@mikeargento/bitgraph-player 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikeargento/bitgraph-player",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Deterministic evaluation of causal rules over BitGraph proof bundles: a pure function from (rule, verified evidence) to a reproducible verdict.",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
     "dist-web",
     "src",
     "SPEC.md",
+    "DOMAIN.md",
     "README.md",
     "LICENSE"
   ],
@@ -35,8 +36,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@mikeargento/bitgraph-audit": "^0.2.1",
-    "@mikeargento/bitgraph-verify": "^1.2.0"
+    "@mikeargento/bitgraph-audit": "^0.2.2",
+    "@mikeargento/bitgraph-verify": "^1.3.0"
   },
   "devDependencies": {
     "@noble/curves": "^2.3.0",

package/src/__tests__/domain.test.ts

@@ -0,0 +1,321 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * BitGraph Domain: parseDomainFile, fingerprints, the pin store, the
+ * fetch, and check --from's "domain" line.
+ *
+ * The invariants under test:
+ *   - The domain line is TRUE or UNDETERMINED, never FALSE: absence of
+ *     domain evidence contradicts nothing (SPEC §9.3's open-world rule).
+ *   - Fingerprints are always derived from key material, never read from
+ *     the file; for es256 the fingerprint IS the actor keyId, proved
+ *     against the real declared recording (fixtures/declared-12010).
+ *   - A malformed file is refused at the pin, and a redirect cannot store
+ *     one party's file under another party's name (the `domain` field
+ *     must equal the domain the reader asked for).
+ *   - A report without --from stays bitgraph-check/1 with no `from` key.
+ *
+ * Everything runs in memory or under a temp dir. The fetch is injected;
+ * no network, no ledger writes, ever.
+ */
+
+import { strict as assert } from "node:assert";
+import { createHash, generateKeyPairSync, sign as cryptoSign } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { ingestEntries } from "@mikeargento/bitgraph-audit";
+import type { CheckRecording, CheckReport } from "../check.js";
+import { checkIngest } from "../check.js";
+import {
+  checkDomain,
+  diffDomainFiles,
+  DomainFileError,
+  domainKeyRefs,
+  isDomainName,
+  keyFingerprint,
+  parseDomainFile,
+} from "../domain.js";
+import { fetchDomainFile, forgetPin, listPins, readPin, writePin } from "../pin.js";
+import type { FetchLike } from "../pin.js";
+import { sigMessage } from "../sig.js";
+
+// ---------------------------------------------------------------------------
+// The real declared recording: actor key ee0c6517…, provider passkey
+// ---------------------------------------------------------------------------
+
+const proofBytes = readFileSync(new URL("../../src/__tests__/fixtures/declared-12010/proof.json", import.meta.url));
+const proofJson = JSON.parse(proofBytes.toString("utf8")) as {
+  agency: { actor: { publicKeyB64: string; keyId: string } };
+  artifact: { digestB64: string };
+};
+const ACTOR_KEY_B64 = proofJson.agency.actor.publicKeyB64;
+const ACTOR_KEY_ID = proofJson.agency.actor.keyId;
+const DIGEST_HEX = Buffer.from(proofJson.artifact.digestB64, "base64").toString("hex");
+
+function domainText(overrides?: Record<string, unknown>): string {
+  return JSON.stringify({
+    version: "bitgraph-domain/1",
+    domain: "acme.com",
+    party: "Acme Corp",
+    keys: { studio: { alg: "es256", publicKey: ACTOR_KEY_B64 } },
+    ...overrides,
+  });
+}
+
+async function ingestProof(bytes: Uint8Array = proofBytes) {
+  return ingestEntries([{ path: "proof.json", open: () => Promise.resolve(new Uint8Array(bytes)) }]);
+}
+
+function onlyRecording(report: CheckReport): CheckRecording {
+  assert.equal(report.recordings.length, 1);
+  return report.recordings[0] as CheckRecording;
+}
+
+function domainLineOf(recording: CheckRecording) {
+  const line = recording.lines.find((l) => l.name === "domain");
+  assert.notEqual(line, undefined, "expected a domain line");
+  return line as NonNullable<typeof line>;
+}
+
+// ---------------------------------------------------------------------------
+// Parsing and fingerprints
+// ---------------------------------------------------------------------------
+
+test("parseDomainFile accepts a valid file and derives the party/keys", () => {
+  const file = parseDomainFile(domainText(), "acme.com");
+  assert.equal(file.domain, "acme.com");
+  assert.equal(file.party, "Acme Corp");
+  assert.deepEqual(Object.keys(file.keys), ["studio"]);
+});
+
+test("isDomainName: lowercase dotted hostnames only", () => {
+  assert.equal(isDomainName("acme.com"), true);
+  assert.equal(isDomainName("sub.acme-corp.co.uk"), true);
+  assert.equal(isDomainName("ACME.com"), false);
+  assert.equal(isDomainName("acme"), false);
+  assert.equal(isDomainName("acme.com/path"), false);
+  assert.equal(isDomainName("https://acme.com"), false);
+  assert.equal(isDomainName("acme.com:443"), false);
+  assert.equal(isDomainName(""), false);
+});
+
+test("parseDomainFile refuses malformed files with every issue named", () => {
+  const bad = (text: string, expected?: string): string[] => {
+    try {
+      parseDomainFile(text, expected);
+    } catch (err) {
+      assert.ok(err instanceof DomainFileError);
+      return [...err.issues];
+    }
+    assert.fail("expected DomainFileError");
+  };
+  assert.match(bad(domainText({ version: "bitgraph-domain/2" })).join(" "), /"version" must be exactly/);
+  assert.match(bad(domainText({ extra: 1 })).join(" "), /unknown field "extra"/);
+  assert.match(bad(domainText(), "other.example").join(" "), /refusing to store one party's file/);
+  assert.match(bad(domainText({ party: "  " })).join(" "), /"party" is required/);
+  assert.match(bad(domainText({ keys: {} })).join(" "), /at least one key/);
+  assert.match(bad(domainText({ keys: { "1234": { alg: "es256", publicKey: ACTOR_KEY_B64 } } })).join(" "), /non-digit/);
+  assert.match(
+    bad(domainText({ keys: { studio: { alg: "es256", publicKey: ACTOR_KEY_B64, note: "x" } } })).join(" "),
+    /unknown field "note"/
+  );
+  assert.match(bad(domainText({ keys: { studio: { alg: "rsa", publicKey: ACTOR_KEY_B64 } } })).join(" "), /"alg" must be/);
+  assert.match(bad(domainText({ keys: { studio: { alg: "es256", publicKey: "!!!" } } })).join(" "), /does not decode/);
+  assert.match(
+    bad(domainText({ keys: { press: { alg: "ed25519", publicKey: Buffer.alloc(16).toString("base64") } } })).join(" "),
+    /does not decode/
+  );
+  assert.match(bad(domainText({ domain: "https://acme.com" })).join(" "), /lowercase hostname/);
+  // Oversize input is refused before parsing.
+  const big = new Uint8Array(70_000);
+  assert.throws(() => parseDomainFile(big), DomainFileError);
+});
+
+test("an es256 fingerprint IS the actor keyId (derived, never assigned)", () => {
+  assert.equal(keyFingerprint({ alg: "es256", publicKey: ACTOR_KEY_B64 }), ACTOR_KEY_ID);
+  const refs = domainKeyRefs(parseDomainFile(domainText()));
+  assert.deepEqual(refs.map((r) => [r.name, r.fingerprint]), [["studio", ACTOR_KEY_ID]]);
+});
+
+test("checkDomain resolves actor keyIds case-insensitively, es256 only", () => {
+  const from = checkDomain(parseDomainFile(domainText()));
+  assert.equal(from.actorKeyName(ACTOR_KEY_ID), "studio");
+  assert.equal(from.actorKeyName(ACTOR_KEY_ID.toUpperCase()), "studio");
+  assert.equal(from.actorKeyName("00".repeat(32)), undefined);
+  // An ed25519 key never actor-matches: actors are P-256.
+  const edPub = generateKeyPairSync("ed25519").publicKey.export({ type: "spki", format: "der" }) as Buffer;
+  const edOnly = parseDomainFile(
+    domainText({ keys: { press: { alg: "ed25519", publicKey: edPub.subarray(edPub.length - 32).toString("base64") } } })
+  );
+  const edFingerprint = keyFingerprint(edOnly.keys["press"] as { alg: "ed25519"; publicKey: string });
+  assert.equal(checkDomain(edOnly).actorKeyName(edFingerprint as string), undefined);
+});
+
+// ---------------------------------------------------------------------------
+// check --from: the domain line
+// ---------------------------------------------------------------------------
+
+test("check --from: the real declared recording reads TRUE under its published key", async () => {
+  const report = await checkIngest(await ingestProof(), { from: checkDomain(parseDomainFile(domainText())) });
+  assert.equal(report.check, "bitgraph-check/2");
+  assert.deepEqual(report.from, { domain: "acme.com", party: "Acme Corp" });
+  const line = domainLineOf(onlyRecording(report));
+  assert.equal(line.result, "TRUE");
+  assert.match(line.detail, /actor key "studio" · published by acme\.com \(Acme Corp\)/);
+  assert.ok(report.notChecked.some((n) => n.includes("pinned")));
+});
+
+test("check --from: a domain that never published the key reads UNDETERMINED, never FALSE", async () => {
+  const otherKey = generateKeyPairSync("ec", { namedCurve: "P-256" })
+    .publicKey.export({ type: "spki", format: "der" }) as Buffer;
+  const from = checkDomain(
+    parseDomainFile(domainText({ keys: { invoices: { alg: "es256", publicKey: otherKey.toString("base64") } } }))
+  );
+  const report = await checkIngest(await ingestProof(), { from });
+  const line = domainLineOf(onlyRecording(report));
+  assert.equal(line.result, "UNDETERMINED");
+  assert.match(line.detail, /is not among the 1 key\(s\) acme\.com publishes/);
+});
+
+test("check --from: a recording that does not verify gets an UNDETERMINED domain line", async () => {
+  const stripped = JSON.parse(proofBytes.toString("utf8")) as Record<string, unknown>;
+  delete stripped["agency"];
+  const report = await checkIngest(await ingestProof(Buffer.from(JSON.stringify(stripped))), {
+    from: checkDomain(parseDomainFile(domainText())),
+  });
+  const recording = onlyRecording(report);
+  assert.equal(recording.lines.find((l) => l.name === "signature")?.result, "FALSE");
+  const line = domainLineOf(recording);
+  assert.equal(line.result, "UNDETERMINED");
+  assert.match(line.detail, /is not verified here/);
+});
+
+test("check --from: a detached bitgraph-sig/1 under a published ed25519 key reads TRUE", async () => {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const spki = publicKey.export({ type: "spki", format: "der" }) as Buffer;
+  const rawB64 = spki.subarray(spki.length - 32).toString("base64");
+  const signature = cryptoSign(null, sigMessage(DIGEST_HEX), privateKey).toString("base64");
+  const sigBytes = Buffer.from(
+    JSON.stringify({
+      sig: "bitgraph-sig/1",
+      over: `sha256:${DIGEST_HEX}`,
+      alg: "ed25519",
+      publicKey: rawB64,
+      signature,
+    })
+  );
+  const from = checkDomain(parseDomainFile(domainText({ keys: { press: { alg: "ed25519", publicKey: rawB64 } } })));
+  const sigEvidence = new Map([[createHash("sha256").update(sigBytes).digest("hex"), new Uint8Array(sigBytes)]]);
+  const report = await checkIngest(await ingestProof(), { from, sigEvidence });
+  const line = domainLineOf(onlyRecording(report));
+  assert.equal(line.result, "TRUE");
+  assert.match(line.detail, /signature by "press" · published by acme\.com/);
+});
+
+test("without --from the report stays bitgraph-check/1 with no from key and no domain line", async () => {
+  const report = await checkIngest(await ingestProof());
+  assert.equal(report.check, "bitgraph-check/1");
+  assert.equal("from" in report, false);
+  assert.equal(onlyRecording(report).lines.some((l) => l.name === "domain"), false);
+});
+
+// ---------------------------------------------------------------------------
+// The pin store
+// ---------------------------------------------------------------------------
+
+test("pin store: write, read, list, forget; malformed pins are refused at read", () => {
+  const dir = mkdtempSync(join(tmpdir(), "bitgraph-pins-"));
+  try {
+    const path = writePin("acme.com", Buffer.from(domainText()), dir);
+    assert.ok(path.endsWith("acme.com"));
+    const pin = readPin("acme.com", dir);
+    assert.equal(pin?.file.party, "Acme Corp");
+    assert.equal(pin?.bytes.toString("utf8"), domainText());
+
+    // A stored file naming a different domain is refused: the store binds
+    // name to statement, so a bad write cannot impersonate.
+    writePin("evil.example", Buffer.from(domainText()), dir);
+    assert.throws(() => readPin("evil.example", dir), DomainFileError);
+
+    writePin("broken.example", Buffer.from("{"), dir);
+    assert.throws(() => readPin("broken.example", dir), DomainFileError);
+
+    const listed = listPins(dir);
+    assert.deepEqual(listed.map((p) => [p.domain, p.malformed]), [
+      ["acme.com", false],
+      ["broken.example", true],
+      ["evil.example", true],
+    ]);
+    assert.equal(listed[0]?.party, "Acme Corp");
+    assert.equal(listed[0]?.keyCount, 1);
+
+    assert.equal(forgetPin("acme.com", dir), true);
+    assert.equal(readPin("acme.com", dir), undefined);
+    assert.equal(forgetPin("acme.com", dir), false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// The fetch (injected; the only networked verb)
+// ---------------------------------------------------------------------------
+
+function fakeFetch(body: string | Buffer, status = 200): { impl: FetchLike; urls: string[] } {
+  const urls: string[] = [];
+  const impl: FetchLike = (url) => {
+    urls.push(url);
+    return Promise.resolve({
+      ok: status >= 200 && status < 300,
+      status,
+      headers: { get: () => null },
+      arrayBuffer: () => {
+        const buf = Buffer.from(body);
+        return Promise.resolve(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+      },
+    });
+  };
+  return { impl, urls };
+}
+
+test("fetchDomainFile: fixed well-known path, verbatim bytes, strict domain binding", async () => {
+  const { impl, urls } = fakeFetch(domainText());
+  const fetched = await fetchDomainFile("acme.com", impl);
+  assert.deepEqual(urls, ["https://acme.com/.well-known/bitgraph"]);
+  assert.equal(fetched.file.party, "Acme Corp");
+  assert.equal(fetched.bytes.toString("utf8"), domainText());
+
+  // The served file names acme.com; pinning it as another.example must
+  // refuse: a redirect cannot repoint the name.
+  await assert.rejects(fetchDomainFile("another.example", fakeFetch(domainText()).impl), DomainFileError);
+  await assert.rejects(fetchDomainFile("acme.com", fakeFetch("nope", 404).impl), /HTTP 404/);
+  await assert.rejects(fetchDomainFile("acme.com", fakeFetch(Buffer.alloc(70_000)).impl), /the cap is/);
+  await assert.rejects(fetchDomainFile("https://acme.com", fakeFetch(domainText()).impl), /bare hostname/);
+});
+
+// ---------------------------------------------------------------------------
+// Re-pin diffs
+// ---------------------------------------------------------------------------
+
+test("diffDomainFiles reports added, removed, changed, and a renamed party", () => {
+  const edPub = generateKeyPairSync("ed25519").publicKey.export({ type: "spki", format: "der" }) as Buffer;
+  const edB64 = edPub.subarray(edPub.length - 32).toString("base64");
+  const before = parseDomainFile(domainText());
+  const after = parseDomainFile(
+    domainText({
+      party: "Acme Corporation",
+      keys: {
+        studio: { alg: "ed25519", publicKey: edB64 },
+        press: { alg: "ed25519", publicKey: edB64 },
+      },
+    })
+  );
+  const diff = diffDomainFiles(before, after);
+  assert.deepEqual(diff.partyChanged, { before: "Acme Corp", after: "Acme Corporation" });
+  assert.deepEqual(diff.added.map((r) => r.name), ["press"]);
+  assert.deepEqual(diff.removed.map((r) => r.name), []);
+  assert.deepEqual(diff.changed.map((c) => c.name), ["studio"]);
+  assert.equal(diff.unchanged, 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;
 }
@@ -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 {
@@ -751,13 +883,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 +949,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(