burnledger 0.9.0 → 0.10.0

package/src/verify.ts

@@ -88,6 +88,17 @@ const FORMAT_VERSION_V8 = "8.0";
 const PAYLOAD_TYPE_ATTESTATION_V9 = "burnledger.attestation.v9";
 const PAYLOAD_TYPE_VERIFICATION_RECORD_V9 = "burnledger.verification_record.v9";
 const FORMAT_VERSION_V9 = "9.0";
+// v10 signs one top-level field, run_id: the run-level record (ADR-031) the
+// record was issued under, when it was issued under one. The attestation bytes
+// are v9's; its tag still moves, for the reason every version's does.
+//
+// READ-ONLY IN THIS BUILD, mirroring core, for the runbook-invariant-5 reason
+// spelled out for v8 above. Until issuance moves, a run binds its records by
+// the run record's records_root alone (run-record.ts), which is the binding
+// the verifier checks in every case.
+const PAYLOAD_TYPE_ATTESTATION_V10 = "burnledger.attestation.v10";
+const PAYLOAD_TYPE_VERIFICATION_RECORD_V10 = "burnledger.verification_record.v10";
+const FORMAT_VERSION_V10 = "10.0";
 const FORMAT_VERSION_V3 = "3.0";
 
 /**
@@ -115,6 +126,7 @@ export const KNOWN_FORMAT_VERSIONS: readonly string[] = Object.freeze([
   FORMAT_VERSION_V7,
   FORMAT_VERSION_V8,
   FORMAT_VERSION_V9,
+  FORMAT_VERSION_V10,
 ]);
 
 /**
@@ -193,6 +205,20 @@ function signatureCoversAuthorization(version: string): boolean {
   return formatAtLeast(version, FORMAT_VERSION_V9);
 }
 
+/**
+ * Does this format sign the top-level run_id (ADR-031)?
+ *
+ * v10 onward, and optional even there: a record issued outside a run has none.
+ * A record OLDER than v10 that carries one is refused outright rather than
+ * signed without it — the field would ride in the JSON beside a signature that
+ * says nothing about it. Exported for the audit pack verifier, which asks the
+ * same question of a record that carries none: below v10 that says nothing
+ * about its run, from v10 it says the record was issued under no run.
+ */
+export function signatureCoversRunId(version: string): boolean {
+  return formatAtLeast(version, FORMAT_VERSION_V10);
+}
+
 /** The two values a v9 record's per-system authorization may take. */
 const AUTHORIZATION_CERTIFIED = "certified";
 const AUTHORIZATION_NONE = "none";
@@ -447,6 +473,18 @@ export function evaluateKey(pki: PublicKeyInfo, anchor: number | null): string {
   if (pki.revoked) return "UNKNOWN_KEY";
   if (pki.keyStatus === "compromised") {
     if (anchor === null || pki.compromisedFrom === undefined) return KEY_COMPROMISED;
+    // The validity window is tested before the compromise anchor (R03-1). A
+    // signature made outside the stated interval was never authorized, whatever
+    // the key's later disposition, so an anchor outside the window is
+    // KEY_OUTSIDE_VALIDITY even when it predates compromisedFrom. Skipping the
+    // window handed the soft, usable VALID_KEY_COMPROMISED_LATER to a signature
+    // the window alone already refuses.
+    if (pki.notBefore !== undefined && anchor < parseRfc3339(pki.notBefore)) {
+      return KEY_OUTSIDE_VALIDITY;
+    }
+    if (pki.notAfter !== undefined && anchor >= parseRfc3339(pki.notAfter)) {
+      return KEY_OUTSIDE_VALIDITY;
+    }
     return anchor < parseRfc3339(pki.compromisedFrom)
       ? VALID_KEY_COMPROMISED_LATER
       : KEY_COMPROMISED;
@@ -491,19 +529,28 @@ export function certificateAnchor(certificate: Record<string, unknown>): number
 }
 
 /**
- * The anchor, but only once the tree head carrying it has been checked against
- * the key being evaluated.
+ * The anchor, but only once this record has been PROVEN to be in the tree head
+ * carrying it — its inclusion proof verified against that head, not merely the
+ * head's own signature checked.
  *
- * The bypass this closes: for a key declared compromised, evaluateKey answers
- * KEY_COMPROMISED with no anchor and VALID_KEY_COMPROMISED_LATER when the
- * anchor predates the compromise — and the second is a verdict requireUsableKey
- * passes through as the RESULT of verifyCertificate. Since the timestamp is
- * covered by no signature, a holder could backdate it and have a certificate
- * signed with a compromised key reported as verified-with-a-caveat. Deleting
- * `transparency` failed closed; keeping a doctored one did not.
+ * The bypass this closes (R12-1/R14-1): for a key declared compromised,
+ * evaluateKey answers KEY_COMPROMISED with no anchor and
+ * VALID_KEY_COMPROMISED_LATER when the anchor predates the compromise — and the
+ * second is a verdict requireUsableKey passes through as the RESULT of
+ * verifyCertificate. A signed tree head is a public artifact: any genuine older
+ * head the issuer ever published can be stapled onto a record it never
+ * contained, and its signature still verifies. Checking only the head signature
+ * let a holder of a certificate signed after the compromise attach a
+ * pre-compromise head and have the forgery reported as verified-with-a-caveat.
+ * The head's timestamp is an honest anchor for THIS record only once THIS record
+ * is shown to be committed to under it.
  *
- * A head that does not verify yields no anchor, which is the same conservative
- * answer as a certificate carrying no transparency block at all.
+ * checkCertificateInclusion is exactly that proof; it deliberately does NOT test
+ * the key's usability at head time — that is the verdict this anchor exists to
+ * compute, so gating the anchor on it would drop the anchor for an out-of-window
+ * key and soften KEY_OUTSIDE_VALIDITY to VALID_KEY_WINDOW_UNKNOWN. Anything short
+ * of a held inclusion proof yields no anchor, the same conservative answer as a
+ * certificate with no transparency block at all.
  */
 async function verifiedCertificateAnchor(
   crypto: CryptoOps,
@@ -513,21 +560,15 @@ async function verifiedCertificateAnchor(
   const anchor = certificateAnchor(certificate);
   if (anchor === null) return null;
 
-  const transparency = certificate.transparency as Record<string, unknown>;
-  const sth = transparency.signed_tree_head as Record<string, unknown>;
-  // Only a refusal of the head's own fields means "no anchor". A bare catch
-  // here gave a defect in this library — or a crypto provider that threw — the
-  // same quiet answer as a malformed document.
-  let headPayload: Uint8Array;
-  let headSig: Uint8Array;
+  // Only a refusal of the proof means "no anchor". A defect in this library, or
+  // a crypto provider that threw, must not get the same quiet answer as a
+  // document whose inclusion proof does not verify.
   try {
-    headPayload = buildTreeHeadPayload(sth);
-    headSig = decodeFixed(sth.signature, "signed_tree_head.signature", 64);
+    await checkCertificateInclusion(crypto, certificate, pki);
   } catch (e) {
     if (e instanceof VerificationError) return null;
     throw e;
   }
-  if (!(await crypto.ed25519Verify(pki.keyBytes, headPayload, headSig))) return null;
   return anchor;
 }
 
@@ -949,15 +990,49 @@ export async function verifyTransparency(
     return "NOT_AVAILABLE" as TransparencyResult;
   }
   const transparency = objectAt(certificate, "transparency", "transparency");
-
-  const sth = objectAt(transparency, "signed_tree_head", "transparency.signed_tree_head");
+  // Read before the key lookup, as it always was: a proof with no head is
+  // reported as that, not as a key the reader does not hold.
+  objectAt(transparency, "signed_tree_head", "transparency.signed_tree_head");
   const issuer = objectAt(certificate, "issuer", "issuer");
   const keyId = stringAt(issuer, "key_id", "issuer.key_id");
 
   const pki = publicKeys.get(keyId);
   if (pki === undefined) throw new VerificationError(`unknown issuer key: ${keyId}`);
-  // The tree head carries its own timestamp, so this path always has an anchor.
-  requireUsableKey(pki, certificateAnchor(certificate), keyId);
+  await verifyTransparencyHead(crypto, transparency, pki, keyId);
+
+  // The leaf is NOT the certificate. It is the canonical log_leaf.v3 payload
+  // over entry_type, certificate_id, certificate_hash and appended_at, where
+  // certificate_hash is SHA-256 of the issuance-time certificate JSON
+  // (ADR-016 §4). v2 hashed the certificate directly, so an issuance and a
+  // revocation of the same certificate produced identical leaves and the tree
+  // committed to neither the entry type nor when it happened.
+  const issuanceData = issuanceBytes(certificate);
+  const leafPayload = buildLogLeafPayload(
+    transparency.entry_type,
+    stringAt(certificate, "certificate_id", "certificate_id"),
+    await crypto.sha256(issuanceData),
+    transparency.appended_at,
+  );
+  await verifyTransparencyInclusion(crypto, transparency, await hashLeaf(crypto, leafPayload));
+
+  return "INCLUDED" as TransparencyResult;
+}
+
+/**
+ * Verify the head signature and the Merkle inclusion of a certificate's proof —
+ * everything about whether this record is committed to under its head, but NOT
+ * whether the key was usable when it signed. That last question is the caller's;
+ * certificateAnchor needs membership, not authority, and folding authority in
+ * here made the anchor for an out-of-window key collapse to "no anchor" and the
+ * verdict soften. Throws VerificationError on any inclusion failure.
+ */
+async function checkCertificateInclusion(
+  crypto: CryptoOps,
+  certificate: Cert,
+  pki: PublicKeyInfo,
+): Promise<void> {
+  const transparency = objectAt(certificate, "transparency", "transparency");
+  const sth = objectAt(transparency, "signed_tree_head", "transparency.signed_tree_head");
 
   // 1. Tree head signature
   const headPayload = buildTreeHeadPayload(sth);
@@ -1028,8 +1103,115 @@ export async function verifyTransparency(
   if (!(await verifyInclusion(crypto, leaf, index, treeSize, proofHashes, root))) {
     throw new VerificationError("merkle inclusion proof is invalid");
   }
+}
 
-  return "INCLUDED" as TransparencyResult;
+/** The first half of a transparency check, shared with the run record's
+ * (run-record.ts): the key's authority at the head's own timestamp, then the
+ * head's signature. The tree head carries its own timestamp, so this path
+ * always has an anchor; a timestamp that does not read leaves none, which is
+ * the same conservative answer as no proof at all. Throws the VerificationError
+ * the caller reports. Exported as an internal seam, not from index.ts. */
+export async function verifyTransparencyHead(
+  crypto: CryptoOps,
+  transparency: Doc,
+  pki: PublicKeyInfo,
+  keyId: string,
+): Promise<void> {
+  const sth = objectAt(transparency, "signed_tree_head", "transparency.signed_tree_head");
+  let anchor: number | null = null;
+  if (typeof sth.timestamp === "string") {
+    try {
+      anchor = parseRfc3339(sth.timestamp);
+    } catch {
+      anchor = null;
+    }
+  }
+  requireUsableKey(pki, anchor, keyId);
+
+  const headPayload = buildTreeHeadPayload(sth);
+  const headSig = decodeFixed(sth.signature, "signed_tree_head.signature", 64);
+  if (!(await crypto.ed25519Verify(pki.keyBytes, headPayload, headSig))) {
+    throw new VerificationError("tree head signature is invalid");
+  }
+}
+
+/** The second half: an already-hashed leaf against the signed head, after the
+ * unsigned duplicates beside the proof are held to the signed copies. Throws
+ * the VerificationError the caller reports. Exported as an internal seam. */
+export async function verifyTransparencyInclusion(
+  crypto: CryptoOps,
+  transparency: Doc,
+  leaf: Uint8Array,
+): Promise<void> {
+  const sth = objectAt(transparency, "signed_tree_head", "transparency.signed_tree_head");
+  const proofHashes = arrayAt(transparency, "inclusion_proof", "transparency.inclusion_proof").map(
+    (h, i) => decodeFixed(h, `transparency.inclusion_proof[${i}]`, 32),
+  );
+  const root = decodeFixed(sth.root_hash, "signed_tree_head.root_hash", 32);
+  // `?? 0` is not a convenience: encoding/json leaves 0 in Go's uint64 fields
+  // for an explicit null and for an absent key rather than failing, so refusing
+  // either would reject documents the reference accepts — the same class of
+  // divergence as #452. An offline verifier is only useful while it agrees.
+  const index = requireUint(transparency.entry_index ?? 0, "entry_index");
+  const treeSize = requireUint(sth.tree_size ?? 0, "signed_tree_head.tree_size");
+
+  // transparency.tree_size duplicates the signed one but carries no signature:
+  // BuildTreeHeadPayload covers only the copy inside signed_tree_head. Go used
+  // to verify against the unsigned copy while this SDK used the signed one, so
+  // the same document got two verdicts (#456). Both now require the two to agree
+  // and then verify against the signed copy — the server always writes them
+  // equal, so this rejects only edited documents.
+  const unsignedSize = requireUint(
+    transparency.tree_size ?? 0,
+    "transparency.tree_size",
+  );
+  if (unsignedSize !== treeSize) {
+    throw new VerificationError(
+      `transparency.tree_size (${unsignedSize}) does not match the signed tree head ` +
+        `(${treeSize}); it is not covered by any signature`,
+    );
+  }
+
+  // Same rule for the log id (Q31). transparency.log_id sits beside log_url and
+  // is the field a reader looks at to answer "which log is this?", and nothing
+  // signs it — so a holder could relabel a genuine proof as belonging to a
+  // different log while every signature still checked out. A head predating log
+  // ids has neither side set and passes.
+  const signedLogId = (sth.log_id as string | undefined) ?? "";
+  const unsignedLogId = (transparency.log_id as string | undefined) ?? "";
+  if (unsignedLogId !== signedLogId) {
+    throw new VerificationError(
+      `transparency.log_id (${JSON.stringify(unsignedLogId)}) does not match the signed ` +
+        `tree head (${JSON.stringify(signedLogId)}); it is not covered by any signature`,
+    );
+  }
+
+  if (!(await verifyInclusion(crypto, leaf, index, treeSize, proofHashes, root))) {
+    throw new VerificationError("merkle inclusion proof is invalid");
+  }
+}
+
+/** The refusals of verifyTransparencyHead and verifyTransparencyInclusion under
+ * core.TransparencyResult's names, for the verifiers that report a pack or a
+ * run record beside Go's verdicts rather than by throwing. The key verdicts
+ * collapse to KEY_UNUSABLE as they do in Go, whose transparency result does not
+ * say which key problem. Anything unmatched is a field this SDK could not read:
+ * UNREADABLE_DOCUMENT, never a tampering claim. */
+const TRANSPARENCY_VERDICTS: ReadonlyArray<[prefix: string, verdict: string]> = [
+  ["issuer key is compromised:", "KEY_UNUSABLE"],
+  ["issuer key was not valid when it signed:", "KEY_UNUSABLE"],
+  ["issuer key has an unusable status", "KEY_UNUSABLE"],
+  ["tree head signature is invalid", "INVALID_TREE_HEAD_SIGNATURE"],
+  ["transparency.tree_size (", "INVALID_INCLUSION_PROOF"],
+  ["transparency.log_id (", "INVALID_INCLUSION_PROOF"],
+  ["merkle inclusion proof is invalid", "INVALID_INCLUSION_PROOF"],
+];
+
+export function transparencyVerdictName(e: VerificationError): string {
+  for (const [prefix, verdict] of TRANSPARENCY_VERDICTS) {
+    if (e.message.startsWith(prefix)) return verdict;
+  }
+  return "UNREADABLE_DOCUMENT";
 }
 
 // ---------------------------------------------------------------------------
@@ -1139,6 +1321,43 @@ function arrayAt(parent: Doc, key: string, path: string): unknown[] {
   return Array.from(value);
 }
 
+/** A UUID in the forms Go's uuid.Parse accepts: 8-4-4-4-12 hex, the same in
+ * braces or behind "urn:uuid:", or 32 bare hex digits. */
+const UUID_RE = /^(?:urn:uuid:)?\{?([0-9a-fA-F]{8})-([0-9a-fA-F]{4})-([0-9a-fA-F]{4})-([0-9a-fA-F]{4})-([0-9a-fA-F]{12})\}?$/;
+const UUID_BARE_RE = /^[0-9a-fA-F]{32}$/;
+
+/** The 16 bytes of a UUID, in any form Go's uuid.Parse reads. Throws TypeError
+ * for anything else: a UUID reaches a signed payload only as its canonical
+ * string, and an unreadable one must not be signed as whatever text arrived. */
+export function parseUuid(text: string): Uint8Array {
+  if (typeof text !== "string") throw new TypeError(`uuid is not a string: ${typeof text}`);
+  const m = UUID_RE.exec(text);
+  const hex = m !== null ? m.slice(1).join("") : UUID_BARE_RE.test(text) ? text : null;
+  if (hex === null) throw new TypeError(`not a UUID: ${JSON.stringify(text)}`);
+  return hexToBytes(hex);
+}
+
+/** The canonical lowercase 8-4-4-4-12 form, as Go's uuid.UUID.String prints:
+ * the only form a UUID takes inside a signed payload. */
+export function formatUuid(bytes: Uint8Array): string {
+  if (bytes.length !== 16) throw new TypeError(`uuid is ${bytes.length} bytes, expected 16`);
+  const h = bytesToHex(bytes);
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+
+/** Read a UUID field as Go's uuid.UUID unmarshals it, refusing with a
+ * VerificationError what encoding/json would refuse to parse. */
+function uuidAt(parent: Doc, key: string, path: string): string {
+  const v = parent[key];
+  if (typeof v !== "string") throw new VerificationError(`${path} is not a string`);
+  try {
+    return formatUuid(parseUuid(v));
+  } catch (e) {
+    if (e instanceof TypeError) throw new VerificationError(`${path} is not a UUID: ${JSON.stringify(v)}`);
+    throw e;
+  }
+}
+
 const HEX_TEXT_RE = /^(?:[0-9a-fA-F]{2})*$/;
 const BASE64_TEXT_RE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 
@@ -1155,7 +1374,9 @@ const BASE64_TEXT_RE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/
  * leniently instead wrapped 300 to 44 inside a Uint8Array, produced bytes no
  * signature covers and blamed the signature — or threw from inside atob.
  */
-function decodeFixed(value: unknown, path: string, length: number): Uint8Array {
+/** Exported for run-record.ts, whose digests and roots arrive in the same
+ * shapes; not published from index.ts. */
+export function decodeFixed(value: unknown, path: string, length: number): Uint8Array {
   if (value === undefined || value === null) throw new VerificationError(`${path} is missing`);
   let raw: Uint8Array;
   if (Array.isArray(value)) {
@@ -1430,6 +1651,7 @@ function requireMeasured(
 /** Domain separator for the record itself, by certificate format version. */
 function certificatePayloadType(version: string): string {
   checkFormatVersion(version);
+  if (version === FORMAT_VERSION_V10) return PAYLOAD_TYPE_VERIFICATION_RECORD_V10;
   if (version === FORMAT_VERSION_V9) return PAYLOAD_TYPE_VERIFICATION_RECORD_V9;
   if (version === FORMAT_VERSION_V8) return PAYLOAD_TYPE_VERIFICATION_RECORD_V8;
   if (version === FORMAT_VERSION_V7) return PAYLOAD_TYPE_VERIFICATION_RECORD_V7;
@@ -1450,6 +1672,7 @@ function attestationPayloadType(version: string): string {
   // Equality here, deliberately: each format has its OWN separator, so this is
   // a lookup rather than a "this version onward" question. v3 and v4 share one
   // because their attestation bytes are identical.
+  if (version === FORMAT_VERSION_V10) return PAYLOAD_TYPE_ATTESTATION_V10;
   if (version === FORMAT_VERSION_V9) return PAYLOAD_TYPE_ATTESTATION_V9;
   if (version === FORMAT_VERSION_V8) return PAYLOAD_TYPE_ATTESTATION_V8;
   if (version === FORMAT_VERSION_V7) return PAYLOAD_TYPE_ATTESTATION_V7;
@@ -1606,17 +1829,33 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
       version: stringAt(scope, "version", "scope.version"),
     };
   }
+  // Signed from v10 when present. On an older format the field is refused
+  // rather than dropped from the bytes: core.BuildCertificatePayload returns an
+  // error there and the verdict is INVALID_CERTIFICATE_SIGNATURE, so the same
+  // words open this message for the audit pack verifier to read it back as
+  // that verdict. A JSON null is an absent run, as Go's *uuid.UUID reads it.
+  if (cert.run_id != null) {
+    if (!signatureCoversRunId(version)) {
+      throw new VerificationError(
+        `certificate signature is invalid: the record carries run_id, which format ${version} does not ` +
+          `sign (run_id is signed from ${FORMAT_VERSION_V10}), so no signature covers the document as presented`,
+      );
+    }
+    payload.run_id = uuidAt(cert, "run_id", "run_id");
+  }
   return canonicalJson(payload);
 }
 
-/** Port of Go's BuildLogLeafPayload (ADR-016 §4). */
-function buildLogLeafPayload(
+/** Port of Go's BuildLogLeafPayload (ADR-016 §4). A RUN_RECORD leaf names its
+ * run id where the other two name a certificate id, under the same key
+ * (ADR-031). Exported for run-record.ts; not published from index.ts. */
+export function buildLogLeafPayload(
   entryType: unknown,
   certificateId: string,
   certificateHash: Uint8Array,
   appendedAt: unknown,
 ): Uint8Array {
-  if (entryType !== "CERTIFICATE" && entryType !== "REVOCATION") {
+  if (entryType !== "CERTIFICATE" && entryType !== "REVOCATION" && entryType !== "RUN_RECORD") {
     throw new VerificationError(`invalid log entry_type: ${String(entryType)}`);
   }
   const payload = {
@@ -1687,10 +1926,21 @@ export function buildTreeHeadPayload(head: Record<string, unknown>): Uint8Array
 // Merkle tree (RFC 6962) — ports of core/merkle.go
 // ---------------------------------------------------------------------------
 
-async function hashLeaf(crypto: CryptoOps, data: Uint8Array): Promise<Uint8Array> {
+/** Exported for run-record.ts, whose roots are trees over these leaves. */
+export async function hashLeaf(crypto: CryptoOps, data: Uint8Array): Promise<Uint8Array> {
   return crypto.sha256(concatBytes(new Uint8Array([0x00]), data));
 }
 
+/** The RFC 6962 root over already-hashed leaves, in the order given. Port of
+ * Go's treeHash, which like it takes at least one leaf: the empty tree has no
+ * root here, and a caller with nothing to commit to says so itself. */
+export async function merkleRoot(crypto: CryptoOps, leaves: Uint8Array[]): Promise<Uint8Array> {
+  if (leaves.length === 0) throw new RangeError("merkleRoot: no leaves");
+  if (leaves.length === 1) return leaves[0]!;
+  const k = splitPoint(leaves.length);
+  return hashNode(crypto, await merkleRoot(crypto, leaves.slice(0, k)), await merkleRoot(crypto, leaves.slice(k)));
+}
+
 async function hashNode(crypto: CryptoOps, left: Uint8Array, right: Uint8Array): Promise<Uint8Array> {
   const prefix = new Uint8Array([0x01]);
   return crypto.sha256(concatBytes(prefix, concatBytes(left, right)));
@@ -1763,7 +2013,12 @@ async function chainInclusion(
 }
 
 function isPow2(n: number): boolean {
-  return n > 0 && (n & (n - 1)) === 0;
+  // Arithmetic, not `n & (n - 1)` (R12-2): JS bitwise operators coerce to 32-bit
+  // signed integers, so for a tree size >= 2^31 the bit test gives the wrong
+  // answer. This holds for every safe integer.
+  if (n < 1) return false;
+  while (n % 2 === 0) n /= 2;
+  return n === 1;
 }
 
 /** Verify a Merkle consistency proof (RFC 6962 Section 2.1.4).
@@ -1800,9 +2055,14 @@ export async function verifyConsistency(
   let fn = oldSize - 1;
   let sn = newSize - 1;
 
-  while ((fn & 1) === 1) {
-    fn >>= 1;
-    sn >>= 1;
+  // Arithmetic throughout (R12-2). `& 1` and `>>= 1` coerce to 32-bit signed
+  // integers, so for tree sizes >= 2^31 fn and sn are truncated and this
+  // consistency check silently returned the wrong answer (CONFIRMED where Go
+  // says INCONSISTENT). `% 2` and Math.floor(/2) are exact for every safe
+  // integer, which requireUint already bounds the inputs to.
+  while (fn % 2 === 1) {
+    fn = Math.floor(fn / 2);
+    sn = Math.floor(sn / 2);
   }
 
   // Drive the walk from the tree, not from the proof's length. Looping on
@@ -1817,19 +2077,19 @@ export async function verifyConsistency(
     const c = proof[pIdx]!;
     pIdx++;
 
-    if ((fn & 1) === 1 || fn === sn) {
+    if (fn % 2 === 1 || fn === sn) {
       fr = await hashNode(crypto, c, fr);
       sr = await hashNode(crypto, c, sr);
-      while (fn !== 0 && (fn & 1) === 0) {
-        fn >>= 1;
-        sn >>= 1;
+      while (fn !== 0 && fn % 2 === 0) {
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
       }
     } else {
       sr = await hashNode(crypto, sr, c);
     }
 
-    fn >>= 1;
-    sn >>= 1;
+    fn = Math.floor(fn / 2);
+    sn = Math.floor(sn / 2);
   }
 
   return pIdx === proof.length && bytesEqual(fr, oldRoot) && bytesEqual(sr, newRoot);

package/src/webhooks.ts

@@ -16,14 +16,32 @@
 
 import { createHmac, timingSafeEqual } from "node:crypto";
 
+/** Strictly hex-decode `value`, or undefined if it is not even-length pure hex.
+ * Buffer.from(_, "hex") silently truncates at the first non-hex character, which
+ * would decode only the first signature of a rotation header — so the input is
+ * validated as pure hex first. */
+function decodeHexStrict(value: string): Buffer | undefined {
+  if (value.length === 0 || value.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(value)) {
+    return undefined;
+  }
+  return Buffer.from(value, "hex");
+}
+
 /**
  * Verify that a webhook payload was signed by the expected secret.
  *
+ * During a secret rotation the server sends both signatures in one header as
+ * `<old>,<new>` for a 24 h window, so whichever secret a receiver holds matches
+ * one of them without dropping deliveries. The header is split on the comma,
+ * each part is trimmed and strictly hex-decoded, and it verifies if any part
+ * matches under `secret`. A single signature (no comma) is the ordinary case and
+ * one iteration of the same loop.
+ *
  * @param secret  The webhook secret (raw UTF-8, as returned by the API)
  * @param timestamp The RFC3339 timestamp from the X-BurnLedger-Timestamp header
  * @param body    The raw request body bytes
- * @param signature The hex-encoded HMAC-SHA256 signature from the X-BurnLedger-Signature header
- * @returns true if the signature is valid
+ * @param signature The hex-encoded HMAC-SHA256 signature(s) from the X-BurnLedger-Signature header
+ * @returns true if any signature in the header is valid
  */
 export function verifyWebhookSignature(
   secret: string,
@@ -44,16 +62,15 @@ export function verifyWebhookSignature(
     .update(bodyBytes)
     .digest();
 
-  let received: Buffer;
-  try {
-    received = Buffer.from(signature, "hex");
-  } catch {
-    return false;
+  // Every candidate is compared in constant time; the loop does not return early
+  // on a match so the work does not reveal which position matched.
+  let matched = false;
+  for (const part of signature.split(",")) {
+    const received = decodeHexStrict(part.trim());
+    if (received === undefined || received.length !== expected.length) continue;
+    if (timingSafeEqual(expected, received)) matched = true;
   }
-
-  if (received.length !== expected.length) return false;
-
-  return timingSafeEqual(expected, received);
+  return matched;
 }
 
 /**