#6405: feat(security): Add HTTP API security hooks for plugin scanning

## Summary This PR adds 4 new plugin hooks to protect HTTP API endpoints from prompt injection and data exfiltration attacks. **Related Discussion:** #6098 **Previous PR:** #6099 (closed for rebase) ## Problem OpenClaw's HTTP API endpoints currently **bypass ALL plugin security hooks**: | Endpoint | Hook Coverage | Risk | |----------|---------------|------| | `/v1/chat/completions` | ❌ None | **Critical** | | `/v1/responses` | ❌ None | **Critical** | | `/tools/invoke` | ❌ None | **Critical** | Any application using the API directly (SDKs, curl) has zero protection against: - Prompt injection attacks - Data exfiltration via LLM responses - Tool argument injection - Indirect injection via tool results ## Solution Added 4 new plugin hooks: | Hook | Purpose | Execution | |------|---------|-----------| | `http_request_received` | Scan/block incoming requests | Sequential (can block) | | `http_response_sending` | Scan/block responses for leaks | Sequential (can block) | | `http_tool_invoke` | Scan/block tool arguments | Sequential (can block) | | `http_tool_result` | Scan/block tool results | Sequential (can block) | ### Security Features - **FAIL-CLOSED**: Hook errors/timeouts block requests (not bypass) - **Header redaction**: Authorization/Cookie/X-API-Key redacted - **Request ID**: For correlation/audit logging ## Changes | File | Lines | Description | |------|-------|-------------| | `src/plugins/types.ts` | +157 | Hook type definitions | | `src/plugins/hooks.ts` | +126 | Hook runners | | `src/gateway/openai-http.ts` | +166 | Hooks for `/v1/chat/completions` | | `src/gateway/openresponses-http.ts` | +103 | Hooks for `/v1/responses` | | `src/gateway/tools-invoke-http.ts` | +108 | Hooks for `/tools/invoke` | | `src/plugins/http-hooks.test.ts` | +387 | 13 unit tests | **Total: 651 lines added, 9 lines removed** ## Test Plan - [x] 13 new unit tests covering all hooks - [x] Tests for error handling (fail-closed behavior) - [x] Tests for hook priority ordering - [x] TypeScript compilation passes - [x] All existing tests unaffected - [x] Rebased on latest main (26 new commits) ```bash npx vitest run src/plugins/http-hooks.test.ts # ✓ 13 tests pass ``` ## Usage Example Security plugins can now register for HTTP hooks: ```typescript api.on("http_request_received", async (event, ctx) => { const result = await scanForInjection(event.content); if (result.isInjection) { return { block: true, blockReason: "Prompt injection detected", blockStatusCode: 400 }; } }); api.on("http_response_sending", async (event, ctx) => { const result = await scanForLeaks(event.content); if (result.hasLeak) { return { block: true, blockReason: "Credential leak detected" }; } }); ``` ## Real-World Plugin This PR enables [Citadel Guard](https://github.com/TryMightyAI/citadel-guard-openclaw), a security plugin that: - Scans for prompt injection using ML models - Detects credential/PII leaks in responses - Provides multi-turn attack detection - Works with both OSS and Pro Citadel backends The plugin already has conditional hook registration to work with both current OpenClaw (messaging hooks) and this PR (HTTP hooks). ## Known Limitations 1. **Streaming responses**: Output scanning only works for non-streaming responses. Streaming would require buffering which breaks the streaming UX. ## Breaking Changes None. New hooks are additive and don't affect existing behavior. <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> This PR introduces four new plugin hooks to apply security scanning/blocking to direct HTTP API consumers that previously bypassed plugin security coverage: request/response scanning for `/v1/chat/completions` and `/v1/responses`, plus tool param/result scanning for `/tools/invoke`. The gateway handlers now build a redacted HTTP context (headers/IP/requestId), invoke the appropriate hook runners in fail-closed mode (errors/blocks return 4xx/5xx), and support request-body replacement and response content modification in non-streaming paths. For streaming responses, it accumulates content and runs an end-of-stream audit hook (cannot retroactively block already-sent data). Hook runner support and unit tests were added in the plugins layer to execute these hooks sequentially with priority ordering and merged results. <h3>Confidence Score: 4/5</h3> - This PR is generally safe to merge, with one notable behavioral ambiguity around how multiple security hook handlers’ decisions are merged. - Core changes are additive, covered by new unit tests, and the gateway integrations appear consistent with the intended fail-closed semantics. The main concern is merge semantics for the new HTTP hook results: the current `next.field ?? acc?.field` pattern allows later (lower-priority) handlers to explicitly undo earlier decisions (e.g., unblock), which may be undesirable for security and could surprise plugin authors. - src/plugins/hooks.ts (HTTP hook merge semantics) <!-- greptile_other_comments_section --> <!-- /greptile_comment -->