@xaccefy/pi-casefile 0.9.3 → 0.10.0

package/README.md

@@ -1,88 +1,52 @@
-# pi-casefile
-
-Local security case book for Pi Agent. Keeps your guesses → proven findings behind a PoC gate, saved in SQLite, run in a sandbox.
+<div align="center">
 
-## Install
+# pi-casefile
 
-```bash
-pi install npm:@xaccefy/pi-casefile
-```
+**Security case ledger for the [Pi agent](https://github.com/earendil-works/pi-coding-agent)** — evidence tracking with machine-verified PoC gates.
 
-Or via the XPI umbrella package: `pi install npm:@xaccefy/pi-xpi`
+[![npm](https://img.shields.io/npm/v/@xaccefy/pi-casefile?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@xaccefy/pi-casefile)
+[![License: MIT](https://img.shields.io/github/license/xaccefy/pi-casefile?style=flat-square&color=blueviolet)](LICENSE)
 
-## XP mode (default OFF)
+</div>
 
-The attack-mode text stays **quiet by default** so your normal coding isn't buried in security talk.
+## What it is
 
-| Control | Effect |
-|---------|--------|
-| `/xp` | Toggle SWARM/OFF |
-| `/xp on` | Default enabled mode: SWARM |
-| `/xp swarm` | Bounded multi-agent workflow: auditor/tracer/skeptic/chain only |
-| `/xp lite` | Focused workflow: single-agent, no subagent dispatch |
-| `/xp off` | Quiet mode explicitly |
-| `PI_XP_MODE=on` | Force SWARM for this process (same as `swarm`) |
-| `PI_XP_MODE=swarm` | Force SWARM for this process (overrides file) |
-| `PI_XP_MODE=lite` | Force LITE (single-agent, no subagent dispatch) |
-| `PI_XP_MODE=off` | Force OFF |
+A structured ledger for offensive-security work — bug bounties, CTFs, audits — built around one idea: **an agent's claim is not evidence until the machine replays it**.
 
-When **LITE**, every prompt gets the attacker-minded workflow plus any open cases, done by the main agent alone — no `subagent` dispatch (CTF / single-shot engagements). When **SWARM**, the bounded pipeline is injected and only auditor/tracer/skeptic/chain are delegated; validation, patching, reporting, and ConfirmFinding stay with the main agent. When **OFF**, nothing is added; tools still work.
+Cases move `hypothesis → investigating → confirmed → reported`. Promotion between phases is gated:
 
-State is persisted next to the ledger as `xp-mode` (e.g. `.pi/xp-mode`).
+- **Zero exit is necessary but never proof** — direct-response findings require nonce-bound body evidence plus a DNS-pinned, conclusive `target_only` replay against an operator-approved control
+- **Differential confirmation** — `inter_host` (attack vs control host) or `intra_target` (attack vs baseline request) so "it worked" means *the discriminator fired*, not "the agent said so"
+- **Blind/OOB classes** confirm through an operator-run oracle with per-run tokens and source-separation attestation
+- Only the main agent makes the semantic decision and commits phase transitions
 
-## Environment
+Designed for **human + AI workflows**: every confirmed finding carries a reproducible evidence trail a human can audit.
 
-| Variable | Purpose |
-|----------|---------|
-| `PI_CASEFILE_PATH` | Absolute path to the SQLite ledger file |
-| `CASEFILE_WORKSPACE_ROOT` / `PI_WORKSPACE_ROOT` | Override workspace root used to place `.pi/casefile.db` |
-| `PI_POC_ALLOW_NETWORK=1` | Operator authorization for a networked PoC sandbox |
-| `PI_POC_ALLOW_PRIVATE_REPLAY=1` | Operator authorization for harness replay to private/internal targets |
-| `PI_POC_CONTROL_TARGETS` | Comma/newline-separated operator-approved control hosts/origins; agent-invented controls are rejected |
+## Tools
 
-Default DB path: `<workspace>/.pi/casefile.db`
+| Tool | Purpose |
+|---|---|
+| `CaseAdd` / `CaseList` / `CaseUpdate` / `CaseContext` | case lifecycle and context retrieval |
+| `EvidenceAdd` | attach raw evidence to a case |
+| `PromoteFinding` → harness replay → `ConfirmFinding` | gated finding pipeline |
+| Scratchpad | phase-scoped working notes, resume-safe |
 
-## State machine
+## Install
 
+```bash
+pi install npm:@xaccefy/pi-casefile
 ```
-hypothesis → investigating → confirmed → reported
-                 ↓               ↓
-              blocked         killed (terminal)
-```
-
-- **investigating** needs `evidence` + `confidence`
-- **confirmed** only through the two-phase gate — `PromoteFinding` runs the PoC 2× target + 1× control, requires complete zero-exit runs and nonce-bound discriminating response-body evidence, then the harness performs a DNS-pinned identical replay and requires two conclusive responses with `target_only`. Reflection-capable requests may add a post-PoC harness-generated canary that must appear only on target. Status-only/trivial matchers and incomplete response capture are rejected. Exit zero is necessary but never proof. The main agent performs semantic review and calls `ConfirmFinding`, which captures a second fresh harness replay and binds it to the verdict; worker processes are rejected. Blind/OOB claims fail closed without a source-separated oracle.
-- **Every promotion requires a distinct `control_target`** pre-approved by the operator in `PI_POC_CONTROL_TARGETS`; an agent cannot invent its own easy control. `control_path` defaults to `poc_path` and exists only as an override — if supplied, it must contain the same bytes as the PoC (sha256 enforced). The control run is stored as `controlVerified`. Crashes, transport-inconclusive controls, status-only evidence, and missing evidence all block promotion.
-- **New cases require `disproveIf`** — falsification conditions (what would disprove this hypothesis). A hypothesis that can't say what kills it isn't one yet.
-- **A kill must be justified**: either an EvidenceAdd `refutation` item, or a canonical kill-reason token (intended_behavior, duplicate, framework_protection, out_of_scope, insufficient_impact, no_attack_path, ...) in assumptions/nextStep. Bare `status: "killed"` is rejected.
-- **reported** needs `CaseContext` first (records the report path; the main agent produces the final file)
-- **killed** / **reported** are final (no more edits)
 
-## Evidence items
-
-`EvidenceAdd` records role-typed, artifact-backed evidence (observation / reproduction / impact / refutation / cleanup). Artifact reads are restricted to regular, non-symlink files inside the workspace. Bytes are copied durably and stored as basename + SHA-256; the full source path is never persisted. The PoC gate auto-records the `reproduction` item at promotion.
-
-## Tools
-
-| Tool | Use |
-|------|-----|
-| `CaseAdd` | Open a case (`title` + `disproveIf` required; start as `hypothesis` or `investigating`) |
-| `CaseUpdate` | Evidence, impact, severity, status (not direct confirm) |
-| `EvidenceAdd` | Role-typed, hashed evidence item on a case (refutation justifies kills; cleanup tracks cleanup) |
-| `PromoteFinding` | Phase 1: main-agent-only PoC 2× target + 1× operator-approved control, then DNS-pinned harness-owned replay requiring conclusive `target_only`; optional reflection canary upgrades the recorded proof strength when observed only on target. `local:true` and private replay are operator-gated; blind/OOB proof fails closed without source separation |
-| `ConfirmFinding` | Phase 2: main-agent-only semantic decision plus a fresh harness-owned target/control replay (CONFIRMED promotes; NOT_CONFIRMED keeps investigating; worker/subagent gate calls are rejected) |
-| `CaseGet` / `CaseList` / `CaseSearch` | Read / filter / search |
-| `CaseLink` / `CaseUnlink` | Bidirectional exploit chains |
-| `ChainSuggest` | Scan cases for exploitable chain combinations (credential+endpoint→ATO, redirect+OAuth→token theft, XSS+state-change→CSRF, IDOR+user-data, SSTI→RCE, race+payment, info-disclosure+SSRF), ranked by confidence |
-| `CoverageAdd` | Record a tested (asset × attack-class) cell — `scope: wide` (deployment-wide verdict, applies to every later asset) or `local`; both found and clean results count. Optionally link the cell to an artifact-backed evidence item (`evidence_item_id`); unbacked cells render as ⚠ unbacked in the report |
-| `CoverageReport` | Render the machine-checkable coverage matrix (which classes are tested where; plateau claims must match it) |
-| `CaseContext` | Context bundle for a confirmed/reported case (full record, logs, links, artifacts) + report path |
-
-Commands: `/casefile` (dashboard), `/xp` (XP mode).
+Peer-depends on a Pi-compatible agent host (`@earendil-works/pi-coding-agent`, `pi-ai`, `pi-tui`, `typebox`). Runtime deps: `@xaccefy/pi-shared`, `undici`.
 
 ## Development
 
 ```bash
-bun test packages/pi-casefile
+bun install
+bun test --isolate   # 222 tests
 bun run typecheck
 ```
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xaccefy/pi-casefile",
-  "version": "0.9.3",
-  "description": "Offensive security case tracker for Pi Agent — bug bounties, CTFs, security audits",
+  "version": "0.10.0",
+  "description": "Offensive security case tracker for Pi Agent \u2014 bug bounties, CTFs, security audits",
   "keywords": [
     "pi-package",
     "pi-extension",
@@ -15,16 +15,17 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/xaccefy/pi-xpi.git",
-    "directory": "packages/pi-casefile"
+    "url": "git+https://github.com/xaccefy/pi-casefile.git"
   },
-  "homepage": "https://github.com/xaccefy/pi-xpi/tree/main/packages/pi-casefile#readme",
+  "homepage": "https://github.com/xaccefy/pi-casefile#readme",
   "bugs": {
-    "url": "https://github.com/xaccefy/pi-xpi/issues"
+    "url": "https://github.com/xaccefy/pi-casefile/issues"
   },
   "scripts": {
-    "test": "bun test test",
-    "typecheck": "tsc --noEmit --project tsconfig.json"
+    "test": "bun test --isolate",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write"
   },
   "publishConfig": {
     "access": "public",
@@ -34,30 +35,26 @@
     "src/index.ts",
     "src/evidence.ts",
     "src/harness-verify.ts",
+    "src/oob-oracle.ts",
+    "src/confirmation.ts",
+    "src/ledger-internal.ts",
     "src/safe-state.ts",
-    "src/ledger-worker.ts",
-    "src/ledger-worker-entry.ts",
     "src/ledger.ts",
-    "src/workflow.ts",
     "src/poc-runner.ts",
-    "src/pipeline-submit.ts",
     "src/scratchpad.ts",
+    "src/workflow.ts",
     "src/sqlite-compat/index.ts",
-    "skills",
     "README.md",
     "LICENSE"
   ],
   "main": "src/index.ts",
   "dependencies": {
-    "@xaccefy/pi-shared": "0.9.3",
+    "@xaccefy/pi-shared": "0.9.4",
     "undici": "^8.9.0"
   },
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ],
-    "skills": [
-      "./skills"
     ]
   },
   "devDependencies": {