burnledger 0.9.1 → 0.10.0

package/src/run-record.ts

@@ -0,0 +1,371 @@
+/** The run record (docs/run-record.md, ADR-031 option C).
+ *
+ * A port of core/run_record.go, verdict for verdict. A run is one bulk
+ * deletion cycle; the run record is the enclave's signed word on it — what the
+ * customer declared the input list to be, what the enclave actually issued
+ * under the run, and when it opened and closed. Held beside every record of
+ * the run (an audit pack filtered by run_id, every page of it), it lets a
+ * reader establish that the records are exactly what was issued, how many
+ * listed subjects have no record, and whether the run closed in time.
+ *
+ * What it does not establish is that the list was the regulator's list: the
+ * enclave never sees the list, and list_digest and list_count are the
+ * customer's assertion, signed and dated here rather than implicit.
+ */
+
+import type { CryptoOps } from "./crypto.js";
+import { VerificationError } from "./errors.js";
+import {
+  buildLogLeafPayload,
+  bytesToHex,
+  canonicalJson,
+  decodeFixed,
+  evaluateKey,
+  formatTimestamp,
+  formatUuid,
+  hashLeaf,
+  keyIsUsable,
+  merkleRoot,
+  parseUuid,
+  signatureCoversRunId,
+  transparencyVerdictName,
+  verifyTransparencyHead,
+  verifyTransparencyInclusion,
+  type PublicKeyInfo,
+} from "./verify.js";
+
+/** The domain-separation tag of a run record. */
+export const PAYLOAD_TYPE_RUN_RECORD = "burnledger.run_record.v1";
+
+/** What a run was: a regulator's bulk cycle or a customer's own sweep. Carried
+ * signed, so an auditor reads what the customer claimed the run to be rather
+ * than inferring it from a date. */
+export type RunKind = "drop_cycle" | "bulk_erasure";
+
+const RUN_KINDS: ReadonlySet<string> = new Set<RunKind>(["drop_cycle", "bulk_erasure"]);
+
+export const NIL_UUID = "00000000-0000-0000-0000-000000000000";
+
+/** Mirrors core.RunRecord, as GET /v1/runs/{id} serves it under `record` and
+ * an audit pack carries it in its header. UUIDs are canonical lowercase,
+ * timestamps whole-second UTC, exactly as the payload signs them. */
+export interface RunRecord {
+  runId: string;
+  runKind: string;
+  /** Signed, so a run record cannot be presented as another team's. */
+  teamId: string;
+  /** The customer's assertion about the input list: SHA-256 over its canonical
+   * form (one normalized identifier per line, sorted, LF-terminated), and how
+   * many entries it had. 32 bytes. */
+  listDigest: Uint8Array;
+  listCount: number;
+  /** Merkle root and count over the DISTINCT subject hashes the enclave issued
+   * records for under this run, leaves sorted. Computed by the enclave, never
+   * asserted. 32 bytes. */
+  subjectsRoot: Uint8Array;
+  subjectsCount: number;
+  /** Merkle root and count over the certificate ids issued under this run,
+   * leaves sorted. A run with no records has zero roots and zero counts. */
+  recordsRoot: Uint8Array;
+  recordsCount: number;
+  /** The systems every record in the run covered. */
+  systemIds: string[];
+  openedAt: string;
+  closedAt: string;
+  /** The customer-declared deadline, so "on time" is checkable against closedAt. */
+  notAfter: string;
+  issuer: { keyId: string; enclavePcr0: string };
+  /** 64 bytes. */
+  signature: Uint8Array;
+  transparencyStatus: string;
+  /** The record's own inclusion proof once it is in the log, in the shape a
+   * certificate's takes. Outside the signature, as on a certificate. */
+  transparency?: Record<string, unknown>;
+}
+
+/** What a verifier learns about a run record's signature (core.RunRecordResult). */
+export type RunRecordResult =
+  | "VALID"
+  | "MALFORMED_RUN_RECORD"
+  | "UNKNOWN_KEY"
+  | "KEY_UNUSABLE"
+  | "INVALID_RUN_RECORD_SIGNATURE";
+
+/** Mirrors core.RunCheck: what a reader learns by holding a run record beside
+ * the records issued under it. */
+export interface RunCheck {
+  /** The certificate ids reproduce records_root and records_count. */
+  recordsMatch: boolean;
+  /** The subject hashes reproduce subjects_root and subjects_count. */
+  subjectsMatch: boolean;
+  /** listCount minus subjectsCount: how many listed subjects have no record in
+   * the run. Zero is the number an auditor wants. */
+  listShortfall: number;
+  /** closedAt <= notAfter. */
+  closedInTime: boolean;
+  /** Records whose own signed run_id (format 10.0 and later) names a different
+   * run, or no run, while the pack presents them as this run's. A record
+   * without the field (older formats) is neither counted nor refused: it says
+   * nothing about its run, and the roots are what bind it. */
+  mislabelled: number;
+}
+
+/** What checkRunAgainstRecords needs from one record of the run. */
+export interface RunCheckRecord {
+  certificateId: string;
+  /** subject.identifier_hash, 32 bytes. */
+  subjectHash: Uint8Array;
+  /** The record's own signed run_id, when it carries one. */
+  runId?: string;
+  formatVersion?: string;
+}
+
+type Doc = Record<string, unknown>;
+
+function isObject(v: unknown): v is Doc {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/** A UUID field as Go's uuid.UUID unmarshals it: null or absent is the nil
+ * UUID (encoding/json leaves the zero value), a string in any form uuid.Parse
+ * reads is canonical, anything else fails the document. */
+function uuidOrNil(v: unknown, path: string): string {
+  if (v === null || v === undefined) return NIL_UUID;
+  if (typeof v !== "string") throw new VerificationError(`${path} is not a string`);
+  try {
+    return formatUuid(parseUuid(v));
+  } catch (e) {
+    if (e instanceof TypeError) throw new VerificationError(`${path} is not a UUID: ${JSON.stringify(v)}`);
+    throw e;
+  }
+}
+
+/** A fixed byte array as Go's [N]byte unmarshals it: null or absent is all
+ * zero, anything else must be exactly N bytes. */
+function bytesOrZero(v: unknown, path: string, length: number): Uint8Array {
+  if (v === null || v === undefined) return new Uint8Array(length);
+  return decodeFixed(v, path, length);
+}
+
+/** A count as Go's uint64 unmarshals it: null or absent is 0, and a fraction
+ * or a negative fails the document. */
+function countOrZero(v: unknown, path: string): number {
+  if (v === null || v === undefined) return 0;
+  if (typeof v !== "number" || !Number.isSafeInteger(v) || v < 0) {
+    throw new VerificationError(`${path} is not a non-negative integer: ${JSON.stringify(v)}`);
+  }
+  return v;
+}
+
+function stringOrEmpty(v: unknown, path: string): string {
+  if (v === null || v === undefined) return "";
+  if (typeof v !== "string") throw new VerificationError(`${path} is not a string`);
+  return v;
+}
+
+/** Read a run record as served, refusing what Go's ParseRunRecordDocument and
+ * the unmarshal behind it refuse. Throws a VerificationError naming the field. */
+export function parseRunRecordDocument(doc: unknown): RunRecord {
+  if (!isObject(doc)) throw new VerificationError("run record: not a JSON object");
+  const rawIssuer = doc.issuer;
+  if (rawIssuer !== null && rawIssuer !== undefined && !isObject(rawIssuer)) {
+    throw new VerificationError("issuer is not an object");
+  }
+  const issuer: Doc = isObject(rawIssuer) ? rawIssuer : {};
+  const rawSystems = doc.system_ids;
+  let systemIds: string[] = [];
+  if (rawSystems !== null && rawSystems !== undefined) {
+    if (!Array.isArray(rawSystems)) throw new VerificationError("system_ids is not an array");
+    systemIds = rawSystems.map((v, i) => uuidOrNil(v, `system_ids[${i}]`));
+  }
+  const record: RunRecord = {
+    runId: uuidOrNil(doc.run_id, "run_id"),
+    runKind: stringOrEmpty(doc.run_kind, "run_kind"),
+    teamId: uuidOrNil(doc.team_id, "team_id"),
+    listDigest: bytesOrZero(doc.list_digest, "list_digest", 32),
+    listCount: countOrZero(doc.list_count, "list_count"),
+    subjectsRoot: bytesOrZero(doc.subjects_root, "subjects_root", 32),
+    subjectsCount: countOrZero(doc.subjects_count, "subjects_count"),
+    recordsRoot: bytesOrZero(doc.records_root, "records_root", 32),
+    recordsCount: countOrZero(doc.records_count, "records_count"),
+    systemIds,
+    openedAt: formatTimestamp(doc.opened_at, "opened_at"),
+    closedAt: formatTimestamp(doc.closed_at, "closed_at"),
+    notAfter: formatTimestamp(doc.not_after, "not_after"),
+    issuer: {
+      keyId: stringOrEmpty(issuer.key_id, "issuer.key_id"),
+      enclavePcr0: stringOrEmpty(issuer.enclave_pcr0, "issuer.enclave_pcr0"),
+    },
+    signature: bytesOrZero(doc.signature, "signature", 64),
+    transparencyStatus: stringOrEmpty(doc.transparency_status, "transparency_status"),
+  };
+  const transparency = doc.transparency;
+  if (transparency !== null && transparency !== undefined) {
+    if (!isObject(transparency)) throw new VerificationError("transparency is not an object");
+    record.transparency = transparency;
+  }
+  return record;
+}
+
+/** The canonical signing payload. Every signed field is present; the system
+ * ids are sorted so two records over the same set sign the same bytes. Mirrors
+ * core.BuildRunRecordPayload, including its refusal of an unknown run_kind. */
+export function buildRunRecordPayload(r: RunRecord): Uint8Array {
+  if (!RUN_KINDS.has(r.runKind)) {
+    throw new VerificationError(`run record: unknown run_kind ${r.runKind}`);
+  }
+  return canonicalJson({
+    payload_type: PAYLOAD_TYPE_RUN_RECORD,
+    closed_at: formatTimestamp(r.closedAt, "closed_at"),
+    enclave_pcr0: r.issuer.enclavePcr0,
+    key_id: r.issuer.keyId,
+    list_count: r.listCount,
+    list_digest: bytesToHex(r.listDigest),
+    not_after: formatTimestamp(r.notAfter, "not_after"),
+    opened_at: formatTimestamp(r.openedAt, "opened_at"),
+    records_count: r.recordsCount,
+    records_root: bytesToHex(r.recordsRoot),
+    run_id: r.runId,
+    run_kind: r.runKind,
+    subjects_count: r.subjectsCount,
+    subjects_root: bytesToHex(r.subjectsRoot),
+    system_ids: [...r.systemIds].sort(),
+    team_id: r.teamId,
+  });
+}
+
+function epochSeconds(rfc3339: string, field: string): number {
+  return Math.floor(Date.parse(formatTimestamp(rfc3339, field)) / 1000);
+}
+
+/** Checks the record's signature against the reader's keys, in the order every
+ * verifier uses: the shape, the key's authority at the record's own close
+ * instant, then the signature. Mirrors core.VerifyRunRecord. */
+export async function verifyRunRecord(
+  crypto: CryptoOps,
+  r: RunRecord,
+  keys: Map<string, PublicKeyInfo>,
+): Promise<RunRecordResult> {
+  const closedAt = epochSeconds(r.closedAt, "closed_at");
+  if (!RUN_KINDS.has(r.runKind) || r.runId === NIL_UUID || closedAt < epochSeconds(r.openedAt, "opened_at")) {
+    return "MALFORMED_RUN_RECORD";
+  }
+  const key = keys.get(r.issuer.keyId);
+  if (key === undefined) return "UNKNOWN_KEY";
+  if (!keyIsUsable(evaluateKey(key, closedAt))) return "KEY_UNUSABLE";
+  const payload = buildRunRecordPayload(r);
+  if (!(await crypto.ed25519Verify(key.keyBytes, payload, r.signature))) return "INVALID_RUN_RECORD_SIGNATURE";
+  return "VALID";
+}
+
+/** What the run record's log leaf commits to: the SHA-256 of its canonical
+ * payload. A certificate leaf hashes the whole document less its transparency
+ * block; a run record's payload already is the whole signed document. */
+export function runRecordHash(crypto: CryptoOps, r: RunRecord): Promise<Uint8Array> {
+  return crypto.sha256(buildRunRecordPayload(r));
+}
+
+/** Checks the record's own transparency proof the way a certificate's is
+ * checked, under core.TransparencyResult's names: NOT_INCLUDED when it carries
+ * none, INVALID_INCLUSION_PROOF for a leaf that is not a RUN_RECORD leaf,
+ * UNREADABLE_DOCUMENT where the leaf cannot be built. Mirrors
+ * core.VerifyRunRecordInclusion. */
+export async function verifyRunRecordInclusion(
+  crypto: CryptoOps,
+  r: RunRecord,
+  key: PublicKeyInfo,
+): Promise<string> {
+  const transparency = r.transparency;
+  if (transparency === undefined) return "NOT_INCLUDED";
+  if (transparency.entry_type !== "RUN_RECORD") return "INVALID_INCLUSION_PROOF";
+  let leaf: Uint8Array;
+  try {
+    const payload = buildLogLeafPayload("RUN_RECORD", r.runId, await runRecordHash(crypto, r), transparency.appended_at);
+    leaf = await hashLeaf(crypto, payload);
+  } catch (e) {
+    if (e instanceof VerificationError) return "UNREADABLE_DOCUMENT";
+    throw e;
+  }
+  try {
+    await verifyTransparencyHead(crypto, transparency, key, r.issuer.keyId);
+    await verifyTransparencyInclusion(crypto, transparency, leaf);
+  } catch (e) {
+    if (e instanceof VerificationError) return transparencyVerdictName(e);
+    throw e;
+  }
+  return "VALID";
+}
+
+function compareBytes(a: Uint8Array, b: Uint8Array): number {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    if (a[i] !== b[i]) return a[i]! - b[i]!;
+  }
+  return a.length - b.length;
+}
+
+/** The root over a leaf set the way a run record commits to one: leaves
+ * sorted bytewise, and 32 zero bytes for the empty set. */
+async function sortedRoot(crypto: CryptoOps, leaves: Uint8Array[]): Promise<Uint8Array> {
+  if (leaves.length === 0) return new Uint8Array(32);
+  return merkleRoot(crypto, [...leaves].sort(compareBytes));
+}
+
+/** What a run record commits to, from what was issued under it. Subjects are
+ * de-duplicated — a subject certified twice in one run is one subject — and
+ * both leaf sets are sorted, so the roots do not depend on issuance order and a
+ * verifier can reproduce them from a pack in any order. A subject leaf is its
+ * 32-byte hash and a record leaf the certificate id's 16 bytes, both through
+ * the RFC 6962 leaf hash. Mirrors core.RunRoots. */
+export async function runRoots(
+  crypto: CryptoOps,
+  subjects: Uint8Array[],
+  certificateIds: string[],
+): Promise<{ subjectsRoot: Uint8Array; subjectsCount: number; recordsRoot: Uint8Array; recordsCount: number }> {
+  const seen = new Set<string>();
+  const subjectLeaves: Uint8Array[] = [];
+  for (const s of subjects) {
+    const key = bytesToHex(s);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    subjectLeaves.push(await hashLeaf(crypto, s));
+  }
+  const recordLeaves: Uint8Array[] = [];
+  for (const id of certificateIds) recordLeaves.push(await hashLeaf(crypto, parseUuid(id)));
+  return {
+    subjectsRoot: await sortedRoot(crypto, subjectLeaves),
+    subjectsCount: subjectLeaves.length,
+    recordsRoot: await sortedRoot(crypto, recordLeaves),
+    recordsCount: recordLeaves.length,
+  };
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  return compareBytes(a, b) === 0;
+}
+
+/** Reproduces the run record's roots from the records a reader holds and
+ * compares them. The reader must hold every record of the run — a complete
+ * chain of pack pages filtered by the run — or the roots cannot match, which
+ * is the honest answer for a partial set. Mirrors core.CheckRunAgainstRecords. */
+export async function checkRunAgainstRecords(
+  crypto: CryptoOps,
+  r: RunRecord,
+  records: RunCheckRecord[],
+): Promise<RunCheck> {
+  let mislabelled = 0;
+  for (const rec of records) {
+    if (rec.runId !== undefined && rec.runId !== r.runId) mislabelled++;
+    if (rec.runId === undefined && rec.formatVersion !== undefined && signatureCoversRunId(rec.formatVersion)) {
+      mislabelled++;
+    }
+  }
+  const roots = await runRoots(crypto, records.map((rec) => rec.subjectHash), records.map((rec) => rec.certificateId));
+  return {
+    recordsMatch: bytesEqual(roots.recordsRoot, r.recordsRoot) && roots.recordsCount === r.recordsCount,
+    subjectsMatch: bytesEqual(roots.subjectsRoot, r.subjectsRoot) && roots.subjectsCount === r.subjectsCount,
+    listShortfall: r.listCount - r.subjectsCount,
+    closedInTime: epochSeconds(r.closedAt, "closed_at") <= epochSeconds(r.notAfter, "not_after"),
+    mislabelled,
+  };
+}