burnledger 0.9.0 → 0.9.1

package/src/verify.ts

@@ -447,6 +447,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 +503,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 +534,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;
 }
 
@@ -948,9 +963,6 @@ export async function verifyTransparency(
   if (certificate.transparency == null) {
     return "NOT_AVAILABLE" as TransparencyResult;
   }
-  const transparency = objectAt(certificate, "transparency", "transparency");
-
-  const sth = objectAt(transparency, "signed_tree_head", "transparency.signed_tree_head");
   const issuer = objectAt(certificate, "issuer", "issuer");
   const keyId = stringAt(issuer, "key_id", "issuer.key_id");
 
@@ -959,6 +971,26 @@ export async function verifyTransparency(
   // The tree head carries its own timestamp, so this path always has an anchor.
   requireUsableKey(pki, certificateAnchor(certificate), keyId);
 
+  await checkCertificateInclusion(crypto, certificate, pki);
+  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);
   const headSig = decodeFixed(sth.signature, "signed_tree_head.signature", 64);
@@ -1028,8 +1060,6 @@ 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;
 }
 
 // ---------------------------------------------------------------------------
@@ -1763,7 +1793,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 +1835,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 +1857,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;
 }
 
 /**