burnledger 0.4.0 → 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";
 
 // ---------------------------------------------------------------------------
@@ -40,6 +44,52 @@ 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
@@ -137,16 +187,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 +240,24 @@ 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
@@ -215,7 +297,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 +320,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,6 +407,12 @@ 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;
 
@@ -267,7 +420,11 @@ export async function verifyCertificate(
   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.
@@ -711,10 +868,7 @@ function buildAttestationPayload(
 
   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 +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>;
@@ -756,8 +932,11 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   // 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;
+  const isV4Plus = version === FORMAT_VERSION_V4 || isV5Plus;
 
   const issuerObj: Record<string, unknown> = {
     key_id: issuer.key_id as string,
@@ -769,7 +948,7 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   }
   // 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 +957,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 +971,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,
   };
@@ -1059,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(
@@ -1072,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;
@@ -1085,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
@@ -1118,17 +1314,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);
   }
-  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);
 }