@mikeargento/bitgraph-player 0.5.2 → 0.7.0

package/src/check.ts

@@ -63,8 +63,9 @@ import type {
   SegmentBound,
   TemporalSegment,
 } from "@mikeargento/bitgraph-audit";
-import { auditIngest, AUDIT_VERSION } from "@mikeargento/bitgraph-audit";
+import { auditIngest, AUDIT_VERSION, streamMatchedArtifacts } from "@mikeargento/bitgraph-audit";
 import type { ThreeValued } from "./types.js";
+import { SIG_EVIDENCE_MAX_BYTES } from "./types.js";
 import { kleeneAll } from "./logic.js";
 import { PLAYER_VERSION } from "./verdict.js";
 
@@ -107,7 +108,7 @@ export const KNOWN_ENCLAVE_MEASUREMENTS: ReadonlyArray<{ pcr0: string; label: st
 
 /** One checked property, three-valued, with a plain-language reason. */
 export interface CheckLine {
-  name: "file" | "signature" | "attestation" | "enclave" | "witness" | "contradiction";
+  name: "file" | "signature" | "attestation" | "enclave" | "witness" | "contradiction" | "domain";
   result: ThreeValued;
   detail: string;
 }
@@ -124,7 +125,7 @@ export interface CheckBound {
 }
 
 export interface CheckBounds {
-  status: "bracketed" | "lower-bounded" | "upper-bounded" | "unanchored";
+  status: "lower-bounded-with-following-anchor" | "lower-bounded" | "upper-bounded" | "unanchored";
   notBefore?: CheckBound;
   notAfter?: CheckBound;
   detail: string;
@@ -162,7 +163,10 @@ export interface CheckAnchor {
 }
 
 export interface CheckReport {
-  check: "bitgraph-check/1";
+  /** /2 exactly when the report was built against a pinned domain (`from`). */
+  check: "bitgraph-check/1" | "bitgraph-check/2";
+  /** The pinned domain this report was checked against, when one was. */
+  from?: { domain: string; party: string };
   result: ThreeValued;
   /** One-sentence plain-language conclusion, deterministic. */
   summary: string;
@@ -178,6 +182,31 @@ export interface CheckReport {
   network: "none";
 }
 
+/**
+ * A pinned BitGraph Domain, as the report builder consults it: one line
+ * per recording, TRUE or UNDETERMINED, never FALSE (absence of domain
+ * evidence contradicts nothing; the open-world rule of SPEC §9.3).
+ *
+ * An interface here rather than an import from domain.ts, deliberately:
+ * this module is also built into the browser verifier, and the crypto the
+ * adapter needs (key decoding, signature verification) stays behind it.
+ * domain.ts's `checkDomain(file)` is the implementation; embedders may
+ * supply their own.
+ */
+export interface CheckDomain {
+  domain: string;
+  party: string;
+  keyCount: number;
+  /** Key name for an actor keyId (es256 fingerprint match), if published. */
+  actorKeyName(keyId: string): string | undefined;
+  /**
+   * Key name of the first pinned key a candidate bitgraph-sig/1 file
+   * verifies under, over this digest (lowercase hex). Deterministic:
+   * candidates ascending by content hash, keys in name order.
+   */
+  signatureKeyName(targetSha256Hex: string, evidence: ReadonlyMap<string, Uint8Array>): string | undefined;
+}
+
 export interface CheckOptions {
   /**
    * False when the environment cannot run the attestation's ECDSA P-384
@@ -185,6 +214,19 @@ export interface CheckOptions {
    * with that reason instead of a false FALSE. Defaults to true.
    */
   webCryptoAvailable?: boolean;
+  /**
+   * Check against a pinned domain: adds one "domain" line per recording
+   * and stamps the report bitgraph-check/2. The check itself stays
+   * offline; the pin was the one fetch, and it already happened.
+   */
+  from?: CheckDomain;
+  /**
+   * Candidate signature bytes by content sha256 hex, for the domain
+   * line's detached-signature path (SPEC §9.4 discipline). checkIngest
+   * collects this from the bundle's matched artifacts when absent;
+   * embedders may supply additional candidates.
+   */
+  sigEvidence?: ReadonlyMap<string, Uint8Array>;
 }
 
 // ---------------------------------------------------------------------------
@@ -215,8 +257,20 @@ const EXCERPT_NORMAL_CODES: ReadonlySet<string> = new Set([
  * browser page call this, so they cannot drift.
  */
 export async function checkIngest(ingest: IngestResult, options?: CheckOptions): Promise<CheckReport> {
+  let opts = options;
+  // Domain checking's detached-signature path wants the same candidate set
+  // the evaluator uses (SPEC §9.4: matched artifacts, size-capped). Collect
+  // it here, where the ingest is in hand, unless the embedder supplied one.
+  if (opts?.from !== undefined && opts.sigEvidence === undefined) {
+    const collected = new Map<string, Uint8Array>();
+    for await (const matched of streamMatchedArtifacts(ingest)) {
+      if (matched.bytes.length > SIG_EVIDENCE_MAX_BYTES) continue;
+      if (!collected.has(matched.sha256Hex)) collected.set(matched.sha256Hex, matched.bytes);
+    }
+    opts = { ...opts, sigEvidence: collected };
+  }
   const audit = await auditIngest(ingest, { startedAt: "" });
-  return buildCheckReport(audit, options);
+  return buildCheckReport(audit, opts);
 }
 
 /** The pure report builder over an AuditResult. */
@@ -260,7 +314,9 @@ export function buildCheckReport(audit: AuditResult, options?: CheckOptions): Ch
           attestationByHash.get(proof.proofHash),
           segmentByHash.get(proof.proofHash),
           artifactPathByProof.get(proof.proofHash),
-          webCrypto
+          webCrypto,
+          options?.from,
+          options?.sigEvidence
         )
       );
     }
@@ -270,7 +326,7 @@ export function buildCheckReport(audit: AuditResult, options?: CheckOptions): Ch
   sortByPosition(anchors);
   const contradictions = collectContradictions(audit);
   const notes = collectNotes(audit, recordings, anchors);
-  const notChecked = collectNotChecked(anchors.length > 0);
+  const notChecked = collectNotChecked(anchors.length > 0, options?.from?.domain);
 
   const allLines: ThreeValued[] = [
     ...recordings.map((r) => r.result),
@@ -280,7 +336,10 @@ export function buildCheckReport(audit: AuditResult, options?: CheckOptions): Ch
   const result: ThreeValued = allLines.length === 0 ? "UNDETERMINED" : kleeneAll(allLines);
 
   return {
-    check: "bitgraph-check/1",
+    check: options?.from !== undefined ? "bitgraph-check/2" : "bitgraph-check/1",
+    ...(options?.from !== undefined
+      ? { from: { domain: options.from.domain, party: options.from.party } }
+      : {}),
     result,
     summary: summarize(result, recordings, anchors, contradictions),
     recordings,
@@ -322,7 +381,9 @@ function buildRecording(
   attestation: ProofAttestationRecord | undefined,
   segment: TemporalSegment | undefined,
   filePath: string | undefined,
-  webCrypto: boolean
+  webCrypto: boolean,
+  from?: CheckDomain,
+  sigEvidence?: ReadonlyMap<string, Uint8Array>
 ): CheckRecording {
   const lines: CheckLine[] = [];
   const v = proof.verification;
@@ -374,6 +435,19 @@ function buildRecording(
   // enclave: the attested PCR0 is a published BitGraph measurement.
   lines.push(enclaveLine(att.attestedPcr0, att.line.result));
 
+  // domain: a key the pinned domain published stands behind this
+  // recording. TRUE or UNDETERMINED, never FALSE: domain evidence can
+  // exist outside any bundle, so its absence contradicts nothing
+  // (SPEC §9.3's open-world rule); tampering already reads FALSE on the
+  // lines above, and this line does not restate them.
+  if (from !== undefined) {
+    // Verified exactly when the signature line above reads TRUE: the
+    // integrity-tier "artifact-unavailable" status is a PASS (proof-only
+    // bundles verify; whether bytes are in hand is the file line's job).
+    const verified = v !== undefined && v.status !== "failed";
+    lines.push(domainLine(proof, verified, from, sigEvidence ?? EMPTY_EVIDENCE));
+  }
+
   const result = kleeneAll(lines.map((l) => l.result));
 
   return {
@@ -453,6 +527,64 @@ function attestationLine(
   };
 }
 
+const EMPTY_EVIDENCE: ReadonlyMap<string, Uint8Array> = new Map();
+
+function domainLine(
+  proof: ObservedProof,
+  verified: boolean,
+  from: CheckDomain,
+  sigEvidence: ReadonlyMap<string, Uint8Array>
+): CheckLine {
+  if (!verified) {
+    return {
+      name: "domain",
+      result: "UNDETERMINED",
+      detail: `the recording is not verified here, so nothing binds it to ${from.domain}`,
+    };
+  }
+  const actorKeyId = proof.proof.agency?.actor?.keyId;
+  if (actorKeyId !== undefined) {
+    const name = from.actorKeyName(actorKeyId);
+    if (name !== undefined) {
+      return {
+        name: "domain",
+        result: "TRUE",
+        detail: `actor key "${name}" · published by ${from.domain} (${from.party})`,
+      };
+    }
+  }
+  const targetBytes = decodeDigestB64(proof.proof.artifact.digestB64);
+  if (targetBytes !== undefined && sigEvidence.size > 0) {
+    const name = from.signatureKeyName(targetBytes.toString("hex"), sigEvidence);
+    if (name !== undefined) {
+      return {
+        name: "domain",
+        result: "TRUE",
+        detail: `signature by "${name}" · published by ${from.domain} (${from.party})`,
+      };
+    }
+  }
+  if (actorKeyId !== undefined) {
+    return {
+      name: "domain",
+      result: "UNDETERMINED",
+      detail: `actor key ${actorKeyId.slice(0, 12)}… is not among the ${from.keyCount} key(s) ${from.domain} publishes`,
+    };
+  }
+  return {
+    name: "domain",
+    result: "UNDETERMINED",
+    detail: `no evidence binds this recording to ${from.domain}`,
+  };
+}
+
+/** Standard-base64 digest to bytes; undefined when it does not round-trip. */
+function decodeDigestB64(digestB64: string): Buffer | undefined {
+  if (!/^[A-Za-z0-9+/]+=*$/.test(digestB64)) return undefined;
+  const bytes = Buffer.from(digestB64, "base64");
+  return bytes.toString("base64") === digestB64 ? bytes : undefined;
+}
+
 function enclaveLine(attestedPcr0: string | undefined, attestationResult: ThreeValued): CheckLine {
   if (attestationResult !== "TRUE" || attestedPcr0 === undefined) {
     return {
@@ -486,7 +618,7 @@ function boundsFor(segment: TemporalSegment | undefined): CheckBounds {
   const notAfter = upper === undefined ? undefined : toBound(upper);
   const status: CheckBounds["status"] =
     notBefore !== undefined && notAfter !== undefined
-      ? "bracketed"
+      ? "lower-bounded-with-following-anchor"
       : notBefore !== undefined
         ? "lower-bounded"
         : notAfter !== undefined
@@ -504,16 +636,22 @@ function boundsFor(segment: TemporalSegment | undefined): CheckBounds {
   };
 }
 
-/** "after Ethereum block A and before block B (both headers verified)…", shared by bounds.detail and the summary. */
+/**
+ * "after Ethereum block A; precedes an anchor that consumed block B", shared by bounds.detail and the summary.
+ * The following anchor is deliberately NOT rendered as "before block B": a proof precedes the anchor's
+ * commit, and block B's timestamp bounds that commit from below, not the proof from above. Reading it as
+ * a ceiling assumes the anchor consumed a recently published block. An inbound anchor cannot carry a
+ * proof of an upper bound, so the phrase says what the evidence supports and names the assumption.
+ */
 function boundsPhrase(
   status: CheckBounds["status"],
   notBefore: CheckBound | undefined,
   notAfter: CheckBound | undefined
 ): string {
   switch (status) {
-    case "bracketed":
+    case "lower-bounded-with-following-anchor":
       return (
-        `after Ethereum block ${blockRef(notBefore as CheckBound)} and before block ${blockRef(notAfter as CheckBound)} (both headers verified in this bundle)` +
+        `after Ethereum block ${blockRef(notBefore as CheckBound)} (header verified in this bundle); precedes an anchor that consumed block ${blockRef(notAfter as CheckBound)} (header verified), an anchor-latency assumption rather than an upper bound on this recording` +
         weakerSuffix((notBefore as CheckBound).weaker || (notAfter as CheckBound).weaker)
       );
     case "lower-bounded":
@@ -557,8 +695,8 @@ function toBound(b: SegmentBound): CheckBound {
 /** The headline form of the bounds: one clause, no qualifiers (those live in bounds.detail). */
 function shortBoundsPhrase(b: CheckBounds): string {
   switch (b.status) {
-    case "bracketed":
-      return `between Ethereum blocks ${blockRef(b.notBefore as CheckBound)} and ${blockRef(b.notAfter as CheckBound)}`;
+    case "lower-bounded-with-following-anchor":
+      return `after Ethereum block ${blockRef(b.notBefore as CheckBound)}, then an anchor at block ${blockRef(b.notAfter as CheckBound)}`;
     case "lower-bounded":
       return `after Ethereum block ${blockRef(b.notBefore as CheckBound)}`;
     case "upper-bounded":
@@ -751,13 +889,18 @@ function collectNotes(audit: AuditResult, recordings: CheckRecording[], anchors:
   return notes;
 }
 
-function collectNotChecked(hasAnchors: boolean): string[] {
+function collectNotChecked(hasAnchors: boolean, fromDomain?: string): string[] {
   const out: string[] = [];
   if (hasAnchors) {
     out.push(
       "whether the anchored Ethereum blocks are canonical: their headers are recomputed here, but canonicality needs an Ethereum node or a block explorer"
     );
   }
+  if (fromDomain !== undefined) {
+    out.push(
+      `whether ${fromDomain}'s published key file has changed since it was pinned: a pin is read as stored; pin the domain again to refresh it`
+    );
+  }
   out.push(
     "whether the public ledger holds these exact recordings at these positions: this is an offline check; drop the file on bitgraph.ing to compare against the ledger"
   );
@@ -812,6 +955,9 @@ export function renderCheckText(report: CheckReport): string {
   const out: string[] = [];
   const mark = (r: ThreeValued): string => (r === "TRUE" ? "TRUE " : r === "FALSE" ? "FALSE" : "UNDET");
   out.push(report.summary);
+  if (report.from !== undefined) {
+    out.push(`checked against ${report.from.domain} (${report.from.party}), from the stored pin`);
+  }
   out.push("");
   report.recordings.forEach((rec, i) => {
     out.push(

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);
 }