Add a pluggable Edge Cookie module seam with the built-in HMAC module

crates/edgecookie/README.md

@@ -0,0 +1,18 @@
+# Edge Cookie modules
+
+Vendor Edge Cookie module crates live here, one per vendor, for example
+`crates/edgecookie/<vendor>`. Each implements the `EdgeCookieModule` trait
+from `trusted-server-core` and is wired in by an adapter.
+
+The built-in HMAC module (HMAC over the client IP) ships in
+`trusted-server-core` (`ec::module`), so no crate is needed for it. There is
+no default module, and a deployment selects one explicitly with
+`[ec] module`.
+
+A module's own settings live in the `[ec.<name>]` table the selector names.
+The name is the module's implementation id, the same string its
+`EdgeCookieModule::id` returns, unless the table names one with
+`implementation = "<id>"`, which lets an operator configure a module under a
+name of their own choosing. A module with no settings needs no table.
+
+This directory is a placeholder until a vendor module is added.

crates/trusted-server-adapter-axum/src/app.rs

@@ -18,6 +18,7 @@ use trusted_server_core::ec::EcContext;
 use trusted_server_core::ec::admin::{
     admin_ec_lookup_not_supported, deny_admin_diagnostic_fallback, handle_admin_eids_lookup,
 };
+use trusted_server_core::ec::module::ensure_module_available;
 use trusted_server_core::ec::registry::PartnerRegistry;
 use trusted_server_core::error::{IntoHttpResponse as _, TrustedServerError};
 use trusted_server_core::integrations::{IntegrationRegistry, ProxyDispatchInput};
@@ -77,8 +78,9 @@ fn build_state() -> Result<Arc<AppState>, Report<TrustedServerError>> {
 ///
 /// # Errors
 ///
-/// Returns an error when the auction orchestrator or the integration
-/// registry fail to initialise.
+/// Returns an error when the selected Edge Cookie module cannot be built for
+/// this adapter, or when the auction orchestrator or the integration registry
+/// fail to initialize.
 fn build_state_with_settings(
     settings: Settings,
 ) -> Result<Arc<AppState>, Report<TrustedServerError>> {
@@ -89,6 +91,26 @@ fn build_state_with_services(
     settings: Settings,
     services: Option<RuntimeServices>,
 ) -> Result<Arc<AppState>, Report<TrustedServerError>> {
+    // Composition root: reject a module selection this adapter can never
+    // supply, once, before any request is served. A caller supplying its own
+    // `RuntimeServices` may already have resolved a module, so the check is
+    // given whatever those services carry, which is what `EcContext` sees per
+    // request.
+    //
+    // This adapter checks rather than keeps what the check resolved, unlike the
+    // Fastly, Cloudflare and Spin adapters, because it is a long-lived process
+    // whose application state is built once at start-up while theirs is rebuilt
+    // for every request. With no services supplied it threads no module, so
+    // `EcContext` resolves the selection itself on every request, building a
+    // fresh built-in module that reads no request data; this dev server
+    // accepts that per-request construction rather than caching a resolved
+    // module.
+    ensure_module_available(
+        &settings.ec,
+        services
+            .as_ref()
+            .and_then(RuntimeServices::resolved_ec_module),
+    )?;
     let plan = Arc::new(compile_auction_plan(&settings)?);
     plan.validate_for_target(trusted_server_core::platform::AuctionTargetId::Axum)?;
     let orchestrator = build_orchestrator_with_plan(Arc::clone(&plan), &settings)?;
@@ -179,13 +201,26 @@ where
 /// Builds the geo-aware [`EcContext`] for consent-gated endpoints (`/auction`,
 /// `/_ts/page-bids`, and the publisher fallback).
 ///
-/// Mirrors the Fastly entry point: `EcContext::default()` leaves jurisdiction
-/// Unknown, which fails the auction consent gate closed even for consented
-/// users. Geo comes from the platform (a no-op on the local Axum dev server, so
-/// jurisdiction stays Unknown there unless the request carries TCF consent). A
-/// malformed consent string is logged and falls back to the default
-/// (fail-closed) context rather than being silently swallowed.
-fn build_ec_context(state: &AppState, services: &RuntimeServices, req: &Request) -> EcContext {
+/// Geo comes from the platform (a no-op on the local Axum dev server, so
+/// jurisdiction stays Unknown there unless the request carries TCF consent), and
+/// a geo lookup failure is logged and treated as no location.
+///
+/// Mirrors the Fastly entry point, which keeps the report and answers with an
+/// error response: when the Edge Cookie context cannot be read the request
+/// fails rather than continuing with `EcContext::default()`, which would serve
+/// every request with no identity. A malformed cookie value, a bad consent
+/// string and a failed geo lookup do not reach this error path at all, so
+/// failing here does not fail requests for ordinary parse problems.
+///
+/// # Errors
+///
+/// Returns an error when the selected Edge Cookie module cannot be built for
+/// this request, or when the request's `Cookie` header is not valid UTF-8.
+fn build_ec_context(
+    state: &AppState,
+    services: &RuntimeServices,
+    req: &Request,
+) -> Result<EcContext, Report<TrustedServerError>> {
     let geo_info = services
         .geo()
         .lookup(services.client_info().client_ip)
@@ -194,10 +229,6 @@ fn build_ec_context(state: &AppState, services: &RuntimeServices, req: &Request)
             None
         });
     EcContext::read_from_request_with_geo(&state.settings, req, services, geo_info.as_ref())
-        .unwrap_or_else(|e| {
-            log::warn!("EC context read failed: {e:?}");
-            EcContext::default()
-        })
 }
 
 // ---------------------------------------------------------------------------
@@ -244,7 +275,7 @@ async fn dispatch_fallback(
 
     // Run the server-side auction with the configured creative-opportunity
     // slots; `handle_publisher_request` matches them against the request path.
-    let mut ec_context = build_ec_context(state, services, &req);
+    let mut ec_context = build_ec_context(state, services, &req)?;
     let auction = AuctionDispatch {
         orchestrator: &state.orchestrator,
         slots: state.settings.creative_opportunity_slots(),
@@ -505,7 +536,7 @@ fn named_route_handler(
                         // Build the geo-aware EC context so the auction consent
                         // gate sees the caller's jurisdiction — `EcContext::default()`
                         // fails it closed for consented users.
-                        let mut ec_context = build_ec_context(&state, &services, &req);
+                        let mut ec_context = build_ec_context(&state, &services, &req)?;
                         handle_auction(
                             &state.settings,
                             &state.orchestrator,
@@ -524,7 +555,7 @@ fn named_route_handler(
                         if req.method() == Method::OPTIONS {
                             Ok(page_bids_preflight_denied())
                         } else {
-                            let mut ec_context = build_ec_context(&state, &services, &req);
+                            let mut ec_context = build_ec_context(&state, &services, &req)?;
                             let auction = AuctionDispatch {
                                 orchestrator: &state.orchestrator,
                                 slots: state.settings.creative_opportunity_slots(),
@@ -715,3 +746,81 @@ fn build_router(state: &Arc<AppState>) -> RouterService {
 
     router.build()
 }
+
+#[cfg(test)]
+mod tests {
+    use edgezero_core::http::request_builder;
+    use edgezero_core::params::PathParams;
+
+    use super::*;
+
+    /// Settings selecting a vendor Edge Cookie module this adapter does not
+    /// inject, with the `[ec.acme]` block that module's settings live in.
+    /// `acme` is a fictional vendor key.
+    const UNINJECTED_MODULE_TOML: &str = r#"
+        [[handlers]]
+        path = "^/_ts/admin"
+        username = "admin"
+        password = "admin-pass"
+
+        [publisher]
+        domain = "test-publisher.example.com"
+        cookie_domain = ".test-publisher.example.com"
+        origin_url = "https://origin.test-publisher.example.com"
+        proxy_secret = "unit-test-proxy-secret"
+
+        [ec]
+        module = "acme"
+
+        [ec.acme]
+        endpoint = "https://ec.acme.example.com"
+    "#;
+
+    /// Builds application state directly, bypassing the composition root's
+    /// startup check, so the per-request behavior can be exercised with a
+    /// selection the adapter cannot supply.
+    fn state_with_uninjected_module() -> AppState {
+        let settings = Settings::from_toml(UNINJECTED_MODULE_TOML)
+            .expect("should parse settings selecting an uninjected module");
+        let plan = Arc::new(compile_auction_plan(&settings).expect("should compile auction plan"));
+        let orchestrator = build_orchestrator_with_plan(Arc::clone(&plan), &settings)
+            .expect("should build orchestrator");
+        let registry =
+            IntegrationRegistry::with_plan(&settings, plan).expect("should build registry");
+        AppState {
+            settings: Arc::new(settings),
+            orchestrator: Arc::new(orchestrator),
+            registry: Arc::new(registry),
+            // This test drives the per-request path, which builds its services
+            // from the request context.
+            services: None,
+        }
+    }
+
+    /// The per-request Edge Cookie read must return its error rather than a
+    /// default context.
+    ///
+    /// Continuing with `EcContext::default()` would serve every request with
+    /// no identity when the selected module cannot be built. The call sites
+    /// propagate the error to `http_error`, matching the Fastly adapter.
+    #[test]
+    fn build_ec_context_fails_when_the_selected_module_is_unavailable() {
+        let state = state_with_uninjected_module();
+        let req = request_builder()
+            .method("POST")
+            .uri("https://test-publisher.example.com/auction")
+            .body(edgezero_core::body::Body::empty())
+            .expect("should build test request");
+        let ctx = RequestContext::new(req, PathParams::default());
+        let services = build_runtime_services(&ctx);
+        let req = ctx.into_request();
+
+        let error = build_ec_context(&state, &services, &req)
+            .expect_err("an unavailable Edge Cookie module must fail the request");
+
+        assert!(
+            error.to_string().contains("acme"),
+            "the error should name the selected module, got: {error}"
+        );
+    }
+}

crates/trusted-server-adapter-axum/src/middleware.rs

@@ -193,6 +193,9 @@ mod tests {
                 proxy_secret = "unit-test-proxy-secret"
 
                 [ec]
+                module = "hmac"
+
+                [ec.hmac]
                 passphrase = "test-secret-key-32-bytes-minimum"
             "#,
         )

crates/trusted-server-adapter-axum/tests/routes.rs

@@ -33,6 +33,9 @@ fn test_settings() -> trusted_server_core::settings::Settings {
             proxy_secret = "integration-test-proxy-secret"
 
             [ec]
+            module = "hmac"
+
+            [ec.hmac]
             passphrase = "test-secret-key-32-bytes-minimum"
         "#,
     )
@@ -868,6 +871,57 @@ async fn first_party_proxy_rebuild_is_routed() {
     );
 }
 
+// ---------------------------------------------------------------------------
+// Edge Cookie module availability
+// ---------------------------------------------------------------------------
+
+/// Test settings selecting a vendor Edge Cookie module this adapter does not
+/// inject, with the `[ec.acme]` block that module's settings live in.
+/// `acme` is a fictional vendor key.
+const UNINJECTED_MODULE_TOML: &str = r#"
+    [[handlers]]
+    path = "^/_ts/admin"
+    username = "admin"
+    password = "admin-pass"
+
+    [publisher]
+    domain = "test-publisher.example.com"
+    cookie_domain = ".test-publisher.example.com"
+    origin_url = "https://origin.test-publisher.example.com"
+    proxy_secret = "integration-test-proxy-secret"
+
+    [ec]
+    module = "acme"
+
+    [ec.acme]
+    endpoint = "https://ec.acme.example.com"
+"#;
+
+/// A module selection this adapter can never supply must fail while the
+/// application state is built, before any request is served.
+///
+/// Configuration validation accepts this selection, because only the adapter
+/// that injects a module knows what that module needs, and the Axum dev
+/// server injects no vendor Edge Cookie module, so only the composition root
+/// can catch it. Without the startup check the deployment would come up and
+/// answer every request.
+#[test]
+fn selecting_a_module_this_adapter_cannot_supply_fails_at_startup() {
+    let settings = trusted_server_core::settings::Settings::from_toml(UNINJECTED_MODULE_TOML)
+        .expect("should parse settings selecting an uninjected module");
+
+    // `RouterService` is not `Debug`, so take the error side directly rather
+    // than through `expect_err`.
+    let error = trusted_server_adapter_axum::app::TrustedServerApp::routes_with_settings(settings)
+        .err()
+        .expect("building state with an uninjected module should fail");
+
+    assert!(
+        error.to_string().contains("acme"),
+        "the startup error should name the selected module, got: {error}"
+    );
+}
+
 /// Regression test: a Next.js navigation with a pending auction must buffer to
 /// the structural body close. The Flight payload carries a literal `</body>`, so
 /// a parser-blind seam would inject bids early and split the RSC data.