@askalf/truecopy 0.0.1 → 0.7.0

package/src/keychain.mjs

@@ -0,0 +1,75 @@
+// OS-keychain storage for canon's PRIVATE signing key — held by the operating
+// system, tied to your login, never written as plaintext. Zero deps: each
+// platform's native CLI/API.
+//   macOS   → Keychain        (security)
+//   Linux   → Secret Service  (secret-tool / libsecret)
+//   Windows → DPAPI user-scope (PowerShell; an encrypted blob only this user can read)
+// The PUBLIC key + keyId stay in ~/.canon/signing-key.json (public is not secret).
+// CANON_KEYCHAIN_FAKE=<file> is a TEST seam (a plain JSON file standing in for the
+// keychain); CANON_NO_KEYCHAIN forces the plaintext-file fallback.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const SERVICE = 'canon', ACCOUNT = 'signing-key';
+const home = () => path.join(process.env.CANON_HOME || os.homedir(), '.canon');
+const blobFile = () => path.join(home(), 'signing-key.dpapi');
+const run = (cmd, args, input) => execFileSync(cmd, args, { input, stdio: ['pipe', 'pipe', 'ignore'], encoding: 'utf8' });
+const fake = () => process.env.CANON_KEYCHAIN_FAKE;
+
+export function keychainAvailable() {
+  if (process.env.CANON_NO_KEYCHAIN) return false;      // explicit opt-out / test seam
+  if (fake()) return true;
+  if (process.platform === 'darwin' || process.platform === 'win32') return true; // security / DPAPI are built in
+  if (process.platform === 'linux') { try { run('secret-tool', ['--version']); return true; } catch { return false; } }
+  return false;
+}
+
+/** Read the stored value (string), or null if none. */
+export function keychainGet() {
+  if (fake()) { try { return JSON.parse(fs.readFileSync(fake(), 'utf8')).value || null; } catch { return null; } }
+  try {
+    if (process.platform === 'darwin') return run('security', ['find-generic-password', '-a', ACCOUNT, '-s', SERVICE, '-w']).trim() || null;
+    if (process.platform === 'linux') return run('secret-tool', ['lookup', 'service', SERVICE, 'account', ACCOUNT]).trim() || null;
+    if (process.platform === 'win32') {
+      const blob = blobFile();
+      if (!fs.existsSync(blob)) return null;
+      const enc = fs.readFileSync(blob, 'utf8').trim();
+      const ps = `Add-Type -AssemblyName System.Security; $b=[Convert]::FromBase64String('${enc}'); $p=[Security.Cryptography.ProtectedData]::Unprotect($b,$null,'CurrentUser'); [Console]::Out.Write([Text.Encoding]::UTF8.GetString($p))`;
+      return run('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps]).trim() || null;
+    }
+  } catch { return null; }
+  return null;
+}
+
+/** Store the value (string) in the OS keychain. On Linux (secret-tool) and Windows
+ *  (PowerShell DPAPI) the value goes via stdin, so it never appears in a process
+ *  listing. macOS `security` has NO stdin password input (its -w prompt reads /dev/tty,
+ *  not stdin), so there the value is passed as an argument — briefly visible in `ps` for
+ *  the command's duration. A CLI limitation; closing it fully needs the native Security
+ *  framework (a non-CLI follow-up). */
+export function keychainSet(value) {
+  if (fake()) { fs.mkdirSync(path.dirname(fake()), { recursive: true }); fs.writeFileSync(fake(), JSON.stringify({ value }), { mode: 0o600 }); return; }
+  // macOS: `security` can't take the password on stdin (see note above), so it goes as an
+  // argument and is briefly visible in `ps`. Accepted CLI limitation — do NOT "fix" this
+  // with `-w` and no inline value: that reads /dev/tty, not stdin, and silently stores the
+  // wrong secret (caught by the macOS CI added in this change).
+  if (process.platform === 'darwin') { run('security', ['add-generic-password', '-a', ACCOUNT, '-s', SERVICE, '-w', value, '-U']); return; }
+  if (process.platform === 'linux') { run('secret-tool', ['store', '--label=canon signing key', 'service', SERVICE, 'account', ACCOUNT], value); return; }
+  if (process.platform === 'win32') {
+    const ps = `Add-Type -AssemblyName System.Security; $p=[Text.Encoding]::UTF8.GetBytes([Console]::In.ReadToEnd()); $b=[Security.Cryptography.ProtectedData]::Protect($p,$null,'CurrentUser'); [Console]::Out.Write([Convert]::ToBase64String($b))`;
+    const enc = run('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps], value).trim();
+    fs.mkdirSync(home(), { recursive: true });
+    fs.writeFileSync(blobFile(), enc, { mode: 0o600 });
+    return;
+  }
+  throw new Error('canon: no OS keychain available on this platform');
+}
+
+export const keychainKind = () =>
+  fake() ? 'test-fake'
+    : process.platform === 'darwin' ? 'macOS Keychain'
+      : process.platform === 'win32' ? 'Windows DPAPI (user scope)'
+        : process.platform === 'linux' ? 'Secret Service (libsecret)'
+          : 'unknown';

package/src/lock.mjs

@@ -0,0 +1,44 @@
+// canon.lock — the pinned, vetted set. One entry per trusted skill: where it came
+// from, the content hash you trusted, the scan verdict at pin time, and (optional)
+// a signature. `verify` re-derives the hash and flags any drift from this file.
+import fs from 'node:fs';
+
+export const DEFAULT_LOCK = 'canon.lock';
+
+// `skills` is ALWAYS a NULL-PROTOTYPE map, on every readLock path — so a skill
+// keyed by a prototype member ("__proto__", "toString", "constructor", …) can't
+// hijack `[[Set]]`/`[[Get]]`. On a plain object `lock.skills["__proto__"] = entry`
+// invokes the __proto__ setter (the entry is silently dropped — pin reports
+// success but writes nothing), and `"toString" in lock.skills` is always true
+// (unpin "removes" a phantom, and on a fresh lock even CREATES the file). A
+// null-proto map makes every key an ordinary own property. Also guards the
+// corrupt/hostile `skills: null | array | string` shape (would crash
+// Object.entries / index assignment).
+const asSkills = (s) =>
+  Object.assign(Object.create(null), s && typeof s === 'object' && !Array.isArray(s) ? s : {});
+const emptyLock = () => ({ version: 1, skills: asSkills(null) });
+
+// A MISSING lock and a CORRUPT lock are different: an absent lock with
+// mustExist=false is a legitimately empty trust set; a present-but-unparseable
+// lock (truncated, merge-conflict markers, non-object) must fail CLOSED — never
+// silently degrade to "nothing pinned, all clear".
+export function readLock(p = DEFAULT_LOCK, { mustExist = false } = {}) {
+  let raw;
+  try { raw = fs.readFileSync(p, 'utf8'); }
+  catch (e) {
+    if (e && e.code === 'ENOENT') {
+      if (mustExist) { const err = new Error(`no canon.lock at ${p}`); err.code = 'ELOCKMISSING'; throw err; }
+      return emptyLock();
+    }
+    throw e;
+  }
+  let l;
+  try { l = JSON.parse(raw); }
+  catch (e) { const err = new Error(`canon.lock at ${p} is present but unparseable: ${e.message}`); err.code = 'ELOCKCORRUPT'; throw err; }
+  if (!l || typeof l !== 'object' || Array.isArray(l)) { const err = new Error(`canon.lock at ${p} is not a lock object`); err.code = 'ELOCKCORRUPT'; throw err; }
+  return { version: 1, ...l, skills: asSkills(l.skills) };
+}
+
+export function writeLock(lock, p = DEFAULT_LOCK) {
+  fs.writeFileSync(p, JSON.stringify(lock, null, 2) + '\n');
+}

package/src/mcp-cli.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// canon-mcp — enforce canon.lock on a live MCP server. Point your MCP client at
+//   canon-mcp [--lock canon.lock] [--name <pinned>] [--strict] -- <server cmd...>
+// Only vetted, unmodified, unpoisoned tools reach the client.
+import { runGate } from './mcp.mjs';
+
+const argv = process.argv.slice(2);
+const sep = argv.indexOf('--');
+const pre = sep >= 0 ? argv.slice(0, sep) : argv;
+const cmd = sep >= 0 ? argv.slice(sep + 1) : [];
+const opt = (n, d) => {
+  const i = pre.indexOf(n);
+  if (i >= 0) { const nx = pre[i + 1]; return nx !== undefined && !nx.startsWith('--') ? nx : true; } // `--n value` or bare `--n`
+  const eq = pre.find((x) => x.startsWith(n + '='));
+  return eq ? eq.slice(n.length + 1) : d;
+};
+
+if (!cmd.length || pre.includes('-h') || pre.includes('--help')) {
+  process.stderr.write('usage: canon-mcp [--lock canon.lock] [--name <pinned>] [--strict] -- <mcp-server cmd...>\n');
+  process.exit(cmd.length ? 0 : 2);
+}
+runGate({ command: cmd[0], args: cmd.slice(1), lockPath: opt('--lock', 'canon.lock'), name: opt('--name', null) || null, strict: !!opt('--strict', false) });

package/src/mcp.mjs

@@ -0,0 +1,102 @@
+// canon-mcp — a stdio MCP proxy that ENFORCES canon.lock at runtime. It sits
+// between an MCP client and a downstream MCP server, filters `tools/list` down to
+// the vetted set, and blocks `tools/call` to anything it dropped. Un-vetted,
+// drifted, or poisoned tools never reach the agent. JSON-RPC over newline stdio.
+//
+// Where warden-mcp firewalls what a tool DOES, canon-mcp gates what tools EXIST.
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+import { gateTools, toolHash } from './gate.mjs';
+import { readLock } from './lock.mjs';
+
+const blockReply = (id, name) =>
+  JSON.stringify({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: `⛔ canon blocked an un-vetted / drifted tool: ${name}` }], isError: true } });
+
+const batchError = (msg) => {
+  // JSON-RPC batching was removed from MCP (2025-06-18) and would let a tools/call
+  // to a dropped tool ride past the single-message gate — so reject a client batch
+  // rather than forward it raw. id null per JSON-RPC for a batch-level error.
+  const id = Array.isArray(msg) ? (msg.find((m) => m && m.id != null)?.id ?? null) : null;
+  return { reply: JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32600, message: '⛔ canon: JSON-RPC batching is not supported through the gate — send individual requests' } }) };
+};
+
+/** client → server. { forward } to pass on, or { reply } to short-circuit a blocked call. */
+export function inspectClient(line, state) {
+  let msg;
+  try { msg = JSON.parse(line); } catch { return { forward: line }; }
+  if (Array.isArray(msg)) return batchError(msg); // a batch could smuggle a blocked tools/call — fail closed
+  if (msg && msg.method && msg.id != null) state.pending[msg.id] = msg.method;
+  // Fail CLOSED on calls: a tool is callable only once we've SEEN and vetted a
+  // tools/list AND its name survived that gating. Before any gated list (`listed`
+  // is false), block everything — a tool known to the agent out-of-band, or
+  // smuggled past tools/list, must not be forwarded and executed.
+  if (msg && msg.method === 'tools/call') {
+    const name = msg.params?.name;
+    if (!state.listed || !state.allowedNames?.has(name) || state.blocked.has(name)) return { reply: blockReply(msg.id, name) };
+  }
+  return { forward: line };
+}
+
+// Gate ONE server→client message in place: strip any tools array down to the
+// vetted set and record vetted/blocked names. Non-tools messages pass through
+// (their pending id is cleared). Extracted so a JSON-RPC batch can gate each
+// element instead of forwarding the array raw.
+function gateServerMsg(msg, state, opts) {
+  const isToolsResult = msg && msg.result && Array.isArray(msg.result.tools);
+  if (!isToolsResult) { if (msg && msg.id != null) delete state.pending[msg.id]; return msg; }
+  if (msg.id != null) delete state.pending[msg.id];
+  const { allowed, report } = gateTools(msg.result.tools, opts.entry);
+  const blockAll = opts.strict && report.some((r) => r.status !== 'vetted'); // strict: any problem → block the whole server
+  for (const r of report) if (r.status !== 'vetted') { state.blocked.add(r.tool); opts.onWarn?.(`${blockAll ? 'strict — blocking all (' : 'dropped '}${r.tool} (${r.status})${blockAll ? ')' : ''}`); }
+  const keep = blockAll ? new Set() : allowed;   // allowed is now a Set of hashes
+  const kept = msg.result.tools.filter((t) => t && typeof t === 'object' && keep.has(toolHash(t)));
+  msg.result.tools = kept;
+  // Remember the vetted names so a later tools/call can be allow-listed (fail
+  // closed). `listed` flips the call gate from blocklist to allowlist.
+  state.listed = true;
+  state.allowedNames = state.allowedNames || new Set();
+  for (const t of kept) state.allowedNames.add(t.name);
+  return msg;
+}
+
+/** server → client. Rewrites ANY result carrying a tools array down to the vetted
+ *  set — not only one correlated to a tracked tools/list id. A hostile server can
+ *  push an UNSOLICITED tools result, answer tools/list TWICE (the 2nd after the id
+ *  is cleared), bury tools in another reply, or hide a tools/list inside a
+ *  JSON-RPC BATCH array; all must be gated, never forwarded raw. */
+export function inspectServer(line, state, opts = {}) {
+  let msg;
+  try { msg = JSON.parse(line); } catch { return { forward: line }; }
+  if (Array.isArray(msg)) return { forward: JSON.stringify(msg.map((m) => gateServerMsg(m, state, opts))) };
+  return { forward: JSON.stringify(gateServerMsg(msg, state, opts)) };
+}
+
+/** Which lock entry governs this server: explicit --name, else the sole MCP entry. */
+export function pickEntry(lock, name) {
+  if (name) return (lock.skills && lock.skills[name]) || null;
+  const mcp = Object.entries(lock.skills || {}).filter(([, e]) => e.kind === 'mcp');
+  return mcp.length === 1 ? mcp[0][1] : null;
+}
+
+/** Spawn the downstream server and wire the two gated streams together. */
+export function runGate({ command, args = [], lockPath = 'canon.lock', name = null, strict = false, onWarn } = {}) {
+  const warn = onWarn || ((m) => process.stderr.write('[canon] ' + m + '\n'));
+  const entry = pickEntry(readLock(lockPath), name);
+  if (!entry) warn(`no pinned ${name ? '"' + name + '" ' : ''}MCP entry in ${lockPath} — every tool will be treated as unvetted (canon add it first)`);
+  const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'inherit'] });
+  const state = { pending: {}, blocked: new Set(), allowedNames: new Set(), listed: false };
+  const opts = { entry, strict, onWarn: warn };
+
+  readline.createInterface({ input: process.stdin }).on('line', (line) => {
+    if (!line.trim()) return;
+    const r = inspectClient(line, state);
+    if (r.reply) process.stdout.write(r.reply + '\n');
+    if (r.forward) child.stdin.write(r.forward + '\n');
+  });
+  readline.createInterface({ input: child.stdout }).on('line', (line) => {
+    if (!line.trim()) return;
+    process.stdout.write(inspectServer(line, state, opts).forward + '\n');
+  });
+  process.stdin.on('end', () => { try { child.stdin.end(); } catch {} });
+  child.on('exit', (code) => process.exit(code ?? 0));
+}

package/src/scan.mjs

@@ -0,0 +1,66 @@
+// Poison scan — reuse warden's supply-chain scanner (the OpenClaw poisoned-skill
+// class: injection / exfil instructions hidden in a tool's name, description, or
+// schema). canon adds the provenance layer on top; warden owns the detection.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { scanMcpTools } from '@askalf/redstamp/mcp';
+import { decide } from '@askalf/redstamp';
+import { canonicalJson } from './hash.mjs';
+
+// Which detection engine vetted a pin. redstamp is a pinned dependency that gets
+// bumped, so "clean" is always clean-as-of-some-ruleset — recording the version at
+// pin time lets verify explain the "same bytes, suddenly poisoned" outcome as
+// detection-improved rather than looking like a tamper. Resolved locally and
+// offline; redstamp's exports map hides ./package.json, so resolve the entry
+// module and walk up to its package.json. Never throws — provenance is an
+// enrichment, and an unreadable version must not break pinning.
+const resolveEngineEntry = () => createRequire(import.meta.url).resolve('@askalf/redstamp');
+let cached; // per-process: the engine version can't change mid-run
+export function detectionInfo(resolveEntry) {
+  if (!resolveEntry && cached !== undefined) return cached;
+  let det = null;
+  try {
+    let dir = path.dirname((resolveEntry || resolveEngineEntry)());
+    for (let up = path.dirname(dir); ; dir = up, up = path.dirname(dir)) {
+      const p = path.join(dir, 'package.json');
+      if (fs.existsSync(p)) {
+        const pkg = JSON.parse(fs.readFileSync(p, 'utf8'));
+        if (pkg && pkg.name === '@askalf/redstamp' && pkg.version) { det = { engine: 'redstamp', version: pkg.version }; break; }
+      }
+      if (up === dir) break;
+    }
+  } catch { det = null; }
+  if (!resolveEntry) cached = det;
+  return det;
+}
+
+/** Scan a loaded skill for poisoning. → { verdict: 'clean'|'flagged', findings, advisories }
+ *
+ *  Severity-aware by SURFACE. Long-form skill/file prose flags only on a
+ *  CRITICAL finding — an injection/exfil *instruction*; a bare sensitive-path or
+ *  secret-env *mention* comes back as an advisory instead (documentation
+ *  legitimately teaches credential handling — the official Claude Code
+ *  marketplace flagged 19/29 skills on mentions alone). MCP tool definitions
+ *  keep the strict any-finding rule: short descriptions are exactly the surface
+ *  the mention heuristics were tuned for. A finding without a `severity` field
+ *  (an older warden) is treated as critical — fail closed, never laxer. */
+export function scanSkill(skill) {
+  const all = scanMcpTools((skill && skill.scanTargets) || []);
+  const prose = !!skill && (skill.kind === 'skill' || skill.kind === 'file');
+  const findings = prose ? all.filter((f) => (f && f.severity) !== 'advisory') : all;
+  const advisories = prose ? all.filter((f) => f && f.severity === 'advisory') : [];
+  // An MCP manifest's launch fields (command/args/env) actually RUN when the
+  // server starts — an RCE or key-exfil hidden there must be caught too, not just
+  // poison in the tool descriptions.
+  const lz = skill && skill.launch;
+  if (lz && (lz.command || lz.args || lz.env)) {
+    const cmd = [lz.command, ...(Array.isArray(lz.args) ? lz.args : []), lz.env ? canonicalJson(lz.env) : '']
+      .filter(Boolean).join(' ');
+    const v = decide({ tool: 'shell', input: { command: cmd } });
+    if (v.tier === 'black' || v.tier === 'red') {
+      findings.push({ tool: (skill.name || 'server') + ' (launch)', flags: (v.why || []).filter((w) => /[☠⚠]/.test(w)), severity: 'critical' });
+    }
+  }
+  return { verdict: findings.length ? 'flagged' : 'clean', findings, advisories };
+}

package/src/sign.mjs

@@ -0,0 +1,128 @@
+// Ed25519 attestation. `--sign` stamps a pinned entry with a signature over its
+// content hash. WHO signed it is identified by the public key embedded in the
+// signature; WHETHER you accept that signer is a separate decision — the trust set
+// (see trust.mjs). Your machine's own key (in ~/.canon) is implicitly trusted, so a
+// local `--sign` round-trips with no extra step; a publisher you trust signs with
+// THEIR key and you add it once via `canon trust add`.
+//
+// The PRIVATE key is held in the OS keychain (keychain.mjs) — never written as
+// plaintext — when one is available; only the PUBLIC key lives in signing-key.json
+// (public is not secret). Hosts with no keychain fall back to a 0600 plaintext file,
+// and a pre-keychain plaintext key is migrated into the keychain on first sign. In CI,
+// set CANON_SIGNING_KEY (the private key) to sign without any local key at all —
+// signing moves off developer boxes into CI, and everyone else only `verify`s.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { keychainAvailable, keychainGet, keychainSet } from './keychain.mjs';
+
+// Resolved at call time (not import) so CANON_HOME can be set per-test/per-run.
+const keyFile = () => path.join(process.env.CANON_HOME || os.homedir(), '.canon', 'signing-key.json');
+
+// PEM bytes can differ only by line endings (CRLF on Windows, a trailing newline
+// from a file read) yet be the same key — normalize before hashing/verifying so a
+// key's identity is stable across platforms.
+const normPem = (p) => String(p).replace(/\r\n/g, '\n').trim();
+const enc64 = (s) => Buffer.from(s, 'utf8').toString('base64');
+const dec64 = (s) => Buffer.from(s, 'base64').toString('utf8');
+
+// A signing key injected via the environment — CI mode. CANON_SIGNING_KEY holds the
+// PRIVATE key (base64-encoded PEM, or a raw PEM); the PUBLIC key is DERIVED from it,
+// so the CI secret is just the private half and signing needs no file or keychain.
+// Read-only: never writes to disk/keychain (CI runners are ephemeral). Takes priority
+// over the local key, so `canon … --sign` in CI signs with this identity. Because the
+// public key is derived, a key minted locally and exported here keeps the same keyId.
+function envKey() {
+  const raw = process.env.CANON_SIGNING_KEY;
+  if (!raw) return null;
+  try {
+    const privateKey = raw.includes('-----BEGIN') ? raw : dec64(raw);
+    const publicKey = crypto.createPublicKey(privateKey).export({ type: 'spki', format: 'pem' });
+    return { publicKey, privateKey };
+  } catch {
+    return null;                                             // malformed → fall through to the local key
+  }
+}
+
+/** A stable short fingerprint for a public key — how the trust set addresses it. */
+export function keyId(publicKey) {
+  if (!publicKey) return '';
+  return crypto.createHash('sha256').update(normPem(publicKey)).digest('hex').slice(0, 16);
+}
+
+// The file half of the key record: { publicKey } (+ a legacy plaintext privateKey on
+// pre-keychain installs). Null when there's no key file at all.
+const readFile = () => { try { return JSON.parse(fs.readFileSync(keyFile(), 'utf8')); } catch { return null; } };
+
+/** The local key if it already exists, else null — never generates one (so a
+ *  read-only path like `verify` building its trust set can't create key material).
+ *  The private half comes from the OS keychain; a legacy plaintext private in the
+ *  file is honored as a fallback so existing installs keep working pre-migration.
+ *
+ *  `envAllowed:false` skips the CANON_SIGNING_KEY env key and returns ONLY the
+ *  machine's persistent local identity. The trust set uses this: the CI signing
+ *  key is for signing, not for auto-trusting — folding it into the verify-time
+ *  trust set as `self` would let anyone who can inject that env var into a verify
+ *  process become a trusted signer. (Commit its public key to canon.trust to
+ *  verify a lock it signed — the documented flow.) */
+export function loadKey({ envAllowed = true } = {}) {
+  if (envAllowed) { const env = envKey(); if (env) return env; } // CI: key from CANON_SIGNING_KEY
+  const file = readFile();
+  if (!file || !file.publicKey) return file;                 // no key (or unreadable)
+  if (keychainAvailable()) {
+    const stored = keychainGet();
+    if (stored) return { publicKey: file.publicKey, privateKey: dec64(stored) };
+  }
+  // keychain empty/unavailable → honor a legacy plaintext private if present.
+  return file.privateKey ? { publicKey: file.publicKey, privateKey: file.privateKey } : { publicKey: file.publicKey };
+}
+
+export function ensureKey() {
+  const env = envKey();
+  if (env) return env;                                       // CI: sign with the injected key; never generate/migrate
+  const file = keyFile();
+  const existing = readFile();
+  if (existing && existing.publicKey) {
+    // Migrate a legacy plaintext private key into the keychain, then strip it from
+    // the file. Same keypair → canon's identity is preserved. One-time, on first
+    // sign after the upgrade.
+    if (existing.privateKey && keychainAvailable()) {
+      keychainSet(enc64(existing.privateKey));
+      fs.writeFileSync(file, JSON.stringify({ publicKey: existing.publicKey }), { mode: 0o600 });
+    }
+    return loadKey();
+  }
+  // Generate a fresh keypair.
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (keychainAvailable()) {
+    keychainSet(enc64(privateKey));
+    fs.writeFileSync(file, JSON.stringify({ publicKey }), { mode: 0o600 });
+  } else {
+    fs.writeFileSync(file, JSON.stringify({ publicKey, privateKey }), { mode: 0o600 });
+  }
+  return { publicKey, privateKey };
+}
+
+/** Sign a content hash → { alg, pub, val }. Signs with the local key by default;
+ *  pass a { publicKey, privateKey } to sign as a specific publisher. */
+export function signHash(hash, key) {
+  const { publicKey, privateKey } = key || ensureKey();
+  const val = crypto.sign(null, Buffer.from(hash), privateKey).toString('base64');
+  return { alg: 'ed25519', pub: publicKey, val };
+}
+
+/** Cryptographically verify a signature object against a hash, using the public key
+ *  embedded in the signature. This proves the bytes were signed by whoever holds
+ *  that key — NOT that you trust that key. Trust (key ∈ your trust set) is a
+ *  separate gate, in trust.mjs, so a valid signature from an unknown key still
+ *  surfaces as `untrusted` rather than silently passing. */
+export function verifyHashSig(hash, sig) {
+  if (!sig || sig.alg !== 'ed25519' || !sig.val || !sig.pub) return false;
+  try { return crypto.verify(null, Buffer.from(hash), normPem(sig.pub), Buffer.from(sig.val, 'base64')); }
+  catch { return false; }
+}

package/src/trust.mjs

@@ -0,0 +1,79 @@
+// The trust set — WHOSE signatures canon accepts. A signed lock entry only counts
+// as vetted-by-a-publisher if its signing key is in this set. Three sources, unioned:
+//   - your machine's own key (implicit, named `self`)  → local `--sign` just works
+//   - a repo-committed `canon.trust`                   → travels with the repo, so a
+//                                                         signed lock verifies in CI
+//   - a user-global `~/.canon/trust.json`              → keys you trust everywhere
+// `canon.trust` is the one that matters for sharing: commit it and a teammate's /
+// CI's `canon verify` knows which publisher key to expect.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadKey, keyId } from './sign.mjs';
+
+export const DEFAULT_REPO_TRUST = 'canon.trust';
+const homeStore = () => path.join(process.env.CANON_HOME || os.homedir(), '.canon', 'trust.json');
+
+function readStore(file) {
+  try { const j = JSON.parse(fs.readFileSync(file, 'utf8')); return Array.isArray(j?.keys) ? j.keys : []; }
+  catch { return []; }
+}
+function writeStore(file, keys, repo) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // global store is private (it's your trust decisions); a repo canon.trust is meant
+  // to be committed, so don't lock it down to 0600.
+  fs.writeFileSync(file, JSON.stringify({ version: 1, keys }, null, 2) + '\n', repo ? undefined : { mode: 0o600 });
+}
+
+/** Build the active trust set as a Map: keyId → { id, name, publicKey }.
+ *  Always includes your own key as `self`, so a locally-signed lock verifies with
+ *  no extra trust step. */
+export function loadTrust({ trustPath, cwd = process.cwd() } = {}) {
+  const map = new Map();
+  const add = (k) => {
+    if (!k || !k.publicKey) return;
+    const id = keyId(k.publicKey);
+    if (!map.has(id)) map.set(id, { id, name: k.name || id.slice(0, 12), publicKey: k.publicKey });
+  };
+  // self = the machine's PERSISTENT local key only — NOT a CANON_SIGNING_KEY env
+  // key. A CI signing key signs; it isn't auto-trusted at verify time (that would
+  // let env-var injection into a verify process mint a trusted signer). Its public
+  // key belongs in canon.trust if you want to verify what it signed.
+  const self = loadKey({ envAllowed: false }); if (self) add({ name: 'self', publicKey: self.publicKey });
+  for (const k of readStore(homeStore())) add(k);
+  for (const k of readStore(trustPath || path.join(cwd, DEFAULT_REPO_TRUST))) add(k);
+  return map;
+}
+
+/** Name of the trusted signer for a public key, or null if its key isn't trusted. */
+export function trustedSigner(publicKey, trust) {
+  if (!publicKey) return null;
+  const entry = trust.get(keyId(publicKey));
+  return entry ? entry.name : null;
+}
+
+/** Add a publisher public key to the trust set (global by default, or repo canon.trust). */
+export function trustKey(publicKey, name, { repo = false, cwd = process.cwd() } = {}) {
+  const file = repo ? path.join(cwd, DEFAULT_REPO_TRUST) : homeStore();
+  const id = keyId(publicKey);
+  if (!id) throw new Error('not a public key');
+  const entry = { id, name: name || id.slice(0, 12), publicKey: String(publicKey).replace(/\r\n/g, '\n').trim() };
+  const keys = readStore(file).filter((k) => keyId(k.publicKey) !== id);
+  keys.push(entry);
+  writeStore(file, keys, repo);
+  return entry;
+}
+
+/** Remove a trusted key by exact id or id-prefix (global store). → count removed. */
+export function untrustKey(idOrPrefix, { cwd = process.cwd() } = {}) {
+  const file = homeStore();
+  const keys = readStore(file);
+  const kept = keys.filter((k) => !(k.id === idOrPrefix || (k.id || keyId(k.publicKey)).startsWith(idOrPrefix)));
+  if (kept.length !== keys.length) writeStore(file, kept, false);
+  return keys.length - kept.length;
+}
+
+/** The flattened trust set (incl. implicit `self`), for display. */
+export function listTrust(opts) {
+  return [...loadTrust(opts).values()];
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = 'name reservation — real release imminent';