burnledger 0.8.1 → 0.9.1

package/src/verify.ts

@@ -18,6 +18,7 @@
 
 import type { CryptoOps } from "./crypto.js";
 import {
+  AUTHORIZATION_POLICY_FAILED,
   CERTIFICATE_REVOKED,
   UNSUPPORTED_ALGORITHM,
   UNSUPPORTED_FORMAT_VERSION,
@@ -74,8 +75,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
@@ -246,25 +248,28 @@ const PAYLOAD_TYPE_LOG_LEAF = "burnledger.log_leaf.v3";
 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: string): Uint8Array {
-  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: number): number {
+function unhex(hex: string, at: number): number {
+  const c = hex.charCodeAt(at);
   // 0-9
   if (c >= 48 && c <= 57) return c - 48;
   // a-f
   if (c >= 97 && c <= 102) return c - 87;
   // 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: Uint8Array): string {
@@ -362,6 +367,13 @@ export async function publicKeyFromHex(
   hexKey: string,
   opts?: PublicKeyOptions,
 ): Promise<PublicKeyInfo> {
+  // 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}`);
@@ -435,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;
@@ -469,8 +493,8 @@ export function evaluateKey(pki: PublicKeyInfo, anchor: number | null): string {
 export function certificateAnchor(certificate: Record<string, unknown>): number | null {
   const transparency = certificate.transparency as Record<string, unknown> | null | undefined;
   if (transparency == null) return null;
-  const sth = transparency.signed_tree_head as Record<string, unknown> | undefined;
-  if (sth === undefined || typeof sth.timestamp !== "string") return null;
+  const sth = transparency.signed_tree_head as Record<string, unknown> | null | undefined;
+  if (sth == null || typeof sth.timestamp !== "string") return null;
   try {
     return parseRfc3339(sth.timestamp);
   } catch {
@@ -479,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,
@@ -501,14 +534,14 @@ 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 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 {
-    const headPayload = buildTreeHeadPayload(sth);
-    const headSig = decodeSignature(sth.signature);
-    if (!(await crypto.ed25519Verify(pki.keyBytes, headPayload, headSig))) return null;
-  } catch {
-    return null;
+    await checkCertificateInclusion(crypto, certificate, pki);
+  } catch (e) {
+    if (e instanceof VerificationError) return null;
+    throw e;
   }
   return anchor;
 }
@@ -559,21 +592,246 @@ function requireUsableKey(
 
 type Cert = Record<string, unknown>;
 
+/**
+ * Require what ADR-025 lets a record prove: that a key group you name signed the
+ * registration the enclave checked each system against before measuring it.
+ *
+ * A pass means each required system is `certified` under one of
+ * `customerKeyIds`, in a record from an enclave image of wire protocol 12 or
+ * later — the first that registers a system only with that key group's
+ * signatures. A record from an earlier image (PRE_PROTOCOL_12_IMAGES), or one
+ * that names no image, fails: those images could say `certified` with no
+ * customer signature at all.
+ *
+ * Off unless asked for, because a record that says `authorization: none` is
+ * still a genuine record. Whoever relays requests to the enclave can always
+ * leave a registration out (ADR-025 §5, §8), and the enclave cannot refuse that
+ * for want of durable state. So "my systems must be certified" can be enforced
+ * in one place only: here, by the party relying on the record.
+ */
+export interface AuthorizationPolicy {
+  /** The system_ids that must be certified. Omitted: every system the record covers. */
+  readonly systems?: readonly string[];
+  /**
+   * The key groups you accept. Required: `certified` under a key id you did not
+   * name proves nothing to you, because the relay can enroll a key group of its
+   * own and the record would name that one.
+   */
+  readonly customerKeyIds: readonly string[];
+}
+
+export interface VerifyOptions {
+  /**
+   * Refuse the record, with a VerificationError whose code is
+   * AUTHORIZATION_POLICY_FAILED, unless it meets this policy. Omitted: no
+   * requirement, and `authorization: none` verifies as it always has.
+   */
+  readonly requireAuthorization?: AuthorizationPolicy;
+}
+
+function policySet(values: readonly string[] | undefined, field: string, lower: boolean): Set<string> | undefined {
+  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)));
+}
+
+interface ParsedPolicy {
+  readonly systems: Set<string> | undefined;
+  readonly customerKeyIds: Set<string>;
+}
+
+/** 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: AuthorizationPolicy): ParsedPolicy {
+  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: ReadonlyMap<string, string> = 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"],
+]);
+
+/**
+ * What a record's signed issuer.enclave_pcr0 makes of `certified`: whether the
+ * image that signed it could mark a system certified without the customer's
+ * signature. "protocol-12-or-later" is the inference the closed list licenses:
+ * a genuine 9.0 record under any other measurement was signed by a later image.
+ */
+export type IssuingImage =
+  | { readonly kind: "unnamed" }
+  | { readonly kind: "before-protocol-12"; readonly name: string; readonly pcr0: string }
+  | { readonly kind: "protocol-12-or-later"; readonly pcr0: string };
+
+export function issuingImage(certificate: Cert): IssuingImage {
+  const issuer = certificate.issuer as Cert | undefined;
+  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: IssuingImage): string {
+  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: Cert, formatVersion: string, policy: ParsedPolicy): void {
+  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 as Record<string, unknown>[] | null | undefined) ?? [];
+  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: Record<string, unknown>): string =>
+    `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 as string)) {
+      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: CryptoOps,
   certificate: Cert,
   publicKeys: Map<string, PublicKeyInfo>,
+  options?: VerifyOptions,
 ): Promise<VerificationResult> {
   // 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.
-  const formatVersion = checkFormatVersion(
-    (certificate as Record<string, unknown>).certificate_format_version,
-  );
+  requireObject(certificate, "certificate");
+  const policy =
+    options?.requireAuthorization === undefined ? undefined : parsePolicy(options.requireAuthorization);
+  const formatVersion = checkFormatVersion(certificate.certificate_format_version);
 
-  const issuer = certificate.issuer as Record<string, unknown>;
+  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.
@@ -587,7 +845,7 @@ export async function verifyCertificate(
       UNSUPPORTED_ALGORITHM,
     );
   }
-  const keyId = issuer.key_id as string;
+  const keyId = stringAt(issuer, "key_id", "issuer.key_id");
 
   const pki = publicKeys.get(keyId);
   if (pki === undefined) throw new VerificationError(`unknown issuer key: ${keyId}`);
@@ -602,7 +860,7 @@ export async function verifyCertificate(
   // 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 as string);
+  const certSig = decodeFixed(certificate.certificate_signature, "certificate_signature", 64);
   if (!(await crypto.ed25519Verify(pki.keyBytes, certPayload, certSig))) {
     throw new VerificationError("certificate signature is invalid");
   }
@@ -621,7 +879,7 @@ export async function verifyCertificate(
     },
     certificate.certificate_format_version as string,
   );
-  const attSig = decodeSignature(att.attestation_signature as string);
+  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");
   }
@@ -682,6 +940,10 @@ export async function verifyCertificate(
     );
   }
 
+  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.
@@ -697,25 +959,41 @@ export async function verifyTransparency(
   certificate: Cert,
   publicKeys: Map<string, PublicKeyInfo>,
 ): Promise<TransparencyResult> {
-  const transparency = certificate.transparency as
-    | Record<string, unknown>
-    | undefined;
-  if (transparency == null) {
+  requireObject(certificate, "certificate");
+  if (certificate.transparency == null) {
     return "NOT_AVAILABLE" as TransparencyResult;
   }
-
-  const sth = transparency.signed_tree_head as Record<string, unknown>;
-  const issuer = certificate.issuer as Record<string, unknown>;
-  const keyId = issuer.key_id as string;
+  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 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 = decodeSignature(sth.signature as string);
+  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");
   }
@@ -731,16 +1009,16 @@ export async function verifyTransparency(
   const issuanceData = issuanceBytes(certificate);
   const leafPayload = buildLogLeafPayload(
     transparency.entry_type,
-    certificate.certificate_id as string,
+    stringAt(certificate, "certificate_id", "certificate_id"),
     await crypto.sha256(issuanceData),
     transparency.appended_at,
   );
   const leaf = await hashLeaf(crypto, leafPayload);
 
-  const proofHashes = (
-    (transparency.inclusion_proof as unknown[] | undefined) ?? []
-  ).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
@@ -782,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -838,48 +1114,96 @@ function canonicalStringify(val: unknown): string {
 }
 
 // ---------------------------------------------------------------------------
-// Byte encoding helpers
+// Reading the document
 // ---------------------------------------------------------------------------
+//
+// A certificate or status statement handed to this verifier is untrusted JSON.
+// A key that is missing, a value of the wrong JSON type or bytes that will not
+// decode is a fact about the DOCUMENT, so every field is read through one of
+// these and refused with a VerificationError naming it. Casting and reading
+// instead threw TypeError from `undefined.x` and a DOMException from atob,
+// which a caller cannot tell apart from a bug in this library (BL-4-001-B).
+//
+// Absent and null are the same thing, as they are to Go's encoding/json.
 
-/** 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: unknown): string {
-  if (Array.isArray(value)) {
-    return bytesToHex(new Uint8Array(value as number[]));
-  }
-  const str = value as string;
-  if (/^[0-9a-fA-F]+$/.test(str) && str.length % 2 === 0) {
-    return str.toLowerCase();
+type Doc = Record<string, unknown>;
+
+function requireObject(value: unknown, path: string): Doc {
+  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`);
   }
-  return bytesToHex(base64ToBytes(str));
+  return value as Doc;
 }
 
-/** Decode a signature field to raw bytes. Same format handling as toHex. */
-function decodeSignature(value: unknown): Uint8Array {
-  if (Array.isArray(value)) {
-    return new Uint8Array(value as number[]);
-  }
-  const str = value as string;
-  if (/^[0-9a-fA-F]+$/.test(str)) {
-    const raw = hexToBytes(str);
-    if (raw.length === 64) return raw;
-  }
-  return base64ToBytes(str);
+function objectAt(parent: Doc, key: string, path: string): Doc {
+  return requireObject(parent[key], path);
 }
 
-/** Decode a hash/bytes field to raw bytes. Same format handling as toHex. */
-function decodeBytes(value: unknown): Uint8Array {
+function stringAt(parent: Doc, key: string, path: string): string {
+  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: Doc, key: string, path: string): string | undefined {
+  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;
+}
+
+/**
+ * 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: Doc, key: string, path: string): unknown[] {
+  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: unknown, path: string, length: number): Uint8Array {
+  if (value === undefined || value === null) throw new VerificationError(`${path} is missing`);
+  let raw: Uint8Array;
   if (Array.isArray(value)) {
-    return new Uint8Array(value as number[]);
+    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 as number[]);
+  } 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`);
+  } else {
+    throw new VerificationError(`${path} is not a byte string`);
   }
-  const str = value as string;
-  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
@@ -912,13 +1236,16 @@ const RFC3339_RE =
  * 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: unknown): string {
+export function formatTimestamp(ts: unknown, field = "timestamp"): string {
   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.
@@ -930,19 +1257,19 @@ export function formatTimestamp(ts: unknown): string {
  * `+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: string): number {
+function parseRfc3339(ts: string, field = "timestamp"): number {
   const m = RFC3339_RE.exec(ts);
-  if (m === null) throw new VerificationError(`timestamp is not RFC 3339: ${ts}`);
+  if (m === null) 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)) as [number, number, number, number, number, number];
 
-  if (month < 1 || month > 12) throw new VerificationError(`timestamp month out of range: ${ts}`);
+  if (month < 1 || month > 12) 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;
@@ -950,8 +1277,8 @@ function parseRfc3339(ts: string): number {
   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}`);
+    if (offHour > 24) throw new VerificationError(`${field} zone offset hour out of range: ${ts}`);
+    if (offMin > 60) throw new VerificationError(`${field} zone offset minute out of range: ${ts}`);
     offset = (offHour * 3600 + offMin * 60) * (sign === "-" ? -1 : 1);
   }
 
@@ -1051,17 +1378,18 @@ function buildAttestationPayload(
   // payload and call every genuine v8 record a forgery.
   const coversMeasured = signatureCoversMeasuredTransport(certFormatVersion);
   const coversRecoverable = signatureCoversRecoverableState(certFormatVersion);
-  const systems = (att.systems as Record<string, unknown>[]).map((s) => {
+  const systems = (att.systems as Record<string, unknown>[]).map((s, i) => {
     const sys: Record<string, unknown> = {
       canonical_version: (s.canonical_version as string | null) ?? null,
       connector_type: s.connector_type as string,
       hash_scope: s.hash_scope as string,
-      merkle_root: s.merkle_root
-        ? toHex(s.merkle_root as string)
-        : 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 as string),
+      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 as number,
       system_id: s.system_id as string,
       system_name: s.system_name as string,
@@ -1095,7 +1423,7 @@ function buildAttestationPayload(
     attested_at: attestedAt,
     payload_type: attestationPayloadType(certFormatVersion),
     proof_mode: att.proof_mode as string,
-    subject_hash: toHex(subject.identifier_hash as string),
+    subject_hash: bytesToHex(decodeFixed(subject.identifier_hash, "subject.identifier_hash", 32)),
     systems,
   };
   return canonicalJson(payload);
@@ -1161,9 +1489,9 @@ function attestationPayloadType(version: string): string {
 }
 
 function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
-  const att = cert.attestation as Record<string, unknown>;
-  const issuer = cert.issuer as Record<string, unknown>;
-  const subject = cert.subject as Record<string, unknown>;
+  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,
@@ -1172,19 +1500,27 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   const coversMeasured = signatureCoversMeasuredTransport(version);
   const coversRecoverable = signatureCoversRecoverableState(version);
   const coversAuthorization = signatureCoversAuthorization(version);
-  const systems = ((cert.systems as Record<string, unknown>[]) ?? []).map((s) => {
+  const systems = arrayAt(cert, "systems", "systems").map((entry, i) => {
+    const where = `systems[${i}]`;
+    const s = requireObject(entry, where);
     const sys: Record<string, unknown> = {
-      attested_at: formatTimestamp(s.attested_at),
-      attested_count: s.attested_count as number,
-      canonical_version: (s.canonical_version as string | null) ?? null,
-      connector_type: s.connector_type as string,
-      hash_scope: s.hash_scope as string,
-      merkle_root: s.merkle_root ? toHex(s.merkle_root as string) : null,
-      query_hash: toHex(s.query_hash as string),
-      system_id: s.system_id as string,
-      system_name: s.system_name as string,
-      verified_at: formatTimestamp(s.verified_at),
-      verified_count: s.verified_count as number,
+      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(
@@ -1219,9 +1555,11 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   // 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 as string),
-    attested_at: formatTimestamp(att.attested_at),
-    proof_mode: att.proof_mode as string,
+    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
@@ -1235,9 +1573,9 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   const isV4Plus = formatAtLeast(version, FORMAT_VERSION_V4);
 
   const issuerObj: Record<string, unknown> = {
-    key_id: issuer.key_id as string,
-    name: issuer.name as string,
-    public_key: toHex(issuer.public_key as string),
+    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,
@@ -1250,26 +1588,31 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
       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: Record<string, unknown> = {
-    identifier_hash: toHex(subject.identifier_hash as string),
+    identifier_hash: bytesToHex(decodeFixed(subject.identifier_hash, "subject.identifier_hash", 32)),
   };
   if (!isV5Plus) {
-    subjectObj.identifier_type_hint = subject.identifier_type_hint as string;
+    subjectObj.identifier_type_hint = stringAt(
+      subject,
+      "identifier_type_hint",
+      "subject.identifier_type_hint",
+    );
   }
 
   // status and revocation are deliberately absent (ADR-016 §3): a signature
@@ -1277,20 +1620,20 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   // travels as a separate short-lived signed status statement.
   const payload: Record<string, unknown> = {
     attestation: attObj,
-    attestation_id: cert.attestation_id as string,
-    certificate_format_version: cert.certificate_format_version as string,
-    certificate_id: cert.certificate_id as string,
-    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 as Record<string, unknown>;
+    const scope = objectAt(cert, "scope", "scope");
     payload.scope = {
-      text_sha256: toHex(scope.text_sha256 as string),
-      version: scope.version as string,
+      text_sha256: bytesToHex(decodeFixed(scope.text_sha256, "scope.text_sha256", 32)),
+      version: stringAt(scope, "version", "scope.version"),
     };
   }
   return canonicalJson(payload);
@@ -1307,7 +1650,7 @@ function buildLogLeafPayload(
     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,
@@ -1358,13 +1701,13 @@ function attestationSystems(cert: Record<string, unknown>): Record<string, unkno
  * between two modules of this package, not published surface.
  */
 export function buildTreeHeadPayload(head: Record<string, unknown>): Uint8Array {
-  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: Record<string, unknown> = {
     payload_type: named ? PAYLOAD_TYPE_TREE_HEAD_V7 : PAYLOAD_TYPE_TREE_HEAD,
-    root_hash: toHex(head.root_hash as string),
-    timestamp: formatTimestamp(head.timestamp),
-    tree_size: head.tree_size as number,
+    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;
   return canonicalJson(payload);
@@ -1450,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).
@@ -1487,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
@@ -1504,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);
@@ -1535,21 +1888,24 @@ export function buildCertificateStatusPayload(
 ): Uint8Array {
   const payload: Record<string, unknown> = {
     payload_type: PAYLOAD_TYPE_CERTIFICATE_STATUS,
-    certificate_id: stmt.certificate_id as string,
-    statement_expires_at: formatTimestamp(stmt.statement_expires_at),
-    statement_issued_at: formatTimestamp(stmt.statement_issued_at),
-    status: stmt.status as string,
-    sth_root_hash: toHex(stmt.sth_root_hash as string),
-    sth_tree_size: stmt.sth_tree_size as number,
+    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 as string;
-  }
+  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 as number;
+    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);
 }
@@ -1582,7 +1938,7 @@ export function buildKeyListPayload(doc: Record<string, unknown>): Uint8Array {
     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 as string),
+    sth_root_hash: bytesToHex(decodeFixed(doc.sth_root_hash, "sth_root_hash", 32)),
     sth_tree_size: doc.sth_tree_size as number,
   };
   return canonicalJson(payload);
@@ -1610,6 +1966,8 @@ 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: CryptoOps,
@@ -1617,18 +1975,49 @@ export async function verifyCertificateWithStatus(
   publicKeys: Map<string, PublicKeyInfo>,
   status?: Record<string, unknown> | null,
   now?: Date,
+  options?: VerifyOptions,
 ): Promise<string> {
   // 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 as string | undefined;
+  return resolveWithBase(
+    base,
+    await verifyStatusStatement(
+      crypto, status, publicKeys, (certificate as Record<string, unknown>).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: CryptoOps,
+  status: Record<string, unknown>,
+  publicKeys: Map<string, PublicKeyInfo>,
+  certificateId: unknown,
+  now?: Date,
+): Promise<string> {
+  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}`);
@@ -1656,10 +2045,10 @@ export async function verifyCertificateWithStatus(
   );
 
   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");
   }
@@ -1677,8 +2066,7 @@ export async function verifyCertificateWithStatus(
   // 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 as Record<string, unknown>).certificate_id;
-  if (status.certificate_id !== certId) {
+  if (status.certificate_id !== certificateId) {
     throw new VerificationError("status statement is about a different certificate");
   }
 
@@ -1689,7 +2077,7 @@ export async function verifyCertificateWithStatus(
   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") {
@@ -1705,12 +2093,12 @@ export async function verifyCertificateWithStatus(
   // case — was reported as revocation CHECKED AND PASSED. Mirrors
   // core.ValidCertificateStatusValue.
   if (!KNOWN_STATUS_VALUES.has(status.status as string)) {
-    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;
 }
 
 /**