sigild 0.0.11 → 0.0.13
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 +43 -13
- package/SECURITY.md +69 -0
- package/THREAT_MODEL.md +5 -3
- package/dist/src/audit/index.d.ts +2 -1
- package/dist/src/audit/index.d.ts.map +1 -1
- package/dist/src/audit/index.js +1 -0
- package/dist/src/audit/index.js.map +1 -1
- package/dist/src/audit/log.d.ts +37 -3
- package/dist/src/audit/log.d.ts.map +1 -1
- package/dist/src/audit/log.js +227 -41
- package/dist/src/audit/log.js.map +1 -1
- package/dist/src/bin/sigil-mcp.js +23 -6
- package/dist/src/bin/sigil-mcp.js.map +1 -1
- package/dist/src/cli/args.d.ts.map +1 -1
- package/dist/src/cli/args.js.map +1 -1
- package/dist/src/cli/index.d.ts +1 -1
- package/dist/src/cli/index.d.ts.map +1 -1
- package/dist/src/cli/index.js +1 -1
- package/dist/src/cli/index.js.map +1 -1
- package/dist/src/cli/main.d.ts.map +1 -1
- package/dist/src/cli/main.js +76 -4
- package/dist/src/cli/main.js.map +1 -1
- package/dist/src/cli/paths.d.ts +2 -0
- package/dist/src/cli/paths.d.ts.map +1 -1
- package/dist/src/cli/paths.js +1 -0
- package/dist/src/cli/paths.js.map +1 -1
- package/dist/src/cli/portal.d.ts.map +1 -1
- package/dist/src/cli/portal.js +17 -3
- package/dist/src/cli/portal.js.map +1 -1
- package/dist/src/cli/rpc.d.ts +24 -0
- package/dist/src/cli/rpc.d.ts.map +1 -0
- package/dist/src/cli/rpc.js +68 -0
- package/dist/src/cli/rpc.js.map +1 -0
- package/dist/src/cli/status.d.ts.map +1 -1
- package/dist/src/cli/status.js +1 -1
- package/dist/src/cli/status.js.map +1 -1
- package/dist/src/cli/unlock.d.ts.map +1 -1
- package/dist/src/cli/unlock.js +1 -1
- package/dist/src/cli/unlock.js.map +1 -1
- package/dist/src/confirm/config.d.ts.map +1 -1
- package/dist/src/confirm/config.js.map +1 -1
- package/dist/src/confirm/index.d.ts +2 -2
- package/dist/src/confirm/index.d.ts.map +1 -1
- package/dist/src/confirm/index.js +1 -1
- package/dist/src/confirm/index.js.map +1 -1
- package/dist/src/confirm/ntfy.d.ts.map +1 -1
- package/dist/src/confirm/ntfy.js +5 -5
- package/dist/src/confirm/ntfy.js.map +1 -1
- package/dist/src/control/broadcast.d.ts.map +1 -1
- package/dist/src/control/broadcast.js +7 -4
- package/dist/src/control/broadcast.js.map +1 -1
- package/dist/src/control/client.d.ts.map +1 -1
- package/dist/src/control/client.js +5 -2
- package/dist/src/control/client.js.map +1 -1
- package/dist/src/control/protocol.d.ts.map +1 -1
- package/dist/src/control/protocol.js.map +1 -1
- package/dist/src/control/server.d.ts.map +1 -1
- package/dist/src/control/server.js +17 -4
- package/dist/src/control/server.js.map +1 -1
- package/dist/src/crypto/aead.d.ts.map +1 -1
- package/dist/src/crypto/aead.js.map +1 -1
- package/dist/src/crypto/index.d.ts +1 -1
- package/dist/src/crypto/index.d.ts.map +1 -1
- package/dist/src/crypto/index.js +1 -1
- package/dist/src/crypto/index.js.map +1 -1
- package/dist/src/crypto/keyfile.d.ts.map +1 -1
- package/dist/src/crypto/keyfile.js +1 -0
- package/dist/src/crypto/keyfile.js.map +1 -1
- package/dist/src/daemon/handles.d.ts.map +1 -1
- package/dist/src/daemon/handles.js +1 -1
- package/dist/src/daemon/handles.js.map +1 -1
- package/dist/src/daemon/index.d.ts +1 -1
- package/dist/src/daemon/index.d.ts.map +1 -1
- package/dist/src/daemon/index.js +1 -1
- package/dist/src/daemon/index.js.map +1 -1
- package/dist/src/daemon/methods.d.ts +8 -1
- package/dist/src/daemon/methods.d.ts.map +1 -1
- package/dist/src/daemon/methods.js +133 -13
- package/dist/src/daemon/methods.js.map +1 -1
- package/dist/src/daemon/passphrase.d.ts.map +1 -1
- package/dist/src/daemon/passphrase.js.map +1 -1
- package/dist/src/eth/address.d.ts.map +1 -1
- package/dist/src/eth/address.js +1 -1
- package/dist/src/eth/address.js.map +1 -1
- package/dist/src/eth/index.d.ts +2 -2
- package/dist/src/eth/index.d.ts.map +1 -1
- package/dist/src/eth/index.js +2 -2
- package/dist/src/eth/index.js.map +1 -1
- package/dist/src/eth/rlp.js +1 -1
- package/dist/src/eth/rlp.js.map +1 -1
- package/dist/src/eth/secp.d.ts.map +1 -1
- package/dist/src/eth/secp.js.map +1 -1
- package/dist/src/eth/sign-message.d.ts.map +1 -1
- package/dist/src/eth/sign-message.js.map +1 -1
- package/dist/src/eth/sign-tx.d.ts.map +1 -1
- package/dist/src/eth/sign-tx.js +13 -4
- package/dist/src/eth/sign-tx.js.map +1 -1
- package/dist/src/eth/sign-typed.d.ts.map +1 -1
- package/dist/src/eth/sign-typed.js.map +1 -1
- package/dist/src/fs/index.d.ts +2 -0
- package/dist/src/fs/index.d.ts.map +1 -0
- package/dist/src/fs/index.js +2 -0
- package/dist/src/fs/index.js.map +1 -0
- package/dist/src/fs/lock.d.ts +84 -0
- package/dist/src/fs/lock.d.ts.map +1 -0
- package/dist/src/fs/lock.js +329 -0
- package/dist/src/fs/lock.js.map +1 -0
- package/dist/src/hooks/bip39-wordlist.d.ts +12 -0
- package/dist/src/hooks/bip39-wordlist.d.ts.map +1 -0
- package/dist/src/hooks/bip39-wordlist.js +2061 -0
- package/dist/src/hooks/bip39-wordlist.js.map +1 -0
- package/dist/src/hooks/bip39.d.ts +19 -0
- package/dist/src/hooks/bip39.d.ts.map +1 -0
- package/dist/src/hooks/bip39.js +101 -0
- package/dist/src/hooks/bip39.js.map +1 -0
- package/dist/src/hooks/command-scanner.d.ts.map +1 -1
- package/dist/src/hooks/command-scanner.js +45 -9
- package/dist/src/hooks/command-scanner.js.map +1 -1
- package/dist/src/hooks/index.d.ts +1 -1
- package/dist/src/hooks/index.d.ts.map +1 -1
- package/dist/src/hooks/index.js +1 -1
- package/dist/src/hooks/index.js.map +1 -1
- package/dist/src/hooks/install.js +1 -1
- package/dist/src/hooks/install.js.map +1 -1
- package/dist/src/hooks/protocol.d.ts.map +1 -1
- package/dist/src/hooks/protocol.js +1 -1
- package/dist/src/hooks/protocol.js.map +1 -1
- package/dist/src/hooks/redactor.d.ts +10 -1
- package/dist/src/hooks/redactor.d.ts.map +1 -1
- package/dist/src/hooks/redactor.js +34 -3
- package/dist/src/hooks/redactor.js.map +1 -1
- package/dist/src/mcp/protocol.d.ts.map +1 -1
- package/dist/src/mcp/protocol.js +5 -1
- package/dist/src/mcp/protocol.js.map +1 -1
- package/dist/src/mcp/tools.d.ts.map +1 -1
- package/dist/src/mcp/tools.js +6 -3
- package/dist/src/mcp/tools.js.map +1 -1
- package/dist/src/policy/evaluate.d.ts.map +1 -1
- package/dist/src/policy/evaluate.js +71 -6
- package/dist/src/policy/evaluate.js.map +1 -1
- package/dist/src/policy/index.d.ts +3 -1
- package/dist/src/policy/index.d.ts.map +1 -1
- package/dist/src/policy/index.js +3 -1
- package/dist/src/policy/index.js.map +1 -1
- package/dist/src/policy/ledger.d.ts +83 -0
- package/dist/src/policy/ledger.d.ts.map +1 -0
- package/dist/src/policy/ledger.js +250 -0
- package/dist/src/policy/ledger.js.map +1 -0
- package/dist/src/policy/loader.d.ts.map +1 -1
- package/dist/src/policy/loader.js +45 -0
- package/dist/src/policy/loader.js.map +1 -1
- package/dist/src/policy/template.d.ts +2 -2
- package/dist/src/policy/template.d.ts.map +1 -1
- package/dist/src/policy/template.js +32 -0
- package/dist/src/policy/template.js.map +1 -1
- package/dist/src/policy/types.d.ts +26 -0
- package/dist/src/policy/types.d.ts.map +1 -1
- package/dist/src/policy/types.js.map +1 -1
- package/dist/src/policy/window.d.ts +22 -0
- package/dist/src/policy/window.d.ts.map +1 -0
- package/dist/src/policy/window.js +66 -0
- package/dist/src/policy/window.js.map +1 -0
- package/dist/src/qr/encode.d.ts +10 -1
- package/dist/src/qr/encode.d.ts.map +1 -1
- package/dist/src/qr/encode.js +2 -2
- package/dist/src/qr/encode.js.map +1 -1
- package/dist/src/qr/index.d.ts +1 -1
- package/dist/src/qr/index.d.ts.map +1 -1
- package/dist/src/qr/index.js.map +1 -1
- package/dist/src/rpc/fill.d.ts.map +1 -1
- package/dist/src/rpc/fill.js.map +1 -1
- package/dist/src/rpc/server.d.ts.map +1 -1
- package/dist/src/rpc/server.js +4 -2
- package/dist/src/rpc/server.js.map +1 -1
- package/dist/src/rpc/upstream.d.ts.map +1 -1
- package/dist/src/rpc/upstream.js.map +1 -1
- package/dist/src/svm/transaction.d.ts.map +1 -1
- package/dist/src/svm/transaction.js +13 -4
- package/dist/src/svm/transaction.js.map +1 -1
- package/package.json +16 -7
package/README.md
CHANGED
|
@@ -4,14 +4,14 @@
|
|
|
4
4
|
|
|
5
5
|
`sigil` is a local signing tool and Claude Code integration that lets agentic coding tools use private keys without ever putting key material in the model's context window.
|
|
6
6
|
|
|
7
|
-
**Status:** pre-alpha. The MCP server, CLI, unlock flow, ward hooks, policy engine (static checks),
|
|
7
|
+
**Status:** pre-alpha. The MCP server, CLI, unlock flow, ward hooks, policy engine (static checks), out-of-band confirmation via ntfy, Solana signing, and the JSON-RPC signing proxy (Foundry/Hardhat) all work end-to-end. Rolling-window value caps and EIP-712 domain allowlists landed in the policy engine, but have not been through a release yet. Until v0.1.0 ships — with the supply-chain attestations promised for it — **do not use this with real funds yet.** Build plan lives in the [tracking issue](https://github.com/cdrn/sigil/issues/9).
|
|
8
8
|
|
|
9
9
|
## What it is
|
|
10
10
|
|
|
11
|
-
One MCP server process, four bins, six runtime deps (all pinned, zero transitive):
|
|
11
|
+
One MCP server process, four bins (plus a legacy `sigild` alias), six runtime deps (all pinned, zero transitive):
|
|
12
12
|
|
|
13
13
|
1. **`sigil-mcp`** — the only thing that runs. Claude Code spawns it per session via your `mcpServers` config; it dies when Claude exits. Holds unlocked keys in process memory (zeroized on shutdown, `sigil lock`, or unlock-failure; mlock against swap is planned). Keys at rest are encrypted with XChaCha20-Poly1305 and an Argon2id-derived key. Signs over stdio using a DIY MCP wire protocol (~200 lines, no SDK dep). Claude never sees key material — only opaque handles like `evm:executor`.
|
|
14
|
-
2. **`sigil`** — control CLI. `init`, `status`, `portal add`/`list`/`remove`, `unlock`, `lock`.
|
|
14
|
+
2. **`sigil`** — control CLI. `init`, `status`, `portal new`/`add`/`list`/`qr`/`remove`, `policy show`/`init`, `unlock`, `lock`.
|
|
15
15
|
3. **`sigil-hook-pre` / `sigil-hook-post`** — Claude Code hook binaries that block reads of common key paths and redact key-shaped strings from tool output.
|
|
16
16
|
|
|
17
17
|
`sigil-mcp` boots **locked**: empty in-memory handle table, no keys loaded. Sign methods return `DAEMON_LOCKED` (-32003) with a "run sigil unlock" message until you push the passphrase in from a separate terminal via `sigil unlock`. That CLI connects to a per-session Unix socket at `~/.sigil/control/<pid>.sock` (0600) that `sigil-mcp` opens at startup — and fans out to every such socket so one `sigil unlock` reaches all open windows. After unlock, signs work for the rest of the session; `sigil lock` zeroizes the table without killing the process.
|
|
@@ -22,7 +22,7 @@ Sign methods exposed today: EIP-191 personal_sign, EIP-1559 + legacy transaction
|
|
|
22
22
|
|
|
23
23
|
- Not a hardware wallet replacement. If you can use a Ledger or YubiKey, do that.
|
|
24
24
|
- Not a custody solution. It runs on your laptop or VPS and protects you from one specific class of failure: leaking key material through an LLM agent.
|
|
25
|
-
- A first cut of *bounding signing authority* via the policy engine — but not the full thing.
|
|
25
|
+
- A first cut of *bounding signing authority* via the policy engine — but not the full thing. Shipped: static checks (chain ID, destination allowlist, per-tx value cap, function-selector allowlist, contract-creation gating, on/off toggles for personal_sign and EIP-712) plus out-of-band human confirmation via ntfy. Rolling-window caps and EIP-712 domain allowlists are tracked in [#3](https://github.com/cdrn/sigil/issues/3) and will land incrementally.
|
|
26
26
|
|
|
27
27
|
## Install
|
|
28
28
|
|
|
@@ -30,9 +30,9 @@ Sign methods exposed today: EIP-191 personal_sign, EIP-1559 + legacy transaction
|
|
|
30
30
|
npm install -g sigild
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
This drops four binaries on your `$PATH`: `sigil`, `sigil-mcp`, `sigil-hook-pre`, `sigil-hook-post
|
|
33
|
+
This drops four binaries on your `$PATH`: `sigil`, `sigil-mcp`, `sigil-hook-pre`, `sigil-hook-post` (plus `sigild`, a legacy alias for `sigil-mcp`). (The package name on npm is `sigild` for legacy reasons; the bins do not include a daemon any more.)
|
|
34
34
|
|
|
35
|
-
Requires Node 22
|
|
35
|
+
Requires Node 22+, macOS or Linux. (The CLI ↔ session control channel uses Unix domain sockets; Windows is untested and currently unsupported.)
|
|
36
36
|
|
|
37
37
|
## Quick start
|
|
38
38
|
|
|
@@ -92,7 +92,7 @@ sigil portal new <handle> [--strict]
|
|
|
92
92
|
sigil portal add <handle> --key-file <path> [--no-remove-source] [--strict]
|
|
93
93
|
Import an existing private key. Encrypts it with your passphrase
|
|
94
94
|
and stores at ~/.sigil/keys/<handle>.sigil (mode 0600). Handle
|
|
95
|
-
format is <kind>:<name> where kind is "
|
|
95
|
+
format is <kind>:<name> where kind is "evm". The source key file
|
|
96
96
|
is deleted by default — pass --no-remove-source to keep it.
|
|
97
97
|
Also writes ~/.sigil/policy/<handle>.toml — permissive by default
|
|
98
98
|
(signs anything), or --strict for a locked-down template you fill
|
|
@@ -109,9 +109,20 @@ sigil policy init <handle> [--strict]
|
|
|
109
109
|
or remove it first. Defaults to permissive; --strict writes the
|
|
110
110
|
locked-down template.
|
|
111
111
|
|
|
112
|
+
sigil rpc init <handle> --upstream <url> [--port <n>]
|
|
113
|
+
Enable the JSON-RPC signing proxy for a portal: generates a strong
|
|
114
|
+
auth token and appends the [rpc] block to ~/.sigil/config.toml
|
|
115
|
+
(refuses if one exists; preserves the rest of the file). Prints the
|
|
116
|
+
ready-to-paste authenticated endpoint and forge invocation. Restart
|
|
117
|
+
Claude Code sessions to pick it up.
|
|
118
|
+
|
|
112
119
|
sigil portal list
|
|
113
|
-
List the encrypted keyfiles on disk with their derived addresses
|
|
114
|
-
Requires the passphrase.
|
|
120
|
+
List the encrypted keyfiles on disk with their derived addresses
|
|
121
|
+
(EVM + Solana). Requires the passphrase.
|
|
122
|
+
|
|
123
|
+
sigil portal qr <handle>
|
|
124
|
+
Render a portal's address as a terminal QR code (for funding it from
|
|
125
|
+
a phone wallet). Requires the passphrase.
|
|
115
126
|
|
|
116
127
|
sigil portal remove <handle>
|
|
117
128
|
Delete a keyfile from disk.
|
|
@@ -145,6 +156,8 @@ Each window still holds its own decrypted keys only for its own lifetime: closin
|
|
|
145
156
|
|
|
146
157
|
OS-keychain integration (planned, v0.3) will make unlock zero-touch for users who set it up.
|
|
147
158
|
|
|
159
|
+
**After upgrading sigil, restart every Claude window's `sigil-mcp`** (reconnect the MCP server or reopen the window, then `sigil unlock` again). A running `sigil-mcp` never reloads code, and daemons from different versions must not share `~/.sigil/audit.log`: the lock protocol and the writer's chain checks are version-specific. `ps -ax | grep sigil-mcp` shows stragglers.
|
|
160
|
+
|
|
148
161
|
## Policy engine
|
|
149
162
|
|
|
150
163
|
Once a portal is unlocked, signing authority over its key is real. To bound the blast radius of a successful prompt injection, every portal has a policy file at `~/.sigil/policy/<handle>.toml`. Two modes:
|
|
@@ -166,6 +179,13 @@ allow_contract_creation = false # deploys (to = null); when true, ever
|
|
|
166
179
|
|
|
167
180
|
allow_message_signing = false # EIP-191 personal_sign (e.g. SIWE)
|
|
168
181
|
allow_typed_data = false # EIP-712 (Permit, OpenSea — can be financial)
|
|
182
|
+
typed_data_verifying_contracts = [] # when allowed: domain.verifyingContract allowlist
|
|
183
|
+
typed_data_primary_types = [] # when allowed: primaryType allowlist ("Permit", …)
|
|
184
|
+
# strict mode also requires domain.chainId ∈ chain_ids
|
|
185
|
+
|
|
186
|
+
# Optional rolling-window caps on tx.value (work in permissive mode too).
|
|
187
|
+
max_value_per_hour_wei = "100000000000000000" # 0.1 ETH / hour
|
|
188
|
+
max_value_per_day_wei = "1000000000000000000" # 1 ETH / day
|
|
169
189
|
|
|
170
190
|
# Optional: above this value, sigil pushes a notification to your phone and
|
|
171
191
|
# waits for an approve/deny tap before signing. See "Out-of-band confirm"
|
|
@@ -175,7 +195,11 @@ require_confirm_above_wei = "10000000000000000" # 0.01 ETH
|
|
|
175
195
|
|
|
176
196
|
A failed rule throws `POLICY_DENIED` (-32001) back to the agent with the human-readable reason ("tx denied — value X exceeds max_value_wei Y"), and the deny is appended to the hash-chained audit log alongside allows. Denies are forensically the more interesting half — they're the prompt-injection canary.
|
|
177
197
|
|
|
178
|
-
|
|
198
|
+
**Rolling-window caps** (`max_value_per_hour_wei`, `max_value_per_day_wei`, and `svm_max_lamports_per_hour/day`) are the one rule that applies in *both* modes — a permissive "bot with an allowance" is the common case. They count native value only: `tx.value` for EVM, decoded System-Program transfers for Solana. ERC-20 / SPL transfers are calldata, not native value, and are not counted — and `require_confirm_above_wei` doesn't see them either (a token transfer has `value = 0`). Gate token movement with strict mode's `allow_to` + `allowed_selectors`; for Solana, anything sigil can't decode as a System-Program transfer is routed to confirm in strict mode, and denied outright when a lamport cap is set. Spends are recorded in a per-portal ledger at `~/.sigil/state/<handle>.ledger` (append-only JSONL, shared across windows through the same lock as the audit log, compacted automatically) and the check-and-record is atomic, so two windows can't both take the last of an allowance. The cap is checked before any confirm push (so you're not asked to approve something that would be denied anyway) and again right before signing. `sigil policy spend <handle>` shows the trailing 1h/24h totals against the caps. `sigil portal remove` deletes the ledger with the portal.
|
|
199
|
+
|
|
200
|
+
**EIP-712 allowlists** (strict mode, with `allow_typed_data = true`): `typed_data_verifying_contracts` and `typed_data_primary_types` each restrict one axis when non-empty, and the domain must carry a `chainId` that names one of `chain_ids` (strict mode refuses chain-less domains, since they can't be checked). A typed-data signature can move funds (Permit, Permit2, exchange orders), so it gets the same treatment as a transaction's destination.
|
|
201
|
+
|
|
202
|
+
Still deferred (in [#3](https://github.com/cdrn/sigil/issues/3)): decoded-calldata argument checks.
|
|
179
203
|
|
|
180
204
|
## Out-of-band confirm
|
|
181
205
|
|
|
@@ -200,7 +224,13 @@ If any policy file sets `require_confirm_above_wei` but no transport is configur
|
|
|
200
224
|
|
|
201
225
|
sigil can expose a local JSON-RPC endpoint that makes any portal a drop-in signer for tooling that expects an unlocked node account — the same pattern Clef and web3signer use. Contract bytecode goes from `forge` straight into sigil; it never transits the agent's context or an MCP tool parameter.
|
|
202
226
|
|
|
203
|
-
Enable it
|
|
227
|
+
Enable it with one command (generates the token, writes the config block, prints the forge invocation):
|
|
228
|
+
|
|
229
|
+
```sh
|
|
230
|
+
sigil rpc init evm:bot --upstream https://sepolia.example/v3/KEY
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
...or by hand in `~/.sigil/config.toml`:
|
|
204
234
|
|
|
205
235
|
```toml
|
|
206
236
|
[rpc]
|
|
@@ -256,7 +286,7 @@ Relevant policy fields (`~/.sigil/policy/<handle>.toml`): `allow_svm_message_sig
|
|
|
256
286
|
|
|
257
287
|
Key-management libraries die from supply chain compromise, not from clever attacks on the code. Given the npm ecosystem in 2026 (Mini Shai-Hulud, Axios, pgserve, TanStack), `sigil` commits to:
|
|
258
288
|
|
|
259
|
-
- **Zero install scripts.** No `postinstall`, `preinstall`, `prepare`. CI-enforced
|
|
289
|
+
- **Zero install scripts.** No `postinstall`, `preinstall`, `prepare`. CI-enforced: every PR runs a guard that fails if any package in the resolved tree declares one.
|
|
260
290
|
- **Six runtime deps, all version-pinned** (no caret ranges), all zero-transitive — the entire `npm ls --omit dev` tree is exactly these six packages:
|
|
261
291
|
- [`@noble/ciphers`](https://github.com/paulmillr/noble-ciphers) for XChaCha20-Poly1305
|
|
262
292
|
- [`@noble/hashes`](https://github.com/paulmillr/noble-hashes) for Argon2id, keccak256, sha2/sha512, HMAC
|
|
@@ -306,7 +336,7 @@ See [THREAT_MODEL.md](./THREAT_MODEL.md). Read it before trusting this with anyt
|
|
|
306
336
|
git clone https://github.com/cdrn/sigil
|
|
307
337
|
cd sigil
|
|
308
338
|
npm install # respects .npmrc ignore-scripts=true
|
|
309
|
-
npm test # builds + runs
|
|
339
|
+
npm test # builds + runs 600+ tests; should finish in under 15s
|
|
310
340
|
```
|
|
311
341
|
|
|
312
342
|
See [CONTRIBUTING.md](./CONTRIBUTING.md) for the PR-per-layer workflow.
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
`sigil` handles private keys. Security reports are the most valuable
|
|
4
|
+
contribution the project can receive, and they are always welcome.
|
|
5
|
+
|
|
6
|
+
## Reporting a vulnerability
|
|
7
|
+
|
|
8
|
+
**Please report privately — do not open a public issue for a vulnerability.**
|
|
9
|
+
|
|
10
|
+
Use GitHub's private vulnerability reporting:
|
|
11
|
+
[**Report a vulnerability**](https://github.com/cdrn/sigil/security/advisories/new).
|
|
12
|
+
This opens a private advisory visible only to you and the maintainers.
|
|
13
|
+
|
|
14
|
+
If you cannot use GitHub advisories, email the maintainer listed on the
|
|
15
|
+
[GitHub profile](https://github.com/cdrn) with the subject line
|
|
16
|
+
`sigil security`.
|
|
17
|
+
|
|
18
|
+
A good report includes:
|
|
19
|
+
|
|
20
|
+
- the affected version (`npm ls sigild`) or commit,
|
|
21
|
+
- what the issue is and why it matters (impact),
|
|
22
|
+
- a minimal reproduction — **please use canary/dummy values, never real
|
|
23
|
+
keys, seed phrases, or credentials**, and
|
|
24
|
+
- any suggested fix, if you have one.
|
|
25
|
+
|
|
26
|
+
You do not need a working exploit. A precise description of the flaw is
|
|
27
|
+
enough.
|
|
28
|
+
|
|
29
|
+
## What to expect
|
|
30
|
+
|
|
31
|
+
This is a small pre-alpha project maintained on a best-effort basis, so
|
|
32
|
+
timelines are not contractual, but the intent is:
|
|
33
|
+
|
|
34
|
+
- acknowledge your report within a few days,
|
|
35
|
+
- confirm or dispute it, and agree a fix and disclosure timeline with you,
|
|
36
|
+
- credit you in the advisory and release notes unless you ask otherwise,
|
|
37
|
+
- publish a GitHub Security Advisory (GHSA) and a patched release when the
|
|
38
|
+
fix ships.
|
|
39
|
+
|
|
40
|
+
Coordinated disclosure is appreciated: please give a reasonable window to
|
|
41
|
+
ship a fix before any public write-up.
|
|
42
|
+
|
|
43
|
+
## Scope
|
|
44
|
+
|
|
45
|
+
In scope — anything that undermines sigil's core promise ("Claude can sign,
|
|
46
|
+
but never see") or its documented controls, for example:
|
|
47
|
+
|
|
48
|
+
- key material reaching the agent's context, transcripts, or logs,
|
|
49
|
+
- a signing path that bypasses the policy engine, confirm gate, or audit
|
|
50
|
+
log,
|
|
51
|
+
- the ward hooks (path blocker / output redactor) not doing what
|
|
52
|
+
[`THREAT_MODEL.md`](./THREAT_MODEL.md) says they do,
|
|
53
|
+
- the JSON-RPC signing proxy signing without the documented authentication
|
|
54
|
+
or policy checks,
|
|
55
|
+
- supply-chain integrity of the published `sigild` package.
|
|
56
|
+
|
|
57
|
+
Out of scope — see the "Out of scope" and "Assumptions" sections of
|
|
58
|
+
[`THREAT_MODEL.md`](./THREAT_MODEL.md). In particular, an attacker who
|
|
59
|
+
already has local code execution or can read process memory is explicitly
|
|
60
|
+
outside the model.
|
|
61
|
+
|
|
62
|
+
Read [`THREAT_MODEL.md`](./THREAT_MODEL.md) before reporting — it states
|
|
63
|
+
what sigil does and does not defend against, which will tell you whether a
|
|
64
|
+
behavior is a bug or a documented limitation.
|
|
65
|
+
|
|
66
|
+
## Supported versions
|
|
67
|
+
|
|
68
|
+
Pre-alpha: only the latest published `sigild` version receives security
|
|
69
|
+
fixes. Pin to an exact version and read the diff before upgrading.
|
package/THREAT_MODEL.md
CHANGED
|
@@ -52,8 +52,8 @@ Defenses:
|
|
|
52
52
|
- Keys live in `sigil-mcp`'s memory only, unlocked from encrypted at-rest storage. Plaintext is zeroized on shutdown, on `sigil lock`, and on any failed unlock. mlock against swap is planned (requires a native module distributed as bundled prebuilds, see Known limitations).
|
|
53
53
|
- The MCP interface exposes only opaque handles (`eth:executor`), never key bytes.
|
|
54
54
|
- The unlock passphrase is delivered out-of-band via the control socket, not through the agent. The agent has no exposed surface that can trigger an unlock.
|
|
55
|
-
- PreToolUse hooks block `Read` and `Bash` access to `~/.sigil/**`, `*.
|
|
56
|
-
- PostToolUse output filter redacts
|
|
55
|
+
- PreToolUse hooks block `Read` and `Bash` access to files whose *entire purpose* is to hold a private key: `~/.sigil/**`, `*.key` / `*.keystore` / `*.jks` / `*.p12`, SSH private-key conventions (`.ssh/id_*`, `*_rsa`, `*_ed25519`, `*_ecdsa`), and GPG / `pass(1)` stores (`.gnupg/**`, `.password-store/**`) — plus a user-configurable extra list. This layer is deliberately **narrow and high-precision**: it does *not* block mixed-content files such as `.env` (blocking every `.env` would break ordinary work and give false assurance — secrets live in many places, and most `.env` content is not secret) nor `*.pem` (dominated by public certs and CA bundles). Those are handled by content redaction below, not by denying the read. Blocking is a whole-file veto; use it only where a read has no legitimate purpose.
|
|
56
|
+
- PostToolUse output filter redacts secret *content* from tool output before it reaches the model, wherever it appears — including inside a `.env` the agent legitimately read. Rules: 0x-prefixed 32-byte hex private keys; PEM private-key / key blocks; **BIP-39 seed phrases, checksum-validated** (a loose "N words" match would shred prose, so a run is only redacted if every word is in the 2048-word list *and* the BIP-39 checksum verifies); **secret-named env/config assignments** (`PRIVATE_KEY=` / `MNEMONIC=` / `SEED_PHRASE=` / `SECRET_KEY=`, value redacted, name kept); and common API-key/token shapes (JWT, npm, Anthropic, OpenAI, AWS). This is the layer that protects `.env` reads: the file comes back with `PORT` and `DATABASE_URL` intact and the key material stripped.
|
|
57
57
|
|
|
58
58
|
### 2. Bounding signing authority
|
|
59
59
|
|
|
@@ -110,6 +110,8 @@ Given the 2026 npm threat landscape, a compromised release of `sigil` would be c
|
|
|
110
110
|
- The user's OS keychain (or chosen unlock mechanism) is not compromised.
|
|
111
111
|
- Clock skew on the host is bounded (matters for rolling-window policy and audit timestamps).
|
|
112
112
|
|
|
113
|
+
- **The spend ledgers share the policy files' trust boundary.** Rolling-window caps are enforced against `~/.sigil/state/<handle>.ledger`. Unparsable content fails closed, but a *missing* ledger is an empty one: anyone who can delete it can equally edit `~/.sigil/policy/<handle>.toml` and remove the cap, so the ledger earns no protection the policy file doesn't have. The caps defend against the agent, which reaches sigil only through the signing RPC and the ward-guarded tools; they are not a defence against a principal with write access to `~/.sigil`. If your deployment gives the agent's tools a different filesystem view from the policy's, treat that as out of scope here.
|
|
114
|
+
|
|
113
115
|
## Known limitations
|
|
114
116
|
|
|
115
117
|
- The hook-based path blocker is best-effort: it covers `Read` and `Bash`, but a sufficiently creative agent could still ask another tool to do the read. The defense in depth is that even if a key file is read, its contents are redacted by the output filter before reaching the model. And, given the unlock model, reading the encrypted keyfile alone yields nothing — the agent would also need the passphrase, which is never in its context.
|
|
@@ -122,4 +124,4 @@ Given the 2026 npm threat landscape, a compromised release of `sigil` would be c
|
|
|
122
124
|
|
|
123
125
|
## Reporting issues
|
|
124
126
|
|
|
125
|
-
|
|
127
|
+
See [SECURITY.md](./SECURITY.md) for how to report a vulnerability privately. In short: use GitHub's [private vulnerability reporting](https://github.com/cdrn/sigil/security/advisories/new) — please don't file public issues for vulnerabilities, and use canary values (never real keys) in reproductions.
|
|
@@ -1,2 +1,3 @@
|
|
|
1
|
-
export { type AuditDecision, type AuditEntry, type StoredAuditEntry, type ChainHead, ZERO_HASH, HASH_HEX_LEN, AuditChainError, AuditWriter, canonicalJSON, hashEntry, sealEntry, serializeEntry, parseLine, verifyChain, readHead, } from './log.js';
|
|
1
|
+
export { type AuditDecision, type AuditEntry, type StoredAuditEntry, type ChainHead, ZERO_HASH, HASH_HEX_LEN, AuditChainError, AuditWriter, canonicalJSON, hashEntry, sealEntry, serializeEntry, parseLine, verifyChain, readHead, type AuditWriterOpts, } from './log.js';
|
|
2
|
+
export { type AcquireLockOptions, AuditLockError, acquireLockSync } from '../fs/lock.js';
|
|
2
3
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,SAAS,EACT,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,EACb,SAAS,EACT,SAAS,EACT,cAAc,EACd,SAAS,EACT,WAAW,EACX,QAAQ,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,SAAS,EACT,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,EACb,SAAS,EACT,SAAS,EACT,cAAc,EACd,SAAS,EACT,WAAW,EACX,QAAQ,EACR,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,KAAK,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}
|
package/dist/src/audit/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,SAAS,EACT,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,EACb,SAAS,EACT,SAAS,EACT,cAAc,EACd,SAAS,EACT,WAAW,EACX,QAAQ,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,SAAS,EACT,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,EACb,SAAS,EACT,SAAS,EACT,cAAc,EACd,SAAS,EACT,WAAW,EACX,QAAQ,GAET,MAAM,UAAU,CAAC;AAClB,OAAO,EAA2B,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}
|
package/dist/src/audit/log.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type AcquireLockOptions } from '../fs/lock.js';
|
|
1
2
|
export type AuditDecision = 'allow' | 'deny' | 'confirm_required';
|
|
2
3
|
export interface AuditEntry {
|
|
3
4
|
seq: number;
|
|
@@ -75,13 +76,36 @@ export declare function readHead(path: string): ChainHead;
|
|
|
75
76
|
*
|
|
76
77
|
* The seq and prev_hash fields are managed by the writer; callers supply
|
|
77
78
|
* everything else.
|
|
79
|
+
*
|
|
80
|
+
* Multiple processes (one sigil-mcp per Claude session) share one audit file,
|
|
81
|
+
* so every append serializes through the sidecar lock directory
|
|
82
|
+
* `<path>.lock.d` (see src/fs/lock.ts). The in-memory head is only a cache:
|
|
83
|
+
* under the lock, the writer checks the file's byte length and the hash of
|
|
84
|
+
* its last line against what it cached and, if either moved, re-reads (and
|
|
85
|
+
* re-verifies) the chain before computing the next entry. Without this, concurrent writers
|
|
86
|
+
* each extend their own stale tail and the interleaved lines fail startup
|
|
87
|
+
* verification with seq gaps and broken prev_hash links.
|
|
78
88
|
*/
|
|
89
|
+
export interface AuditWriterOpts {
|
|
90
|
+
/** Clock override for tests. Defaults to Date.now. */
|
|
91
|
+
now?: () => number;
|
|
92
|
+
lock?: AcquireLockOptions;
|
|
93
|
+
/**
|
|
94
|
+
* What to do when the file on disk fails chain verification:
|
|
95
|
+
* - 'throw' (default): raise AuditChainError; the caller decides.
|
|
96
|
+
* - 'quarantine': move the file to `<path>.corrupt-<timestamp>` (never
|
|
97
|
+
* overwriting an existing file), report via `warn`, and start a fresh
|
|
98
|
+
* chain. Nothing is deleted. sigil-mcp uses this so one damaged log
|
|
99
|
+
* can't lock the user out of signing until they hand-edit it.
|
|
100
|
+
*/
|
|
101
|
+
onCorrupt?: 'throw' | 'quarantine';
|
|
102
|
+
warn?: (message: string) => void;
|
|
103
|
+
}
|
|
79
104
|
export declare class AuditWriter {
|
|
80
105
|
#private;
|
|
81
106
|
readonly path: string;
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
});
|
|
107
|
+
readonly lockPath: string;
|
|
108
|
+
constructor(path: string, opts?: AuditWriterOpts);
|
|
85
109
|
get head(): ChainHead;
|
|
86
110
|
append(input: {
|
|
87
111
|
kind: string;
|
|
@@ -93,4 +117,14 @@ export declare class AuditWriter {
|
|
|
93
117
|
}): StoredAuditEntry;
|
|
94
118
|
close(): void;
|
|
95
119
|
}
|
|
120
|
+
/**
|
|
121
|
+
* Test-only seams. `quarantineStep` is invoked before each step of
|
|
122
|
+
* quarantine publication and may throw to simulate that step failing;
|
|
123
|
+
* `tailScanMax` overrides the scan cap so the fallback path can be tested
|
|
124
|
+
* without writing tens of megabytes. Never set by production code.
|
|
125
|
+
*/
|
|
126
|
+
export declare const _auditTestHooks: {
|
|
127
|
+
quarantineStep?: (step: 'fsync-evidence' | 'fsync-dir' | 'unlink') => void;
|
|
128
|
+
tailScanMax?: number;
|
|
129
|
+
};
|
|
96
130
|
//# sourceMappingURL=log.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../../src/audit/log.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../../src/audit/log.ts"],"names":[],"mappings":"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"}
|