burnledger 0.8.1 → 0.9.0

package/dist/esm/verify.js

@@ -15,7 +15,7 @@
  *     certificate signing payload. issuanceBytes reconstructs json.Marshal
  *     output at issuance time (transparency_status=PENDING, no transparency).
  */
-import { CERTIFICATE_REVOKED, UNSUPPORTED_ALGORITHM, UNSUPPORTED_FORMAT_VERSION, VerificationError, } from "./errors.js";
+import { AUTHORIZATION_POLICY_FAILED, CERTIFICATE_REVOKED, UNSUPPORTED_ALGORITHM, UNSUPPORTED_FORMAT_VERSION, VerificationError, } from "./errors.js";
 // ---------------------------------------------------------------------------
 // Pure byte helpers (no Buffer, no node:crypto)
 // ---------------------------------------------------------------------------
@@ -63,8 +63,9 @@ const PAYLOAD_TYPE_ATTESTATION_V8 = "burnledger.attestation.v8";
 const PAYLOAD_TYPE_VERIFICATION_RECORD_V8 = "burnledger.verification_record.v8";
 const FORMAT_VERSION_V8 = "8.0";
 // v9 adds two per-system fields, authorization and customer_key_id: whether the
-// enclave checked this system against a customer-signed registration
-// certificate (ADR-025 §4), and under which customer key group if it did.
+// enclave checked this system against a registration certificate (ADR-025 §4),
+// and under which customer key group if it did. That the key group SIGNED the
+// registration holds only from enclave protocol 12: see PRE_PROTOCOL_12_IMAGES.
 //
 // The attestation gains NO field at v9. Its tag still moves, because the tag
 // follows the record's version and the record's bytes changed — a v9
@@ -208,17 +209,22 @@ const PAYLOAD_TYPE_LOG_LEAF = "burnledger.log_leaf.v3";
 // in the same enclave call that signs the certificate (ADR-016 §2).
 const PAYLOAD_TYPE_CERTIFICATE_STATUS = "burnledger.certificate_status.v3";
 const PAYLOAD_TYPE_KEY_LIST = "burnledger.key_list.v3";
+/** Decode hex: whole bytes, digits in either case, nothing else. Anything else
+ * throws TypeError. It is exported, so its input is a boundary: reading a stray
+ * character as 0, as it once did, turned a typo into different bytes. */
 export function hexToBytes(hex) {
-    const len = hex.length >>> 1;
-    const out = new Uint8Array(len);
-    for (let i = 0; i < len; i++) {
-        const hi = hex.charCodeAt(i * 2);
-        const lo = hex.charCodeAt(i * 2 + 1);
-        out[i] = (unhex(hi) << 4) | unhex(lo);
+    if (typeof hex !== "string")
+        throw new TypeError(`hex is not a string: ${typeof hex}`);
+    if (hex.length % 2 !== 0)
+        throw new TypeError(`hex has an odd number of digits: ${hex.length}`);
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = (unhex(hex, i * 2) << 4) | unhex(hex, i * 2 + 1);
     }
     return out;
 }
-function unhex(c) {
+function unhex(hex, at) {
+    const c = hex.charCodeAt(at);
     // 0-9
     if (c >= 48 && c <= 57)
         return c - 48;
@@ -228,7 +234,7 @@ function unhex(c) {
     // A-F
     if (c >= 65 && c <= 70)
         return c - 55;
-    return 0;
+    throw new TypeError(`hex has a non-hex character ${JSON.stringify(hex[at])} at ${at}`);
 }
 export function bytesToHex(bytes) {
     let out = "";
@@ -268,6 +274,13 @@ function textToBytes(s) {
     return new TextEncoder().encode(s);
 }
 export async function publicKeyFromHex(crypto, hexKey, opts) {
+    // Refused here, as the VerificationError callers are told to catch, rather
+    // than left to hexToBytes's TypeError. The alphabet is the one
+    // core.KeyEntry.PublicKeyInfo takes through hex.DecodeString: either case,
+    // whole bytes, nothing else.
+    if (typeof hexKey !== "string" || !HEX_TEXT_RE.test(hexKey)) {
+        throw new VerificationError(`public key is not hex: ${JSON.stringify(hexKey)}`);
+    }
     const raw = hexToBytes(hexKey);
     if (raw.length !== 32) {
         throw new VerificationError(`public key must be 32 bytes, got ${raw.length}`);
@@ -375,7 +388,7 @@ export function certificateAnchor(certificate) {
     if (transparency == null)
         return null;
     const sth = transparency.signed_tree_head;
-    if (sth === undefined || typeof sth.timestamp !== "string")
+    if (sth == null || typeof sth.timestamp !== "string")
         return null;
     try {
         return parseRfc3339(sth.timestamp);
@@ -405,15 +418,22 @@ async function verifiedCertificateAnchor(crypto, certificate, pki) {
         return null;
     const transparency = certificate.transparency;
     const sth = transparency.signed_tree_head;
+    // 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;
+    let headSig;
     try {
-        const headPayload = buildTreeHeadPayload(sth);
-        const headSig = decodeSignature(sth.signature);
-        if (!(await crypto.ed25519Verify(pki.keyBytes, headPayload, headSig)))
+        headPayload = buildTreeHeadPayload(sth);
+        headSig = decodeFixed(sth.signature, "signed_tree_head.signature", 64);
+    }
+    catch (e) {
+        if (e instanceof VerificationError)
             return null;
+        throw e;
     }
-    catch {
+    if (!(await crypto.ed25519Verify(pki.keyBytes, headPayload, headSig)))
         return null;
-    }
     return anchor;
 }
 /** Throws for a key that cannot be used at all; returns the verdict otherwise.
@@ -449,14 +469,155 @@ role = "issuer key") {
     }
     return verdict;
 }
+function policySet(values, field, lower) {
+    if (values === undefined)
+        return undefined;
+    if (!Array.isArray(values) || !values.every((v) => typeof v === "string" && v !== "")) {
+        throw new TypeError(`requireAuthorization.${field} must be an array of non-empty strings`);
+    }
+    if (values.length === 0) {
+        // An empty requirement requires nothing, which is never what a caller who
+        // built a policy meant.
+        throw new Error(`an empty requireAuthorization.${field} requires nothing; omit it instead`);
+    }
+    return new Set(values.map((v) => (lower ? v.toLowerCase() : v)));
+}
+/** Check a policy before anything is verified, so a caller's mistake surfaces as
+ * one whatever the record turns out to be. */
+function parsePolicy(policy) {
+    const keys = policy.customerKeyIds;
+    if (keys === undefined || (Array.isArray(keys) && keys.length === 0)) {
+        throw new TypeError("requireAuthorization.customerKeyIds is required, with at least one key id: `certified` under " +
+            "a key id you did not name proves nothing to you, because the relay can enroll a key group of its own");
+    }
+    return {
+        systems: policySet(policy.systems, "systems", true),
+        customerKeyIds: policySet(policy.customerKeyIds, "customerKeyIds", false),
+    };
+}
+/**
+ * The enclave images that issued format 9.0 while running wire protocol 11 or
+ * earlier, by PCR0, as the published measurement history records them
+ * (website/docs/enclave-measurements/, docs/CONNECTOR-STATUS.md).
+ *
+ * Their `certified` is not evidence of a customer signature. Before protocol 12
+ * the enclave enrolled a key group with no proof that anyone held its keys, and
+ * registered a system for whoever relayed the authorization — so the host could
+ * make a genuine 9.0 record say `certified`, under a key id it chose, with no
+ * customer signature anywhere (reproduced by an independent re-review,
+ * 2026-09-13).
+ *
+ * THE SET IS CLOSED BY POLICY, NOT BY ENFORCEMENT: the release runbook forbids
+ * admitting or rolling back to an image of protocol 11 or earlier once any
+ * customer key is enrolled, and admitting one takes a KMS re-pin, which ADR-027
+ * leaves to the owner. The protocol-12 cutover's KMS tighten drops every
+ * measurement here from the signing key's policy, after which none of them can
+ * sign. v42 ran for seven minutes and is recorded as issuing nothing; it is here
+ * because it held the signing key while it ran.
+ *
+ * The Python SDK carries the same list, in _verify.py.
+ */
+export const PRE_PROTOCOL_12_IMAGES = new Map([
+    ["0e79f985c287fbad3ed9aa1d5443189c45428929086dc4d4312ba71c4039742a8bca02f4ea15ab318d82e1d86ff883d3", "EIF v39"],
+    ["665864551aeb57705c3b3721018112cbd0e2be98de2e0ff9142a6c0abf366c72c6ba6cdcd31cd6ed8471862e1b9187ce", "EIF v40"],
+    ["7a61327a0ee11508764a8ad03d68e81e3b374e4e605a284e9e815ec9cf57de8497e59d57048977441f9c5c98bee1d14b", "EIF v41"],
+    ["f1e02ace0011bfc0d60d6dd76da0078b7706f3165eff6904a36e97e5d2029246099ef20bf15f87d0263dd843f878731c", "EIF v42"],
+    ["10ed72207ffd6a14f5913130eca69e9f4f9de0447b360e9cfd8aa8e349681c6fe98c515499a38a347d67932a6201a9b4", "EIF v43"],
+    ["0bfbd2251cb9e138491c6ce424ad132b28be152e1486aa7100acabce0201f3f5d500eb47dc00184de4eebc93fe4dc695", "EIF v44"],
+    ["4d68b3ef6b77418f2827964400241ee9db7e101ce53666b75cc6cf7aa17d7c9f3a1b9055bafec4f799beee6e00227546", "EIF v45 and v46"],
+]);
+export function issuingImage(certificate) {
+    const issuer = certificate.issuer;
+    const pcr0 = String(issuer?.enclave_pcr0 ?? "").toLowerCase();
+    if (pcr0 === "")
+        return { kind: "unnamed" };
+    const name = PRE_PROTOCOL_12_IMAGES.get(pcr0);
+    return name === undefined
+        ? { kind: "protocol-12-or-later", pcr0 }
+        : { kind: "before-protocol-12", name, pcr0 };
+}
+/**
+ * What `certified` is evidence of, given the image that signed the record: the
+ * words every verifier prints after "certified under <key id> —". The Go CLI
+ * (cmd/cli/registration_image.go), both SDK CLIs and the /verify page state it
+ * identically, and testdata/registration_line_cases.json holds them to it.
+ */
+export function registrationQualifier(image) {
+    switch (image.kind) {
+        case "unnamed":
+            return ("not evidence here: this record names no enclave image, so it may come from one " +
+                "that could mark a system certified without the customer's signature.");
+        case "before-protocol-12":
+            return (`not evidence here: this record comes from ${image.name}, an enclave image of ` +
+                "protocol 11 or earlier, which could mark a system certified without the customer's signature.");
+        case "protocol-12-or-later":
+            return ("the key group with that id signed this system's registration, if that key id is yours: " +
+                "this record comes from an enclave image of protocol 12 or later. If that key id is not yours, " +
+                "someone else authorized this verification.");
+    }
+}
+/**
+ * Throw unless a record that has already verified meets `policy`.
+ *
+ * From 9.0 every field read here is under the certificate signature, the
+ * issuer's enclave_pcr0 included. Below 9.0
+ * nothing signs `authorization` — those records carry the field outside the
+ * signed bytes — so one that says `certified` says only what its last holder
+ * typed. It fails on the format, before the field is read.
+ */
+function enforceAuthorization(certificate, formatVersion, policy) {
+    const systemsWanted = policy.systems;
+    if (!signatureCoversAuthorization(formatVersion)) {
+        throw new VerificationError(`authorization required, but this record is format ${formatVersion}, which predates ` +
+            `customer-signed registration (${FORMAT_VERSION_V9}); it cannot show that any system was certified`, AUTHORIZATION_POLICY_FAILED);
+    }
+    const systems = certificate.systems ?? [];
+    let required = systems;
+    if (systemsWanted !== undefined) {
+        const byId = new Map(systems.map((s) => [String(s.system_id).toLowerCase(), s]));
+        const missing = [...systemsWanted].filter((id) => !byId.has(id)).sort();
+        if (missing.length > 0) {
+            throw new VerificationError(`authorization required for system ${missing[0]}, which this record does not cover`, AUTHORIZATION_POLICY_FAILED);
+        }
+        required = [...systemsWanted].sort().map((id) => byId.get(id));
+    }
+    const labelOf = (s) => `system ${JSON.stringify(s.system_name)} (${String(s.system_id)})`;
+    for (const s of required) {
+        if (s.authorization !== AUTHORIZATION_CERTIFIED) {
+            throw new VerificationError(`authorization required, but ${labelOf(s)} is ${JSON.stringify(s.authorization ?? null)}: ` +
+                "the enclave did not check it against a registration", AUTHORIZATION_POLICY_FAILED);
+        }
+    }
+    // Asked once, for the record, after every required system has said certified:
+    // which image said it decides whether `certified` means a customer signed.
+    const image = issuingImage(certificate);
+    if (image.kind === "unnamed") {
+        throw new VerificationError("authorization required, but this record names no enclave image (issuer.enclave_pcr0 is " +
+            "absent), so nothing shows it came from one that registers a system only with the " +
+            "customer's signature", AUTHORIZATION_POLICY_FAILED);
+    }
+    if (image.kind === "before-protocol-12") {
+        throw new VerificationError(`authorization required, but this record was signed by ${image.name} (PCR0 ${image.pcr0.slice(0, 16)}…), ` +
+            "an enclave image of wire protocol 11 or earlier, which could register a system without " +
+            "the customer's signature; its `certified` does not show that any key group signed anything", AUTHORIZATION_POLICY_FAILED);
+    }
+    for (const s of required) {
+        if (!policy.customerKeyIds.has(s.customer_key_id)) {
+            throw new VerificationError(`${labelOf(s)} is certified under ${String(s.customer_key_id)}, which is not a key you ` +
+                "accept; if it is not yours, someone else authorized this verification", AUTHORIZATION_POLICY_FAILED);
+        }
+    }
+}
 /** Verify all signatures on a deletion certificate offline. */
-export async function verifyCertificate(crypto, certificate, publicKeys) {
+export async function verifyCertificate(crypto, certificate, publicKeys, options) {
     // Step 0: can this SDK read the format at all? Every check below rebuilds
     // signed bytes from the version, so an unreadable version makes all of them
     // meaningless - and "unknown issuer key" would be the wrong thing to tell
     // someone holding a record that is merely newer than this library.
+    requireObject(certificate, "certificate");
+    const policy = options?.requireAuthorization === undefined ? undefined : parsePolicy(options.requireAuthorization);
     const formatVersion = checkFormatVersion(certificate.certificate_format_version);
-    const issuer = certificate.issuer;
+    const issuer = objectAt(certificate, "issuer", "issuer");
     // Step 0b: can this SDK check the algorithm the record names? Asked before
     // any signature, because verifying an Ed25519 signature over a record that
     // says it was signed with something else answers a question nobody asked.
@@ -467,7 +628,7 @@ export async function verifyCertificate(crypto, certificate, publicKeys) {
             `this version of the SDK verifies ${ALGORITHM_ED25519}. ` +
             "The record may be genuine and simply signed with a scheme this library does not implement.", UNSUPPORTED_ALGORITHM);
     }
-    const keyId = issuer.key_id;
+    const keyId = stringAt(issuer, "key_id", "issuer.key_id");
     const pki = publicKeys.get(keyId);
     if (pki === undefined)
         throw new VerificationError(`unknown issuer key: ${keyId}`);
@@ -477,7 +638,7 @@ export async function verifyCertificate(crypto, certificate, publicKeys) {
     // 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);
+    const certSig = decodeFixed(certificate.certificate_signature, "certificate_signature", 64);
     if (!(await crypto.ed25519Verify(pki.keyBytes, certPayload, certSig))) {
         throw new VerificationError("certificate signature is invalid");
     }
@@ -491,7 +652,7 @@ export async function verifyCertificate(crypto, certificate, publicKeys) {
         attested_at: att.attested_at,
         systems: attestationSystems(certificate),
     }, certificate.certificate_format_version);
-    const attSig = decodeSignature(att.attestation_signature);
+    const attSig = decodeFixed(att.attestation_signature, "attestation.attestation_signature", 64);
     if (!(await crypto.ed25519Verify(pki.keyBytes, attPayload, attSig))) {
         throw new VerificationError("attestation signature is invalid");
     }
@@ -540,6 +701,9 @@ export async function verifyCertificate(crypto, certificate, publicKeys) {
     if (!anyAttested) {
         throw new VerificationError("incomplete verification: no system held any records at attestation time");
     }
+    if (policy !== undefined) {
+        enforceAuthorization(certificate, formatVersion, policy);
+    }
     // A soft key verdict is the result, not a footnote: VALID_KEY_WINDOW_UNKNOWN
     // and VALID_KEY_COMPROMISED_LATER mean this document still needs a human, and
     // reporting VALID here would be the lying by omission ADR-017 exists to stop.
@@ -548,13 +712,14 @@ export async function verifyCertificate(crypto, certificate, publicKeys) {
 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;
-    if (transparency == null) {
+    requireObject(certificate, "certificate");
+    if (certificate.transparency == null) {
         return "NOT_AVAILABLE";
     }
-    const sth = transparency.signed_tree_head;
-    const issuer = certificate.issuer;
-    const keyId = issuer.key_id;
+    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");
     const pki = publicKeys.get(keyId);
     if (pki === undefined)
         throw new VerificationError(`unknown issuer key: ${keyId}`);
@@ -562,7 +727,7 @@ export async function verifyTransparency(crypto, certificate, publicKeys) {
     requireUsableKey(pki, certificateAnchor(certificate), keyId);
     // 1. Tree head signature
     const headPayload = buildTreeHeadPayload(sth);
-    const headSig = decodeSignature(sth.signature);
+    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");
     }
@@ -575,10 +740,10 @@ export async function verifyTransparency(crypto, certificate, publicKeys) {
     // 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, certificate.certificate_id, await crypto.sha256(issuanceData), transparency.appended_at);
+    const leafPayload = buildLogLeafPayload(transparency.entry_type, stringAt(certificate, "certificate_id", "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 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
@@ -660,47 +825,89 @@ function canonicalStringify(val) {
     }
     return JSON.stringify(val);
 }
-// ---------------------------------------------------------------------------
-// Byte encoding helpers
-// ---------------------------------------------------------------------------
-/** Convert a byte field to lowercase hex. Handles:
- *  - hex string (from hand-crafted test data)
- *  - base64 string (from Go's json.Marshal of []byte slices)
- *  - number[] (from Go's json.Marshal of [N]byte fixed arrays)
- */
-function toHex(value) {
-    if (Array.isArray(value)) {
-        return bytesToHex(new Uint8Array(value));
+function requireObject(value, path) {
+    if (value === undefined || value === null)
+        throw new VerificationError(`${path} is missing`);
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new VerificationError(`${path} is not an object`);
     }
-    const str = value;
-    if (/^[0-9a-fA-F]+$/.test(str) && str.length % 2 === 0) {
-        return str.toLowerCase();
-    }
-    return bytesToHex(base64ToBytes(str));
+    return value;
+}
+function objectAt(parent, key, path) {
+    return requireObject(parent[key], path);
+}
+function stringAt(parent, key, path) {
+    const value = parent[key];
+    if (value === undefined || value === null)
+        throw new VerificationError(`${path} is missing`);
+    if (typeof value !== "string")
+        throw new VerificationError(`${path} is not a string`);
+    return value;
+}
+function optionalStringAt(parent, key, path) {
+    const value = parent[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new VerificationError(`${path} is not a string`);
+    return value;
 }
-/** Decode a signature field to raw bytes. Same format handling as toHex. */
-function decodeSignature(value) {
+/**
+ * An array field. Absent and null read as empty: Go leaves a nil slice.
+ *
+ * Returned dense. JSON cannot express a hole, but a caller building the object
+ * in JavaScript can, and `.map` skips holes — so one reached the Merkle code as
+ * `undefined` and threw a TypeError. Array.from reads a hole as undefined,
+ * which the element's own reader then refuses as missing.
+ */
+function arrayAt(parent, key, path) {
+    const value = parent[key];
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new VerificationError(`${path} is not an array`);
+    return Array.from(value);
+}
+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}=)?$/;
+/**
+ * Decode a fixed-size byte field — a hash, a key, a signature.
+ *
+ * Go marshals `[N]byte` as an array of numbers; hand-written documents carry
+ * hex or standard base64. A well-formed value of the right size is never
+ * ambiguous between the two text forms, because base64 of 32 or 64 bytes ends
+ * in padding hex cannot contain.
+ *
+ * Everything else is refused here, by name: a number, an array element that is
+ * not a byte, text that is neither encoding, the wrong length. Decoding it
+ * 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, path, length) {
+    if (value === undefined || value === null)
+        throw new VerificationError(`${path} is missing`);
+    let raw;
     if (Array.isArray(value)) {
-        return new Uint8Array(value);
+        if (!value.every((b) => Number.isInteger(b) && b >= 0 && b <= 255)) {
+            throw new VerificationError(`${path} is not an array of bytes`);
+        }
+        raw = new Uint8Array(value);
     }
-    const str = value;
-    if (/^[0-9a-fA-F]+$/.test(str)) {
-        const raw = hexToBytes(str);
-        if (raw.length === 64)
-            return raw;
+    else if (typeof value === "string") {
+        if (HEX_TEXT_RE.test(value))
+            raw = hexToBytes(value);
+        else if (BASE64_TEXT_RE.test(value))
+            raw = base64ToBytes(value);
+        else
+            throw new VerificationError(`${path} is neither hex nor base64`);
     }
-    return base64ToBytes(str);
-}
-/** Decode a hash/bytes field to raw bytes. Same format handling as toHex. */
-function decodeBytes(value) {
-    if (Array.isArray(value)) {
-        return new Uint8Array(value);
+    else {
+        throw new VerificationError(`${path} is not a byte string`);
     }
-    const str = value;
-    if (/^[0-9a-fA-F]+$/.test(str) && str.length % 2 === 0) {
-        return hexToBytes(str);
+    if (raw.length !== length) {
+        throw new VerificationError(`${path} is ${raw.length} bytes, expected ${length}`);
     }
-    return base64ToBytes(str);
+    return raw;
 }
 /** 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. */
@@ -729,14 +936,17 @@ const RFC3339_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?
  * 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.
+ *
+ * `field` names the value in a refusal. It defaults to the word these messages
+ * always used, for callers normalizing a time that is not a field of a document.
  */
-export function formatTimestamp(ts) {
+export function formatTimestamp(ts, field = "timestamp") {
     if (ts === null || ts === undefined)
         return ZERO_INSTANT;
     if (typeof ts !== "string") {
-        throw new VerificationError(`timestamp is not a string: ${JSON.stringify(ts)}`);
+        throw new VerificationError(`${field} is not a string: ${JSON.stringify(ts)}`);
     }
-    return formatEpochSeconds(parseRfc3339(ts));
+    return formatEpochSeconds(parseRfc3339(ts, field));
 }
 /** Parse a strict RFC 3339 timestamp to seconds since 1970-01-01T00:00:00Z.
  *
@@ -747,20 +957,20 @@ export function formatTimestamp(ts) {
  * `+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) {
+function parseRfc3339(ts, field = "timestamp") {
     const m = RFC3339_RE.exec(ts);
     if (m === null)
-        throw new VerificationError(`timestamp is not RFC 3339: ${ts}`);
+        throw new VerificationError(`${field} 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}`);
+        throw new VerificationError(`${field} month out of range: ${ts}`);
     if (day < 1 || day > daysInMonth(year, month)) {
-        throw new VerificationError(`timestamp day out of range: ${ts}`);
+        throw new VerificationError(`${field} day out of range: ${ts}`);
     }
     if (hour > 23 || minute > 59 || second > 59) {
-        throw new VerificationError(`timestamp time of day out of range: ${ts}`);
+        throw new VerificationError(`${field} time of day out of range: ${ts}`);
     }
     let offset = 0;
     const sign = m[7];
@@ -768,9 +978,9 @@ function parseRfc3339(ts) {
         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}`);
+            throw new VerificationError(`${field} zone offset hour out of range: ${ts}`);
         if (offMin > 60)
-            throw new VerificationError(`timestamp zone offset minute out of range: ${ts}`);
+            throw new VerificationError(`${field} 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;
@@ -854,17 +1064,17 @@ function buildAttestationPayload(subject, att, certFormatVersion) {
     // payload and call every genuine v8 record a forgery.
     const coversMeasured = signatureCoversMeasuredTransport(certFormatVersion);
     const coversRecoverable = signatureCoversRecoverableState(certFormatVersion);
-    const systems = att.systems.map((s) => {
+    const systems = att.systems.map((s, i) => {
         const sys = {
             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,
+            merkle_root: s.merkle_root == null
+                ? null
+                : bytesToHex(decodeFixed(s.merkle_root, `systems[${i}].merkle_root`, 32)),
             // The system's own observation time, not the envelope's.
-            observed_at: formatTimestamp(s.observed_at),
-            query_hash: toHex(s.query_hash),
+            observed_at: formatTimestamp(s.observed_at, `systems[${i}].attested_at`),
+            query_hash: bytesToHex(decodeFixed(s.query_hash, `systems[${i}].query_hash`, 32)),
             record_count: s.record_count,
             system_id: s.system_id,
             system_name: s.system_name,
@@ -882,7 +1092,7 @@ function buildAttestationPayload(subject, att, certFormatVersion) {
         attested_at: attestedAt,
         payload_type: attestationPayloadType(certFormatVersion),
         proof_mode: att.proof_mode,
-        subject_hash: toHex(subject.identifier_hash),
+        subject_hash: bytesToHex(decodeFixed(subject.identifier_hash, "subject.identifier_hash", 32)),
         systems,
     };
     return canonicalJson(payload);
@@ -948,9 +1158,9 @@ function attestationPayloadType(version) {
     return PAYLOAD_TYPE_ATTESTATION;
 }
 function buildCertificatePayload(cert) {
-    const att = cert.attestation;
-    const issuer = cert.issuer;
-    const subject = cert.subject;
+    const att = objectAt(cert, "attestation", "attestation");
+    const issuer = objectAt(cert, "issuer", "issuer");
+    const subject = objectAt(cert, "subject", "subject");
     // 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.
@@ -958,19 +1168,25 @@ function buildCertificatePayload(cert) {
     const coversMeasured = signatureCoversMeasuredTransport(version);
     const coversRecoverable = signatureCoversRecoverableState(version);
     const coversAuthorization = signatureCoversAuthorization(version);
-    const systems = (cert.systems ?? []).map((s) => {
+    const systems = arrayAt(cert, "systems", "systems").map((entry, i) => {
+        const where = `systems[${i}]`;
+        const s = requireObject(entry, where);
         const sys = {
-            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,
-            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,
+            attested_at: formatTimestamp(s.attested_at, `${where}.attested_at`),
+            attested_count: requireUint(s.attested_count, `${where}.attested_count`),
+            canonical_version: optionalStringAt(s, "canonical_version", `${where}.canonical_version`) ?? null,
+            connector_type: stringAt(s, "connector_type", `${where}.connector_type`),
+            hash_scope: stringAt(s, "hash_scope", `${where}.hash_scope`),
+            // Absent is a system with no Merkle root; anything present must be one.
+            // Go's *[32]byte is nil or 32 bytes, never "" or [].
+            merkle_root: s.merkle_root == null
+                ? null
+                : bytesToHex(decodeFixed(s.merkle_root, `${where}.merkle_root`, 32)),
+            query_hash: bytesToHex(decodeFixed(s.query_hash, `${where}.query_hash`, 32)),
+            system_id: stringAt(s, "system_id", `${where}.system_id`),
+            system_name: stringAt(s, "system_name", `${where}.system_name`),
+            verified_at: formatTimestamp(s.verified_at, `${where}.verified_at`),
+            verified_count: requireUint(s.verified_count, `${where}.verified_count`),
         };
         if (coversMeasured) {
             sys.read_only_enforcement = requireMeasured(s.read_only_enforcement, "read_only_enforcement", s.system_name, version);
@@ -990,9 +1206,9 @@ function buildCertificatePayload(cert) {
     // 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,
+        attestation_signature: bytesToHex(decodeFixed(att.attestation_signature, "attestation.attestation_signature", 64)),
+        attested_at: formatTimestamp(att.attested_at, "attestation.attested_at"),
+        proof_mode: stringAt(att, "proof_mode", "attestation.proof_mode"),
     };
     // Fields added after v3 are gated on the certificate's OWN version. A v3
     // certificate must reconstruct to the same bytes forever; reading these
@@ -1004,9 +1220,9 @@ function buildCertificatePayload(cert) {
     const isV5Plus = formatAtLeast(version, FORMAT_VERSION_V5);
     const isV4Plus = formatAtLeast(version, FORMAT_VERSION_V4);
     const issuerObj = {
-        key_id: issuer.key_id,
-        name: issuer.name,
-        public_key: toHex(issuer.public_key),
+        key_id: stringAt(issuer, "key_id", "issuer.key_id"),
+        name: stringAt(issuer, "name", "issuer.name"),
+        public_key: bytesToHex(decodeFixed(issuer.public_key, "issuer.public_key", 32)),
     };
     // v7 signs the algorithm, and does so unconditionally: unlike legal_entity
     // and enclave_pcr0, "which scheme signed this" is never unknown to a signer,
@@ -1014,43 +1230,48 @@ function buildCertificatePayload(cert) {
     if (signatureCoversAlgorithm(version)) {
         issuerObj.algorithm = requireMeasured(issuer.algorithm, "issuer.algorithm", "issuer", version);
     }
-    if (isV4Plus && typeof issuer.legal_entity === "string" && issuer.legal_entity !== "") {
-        issuerObj.legal_entity = issuer.legal_entity;
+    // A non-string here used to be dropped silently, so a junk value added to a
+    // record that never carried one still verified. Python refused it; so does
+    // Go, at parse. Now this does too.
+    if (isV4Plus) {
+        const legalEntity = optionalStringAt(issuer, "legal_entity", "issuer.legal_entity");
+        if (legalEntity)
+            issuerObj.legal_entity = legalEntity;
     }
     // Signed from v5, and omitted when absent or empty: a build with no
     // measurement signs none, and "" is a value a reader could mistake for one.
-    if (signatureCoversEnclavePcr0(version) &&
-        typeof issuer.enclave_pcr0 === "string" &&
-        issuer.enclave_pcr0 !== "") {
-        issuerObj.enclave_pcr0 = issuer.enclave_pcr0;
+    if (signatureCoversEnclavePcr0(version)) {
+        const pcr0 = optionalStringAt(issuer, "enclave_pcr0", "issuer.enclave_pcr0");
+        if (pcr0)
+            issuerObj.enclave_pcr0 = pcr0;
     }
     // v5 drops identifier_type_hint: signed, but always the constant "custom",
     // so it was never evidence. v3 and v4 keep it or they stop verifying.
     const subjectObj = {
-        identifier_hash: toHex(subject.identifier_hash),
+        identifier_hash: bytesToHex(decodeFixed(subject.identifier_hash, "subject.identifier_hash", 32)),
     };
     if (!isV5Plus) {
-        subjectObj.identifier_type_hint = subject.identifier_type_hint;
+        subjectObj.identifier_type_hint = stringAt(subject, "identifier_type_hint", "subject.identifier_type_hint");
     }
     // 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,
-        certificate_format_version: cert.certificate_format_version,
-        certificate_id: cert.certificate_id,
-        issued_at: formatTimestamp(cert.issued_at),
+        attestation_id: stringAt(cert, "attestation_id", "attestation_id"),
+        certificate_format_version: version,
+        certificate_id: stringAt(cert, "certificate_id", "certificate_id"),
+        issued_at: formatTimestamp(cert.issued_at, "issued_at"),
         issuer: issuerObj,
         payload_type: certificatePayloadType(version),
         subject: subjectObj,
         systems,
     };
     if (isV4Plus && cert.scope != null) {
-        const scope = cert.scope;
+        const scope = objectAt(cert, "scope", "scope");
         payload.scope = {
-            text_sha256: toHex(scope.text_sha256),
-            version: scope.version,
+            text_sha256: bytesToHex(decodeFixed(scope.text_sha256, "scope.text_sha256", 32)),
+            version: stringAt(scope, "version", "scope.version"),
         };
     }
     return canonicalJson(payload);
@@ -1061,7 +1282,7 @@ function buildLogLeafPayload(entryType, certificateId, certificateHash, appended
         throw new VerificationError(`invalid log entry_type: ${String(entryType)}`);
     }
     const payload = {
-        appended_at: formatTimestamp(appendedAt),
+        appended_at: formatTimestamp(appendedAt, "transparency.appended_at"),
         certificate_hash: bytesToHex(certificateHash),
         certificate_id: certificateId,
         entry_type: entryType,
@@ -1110,13 +1331,13 @@ function attestationSystems(cert) {
  * between two modules of this package, not published surface.
  */
 export function buildTreeHeadPayload(head) {
-    const logId = head.log_id;
-    const named = typeof logId === "string" && logId !== "";
+    const logId = optionalStringAt(head, "log_id", "signed_tree_head.log_id");
+    const named = logId !== undefined && logId !== "";
     const payload = {
         payload_type: named ? PAYLOAD_TYPE_TREE_HEAD_V7 : PAYLOAD_TYPE_TREE_HEAD,
-        root_hash: toHex(head.root_hash),
-        timestamp: formatTimestamp(head.timestamp),
-        tree_size: head.tree_size,
+        root_hash: bytesToHex(decodeFixed(head.root_hash, "signed_tree_head.root_hash", 32)),
+        timestamp: formatTimestamp(head.timestamp, "signed_tree_head.timestamp"),
+        tree_size: requireUint(head.tree_size ?? 0, "signed_tree_head.tree_size"),
     };
     if (named)
         payload.log_id = logId;
@@ -1256,21 +1477,21 @@ export async function verifyConsistency(crypto, oldSize, newSize, oldRoot, newRo
 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,
+        certificate_id: stringAt(stmt, "certificate_id", "status.certificate_id"),
+        statement_expires_at: formatTimestamp(stmt.statement_expires_at, "status.statement_expires_at"),
+        statement_issued_at: formatTimestamp(stmt.statement_issued_at, "status.statement_issued_at"),
+        status: stringAt(stmt, "status", "status.status"),
+        sth_root_hash: bytesToHex(decodeFixed(stmt.sth_root_hash, "status.sth_root_hash", 32)),
+        sth_tree_size: requireUint(stmt.sth_tree_size ?? 0, "status.sth_tree_size"),
     };
-    if (stmt.replacement_certificate_id != null) {
-        payload.replacement_certificate_id = stmt.replacement_certificate_id;
-    }
+    const replacement = optionalStringAt(stmt, "replacement_certificate_id", "status.replacement_certificate_id");
+    if (replacement !== undefined)
+        payload.replacement_certificate_id = replacement;
     if (stmt.revocation_log_index != null) {
-        payload.revocation_log_index = stmt.revocation_log_index;
+        payload.revocation_log_index = requireUint(stmt.revocation_log_index, "status.revocation_log_index");
     }
     if (stmt.revoked_at != null) {
-        payload.revoked_at = formatTimestamp(stmt.revoked_at);
+        payload.revoked_at = formatTimestamp(stmt.revoked_at, "status.revoked_at");
     }
     return canonicalJson(payload);
 }
@@ -1305,7 +1526,7 @@ export function buildKeyListPayload(doc) {
         keys: entries,
         statement_expires_at: formatTimestamp(doc.statement_expires_at),
         statement_issued_at: formatTimestamp(doc.statement_issued_at),
-        sth_root_hash: toHex(doc.sth_root_hash),
+        sth_root_hash: bytesToHex(decodeFixed(doc.sth_root_hash, "sth_root_hash", 32)),
         sth_tree_size: doc.sth_tree_size,
     };
     return canonicalJson(payload);
@@ -1331,18 +1552,38 @@ export const VALID_REVOCATION_UNKNOWN = "VALID_REVOCATION_UNKNOWN";
  *
  * The third row is the point: `verifyCertificate` answers VALID there, which
  * reads as "not revoked" and is not something it checked.
+ *
+ * `options` is passed to {@link verifyCertificate} unchanged.
  */
-export async function verifyCertificateWithStatus(crypto, certificate, publicKeys, status, now) {
+export async function verifyCertificateWithStatus(crypto, certificate, publicKeys, status, now, options) {
     // A refusal throws out of verifyCertificate, so `base` is VALID or one of the
     // two soft verdicts. Returning a soft verdict here skipped every check below
     // it: a revoked certificate signed by a compromised-later key answered
     // VALID_KEY_COMPROMISED_LATER and its statement was never authenticated. The
     // verdict is held instead, and resolved against what the statement says.
-    const base = await verifyCertificate(crypto, certificate, publicKeys);
+    const base = await verifyCertificate(crypto, certificate, publicKeys, options);
     if (status == null) {
         return resolveWithBase(base, VALID_REVOCATION_UNKNOWN);
     }
-    const keyId = status.key_id;
+    return resolveWithBase(base, await verifyStatusStatement(crypto, status, publicKeys, certificate.certificate_id, now));
+}
+/**
+ * The statement half of {@link verifyCertificateWithStatus}: authenticate a
+ * status statement about `certificateId` against the published keys, and read
+ * it at `now`. The /verify page's QR lookup has a record id and no record, and
+ * uses this so it shows what a signed, fresh statement says, never what the
+ * status endpoint claims.
+ *
+ * | input | result |
+ * |---|---|
+ * | fresh, REVOKED | throws VerificationError, code CERTIFICATE_REVOKED |
+ * | fresh, ACTIVE | the statement key's verdict: `"VALID"`, or a soft one |
+ * | stale, or a status this SDK does not know | `"VALID_REVOCATION_UNKNOWN"` |
+ * | unknown or unusable key, bad signature, another certificate | throws VerificationError |
+ */
+export async function verifyStatusStatement(crypto, status, publicKeys, certificateId, now) {
+    requireObject(status, "status");
+    const keyId = optionalStringAt(status, "key_id", "status.key_id");
     const info = keyId ? publicKeys.get(keyId) : undefined;
     if (!info) {
         throw new VerificationError(`status statement signed by unknown key: ${keyId}`);
@@ -1363,10 +1604,10 @@ export async function verifyCertificateWithStatus(crypto, certificate, publicKey
     const at = formatTimestamp(when.toISOString());
     const statusKeyVerdict = requireUsableKey(info, parseRfc3339(at), keyId, "status statement key");
     const payload = buildCertificateStatusPayload(status);
-    // decodeSignature, not hexToBytes: signatures arrive as hex, base64 or a byte
+    // decodeFixed, 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);
+    const sig = decodeFixed(status.signature, "status.signature", 64);
     if (!(await crypto.ed25519Verify(info.keyBytes, payload, sig))) {
         throw new VerificationError("status statement signature is invalid");
     }
@@ -1383,8 +1624,7 @@ export async function verifyCertificateWithStatus(crypto, certificate, publicKey
     // Every signature still verified; the binding was the only forged part.
     // core/verify.go never had the fallback, so Go said STATUS_STATEMENT_MISMATCH
     // while both SDKs and the browser bundle said VALID.
-    const certId = certificate.certificate_id;
-    if (status.certificate_id !== certId) {
+    if (status.certificate_id !== certificateId) {
         throw new VerificationError("status statement is about a different certificate");
     }
     // Compared in the normalized form the payload signs, so the freshness check
@@ -1394,7 +1634,7 @@ export async function verifyCertificateWithStatus(crypto, certificate, publicKey
     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 resolveWithBase(base, VALID_REVOCATION_UNKNOWN);
+        return VALID_REVOCATION_UNKNOWN;
     }
     if (status.status === "REVOKED") {
         // Coded, because this is the only status-path rejection that is a fact
@@ -1409,12 +1649,12 @@ export async function verifyCertificateWithStatus(crypto, certificate, publicKey
     // case — was reported as revocation CHECKED AND PASSED. Mirrors
     // core.ValidCertificateStatusValue.
     if (!KNOWN_STATUS_VALUES.has(status.status)) {
-        return resolveWithBase(base, VALID_REVOCATION_UNKNOWN);
+        return VALID_REVOCATION_UNKNOWN;
     }
     // A soft verdict on the status key is the result, not a footnote — but it is
     // reported only once the statement has authenticated and been read, so it can
     // neither speak for an unverified statement nor suppress a revocation.
-    return resolveWithBase(base, statusKeyVerdict);
+    return statusKeyVerdict;
 }
 /**
  * Picks what to report when the certificate's own key returned a soft verdict