@askalf/truecopy 0.6.2 → 0.7.0

package/README.md

@@ -34,6 +34,7 @@ truecopy add  ./mcp-server.json --sign   # vet + pin into truecopy.lock (refuses
 truecopy verify                          # re-check every pinned skill for drift / poisoning  (CI: exit 1 on any fail)
 truecopy diff ./mcp-server.json          # what changed since you pinned it
 truecopy list                            # the pinned set
+truecopy remove old-skill                # un-pin a deprecated skill — drops its lock entry, no hand-editing (a signed lock would flag that as tampering)
 truecopy guard -- npm start              # verify the lock, then launch only if it's clean
 truecopy add --claude --claude-plugins --sign   # pin every Claude Code skill — project, user, and marketplace-plugin scope
 truecopy hook install                    # …and wire the invocation-time gate into .claude/settings.json
@@ -95,7 +96,7 @@ truecopy scan --marketplace ./clone     # audit a marketplace or plugin repo you
   "hooks": {
     "PreToolUse": [
       { "matcher": "Skill",
-        "hooks": [{ "type": "command", "command": "npx -y github:askalf/truecopy hook claude", "timeout": 10 }] }
+        "hooks": [{ "type": "command", "command": "npx -y github:askalf/truecopy#v0.6.2 hook claude", "timeout": 20 }] }
     ]
   }
 }
@@ -164,6 +165,13 @@ Trust comes from three sources, unioned: your own machine's key (implicit, so a
 
 ```yaml
 - run: npx -y github:askalf/truecopy verify   # fails the build if any pinned skill drifted or turned poisonous
+- run: npx -y github:askalf/truecopy verify --json > truecopy-report.json   # same gate, machine-readable — feed a dashboard / PR comment (scan, list, diff take --json too)
+```
+
+**Require signatures where trust matters.** By default `verify` accepts an unsigned entry whose bytes match — signing only helps if you also *look* at the lock diff. Add **`--require-signed`** (to `verify` or `guard`) and any entry without a valid signature from a **trusted key** fails closed, so a lock substitution that strips the signature and swaps in other clean-scanning bytes can't pass. Pair it with a committed `truecopy.trust`:
+
+```yaml
+- run: npx -y github:askalf/truecopy verify --require-signed   # every pinned skill must be signed by a trusted publisher
 ```
 
 **Sign in CI, not on laptops.** Hold the private signing key as a single CI secret instead of scattering it across developer machines. Set **`CANON_SIGNING_KEY`** to the private key (a raw ed25519 PEM, or base64-encoded) — truecopy derives the public key from it, so signing needs no `~/.truecopy` file and no keychain, and the key keeps the same `keyId`:
@@ -176,6 +184,8 @@ Trust comes from three sources, unioned: your own machine's key (implicit, so a
 
 Mint the identity once (`openssl genpkey -algorithm ed25519`), store the private key as the `CANON_SIGNING_KEY` secret, and commit its public key to **`truecopy.trust`** (`truecopy trust add <pub.pem> --repo`). Everyone else — laptops, the fleet, the verify job above — carries only the public key, so they `verify` but never sign: one signing identity in one secret, not a private key on every box.
 
+> The `CANON_SIGNING_KEY` env key **signs only** — it is *not* auto-trusted at verify time (otherwise anyone who could set that env var on a verify runner would become a trusted signer). So committing its public key to `truecopy.trust` is required, not optional: that is what a `verify` step checks the signature against.
+
 ## Library
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/truecopy",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "own your agent skills — vet, sign, and pin every skill & MCP server before it runs. The supply-chain gate for AI agents. Part of Own Your Stack.",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -5,9 +5,14 @@ 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 { 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;
@@ -31,6 +36,10 @@ const sources = (() => {
 })();
 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
@@ -69,10 +78,14 @@ function usage() {
   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 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 guard [--lock <file>] -- <cmd...>   verify the lock, then run <cmd> only if it's clean
+  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)
@@ -99,16 +112,27 @@ 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);
-      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 (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) { out(`${c(C.red, '✗')} ${src}: ${e.message}`); 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;
 }
 
@@ -128,7 +152,10 @@ function runAdd() {
 }
 
 function runVerify() {
-  const { ok, results, error } = verify({ lockPath, trustPath: optTrust() });
+  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) {
@@ -137,7 +164,13 @@ function runVerify() {
     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)));
+    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;
@@ -145,7 +178,15 @@ function runVerify() {
 
 function runDiff() {
   if (!sources.length) return (usage(), 2);
-  const r = diff(sources[0], { lockPath, name: opt('--name', undefined) });
+  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)}`));
@@ -163,19 +204,43 @@ function summary(r) {
 }
 
 function runList() {
-  const lock = readLock(lockPath);
+  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} · ${e.hash.slice(0, 12)} · ${e.scannedAt.slice(0, 10)}${e.sig ? ' · signed' : ''}`)}`);
+    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() });
+  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');
@@ -251,9 +316,16 @@ 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
+    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;
 
@@ -295,8 +367,13 @@ function runHookInstall() {
   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/canon hook claude${strict ? ' --strict' : ''}`;
+    : `npx -y github:askalf/truecopy${ref} hook claude${strict ? ' --strict' : ''}`;
 
   let settings = {};
   try { settings = JSON.parse(fs.readFileSync(target, 'utf8')); }
@@ -310,7 +387,7 @@ function runHookInstall() {
   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 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);
@@ -332,7 +409,7 @@ function runHook() {
   return 2;
 }
 
-const table = { scan: runScan, add: runAdd, verify: runVerify, diff: runDiff, list: runList, guard: runGuard, key: runKey, trust: runTrust, hook: runHook };
+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/index.mjs

@@ -2,13 +2,13 @@
 // (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 { 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, readLock, writeLock, DEFAULT_LOCK };
+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';
@@ -46,6 +46,7 @@ export function pin(source, { lockPath = DEFAULT_LOCK, sign = false, force = fal
     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 } : {}),
   };
@@ -53,15 +54,36 @@ export function pin(source, { lockPath = DEFAULT_LOCK, sign = false, force = fal
   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 } = {}) {
+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 };
 }
 
@@ -70,14 +92,27 @@ function verifyOne(name, entry, trust) {
   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)) };
+  // `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) return { name, status: 'poisoned', source: entry.source, findings: s.findings };
+  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

package/src/lock.mjs

@@ -5,6 +5,19 @@ 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
@@ -15,7 +28,7 @@ export function readLock(p = DEFAULT_LOCK, { mustExist = false } = {}) {
   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: {} };
+      return emptyLock();
     }
     throw e;
   }
@@ -23,11 +36,7 @@ export function readLock(p = DEFAULT_LOCK, { mustExist = false } = {}) {
   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 };
+  return { version: 1, ...l, skills: asSkills(l.skills) };
 }
 
 export function writeLock(lock, p = DEFAULT_LOCK) {

package/src/mcp.mjs

@@ -12,49 +12,63 @@ 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 if it was VETTED in a gated
-  // tools/list. `blocked` alone is insufficient — a tool that was never gated
-  // (smuggled past tools/list, or known to the agent out-of-band) would otherwise
-  // be forwarded and executed. Only allow once we've actually seen+vetted a list.
+  // 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)) return { reply: blockReply(msg.id, name) };
-    if (state.blocked.has(name)) return { reply: blockReply(msg.id, 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), or bury tools in another reply; all must be gated, never forwarded
- *  raw. */
+ *  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 }; }
-  const isToolsResult = msg && msg.result && Array.isArray(msg.result.tools);
-  if (isToolsResult) {
-    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 { forward: JSON.stringify(msg) };
-  }
-  if (msg && msg.id != null) delete state.pending[msg.id];
-  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. */

package/src/scan.mjs

@@ -1,10 +1,40 @@
 // 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

package/src/sign.mjs

@@ -58,10 +58,16 @@ const readFile = () => { try { return JSON.parse(fs.readFileSync(keyFile(), 'utf
 /** 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. */
-export function loadKey() {
-  const env = envKey();
-  if (env) return env;                                       // CI: key from CANON_SIGNING_KEY
+ *  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()) {

package/src/trust.mjs

@@ -35,7 +35,11 @@ export function loadTrust({ trustPath, cwd = process.cwd() } = {}) {
     const id = keyId(k.publicKey);
     if (!map.has(id)) map.set(id, { id, name: k.name || id.slice(0, 12), publicKey: k.publicKey });
   };
-  const self = loadKey(); if (self) add({ name: 'self', publicKey: self.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;