@ev-ai/agent-hook 1.2.1 → 1.2.3

package/README.md

@@ -11,6 +11,37 @@ This is an **opt-in, first-party observability agent** that an ev-ai customer in
 - **Collection is opt-out for prompt / tool-arg / tool-result / last-assistant-message bodies.** Those four `hook_input` fields are sent by default (size-capped). Set `EV_AI_HOOK_CAPTURE_CONTENT=off` or `capture_hook_input: "allowlist"` to drop them. On Claude that includes file bodies written or read through a tool, which arrive nested in `tool_input` / `tool_response`. Session titles, chat transcripts, keystrokes, and runner error prose stay dropped. `env_vars` is a fixed allowlist of non-secret CI/runtime markers; API keys and proxy vars are never read. See [Privacy defaults](#privacy-defaults).
 - **What it is not:** it is not spyware, not a keylogger, and not a data broker. It does not collect keystrokes, does not scrape the filesystem, and does not exfiltrate to any endpoint the operator did not configure. It does forward the bodies of tool calls the agent makes, unless content capture is turned off.
 
+## What this package does on your machine
+
+A plain list of every behavior a security reviewer or supply-chain scanner will want to know about. Details and opt-outs are in the linked sections.
+
+**At install time: nothing.** The package has no `preinstall` / `install` / `postinstall` scripts, no native modules, and no runtime dependencies. Code runs only when a runner (Claude Code, Cursor, Codex) fires a configured hook, or when you run the CLI yourself.
+
+**Network requests** (all HTTPS, except `http://` to loopback for a local collector):
+
+- `POST {collector_url}` on hook events — the runtime envelope described in [COLLECTED-DATA.md](COLLECTED-DATA.md). The destination is only the collector URL you configure (`--url`, the committed `ev-ai-runtime-report.json`, or `~/.ev-ai/config.json`).
+- `GET /{orgToken}/version` on that same collector, and — when the collector returns a signed envelope — a download of `hook.mjs` from the signed URL — the auto-update path. See [Hook updates](#hook-updates-npx-path).
+- Cloud instance metadata, **only in non-interactive contexts** (CI / cloud VMs, never a developer's interactive session), at most once per 24 h: AWS IMDSv2 (`169.254.169.254`), GCP (`metadata.google.internal`), Azure (`169.254.169.254`). Only provider, region and instance id are read; no credentials or tokens are requested beyond the short-lived IMDSv2 session token that AWS requires for the read.
+
+**Auto-update: the package can run code it did not ship with.** On the npx path the launcher may run a newer `hook.mjs` that your collector selects, downloaded to `~/.ev-ai/agent-hook/js/signed-v1/`, verified against an ev-ai signed envelope (built-in public key) and SHA-512 of the bytes, and executed with the same Node that runs the launcher. It is on by default; turn it off with `EV_AI_AUTO_UPDATE=0` or `"auto_update": false` in `~/.ev-ai/config.json`, and the pinned, bundled hook is the only code that runs. A repo manifest cannot change this setting.
+
+**Background processes.** To ack the runner quickly, most events are collected by a detached child process that exits after one POST. At session start the launcher may also spawn one detached `__refresh` process that performs the update check above and exits (skipped when auto-update is off).
+
+**Files read** (identity and configuration only, never file contents from your projects):
+
+- Runner configs: `.claude/`, `.cursor/`, `.codex/` hook / plugin / MCP settings at user, project and managed scope. MCP `env` blocks are reduced to variable **names**; values are never read into the envelope.
+- Operator identity: `~/.claude.json` (the `oauthAccount` login email and name), `~/.cursor/cli-config.json`, Cursor's `state.vscdb` (only `cursorAuth/*` rows, with every key containing `token` excluded in the SQL query and again in code), and `~/.codex/auth.json` (only the ID-token's identity claims are decoded locally; the API key and access / refresh tokens are never read out or sent).
+- Git: `remote.origin.url`, `user.email`, last commit author, repo root.
+- A fixed allowlist of non-secret environment variables (CI / runtime markers). API keys, tokens and proxy variables are never read.
+
+**Files written.** Only under `~/.ev-ai/` (installation id, caches, update artifacts, short-lived dedup claims) and, when you run `configure` / `install`, the runner hook config files and manifest in the repo. `uninstall` removes the ev-ai entries.
+
+**Subprocesses.** `git`, and for OS / host detection `sw_vers`, `uname`, `lsb_release`, `tty`, `systemd-detect-virt`; `sqlite3` as a fallback reader for Cursor's `state.vscdb`. All are invoked with fixed argument lists (no shell) and short timeouts.
+
+**Content capture.** Prompt, tool-argument, tool-result and last-assistant-message bodies are sent by default (size-capped). Turn them off with `EV_AI_HOOK_CAPTURE_CONTENT=off`. See [Privacy defaults](#privacy-defaults).
+
+**Shipped code is bundled and minified** (`dist/*.mjs`, built with esbuild from TypeScript).
+
 ## Install
 
 **Primary path:** enable the ev-ai **runner plugins** (Claude / Cursor / Codex) from the hosted marketplace. Their hooks run the shipped `hook.mjs` with Node (no package version in the command). Your repo commits only a shared `collector_url` manifest plus plugin enablement — not per-event blocks in `.claude/settings.json` / `.cursor/hooks.json` / `.codex/hooks.json`.
@@ -134,12 +165,12 @@ Per-event execution uses `npx` (primary) or the pinned binary (CDN path). The ru
 
 ### Hook updates (npx path)
 
-The npx package's entry point is a small launcher. It runs the hook your collector selects, from a per-machine cache under `~/.ev-ai/agent-hook/js/`, and otherwise the hook bundled in the pinned package. A cached hook is re-verified (sha256) on every event, and any problem with it (missing, altered, incompatible with this Node or launcher, or failing to start twice in a row) falls back to the bundled hook for that event.
+The npx package's entry point is a small launcher. It runs the hook your collector selects, from a per-machine cache under `~/.ev-ai/agent-hook/js/signed-v1/`, and otherwise the hook bundled in the pinned package. A cached hook is re-verified (signature + SHA-512) on every event, and any problem with it (missing, altered, unsigned, incompatible with this Node or launcher, or failing to start twice in a row) falls back to the bundled hook for that event.
 
 **Network.** Besides the collector POST, the launcher makes two kinds of request, both only on the npx path:
 
 - `GET /{orgToken}/version` on the same collector, at most once per 6 h per collector: on the first event in a new collector scope, then from a detached background refresh at session start. No request is made on other events.
-- When the collector names a release, a download of that release's npm tarball from `https://registry.npmjs.org/@ev-ai/agent-hook/-/`. The tarball is checked against the sha512 integrity the collector sent before it is unpacked, and only `package.json` and `dist/hook.mjs` are extracted. No other destination is contacted.
+- When the collector returns a signed envelope, a download of that release's `hook.mjs` from the signed URL (`https://…/{version}/hook.mjs`). The launcher verifies the envelope with a built-in public key, then checks the bytes against the signed SHA-512 before they are written to the cache. The launcher never downloads from npm and does not hardcode a CDN hostname.
 
 **Kill switch.** `EV_AI_AUTO_UPDATE=0`, or `"auto_update": false` in `~/.ev-ai/config.json`, always runs the bundled hook and makes neither request. Ephemeral CI homes start cold on every run, so their first event makes the `/version` check (within a 3 s budget); set `EV_AI_AUTO_UPDATE=0` in CI if you want the pinned hook with no extra request.