Add JA4/TLS fingerprint debug endpoint at /_ts/debug/ja4

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

@@ -1,5 +1,5 @@
 use error_stack::Report;
-use fastly::http::Method;
+use fastly::http::{header, Method};
 use fastly::{Request, Response};
 
 use trusted_server_core::auction::endpoints::handle_auction;
@@ -109,6 +109,33 @@ fn main() {
     }
 }
 
+fn build_ja4_debug_response(req: &Request) -> Response {
+    let ja4 = req.get_tls_ja4().unwrap_or("unavailable");
+    let h2 = req.get_client_h2_fingerprint().unwrap_or("unavailable");
+    let cipher = req.get_tls_cipher_openssl_name().unwrap_or("unavailable");
+    let tls_version = req.get_tls_protocol().unwrap_or("unavailable");
+    let ua = req.get_header_str("user-agent").unwrap_or("none");
+    let ch_mobile = req.get_header_str("sec-ch-ua-mobile").unwrap_or("not sent");
+    let ch_platform = req
+        .get_header_str("sec-ch-ua-platform")
+        .unwrap_or("not sent");
+
+    let body = format!(
+        "ja4:         {ja4}\n\
+         h2_fp:       {h2}\n\
+         cipher:      {cipher}\n\
+         tls_version: {tls_version}\n\
+         user-agent:  {ua}\n\
+         ch-mobile:   {ch_mobile}\n\
+         ch-platform: {ch_platform}\n"
+    );
+
+    Response::from_status(fastly::http::StatusCode::OK)
+        .with_header(header::CACHE_CONTROL, "no-store, private")
+        .with_content_type(fastly::mime::TEXT_PLAIN_UTF_8)
+        .with_body(body)
+}
+
 async fn route_request(
     settings: &Settings,
     orchestrator: &AuctionOrchestrator,
@@ -186,6 +213,15 @@ async fn route_request(
             }
         }
 
+        // JA4/TLS debug endpoint — only active when debug.ja4_endpoint_enabled = true.
+        (Method::GET, "/_ts/debug/ja4") => {
+            if settings.debug.ja4_endpoint_enabled {
+                Ok(build_ja4_debug_response(&req))
+            } else {
+                Ok(Response::from_status(fastly::http::StatusCode::NOT_FOUND))
+            }
+        }
+
         // tsjs endpoints
         (Method::GET, "/first-party/proxy") => {
             handle_first_party_proxy(settings, runtime_services, req).await
@@ -320,3 +356,63 @@ fn finalize_response(settings: &Settings, geo_info: Option<&GeoInfo>, response:
         response.set_header(key, value);
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use fastly::mime;
+
+    #[test]
+    fn ja4_debug_response_uses_plain_text_and_fallback_values() {
+        let req = Request::get("https://example.com/_ts/debug/ja4");
+
+        let mut response = build_ja4_debug_response(&req);
+
+        assert_eq!(
+            response.get_status(),
+            fastly::http::StatusCode::OK,
+            "should return 200 OK"
+        );
+        assert_eq!(
+            response.get_content_type(),
+            Some(mime::TEXT_PLAIN_UTF_8),
+            "should return plain text content"
+        );
+        assert_eq!(
+            response.get_header_str("cache-control"),
+            Some("no-store, private"),
+            "should disable caching for the debug response"
+        );
+
+        let body = response.take_body_str();
+
+        assert!(
+            body.contains("ja4:         unavailable"),
+            "should include JA4 fallback"
+        );
+        assert!(
+            body.contains("h2_fp:       unavailable"),
+            "should include H2 fingerprint fallback"
+        );
+        assert!(
+            body.contains("cipher:      unavailable"),
+            "should include cipher fallback"
+        );
+        assert!(
+            body.contains("tls_version: unavailable"),
+            "should include TLS version fallback"
+        );
+        assert!(
+            body.contains("user-agent:  none"),
+            "should include user-agent fallback"
+        );
+        assert!(
+            body.contains("ch-mobile:   not sent"),
+            "should include sec-ch-ua-mobile fallback"
+        );
+        assert!(
+            body.contains("ch-platform: not sent"),
+            "should include sec-ch-ua-platform fallback"
+        );
+    }
+}

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

@@ -4,7 +4,7 @@ use std::sync::Arc;
 use edgezero_core::key_value_store::NoopKvStore;
 use error_stack::Report;
 use fastly::http::StatusCode;
-use fastly::Request;
+use fastly::{mime, Request};
 use trusted_server_core::auction::build_orchestrator;
 use trusted_server_core::integrations::IntegrationRegistry;
 use trusted_server_core::platform::{
@@ -249,3 +249,133 @@ fn configured_missing_consent_store_only_breaks_consent_routes() {
         "should scope consent store failures to the consent-dependent routes"
     );
 }
+
+#[test]
+fn ja4_debug_route_returns_404_when_disabled() {
+    let settings = create_test_settings();
+    let orchestrator = build_orchestrator(&settings).expect("should build auction orchestrator");
+    let integration_registry =
+        IntegrationRegistry::new(&settings).expect("should create integration registry");
+
+    let req = Request::get("https://test.com/_ts/debug/ja4");
+    let runtime_services = test_runtime_services(&req);
+    let response = futures::executor::block_on(route_request(
+        &settings,
+        &orchestrator,
+        &integration_registry,
+        &runtime_services,
+        req,
+    ))
+    .expect("should route ja4 debug request");
+
+    assert_eq!(
+        response.get_status(),
+        StatusCode::NOT_FOUND,
+        "should return 404 when debug.ja4_endpoint_enabled is false"
+    );
+}
+
+fn create_debug_enabled_settings() -> Settings {
+    let base = r#"
+            [[handlers]]
+            path = "^/admin"
+            username = "admin"
+            password = "admin-pass"
+
+            [publisher]
+            domain = "test-publisher.com"
+            cookie_domain = ".test-publisher.com"
+            origin_url = "https://origin.test-publisher.com"
+            proxy_secret = "unit-test-proxy-secret"
+
+            [edge_cookie]
+            secret_key = "test-secret-key"
+
+            [request_signing]
+            enabled = false
+            config_store_id = "test-config-store-id"
+            secret_store_id = "test-secret-store-id"
+
+            [consent]
+            consent_store = "missing-consent-store"
+
+            [integrations.prebid]
+            enabled = true
+            server_url = "https://test-prebid.com/openrtb2/auction"
+
+            [auction]
+            enabled = true
+            providers = ["prebid"]
+            timeout_ms = 2000
+
+            [debug]
+            ja4_endpoint_enabled = true
+        "#;
+    Settings::from_toml(base).expect("should parse debug-enabled test settings")
+}
+
+#[test]
+fn ja4_debug_route_returns_plain_text_fallback_response() {
+    let settings = create_debug_enabled_settings();
+    let orchestrator = build_orchestrator(&settings).expect("should build auction orchestrator");
+    let integration_registry =
+        IntegrationRegistry::new(&settings).expect("should create integration registry");
+
+    let req = Request::get("https://test.com/_ts/debug/ja4");
+    let runtime_services = test_runtime_services(&req);
+    let mut response = futures::executor::block_on(route_request(
+        &settings,
+        &orchestrator,
+        &integration_registry,
+        &runtime_services,
+        req,
+    ))
+    .expect("should route ja4 debug request");
+
+    assert_eq!(
+        response.get_status(),
+        StatusCode::OK,
+        "should return 200 OK for the ja4 debug route"
+    );
+    assert_eq!(
+        response.get_content_type(),
+        Some(mime::TEXT_PLAIN_UTF_8),
+        "should return plain text content for the ja4 debug route"
+    );
+    assert_eq!(
+        response.get_header_str("cache-control"),
+        Some("no-store, private"),
+        "should disable caching for the ja4 debug route"
+    );
+
+    let body = response.take_body_str();
+
+    assert!(
+        body.contains("ja4:         unavailable"),
+        "should include the JA4 fallback when Fastly omits the fingerprint"
+    );
+    assert!(
+        body.contains("h2_fp:       unavailable"),
+        "should include the H2 fingerprint fallback when Fastly omits it"
+    );
+    assert!(
+        body.contains("cipher:      unavailable"),
+        "should include the cipher fallback when Fastly omits it"
+    );
+    assert!(
+        body.contains("tls_version: unavailable"),
+        "should include the TLS version fallback when Fastly omits it"
+    );
+    assert!(
+        body.contains("user-agent:  none"),
+        "should include the user-agent fallback when the header is absent"
+    );
+    assert!(
+        body.contains("ch-mobile:   not sent"),
+        "should include the mobile client hints fallback when the header is absent"
+    );
+    assert!(
+        body.contains("ch-platform: not sent"),
+        "should include the platform client hints fallback when the header is absent"
+    );
+}

crates/trusted-server-core/src/settings.rs

@@ -399,6 +399,18 @@ impl Proxy {
     }
 }
 
+/// Debug-only features. All flags default to `false` (off in production).
+#[derive(Debug, Default, Clone, Deserialize, Serialize)]
+pub struct DebugConfig {
+    /// Expose the JA4/TLS fingerprint debug endpoint at `GET /_ts/debug/ja4`.
+    ///
+    /// When `false` (the default), the endpoint returns 404. Enable only for
+    /// intentional Fastly/browser TLS investigation — the endpoint reflects
+    /// Fastly-observed TLS details that browser JS cannot normally read.
+    #[serde(default)]
+    pub ja4_endpoint_enabled: bool,
+}
+
 #[derive(Debug, Default, Clone, Deserialize, Serialize, Validate)]
 pub struct Settings {
     #[validate(nested)]
@@ -423,6 +435,8 @@ pub struct Settings {
     pub consent: ConsentConfig,
     #[serde(default)]
     pub proxy: Proxy,
+    #[serde(default)]
+    pub debug: DebugConfig,
 }
 
 #[allow(unused)]

trusted-server.toml

@@ -184,6 +184,23 @@ enabled = false
 endpoint = "https://origin-mocktioneer.cdintel.com/adserver/mediate"
 timeout_ms = 1000
 
+# Debug configuration (all flags default to false — do not enable in production)
+# [debug]
+# Enable the JA4/TLS fingerprint debug endpoint at GET /_ts/debug/ja4.
+# Returns a plain-text response with the following fields (Fastly-observed values):
+#   ja4         — JA4 TLS client fingerprint
+#   h2_fp       — HTTP/2 client fingerprint
+#   cipher      — TLS cipher suite (OpenSSL name)
+#   tls_version — TLS protocol version
+#   user-agent  — User-Agent request header
+#   ch-mobile   — Sec-CH-UA-Mobile client hint
+#   ch-platform — Sec-CH-UA-Platform client hint
+# All fields fall back to "unavailable" or "not sent" when Fastly does not provide them.
+# Response always carries Cache-Control: no-store, private.
+# IMPORTANT: This endpoint reflects TLS details that browser JS cannot normally read.
+# Disable after investigation is complete.
+# ja4_endpoint_enabled = false
+
 # Map auction-request context keys to mediation URL query parameters.
 # Each key is a context key from the JS client; the value becomes the
 # query parameter name. Arrays are joined with commas.