burnledger 0.3.1 → 0.5.0

package/dist/esm/verify.d.ts

@@ -17,16 +17,93 @@
  */
 import type { CryptoOps } from "./crypto.js";
 import type { TransparencyResult, VerificationResult } from "./models.js";
+/**
+ * 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 declare const KNOWN_FORMAT_VERSIONS: readonly string[];
 export declare function hexToBytes(hex: string): Uint8Array;
 export declare function bytesToHex(bytes: Uint8Array): string;
+/** 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;
 }
-export declare function publicKeyFromHex(crypto: CryptoOps, hexKey: string, opts?: {
+/**
+ * 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;
-}): Promise<PublicKeyInfo>;
+    keyStatus?: string;
+    notBefore?: string;
+    notAfter?: string;
+    compromisedFrom?: string;
+}
+export declare function publicKeyFromHex(crypto: CryptoOps, hexKey: string, opts?: PublicKeyOptions): Promise<PublicKeyInfo>;
+/** Verdicts for the key check (ADR-017 §2). */
+export declare const KEY_OUTSIDE_VALIDITY = "KEY_OUTSIDE_VALIDITY";
+export declare const KEY_COMPROMISED = "KEY_COMPROMISED";
+export declare const VALID_KEY_COMPROMISED_LATER = "VALID_KEY_COMPROMISED_LATER";
+export declare const VALID_KEY_WINDOW_UNKNOWN = "VALID_KEY_WINDOW_UNKNOWN";
+/** 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 declare function evaluateKey(pki: PublicKeyInfo, anchor: number | null): string;
+/**
+ * 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 declare function certificateAnchor(certificate: Record<string, unknown>): number | null;
 type Cert = Record<string, unknown>;
 /** Verify all signatures on a deletion certificate offline. */
 export declare function verifyCertificate(crypto: CryptoOps, certificate: Cert, publicKeys: Map<string, PublicKeyInfo>): Promise<VerificationResult>;
@@ -93,10 +170,11 @@ export declare 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 declare function verifyCertificateWithStatus(crypto: CryptoOps, certificate: Cert, publicKeys: Map<string, PublicKeyInfo>, status?: Record<string, unknown> | null, now?: Date): Promise<string>;

package/dist/esm/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAkB1E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CASlD;AAYD,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAQpD;AAoCD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3B,OAAO,CAAC,aAAa,CAAC,CAQxB;AAMD,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpC,+DAA+D;AAC/D,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,IAAI,EACjB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GACrC,OAAO,CAAC,kBAAkB,CAAC,CA2F7B;AAKD,+DAA+D;AAC/D,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,IAAI,EACjB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GACrC,OAAO,CAAC,kBAAkB,CAAC,CAyE7B;AAMD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,IAAI,GAAG,UAAU,CAK3D;AAoFD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAMnD;AAgVD;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,UAAU,EAAE,GAClB,OAAO,CAAC,OAAO,CAAC,CAwDlB;AAGD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,UAAU,CAoBZ;AAED,uFAAuF;AACvF,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,IAAI,EACjB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EACtC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,GAAG,CAAC,EAAE,IAAI,GACT,OAAO,CAAC,MAAM,CAAC,CAkDjB"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/verify.ts"],"names":[],"mappings":"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"}

package/dist/esm/verify.js

@@ -15,7 +15,7 @@
  *     certificate signing payload. issuanceBytes reconstructs json.Marshal
  *     output at issuance time (transparency_status=PENDING, no transparency).
  */
-import { VerificationError } from "./errors.js";
+import { CERTIFICATE_REVOKED, UNSUPPORTED_FORMAT_VERSION, VerificationError, } from "./errors.js";
 // ---------------------------------------------------------------------------
 // Pure byte helpers (no Buffer, no node:crypto)
 // ---------------------------------------------------------------------------
@@ -24,6 +24,57 @@ 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 = 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) {
+    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
@@ -95,17 +146,189 @@ export async function publicKeyFromHex(crypto, hexKey, opts) {
     }
     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 = 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 = 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, anchor) {
+    // 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) {
+    const transparency = certificate.transparency;
+    if (transparency == null)
+        return null;
+    const sth = transparency.signed_tree_head;
+    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, certificate, pki) {
+    const anchor = certificateAnchor(certificate);
+    if (anchor === null)
+        return null;
+    const transparency = certificate.transparency;
+    const sth = transparency.signed_tree_head;
+    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, anchor, keyId, 
+// 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") {
+    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;
 }
 /** Verify all signatures on a deletion certificate offline. */
 export async function verifyCertificate(crypto, certificate, publicKeys) {
+    // 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.certificate_format_version);
     const issuer = certificate.issuer;
     const keyId = issuer.key_id;
     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.
     const certPayload = buildCertificatePayload(certificate);
@@ -122,7 +345,7 @@ export async function verifyCertificate(crypto, certificate, publicKeys) {
         proof_mode: att.proof_mode,
         attested_at: att.attested_at,
         systems: attestationSystems(certificate),
-    });
+    }, certificate.certificate_format_version);
     const attSig = decodeSignature(att.attestation_signature);
     if (!(await crypto.ed25519Verify(pki.keyBytes, attPayload, attSig))) {
         throw new VerificationError("attestation signature is invalid");
@@ -172,7 +395,10 @@ export async function verifyCertificate(crypto, certificate, publicKeys) {
     if (!anyAttested) {
         throw new VerificationError("incomplete verification: no system held any records at attestation time");
     }
-    return "VALID";
+    // 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;
 }
 const NIL_UUID = "00000000-0000-0000-0000-000000000000";
 /** Verify the transparency proof embedded in a certificate. */
@@ -187,8 +413,8 @@ export async function verifyTransparency(crypto, certificate, publicKeys) {
     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);
     const headSig = decodeSignature(sth.signature);
@@ -457,7 +683,7 @@ function civilFromDays(days) {
 // ---------------------------------------------------------------------------
 // Payload builders — exact ports of core/payload.go
 // ---------------------------------------------------------------------------
-function buildAttestationPayload(subject, att) {
+function buildAttestationPayload(subject, att, certFormatVersion) {
     const attestedAt = formatTimestamp(att.attested_at);
     const systems = att.systems.map((s) => ({
         canonical_version: s.canonical_version ?? null,
@@ -475,13 +701,38 @@ function buildAttestationPayload(subject, att) {
     }));
     const payload = {
         attested_at: attestedAt,
-        payload_type: PAYLOAD_TYPE_ATTESTATION,
+        payload_type: attestationPayloadType(certFormatVersion),
         proof_mode: att.proof_mode,
         subject_hash: toHex(subject.identifier_hash),
         systems,
     };
     return canonicalJson(payload);
 }
+/** Domain separator for the record itself, by certificate format version. */
+function certificatePayloadType(version) {
+    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) {
+    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) {
     const att = cert.attestation;
     const issuer = cert.issuer;
@@ -509,15 +760,36 @@ function buildCertificatePayload(cert) {
         attested_at: formatTimestamp(att.attested_at),
         proof_mode: att.proof_mode,
     };
+    // Fields added after v3 are gated on the certificate's OWN version. A v3
+    // certificate must reconstruct to the same bytes forever; reading these
+    // unconditionally would break every certificate already issued.
+    const version = cert.certificate_format_version;
+    // 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 = {
         key_id: issuer.key_id,
         name: issuer.name,
         public_key: toHex(issuer.public_key),
     };
+    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;
+    }
+    // v5 drops identifier_type_hint: signed, but always the constant "custom",
+    // so it was never evidence. v3 and v4 keep it or they stop verifying.
     const subjectObj = {
         identifier_hash: toHex(subject.identifier_hash),
-        identifier_type_hint: subject.identifier_type_hint,
     };
+    if (!isV5Plus) {
+        subjectObj.identifier_type_hint = subject.identifier_type_hint;
+    }
     // status and revocation are deliberately absent (ADR-016 §3): a signature
     // commits to bytes at an instant, revocation is discovered later, so it
     // travels as a separate short-lived signed status statement.
@@ -528,10 +800,17 @@ function buildCertificatePayload(cert) {
         certificate_id: cert.certificate_id,
         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;
+        payload.scope = {
+            text_sha256: toHex(scope.text_sha256),
+            version: scope.version,
+        };
+    }
     return canonicalJson(payload);
 }
 /** Port of Go's BuildLogLeafPayload (ADR-016 §4). */
@@ -742,28 +1021,43 @@ 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(crypto, certificate, publicKeys, status, now) {
+    // 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;
-    }
     if (status == null) {
-        return VALID_REVOCATION_UNKNOWN;
+        return resolveWithBase(base, VALID_REVOCATION_UNKNOWN);
     }
     const keyId = status.key_id;
     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");
-    }
+    // 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
     // array depending on the producer, and every other signature on this path
@@ -774,24 +1068,59 @@ export async function verifyCertificateWithStatus(crypto, certificate, publicKey
     }
     // A validly signed statement about a different certificate must not be
     // allowed to speak for this one.
-    const certId = certificate.id ??
-        certificate.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.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)) {
+        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, verdict) {
+    return base !== "VALID" ? base : verdict;
 }
 //# sourceMappingURL=verify.js.map