burnledger 0.5.0 → 0.6.0

package/src/cli.ts

@@ -6,57 +6,97 @@ import { readFile } from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { nodeCrypto } from "./crypto-node.js";
-import { verifyCertificate, verifyTransparency, publicKeyFromHex } from "./verify.js";
-import { parseKeyEntries, type KeyEntry } from "./keys.js";
+import { CERTIFICATE_REVOKED, VerificationError } from "./errors.js";
+import {
+  formatTimestamp,
+  publicKeyFromHex,
+  verifyCertificateWithStatus,
+  verifyTransparency,
+  VALID_REVOCATION_UNKNOWN,
+} from "./verify.js";
+import {
+  KEY_LIST_STALE,
+  KEY_LIST_VALID,
+  parseKeyListDocument,
+  verifyKeyList,
+  type KeyEntry,
+  type KeyListEvidence,
+} from "./keys.js";
+import { ANCHOR_INCONSISTENT, checkStatementAnchor, type AnchorResult } from "./anchor.js";
 import type { PublicKeyInfo } from "./verify.js";
 
 type Cert = Record<string, unknown>;
-const USAGE = "Usage: burnledger check --cert <file> --keys <file> [--online --api-url <url> --api-key <key>]\n";
+/** A published status statement, exactly as GET /v1/certificates/{id}/status
+ * serves it: hex strings, not decoded bytes. verifyCertificateWithStatus reads
+ * this shape, so nothing here re-encodes a field the signature covers. */
+type StatusStatement = Record<string, unknown>;
+const USAGE = "Usage: burnledger check --cert <file> --keys <file> [--online --api-url <url>]\n";
 
 function die(msg: string): never { process.stderr.write(msg); process.exit(2); }
 
 function parseArgs(argv: string[]): {
-  certPath: string; keysPath: string; online: boolean; apiUrl: string; apiKey: string;
+  certPath: string; keysPath: string; online: boolean; apiUrl: string;
 } {
   const args = argv.slice(2);
   if (args[0] !== "check") die(USAGE);
-  let certPath = "", keysPath = "", online = false, apiUrl = "", apiKey = "";
+  let certPath = "", keysPath = "", online = false, apiUrl = "";
   for (let i = 1; i < args.length; i++) {
     const a = args[i]!;
     if (a === "--cert") { certPath = args[++i] ?? die("--cert requires a value\n"); }
     else if (a === "--keys") { keysPath = args[++i] ?? die("--keys requires a value\n"); }
     else if (a === "--online") { online = true; }
     else if (a === "--api-url") { apiUrl = args[++i] ?? die("--api-url requires a value\n"); }
-    else if (a === "--api-key") { apiKey = args[++i] ?? die("--api-key requires a value\n"); }
+    // Accepted and ignored. The status endpoint is unauthenticated, so the key
+    // buys nothing — but it is a published flag that scripts already pass, and
+    // failing on an unknown flag would break them for no gain.
+    else if (a === "--api-key") { void (args[++i] ?? die("--api-key requires a value\n")); }
     else die(`Unknown argument: ${a}\n`);
   }
   if (!certPath || !keysPath) die("Both --cert and --keys are required.\n");
   if (online) {
     try {
-      ({ apiUrl, apiKey } = resolveApiConfig(apiUrl, apiKey, process.env));
+      apiUrl = resolveApiBaseUrl(apiUrl, process.env);
     } catch (e) {
       die((e as Error).message + "\n");
     }
   }
-  return { certPath, keysPath, online, apiUrl, apiKey };
+  return { certPath, keysPath, online, apiUrl };
 }
 
 /** Flag first, then environment — the precedence docs/cli.md promises and the
- * Go CLI (cmd/cli/online.go resolveAPIConfig) implements. Exported for testing. */
-export function resolveApiConfig(
-  apiUrl: string, apiKey: string, env: Record<string, string | undefined>,
-): { apiUrl: string; apiKey: string } {
+ * Go CLI (cmd/cli/online.go resolveAPIBaseURL) implements. Exported for testing.
+ *
+ * It no longer resolves a key, and that is the change. GET
+ * /v1/certificates/{id}/status is unauthenticated by design: the audience for
+ * revocation is a relying party holding a certificate — a regulator, an
+ * auditor, the customer's customer — who has no account here and never will.
+ * Demanding an API key was what stopped that reader asking the one question the
+ * artifact exists to answer. */
+export function resolveApiBaseUrl(
+  apiUrl: string, env: Record<string, string | undefined>,
+): string {
   apiUrl ||= env.BURNLEDGER_API_URL ?? "";
   if (!apiUrl) throw new Error("--api-url or BURNLEDGER_API_URL environment variable is required for online mode");
-  apiKey ||= env.BURNLEDGER_API_KEY ?? "";
-  if (!apiKey) throw new Error("--api-key or BURNLEDGER_API_KEY environment variable is required for online mode");
-  return { apiUrl, apiKey };
+  return apiUrl;
 }
 
-async function loadKeys(path: string): Promise<Map<string, PublicKeyInfo>> {
+/** Load the key set and, separately, what the file establishes about the key
+ * STATUSES (ADR-017 §5a). The keys load the same way whether or not the file
+ * carries a signed statement — key_id == sha256(public_key) makes every
+ * identity self-checking — so an unsigned file is not refused. What changes is
+ * what this CLI is entitled to say about the statuses and dates. Mirrors
+ * loadKeysFromFile in cmd/cli/keys.go. */
+async function loadKeys(path: string): Promise<{ keys: Map<string, PublicKeyInfo>; keyList: KeyListEvidence }> {
   let entries: KeyEntry[];
+  let keyList: KeyListEvidence;
   try {
-    entries = parseKeyEntries(JSON.parse(await readFile(path, "utf-8")));
+    const doc = parseKeyListDocument(JSON.parse(await readFile(path, "utf-8")));
+    entries = doc.keys;
+    // A statement that will not verify is a verdict; one that will not PARSE
+    // is a hard error, exactly as in Go: someone signed something the reader
+    // cannot read, and continuing as though the file were merely unsigned
+    // would throw that fact away.
+    keyList = await verifyKeyList(nodeCrypto, doc, new Date());
   } catch (e) {
     die((e as Error).message + "\n");
   }
@@ -92,31 +132,117 @@ async function loadKeys(path: string): Promise<Map<string, PublicKeyInfo>> {
     }
     map.set(pki.keyId, pki);
   }
-  return map;
+  return { keys: map, keyList };
 }
 
-async function checkRevocation(apiUrl: string, apiKey: string, certId: string) {
-  const res = await fetch(`${apiUrl}/v1/certificates/${certId}/revocation-status`, {
-    headers: { Authorization: `Bearer ${apiKey}` },
-  });
-  if (!res.ok) throw new Error(`Revocation check failed: HTTP ${res.status}`);
-  return (await res.json() as { data: { status: string; reason?: string } }).data;
+/** Retrieve the SIGNED status statement for a certificate.
+ *
+ * It replaces a GET of /v1/certificates/{id}/revocation-status, which returned
+ * a bare {"status": "..."} with no signature over it. That answer was the API's
+ * word — or the word of whatever --api-url happened to point at — and this CLI
+ * printed it. Nothing about it was checkable, so a network attacker, a stale
+ * proxy or a wrong URL could suppress a revocation and the reader could not
+ * tell. Every field of this response that the verdict acts on is covered by the
+ * issuer's signature.
+ *
+ * No Authorization header is sent. The endpoint takes none, and sending an API
+ * key to an arbitrary --api-url is a credential leak the check never needed. */
+async function fetchStatusStatement(apiUrl: string, certId: string): Promise<StatusStatement> {
+  const res = await fetch(`${apiUrl.replace(/\/+$/, "")}/v1/certificates/${certId}/status`);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return unwrapStatusStatement(await res.json());
+}
+
+/** The API wraps every response in {"data": ...}; a caller may hand over either
+ * the envelope or the document inside it. Mirrors
+ * core.ParseCertificateStatusDocument, so this CLI and the Go one cannot
+ * disagree about which shape the endpoint returns. Exported for testing.
+ *
+ * A document that does not parse THROWS, and the caller turns that into a
+ * warning and a VALID_REVOCATION_UNKNOWN verdict. That is deliberate: an answer
+ * this build cannot read is silence about revocation, not a finding about the
+ * certificate. Handing a half-read document to the verifier instead would
+ * report "status statement signature is invalid" — a claim about the issuer —
+ * when what actually happened is that something returned nonsense.
+ *
+ * `status` itself is NOT validated against a known set. A statement saying
+ * SUSPENDED is a statement this build cannot read, and the verifier already has
+ * the right answer for that: it authenticates the signature first, then reports
+ * VALID_REVOCATION_UNKNOWN. Refusing it here would discard the statement before
+ * anyone authenticated it. */
+export function unwrapStatusStatement(parsed: unknown): StatusStatement {
+  if (parsed === null || typeof parsed !== "object") {
+    throw new Error("status statement: response is not a JSON object");
+  }
+  let doc = parsed as StatusStatement;
+  if (doc.certificate_id === undefined && doc.data !== null && typeof doc.data === "object") {
+    doc = doc.data as StatusStatement;
+  }
+  for (const f of ["certificate_id", "status", "key_id"]) {
+    if (typeof doc[f] !== "string" || doc[f] === "") throw new Error(`status statement: ${f} is missing`);
+  }
+  for (const f of ["statement_issued_at", "statement_expires_at"]) requireRfc3339(doc, f);
+  if (doc.revoked_at != null) requireRfc3339(doc, "revoked_at");
+  if (typeof doc.sth_tree_size !== "number") throw new Error("status statement: sth_tree_size is not a number");
+  // Refuse a short or long value rather than letting it through: a truncated
+  // signature or root hash that reaches the verifier is checked against bytes
+  // nobody sent.
+  requireHex(doc, "sth_root_hash", 32);
+  requireHex(doc, "signature", 64);
+  return doc;
+}
+
+function requireRfc3339(doc: StatusStatement, field: string): void {
+  const v = doc[field];
+  if (typeof v !== "string" || Number.isNaN(Date.parse(v))) {
+    throw new Error(`status statement: ${field} is not RFC 3339`);
+  }
 }
 
+function requireHex(doc: StatusStatement, field: string, bytes: number): void {
+  const v = doc[field];
+  if (typeof v !== "string" || !new RegExp(`^[0-9a-fA-F]{${bytes * 2}}$`).test(v)) {
+    throw new Error(`status statement: ${field} is not ${bytes} bytes of hex`);
+  }
+}
+
+/** The verdicts a reader can act on, and therefore the ones that exit 0.
+ *
+ * VALID_REVOCATION_UNKNOWN is here. It is the verdict every offline run now
+ * carries, and it means what an offline run has always meant: the document
+ * verified, and nothing was learned about revocation. Failing it would turn
+ * every existing `burnledger check` red overnight while telling the reader
+ * nothing new — the honest words are on the first line, where a human reads
+ * them, and the exit code keeps the meaning it was given. The soft KEY verdicts
+ * still exit 1, unchanged: those need a human before the record is relied on. */
+const USABLE_VERDICTS: ReadonlySet<string> = new Set(["VALID", VALID_REVOCATION_UNKNOWN]);
+
+/** The verdict word for an authenticated statement that says REVOKED.
+ *
+ * It is derived from VerificationError.code, never from the error's prose and
+ * never from the statement's own `status` field: every other rejection on the
+ * status path — unknown key, revoked key, bad signature, a statement about a
+ * different certificate — means the statement could not be authenticated, and
+ * rendering one of those as "REVOKED" would report an unauthenticated document
+ * as a fact about this certificate. */
+const REVOKED = "REVOKED";
+
 /** The pass/fail decision behind the exit code. A signature failure, a
- * transparency FAILURE (thrown, not NOT_AVAILABLE), or an online-confirmed
- * revocation all make the certificate invalid. Exported for testing. */
+ * revocation, or a transparency FAILURE (thrown, not NOT_AVAILABLE) all make
+ * the certificate unusable. Revocation is no longer a separate input: it is
+ * part of the verdict verifyCertificateWithStatus returns. Exported for
+ * testing.
+ *
+ * An INCONSISTENT anchor refuses, mirroring exitCode in cmd/cli/check.go. It is
+ * not a doubt: it is a proof, from the issuer's own signatures, that the head a
+ * statement was anchored to is not a prefix of the head the log now publishes.
+ * An anchor that could NOT be checked does not refuse — the reader is told so,
+ * and the statement still stands on its own signature. */
 export function certVerdict(
-  sigResult: string,
-  transparencyFailed: boolean,
-  online: boolean,
-  revocation: { status: string } | undefined,
+  sigResult: string, transparencyFailed: boolean, anchor?: AnchorResult,
 ): boolean {
-  return (
-    sigResult === "VALID" &&
-    !transparencyFailed &&
-    !(online && revocation?.status === "REVOKED")
-  );
+  if (anchor?.verdict === ANCHOR_INCONSISTENT) return false;
+  return USABLE_VERDICTS.has(sigResult) && !transparencyFailed;
 }
 
 /** Verdicts that are neither a pass nor a refusal, and what each one leaves
@@ -132,15 +258,21 @@ const SOFT_KEY_VERDICTS: Record<string, string> = {
     "confirm against the witness's record",
 };
 
-/** Qualifies everything this CLI says from
- * GET /v1/certificates/{id}/revocation-status. That response is a plain JSON
- * envelope with no signature over it, so it is the API's word rather than
- * something the reader can re-check. The signed form exists — a
- * certificate-status statement, which verifyCertificateWithStatus verifies —
- * and this CLI does not fetch one; until it does, saying whose word this is
- * beats printing the field as an established fact. Mirrors
- * unsignedRevocationNote in cmd/cli/format.go. */
-const UNSIGNED_REVOCATION_NOTE = "unsigned API response, not a signed status statement";
+/** What a VALID_REVOCATION_UNKNOWN verdict leaves unestablished, and there are
+ * two ways to arrive at it.
+ *
+ * Offline it is the ordinary case and always was: nothing was asked, so nothing
+ * is known. Online it means the ask failed — a status endpoint that did not
+ * answer, an answer this build could not read, or one whose window had closed.
+ * Both are silence about revocation, and silence is reported as unknown. This
+ * CLI used to report both as VALID, which reads as "checked and not revoked".
+ * Mirrors revocationUnknownOffline/Online in cmd/cli/format.go. */
+const REVOCATION_UNKNOWN_OFFLINE =
+  "offline — nothing was asked about revocation, so nothing is known; " +
+  "re-run with --online to fetch a signed status statement";
+const REVOCATION_UNKNOWN_ONLINE =
+  "no usable signed status statement — the issuer said nothing this " +
+  "build could read about revocation, which is not the same as saying the record is live";
 
 /**
  * The certificate formats whose signing payload covers enclave_pcr0.
@@ -168,37 +300,54 @@ function displayHash(v: unknown): string {
 
 export function formatOutput(
   cert: Cert, sigResult: string, transparency: string, transparencyFailed: boolean,
-  revocation: { status: string; reason?: string } | undefined, online: boolean,
+  status: StatusStatement | undefined, online: boolean, anchor?: AnchorResult,
+  keyList?: KeyListEvidence,
 ): string {
   const id = (cert.certificate_id as string).slice(0, 6);
   const sub = displayHash((cert.subject as Record<string, unknown>).identifier_hash);
   const att = cert.attestation as Record<string, unknown>;
   const L: string[] = [];
 
+  // A proven-inconsistent anchor outranks every verdict below it, including
+  // REVOKED. The issuer has contradicted itself about an append-only structure,
+  // so nothing it says about this record — revoked or live — can be taken at
+  // face value, and printing "REVOKED" or "VALID" here would answer a question
+  // that is no longer the important one. Mirrors formatResult in
+  // cmd/cli/format.go, which puts this branch in the same place.
+  if (anchor?.verdict === ANCHOR_INCONSISTENT) {
+    L.push(`Verification record dc_${id}: INVALID (LOG_ANCHOR_INCONSISTENT)`);
+    L.push(`  ${anchor.detail}`);
+    L.push(`  The certificate itself verified as ${sigResult}; the issuer's log is what does not add up.`);
+    pushStatementEvidence(L, status);
+    return L.join("\n") + "\n";
+  }
+
   // A soft key verdict is not a forgery: every signature verified, and what
   // could not be established is the key's authority. "INVALID" would send an
   // auditor hunting for tampering that is not there, and "VALID" — which this
   // CLI printed — claims a check that did not happen.
   const note = SOFT_KEY_VERDICTS[sigResult];
   if (note !== undefined) return `Verification record dc_${id}: ${sigResult} (${note})\n`;
-  if (sigResult !== "VALID") return `Verification record dc_${id}: INVALID (${sigResult})\n`;
-  if (transparencyFailed) return `Verification record dc_${id}: INVALID (transparency: ${transparency})\n`;
-  if (online && revocation?.status === "REVOKED") {
+  // Revocation is now a signed fact, so the reader gets the evidence with the
+  // verdict: who said it, when, and which log entry it points at.
+  if (sigResult === REVOKED) {
     L.push(`Verification record dc_${id}: INVALID (REVOKED)`);
-    if (revocation.reason) L.push(`  Revocation reason: ${revocation.reason}`);
-    // Fail closed on the API's word — an unbelieved revocation is the worse
-    // error — but name the source: this verdict rests on the same unsigned
-    // field as the one below.
-    L.push(`  Revocation source: ${UNSIGNED_REVOCATION_NOTE}`);
+    pushStatementEvidence(L, status);
+    pushAnchorEvidence(L, anchor);
     return L.join("\n") + "\n";
   }
+  if (!USABLE_VERDICTS.has(sigResult)) return `Verification record dc_${id}: INVALID (${sigResult})\n`;
+  if (transparencyFailed) return `Verification record dc_${id}: INVALID (transparency: ${transparency})\n`;
 
-  // An --online answer is not a stronger answer, only a different one, so the
-  // qualifier is replaced rather than dropped.
-  const tag = online
-    ? ` (the API reports it is not revoked; ${UNSIGNED_REVOCATION_NOTE})`
-    : " (offline — revocation status not checked)";
-  L.push(`Verification record dc_${id}: VALID${tag}`);
+  // The two usable verdicts. VALID is sayable without a qualifier for the first
+  // time: it is reached only when a fresh statement, signed by a key from the
+  // key file and naming this certificate, said ACTIVE. Everything short of that
+  // is VALID_REVOCATION_UNKNOWN and says so in the verdict itself, not in a
+  // footnote a script will never read.
+  const tag = sigResult === VALID_REVOCATION_UNKNOWN
+    ? `${VALID_REVOCATION_UNKNOWN} (${online ? REVOCATION_UNKNOWN_ONLINE : REVOCATION_UNKNOWN_OFFLINE})`
+    : "VALID (a signed status statement says this record is live)";
+  L.push(`Verification record dc_${id}: ${tag}`);
   L.push(`  Subject: sha256:${sub.slice(0, 6)}...`);
   L.push(`  Format version: ${cert.certificate_format_version as string}`);
 
@@ -246,12 +395,90 @@ export function formatOutput(
   } else {
     L.push(`  Transparency log: ${transparency === "NOT_AVAILABLE" ? "not included" : transparency}`);
   }
-  if (online && revocation) {
-    L.push(`  Revocation status: ${revocation.status} (${UNSIGNED_REVOCATION_NOTE})`);
-  }
+  pushStatementEvidence(L, status);
+  pushAnchorEvidence(L, anchor);
+  pushKeyListEvidence(L, keyList);
   return L.join("\n") + "\n";
 }
 
+/** Where the key statuses this verdict rests on came from, printed on every
+ * run — including the ordinary one, where the answer is "an unsigned list".
+ *
+ * ADR-017 §5a's point is not that an unsigned key list is unusable. It is that
+ * the two halves of a key set have different lifetimes: key_id is
+ * sha256(public_key), so every key's IDENTITY is self-checking offline forever,
+ * while its status and dates are only as good as the endpoint they were
+ * fetched from and the moment they were fetched. Mirrors writeKeyListEvidence
+ * in cmd/cli/format.go, word for word, so the four verifiers say one thing. */
+function pushKeyListEvidence(L: string[], e: KeyListEvidence | undefined): void {
+  if (e === undefined) return;
+  if (!e.present) {
+    L.push("  Key statuses: unsigned key list — identities are self-checking " +
+      "(key_id = sha256(public_key)); statuses and dates are not evidenced");
+    return;
+  }
+  if (e.result === KEY_LIST_VALID) {
+    L.push(`  Key statuses: signed key_list.v3, VALID until ${e.expiresAt}`);
+    if (e.selfSigned) {
+      // Said out loud, every time. A list that vouches for itself proves only
+      // that whoever wrote it holds the key it names, and a reader who does
+      // not know that will read "VALID" as more than it is.
+      L.push("  Key list trust: the list is signed by a key inside itself — " +
+        "trust-on-first-use, not proof; pin this file and compare it on later runs");
+    }
+    return;
+  }
+  if (e.result === KEY_LIST_STALE) {
+    L.push(`  Key statuses: signed key_list.v3, but its window closed at ${e.expiresAt} — ` +
+      "the identities still check, the statuses no longer do");
+    return;
+  }
+  L.push(`  Key statuses: signed key_list.v3 did NOT verify (${e.result}) — ` +
+    "treat its statuses and dates as unevidenced");
+}
+
+/** Whether the statement's log anchor was tested, and how it came out.
+ *
+ * The UNVERIFIED line matters as much as the CONFIRMED one. A statement whose
+ * anchor could not be checked is a statement that rests entirely on its
+ * issuer's signature, and a reader who is not told that will assume the stronger
+ * thing — which is the mistake this whole command has been correcting. Mirrors
+ * writeAnchorEvidence in cmd/cli/format.go. */
+function pushAnchorEvidence(L: string[], anchor: AnchorResult | undefined): void {
+  if (anchor === undefined) return;
+  L.push(`  Statement log anchor: ${anchor.verdict} (${anchor.detail})`);
+}
+
+/** What the signed statement said, and by whom.
+ *
+ * Nothing is printed when there is no statement: the verdict line has already
+ * told the reader that revocation is unknown, and a "Revocation status: n/a"
+ * line here would put a word where there is no evidence.
+ *
+ * `Statement signed by` is not decoration. The verdict rests on that key, the
+ * key came from the reader's own --keys file, and naming it is what lets an
+ * auditor say which key they are trusting rather than "the API said so".
+ * Mirrors writeStatementEvidence in cmd/cli/format.go. */
+function pushStatementEvidence(L: string[], status: StatusStatement | undefined): void {
+  if (status === undefined) return;
+  L.push(`  Revocation status: ${String(status.status)} (signed status statement)`);
+  L.push(`  Statement signed by: ${String(status.key_id)}`);
+  L.push(`  Statement valid: ${formatTimestamp(status.statement_issued_at)} to ` +
+    `${formatTimestamp(status.statement_expires_at)}`);
+  // The head the issuer had seen when it spoke. Printed as evidence; whether it
+  // is a prefix of the head the log publishes now is a separate question, and
+  // the "Statement log anchor" line below answers it (anchor.ts).
+  L.push(`  Statement anchored to: tree size ${String(status.sth_tree_size)}, ` +
+    `root ${displayHash(status.sth_root_hash)}`);
+  if (status.revoked_at != null) L.push(`  Revoked at: ${formatTimestamp(status.revoked_at)}`);
+  if (status.replacement_certificate_id != null) {
+    L.push(`  Replaced by: ${String(status.replacement_certificate_id)}`);
+  }
+  if (status.revocation_log_index != null) {
+    L.push(`  Revocation log entry: #${String(status.revocation_log_index)}`);
+  }
+}
+
 /** Accept the raw API response too: GET /v1/certificates/{id} nests the
  * signed certificate as data.certificate. Exported for testing. */
 export function unwrapCertificate(parsed: Cert): Cert {
@@ -269,15 +496,51 @@ export function unwrapCertificate(parsed: Cert): Cert {
 async function main(): Promise<void> {
   const args = parseArgs(process.argv);
   const cert = unwrapCertificate(JSON.parse(await readFile(args.certPath, "utf-8")) as Cert);
-  const keys = await loadKeys(args.keysPath);
+  const { keys, keyList } = await loadKeys(args.keysPath);
+
+  // Fetched first, because the verdict now depends on it. A status statement is
+  // an input to the verdict, not a footnote printed beside one:
+  // verifyCertificateWithStatus answers REVOKED, VALID or
+  // VALID_REVOCATION_UNKNOWN from the same call, and splitting that decision
+  // across two checks is how this CLI ended up printing VALID for a certificate
+  // whose revocation it had never established.
+  let status: StatusStatement | undefined;
+  let anchor: AnchorResult | undefined;
+  if (args.online) {
+    try {
+      status = await fetchStatusStatement(args.apiUrl, cert.certificate_id as string);
+    } catch (e) {
+      // Non-fatal, and NOT a pass. Leaving `status` undefined sends the verdict
+      // to VALID_REVOCATION_UNKNOWN rather than to VALID: an endpoint that did
+      // not answer has said nothing about revocation, and the older code
+      // reported that silence as a clean bill of health.
+      process.stderr.write(
+        `warning: signed status statement unavailable: ${e instanceof Error ? e.message : String(e)}\n`,
+      );
+    }
+    // The statement's anchor is only checkable against the log, and only with a
+    // key the reader already holds. A statement signed by a key that is not in
+    // --keys cannot be authenticated at all, so there is nothing to anchor and
+    // no anchor line is printed. See anchor.ts for what this does and does not
+    // close.
+    if (status !== undefined) {
+      const key = keys.get(status.key_id as string);
+      if (key !== undefined) {
+        anchor = await checkStatementAnchor(nodeCrypto, args.apiUrl, status, key);
+      }
+    }
+  }
 
   // The verifier's own verdict, never a hardcoded word. VALID_KEY_WINDOW_UNKNOWN
-  // and VALID_KEY_COMPROMISED_LATER are cases verifyCertificate deliberately
-  // refused to call VALID, and this is the tool an auditor runs in a script —
-  // the one whose exit code gets trusted.
+  // and VALID_KEY_COMPROMISED_LATER are cases verifyCertificateWithStatus
+  // deliberately refused to call VALID, and this is the tool an auditor runs in
+  // a script — the one whose exit code gets trusted.
   let sigResult = "VALID";
-  try { sigResult = await verifyCertificate(nodeCrypto, cert, keys); }
-  catch (e) { sigResult = e instanceof Error ? e.message : "unknown error"; }
+  try { sigResult = await verifyCertificateWithStatus(nodeCrypto, cert, keys, status ?? null); }
+  catch (e) {
+    if (e instanceof VerificationError && e.code === CERTIFICATE_REVOKED) sigResult = REVOKED;
+    else sigResult = e instanceof Error ? e.message : "unknown error";
+  }
 
   // NOT_AVAILABLE (no proof) is a legitimate result; only a thrown error is a
   // transparency FAILURE and must fail the verdict + exit code.
@@ -286,12 +549,11 @@ async function main(): Promise<void> {
   try { transparency = await verifyTransparency(nodeCrypto, cert, keys); }
   catch (e) { transparency = e instanceof Error ? e.message : "unknown error"; transparencyFailed = true; }
 
-  let revocation: { status: string; reason?: string } | undefined;
-  if (args.online) revocation = await checkRevocation(args.apiUrl, args.apiKey, cert.certificate_id as string);
-
-  const valid = certVerdict(sigResult, transparencyFailed, args.online, revocation);
+  const valid = certVerdict(sigResult, transparencyFailed, anchor);
 
-  process.stdout.write(formatOutput(cert, sigResult, transparency, transparencyFailed, revocation, args.online));
+  process.stdout.write(
+    formatOutput(cert, sigResult, transparency, transparencyFailed, status, args.online, anchor, keyList),
+  );
   process.exit(valid ? 0 : 1);
 }
 

package/src/client.ts

@@ -11,6 +11,7 @@ import type {
   ApiKeyResponse,
   Attestation,
   BatchAttestationResponse,
+  BatchRevokeResponse,
   CertificateResponse,
   CertificateStats,
   ConsistencyProof,
@@ -31,6 +32,7 @@ import {
   parseApiKeyResponse,
   parseAttestation,
   parseBatchAttestationResponse,
+  parseBatchRevokeResponse,
   parseCertificateResponse,
   parseCertificateStats,
   parseConsistencyProof,
@@ -65,6 +67,10 @@ export interface BurnLedgerOptions {
   teamId?: string;
 }
 
+/** Per-call cap on POST /v1/certificates/batch-revoke, the same 100 the
+ * server enforces (service.maxBatchRevoke). Chunk larger sets by this. */
+export const MAX_BATCH_REVOKE = 100;
+
 export class BurnLedger {
   private readonly transport: Transport;
 
@@ -306,6 +312,27 @@ export class BurnLedger {
     return parseCertificateResponse(data as Raw);
   }
 
+  /** Revokes up to MAX_BATCH_REVOKE records under one reason. Partial
+   * completion is the normal case, not an exception: inspect `errors`. */
+  async batchRevokeCertificates(
+    certificateIds: string[],
+    opts: { reason: string },
+  ): Promise<BatchRevokeResponse> {
+    if (certificateIds.length > MAX_BATCH_REVOKE) {
+      // The server answers 400 and revokes nothing; failing here spares the
+      // caller a rate-limited round trip for a request that cannot succeed.
+      throw new Error(
+        `batchRevokeCertificates: ${certificateIds.length} ids exceeds the limit of ${MAX_BATCH_REVOKE} per call`,
+      );
+    }
+    const data = await this.transport.request(
+      "POST",
+      "/v1/certificates/batch-revoke",
+      { json: { certificate_ids: certificateIds, reason: opts.reason } },
+    );
+    return parseBatchRevokeResponse(data as Raw);
+  }
+
   async getCertificateStats(): Promise<CertificateStats> {
     const data = await this.transport.request("GET", "/v1/certificates/stats");
     return parseCertificateStats(data as Raw);
@@ -396,10 +423,14 @@ export class BurnLedger {
     );
   }
 
-  async createApiKey(): Promise<ApiKeyResponse> {
-    const data = await this.transport.request("POST", "/v1/api-keys", {
-      json: {},
-    });
+  /** Create an API key. `teamId` pins it to one team the caller belongs to:
+   * a pinned key always acts for that team and refuses a conflicting
+   * `X-Team-ID` with 403. Omitted means unpinned — the server resolves the
+   * team per request, as every key created before pinning existed does. */
+  async createApiKey(params?: { teamId?: string }): Promise<ApiKeyResponse> {
+    const json: Record<string, unknown> = {};
+    if (params?.teamId !== undefined) json.team_id = params.teamId;
+    const data = await this.transport.request("POST", "/v1/api-keys", { json });
     return parseApiKeyResponse(data as Raw);
   }