@scopebond/hook 0.5.0 → 0.7.0

package/README.md

@@ -23,8 +23,11 @@ scaffolds a user-level home (`~/.scopebond`, override `SCOPEBOND_HOME`) with a
 signing key, a countersigning key and a starter policy, and registers the hook by
 absolute path in your user-level `~/.claude/settings.json`, `~/.cursor/hooks.json`,
 or `~/.codex/hooks.json`. After Codex setup, open Codex, run `/hooks`, review
-Scopebond, and choose **Trust** once. Every project you open is then governed, and a project-local
-`.scopebond/` still takes precedence when you want a per-repo policy.
+Scopebond, and choose **Trust** once. Every project you open is then governed by your
+user-level policy. A project's own `.scopebond/policy.json` applies only after you trust it
+in that project (`scopebond trust`, or `init` there), pinned to its exact contents: a
+repository you clone, or an agent working in it, cannot swap in a weaker policy, and any
+later edit to that file stops it applying until you trust it again.
 
 ```
 scopebond status                    # home, which agents are configured, cloud, receipts
@@ -54,7 +57,62 @@ npx @scopebond/hook init --codex    # Codex, then approve it once with /hooks
 countersigning key, a starter policy — "protect main and production paths" — and a
 `.gitignore` so none of it is committed) and configures `.claude/settings.json`,
 `.cursor/hooks.json`, or `.codex/hooks.json`. Then run one safe command in the agent and see the receipt in
-`.scopebond/receipts.db`.
+`.scopebond/receipts.db`. `init`, `trust` and `uninstall` are meant for a person at a
+terminal: in a script or CI, pass `--yes`.
+
+Check what it did with `npx @scopebond/hook status` (which agents are configured, in
+which scope) and `npx @scopebond/hook doctor` (whether each configured command can
+actually start).
+
+### Changing the rules
+
+`.scopebond/policy.json` is **generated**. The thing you edit is `.scopebond/rules.json`,
+a short readable list, and `policy.json` is compiled from it — so a limit is a line in a
+list, not a 700-character lookahead:
+
+```
+npx @scopebond/hook rules                      # what is blocked, in plain English
+npx @scopebond/hook rules allow dd             # stop blocking a program
+npx @scopebond/hook rules protect infra/       # never write there
+npx @scopebond/hook rules protect-branch production
+npx @scopebond/hook rules apply                # recompile after editing rules.json by hand
+```
+
+The compiled patterns are identical to the ones this package has always shipped — there
+is a test that pins them against the starter policy — so the readable front end cannot
+change what is enforced. Each clause description is generated from the list too, so it
+stays true after an edit, and a block message quotes it.
+
+### The hook command `init` installs
+
+The hook runs once per tool call, so the command has to start fast. `init` copies this
+package into `~/.scopebond/runtime/<version>/` once per machine and points your agent
+at that absolute path. Measured on one Windows machine, through a shell, warm cache:
+
+| Command in the agent config | Median per tool call |
+|---|---|
+| pinned absolute path (the default) | **151 ms** |
+| `npx -y @scopebond/hook@<version>` | 1053 ms |
+
+That ~900 ms is npm re-resolving a package already on disk, on every action. Pass
+`--npx` to `init` if you would rather have the portable command, and `init` falls back
+to it automatically when it cannot make a durable copy — slow beats broken. `doctor`
+re-checks that the pinned paths still resolve, so a cleared home or a switched Node
+version shows up as a problem rather than as a hook that silently cannot start.
+
+### What each agent can actually stop
+
+| | Claude Code | Cursor | Codex |
+|---|---|---|---|
+| Shell commands | prevented | prevented | prevented |
+| File reads | prevented | prevented | prevented |
+| MCP tool calls | prevented | prevented | prevented |
+| File writes / edits | prevented | **recorded, not prevented** | prevented |
+
+Cursor reports a file edit only *after* it is written (`afterFileEdit`; it has no
+before-edit hook), so an out-of-policy edit there is signed and flagged, not blocked —
+and the message says so rather than claiming otherwise. For edits that must be stopped
+before they land, make `@scopebond/github-action` a required check on pull requests.
 
 ## Connect it to your workspace (optional)
 
@@ -78,8 +136,8 @@ can hand you a single copy-paste command with nothing to save.
 
 From then on every receipt is mirrored to the workspace through a **durable outbox**:
 delivery is best-effort and never blocks a tool call, and receipts are retained
-locally and retried if the workspace is unreachable. `scopebond-hook flush` delivers
-anything still queued — run it on a session-end hook (and set
+locally and retried if the workspace is unreachable. `npx @scopebond/hook flush`
+delivers anything still queued — run it on a session-end hook (and set
 `SCOPEBOND_HOOK_FLUSH_MS=0`) if you want zero per-call latency.
 
 ## How it works
@@ -87,17 +145,86 @@ anything still queued — run it on a session-end hook (and set
 Each tool call is mapped to a normalized [Action Taxonomy](https://github.com/avouro-com/scopebond)
 action (`shell.exec`, `git.push`, `file.write`, `mcp.tool.call`, …), signed by the
 machine key and decided against your policy by an in-process check-only gateway.
-An allowed action is recorded and left to the coding agent's normal permission
-prompt; the hook never auto-approves it. A denied action is blocked. Unknown tools are
-recorded as *not evaluated* and grant nothing. Anything unexpected fails closed
-(deny) with a repair message.
+An allowed action is recorded and the agent proceeds. A denied action is blocked.
+Unknown tools are recorded as *not evaluated* and grant nothing — they fall through to
+the coding agent's own permission prompt, so the hook never turns an unrecognised
+action into an approval. Anything unexpected fails closed (deny) with a repair message.
+
+**What a block says.** A denial names the action, the rule that decided, why that rule
+exists (the clause's own description), the engine's technical detail and where to change
+it. The same text goes to the agent, so it can choose another approach instead of
+retrying a blocked call:
+
+```
+Scopebond blocked git.push origin main — rule "protect-branches" (enforce).
+Why: Deny pushes to main, master and release/* (any case, any refspec spelling), …
+Detail: param ref fails pattern
+Change the rule: edit clause "protect-branches" in /repo/.scopebond/policy.json
+```
 
 Commands are stored as a scrubbed head plus a digest; file contents are never
 stored; common secret shapes are removed before signing.
 
-**Strict mode.** By default a tool with no taxonomy mapping is recorded *not
-evaluated* (not blocked). Add `--strict` (or `SCOPEBOND_HOOK_STRICT=1`) to deny
-unmapped tools too — fail-closed coverage for anything the taxonomy does not map.
+**Where receipts live, and how much room they take.** `.scopebond/receipts.db` in the
+project, roughly 25 KiB per tool call. Nothing is ever deleted automatically — these are
+your evidence — so `status` reports the count and size, and `prune` bounds it when you
+choose to:
+
+```
+npx @scopebond/hook prune                      # report the footprint
+npx @scopebond/hook prune --before 90d --yes   # archive, then remove, anything older
+```
+
+`prune` writes the receipts it will remove to a JSONL file beside the database first, so
+they stay verifiable, and it refuses outright once the log has been anchored — a receipt's
+position is its anchor leaf index, so removing one would make an existing anchor
+unverifiable.
+
+**What a shell command is checked for.** A command line is split into every command it
+runs (`&&`, `;`, pipes, `$( )` and backticks — also inside double quotes — `bash -c`,
+`eval`, `trap`, `su -c`, `script -c`, `watch`, `parallel`, `cmd /c`, `pwsh -Command`
+and `-EncodedCommand`, `find -exec`, `env -S`), with shell keywords and grouping
+(`if … then`, `for … do`, `{ … }`, `!`, `case`) and wrappers (`sudo`, `env`, `time`,
+`nice`, `xargs`, `timeout`, `strace`, `busybox` …, each with its own option arity)
+stripped so the real program is seen; the wrappers are checked too. Each command is
+checked as a program, and the files it reads or writes are checked like the Read and
+Write tools: operands of programs that output or copy file content (`cat`, `grep`,
+`tar`, …), copies and moves (`cp`, `mv`, `rsync`, `scp`, `Copy-Item`), writers and
+editors (`tee`, `touch`, `sed -i`, `yq -i`, `ed`, `vim`, `Set-Content`), git's own writes
+(`checkout -- p`, `restore`, `mv`, `rm`, `config core.hooksPath`), secrets sent or staged
+(`curl -T`, `-d @file`, `gh gist create`, `git add`) and redirections, including
+`x>file` without spaces. Existence and metadata checks (`ls`, `test -f`, `[ -f ]`,
+`stat`) and a secret file's name in a string are not reads. Paths are compared
+case-insensitively; Windows `\` paths, 8.3 short names (`CLAUDE~1`), `::$DATA` streams
+and trailing dots are normalized; and a glob, variable or brace list that could name a
+protected file or directory (`.scope*/agent.key`, `.*/*`, `$HOME/.ssh/id_rsa`) is
+treated as that file. Every destination of a `git push` is checked in the common
+spellings (`refs/heads/main`, `HEAD:main`, a second refspec, `--repo`, `--all`,
+`--mirror`); a push whose destination is not on the command line (a git alias, a
+configured push refspec, `send-pack`) is denied, and a tags-only push is allowed. The
+agent running the hook's own `init`, `install`, `trust`, `uninstall` or `connect` is
+denied, and those commands also refuse a non-interactive terminal unless `--yes` is
+passed.
+
+**Limits.** The hook sees the command text, not what a program does at run time. It
+does not follow a variable whose value it cannot see (`cat $FILE`), a path assembled
+inside a script or interpreter (`python script.py`), aliases and functions defined in
+an earlier call, git aliases from a config file, recursive reads of a parent of a
+protected directory (`grep -r . `, `cp -r ~ /tmp`), or deletion expressed as arguments
+(`find -delete`, `git clean`). Commands whose written files are named only inside their
+input — `patch`, `git apply`, `git am`, `tar x`, `unzip`, `7z x`, `cpio -i` — are
+recorded with an unevaluated write: allowed in normal mode, denied in strict mode.
+Reading any `*.pem` file is denied, including a public certificate, because a PEM file
+is often a private key. For stronger guarantees, run the agent behind the Scopebond
+gateway or in a sandbox; the hook is a guardrail for a cooperating agent, not a jail.
+
+**Strict mode.** A shell command that cannot be parsed (an unbalanced quote) or whose
+program is only known at run time (`$cmd`, `$(…) args`) is checked with an empty
+program name, which the starter policy denies in every mode — edit the `safe-shell`
+clause to change that. By default a tool with no taxonomy mapping, or a write whose
+target the command text does not name, is recorded *not evaluated* (not blocked). Add
+`--strict` (or `SCOPEBOND_HOOK_STRICT=1`) to deny those too — fail-closed coverage for
+anything the taxonomy does not map.
 
 ## Library
 

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
-export {};
+/** A `--since` value: a duration (`7d`, `24h`, `30m`) or an ISO-ish date. */
+export declare function parseSince(value: string | undefined, now?: number): number | null;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA8fA,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAS7F"}