@lhi/tdd-audit 1.15.0 → 1.18.0

package/docs/rest-api.md

@@ -1,6 +1,6 @@
 # REST API
 
-`tdd-audit serve` turns the scanner into an authenticated HTTP API built on **Fastify**. Use it to integrate vulnerability scanning and AI remediation into dashboards, CI pipelines, bots, or any tooling that speaks JSON.
+`tdd-audit serve` exposes an authenticated HTTP API built on **Fastify**. Use it to integrate AI-powered security audits into dashboards, CI pipelines, bots, or any tooling that speaks JSON.
 
 ---
 
@@ -59,7 +59,7 @@ By default the rate limiter keys on the **socket IP**, not `X-Forwarded-For`, to
 
 ### Path validation
 
-`POST /scan` and `POST /audit` validate that the requested path is inside the server's working directory. The check is normalised with a trailing path separator to prevent sibling-directory prefix bypasses (e.g. `/app-evil` cannot escape via `/app`). Paths outside cwd return `400`.
+`POST /audit` and `POST /audit/ai` validate that the requested path is inside the server's working directory. The check is normalised with a trailing path separator to prevent sibling-directory prefix bypasses (e.g. `/app-evil` cannot escape via `/app`). Paths outside cwd return `400`.
 
 ### Security headers
 
@@ -80,60 +80,117 @@ X-Frame-Options:         DENY
 No auth required. Returns server status and version.
 
 ```json
-{ "status": "ok", "version": "1.13.0" }
+{ "status": "ok", "version": "1.17.0" }
 ```
 
 ---
 
-### `POST /scan`
+### `POST /audit/ai`
 
-Scan a local path and return structured findings synchronously.
+**The primary endpoint.** Runs a full agentic LLM audit using tool calls (`read_file`, `list_files`, `search_in_files`, `write_file`). Returns immediately with a `jobId`; poll `GET /jobs/:id` or stream `GET /jobs/:id/stream` for results.
+
+Provider and API key can be supplied in the request body or pre-configured in `.tdd-audit.json`.
 
 **Request**
 ```json
 {
-  "path":   ".",
-  "format": "json"
+  "path":     ".",
+  "provider": "anthropic",
+  "apiKey":   "sk-ant-...",
+  "model":    "claude-opus-4-6",
+  "baseUrl":  null,
+  "depth":    "tier-2"
 }
 ```
 
-| Field | Type | Default | Description |
+| Field | Required | Default | Description |
 |---|---|---|---|
-| `path` | string | cwd | Absolute or relative path to scan. Must be inside server cwd. |
-| `format` | `"json"` \| `"sarif"` | `"json"` | Output format |
+| `path` | no | cwd | Path to audit. Must be inside server cwd. |
+| `provider` | yes* | cfg | `anthropic` \| `openai` \| `gemini` \| `ollama` |
+| `apiKey` | yes* | cfg | Provider API key |
+| `model` | no | provider default | Model override |
+| `baseUrl` | no | — | Base URL for OpenAI-compatible services |
+| `depth` | no | `tier-1` | Output depth tier (see below) |
+| `scanOnly` | no | — | Override depth-derived scan mode |
+| `allowWrites` | no | `false` | Override depth-derived write permission |
+| `findings` | no | — | Pre-identified findings array (triggers targeted-apply mode when `depth=tier-4`) |
+
+*Required unless configured in `.tdd-audit.json`.
+
+**Response — 202 Accepted**
+
+```
+HTTP/1.1 202 Accepted
+Location: /jobs/job_1_...
+Retry-After: 5
+```
+```json
+{ "jobId": "job_1_1711363200000" }
+```
+
+**Job result envelope** (available via `GET /jobs/:id` after completion)
 
-**Response — JSON**
 ```json
 {
-  "version":              "1.13.0",
-  "summary":              { "CRITICAL": 1, "HIGH": 3, "MEDIUM": 1, "LOW": 0 },
-  "findings":             [ ... ],
+  "version":             "1.16.0",
+  "provider":            "anthropic",
+  "model":               "claude-opus-4-6",
+  "depth":               "tier-2",
+  "mode":                "scan-only",
+  "stack":               "Node.js / Express",
+  "summary":             { "CRITICAL": 1, "HIGH": 2, "MEDIUM": 0, "LOW": 1 },
+  "patchesApplied":      0,
+  "findings":            [ ... ],
   "likelyFalsePositives": [ ... ],
-  "exempted":             [],
-  "scannedAt":            "2026-03-25T12:00:00.000Z",
-  "duration":             42
+  "remediation":         [],
+  "scannedAt":           "2026-03-26T12:00:00.000Z"
 }
 ```
 
-**Response — SARIF**
+`patchesApplied` is the billable unit for `tier-4`: the count of `remediation` entries where `status === "fixed"`.
+
+---
+
+### Depth tiers
+
+| Tier | Mode | Finding fields added | `allowWrites` |
+|---|---|---|---|
+| `tier-1` | scan-only | `name`, `severity`, `file`, `line`, `snippet` | no |
+| `tier-2` | scan-only | + `risk`, `effort`, `cwe`, `owasp`, `references` | no |
+| `tier-3` | full audit | + `patch` (copy-ready), `testSnippet` | no |
+| `tier-4` | full audit | LLM calls `write_file`; `remediation` array tracks each patch | yes |
+
+---
+
+### Targeted apply (tier-4 + findings)
 
-Returns a SARIF 2.1.0 object ready to upload to GitHub code scanning.
+When `depth=tier-4` and a `findings` array is supplied, the LLM skips the scan phase entirely and applies only the patches you specify. Use this to apply a single finding from a previous tier-3 report:
 
-**Errors**
+```json
+{
+  "provider": "anthropic",
+  "apiKey":   "sk-ant-...",
+  "depth":    "tier-4",
+  "findings": [
+    {
+      "name":    "SQL Injection",
+      "file":    "src/db.js",
+      "line":    42,
+      "patch":   "const stmt = db.prepare('SELECT * FROM users WHERE id = ?');\nstmt.run(id);"
+    }
+  ]
+}
+```
 
-| Status | Reason |
-|---|---|
-| 400 | Path traversal attempt, oversized body (> 512 KB), or invalid JSON |
-| 401 | Missing or invalid API key |
-| 429 | Rate limit exceeded |
+The job mode will be reported as `targeted-apply/tier-4(1)`. Only the listed findings are touched — no full re-scan.
 
 ---
 
 ### `POST /remediate`
 
-Queue an AI-powered remediation job for a **provided findings list**. Returns immediately with a `jobId`; poll `GET /jobs/:id` (or stream `GET /jobs/:id/stream`) for results.
+Queue an AI-powered remediation job for a **provided findings list**. Returns immediately with a `jobId`.
 
-Use `POST /audit` instead if you want the server to run the scan itself.
+Use `POST /audit/ai` for a fully agentic audit instead.
 
 **Request**
 ```json
@@ -142,34 +199,28 @@ Use `POST /audit` instead if you want the server to run the scan itself.
   "provider": "anthropic",
   "apiKey":   "sk-ant-...",
   "model":    "claude-opus-4-6",
-  "baseUrl":  null,
-  "severity": "HIGH"
+  "baseUrl":  null
 }
 ```
 
 | Field | Required | Description |
 |---|---|---|
-| `findings` | yes | Array of finding objects from `POST /scan` |
+| `findings` | yes | Array of finding objects |
 | `provider` | yes | `anthropic` \| `openai` \| `gemini` \| `ollama` |
 | `apiKey` | yes | Provider API key |
-| `model` | no | Defaults per provider (see [AI Remediation](ai-remediation.md)) |
-| `baseUrl` | no | Override base URL for any OpenAI-compatible service |
-| `severity` | no | Minimum severity to fix. Default: `LOW` (fix all) |
+| `model` | no | Defaults per provider |
+| `baseUrl` | no | Override base URL for OpenAI-compatible services |
 
 **Response — 202 Accepted**
 ```json
 { "jobId": "job_1_1711363200000" }
 ```
 
-Job lifecycle: `pending → running → done | error`
-
 ---
 
 ### `POST /audit`
 
-Full automated pipeline: **scan + AI remediation in one shot**. No interaction needed. Returns immediately with a `jobId`.
-
-If no `provider`/`apiKey` are supplied, the server runs the scan only (no remediation) and the job transitions to `done` with just the `findings` array.
+Static scan + AI remediation pipeline in one shot. Runs `quickScan` then passes findings to the remediator. If no `provider`/`apiKey` are supplied, runs the scan only.
 
 **Request**
 ```json
@@ -185,7 +236,7 @@ If no `provider`/`apiKey` are supplied, the server runs the scan only (no remedi
 
 | Field | Required | Description |
 |---|---|---|
-| `path` | no | Path to scan. Defaults to cwd. Must be inside server cwd. |
+| `path` | no | Path to scan. Defaults to cwd. |
 | `provider` | no | If supplied with `apiKey`, AI remediation runs after the scan |
 | `apiKey` | no | Provider API key |
 | `model` | no | Defaults per provider |
@@ -196,69 +247,21 @@ If no `provider`/`apiKey` are supplied, the server runs the scan only (no remedi
 
 ```
 HTTP/1.1 202 Accepted
-Location: /jobs/job_1_1711363200000
+Location: /jobs/job_1_...
 Retry-After: 2
 ```
-```json
-{ "jobId": "job_1_1711363200000" }
-```
 
 Job lifecycle: `pending → scanning → scanned → remediating → done | error`
 
-Poll `GET /jobs/:id` or stream `GET /jobs/:id/stream` for progress.
-
-**Job object during remediation**
-```json
-{
-  "id":        "job_1_...",
-  "status":    "remediating",
-  "total":     8,
-  "completed": 3,
-  "current":   "SQL Injection"
-}
-```
-
-**Job object when done**
-```json
-{
-  "id":          "job_1_...",
-  "status":      "done",
-  "createdAt":   "...",
-  "startedAt":   "...",
-  "completedAt": "...",
-  "findings":    [ ... ],
-  "results": [
-    {
-      "finding":        { ... },
-      "status":         "remediated",
-      "exploitTest":    { "filename": "__tests__/security/xss.test.js", "content": "..." },
-      "patch":          { "filename": "src/app.js", "diff": "..." },
-      "refactorChecks": ["npm test", "npm run test:security"]
-    }
-  ]
-}
-```
-
 ---
 
 ### `GET /jobs/:id`
 
-Poll for job status. Works for jobs created by both `POST /remediate` and `POST /audit`.
+Poll for job status. Works for jobs created by `POST /audit/ai`, `POST /remediate`, and `POST /audit`.
 
-**Response — pending / scanning**
+**Response — pending / running**
 ```json
-{ "id": "job_1_...", "status": "scanning", "createdAt": "..." }
-```
-
-**Response — remediating (with progress)**
-```json
-{
-  "id":        "job_1_...",
-  "status":    "remediating",
-  "total":     8,
-  "completed": 3,
-  "current":   "SQL Injection"
-}
+{ "id": "job_1_...", "status": "running", "depth": "tier-2", "createdAt": "..." }
 ```
 
 **Response — done**
@@ -269,7 +272,7 @@ Poll for job status. Works for jobs created by both `POST /remediate` and `POST
   "createdAt":   "...",
   "startedAt":   "...",
   "completedAt": "...",
-  "results":     [ ... ]
+  "result": { ... }
 }
 ```
 
@@ -293,18 +296,14 @@ curl -N http://localhost:3000/jobs/job_1_.../stream \
 
 **Event format**
 ```
-data: {"id":"job_1_...","status":"scanning","createdAt":"..."}
-
-data: {"id":"job_1_...","status":"scanned","findings":[...]}
-
-data: {"id":"job_1_...","status":"remediating","total":8,"completed":1,"current":"SQL Injection"}
+data: {"id":"job_1_...","status":"running","depth":"tier-2","log":"🔍 Exploring..."}
 
-data: {"id":"job_1_...","status":"done","completedAt":"...","results":[...]}
+data: {"id":"job_1_...","status":"done","completedAt":"...","result":{...}}
 ```
 
-The connection is closed automatically after the terminal state (`done` / `error`). If you connect to an already-completed job, the server pushes the current state and closes immediately.
+The connection closes automatically after the terminal state. Connecting to an already-completed job pushes the current state and closes immediately.
 
-**Node.js example using EventSource**
+**Node.js example**
 ```javascript
 const es = new EventSource(
   'http://localhost:3000/jobs/job_1_.../stream',
@@ -312,7 +311,7 @@ const es = new EventSource(
 );
 es.onmessage = (e) => {
   const job = JSON.parse(e.data);
-  if (job.status === 'done') { console.log(job.results); es.close(); }
+  if (job.status === 'done') { console.log(job.result); es.close(); }
   if (job.status === 'error') { console.error(job.error); es.close(); }
 };
 ```
@@ -321,28 +320,19 @@ es.onmessage = (e) => {
 
 ## Full workflow examples
 
-### curl — scan only
+### curl — tier-2 audit with polling
 
 ```bash
 npx @lhi/tdd-audit serve --port 3000 --api-key mysecret &
 
-curl -s -X POST http://localhost:3000/scan \
-  -H "Authorization: Bearer mysecret" \
-  -H "Content-Type: application/json" \
-  -d '{"path": "."}' | jq '.summary'
-```
-
-### curl — full pipeline with polling
-
-```bash
-# Kick off audit
-JOB=$(curl -s -X POST http://localhost:3000/audit \
+# Start the audit
+JOB=$(curl -s -X POST http://localhost:3000/audit/ai \
   -H "Authorization: Bearer mysecret" \
   -H "Content-Type: application/json" \
   -d '{
-    "path":     ".",
     "provider": "anthropic",
-    "apiKey":   "sk-ant-..."
+    "apiKey":   "sk-ant-...",
+    "depth":    "tier-2"
   }' | jq -r '.jobId')
 
 # Poll until done
@@ -351,30 +341,53 @@ while true; do
     -H "Authorization: Bearer mysecret" | jq -r '.status')
   echo "Status: $STATUS"
   [ "$STATUS" = "done" ] || [ "$STATUS" = "error" ] && break
-  sleep 2
+  sleep 3
 done
+
+# Print findings summary
+curl -s http://localhost:3000/jobs/$JOB \
+  -H "Authorization: Bearer mysecret" | jq '.result.summary'
 ```
 
-### curl — SARIF output for GitHub code scanning
+### curl — tier-3 report then targeted apply
 
 ```bash
-curl -s -X POST http://localhost:3000/scan \
+# Step 1: get copy-ready patches (no writes)
+JOB=$(curl -s -X POST http://localhost:3000/audit/ai \
   -H "Authorization: Bearer mysecret" \
   -H "Content-Type: application/json" \
-  -d '{"path": ".", "format": "sarif"}' > results.sarif
+  -d '{"provider":"anthropic","apiKey":"sk-ant-...","depth":"tier-3"}' \
+  | jq -r '.jobId')
+
+# (wait for done)
+
+# Step 2: apply one specific patch
+FINDING=$(curl -s http://localhost:3000/jobs/$JOB \
+  -H "Authorization: Bearer mysecret" \
+  | jq '.result.findings[0]')
+
+curl -s -X POST http://localhost:3000/audit/ai \
+  -H "Authorization: Bearer mysecret" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"provider\": \"anthropic\",
+    \"apiKey\":   \"sk-ant-...\",
+    \"depth\":    \"tier-4\",
+    \"findings\": [$FINDING]
+  }" | jq '.jobId'
 ```
 
-### Node.js — scan
+### curl — SARIF output for GitHub code scanning
 
-```javascript
-const res = await fetch('http://localhost:3000/scan', {
-  method:  'POST',
-  headers: {
-    'Authorization': 'Bearer mysecret',
-    'Content-Type':  'application/json',
-  },
-  body: JSON.stringify({ path: '/path/to/project' }),
-});
-const { findings, summary } = await res.json();
-console.log(`CRITICAL: ${summary.CRITICAL}  HIGH: ${summary.HIGH}`);
+```bash
+JOB=$(curl -s -X POST http://localhost:3000/audit/ai \
+  -H "Authorization: Bearer mysecret" \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"anthropic","apiKey":"sk-ant-...","depth":"tier-2","format":"sarif"}' \
+  | jq -r '.jobId')
+
+# (wait for done)
+
+curl -s http://localhost:3000/jobs/$JOB \
+  -H "Authorization: Bearer mysecret" | jq '.result' > results.sarif
 ```

package/docs/scanner.md

@@ -1,10 +1,12 @@
 # Scanner Architecture
 
-`lib/scanner.js` is the core engine behind `npx @lhi/tdd-audit --scan` and the auto-audit skill. It is a pure Node.js module with no runtime dependencies — only `fs` and `path`.
+`lib/scanner.js` provides the static vulnerability pattern engine used internally by the tdd-audit skill and the `POST /audit` pipeline. It is a pure Node.js module with no runtime dependencies — only `fs` and `path`.
+
+> The scanner is an internal pre-processing component, not a standalone product. Customer-facing output is produced by the LLM audit (`--ai` / `POST /audit/ai`), which uses the scanner's signal as one input alongside its own tool-use exploration.
 
 ---
 
-## Entry points
+## Exports
 
 | Export | Purpose |
 |---|---|
@@ -64,7 +66,7 @@ Same skip rules, yields `.md` files only. Used by `scanPromptFiles`.
 
 `.js` `.ts` `.jsx` `.tsx` `.mjs` `.py` `.go` `.dart` `.yml` `.yaml`
 
-JSON and XML files are not walked by the code scanner. `package.json` is handled by `scanPackageJson()` and `.env*` files by `scanEnvFiles()` — both run as separate targeted checks. CI workflow files (`.yml`/`.yaml`) **are** now scanned by `walkFiles()` for GitHub Actions expression injection and similar patterns.
+JSON and XML files are not walked by the code scanner. `package.json` is handled by `scanPackageJson()` and `.env*` files by `scanEnvFiles()` — both run as separate targeted checks. CI workflow files (`.yml`/`.yaml`) **are** scanned by `walkFiles()` for GitHub Actions expression injection and similar patterns.
 
 ---