burnledger 0.2.2 → 0.3.0

package/src/verify.ts

@@ -0,0 +1,956 @@
+/** Offline certificate and transparency verification.
+ *
+ * Ports the Go signing payload builders (core/payload.go) and Merkle tree
+ * verification (core/merkle.go) to TypeScript. All crypto is delegated to
+ * a CryptoOps provider (Node or browser).
+ *
+ * Critical encoding details:
+ *   - Go's json.Marshal encodes []byte as base64, [N]byte as number arrays.
+ *   - The payload builders normalize both formats to lowercase hex strings.
+ *   - Timestamps in payloads use second-precision UTC: "YYYY-MM-DDTHH:MM:SSZ".
+ *   - RFC 8785 canonical JSON: sorted keys recursively, no whitespace.
+ *   - Transparency leaf = SHA-256(0x00 || logLeafPayload), where the payload
+ *     commits to entry_type, certificate_id, SHA-256(issuanceBytes(cert)) and
+ *     appended_at (ADR-016 §4). NOT the
+ *     certificate signing payload. issuanceBytes reconstructs json.Marshal
+ *     output at issuance time (transparency_status=PENDING, no transparency).
+ */
+
+import type { CryptoOps } from "./crypto.js";
+import { VerificationError } from "./errors.js";
+import type { TransparencyResult, VerificationResult } from "./models.js";
+
+// ---------------------------------------------------------------------------
+// Pure byte helpers (no Buffer, no node:crypto)
+// ---------------------------------------------------------------------------
+
+const HEX_CHARS = "0123456789abcdef";
+
+// Signing-format v2 domain-separation tags (CR-H01). Must match the
+// source-of-truth const block in Go's core/payload.go byte-for-byte.
+const PAYLOAD_TYPE_ATTESTATION = "burnledger.attestation.v3";
+const PAYLOAD_TYPE_CERTIFICATE = "burnledger.certificate.v3";
+const PAYLOAD_TYPE_TREE_HEAD = "burnledger.sth.v3";
+const PAYLOAD_TYPE_LOG_LEAF = "burnledger.log_leaf.v3";
+// There is deliberately no verification payload type: v3 produces those facts
+// in the same enclave call that signs the certificate (ADR-016 §2).
+const PAYLOAD_TYPE_CERTIFICATE_STATUS = "burnledger.certificate_status.v3";
+
+export function hexToBytes(hex: 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);
+  }
+  return out;
+}
+
+function unhex(c: number): number {
+  // 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;
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i]!;
+    out += HEX_CHARS[b >>> 4];
+    out += HEX_CHARS[b & 0x0f];
+  }
+  return out;
+}
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+function base64ToBytes(b64: string): Uint8Array {
+  // Use atob for universal browser+node compatibility.
+  // Node 18+ has atob globally; browsers always have it.
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) {
+    out[i] = bin.charCodeAt(i);
+  }
+  return out;
+}
+
+function textToBytes(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+// ---------------------------------------------------------------------------
+// Public key info
+// ---------------------------------------------------------------------------
+
+export interface PublicKeyInfo {
+  readonly keyBytes: Uint8Array;
+  readonly keyId: string;
+  readonly revoked: boolean;
+}
+
+export async function publicKeyFromHex(
+  crypto: CryptoOps,
+  hexKey: string,
+  opts?: { revoked?: boolean },
+): Promise<PublicKeyInfo> {
+  const raw = hexToBytes(hexKey);
+  if (raw.length !== 32) {
+    throw new VerificationError(`public key must be 32 bytes, got ${raw.length}`);
+  }
+  const hash = await crypto.sha256(raw);
+  const keyId = "dp_k_" + bytesToHex(hash);
+  return { keyBytes: raw, keyId, revoked: opts?.revoked ?? false };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+type Cert = Record<string, unknown>;
+
+/** Verify all signatures on a deletion certificate offline. */
+export async function verifyCertificate(
+  crypto: CryptoOps,
+  certificate: Cert,
+  publicKeys: Map<string, PublicKeyInfo>,
+): Promise<VerificationResult> {
+  const issuer = certificate.issuer as Record<string, unknown>;
+  const keyId = issuer.key_id as string;
+
+  const pki = publicKeys.get(keyId);
+  if (pki === undefined) throw new VerificationError(`unknown issuer key: ${keyId}`);
+  if (pki.revoked) throw new VerificationError(`issuer key is revoked: ${keyId}`);
+
+  // 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);
+  if (!(await crypto.ed25519Verify(pki.keyBytes, certPayload, certSig))) {
+    throw new VerificationError("certificate signature is invalid");
+  }
+
+  // 2. Attestation signature, rebuilt from the merged list. There is no
+  // verification signature: those facts are produced in the same enclave call
+  // that signs the certificate, so certificate_signature already covers them
+  // (ADR-016 §2).
+  const att = certificate.attestation as Record<string, unknown>;
+  const attPayload = buildAttestationPayload(
+    certificate.subject as Record<string, unknown>,
+    {
+      proof_mode: att.proof_mode,
+      attested_at: att.attested_at,
+      systems: attestationSystems(certificate),
+    },
+  );
+  const attSig = decodeSignature(att.attestation_signature as string);
+  if (!(await crypto.ed25519Verify(pki.keyBytes, attPayload, attSig))) {
+    throw new VerificationError("attestation signature is invalid");
+  }
+
+  // 3. Structural rules on the system set.
+  //
+  // v2 carried two lists joined on the human-editable system_name, so "attested
+  // but not verified" was a representable state that had to be caught by a
+  // check — and for a long time was not (#451). v3 carries one list keyed by
+  // system_id, which makes that state unexpressible. What remains is
+  // structural, and mirrors core/verify.go step 4.
+  const systems = (certificate.systems as Record<string, unknown>[]) ?? [];
+  if (systems.length === 0) {
+    throw new VerificationError("certificate attests no systems, so it asserts nothing");
+  }
+
+  const seen = new Set<string>();
+  let anyAttested = false;
+  for (const s of systems) {
+    const systemId = s.system_id as string | undefined;
+    if (!systemId || systemId === NIL_UUID) {
+      throw new VerificationError("malformed systems: a system carries no system_id");
+    }
+    if (seen.has(systemId)) {
+      // Duplicate ids would let one verification stand in for several systems,
+      // which is the v2 hole in a new costume.
+      throw new VerificationError(`malformed systems: duplicate system_id ${systemId}`);
+    }
+    seen.add(systemId);
+
+    const attestedAt = parseRfc3339(s.attested_at as string);
+    const verifiedAt = parseRfc3339(s.verified_at as string);
+    if (verifiedAt < attestedAt) {
+      throw new VerificationError(
+        `malformed systems: system ${systemId} was verified before it was attested`,
+      );
+    }
+
+    if ((s.attested_count as number) > 0) anyAttested = true;
+  }
+
+  // 4. Nothing may remain anywhere.
+  for (const s of systems) {
+    const remaining = s.verified_count as number;
+    if (remaining !== 0) {
+      throw new VerificationError(
+        `data still present: system "${s.system_name as string}" reports ${remaining} record(s)`,
+      );
+    }
+  }
+
+  // 5. At least one system must have held records at attest time — across the
+  // set, not per system. Every system reporting zero means the certificate
+  // documents the deletion of nothing.
+  if (!anyAttested) {
+    throw new VerificationError(
+      "incomplete verification: no system held any records at attestation time",
+    );
+  }
+
+  return "VALID" as VerificationResult;
+}
+
+const NIL_UUID = "00000000-0000-0000-0000-000000000000";
+
+
+/** Verify the transparency proof embedded in a certificate. */
+export async function verifyTransparency(
+  crypto: CryptoOps,
+  certificate: Cert,
+  publicKeys: Map<string, PublicKeyInfo>,
+): Promise<TransparencyResult> {
+  const transparency = certificate.transparency as
+    | Record<string, unknown>
+    | undefined;
+  if (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 pki = publicKeys.get(keyId);
+  if (pki === undefined) throw new VerificationError(`unknown issuer key: ${keyId}`);
+  if (pki.revoked) throw new VerificationError(`issuer key is revoked: ${keyId}`);
+
+  // 1. Tree head signature
+  const headPayload = buildTreeHeadPayload(sth);
+  const headSig = decodeSignature(sth.signature as string);
+  if (!(await crypto.ed25519Verify(pki.keyBytes, headPayload, headSig))) {
+    throw new VerificationError("tree head signature is invalid");
+  }
+
+  // 2. Merkle inclusion proof.
+  //
+  // The leaf is NOT the certificate. It is the canonical log_leaf.v3 payload
+  // over entry_type, certificate_id, certificate_hash and appended_at, where
+  // certificate_hash is SHA-256 of the issuance-time certificate JSON
+  // (ADR-016 §4). v2 hashed the certificate directly, so an issuance and a
+  // revocation of the same certificate produced identical leaves and the tree
+  // committed to neither the entry type nor when it happened.
+  const issuanceData = issuanceBytes(certificate);
+  const leafPayload = buildLogLeafPayload(
+    transparency.entry_type,
+    certificate.certificate_id as string,
+    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);
+  // `?? 0` is not a convenience: encoding/json leaves 0 in Go's uint64 fields
+  // for an explicit null and for an absent key rather than failing, so refusing
+  // either would reject documents the reference accepts — the same class of
+  // divergence as #452. An offline verifier is only useful while it agrees.
+  const index = requireUint(transparency.entry_index ?? 0, "entry_index");
+  const treeSize = requireUint(sth.tree_size ?? 0, "signed_tree_head.tree_size");
+
+  // transparency.tree_size duplicates the signed one but carries no signature:
+  // BuildTreeHeadPayload covers only the copy inside signed_tree_head. Go used
+  // to verify against the unsigned copy while this SDK used the signed one, so
+  // the same document got two verdicts (#456). Both now require the two to agree
+  // and then verify against the signed copy — the server always writes them
+  // equal, so this rejects only edited documents.
+  const unsignedSize = requireUint(
+    transparency.tree_size ?? 0,
+    "transparency.tree_size",
+  );
+  if (unsignedSize !== treeSize) {
+    throw new VerificationError(
+      `transparency.tree_size (${unsignedSize}) does not match the signed tree head ` +
+        `(${treeSize}); it is not covered by any signature`,
+    );
+  }
+
+  if (!(await verifyInclusion(crypto, leaf, index, treeSize, proofHashes, root))) {
+    throw new VerificationError("merkle inclusion proof is invalid");
+  }
+
+  return "INCLUDED" as TransparencyResult;
+}
+
+// ---------------------------------------------------------------------------
+// Issuance bytes — matches Go's core.IssuanceBytes(cert)
+// ---------------------------------------------------------------------------
+
+/** Reconstruct the certificate JSON as it existed at issuance time.
+ *
+ * At issuance: transparency_status = "PENDING", transparency = nil (omitted).
+ * The leaf preimage is the RFC 8785 canonical JSON of that form — exactly
+ * Go's `CanonicalJSON(json.Marshal(cert))` in core.IssuanceBytes. It MUST be
+ * canonicalized (sorted keys, recursively), not serialized in insertion order:
+ * Go's struct field order is not alphabetical, so insertion-order stringify
+ * produces a different leaf hash and every genuine certificate fails inclusion
+ * verification (#C-01).
+ */
+export function issuanceBytes(certificate: Cert): Uint8Array {
+  const clone = JSON.parse(JSON.stringify(certificate)) as Record<string, unknown>;
+  clone.transparency_status = "PENDING";
+  delete clone.transparency;
+  return canonicalJson(clone);
+}
+
+// ---------------------------------------------------------------------------
+// RFC 8785 Canonical JSON
+// ---------------------------------------------------------------------------
+
+function canonicalJson(obj: unknown): Uint8Array {
+  return textToBytes(canonicalStringify(obj));
+}
+
+function canonicalStringify(val: unknown): string {
+  if (val === null || val === undefined) return "null";
+  if (typeof val === "boolean") return val ? "true" : "false";
+  if (typeof val === "number") return JSON.stringify(val);
+  if (typeof val === "string") return JSON.stringify(val);
+  if (Array.isArray(val)) {
+    return "[" + val.map(canonicalStringify).join(",") + "]";
+  }
+  if (typeof val === "object") {
+    const obj = val as Record<string, unknown>;
+    const keys = Object.keys(obj).sort();
+    const pairs = keys.map(
+      (k) => JSON.stringify(k) + ":" + canonicalStringify(obj[k]),
+    );
+    return "{" + pairs.join(",") + "}";
+  }
+  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: 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();
+  }
+  return bytesToHex(base64ToBytes(str));
+}
+
+/** 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);
+}
+
+/** Decode a hash/bytes field to raw bytes. Same format handling as toHex. */
+function decodeBytes(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) && str.length % 2 === 0) {
+    return hexToBytes(str);
+  }
+  return base64ToBytes(str);
+}
+
+/** Go's zero time.Time — what encoding/json leaves in a non-pointer time.Time
+ *  field for an explicit JSON null or an absent key. */
+const ZERO_INSTANT = "0001-01-01T00:00:00Z";
+
+/** The grammar encoding/json accepts for time.Time: strict RFC 3339, uppercase
+ *  "T" and "Z" only, fixed field widths, at least one fractional digit if a "."
+ *  is present. Anything else makes Go fail to parse the certificate at all. */
+const RFC3339_RE =
+  /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|([+-])(\d{2}):(\d{2}))$/;
+
+/** Normalize a certificate timestamp to the UTC form Go signs.
+ *
+ * Go builds every payload timestamp as `t.UTC().Format("2006-01-02T15:04:05Z")`
+ * (core/payload.go) on a value encoding/json already parsed as strict RFC 3339.
+ * This reproduces both halves — the same acceptance rules and the same
+ * conversion — because the two are one contract, not two.
+ *
+ * It must convert, never truncate. `12:00:00+05:00` and `12:00:00Z` are six
+ * hours apart; treating them as the same string made this verifier accept a
+ * certificate whose attestation window had been re-labelled to a different
+ * instant, and reject genuine certificates issued by a server on local time
+ * (#452). Input Go would refuse to parse is refused here rather than
+ * string-surgered into something that verifies.
+ *
+ * `null`/`undefined` — an explicit JSON null, or a key Go's struct has and the
+ * document does not — is Go's zero time, not an error.
+ *
+ * Exported from this module so the timestamp_vectors.json suite can diff it
+ * against Go directly. It is deliberately not re-exported from index.ts, so it
+ * is not part of the published package surface.
+ */
+export function formatTimestamp(ts: unknown): string {
+  if (ts === null || ts === undefined) return ZERO_INSTANT;
+  if (typeof ts !== "string") {
+    throw new VerificationError(`timestamp is not a string: ${JSON.stringify(ts)}`);
+  }
+  return formatEpochSeconds(parseRfc3339(ts));
+}
+
+/** Parse a strict RFC 3339 timestamp to seconds since 1970-01-01T00:00:00Z.
+ *
+ * Rejects exactly what Go's encoding/json rejects, including the ranges its
+ * parser enforces once the shape matches. Those ranges were measured against
+ * Go 1.26, not inferred from RFC 3339, and they are not the obvious ones: the
+ * time of day is 23:59:59 at most, but a zone offset runs to +24:60 — both
+ * `+24:00` and `+00:60` parse, while `+25:00` and `+00:61` do not. Sub-second
+ * digits are dropped, matching Format's truncation.
+ */
+function parseRfc3339(ts: string): number {
+  const m = RFC3339_RE.exec(ts);
+  if (m === null) throw new VerificationError(`timestamp is not RFC 3339: ${ts}`);
+  const [year, month, day, hour, minute, second] = m
+    .slice(1, 7)
+    .map((v) => Number.parseInt(v!, 10)) as [number, number, number, number, number, number];
+
+  if (month < 1 || month > 12) throw new VerificationError(`timestamp month out of range: ${ts}`);
+  if (day < 1 || day > daysInMonth(year, month)) {
+    throw new VerificationError(`timestamp day out of range: ${ts}`);
+  }
+  if (hour > 23 || minute > 59 || second > 59) {
+    throw new VerificationError(`timestamp time of day out of range: ${ts}`);
+  }
+
+  let offset = 0;
+  const sign = m[7];
+  if (sign !== undefined) {
+    const offHour = Number.parseInt(m[8]!, 10);
+    const offMin = Number.parseInt(m[9]!, 10);
+    if (offHour > 24) throw new VerificationError(`timestamp zone offset hour out of range: ${ts}`);
+    if (offMin > 60) throw new VerificationError(`timestamp zone offset minute out of range: ${ts}`);
+    offset = (offHour * 3600 + offMin * 60) * (sign === "-" ? -1 : 1);
+  }
+
+  return daysFromCivil(year, month, day) * 86400 + hour * 3600 + minute * 60 + second - offset;
+}
+
+/** Render seconds since the Unix epoch as `YYYY-MM-DDTHH:MM:SSZ`.
+ *
+ * Matches Go's Format for the reachable extremes: a year 0000 timestamp with a
+ * `+24:00` offset lands in year -1, which Go prints as `-0001`, and 9999-12-31
+ * with `-24:00` lands in year 10000, which Go prints unpadded.
+ */
+function formatEpochSeconds(total: number): string {
+  const days = Math.floor(total / 86400);
+  const secs = total - days * 86400;
+  const [year, month, day] = civilFromDays(days);
+  const hour = Math.floor(secs / 3600);
+  const minute = Math.floor((secs - hour * 3600) / 60);
+  const second = secs - hour * 3600 - minute * 60;
+  const printedYear = year < 0 ? "-" + pad(-year, 4) : pad(year, 4);
+  return `${printedYear}-${pad(month, 2)}-${pad(day, 2)}T${pad(hour, 2)}:${pad(minute, 2)}:${pad(second, 2)}Z`;
+}
+
+function pad(value: number, width: number): string {
+  return String(value).padStart(width, "0");
+}
+
+/** Length of a proleptic Gregorian month. Year 0 is a leap year; 1900 is not. */
+function daysInMonth(year: number, month: number): number {
+  if (month === 2) {
+    const isLeap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    return isLeap ? 29 : 28;
+  }
+  return month === 4 || month === 6 || month === 9 || month === 11 ? 30 : 31;
+}
+
+/** Days from 1970-01-01 to a proleptic Gregorian date (Howard Hinnant's algorithm).
+ *
+ * Deliberately not `Date`: Go accepts year 0000, and a zone offset can push the
+ * UTC instant to year -1 or 10000, where `Date`'s parsing and formatting stop
+ * agreeing with Go. A verifier that disagrees with the reference on any input is
+ * a verifier a relying party cannot use to second-guess the reference.
+ */
+function daysFromCivil(year: number, month: number, day: number): number {
+  const y = month <= 2 ? year - 1 : year;
+  const era = Math.floor(y / 400);
+  const yearOfEra = y - era * 400; // [0, 399]
+  const shiftedMonth = month > 2 ? month - 3 : month + 9; // [0, 11]
+  const dayOfYear = Math.floor((153 * shiftedMonth + 2) / 5) + day - 1; // [0, 365]
+  const dayOfEra =
+    yearOfEra * 365 +
+    Math.floor(yearOfEra / 4) -
+    Math.floor(yearOfEra / 100) +
+    dayOfYear;
+  return era * 146097 + dayOfEra - 719468;
+}
+
+/** Inverse of daysFromCivil. */
+function civilFromDays(days: number): [number, number, number] {
+  const z = days + 719468;
+  const era = Math.floor(z / 146097);
+  const dayOfEra = z - era * 146097; // [0, 146096]
+  const yearOfEra = Math.floor(
+    (dayOfEra -
+      Math.floor(dayOfEra / 1460) +
+      Math.floor(dayOfEra / 36524) -
+      Math.floor(dayOfEra / 146096)) /
+      365,
+  ); // [0, 399]
+  const dayOfYear =
+    dayOfEra -
+    (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100)); // [0, 365]
+  const shiftedMonth = Math.floor((5 * dayOfYear + 2) / 153); // [0, 11]
+  const day = dayOfYear - Math.floor((153 * shiftedMonth + 2) / 5) + 1;
+  const month = shiftedMonth < 10 ? shiftedMonth + 3 : shiftedMonth - 9;
+  const year = yearOfEra + era * 400 + (month <= 2 ? 1 : 0);
+  return [year, month, day];
+}
+
+// ---------------------------------------------------------------------------
+// Payload builders — exact ports of core/payload.go
+// ---------------------------------------------------------------------------
+
+function buildAttestationPayload(
+  subject: Record<string, unknown>,
+  att: Record<string, unknown>,
+): Uint8Array {
+  const attestedAt = formatTimestamp(att.attested_at);
+  const systems = (att.systems as Record<string, unknown>[]).map((s) => ({
+    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,
+    // The system's own observation time, not the envelope's.
+    observed_at: formatTimestamp(s.observed_at),
+    query_hash: toHex(s.query_hash as string),
+    record_count: s.record_count as number,
+    system_id: s.system_id as string,
+    system_name: s.system_name as string,
+  }));
+
+  const payload = {
+    attested_at: attestedAt,
+    payload_type: PAYLOAD_TYPE_ATTESTATION,
+    proof_mode: att.proof_mode as string,
+    subject_hash: toHex(subject.identifier_hash as string),
+    systems,
+  };
+  return canonicalJson(payload);
+}
+
+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>;
+
+  // One list, keyed by system_id (ADR-016 §2). v2 signed an attestation list
+  // and a verification list joined only on the human-editable system_name,
+  // which made a partial deletion indistinguishable from a complete one.
+  const systems = ((cert.systems as Record<string, unknown>[]) ?? []).map((s) => ({
+    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,
+  }));
+
+  // 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,
+  };
+
+  const issuerObj = {
+    key_id: issuer.key_id as string,
+    name: issuer.name as string,
+    public_key: toHex(issuer.public_key as string),
+  };
+
+  const subjectObj = {
+    identifier_hash: toHex(subject.identifier_hash as string),
+    identifier_type_hint: subject.identifier_type_hint as string,
+  };
+
+  // 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 as string,
+    certificate_format_version: cert.certificate_format_version as string,
+    certificate_id: cert.certificate_id as string,
+    issued_at: formatTimestamp(cert.issued_at),
+    issuer: issuerObj,
+    payload_type: PAYLOAD_TYPE_CERTIFICATE,
+    subject: subjectObj,
+    systems,
+  };
+  return canonicalJson(payload);
+}
+
+/** Port of Go's BuildLogLeafPayload (ADR-016 §4). */
+function buildLogLeafPayload(
+  entryType: unknown,
+  certificateId: string,
+  certificateHash: Uint8Array,
+  appendedAt: unknown,
+): Uint8Array {
+  if (entryType !== "CERTIFICATE" && entryType !== "REVOCATION") {
+    throw new VerificationError(`invalid log entry_type: ${String(entryType)}`);
+  }
+  const payload = {
+    appended_at: formatTimestamp(appendedAt),
+    certificate_hash: bytesToHex(certificateHash),
+    certificate_id: certificateId,
+    entry_type: entryType,
+    payload_type: PAYLOAD_TYPE_LOG_LEAF,
+  };
+  return canonicalJson(payload);
+}
+
+/**
+ * Project the merged system list back onto the attest-time shape, so the
+ * attestation signature — produced days before the certificate existed — can be
+ * checked. Mirrors DeletionCertificate.AttestationSystems() in Go.
+ */
+function attestationSystems(cert: Record<string, unknown>): Record<string, unknown>[] {
+  return ((cert.systems as Record<string, unknown>[]) ?? []).map((s) => ({
+    system_id: s.system_id,
+    system_name: s.system_name,
+    connector_type: s.connector_type,
+    hash_scope: s.hash_scope,
+    query_hash: s.query_hash,
+    record_count: s.attested_count,
+    observed_at: s.attested_at,
+    merkle_root: s.merkle_root,
+    canonical_version: s.canonical_version,
+  }));
+}
+
+function buildTreeHeadPayload(head: Record<string, unknown>): Uint8Array {
+  const payload = {
+    payload_type: PAYLOAD_TYPE_TREE_HEAD,
+    root_hash: toHex(head.root_hash as string),
+    timestamp: formatTimestamp(head.timestamp),
+    tree_size: head.tree_size as number,
+  };
+  return canonicalJson(payload);
+}
+
+// ---------------------------------------------------------------------------
+// Merkle tree (RFC 6962) — ports of core/merkle.go
+// ---------------------------------------------------------------------------
+
+async function hashLeaf(crypto: CryptoOps, data: Uint8Array): Promise<Uint8Array> {
+  return crypto.sha256(concatBytes(new Uint8Array([0x00]), data));
+}
+
+async function hashNode(crypto: CryptoOps, left: Uint8Array, right: Uint8Array): Promise<Uint8Array> {
+  const prefix = new Uint8Array([0x01]);
+  return crypto.sha256(concatBytes(prefix, concatBytes(left, right)));
+}
+
+/** Read a tree index or size the way Go's uint64 unmarshalling does.
+ *
+ * Go's struct fields are uint64, so a negative or fractional JSON number makes
+ * the whole certificate fail to parse, and the `index >= size` guard in
+ * verifyInclusion never sees one. This SDK gets a JavaScript number, where that
+ * guard passes a negative index straight through and any value past 2^53 has
+ * already lost the precision the Merkle arithmetic depends on (#456). Both are
+ * rejected here, at the document boundary, rather than trusted downstream.
+ */
+function requireUint(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+    throw new VerificationError(
+      `${field} is not an exact non-negative integer: ${JSON.stringify(value)}`,
+    );
+  }
+  if (value < 0) throw new VerificationError(`${field} is negative: ${value}`);
+  return value;
+}
+
+/** Largest power of 2 strictly less than n. Port of Go's splitPoint.
+ *
+ * The loop terminates because requireUint has already bounded n to a safe
+ * integer; Go, which has no such bound, computes the same value with
+ * `1 << (bits.Len64(n-1) - 1)` because its loop form overflowed (#456).
+ */
+function splitPoint(n: number): number {
+  let k = 1;
+  while (k * 2 < n) {
+    k *= 2;
+  }
+  return k;
+}
+
+async function verifyInclusion(
+  crypto: CryptoOps,
+  leaf: Uint8Array,
+  index: number,
+  size: number,
+  proof: Uint8Array[],
+  root: Uint8Array,
+): Promise<boolean> {
+  if (size === 0 || index >= size) return false;
+  if (size === 1) return proof.length === 0 && bytesEqual(leaf, root);
+  const [computed, consumed] = await chainInclusion(crypto, leaf, index, size, proof);
+  return consumed === proof.length && bytesEqual(computed, root);
+}
+
+async function chainInclusion(
+  crypto: CryptoOps,
+  leaf: Uint8Array,
+  index: number,
+  n: number,
+  proof: Uint8Array[],
+): Promise<[Uint8Array, number]> {
+  if (n === 1) return [leaf, 0];
+  const k = splitPoint(n);
+  if (index < k) {
+    const [inner, used] = await chainInclusion(crypto, leaf, index, k, proof);
+    if (used >= proof.length) return [inner, used + 1];
+    return [await hashNode(crypto, inner, proof[used]!), used + 1];
+  }
+  const [inner, used] = await chainInclusion(crypto, leaf, index - k, n - k, proof);
+  if (used >= proof.length) return [inner, used + 1];
+  return [await hashNode(crypto, proof[used]!, inner), used + 1];
+}
+
+function isPow2(n: number): boolean {
+  return n > 0 && (n & (n - 1)) === 0;
+}
+
+/** Verify a Merkle consistency proof (RFC 6962 Section 2.1.4).
+ *
+ * Port of Go's VerifyConsistency / Python's _verify_consistency.
+ */
+export async function verifyConsistency(
+  crypto: CryptoOps,
+  oldSize: number,
+  newSize: number,
+  oldRoot: Uint8Array,
+  newRoot: Uint8Array,
+  proof: Uint8Array[],
+): Promise<boolean> {
+  if (oldSize === 0 || newSize === 0 || oldSize > newSize) return false;
+  if (oldSize === newSize) {
+    return proof.length === 0 && bytesEqual(oldRoot, newRoot);
+  }
+
+  let pIdx = 0;
+  let fr: Uint8Array;
+  let sr: Uint8Array;
+
+  if (isPow2(oldSize)) {
+    fr = oldRoot;
+    sr = oldRoot;
+  } else {
+    if (pIdx >= proof.length) return false;
+    fr = proof[pIdx]!;
+    sr = proof[pIdx]!;
+    pIdx++;
+  }
+
+  let fn = oldSize - 1;
+  let sn = newSize - 1;
+
+  while ((fn & 1) === 1) {
+    fn >>= 1;
+    sn >>= 1;
+  }
+
+  // Drive the walk from the tree, not from the proof's length. Looping on
+  // `pIdx < proof.length` let the prover choose how many steps ran, so a log
+  // could understate its own size and present the genuine proof for the size it
+  // really had — STH{size: 6} carrying the root of 7 leaves verified against the
+  // real 7 -> 8 proof. The only consumer is a witness detecting exactly that
+  // equivocation. Length is part of the claim: too few elements runs out here,
+  // too many is caught by the pIdx check below.
+  while (sn !== 0) {
+    if (pIdx >= proof.length) return false;
+    const c = proof[pIdx]!;
+    pIdx++;
+
+    if ((fn & 1) === 1 || fn === sn) {
+      fr = await hashNode(crypto, c, fr);
+      sr = await hashNode(crypto, c, sr);
+      while (fn !== 0 && (fn & 1) === 0) {
+        fn >>= 1;
+        sn >>= 1;
+      }
+    } else {
+      sr = await hashNode(crypto, sr, c);
+    }
+
+    fn >>= 1;
+    sn >>= 1;
+  }
+
+  return pIdx === proof.length && bytesEqual(fr, oldRoot) && bytesEqual(sr, newRoot);
+}
+
+
+/**
+ * Port of Go's BuildCertificateStatusPayload.
+ *
+ * Optional fields are omitted, never emitted as null: the issuer omits them, so
+ * a verifier that emitted nulls would rebuild different bytes and reject a
+ * genuine statement.
+ */
+export function buildCertificateStatusPayload(
+  stmt: Record<string, unknown>,
+): 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,
+  };
+  if (stmt.replacement_certificate_id != null) {
+    payload.replacement_certificate_id = stmt.replacement_certificate_id as string;
+  }
+  if (stmt.revocation_log_index != null) {
+    payload.revocation_log_index = stmt.revocation_log_index as number;
+  }
+  if (stmt.revoked_at != null) {
+    payload.revoked_at = formatTimestamp(stmt.revoked_at);
+  }
+  return canonicalJson(payload);
+}
+
+/** The verdict when a certificate verified but nothing said whether it was revoked. */
+export const VALID_REVOCATION_UNKNOWN = "VALID_REVOCATION_UNKNOWN";
+
+/**
+ * Verify a certificate and, separately, what a statement says about its
+ * revocation.
+ *
+ * A signature commits to bytes at an instant; revocation is discovered later,
+ * so no edit to the signed certificate can express it. The statement is a
+ * separate short-lived document — fetch it from
+ * `GET /v1/certificates/{id}/status`, or read `status_statement` from the
+ * certificate response, where it is stapled for exactly this purpose.
+ *
+ * | input | result |
+ * |---|---|
+ * | fresh statement, REVOKED | throws VerificationError |
+ * | fresh statement, ACTIVE | `"VALID"` |
+ * | absent or expired statement | `"VALID_REVOCATION_UNKNOWN"` |
+ *
+ * The last row is the point: `verifyCertificate` answers VALID there, which
+ * reads as "not revoked" and is not something it checked.
+ */
+export async function verifyCertificateWithStatus(
+  crypto: CryptoOps,
+  certificate: Cert,
+  publicKeys: Map<string, PublicKeyInfo>,
+  status?: Record<string, unknown> | null,
+  now?: Date,
+): Promise<string> {
+  const base = await verifyCertificate(crypto, certificate, publicKeys);
+  if (base !== "VALID") {
+    return base as string;
+  }
+  if (status == null) {
+    return VALID_REVOCATION_UNKNOWN;
+  }
+
+  const keyId = status.key_id as string | undefined;
+  const info = keyId ? publicKeys.get(keyId) : undefined;
+  if (!info) {
+    throw new VerificationError(`status statement signed by unknown key: ${keyId}`);
+  }
+  if (info.revoked) {
+    throw new VerificationError("status statement signed by a revoked key");
+  }
+
+  const payload = buildCertificateStatusPayload(status);
+  // decodeSignature, not hexToBytes: signatures arrive as hex, base64 or a byte
+  // array depending on the producer, and every other signature on this path
+  // goes through the same decoder.
+  const sig = decodeSignature(status.signature);
+  if (!(await crypto.ed25519Verify(info.keyBytes, payload, sig))) {
+    throw new VerificationError("status statement signature is invalid");
+  }
+
+  // A validly signed statement about a different certificate must not be
+  // allowed to speak for this one.
+  const certId = (certificate as Record<string, unknown>).id ??
+    (certificate as Record<string, unknown>).certificate_id;
+  if (status.certificate_id !== certId) {
+    throw new VerificationError("status statement is about a different certificate");
+  }
+
+  // Compared in the normalized form the payload signs, so the freshness check
+  // cannot disagree with what was signed about the same two instants.
+  const at = formatTimestamp((now ?? new Date()).toISOString());
+  const issued = formatTimestamp(status.statement_issued_at);
+  const expires = formatTimestamp(status.statement_expires_at);
+  if (at < issued || at >= expires) {
+    // Stale is not a weaker answer, it is no answer — including for a REVOKED
+    // statement, which must never decay into VALID.
+    return VALID_REVOCATION_UNKNOWN;
+  }
+
+  if (status.status === "REVOKED") {
+    throw new VerificationError("certificate has been revoked");
+  }
+  return "VALID";
+}