@askalf/truecopy 0.10.4 → 0.10.6
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 +196 -65
- package/package.json +1 -1
- package/src/cli.mjs +2 -0
- package/src/lock.mjs +15 -2
package/README.md
CHANGED
|
@@ -1,111 +1,242 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
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." width="100%">
|
|
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
|
-
# truecopy
|
|
5
|
+
# @askalf/truecopy
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
### The supply-chain gate for agent skills and MCP servers.
|
|
8
8
|
|
|
9
|
-
|
|
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://pitlane.askalf.org/"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fpitlane.askalf.org%2Fbadge.json" alt="CI measured"></a>
|
|
15
|
+
<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>
|
|
16
|
+
<a href="https://www.bestpractices.dev/projects/14488"><img src="https://www.bestpractices.dev/projects/14488/badge" alt="OpenSSF Best Practices"></a>
|
|
17
|
+
<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>
|
|
18
|
+
</p>
|
|
10
19
|
|
|
11
|
-
|
|
20
|
+
<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>
|
|
12
21
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
**68,560 skills poison-scanned**: the official Claude Code plugin directory, nine community marketplaces and all of ClawHub.<br>
|
|
16
|
-
The official directory is [re-scanned every day](#proven-at-ecosystem-scale); the watch badge above is the live result.
|
|
17
|
-
|
|
18
|
-
[Quick start](#quick-start) · [The observatory](#proven-at-ecosystem-scale) · [What it gates](#what-it-gates) · [In CI](#in-ci) · [Reference](#reference)
|
|
22
|
+
<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>
|
|
19
23
|
|
|
20
24
|
</div>
|
|
21
25
|
|
|
22
26
|
---
|
|
23
27
|
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
## See it catch one
|
|
31
|
+
|
|
32
|
+
<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%">
|
|
33
|
+
|
|
34
|
+
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.
|
|
35
|
+
|
|
24
36
|
## Quick start
|
|
25
37
|
|
|
26
38
|
```bash
|
|
27
|
-
npm i -g @askalf/truecopy
|
|
28
|
-
truecopy add ./mcp-server.json --sign # vet + pin into truecopy.lock (refuses a poisoned skill)
|
|
29
|
-
truecopy verify # re-check every pin for drift / poisoning (CI: exit 1 on any fail)
|
|
30
|
-
```
|
|
39
|
+
npm i -g @askalf/truecopy # Node 20 or newer
|
|
31
40
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
☠ summarize: instruction-override; exfiltration intent
|
|
36
|
-
|
|
37
|
-
$ truecopy verify
|
|
38
|
-
⚠ filesystem drifted
|
|
39
|
-
was 8f3a1c0b9e22 → now d41d8cd98f00
|
|
40
|
-
~summarize
|
|
41
|
-
1/1 FAILED — review above # exit 1
|
|
41
|
+
truecopy scan ./mcp-server.json # poison-scan it before you trust it
|
|
42
|
+
truecopy add ./mcp-server.json --sign # pin the vetted bytes into truecopy.lock, signed
|
|
43
|
+
truecopy verify # re-check every pin; exit 1 on drift or poison
|
|
42
44
|
```
|
|
43
45
|
|
|
44
|
-
|
|
46
|
+
Commit `truecopy.lock` next to your code, the way you commit `package-lock.json`. Then choose where it is enforced:
|
|
45
47
|
|
|
46
|
-
|
|
48
|
+
```bash
|
|
49
|
+
# Claude Code: pin every skill, then check each one at the moment it is invoked
|
|
50
|
+
truecopy add --claude --claude-plugins --sign && truecopy hook install
|
|
47
51
|
|
|
48
|
-
|
|
52
|
+
# any MCP client: launch the server through the proxy; only pinned, unchanged tools get through
|
|
53
|
+
truecopy-mcp --lock truecopy.lock --name filesystem -- <server command>
|
|
49
54
|
|
|
50
|
-
|
|
55
|
+
# any process: refuse to launch while a pin is bad
|
|
56
|
+
truecopy guard -- npm start
|
|
57
|
+
```
|
|
51
58
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
59
|
+
No install needed for a one-off: `npx -y @askalf/truecopy verify`. In a clone, `npm run demo` plays the whole story offline.
|
|
60
|
+
|
|
61
|
+
## The attack
|
|
62
|
+
|
|
63
|
+
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:
|
|
64
|
+
|
|
65
|
+
| The attack | What it looks like | What truecopy does |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| **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. |
|
|
68
|
+
| **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. |
|
|
69
|
+
| **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. |
|
|
70
|
+
|
|
71
|
+
## How it works
|
|
72
|
+
|
|
73
|
+
| Stage | Command | What happens |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| **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. |
|
|
76
|
+
| **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. |
|
|
77
|
+
| **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. |
|
|
78
|
+
| **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. |
|
|
79
|
+
|
|
80
|
+
A lock entry, as committed in this repo's own [`truecopy.lock`](truecopy.lock):
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
"filesystem": {
|
|
84
|
+
"source": "demo/clean-mcp.json",
|
|
85
|
+
"kind": "mcp",
|
|
86
|
+
"hash": "a881946cef3fb45d7c78d3297070a179f4c55ba65f00a576ada922c39f4e1f57",
|
|
87
|
+
"scannedAt": "2026-07-16T17:25:56.559Z",
|
|
88
|
+
"verdict": "clean",
|
|
89
|
+
"findings": 0,
|
|
90
|
+
"detection": { "engine": "redstamp", "version": "0.4.1" },
|
|
91
|
+
"parts": {
|
|
92
|
+
"read_file": "cfe9acc21dbc05b0b8baa751e71fe524fd8fa15578d20610fc90b8d533bd8d8f",
|
|
93
|
+
"list_directory": "ac606087a4a47e23d801beb12699d87364430677f04b6709eacbaec062156227",
|
|
94
|
+
"(manifest)": "cac4676bf307456c45dfa470fa0b350b6b305b0d3cb86ffc3b68396625261b46"
|
|
95
|
+
}
|
|
96
|
+
}
|
|
67
97
|
```
|
|
68
98
|
|
|
69
|
-
|
|
99
|
+
`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.
|
|
70
100
|
|
|
71
|
-
|
|
101
|
+
<details>
|
|
102
|
+
<summary><b>Every verdict <code>verify</code> can return</b></summary>
|
|
103
|
+
|
|
104
|
+
<br>
|
|
72
105
|
|
|
73
|
-
|
|
106
|
+
| Status | Meaning | Fails? |
|
|
107
|
+
|---|---|---|
|
|
108
|
+
| `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 |
|
|
109
|
+
| `drifted` | The bytes changed since the pin. Lists the tools or files added, removed or changed. | yes |
|
|
110
|
+
| `poisoned` | Same bytes, but they now scan poisoned: detection improved after you pinned. | yes |
|
|
111
|
+
| `untrusted` | A valid signature from a key outside your trust set. | yes |
|
|
112
|
+
| `unsigned` | An entry recorded as signed whose signature no longer checks; or, under `--require-signed`, any entry without a trusted signature. | yes |
|
|
113
|
+
| `missing` | The pinned source cannot be read. | yes |
|
|
74
114
|
|
|
75
|
-
|
|
115
|
+
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.
|
|
116
|
+
|
|
117
|
+
</details>
|
|
76
118
|
|
|
77
119
|
## What it gates
|
|
78
120
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
121
|
+
| Surface | Checked | A bad pin |
|
|
122
|
+
|---|---|---|
|
|
123
|
+
| **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) |
|
|
124
|
+
| **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) |
|
|
125
|
+
| **Process launch**<br><code>guard -- <cmd></code> | Before the command starts | The command never starts; exit 1. |
|
|
126
|
+
| **CI**<br><code>askalf/truecopy-action@v1</code> | Every workflow run | The build fails. [In CI](#in-ci) |
|
|
127
|
+
| **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) |
|
|
128
|
+
| **A marketplace before you install**<br><code>scan --marketplace</code> | On demand, against your clone | Every flagged skill is listed; exit 1. |
|
|
129
|
+
|
|
130
|
+
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**.
|
|
83
131
|
|
|
84
132
|
## In CI
|
|
85
133
|
|
|
86
|
-
One line
|
|
134
|
+
[truecopy-action](https://github.com/askalf/truecopy-action) is the gate that fails the build on a tampered skill. One line from the [GitHub Marketplace](https://github.com/marketplace/actions/truecopy-gate-your-agent-skills) installs `@askalf/truecopy`, verifies the committed lock and fails the build on drift or poison:
|
|
135
|
+
|
|
136
|
+
```yaml
|
|
137
|
+
- uses: askalf/truecopy-action@v1
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Or scan a marketplace or manifest with no lock at all:
|
|
87
141
|
|
|
88
142
|
```yaml
|
|
89
|
-
- uses: askalf/truecopy-action@v1
|
|
143
|
+
- uses: askalf/truecopy-action@v1
|
|
144
|
+
with:
|
|
145
|
+
command: scan
|
|
146
|
+
marketplace: ./the-repo-you-cloned
|
|
90
147
|
```
|
|
91
148
|
|
|
92
|
-
|
|
149
|
+
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:
|
|
150
|
+
|
|
151
|
+
```yaml
|
|
152
|
+
# every pin must carry a valid signature from a key in the runner's trust set
|
|
153
|
+
- run: npx -y @askalf/truecopy verify --require-signed
|
|
154
|
+
|
|
155
|
+
# sign with the CI secret: no key file and no keychain on the runner
|
|
156
|
+
- run: npx -y @askalf/truecopy add ./mcp-server.json --sign
|
|
157
|
+
env:
|
|
158
|
+
CANON_SIGNING_KEY: ${{ secrets.CANON_SIGNING_KEY }}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
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.
|
|
162
|
+
|
|
163
|
+
Publisher keys, the committed `truecopy.trust`, JSON reports and the signing setup: [docs/signing-and-ci.md](docs/signing-and-ci.md).
|
|
93
164
|
|
|
94
|
-
|
|
165
|
+
The action is the integrity layer of the CI our own repositories share. [askalf/ci](https://github.com/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](https://github.com/askalf/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](https://pitlane.askalf.org/), 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`](.github/workflows/truecopy-gate.yml).
|
|
95
166
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
167
|
+
## Proven at ecosystem scale
|
|
168
|
+
|
|
169
|
+
| Corpus | Skills | Result |
|
|
170
|
+
|---|---:|---|
|
|
171
|
+
| 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. |
|
|
172
|
+
| 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. |
|
|
173
|
+
| 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. |
|
|
174
|
+
|
|
175
|
+
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). 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.
|
|
176
|
+
|
|
177
|
+
## Trust and transparency
|
|
178
|
+
|
|
179
|
+
A supply-chain gate has to survive the scrutiny it applies to others.
|
|
180
|
+
|
|
181
|
+
| Promise | How it holds |
|
|
182
|
+
|---|---|
|
|
183
|
+
| **Offline** | No network calls and no telemetry. You clone or download; truecopy only reads. |
|
|
184
|
+
| **Deterministic** | No model in the loop. The same bytes get the same verdict on every machine, every time. |
|
|
185
|
+
| **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. |
|
|
186
|
+
| **Releases** | `@askalf/truecopy` is published to npm only from CI, through trusted publishing (OIDC) with provenance. Check yours with `npm audit signatures`. |
|
|
187
|
+
| **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. |
|
|
188
|
+
| **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. |
|
|
189
|
+
| **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. |
|
|
190
|
+
|
|
191
|
+
**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).
|
|
192
|
+
|
|
193
|
+
<details>
|
|
194
|
+
<summary><b>FAQ</b></summary>
|
|
195
|
+
|
|
196
|
+
<br>
|
|
197
|
+
|
|
198
|
+
**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.
|
|
199
|
+
|
|
200
|
+
**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.
|
|
201
|
+
|
|
202
|
+
**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.
|
|
101
203
|
|
|
102
|
-
|
|
204
|
+
**Can I use it from code?** Yes: `import { scan, pin, verify, diff } from '@askalf/truecopy'`. See [docs/commands.md](docs/commands.md#library).
|
|
205
|
+
|
|
206
|
+
**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.
|
|
207
|
+
|
|
208
|
+
**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).
|
|
209
|
+
|
|
210
|
+
**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.
|
|
211
|
+
|
|
212
|
+
</details>
|
|
213
|
+
|
|
214
|
+
## Docs
|
|
215
|
+
|
|
216
|
+
| Guide | Covers |
|
|
217
|
+
|---|---|
|
|
218
|
+
| [Commands, sources and the library](docs/commands.md) | Every command, pinned installs, what you can pin, the library API |
|
|
219
|
+
| [Gate Claude Code skills](docs/claude-code.md) | `hook install`, default vs `--strict`, severity-aware verdicts, per-repo lockdown |
|
|
220
|
+
| [Runtime gate](docs/runtime-gate.md) | `truecopy-mcp`, the container and its standalone tools, `truecopy guard`, the Windows note |
|
|
221
|
+
| [Lockfile, signatures and CI](docs/signing-and-ci.md) | The lock format, publisher trust, `--require-signed`, signing in CI |
|
|
222
|
+
| [The marketplace watch](docs/watch.md) | The daily scan and `check-manifest` |
|
|
223
|
+
|
|
224
|
+
Also: [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)
|
|
103
225
|
|
|
104
226
|
## The agent-security stack
|
|
105
227
|
|
|
106
|
-
Three
|
|
228
|
+
Three layers, one defense, each usable on its own:
|
|
229
|
+
|
|
230
|
+
| Project | Layer | Answers |
|
|
231
|
+
|---|---|---|
|
|
232
|
+
| **[redstamp](https://github.com/askalf/redstamp)** | the call | Is *this* action safe to run right now? |
|
|
233
|
+
| **truecopy** *(you are here)* | the tool | Is this the exact skill or server I vetted? |
|
|
234
|
+
| **[plumbline](https://github.com/askalf/plumbline)** | the trajectory | Did the whole sequence of actions stay on the declared job? |
|
|
107
235
|
|
|
108
|
-
|
|
236
|
+
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.
|
|
109
237
|
|
|
110
238
|
---
|
|
111
|
-
|
|
239
|
+
|
|
240
|
+
<div align="center">
|
|
241
|
+
<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>
|
|
242
|
+
</div>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@askalf/truecopy",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.6",
|
|
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
|
@@ -131,6 +131,13 @@ function acquire(p, { waitMs = GUARD_WAIT_MS, staleMs = GUARD_STALE_MS } = {}) {
|
|
|
131
131
|
const deadline = Date.now() + waitMs;
|
|
132
132
|
const timedOutError = () =>
|
|
133
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;
|
|
134
141
|
for (;;) {
|
|
135
142
|
try {
|
|
136
143
|
const fd = fs.openSync(g, 'wx');
|
|
@@ -138,9 +145,12 @@ function acquire(p, { waitMs = GUARD_WAIT_MS, staleMs = GUARD_STALE_MS } = {}) {
|
|
|
138
145
|
return g;
|
|
139
146
|
} catch (e) {
|
|
140
147
|
if (!GUARD_CONTENTION.has(e.code)) throw e;
|
|
148
|
+
lastOpenError = e;
|
|
149
|
+
if (e.code === 'EEXIST') guardSeen = true;
|
|
141
150
|
// A process that crashed mid-update would otherwise wedge the lock file
|
|
142
151
|
// forever. Guards are held for milliseconds, so anything this old is dead.
|
|
143
152
|
const { age, error } = guardAge(g);
|
|
153
|
+
if (age != null) guardSeen = true;
|
|
144
154
|
const timedOut = Date.now() > deadline;
|
|
145
155
|
if (error) {
|
|
146
156
|
// Not a guard we can see. Windows can fail the stat transiently on a
|
|
@@ -150,8 +160,11 @@ function acquire(p, { waitMs = GUARD_WAIT_MS, staleMs = GUARD_STALE_MS } = {}) {
|
|
|
150
160
|
// not an endless loop.
|
|
151
161
|
if (timedOut) throw error;
|
|
152
162
|
} else if (age === null) {
|
|
153
|
-
|
|
154
|
-
|
|
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;
|
|
155
168
|
} else if (age > staleMs) {
|
|
156
169
|
// Reaping a stale guard is the one path that can loop without ever
|
|
157
170
|
// sleeping, so it needs the same deadline as the others. A directory
|