burnledger 0.8.1 → 0.9.1

package/src/cli.ts

@@ -9,7 +9,9 @@ import { nodeCrypto } from "./crypto-node.js";
 import { CERTIFICATE_REVOKED, VerificationError } from "./errors.js";
 import {
   formatTimestamp,
+  issuingImage,
   publicKeyFromHex,
+  registrationQualifier,
   verifyCertificateWithStatus,
   verifyTransparency,
   KNOWN_FORMAT_VERSIONS,
@@ -24,23 +26,34 @@ import {
   type KeyListEvidence,
 } from "./keys.js";
 import { ANCHOR_INCONSISTENT, checkStatementAnchor, type AnchorResult } from "./anchor.js";
-import type { PublicKeyInfo } from "./verify.js";
+import { unwrapStatusStatement } from "./status-document.js";
+import type { AuthorizationPolicy, PublicKeyInfo } from "./verify.js";
+
+// Exported from here too: tests/cli-revocation-unknown.test.ts reads it as the
+// CLI's own parser.
+export { unwrapStatusStatement };
 
 type Cert = Record<string, unknown>;
 /** 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";
+const USAGE =
+  "Usage: burnledger check --cert <file> --keys <file> [--online --api-url <url>]\n" +
+  "       [[--require-certified | --require-certified-system <system_id>...] --customer-key-id <id>...]\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;
+  policy: AuthorizationPolicy | undefined;
 } {
   const args = argv.slice(2);
   if (args[0] !== "check") die(USAGE);
   let certPath = "", keysPath = "", online = false, apiUrl = "";
+  let requireCertified = false;
+  const systems: string[] = [];
+  const keyIds: string[] = [];
   for (let i = 1; i < args.length; i++) {
     const a = args[i]!;
     if (a === "--cert") { certPath = args[++i] ?? die("--cert requires a value\n"); }
@@ -51,9 +64,29 @@ function parseArgs(argv: string[]): {
     // 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")); }
+    // ADR-025. Opt-in: without these, authorization: none verifies as it always
+    // has. The Go CLI has no equivalent yet; these names are the proposal for it.
+    else if (a === "--require-certified") { requireCertified = true; }
+    else if (a === "--require-certified-system") {
+      systems.push(args[++i] ?? die("--require-certified-system requires a value\n"));
+    }
+    else if (a === "--customer-key-id") { keyIds.push(args[++i] ?? die("--customer-key-id requires a value\n")); }
     else die(`Unknown argument: ${a}\n`);
   }
   if (!certPath || !keysPath) die("Both --cert and --keys are required.\n");
+  // Every system, or these systems: asking for both is a mistake to name, not
+  // one to resolve silently in either direction.
+  if (requireCertified && systems.length > 0) {
+    die("--require-certified and --require-certified-system are alternatives; use one\n");
+  }
+  // Certified under a key id you did not name proves nothing to you: the relay
+  // can enroll a key group of its own, and the record would name that one.
+  if ((requireCertified || systems.length > 0) && keyIds.length === 0) {
+    die(
+      "--require-certified and --require-certified-system need --customer-key-id <id>: " +
+        "certified under a key you did not name proves nothing\n",
+    );
+  }
   if (online) {
     try {
       apiUrl = resolveApiBaseUrl(apiUrl, process.env);
@@ -61,7 +94,9 @@ function parseArgs(argv: string[]): {
       die((e as Error).message + "\n");
     }
   }
-  return { certPath, keysPath, online, apiUrl };
+  const policy: AuthorizationPolicy | undefined =
+    keyIds.length > 0 ? { ...(systems.length > 0 ? { systems } : {}), customerKeyIds: keyIds } : undefined;
+  return { certPath, keysPath, online, apiUrl, policy };
 }
 
 /** Flag first, then environment — the precedence docs/cli.md promises and the
@@ -86,8 +121,8 @@ export function resolveApiBaseUrl(
  * 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 }> {
+ * loadKeysFromFile in cmd/cli/keys.go. Exported for testing. */
+export async function loadKeys(path: string): Promise<{ keys: Map<string, PublicKeyInfo>; keyList: KeyListEvidence }> {
   let entries: KeyEntry[];
   let keyList: KeyListEvidence;
   try {
@@ -147,64 +182,61 @@ async function loadKeys(path: string): Promise<{ keys: Map<string, PublicKeyInfo
  * 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.
+ * key to an arbitrary --api-url is a credential leak the check never needed.
  *
- * `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`);
+ * Read under a 1 MiB cap and a total deadline, matching the anchor fetch
+ * (anchor.ts) and the Go CLI (cmd/cli/online.go): a status statement is a few
+ * hundred bytes, so anything near the cap is a misbehaving or hostile server.
+ * The AbortController bounds the whole fetch including the body read, which a
+ * server dripping bytes could otherwise hold open. Exported for testing. */
+export async function fetchStatusStatement(apiUrl: string, certId: string): Promise<StatusStatement> {
+  const url = `${apiUrl.replace(/\/+$/, "")}/v1/certificates/${certId}/status`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => { controller.abort(); }, STATUS_FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    const body = await readCapped(res);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    try {
+      return unwrapStatusStatement(JSON.parse(body));
+    } catch (e) {
+      throw new Error(`parse response: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  } finally {
+    clearTimeout(timer);
   }
-  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`);
+/** How much of the status response to buffer (1 MiB) and how long the whole
+ * fetch may take (10 s), matching cmd/cli/online.go and anchor.ts. */
+const MAX_STATUS_BYTES = 1 << 20;
+const STATUS_FETCH_TIMEOUT_MS = 10_000;
+
+/** Read a response body, stopping at the cap instead of buffering whatever a
+ * hostile server decides to send. The stream is cancelled on the way out, so an
+ * endless body costs one megabyte and not the process. */
+async function readCapped(res: Response): Promise<string> {
+  const reader = res.body?.getReader();
+  if (reader === undefined) return "";
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.length;
+    if (total > MAX_STATUS_BYTES) {
+      await reader.cancel();
+      throw new Error(`read response: body exceeds ${MAX_STATUS_BYTES} bytes`);
+    }
+    chunks.push(value);
   }
-}
-
-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`);
+  const joined = new Uint8Array(total);
+  let at = 0;
+  for (const c of chunks) {
+    joined.set(c, at);
+    at += c.length;
   }
+  return new TextDecoder().decode(joined);
 }
 
 /** The verdicts a reader can act on, and therefore the ones that exit 0.
@@ -321,8 +353,15 @@ function pushRecordCounts(L: string[], sys: Record<string, unknown>[]): void {
 }
 
 /**
- * Per system: did the enclave check it against a customer-signed registration,
- * and under which key?
+ * Per system: did the enclave check it against a registration, under which key,
+ * and what does the image that signed the record make of that?
+ *
+ * Printed for exactly the verdicts that say the record's own signature
+ * verified: VALID, VALID_REVOCATION_UNKNOWN, the two soft key verdicts and
+ * REVOKED, as in the Go and Python CLIs and the /verify page. The qualifier is
+ * read from issuer.enclave_pcr0, which that signature covers, and
+ * verifyCertificate checks it before any of those verdicts is reached. Beside
+ * INVALID the field is unverified bytes, so nothing is printed there.
  *
  * This line is the WHOLE POINT of the field. ADR-025 §2: the enclave cannot
  * refuse a second enrollment for a team — that needs durable state — so a parent
@@ -344,14 +383,11 @@ function pushRegistrationEvidence(L: string[], cert: Record<string, unknown>): v
     );
     return;
   }
+  const qualifier = registrationQualifier(issuingImage(cert));
   for (const sys of (cert.systems as Record<string, unknown>[]) ?? []) {
     const name = sys.system_name as string;
     if (sys.authorization === "certified") {
-      L.push(
-        `  Registration [${name}]: certified under ${sys.customer_key_id as string} — ` +
-          "the enclave checked this system against a customer-signed registration. " +
-          "If that key id is not yours, someone else authorized this verification.",
-      );
+      L.push(`  Registration [${name}]: certified under ${sys.customer_key_id as string} — ${qualifier}`);
     } else if (sys.authorization === "none") {
       L.push(
         `  Registration [${name}]: none — this verification was NOT checked against ` +
@@ -388,8 +424,9 @@ export function formatOutput(
   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);
+  // This line prints for records that FAILED verification too, so it must not
+  // assume the shape verification would have checked.
+  const id = typeof cert.certificate_id === "string" ? cert.certificate_id.slice(0, 6) : "unknown";
   const att = cert.attestation as Record<string, unknown>;
   const L: string[] = [];
 
@@ -407,22 +444,33 @@ export function formatOutput(
     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`;
   // 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)`);
+    pushRegistrationEvidence(L, cert);
     pushStatementEvidence(L, status);
     pushAnchorEvidence(L, anchor);
     return L.join("\n") + "\n";
   }
-  if (!USABLE_VERDICTS.has(sigResult)) return `Verification record dc_${id}: INVALID (${sigResult})\n`;
+  const note = SOFT_KEY_VERDICTS[sigResult];
+  if (!USABLE_VERDICTS.has(sigResult) && note === undefined) {
+    return `Verification record dc_${id}: INVALID (${sigResult})\n`;
+  }
+  // A failed proof refuses the record, and it outranks a soft key verdict: a
+  // verdict that asks for a human must not hide one that refuses. The Python
+  // CLI and the /verify page already put it first; this CLI and Go printed
+  // the soft verdict instead.
   if (transparencyFailed) return `Verification record dc_${id}: INVALID (transparency: ${transparency})\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.
+  if (note !== undefined) {
+    L.push(`Verification record dc_${id}: ${sigResult} (${note})`);
+    pushRegistrationEvidence(L, cert);
+    return L.join("\n") + "\n";
+  }
 
   // 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
@@ -433,6 +481,7 @@ export function formatOutput(
     ? `${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}`);
+  const sub = displayHash((cert.subject as Record<string, unknown>).identifier_hash);
   L.push(`  Subject: sha256:${sub.slice(0, 6)}...`);
   L.push(`  Format version: ${cert.certificate_format_version as string}`);
 
@@ -583,7 +632,13 @@ 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 parsed: unknown = JSON.parse(await readFile(args.certPath, "utf-8"));
+  // No record to give a verdict about. Go's loader refuses the same file at
+  // unmarshal and exits 2, as this does.
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    die(`${args.certPath}: not a JSON object\n`);
+  }
+  const cert = unwrapCertificate(parsed as Cert);
   const { keys, keyList } = await loadKeys(args.keysPath);
 
   // Fetched first, because the verdict now depends on it. A status statement is
@@ -623,11 +678,19 @@ async function main(): Promise<void> {
   // 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.
+  //
+  // Only a VerificationError is a verdict. Anything else is a defect in this
+  // CLI or the SDK under it; printing it as INVALID dressed a crash up as a
+  // finding about the record, so it propagates and exits 2 instead.
   let sigResult = "VALID";
-  try { sigResult = await verifyCertificateWithStatus(nodeCrypto, cert, keys, status ?? null); }
+  try {
+    sigResult = await verifyCertificateWithStatus(nodeCrypto, cert, keys, status ?? null, undefined, {
+      requireAuthorization: args.policy,
+    });
+  }
   catch (e) {
-    if (e instanceof VerificationError && e.code === CERTIFICATE_REVOKED) sigResult = REVOKED;
-    else sigResult = e instanceof Error ? e.message : "unknown error";
+    if (!(e instanceof VerificationError)) throw e;
+    sigResult = e.code === CERTIFICATE_REVOKED ? REVOKED : e.message;
   }
 
   // NOT_AVAILABLE (no proof) is a legitimate result; only a thrown error is a
@@ -635,7 +698,11 @@ async function main(): Promise<void> {
   let transparency = "NOT_AVAILABLE";
   let transparencyFailed = false;
   try { transparency = await verifyTransparency(nodeCrypto, cert, keys); }
-  catch (e) { transparency = e instanceof Error ? e.message : "unknown error"; transparencyFailed = true; }
+  catch (e) {
+    if (!(e instanceof VerificationError)) throw e;
+    transparency = e.message;
+    transparencyFailed = true;
+  }
 
   const valid = certVerdict(sigResult, transparencyFailed, anchor);