feat(apl): evaluate the global policy for entity-less HTTP requests

Make the catch-all `global` policy enforce on generic (non-MCP/A2A) HTTP
requests, which carry no entity (Praxis spike Phase B / U3).

- New reserved coordinates: ENTITY_HTTP ("http") / ENTITY_NAME_GLOBAL ("*")
  and the HOOK_CMF_HTTP_REQUEST ("cmf.http_request") hook.
- The visitor installs a Pre-phase AplRouteHandler bound to the compiled
  global policy under those coordinates, granted read_headers so the
  policy can read the request line/headers. Entity routes still stack
  `global` via apply_layer; this adds the entity-less evaluation path.
- A global-scope `response:` block (transpiled denyWith) is carried onto
  the global handler and surfaced on deny via PluginViolation.details (U2).

A host fires invoke_named::<CmfHook>("cmf.http_request", ...) with
meta.entity_type/name set to the reserved coordinates. End-to-end tests
cover allow, deny, and custom-denyWith — exercising U1 + U2 + U3 together.

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

Author: araujof

crates/apl-cpex/src/visitor.rs

@@ -51,10 +51,10 @@ use std::collections::HashMap;
 use std::sync::{Arc, RwLock, Weak};
 
 use cpex_core::cmf::constants::{
-    ENTITY_LLM, ENTITY_PROMPT, ENTITY_RESOURCE, ENTITY_TOOL, HOOK_CMF_LLM_INPUT,
-    HOOK_CMF_LLM_OUTPUT, HOOK_CMF_PROMPT_POST_INVOKE, HOOK_CMF_PROMPT_PRE_INVOKE,
-    HOOK_CMF_RESOURCE_POST_FETCH, HOOK_CMF_RESOURCE_PRE_FETCH, HOOK_CMF_TOOL_POST_INVOKE,
-    HOOK_CMF_TOOL_PRE_INVOKE,
+    ENTITY_HTTP, ENTITY_LLM, ENTITY_NAME_GLOBAL, ENTITY_PROMPT, ENTITY_RESOURCE, ENTITY_TOOL,
+    HOOK_CMF_HTTP_REQUEST, HOOK_CMF_LLM_INPUT, HOOK_CMF_LLM_OUTPUT, HOOK_CMF_PROMPT_POST_INVOKE,
+    HOOK_CMF_PROMPT_PRE_INVOKE, HOOK_CMF_RESOURCE_POST_FETCH, HOOK_CMF_RESOURCE_PRE_FETCH,
+    HOOK_CMF_TOOL_POST_INVOKE, HOOK_CMF_TOOL_PRE_INVOKE,
 };
 use cpex_core::config::RouteEntry;
 use cpex_core::manager::PluginManager;
@@ -357,7 +357,7 @@ impl ConfigVisitor for AplConfigVisitor {
 
     fn visit_global(
         &self,
-        _mgr: &Arc<PluginManager>,
+        mgr: &Arc<PluginManager>,
         yaml: &serde_yaml::Value,
     ) -> Result<(), VisitorError> {
         let Some(apl_block) = apl_subblock(yaml) else {
@@ -386,8 +386,50 @@ impl ConfigVisitor for AplConfigVisitor {
         // `post_policy:` / `args:` / `result:` / `plugins:` (and inert
         // fields it ignores), so a shallow strip on a clone is enough.
         let policy_only = strip_non_dsl_keys(&apl_block);
-        let compiled = compile_policy_block_value("global.apl", &policy_only)
+        let mut compiled = compile_policy_block_value("global.apl", &policy_only)
             .map_err(|e| Box::new(e) as VisitorError)?;
+        // A `response:` block at the global scope is the catch-all denyWith.
+        compiled.response = response_subblock(yaml, "global");
+
+        // Install a catch-all handler so the global policy also evaluates for
+        // generic (non-MCP/A2A) HTTP requests, which carry no entity (U3).
+        // Entity routes still stack `global` via apply_layer in visit_route;
+        // this is the *entity-less* evaluation path. Pre-phase only —
+        // authorization is an admission check, so there is no post handler.
+        if !compiled.policy.is_empty() {
+            let (plugin_registry, pdp_router_arc) = {
+                let state = self.state.read().unwrap_or_else(|p| p.into_inner());
+                (
+                    Arc::new(state.plugin_registry.clone()),
+                    Arc::new(state.pdp_router.clone()) as Arc<dyn PdpResolver>,
+                )
+            };
+            let session_store = self
+                .session_store
+                .read()
+                .unwrap_or_else(|p| p.into_inner())
+                .clone();
+            // The global HTTP policy reads the request line / headers, so
+            // grant `read_headers` on top of the visitor baseline.
+            let mut caps = self.base_capabilities.clone();
+            caps.insert("read_headers".to_string());
+            install_handler(
+                mgr,
+                ENTITY_HTTP,
+                ENTITY_NAME_GLOBAL,
+                None,
+                HOOK_CMF_HTTP_REQUEST,
+                Phase::Pre,
+                Arc::new(compiled.clone()),
+                &plugin_registry,
+                &self.dispatch_cache,
+                &session_store,
+                &self.manager,
+                Some(pdp_router_arc),
+                &caps,
+            );
+        }
+
         self.state
             .write()
             .unwrap_or_else(|p| p.into_inner())

crates/apl-cpex/tests/global_http_authz.rs

@@ -0,0 +1,131 @@
+// Location: ./crates/apl-cpex/tests/global_http_authz.rs
+// Copyright 2026
+// SPDX-License-Identifier: Apache-2.0
+// Authors: Fred Araujo
+//
+// End-to-end: a `global` APL policy is evaluated for a generic
+// (non-MCP/A2A) HTTP request that carries no entity. The visitor installs
+// a catch-all handler under (ENTITY_HTTP, ENTITY_NAME_GLOBAL,
+// HOOK_CMF_HTTP_REQUEST); the host fires that hook with `meta` set to the
+// reserved coordinates and an `http` extension carrying the request line.
+// This is the entity-less authorization path the Praxis AuthPolicy
+// transpiler targets (spike Phase B / U3). It also exercises U1
+// (http.method in the bag) and U2 (custom denyWith via the route
+// `response:` block surfaced on the violation details).
+
+use std::sync::Arc;
+
+use cpex_core::cmf::constants::{ENTITY_HTTP, ENTITY_NAME_GLOBAL, HOOK_CMF_HTTP_REQUEST};
+use cpex_core::cmf::enums::Role;
+use cpex_core::cmf::{CmfHook, Message, MessagePayload};
+use cpex_core::extensions::{Extensions, HttpExtension, MetaExtension};
+use cpex_core::manager::PluginManager;
+
+use apl_cpex::{register_apl, AplOptions};
+
+async fn manager_with(yaml: &str) -> Arc<PluginManager> {
+    let mgr = Arc::new(PluginManager::default());
+    register_apl(&mgr, AplOptions::in_process());
+    mgr.load_config_yaml(yaml).expect("load_config_yaml");
+    mgr.initialize().await.expect("initialize");
+    mgr
+}
+
+/// A generic-HTTP request: reserved entity coordinates + an `http`
+/// extension carrying the request method.
+fn http_request(method: &str) -> Extensions {
+    let mut meta = MetaExtension::default();
+    meta.entity_type = Some(ENTITY_HTTP.to_string());
+    meta.entity_name = Some(ENTITY_NAME_GLOBAL.to_string());
+    let http = HttpExtension {
+        method: Some(method.to_string()),
+        ..Default::default()
+    };
+    Extensions {
+        meta: Some(Arc::new(meta)),
+        http: Some(Arc::new(http)),
+        ..Default::default()
+    }
+}
+
+fn payload() -> MessagePayload {
+    MessagePayload {
+        message: Message::text(Role::User, "hi"),
+    }
+}
+
+// APL predicate:action form: deny when the method is not GET. (Comparisons
+// use this form; `require(...)` is truthiness-only.)
+const GET_ONLY: &str = r#"
+plugin_settings:
+  routing_enabled: true
+global:
+  apl:
+    policy:
+      - "http.method != 'GET': deny"
+"#;
+
+#[tokio::test]
+async fn global_policy_allows_matching_http_request() {
+    let mgr = manager_with(GET_ONLY).await;
+    let (res, _bg) = mgr
+        .invoke_named::<CmfHook>(HOOK_CMF_HTTP_REQUEST, payload(), http_request("GET"), None)
+        .await;
+    assert!(
+        res.continue_processing,
+        "GET must be allowed by the global policy; violation = {:?}",
+        res.violation
+    );
+}
+
+#[tokio::test]
+async fn global_policy_denies_nonmatching_http_request() {
+    let mgr = manager_with(GET_ONLY).await;
+    let (res, _bg) = mgr
+        .invoke_named::<CmfHook>(HOOK_CMF_HTTP_REQUEST, payload(), http_request("POST"), None)
+        .await;
+    assert!(
+        !res.continue_processing,
+        "POST must be denied by the global policy"
+    );
+}
+
+/// A route-level `response:` block (transpiled `denyWith`) surfaces custom
+/// status/body/headers on the violation `details` map (U2) when the global
+/// policy denies.
+#[tokio::test]
+async fn global_policy_deny_carries_custom_response() {
+    const YAML: &str = r#"
+plugin_settings:
+  routing_enabled: true
+global:
+  apl:
+    policy:
+      - "http.method != 'GET': deny"
+  response:
+    status: 403
+    body: "{\"error\":\"forbidden\"}"
+    headers:
+      X-Reason: "method-not-allowed"
+"#;
+    let mgr = manager_with(YAML).await;
+    let (res, _bg) = mgr
+        .invoke_named::<CmfHook>(
+            HOOK_CMF_HTTP_REQUEST,
+            payload(),
+            http_request("DELETE"),
+            None,
+        )
+        .await;
+    assert!(!res.continue_processing, "DELETE must be denied");
+    let v = res.violation.expect("deny must surface a violation");
+    assert_eq!(v.details.get("http.status"), Some(&serde_json::json!(403)));
+    assert_eq!(
+        v.details.get("http.body"),
+        Some(&serde_json::json!("{\"error\":\"forbidden\"}"))
+    );
+    assert_eq!(
+        v.details.get("http.headers"),
+        Some(&serde_json::json!({ "X-Reason": "method-not-allowed" }))
+    );
+}

crates/cpex-core/src/cmf/constants.rs

@@ -76,6 +76,15 @@ pub const ENTITY_LLM: &str = "llm";
 pub const ENTITY_PROMPT: &str = "prompt";
 pub const ENTITY_RESOURCE: &str = "resource";
 
+/// Reserved entity type for generic (non-MCP/A2A) HTTP requests. The
+/// catch-all `global` policy is dispatched under this entity so an
+/// entity-less request can be authorized; hosts set `meta.entity_type` to
+/// this and `meta.entity_name` to [`ENTITY_NAME_GLOBAL`].
+pub const ENTITY_HTTP: &str = "http";
+
+/// Reserved entity name for the global catch-all policy annotation.
+pub const ENTITY_NAME_GLOBAL: &str = "*";
+
 // ---------------------------------------------------------------------------
 // CMF hook names — the canonical names plugins register under and hosts
 // pass to `PluginManager::invoke_named::<CmfHook>(...)`. Two per entity
@@ -94,3 +103,9 @@ pub const HOOK_CMF_PROMPT_PRE_INVOKE: &str = "cmf.prompt_pre_invoke";
 pub const HOOK_CMF_PROMPT_POST_INVOKE: &str = "cmf.prompt_post_invoke";
 pub const HOOK_CMF_RESOURCE_PRE_FETCH: &str = "cmf.resource_pre_fetch";
 pub const HOOK_CMF_RESOURCE_POST_FETCH: &str = "cmf.resource_post_fetch";
+
+/// Generic HTTP request hook. Hosts fire this for non-MCP/A2A HTTP
+/// requests; the catch-all `global` policy (if any) is annotated under
+/// it via [`ENTITY_HTTP`] / [`ENTITY_NAME_GLOBAL`]. Pre-invocation only —
+/// authorization is an admission check, so there is no post counterpart.
+pub const HOOK_CMF_HTTP_REQUEST: &str = "cmf.http_request";