feat(apl): generic-HTTP authorization

[araujof]

Summary

Engine-side additions that let CPEX authorize generic (non-MCP/A2A) HTTP requests. These are consumed by the Praxis policy filter's new experimental enforcement: http mode to run Kuadrant-AuthPolicy-style authorization (see the companion Praxis PR). All changes are additive and non-breaking — existing MCP/entity behavior is unchanged.

Draft: pairs with the Praxis AuthPolicy spike praxis-proxy/praxis#746. Cut a release from this branch before Praxis pins it (Praxis currently consumes it via a temporary path dep).

What's here

• HTTP request line on HttpExtension. Optional method/path/host/scheme, surfaced in the APL bag as http.method/http.path/http.host/http.scheme. Ride the existing read_headers capability (the http slot is gated as a whole in filter_extensions; a base-tier split would need granular sub-field filtering — deferred). host is documented to come from a validated authority, never a raw client Host.
• custom denial response via PluginViolation.details. A per-route response: block (transpiled denyWith) is carried on CompiledRoute (additive; most-specific layer wins) and, on Decision::Deny, stashed into the existing details map under http.status / http.body / http.headers. No new fields on PluginViolation, no new APL grammar — reason-only denies are unchanged.
• evaluate the global policy for entity-less requests. New reserved coordinates ENTITY_HTTP / ENTITY_NAME_GLOBAL and the cmf.http_request hook. The visitor installs a Pre-phase handler bound to the compiled global policy under those coordinates (granted read_headers), so a host can authorize a request that carries no MCP entity. Entity routes still stack global via apply_layer.

Tests

• apl-cmf: request-line surfacing in the bag.
• apl-core: DenyResponse apply_layer merge.
• apl-cpex: response: sub-block parsing; and a new end-to-end global_http_authz test exercising everything together — allow, deny, and custom denyWith for an entity-less HTTP request.

Full apl-core / apl-cpex / cpex-core suites green; clippy + fmt clean.

[terylt]

Nice — the feature is well-structured and the additive claims hold up. I traced the capability-namespace / filter_extensions gating and it's safe: the whole http slot rides read_headers and the new exact-key constants (http.method etc., no trailing .) don't over-grant. A few things I'd want addressed before merge, plus one design question.

Would block on

1. The deny-response decoration isn't gated to actual denials — it can corrupt the HIL elicitation protocol.
In route_handler.rs, the new block

if let (Some(v), Some(resp)) = (violation.as_mut(), self.route.response.as_ref()) { ... }

runs after the pending-elicitation assignment (violation = Some(pending_violation(p)), -32120) and the approved-peek assignment (approved_peek_violation, -32121), and decorates whatever violation is currently set — not just a genuine Decision::Deny. So a route that suspends on an approval/elicitation step gets its -32120 "retry" / -32121 "confirm-to-apply" signal stamped with http.status/http.body/http.headers. A host that maps http.status onto the wire then renders a 403 instead of the retry signal, and the approve/retry loop can't resolve. Combined with #2 (a global response: propagates onto every route) this is reachable without a per-route response: at all.
Suggest gating the decoration to the Decision::Deny arm (or code == "policy.deny" / rule-source denials) rather than any set violation.

2. A global response: is inherited by every entity route, including MCP tool/llm/prompt/resource.
visit_route applies global_layer first onto an empty effective, and the new apply_layer line if more_specific.response.is_some() { self.response = more_specific.response } copies global's response in. So a global catch-all denyWith (meant for HTTP) ends up stamped onto MCP entity denials too. And once inherited it can only be overridden, never unset — a route that wants the plain JSON-RPC deny shape has no opt-out. Worth deciding whether response should layer for non-HTTP entities at all, or be scoped to the HTTP entity. This is the root that makes #1 reachable.

Gaps worth a look

3. The R18 session.persist_failed denial never picks up the custom response. The decoration block runs before the fail-closed logic, and the session.persist_failed violation is constructed after it — so a route with a configured response: renders custom denials for policy denies but the default shape specifically on persist failures. Inconsistent.

4. response: at default / tag scope is silently dropped. response_subblock is only read in visit_global and visit_route; visit_default and visit_policy_bundle never read it, so default_layers[...].response / tag_layers[...].response stay None and never propagate. An operator putting response: under global.defaults.tool or a policies.<tag> bundle gets no effect and no warning (unlike the existing global-only-key lint).

5. A malformed route response: silently falls back to the inherited/global response. On a deserialize error response_subblock warns and returns None, so the route keeps whatever global layered in (see #2). The operator believes the route serves its custom page; it serves the inherited one. The warn-only path is a reasonable choice, but combined with global inheritance the failure mode is "wrong page," not "default page."

Nits

6. response_subblock(yaml, &route_key) is parsed inside the per-entity loop, but its result depends only on the loop-invariant yaml. For a route matching N entities it re-deserializes (and re-warns) N times — hoist above the loop.

7. The global-handler install block duplicates visit_route's dispatch-state snapshot boilerplate (registry/router/session_store RwLock-read + Arc-wrap) verbatim. A small snapshot_dispatch_state() helper would keep the poison-recovery policy from diverging.

8. The detail keys "http.status"/"http.body"/"http.headers" are bare literals on both the producer (route_handler.rs) and consumer (test, future host renderer) side, while this same PR introduces BAG_HTTP_* constants for the request line. Since details is stringly-typed, promoting these to shared constants would couple the two sides.

Design question (non-blocking)

The cmf.http_request hook takes a full MessagePayload, but the request is entirely in the http extension — the test passes Message::text("hi") as a placeholder. Routing HTTP through a CMF hook makes sense to me (it lets the whole plugin chain — audit, rate-limit, token-exchange — act on HTTP, not just APL), but the vestigial payload reads as odd today. Is the intent for the HTTP request body to eventually map into the Message payload (request line → http ext, body → message/args)? If so, a doc comment noting the payload is a deliberate placeholder pending body mapping would help. If body is out of scope permanently, is an Extensions-only hook contract worth considering instead?

[araujof]

Thanks @terylt — all addressed in 4f03fdb.

• apply_layer no longer propagates response. It's now scope-local: the entity-less HTTP handler carries the global block, an entity route carries only its own. No more leak onto MCP entity denials, and no more "can't unset". Regression test added.
• Decoration is now applied per-denial-site via a decorate_denial_response helper (Deny arm + fail-closed sites), never blanket-applied to whatever violation is set. Note: the -32120/-32121 elicitation/peek path you describe isn't in this branch or dev yet, so this is hardening rather than a live bug — but the helper keeps it correct once those land.
• session.load_failed / session.persist_failed denials now pick up the custom response too.
• response: at default/policy-bundle scope now warns (mirrors the global-only-key lint) instead of dropping silently.
• With inheritance gone, a malformed/absent route response: falls back to the host default denial, not an inherited page. Still warn-only.
• response_subblock hoisted above the per-entity loop.
• Extracted snapshot_dispatch_state(), shared by both install sites.
• http.status/body/headers promoted to DETAIL_HTTP_* constants, used on both sides.

Note: Keeping the MessagePayload hook contract — the placeholder is deliberate pending body→Message mapping.