burnledger 0.2.2 → 0.3.0

package/dist/esm/verify.js

@@ -9,7 +9,9 @@
  *   - The payload builders normalize both formats to lowercase hex strings.
  *   - Timestamps in payloads use second-precision UTC: "YYYY-MM-DDTHH:MM:SSZ".
  *   - RFC 8785 canonical JSON: sorted keys recursively, no whitespace.
- *   - Transparency leaf = SHA-256(0x00 || issuanceBytes(cert)), NOT the
+ *   - Transparency leaf = SHA-256(0x00 || logLeafPayload), where the payload
+ *     commits to entry_type, certificate_id, SHA-256(issuanceBytes(cert)) and
+ *     appended_at (ADR-016 §4). NOT the
  *     certificate signing payload. issuanceBytes reconstructs json.Marshal
  *     output at issuance time (transparency_status=PENDING, no transparency).
  */
@@ -20,10 +22,13 @@ import { VerificationError } from "./errors.js";
 const HEX_CHARS = "0123456789abcdef";
 // Signing-format v2 domain-separation tags (CR-H01). Must match the
 // source-of-truth const block in Go's core/payload.go byte-for-byte.
-const PAYLOAD_TYPE_ATTESTATION = "burnledger.attestation.v2";
-const PAYLOAD_TYPE_VERIFICATION = "burnledger.verification.v2";
-const PAYLOAD_TYPE_CERTIFICATE = "burnledger.certificate.v2";
-const PAYLOAD_TYPE_TREE_HEAD = "burnledger.sth.v2";
+const PAYLOAD_TYPE_ATTESTATION = "burnledger.attestation.v3";
+const PAYLOAD_TYPE_CERTIFICATE = "burnledger.certificate.v3";
+const PAYLOAD_TYPE_TREE_HEAD = "burnledger.sth.v3";
+const PAYLOAD_TYPE_LOG_LEAF = "burnledger.log_leaf.v3";
+// There is deliberately no verification payload type: v3 produces those facts
+// in the same enclave call that signs the certificate (ADR-016 §2).
+const PAYLOAD_TYPE_CERTIFICATE_STATUS = "burnledger.certificate_status.v3";
 export function hexToBytes(hex) {
     const len = hex.length >>> 1;
     const out = new Uint8Array(len);
@@ -101,41 +106,75 @@ export async function verifyCertificate(crypto, certificate, publicKeys) {
         throw new VerificationError(`unknown issuer key: ${keyId}`);
     if (pki.revoked)
         throw new VerificationError(`issuer key is revoked: ${keyId}`);
-    // 1. Attestation signature
+    // 1. Certificate signature FIRST — nothing below may trust a field until the
+    // bytes carrying it are covered by a verified signature.
+    const certPayload = buildCertificatePayload(certificate);
+    const certSig = decodeSignature(certificate.certificate_signature);
+    if (!(await crypto.ed25519Verify(pki.keyBytes, certPayload, certSig))) {
+        throw new VerificationError("certificate signature is invalid");
+    }
+    // 2. Attestation signature, rebuilt from the merged list. There is no
+    // verification signature: those facts are produced in the same enclave call
+    // that signs the certificate, so certificate_signature already covers them
+    // (ADR-016 §2).
     const att = certificate.attestation;
-    const attPayload = buildAttestationPayload(certificate.subject, att);
+    const attPayload = buildAttestationPayload(certificate.subject, {
+        proof_mode: att.proof_mode,
+        attested_at: att.attested_at,
+        systems: attestationSystems(certificate),
+    });
     const attSig = decodeSignature(att.attestation_signature);
     if (!(await crypto.ed25519Verify(pki.keyBytes, attPayload, attSig))) {
         throw new VerificationError("attestation signature is invalid");
     }
-    // 2. Verification signature
-    const ver = certificate.verification;
-    const verPayload = buildVerificationPayload(certificate.attestation_id, ver);
-    const verSig = decodeSignature(ver.verification_signature);
-    if (!(await crypto.ed25519Verify(pki.keyBytes, verPayload, verSig))) {
-        throw new VerificationError("verification signature is invalid");
+    // 3. Structural rules on the system set.
+    //
+    // v2 carried two lists joined on the human-editable system_name, so "attested
+    // but not verified" was a representable state that had to be caught by a
+    // check — and for a long time was not (#451). v3 carries one list keyed by
+    // system_id, which makes that state unexpressible. What remains is
+    // structural, and mirrors core/verify.go step 4.
+    const systems = certificate.systems ?? [];
+    if (systems.length === 0) {
+        throw new VerificationError("certificate attests no systems, so it asserts nothing");
     }
-    // 3. Certificate signature
-    const certPayload = buildCertificatePayload(certificate);
-    const certSig = decodeSignature(certificate.certificate_signature);
-    if (!(await crypto.ed25519Verify(pki.keyBytes, certPayload, certSig))) {
-        throw new VerificationError("certificate signature is invalid");
-    }
-    // 4. Now that every signature is verified (so these fields are trustworthy),
-    // reject certificates that are validly signed but are NOT proof of deletion.
-    // Mirrors core/verify.go steps 3 and 6 — without these the SDK would accept
-    // a revoked certificate, or one attesting data that is still present, as VALID.
-    if (certificate.status === "REVOKED") {
-        throw new VerificationError("certificate has been revoked");
+    const seen = new Set();
+    let anyAttested = false;
+    for (const s of systems) {
+        const systemId = s.system_id;
+        if (!systemId || systemId === NIL_UUID) {
+            throw new VerificationError("malformed systems: a system carries no system_id");
+        }
+        if (seen.has(systemId)) {
+            // Duplicate ids would let one verification stand in for several systems,
+            // which is the v2 hole in a new costume.
+            throw new VerificationError(`malformed systems: duplicate system_id ${systemId}`);
+        }
+        seen.add(systemId);
+        const attestedAt = parseRfc3339(s.attested_at);
+        const verifiedAt = parseRfc3339(s.verified_at);
+        if (verifiedAt < attestedAt) {
+            throw new VerificationError(`malformed systems: system ${systemId} was verified before it was attested`);
+        }
+        if (s.attested_count > 0)
+            anyAttested = true;
     }
-    for (const s of ver.systems ?? []) {
-        const recordCount = s.record_count;
-        if (recordCount !== 0) {
-            throw new VerificationError(`data still present: system "${s.system_name}" reports ${recordCount} record(s)`);
+    // 4. Nothing may remain anywhere.
+    for (const s of systems) {
+        const remaining = s.verified_count;
+        if (remaining !== 0) {
+            throw new VerificationError(`data still present: system "${s.system_name}" reports ${remaining} record(s)`);
         }
     }
+    // 5. At least one system must have held records at attest time — across the
+    // set, not per system. Every system reporting zero means the certificate
+    // documents the deletion of nothing.
+    if (!anyAttested) {
+        throw new VerificationError("incomplete verification: no system held any records at attestation time");
+    }
     return "VALID";
 }
+const NIL_UUID = "00000000-0000-0000-0000-000000000000";
 /** Verify the transparency proof embedded in a certificate. */
 export async function verifyTransparency(crypto, certificate, publicKeys) {
     const transparency = certificate.transparency;
@@ -156,14 +195,36 @@ export async function verifyTransparency(crypto, certificate, publicKeys) {
     if (!(await crypto.ed25519Verify(pki.keyBytes, headPayload, headSig))) {
         throw new VerificationError("tree head signature is invalid");
     }
-    // 2. Merkle inclusion proof — leaf is hash of issuance-time certificate JSON,
-    // NOT the canonical signing payload. Matches Go's core.IssuanceBytes(cert).
+    // 2. Merkle inclusion proof.
+    //
+    // 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 leaf = await hashLeaf(crypto, issuanceData);
+    const leafPayload = buildLogLeafPayload(transparency.entry_type, certificate.certificate_id, await crypto.sha256(issuanceData), transparency.appended_at);
+    const leaf = await hashLeaf(crypto, leafPayload);
     const proofHashes = (transparency.inclusion_proof ?? []).map((h) => decodeBytes(h));
     const root = decodeBytes(sth.root_hash);
-    const index = transparency.entry_index;
-    const treeSize = sth.tree_size;
+    // `?? 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`);
+    }
     if (!(await verifyInclusion(crypto, leaf, index, treeSize, proofHashes, root))) {
         throw new VerificationError("merkle inclusion proof is invalid");
     }
@@ -256,29 +317,142 @@ function decodeBytes(value) {
     }
     return base64ToBytes(str);
 }
-function formatTimestamp(ts) {
-    // Strip fractional seconds, normalize to YYYY-MM-DDTHH:MM:SSZ
-    let s = ts;
-    const dotIdx = s.indexOf(".");
-    if (dotIdx !== -1) {
-        // Find the end of fractional seconds (Z, +, or end)
-        let endIdx = s.length;
-        for (let i = dotIdx + 1; i < s.length; i++) {
-            if (s[i] === "Z" || s[i] === "+" || s[i] === "-") {
-                endIdx = i;
-                break;
-            }
-        }
-        s = s.slice(0, dotIdx) + s.slice(endIdx);
+/** Go's zero time.Time — what encoding/json leaves in a non-pointer time.Time
+ *  field for an explicit JSON null or an absent key. */
+const ZERO_INSTANT = "0001-01-01T00:00:00Z";
+/** The grammar encoding/json accepts for time.Time: strict RFC 3339, uppercase
+ *  "T" and "Z" only, fixed field widths, at least one fractional digit if a "."
+ *  is present. Anything else makes Go fail to parse the certificate at all. */
+const RFC3339_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|([+-])(\d{2}):(\d{2}))$/;
+/** Normalize a certificate timestamp to the UTC form Go signs.
+ *
+ * Go builds every payload timestamp as `t.UTC().Format("2006-01-02T15:04:05Z")`
+ * (core/payload.go) on a value encoding/json already parsed as strict RFC 3339.
+ * This reproduces both halves — the same acceptance rules and the same
+ * conversion — because the two are one contract, not two.
+ *
+ * It must convert, never truncate. `12:00:00+05:00` and `12:00:00Z` are six
+ * hours apart; treating them as the same string made this verifier accept a
+ * certificate whose attestation window had been re-labelled to a different
+ * instant, and reject genuine certificates issued by a server on local time
+ * (#452). Input Go would refuse to parse is refused here rather than
+ * string-surgered into something that verifies.
+ *
+ * `null`/`undefined` — an explicit JSON null, or a key Go's struct has and the
+ * document does not — is Go's zero time, not an error.
+ *
+ * Exported from this module so the timestamp_vectors.json suite can diff it
+ * against Go directly. It is deliberately not re-exported from index.ts, so it
+ * is not part of the published package surface.
+ */
+export function formatTimestamp(ts) {
+    if (ts === null || ts === undefined)
+        return ZERO_INSTANT;
+    if (typeof ts !== "string") {
+        throw new VerificationError(`timestamp is not a string: ${JSON.stringify(ts)}`);
     }
-    if (s.endsWith("Z"))
-        return s;
-    // Strip timezone offset
-    const plusIdx = s.indexOf("+");
-    if (plusIdx !== -1) {
-        s = s.slice(0, plusIdx);
+    return formatEpochSeconds(parseRfc3339(ts));
+}
+/** Parse a strict RFC 3339 timestamp to seconds since 1970-01-01T00:00:00Z.
+ *
+ * Rejects exactly what Go's encoding/json rejects, including the ranges its
+ * parser enforces once the shape matches. Those ranges were measured against
+ * Go 1.26, not inferred from RFC 3339, and they are not the obvious ones: the
+ * time of day is 23:59:59 at most, but a zone offset runs to +24:60 — both
+ * `+24:00` and `+00:60` parse, while `+25:00` and `+00:61` do not. Sub-second
+ * digits are dropped, matching Format's truncation.
+ */
+function parseRfc3339(ts) {
+    const m = RFC3339_RE.exec(ts);
+    if (m === null)
+        throw new VerificationError(`timestamp is not RFC 3339: ${ts}`);
+    const [year, month, day, hour, minute, second] = m
+        .slice(1, 7)
+        .map((v) => Number.parseInt(v, 10));
+    if (month < 1 || month > 12)
+        throw new VerificationError(`timestamp month out of range: ${ts}`);
+    if (day < 1 || day > daysInMonth(year, month)) {
+        throw new VerificationError(`timestamp day out of range: ${ts}`);
+    }
+    if (hour > 23 || minute > 59 || second > 59) {
+        throw new VerificationError(`timestamp time of day out of range: ${ts}`);
     }
-    return s + "Z";
+    let offset = 0;
+    const sign = m[7];
+    if (sign !== undefined) {
+        const offHour = Number.parseInt(m[8], 10);
+        const offMin = Number.parseInt(m[9], 10);
+        if (offHour > 24)
+            throw new VerificationError(`timestamp zone offset hour out of range: ${ts}`);
+        if (offMin > 60)
+            throw new VerificationError(`timestamp zone offset minute out of range: ${ts}`);
+        offset = (offHour * 3600 + offMin * 60) * (sign === "-" ? -1 : 1);
+    }
+    return daysFromCivil(year, month, day) * 86400 + hour * 3600 + minute * 60 + second - offset;
+}
+/** Render seconds since the Unix epoch as `YYYY-MM-DDTHH:MM:SSZ`.
+ *
+ * Matches Go's Format for the reachable extremes: a year 0000 timestamp with a
+ * `+24:00` offset lands in year -1, which Go prints as `-0001`, and 9999-12-31
+ * with `-24:00` lands in year 10000, which Go prints unpadded.
+ */
+function formatEpochSeconds(total) {
+    const days = Math.floor(total / 86400);
+    const secs = total - days * 86400;
+    const [year, month, day] = civilFromDays(days);
+    const hour = Math.floor(secs / 3600);
+    const minute = Math.floor((secs - hour * 3600) / 60);
+    const second = secs - hour * 3600 - minute * 60;
+    const printedYear = year < 0 ? "-" + pad(-year, 4) : pad(year, 4);
+    return `${printedYear}-${pad(month, 2)}-${pad(day, 2)}T${pad(hour, 2)}:${pad(minute, 2)}:${pad(second, 2)}Z`;
+}
+function pad(value, width) {
+    return String(value).padStart(width, "0");
+}
+/** Length of a proleptic Gregorian month. Year 0 is a leap year; 1900 is not. */
+function daysInMonth(year, month) {
+    if (month === 2) {
+        const isLeap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+        return isLeap ? 29 : 28;
+    }
+    return month === 4 || month === 6 || month === 9 || month === 11 ? 30 : 31;
+}
+/** Days from 1970-01-01 to a proleptic Gregorian date (Howard Hinnant's algorithm).
+ *
+ * Deliberately not `Date`: Go accepts year 0000, and a zone offset can push the
+ * UTC instant to year -1 or 10000, where `Date`'s parsing and formatting stop
+ * agreeing with Go. A verifier that disagrees with the reference on any input is
+ * a verifier a relying party cannot use to second-guess the reference.
+ */
+function daysFromCivil(year, month, day) {
+    const y = month <= 2 ? year - 1 : year;
+    const era = Math.floor(y / 400);
+    const yearOfEra = y - era * 400; // [0, 399]
+    const shiftedMonth = month > 2 ? month - 3 : month + 9; // [0, 11]
+    const dayOfYear = Math.floor((153 * shiftedMonth + 2) / 5) + day - 1; // [0, 365]
+    const dayOfEra = yearOfEra * 365 +
+        Math.floor(yearOfEra / 4) -
+        Math.floor(yearOfEra / 100) +
+        dayOfYear;
+    return era * 146097 + dayOfEra - 719468;
+}
+/** Inverse of daysFromCivil. */
+function civilFromDays(days) {
+    const z = days + 719468;
+    const era = Math.floor(z / 146097);
+    const dayOfEra = z - era * 146097; // [0, 146096]
+    const yearOfEra = Math.floor((dayOfEra -
+        Math.floor(dayOfEra / 1460) +
+        Math.floor(dayOfEra / 36524) -
+        Math.floor(dayOfEra / 146096)) /
+        365); // [0, 399]
+    const dayOfYear = dayOfEra -
+        (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100)); // [0, 365]
+    const shiftedMonth = Math.floor((5 * dayOfYear + 2) / 153); // [0, 11]
+    const day = dayOfYear - Math.floor((153 * shiftedMonth + 2) / 5) + 1;
+    const month = shiftedMonth < 10 ? shiftedMonth + 3 : shiftedMonth - 9;
+    const year = yearOfEra + era * 400 + (month <= 2 ? 1 : 0);
+    return [year, month, day];
 }
 // ---------------------------------------------------------------------------
 // Payload builders — exact ports of core/payload.go
@@ -292,8 +466,11 @@ function buildAttestationPayload(subject, att) {
         merkle_root: s.merkle_root
             ? toHex(s.merkle_root)
             : null,
-        observed_at: attestedAt,
+        // The system's own observation time, not the envelope's.
+        observed_at: formatTimestamp(s.observed_at),
+        query_hash: toHex(s.query_hash),
         record_count: s.record_count,
+        system_id: s.system_id,
         system_name: s.system_name,
     }));
     const payload = {
@@ -305,53 +482,32 @@ function buildAttestationPayload(subject, att) {
     };
     return canonicalJson(payload);
 }
-function buildVerificationPayload(attestationId, ver) {
-    const verifiedAt = formatTimestamp(ver.verified_at);
-    const systems = ver.systems.map((s) => ({
-        observed_at: verifiedAt,
-        record_count: s.record_count,
-        system_name: s.system_name,
-    }));
-    const payload = {
-        attestation_id: attestationId,
-        payload_type: PAYLOAD_TYPE_VERIFICATION,
-        systems,
-        verified_at: verifiedAt,
-    };
-    return canonicalJson(payload);
-}
 function buildCertificatePayload(cert) {
     const att = cert.attestation;
-    const ver = cert.verification;
     const issuer = cert.issuer;
     const subject = cert.subject;
-    // Attestation systems — uses "system_name" field name
-    const attSystems = att.systems.map((s) => ({
+    // One list, keyed by system_id (ADR-016 §2). v2 signed an attestation list
+    // and a verification list joined only on the human-editable system_name,
+    // which made a partial deletion indistinguishable from a complete one.
+    const systems = (cert.systems ?? []).map((s) => ({
+        attested_at: formatTimestamp(s.attested_at),
+        attested_count: s.attested_count,
         canonical_version: s.canonical_version ?? null,
         connector_type: s.connector_type,
         hash_scope: s.hash_scope,
-        merkle_root: s.merkle_root
-            ? toHex(s.merkle_root)
-            : null,
-        record_count: s.record_count,
+        merkle_root: s.merkle_root ? toHex(s.merkle_root) : null,
+        query_hash: toHex(s.query_hash),
+        system_id: s.system_id,
         system_name: s.system_name,
+        verified_at: formatTimestamp(s.verified_at),
+        verified_count: s.verified_count,
     }));
+    // The attestation block carries no system list of its own: the merged list
+    // above is a superset of it. verification_signature is gone entirely.
     const attObj = {
         attestation_signature: toHex(att.attestation_signature),
         attested_at: formatTimestamp(att.attested_at),
         proof_mode: att.proof_mode,
-        systems: attSystems,
-    };
-    // Verification systems
-    const verSystems = ver.systems.map((s) => ({
-        connector_type: s.connector_type,
-        record_count: s.record_count,
-        system_name: s.system_name,
-    }));
-    const verObj = {
-        systems: verSystems,
-        verification_signature: toHex(ver.verification_signature),
-        verified_at: formatTimestamp(ver.verified_at),
     };
     const issuerObj = {
         key_id: issuer.key_id,
@@ -362,16 +518,9 @@ function buildCertificatePayload(cert) {
         identifier_hash: toHex(subject.identifier_hash),
         identifier_type_hint: subject.identifier_type_hint,
     };
-    // Revocation
-    let revocation = null;
-    const rev = cert.revocation;
-    if (rev != null) {
-        revocation = {
-            reason: rev.reason,
-            replacement_certificate_id: rev.replacement_certificate_id ?? null,
-            revoked_at: formatTimestamp(rev.revoked_at),
-        };
-    }
+    // status and revocation are deliberately absent (ADR-016 §3): a signature
+    // commits to bytes at an instant, revocation is discovered later, so it
+    // travels as a separate short-lived signed status statement.
     const payload = {
         attestation: attObj,
         attestation_id: cert.attestation_id,
@@ -380,13 +529,43 @@ function buildCertificatePayload(cert) {
         issued_at: formatTimestamp(cert.issued_at),
         issuer: issuerObj,
         payload_type: PAYLOAD_TYPE_CERTIFICATE,
-        revocation,
-        status: cert.status,
         subject: subjectObj,
-        verification: verObj,
+        systems,
     };
     return canonicalJson(payload);
 }
+/** Port of Go's BuildLogLeafPayload (ADR-016 §4). */
+function buildLogLeafPayload(entryType, certificateId, certificateHash, appendedAt) {
+    if (entryType !== "CERTIFICATE" && entryType !== "REVOCATION") {
+        throw new VerificationError(`invalid log entry_type: ${String(entryType)}`);
+    }
+    const payload = {
+        appended_at: formatTimestamp(appendedAt),
+        certificate_hash: bytesToHex(certificateHash),
+        certificate_id: certificateId,
+        entry_type: entryType,
+        payload_type: PAYLOAD_TYPE_LOG_LEAF,
+    };
+    return canonicalJson(payload);
+}
+/**
+ * Project the merged system list back onto the attest-time shape, so the
+ * attestation signature — produced days before the certificate existed — can be
+ * checked. Mirrors DeletionCertificate.AttestationSystems() in Go.
+ */
+function attestationSystems(cert) {
+    return (cert.systems ?? []).map((s) => ({
+        system_id: s.system_id,
+        system_name: s.system_name,
+        connector_type: s.connector_type,
+        hash_scope: s.hash_scope,
+        query_hash: s.query_hash,
+        record_count: s.attested_count,
+        observed_at: s.attested_at,
+        merkle_root: s.merkle_root,
+        canonical_version: s.canonical_version,
+    }));
+}
 function buildTreeHeadPayload(head) {
     const payload = {
         payload_type: PAYLOAD_TYPE_TREE_HEAD,
@@ -406,6 +585,29 @@ async function hashNode(crypto, left, right) {
     const prefix = new Uint8Array([0x01]);
     return crypto.sha256(concatBytes(prefix, concatBytes(left, right)));
 }
+/** Read a tree index or size the way Go's uint64 unmarshalling does.
+ *
+ * Go's struct fields are uint64, so a negative or fractional JSON number makes
+ * the whole certificate fail to parse, and the `index >= size` guard in
+ * verifyInclusion never sees one. This SDK gets a JavaScript number, where that
+ * guard passes a negative index straight through and any value past 2^53 has
+ * already lost the precision the Merkle arithmetic depends on (#456). Both are
+ * rejected here, at the document boundary, rather than trusted downstream.
+ */
+function requireUint(value, field) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+        throw new VerificationError(`${field} is not an exact non-negative integer: ${JSON.stringify(value)}`);
+    }
+    if (value < 0)
+        throw new VerificationError(`${field} is negative: ${value}`);
+    return value;
+}
+/** Largest power of 2 strictly less than n. Port of Go's splitPoint.
+ *
+ * The loop terminates because requireUint has already bounded n to a safe
+ * integer; Go, which has no such bound, computes the same value with
+ * `1 << (bits.Len64(n-1) - 1)` because its loop form overflowed (#456).
+ */
 function splitPoint(n) {
     let k = 1;
     while (k * 2 < n) {
@@ -469,7 +671,16 @@ export async function verifyConsistency(crypto, oldSize, newSize, oldRoot, newRo
         fn >>= 1;
         sn >>= 1;
     }
-    while (pIdx < proof.length) {
+    // Drive the walk from the tree, not from the proof's length. Looping on
+    // `pIdx < proof.length` let the prover choose how many steps ran, so a log
+    // could understate its own size and present the genuine proof for the size it
+    // really had — STH{size: 6} carrying the root of 7 leaves verified against the
+    // real 7 -> 8 proof. The only consumer is a witness detecting exactly that
+    // equivocation. Length is part of the claim: too few elements runs out here,
+    // too many is caught by the pIdx check below.
+    while (sn !== 0) {
+        if (pIdx >= proof.length)
+            return false;
         const c = proof[pIdx];
         pIdx++;
         if ((fn & 1) === 1 || fn === sn) {
@@ -486,6 +697,101 @@ export async function verifyConsistency(crypto, oldSize, newSize, oldRoot, newRo
         fn >>= 1;
         sn >>= 1;
     }
-    return sn === 0 && bytesEqual(fr, oldRoot) && bytesEqual(sr, newRoot);
+    return pIdx === proof.length && bytesEqual(fr, oldRoot) && bytesEqual(sr, newRoot);
+}
+/**
+ * Port of Go's BuildCertificateStatusPayload.
+ *
+ * Optional fields are omitted, never emitted as null: the issuer omits them, so
+ * a verifier that emitted nulls would rebuild different bytes and reject a
+ * genuine statement.
+ */
+export function buildCertificateStatusPayload(stmt) {
+    const payload = {
+        payload_type: PAYLOAD_TYPE_CERTIFICATE_STATUS,
+        certificate_id: stmt.certificate_id,
+        statement_expires_at: formatTimestamp(stmt.statement_expires_at),
+        statement_issued_at: formatTimestamp(stmt.statement_issued_at),
+        status: stmt.status,
+        sth_root_hash: toHex(stmt.sth_root_hash),
+        sth_tree_size: stmt.sth_tree_size,
+    };
+    if (stmt.replacement_certificate_id != null) {
+        payload.replacement_certificate_id = stmt.replacement_certificate_id;
+    }
+    if (stmt.revocation_log_index != null) {
+        payload.revocation_log_index = stmt.revocation_log_index;
+    }
+    if (stmt.revoked_at != null) {
+        payload.revoked_at = formatTimestamp(stmt.revoked_at);
+    }
+    return canonicalJson(payload);
+}
+/** The verdict when a certificate verified but nothing said whether it was revoked. */
+export const VALID_REVOCATION_UNKNOWN = "VALID_REVOCATION_UNKNOWN";
+/**
+ * Verify a certificate and, separately, what a statement says about its
+ * revocation.
+ *
+ * A signature commits to bytes at an instant; revocation is discovered later,
+ * so no edit to the signed certificate can express it. The statement is a
+ * separate short-lived document — fetch it from
+ * `GET /v1/certificates/{id}/status`, or read `status_statement` from the
+ * certificate response, where it is stapled for exactly this purpose.
+ *
+ * | input | result |
+ * |---|---|
+ * | fresh statement, REVOKED | throws VerificationError |
+ * | fresh statement, ACTIVE | `"VALID"` |
+ * | absent or expired statement | `"VALID_REVOCATION_UNKNOWN"` |
+ *
+ * The last row is the point: `verifyCertificate` answers VALID there, which
+ * reads as "not revoked" and is not something it checked.
+ */
+export async function verifyCertificateWithStatus(crypto, certificate, publicKeys, status, now) {
+    const base = await verifyCertificate(crypto, certificate, publicKeys);
+    if (base !== "VALID") {
+        return base;
+    }
+    if (status == null) {
+        return VALID_REVOCATION_UNKNOWN;
+    }
+    const keyId = status.key_id;
+    const info = keyId ? publicKeys.get(keyId) : undefined;
+    if (!info) {
+        throw new VerificationError(`status statement signed by unknown key: ${keyId}`);
+    }
+    if (info.revoked) {
+        throw new VerificationError("status statement signed by a revoked key");
+    }
+    const payload = buildCertificateStatusPayload(status);
+    // decodeSignature, not hexToBytes: signatures arrive as hex, base64 or a byte
+    // array depending on the producer, and every other signature on this path
+    // goes through the same decoder.
+    const sig = decodeSignature(status.signature);
+    if (!(await crypto.ed25519Verify(info.keyBytes, payload, sig))) {
+        throw new VerificationError("status statement signature is invalid");
+    }
+    // A validly signed statement about a different certificate must not be
+    // allowed to speak for this one.
+    const certId = certificate.id ??
+        certificate.certificate_id;
+    if (status.certificate_id !== certId) {
+        throw new VerificationError("status statement is about a different certificate");
+    }
+    // Compared in the normalized form the payload signs, so the freshness check
+    // cannot disagree with what was signed about the same two instants.
+    const at = formatTimestamp((now ?? new Date()).toISOString());
+    const issued = formatTimestamp(status.statement_issued_at);
+    const expires = formatTimestamp(status.statement_expires_at);
+    if (at < issued || at >= expires) {
+        // Stale is not a weaker answer, it is no answer — including for a REVOKED
+        // statement, which must never decay into VALID.
+        return VALID_REVOCATION_UNKNOWN;
+    }
+    if (status.status === "REVOKED") {
+        throw new VerificationError("certificate has been revoked");
+    }
+    return "VALID";
 }
 //# sourceMappingURL=verify.js.map