burnledger 0.9.1 → 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
@@ -321,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);
@@ -616,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 {
@@ -632,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.

package/src/client.ts

@@ -19,6 +19,8 @@ import type {
   LogEntry,
   Profile,
   RevocationStatus,
+  Run,
+  RunKind,
   SignedTreeHead,
   System,
   SystemHealth,
@@ -40,6 +42,7 @@ import {
   parseLogEntry,
   parseProfile,
   parseRevocationStatus,
+  parseRun,
   parseSignedTreeHead,
   parseSystem,
   parseSystemHealth,
@@ -191,6 +194,9 @@ export class BurnLedger {
       proofMode?: string;
       expiresIn?: string;
       webhookUrl?: string;
+      /** Issue the record under this OPEN run (ADR-031). The run must be this
+       * team's and its declared systems must be exactly systemIds. */
+      runId?: string;
     },
   ): Promise<Attestation> {
     const body: Record<string, unknown> = {
@@ -200,6 +206,7 @@ export class BurnLedger {
     };
     if (opts?.systemIds !== undefined) body.system_ids = opts.systemIds;
     if (opts?.webhookUrl !== undefined) body.webhook_url = opts.webhookUrl;
+    if (opts?.runId !== undefined) body.run_id = opts.runId;
 
     const data = await this.transport.request("POST", "/v1/attestations", {
       json: body,
@@ -267,13 +274,16 @@ export class BurnLedger {
     systemIds: string[];
     proofMode?: string;
     expiresIn?: string;
+    /** Issue every record under this OPEN run (ADR-031). */
+    runId?: string;
   }): Promise<BatchAttestationResponse> {
-    const body = {
+    const body: Record<string, unknown> = {
       subject_identifiers: opts.subjectIdentifiers,
       system_ids: opts.systemIds,
       proof_mode: opts.proofMode ?? "count",
       expires_in: opts.expiresIn ?? "72h",
     };
+    if (opts.runId !== undefined) body.run_id = opts.runId;
     const data = await this.transport.request("POST", "/v1/attestations/batch", {
       json: body,
     });
@@ -377,6 +387,77 @@ export class BurnLedger {
     return this.transport.requestBytes("GET", path);
   }
 
+  /** One page of an audit pack (docs/audit-pack.md): the export's records as
+   * signed documents, with the issuer's keys and log head, framed by a header
+   * and a footer. The footer's next_cursor names the next page; pass it back
+   * as `cursor` and keep each page as its own file — pages chain by their
+   * cursors, not by their bytes. */
+  async exportAuditPack(opts?: {
+    status?: "ACTIVE" | "REVOKED";
+    issuedAfter?: string;
+    issuedBefore?: string;
+    /** Only the records issued under this run (ADR-031); a closed run's pack
+     * carries the signed run record in its header. */
+    runId?: string;
+    cursor?: string;
+  }): Promise<Uint8Array> {
+    const params: Record<string, string> = {};
+    if (opts?.status !== undefined) params.status = opts.status;
+    if (opts?.issuedAfter !== undefined) params.issued_after = opts.issuedAfter;
+    if (opts?.issuedBefore !== undefined) params.issued_before = opts.issuedBefore;
+    if (opts?.runId !== undefined) params.run_id = opts.runId;
+    if (opts?.cursor !== undefined) params.cursor = opts.cursor;
+
+    const qs = new URLSearchParams(params).toString();
+    const path = qs ? `/v1/certificates/audit-pack?${qs}` : "/v1/certificates/audit-pack";
+    return this.transport.requestBytes("GET", path);
+  }
+
+  // --- Runs (ADR-031) ---
+
+  /** Open a bulk run with the customer's declaration: what the input list was
+   * (its SHA-256 over the canonical form and entry count), the deadline, and
+   * the systems every record in the run will cover. The enclave never sees the
+   * list; the digest and count are signed into the run record as declared. */
+  async openRun(opts: {
+    runKind: RunKind;
+    /** 64 hex characters. */
+    listDigest: string;
+    listCount: number;
+    notAfter: Date | string;
+    systemIds: string[];
+  }): Promise<Run> {
+    const body = {
+      run_kind: opts.runKind,
+      list_digest: opts.listDigest,
+      list_count: opts.listCount,
+      not_after: opts.notAfter instanceof Date ? opts.notAfter.toISOString() : opts.notAfter,
+      system_ids: opts.systemIds,
+    };
+    const data = await this.transport.request("POST", "/v1/runs", { json: body });
+    return parseRun(data as Raw);
+  }
+
+  /** Close a run: the enclave signs the run record over what it issued under
+   * it and the record is appended to the transparency log. 409 (ConflictError)
+   * when the run is not OPEN — including a run an enclave restart forgot,
+   * which is marked LOST and can never be closed. */
+  async closeRun(runId: string): Promise<Run> {
+    const data = await this.transport.request("POST", `/v1/runs/${runId}/close`);
+    return parseRun(data as Raw);
+  }
+
+  async getRun(runId: string): Promise<Run> {
+    const data = await this.transport.request("GET", `/v1/runs/${runId}`);
+    return parseRun(data as Raw);
+  }
+
+  listRuns(opts?: { limit?: number }): Paginator<Run> {
+    return new Paginator(this.transport, "/v1/runs", parseRun, {
+      params: { limit: opts?.limit ?? 25 },
+    });
+  }
+
   // --- Webhooks ---
 
   async registerWebhook(opts: { url: string }): Promise<Webhook> {

package/src/index.ts

@@ -48,6 +48,9 @@ export type {
   ConnectorType,
   HashScope,
   LogEntryType,
+  Run,
+  RunKind,
+  RunStatus,
   VerificationResult,
   TransparencyResult,
   ApiKeyRole,
@@ -84,7 +87,7 @@ export type {
 
 // Raw-JSON → model parsers, for consumers that fetch API responses outside
 // the client (the dashboard's paginated list hooks) but render SDK types.
-export { parseSystem, parseCertificateResponse, parseWebhook } from "./models.js";
+export { parseSystem, parseCertificateResponse, parseRun, parseWebhook } from "./models.js";
 
 export { Paginator } from "./pagination.js";
 
@@ -170,6 +173,119 @@ export function verifyConsistency(
 
 export { verifyWebhookSignature, isTimestampFresh } from "./webhooks.js";
 
+/**
+ * Audit pack verification (docs/audit-pack.md). Node only: a pack is a file an
+ * auditor holds, and the browser verifier reads one record at a time.
+ */
+export {
+  AUDIT_PACK_FORMAT,
+  PAYLOAD_TYPE_AUDIT_PACK_FOOTER,
+  auditPackFooterStatement,
+  buildAuditPackFooterPayload,
+  chainAuditPackPages,
+} from "./audit-pack.js";
+export type {
+  AuditPackFilters,
+  AuditPackFooter,
+  AuditPackFooterResult,
+  AuditPackFooterSigned,
+  AuditPackFooterStatement,
+  AuditPackHeader,
+  AuditPackLogHead,
+  AuditPackOptions,
+  AuditPackPage,
+  AuditPackRecordFailure,
+  AuditPackResult,
+  AuditPackVerdict,
+  SignedTreeHeadDocument,
+} from "./audit-pack.js";
+import {
+  verifyAuditPack as _verifyAuditPack,
+  verifyAuditPackFooter as _verifyAuditPackFooter,
+} from "./audit-pack.js";
+import type {
+  AuditPackFooterResult,
+  AuditPackFooterStatement,
+  AuditPackOptions,
+  AuditPackResult,
+} from "./audit-pack.js";
+
+/** Verify one audit pack page offline, as `burnledger check --pack` does.
+ * `keys` null uses the pack's own issuer_keys (trust on first use, and the
+ * result's keysFromPack says so); a supplied key set outranks them. */
+export function verifyAuditPack(
+  source: string | Uint8Array,
+  keys: Map<string, PublicKeyInfo> | null,
+  now?: Date,
+  options?: AuditPackOptions,
+): Promise<AuditPackResult> {
+  return _verifyAuditPack(nodeCrypto, source, keys, now ?? new Date(), options);
+}
+
+/** Verify a footer statement — rebuilt from a page's header and footer by
+ * auditPackFooterStatement — under a key set. verifyAuditPack already does
+ * this for every signed footer it reads; this is for a reader holding the
+ * statement on its own. */
+export function verifyAuditPackFooter(
+  statement: AuditPackFooterStatement,
+  keys: Map<string, PublicKeyInfo>,
+): Promise<AuditPackFooterResult> {
+  return _verifyAuditPackFooter(nodeCrypto, statement, keys);
+}
+
+/**
+ * The run record (docs/run-record.md, ADR-031): the enclave's signed word on
+ * one bulk run, checked beside the run's records. Node only, as the audit pack
+ * verifier that carries it is.
+ */
+export {
+  PAYLOAD_TYPE_RUN_RECORD,
+  buildRunRecordPayload,
+  parseRunRecordDocument,
+} from "./run-record.js";
+export type { RunCheck, RunCheckRecord, RunRecord, RunRecordResult } from "./run-record.js";
+import {
+  checkRunAgainstRecords as _checkRunAgainstRecords,
+  runRecordHash as _runRecordHash,
+  runRoots as _runRoots,
+  verifyRunRecord as _verifyRunRecord,
+  verifyRunRecordInclusion as _verifyRunRecordInclusion,
+} from "./run-record.js";
+import type { RunCheck, RunCheckRecord, RunRecord, RunRecordResult } from "./run-record.js";
+
+/** Verify a run record's signature under a key set: the shape, the key's
+ * authority at the record's close instant, then the signature. */
+export function verifyRunRecord(record: RunRecord, keys: Map<string, PublicKeyInfo>): Promise<RunRecordResult> {
+  return _verifyRunRecord(nodeCrypto, record, keys);
+}
+
+/** What the run record's transparency leaf commits to: SHA-256 of its payload. */
+export function runRecordHash(record: RunRecord): Promise<Uint8Array> {
+  return _runRecordHash(nodeCrypto, record);
+}
+
+/** Verify the run record's own inclusion proof under the key that signed it,
+ * as core.TransparencyResult names the outcome; NOT_INCLUDED without one. */
+export function verifyRunRecordInclusion(record: RunRecord, key: PublicKeyInfo): Promise<string> {
+  return _verifyRunRecordInclusion(nodeCrypto, record, key);
+}
+
+/** The roots a run record commits to, reproduced from subject hashes and
+ * certificate ids in any order: subjects de-duplicated, both leaf sets sorted. */
+export function runRoots(
+  subjects: Uint8Array[],
+  certificateIds: string[],
+): Promise<{ subjectsRoot: Uint8Array; subjectsCount: number; recordsRoot: Uint8Array; recordsCount: number }> {
+  return _runRoots(nodeCrypto, subjects, certificateIds);
+}
+
+/** Hold a run record beside every record of the run: whether the roots
+ * reproduce, the shortfall against the declared list, whether it closed in
+ * time, and how many records are labelled with another run. */
+export function checkRunAgainstRecords(record: RunRecord, records: RunCheckRecord[]): Promise<RunCheck> {
+  return _checkRunAgainstRecords(nodeCrypto, record, records);
+}
+
 /**
  * Client-side connection-config sealing.
  *

package/src/models.ts

@@ -73,7 +73,9 @@ export type ConnectorType =
   | "bigquery"
   | "azure_blob";
 export type HashScope = "full" | "existence";
-export type LogEntryType = "CERTIFICATE" | "REVOCATION";
+export type LogEntryType = "CERTIFICATE" | "REVOCATION" | "RUN_RECORD";
+export type RunKind = "drop_cycle" | "bulk_erasure";
+export type RunStatus = "OPEN" | "CLOSED" | "LOST";
 
 /** Result of offline certificate signature verification. */
 export type VerificationResult = "VALID" | "INVALID";
@@ -190,11 +192,35 @@ export interface SignedTreeHead {
 export interface LogEntry {
   readonly index: number;
   readonly entryType: LogEntryType;
-  readonly certificateId: string;
+  /** Present on CERTIFICATE and REVOCATION leaves. */
+  readonly certificateId: string | undefined;
+  /** Present on RUN_RECORD leaves (ADR-031). */
+  readonly runId: string | undefined;
   readonly hash: string;
   readonly appendedAt: Date;
 }
 
+/** One bulk run (ADR-031, docs/run-record.md): the customer's declaration as
+ * opened, and once CLOSED the enclave-signed run record under `record`, with
+ * its transparency proof merged in when a signed tree head covers its leaf.
+ * The record is kept raw so it can be handed straight to verifyRunRecord. */
+export interface Run {
+  readonly id: string;
+  readonly teamId: string;
+  readonly runKind: RunKind;
+  /** SHA-256 of the input list's canonical form, 64 hex characters. */
+  readonly listDigest: string;
+  readonly listCount: number;
+  readonly notAfter: Date;
+  readonly systemIds: readonly string[];
+  readonly status: RunStatus;
+  readonly openedAt: Date;
+  readonly closedAt: Date | undefined;
+  /** The run record's leaf in the transparency log, once appended. */
+  readonly logIndex: number | undefined;
+  readonly record: Record<string, unknown> | undefined;
+}
+
 export interface InclusionProof {
   readonly index: number;
   readonly treeSize: number;
@@ -486,12 +512,30 @@ export function parseLogEntry(d: Raw): LogEntry {
   return {
     index: d.index,
     entryType: d.entry_type as LogEntryType,
-    certificateId: d.certificate_id,
+    certificateId: d.certificate_id ?? undefined,
+    runId: d.run_id ?? undefined,
     hash: d.hash,
     appendedAt: parseDt(d.appended_at),
   };
 }
 
+export function parseRun(d: Raw): Run {
+  return {
+    id: d.id,
+    teamId: d.team_id,
+    runKind: d.run_kind as RunKind,
+    listDigest: d.list_digest,
+    listCount: d.list_count,
+    notAfter: parseDt(d.not_after),
+    systemIds: d.system_ids ?? [],
+    status: d.status as RunStatus,
+    openedAt: parseDt(d.opened_at),
+    closedAt: parseDtOpt(d.closed_at),
+    logIndex: d.log_index ?? undefined,
+    record: d.record ?? undefined,
+  };
+}
+
 export function parseInclusionProof(d: Raw): InclusionProof {
   return {
     index: d.index,