Debian Codegraph @

node_modules/@sigstore/verify/dist/tlog/checkpoint.js

raw
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;