middleware.audit

HTTP audit middleware — opt-in per-request who/what/when/status trail.

AuditMiddlewareemits one structured event per (audited) request through the existingemit_security_event() sink, under an http.requestnamespace — so general request auditing and auth/CSRF telemetry flow through one pipeline (one sink, one SIEM forwarder).

It is opt-in and off by default (explicit-over-magic, like the auth leg): nothing is emitted unlessAuditConfig.level is raised above "none". Wire it viasecure_stack(config, audit=AuditConfig(level="metadata"))or app.add_middleware(AuditMiddleware(AuditConfig(...))).

Verbosity is tiered (NONE < METADATA < REQUEST < REQUEST_RESPONSE):

• none— disabled; emit nothing.
• metadata— who/what/when/status only (method, path, status_code, source_ip, user_agent, user_id). No body capture.
• request— metadata plus a byte-capped, redacted snapshot of the request body for audited methods.
• request_response — reserved; treated as requestfor body capture (response-body capture is intentionally not implemented to avoid buffering large/streaming responses).

Hypermedia correctness (the critical safety property): the middleware runs afternext()has resolved the response, then branches on the response type. ForStreamingResponse / SSEResponse / FileResponse (Chirp'sStream / Suspense / EventStreamreturn types resolve to these) it downgrades to metadata-only and never touches request.body() / request.form()— draining a streaming request would buffer unbounded or break the stream, and a request body already consumed by the handler is read from cache only when present.

Source IP comes fromtrusted_client_ip— the trusted-proxy-corrected client, never a re-parsed (spoofable)X-Forwarded-For.

User identity comes fromrequest.user.idand is only non-anonymous when AuthMiddlewareis wired upstream; without it the trail records an anonymous user (it never crashes).