fix(security): harden live Coraza authority boundary

docs/architecture.md

@@ -43,7 +43,7 @@ flowchart LR
 
 ## Near-Term Integrations
 
-- **WAF**: Coraza/OWASP CRS audit JSON/NDJSON ingest is available at `POST /api/waf/coraza/audit` (admin token). Interrupted transactions and CRS rule messages become `SecurityEvent` rows and feed gateway enforcement (DNSBL + `client_ip`/`path` threat indicators) so subsequent gateway decisions block matching clients. In-process Coraza embedding remains a follow-up — do not replace CRS with hand-rolled rules.
+- **WAF**: Coraza/OWASP CRS audit JSON/NDJSON ingest is available at `POST /api/waf/coraza/audit` (admin token). The bounded `ProvenEngineConfig` port can also evaluate each live matched gateway request through a loopback Coraza sidecar before forwarding; Wardnet sends only method/effective URI/body/client IP plus a capped non-secret header allowlist, correlates response evidence to the exact request, fails block-mode traffic closed when the proven engine is unconfigured or its evidence is unusable, and preserves Coraza/CRS as detection authority. Runtime Configuration still owns how packaged deployments expose that adapter. Do not replace CRS with hand-written signatures or duplicate EgressWeave transport policy.
 - **IDS**: Suricata EVE JSON/NDJSON ingest is available at `POST /api/ids/suricata/eve` (admin token). Alert records become `SecurityEvent` rows for SOC export/KPI; full route correlation and live EVE tailing remain follow-ups.
 - **Threat Intelligence**: STIX 2.x indicator/bundle ingest is available at `POST /api/threat-intel/stix` (admin token), MISP Event/attribute JSON ingest at `POST /api/threat-intel/misp` (admin token), TAXII 2.1 collection poll at `POST /api/threat-intel/taxii/poll` (admin token; Basic/Bearer optional), OpenCTI observable/indicator export ingest at `POST /api/threat-intel/opencti` (admin token), and a CISA Known Exploited Vulnerabilities (KEV) catalog pull at `POST /api/threat-intel/cisa-kev` (admin token; fetches the official catalog and upserts one `cve` threat indicator per entry, severity escalated when CISA has tied the CVE to a known ransomware campaign). All update `ThreatIndicator` / `DnsblEntry` plus feed freshness. Live MISP REST pull and live OpenCTI GraphQL pull remain follow-ups.
 - **DNSBL Serving**: Hickory DNS should serve authoritative DNSBL responses directly after zone export semantics stabilize.

docs/doctoring/in-path-coraza-adapter.md

@@ -0,0 +1,35 @@
+# In-path Coraza request adapter
+
+## Decision boundary
+
+Wardnet owns route selection, monitor/block policy, security-event production, and the decision to forward a request. It does not own OWASP CRS detection logic. When a `ProvenEngineConfig` sidecar is configured, Wardnet submits each matched live gateway request to a same-host Coraza/OWASP CRS evaluator before forwarding. The adapter is intentionally loopback-only; executable general-purpose egress authorization remains EgressWeave ownership and is not copied into Wardnet.
+
+The request envelope contains method, effective gateway URI, body, client address when known, a bounded non-secret header allowlist, Wardnet route-policy identity, contract identifier `coraza-live-evaluate-v1`, and a bounded Wardnet `correlation_id`. `Authorization`, `Cookie`, `Proxy-Authorization`, and `X-Admin-Token` are never forwarded. Raw `X-Forwarded-For` and `X-Real-IP` are also withheld until Wardnet's trusted-proxy attribution owner reaches protected truth; the sidecar receives the transport-derived `client_ip` separately. Header forwarding is capped at 32 fields / 8 KiB. If any allowlisted value cannot be represented as UTF-8 or the complete allowlisted envelope would exceed either cap, Wardnet records `engine_unavailable` and does not call the sidecar; a partial request projection is never eligible for a clean verdict. The v1 JSON envelope can carry the body only as UTF-8 text. The gateway obtains that text through `String::from_utf8_lossy`, whose `Cow` ownership records whether the original request bytes were already valid UTF-8. The adapter accepts only the borrowed projection: valid UTF-8 is therefore preserved exactly, including a literal U+FFFD present in the original request. An owned projection proves that invalid input bytes were replaced, so Wardnet records `engine_unavailable` without calling Coraza and block mode fails closed rather than accepting a verdict over altered bytes. A future binary-safe owner contract may remove this UTF-8 limitation while preserving byte identity end to end. Sidecar evaluation has a 1.5 s timeout and a 1 MiB response cap.
+
+The correlation value is evidence binding, not authentication. Wardnet combines a process-randomized prefix with an atomic per-process sequence so concurrent evaluations cannot share an identifier and a restarted process is distinguishable with overwhelming practical probability. The sidecar must return the exact `wardnet.correlation_id` it received. Method and URI remain additional context, but neither is sufficient replay authority by itself. A response that omits the correlation value or returns a stale value from a prior same-route request is uncorrelated evidence even when method and URI match.
+
+A sidecar response is not accepted merely because it is HTTP 2xx. Wardnet requires parseable JSON evidence carrying the exact current `wardnet.correlation_id` plus the exact request method and URI. A clean decision additionally requires an explicit non-interrupted transaction, a response status below 400, and an empty messages array. Coraza/CRS rule messages retain their rule text/ID as SOC evidence, but the live adapter projects enforcement authority separately: only explicit `is_interrupted=true`, HTTP 403/406 from the sidecar, or transaction response 403/406 is disruptive. Disruptive evidence is subject to the same exact-request correlation requirement as clean evidence. A non-interrupted successful transaction with rule messages remains monitor evidence and is never promoted to a block merely because audit severity maps to a high score. Wardnet adds policy identity plus sidecar ruleset identity when supplied. An unconfigured engine and malformed, oversized, uncorrelated, timed-out, or unreachable evidence are `engine_unavailable`; a block-mode route fails closed with HTTP 503. Independent Wardnet threat/DNSBL evidence may deny a request first; Coraza is the required authorization boundary only for block-mode traffic that has not already been denied and would otherwise proceed upstream. Monitor mode records the degraded evidence and may continue, preserving route-scoped semantics.
+
+The dedicated Coraza client also disables ambient HTTP proxy inheritance and redirects. Validation of a loopback URL is not enough if `HTTP_PROXY`/`ALL_PROXY` can divert the inspection envelope, so `tests/coraza_loopback_proxy_boundary.rs` installs an attacker-controlled ambient proxy and requires it to observe zero Coraza calls.
+
+`tests/coraza_proven_engine_adapter.rs` uses a protocol fixture, not a substitute detector. The fixture returns Coraza-shaped block/clean evidence by test URI so the test proves Wardnet forwards the hostile `User-Agent`, excludes credential-bearing headers, carries and echoes the current correlation, enforces block versus monitor semantics, and fails closed on unusable engine evidence. `tests/coraza_exact_request_binding.rs` proves that method/URI-only evidence and a replayed correlation captured from the prior same-route request both fail closed. `tests/coraza_non_utf8_body.rs` proves both sides of the request-body identity boundary: invalid UTF-8 bytes must produce HTTP 503 without invoking the sidecar, while valid UTF-8 containing a literal U+FFFD must reach the sidecar exactly and may receive a correlated clean verdict. Production detection authority remains a real Coraza deployment with a pinned OWASP CRS ruleset.
+
+## Operational acceptance
+
+Before exposing a block-mode route through this boundary, deploy the Coraza evaluator on loopback, pin and inventory the CRS policy/ruleset, then construct `AppState` with `ProvenEngineConfig::sidecar(...)`. The sidecar adapter must echo `wardnet.correlation_id` from each request into the matching response without caching or substituting a prior value. A legacy fixture or sidecar that returns only method/URI is intentionally incompatible and will produce `engine_unavailable`/HTTP 503 in block mode. The current bounded slice does not add a new environment-variable or database configuration source because Runtime Configuration is owned by its separate Wardnet lane. That owner must expose the released/configured adapter without reintroducing handler-time environment reads before this becomes a packaged production default.
+
+Treat `engine_unavailable` events as protection-loss evidence. Do not convert malformed, stale, or uncorrelated evidence to `Clean`, and do not add local request signatures to compensate for a missing Coraza engine.
+
+Hosted successor run `35509666499` re-proved the earlier hostile request-context boundaries, passed the focused Coraza suites, the full locked workspace test suite, formatting, and strict Clippy, then promoted the reviewed production candidate as `ede52a7a25efc2f98e47b64802484009a43a8532`. That commit predates the exact-request correlation repair and remains historical candidate evidence only, not protected-branch or release evidence. Any later PR head must reacquire its own exact-head checks, reviews, and thread state before normal protected integration.
+
+## Traceability
+
+Coraza. (n.d.). *Coraza Web Application Firewall documentation*. https://coraza.io/docs/
+
+National Institute of Standards and Technology. (2007). *Guide to intrusion detection and prevention systems (IDPS)* (NIST Special Publication 800-94). https://doi.org/10.6028/NIST.SP.800-94
+
+OWASP Foundation. (2025). *OWASP Core Rule Set documentation*. https://coreruleset.org/docs/
+
+Saltzer, J. H., & Schroeder, M. D. (1975). The protection of information in computer systems. *Proceedings of the IEEE, 63*(9), 1278–1308. https://doi.org/10.1109/PROC.1975.9939
+
+These references ground the use of a proven WAF/ruleset authority, evidence correlation, and fail-safe treatment of unavailable or unverifiable decisions. They are rationale, not evidence that a specific Coraza/CRS build has been deployed or released. No paper PDF is added in this lane because redistribution permission for the exact retrieved versions was not independently established.

docs/runbooks/operations.md

@@ -86,6 +86,14 @@ When `WAF_IDS_STATE_PATH` is enabled, the process writes a temporary sibling fil
 4. Keep the previous route JSON available for rollback.
 5. Disable the route or switch back to `monitor` if legitimate traffic is blocked.
 
+## Coraza Sidecar Acceptance
+
+When a block-mode route uses `ProvenEngineConfig`, the Coraza evaluator must run on the configured loopback endpoint. Wardnet's dedicated sidecar transport ignores ambient `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY` settings and does not follow redirects. Do not add proxying or non-loopback sidecar endpoints locally; broader executable outbound authorization belongs to EgressWeave through a released owner contract.
+
+Each `coraza-live-evaluate-v1` request includes `wardnet.correlation_id`. The sidecar adapter must echo that exact value in the matching JSON response. It must not cache, reuse, normalize, or substitute a correlation value from another request. A response with no correlation value, a stale value from a prior same-method/same-URI request, malformed JSON, an oversized body, or a timeout/connect failure is `engine_unavailable`; block mode returns HTTP 503 rather than treating it as clean evidence. This applies to disruptive evidence as well as clean evidence.
+
+If a newly deployed sidecar causes a sudden rise in `engine_unavailable`, first verify that its response adapter echoes `wardnet.correlation_id` from the same request and preserves method/URI. Do not disable the correlation check as a recovery measure. Roll back the sidecar adapter or the route to the previous safe/monitor configuration instead.
+
 ## Commercial Readiness Procedure
 
 1. Register buyer-approved license metadata through `POST /api/commercial/license`.
@@ -103,7 +111,7 @@ This baseline is suitable for local and controlled lab deployments. Internet-fac
 - durable database storage with backups
 - SSO/OIDC federation (multi-token RBAC with readonly role and audit-log auth are available)
 - asynchronous event persistence or a database-backed event store for high-throughput gateway traffic
-- In-process Coraza embedding (HTTP audit ingest at `POST /api/waf/coraza/audit` already fuses block hits into DNSBL/`client_ip` indicators for gateway enforcement)
+- Package the live Coraza boundary: the code-level `ProvenEngineConfig` loopback sidecar port now evaluates matched requests, binds accepted verdict evidence to a request-unique Wardnet correlation plus method/URI, and fails block mode closed when the proven engine is unconfigured or its evidence is unusable, while Runtime Configuration still owns its deployment/bootstrap surface. Audit ingest at `POST /api/waf/coraza/audit` remains available for SOC evidence.
 - Live Suricata EVE tailing / shipper (HTTP ingest of EVE alerts is available at `POST /api/ids/suricata/eve`)
 - Live MISP REST pull or live OpenCTI GraphQL pull (HTTP STIX/MISP/OpenCTI document ingest and TAXII 2.1 poll are available at `POST /api/threat-intel/stix`, `POST /api/threat-intel/misp`, `POST /api/threat-intel/opencti`, and `POST /api/threat-intel/taxii/poll`)
 - human approval workflow for AI SOC recommendations that change enforcement

docs/security/gateway-header-mediation.md

@@ -0,0 +1,39 @@
+# Gateway header mediation contract
+
+Status: candidate security contract for PR #441; not released or authoritative on the protected branch until that PR is merged.
+
+Wardnet owns the generic gateway/SOC mediation boundary. This contract is deliberately narrower than an HTTP-transparent proxy: it preserves only application metadata required by the buyer path and rejects or removes transport, framing, management, and proxy authority that must not cross the gateway trust boundary. Egress authorization, sandbox isolation, LLM routing, and application guardrail semantics remain with their canonical owner repositories.
+
+## Request boundary
+
+The generic gateway admits only `Content-Type`, `Accept`, and bounded `X-Wardnet-App-Meta` values to the routed upstream. `X-Admin-Token`, `Authorization`, cookies, proxy credentials, client-supplied forwarding identity, `Host`, framing fields, upgrades, and other unlisted fields are not forwarded.
+
+`Content-Type` and `X-Admin-Token` are treated as security-relevant singletons at this boundary. Duplicate instances fail closed with `400 Bad Request`. The aggregate byte length of `X-Wardnet-App-Meta` is capped at 16,384 bytes before route-upstream contact. Any field nominated by `Connection` is removed even if that field would otherwise be admitted.
+
+This follows RFC 9110 section 7.6.1: an intermediary must parse `Connection`, remove every field named by a connection option, and remove `Connection` itself before forwarding. The allowlist is an intentional Wardnet policy restriction rather than an attempt to redefine HTTP semantics.
+
+## Response boundary
+
+Wardnet reconstructs the downstream response from an explicit response allowlist. The current candidate admits `Content-Type`, bounded `X-Wardnet-App-Meta`, `Location`, `Retry-After`, and `WWW-Authenticate`; it does not reflect `Connection`, fields named by `Connection`, proxy-authentication fields, upgrades, cookies, or other unadmitted authority.
+
+An invalid admitted upstream header envelope fails closed as `502 Bad Gateway`. `Content-Type` is currently enforced as a singleton. Response-singleton hardening for `Location` and `Retry-After` is tracked separately so this PR does not silently expand its causal scope: RFC 9110 sections 10.2.2 and 10.2.3 define each with a single field value grammar.
+
+`Content-Encoding` is representation metadata under RFC 9110 section 8.4, not hop-by-hop metadata. It is therefore a separate follow-on acceptance gap rather than something Wardnet may drop while relaying coded bytes. Transparent decompression is not an acceptable shortcut unless every affected representation field is transformed consistently.
+
+## Acceptance evidence
+
+The hostile buyer suite in `tests/gateway_header_mediation.rs` must exercise a real loopback upstream, not a mocked header helper alone. GREEN requires all of the following on one exact head:
+
+- admitted request media type, content negotiation, and bounded repeated application metadata survive the gateway;
+- duplicated management credentials, duplicated request `Content-Type`, and oversized application metadata fail before the routed upstream receives the request;
+- `Host`, framing authority, credentials, cookies, proxy authority, forwarding identity, upgrades, and dynamically connection-nominated fields do not cross the request boundary;
+- admitted upstream representation metadata survives the response boundary while fixed and dynamically nominated hop-by-hop/security authority does not;
+- repository CI, fuzzing, security/SAST/CodeQL governance, coverage/rustdoc evidence, buyer-path latency evidence, and parent/base compatibility are reacquired for the exact candidate head.
+
+A workflow result that is queued, `action_required`, skipped without jobs, or attached to a predecessor SHA is not transferable GREEN evidence.
+
+## References
+
+Fielding, R., Nottingham, M., & Reschke, J. (2022). *HTTP semantics* (RFC 9110). RFC Editor. https://www.rfc-editor.org/rfc/rfc9110
+
+Fielding, R., Nottingham, M., & Reschke, J. (2022). *HTTP/1.1* (RFC 9112). RFC Editor. https://www.rfc-editor.org/rfc/rfc9112