@mikeargento/bitgraph-player 0.2.1 → 0.4.0

package/src/cli.ts

@@ -4,6 +4,7 @@
 /**
  * bitgraph-play <rule.json> <bundle> [--out <file>] [--summary]
  * bitgraph-play init <file>... [--out <rule.json>]
+ * bitgraph-play check <bundle-or-file>... [--json] [--out <file>]
  *
  * Evaluate: runs a bitgraph-player/1 rule against a proof bundle
  * (directory, .tar, .tar.gz, or .tgz) and writes the verdict JSON to
@@ -15,9 +16,15 @@
  * a placeholder the author must replace — the trust floor has no
  * default, and the scaffolder must not choose it either.
  *
+ * Check: reads a bundle (a directory or archive, or a list of files such
+ * as a proof.json and the file it records) and reports, in the three
+ * values, what the bundle establishes about each recording it holds and
+ * what bounds it. Human text on stdout by default; --json for the
+ * bitgraph-check/1 report. Offline. See check.ts for the vocabulary.
+ *
  * Exit codes: 0 TRUE, 1 FALSE, 2 UNDETERMINED, 3 error (init: 0 or 3).
- * Diagnostics go to stderr; stdout carries the verdict (or skeleton)
- * bytes only.
+ * Diagnostics go to stderr; stdout carries the verdict (or skeleton, or
+ * check report) bytes only.
  *
  * The process exits by setting process.exitCode and returning, never by
  * process.exit(): exiting early would truncate output still draining to
@@ -26,9 +33,12 @@
 
 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 { pipeline } from "node:stream/promises";
-import type { AuditResult } from "@mikeargento/bitgraph-audit";
+import type { AuditResult, BundleEntrySource } from "@mikeargento/bitgraph-audit";
+import { ingestBundle, ingestEntries } from "@mikeargento/bitgraph-audit";
+import { checkIngest, renderCheckText, serializeCheckReport } from "./check.js";
 import { scaffoldRule } from "./init.js";
 import type { ScaffoldEntry } from "./init.js";
 import { play, PlayError } from "./play.js";
@@ -38,8 +48,9 @@ function usage(): number {
   process.stderr.write(
     "usage: bitgraph-play <rule.json> <bundle> [--out <file>] [--summary]\n" +
       "       bitgraph-play init <file>... [--out <rule.json>]\n" +
-      '  "--" ends option parsing; a rule file literally named "init" is\n' +
-      "  evaluated with: bitgraph-play -- init <bundle>\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' +
       "  exit codes: 0 TRUE, 1 FALSE, 2 UNDETERMINED, 3 error\n"
   );
   return 3;
@@ -79,10 +90,11 @@ interface ParsedArgs {
   positional: string[];
   outFile?: string;
   summary: boolean;
+  json: boolean;
 }
 
 function parseArgs(args: string[]): ParsedArgs | undefined {
-  const parsed: ParsedArgs = { positional: [], summary: false };
+  const parsed: ParsedArgs = { positional: [], summary: false, json: false };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i] as string;
     if (arg === "--") {
@@ -95,6 +107,8 @@ function parseArgs(args: string[]): ParsedArgs | undefined {
       parsed.outFile = next;
     } else if (arg === "--summary") {
       parsed.summary = true;
+    } else if (arg === "--json") {
+      parsed.json = true;
     } else if (arg.startsWith("-")) {
       return undefined;
     } else {
@@ -104,8 +118,58 @@ function parseArgs(args: string[]): ParsedArgs | undefined {
   return parsed;
 }
 
-async function runInit(args: ParsedArgs): Promise<number> {
+/**
+ * check: one directory or archive path is ingested as a bundle; any other
+ * argument list (one or more plain files, or several paths) is ingested
+ * in memory as a flat set of entries named by their basenames, so
+ * `bitgraph-play check proof.json photo.jpg` works without a folder.
+ */
+async function runCheck(args: ParsedArgs): Promise<number> {
   if (args.summary) return usage();
+  const targets = args.positional;
+  if (targets.length === 0) return usage();
+
+  let ingest;
+  try {
+    const single = targets.length === 1 ? await stat(targets[0] as string) : undefined;
+    if (single !== undefined && (single.isDirectory() || looksLikeArchive(targets[0] as string))) {
+      ingest = await ingestBundle(targets[0] as string);
+    } else {
+      const entries: BundleEntrySource[] = [];
+      for (const target of targets) {
+        const info = await stat(target);
+        if (info.isDirectory()) {
+          // A directory among several arguments: ingest it as its own
+          // bundle would be ambiguous, so refuse plainly.
+          process.stderr.write(`error: ${target} is a directory; pass one bundle path, or a list of files\n`);
+          return 3;
+        }
+        entries.push({ path: basename(target), open: () => readFile(target).then((b) => new Uint8Array(b)) });
+      }
+      ingest = await ingestEntries(entries);
+    }
+  } catch (err) {
+    process.stderr.write(`error: cannot read bundle: ${(err as Error).message}\n`);
+    return 3;
+  }
+
+  const report = await checkIngest(ingest);
+  const bytes = args.json ? serializeCheckReport(report) : renderCheckText(report);
+  if (args.outFile !== undefined) {
+    writeFileSync(args.outFile, bytes);
+  } else {
+    process.stdout.write(bytes);
+  }
+  return report.result === "TRUE" ? 0 : report.result === "FALSE" ? 1 : 2;
+}
+
+function looksLikeArchive(path: string): boolean {
+  const lower = path.toLowerCase();
+  return lower.endsWith(".tar") || lower.endsWith(".tar.gz") || lower.endsWith(".tgz");
+}
+
+async function runInit(args: ParsedArgs): Promise<number> {
+  if (args.summary || args.json) return usage();
   const files = args.positional;
   if (files.length === 0) return usage();
   if (args.outFile !== undefined && existsSync(args.outFile)) {
@@ -161,7 +225,7 @@ async function runInit(args: ParsedArgs): Promise<number> {
 }
 
 async function runEvaluate(args: ParsedArgs): Promise<number> {
-  if (args.positional.length !== 2) return usage();
+  if (args.json || args.positional.length !== 2) return usage();
   const [rulePath, bundlePath] = args.positional as [string, string];
 
   let result;
@@ -192,22 +256,24 @@ 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" is reachable as `bitgraph-play -- init <bundle>`.
-  const isInit = argv[0] === "init";
-  if (isInit && existsSync("init")) {
+  // "init" or "check" is reachable as `bitgraph-play -- init <bundle>`.
+  const subcommand = argv[0] === "init" || argv[0] === "check" ? 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
     // returned a verdict. Refuse loudly instead.
     process.stderr.write(
-      'error: a file named "init" exists here, so this command is ambiguous.\n' +
-        '  to evaluate it as a rule:  bitgraph-play -- init <bundle>  (or ./init)\n' +
-        "  to scaffold a rule: rename that file or run from another directory\n"
+      `error: a file named "${subcommand}" exists here, so this command is ambiguous.\n` +
+        `  to evaluate it as a rule:  bitgraph-play -- ${subcommand} <bundle>  (or ./${subcommand})\n` +
+        `  to run the ${subcommand} subcommand: rename that file or run from another directory\n`
     );
     return 3;
   }
-  const parsed = parseArgs(isInit ? argv.slice(1) : argv);
+  const parsed = parseArgs(subcommand !== undefined ? argv.slice(1) : argv);
   if (parsed === undefined) return usage();
-  return isInit ? runInit(parsed) : runEvaluate(parsed);
+  if (subcommand === "init") return runInit(parsed);
+  if (subcommand === "check") return runCheck(parsed);
+  return runEvaluate(parsed);
 }
 
 main().then(

package/src/evaluate.ts

@@ -21,9 +21,12 @@
  *   that evidence in either direction.
  */
 
+import type { KeyObject } from "node:crypto";
 import type { AuditResult, ObservedProof } from "@mikeargento/bitgraph-audit";
 import { kleeneAll, kleeneAny, kleeneNot } from "./logic.js";
 import { compare } from "./order.js";
+import { decodeDigestBytes, normalizeDigest } from "./rule.js";
+import { keyObjectFor, parseSigFile, verifySigFile } from "./sig.js";
 import { basisTier, meetsFloor } from "./types.js";
 import type {
   Claim,
@@ -41,12 +44,22 @@ export interface Evaluation {
   weakestEvidence?: EvidenceTier;
 }
 
+/**
+ * Signature evidence for format-2 signedBy claims: candidate file bytes
+ * keyed by lowercase hex SHA-256. Collected by the caller (play() streams
+ * size-capped matched artifacts from the bundle); evaluate() itself stays
+ * a pure function over its arguments.
+ */
+export type SigEvidence = ReadonlyMap<string, Uint8Array>;
+
 interface Ctx {
   rule: Rule;
   resolutions: Map<string, Resolution>;
   audit: AuditResult;
   steps: DerivedStep[];
   usedTiers: Set<EvidenceTier>;
+  sigEvidence: SigEvidence;
+  keyObjects: Map<string, KeyObject | undefined>;
 }
 
 function positionOf(proof: ObservedProof): Record<string, unknown> {
@@ -198,8 +211,91 @@ function evalPrecedes(ctx: Ctx, claim: string, x: string, y: string): ThreeValue
   });
 }
 
+/**
+ * signedBy(role, keyName): TRUE when a valid bitgraph-sig/1 by the named
+ * trusted key over the role's digest is present in the supplied evidence;
+ * UNDETERMINED otherwise, NEVER FALSE. Absence of a signature from a
+ * bundle proves nothing about the world, and `not(signedBy(...))` is
+ * therefore permanently UNDETERMINED by the Kleene table.
+ *
+ * The claim is about BITS, not occurrences: it evaluates against the
+ * declared role digest whether or not the role resolved to a recording.
+ * Only an undeclared role is UNDETERMINED for want of a digest.
+ */
+function evalSignedBy(ctx: Ctx, role: string, keyName: string): ThreeValued {
+  const claim = `signedBy(${role}, ${keyName})`;
+  const entry = ctx.rule.cast[role];
+  if (entry === undefined) {
+    return record(ctx, {
+      claim,
+      result: "UNDETERMINED",
+      because: { reason: `role "${role}" is not declared in the cast` },
+    });
+  }
+  // parseRule guarantees the key name resolves; guard for direct API use.
+  const key = ctx.rule.trustedKeys?.[keyName];
+  if (key === undefined) {
+    return record(ctx, {
+      claim,
+      result: "UNDETERMINED",
+      because: { reason: `trusted key "${keyName}" is not declared` },
+    });
+  }
+  if (!ctx.keyObjects.has(keyName)) ctx.keyObjects.set(keyName, keyObjectFor(key));
+  const keyObject = ctx.keyObjects.get(keyName);
+  if (keyObject === undefined) {
+    return record(ctx, {
+      claim,
+      result: "UNDETERMINED",
+      because: {
+        reason: `trusted key "${keyName}" is not decodable as ${key.alg} key material; no signature can verify against it`,
+      },
+    });
+  }
+
+  const digestB64 = normalizeDigest(entry.digest) as string;
+  const targetHex = (decodeDigestBytes(digestB64) as Buffer).toString("hex");
+
+  // Deterministic scan: candidates in ascending content-hash order.
+  const candidates = [...ctx.sigEvidence.keys()].sort();
+  let parsedCount = 0;
+  for (const sha256Hex of candidates) {
+    const bytes = ctx.sigEvidence.get(sha256Hex) as Uint8Array;
+    const sig = parseSigFile(bytes);
+    if (sig === undefined) continue;
+    parsedCount += 1;
+    if (verifySigFile(sig, key, keyObject, targetHex, decodeDigestBytes)) {
+      return record(ctx, {
+        claim,
+        result: "TRUE",
+        because: {
+          signatureSha256Hex: sha256Hex,
+          alg: key.alg,
+          keyName,
+          over: `sha256:${targetHex}`,
+          note: "signature math verified here; that this key belongs to the named party is declared, never derived",
+        },
+      });
+    }
+  }
+  return record(ctx, {
+    claim,
+    result: "UNDETERMINED",
+    because: {
+      reason:
+        `no valid bitgraph-sig/1 by trusted key "${keyName}" over the role digest is present in the ` +
+        `supplied evidence (${ctx.sigEvidence.size} candidate file(s), ${parsedCount} parsed as signatures); ` +
+        `absence of a signature from a bundle proves nothing`,
+    },
+  });
+}
+
 function evalClaim(ctx: Ctx, claim: Claim): ThreeValued {
   if ("exists" in claim) return evalExists(ctx, claim.exists);
+  if ("signedBy" in claim) {
+    const [role, keyName] = claim.signedBy;
+    return evalSignedBy(ctx, role, keyName);
+  }
   if ("before" in claim) {
     const [x, y] = claim.before;
     return evalPrecedes(ctx, `before(${x}, ${y})`, x, y);
@@ -224,9 +320,18 @@ function evalClaim(ctx: Ctx, claim: Claim): ThreeValued {
 export function evaluate(
   rule: Rule,
   resolutions: Map<string, Resolution>,
-  audit: AuditResult
+  audit: AuditResult,
+  sigEvidence: SigEvidence = new Map()
 ): Evaluation {
-  const ctx: Ctx = { rule, resolutions, audit, steps: [], usedTiers: new Set() };
+  const ctx: Ctx = {
+    rule,
+    resolutions,
+    audit,
+    steps: [],
+    usedTiers: new Set(),
+    sigEvidence,
+    keyObjects: new Map(),
+  };
   const result = evalClaim(ctx, rule.claim);
   const evaluation: Evaluation = { result, steps: ctx.steps };
   if (ctx.usedTiers.has("assumption-dependent")) {

package/src/index.ts

@@ -24,14 +24,18 @@ export type {
   OrderResult,
   Resolution,
   Rule,
+  RuleFormat,
   ThreeValued,
   Verdict,
 } from "./types.js";
 export { basisTier, meetsFloor } from "./types.js";
 
-export { parseRule, normalizeDigest, RuleError } from "./rule.js";
-export { play, playAudit, PlayError } from "./play.js";
+export { parseRule, normalizeDigest, decodeDigestBytes, RuleError } from "./rule.js";
+export { play, playAudit, claimUsesSignatures, SIG_EVIDENCE_MAX_BYTES, PlayError } from "./play.js";
 export type { PlayResult, PlayStage } from "./play.js";
+export { parseSigFile, verifySigFile, keyObjectFor, sigMessage } from "./sig.js";
+export type { SigAlg, SigFile, TrustedKey } from "./sig.js";
+export type { SigEvidence } from "./evaluate.js";
 export { scaffoldRule, roleNameForFile, ORDERING_PLACEHOLDER } from "./init.js";
 export type { ScaffoldEntry } from "./init.js";
 export { resolveCast, resolveRole } from "./cast.js";
@@ -40,3 +44,6 @@ export { kleeneAll, kleeneAny, kleeneNot } from "./logic.js";
 export { evaluate } from "./evaluate.js";
 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";

package/src/play.ts

@@ -16,12 +16,13 @@
 
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { runAudit } from "@mikeargento/bitgraph-audit";
+import { runAudit, streamMatchedArtifacts } from "@mikeargento/bitgraph-audit";
 import type { AuditResult } from "@mikeargento/bitgraph-audit";
 import { resolveCast } from "./cast.js";
 import { evaluate } from "./evaluate.js";
+import type { SigEvidence } from "./evaluate.js";
 import { parseRule } from "./rule.js";
-import type { Rule, Verdict } from "./types.js";
+import type { Claim, Rule, Verdict } from "./types.js";
 import { buildVerdict, serializeVerdict } from "./verdict.js";
 
 export type PlayStage = "rule-read" | "audit";
@@ -45,10 +46,32 @@ export interface PlayResult {
   audit: AuditResult;
 }
 
+/** True when the claim tree contains a signedBy claim anywhere. */
+export function claimUsesSignatures(claim: Claim): boolean {
+  if ("signedBy" in claim) return true;
+  if ("all" in claim) return claim.all.some(claimUsesSignatures);
+  if ("any" in claim) return claim.any.some(claimUsesSignatures);
+  if ("not" in claim) return claimUsesSignatures(claim.not);
+  return false;
+}
+
+/**
+ * Ceiling on candidate signature-file bytes retained for signedBy
+ * evaluation. Signature files are a few hundred bytes; the cap only
+ * exists so a bundle full of large artifacts never inflates memory.
+ * A file above the cap is simply not signature evidence.
+ */
+export const SIG_EVIDENCE_MAX_BYTES = 1_048_576;
+
 /** The pure tail of the pipeline: no filesystem, no network. */
-export function playAudit(rule: Rule, ruleSha256Hex: string, audit: AuditResult): PlayResult {
+export function playAudit(
+  rule: Rule,
+  ruleSha256Hex: string,
+  audit: AuditResult,
+  sigEvidence: SigEvidence = new Map()
+): PlayResult {
   const resolutions = resolveCast(rule.cast, audit);
-  const evaluation = evaluate(rule, resolutions, audit);
+  const evaluation = evaluate(rule, resolutions, audit, sigEvidence);
   const verdict = buildVerdict(rule, ruleSha256Hex, resolutions, evaluation, audit);
   const exitCode = evaluation.result === "TRUE" ? 0 : evaluation.result === "FALSE" ? 1 : 2;
   return { verdict, bytes: serializeVerdict(verdict), exitCode, audit };
@@ -74,5 +97,20 @@ export async function play(rulePath: string, bundlePath: string): Promise<PlayRe
   } catch (err) {
     throw new PlayError("audit", `bundle audit failed: ${(err as Error).message}`, err);
   }
-  return playAudit(rule, ruleSha256Hex, audit);
+
+  // Format 2 with signature claims: candidate evidence is every RECORDED
+  // artifact in the bundle (matched to a proof), size-capped. A signature
+  // that was never recorded can still be supplied to playAudit directly
+  // by an embedder; the reference CLI evaluates recorded evidence, which
+  // is what a Titles thread produces by construction.
+  let sigEvidence: SigEvidence | undefined;
+  if (rule.rule === "bitgraph-player/2" && claimUsesSignatures(rule.claim)) {
+    const collected = new Map<string, Uint8Array>();
+    for await (const matched of streamMatchedArtifacts(audit.ingest)) {
+      if (matched.bytes.length > SIG_EVIDENCE_MAX_BYTES) continue;
+      if (!collected.has(matched.sha256Hex)) collected.set(matched.sha256Hex, matched.bytes);
+    }
+    sigEvidence = collected;
+  }
+  return playAudit(rule, ruleSha256Hex, audit, sigEvidence);
 }

package/src/rule.ts

@@ -14,7 +14,8 @@
  * was undeclared.
  */
 
-import type { CastEntry, CastPin, Claim, EvidenceTier, Rule } from "./types.js";
+import type { TrustedKey } from "./sig.js";
+import type { CastEntry, CastPin, Claim, EvidenceTier, Rule, RuleFormat } from "./types.js";
 
 export class RuleError extends Error {
   readonly issues: readonly string[];
@@ -171,7 +172,13 @@ function parseCastEntry(role: string, v: unknown, issues: string[]): CastEntry |
   return entry;
 }
 
-function parseClaim(v: unknown, where: string, issues: string[], depth: number): Claim | undefined {
+function parseClaim(
+  v: unknown,
+  where: string,
+  issues: string[],
+  depth: number,
+  format: RuleFormat
+): Claim | undefined {
   if (depth > 32) {
     issues.push(`${where}: claim nesting exceeds the maximum depth of 32`);
     return undefined;
@@ -220,7 +227,7 @@ function parseClaim(v: unknown, where: string, issues: string[], depth: number):
       const parsed: Claim[] = [];
       let ok = true;
       body.forEach((child, i) => {
-        const c = parseClaim(child, `${where}.${op}[${i}]`, issues, depth + 1);
+        const c = parseClaim(child, `${where}.${op}[${i}]`, issues, depth + 1, format);
         if (c === undefined) ok = false;
         else parsed.push(c);
       });
@@ -228,10 +235,21 @@ function parseClaim(v: unknown, where: string, issues: string[], depth: number):
       return op === "all" ? { all: parsed } : { any: parsed };
     }
     case "not": {
-      const inner = parseClaim(body, `${where}.not`, issues, depth + 1);
+      const inner = parseClaim(body, `${where}.not`, issues, depth + 1, format);
       if (inner === undefined) return undefined;
       return { not: inner };
     }
+    case "signedBy": {
+      if (format !== "bitgraph-player/2") {
+        issues.push(`${where}.signedBy: requires rule format "bitgraph-player/2"`);
+        return undefined;
+      }
+      if (!Array.isArray(body) || body.length !== 2 || body.some((r) => typeof r !== "string")) {
+        issues.push(`${where}.signedBy: must be [roleName, trustedKeyName]`);
+        return undefined;
+      }
+      return { signedBy: body as [string, string] };
+    }
     default:
       issues.push(`${where}: unknown operator "${op}"`);
       return undefined;
@@ -252,10 +270,18 @@ export function parseRule(jsonText: string): Rule {
   const issues: string[] = [];
   if (!isPlainObject(raw)) throw new RuleError(["rule file must be a JSON object"]);
 
-  rejectUnknownKeys(raw, ["rule", "id", "cast", "world", "requires", "claim", "then"], "rule", issues);
+  rejectUnknownKeys(
+    raw,
+    ["rule", "id", "cast", "world", "requires", "trustedKeys", "claim", "then"],
+    "rule",
+    issues
+  );
 
-  if (raw["rule"] !== "bitgraph-player/1") {
-    issues.push(`"rule" must be exactly "bitgraph-player/1"`);
+  let format: RuleFormat = "bitgraph-player/1";
+  if (raw["rule"] === "bitgraph-player/1" || raw["rule"] === "bitgraph-player/2") {
+    format = raw["rule"];
+  } else {
+    issues.push(`"rule" must be "bitgraph-player/1" or "bitgraph-player/2"`);
   }
   if (typeof raw["id"] !== "string" || raw["id"].length === 0) {
     issues.push(`"id" is required and must be a non-empty string`);
@@ -302,11 +328,68 @@ export function parseRule(jsonText: string): Rule {
     }
   }
 
+  // trustedKeys: format 2 only. The name-to-key binding is declared, so
+  // parsing only enforces well-formedness, never meaning.
+  let trustedKeys: Record<string, TrustedKey> | undefined;
+  if ("trustedKeys" in raw) {
+    if (format !== "bitgraph-player/2") {
+      issues.push(`"trustedKeys" requires rule format "bitgraph-player/2"`);
+    } else if (!isPlainObject(raw["trustedKeys"]) || Object.keys(raw["trustedKeys"]).length === 0) {
+      issues.push(`"trustedKeys" must be an object naming at least one key`);
+    } else {
+      trustedKeys = Object.create(null) as Record<string, TrustedKey>;
+      for (const [name, entry] of Object.entries(raw["trustedKeys"])) {
+        const where = `trustedKeys.${name}`;
+        if (!/^[A-Za-z0-9_.-]+$/.test(name) || /^[0-9]+$/.test(name)) {
+          issues.push(
+            `trustedKeys: key name "${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;
+        }
+        rejectUnknownKeys(entry, ["alg", "publicKey"], where, issues);
+        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;
+        }
+        trustedKeys[name] = { alg, publicKey };
+      }
+    }
+  }
+
   let claim: Claim | undefined;
   if (!("claim" in raw)) {
     issues.push(`"claim" is required`);
   } else {
-    claim = parseClaim(raw["claim"], "claim", issues, 0);
+    claim = parseClaim(raw["claim"], "claim", issues, 0, format);
+  }
+
+  // Every signedBy claim must reference a declared trusted key: the
+  // reference is statically checkable, and an unresolvable key name is a
+  // rule the author believes is being enforced and is not.
+  if (claim !== undefined) {
+    const referenced: string[] = [];
+    const walk = (c: Claim): void => {
+      if ("signedBy" in c) referenced.push(c.signedBy[1]);
+      else if ("all" in c) c.all.forEach(walk);
+      else if ("any" in c) c.any.forEach(walk);
+      else if ("not" in c) walk(c.not);
+    };
+    walk(claim);
+    for (const name of referenced) {
+      if (trustedKeys === undefined || !(name in trustedKeys)) {
+        issues.push(`claim: signedBy references trusted key "${name}" which trustedKeys does not declare`);
+      }
+    }
   }
 
   let then: { label: string } | undefined;
@@ -328,13 +411,14 @@ export function parseRule(jsonText: string): Rule {
   if (issues.length > 0) throw new RuleError(issues);
 
   const rule: Rule = {
-    rule: "bitgraph-player/1",
+    rule: format,
     id: raw["id"] as string,
     cast,
     world: "closed",
     requires: { ordering: ordering as EvidenceTier },
     claim: claim as Claim,
   };
+  if (trustedKeys !== undefined) rule.trustedKeys = trustedKeys;
   if (then !== undefined) rule.then = then;
   return rule;
 }