burnledger 0.3.1 → 0.5.0

package/src/verify.ts

@@ -17,7 +17,11 @@
  */
 
 import type { CryptoOps } from "./crypto.js";
-import { VerificationError } from "./errors.js";
+import {
+  CERTIFICATE_REVOKED,
+  UNSUPPORTED_FORMAT_VERSION,
+  VerificationError,
+} from "./errors.js";
 import type { TransparencyResult, VerificationResult } from "./models.js";
 
 // ---------------------------------------------------------------------------
@@ -30,6 +34,62 @@ const HEX_CHARS = "0123456789abcdef";
 // 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";
+// v4 signs the legal entity behind the trading name and a commitment to the
+// limitations wording. v3 certificates are verified forever -- they are evidence
+// designed to outlive the company -- so this is a branch, never a replacement.
+const PAYLOAD_TYPE_CERTIFICATE_V4 = "burnledger.certificate.v4";
+// v5 moves BOTH tags. v4 moved only the certificate's, because the attestation
+// shape did not change; in v5 it does, by way of the certificate carrying it.
+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";
+const FORMAT_VERSION_V3 = "3.0";
+
+/**
+ * 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,
+]);
+
+/**
+ * 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";
 const PAYLOAD_TYPE_LOG_LEAF = "burnledger.log_leaf.v3";
 // There is deliberately no verification payload type: v3 produces those facts
@@ -101,16 +161,56 @@ function textToBytes(s: string): Uint8Array {
 // Public key info
 // ---------------------------------------------------------------------------
 
+/** A signing key's disposition (ADR-017 §1).
+ *
+ * There is deliberately no "revoked": that word belongs to certificate
+ * revocation, and one word meaning two things is the confusion ADR-017 ends.
+ * Retirement is routine and a retired key's signatures stay exactly as good as
+ * the day they were made; compromise is an incident with a date.
+ */
+export type KeyStatus = "active" | "retired" | "compromised";
+
 export interface PublicKeyInfo {
   readonly keyBytes: Uint8Array;
   readonly keyId: string;
+  /** Raw `key_status` from the published entry. Kept as a string rather than
+   * KeyStatus so a word this verifier does not understand can fail closed
+   * instead of being narrowed away at the type level. */
+  readonly keyStatus: string;
+  /** RFC 3339, whole seconds, exactly as published. */
+  readonly notBefore?: string;
+  readonly notAfter?: string;
+  readonly compromisedFrom?: string;
+  /** @deprecated Superseded by keyStatus. Retained because it is published
+   * surface: a caller still passing `{ revoked: true }` gets the same
+   * fail-closed behaviour it always did. */
   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 },
+  opts?: PublicKeyOptions,
 ): Promise<PublicKeyInfo> {
   const raw = hexToBytes(hexKey);
   if (raw.length !== 32) {
@@ -118,7 +218,181 @@ export async function publicKeyFromHex(
   }
   const hash = await crypto.sha256(raw);
   const keyId = "dp_k_" + bytesToHex(hash);
-  return { keyBytes: raw, keyId, revoked: opts?.revoked ?? false };
+  const revoked = opts?.revoked ?? false;
+  // An old caller passing revoked:true meant "this key is unusable" and must
+  // keep getting exactly that. Mapping it to a status this verifier cannot
+  // interpret reaches the same fail-closed branch as before.
+  const keyStatus = opts?.keyStatus ?? (revoked ? "revoked" : "active");
+  return {
+    keyBytes: raw,
+    keyId,
+    keyStatus,
+    notBefore: opts?.notBefore,
+    notAfter: opts?.notAfter,
+    compromisedFrom: opts?.compromisedFrom,
+    revoked,
+  };
+}
+
+/** Verdicts for the key check (ADR-017 §2). */
+export const KEY_OUTSIDE_VALIDITY = "KEY_OUTSIDE_VALIDITY";
+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 was authorized to sign at anchor time `t`.
+ *
+ * Returns `"VALID"` when the key clears. The anchor is seconds since the epoch
+ * from a time the verifier observed independently — the signed tree head's
+ * timestamp — never the certificate's own `issued_at`, which is signed by the
+ * very key whose validity is in question.
+ *
+ * Mirrors core.EvaluateKey in Go, including both of its settled readings: an
+ * entry stating no interval has nothing to check, so a missing anchor is not
+ * "unknown"; and a compromised key with no anchor does not soften, because
+ * without an anchor we cannot show the signature predates the compromise.
+ */
+export function evaluateKey(pki: PublicKeyInfo, anchor: number | null): string {
+  // A caller can still build a PublicKeyInfo by hand with revoked:true rather
+  // than going through publicKeyFromHex. That flag meant "this key is
+  // unusable" and must keep meaning exactly that.
+  if (pki.revoked) return "UNKNOWN_KEY";
+  if (pki.keyStatus === "compromised") {
+    if (anchor === null || pki.compromisedFrom === undefined) return KEY_COMPROMISED;
+    return anchor < parseRfc3339(pki.compromisedFrom)
+      ? VALID_KEY_COMPROMISED_LATER
+      : KEY_COMPROMISED;
+  }
+  if (pki.keyStatus === "active" || pki.keyStatus === "retired" || pki.keyStatus === "") {
+    if (pki.notBefore === undefined && pki.notAfter === undefined) return "VALID";
+    if (anchor === null) return VALID_KEY_WINDOW_UNKNOWN;
+    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 "VALID";
+  }
+  // A disposition this verifier does not understand is not one it can vouch
+  // for. Fail closed, as the boolean it replaces did.
+  return "UNKNOWN_KEY";
+}
+
+/**
+ * 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;
+  const sth = transparency.signed_tree_head as Record<string, unknown> | undefined;
+  if (sth === undefined || typeof sth.timestamp !== "string") return null;
+  try {
+    return parseRfc3339(sth.timestamp);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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,
+  // 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(`${role} is compromised: ${keyId}`);
+  }
+  if (verdict === KEY_OUTSIDE_VALIDITY) {
+    throw new VerificationError(`${role} was not valid when it signed: ${keyId}`);
+  }
+  if (verdict === "UNKNOWN_KEY") {
+    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;
 }
 
 // ---------------------------------------------------------------------------
@@ -133,12 +407,24 @@ 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.
+  checkFormatVersion((certificate as Record<string, unknown>).certificate_format_version);
+
   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}`);
+  // 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,
+    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.
@@ -160,6 +446,7 @@ export async function verifyCertificate(
       attested_at: att.attested_at,
       systems: attestationSystems(certificate),
     },
+    certificate.certificate_format_version as string,
   );
   const attSig = decodeSignature(att.attestation_signature as string);
   if (!(await crypto.ed25519Verify(pki.keyBytes, attPayload, attSig))) {
@@ -222,7 +509,10 @@ export async function verifyCertificate(
     );
   }
 
-  return "VALID" as VerificationResult;
+  // 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.
+  return keyVerdict as VerificationResult;
 }
 
 const NIL_UUID = "00000000-0000-0000-0000-000000000000";
@@ -247,7 +537,8 @@ export async function verifyTransparency(
 
   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}`);
+  // The tree head carries its own timestamp, so this path always has an anchor.
+  requireUsableKey(pki, certificateAnchor(certificate), keyId);
 
   // 1. Tree head signature
   const headPayload = buildTreeHeadPayload(sth);
@@ -557,6 +848,7 @@ function civilFromDays(days: number): [number, number, number] {
 function buildAttestationPayload(
   subject: Record<string, unknown>,
   att: Record<string, unknown>,
+  certFormatVersion: string,
 ): Uint8Array {
   const attestedAt = formatTimestamp(att.attested_at);
   const systems = (att.systems as Record<string, unknown>[]).map((s) => ({
@@ -576,7 +868,7 @@ function buildAttestationPayload(
 
   const payload = {
     attested_at: attestedAt,
-    payload_type: PAYLOAD_TYPE_ATTESTATION,
+    payload_type: attestationPayloadType(certFormatVersion),
     proof_mode: att.proof_mode as string,
     subject_hash: toHex(subject.identifier_hash as string),
     systems,
@@ -584,6 +876,28 @@ function buildAttestationPayload(
   return canonicalJson(payload);
 }
 
+/** Domain separator for the record itself, by certificate format version. */
+function certificatePayloadType(version: string): string {
+  checkFormatVersion(version);
+  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_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>;
@@ -614,31 +928,60 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
     proof_mode: att.proof_mode as string,
   };
 
-  const issuerObj = {
+  // 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;
+  // 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;
+  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),
   };
+  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 (isV5Plus && typeof issuer.enclave_pcr0 === "string" && issuer.enclave_pcr0 !== "") {
+    issuerObj.enclave_pcr0 = issuer.enclave_pcr0;
+  }
 
-  const subjectObj = {
+  // 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_type_hint: subject.identifier_type_hint as string,
   };
+  if (!isV5Plus) {
+    subjectObj.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 = {
+  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),
     issuer: issuerObj,
-    payload_type: PAYLOAD_TYPE_CERTIFICATE,
+    payload_type: certificatePayloadType(version),
     subject: subjectObj,
     systems,
   };
+  if (isV4Plus && cert.scope != null) {
+    const scope = cert.scope as Record<string, unknown>;
+    payload.scope = {
+      text_sha256: toHex(scope.text_sha256 as string),
+      version: scope.version as string,
+    };
+  }
   return canonicalJson(payload);
 }
 
@@ -891,10 +1234,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(
@@ -904,12 +1248,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;
@@ -917,9 +1263,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
@@ -932,25 +1296,61 @@ export async function verifyCertificateWithStatus(
 
   // 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;
+  //
+  // Compared against `certificate_id` and nothing else. This used to fall back
+  // through `certificate.id`, which the signature does not cover:
+  // buildCertificatePayload (core/payload.go) enumerates nine keys and `id` is
+  // not among them, and no verifier rejects unknown top-level keys. So a holder
+  // of a REVOKED certificate could add `"id": "<some other certificate>"`,
+  // staple that certificate's ACTIVE status statement — served unauthenticated
+  // by design — and this check would compare the two things the attacker chose.
+  // 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) {
     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;
+    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);
   }
-  return "VALID";
+  // 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);
+  }
+  // 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;
 }

package/src/web-verifier.ts

@@ -4,9 +4,9 @@
  * Imports the leaf modules directly rather than re-exporting from
  * `index.browser.ts`: that entry pulls in the HTTP client, which imports
  * `node:fs/promises` and cannot be bundled for a browser at all. The page needs
- * four functions, so this exposes four functions — the surface a relying party's
- * browser is handed is then something you can read in one screen instead of
- * inferring from a minified artifact.
+ * four functions and one error code, so that is what this exposes — the surface
+ * a relying party's browser is handed is then something you can read in one
+ * screen instead of inferring from a minified artifact.
  *
  * Built by `scripts/build-web-verifier.mjs`. The bundle this replaces was built
  * by hand once and never regenerated, and had drifted into disagreeing with the
@@ -16,13 +16,14 @@
  * source file anywhere in the repository.
  */
 import { browserCrypto } from "./crypto-browser.js";
+import { CERTIFICATE_REVOKED, UNSUPPORTED_FORMAT_VERSION } from "./errors.js";
 import {
   verifyCertificate as _verifyCertificate,
   verifyCertificateWithStatus as _verifyCertificateWithStatus,
   verifyTransparency as _verifyTransparency,
   publicKeyFromHex as _publicKeyFromHex,
 } from "./verify.js";
-import type { PublicKeyInfo } from "./verify.js";
+import type { PublicKeyInfo, PublicKeyOptions } from "./verify.js";
 import type { VerificationResult, TransparencyResult } from "./models.js";
 
 type Cert = Record<string, unknown>;
@@ -50,6 +51,14 @@ export function verifyCertificateWithStatus(
   return _verifyCertificateWithStatus(browserCrypto, certificate, publicKeys, status, now);
 }
 
+/**
+ * The `code` a VerificationError carries when a status statement verified and
+ * says REVOKED. The page needs it to tell that fact apart from a statement it
+ * could not authenticate, which is a different claim and must not be painted
+ * as a revocation.
+ */
+export { CERTIFICATE_REVOKED, UNSUPPORTED_FORMAT_VERSION };
+
 /** Verify the transparency proof embedded in a certificate. */
 export function verifyTransparency(
   certificate: Cert,
@@ -61,7 +70,7 @@ export function verifyTransparency(
 /** Construct a PublicKeyInfo from a hex-encoded Ed25519 public key. */
 export function publicKeyFromHex(
   hexKey: string,
-  opts?: { revoked?: boolean },
+  opts?: PublicKeyOptions,
 ): Promise<PublicKeyInfo> {
   return _publicKeyFromHex(browserCrypto, hexKey, opts);
 }