@askalf/truecopy

The supply-chain gate for agent skills and MCP servers.

68,560 skills poison-scanned · the official Claude Code plugin directory re-scanned every day · deterministic and offline · one runtime dependency · MIT

See it · Quick start · The attack · How it works · What it gates · In CI · Proof · Trust · Docs

An agent runs its tools with your privileges, and it believes what their descriptions tell it. truecopy is the supply-chain gate in front of those tools. It poison-scans a skill or MCP server before you trust it, pins exactly the bytes you vetted into truecopy.lock (signed, if you want to know who vetted them), re-checks every pin on every run and every CI pass, and enforces the lock at runtime. A poisoned tool is refused at the door; a tool you trusted last week that quietly changed is stopped before the agent ever sees it.

See it catch one

That picture is a recording, not a mock-up. scripts/readme/terminal.mjs runs each command with this checkout's CLI in a throwaway directory, against the two manifests in demo/, and refuses to redraw it if any verdict or exit code changes.

Related MCP server: mcpsentry

Quick start

npm i -g @askalf/truecopy                  # Node 20 or newer

truecopy scan ./mcp-server.json            # poison-scan it before you trust it
truecopy add  ./mcp-server.json --sign     # pin the vetted bytes into truecopy.lock, signed
truecopy verify                            # re-check every pin; exit 1 on drift or poison

Commit truecopy.lock next to your code, the way you commit package-lock.json. Then choose where it is enforced:

# Claude Code: pin every skill, then check each one at the moment it is invoked
truecopy add --claude --claude-plugins --sign && truecopy hook install

# any MCP client: launch the server through the proxy; only pinned, unchanged tools get through
truecopy-mcp --lock truecopy.lock --name filesystem -- <server command>

# any process: refuse to launch while a pin is bad
truecopy guard -- npm start

No install needed for a one-off: npx -y @askalf/truecopy verify. In a clone, npm run demo plays the whole story offline.

The attack

Agents pull tools from places you do not control: MCP servers, skill marketplaces, a teammate's repo. OpenClaw's poisoned-skills marketplace showed what that costs. Three things go wrong, and truecopy answers each one:

How it works

A lock entry, as committed in this repo's own truecopy.lock:

"filesystem": {
  "source": "demo/clean-mcp.json",
  "kind": "mcp",
  "hash": "a881946cef3fb45d7c78d3297070a179f4c55ba65f00a576ada922c39f4e1f57",
  "scannedAt": "2026-07-16T17:25:56.559Z",
  "verdict": "clean",
  "findings": 0,
  "detection": { "engine": "redstamp", "version": "0.4.1" },
  "parts": {
    "read_file": "cfe9acc21dbc05b0b8baa751e71fe524fd8fa15578d20610fc90b8d533bd8d8f",
    "list_directory": "ac606087a4a47e23d801beb12699d87364430677f04b6709eacbaec062156227",
    "(manifest)": "cac4676bf307456c45dfa470fa0b350b6b305b0d3cb86ffc3b68396625261b46"
  }
}

parts is why a failure can name ~read_file instead of just saying something changed: one hash per tool for an MCP server, one per file for a skill, and one for the manifest's own fields, so a swapped launch command is caught too. Paths in the lock are separator-independent, so a lock committed on one OS verifies on another.

Exit codes: 0 when every pin is ok, 1 on any failure. The Claude Code hook blocks with exit 2 and tells the model why. scan, verify, list and diff take --json with the same exit codes.

What it gates

What you can pin: an MCP manifest (a .json holding the server's tools array, the shape tools/list returns; its other top-level fields, such as the launch command and args, are hashed and scanned too), a skill directory (SKILL.md plus its files, hashed per file), or any single file.

In CI

truecopy-action is the gate that fails the build on a tampered skill. One line from the GitHub Marketplace installs @askalf/truecopy, verifies the committed lock and fails the build on drift or poison:

- uses: askalf/truecopy-action@v1

Or scan a marketplace or manifest with no lock at all:

- uses: askalf/truecopy-action@v1
  with:
    command: scan
    marketplace: ./the-repo-you-cloned

Where trust matters, require a signature from a publisher you trust, and keep the one private signing key in a single CI secret instead of on every laptop:

# every pin must carry a valid signature from a key in the runner's trust set
- run: npx -y @askalf/truecopy verify --require-signed

# sign with the CI secret: no key file and no keychain on the runner
- run: npx -y @askalf/truecopy add ./mcp-server.json --sign
  env:
    CANON_SIGNING_KEY: ${{ secrets.CANON_SIGNING_KEY }}

On a workstation the trust set is your machine's own key, the keys you trust globally and the repo's truecopy.trust. A clean runner has no key and no global store, so there it is truecopy.trust alone: commit every publisher's public key to it, the public half of CANON_SIGNING_KEY included. That key signs but is never trusted just for being set.

Publisher keys, the committed truecopy.trust, JSON reports and the signing setup: docs/signing-and-ci.md.

The action is the integrity layer of the CI our own repositories share. askalf/ci is the gate layer: the reusable workflows every pull request has to pass, Redline's code review among them, and it runs truecopy-action over the tool definitions Redline's reviewer and fixer read, so a changed tool fails the build until it is re-pinned. The jobs run on pitlane, the lab where ci-wizard's method is proven: self-hosted runners whose start and run times are measured on every job and published live on the lab page, the CI measured badge above. This repo passes the same layers on every pull request and runs the gate on itself in truecopy-gate.yml.

Proven at ecosystem scale

The daily watch fetches every catalog plugin, including vendor plugins at their catalog-pinned commits, and publishes each snapshot to WATCH.md and the live observatory at truecopy.sprayberrylabs.com. Each run also publishes a directory-manifest.json of the exact bytes it vetted, so truecopy check-manifest can hold the plugins on your own machine to the same standard.

Trust and transparency

A supply-chain gate has to survive the scrutiny it applies to others.

What truecopy is not. It is not a sandbox: once a vetted tool runs, containing what that call does is redstamp's job. A clean scan means no known poisoning shape was found, not that a tool is safe; the pin is what makes your review last. For an MCP server, truecopy pins the surface the model reads (tool names, descriptions and schemas, plus any manifest fields you include, such as the launch command), not the server's code, so pin the server's own version with your package manager as well. Found a gap? Report it privately.

Does it send anything anywhere? No. There is no network code in the CLI. Even the daily watch manifest is something you download yourself and point truecopy at.

Does it use an LLM to judge skills? No. Detection is deterministic, shared with redstamp, and every finding can be reproduced from the bytes.

What about a false positive? Read the skill, then pin it with --force: the findings are recorded as accepted for exactly those bytes, shown as · accepted findings (--force pin), and any change re-flags it. Please also report it so detection improves for everyone.

Can I use it from code? Yes: import { scan, pin, verify, diff } from '@askalf/truecopy'. See docs/commands.md.

Remote (HTTP) MCP servers? truecopy-mcp gates stdio servers. For a remote server, pin a manifest of its tools/list and verify it in CI.

Windows? Supported and tested. In Git Bash, MSYS rewrites Unix-looking path arguments before truecopy sees them; see the Windows note.

Why is the signing key variable called CANON_SIGNING_KEY? truecopy was called canon before its npm release. The repo redirects, the canon and canon-mcp commands still work, an existing canon.lock or canon.trust is read automatically, and the CANON_* environment variables keep their names so existing setups keep working.

Docs

Also: Changelog · Contributing · Security policy

The agent-security stack

Three layers, one defense, each usable on its own:

truecopy and redstamp share one detection engine, so they are a pair, not a duplicate: truecopy vets the tool, redstamp contains the call. plumbline watches from above, out of band and read-only, and catches an escape assembled from steps that were each allowed.