| 1 |
"use strict"; |
| 2 |
Object.defineProperty(exports, "__esModule", { value: true }); |
| 3 |
exports.LogCheckpoint = void 0; |
| 4 |
exports.verifyCheckpoint = verifyCheckpoint; |
| 5 |
/* |
| 6 |
Copyright 2025 The Sigstore Authors. |
| 7 |
|
| 8 |
Licensed under the Apache License, Version 2.0 (the "License"); |
| 9 |
you may not use this file except in compliance with the License. |
| 10 |
You may obtain a copy of the License at |
| 11 |
|
| 12 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 13 |
|
| 14 |
Unless required by applicable law or agreed to in writing, software |
| 15 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 16 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 17 |
See the License for the specific language governing permissions and |
| 18 |
limitations under the License. |
| 19 |
*/ |
| 20 |
const core_1 = require("@sigstore/core"); |
| 21 |
const error_1 = require("../error"); |
| 22 |
// Separator between the note and the signatures in a checkpoint |
| 23 |
const CHECKPOINT_SEPARATOR = '\n\n'; |
| 24 |
// Checkpoint signatures are of the following form: |
| 25 |
// "– <identity> <key_hint+signature_bytes>\n" |
| 26 |
// where: |
| 27 |
// - the prefix is an emdash (U+2014). |
| 28 |
// - <identity> gives a human-readable representation of the signing ID. |
| 29 |
// - <key_hint+signature_bytes> is the first 4 bytes of the SHA256 hash of the |
| 30 |
// associated public key followed by the signature bytes. |
| 31 |
const SIGNATURE_REGEX = /\u2014 (\S+) (\S+)\n/g; |
| 32 |
// Verifies the checkpoint value in the given tlog entry. There are two steps |
| 33 |
// to the verification: |
| 34 |
// 1. Verify that all signatures in the checkpoint can be verified against a |
| 35 |
// trusted public key |
| 36 |
// 2. Verify that the root hash in the checkpoint matches the root hash in the |
| 37 |
// inclusion proof |
| 38 |
// See: https://github.com/transparency-dev/formats/blob/main/log/README.md |
| 39 |
function verifyCheckpoint(entry, tlogs) { |
| 40 |
const inclusionProof = entry.inclusionProof; |
| 41 |
const signedNote = SignedNote.fromString(inclusionProof.checkpoint.envelope); |
| 42 |
const checkpoint = LogCheckpoint.fromString(signedNote.note); |
| 43 |
// Verify that the signatures in the checkpoint are all valid |
| 44 |
if (!verifySignedNote(signedNote, tlogs)) { |
| 45 |
throw new error_1.VerificationError({ |
| 46 |
code: 'TLOG_INCLUSION_PROOF_ERROR', |
| 47 |
message: 'invalid checkpoint signature', |
| 48 |
}); |
| 49 |
} |
| 50 |
return checkpoint; |
| 51 |
} |
| 52 |
// Verifies the signatures in the SignedNote. For each signature, the |
| 53 |
// corresponding transparency log is looked up by the key hint and the |
| 54 |
// signature is verified against the public key in the transparency log. |
| 55 |
// Throws an error if any of the signatures are invalid. |
| 56 |
function verifySignedNote(signedNote, tlogs) { |
| 57 |
const data = Buffer.from(signedNote.note, 'utf-8'); |
| 58 |
return signedNote.signatures.some((signature) => { |
| 59 |
// Find the transparency log instance with the matching key hint |
| 60 |
const tlog = tlogs.find((tlog) => core_1.crypto.bufferEqual(tlog.logID.subarray(0, 4), signature.keyHint) && |
| 61 |
tlog.baseURL.match(signature.name) // Match the name to the base URL of the tlog |
| 62 |
); |
| 63 |
if (!tlog) { |
| 64 |
return false; |
| 65 |
} |
| 66 |
return core_1.crypto.verify(data, tlog.publicKey, signature.signature); |
| 67 |
}); |
| 68 |
} |
| 69 |
// SignedNote represents a signed note from a transparency log checkpoint. Consists |
| 70 |
// of a body (or note) and one more signatures calculated over the body. See |
| 71 |
// https://github.com/transparency-dev/formats/blob/main/log/README.md#signed-envelope |
| 72 |
class SignedNote { |
| 73 |
note; |
| 74 |
signatures; |
| 75 |
constructor(note, signatures) { |
| 76 |
this.note = note; |
| 77 |
this.signatures = signatures; |
| 78 |
} |
| 79 |
// Deserialize a SignedNote from a string |
| 80 |
static fromString(envelope) { |
| 81 |
if (!envelope.includes(CHECKPOINT_SEPARATOR)) { |
| 82 |
throw new error_1.VerificationError({ |
| 83 |
code: 'TLOG_INCLUSION_PROOF_ERROR', |
| 84 |
message: 'missing checkpoint separator', |
| 85 |
}); |
| 86 |
} |
| 87 |
// Split the note into the header and the data portions at the separator |
| 88 |
const split = envelope.indexOf(CHECKPOINT_SEPARATOR); |
| 89 |
const header = envelope.slice(0, split + 1); |
| 90 |
const data = envelope.slice(split + CHECKPOINT_SEPARATOR.length); |
| 91 |
// Find all the signature lines in the data portion |
| 92 |
const matches = data.matchAll(SIGNATURE_REGEX); |
| 93 |
// Parse each of the matched signature lines into the name and signature. |
| 94 |
// The first four bytes of the signature are the key hint (should match the |
| 95 |
// first four bytes of the log ID), and the rest is the signature itself. |
| 96 |
const signatures = Array.from(matches, (match) => { |
| 97 |
const [, name, signature] = match; |
| 98 |
const sigBytes = Buffer.from(signature, 'base64'); |
| 99 |
if (sigBytes.length < 5) { |
| 100 |
throw new error_1.VerificationError({ |
| 101 |
code: 'TLOG_INCLUSION_PROOF_ERROR', |
| 102 |
message: 'malformed checkpoint signature', |
| 103 |
}); |
| 104 |
} |
| 105 |
return { |
| 106 |
name, |
| 107 |
keyHint: sigBytes.subarray(0, 4), |
| 108 |
signature: sigBytes.subarray(4), |
| 109 |
}; |
| 110 |
}); |
| 111 |
if (signatures.length === 0) { |
| 112 |
throw new error_1.VerificationError({ |
| 113 |
code: 'TLOG_INCLUSION_PROOF_ERROR', |
| 114 |
message: 'no signatures found in checkpoint', |
| 115 |
}); |
| 116 |
} |
| 117 |
return new SignedNote(header, signatures); |
| 118 |
} |
| 119 |
} |
| 120 |
// LogCheckpoint represents a transparency log checkpoint. Consists of the |
| 121 |
// following: |
| 122 |
// - origin: the name of the transparency log |
| 123 |
// - logSize: the size of the log at the time of the checkpoint |
| 124 |
// - logHash: the root hash of the log at the time of the checkpoint |
| 125 |
// - rest: the rest of the checkpoint body, which is a list of log entries |
| 126 |
// See: |
| 127 |
// https://github.com/transparency-dev/formats/blob/main/log/README.md#checkpoint-body |
| 128 |
class LogCheckpoint { |
| 129 |
origin; |
| 130 |
logSize; |
| 131 |
logHash; |
| 132 |
rest; |
| 133 |
constructor(origin, logSize, logHash, rest) { |
| 134 |
this.origin = origin; |
| 135 |
this.logSize = logSize; |
| 136 |
this.logHash = logHash; |
| 137 |
this.rest = rest; |
| 138 |
} |
| 139 |
static fromString(note) { |
| 140 |
const lines = note.trimEnd().split('\n'); |
| 141 |
if (lines.length < 3) { |
| 142 |
throw new error_1.VerificationError({ |
| 143 |
code: 'TLOG_INCLUSION_PROOF_ERROR', |
| 144 |
message: 'too few lines in checkpoint header', |
| 145 |
}); |
| 146 |
} |
| 147 |
const origin = lines[0]; |
| 148 |
const logSize = BigInt(lines[1]); |
| 149 |
const rootHash = Buffer.from(lines[2], 'base64'); |
| 150 |
const rest = lines.slice(3); |
| 151 |
return new LogCheckpoint(origin, logSize, rootHash, rest); |
| 152 |
} |
| 153 |
} |
| 154 |
exports.LogCheckpoint = LogCheckpoint; |