burnledger 0.9.0 → 0.10.0

package/src/cli.ts

@@ -4,10 +4,12 @@
 
 import { readFile } from "node:fs/promises";
 import { realpathSync } from "node:fs";
+import { basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { nodeCrypto } from "./crypto-node.js";
 import { CERTIFICATE_REVOKED, VerificationError } from "./errors.js";
 import {
+  bytesToHex,
   formatTimestamp,
   issuingImage,
   publicKeyFromHex,
@@ -27,6 +29,8 @@ import {
 } from "./keys.js";
 import { ANCHOR_INCONSISTENT, checkStatementAnchor, type AnchorResult } from "./anchor.js";
 import { unwrapStatusStatement } from "./status-document.js";
+import { chainAuditPackPages, verifyAuditPack, type AuditPackPage, type AuditPackResult } from "./audit-pack.js";
+import { checkRunAgainstRecords, type RunCheckRecord, type RunRecord } from "./run-record.js";
 import type { AuthorizationPolicy, PublicKeyInfo } from "./verify.js";
 
 // Exported from here too: tests/cli-revocation-unknown.test.ts reads it as the
@@ -40,23 +44,26 @@ type Cert = Record<string, unknown>;
 type StatusStatement = Record<string, unknown>;
 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";
+  "       [[--require-certified | --require-certified-system <system_id>...] --customer-key-id <id>...]\n" +
+  "       burnledger check --pack <file> [--pack <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;
+  certPath: string; packPaths: 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 packPaths: string[] = [];
   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"); }
+    else if (a === "--pack") { packPaths.push(args[++i] ?? die("--pack 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"); }
@@ -73,7 +80,17 @@ function parseArgs(argv: string[]): {
     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");
+  // One record or a pack of them, never both: the two have different verdicts,
+  // different exit codes and different output, and a run that printed one
+  // after the other would leave a script reading the wrong first line.
+  if (packPaths.length > 0 && certPath) die("--pack and --cert are alternatives; use one\n");
+  if (packPaths.length === 0 && (!certPath || !keysPath)) die("Both --cert and --keys are required.\n");
+  // The authorization policy is a question about one record's systems. Over a
+  // pack it would need a per-record answer the pack output has no line for,
+  // and refusing it is better than silently ignoring a flag that says "fail".
+  if (packPaths.length > 0 && (requireCertified || systems.length > 0 || keyIds.length > 0)) {
+    die("--require-certified, --require-certified-system and --customer-key-id are for a single --cert, not --pack\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) {
@@ -96,7 +113,7 @@ function parseArgs(argv: string[]): {
   }
   const policy: AuthorizationPolicy | undefined =
     keyIds.length > 0 ? { ...(systems.length > 0 ? { systems } : {}), customerKeyIds: keyIds } : undefined;
-  return { certPath, keysPath, online, apiUrl, policy };
+  return { certPath, packPaths, keysPath, online, apiUrl, policy };
 }
 
 /** Flag first, then environment — the precedence docs/cli.md promises and the
@@ -182,11 +199,61 @@ export async function loadKeys(path: string): Promise<{ keys: Map<string, Public
  * 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());
+ * key to an arbitrary --api-url is a credential leak the check never needed.
+ *
+ * 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);
+  }
+}
+
+/** 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);
+  }
+  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.
@@ -271,7 +338,7 @@ const REVOCATION_UNKNOWN_ONLINE =
  * enclave measurement was unattributable when the signature covers it.
  * scripts/check-pcr0-signed-parity.py now pins this list to the Go function.
  */
-const ENCLAVE_PCR0_SIGNED_IN: readonly string[] = Object.freeze(["5.0", "6.0", "7.0", "8.0", "9.0"]);
+const ENCLAVE_PCR0_SIGNED_IN: readonly string[] = Object.freeze(["5.0", "6.0", "7.0", "8.0", "9.0", "10.0"]);
 
 function signatureCoversEnclavePcr0(version: string): boolean {
   return ENCLAVE_PCR0_SIGNED_IN.includes(version);
@@ -566,6 +633,217 @@ function pushStatementEvidence(L: string[], status: StatusStatement | undefined)
   }
 }
 
+/** One page's block, laid out as docs/audit-pack.md specifies. Every line is
+ * evidence the verdict rests on, and the two that qualify it — where the keys
+ * came from, and whether another page exists — are printed on a VERIFIED page
+ * too, because that word says nothing about either. Exported for testing:
+ * docs/cli.md pins two of these blocks byte for byte. */
+export function formatAuditPackOutput(
+  fileName: string, result: AuditPackResult, opts: { keysFile?: string; online: boolean },
+): string {
+  const name = basename(fileName);
+  if (result.verdict === "UNREADABLE") return `Audit pack ${name}: UNREADABLE (${result.reason})\n`;
+  // Every readable result carries a header; the scanner refuses a page
+  // without one before a verdict is reached.
+  const header = result.header!;
+  const L: string[] = [];
+  L.push(`Audit pack ${name}: ${result.verdict}`);
+  L.push(`  Format: ${header.format}`);
+  L.push(`  Generated: ${header.generatedAt}`);
+  L.push(`  Records: ${result.records - result.failed.length} verified, ${result.failed.length} refused`);
+  L.push(`  Not yet in the log: ${result.notIncluded}`);
+  L.push(`  Labeled revoked by the issuer: ${result.revoked} (unsigned; re-run with --online to evidence)`);
+  if (opts.online) {
+    L.push(`  Revoked by signed statement: ${result.statusRevoked} of ${result.statusChecked} checked`);
+    if (result.statusRevoked > 0) {
+      L.push("  Revoked:");
+      for (const id of result.revokedIds) L.push(`    ${id}`);
+    }
+  }
+  L.push(
+    result.keysFromPack
+      ? "  Keys: from the pack itself (trust on first use; pass --keys to pin them)"
+      : `  Keys: from ${basename(opts.keysFile ?? "")}`,
+  );
+  const treeSize = header.logHead?.tree_size ?? 0;
+  switch (result.logHead) {
+    case "VALID":
+      L.push(`  Log head: tree size ${treeSize}, signature VALID under ${result.logHeadKeyId}`);
+      break;
+    case "ABSENT":
+      L.push("  Log head: absent");
+      break;
+    case "INVALID_SIGNATURE":
+      L.push(`  Log head: tree size ${treeSize}, signature INVALID_SIGNATURE (no key in use signed it)`);
+      break;
+    case "UNREADABLE":
+      L.push("  Log head: unreadable");
+      break;
+  }
+  L.push(`  Digest: sha256:${result.digest}`);
+  if (result.run !== null) {
+    let inclusion = "not yet in the log";
+    if (result.runInclusion === "VALID") {
+      // VALID is only reached through a proof, whose entry_index the
+      // inclusion check read as an exact integer.
+      inclusion = `in the log at index ${String(result.run.transparency!.entry_index)}`;
+    } else if (result.runInclusion !== "NOT_INCLUDED") {
+      inclusion = `inclusion ${result.runInclusion}`;
+    }
+    L.push(`  Run record: ${result.runResult} under ${result.run.issuer.keyId}, ${inclusion}`);
+  }
+  switch (result.footerStatement) {
+    case "VALID":
+      // VALID is only reached through a footer that carries signed fields; the
+      // instant is printed as the file wrote it, as the Go CLI prints it.
+      L.push(
+        `  Footer: signed under ${result.footerKeyId} at ${result.footer!.signed!.statement_issued_at} ` +
+          "(count and digest attested by the issuer)",
+      );
+      break;
+    case "UNSIGNED":
+      L.push("  Footer: unsigned (count and digest are the issuer's unsigned word)");
+      break;
+    default:
+      L.push(`  Footer: ${result.footerStatement}`);
+  }
+  if (result.footer === null) {
+    L.push("  Next page: unknown (no footer)");
+  } else if (result.footer.nextCursor === null) {
+    L.push("  Next page: none");
+  } else {
+    L.push(`  Next page: ${result.footer.nextCursor} (more pages exist; this file alone is not the whole answer)`);
+  }
+  if (result.failed.length > 0) {
+    L.push("  Refused:");
+    for (const f of result.failed) {
+      L.push(f.certificateId === "" ? `    #${f.index}: ${f.reason}` : `    #${f.index} ${f.certificateId}: ${f.reason}`);
+    }
+  }
+  if (result.verdict !== "VERIFIED") L.push(`  Findings: ${result.reason}`);
+  return L.join("\n") + "\n";
+}
+
+/** The chain line printed after several pages. Exported for testing. */
+export function formatAuditPackChain(chain: ReturnType<typeof chainAuditPackPages>): string {
+  if (!chain.complete) return `Pages: INCOMPLETE: ${chain.reason}\n`;
+  const names = chain.order.map((p) => p.name).join(", ");
+  return `Pages: ${chain.order.length} files chain into one complete answer: ${names}\n`;
+}
+
+/** What reproducing a run record's roots needs, collected across every page
+ * given: the subject hash and certificate id of every record the pages carry,
+ * and the record itself. A set of pages that carry different run records is
+ * not one run and is refused. Mirrors runAggregate in cmd/cli/auditpack.go. */
+export interface RunAggregate {
+  record: RunRecord | null;
+  conflict: boolean;
+  records: RunCheckRecord[];
+}
+
+export function aggregateRun(agg: RunAggregate, result: AuditPackResult): void {
+  if (result.run === null) return;
+  if (agg.record === null) agg.record = result.run;
+  else if (agg.record.runId !== result.run.runId) agg.conflict = true;
+  for (let i = 0; i < result.runRecordIds.length; i++) {
+    agg.records.push({ certificateId: result.runRecordIds[i]!, subjectHash: result.runSubjects[i]! });
+  }
+}
+
+/** The run block that follows the pages, laid out as docs/cli.md pins it. ok
+ * is false when the run's roots could not be reproduced from a complete chain,
+ * or the pages disagree about which run they are. A shortfall against the
+ * declared list and a close after the deadline are reported, not refused:
+ * they are findings about the cycle, which is the auditor's question, not
+ * about the evidence. Mirrors formatRunCheck in cmd/cli/auditpack.go. */
+export async function formatRunCheck(
+  agg: RunAggregate, complete: boolean,
+): Promise<{ output: string; ok: boolean }> {
+  if (agg.conflict) return { output: "Run: INVALID: the pages carry records of different runs\n", ok: false };
+  const r = agg.record!;
+  const L: string[] = [];
+  L.push(`Run ${r.runId}: ${r.runKind}`);
+  L.push(`  Opened: ${r.openedAt}`);
+  const late = r.closedAt > r.notAfter ? " (AFTER the declared deadline)" : "";
+  L.push(`  Closed: ${r.closedAt}, deadline ${r.notAfter}${late}`);
+  L.push(
+    `  Declared list: ${r.listCount} entries, sha256:${bytesToHex(r.listDigest)} ` +
+      "(the customer's assertion; the enclave never sees the list)",
+  );
+  L.push(`  Issued under the run: ${r.recordsCount} records over ${r.subjectsCount} distinct subjects`);
+  if (!complete) {
+    L.push("  Roots: NOT CHECKED (the pages do not chain into the whole run; every page is needed to reproduce the roots)");
+    return { output: L.join("\n") + "\n", ok: false };
+  }
+  const check = await checkRunAgainstRecords(nodeCrypto, r, agg.records);
+  const ok = check.recordsMatch && check.subjectsMatch;
+  L.push(
+    ok
+      ? `  Roots: REPRODUCED from the ${agg.records.length} records in these pages`
+      : `  Roots: MISMATCH: the ${agg.records.length} records in these pages do not reproduce the record's roots`,
+  );
+  if (check.listShortfall > 0) {
+    L.push(`  Shortfall: ${check.listShortfall} listed subjects have no record in this run`);
+  } else if (check.listShortfall < 0) {
+    L.push(`  Shortfall: none; ${-check.listShortfall} more subjects than the list declared`);
+  } else {
+    L.push("  Shortfall: none; every listed subject has a record");
+  }
+  return { output: L.join("\n") + "\n", ok };
+}
+
+/** `--pack`: each file verified on its own, then the set checked to chain.
+ * Exit 0 only when every page VERIFIED and the chain is complete — a single
+ * page whose footer names a next cursor is not the whole answer. An UNREADABLE
+ * page ends the run at 2, as an unreadable --cert does: no record was checked,
+ * and a page with no header has nothing to chain by. Mirrors runPackCheck in
+ * cmd/cli/auditpack.go. */
+async function mainPack(args: ReturnType<typeof parseArgs>): Promise<void> {
+  let keys: Map<string, PublicKeyInfo> | null = null;
+  if (args.keysPath) keys = (await loadKeys(args.keysPath)).keys;
+
+  // Step 8 per record, with the same absence of credentials as a single
+  // record. A statement that could not be had leaves that record at
+  // VALID_REVOCATION_UNKNOWN, as offline; the reader is told on stderr.
+  const status = args.online
+    ? async (certId: string): Promise<StatusStatement | null> => {
+        try {
+          return await fetchStatusStatement(args.apiUrl, certId);
+        } catch (e) {
+          process.stderr.write(
+            `warning: signed status statement unavailable for ${certId}: ${e instanceof Error ? e.message : String(e)}\n`,
+          );
+          return null;
+        }
+      }
+    : undefined;
+
+  const now = new Date();
+  const pages: AuditPackPage[] = [];
+  const run: RunAggregate = { record: null, conflict: false, records: [] };
+  let refused = false;
+  for (const path of args.packPaths) {
+    const result = await verifyAuditPack(nodeCrypto, await readFile(path), keys, now, { status });
+    process.stdout.write(formatAuditPackOutput(path, result, { keysFile: args.keysPath, online: args.online }));
+    if (result.verdict === "UNREADABLE" || result.header === null) process.exit(2);
+    if (result.verdict !== "VERIFIED") refused = true;
+    pages.push({
+      name: basename(path),
+      cursor: result.header.cursor,
+      nextCursor: result.footer?.nextCursor ?? null,
+    });
+    aggregateRun(run, result);
+  }
+  const chain = chainAuditPackPages(pages);
+  if (args.packPaths.length > 1) process.stdout.write(formatAuditPackChain(chain));
+  if (run.record !== null) {
+    const { output, ok } = await formatRunCheck(run, chain.complete);
+    process.stdout.write(output);
+    if (!ok) refused = true;
+  }
+  process.exit(refused || !chain.complete ? 1 : 0);
+}
+
 /** 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 {
@@ -582,6 +860,7 @@ export function unwrapCertificate(parsed: Cert): Cert {
 
 async function main(): Promise<void> {
   const args = parseArgs(process.argv);
+  if (args.packPaths.length > 0) return mainPack(args);
   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.