@askalf/truecopy 0.0.1 → 0.7.0

package/src/cli.mjs

@@ -0,0 +1,415 @@
+#!/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, unpin, verify, diff, readLock, ensureKey, keyId, trustKey, untrustKey, listTrust, loadSkill, skillHash, scanSkill } from './index.mjs';
+import { discoverClaudeSkills, discoverClaudePluginSkills, discoverMarketplaceSkills, resolveClaudeSkill } from './claude.mjs';
+
+// This build's version — so `hook install` can PIN the gate command to a git tag
+// (a released version always has one) instead of fetching an unpinned ref at every
+// Skill invocation. Unreadable → unpinned fallback.
+const PKG_VERSION = (() => { try { return JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version; } catch { return null; } })();
+
+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; };
+// `--json` — machine-readable output for scan/verify/list/diff: one JSON document
+// on stdout, no ANSI, and the SAME exit codes (the CI gate contract is the exit
+// code; --json only changes what a dashboard/PR-commenter can parse from stdout).
+const jsonOut = !!opt('--json', false);
+
+// `--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>] [--require-signed]   re-check every pinned skill
+                                    for drift / poisoning (--require-signed: also fail any entry
+                                    without a valid signature from a trusted key)
+  canon diff <source> [--name <n>]  show what changed since it was pinned
+  canon list                        show the pinned set
+  canon remove <name...>            un-pin a skill — drop its ${lockPath} entry (alias: unpin)
+  canon guard [--lock <file>] [--require-signed] -- <cmd...>   verify the lock, then run <cmd> only if it's clean
+  …scan / verify / list / diff take --json: machine-readable stdout, same exit codes
+
+  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;
+  const results = [];
+  for (const { src, name } of list) {
+    try {
+      const r = scan(src);
+      if (jsonOut) results.push({ name: name || r.skill.name, kind: r.skill.kind, verdict: r.verdict, findings: r.findings, advisories: r.advisories || [] });
+      else {
+        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) {
+      // an unreadable source counts against `flagged` — it fails the gate today, and
+      // a JSON consumer must see WHY the exit code is 1
+      if (jsonOut) results.push({ name: name || src, error: e.message });
+      else out(`${c(C.red, '✗')} ${src}: ${e.message}`);
+      bad++;
+    }
+  }
+  if (jsonOut) out(JSON.stringify({ results, flagged: 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(), requireSigned: !!opt('--require-signed', false) });
+  // the library return IS the documented shape — emit it verbatim (incl. `error`
+  // for a missing/corrupt lock, which keeps failing closed with exit 1)
+  if (jsonOut) { out(JSON.stringify(error === undefined ? { ok, results } : { ok, results, error })); return ok ? 0 : 1; }
+  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.requiredSignature) out(c(C.dim, `      --require-signed: no trusted signature — sign it (canon add --sign) and trust the key`));
+    if (r.status === 'poisoned') {
+      r.findings.forEach((f) => out(findingLine(f)));
+      // the single most confusing verify outcome, disambiguated: the bytes did not
+      // move — the detection did. Still fails closed; a human must re-accept.
+      if (r.detectionChanged) out(c(C.dim, `      same bytes — flagged by newer detection (${r.pinnedDetection.engine} ${r.pinnedDetection.version} → ${r.currentDetection?.version || 'unknown'}); review, then re-accept with: canon add --force ${r.source}`));
+    }
+  }
+  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);
+  let r;
+  try { r = diff(sources[0], { lockPath, name: opt('--name', undefined) }); }
+  catch (e) {
+    // an unreadable source / corrupt lock must not break the --json contract
+    // (one JSON document on stdout) — emit a JSON error, still exit 1
+    if (jsonOut) { out(JSON.stringify({ name: opt('--name', undefined) || sources[0], status: 'error', error: e.message })); return 1; }
+    out(`${c(C.red, '✗')} ${e.message}`); return 1;
+  }
+  if (jsonOut) { out(JSON.stringify(r)); return r.status === 'drifted' || r.status === 'unpinned' ? 1 : 0; }
+  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() {
+  let lock;
+  try { lock = readLock(lockPath); }
+  catch (e) {
+    // a corrupt lock throws — keep the --json contract instead of an empty stdout
+    if (jsonOut) { out(JSON.stringify({ error: e.message, skills: [] })); return 1; }
+    out(`${c(C.red, '⛔ ')}${e.message}`); return 1;
+  }
+  const names = Object.keys(lock.skills);
+  if (jsonOut) {
+    const skills = names.map((n) => { const e = lock.skills[n]; return { name: n, kind: e.kind, hash: e.hash, scannedAt: e.scannedAt, signed: !!(e.sig || e.signed), ...(e.detection ? { detection: e.detection } : {}) }; });
+    out(JSON.stringify({ skills }));
+    return 0;
+  }
+  if (!names.length) { out(c(C.dim, `no pinned skills in ${lockPath}`)); return 0; }
+  const short = (s, n) => (typeof s === 'string' ? s.slice(0, n) : '?'); // a hand-edited entry may lack hash/scannedAt
+  for (const n of names) {
+    const e = lock.skills[n];
+    out(`${c(C.grn, '●')} ${c(C.bold, n)} ${c(C.dim, `${e.kind || '?'} · ${short(e.hash, 12)} · ${short(e.scannedAt, 10)}${e.detection ? ` · ${e.detection.engine} ${e.detection.version}` : ''}${e.sig ? ' · signed' : ''}`)}`);
+  }
+  return 0;
+}
+
+// The lock lifecycle's other half: `add` pins, `remove` un-pins. Names are lock
+// keys matched exactly (no disk access), so removing an already-uninstalled skill
+// works. Idempotent — a missing name is a notice, not a failure — so CI can call it.
+function runRemove() {
+  if (!sources.length) { out(`usage: canon remove <name...> [--lock <file>]`); return 2; }
+  for (const name of sources) {
+    const n = unpin(name, { lockPath });
+    out(n ? `${mark.ok} removed ${c(C.bold, name)}` : c(C.dim, `no matching entry: ${name}`));
+  }
+  return 0;
+}
+
+function runGuard() {
+  if (!post.length) { out('usage: canon guard [--lock <file>] -- <command...>'); return 2; }
+  const { ok, results, error } = verify({ lockPath, trustPath: optTrust(), requireSigned: !!opt('--require-signed', false) });
+  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 = null, parsed = true;
+    try { payload = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { parsed = false; }
+    // A payload we couldn't read/parse is a HOOK ERROR, not a non-Skill call: we
+    // don't know what's being invoked. Fail CLOSED in strict (the decision table's
+    // "hook error → BLOCK"); allow in default (adoption-friendly). A successfully
+    // parsed NON-Skill object is a mis-wired matcher — return 0 in both modes so
+    // other tools never break.
+    if (!parsed || !payload || typeof payload !== 'object' || Array.isArray(payload))
+      return strict ? deny('unreadable hook payload — failing closed (strict)') : 0;
+    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);
+  // Pin to THIS version's git tag (released versions have one) — a supply-chain
+  // gate should not fetch a moving ref on every Skill call. Correct repo name
+  // (truecopy, not the legacy canon). Re-run `hook install` after upgrading to
+  // repoint; `--command` still overrides for a global-install / offline setup.
+  const ref = PKG_VERSION ? `#v${PKG_VERSION}` : '';
+  const command = typeof cmdOverride === 'string' ? cmdOverride
+    : `npx -y github:askalf/truecopy${ref} 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: 20 }] }; // 20s: margin for a cold (pinned) npx fetch on the first gated call
+  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, remove: runRemove, unpin: runRemove, 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,149 @@
+// 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, detectionInfo } 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, detectionInfo, 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
+    ...((d) => (d ? { detection: d } : {}))(detectionInfo()), // WHAT this verdict was judged against — omitted if unreadable, never fatal
+    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 };
+}
+
+/** Un-pin a skill — remove its lock entry by exact name. → count removed (0 or 1).
+ *  The guided mirror of `pin`: hand-deleting from a signed lock is exactly the
+ *  manual editing canon exists to discourage. A no-op removal never writes (so it
+ *  can't create an empty lock), and a corrupt lock still fails CLOSED via readLock. */
+export function unpin(name, { lockPath = DEFAULT_LOCK } = {}) {
+  const lock = readLock(lockPath);
+  if (!(name in lock.skills)) return 0;
+  delete lock.skills[name];
+  writeLock(lock, lockPath);
+  return 1;
+}
+
+/** 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, requireSigned = false } = {}) {
+  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));
+  // Opt-in strict policy: reject any entry that lacks a valid signature from a
+  // TRUSTED key. Without it, `--sign` only helps if you also *look* — a lock
+  // substitution that strips `sig`+`signed` and re-points at other clean-scanning
+  // bytes verifies `ok`. requireSigned makes that fail closed: an ok-but-unsigned
+  // (or force-accepted-unsigned) entry becomes `unsigned`. Entries already failing
+  // (drifted/poisoned/untrusted/missing) are untouched.
+  if (requireSigned) for (const r of results) {
+    if (r.status === 'ok' && !(r.signed && r.signer)) { r.status = 'unsigned'; r.requiredSignature = true; }
+  }
+  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);
+  // `entry.parts || {}` (not diffParts' default) because a hostile lock can carry
+  // parts:null — the default only fills `undefined`, so `k in null` would throw an
+  // uncaught TypeError up through verify() (diff() already guards this the same way).
+  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) {
+    // Pinned CLEAN, flagged NOW, and the hash already matched above — so the bytes
+    // did not change; the detection did. Same fail-closed `poisoned` (nobody
+    // accepted these findings), but tagged so the CLI can say "this is not a
+    // tamper" — only for entries that carry a pin-time detection stamp; older
+    // locks get exactly today's bare report.
+    const explain = entry.verdict === 'clean' && entry.detection
+      ? { detectionChanged: true, pinnedDetection: entry.detection, currentDetection: detectionInfo() }
+      : {};
+    return { name, status: 'poisoned', source: entry.source, findings: s.findings, ...explain };
+  }
+  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 };