@askalf/truecopy 0.0.1 → 0.6.2

package/src/cli.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+// canon CLI — vet, pin, and verify agent skills & MCP servers.
+// Exit code is a CI gate: 0 = all clean, 1 = anything flagged / drifted / poisoned.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { scan, pin, verify, diff, readLock, ensureKey, keyId, trustKey, untrustKey, listTrust, loadSkill, skillHash, scanSkill } from './index.mjs';
+import { discoverClaudeSkills, discoverClaudePluginSkills, discoverMarketplaceSkills, resolveClaudeSkill } from './claude.mjs';
+
+const argv = process.argv.slice(2);
+const sep = argv.indexOf('--');
+const pre = sep >= 0 ? argv.slice(0, sep) : argv;
+const post = sep >= 0 ? argv.slice(sep + 1) : []; // wrapped command, for `canon guard -- <cmd>`
+const cmd = pre[0];
+const opt = (name, def) => {
+  const i = pre.indexOf(name);
+  if (i >= 0) { const nx = pre[i + 1]; return nx !== undefined && !nx.startsWith('--') ? nx : true; } // `--name value` or bare `--name`
+  const eq = pre.find((x) => x.startsWith(name + '='));
+  return eq ? eq.slice(name.length + 1) : def;
+};
+const VALUE_FLAGS = new Set(['--lock', '--name', '--trust', '--settings', '--command', '--marketplace']); // consume the next token as a value
+const sources = (() => {
+  const out = [];
+  for (let i = 1; i < pre.length; i++) {
+    const a = pre[i];
+    if (a.startsWith('--')) { if (VALUE_FLAGS.has(a) && pre[i + 1] && !pre[i + 1].startsWith('--')) i++; continue; }
+    out.push(a);
+  }
+  return out;
+})();
+const lockPath = opt('--lock', 'canon.lock');
+const optTrust = () => { const t = opt('--trust', undefined); return typeof t === 'string' ? t : undefined; };
+
+// `--claude` expands to every Claude Code skill visible from here (.claude/skills,
+// project + user scope); `--claude-plugins` adds every skill shipped by installed
+// marketplace plugins, pinned under the `plugin:skill` name Claude Code invokes it
+// by (the dir basename alone would collide — discord:access vs telegram:access).
+// Project-relative paths go into the lock with forward slashes so a committed
+// canon.lock verifies on any OS / in CI.
+const portable = (dir) => {
+  const rel = path.relative(process.cwd(), dir);
+  return (rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : dir).replace(/\\/g, '/');
+};
+const allSources = () => {
+  const mkt = opt('--marketplace', undefined); // a CLONED marketplace/plugin repo (canon stays offline — you fetch, it scans)
+  return [
+    ...sources.map((src) => ({ src })),
+    ...(opt('--claude', false) ? discoverClaudeSkills().map(({ dir }) => ({ src: portable(dir) })) : []),
+    ...(opt('--claude-plugins', false) ? discoverClaudePluginSkills().map(({ name, dir }) => ({ src: portable(dir), name })) : []),
+    ...(typeof mkt === 'string' ? discoverMarketplaceSkills(mkt).map(({ name, dir }) => ({ src: portable(dir), name })) : []),
+  ];
+};
+
+const tty = process.stdout.isTTY;
+const C = { red: '\x1b[31m', grn: '\x1b[32m', yel: '\x1b[33m', dim: '\x1b[2m', bold: '\x1b[1m', rst: '\x1b[0m' };
+const c = (col, s) => (tty ? col + s + C.rst : s);
+const out = (s = '') => process.stdout.write(s + '\n');
+const mark = { ok: c(C.grn, '✓'), clean: c(C.grn, '✓'), flagged: c(C.red, '☠'), poisoned: c(C.red, '☠'), drifted: c(C.yel, '⚠'), missing: c(C.yel, '?'), unsigned: c(C.red, '⚠'), untrusted: c(C.red, '⚠'), unpinned: c(C.dim, '·') };
+const findingLine = (f) => `      ${c(C.red, '☠')} ${f.tool}: ${f.flags.join('; ')}`;
+
+function usage() {
+  out(`${c(C.bold, 'canon')} — own your agent skills · vet · sign · pin · verify
+
+  canon scan <source...>            poison-scan a skill / MCP manifest / directory
+  canon add  <source...> [--sign]   vet + pin into ${lockPath} (refuses poisoned unless --force)
+  canon scan --claude               poison-scan every Claude Code skill (.claude/skills, project + user)
+  canon add  --claude [--sign]      vet + pin them all
+  canon scan --claude-plugins       …and every skill shipped by installed marketplace plugins
+  canon add  --claude-plugins       vet + pin those under their \`plugin:skill\` invocation name
+  canon scan --marketplace <dir>    poison-scan a CLONED marketplace or plugin repo (you fetch, canon scans)
+  canon verify [--lock <file>] [--trust <file>]   re-check every pinned skill for drift / poisoning
+  canon diff <source> [--name <n>]  show what changed since it was pinned
+  canon list                        show the pinned set
+  canon guard [--lock <file>] -- <cmd...>   verify the lock, then run <cmd> only if it's clean
+
+  canon key                         print this machine's public key + id (share it to be trusted)
+  canon trust add <pubkey> --name <who> [--repo]   trust a publisher's key (--repo → commit it to canon.trust)
+  canon trust list                  show the trusted signing keys
+  canon trust remove <id>           stop trusting a key
+
+  canon hook claude [--strict]      Claude Code PreToolUse hook: block a pinned skill that
+                                    drifted or turned poisonous at the moment it's invoked
+                                    (--strict: only pinned skills may run at all)
+  canon hook install [--strict] [--user] [--settings <file>]
+                                    wire that hook into .claude/settings.json (idempotent;
+                                    project file by default, --user for ~/.claude)
+
+  canon-mcp [--lock] [--name] [--strict] -- <mcp-server cmd...>
+                                    enforce the lock on a LIVE MCP server: only vetted,
+                                    unmodified, unpoisoned tools reach the client
+
+  Exit 1 on any flagged / drifted / poisoned result — drop it in CI.`);
+}
+
+const advisoryLine = (f) => c(C.dim, `      · ${f.tool}: ${f.flags.join('; ')}  (advisory — capability mention, not an instruction)`);
+
+function runScan() {
+  const list = allSources();
+  if (!list.length) return (usage(), 2);
+  let bad = 0;
+  for (const { src, name } of list) {
+    try {
+      const r = scan(src);
+      const adv = r.advisories?.length ? c(C.yel, `  · ${r.advisories.length} advisory`) : '';
+      out(`${mark[r.verdict]} ${c(C.bold, name || r.skill.name)} ${c(C.dim, `(${r.skill.kind})`)}  ${r.verdict}${adv}`);
+      r.findings.forEach((f) => out(findingLine(f)));
+      (r.advisories || []).forEach((f) => out(advisoryLine(f)));
+      if (r.verdict !== 'clean') bad++;
+    } catch (e) { out(`${c(C.red, '✗')} ${src}: ${e.message}`); bad++; }
+  }
+  return bad ? 1 : 0;
+}
+
+function runAdd() {
+  const list = allSources();
+  if (!list.length) return (usage(), 2);
+  const sign = opt('--sign', false), force = opt('--force', false);
+  let bad = 0;
+  for (const { src, name } of list) {
+    try {
+      const r = pin(src, { lockPath, sign: !!sign, force: !!force, name: name || opt('--name', undefined) });
+      if (r.ok) out(`${mark.ok} pinned ${c(C.bold, r.name)} ${c(C.dim, r.hash.slice(0, 12))}${r.signed ? c(C.dim, ' · signed') : ''}${r.advisories ? c(C.yel, ` · ${r.advisories} advisory`) : ''}`);
+      else { out(`${mark.flagged} refused ${c(C.bold, name || src)} — poisoned (use --force to override):`); r.findings.forEach((f) => out(findingLine(f))); bad++; }
+    } catch (e) { out(`${c(C.red, '✗')} ${src}: ${e.message}`); bad++; }
+  }
+  return bad ? 1 : 0;
+}
+
+function runVerify() {
+  const { ok, results, error } = verify({ lockPath, trustPath: optTrust() });
+  if (error) { out(c(C.red, `⛔ ${error}`)); return 1; }
+  if (!results.length) { out(c(C.dim, `no pinned skills in ${lockPath}`)); return 0; }
+  for (const r of results) {
+    const sig = r.signer ? c(C.dim, ` · signed by ${r.signer}`) : (r.signed ? c(C.dim, ' · signed') : '');
+    const acc = r.accepted ? c(C.yel, ' · accepted findings (--force pin)') : '';
+    out(`${mark[r.status] || '?'} ${c(C.bold, r.name)}  ${r.status}${sig}${acc}`);
+    if (r.status === 'drifted') out(c(C.dim, `      ${summary(r)}`));
+    if (r.status === 'untrusted') out(c(C.dim, `      key ${r.keyId} not trusted — canon trust add <pubkey> --name <publisher>`));
+    if (r.status === 'poisoned') r.findings.forEach((f) => out(findingLine(f)));
+  }
+  out(ok ? c(C.grn, `\nall ${results.length} pinned skills verified`) : c(C.red, `\n${results.filter((r) => r.status !== 'ok').length}/${results.length} FAILED — review above`));
+  return ok ? 0 : 1;
+}
+
+function runDiff() {
+  if (!sources.length) return (usage(), 2);
+  const r = diff(sources[0], { lockPath, name: opt('--name', undefined) });
+  out(`${mark[r.status] || '?'} ${c(C.bold, r.name)}  ${r.status}`);
+  if (r.status === 'drifted') {
+    out(c(C.dim, `      was ${r.was.slice(0, 12)} → now ${r.now.slice(0, 12)}`));
+    out(`      ${summary(r)}`);
+  }
+  return r.status === 'drifted' || r.status === 'unpinned' ? 1 : 0;
+}
+
+function summary(r) {
+  const bits = [];
+  if (r.added?.length) bits.push(c(C.grn, `+${r.added.join(' +')}`));
+  if (r.changed?.length) bits.push(c(C.yel, `~${r.changed.join(' ~')}`));
+  if (r.removed?.length) bits.push(c(C.red, `-${r.removed.join(' -')}`));
+  return bits.join('  ') || c(C.dim, '(content changed)');
+}
+
+function runList() {
+  const lock = readLock(lockPath);
+  const names = Object.keys(lock.skills);
+  if (!names.length) { out(c(C.dim, `no pinned skills in ${lockPath}`)); return 0; }
+  for (const n of names) {
+    const e = lock.skills[n];
+    out(`${c(C.grn, '●')} ${c(C.bold, n)} ${c(C.dim, `${e.kind} · ${e.hash.slice(0, 12)} · ${e.scannedAt.slice(0, 10)}${e.sig ? ' · signed' : ''}`)}`);
+  }
+  return 0;
+}
+
+function runGuard() {
+  if (!post.length) { out('usage: canon guard [--lock <file>] -- <command...>'); return 2; }
+  const { ok, results, error } = verify({ lockPath, trustPath: optTrust() });
+  if (error) { out(`${c(C.red, '⛔ canon: refusing to launch —')} ${error}`); return 1; }
+  if (!ok) {
+    const bad = results.filter((r) => r.status !== 'ok');
+    out(`${c(C.red, '⛔ canon: refusing to launch —')} ${bad.length} of ${results.length} skill(s) failed:`);
+    bad.forEach((r) => out(`   ${mark[r.status] || '?'} ${c(C.bold, r.name)}: ${r.status}`));
+    return 1;
+  }
+  out(c(C.dim, `canon: ${results.length} pinned skill(s) verified — launching`));
+  const res = spawnSync(post[0], post.slice(1), { stdio: 'inherit' });
+  return res.status ?? (res.error ? 127 : 0);
+}
+
+function runKey() {
+  const { publicKey } = ensureKey();
+  const id = keyId(publicKey);
+  if (opt('--json', false)) { out(JSON.stringify({ id, publicKey: publicKey.trim() })); return 0; }
+  out(`${c(C.bold, 'key id')}  ${id}`);
+  out(publicKey.trim());
+  out(c(C.dim, `\nShare this key; whoever trusts you runs:  canon trust add <this-key-file> --name <you>`));
+  return 0;
+}
+
+function readKeyArg(arg) {
+  // accept a PEM file, or a JSON key file / `canon key --json` output ({ publicKey })
+  const raw = fs.readFileSync(arg, 'utf8');
+  if (raw.trim().startsWith('{')) { try { return JSON.parse(raw).publicKey; } catch {} }
+  return raw;
+}
+
+function runTrust() {
+  const action = sources[0] || 'list';
+  if (action === 'list') {
+    const keys = listTrust({ trustPath: optTrust() });
+    if (!keys.length) { out(c(C.dim, 'no trusted keys')); return 0; }
+    for (const k of keys) out(`${c(C.grn, '●')} ${c(C.bold, k.name)} ${c(C.dim, k.id)}`);
+    return 0;
+  }
+  if (action === 'add') {
+    if (!sources[1]) { out('usage: canon trust add <publicKeyFile> --name <label> [--repo]'); return 2; }
+    let pub;
+    try { pub = readKeyArg(sources[1]); } catch (e) { out(`${c(C.red, '✗')} ${e.message}`); return 1; }
+    try {
+      const repo = !!opt('--repo', false);
+      const r = trustKey(pub, opt('--name', undefined), { repo });
+      out(`${mark.ok} trusted ${c(C.bold, r.name)} ${c(C.dim, r.id)}${repo ? c(C.dim, ' · canon.trust') : ''}`);
+      return 0;
+    } catch (e) { out(`${c(C.red, '✗')} ${e.message}`); return 1; }
+  }
+  if (action === 'remove' || action === 'rm') {
+    if (!sources[1]) { out('usage: canon trust remove <keyId>'); return 2; }
+    const n = untrustKey(sources[1]);
+    out(n ? `${mark.ok} removed ${n} key(s)` : c(C.dim, 'no matching key'));
+    return 0;
+  }
+  out(`canon trust: unknown action '${action}' (add | list | remove)`);
+  return 2;
+}
+
+// `canon hook claude` — a Claude Code PreToolUse hook (matcher: Skill). Reads the
+// hook payload from stdin, resolves the SAME skill directory Claude Code is about
+// to run, and re-checks it against the lock right then. Exit 2 blocks the call
+// (Claude Code feeds stderr back to the model); exit 0 lets it through.
+//
+// Policy — default protects the PINNED set; --strict turns the lock into a whitelist:
+//                        default   --strict
+//   pinned + unchanged     allow     allow
+//   pinned + drifted       BLOCK     BLOCK
+//   pinned + poisoned      BLOCK     BLOCK
+//   pinned, dir missing    BLOCK     BLOCK     (can't verify what will run → fail closed)
+//   not pinned             allow     BLOCK     (adoption-friendly vs lockdown)
+//   no lock / hook error   allow     BLOCK     (a crashed gate must not be a bypass in strict)
+function runHookClaude() {
+  const strict = !!opt('--strict', false);
+  const deny = (msg) => { process.stderr.write(`canon: ${msg}\n`); return 2; };
+  try {
+    let payload = {};
+    try { payload = JSON.parse(fs.readFileSync(0, 'utf8')); } catch {}
+    if ((payload.tool_name || '') !== 'Skill') return 0; // mis-wired matcher — never break other tools
+    const name = payload.tool_input && payload.tool_input.skill;
+    if (!name) return 0;
+
+    // lock: explicit --lock > <project>/canon.lock > ./canon.lock (hooks run in the project dir)
+    const projectDir = process.env.CLAUDE_PROJECT_DIR || payload.cwd || process.cwd();
+    const explicit = opt('--lock', undefined);
+    const candidates = typeof explicit === 'string' ? [explicit] : [path.join(projectDir, 'canon.lock'), 'canon.lock'];
+    const lp = candidates.find((p) => fs.existsSync(p));
+    if (!lp) return strict ? deny(`no canon.lock — pin your skills first: canon add --claude`) : 0;
+
+    let lock;
+    try { lock = readLock(lp, { mustExist: true }); }
+    catch (e) { return deny(`refusing skill '${name}' — ${e.message}`); } // corrupt lock fails CLOSED, both modes
+    const entry = lock.skills[name];
+    if (!entry) return strict ? deny(`skill '${name}' is not pinned in ${lp} — vet it first: canon add .claude/skills/${name}`) : 0;
+
+    const dir = resolveClaudeSkill(name, { projectDir });
+    if (!dir) return deny(`skill '${name}' is pinned but not found under .claude/skills — can't verify what will run`);
+    const skill = loadSkill(dir);
+    if (skillHash(skill) !== entry.hash) return deny(`skill '${name}' DRIFTED since it was pinned — review with: canon diff ${dir.replace(/\\/g, '/')}`);
+    const s = scanSkill(skill);
+    // findings the human accepted with a --force pin (verdict:'flagged' in the
+    // lock) don't re-block the same bytes; flagged-but-pinned-clean still does
+    if (s.verdict === 'flagged' && entry.verdict !== 'flagged') return deny(`skill '${name}' is POISONED: ${s.findings.map((f) => `${f.tool}: ${f.flags.join('; ')}`).join(' · ')}`);
+    return 0;
+  } catch (e) {
+    return strict ? deny(`hook error — ${e && e.message || e}`) : 0;
+  }
+}
+
+// `canon hook install` — wire the gate into Claude Code settings without hand-
+// editing JSON. Manages exactly ONE canon-owned PreToolUse entry (recognized by
+// its command containing `hook claude`), updating it in place on re-runs; every
+// other hook is left untouched. An unparseable settings file is REFUSED, never
+// clobbered — a config gate must not destroy config.
+function runHookInstall() {
+  const strict = !!opt('--strict', false);
+  const explicit = opt('--settings', undefined);
+  const target = typeof explicit === 'string' ? explicit
+    : (opt('--user', false) ? path.join(os.homedir(), '.claude', 'settings.json') : path.join('.claude', 'settings.json'));
+  const cmdOverride = opt('--command', undefined);
+  const command = typeof cmdOverride === 'string' ? cmdOverride
+    : `npx -y github:askalf/canon hook claude${strict ? ' --strict' : ''}`;
+
+  let settings = {};
+  try { settings = JSON.parse(fs.readFileSync(target, 'utf8')); }
+  catch (e) {
+    if (!e || e.code !== 'ENOENT') { out(`${c(C.red, '✗')} ${target} exists but can't be used: ${e.message} — fix it, or point --settings elsewhere`); return 1; }
+  }
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) { out(`${c(C.red, '✗')} ${target} is not a settings object — refusing to rewrite it`); return 1; }
+  if (settings.hooks !== undefined && (typeof settings.hooks !== 'object' || Array.isArray(settings.hooks) || settings.hooks === null)) { out(`${c(C.red, '✗')} ${target} has a non-object "hooks" — refusing to rewrite it`); return 1; }
+  settings.hooks = settings.hooks || {};
+  if (settings.hooks.PreToolUse !== undefined && !Array.isArray(settings.hooks.PreToolUse)) { out(`${c(C.red, '✗')} ${target} has a non-array hooks.PreToolUse — refusing to rewrite it`); return 1; }
+  const pre = settings.hooks.PreToolUse || (settings.hooks.PreToolUse = []);
+
+  const ours = (h) => h && Array.isArray(h.hooks) && h.hooks.some((x) => x && typeof x.command === 'string' && x.command.includes('hook claude'));
+  const entry = { matcher: 'Skill', hooks: [{ type: 'command', command, timeout: 10 }] };
+  const i = pre.findIndex(ours);
+  const action = i >= 0 ? 'updated' : 'installed';
+  if (i >= 0) pre[i] = entry; else pre.push(entry);
+
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, JSON.stringify(settings, null, 2) + '\n');
+  out(`${mark.ok} ${action} the canon Skill gate in ${target}${strict ? ` ${c(C.yel, '(strict)')}` : ''}`);
+  out(c(C.dim, `   command: ${command}`));
+  out(c(C.dim, '   already-running Claude Code sessions snapshot hooks at start — restart them to pick this up'));
+  if (typeof explicit !== 'string' && !opt('--user', false)) out(c(C.dim, `   commit ${target} together with ${lockPath} and this repo's gate travels with it`));
+  return 0;
+}
+
+function runHook() {
+  const sub = sources[0] || '';
+  if (sub === 'claude') return runHookClaude();
+  if (sub === 'install') return runHookInstall();
+  out('usage: canon hook claude [--lock <file>] [--strict]   ·   canon hook install [--strict] [--user] [--settings <file>] [--command <cmd>]');
+  return 2;
+}
+
+const table = { scan: runScan, add: runAdd, verify: runVerify, diff: runDiff, list: runList, guard: runGuard, key: runKey, trust: runTrust, hook: runHook };
+if (!cmd || cmd === '-h' || cmd === '--help' || !table[cmd]) { usage(); process.exit(cmd && cmd !== '-h' && cmd !== '--help' ? 2 : 0); }
+try { process.exit(table[cmd]()); }
+catch (e) { process.stderr.write(`canon: ${e && e.message || e}\n`); process.exit(1); }

package/src/gate.mjs

@@ -0,0 +1,49 @@
+// Runtime enforcement logic — classify the tools an MCP server actually advertises
+// against what you pinned in canon.lock. Only a tool that is pinned, unmodified,
+// and unpoisoned is "vetted"; everything else is dropped so it never reaches the
+// agent. This is the runtime half of canon: vet (scan/add) → pin → ENFORCE.
+import { sha256, canonicalJson } from './hash.mjs';
+import { scanSkill } from './scan.mjs';
+
+export const toolHash = (t) => sha256(canonicalJson(t));   // export it for mcp.mjs
+
+/**
+ * → { report: [{ tool, hash, status }], allowed: Set<contentHash> }
+ * status: vetted | drifted | unvetted | unpinned | poisoned
+ */
+export function gateTools(tools = [], entry = null) {
+  // Fail-safe: a hostile MCP server can advertise a non-array tool list or
+  // null/primitive entries. A non-array yields an empty gate (nothing vetted →
+  // everything dropped downstream); malformed entries are filtered out (they're
+  // never "vetted", so dropping them is the safe outcome).
+  if (!Array.isArray(tools)) return { report: [], allowed: new Set() };
+  tools = tools.filter((t) => t && typeof t === 'object');
+  const parts = (entry && entry.parts && typeof entry.parts === 'object') ? entry.parts : {};
+  const poisoned = new Set(scanSkill({ scanTargets: tools }).findings.map((f) => f.tool));
+  // null-prototype map: a tool whose name is a prototype member ("__proto__",
+  // "toString", "constructor", "hasOwnProperty", …) would otherwise read/clobber
+  // an inherited value, corrupting the count so the duplicate-name guard below
+  // silently never fires — letting a same-named poisoned twin ride in. (Same
+  // reason `parts` is probed with Object.hasOwn, not `in`, which walks the chain.)
+  const nameCounts = Object.create(null);
+  for (const t of tools) nameCounts[t.name] = (nameCounts[t.name] || 0) + 1;
+  // A --force pin recorded verdict:'flagged' — the human accepted the findings for
+  // exactly the pinned bytes, so a flagged tool whose hash still matches its pinned
+  // part isn't re-blocked. Everything else flagged (unpinned, drifted, or pinned
+  // clean and re-flagged by newer detection) is never served.
+  const acceptedFinding = (t, h) =>
+    entry && entry.verdict === 'flagged' && nameCounts[t.name] === 1 && Object.hasOwn(parts, t.name) && parts[t.name] === h;
+  const report = tools.map((t) => {
+    const h = toolHash(t);
+    const status =
+      poisoned.has(t.name) && !acceptedFinding(t, h) ? 'poisoned' // injection/exfil in name/desc/schema — never serve
+        : !entry ? 'unpinned'                  // this server isn't in the lock at all
+          : nameCounts[t.name] > 1 ? 'drifted' // duplicate name → not trustworthy by name
+            : !Object.hasOwn(parts, t.name) ? 'unvetted'  // a tool you never pinned (e.g. silently added)
+              : parts[t.name] !== h ? 'drifted' // pinned, but its definition changed
+                : 'vetted';
+    return { tool: t.name, hash: h, status };
+  });
+  // allowed keyed by CONTENT HASH so the runtime filter can drop a same-named drifted twin
+  return { report, allowed: new Set(report.filter((r) => r.status === 'vetted').map((r) => r.hash)) };
+}

package/src/hash.mjs

@@ -0,0 +1,25 @@
+// Content hashing + stable JSON, so a skill's identity is its bytes — not the
+// order a tool happened to serialize its keys in.
+import crypto from 'node:crypto';
+
+export const sha256 = (s) =>
+  crypto.createHash('sha256')
+    .update(Buffer.isBuffer(s) ? s : typeof s === 'string' ? s : String(s ?? ''))
+    .digest('hex');
+
+/** Deterministic JSON: object keys sorted recursively (arrays keep order).
+ *  Fail-safe on hostile input — a circular ref becomes "[circular]" and a BigInt
+ *  is stringified, so hashing a malformed tool definition can't throw. */
+export function canonicalJson(v) {
+  const seen = new WeakSet();
+  const sort = (x) => {
+    if (Array.isArray(x)) return x.map(sort);
+    if (x && typeof x === 'object') {
+      if (seen.has(x)) return '[circular]';
+      seen.add(x);
+      return Object.fromEntries(Object.keys(x).sort().map((k) => [k, sort(x[k])]));
+    }
+    return typeof x === 'bigint' ? x.toString() : x;
+  };
+  return JSON.stringify(sort(v)) ?? '';
+}

package/src/index.mjs

@@ -0,0 +1,114 @@
+// canon — own your agent skills. Vet (scan), pin (lock + hash), and verify
+// (drift) every skill & MCP server before it runs. The supply-chain gate that
+// pairs with warden's runtime firewall: vet it → contain it.
+import { loadSkill, skillHash } from './skill.mjs';
+import { scanSkill } from './scan.mjs';
+import { readLock, writeLock, DEFAULT_LOCK } from './lock.mjs';
+import { signHash, verifyHashSig, keyId, ensureKey } from './sign.mjs';
+import { loadTrust, trustedSigner, trustKey, untrustKey, listTrust } from './trust.mjs';
+import { sha256, canonicalJson } from './hash.mjs';
+
+export { loadSkill, skillHash, scanSkill, readLock, writeLock, DEFAULT_LOCK };
+export { signHash, verifyHashSig, keyId, ensureKey };
+export { loadTrust, trustedSigner, trustKey, untrustKey, listTrust };
+export { claudeSkillRoots, discoverClaudeSkills, discoverClaudePluginSkills, discoverMarketplaceSkills, resolveClaudeSkill } from './claude.mjs';
+
+// A per-part hash map (files of a skill dir, or tools of an MCP server), so a
+// drift can be explained as added / removed / changed parts — not just "the hash moved".
+function partsOf(skill) {
+  if (skill.kind === 'skill') return Object.fromEntries(skill.files.map((f) => [f.path, f.hash]));
+  if (skill.kind === 'mcp') {
+    const parts = Object.fromEntries(skill.tools.map((t, i) => [t.name || `tool[${i}]`, sha256(canonicalJson(t))]));
+    // The manifest envelope (name/instructions/command/args/env/url/…) is part of
+    // the pinned identity too, so a renamed server or a swapped launch command is
+    // an explainable drift, not an invisible one.
+    if (skill.manifestEnvelope) parts['(manifest)'] = sha256(canonicalJson(skill.manifestEnvelope));
+    return parts;
+  }
+  return { [skill.name]: sha256(skill.hashInput) };
+}
+
+/** Scan a source for poisoning. → { skill, verdict, findings } */
+export function scan(source) {
+  const skill = loadSkill(source);
+  return { skill, ...scanSkill(skill) };
+}
+
+/** Pin a vetted skill into the lock. Refuses to pin a flagged skill unless force. */
+export function pin(source, { lockPath = DEFAULT_LOCK, sign = false, force = false, name } = {}) {
+  const skill = loadSkill(source);
+  const s = scanSkill(skill);
+  if (s.verdict === 'flagged' && !force) return { ok: false, reason: 'flagged', findings: s.findings, skill };
+  const hash = skillHash(skill);
+  const key = name || skill.name;
+  const lock = readLock(lockPath);
+  lock.skills[key] = {
+    source: skill.source, kind: skill.kind, hash,
+    scannedAt: new Date().toISOString(), verdict: s.verdict, findings: s.findings.length,
+    ...(s.advisories?.length ? { advisories: s.advisories.length } : {}), // mentions noted at pin time, for the record
+    parts: partsOf(skill),
+    ...(sign ? { sig: signHash(hash), signed: true } : {}),
+  };
+  writeLock(lock, lockPath);
+  return { ok: true, name: key, hash, verdict: s.verdict, signed: sign, skill, advisories: s.advisories?.length || 0 };
+}
+
+/** Re-derive every pinned skill and classify it against the lock.
+ *  Fails CLOSED on a missing or corrupt lock — a present-but-empty lock stays
+ *  ok:true (legitimately nothing pinned). */
+export function verify({ lockPath = DEFAULT_LOCK, trustPath } = {}) {
+  let lock;
+  try { lock = readLock(lockPath, { mustExist: true }); }
+  catch (e) { return { ok: false, error: e.message, results: [] }; }
+  const trust = loadTrust({ trustPath });
+  const results = Object.entries(lock.skills).map(([name, entry]) => verifyOne(name, entry, trust));
+  return { ok: results.every((r) => r.status === 'ok'), results };
+}
+
+function verifyOne(name, entry, trust) {
+  let skill;
+  try { skill = loadSkill(entry.source); }
+  catch { return { name, status: 'missing', source: entry.source }; }
+  const hash = skillHash(skill);
+  if (hash !== entry.hash) return { name, status: 'drifted', source: entry.source, ...diffParts(entry.parts, partsOf(skill)) };
+  const s = scanSkill(skill);
+  // A `--force` pin recorded verdict:'flagged' — the human read these exact bytes
+  // and accepted the findings, so an UNCHANGED artifact doesn't re-fail on them.
+  // A skill pinned CLEAN that now scans flagged (same bytes, newer detection) still
+  // fails: nobody accepted those findings.
+  const accepted = s.verdict === 'flagged' && entry.verdict === 'flagged';
+  if (s.verdict === 'flagged' && !accepted) return { name, status: 'poisoned', source: entry.source, findings: s.findings };
+  if (entry.signed || entry.sig) {
+    // A signature that was STRIPPED or forged-against-a-different-hash fails the
+    // crypto check → `unsigned` (trust the recorded `signed` flag, not just a
+    // present `sig`, so deleting `sig` can't downgrade a tamper-stamp to "ok").
+    if (!verifyHashSig(hash, entry.sig)) return { name, status: 'unsigned', source: entry.source };
+    // Cryptographically valid, but anyone can sign with their OWN key — so the
+    // signer must be in your trust set. A valid signature from an unknown key is
+    // `untrusted` (fails closed), not silently accepted.
+    const signer = trustedSigner(entry.sig.pub, trust);
+    if (!signer) return { name, status: 'untrusted', source: entry.source, keyId: keyId(entry.sig.pub) };
+    return { name, status: 'ok', source: entry.source, signed: true, signer, ...(accepted ? { accepted: true } : {}) };
+  }
+  return { name, status: 'ok', source: entry.source, signed: false, ...(accepted ? { accepted: true } : {}) };
+}
+
+/** What changed in a source since it was pinned. */
+export function diff(source, { lockPath = DEFAULT_LOCK, name } = {}) {
+  const skill = loadSkill(source);
+  const key = name || skill.name;
+  const entry = readLock(lockPath).skills[key];
+  if (!entry) return { name: key, status: 'unpinned' };
+  const now = skillHash(skill);
+  if (now === entry.hash) return { name: key, status: 'ok' };
+  return { name: key, status: 'drifted', was: entry.hash, now, ...diffParts(entry.parts || {}, partsOf(skill)) };
+}
+
+function diffParts(before = {}, after = {}) {
+  const added = [], removed = [], changed = [];
+  for (const k of Object.keys(after)) if (!(k in before)) added.push(k); else if (before[k] !== after[k]) changed.push(k);
+  for (const k of Object.keys(before)) if (!(k in after)) removed.push(k);
+  return { added, removed, changed };
+}
+
+export { partsOf, diffParts };

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,35 @@
+// 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';
+
+// 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 { version: 1, skills: {} };
+    }
+    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; }
+  // Guarantee `skills` is a plain object — a corrupt/hostile lock with
+  // `skills: null` (or an array/string) would otherwise crash verify()'s
+  // Object.entries and pin()'s index assignment.
+  const skills = l.skills && typeof l.skills === 'object' && !Array.isArray(l.skills) ? l.skills : {};
+  return { version: 1, ...l, skills };
+}
+
+export function writeLock(lock, p = DEFAULT_LOCK) {
+  fs.writeFileSync(p, JSON.stringify(lock, null, 2) + '\n');
+}