burnledger 0.9.0 → 0.10.0

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,
@@ -50,6 +53,10 @@ import {
 } from "./models.js";
 import type { KeyEnrollmentResult, SystemRegistrationCertificate } from "./models.js";
 import { Paginator } from "./pagination.js";
+// Node-only work (enrolment, registration, savePdf) is reached through here, not
+// by naming the Node modules — so the browser entry that shares this class never
+// pulls node:crypto or node:fs into a bundle. See node-runtime.ts.
+import { loadNodeRuntime } from "./node-runtime.js";
 // Types only: erased at build, so the browser entry that shares this module
 // never loads node:crypto. The code behind them is imported lazily, on use.
 import type { CustomerKeyGroup } from "./customer-keys.js";
@@ -155,7 +162,7 @@ export class BurnLedger {
   async getSystem(systemId: string): Promise<System> {
     const data = await this.transport.request(
       "GET",
-      `/v1/systems/${systemId}`,
+      `/v1/systems/${encodeId(systemId)}`,
     );
     return parseSystem(data as Raw);
   }
@@ -167,13 +174,13 @@ export class BurnLedger {
   }
 
   async deregisterSystem(systemId: string): Promise<void> {
-    await this.transport.request("DELETE", `/v1/systems/${systemId}`);
+    await this.transport.request("DELETE", `/v1/systems/${encodeId(systemId)}`);
   }
 
   async healthCheck(systemId: string): Promise<System> {
     const data = await this.transport.request(
       "POST",
-      `/v1/systems/${systemId}/health-check`,
+      `/v1/systems/${encodeId(systemId)}/health-check`,
     );
     return parseSystem(data as Raw);
   }
@@ -187,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> = {
@@ -196,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,
@@ -206,7 +217,7 @@ export class BurnLedger {
   async getAttestation(attestationId: string): Promise<Attestation> {
     const data = await this.transport.request(
       "GET",
-      `/v1/attestations/${attestationId}`,
+      `/v1/attestations/${encodeId(attestationId)}`,
     );
     return parseAttestation(data as Raw);
   }
@@ -232,7 +243,7 @@ export class BurnLedger {
     const body = { subject_identifier: subjectIdentifier };
     const data = await this.transport.request(
       "POST",
-      `/v1/attestations/${attestationId}/verify`,
+      `/v1/attestations/${encodeId(attestationId)}/verify`,
       { json: body },
     );
     const result = parseVerifyResult(data as Raw);
@@ -246,7 +257,7 @@ export class BurnLedger {
       fetch: async () => {
         const d = await this.transport.request(
           "POST",
-          `/v1/attestations/${attestationId}/verify`,
+          `/v1/attestations/${encodeId(attestationId)}/verify`,
           { json: body },
         );
         return parseVerifyResult(d as Raw);
@@ -263,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,
     });
@@ -281,7 +295,7 @@ export class BurnLedger {
   async getCertificate(certificateId: string): Promise<CertificateResponse> {
     const data = await this.transport.request(
       "GET",
-      `/v1/certificates/${certificateId}`,
+      `/v1/certificates/${encodeId(certificateId)}`,
     );
     return parseCertificateResponse(data as Raw);
   }
@@ -300,20 +314,20 @@ export class BurnLedger {
   async downloadPdf(certificateId: string): Promise<Uint8Array> {
     return this.transport.requestBytes(
       "GET",
-      `/v1/certificates/${certificateId}/pdf`,
+      `/v1/certificates/${encodeId(certificateId)}/pdf`,
     );
   }
 
   async savePdf(certificateId: string, path: string): Promise<void> {
     const pdf = await this.downloadPdf(certificateId);
-    const { writeFile } = await import("node:fs/promises");
+    const { writeFile } = await loadNodeRuntime();
     await writeFile(path, pdf);
   }
 
   async getRevocationStatus(certificateId: string): Promise<RevocationStatus> {
     const data = await this.transport.request(
       "GET",
-      `/v1/certificates/${certificateId}/revocation-status`,
+      `/v1/certificates/${encodeId(certificateId)}/revocation-status`,
     );
     return parseRevocationStatus(data as Raw);
   }
@@ -324,7 +338,7 @@ export class BurnLedger {
   ): Promise<CertificateResponse> {
     const data = await this.transport.request(
       "POST",
-      `/v1/certificates/${certificateId}/revoke`,
+      `/v1/certificates/${encodeId(certificateId)}/revoke`,
       { json: { reason: opts.reason } },
     );
     return parseCertificateResponse(data as Raw);
@@ -373,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> {
@@ -389,13 +474,13 @@ export class BurnLedger {
   }
 
   async deleteWebhook(webhookId: string): Promise<void> {
-    await this.transport.request("DELETE", `/v1/webhooks/${webhookId}`);
+    await this.transport.request("DELETE", `/v1/webhooks/${encodeId(webhookId)}`);
   }
 
   async rotateWebhookSecret(webhookId: string): Promise<WebhookRotateResponse> {
     const data = await this.transport.request(
       "POST",
-      `/v1/webhooks/${webhookId}/rotate-secret`,
+      `/v1/webhooks/${encodeId(webhookId)}/rotate-secret`,
     );
     return parseWebhookRotateResponse(data as Raw);
   }
@@ -403,7 +488,7 @@ export class BurnLedger {
   async commitWebhookRotation(webhookId: string): Promise<void> {
     await this.transport.request(
       "POST",
-      `/v1/webhooks/${webhookId}/commit-rotation`,
+      `/v1/webhooks/${encodeId(webhookId)}/commit-rotation`,
     );
   }
 
@@ -419,14 +504,14 @@ export class BurnLedger {
   async retryDelivery(deliveryId: string): Promise<void> {
     await this.transport.request(
       "POST",
-      `/v1/webhooks/deliveries/${deliveryId}/retry`,
+      `/v1/webhooks/deliveries/${encodeId(deliveryId)}/retry`,
     );
   }
 
   async resolveDelivery(deliveryId: string): Promise<void> {
     await this.transport.request(
       "DELETE",
-      `/v1/webhooks/deliveries/${deliveryId}`,
+      `/v1/webhooks/deliveries/${encodeId(deliveryId)}`,
     );
   }
 
@@ -453,7 +538,7 @@ export class BurnLedger {
   }
 
   async revokeApiKey(keyId: string): Promise<void> {
-    await this.transport.request("DELETE", `/v1/api-keys/${keyId}`);
+    await this.transport.request("DELETE", `/v1/api-keys/${encodeId(keyId)}`);
   }
 
   // --- Profile ---
@@ -494,7 +579,7 @@ export class BurnLedger {
    * and every document they return must verify under its signing key.
    */
   async attestEnclaveIdentity(pin: EnclavePinOptions): Promise<EnclaveIdentity> {
-    const flow = await import("./enclave-registration.js");
+    const { registration: flow } = await loadNodeRuntime();
     const { nonce, params } = flow.attestationParams(pin.nonce);
     const data = await this.transport.request("GET", "/v1/enclave/attestation", {
       params,
@@ -521,7 +606,7 @@ export class BurnLedger {
     /** The time to judge the answer's not_before against. Defaults to now. */
     now?: Date;
   }): Promise<KeyEnrollmentResult> {
-    const flow = await import("./enclave-registration.js");
+    const { registration: flow } = await loadNodeRuntime();
     const { body, keyId, notAfter } = await flow.enrollBody(opts);
     const data = await this.transport.request("POST", "/v1/enclave/keys", { json: body });
     return flow.checkEnrollment(data, {
@@ -552,7 +637,7 @@ export class BurnLedger {
     /** The time to judge the answer's not_before against. Defaults to now. */
     now?: Date;
   }): Promise<KeyEnrollmentResult> {
-    const flow = await import("./enclave-registration.js");
+    const { registration: flow } = await loadNodeRuntime();
     const { body, prevKeyId, nextKeyId, notAfter } = await flow.rotateBody(opts);
     const data = await this.transport.request("POST", "/v1/enclave/keys/rotate", { json: body });
     return flow.checkEnrollment(data, {
@@ -581,7 +666,7 @@ export class BurnLedger {
     queryTemplate: string;
     connectorType: string;
   }): Promise<SystemRegistrationCertificate> {
-    const flow = await import("./enclave-registration.js");
+    const { registration: flow } = await loadNodeRuntime();
     const { body, keyId, configDigest } = await flow.registrationBody(opts);
     const data = await this.transport.request("POST", "/v1/enclave/registrations", { json: body });
     return flow.checkRegistration(data, {
@@ -615,8 +700,7 @@ export class BurnLedger {
     maxBytes?: number;
     queryTimeout?: string;
   }): Promise<RegisteredSystem> {
-    const flow = await import("./enclave-registration.js");
-    const { sealToKey } = await import("./enclave-seal.js");
+    const { registration: flow, seal } = await loadNodeRuntime();
     const config = flow.configBytes(resolveConnectionConfig(opts.connectionConfig, opts.dsn, opts.uri));
     const system = await this.registerSystem({
       name: opts.name,
@@ -627,7 +711,7 @@ export class BurnLedger {
       maxRecords: opts.maxRecords,
       maxBytes: opts.maxBytes,
       queryTimeout: opts.queryTimeout,
-      sealedConnectionConfig: await sealToKey(opts.enclave.configSealKey, config),
+      sealedConnectionConfig: await seal.sealToKey(opts.enclave.configSealKey, config),
     });
     const registration = await this.registerSystemWithKey({
       teamId: opts.teamId,
@@ -647,7 +731,7 @@ export class BurnLedger {
   async getSystemHealth(systemId: string): Promise<SystemHealth> {
     const data = await this.transport.request(
       "GET",
-      `/v1/systems/${systemId}/health`,
+      `/v1/systems/${encodeId(systemId)}/health`,
     );
     return parseSystemHealth(data as Raw);
   }
@@ -716,6 +800,20 @@ export class BurnLedger {
 // Connection config resolution
 // ---------------------------------------------------------------------------
 
+/** Percent-encode an id before it goes into a URL path, and refuse `.`/`..`.
+ *
+ * A raw id lets untrusted input escape its segment: `deregisterSystem("x/../../
+ * api-keys/k1")` would otherwise resolve to `DELETE /v1/api-keys/k1`.
+ * encodeURIComponent escapes the `/`, but it leaves `.` and `..` untouched, and
+ * a segment that IS `.` or `..` is still traversal — so those are rejected
+ * outright. An empty id is rejected too: it collapses two path segments into one. */
+function encodeId(id: string): string {
+  if (id === "" || id === "." || id === "..") {
+    throw new Error(`invalid id path segment: ${JSON.stringify(id)}`);
+  }
+  return encodeURIComponent(id);
+}
+
 /** Standard base64, as Go decodes a []byte field. No Buffer: this module is
  * also the browser entry's. */
 function bytesToBase64(bytes: Uint8Array): string {
@@ -769,7 +867,14 @@ async function poll<T>(opts: {
       result = await opts.fetch();
     } catch (err) {
       if (err instanceof RateLimitError && err.retryAfter !== undefined) {
-        await sleep(err.retryAfter * 1000);
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+          throw new TimeoutError(opts.operation, elapsed);
+        }
+        // Bound the wait to the caller's remaining budget: a server asking for a
+        // day, or an Infinity Retry-After, must not block past the timeout the
+        // caller set (Math.min(Infinity, remaining) === remaining).
+        await sleep(Math.min(err.retryAfter * 1000, remaining));
         continue;
       }
       throw err;

package/src/enclave-registration.ts

@@ -353,8 +353,20 @@ export async function registrationBody(opts: {
   };
 }
 
-/** Verify the registration under the attested enclave's signing key, then
- * refuse it unless it binds what this caller signed. */
+/** Verify the registration under the attested enclave's signing key, then refuse
+ * it unless it binds the key id, system id, config digest and connector this
+ * caller signed.
+ *
+ * Two signed fields are deliberately NOT compared here, so the binding is
+ * narrower than "everything you signed". `query_template_hash` in the answer is
+ * HashQuery over the NORMALIZED subject query, while the request signs sha256 of
+ * the RAW template; the two are not byte-equal even for an honest registration,
+ * so comparing them would reject legitimate answers (see the README's
+ * "query-template normalization" note). `registered_at` is not checked for
+ * freshness either: there is no signed bound to hold it to. A relay could
+ * therefore substitute an older genuine registration for the same system, config,
+ * connector and key but a different query template — the customer path calls this
+ * immediately after its own POST, which narrows that window but does not close it. */
 export async function checkRegistration(
   data: unknown,
   opts: {

package/src/index.ts

@@ -1,5 +1,18 @@
 /** BurnLedger TypeScript SDK — public API (Node.js entry point). */
 
+// Wire the Node-only client capabilities (enrolment, registration, savePdf). The
+// browser entry never does this, so those modules — and node:crypto/node:fs with
+// them — stay out of any browser bundle. See node-runtime.ts.
+import { setNodeRuntimeLoader } from "./node-runtime.js";
+setNodeRuntimeLoader(async () => {
+  const [registration, seal, fs] = await Promise.all([
+    import("./enclave-registration.js"),
+    import("./enclave-seal.js"),
+    import("node:fs/promises"),
+  ]);
+  return { registration, seal, writeFile: (path, data) => fs.writeFile(path, data) };
+});
+
 export { BurnLedger, MAX_BATCH_REVOKE } from "./client.js";
 export type { BurnLedgerOptions } from "./client.js";
 
@@ -35,6 +48,9 @@ export type {
   ConnectorType,
   HashScope,
   LogEntryType,
+  Run,
+  RunKind,
+  RunStatus,
   VerificationResult,
   TransparencyResult,
   ApiKeyRole,
@@ -71,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";
 
@@ -157,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,