@askalf/truecopy 0.10.3 → 0.10.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +159 -176
- package/package.json +1 -1
- package/src/cli.mjs +2 -0
- package/src/lock.mjs +70 -8
package/README.md
CHANGED
|
@@ -1,256 +1,239 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<img src=".github/readme/hero.jpg" alt="Own your agent skills. Vet, sign and pin before it runs. MCP servers, skills and marketplaces flow through scan, pin, verify and enforce into truecopy.lock, and a poisoned skill is stopped at scan. npm i -g @askalf/truecopy. 68,560 skills poison-scanned." width="100%">
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
[](https://www.bestpractices.dev/projects/PROJECT_ID)
|
|
7
|
-
-->
|
|
5
|
+
# truecopy
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
### The supply-chain gate for agent skills and MCP servers.
|
|
10
8
|
|
|
11
|
-
|
|
9
|
+
<p>
|
|
10
|
+
<a href="https://www.npmjs.com/package/@askalf/truecopy"><img src="https://img.shields.io/npm/v/%40askalf%2Ftruecopy?color=8b5cf6&label=npm&logo=npm" alt="npm version"></a>
|
|
11
|
+
<a href="https://github.com/marketplace/actions/truecopy-gate-your-agent-skills"><img src="https://img.shields.io/badge/marketplace-truecopy--action-8b5cf6?logo=github" alt="GitHub Marketplace: truecopy-action"></a>
|
|
12
|
+
<a href="https://github.com/askalf/truecopy/blob/watch/WATCH.md"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Faskalf%2Ftruecopy%2Fwatch%2Fbadge.json" alt="Marketplace watch: the latest daily scan of the official Claude Code plugin directory"></a>
|
|
13
|
+
<a href="https://github.com/askalf/truecopy/actions/workflows/ci.yml"><img src="https://github.com/askalf/truecopy/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
14
|
+
<a href="https://scorecard.dev/viewer/?uri=github.com/askalf/truecopy"><img src="https://api.scorecard.dev/projects/github.com/askalf/truecopy/badge" alt="OpenSSF Scorecard"></a>
|
|
15
|
+
<a href="https://www.bestpractices.dev/projects/14488"><img src="https://www.bestpractices.dev/projects/14488/badge" alt="OpenSSF Best Practices"></a>
|
|
16
|
+
<a href="https://github.com/askalf/truecopy/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/%40askalf%2Ftruecopy?label=license&color=8b5cf6" alt="MIT license"></a>
|
|
17
|
+
</p>
|
|
12
18
|
|
|
13
|
-
>
|
|
19
|
+
<sub><b>68,560 skills poison-scanned</b> · the official Claude Code plugin directory re-scanned every day · deterministic and offline · one runtime dependency · MIT</sub>
|
|
14
20
|
|
|
15
|
-
|
|
21
|
+
<sub><a href="#see-it-catch-one">See it</a> · <a href="#quick-start">Quick start</a> · <a href="#the-attack">The attack</a> · <a href="#how-it-works">How it works</a> · <a href="#what-it-gates">What it gates</a> · <a href="#in-ci">In CI</a> · <a href="#proven-at-ecosystem-scale">Proof</a> · <a href="#trust-and-transparency">Trust</a> · <a href="#docs">Docs</a></sub>
|
|
16
22
|
|
|
17
|
-
|
|
23
|
+
</div>
|
|
18
24
|
|
|
19
|
-
|
|
20
|
-
- **pins** the vetted version into a `truecopy.lock` with a content hash (and an optional signature)
|
|
21
|
-
- **verifies** on every run / in CI that nothing **drifted** — a pinned skill whose bytes changed is a silent update or a supply-chain attack, and `truecopy verify` exits non-zero before it loads
|
|
22
|
-
- **diffs** exactly what changed since you trusted it
|
|
25
|
+
---
|
|
23
26
|
|
|
24
|
-
|
|
27
|
+
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.
|
|
25
28
|
|
|
26
|
-
##
|
|
29
|
+
## See it catch one
|
|
27
30
|
|
|
28
|
-
|
|
29
|
-
npm i -g @askalf/truecopy # latest, from npm
|
|
30
|
-
npm i -g @askalf/truecopy@0.10.2 # pinned release
|
|
31
|
-
```
|
|
31
|
+
<img src=".github/readme/terminal.svg" alt="A recorded run. truecopy scan ./poisoned-mcp.json flags productivity-helpers: the summarize tool carries an instruction-override, exfiltration intent, a sensitive-path exfil instruction and a sensitive-path reference; exit 1. truecopy add ./mcp-server.json --sign pins filesystem with its hash, signed. truecopy verify prints filesystem ok, signed by self, all 1 pinned skills verified. Later, upstream ships a silent update in which one tool description gains an exfil instruction. truecopy verify prints filesystem drifted, the changed tool read_file, 1/1 FAILED; exit 1." width="100%">
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
That picture is a recording, not a mock-up. [`scripts/readme/terminal.mjs`](scripts/readme/terminal.mjs) runs each command with this checkout's CLI in a throwaway directory, against the two manifests in [`demo/`](demo/), and refuses to redraw it if any verdict or exit code changes.
|
|
34
34
|
|
|
35
35
|
## Quick start
|
|
36
36
|
|
|
37
37
|
```bash
|
|
38
|
-
|
|
39
|
-
truecopy add ./mcp-server.json --sign # vet + pin into truecopy.lock (refuses a poisoned skill)
|
|
40
|
-
truecopy verify # re-check every pinned skill for drift / poisoning (CI: exit 1 on any fail)
|
|
41
|
-
truecopy diff ./mcp-server.json # what changed since you pinned it
|
|
42
|
-
truecopy list # the pinned set
|
|
43
|
-
truecopy remove old-skill # un-pin a deprecated skill — drops its lock entry, no hand-editing (a signed lock would flag that as tampering)
|
|
44
|
-
truecopy guard -- npm start # verify the lock, then launch only if it's clean
|
|
45
|
-
truecopy add --claude --claude-plugins --sign # pin every Claude Code skill — project, user, and marketplace-plugin scope
|
|
46
|
-
truecopy hook install # …and wire the invocation-time gate into .claude/settings.json
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
```text
|
|
50
|
-
$ truecopy scan demo/poisoned-mcp.json
|
|
51
|
-
☠ productivity-helpers (mcp) flagged
|
|
52
|
-
☠ summarize: instruction-override; exfiltration intent
|
|
38
|
+
npm i -g @askalf/truecopy # Node 20 or newer
|
|
53
39
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
~summarize
|
|
58
|
-
1/1 FAILED — review above # exit 1
|
|
40
|
+
truecopy scan ./mcp-server.json # poison-scan it before you trust it
|
|
41
|
+
truecopy add ./mcp-server.json --sign # pin the vetted bytes into truecopy.lock, signed
|
|
42
|
+
truecopy verify # re-check every pin; exit 1 on drift or poison
|
|
59
43
|
```
|
|
60
44
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
## Runtime gate — enforce the lock
|
|
64
|
-
|
|
65
|
-
Scanning and pinning are *checks*. truecopy also **enforces** the lock at runtime, so an unvetted or drifted tool never reaches the agent:
|
|
66
|
-
|
|
67
|
-
**`truecopy-mcp`** — a drop-in MCP proxy. Point your MCP client at it instead of the server; only tools that are pinned, unmodified, and unpoisoned pass through `tools/list`, and calls to anything it dropped are blocked:
|
|
45
|
+
Commit `truecopy.lock` next to your code, the way you commit `package-lock.json`. Then choose where it is enforced:
|
|
68
46
|
|
|
69
47
|
```bash
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
A silently-added, drifted, or poisoned tool is stripped from `tools/list` (the agent never sees it); a call to one comes back as a normal tool error. `--strict` blocks the *entire* server if anything is off, instead of stripping the bad tools.
|
|
74
|
-
|
|
75
|
-
> **Windows / Git Bash:** MSYS auto-rewrites an argument that looks like a Unix absolute path before `truecopy` (a native node process) sees it — a bare `--lock /etc/truecopy.lock`, a scan source like `/srv/skill.json`, or the wrapped server's `/workspace` path can arrive mangled (e.g. prefixed with `C:/Program Files/Git/…`), so the lock isn't found or the wrong path is scanned. Prefix the run with `MSYS_NO_PATHCONV=1` and use drive-letter paths (`C:/…`), or run truecopy from PowerShell/cmd. Not a truecopy bug — the arg is rewritten before truecopy reads it.
|
|
48
|
+
# Claude Code: pin every skill, then check each one at the moment it is invoked
|
|
49
|
+
truecopy add --claude --claude-plugins --sign && truecopy hook install
|
|
76
50
|
|
|
77
|
-
|
|
51
|
+
# any MCP client: launch the server through the proxy; only pinned, unchanged tools get through
|
|
52
|
+
truecopy-mcp --lock truecopy.lock --name filesystem -- <server command>
|
|
78
53
|
|
|
79
|
-
|
|
80
|
-
|
|
54
|
+
# any process: refuse to launch while a pin is bad
|
|
55
|
+
truecopy guard -- npm start
|
|
81
56
|
```
|
|
82
57
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
To gate a real downstream server from the image instead, override the `ENTRYPOINT` with your own `--lock`/`--name -- <server cmd>`.
|
|
86
|
-
|
|
87
|
-
#### Standalone tools
|
|
88
|
-
|
|
89
|
-
Run `truecopy-mcp` with no downstream command (`truecopy-mcp [--lock truecopy.lock]`) and it serves two read-only tools of its own instead of gating a server:
|
|
58
|
+
No install needed for a one-off: `npx -y @askalf/truecopy verify`. In a clone, `npm run demo` plays the whole story offline.
|
|
90
59
|
|
|
91
|
-
|
|
92
|
-
|---|---|
|
|
93
|
-
| `truecopy-verify` | re-derives every pinned hash → `ok` / `drifted` / `poisoned` / `untrusted` / `unsigned` / `missing` per entry |
|
|
94
|
-
| `truecopy-status` | what this lock pins — kind, pin-time verdict, signed — without re-verifying |
|
|
95
|
-
|
|
96
|
-
Neither accepts a caller-supplied path — both operate only on the lock the process was configured with. `truecopy-scan` is deliberately **not** exposed here: findings carry the matched source text as evidence, so a scan tool taking a caller path would be an arbitrary file-content disclosure primitive.
|
|
97
|
-
|
|
98
|
-
**`truecopy guard`** — a launch gate. Verify the lock, then run a command only if it's clean:
|
|
60
|
+
## The attack
|
|
99
61
|
|
|
100
|
-
|
|
101
|
-
truecopy guard -- npm start # refuses to launch (exit 1) if any pinned skill drifted or turned poisonous
|
|
102
|
-
```
|
|
62
|
+
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:
|
|
103
63
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
64
|
+
| The attack | What it looks like | What truecopy does |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| **Tool poisoning** | A description, schema or `SKILL.md` that tells the model to *"ignore previous instructions"* and send `~/.ssh/id_rsa` somewhere. The model reads it as an instruction; you never read it at all. | `scan` flags injection and exfiltration instructions in every name, description, schema and skill file, and `add` refuses to pin a poisoned one. |
|
|
67
|
+
| **The silent update** | A server or skill you vetted last week ships new bytes. No diff you will ever read shows it, and the agent loads it on the next run. | Every pin records a content hash plus one hash per tool or file. `verify`, the hook, the proxy and `guard` re-derive them and fail on any change, naming what changed. |
|
|
68
|
+
| **The wrong signer** | Someone substitutes the lock entry, or signs a tampered version with a key of their own. | Ed25519 signatures are checked against your trust set: your machine's own key, the keys you trust globally and the `truecopy.trust` you commit. A valid signature from a key you do not trust fails closed as `untrusted`; `--require-signed` fails anything unsigned. |
|
|
109
69
|
|
|
110
|
-
|
|
70
|
+
## How it works
|
|
111
71
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
truecopy
|
|
115
|
-
truecopy
|
|
116
|
-
|
|
117
|
-
|
|
72
|
+
| Stage | Command | What happens |
|
|
73
|
+
|---|---|---|
|
|
74
|
+
| **scan** | <code>truecopy scan</code> | Deterministic poison detection over everything the model will read. Prose in skills is severity-aware: an *instruction* flags, a mere *mention* of a secret path is an advisory. Tool definitions keep the strict any-finding rule. |
|
|
75
|
+
| **pin** | <code>truecopy add</code> | The vetted version goes into `truecopy.lock`: source, content hash, per-part hashes, the verdict and detection engine version at pin time, and optionally an Ed25519 signature. |
|
|
76
|
+
| **verify** | <code>truecopy verify</code> | Every run or CI pass re-hashes and re-scans every pin. Changed bytes are `drifted`; unchanged bytes that newer detection now flags are `poisoned`. Exit 1 on any failure. |
|
|
77
|
+
| **enforce** | hook · proxy · guard | The [runtime gate](docs/runtime-gate.md) keeps an unvetted or drifted tool from reaching the agent at all: the Claude Code hook, the `truecopy-mcp` proxy, and the `guard` launch gate. |
|
|
118
78
|
|
|
119
|
-
|
|
79
|
+
A lock entry, as committed in this repo's own [`truecopy.lock`](truecopy.lock):
|
|
120
80
|
|
|
121
81
|
```json
|
|
122
|
-
{
|
|
123
|
-
"
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
82
|
+
"filesystem": {
|
|
83
|
+
"source": "demo/clean-mcp.json",
|
|
84
|
+
"kind": "mcp",
|
|
85
|
+
"hash": "a881946cef3fb45d7c78d3297070a179f4c55ba65f00a576ada922c39f4e1f57",
|
|
86
|
+
"scannedAt": "2026-07-16T17:25:56.559Z",
|
|
87
|
+
"verdict": "clean",
|
|
88
|
+
"findings": 0,
|
|
89
|
+
"detection": { "engine": "redstamp", "version": "0.4.1" },
|
|
90
|
+
"parts": {
|
|
91
|
+
"read_file": "cfe9acc21dbc05b0b8baa751e71fe524fd8fa15578d20610fc90b8d533bd8d8f",
|
|
92
|
+
"list_directory": "ac606087a4a47e23d801beb12699d87364430677f04b6709eacbaec062156227",
|
|
93
|
+
"(manifest)": "cac4676bf307456c45dfa470fa0b350b6b305b0d3cb86ffc3b68396625261b46"
|
|
128
94
|
}
|
|
129
95
|
}
|
|
130
96
|
```
|
|
131
97
|
|
|
132
|
-
|
|
98
|
+
`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.
|
|
133
99
|
|
|
134
|
-
|
|
100
|
+
<details>
|
|
101
|
+
<summary><b>Every verdict <code>verify</code> can return</b></summary>
|
|
135
102
|
|
|
136
|
-
|
|
103
|
+
<br>
|
|
104
|
+
|
|
105
|
+
| Status | Meaning | Fails? |
|
|
137
106
|
|---|---|---|
|
|
138
|
-
|
|
|
139
|
-
|
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
|
|
|
143
|
-
|
|
|
144
|
-
|
|
145
|
-
|
|
107
|
+
| `ok` | Same bytes as the pin, still scans clean (or carries findings you accepted for exactly these bytes with `--force`), and any signature is valid from a trusted key. | no |
|
|
108
|
+
| `drifted` | The bytes changed since the pin. Lists the tools or files added, removed or changed. | yes |
|
|
109
|
+
| `poisoned` | Same bytes, but they now scan poisoned: detection improved after you pinned. | yes |
|
|
110
|
+
| `untrusted` | A valid signature from a key outside your trust set. | yes |
|
|
111
|
+
| `unsigned` | An entry recorded as signed whose signature no longer checks; or, under `--require-signed`, any entry without a trusted signature. | yes |
|
|
112
|
+
| `missing` | The pinned source cannot be read. | yes |
|
|
113
|
+
|
|
114
|
+
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.
|
|
146
115
|
|
|
147
|
-
|
|
116
|
+
</details>
|
|
148
117
|
|
|
149
|
-
|
|
118
|
+
## What it gates
|
|
150
119
|
|
|
151
|
-
|
|
120
|
+
| Surface | Checked | A bad pin |
|
|
121
|
+
|---|---|---|
|
|
122
|
+
| **Claude Code skills**<br>project, user and marketplace plugins<br><code>hook install</code> | The moment a skill is invoked, against the exact directory about to run | Blocked, and the model is told the skill drifted or turned poisonous. <code>--strict</code> makes the lock a whitelist that fails closed. [More](docs/claude-code.md) |
|
|
123
|
+
| **MCP servers**<br>any client that launches stdio servers<br><code>truecopy-mcp</code> | Every <code>tools/list</code> response, and every call against it | Stripped from <code>tools/list</code>, and a call to it errors. <code>--strict</code> blocks the whole server. [More](docs/runtime-gate.md) |
|
|
124
|
+
| **Process launch**<br><code>guard -- <cmd></code> | Before the command starts | The command never starts; exit 1. |
|
|
125
|
+
| **CI**<br><code>askalf/truecopy-action@v1</code> | Every workflow run | The build fails. [In CI](#in-ci) |
|
|
126
|
+
| **Plugins already installed**<br><code>check-manifest</code> | On demand, against the daily watch | Fails when an installed skill's bytes differ from what the watch vetted, or the watch flagged it. [More](docs/watch.md) |
|
|
127
|
+
| **A marketplace before you install**<br><code>scan --marketplace</code> | On demand, against your clone | Every flagged skill is listed; exit 1. |
|
|
152
128
|
|
|
153
|
-
|
|
129
|
+
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**.
|
|
154
130
|
|
|
155
|
-
|
|
156
|
-
curl -fsSLo directory-manifest.json https://raw.githubusercontent.com/askalf/truecopy/watch/directory-manifest.json
|
|
157
|
-
truecopy check-manifest directory-manifest.json
|
|
158
|
-
```
|
|
131
|
+
## In CI
|
|
159
132
|
|
|
160
|
-
|
|
133
|
+
One line from the [GitHub Marketplace](https://github.com/marketplace/actions/truecopy-gate-your-agent-skills) verifies the committed lock and fails the build on drift or poison:
|
|
161
134
|
|
|
162
|
-
|
|
135
|
+
```yaml
|
|
136
|
+
- uses: askalf/truecopy-action@v1
|
|
137
|
+
```
|
|
163
138
|
|
|
164
|
-
|
|
139
|
+
Or scan a marketplace or manifest with no lock at all:
|
|
165
140
|
|
|
166
|
-
|
|
141
|
+
```yaml
|
|
142
|
+
- uses: askalf/truecopy-action@v1
|
|
143
|
+
with:
|
|
144
|
+
command: scan
|
|
145
|
+
marketplace: ./the-repo-you-cloned
|
|
146
|
+
```
|
|
167
147
|
|
|
168
|
-
|
|
169
|
-
|---|---|---|
|
|
170
|
-
| an **MCP manifest** (`.json` with a `tools` array) | the canonical tool set | every tool's name + description + schema |
|
|
171
|
-
| a **skill directory** (`SKILL.md` + files) | a manifest of per-file hashes | the instruction/text files |
|
|
172
|
-
| a single **file** | its bytes | its text |
|
|
148
|
+
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:
|
|
173
149
|
|
|
174
|
-
|
|
150
|
+
```yaml
|
|
151
|
+
# every pin must carry a valid signature from a key in the runner's trust set
|
|
152
|
+
- run: npx -y @askalf/truecopy verify --require-signed
|
|
175
153
|
|
|
176
|
-
|
|
154
|
+
# sign with the CI secret: no key file and no keychain on the runner
|
|
155
|
+
- run: npx -y @askalf/truecopy add ./mcp-server.json --sign
|
|
156
|
+
env:
|
|
157
|
+
CANON_SIGNING_KEY: ${{ secrets.CANON_SIGNING_KEY }}
|
|
158
|
+
```
|
|
177
159
|
|
|
178
|
-
|
|
160
|
+
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.
|
|
179
161
|
|
|
180
|
-
|
|
162
|
+
Publisher keys, the committed `truecopy.trust`, JSON reports and the signing setup: [docs/signing-and-ci.md](docs/signing-and-ci.md). This repo runs the same gate on itself in [`truecopy-gate.yml`](.github/workflows/truecopy-gate.yml).
|
|
181
163
|
|
|
182
|
-
|
|
164
|
+
## Proven at ecosystem scale
|
|
183
165
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
# consumer — trust the publisher once; every future version is then provenance-checked
|
|
190
|
-
truecopy trust add publisher.pub --name acme # add --repo to commit it to ./truecopy.trust
|
|
191
|
-
truecopy verify # ✓ filesystem ok · signed by acme
|
|
192
|
-
# # a signature from any other key → ⚠ untrusted, exit 1
|
|
193
|
-
```
|
|
166
|
+
| Corpus | Skills | Result |
|
|
167
|
+
|---|---:|---|
|
|
168
|
+
| The official Claude Code plugin directory plus nine community marketplaces | 2,019 | **0 poisoned.** Tuning detection against this corpus took the flag rate from 126 to 12 (0.6%), and every one of the 12 was benign on manual review. |
|
|
169
|
+
| ClawHub, the registry whose poisoning incident started the category | 66,541 | **0 confirmed malicious.** 813 deterministic alarms, every one benign on cross-check against ClawHub's own scanner. |
|
|
170
|
+
| The official directory, re-scanned every day | 2,471 | The 2026-10-29 run covered 315 plugins: **0 under review**, 463 advisories. The watch badge above always carries the latest run. |
|
|
194
171
|
|
|
195
|
-
|
|
172
|
+
The daily watch fetches every catalog plugin, including vendor plugins at their catalog-pinned commits, and publishes each snapshot to [`WATCH.md`](https://github.com/askalf/truecopy/blob/watch/WATCH.md) and the **[live observatory at truecopy.sprayberrylabs.com](https://truecopy.sprayberrylabs.com)**. Each run also publishes a [`directory-manifest.json`](https://github.com/askalf/truecopy/blob/watch/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.
|
|
196
173
|
|
|
197
|
-
##
|
|
174
|
+
## Trust and transparency
|
|
198
175
|
|
|
199
|
-
|
|
176
|
+
A supply-chain gate has to survive the scrutiny it applies to others.
|
|
200
177
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
178
|
+
| Promise | How it holds |
|
|
179
|
+
|---|---|
|
|
180
|
+
| **Offline** | No network calls and no telemetry. You clone or download; truecopy only reads. |
|
|
181
|
+
| **Deterministic** | No model in the loop. The same bytes get the same verdict on every machine, every time. |
|
|
182
|
+
| **One runtime dependency** | [`@askalf/redstamp`](https://github.com/askalf/redstamp), the detection engine, pinned to an exact release tarball. It has no dependencies of its own. |
|
|
183
|
+
| **Releases** | Published to npm only from CI, through trusted publishing (OIDC) with provenance. Check yours with `npm audit signatures`. |
|
|
184
|
+
| **Eats its own cooking** | This repo pins its demo manifest in its own [`truecopy.lock`](truecopy.lock) and verifies it with [truecopy-action](https://github.com/marketplace/actions/truecopy-gate-your-agent-skills) on every pull request. |
|
|
185
|
+
| **Tested** | Node 20, 22 and 24 on Linux and Node 22 on Windows, plus the packed npm tarball on both. Every row of the [Claude Code policy table](docs/claude-code.md) was also verified live, each in its own fresh Claude Code session. |
|
|
186
|
+
| **Hardened** | Jazzer.js fuzz targets for canonical JSON, the scanner and the MCP gate; CodeQL; [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/askalf/truecopy); [OpenSSF Best Practices](https://www.bestpractices.dev/projects/14488) passing. |
|
|
208
187
|
|
|
209
|
-
|
|
188
|
+
**What truecopy is not.** It is not a sandbox: once a vetted tool runs, containing what that call does is [redstamp](https://github.com/askalf/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](SECURITY.md).
|
|
210
189
|
|
|
211
|
-
>
|
|
190
|
+
<details>
|
|
191
|
+
<summary><b>FAQ</b></summary>
|
|
212
192
|
|
|
213
|
-
|
|
193
|
+
<br>
|
|
214
194
|
|
|
215
|
-
|
|
216
|
-
- run: npx -y github:askalf/truecopy verify # fails the build if any pinned skill drifted or turned poisonous
|
|
217
|
-
- 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)
|
|
218
|
-
```
|
|
195
|
+
**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.
|
|
219
196
|
|
|
220
|
-
**
|
|
197
|
+
**Does it use an LLM to judge skills?** No. Detection is deterministic, shared with [redstamp](https://github.com/askalf/redstamp), and every finding can be reproduced from the bytes.
|
|
221
198
|
|
|
222
|
-
|
|
223
|
-
- run: npx -y github:askalf/truecopy verify --require-signed # every pinned skill must be signed by a trusted publisher
|
|
224
|
-
```
|
|
199
|
+
**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](https://github.com/askalf/truecopy/issues/new?template=false-positive.yml) so detection improves for everyone.
|
|
225
200
|
|
|
226
|
-
**
|
|
201
|
+
**Can I use it from code?** Yes: `import { scan, pin, verify, diff } from '@askalf/truecopy'`. See [docs/commands.md](docs/commands.md#library).
|
|
227
202
|
|
|
228
|
-
|
|
229
|
-
- run: npx -y github:askalf/truecopy add ./mcp-server.json --sign
|
|
230
|
-
env:
|
|
231
|
-
CANON_SIGNING_KEY: ${{ secrets.CANON_SIGNING_KEY }}
|
|
232
|
-
```
|
|
203
|
+
**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.
|
|
233
204
|
|
|
234
|
-
|
|
205
|
+
**Windows?** Supported and tested. In Git Bash, MSYS rewrites Unix-looking path arguments before truecopy sees them; see the [Windows note](docs/runtime-gate.md).
|
|
235
206
|
|
|
236
|
-
|
|
207
|
+
**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.
|
|
237
208
|
|
|
238
|
-
|
|
209
|
+
</details>
|
|
239
210
|
|
|
240
|
-
|
|
241
|
-
import { scan, pin, verify, diff } from '@askalf/truecopy';
|
|
211
|
+
## Docs
|
|
242
212
|
|
|
243
|
-
|
|
244
|
-
|
|
213
|
+
| Guide | Covers |
|
|
214
|
+
|---|---|
|
|
215
|
+
| [Commands, sources and the library](docs/commands.md) | Every command, pinned installs, what you can pin, the library API |
|
|
216
|
+
| [Gate Claude Code skills](docs/claude-code.md) | `hook install`, default vs `--strict`, severity-aware verdicts, per-repo lockdown |
|
|
217
|
+
| [Runtime gate](docs/runtime-gate.md) | `truecopy-mcp`, the container and its standalone tools, `truecopy guard`, the Windows note |
|
|
218
|
+
| [Lockfile, signatures and CI](docs/signing-and-ci.md) | The lock format, publisher trust, `--require-signed`, signing in CI |
|
|
219
|
+
| [The marketplace watch](docs/watch.md) | The daily scan and `check-manifest` |
|
|
245
220
|
|
|
246
|
-
|
|
247
|
-
```
|
|
221
|
+
Also: [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)
|
|
248
222
|
|
|
249
223
|
## The agent-security stack
|
|
250
224
|
|
|
251
|
-
Three
|
|
225
|
+
Three layers, one defense, each usable on its own:
|
|
226
|
+
|
|
227
|
+
| Project | Layer | Answers |
|
|
228
|
+
|---|---|---|
|
|
229
|
+
| **[redstamp](https://github.com/askalf/redstamp)** | the call | Is *this* action safe to run right now? |
|
|
230
|
+
| **truecopy** *(you are here)* | the tool | Is this the exact skill or server I vetted? |
|
|
231
|
+
| **[plumbline](https://github.com/askalf/plumbline)** | the trajectory | Did the whole sequence of actions stay on the declared job? |
|
|
252
232
|
|
|
253
|
-
|
|
233
|
+
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.
|
|
254
234
|
|
|
255
235
|
---
|
|
256
|
-
|
|
236
|
+
|
|
237
|
+
<div align="center">
|
|
238
|
+
<sub>Part of <b><a href="https://github.com/askalf">Own Your Stack</a></b>: own your AI infrastructure instead of renting it by the token.<br>Built by Thomas Sprayberry · <a href="LICENSE">MIT</a></sub>
|
|
239
|
+
</div>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@askalf/truecopy",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.5",
|
|
4
4
|
"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.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
package/src/cli.mjs
CHANGED
|
@@ -499,6 +499,8 @@ function runHook() {
|
|
|
499
499
|
return 2;
|
|
500
500
|
}
|
|
501
501
|
|
|
502
|
+
if (cmd === '--version' || cmd === '-v' || cmd === 'version') { out(PKG_VERSION || 'unknown'); process.exit(0); }
|
|
503
|
+
|
|
502
504
|
const table = { scan: runScan, add: runAdd, remove: runRemove, unpin: runRemove, verify: runVerify, diff: runDiff, list: runList, 'check-manifest': runCheckManifest, guard: runGuard, key: runKey, trust: runTrust, hook: runHook };
|
|
503
505
|
if (!cmd || cmd === '-h' || cmd === '--help' || !table[cmd]) { usage(); process.exit(cmd && cmd !== '-h' && cmd !== '--help' ? 2 : 0); }
|
|
504
506
|
try { process.exit(table[cmd]()); }
|
package/src/lock.mjs
CHANGED
|
@@ -90,7 +90,38 @@ const GUARD_STALE_MS = 30_000; // a guard older than this belonged to a process
|
|
|
90
90
|
// would burn a core while a concurrent `add` does its work.
|
|
91
91
|
const sleepSync = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* fall through to a spin */ } };
|
|
92
92
|
|
|
93
|
-
|
|
93
|
+
// The guard's mtime, or `age: null` when it vanished between our open and this
|
|
94
|
+
// stat (ENOENT — a raced-away guard, which simply means try again).
|
|
95
|
+
//
|
|
96
|
+
// Any OTHER stat failure is reported as `error` rather than swallowed. It used
|
|
97
|
+
// to come back as null too, and that conflated two very different situations:
|
|
98
|
+
// a guard that raced away, and a lock path we cannot reach AT ALL. An
|
|
99
|
+
// inaccessible lock directory answers open(wx) with EACCES *and* stat with
|
|
100
|
+
// EACCES, so the retry loop treated a permanent denial as contention and spun
|
|
101
|
+
// on it forever — never pinning, never timing out, never saying "permission
|
|
102
|
+
// denied". acquire() decides what to do with it.
|
|
103
|
+
const guardAge = (g) => {
|
|
104
|
+
try { return { age: Date.now() - fs.statSync(g).mtimeMs }; }
|
|
105
|
+
catch (e) { return e && e.code === 'ENOENT' ? { age: null } : { error: e }; }
|
|
106
|
+
};
|
|
107
|
+
|
|
108
|
+
// "Someone else holds the guard" is EEXIST on every platform. On Windows it is
|
|
109
|
+
// ALSO EPERM (and, on some filesystems, EACCES / EBUSY) for the few
|
|
110
|
+
// microseconds a guard sits in the delete-pending state while its holder is
|
|
111
|
+
// unlinking it: `open(wx)` collides with the unlink and comes back "not
|
|
112
|
+
// permitted" instead of "exists". Measured on Windows 11 / Node 22: six
|
|
113
|
+
// processes hammering one guard saw EPERM on ~1% of attempts. Treating only
|
|
114
|
+
// EEXIST as contention made that 1% a hard failure — one of twelve concurrent
|
|
115
|
+
// `truecopy add`s exited 1 on the windows-latest CI leg while the other eleven
|
|
116
|
+
// pinned fine, and the lock was correct. The guard is not lost, it is
|
|
117
|
+
// mid-release; the right move is the same as for EEXIST: wait and retry.
|
|
118
|
+
//
|
|
119
|
+
// EPERM and EACCES are genuinely ambiguous, though: the same two codes also
|
|
120
|
+
// mean a permanent ACL or parent-directory denial. The retry loop below tells
|
|
121
|
+
// them apart by OUTCOME rather than by code — a mid-release guard clears within
|
|
122
|
+
// milliseconds, a denied path never does — so a permanent denial is bounded by
|
|
123
|
+
// the same deadline as any other wait and then thrown.
|
|
124
|
+
const GUARD_CONTENTION = new Set(['EEXIST', 'EPERM', 'EACCES', 'EBUSY']);
|
|
94
125
|
|
|
95
126
|
/** Take the guard for `p`, or throw if someone else holds it too long.
|
|
96
127
|
* `wx` is create-if-absent in ONE syscall, which is what makes this a lock and
|
|
@@ -98,21 +129,52 @@ const guardAge = (g) => { try { return Date.now() - fs.statSync(g).mtimeMs; } ca
|
|
|
98
129
|
function acquire(p, { waitMs = GUARD_WAIT_MS, staleMs = GUARD_STALE_MS } = {}) {
|
|
99
130
|
const g = GUARD(p);
|
|
100
131
|
const deadline = Date.now() + waitMs;
|
|
132
|
+
const timedOutError = () =>
|
|
133
|
+
new Error(`timed out waiting for another truecopy process to finish updating ${p} (holder: ${g}) — delete it if no truecopy is running`);
|
|
134
|
+
// The "another process holds it" timeout is only honest if a guard was ever
|
|
135
|
+
// actually there: EEXIST from open, or a stat that found the file. A
|
|
136
|
+
// read-only lock directory answers open(wx) with EPERM/EACCES and stat with
|
|
137
|
+
// ENOENT on every pass, so no guard is ever seen; at the deadline the open
|
|
138
|
+
// error itself is the answer, not a holder the operator cannot find.
|
|
139
|
+
let guardSeen = false;
|
|
140
|
+
let lastOpenError = null;
|
|
101
141
|
for (;;) {
|
|
102
142
|
try {
|
|
103
143
|
const fd = fs.openSync(g, 'wx');
|
|
104
144
|
try { fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() })); } finally { fs.closeSync(fd); }
|
|
105
145
|
return g;
|
|
106
146
|
} catch (e) {
|
|
107
|
-
if (e.code
|
|
147
|
+
if (!GUARD_CONTENTION.has(e.code)) throw e;
|
|
148
|
+
lastOpenError = e;
|
|
149
|
+
if (e.code === 'EEXIST') guardSeen = true;
|
|
108
150
|
// A process that crashed mid-update would otherwise wedge the lock file
|
|
109
151
|
// forever. Guards are held for milliseconds, so anything this old is dead.
|
|
110
|
-
const age = guardAge(g);
|
|
111
|
-
if (age
|
|
112
|
-
|
|
113
|
-
if (
|
|
114
|
-
|
|
115
|
-
|
|
152
|
+
const { age, error } = guardAge(g);
|
|
153
|
+
if (age != null) guardSeen = true;
|
|
154
|
+
const timedOut = Date.now() > deadline;
|
|
155
|
+
if (error) {
|
|
156
|
+
// Not a guard we can see. Windows can fail the stat transiently on a
|
|
157
|
+
// delete-pending guard, so this still gets the normal retry window —
|
|
158
|
+
// but when the window closes, the access error itself is the honest
|
|
159
|
+
// answer, not a "another process is holding it" timeout and certainly
|
|
160
|
+
// not an endless loop.
|
|
161
|
+
if (timedOut) throw error;
|
|
162
|
+
} else if (age === null) {
|
|
163
|
+
// No guard at stat time: either it raced away (retry) or it never
|
|
164
|
+
// existed because the directory refuses the create. Both retry after
|
|
165
|
+
// the same sleep as any other wait; retrying without one busy-loops a
|
|
166
|
+
// full core for the whole window on a read-only directory.
|
|
167
|
+
if (timedOut) throw guardSeen ? timedOutError() : lastOpenError;
|
|
168
|
+
} else if (age > staleMs) {
|
|
169
|
+
// Reaping a stale guard is the one path that can loop without ever
|
|
170
|
+
// sleeping, so it needs the same deadline as the others. A directory
|
|
171
|
+
// ACL can permit stat while denying unlink — a permanent denial then
|
|
172
|
+
// reads as "stale guard I keep failing to delete", and an
|
|
173
|
+
// unconditional `continue` would spin on it at full speed instead of
|
|
174
|
+
// eventually reporting the access error.
|
|
175
|
+
try { fs.unlinkSync(g); continue; }
|
|
176
|
+
catch (unlinkError) { if (timedOut) throw unlinkError; }
|
|
177
|
+
} else if (timedOut) throw timedOutError();
|
|
116
178
|
sleepSync(20);
|
|
117
179
|
}
|
|
118
180
|
}
|