@mikeargento/bitgraph-player 0.2.0 → 0.3.0

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

package/src/sig.ts

@@ -0,0 +1,170 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * bitgraph-sig/1: detached signature evidence over a digest.
+ *
+ * A signature file states that a key signed a domain-separated message
+ * derived from an artifact digest. Verification here is pure math over
+ * supplied bytes: no filesystem, no network, no clock. What a valid
+ * signature MEANS (that the key belongs to a named party) is never
+ * derived; the rule's trustedKeys block is a DECLARED binding and the
+ * verdict says so.
+ *
+ * The signed message is:
+ *
+ *     "bitgraph-sig/1\n" + lowercase hex SHA-256 of the target bytes
+ *
+ * as UTF-8. Domain separation keeps a signature made in any other
+ * protocol from being replayed as a bitgraph-sig, and signing the digest
+ * spelling (not the raw 32 bytes) keeps the message printable and
+ * auditable by eye.
+ *
+ * Algorithms:
+ *   "ed25519"  publicKey is the raw 32-byte key, standard base64 — the
+ *              same spelling bitgraph/1 proofs use for signer keys.
+ *              signature is the raw 64-byte Ed25519 signature, base64.
+ *   "es256"    ECDSA P-256 over SHA-256. publicKey is SPKI DER, base64
+ *              (the export format of every platform keystore, including
+ *              Secure Enclave keys surfaced through WebCrypto).
+ *              signature is DER-encoded ECDSA, base64.
+ *
+ * A signature claim can be TRUE or UNDETERMINED, never FALSE: "this key
+ * never signed these bytes" is a negative over an open world no bundle
+ * can close. A malformed or non-verifying signature file is not evidence
+ * of anything.
+ */
+
+import { createPublicKey, verify as cryptoVerify } from "node:crypto";
+import type { KeyObject } from "node:crypto";
+
+export type SigAlg = "ed25519" | "es256";
+
+export interface TrustedKey {
+  alg: SigAlg;
+  /** ed25519: raw 32-byte key, standard base64. es256: SPKI DER, base64. */
+  publicKey: string;
+}
+
+/** A parsed, well-formed bitgraph-sig/1 object (not yet verified). */
+export interface SigFile {
+  sig: "bitgraph-sig/1";
+  /** Digest of the target bytes, in any accepted canonical spelling. */
+  over: string;
+  alg: SigAlg;
+  publicKey: string;
+  signature: string;
+}
+
+/** SPKI DER prefix for a raw Ed25519 public key (RFC 8410). */
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+/** The domain-separated message a bitgraph-sig/1 signature covers. */
+export function sigMessage(targetSha256Hex: string): Buffer {
+  return Buffer.from(`bitgraph-sig/1\n${targetSha256Hex.toLowerCase()}`, "utf8");
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Parse candidate bytes as a bitgraph-sig/1 file. Returns undefined for
+ * anything malformed: a broken signature file is noise, never evidence,
+ * and never an error that stops evaluation.
+ */
+export function parseSigFile(bytes: Uint8Array): SigFile | undefined {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(Buffer.from(bytes).toString("utf8"));
+  } catch {
+    return undefined;
+  }
+  if (!isPlainObject(raw)) return undefined;
+  if (raw["sig"] !== "bitgraph-sig/1") return undefined;
+  const over = raw["over"];
+  const alg = raw["alg"];
+  const publicKey = raw["publicKey"];
+  const signature = raw["signature"];
+  if (typeof over !== "string" || over.length === 0) return undefined;
+  if (alg !== "ed25519" && alg !== "es256") return undefined;
+  if (typeof publicKey !== "string" || publicKey.length === 0) return undefined;
+  if (typeof signature !== "string" || signature.length === 0) return undefined;
+  return { sig: "bitgraph-sig/1", over, alg, publicKey, signature };
+}
+
+/** Strict base64 decode: the spelling must round-trip byte-exactly. */
+function decodeB64Strict(s: string): Buffer | undefined {
+  if (!/^[A-Za-z0-9+/]+=*$/.test(s)) return undefined;
+  const bytes = Buffer.from(s, "base64");
+  return bytes.toString("base64") === s ? bytes : undefined;
+}
+
+/**
+ * Build a KeyObject for a trusted key. Returns undefined when the key
+ * material is malformed — a rule declaring an undecodable key can never
+ * make a signedBy claim TRUE, and the verdict's reason says why.
+ */
+export function keyObjectFor(key: TrustedKey): KeyObject | undefined {
+  const material = decodeB64Strict(key.publicKey);
+  if (material === undefined) return undefined;
+  try {
+    if (key.alg === "ed25519") {
+      if (material.length !== 32) return undefined;
+      return createPublicKey({
+        key: Buffer.concat([ED25519_SPKI_PREFIX, material]),
+        format: "der",
+        type: "spki",
+      });
+    }
+    const keyObject = createPublicKey({ key: material, format: "der", type: "spki" });
+    // es256 means ECDSA over P-256 specifically. SPKI decodes many key
+    // types; anything that is not an EC key on prime256v1 is not es256
+    // key material, and verification against it must never proceed.
+    if (
+      keyObject.asymmetricKeyType !== "ec" ||
+      keyObject.asymmetricKeyDetails?.namedCurve !== "prime256v1"
+    ) {
+      return undefined;
+    }
+    return keyObject;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Verify one parsed signature file against a trusted key and a target
+ * digest (lowercase hex). TRUE means: the file's `over` names exactly
+ * these bytes, its key material equals the trusted key, and the
+ * signature verifies over the domain-separated message.
+ */
+export function verifySigFile(
+  sig: SigFile,
+  key: TrustedKey,
+  keyObject: KeyObject,
+  targetSha256Hex: string,
+  decodeDigestBytes: (s: string) => Buffer | undefined
+): boolean {
+  if (sig.alg !== key.alg) return false;
+  if (sig.publicKey !== key.publicKey) return false;
+  // `over` accepts the same spellings as rule digests, including the
+  // "sha256:" prefix, which the byte-level decoder does not strip itself.
+  let over = sig.over.trim();
+  if (over.toLowerCase().startsWith("sha256:")) over = over.slice("sha256:".length);
+  const overBytes = decodeDigestBytes(over);
+  const targetBytes = decodeDigestBytes(targetSha256Hex);
+  if (overBytes === undefined || targetBytes === undefined) return false;
+  if (!overBytes.equals(targetBytes)) return false;
+  const signature = decodeB64Strict(sig.signature);
+  if (signature === undefined) return false;
+  if (sig.alg === "ed25519" && signature.length !== 64) return false;
+  const message = sigMessage(targetSha256Hex);
+  try {
+    if (sig.alg === "ed25519") {
+      return cryptoVerify(null, message, keyObject, signature);
+    }
+    return cryptoVerify("sha256", message, keyObject, signature);
+  } catch {
+    return false;
+  }
+}

package/src/types.ts

@@ -133,10 +133,19 @@ export type Claim =
   | { between: [string, string, string] }
   | { all: Claim[] }
   | { any: Claim[] }
-  | { not: Claim };
+  | { not: Claim }
+  /**
+   * Format 2 only: a valid bitgraph-sig/1 by the named trusted key over
+   * the role's digest is present in the supplied evidence. TRUE or
+   * UNDETERMINED, never FALSE — "this key never signed these bytes" is a
+   * negative over an open world no bundle can close.
+   */
+  | { signedBy: [string, string] };
+
+export type RuleFormat = "bitgraph-player/1" | "bitgraph-player/2";
 
 export interface Rule {
-  rule: "bitgraph-player/1";
+  rule: RuleFormat;
   id: string;
   cast: Record<string, CastEntry>;
   /** The only defined value. Absence is only ever asserted within the declared cast. */
@@ -146,6 +155,13 @@ export interface Rule {
    * the rule carries its own security policy.
    */
   requires: { ordering: EvidenceTier };
+  /**
+   * Format 2 only. Named keys the rule author trusts. The name-to-key
+   * binding is DECLARED — surfaced in the verdict, never derived. What
+   * becomes derived under format 2 is only the math: a signature by the
+   * named key material verifies over the role's digest.
+   */
+  trustedKeys?: Record<string, import("./sig.js").TrustedKey>;
   claim: Claim;
   /**
    * A label and nothing else. No field in this format is capable of
@@ -192,14 +208,15 @@ export interface DerivedStep {
 
 /** One assertion Player took on somebody's word. */
 export interface DeclaredEntry {
-  assertion: "signedBy" | "means" | "closed-world" | "pinned-occurrence";
+  assertion: "signedBy" | "means" | "closed-world" | "pinned-occurrence" | "trusted-key";
   role?: string;
   verifiedHere: false;
   [k: string]: unknown;
 }
 
 export interface Verdict {
-  verdict: "bitgraph-player-verdict/1";
+  /** Tracks the rule format: a /1 rule yields a /1 verdict, byte-identical to prior releases. */
+  verdict: "bitgraph-player-verdict/1" | "bitgraph-player-verdict/2";
   result: ThreeValued;
   rule: { id: string; sha256: string };
   then?: { label: string };

package/src/verdict.ts

@@ -31,7 +31,7 @@ import type { DeclaredEntry, Resolution, Rule, Verdict } from "./types.js";
  * A unit test asserts this equals package.json's version, so the
  * constant cannot drift silently across releases.
  */
-export const PLAYER_VERSION = "0.2.0";
+export const PLAYER_VERSION = "0.3.0";
 
 /** The player package's own version. */
 export function playerVersion(): string {
@@ -110,6 +110,21 @@ export function buildVerdict(
       });
     }
   }
+  // Format 2: the name-to-key bindings are declared trust. The signature
+  // MATH is derived (it appears in `derived` steps); that key K IS the
+  // named party is taken on the rule author's word, exactly like a cast
+  // digest's meaning.
+  if (rule.trustedKeys !== undefined) {
+    for (const [keyName, key] of Object.entries(rule.trustedKeys)) {
+      declared.push({
+        assertion: "trusted-key",
+        verifiedHere: false,
+        keyName,
+        alg: key.alg,
+        publicKey: key.publicKey,
+      });
+    }
+  }
   declared.push({
     assertion: "closed-world",
     verifiedHere: false,
@@ -120,7 +135,8 @@ export function buildVerdict(
   });
 
   const verdict: Verdict = {
-    verdict: "bitgraph-player-verdict/1",
+    verdict:
+      rule.rule === "bitgraph-player/2" ? "bitgraph-player-verdict/2" : "bitgraph-player-verdict/1",
     result: evaluation.result,
     rule: { id: rule.id, sha256: ruleSha256Hex },
     cast,