feat(pipeline): Body mutation via WritesBody capability + SetBody helpers

[huang195]

Summary

Plugins can now rewrite request / response bodies. A plugin declares WritesBody: true and calls pctx.SetBody(newBytes) or pctx.SetResponseBody(newBytes); all three listeners (ext_proc, forward proxy, reverse proxy) propagate the rewrite to the upstream with correct Content-Length and cleared Content-Encoding. Enables prompt-redaction, LLM output filtering, DLP-style guardrails, and any other content-transform plugin — without each author wiring their own wire protocol.

Based on PR #386 (feat/open-plugin-registry). Merge that first; this rebases cleanly onto main afterward. Independent from PR #388 (hot-reload).

Before / after

Before — the BodyAccess: true flag told listeners to buffer. Response-body mutation was de-facto supported through undocumented diff-compare in three listeners (no capability gate, no Invocation). Request-body mutation was impossible.

After

// Capability declares intent; pipeline.New enforces ordering rules.
func (p *Redactor) Capabilities() pipeline.PluginCapabilities {
    return pipeline.PluginCapabilities{WritesBody: true} // implies ReadsBody
}

func (p *Redactor) OnRequest(_ context.Context, pctx *pipeline.Context) pipeline.Action {
    cleaned := redactSSNs(pctx.Body)
    pctx.SetBody(cleaned) // auto-emits modify Invocation + body-mutation/event
    return pipeline.Action{Type: pipeline.Continue}
}

Capability model

Field	Meaning	Listener effect
ReadsBody	plugin reads pctx.Body / pctx.ResponseBody	buffers the body
WritesBody	plugin may call pctx.SetBody / pctx.SetResponseBody	implies ReadsBody; propagates mutations
BodyAccess (deprecated)	legacy alias for ReadsBody	folded by Normalize(), removed in a future release

pipeline.New enforces:

1. At most one WritesBody per pipeline — multiple mutators = ambiguous ordering. Error names both plugins.
2. WritesBody must run after any ReadsBody — readers expect the original bytes.

Per-listener wire behavior

Listener	Request body	Response body
extproc	new withBodyMutation helper wraps RequestBody ProcessingResponse with ext_proc BodyMutation	same helper on the response-body path (replaces ad-hoc diff-compare)
forwardproxy	pctx.BodyMutated() → rebuild r.Body, set Content-Length, clear Content-Encoding	pctx.ResponseBodyMutated() → same pattern on resp.Body
reverseproxy	same as forwardproxy, before httputil.ReverseProxy	same as forwardproxy, in modifyResponse

Content-Encoding is always cleared on mutation — framework can't know if the plugin decompressed; shipping plain bytes without the encoding header is safer than shipping a malformed archive. Auto-decompress/recompress is explicitly out of scope.

Observability

Every SetBody / SetResponseBody auto-emits:

• A modify-action Invocation with Reason: "body_rewritten", framework-attributed to the mutating plugin.
• A body-mutation/event entry in pctx.Extensions.Custom with phase, plugin name, length before/after, sha256 before/after. Never the body content — the session store is unauthenticated.

Already renders in abctl via the generic plugin:body-mutation filter.

Waypoint mode (ext_authz) — not supported

ext_authz has no body-mutation field in CheckResponse. A pipeline combining mode: waypoint with any WritesBody: true plugin is caught at runtime; documented in plugin-reference.md.

Commit breakdown

1. feat(pipeline): Capability split for body mutation — ReadsBody + WritesBody + Normalize() + build-time validation
2. feat(pipeline): pctx.SetBody / SetResponseBody helpers — mutation API + 10 unit tests + auto-emitted Invocation + body-mutation/event with sha256/length deltas
3. refactor(plugins): Flip parsers from BodyAccess to ReadsBody — a2a, mcp, inference parsers migrated to the new alias
4. refactor(listeners): Use ResponseBodyMutated flag — replaces ad-hoc string-compare / nil-check heuristics in all 3 listeners
5. feat(listeners): Propagate request-body mutations to upstream — ext_proc BodyMutation wrap + r.Body rebuild + Content-Encoding clearing; one integration test per listener
6. docs: Body mutation lifecycle and plugin-author surface — framework-architecture §6.5 + plugin-reference + plugin-tutorial

Each commit compiles and passes tests independently. Steps 1-4 are net no-op (capability rename, response-path tidy); step 5 is where request-body mutation actually becomes a user-visible feature.

Test plan

• go test -race ./... green in authlib/ (10 new unit tests: Normalize, NeedsBody+WritesBody, two-mutator rejection, reader-after-mutator rejection, SetBody flag+invocation, SetBody custom event, SetResponseBody phase label)
• go test -race ./... green in cmd/authbridge/ (3 new listener integration tests: synthetic mutator plugin verifies each listener ships new bytes with correct Content-Length and cleared Content-Encoding)
• go vet ./... clean across both modules under GOWORK=off
• gofmt -l clean on touched files

Out of scope (possible followups)

• Metrics. authbridge_body_mutations_total{direction,phase} — deferred until there's a generic metrics surface (OTEL). Today's /stats is JWT/token-exchange specific.
• Streaming mutation (SSE, chunked bodies beyond buffer cap). A streaming-transform API is a separate design.
• Auto-decompress/recompress. Would let mutators transparently edit gzipped bodies. Today the framework clears Content-Encoding on any mutation to avoid shipping malformed archives.
• Reference guardrail plugin (e.g., prompt-sanitizer). The contract is in place; an actual production plugin is a separate PR driven by a concrete use case.

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

[cwiklik]

Review Summary

Well-structured PR that adds body mutation capability to the plugin framework with proper separation of concerns (ReadsBody vs WritesBody). The open plugin registry follows the proven database/sql.Register pattern with appropriate init-time panics. Pipeline validation is build-time (not runtime), which is the correct safety boundary.

Test coverage is thorough: 35 test functions covering the registry, capabilities, ordering validation, and end-to-end body mutation through all three listener types (ExtProc, ForwardProxy, ReverseProxy).

Design highlights:

• Single-mutator constraint prevents ambiguous ordering
• SHA256-only logging of mutated bodies (no cleartext leakage)
• Content-Encoding cleared on mutation (safe default)
• NeedsBody() correctly folds WritesBody into buffering requirement

Areas reviewed: Go source (plugin framework, registry, pipeline validation, listeners), Go tests (unit + integration), Documentation
Commits: 13, all signed-off
CI: All 17 checks passing