Add admin endpoint to look up EC entries by id

Adds GET /_ts/admin/ec/{id} (explicit EC ID) and GET /_ts/admin/ec
(EC ID from the caller's ts-ec cookie) so operators can inspect EC
identity graph entries and debug KV-to-auction EID propagation.

The core handler returns the stored KvEntry verbatim (including raw
consent strings and partner UIDs), the KV metadata mirror, the store
generation marker, and a derived auction view showing exactly which
EIDs the auction would attach and why each stored partner ID was
skipped (empty_uid, not_in_registry, bidstream_disabled). Corrupt
entries are returned with the parse error and raw body via the new
KvIdentityGraph::lookup_raw instead of failing closed.

The routes join Settings::ADMIN_ENDPOINTS so startup validation
rejects configs whose basic-auth handler regex does not cover them.
The EC identity graph is Fastly KV backed, so the Axum, Cloudflare,
and Spin adapters register the routes to local 501 responses, keeping
them off the publisher fallback that would forward the Authorization
header to the origin.

Closes #921

Author: prk-Jr

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

@@ -252,6 +252,7 @@ enum NamedRouteHandler {
     TrustedServerDiscovery,
     VerifySignature,
     AdminNotSupported,
+    AdminEcNotSupported,
     /// Legacy `/admin/keys/*` aliases — denied locally with 404 so they never
     /// reach the publisher fallback (which would leak admin credentials).
     LegacyAdminDenied,
@@ -279,7 +280,7 @@ const LEGACY_ADMIN_DENY_METHODS: &[Method] = &[
     Method::DELETE,
 ];
 
-fn named_routes() -> [NamedRoute; 12] {
+fn named_routes() -> [NamedRoute; 14] {
     [
         NamedRoute {
             path: "/.well-known/trusted-server.json",
@@ -304,6 +305,19 @@ fn named_routes() -> [NamedRoute; 12] {
             primary_methods: &[Method::POST],
             handler: NamedRouteHandler::AdminNotSupported,
         },
+        // Admin EC lookup routes. Registered explicitly (like the key routes
+        // above) so they never fall through to the publisher fallback, and
+        // they match `Settings::ADMIN_ENDPOINTS` for auth coverage.
+        NamedRoute {
+            path: "/_ts/admin/ec",
+            primary_methods: &[Method::GET],
+            handler: NamedRouteHandler::AdminEcNotSupported,
+        },
+        NamedRoute {
+            path: "/_ts/admin/ec/{id}",
+            primary_methods: &[Method::GET],
+            handler: NamedRouteHandler::AdminEcNotSupported,
+        },
         // The legacy non-`/_ts` aliases (`/admin/keys/*`) are denied locally with
         // a 404, matching the Fastly and Cloudflare adapters: the production
         // basic-auth handler regex `^/_ts/admin` does not match them, and letting
@@ -388,6 +402,21 @@ fn named_route_handler(
                         );
                         Ok(resp)
                     }
+                    NamedRouteHandler::AdminEcNotSupported => {
+                        // The EC identity graph is Fastly KV backed; the Axum
+                        // dev server has no store to read.
+                        let body = edgezero_core::body::Body::from(
+                            "Admin EC lookup is not supported on the Axum dev server.\n\
+                             Use the Fastly adapter (via Viceroy or deployed) to inspect EC entries.\n",
+                        );
+                        let mut resp = Response::new(body);
+                        *resp.status_mut() = StatusCode::NOT_IMPLEMENTED;
+                        resp.headers_mut().insert(
+                            header::CONTENT_TYPE,
+                            HeaderValue::from_static("text/plain; charset=utf-8"),
+                        );
+                        Ok(resp)
+                    }
                     NamedRouteHandler::LegacyAdminDenied => Ok(legacy_admin_alias_denied()),
                     NamedRouteHandler::Auction => {
                         // Build the geo-aware EC context so the auction consent

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

@@ -74,6 +74,8 @@ fn all_explicit_routes_are_registered() {
         ("POST", "/verify-signature"),
         ("POST", "/_ts/admin/keys/rotate"),
         ("POST", "/_ts/admin/keys/deactivate"),
+        ("GET", "/_ts/admin/ec"),
+        ("GET", "/_ts/admin/ec/{id}"),
         ("POST", "/admin/keys/rotate"),
         ("POST", "/admin/keys/deactivate"),
         ("POST", "/auction"),
@@ -256,6 +258,38 @@ async fn admin_route_without_credentials_returns_401() {
     );
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn authenticated_admin_ec_routes_return_501() {
+    // The EC identity graph is Fastly KV backed, so the Axum dev server
+    // answers the admin EC lookup routes locally with 501 instead of letting
+    // them fall through to the publisher fallback.
+    let sample_ec_id = format!("{}.abc123", "a".repeat(64));
+    for path in [
+        "/_ts/admin/ec".to_owned(),
+        format!("/_ts/admin/ec/{sample_ec_id}"),
+    ] {
+        let mut svc = make_service();
+        let req = Request::builder()
+            .method("GET")
+            .uri(&path)
+            .header("authorization", "Basic YWRtaW46YWRtaW4tcGFzcw==")
+            .body(AxumBody::empty())
+            .expect("should build request");
+        let resp = svc
+            .ready()
+            .await
+            .expect("should be ready")
+            .call(req)
+            .await
+            .expect("should respond");
+        assert_eq!(
+            resp.status().as_u16(),
+            501,
+            "{path} should report that Axum EC lookup is unsupported"
+        );
+    }
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn legacy_admin_aliases_denied_locally_not_proxied_to_publisher() {
     // Regression for the credential-leak finding: the production basic-auth regex

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

@@ -242,6 +242,20 @@ fn admin_key_management_not_supported() -> Response {
     response
 }
 
+fn admin_ec_lookup_not_supported() -> Response {
+    let body = edgezero_core::body::Body::from(
+        "Admin EC lookup is not supported on Cloudflare Workers.\n\
+         Use the Fastly adapter (via Viceroy or deployed) to inspect EC entries.\n",
+    );
+    let mut response = Response::new(body);
+    *response.status_mut() = StatusCode::NOT_IMPLEMENTED;
+    response.headers_mut().insert(
+        header::CONTENT_TYPE,
+        HeaderValue::from_static("text/plain; charset=utf-8"),
+    );
+    response
+}
+
 /// Builds the local `404 Not Found` returned for legacy `/admin/keys/*`
 /// aliases on the Cloudflare adapter.
 ///
@@ -461,6 +475,17 @@ fn build_router(state: &Arc<AppState>) -> RouterService {
             .post("/_ts/admin/keys/deactivate", |_ctx: RequestContext| async {
                 Ok::<Response, EdgeError>(admin_key_management_not_supported())
             })
+            // Admin EC lookup routes. Registered explicitly (like the key
+            // routes above) so they never fall through to the publisher
+            // fallback, and they match `Settings::ADMIN_ENDPOINTS` for auth
+            // coverage. The EC identity graph is Fastly KV backed, so this
+            // adapter has no store to read.
+            .get("/_ts/admin/ec", |_ctx: RequestContext| async {
+                Ok::<Response, EdgeError>(admin_ec_lookup_not_supported())
+            })
+            .get("/_ts/admin/ec/{id}", |_ctx: RequestContext| async {
+                Ok::<Response, EdgeError>(admin_ec_lookup_not_supported())
+            })
             .post(
                 "/auction",
                 make_handler(Arc::clone(&state), |s, services, req| async move {

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

@@ -215,6 +215,8 @@ fn all_explicit_routes_are_registered() {
         ("POST", "/verify-signature"),
         ("POST", "/_ts/admin/keys/rotate"),
         ("POST", "/_ts/admin/keys/deactivate"),
+        ("GET", "/_ts/admin/ec"),
+        ("GET", "/_ts/admin/ec/{id}"),
         ("POST", "/auction"),
         ("GET", "/first-party/proxy"),
         ("GET", "/first-party/click"),
@@ -264,6 +266,32 @@ async fn authenticated_admin_routes_return_501() {
     }
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn authenticated_admin_ec_routes_return_501() {
+    // The EC identity graph is Fastly KV backed, so Cloudflare answers the
+    // admin EC lookup routes locally with 501 instead of letting them fall
+    // through to the publisher fallback.
+    let sample_ec_id = format!("{}.abc123", "a".repeat(64));
+    for path in [
+        "/_ts/admin/ec".to_owned(),
+        format!("/_ts/admin/ec/{sample_ec_id}"),
+    ] {
+        let req = request_builder()
+            .method("GET")
+            .uri(&path)
+            .header("authorization", "Basic YWRtaW46YWRtaW4tcGFzcw==")
+            .body(edgezero_core::body::Body::empty())
+            .expect("should build request");
+        let resp = route(test_router(), req).await;
+
+        assert_eq!(
+            resp.status().as_u16(),
+            501,
+            "{path} should report that Cloudflare EC lookup is unsupported"
+        );
+    }
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn admin_route_without_credentials_returns_401() {
     let router = test_router();

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

@@ -22,6 +22,8 @@
 //! | POST | `/verify-signature` | [`handle_verify_signature`] |
 //! | POST | `/_ts/admin/keys/rotate` | [`handle_rotate_key`] |
 //! | POST | `/_ts/admin/keys/deactivate` | [`handle_deactivate_key`] |
+//! | GET | `/_ts/admin/ec` | [`handle_admin_ec_lookup`] |
+//! | GET | `/_ts/admin/ec/{id}` | [`handle_admin_ec_lookup`] |
 //! | POST | `/_ts/api/v1/batch-sync` | [`handle_batch_sync`] |
 //! | GET | `/_ts/api/v1/identify` | [`handle_identify`] |
 //! | GET | `/_ts/set-tester` | [`handle_set_tester`] |
@@ -98,6 +100,7 @@ use trusted_server_core::auction::endpoints::handle_auction;
 use trusted_server_core::auction::{AuctionOrchestrator, build_orchestrator};
 use trusted_server_core::constants::{COOKIE_SHAREDID, COOKIE_TS_EIDS};
 use trusted_server_core::ec::EcContext;
+use trusted_server_core::ec::admin::handle_admin_ec_lookup;
 use trusted_server_core::ec::batch_sync::handle_batch_sync;
 use trusted_server_core::ec::consent::ec_consent_withdrawn;
 use trusted_server_core::ec::device::DeviceSignals;
@@ -565,6 +568,10 @@ async fn run_named_route(
         }
         NamedRouteHandler::RotateKey => handle_rotate_key(&state.settings, services, req),
         NamedRouteHandler::DeactivateKey => handle_deactivate_key(&state.settings, services, req),
+        NamedRouteHandler::AdminEcLookup => {
+            let partner_registry = PartnerRegistry::from_config(&state.settings.ec.partners)?;
+            handle_admin_ec_lookup(ec.kv_graph.as_ref(), &partner_registry, &req)
+        }
         NamedRouteHandler::LegacyAdminDenied => Ok(legacy_admin_alias_denied()),
         NamedRouteHandler::BatchSync => {
             // Dispatched by execute_named before EC state is built.
@@ -987,6 +994,7 @@ enum NamedRouteHandler {
     VerifySignature,
     RotateKey,
     DeactivateKey,
+    AdminEcLookup,
     /// Legacy `/admin/keys/*` aliases — denied locally with 404 so they never
     /// reach the publisher fallback (which would leak admin credentials).
     LegacyAdminDenied,
@@ -1039,6 +1047,18 @@ const NAMED_ROUTES: &[NamedRoute] = &[
         primary_methods: &[Method::POST],
         handler: NamedRouteHandler::DeactivateKey,
     },
+    // Admin EC lookup: the bare route reads the EC ID from the caller's
+    // `ts-ec` cookie; the parameterized route takes an explicit EC ID.
+    NamedRoute {
+        path: "/_ts/admin/ec",
+        primary_methods: &[Method::GET],
+        handler: NamedRouteHandler::AdminEcLookup,
+    },
+    NamedRoute {
+        path: "/_ts/admin/ec/{id}",
+        primary_methods: &[Method::GET],
+        handler: NamedRouteHandler::AdminEcLookup,
+    },
     // The legacy non-`/_ts` aliases (`/admin/keys/*`) are denied locally with a
     // 404 instead of executing key operations: the production basic-auth handler
     // regex `^/_ts/admin` does not match them, and letting them fall through to
@@ -1624,6 +1644,30 @@ mod tests {
         }
     }
 
+    #[test]
+    fn admin_ec_lookup_routes_are_registered() {
+        // Both lookup shapes must be explicitly routed to the admin EC
+        // handler: the bare cookie-based route and the parameterized route.
+        // Leaving either unrouted would fall through to the publisher
+        // fallback, forwarding the caller's `Authorization` header to the
+        // origin.
+        for path in ["/_ts/admin/ec", "/_ts/admin/ec/{id}"] {
+            let route = NAMED_ROUTES
+                .iter()
+                .find(|route| route.path == path)
+                .unwrap_or_else(|| panic!("{path} must be a named route"));
+            assert!(
+                matches!(route.handler, NamedRouteHandler::AdminEcLookup),
+                "{path} must map to the admin EC lookup handler"
+            );
+            assert_eq!(
+                route.primary_methods,
+                &[Method::GET],
+                "{path} must have GET as its only primary method"
+            );
+        }
+    }
+
     #[test]
     fn legacy_admin_aliases_denied_locally_not_proxied_to_publisher() {
         // Regression for the credential-leak finding: with a production-shaped

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

@@ -141,12 +141,14 @@ const LEGACY_ADMIN_DENY_METHODS: &[Method] = &[
     Method::DELETE,
 ];
 
-fn named_fallback_paths() -> [(&'static str, &'static [Method]); 12] {
+fn named_fallback_paths() -> [(&'static str, &'static [Method]); 14] {
     [
         ("/.well-known/trusted-server.json", &[Method::GET]),
         ("/verify-signature", &[Method::POST]),
         ("/_ts/admin/keys/rotate", &[Method::POST]),
         ("/_ts/admin/keys/deactivate", &[Method::POST]),
+        ("/_ts/admin/ec", &[Method::GET]),
+        ("/_ts/admin/ec/{id}", &[Method::GET]),
         ("/admin/keys/rotate", LEGACY_ADMIN_DENY_METHODS),
         ("/admin/keys/deactivate", LEGACY_ADMIN_DENY_METHODS),
         ("/auction", &[Method::POST]),
@@ -359,6 +361,20 @@ fn admin_key_management_not_supported() -> Response {
     response
 }
 
+fn admin_ec_lookup_not_supported() -> Response {
+    let body = edgezero_core::body::Body::from(
+        "Admin EC lookup is not supported on Fermyon Spin.\n\
+         Use the Fastly adapter (via Viceroy or deployed) to inspect EC entries.\n",
+    );
+    let mut response = Response::new(body);
+    *response.status_mut() = StatusCode::NOT_IMPLEMENTED;
+    response.headers_mut().insert(
+        header::CONTENT_TYPE,
+        HeaderValue::from_static("text/plain; charset=utf-8"),
+    );
+    response
+}
+
 // ---------------------------------------------------------------------------
 // Error helper
 // ---------------------------------------------------------------------------
@@ -511,6 +527,10 @@ fn build_router(state: &Arc<AppState>) -> RouterService {
             Ok::<Response, EdgeError>(admin_key_management_not_supported())
         };
 
+        let admin_ec_not_supported_handler = |_ctx: RequestContext| async {
+            Ok::<Response, EdgeError>(admin_ec_lookup_not_supported())
+        };
+
         // /auction
         let s = Arc::clone(&state);
         let auction_handler = move |ctx: RequestContext| {
@@ -730,6 +750,13 @@ fn build_router(state: &Arc<AppState>) -> RouterService {
             // credentials and key-management payloads to the origin.
             .post("/_ts/admin/keys/rotate", admin_not_supported_handler)
             .post("/_ts/admin/keys/deactivate", admin_not_supported_handler)
+            // Admin EC lookup routes. Registered explicitly (like the key
+            // routes above) so they never fall through to the publisher
+            // fallback, and they match `Settings::ADMIN_ENDPOINTS` for auth
+            // coverage. The EC identity graph is Fastly KV backed, so this
+            // adapter has no store to read.
+            .get("/_ts/admin/ec", admin_ec_not_supported_handler)
+            .get("/_ts/admin/ec/{id}", admin_ec_not_supported_handler)
             .post("/auction", auction_handler)
             .get("/__ts/page-bids", page_bids_handler)
             .route(

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

@@ -113,6 +113,32 @@ async fn authenticated_admin_routes_return_501() {
     }
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn authenticated_admin_ec_routes_return_501() {
+    // The EC identity graph is Fastly KV backed, so Spin answers the admin
+    // EC lookup routes locally with 501 instead of letting them fall through
+    // to the publisher fallback.
+    let sample_ec_id = format!("{}.abc123", "a".repeat(64));
+    for path in [
+        "/_ts/admin/ec".to_owned(),
+        format!("/_ts/admin/ec/{sample_ec_id}"),
+    ] {
+        let req = request_builder()
+            .method("GET")
+            .uri(&path)
+            .header("authorization", "Basic YWRtaW46YWRtaW4tcGFzcw==")
+            .body(edgezero_core::body::Body::empty())
+            .expect("should build request");
+        let resp = route(test_router(), req).await;
+
+        assert_eq!(
+            resp.status().as_u16(),
+            501,
+            "{path} should report that Spin EC lookup is unsupported"
+        );
+    }
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn health_route_returns_ok() {
     // Parity with the Fastly/Axum adapters: GET /health is a cheap liveness probe