burnledger 0.4.0 → 0.6.0

package/src/verify.ts

@@ -17,7 +17,12 @@
  */
 
 import type { CryptoOps } from "./crypto.js";
-import { VerificationError } from "./errors.js";
+import {
+  CERTIFICATE_REVOKED,
+  UNSUPPORTED_ALGORITHM,
+  UNSUPPORTED_FORMAT_VERSION,
+  VerificationError,
+} from "./errors.js";
 import type { TransparencyResult, VerificationResult } from "./models.js";
 
 // ---------------------------------------------------------------------------
@@ -40,11 +45,75 @@ const PAYLOAD_TYPE_ATTESTATION_V5 = "burnledger.attestation.v5";
 const PAYLOAD_TYPE_CERTIFICATE_V5 = "burnledger.certificate.v5";
 const FORMAT_VERSION_V5 = "5.0";
 const FORMAT_VERSION_V4 = "4.0";
+// v6 renames the artifact and nothing else: the shape is byte-for-byte v5, and
+// only the tag and the version string differ. It still takes its own tag, for
+// the same reason v4 and v5 each took one -- a signature over a payload calling
+// itself a verification record must not verify as one calling itself a
+// certificate. Two names for one shape sharing a separator is exactly what a
+// separator prevents.
+const PAYLOAD_TYPE_ATTESTATION_V6 = "burnledger.attestation.v6";
+const PAYLOAD_TYPE_VERIFICATION_RECORD_V6 = "burnledger.verification_record.v6";
+const FORMAT_VERSION_V6 = "6.0";
+// v7 changes the SHAPE, not just the name: every system entry gains
+// read_only_enforcement and transport_security, and the issuer gains the
+// algorithm identifier. Its tags move for the reason v4, v5 and v6 each moved
+// theirs, and this time the bytes under them genuinely differ.
+const PAYLOAD_TYPE_ATTESTATION_V7 = "burnledger.attestation.v7";
+const PAYLOAD_TYPE_VERIFICATION_RECORD_V7 = "burnledger.verification_record.v7";
+const FORMAT_VERSION_V7 = "7.0";
+const FORMAT_VERSION_V3 = "3.0";
+
+/**
+ * The only signature scheme this SDK can check. A v7 record names its own
+ * algorithm, so a record naming anything else must be refused with its own
+ * code rather than fed to ed25519Verify and reported as a bad signature.
+ */
+const ALGORITHM_ED25519 = "ed25519";
+
+/**
+ * Every format this build can read, oldest first. Mirrors core.FormatVersions()
+ * in the Go source; the cross-language conformance corpus carries a fixture per
+ * version, so a version present in one language and missing here fails there.
+ *
+ * Frozen because `readonly` is erased at build time: it stops a TypeScript
+ * caller from writing to the array, and does nothing at all to the JavaScript
+ * this compiles to — which is what the browser bundle actually runs, where any
+ * script on the page could otherwise push a version onto it.
+ */
+export const KNOWN_FORMAT_VERSIONS: readonly string[] = Object.freeze([
+  FORMAT_VERSION_V3,
+  FORMAT_VERSION_V4,
+  FORMAT_VERSION_V5,
+  FORMAT_VERSION_V6,
+  FORMAT_VERSION_V7,
+]);
+
+/**
+ * Returns the version, or throws if this SDK cannot read it.
+ *
+ * Rejects a non-string too: JSON carrying `6.0` as a NUMBER would compare
+ * unequal to every known version and silently take the oldest branch, which is
+ * the same trap as an unknown version wearing a different hat.
+ */
+function checkFormatVersion(version: unknown): string {
+  if (typeof version !== "string" || !KNOWN_FORMAT_VERSIONS.includes(version)) {
+    throw new VerificationError(
+      `unsupported certificate_format_version ${JSON.stringify(version)}; ` +
+        `this version of the SDK reads ${KNOWN_FORMAT_VERSIONS.join(", ")}. ` +
+        "The record may be genuine and simply newer than this library.",
+      UNSUPPORTED_FORMAT_VERSION,
+    );
+  }
+  return version;
+}
 const PAYLOAD_TYPE_TREE_HEAD = "burnledger.sth.v3";
+// The domain for a tree head that names its log. See buildTreeHeadPayload.
+const PAYLOAD_TYPE_TREE_HEAD_V7 = "burnledger.sth.v7";
 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";
+const PAYLOAD_TYPE_KEY_LIST = "burnledger.key_list.v3";
 
 export function hexToBytes(hex: string): Uint8Array {
   const len = hex.length >>> 1;
@@ -137,16 +206,30 @@ export interface PublicKeyInfo {
   readonly revoked: boolean;
 }
 
+/**
+ * The options publicKeyFromHex accepts, mirroring one entry of the published key
+ * set at `/.well-known/burnledger-keys`.
+ *
+ * Named, and exported, because it is restated by every entry point that wraps
+ * publicKeyFromHex — index.ts, index.browser.ts, web-verifier.ts. When the
+ * ADR-017 fields were added, two of the three were widened and the browser entry
+ * was not, so the dashboard could not express a compromised key through the API
+ * it imports and every key it built looked unconditionally active. A shared type
+ * is what stops the next field from being added to two places out of three.
+ */
+export interface PublicKeyOptions {
+  /** @deprecated Use keyStatus. Retained: true still means "unusable". */
+  revoked?: boolean;
+  keyStatus?: string;
+  notBefore?: string;
+  notAfter?: string;
+  compromisedFrom?: string;
+}
+
 export async function publicKeyFromHex(
   crypto: CryptoOps,
   hexKey: string,
-  opts?: {
-    revoked?: boolean;
-    keyStatus?: string;
-    notBefore?: string;
-    notAfter?: string;
-    compromisedFrom?: string;
-  },
+  opts?: PublicKeyOptions,
 ): Promise<PublicKeyInfo> {
   const raw = hexToBytes(hexKey);
   if (raw.length !== 32) {
@@ -176,6 +259,32 @@ export const KEY_COMPROMISED = "KEY_COMPROMISED";
 export const VALID_KEY_COMPROMISED_LATER = "VALID_KEY_COMPROMISED_LATER";
 export const VALID_KEY_WINDOW_UNKNOWN = "VALID_KEY_WINDOW_UNKNOWN";
 
+/**
+ * The revocation states a statement may assert. Mirrors
+ * core.ValidCertificateStatusValue: anything else means the statement was read
+ * but not understood, which is not the same as "not revoked".
+ */
+const KNOWN_STATUS_VALUES: ReadonlySet<string> = new Set(["ACTIVE", "REVOKED"]);
+
+/**
+ * The key verdicts that permit relying on a signature: VALID plus the two soft
+ * verdicts ADR-017 §2 says a reader must be SHOWN rather than refused. Anything
+ * not named here is refused, including a verdict added in a later release.
+ */
+const USABLE_KEY_VERDICTS: ReadonlySet<string> = new Set([
+  "VALID",
+  VALID_KEY_WINDOW_UNKNOWN,
+  VALID_KEY_COMPROMISED_LATER,
+]);
+
+/** Whether a key verdict permits relying on a signature. Mirrors
+ * core.KeyIsUsable; exported so the key-list verifier (keys.ts) refuses the
+ * same set requireUsableKey refuses rather than keeping a second copy of it —
+ * a second copy is exactly how #684's fourth answer came to exist. */
+export function keyIsUsable(verdict: string): boolean {
+  return USABLE_KEY_VERDICTS.has(verdict);
+}
+
 /** Whether a key was authorized to sign at anchor time `t`.
  *
  * Returns `"VALID"` when the key clears. The anchor is seconds since the epoch
@@ -215,7 +324,17 @@ export function evaluateKey(pki: PublicKeyInfo, anchor: number | null): string {
   return "UNKNOWN_KEY";
 }
 
-/** The anchor a certificate supplies, or null when it supplies none. */
+/**
+ * The anchor a certificate supplies, or null when it supplies none.
+ *
+ * READS AN UNSIGNED FIELD. `transparency` is stripped before signing, so on a
+ * certificate handed to a verifier the timestamp is holder-editable. Use
+ * {@link verifiedCertificateAnchor} anywhere the anchor decides whether a key
+ * may be relied on; this is safe only where the same timestamp is inside a
+ * payload the caller goes on to verify, which is what verifyTransparency does.
+ *
+ * Exported and unchanged because it is published API.
+ */
 export function certificateAnchor(certificate: Record<string, unknown>): number | null {
   const transparency = certificate.transparency as Record<string, unknown> | null | undefined;
   if (transparency == null) return null;
@@ -228,22 +347,77 @@ 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 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.
+ *
+ * A head that does not verify yields no anchor, which is the same conservative
+ * answer as a certificate carrying no transparency block at all.
+ */
+async function verifiedCertificateAnchor(
+  crypto: CryptoOps,
+  certificate: Record<string, unknown>,
+  pki: PublicKeyInfo,
+): Promise<number | null> {
+  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>;
+  try {
+    const headPayload = buildTreeHeadPayload(sth);
+    const headSig = decodeSignature(sth.signature);
+    if (!(await crypto.ed25519Verify(pki.keyBytes, headPayload, headSig))) return null;
+  } catch {
+    return null;
+  }
+  return anchor;
+}
+
 /** Throws for a key that cannot be used at all; returns the verdict otherwise.
  *
  * VALID_KEY_COMPROMISED_LATER and VALID_KEY_WINDOW_UNKNOWN are returned rather
  * than thrown because they are not refusals — they are results a caller must
  * show the reader instead of collapsing into green.
  */
-function requireUsableKey(pki: PublicKeyInfo, anchor: number | null, keyId: string): string {
+function requireUsableKey(
+  pki: PublicKeyInfo,
+  anchor: number | null,
+  keyId: string,
+  // Named, because this is also the key that signs a certificate-status
+  // statement, and "issuer key is compromised" would send a reader looking at
+  // the wrong key.
+  role = "issuer key",
+): string {
   const verdict = evaluateKey(pki, anchor);
   if (verdict === KEY_COMPROMISED) {
-    throw new VerificationError(`issuer key is compromised: ${keyId}`);
+    throw new VerificationError(`${role} is compromised: ${keyId}`);
   }
   if (verdict === KEY_OUTSIDE_VALIDITY) {
-    throw new VerificationError(`issuer key was not valid when it signed: ${keyId}`);
+    throw new VerificationError(`${role} was not valid when it signed: ${keyId}`);
   }
   if (verdict === "UNKNOWN_KEY") {
-    throw new VerificationError(`issuer key has an unusable status "${pki.keyStatus}": ${keyId}`);
+    throw new VerificationError(`${role} has an unusable status "${pki.keyStatus}": ${keyId}`);
+  }
+  // An ALLOW-list, matching core.KeyIsUsable, which was inverted away from
+  // exactly the shape above. Naming the refusals and returning everything else
+  // means a verdict added to evaluateKey later becomes a PASS by default — and
+  // the value returned here is propagated out of verifyCertificate as its
+  // result, so "everything else" is rendered to a reader as "verified, with a
+  // note". Go would refuse the same document. That is #684's three-verifiers-
+  // two-answers divergence, in the direction that calls a bad document good.
+  if (!USABLE_KEY_VERDICTS.has(verdict)) {
+    throw new VerificationError(
+      `${role} returned a verdict this SDK does not recognize (${verdict}): ${keyId}`,
+    );
   }
   return verdict;
 }
@@ -260,14 +434,38 @@ export async function verifyCertificate(
   certificate: Cert,
   publicKeys: Map<string, PublicKeyInfo>,
 ): 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,
+  );
+
   const issuer = certificate.issuer as Record<string, unknown>;
+  // 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.
+  // Below v7 no record names one, so there is nothing to check.
+  if (formatVersion === FORMAT_VERSION_V7 && issuer.algorithm !== ALGORITHM_ED25519) {
+    throw new VerificationError(
+      `record names signature algorithm ${JSON.stringify(issuer.algorithm)}; ` +
+        `this version of the SDK verifies ${ALGORITHM_ED25519}. ` +
+        "The record may be genuine and simply signed with a scheme this library does not implement.",
+      UNSUPPORTED_ALGORITHM,
+    );
+  }
   const keyId = issuer.key_id as string;
 
   const pki = publicKeys.get(keyId);
   if (pki === undefined) throw new VerificationError(`unknown issuer key: ${keyId}`);
   // The key check runs before any signature check: a signature verified
   // against a key nobody vouches for proves nothing about the issuer.
-  const keyVerdict = requireUsableKey(pki, certificateAnchor(certificate), keyId);
+  const keyVerdict = requireUsableKey(
+    pki,
+    await verifiedCertificateAnchor(crypto, certificate, pki),
+    keyId,
+  );
 
   // 1. Certificate signature FIRST — nothing below may trust a field until the
   // bytes carrying it are covered by a verified signature.
@@ -435,6 +633,20 @@ export async function verifyTransparency(
     );
   }
 
+  // Same rule for the log id (Q31). transparency.log_id sits beside log_url and
+  // is the field a reader looks at to answer "which log is this?", and nothing
+  // signs it — so a holder could relabel a genuine proof as belonging to a
+  // different log while every signature still checked out. A head predating log
+  // ids has neither side set and passes.
+  const signedLogId = (sth.log_id as string | undefined) ?? "";
+  const unsignedLogId = (transparency.log_id as string | undefined) ?? "";
+  if (unsignedLogId !== signedLogId) {
+    throw new VerificationError(
+      `transparency.log_id (${JSON.stringify(unsignedLogId)}) does not match the signed ` +
+        `tree head (${JSON.stringify(signedLogId)}); it is not covered by any signature`,
+    );
+  }
+
   if (!(await verifyInclusion(crypto, leaf, index, treeSize, proofHashes, root))) {
     throw new VerificationError("merkle inclusion proof is invalid");
   }
@@ -694,27 +906,43 @@ function buildAttestationPayload(
   certFormatVersion: string,
 ): 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,
-  }));
+  // v7 signs two per-system measurements v6 leaves on a mutable row. Gated on
+  // the record's OWN version: emitting them for an older format would rebuild
+  // bytes no signer ever produced and reject every record already issued.
+  const isV7 = certFormatVersion === FORMAT_VERSION_V7;
+  const systems = (att.systems as Record<string, unknown>[]).map((s) => {
+    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,
+      // 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,
+    };
+    if (isV7) {
+      sys.read_only_enforcement = requireMeasured(
+        s.read_only_enforcement,
+        "read_only_enforcement",
+        s.system_name,
+      );
+      sys.transport_security = requireMeasured(
+        s.transport_security,
+        "transport_security",
+        s.system_name,
+      );
+    }
+    return sys;
+  });
 
   const payload = {
     attested_at: attestedAt,
-    payload_type:
-      certFormatVersion === FORMAT_VERSION_V5
-        ? PAYLOAD_TYPE_ATTESTATION_V5
-        : PAYLOAD_TYPE_ATTESTATION,
+    payload_type: attestationPayloadType(certFormatVersion),
     proof_mode: att.proof_mode as string,
     subject_hash: toHex(subject.identifier_hash as string),
     systems,
@@ -722,6 +950,49 @@ function buildAttestationPayload(
   return canonicalJson(payload);
 }
 
+/**
+ * Read a v7 measured field that MUST be a non-empty string.
+ *
+ * A missing or non-string value cannot be turned into `""` and canonicalized:
+ * the signer never emits an empty measurement, so an empty one here would
+ * rebuild bytes no signature covers and be reported as forgery. Refusing with a
+ * document-shape message says the true thing — this record is malformed, not
+ * this record is fake.
+ */
+function requireMeasured(value: unknown, field: string, systemName: unknown): string {
+  if (typeof value !== "string" || value === "") {
+    throw new VerificationError(
+      `system ${JSON.stringify(systemName)}: ${field} is missing from a 7.0 record, ` +
+        "which signs it; the document is incomplete rather than unverifiable",
+    );
+  }
+  return value;
+}
+
+/** Domain separator for the record itself, by certificate format version. */
+function certificatePayloadType(version: string): string {
+  checkFormatVersion(version);
+  if (version === FORMAT_VERSION_V7) return PAYLOAD_TYPE_VERIFICATION_RECORD_V7;
+  if (version === FORMAT_VERSION_V6) return PAYLOAD_TYPE_VERIFICATION_RECORD_V6;
+  if (version === FORMAT_VERSION_V5) return PAYLOAD_TYPE_CERTIFICATE_V5;
+  if (version === FORMAT_VERSION_V4) return PAYLOAD_TYPE_CERTIFICATE_V4;
+  return PAYLOAD_TYPE_CERTIFICATE;
+}
+
+/**
+ * Domain separator for the attestation carried by a record of that format. It
+ * follows the record's version because a verifier rebuilds the attestation
+ * payload from the record it is checking, and must reproduce the exact bytes
+ * the enclave signed.
+ */
+function attestationPayloadType(version: string): string {
+  checkFormatVersion(version);
+  if (version === FORMAT_VERSION_V7) return PAYLOAD_TYPE_ATTESTATION_V7;
+  if (version === FORMAT_VERSION_V6) return PAYLOAD_TYPE_ATTESTATION_V6;
+  if (version === FORMAT_VERSION_V5) return PAYLOAD_TYPE_ATTESTATION_V5;
+  return PAYLOAD_TYPE_ATTESTATION;
+}
+
 function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   const att = cert.attestation as Record<string, unknown>;
   const issuer = cert.issuer as Record<string, unknown>;
@@ -730,19 +1001,36 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   // 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,
-  }));
+  const version = cert.certificate_format_version as string;
+  const isV7 = version === FORMAT_VERSION_V7;
+  const systems = ((cert.systems as Record<string, unknown>[]) ?? []).map((s) => {
+    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,
+    };
+    if (isV7) {
+      sys.read_only_enforcement = requireMeasured(
+        s.read_only_enforcement,
+        "read_only_enforcement",
+        s.system_name,
+      );
+      sys.transport_security = requireMeasured(
+        s.transport_security,
+        "transport_security",
+        s.system_name,
+      );
+    }
+    return sys;
+  });
 
   // The attestation block carries no system list of its own: the merged list
   // above is a superset of it. verification_signature is gone entirely.
@@ -755,21 +1043,30 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   // Fields added after v3 are gated on the certificate's OWN version. A v3
   // certificate must reconstruct to the same bytes forever; reading these
   // unconditionally would break every certificate already issued.
-  const version = cert.certificate_format_version as string;
-  const isV5 = version === FORMAT_VERSION_V5;
-  const isV4Plus = version === FORMAT_VERSION_V4 || isV5;
+  // v6 carries v5's shape exactly, so it takes every gate v5 takes. Naming
+  // these "Plus" rather than testing equality at each use is what stops a new
+  // version from silently missing one.
+  const isV5Plus =
+    version === FORMAT_VERSION_V5 || version === FORMAT_VERSION_V6 || isV7;
+  const isV4Plus = version === FORMAT_VERSION_V4 || isV5Plus;
 
   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),
   };
+  // v7 signs the algorithm, and does so unconditionally: unlike legal_entity
+  // and enclave_pcr0, "which scheme signed this" is never unknown to a signer,
+  // so a v7 record missing it is malformed rather than merely sparse.
+  if (isV7) {
+    issuerObj.algorithm = requireMeasured(issuer.algorithm, "issuer.algorithm", "issuer");
+  }
   if (isV4Plus && typeof issuer.legal_entity === "string" && issuer.legal_entity !== "") {
     issuerObj.legal_entity = issuer.legal_entity;
   }
   // 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 (isV5 && typeof issuer.enclave_pcr0 === "string" && issuer.enclave_pcr0 !== "") {
+  if (isV5Plus && typeof issuer.enclave_pcr0 === "string" && issuer.enclave_pcr0 !== "") {
     issuerObj.enclave_pcr0 = issuer.enclave_pcr0;
   }
 
@@ -778,7 +1075,7 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   const subjectObj: Record<string, unknown> = {
     identifier_hash: toHex(subject.identifier_hash as string),
   };
-  if (!isV5) {
+  if (!isV5Plus) {
     subjectObj.identifier_type_hint = subject.identifier_type_hint as string;
   }
 
@@ -792,11 +1089,7 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
     certificate_id: cert.certificate_id as string,
     issued_at: formatTimestamp(cert.issued_at),
     issuer: issuerObj,
-    payload_type: isV5
-      ? PAYLOAD_TYPE_CERTIFICATE_V5
-      : isV4Plus
-        ? PAYLOAD_TYPE_CERTIFICATE_V4
-        : PAYLOAD_TYPE_CERTIFICATE,
+    payload_type: certificatePayloadType(version),
     subject: subjectObj,
     systems,
   };
@@ -846,16 +1139,37 @@ function attestationSystems(cert: Record<string, unknown>): Record<string, unkno
     observed_at: s.attested_at,
     merkle_root: s.merkle_root,
     canonical_version: s.canonical_version,
+    // Carried through so the v7 attestation payload can be rebuilt from the
+    // record. Undefined on older formats, where buildAttestationPayload never
+    // reads them.
+    read_only_enforcement: s.read_only_enforcement,
+    transport_security: s.transport_security,
   }));
 }
 
-function buildTreeHeadPayload(head: Record<string, unknown>): Uint8Array {
-  const payload = {
-    payload_type: PAYLOAD_TYPE_TREE_HEAD,
+/**
+ * Port of Go's BuildTreeHeadPayload.
+ *
+ * A head that names its log is signed in a DIFFERENT DOMAIN from one that does
+ * not (Q31). That is what makes log_id unstrippable: removing it moves the
+ * rebuild into burnledger.sth.v3 and adding one moves it into
+ * burnledger.sth.v7, and the signature fails either way. Heads signed before
+ * log ids existed carry none and reproduce exactly the bytes they always did.
+ *
+ * Exported for anchor.ts, which rebuilds the preimage of a head fetched from
+ * GET /v1/log/head. Not re-exported from index.ts: it is an internal seam
+ * 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 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,
   };
+  if (named) payload.log_id = logId;
   return canonicalJson(payload);
 }
 
@@ -1043,6 +1357,40 @@ export function buildCertificateStatusPayload(
   return canonicalJson(payload);
 }
 
+/**
+ * Port of Go's BuildKeyListPayload (core/key_list.go).
+ *
+ * The key array is sorted by key_id before signing: canonical JSON sorts
+ * object keys but does nothing to array order, and the server has no reason to
+ * preserve any particular order across a rotation. Optional entry fields are
+ * omitted, never emitted as null, for the reason buildCertificateStatusPayload
+ * omits them. `keys` is the array exactly as HANDED to the verifier — the
+ * signature covers the published entries, not a parsed reinterpretation of
+ * them, which is what makes an edited key_status detectable.
+ */
+export function buildKeyListPayload(doc: Record<string, unknown>): Uint8Array {
+  const entries = (doc.keys as Record<string, unknown>[]).map((e) => {
+    const k: Record<string, unknown> = {};
+    if (e.compromised_from != null) k.compromised_from = e.compromised_from;
+    k.key_id = e.key_id;
+    k.key_status = e.key_status;
+    if (e.not_after != null) k.not_after = e.not_after;
+    if (e.not_before != null && e.not_before !== "") k.not_before = e.not_before;
+    k.public_key = e.public_key;
+    return k;
+  });
+  entries.sort((a, b) => ((a.key_id as string) < (b.key_id as string) ? -1 : a.key_id === b.key_id ? 0 : 1));
+  const payload: Record<string, unknown> = {
+    payload_type: PAYLOAD_TYPE_KEY_LIST,
+    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_tree_size: doc.sth_tree_size as number,
+  };
+  return canonicalJson(payload);
+}
+
 /** The verdict when a certificate verified but nothing said whether it was revoked. */
 export const VALID_REVOCATION_UNKNOWN = "VALID_REVOCATION_UNKNOWN";
 
@@ -1059,10 +1407,11 @@ export const VALID_REVOCATION_UNKNOWN = "VALID_REVOCATION_UNKNOWN";
  * | input | result |
  * |---|---|
  * | fresh statement, REVOKED | throws VerificationError |
- * | fresh statement, ACTIVE | `"VALID"` |
- * | absent or expired statement | `"VALID_REVOCATION_UNKNOWN"` |
+ * | fresh statement, ACTIVE | `"VALID"`, or a soft verdict on either key |
+ * | absent or expired statement | `"VALID_REVOCATION_UNKNOWN"`, or the certificate key's soft verdict |
+ * | statement key unusable (ADR-017) | throws VerificationError |
  *
- * The last row is the point: `verifyCertificate` answers VALID there, which
+ * The third row is the point: `verifyCertificate` answers VALID there, which
  * reads as "not revoked" and is not something it checked.
  */
 export async function verifyCertificateWithStatus(
@@ -1072,12 +1421,14 @@ export async function verifyCertificateWithStatus(
   status?: Record<string, unknown> | null,
   now?: Date,
 ): 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);
-  if (base !== "VALID") {
-    return base as string;
-  }
   if (status == null) {
-    return VALID_REVOCATION_UNKNOWN;
+    return resolveWithBase(base, VALID_REVOCATION_UNKNOWN);
   }
 
   const keyId = status.key_id as string | undefined;
@@ -1085,9 +1436,27 @@ export async function verifyCertificateWithStatus(
   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");
-  }
+
+  // The whole ADR-017 table, not just the deprecated boolean. `revoked` is
+  // never set by a key loaded from /.well-known/burnledger-keys — that endpoint
+  // publishes key_status — so this check read `false` for a key the issuer had
+  // declared COMPROMISED, and whoever held that key could mint an ACTIVE
+  // statement for a revoked certificate that every SDK and the browser bundle
+  // rendered as a signed "not revoked". core.VerifyCertificateWithStatus has
+  // always evaluated it.
+  //
+  // The anchor is the verifier's own clock, not a field inside the statement: a
+  // statement must already be inside its own validity window to be served at
+  // all, and `now` is a time this verifier observed rather than one the signing
+  // key asserted about itself.
+  const when = now ?? new Date();
+  const at = formatTimestamp(when.toISOString());
+  const statusKeyVerdict = requireUsableKey(
+    info,
+    parseRfc3339(at),
+    keyId!,
+    "status statement key",
+  );
 
   const payload = buildCertificateStatusPayload(status);
   // decodeSignature, not hexToBytes: signatures arrive as hex, base64 or a byte
@@ -1118,17 +1487,43 @@ export async function verifyCertificateWithStatus(
 
   // 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;
+    return resolveWithBase(base, VALID_REVOCATION_UNKNOWN);
   }
 
   if (status.status === "REVOKED") {
-    throw new VerificationError("certificate has been revoked");
+    // Coded, because this is the only status-path rejection that is a fact
+    // about the certificate rather than a failure to authenticate the
+    // statement. A caller that cannot tell the two apart will render an
+    // unsigned statement as a revocation.
+    throw new VerificationError("certificate has been revoked", CERTIFICATE_REVOKED);
+  }
+  // A state this SDK does not recognize is NOT active. This tested only for
+  // REVOKED and treated everything else as a pass, so a signed, fresh,
+  // correctly-bound statement saying "SUSPENDED" — or "revoked" in the wrong
+  // 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";
+  // 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);
+}
+
+/**
+ * Picks what to report when the certificate's own key returned a soft verdict
+ * and the status path also has something to say. A doubt about the key that
+ * signed the certificate questions the whole document, so it outranks a doubt
+ * about revocation or about the statement's own key; only one verdict string
+ * comes back, and this is the one a reader most needs. Mirrors
+ * core.resolveWithBase.
+ */
+function resolveWithBase(base: string, verdict: string): string {
+  return base !== "VALID" ? base : verdict;
 }