@mikeargento/bitgraph-player 0.5.1 → 0.6.0

package/src/cli.ts

@@ -4,7 +4,8 @@
 /**
  * bitgraph-play <rule.json> <bundle> [--out <file>] [--summary]
  * bitgraph-play init <file>... [--out <rule.json>]
- * bitgraph-play check <bundle-or-file>... [--json] [--out <file>]
+ * bitgraph-play check <bundle-or-file>... [--json] [--out <file>] [--from <domain> [--pins <dir>]]
+ * bitgraph-play pin [<domain>] [--forget <domain>] [--pins <dir>] [--yes]
  *
  * Evaluate: runs a bitgraph-player/1 rule against a proof bundle
  * (directory, .tar, .tar.gz, or .tgz) and writes the verdict JSON to
@@ -22,6 +23,13 @@
  * what bounds it. Human text on stdout by default; --json for the
  * bitgraph-check/1 report. Offline. See check.ts for the vocabulary.
  *
+ * Pin: fetches https://<domain>/.well-known/bitgraph once (the ONLY
+ * network access anywhere in this package, and only when invoked), shows
+ * the party and every key's fingerprint, and stores the bytes verbatim
+ * after confirmation. `check --from <domain>` then adds one three-valued
+ * "domain" line per recording, offline, from the stored pin: TRUE or
+ * UNDETERMINED, never FALSE. Format and semantics: DOMAIN.md.
+ *
  * Exit codes: 0 TRUE, 1 FALSE, 2 UNDETERMINED, 3 error (init: 0 or 3).
  * Diagnostics go to stderr; stdout carries the verdict (or skeleton, or
  * check report) bytes only.
@@ -35,10 +43,14 @@ import { createHash } from "node:crypto";
 import { createReadStream, existsSync, writeFileSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { basename } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { pipeline } from "node:stream/promises";
 import type { AuditResult, BundleEntrySource } from "@mikeargento/bitgraph-audit";
 import { ingestBundle, ingestEntries } from "@mikeargento/bitgraph-audit";
+import type { CheckOptions } from "./check.js";
 import { checkIngest, renderCheckText, serializeCheckReport } from "./check.js";
+import { checkDomain, diffDomainFiles, domainKeyRefs, DomainFileError, isDomainName } from "./domain.js";
+import { defaultPinsDir, fetchDomainFile, forgetPin, listPins, readPin, writePin } from "./pin.js";
 import { scaffoldRule } from "./init.js";
 import type { ScaffoldEntry } from "./init.js";
 import { play, PlayError } from "./play.js";
@@ -49,8 +61,12 @@ function usage(): number {
     "usage: bitgraph-play <rule.json> <bundle> [--out <file>] [--summary]\n" +
       "       bitgraph-play init <file>... [--out <rule.json>]\n" +
       "       bitgraph-play check <bundle-or-file>... [--json] [--out <file>]\n" +
-      '  "--" ends option parsing; a rule file literally named "init" or\n' +
-      '  "check" is evaluated with: bitgraph-play -- init <bundle>\n' +
+      "                          [--from <domain> [--pins <dir>]]\n" +
+      "       bitgraph-play pin [<domain>] [--forget <domain>] [--pins <dir>] [--yes]\n" +
+      '  "--" ends option parsing; a rule file literally named "init",\n' +
+      '  "check" or "pin" is evaluated with: bitgraph-play -- init <bundle>\n' +
+      "  pin is the only command that touches the network; check --from\n" +
+      "  reads the stored pin and runs offline\n" +
       "  exit codes: 0 TRUE, 1 FALSE, 2 UNDETERMINED, 3 error\n"
   );
   return 3;
@@ -91,10 +107,18 @@ interface ParsedArgs {
   outFile?: string;
   summary: boolean;
   json: boolean;
+  from?: string;
+  pinsDir?: string;
+  forget?: string;
+  yes: boolean;
 }
 
 function parseArgs(args: string[]): ParsedArgs | undefined {
-  const parsed: ParsedArgs = { positional: [], summary: false, json: false };
+  const parsed: ParsedArgs = { positional: [], summary: false, json: false, yes: false };
+  const valueFor = (i: number): string | undefined => {
+    const next = args[i];
+    return next === undefined || next.startsWith("-") ? undefined : next;
+  };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i] as string;
     if (arg === "--") {
@@ -102,13 +126,27 @@ function parseArgs(args: string[]): ParsedArgs | undefined {
       parsed.positional.push(...args.slice(i + 1));
       break;
     } else if (arg === "--out") {
-      const next = args[++i];
-      if (next === undefined || next.startsWith("-")) return undefined;
+      const next = valueFor(++i);
+      if (next === undefined) return undefined;
       parsed.outFile = next;
+    } else if (arg === "--from") {
+      const next = valueFor(++i);
+      if (next === undefined) return undefined;
+      parsed.from = next;
+    } else if (arg === "--pins") {
+      const next = valueFor(++i);
+      if (next === undefined) return undefined;
+      parsed.pinsDir = next;
+    } else if (arg === "--forget") {
+      const next = valueFor(++i);
+      if (next === undefined) return undefined;
+      parsed.forget = next;
     } else if (arg === "--summary") {
       parsed.summary = true;
     } else if (arg === "--json") {
       parsed.json = true;
+    } else if (arg === "--yes") {
+      parsed.yes = true;
     } else if (arg.startsWith("-")) {
       return undefined;
     } else {
@@ -125,10 +163,43 @@ function parseArgs(args: string[]): ParsedArgs | undefined {
  * `bitgraph-play check proof.json photo.jpg` works without a folder.
  */
 async function runCheck(args: ParsedArgs): Promise<number> {
-  if (args.summary) return usage();
+  if (args.summary || args.yes || args.forget !== undefined) return usage();
+  if (args.pinsDir !== undefined && args.from === undefined) return usage();
   const targets = args.positional;
   if (targets.length === 0) return usage();
 
+  // Resolve the pin before touching the bundle: a missing pin should fail
+  // in milliseconds, with its remedy, not after a long ingest. check
+  // itself NEVER fetches; the pin was the one network step, already done.
+  let options: CheckOptions | undefined;
+  if (args.from !== undefined) {
+    const domain = args.from.toLowerCase();
+    if (!isDomainName(domain)) {
+      process.stderr.write(`error: not a domain name: ${args.from}\n`);
+      return 3;
+    }
+    const pinsDir = args.pinsDir ?? defaultPinsDir();
+    let pin;
+    try {
+      pin = readPin(domain, pinsDir);
+    } catch (err) {
+      process.stderr.write(`error: the stored pin for ${domain} is malformed`);
+      if (err instanceof DomainFileError && err.issues[0] !== undefined) {
+        process.stderr.write(`: ${err.issues[0]}`);
+      }
+      process.stderr.write(`\n  pin it again:  bitgraph-play pin ${domain}\n`);
+      return 3;
+    }
+    if (pin === undefined) {
+      process.stderr.write(
+        `error: no pin for ${domain}\n` +
+          `  pin it once (the only step that needs the network):  bitgraph-play pin ${domain}\n`
+      );
+      return 3;
+    }
+    options = { from: checkDomain(pin.file) };
+  }
+
   let ingest;
   try {
     const single = targets.length === 1 ? await stat(targets[0] as string) : undefined;
@@ -153,7 +224,7 @@ async function runCheck(args: ParsedArgs): Promise<number> {
     return 3;
   }
 
-  const report = await checkIngest(ingest);
+  const report = await checkIngest(ingest, options);
   const bytes = args.json ? serializeCheckReport(report) : renderCheckText(report);
   if (args.outFile !== undefined) {
     writeFileSync(args.outFile, bytes);
@@ -169,7 +240,7 @@ function looksLikeArchive(path: string): boolean {
 }
 
 async function runInit(args: ParsedArgs): Promise<number> {
-  if (args.summary || args.json) return usage();
+  if (args.summary || args.json || args.from !== undefined || args.pinsDir !== undefined || args.yes || args.forget !== undefined) return usage();
   const files = args.positional;
   if (files.length === 0) return usage();
   if (args.outFile !== undefined && existsSync(args.outFile)) {
@@ -225,7 +296,8 @@ async function runInit(args: ParsedArgs): Promise<number> {
 }
 
 async function runEvaluate(args: ParsedArgs): Promise<number> {
-  if (args.json || args.positional.length !== 2) return usage();
+  if (args.json || args.from !== undefined || args.pinsDir !== undefined || args.yes || args.forget !== undefined) return usage();
+  if (args.positional.length !== 2) return usage();
   const [rulePath, bundlePath] = args.positional as [string, string];
 
   let result;
@@ -252,12 +324,126 @@ async function runEvaluate(args: ParsedArgs): Promise<number> {
   return result.exitCode;
 }
 
+/**
+ * pin: the only command in this package that touches the network, and
+ * only when invoked. Conversational output goes to stderr (there are no
+ * report bytes); the pin listing, which IS the output, goes to stdout.
+ */
+async function runPin(args: ParsedArgs): Promise<number> {
+  if (args.summary || args.json || args.outFile !== undefined || args.from !== undefined) return usage();
+  const pinsDir = args.pinsDir ?? defaultPinsDir();
+
+  if (args.forget !== undefined) {
+    if (args.positional.length !== 0) return usage();
+    const domain = args.forget.toLowerCase();
+    if (!isDomainName(domain)) {
+      process.stderr.write(`error: not a domain name: ${args.forget}\n`);
+      return 3;
+    }
+    if (forgetPin(domain, pinsDir)) {
+      process.stderr.write(`forgot ${domain}\n`);
+      return 0;
+    }
+    process.stderr.write(`error: no pin for ${domain}\n`);
+    return 3;
+  }
+
+  if (args.positional.length === 0) {
+    const pins = listPins(pinsDir);
+    if (pins.length === 0) {
+      process.stderr.write(
+        "no pins yet\n  pin a domain (the only step that needs the network):  bitgraph-play pin <domain>\n"
+      );
+      return 0;
+    }
+    for (const pin of pins) {
+      process.stdout.write(
+        pin.malformed
+          ? `${pin.domain}  (malformed pin; pin it again or --forget it)\n`
+          : `${pin.domain}  ${pin.party as string}  ${pin.keyCount as number} key(s)  pinned ${pin.pinnedAt.toISOString().slice(0, 10)}\n`
+      );
+    }
+    return 0;
+  }
+
+  if (args.positional.length !== 1) return usage();
+  const domain = (args.positional[0] as string).toLowerCase();
+
+  let fetched;
+  try {
+    fetched = await fetchDomainFile(domain);
+  } catch (err) {
+    if (err instanceof DomainFileError) {
+      process.stderr.write(
+        `error: the file at https://${domain}/.well-known/bitgraph is not a valid bitgraph-domain/1 file:\n`
+      );
+      for (const issue of err.issues) process.stderr.write(`  - ${issue}\n`);
+    } else {
+      process.stderr.write(`error: ${(err as Error).message}\n`);
+    }
+    return 3;
+  }
+
+  const refs = domainKeyRefs(fetched.file);
+  const nameWidth = refs.reduce((w, r) => Math.max(w, r.name.length), 4);
+  process.stderr.write(`\n${domain} · ${fetched.file.party}\n`);
+  for (const ref of refs) {
+    process.stderr.write(`  ${ref.name.padEnd(nameWidth)}  ${ref.key.alg.padEnd(7)}  ${ref.fingerprint}\n`);
+  }
+
+  let existing;
+  let existingMalformed = false;
+  try {
+    existing = readPin(domain, pinsDir);
+  } catch {
+    existingMalformed = true;
+  }
+  if (existingMalformed) {
+    process.stderr.write(`\nthe stored pin for ${domain} is malformed and will be replaced\n`);
+  } else if (existing !== undefined) {
+    const diff = diffDomainFiles(existing.file, fetched.file);
+    const changes: string[] = [];
+    if (diff.partyChanged !== undefined) {
+      changes.push(`  party: "${diff.partyChanged.before}" is now "${diff.partyChanged.after}"`);
+    }
+    for (const ref of diff.added) changes.push(`  + ${ref.name}  ${ref.key.alg}  ${ref.fingerprint}`);
+    for (const ref of diff.removed) changes.push(`  - ${ref.name}  ${ref.key.alg}  ${ref.fingerprint}`);
+    for (const ch of diff.changed) changes.push(`  ~ ${ch.name}  now ${ch.after.key.alg}  ${ch.after.fingerprint}`);
+    const pinnedOn = existing.pinnedAt.toISOString().slice(0, 10);
+    process.stderr.write(
+      changes.length === 0
+        ? `\nunchanged since the stored pin (${pinnedOn})\n`
+        : `\nchanges since the stored pin (${pinnedOn}):\n${changes.join("\n")}\n`
+    );
+  }
+
+  if (!args.yes) {
+    if (!process.stdin.isTTY) {
+      process.stderr.write("\nerror: not a terminal; pass --yes to pin non-interactively\n");
+      return 3;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const answer = (await rl.question(`\npin ${refs.length} key(s) for ${domain}? [y/N] `)).trim().toLowerCase();
+    rl.close();
+    if (answer !== "y" && answer !== "yes") {
+      process.stderr.write("not pinned\n");
+      return 3;
+    }
+  }
+
+  const path = writePin(domain, fetched.bytes, pinsDir);
+  process.stderr.write(
+    `pinned: ${path}\nchecks now run offline:  bitgraph-play check <export> --from ${domain}\n`
+  );
+  return 0;
+}
+
 async function main(): Promise<number> {
   const argv = process.argv.slice(2);
   // "--" as the first token forces evaluate mode: parseArgs treats
   // everything after it as positional, so a rule file literally named
-  // "init" or "check" is reachable as `bitgraph-play -- init <bundle>`.
-  const subcommand = argv[0] === "init" || argv[0] === "check" ? argv[0] : undefined;
+  // "init", "check" or "pin" is reachable as `bitgraph-play -- init <bundle>`.
+  const subcommand = argv[0] === "init" || argv[0] === "check" || argv[0] === "pin" ? argv[0] : undefined;
   if (subcommand !== undefined && existsSync(subcommand)) {
     // Both readings are plausible here; a silent pick would hand a
     // 0.1.1 caller a skeleton with exit 0 where the published contract
@@ -273,6 +459,7 @@ async function main(): Promise<number> {
   if (parsed === undefined) return usage();
   if (subcommand === "init") return runInit(parsed);
   if (subcommand === "check") return runCheck(parsed);
+  if (subcommand === "pin") return runPin(parsed);
   return runEvaluate(parsed);
 }
 

package/src/domain.ts

@@ -0,0 +1,245 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * BitGraph Domain: a party's own domain publishing the keys that record
+ * for it. The file (`bitgraph-domain/1`) is served at
+ * `https://<domain>/.well-known/bitgraph` and is the party speaking for
+ * itself, never BitGraph speaking about the party: parsing enforces
+ * well-formedness only, and adopting the statement is the reader's act
+ * (see pin.ts). The format is DOMAIN.md; evaluation semantics (SPEC.md
+ * sections 1 through 9) are untouched by everything in this module.
+ *
+ * The file shares SPEC section 9.1's trusted-key grammar, so an entry
+ * pastes into a format 2 rule's `trustedKeys` unchanged, and a key's
+ * fingerprint is the lowercase hex SHA-256 of the decoded key bytes,
+ * which for es256 is exactly the `keyId` actor proofs carry. Fingerprints
+ * are always derived here and never read from the file, so a domain
+ * cannot claim a key it does not show.
+ */
+
+import { createHash } from "node:crypto";
+import type { CheckDomain } from "./check.js";
+import { decodeDigestBytes } from "./rule.js";
+import type { TrustedKey } from "./sig.js";
+import { decodeB64Strict, keyObjectFor, parseSigFile, verifySigFile } from "./sig.js";
+
+export const DOMAIN_FILE_VERSION = "bitgraph-domain/1";
+export const DOMAIN_WELL_KNOWN_PATH = "/.well-known/bitgraph";
+export const DOMAIN_FILE_MAX_BYTES = 65_536;
+
+export interface DomainFile {
+  version: "bitgraph-domain/1";
+  /** Lowercase hostname; the binding. Must equal the domain the reader asked for. */
+  domain: string;
+  /** The name the domain gives itself. Display only. */
+  party: string;
+  /** SPEC §9.1 trusted-key bodies, named. */
+  keys: Record<string, TrustedKey>;
+}
+
+export class DomainFileError extends Error {
+  readonly issues: readonly string[];
+  constructor(issues: string[]) {
+    super(issues[0] ?? "invalid domain file");
+    this.name = "DomainFileError";
+    this.issues = issues;
+  }
+}
+
+/**
+ * Lowercase registrable hostname: dot-separated LDH labels, at least two,
+ * no scheme, no port, no path. Also the safety property the pin store
+ * rests on: a name this grammar accepts contains no path separators.
+ */
+const LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
+const DOMAIN_RE = new RegExp(`^${LABEL}(?:\\.${LABEL})+$`);
+
+export function isDomainName(s: string): boolean {
+  return s.length > 0 && s.length <= 253 && DOMAIN_RE.test(s);
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Parse and validate a bitgraph-domain/1 file. Strict: unknown fields are
+ * errors (additions are a new format version), and key material that does
+ * not decode is refused here rather than stored, so a pin can never hold
+ * keys that silently match nothing. Throws DomainFileError with every
+ * issue found.
+ */
+export function parseDomainFile(input: Uint8Array | string, expectedDomain?: string): DomainFile {
+  const issues: string[] = [];
+  const text = typeof input === "string" ? input : Buffer.from(input).toString("utf8");
+  if (typeof input !== "string" && input.length > DOMAIN_FILE_MAX_BYTES) {
+    throw new DomainFileError([`file is ${input.length} bytes; the cap is ${DOMAIN_FILE_MAX_BYTES}`]);
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    throw new DomainFileError([`not JSON: ${(err as Error).message}`]);
+  }
+  if (!isPlainObject(raw)) throw new DomainFileError(["not a JSON object"]);
+
+  for (const k of Object.keys(raw)) {
+    if (!["version", "domain", "party", "keys"].includes(k)) {
+      issues.push(`unknown field "${k}" (additions are a new format version)`);
+    }
+  }
+
+  if (raw["version"] !== DOMAIN_FILE_VERSION) {
+    issues.push(`"version" must be exactly "${DOMAIN_FILE_VERSION}"`);
+  }
+
+  const domain = raw["domain"];
+  if (typeof domain !== "string" || !isDomainName(domain)) {
+    issues.push(`"domain" must be a lowercase hostname (no scheme, no port, no path)`);
+  } else if (expectedDomain !== undefined && domain !== expectedDomain) {
+    issues.push(
+      `the file names domain "${domain}" but was requested for "${expectedDomain}"; refusing to store one party's file under another party's name`
+    );
+  }
+
+  const party = raw["party"];
+  if (typeof party !== "string" || party.trim().length === 0) {
+    issues.push(`"party" is required: the name the domain gives itself`);
+  }
+
+  const keys = Object.create(null) as Record<string, TrustedKey>;
+  const rawKeys = raw["keys"];
+  if (!isPlainObject(rawKeys) || Object.keys(rawKeys).length === 0) {
+    issues.push(`"keys" must be an object naming at least one key`);
+  } else {
+    for (const [name, entry] of Object.entries(rawKeys)) {
+      const where = `keys.${name}`;
+      if (!/^[A-Za-z0-9_.-]+$/.test(name) || /^[0-9]+$/.test(name)) {
+        issues.push(`${where}: key name must match [A-Za-z0-9_.-]+ with at least one non-digit`);
+        continue;
+      }
+      if (!isPlainObject(entry)) {
+        issues.push(`${where}: must be an object`);
+        continue;
+      }
+      for (const k of Object.keys(entry)) {
+        if (k !== "alg" && k !== "publicKey") issues.push(`${where}: unknown field "${k}"`);
+      }
+      const alg = entry["alg"];
+      const publicKey = entry["publicKey"];
+      if (alg !== "ed25519" && alg !== "es256") {
+        issues.push(`${where}: "alg" must be "ed25519" or "es256"`);
+        continue;
+      }
+      if (typeof publicKey !== "string" || publicKey.length === 0) {
+        issues.push(`${where}: "publicKey" is required and must be a non-empty string`);
+        continue;
+      }
+      const key: TrustedKey = { alg, publicKey };
+      if (keyObjectFor(key) === undefined) {
+        issues.push(
+          `${where}: key material does not decode as ${alg} (${alg === "es256" ? "SPKI DER for P-256" : "raw 32-byte key"}, standard base64)`
+        );
+        continue;
+      }
+      keys[name] = key;
+    }
+  }
+
+  if (issues.length > 0) throw new DomainFileError(issues);
+  return { version: DOMAIN_FILE_VERSION, domain: domain as string, party: (party as string).trim(), keys };
+}
+
+/**
+ * Lowercase hex SHA-256 of the decoded publicKey bytes. For es256 this is
+ * exactly the actor keyId (hex SHA-256 of the SPKI DER). Undefined when
+ * the material does not decode, which parseDomainFile refuses anyway.
+ */
+export function keyFingerprint(key: TrustedKey): string | undefined {
+  const material = decodeB64Strict(key.publicKey);
+  if (material === undefined) return undefined;
+  return createHash("sha256").update(material).digest("hex");
+}
+
+export interface DomainKeyRef {
+  name: string;
+  key: TrustedKey;
+  fingerprint: string;
+}
+
+/** Every key with its derived fingerprint, name order. */
+export function domainKeyRefs(file: DomainFile): DomainKeyRef[] {
+  const refs: DomainKeyRef[] = [];
+  for (const name of Object.keys(file.keys).sort()) {
+    const key = file.keys[name] as TrustedKey;
+    const fingerprint = keyFingerprint(key);
+    if (fingerprint !== undefined) refs.push({ name, key, fingerprint });
+  }
+  return refs;
+}
+
+export interface DomainDiff {
+  partyChanged?: { before: string; after: string };
+  added: DomainKeyRef[];
+  removed: DomainKeyRef[];
+  changed: { name: string; before: DomainKeyRef; after: DomainKeyRef }[];
+  unchanged: number;
+}
+
+/** What a re-pin would change, for showing before asking. */
+export function diffDomainFiles(before: DomainFile, after: DomainFile): DomainDiff {
+  const beforeRefs = new Map(domainKeyRefs(before).map((r) => [r.name, r]));
+  const afterRefs = new Map(domainKeyRefs(after).map((r) => [r.name, r]));
+  const diff: DomainDiff = { added: [], removed: [], changed: [], unchanged: 0 };
+  if (before.party !== after.party) diff.partyChanged = { before: before.party, after: after.party };
+  for (const [name, ref] of afterRefs) {
+    const prior = beforeRefs.get(name);
+    if (prior === undefined) diff.added.push(ref);
+    else if (prior.key.alg !== ref.key.alg || prior.key.publicKey !== ref.key.publicKey) {
+      diff.changed.push({ name, before: prior, after: ref });
+    } else diff.unchanged += 1;
+  }
+  for (const [name, ref] of beforeRefs) {
+    if (!afterRefs.has(name)) diff.removed.push(ref);
+  }
+  return diff;
+}
+
+/**
+ * The check-report adapter: what `check --from` consults per recording.
+ * Defined as an interface in check.ts so the check module (which also
+ * builds verify.html) never imports the crypto this module uses; the CLI
+ * hands the report builder this object.
+ */
+export function checkDomain(file: DomainFile): CheckDomain {
+  const actorNames = new Map<string, string>();
+  for (const ref of domainKeyRefs(file)) {
+    if (ref.key.alg !== "es256") continue;
+    if (!actorNames.has(ref.fingerprint)) actorNames.set(ref.fingerprint, ref.name);
+  }
+  const sigKeys = domainKeyRefs(file)
+    .map((ref) => ({ name: ref.name, key: ref.key, keyObject: keyObjectFor(ref.key) }))
+    .filter((k) => k.keyObject !== undefined);
+
+  return {
+    domain: file.domain,
+    party: file.party,
+    keyCount: Object.keys(file.keys).length,
+    actorKeyName: (keyId: string): string | undefined => actorNames.get(keyId.toLowerCase()),
+    signatureKeyName: (targetSha256Hex: string, evidence: ReadonlyMap<string, Uint8Array>): string | undefined => {
+      // Deterministic: candidates in ascending content-hash order, keys in
+      // name order; the first verifying pair decides (SPEC §9.4 discipline).
+      for (const sha256Hex of [...evidence.keys()].sort()) {
+        const sig = parseSigFile(evidence.get(sha256Hex) as Uint8Array);
+        if (sig === undefined) continue;
+        for (const k of sigKeys) {
+          if (verifySigFile(sig, k.key, k.keyObject as NonNullable<typeof k.keyObject>, targetSha256Hex, decodeDigestBytes)) {
+            return k.name;
+          }
+        }
+      }
+      return undefined;
+    },
+  };
+}

package/src/index.ts

@@ -46,4 +46,20 @@ export type { Evaluation } from "./evaluate.js";
 export { buildVerdict, serializeVerdict, playerVersion, PLAYER_VERSION } from "./verdict.js";
 
 export { checkIngest, buildCheckReport, renderCheckText, serializeCheckReport, KNOWN_ENCLAVE_MEASUREMENTS } from "./check.js";
-export type { CheckReport, CheckRecording, CheckAnchor, CheckLine, CheckBounds, CheckBound, CheckOptions } from "./check.js";
+export type { CheckReport, CheckRecording, CheckAnchor, CheckLine, CheckBounds, CheckBound, CheckOptions, CheckDomain } from "./check.js";
+
+export {
+  parseDomainFile,
+  isDomainName,
+  keyFingerprint,
+  domainKeyRefs,
+  diffDomainFiles,
+  checkDomain,
+  DomainFileError,
+  DOMAIN_FILE_VERSION,
+  DOMAIN_WELL_KNOWN_PATH,
+  DOMAIN_FILE_MAX_BYTES,
+} from "./domain.js";
+export type { DomainFile, DomainKeyRef, DomainDiff } from "./domain.js";
+export { defaultPinsDir, readPin, writePin, forgetPin, listPins, fetchDomainFile } from "./pin.js";
+export type { StoredPin, PinListEntry, FetchLike } from "./pin.js";