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.
Files changed (180) hide show
  1. package/README.md +43 -13
  2. package/SECURITY.md +69 -0
  3. package/THREAT_MODEL.md +5 -3
  4. package/dist/src/audit/index.d.ts +2 -1
  5. package/dist/src/audit/index.d.ts.map +1 -1
  6. package/dist/src/audit/index.js +1 -0
  7. package/dist/src/audit/index.js.map +1 -1
  8. package/dist/src/audit/log.d.ts +37 -3
  9. package/dist/src/audit/log.d.ts.map +1 -1
  10. package/dist/src/audit/log.js +227 -41
  11. package/dist/src/audit/log.js.map +1 -1
  12. package/dist/src/bin/sigil-mcp.js +23 -6
  13. package/dist/src/bin/sigil-mcp.js.map +1 -1
  14. package/dist/src/cli/args.d.ts.map +1 -1
  15. package/dist/src/cli/args.js.map +1 -1
  16. package/dist/src/cli/index.d.ts +1 -1
  17. package/dist/src/cli/index.d.ts.map +1 -1
  18. package/dist/src/cli/index.js +1 -1
  19. package/dist/src/cli/index.js.map +1 -1
  20. package/dist/src/cli/main.d.ts.map +1 -1
  21. package/dist/src/cli/main.js +76 -4
  22. package/dist/src/cli/main.js.map +1 -1
  23. package/dist/src/cli/paths.d.ts +2 -0
  24. package/dist/src/cli/paths.d.ts.map +1 -1
  25. package/dist/src/cli/paths.js +1 -0
  26. package/dist/src/cli/paths.js.map +1 -1
  27. package/dist/src/cli/portal.d.ts.map +1 -1
  28. package/dist/src/cli/portal.js +17 -3
  29. package/dist/src/cli/portal.js.map +1 -1
  30. package/dist/src/cli/rpc.d.ts +24 -0
  31. package/dist/src/cli/rpc.d.ts.map +1 -0
  32. package/dist/src/cli/rpc.js +68 -0
  33. package/dist/src/cli/rpc.js.map +1 -0
  34. package/dist/src/cli/status.d.ts.map +1 -1
  35. package/dist/src/cli/status.js +1 -1
  36. package/dist/src/cli/status.js.map +1 -1
  37. package/dist/src/cli/unlock.d.ts.map +1 -1
  38. package/dist/src/cli/unlock.js +1 -1
  39. package/dist/src/cli/unlock.js.map +1 -1
  40. package/dist/src/confirm/config.d.ts.map +1 -1
  41. package/dist/src/confirm/config.js.map +1 -1
  42. package/dist/src/confirm/index.d.ts +2 -2
  43. package/dist/src/confirm/index.d.ts.map +1 -1
  44. package/dist/src/confirm/index.js +1 -1
  45. package/dist/src/confirm/index.js.map +1 -1
  46. package/dist/src/confirm/ntfy.d.ts.map +1 -1
  47. package/dist/src/confirm/ntfy.js +5 -5
  48. package/dist/src/confirm/ntfy.js.map +1 -1
  49. package/dist/src/control/broadcast.d.ts.map +1 -1
  50. package/dist/src/control/broadcast.js +7 -4
  51. package/dist/src/control/broadcast.js.map +1 -1
  52. package/dist/src/control/client.d.ts.map +1 -1
  53. package/dist/src/control/client.js +5 -2
  54. package/dist/src/control/client.js.map +1 -1
  55. package/dist/src/control/protocol.d.ts.map +1 -1
  56. package/dist/src/control/protocol.js.map +1 -1
  57. package/dist/src/control/server.d.ts.map +1 -1
  58. package/dist/src/control/server.js +17 -4
  59. package/dist/src/control/server.js.map +1 -1
  60. package/dist/src/crypto/aead.d.ts.map +1 -1
  61. package/dist/src/crypto/aead.js.map +1 -1
  62. package/dist/src/crypto/index.d.ts +1 -1
  63. package/dist/src/crypto/index.d.ts.map +1 -1
  64. package/dist/src/crypto/index.js +1 -1
  65. package/dist/src/crypto/index.js.map +1 -1
  66. package/dist/src/crypto/keyfile.d.ts.map +1 -1
  67. package/dist/src/crypto/keyfile.js +1 -0
  68. package/dist/src/crypto/keyfile.js.map +1 -1
  69. package/dist/src/daemon/handles.d.ts.map +1 -1
  70. package/dist/src/daemon/handles.js +1 -1
  71. package/dist/src/daemon/handles.js.map +1 -1
  72. package/dist/src/daemon/index.d.ts +1 -1
  73. package/dist/src/daemon/index.d.ts.map +1 -1
  74. package/dist/src/daemon/index.js +1 -1
  75. package/dist/src/daemon/index.js.map +1 -1
  76. package/dist/src/daemon/methods.d.ts +8 -1
  77. package/dist/src/daemon/methods.d.ts.map +1 -1
  78. package/dist/src/daemon/methods.js +133 -13
  79. package/dist/src/daemon/methods.js.map +1 -1
  80. package/dist/src/daemon/passphrase.d.ts.map +1 -1
  81. package/dist/src/daemon/passphrase.js.map +1 -1
  82. package/dist/src/eth/address.d.ts.map +1 -1
  83. package/dist/src/eth/address.js +1 -1
  84. package/dist/src/eth/address.js.map +1 -1
  85. package/dist/src/eth/index.d.ts +2 -2
  86. package/dist/src/eth/index.d.ts.map +1 -1
  87. package/dist/src/eth/index.js +2 -2
  88. package/dist/src/eth/index.js.map +1 -1
  89. package/dist/src/eth/rlp.js +1 -1
  90. package/dist/src/eth/rlp.js.map +1 -1
  91. package/dist/src/eth/secp.d.ts.map +1 -1
  92. package/dist/src/eth/secp.js.map +1 -1
  93. package/dist/src/eth/sign-message.d.ts.map +1 -1
  94. package/dist/src/eth/sign-message.js.map +1 -1
  95. package/dist/src/eth/sign-tx.d.ts.map +1 -1
  96. package/dist/src/eth/sign-tx.js +13 -4
  97. package/dist/src/eth/sign-tx.js.map +1 -1
  98. package/dist/src/eth/sign-typed.d.ts.map +1 -1
  99. package/dist/src/eth/sign-typed.js.map +1 -1
  100. package/dist/src/fs/index.d.ts +2 -0
  101. package/dist/src/fs/index.d.ts.map +1 -0
  102. package/dist/src/fs/index.js +2 -0
  103. package/dist/src/fs/index.js.map +1 -0
  104. package/dist/src/fs/lock.d.ts +84 -0
  105. package/dist/src/fs/lock.d.ts.map +1 -0
  106. package/dist/src/fs/lock.js +329 -0
  107. package/dist/src/fs/lock.js.map +1 -0
  108. package/dist/src/hooks/bip39-wordlist.d.ts +12 -0
  109. package/dist/src/hooks/bip39-wordlist.d.ts.map +1 -0
  110. package/dist/src/hooks/bip39-wordlist.js +2061 -0
  111. package/dist/src/hooks/bip39-wordlist.js.map +1 -0
  112. package/dist/src/hooks/bip39.d.ts +19 -0
  113. package/dist/src/hooks/bip39.d.ts.map +1 -0
  114. package/dist/src/hooks/bip39.js +101 -0
  115. package/dist/src/hooks/bip39.js.map +1 -0
  116. package/dist/src/hooks/command-scanner.d.ts.map +1 -1
  117. package/dist/src/hooks/command-scanner.js +45 -9
  118. package/dist/src/hooks/command-scanner.js.map +1 -1
  119. package/dist/src/hooks/index.d.ts +1 -1
  120. package/dist/src/hooks/index.d.ts.map +1 -1
  121. package/dist/src/hooks/index.js +1 -1
  122. package/dist/src/hooks/index.js.map +1 -1
  123. package/dist/src/hooks/install.js +1 -1
  124. package/dist/src/hooks/install.js.map +1 -1
  125. package/dist/src/hooks/protocol.d.ts.map +1 -1
  126. package/dist/src/hooks/protocol.js +1 -1
  127. package/dist/src/hooks/protocol.js.map +1 -1
  128. package/dist/src/hooks/redactor.d.ts +10 -1
  129. package/dist/src/hooks/redactor.d.ts.map +1 -1
  130. package/dist/src/hooks/redactor.js +34 -3
  131. package/dist/src/hooks/redactor.js.map +1 -1
  132. package/dist/src/mcp/protocol.d.ts.map +1 -1
  133. package/dist/src/mcp/protocol.js +5 -1
  134. package/dist/src/mcp/protocol.js.map +1 -1
  135. package/dist/src/mcp/tools.d.ts.map +1 -1
  136. package/dist/src/mcp/tools.js +6 -3
  137. package/dist/src/mcp/tools.js.map +1 -1
  138. package/dist/src/policy/evaluate.d.ts.map +1 -1
  139. package/dist/src/policy/evaluate.js +71 -6
  140. package/dist/src/policy/evaluate.js.map +1 -1
  141. package/dist/src/policy/index.d.ts +3 -1
  142. package/dist/src/policy/index.d.ts.map +1 -1
  143. package/dist/src/policy/index.js +3 -1
  144. package/dist/src/policy/index.js.map +1 -1
  145. package/dist/src/policy/ledger.d.ts +83 -0
  146. package/dist/src/policy/ledger.d.ts.map +1 -0
  147. package/dist/src/policy/ledger.js +250 -0
  148. package/dist/src/policy/ledger.js.map +1 -0
  149. package/dist/src/policy/loader.d.ts.map +1 -1
  150. package/dist/src/policy/loader.js +45 -0
  151. package/dist/src/policy/loader.js.map +1 -1
  152. package/dist/src/policy/template.d.ts +2 -2
  153. package/dist/src/policy/template.d.ts.map +1 -1
  154. package/dist/src/policy/template.js +32 -0
  155. package/dist/src/policy/template.js.map +1 -1
  156. package/dist/src/policy/types.d.ts +26 -0
  157. package/dist/src/policy/types.d.ts.map +1 -1
  158. package/dist/src/policy/types.js.map +1 -1
  159. package/dist/src/policy/window.d.ts +22 -0
  160. package/dist/src/policy/window.d.ts.map +1 -0
  161. package/dist/src/policy/window.js +66 -0
  162. package/dist/src/policy/window.js.map +1 -0
  163. package/dist/src/qr/encode.d.ts +10 -1
  164. package/dist/src/qr/encode.d.ts.map +1 -1
  165. package/dist/src/qr/encode.js +2 -2
  166. package/dist/src/qr/encode.js.map +1 -1
  167. package/dist/src/qr/index.d.ts +1 -1
  168. package/dist/src/qr/index.d.ts.map +1 -1
  169. package/dist/src/qr/index.js.map +1 -1
  170. package/dist/src/rpc/fill.d.ts.map +1 -1
  171. package/dist/src/rpc/fill.js.map +1 -1
  172. package/dist/src/rpc/server.d.ts.map +1 -1
  173. package/dist/src/rpc/server.js +4 -2
  174. package/dist/src/rpc/server.js.map +1 -1
  175. package/dist/src/rpc/upstream.d.ts.map +1 -1
  176. package/dist/src/rpc/upstream.js.map +1 -1
  177. package/dist/src/svm/transaction.d.ts.map +1 -1
  178. package/dist/src/svm/transaction.js +13 -4
  179. package/dist/src/svm/transaction.js.map +1 -1
  180. 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), and out-of-band confirmation via ntfy all work end-to-end. Rolling-window value caps and EIP-712 domain allowlists are not yet implemented. Until they land — and until the supply-chain attestations promised for v0.1.0 ship — **do not use this with real funds yet.** Build plan lives in the [tracking issue](https://github.com/cdrn/sigil/issues/9).
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. v1 covers static checks (chain ID, destination allowlist, per-tx value cap, function-selector allowlist, on/off toggles for personal_sign and EIP-712). Rolling-window caps, EIP-712 domain allowlists, and out-of-band human confirmation are tracked in [#3](https://github.com/cdrn/sigil/issues/3) + [#4](https://github.com/cdrn/sigil/issues/4) and will land incrementally.
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`. (The package name on npm is `sigild` for legacy reasons; the bins do not include a daemon any more.)
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 "eth". The source key file
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
- What's deferred to follow-up PRs (still in [#3](https://github.com/cdrn/sigil/issues/3)): rolling-window value caps (e.g. 1 ETH/day per portal), EIP-712 domain + primary-type allowlists, decoded-calldata arg checks.
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 in `~/.sigil/config.toml`:
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 (planned: a CI guard that fails if any dep adds one).
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 ~330 tests; should finish in under 10s
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/**`, `*.pem`, `**/.env*`, `**/keystore*`, and a configurable extra list.
56
- - PostToolUse output filter redacts hex-encoded 32-byte blobs, PEM blocks, and bip39-shaped strings from tool output before it reaches the model.
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
- Security issues: open a GitHub security advisory on the repo. Please do not file public issues for vulnerabilities.
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,GACT,MAAM,UAAU,CAAC"}
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"}
@@ -1,2 +1,3 @@
1
1
  export { ZERO_HASH, HASH_HEX_LEN, AuditChainError, AuditWriter, canonicalJSON, hashEntry, sealEntry, serializeEntry, parseLine, verifyChain, readHead, } from './log.js';
2
+ export { AuditLockError, acquireLockSync } from '../fs/lock.js';
2
3
  //# sourceMappingURL=index.js.map
@@ -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,GACT,MAAM,UAAU,CAAC"}
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"}
@@ -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
- constructor(path: string, opts?: {
83
- now?: () => number;
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":"AAGA,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,kBAAkB,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,SAAS,QAAiB,CAAC;AACxC,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;gBACvB,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAKxC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAuBpD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,gBAAgB,CAE7D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CA4CxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,gBAAgB,EAAE,CA8BpE;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAgBhD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,WAAW;;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAMV,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KAAO;IAM3D,IAAI,IAAI,IAAI,SAAS,CAEpB;IAED,MAAM,CAAC,KAAK,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,aAAa,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,gBAAgB;IA4BpB,KAAK,IAAI,IAAI;CAGd"}
1
+ {"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../../src/audit/log.ts"],"names":[],"mappings":"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"}