From 9221df660961440d133cbdf1eea8153ebd52676f Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Wed, 25 Mar 2026 18:03:43 -0500
Subject: [PATCH 01/36] Rename Synthetic ID to Edge Cookie (EC) and simplify
 generation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rename 'Synthetic ID' to 'Edge Cookie (EC)' across all external-facing
  identifiers, config, internal Rust code, and documentation
- Simplify EC hash generation to use only client IP (IPv4 or /64-masked
  IPv6) with HMAC-SHA256, removing User-Agent, Accept-Language,
  Accept-Encoding, random_uuid inputs and Handlebars template rendering
- Downgrade EC ID generation logs to trace level since client IP and EC
  IDs are sensitive data
- Remove unused counter_store and opid_store config fields and KV store
  declarations (vestigial from template-based generation)
- Remove handlebars dependency

Breaking changes: wire field synthetic_fresh → ec_fresh, response headers
X-Synthetic-ID → X-TS-EC, cookie synthetic_id → ts-ec, query param
synthetic_id → ts-ec, config section [synthetic] → [edge_cookie].

Closes #462
---
 .../trusted-server-core/src/settings_data.rs  | 117 ++++++++++++++----
 1 file changed, 94 insertions(+), 23 deletions(-)

diff --git a/crates/trusted-server-core/src/settings_data.rs b/crates/trusted-server-core/src/settings_data.rs
index f69fc7ba..1567b338 100644
--- a/crates/trusted-server-core/src/settings_data.rs
+++ b/crates/trusted-server-core/src/settings_data.rs
@@ -40,21 +40,7 @@ pub fn get_settings() -> Result<Settings, Report<TrustedServerError>> {
         );
     }
 
-    if EdgeCookie::is_placeholder_secret_key(settings.edge_cookie.secret_key.expose()) {
-        log::warn!(
-            "INSECURE: edge_cookie.secret_key is set to a default placeholder — \
-             HMAC-SHA256 signatures can be forged. \
-             Override via TRUSTED_SERVER__EDGE_COOKIE__SECRET_KEY at build time"
-        );
-    }
-
-    if Publisher::is_placeholder_proxy_secret(settings.publisher.proxy_secret.expose()) {
-        log::warn!(
-            "INSECURE: publisher.proxy_secret is set to a default placeholder — \
-             XChaCha20-Poly1305 encrypted URLs can be decrypted by anyone. \
-             Override via TRUSTED_SERVER__PUBLISHER__PROXY_SECRET at build time"
-        );
-    }
+    settings.reject_placeholder_secrets()?;
 
     Ok(settings)
 }
@@ -63,14 +49,99 @@ pub fn get_settings() -> Result<Settings, Report<TrustedServerError>> {
 mod tests {
     use super::*;
 
+    fn toml_with_secrets(secret_key: &str, proxy_secret: &str) -> String {
+        format!(
+            r#"
+[publisher]
+domain = "test-publisher.com"
+cookie_domain = ".test-publisher.com"
+origin_url = "https://origin.test-publisher.com"
+proxy_secret = "{proxy_secret}"
+
+[edge_cookie]
+secret_key = "{secret_key}"
+
+[[handlers]]
+path = "^/admin"
+username = "admin"
+password = "admin-pass"
+"#
+        )
+    }
+
+    #[test]
+    fn rejects_placeholder_secret_key() {
+        let toml = toml_with_secrets("secret-key", "real-proxy-secret");
+        let settings = Settings::from_toml(&toml).expect("should parse TOML");
+        let err = settings
+            .reject_placeholder_secrets()
+            .expect_err("should reject placeholder secret_key");
+        let root = err.current_context();
+        assert!(
+            matches!(root, TrustedServerError::InsecureDefault { field } if field.contains("edge_cookie.secret_key")),
+            "error should mention edge_cookie.secret_key, got: {root}"
+        );
+    }
+
     #[test]
-    fn get_settings_loads_embedded_toml_successfully() {
-        // The embedded TOML contains placeholder secrets (e.g. "trusted-server",
-        // "change-me-proxy-secret"). This is expected — production builds override
-        // them via TRUSTED_SERVER__* env vars at build time.
-        let settings = get_settings().expect("should load settings from embedded TOML");
-        assert!(!settings.publisher.domain.is_empty());
-        assert!(!settings.publisher.cookie_domain.is_empty());
-        assert!(!settings.publisher.origin_url.is_empty());
+    fn rejects_placeholder_proxy_secret() {
+        let toml = toml_with_secrets("real-secret-key", "change-me-proxy-secret");
+        let settings = Settings::from_toml(&toml).expect("should parse TOML");
+        let err = settings
+            .reject_placeholder_secrets()
+            .expect_err("should reject placeholder proxy_secret");
+        let root = err.current_context();
+        assert!(
+            matches!(root, TrustedServerError::InsecureDefault { field } if field.contains("publisher.proxy_secret")),
+            "error should mention publisher.proxy_secret, got: {root}"
+        );
+    }
+
+    #[test]
+    fn rejects_both_placeholders_in_single_error() {
+        let toml = toml_with_secrets("secret_key", "change-me-proxy-secret");
+        let settings = Settings::from_toml(&toml).expect("should parse TOML");
+        let err = settings
+            .reject_placeholder_secrets()
+            .expect_err("should reject both placeholder secrets");
+        let root = err.current_context();
+        match root {
+            TrustedServerError::InsecureDefault { field } => {
+                assert!(
+                    field.contains("edge_cookie.secret_key"),
+                    "error should mention edge_cookie.secret_key, got: {field}"
+                );
+                assert!(
+                    field.contains("publisher.proxy_secret"),
+                    "error should mention publisher.proxy_secret, got: {field}"
+                );
+            }
+            other => panic!("expected InsecureDefault, got: {other}"),
+        }
+    }
+
+    #[test]
+    fn accepts_non_placeholder_secrets() {
+        let toml = toml_with_secrets("production-secret-key", "production-proxy-secret");
+        let settings = Settings::from_toml(&toml).expect("should parse TOML");
+        settings
+            .reject_placeholder_secrets()
+            .expect("non-placeholder secrets should pass validation");
+    }
+
+    /// Smoke-test the full `get_settings()` pipeline (embedded bytes → UTF-8 →
+    /// parse → validate → placeholder check).  The build-time TOML ships with
+    /// placeholder secrets, so the expected outcome is an [`InsecureDefault`]
+    /// error — but reaching that error proves every earlier stage succeeded.
+    #[test]
+    fn get_settings_rejects_embedded_placeholder_secrets() {
+        let err = super::get_settings().expect_err("should reject embedded placeholder secrets");
+        assert!(
+            matches!(
+                err.current_context(),
+                TrustedServerError::InsecureDefault { .. }
+            ),
+            "should fail with InsecureDefault, got: {err}"
+        );
     }
 }

From ef55eab0ba5562457ef91b5c1d193c357403039d Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Mon, 30 Mar 2026 13:25:24 -0500
Subject: [PATCH 02/36] Fix CI: remove re-introduced placeholder secret
 validation tests

The EC rename commit (984ba2b) accidentally re-introduced the
reject_placeholder_secrets() call and InsecureDefault tests that were
intentionally removed in 4c29dbf. Replace with log::warn() for
placeholder detection and restore the simple smoke test.
---
 .../trusted-server-core/src/settings_data.rs  | 101 ++----------------
 1 file changed, 8 insertions(+), 93 deletions(-)

diff --git a/crates/trusted-server-core/src/settings_data.rs b/crates/trusted-server-core/src/settings_data.rs
index 1567b338..7e89ab65 100644
--- a/crates/trusted-server-core/src/settings_data.rs
+++ b/crates/trusted-server-core/src/settings_data.rs
@@ -49,99 +49,14 @@ pub fn get_settings() -> Result<Settings, Report<TrustedServerError>> {
 mod tests {
     use super::*;
 
-    fn toml_with_secrets(secret_key: &str, proxy_secret: &str) -> String {
-        format!(
-            r#"
-[publisher]
-domain = "test-publisher.com"
-cookie_domain = ".test-publisher.com"
-origin_url = "https://origin.test-publisher.com"
-proxy_secret = "{proxy_secret}"
-
-[edge_cookie]
-secret_key = "{secret_key}"
-
-[[handlers]]
-path = "^/admin"
-username = "admin"
-password = "admin-pass"
-"#
-        )
-    }
-
-    #[test]
-    fn rejects_placeholder_secret_key() {
-        let toml = toml_with_secrets("secret-key", "real-proxy-secret");
-        let settings = Settings::from_toml(&toml).expect("should parse TOML");
-        let err = settings
-            .reject_placeholder_secrets()
-            .expect_err("should reject placeholder secret_key");
-        let root = err.current_context();
-        assert!(
-            matches!(root, TrustedServerError::InsecureDefault { field } if field.contains("edge_cookie.secret_key")),
-            "error should mention edge_cookie.secret_key, got: {root}"
-        );
-    }
-
     #[test]
-    fn rejects_placeholder_proxy_secret() {
-        let toml = toml_with_secrets("real-secret-key", "change-me-proxy-secret");
-        let settings = Settings::from_toml(&toml).expect("should parse TOML");
-        let err = settings
-            .reject_placeholder_secrets()
-            .expect_err("should reject placeholder proxy_secret");
-        let root = err.current_context();
-        assert!(
-            matches!(root, TrustedServerError::InsecureDefault { field } if field.contains("publisher.proxy_secret")),
-            "error should mention publisher.proxy_secret, got: {root}"
-        );
-    }
-
-    #[test]
-    fn rejects_both_placeholders_in_single_error() {
-        let toml = toml_with_secrets("secret_key", "change-me-proxy-secret");
-        let settings = Settings::from_toml(&toml).expect("should parse TOML");
-        let err = settings
-            .reject_placeholder_secrets()
-            .expect_err("should reject both placeholder secrets");
-        let root = err.current_context();
-        match root {
-            TrustedServerError::InsecureDefault { field } => {
-                assert!(
-                    field.contains("edge_cookie.secret_key"),
-                    "error should mention edge_cookie.secret_key, got: {field}"
-                );
-                assert!(
-                    field.contains("publisher.proxy_secret"),
-                    "error should mention publisher.proxy_secret, got: {field}"
-                );
-            }
-            other => panic!("expected InsecureDefault, got: {other}"),
-        }
-    }
-
-    #[test]
-    fn accepts_non_placeholder_secrets() {
-        let toml = toml_with_secrets("production-secret-key", "production-proxy-secret");
-        let settings = Settings::from_toml(&toml).expect("should parse TOML");
-        settings
-            .reject_placeholder_secrets()
-            .expect("non-placeholder secrets should pass validation");
-    }
-
-    /// Smoke-test the full `get_settings()` pipeline (embedded bytes → UTF-8 →
-    /// parse → validate → placeholder check).  The build-time TOML ships with
-    /// placeholder secrets, so the expected outcome is an [`InsecureDefault`]
-    /// error — but reaching that error proves every earlier stage succeeded.
-    #[test]
-    fn get_settings_rejects_embedded_placeholder_secrets() {
-        let err = super::get_settings().expect_err("should reject embedded placeholder secrets");
-        assert!(
-            matches!(
-                err.current_context(),
-                TrustedServerError::InsecureDefault { .. }
-            ),
-            "should fail with InsecureDefault, got: {err}"
-        );
+    fn get_settings_loads_embedded_toml_successfully() {
+        // The embedded TOML contains placeholder secrets (e.g. "trusted-server",
+        // "change-me-proxy-secret"). This is expected — production builds override
+        // them via TRUSTED_SERVER__* env vars at build time.
+        let settings = get_settings().expect("should load settings from embedded TOML");
+        assert!(!settings.publisher.domain.is_empty());
+        assert!(!settings.publisher.cookie_domain.is_empty());
+        assert!(!settings.publisher.origin_url.is_empty());
     }
 }

From 63e896c21d4429f7d6725c7b02dcb5bc6adc0076 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Wed, 25 Mar 2026 18:23:46 -0500
Subject: [PATCH 03/36] Add EC module with lifecycle management, consent
 gating, and config migration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add ec/ module with EcContext lifecycle, generation, cookies, and consent
- Compute cookie domain from publisher.domain, move EC cookie helpers
- Fix auction consent gating, restore cookie_domain for non-EC cookies
- Add integration proxy revocation, refactor EC parsing, clean up ec_hash
- Remove fresh_id and ec_fresh per EC spec §12.1
- Migrate [edge_cookie] config to [ec] per spec §14
---
 CLAUDE.md                                     |   2 +-
 .../fixtures/configs/viceroy-template.toml    |   4 +-
 crates/js/lib/package-lock.json               | 271 +++++------
 crates/js/lib/package.json                    |   2 +-
 crates/js/lib/src/core/render.ts              |  13 +-
 .../js/lib/src/integrations/prebid/index.ts   |   7 -
 crates/js/lib/test/core/render.test.ts        |   6 +-
 .../test/integrations/prebid/index.test.ts    |  67 +--
 crates/trusted-server-core/README.md          |   9 +-
 .../src/auction/endpoints.rs                  |  54 ++-
 .../src/auction/formats.rs                    |   8 +-
 .../src/auction/orchestrator.rs               |   1 -
 .../trusted-server-core/src/auction/types.rs  |   2 -
 crates/trusted-server-core/src/consent/mod.rs |  49 +-
 crates/trusted-server-core/src/constants.rs   |   2 -
 crates/trusted-server-core/src/creative.rs    |  24 +-
 crates/trusted-server-core/src/ec/consent.rs  |  22 +
 crates/trusted-server-core/src/ec/cookies.rs  | 125 ++++++
 .../trusted-server-core/src/ec/generation.rs  | 251 +++++++++++
 crates/trusted-server-core/src/ec/mod.rs      | 421 ++++++++++++++++++
 crates/trusted-server-core/src/edge_cookie.rs | 376 ----------------
 .../src/integrations/adserver_mock.rs         |   2 -
 .../src/integrations/aps.rs                   |   1 -
 .../src/integrations/google_tag_manager.rs    |   8 +-
 .../src/integrations/prebid.rs                |   9 +-
 .../src/integrations/registry.rs              |   2 +-
 .../src/integrations/testlight.rs             |   2 +-
 crates/trusted-server-core/src/lib.rs         |   4 +-
 crates/trusted-server-core/src/openrtb.rs     |  27 --
 crates/trusted-server-core/src/proxy.rs       |   2 +-
 crates/trusted-server-core/src/publisher.rs   |   4 +-
 crates/trusted-server-core/src/settings.rs    | 100 +++--
 .../trusted-server-core/src/settings_data.rs  | 112 ++++-
 .../trusted-server-core/src/test_support.rs   |   4 +-
 docs/guide/configuration.md                   |  55 ++-
 docs/guide/edge-cookies.md                    |   2 +-
 docs/guide/error-reference.md                 |  12 +-
 docs/guide/first-party-proxy.md               |   2 +-
 docs/guide/onboarding.md                      |   4 +-
 docs/guide/testing.md                         |   5 +-
 .../2026-03-24-ssc-technical-spec-design.md   |   8 +-
 trusted-server.toml                           |   4 +-
 42 files changed, 1313 insertions(+), 772 deletions(-)
 create mode 100644 crates/trusted-server-core/src/ec/consent.rs
 create mode 100644 crates/trusted-server-core/src/ec/cookies.rs
 create mode 100644 crates/trusted-server-core/src/ec/generation.rs
 create mode 100644 crates/trusted-server-core/src/ec/mod.rs
 delete mode 100644 crates/trusted-server-core/src/edge_cookie.rs

diff --git a/CLAUDE.md b/CLAUDE.md
index ec76ee46..b5e2b6f0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -366,7 +366,7 @@ both runtime behavior and build/tooling changes.
 | `crates/trusted-server-core/src/tsjs.rs`                  | Script tag generation with module IDs             |
 | `crates/trusted-server-core/src/html_processor.rs`        | Injects `<script>` at `<head>` start              |
 | `crates/trusted-server-core/src/publisher.rs`             | `/static/tsjs=` handler, concatenates modules     |
-| `crates/trusted-server-core/src/edge_cookie.rs`           | Edge Cookie (EC) ID generation                    |
+| `crates/trusted-server-core/src/ec/`                      | EC identity subsystem (generation, consent, cookies) |
 | `crates/trusted-server-core/src/cookies.rs`               | Cookie handling                                   |
 | `crates/trusted-server-core/src/consent/mod.rs`           | GDPR and broader consent management               |
 | `crates/trusted-server-core/src/http_util.rs`             | HTTP abstractions and request utilities           |
diff --git a/crates/integration-tests/fixtures/configs/viceroy-template.toml b/crates/integration-tests/fixtures/configs/viceroy-template.toml
index 5f64f794..06c2a850 100644
--- a/crates/integration-tests/fixtures/configs/viceroy-template.toml
+++ b/crates/integration-tests/fixtures/configs/viceroy-template.toml
@@ -7,7 +7,9 @@
     [local_server.backends]
 
     [local_server.kv_stores]
-        [[local_server.kv_stores.creative_store]]
+         # These inline placeholders satisfy Viceroy's local KV configuration
+         # requirements without exercising KV-backed application behavior.
+         [[local_server.kv_stores.creative_store]]
             key = "placeholder"
             data = "placeholder"
 
diff --git a/crates/js/lib/package-lock.json b/crates/js/lib/package-lock.json
index 6b4f3e21..ee30a477 100644
--- a/crates/js/lib/package-lock.json
+++ b/crates/js/lib/package-lock.json
@@ -19,7 +19,7 @@
         "eslint": "^9.10.0",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-import": "^2.29.1",
-        "eslint-plugin-jsdoc": "^62.8.0",
+        "eslint-plugin-jsdoc": "^62.5.4",
         "eslint-plugin-unicorn": "^62.0.0",
         "jsdom": "^28.0.0",
         "prettier": "^3.2.5",
@@ -99,6 +99,7 @@
       "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.0.tgz",
       "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.29.0",
         "@babel/generator": "^7.29.0",
@@ -1728,6 +1729,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=20.19.0"
       },
@@ -1768,6 +1770,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=20.19.0"
       }
@@ -2297,9 +2300,9 @@
       }
     },
     "node_modules/@eslint/config-array/node_modules/minimatch": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
-      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
+      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -2381,9 +2384,9 @@
       }
     },
     "node_modules/@eslint/eslintrc/node_modules/minimatch": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
-      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
+      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -2546,9 +2549,9 @@
       }
     },
     "node_modules/@rollup/rollup-android-arm-eabi": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.59.0.tgz",
-      "integrity": "sha512-upnNBkA6ZH2VKGcBj9Fyl9IGNPULcjXRlg0LLeaioQWueH30p6IXtJEbKAgvyv+mJaMxSm1l6xwDXYjpEMiLMg==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.57.1.tgz",
+      "integrity": "sha512-A6ehUVSiSaaliTxai040ZpZ2zTevHYbvu/lDoeAteHI8QnaosIzm4qwtezfRg1jOYaUmnzLX1AOD6Z+UJjtifg==",
       "cpu": [
         "arm"
       ],
@@ -2560,9 +2563,9 @@
       ]
     },
     "node_modules/@rollup/rollup-android-arm64": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.59.0.tgz",
-      "integrity": "sha512-hZ+Zxj3SySm4A/DylsDKZAeVg0mvi++0PYVceVyX7hemkw7OreKdCvW2oQ3T1FMZvCaQXqOTHb8qmBShoqk69Q==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.57.1.tgz",
+      "integrity": "sha512-dQaAddCY9YgkFHZcFNS/606Exo8vcLHwArFZ7vxXq4rigo2bb494/xKMMwRRQW6ug7Js6yXmBZhSBRuBvCCQ3w==",
       "cpu": [
         "arm64"
       ],
@@ -2574,9 +2577,9 @@
       ]
     },
     "node_modules/@rollup/rollup-darwin-arm64": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.59.0.tgz",
-      "integrity": "sha512-W2Psnbh1J8ZJw0xKAd8zdNgF9HRLkdWwwdWqubSVk0pUuQkoHnv7rx4GiF9rT4t5DIZGAsConRE3AxCdJ4m8rg==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.57.1.tgz",
+      "integrity": "sha512-crNPrwJOrRxagUYeMn/DZwqN88SDmwaJ8Cvi/TN1HnWBU7GwknckyosC2gd0IqYRsHDEnXf328o9/HC6OkPgOg==",
       "cpu": [
         "arm64"
       ],
@@ -2588,9 +2591,9 @@
       ]
     },
     "node_modules/@rollup/rollup-darwin-x64": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.59.0.tgz",
-      "integrity": "sha512-ZW2KkwlS4lwTv7ZVsYDiARfFCnSGhzYPdiOU4IM2fDbL+QGlyAbjgSFuqNRbSthybLbIJ915UtZBtmuLrQAT/w==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.57.1.tgz",
+      "integrity": "sha512-Ji8g8ChVbKrhFtig5QBV7iMaJrGtpHelkB3lsaKzadFBe58gmjfGXAOfI5FV0lYMH8wiqsxKQ1C9B0YTRXVy4w==",
       "cpu": [
         "x64"
       ],
@@ -2602,9 +2605,9 @@
       ]
     },
     "node_modules/@rollup/rollup-freebsd-arm64": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.59.0.tgz",
-      "integrity": "sha512-EsKaJ5ytAu9jI3lonzn3BgG8iRBjV4LxZexygcQbpiU0wU0ATxhNVEpXKfUa0pS05gTcSDMKpn3Sx+QB9RlTTA==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.57.1.tgz",
+      "integrity": "sha512-R+/WwhsjmwodAcz65guCGFRkMb4gKWTcIeLy60JJQbXrJ97BOXHxnkPFrP+YwFlaS0m+uWJTstrUA9o+UchFug==",
       "cpu": [
         "arm64"
       ],
@@ -2616,9 +2619,9 @@
       ]
     },
     "node_modules/@rollup/rollup-freebsd-x64": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.59.0.tgz",
-      "integrity": "sha512-d3DuZi2KzTMjImrxoHIAODUZYoUUMsuUiY4SRRcJy6NJoZ6iIqWnJu9IScV9jXysyGMVuW+KNzZvBLOcpdl3Vg==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.57.1.tgz",
+      "integrity": "sha512-IEQTCHeiTOnAUC3IDQdzRAGj3jOAYNr9kBguI7MQAAZK3caezRrg0GxAb6Hchg4lxdZEI5Oq3iov/w/hnFWY9Q==",
       "cpu": [
         "x64"
       ],
@@ -2630,9 +2633,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.59.0.tgz",
-      "integrity": "sha512-t4ONHboXi/3E0rT6OZl1pKbl2Vgxf9vJfWgmUoCEVQVxhW6Cw/c8I6hbbu7DAvgp82RKiH7TpLwxnJeKv2pbsw==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.57.1.tgz",
+      "integrity": "sha512-F8sWbhZ7tyuEfsmOxwc2giKDQzN3+kuBLPwwZGyVkLlKGdV1nvnNwYD0fKQ8+XS6hp9nY7B+ZeK01EBUE7aHaw==",
       "cpu": [
         "arm"
       ],
@@ -2644,9 +2647,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm-musleabihf": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.59.0.tgz",
-      "integrity": "sha512-CikFT7aYPA2ufMD086cVORBYGHffBo4K8MQ4uPS/ZnY54GKj36i196u8U+aDVT2LX4eSMbyHtyOh7D7Zvk2VvA==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.57.1.tgz",
+      "integrity": "sha512-rGfNUfn0GIeXtBP1wL5MnzSj98+PZe/AXaGBCRmT0ts80lU5CATYGxXukeTX39XBKsxzFpEeK+Mrp9faXOlmrw==",
       "cpu": [
         "arm"
       ],
@@ -2658,9 +2661,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm64-gnu": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.59.0.tgz",
-      "integrity": "sha512-jYgUGk5aLd1nUb1CtQ8E+t5JhLc9x5WdBKew9ZgAXg7DBk0ZHErLHdXM24rfX+bKrFe+Xp5YuJo54I5HFjGDAA==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.57.1.tgz",
+      "integrity": "sha512-MMtej3YHWeg/0klK2Qodf3yrNzz6CGjo2UntLvk2RSPlhzgLvYEB3frRvbEF2wRKh1Z2fDIg9KRPe1fawv7C+g==",
       "cpu": [
         "arm64"
       ],
@@ -2672,9 +2675,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-arm64-musl": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.59.0.tgz",
-      "integrity": "sha512-peZRVEdnFWZ5Bh2KeumKG9ty7aCXzzEsHShOZEFiCQlDEepP1dpUl/SrUNXNg13UmZl+gzVDPsiCwnV1uI0RUA==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.57.1.tgz",
+      "integrity": "sha512-1a/qhaaOXhqXGpMFMET9VqwZakkljWHLmZOX48R0I/YLbhdxr1m4gtG1Hq7++VhVUmf+L3sTAf9op4JlhQ5u1Q==",
       "cpu": [
         "arm64"
       ],
@@ -2686,9 +2689,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-loong64-gnu": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.59.0.tgz",
-      "integrity": "sha512-gbUSW/97f7+r4gHy3Jlup8zDG190AuodsWnNiXErp9mT90iCy9NKKU0Xwx5k8VlRAIV2uU9CsMnEFg/xXaOfXg==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.57.1.tgz",
+      "integrity": "sha512-QWO6RQTZ/cqYtJMtxhkRkidoNGXc7ERPbZN7dVW5SdURuLeVU7lwKMpo18XdcmpWYd0qsP1bwKPf7DNSUinhvA==",
       "cpu": [
         "loong64"
       ],
@@ -2700,9 +2703,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-loong64-musl": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.59.0.tgz",
-      "integrity": "sha512-yTRONe79E+o0FWFijasoTjtzG9EBedFXJMl888NBEDCDV9I2wGbFFfJQQe63OijbFCUZqxpHz1GzpbtSFikJ4Q==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.57.1.tgz",
+      "integrity": "sha512-xpObYIf+8gprgWaPP32xiN5RVTi/s5FCR+XMXSKmhfoJjrpRAjCuuqQXyxUa/eJTdAE6eJ+KDKaoEqjZQxh3Gw==",
       "cpu": [
         "loong64"
       ],
@@ -2714,9 +2717,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-ppc64-gnu": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.59.0.tgz",
-      "integrity": "sha512-sw1o3tfyk12k3OEpRddF68a1unZ5VCN7zoTNtSn2KndUE+ea3m3ROOKRCZxEpmT9nsGnogpFP9x6mnLTCaoLkA==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.57.1.tgz",
+      "integrity": "sha512-4BrCgrpZo4hvzMDKRqEaW1zeecScDCR+2nZ86ATLhAoJ5FQ+lbHVD3ttKe74/c7tNT9c6F2viwB3ufwp01Oh2w==",
       "cpu": [
         "ppc64"
       ],
@@ -2728,9 +2731,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-ppc64-musl": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.59.0.tgz",
-      "integrity": "sha512-+2kLtQ4xT3AiIxkzFVFXfsmlZiG5FXYW7ZyIIvGA7Bdeuh9Z0aN4hVyXS/G1E9bTP/vqszNIN/pUKCk/BTHsKA==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.57.1.tgz",
+      "integrity": "sha512-NOlUuzesGauESAyEYFSe3QTUguL+lvrN1HtwEEsU2rOwdUDeTMJdO5dUYl/2hKf9jWydJrO9OL/XSSf65R5+Xw==",
       "cpu": [
         "ppc64"
       ],
@@ -2742,9 +2745,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-riscv64-gnu": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.59.0.tgz",
-      "integrity": "sha512-NDYMpsXYJJaj+I7UdwIuHHNxXZ/b/N2hR15NyH3m2qAtb/hHPA4g4SuuvrdxetTdndfj9b1WOmy73kcPRoERUg==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.57.1.tgz",
+      "integrity": "sha512-ptA88htVp0AwUUqhVghwDIKlvJMD/fmL/wrQj99PRHFRAG6Z5nbWoWG4o81Nt9FT+IuqUQi+L31ZKAFeJ5Is+A==",
       "cpu": [
         "riscv64"
       ],
@@ -2756,9 +2759,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-riscv64-musl": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.59.0.tgz",
-      "integrity": "sha512-nLckB8WOqHIf1bhymk+oHxvM9D3tyPndZH8i8+35p/1YiVoVswPid2yLzgX7ZJP0KQvnkhM4H6QZ5m0LzbyIAg==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.57.1.tgz",
+      "integrity": "sha512-S51t7aMMTNdmAMPpBg7OOsTdn4tySRQvklmL3RpDRyknk87+Sp3xaumlatU+ppQ+5raY7sSTcC2beGgvhENfuw==",
       "cpu": [
         "riscv64"
       ],
@@ -2770,9 +2773,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-s390x-gnu": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.59.0.tgz",
-      "integrity": "sha512-oF87Ie3uAIvORFBpwnCvUzdeYUqi2wY6jRFWJAy1qus/udHFYIkplYRW+wo+GRUP4sKzYdmE1Y3+rY5Gc4ZO+w==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.57.1.tgz",
+      "integrity": "sha512-Bl00OFnVFkL82FHbEqy3k5CUCKH6OEJL54KCyx2oqsmZnFTR8IoNqBF+mjQVcRCT5sB6yOvK8A37LNm/kPJiZg==",
       "cpu": [
         "s390x"
       ],
@@ -2784,9 +2787,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-x64-gnu": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.59.0.tgz",
-      "integrity": "sha512-3AHmtQq/ppNuUspKAlvA8HtLybkDflkMuLK4DPo77DfthRb71V84/c4MlWJXixZz4uruIH4uaa07IqoAkG64fg==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.57.1.tgz",
+      "integrity": "sha512-ABca4ceT4N+Tv/GtotnWAeXZUZuM/9AQyCyKYyKnpk4yoA7QIAuBt6Hkgpw8kActYlew2mvckXkvx0FfoInnLg==",
       "cpu": [
         "x64"
       ],
@@ -2798,9 +2801,9 @@
       ]
     },
     "node_modules/@rollup/rollup-linux-x64-musl": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.59.0.tgz",
-      "integrity": "sha512-2UdiwS/9cTAx7qIUZB/fWtToJwvt0Vbo0zmnYt7ED35KPg13Q0ym1g442THLC7VyI6JfYTP4PiSOWyoMdV2/xg==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.57.1.tgz",
+      "integrity": "sha512-HFps0JeGtuOR2convgRRkHCekD7j+gdAuXM+/i6kGzQtFhlCtQkpwtNzkNj6QhCDp7DRJ7+qC/1Vg2jt5iSOFw==",
       "cpu": [
         "x64"
       ],
@@ -2812,9 +2815,9 @@
       ]
     },
     "node_modules/@rollup/rollup-openbsd-x64": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.59.0.tgz",
-      "integrity": "sha512-M3bLRAVk6GOwFlPTIxVBSYKUaqfLrn8l0psKinkCFxl4lQvOSz8ZrKDz2gxcBwHFpci0B6rttydI4IpS4IS/jQ==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.57.1.tgz",
+      "integrity": "sha512-H+hXEv9gdVQuDTgnqD+SQffoWoc0Of59AStSzTEj/feWTBAnSfSD3+Dql1ZruJQxmykT/JVY0dE8Ka7z0DH1hw==",
       "cpu": [
         "x64"
       ],
@@ -2826,9 +2829,9 @@
       ]
     },
     "node_modules/@rollup/rollup-openharmony-arm64": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.59.0.tgz",
-      "integrity": "sha512-tt9KBJqaqp5i5HUZzoafHZX8b5Q2Fe7UjYERADll83O4fGqJ49O1FsL6LpdzVFQcpwvnyd0i+K/VSwu/o/nWlA==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.57.1.tgz",
+      "integrity": "sha512-4wYoDpNg6o/oPximyc/NG+mYUejZrCU2q+2w6YZqrAs2UcNUChIZXjtafAiiZSUc7On8v5NyNj34Kzj/Ltk6dQ==",
       "cpu": [
         "arm64"
       ],
@@ -2840,9 +2843,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-arm64-msvc": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.59.0.tgz",
-      "integrity": "sha512-V5B6mG7OrGTwnxaNUzZTDTjDS7F75PO1ae6MJYdiMu60sq0CqN5CVeVsbhPxalupvTX8gXVSU9gq+Rx1/hvu6A==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.57.1.tgz",
+      "integrity": "sha512-O54mtsV/6LW3P8qdTcamQmuC990HDfR71lo44oZMZlXU4tzLrbvTii87Ni9opq60ds0YzuAlEr/GNwuNluZyMQ==",
       "cpu": [
         "arm64"
       ],
@@ -2854,9 +2857,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-ia32-msvc": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.59.0.tgz",
-      "integrity": "sha512-UKFMHPuM9R0iBegwzKF4y0C4J9u8C6MEJgFuXTBerMk7EJ92GFVFYBfOZaSGLu6COf7FxpQNqhNS4c4icUPqxA==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.57.1.tgz",
+      "integrity": "sha512-P3dLS+IerxCT/7D2q2FYcRdWRl22dNbrbBEtxdWhXrfIMPP9lQhb5h4Du04mdl5Woq05jVCDPCMF7Ub0NAjIew==",
       "cpu": [
         "ia32"
       ],
@@ -2868,9 +2871,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-x64-gnu": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.59.0.tgz",
-      "integrity": "sha512-laBkYlSS1n2L8fSo1thDNGrCTQMmxjYY5G0WFWjFFYZkKPjsMBsgJfGf4TLxXrF6RyhI60L8TMOjBMvXiTcxeA==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.57.1.tgz",
+      "integrity": "sha512-VMBH2eOOaKGtIJYleXsi2B8CPVADrh+TyNxJ4mWPnKfLB/DBUmzW+5m1xUrcwWoMfSLagIRpjUFeW5CO5hyciQ==",
       "cpu": [
         "x64"
       ],
@@ -2882,9 +2885,9 @@
       ]
     },
     "node_modules/@rollup/rollup-win32-x64-msvc": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.59.0.tgz",
-      "integrity": "sha512-2HRCml6OztYXyJXAvdDXPKcawukWY2GpR5/nxKp4iBgiO3wcoEGkAaqctIbZcNB6KlUQBIqt8VYkNSj2397EfA==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.57.1.tgz",
+      "integrity": "sha512-mxRFDdHIWRxg3UfIIAwCm6NzvxG0jDX/wBN6KsQFTvKFqqg9vTrWUE68qEjHt19A5wwx5X5aUi2zuZT7YR0jrA==",
       "cpu": [
         "x64"
       ],
@@ -3024,6 +3027,7 @@
       "integrity": "sha512-klQbnPAAiGYFyI02+znpBRLyjL4/BrBd0nyWkdC0s/6xFLkXYQ8OoRrSkqacS1ddVxf/LDyODIKbQ5TgKAf/Fg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "8.56.1",
         "@typescript-eslint/types": "8.56.1",
@@ -3352,6 +3356,7 @@
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -3401,7 +3406,6 @@
       "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-2.1.1.tgz",
       "integrity": "sha512-Wx0Kx52hxE7C18hkMEggYlEifqWZtYaRgouJor+WMdPnQyEK13vgEWyVNup7SoeeoLMsr4kf5h6dOW11I15MUA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "ajv": "^8.0.0"
       },
@@ -3419,7 +3423,6 @@
       "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
       "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -3435,8 +3438,7 @@
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
       "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/ansi-colors": {
       "version": "1.1.0",
@@ -3847,6 +3849,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.9.0",
         "caniuse-lite": "^1.0.30001759",
@@ -4707,6 +4710,7 @@
       "integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.1",
@@ -4883,9 +4887,9 @@
       }
     },
     "node_modules/eslint-plugin-import/node_modules/minimatch": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
-      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
+      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -4906,9 +4910,9 @@
       }
     },
     "node_modules/eslint-plugin-jsdoc": {
-      "version": "62.8.0",
-      "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-62.8.0.tgz",
-      "integrity": "sha512-hu3r9/6JBmPG6wTcqtYzgZAnjEG2eqRUATfkFscokESg1VDxZM21ZaMire0KjeMwfj+SXvgB4Rvh5LBuesj92w==",
+      "version": "62.6.1",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-62.6.1.tgz",
+      "integrity": "sha512-zfz4lMIKDkidkqZniIieZujwZAtpaSNM0WXwilToKoR2UWEw0JE/QevQI2k6YN4ZSy3YhXB3Vs1ab62GZu8Wug==",
       "dev": true,
       "license": "BSD-3-Clause",
       "dependencies": {
@@ -4923,7 +4927,7 @@
         "html-entities": "^2.6.0",
         "object-deep-merge": "^2.0.0",
         "parse-imports-exports": "^0.2.4",
-        "semver": "^7.7.4",
+        "semver": "^7.7.3",
         "spdx-expression-parse": "^4.0.0",
         "to-valid-identifier": "^1.0.0"
       },
@@ -4931,7 +4935,7 @@
         "node": "^20.19.0 || ^22.13.0 || >=24"
       },
       "peerDependencies": {
-        "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0"
+        "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0"
       }
     },
     "node_modules/eslint-plugin-jsdoc/node_modules/eslint-visitor-keys": {
@@ -5079,9 +5083,9 @@
       }
     },
     "node_modules/eslint/node_modules/minimatch": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
-      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
+      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -5317,8 +5321,7 @@
           "url": "https://opencollective.com/fastify"
         }
       ],
-      "license": "BSD-3-Clause",
-      "peer": true
+      "license": "BSD-3-Clause"
     },
     "node_modules/fdir": {
       "version": "6.5.0",
@@ -6823,9 +6826,9 @@
       }
     },
     "node_modules/minimatch": {
-      "version": "10.2.4",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.4.tgz",
-      "integrity": "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg==",
+      "version": "10.2.2",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.2.tgz",
+      "integrity": "sha512-+G4CpNBxa5MprY+04MbgOw1v7So6n5JY166pFi9KfYwT78fxScCeSNQSNzp6dpPSW2rONOps6Ocam1wFhCgoVw==",
       "dev": true,
       "license": "BlueOak-1.0.0",
       "dependencies": {
@@ -7205,6 +7208,7 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -7600,9 +7604,9 @@
       }
     },
     "node_modules/rollup": {
-      "version": "4.59.0",
-      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.59.0.tgz",
-      "integrity": "sha512-2oMpl67a3zCH9H79LeMcbDhXW/UmWG/y2zuqnF2jQq5uq9TbM9TVyXvA4+t+ne2IIkBdrLpAaRQAvo7YI/Yyeg==",
+      "version": "4.57.1",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.57.1.tgz",
+      "integrity": "sha512-oQL6lgK3e2QZeQ7gcgIkS2YZPg5slw37hYufJ3edKlfQSGGm8ICoxswK15ntSzF/a8+h7ekRy7k7oWc3BQ7y8A==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -7616,31 +7620,31 @@
         "npm": ">=8.0.0"
       },
       "optionalDependencies": {
-        "@rollup/rollup-android-arm-eabi": "4.59.0",
-        "@rollup/rollup-android-arm64": "4.59.0",
-        "@rollup/rollup-darwin-arm64": "4.59.0",
-        "@rollup/rollup-darwin-x64": "4.59.0",
-        "@rollup/rollup-freebsd-arm64": "4.59.0",
-        "@rollup/rollup-freebsd-x64": "4.59.0",
-        "@rollup/rollup-linux-arm-gnueabihf": "4.59.0",
-        "@rollup/rollup-linux-arm-musleabihf": "4.59.0",
-        "@rollup/rollup-linux-arm64-gnu": "4.59.0",
-        "@rollup/rollup-linux-arm64-musl": "4.59.0",
-        "@rollup/rollup-linux-loong64-gnu": "4.59.0",
-        "@rollup/rollup-linux-loong64-musl": "4.59.0",
-        "@rollup/rollup-linux-ppc64-gnu": "4.59.0",
-        "@rollup/rollup-linux-ppc64-musl": "4.59.0",
-        "@rollup/rollup-linux-riscv64-gnu": "4.59.0",
-        "@rollup/rollup-linux-riscv64-musl": "4.59.0",
-        "@rollup/rollup-linux-s390x-gnu": "4.59.0",
-        "@rollup/rollup-linux-x64-gnu": "4.59.0",
-        "@rollup/rollup-linux-x64-musl": "4.59.0",
-        "@rollup/rollup-openbsd-x64": "4.59.0",
-        "@rollup/rollup-openharmony-arm64": "4.59.0",
-        "@rollup/rollup-win32-arm64-msvc": "4.59.0",
-        "@rollup/rollup-win32-ia32-msvc": "4.59.0",
-        "@rollup/rollup-win32-x64-gnu": "4.59.0",
-        "@rollup/rollup-win32-x64-msvc": "4.59.0",
+        "@rollup/rollup-android-arm-eabi": "4.57.1",
+        "@rollup/rollup-android-arm64": "4.57.1",
+        "@rollup/rollup-darwin-arm64": "4.57.1",
+        "@rollup/rollup-darwin-x64": "4.57.1",
+        "@rollup/rollup-freebsd-arm64": "4.57.1",
+        "@rollup/rollup-freebsd-x64": "4.57.1",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.57.1",
+        "@rollup/rollup-linux-arm-musleabihf": "4.57.1",
+        "@rollup/rollup-linux-arm64-gnu": "4.57.1",
+        "@rollup/rollup-linux-arm64-musl": "4.57.1",
+        "@rollup/rollup-linux-loong64-gnu": "4.57.1",
+        "@rollup/rollup-linux-loong64-musl": "4.57.1",
+        "@rollup/rollup-linux-ppc64-gnu": "4.57.1",
+        "@rollup/rollup-linux-ppc64-musl": "4.57.1",
+        "@rollup/rollup-linux-riscv64-gnu": "4.57.1",
+        "@rollup/rollup-linux-riscv64-musl": "4.57.1",
+        "@rollup/rollup-linux-s390x-gnu": "4.57.1",
+        "@rollup/rollup-linux-x64-gnu": "4.57.1",
+        "@rollup/rollup-linux-x64-musl": "4.57.1",
+        "@rollup/rollup-openbsd-x64": "4.57.1",
+        "@rollup/rollup-openharmony-arm64": "4.57.1",
+        "@rollup/rollup-win32-arm64-msvc": "4.57.1",
+        "@rollup/rollup-win32-ia32-msvc": "4.57.1",
+        "@rollup/rollup-win32-x64-gnu": "4.57.1",
+        "@rollup/rollup-win32-x64-msvc": "4.57.1",
         "fsevents": "~2.3.2"
       }
     },
@@ -7743,7 +7747,6 @@
       "resolved": "https://registry.npmjs.org/schema-utils/-/schema-utils-4.3.3.tgz",
       "integrity": "sha512-eflK8wEtyOE6+hsaRVPxvUKYCpRgzLqDTb8krvAsRIwOGlHoSgYLgBXoubGgLd2fT41/OUYdb48v4k4WWHQurA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/json-schema": "^7.0.9",
         "ajv": "^8.9.0",
@@ -7780,7 +7783,6 @@
       "resolved": "https://registry.npmjs.org/ajv-keywords/-/ajv-keywords-5.1.0.tgz",
       "integrity": "sha512-YCS/JNFAUyr5vAuhk1DWm1CBxRHW9LbJ2ozWeemrIqpbsqKjHVxYPyi5GC0rjZIT5JxJ3virVTS8wk4i/Z+krw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3"
       },
@@ -7792,8 +7794,7 @@
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
       "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/semver": {
       "version": "7.7.4",
@@ -8535,6 +8536,7 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -8763,6 +8765,7 @@
       "integrity": "sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "esbuild": "^0.27.0",
         "fdir": "^6.5.0",
diff --git a/crates/js/lib/package.json b/crates/js/lib/package.json
index 7d2257f6..9beca211 100644
--- a/crates/js/lib/package.json
+++ b/crates/js/lib/package.json
@@ -26,7 +26,7 @@
     "eslint": "^9.10.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-jsdoc": "^62.8.0",
+    "eslint-plugin-jsdoc": "^62.5.4",
     "eslint-plugin-unicorn": "^62.0.0",
     "jsdom": "^28.0.0",
     "prettier": "^3.2.5",
diff --git a/crates/js/lib/src/core/render.ts b/crates/js/lib/src/core/render.ts
index ee08ef28..da223851 100644
--- a/crates/js/lib/src/core/render.ts
+++ b/crates/js/lib/src/core/render.ts
@@ -7,16 +7,15 @@ import NORMALIZE_CSS from './styles/normalize.css?inline';
 import IFRAME_TEMPLATE from './templates/iframe.html?raw';
 
 // Sandbox permissions granted to creative iframes.
-// Ad creatives routinely contain scripts for tracking, click handling, and
-// viewability measurement, so allow-scripts and allow-same-origin are required
-// for creatives to render correctly. Server-side sanitization is the primary
-// defense against malicious markup; the sandbox provides defense-in-depth.
+// Notably absent:
+//   allow-scripts, allow-same-origin — prevent JS execution and same-origin
+//     access, which are the primary attack vectors for malicious creatives.
+//   allow-forms — server-side sanitization strips <form> elements, so form
+//     submission from creatives is not a supported use case. Omitting this token
+//     is consistent with that server-side policy and reduces the attack surface.
 const CREATIVE_SANDBOX_TOKENS = [
-  'allow-forms',
   'allow-popups',
   'allow-popups-to-escape-sandbox',
-  'allow-same-origin',
-  'allow-scripts',
   'allow-top-navigation-by-user-activation',
 ] as const;
 
diff --git a/crates/js/lib/src/integrations/prebid/index.ts b/crates/js/lib/src/integrations/prebid/index.ts
index f2a815b7..63282513 100644
--- a/crates/js/lib/src/integrations/prebid/index.ts
+++ b/crates/js/lib/src/integrations/prebid/index.ts
@@ -269,13 +269,6 @@ export function installPrebidNpm(config?: Partial<PrebidNpmConfig>): typeof pbjs
       } else {
         unit.bids.push({ bidder: ADAPTER_CODE, params: tsParams });
       }
-
-      // Remove server-side bidder entries — they are now handled via the
-      // trustedServer adapter. Only keep client-side bidders (which run via
-      // their native Prebid.js adapters) and the trustedServer bid itself.
-      unit.bids = unit.bids.filter(
-        (b) => b.bidder === ADAPTER_CODE || clientSideBidders.has(b.bidder ?? '')
-      );
     }
 
     // Ensure the trustedServer adapter is allowed to return bids under any
diff --git a/crates/js/lib/test/core/render.test.ts b/crates/js/lib/test/core/render.test.ts
index a81486cf..5bdb3a81 100644
--- a/crates/js/lib/test/core/render.test.ts
+++ b/crates/js/lib/test/core/render.test.ts
@@ -27,12 +27,12 @@ describe('render', () => {
     expect(iframe.srcdoc).toContain('<span>ad</span>');
     expect(div.querySelector('iframe')).toBe(iframe);
     const sandbox = iframe.getAttribute('sandbox') ?? '';
-    expect(sandbox).toContain('allow-forms');
+    expect(sandbox).not.toContain('allow-forms');
     expect(sandbox).toContain('allow-popups');
     expect(sandbox).toContain('allow-popups-to-escape-sandbox');
     expect(sandbox).toContain('allow-top-navigation-by-user-activation');
-    expect(sandbox).toContain('allow-same-origin');
-    expect(sandbox).toContain('allow-scripts');
+    expect(sandbox).not.toContain('allow-same-origin');
+    expect(sandbox).not.toContain('allow-scripts');
   });
 
   it('preserves dollar sequences when building the creative document', async () => {
diff --git a/crates/js/lib/test/integrations/prebid/index.test.ts b/crates/js/lib/test/integrations/prebid/index.test.ts
index a68150cb..961b7abc 100644
--- a/crates/js/lib/test/integrations/prebid/index.test.ts
+++ b/crates/js/lib/test/integrations/prebid/index.test.ts
@@ -411,13 +411,14 @@ describe('prebid/installPrebidNpm', () => {
       ];
       pbjs.requestBids({ adUnits } as any);
 
-      // Each ad unit should only have trustedServer — original bidders are absorbed
+      // Each ad unit should have trustedServer added
       for (const unit of adUnits) {
-        expect(unit.bids).toHaveLength(1);
-        expect(unit.bids[0].bidder).toBe('trustedServer');
+        const hasTsBidder = unit.bids.some((b: any) => b.bidder === 'trustedServer');
+        expect(hasTsBidder).toBe(true);
       }
 
-      expect(adUnits[0].bids[0].params.bidderParams).toEqual({ appnexus: {} });
+      const trustedServerBid = adUnits[0].bids.find((b: any) => b.bidder === 'trustedServer');
+      expect(trustedServerBid.params.bidderParams).toEqual({ appnexus: {} });
 
       // Should call through to original requestBids
       expect(mockRequestBids).toHaveBeenCalled();
@@ -433,7 +434,7 @@ describe('prebid/installPrebidNpm', () => {
       expect(tsCount).toBe(1);
     });
 
-    it('captures per-bidder params on trustedServer bid and removes originals', () => {
+    it('captures per-bidder params on trustedServer bid', () => {
       const pbjs = installPrebidNpm();
 
       const adUnits = [
@@ -446,10 +447,8 @@ describe('prebid/installPrebidNpm', () => {
       ];
       pbjs.requestBids({ adUnits } as any);
 
-      // Only trustedServer should remain — original bidders are absorbed
-      expect(adUnits[0].bids).toHaveLength(1);
-      const trustedServerBid = adUnits[0].bids[0] as any;
-      expect(trustedServerBid.bidder).toBe('trustedServer');
+      const trustedServerBid = adUnits[0].bids.find((b: any) => b.bidder === 'trustedServer');
+      expect(trustedServerBid).toBeDefined();
       expect(trustedServerBid.params.bidderParams).toEqual({
         appnexus: { placementId: 123 },
         rubicon: { accountId: 'abc' },
@@ -483,12 +482,11 @@ describe('prebid/installPrebidNpm', () => {
       ];
       pbjs.requestBids({ adUnits } as any);
 
-      // Original kargo bids should be removed, only trustedServer remains
-      expect(adUnits[0].bids).toHaveLength(1);
-      expect(adUnits[0].bids[0].params.zone).toBe('header');
+      const tsBid0 = adUnits[0].bids.find((b: any) => b.bidder === 'trustedServer') as any;
+      expect(tsBid0.params.zone).toBe('header');
 
-      expect(adUnits[1].bids).toHaveLength(1);
-      expect(adUnits[1].bids[0].params.zone).toBe('fixed_bottom');
+      const tsBid1 = adUnits[1].bids.find((b: any) => b.bidder === 'trustedServer') as any;
+      expect(tsBid1.params.zone).toBe('fixed_bottom');
     });
 
     it('omits zone when mediaTypes.banner.name is not set', () => {
@@ -503,8 +501,8 @@ describe('prebid/installPrebidNpm', () => {
       ];
       pbjs.requestBids({ adUnits } as any);
 
-      expect(adUnits[0].bids).toHaveLength(1);
-      expect(adUnits[0].bids[0].params.zone).toBeUndefined();
+      const tsBid = adUnits[0].bids.find((b: any) => b.bidder === 'trustedServer') as any;
+      expect(tsBid.params.zone).toBeUndefined();
     });
 
     it('omits zone when ad unit has no mediaTypes', () => {
@@ -513,8 +511,8 @@ describe('prebid/installPrebidNpm', () => {
       const adUnits = [{ bids: [{ bidder: 'rubicon', params: {} }] }];
       pbjs.requestBids({ adUnits } as any);
 
-      expect(adUnits[0].bids).toHaveLength(1);
-      expect(adUnits[0].bids[0].params.zone).toBeUndefined();
+      const tsBid = adUnits[0].bids.find((b: any) => b.bidder === 'trustedServer') as any;
+      expect(tsBid.params.zone).toBeUndefined();
     });
 
     it('clears stale zone when existing trustedServer bid is reused', () => {
@@ -551,10 +549,10 @@ describe('prebid/installPrebidNpm', () => {
       mockPbjs.adUnits = [{ bids: [{ bidder: 'openx', params: {} }] }] as any[];
       pbjs.requestBids({} as any);
 
-      // Original openx bid should be removed, only trustedServer remains
-      const unit = mockPbjs.adUnits[0] as any;
-      expect(unit.bids).toHaveLength(1);
-      expect(unit.bids[0].bidder).toBe('trustedServer');
+      const hasTsBidder = (mockPbjs.adUnits[0] as any).bids.some(
+        (b: any) => b.bidder === 'trustedServer'
+      );
+      expect(hasTsBidder).toBe(true);
     });
   });
 });
@@ -613,7 +611,7 @@ describe('prebid/client-side bidders', () => {
     delete (window as any).__tsjs_prebid;
   });
 
-  it('excludes client-side bidders from trustedServer bidderParams and removes server-side bids', () => {
+  it('excludes client-side bidders from trustedServer bidderParams', () => {
     (window as any).__tsjs_prebid = { clientSideBidders: ['rubicon'] };
 
     const pbjs = installPrebidNpm();
@@ -629,8 +627,6 @@ describe('prebid/client-side bidders', () => {
     ];
     pbjs.requestBids({ adUnits } as any);
 
-    // Only rubicon (client-side) and trustedServer should remain
-    expect(adUnits[0].bids).toHaveLength(2);
     const tsBid = adUnits[0].bids.find((b: any) => b.bidder === 'trustedServer') as any;
     expect(tsBid).toBeDefined();
     // rubicon should NOT be in bidderParams — it runs client-side
@@ -638,9 +634,6 @@ describe('prebid/client-side bidders', () => {
       appnexus: { placementId: 123 },
       kargo: { placementId: 'k1' },
     });
-    // appnexus and kargo should be removed (absorbed into trustedServer)
-    expect(adUnits[0].bids.find((b: any) => b.bidder === 'appnexus')).toBeUndefined();
-    expect(adUnits[0].bids.find((b: any) => b.bidder === 'kargo')).toBeUndefined();
   });
 
   it('preserves client-side bidder bids as standalone entries', () => {
@@ -680,8 +673,6 @@ describe('prebid/client-side bidders', () => {
     ];
     pbjs.requestBids({ adUnits } as any);
 
-    // 3 bids: rubicon (client-side), openx (client-side), trustedServer
-    expect(adUnits[0].bids).toHaveLength(3);
     const tsBid = adUnits[0].bids.find((b: any) => b.bidder === 'trustedServer') as any;
     // Only appnexus should be in bidderParams
     expect(tsBid.params.bidderParams).toEqual({
@@ -691,9 +682,6 @@ describe('prebid/client-side bidders', () => {
     // Both client-side bidders should remain
     expect(adUnits[0].bids.find((b: any) => b.bidder === 'rubicon')).toBeDefined();
     expect(adUnits[0].bids.find((b: any) => b.bidder === 'openx')).toBeDefined();
-
-    // Server-side bidder should be removed
-    expect(adUnits[0].bids.find((b: any) => b.bidder === 'appnexus')).toBeUndefined();
   });
 
   it('behaves normally when no client-side bidders are configured', () => {
@@ -710,10 +698,7 @@ describe('prebid/client-side bidders', () => {
     ];
     pbjs.requestBids({ adUnits } as any);
 
-    // All original bidders should be removed, only trustedServer remains
-    expect(adUnits[0].bids).toHaveLength(1);
-    const tsBid = adUnits[0].bids[0] as any;
-    expect(tsBid.bidder).toBe('trustedServer');
+    const tsBid = adUnits[0].bids.find((b: any) => b.bidder === 'trustedServer') as any;
     expect(tsBid.params.bidderParams).toEqual({
       appnexus: { placementId: 123 },
       rubicon: { accountId: 'abc' },
@@ -735,10 +720,7 @@ describe('prebid/client-side bidders', () => {
     ];
     pbjs.requestBids({ adUnits } as any);
 
-    // All original bidders should be removed, only trustedServer remains
-    expect(adUnits[0].bids).toHaveLength(1);
-    const tsBid = adUnits[0].bids[0] as any;
-    expect(tsBid.bidder).toBe('trustedServer');
+    const tsBid = adUnits[0].bids.find((b: any) => b.bidder === 'trustedServer') as any;
     expect(tsBid.params.bidderParams).toEqual({
       appnexus: { placementId: 123 },
       rubicon: { accountId: 'abc' },
@@ -760,8 +742,7 @@ describe('prebid/client-side bidders', () => {
     ];
     pbjs.requestBids({ adUnits } as any);
 
-    // All 3 should be present: rubicon, appnexus (both client-side), and trustedServer
-    expect(adUnits[0].bids).toHaveLength(3);
+    // trustedServer should still be present (even with empty bidderParams)
     const tsBid = adUnits[0].bids.find((b: any) => b.bidder === 'trustedServer') as any;
     expect(tsBid).toBeDefined();
     expect(tsBid.params.bidderParams).toEqual({});
diff --git a/crates/trusted-server-core/README.md b/crates/trusted-server-core/README.md
index 364ef39c..3b54bfcb 100644
--- a/crates/trusted-server-core/README.md
+++ b/crates/trusted-server-core/README.md
@@ -49,10 +49,11 @@ Behavior is covered by an extensive test suite in `crates/trusted-server-core/sr
 
 ## Edge Cookie (EC) Identifier Propagation
 
-- `edge_cookie.rs` generates an edge cookie identifier per user request and exposes helpers:
-  - `generate_ec_id` — creates a fresh HMAC-based ID using the client IP address and appends a short random suffix (format: `64hex.6alnum`).
-  - `get_ec_id` — extracts an existing ID from the `x-ts-ec` header or `ts-ec` cookie.
-  - `get_or_generate_ec_id` — reuses the existing ID when present, otherwise creates one.
+- The `ec/` module owns the EC identity subsystem:
+  - `ec/generation.rs` — creates HMAC-based IDs using the client IP and publisher passphrase (format: `64hex.6alnum`).
+  - `ec/mod.rs` — `EcContext` struct with two-phase lifecycle (`read_from_request` + `generate_if_needed`), `get_ec_id` helper.
+  - `ec/consent.rs` — EC-specific consent gating wrapper.
+  - `ec/cookies.rs` — `Set-Cookie` header creation and expiration helpers.
 - `publisher.rs::handle_publisher_request` stamps proxied origin responses with `x-ts-ec`, and (when absent) issues the `ts-ec` cookie so the browser keeps the identifier on subsequent requests.
 - `proxy.rs::handle_first_party_proxy` replays the identifier to third-party creative origins by appending `ts-ec=<value>` to the reconstructed target URL, follows redirects (301/302/303/307/308) up to four hops, and keeps downstream fetches linked to the same user scope.
 - `proxy.rs::handle_first_party_click` adds `ts-ec=<value>` to outbound click redirect URLs so analytics endpoints can associate clicks with impressions without third-party cookies.
diff --git a/crates/trusted-server-core/src/auction/endpoints.rs b/crates/trusted-server-core/src/auction/endpoints.rs
index 018b2b38..605f8ee9 100644
--- a/crates/trusted-server-core/src/auction/endpoints.rs
+++ b/crates/trusted-server-core/src/auction/endpoints.rs
@@ -4,12 +4,9 @@ use error_stack::{Report, ResultExt};
 use fastly::{Request, Response};
 
 use crate::auction::formats::AdRequest;
-use crate::consent;
-use crate::cookies::handle_request_cookies;
-use crate::edge_cookie::get_or_generate_ec_id;
+use crate::ec::EcContext;
 use crate::error::TrustedServerError;
-use crate::geo::GeoInfo;
-use crate::platform::RuntimeServices;
+
 use crate::settings::Settings;
 
 use super::formats::{convert_to_openrtb_response, convert_tsjs_to_auction_request};
@@ -35,6 +32,18 @@ pub async fn handle_auction(
     runtime_services: &RuntimeServices,
     mut req: Request,
 ) -> Result<Response, Report<TrustedServerError>> {
+    // Read EC state before consuming the request body.
+    let mut ec_context = EcContext::read_from_request(settings, &req).change_context(
+        TrustedServerError::Auction {
+            message: "Failed to read EC context".to_string(),
+        },
+    )?;
+
+    // Auction is an organic handler — generate EC if needed.
+    if let Err(err) = ec_context.generate_if_needed(settings) {
+        log::warn!("EC generation failed for auction: {err:?}");
+    }
+
     // Parse request body
     let body: AdRequest = serde_json::from_slice(&req.take_body_bytes()).change_context(
         TrustedServerError::Auction {
@@ -47,33 +56,20 @@ pub async fn handle_auction(
         body.ad_units.len()
     );
 
-    // Generate EC ID early so the consent pipeline can use it for
-    // KV Store fallback/write operations.
-    let ec_id =
-        get_or_generate_ec_id(settings, &req).change_context(TrustedServerError::Auction {
-            message: "Failed to generate EC ID".to_string(),
-        })?;
-
-    // Extract consent from request cookies, headers, and geo.
-    let cookie_jar = handle_request_cookies(&req)?;
-    #[allow(deprecated)]
-    let geo = GeoInfo::from_request(&req);
-    let consent_context = consent::build_consent_context(&consent::ConsentPipelineInput {
-        jar: cookie_jar.as_ref(),
-        req: &req,
-        config: &settings.consent,
-        geo: geo.as_ref(),
-        ec_id: Some(ec_id.as_str()),
-        kv_store: settings
-            .consent
-            .consent_store
-            .as_deref()
-            .map(|_| runtime_services.kv_store()),
-    });
+    // Only forward the EC ID to auction partners when consent allows it.
+    // A returning user may still have a ts-ec cookie but have since
+    // withdrawn consent — forwarding that revoked ID to bidders would
+    // defeat the consent gating.
+    let ec_id = if ec_context.ec_allowed() {
+        ec_context.ec_value().unwrap_or("")
+    } else {
+        ""
+    };
+    let consent_context = ec_context.consent().clone();
 
     // Convert tsjs request format to auction request
     let auction_request =
-        convert_tsjs_to_auction_request(&body, settings, &req, consent_context, &ec_id)?;
+        convert_tsjs_to_auction_request(&body, settings, &req, consent_context, ec_id)?;
 
     // Create auction context
     let context = AuctionContext {
diff --git a/crates/trusted-server-core/src/auction/formats.rs b/crates/trusted-server-core/src/auction/formats.rs
index 1f557a17..92a3f533 100644
--- a/crates/trusted-server-core/src/auction/formats.rs
+++ b/crates/trusted-server-core/src/auction/formats.rs
@@ -14,9 +14,8 @@ use uuid::Uuid;
 
 use crate::auction::context::ContextValue;
 use crate::consent::ConsentContext;
-use crate::constants::{HEADER_X_TS_EC, HEADER_X_TS_EC_FRESH};
+use crate::constants::HEADER_X_TS_EC;
 use crate::creative;
-use crate::edge_cookie::generate_ec_id;
 use crate::error::TrustedServerError;
 use crate::geo::GeoInfo;
 use crate::openrtb::{to_openrtb_i32, OpenRtbBid, OpenRtbResponse, ResponseExt, SeatBid, ToExt};
@@ -88,9 +87,6 @@ pub fn convert_tsjs_to_auction_request(
     ec_id: &str,
 ) -> Result<AuctionRequest, Report<TrustedServerError>> {
     let ec_id = ec_id.to_owned();
-    let fresh_id = generate_ec_id(settings, req).change_context(TrustedServerError::Auction {
-        message: "Failed to generate fresh EC ID".to_string(),
-    })?;
 
     // Convert ad units to slots
     let mut slots = Vec::new();
@@ -185,7 +181,6 @@ pub fn convert_tsjs_to_auction_request(
         },
         user: UserInfo {
             id: ec_id,
-            fresh_id,
             consent: Some(consent),
         },
         device,
@@ -313,6 +308,5 @@ pub fn convert_to_openrtb_response(
     Ok(Response::from_status(StatusCode::OK)
         .with_header(header::CONTENT_TYPE, "application/json")
         .with_header(HEADER_X_TS_EC, &auction_request.user.id)
-        .with_header(HEADER_X_TS_EC_FRESH, &auction_request.user.fresh_id)
         .with_body(body_bytes))
 }
diff --git a/crates/trusted-server-core/src/auction/orchestrator.rs b/crates/trusted-server-core/src/auction/orchestrator.rs
index 0fc6ee9f..23116256 100644
--- a/crates/trusted-server-core/src/auction/orchestrator.rs
+++ b/crates/trusted-server-core/src/auction/orchestrator.rs
@@ -626,7 +626,6 @@ mod tests {
             },
             user: UserInfo {
                 id: "user-123".to_string(),
-                fresh_id: "fresh-456".to_string(),
                 consent: None,
             },
             device: None,
diff --git a/crates/trusted-server-core/src/auction/types.rs b/crates/trusted-server-core/src/auction/types.rs
index aa863d61..0ac5b978 100644
--- a/crates/trusted-server-core/src/auction/types.rs
+++ b/crates/trusted-server-core/src/auction/types.rs
@@ -71,8 +71,6 @@ pub struct PublisherInfo {
 pub struct UserInfo {
     /// Stable EC ID (from cookie or freshly generated)
     pub id: String,
-    /// Fresh ID for this session
-    pub fresh_id: String,
     /// Decoded consent context for this request.
     ///
     /// Carries both raw consent strings (for `OpenRTB` forwarding) and decoded
diff --git a/crates/trusted-server-core/src/consent/mod.rs b/crates/trusted-server-core/src/consent/mod.rs
index 9d605008..83afcde5 100644
--- a/crates/trusted-server-core/src/consent/mod.rs
+++ b/crates/trusted-server-core/src/consent/mod.rs
@@ -481,8 +481,12 @@ pub fn gate_eids_by_consent<T>(
 ///   information on a device) must be explicitly consented. If no TCF data is
 ///   available under GDPR, consent is assumed absent and EC is blocked.
 /// - **US state privacy**: opt-out model — EC is allowed unless the user has
-///   explicitly opted out via the US Privacy string or Global Privacy Control.
-/// - **Non-regulated / Unknown**: EC is allowed (no consent requirement).
+///   explicitly opted out via the US Privacy string **or** Global Privacy
+///   Control. GPC is checked independently — it always blocks EC creation
+///   regardless of what the US Privacy string says.
+/// - **Non-regulated**: EC is allowed (no consent requirement).
+/// - **Unknown**: fail-closed — jurisdiction cannot be determined so EC is
+///   blocked as a precaution.
 #[must_use]
 pub fn allows_ec_creation(ctx: &ConsentContext) -> bool {
     match &ctx.jurisdiction {
@@ -494,15 +498,23 @@ pub fn allows_ec_creation(ctx: &ConsentContext) -> bool {
             }
         }
         jurisdiction::Jurisdiction::UsState(_) => {
-            // US: opt-out model — allow unless user explicitly opted out.
+            // GPC is an independent opt-out signal — it always blocks EC
+            // creation regardless of what the US Privacy string says.
+            if ctx.gpc {
+                return false;
+            }
+            // Check US Privacy string for explicit opt-out.
             if let Some(usp) = &ctx.us_privacy {
                 usp.opt_out_sale != PrivacyFlag::Yes
             } else {
-                // No US Privacy string — fall back to GPC signal.
-                !ctx.gpc
+                // No opt-out signals present — allow under opt-out model.
+                true
             }
         }
-        jurisdiction::Jurisdiction::NonRegulated | jurisdiction::Jurisdiction::Unknown => true,
+        jurisdiction::Jurisdiction::NonRegulated => true,
+        // No geolocation data — cannot determine jurisdiction.
+        // Fail-closed: block EC creation as a precaution.
+        jurisdiction::Jurisdiction::Unknown => false,
     }
 }
 
@@ -1036,14 +1048,33 @@ mod tests {
     }
 
     #[test]
-    fn ec_allowed_unknown_jurisdiction() {
+    fn ec_blocked_unknown_jurisdiction() {
         let ctx = ConsentContext {
             jurisdiction: Jurisdiction::Unknown,
             ..ConsentContext::default()
         };
         assert!(
-            allows_ec_creation(&ctx),
-            "unknown jurisdiction should allow EC (no geo data available)"
+            !allows_ec_creation(&ctx),
+            "unknown jurisdiction should block EC (fail-closed when geo unavailable)"
+        );
+    }
+
+    #[test]
+    fn ec_blocked_us_state_gpc_overrides_us_privacy() {
+        let ctx = ConsentContext {
+            jurisdiction: Jurisdiction::UsState("CA".to_owned()),
+            us_privacy: Some(UsPrivacy {
+                version: 1,
+                notice_given: PrivacyFlag::Yes,
+                opt_out_sale: PrivacyFlag::No,
+                lspa_covered: PrivacyFlag::NotApplicable,
+            }),
+            gpc: true,
+            ..ConsentContext::default()
+        };
+        assert!(
+            !allows_ec_creation(&ctx),
+            "GPC=true should block EC even when US Privacy says no opt-out"
         );
     }
 
diff --git a/crates/trusted-server-core/src/constants.rs b/crates/trusted-server-core/src/constants.rs
index 0ee9fc76..0294cd25 100644
--- a/crates/trusted-server-core/src/constants.rs
+++ b/crates/trusted-server-core/src/constants.rs
@@ -4,7 +4,6 @@ pub const COOKIE_TS_EC: &str = "ts-ec";
 
 pub const HEADER_X_PUB_USER_ID: HeaderName = HeaderName::from_static("x-pub-user-id");
 pub const HEADER_X_TS_EC: HeaderName = HeaderName::from_static("x-ts-ec");
-pub const HEADER_X_TS_EC_FRESH: HeaderName = HeaderName::from_static("x-ts-ec-fresh");
 pub const HEADER_X_CONSENT_ADVERTISING: HeaderName =
     HeaderName::from_static("x-consent-advertising");
 pub const HEADER_X_FORWARDED_FOR: HeaderName = HeaderName::from_static("x-forwarded-for");
@@ -45,7 +44,6 @@ pub const HEADER_REFERER: HeaderName = HeaderName::from_static("referer");
 /// in `const` context.
 pub const INTERNAL_HEADERS: &[&str] = &[
     "x-ts-ec",
-    "x-ts-ec-fresh",
     "x-pub-user-id",
     "x-subject-id",
     "x-consent-advertising",
diff --git a/crates/trusted-server-core/src/creative.rs b/crates/trusted-server-core/src/creative.rs
index 245af0e1..45162d8c 100644
--- a/crates/trusted-server-core/src/creative.rs
+++ b/crates/trusted-server-core/src/creative.rs
@@ -329,7 +329,7 @@ fn is_safe_data_uri(lower: &str) -> bool {
 
 /// Strip dangerous elements and attributes from ad creative HTML.
 ///
-/// Removes elements that can execute code or exfiltrate data (`script`,
+/// Removes elements that can execute code or exfiltrate data (`script`, `iframe`,
 /// `object`, `embed`, `base`, `meta`, `form`, `link`, `style`, `noscript`) and strips `on*` event-handler
 /// attributes and dangerous URI schemes from all remaining elements:
 /// - `javascript:`, `vbscript:`
@@ -361,17 +361,18 @@ pub fn sanitize_creative_html(markup: &str) -> String {
         HtmlSettings {
             element_content_handlers: vec![
                 // Remove executable/dangerous elements along with their inner content.
-                // - <script>, <object>, <embed>: direct execution vectors.
+                // - <script>, <iframe>, <object>, <embed>: direct execution vectors.
                 // - <base>: rewrites all relative URLs, undermining the proxy rewriter.
                 // - <meta>: can trigger redirects (http-equiv=refresh) or inject CSP.
-                // - <form>: action/formaction can exfiltrate data.
+                // - <form>: action/formaction can exfiltrate data; stripped to match the
+                //   iframe sandbox which omits allow-forms.
                 // - <link>: external stylesheet/resource loading.
                 // - <style>: CSS expressions, @import, and url() data exfiltration.
                 // - <noscript>: rendered when scripts are disabled (always the case
                 //   inside a sandbox without allow-scripts); strip to prevent parser
                 //   differential attacks.
                 element!(
-                    "script, object, embed, base, meta, form, link, style, noscript",
+                    "script, iframe, object, embed, base, meta, form, link, style, noscript",
                     |el| {
                         el.remove();
                         Ok(())
@@ -453,9 +454,10 @@ pub fn sanitize_creative_html(markup: &str) -> String {
                     // NOTE: This uses simple substring matching on the lowercased value,
                     // which does not handle CSS escape sequences (e.g. `\65xpression(`)
                     // or comments (e.g. `expr/**/ession(`). That is acceptable: CSS
-                    // expression() is IE6-8 only, and downstream rendering still happens
-                    // inside a sandboxed iframe. This check is defense-in-depth for
-                    // obvious patterns.
+                    // expression() is IE6-8 only and the iframe sandbox's absence of
+                    // allow-scripts prevents execution even if an obfuscated value were
+                    // to slip through. The sandbox is the primary mitigation; this check
+                    // is defense-in-depth for obvious patterns.
                     if let Some(style) = el.get_attribute("style") {
                         let lower = style.to_ascii_lowercase();
                         if lower.contains("expression(")
@@ -1502,14 +1504,10 @@ mod tests {
     }
 
     #[test]
-    fn sanitize_preserves_iframe_element_and_src() {
+    fn sanitize_removes_iframe_element() {
         let html = r#"<div>ad</div><iframe src="https://evil.example/"></iframe>"#;
         let out = sanitize_creative_html(html);
-        assert!(out.contains("<iframe"), "should preserve iframe element");
-        assert!(
-            out.contains("https://evil.example/"),
-            "should preserve safe iframe src"
-        );
+        assert!(!out.contains("<iframe"), "should remove iframe element");
         assert!(out.contains("ad"), "should preserve safe content");
     }
 
diff --git a/crates/trusted-server-core/src/ec/consent.rs b/crates/trusted-server-core/src/ec/consent.rs
new file mode 100644
index 00000000..bd78765e
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/consent.rs
@@ -0,0 +1,22 @@
+//! EC-specific consent gating.
+//!
+//! This module provides the public consent-check API for the EC subsystem.
+//! The underlying logic lives in [`crate::consent::allows_ec_creation`]; this
+//! wrapper exists so that EC callers can import from `ec::consent` and the
+//! eventual migration path (renaming, adding EC-specific conditions) is
+//! contained here.
+
+use crate::consent::ConsentContext;
+
+/// Determines whether Edge Cookie creation is permitted based on the
+/// user's consent and detected jurisdiction.
+///
+/// This is the canonical entry point for EC consent checks. It delegates
+/// to [`crate::consent::allows_ec_creation`] today but may diverge as
+/// EC-specific consent rules evolve.
+///
+/// See [`crate::consent::allows_ec_creation`] for the full decision matrix.
+#[must_use]
+pub fn ec_consent_granted(consent_context: &ConsentContext) -> bool {
+    crate::consent::allows_ec_creation(consent_context)
+}
diff --git a/crates/trusted-server-core/src/ec/cookies.rs b/crates/trusted-server-core/src/ec/cookies.rs
new file mode 100644
index 00000000..f13e12be
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/cookies.rs
@@ -0,0 +1,125 @@
+//! EC cookie creation and expiration helpers.
+//!
+//! These functions handle the `Set-Cookie` header for the `ts-ec` cookie.
+//! Cookie attributes follow current best practices:
+//!
+//! - `Domain` is computed as `.{publisher.domain}` for subdomain coverage
+//! - `Path=/` makes the cookie available on all paths
+//! - `Secure` restricts to HTTPS
+//! - `SameSite=Lax` provides CSRF protection while allowing top-level navigations
+//! - `Max-Age` of 1 year (or 0 to expire)
+//! - No `HttpOnly` — the cookie needs to be readable by client-side scripts
+
+use fastly::http::header;
+
+use crate::constants::COOKIE_TS_EC;
+use crate::settings::Settings;
+
+/// Maximum age for the EC cookie (1 year in seconds).
+const COOKIE_MAX_AGE: i32 = 365 * 24 * 60 * 60;
+
+/// Formats a `Set-Cookie` header value for the EC cookie.
+///
+/// Centralises the cookie attribute string so that changes to security
+/// attributes (e.g. adding `Partitioned`) only need updating in one place.
+fn format_set_cookie(domain: &str, value: &str, max_age: i32) -> String {
+    format!(
+        "{}={}; Domain={}; Path=/; Secure; SameSite=Lax; Max-Age={}",
+        COOKIE_TS_EC, value, domain, max_age,
+    )
+}
+
+/// Creates an EC cookie `Set-Cookie` header value.
+///
+/// Per spec §5.2, the EC cookie domain is computed from
+/// `settings.publisher.domain` (not `cookie_domain`) to ensure the EC
+/// cookie is always scoped to the publisher's apex domain.
+#[must_use]
+pub fn create_ec_cookie(settings: &Settings, ec_id: &str) -> String {
+    format_set_cookie(
+        &settings.publisher.ec_cookie_domain(),
+        ec_id,
+        COOKIE_MAX_AGE,
+    )
+}
+
+/// Sets the EC ID cookie on the given response.
+pub fn set_ec_cookie(settings: &Settings, response: &mut fastly::Response, ec_id: &str) {
+    response.append_header(header::SET_COOKIE, create_ec_cookie(settings, ec_id));
+}
+
+/// Expires the EC cookie by setting `Max-Age=0`.
+///
+/// Used when a user revokes consent — the browser will delete the cookie
+/// on receipt of this header.
+pub fn expire_ec_cookie(settings: &Settings, response: &mut fastly::Response) {
+    response.append_header(
+        header::SET_COOKIE,
+        format_set_cookie(&settings.publisher.ec_cookie_domain(), "", 0),
+    );
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_support::tests::create_test_settings;
+    use fastly::http::header;
+
+    #[test]
+    fn create_ec_cookie_uses_computed_domain() {
+        let settings = create_test_settings();
+        let result = create_ec_cookie(&settings, "12345");
+
+        assert_eq!(
+            result,
+            format!(
+                "{}=12345; Domain=.{}; Path=/; Secure; SameSite=Lax; Max-Age={}",
+                COOKIE_TS_EC, settings.publisher.domain, COOKIE_MAX_AGE,
+            ),
+            "should use computed cookie domain (.{{domain}})"
+        );
+    }
+
+    #[test]
+    fn set_ec_cookie_appends_header() {
+        let settings = create_test_settings();
+        let mut response = fastly::Response::new();
+        set_ec_cookie(&settings, &mut response, "test-id-123");
+
+        let cookie_header = response
+            .get_header(header::SET_COOKIE)
+            .expect("should have Set-Cookie header");
+        let cookie_str = cookie_header.to_str().expect("should be valid UTF-8");
+
+        assert_eq!(
+            cookie_str,
+            create_ec_cookie(&settings, "test-id-123"),
+            "should match create_ec_cookie output"
+        );
+    }
+
+    #[test]
+    fn expire_ec_cookie_sets_max_age_zero() {
+        let settings = create_test_settings();
+        let mut response = fastly::Response::new();
+        expire_ec_cookie(&settings, &mut response);
+
+        let cookie_header = response
+            .get_header(header::SET_COOKIE)
+            .expect("should have Set-Cookie header");
+        let cookie_str = cookie_header.to_str().expect("should be valid UTF-8");
+
+        assert!(
+            cookie_str.contains("Max-Age=0"),
+            "should set Max-Age=0 to expire cookie"
+        );
+        assert!(
+            cookie_str.starts_with(&format!("{}=;", COOKIE_TS_EC)),
+            "should clear cookie value"
+        );
+        assert!(
+            cookie_str.contains(&format!("Domain=.{}", settings.publisher.domain)),
+            "should use computed cookie domain"
+        );
+    }
+}
diff --git a/crates/trusted-server-core/src/ec/generation.rs b/crates/trusted-server-core/src/ec/generation.rs
new file mode 100644
index 00000000..b54903ea
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/generation.rs
@@ -0,0 +1,251 @@
+//! Edge Cookie (EC) ID generation using HMAC.
+//!
+//! This module provides functionality for generating privacy-preserving EC IDs
+//! based on the client IP address and a secret key.
+
+use std::net::IpAddr;
+
+use error_stack::{Report, ResultExt};
+use hmac::{Hmac, Mac};
+use rand::Rng;
+use sha2::Sha256;
+
+use crate::error::TrustedServerError;
+use crate::settings::Settings;
+
+type HmacSha256 = Hmac<Sha256>;
+
+const ALPHANUMERIC_CHARSET: &[u8] =
+    b"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+
+/// Normalizes an IP address for stable EC ID generation.
+///
+/// For IPv6 addresses, masks to /64 prefix to handle Privacy Extensions
+/// where devices rotate their interface identifier (lower 64 bits).
+/// The first 4 segments are hex-encoded without separators.
+/// IPv4 addresses are returned unchanged.
+fn normalize_ip(ip: IpAddr) -> String {
+    match ip {
+        IpAddr::V4(ipv4) => ipv4.to_string(),
+        IpAddr::V6(ipv6) => {
+            let segments = ipv6.segments();
+            // Keep only the first 4 segments (64 bits) for /64 prefix.
+            // Concatenate as zero-padded hex without separators.
+            format!(
+                "{:04x}{:04x}{:04x}{:04x}",
+                segments[0], segments[1], segments[2], segments[3]
+            )
+        }
+    }
+}
+
+/// Generates a random alphanumeric string of the specified length.
+fn generate_random_suffix(length: usize) -> String {
+    let mut rng = rand::thread_rng();
+    (0..length)
+        .map(|_| {
+            let idx = rng.gen_range(0..ALPHANUMERIC_CHARSET.len());
+            ALPHANUMERIC_CHARSET[idx] as char
+        })
+        .collect()
+}
+
+/// Generates a fresh EC ID from a pre-captured client IP string.
+///
+/// Uses only the client IP (not user-agent or other headers) intentionally:
+/// EC IDs are meant to be simple, privacy-preserving identifiers — not
+/// high-entropy fingerprints. The random suffix provides per-cookie
+/// uniqueness for users behind the same NAT/proxy.
+///
+/// Creates an HMAC-SHA256-based ID using the configured secret key and
+/// the client IP address, then appends a random suffix for additional
+/// uniqueness. The resulting format is `{64hex}.{6alnum}`.
+///
+/// # Errors
+///
+/// - [`TrustedServerError::Ec`] if HMAC generation fails
+pub fn generate_ec_id(
+    settings: &Settings,
+    client_ip: &str,
+) -> Result<String, Report<TrustedServerError>> {
+    log::trace!("Input for fresh EC ID: client_ip={client_ip}");
+
+    let mut mac = HmacSha256::new_from_slice(settings.ec.passphrase.expose().as_bytes())
+        .change_context(TrustedServerError::Ec {
+            message: "Failed to create HMAC instance".to_string(),
+        })?;
+    mac.update(client_ip.as_bytes());
+    let hmac_hash = hex::encode(mac.finalize().into_bytes());
+
+    // Append random 6-character alphanumeric suffix for additional uniqueness.
+    let random_suffix = generate_random_suffix(6);
+    let ec_id = format!("{hmac_hash}.{random_suffix}");
+
+    log::trace!("Generated fresh EC ID: {ec_id}");
+
+    Ok(ec_id)
+}
+
+/// Extracts and normalizes the client IP from a request.
+///
+/// Returns the normalized IP as a string suitable for HMAC input.
+///
+/// # Errors
+///
+/// Returns [`TrustedServerError::Ec`] when the client IP is unavailable
+/// (e.g. in certain test or proxy configurations). EC generation requires
+/// a valid client IP — there is no fallback.
+pub fn extract_client_ip(req: &fastly::Request) -> Result<String, Report<TrustedServerError>> {
+    req.get_client_ip_addr().map(normalize_ip).ok_or_else(|| {
+        Report::new(TrustedServerError::Ec {
+            message: "Client IP required for EC generation but unavailable".to_string(),
+        })
+    })
+}
+
+/// Extracts the stable 64-character hex prefix from an EC ID.
+///
+/// Given an EC ID in `{64hex}.{6alnum}` format, returns the `{64hex}`
+/// portion. If the ID does not contain a dot separator, returns the
+/// entire string.
+#[must_use]
+pub fn ec_hash(ec_id: &str) -> &str {
+    // Find the dot separator; if absent, return the entire string.
+    match ec_id.find('.') {
+        Some(pos) => &ec_id[..pos],
+        None => ec_id,
+    }
+}
+
+/// Checks whether a string matches the expected EC ID format.
+///
+/// The format is `{64hex}.{6alnum}` where the first part is a 64-character
+/// lowercase hex string and the second part is a 6-character alphanumeric
+/// string.
+#[must_use]
+pub fn is_valid_ec_id(value: &str) -> bool {
+    let mut parts = value.split('.');
+    let Some(hmac_part) = parts.next() else {
+        return false;
+    };
+    let Some(suffix_part) = parts.next() else {
+        return false;
+    };
+
+    // Must have exactly two segments.
+    if parts.next().is_some() {
+        return false;
+    }
+
+    hmac_part.len() == 64
+        && suffix_part.len() == 6
+        && hmac_part.bytes().all(|b| b.is_ascii_hexdigit())
+        && suffix_part.bytes().all(|b| b.is_ascii_alphanumeric())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::net::{Ipv4Addr, Ipv6Addr};
+
+    use crate::test_support::tests::create_test_settings;
+
+    #[test]
+    fn normalize_ipv4_unchanged() {
+        let ipv4 = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 100));
+        assert_eq!(normalize_ip(ipv4), "192.168.1.100");
+    }
+
+    #[test]
+    fn normalize_ipv6_masks_to_64_no_separators() {
+        let ipv6 = IpAddr::V6(Ipv6Addr::new(
+            0x2001, 0x0db8, 0x85a3, 0x0000, 0x8a2e, 0x0370, 0x7334, 0x1234,
+        ));
+        assert_eq!(
+            normalize_ip(ipv6),
+            "20010db885a30000",
+            "should concatenate first 4 segments as zero-padded hex without separators"
+        );
+    }
+
+    #[test]
+    fn normalize_ipv6_different_suffix_same_prefix() {
+        // Two IPv6 addresses with same /64 prefix but different interface identifiers
+        // (simulating Privacy Extensions rotation).
+        let ipv6_a = IpAddr::V6(Ipv6Addr::new(
+            0x2001, 0x0db8, 0xabcd, 0x0001, 0x1111, 0x2222, 0x3333, 0x4444,
+        ));
+        let ipv6_b = IpAddr::V6(Ipv6Addr::new(
+            0x2001, 0x0db8, 0xabcd, 0x0001, 0xaaaa, 0xbbbb, 0xcccc, 0xdddd,
+        ));
+        assert_eq!(
+            normalize_ip(ipv6_a),
+            normalize_ip(ipv6_b),
+            "should normalize to the same /64 prefix"
+        );
+        assert_eq!(normalize_ip(ipv6_a), "20010db8abcd0001");
+    }
+
+    #[test]
+    fn generate_produces_valid_format() {
+        let settings = create_test_settings();
+        let ec_id = generate_ec_id(&settings, "192.168.1.1").expect("should generate EC ID");
+        assert!(
+            is_valid_ec_id(&ec_id),
+            "should match EC ID format: {{64hex}}.{{6alnum}}, got: {ec_id}"
+        );
+    }
+
+    #[test]
+    fn ec_hash_extracts_prefix() {
+        let id = format!("{}.Ab12z9", "a".repeat(64));
+        assert_eq!(ec_hash(&id), "a".repeat(64));
+    }
+
+    #[test]
+    fn ec_hash_returns_full_string_without_dot() {
+        assert_eq!(ec_hash("nodot"), "nodot");
+    }
+
+    #[test]
+    fn is_valid_ec_id_accepts_valid() {
+        let value = format!("{}.Ab12z9", "a".repeat(64));
+        assert!(is_valid_ec_id(&value), "should accept a valid EC ID format");
+    }
+
+    #[test]
+    fn is_valid_ec_id_rejects_missing_suffix() {
+        let missing_suffix = "a".repeat(64);
+        assert!(
+            !is_valid_ec_id(&missing_suffix),
+            "should reject missing suffix"
+        );
+    }
+
+    #[test]
+    fn is_valid_ec_id_rejects_invalid_hex() {
+        let invalid_hex = format!("{}.Ab12z9", "a".repeat(63) + "g");
+        assert!(
+            !is_valid_ec_id(&invalid_hex),
+            "should reject non-hex HMAC content"
+        );
+    }
+
+    #[test]
+    fn is_valid_ec_id_rejects_invalid_suffix() {
+        let invalid_suffix = format!("{}.ab-129", "a".repeat(64));
+        assert!(
+            !is_valid_ec_id(&invalid_suffix),
+            "should reject non-alphanumeric suffix"
+        );
+    }
+
+    #[test]
+    fn is_valid_ec_id_rejects_extra_segments() {
+        let extra_segment = format!("{}.Ab12z9.zz", "a".repeat(64));
+        assert!(
+            !is_valid_ec_id(&extra_segment),
+            "should reject extra segments"
+        );
+    }
+}
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
new file mode 100644
index 00000000..6f53b12e
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -0,0 +1,421 @@
+//! Edge Cookie (EC) identity subsystem.
+//!
+//! This module owns the EC lifecycle:
+//!
+//! 1. **Read** — [`EcContext::read_from_request`] extracts any existing EC ID
+//!    from headers/cookies, captures the client IP, and builds the consent
+//!    context. This is called pre-routing on every request.
+//!
+//! 2. **Generate** — [`EcContext::generate_if_needed`] creates a new EC ID
+//!    when none exists and consent allows it. This is called only in organic
+//!    handlers (publisher proxy, integration proxy) — never in read-only
+//!    endpoints like `/identify`.
+//!
+//! # Module structure
+//!
+//! - [`generation`] — HMAC-based ID generation, IP normalization, format helpers
+//! - [`consent`] — EC-specific consent gating wrapper
+//! - [`cookies`] — `Set-Cookie` header creation and expiration helpers
+
+pub mod consent;
+pub mod cookies;
+pub mod generation;
+
+use cookie::CookieJar;
+use error_stack::Report;
+use fastly::Request;
+
+use crate::consent::{self as consent_mod, ConsentContext, ConsentPipelineInput};
+use crate::constants::{COOKIE_TS_EC, HEADER_X_TS_EC};
+use crate::cookies::handle_request_cookies;
+use crate::error::TrustedServerError;
+use crate::geo::GeoInfo;
+use crate::settings::Settings;
+
+pub use generation::{ec_hash, extract_client_ip, generate_ec_id, is_valid_ec_id};
+
+/// Parsed EC identity from an incoming request.
+///
+/// Separates the header-derived and cookie-derived EC values so callers
+/// can apply different policies (e.g. revocation targets the cookie value).
+struct RequestEc {
+    /// EC ID from the `X-ts-ec` header, if present.
+    header_ec: Option<String>,
+    /// EC ID from the `ts-ec` cookie, if present.
+    cookie_ec: Option<String>,
+    /// The parsed cookie jar (retained for consent pipeline input).
+    jar: Option<CookieJar>,
+}
+
+/// Parses EC identity from request headers and cookies in a single pass.
+///
+/// # Errors
+///
+/// - [`TrustedServerError::InvalidHeaderValue`] if cookie parsing fails
+fn parse_ec_from_request(req: &Request) -> Result<RequestEc, Report<TrustedServerError>> {
+    let header_ec = req
+        .get_header(HEADER_X_TS_EC)
+        .and_then(|h| h.to_str().ok())
+        .map(str::to_owned);
+
+    let jar = handle_request_cookies(req)?;
+    let cookie_ec = jar
+        .as_ref()
+        .and_then(|j| j.get(COOKIE_TS_EC))
+        .map(|cookie| cookie.value().to_owned());
+
+    Ok(RequestEc {
+        header_ec,
+        cookie_ec,
+        jar,
+    })
+}
+
+/// Gets an existing EC ID from the request.
+///
+/// Attempts to retrieve an existing EC ID from:
+/// 1. The `x-ts-ec` header
+/// 2. The `ts-ec` cookie
+///
+/// Returns `None` if neither source contains an EC ID.
+///
+/// # Errors
+///
+/// - [`TrustedServerError::InvalidHeaderValue`] if cookie parsing fails
+pub fn get_ec_id(req: &fastly::Request) -> Result<Option<String>, Report<TrustedServerError>> {
+    let parsed = parse_ec_from_request(req)?;
+    // Header takes precedence over cookie.
+    let ec_id = parsed.header_ec.or(parsed.cookie_ec);
+    if let Some(ref id) = ec_id {
+        log::trace!("Existing EC ID found: {id}");
+    }
+    Ok(ec_id)
+}
+
+/// Gets an existing EC ID from the request, or generates a new one.
+///
+/// This is a convenience wrapper that combines [`get_ec_id`] with
+/// [`generation::generate_ec_id`]. It extracts the client IP from the
+/// request for generation when no existing ID is found.
+///
+/// When the client IP is unavailable (e.g. in local testing environments),
+/// falls back to `"unknown"` — all such requests share the same HMAC
+/// base, but the random suffix still provides uniqueness.
+///
+/// # Errors
+///
+/// - [`TrustedServerError::InvalidHeaderValue`] if cookie parsing fails
+/// - [`TrustedServerError::Ec`] if HMAC generation fails
+pub fn get_or_generate_ec_id(
+    settings: &Settings,
+    req: &Request,
+) -> Result<String, Report<TrustedServerError>> {
+    if let Some(id) = get_ec_id(req)? {
+        return Ok(id);
+    }
+
+    // Fallback to "unknown" when client IP is unavailable (e.g. local testing).
+    // All such requests share the same HMAC base; the random suffix provides uniqueness.
+    let client_ip = extract_client_ip(req).unwrap_or_else(|_| "unknown".to_string());
+    let ec_id = generate_ec_id(settings, &client_ip)?;
+    log::trace!("No existing EC ID, generated: {ec_id}");
+    Ok(ec_id)
+}
+
+/// Captures the EC state for a single request lifecycle.
+///
+/// Created via [`read_from_request`](Self::read_from_request) during
+/// pre-routing, then optionally mutated by
+/// [`generate_if_needed`](Self::generate_if_needed) in organic handlers.
+#[derive(Debug)]
+pub struct EcContext {
+    /// The EC ID value, if one exists (from request) or was generated.
+    ec_value: Option<String>,
+    /// The EC ID from the `ts-ec` cookie, if present on the incoming
+    /// request. Stored separately from `ec_value` because the header may
+    /// take precedence, but revocation still needs the cookie value.
+    cookie_ec_value: Option<String>,
+    /// Whether an EC ID was found on the incoming request (header or cookie).
+    ec_was_present: bool,
+    /// Whether a new EC ID was generated during this request.
+    ec_generated: bool,
+    /// The consent context for this request.
+    consent: ConsentContext,
+    /// The normalized client IP, captured early before the request body
+    /// is consumed. `None` when the platform cannot determine client IP.
+    client_ip: Option<String>,
+}
+
+impl EcContext {
+    /// Reads EC state from an incoming request without generating a new ID.
+    ///
+    /// This is the first phase of the EC lifecycle. It:
+    /// - Checks the `X-ts-ec` header and `ts-ec` cookie for an existing EC ID
+    /// - Captures the client IP (normalized) for later generation
+    /// - Builds the full [`ConsentContext`] from cookies, headers, and geo
+    ///
+    /// Call this pre-routing on **every** request.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if cookie parsing fails.
+    pub fn read_from_request(
+        settings: &Settings,
+        req: &Request,
+    ) -> Result<Self, Report<TrustedServerError>> {
+        let parsed = parse_ec_from_request(req)?;
+
+        // Header takes precedence over cookie for the active EC value.
+        // The cookie value is stored separately for revocation handling.
+        let ec_value = parsed.header_ec.or_else(|| parsed.cookie_ec.clone());
+        let ec_was_present = ec_value.is_some();
+
+        if let Some(ref id) = ec_value {
+            log::trace!("Existing EC ID found: {id}");
+        }
+
+        // Capture the client IP now — the request body may be consumed later.
+        let client_ip = generation::extract_client_ip(req).ok();
+
+        // Build consent context. Pass the EC ID (if any) so the consent
+        // pipeline can use it for KV Store fallback/write operations.
+        let geo = GeoInfo::from_request(req);
+        let consent = consent_mod::build_consent_context(&ConsentPipelineInput {
+            jar: parsed.jar.as_ref(),
+            req,
+            config: &settings.consent,
+            geo: geo.as_ref(),
+            ec_id: ec_value.as_deref(),
+        });
+
+        Ok(Self {
+            ec_value,
+            cookie_ec_value: parsed.cookie_ec,
+            ec_was_present,
+            ec_generated: false,
+            consent,
+            client_ip,
+        })
+    }
+
+    /// Generates a new EC ID if none exists and consent allows it.
+    ///
+    /// This is the second phase of the EC lifecycle. Call this only in
+    /// organic handlers (publisher proxy, integration proxy, auction) —
+    /// never in read-only endpoints.
+    ///
+    /// If an EC ID already exists (from the request), this is a no-op.
+    /// If consent does not permit EC creation, this is a no-op.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the client IP is unavailable and generation is
+    /// needed, or if HMAC generation fails.
+    pub fn generate_if_needed(
+        &mut self,
+        settings: &Settings,
+    ) -> Result<(), Report<TrustedServerError>> {
+        if self.ec_value.is_some() {
+            return Ok(());
+        }
+
+        if !consent::ec_consent_granted(&self.consent) {
+            log::debug!(
+                "EC generation skipped: consent not granted (jurisdiction={})",
+                self.consent.jurisdiction,
+            );
+            return Ok(());
+        }
+
+        let client_ip = self.client_ip.as_deref().ok_or_else(|| {
+            Report::new(TrustedServerError::Ec {
+                message: "Client IP required for EC generation but unavailable".to_string(),
+            })
+        })?;
+
+        let ec_id = generation::generate_ec_id(settings, client_ip)?;
+        log::trace!("Generated new EC ID: {ec_id}");
+        self.ec_value = Some(ec_id);
+        self.ec_generated = true;
+
+        Ok(())
+    }
+
+    /// Returns the EC ID value, if present (either from request or generated).
+    #[must_use]
+    pub fn ec_value(&self) -> Option<&str> {
+        self.ec_value.as_deref()
+    }
+
+    /// Returns whether the `ts-ec` cookie was present on the incoming request.
+    #[must_use]
+    pub fn cookie_was_present(&self) -> bool {
+        self.cookie_ec_value.is_some()
+    }
+
+    /// Returns whether an EC ID was found on the incoming request
+    /// (from header or cookie).
+    #[must_use]
+    pub fn ec_was_present(&self) -> bool {
+        self.ec_was_present
+    }
+
+    /// Returns whether a new EC ID was generated during this request.
+    #[must_use]
+    pub fn ec_generated(&self) -> bool {
+        self.ec_generated
+    }
+
+    /// Returns a reference to the consent context for this request.
+    #[must_use]
+    pub fn consent(&self) -> &ConsentContext {
+        &self.consent
+    }
+
+    /// Returns the normalized client IP, if available.
+    #[must_use]
+    pub fn client_ip(&self) -> Option<&str> {
+        self.client_ip.as_deref()
+    }
+
+    /// Returns whether EC creation is permitted by consent for this request.
+    #[must_use]
+    pub fn ec_allowed(&self) -> bool {
+        consent::ec_consent_granted(&self.consent)
+    }
+
+    /// Returns the existing EC cookie value for revocation handling.
+    ///
+    /// When consent is withdrawn, this value is needed to identify the
+    /// correct KV entry to tombstone. Returns `None` if no cookie was
+    /// present on the request. This always returns the cookie value,
+    /// even when the header took precedence for the active EC ID.
+    #[must_use]
+    pub fn existing_cookie_ec_id(&self) -> Option<&str> {
+        self.cookie_ec_value.as_deref()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_support::tests::create_test_settings;
+    use fastly::http::HeaderValue;
+
+    fn create_test_request(headers: &[(&str, &str)]) -> Request {
+        let mut req = Request::new("GET", "http://example.com");
+        for &(key, value) in headers {
+            req.set_header(
+                key,
+                HeaderValue::from_str(value).expect("should create valid header value"),
+            );
+        }
+        req
+    }
+
+    #[test]
+    fn read_from_request_with_header_ec() {
+        let settings = create_test_settings();
+        let req = create_test_request(&[("x-ts-ec", "header-ec-id")]);
+
+        let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
+
+        assert_eq!(ec.ec_value(), Some("header-ec-id"));
+        assert!(ec.ec_was_present(), "should detect EC from header");
+        assert!(!ec.cookie_was_present(), "should not detect cookie");
+        assert!(!ec.ec_generated(), "should not mark as generated");
+    }
+
+    #[test]
+    fn read_from_request_with_cookie_ec() {
+        let settings = create_test_settings();
+        let req = create_test_request(&[("cookie", "ts-ec=cookie-ec-id")]);
+
+        let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
+
+        assert_eq!(ec.ec_value(), Some("cookie-ec-id"));
+        assert!(ec.ec_was_present(), "should detect EC from cookie");
+        assert!(ec.cookie_was_present(), "should detect cookie");
+        assert!(!ec.ec_generated(), "should not mark as generated");
+    }
+
+    #[test]
+    fn read_from_request_header_takes_precedence_over_cookie() {
+        let settings = create_test_settings();
+        let req = create_test_request(&[("x-ts-ec", "header-id"), ("cookie", "ts-ec=cookie-id")]);
+
+        let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
+
+        assert_eq!(
+            ec.ec_value(),
+            Some("header-id"),
+            "should prefer header over cookie"
+        );
+        assert!(ec.cookie_was_present(), "should still detect cookie");
+    }
+
+    #[test]
+    fn read_from_request_no_ec() {
+        let settings = create_test_settings();
+        let req = create_test_request(&[]);
+
+        let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
+
+        assert!(ec.ec_value().is_none(), "should have no EC value");
+        assert!(!ec.ec_was_present(), "should not detect EC");
+        assert!(!ec.cookie_was_present(), "should not detect cookie");
+    }
+
+    #[test]
+    fn generate_if_needed_skips_when_ec_exists() {
+        let settings = create_test_settings();
+        let req = create_test_request(&[("x-ts-ec", "existing-id")]);
+
+        let mut ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
+        ec.generate_if_needed(&settings)
+            .expect("should not error when EC already exists");
+
+        assert_eq!(
+            ec.ec_value(),
+            Some("existing-id"),
+            "should keep existing EC"
+        );
+        assert!(!ec.ec_generated(), "should not mark as generated");
+    }
+
+    #[test]
+    fn existing_cookie_ec_id_returns_cookie_value() {
+        let settings = create_test_settings();
+
+        // With cookie present
+        let req = create_test_request(&[("cookie", "ts-ec=cookie-value")]);
+        let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
+        assert_eq!(
+            ec.existing_cookie_ec_id(),
+            Some("cookie-value"),
+            "should return cookie EC ID"
+        );
+
+        // With only header (no cookie)
+        let req = create_test_request(&[("x-ts-ec", "header-value")]);
+        let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
+        assert!(
+            ec.existing_cookie_ec_id().is_none(),
+            "should return None when EC came from header only"
+        );
+
+        // With both header and cookie — should return cookie value
+        let req = create_test_request(&[("x-ts-ec", "header-id"), ("cookie", "ts-ec=cookie-id")]);
+        let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
+        assert_eq!(
+            ec.ec_value(),
+            Some("header-id"),
+            "should use header as active EC"
+        );
+        assert_eq!(
+            ec.existing_cookie_ec_id(),
+            Some("cookie-id"),
+            "should return cookie value for revocation even when header takes precedence"
+        );
+    }
+}
diff --git a/crates/trusted-server-core/src/edge_cookie.rs b/crates/trusted-server-core/src/edge_cookie.rs
deleted file mode 100644
index 063c3fdd..00000000
--- a/crates/trusted-server-core/src/edge_cookie.rs
+++ /dev/null
@@ -1,376 +0,0 @@
-//! Edge Cookie (EC) ID generation using HMAC.
-//!
-//! This module provides functionality for generating privacy-preserving EC IDs
-//! based on the client IP address and a secret key.
-
-use std::net::IpAddr;
-
-use error_stack::{Report, ResultExt};
-use fastly::Request;
-use hmac::{Hmac, Mac};
-use rand::Rng;
-use sha2::Sha256;
-
-use crate::constants::{COOKIE_TS_EC, HEADER_X_TS_EC};
-use crate::cookies::{ec_id_has_only_allowed_chars, handle_request_cookies};
-use crate::error::TrustedServerError;
-use crate::settings::Settings;
-
-type HmacSha256 = Hmac<Sha256>;
-
-const ALPHANUMERIC_CHARSET: &[u8] =
-    b"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
-
-/// Normalizes an IP address for stable EC ID generation.
-///
-/// For IPv6 addresses, masks to /64 prefix to handle Privacy Extensions
-/// where devices rotate their interface identifier (lower 64 bits).
-/// IPv4 addresses are returned unchanged.
-fn normalize_ip(ip: IpAddr) -> String {
-    match ip {
-        IpAddr::V4(ipv4) => ipv4.to_string(),
-        IpAddr::V6(ipv6) => {
-            let segments = ipv6.segments();
-            // Keep only the first 4 segments (64 bits) for /64 prefix
-            format!(
-                "{:x}:{:x}:{:x}:{:x}::",
-                segments[0], segments[1], segments[2], segments[3]
-            )
-        }
-    }
-}
-
-/// Generates a random alphanumeric string of the specified length.
-fn generate_random_suffix(length: usize) -> String {
-    let mut rng = rand::thread_rng();
-    (0..length)
-        .map(|_| {
-            let idx = rng.gen_range(0..ALPHANUMERIC_CHARSET.len());
-            ALPHANUMERIC_CHARSET[idx] as char
-        })
-        .collect()
-}
-
-/// Generates a fresh EC ID based on client IP address.
-///
-/// Uses only the client IP (not user-agent or other headers) intentionally:
-/// EC IDs are meant to be simple, privacy-preserving identifiers — not
-/// high-entropy fingerprints. The random suffix provides per-cookie
-/// uniqueness for users behind the same NAT/proxy.
-///
-/// Creates an HMAC-SHA256-based ID using the configured secret key and
-/// the client IP address, then appends a random suffix for additional
-/// uniqueness. The resulting format is `{64hex}.{6alnum}`.
-///
-/// # Errors
-///
-/// - [`TrustedServerError::Ec`] if HMAC generation fails
-pub fn generate_ec_id(
-    settings: &Settings,
-    req: &Request,
-) -> Result<String, Report<TrustedServerError>> {
-    // Fallback to "unknown" when client IP is unavailable (e.g., local testing).
-    // All such requests share the same HMAC base; the random suffix provides uniqueness.
-    let client_ip = req
-        .get_client_ip_addr()
-        .map(normalize_ip)
-        .unwrap_or_else(|| "unknown".to_string());
-
-    log::trace!("Input for fresh EC ID: client_ip={}", client_ip);
-
-    let mut mac = HmacSha256::new_from_slice(settings.edge_cookie.secret_key.expose().as_bytes())
-        .change_context(TrustedServerError::Ec {
-        message: "Failed to create HMAC instance".to_string(),
-    })?;
-    mac.update(client_ip.as_bytes());
-    let hmac_hash = hex::encode(mac.finalize().into_bytes());
-
-    // Append random 6-character alphanumeric suffix for additional uniqueness
-    let random_suffix = generate_random_suffix(6);
-    let ec_id = format!("{hmac_hash}.{random_suffix}");
-
-    log::trace!("Generated fresh EC ID: {}", ec_id);
-
-    Ok(ec_id)
-}
-
-/// Gets an existing EC ID from the request.
-///
-/// Attempts to retrieve an existing EC ID from:
-/// 1. The `x-ts-ec` header
-/// 2. The `ts-ec` cookie
-///
-/// Returns `None` if neither source contains an EC ID.
-///
-/// # Errors
-///
-/// - [`TrustedServerError::InvalidHeaderValue`] if cookie parsing fails
-pub fn get_ec_id(req: &Request) -> Result<Option<String>, Report<TrustedServerError>> {
-    if let Some(ec_id) = req.get_header(HEADER_X_TS_EC).and_then(|h| h.to_str().ok()) {
-        if ec_id_has_only_allowed_chars(ec_id) {
-            log::trace!("Using existing EC ID from header: {}", ec_id);
-            return Ok(Some(ec_id.to_string()));
-        }
-        log::warn!("Rejected EC ID from x-ts-ec header with disallowed characters");
-    }
-
-    match handle_request_cookies(req)? {
-        Some(jar) => {
-            if let Some(cookie) = jar.get(COOKIE_TS_EC) {
-                let value = cookie.value();
-                if ec_id_has_only_allowed_chars(value) {
-                    log::trace!("Using existing EC ID from cookie: {}", value);
-                    return Ok(Some(value.to_string()));
-                }
-                log::warn!("Rejected EC ID from cookie with disallowed characters");
-            }
-        }
-        None => {
-            log::debug!("No cookie header found in request");
-        }
-    }
-
-    Ok(None)
-}
-
-/// Gets or creates an EC ID from the request.
-///
-/// Attempts to retrieve an existing EC ID from:
-/// 1. The `x-ts-ec` header
-/// 2. The `ts-ec` cookie
-///
-/// If neither exists, generates a new EC ID.
-///
-/// # Errors
-///
-/// Returns an error if ID generation fails.
-pub fn get_or_generate_ec_id(
-    settings: &Settings,
-    req: &Request,
-) -> Result<String, Report<TrustedServerError>> {
-    if let Some(id) = get_ec_id(req)? {
-        return Ok(id);
-    }
-
-    // If no existing EC ID found, generate a fresh one
-    let ec_id = generate_ec_id(settings, req)?;
-    log::trace!("No existing EC ID, generated: {}", ec_id);
-    Ok(ec_id)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use fastly::http::{HeaderName, HeaderValue};
-    use std::net::{Ipv4Addr, Ipv6Addr};
-
-    use crate::test_support::tests::create_test_settings;
-
-    #[test]
-    fn test_normalize_ip_ipv4_unchanged() {
-        let ipv4 = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 100));
-        assert_eq!(normalize_ip(ipv4), "192.168.1.100");
-    }
-
-    #[test]
-    fn test_normalize_ip_ipv6_masks_to_64() {
-        // Full IPv6 address with interface identifier
-        let ipv6 = IpAddr::V6(Ipv6Addr::new(
-            0x2001, 0x0db8, 0x85a3, 0x0000, 0x8a2e, 0x0370, 0x7334, 0x1234,
-        ));
-        assert_eq!(normalize_ip(ipv6), "2001:db8:85a3:0::");
-    }
-
-    #[test]
-    fn test_normalize_ip_ipv6_different_suffix_same_prefix() {
-        // Two IPv6 addresses with same /64 prefix but different interface identifiers
-        // (simulating Privacy Extensions rotation)
-        let ipv6_a = IpAddr::V6(Ipv6Addr::new(
-            0x2001, 0x0db8, 0xabcd, 0x0001, 0x1111, 0x2222, 0x3333, 0x4444,
-        ));
-        let ipv6_b = IpAddr::V6(Ipv6Addr::new(
-            0x2001, 0x0db8, 0xabcd, 0x0001, 0xaaaa, 0xbbbb, 0xcccc, 0xdddd,
-        ));
-        // Both should normalize to the same /64 prefix
-        assert_eq!(normalize_ip(ipv6_a), normalize_ip(ipv6_b));
-        assert_eq!(normalize_ip(ipv6_a), "2001:db8:abcd:1::");
-    }
-
-    fn create_test_request(headers: Vec<(HeaderName, &str)>) -> Request {
-        let mut req = Request::new("GET", "http://example.com");
-        for (key, value) in headers {
-            req.set_header(
-                key,
-                HeaderValue::from_str(value).expect("should create valid header value"),
-            );
-        }
-
-        req
-    }
-
-    fn is_ec_id_format(value: &str) -> bool {
-        let mut parts = value.split('.');
-        let hmac_part = match parts.next() {
-            Some(part) => part,
-            None => return false,
-        };
-        let suffix_part = match parts.next() {
-            Some(part) => part,
-            None => return false,
-        };
-        if parts.next().is_some() {
-            return false;
-        }
-        if hmac_part.len() != 64 || suffix_part.len() != 6 {
-            return false;
-        }
-        if !hmac_part.chars().all(|c| c.is_ascii_hexdigit()) {
-            return false;
-        }
-        if !suffix_part.chars().all(|c| c.is_ascii_alphanumeric()) {
-            return false;
-        }
-        true
-    }
-
-    #[test]
-    fn test_generate_ec_id() {
-        let settings: Settings = create_test_settings();
-        let req = create_test_request(vec![]);
-
-        let ec_id = generate_ec_id(&settings, &req).expect("should generate EC ID");
-        log::debug!("Generated EC ID: {}", ec_id);
-        assert!(
-            is_ec_id_format(&ec_id),
-            "should match EC ID format: {{64hex}}.{{6alnum}}"
-        );
-    }
-
-    #[test]
-    fn test_is_ec_id_format_accepts_valid_value() {
-        let value = format!("{}.{}", "a".repeat(64), "Ab12z9");
-        assert!(
-            is_ec_id_format(&value),
-            "should accept a valid EC ID format"
-        );
-    }
-
-    #[test]
-    fn test_is_ec_id_format_rejects_invalid_values() {
-        let missing_suffix = "a".repeat(64);
-        assert!(
-            !is_ec_id_format(&missing_suffix),
-            "should reject missing suffix"
-        );
-
-        let invalid_hex = format!("{}.{}", "a".repeat(63) + "g", "Ab12z9");
-        assert!(
-            !is_ec_id_format(&invalid_hex),
-            "should reject non-hex HMAC content"
-        );
-
-        let invalid_suffix = format!("{}.{}", "a".repeat(64), "ab-129");
-        assert!(
-            !is_ec_id_format(&invalid_suffix),
-            "should reject non-alphanumeric suffix"
-        );
-
-        let extra_segment = format!("{}.{}.{}", "a".repeat(64), "Ab12z9", "zz");
-        assert!(
-            !is_ec_id_format(&extra_segment),
-            "should reject extra segments"
-        );
-    }
-
-    #[test]
-    fn test_get_ec_id_with_header() {
-        let settings = create_test_settings();
-        let req = create_test_request(vec![(HEADER_X_TS_EC, "existing_ec_id")]);
-
-        let ec_id = get_ec_id(&req).expect("should get EC ID");
-        assert_eq!(ec_id, Some("existing_ec_id".to_string()));
-
-        let ec_id = get_or_generate_ec_id(&settings, &req).expect("should reuse header EC ID");
-        assert_eq!(ec_id, "existing_ec_id");
-    }
-
-    #[test]
-    fn test_get_ec_id_with_cookie() {
-        let settings = create_test_settings();
-        let req = create_test_request(vec![(
-            fastly::http::header::COOKIE,
-            &format!("{}=existing_cookie_id", COOKIE_TS_EC),
-        )]);
-
-        let ec_id = get_ec_id(&req).expect("should get EC ID");
-        assert_eq!(ec_id, Some("existing_cookie_id".to_string()));
-
-        let ec_id = get_or_generate_ec_id(&settings, &req).expect("should reuse cookie EC ID");
-        assert_eq!(ec_id, "existing_cookie_id");
-    }
-
-    #[test]
-    fn test_get_ec_id_none() {
-        let req = create_test_request(vec![]);
-        let ec_id = get_ec_id(&req).expect("should handle missing ID");
-        assert!(ec_id.is_none());
-    }
-
-    #[test]
-    fn test_get_or_generate_ec_id_generate_new() {
-        let settings = create_test_settings();
-        let req = create_test_request(vec![]);
-
-        let ec_id = get_or_generate_ec_id(&settings, &req).expect("should get or generate EC ID");
-        assert!(!ec_id.is_empty());
-    }
-
-    #[test]
-    fn test_get_ec_id_rejects_invalid_header_and_falls_back_to_cookie() {
-        let req = create_test_request(vec![
-            (HEADER_X_TS_EC, "evil;injected"),
-            (
-                fastly::http::header::COOKIE,
-                &format!("{}=valid_cookie_id", COOKIE_TS_EC),
-            ),
-        ]);
-
-        let ec_id = get_ec_id(&req).expect("should handle invalid header gracefully");
-        assert_eq!(
-            ec_id,
-            Some("valid_cookie_id".to_string()),
-            "should reject tampered header and fall back to valid cookie"
-        );
-    }
-
-    #[test]
-    fn test_get_or_generate_ec_id_replaces_invalid_header() {
-        let settings = create_test_settings();
-        let req = create_test_request(vec![(HEADER_X_TS_EC, "evil;injected")]);
-
-        let ec_id = get_or_generate_ec_id(&settings, &req)
-            .expect("should generate fresh ID on invalid header");
-        assert_ne!(
-            ec_id, "evil;injected",
-            "should not use tampered header value"
-        );
-        assert!(
-            is_ec_id_format(&ec_id),
-            "should generate a valid EC ID format when header is rejected"
-        );
-    }
-
-    #[test]
-    fn test_get_ec_id_rejects_invalid_cookie() {
-        let req = create_test_request(vec![(
-            fastly::http::header::COOKIE,
-            &format!("{}=bad<script>value", COOKIE_TS_EC),
-        )]);
-
-        let ec_id = get_ec_id(&req).expect("should handle invalid cookie gracefully");
-        assert!(
-            ec_id.is_none(),
-            "should reject cookie with disallowed characters"
-        );
-    }
-}
diff --git a/crates/trusted-server-core/src/integrations/adserver_mock.rs b/crates/trusted-server-core/src/integrations/adserver_mock.rs
index f4ce745d..cfbece21 100644
--- a/crates/trusted-server-core/src/integrations/adserver_mock.rs
+++ b/crates/trusted-server-core/src/integrations/adserver_mock.rs
@@ -466,7 +466,6 @@ mod tests {
             },
             user: UserInfo {
                 id: "user-123".to_string(),
-                fresh_id: "fresh-456".to_string(),
                 consent: None,
             },
             device: Some(DeviceInfo {
@@ -640,7 +639,6 @@ mod tests {
             },
             user: UserInfo {
                 id: "user-1".to_string(),
-                fresh_id: "fresh-1".to_string(),
                 consent: None,
             },
             device: None,
diff --git a/crates/trusted-server-core/src/integrations/aps.rs b/crates/trusted-server-core/src/integrations/aps.rs
index af66dd06..b18cc454 100644
--- a/crates/trusted-server-core/src/integrations/aps.rs
+++ b/crates/trusted-server-core/src/integrations/aps.rs
@@ -678,7 +678,6 @@ mod tests {
             },
             user: UserInfo {
                 id: "user-123".to_string(),
-                fresh_id: "fresh-456".to_string(),
                 consent: None,
             },
             device: Some(DeviceInfo {
diff --git a/crates/trusted-server-core/src/integrations/google_tag_manager.rs b/crates/trusted-server-core/src/integrations/google_tag_manager.rs
index 64dc6cd5..301d0eca 100644
--- a/crates/trusted-server-core/src/integrations/google_tag_manager.rs
+++ b/crates/trusted-server-core/src/integrations/google_tag_manager.rs
@@ -1315,8 +1315,8 @@ cookie_domain = ".test-publisher.com"
 origin_url = "https://origin.test-publisher.com"
 proxy_secret = "test-secret"
 
-[edge_cookie]
-secret_key = "test-secret-key"
+[ec]
+passphrase = "test-secret-key"
 
 [integrations.google_tag_manager]
 enabled = true
@@ -1348,8 +1348,8 @@ cookie_domain = ".test-publisher.com"
 origin_url = "https://origin.test-publisher.com"
 proxy_secret = "test-secret"
 
-[edge_cookie]
-secret_key = "test-secret-key"
+[ec]
+passphrase = "test-secret-key"
 
 [integrations.google_tag_manager]
 container_id = "GTM-DEFAULT"
diff --git a/crates/trusted-server-core/src/integrations/prebid.rs b/crates/trusted-server-core/src/integrations/prebid.rs
index 1ced7059..8acca812 100644
--- a/crates/trusted-server-core/src/integrations/prebid.rs
+++ b/crates/trusted-server-core/src/integrations/prebid.rs
@@ -618,7 +618,6 @@ impl PrebidAuctionProvider {
                 // EIDs will be populated by identity providers; consent gating
                 // is applied via `gate_eids_by_consent` before they are set here.
                 eids: None,
-                ec_fresh: Some(request.user.fresh_id.clone()),
             }
             .to_ext(),
             ..Default::default()
@@ -1269,7 +1268,7 @@ mod tests {
             },
             user: UserInfo {
                 id: "user-123".to_string(),
-                fresh_id: "fresh-456".to_string(),
+
                 consent: None,
             },
             device: None,
@@ -1316,8 +1315,8 @@ cookie_domain = ".test-publisher.com"
 origin_url = "https://origin.test-publisher.com"
 proxy_secret = "test-secret"
 
-[edge_cookie]
-secret_key = "test-secret-key"
+[ec]
+passphrase = "test-secret-key"
 "#;
 
     /// Parse a TOML string containing only the `[integrations.prebid]` section
@@ -2629,7 +2628,7 @@ server_url = "https://prebid.example"
             },
             user: UserInfo {
                 id: "synth-123".to_string(),
-                fresh_id: "fresh-456".to_string(),
+
                 consent: None,
             },
             device: Some(DeviceInfo {
diff --git a/crates/trusted-server-core/src/integrations/registry.rs b/crates/trusted-server-core/src/integrations/registry.rs
index 1e03937a..cd82c5ef 100644
--- a/crates/trusted-server-core/src/integrations/registry.rs
+++ b/crates/trusted-server-core/src/integrations/registry.rs
@@ -10,7 +10,7 @@ use matchit::Router;
 
 use crate::constants::HEADER_X_TS_EC;
 use crate::cookies::set_ec_cookie;
-use crate::edge_cookie::get_or_generate_ec_id;
+use crate::ec::get_or_generate_ec_id;
 use crate::error::TrustedServerError;
 use crate::settings::Settings;
 
diff --git a/crates/trusted-server-core/src/integrations/testlight.rs b/crates/trusted-server-core/src/integrations/testlight.rs
index 574414d3..e63baea3 100644
--- a/crates/trusted-server-core/src/integrations/testlight.rs
+++ b/crates/trusted-server-core/src/integrations/testlight.rs
@@ -8,7 +8,7 @@ use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value};
 use validator::Validate;
 
-use crate::edge_cookie::get_ec_id;
+use crate::ec::get_ec_id;
 use crate::error::TrustedServerError;
 use crate::integrations::{
     AttributeRewriteAction, IntegrationAttributeContext, IntegrationAttributeRewriter,
diff --git a/crates/trusted-server-core/src/lib.rs b/crates/trusted-server-core/src/lib.rs
index 44fa108d..1dc4c912 100644
--- a/crates/trusted-server-core/src/lib.rs
+++ b/crates/trusted-server-core/src/lib.rs
@@ -16,7 +16,7 @@
 //! - [`privacy`]: Privacy utilities and helpers
 //! - [`settings`]: Configuration management and validation
 //! - [`streaming_replacer`]: Streaming URL replacement for large responses
-//! - [`edge_cookie`]: Edge Cookie (EC) ID generation using HMAC
+//! - [`ec`]: Edge Cookie (EC) identity subsystem — ID generation, consent gating, lifecycle
 //! - [`test_support`]: Testing utilities and mocks
 //! - [`why`]: Debugging and introspection utilities
 
@@ -40,7 +40,7 @@ pub mod consent_config;
 pub mod constants;
 pub mod cookies;
 pub mod creative;
-pub mod edge_cookie;
+pub mod ec;
 pub mod error;
 pub mod geo;
 pub(crate) mod host_rewrite;
diff --git a/crates/trusted-server-core/src/openrtb.rs b/crates/trusted-server-core/src/openrtb.rs
index 3c9be932..37c3d675 100644
--- a/crates/trusted-server-core/src/openrtb.rs
+++ b/crates/trusted-server-core/src/openrtb.rs
@@ -49,12 +49,6 @@ pub struct UserExt {
     /// Gated by TCF Purpose 1 (storage) and Purpose 4 (personalized ads).
     #[serde(skip_serializing_if = "Option::is_none")]
     pub eids: Option<Vec<Eid>>,
-    /// Whether this EC ID was freshly generated for this request.
-    ///
-    /// **Breaking change:** this wire field was previously named `synthetic_fresh`.
-    /// Downstream PBS modules or analytics reading the old name must be updated.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub ec_fresh: Option<String>,
 }
 
 impl ToExt for UserExt {}
@@ -336,7 +330,6 @@ mod tests {
                     consented_providers: Some("2~2628.2316~dv.".to_string()),
                 }),
                 eids: None,
-                ec_fresh: None,
             }
             .to_ext(),
             ..Default::default()
@@ -397,24 +390,4 @@ mod tests {
             "ext should be omitted when None"
         );
     }
-
-    #[test]
-    fn user_ext_serializes_ec_fresh_not_synthetic_fresh() {
-        let ext = UserExt {
-            consent: None,
-            consented_providers_settings: None,
-            eids: None,
-            ec_fresh: Some("true".to_string()),
-        };
-
-        let serialized = serde_json::to_value(&ext).expect("should serialize UserExt");
-        assert_eq!(
-            serialized["ec_fresh"], "true",
-            "ec_fresh should be present in serialized output"
-        );
-        assert!(
-            serialized.get("synthetic_fresh").is_none(),
-            "synthetic_fresh should not appear — field was renamed to ec_fresh"
-        );
-    }
 }
diff --git a/crates/trusted-server-core/src/proxy.rs b/crates/trusted-server-core/src/proxy.rs
index c9efd6ce..c85298c1 100644
--- a/crates/trusted-server-core/src/proxy.rs
+++ b/crates/trusted-server-core/src/proxy.rs
@@ -10,7 +10,7 @@ use crate::constants::{
     HEADER_USER_AGENT, HEADER_X_FORWARDED_FOR,
 };
 use crate::creative::{CreativeCssProcessor, CreativeHtmlProcessor};
-use crate::edge_cookie::get_ec_id;
+use crate::ec::get_ec_id;
 use crate::error::TrustedServerError;
 use crate::settings::Settings;
 use crate::streaming_processor::{Compression, PipelineConfig, StreamProcessor, StreamingPipeline};
diff --git a/crates/trusted-server-core/src/publisher.rs b/crates/trusted-server-core/src/publisher.rs
index a642c60f..2e2568f6 100644
--- a/crates/trusted-server-core/src/publisher.rs
+++ b/crates/trusted-server-core/src/publisher.rs
@@ -6,7 +6,7 @@ use crate::backend::BackendConfig;
 use crate::consent::{allows_ec_creation, build_consent_context, ConsentPipelineInput};
 use crate::constants::{COOKIE_TS_EC, HEADER_X_COMPRESS_HINT, HEADER_X_TS_EC};
 use crate::cookies::{expire_ec_cookie, handle_request_cookies, set_ec_cookie};
-use crate::edge_cookie::get_or_generate_ec_id;
+use crate::ec::get_or_generate_ec_id;
 use crate::error::TrustedServerError;
 use crate::http_util::{serve_static_with_etag, RequestInfo};
 use crate::integrations::IntegrationRegistry;
@@ -348,7 +348,7 @@ pub fn handle_publisher_request(
             .map(|_| services.kv_store()),
     });
     let ec_allowed = allows_ec_creation(&consent_context);
-    log::trace!("Proxy EC ID: {}, ec_allowed: {}", ec_id, ec_allowed);
+    log::debug!("Proxy EC ID: {}, ec_allowed: {}", ec_id, ec_allowed,);
 
     let backend_name = BackendConfig::from_url(
         &settings.publisher.origin_url,
diff --git a/crates/trusted-server-core/src/settings.rs b/crates/trusted-server-core/src/settings.rs
index 78549262..9b19e1c2 100644
--- a/crates/trusted-server-core/src/settings.rs
+++ b/crates/trusted-server-core/src/settings.rs
@@ -58,6 +58,16 @@ impl Publisher {
     /// };
     /// assert_eq!(publisher.origin_host(), "origin.example.com:8080");
     /// ```
+    /// Returns the domain to use for the EC `Set-Cookie` header.
+    ///
+    /// Per spec §5.2, the EC cookie domain is `.{publisher.domain}` so
+    /// that the cookie is available on all subdomains of the publisher's
+    /// apex domain.
+    #[must_use]
+    pub fn ec_cookie_domain(&self) -> String {
+        format!(".{}", self.domain)
+    }
+
     #[allow(dead_code)]
     #[must_use]
     pub fn origin_host(&self) -> String {
@@ -203,35 +213,49 @@ impl DerefMut for IntegrationSettings {
     }
 }
 
-/// Edge Cookie configuration.
+/// Edge Cookie (EC) configuration.
+///
+/// Mapped from the `[ec]` TOML section. Controls EC identity generation,
+/// KV store names, and partner registry.
 #[allow(unused)]
 #[derive(Debug, Default, Clone, Deserialize, Serialize, Validate)]
-pub struct EdgeCookie {
-    #[validate(custom(function = EdgeCookie::validate_secret_key))]
-    pub secret_key: Redacted<String>,
+pub struct Ec {
+    /// Publisher passphrase used as HMAC key for EC generation.
+    #[validate(custom(function = Ec::validate_passphrase))]
+    pub passphrase: Redacted<String>,
+
+    /// Fastly KV store name for the EC identity graph.
+    /// Required for Stories 3+ (KV identity graph).
+    #[serde(default)]
+    pub ec_store: Option<String>,
+
+    /// Fastly KV store name for the partner registry.
+    /// Required for Story 4+ (partner registry).
+    #[serde(default)]
+    pub partner_store: Option<String>,
 }
 
-impl EdgeCookie {
+impl Ec {
     /// Known placeholder values that must not be used in production.
-    pub const SECRET_KEY_PLACEHOLDERS: &[&str] = &["secret-key", "secret_key", "trusted-server"];
+    pub const PASSPHRASE_PLACEHOLDERS: &[&str] = &["secret-key", "secret_key", "trusted-server"];
 
-    /// Returns `true` if `secret_key` matches a known placeholder value
+    /// Returns `true` if `passphrase` matches a known placeholder value
     /// (case-insensitive).
     #[must_use]
-    pub fn is_placeholder_secret_key(secret_key: &str) -> bool {
-        Self::SECRET_KEY_PLACEHOLDERS
+    pub fn is_placeholder_passphrase(passphrase: &str) -> bool {
+        Self::PASSPHRASE_PLACEHOLDERS
             .iter()
-            .any(|p| p.eq_ignore_ascii_case(secret_key))
+            .any(|p| p.eq_ignore_ascii_case(passphrase))
     }
 
-    /// Validates that the secret key is not empty.
+    /// Validates that the passphrase is not empty.
     ///
     /// # Errors
     ///
-    /// Returns a validation error if the secret key is empty.
-    pub fn validate_secret_key(secret_key: &Redacted<String>) -> Result<(), ValidationError> {
-        if secret_key.expose().is_empty() {
-            return Err(ValidationError::new("empty_secret_key"));
+    /// Returns a validation error if the passphrase is empty.
+    pub fn validate_passphrase(passphrase: &Redacted<String>) -> Result<(), ValidationError> {
+        if passphrase.expose().is_empty() {
+            return Err(ValidationError::new("empty_passphrase"));
         }
         Ok(())
     }
@@ -405,7 +429,7 @@ pub struct Settings {
     pub publisher: Publisher,
     #[serde(default)]
     #[validate(nested)]
-    pub edge_cookie: EdgeCookie,
+    pub ec: Ec,
     #[serde(default)]
     pub integrations: IntegrationSettings,
     #[serde(default, deserialize_with = "vec_from_seq_or_map")]
@@ -498,10 +522,16 @@ impl Settings {
     ///
     /// # Errors
     ///
-    /// Returns a configuration error if any cached runtime artifact cannot be prepared.
-    pub fn prepare_runtime(&self) -> Result<(), Report<TrustedServerError>> {
-        for handler in &self.handlers {
-            handler.prepare_runtime()?;
+    /// Returns [`TrustedServerError::InsecureDefault`] when one or more secret
+    /// fields still contain a placeholder value.
+    pub fn reject_placeholder_secrets(&self) -> Result<(), Report<TrustedServerError>> {
+        let mut insecure_fields: Vec<&str> = Vec::new();
+
+        if Ec::is_placeholder_passphrase(self.ec.passphrase.expose()) {
+            insecure_fields.push("ec.passphrase");
+        }
+        if Publisher::is_placeholder_proxy_secret(self.publisher.proxy_secret.expose()) {
+            insecure_fields.push("publisher.proxy_secret");
         }
 
         Ok(())
@@ -806,7 +836,7 @@ mod tests {
             settings.publisher.origin_url,
             "https://origin.test-publisher.com"
         );
-        assert_eq!(settings.edge_cookie.secret_key.expose(), "test-secret-key");
+        assert_eq!(settings.ec.passphrase.expose(), "test-secret-key");
 
         settings.validate().expect("Failed to validate settings");
     }
@@ -853,32 +883,32 @@ mod tests {
     }
 
     #[test]
-    fn is_placeholder_secret_key_rejects_all_known_placeholders() {
-        for placeholder in EdgeCookie::SECRET_KEY_PLACEHOLDERS {
+    fn is_placeholder_passphrase_rejects_all_known_placeholders() {
+        for placeholder in Ec::PASSPHRASE_PLACEHOLDERS {
             assert!(
-                EdgeCookie::is_placeholder_secret_key(placeholder),
-                "should detect placeholder secret_key '{placeholder}'"
+                Ec::is_placeholder_passphrase(placeholder),
+                "should detect placeholder passphrase '{placeholder}'"
             );
         }
     }
 
     #[test]
-    fn is_placeholder_secret_key_is_case_insensitive() {
+    fn is_placeholder_passphrase_is_case_insensitive() {
         assert!(
-            EdgeCookie::is_placeholder_secret_key("SECRET-KEY"),
-            "should detect case-insensitive placeholder secret_key"
+            Ec::is_placeholder_passphrase("SECRET-KEY"),
+            "should detect case-insensitive placeholder passphrase"
         );
         assert!(
-            EdgeCookie::is_placeholder_secret_key("Trusted-Server"),
-            "should detect mixed-case placeholder secret_key"
+            Ec::is_placeholder_passphrase("Trusted-Server"),
+            "should detect mixed-case placeholder passphrase"
         );
     }
 
     #[test]
-    fn is_placeholder_secret_key_accepts_non_placeholder() {
+    fn is_placeholder_passphrase_accepts_non_placeholder() {
         assert!(
-            !EdgeCookie::is_placeholder_secret_key("test-secret-key"),
-            "should accept non-placeholder secret_key"
+            !Ec::is_placeholder_passphrase("test-secret-key"),
+            "should accept non-placeholder passphrase"
         );
     }
 
@@ -1815,8 +1845,8 @@ mod tests {
             origin_url = "https://origin.test-publisher.com"
             proxy_secret = "unit-test-proxy-secret"
 
-            [edge_cookie]
-            secret_key = "test-secret-key"
+            [ec]
+            passphrase = "test-secret-key"
 
             [request_signing]
             config_store_id = "test-config-store-id"
diff --git a/crates/trusted-server-core/src/settings_data.rs b/crates/trusted-server-core/src/settings_data.rs
index 7e89ab65..39b06650 100644
--- a/crates/trusted-server-core/src/settings_data.rs
+++ b/crates/trusted-server-core/src/settings_data.rs
@@ -47,16 +47,110 @@ pub fn get_settings() -> Result<Settings, Report<TrustedServerError>> {
 
 #[cfg(test)]
 mod tests {
-    use super::*;
+    use crate::error::TrustedServerError;
+    use crate::settings::Settings;
+    use crate::test_support::tests::crate_test_settings_str;
+
+    /// Builds a TOML string with the given secret values swapped in.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the replacement patterns no longer match the test TOML,
+    /// which would cause the substitution to silently no-op.
+    fn toml_with_secrets(passphrase: &str, proxy_secret: &str) -> String {
+        let original = crate_test_settings_str();
+        let after_passphrase = original.replace(
+            r#"passphrase = "test-secret-key""#,
+            &format!(r#"passphrase = "{passphrase}""#),
+        );
+        assert_ne!(
+            after_passphrase, original,
+            "should have replaced passphrase value"
+        );
+        let result = after_passphrase.replace(
+            r#"proxy_secret = "unit-test-proxy-secret""#,
+            &format!(r#"proxy_secret = "{proxy_secret}""#),
+        );
+        assert_ne!(
+            result, after_passphrase,
+            "should have replaced proxy_secret value"
+        );
+        result
+    }
 
     #[test]
-    fn get_settings_loads_embedded_toml_successfully() {
-        // The embedded TOML contains placeholder secrets (e.g. "trusted-server",
-        // "change-me-proxy-secret"). This is expected — production builds override
-        // them via TRUSTED_SERVER__* env vars at build time.
-        let settings = get_settings().expect("should load settings from embedded TOML");
-        assert!(!settings.publisher.domain.is_empty());
-        assert!(!settings.publisher.cookie_domain.is_empty());
-        assert!(!settings.publisher.origin_url.is_empty());
+    fn rejects_placeholder_secret_key() {
+        let toml = toml_with_secrets("secret-key", "real-proxy-secret");
+        let settings = Settings::from_toml(&toml).expect("should parse TOML");
+        let err = settings
+            .reject_placeholder_secrets()
+            .expect_err("should reject placeholder secret_key");
+        let root = err.current_context();
+        assert!(
+            matches!(root, TrustedServerError::InsecureDefault { field } if field.contains("ec.passphrase")),
+            "error should mention ec.passphrase, got: {root}"
+        );
+    }
+
+    #[test]
+    fn rejects_placeholder_proxy_secret() {
+        let toml = toml_with_secrets("real-secret-key", "change-me-proxy-secret");
+        let settings = Settings::from_toml(&toml).expect("should parse TOML");
+        let err = settings
+            .reject_placeholder_secrets()
+            .expect_err("should reject placeholder proxy_secret");
+        let root = err.current_context();
+        assert!(
+            matches!(root, TrustedServerError::InsecureDefault { field } if field.contains("publisher.proxy_secret")),
+            "error should mention publisher.proxy_secret, got: {root}"
+        );
+    }
+
+    #[test]
+    fn rejects_both_placeholders_in_single_error() {
+        let toml = toml_with_secrets("secret_key", "change-me-proxy-secret");
+        let settings = Settings::from_toml(&toml).expect("should parse TOML");
+        let err = settings
+            .reject_placeholder_secrets()
+            .expect_err("should reject both placeholder secrets");
+        let root = err.current_context();
+        match root {
+            TrustedServerError::InsecureDefault { field } => {
+                assert!(
+                    field.contains("ec.passphrase"),
+                    "error should mention ec.passphrase, got: {field}"
+                );
+                assert!(
+                    field.contains("publisher.proxy_secret"),
+                    "error should mention publisher.proxy_secret, got: {field}"
+                );
+            }
+            other => panic!("expected InsecureDefault, got: {other}"),
+        }
+    }
+
+    #[test]
+    fn accepts_non_placeholder_secrets() {
+        let toml = toml_with_secrets("production-secret-key", "production-proxy-secret");
+        let settings = Settings::from_toml(&toml).expect("should parse TOML");
+        settings
+            .reject_placeholder_secrets()
+            .expect("non-placeholder secrets should pass validation");
+    }
+
+    /// Smoke-test the full `get_settings()` pipeline (embedded bytes → UTF-8 →
+    /// parse → validate → placeholder check).  The build-time TOML ships with
+    /// placeholder secrets, so the expected outcome is an [`InsecureDefault`]
+    /// error — but reaching that error proves every earlier stage succeeded.
+    #[test]
+    fn get_settings_rejects_embedded_placeholder_secrets() {
+        let err = super::get_settings().expect_err("should reject embedded placeholder secrets");
+        assert!(
+            matches!(
+                err.current_context(),
+                TrustedServerError::InsecureDefault { .. }
+            ),
+            "should fail with InsecureDefault, got: {err}"
+        );
     }
 }
diff --git a/crates/trusted-server-core/src/test_support.rs b/crates/trusted-server-core/src/test_support.rs
index 8fdfaa85..2fe0534b 100644
--- a/crates/trusted-server-core/src/test_support.rs
+++ b/crates/trusted-server-core/src/test_support.rs
@@ -34,8 +34,8 @@ pub mod tests {
             enabled = false
             rewrite_attributes = ["href", "link", "url"]
 
-            [edge_cookie]
-            secret_key = "test-secret-key"
+            [ec]
+            passphrase = "test-secret-key"
             [request_signing]
             config_store_id = "test-config-store-id"
             secret_store_id = "test-secret-store-id"
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index 029163bb..e5d5ead5 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -23,8 +23,8 @@ cookie_domain = ".publisher.com"
 origin_url = "https://origin.publisher.com"
 proxy_secret = "your-secure-secret-here"
 
-[edge_cookie]
-secret_key = "your-hmac-secret"
+[ec]
+passphrase = "your-hmac-secret"
 ```
 
 ### Environment Variable Overrides
@@ -60,7 +60,7 @@ openssl rand -base64 32
 | Section             | Purpose                                      |
 | ------------------- | -------------------------------------------- |
 | `[publisher]`       | Domain, origin, proxy settings               |
-| `[edge_cookie]`     | Edge Cookie (EC) ID generation               |
+| `[ec]`              | Edge Cookie (EC) ID generation               |
 | `[proxy]`           | Proxy SSRF allowlist                         |
 | `[request_signing]` | Ed25519 request signing                      |
 | `[auction]`         | Auction orchestration                        |
@@ -75,8 +75,8 @@ cookie_domain = ".publisher.com"
 origin_url = "https://origin.publisher.com"
 proxy_secret = "change-me-to-secure-value"
 
-[edge_cookie]
-secret_key = "your-hmac-secret-key"
+[ec]
+passphrase = "your-hmac-secret-key"
 
 [request_signing]
 enabled = true
@@ -155,17 +155,20 @@ Core publisher settings for domain, origin, and proxy configuration.
 
 | Field           | Type   | Required | Description                                             |
 | --------------- | ------ | -------- | ------------------------------------------------------- |
-| `domain`        | String | Yes      | Publisher's domain name                                 |
-| `cookie_domain` | String | Yes      | Domain for setting cookies (typically with leading dot) |
+| `domain`        | String | Yes      | Publisher's apex domain name                            |
+| `cookie_domain` | String | Yes      | Domain for non-EC cookies (typically with leading dot)  |
 | `origin_url`    | String | Yes      | Full URL of publisher origin server                     |
 | `proxy_secret`  | String | Yes      | Secret key for encrypting/signing proxy URLs            |
 
+> **Note:** EC cookies (`ts-ec`) derive their domain automatically as `.{domain}` and
+> do not use `cookie_domain`. The `cookie_domain` field is used by other cookie helpers.
+
 **Example**:
 
 ```toml
 [publisher]
 domain = "publisher.com"
-cookie_domain = ".publisher.com"  # Includes subdomains
+cookie_domain = ".publisher.com"
 origin_url = "https://origin.publisher.com"
 proxy_secret = "change-me-to-secure-random-value"
 ```
@@ -199,12 +202,12 @@ TRUSTED_SERVER__PUBLISHER__PROXY_SECRET=your-secret-here
 
 #### `cookie_domain`
 
-**Purpose**: Domain scope for EC cookies.
+**Purpose**: Domain scope for non-EC cookies.
 
 **Usage**:
 
-- Set on `ts-ec` cookie
-- Controls cookie sharing across subdomains
+- Used by non-EC cookie helpers for domain scoping
+- EC cookies (`ts-ec`) use a separate computed domain derived from `domain`
 
 **Format**: Domain with optional leading dot
 
@@ -265,30 +268,36 @@ Changing `proxy_secret` invalidates all existing signed URLs. Plan rotations car
 
 Settings for generating privacy-preserving Edge Cookie identifiers.
 
-### `[edge_cookie]`
+### `[ec]`
 
-| Field        | Type   | Required | Description                   |
-| ------------ | ------ | -------- | ----------------------------- |
-| `secret_key` | String | Yes      | HMAC secret for ID generation |
+| Field           | Type            | Required | Description                                      |
+| --------------- | --------------- | -------- | ------------------------------------------------ |
+| `passphrase`    | String          | Yes      | Publisher passphrase used as HMAC key             |
+| `ec_store`      | String or null  | No       | Fastly KV store name for EC identity graph        |
+| `partner_store` | String or null  | No       | Fastly KV store name for partner registry         |
 
 **Example**:
 
 ```toml
-[edge_cookie]
-secret_key = "your-secure-hmac-secret"
+[ec]
+passphrase = "your-secure-hmac-secret"
+ec_store = "ec_identity_store"
+partner_store = "ec_partner_store"
 ```
 
 **Environment Override**:
 
 ```bash
-TRUSTED_SERVER__EDGE_COOKIE__SECRET_KEY=your-secret
+TRUSTED_SERVER__EC__PASSPHRASE=your-secret
+TRUSTED_SERVER__EC__EC_STORE=ec_identity_store
+TRUSTED_SERVER__EC__PARTNER_STORE=ec_partner_store
 ```
 
 ### Field Details
 
-#### `secret_key`
+#### `passphrase`
 
-**Purpose**: HMAC secret for EC ID base generation.
+**Purpose**: Publisher passphrase used as HMAC key for EC ID generation.
 
 **Security**:
 
@@ -886,8 +895,8 @@ Configuration is validated at startup:
 
 **EC Validation**:
 
-- `secret_key` ≥ 1 character
-- `secret_key` ≠ known placeholders (`"secret-key"`, `"secret_key"`, `"trusted-server"` — case-insensitive)
+- `passphrase` ≥ 1 character
+- `passphrase` ≠ known placeholders (`"secret-key"`, `"secret_key"`, `"trusted-server"` — case-insensitive)
 
 **Handler Validation**:
 
@@ -998,7 +1007,7 @@ trusted-server.dev.toml      # Development overrides
 
 **"Configuration field '...' is set to a known placeholder value"**:
 
-- `edge_cookie.secret_key` cannot be `"secret-key"`, `"secret_key"`, or `"trusted-server"` (case-insensitive)
+- `ec.passphrase` cannot be `"secret-key"`, `"secret_key"`, or `"trusted-server"` (case-insensitive)
 - `publisher.proxy_secret` cannot be `"change-me-proxy-secret"` (case-insensitive)
 - Must be non-empty
 - Change to a secure random value (see generation commands above)
diff --git a/docs/guide/edge-cookies.md b/docs/guide/edge-cookies.md
index d0e31e2e..bdb7361e 100644
--- a/docs/guide/edge-cookies.md
+++ b/docs/guide/edge-cookies.md
@@ -20,7 +20,7 @@ EC IDs use HMAC (Hash-based Message Authentication Code) to generate a determini
 
 ## Configuration
 
-Configure EC secrets in `trusted-server.toml`. See the full [Configuration Reference](/guide/configuration) for the `[edge_cookie]` section and environment variable overrides.
+Configure EC settings in `trusted-server.toml`. See the full [Configuration Reference](/guide/configuration) for the `[ec]` section and environment variable overrides.
 
 ## Privacy Considerations
 
diff --git a/docs/guide/error-reference.md b/docs/guide/error-reference.md
index 99f611aa..92d1a003 100644
--- a/docs/guide/error-reference.md
+++ b/docs/guide/error-reference.md
@@ -69,7 +69,7 @@ proxy_secret = "change-me-to-random-string"
 - `publisher.domain`
 - `publisher.origin_url`
 - `publisher.proxy_secret`
-- `edge_cookie.secret_key`
+- `ec.passphrase`
 
 ---
 
@@ -141,11 +141,11 @@ Failed to generate EC ID: HMAC error
 
 **Solution:**
 
-1. Ensure `secret_key` is set in `trusted-server.toml`:
+1. Ensure `passphrase` is set in `trusted-server.toml`:
 
 ```toml
-[edge_cookie]
-secret_key = "your-secure-hmac-secret"
+[ec]
+passphrase = "your-secure-hmac-secret"
 ```
 
 2. Or set via environment variable:
@@ -245,7 +245,9 @@ curl -w "%{time_total}\n" https://upstream-service.example.com
 Warning: Cookie not set due to domain mismatch
 ```
 
-**Cause:** `publisher.cookie_domain` doesn't match request domain
+**Cause:** `publisher.cookie_domain` doesn't match request domain.
+Note: EC cookies (`ts-ec`) use a computed domain from `publisher.domain`,
+not `cookie_domain`.
 
 **Solution:**
 
diff --git a/docs/guide/first-party-proxy.md b/docs/guide/first-party-proxy.md
index b978e35f..a2567c51 100644
--- a/docs/guide/first-party-proxy.md
+++ b/docs/guide/first-party-proxy.md
@@ -420,9 +420,9 @@ Configure proxy behavior in `trusted-server.toml`:
 ```toml
 [publisher]
 domain = "publisher.com"
+cookie_domain = ".publisher.com"
 origin_url = "https://origin.publisher.com"
 proxy_secret = "your-secure-random-secret"
-cookie_domain = ".publisher.com"  # For ts-ec cookies
 ```
 
 ### Proxy Allowlist
diff --git a/docs/guide/onboarding.md b/docs/guide/onboarding.md
index 83203d35..5d4d5b32 100644
--- a/docs/guide/onboarding.md
+++ b/docs/guide/onboarding.md
@@ -40,7 +40,7 @@ Welcome to the Trusted Server project! This guide keeps internal onboarding note
 | `crates/trusted-server-adapter-fastly/src/main.rs`        | Request routing entry point      |
 | `crates/trusted-server-core/src/publisher.rs`             | Publisher origin handling        |
 | `crates/trusted-server-core/src/proxy.rs`                 | First-party proxy implementation |
-| `crates/trusted-server-core/src/edge_cookie.rs`           | EC ID generation                 |
+| `crates/trusted-server-core/src/ec/`                      | EC identity subsystem            |
 | `crates/trusted-server-core/src/integrations/registry.rs` | Integration module pattern       |
 | `trusted-server.toml`                                     | Application configuration        |
 
@@ -146,7 +146,7 @@ Use this checklist to track your onboarding progress:
 
 - [ ] Read through `main.rs` to understand request routing
 - [ ] Trace a request through `publisher.rs` and `proxy.rs`
-- [ ] Understand EC ID generation in `edge_cookie.rs`
+- [ ] Understand the EC identity subsystem in `ec/`
 - [ ] Review an existing integration (e.g., `prebid.rs`)
 
 ### Documentation & Contribution
diff --git a/docs/guide/testing.md b/docs/guide/testing.md
index cfa7ea51..42eec03e 100644
--- a/docs/guide/testing.md
+++ b/docs/guide/testing.md
@@ -21,7 +21,7 @@ cargo test
 Tests are organized alongside source code in `#[cfg(test)]` modules:
 
 ```rust
-// crates/trusted-server-core/src/edge_cookie.rs
+// crates/trusted-server-core/src/ec/generation.rs
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -88,7 +88,7 @@ curl http://localhost:7676/.well-known/trusted-server.json
 
 ### EC ID Tests
 
-From `crates/trusted-server-core/src/edge_cookie.rs`:
+From `crates/trusted-server-core/src/ec/mod.rs`:
 
 ```rust
 #[test]
@@ -323,6 +323,7 @@ k6 run load-test.js
 5. **Use test helpers** - `create_test_settings()`, `create_test_request()`
 6. **Assert specific values** - Not just `assert!(result.is_ok())`
 
+
 ## Next Steps
 
 - Review [Architecture](/guide/architecture) for system design
diff --git a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
index ad47c65d..90fd9a7f 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
@@ -39,11 +39,11 @@ EC is the full replacement for SyntheticID. The PRD explicitly states backward c
 
 **Prerequisites (must be merged before this epic begins):**
 
-- **SyntheticID → Edge Cookie rename** — [PR #479](https://github.com/IABTechLab/trusted-server/pull/479) renames SyntheticID to Edge Cookie (EC) across all code paths: `synthetic.rs` → `edge_cookie.rs`, `COOKIE_SYNTHETIC_ID` → `COOKIE_EC_ID`, `X-Synthetic-*` → `X-ts-ec`/`X-ts-ec-fresh` headers, `settings.synthetic` → `settings.edge_cookie`, and simplifies EC generation to IP-only HMAC-SHA256 (removing Handlebars templating). It also renames `ConsentPipelineInput.synthetic_id` to `ec_id`, updates consent KV helper parameters/docs, and handles consent-store key migration (old SyntheticID keys orphaned, TTL expiry cleans them up). **This PR must be merged before implementation of this spec begins.** The spec assumes a codebase where SyntheticID no longer exists. Verify before starting:
+- **SyntheticID removal** — [PR #479](https://github.com/IABTechLab/trusted-server/pull/479) removes SyntheticID from all active code paths: `get_or_generate_synthetic_id()`, `COOKIE_SYNTHETIC_ID`, `X-Synthetic-*` headers, `synthetic.rs` module, `settings.synthetic` config, and all SyntheticID generation/cookie code from `publisher.rs`, `endpoints.rs`, and `registry.rs`. It also renames `ConsentPipelineInput.synthetic_id` to `identity_key`, updates consent KV helper parameters/docs, and handles consent-store key migration (old SyntheticID keys orphaned, TTL expiry cleans them up). **This PR must be merged before implementation of this spec begins.** The spec assumes a codebase where SyntheticID no longer exists. Verify before starting:
   - `grep -r 'synthetic_id' crates/` returns no hits outside test fixtures
   - `grep -r 'X-Synthetic' crates/` returns no hits
   - `trusted-server.toml` has no `[synthetic]` section
-  - `ConsentPipelineInput` uses `ec_id`, not `synthetic_id`
+  - `ConsentPipelineInput` uses `identity_key`, not `synthetic_id`
 - **Consent implementation** — The consent pipeline (`build_consent_context()`, `ConsentContext`, `allows_ec_creation()`, TCF/GPP/US-Privacy decoding) is implemented and available as a stable interface before this epic. PR `#380` merged to `main`. EC calls `allows_ec_creation()` directly — no new gating functions are introduced. Note: EC changes the _phase order_ relative to the old SyntheticID flow — consent is evaluated before EC generation, so first-visit consent KV persistence is deferred to the second request (see §6.1.1 for full analysis).
 
 **Deferred from this spec (not in scope):**
@@ -257,7 +257,7 @@ impl EcContext {
     /// `GeoInfo::from_request()` in the current `main.rs`.
     ///
     /// Calls `build_consent_context()` with the EC hash (when present) passed
-    /// via `ConsentPipelineInput.ec_id` (renamed from `synthetic_id`
+    /// via `ConsentPipelineInput.identity_key` (renamed from `synthetic_id`
     /// in PR #479).
     ///
     /// When an EC hash is available (returning user), this enables the consent
@@ -452,7 +452,7 @@ the consent module; EC only consumes that existing decision.
 
 **Consent pipeline integration:**
 
-`EcContext::read_from_request()` calls `build_consent_context()` with the EC hash as the identity key, passed via `ConsentPipelineInput.ec_id` (renamed from `synthetic_id` in PR #479). The consent pipeline's KV persistence and fallback behavior works with EC hashes:
+`EcContext::read_from_request()` calls `build_consent_context()` with the EC hash as the identity key, passed via `ConsentPipelineInput.identity_key` (renamed from `synthetic_id` in PR #479). The consent pipeline's KV persistence and fallback behavior works with EC hashes:
 
 - **Returning user** (EC cookie present → `ec_hash` is `Some`): consent KV fallback read is available when consent cookies are absent; consent KV write persists cookie-sourced consent for future requests. Note: `build_consent_context()` calls `try_kv_write()` internally, so phase 1 writes to the **consent** KV store (not the EC identity store).
 - **First visit** (no EC cookie → `ec_hash` is `None`): no consent KV interaction. Consent is evaluated purely from request cookies/headers. The gap: consent is not persisted to consent KV on the first request. This is accepted — in regulated jurisdictions (GDPR, US state), consent cookies/headers must be present for `allows_ec_creation()` to return `true`, so there is always a signal to persist on the next request. In non-regulated jurisdictions, `allows_ec_creation()` returns `true` without consent signals, so there is nothing to persist anyway. Consent KV persistence begins on the second request when the EC cookie is present.
diff --git a/trusted-server.toml b/trusted-server.toml
index d9189aaa..dbee4746 100644
--- a/trusted-server.toml
+++ b/trusted-server.toml
@@ -14,8 +14,8 @@ cookie_domain = ".test-publisher.com"
 origin_url = "https://origin.test-publisher.com"
 proxy_secret = "change-me-proxy-secret"
 
-[edge_cookie]
-secret_key = "trusted-server"
+[ec]
+passphrase = "trusted-server"
 
 # Custom headers to be included in every response
 # Allows publishers to include tags such as X-Robots-Tag: noindex

From 7851ac586584742a2f545d842170c5781e1bd661 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Wed, 25 Mar 2026 18:57:46 -0500
Subject: [PATCH 04/36] Add KV identity graph with CAS concurrency control

Implement Story 3 (#536): KV-backed identity graph with compare-and-swap
concurrency, partner ID upserts, tombstone writes for consent withdrawal,
and revive semantics. Includes schema types, metadata, 300s last-seen
debounce, and comprehensive unit tests.

Also incorporates earlier foundation work: EC module restructure, config
migration from [edge_cookie] to [ec], cookie domain computation, consent
gating fixes, and integration proxy revocation support.
---
 Cargo.lock                                    |   1 -
 Cargo.toml                                    |   1 -
 .../fixtures/configs/viceroy-template.toml    |  14 +-
 .../tests/kv_store/counter_store.json         |   3 +
 .../tests/kv_store/opid_store.json            |   3 +
 crates/trusted-server-core/Cargo.toml         |   1 -
 crates/trusted-server-core/src/auth.rs        |  27 +-
 crates/trusted-server-core/src/cookies.rs     | 264 +-------
 crates/trusted-server-core/src/ec/kv.rs       | 588 ++++++++++++++++++
 crates/trusted-server-core/src/ec/kv_types.rs | 386 ++++++++++++
 crates/trusted-server-core/src/ec/mod.rs      |  36 +-
 .../src/integrations/prebid.rs                | 164 ++++-
 .../src/integrations/registry.rs              | 119 ++--
 crates/trusted-server-core/src/publisher.rs   | 102 ++-
 crates/trusted-server-core/src/settings.rs    |  42 +-
 docs/guide/testing.md                         |   1 -
 fastly.toml                                   |  16 +
 trusted-server.toml                           |   2 +
 18 files changed, 1312 insertions(+), 458 deletions(-)
 create mode 100644 crates/trusted-server-adapter-fastly/tests/kv_store/counter_store.json
 create mode 100644 crates/trusted-server-adapter-fastly/tests/kv_store/opid_store.json
 create mode 100644 crates/trusted-server-core/src/ec/kv.rs
 create mode 100644 crates/trusted-server-core/src/ec/kv_types.rs

diff --git a/Cargo.lock b/Cargo.lock
index 6dceaf01..8ad2b3e2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2767,7 +2767,6 @@ dependencies = [
  "serde",
  "serde_json",
  "sha2 0.10.9",
- "subtle",
  "temp-env",
  "tokio",
  "tokio-test",
diff --git a/Cargo.toml b/Cargo.toml
index c3a35154..69c03344 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -81,7 +81,6 @@ regex = "1.12.3"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0.149"
 sha2 = "0.10.9"
-subtle = "2.6"
 temp-env = "0.3.6"
 tokio = { version = "1.49", features = ["sync", "macros", "io-util", "rt", "time"] }
 tokio-test = "0.4"
diff --git a/crates/integration-tests/fixtures/configs/viceroy-template.toml b/crates/integration-tests/fixtures/configs/viceroy-template.toml
index 06c2a850..68e8bd15 100644
--- a/crates/integration-tests/fixtures/configs/viceroy-template.toml
+++ b/crates/integration-tests/fixtures/configs/viceroy-template.toml
@@ -7,9 +7,17 @@
     [local_server.backends]
 
     [local_server.kv_stores]
-         # These inline placeholders satisfy Viceroy's local KV configuration
-         # requirements without exercising KV-backed application behavior.
-         [[local_server.kv_stores.creative_store]]
+        # These inline placeholders satisfy Viceroy's local KV configuration
+        # requirements without exercising KV-backed application behavior.
+        [[local_server.kv_stores.counter_store]]
+            key = "placeholder"
+            data = "placeholder"
+
+        [[local_server.kv_stores.opid_store]]
+            key = "placeholder"
+            data = "placeholder"
+
+        [[local_server.kv_stores.creative_store]]
             key = "placeholder"
             data = "placeholder"
 
diff --git a/crates/trusted-server-adapter-fastly/tests/kv_store/counter_store.json b/crates/trusted-server-adapter-fastly/tests/kv_store/counter_store.json
new file mode 100644
index 00000000..8c3b91f8
--- /dev/null
+++ b/crates/trusted-server-adapter-fastly/tests/kv_store/counter_store.json
@@ -0,0 +1,3 @@
+{
+    "ec_counter": 10
+}
diff --git a/crates/trusted-server-adapter-fastly/tests/kv_store/opid_store.json b/crates/trusted-server-adapter-fastly/tests/kv_store/opid_store.json
new file mode 100644
index 00000000..8c3b91f8
--- /dev/null
+++ b/crates/trusted-server-adapter-fastly/tests/kv_store/opid_store.json
@@ -0,0 +1,3 @@
+{
+    "ec_counter": 10
+}
diff --git a/crates/trusted-server-core/Cargo.toml b/crates/trusted-server-core/Cargo.toml
index c9c538fd..facb74bb 100644
--- a/crates/trusted-server-core/Cargo.toml
+++ b/crates/trusted-server-core/Cargo.toml
@@ -40,7 +40,6 @@ regex = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 sha2 = { workspace = true }
-subtle = { workspace = true }
 tokio = { workspace = true }
 toml = { workspace = true }
 trusted-server-js = { path = "../js" }
diff --git a/crates/trusted-server-core/src/auth.rs b/crates/trusted-server-core/src/auth.rs
index 547784df..1b60eb81 100644
--- a/crates/trusted-server-core/src/auth.rs
+++ b/crates/trusted-server-core/src/auth.rs
@@ -2,8 +2,6 @@ use base64::{engine::general_purpose::STANDARD, Engine as _};
 use error_stack::Report;
 use fastly::http::{header, StatusCode};
 use fastly::{Request, Response};
-use sha2::{Digest as _, Sha256};
-use subtle::ConstantTimeEq as _;
 
 use crate::error::TrustedServerError;
 use crate::settings::Settings;
@@ -99,9 +97,14 @@ mod tests {
 
     use crate::test_support::tests::{crate_test_settings_str, create_test_settings};
 
+    fn settings_with_handlers() -> Settings {
+        let config = crate_test_settings_str();
+        Settings::from_toml(&config).expect("should parse settings with handlers")
+    }
+
     #[test]
     fn no_challenge_for_non_protected_path() {
-        let settings = create_test_settings();
+        let settings = settings_with_handlers();
         let req = Request::new(Method::GET, "https://example.com/open");
 
         assert!(enforce_basic_auth(&settings, &req)
@@ -111,7 +114,7 @@ mod tests {
 
     #[test]
     fn challenge_when_missing_credentials() {
-        let settings = create_test_settings();
+        let settings = settings_with_handlers();
         let req = Request::new(Method::GET, "https://example.com/secure");
 
         let response = enforce_basic_auth(&settings, &req)
@@ -126,7 +129,7 @@ mod tests {
 
     #[test]
     fn allow_when_credentials_match() {
-        let settings = create_test_settings();
+        let settings = settings_with_handlers();
         let mut req = Request::new(Method::GET, "https://example.com/secure/data");
         let token = STANDARD.encode("user:pass");
         req.set_header(header::AUTHORIZATION, format!("Basic {token}"));
@@ -137,10 +140,10 @@ mod tests {
     }
 
     #[test]
-    fn challenge_when_both_credentials_wrong() {
-        let settings = create_test_settings();
+    fn challenge_when_credentials_mismatch() {
+        let settings = settings_with_handlers();
         let mut req = Request::new(Method::GET, "https://example.com/secure/data");
-        let token = STANDARD.encode("wrong:wrong");
+        let token = STANDARD.encode("user:wrong");
         req.set_header(header::AUTHORIZATION, format!("Basic {token}"));
 
         let response = enforce_basic_auth(&settings, &req)
@@ -186,7 +189,7 @@ mod tests {
 
     #[test]
     fn challenge_when_scheme_is_not_basic() {
-        let settings = create_test_settings();
+        let settings = settings_with_handlers();
         let mut req = Request::new(Method::GET, "https://example.com/secure");
         req.set_header(header::AUTHORIZATION, "Bearer token");
 
@@ -209,7 +212,7 @@ mod tests {
 
     #[test]
     fn allow_admin_path_with_valid_credentials() {
-        let settings = create_test_settings();
+        let settings = settings_with_handlers();
         let mut req = Request::new(Method::POST, "https://example.com/admin/keys/rotate");
         let token = STANDARD.encode("admin:admin-pass");
         req.set_header(header::AUTHORIZATION, format!("Basic {token}"));
@@ -224,7 +227,7 @@ mod tests {
 
     #[test]
     fn challenge_admin_path_with_wrong_credentials() {
-        let settings = create_test_settings();
+        let settings = settings_with_handlers();
         let mut req = Request::new(Method::POST, "https://example.com/admin/keys/rotate");
         let token = STANDARD.encode("admin:wrong");
         req.set_header(header::AUTHORIZATION, format!("Basic {token}"));
@@ -237,7 +240,7 @@ mod tests {
 
     #[test]
     fn challenge_admin_path_with_missing_credentials() {
-        let settings = create_test_settings();
+        let settings = settings_with_handlers();
         let req = Request::new(Method::POST, "https://example.com/admin/keys/rotate");
 
         let response = enforce_basic_auth(&settings, &req)
diff --git a/crates/trusted-server-core/src/cookies.rs b/crates/trusted-server-core/src/cookies.rs
index 963bf125..2d9bf2ff 100644
--- a/crates/trusted-server-core/src/cookies.rs
+++ b/crates/trusted-server-core/src/cookies.rs
@@ -1,20 +1,15 @@
 //! Cookie handling utilities.
 //!
-//! This module provides functionality for parsing and creating cookies
+//! This module provides functionality for parsing, stripping, and forwarding cookies
 //! used in the trusted server system.
 
-use std::borrow::Cow;
-
 use cookie::{Cookie, CookieJar};
 use error_stack::{Report, ResultExt};
 use fastly::http::header;
 use fastly::Request;
 
-use crate::constants::{
-    COOKIE_EUCONSENT_V2, COOKIE_GPP, COOKIE_GPP_SID, COOKIE_TS_EC, COOKIE_US_PRIVACY,
-};
+use crate::constants::{COOKIE_EUCONSENT_V2, COOKIE_GPP, COOKIE_GPP_SID, COOKIE_US_PRIVACY};
 use crate::error::TrustedServerError;
-use crate::settings::Settings;
 
 /// Cookie names carrying privacy consent signals.
 ///
@@ -170,106 +165,8 @@ pub fn forward_cookie_header(from: &Request, to: &mut Request, strip_consent: bo
     }
 }
 
-/// Returns `true` if every byte in `value` is a valid RFC 6265 `cookie-octet`.
-/// An empty string is always rejected.
-///
-/// RFC 6265 restricts cookie values to printable US-ASCII excluding whitespace,
-/// double-quote, comma, semicolon, and backslash. Rejecting these characters
-/// prevents header-injection attacks where a crafted value could append
-/// spurious cookie attributes (e.g. `evil; Domain=.attacker.com`).
-///
-/// Non-ASCII characters (multi-byte UTF-8) are always rejected because their
-/// byte values exceed `0x7E`.
-#[must_use]
-fn is_safe_cookie_value(value: &str) -> bool {
-    // RFC 6265 §4.1.1 cookie-octet:
-    //   0x21        — '!'
-    //   0x23–0x2B  — '#' through '+'   (excludes 0x22 DQUOTE)
-    //   0x2D–0x3A  — '-' through ':'   (excludes 0x2C comma)
-    //   0x3C–0x5B  — '<' through '['   (excludes 0x3B semicolon)
-    //   0x5D–0x7E  — ']' through '~'   (excludes 0x5C backslash, 0x7F DEL)
-    // All control characters (0x00–0x20) and non-ASCII (0x80+) are also excluded.
-    !value.is_empty()
-        && value
-            .bytes()
-            .all(|b| matches!(b, 0x21 | 0x23..=0x2B | 0x2D..=0x3A | 0x3C..=0x5B | 0x5D..=0x7E))
-}
-
-/// Generates a `Set-Cookie` header value with the following security attributes:
-/// - `Secure`: transmitted over HTTPS only.
-/// - `HttpOnly`: inaccessible to JavaScript (`document.cookie`), blocking XSS exfiltration.
-///   Safe to set because integrations receive the EC ID via the `x-ts-ec`
-///   response header instead of reading it from the cookie directly.
-/// - `SameSite=Lax`: sent on same-site requests and top-level cross-site navigations.
-///   `Strict` is intentionally avoided — it would suppress the cookie on the first
-///   request when a user arrives from an external page, breaking first-visit attribution.
-/// - `Max-Age`: 1 year retention.
-///
-/// The `ec_id` is sanitized via an allowlist before embedding in the cookie value.
-/// Only ASCII alphanumeric characters and `.`, `-`, `_` are permitted — matching the
-/// known EC ID format (`{64-char-hex}.{6-char-alphanumeric}`). Request-sourced IDs
-/// with disallowed characters are rejected earlier in [`crate::edge_cookie::get_ec_id`];
-/// this sanitization remains as a defense-in-depth backstop for unexpected callers.
-///
-/// The `cookie_domain` is validated at config load time via [`validator::Validate`] on
-/// [`crate::settings::Publisher`]; bad config fails at startup, not per-request.
-///
-/// # Examples
-///
-/// ```no_run
-/// # use trusted_server_core::cookies::create_ec_cookie;
-/// # use trusted_server_core::settings::Settings;
-/// // `settings` is loaded at startup via `Settings::from_toml_and_env`.
-/// # fn example(settings: &Settings) {
-/// let cookie = create_ec_cookie(settings, "abc123.xk92ab");
-/// assert!(cookie.contains("HttpOnly"));
-/// assert!(cookie.contains("Secure"));
-/// # }
-/// ```
-#[must_use]
-pub fn create_ec_cookie(settings: &Settings, ec_id: &str) -> String {
-    let safe_id = sanitize_ec_id_for_cookie(ec_id);
-
-    format!(
-        "{}={}; {}",
-        COOKIE_TS_EC,
-        safe_id,
-        ec_cookie_attributes(settings, COOKIE_MAX_AGE),
-    )
-}
-
-/// Sets the EC ID cookie on the given response.
-///
-/// Validates `ec_id` against RFC 6265 `cookie-octet` rules before
-/// interpolation. If the value contains unsafe characters (e.g. semicolons),
-/// the cookie is not set and a warning is logged. This prevents an attacker
-/// from injecting spurious cookie attributes via a controlled ID value.
-///
-/// `cookie_domain` comes from operator configuration and is considered trusted.
-pub fn set_ec_cookie(settings: &Settings, response: &mut fastly::Response, ec_id: &str) {
-    if !is_safe_cookie_value(ec_id) {
-        log::warn!(
-            "Rejecting EC ID for Set-Cookie: value of {} bytes contains characters illegal in a cookie value",
-            ec_id.len()
-        );
-        return;
-    }
-    response.append_header(header::SET_COOKIE, create_ec_cookie(settings, ec_id));
-}
-
-/// Expires the EC cookie by setting `Max-Age=0`.
-///
-/// Used when a user revokes consent — the browser will delete the cookie
-/// on receipt of this header.
-pub fn expire_ec_cookie(settings: &Settings, response: &mut fastly::Response) {
-    let cookie = format!("{}=; {}", COOKIE_TS_EC, ec_cookie_attributes(settings, 0),);
-    response.append_header(header::SET_COOKIE, cookie);
-}
-
 #[cfg(test)]
 mod tests {
-    use crate::test_support::tests::create_test_settings;
-
     use super::*;
 
     #[test]
@@ -292,7 +189,7 @@ mod tests {
     }
 
     #[test]
-    fn test_parse_cookies_to_jar_empty() {
+    fn test_parse_cookies_to_jar_emtpy() {
         let cookie_str = "";
         let jar = parse_cookies_to_jar(cookie_str);
 
@@ -347,161 +244,6 @@ mod tests {
         assert!(jar.iter().count() == 0);
     }
 
-    #[test]
-    fn test_set_ec_cookie() {
-        let settings = create_test_settings();
-        let mut response = fastly::Response::new();
-        set_ec_cookie(&settings, &mut response, "abc123.XyZ789");
-
-        let cookie_str = response
-            .get_header(header::SET_COOKIE)
-            .expect("Set-Cookie header should be present")
-            .to_str()
-            .expect("header should be valid UTF-8");
-
-        assert_eq!(
-            cookie_str,
-            format!(
-                "{}=abc123.XyZ789; Domain={}; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age={}",
-                COOKIE_TS_EC, settings.publisher.cookie_domain, COOKIE_MAX_AGE,
-            ),
-            "Set-Cookie header should match expected format"
-        );
-    }
-
-    #[test]
-    fn test_create_ec_cookie_sanitizes_disallowed_chars_in_id() {
-        let settings = create_test_settings();
-        // Allowlist permits only ASCII alphanumeric, '.', '-', '_'.
-        // ';', '=', '\r', '\n', spaces, NUL bytes, and other control chars are all stripped.
-        let result = create_ec_cookie(&settings, "evil;injected\r\nfoo=bar\0baz");
-        // Extract the value portion anchored to the cookie name constant to
-        // avoid false positives from disallowed chars in cookie attributes.
-        let value = result
-            .strip_prefix(&format!("{}=", COOKIE_TS_EC))
-            .and_then(|s| s.split_once(';').map(|(v, _)| v))
-            .expect("should have cookie value portion");
-        assert_eq!(
-            value, "evilinjectedfoobarbaz",
-            "should strip disallowed characters and preserve safe chars"
-        );
-    }
-
-    #[test]
-    fn test_create_ec_cookie_preserves_well_formed_id() {
-        let settings = create_test_settings();
-        // A well-formed ID should pass through the allowlist unmodified.
-        let id = "abc123def0123456789abcdef0123456789abcdef0123456789abcdef01234567.xk92ab";
-        let result = create_ec_cookie(&settings, id);
-        let value = result
-            .strip_prefix(&format!("{}=", COOKIE_TS_EC))
-            .and_then(|s| s.split_once(';').map(|(v, _)| v))
-            .expect("should have cookie value portion");
-        assert_eq!(value, id, "should not modify a well-formed EC ID");
-    }
-
-    #[test]
-    fn test_set_ec_cookie_rejects_semicolon() {
-        let settings = create_test_settings();
-        let mut response = fastly::Response::new();
-        set_ec_cookie(&settings, &mut response, "evil; Domain=.attacker.com");
-
-        assert!(
-            response.get_header(header::SET_COOKIE).is_none(),
-            "Set-Cookie should not be set when value contains a semicolon"
-        );
-    }
-
-    #[test]
-    fn test_set_ec_cookie_rejects_crlf() {
-        let settings = create_test_settings();
-        let mut response = fastly::Response::new();
-        set_ec_cookie(&settings, &mut response, "evil\r\nX-Injected: header");
-
-        assert!(
-            response.get_header(header::SET_COOKIE).is_none(),
-            "Set-Cookie should not be set when value contains CRLF"
-        );
-    }
-
-    #[test]
-    fn test_set_ec_cookie_rejects_space() {
-        let settings = create_test_settings();
-        let mut response = fastly::Response::new();
-        set_ec_cookie(&settings, &mut response, "bad value");
-
-        assert!(
-            response.get_header(header::SET_COOKIE).is_none(),
-            "Set-Cookie should not be set when value contains whitespace"
-        );
-    }
-
-    #[test]
-    fn test_is_safe_cookie_value_rejects_empty_string() {
-        assert!(!is_safe_cookie_value(""), "should reject empty string");
-    }
-
-    #[test]
-    fn test_is_safe_cookie_value_accepts_valid_ec_id_characters() {
-        // Hex digits, dot separator, alphanumeric suffix — the full EC ID character set
-        assert!(
-            is_safe_cookie_value("abcdef0123456789.ABCDEFabcdef"),
-            "should accept hex digits, dots, and alphanumeric characters"
-        );
-    }
-
-    #[test]
-    fn test_is_safe_cookie_value_rejects_non_ascii() {
-        assert!(
-            !is_safe_cookie_value("valüe"),
-            "should reject non-ASCII UTF-8 characters"
-        );
-    }
-
-    #[test]
-    fn test_is_safe_cookie_value_rejects_illegal_characters() {
-        assert!(!is_safe_cookie_value("val;ue"), "should reject semicolon");
-        assert!(!is_safe_cookie_value("val,ue"), "should reject comma");
-        assert!(
-            !is_safe_cookie_value("val\"ue"),
-            "should reject double-quote"
-        );
-        assert!(!is_safe_cookie_value("val\\ue"), "should reject backslash");
-        assert!(!is_safe_cookie_value("val ue"), "should reject space");
-        assert!(
-            !is_safe_cookie_value("val\x00ue"),
-            "should reject null byte"
-        );
-        assert!(
-            !is_safe_cookie_value("val\x7fue"),
-            "should reject DEL character"
-        );
-    }
-
-    #[test]
-    fn test_expire_ec_cookie_matches_security_attributes() {
-        let settings = create_test_settings();
-        let mut response = fastly::Response::new();
-
-        expire_ec_cookie(&settings, &mut response);
-
-        let cookie_header = response
-            .get_header(header::SET_COOKIE)
-            .expect("Set-Cookie header should be present");
-        let cookie_str = cookie_header
-            .to_str()
-            .expect("header should be valid UTF-8");
-
-        assert_eq!(
-            cookie_str,
-            format!(
-                "{}=; Domain={}; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=0",
-                COOKIE_TS_EC, settings.publisher.cookie_domain,
-            ),
-            "expiry cookie should retain the same security attributes as the live cookie"
-        );
-    }
-
     // ---------------------------------------------------------------
     // strip_cookies tests
     // ---------------------------------------------------------------
diff --git a/crates/trusted-server-core/src/ec/kv.rs b/crates/trusted-server-core/src/ec/kv.rs
new file mode 100644
index 00000000..44be5513
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/kv.rs
@@ -0,0 +1,588 @@
+//! KV identity graph operations.
+//!
+//! This module provides [`KvIdentityGraph`] which wraps a Fastly KV Store
+//! and implements the read-modify-write operations for the EC identity graph.
+//!
+//! All methods return `Result` — callers decide whether to swallow errors
+//! (organic request paths) or propagate them (sync endpoints). See the
+//! per-operation error handling policy in the spec §7.5.
+
+use std::time::Duration;
+
+use error_stack::{Report, ResultExt};
+use fastly::kv_store::{InsertMode, KVStore};
+
+use crate::error::TrustedServerError;
+
+use super::kv_types::{KvEntry, KvMetadata};
+
+/// Maximum number of CAS retry attempts before giving up.
+const MAX_CAS_RETRIES: u32 = 3;
+
+/// Minimum interval (seconds) between `last_seen` KV writes for the same key.
+/// Prevents write thrashing under bursty traffic — Fastly KV enforces a
+/// 1 write/sec limit per key.
+const LAST_SEEN_DEBOUNCE_SECS: u64 = 300;
+
+/// TTL for live entries (1 year), matching the EC cookie `Max-Age`.
+const ENTRY_TTL: Duration = Duration::from_secs(365 * 24 * 60 * 60);
+
+/// TTL for withdrawal tombstones (24 hours).
+const TOMBSTONE_TTL: Duration = Duration::from_secs(24 * 60 * 60);
+
+/// Wraps a Fastly KV Store for EC identity graph operations.
+///
+/// Each EC hash (64-char hex prefix) maps to a JSON-encoded [`KvEntry`]
+/// containing consent state, geo location, and accumulated partner IDs.
+///
+/// Methods use optimistic concurrency (generation markers) for safe
+/// read-modify-write operations on concurrent requests.
+pub struct KvIdentityGraph {
+    store_name: String,
+}
+
+impl KvIdentityGraph {
+    /// Creates a new identity graph backed by the named KV store.
+    #[must_use]
+    pub fn new(store_name: impl Into<String>) -> Self {
+        Self {
+            store_name: store_name.into(),
+        }
+    }
+
+    /// Returns the configured store name.
+    #[must_use]
+    pub fn store_name(&self) -> &str {
+        &self.store_name
+    }
+
+    /// Opens the underlying Fastly KV store.
+    fn open_store(&self) -> Result<KVStore, Report<TrustedServerError>> {
+        KVStore::open(&self.store_name)
+            .change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: "Failed to open KV store".to_owned(),
+            })?
+            .ok_or_else(|| {
+                Report::new(TrustedServerError::KvStore {
+                    store_name: self.store_name.clone(),
+                    message: "KV store not found".to_owned(),
+                })
+            })
+    }
+
+    /// Serializes an entry body and metadata for insertion.
+    fn serialize_entry(
+        entry: &KvEntry,
+        store_name: &str,
+    ) -> Result<(String, String), Report<TrustedServerError>> {
+        let body = serde_json::to_string(entry).change_context(TrustedServerError::KvStore {
+            store_name: store_name.to_owned(),
+            message: "Failed to serialize KV entry body".to_owned(),
+        })?;
+        let meta = KvMetadata::from_entry(entry);
+        let meta_str =
+            serde_json::to_string(&meta).change_context(TrustedServerError::KvStore {
+                store_name: store_name.to_owned(),
+                message: "Failed to serialize KV entry metadata".to_owned(),
+            })?;
+        Ok((body, meta_str))
+    }
+
+    /// Reads the full entry and its generation marker for CAS writes.
+    ///
+    /// Returns `Ok(None)` when the key does not exist.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store open or read failure.
+    pub fn get(&self, ec_hash: &str) -> Result<Option<(KvEntry, u64)>, Report<TrustedServerError>> {
+        let store = self.open_store()?;
+        let mut response = match store.lookup(ec_hash) {
+            Ok(resp) => resp,
+            Err(fastly::kv_store::KVStoreError::ItemNotFound) => return Ok(None),
+            Err(err) => {
+                return Err(
+                    Report::new(err).change_context(TrustedServerError::KvStore {
+                        store_name: self.store_name.clone(),
+                        message: format!("Failed to read key '{ec_hash}'"),
+                    }),
+                );
+            }
+        };
+
+        let generation = response.current_generation();
+        let body_bytes = response.take_body_bytes();
+        let entry: KvEntry =
+            serde_json::from_slice(&body_bytes).change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!("Failed to deserialize entry for key '{ec_hash}'"),
+            })?;
+
+        Ok(Some((entry, generation)))
+    }
+
+    /// Reads only the metadata for an EC hash (no body streaming).
+    ///
+    /// Returns `Ok(None)` when the key does not exist or has no metadata.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store open or read failure.
+    pub fn get_metadata(
+        &self,
+        ec_hash: &str,
+    ) -> Result<Option<KvMetadata>, Report<TrustedServerError>> {
+        let store = self.open_store()?;
+        let response = match store.lookup(ec_hash) {
+            Ok(resp) => resp,
+            Err(fastly::kv_store::KVStoreError::ItemNotFound) => return Ok(None),
+            Err(err) => {
+                return Err(
+                    Report::new(err).change_context(TrustedServerError::KvStore {
+                        store_name: self.store_name.clone(),
+                        message: format!("Failed to read metadata for key '{ec_hash}'"),
+                    }),
+                );
+            }
+        };
+
+        let meta_bytes = match response.metadata() {
+            Some(bytes) => bytes,
+            None => return Ok(None),
+        };
+
+        let meta: KvMetadata =
+            serde_json::from_slice(&meta_bytes).change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!("Failed to deserialize metadata for key '{ec_hash}'"),
+            })?;
+
+        Ok(Some(meta))
+    }
+
+    /// Creates a new entry. Fails if the key already exists.
+    ///
+    /// Uses `InsertMode::Add` so concurrent creates for the same EC hash
+    /// are safely rejected (only one wins).
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store error or if the
+    /// key already exists (`ItemPreconditionFailed`).
+    pub fn create(&self, ec_hash: &str, entry: &KvEntry) -> Result<(), Report<TrustedServerError>> {
+        let store = self.open_store()?;
+        let (body, meta_str) = Self::serialize_entry(entry, &self.store_name)?;
+        let created = Self::try_insert_add(&store, ec_hash, &body, &meta_str, &self.store_name)?;
+        if created {
+            Ok(())
+        } else {
+            Err(Report::new(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!("Key '{ec_hash}' already exists"),
+            }))
+        }
+    }
+
+    /// Low-level create using a pre-opened store and pre-serialized data.
+    ///
+    /// Returns `true` if the entry was created, `false` if the key already
+    /// exists (`ItemPreconditionFailed`). Other errors are propagated.
+    fn try_insert_add(
+        store: &KVStore,
+        ec_hash: &str,
+        body: &str,
+        meta_str: &str,
+        store_name: &str,
+    ) -> Result<bool, Report<TrustedServerError>> {
+        match store
+            .build_insert()
+            .mode(InsertMode::Add)
+            .metadata(meta_str)
+            .time_to_live(ENTRY_TTL)
+            .execute(ec_hash, body)
+        {
+            Ok(()) => Ok(true),
+            Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => Ok(false),
+            Err(err) => Err(
+                Report::new(err).change_context(TrustedServerError::KvStore {
+                    store_name: store_name.to_owned(),
+                    message: format!("Failed to create entry for key '{ec_hash}'"),
+                }),
+            ),
+        }
+    }
+
+    /// Creates a new entry, or overwrites an existing tombstone on re-consent.
+    ///
+    /// Three-way behavior:
+    /// - **No existing key** — creates the entry (same as [`create`](Self::create)).
+    /// - **Existing live entry** (`consent.ok = true`) — no-op, returns `Ok(())`.
+    /// - **Existing tombstone** (`consent.ok = false`) — CAS overwrite with
+    ///   the new entry. Retries up to [`MAX_CAS_RETRIES`] on conflict.
+    ///
+    /// Called by `generate_if_needed()` instead of `create()` so that a
+    /// user who re-consents within the 24-hour tombstone window recovers
+    /// immediately.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store error or CAS
+    /// exhaustion.
+    pub fn create_or_revive(
+        &self,
+        ec_hash: &str,
+        entry: &KvEntry,
+    ) -> Result<(), Report<TrustedServerError>> {
+        // Serialize once and reuse across the fast path and CAS loop.
+        let store = self.open_store()?;
+        let (body, meta_str) = Self::serialize_entry(entry, &self.store_name)?;
+
+        // Try create first — fast path for new entries.
+        if Self::try_insert_add(&store, ec_hash, &body, &meta_str, &self.store_name)? {
+            return Ok(());
+        }
+
+        // Key exists — read it to determine if it's live or a tombstone.
+        let (existing, generation) = match self.get(ec_hash)? {
+            Some(pair) => pair,
+            // Raced with a delete — try create again.
+            None => return self.create(ec_hash, entry),
+        };
+
+        // Live entry — nothing to do.
+        if existing.consent.ok {
+            log::debug!("create_or_revive: live entry exists for '{ec_hash}', no-op");
+            return Ok(());
+        }
+
+        // Tombstone — CAS overwrite to revive.
+        log::info!("create_or_revive: reviving tombstone for '{ec_hash}'");
+
+        let mut current_gen = generation;
+        for attempt in 0..MAX_CAS_RETRIES {
+            match store
+                .build_insert()
+                .if_generation_match(current_gen)
+                .metadata(&meta_str)
+                .time_to_live(ENTRY_TTL)
+                .execute(ec_hash, body.as_str())
+            {
+                Ok(()) => return Ok(()),
+                Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
+                    log::debug!(
+                        "create_or_revive: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_hash}'",
+                        attempt + 1,
+                    );
+                    // Re-read to get fresh generation.
+                    match self.get(ec_hash)? {
+                        Some((refreshed, gen)) => {
+                            if refreshed.consent.ok {
+                                // Someone else revived it — done.
+                                return Ok(());
+                            }
+                            current_gen = gen;
+                        }
+                        None => return self.create(ec_hash, entry),
+                    }
+                }
+                Err(err) => {
+                    return Err(
+                        Report::new(err).change_context(TrustedServerError::KvStore {
+                            store_name: self.store_name.clone(),
+                            message: format!(
+                                "Failed to revive tombstone for key '{ec_hash}' on attempt {}",
+                                attempt + 1,
+                            ),
+                        }),
+                    );
+                }
+            }
+        }
+
+        Err(Report::new(TrustedServerError::KvStore {
+            store_name: self.store_name.clone(),
+            message: format!(
+                "CAS conflict after {MAX_CAS_RETRIES} retries reviving tombstone for '{ec_hash}'"
+            ),
+        }))
+    }
+
+    /// Atomically merges a partner ID into the existing entry.
+    ///
+    /// Uses CAS (generation markers) to avoid clobbering concurrent writes
+    /// from other partners. Retries up to [`MAX_CAS_RETRIES`] on conflict.
+    ///
+    /// If the root entry does not exist (e.g. the initial `create_or_revive`
+    /// failed), creates a minimal live entry first — this is the recovery
+    /// path for best-effort EC creation misses.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store error or CAS
+    /// exhaustion after [`MAX_CAS_RETRIES`] attempts.
+    pub fn upsert_partner_id(
+        &self,
+        ec_hash: &str,
+        partner_id: &str,
+        uid: &str,
+        synced: u64,
+    ) -> Result<(), Report<TrustedServerError>> {
+        // Open store once for write operations. Note: `self.get()` opens
+        // its own handle internally — this is intentional since `KVStore::open`
+        // is a cheap name lookup, and keeping the read/write APIs independent
+        // simplifies the method signatures.
+        let store = self.open_store()?;
+
+        for attempt in 0..MAX_CAS_RETRIES {
+            let (mut entry, generation) = match self.get(ec_hash)? {
+                Some(pair) => pair,
+                None => {
+                    // Root entry missing — create a minimal entry.
+                    log::info!(
+                        "upsert_partner_id: no entry for '{ec_hash}', creating minimal entry"
+                    );
+                    let minimal = KvEntry::minimal(partner_id, uid, synced);
+                    let (min_body, min_meta) = Self::serialize_entry(&minimal, &self.store_name)?;
+                    if Self::try_insert_add(
+                        &store,
+                        ec_hash,
+                        &min_body,
+                        &min_meta,
+                        &self.store_name,
+                    )? {
+                        return Ok(());
+                    }
+                    // Key appeared between get() and create — re-read on next iteration.
+                    log::debug!(
+                        "upsert_partner_id: minimal create raced for '{ec_hash}', retrying (attempt {}/{})",
+                        attempt + 1,
+                        MAX_CAS_RETRIES,
+                    );
+                    continue;
+                }
+            };
+
+            // Reject upserts on withdrawn entries — a late sync must not
+            // repopulate partner IDs after consent withdrawal.
+            if !entry.consent.ok {
+                log::info!(
+                    "upsert_partner_id: entry for '{ec_hash}' is a tombstone, rejecting upsert"
+                );
+                return Err(Report::new(TrustedServerError::KvStore {
+                    store_name: self.store_name.clone(),
+                    message: format!(
+                        "Cannot upsert partner '{partner_id}' for withdrawn key '{ec_hash}'"
+                    ),
+                }));
+            }
+
+            // Merge the partner ID.
+            entry.ids.insert(
+                partner_id.to_owned(),
+                super::kv_types::KvPartnerId {
+                    uid: uid.to_owned(),
+                    synced,
+                },
+            );
+
+            let (body, meta_str) = Self::serialize_entry(&entry, &self.store_name)?;
+
+            match store
+                .build_insert()
+                .if_generation_match(generation)
+                .metadata(&meta_str)
+                .time_to_live(ENTRY_TTL)
+                .execute(ec_hash, body.as_str())
+            {
+                Ok(()) => return Ok(()),
+                Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
+                    log::debug!(
+                        "upsert_partner_id: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_hash}'",
+                        attempt + 1,
+                    );
+                    // Loop will re-read on next iteration.
+                }
+                Err(err) => {
+                    return Err(
+                        Report::new(err).change_context(TrustedServerError::KvStore {
+                            store_name: self.store_name.clone(),
+                            message: format!(
+                                "Failed to upsert partner '{partner_id}' for key '{ec_hash}'"
+                            ),
+                        }),
+                    );
+                }
+            }
+        }
+
+        Err(Report::new(TrustedServerError::KvStore {
+            store_name: self.store_name.clone(),
+            message: format!(
+                "CAS conflict after {MAX_CAS_RETRIES} retries upserting partner '{partner_id}' for '{ec_hash}'"
+            ),
+        }))
+    }
+
+    /// Updates the `last_seen` timestamp with a 300-second debounce.
+    ///
+    /// Skips the write if the stored `last_seen` is within
+    /// [`LAST_SEEN_DEBOUNCE_SECS`] of the new timestamp, or if the entry
+    /// does not exist.
+    ///
+    /// Does **not** retry on CAS conflict — if someone else wrote more
+    /// recently, the debounce condition is satisfied anyway.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store error or CAS
+    /// conflict.
+    pub fn update_last_seen(
+        &self,
+        ec_hash: &str,
+        timestamp: u64,
+    ) -> Result<(), Report<TrustedServerError>> {
+        let (mut entry, generation) = match self.get(ec_hash)? {
+            Some(pair) => pair,
+            None => {
+                log::debug!("update_last_seen: no entry for '{ec_hash}', skipping");
+                return Ok(());
+            }
+        };
+
+        // Skip tombstones — a stale cookie should not extend a 24h tombstone
+        // back to 1-year TTL.
+        if !entry.consent.ok {
+            log::debug!("update_last_seen: entry for '{ec_hash}' is a tombstone, skipping");
+            return Ok(());
+        }
+
+        // Guard against stale/out-of-order timestamps.
+        if timestamp <= entry.last_seen {
+            log::trace!(
+                "update_last_seen: stale timestamp for '{ec_hash}' (stored={}, incoming={timestamp})",
+                entry.last_seen,
+            );
+            return Ok(());
+        }
+
+        // Debounce: skip if the stored value is recent enough.
+        if timestamp - entry.last_seen < LAST_SEEN_DEBOUNCE_SECS {
+            log::trace!(
+                "update_last_seen: debounced for '{ec_hash}' (delta={}s)",
+                timestamp - entry.last_seen,
+            );
+            return Ok(());
+        }
+
+        entry.last_seen = timestamp;
+        let store = self.open_store()?;
+        let (body, meta_str) = Self::serialize_entry(&entry, &self.store_name)?;
+
+        store
+            .build_insert()
+            .if_generation_match(generation)
+            .metadata(&meta_str)
+            .time_to_live(ENTRY_TTL)
+            .execute(ec_hash, body)
+            .change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!("Failed to update last_seen for key '{ec_hash}'"),
+            })
+    }
+
+    /// Writes a withdrawal tombstone for consent enforcement.
+    ///
+    /// Overwrites the entry with `consent.ok = false`, empty partner IDs,
+    /// and a 24-hour TTL. Uses unconditional overwrite (no CAS) since the
+    /// entry is being withdrawn regardless of concurrent state.
+    ///
+    /// The tombstone allows batch sync clients (`POST /api/v1/sync`) to
+    /// distinguish `consent_withdrawn` from `ec_hash_not_found` for 24 hours.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store error. Callers on
+    /// the browser path should log at `error` level and continue — cookie
+    /// deletion is the primary enforcement mechanism.
+    pub fn write_withdrawal_tombstone(
+        &self,
+        ec_hash: &str,
+    ) -> Result<(), Report<TrustedServerError>> {
+        let store = self.open_store()?;
+        let entry = KvEntry::tombstone(current_timestamp());
+        let (body, meta_str) = Self::serialize_entry(&entry, &self.store_name)?;
+
+        store
+            .build_insert()
+            .metadata(&meta_str)
+            .time_to_live(TOMBSTONE_TTL)
+            .execute(ec_hash, body)
+            .change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!("Failed to write tombstone for key '{ec_hash}'"),
+            })
+    }
+
+    /// Hard-deletes the entry.
+    ///
+    /// Reserved for the IAB data deletion framework (deferred). For consent
+    /// withdrawal, use [`write_withdrawal_tombstone`](Self::write_withdrawal_tombstone).
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store error.
+    pub fn delete(&self, ec_hash: &str) -> Result<(), Report<TrustedServerError>> {
+        let store = self.open_store()?;
+        store
+            .delete(ec_hash)
+            .change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!("Failed to delete key '{ec_hash}'"),
+            })
+    }
+}
+
+/// Returns the current Unix timestamp in seconds.
+///
+/// Uses `std::time::SystemTime` which is supported on `wasm32-wasip1`.
+fn current_timestamp() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn constants_have_expected_values() {
+        assert_eq!(MAX_CAS_RETRIES, 3);
+        assert_eq!(LAST_SEEN_DEBOUNCE_SECS, 300);
+        assert_eq!(ENTRY_TTL, Duration::from_secs(31_536_000));
+        assert_eq!(TOMBSTONE_TTL, Duration::from_secs(86_400));
+    }
+
+    #[test]
+    fn current_timestamp_is_nonzero() {
+        let ts = current_timestamp();
+        assert!(ts > 0, "should return a nonzero timestamp");
+    }
+
+    #[test]
+    fn serialize_entry_produces_valid_json() {
+        let entry = KvEntry::tombstone(1000);
+        let (body, meta) =
+            KvIdentityGraph::serialize_entry(&entry, "test-store").expect("should serialize entry");
+
+        // Verify body is valid JSON.
+        let _: KvEntry =
+            serde_json::from_str(&body).expect("should deserialize body back to KvEntry");
+
+        // Verify metadata is valid JSON.
+        let _: KvMetadata =
+            serde_json::from_str(&meta).expect("should deserialize metadata back to KvMetadata");
+    }
+}
diff --git a/crates/trusted-server-core/src/ec/kv_types.rs b/crates/trusted-server-core/src/ec/kv_types.rs
new file mode 100644
index 00000000..fa0f256f
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/kv_types.rs
@@ -0,0 +1,386 @@
+//! KV identity graph schema types.
+//!
+//! These types define the JSON schema stored in the Fastly KV Store for the
+//! EC identity graph. Each EC hash (64-char hex prefix) maps to a [`KvEntry`]
+//! containing consent state, geo location, and accumulated partner IDs.
+//!
+//! The schema is versioned (`v: 1`) to allow future migrations.
+
+use std::collections::HashMap;
+
+use serde::{Deserialize, Serialize};
+
+use crate::consent::ConsentContext;
+use crate::geo::GeoInfo;
+
+/// Current schema version for KV entries.
+pub const SCHEMA_VERSION: u8 = 1;
+
+/// Full KV entry stored as the body of an EC identity graph record.
+///
+/// **KV key:** 64-character hex hash (the stable prefix from the EC ID).
+/// **KV value:** JSON-serialized `KvEntry` (max ~5KB).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct KvEntry {
+    /// Schema version — always [`SCHEMA_VERSION`].
+    pub v: u8,
+    /// Unix timestamp (seconds) of initial entry creation.
+    pub created: u64,
+    /// Unix timestamp (seconds) of last organic request.
+    /// Updated by [`super::kv::KvIdentityGraph::update_last_seen`] with
+    /// a 300-second debounce.
+    pub last_seen: u64,
+    /// Consent state sub-object.
+    pub consent: KvConsent,
+    /// Geo location sub-object.
+    pub geo: KvGeo,
+    /// Map of partner ID namespace → synced UID record.
+    /// Populated by pixel sync, batch sync, and pull sync operations.
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub ids: HashMap<String, KvPartnerId>,
+}
+
+/// Consent state within a KV entry.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct KvConsent {
+    /// Raw TCF v2 consent string.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tcf: Option<String>,
+    /// Raw GPP consent string.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gpp: Option<String>,
+    /// `true` for a live entry, `false` for a withdrawal tombstone.
+    pub ok: bool,
+    /// Unix timestamp (seconds) of last consent state change.
+    pub updated: u64,
+}
+
+/// Geo location within a KV entry.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct KvGeo {
+    /// ISO 3166-1 alpha-2 country code (e.g. `"US"`).
+    pub country: String,
+    /// ISO 3166-2 region code (e.g. `"CA"` for California).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub region: Option<String>,
+}
+
+/// A synced partner user ID within a KV entry.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct KvPartnerId {
+    /// The partner's user identifier.
+    pub uid: String,
+    /// Unix timestamp (seconds) when this UID was written/updated.
+    pub synced: u64,
+}
+
+/// Compact metadata stored alongside the KV entry body.
+///
+/// Fastly KV metadata is limited to 2048 bytes and can be read without
+/// streaming the full body. Used by batch sync for fast consent checks.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct KvMetadata {
+    /// Mirrors [`KvConsent::ok`] — `false` means tombstone.
+    pub ok: bool,
+    /// Mirrors [`KvGeo::country`].
+    pub country: String,
+    /// Mirrors [`KvEntry::v`].
+    pub v: u8,
+}
+
+impl KvEntry {
+    /// Creates a new live entry from the current request context.
+    #[must_use]
+    pub fn new(consent: &ConsentContext, geo: Option<&GeoInfo>, now: u64) -> Self {
+        Self {
+            v: SCHEMA_VERSION,
+            created: now,
+            last_seen: now,
+            consent: KvConsent {
+                tcf: consent.raw_tc_string.clone(),
+                gpp: consent.raw_gpp_string.clone(),
+                ok: true,
+                updated: now,
+            },
+            geo: KvGeo::from_geo_info(geo),
+            ids: HashMap::new(),
+        }
+    }
+
+    /// Creates a minimal live entry for the recovery path.
+    ///
+    /// Used by [`super::kv::KvIdentityGraph::upsert_partner_id`] when the
+    /// root KV entry is missing (e.g. the initial best-effort
+    /// `create_or_revive` failed on EC generation).
+    #[must_use]
+    pub fn minimal(partner_id: &str, uid: &str, synced: u64) -> Self {
+        let mut ids = HashMap::new();
+        ids.insert(
+            partner_id.to_owned(),
+            KvPartnerId {
+                uid: uid.to_owned(),
+                synced,
+            },
+        );
+        Self {
+            v: SCHEMA_VERSION,
+            created: synced,
+            last_seen: synced,
+            consent: KvConsent {
+                tcf: None,
+                gpp: None,
+                ok: true,
+                updated: synced,
+            },
+            geo: KvGeo {
+                country: "ZZ".to_owned(),
+                region: None,
+            },
+            ids,
+        }
+    }
+
+    /// Creates a withdrawal tombstone entry.
+    ///
+    /// Sets `consent.ok = false`, clears all partner IDs, and uses a
+    /// placeholder geo. The caller should apply a 24-hour TTL when writing.
+    ///
+    /// **Note:** The original `created` timestamp is intentionally not
+    /// preserved — reading the existing entry first would add latency on
+    /// the consent-withdrawal hot path, and the tombstone expires in 24h.
+    #[must_use]
+    pub fn tombstone(now: u64) -> Self {
+        Self {
+            v: SCHEMA_VERSION,
+            created: now,
+            last_seen: now,
+            consent: KvConsent {
+                tcf: None,
+                gpp: None,
+                ok: false,
+                updated: now,
+            },
+            geo: KvGeo {
+                country: "ZZ".to_owned(),
+                region: None,
+            },
+            ids: HashMap::new(),
+        }
+    }
+}
+
+impl KvMetadata {
+    /// Extracts metadata from a full entry.
+    #[must_use]
+    pub fn from_entry(entry: &KvEntry) -> Self {
+        Self {
+            ok: entry.consent.ok,
+            country: entry.geo.country.clone(),
+            v: entry.v,
+        }
+    }
+}
+
+impl KvGeo {
+    /// Creates a `KvGeo` from an optional [`GeoInfo`].
+    ///
+    /// Returns `country: "ZZ"` (unknown) when geo data is unavailable.
+    #[must_use]
+    pub fn from_geo_info(geo: Option<&GeoInfo>) -> Self {
+        match geo {
+            Some(info) => Self {
+                country: info.country.clone(),
+                region: info.region.clone(),
+            },
+            None => Self {
+                country: "ZZ".to_owned(),
+                region: None,
+            },
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample_consent_context() -> ConsentContext {
+        ConsentContext {
+            raw_tc_string: Some("CP_test_tc_string".to_owned()),
+            raw_gpp_string: Some("DBA_test_gpp".to_owned()),
+            ..ConsentContext::default()
+        }
+    }
+
+    fn sample_geo_info() -> GeoInfo {
+        GeoInfo {
+            city: "San Francisco".to_owned(),
+            country: "US".to_owned(),
+            continent: "NorthAmerica".to_owned(),
+            latitude: 37.7749,
+            longitude: -122.4194,
+            metro_code: 807,
+            region: Some("CA".to_owned()),
+        }
+    }
+
+    #[test]
+    fn entry_serialization_roundtrip() {
+        let geo = sample_geo_info();
+        let consent = sample_consent_context();
+        let mut entry = KvEntry::new(&consent, Some(&geo), 1741824000);
+        entry.ids.insert(
+            "liveramp".to_owned(),
+            KvPartnerId {
+                uid: "LR_xyz".to_owned(),
+                synced: 1741890000,
+            },
+        );
+
+        let json = serde_json::to_string(&entry).expect("should serialize KvEntry");
+        let deserialized: KvEntry =
+            serde_json::from_str(&json).expect("should deserialize KvEntry");
+
+        assert_eq!(deserialized.v, SCHEMA_VERSION);
+        assert_eq!(deserialized.created, 1741824000);
+        assert_eq!(
+            deserialized.consent.tcf.as_deref(),
+            Some("CP_test_tc_string")
+        );
+        assert_eq!(deserialized.consent.gpp.as_deref(), Some("DBA_test_gpp"));
+        assert!(deserialized.consent.ok, "should be a live entry");
+        assert_eq!(deserialized.geo.country, "US");
+        assert_eq!(deserialized.geo.region.as_deref(), Some("CA"));
+        assert_eq!(
+            deserialized.ids.get("liveramp").map(|p| p.uid.as_str()),
+            Some("LR_xyz"),
+        );
+    }
+
+    #[test]
+    fn metadata_serialization_roundtrip() {
+        let meta = KvMetadata {
+            ok: true,
+            country: "US".to_owned(),
+            v: 1,
+        };
+
+        let json = serde_json::to_string(&meta).expect("should serialize KvMetadata");
+        let deserialized: KvMetadata =
+            serde_json::from_str(&json).expect("should deserialize KvMetadata");
+
+        assert!(deserialized.ok, "should be ok=true");
+        assert_eq!(deserialized.country, "US");
+        assert_eq!(deserialized.v, 1);
+    }
+
+    #[test]
+    fn metadata_fits_in_2048_bytes() {
+        // Worst case: long country code (though ISO 3166-1 is always 2 chars)
+        let meta = KvMetadata {
+            ok: false,
+            country: "XX".to_owned(),
+            v: SCHEMA_VERSION,
+        };
+        let json = serde_json::to_string(&meta).expect("should serialize KvMetadata");
+        assert!(
+            json.len() <= 2048,
+            "metadata must fit in Fastly's 2048-byte limit, got {} bytes",
+            json.len()
+        );
+    }
+
+    #[test]
+    fn new_entry_has_correct_initial_state() {
+        let consent = sample_consent_context();
+        let geo = sample_geo_info();
+        let entry = KvEntry::new(&consent, Some(&geo), 1000);
+
+        assert_eq!(entry.v, SCHEMA_VERSION);
+        assert_eq!(entry.created, 1000);
+        assert_eq!(entry.last_seen, 1000);
+        assert!(entry.consent.ok, "should be a live entry");
+        assert_eq!(entry.consent.updated, 1000);
+        assert_eq!(entry.geo.country, "US");
+        assert!(entry.ids.is_empty(), "should have no partner IDs initially");
+    }
+
+    #[test]
+    fn new_entry_without_geo_uses_zz() {
+        let consent = ConsentContext::default();
+        let entry = KvEntry::new(&consent, None, 1000);
+        assert_eq!(
+            entry.geo.country, "ZZ",
+            "should use ZZ when geo is unavailable"
+        );
+        assert!(entry.geo.region.is_none());
+    }
+
+    #[test]
+    fn minimal_entry_has_partner_id_and_placeholder_geo() {
+        let entry = KvEntry::minimal("ssp_x", "abc123", 1741824000);
+
+        assert_eq!(entry.v, SCHEMA_VERSION);
+        assert!(entry.consent.ok, "should be a live entry");
+        assert_eq!(entry.geo.country, "ZZ");
+        assert_eq!(entry.ids.len(), 1);
+        let partner = entry.ids.get("ssp_x").expect("should have ssp_x entry");
+        assert_eq!(partner.uid, "abc123");
+        assert_eq!(partner.synced, 1741824000);
+    }
+
+    #[test]
+    fn tombstone_entry_has_correct_shape() {
+        let entry = KvEntry::tombstone(1741910400);
+
+        assert_eq!(entry.v, SCHEMA_VERSION);
+        assert!(!entry.consent.ok, "should be a tombstone");
+        assert!(entry.ids.is_empty(), "tombstone should have no partner IDs");
+        assert_eq!(entry.geo.country, "ZZ");
+        assert_eq!(entry.consent.updated, 1741910400);
+    }
+
+    #[test]
+    fn metadata_from_entry_mirrors_fields() {
+        let consent = sample_consent_context();
+        let geo = sample_geo_info();
+        let entry = KvEntry::new(&consent, Some(&geo), 1000);
+        let meta = KvMetadata::from_entry(&entry);
+
+        assert_eq!(meta.ok, entry.consent.ok);
+        assert_eq!(meta.country, entry.geo.country);
+        assert_eq!(meta.v, entry.v);
+    }
+
+    #[test]
+    fn tombstone_metadata_has_ok_false() {
+        let entry = KvEntry::tombstone(1000);
+        let meta = KvMetadata::from_entry(&entry);
+
+        assert!(!meta.ok, "tombstone metadata should have ok=false");
+    }
+
+    #[test]
+    fn empty_ids_omitted_from_json() {
+        let entry = KvEntry::tombstone(1000);
+        let json = serde_json::to_string(&entry).expect("should serialize");
+        assert!(
+            !json.contains("\"ids\""),
+            "empty ids should be omitted from JSON, got: {json}"
+        );
+    }
+
+    #[test]
+    fn none_consent_fields_omitted_from_json() {
+        let entry = KvEntry::tombstone(1000);
+        let json = serde_json::to_string(&entry).expect("should serialize");
+        assert!(
+            !json.contains("\"tcf\""),
+            "None tcf should be omitted from JSON"
+        );
+        assert!(
+            !json.contains("\"gpp\""),
+            "None gpp should be omitted from JSON"
+        );
+    }
+}
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index 6f53b12e..97116239 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -16,10 +16,14 @@
 //! - [`generation`] — HMAC-based ID generation, IP normalization, format helpers
 //! - [`consent`] — EC-specific consent gating wrapper
 //! - [`cookies`] — `Set-Cookie` header creation and expiration helpers
+//! - [`kv`] — KV Store identity graph operations (CAS, tombstones, debounce)
+//! - [`kv_types`] — Schema types for KV identity graph entries
 
 pub mod consent;
 pub mod cookies;
 pub mod generation;
+pub mod kv;
+pub mod kv_types;
 
 use cookie::CookieJar;
 use error_stack::Report;
@@ -32,7 +36,7 @@ use crate::error::TrustedServerError;
 use crate::geo::GeoInfo;
 use crate::settings::Settings;
 
-pub use generation::{ec_hash, extract_client_ip, generate_ec_id, is_valid_ec_id};
+pub use generation::{ec_hash, generate_ec_id, is_valid_ec_id};
 
 /// Parsed EC identity from an incoming request.
 ///
@@ -92,36 +96,6 @@ pub fn get_ec_id(req: &fastly::Request) -> Result<Option<String>, Report<Trusted
     Ok(ec_id)
 }
 
-/// Gets an existing EC ID from the request, or generates a new one.
-///
-/// This is a convenience wrapper that combines [`get_ec_id`] with
-/// [`generation::generate_ec_id`]. It extracts the client IP from the
-/// request for generation when no existing ID is found.
-///
-/// When the client IP is unavailable (e.g. in local testing environments),
-/// falls back to `"unknown"` — all such requests share the same HMAC
-/// base, but the random suffix still provides uniqueness.
-///
-/// # Errors
-///
-/// - [`TrustedServerError::InvalidHeaderValue`] if cookie parsing fails
-/// - [`TrustedServerError::Ec`] if HMAC generation fails
-pub fn get_or_generate_ec_id(
-    settings: &Settings,
-    req: &Request,
-) -> Result<String, Report<TrustedServerError>> {
-    if let Some(id) = get_ec_id(req)? {
-        return Ok(id);
-    }
-
-    // Fallback to "unknown" when client IP is unavailable (e.g. local testing).
-    // All such requests share the same HMAC base; the random suffix provides uniqueness.
-    let client_ip = extract_client_ip(req).unwrap_or_else(|_| "unknown".to_string());
-    let ec_id = generate_ec_id(settings, &client_ip)?;
-    log::trace!("No existing EC ID, generated: {ec_id}");
-    Ok(ec_id)
-}
-
 /// Captures the EC state for a single request lifecycle.
 ///
 /// Created via [`read_from_request`](Self::read_from_request) during
diff --git a/crates/trusted-server-core/src/integrations/prebid.rs b/crates/trusted-server-core/src/integrations/prebid.rs
index 8acca812..80700a69 100644
--- a/crates/trusted-server-core/src/integrations/prebid.rs
+++ b/crates/trusted-server-core/src/integrations/prebid.rs
@@ -3,11 +3,12 @@ use std::sync::Arc;
 use std::time::Duration;
 
 use async_trait::async_trait;
+use base64::{engine::general_purpose::STANDARD as BASE64, Engine};
 use error_stack::{Report, ResultExt};
 use fastly::http::{header, Method, StatusCode, Url};
 use fastly::{Request, Response};
 use serde::{Deserialize, Serialize};
-use serde_json::Value as Json;
+use serde_json::{json, Value as Json};
 use validator::Validate;
 
 use crate::auction::provider::AuctionProvider;
@@ -418,6 +419,88 @@ fn expand_trusted_server_bidders(
         })
         .collect()
 }
+fn transform_prebid_response(
+    response: &mut Json,
+    request_host: &str,
+    request_scheme: &str,
+) -> Result<(), Report<TrustedServerError>> {
+    if let Some(seatbids) = response["seatbid"].as_array_mut() {
+        for seatbid in seatbids {
+            if let Some(bids) = seatbid["bid"].as_array_mut() {
+                for bid in bids {
+                    if let Some(adm) = bid["adm"].as_str() {
+                        bid["adm"] = json!(rewrite_ad_markup(adm, request_host, request_scheme));
+                    }
+
+                    if let Some(nurl) = bid["nurl"].as_str() {
+                        bid["nurl"] = json!(make_first_party_proxy_url(
+                            nurl,
+                            request_host,
+                            request_scheme,
+                            "track"
+                        ));
+                    }
+
+                    if let Some(burl) = bid["burl"].as_str() {
+                        bid["burl"] = json!(make_first_party_proxy_url(
+                            burl,
+                            request_host,
+                            request_scheme,
+                            "track"
+                        ));
+                    }
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
+
+fn rewrite_ad_markup(markup: &str, request_host: &str, request_scheme: &str) -> String {
+    let mut content = markup.to_string();
+    let cdn_patterns = [
+        ("https://cdn.adsrvr.org", "adsrvr"),
+        ("https://ib.adnxs.com", "adnxs"),
+        ("https://rtb.openx.net", "openx"),
+        ("https://as.casalemedia.com", "casale"),
+        ("https://eus.rubiconproject.com", "rubicon"),
+    ];
+
+    for (cdn_url, cdn_name) in cdn_patterns {
+        if content.contains(cdn_url) {
+            let proxy_base = format!(
+                "{}://{}/ad-proxy/{}",
+                request_scheme, request_host, cdn_name
+            );
+            content = content.replace(cdn_url, &proxy_base);
+        }
+    }
+
+    content = content.replace(
+        "//cdn.adsrvr.org",
+        &format!("//{}/ad-proxy/adsrvr", request_host),
+    );
+    content = content.replace(
+        "//ib.adnxs.com",
+        &format!("//{}/ad-proxy/adnxs", request_host),
+    );
+    content
+}
+
+fn make_first_party_proxy_url(
+    third_party_url: &str,
+    request_host: &str,
+    request_scheme: &str,
+    proxy_type: &str,
+) -> String {
+    let encoded = BASE64.encode(third_party_url.as_bytes());
+    format!(
+        "{}://{}/ad-proxy/{}/{}",
+        request_scheme, request_host, proxy_type, encoded
+    )
+}
+
 /// Copies browser headers to the outgoing Prebid Server request.
 ///
 /// In [`ConsentForwardingMode::OpenrtbOnly`] mode, consent cookies are
@@ -1107,7 +1190,7 @@ impl AuctionProvider for PrebidAuctionProvider {
             return Ok(AuctionResponse::error("prebid", response_time_ms));
         }
 
-        let response_json: Json =
+        let mut response_json: Json =
             serde_json::from_slice(&body_bytes).change_context(TrustedServerError::Prebid {
                 message: "Failed to parse Prebid response".to_string(),
             })?;
@@ -1123,6 +1206,27 @@ impl AuctionProvider for PrebidAuctionProvider {
             }
         }
 
+        let request_host = response_json
+            .get("ext")
+            .and_then(|ext| ext.get("trusted_server"))
+            .and_then(|trusted_server| trusted_server.get("request_host"))
+            .and_then(|value| value.as_str())
+            .unwrap_or("")
+            .to_string();
+        let request_scheme = response_json
+            .get("ext")
+            .and_then(|ext| ext.get("trusted_server"))
+            .and_then(|trusted_server| trusted_server.get("request_scheme"))
+            .and_then(|value| value.as_str())
+            .unwrap_or("https")
+            .to_string();
+
+        if request_host.is_empty() {
+            log::warn!("Prebid response missing request host; skipping URL rewrites");
+        } else {
+            transform_prebid_response(&mut response_json, &request_host, &request_scheme)?;
+        }
+
         let mut auction_response = self.parse_openrtb_response(&response_json, response_time_ms);
         self.enrich_response_metadata(&response_json, &mut auction_response);
 
@@ -1470,6 +1574,62 @@ passphrase = "test-secret-key"
         );
     }
 
+    #[test]
+    fn transform_prebid_response_rewrites_creatives_and_tracking() {
+        let mut response = json!({
+            "seatbid": [{
+                "bid": [{
+                    "adm": r#"<img src="https://cdn.adsrvr.org/pixel.png">"#,
+                    "nurl": "https://notify.example/win",
+                    "burl": "https://notify.example/bill"
+                }]
+            }]
+        });
+
+        transform_prebid_response(&mut response, "pub.example", "https")
+            .expect("should rewrite response");
+
+        let rewritten_adm = response["seatbid"][0]["bid"][0]["adm"]
+            .as_str()
+            .expect("adm should be string");
+        assert!(
+            rewritten_adm.contains("/ad-proxy/adsrvr"),
+            "creative markup should proxy CDN urls"
+        );
+
+        for url_field in ["nurl", "burl"] {
+            let value = response["seatbid"][0]["bid"][0][url_field]
+                .as_str()
+                .expect("should get tracking URL");
+            assert!(
+                value.contains("/ad-proxy/track/"),
+                "tracking URLs should be proxied"
+            );
+        }
+    }
+
+    #[test]
+    fn make_first_party_proxy_url_base64_encodes_target() {
+        let url = "https://cdn.example/path?x=1";
+        let rewritten = make_first_party_proxy_url(url, "pub.example", "https", "track");
+        assert!(
+            rewritten.starts_with("https://pub.example/ad-proxy/track/"),
+            "proxy prefix should be applied"
+        );
+
+        let encoded = rewritten
+            .split("/ad-proxy/track/")
+            .nth(1)
+            .expect("should have encoded payload after proxy prefix");
+        let decoded = BASE64
+            .decode(encoded.as_bytes())
+            .expect("should decode base64 proxy payload");
+        assert_eq!(
+            String::from_utf8(decoded).expect("should be valid UTF-8"),
+            url
+        );
+    }
+
     #[test]
     fn matches_script_url_matches_common_variants() {
         let integration = PrebidIntegration::new(base_config());
diff --git a/crates/trusted-server-core/src/integrations/registry.rs b/crates/trusted-server-core/src/integrations/registry.rs
index cd82c5ef..9ef94264 100644
--- a/crates/trusted-server-core/src/integrations/registry.rs
+++ b/crates/trusted-server-core/src/integrations/registry.rs
@@ -9,8 +9,8 @@ use fastly::{Request, Response};
 use matchit::Router;
 
 use crate::constants::HEADER_X_TS_EC;
-use crate::cookies::set_ec_cookie;
-use crate::ec::get_or_generate_ec_id;
+use crate::ec::cookies::{expire_ec_cookie, set_ec_cookie};
+use crate::ec::EcContext;
 use crate::error::TrustedServerError;
 use crate::settings::Settings;
 
@@ -655,33 +655,46 @@ impl IntegrationRegistry {
         mut req: Request,
     ) -> Option<Result<Response, Report<TrustedServerError>>> {
         if let Some((proxy, _)) = self.find_route(method, path) {
-            // Generate EC ID before consuming request
-            let ec_id_result = get_or_generate_ec_id(settings, &req);
+            // Read EC state and generate if needed before consuming request.
+            let ec_context = match EcContext::read_from_request(settings, &req) {
+                Ok(mut ec) => {
+                    if let Err(err) = ec.generate_if_needed(settings) {
+                        log::warn!("EC generation failed for integration proxy: {err:?}");
+                    }
+                    Some(ec)
+                }
+                Err(err) => {
+                    log::warn!("Failed to read EC context for integration proxy: {err:?}");
+                    None
+                }
+            };
 
             // Set EC ID header on the request so integrations can read it.
-            // Header injection: Fastly's HeaderValue API rejects values containing \r, \n, or \0,
-            // so a crafted EC ID cannot inject additional request headers.
-            if let Ok(ref ec_id) = ec_id_result {
-                req.set_header(HEADER_X_TS_EC, ec_id.as_str());
+            if let Some(ec_id) = ec_context.as_ref().and_then(|ec| ec.ec_value()) {
+                req.set_header(HEADER_X_TS_EC, ec_id);
             }
 
             let mut result = proxy.handle(settings, req).await;
 
-            // Set EC ID header on successful responses
+            // Consent-gated EC on successful responses:
+            // - Consent given → set header + cookie.
+            // - Consent denied + existing cookie → expire cookie (revoke).
+            // - Otherwise → set header only (for internal use).
             if let Ok(ref mut response) = result {
-                match ec_id_result {
-                    Ok(ref ec_id) => {
-                        // Response-header injection: Fastly's HeaderValue API rejects values
-                        // containing \r, \n, or \0, so a crafted EC ID cannot inject
-                        // additional response headers.
-                        response.set_header(HEADER_X_TS_EC, ec_id.as_str());
-                        // Cookie is intentionally not set when EC ID contains RFC 6265-illegal
-                        // characters (e.g. a crafted x-ts-ec header value). The response header
-                        // is still emitted; only cookie persistence is skipped.
-                        set_ec_cookie(settings, response, ec_id.as_str());
+                if let Some(ref ec) = ec_context {
+                    if let Some(ec_id) = ec.ec_value() {
+                        response.set_header(HEADER_X_TS_EC, ec_id);
+                        if ec.ec_allowed() {
+                            set_ec_cookie(settings, response, ec_id);
+                        }
                     }
-                    Err(ref err) => {
-                        log::warn!("Failed to generate EC ID for integration response: {err:?}");
+                    if !ec.ec_allowed() {
+                        if let Some(cookie_ec_id) = ec.existing_cookie_ec_id() {
+                            log::info!(
+                                "EC revoked for '{cookie_ec_id}': consent withdrawn on integration proxy"
+                            );
+                            expire_ec_cookie(settings, response);
+                        }
                     }
                 }
             }
@@ -1212,7 +1225,6 @@ mod tests {
     }
 
     // Tests for EC ID header on proxy responses
-    use crate::constants::COOKIE_TS_EC;
     use crate::test_support::tests::create_test_settings;
     use fastly::http::header;
 
@@ -1262,8 +1274,10 @@ mod tests {
         )];
         let registry = IntegrationRegistry::from_routes(routes);
 
-        // Create a request without an EC ID cookie
-        let req = Request::get("https://test-publisher.com/integrations/test/ec");
+        // Provide an existing EC via header (client IP is unavailable in
+        // the test environment, so generation would fail).
+        let mut req = Request::get("https://test-publisher.com/integrations/test/ec");
+        req.set_header("x-ts-ec", "test-ec-id-from-header");
 
         // Call handle_proxy (uses futures executor in test environment)
         let result = futures::executor::block_on(registry.handle_proxy(
@@ -1274,35 +1288,29 @@ mod tests {
         ));
 
         // Should have matched and returned a response
-        assert!(result.is_some(), "Should find route and handle request");
+        assert!(result.is_some(), "should find route and handle request");
         let response = result.unwrap();
-        assert!(response.is_ok(), "Handler should succeed");
+        assert!(response.is_ok(), "handler should succeed");
 
         let response = response.unwrap();
 
-        // Verify x-ts-ec header is present
+        // The x-ts-ec header is always set for internal use by downstream
+        // integrations, regardless of consent.
         assert!(
             response.get_header(HEADER_X_TS_EC).is_some(),
-            "Response should have x-ts-ec header"
+            "should have x-ts-ec header on response"
         );
 
-        // Verify Set-Cookie header is present (since no cookie was in request)
-        let set_cookie = response.get_header(header::SET_COOKIE);
+        // Without geo data, jurisdiction is Unknown → consent denied
+        // (fail-closed). The Set-Cookie header should not be set.
         assert!(
-            set_cookie.is_some(),
-            "Response should have Set-Cookie header for ts-ec"
-        );
-
-        let cookie_value = set_cookie.unwrap().to_str().unwrap();
-        assert!(
-            cookie_value.contains(COOKIE_TS_EC),
-            "Set-Cookie should contain ts-ec cookie, got: {}",
-            cookie_value
+            response.get_header(header::SET_COOKIE).is_none(),
+            "should not set Set-Cookie when consent is denied"
         );
     }
 
     #[test]
-    fn handle_proxy_always_sets_cookie() {
+    fn handle_proxy_skips_cookie_when_consent_denied() {
         let settings = create_test_settings();
         let routes = vec![(
             Method::GET,
@@ -1313,7 +1321,7 @@ mod tests {
         let registry = IntegrationRegistry::from_routes(routes);
 
         let mut req = Request::get("https://test.example.com/integrations/test/ec");
-        // Pre-existing cookie
+        // Pre-existing cookie, but no geo data → Unknown jurisdiction → consent denied.
         req.set_header(header::COOKIE, "ts-ec=existing_id_12345");
 
         let result = futures::executor::block_on(registry.handle_proxy(
@@ -1326,28 +1334,22 @@ mod tests {
 
         let response = result.expect("proxy handle should succeed");
 
-        // Should still have x-ts-ec header
+        // The x-ts-ec header is always set (for internal use by integrations).
         assert!(
             response.get_header(HEADER_X_TS_EC).is_some(),
-            "Response should still have x-ts-ec header"
+            "should still have x-ts-ec header for internal use"
         );
 
-        // Should ALWAYS set the cookie again (per new requirements)
-        let set_cookie = response.get_header(header::SET_COOKIE);
-
+        // Without geo data, jurisdiction is Unknown and consent is denied
+        // (fail-closed). An existing cookie should be expired (revoked).
+        let set_cookie = response
+            .get_header(header::SET_COOKIE)
+            .expect("should have Set-Cookie header to expire the existing cookie");
+        let cookie_str = set_cookie.to_str().expect("should be valid UTF-8");
         assert!(
-            set_cookie.is_some(),
-            "Should set Set-Cookie header even if cookie is present"
+            cookie_str.contains("Max-Age=0"),
+            "should expire the EC cookie when consent is denied, got: {cookie_str}"
         );
-
-        if let Some(cookie) = set_cookie {
-            let cookie_str = cookie.to_str().unwrap_or("");
-            assert!(
-                cookie_str.contains(COOKIE_TS_EC),
-                "Should contain ts-ec cookie, got: {}",
-                cookie_str
-            );
-        }
     }
 
     #[test]
@@ -1363,8 +1365,9 @@ mod tests {
         )];
         let registry = IntegrationRegistry::from_routes(routes);
 
-        let req =
+        let mut req =
             Request::post("https://test-publisher.com/integrations/test/ec").with_body("test body");
+        req.set_header("x-ts-ec", "test-ec-id-from-header");
 
         let result = futures::executor::block_on(registry.handle_proxy(
             &Method::POST,
diff --git a/crates/trusted-server-core/src/publisher.rs b/crates/trusted-server-core/src/publisher.rs
index 2e2568f6..e2d724cf 100644
--- a/crates/trusted-server-core/src/publisher.rs
+++ b/crates/trusted-server-core/src/publisher.rs
@@ -3,10 +3,9 @@ use fastly::http::{header, StatusCode};
 use fastly::{Body, Request, Response};
 
 use crate::backend::BackendConfig;
-use crate::consent::{allows_ec_creation, build_consent_context, ConsentPipelineInput};
-use crate::constants::{COOKIE_TS_EC, HEADER_X_COMPRESS_HINT, HEADER_X_TS_EC};
-use crate::cookies::{expire_ec_cookie, handle_request_cookies, set_ec_cookie};
-use crate::ec::get_or_generate_ec_id;
+use crate::constants::{HEADER_X_COMPRESS_HINT, HEADER_X_TS_EC};
+use crate::ec::cookies::{expire_ec_cookie, set_ec_cookie};
+use crate::ec::EcContext;
 use crate::error::TrustedServerError;
 use crate::http_util::{serve_static_with_etag, RequestInfo};
 use crate::integrations::IntegrationRegistry;
@@ -312,43 +311,21 @@ pub fn handle_publisher_request(
         req.get_header("x-forwarded-proto"),
     );
 
-    // Parse cookies once for reuse by both consent extraction and EC ID logic.
-    let cookie_jar = handle_request_cookies(&req)?;
-
-    // Capture the current EC cookie value for revocation handling.
-    // This must come from the cookie itself (not the x-ts-ec header)
-    // to ensure KV deletion targets the same identifier being revoked.
-    let existing_ec_cookie = cookie_jar
-        .as_ref()
-        .and_then(|jar| jar.get(COOKIE_TS_EC))
-        .map(|cookie| cookie.value().to_owned());
-
-    // Generate EC identifiers before the request body is consumed.
-    // Always generated for internal use (KV lookups, logging) even when
-    // consent is absent — the cookie is only *set* when consent allows it.
-    let ec_id = get_or_generate_ec_id(settings, &req)?;
-
-    // Extract, decode, and log consent signals (TCF, GPP, US Privacy, GPC)
-    // from the incoming request. The ConsentContext carries both raw strings
-    // (for OpenRTB forwarding) and decoded data (for enforcement).
-    // When a consent_store is configured, this also persists consent to KV
-    // and falls back to stored consent when cookies are absent.
-    #[allow(deprecated)]
-    let geo = crate::geo::GeoInfo::from_request(&req);
-    let consent_context = build_consent_context(&ConsentPipelineInput {
-        jar: cookie_jar.as_ref(),
-        req: &req,
-        config: &settings.consent,
-        geo: geo.as_ref(),
-        ec_id: Some(ec_id.as_str()),
-        kv_store: settings
-            .consent
-            .consent_store
-            .as_deref()
-            .map(|_| services.kv_store()),
-    });
-    let ec_allowed = allows_ec_creation(&consent_context);
-    log::debug!("Proxy EC ID: {}, ec_allowed: {}", ec_id, ec_allowed,);
+    // Read EC state from the request (existing ID, consent, client IP).
+    // This must happen before the request body is consumed.
+    let mut ec_context = EcContext::read_from_request(settings, &req)?;
+
+    // Generate a new EC ID if none exists and consent allows it.
+    // This is an organic handler, so generation is permitted here.
+    if let Err(err) = ec_context.generate_if_needed(settings) {
+        log::warn!("EC generation failed: {err:?}");
+    }
+
+    let ec_allowed = ec_context.ec_allowed();
+    log::debug!(
+        "Proxy EC ID: {:?}, ec_allowed: {ec_allowed}",
+        ec_context.ec_value(),
+    );
 
     let backend_name = BackendConfig::from_url(
         &settings.publisher.origin_url,
@@ -451,17 +428,14 @@ pub fn handle_publisher_request(
     // - Consent absent + existing cookie → revoke (expire cookie + delete KV entry).
     // - Consent absent + no cookie → do nothing.
     if ec_allowed {
-        // Fastly's HeaderValue API rejects \r, \n, and \0, so the EC ID
-        // cannot inject additional response headers.
-        response.set_header(HEADER_X_TS_EC, ec_id.as_str());
-        // Cookie persistence is skipped if the EC ID contains RFC 6265-illegal
-        // characters. The header is still emitted when consent allows it.
-        set_ec_cookie(settings, &mut response, ec_id.as_str());
-    } else if let Some(cookie_ec_id) = existing_ec_cookie.as_deref() {
+        if let Some(ec_id) = ec_context.ec_value() {
+            response.set_header(HEADER_X_TS_EC, ec_id);
+            set_ec_cookie(settings, &mut response, ec_id);
+        }
+    } else if let Some(cookie_ec_id) = ec_context.existing_cookie_ec_id() {
         log::info!(
-            "EC revoked for '{}': consent withdrawn (jurisdiction={})",
-            cookie_ec_id,
-            consent_context.jurisdiction,
+            "EC revoked for '{cookie_ec_id}': consent withdrawn (jurisdiction={})",
+            ec_context.consent().jurisdiction,
         );
         expire_ec_cookie(settings, &mut response);
         if settings.consent.consent_store.is_some() {
@@ -470,7 +444,7 @@ pub fn handle_publisher_request(
     } else {
         log::debug!(
             "EC skipped: no consent and no existing cookie (jurisdiction={})",
-            consent_context.jurisdiction,
+            ec_context.consent().jurisdiction,
         );
     }
 
@@ -673,22 +647,22 @@ mod tests {
         req.set_header("x-ts-ec", "header_id");
         req.set_header("cookie", "ts-ec=cookie_id; other=value");
 
-        let cookie_jar = handle_request_cookies(&req).expect("should parse cookies");
-        let existing_ec_cookie = cookie_jar
-            .as_ref()
-            .and_then(|jar| jar.get(COOKIE_TS_EC))
-            .map(|cookie| cookie.value().to_owned());
-
-        let resolved_ec_id = get_or_generate_ec_id(&settings, &req).expect("should resolve EC ID");
+        let ec_context =
+            EcContext::read_from_request(&settings, &req).expect("should read EC context");
 
         assert_eq!(
-            existing_ec_cookie.as_deref(),
-            Some("cookie_id"),
-            "should read revocation target from cookie value"
+            ec_context.ec_value(),
+            Some("header_id"),
+            "should resolve request EC ID from header precedence"
+        );
+        assert!(
+            ec_context.cookie_was_present(),
+            "should detect cookie was present"
         );
         assert_eq!(
-            resolved_ec_id, "header_id",
-            "should still resolve request EC ID from header precedence"
+            ec_context.existing_cookie_ec_id(),
+            Some("cookie_id"),
+            "should return cookie EC value for revocation, not the header value"
         );
     }
 
diff --git a/crates/trusted-server-core/src/settings.rs b/crates/trusted-server-core/src/settings.rs
index 9b19e1c2..8ea9088a 100644
--- a/crates/trusted-server-core/src/settings.rs
+++ b/crates/trusted-server-core/src/settings.rs
@@ -20,7 +20,8 @@ pub const ENVIRONMENT_VARIABLE_SEPARATOR: &str = "__";
 #[derive(Debug, Default, Clone, Deserialize, Serialize, Validate)]
 pub struct Publisher {
     pub domain: String,
-    #[validate(custom(function = validate_cookie_domain))]
+    /// Domain for non-EC cookies. EC cookies use a separate computed domain
+    /// (see [`ec_cookie_domain`](Self::ec_cookie_domain)).
     pub cookie_domain: String,
     #[validate(custom(function = validate_no_trailing_slash))]
     pub origin_url: String,
@@ -34,6 +35,17 @@ impl Publisher {
     /// Known placeholder values that must not be used in production.
     pub const PROXY_SECRET_PLACEHOLDERS: &[&str] = &["change-me-proxy-secret", "proxy-secret"];
 
+    /// Returns the EC cookie domain, computed as `.{domain}`.
+    ///
+    /// Per spec §5.2, EC cookies derive their domain from
+    /// `publisher.domain` — **not** from `publisher.cookie_domain`.
+    /// This ensures the EC cookie is always scoped to the publisher's
+    /// apex domain regardless of how `cookie_domain` is configured.
+    #[must_use]
+    pub fn ec_cookie_domain(&self) -> String {
+        format!(".{}", self.domain)
+    }
+
     /// Returns `true` if `proxy_secret` matches a known placeholder value
     /// (case-insensitive).
     #[must_use]
@@ -58,16 +70,6 @@ impl Publisher {
     /// };
     /// assert_eq!(publisher.origin_host(), "origin.example.com:8080");
     /// ```
-    /// Returns the domain to use for the EC `Set-Cookie` header.
-    ///
-    /// Per spec §5.2, the EC cookie domain is `.{publisher.domain}` so
-    /// that the cookie is available on all subdomains of the publisher's
-    /// apex domain.
-    #[must_use]
-    pub fn ec_cookie_domain(&self) -> String {
-        format!(".{}", self.domain)
-    }
-
     #[allow(dead_code)]
     #[must_use]
     pub fn origin_host(&self) -> String {
@@ -629,18 +631,6 @@ impl Settings {
     }
 }
 
-fn validate_cookie_domain(value: &str) -> Result<(), ValidationError> {
-    // `=` is excluded: it only has special meaning in the name=value pair,
-    // not within the Domain attribute value.
-    if value.contains([';', '\n', '\r']) {
-        let mut err = ValidationError::new("cookie_metacharacters");
-        err.message =
-            Some("cookie_domain must not contain cookie metacharacters (;, \\n, \\r)".into());
-        return Err(err);
-    }
-    Ok(())
-}
-
 fn validate_no_trailing_slash(value: &str) -> Result<(), ValidationError> {
     if value.ends_with('/') {
         let mut err = ValidationError::new("trailing_slash");
@@ -832,6 +822,11 @@ mod tests {
         );
         assert_eq!(settings.publisher.domain, "test-publisher.com");
         assert_eq!(settings.publisher.cookie_domain, ".test-publisher.com");
+        assert_eq!(
+            settings.publisher.ec_cookie_domain(),
+            ".test-publisher.com",
+            "EC cookie domain should be computed as .{{domain}}"
+        );
         assert_eq!(
             settings.publisher.origin_url,
             "https://origin.test-publisher.com"
@@ -1675,6 +1670,7 @@ mod tests {
         );
     }
 
+<<<<<<< HEAD
     // --- Proxy::normalize ---
 
     #[test]
diff --git a/docs/guide/testing.md b/docs/guide/testing.md
index 42eec03e..fb12ac77 100644
--- a/docs/guide/testing.md
+++ b/docs/guide/testing.md
@@ -323,7 +323,6 @@ k6 run load-test.js
 5. **Use test helpers** - `create_test_settings()`, `create_test_request()`
 6. **Assert specific values** - Not just `assert!(result.is_ok())`
 
-
 ## Next Steps
 
 - Review [Architecture](/guide/architecture) for system design
diff --git a/fastly.toml b/fastly.toml
index 9d6c0f26..28961877 100644
--- a/fastly.toml
+++ b/fastly.toml
@@ -23,6 +23,14 @@ build = """
     [local_server.backends]
 
     [local_server.kv_stores]
+        [[local_server.kv_stores.counter_store]]
+            key = "placeholder"
+            data = "placeholder"
+
+        [[local_server.kv_stores.opid_store]]
+            key = "placeholder"
+            data = "placeholder"
+
         [[local_server.kv_stores.creative_store]]
             key = "placeholder"
             data = "placeholder"
@@ -30,6 +38,14 @@ build = """
         [[local_server.kv_stores.consent_store]]
             key = "placeholder"
             data = "placeholder"
+
+        [[local_server.kv_stores.ec_identity_store]]
+            key = "placeholder"
+            data = "placeholder"
+
+        [[local_server.kv_stores.ec_partner_store]]
+            key = "placeholder"
+            data = "placeholder"
     [local_server.secret_stores]
         [[local_server.secret_stores.signing_keys]]
             key = "ts-2025-10-A"
diff --git a/trusted-server.toml b/trusted-server.toml
index dbee4746..bf0cf199 100644
--- a/trusted-server.toml
+++ b/trusted-server.toml
@@ -16,6 +16,8 @@ proxy_secret = "change-me-proxy-secret"
 
 [ec]
 passphrase = "trusted-server"
+ec_store = "ec_identity_store"
+partner_store = "ec_partner_store"
 
 # Custom headers to be included in every response
 # Allows publishers to include tags such as X-Robots-Tag: noindex

From db93ed4f453b9e7059c3a1ef39ef9f7374776198 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Wed, 25 Mar 2026 18:58:10 -0500
Subject: [PATCH 05/36] Add partner registry and admin registration endpoint

Implement Story 4 (#537): partner KV store with API key hashing,
POST /admin/partners/register with basic-auth protection, strict
field validation (ID format, URL allowlists, domain normalization),
and pull-sync config validation. Includes index-based API key lookup
and comprehensive unit tests.
---
 Cargo.lock                                    |   1 +
 Cargo.toml                                    |   1 +
 .../trusted-server-adapter-fastly/src/main.rs |  19 +-
 crates/trusted-server-core/Cargo.toml         |   1 +
 crates/trusted-server-core/src/ec/admin.rs    | 380 +++++++++
 crates/trusted-server-core/src/ec/mod.rs      |   4 +
 crates/trusted-server-core/src/ec/partner.rs  | 732 ++++++++++++++++++
 crates/trusted-server-core/src/settings.rs    |  18 +-
 8 files changed, 1150 insertions(+), 6 deletions(-)
 create mode 100644 crates/trusted-server-core/src/ec/admin.rs
 create mode 100644 crates/trusted-server-core/src/ec/partner.rs

diff --git a/Cargo.lock b/Cargo.lock
index 8ad2b3e2..6dceaf01 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2767,6 +2767,7 @@ dependencies = [
  "serde",
  "serde_json",
  "sha2 0.10.9",
+ "subtle",
  "temp-env",
  "tokio",
  "tokio-test",
diff --git a/Cargo.toml b/Cargo.toml
index 69c03344..c3a35154 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -81,6 +81,7 @@ regex = "1.12.3"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0.149"
 sha2 = "0.10.9"
+subtle = "2.6"
 temp-env = "0.3.6"
 tokio = { version = "1.49", features = ["sync", "macros", "io-util", "rt", "time"] }
 tokio-test = "0.4"
diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 72cae33e..7c1de705 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -10,6 +10,8 @@ use trusted_server_core::constants::{
     ENV_FASTLY_IS_STAGING, ENV_FASTLY_SERVICE_VERSION, HEADER_X_GEO_INFO_AVAILABLE,
     HEADER_X_TS_ENV, HEADER_X_TS_VERSION,
 };
+use trusted_server_core::ec::admin::handle_register_partner;
+use trusted_server_core::ec::partner::PartnerStore;
 use trusted_server_core::error::TrustedServerError;
 use trusted_server_core::geo::GeoInfo;
 use trusted_server_core::http_util::sanitize_forwarded_headers;
@@ -145,10 +147,13 @@ async fn route_request(
         // Signature verification endpoint
         (Method::POST, "/verify-signature") => handle_verify_signature(settings, req),
 
-        // Key rotation admin endpoints
+        // Admin endpoints
         // Keep in sync with Settings::ADMIN_ENDPOINTS in crates/trusted-server-core/src/settings.rs
         (Method::POST, "/admin/keys/rotate") => handle_rotate_key(settings, req),
         (Method::POST, "/admin/keys/deactivate") => handle_deactivate_key(settings, req),
+        (Method::POST, "/admin/partners/register") => {
+            require_partner_store(settings).and_then(|store| handle_register_partner(&store, req))
+        }
 
         // Unified auction endpoint (returns creative HTML inline)
         (Method::POST, "/auction") => {
@@ -284,3 +289,15 @@ fn init_logger() {
         .apply()
         .expect("should initialize logger");
 }
+
+/// Constructs a `PartnerStore` from settings, or returns 503 if the
+/// `partner_store` config is not set.
+fn require_partner_store(settings: &Settings) -> Result<PartnerStore, Report<TrustedServerError>> {
+    let store_name = settings.ec.partner_store.as_deref().ok_or_else(|| {
+        Report::new(TrustedServerError::KvStore {
+            store_name: "ec.partner_store".to_owned(),
+            message: "ec.partner_store is not configured".to_owned(),
+        })
+    })?;
+    Ok(PartnerStore::new(store_name))
+}
diff --git a/crates/trusted-server-core/Cargo.toml b/crates/trusted-server-core/Cargo.toml
index facb74bb..c9c538fd 100644
--- a/crates/trusted-server-core/Cargo.toml
+++ b/crates/trusted-server-core/Cargo.toml
@@ -40,6 +40,7 @@ regex = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 sha2 = { workspace = true }
+subtle = { workspace = true }
 tokio = { workspace = true }
 toml = { workspace = true }
 trusted-server-js = { path = "../js" }
diff --git a/crates/trusted-server-core/src/ec/admin.rs b/crates/trusted-server-core/src/ec/admin.rs
new file mode 100644
index 00000000..db32a3cf
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/admin.rs
@@ -0,0 +1,380 @@
+//! Admin endpoints for partner management.
+//!
+//! Provides `POST /admin/partners/register` for registering and updating
+//! partner configurations. Authentication is handled by the `[[handlers]]`
+//! basic-auth layer before this code runs.
+
+use error_stack::{Report, ResultExt};
+use fastly::{Request, Response};
+use serde::{Deserialize, Serialize};
+use std::collections::HashSet;
+use url::Host;
+
+use crate::error::TrustedServerError;
+
+use super::partner::{
+    hash_api_key, validate_partner_id, validate_pull_sync_config, PartnerRecord, PartnerStore,
+};
+
+/// Request body for `POST /admin/partners/register`.
+///
+/// Accepts `api_key` as plaintext — it is hashed before storage and
+/// never persisted in cleartext.
+#[derive(Debug, Deserialize)]
+pub struct RegisterPartnerRequest {
+    pub id: String,
+    pub name: String,
+    pub allowed_return_domains: Vec<String>,
+    /// Raw API key — will be SHA-256 hashed before storage.
+    pub api_key: String,
+    #[serde(default)]
+    pub bidstream_enabled: bool,
+    pub source_domain: String,
+    #[serde(default = "default_openrtb_atype")]
+    pub openrtb_atype: u8,
+    #[serde(default = "default_sync_rate_limit")]
+    pub sync_rate_limit: u32,
+    #[serde(default = "default_batch_rate_limit")]
+    pub batch_rate_limit: u32,
+    #[serde(default)]
+    pub pull_sync_enabled: bool,
+    #[serde(default)]
+    pub pull_sync_url: Option<String>,
+    #[serde(default)]
+    pub pull_sync_allowed_domains: Vec<String>,
+    #[serde(default = "default_pull_sync_ttl_sec")]
+    pub pull_sync_ttl_sec: u64,
+    #[serde(default = "default_pull_sync_rate_limit")]
+    pub pull_sync_rate_limit: u32,
+    #[serde(default)]
+    pub ts_pull_token: Option<String>,
+}
+
+fn default_openrtb_atype() -> u8 {
+    3
+}
+fn default_sync_rate_limit() -> u32 {
+    100
+}
+fn default_batch_rate_limit() -> u32 {
+    60
+}
+fn default_pull_sync_ttl_sec() -> u64 {
+    86400
+}
+fn default_pull_sync_rate_limit() -> u32 {
+    10
+}
+
+fn bad_request(message: impl Into<String>) -> Report<TrustedServerError> {
+    Report::new(TrustedServerError::BadRequest {
+        message: message.into(),
+    })
+}
+
+fn normalize_required_text(
+    value: &str,
+    field_name: &str,
+) -> Result<String, Report<TrustedServerError>> {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        return Err(bad_request(format!("{field_name} is required")));
+    }
+    Ok(trimmed.to_owned())
+}
+
+fn normalize_hostname(value: &str, field_name: &str) -> Result<String, Report<TrustedServerError>> {
+    let trimmed = value.trim().trim_end_matches('.');
+    if trimmed.is_empty() {
+        return Err(bad_request(format!("{field_name} is required")));
+    }
+
+    let normalized = trimmed.to_ascii_lowercase();
+    Host::parse(&normalized)
+        .map_err(|_| bad_request(format!("{field_name} must be a valid hostname")))?;
+
+    Ok(normalized)
+}
+
+fn normalize_hostname_list(
+    values: Vec<String>,
+    field_name: &str,
+) -> Result<Vec<String>, Report<TrustedServerError>> {
+    let mut normalized_values = Vec::with_capacity(values.len());
+    let mut seen = HashSet::with_capacity(values.len());
+
+    for value in values {
+        let trimmed = value.trim().trim_end_matches('.');
+        if trimmed.is_empty() {
+            return Err(bad_request(format!(
+                "{field_name} entries must not be empty"
+            )));
+        }
+
+        let normalized = trimmed.to_ascii_lowercase();
+        Host::parse(&normalized).map_err(|_| {
+            bad_request(format!("{field_name} contains invalid hostname '{value}'"))
+        })?;
+
+        if seen.insert(normalized.clone()) {
+            normalized_values.push(normalized);
+        }
+    }
+
+    Ok(normalized_values)
+}
+
+/// Response body for `POST /admin/partners/register`.
+///
+/// Echoes key fields without exposing sensitive data (`api_key_hash`,
+/// `ts_pull_token`).
+#[derive(Debug, Serialize)]
+pub struct RegisterPartnerResponse {
+    pub id: String,
+    pub name: String,
+    pub pull_sync_enabled: bool,
+    pub bidstream_enabled: bool,
+    pub created: bool,
+}
+
+/// Handles `POST /admin/partners/register`.
+///
+/// Registers a new partner or updates an existing one. Authentication is
+/// handled upstream by the `[[handlers]]` basic-auth layer.
+///
+/// # Errors
+///
+/// Returns `Report<TrustedServerError>` on validation failure (400),
+/// KV store failure (503), or JSON parse failure (400).
+pub fn handle_register_partner(
+    partner_store: &PartnerStore,
+    mut req: Request,
+) -> Result<Response, Report<TrustedServerError>> {
+    // Parse request body.
+    let body_bytes = req.take_body_bytes();
+    let request: RegisterPartnerRequest =
+        serde_json::from_slice(&body_bytes).change_context(TrustedServerError::BadRequest {
+            message: "Invalid JSON in request body".to_owned(),
+        })?;
+
+    let RegisterPartnerRequest {
+        id,
+        name,
+        allowed_return_domains,
+        api_key,
+        bidstream_enabled,
+        source_domain,
+        openrtb_atype,
+        sync_rate_limit,
+        batch_rate_limit,
+        pull_sync_enabled,
+        pull_sync_url,
+        pull_sync_allowed_domains,
+        pull_sync_ttl_sec,
+        pull_sync_rate_limit,
+        ts_pull_token,
+    } = request;
+
+    // Validate partner ID.
+    validate_partner_id(&id).map_err(bad_request)?;
+
+    // Validate and normalize required fields.
+    let name = normalize_required_text(&name, "name")?;
+    if api_key.trim().is_empty() {
+        return Err(bad_request("api_key is required"));
+    }
+    let source_domain = normalize_hostname(&source_domain, "source_domain")?;
+
+    if allowed_return_domains.is_empty() {
+        return Err(bad_request(
+            "allowed_return_domains must have at least one entry",
+        ));
+    }
+    let allowed_return_domains =
+        normalize_hostname_list(allowed_return_domains, "allowed_return_domains")?;
+    let pull_sync_allowed_domains =
+        normalize_hostname_list(pull_sync_allowed_domains, "pull_sync_allowed_domains")?;
+
+    // Build the PartnerRecord with hashed API key.
+    let record = PartnerRecord {
+        id,
+        name,
+        allowed_return_domains,
+        api_key_hash: hash_api_key(&api_key),
+        bidstream_enabled,
+        source_domain,
+        openrtb_atype,
+        sync_rate_limit,
+        batch_rate_limit,
+        pull_sync_enabled,
+        pull_sync_url,
+        pull_sync_allowed_domains,
+        pull_sync_ttl_sec,
+        pull_sync_rate_limit,
+        ts_pull_token,
+    };
+
+    // Validate pull sync configuration.
+    validate_pull_sync_config(&record).map_err(bad_request)?;
+
+    // Persist to KV store.
+    let created = partner_store.upsert(&record)?;
+
+    let status = if created {
+        log::info!("Registered new partner '{}'", record.id);
+        fastly::http::StatusCode::CREATED
+    } else {
+        log::info!("Updated existing partner '{}'", record.id);
+        fastly::http::StatusCode::OK
+    };
+
+    let response_body = RegisterPartnerResponse {
+        id: record.id,
+        name: record.name,
+        pull_sync_enabled: record.pull_sync_enabled,
+        bidstream_enabled: record.bidstream_enabled,
+        created,
+    };
+
+    let body = serde_json::to_string(&response_body).change_context(
+        TrustedServerError::Configuration {
+            message: "Failed to serialize registration response".to_owned(),
+        },
+    )?;
+
+    Ok(Response::from_status(status)
+        .with_content_type(fastly::mime::APPLICATION_JSON)
+        .with_body(body))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn request_deserializes_with_defaults() {
+        let json = r#"{
+            "id": "ssp_x",
+            "name": "SSP Example",
+            "allowed_return_domains": ["sync.example-ssp.com"],
+            "api_key": "raw-secret-key",
+            "source_domain": "example-ssp.com"
+        }"#;
+
+        let req: RegisterPartnerRequest =
+            serde_json::from_str(json).expect("should deserialize with defaults");
+
+        assert_eq!(req.id, "ssp_x");
+        assert_eq!(req.openrtb_atype, 3, "should default to 3");
+        assert_eq!(req.sync_rate_limit, 100, "should default to 100");
+        assert_eq!(req.batch_rate_limit, 60, "should default to 60");
+        assert_eq!(req.pull_sync_ttl_sec, 86400, "should default to 86400");
+        assert_eq!(req.pull_sync_rate_limit, 10, "should default to 10");
+        assert!(!req.bidstream_enabled, "should default to false");
+        assert!(!req.pull_sync_enabled, "should default to false");
+        assert!(req.pull_sync_url.is_none());
+        assert!(req.ts_pull_token.is_none());
+    }
+
+    #[test]
+    fn response_does_not_contain_sensitive_fields() {
+        let response = RegisterPartnerResponse {
+            id: "ssp_x".to_owned(),
+            name: "SSP Example".to_owned(),
+            pull_sync_enabled: false,
+            bidstream_enabled: true,
+            created: true,
+        };
+
+        let json = serde_json::to_string(&response).expect("should serialize");
+        assert!(!json.contains("api_key"), "should not contain api_key");
+        assert!(
+            !json.contains("api_key_hash"),
+            "should not contain api_key_hash"
+        );
+        assert!(
+            !json.contains("ts_pull_token"),
+            "should not contain ts_pull_token"
+        );
+    }
+
+    #[test]
+    fn request_deserializes_full_payload() {
+        let json = r#"{
+            "id": "ssp_x",
+            "name": "SSP Example",
+            "allowed_return_domains": ["sync.example-ssp.com"],
+            "api_key": "raw-secret-key",
+            "bidstream_enabled": true,
+            "source_domain": "example-ssp.com",
+            "openrtb_atype": 3,
+            "sync_rate_limit": 200,
+            "batch_rate_limit": 120,
+            "pull_sync_enabled": true,
+            "pull_sync_url": "https://sync.example-ssp.com/pull",
+            "pull_sync_allowed_domains": ["sync.example-ssp.com"],
+            "pull_sync_ttl_sec": 43200,
+            "pull_sync_rate_limit": 5,
+            "ts_pull_token": "bearer-token-123"
+        }"#;
+
+        let req: RegisterPartnerRequest =
+            serde_json::from_str(json).expect("should deserialize full payload");
+
+        assert_eq!(req.sync_rate_limit, 200);
+        assert_eq!(req.batch_rate_limit, 120);
+        assert!(req.pull_sync_enabled);
+        assert_eq!(
+            req.pull_sync_url.as_deref(),
+            Some("https://sync.example-ssp.com/pull")
+        );
+    }
+
+    #[test]
+    fn normalize_required_text_rejects_whitespace_only() {
+        let err = normalize_required_text("   ", "name")
+            .expect_err("should reject whitespace-only required field");
+        assert!(
+            err.to_string().contains("name is required"),
+            "should mention required field"
+        );
+    }
+
+    #[test]
+    fn normalize_hostname_normalizes_case_and_trailing_dot() {
+        let normalized = normalize_hostname("  Sync.Example.COM.  ", "source_domain")
+            .expect("should parse host");
+        assert_eq!(normalized, "sync.example.com");
+    }
+
+    #[test]
+    fn normalize_hostname_list_rejects_empty_entry() {
+        let err = normalize_hostname_list(
+            vec!["sync.example.com".to_owned(), "   ".to_owned()],
+            "allowed_return_domains",
+        )
+        .expect_err("should reject empty domain entries");
+        assert!(
+            err.to_string()
+                .contains("allowed_return_domains entries must not be empty"),
+            "should surface empty-entry error"
+        );
+    }
+
+    #[test]
+    fn normalize_hostname_list_deduplicates_normalized_values() {
+        let normalized = normalize_hostname_list(
+            vec![
+                "Sync.Example.com".to_owned(),
+                "sync.example.com.".to_owned(),
+                "cdn.example.com".to_owned(),
+            ],
+            "allowed_return_domains",
+        )
+        .expect("should normalize hostnames");
+        assert_eq!(
+            normalized,
+            vec!["sync.example.com".to_owned(), "cdn.example.com".to_owned()]
+        );
+    }
+}
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index 97116239..df5e6289 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -18,12 +18,16 @@
 //! - [`cookies`] — `Set-Cookie` header creation and expiration helpers
 //! - [`kv`] — KV Store identity graph operations (CAS, tombstones, debounce)
 //! - [`kv_types`] — Schema types for KV identity graph entries
+//! - [`partner`] — Partner registry (`PartnerRecord`, `PartnerStore`)
+//! - [`admin`] — Admin endpoints for partner management
 
+pub mod admin;
 pub mod consent;
 pub mod cookies;
 pub mod generation;
 pub mod kv;
 pub mod kv_types;
+pub mod partner;
 
 use cookie::CookieJar;
 use error_stack::Report;
diff --git a/crates/trusted-server-core/src/ec/partner.rs b/crates/trusted-server-core/src/ec/partner.rs
new file mode 100644
index 00000000..7e1566a8
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/partner.rs
@@ -0,0 +1,732 @@
+//! Partner registry — `PartnerRecord` schema and `PartnerStore` operations.
+//!
+//! Each partner (SSP, DSP, identity vendor) is stored as a JSON record in
+//! the Fastly KV Store keyed by `partner_id`. A secondary index
+//! `apikey:{sha256_hex}` provides O(1) API key lookups for batch sync auth.
+
+use std::{collections::HashSet, sync::OnceLock};
+
+use error_stack::{Report, ResultExt};
+use fastly::kv_store::KVStore;
+use regex::Regex;
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use subtle::ConstantTimeEq;
+
+use crate::error::TrustedServerError;
+
+/// Regex pattern for valid partner IDs.
+/// Lowercase alphanumeric, hyphens, underscores; 1-32 characters.
+const PARTNER_ID_PATTERN: &str = r"^[a-z0-9_-]{1,32}$";
+
+/// Reserved partner IDs that would collide with managed `X-ts-*` headers.
+const RESERVED_PARTNER_IDS: &[&str] = &[
+    "ec",
+    "eids",
+    "ec-consent",
+    "eids-truncated",
+    "synthetic",
+    "ts",
+    "version",
+    "env",
+];
+
+/// Prefix for the API key hash secondary index keys.
+const APIKEY_INDEX_PREFIX: &str = "apikey:";
+
+/// Cached compiled regex for partner ID validation.
+static PARTNER_ID_REGEX: OnceLock<Result<Regex, String>> = OnceLock::new();
+
+fn partner_id_regex() -> Result<&'static Regex, String> {
+    PARTNER_ID_REGEX
+        .get_or_init(|| {
+            Regex::new(PARTNER_ID_PATTERN)
+                .map_err(|e| format!("internal error compiling partner ID regex: {e}"))
+        })
+        .as_ref()
+        .map_err(Clone::clone)
+}
+
+/// A registered partner configuration stored in the partner KV store.
+///
+/// Created via `POST /admin/partners/register`. Used by pixel sync, batch
+/// sync, pull sync, and auction bidstream decoration.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct PartnerRecord {
+    /// Unique partner identifier. Must match [`PARTNER_ID_PATTERN`] and
+    /// not be in [`RESERVED_PARTNER_IDS`]. Used to build `X-ts-<id>`
+    /// response headers.
+    pub id: String,
+    /// Human-readable partner name.
+    pub name: String,
+    /// Exact hostnames allowed as `return` URL domains in pixel sync.
+    pub allowed_return_domains: Vec<String>,
+    /// SHA-256 hex of the partner's API key. Plaintext is never stored.
+    pub api_key_hash: String,
+    /// Whether this partner's UIDs appear in auction `user.eids`.
+    pub bidstream_enabled: bool,
+    /// `OpenRTB` `source.domain` for EID entries (e.g. `"liveramp.com"`).
+    pub source_domain: String,
+    /// `OpenRTB` `atype` value (typically 3).
+    pub openrtb_atype: u8,
+    /// Max pixel sync writes per EC hash per partner per hour.
+    pub sync_rate_limit: u32,
+    /// Max batch sync API requests per partner per minute.
+    pub batch_rate_limit: u32,
+    /// Whether server-to-server pull sync is enabled for this partner.
+    pub pull_sync_enabled: bool,
+    /// URL to call for pull sync. Required when `pull_sync_enabled`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pull_sync_url: Option<String>,
+    /// Allowlist of domains TS may call for this partner's pull sync.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub pull_sync_allowed_domains: Vec<String>,
+    /// Seconds between pull sync refreshes (default 86400).
+    pub pull_sync_ttl_sec: u64,
+    /// Max pull sync calls per EC hash per partner per hour.
+    pub pull_sync_rate_limit: u32,
+    /// Outbound bearer token for pull sync requests.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub ts_pull_token: Option<String>,
+}
+
+/// Validates a partner ID format and checks against reserved names.
+///
+/// # Errors
+///
+/// Returns a descriptive error string on validation failure.
+pub fn validate_partner_id(id: &str) -> Result<(), String> {
+    let re = partner_id_regex()?;
+    if !re.is_match(id) {
+        return Err(format!(
+            "partner ID must match {PARTNER_ID_PATTERN}, got: '{id}'"
+        ));
+    }
+    if RESERVED_PARTNER_IDS.contains(&id) {
+        return Err(format!("partner ID '{id}' is reserved"));
+    }
+    Ok(())
+}
+
+/// Validates pull sync configuration consistency.
+///
+/// When `pull_sync_enabled` is true, both `pull_sync_url` and
+/// `ts_pull_token` must be present, and the URL's hostname must
+/// appear in `pull_sync_allowed_domains`.
+///
+/// # Errors
+///
+/// Returns a descriptive error string on validation failure.
+pub fn validate_pull_sync_config(record: &PartnerRecord) -> Result<(), String> {
+    if !record.pull_sync_enabled {
+        return Ok(());
+    }
+
+    let url_str = record.pull_sync_url.as_deref().unwrap_or("");
+    if url_str.is_empty() {
+        return Err(
+            "pull_sync_url and ts_pull_token are required when pull_sync_enabled is true"
+                .to_owned(),
+        );
+    }
+
+    if record.ts_pull_token.as_deref().unwrap_or("").is_empty() {
+        return Err(
+            "pull_sync_url and ts_pull_token are required when pull_sync_enabled is true"
+                .to_owned(),
+        );
+    }
+
+    // Validate that the pull sync URL hostname is in the allowed domains.
+    let parsed =
+        url::Url::parse(url_str).map_err(|e| format!("pull_sync_url is not a valid URL: {e}"))?;
+    let host = parsed
+        .host_str()
+        .ok_or("pull_sync_url has no hostname")?
+        .trim_end_matches('.')
+        .to_ascii_lowercase();
+
+    let allowed: HashSet<String> = record
+        .pull_sync_allowed_domains
+        .iter()
+        .map(|domain| domain.trim().trim_end_matches('.').to_ascii_lowercase())
+        .collect();
+
+    if !allowed.contains(&host) {
+        return Err("pull_sync_url domain must be in pull_sync_allowed_domains".to_owned());
+    }
+
+    Ok(())
+}
+
+/// Computes the SHA-256 hex digest of an API key.
+#[must_use]
+pub fn hash_api_key(api_key: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(api_key.as_bytes());
+    hex::encode(hasher.finalize())
+}
+
+/// Wraps a Fastly KV Store for partner registry operations.
+///
+/// Partner records are keyed by `partner_id`. A secondary index
+/// `apikey:{sha256_hex}` maps API key hashes to partner IDs for
+/// O(1) auth lookups during batch sync.
+pub struct PartnerStore {
+    store_name: String,
+}
+
+impl PartnerStore {
+    /// Creates a new partner store backed by the named KV store.
+    #[must_use]
+    pub fn new(store_name: impl Into<String>) -> Self {
+        Self {
+            store_name: store_name.into(),
+        }
+    }
+
+    /// Returns the configured store name.
+    #[must_use]
+    pub fn store_name(&self) -> &str {
+        &self.store_name
+    }
+
+    /// Opens the underlying Fastly KV store.
+    fn open_store(&self) -> Result<KVStore, Report<TrustedServerError>> {
+        KVStore::open(&self.store_name)
+            .change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: "Failed to open partner store".to_owned(),
+            })?
+            .ok_or_else(|| {
+                Report::new(TrustedServerError::KvStore {
+                    store_name: self.store_name.clone(),
+                    message: "Partner store not found".to_owned(),
+                })
+            })
+    }
+
+    /// Reads a partner record by ID.
+    ///
+    /// Returns `Ok(None)` when the partner is not registered.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store or deserialization failure.
+    pub fn get(
+        &self,
+        partner_id: &str,
+    ) -> Result<Option<PartnerRecord>, Report<TrustedServerError>> {
+        let store = self.open_store()?;
+        let mut response = match store.lookup(partner_id) {
+            Ok(resp) => resp,
+            Err(fastly::kv_store::KVStoreError::ItemNotFound) => return Ok(None),
+            Err(err) => {
+                return Err(
+                    Report::new(err).change_context(TrustedServerError::KvStore {
+                        store_name: self.store_name.clone(),
+                        message: format!("Failed to read partner '{partner_id}'"),
+                    }),
+                );
+            }
+        };
+
+        let body_bytes = response.take_body_bytes();
+        let record: PartnerRecord =
+            serde_json::from_slice(&body_bytes).change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!("Failed to deserialize partner '{partner_id}'"),
+            })?;
+
+        Ok(Some(record))
+    }
+
+    /// Writes or updates a partner record and maintains the API key index.
+    ///
+    /// Returns `true` if this was a new partner (create), `false` if an
+    /// existing partner was updated.
+    ///
+    /// Index maintenance order:
+    /// 1. Read existing `apikey:` index value for rollback
+    /// 2. Write new `apikey:` index
+    /// 3. Write primary record
+    /// 4. Delete old `apikey:` index (if key rotated)
+    ///
+    /// Writes are still **not fully atomic**, but this order ensures
+    /// registration does not return success after a failed index write and
+    /// performs best-effort rollback when primary write fails.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store failure.
+    pub fn upsert(&self, record: &PartnerRecord) -> Result<bool, Report<TrustedServerError>> {
+        let store = self.open_store()?;
+
+        // Read existing record to detect API key rotation.
+        let existing = match store.lookup(&record.id) {
+            Ok(mut resp) => {
+                let bytes = resp.take_body_bytes();
+                serde_json::from_slice::<PartnerRecord>(&bytes).ok()
+            }
+            Err(_) => None,
+        };
+
+        let is_create = existing.is_none();
+        let old_api_key_hash = existing.as_ref().map(|r| r.api_key_hash.clone());
+
+        let index_key = format!("{APIKEY_INDEX_PREFIX}{}", record.api_key_hash);
+        let previous_index_partner_id = self.read_index_partner_id(&store, &index_key)?;
+
+        // 1. Write new API key index.
+        store
+            .build_insert()
+            .execute(&index_key, record.id.as_str())
+            .change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!(
+                    "Failed to write API key index for partner '{}' (hash '{}')",
+                    record.id, record.api_key_hash
+                ),
+            })?;
+
+        // 2. Write primary record.
+        let body = serde_json::to_string(record).change_context(TrustedServerError::KvStore {
+            store_name: self.store_name.clone(),
+            message: format!("Failed to serialize partner '{}'", record.id),
+        })?;
+
+        if let Err(err) = store.build_insert().execute(&record.id, body) {
+            self.restore_previous_index_mapping(
+                &store,
+                &index_key,
+                previous_index_partner_id.as_deref(),
+                &record.id,
+            );
+            return Err(
+                Report::new(err).change_context(TrustedServerError::KvStore {
+                    store_name: self.store_name.clone(),
+                    message: format!("Failed to write partner '{}'", record.id),
+                }),
+            );
+        }
+
+        // 3. Delete old API key index if key rotated.
+        if let Some(ref old_hash) = old_api_key_hash {
+            if *old_hash != record.api_key_hash {
+                let old_key = format!("{APIKEY_INDEX_PREFIX}{old_hash}");
+                if let Err(err) = store.delete(&old_key) {
+                    log::warn!(
+                        "Failed to delete old API key index for partner '{}': {err:?}",
+                        record.id,
+                    );
+                }
+            }
+        }
+
+        Ok(is_create)
+    }
+
+    fn read_index_partner_id(
+        &self,
+        store: &KVStore,
+        index_key: &str,
+    ) -> Result<Option<String>, Report<TrustedServerError>> {
+        let mut response = match store.lookup(index_key) {
+            Ok(resp) => resp,
+            Err(fastly::kv_store::KVStoreError::ItemNotFound) => return Ok(None),
+            Err(err) => {
+                return Err(
+                    Report::new(err).change_context(TrustedServerError::KvStore {
+                        store_name: self.store_name.clone(),
+                        message: format!(
+                            "Failed to read existing API key index before upsert ('{index_key}')"
+                        ),
+                    }),
+                );
+            }
+        };
+
+        let partner_id = String::from_utf8(response.take_body_bytes()).map_err(|_| {
+            Report::new(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!(
+                    "Existing API key index value is not valid UTF-8 before upsert ('{index_key}')"
+                ),
+            })
+        })?;
+
+        Ok(Some(partner_id))
+    }
+
+    fn restore_previous_index_mapping(
+        &self,
+        store: &KVStore,
+        index_key: &str,
+        previous_partner_id: Option<&str>,
+        partner_id: &str,
+    ) {
+        if let Some(previous_partner_id) = previous_partner_id {
+            if previous_partner_id == partner_id {
+                return;
+            }
+
+            if let Err(err) = store.build_insert().execute(index_key, previous_partner_id) {
+                log::warn!(
+                    "Failed to restore previous API key index mapping after write failure for partner '{}': {err:?}",
+                    partner_id,
+                );
+            }
+            return;
+        }
+
+        match store.delete(index_key) {
+            Ok(()) | Err(fastly::kv_store::KVStoreError::ItemNotFound) => {}
+            Err(err) => {
+                log::warn!(
+                    "Failed to roll back API key index after write failure for partner '{}': {err:?}",
+                    partner_id,
+                );
+            }
+        }
+    }
+
+    /// Looks up a partner by API key hash using the `apikey:` secondary index.
+    ///
+    /// After resolving the index to a partner ID, re-verifies that the
+    /// stored `api_key_hash` matches the lookup hash (guards against stale
+    /// index entries from key rotation).
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store failure.
+    pub fn find_by_api_key_hash(
+        &self,
+        hash: &str,
+    ) -> Result<Option<PartnerRecord>, Report<TrustedServerError>> {
+        let store = self.open_store()?;
+
+        // Look up the secondary index.
+        let index_key = format!("{APIKEY_INDEX_PREFIX}{hash}");
+        let mut index_response = match store.lookup(&index_key) {
+            Ok(resp) => resp,
+            Err(fastly::kv_store::KVStoreError::ItemNotFound) => return Ok(None),
+            Err(err) => {
+                return Err(
+                    Report::new(err).change_context(TrustedServerError::KvStore {
+                        store_name: self.store_name.clone(),
+                        message: format!("Failed to read API key index for hash '{hash}'"),
+                    }),
+                );
+            }
+        };
+
+        let partner_id = String::from_utf8(index_response.take_body_bytes()).map_err(|_| {
+            Report::new(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!("API key index value for hash '{hash}' is not valid UTF-8"),
+            })
+        })?;
+
+        // Fetch the actual partner record.
+        let record = match self.get(&partner_id)? {
+            Some(r) => r,
+            None => {
+                // Stale index — partner was deleted.
+                log::warn!(
+                    "API key index points to non-existent partner '{partner_id}' (stale index)"
+                );
+                return Ok(None);
+            }
+        };
+
+        // Verify the stored hash matches — guards against stale index from
+        // key rotation.
+        if record.api_key_hash != hash {
+            log::warn!(
+                "API key hash mismatch for partner '{}' (stale index after key rotation)",
+                record.id,
+            );
+            return Ok(None);
+        }
+
+        Ok(Some(record))
+    }
+
+    /// Verifies an API key against the stored hash for a given partner.
+    ///
+    /// Uses SHA-256 hashing and constant-time comparison to prevent
+    /// timing attacks.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] if the partner lookup fails.
+    pub fn verify_api_key(
+        &self,
+        partner_id: &str,
+        api_key: &str,
+    ) -> Result<bool, Report<TrustedServerError>> {
+        let record = match self.get(partner_id)? {
+            Some(r) => r,
+            None => return Ok(false),
+        };
+
+        let incoming_hash = hash_api_key(api_key);
+        let stored_bytes = record.api_key_hash.as_bytes();
+        let incoming_bytes = incoming_hash.as_bytes();
+
+        Ok(stored_bytes.ct_eq(incoming_bytes).into())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn partner_record_serialization_roundtrip() {
+        let record = PartnerRecord {
+            id: "ssp_x".to_owned(),
+            name: "SSP Example".to_owned(),
+            allowed_return_domains: vec!["sync.example-ssp.com".to_owned()],
+            api_key_hash: hash_api_key("test-api-key"),
+            bidstream_enabled: true,
+            source_domain: "example-ssp.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+        };
+
+        let json = serde_json::to_string(&record).expect("should serialize");
+        let deserialized: PartnerRecord = serde_json::from_str(&json).expect("should deserialize");
+
+        assert_eq!(deserialized, record);
+    }
+
+    #[test]
+    fn hash_api_key_is_deterministic() {
+        let h1 = hash_api_key("my-secret-key");
+        let h2 = hash_api_key("my-secret-key");
+        assert_eq!(h1, h2);
+        assert_eq!(h1.len(), 64, "should be 64-char hex SHA-256");
+    }
+
+    #[test]
+    fn hash_api_key_differs_for_different_keys() {
+        let h1 = hash_api_key("key-a");
+        let h2 = hash_api_key("key-b");
+        assert_ne!(h1, h2);
+    }
+
+    #[test]
+    fn validate_partner_id_accepts_valid() {
+        assert!(validate_partner_id("ssp_x").is_ok());
+        assert!(validate_partner_id("liveramp").is_ok());
+        assert!(validate_partner_id("a-b_c-1").is_ok());
+        assert!(validate_partner_id("a").is_ok());
+    }
+
+    #[test]
+    fn validate_partner_id_rejects_uppercase() {
+        let err = validate_partner_id("SSP_X").unwrap_err();
+        assert!(
+            err.contains("must match"),
+            "should reject uppercase, got: {err}"
+        );
+    }
+
+    #[test]
+    fn validate_partner_id_rejects_too_long() {
+        let long = "a".repeat(33);
+        let err = validate_partner_id(&long).unwrap_err();
+        assert!(
+            err.contains("must match"),
+            "should reject >32 chars, got: {err}"
+        );
+    }
+
+    #[test]
+    fn validate_partner_id_rejects_empty() {
+        let err = validate_partner_id("").unwrap_err();
+        assert!(
+            err.contains("must match"),
+            "should reject empty, got: {err}"
+        );
+    }
+
+    #[test]
+    fn validate_partner_id_rejects_reserved() {
+        for reserved in RESERVED_PARTNER_IDS {
+            let err = validate_partner_id(reserved).unwrap_err();
+            assert!(
+                err.contains("reserved"),
+                "should reject '{reserved}', got: {err}"
+            );
+        }
+    }
+
+    #[test]
+    fn validate_partner_id_rejects_special_chars() {
+        assert!(validate_partner_id("ssp.x").is_err(), "should reject dots");
+        assert!(
+            validate_partner_id("ssp x").is_err(),
+            "should reject spaces"
+        );
+        assert!(
+            validate_partner_id("ssp/x").is_err(),
+            "should reject slashes"
+        );
+    }
+
+    #[test]
+    fn validate_pull_sync_ok_when_disabled() {
+        let record = PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+        };
+        assert!(validate_pull_sync_config(&record).is_ok());
+    }
+
+    #[test]
+    fn validate_pull_sync_rejects_missing_url() {
+        let record = PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: true,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: Some("token".to_owned()),
+        };
+        let err = validate_pull_sync_config(&record).unwrap_err();
+        assert!(err.contains("pull_sync_url"), "got: {err}");
+    }
+
+    #[test]
+    fn validate_pull_sync_rejects_missing_token() {
+        let record = PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: true,
+            pull_sync_url: Some("https://sync.test.com/pull".to_owned()),
+            pull_sync_allowed_domains: vec!["sync.test.com".to_owned()],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+        };
+        let err = validate_pull_sync_config(&record).unwrap_err();
+        assert!(err.contains("ts_pull_token"), "got: {err}");
+    }
+
+    #[test]
+    fn validate_pull_sync_rejects_url_not_in_allowed_domains() {
+        let record = PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: true,
+            pull_sync_url: Some("https://evil.com/pull".to_owned()),
+            pull_sync_allowed_domains: vec!["sync.test.com".to_owned()],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: Some("token".to_owned()),
+        };
+        let err = validate_pull_sync_config(&record).unwrap_err();
+        assert!(err.contains("pull_sync_allowed_domains"), "got: {err}");
+    }
+
+    #[test]
+    fn validate_pull_sync_accepts_valid_config() {
+        let record = PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: true,
+            pull_sync_url: Some("https://sync.test.com/pull".to_owned()),
+            pull_sync_allowed_domains: vec!["sync.test.com".to_owned()],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: Some("token".to_owned()),
+        };
+        assert!(validate_pull_sync_config(&record).is_ok());
+    }
+
+    #[test]
+    fn optional_fields_omitted_from_json() {
+        let record = PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+        };
+        let json = serde_json::to_string(&record).expect("should serialize");
+        assert!(
+            !json.contains("pull_sync_url"),
+            "None pull_sync_url should be omitted"
+        );
+        assert!(
+            !json.contains("ts_pull_token"),
+            "None ts_pull_token should be omitted"
+        );
+        assert!(
+            !json.contains("pull_sync_allowed_domains"),
+            "empty pull_sync_allowed_domains should be omitted"
+        );
+    }
+}
diff --git a/crates/trusted-server-core/src/settings.rs b/crates/trusted-server-core/src/settings.rs
index 8ea9088a..3fb91fc6 100644
--- a/crates/trusted-server-core/src/settings.rs
+++ b/crates/trusted-server-core/src/settings.rs
@@ -564,7 +564,11 @@ impl Settings {
     /// endpoints are always protected by authentication.
     /// Update [`ADMIN_ENDPOINTS`](Self::ADMIN_ENDPOINTS) when adding new
     /// admin routes to `crates/trusted-server-adapter-fastly/src/main.rs`.
-    pub(crate) const ADMIN_ENDPOINTS: &[&str] = &["/admin/keys/rotate", "/admin/keys/deactivate"];
+    pub(crate) const ADMIN_ENDPOINTS: &[&str] = &[
+        "/admin/keys/rotate",
+        "/admin/keys/deactivate",
+        "/admin/partners/register",
+    ];
 
     /// Returns admin endpoint paths that no configured handler covers.
     ///
@@ -1862,8 +1866,12 @@ mod tests {
             .expect("should check admin coverage");
         assert_eq!(
             uncovered,
-            vec!["/admin/keys/rotate", "/admin/keys/deactivate"],
-            "should report both admin endpoints as uncovered"
+            vec![
+                "/admin/keys/rotate",
+                "/admin/keys/deactivate",
+                "/admin/partners/register",
+            ],
+            "should report all admin endpoints as uncovered"
         );
     }
 
@@ -1896,8 +1904,8 @@ mod tests {
             .expect("should check admin coverage");
         assert_eq!(
             uncovered,
-            vec!["/admin/keys/deactivate"],
-            "should detect that only deactivate is uncovered"
+            vec!["/admin/keys/deactivate", "/admin/partners/register"],
+            "should detect endpoints not covered by the rotate-only handler"
         );
     }
 

From a037e7a3a5e707eb8f4777cdc0150c7e5d59e639 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Wed, 25 Mar 2026 18:58:44 -0500
Subject: [PATCH 06/36] Centralize EC lifecycle finalization in middleware

Implement Story 5 (#538): centralize EC cookie set/delete and KV
tombstone writes in finalize_response(), replacing inline mutation
scattered across publisher and proxy handlers. Adds consent-withdrawal
cleanup, EC header propagation on proxy requests, and docs formatting.
---
 .../trusted-server-adapter-fastly/src/main.rs |  94 ++---
 .../src/auction/endpoints.rs                  |  18 +-
 crates/trusted-server-core/src/ec/finalize.rs | 324 ++++++++++++++++++
 crates/trusted-server-core/src/ec/mod.rs      |  65 +++-
 .../src/integrations/registry.rs              | 117 +++----
 crates/trusted-server-core/src/publisher.rs   |  38 +-
 docs/guide/configuration.md                   |  22 +-
 7 files changed, 496 insertions(+), 182 deletions(-)
 create mode 100644 crates/trusted-server-core/src/ec/finalize.rs

diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 7c1de705..10a73eb0 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -11,7 +11,10 @@ use trusted_server_core::constants::{
     HEADER_X_TS_ENV, HEADER_X_TS_VERSION,
 };
 use trusted_server_core::ec::admin::handle_register_partner;
+use trusted_server_core::ec::finalize::ec_finalize_response;
+use trusted_server_core::ec::kv::KvIdentityGraph;
 use trusted_server_core::ec::partner::PartnerStore;
+use trusted_server_core::ec::EcContext;
 use trusted_server_core::error::TrustedServerError;
 use trusted_server_core::geo::GeoInfo;
 use trusted_server_core::http_util::sanitize_forwarded_headers;
@@ -101,21 +104,33 @@ async fn route_request(
     // clients are untrusted and can hijack URL rewriting (see #409).
     sanitize_forwarded_headers(&mut req);
 
-    // Look up geo info via the platform abstraction using the client IP
-    // already captured in RuntimeServices at the entry point.
-    let geo_info = runtime_services
-        .geo()
-        .lookup(runtime_services.client_info().client_ip)
-        .unwrap_or_else(|e| {
-            log::warn!("geo lookup failed: {e}");
-            None
-        });
+    // Extract geo info before auth check or routing consumes the request.
+    let geo_info = GeoInfo::from_request(&req);
+
+    let mut ec_context =
+        match EcContext::read_from_request_with_geo(settings, &req, geo_info.as_ref()) {
+            Ok(context) => context,
+            Err(err) => {
+                let mut response = to_error_response(&err);
+                finalize_response(settings, geo_info.as_ref(), &mut response);
+                return Ok(response);
+            }
+        };
+
+    let kv_graph = maybe_identity_graph(settings);
 
     // `get_settings()` should already have rejected invalid handler regexes.
     // Keep this fallback so manually-constructed or otherwise unprepared
     // settings still become an error response instead of panicking.
     match enforce_basic_auth(settings, &req) {
         Ok(Some(mut response)) => {
+            ec_finalize_response(
+                settings,
+                geo_info.as_ref(),
+                &ec_context,
+                kv_graph.as_ref(),
+                &mut response,
+            );
             finalize_response(settings, geo_info.as_ref(), &mut response);
             return Ok(response);
         }
@@ -157,12 +172,7 @@ async fn route_request(
 
         // Unified auction endpoint (returns creative HTML inline)
         (Method::POST, "/auction") => {
-            match runtime_services_for_consent_route(settings, runtime_services) {
-                Ok(auction_services) => {
-                    handle_auction(settings, orchestrator, &auction_services, req).await
-                }
-                Err(e) => Err(e),
-            }
+            handle_auction(settings, orchestrator, kv_graph.as_ref(), &ec_context, req).await
         }
 
         // tsjs endpoints
@@ -175,7 +185,7 @@ async fn route_request(
             handle_first_party_proxy_rebuild(settings, req).await
         }
         (m, path) if integration_registry.has_route(&m, path) => integration_registry
-            .handle_proxy(&m, path, settings, req)
+            .handle_proxy(&m, path, settings, kv_graph.as_ref(), &mut ec_context, req)
             .await
             .unwrap_or_else(|| {
                 Err(Report::new(TrustedServerError::BadRequest {
@@ -190,22 +200,18 @@ async fn route_request(
                 path
             );
 
-            match runtime_services_for_consent_route(settings, runtime_services) {
-                Ok(publisher_services) => {
-                    match handle_publisher_request(
-                        settings,
-                        integration_registry,
-                        &publisher_services,
-                        req,
-                    ) {
-                        Ok(response) => Ok(response),
-                        Err(e) => {
-                            log::error!("Failed to proxy to publisher origin: {:?}", e);
-                            Err(e)
-                        }
-                    }
+            match handle_publisher_request(
+                settings,
+                integration_registry,
+                kv_graph.as_ref(),
+                &mut ec_context,
+                req,
+            ) {
+                Ok(response) => Ok(response),
+                Err(e) => {
+                    log::error!("Failed to proxy to publisher origin: {:?}", e);
+                    Err(e)
                 }
-                Err(e) => Err(e),
             }
         }
     };
@@ -213,27 +219,21 @@ async fn route_request(
     // Convert any errors to HTTP error responses
     let mut response = result.unwrap_or_else(|e| to_error_response(&e));
 
+    ec_finalize_response(
+        settings,
+        geo_info.as_ref(),
+        &ec_context,
+        kv_graph.as_ref(),
+        &mut response,
+    );
+
     finalize_response(settings, geo_info.as_ref(), &mut response);
 
     Ok(response)
 }
 
-fn runtime_services_for_consent_route(
-    settings: &Settings,
-    runtime_services: &RuntimeServices,
-) -> Result<RuntimeServices, Report<TrustedServerError>> {
-    let Some(store_name) = settings.consent.consent_store.as_deref() else {
-        return Ok(runtime_services.clone());
-    };
-
-    open_kv_store(store_name)
-        .map(|store| runtime_services.clone().with_kv_store(store))
-        .map_err(|e| {
-            Report::new(TrustedServerError::KvStore {
-                store_name: store_name.to_string(),
-                message: e.to_string(),
-            })
-        })
+fn maybe_identity_graph(settings: &Settings) -> Option<KvIdentityGraph> {
+    settings.ec.ec_store.as_ref().map(KvIdentityGraph::new)
 }
 
 /// Applies all standard response headers: geo, version, staging, and configured headers.
diff --git a/crates/trusted-server-core/src/auction/endpoints.rs b/crates/trusted-server-core/src/auction/endpoints.rs
index 605f8ee9..fff0eb79 100644
--- a/crates/trusted-server-core/src/auction/endpoints.rs
+++ b/crates/trusted-server-core/src/auction/endpoints.rs
@@ -4,6 +4,7 @@ use error_stack::{Report, ResultExt};
 use fastly::{Request, Response};
 
 use crate::auction::formats::AdRequest;
+use crate::ec::kv::KvIdentityGraph;
 use crate::ec::EcContext;
 use crate::error::TrustedServerError;
 
@@ -29,21 +30,10 @@ use super::AuctionOrchestrator;
 pub async fn handle_auction(
     settings: &Settings,
     orchestrator: &AuctionOrchestrator,
-    runtime_services: &RuntimeServices,
+    _kv: Option<&KvIdentityGraph>,
+    ec_context: &EcContext,
     mut req: Request,
 ) -> Result<Response, Report<TrustedServerError>> {
-    // Read EC state before consuming the request body.
-    let mut ec_context = EcContext::read_from_request(settings, &req).change_context(
-        TrustedServerError::Auction {
-            message: "Failed to read EC context".to_string(),
-        },
-    )?;
-
-    // Auction is an organic handler — generate EC if needed.
-    if let Err(err) = ec_context.generate_if_needed(settings) {
-        log::warn!("EC generation failed for auction: {err:?}");
-    }
-
     // Parse request body
     let body: AdRequest = serde_json::from_slice(&req.take_body_bytes()).change_context(
         TrustedServerError::Auction {
@@ -56,6 +46,8 @@ pub async fn handle_auction(
         body.ad_units.len()
     );
 
+    // Story 5 middleware contract: auction is a read-only EC route.
+    // It must not generate EC IDs; it only consumes pre-routed context.
     // Only forward the EC ID to auction partners when consent allows it.
     // A returning user may still have a ts-ec cookie but have since
     // withdrawn consent — forwarding that revoked ID to bidders would
diff --git a/crates/trusted-server-core/src/ec/finalize.rs b/crates/trusted-server-core/src/ec/finalize.rs
new file mode 100644
index 00000000..1c2bf71d
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/finalize.rs
@@ -0,0 +1,324 @@
+//! EC response finalization.
+//!
+//! Centralizes post-routing EC behavior so all handlers get consistent cookie
+//! and KV semantics.
+
+use std::collections::HashSet;
+
+use fastly::Response;
+
+use crate::consent::allows_ec_creation;
+use crate::consent::kv::delete_consent_from_kv;
+use crate::constants::HEADER_X_TS_EC;
+use crate::geo::GeoInfo;
+use crate::settings::Settings;
+
+use super::cookies::{expire_ec_cookie, set_ec_cookie};
+use super::generation::{ec_hash, is_valid_ec_id};
+use super::kv::KvIdentityGraph;
+use super::EcContext;
+
+/// TS-managed response headers tied to EC identity output.
+const EC_RESPONSE_HEADERS: &[&str] = &[
+    "x-ts-ec",
+    "x-ts-eids",
+    "x-ts-ec-consent",
+    "x-ts-eids-truncated",
+];
+
+/// Finalizes EC response behavior for all routes.
+///
+/// Applies withdrawal handling, last-seen updates, cookie reconciliation,
+/// and cookie writes for new EC generation.
+pub fn ec_finalize_response(
+    settings: &Settings,
+    _geo_info: Option<&GeoInfo>, // reserved for future route-specific finalize behavior
+    ec_context: &EcContext,
+    kv: Option<&KvIdentityGraph>,
+    response: &mut Response,
+) {
+    let consent_allows_ec = allows_ec_creation(ec_context.consent());
+
+    // Withdrawal path: no consent + cookie was present.
+    if !consent_allows_ec && ec_context.cookie_was_present() {
+        clear_ec_on_response(settings, response);
+
+        if let Some(store_name) = settings.consent.consent_store.as_deref() {
+            for ec_id in withdrawal_ec_ids(ec_context) {
+                delete_consent_from_kv(store_name, &ec_id);
+            }
+        }
+
+        if let Some(graph) = kv {
+            for hash in withdrawal_hashes(ec_context) {
+                if let Err(err) = graph.write_withdrawal_tombstone(&hash) {
+                    log::error!(
+                        "Failed to write withdrawal tombstone for hash '{}': {err:?}",
+                        hash,
+                    );
+                }
+            }
+        }
+
+        return;
+    }
+
+    // Returning user: consent is granted and EC came from request.
+    if ec_context.ec_was_present() && !ec_context.ec_generated() && consent_allows_ec {
+        if let (Some(graph), Some(ec_id)) = (kv, ec_context.ec_value()) {
+            let hash = ec_hash(ec_id);
+            if is_valid_ec_hash(hash) {
+                if let Err(err) = graph.update_last_seen(hash, current_timestamp()) {
+                    log::error!("Failed to update last_seen for hash '{}': {err:?}", hash,);
+                }
+            }
+        }
+
+        // If header/cookie were mismatched, rewrite cookie to active EC value.
+        if ec_context.has_cookie_mismatch() {
+            set_ec_on_response(settings, ec_context, response);
+        }
+
+        return;
+    }
+
+    // Newly generated EC in this request.
+    if ec_context.ec_generated() {
+        set_ec_on_response(settings, ec_context, response);
+    }
+}
+
+/// Sets EC header + cookie on response when an EC ID is available.
+pub fn set_ec_on_response(settings: &Settings, ec_context: &EcContext, response: &mut Response) {
+    if let Some(ec_id) = ec_context.ec_value() {
+        response.set_header(HEADER_X_TS_EC, ec_id);
+        set_ec_cookie(settings, response, ec_id);
+    }
+}
+
+/// Clears EC cookie and removes EC-specific response headers.
+pub fn clear_ec_on_response(settings: &Settings, response: &mut Response) {
+    expire_ec_cookie(settings, response);
+
+    for header in EC_RESPONSE_HEADERS {
+        response.remove_header(*header);
+    }
+}
+
+fn withdrawal_hashes(ec_context: &EcContext) -> HashSet<String> {
+    withdrawal_ec_ids(ec_context)
+        .into_iter()
+        .map(|ec_id| ec_hash(&ec_id).to_owned())
+        .collect()
+}
+
+fn withdrawal_ec_ids(ec_context: &EcContext) -> HashSet<String> {
+    let mut hashes = HashSet::new();
+
+    if let Some(cookie_ec_id) = ec_context.existing_cookie_ec_id() {
+        if is_valid_ec_id(cookie_ec_id) {
+            hashes.insert(cookie_ec_id.to_owned());
+        }
+    }
+
+    if let Some(active_ec_id) = ec_context.ec_value() {
+        if is_valid_ec_id(active_ec_id) {
+            hashes.insert(active_ec_id.to_owned());
+        }
+    }
+
+    hashes
+}
+
+fn is_valid_ec_hash(value: &str) -> bool {
+    value.len() == 64 && value.bytes().all(|b| b.is_ascii_hexdigit())
+}
+
+fn current_timestamp() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::consent::jurisdiction::Jurisdiction;
+    use crate::consent::types::ConsentSource;
+    use crate::test_support::tests::create_test_settings;
+
+    fn make_context(
+        ec_value: Option<&str>,
+        cookie_ec_value: Option<&str>,
+        ec_was_present: bool,
+        ec_generated: bool,
+        jurisdiction: Jurisdiction,
+    ) -> EcContext {
+        let consent = crate::consent::types::ConsentContext {
+            jurisdiction,
+            source: ConsentSource::Cookie,
+            ..Default::default()
+        };
+
+        EcContext {
+            ec_value: ec_value.map(str::to_owned),
+            cookie_ec_value: cookie_ec_value.map(str::to_owned),
+            ec_was_present,
+            ec_generated,
+            consent,
+            client_ip: None,
+            geo_info: None,
+        }
+    }
+
+    fn sample_ec_id(suffix: &str) -> String {
+        format!("{}.{suffix}", "a".repeat(64))
+    }
+
+    #[test]
+    fn clear_ec_on_response_removes_headers_and_expires_cookie() {
+        let settings = create_test_settings();
+        let mut response = Response::new();
+        response.set_header("x-ts-ec", "abc");
+        response.set_header("x-ts-eids", "[]");
+
+        clear_ec_on_response(&settings, &mut response);
+
+        assert!(
+            response.get_header("x-ts-ec").is_none(),
+            "should remove x-ts-ec"
+        );
+        assert!(
+            response.get_header("x-ts-eids").is_none(),
+            "should remove x-ts-eids"
+        );
+
+        let set_cookie = response
+            .get_header("set-cookie")
+            .expect("should append Set-Cookie for expiry")
+            .to_str()
+            .expect("should render set-cookie as utf-8");
+
+        assert!(
+            set_cookie.contains("Max-Age=0"),
+            "should expire the EC cookie"
+        );
+    }
+
+    #[test]
+    fn finalize_withdrawal_clears_cookie_and_headers() {
+        let settings = create_test_settings();
+        let ec_id = sample_ec_id("ABC123");
+        let ec_context = make_context(
+            Some(&ec_id),
+            Some(&ec_id),
+            true,
+            false,
+            Jurisdiction::Unknown,
+        );
+        let mut response = Response::new();
+        response.set_header("x-ts-ec", "stale");
+        response.set_header("x-ts-eids", "[]");
+
+        ec_finalize_response(&settings, None, &ec_context, None, &mut response);
+
+        assert!(
+            response.get_header("x-ts-ec").is_none(),
+            "withdrawal should clear x-ts-ec header"
+        );
+        assert!(
+            response.get_header("x-ts-eids").is_none(),
+            "withdrawal should clear x-ts-eids header"
+        );
+        let set_cookie = response
+            .get_header("set-cookie")
+            .expect("withdrawal should expire cookie")
+            .to_str()
+            .expect("set-cookie should be utf-8");
+        assert!(
+            set_cookie.contains("Max-Age=0"),
+            "withdrawal should set Max-Age=0"
+        );
+    }
+
+    #[test]
+    fn finalize_returning_user_with_cookie_mismatch_rewrites_cookie_and_header() {
+        let settings = create_test_settings();
+        let active_ec = sample_ec_id("ACTIVE1");
+        let cookie_ec = sample_ec_id("COOKIE1");
+        let ec_context = make_context(
+            Some(&active_ec),
+            Some(&cookie_ec),
+            true,
+            false,
+            Jurisdiction::NonRegulated,
+        );
+        let mut response = Response::new();
+
+        ec_finalize_response(&settings, None, &ec_context, None, &mut response);
+
+        let header = response
+            .get_header("x-ts-ec")
+            .expect("mismatch should set x-ts-ec")
+            .to_str()
+            .expect("x-ts-ec should be utf-8");
+        assert_eq!(header, active_ec, "should set active EC on header");
+
+        let set_cookie = response
+            .get_header("set-cookie")
+            .expect("mismatch should rewrite cookie")
+            .to_str()
+            .expect("set-cookie should be utf-8");
+        assert!(
+            set_cookie.contains(&format!("ts-ec={active_ec}")),
+            "cookie should be rewritten to active EC"
+        );
+    }
+
+    #[test]
+    fn finalize_generated_ec_sets_cookie_and_header() {
+        let settings = create_test_settings();
+        let generated_ec = sample_ec_id("GEN123");
+        let ec_context = make_context(
+            Some(&generated_ec),
+            None,
+            false,
+            true,
+            Jurisdiction::NonRegulated,
+        );
+        let mut response = Response::new();
+
+        ec_finalize_response(&settings, None, &ec_context, None, &mut response);
+
+        let header = response
+            .get_header("x-ts-ec")
+            .expect("generated EC should set response header")
+            .to_str()
+            .expect("x-ts-ec should be utf-8");
+        assert_eq!(header, generated_ec, "header should contain generated EC");
+
+        assert!(
+            response.get_header("set-cookie").is_some(),
+            "generated EC should set cookie"
+        );
+    }
+
+    #[test]
+    fn finalize_denied_without_cookie_is_noop() {
+        let settings = create_test_settings();
+        let ec_context = make_context(None, None, false, false, Jurisdiction::Unknown);
+        let mut response = Response::new();
+
+        ec_finalize_response(&settings, None, &ec_context, None, &mut response);
+
+        assert!(
+            response.get_header("x-ts-ec").is_none(),
+            "should not set EC header"
+        );
+        assert!(
+            response.get_header("set-cookie").is_none(),
+            "should not mutate cookie when there is nothing to revoke"
+        );
+    }
+}
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index df5e6289..cb440537 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -24,6 +24,7 @@
 pub mod admin;
 pub mod consent;
 pub mod cookies;
+pub mod finalize;
 pub mod generation;
 pub mod kv;
 pub mod kv_types;
@@ -40,6 +41,9 @@ use crate::error::TrustedServerError;
 use crate::geo::GeoInfo;
 use crate::settings::Settings;
 
+use self::kv::KvIdentityGraph;
+use self::kv_types::KvEntry;
+
 pub use generation::{ec_hash, generate_ec_id, is_valid_ec_id};
 
 /// Parsed EC identity from an incoming request.
@@ -122,6 +126,8 @@ pub struct EcContext {
     /// The normalized client IP, captured early before the request body
     /// is consumed. `None` when the platform cannot determine client IP.
     client_ip: Option<String>,
+    /// Geo information captured pre-routing for downstream KV writes.
+    geo_info: Option<GeoInfo>,
 }
 
 impl EcContext {
@@ -140,6 +146,23 @@ impl EcContext {
     pub fn read_from_request(
         settings: &Settings,
         req: &Request,
+    ) -> Result<Self, Report<TrustedServerError>> {
+        let geo_info = GeoInfo::from_request(req);
+        Self::read_from_request_with_geo(settings, req, geo_info.as_ref())
+    }
+
+    /// Reads EC state from an incoming request using pre-extracted geo data.
+    ///
+    /// Use this when geo has already been resolved in router prelude to avoid
+    /// duplicate lookup work.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if cookie parsing fails.
+    pub fn read_from_request_with_geo(
+        settings: &Settings,
+        req: &Request,
+        geo_info: Option<&GeoInfo>,
     ) -> Result<Self, Report<TrustedServerError>> {
         let parsed = parse_ec_from_request(req)?;
 
@@ -157,12 +180,11 @@ impl EcContext {
 
         // Build consent context. Pass the EC ID (if any) so the consent
         // pipeline can use it for KV Store fallback/write operations.
-        let geo = GeoInfo::from_request(req);
         let consent = consent_mod::build_consent_context(&ConsentPipelineInput {
             jar: parsed.jar.as_ref(),
             req,
             config: &settings.consent,
-            geo: geo.as_ref(),
+            geo: geo_info,
             ec_id: ec_value.as_deref(),
         });
 
@@ -173,6 +195,7 @@ impl EcContext {
             ec_generated: false,
             consent,
             client_ip,
+            geo_info: geo_info.cloned(),
         })
     }
 
@@ -192,6 +215,7 @@ impl EcContext {
     pub fn generate_if_needed(
         &mut self,
         settings: &Settings,
+        kv: Option<&KvIdentityGraph>,
     ) -> Result<(), Report<TrustedServerError>> {
         if self.ec_value.is_some() {
             return Ok(());
@@ -216,6 +240,19 @@ impl EcContext {
         self.ec_value = Some(ec_id);
         self.ec_generated = true;
 
+        if let (Some(graph), Some(ec_value)) = (kv, self.ec_value.as_deref()) {
+            let now = current_timestamp();
+            let entry = KvEntry::new(&self.consent, self.geo_info.as_ref(), now);
+            let ec_hash = generation::ec_hash(ec_value);
+
+            if let Err(err) = graph.create_or_revive(ec_hash, &entry) {
+                log::error!(
+                    "Failed to create or revive EC entry for hash '{}' after generation: {err:?}",
+                    ec_hash,
+                );
+            }
+        }
+
         Ok(())
     }
 
@@ -256,6 +293,12 @@ impl EcContext {
         self.client_ip.as_deref()
     }
 
+    /// Returns the pre-routing geo data, if available.
+    #[must_use]
+    pub fn geo_info(&self) -> Option<&GeoInfo> {
+        self.geo_info.as_ref()
+    }
+
     /// Returns whether EC creation is permitted by consent for this request.
     #[must_use]
     pub fn ec_allowed(&self) -> bool {
@@ -272,6 +315,22 @@ impl EcContext {
     pub fn existing_cookie_ec_id(&self) -> Option<&str> {
         self.cookie_ec_value.as_deref()
     }
+
+    /// Returns true when both cookie and active EC are present and differ.
+    #[must_use]
+    pub fn has_cookie_mismatch(&self) -> bool {
+        matches!(
+            (self.cookie_ec_value.as_deref(), self.ec_value.as_deref()),
+            (Some(cookie), Some(active)) if cookie != active
+        )
+    }
+}
+
+fn current_timestamp() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0)
 }
 
 #[cfg(test)]
@@ -350,7 +409,7 @@ mod tests {
         let req = create_test_request(&[("x-ts-ec", "existing-id")]);
 
         let mut ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
-        ec.generate_if_needed(&settings)
+        ec.generate_if_needed(&settings, None)
             .expect("should not error when EC already exists");
 
         assert_eq!(
diff --git a/crates/trusted-server-core/src/integrations/registry.rs b/crates/trusted-server-core/src/integrations/registry.rs
index 9ef94264..c3c824be 100644
--- a/crates/trusted-server-core/src/integrations/registry.rs
+++ b/crates/trusted-server-core/src/integrations/registry.rs
@@ -9,7 +9,7 @@ use fastly::{Request, Response};
 use matchit::Router;
 
 use crate::constants::HEADER_X_TS_EC;
-use crate::ec::cookies::{expire_ec_cookie, set_ec_cookie};
+use crate::ec::kv::KvIdentityGraph;
 use crate::ec::EcContext;
 use crate::error::TrustedServerError;
 use crate::settings::Settings;
@@ -644,61 +644,30 @@ impl IntegrationRegistry {
 
     /// Dispatch a proxy request when an integration handles the path.
     ///
-    /// This method automatically sets the `x-ts-ec` header and
-    /// `ts-ec` cookie on successful responses.
+    /// This method sets request-side `x-ts-ec` for integration backends.
+    /// Response-side cookie/header mutation is centralized in EC finalize.
     #[must_use]
     pub async fn handle_proxy(
         &self,
         method: &Method,
         path: &str,
         settings: &Settings,
+        kv: Option<&KvIdentityGraph>,
+        ec_context: &mut EcContext,
         mut req: Request,
     ) -> Option<Result<Response, Report<TrustedServerError>>> {
         if let Some((proxy, _)) = self.find_route(method, path) {
-            // Read EC state and generate if needed before consuming request.
-            let ec_context = match EcContext::read_from_request(settings, &req) {
-                Ok(mut ec) => {
-                    if let Err(err) = ec.generate_if_needed(settings) {
-                        log::warn!("EC generation failed for integration proxy: {err:?}");
-                    }
-                    Some(ec)
-                }
-                Err(err) => {
-                    log::warn!("Failed to read EC context for integration proxy: {err:?}");
-                    None
-                }
-            };
+            // Organic proxy handler: generate if needed (best effort).
+            if let Err(err) = ec_context.generate_if_needed(settings, kv) {
+                log::warn!("EC generation failed for integration proxy: {err:?}");
+            }
 
             // Set EC ID header on the request so integrations can read it.
-            if let Some(ec_id) = ec_context.as_ref().and_then(|ec| ec.ec_value()) {
+            if let Some(ec_id) = ec_context.ec_value() {
                 req.set_header(HEADER_X_TS_EC, ec_id);
             }
 
-            let mut result = proxy.handle(settings, req).await;
-
-            // Consent-gated EC on successful responses:
-            // - Consent given → set header + cookie.
-            // - Consent denied + existing cookie → expire cookie (revoke).
-            // - Otherwise → set header only (for internal use).
-            if let Ok(ref mut response) = result {
-                if let Some(ref ec) = ec_context {
-                    if let Some(ec_id) = ec.ec_value() {
-                        response.set_header(HEADER_X_TS_EC, ec_id);
-                        if ec.ec_allowed() {
-                            set_ec_cookie(settings, response, ec_id);
-                        }
-                    }
-                    if !ec.ec_allowed() {
-                        if let Some(cookie_ec_id) = ec.existing_cookie_ec_id() {
-                            log::info!(
-                                "EC revoked for '{cookie_ec_id}': consent withdrawn on integration proxy"
-                            );
-                            expire_ec_cookie(settings, response);
-                        }
-                    }
-                }
-            }
-            Some(result)
+            Some(proxy.handle(settings, req).await)
         } else {
             None
         }
@@ -1253,16 +1222,21 @@ mod tests {
         async fn handle(
             &self,
             _settings: &Settings,
-            _req: Request,
+            req: Request,
         ) -> Result<Response, Report<TrustedServerError>> {
-            // Return a simple response without the EC ID header.
-            // The registry's handle_proxy should add it.
-            Ok(Response::from_status(fastly::http::StatusCode::OK).with_body("test response"))
+            let mut response =
+                Response::from_status(fastly::http::StatusCode::OK).with_body("test response");
+
+            if let Some(ec) = req.get_header(HEADER_X_TS_EC) {
+                response.set_header("x-echo-ts-ec", ec);
+            }
+
+            Ok(response)
         }
     }
 
     #[test]
-    fn handle_proxy_sets_ec_id_header_on_response() {
+    fn handle_proxy_sets_ec_id_header_on_request() {
         let settings = create_test_settings();
         let routes = vec![(
             Method::GET,
@@ -1278,12 +1252,16 @@ mod tests {
         // the test environment, so generation would fail).
         let mut req = Request::get("https://test-publisher.com/integrations/test/ec");
         req.set_header("x-ts-ec", "test-ec-id-from-header");
+        let mut ec_context =
+            EcContext::read_from_request(&settings, &req).expect("should read EC context");
 
         // Call handle_proxy (uses futures executor in test environment)
         let result = futures::executor::block_on(registry.handle_proxy(
             &Method::GET,
             "/integrations/test/ec",
             &settings,
+            None,
+            &mut ec_context,
             req,
         ));
 
@@ -1294,23 +1272,15 @@ mod tests {
 
         let response = response.unwrap();
 
-        // The x-ts-ec header is always set for internal use by downstream
-        // integrations, regardless of consent.
-        assert!(
-            response.get_header(HEADER_X_TS_EC).is_some(),
-            "should have x-ts-ec header on response"
-        );
-
-        // Without geo data, jurisdiction is Unknown → consent denied
-        // (fail-closed). The Set-Cookie header should not be set.
+        // The x-ts-ec header should be set on outbound integration request.
         assert!(
-            response.get_header(header::SET_COOKIE).is_none(),
-            "should not set Set-Cookie when consent is denied"
+            response.get_header("x-echo-ts-ec").is_some(),
+            "should have x-ts-ec header on integration request"
         );
     }
 
     #[test]
-    fn handle_proxy_skips_cookie_when_consent_denied() {
+    fn handle_proxy_keeps_request_ec_even_when_consent_denied() {
         let settings = create_test_settings();
         let routes = vec![(
             Method::GET,
@@ -1323,32 +1293,25 @@ mod tests {
         let mut req = Request::get("https://test.example.com/integrations/test/ec");
         // Pre-existing cookie, but no geo data → Unknown jurisdiction → consent denied.
         req.set_header(header::COOKIE, "ts-ec=existing_id_12345");
+        let mut ec_context =
+            EcContext::read_from_request(&settings, &req).expect("should read EC context");
 
         let result = futures::executor::block_on(registry.handle_proxy(
             &Method::GET,
             "/integrations/test/ec",
             &settings,
+            None,
+            &mut ec_context,
             req,
         ))
         .expect("should handle proxy request");
 
         let response = result.expect("proxy handle should succeed");
 
-        // The x-ts-ec header is always set (for internal use by integrations).
-        assert!(
-            response.get_header(HEADER_X_TS_EC).is_some(),
-            "should still have x-ts-ec header for internal use"
-        );
-
-        // Without geo data, jurisdiction is Unknown and consent is denied
-        // (fail-closed). An existing cookie should be expired (revoked).
-        let set_cookie = response
-            .get_header(header::SET_COOKIE)
-            .expect("should have Set-Cookie header to expire the existing cookie");
-        let cookie_str = set_cookie.to_str().expect("should be valid UTF-8");
+        // The x-ts-ec request header is still set for integration request flow.
         assert!(
-            cookie_str.contains("Max-Age=0"),
-            "should expire the EC cookie when consent is denied, got: {cookie_str}"
+            response.get_header("x-echo-ts-ec").is_some(),
+            "should still set x-ts-ec on integration request"
         );
     }
 
@@ -1368,11 +1331,15 @@ mod tests {
         let mut req =
             Request::post("https://test-publisher.com/integrations/test/ec").with_body("test body");
         req.set_header("x-ts-ec", "test-ec-id-from-header");
+        let mut ec_context =
+            EcContext::read_from_request(&settings, &req).expect("should read EC context");
 
         let result = futures::executor::block_on(registry.handle_proxy(
             &Method::POST,
             "/integrations/test/ec",
             &settings,
+            None,
+            &mut ec_context,
             req,
         ));
 
@@ -1382,8 +1349,8 @@ mod tests {
 
         let response = response.unwrap();
         assert!(
-            response.get_header(HEADER_X_TS_EC).is_some(),
-            "POST response should have x-ts-ec header"
+            response.get_header("x-echo-ts-ec").is_some(),
+            "POST integration request should include x-ts-ec"
         );
     }
 
diff --git a/crates/trusted-server-core/src/publisher.rs b/crates/trusted-server-core/src/publisher.rs
index e2d724cf..70452635 100644
--- a/crates/trusted-server-core/src/publisher.rs
+++ b/crates/trusted-server-core/src/publisher.rs
@@ -3,8 +3,8 @@ use fastly::http::{header, StatusCode};
 use fastly::{Body, Request, Response};
 
 use crate::backend::BackendConfig;
-use crate::constants::{HEADER_X_COMPRESS_HINT, HEADER_X_TS_EC};
-use crate::ec::cookies::{expire_ec_cookie, set_ec_cookie};
+use crate::constants::HEADER_X_COMPRESS_HINT;
+use crate::ec::kv::KvIdentityGraph;
 use crate::ec::EcContext;
 use crate::error::TrustedServerError;
 use crate::http_util::{serve_static_with_etag, RequestInfo};
@@ -289,7 +289,8 @@ fn create_html_stream_processor(
 pub fn handle_publisher_request(
     settings: &Settings,
     integration_registry: &IntegrationRegistry,
-    services: &RuntimeServices,
+    kv: Option<&KvIdentityGraph>,
+    ec_context: &mut EcContext,
     mut req: Request,
 ) -> Result<Response, Report<TrustedServerError>> {
     log::debug!("Proxying request to publisher_origin");
@@ -311,13 +312,9 @@ pub fn handle_publisher_request(
         req.get_header("x-forwarded-proto"),
     );
 
-    // Read EC state from the request (existing ID, consent, client IP).
-    // This must happen before the request body is consumed.
-    let mut ec_context = EcContext::read_from_request(settings, &req)?;
-
     // Generate a new EC ID if none exists and consent allows it.
     // This is an organic handler, so generation is permitted here.
-    if let Err(err) = ec_context.generate_if_needed(settings) {
+    if let Err(err) = ec_context.generate_if_needed(settings, kv) {
         log::warn!("EC generation failed: {err:?}");
     }
 
@@ -423,31 +420,6 @@ pub fn handle_publisher_request(
         );
     }
 
-    // Consent-gated EC creation:
-    // - Consent given → set EC ID header + cookie.
-    // - Consent absent + existing cookie → revoke (expire cookie + delete KV entry).
-    // - Consent absent + no cookie → do nothing.
-    if ec_allowed {
-        if let Some(ec_id) = ec_context.ec_value() {
-            response.set_header(HEADER_X_TS_EC, ec_id);
-            set_ec_cookie(settings, &mut response, ec_id);
-        }
-    } else if let Some(cookie_ec_id) = ec_context.existing_cookie_ec_id() {
-        log::info!(
-            "EC revoked for '{cookie_ec_id}': consent withdrawn (jurisdiction={})",
-            ec_context.consent().jurisdiction,
-        );
-        expire_ec_cookie(settings, &mut response);
-        if settings.consent.consent_store.is_some() {
-            crate::consent::kv::delete_consent_from_kv(services.kv_store(), cookie_ec_id);
-        }
-    } else {
-        log::debug!(
-            "EC skipped: no consent and no existing cookie (jurisdiction={})",
-            ec_context.consent().jurisdiction,
-        );
-    }
-
     Ok(response)
 }
 
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index e5d5ead5..ffb13882 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -153,12 +153,12 @@ Core publisher settings for domain, origin, and proxy configuration.
 
 ### `[publisher]`
 
-| Field           | Type   | Required | Description                                             |
-| --------------- | ------ | -------- | ------------------------------------------------------- |
-| `domain`        | String | Yes      | Publisher's apex domain name                            |
-| `cookie_domain` | String | Yes      | Domain for non-EC cookies (typically with leading dot)  |
-| `origin_url`    | String | Yes      | Full URL of publisher origin server                     |
-| `proxy_secret`  | String | Yes      | Secret key for encrypting/signing proxy URLs            |
+| Field           | Type   | Required | Description                                            |
+| --------------- | ------ | -------- | ------------------------------------------------------ |
+| `domain`        | String | Yes      | Publisher's apex domain name                           |
+| `cookie_domain` | String | Yes      | Domain for non-EC cookies (typically with leading dot) |
+| `origin_url`    | String | Yes      | Full URL of publisher origin server                    |
+| `proxy_secret`  | String | Yes      | Secret key for encrypting/signing proxy URLs           |
 
 > **Note:** EC cookies (`ts-ec`) derive their domain automatically as `.{domain}` and
 > do not use `cookie_domain`. The `cookie_domain` field is used by other cookie helpers.
@@ -270,11 +270,11 @@ Settings for generating privacy-preserving Edge Cookie identifiers.
 
 ### `[ec]`
 
-| Field           | Type            | Required | Description                                      |
-| --------------- | --------------- | -------- | ------------------------------------------------ |
-| `passphrase`    | String          | Yes      | Publisher passphrase used as HMAC key             |
-| `ec_store`      | String or null  | No       | Fastly KV store name for EC identity graph        |
-| `partner_store` | String or null  | No       | Fastly KV store name for partner registry         |
+| Field           | Type           | Required | Description                                |
+| --------------- | -------------- | -------- | ------------------------------------------ |
+| `passphrase`    | String         | Yes      | Publisher passphrase used as HMAC key      |
+| `ec_store`      | String or null | No       | Fastly KV store name for EC identity graph |
+| `partner_store` | String or null | No       | Fastly KV store name for partner registry  |
 
 **Example**:
 

From 16a13b77aed4777501cb48686a76f78d7bced2d4 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Tue, 24 Mar 2026 16:02:37 -0500
Subject: [PATCH 07/36] Add EC sync and identify endpoints

---
 .../trusted-server-adapter-fastly/src/main.rs |  28 +
 crates/trusted-server-core/src/constants.rs   |   6 +
 crates/trusted-server-core/src/ec/identify.rs | 512 ++++++++++++++++++
 crates/trusted-server-core/src/ec/mod.rs      |  19 +
 .../trusted-server-core/src/ec/sync_pixel.rs  | 432 +++++++++++++++
 5 files changed, 997 insertions(+)
 create mode 100644 crates/trusted-server-core/src/ec/identify.rs
 create mode 100644 crates/trusted-server-core/src/ec/sync_pixel.rs

diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 10a73eb0..b3ff2582 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -12,8 +12,10 @@ use trusted_server_core::constants::{
 };
 use trusted_server_core::ec::admin::handle_register_partner;
 use trusted_server_core::ec::finalize::ec_finalize_response;
+use trusted_server_core::ec::identify::{cors_preflight_identify, handle_identify};
 use trusted_server_core::ec::kv::KvIdentityGraph;
 use trusted_server_core::ec::partner::PartnerStore;
+use trusted_server_core::ec::sync_pixel::handle_sync;
 use trusted_server_core::ec::EcContext;
 use trusted_server_core::error::TrustedServerError;
 use trusted_server_core::geo::GeoInfo;
@@ -170,6 +172,18 @@ async fn route_request(
             require_partner_store(settings).and_then(|store| handle_register_partner(&store, req))
         }
 
+        (Method::GET, "/sync") => require_identity_graph(settings).and_then(|kv| {
+            require_partner_store(settings).and_then(|partner_store| {
+                handle_sync(settings, &kv, &partner_store, &req, &mut ec_context)
+            })
+        }),
+        (Method::GET, "/identify") => require_identity_graph(settings).and_then(|kv| {
+            require_partner_store(settings).and_then(|partner_store| {
+                handle_identify(settings, &kv, &partner_store, &req, &ec_context)
+            })
+        }),
+        (Method::OPTIONS, "/identify") => cors_preflight_identify(settings, &req),
+
         // Unified auction endpoint (returns creative HTML inline)
         (Method::POST, "/auction") => {
             handle_auction(settings, orchestrator, kv_graph.as_ref(), &ec_context, req).await
@@ -301,3 +315,17 @@ fn require_partner_store(settings: &Settings) -> Result<PartnerStore, Report<Tru
     })?;
     Ok(PartnerStore::new(store_name))
 }
+
+/// Constructs a `KvIdentityGraph` from settings, or returns 503 if the
+/// `ec_store` config is not set.
+fn require_identity_graph(
+    settings: &Settings,
+) -> Result<KvIdentityGraph, Report<TrustedServerError>> {
+    let store_name = settings.ec.ec_store.as_deref().ok_or_else(|| {
+        Report::new(TrustedServerError::KvStore {
+            store_name: "ec.ec_store".to_owned(),
+            message: "ec.ec_store is not configured".to_owned(),
+        })
+    })?;
+    Ok(KvIdentityGraph::new(store_name))
+}
diff --git a/crates/trusted-server-core/src/constants.rs b/crates/trusted-server-core/src/constants.rs
index 0294cd25..d7047a4c 100644
--- a/crates/trusted-server-core/src/constants.rs
+++ b/crates/trusted-server-core/src/constants.rs
@@ -4,6 +4,9 @@ pub const COOKIE_TS_EC: &str = "ts-ec";
 
 pub const HEADER_X_PUB_USER_ID: HeaderName = HeaderName::from_static("x-pub-user-id");
 pub const HEADER_X_TS_EC: HeaderName = HeaderName::from_static("x-ts-ec");
+pub const HEADER_X_TS_EIDS: HeaderName = HeaderName::from_static("x-ts-eids");
+pub const HEADER_X_TS_EC_CONSENT: HeaderName = HeaderName::from_static("x-ts-ec-consent");
+pub const HEADER_X_TS_EIDS_TRUNCATED: HeaderName = HeaderName::from_static("x-ts-eids-truncated");
 pub const HEADER_X_CONSENT_ADVERTISING: HeaderName =
     HeaderName::from_static("x-consent-advertising");
 pub const HEADER_X_FORWARDED_FOR: HeaderName = HeaderName::from_static("x-forwarded-for");
@@ -44,6 +47,9 @@ pub const HEADER_REFERER: HeaderName = HeaderName::from_static("referer");
 /// in `const` context.
 pub const INTERNAL_HEADERS: &[&str] = &[
     "x-ts-ec",
+    "x-ts-eids",
+    "x-ts-ec-consent",
+    "x-ts-eids-truncated",
     "x-pub-user-id",
     "x-subject-id",
     "x-consent-advertising",
diff --git a/crates/trusted-server-core/src/ec/identify.rs b/crates/trusted-server-core/src/ec/identify.rs
new file mode 100644
index 00000000..d25fdd1c
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/identify.rs
@@ -0,0 +1,512 @@
+//! Identity lookup endpoint (`GET /identify`).
+
+use std::collections::HashMap;
+
+use base64::{engine::general_purpose::STANDARD as BASE64, Engine as _};
+use error_stack::{Report, ResultExt};
+use fastly::http::{header, StatusCode};
+use fastly::{Request, Response};
+use url::Url;
+
+use crate::consent::allows_ec_creation;
+use crate::constants::{
+    HEADER_X_TS_EC, HEADER_X_TS_EC_CONSENT, HEADER_X_TS_EIDS, HEADER_X_TS_EIDS_TRUNCATED,
+};
+use crate::error::TrustedServerError;
+use crate::openrtb::{Eid, Uid};
+use crate::settings::Settings;
+
+use super::kv::KvIdentityGraph;
+use super::kv_types::KvEntry;
+use super::partner::PartnerStore;
+use super::EcContext;
+
+const MAX_EXPOSE_PARTNER_HEADERS: usize = 20;
+const MAX_EIDS_HEADER_BYTES: usize = 4096;
+
+/// Handles `GET /identify`.
+///
+/// # Errors
+///
+/// Returns [`TrustedServerError`] for response serialization issues.
+pub fn handle_identify(
+    settings: &Settings,
+    kv: &KvIdentityGraph,
+    partner_store: &PartnerStore,
+    req: &Request,
+    ec_context: &EcContext,
+) -> Result<Response, Report<TrustedServerError>> {
+    let cors = classify_origin(req, settings);
+    if matches!(cors, CorsDecision::Denied) {
+        return Ok(Response::from_status(StatusCode::FORBIDDEN));
+    }
+
+    if !allows_ec_creation(ec_context.consent()) {
+        let mut response = json_response(
+            StatusCode::FORBIDDEN,
+            &serde_json::json!({ "consent": "denied" }),
+        )?;
+        if let CorsDecision::Allowed(origin) = cors {
+            apply_cors_headers(&mut response, &origin);
+        }
+        return Ok(response);
+    }
+
+    let Some(ec_id) = ec_context.ec_value() else {
+        let mut response = Response::from_status(StatusCode::NO_CONTENT);
+        if let CorsDecision::Allowed(origin) = cors {
+            apply_cors_headers(&mut response, &origin);
+        }
+        return Ok(response);
+    };
+
+    let mut degraded = false;
+    let mut resolved = Vec::new();
+
+    if let Some(ec_hash) = ec_context.ec_hash() {
+        match kv.get(ec_hash) {
+            Ok(Some((entry, _generation))) => match resolve_partner_ids(partner_store, &entry) {
+                Ok(values) => {
+                    resolved = values;
+                }
+                Err(err) => {
+                    log::warn!("Identify partner resolution failed: {err:?}");
+                    degraded = true;
+                }
+            },
+            Ok(None) => {}
+            Err(err) => {
+                log::warn!("Identify KV read failed for hash '{ec_hash}': {err:?}");
+                degraded = true;
+            }
+        }
+    }
+
+    let mut uids = HashMap::new();
+    for item in &resolved {
+        uids.insert(item.partner_id.clone(), item.uid.clone());
+    }
+
+    let eids = to_eids(&resolved);
+    let body = IdentifyResponse {
+        ec: ec_id.to_owned(),
+        consent: "ok".to_owned(),
+        degraded,
+        uids,
+        eids,
+    };
+
+    let mut response = json_response(StatusCode::OK, &body)?;
+    response.set_header(HEADER_X_TS_EC, ec_id);
+    response.set_header(HEADER_X_TS_EC_CONSENT, "ok");
+
+    let mut expose_headers = vec![
+        "x-ts-ec".to_owned(),
+        "x-ts-eids".to_owned(),
+        "x-ts-ec-consent".to_owned(),
+        "x-ts-eids-truncated".to_owned(),
+    ];
+
+    for item in resolved.iter().take(MAX_EXPOSE_PARTNER_HEADERS) {
+        let header_name = format!("x-ts-{}", item.partner_id);
+        response.set_header(&header_name, &item.uid);
+        expose_headers.push(header_name);
+    }
+
+    let (encoded_eids, truncated) = build_eids_header(&resolved)?;
+    response.set_header(HEADER_X_TS_EIDS, encoded_eids);
+    if truncated {
+        response.set_header(HEADER_X_TS_EIDS_TRUNCATED, "true");
+    }
+
+    if let CorsDecision::Allowed(origin) = cors {
+        apply_cors_headers(&mut response, &origin);
+        response.set_header(
+            header::ACCESS_CONTROL_EXPOSE_HEADERS,
+            expose_headers.join(", "),
+        );
+    }
+
+    Ok(response)
+}
+
+/// Handles `OPTIONS /identify` CORS preflight.
+///
+/// # Errors
+///
+/// Returns [`TrustedServerError`] when response construction fails.
+pub fn cors_preflight_identify(
+    settings: &Settings,
+    req: &Request,
+) -> Result<Response, Report<TrustedServerError>> {
+    let mut response = match classify_origin(req, settings) {
+        CorsDecision::Denied => Response::from_status(StatusCode::FORBIDDEN),
+        CorsDecision::NoOrigin => Response::from_status(StatusCode::OK),
+        CorsDecision::Allowed(origin) => {
+            let mut response = Response::from_status(StatusCode::OK);
+            apply_cors_headers(&mut response, &origin);
+            response
+        }
+    };
+
+    response.set_body(Vec::new());
+    Ok(response)
+}
+
+#[derive(serde::Serialize)]
+struct IdentifyResponse {
+    ec: String,
+    consent: String,
+    degraded: bool,
+    uids: HashMap<String, String>,
+    eids: Vec<Eid>,
+}
+
+struct ResolvedPartnerId {
+    partner_id: String,
+    uid: String,
+    synced: u64,
+    source_domain: String,
+    openrtb_atype: u8,
+}
+
+fn resolve_partner_ids(
+    partner_store: &PartnerStore,
+    entry: &KvEntry,
+) -> Result<Vec<ResolvedPartnerId>, Report<TrustedServerError>> {
+    let mut resolved = Vec::new();
+
+    for (partner_id, partner_uid) in &entry.ids {
+        if partner_uid.uid.is_empty() {
+            continue;
+        }
+
+        let Some(partner) = partner_store.get(partner_id)? else {
+            continue;
+        };
+        if !partner.bidstream_enabled {
+            continue;
+        }
+
+        resolved.push(ResolvedPartnerId {
+            partner_id: partner_id.clone(),
+            uid: partner_uid.uid.clone(),
+            synced: partner_uid.synced,
+            source_domain: partner.source_domain,
+            openrtb_atype: partner.openrtb_atype,
+        });
+    }
+
+    resolved.sort_by(|a, b| b.synced.cmp(&a.synced));
+    Ok(resolved)
+}
+
+fn to_eids(resolved: &[ResolvedPartnerId]) -> Vec<Eid> {
+    resolved
+        .iter()
+        .map(|item| Eid {
+            source: item.source_domain.clone(),
+            uids: vec![Uid {
+                id: item.uid.clone(),
+                atype: Some(item.openrtb_atype),
+                ext: None,
+            }],
+        })
+        .collect()
+}
+
+fn build_eids_header(
+    resolved: &[ResolvedPartnerId],
+) -> Result<(String, bool), Report<TrustedServerError>> {
+    for size in (0..=resolved.len()).rev() {
+        let eids = to_eids(&resolved[..size]);
+        let json = serde_json::to_vec(&eids).change_context(TrustedServerError::Configuration {
+            message: "Failed to serialize identify eids header payload".to_owned(),
+        })?;
+        let encoded = BASE64.encode(json);
+
+        if encoded.len() <= MAX_EIDS_HEADER_BYTES {
+            return Ok((encoded, size != resolved.len()));
+        }
+    }
+
+    Ok((BASE64.encode("[]"), true))
+}
+
+fn json_response<T: serde::Serialize>(
+    status: StatusCode,
+    body: &T,
+) -> Result<Response, Report<TrustedServerError>> {
+    let body = serde_json::to_string(body).change_context(TrustedServerError::Configuration {
+        message: "Failed to serialize identify response".to_owned(),
+    })?;
+
+    Ok(Response::from_status(status)
+        .with_content_type(fastly::mime::APPLICATION_JSON)
+        .with_body(body))
+}
+
+enum CorsDecision {
+    NoOrigin,
+    Allowed(String),
+    Denied,
+}
+
+fn classify_origin(req: &Request, settings: &Settings) -> CorsDecision {
+    let Some(origin) = req.get_header(header::ORIGIN).and_then(|v| v.to_str().ok()) else {
+        return CorsDecision::NoOrigin;
+    };
+
+    let Ok(origin_url) = Url::parse(origin) else {
+        return CorsDecision::Denied;
+    };
+
+    let Some(host) = origin_url.host_str() else {
+        return CorsDecision::Denied;
+    };
+
+    let host = host.to_ascii_lowercase();
+    let publisher_host = settings
+        .publisher
+        .domain
+        .trim_end_matches('.')
+        .to_ascii_lowercase();
+
+    if host == publisher_host || host.ends_with(&format!(".{publisher_host}")) {
+        return CorsDecision::Allowed(origin.to_owned());
+    }
+
+    CorsDecision::Denied
+}
+
+fn apply_cors_headers(response: &mut Response, origin: &str) {
+    response.set_header(header::ACCESS_CONTROL_ALLOW_ORIGIN, origin);
+    response.set_header(header::ACCESS_CONTROL_ALLOW_CREDENTIALS, "true");
+    response.set_header(header::ACCESS_CONTROL_ALLOW_METHODS, "GET, OPTIONS");
+    response.set_header(
+        header::ACCESS_CONTROL_ALLOW_HEADERS,
+        "Cookie, X-ts-ec, X-consent-advertising",
+    );
+    response.set_header(header::VARY, "Origin");
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::consent::jurisdiction::Jurisdiction;
+    use crate::consent::types::{ConsentContext, ConsentSource};
+    use crate::test_support::tests::create_test_settings;
+
+    fn make_ec_context(jurisdiction: Jurisdiction, ec_value: Option<&str>) -> EcContext {
+        EcContext {
+            ec_value: ec_value.map(str::to_owned),
+            cookie_ec_value: ec_value.map(str::to_owned),
+            ec_was_present: ec_value.is_some(),
+            ec_generated: false,
+            consent: ConsentContext {
+                jurisdiction,
+                source: ConsentSource::Cookie,
+                ..ConsentContext::default()
+            },
+            client_ip: None,
+            geo_info: None,
+        }
+    }
+
+    #[test]
+    fn classify_origin_accepts_publisher_subdomain() {
+        let settings = create_test_settings();
+        let mut req = Request::new("GET", "https://edge.test-publisher.com/identify");
+        req.set_header("origin", "https://www.test-publisher.com");
+
+        let decision = classify_origin(&req, &settings);
+        assert!(
+            matches!(decision, CorsDecision::Allowed(_)),
+            "should allow publisher subdomain origin"
+        );
+    }
+
+    #[test]
+    fn classify_origin_rejects_mismatch() {
+        let settings = create_test_settings();
+        let mut req = Request::new("GET", "https://edge.test-publisher.com/identify");
+        req.set_header("origin", "https://evil.com");
+
+        let decision = classify_origin(&req, &settings);
+        assert!(
+            matches!(decision, CorsDecision::Denied),
+            "should deny mismatched origin"
+        );
+    }
+
+    #[test]
+    fn classify_origin_allows_absent_origin_header() {
+        let settings = create_test_settings();
+        let req = Request::new("GET", "https://edge.test-publisher.com/identify");
+
+        let decision = classify_origin(&req, &settings);
+        assert!(
+            matches!(decision, CorsDecision::NoOrigin),
+            "should allow no-origin requests"
+        );
+    }
+
+    #[test]
+    fn eids_header_truncates_when_too_large() {
+        let mut resolved = Vec::new();
+        for idx in 0..64 {
+            resolved.push(ResolvedPartnerId {
+                partner_id: format!("p{idx}"),
+                uid: "x".repeat(200),
+                synced: 1000 - idx,
+                source_domain: format!("s{idx}.example.com"),
+                openrtb_atype: 3,
+            });
+        }
+
+        let (header, truncated) =
+            build_eids_header(&resolved).expect("should build capped eids header");
+        assert!(truncated, "should truncate oversized eids header payload");
+        assert!(
+            header.len() <= MAX_EIDS_HEADER_BYTES,
+            "should cap encoded header bytes"
+        );
+    }
+
+    #[test]
+    fn handle_identify_denied_consent_returns_403_json() {
+        let settings = create_test_settings();
+        let kv = KvIdentityGraph::new("missing_store");
+        let partner_store = PartnerStore::new("missing_store");
+        let mut req = Request::new("GET", "https://edge.test-publisher.com/identify");
+        req.set_header("origin", "https://www.test-publisher.com");
+        let ec_context = make_ec_context(Jurisdiction::Unknown, None);
+
+        let mut response = handle_identify(&settings, &kv, &partner_store, &req, &ec_context)
+            .expect("should construct denied response");
+
+        assert_eq!(
+            response.get_status(),
+            StatusCode::FORBIDDEN,
+            "should return 403 when consent denies EC"
+        );
+        assert_eq!(
+            response
+                .get_header(header::ACCESS_CONTROL_ALLOW_ORIGIN)
+                .and_then(|v| v.to_str().ok()),
+            Some("https://www.test-publisher.com"),
+            "should include CORS allow-origin for approved publisher origin"
+        );
+
+        let body = serde_json::from_slice::<serde_json::Value>(&response.take_body_bytes())
+            .expect("should decode denied JSON body");
+        assert_eq!(
+            body,
+            serde_json::json!({ "consent": "denied" }),
+            "should return denied consent payload"
+        );
+    }
+
+    #[test]
+    fn handle_identify_without_ec_returns_204() {
+        let settings = create_test_settings();
+        let kv = KvIdentityGraph::new("missing_store");
+        let partner_store = PartnerStore::new("missing_store");
+        let mut req = Request::new("GET", "https://edge.test-publisher.com/identify");
+        req.set_header("origin", "https://www.test-publisher.com");
+        let ec_context = make_ec_context(Jurisdiction::NonRegulated, None);
+
+        let response = handle_identify(&settings, &kv, &partner_store, &req, &ec_context)
+            .expect("should construct no-content response");
+
+        assert_eq!(
+            response.get_status(),
+            StatusCode::NO_CONTENT,
+            "should return 204 when EC is unavailable"
+        );
+        assert_eq!(
+            response
+                .get_header(header::ACCESS_CONTROL_ALLOW_ORIGIN)
+                .and_then(|v| v.to_str().ok()),
+            Some("https://www.test-publisher.com"),
+            "should include CORS allow-origin for approved publisher origin"
+        );
+    }
+
+    #[test]
+    fn handle_identify_kv_failure_sets_degraded_true() {
+        let settings = create_test_settings();
+        let kv = KvIdentityGraph::new("missing_store");
+        let partner_store = PartnerStore::new("missing_store");
+        let req = Request::new("GET", "https://edge.test-publisher.com/identify");
+        let ec_id = format!("{}.ABC123", "a".repeat(64));
+        let ec_context = make_ec_context(Jurisdiction::NonRegulated, Some(&ec_id));
+
+        let mut response = handle_identify(&settings, &kv, &partner_store, &req, &ec_context)
+            .expect("should construct degraded identify response");
+
+        assert_eq!(
+            response.get_status(),
+            StatusCode::OK,
+            "should return 200 on degraded KV read"
+        );
+        let body = serde_json::from_slice::<serde_json::Value>(&response.take_body_bytes())
+            .expect("should decode identify response JSON");
+
+        assert_eq!(body["ec"], ec_id, "should echo EC in body");
+        assert_eq!(
+            body["degraded"],
+            serde_json::Value::Bool(true),
+            "should mark response as degraded when KV read fails"
+        );
+        assert_eq!(
+            body["uids"],
+            serde_json::json!({}),
+            "should emit empty uids"
+        );
+        assert_eq!(
+            body["eids"],
+            serde_json::json!([]),
+            "should emit empty eids"
+        );
+    }
+
+    #[test]
+    fn identify_preflight_denies_mismatched_origin() {
+        let settings = create_test_settings();
+        let mut req = Request::new("OPTIONS", "https://edge.test-publisher.com/identify");
+        req.set_header("origin", "https://evil.example");
+
+        let response =
+            cors_preflight_identify(&settings, &req).expect("should construct preflight response");
+
+        assert_eq!(
+            response.get_status(),
+            StatusCode::FORBIDDEN,
+            "should reject preflight from non-publisher origin"
+        );
+    }
+
+    #[test]
+    fn identify_preflight_allows_publisher_origin() {
+        let settings = create_test_settings();
+        let mut req = Request::new("OPTIONS", "https://edge.test-publisher.com/identify");
+        req.set_header("origin", "https://www.test-publisher.com");
+
+        let response =
+            cors_preflight_identify(&settings, &req).expect("should construct preflight response");
+
+        assert_eq!(
+            response.get_status(),
+            StatusCode::OK,
+            "should allow preflight from publisher origin"
+        );
+        assert_eq!(
+            response
+                .get_header(header::ACCESS_CONTROL_ALLOW_ORIGIN)
+                .and_then(|v| v.to_str().ok()),
+            Some("https://www.test-publisher.com"),
+            "should include CORS allow-origin header"
+        );
+    }
+}
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index cb440537..d7dfe480 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -20,15 +20,19 @@
 //! - [`kv_types`] — Schema types for KV identity graph entries
 //! - [`partner`] — Partner registry (`PartnerRecord`, `PartnerStore`)
 //! - [`admin`] — Admin endpoints for partner management
+//! - [`sync_pixel`] — Pixel sync write endpoint (`GET /sync`)
+//! - [`identify`] — Browser identity read endpoint (`GET /identify`)
 
 pub mod admin;
 pub mod consent;
 pub mod cookies;
 pub mod finalize;
 pub mod generation;
+pub mod identify;
 pub mod kv;
 pub mod kv_types;
 pub mod partner;
+pub mod sync_pixel;
 
 use cookie::CookieJar;
 use error_stack::Report;
@@ -287,6 +291,15 @@ impl EcContext {
         &self.consent
     }
 
+    /// Returns a mutable reference to the consent context.
+    ///
+    /// Used by `/sync` to apply query-param fallback consent for the current
+    /// request only when pre-routing consent extraction produced an empty
+    /// context.
+    pub fn consent_mut(&mut self) -> &mut ConsentContext {
+        &mut self.consent
+    }
+
     /// Returns the normalized client IP, if available.
     #[must_use]
     pub fn client_ip(&self) -> Option<&str> {
@@ -324,6 +337,12 @@ impl EcContext {
             (Some(cookie), Some(active)) if cookie != active
         )
     }
+
+    /// Returns the stable EC hash prefix from the active EC value.
+    #[must_use]
+    pub fn ec_hash(&self) -> Option<&str> {
+        self.ec_value.as_deref().map(generation::ec_hash)
+    }
 }
 
 fn current_timestamp() -> u64 {
diff --git a/crates/trusted-server-core/src/ec/sync_pixel.rs b/crates/trusted-server-core/src/ec/sync_pixel.rs
new file mode 100644
index 00000000..a129a65b
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/sync_pixel.rs
@@ -0,0 +1,432 @@
+//! Pixel sync endpoint (`GET /sync`).
+
+use error_stack::{Report, ResultExt};
+use fastly::erl::{CounterDuration, RateCounter};
+use fastly::http::StatusCode;
+use fastly::{Request, Response};
+use url::Url;
+
+use crate::consent::{allows_ec_creation, gpp, tcf, ConsentContext};
+use crate::error::TrustedServerError;
+use crate::settings::Settings;
+
+use super::generation::{ec_hash, is_valid_ec_id};
+use super::kv::KvIdentityGraph;
+use super::partner::{PartnerRecord, PartnerStore};
+use super::EcContext;
+
+const RATE_COUNTER_NAME: &str = "counter_store";
+
+/// Handles `GET /sync` pixel sync requests.
+///
+/// # Errors
+///
+/// Returns [`TrustedServerError`] when request validation fails (`400`) or
+/// required stores are unavailable (`503`).
+pub fn handle_sync(
+    _settings: &Settings,
+    kv: &KvIdentityGraph,
+    partner_store: &PartnerStore,
+    req: &Request,
+    ec_context: &mut EcContext,
+) -> Result<Response, Report<TrustedServerError>> {
+    let query = SyncQuery::parse(req)?;
+
+    let partner = partner_store.get(&query.partner)?.ok_or_else(|| {
+        Report::new(TrustedServerError::BadRequest {
+            message: format!("unknown partner '{}'", query.partner),
+        })
+    })?;
+
+    let return_url = validate_return_url(&query.return_url, &partner)?;
+
+    let Some(cookie_ec_id) = ec_context
+        .existing_cookie_ec_id()
+        .filter(|v| is_valid_ec_id(v))
+        .map(str::to_owned)
+    else {
+        return Ok(redirect_with_status(&return_url, "0", Some("no_ec")));
+    };
+
+    if ec_context.consent().is_empty() {
+        if let Some(consent_query) = query.consent.as_deref() {
+            if let Some(fallback) =
+                decode_query_fallback_consent(ec_context.consent(), consent_query)
+            {
+                *ec_context.consent_mut() = fallback;
+            }
+        }
+    }
+
+    if !allows_ec_creation(ec_context.consent()) {
+        return Ok(redirect_with_status(&return_url, "0", Some("no_consent")));
+    }
+
+    let hash = ec_hash(&cookie_ec_id);
+    let limiter = FastlyRateLimiter::new(RATE_COUNTER_NAME);
+    if limiter.exceeded(&format!("{}:{hash}", partner.id), partner.sync_rate_limit)? {
+        return Ok(Response::from_status(StatusCode::TOO_MANY_REQUESTS)
+            .with_body_text_plain("rate_limit_exceeded"));
+    }
+
+    let now = current_timestamp();
+    if let Err(err) = kv.upsert_partner_id(hash, &partner.id, &query.uid, now) {
+        log::warn!(
+            "Pixel sync write failed for partner '{}' and hash '{}': {err:?}",
+            partner.id,
+            hash,
+        );
+        return Ok(redirect_with_status(&return_url, "0", Some("write_failed")));
+    }
+
+    Ok(redirect_with_status(&return_url, "1", None))
+}
+
+#[derive(Debug)]
+struct SyncQuery {
+    partner: String,
+    uid: String,
+    return_url: String,
+    consent: Option<String>,
+}
+
+impl SyncQuery {
+    fn parse(req: &Request) -> Result<Self, Report<TrustedServerError>> {
+        let mut partner = None;
+        let mut uid = None;
+        let mut return_url = None;
+        let mut consent = None;
+
+        let raw_query = req.get_query_str().unwrap_or("");
+        for (key, value) in url::form_urlencoded::parse(raw_query.as_bytes()) {
+            match key.as_ref() {
+                "partner" => partner = Some(value.into_owned()),
+                "uid" => uid = Some(value.into_owned()),
+                "return" => return_url = Some(value.into_owned()),
+                "consent" => consent = Some(value.into_owned()),
+                _ => {}
+            }
+        }
+
+        Ok(Self {
+            partner: required_query_param(partner, "partner")?,
+            uid: required_query_param(uid, "uid")?,
+            return_url: required_query_param(return_url, "return")?,
+            consent,
+        })
+    }
+}
+
+fn required_query_param(
+    value: Option<String>,
+    key: &str,
+) -> Result<String, Report<TrustedServerError>> {
+    let Some(value) = value else {
+        return Err(Report::new(TrustedServerError::BadRequest {
+            message: format!("missing required query parameter '{key}'"),
+        }));
+    };
+
+    if value.trim().is_empty() {
+        return Err(Report::new(TrustedServerError::BadRequest {
+            message: format!("query parameter '{key}' must not be empty"),
+        }));
+    }
+
+    Ok(value)
+}
+
+fn validate_return_url(
+    return_url: &str,
+    partner: &PartnerRecord,
+) -> Result<Url, Report<TrustedServerError>> {
+    let parsed = Url::parse(return_url).change_context(TrustedServerError::BadRequest {
+        message: "return URL must be a valid absolute URL".to_owned(),
+    })?;
+
+    let host = parsed
+        .host_str()
+        .ok_or_else(|| {
+            Report::new(TrustedServerError::BadRequest {
+                message: "return URL must include a hostname".to_owned(),
+            })
+        })?
+        .trim_end_matches('.')
+        .to_ascii_lowercase();
+
+    let allowed = partner
+        .allowed_return_domains
+        .iter()
+        .map(|domain| domain.trim().trim_end_matches('.').to_ascii_lowercase())
+        .any(|domain| domain == host);
+
+    if !allowed {
+        return Err(Report::new(TrustedServerError::BadRequest {
+            message: format!(
+                "return URL host '{host}' is not allowed for partner '{}'",
+                partner.id
+            ),
+        }));
+    }
+
+    Ok(parsed)
+}
+
+fn redirect_with_status(return_url: &Url, synced: &str, reason: Option<&str>) -> Response {
+    let mut url = return_url.clone();
+    {
+        let mut query = url.query_pairs_mut();
+        query.append_pair("ts_synced", synced);
+        if let Some(reason) = reason {
+            query.append_pair("ts_reason", reason);
+        }
+    }
+
+    Response::from_status(StatusCode::FOUND).with_header("location", url.as_str())
+}
+
+fn decode_query_fallback_consent(
+    base: &ConsentContext,
+    raw_consent: &str,
+) -> Option<ConsentContext> {
+    if raw_consent.trim().is_empty() {
+        return None;
+    }
+
+    let mut consent = ConsentContext {
+        jurisdiction: base.jurisdiction.clone(),
+        gpc: base.gpc,
+        ..ConsentContext::default()
+    };
+
+    if raw_consent.contains('~') || raw_consent.starts_with("DB") {
+        match gpp::decode_gpp_string(raw_consent) {
+            Ok(decoded) => {
+                consent.raw_gpp_string = Some(raw_consent.to_owned());
+                consent.gpp_section_ids = Some(decoded.section_ids.clone());
+                consent.tcf = decoded.eu_tcf.clone();
+                consent.gpp = Some(decoded);
+                consent.gdpr_applies = consent
+                    .gpp_section_ids
+                    .as_ref()
+                    .is_some_and(|sids| sids.contains(&2));
+                return Some(consent);
+            }
+            Err(err) => {
+                log::warn!("Failed to decode GPP consent query fallback: {err:?}");
+                return None;
+            }
+        }
+    }
+
+    match tcf::decode_tc_string(raw_consent) {
+        Ok(decoded) => {
+            consent.raw_tc_string = Some(raw_consent.to_owned());
+            consent.tcf = Some(decoded);
+            consent.gdpr_applies = true;
+            Some(consent)
+        }
+        Err(err) => {
+            log::warn!("Failed to decode TCF consent query fallback: {err:?}");
+            None
+        }
+    }
+}
+
+trait RateLimiter {
+    fn exceeded(&self, key: &str, hourly_limit: u32) -> Result<bool, Report<TrustedServerError>>;
+}
+
+struct FastlyRateLimiter {
+    counter: RateCounter,
+}
+
+impl FastlyRateLimiter {
+    fn new(counter_name: &str) -> Self {
+        Self {
+            counter: RateCounter::open(counter_name),
+        }
+    }
+}
+
+impl RateLimiter for FastlyRateLimiter {
+    fn exceeded(&self, key: &str, hourly_limit: u32) -> Result<bool, Report<TrustedServerError>> {
+        // Fastly's public rate-counter API currently exposes windows up to 60s.
+        // Approximate the story's 1h limit by converting to a per-minute budget.
+        //
+        // Follow-up: move to exact 1-hour enforcement once platform counters
+        // expose longer windows or we add a dedicated KV-backed hour bucket.
+        let per_minute_limit = hourly_limit.saturating_add(59) / 60;
+        let per_minute_limit = per_minute_limit.max(1);
+
+        let current = self
+            .counter
+            .lookup_count(key, CounterDuration::SixtySecs)
+            .map_err(|e| {
+                Report::new(TrustedServerError::KvStore {
+                    store_name: RATE_COUNTER_NAME.to_owned(),
+                    message: format!("Failed to read sync rate counter: {e}"),
+                })
+            })?;
+
+        if current >= per_minute_limit {
+            return Ok(true);
+        }
+
+        self.counter.increment(key, 1).map_err(|e| {
+            Report::new(TrustedServerError::KvStore {
+                store_name: RATE_COUNTER_NAME.to_owned(),
+                message: format!("Failed to increment sync rate counter: {e}"),
+            })
+        })?;
+
+        Ok(false)
+    }
+}
+
+fn current_timestamp() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample_partner() -> PartnerRecord {
+        PartnerRecord {
+            id: "ssp_x".to_owned(),
+            name: "SSP X".to_owned(),
+            allowed_return_domains: vec!["sync.example.com".to_owned()],
+            api_key_hash: "deadbeef".to_owned(),
+            bidstream_enabled: false,
+            source_domain: "ssp.example.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+        }
+    }
+
+    #[test]
+    fn redirect_appends_query_when_url_has_none() {
+        let url = Url::parse("https://sync.example.com/return").expect("should parse URL");
+        let response = redirect_with_status(&url, "1", None);
+        let location = response
+            .get_header("location")
+            .expect("should set location header")
+            .to_str()
+            .expect("should convert location to UTF-8");
+
+        assert_eq!(
+            location, "https://sync.example.com/return?ts_synced=1",
+            "should append query with ? when missing"
+        );
+    }
+
+    #[test]
+    fn redirect_appends_query_when_url_already_has_query() {
+        let url = Url::parse("https://sync.example.com/return?foo=bar").expect("should parse URL");
+        let response = redirect_with_status(&url, "0", Some("no_ec"));
+        let location = response
+            .get_header("location")
+            .expect("should set location header")
+            .to_str()
+            .expect("should convert location to UTF-8");
+
+        assert_eq!(
+            location, "https://sync.example.com/return?foo=bar&ts_synced=0&ts_reason=no_ec",
+            "should append sync status after existing query"
+        );
+    }
+
+    #[test]
+    fn fallback_decodes_tcf() {
+        let base = ConsentContext::default();
+        let decoded =
+            decode_query_fallback_consent(&base, "CPXxGfAPXxGfAAfKABENB-CgAAAAAAAAAAYgAAAAAAAA")
+                .expect("should decode TCF fallback");
+
+        assert!(
+            decoded.raw_tc_string.is_some(),
+            "should store raw TC string"
+        );
+    }
+
+    #[test]
+    fn query_parse_rejects_missing_required_param() {
+        let req = Request::new("GET", "https://edge.example.com/sync?partner=ssp&uid=u1");
+        let err = SyncQuery::parse(&req).expect_err("should fail when return param is missing");
+        assert!(
+            err.to_string()
+                .contains("missing required query parameter 'return'"),
+            "should mention missing required return parameter"
+        );
+    }
+
+    #[test]
+    fn query_parse_rejects_empty_required_param() {
+        let req = Request::new(
+            "GET",
+            "https://edge.example.com/sync?partner=ssp&uid=u1&return=   ",
+        );
+        let err = SyncQuery::parse(&req).expect_err("should fail when return param is empty");
+        assert!(
+            err.to_string()
+                .contains("query parameter 'return' must not be empty"),
+            "should reject empty required return parameter"
+        );
+    }
+
+    #[test]
+    fn return_url_validation_rejects_subdomain_spoofing() {
+        let partner = sample_partner();
+        let err = validate_return_url("https://a.sync.example.com/callback", &partner)
+            .expect_err("should reject return host not exactly allowlisted");
+
+        assert!(
+            err.to_string().contains("is not allowed"),
+            "should reject non-exact allowlist host"
+        );
+    }
+
+    #[test]
+    fn return_url_validation_rejects_relative_url() {
+        let partner = sample_partner();
+        let err = validate_return_url("/callback", &partner)
+            .expect_err("should reject non-absolute return URL");
+        assert!(
+            err.to_string().contains("valid absolute URL"),
+            "should require absolute return URLs"
+        );
+    }
+
+    #[test]
+    fn fallback_decodes_gpp() {
+        let base = ConsentContext::default();
+        let decoded = decode_query_fallback_consent(&base, "DBABTA~1YNN")
+            .expect("should decode valid GPP fallback");
+
+        assert!(
+            decoded.raw_gpp_string.is_some(),
+            "should store raw GPP string"
+        );
+    }
+
+    #[test]
+    fn fallback_returns_none_for_invalid_consent_string() {
+        let base = ConsentContext::default();
+        let decoded = decode_query_fallback_consent(&base, "not-a-valid-consent");
+        assert!(
+            decoded.is_none(),
+            "should ignore undecodable consent fallback"
+        );
+    }
+}

From dbf0ccdfff039d41e590462df6895432ade0752d Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Tue, 24 Mar 2026 20:14:15 -0500
Subject: [PATCH 08/36] Decorate auction bidstream with partner EIDs from KV
 identity graph

---
 .../trusted-server-adapter-fastly/src/main.rs |  11 +-
 .../src/auction/endpoints.rs                  | 145 +++++++++++-
 .../src/auction/formats.rs                    | 160 +++++++++++++-
 .../src/auction/orchestrator.rs               |   1 +
 .../trusted-server-core/src/auction/types.rs  |   7 +
 crates/trusted-server-core/src/consent/mod.rs |   5 +-
 crates/trusted-server-core/src/ec/eids.rs     | 206 ++++++++++++++++++
 crates/trusted-server-core/src/ec/identify.rs |  78 +------
 crates/trusted-server-core/src/ec/mod.rs      |  17 ++
 .../src/integrations/adserver_mock.rs         |   2 +
 .../src/integrations/aps.rs                   |   1 +
 .../src/integrations/prebid.rs                |  71 +++++-
 crates/trusted-server-core/src/openrtb.rs     |   4 +-
 13 files changed, 615 insertions(+), 93 deletions(-)
 create mode 100644 crates/trusted-server-core/src/ec/eids.rs

diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index b3ff2582..460342e0 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -186,7 +186,16 @@ async fn route_request(
 
         // Unified auction endpoint (returns creative HTML inline)
         (Method::POST, "/auction") => {
-            handle_auction(settings, orchestrator, kv_graph.as_ref(), &ec_context, req).await
+            let partner_store = require_partner_store(settings).ok();
+            handle_auction(
+                settings,
+                orchestrator,
+                kv_graph.as_ref(),
+                partner_store.as_ref(),
+                &ec_context,
+                req,
+            )
+            .await
         }
 
         // tsjs endpoints
diff --git a/crates/trusted-server-core/src/auction/endpoints.rs b/crates/trusted-server-core/src/auction/endpoints.rs
index fff0eb79..6cbc58cb 100644
--- a/crates/trusted-server-core/src/auction/endpoints.rs
+++ b/crates/trusted-server-core/src/auction/endpoints.rs
@@ -4,10 +4,13 @@ use error_stack::{Report, ResultExt};
 use fastly::{Request, Response};
 
 use crate::auction::formats::AdRequest;
+use crate::consent::gate_eids_by_consent;
+use crate::ec::eids::{resolve_partner_ids, to_eids};
 use crate::ec::kv::KvIdentityGraph;
+use crate::ec::partner::PartnerStore;
 use crate::ec::EcContext;
 use crate::error::TrustedServerError;
-
+use crate::openrtb::Eid;
 use crate::settings::Settings;
 
 use super::formats::{convert_to_openrtb_response, convert_tsjs_to_auction_request};
@@ -30,7 +33,8 @@ use super::AuctionOrchestrator;
 pub async fn handle_auction(
     settings: &Settings,
     orchestrator: &AuctionOrchestrator,
-    _kv: Option<&KvIdentityGraph>,
+    kv: Option<&KvIdentityGraph>,
+    partner_store: Option<&PartnerStore>,
     ec_context: &EcContext,
     mut req: Request,
 ) -> Result<Response, Report<TrustedServerError>> {
@@ -59,10 +63,22 @@ pub async fn handle_auction(
     };
     let consent_context = ec_context.consent().clone();
 
+    // Resolve partner EIDs from the KV identity graph when the user has
+    // a valid EC and both KV and partner stores are available.
+    let eids = resolve_auction_eids(kv, partner_store, ec_context);
+
     // Convert tsjs request format to auction request
-    let auction_request =
+    let mut auction_request =
         convert_tsjs_to_auction_request(&body, settings, &req, consent_context, ec_id)?;
 
+    // Apply consent gating to the resolved EIDs before attaching them to the
+    // auction request. `gate_eids_by_consent` checks TCF Purpose 1 + 4.
+    let had_eids = eids.as_ref().is_some_and(|v| !v.is_empty());
+    auction_request.user.eids = gate_eids_by_consent(eids, auction_request.user.consent.as_ref());
+    if had_eids && auction_request.user.eids.is_none() {
+        log::debug!("Auction EIDs stripped by TCF consent gating");
+    }
+
     // Create auction context
     let context = AuctionContext {
         settings,
@@ -87,5 +103,126 @@ pub async fn handle_auction(
     );
 
     // Convert to OpenRTB response format with inline creative HTML
-    convert_to_openrtb_response(&result, settings, &auction_request)
+    convert_to_openrtb_response(&result, settings, &auction_request, ec_context.ec_allowed())
+}
+
+/// Resolves partner EIDs from the KV identity graph for bidstream decoration.
+///
+/// Returns `None` when any prerequisite is missing (no KV store, no partner
+/// store, no EC, consent denied). On KV or partner-resolution errors, logs a
+/// warning and returns empty EIDs so the auction can proceed in degraded mode.
+fn resolve_auction_eids(
+    kv: Option<&KvIdentityGraph>,
+    partner_store: Option<&PartnerStore>,
+    ec_context: &EcContext,
+) -> Option<Vec<Eid>> {
+    let kv = kv?;
+    let partner_store = partner_store?;
+
+    if !ec_context.ec_allowed() {
+        return None;
+    }
+
+    let ec_hash = ec_context.ec_hash()?;
+
+    let entry = match kv.get(ec_hash) {
+        Ok(Some((entry, _generation))) => entry,
+        Ok(None) => return Some(Vec::new()),
+        Err(err) => {
+            log::warn!("Auction KV read failed for EC hash '{ec_hash}': {err:?}");
+            return Some(Vec::new());
+        }
+    };
+
+    match resolve_partner_ids(partner_store, &entry) {
+        Ok(resolved) => Some(to_eids(&resolved)),
+        Err(err) => {
+            log::warn!("Auction partner resolution failed: {err:?}");
+            Some(Vec::new())
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::consent::jurisdiction::Jurisdiction;
+    use crate::consent::types::ConsentContext;
+
+    fn make_ec_context(jurisdiction: Jurisdiction, ec_value: Option<&str>) -> EcContext {
+        EcContext::new_for_test(
+            ec_value.map(str::to_owned),
+            ConsentContext {
+                jurisdiction,
+                ..ConsentContext::default()
+            },
+        )
+    }
+
+    #[test]
+    fn resolve_auction_eids_returns_none_without_kv() {
+        let partner_store = PartnerStore::new("test_store");
+        let ec_id = format!("{}.ABC123", "a".repeat(64));
+        let ec_context = make_ec_context(Jurisdiction::NonRegulated, Some(&ec_id));
+
+        let result = resolve_auction_eids(None, Some(&partner_store), &ec_context);
+        assert!(result.is_none(), "should return None when KV is missing");
+    }
+
+    #[test]
+    fn resolve_auction_eids_returns_none_without_partner_store() {
+        let kv = KvIdentityGraph::new("test_store");
+        let ec_id = format!("{}.ABC123", "a".repeat(64));
+        let ec_context = make_ec_context(Jurisdiction::NonRegulated, Some(&ec_id));
+
+        let result = resolve_auction_eids(Some(&kv), None, &ec_context);
+        assert!(
+            result.is_none(),
+            "should return None when partner store is missing"
+        );
+    }
+
+    #[test]
+    fn resolve_auction_eids_returns_none_when_consent_denied() {
+        let kv = KvIdentityGraph::new("test_store");
+        let partner_store = PartnerStore::new("test_store");
+        let ec_id = format!("{}.ABC123", "a".repeat(64));
+        let ec_context = make_ec_context(Jurisdiction::Unknown, Some(&ec_id));
+
+        let result = resolve_auction_eids(Some(&kv), Some(&partner_store), &ec_context);
+        assert!(
+            result.is_none(),
+            "should return None when consent is denied"
+        );
+    }
+
+    #[test]
+    fn resolve_auction_eids_returns_none_when_no_ec() {
+        let kv = KvIdentityGraph::new("test_store");
+        let partner_store = PartnerStore::new("test_store");
+        let ec_context = make_ec_context(Jurisdiction::NonRegulated, None);
+
+        let result = resolve_auction_eids(Some(&kv), Some(&partner_store), &ec_context);
+        assert!(
+            result.is_none(),
+            "should return None when no EC value is present"
+        );
+    }
+
+    #[test]
+    fn resolve_auction_eids_returns_empty_on_kv_miss() {
+        let kv = KvIdentityGraph::new("nonexistent_store");
+        let partner_store = PartnerStore::new("nonexistent_store");
+        let ec_id = format!("{}.ABC123", "a".repeat(64));
+        let ec_context = make_ec_context(Jurisdiction::NonRegulated, Some(&ec_id));
+
+        // KV store doesn't exist, so the get() call will error — should return
+        // empty Vec (degraded mode), not None.
+        let result = resolve_auction_eids(Some(&kv), Some(&partner_store), &ec_context);
+        let eids = result.expect("should return Some on KV error (degraded mode)");
+        assert!(
+            eids.is_empty(),
+            "should return empty vec on KV error (degraded mode)"
+        );
+    }
 }
diff --git a/crates/trusted-server-core/src/auction/formats.rs b/crates/trusted-server-core/src/auction/formats.rs
index 92a3f533..f4d9dbcd 100644
--- a/crates/trusted-server-core/src/auction/formats.rs
+++ b/crates/trusted-server-core/src/auction/formats.rs
@@ -14,8 +14,11 @@ use uuid::Uuid;
 
 use crate::auction::context::ContextValue;
 use crate::consent::ConsentContext;
-use crate::constants::HEADER_X_TS_EC;
+use crate::constants::{
+    HEADER_X_TS_EC, HEADER_X_TS_EC_CONSENT, HEADER_X_TS_EIDS, HEADER_X_TS_EIDS_TRUNCATED,
+};
 use crate::creative;
+use crate::ec::eids::encode_eids_header;
 use crate::error::TrustedServerError;
 use crate::geo::GeoInfo;
 use crate::openrtb::{to_openrtb_i32, OpenRtbBid, OpenRtbResponse, ResponseExt, SeatBid, ToExt};
@@ -182,6 +185,7 @@ pub fn convert_tsjs_to_auction_request(
         user: UserInfo {
             id: ec_id,
             consent: Some(consent),
+            eids: None,
         },
         device,
         site: Some(SiteInfo {
@@ -205,6 +209,7 @@ pub fn convert_to_openrtb_response(
     result: &OrchestrationResult,
     settings: &Settings,
     auction_request: &AuctionRequest,
+    ec_allowed: bool,
 ) -> Result<Response, Report<TrustedServerError>> {
     // Build OpenRTB-style seatbid array
     let mut seatbids = Vec::with_capacity(result.winning_bids.len());
@@ -305,8 +310,157 @@ pub fn convert_to_openrtb_response(
             message: "Failed to serialize auction response".to_string(),
         })?;
 
-    Ok(Response::from_status(StatusCode::OK)
+    let mut response = Response::from_status(StatusCode::OK)
         .with_header(header::CONTENT_TYPE, "application/json")
         .with_header(HEADER_X_TS_EC, &auction_request.user.id)
-        .with_body(body_bytes))
+        .with_body(body_bytes);
+
+    // Signal consent status independently of whether EIDs were resolved.
+    // A user may have granted consent but have no partner syncs yet;
+    // downstream clients rely on this header to know consent was verified.
+    if ec_allowed {
+        response.set_header(HEADER_X_TS_EC_CONSENT, "ok");
+    }
+
+    // Attach EID response headers when consent-gated EIDs are available.
+    // `Some(empty)` means "we looked and found no synced partners" — the
+    // header is still set (with an encoded empty array) so clients can
+    // distinguish this from `None` (EIDs not checked / consent denied).
+    if let Some(ref eids) = auction_request.user.eids {
+        let (encoded, truncated) = encode_eids_header(eids)?;
+        response.set_header(HEADER_X_TS_EIDS, encoded);
+        if truncated {
+            response.set_header(HEADER_X_TS_EIDS_TRUNCATED, "true");
+        }
+    }
+
+    Ok(response)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::auction::orchestrator::OrchestrationResult;
+    use crate::auction::types::{AdFormat, AdSlot, MediaType};
+    use crate::constants::{HEADER_X_TS_EC_CONSENT, HEADER_X_TS_EIDS, HEADER_X_TS_EIDS_TRUNCATED};
+    use crate::openrtb::{Eid, Uid};
+
+    fn make_minimal_auction_request() -> AuctionRequest {
+        AuctionRequest {
+            id: "test-auction".to_owned(),
+            slots: vec![AdSlot {
+                id: "slot-1".to_owned(),
+                formats: vec![AdFormat {
+                    media_type: MediaType::Banner,
+                    width: 300,
+                    height: 250,
+                }],
+                floor_price: None,
+                targeting: HashMap::new(),
+                bidders: HashMap::new(),
+            }],
+            publisher: PublisherInfo {
+                domain: "test.com".to_owned(),
+                page_url: None,
+            },
+            user: UserInfo {
+                id: "test-ec-id".to_owned(),
+                consent: None,
+                eids: None,
+            },
+            device: None,
+            site: None,
+            context: HashMap::new(),
+        }
+    }
+
+    fn make_empty_result() -> OrchestrationResult {
+        OrchestrationResult {
+            winning_bids: HashMap::new(),
+            provider_responses: Vec::new(),
+            mediator_response: None,
+            total_time_ms: 10,
+            metadata: HashMap::new(),
+        }
+    }
+
+    fn make_settings() -> Settings {
+        crate::test_support::tests::create_test_settings()
+    }
+
+    #[test]
+    fn response_includes_eid_headers_when_eids_present() {
+        let mut request = make_minimal_auction_request();
+        request.user.eids = Some(vec![Eid {
+            source: "ssp.com".to_owned(),
+            uids: vec![Uid {
+                id: "uid-1".to_owned(),
+                atype: Some(3),
+                ext: None,
+            }],
+        }]);
+
+        let settings = make_settings();
+        let result = make_empty_result();
+
+        let response = convert_to_openrtb_response(&result, &settings, &request, true)
+            .expect("should build response");
+
+        assert!(
+            response.get_header(HEADER_X_TS_EIDS).is_some(),
+            "should include x-ts-eids header when EIDs are present"
+        );
+        assert_eq!(
+            response
+                .get_header(HEADER_X_TS_EC_CONSENT)
+                .and_then(|v| v.to_str().ok()),
+            Some("ok"),
+            "should include x-ts-ec-consent: ok when ec_allowed is true"
+        );
+        assert!(
+            response.get_header(HEADER_X_TS_EIDS_TRUNCATED).is_none(),
+            "should not include truncated header for small payload"
+        );
+    }
+
+    #[test]
+    fn response_sets_consent_header_even_without_eids() {
+        let request = make_minimal_auction_request();
+        let settings = make_settings();
+        let result = make_empty_result();
+
+        let response = convert_to_openrtb_response(&result, &settings, &request, true)
+            .expect("should build response");
+
+        assert_eq!(
+            response
+                .get_header(HEADER_X_TS_EC_CONSENT)
+                .and_then(|v| v.to_str().ok()),
+            Some("ok"),
+            "should set x-ts-ec-consent: ok based on consent, not EID presence"
+        );
+        assert!(
+            response.get_header(HEADER_X_TS_EIDS).is_none(),
+            "should omit x-ts-eids when no EIDs available"
+        );
+    }
+
+    #[test]
+    fn response_omits_consent_header_when_not_allowed() {
+        let request = make_minimal_auction_request();
+        let settings = make_settings();
+        let result = make_empty_result();
+
+        let response = convert_to_openrtb_response(&result, &settings, &request, false)
+            .expect("should build response");
+
+        assert!(
+            response.get_header(HEADER_X_TS_EC_CONSENT).is_none(),
+            "should omit x-ts-ec-consent when ec_allowed is false"
+        );
+        assert!(
+            response.get_header(HEADER_X_TS_EIDS).is_none(),
+            "should omit x-ts-eids when no EIDs available"
+        );
+    }
 }
diff --git a/crates/trusted-server-core/src/auction/orchestrator.rs b/crates/trusted-server-core/src/auction/orchestrator.rs
index 23116256..475e7ce1 100644
--- a/crates/trusted-server-core/src/auction/orchestrator.rs
+++ b/crates/trusted-server-core/src/auction/orchestrator.rs
@@ -627,6 +627,7 @@ mod tests {
             user: UserInfo {
                 id: "user-123".to_string(),
                 consent: None,
+                eids: None,
             },
             device: None,
             site: None,
diff --git a/crates/trusted-server-core/src/auction/types.rs b/crates/trusted-server-core/src/auction/types.rs
index 0ac5b978..360da1d7 100644
--- a/crates/trusted-server-core/src/auction/types.rs
+++ b/crates/trusted-server-core/src/auction/types.rs
@@ -79,6 +79,13 @@ pub struct UserInfo {
     /// cookies/headers, not from stored data.
     #[serde(skip)]
     pub consent: Option<crate::consent::ConsentContext>,
+    /// Consent-gated Extended User IDs resolved from the KV identity graph.
+    ///
+    /// Populated by the auction handler from partner data when the user has
+    /// a valid EC and consent permits EID transmission. `None` when no EIDs
+    /// are available (no EC, consent denied, or KV read failure).
+    #[serde(skip)]
+    pub eids: Option<Vec<crate::openrtb::Eid>>,
 }
 
 /// Device information from request.
diff --git a/crates/trusted-server-core/src/consent/mod.rs b/crates/trusted-server-core/src/consent/mod.rs
index 83afcde5..4096c159 100644
--- a/crates/trusted-server-core/src/consent/mod.rs
+++ b/crates/trusted-server-core/src/consent/mod.rs
@@ -435,9 +435,8 @@ pub fn build_us_privacy_from_gpc(config: &ConsentConfig) -> Option<types::UsPriv
 /// Returns [`None`] if consent is missing or insufficient, stripping all EIDs
 /// from the outgoing bid request.
 ///
-/// **Note:** This function is implemented and tested but not yet wired into
-/// the bid request path. It will be connected when identity provider
-/// integration populates EIDs (see `prebid.rs` where `eids: None`).
+/// Called by `handle_auction` after resolving partner EIDs from the KV
+/// identity graph, before attaching them to the outbound `OpenRTB` request.
 #[must_use]
 pub fn gate_eids_by_consent<T>(
     eids: Option<Vec<T>>,
diff --git a/crates/trusted-server-core/src/ec/eids.rs b/crates/trusted-server-core/src/ec/eids.rs
new file mode 100644
index 00000000..5af322c0
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/eids.rs
@@ -0,0 +1,206 @@
+//! Shared EID resolution and formatting helpers.
+//!
+//! Used by both `/identify` and `/auction` to resolve partner IDs from KV
+//! entries, convert them to `OpenRTB` EID structures, and build base64-encoded
+//! response headers.
+
+use base64::{engine::general_purpose::STANDARD as BASE64, Engine as _};
+use error_stack::{Report, ResultExt};
+
+use crate::error::TrustedServerError;
+use crate::openrtb::{Eid, Uid};
+
+use super::kv_types::KvEntry;
+use super::partner::PartnerStore;
+
+/// Maximum size (in bytes) for the base64-encoded `x-ts-eids` header value.
+pub const MAX_EIDS_HEADER_BYTES: usize = 4096;
+
+/// A partner ID resolved from a KV entry against the partner registry.
+///
+/// Only includes partners with `bidstream_enabled = true` and a non-empty UID.
+pub struct ResolvedPartnerId {
+    /// Partner namespace key (e.g. `"liveramp"`).
+    pub partner_id: String,
+    /// The synced user ID value.
+    pub uid: String,
+    /// Epoch timestamp of the last sync.
+    pub synced: u64,
+    /// The partner's identity source domain (e.g. `"liveramp.com"`).
+    pub source_domain: String,
+    /// `OpenRTB` agent type for this partner's identifiers.
+    pub openrtb_atype: u8,
+}
+
+/// Resolves partner IDs from a KV entry against the partner registry.
+///
+/// Filters to partners with `bidstream_enabled = true` and non-empty UIDs,
+/// sorted by `synced` timestamp descending (most recent first).
+///
+/// # Errors
+///
+/// Returns [`TrustedServerError::KvStore`] if a partner registry lookup fails.
+pub fn resolve_partner_ids(
+    partner_store: &PartnerStore,
+    entry: &KvEntry,
+) -> Result<Vec<ResolvedPartnerId>, Report<TrustedServerError>> {
+    let mut resolved = Vec::new();
+
+    for (partner_id, partner_uid) in &entry.ids {
+        if partner_uid.uid.is_empty() {
+            continue;
+        }
+
+        let Some(partner) = partner_store.get(partner_id)? else {
+            continue;
+        };
+        if !partner.bidstream_enabled {
+            continue;
+        }
+
+        resolved.push(ResolvedPartnerId {
+            partner_id: partner_id.clone(),
+            uid: partner_uid.uid.clone(),
+            synced: partner_uid.synced,
+            source_domain: partner.source_domain,
+            openrtb_atype: partner.openrtb_atype,
+        });
+    }
+
+    resolved.sort_by(|a, b| b.synced.cmp(&a.synced));
+    Ok(resolved)
+}
+
+/// Converts resolved partner IDs to `OpenRTB` `Eid` entries.
+#[must_use]
+pub fn to_eids(resolved: &[ResolvedPartnerId]) -> Vec<Eid> {
+    resolved
+        .iter()
+        .map(|item| Eid {
+            source: item.source_domain.clone(),
+            uids: vec![Uid {
+                id: item.uid.clone(),
+                atype: Some(item.openrtb_atype),
+                ext: None,
+            }],
+        })
+        .collect()
+}
+
+/// Builds a base64-encoded EID header value, truncating if needed.
+///
+/// Returns `(encoded_value, was_truncated)`. If the full set of EIDs exceeds
+/// [`MAX_EIDS_HEADER_BYTES`] after base64 encoding, partners are removed
+/// (least recently synced first) until it fits.
+///
+/// # Errors
+///
+/// Returns an error if JSON serialization fails.
+pub fn build_eids_header(
+    resolved: &[ResolvedPartnerId],
+) -> Result<(String, bool), Report<TrustedServerError>> {
+    let eids = to_eids(resolved);
+    encode_eids_header(&eids)
+}
+
+/// Encodes a pre-built EID slice into a base64 header value with truncation.
+///
+/// Like [`build_eids_header`] but operates on already-constructed `Eid` values
+/// (e.g., from `UserInfo.eids` in the auction response path).
+///
+/// Returns `(encoded_value, was_truncated)`.
+///
+/// # Errors
+///
+/// Returns an error if JSON serialization fails.
+pub fn encode_eids_header(eids: &[Eid]) -> Result<(String, bool), Report<TrustedServerError>> {
+    for size in (0..=eids.len()).rev() {
+        let json = serde_json::to_vec(&eids[..size]).change_context(
+            TrustedServerError::Configuration {
+                message: "Failed to serialize eids header payload".to_owned(),
+            },
+        )?;
+        let encoded = BASE64.encode(json);
+
+        if encoded.len() <= MAX_EIDS_HEADER_BYTES {
+            return Ok((encoded, size != eids.len()));
+        }
+    }
+
+    Ok((BASE64.encode("[]"), true))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn to_eids_maps_resolved_ids_correctly() {
+        let resolved = vec![
+            ResolvedPartnerId {
+                partner_id: "liveramp".to_owned(),
+                uid: "LR_xyz".to_owned(),
+                synced: 100,
+                source_domain: "liveramp.com".to_owned(),
+                openrtb_atype: 3,
+            },
+            ResolvedPartnerId {
+                partner_id: "id5".to_owned(),
+                uid: "ID5_abc".to_owned(),
+                synced: 50,
+                source_domain: "id5-sync.com".to_owned(),
+                openrtb_atype: 1,
+            },
+        ];
+
+        let eids = to_eids(&resolved);
+
+        assert_eq!(eids.len(), 2, "should produce one EID per resolved partner");
+        assert_eq!(eids[0].source, "liveramp.com");
+        assert_eq!(eids[0].uids[0].id, "LR_xyz");
+        assert_eq!(eids[0].uids[0].atype, Some(3));
+        assert_eq!(eids[1].source, "id5-sync.com");
+        assert_eq!(eids[1].uids[0].id, "ID5_abc");
+        assert_eq!(eids[1].uids[0].atype, Some(1));
+    }
+
+    #[test]
+    fn build_eids_header_truncates_when_too_large() {
+        let mut resolved = Vec::new();
+        for idx in 0..64 {
+            resolved.push(ResolvedPartnerId {
+                partner_id: format!("partner_{idx}"),
+                uid: format!("uid_{}", "x".repeat(100)),
+                synced: idx as u64,
+                source_domain: format!("partner-{idx}.example.com"),
+                openrtb_atype: 3,
+            });
+        }
+
+        let (encoded, truncated) =
+            build_eids_header(&resolved).expect("should build truncated header");
+
+        assert!(truncated, "should report truncation for large payload");
+        assert!(
+            encoded.len() <= MAX_EIDS_HEADER_BYTES,
+            "should cap encoded header bytes"
+        );
+    }
+
+    #[test]
+    fn build_eids_header_fits_without_truncation() {
+        let resolved = vec![ResolvedPartnerId {
+            partner_id: "ssp".to_owned(),
+            uid: "u1".to_owned(),
+            synced: 100,
+            source_domain: "ssp.com".to_owned(),
+            openrtb_atype: 3,
+        }];
+
+        let (encoded, truncated) =
+            build_eids_header(&resolved).expect("should build header without truncation");
+
+        assert!(!truncated, "should not truncate small payload");
+        assert!(!encoded.is_empty(), "should produce non-empty value");
+    }
+}
diff --git a/crates/trusted-server-core/src/ec/identify.rs b/crates/trusted-server-core/src/ec/identify.rs
index d25fdd1c..62f755e9 100644
--- a/crates/trusted-server-core/src/ec/identify.rs
+++ b/crates/trusted-server-core/src/ec/identify.rs
@@ -2,7 +2,6 @@
 
 use std::collections::HashMap;
 
-use base64::{engine::general_purpose::STANDARD as BASE64, Engine as _};
 use error_stack::{Report, ResultExt};
 use fastly::http::{header, StatusCode};
 use fastly::{Request, Response};
@@ -13,16 +12,15 @@ use crate::constants::{
     HEADER_X_TS_EC, HEADER_X_TS_EC_CONSENT, HEADER_X_TS_EIDS, HEADER_X_TS_EIDS_TRUNCATED,
 };
 use crate::error::TrustedServerError;
-use crate::openrtb::{Eid, Uid};
+use crate::openrtb::Eid;
 use crate::settings::Settings;
 
+use super::eids::{build_eids_header, resolve_partner_ids, to_eids};
 use super::kv::KvIdentityGraph;
-use super::kv_types::KvEntry;
 use super::partner::PartnerStore;
 use super::EcContext;
 
 const MAX_EXPOSE_PARTNER_HEADERS: usize = 20;
-const MAX_EIDS_HEADER_BYTES: usize = 4096;
 
 /// Handles `GET /identify`.
 ///
@@ -162,77 +160,6 @@ struct IdentifyResponse {
     eids: Vec<Eid>,
 }
 
-struct ResolvedPartnerId {
-    partner_id: String,
-    uid: String,
-    synced: u64,
-    source_domain: String,
-    openrtb_atype: u8,
-}
-
-fn resolve_partner_ids(
-    partner_store: &PartnerStore,
-    entry: &KvEntry,
-) -> Result<Vec<ResolvedPartnerId>, Report<TrustedServerError>> {
-    let mut resolved = Vec::new();
-
-    for (partner_id, partner_uid) in &entry.ids {
-        if partner_uid.uid.is_empty() {
-            continue;
-        }
-
-        let Some(partner) = partner_store.get(partner_id)? else {
-            continue;
-        };
-        if !partner.bidstream_enabled {
-            continue;
-        }
-
-        resolved.push(ResolvedPartnerId {
-            partner_id: partner_id.clone(),
-            uid: partner_uid.uid.clone(),
-            synced: partner_uid.synced,
-            source_domain: partner.source_domain,
-            openrtb_atype: partner.openrtb_atype,
-        });
-    }
-
-    resolved.sort_by(|a, b| b.synced.cmp(&a.synced));
-    Ok(resolved)
-}
-
-fn to_eids(resolved: &[ResolvedPartnerId]) -> Vec<Eid> {
-    resolved
-        .iter()
-        .map(|item| Eid {
-            source: item.source_domain.clone(),
-            uids: vec![Uid {
-                id: item.uid.clone(),
-                atype: Some(item.openrtb_atype),
-                ext: None,
-            }],
-        })
-        .collect()
-}
-
-fn build_eids_header(
-    resolved: &[ResolvedPartnerId],
-) -> Result<(String, bool), Report<TrustedServerError>> {
-    for size in (0..=resolved.len()).rev() {
-        let eids = to_eids(&resolved[..size]);
-        let json = serde_json::to_vec(&eids).change_context(TrustedServerError::Configuration {
-            message: "Failed to serialize identify eids header payload".to_owned(),
-        })?;
-        let encoded = BASE64.encode(json);
-
-        if encoded.len() <= MAX_EIDS_HEADER_BYTES {
-            return Ok((encoded, size != resolved.len()));
-        }
-    }
-
-    Ok((BASE64.encode("[]"), true))
-}
-
 fn json_response<T: serde::Serialize>(
     status: StatusCode,
     body: &T,
@@ -295,6 +222,7 @@ mod tests {
     use super::*;
     use crate::consent::jurisdiction::Jurisdiction;
     use crate::consent::types::{ConsentContext, ConsentSource};
+    use crate::ec::eids::{ResolvedPartnerId, MAX_EIDS_HEADER_BYTES};
     use crate::test_support::tests::create_test_settings;
 
     fn make_ec_context(jurisdiction: Jurisdiction, ec_value: Option<&str>) -> EcContext {
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index d7dfe480..a8eab5b7 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -22,10 +22,12 @@
 //! - [`admin`] — Admin endpoints for partner management
 //! - [`sync_pixel`] — Pixel sync write endpoint (`GET /sync`)
 //! - [`identify`] — Browser identity read endpoint (`GET /identify`)
+//! - [`eids`] — Shared EID resolution and formatting helpers
 
 pub mod admin;
 pub mod consent;
 pub mod cookies;
+pub mod eids;
 pub mod finalize;
 pub mod generation;
 pub mod identify;
@@ -343,6 +345,21 @@ impl EcContext {
     pub fn ec_hash(&self) -> Option<&str> {
         self.ec_value.as_deref().map(generation::ec_hash)
     }
+
+    /// Creates a test-only `EcContext` with explicit field values.
+    #[cfg(test)]
+    #[must_use]
+    pub fn new_for_test(ec_value: Option<String>, consent: ConsentContext) -> Self {
+        Self {
+            ec_was_present: ec_value.is_some(),
+            cookie_ec_value: ec_value.clone(),
+            ec_value,
+            ec_generated: false,
+            consent,
+            client_ip: None,
+            geo_info: None,
+        }
+    }
 }
 
 fn current_timestamp() -> u64 {
diff --git a/crates/trusted-server-core/src/integrations/adserver_mock.rs b/crates/trusted-server-core/src/integrations/adserver_mock.rs
index cfbece21..4c888a23 100644
--- a/crates/trusted-server-core/src/integrations/adserver_mock.rs
+++ b/crates/trusted-server-core/src/integrations/adserver_mock.rs
@@ -467,6 +467,7 @@ mod tests {
             user: UserInfo {
                 id: "user-123".to_string(),
                 consent: None,
+                eids: None,
             },
             device: Some(DeviceInfo {
                 user_agent: Some("Mozilla/5.0".to_string()),
@@ -640,6 +641,7 @@ mod tests {
             user: UserInfo {
                 id: "user-1".to_string(),
                 consent: None,
+                eids: None,
             },
             device: None,
             site: None,
diff --git a/crates/trusted-server-core/src/integrations/aps.rs b/crates/trusted-server-core/src/integrations/aps.rs
index b18cc454..16785aa0 100644
--- a/crates/trusted-server-core/src/integrations/aps.rs
+++ b/crates/trusted-server-core/src/integrations/aps.rs
@@ -679,6 +679,7 @@ mod tests {
             user: UserInfo {
                 id: "user-123".to_string(),
                 consent: None,
+                eids: None,
             },
             device: Some(DeviceInfo {
                 user_agent: Some("Mozilla/5.0".to_string()),
diff --git a/crates/trusted-server-core/src/integrations/prebid.rs b/crates/trusted-server-core/src/integrations/prebid.rs
index 80700a69..a786af55 100644
--- a/crates/trusted-server-core/src/integrations/prebid.rs
+++ b/crates/trusted-server-core/src/integrations/prebid.rs
@@ -698,9 +698,9 @@ impl PrebidAuctionProvider {
                     .map(|ac| ConsentedProvidersSettings {
                         consented_providers: Some(ac.clone()),
                     }),
-                // EIDs will be populated by identity providers; consent gating
-                // is applied via `gate_eids_by_consent` before they are set here.
-                eids: None,
+                // EIDs resolved from the KV identity graph and consent-gated
+                // in `handle_auction` via `gate_eids_by_consent`.
+                eids: request.user.eids.clone(),
             }
             .to_ext(),
             ..Default::default()
@@ -1372,8 +1372,8 @@ mod tests {
             },
             user: UserInfo {
                 id: "user-123".to_string(),
-
                 consent: None,
+                eids: None,
             },
             device: None,
             site: None,
@@ -2686,6 +2686,67 @@ server_url = "https://prebid.example"
         );
     }
 
+    #[test]
+    fn to_openrtb_includes_eids_from_auction_request() {
+        let provider = PrebidAuctionProvider::new(base_config());
+        let mut auction_request = create_test_auction_request();
+        auction_request.user.eids = Some(vec![
+            crate::openrtb::Eid {
+                source: "liveramp.com".to_owned(),
+                uids: vec![crate::openrtb::Uid {
+                    id: "LR_xyz".to_owned(),
+                    atype: Some(3),
+                    ext: None,
+                }],
+            },
+            crate::openrtb::Eid {
+                source: "id5-sync.com".to_owned(),
+                uids: vec![crate::openrtb::Uid {
+                    id: "ID5_abc".to_owned(),
+                    atype: Some(1),
+                    ext: None,
+                }],
+            },
+        ]);
+
+        let settings = make_settings();
+        let request = Request::get("https://pub.example/auction");
+        let context = create_test_auction_context(&settings, &request);
+
+        let openrtb = provider.to_openrtb(&auction_request, &context, None);
+
+        let serialized = serde_json::to_value(&openrtb).expect("should serialize OpenRTB request");
+        let ext_eids = &serialized["user"]["ext"]["eids"];
+        assert!(ext_eids.is_array(), "should populate user.ext.eids");
+        assert_eq!(ext_eids.as_array().unwrap().len(), 2, "should have 2 EIDs");
+        assert_eq!(
+            ext_eids[0]["source"], "liveramp.com",
+            "should include liveramp EID"
+        );
+        assert_eq!(
+            ext_eids[1]["source"], "id5-sync.com",
+            "should include id5 EID"
+        );
+    }
+
+    #[test]
+    fn to_openrtb_omits_eids_when_none() {
+        let provider = PrebidAuctionProvider::new(base_config());
+        let auction_request = create_test_auction_request();
+
+        let settings = make_settings();
+        let request = Request::get("https://pub.example/auction");
+        let context = create_test_auction_context(&settings, &request);
+
+        let openrtb = provider.to_openrtb(&auction_request, &context, None);
+
+        let serialized = serde_json::to_value(&openrtb).expect("should serialize OpenRTB request");
+        assert!(
+            serialized["user"]["ext"]["eids"].is_null(),
+            "should omit user.ext.eids when no EIDs available"
+        );
+    }
+
     #[test]
     fn expand_trusted_server_bidders_uses_per_bidder_map_when_present() {
         let params = json!({
@@ -2788,8 +2849,8 @@ server_url = "https://prebid.example"
             },
             user: UserInfo {
                 id: "synth-123".to_string(),
-
                 consent: None,
+                eids: None,
             },
             device: Some(DeviceInfo {
                 user_agent: Some("test-agent".to_string()),
diff --git a/crates/trusted-server-core/src/openrtb.rs b/crates/trusted-server-core/src/openrtb.rs
index 37c3d675..3ea837d4 100644
--- a/crates/trusted-server-core/src/openrtb.rs
+++ b/crates/trusted-server-core/src/openrtb.rs
@@ -69,7 +69,7 @@ pub struct ConsentedProvidersSettings {
 }
 
 /// An Extended User ID entry from an identity provider.
-#[derive(Debug, Serialize)]
+#[derive(Debug, Clone, Serialize)]
 pub struct Eid {
     /// Identity provider domain (e.g. `"id5-sync.com"`).
     pub source: String,
@@ -78,7 +78,7 @@ pub struct Eid {
 }
 
 /// A single user identifier within an [`Eid`] entry.
-#[derive(Debug, Serialize)]
+#[derive(Debug, Clone, Serialize)]
 pub struct Uid {
     /// The identifier value.
     pub id: String,

From b776377d1687750f61d345a811b712383b2428ff Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Wed, 25 Mar 2026 18:59:40 -0500
Subject: [PATCH 09/36] Add authenticated S2S batch sync endpoint

Implement Story 8 (#541): POST /api/v1/sync with Bearer API key auth,
per-partner rate limiting, batch size cap, per-mapping validation and
rejection reasons, 200/207 response semantics, tolerant Bearer parsing,
and KV-abort on store unavailability.
---
 .../trusted-server-adapter-fastly/src/main.rs |  18 +-
 .../trusted-server-core/src/ec/batch_sync.rs  | 537 ++++++++++++++++++
 crates/trusted-server-core/src/ec/kv.rs       | 102 ++++
 crates/trusted-server-core/src/ec/mod.rs      |   2 +
 .../trusted-server-core/src/ec/sync_pixel.rs  |  40 +-
 5 files changed, 693 insertions(+), 6 deletions(-)
 create mode 100644 crates/trusted-server-core/src/ec/batch_sync.rs

diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 460342e0..553d5253 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -11,11 +11,12 @@ use trusted_server_core::constants::{
     HEADER_X_TS_ENV, HEADER_X_TS_VERSION,
 };
 use trusted_server_core::ec::admin::handle_register_partner;
+use trusted_server_core::ec::batch_sync::handle_batch_sync;
 use trusted_server_core::ec::finalize::ec_finalize_response;
 use trusted_server_core::ec::identify::{cors_preflight_identify, handle_identify};
 use trusted_server_core::ec::kv::KvIdentityGraph;
 use trusted_server_core::ec::partner::PartnerStore;
-use trusted_server_core::ec::sync_pixel::handle_sync;
+use trusted_server_core::ec::sync_pixel::{handle_sync, FastlyRateLimiter, RATE_COUNTER_NAME};
 use trusted_server_core::ec::EcContext;
 use trusted_server_core::error::TrustedServerError;
 use trusted_server_core::geo::GeoInfo;
@@ -109,6 +110,21 @@ async fn route_request(
     // Extract geo info before auth check or routing consumes the request.
     let geo_info = GeoInfo::from_request(&req);
 
+    // S2S batch sync — uses Bearer auth (not EC cookies), so skip EC
+    // context creation and the EC finalize middleware entirely.
+    if req.get_method() == Method::POST && req.get_path() == "/api/v1/sync" {
+        let mut response = require_identity_graph(settings)
+            .and_then(|kv| {
+                require_partner_store(settings).and_then(|partner_store| {
+                    let limiter = FastlyRateLimiter::new(RATE_COUNTER_NAME);
+                    handle_batch_sync(&kv, &partner_store, &limiter, req)
+                })
+            })
+            .unwrap_or_else(|e| to_error_response(&e));
+        finalize_response(settings, geo_info.as_ref(), &mut response);
+        return Ok(response);
+    }
+
     let mut ec_context =
         match EcContext::read_from_request_with_geo(settings, &req, geo_info.as_ref()) {
             Ok(context) => context,
diff --git a/crates/trusted-server-core/src/ec/batch_sync.rs b/crates/trusted-server-core/src/ec/batch_sync.rs
new file mode 100644
index 00000000..9b1aab14
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/batch_sync.rs
@@ -0,0 +1,537 @@
+//! Server-to-server batch sync endpoint (`POST /api/v1/sync`).
+//!
+//! Partners send authenticated batch ID sync requests via Bearer token.
+//! Each mapping associates an `ssc_hash` (the 64-char hex EC hash prefix)
+//! with the partner's user ID. Mappings are individually validated and
+//! written to the KV identity graph, with per-mapping rejection reasons
+//! reported in the response.
+
+use error_stack::{Report, ResultExt};
+use fastly::http::StatusCode;
+use fastly::{Request, Response};
+use serde::{Deserialize, Serialize};
+
+use crate::error::TrustedServerError;
+
+use super::kv::{KvIdentityGraph, UpsertResult};
+use super::partner::{hash_api_key, PartnerRecord, PartnerStore};
+use super::sync_pixel::RateLimiter;
+
+const REASON_INVALID_EC_HASH: &str = "invalid_ec_hash";
+const REASON_INVALID_PARTNER_UID: &str = "invalid_partner_uid";
+const REASON_EC_HASH_NOT_FOUND: &str = "ec_hash_not_found";
+const REASON_CONSENT_WITHDRAWN: &str = "consent_withdrawn";
+const REASON_KV_UNAVAILABLE: &str = "kv_unavailable";
+
+/// Maximum number of mappings allowed in a single batch request.
+const MAX_BATCH_SIZE: usize = 1000;
+
+/// Regex-free validation: 64 lowercase hex characters.
+fn is_valid_ssc_hash(s: &str) -> bool {
+    s.len() == 64 && s.bytes().all(|b| b.is_ascii_hexdigit())
+}
+
+trait BatchSyncWriter {
+    fn upsert_partner_id_if_exists(
+        &self,
+        ec_hash: &str,
+        partner_id: &str,
+        uid: &str,
+        synced: u64,
+    ) -> Result<UpsertResult, Report<TrustedServerError>>;
+}
+
+impl BatchSyncWriter for KvIdentityGraph {
+    fn upsert_partner_id_if_exists(
+        &self,
+        ec_hash: &str,
+        partner_id: &str,
+        uid: &str,
+        synced: u64,
+    ) -> Result<UpsertResult, Report<TrustedServerError>> {
+        KvIdentityGraph::upsert_partner_id_if_exists(self, ec_hash, partner_id, uid, synced)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Request / response types
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+struct BatchSyncRequest {
+    mappings: Vec<SyncMapping>,
+}
+
+#[derive(Debug, Deserialize)]
+struct SyncMapping {
+    ssc_hash: String,
+    partner_uid: String,
+    timestamp: u64,
+}
+
+#[derive(Debug, Serialize)]
+struct BatchSyncResponse {
+    accepted: usize,
+    rejected: usize,
+    errors: Vec<MappingError>,
+}
+
+#[derive(Debug, Serialize)]
+struct MappingError {
+    index: usize,
+    reason: &'static str,
+}
+
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+
+/// Extracts and validates a `Bearer` token from the `Authorization` header,
+/// returning the authenticated [`PartnerRecord`].
+fn authenticate_bearer(
+    partner_store: &PartnerStore,
+    req: &Request,
+) -> Result<Option<PartnerRecord>, Report<TrustedServerError>> {
+    let header_value = match req.get_header_str("authorization") {
+        Some(v) => v.to_owned(),
+        None => return Ok(None),
+    };
+
+    let token = match parse_bearer_token(&header_value) {
+        Some(t) => t,
+        None => return Ok(None),
+    };
+
+    let key_hash = hash_api_key(token);
+    partner_store.find_by_api_key_hash(&key_hash)
+}
+
+fn parse_bearer_token(header_value: &str) -> Option<&str> {
+    let mut parts = header_value.split_whitespace();
+    let scheme = parts.next()?;
+    let token = parts.next()?;
+
+    if !scheme.eq_ignore_ascii_case("bearer") || token.is_empty() {
+        return None;
+    }
+    if parts.next().is_some() {
+        return None;
+    }
+
+    Some(token)
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+/// Handles `POST /api/v1/sync`.
+///
+/// # Errors
+///
+/// Returns [`TrustedServerError`] on serialization or KV store failures.
+pub fn handle_batch_sync(
+    kv: &KvIdentityGraph,
+    partner_store: &PartnerStore,
+    rate_limiter: &dyn RateLimiter,
+    mut req: Request,
+) -> Result<Response, Report<TrustedServerError>> {
+    handle_batch_sync_with_writer(kv, partner_store, rate_limiter, &mut req)
+}
+
+fn handle_batch_sync_with_writer(
+    writer: &dyn BatchSyncWriter,
+    partner_store: &PartnerStore,
+    rate_limiter: &dyn RateLimiter,
+    req: &mut Request,
+) -> Result<Response, Report<TrustedServerError>> {
+    // 1. Authenticate
+    let partner = match authenticate_bearer(partner_store, req)? {
+        Some(p) => p,
+        None => return Ok(error_response(StatusCode::UNAUTHORIZED, "invalid_token")),
+    };
+
+    // 2. Rate limit (per-partner, per-minute via batch_rate_limit)
+    let rate_key = format!("batch:{}", partner.id);
+    if rate_limiter.exceeded_per_minute(&rate_key, partner.batch_rate_limit)? {
+        return Ok(error_response(
+            StatusCode::TOO_MANY_REQUESTS,
+            "rate_limit_exceeded",
+        ));
+    }
+
+    // 3. Parse body
+    let body: BatchSyncRequest = serde_json::from_slice(&req.take_body_bytes()).map_err(|e| {
+        Report::new(TrustedServerError::BadRequest {
+            message: format!("Invalid request body: {e}"),
+        })
+    })?;
+
+    if body.mappings.len() > MAX_BATCH_SIZE {
+        return Ok(error_response(StatusCode::BAD_REQUEST, "batch_too_large"));
+    }
+
+    // 4. Process mappings with per-item validation and rejection reasons.
+    let (accepted, errors) = process_mappings(writer, &partner.id, &body.mappings);
+
+    let rejected = errors.len();
+    let status = if rejected > 0 {
+        StatusCode::MULTI_STATUS
+    } else {
+        StatusCode::OK
+    };
+
+    let response_body = BatchSyncResponse {
+        accepted,
+        rejected,
+        errors,
+    };
+
+    json_response(status, &response_body)
+}
+
+fn process_mappings(
+    writer: &dyn BatchSyncWriter,
+    partner_id: &str,
+    mappings: &[SyncMapping],
+) -> (usize, Vec<MappingError>) {
+    let mut accepted: usize = 0;
+    let mut errors = Vec::new();
+
+    for (idx, mapping) in mappings.iter().enumerate() {
+        if !is_valid_ssc_hash(&mapping.ssc_hash) {
+            errors.push(MappingError {
+                index: idx,
+                reason: REASON_INVALID_EC_HASH,
+            });
+            continue;
+        }
+
+        if mapping.partner_uid.is_empty() {
+            errors.push(MappingError {
+                index: idx,
+                reason: REASON_INVALID_PARTNER_UID,
+            });
+            continue;
+        }
+
+        // Normalize to lowercase — KV keys are always lowercase hex.
+        let ssc_hash = mapping.ssc_hash.to_ascii_lowercase();
+        match writer.upsert_partner_id_if_exists(
+            &ssc_hash,
+            partner_id,
+            &mapping.partner_uid,
+            mapping.timestamp,
+        ) {
+            Ok(UpsertResult::Written | UpsertResult::Stale) => {
+                accepted += 1;
+            }
+            Ok(UpsertResult::NotFound) => {
+                errors.push(MappingError {
+                    index: idx,
+                    reason: REASON_EC_HASH_NOT_FOUND,
+                });
+            }
+            Ok(UpsertResult::ConsentWithdrawn) => {
+                errors.push(MappingError {
+                    index: idx,
+                    reason: REASON_CONSENT_WITHDRAWN,
+                });
+            }
+            Err(err) => {
+                log::warn!(
+                    "Batch sync KV write failed for index {idx} (ssc_hash '{}'): {err:?}",
+                    mapping.ssc_hash
+                );
+                errors.push(MappingError {
+                    index: idx,
+                    reason: REASON_KV_UNAVAILABLE,
+                });
+                // Abort remaining mappings on infrastructure failure.
+                for remaining_idx in (idx + 1)..mappings.len() {
+                    errors.push(MappingError {
+                        index: remaining_idx,
+                        reason: REASON_KV_UNAVAILABLE,
+                    });
+                }
+                break;
+            }
+        }
+    }
+
+    (accepted, errors)
+}
+
+fn json_response<T: serde::Serialize>(
+    status: StatusCode,
+    body: &T,
+) -> Result<Response, Report<TrustedServerError>> {
+    let body = serde_json::to_string(body).change_context(TrustedServerError::Configuration {
+        message: "Failed to serialize batch sync response".to_owned(),
+    })?;
+
+    Ok(Response::from_status(status)
+        .with_content_type(fastly::mime::APPLICATION_JSON)
+        .with_body(body))
+}
+
+fn error_response(status: StatusCode, reason: &str) -> Response {
+    let body = serde_json::json!({ "error": reason });
+    Response::from_status(status)
+        .with_content_type(fastly::mime::APPLICATION_JSON)
+        .with_body(body.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::VecDeque;
+
+    use crate::error::TrustedServerError;
+
+    #[test]
+    fn is_valid_ssc_hash_accepts_64_hex_chars() {
+        assert!(is_valid_ssc_hash(&"a".repeat(64)));
+        assert!(is_valid_ssc_hash(&"0123456789abcdef".repeat(4)));
+    }
+
+    #[test]
+    fn is_valid_ssc_hash_rejects_wrong_length() {
+        assert!(!is_valid_ssc_hash(&"a".repeat(63)));
+        assert!(!is_valid_ssc_hash(&"a".repeat(65)));
+        assert!(!is_valid_ssc_hash(""));
+    }
+
+    #[test]
+    fn is_valid_ssc_hash_rejects_non_hex() {
+        let mut hash = "a".repeat(64);
+        hash.replace_range(0..1, "g");
+        assert!(!is_valid_ssc_hash(&hash));
+    }
+
+    #[test]
+    fn is_valid_ssc_hash_accepts_uppercase_hex() {
+        assert!(
+            is_valid_ssc_hash(&"A".repeat(64)),
+            "should accept uppercase hex (normalized to lowercase before KV lookup)"
+        );
+    }
+
+    #[test]
+    fn parse_bearer_token_accepts_case_insensitive_scheme() {
+        assert_eq!(parse_bearer_token("Bearer tok"), Some("tok"));
+        assert_eq!(parse_bearer_token("bearer tok"), Some("tok"));
+        assert_eq!(parse_bearer_token("BEARER tok"), Some("tok"));
+    }
+
+    #[test]
+    fn parse_bearer_token_rejects_invalid_shapes() {
+        assert_eq!(parse_bearer_token("Bearer"), None);
+        assert_eq!(parse_bearer_token("Bearer "), None);
+        assert_eq!(parse_bearer_token("Basic abc"), None);
+        assert_eq!(parse_bearer_token("Bearer a b"), None);
+    }
+
+    #[test]
+    fn authenticate_bearer_returns_none_for_missing_header() {
+        let partner_store = PartnerStore::new("test_store");
+        let req = Request::new("POST", "https://edge.example.com/api/v1/sync");
+
+        let result =
+            authenticate_bearer(&partner_store, &req).expect("should not error on missing header");
+        assert!(result.is_none(), "should return None without auth header");
+    }
+
+    #[test]
+    fn authenticate_bearer_returns_none_for_malformed_header() {
+        let partner_store = PartnerStore::new("test_store");
+        let mut req = Request::new("POST", "https://edge.example.com/api/v1/sync");
+        req.set_header("authorization", "Basic dXNlcjpwYXNz");
+
+        let result = authenticate_bearer(&partner_store, &req)
+            .expect("should not error on malformed header");
+        assert!(
+            result.is_none(),
+            "should return None for non-Bearer auth scheme"
+        );
+    }
+
+    #[test]
+    fn authenticate_bearer_returns_none_for_empty_token() {
+        let partner_store = PartnerStore::new("test_store");
+        let mut req = Request::new("POST", "https://edge.example.com/api/v1/sync");
+        req.set_header("authorization", "Bearer ");
+
+        let result =
+            authenticate_bearer(&partner_store, &req).expect("should not error on empty token");
+        assert!(
+            result.is_none(),
+            "should return None for empty Bearer token"
+        );
+    }
+
+    struct MockRateLimiter {
+        should_exceed: bool,
+    }
+
+    impl RateLimiter for MockRateLimiter {
+        fn exceeded(
+            &self,
+            _key: &str,
+            _hourly_limit: u32,
+        ) -> Result<bool, Report<TrustedServerError>> {
+            Ok(self.should_exceed)
+        }
+
+        fn exceeded_per_minute(
+            &self,
+            _key: &str,
+            _per_minute_limit: u32,
+        ) -> Result<bool, Report<TrustedServerError>> {
+            Ok(self.should_exceed)
+        }
+    }
+
+    struct MockWriter {
+        results: std::cell::RefCell<VecDeque<Result<UpsertResult, Report<TrustedServerError>>>>,
+    }
+
+    impl MockWriter {
+        fn new(results: Vec<Result<UpsertResult, Report<TrustedServerError>>>) -> Self {
+            Self {
+                results: std::cell::RefCell::new(results.into()),
+            }
+        }
+    }
+
+    impl BatchSyncWriter for MockWriter {
+        fn upsert_partner_id_if_exists(
+            &self,
+            _ec_hash: &str,
+            _partner_id: &str,
+            _uid: &str,
+            _synced: u64,
+        ) -> Result<UpsertResult, Report<TrustedServerError>> {
+            self.results
+                .borrow_mut()
+                .pop_front()
+                .expect("should provide mock result for each mapping")
+        }
+    }
+
+    fn mapping(ssc_hash: &str, partner_uid: &str, timestamp: u64) -> SyncMapping {
+        SyncMapping {
+            ssc_hash: ssc_hash.to_owned(),
+            partner_uid: partner_uid.to_owned(),
+            timestamp,
+        }
+    }
+
+    #[test]
+    fn process_mappings_returns_multistatus_errors_per_mapping() {
+        let writer = MockWriter::new(vec![Ok(UpsertResult::Written)]);
+        let mappings = vec![
+            mapping("x", "u1", 1),
+            mapping(&"a".repeat(64), "", 1),
+            mapping(&"a".repeat(64), "u3", 1),
+        ];
+
+        let (accepted, errors) = process_mappings(&writer, "partner", &mappings);
+
+        assert_eq!(accepted, 1, "should count successful writes as accepted");
+        assert_eq!(errors.len(), 2, "should reject invalid mappings only");
+        assert_eq!(errors[0].index, 0);
+        assert_eq!(errors[0].reason, REASON_INVALID_EC_HASH);
+        assert_eq!(errors[1].index, 1);
+        assert_eq!(errors[1].reason, REASON_INVALID_PARTNER_UID);
+    }
+
+    #[test]
+    fn process_mappings_aborts_on_kv_unavailable() {
+        let writer = MockWriter::new(vec![
+            Ok(UpsertResult::Written),
+            Err(Report::new(TrustedServerError::KvStore {
+                store_name: "ec_store".to_owned(),
+                message: "down".to_owned(),
+            })),
+            Ok(UpsertResult::Written),
+        ]);
+
+        let mappings = vec![
+            mapping(&"a".repeat(64), "u1", 1),
+            mapping(&"b".repeat(64), "u2", 1),
+            mapping(&"c".repeat(64), "u3", 1),
+        ];
+
+        let (accepted, errors) = process_mappings(&writer, "partner", &mappings);
+
+        assert_eq!(accepted, 1, "should keep accepted count before failure");
+        assert_eq!(
+            errors.len(),
+            2,
+            "should mark current and remaining as unavailable"
+        );
+        assert_eq!(errors[0].index, 1);
+        assert_eq!(errors[0].reason, REASON_KV_UNAVAILABLE);
+        assert_eq!(errors[1].index, 2);
+        assert_eq!(errors[1].reason, REASON_KV_UNAVAILABLE);
+    }
+
+    #[test]
+    fn handle_batch_sync_rejects_missing_auth() {
+        let kv = KvIdentityGraph::new("test_store");
+        let partner_store = PartnerStore::new("test_store");
+        let limiter = MockRateLimiter {
+            should_exceed: false,
+        };
+        let req = Request::new("POST", "https://edge.example.com/api/v1/sync");
+
+        let response =
+            handle_batch_sync(&kv, &partner_store, &limiter, req).expect("should return response");
+        assert_eq!(
+            response.get_status(),
+            StatusCode::UNAUTHORIZED,
+            "should return 401 for missing auth"
+        );
+    }
+
+    #[test]
+    fn batch_sync_request_deserializes_correctly() {
+        let json = r#"{"mappings": [{"ssc_hash": "aaaa", "partner_uid": "u1", "timestamp": 100}]}"#;
+        let parsed: BatchSyncRequest =
+            serde_json::from_str(json).expect("should deserialize batch sync request");
+        assert_eq!(parsed.mappings.len(), 1);
+        assert_eq!(parsed.mappings[0].ssc_hash, "aaaa");
+        assert_eq!(parsed.mappings[0].partner_uid, "u1");
+        assert_eq!(parsed.mappings[0].timestamp, 100);
+    }
+
+    #[test]
+    fn batch_sync_request_rejects_missing_timestamp() {
+        let json = r#"{"mappings": [{"ssc_hash": "bbbb", "partner_uid": "u2"}]}"#;
+        let result = serde_json::from_str::<BatchSyncRequest>(json);
+        assert!(
+            result.is_err(),
+            "should reject mapping without required timestamp"
+        );
+    }
+
+    #[test]
+    fn batch_sync_response_serializes_correctly() {
+        let response = BatchSyncResponse {
+            accepted: 5,
+            rejected: 1,
+            errors: vec![MappingError {
+                index: 3,
+                reason: REASON_EC_HASH_NOT_FOUND,
+            }],
+        };
+
+        let json: serde_json::Value =
+            serde_json::to_value(&response).expect("should serialize batch sync response");
+        assert_eq!(json["accepted"], 5);
+        assert_eq!(json["rejected"], 1);
+        assert_eq!(json["errors"][0]["index"], 3);
+        assert_eq!(json["errors"][0]["reason"], REASON_EC_HASH_NOT_FOUND);
+    }
+}
diff --git a/crates/trusted-server-core/src/ec/kv.rs b/crates/trusted-server-core/src/ec/kv.rs
index 44be5513..4c4c1bfb 100644
--- a/crates/trusted-server-core/src/ec/kv.rs
+++ b/crates/trusted-server-core/src/ec/kv.rs
@@ -30,6 +30,24 @@ const ENTRY_TTL: Duration = Duration::from_secs(365 * 24 * 60 * 60);
 /// TTL for withdrawal tombstones (24 hours).
 const TOMBSTONE_TTL: Duration = Duration::from_secs(24 * 60 * 60);
 
+/// Outcome of an [`KvIdentityGraph::upsert_partner_id_if_exists`] call.
+///
+/// Unlike [`KvIdentityGraph::upsert_partner_id`] (which auto-creates entries),
+/// this enum encodes the per-mapping rejection reasons needed by the S2S
+/// batch sync endpoint.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum UpsertResult {
+    /// The partner ID was successfully written.
+    Written,
+    /// The KV key does not exist — S2S must not create new entries.
+    NotFound,
+    /// The entry's `consent.ok` is `false` (withdrawal tombstone).
+    ConsentWithdrawn,
+    /// The request timestamp is not newer than the stored `synced` value,
+    /// so the write was skipped. Counted as accepted by the batch endpoint.
+    Stale,
+}
+
 /// Wraps a Fastly KV Store for EC identity graph operations.
 ///
 /// Each EC hash (64-char hex prefix) maps to a JSON-encoded [`KvEntry`]
@@ -424,6 +442,90 @@ impl KvIdentityGraph {
         }))
     }
 
+    /// Upserts a partner ID only if the KV entry already exists.
+    ///
+    /// Unlike [`Self::upsert_partner_id`], this method does **not** create
+    /// entries for missing keys. Used by the S2S batch sync endpoint where
+    /// the KV entry must have been created by the organic EC flow.
+    ///
+    /// Returns [`UpsertResult::Stale`] when the stored `synced` timestamp
+    /// for this partner is already >= `synced`, skipping the write.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store I/O or CAS
+    /// exhaustion errors.
+    pub fn upsert_partner_id_if_exists(
+        &self,
+        ec_hash: &str,
+        partner_id: &str,
+        uid: &str,
+        synced: u64,
+    ) -> Result<UpsertResult, Report<TrustedServerError>> {
+        let store = self.open_store()?;
+
+        for attempt in 0..MAX_CAS_RETRIES {
+            let (mut entry, generation) = match self.get(ec_hash)? {
+                Some(pair) => pair,
+                None => return Ok(UpsertResult::NotFound),
+            };
+
+            if !entry.consent.ok {
+                return Ok(UpsertResult::ConsentWithdrawn);
+            }
+
+            // Skip if existing sync is at least as fresh as the request.
+            if let Some(existing) = entry.ids.get(partner_id) {
+                if existing.synced >= synced {
+                    return Ok(UpsertResult::Stale);
+                }
+            }
+
+            entry.ids.insert(
+                partner_id.to_owned(),
+                super::kv_types::KvPartnerId {
+                    uid: uid.to_owned(),
+                    synced,
+                },
+            );
+
+            let (body, meta_str) = Self::serialize_entry(&entry, &self.store_name)?;
+
+            match store
+                .build_insert()
+                .if_generation_match(generation)
+                .metadata(&meta_str)
+                .time_to_live(ENTRY_TTL)
+                .execute(ec_hash, body.as_str())
+            {
+                Ok(()) => return Ok(UpsertResult::Written),
+                Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
+                    log::debug!(
+                        "upsert_partner_id_if_exists: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_hash}'",
+                        attempt + 1,
+                    );
+                }
+                Err(err) => {
+                    return Err(
+                        Report::new(err).change_context(TrustedServerError::KvStore {
+                            store_name: self.store_name.clone(),
+                            message: format!(
+                                "Failed to upsert partner '{partner_id}' for key '{ec_hash}'"
+                            ),
+                        }),
+                    );
+                }
+            }
+        }
+
+        Err(Report::new(TrustedServerError::KvStore {
+            store_name: self.store_name.clone(),
+            message: format!(
+                "CAS conflict after {MAX_CAS_RETRIES} retries upserting partner '{partner_id}' for '{ec_hash}'"
+            ),
+        }))
+    }
+
     /// Updates the `last_seen` timestamp with a 300-second debounce.
     ///
     /// Skips the write if the stored `last_seen` is within
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index a8eab5b7..65df9662 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -23,8 +23,10 @@
 //! - [`sync_pixel`] — Pixel sync write endpoint (`GET /sync`)
 //! - [`identify`] — Browser identity read endpoint (`GET /identify`)
 //! - [`eids`] — Shared EID resolution and formatting helpers
+//! - [`batch_sync`] — S2S batch sync endpoint (`POST /api/v1/sync`)
 
 pub mod admin;
+pub mod batch_sync;
 pub mod consent;
 pub mod cookies;
 pub mod eids;
diff --git a/crates/trusted-server-core/src/ec/sync_pixel.rs b/crates/trusted-server-core/src/ec/sync_pixel.rs
index a129a65b..103e7600 100644
--- a/crates/trusted-server-core/src/ec/sync_pixel.rs
+++ b/crates/trusted-server-core/src/ec/sync_pixel.rs
@@ -15,7 +15,8 @@ use super::kv::KvIdentityGraph;
 use super::partner::{PartnerRecord, PartnerStore};
 use super::EcContext;
 
-const RATE_COUNTER_NAME: &str = "counter_store";
+/// Name of the Fastly rate counter resource used by sync rate limiting.
+pub const RATE_COUNTER_NAME: &str = "counter_store";
 
 /// Handles `GET /sync` pixel sync requests.
 ///
@@ -233,16 +234,43 @@ fn decode_query_fallback_consent(
     }
 }
 
-trait RateLimiter {
+/// Rate limiter abstraction for sync endpoints.
+///
+/// Used by both pixel sync (`/sync`) and batch sync (`/api/v1/sync`)
+/// for per-partner request rate enforcement.
+pub trait RateLimiter {
+    /// Returns `true` when the rate limit has been exceeded for the given key.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError`] on rate counter I/O failure.
     fn exceeded(&self, key: &str, hourly_limit: u32) -> Result<bool, Report<TrustedServerError>>;
+
+    /// Returns `true` when the per-minute rate limit has been exceeded.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError`] on rate counter I/O failure.
+    fn exceeded_per_minute(
+        &self,
+        key: &str,
+        per_minute_limit: u32,
+    ) -> Result<bool, Report<TrustedServerError>> {
+        // Default implementation maps a per-minute budget to the existing
+        // hourly API used by pixel sync.
+        self.exceeded(key, per_minute_limit.saturating_mul(60))
+    }
 }
 
-struct FastlyRateLimiter {
+/// Fastly Edge Rate Limiting implementation of [`RateLimiter`].
+pub struct FastlyRateLimiter {
     counter: RateCounter,
 }
 
 impl FastlyRateLimiter {
-    fn new(counter_name: &str) -> Self {
+    /// Creates a new rate limiter backed by the named Fastly rate counter.
+    #[must_use]
+    pub fn new(counter_name: &str) -> Self {
         Self {
             counter: RateCounter::open(counter_name),
         }
@@ -284,7 +312,9 @@ impl RateLimiter for FastlyRateLimiter {
     }
 }
 
-fn current_timestamp() -> u64 {
+/// Returns the current Unix timestamp in seconds.
+#[must_use]
+pub fn current_timestamp() -> u64 {
     std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
         .map(|d| d.as_secs())

From f42002333639a6bc81cf2f605af51fa3354fb967 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Wed, 25 Mar 2026 10:00:02 -0500
Subject: [PATCH 10/36] Add background pull-sync dispatch for organic routes

Implement Story 9 (#542): server-to-server pull sync that runs after
send_to_client() on organic traffic only. Refactors the Fastly adapter
entrypoint from #[fastly::main] to explicit Request::from_client() +
send_to_client() to enable post-send background work.

Pull sync enumerates pull-enabled partners, checks staleness against
pull_sync_ttl_sec, validates URL hosts against the partner allowlist,
enforces hourly rate limits, and dispatches concurrent outbound GETs
with Bearer auth. Responses with uid:null or 404 are no-ops; valid
UIDs are upserted into the identity graph.

Includes EC ID format validation to prevent dispatch on spoofed values,
partner list_registered() for KV store enumeration, and configurable
pull_sync_concurrency (default 3).
---
 .../trusted-server-adapter-fastly/src/main.rs | 209 +++++--
 crates/trusted-server-core/src/ec/mod.rs      |  21 +
 crates/trusted-server-core/src/ec/partner.rs  |  89 ++-
 .../trusted-server-core/src/ec/pull_sync.rs   | 539 ++++++++++++++++++
 crates/trusted-server-core/src/settings.rs    |  10 +
 trusted-server.toml                           |   2 +-
 6 files changed, 805 insertions(+), 65 deletions(-)
 create mode 100644 crates/trusted-server-core/src/ec/pull_sync.rs

diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 553d5253..0901adcd 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -16,6 +16,9 @@ use trusted_server_core::ec::finalize::ec_finalize_response;
 use trusted_server_core::ec::identify::{cors_preflight_identify, handle_identify};
 use trusted_server_core::ec::kv::KvIdentityGraph;
 use trusted_server_core::ec::partner::PartnerStore;
+use trusted_server_core::ec::pull_sync::{
+    build_pull_sync_context, dispatch_pull_sync, PullSyncContext,
+};
 use trusted_server_core::ec::sync_pixel::{handle_sync, FastlyRateLimiter, RATE_COUNTER_NAME};
 use trusted_server_core::ec::EcContext;
 use trusted_server_core::error::TrustedServerError;
@@ -43,21 +46,26 @@ mod route_tests;
 use crate::error::to_error_response;
 use crate::platform::{build_runtime_services, open_kv_store, UnavailableKvStore};
 
-#[fastly::main]
-fn main(req: Request) -> Result<Response, Error> {
+fn main() -> Result<(), Error> {
     init_logger();
 
+    let req = Request::from_client();
+
     // Keep the health probe independent from settings loading and routing so
     // readiness checks still get a cheap liveness response during startup.
     if req.get_method() == Method::GET && req.get_path() == "/health" {
-        return Ok(Response::from_status(200).with_body_text_plain("ok"));
+        Response::from_status(200)
+            .with_body_text_plain("ok")
+            .send_to_client();
+        return Ok(());
     }
 
     let settings = match get_settings() {
         Ok(s) => s,
         Err(e) => {
             log::error!("Failed to load settings: {:?}", e);
-            return Ok(to_error_response(&e));
+            to_error_response(&e).send_to_client();
+            return Ok(());
         }
     };
     log::debug!("Settings {settings:?}");
@@ -75,24 +83,37 @@ fn main(req: Request) -> Result<Response, Error> {
         Ok(r) => r,
         Err(e) => {
             log::error!("Failed to create integration registry: {:?}", e);
-            return Ok(to_error_response(&e));
+            to_error_response(&e).send_to_client();
+            return Ok(());
         }
     };
 
-    // Start with an unavailable KV slot. Consent-dependent routes lazily
-    // replace it with the configured store at dispatch time so unrelated
-    // routes stay available when consent persistence is misconfigured.
-    let kv_store = std::sync::Arc::new(UnavailableKvStore)
-        as std::sync::Arc<dyn trusted_server_core::platform::PlatformKvStore>;
-    let runtime_services = build_runtime_services(&req, kv_store);
-
-    futures::executor::block_on(route_request(
+    let outcome = futures::executor::block_on(route_request(
         &settings,
         &orchestrator,
         &integration_registry,
         &runtime_services,
         req,
-    ))
+    ))?;
+
+    let RouteOutcome {
+        response,
+        pull_sync_context,
+    } = outcome;
+
+    response.send_to_client();
+
+    if let Some(context) = pull_sync_context {
+        run_pull_sync_after_send(&settings, &context);
+    }
+
+    Ok(())
+}
+
+#[must_use]
+struct RouteOutcome {
+    response: Response,
+    pull_sync_context: Option<PullSyncContext>,
 }
 
 async fn route_request(
@@ -101,7 +122,7 @@ async fn route_request(
     integration_registry: &IntegrationRegistry,
     runtime_services: &RuntimeServices,
     mut req: Request,
-) -> Result<Response, Error> {
+) -> Result<RouteOutcome, Error> {
     // Strip client-spoofable forwarded headers at the edge.
     // On Fastly this service IS the first proxy — these headers from
     // clients are untrusted and can hijack URL rewriting (see #409).
@@ -122,7 +143,10 @@ async fn route_request(
             })
             .unwrap_or_else(|e| to_error_response(&e));
         finalize_response(settings, geo_info.as_ref(), &mut response);
-        return Ok(response);
+        return Ok(RouteOutcome {
+            response,
+            pull_sync_context: None,
+        });
     }
 
     let mut ec_context =
@@ -131,7 +155,10 @@ async fn route_request(
             Err(err) => {
                 let mut response = to_error_response(&err);
                 finalize_response(settings, geo_info.as_ref(), &mut response);
-                return Ok(response);
+                return Ok(RouteOutcome {
+                    response,
+                    pull_sync_context: None,
+                });
             }
         };
 
@@ -150,14 +177,20 @@ async fn route_request(
                 &mut response,
             );
             finalize_response(settings, geo_info.as_ref(), &mut response);
-            return Ok(response);
+            return Ok(RouteOutcome {
+                response,
+                pull_sync_context: None,
+            });
         }
         Ok(None) => {}
         Err(e) => {
             log::error!("Failed to evaluate basic auth: {:?}", e);
             let mut response = to_error_response(&e);
             finalize_response(settings, geo_info.as_ref(), &mut response);
-            return Ok(response);
+            return Ok(RouteOutcome {
+                response,
+                pull_sync_context: None,
+            });
         }
     }
 
@@ -166,71 +199,88 @@ async fn route_request(
     let method = req.get_method().clone();
 
     // Match known routes and handle them
-    let result = match (method, path.as_str()) {
+    let (result, organic_route) = match (method, path.as_str()) {
         // Serve the tsjs library
         (Method::GET, path) if path.starts_with("/static/tsjs=") => {
-            handle_tsjs_dynamic(&req, integration_registry)
+            (handle_tsjs_dynamic(&req, integration_registry), false)
         }
 
         // Discovery endpoint for trusted-server capabilities and JWKS
         (Method::GET, "/.well-known/trusted-server.json") => {
-            handle_trusted_server_discovery(settings, runtime_services, req)
+            (handle_trusted_server_discovery(settings, req), false)
         }
 
         // Signature verification endpoint
-        (Method::POST, "/verify-signature") => handle_verify_signature(settings, req),
+        (Method::POST, "/verify-signature") => (handle_verify_signature(settings, req), false),
 
         // Admin endpoints
         // Keep in sync with Settings::ADMIN_ENDPOINTS in crates/trusted-server-core/src/settings.rs
-        (Method::POST, "/admin/keys/rotate") => handle_rotate_key(settings, req),
-        (Method::POST, "/admin/keys/deactivate") => handle_deactivate_key(settings, req),
-        (Method::POST, "/admin/partners/register") => {
-            require_partner_store(settings).and_then(|store| handle_register_partner(&store, req))
-        }
-
-        (Method::GET, "/sync") => require_identity_graph(settings).and_then(|kv| {
-            require_partner_store(settings).and_then(|partner_store| {
-                handle_sync(settings, &kv, &partner_store, &req, &mut ec_context)
-            })
-        }),
-        (Method::GET, "/identify") => require_identity_graph(settings).and_then(|kv| {
-            require_partner_store(settings).and_then(|partner_store| {
-                handle_identify(settings, &kv, &partner_store, &req, &ec_context)
-            })
-        }),
-        (Method::OPTIONS, "/identify") => cors_preflight_identify(settings, &req),
+        (Method::POST, "/admin/keys/rotate") => (handle_rotate_key(settings, req), false),
+        (Method::POST, "/admin/keys/deactivate") => (handle_deactivate_key(settings, req), false),
+        (Method::POST, "/admin/partners/register") => (
+            require_partner_store(settings).and_then(|store| handle_register_partner(&store, req)),
+            false,
+        ),
+
+        (Method::GET, "/sync") => (
+            require_identity_graph(settings).and_then(|kv| {
+                require_partner_store(settings).and_then(|partner_store| {
+                    handle_sync(settings, &kv, &partner_store, &req, &mut ec_context)
+                })
+            }),
+            false,
+        ),
+        (Method::GET, "/identify") => (
+            require_identity_graph(settings).and_then(|kv| {
+                require_partner_store(settings).and_then(|partner_store| {
+                    handle_identify(settings, &kv, &partner_store, &req, &ec_context)
+                })
+            }),
+            false,
+        ),
+        (Method::OPTIONS, "/identify") => (cors_preflight_identify(settings, &req), false),
 
         // Unified auction endpoint (returns creative HTML inline)
         (Method::POST, "/auction") => {
             let partner_store = require_partner_store(settings).ok();
-            handle_auction(
-                settings,
-                orchestrator,
-                kv_graph.as_ref(),
-                partner_store.as_ref(),
-                &ec_context,
-                req,
+            (
+                handle_auction(
+                    settings,
+                    orchestrator,
+                    kv_graph.as_ref(),
+                    partner_store.as_ref(),
+                    &ec_context,
+                    req,
+                )
+                .await,
+                false,
             )
-            .await
         }
 
         // tsjs endpoints
-        (Method::GET, "/first-party/proxy") => handle_first_party_proxy(settings, req).await,
-        (Method::GET, "/first-party/click") => handle_first_party_click(settings, req).await,
+        (Method::GET, "/first-party/proxy") => {
+            (handle_first_party_proxy(settings, req).await, false)
+        }
+        (Method::GET, "/first-party/click") => {
+            (handle_first_party_click(settings, req).await, false)
+        }
         (Method::GET, "/first-party/sign") | (Method::POST, "/first-party/sign") => {
-            handle_first_party_proxy_sign(settings, req).await
+            (handle_first_party_proxy_sign(settings, req).await, false)
         }
         (Method::POST, "/first-party/proxy-rebuild") => {
-            handle_first_party_proxy_rebuild(settings, req).await
+            (handle_first_party_proxy_rebuild(settings, req).await, false)
+        }
+        (m, path) if integration_registry.has_route(&m, path) => {
+            let result = integration_registry
+                .handle_proxy(&m, path, settings, kv_graph.as_ref(), &mut ec_context, req)
+                .await
+                .unwrap_or_else(|| {
+                    Err(Report::new(TrustedServerError::BadRequest {
+                        message: format!("Unknown integration route: {path}"),
+                    }))
+                });
+            (result, true)
         }
-        (m, path) if integration_registry.has_route(&m, path) => integration_registry
-            .handle_proxy(&m, path, settings, kv_graph.as_ref(), &mut ec_context, req)
-            .await
-            .unwrap_or_else(|| {
-                Err(Report::new(TrustedServerError::BadRequest {
-                    message: format!("Unknown integration route: {path}"),
-                }))
-            }),
 
         // No known route matched, proxy to publisher origin as fallback
         _ => {
@@ -239,7 +289,7 @@ async fn route_request(
                 path
             );
 
-            match handle_publisher_request(
+            let result = match handle_publisher_request(
                 settings,
                 integration_registry,
                 kv_graph.as_ref(),
@@ -251,10 +301,13 @@ async fn route_request(
                     log::error!("Failed to proxy to publisher origin: {:?}", e);
                     Err(e)
                 }
-            }
+            };
+            (result, true)
         }
     };
 
+    let route_succeeded = result.is_ok();
+
     // Convert any errors to HTTP error responses
     let mut response = result.unwrap_or_else(|e| to_error_response(&e));
 
@@ -268,13 +321,43 @@ async fn route_request(
 
     finalize_response(settings, geo_info.as_ref(), &mut response);
 
-    Ok(response)
+    let pull_sync_context = if organic_route && route_succeeded {
+        build_pull_sync_context(&ec_context)
+    } else {
+        None
+    };
+
+    Ok(RouteOutcome {
+        response,
+        pull_sync_context,
+    })
 }
 
 fn maybe_identity_graph(settings: &Settings) -> Option<KvIdentityGraph> {
     settings.ec.ec_store.as_ref().map(KvIdentityGraph::new)
 }
 
+fn run_pull_sync_after_send(settings: &Settings, context: &PullSyncContext) {
+    let kv = match require_identity_graph(settings) {
+        Ok(kv) => kv,
+        Err(err) => {
+            log::debug!("Pull sync: identity graph unavailable, skipping: {err:?}");
+            return;
+        }
+    };
+
+    let partner_store = match require_partner_store(settings) {
+        Ok(store) => store,
+        Err(err) => {
+            log::debug!("Pull sync: partner store unavailable, skipping: {err:?}");
+            return;
+        }
+    };
+
+    let limiter = FastlyRateLimiter::new(RATE_COUNTER_NAME);
+    dispatch_pull_sync(settings, &kv, &partner_store, &limiter, context);
+}
+
 /// Applies all standard response headers: geo, version, staging, and configured headers.
 ///
 /// Called from every response path (including auth early-returns) so that all
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index 65df9662..4723379d 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -24,6 +24,7 @@
 //! - [`identify`] — Browser identity read endpoint (`GET /identify`)
 //! - [`eids`] — Shared EID resolution and formatting helpers
 //! - [`batch_sync`] — S2S batch sync endpoint (`POST /api/v1/sync`)
+//! - [`pull_sync`] — Background pull-sync dispatcher for organic routes
 
 pub mod admin;
 pub mod batch_sync;
@@ -36,6 +37,7 @@ pub mod identify;
 pub mod kv;
 pub mod kv_types;
 pub mod partner;
+pub mod pull_sync;
 pub mod sync_pixel;
 
 use cookie::CookieJar;
@@ -362,6 +364,25 @@ impl EcContext {
             geo_info: None,
         }
     }
+
+    /// Creates a test-only [`EcContext`] with explicit client IP.
+    #[cfg(test)]
+    #[must_use]
+    pub fn new_for_test_with_ip(
+        ec_value: Option<String>,
+        consent: ConsentContext,
+        client_ip: Option<String>,
+    ) -> Self {
+        Self {
+            ec_was_present: ec_value.is_some(),
+            cookie_ec_value: ec_value.clone(),
+            ec_value,
+            ec_generated: false,
+            consent,
+            client_ip,
+            geo_info: None,
+        }
+    }
 }
 
 fn current_timestamp() -> u64 {
diff --git a/crates/trusted-server-core/src/ec/partner.rs b/crates/trusted-server-core/src/ec/partner.rs
index 7e1566a8..b83e8e41 100644
--- a/crates/trusted-server-core/src/ec/partner.rs
+++ b/crates/trusted-server-core/src/ec/partner.rs
@@ -137,9 +137,18 @@ pub fn validate_pull_sync_config(record: &PartnerRecord) -> Result<(), String> {
         );
     }
 
-    // Validate that the pull sync URL hostname is in the allowed domains.
+    // Validate that the pull sync URL uses HTTPS (bearer tokens must not
+    // travel over plaintext).
     let parsed =
         url::Url::parse(url_str).map_err(|e| format!("pull_sync_url is not a valid URL: {e}"))?;
+    if parsed.scheme() != "https" {
+        return Err(format!(
+            "pull_sync_url must use HTTPS, got scheme '{}'",
+            parsed.scheme()
+        ));
+    }
+
+    // Validate that the pull sync URL hostname is in the allowed domains.
     let host = parsed
         .host_str()
         .ok_or("pull_sync_url has no hostname")?
@@ -241,6 +250,58 @@ impl PartnerStore {
         Ok(Some(record))
     }
 
+    /// Lists all registered partner records.
+    ///
+    /// Scans the partner KV store and returns records for non-index keys.
+    /// Secondary index entries (e.g. `apikey:*`) are skipped.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on list, lookup, or
+    /// deserialization failure.
+    pub fn list_registered(&self) -> Result<Vec<PartnerRecord>, Report<TrustedServerError>> {
+        let store = self.open_store()?;
+        let mut records = Vec::new();
+
+        for page in store.build_list().limit(1000).iter() {
+            let page = page.change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: "Failed to list partner keys".to_owned(),
+            })?;
+
+            for key in page.keys() {
+                if key.starts_with(APIKEY_INDEX_PREFIX) {
+                    continue;
+                }
+
+                let mut response = match store.lookup(key) {
+                    Ok(resp) => resp,
+                    Err(fastly::kv_store::KVStoreError::ItemNotFound) => continue,
+                    Err(err) => {
+                        return Err(
+                            Report::new(err).change_context(TrustedServerError::KvStore {
+                                store_name: self.store_name.clone(),
+                                message: format!("Failed to read partner '{key}' while listing"),
+                            }),
+                        );
+                    }
+                };
+
+                let body_bytes = response.take_body_bytes();
+                let record = serde_json::from_slice::<PartnerRecord>(&body_bytes).change_context(
+                    TrustedServerError::KvStore {
+                        store_name: self.store_name.clone(),
+                        message: format!("Failed to deserialize partner '{key}' while listing"),
+                    },
+                )?;
+
+                records.push(record);
+            }
+        }
+
+        Ok(records)
+    }
+
     /// Writes or updates a partner record and maintains the API key index.
     ///
     /// Returns `true` if this was a new partner (create), `false` if an
@@ -651,6 +712,32 @@ mod tests {
         assert!(err.contains("ts_pull_token"), "got: {err}");
     }
 
+    #[test]
+    fn validate_pull_sync_rejects_http_scheme() {
+        let record = PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: true,
+            pull_sync_url: Some("http://sync.test.com/pull".to_owned()),
+            pull_sync_allowed_domains: vec!["sync.test.com".to_owned()],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: Some("token".to_owned()),
+        };
+        let err = validate_pull_sync_config(&record).unwrap_err();
+        assert!(
+            err.contains("HTTPS"),
+            "should reject HTTP scheme, got: {err}"
+        );
+    }
+
     #[test]
     fn validate_pull_sync_rejects_url_not_in_allowed_domains() {
         let record = PartnerRecord {
diff --git a/crates/trusted-server-core/src/ec/pull_sync.rs b/crates/trusted-server-core/src/ec/pull_sync.rs
new file mode 100644
index 00000000..d07c15e0
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/pull_sync.rs
@@ -0,0 +1,539 @@
+//! Pull sync background dispatch.
+//!
+//! Launches partner pull-sync requests for organic traffic after the client
+//! response has been sent. Dispatch is best-effort and never affects client
+//! response status.
+
+use fastly::http::request::PendingRequest;
+use fastly::http::{Method, StatusCode};
+use fastly::Request;
+use serde::Deserialize;
+use url::Url;
+
+use crate::backend::BackendConfig;
+use crate::settings::Settings;
+
+use super::generation::is_valid_ec_id;
+use super::kv::KvIdentityGraph;
+use super::kv_types::KvEntry;
+use super::partner::{PartnerRecord, PartnerStore};
+use super::sync_pixel::{current_timestamp, RateLimiter};
+use super::EcContext;
+
+/// Inputs needed to dispatch pull sync after response flush.
+#[derive(Debug, Clone)]
+pub struct PullSyncContext {
+    ec_hash: String,
+    client_ip: String,
+}
+
+impl PullSyncContext {
+    /// Returns the stable EC hash for the request.
+    #[must_use]
+    pub fn ec_hash(&self) -> &str {
+        &self.ec_hash
+    }
+
+    /// Returns the normalized client IP for pull endpoint query parameters.
+    #[must_use]
+    pub fn client_ip(&self) -> &str {
+        &self.client_ip
+    }
+}
+
+struct InFlightPull {
+    partner_id: String,
+    pending: PendingRequest,
+}
+
+#[derive(Debug, Deserialize)]
+struct PullSyncResponse {
+    uid: Option<String>,
+}
+
+/// Builds post-send pull-sync context from the route EC context.
+///
+/// Returns `None` when consent denies EC, there is no active EC hash, or no
+/// client IP is available.
+#[must_use]
+pub fn build_pull_sync_context(ec_context: &EcContext) -> Option<PullSyncContext> {
+    if !ec_context.ec_allowed() {
+        return None;
+    }
+
+    let ec_id = ec_context.ec_value()?;
+    if !is_valid_ec_id(ec_id) {
+        log::debug!("Pull sync: skipping dispatch because active EC ID is invalid format");
+        return None;
+    }
+
+    let ec_hash = ec_context.ec_hash()?.to_owned();
+    let client_ip = ec_context.client_ip()?.to_owned();
+    Some(PullSyncContext { ec_hash, client_ip })
+}
+
+/// Dispatches partner pull-sync requests in the background.
+///
+/// This function is best-effort: all errors are logged and swallowed.
+pub fn dispatch_pull_sync(
+    settings: &Settings,
+    kv: &KvIdentityGraph,
+    partner_store: &PartnerStore,
+    rate_limiter: &dyn RateLimiter,
+    context: &PullSyncContext,
+) {
+    let now = current_timestamp();
+    let kv_entry = match kv.get(context.ec_hash()) {
+        Ok(entry) => entry.map(|(entry, _)| entry),
+        Err(err) => {
+            log::warn!(
+                "Pull sync: failed to read identity graph for '{}': {err:?}",
+                context.ec_hash()
+            );
+            return;
+        }
+    };
+
+    let partners = match partner_store.list_registered() {
+        Ok(partners) => partners,
+        Err(err) => {
+            log::warn!("Pull sync: failed to list partners: {err:?}");
+            return;
+        }
+    };
+
+    let pull_enabled_count = partners.iter().filter(|p| p.pull_sync_enabled).count();
+    log::debug!(
+        "Pull sync: enumerated {} partners ({} pull-enabled)",
+        partners.len(),
+        pull_enabled_count
+    );
+
+    if pull_enabled_count == 0 {
+        return;
+    }
+
+    let max_concurrency = settings.ec.pull_sync_concurrency.max(1);
+    let mut in_flight: Vec<InFlightPull> = Vec::new();
+
+    for partner in partners {
+        if !partner.pull_sync_enabled {
+            continue;
+        }
+
+        if !is_partner_pull_eligible(&partner, kv_entry.as_ref(), now) {
+            continue;
+        }
+
+        let Some(url) = validated_pull_sync_url(&partner) else {
+            continue;
+        };
+
+        let rate_key = format!("pull:{}:{}", partner.id, context.ec_hash());
+        match rate_limiter.exceeded(&rate_key, partner.pull_sync_rate_limit) {
+            Ok(true) => {
+                log::debug!(
+                    "Pull sync: rate-limited partner '{}' for hash '{}'",
+                    partner.id,
+                    context.ec_hash()
+                );
+                continue;
+            }
+            Ok(false) => {}
+            Err(err) => {
+                log::warn!(
+                    "Pull sync: failed to read rate limit for partner '{}': {err:?}",
+                    partner.id
+                );
+                continue;
+            }
+        }
+
+        let Some(token) = partner.ts_pull_token.as_deref() else {
+            log::warn!(
+                "Pull sync: partner '{}' enabled but missing ts_pull_token",
+                partner.id
+            );
+            continue;
+        };
+
+        let request_url = build_pull_request_url(url, context.ec_hash(), context.client_ip());
+        let mut request = Request::new(Method::GET, request_url.as_str());
+        request.set_header("authorization", format!("Bearer {token}"));
+
+        let backend_name =
+            match BackendConfig::from_url(request_url.as_str(), settings.proxy.certificate_check) {
+                Ok(name) => name,
+                Err(err) => {
+                    log::warn!(
+                        "Pull sync: failed to resolve backend for partner '{}': {err:?}",
+                        partner.id
+                    );
+                    continue;
+                }
+            };
+
+        let pending = match request.send_async(backend_name) {
+            Ok(pending) => pending,
+            Err(err) => {
+                log::warn!(
+                    "Pull sync: failed to dispatch partner '{}': {err:?}",
+                    partner.id
+                );
+                continue;
+            }
+        };
+
+        in_flight.push(InFlightPull {
+            partner_id: partner.id,
+            pending,
+        });
+
+        if in_flight.len() >= max_concurrency {
+            drain_pull_batch(kv, context.ec_hash(), &mut in_flight);
+        }
+    }
+
+    drain_pull_batch(kv, context.ec_hash(), &mut in_flight);
+}
+
+fn is_partner_pull_eligible(partner: &PartnerRecord, kv_entry: Option<&KvEntry>, now: u64) -> bool {
+    let Some(entry) = kv_entry else {
+        return true;
+    };
+
+    let Some(existing) = entry.ids.get(&partner.id) else {
+        return true;
+    };
+
+    now.saturating_sub(existing.synced) >= partner.pull_sync_ttl_sec
+}
+
+fn validated_pull_sync_url(partner: &PartnerRecord) -> Option<Url> {
+    let pull_sync_url = partner.pull_sync_url.as_deref()?;
+    let parsed = match Url::parse(pull_sync_url) {
+        Ok(url) => url,
+        Err(err) => {
+            log::error!(
+                "Pull sync: partner '{}' has invalid pull_sync_url '{}': {err}",
+                partner.id,
+                pull_sync_url
+            );
+            return None;
+        }
+    };
+
+    if parsed.scheme() != "https" {
+        log::error!(
+            "Pull sync: partner '{}' pull_sync_url must use HTTPS, got scheme '{}'",
+            partner.id,
+            parsed.scheme()
+        );
+        return None;
+    }
+
+    let Some(hostname) = parsed.host_str() else {
+        log::error!(
+            "Pull sync: partner '{}' pull_sync_url has no hostname: {}",
+            partner.id,
+            pull_sync_url
+        );
+        return None;
+    };
+
+    let hostname = hostname.trim_end_matches('.').to_ascii_lowercase();
+    if !partner.pull_sync_allowed_domains.iter().any(|domain| {
+        domain
+            .trim()
+            .trim_end_matches('.')
+            .eq_ignore_ascii_case(&hostname)
+    }) {
+        log::error!(
+            "Pull sync: partner '{}' URL host '{}' not in pull_sync_allowed_domains",
+            partner.id,
+            hostname
+        );
+        return None;
+    }
+
+    Some(parsed)
+}
+
+fn build_pull_request_url(mut base_url: Url, ec_hash: &str, client_ip: &str) -> Url {
+    base_url
+        .query_pairs_mut()
+        .append_pair("ec_hash", ec_hash)
+        .append_pair("ip", client_ip);
+    base_url
+}
+
+fn drain_pull_batch(kv: &KvIdentityGraph, ec_hash: &str, in_flight: &mut Vec<InFlightPull>) {
+    for pending in in_flight.drain(..) {
+        let partner_id = pending.partner_id;
+        let response = match pending.pending.wait() {
+            Ok(response) => response,
+            Err(err) => {
+                log::warn!(
+                    "Pull sync: request failed for partner '{}': {err:?}",
+                    partner_id
+                );
+                continue;
+            }
+        };
+
+        let Some(uid) = extract_pull_uid(response, &partner_id) else {
+            continue;
+        };
+
+        if let Err(err) = kv.upsert_partner_id(ec_hash, &partner_id, &uid, current_timestamp()) {
+            log::warn!(
+                "Pull sync: failed to upsert partner '{}' for hash '{}': {err:?}",
+                partner_id,
+                ec_hash
+            );
+        }
+    }
+}
+
+fn extract_pull_uid(mut response: fastly::Response, partner_id: &str) -> Option<String> {
+    let status = response.get_status();
+
+    if status == StatusCode::NOT_FOUND {
+        log::debug!(
+            "Pull sync: partner '{}' returned 404, treating as no-op",
+            partner_id
+        );
+        return None;
+    }
+
+    if !status.is_success() {
+        log::warn!(
+            "Pull sync: partner '{}' returned non-success status {}",
+            partner_id,
+            status
+        );
+        return None;
+    }
+
+    let body = response.take_body_bytes();
+    let payload = match serde_json::from_slice::<PullSyncResponse>(&body) {
+        Ok(payload) => payload,
+        Err(err) => {
+            log::warn!(
+                "Pull sync: partner '{}' returned invalid JSON body: {err}",
+                partner_id
+            );
+            return None;
+        }
+    };
+
+    const MAX_UID_LENGTH: usize = 256;
+
+    let uid = payload.uid.filter(|value| !value.is_empty());
+    match uid {
+        None => {
+            log::debug!(
+                "Pull sync: partner '{}' returned null/empty uid, treating as no-op",
+                partner_id
+            );
+            None
+        }
+        Some(ref value) if value.len() > MAX_UID_LENGTH => {
+            log::warn!(
+                "Pull sync: partner '{}' returned uid exceeding {} bytes (got {}), rejecting",
+                partner_id,
+                MAX_UID_LENGTH,
+                value.len()
+            );
+            None
+        }
+        _ => uid,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::consent::types::ConsentContext;
+    use crate::ec::kv_types::KvEntry;
+
+    fn pull_partner(ttl_sec: u64) -> PartnerRecord {
+        PartnerRecord {
+            id: "ssp_x".to_owned(),
+            name: "SSP X".to_owned(),
+            allowed_return_domains: vec!["sync.example.com".to_owned()],
+            api_key_hash: "deadbeef".to_owned(),
+            bidstream_enabled: true,
+            source_domain: "ssp.example.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 60,
+            batch_rate_limit: 60,
+            pull_sync_enabled: true,
+            pull_sync_url: Some("https://sync.partner.test/pull".to_owned()),
+            pull_sync_allowed_domains: vec!["sync.partner.test".to_owned()],
+            pull_sync_ttl_sec: ttl_sec,
+            pull_sync_rate_limit: 20,
+            ts_pull_token: Some("token".to_owned()),
+        }
+    }
+
+    #[test]
+    fn build_pull_sync_context_requires_ec_and_ip() {
+        let consent = ConsentContext {
+            jurisdiction: crate::consent::jurisdiction::Jurisdiction::NonRegulated,
+            ..ConsentContext::default()
+        };
+        let ec_context =
+            EcContext::new_for_test(Some(format!("{}.ABC123", "a".repeat(64))), consent);
+
+        let context = build_pull_sync_context(&ec_context);
+        assert!(
+            context.is_none(),
+            "should require client_ip for pull sync dispatch context"
+        );
+    }
+
+    #[test]
+    fn build_pull_sync_context_returns_context_when_valid() {
+        let consent = ConsentContext {
+            jurisdiction: crate::consent::jurisdiction::Jurisdiction::NonRegulated,
+            ..ConsentContext::default()
+        };
+        let ec_id = format!("{}.ABC123", "a".repeat(64));
+        let ec_context =
+            EcContext::new_for_test_with_ip(Some(ec_id), consent, Some("1.2.3.4".to_owned()));
+
+        let context = build_pull_sync_context(&ec_context)
+            .expect("should build pull sync context for valid EC with IP");
+        assert_eq!(context.ec_hash(), "a".repeat(64).as_str());
+        assert_eq!(context.client_ip(), "1.2.3.4");
+    }
+
+    #[test]
+    fn build_pull_sync_context_rejects_invalid_ec_id() {
+        let consent = ConsentContext {
+            jurisdiction: crate::consent::jurisdiction::Jurisdiction::NonRegulated,
+            ..ConsentContext::default()
+        };
+        let ec_context = EcContext::new_for_test_with_ip(
+            Some("invalid-ec".to_owned()),
+            consent,
+            Some("1.2.3.4".to_owned()),
+        );
+
+        let context = build_pull_sync_context(&ec_context);
+        assert!(
+            context.is_none(),
+            "should reject pull sync context when EC ID format is invalid"
+        );
+    }
+
+    #[test]
+    fn partner_is_eligible_when_missing_from_entry() {
+        let partner = pull_partner(3600);
+        let entry = KvEntry::minimal("other_partner", "uid-1", 100);
+
+        assert!(
+            is_partner_pull_eligible(&partner, Some(&entry), 200),
+            "should dispatch when partner has no stored sync"
+        );
+    }
+
+    #[test]
+    fn partner_is_not_eligible_when_not_stale() {
+        let partner = pull_partner(3600);
+        let entry = KvEntry::minimal("ssp_x", "uid-1", 1000);
+
+        assert!(
+            !is_partner_pull_eligible(&partner, Some(&entry), 1500),
+            "should skip dispatch when sync is fresher than ttl"
+        );
+    }
+
+    #[test]
+    fn validated_pull_sync_url_rejects_http_scheme() {
+        let mut partner = pull_partner(3600);
+        partner.pull_sync_url = Some("http://sync.partner.test/pull".to_owned());
+
+        let validated = validated_pull_sync_url(&partner);
+        assert!(
+            validated.is_none(),
+            "should reject pull_sync_url with HTTP scheme"
+        );
+    }
+
+    #[test]
+    fn validated_pull_sync_url_rejects_non_allowlisted_host() {
+        let mut partner = pull_partner(3600);
+        partner.pull_sync_url = Some("https://evil.test/pull".to_owned());
+
+        let validated = validated_pull_sync_url(&partner);
+        assert!(
+            validated.is_none(),
+            "should reject runtime pull_sync_url host outside allowlist"
+        );
+    }
+
+    #[test]
+    fn validated_pull_sync_url_accepts_normalized_allowlist_match() {
+        let mut partner = pull_partner(3600);
+        partner.pull_sync_url = Some("https://SYNC.PARTNER.TEST./pull".to_owned());
+        partner.pull_sync_allowed_domains = vec!["sync.partner.test".to_owned()];
+
+        let validated = validated_pull_sync_url(&partner);
+        assert!(
+            validated.is_some(),
+            "should accept allowlist match after hostname normalization"
+        );
+    }
+
+    #[test]
+    fn build_pull_request_url_appends_query_pairs() {
+        let url = Url::parse("https://sync.partner.test/pull?x=1").expect("should parse URL");
+        let result = build_pull_request_url(url, "hash123", "1.2.3.4");
+
+        let query = result.query().expect("should have query string");
+        assert!(query.contains("x=1"), "should preserve existing query");
+        assert!(query.contains("ec_hash=hash123"), "should append ec_hash");
+        assert!(query.contains("ip=1.2.3.4"), "should append ip");
+    }
+
+    #[test]
+    fn extract_pull_uid_treats_404_as_noop() {
+        let response = fastly::Response::from_status(StatusCode::NOT_FOUND);
+
+        let uid = extract_pull_uid(response, "ssp_x");
+        assert!(uid.is_none(), "should treat 404 as no-op");
+    }
+
+    #[test]
+    fn extract_pull_uid_treats_uid_null_as_noop() {
+        let response = fastly::Response::from_status(StatusCode::OK).with_body("{\"uid\":null}");
+
+        let uid = extract_pull_uid(response, "ssp_x");
+        assert!(uid.is_none(), "should treat uid=null as no-op");
+    }
+
+    #[test]
+    fn extract_pull_uid_rejects_oversized_uid() {
+        let long_uid = "x".repeat(257);
+        let body = format!("{{\"uid\":\"{long_uid}\"}}");
+        let response = fastly::Response::from_status(StatusCode::OK).with_body(body);
+
+        let uid = extract_pull_uid(response, "ssp_x");
+        assert!(uid.is_none(), "should reject uid exceeding 256 bytes");
+    }
+
+    #[test]
+    fn extract_pull_uid_reads_uid_from_success_body() {
+        let response =
+            fastly::Response::from_status(StatusCode::OK).with_body("{\"uid\":\"abc123\"}");
+
+        let uid = extract_pull_uid(response, "ssp_x");
+        assert_eq!(
+            uid.as_deref(),
+            Some("abc123"),
+            "should parse uid from 200 body"
+        );
+    }
+}
diff --git a/crates/trusted-server-core/src/settings.rs b/crates/trusted-server-core/src/settings.rs
index 3fb91fc6..6d8b714d 100644
--- a/crates/trusted-server-core/src/settings.rs
+++ b/crates/trusted-server-core/src/settings.rs
@@ -235,12 +235,22 @@ pub struct Ec {
     /// Required for Story 4+ (partner registry).
     #[serde(default)]
     pub partner_store: Option<String>,
+
+    /// Maximum number of concurrent pull-sync requests.
+    #[serde(default = "Ec::default_pull_sync_concurrency")]
+    pub pull_sync_concurrency: usize,
 }
 
 impl Ec {
     /// Known placeholder values that must not be used in production.
     pub const PASSPHRASE_PLACEHOLDERS: &[&str] = &["secret-key", "secret_key", "trusted-server"];
 
+    /// Default maximum concurrent pull-sync requests.
+    #[must_use]
+    pub const fn default_pull_sync_concurrency() -> usize {
+        3
+    }
+
     /// Returns `true` if `passphrase` matches a known placeholder value
     /// (case-insensitive).
     #[must_use]
diff --git a/trusted-server.toml b/trusted-server.toml
index bf0cf199..3c3316e1 100644
--- a/trusted-server.toml
+++ b/trusted-server.toml
@@ -18,6 +18,7 @@ proxy_secret = "change-me-proxy-secret"
 passphrase = "trusted-server"
 ec_store = "ec_identity_store"
 partner_store = "ec_partner_store"
+pull_sync_concurrency = 3
 
 # Custom headers to be included in every response
 # Allows publishers to include tags such as X-Robots-Tag: noindex
@@ -192,4 +193,3 @@ timeout_ms = 1000
 [integrations.adserver_mock.context_query_params]
 permutive_segments = "permutive"
 
-

From ad20ad96125b86ebed61160006928087f45ef85d Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Wed, 25 Mar 2026 18:59:59 -0500
Subject: [PATCH 11/36] Add EC lifecycle integration test scenarios

Implement Story 11 (#544): Viceroy-driven E2E tests covering full EC
lifecycle (generation, pixel sync, identify, batch sync, consent
withdrawal, auth rejection). Adds EC test helpers with manual cookie
tracking, minimal origin server with graceful shutdown, and required
KV store fixtures. Fixes integration build env vars.
---
 .../setup-integration-test-env/action.yml     |   2 +-
 crates/integration-tests/Cargo.lock           |  69 +++
 crates/integration-tests/Cargo.toml           |   3 +-
 .../fixtures/configs/viceroy-template.toml    |  12 +
 crates/integration-tests/tests/common/ec.rs   | 447 ++++++++++++++++++
 crates/integration-tests/tests/common/mod.rs  |   1 +
 .../integration-tests/tests/common/runtime.rs |  13 +
 .../tests/frameworks/scenarios.rs             | 349 +++++++++++++-
 crates/integration-tests/tests/integration.rs |  39 +-
 scripts/integration-tests-browser.sh          |   2 +-
 scripts/integration-tests.sh                  |   2 +-
 11 files changed, 933 insertions(+), 6 deletions(-)
 create mode 100644 crates/integration-tests/tests/common/ec.rs

diff --git a/.github/actions/setup-integration-test-env/action.yml b/.github/actions/setup-integration-test-env/action.yml
index e61d129b..e6572158 100644
--- a/.github/actions/setup-integration-test-env/action.yml
+++ b/.github/actions/setup-integration-test-env/action.yml
@@ -71,7 +71,7 @@ runs:
       env:
         TRUSTED_SERVER__PUBLISHER__ORIGIN_URL: http://127.0.0.1:${{ inputs.origin-port }}
         TRUSTED_SERVER__PUBLISHER__PROXY_SECRET: integration-test-proxy-secret
-        TRUSTED_SERVER__EDGE_COOKIE__SECRET_KEY: integration-test-secret-key
+        TRUSTED_SERVER__EC__PASSPHRASE: integration-test-ec-secret
         TRUSTED_SERVER__PROXY__CERTIFICATE_CHECK: "false"
       run: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
 
diff --git a/crates/integration-tests/Cargo.lock b/crates/integration-tests/Cargo.lock
index 9b98a638..06b8a551 100644
--- a/crates/integration-tests/Cargo.lock
+++ b/crates/integration-tests/Cargo.lock
@@ -349,6 +349,35 @@ dependencies = [
  "unicode-segmentation",
 ]
 
+[[package]]
+name = "cookie"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ddef33a339a91ea89fb53151bd0a4689cfce27055c291dfa69945475d22c747"
+dependencies = [
+ "percent-encoding",
+ "time",
+ "version_check",
+]
+
+[[package]]
+name = "cookie_store"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15b2c103cf610ec6cae3da84a766285b42fd16aad564758459e6ecf128c75206"
+dependencies = [
+ "cookie",
+ "document-features",
+ "idna",
+ "log",
+ "publicsuffix",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "time",
+ "url",
+]
+
 [[package]]
 name = "core-foundation"
 version = "0.9.4"
@@ -498,6 +527,15 @@ dependencies = [
  "serde_json",
 ]
 
+[[package]]
+name = "document-features"
+version = "0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61"
+dependencies = [
+ "litrs",
+]
+
 [[package]]
 name = "dtoa"
 version = "1.0.11"
@@ -1225,6 +1263,7 @@ dependencies = [
  "scraper",
  "serde_json",
  "testcontainers",
+ "urlencoding",
 ]
 
 [[package]]
@@ -1334,6 +1373,12 @@ version = "0.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6373607a59f0be73a39b6fe456b8192fcc3585f602af20751600e974dd455e77"
 
+[[package]]
+name = "litrs"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
+
 [[package]]
 name = "lock_api"
 version = "0.4.14"
@@ -1813,6 +1858,22 @@ dependencies = [
  "prost",
 ]
 
+[[package]]
+name = "psl-types"
+version = "2.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33cb294fe86a74cbcf50d4445b37da762029549ebeea341421c7c70370f86cac"
+
+[[package]]
+name = "publicsuffix"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f42ea446cab60335f76979ec15e12619a2165b5ae2c12166bef27d283a9fadf"
+dependencies = [
+ "idna",
+ "psl-types",
+]
+
 [[package]]
 name = "quote"
 version = "1.0.45"
@@ -1953,6 +2014,8 @@ checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
 dependencies = [
  "base64 0.22.1",
  "bytes",
+ "cookie",
+ "cookie_store",
  "encoding_rs",
  "futures-channel",
  "futures-core",
@@ -2848,6 +2911,12 @@ dependencies = [
  "serde_derive",
 ]
 
+[[package]]
+name = "urlencoding"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "daf8dba3b7eb870caf1ddeed7bc9d2a049f3cfdfae7cb521b087cc33ae4c49da"
+
 [[package]]
 name = "utf-8"
 version = "0.7.6"
diff --git a/crates/integration-tests/Cargo.toml b/crates/integration-tests/Cargo.toml
index 24d0cdcc..9bfd696f 100644
--- a/crates/integration-tests/Cargo.toml
+++ b/crates/integration-tests/Cargo.toml
@@ -11,10 +11,11 @@ harness = true
 
 [dev-dependencies]
 testcontainers = { version = "0.25", features = ["blocking"] }
-reqwest = { version = "0.12", features = ["blocking"] }
+reqwest = { version = "0.12", features = ["blocking", "cookies", "json"] }
 scraper = "0.21"
 log = "0.4.29"
 serde_json = "1.0.149"
 error-stack = "0.6"
 derive_more = { version = "2.0", features = ["display"] }
 env_logger = "0.11"
+urlencoding = "2.1"
diff --git a/crates/integration-tests/fixtures/configs/viceroy-template.toml b/crates/integration-tests/fixtures/configs/viceroy-template.toml
index 68e8bd15..ddc3c580 100644
--- a/crates/integration-tests/fixtures/configs/viceroy-template.toml
+++ b/crates/integration-tests/fixtures/configs/viceroy-template.toml
@@ -21,6 +21,18 @@
             key = "placeholder"
             data = "placeholder"
 
+        [[local_server.kv_stores.consent_store]]
+            key = "placeholder"
+            data = "placeholder"
+
+        [[local_server.kv_stores.ec_identity_store]]
+            key = "placeholder"
+            data = "placeholder"
+
+        [[local_server.kv_stores.ec_partner_store]]
+            key = "placeholder"
+            data = "placeholder"
+
     # These are generated test-only key pairs, not production credentials.
     # The Ed25519 private key (data) and its matching public key (x in jwks_store below)
     # exist solely for signing and verifying tokens in the integration test environment.
diff --git a/crates/integration-tests/tests/common/ec.rs b/crates/integration-tests/tests/common/ec.rs
new file mode 100644
index 00000000..b918faff
--- /dev/null
+++ b/crates/integration-tests/tests/common/ec.rs
@@ -0,0 +1,447 @@
+//! EC integration test helpers.
+//!
+//! Provides a cookie-aware HTTP client and request builders for the EC
+//! identity lifecycle endpoints: partner registration, pixel sync,
+//! identify, and batch sync.
+//!
+//! Also provides a minimal origin server that satisfies organic route
+//! proxying so the trusted-server can generate and set EC cookies.
+
+use crate::common::runtime::{TestError, TestResult};
+use error_stack::{Report, ResultExt};
+use reqwest::blocking::{Client, Response};
+use serde_json::Value;
+use std::io::{Read, Write};
+use std::net::TcpListener;
+use std::sync::mpsc;
+use std::thread;
+use std::thread::JoinHandle;
+use std::time::Duration;
+
+// ---------------------------------------------------------------------------
+// Cookie-aware HTTP client
+// ---------------------------------------------------------------------------
+
+/// HTTP client that manually tracks the `ts-ec` cookie value.
+///
+/// Reqwest's built-in cookie jar respects domain matching, but the EC
+/// cookie is set with `Domain=.test-publisher.com` while tests run
+/// against `127.0.0.1`. This client extracts and replays the `ts-ec`
+/// cookie manually via the `Cookie` header.
+pub struct EcTestClient {
+    client: Client,
+    pub base_url: String,
+    /// The active `ts-ec` cookie value, updated after each response.
+    ec_cookie: std::cell::RefCell<Option<String>>,
+}
+
+impl EcTestClient {
+    /// Creates a new client. Redirects are disabled so tests can inspect
+    /// 302 responses from `/sync`.
+    pub fn new(base_url: &str) -> Self {
+        let client = Client::builder()
+            .redirect(reqwest::redirect::Policy::none())
+            .build()
+            .expect("should build reqwest client");
+
+        Self {
+            client,
+            base_url: base_url.to_owned(),
+            ec_cookie: std::cell::RefCell::new(None),
+        }
+    }
+
+    /// Updates the tracked EC cookie from a response's `Set-Cookie` headers.
+    fn track_ec_cookie(&self, resp: &Response) {
+        for value in resp.headers().get_all("set-cookie") {
+            if let Ok(cookie_str) = value.to_str() {
+                if cookie_str.starts_with("ts-ec=") {
+                    if cookie_str.contains("Max-Age=0") {
+                        // Cookie deletion
+                        *self.ec_cookie.borrow_mut() = None;
+                    } else if let Some(val) = cookie_str
+                        .split(';')
+                        .next()
+                        .and_then(|s| s.strip_prefix("ts-ec="))
+                    {
+                        if !val.is_empty() {
+                            *self.ec_cookie.borrow_mut() = Some(val.to_owned());
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    /// Builds a request with the tracked EC cookie attached.
+    fn attach_ec_cookie(
+        &self,
+        builder: reqwest::blocking::RequestBuilder,
+    ) -> reqwest::blocking::RequestBuilder {
+        if let Some(ref ec) = *self.ec_cookie.borrow() {
+            builder.header("cookie", format!("ts-ec={ec}"))
+        } else {
+            builder
+        }
+    }
+
+    /// `GET {base_url}{path}` with tracked EC cookie.
+    pub fn get(&self, path: &str) -> TestResult<Response> {
+        let builder = self.client.get(format!("{}{path}", self.base_url));
+        let resp = self
+            .attach_ec_cookie(builder)
+            .send()
+            .change_context(TestError::HttpRequest)
+            .attach(format!("GET {path}"))?;
+        self.track_ec_cookie(&resp);
+        Ok(resp)
+    }
+
+    /// `GET {base_url}{path}` with extra headers.
+    pub fn get_with_headers(&self, path: &str, headers: &[(&str, &str)]) -> TestResult<Response> {
+        let mut builder = self.client.get(format!("{}{path}", self.base_url));
+        for (key, value) in headers {
+            builder = builder.header(*key, *value);
+        }
+        let resp = self
+            .attach_ec_cookie(builder)
+            .send()
+            .change_context(TestError::HttpRequest)
+            .attach(format!("GET {path}"))?;
+        self.track_ec_cookie(&resp);
+        Ok(resp)
+    }
+
+    /// `POST {base_url}{path}` with JSON body.
+    pub fn post_json(&self, path: &str, body: &Value) -> TestResult<Response> {
+        let builder = self
+            .client
+            .post(format!("{}{path}", self.base_url))
+            .json(body);
+        let resp = self
+            .attach_ec_cookie(builder)
+            .send()
+            .change_context(TestError::HttpRequest)
+            .attach(format!("POST {path}"))?;
+        self.track_ec_cookie(&resp);
+        Ok(resp)
+    }
+
+    /// `POST {base_url}{path}` with JSON body and basic auth.
+    pub fn post_json_with_basic_auth(
+        &self,
+        path: &str,
+        body: &Value,
+        username: &str,
+        password: &str,
+    ) -> TestResult<Response> {
+        let builder = self
+            .client
+            .post(format!("{}{path}", self.base_url))
+            .basic_auth(username, Some(password))
+            .json(body);
+        let resp = self
+            .attach_ec_cookie(builder)
+            .send()
+            .change_context(TestError::HttpRequest)
+            .attach(format!("POST {path} (basic auth)"))?;
+        self.track_ec_cookie(&resp);
+        Ok(resp)
+    }
+
+    /// `POST {base_url}{path}` with JSON body and bearer token auth.
+    pub fn post_json_with_bearer(
+        &self,
+        path: &str,
+        body: &Value,
+        token: &str,
+    ) -> TestResult<Response> {
+        let builder = self
+            .client
+            .post(format!("{}{path}", self.base_url))
+            .bearer_auth(token)
+            .json(body);
+        let resp = self
+            .attach_ec_cookie(builder)
+            .send()
+            .change_context(TestError::HttpRequest)
+            .attach(format!("POST {path} (bearer auth)"))?;
+        self.track_ec_cookie(&resp);
+        Ok(resp)
+    }
+
+    /// Returns the currently tracked EC cookie value, if any.
+    #[allow(dead_code)]
+    pub fn ec_cookie_value(&self) -> Option<String> {
+        self.ec_cookie.borrow().clone()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Partner registration
+// ---------------------------------------------------------------------------
+
+/// Admin credentials matching `trusted-server.toml` `[[handlers]]` for `/admin`.
+const ADMIN_USER: &str = "admin";
+const ADMIN_PASS: &str = "changeme";
+
+/// Registers a test partner via `POST /admin/partners/register`.
+pub fn register_test_partner(
+    client: &EcTestClient,
+    partner_id: &str,
+    api_key: &str,
+    return_domain: &str,
+) -> TestResult<()> {
+    let body = serde_json::json!({
+        "id": partner_id,
+        "name": format!("Test Partner {partner_id}"),
+        "api_key": api_key,
+        "allowed_return_domains": [return_domain],
+        "source_domain": format!("{partner_id}.example.com"),
+        "bidstream_enabled": true,
+    });
+
+    let resp = client.post_json_with_basic_auth(
+        "/admin/partners/register",
+        &body,
+        ADMIN_USER,
+        ADMIN_PASS,
+    )?;
+
+    let status = resp.status().as_u16();
+    if !resp.status().is_success() {
+        let body_text = resp.text().unwrap_or_default();
+        return Err(Report::new(TestError::PartnerRegistrationFailed)
+            .attach(format!("Expected 2xx, got {status}; body: {body_text}")));
+    }
+
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Pixel sync
+// ---------------------------------------------------------------------------
+
+/// Calls `GET /sync` with the required query parameters.
+///
+/// Returns the raw response (typically a 302 redirect).
+pub fn pixel_sync(
+    client: &EcTestClient,
+    partner: &str,
+    uid: &str,
+    return_url: &str,
+) -> TestResult<Response> {
+    let path = format!(
+        "/sync?partner={partner}&uid={uid}&return={}",
+        urlencoding::encode(return_url)
+    );
+    client.get(&path)
+}
+
+// ---------------------------------------------------------------------------
+// Identify
+// ---------------------------------------------------------------------------
+
+/// Calls `GET /identify` and returns the raw response.
+pub fn identify(client: &EcTestClient) -> TestResult<Response> {
+    client.get("/identify")
+}
+
+// ---------------------------------------------------------------------------
+// Batch sync
+// ---------------------------------------------------------------------------
+
+/// Calls `POST /api/v1/sync` with bearer auth and the given mappings.
+pub fn batch_sync(
+    client: &EcTestClient,
+    api_key: &str,
+    mappings: &[BatchMapping],
+) -> TestResult<Response> {
+    let body = serde_json::json!({ "mappings": mappings_to_json(mappings) });
+    client.post_json_with_bearer("/api/v1/sync", &body, api_key)
+}
+
+/// Calls `POST /api/v1/sync` without any auth header.
+pub fn batch_sync_no_auth(
+    client: &EcTestClient,
+    mappings: &[BatchMapping],
+) -> TestResult<Response> {
+    let body = serde_json::json!({ "mappings": mappings_to_json(mappings) });
+    client.post_json("/api/v1/sync", &body)
+}
+
+/// Single mapping in a batch sync request.
+pub struct BatchMapping {
+    pub ssc_hash: String,
+    pub partner_uid: String,
+    pub timestamp: u64,
+}
+
+fn mappings_to_json(mappings: &[BatchMapping]) -> Vec<Value> {
+    mappings
+        .iter()
+        .map(|m| {
+            serde_json::json!({
+                "ssc_hash": m.ssc_hash,
+                "partner_uid": m.partner_uid,
+                "timestamp": m.timestamp,
+            })
+        })
+        .collect()
+}
+
+// ---------------------------------------------------------------------------
+// Assertion helpers
+// ---------------------------------------------------------------------------
+
+/// Asserts the response has a specific HTTP status code.
+pub fn assert_status(resp: &Response, expected: u16) -> TestResult<()> {
+    let actual = resp.status().as_u16();
+    if actual != expected {
+        return Err(Report::new(TestError::UnexpectedStatusCode {
+            expected,
+            actual,
+        }));
+    }
+    Ok(())
+}
+
+/// Asserts the response status and returns the parsed JSON body.
+pub fn assert_json_response(resp: Response, expected_status: u16) -> TestResult<Value> {
+    let actual = resp.status().as_u16();
+    if actual != expected_status {
+        let body_text = resp.text().unwrap_or_default();
+        return Err(Report::new(TestError::UnexpectedStatusCode {
+            expected: expected_status,
+            actual,
+        })
+        .attach(format!("body: {body_text}")));
+    }
+
+    let body = resp
+        .text()
+        .change_context(TestError::ResponseParse)
+        .attach("failed to read response body")?;
+
+    serde_json::from_str(&body)
+        .change_context(TestError::ResponseParse)
+        .attach(format!("invalid JSON: {body}"))
+}
+
+/// Extracts the `ts-ec` cookie value from a `Set-Cookie` response header.
+///
+/// Returns `None` if no `ts-ec` cookie was set.
+pub fn extract_ec_cookie_from_response(resp: &Response) -> Option<String> {
+    for value in resp.headers().get_all("set-cookie") {
+        let cookie_str = value.to_str().ok()?;
+        if cookie_str.starts_with("ts-ec=") {
+            let value = cookie_str
+                .split(';')
+                .next()?
+                .strip_prefix("ts-ec=")?
+                .to_owned();
+            if !value.is_empty() {
+                return Some(value);
+            }
+        }
+    }
+    None
+}
+
+/// Checks whether the response expires (deletes) the `ts-ec` cookie.
+pub fn is_ec_cookie_expired(resp: &Response) -> bool {
+    for value in resp.headers().get_all("set-cookie") {
+        if let Ok(cookie_str) = value.to_str() {
+            if cookie_str.starts_with("ts-ec=") && cookie_str.contains("Max-Age=0") {
+                return true;
+            }
+        }
+    }
+    false
+}
+
+/// Extracts the stable 64-char hex prefix from an EC ID (`{64hex}.{6alnum}`).
+pub fn ec_hash(ec_id: &str) -> &str {
+    match ec_id.find('.') {
+        Some(pos) => &ec_id[..pos],
+        None => ec_id,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Minimal origin server
+// ---------------------------------------------------------------------------
+
+/// A minimal HTTP origin server that returns `200 OK` with a simple HTML body
+/// for any request. Required for organic route proxying — without a running
+/// origin, the trusted-server returns an error and never sets the EC cookie.
+///
+/// Runs on the given port in a background thread. Dropped when the handle
+/// goes out of scope via explicit shutdown + thread join.
+pub struct MinimalOrigin {
+    shutdown_tx: mpsc::Sender<()>,
+    handle: Option<JoinHandle<()>>,
+}
+
+impl MinimalOrigin {
+    /// Starts a minimal origin server on `127.0.0.1:{port}`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the port is already in use.
+    pub fn start(port: u16) -> Self {
+        let listener =
+            TcpListener::bind(format!("127.0.0.1:{port}")).expect("should bind origin port");
+        listener
+            .set_nonblocking(true)
+            .expect("should set listener nonblocking");
+        let (shutdown_tx, shutdown_rx) = mpsc::channel::<()>();
+
+        let handle = thread::spawn(move || {
+            loop {
+                if shutdown_rx.try_recv().is_ok() {
+                    break;
+                }
+
+                match listener.accept() {
+                    Ok((mut stream, _addr)) => {
+                        // Read one chunk to consume the request line/headers.
+                        let mut buf = [0u8; 4096];
+                        let _ = stream.read(&mut buf);
+
+                        let body = "<html><body><h1>Test Origin</h1></body></html>";
+                        let response = format!(
+                            "HTTP/1.1 200 OK\r\n\
+                             Content-Type: text/html\r\n\
+                             Content-Length: {}\r\n\
+                             Connection: close\r\n\
+                             \r\n\
+                             {body}",
+                            body.len()
+                        );
+                        let _ = stream.write_all(response.as_bytes());
+                        let _ = stream.flush();
+                    }
+                    Err(err) if err.kind() == std::io::ErrorKind::WouldBlock => {
+                        thread::sleep(Duration::from_millis(10));
+                    }
+                    Err(_) => break,
+                }
+            }
+        });
+
+        Self {
+            shutdown_tx,
+            handle: Some(handle),
+        }
+    }
+}
+
+impl Drop for MinimalOrigin {
+    fn drop(&mut self) {
+        let _ = self.shutdown_tx.send(());
+        if let Some(handle) = self.handle.take() {
+            let _ = handle.join();
+        }
+    }
+}
diff --git a/crates/integration-tests/tests/common/mod.rs b/crates/integration-tests/tests/common/mod.rs
index 61fb404e..9dba15c4 100644
--- a/crates/integration-tests/tests/common/mod.rs
+++ b/crates/integration-tests/tests/common/mod.rs
@@ -1,2 +1,3 @@
 pub mod assertions;
+pub mod ec;
 pub mod runtime;
diff --git a/crates/integration-tests/tests/common/runtime.rs b/crates/integration-tests/tests/common/runtime.rs
index bf8b795a..95bc6c14 100644
--- a/crates/integration-tests/tests/common/runtime.rs
+++ b/crates/integration-tests/tests/common/runtime.rs
@@ -45,6 +45,19 @@ pub enum TestError {
     #[display("Origin URL not rewritten in HTML attributes")]
     AttributeNotRewritten,
 
+    // EC lifecycle errors
+    #[display("EC cookie was not set on the response")]
+    EcCookieNotSet,
+
+    #[display("Expected HTTP status {expected}, got {actual}")]
+    UnexpectedStatusCode { expected: u16, actual: u16 },
+
+    #[display("Partner registration failed")]
+    PartnerRegistrationFailed,
+
+    #[display("JSON field assertion failed: {field}")]
+    JsonFieldMismatch { field: String },
+
     // Resource errors
     #[display("No available port found")]
     NoPortAvailable,
diff --git a/crates/integration-tests/tests/frameworks/scenarios.rs b/crates/integration-tests/tests/frameworks/scenarios.rs
index 09268a4e..9990e2d9 100644
--- a/crates/integration-tests/tests/frameworks/scenarios.rs
+++ b/crates/integration-tests/tests/frameworks/scenarios.rs
@@ -1,5 +1,10 @@
 use crate::common::assertions;
-use crate::common::runtime::{TestError, TestResult, origin_port};
+use crate::common::ec::{
+    assert_json_response, assert_status, batch_sync, batch_sync_no_auth, ec_hash,
+    extract_ec_cookie_from_response, identify, is_ec_cookie_expired, pixel_sync,
+    register_test_partner, BatchMapping, EcTestClient,
+};
+use crate::common::runtime::{origin_port, TestError, TestResult};
 use error_stack::Report;
 use error_stack::ResultExt as _;
 
@@ -422,3 +427,345 @@ impl CustomScenario {
         }
     }
 }
+
+// ---------------------------------------------------------------------------
+// EC identity lifecycle scenarios
+// ---------------------------------------------------------------------------
+
+/// EC identity lifecycle scenarios that test KV-backed stateful behavior.
+///
+/// These run against the Viceroy runtime directly without a frontend
+/// framework container — they exercise EC-specific endpoints (`/sync`,
+/// `/identify`, `/api/v1/sync`, `/admin/partners/register`).
+#[derive(Debug, Clone)]
+pub enum EcScenario {
+    /// Full flow: organic request generates EC → pixel sync writes partner
+    /// UID → identify returns UID.
+    FullLifecycle,
+
+    /// Consent withdrawal: GPC header triggers EC cookie deletion.
+    ConsentWithdrawal,
+
+    /// Identify without EC cookie returns 204.
+    IdentifyWithoutEc,
+
+    /// Identify with consent denied returns 403.
+    IdentifyConsentDenied,
+
+    /// Two pixel syncs with different partners → identify returns both UIDs.
+    ConcurrentPartnerSyncs,
+
+    /// Batch sync happy path: authenticated request writes UID.
+    BatchSyncHappyPath,
+
+    /// Batch sync auth rejection: no auth → 401, wrong auth → 401.
+    BatchSyncAuthRejection,
+}
+
+impl EcScenario {
+    /// All EC scenarios in order.
+    pub fn all() -> Vec<Self> {
+        vec![
+            Self::FullLifecycle,
+            Self::ConsentWithdrawal,
+            Self::IdentifyWithoutEc,
+            Self::IdentifyConsentDenied,
+            Self::ConcurrentPartnerSyncs,
+            Self::BatchSyncHappyPath,
+            Self::BatchSyncAuthRejection,
+        ]
+    }
+
+    /// Execute this EC scenario against a running Viceroy instance.
+    ///
+    /// Each scenario creates its own `EcTestClient` to isolate cookie state.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TestError`] on assertion failures.
+    pub fn run(&self, base_url: &str) -> TestResult<()> {
+        match self {
+            Self::FullLifecycle => ec_full_lifecycle(base_url),
+            Self::ConsentWithdrawal => ec_consent_withdrawal(base_url),
+            Self::IdentifyWithoutEc => ec_identify_without_ec(base_url),
+            Self::IdentifyConsentDenied => ec_identify_consent_denied(base_url),
+            Self::ConcurrentPartnerSyncs => ec_concurrent_partner_syncs(base_url),
+            Self::BatchSyncHappyPath => ec_batch_sync_happy_path(base_url),
+            Self::BatchSyncAuthRejection => ec_batch_sync_auth_rejection(base_url),
+        }
+    }
+}
+
+/// Full lifecycle: page load → EC → pixel sync → identify with UID.
+fn ec_full_lifecycle(base_url: &str) -> TestResult<()> {
+    let client = EcTestClient::new(base_url);
+
+    // 1. Organic request generates EC cookie
+    let resp = client.get("/")?;
+    let ec_id = extract_ec_cookie_from_response(&resp).ok_or_else(|| {
+        Report::new(TestError::EcCookieNotSet).attach("organic GET / should set ts-ec cookie")
+    })?;
+    log::info!("EC full lifecycle: generated EC ID = {ec_id}");
+
+    // 2. Register a test partner
+    register_test_partner(&client, "inttest", "inttest-api-key-1", "sync.example.com")
+        .attach("EC full lifecycle: partner registration")?;
+
+    // 3. Pixel sync writes partner UID
+    let return_url = "https://sync.example.com/done?ok=1";
+    let resp = pixel_sync(&client, "inttest", "user-uid-42", return_url)?;
+
+    let status = resp.status().as_u16();
+    if status != 302 {
+        let body = resp.text().unwrap_or_default();
+        return Err(Report::new(TestError::UnexpectedStatusCode {
+            expected: 302,
+            actual: status,
+        })
+        .attach(format!("pixel sync should redirect; body: {body}")));
+    }
+
+    // 4. Identify should return the synced UID
+    let json = assert_json_response(identify(&client)?, 200)
+        .attach("EC full lifecycle: identify after pixel sync")?;
+
+    let uids = json
+        .get("uids")
+        .and_then(|v| v.as_object())
+        .ok_or_else(|| {
+            Report::new(TestError::JsonFieldMismatch {
+                field: "uids".to_owned(),
+            })
+            .attach(format!("identify body: {json}"))
+        })?;
+
+    let uid_value = uids.get("inttest").and_then(|v| v.as_str());
+    if uid_value != Some("user-uid-42") {
+        return Err(Report::new(TestError::JsonFieldMismatch {
+            field: "uids.inttest".to_owned(),
+        })
+        .attach(format!(
+            "expected uid 'user-uid-42', got {:?}; body: {json}",
+            uid_value
+        )));
+    }
+
+    log::info!("EC full lifecycle: PASSED");
+    Ok(())
+}
+
+/// Consent withdrawal: GPC header clears EC cookie.
+fn ec_consent_withdrawal(base_url: &str) -> TestResult<()> {
+    let client = EcTestClient::new(base_url);
+
+    // 1. Generate EC (no consent headers → non-regulated → EC allowed)
+    let resp = client.get("/")?;
+    let ec_id = extract_ec_cookie_from_response(&resp).ok_or_else(|| {
+        Report::new(TestError::EcCookieNotSet).attach("should set ts-ec on first organic request")
+    })?;
+    log::info!("EC consent withdrawal: generated EC = {ec_id}");
+
+    // 2. Second request with GPC=1 should revoke consent and expire the EC
+    // cookie. This endpoint was selected because step #1 proved EC was
+    // allowed for this client in the active runtime config.
+    let resp = client.get_with_headers("/", &[("sec-gpc", "1")])?;
+
+    if !is_ec_cookie_expired(&resp) {
+        return Err(Report::new(TestError::JsonFieldMismatch {
+            field: "set-cookie(ts-ec expired)".to_owned(),
+        })
+        .attach("consent withdrawal should expire ts-ec cookie"));
+    }
+
+    // 3. With cookie revoked and no GPC header on identify, server should
+    // report no EC present.
+    let resp = identify(&client)?;
+    assert_status(&resp, 204).attach("identify should return 204 after cookie revocation")?;
+
+    // 4. With GPC still asserted, identify should reflect consent denial.
+    let resp = client.get_with_headers("/identify", &[("sec-gpc", "1")])?;
+    assert_status(&resp, 403)
+        .attach("identify with GPC should return 403 after consent withdrawal")?;
+
+    log::info!("EC consent withdrawal: PASSED");
+    Ok(())
+}
+
+/// Identify without EC cookie returns 204 No Content.
+fn ec_identify_without_ec(base_url: &str) -> TestResult<()> {
+    let client = EcTestClient::new(base_url);
+
+    let resp = identify(&client)?;
+    assert_status(&resp, 204).attach("identify without EC cookie should return 204")?;
+
+    log::info!("EC identify without EC: PASSED");
+    Ok(())
+}
+
+/// Identify with consent denied returns 403.
+fn ec_identify_consent_denied(base_url: &str) -> TestResult<()> {
+    let client = EcTestClient::new(base_url);
+
+    // Generate EC first (non-regulated → allowed)
+    let resp = client.get("/")?;
+    let _ec_id = extract_ec_cookie_from_response(&resp).ok_or_else(|| {
+        Report::new(TestError::EcCookieNotSet)
+            .attach("should set ts-ec on organic request for consent-denied test")
+    })?;
+
+    // Identify with GPC=1 — if jurisdiction is non-regulated + GPC,
+    // consent may still be denied depending on US-state detection.
+    // Without geo, jurisdiction is Unknown → fail-closed → 403.
+    let resp = client.get_with_headers("/identify", &[("sec-gpc", "1")])?;
+
+    let status = resp.status().as_u16();
+    // Under Unknown jurisdiction (no geo in Viceroy), EC is denied
+    // so the response may be 403 or 204 depending on whether the EC
+    // context reads the cookie before consent check.
+    if status != 403 && status != 204 {
+        return Err(Report::new(TestError::UnexpectedStatusCode {
+            expected: 403,
+            actual: status,
+        })
+        .attach("identify with consent denied should return 403 or 204"));
+    }
+
+    log::info!("EC identify consent denied: PASSED (status={status})");
+    Ok(())
+}
+
+/// Two pixel syncs with different partners → identify returns both UIDs.
+fn ec_concurrent_partner_syncs(base_url: &str) -> TestResult<()> {
+    let client = EcTestClient::new(base_url);
+
+    // Generate EC
+    let resp = client.get("/")?;
+    let ec_id = extract_ec_cookie_from_response(&resp).ok_or_else(|| {
+        Report::new(TestError::EcCookieNotSet).attach("concurrent syncs: need EC cookie")
+    })?;
+    log::info!("EC concurrent syncs: EC = {ec_id}");
+
+    // Register two partners
+    register_test_partner(&client, "sspa", "key-sspa", "sync.example.com")
+        .attach("register partner sspa")?;
+    register_test_partner(&client, "sspb", "key-sspb", "sync.example.com")
+        .attach("register partner sspb")?;
+
+    // Pixel sync both
+    let return_url = "https://sync.example.com/done";
+    let resp = pixel_sync(&client, "sspa", "uid-a", return_url)?;
+    assert_status(&resp, 302).attach("pixel sync sspa should redirect")?;
+
+    let resp = pixel_sync(&client, "sspb", "uid-b", return_url)?;
+    assert_status(&resp, 302).attach("pixel sync sspb should redirect")?;
+
+    // Identify should contain both
+    let json =
+        assert_json_response(identify(&client)?, 200).attach("identify after dual pixel sync")?;
+
+    let uids = json
+        .get("uids")
+        .and_then(|v| v.as_object())
+        .ok_or_else(|| {
+            Report::new(TestError::JsonFieldMismatch {
+                field: "uids".to_owned(),
+            })
+            .attach(format!("body: {json}"))
+        })?;
+
+    for (partner, expected_uid) in [("sspa", "uid-a"), ("sspb", "uid-b")] {
+        let actual = uids.get(partner).and_then(|v| v.as_str());
+        if actual != Some(expected_uid) {
+            return Err(Report::new(TestError::JsonFieldMismatch {
+                field: format!("uids.{partner}"),
+            })
+            .attach(format!(
+                "expected '{expected_uid}', got {:?}; body: {json}",
+                actual
+            )));
+        }
+    }
+
+    log::info!("EC concurrent partner syncs: PASSED");
+    Ok(())
+}
+
+/// Batch sync happy path: authenticated request writes UID, verify via identify.
+fn ec_batch_sync_happy_path(base_url: &str) -> TestResult<()> {
+    let client = EcTestClient::new(base_url);
+
+    // Generate EC to get a valid hash
+    let resp = client.get("/")?;
+    let ec_id = extract_ec_cookie_from_response(&resp).ok_or_else(|| {
+        Report::new(TestError::EcCookieNotSet).attach("batch sync: need EC cookie")
+    })?;
+    let hash = ec_hash(&ec_id).to_owned();
+    log::info!("EC batch sync happy path: hash = {hash}");
+
+    // Register partner with known API key
+    register_test_partner(&client, "batchssp", "batch-api-key-1", "sync.example.com")
+        .attach("register batch sync partner")?;
+
+    // Batch sync writes a UID for this hash
+    let mappings = vec![BatchMapping {
+        ssc_hash: hash.clone(),
+        partner_uid: "batch-uid-99".to_owned(),
+        timestamp: 1_700_000_000,
+    }];
+    let resp = batch_sync(&client, "batch-api-key-1", &mappings)?;
+    let json = assert_json_response(resp, 200).attach("batch sync should return 200")?;
+
+    let accepted = json.get("accepted").and_then(|v| v.as_u64());
+    if accepted != Some(1) {
+        return Err(Report::new(TestError::JsonFieldMismatch {
+            field: "accepted".to_owned(),
+        })
+        .attach(format!(
+            "expected accepted=1, got {:?}; body: {json}",
+            accepted
+        )));
+    }
+
+    // Verify via identify
+    let json = assert_json_response(identify(&client)?, 200).attach("identify after batch sync")?;
+
+    let uid = json
+        .get("uids")
+        .and_then(|v| v.get("batchssp"))
+        .and_then(|v| v.as_str());
+
+    if uid != Some("batch-uid-99") {
+        return Err(Report::new(TestError::JsonFieldMismatch {
+            field: "uids.batchssp".to_owned(),
+        })
+        .attach(format!(
+            "expected 'batch-uid-99', got {:?}; body: {json}",
+            uid
+        )));
+    }
+
+    log::info!("EC batch sync happy path: PASSED");
+    Ok(())
+}
+
+/// Batch sync auth rejection: no auth → 401, wrong auth → 401.
+fn ec_batch_sync_auth_rejection(base_url: &str) -> TestResult<()> {
+    let client = EcTestClient::new(base_url);
+
+    let dummy_mappings = vec![BatchMapping {
+        ssc_hash: "a".repeat(64),
+        partner_uid: "uid-1".to_owned(),
+        timestamp: 1_700_000_000,
+    }];
+
+    // No auth header
+    let resp = batch_sync_no_auth(&client, &dummy_mappings)?;
+    assert_status(&resp, 401).attach("batch sync without auth should return 401")?;
+
+    // Wrong bearer token
+    let resp = batch_sync(&client, "completely-wrong-key", &dummy_mappings)?;
+    assert_status(&resp, 401).attach("batch sync with wrong auth should return 401")?;
+
+    log::info!("EC batch sync auth rejection: PASSED");
+    Ok(())
+}
diff --git a/crates/integration-tests/tests/integration.rs b/crates/integration-tests/tests/integration.rs
index e52d0944..84d6d1ad 100644
--- a/crates/integration-tests/tests/integration.rs
+++ b/crates/integration-tests/tests/integration.rs
@@ -2,9 +2,10 @@ mod common;
 mod environments;
 mod frameworks;
 
-use common::runtime::{TestError, origin_port, wasm_binary_path};
+use common::runtime::{RuntimeEnvironment, TestError, origin_port, wasm_binary_path};
 use environments::{RUNTIME_ENVIRONMENTS, ReadyCheckOptions, wait_for_http_ready};
 use error_stack::ResultExt as _;
+use frameworks::scenarios::EcScenario;
 use frameworks::{FRAMEWORKS, FrontendFramework};
 use std::time::Duration;
 use testcontainers::runners::SyncRunner as _;
@@ -134,3 +135,39 @@ fn test_nextjs_fastly() {
     let framework = frameworks::nextjs::NextJs;
     test_combination(&runtime, &framework).expect("should pass Next.js on Fastly");
 }
+
+// ---------------------------------------------------------------------------
+// EC identity lifecycle tests (no frontend framework container needed)
+// ---------------------------------------------------------------------------
+
+/// Runs all EC lifecycle scenarios against a standalone Viceroy instance.
+///
+/// Unlike framework tests, these use a minimal TCP origin server instead
+/// of a Docker container — organic routes need *something* to proxy to
+/// so the trusted-server can generate and set EC cookies.
+#[test]
+#[ignore = "requires Viceroy and pre-built WASM binary"]
+fn test_ec_lifecycle_fastly() {
+    init_logger();
+    let port = origin_port();
+
+    // Start a minimal origin server so organic route proxying succeeds.
+    let _origin = common::ec::MinimalOrigin::start(port);
+    log::info!("EC lifecycle tests: minimal origin running on port {port}");
+
+    let runtime = environments::fastly::FastlyViceroy;
+    let wasm_path = wasm_binary_path();
+
+    let process = runtime
+        .spawn(&wasm_path)
+        .expect("should spawn Viceroy for EC tests");
+
+    log::info!("EC lifecycle tests: Viceroy running at {}", process.base_url);
+
+    for scenario in EcScenario::all() {
+        log::info!("  Running EC scenario: {scenario:?}");
+        scenario
+            .run(&process.base_url)
+            .unwrap_or_else(|e| panic!("EC scenario {scenario:?} failed: {e:?}"));
+    }
+}
diff --git a/scripts/integration-tests-browser.sh b/scripts/integration-tests-browser.sh
index 888adb13..fb1289d3 100755
--- a/scripts/integration-tests-browser.sh
+++ b/scripts/integration-tests-browser.sh
@@ -32,7 +32,7 @@ echo "==> Validating shared integration-test dependency versions..."
 echo "==> Building WASM binary (origin=http://127.0.0.1:$ORIGIN_PORT)..."
 TRUSTED_SERVER__PUBLISHER__ORIGIN_URL="http://127.0.0.1:$ORIGIN_PORT" \
 TRUSTED_SERVER__PUBLISHER__PROXY_SECRET="integration-test-proxy-secret" \
-TRUSTED_SERVER__EDGE_COOKIE__SECRET_KEY="integration-test-secret-key" \
+TRUSTED_SERVER__EC__PASSPHRASE="integration-test-ec-secret" \
 TRUSTED_SERVER__PROXY__CERTIFICATE_CHECK=false \
     cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
 
diff --git a/scripts/integration-tests.sh b/scripts/integration-tests.sh
index 3b9ec974..318b9323 100755
--- a/scripts/integration-tests.sh
+++ b/scripts/integration-tests.sh
@@ -53,7 +53,7 @@ fi
 echo "==> Building WASM binary (origin=http://127.0.0.1:$ORIGIN_PORT)..."
 TRUSTED_SERVER__PUBLISHER__ORIGIN_URL="http://127.0.0.1:$ORIGIN_PORT" \
 TRUSTED_SERVER__PUBLISHER__PROXY_SECRET="integration-test-proxy-secret" \
-TRUSTED_SERVER__EDGE_COOKIE__SECRET_KEY="integration-test-secret-key" \
+TRUSTED_SERVER__EC__PASSPHRASE="integration-test-ec-secret" \
 TRUSTED_SERVER__PROXY__CERTIFICATE_CHECK=false \
     cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
 

From 5dc8079da916ba72772eaa410dd29e59423f796c Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Thu, 26 Mar 2026 12:26:05 -0500
Subject: [PATCH 12/36] Deduplicate EC helpers, fix error variants, and improve
 documentation

Consolidate is_valid_ec_hash and current_timestamp into single canonical
definitions to eliminate copy-paste drift across the ec/ module tree. Fix
serialization error variants in admin and batch_sync to use Ec instead of
Configuration. Add scaling and design-decision documentation for partner
store enumeration, rate limiter burstiness, and plaintext pull token storage.
Use test constructors consistently in identify and finalize tests.
---
 crates/trusted-server-core/src/ec/admin.rs    |  8 ++--
 .../trusted-server-core/src/ec/batch_sync.rs  | 40 ++++---------------
 crates/trusted-server-core/src/ec/finalize.rs | 24 +++--------
 .../trusted-server-core/src/ec/generation.rs  | 39 ++++++++++++++++++
 crates/trusted-server-core/src/ec/identify.rs | 19 +++------
 crates/trusted-server-core/src/ec/kv.rs       | 11 +----
 crates/trusted-server-core/src/ec/mod.rs      | 29 +++++++++++++-
 crates/trusted-server-core/src/ec/partner.rs  | 19 +++++++++
 .../trusted-server-core/src/ec/sync_pixel.rs  | 12 ++----
 9 files changed, 112 insertions(+), 89 deletions(-)

diff --git a/crates/trusted-server-core/src/ec/admin.rs b/crates/trusted-server-core/src/ec/admin.rs
index db32a3cf..64e4ac39 100644
--- a/crates/trusted-server-core/src/ec/admin.rs
+++ b/crates/trusted-server-core/src/ec/admin.rs
@@ -236,11 +236,9 @@ pub fn handle_register_partner(
         created,
     };
 
-    let body = serde_json::to_string(&response_body).change_context(
-        TrustedServerError::Configuration {
-            message: "Failed to serialize registration response".to_owned(),
-        },
-    )?;
+    let body = serde_json::to_string(&response_body).change_context(TrustedServerError::Ec {
+        message: "Failed to serialize registration response".to_owned(),
+    })?;
 
     Ok(Response::from_status(status)
         .with_content_type(fastly::mime::APPLICATION_JSON)
diff --git a/crates/trusted-server-core/src/ec/batch_sync.rs b/crates/trusted-server-core/src/ec/batch_sync.rs
index 9b1aab14..5a5bc559 100644
--- a/crates/trusted-server-core/src/ec/batch_sync.rs
+++ b/crates/trusted-server-core/src/ec/batch_sync.rs
@@ -13,6 +13,7 @@ use serde::{Deserialize, Serialize};
 
 use crate::error::TrustedServerError;
 
+use super::generation::is_valid_ec_hash;
 use super::kv::{KvIdentityGraph, UpsertResult};
 use super::partner::{hash_api_key, PartnerRecord, PartnerStore};
 use super::sync_pixel::RateLimiter;
@@ -26,11 +27,6 @@ const REASON_KV_UNAVAILABLE: &str = "kv_unavailable";
 /// Maximum number of mappings allowed in a single batch request.
 const MAX_BATCH_SIZE: usize = 1000;
 
-/// Regex-free validation: 64 lowercase hex characters.
-fn is_valid_ssc_hash(s: &str) -> bool {
-    s.len() == 64 && s.bytes().all(|b| b.is_ascii_hexdigit())
-}
-
 trait BatchSyncWriter {
     fn upsert_partner_id_if_exists(
         &self,
@@ -199,7 +195,7 @@ fn process_mappings(
     let mut errors = Vec::new();
 
     for (idx, mapping) in mappings.iter().enumerate() {
-        if !is_valid_ssc_hash(&mapping.ssc_hash) {
+        if !is_valid_ec_hash(&mapping.ssc_hash) {
             errors.push(MappingError {
                 index: idx,
                 reason: REASON_INVALID_EC_HASH,
@@ -266,7 +262,7 @@ fn json_response<T: serde::Serialize>(
     status: StatusCode,
     body: &T,
 ) -> Result<Response, Report<TrustedServerError>> {
-    let body = serde_json::to_string(body).change_context(TrustedServerError::Configuration {
+    let body = serde_json::to_string(body).change_context(TrustedServerError::Ec {
         message: "Failed to serialize batch sync response".to_owned(),
     })?;
 
@@ -289,32 +285,12 @@ mod tests {
 
     use crate::error::TrustedServerError;
 
+    // Hash validation tests are in generation.rs (is_valid_ec_hash).
+    // Verify the import works here with a basic smoke test.
     #[test]
-    fn is_valid_ssc_hash_accepts_64_hex_chars() {
-        assert!(is_valid_ssc_hash(&"a".repeat(64)));
-        assert!(is_valid_ssc_hash(&"0123456789abcdef".repeat(4)));
-    }
-
-    #[test]
-    fn is_valid_ssc_hash_rejects_wrong_length() {
-        assert!(!is_valid_ssc_hash(&"a".repeat(63)));
-        assert!(!is_valid_ssc_hash(&"a".repeat(65)));
-        assert!(!is_valid_ssc_hash(""));
-    }
-
-    #[test]
-    fn is_valid_ssc_hash_rejects_non_hex() {
-        let mut hash = "a".repeat(64);
-        hash.replace_range(0..1, "g");
-        assert!(!is_valid_ssc_hash(&hash));
-    }
-
-    #[test]
-    fn is_valid_ssc_hash_accepts_uppercase_hex() {
-        assert!(
-            is_valid_ssc_hash(&"A".repeat(64)),
-            "should accept uppercase hex (normalized to lowercase before KV lookup)"
-        );
+    fn is_valid_ec_hash_smoke_test() {
+        assert!(is_valid_ec_hash(&"a".repeat(64)));
+        assert!(!is_valid_ec_hash(&"a".repeat(63)));
     }
 
     #[test]
diff --git a/crates/trusted-server-core/src/ec/finalize.rs b/crates/trusted-server-core/src/ec/finalize.rs
index 1c2bf71d..94fe6b14 100644
--- a/crates/trusted-server-core/src/ec/finalize.rs
+++ b/crates/trusted-server-core/src/ec/finalize.rs
@@ -14,7 +14,8 @@ use crate::geo::GeoInfo;
 use crate::settings::Settings;
 
 use super::cookies::{expire_ec_cookie, set_ec_cookie};
-use super::generation::{ec_hash, is_valid_ec_id};
+use super::current_timestamp;
+use super::generation::{ec_hash, is_valid_ec_hash, is_valid_ec_id};
 use super::kv::KvIdentityGraph;
 use super::EcContext;
 
@@ -130,17 +131,6 @@ fn withdrawal_ec_ids(ec_context: &EcContext) -> HashSet<String> {
     hashes
 }
 
-fn is_valid_ec_hash(value: &str) -> bool {
-    value.len() == 64 && value.bytes().all(|b| b.is_ascii_hexdigit())
-}
-
-fn current_timestamp() -> u64 {
-    std::time::SystemTime::now()
-        .duration_since(std::time::UNIX_EPOCH)
-        .map(|d| d.as_secs())
-        .unwrap_or(0)
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -161,15 +151,13 @@ mod tests {
             ..Default::default()
         };
 
-        EcContext {
-            ec_value: ec_value.map(str::to_owned),
-            cookie_ec_value: cookie_ec_value.map(str::to_owned),
+        EcContext::new_for_test_with_cookie(
+            ec_value.map(str::to_owned),
+            cookie_ec_value.map(str::to_owned),
             ec_was_present,
             ec_generated,
             consent,
-            client_ip: None,
-            geo_info: None,
-        }
+        )
     }
 
     fn sample_ec_id(suffix: &str) -> String {
diff --git a/crates/trusted-server-core/src/ec/generation.rs b/crates/trusted-server-core/src/ec/generation.rs
index b54903ea..f3bafeeb 100644
--- a/crates/trusted-server-core/src/ec/generation.rs
+++ b/crates/trusted-server-core/src/ec/generation.rs
@@ -117,6 +117,17 @@ pub fn ec_hash(ec_id: &str) -> &str {
     }
 }
 
+/// Checks whether a string is a valid 64-character hex EC hash prefix.
+///
+/// Used by batch sync, finalize, and other modules that handle the
+/// `{64hex}` portion of an EC ID independently. Accepts both uppercase
+/// and lowercase hex; callers that require a specific case should
+/// normalize before comparison.
+#[must_use]
+pub fn is_valid_ec_hash(value: &str) -> bool {
+    value.len() == 64 && value.bytes().all(|b| b.is_ascii_hexdigit())
+}
+
 /// Checks whether a string matches the expected EC ID format.
 ///
 /// The format is `{64hex}.{6alnum}` where the first part is a 64-character
@@ -207,6 +218,34 @@ mod tests {
         assert_eq!(ec_hash("nodot"), "nodot");
     }
 
+    #[test]
+    fn is_valid_ec_hash_accepts_64_hex() {
+        assert!(is_valid_ec_hash(&"a".repeat(64)));
+        assert!(is_valid_ec_hash(&"0123456789abcdef".repeat(4)));
+    }
+
+    #[test]
+    fn is_valid_ec_hash_accepts_uppercase_hex() {
+        assert!(
+            is_valid_ec_hash(&"A".repeat(64)),
+            "should accept uppercase hex (callers normalize before KV lookup)"
+        );
+    }
+
+    #[test]
+    fn is_valid_ec_hash_rejects_wrong_length() {
+        assert!(!is_valid_ec_hash(&"a".repeat(63)));
+        assert!(!is_valid_ec_hash(&"a".repeat(65)));
+        assert!(!is_valid_ec_hash(""));
+    }
+
+    #[test]
+    fn is_valid_ec_hash_rejects_non_hex() {
+        let mut hash = "a".repeat(64);
+        hash.replace_range(0..1, "g");
+        assert!(!is_valid_ec_hash(&hash));
+    }
+
     #[test]
     fn is_valid_ec_id_accepts_valid() {
         let value = format!("{}.Ab12z9", "a".repeat(64));
diff --git a/crates/trusted-server-core/src/ec/identify.rs b/crates/trusted-server-core/src/ec/identify.rs
index 62f755e9..5226cd85 100644
--- a/crates/trusted-server-core/src/ec/identify.rs
+++ b/crates/trusted-server-core/src/ec/identify.rs
@@ -226,19 +226,12 @@ mod tests {
     use crate::test_support::tests::create_test_settings;
 
     fn make_ec_context(jurisdiction: Jurisdiction, ec_value: Option<&str>) -> EcContext {
-        EcContext {
-            ec_value: ec_value.map(str::to_owned),
-            cookie_ec_value: ec_value.map(str::to_owned),
-            ec_was_present: ec_value.is_some(),
-            ec_generated: false,
-            consent: ConsentContext {
-                jurisdiction,
-                source: ConsentSource::Cookie,
-                ..ConsentContext::default()
-            },
-            client_ip: None,
-            geo_info: None,
-        }
+        let consent = ConsentContext {
+            jurisdiction,
+            source: ConsentSource::Cookie,
+            ..ConsentContext::default()
+        };
+        EcContext::new_for_test(ec_value.map(str::to_owned), consent)
     }
 
     #[test]
diff --git a/crates/trusted-server-core/src/ec/kv.rs b/crates/trusted-server-core/src/ec/kv.rs
index 4c4c1bfb..fbcf77ef 100644
--- a/crates/trusted-server-core/src/ec/kv.rs
+++ b/crates/trusted-server-core/src/ec/kv.rs
@@ -14,6 +14,7 @@ use fastly::kv_store::{InsertMode, KVStore};
 
 use crate::error::TrustedServerError;
 
+use super::current_timestamp;
 use super::kv_types::{KvEntry, KvMetadata};
 
 /// Maximum number of CAS retry attempts before giving up.
@@ -645,16 +646,6 @@ impl KvIdentityGraph {
     }
 }
 
-/// Returns the current Unix timestamp in seconds.
-///
-/// Uses `std::time::SystemTime` which is supported on `wasm32-wasip1`.
-fn current_timestamp() -> u64 {
-    std::time::SystemTime::now()
-        .duration_since(std::time::UNIX_EPOCH)
-        .map(|d| d.as_secs())
-        .unwrap_or(0)
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index 4723379d..b137808f 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -54,7 +54,7 @@ use crate::settings::Settings;
 use self::kv::KvIdentityGraph;
 use self::kv_types::KvEntry;
 
-pub use generation::{ec_hash, generate_ec_id, is_valid_ec_id};
+pub use generation::{ec_hash, generate_ec_id, is_valid_ec_hash, is_valid_ec_id};
 
 /// Parsed EC identity from an incoming request.
 ///
@@ -383,9 +383,34 @@ impl EcContext {
             geo_info: None,
         }
     }
+
+    /// Creates a test-only [`EcContext`] with independent cookie and active EC
+    /// values. Use this to test cookie-mismatch and withdrawal scenarios.
+    #[cfg(test)]
+    #[must_use]
+    pub fn new_for_test_with_cookie(
+        ec_value: Option<String>,
+        cookie_ec_value: Option<String>,
+        ec_was_present: bool,
+        ec_generated: bool,
+        consent: ConsentContext,
+    ) -> Self {
+        Self {
+            ec_value,
+            cookie_ec_value,
+            ec_was_present,
+            ec_generated,
+            consent,
+            client_ip: None,
+            geo_info: None,
+        }
+    }
 }
 
-fn current_timestamp() -> u64 {
+/// Returns the current Unix timestamp in seconds.
+///
+/// Uses `std::time::SystemTime` which is supported on `wasm32-wasip1`.
+pub(crate) fn current_timestamp() -> u64 {
     std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
         .map(|d| d.as_secs())
diff --git a/crates/trusted-server-core/src/ec/partner.rs b/crates/trusted-server-core/src/ec/partner.rs
index b83e8e41..acc32517 100644
--- a/crates/trusted-server-core/src/ec/partner.rs
+++ b/crates/trusted-server-core/src/ec/partner.rs
@@ -70,6 +70,12 @@ pub struct PartnerRecord {
     /// `OpenRTB` `atype` value (typically 3).
     pub openrtb_atype: u8,
     /// Max pixel sync writes per EC hash per partner per hour.
+    ///
+    /// **Note:** Fastly rate counters only expose 60-second windows, so the
+    /// effective enforcement is `sync_rate_limit / 60` per minute. This can
+    /// create bursty behavior for low limits (e.g. a limit of 60 allows
+    /// 1 sync per 60 seconds, not a smooth 1/sec). See `FastlyRateLimiter`
+    /// in `sync_pixel.rs` for details.
     pub sync_rate_limit: u32,
     /// Max batch sync API requests per partner per minute.
     pub batch_rate_limit: u32,
@@ -86,6 +92,12 @@ pub struct PartnerRecord {
     /// Max pull sync calls per EC hash per partner per hour.
     pub pull_sync_rate_limit: u32,
     /// Outbound bearer token for pull sync requests.
+    ///
+    /// Stored in plaintext (unlike `api_key_hash`, which is SHA-256 hashed).
+    /// This is intentional: `ts_pull_token` is an *outbound* credential that
+    /// TS sends to the partner's pull sync endpoint, so it must be readable
+    /// at runtime. `api_key_hash` is an *inbound* credential that partners
+    /// send to us, so it only needs hash verification.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub ts_pull_token: Option<String>,
 }
@@ -255,6 +267,13 @@ impl PartnerStore {
     /// Scans the partner KV store and returns records for non-index keys.
     /// Secondary index entries (e.g. `apikey:*`) are skipped.
     ///
+    /// **Scaling note:** This performs O(N) KV reads where N is the number
+    /// of registered partners. Called by `dispatch_pull_sync` on every
+    /// organic request post-send. For large partner counts, consider
+    /// caching the result or maintaining a summary key. The
+    /// `pull_sync_concurrency` setting bounds downstream dispatch but
+    /// does not reduce the enumeration cost.
+    ///
     /// # Errors
     ///
     /// Returns [`TrustedServerError::KvStore`] on list, lookup, or
diff --git a/crates/trusted-server-core/src/ec/sync_pixel.rs b/crates/trusted-server-core/src/ec/sync_pixel.rs
index 103e7600..d054076c 100644
--- a/crates/trusted-server-core/src/ec/sync_pixel.rs
+++ b/crates/trusted-server-core/src/ec/sync_pixel.rs
@@ -25,7 +25,7 @@ pub const RATE_COUNTER_NAME: &str = "counter_store";
 /// Returns [`TrustedServerError`] when request validation fails (`400`) or
 /// required stores are unavailable (`503`).
 pub fn handle_sync(
-    _settings: &Settings,
+    _settings: &Settings, // reserved for future per-publisher sync config
     kv: &KvIdentityGraph,
     partner_store: &PartnerStore,
     req: &Request,
@@ -312,14 +312,8 @@ impl RateLimiter for FastlyRateLimiter {
     }
 }
 
-/// Returns the current Unix timestamp in seconds.
-#[must_use]
-pub fn current_timestamp() -> u64 {
-    std::time::SystemTime::now()
-        .duration_since(std::time::UNIX_EPOCH)
-        .map(|d| d.as_secs())
-        .unwrap_or(0)
-}
+// Re-export `current_timestamp` from parent module for sibling modules.
+pub(crate) use super::current_timestamp;
 
 #[cfg(test)]
 mod tests {

From da7782c8ffb2b938127495da0a0d7442419ff0de Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Thu, 26 Mar 2026 13:55:00 -0500
Subject: [PATCH 13/36] Fix 8 EC spec deviations identified in branch audit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rename ssc_hash → ec_hash in batch sync wire format (§9.3)
- Strip x-ts-* prefix headers in copy_custom_headers (§15)
- Strip dynamic x-ts-<partner_id> headers in clear_ec_on_response (§5.2)
- Add PartnerNotFound and PartnerAuthFailed error variants (§16)
- Rename Ec error variant → EdgeCookie (§16)
- Validate EC IDs at read time, discard malformed values (§4.2)
- Add rotating hourly offset for pull sync partner dispatch (§10.3)
- Add _pull_enabled secondary index for O(1+N) pull sync reads (§13.1)
---
 crates/integration-tests/tests/common/ec.rs   |   4 +-
 .../tests/frameworks/scenarios.rs             |   4 +-
 crates/trusted-server-core/src/ec/admin.rs    |   7 +-
 .../trusted-server-core/src/ec/batch_sync.rs  |  26 +--
 crates/trusted-server-core/src/ec/finalize.rs |  33 ++++
 .../trusted-server-core/src/ec/generation.rs  |   8 +-
 crates/trusted-server-core/src/ec/mod.rs      | 104 +++++++++---
 crates/trusted-server-core/src/ec/partner.rs  | 153 +++++++++++++++++-
 .../trusted-server-core/src/ec/pull_sync.rs   |  63 ++++++--
 .../trusted-server-core/src/ec/sync_pixel.rs  |   4 +-
 crates/trusted-server-core/src/error.rs       |  16 +-
 crates/trusted-server-core/src/http_util.rs   |  23 ++-
 .../src/integrations/registry.rs              |   6 +-
 crates/trusted-server-core/src/proxy.rs       |   5 +-
 crates/trusted-server-core/src/publisher.rs   |  10 +-
 15 files changed, 386 insertions(+), 80 deletions(-)

diff --git a/crates/integration-tests/tests/common/ec.rs b/crates/integration-tests/tests/common/ec.rs
index b918faff..1a002e56 100644
--- a/crates/integration-tests/tests/common/ec.rs
+++ b/crates/integration-tests/tests/common/ec.rs
@@ -272,7 +272,7 @@ pub fn batch_sync_no_auth(
 
 /// Single mapping in a batch sync request.
 pub struct BatchMapping {
-    pub ssc_hash: String,
+    pub ec_hash: String,
     pub partner_uid: String,
     pub timestamp: u64,
 }
@@ -282,7 +282,7 @@ fn mappings_to_json(mappings: &[BatchMapping]) -> Vec<Value> {
         .iter()
         .map(|m| {
             serde_json::json!({
-                "ssc_hash": m.ssc_hash,
+                "ec_hash": m.ec_hash,
                 "partner_uid": m.partner_uid,
                 "timestamp": m.timestamp,
             })
diff --git a/crates/integration-tests/tests/frameworks/scenarios.rs b/crates/integration-tests/tests/frameworks/scenarios.rs
index 9990e2d9..d5f01fbb 100644
--- a/crates/integration-tests/tests/frameworks/scenarios.rs
+++ b/crates/integration-tests/tests/frameworks/scenarios.rs
@@ -708,7 +708,7 @@ fn ec_batch_sync_happy_path(base_url: &str) -> TestResult<()> {
 
     // Batch sync writes a UID for this hash
     let mappings = vec![BatchMapping {
-        ssc_hash: hash.clone(),
+        ec_hash: hash.clone(),
         partner_uid: "batch-uid-99".to_owned(),
         timestamp: 1_700_000_000,
     }];
@@ -753,7 +753,7 @@ fn ec_batch_sync_auth_rejection(base_url: &str) -> TestResult<()> {
     let client = EcTestClient::new(base_url);
 
     let dummy_mappings = vec![BatchMapping {
-        ssc_hash: "a".repeat(64),
+        ec_hash: "a".repeat(64),
         partner_uid: "uid-1".to_owned(),
         timestamp: 1_700_000_000,
     }];
diff --git a/crates/trusted-server-core/src/ec/admin.rs b/crates/trusted-server-core/src/ec/admin.rs
index 64e4ac39..7f7c60d5 100644
--- a/crates/trusted-server-core/src/ec/admin.rs
+++ b/crates/trusted-server-core/src/ec/admin.rs
@@ -236,9 +236,10 @@ pub fn handle_register_partner(
         created,
     };
 
-    let body = serde_json::to_string(&response_body).change_context(TrustedServerError::Ec {
-        message: "Failed to serialize registration response".to_owned(),
-    })?;
+    let body =
+        serde_json::to_string(&response_body).change_context(TrustedServerError::EdgeCookie {
+            message: "Failed to serialize registration response".to_owned(),
+        })?;
 
     Ok(Response::from_status(status)
         .with_content_type(fastly::mime::APPLICATION_JSON)
diff --git a/crates/trusted-server-core/src/ec/batch_sync.rs b/crates/trusted-server-core/src/ec/batch_sync.rs
index 5a5bc559..c99d45ee 100644
--- a/crates/trusted-server-core/src/ec/batch_sync.rs
+++ b/crates/trusted-server-core/src/ec/batch_sync.rs
@@ -1,7 +1,7 @@
 //! Server-to-server batch sync endpoint (`POST /api/v1/sync`).
 //!
 //! Partners send authenticated batch ID sync requests via Bearer token.
-//! Each mapping associates an `ssc_hash` (the 64-char hex EC hash prefix)
+//! Each mapping associates an `ec_hash` (the 64-char hex EC hash prefix)
 //! with the partner's user ID. Mappings are individually validated and
 //! written to the KV identity graph, with per-mapping rejection reasons
 //! reported in the response.
@@ -60,7 +60,7 @@ struct BatchSyncRequest {
 
 #[derive(Debug, Deserialize)]
 struct SyncMapping {
-    ssc_hash: String,
+    ec_hash: String,
     partner_uid: String,
     timestamp: u64,
 }
@@ -195,7 +195,7 @@ fn process_mappings(
     let mut errors = Vec::new();
 
     for (idx, mapping) in mappings.iter().enumerate() {
-        if !is_valid_ec_hash(&mapping.ssc_hash) {
+        if !is_valid_ec_hash(&mapping.ec_hash) {
             errors.push(MappingError {
                 index: idx,
                 reason: REASON_INVALID_EC_HASH,
@@ -212,9 +212,9 @@ fn process_mappings(
         }
 
         // Normalize to lowercase — KV keys are always lowercase hex.
-        let ssc_hash = mapping.ssc_hash.to_ascii_lowercase();
+        let ec_hash = mapping.ec_hash.to_ascii_lowercase();
         match writer.upsert_partner_id_if_exists(
-            &ssc_hash,
+            &ec_hash,
             partner_id,
             &mapping.partner_uid,
             mapping.timestamp,
@@ -236,8 +236,8 @@ fn process_mappings(
             }
             Err(err) => {
                 log::warn!(
-                    "Batch sync KV write failed for index {idx} (ssc_hash '{}'): {err:?}",
-                    mapping.ssc_hash
+                    "Batch sync KV write failed for index {idx} (ec_hash '{}'): {err:?}",
+                    mapping.ec_hash
                 );
                 errors.push(MappingError {
                     index: idx,
@@ -262,7 +262,7 @@ fn json_response<T: serde::Serialize>(
     status: StatusCode,
     body: &T,
 ) -> Result<Response, Report<TrustedServerError>> {
-    let body = serde_json::to_string(body).change_context(TrustedServerError::Ec {
+    let body = serde_json::to_string(body).change_context(TrustedServerError::EdgeCookie {
         message: "Failed to serialize batch sync response".to_owned(),
     })?;
 
@@ -395,9 +395,9 @@ mod tests {
         }
     }
 
-    fn mapping(ssc_hash: &str, partner_uid: &str, timestamp: u64) -> SyncMapping {
+    fn mapping(ec_hash: &str, partner_uid: &str, timestamp: u64) -> SyncMapping {
         SyncMapping {
-            ssc_hash: ssc_hash.to_owned(),
+            ec_hash: ec_hash.to_owned(),
             partner_uid: partner_uid.to_owned(),
             timestamp,
         }
@@ -473,18 +473,18 @@ mod tests {
 
     #[test]
     fn batch_sync_request_deserializes_correctly() {
-        let json = r#"{"mappings": [{"ssc_hash": "aaaa", "partner_uid": "u1", "timestamp": 100}]}"#;
+        let json = r#"{"mappings": [{"ec_hash": "aaaa", "partner_uid": "u1", "timestamp": 100}]}"#;
         let parsed: BatchSyncRequest =
             serde_json::from_str(json).expect("should deserialize batch sync request");
         assert_eq!(parsed.mappings.len(), 1);
-        assert_eq!(parsed.mappings[0].ssc_hash, "aaaa");
+        assert_eq!(parsed.mappings[0].ec_hash, "aaaa");
         assert_eq!(parsed.mappings[0].partner_uid, "u1");
         assert_eq!(parsed.mappings[0].timestamp, 100);
     }
 
     #[test]
     fn batch_sync_request_rejects_missing_timestamp() {
-        let json = r#"{"mappings": [{"ssc_hash": "bbbb", "partner_uid": "u2"}]}"#;
+        let json = r#"{"mappings": [{"ec_hash": "bbbb", "partner_uid": "u2"}]}"#;
         let result = serde_json::from_str::<BatchSyncRequest>(json);
         assert!(
             result.is_err(),
diff --git a/crates/trusted-server-core/src/ec/finalize.rs b/crates/trusted-server-core/src/ec/finalize.rs
index 94fe6b14..712c6719 100644
--- a/crates/trusted-server-core/src/ec/finalize.rs
+++ b/crates/trusted-server-core/src/ec/finalize.rs
@@ -98,12 +98,34 @@ pub fn set_ec_on_response(settings: &Settings, ec_context: &EcContext, response:
 }
 
 /// Clears EC cookie and removes EC-specific response headers.
+///
+/// In addition to the fixed [`EC_RESPONSE_HEADERS`], this also strips any
+/// dynamic `X-ts-<partner_id>` headers (matching the `x-ts-` prefix) to
+/// prevent leaking EC identity data when consent is withdrawn.
 pub fn clear_ec_on_response(settings: &Settings, response: &mut Response) {
     expire_ec_cookie(settings, response);
 
     for header in EC_RESPONSE_HEADERS {
         response.remove_header(*header);
     }
+
+    // Strip any dynamic x-ts-<partner_id> headers set by /identify or
+    // earlier processing. Collect names first to avoid borrow conflict.
+    let dynamic_ts_headers: Vec<String> = response
+        .get_header_names()
+        .filter_map(|name| {
+            let s = name.as_str();
+            if s.starts_with("x-ts-") {
+                Some(s.to_owned())
+            } else {
+                None
+            }
+        })
+        .collect();
+
+    for header in &dynamic_ts_headers {
+        response.remove_header(header.as_str());
+    }
 }
 
 fn withdrawal_hashes(ec_context: &EcContext) -> HashSet<String> {
@@ -170,6 +192,9 @@ mod tests {
         let mut response = Response::new();
         response.set_header("x-ts-ec", "abc");
         response.set_header("x-ts-eids", "[]");
+        // Dynamic partner headers that should also be stripped
+        response.set_header("x-ts-ssp_x", "partner-uid-123");
+        response.set_header("x-ts-liveramp", "lr-uid-456");
 
         clear_ec_on_response(&settings, &mut response);
 
@@ -181,6 +206,14 @@ mod tests {
             response.get_header("x-ts-eids").is_none(),
             "should remove x-ts-eids"
         );
+        assert!(
+            response.get_header("x-ts-ssp_x").is_none(),
+            "should remove dynamic x-ts-<partner_id> headers"
+        );
+        assert!(
+            response.get_header("x-ts-liveramp").is_none(),
+            "should remove dynamic x-ts-<partner_id> headers"
+        );
 
         let set_cookie = response
             .get_header("set-cookie")
diff --git a/crates/trusted-server-core/src/ec/generation.rs b/crates/trusted-server-core/src/ec/generation.rs
index f3bafeeb..d21728d4 100644
--- a/crates/trusted-server-core/src/ec/generation.rs
+++ b/crates/trusted-server-core/src/ec/generation.rs
@@ -63,7 +63,7 @@ fn generate_random_suffix(length: usize) -> String {
 ///
 /// # Errors
 ///
-/// - [`TrustedServerError::Ec`] if HMAC generation fails
+/// - [`TrustedServerError::EdgeCookie`] if HMAC generation fails
 pub fn generate_ec_id(
     settings: &Settings,
     client_ip: &str,
@@ -71,7 +71,7 @@ pub fn generate_ec_id(
     log::trace!("Input for fresh EC ID: client_ip={client_ip}");
 
     let mut mac = HmacSha256::new_from_slice(settings.ec.passphrase.expose().as_bytes())
-        .change_context(TrustedServerError::Ec {
+        .change_context(TrustedServerError::EdgeCookie {
             message: "Failed to create HMAC instance".to_string(),
         })?;
     mac.update(client_ip.as_bytes());
@@ -92,12 +92,12 @@ pub fn generate_ec_id(
 ///
 /// # Errors
 ///
-/// Returns [`TrustedServerError::Ec`] when the client IP is unavailable
+/// Returns [`TrustedServerError::EdgeCookie`] when the client IP is unavailable
 /// (e.g. in certain test or proxy configurations). EC generation requires
 /// a valid client IP — there is no fallback.
 pub fn extract_client_ip(req: &fastly::Request) -> Result<String, Report<TrustedServerError>> {
     req.get_client_ip_addr().map(normalize_ip).ok_or_else(|| {
-        Report::new(TrustedServerError::Ec {
+        Report::new(TrustedServerError::EdgeCookie {
             message: "Client IP required for EC generation but unavailable".to_string(),
         })
     })
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index b137808f..efb3f63d 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -106,8 +106,11 @@ fn parse_ec_from_request(req: &Request) -> Result<RequestEc, Report<TrustedServe
 /// - [`TrustedServerError::InvalidHeaderValue`] if cookie parsing fails
 pub fn get_ec_id(req: &fastly::Request) -> Result<Option<String>, Report<TrustedServerError>> {
     let parsed = parse_ec_from_request(req)?;
-    // Header takes precedence over cookie.
-    let ec_id = parsed.header_ec.or(parsed.cookie_ec);
+    // Header takes precedence over cookie; malformed values are discarded.
+    let ec_id = parsed
+        .header_ec
+        .filter(|v| is_valid_ec_id(v))
+        .or_else(|| parsed.cookie_ec.filter(|v| is_valid_ec_id(v)));
     if let Some(ref id) = ec_id {
         log::trace!("Existing EC ID found: {id}");
     }
@@ -177,8 +180,13 @@ impl EcContext {
         let parsed = parse_ec_from_request(req)?;
 
         // Header takes precedence over cookie for the active EC value.
-        // The cookie value is stored separately for revocation handling.
-        let ec_value = parsed.header_ec.or_else(|| parsed.cookie_ec.clone());
+        // Malformed values are discarded per §4.2: "If the header is
+        // present but malformed, it is discarded and the cookie value
+        // is used instead."
+        let ec_value = parsed
+            .header_ec
+            .filter(|v| is_valid_ec_id(v))
+            .or_else(|| parsed.cookie_ec.clone().filter(|v| is_valid_ec_id(v)));
         let ec_was_present = ec_value.is_some();
 
         if let Some(ref id) = ec_value {
@@ -240,7 +248,7 @@ impl EcContext {
         }
 
         let client_ip = self.client_ip.as_deref().ok_or_else(|| {
-            Report::new(TrustedServerError::Ec {
+            Report::new(TrustedServerError::EdgeCookie {
                 message: "Client IP required for EC generation but unavailable".to_string(),
             })
         })?;
@@ -434,14 +442,20 @@ mod tests {
         req
     }
 
+    /// Creates a valid EC ID for testing: `{64hex}.{6alnum}`.
+    fn valid_ec_id(prefix_char: &str, suffix: &str) -> String {
+        format!("{}.{suffix}", prefix_char.repeat(64))
+    }
+
     #[test]
     fn read_from_request_with_header_ec() {
         let settings = create_test_settings();
-        let req = create_test_request(&[("x-ts-ec", "header-ec-id")]);
+        let ec_id = valid_ec_id("a", "HdrEc1");
+        let req = create_test_request(&[("x-ts-ec", &ec_id)]);
 
         let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
 
-        assert_eq!(ec.ec_value(), Some("header-ec-id"));
+        assert_eq!(ec.ec_value(), Some(ec_id.as_str()));
         assert!(ec.ec_was_present(), "should detect EC from header");
         assert!(!ec.cookie_was_present(), "should not detect cookie");
         assert!(!ec.ec_generated(), "should not mark as generated");
@@ -450,11 +464,13 @@ mod tests {
     #[test]
     fn read_from_request_with_cookie_ec() {
         let settings = create_test_settings();
-        let req = create_test_request(&[("cookie", "ts-ec=cookie-ec-id")]);
+        let ec_id = valid_ec_id("b", "CkEc01");
+        let cookie = format!("ts-ec={ec_id}");
+        let req = create_test_request(&[("cookie", &cookie)]);
 
         let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
 
-        assert_eq!(ec.ec_value(), Some("cookie-ec-id"));
+        assert_eq!(ec.ec_value(), Some(ec_id.as_str()));
         assert!(ec.ec_was_present(), "should detect EC from cookie");
         assert!(ec.cookie_was_present(), "should detect cookie");
         assert!(!ec.ec_generated(), "should not mark as generated");
@@ -463,13 +479,16 @@ mod tests {
     #[test]
     fn read_from_request_header_takes_precedence_over_cookie() {
         let settings = create_test_settings();
-        let req = create_test_request(&[("x-ts-ec", "header-id"), ("cookie", "ts-ec=cookie-id")]);
+        let header_id = valid_ec_id("a", "Hdr001");
+        let cookie_id = valid_ec_id("b", "Ck0001");
+        let cookie = format!("ts-ec={cookie_id}");
+        let req = create_test_request(&[("x-ts-ec", &header_id), ("cookie", &cookie)]);
 
         let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
 
         assert_eq!(
             ec.ec_value(),
-            Some("header-id"),
+            Some(header_id.as_str()),
             "should prefer header over cookie"
         );
         assert!(ec.cookie_was_present(), "should still detect cookie");
@@ -487,10 +506,49 @@ mod tests {
         assert!(!ec.cookie_was_present(), "should not detect cookie");
     }
 
+    #[test]
+    fn read_from_request_discards_malformed_header_falls_back_to_cookie() {
+        let settings = create_test_settings();
+        let cookie_id = valid_ec_id("c", "FbCk01");
+        let cookie = format!("ts-ec={cookie_id}");
+        let req = create_test_request(&[("x-ts-ec", "malformed-header"), ("cookie", &cookie)]);
+
+        let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
+
+        assert_eq!(
+            ec.ec_value(),
+            Some(cookie_id.as_str()),
+            "should fall back to cookie when header is malformed"
+        );
+        assert!(ec.cookie_was_present(), "should detect cookie");
+    }
+
+    #[test]
+    fn read_from_request_discards_malformed_header_and_cookie() {
+        let settings = create_test_settings();
+        let req = create_test_request(&[("x-ts-ec", "bad-header"), ("cookie", "ts-ec=bad-cookie")]);
+
+        let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
+
+        assert!(
+            ec.ec_value().is_none(),
+            "should discard both malformed header and cookie"
+        );
+        assert!(
+            !ec.ec_was_present(),
+            "ec_was_present should be false when no valid EC found"
+        );
+        assert!(
+            ec.cookie_was_present(),
+            "cookie_was_present should still be true for withdrawal path"
+        );
+    }
+
     #[test]
     fn generate_if_needed_skips_when_ec_exists() {
         let settings = create_test_settings();
-        let req = create_test_request(&[("x-ts-ec", "existing-id")]);
+        let ec_id = valid_ec_id("d", "Exist1");
+        let req = create_test_request(&[("x-ts-ec", &ec_id)]);
 
         let mut ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
         ec.generate_if_needed(&settings, None)
@@ -498,7 +556,7 @@ mod tests {
 
         assert_eq!(
             ec.ec_value(),
-            Some("existing-id"),
+            Some(ec_id.as_str()),
             "should keep existing EC"
         );
         assert!(!ec.ec_generated(), "should not mark as generated");
@@ -508,17 +566,20 @@ mod tests {
     fn existing_cookie_ec_id_returns_cookie_value() {
         let settings = create_test_settings();
 
-        // With cookie present
-        let req = create_test_request(&[("cookie", "ts-ec=cookie-value")]);
+        // With cookie present (valid format)
+        let cookie_ec = valid_ec_id("e", "CkVal1");
+        let cookie = format!("ts-ec={cookie_ec}");
+        let req = create_test_request(&[("cookie", &cookie)]);
         let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
         assert_eq!(
             ec.existing_cookie_ec_id(),
-            Some("cookie-value"),
+            Some(cookie_ec.as_str()),
             "should return cookie EC ID"
         );
 
         // With only header (no cookie)
-        let req = create_test_request(&[("x-ts-ec", "header-value")]);
+        let header_ec = valid_ec_id("f", "HdrVl1");
+        let req = create_test_request(&[("x-ts-ec", &header_ec)]);
         let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
         assert!(
             ec.existing_cookie_ec_id().is_none(),
@@ -526,16 +587,19 @@ mod tests {
         );
 
         // With both header and cookie — should return cookie value
-        let req = create_test_request(&[("x-ts-ec", "header-id"), ("cookie", "ts-ec=cookie-id")]);
+        let header_ec2 = valid_ec_id("a", "Hdr002");
+        let cookie_ec2 = valid_ec_id("b", "Ck0002");
+        let cookie2 = format!("ts-ec={cookie_ec2}");
+        let req = create_test_request(&[("x-ts-ec", &header_ec2), ("cookie", &cookie2)]);
         let ec = EcContext::read_from_request(&settings, &req).expect("should read EC context");
         assert_eq!(
             ec.ec_value(),
-            Some("header-id"),
+            Some(header_ec2.as_str()),
             "should use header as active EC"
         );
         assert_eq!(
             ec.existing_cookie_ec_id(),
-            Some("cookie-id"),
+            Some(cookie_ec2.as_str()),
             "should return cookie value for revocation even when header takes precedence"
         );
     }
diff --git a/crates/trusted-server-core/src/ec/partner.rs b/crates/trusted-server-core/src/ec/partner.rs
index acc32517..828e225a 100644
--- a/crates/trusted-server-core/src/ec/partner.rs
+++ b/crates/trusted-server-core/src/ec/partner.rs
@@ -1,8 +1,13 @@
 //! Partner registry — `PartnerRecord` schema and `PartnerStore` operations.
 //!
 //! Each partner (SSP, DSP, identity vendor) is stored as a JSON record in
-//! the Fastly KV Store keyed by `partner_id`. A secondary index
-//! `apikey:{sha256_hex}` provides O(1) API key lookups for batch sync auth.
+//! the Fastly KV Store keyed by `partner_id`. Two secondary indexes exist:
+//!
+//! - `apikey:{sha256_hex}` — maps API key hashes to partner IDs for O(1)
+//!   auth lookups during batch sync.
+//! - `_pull_enabled` — JSON array of partner IDs with `pull_sync_enabled:
+//!   true`, enabling O(1+N) reads on the pull sync hot path instead of a
+//!   full partner scan.
 
 use std::{collections::HashSet, sync::OnceLock};
 
@@ -34,6 +39,13 @@ const RESERVED_PARTNER_IDS: &[&str] = &[
 /// Prefix for the API key hash secondary index keys.
 const APIKEY_INDEX_PREFIX: &str = "apikey:";
 
+/// Key for the pull-enabled partner secondary index.
+///
+/// Stores a JSON array of partner IDs that have `pull_sync_enabled: true`.
+/// Updated on every `upsert()` so that `pull_enabled_partners()` can read
+/// a single index key instead of listing/scanning all partners.
+const PULL_ENABLED_INDEX_KEY: &str = "_pull_enabled";
+
 /// Cached compiled regex for partner ID validation.
 static PARTNER_ID_REGEX: OnceLock<Result<Regex, String>> = OnceLock::new();
 
@@ -190,9 +202,13 @@ pub fn hash_api_key(api_key: &str) -> String {
 
 /// Wraps a Fastly KV Store for partner registry operations.
 ///
-/// Partner records are keyed by `partner_id`. A secondary index
-/// `apikey:{sha256_hex}` maps API key hashes to partner IDs for
-/// O(1) auth lookups during batch sync.
+/// Partner records are keyed by `partner_id`. Two secondary indexes
+/// optimize hot-path operations:
+///
+/// - `apikey:{sha256_hex}` maps API key hashes to partner IDs for
+///   O(1) auth lookups during batch sync.
+/// - `_pull_enabled` stores a JSON array of partner IDs with
+///   `pull_sync_enabled: true` for O(1+N) reads during pull sync dispatch.
 pub struct PartnerStore {
     store_name: String,
 }
@@ -289,7 +305,7 @@ impl PartnerStore {
             })?;
 
             for key in page.keys() {
-                if key.starts_with(APIKEY_INDEX_PREFIX) {
+                if key.starts_with(APIKEY_INDEX_PREFIX) || key == PULL_ENABLED_INDEX_KEY {
                     continue;
                 }
 
@@ -321,7 +337,73 @@ impl PartnerStore {
         Ok(records)
     }
 
-    /// Writes or updates a partner record and maintains the API key index.
+    /// Returns pull-enabled partners via the `_pull_enabled` secondary index.
+    ///
+    /// Performs 1 index read + N partner reads (where N = pull-enabled count)
+    /// instead of scanning all partners. Falls back to [`list_registered`]
+    /// with client-side filtering when the index is missing or unreadable,
+    /// ensuring correctness even before the first `upsert()` writes the index.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store or deserialization failure.
+    pub fn pull_enabled_partners(&self) -> Result<Vec<PartnerRecord>, Report<TrustedServerError>> {
+        let store = self.open_store()?;
+
+        // Read the secondary index.
+        let index_body = match store.lookup(PULL_ENABLED_INDEX_KEY) {
+            Ok(mut resp) => resp.take_body_bytes(),
+            Err(fastly::kv_store::KVStoreError::ItemNotFound) => {
+                // Index not yet written — fall back to full scan.
+                log::debug!("Pull-enabled index missing, falling back to list_registered");
+                return self
+                    .list_registered()
+                    .map(|v| v.into_iter().filter(|p| p.pull_sync_enabled).collect());
+            }
+            Err(err) => {
+                // Index unreadable — fall back to full scan rather than failing.
+                log::warn!(
+                    "Failed to read pull-enabled index, falling back to list_registered: {err:?}"
+                );
+                return self
+                    .list_registered()
+                    .map(|v| v.into_iter().filter(|p| p.pull_sync_enabled).collect());
+            }
+        };
+
+        let partner_ids: Vec<String> =
+            serde_json::from_slice(&index_body).change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: "Failed to deserialize pull-enabled index".to_owned(),
+            })?;
+
+        let mut records = Vec::with_capacity(partner_ids.len());
+        for partner_id in &partner_ids {
+            match self.get(partner_id)? {
+                Some(record) if record.pull_sync_enabled => {
+                    records.push(record);
+                }
+                Some(_) => {
+                    // Index is stale — partner is no longer pull-enabled.
+                    // This is self-healing: the next `upsert()` will fix the index.
+                    log::debug!(
+                        "Pull-enabled index references partner '{}' which is no longer pull-enabled",
+                        partner_id
+                    );
+                }
+                None => {
+                    log::debug!(
+                        "Pull-enabled index references non-existent partner '{}'",
+                        partner_id
+                    );
+                }
+            }
+        }
+
+        Ok(records)
+    }
+
+    /// Writes or updates a partner record and maintains secondary indexes.
     ///
     /// Returns `true` if this was a new partner (create), `false` if an
     /// existing partner was updated.
@@ -331,6 +413,7 @@ impl PartnerStore {
     /// 2. Write new `apikey:` index
     /// 3. Write primary record
     /// 4. Delete old `apikey:` index (if key rotated)
+    /// 5. Update `_pull_enabled` secondary index (best-effort)
     ///
     /// Writes are still **not fully atomic**, but this order ensures
     /// registration does not return success after a failed index write and
@@ -403,6 +486,12 @@ impl PartnerStore {
             }
         }
 
+        // 4. Update _pull_enabled secondary index (best-effort).
+        //    This is the last step so a failure here doesn't affect the
+        //    primary registration. `pull_enabled_partners()` falls back to
+        //    `list_registered()` if the index is missing or stale.
+        self.update_pull_enabled_index(&store, &record.id, record.pull_sync_enabled);
+
         Ok(is_create)
     }
 
@@ -438,6 +527,56 @@ impl PartnerStore {
         Ok(Some(partner_id))
     }
 
+    /// Best-effort update of the `_pull_enabled` secondary index.
+    ///
+    /// Reads the current index, adds or removes the partner ID, and writes
+    /// it back. All errors are logged and swallowed — the primary record
+    /// write has already succeeded.
+    fn update_pull_enabled_index(
+        &self,
+        store: &KVStore,
+        partner_id: &str,
+        pull_sync_enabled: bool,
+    ) {
+        // Read existing index (or start with empty list).
+        let mut ids: Vec<String> = match store.lookup(PULL_ENABLED_INDEX_KEY) {
+            Ok(mut resp) => {
+                let bytes = resp.take_body_bytes();
+                serde_json::from_slice(&bytes).unwrap_or_default()
+            }
+            Err(_) => Vec::new(),
+        };
+
+        let had_id = ids.iter().any(|id| id == partner_id);
+
+        if pull_sync_enabled && !had_id {
+            ids.push(partner_id.to_owned());
+        } else if !pull_sync_enabled && had_id {
+            ids.retain(|id| id != partner_id);
+        } else {
+            // No change needed.
+            return;
+        }
+
+        let body = match serde_json::to_string(&ids) {
+            Ok(b) => b,
+            Err(err) => {
+                log::warn!(
+                    "Failed to serialize pull-enabled index after updating partner '{}': {err}",
+                    partner_id
+                );
+                return;
+            }
+        };
+
+        if let Err(err) = store.build_insert().execute(PULL_ENABLED_INDEX_KEY, body) {
+            log::warn!(
+                "Failed to write pull-enabled index after updating partner '{}': {err:?}",
+                partner_id
+            );
+        }
+    }
+
     fn restore_previous_index_mapping(
         &self,
         store: &KVStore,
diff --git a/crates/trusted-server-core/src/ec/pull_sync.rs b/crates/trusted-server-core/src/ec/pull_sync.rs
index d07c15e0..298671ef 100644
--- a/crates/trusted-server-core/src/ec/pull_sync.rs
+++ b/crates/trusted-server-core/src/ec/pull_sync.rs
@@ -94,33 +94,40 @@ pub fn dispatch_pull_sync(
         }
     };
 
-    let partners = match partner_store.list_registered() {
+    // Use the _pull_enabled secondary index for O(1+N) reads instead of
+    // scanning all partners (§13.1). Falls back to list_registered() if
+    // the index is missing or unreadable.
+    let mut pull_partners = match partner_store.pull_enabled_partners() {
         Ok(partners) => partners,
         Err(err) => {
-            log::warn!("Pull sync: failed to list partners: {err:?}");
+            log::warn!("Pull sync: failed to list pull-enabled partners: {err:?}");
             return;
         }
     };
 
-    let pull_enabled_count = partners.iter().filter(|p| p.pull_sync_enabled).count();
+    // Sort by ID for deterministic ordering, then apply a rotating hourly
+    // offset so that different partners get dispatch priority (§10.3).
+    pull_partners.sort_by(|a, b| a.id.cmp(&b.id));
+
     log::debug!(
-        "Pull sync: enumerated {} partners ({} pull-enabled)",
-        partners.len(),
-        pull_enabled_count
+        "Pull sync: {} pull-enabled partners after filtering",
+        pull_partners.len(),
     );
 
-    if pull_enabled_count == 0 {
+    if pull_partners.is_empty() {
         return;
     }
 
+    // Rotate the partner list so that the starting partner changes each
+    // hour. This ensures fair distribution when max_concurrency limits
+    // how many partners are dispatched per request.
+    let offset = (now / 3600) as usize % pull_partners.len();
+    pull_partners.rotate_left(offset);
+
     let max_concurrency = settings.ec.pull_sync_concurrency.max(1);
     let mut in_flight: Vec<InFlightPull> = Vec::new();
 
-    for partner in partners {
-        if !partner.pull_sync_enabled {
-            continue;
-        }
-
+    for partner in pull_partners {
         if !is_partner_pull_eligible(&partner, kv_entry.as_ref(), now) {
             continue;
         }
@@ -536,4 +543,36 @@ mod tests {
             "should parse uid from 200 body"
         );
     }
+
+    #[test]
+    fn rotating_offset_distributes_partners_across_hours() {
+        // Simulate 3 partners sorted by ID: alpha, beta, gamma.
+        let ids = vec!["alpha", "beta", "gamma"];
+
+        // Hour 0: offset = 0 % 3 = 0 → [alpha, beta, gamma]
+        let ts_h0: u64 = 100; // within hour 0
+        let offset_h0 = (ts_h0 / 3600) as usize % ids.len();
+        assert_eq!(offset_h0, 0, "hour 0 should start at index 0");
+
+        // Hour 1: offset = (3600 / 3600) % 3 = 1 → [beta, gamma, alpha]
+        let offset_h1 = (3600u64 / 3600) as usize % ids.len();
+        assert_eq!(offset_h1, 1, "hour 1 should start at index 1");
+
+        // Hour 2: offset = (7200 / 3600) % 3 = 2 → [gamma, alpha, beta]
+        let offset_h2 = (7200u64 / 3600) as usize % ids.len();
+        assert_eq!(offset_h2, 2, "hour 2 should start at index 2");
+
+        // Hour 3: offset = (10800 / 3600) % 3 = 0 → wraps back to [alpha, beta, gamma]
+        let offset_h3 = (10800u64 / 3600) as usize % ids.len();
+        assert_eq!(offset_h3, 0, "hour 3 should wrap back to index 0");
+
+        // Verify rotate_left produces expected ordering
+        let mut rotated = ids.clone();
+        rotated.rotate_left(offset_h1);
+        assert_eq!(
+            rotated,
+            vec!["beta", "gamma", "alpha"],
+            "hour 1 rotation should move beta to front"
+        );
+    }
 }
diff --git a/crates/trusted-server-core/src/ec/sync_pixel.rs b/crates/trusted-server-core/src/ec/sync_pixel.rs
index d054076c..9323a038 100644
--- a/crates/trusted-server-core/src/ec/sync_pixel.rs
+++ b/crates/trusted-server-core/src/ec/sync_pixel.rs
@@ -34,8 +34,8 @@ pub fn handle_sync(
     let query = SyncQuery::parse(req)?;
 
     let partner = partner_store.get(&query.partner)?.ok_or_else(|| {
-        Report::new(TrustedServerError::BadRequest {
-            message: format!("unknown partner '{}'", query.partner),
+        Report::new(TrustedServerError::PartnerNotFound {
+            partner_id: query.partner.clone(),
         })
     })?;
 
diff --git a/crates/trusted-server-core/src/error.rs b/crates/trusted-server-core/src/error.rs
index 2720e88b..7008c42e 100644
--- a/crates/trusted-server-core/src/error.rs
+++ b/crates/trusted-server-core/src/error.rs
@@ -80,9 +80,17 @@ pub enum TrustedServerError {
     #[display("Settings error: {message}")]
     Settings { message: String },
 
-    /// EC ID generation or validation failed.
-    #[display("EC error: {message}")]
-    Ec { message: String },
+    /// Edge cookie ID generation or validation failed.
+    #[display("Edge cookie error: {message}")]
+    EdgeCookie { message: String },
+
+    /// Requested partner was not found in the partner registry.
+    #[display("Partner not found: {partner_id}")]
+    PartnerNotFound { partner_id: String },
+
+    /// Partner authentication failed (invalid or missing credentials).
+    #[display("Partner auth failed: {partner_id}")]
+    PartnerAuthFailed { partner_id: String },
 }
 
 impl Error for TrustedServerError {}
@@ -117,6 +125,8 @@ impl IntoHttpResponse for TrustedServerError {
             Self::Forbidden { .. } => StatusCode::FORBIDDEN,
             Self::AllowlistViolation { .. } => StatusCode::FORBIDDEN,
             Self::Ec { .. } => StatusCode::INTERNAL_SERVER_ERROR,
+            Self::PartnerNotFound { .. } => StatusCode::BAD_REQUEST,
+            Self::PartnerAuthFailed { .. } => StatusCode::UNAUTHORIZED,
         }
     }
 
diff --git a/crates/trusted-server-core/src/http_util.rs b/crates/trusted-server-core/src/http_util.rs
index 72d01e4b..b38a0e4f 100644
--- a/crates/trusted-server-core/src/http_util.rs
+++ b/crates/trusted-server-core/src/http_util.rs
@@ -10,14 +10,18 @@ use crate::settings::Settings;
 
 /// Copy `X-*` custom headers from one request to another, skipping TS-internal headers.
 ///
-/// This filters out all headers listed in [`INTERNAL_HEADERS`] to prevent leaking
-/// internal identity, geo-enrichment, and debugging data to downstream third-party
-/// services. Integrations that forward custom headers should use this utility
-/// instead of manually iterating over header names.
+/// This filters out all headers listed in [`INTERNAL_HEADERS`] **and** any header
+/// matching the `x-ts-` prefix (case-insensitive) to prevent leaking internal
+/// identity, geo-enrichment, debugging data, and dynamic `X-ts-<partner_id>`
+/// headers to downstream third-party services. Integrations that forward custom
+/// headers should use this utility instead of manually iterating over header names.
 pub fn copy_custom_headers(from: &Request, to: &mut Request) {
     for header_name in from.get_header_names() {
         let name_str = header_name.as_str();
+        // Header names are lowercased by the HTTP library, so a single
+        // prefix check covers both `x-ts-` and `X-ts-` variants.
         if (name_str.starts_with("x-") || name_str.starts_with("X-"))
+            && !name_str.starts_with("x-ts-")
             && !INTERNAL_HEADERS.contains(&name_str)
         {
             if let Some(value) = from.get_header(header_name) {
@@ -639,6 +643,9 @@ mod tests {
         req.set_header("X-Custom-2", "value2");
         req.set_header("x-ts-ec", "should not copy");
         req.set_header("x-geo-country", "US");
+        // Dynamic partner header (x-ts-<partner_id>)
+        req.set_header("x-ts-ssp_x", "partner-uid-123");
+        req.set_header("x-ts-liveramp", "lr-uid-456");
 
         let mut target = Request::new(fastly::http::Method::GET, "https://target.com");
         copy_custom_headers(&req, &mut target);
@@ -661,5 +668,13 @@ mod tests {
             target.get_header("x-geo-country").is_none(),
             "Should filter x-geo-country"
         );
+        assert!(
+            target.get_header("x-ts-ssp_x").is_none(),
+            "Should filter dynamic x-ts-<partner_id> headers"
+        );
+        assert!(
+            target.get_header("x-ts-liveramp").is_none(),
+            "Should filter dynamic x-ts-<partner_id> headers"
+        );
     }
 }
diff --git a/crates/trusted-server-core/src/integrations/registry.rs b/crates/trusted-server-core/src/integrations/registry.rs
index c3c824be..2c7de3bc 100644
--- a/crates/trusted-server-core/src/integrations/registry.rs
+++ b/crates/trusted-server-core/src/integrations/registry.rs
@@ -1291,8 +1291,10 @@ mod tests {
         let registry = IntegrationRegistry::from_routes(routes);
 
         let mut req = Request::get("https://test.example.com/integrations/test/ec");
-        // Pre-existing cookie, but no geo data → Unknown jurisdiction → consent denied.
-        req.set_header(header::COOKIE, "ts-ec=existing_id_12345");
+        // Pre-existing cookie with valid EC ID format, but no geo data →
+        // Unknown jurisdiction → consent denied.
+        let valid_ec_id = format!("{}.AbCd12", "a".repeat(64));
+        req.set_header(header::COOKIE, format!("ts-ec={valid_ec_id}"));
         let mut ec_context =
             EcContext::read_from_request(&settings, &req).expect("should read EC context");
 
diff --git a/crates/trusted-server-core/src/proxy.rs b/crates/trusted-server-core/src/proxy.rs
index c85298c1..c03c7d45 100644
--- a/crates/trusted-server-core/src/proxy.rs
+++ b/crates/trusted-server-core/src/proxy.rs
@@ -1407,7 +1407,8 @@ mod tests {
                 sig
             ),
         );
-        req.set_header(crate::constants::HEADER_X_TS_EC, "ec-123");
+        let valid_ec_id = format!("{}.AbCd12", "a".repeat(64));
+        req.set_header(crate::constants::HEADER_X_TS_EC, &valid_ec_id);
 
         let resp = handle_first_party_click(&settings, req)
             .await
@@ -1423,7 +1424,7 @@ mod tests {
             .map(|(k, v)| (k.into_owned(), v.into_owned()))
             .collect();
         assert_eq!(pairs.remove("foo").as_deref(), Some("1"));
-        assert_eq!(pairs.remove("ts-ec").as_deref(), Some("ec-123"));
+        assert_eq!(pairs.remove("ts-ec").as_deref(), Some(valid_ec_id.as_str()));
         assert!(pairs.is_empty());
     }
 
diff --git a/crates/trusted-server-core/src/publisher.rs b/crates/trusted-server-core/src/publisher.rs
index 70452635..7cce461f 100644
--- a/crates/trusted-server-core/src/publisher.rs
+++ b/crates/trusted-server-core/src/publisher.rs
@@ -615,16 +615,18 @@ mod tests {
     #[test]
     fn revocation_targets_cookie_ec_id_not_header() {
         let settings = create_test_settings();
+        let header_ec = format!("{}.HdrId1", "a".repeat(64));
+        let cookie_ec = format!("{}.CkId01", "b".repeat(64));
         let mut req = Request::new(Method::GET, "https://test.example.com/page");
-        req.set_header("x-ts-ec", "header_id");
-        req.set_header("cookie", "ts-ec=cookie_id; other=value");
+        req.set_header("x-ts-ec", &header_ec);
+        req.set_header("cookie", format!("ts-ec={cookie_ec}; other=value"));
 
         let ec_context =
             EcContext::read_from_request(&settings, &req).expect("should read EC context");
 
         assert_eq!(
             ec_context.ec_value(),
-            Some("header_id"),
+            Some(header_ec.as_str()),
             "should resolve request EC ID from header precedence"
         );
         assert!(
@@ -633,7 +635,7 @@ mod tests {
         );
         assert_eq!(
             ec_context.existing_cookie_ec_id(),
-            Some("cookie_id"),
+            Some(cookie_ec.as_str()),
             "should return cookie EC value for revocation, not the header value"
         );
     }

From 6244da2326a4271728c3df248f60d51c77c62805 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Mon, 30 Mar 2026 09:36:30 -0500
Subject: [PATCH 14/36] Harden EC endpoints: input validation, binary-search
 EIDs encoding, and cleanup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add body size limit (64 KiB) to partner registration
- Validate partner UID length (max 512 bytes) in batch sync and sync pixel
- Replace linear scan with binary search in encode_eids_header
- Use constant-time comparison inline in partner lookup, remove unused verify_api_key
- Remove unused PartnerAuthFailed error variant, fix PartnerNotFound → 404
- Add Access-Control-Max-Age CORS header to identify endpoint
- Tighten consent-denied integration test to expect only 403
- Add stability doc-comment to normalize_ip
- Log warning instead of silent fallback on SystemTime failure
---
 .../tests/frameworks/scenarios.rs             | 14 ++++-----
 crates/trusted-server-core/src/ec/admin.rs    | 11 ++++++-
 .../trusted-server-core/src/ec/batch_sync.rs  |  5 +++-
 crates/trusted-server-core/src/ec/eids.rs     | 27 ++++++++++++++---
 .../trusted-server-core/src/ec/generation.rs  |  8 +++++
 crates/trusted-server-core/src/ec/identify.rs |  1 +
 crates/trusted-server-core/src/ec/mod.rs      |  5 +++-
 crates/trusted-server-core/src/ec/partner.rs  | 29 ++-----------------
 .../trusted-server-core/src/ec/sync_pixel.rs  |  9 ++++++
 crates/trusted-server-core/src/error.rs       |  6 +---
 10 files changed, 68 insertions(+), 47 deletions(-)

diff --git a/crates/integration-tests/tests/frameworks/scenarios.rs b/crates/integration-tests/tests/frameworks/scenarios.rs
index d5f01fbb..3ee9f913 100644
--- a/crates/integration-tests/tests/frameworks/scenarios.rs
+++ b/crates/integration-tests/tests/frameworks/scenarios.rs
@@ -613,21 +613,19 @@ fn ec_identify_consent_denied(base_url: &str) -> TestResult<()> {
             .attach("should set ts-ec on organic request for consent-denied test")
     })?;
 
-    // Identify with GPC=1 — if jurisdiction is non-regulated + GPC,
-    // consent may still be denied depending on US-state detection.
-    // Without geo, jurisdiction is Unknown → fail-closed → 403.
+    // Identify with GPC=1 — without geo, jurisdiction is Unknown →
+    // fail-closed → consent denied. Per spec §11.4, consent is evaluated
+    // *before* EC presence, so this must be 403 Forbidden regardless of
+    // whether an EC cookie exists.
     let resp = client.get_with_headers("/identify", &[("sec-gpc", "1")])?;
 
     let status = resp.status().as_u16();
-    // Under Unknown jurisdiction (no geo in Viceroy), EC is denied
-    // so the response may be 403 or 204 depending on whether the EC
-    // context reads the cookie before consent check.
-    if status != 403 && status != 204 {
+    if status != 403 {
         return Err(Report::new(TestError::UnexpectedStatusCode {
             expected: 403,
             actual: status,
         })
-        .attach("identify with consent denied should return 403 or 204"));
+        .attach("identify with consent denied should return 403"));
     }
 
     log::info!("EC identify consent denied: PASSED (status={status})");
diff --git a/crates/trusted-server-core/src/ec/admin.rs b/crates/trusted-server-core/src/ec/admin.rs
index 7f7c60d5..ae30e3db 100644
--- a/crates/trusted-server-core/src/ec/admin.rs
+++ b/crates/trusted-server-core/src/ec/admin.rs
@@ -150,8 +150,17 @@ pub fn handle_register_partner(
     partner_store: &PartnerStore,
     mut req: Request,
 ) -> Result<Response, Report<TrustedServerError>> {
-    // Parse request body.
+    // Parse request body with size limit to prevent memory abuse.
+    const MAX_BODY_SIZE: usize = 64 * 1024; // 64 KiB
     let body_bytes = req.take_body_bytes();
+    if body_bytes.len() > MAX_BODY_SIZE {
+        return Err(Report::new(TrustedServerError::BadRequest {
+            message: format!(
+                "Request body too large ({} bytes, max {MAX_BODY_SIZE})",
+                body_bytes.len()
+            ),
+        }));
+    }
     let request: RegisterPartnerRequest =
         serde_json::from_slice(&body_bytes).change_context(TrustedServerError::BadRequest {
             message: "Invalid JSON in request body".to_owned(),
diff --git a/crates/trusted-server-core/src/ec/batch_sync.rs b/crates/trusted-server-core/src/ec/batch_sync.rs
index c99d45ee..6c4da2be 100644
--- a/crates/trusted-server-core/src/ec/batch_sync.rs
+++ b/crates/trusted-server-core/src/ec/batch_sync.rs
@@ -27,6 +27,9 @@ const REASON_KV_UNAVAILABLE: &str = "kv_unavailable";
 /// Maximum number of mappings allowed in a single batch request.
 const MAX_BATCH_SIZE: usize = 1000;
 
+/// Maximum allowed length (in bytes) for a partner UID.
+const MAX_UID_LENGTH: usize = 512;
+
 trait BatchSyncWriter {
     fn upsert_partner_id_if_exists(
         &self,
@@ -203,7 +206,7 @@ fn process_mappings(
             continue;
         }
 
-        if mapping.partner_uid.is_empty() {
+        if mapping.partner_uid.is_empty() || mapping.partner_uid.len() > MAX_UID_LENGTH {
             errors.push(MappingError {
                 index: idx,
                 reason: REASON_INVALID_PARTNER_UID,
diff --git a/crates/trusted-server-core/src/ec/eids.rs b/crates/trusted-server-core/src/ec/eids.rs
index 5af322c0..c4f7e550 100644
--- a/crates/trusted-server-core/src/ec/eids.rs
+++ b/crates/trusted-server-core/src/ec/eids.rs
@@ -114,20 +114,39 @@ pub fn build_eids_header(
 ///
 /// Returns an error if JSON serialization fails.
 pub fn encode_eids_header(eids: &[Eid]) -> Result<(String, bool), Report<TrustedServerError>> {
-    for size in (0..=eids.len()).rev() {
+    let try_encode = |size: usize| -> Result<String, Report<TrustedServerError>> {
         let json = serde_json::to_vec(&eids[..size]).change_context(
             TrustedServerError::Configuration {
                 message: "Failed to serialize eids header payload".to_owned(),
             },
         )?;
-        let encoded = BASE64.encode(json);
+        Ok(BASE64.encode(json))
+    };
 
+    // Fast path: try the full slice first (common case — no truncation).
+    let encoded = try_encode(eids.len())?;
+    if encoded.len() <= MAX_EIDS_HEADER_BYTES {
+        return Ok((encoded, false));
+    }
+
+    // Binary search for the largest count that fits within the limit.
+    // Invariant: lo always fits, hi never fits.
+    let mut lo: usize = 0;
+    let mut hi: usize = eids.len();
+
+    while lo + 1 < hi {
+        let mid = lo + (hi - lo) / 2;
+        let encoded = try_encode(mid)?;
         if encoded.len() <= MAX_EIDS_HEADER_BYTES {
-            return Ok((encoded, size != eids.len()));
+            lo = mid;
+        } else {
+            hi = mid;
         }
     }
 
-    Ok((BASE64.encode("[]"), true))
+    // `lo` is the largest size that fits. Re-encode it for the final value.
+    let encoded = try_encode(lo)?;
+    Ok((encoded, true))
 }
 
 #[cfg(test)]
diff --git a/crates/trusted-server-core/src/ec/generation.rs b/crates/trusted-server-core/src/ec/generation.rs
index d21728d4..3752b479 100644
--- a/crates/trusted-server-core/src/ec/generation.rs
+++ b/crates/trusted-server-core/src/ec/generation.rs
@@ -24,6 +24,14 @@ const ALPHANUMERIC_CHARSET: &[u8] =
 /// where devices rotate their interface identifier (lower 64 bits).
 /// The first 4 segments are hex-encoded without separators.
 /// IPv4 addresses are returned unchanged.
+///
+/// # Stability
+///
+/// The output format is a stable contract — EC hashes stored in KV depend
+/// on it. Changing the format would invalidate all existing EC identities.
+/// - **IPv4:** decimal-dotted notation (e.g. `"192.168.1.1"`)
+/// - **IPv6:** first 4 segments as zero-padded lowercase hex without
+///   separators (e.g. `"20010db885a30000"`)
 fn normalize_ip(ip: IpAddr) -> String {
     match ip {
         IpAddr::V4(ipv4) => ipv4.to_string(),
diff --git a/crates/trusted-server-core/src/ec/identify.rs b/crates/trusted-server-core/src/ec/identify.rs
index 5226cd85..b03dee86 100644
--- a/crates/trusted-server-core/src/ec/identify.rs
+++ b/crates/trusted-server-core/src/ec/identify.rs
@@ -214,6 +214,7 @@ fn apply_cors_headers(response: &mut Response, origin: &str) {
         header::ACCESS_CONTROL_ALLOW_HEADERS,
         "Cookie, X-ts-ec, X-consent-advertising",
     );
+    response.set_header(header::ACCESS_CONTROL_MAX_AGE, "600");
     response.set_header(header::VARY, "Origin");
 }
 
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index efb3f63d..959824b0 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -422,7 +422,10 @@ pub(crate) fn current_timestamp() -> u64 {
     std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
         .map(|d| d.as_secs())
-        .unwrap_or(0)
+        .unwrap_or_else(|err| {
+            log::warn!("SystemTime::now() failed, falling back to epoch 0: {err}");
+            0
+        })
 }
 
 #[cfg(test)]
diff --git a/crates/trusted-server-core/src/ec/partner.rs b/crates/trusted-server-core/src/ec/partner.rs
index 828e225a..b26e7a91 100644
--- a/crates/trusted-server-core/src/ec/partner.rs
+++ b/crates/trusted-server-core/src/ec/partner.rs
@@ -659,8 +659,8 @@ impl PartnerStore {
         };
 
         // Verify the stored hash matches — guards against stale index from
-        // key rotation.
-        if record.api_key_hash != hash {
+        // key rotation. Uses constant-time comparison to prevent timing attacks.
+        if !bool::from(record.api_key_hash.as_bytes().ct_eq(hash.as_bytes())) {
             log::warn!(
                 "API key hash mismatch for partner '{}' (stale index after key rotation)",
                 record.id,
@@ -670,31 +670,6 @@ impl PartnerStore {
 
         Ok(Some(record))
     }
-
-    /// Verifies an API key against the stored hash for a given partner.
-    ///
-    /// Uses SHA-256 hashing and constant-time comparison to prevent
-    /// timing attacks.
-    ///
-    /// # Errors
-    ///
-    /// Returns [`TrustedServerError::KvStore`] if the partner lookup fails.
-    pub fn verify_api_key(
-        &self,
-        partner_id: &str,
-        api_key: &str,
-    ) -> Result<bool, Report<TrustedServerError>> {
-        let record = match self.get(partner_id)? {
-            Some(r) => r,
-            None => return Ok(false),
-        };
-
-        let incoming_hash = hash_api_key(api_key);
-        let stored_bytes = record.api_key_hash.as_bytes();
-        let incoming_bytes = incoming_hash.as_bytes();
-
-        Ok(stored_bytes.ct_eq(incoming_bytes).into())
-    }
 }
 
 #[cfg(test)]
diff --git a/crates/trusted-server-core/src/ec/sync_pixel.rs b/crates/trusted-server-core/src/ec/sync_pixel.rs
index 9323a038..d968c151 100644
--- a/crates/trusted-server-core/src/ec/sync_pixel.rs
+++ b/crates/trusted-server-core/src/ec/sync_pixel.rs
@@ -18,6 +18,9 @@ use super::EcContext;
 /// Name of the Fastly rate counter resource used by sync rate limiting.
 pub const RATE_COUNTER_NAME: &str = "counter_store";
 
+/// Maximum allowed length (in bytes) for a partner UID.
+const MAX_UID_LENGTH: usize = 512;
+
 /// Handles `GET /sync` pixel sync requests.
 ///
 /// # Errors
@@ -33,6 +36,12 @@ pub fn handle_sync(
 ) -> Result<Response, Report<TrustedServerError>> {
     let query = SyncQuery::parse(req)?;
 
+    if query.uid.len() > MAX_UID_LENGTH {
+        return Err(Report::new(TrustedServerError::BadRequest {
+            message: format!("uid exceeds maximum length of {MAX_UID_LENGTH} bytes"),
+        }));
+    }
+
     let partner = partner_store.get(&query.partner)?.ok_or_else(|| {
         Report::new(TrustedServerError::PartnerNotFound {
             partner_id: query.partner.clone(),
diff --git a/crates/trusted-server-core/src/error.rs b/crates/trusted-server-core/src/error.rs
index 7008c42e..c0de14ba 100644
--- a/crates/trusted-server-core/src/error.rs
+++ b/crates/trusted-server-core/src/error.rs
@@ -87,10 +87,6 @@ pub enum TrustedServerError {
     /// Requested partner was not found in the partner registry.
     #[display("Partner not found: {partner_id}")]
     PartnerNotFound { partner_id: String },
-
-    /// Partner authentication failed (invalid or missing credentials).
-    #[display("Partner auth failed: {partner_id}")]
-    PartnerAuthFailed { partner_id: String },
 }
 
 impl Error for TrustedServerError {}
@@ -125,7 +121,7 @@ impl IntoHttpResponse for TrustedServerError {
             Self::Forbidden { .. } => StatusCode::FORBIDDEN,
             Self::AllowlistViolation { .. } => StatusCode::FORBIDDEN,
             Self::Ec { .. } => StatusCode::INTERNAL_SERVER_ERROR,
-            Self::PartnerNotFound { .. } => StatusCode::BAD_REQUEST,
+            Self::PartnerNotFound { .. } => StatusCode::NOT_FOUND,
             Self::PartnerAuthFailed { .. } => StatusCode::UNAUTHORIZED,
         }
     }

From d544aadfc639eb0e80c51d870492026e0b70d6a2 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Mon, 30 Mar 2026 19:03:54 -0500
Subject: [PATCH 15/36] Fix post-rebase compilation: restore missing methods,
 imports, and error variants
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Resolve integration issues from rebasing onto feature/ssc-update:
- Restore prepare_runtime() and validate_cookie_domain() lost in conflict resolution
- Add InsecureDefault error variant and wire reject_placeholder_secrets() into get_settings()
- Add sha2/subtle imports for constant-time auth comparison
- Fix error match arms (Ec → EdgeCookie, remove nonexistent PartnerAuthFailed)
- Fix orchestrator error handling to use send_to_client() pattern
- Remove dead cookie helpers superseded by ec/cookies module
---
 .../trusted-server-adapter-fastly/src/main.rs |  3 +-
 crates/trusted-server-core/src/auth.rs        |  2 +
 crates/trusted-server-core/src/cookies.rs     | 44 -------------------
 crates/trusted-server-core/src/error.rs       |  8 +++-
 crates/trusted-server-core/src/settings.rs    | 35 ++++++++++++++-
 .../trusted-server-core/src/settings_data.rs  |  2 +-
 6 files changed, 44 insertions(+), 50 deletions(-)

diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 0901adcd..0e4f7867 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -75,7 +75,8 @@ fn main() -> Result<(), Error> {
         Ok(orchestrator) => orchestrator,
         Err(e) => {
             log::error!("Failed to build auction orchestrator: {:?}", e);
-            return Ok(to_error_response(&e));
+            to_error_response(&e).send_to_client();
+            return Ok(());
         }
     };
 
diff --git a/crates/trusted-server-core/src/auth.rs b/crates/trusted-server-core/src/auth.rs
index 1b60eb81..9ea918e8 100644
--- a/crates/trusted-server-core/src/auth.rs
+++ b/crates/trusted-server-core/src/auth.rs
@@ -2,6 +2,8 @@ use base64::{engine::general_purpose::STANDARD, Engine as _};
 use error_stack::Report;
 use fastly::http::{header, StatusCode};
 use fastly::{Request, Response};
+use sha2::{Digest, Sha256};
+use subtle::ConstantTimeEq;
 
 use crate::error::TrustedServerError;
 use crate::settings::Settings;
diff --git a/crates/trusted-server-core/src/cookies.rs b/crates/trusted-server-core/src/cookies.rs
index 2d9bf2ff..3408eb79 100644
--- a/crates/trusted-server-core/src/cookies.rs
+++ b/crates/trusted-server-core/src/cookies.rs
@@ -23,50 +23,6 @@ pub const CONSENT_COOKIE_NAMES: &[&str] = &[
     COOKIE_US_PRIVACY,
 ];
 
-const COOKIE_MAX_AGE: i32 = 365 * 24 * 60 * 60; // 1 year
-
-fn is_allowed_ec_id_char(c: char) -> bool {
-    c.is_ascii_alphanumeric() || matches!(c, '.' | '-' | '_')
-}
-
-// Outbound allowlist for cookie sanitization: permits [a-zA-Z0-9._-] as a
-// defense-in-depth backstop when setting the Set-Cookie header. This is
-// intentionally broader than the inbound format validator
-// (`synthetic::is_valid_synthetic_id`), which enforces the exact
-// `<64-hex>.<6-alphanumeric>` structure and is used to reject untrusted
-// request values before they enter the system.
-#[must_use]
-pub(crate) fn ec_id_has_only_allowed_chars(ec_id: &str) -> bool {
-    ec_id.chars().all(is_allowed_ec_id_char)
-}
-
-fn sanitize_ec_id_for_cookie(ec_id: &str) -> Cow<'_, str> {
-    if ec_id_has_only_allowed_chars(ec_id) {
-        return Cow::Borrowed(ec_id);
-    }
-
-    let safe_id = ec_id
-        .chars()
-        .filter(|c| is_allowed_ec_id_char(*c))
-        .collect::<String>();
-
-    log::warn!(
-        "Stripped disallowed characters from EC ID before setting cookie (len {} -> {}); \
-         callers should reject invalid request IDs before cookie creation",
-        ec_id.len(),
-        safe_id.len(),
-    );
-
-    Cow::Owned(safe_id)
-}
-
-fn ec_cookie_attributes(settings: &Settings, max_age: i32) -> String {
-    format!(
-        "Domain={}; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age={max_age}",
-        settings.publisher.cookie_domain,
-    )
-}
-
 /// Parses a cookie string into a [`CookieJar`].
 ///
 /// Returns an empty jar if the cookie string is unparseable.
diff --git a/crates/trusted-server-core/src/error.rs b/crates/trusted-server-core/src/error.rs
index c0de14ba..26c000c6 100644
--- a/crates/trusted-server-core/src/error.rs
+++ b/crates/trusted-server-core/src/error.rs
@@ -87,6 +87,10 @@ pub enum TrustedServerError {
     /// Requested partner was not found in the partner registry.
     #[display("Partner not found: {partner_id}")]
     PartnerNotFound { partner_id: String },
+
+    /// A secret field still contains a known placeholder/default value.
+    #[display("Insecure default value for: {field}")]
+    InsecureDefault { field: String },
 }
 
 impl Error for TrustedServerError {}
@@ -120,9 +124,9 @@ impl IntoHttpResponse for TrustedServerError {
             Self::Proxy { .. } => StatusCode::BAD_GATEWAY,
             Self::Forbidden { .. } => StatusCode::FORBIDDEN,
             Self::AllowlistViolation { .. } => StatusCode::FORBIDDEN,
-            Self::Ec { .. } => StatusCode::INTERNAL_SERVER_ERROR,
+            Self::EdgeCookie { .. } => StatusCode::INTERNAL_SERVER_ERROR,
             Self::PartnerNotFound { .. } => StatusCode::NOT_FOUND,
-            Self::PartnerAuthFailed { .. } => StatusCode::UNAUTHORIZED,
+            Self::InsecureDefault { .. } => StatusCode::INTERNAL_SERVER_ERROR,
         }
     }
 
diff --git a/crates/trusted-server-core/src/settings.rs b/crates/trusted-server-core/src/settings.rs
index 6d8b714d..3951f991 100644
--- a/crates/trusted-server-core/src/settings.rs
+++ b/crates/trusted-server-core/src/settings.rs
@@ -22,6 +22,7 @@ pub struct Publisher {
     pub domain: String,
     /// Domain for non-EC cookies. EC cookies use a separate computed domain
     /// (see [`ec_cookie_domain`](Self::ec_cookie_domain)).
+    #[validate(custom(function = validate_cookie_domain))]
     pub cookie_domain: String,
     #[validate(custom(function = validate_no_trailing_slash))]
     pub origin_url: String,
@@ -534,6 +535,19 @@ impl Settings {
     ///
     /// # Errors
     ///
+    /// Returns a configuration error if any cached runtime artifact cannot be prepared.
+    pub fn prepare_runtime(&self) -> Result<(), Report<TrustedServerError>> {
+        for handler in &self.handlers {
+            handler.prepare_runtime()?;
+        }
+
+        Ok(())
+    }
+
+    /// Reject settings that still contain known placeholder secrets.
+    ///
+    /// # Errors
+    ///
     /// Returns [`TrustedServerError::InsecureDefault`] when one or more secret
     /// fields still contain a placeholder value.
     pub fn reject_placeholder_secrets(&self) -> Result<(), Report<TrustedServerError>> {
@@ -546,7 +560,13 @@ impl Settings {
             insecure_fields.push("publisher.proxy_secret");
         }
 
-        Ok(())
+        if insecure_fields.is_empty() {
+            Ok(())
+        } else {
+            Err(Report::new(TrustedServerError::InsecureDefault {
+                field: insecure_fields.join(", "),
+            }))
+        }
     }
 
     /// Resolve the first handler whose regex matches the request path.
@@ -645,6 +665,18 @@ impl Settings {
     }
 }
 
+fn validate_cookie_domain(value: &str) -> Result<(), ValidationError> {
+    // `=` is excluded: it only has special meaning in the name=value pair,
+    // not within the Domain attribute value.
+    if value.contains([';', '\n', '\r']) {
+        let mut err = ValidationError::new("cookie_metacharacters");
+        err.message =
+            Some("cookie_domain must not contain cookie metacharacters (;, \\n, \\r)".into());
+        return Err(err);
+    }
+    Ok(())
+}
+
 fn validate_no_trailing_slash(value: &str) -> Result<(), ValidationError> {
     if value.ends_with('/') {
         let mut err = ValidationError::new("trailing_slash");
@@ -1684,7 +1716,6 @@ mod tests {
         );
     }
 
-<<<<<<< HEAD
     // --- Proxy::normalize ---
 
     #[test]
diff --git a/crates/trusted-server-core/src/settings_data.rs b/crates/trusted-server-core/src/settings_data.rs
index 39b06650..7a59f47a 100644
--- a/crates/trusted-server-core/src/settings_data.rs
+++ b/crates/trusted-server-core/src/settings_data.rs
@@ -3,7 +3,7 @@ use error_stack::{Report, ResultExt};
 use validator::Validate;
 
 use crate::error::TrustedServerError;
-use crate::settings::{EdgeCookie, Publisher, Settings};
+use crate::settings::Settings;
 
 pub use crate::auction_config_types::AuctionConfig;
 

From b15c23335cfc14c33a84e39620c9d426a31ae233 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Mon, 30 Mar 2026 20:20:19 -0500
Subject: [PATCH 16/36] Restore iframe creative rendering accidentally reverted
 by EC migration

---
 crates/js/lib/src/core/render.ts           | 13 ++++++------
 crates/js/lib/test/core/render.test.ts     |  6 +++---
 crates/trusted-server-core/src/creative.rs | 24 ++++++++++++----------
 3 files changed, 23 insertions(+), 20 deletions(-)

diff --git a/crates/js/lib/src/core/render.ts b/crates/js/lib/src/core/render.ts
index da223851..ee08ef28 100644
--- a/crates/js/lib/src/core/render.ts
+++ b/crates/js/lib/src/core/render.ts
@@ -7,15 +7,16 @@ import NORMALIZE_CSS from './styles/normalize.css?inline';
 import IFRAME_TEMPLATE from './templates/iframe.html?raw';
 
 // Sandbox permissions granted to creative iframes.
-// Notably absent:
-//   allow-scripts, allow-same-origin — prevent JS execution and same-origin
-//     access, which are the primary attack vectors for malicious creatives.
-//   allow-forms — server-side sanitization strips <form> elements, so form
-//     submission from creatives is not a supported use case. Omitting this token
-//     is consistent with that server-side policy and reduces the attack surface.
+// Ad creatives routinely contain scripts for tracking, click handling, and
+// viewability measurement, so allow-scripts and allow-same-origin are required
+// for creatives to render correctly. Server-side sanitization is the primary
+// defense against malicious markup; the sandbox provides defense-in-depth.
 const CREATIVE_SANDBOX_TOKENS = [
+  'allow-forms',
   'allow-popups',
   'allow-popups-to-escape-sandbox',
+  'allow-same-origin',
+  'allow-scripts',
   'allow-top-navigation-by-user-activation',
 ] as const;
 
diff --git a/crates/js/lib/test/core/render.test.ts b/crates/js/lib/test/core/render.test.ts
index 5bdb3a81..a81486cf 100644
--- a/crates/js/lib/test/core/render.test.ts
+++ b/crates/js/lib/test/core/render.test.ts
@@ -27,12 +27,12 @@ describe('render', () => {
     expect(iframe.srcdoc).toContain('<span>ad</span>');
     expect(div.querySelector('iframe')).toBe(iframe);
     const sandbox = iframe.getAttribute('sandbox') ?? '';
-    expect(sandbox).not.toContain('allow-forms');
+    expect(sandbox).toContain('allow-forms');
     expect(sandbox).toContain('allow-popups');
     expect(sandbox).toContain('allow-popups-to-escape-sandbox');
     expect(sandbox).toContain('allow-top-navigation-by-user-activation');
-    expect(sandbox).not.toContain('allow-same-origin');
-    expect(sandbox).not.toContain('allow-scripts');
+    expect(sandbox).toContain('allow-same-origin');
+    expect(sandbox).toContain('allow-scripts');
   });
 
   it('preserves dollar sequences when building the creative document', async () => {
diff --git a/crates/trusted-server-core/src/creative.rs b/crates/trusted-server-core/src/creative.rs
index 45162d8c..245af0e1 100644
--- a/crates/trusted-server-core/src/creative.rs
+++ b/crates/trusted-server-core/src/creative.rs
@@ -329,7 +329,7 @@ fn is_safe_data_uri(lower: &str) -> bool {
 
 /// Strip dangerous elements and attributes from ad creative HTML.
 ///
-/// Removes elements that can execute code or exfiltrate data (`script`, `iframe`,
+/// Removes elements that can execute code or exfiltrate data (`script`,
 /// `object`, `embed`, `base`, `meta`, `form`, `link`, `style`, `noscript`) and strips `on*` event-handler
 /// attributes and dangerous URI schemes from all remaining elements:
 /// - `javascript:`, `vbscript:`
@@ -361,18 +361,17 @@ pub fn sanitize_creative_html(markup: &str) -> String {
         HtmlSettings {
             element_content_handlers: vec![
                 // Remove executable/dangerous elements along with their inner content.
-                // - <script>, <iframe>, <object>, <embed>: direct execution vectors.
+                // - <script>, <object>, <embed>: direct execution vectors.
                 // - <base>: rewrites all relative URLs, undermining the proxy rewriter.
                 // - <meta>: can trigger redirects (http-equiv=refresh) or inject CSP.
-                // - <form>: action/formaction can exfiltrate data; stripped to match the
-                //   iframe sandbox which omits allow-forms.
+                // - <form>: action/formaction can exfiltrate data.
                 // - <link>: external stylesheet/resource loading.
                 // - <style>: CSS expressions, @import, and url() data exfiltration.
                 // - <noscript>: rendered when scripts are disabled (always the case
                 //   inside a sandbox without allow-scripts); strip to prevent parser
                 //   differential attacks.
                 element!(
-                    "script, iframe, object, embed, base, meta, form, link, style, noscript",
+                    "script, object, embed, base, meta, form, link, style, noscript",
                     |el| {
                         el.remove();
                         Ok(())
@@ -454,10 +453,9 @@ pub fn sanitize_creative_html(markup: &str) -> String {
                     // NOTE: This uses simple substring matching on the lowercased value,
                     // which does not handle CSS escape sequences (e.g. `\65xpression(`)
                     // or comments (e.g. `expr/**/ession(`). That is acceptable: CSS
-                    // expression() is IE6-8 only and the iframe sandbox's absence of
-                    // allow-scripts prevents execution even if an obfuscated value were
-                    // to slip through. The sandbox is the primary mitigation; this check
-                    // is defense-in-depth for obvious patterns.
+                    // expression() is IE6-8 only, and downstream rendering still happens
+                    // inside a sandboxed iframe. This check is defense-in-depth for
+                    // obvious patterns.
                     if let Some(style) = el.get_attribute("style") {
                         let lower = style.to_ascii_lowercase();
                         if lower.contains("expression(")
@@ -1504,10 +1502,14 @@ mod tests {
     }
 
     #[test]
-    fn sanitize_removes_iframe_element() {
+    fn sanitize_preserves_iframe_element_and_src() {
         let html = r#"<div>ad</div><iframe src="https://evil.example/"></iframe>"#;
         let out = sanitize_creative_html(html);
-        assert!(!out.contains("<iframe"), "should remove iframe element");
+        assert!(out.contains("<iframe"), "should preserve iframe element");
+        assert!(
+            out.contains("https://evil.example/"),
+            "should preserve safe iframe src"
+        );
         assert!(out.contains("ad"), "should preserve safe content");
     }
 

From f02b538aabb1f58cdc2c732991e57b37368e679d Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Tue, 31 Mar 2026 17:04:56 -0500
Subject: [PATCH 17/36] Restrict EC generation to document navigations to
 prevent consent bypass

Subresource requests (fonts, images, CSS) may omit the Sec-GPC header,
causing the server to incorrectly generate ts-ec cookies when the user
has opted out via Global Privacy Control. Gate generate_if_needed() on
the request Accept header containing text/html so only navigations
trigger EC identity creation.
---
 crates/trusted-server-core/src/consent/mod.rs |  79 ++++++++-
 crates/trusted-server-core/src/http_util.rs   | 150 ++++++++++++++++++
 .../src/integrations/registry.rs              |  14 +-
 crates/trusted-server-core/src/publisher.rs   |  19 ++-
 4 files changed, 248 insertions(+), 14 deletions(-)

diff --git a/crates/trusted-server-core/src/consent/mod.rs b/crates/trusted-server-core/src/consent/mod.rs
index 4096c159..aed71281 100644
--- a/crates/trusted-server-core/src/consent/mod.rs
+++ b/crates/trusted-server-core/src/consent/mod.rs
@@ -502,13 +502,19 @@ pub fn allows_ec_creation(ctx: &ConsentContext) -> bool {
             if ctx.gpc {
                 return false;
             }
+            // When a CMP uses TCF in the US (e.g. Didomi), respect the
+            // TCF Purpose 1 decision — this is an explicit opt-in signal.
+            if let Some(tcf) = effective_tcf(ctx) {
+                return tcf.has_storage_consent();
+            }
             // Check US Privacy string for explicit opt-out.
             if let Some(usp) = &ctx.us_privacy {
-                usp.opt_out_sale != PrivacyFlag::Yes
-            } else {
-                // No opt-out signals present — allow under opt-out model.
-                true
+                return usp.opt_out_sale != PrivacyFlag::Yes;
             }
+            // Spec §6.1.1: "In regulated jurisdictions (GDPR, US state),
+            // consent cookies/headers must be present for
+            // allows_ec_creation() to return true." No signals = block.
+            false
         }
         jurisdiction::Jurisdiction::NonRegulated => true,
         // No geolocation data — cannot determine jurisdiction.
@@ -1021,7 +1027,7 @@ mod tests {
     }
 
     #[test]
-    fn ec_allowed_us_state_no_signals() {
+    fn ec_blocked_us_state_no_signals() {
         let ctx = ConsentContext {
             jurisdiction: Jurisdiction::UsState("CA".to_owned()),
             us_privacy: None,
@@ -1029,8 +1035,8 @@ mod tests {
             ..ConsentContext::default()
         };
         assert!(
-            allows_ec_creation(&ctx),
-            "US state + no opt-out signals should allow EC (opt-out model)"
+            !allows_ec_creation(&ctx),
+            "US state + no consent signals should block EC (spec §6.1.1: fail-closed)"
         );
     }
 
@@ -1094,4 +1100,63 @@ mod tests {
             "US Privacy with opt_out=N/A should allow EC"
         );
     }
+
+    #[test]
+    fn ec_allowed_us_state_tcf_with_storage_consent() {
+        let ctx = ConsentContext {
+            jurisdiction: Jurisdiction::UsState("TN".to_owned()),
+            tcf: Some(make_tcf_with_storage(true)),
+            ..ConsentContext::default()
+        };
+        assert!(
+            allows_ec_creation(&ctx),
+            "US state + TCF Purpose 1 consented should allow EC (Didomi-style CMP)"
+        );
+    }
+
+    #[test]
+    fn ec_blocked_us_state_tcf_without_storage_consent() {
+        let ctx = ConsentContext {
+            jurisdiction: Jurisdiction::UsState("TN".to_owned()),
+            tcf: Some(make_tcf_with_storage(false)),
+            ..ConsentContext::default()
+        };
+        assert!(
+            !allows_ec_creation(&ctx),
+            "US state + TCF Purpose 1 denied should block EC"
+        );
+    }
+
+    #[test]
+    fn ec_blocked_us_state_gpc_overrides_tcf() {
+        let ctx = ConsentContext {
+            jurisdiction: Jurisdiction::UsState("TN".to_owned()),
+            tcf: Some(make_tcf_with_storage(true)),
+            gpc: true,
+            ..ConsentContext::default()
+        };
+        assert!(
+            !allows_ec_creation(&ctx),
+            "GPC should block EC even when TCF grants storage consent in US state"
+        );
+    }
+
+    #[test]
+    fn ec_allowed_us_state_tcf_takes_priority_over_us_privacy() {
+        let ctx = ConsentContext {
+            jurisdiction: Jurisdiction::UsState("CA".to_owned()),
+            tcf: Some(make_tcf_with_storage(true)),
+            us_privacy: Some(UsPrivacy {
+                version: 1,
+                notice_given: PrivacyFlag::Yes,
+                opt_out_sale: PrivacyFlag::Yes,
+                lspa_covered: PrivacyFlag::NotApplicable,
+            }),
+            ..ConsentContext::default()
+        };
+        assert!(
+            allows_ec_creation(&ctx),
+            "TCF consent should take priority over US Privacy opt-out when both present"
+        );
+    }
 }
diff --git a/crates/trusted-server-core/src/http_util.rs b/crates/trusted-server-core/src/http_util.rs
index b38a0e4f..29093218 100644
--- a/crates/trusted-server-core/src/http_util.rs
+++ b/crates/trusted-server-core/src/http_util.rs
@@ -57,6 +57,40 @@ pub fn sanitize_forwarded_headers(req: &mut Request) {
     }
 }
 
+/// Returns `true` when the request looks like a top-level document navigation.
+///
+/// Uses [`Sec-Fetch-Dest`] when available (preferred — it is a forbidden
+/// header that cannot be spoofed by client-side JS). Falls back to checking
+/// the `Accept` header for an explicit `text/html` MIME type.
+///
+/// This distinction prevents EC identity cookies from being generated on
+/// subresource requests (fonts, images, scripts) where browsers may omit
+/// consent signals such as `Sec-GPC`.
+///
+/// [`Sec-Fetch-Dest`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Dest
+#[must_use]
+pub fn is_navigation_request(req: &Request) -> bool {
+    // Prefer Sec-Fetch-Dest (reliable, unspoofable by JS). All modern
+    // browsers send this header on every request.
+    if let Some(dest) = req
+        .get_header("sec-fetch-dest")
+        .and_then(|v| v.to_str().ok())
+    {
+        return dest.trim().eq_ignore_ascii_case("document");
+    }
+
+    // Fallback for clients that don't send Fetch Metadata headers:
+    // only match an explicit text/html (not */* which fonts also send).
+    req.get_header(header::ACCEPT)
+        .and_then(|v| v.to_str().ok())
+        .is_some_and(|accept| {
+            accept.split(',').any(|part| {
+                let mime = part.split(';').next().unwrap_or("").trim();
+                mime.eq_ignore_ascii_case("text/html")
+            })
+        })
+}
+
 /// Extracted request information for host rewriting.
 ///
 /// This struct captures the effective host and scheme from an incoming request.
@@ -677,4 +711,120 @@ mod tests {
             "Should filter dynamic x-ts-<partner_id> headers"
         );
     }
+
+    // -----------------------------------------------------------------------
+    // is_navigation_request
+    // -----------------------------------------------------------------------
+
+    #[test]
+    fn navigation_true_for_sec_fetch_dest_document() {
+        let req = Request::get("https://example.com").with_header("sec-fetch-dest", "document");
+        assert!(
+            is_navigation_request(&req),
+            "should detect Sec-Fetch-Dest: document as navigation"
+        );
+    }
+
+    #[test]
+    fn navigation_false_for_sec_fetch_dest_font() {
+        let req = Request::get("https://example.com/font.woff2")
+            .with_header("sec-fetch-dest", "font")
+            .with_header(header::ACCEPT, "*/*");
+        assert!(
+            !is_navigation_request(&req),
+            "should reject font even when Accept is */*"
+        );
+    }
+
+    #[test]
+    fn navigation_false_for_sec_fetch_dest_script() {
+        let req = Request::get("https://example.com/app.js")
+            .with_header("sec-fetch-dest", "script")
+            .with_header(header::ACCEPT, "*/*");
+        assert!(
+            !is_navigation_request(&req),
+            "should reject script even when Accept is */*"
+        );
+    }
+
+    #[test]
+    fn navigation_false_for_sec_fetch_dest_style() {
+        let req = Request::get("https://example.com/style.css")
+            .with_header("sec-fetch-dest", "style")
+            .with_header(header::ACCEPT, "text/css,*/*;q=0.1");
+        assert!(
+            !is_navigation_request(&req),
+            "should reject style subresource"
+        );
+    }
+
+    #[test]
+    fn navigation_false_for_sec_fetch_dest_image() {
+        let req = Request::get("https://example.com/logo.png")
+            .with_header("sec-fetch-dest", "image")
+            .with_header(header::ACCEPT, "image/webp,image/png,*/*;q=0.8");
+        assert!(
+            !is_navigation_request(&req),
+            "should reject image subresource"
+        );
+    }
+
+    #[test]
+    fn navigation_false_for_sec_fetch_dest_empty() {
+        let req = Request::get("https://example.com/api/data")
+            .with_header("sec-fetch-dest", "empty")
+            .with_header(header::ACCEPT, "*/*");
+        assert!(
+            !is_navigation_request(&req),
+            "should reject fetch/XHR requests (dest=empty)"
+        );
+    }
+
+    #[test]
+    fn navigation_sec_fetch_dest_case_insensitive() {
+        let req = Request::get("https://example.com").with_header("sec-fetch-dest", "Document");
+        assert!(
+            is_navigation_request(&req),
+            "should match Sec-Fetch-Dest case-insensitively"
+        );
+    }
+
+    #[test]
+    fn navigation_fallback_accept_text_html() {
+        let req = Request::get("https://example.com").with_header(
+            header::ACCEPT,
+            "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        );
+        assert!(
+            is_navigation_request(&req),
+            "should fall back to Accept: text/html when Sec-Fetch-Dest is absent"
+        );
+    }
+
+    #[test]
+    fn navigation_fallback_wildcard_only_is_false() {
+        let req = Request::get("https://example.com").with_header(header::ACCEPT, "*/*");
+        assert!(
+            !is_navigation_request(&req),
+            "should not treat bare */* as navigation in fallback path"
+        );
+    }
+
+    #[test]
+    fn navigation_false_when_no_headers() {
+        let req = Request::get("https://example.com/resource");
+        assert!(
+            !is_navigation_request(&req),
+            "should return false when no Accept or Sec-Fetch-Dest headers are present"
+        );
+    }
+
+    #[test]
+    fn navigation_fallback_accept_case_insensitive() {
+        let req = Request::get("https://example.com").with_header(header::ACCEPT, "TEXT/HTML");
+        assert!(
+            is_navigation_request(&req),
+            "should match text/html case-insensitively in fallback"
+        );
+    }
 }
diff --git a/crates/trusted-server-core/src/integrations/registry.rs b/crates/trusted-server-core/src/integrations/registry.rs
index 2c7de3bc..f5a17a5f 100644
--- a/crates/trusted-server-core/src/integrations/registry.rs
+++ b/crates/trusted-server-core/src/integrations/registry.rs
@@ -12,6 +12,7 @@ use crate::constants::HEADER_X_TS_EC;
 use crate::ec::kv::KvIdentityGraph;
 use crate::ec::EcContext;
 use crate::error::TrustedServerError;
+use crate::http_util::is_navigation_request;
 use crate::settings::Settings;
 
 /// Action returned by attribute rewriters to describe how the runtime should mutate the element.
@@ -658,8 +659,17 @@ impl IntegrationRegistry {
     ) -> Option<Result<Response, Report<TrustedServerError>>> {
         if let Some((proxy, _)) = self.find_route(method, path) {
             // Organic proxy handler: generate if needed (best effort).
-            if let Err(err) = ec_context.generate_if_needed(settings, kv) {
-                log::warn!("EC generation failed for integration proxy: {err:?}");
+            // Only generate for document navigations — subresource requests
+            // may lack consent signals such as the Sec-GPC header.
+            if is_navigation_request(&req) {
+                if let Err(err) = ec_context.generate_if_needed(settings, kv) {
+                    log::warn!("EC generation failed for integration proxy: {err:?}");
+                }
+            } else {
+                log::debug!(
+                    "EC generation skipped for integration proxy: non-document request (path={})",
+                    path,
+                );
             }
 
             // Set EC ID header on the request so integrations can read it.
diff --git a/crates/trusted-server-core/src/publisher.rs b/crates/trusted-server-core/src/publisher.rs
index 7cce461f..fa2119a4 100644
--- a/crates/trusted-server-core/src/publisher.rs
+++ b/crates/trusted-server-core/src/publisher.rs
@@ -7,7 +7,7 @@ use crate::constants::HEADER_X_COMPRESS_HINT;
 use crate::ec::kv::KvIdentityGraph;
 use crate::ec::EcContext;
 use crate::error::TrustedServerError;
-use crate::http_util::{serve_static_with_etag, RequestInfo};
+use crate::http_util::{is_navigation_request, serve_static_with_etag, RequestInfo};
 use crate::integrations::IntegrationRegistry;
 use crate::platform::RuntimeServices;
 use crate::rsc_flight::RscFlightUrlRewriter;
@@ -312,10 +312,19 @@ pub fn handle_publisher_request(
         req.get_header("x-forwarded-proto"),
     );
 
-    // Generate a new EC ID if none exists and consent allows it.
-    // This is an organic handler, so generation is permitted here.
-    if let Err(err) = ec_context.generate_if_needed(settings, kv) {
-        log::warn!("EC generation failed: {err:?}");
+    // Generate a new EC ID only for document navigations. Subresource
+    // requests (fonts, images, CSS) may lack consent signals such as the
+    // Sec-GPC header, so we skip generation to avoid setting identity
+    // cookies when the user's consent preference is unknown.
+    if is_navigation_request(&req) {
+        if let Err(err) = ec_context.generate_if_needed(settings, kv) {
+            log::warn!("EC generation failed: {err:?}");
+        }
+    } else {
+        log::debug!(
+            "EC generation skipped: non-document request (path={})",
+            req.get_path(),
+        );
     }
 
     let ec_allowed = ec_context.ec_allowed();

From bcca87de565861550c264013a963cbef10e02a90 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Wed, 1 Apr 2026 19:11:51 -0500
Subject: [PATCH 18/36] Migrate admin endpoints to /_ts/admin namespace

Move admin route matching and basic-auth coverage to /_ts/admin for a hard cutover, and align tests and docs so operational guidance matches runtime behavior.
---
 crates/integration-tests/tests/common/ec.rs   |  6 +--
 .../tests/frameworks/scenarios.rs             |  2 +-
 .../trusted-server-adapter-fastly/src/main.rs |  8 ++--
 .../trusted-server-core/src/auction/README.md |  6 +--
 crates/trusted-server-core/src/auth.rs        |  6 +--
 crates/trusted-server-core/src/ec/admin.rs    |  8 ++--
 crates/trusted-server-core/src/ec/partner.rs  |  2 +-
 .../src/integrations/google_tag_manager.rs    |  4 +-
 .../src/integrations/prebid.rs                |  2 +-
 .../src/request_signing/endpoints.rs          | 12 ++---
 crates/trusted-server-core/src/settings.rs    | 28 +++++------
 .../trusted-server-core/src/test_support.rs   |  2 +-
 docs/guide/api-reference.md                   | 16 +++----
 docs/guide/configuration.md                   | 10 ++--
 docs/guide/error-reference.md                 |  4 +-
 docs/guide/key-rotation.md                    | 22 ++++-----
 ...3-11-production-readiness-report-design.md |  6 +--
 .../2026-03-19-edgezero-migration-design.md   |  8 ++--
 .../specs/2026-03-24-ssc-prd-design.md        | 10 ++--
 .../2026-03-24-ssc-technical-spec-design.md   | 46 +++++++++----------
 trusted-server.toml                           |  3 +-
 21 files changed, 106 insertions(+), 105 deletions(-)

diff --git a/crates/integration-tests/tests/common/ec.rs b/crates/integration-tests/tests/common/ec.rs
index 1a002e56..428c06f9 100644
--- a/crates/integration-tests/tests/common/ec.rs
+++ b/crates/integration-tests/tests/common/ec.rs
@@ -181,11 +181,11 @@ impl EcTestClient {
 // Partner registration
 // ---------------------------------------------------------------------------
 
-/// Admin credentials matching `trusted-server.toml` `[[handlers]]` for `/admin`.
+/// Admin credentials matching `trusted-server.toml` `[[handlers]]` for `/_ts/admin`.
 const ADMIN_USER: &str = "admin";
 const ADMIN_PASS: &str = "changeme";
 
-/// Registers a test partner via `POST /admin/partners/register`.
+/// Registers a test partner via `POST /_ts/admin/partners/register`.
 pub fn register_test_partner(
     client: &EcTestClient,
     partner_id: &str,
@@ -202,7 +202,7 @@ pub fn register_test_partner(
     });
 
     let resp = client.post_json_with_basic_auth(
-        "/admin/partners/register",
+        "/_ts/admin/partners/register",
         &body,
         ADMIN_USER,
         ADMIN_PASS,
diff --git a/crates/integration-tests/tests/frameworks/scenarios.rs b/crates/integration-tests/tests/frameworks/scenarios.rs
index 3ee9f913..580f6abb 100644
--- a/crates/integration-tests/tests/frameworks/scenarios.rs
+++ b/crates/integration-tests/tests/frameworks/scenarios.rs
@@ -436,7 +436,7 @@ impl CustomScenario {
 ///
 /// These run against the Viceroy runtime directly without a frontend
 /// framework container — they exercise EC-specific endpoints (`/sync`,
-/// `/identify`, `/api/v1/sync`, `/admin/partners/register`).
+/// `/identify`, `/api/v1/sync`, `/_ts/admin/partners/register`).
 #[derive(Debug, Clone)]
 pub enum EcScenario {
     /// Full flow: organic request generates EC → pixel sync writes partner
diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 0e4f7867..121ed039 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -216,9 +216,11 @@ async fn route_request(
 
         // Admin endpoints
         // Keep in sync with Settings::ADMIN_ENDPOINTS in crates/trusted-server-core/src/settings.rs
-        (Method::POST, "/admin/keys/rotate") => (handle_rotate_key(settings, req), false),
-        (Method::POST, "/admin/keys/deactivate") => (handle_deactivate_key(settings, req), false),
-        (Method::POST, "/admin/partners/register") => (
+        (Method::POST, "/_ts/admin/keys/rotate") => (handle_rotate_key(settings, req), false),
+        (Method::POST, "/_ts/admin/keys/deactivate") => {
+            (handle_deactivate_key(settings, req), false)
+        }
+        (Method::POST, "/_ts/admin/partners/register") => (
             require_partner_store(settings).and_then(|store| handle_register_partner(&store, req)),
             false,
         ),
diff --git a/crates/trusted-server-core/src/auction/README.md b/crates/trusted-server-core/src/auction/README.md
index d6f4483a..332b3604 100644
--- a/crates/trusted-server-core/src/auction/README.md
+++ b/crates/trusted-server-core/src/auction/README.md
@@ -265,8 +265,8 @@ The trusted-server handles several types of routes defined in `crates/trusted-se
 | `/static/tsjs=*`          | GET    | `handle_tsjs_dynamic()`        | Serve tsjs library (Prebid.js alternative)       | 66   |
 | `/.well-known/ts.jwks.json` | GET  | `handle_jwks_endpoint()`       | Public key distribution for request signing      | 71   |
 | `/verify-signature`       | POST   | `handle_verify_signature()`    | Verify signed requests                           | 74   |
-| `/admin/keys/rotate`      | POST   | `handle_rotate_key()`          | Rotate signing keys (admin only)                 | 77   |
-| `/admin/keys/deactivate`  | POST   | `handle_deactivate_key()`      | Deactivate signing keys (admin only)             | 78   |
+| `/_ts/admin/keys/rotate`      | POST   | `handle_rotate_key()`          | Rotate signing keys (admin only)                 | 77   |
+| `/_ts/admin/keys/deactivate`  | POST   | `handle_deactivate_key()`      | Deactivate signing keys (admin only)             | 78   |
 | `/integrations/*`         | *      | Integration Registry           | Provider-specific endpoints (Prebid, etc.)       | 92   |
 | `*` (fallback)            | *      | `handle_publisher_request()`   | Proxy to publisher origin                        | 108  |
 
@@ -318,7 +318,7 @@ The integration registry checks if a route matches any registered integration ro
 #### 3. Route Priority
 Routes are matched in this order:
 1. **Exact top-level routes** (`/auction`, `/first-party/proxy`, etc.)
-2. **Admin routes** (`/admin/*`)
+2. **Admin routes** (`/_ts/admin/*`)
 3. **Integration routes** (`/integrations/*`)
 4. **Fallback to publisher origin** (all other paths)
 
diff --git a/crates/trusted-server-core/src/auth.rs b/crates/trusted-server-core/src/auth.rs
index 9ea918e8..ac98c313 100644
--- a/crates/trusted-server-core/src/auth.rs
+++ b/crates/trusted-server-core/src/auth.rs
@@ -215,7 +215,7 @@ mod tests {
     #[test]
     fn allow_admin_path_with_valid_credentials() {
         let settings = settings_with_handlers();
-        let mut req = Request::new(Method::POST, "https://example.com/admin/keys/rotate");
+        let mut req = Request::new(Method::POST, "https://example.com/_ts/admin/keys/rotate");
         let token = STANDARD.encode("admin:admin-pass");
         req.set_header(header::AUTHORIZATION, format!("Basic {token}"));
 
@@ -230,7 +230,7 @@ mod tests {
     #[test]
     fn challenge_admin_path_with_wrong_credentials() {
         let settings = settings_with_handlers();
-        let mut req = Request::new(Method::POST, "https://example.com/admin/keys/rotate");
+        let mut req = Request::new(Method::POST, "https://example.com/_ts/admin/keys/rotate");
         let token = STANDARD.encode("admin:wrong");
         req.set_header(header::AUTHORIZATION, format!("Basic {token}"));
 
@@ -243,7 +243,7 @@ mod tests {
     #[test]
     fn challenge_admin_path_with_missing_credentials() {
         let settings = settings_with_handlers();
-        let req = Request::new(Method::POST, "https://example.com/admin/keys/rotate");
+        let req = Request::new(Method::POST, "https://example.com/_ts/admin/keys/rotate");
 
         let response = enforce_basic_auth(&settings, &req)
             .expect("should evaluate auth")
diff --git a/crates/trusted-server-core/src/ec/admin.rs b/crates/trusted-server-core/src/ec/admin.rs
index ae30e3db..c8c8d223 100644
--- a/crates/trusted-server-core/src/ec/admin.rs
+++ b/crates/trusted-server-core/src/ec/admin.rs
@@ -1,6 +1,6 @@
 //! Admin endpoints for partner management.
 //!
-//! Provides `POST /admin/partners/register` for registering and updating
+//! Provides `POST /_ts/admin/partners/register` for registering and updating
 //! partner configurations. Authentication is handled by the `[[handlers]]`
 //! basic-auth layer before this code runs.
 
@@ -16,7 +16,7 @@ use super::partner::{
     hash_api_key, validate_partner_id, validate_pull_sync_config, PartnerRecord, PartnerStore,
 };
 
-/// Request body for `POST /admin/partners/register`.
+/// Request body for `POST /_ts/admin/partners/register`.
 ///
 /// Accepts `api_key` as plaintext — it is hashed before storage and
 /// never persisted in cleartext.
@@ -124,7 +124,7 @@ fn normalize_hostname_list(
     Ok(normalized_values)
 }
 
-/// Response body for `POST /admin/partners/register`.
+/// Response body for `POST /_ts/admin/partners/register`.
 ///
 /// Echoes key fields without exposing sensitive data (`api_key_hash`,
 /// `ts_pull_token`).
@@ -137,7 +137,7 @@ pub struct RegisterPartnerResponse {
     pub created: bool,
 }
 
-/// Handles `POST /admin/partners/register`.
+/// Handles `POST /_ts/admin/partners/register`.
 ///
 /// Registers a new partner or updates an existing one. Authentication is
 /// handled upstream by the `[[handlers]]` basic-auth layer.
diff --git a/crates/trusted-server-core/src/ec/partner.rs b/crates/trusted-server-core/src/ec/partner.rs
index b26e7a91..f7105eb6 100644
--- a/crates/trusted-server-core/src/ec/partner.rs
+++ b/crates/trusted-server-core/src/ec/partner.rs
@@ -61,7 +61,7 @@ fn partner_id_regex() -> Result<&'static Regex, String> {
 
 /// A registered partner configuration stored in the partner KV store.
 ///
-/// Created via `POST /admin/partners/register`. Used by pixel sync, batch
+/// Created via `POST /_ts/admin/partners/register`. Used by pixel sync, batch
 /// sync, pull sync, and auction bidstream decoration.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct PartnerRecord {
diff --git a/crates/trusted-server-core/src/integrations/google_tag_manager.rs b/crates/trusted-server-core/src/integrations/google_tag_manager.rs
index 301d0eca..36ef74f3 100644
--- a/crates/trusted-server-core/src/integrations/google_tag_manager.rs
+++ b/crates/trusted-server-core/src/integrations/google_tag_manager.rs
@@ -1305,7 +1305,7 @@ j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
     fn test_config_parsing() {
         let toml_str = r#"
 [[handlers]]
-path = "^/admin"
+path = "^/_ts/admin"
 username = "admin"
 password = "admin-pass"
 
@@ -1338,7 +1338,7 @@ upstream_url = "https://custom.gtm.example"
     fn test_config_defaults() {
         let toml_str = r#"
 [[handlers]]
-path = "^/admin"
+path = "^/_ts/admin"
 username = "admin"
 password = "admin-pass"
 
diff --git a/crates/trusted-server-core/src/integrations/prebid.rs b/crates/trusted-server-core/src/integrations/prebid.rs
index a786af55..890cf677 100644
--- a/crates/trusted-server-core/src/integrations/prebid.rs
+++ b/crates/trusted-server-core/src/integrations/prebid.rs
@@ -1409,7 +1409,7 @@ mod tests {
     /// Shared TOML prefix for config-parsing tests (publisher + ec sections).
     const TOML_BASE: &str = r#"
 [[handlers]]
-path = "^/admin"
+path = "^/_ts/admin"
 username = "admin"
 password = "admin-pass"
 
diff --git a/crates/trusted-server-core/src/request_signing/endpoints.rs b/crates/trusted-server-core/src/request_signing/endpoints.rs
index 3b14317e..9b4b957e 100644
--- a/crates/trusted-server-core/src/request_signing/endpoints.rs
+++ b/crates/trusted-server-core/src/request_signing/endpoints.rs
@@ -473,7 +473,7 @@ mod tests {
     #[test]
     fn test_handle_rotate_key_with_empty_body() {
         let settings = crate::test_support::tests::create_test_settings();
-        let req = Request::new(Method::POST, "https://test.com/admin/keys/rotate");
+        let req = Request::new(Method::POST, "https://test.com/_ts/admin/keys/rotate");
 
         let result = handle_rotate_key(&settings, req);
         match result {
@@ -500,7 +500,7 @@ mod tests {
         };
 
         let body_json = serde_json::to_string(&req_body).expect("should serialize rotate request");
-        let mut req = Request::new(Method::POST, "https://test.com/admin/keys/rotate");
+        let mut req = Request::new(Method::POST, "https://test.com/_ts/admin/keys/rotate");
         req.set_body(body_json);
 
         let result = handle_rotate_key(&settings, req);
@@ -522,7 +522,7 @@ mod tests {
     #[test]
     fn test_handle_rotate_key_invalid_json() {
         let settings = crate::test_support::tests::create_test_settings();
-        let mut req = Request::new(Method::POST, "https://test.com/admin/keys/rotate");
+        let mut req = Request::new(Method::POST, "https://test.com/_ts/admin/keys/rotate");
         req.set_body("invalid json");
 
         let result = handle_rotate_key(&settings, req);
@@ -540,7 +540,7 @@ mod tests {
 
         let body_json =
             serde_json::to_string(&req_body).expect("should serialize deactivate request");
-        let mut req = Request::new(Method::POST, "https://test.com/admin/keys/deactivate");
+        let mut req = Request::new(Method::POST, "https://test.com/_ts/admin/keys/deactivate");
         req.set_body(body_json);
 
         let result = handle_deactivate_key(&settings, req);
@@ -570,7 +570,7 @@ mod tests {
 
         let body_json =
             serde_json::to_string(&req_body).expect("should serialize deactivate request");
-        let mut req = Request::new(Method::POST, "https://test.com/admin/keys/deactivate");
+        let mut req = Request::new(Method::POST, "https://test.com/_ts/admin/keys/deactivate");
         req.set_body(body_json);
 
         let result = handle_deactivate_key(&settings, req);
@@ -592,7 +592,7 @@ mod tests {
     #[test]
     fn test_handle_deactivate_key_invalid_json() {
         let settings = crate::test_support::tests::create_test_settings();
-        let mut req = Request::new(Method::POST, "https://test.com/admin/keys/deactivate");
+        let mut req = Request::new(Method::POST, "https://test.com/_ts/admin/keys/deactivate");
         req.set_body("invalid json");
 
         let result = handle_deactivate_key(&settings, req);
diff --git a/crates/trusted-server-core/src/settings.rs b/crates/trusted-server-core/src/settings.rs
index 3951f991..888b19d0 100644
--- a/crates/trusted-server-core/src/settings.rs
+++ b/crates/trusted-server-core/src/settings.rs
@@ -595,9 +595,9 @@ impl Settings {
     /// Update [`ADMIN_ENDPOINTS`](Self::ADMIN_ENDPOINTS) when adding new
     /// admin routes to `crates/trusted-server-adapter-fastly/src/main.rs`.
     pub(crate) const ADMIN_ENDPOINTS: &[&str] = &[
-        "/admin/keys/rotate",
-        "/admin/keys/deactivate",
-        "/admin/partners/register",
+        "/_ts/admin/keys/rotate",
+        "/_ts/admin/keys/deactivate",
+        "/_ts/admin/partners/register",
     ];
 
     /// Returns admin endpoint paths that no configured handler covers.
@@ -642,7 +642,7 @@ impl Settings {
         Err(Report::new(TrustedServerError::Configuration {
             message: format!(
                 "No handler covers admin endpoint(s): {}. \
-                 Add a [[handlers]] entry with a path regex matching /admin/ \
+                 Add a [[handlers]] entry with a path regex matching /_ts/admin/ \
                  to protect admin access.",
                 uncovered.join(", ")
             ),
@@ -1163,7 +1163,7 @@ mod tests {
                 (path_key_0, Some("^/env-handler")),
                 (username_key_0, Some("env-user")),
                 (password_key_0, Some("env-pass")),
-                (path_key_1, Some("^/admin")),
+                (path_key_1, Some("^/_ts/admin")),
                 (username_key_1, Some("admin")),
                 (password_key_1, Some("admin-pass")),
             ],
@@ -1908,9 +1908,9 @@ mod tests {
         assert_eq!(
             uncovered,
             vec![
-                "/admin/keys/rotate",
-                "/admin/keys/deactivate",
-                "/admin/partners/register",
+                "/_ts/admin/keys/rotate",
+                "/_ts/admin/keys/deactivate",
+                "/_ts/admin/partners/register",
             ],
             "should report all admin endpoints as uncovered"
         );
@@ -1924,7 +1924,7 @@ mod tests {
             .expect("should check admin coverage");
         assert!(
             uncovered.is_empty(),
-            "should report no uncovered admin endpoints when handler covers /admin"
+            "should report no uncovered admin endpoints when handler covers /_ts/admin"
         );
     }
 
@@ -1933,7 +1933,7 @@ mod tests {
         let toml_str = settings_str_without_admin_handler()
             + r#"
             [[handlers]]
-            path = "^/admin/keys/rotate$"
+            path = "^/_ts/admin/keys/rotate$"
             username = "admin"
             password = "secret"
             "#;
@@ -1945,7 +1945,7 @@ mod tests {
             .expect("should check admin coverage");
         assert_eq!(
             uncovered,
-            vec!["/admin/keys/deactivate", "/admin/partners/register"],
+            vec!["/_ts/admin/keys/deactivate", "/_ts/admin/partners/register"],
             "should detect endpoints not covered by the rotate-only handler"
         );
     }
@@ -2016,9 +2016,9 @@ mod tests {
             .lines()
             .filter_map(|line| {
                 let trimmed = line.trim();
-                // Match arms look like: (Method::POST, "/admin/...") => ...
-                if trimmed.starts_with('(') && trimmed.contains("\"/admin/") {
-                    let start = trimmed.find("\"/admin/")?;
+                // Match arms look like: (Method::POST, "/_ts/admin/...") => ...
+                if trimmed.starts_with('(') && trimmed.contains("\"/_ts/admin/") {
+                    let start = trimmed.find("\"/_ts/admin/")?;
                     let rest = &trimmed[start + 1..];
                     let end = rest.find('"')?;
                     Some(&rest[..end])
diff --git a/crates/trusted-server-core/src/test_support.rs b/crates/trusted-server-core/src/test_support.rs
index 2fe0534b..77b65b12 100644
--- a/crates/trusted-server-core/src/test_support.rs
+++ b/crates/trusted-server-core/src/test_support.rs
@@ -15,7 +15,7 @@ pub mod tests {
             password = "pass"
 
             [[handlers]]
-            path = "^/admin"
+            path = "^/_ts/admin"
             username = "admin"
             password = "admin-pass"
 
diff --git a/docs/guide/api-reference.md b/docs/guide/api-reference.md
index 880efc83..7bcafd72 100644
--- a/docs/guide/api-reference.md
+++ b/docs/guide/api-reference.md
@@ -329,7 +329,7 @@ curl -X POST https://edge.example.com/verify-signature \
 
 ---
 
-### POST /admin/keys/rotate
+### POST /_ts/admin/keys/rotate
 
 Generates and activates a new signing key.
 
@@ -359,7 +359,7 @@ If omitted, auto-generates date-based ID (e.g., `ts-2025-01-15-A`).
 **Example:**
 
 ```bash
-curl -X POST https://edge.example.com/admin/keys/rotate \
+curl -X POST https://edge.example.com/_ts/admin/keys/rotate \
   -u admin:password \
   -H "Content-Type: application/json"
 ```
@@ -374,7 +374,7 @@ See [Key Rotation Guide](./key-rotation.md) for workflow details.
 
 ---
 
-### POST /admin/keys/deactivate
+### POST /_ts/admin/keys/deactivate
 
 Deactivates or deletes a signing key.
 
@@ -407,7 +407,7 @@ Deactivates or deletes a signing key.
 **Example:**
 
 ```bash
-curl -X POST https://edge.example.com/admin/keys/deactivate \
+curl -X POST https://edge.example.com/_ts/admin/keys/deactivate \
   -u admin:password \
   -H "Content-Type: application/json" \
   -d '{"kid":"ts-2025-01-14-A","delete":true}'
@@ -588,7 +588,7 @@ Endpoints under protected paths require HTTP Basic Authentication:
 
 ```toml
 [[handlers]]
-path = "^/admin"
+path = "^/_ts/admin"
 username = "admin"
 password = "secure-password"
 ```
@@ -596,13 +596,13 @@ password = "secure-password"
 **Usage:**
 
 ```bash
-curl -u admin:secure-password https://edge.example.com/admin/keys/rotate
+curl -u admin:secure-password https://edge.example.com/_ts/admin/keys/rotate
 ```
 
 **Protected Endpoints:**
 
-- `/admin/keys/rotate`
-- `/admin/keys/deactivate`
+- `/_ts/admin/keys/rotate`
+- `/_ts/admin/keys/deactivate`
 - Any paths matching configured `handlers` patterns
 
 ---
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index ffb13882..5910cf7d 100644
--- a/docs/guide/configuration.md
+++ b/docs/guide/configuration.md
@@ -445,7 +445,7 @@ Path-based HTTP Basic Authentication.
 ```toml
 # Single handler
 [[handlers]]
-path = "^/admin"
+path = "^/_ts/admin"
 username = "admin"
 password = "secure-password"
 
@@ -465,7 +465,7 @@ password = "api-pass"
 
 ```bash
 # Handler 0
-TRUSTED_SERVER__HANDLERS__0__PATH="^/admin"
+TRUSTED_SERVER__HANDLERS__0__PATH="^/_ts/admin"
 TRUSTED_SERVER__HANDLERS__0__USERNAME="admin"
 TRUSTED_SERVER__HANDLERS__0__PASSWORD="secure-password"
 
@@ -483,10 +483,10 @@ TRUSTED_SERVER__HANDLERS__1__PASSWORD="api-pass"
 
 ```toml
 # Exact path
-path = "^/admin$"  # Only /admin
+path = "^/_ts/admin$"  # Only /_ts/admin
 
 # Prefix match
-path = "^/admin"   # /admin, /admin/users, /admin/settings
+path = "^/_ts/admin"   # /_ts/admin, /_ts/admin/users, /_ts/admin/settings
 
 # Multiple paths
 path = "^/(admin|secure|private)"
@@ -1015,7 +1015,7 @@ trusted-server.dev.toml      # Development overrides
 **"Invalid regex"**:
 
 - Handler `path` must be valid regex
-- Test pattern: `echo "^/admin" | grep -E "^/admin"`
+- Test pattern: `echo "^/_ts/admin" | grep -E "^/_ts/admin"`
 - Escape special characters: `\.`, `\$`, etc.
 
 **"Integration configuration could not be parsed"**:
diff --git a/docs/guide/error-reference.md b/docs/guide/error-reference.md
index 92d1a003..80f93522 100644
--- a/docs/guide/error-reference.md
+++ b/docs/guide/error-reference.md
@@ -404,7 +404,7 @@ Signing key not found: ts-2025-01-A
 3. Run key rotation to generate new key:
 
 ```bash
-curl -X POST https://edge.example.com/admin/keys/rotate \
+curl -X POST https://edge.example.com/_ts/admin/keys/rotate \
   -u admin:password
 ```
 
@@ -427,7 +427,7 @@ curl -X POST https://edge.example.com/admin/keys/rotate \
 1. Initialize keys using rotation endpoint:
 
 ```bash
-curl -X POST https://edge.example.com/admin/keys/rotate \
+curl -X POST https://edge.example.com/_ts/admin/keys/rotate \
   -u admin:password
 ```
 
diff --git a/docs/guide/key-rotation.md b/docs/guide/key-rotation.md
index d4467bc8..e7aaef50 100644
--- a/docs/guide/key-rotation.md
+++ b/docs/guide/key-rotation.md
@@ -240,14 +240,14 @@ You should see a JWKS response with your public keys.
 
 ### Using the Rotation Endpoint
 
-**Endpoint**: `POST /admin/keys/rotate`
+**Endpoint**: `POST /_ts/admin/keys/rotate`
 
 #### Automatic Key ID (Recommended)
 
 Let Trusted Server generate a date-based key ID:
 
 ```bash
-curl -X POST https://your-domain/admin/keys/rotate \
+curl -X POST https://your-domain/_ts/admin/keys/rotate \
   -H "Content-Type: application/json" \
   -d '{}'
 ```
@@ -276,7 +276,7 @@ curl -X POST https://your-domain/admin/keys/rotate \
 Specify a custom key identifier:
 
 ```bash
-curl -X POST https://your-domain/admin/keys/rotate \
+curl -X POST https://your-domain/_ts/admin/keys/rotate \
   -H "Content-Type: application/json" \
   -d '{"kid": "production-2024-q1"}'
 ```
@@ -356,14 +356,14 @@ Deactivate old keys after:
 
 ### Deactivation Endpoint
 
-**Endpoint**: `POST /admin/keys/deactivate`
+**Endpoint**: `POST /_ts/admin/keys/deactivate`
 
 #### Deactivate (Keep in Storage)
 
 Remove from active rotation but keep in storage:
 
 ```bash
-curl -X POST https://your-domain/admin/keys/deactivate \
+curl -X POST https://your-domain/_ts/admin/keys/deactivate \
   -H "Content-Type: application/json" \
   -d '{
     "kid": "ts-2024-01-15",
@@ -388,7 +388,7 @@ curl -X POST https://your-domain/admin/keys/deactivate \
 Remove from storage completely:
 
 ```bash
-curl -X POST https://your-domain/admin/keys/deactivate \
+curl -X POST https://your-domain/_ts/admin/keys/deactivate \
   -H "Content-Type: application/json" \
   -d '{
     "kid": "ts-2024-01-15",
@@ -476,14 +476,14 @@ Regular rotation on a fixed schedule:
 ```bash
 #!/bin/bash
 # Rotate signing keys
-curl -X POST https://your-domain/admin/keys/rotate
+curl -X POST https://your-domain/_ts/admin/keys/rotate
 
 # Wait 30 days grace period
 sleep $((30 * 24 * 60 * 60))
 
 # Deactivate old key
 OLD_KEY=$(date -d '90 days ago' +ts-%Y-%m-%d)
-curl -X POST https://your-domain/admin/keys/deactivate \
+curl -X POST https://your-domain/_ts/admin/keys/deactivate \
   -d "{\"kid\": \"$OLD_KEY\", \"delete\": true}"
 ```
 
@@ -647,13 +647,13 @@ If a key is compromised:
 1. **Immediate**: Rotate to new key
 
 ```bash
-curl -X POST /admin/keys/rotate
+curl -X POST /_ts/admin/keys/rotate
 ```
 
 2. **Urgent**: Deactivate compromised key
 
 ```bash
-curl -X POST /admin/keys/deactivate \
+curl -X POST /_ts/admin/keys/deactivate \
   -d '{"kid": "compromised-key", "delete": false}'
 ```
 
@@ -664,7 +664,7 @@ curl -X POST /admin/keys/deactivate \
 5. **Cleanup**: Delete compromised key after investigation
 
 ```bash
-curl -X POST /admin/keys/deactivate \
+curl -X POST /_ts/admin/keys/deactivate \
   -d '{"kid": "compromised-key", "delete": true}'
 ```
 
diff --git a/docs/superpowers/specs/2026-03-11-production-readiness-report-design.md b/docs/superpowers/specs/2026-03-11-production-readiness-report-design.md
index 5203e5ff..e9bf5d16 100644
--- a/docs/superpowers/specs/2026-03-11-production-readiness-report-design.md
+++ b/docs/superpowers/specs/2026-03-11-production-readiness-report-design.md
@@ -51,10 +51,10 @@ match config.
 
 ### C-2: Admin endpoints unprotected unless handler regex covers them
 
-`/admin/keys/rotate` and `/admin/keys/deactivate` are always routed. The
+`/_ts/admin/keys/rotate` and `/_ts/admin/keys/deactivate` are always routed. The
 `enforce_basic_auth` gate only triggers for paths that match a configured
 `handlers[].path` regex. The default config (`^/secure`) does not cover
-`/admin/*`. An operator who doesn't add an explicit admin handler has
+`/_ts/admin/*`. An operator who doesn't add an explicit admin handler has
 **publicly-accessible key rotation/deletion endpoints**.
 
 **Refs:**
@@ -64,7 +64,7 @@ match config.
 - `settings.rs:381` -- `handlers` parsing
 - `trusted-server.toml:1` -- default handler only covers `^/secure`
 
-**Recommendation:** Either hard-require auth for `/admin/*` paths regardless of
+**Recommendation:** Either hard-require auth for `/_ts/admin/*` paths regardless of
 handler config, or validate at startup that an admin handler exists.
 
 ---
diff --git a/docs/superpowers/specs/2026-03-19-edgezero-migration-design.md b/docs/superpowers/specs/2026-03-19-edgezero-migration-design.md
index 0ae8c906..c48a947d 100644
--- a/docs/superpowers/specs/2026-03-19-edgezero-migration-design.md
+++ b/docs/superpowers/specs/2026-03-19-edgezero-migration-design.md
@@ -46,7 +46,7 @@ These decisions are finalized and reflected in this plan:
 2. **Migrate all integrations** including GPT and Google Tag Manager as
    first-class scope.
 3. **Admin key routes must be supported on all adapters** —
-   `/admin/keys/rotate` and `/admin/keys/deactivate` are required on Fastly,
+   `/_ts/admin/keys/rotate` and `/_ts/admin/keys/deactivate` are required on Fastly,
    Axum, and Cloudflare (no disabled-route mode).
 4. **Temporary Fastly compatibility adapter is required** — `compat.rs` lives in
    trusted-server during migration (created in PR 11, deleted in PR 15),
@@ -1357,7 +1357,7 @@ Changes:
 - Local development without Viceroy
 - Mock stores for local KV/config/secret
 - Implement required admin key routes
-  (`/admin/keys/rotate`, `/admin/keys/deactivate`) — core signing logic
+  (`/_ts/admin/keys/rotate`, `/_ts/admin/keys/deactivate`) — core signing logic
   composes the Axum store primitives (local config/secret providers)
 - Add `.env.dev` or local config file for Axum-specific **non-secret**
   settings only (listen address, mock store paths, log level).
@@ -1387,7 +1387,7 @@ Changes:
 - Construct `RuntimeServices` with Cloudflare-backed trait implementations
 - Wrangler configuration
 - Implement required admin key routes
-  (`/admin/keys/rotate`, `/admin/keys/deactivate`) — core signing logic
+  (`/_ts/admin/keys/rotate`, `/_ts/admin/keys/deactivate`) — core signing logic
   composes the Cloudflare store primitives (Workers API bindings)
 - Add `wrangler.toml` with bindings for KV, secrets, and config
 - Add integration tests: route smoke tests, admin key route tests,
@@ -1421,7 +1421,7 @@ Changes:
 
 - Route parity validation for all routes currently in `crates/trusted-server-adapter-fastly/src/main.rs`
   (`/static/tsjs=*`, `/.well-known/trusted-server.json`,
-  `/verify-signature`, `/admin/keys/rotate`, `/admin/keys/deactivate`,
+  `/verify-signature`, `/_ts/admin/keys/rotate`, `/_ts/admin/keys/deactivate`,
   `/auction`, `/first-party/*`, integration routes, and publisher fallback)
 - Cross-adapter behavior parity tests (Fastly vs Axum vs Cloudflare) for:
   response status/body, required headers, cookie behavior, and request-signing
diff --git a/docs/superpowers/specs/2026-03-24-ssc-prd-design.md b/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
index 7f88ef15..37a39728 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
@@ -69,7 +69,7 @@ Today, regular cookies don't suffice for publisher and partner needs. Additional
 - Build a server-side identity graph in Fastly KV Store that accumulates resolved partner IDs over time
 - Provide three KV write paths: real-time pixel sync redirects, S2S batch push from partners, and TS-initiated S2S pull from partner resolution endpoints
 - Expose two bidstream integration modes: header decoration (`/identify`) and full auction orchestration (`/auction`)
-- Expose a publisher-authenticated `/admin/partners/register` endpoint for partner provisioning without direct KV access
+- Expose a publisher-authenticated `/_ts/admin/partners/register` endpoint for partner provisioning without direct KV access
 
 ### Non-Goals
 
@@ -529,7 +529,7 @@ POST /api/v1/sync
 
 ### 10.3 Authentication
 
-Partners authenticate with a rotatable API key. Key rotation must not require redeploying the binary. Partner provisioning is handled via the `/admin/partners/register` endpoint (see Section 15, Open Questions).
+Partners authenticate with a rotatable API key. Key rotation must not require redeploying the binary. Partner provisioning is handled via the `/_ts/admin/partners/register` endpoint (see Section 15, Open Questions).
 
 ### 10.4 Request
 
@@ -933,7 +933,7 @@ The following capabilities must be configurable without redeploying the binary:
 - **Publisher passphrase** — the HMAC key used for EC hash generation; same value across all of the publisher's domains; shared with trusted partners to form an identity-federated consortium
 - **Identity graph store** — the KV store backing the EC hash → identity graph
 - **Partner registry store** — the KV store backing partner configuration and API key validation
-- **Partner records** — each partner's allowed sync domains, bidstream settings, pull sync configuration, and API credentials; managed via `/admin/partners/register` without redeployment
+- **Partner records** — each partner's allowed sync domains, bidstream settings, pull sync configuration, and API credentials; managed via `/_ts/admin/partners/register` without redeployment
 
 The exact configuration format (TOML keys, KV schema, JSON field names) is an engineering decision and will be documented in the technical design doc.
 
@@ -945,7 +945,7 @@ The following documentation changes are required alongside the EC feature:
 
 - **Rename SyntheticID → Edge Cookie** across the entire `docs/` GitHub Pages site. The underlying concept is the same but the product name changes.
 - **New integration guides**, one per customer type:
-  - Publisher (full TS): enabling EC in `trusted-server.toml`, partner onboarding via `/admin/partners/register`
+  - Publisher (full TS): enabling EC in `trusted-server.toml`, partner onboarding via `/_ts/admin/partners/register`
   - SSP: pixel sync integration guide, sync pixel URL format, callback handling, optional pull resolution endpoint
   - DSP: S2S batch API reference, authentication, conflict resolution behavior, optional pull resolution endpoint
   - Identity Provider: registering as a partner, `source_domain` and `openrtb_atype` configuration, sync patterns
@@ -959,7 +959,7 @@ The following documentation changes are required alongside the EC feature:
 
 | #   | Question                                                                                                                                                                                                                                                                                     | Owner       | Status                                                                      |
 | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------- |
-| 1   | Partner provisioning: TS will expose a `/admin/partners/register` endpoint authenticated at the publisher level (bearer token issued per publisher Fastly service), so publishers can onboard SSP/DSP partners without touching KV directly. Engineering to define the exact auth mechanism. | Engineering | **Resolved** — `/admin/partners/register` endpoint, publisher-authenticated |
+| 1   | Partner provisioning: TS will expose a `/_ts/admin/partners/register` endpoint authenticated at the publisher level (bearer token issued per publisher Fastly service), so publishers can onboard SSP/DSP partners without touching KV directly. Engineering to define the exact auth mechanism. | Engineering | **Resolved** — `/_ts/admin/partners/register` endpoint, publisher-authenticated |
 | 2   | Should TS Lite expose a `GET /health` endpoint so partners can programmatically verify their service is running and their partner config is active in KV?                                                                                                                                    | Product     | **N/A** — TS Lite deferred (see Section 5)                                  |
 
 ---
diff --git a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
index 90fd9a7f..4200ddc6 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
@@ -85,8 +85,8 @@ handle_publisher_request()     integration_registry.handle_proxy()
 calls ec_context.generate_if_needed()   calls ec_context.generate_if_needed()
 
 EC route handlers (GET /sync, GET /identify, POST /auction,
-POST /api/v1/sync, POST /admin/*) NEVER call generate_if_needed().
-`/identify`, `/auction`, `POST /api/v1/sync`, and `POST /admin/*`
+POST /api/v1/sync, POST /_ts/admin/*) NEVER call generate_if_needed().
+`/identify`, `/auction`, `POST /api/v1/sync`, and `POST /_ts/admin/*`
 use `EcContext` in read-only form. `GET /sync` is the one exception:
 it never bootstraps an EC, but it may replace `ec_context.consent`
 with a locally-decoded fallback consent context for that request only
@@ -421,7 +421,7 @@ ec_context.generate_if_needed(settings, &kv)    // best-effort — never 500s
           → set_ec_on_response()        (Set-Cookie + X-ts-ec on response)
 ```
 
-EC route handlers (`GET /sync`, `GET /identify`, `POST /api/v1/sync`, `POST /admin/*`) never call `generate_if_needed()`. `ec_finalize_response()` will still delete the cookie on those routes if consent is withdrawn — that is intentional.
+EC route handlers (`GET /sync`, `GET /identify`, `POST /api/v1/sync`, `POST /_ts/admin/*`) never call `generate_if_needed()`. `ec_finalize_response()` will still delete the cookie on those routes if consent is withdrawn — that is intentional.
 
 **Cookie write rule:** `Set-Cookie` is written in exactly two cases: (1) `ec_generated == true` (first-time generation), or (2) `cookie_ec_value.is_some()` (header/cookie mismatch — reconcile cookie to match the header-derived identity). There is no cookie refresh or Max-Age reset on ordinary returning users where cookie already matches. The PRD defers a blanket refresh-on-every-request strategy to a future iteration.
 
@@ -816,7 +816,7 @@ pub async fn handle_batch_sync(
 4. If no match or verification fails → `401 Unauthorized` with no body processing.
 5. If KV lookup fails (store unavailable) → `503 Service Unavailable`.
 
-Key rotation does not require binary redeployment — partners update via `/admin/partners/register`, which handles old API-key index cleanup (§13.1).
+Key rotation does not require binary redeployment — partners update via `/_ts/admin/partners/register`, which handles old API-key index cleanup (§13.1).
 
 ### 9.2.1 API-key rate limiting
 
@@ -951,7 +951,7 @@ fn pull_one_partner(
 
 A pull sync is dispatched for a partner when all of the following are true on a request:
 
-1. The request was routed to an **organic handler** (`handle_publisher_request` or `integration_registry.handle_proxy`). Pull sync never fires on EC route handlers (`/sync`, `/identify`, `/api/v1/sync`, `/admin/*`) or `/auction`. This matches the PRD requirement that pull calls must not happen during the pixel sync flow.
+1. The request was routed to an **organic handler** (`handle_publisher_request` or `integration_registry.handle_proxy`). Pull sync never fires on EC route handlers (`/sync`, `/identify`, `/api/v1/sync`, `/_ts/admin/*`) or `/auction`. This matches the PRD requirement that pull calls must not happen during the pixel sync flow.
 2. A valid EC is present (`ec_context.ec_hash().is_some()`). This includes an EC
    newly generated on the current organic request — pull sync may run immediately
    after first-page EC creation because the response cookie is flushed before the
@@ -1305,17 +1305,17 @@ impl PartnerStore {
 - `pull_enabled_partners()`: if a listed partner ID returns `None` from `get()`, skip it silently. If the fetched record has `pull_sync_enabled == false`, also skip it silently — that is a stale `_pull_enabled` index entry.
 - The `_pull_enabled` list is vulnerable to lost updates under concurrent registrations. This is accepted — partner registration is a low-frequency admin operation (not a hot path). If lost updates become an issue, a CAS-based read-modify-write can be added later.
 
-### 13.2 Admin endpoint (`POST /admin/partners/register`)
+### 13.2 Admin endpoint (`POST /_ts/admin/partners/register`)
 
 **Module:** `ec/admin.rs`
 
-> **Codebase invariant — requires test update:** `Settings::ADMIN_ENDPOINTS` in `settings.rs` lists routes that must be covered by a `[[handlers]]` Basic Auth entry. The existing test at `settings.rs:1504-1530` scans `main.rs` for **every** `/admin/` route string and asserts it appears in `ADMIN_ENDPOINTS`. When `/admin/partners/register` is added to `main.rs`, this test will fail.
+> **Codebase invariant — requires test update:** `Settings::ADMIN_ENDPOINTS` in `settings.rs` lists routes that must be covered by a `[[handlers]]` Basic Auth entry. The existing test at `settings.rs:1504-1530` scans `main.rs` for **every** `/_ts/admin/` route string and asserts it appears in `ADMIN_ENDPOINTS`. When `/_ts/admin/partners/register` is added to `main.rs`, this test will fail.
 >
 > **Required changes:**
 >
-> 1. Do **NOT** add `/admin/partners/register` to `ADMIN_ENDPOINTS` — it uses bearer-token-in-handler auth.
-> 2. Update the admin-route-scan test (`settings.rs:1504-1530`) to maintain an exclusion list of bearer-token-authed admin routes (e.g., `const BEARER_AUTH_ADMIN_ROUTES: &[&str] = &["/admin/partners/register"]`) and skip those when asserting `ADMIN_ENDPOINTS` coverage.
-> 3. Narrow the `[[handlers]]` pattern in `trusted-server.toml` from `"^/admin"` to `"^/admin/keys"` so that `/admin/partners/register` is not intercepted by `enforce_basic_auth()` before reaching its bearer-token handler.
+> 1. Do **NOT** add `/_ts/admin/partners/register` to `ADMIN_ENDPOINTS` — it uses bearer-token-in-handler auth.
+> 2. Update the admin-route-scan test (`settings.rs:1504-1530`) to maintain an exclusion list of bearer-token-authed admin routes (e.g., `const BEARER_AUTH_ADMIN_ROUTES: &[&str] = &["/_ts/admin/partners/register"]`) and skip those when asserting `ADMIN_ENDPOINTS` coverage.
+> 3. Narrow the `[[handlers]]` pattern in `trusted-server.toml` from `"^/_ts/admin"` to `"^/_ts/admin/keys"` so that `/_ts/admin/partners/register` is not intercepted by `enforce_basic_auth()` before reaching its bearer-token handler.
 
 ```rust
 pub async fn handle_register_partner(
@@ -1330,7 +1330,7 @@ Authentication: `Authorization: Bearer <token>` header, validated inside the han
 **Request:**
 
 ```
-POST /admin/partners/register
+POST /_ts/admin/partners/register
 Authorization: Bearer <admin_token>
 Content-Type: application/json
 
@@ -1407,7 +1407,7 @@ pub struct EdgeCookie {
     #[validate(length(min = 1))]
     pub partner_store: String,
 
-    /// SHA-256 hex of the publisher admin token for `POST /admin/partners/register`.
+    /// SHA-256 hex of the publisher admin token for `POST /_ts/admin/partners/register`.
     /// The plaintext token is provided in the `Authorization: Bearer` header;
     /// it is never stored in plaintext.
     #[validate(custom(function = EdgeCookie::validate_sha256_hex))]
@@ -1504,7 +1504,7 @@ The following EC headers must be added to `INTERNAL_HEADERS` in `constants.rs` t
 - `HEADER_X_TS_EIDS` (`x-ts-eids`)
 - `HEADER_X_TS_EC_CONSENT` (`x-ts-ec-consent`)
 - `HEADER_X_TS_EIDS_TRUNCATED` (`x-ts-eids-truncated`)
-- Dynamic `X-ts-<partner_id>` headers — these cannot be registered statically because partners are added at runtime via `/admin/partners/register`. The `INTERNAL_HEADERS` filter **must use prefix stripping** (`x-ts-` prefix match) rather than enumerating partner IDs. A startup snapshot would miss partners registered after deployment. The current filter in `http_util.rs` uses explicit header names — extend it to also strip any header matching the `x-ts-` prefix pattern.
+- Dynamic `X-ts-<partner_id>` headers — these cannot be registered statically because partners are added at runtime via `/_ts/admin/partners/register`. The `INTERNAL_HEADERS` filter **must use prefix stripping** (`x-ts-` prefix match) rather than enumerating partner IDs. A startup snapshot would miss partners registered after deployment. The current filter in `http_util.rs` uses explicit header names — extend it to also strip any header matching the `x-ts-` prefix pattern.
 
 ---
 
@@ -1557,10 +1557,10 @@ New routes added to `route_request()` in `crates/trusted-server-adapter-fastly/s
 (POST, "/api/v1/sync") → handle_batch_sync(settings, &kv, &partner_store, req)
 
 // Partner registration — publisher admin auth enforced in-handler (Bearer token)
-(POST, "/admin/partners/register") → handle_register_partner(settings, &partner_store, req)
+(POST, "/_ts/admin/partners/register") → handle_register_partner(settings, &partner_store, req)
 ```
 
-Route ordering: EC routes are inserted before the fallback `handle_publisher_request()`. The `/admin/partners/register` route uses bearer-token auth in-handler (not `[[handlers]]` Basic Auth). The current `trusted-server.toml` has `path = "^/admin"` which catches **all** `/admin/*` paths via `enforce_basic_auth()` before routing — this would block bearer-token requests to `/admin/partners/register`. **Required change:** narrow the existing `[[handlers]]` pattern from `"^/admin"` to `"^/admin/keys"` so it covers only `/admin/keys/rotate` and `/admin/keys/deactivate` (the routes in `Settings::ADMIN_ENDPOINTS`). `/admin/partners/register` then passes through `enforce_basic_auth()` unchallenged and reaches the bearer-token handler.
+Route ordering: EC routes are inserted before the fallback `handle_publisher_request()`. The `/_ts/admin/partners/register` route uses bearer-token auth in-handler (not `[[handlers]]` Basic Auth). The current `trusted-server.toml` has `path = "^/_ts/admin"` which catches **all** `/_ts/admin/*` paths via `enforce_basic_auth()` before routing — this would block bearer-token requests to `/_ts/admin/partners/register`. **Required change:** narrow the existing `[[handlers]]` pattern from `"^/_ts/admin"` to `"^/_ts/admin/keys"` so it covers only `/_ts/admin/keys/rotate` and `/_ts/admin/keys/deactivate` (the routes in `Settings::ADMIN_ENDPOINTS`). `/_ts/admin/partners/register` then passes through `enforce_basic_auth()` unchallenged and reaches the bearer-token handler.
 
 ### 17.1 EC integration in `main.rs`
 
@@ -1616,7 +1616,7 @@ async fn route_request(...) -> Result<(), Error> {
         (GET, "/identify")          => handle_identify(settings, &kv, &partner_store, &req, &ec_context).await,
         (OPTIONS, "/identify")      => cors_preflight_identify(settings, &req),
         (POST, "/api/v1/sync")      => handle_batch_sync(settings, &kv, &partner_store, req).await,
-        (POST, "/admin/partners/register") => handle_register_partner(settings, &partner_store, req).await,
+        (POST, "/_ts/admin/partners/register") => handle_register_partner(settings, &partner_store, req).await,
 
         // /auction — EC-read-only; never generates EC.
         // NOTE: handle_auction signature changes from (settings, orchestrator, req) to
@@ -1647,7 +1647,7 @@ async fn route_request(...) -> Result<(), Error> {
     response.send_to_client();
 
     // Background pull sync — organic routes only (§10.2). Never fires on /sync,
-    // /identify, /auction, /api/v1/sync, or /admin/* routes.
+    // /identify, /auction, /api/v1/sync, or /_ts/admin/* routes.
     // Fires outbound HTTP calls via send_async(), blocks on PendingRequest::wait().
     if is_organic {
         if let (Some(ip), Ok(pull_partners)) = (ec_context.client_ip, partner_store.pull_enabled_partners()) {
@@ -1712,7 +1712,7 @@ Suggested order to minimize risk and allow incremental testing. Each step should
 | 2    | `ec/finalize.rs`                                          | `ec_finalize_response()` (cookie write, deletion, tombstone, last_seen)                        |
 | 3    | `ec/cookie.rs`                                            | Cookie creation, deletion, response header                                                     |
 | 4    | `ec/kv.rs`                                                | `KvIdentityGraph` CRUD with CAS                                                                |
-| 5    | `ec/partner.rs` + `ec/admin.rs`                           | `PartnerStore`, `/admin/partners/register`                                                     |
+| 5    | `ec/partner.rs` + `ec/admin.rs`                           | `PartnerStore`, `/_ts/admin/partners/register`                                                     |
 | 6    | EC middleware in `main.rs`, `publisher.rs`, `registry.rs` | `EcContext::read_from_request()` pre-routing, `generate_if_needed()`, `ec_finalize_response()` |
 | 7    | `ec/sync_pixel.rs`                                        | `GET /sync` handler + route                                                                    |
 | 8    | `ec/identify.rs`                                          | `GET /identify` handler + route                                                                |
@@ -1892,7 +1892,7 @@ that operators use to onboard ID sync partners.
   records so stale `_pull_enabled` index entries do not dispatch disabled partners.
 - API key stored as SHA-256 hex; plaintext never written to KV.
 - `verify_api_key()` uses constant-time comparison.
-- `POST /admin/partners/register` validates `Authorization: Bearer <token>` inside
+- `POST /_ts/admin/partners/register` validates `Authorization: Bearer <token>` inside
   the handler against `settings.ec.admin_token_hash` (constant-time SHA-256 comparison).
   Returns `401` if missing or invalid — before any request body is read.
 - Admin endpoint validates: `pull_sync_url` hostname must be in
@@ -1900,13 +1900,13 @@ that operators use to onboard ID sync partners.
 - Returns `201 Created` on new partner or `200 OK` on update, with an explicit
   response DTO (see §13.2 step 6 — do NOT serialize full `PartnerRecord`).
   Returns `400` on validation failure; `503` on KV failure.
-- `/admin/partners/register` is **NOT** added to `Settings::ADMIN_ENDPOINTS` —
+- `/_ts/admin/partners/register` is **NOT** added to `Settings::ADMIN_ENDPOINTS` —
   it uses bearer-token-in-handler auth, not `[[handlers]]` Basic Auth.
 - The admin-route-scan test (`settings.rs:1504-1530`) must be updated to exclude
   bearer-token-authed routes from its `ADMIN_ENDPOINTS` assertion. Add an exclusion
   list (see §13.2 codebase invariant note).
 - The `[[handlers]]` pattern in `trusted-server.toml` must be narrowed from
-  `"^/admin"` to `"^/admin/keys"` (see §13.2).
+  `"^/_ts/admin"` to `"^/_ts/admin/keys"` (see §13.2).
 - Unit tests cover API key hash verification and record serialization.
 
 **Spec ref:** §13
@@ -1926,7 +1926,7 @@ Wire `EcContext` into the request pipeline following the two-phase model
 - `EcContext::read_from_request()` is called before the route match on every
   request, passed the existing `geo_info` (no duplicate geo header parsing).
 - EC route handlers receive `ec_context` without EC generation. `/identify`,
-  `/auction`, `/api/v1/sync`, and `/admin/*` use read-only `&EcContext` and
+  `/auction`, `/api/v1/sync`, and `/_ts/admin/*` use read-only `&EcContext` and
   never mutate it. **Exception:** `/sync` receives `&mut EcContext`; when the
   consent query-param fallback applies (`ec_context.consent.is_empty()`), it
   assigns the locally-decoded consent into `ec_context.consent` so that both
@@ -2100,7 +2100,7 @@ runtime). Only fires on organic routes (§10.2).
 - Dispatch runs after `send_to_client()` — does not add latency to the
   user-facing response. Uses `send_async()` + `PendingRequest::wait()` (blocking).
 - Only fires on organic routes (`handle_publisher_request`, `handle_proxy`) —
-  never on `/sync`, `/identify`, `/auction`, `/api/v1/sync`, or `/admin/*`.
+  never on `/sync`, `/identify`, `/auction`, `/api/v1/sync`, or `/_ts/admin/*`.
 - Unit tests cover trigger conditions, null/404 no-op, domain allowlist check,
   dispatch limit enforcement.
 
diff --git a/trusted-server.toml b/trusted-server.toml
index 3c3316e1..edece9e2 100644
--- a/trusted-server.toml
+++ b/trusted-server.toml
@@ -4,7 +4,7 @@ username = "user"
 password = "pass"
 
 [[handlers]]
-path = "^/admin"
+path = "^/_ts/admin"
 username = "admin"
 password = "changeme"
 
@@ -192,4 +192,3 @@ timeout_ms = 1000
 # query parameter name. Arrays are joined with commas.
 [integrations.adserver_mock.context_query_params]
 permutive_segments = "permutive"
-

From 2d39f60a0cf1f1640bf59e3703239b683946b4e3 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Thu, 2 Apr 2026 11:09:17 -0500
Subject: [PATCH 19/36] Migrate batch sync API to /_ts/api/v1/sync namespace

---
 crates/integration-tests/tests/common/ec.rs   |  8 ++---
 .../tests/frameworks/scenarios.rs             |  2 +-
 .../trusted-server-adapter-fastly/src/main.rs |  2 +-
 .../trusted-server-core/src/ec/batch_sync.rs  | 12 +++----
 crates/trusted-server-core/src/ec/kv.rs       |  2 +-
 crates/trusted-server-core/src/ec/mod.rs      |  2 +-
 .../trusted-server-core/src/ec/sync_pixel.rs  |  2 +-
 .../specs/2026-03-24-ssc-prd-design.md        | 12 +++----
 .../2026-03-24-ssc-technical-spec-design.md   | 36 +++++++++----------
 9 files changed, 39 insertions(+), 39 deletions(-)

diff --git a/crates/integration-tests/tests/common/ec.rs b/crates/integration-tests/tests/common/ec.rs
index 428c06f9..7d30740f 100644
--- a/crates/integration-tests/tests/common/ec.rs
+++ b/crates/integration-tests/tests/common/ec.rs
@@ -251,23 +251,23 @@ pub fn identify(client: &EcTestClient) -> TestResult<Response> {
 // Batch sync
 // ---------------------------------------------------------------------------
 
-/// Calls `POST /api/v1/sync` with bearer auth and the given mappings.
+/// Calls `POST /_ts/api/v1/sync` with bearer auth and the given mappings.
 pub fn batch_sync(
     client: &EcTestClient,
     api_key: &str,
     mappings: &[BatchMapping],
 ) -> TestResult<Response> {
     let body = serde_json::json!({ "mappings": mappings_to_json(mappings) });
-    client.post_json_with_bearer("/api/v1/sync", &body, api_key)
+    client.post_json_with_bearer("/_ts/api/v1/sync", &body, api_key)
 }
 
-/// Calls `POST /api/v1/sync` without any auth header.
+/// Calls `POST /_ts/api/v1/sync` without any auth header.
 pub fn batch_sync_no_auth(
     client: &EcTestClient,
     mappings: &[BatchMapping],
 ) -> TestResult<Response> {
     let body = serde_json::json!({ "mappings": mappings_to_json(mappings) });
-    client.post_json("/api/v1/sync", &body)
+    client.post_json("/_ts/api/v1/sync", &body)
 }
 
 /// Single mapping in a batch sync request.
diff --git a/crates/integration-tests/tests/frameworks/scenarios.rs b/crates/integration-tests/tests/frameworks/scenarios.rs
index 580f6abb..1d094189 100644
--- a/crates/integration-tests/tests/frameworks/scenarios.rs
+++ b/crates/integration-tests/tests/frameworks/scenarios.rs
@@ -436,7 +436,7 @@ impl CustomScenario {
 ///
 /// These run against the Viceroy runtime directly without a frontend
 /// framework container — they exercise EC-specific endpoints (`/sync`,
-/// `/identify`, `/api/v1/sync`, `/_ts/admin/partners/register`).
+/// `/identify`, `/_ts/api/v1/sync`, `/_ts/admin/partners/register`).
 #[derive(Debug, Clone)]
 pub enum EcScenario {
     /// Full flow: organic request generates EC → pixel sync writes partner
diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 121ed039..5e2b86de 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -134,7 +134,7 @@ async fn route_request(
 
     // S2S batch sync — uses Bearer auth (not EC cookies), so skip EC
     // context creation and the EC finalize middleware entirely.
-    if req.get_method() == Method::POST && req.get_path() == "/api/v1/sync" {
+    if req.get_method() == Method::POST && req.get_path() == "/_ts/api/v1/sync" {
         let mut response = require_identity_graph(settings)
             .and_then(|kv| {
                 require_partner_store(settings).and_then(|partner_store| {
diff --git a/crates/trusted-server-core/src/ec/batch_sync.rs b/crates/trusted-server-core/src/ec/batch_sync.rs
index 6c4da2be..0798f54d 100644
--- a/crates/trusted-server-core/src/ec/batch_sync.rs
+++ b/crates/trusted-server-core/src/ec/batch_sync.rs
@@ -1,4 +1,4 @@
-//! Server-to-server batch sync endpoint (`POST /api/v1/sync`).
+//! Server-to-server batch sync endpoint (`POST /_ts/api/v1/sync`).
 //!
 //! Partners send authenticated batch ID sync requests via Bearer token.
 //! Each mapping associates an `ec_hash` (the 64-char hex EC hash prefix)
@@ -124,7 +124,7 @@ fn parse_bearer_token(header_value: &str) -> Option<&str> {
 // Handler
 // ---------------------------------------------------------------------------
 
-/// Handles `POST /api/v1/sync`.
+/// Handles `POST /_ts/api/v1/sync`.
 ///
 /// # Errors
 ///
@@ -314,7 +314,7 @@ mod tests {
     #[test]
     fn authenticate_bearer_returns_none_for_missing_header() {
         let partner_store = PartnerStore::new("test_store");
-        let req = Request::new("POST", "https://edge.example.com/api/v1/sync");
+        let req = Request::new("POST", "https://edge.example.com/_ts/api/v1/sync");
 
         let result =
             authenticate_bearer(&partner_store, &req).expect("should not error on missing header");
@@ -324,7 +324,7 @@ mod tests {
     #[test]
     fn authenticate_bearer_returns_none_for_malformed_header() {
         let partner_store = PartnerStore::new("test_store");
-        let mut req = Request::new("POST", "https://edge.example.com/api/v1/sync");
+        let mut req = Request::new("POST", "https://edge.example.com/_ts/api/v1/sync");
         req.set_header("authorization", "Basic dXNlcjpwYXNz");
 
         let result = authenticate_bearer(&partner_store, &req)
@@ -338,7 +338,7 @@ mod tests {
     #[test]
     fn authenticate_bearer_returns_none_for_empty_token() {
         let partner_store = PartnerStore::new("test_store");
-        let mut req = Request::new("POST", "https://edge.example.com/api/v1/sync");
+        let mut req = Request::new("POST", "https://edge.example.com/_ts/api/v1/sync");
         req.set_header("authorization", "Bearer ");
 
         let result =
@@ -463,7 +463,7 @@ mod tests {
         let limiter = MockRateLimiter {
             should_exceed: false,
         };
-        let req = Request::new("POST", "https://edge.example.com/api/v1/sync");
+        let req = Request::new("POST", "https://edge.example.com/_ts/api/v1/sync");
 
         let response =
             handle_batch_sync(&kv, &partner_store, &limiter, req).expect("should return response");
diff --git a/crates/trusted-server-core/src/ec/kv.rs b/crates/trusted-server-core/src/ec/kv.rs
index fbcf77ef..f6815b1c 100644
--- a/crates/trusted-server-core/src/ec/kv.rs
+++ b/crates/trusted-server-core/src/ec/kv.rs
@@ -600,7 +600,7 @@ impl KvIdentityGraph {
     /// and a 24-hour TTL. Uses unconditional overwrite (no CAS) since the
     /// entry is being withdrawn regardless of concurrent state.
     ///
-    /// The tombstone allows batch sync clients (`POST /api/v1/sync`) to
+    /// The tombstone allows batch sync clients (`POST /_ts/api/v1/sync`) to
     /// distinguish `consent_withdrawn` from `ec_hash_not_found` for 24 hours.
     ///
     /// # Errors
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index 959824b0..c2593d68 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -23,7 +23,7 @@
 //! - [`sync_pixel`] — Pixel sync write endpoint (`GET /sync`)
 //! - [`identify`] — Browser identity read endpoint (`GET /identify`)
 //! - [`eids`] — Shared EID resolution and formatting helpers
-//! - [`batch_sync`] — S2S batch sync endpoint (`POST /api/v1/sync`)
+//! - [`batch_sync`] — S2S batch sync endpoint (`POST /_ts/api/v1/sync`)
 //! - [`pull_sync`] — Background pull-sync dispatcher for organic routes
 
 pub mod admin;
diff --git a/crates/trusted-server-core/src/ec/sync_pixel.rs b/crates/trusted-server-core/src/ec/sync_pixel.rs
index d968c151..3ac157b3 100644
--- a/crates/trusted-server-core/src/ec/sync_pixel.rs
+++ b/crates/trusted-server-core/src/ec/sync_pixel.rs
@@ -245,7 +245,7 @@ fn decode_query_fallback_consent(
 
 /// Rate limiter abstraction for sync endpoints.
 ///
-/// Used by both pixel sync (`/sync`) and batch sync (`/api/v1/sync`)
+/// Used by both pixel sync (`/sync`) and batch sync (`/_ts/api/v1/sync`)
 /// for per-partner request rate enforcement.
 pub trait RateLimiter {
     /// Returns `true` when the rate limit has been exceeded for the given key.
diff --git a/docs/superpowers/specs/2026-03-24-ssc-prd-design.md b/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
index 37a39728..9f5df9a4 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
@@ -118,7 +118,7 @@ TS Lite is a runtime configuration of the existing Trusted Server binary. It is
 | GTM integration                        | Enabled  | Disabled                |
 | `GET /sync`                            | Disabled | **Enabled**             |
 | `GET /identify`                        | Disabled | **Enabled**             |
-| `POST /api/v1/sync`                    | Disabled | **Enabled**             |
+| `POST /_ts/api/v1/sync`                    | Disabled | **Enabled**             |
 | `GET /.well-known/trusted-server.json` | Enabled  | Enabled                 |
 
 When a disabled route is requested, TS returns `404` with the header `X-ts-error: feature-disabled`.
@@ -343,7 +343,7 @@ The EC cookie is deterministic (derived from IP + publisher salt) and lives in t
 | EC cookie refresh (existing user) | Refresh the cookie. Skip the KV `last_seen` update silently. Log at `warn`.                                                       | Same as above — the cookie continues working. Stale `last_seen` is acceptable.                                                                                                                                                                                    |
 | `/sync` KV write                  | Redirect to `return` with `ts_synced=0&ts_reason=write_failed`.                                                                   | The browser redirect must not be blocked by KV availability. This case is already specified in Section 9.4.                                                                                                                                                       |
 | `/identify` KV read               | Return `200` with `ec` hash (from cookie) and `degraded: true`. Set `uids: {}` and `eids: []`.                                    | The EC hash is still valid and useful for attribution and analytics. Empty uids signal that enrichment is unavailable, not that the user has no synced partners. `degraded: true` lets callers distinguish transient KV failure from a genuinely unenriched user. |
-| S2S batch write (`/api/v1/sync`)  | Return `207` with all mappings rejected, `reason: "kv_unavailable"`.                                                              | The request was valid; the failure is infrastructure. Partners should retry the batch.                                                                                                                                                                            |
+| S2S batch write (`/_ts/api/v1/sync`)  | Return `207` with all mappings rejected, `reason: "kv_unavailable"`.                                                              | The request was valid; the failure is infrastructure. Partners should retry the batch.                                                                                                                                                                            |
 | S2S pull sync write (async)       | Discard the resolved uid. Log at `warn`. Retry will occur on the next qualifying request per the `pull_sync_ttl_sec` window.      | Async path — no user-facing impact.                                                                                                                                                                                                                               |
 | Consent withdrawal KV delete      | Expire the cookie immediately. Log the KV delete failure at `error` level. Retry the KV delete on the next request for this user. | Cookie deletion is the primary enforcement mechanism. KV delete failure must not block or delay the cookie expiry.                                                                                                                                                |
 
@@ -524,7 +524,7 @@ The S2S batch sync API allows partners to push ID mappings to Trusted Server in
 ### 10.2 Endpoint
 
 ```
-POST /api/v1/sync
+POST /_ts/api/v1/sync
 ```
 
 ### 10.3 Authentication
@@ -534,7 +534,7 @@ Partners authenticate with a rotatable API key. Key rotation must not require re
 ### 10.4 Request
 
 ```
-POST /api/v1/sync
+POST /_ts/api/v1/sync
 Content-Type: application/json
 Authorization: Bearer <api_key>
 
@@ -593,7 +593,7 @@ Before writing a mapping, Trusted Server checks the KV metadata for the given EC
 
 **Acceptance criteria:**
 
-- [ ] `POST /api/v1/sync` with a valid Bearer token and a batch of up to 1000 mappings returns a response within 5 seconds
+- [ ] `POST /_ts/api/v1/sync` with a valid Bearer token and a batch of up to 1000 mappings returns a response within 5 seconds
 - [ ] Accepted mappings are written to the corresponding KV identity graph entries within 1 second
 - [ ] Mappings for unknown `ec_hash` values are rejected with `ec_hash_not_found`
 - [ ] Mappings for users with withdrawn consent are rejected with `consent_withdrawn`
@@ -949,7 +949,7 @@ The following documentation changes are required alongside the EC feature:
   - SSP: pixel sync integration guide, sync pixel URL format, callback handling, optional pull resolution endpoint
   - DSP: S2S batch API reference, authentication, conflict resolution behavior, optional pull resolution endpoint
   - Identity Provider: registering as a partner, `source_domain` and `openrtb_atype` configuration, sync patterns
-- **API reference** for the four new endpoints: `GET /sync`, `GET /identify`, `POST /api/v1/sync`, and the partner-side pull resolution contract
+- **API reference** for the four new endpoints: `GET /sync`, `GET /identify`, `POST /_ts/api/v1/sync`, and the partner-side pull resolution contract
 - **Pull sync integration guide**: partner requirements for exposing a resolution endpoint, authentication, expected response shape, rate limit behavior
 - **Consent enforcement guide**: how TCF and GPP signals are read, precedence rules, what happens on withdrawal
 
diff --git a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
index 4200ddc6..57fdc919 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
@@ -17,7 +17,7 @@
 6. [Consent Enforcement](#6-consent-enforcement)
 7. [KV Store Identity Graph](#7-kv-store-identity-graph)
 8. [Pixel Sync Endpoint (`GET /sync`)](#8-pixel-sync-endpoint-get-sync)
-9. [S2S Batch Sync API (`POST /api/v1/sync`)](#9-s2s-batch-sync-api-post-apiv1sync)
+9. [S2S Batch Sync API (`POST /_ts/api/v1/sync`)](#9-s2s-batch-sync-api-post-apiv1sync)
 10. [S2S Pull Sync (TS-Initiated)](#10-s2s-pull-sync-ts-initiated)
 11. [Identity Resolution Endpoint (`GET /identify`)](#11-identity-resolution-endpoint-get-identify)
 12. [Bidstream Decoration (`/auction` Mode B)](#12-bidstream-decoration-auction-mode-b)
@@ -85,8 +85,8 @@ handle_publisher_request()     integration_registry.handle_proxy()
 calls ec_context.generate_if_needed()   calls ec_context.generate_if_needed()
 
 EC route handlers (GET /sync, GET /identify, POST /auction,
-POST /api/v1/sync, POST /_ts/admin/*) NEVER call generate_if_needed().
-`/identify`, `/auction`, `POST /api/v1/sync`, and `POST /_ts/admin/*`
+POST /_ts/api/v1/sync, POST /_ts/admin/*) NEVER call generate_if_needed().
+`/identify`, `/auction`, `POST /_ts/api/v1/sync`, and `POST /_ts/admin/*`
 use `EcContext` in read-only form. `GET /sync` is the one exception:
 it never bootstraps an EC, but it may replace `ec_context.consent`
 with a locally-decoded fallback consent context for that request only
@@ -421,7 +421,7 @@ ec_context.generate_if_needed(settings, &kv)    // best-effort — never 500s
           → set_ec_on_response()        (Set-Cookie + X-ts-ec on response)
 ```
 
-EC route handlers (`GET /sync`, `GET /identify`, `POST /api/v1/sync`, `POST /_ts/admin/*`) never call `generate_if_needed()`. `ec_finalize_response()` will still delete the cookie on those routes if consent is withdrawn — that is intentional.
+EC route handlers (`GET /sync`, `GET /identify`, `POST /_ts/api/v1/sync`, `POST /_ts/admin/*`) never call `generate_if_needed()`. `ec_finalize_response()` will still delete the cookie on those routes if consent is withdrawn — that is intentional.
 
 **Cookie write rule:** `Set-Cookie` is written in exactly two cases: (1) `ec_generated == true` (first-time generation), or (2) `cookie_ec_value.is_some()` (header/cookie mismatch — reconcile cookie to match the header-derived identity). There is no cookie refresh or Max-Age reset on ordinary returning users where cookie already matches. The PRD defers a blanket refresh-on-every-request strategy to a future iteration.
 
@@ -525,7 +525,7 @@ Two KV stores are used. Their names are configured in `trusted-server.toml`:
 { "ok": true, "country": "US", "v": 1 }
 ```
 
-The `ok` field in metadata is a **historical consent record for S2S consumers only** — it is set to `false` by `write_withdrawal_tombstone()` so that batch sync clients (`POST /api/v1/sync`) can return `consent_withdrawn` rather than `ec_hash_not_found` during the 24-hour tombstone TTL.
+The `ok` field in metadata is a **historical consent record for S2S consumers only** — it is set to `false` by `write_withdrawal_tombstone()` so that batch sync clients (`POST /_ts/api/v1/sync`) can return `consent_withdrawn` rather than `ec_hash_not_found` during the 24-hour tombstone TTL.
 
 **`consent.ok` is NOT used to make the withdrawal decision on the main request path.** Consent withdrawal is determined entirely from `allows_ec_creation(&ec_context.consent)` on the current request. When withdrawal is detected, the cookie is deleted and `write_withdrawal_tombstone()` is called in-path (setting `ok = false`, 24h TTL — see §6.2). Engineers must not add a KV read to the consent withdrawal hot path based on this field.
 
@@ -633,7 +633,7 @@ impl KvIdentityGraph {
     /// This recovery path is intentional: it materializes the graph later when
     /// the initial best-effort `create_or_revive()` on EC generation failed.
     /// Batch sync still performs its explicit existence/tombstone check before
-    /// calling this method, so `POST /api/v1/sync` retains its `ec_hash_not_found`
+    /// calling this method, so `POST /_ts/api/v1/sync` retains its `ec_hash_not_found`
     /// contract.
     pub fn upsert_partner_id(
         &self,
@@ -657,7 +657,7 @@ impl KvIdentityGraph {
     ///
     /// Instead of hard-deleting the KV entry, this overwrites it with
     /// `consent.ok = false`, clears all partner IDs, and sets a 24-hour TTL.
-    /// The tombstone allows batch sync clients (`POST /api/v1/sync`) to return
+    /// The tombstone allows batch sync clients (`POST /_ts/api/v1/sync`) to return
     /// `consent_withdrawn` rather than `ec_hash_not_found` for the tombstone TTL.
     ///
     /// After the 24-hour TTL expires, the entry is gone. Any subsequent `get()`
@@ -685,7 +685,7 @@ impl KvIdentityGraph {
 | EC cookie creation                 | KV error       | Set cookie. Skip KV create. Log `warn`.                                                        |
 | `/sync` KV write                   | KV error       | Redirect with `ts_synced=0&ts_reason=write_failed`.                                            |
 | `/identify` KV read                | KV error       | Return `200` with `ec` set, `degraded: true`, empty `uids`/`eids`.                             |
-| `POST /api/v1/sync`                | KV error       | Return `207` with all mappings rejected, `reason: "kv_unavailable"`.                           |
+| `POST /_ts/api/v1/sync`                | KV error       | Return `207` with all mappings rejected, `reason: "kv_unavailable"`.                           |
 | Pull sync KV write                 | KV error       | Discard uid. Log `warn`. Retry on next qualifying request.                                     |
 | Consent withdrawal tombstone write | KV error       | Delete cookie (primary enforcement). Log `error`. Next request: no cookie → no EC regenerated. |
 
@@ -793,7 +793,7 @@ Do not modify any other query parameters on the `return` URL.
 
 ---
 
-## 9. S2S Batch Sync API (`POST /api/v1/sync`)
+## 9. S2S Batch Sync API (`POST /_ts/api/v1/sync`)
 
 ### 9.1 Module: `ec/sync_batch.rs`
 
@@ -827,7 +827,7 @@ Exceeded → `429 Too Many Requests` with body `{ "error": "rate_limit_exceeded"
 ### 9.3 Request format
 
 ```
-POST /api/v1/sync
+POST /_ts/api/v1/sync
 Content-Type: application/json
 Authorization: Bearer <api_key>
 
@@ -951,7 +951,7 @@ fn pull_one_partner(
 
 A pull sync is dispatched for a partner when all of the following are true on a request:
 
-1. The request was routed to an **organic handler** (`handle_publisher_request` or `integration_registry.handle_proxy`). Pull sync never fires on EC route handlers (`/sync`, `/identify`, `/api/v1/sync`, `/_ts/admin/*`) or `/auction`. This matches the PRD requirement that pull calls must not happen during the pixel sync flow.
+1. The request was routed to an **organic handler** (`handle_publisher_request` or `integration_registry.handle_proxy`). Pull sync never fires on EC route handlers (`/sync`, `/identify`, `/_ts/api/v1/sync`, `/_ts/admin/*`) or `/auction`. This matches the PRD requirement that pull calls must not happen during the pixel sync flow.
 2. A valid EC is present (`ec_context.ec_hash().is_some()`). This includes an EC
    newly generated on the current organic request — pull sync may run immediately
    after first-page EC creation because the response cookie is flushed before the
@@ -1554,7 +1554,7 @@ New routes added to `route_request()` in `crates/trusted-server-adapter-fastly/s
 (OPTIONS, "/identify") → cors_preflight_identify(settings, &req)
 
 // S2S batch sync — partner API key auth (internal to handler)
-(POST, "/api/v1/sync") → handle_batch_sync(settings, &kv, &partner_store, req)
+(POST, "/_ts/api/v1/sync") → handle_batch_sync(settings, &kv, &partner_store, req)
 
 // Partner registration — publisher admin auth enforced in-handler (Bearer token)
 (POST, "/_ts/admin/partners/register") → handle_register_partner(settings, &partner_store, req)
@@ -1615,7 +1615,7 @@ async fn route_request(...) -> Result<(), Error> {
         (GET, "/sync")              => handle_sync(settings, &kv, &partner_store, &req, &mut ec_context).await,
         (GET, "/identify")          => handle_identify(settings, &kv, &partner_store, &req, &ec_context).await,
         (OPTIONS, "/identify")      => cors_preflight_identify(settings, &req),
-        (POST, "/api/v1/sync")      => handle_batch_sync(settings, &kv, &partner_store, req).await,
+        (POST, "/_ts/api/v1/sync")      => handle_batch_sync(settings, &kv, &partner_store, req).await,
         (POST, "/_ts/admin/partners/register") => handle_register_partner(settings, &partner_store, req).await,
 
         // /auction — EC-read-only; never generates EC.
@@ -1647,7 +1647,7 @@ async fn route_request(...) -> Result<(), Error> {
     response.send_to_client();
 
     // Background pull sync — organic routes only (§10.2). Never fires on /sync,
-    // /identify, /auction, /api/v1/sync, or /_ts/admin/* routes.
+    // /identify, /auction, /_ts/api/v1/sync, or /_ts/admin/* routes.
     // Fires outbound HTTP calls via send_async(), blocks on PendingRequest::wait().
     if is_organic {
         if let (Some(ip), Ok(pull_partners)) = (ec_context.client_ip, partner_store.pull_enabled_partners()) {
@@ -1716,7 +1716,7 @@ Suggested order to minimize risk and allow incremental testing. Each step should
 | 6    | EC middleware in `main.rs`, `publisher.rs`, `registry.rs` | `EcContext::read_from_request()` pre-routing, `generate_if_needed()`, `ec_finalize_response()` |
 | 7    | `ec/sync_pixel.rs`                                        | `GET /sync` handler + route                                                                    |
 | 8    | `ec/identify.rs`                                          | `GET /identify` handler + route                                                                |
-| 9    | `ec/sync_batch.rs`                                        | `POST /api/v1/sync` handler + route                                                            |
+| 9    | `ec/sync_batch.rs`                                        | `POST /_ts/api/v1/sync` handler + route                                                            |
 | 10   | `ec/pull_sync.rs`                                         | Background pull sync dispatch (blocking, after `send_to_client()`)                             |
 | 11   | Auction integration                                       | EC injection into `user.id`, `user.eids`, `user.consent`                                       |
 | 12   | End-to-end integration tests                              | Viceroy-based flow tests                                                                       |
@@ -1926,7 +1926,7 @@ Wire `EcContext` into the request pipeline following the two-phase model
 - `EcContext::read_from_request()` is called before the route match on every
   request, passed the existing `geo_info` (no duplicate geo header parsing).
 - EC route handlers receive `ec_context` without EC generation. `/identify`,
-  `/auction`, `/api/v1/sync`, and `/_ts/admin/*` use read-only `&EcContext` and
+  `/auction`, `/_ts/api/v1/sync`, and `/_ts/admin/*` use read-only `&EcContext` and
   never mutate it. **Exception:** `/sync` receives `&mut EcContext`; when the
   consent query-param fallback applies (`ec_context.consent.is_empty()`), it
   assigns the locally-decoded consent into `ec_context.consent` so that both
@@ -2042,7 +2042,7 @@ hash and synced partner UIDs for the current user.
 
 ---
 
-### Story 9 — S2S batch sync (`POST /api/v1/sync`)
+### Story 9 — S2S batch sync (`POST /_ts/api/v1/sync`)
 
 Implement the server-to-server batch sync endpoint for partners to bulk-write
 their UIDs against a list of EC hashes.
@@ -2100,7 +2100,7 @@ runtime). Only fires on organic routes (§10.2).
 - Dispatch runs after `send_to_client()` — does not add latency to the
   user-facing response. Uses `send_async()` + `PendingRequest::wait()` (blocking).
 - Only fires on organic routes (`handle_publisher_request`, `handle_proxy`) —
-  never on `/sync`, `/identify`, `/auction`, `/api/v1/sync`, or `/_ts/admin/*`.
+  never on `/sync`, `/identify`, `/auction`, `/_ts/api/v1/sync`, or `/_ts/admin/*`.
 - Unit tests cover trigger conditions, null/404 no-op, domain allowlist check,
   dispatch limit enforcement.
 

From f294b91aa74544fc6e591889c9103cd712204f7e Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Thu, 2 Apr 2026 11:51:12 -0500
Subject: [PATCH 20/36] Refresh EC header and cookie on returning requests

---
 crates/trusted-server-core/src/ec/finalize.rs | 40 +++++++++++++++++--
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/crates/trusted-server-core/src/ec/finalize.rs b/crates/trusted-server-core/src/ec/finalize.rs
index 712c6719..e3e91b73 100644
--- a/crates/trusted-server-core/src/ec/finalize.rs
+++ b/crates/trusted-server-core/src/ec/finalize.rs
@@ -75,10 +75,9 @@ pub fn ec_finalize_response(
             }
         }
 
-        // If header/cookie were mismatched, rewrite cookie to active EC value.
-        if ec_context.has_cookie_mismatch() {
-            set_ec_on_response(settings, ec_context, response);
-        }
+        // Always set the EC header and refresh the cookie so downstream
+        // consumers (Prebid, frontend JS) can read it on every response.
+        set_ec_on_response(settings, ec_context, response);
 
         return;
     }
@@ -297,6 +296,39 @@ mod tests {
         );
     }
 
+    #[test]
+    fn finalize_returning_user_refreshes_cookie_and_header_when_matching() {
+        let settings = create_test_settings();
+        let ec_id = sample_ec_id("MATCH01");
+        let ec_context = make_context(
+            Some(&ec_id),
+            Some(&ec_id),
+            true,
+            false,
+            Jurisdiction::NonRegulated,
+        );
+        let mut response = Response::new();
+
+        ec_finalize_response(&settings, None, &ec_context, None, &mut response);
+
+        let header = response
+            .get_header("x-ts-ec")
+            .expect("returning user should set x-ts-ec")
+            .to_str()
+            .expect("x-ts-ec should be utf-8");
+        assert_eq!(header, ec_id, "header should contain active EC");
+
+        let set_cookie = response
+            .get_header("set-cookie")
+            .expect("returning user should refresh cookie")
+            .to_str()
+            .expect("set-cookie should be utf-8");
+        assert!(
+            set_cookie.contains(&format!("ts-ec={ec_id}")),
+            "cookie should be refreshed to active EC"
+        );
+    }
+
     #[test]
     fn finalize_generated_ec_sets_cookie_and_header() {
         let settings = create_test_settings();

From 71fd00c30c6c7547b69aedfc65792e46f8a3a6a5 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Thu, 2 Apr 2026 12:28:51 -0500
Subject: [PATCH 21/36] Add end-to-end EC setup and API documentation

---
 docs/.vitepress/config.mts                    |   1 +
 docs/guide/api-reference.md                   | 120 ++++++++-
 docs/guide/ec-setup-guide.md                  | 247 ++++++++++++++++++
 docs/guide/edge-cookies.md                    |  11 +
 docs/guide/fastly.md                          |  38 +++
 docs/guide/getting-started.md                 |   1 +
 .../specs/2026-03-24-ssc-prd-design.md        |  26 +-
 .../2026-03-24-ssc-technical-spec-design.md   |  16 +-
 8 files changed, 435 insertions(+), 25 deletions(-)
 create mode 100644 docs/guide/ec-setup-guide.md

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index d66a820c..36ed84c5 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -78,6 +78,7 @@ export default withMermaid(
           text: 'Core Concepts',
           items: [
             { text: 'Edge Cookies', link: '/guide/edge-cookies' },
+            { text: 'EC Setup Guide', link: '/guide/ec-setup-guide' },
             { text: 'GDPR Compliance', link: '/guide/gdpr-compliance' },
             { text: 'Ad Serving', link: '/guide/ad-serving' },
             {
diff --git a/docs/guide/api-reference.md b/docs/guide/api-reference.md
index 7bcafd72..ee247fda 100644
--- a/docs/guide/api-reference.md
+++ b/docs/guide/api-reference.md
@@ -5,6 +5,7 @@ Quick reference for all Trusted Server HTTP endpoints.
 ## Endpoint Categories
 
 - [First-Party Endpoints](#first-party-endpoints) - Core ad serving and proxying
+- [Edge Cookie Endpoints](#edge-cookie-endpoints) - Identity sync and enrichment
 - [Request Signing](#request-signing-endpoints) - Cryptographic signing and key management
 - [TSJS Library](#tsjs-library-endpoint) - JavaScript library serving
 - [Integration Endpoints](#integration-endpoints) - Third-party service proxying
@@ -47,6 +48,121 @@ curl "https://edge.example.com/first-party/ad?slot=header-banner&w=728&h=90"
 
 ---
 
+## Edge Cookie Endpoints
+
+### POST /\_ts/admin/partners/register
+
+Registers or updates a partner used for EC sync and bidstream enrichment.
+
+**Auth:** Basic auth (admin credentials)
+
+**Request Body:**
+
+```json
+{
+  "id": "mocktioneer",
+  "name": "Mocktioneer SSP",
+  "api_key": "partner-secret-key",
+  "allowed_return_domains": ["formally-vital-lion.edgecompute.app"],
+  "source_domain": "formally-vital-lion.edgecompute.app",
+  "bidstream_enabled": true
+}
+```
+
+**Response:**
+
+- `201 Created` when newly created
+- `200 OK` when existing partner is updated
+
+---
+
+### GET /sync
+
+Browser pixel sync endpoint. Associates an EC ID with a partner UID.
+
+**Query Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `partner` | string | Yes | Registered partner id |
+| `uid` | string | Yes | Partner's user id |
+| `return` | string (URL) | Yes | Redirect URL after sync |
+
+**Request Requirements:**
+
+- `ts-ec` cookie present
+- valid consent signal (`euconsent-v2`) for consent-required jurisdictions
+
+**Response:**
+
+- `302 Found` redirect
+- Success: `Location: <return>?ts_synced=1`
+- Failure: `Location: <return>?ts_synced=0&ts_reason=<reason>`
+
+Common `ts_reason` values: `no_ec`, `no_consent`, `write_failed`, `rate_limited`.
+
+---
+
+### GET /identify
+
+Returns EC identity plus resolved partner IDs and EIDs for the current user.
+
+**Request:**
+
+- Uses `ts-ec` cookie and consent signals
+
+**Response (example):**
+
+```json
+{
+  "ec": "954d...e0c3.nZ1GxL",
+  "consent": "ok",
+  "degraded": false,
+  "uids": {
+    "mocktioneer": "mock-user-123"
+  },
+  "eids": [
+    {
+      "source": "formally-vital-lion.edgecompute.app",
+      "uids": [{ "id": "mock-user-123", "atype": 3 }]
+    }
+  ]
+}
+```
+
+---
+
+### POST /\_ts/api/v1/sync
+
+Server-to-server batch sync endpoint for writing EC hash to partner UID mappings.
+
+**Auth:** Bearer token (`Authorization: Bearer <partner-api-key>`)
+
+**Request Body:**
+
+```json
+{
+  "mappings": [
+    {
+      "ec_hash": "954d8e7398dd993f78e3875ca1ef7841249781240e913157c1f2d6a6c960e0c3",
+      "partner_uid": "mock-user-123",
+      "timestamp": 1775147300
+    }
+  ]
+}
+```
+
+**Response:**
+
+```json
+{
+  "accepted": 1,
+  "rejected": 0,
+  "errors": []
+}
+```
+
+---
+
 ### POST /third-party/ad
 
 Client-side auction endpoint for TSJS library.
@@ -329,7 +445,7 @@ curl -X POST https://edge.example.com/verify-signature \
 
 ---
 
-### POST /_ts/admin/keys/rotate
+### POST /\_ts/admin/keys/rotate
 
 Generates and activates a new signing key.
 
@@ -374,7 +490,7 @@ See [Key Rotation Guide](./key-rotation.md) for workflow details.
 
 ---
 
-### POST /_ts/admin/keys/deactivate
+### POST /\_ts/admin/keys/deactivate
 
 Deactivates or deletes a signing key.
 
diff --git a/docs/guide/ec-setup-guide.md b/docs/guide/ec-setup-guide.md
new file mode 100644
index 00000000..a5dbc385
--- /dev/null
+++ b/docs/guide/ec-setup-guide.md
@@ -0,0 +1,247 @@
+# Edge Cookie Setup Guide
+
+End-to-end setup and verification guide for Edge Cookie (EC) identity flows.
+
+This guide covers:
+
+1. Fastly store setup
+2. Partner registration
+3. Browser pixel sync (`/sync`)
+4. Server-to-server batch sync (`/_ts/api/v1/sync`)
+5. Identity verification (`/identify`)
+6. Auction bidstream verification (`/auction`)
+
+## Prerequisites
+
+- Trusted Server deployed and reachable (example: `https://getpurpose.ai`)
+- Admin credentials for `/_ts/admin/partners/register`
+- Fastly CLI authenticated (for store verification)
+- A valid TCF consent string (`euconsent-v2`) for consent-required requests
+
+## 1) Required Configuration
+
+Set EC configuration in `trusted-server.toml`:
+
+```toml
+[ec]
+passphrase = "your-secure-hmac-secret"
+ec_store = "ec_identity_store"
+partner_store = "ec_partner_store"
+```
+
+Required behavior assumptions:
+
+- `ec_store` and `partner_store` are linked to the active Fastly service version
+- Partner has `bidstream_enabled = true` if you want `user.ext.eids` in bidstream
+
+## 2) Configure Demo Variables
+
+```bash
+TS_BASE_URL="https://getpurpose.ai"
+MOCK_SSP_URL="https://formally-vital-lion.edgecompute.app"
+
+ADMIN_USER="admin"
+ADMIN_PASSWORD="<admin-password>"
+
+PARTNER_ID="mocktioneer"
+PARTNER_NAME="Mocktioneer SSP"
+PARTNER_API_KEY="test-batch-sync-key-2026"
+
+# Optional: use a real browser EC if already present
+EC_ID="<64hex.6chars>"
+EC_HASH="${EC_ID%%.*}"
+
+TCF_CONSENT="<euconsent-v2-string>"
+PARTNER_UID="mock-user-$(date +%s)"
+```
+
+## 3) Register Partner
+
+Endpoint: `POST /_ts/admin/partners/register`
+
+```bash
+curl -X POST "${TS_BASE_URL}/_ts/admin/partners/register" \
+  -u "${ADMIN_USER}:${ADMIN_PASSWORD}" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"id\": \"${PARTNER_ID}\",
+    \"name\": \"${PARTNER_NAME}\",
+    \"api_key\": \"${PARTNER_API_KEY}\",
+    \"allowed_return_domains\": [\"${MOCK_SSP_URL#https://}\"],
+    \"source_domain\": \"${MOCK_SSP_URL#https://}\",
+    \"bidstream_enabled\": true
+  }"
+```
+
+Expected:
+
+- `201` for new partner
+- `200` for update of existing partner
+
+## 4) Acquire or Reuse EC Cookie
+
+If you already have an EC from browser traffic, reuse it.
+
+Otherwise, attempt generation with consent:
+
+```bash
+curl -si "${TS_BASE_URL}/" \
+  -H "Cookie: euconsent-v2=${TCF_CONSENT}"
+```
+
+Look for:
+
+- `Set-Cookie: ts-ec=<64hex.6chars>`
+
+## 5) Pixel Sync (Browser-style)
+
+Endpoint: `GET /sync`
+
+```bash
+curl -si "${TS_BASE_URL}/sync?partner=${PARTNER_ID}&uid=${PARTNER_UID}&return=${MOCK_SSP_URL}/done" \
+  -H "Cookie: ts-ec=${EC_ID}; euconsent-v2=${TCF_CONSENT}"
+```
+
+Expected redirect result:
+
+- Success: `Location: ...?ts_synced=1`
+- Failure: `Location: ...?ts_synced=0&ts_reason=<reason>`
+
+Common `ts_reason` values:
+
+- `no_ec`
+- `no_consent`
+- `write_failed`
+- `rate_limited`
+
+## 6) Verify Identity
+
+Endpoint: `GET /identify`
+
+```bash
+curl -s "${TS_BASE_URL}/identify" \
+  -H "Cookie: ts-ec=${EC_ID}; euconsent-v2=${TCF_CONSENT}" | python3 -m json.tool
+```
+
+Expected shape:
+
+```json
+{
+  "ec": "<ec-id>",
+  "consent": "ok",
+  "degraded": false,
+  "uids": {
+    "mocktioneer": "mock-user-123"
+  },
+  "eids": [
+    {
+      "source": "formally-vital-lion.edgecompute.app",
+      "uids": [{ "id": "mock-user-123", "atype": 3 }]
+    }
+  ]
+}
+```
+
+## 7) Batch Sync (S2S)
+
+Endpoint: `POST /_ts/api/v1/sync`
+
+Important: request field is `ec_hash` (not `ssc_hash`).
+
+```bash
+BATCH_UID="${PARTNER_UID}-batch"
+NOW_TS="$(date +%s)"
+
+curl -X POST "${TS_BASE_URL}/_ts/api/v1/sync" \
+  -H "Authorization: Bearer ${PARTNER_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"mappings\": [{
+      \"ec_hash\": \"${EC_HASH}\",
+      \"partner_uid\": \"${BATCH_UID}\",
+      \"timestamp\": ${NOW_TS}
+    }]
+  }" | python3 -m json.tool
+```
+
+Expected:
+
+```json
+{
+  "accepted": 1,
+  "rejected": 0,
+  "errors": []
+}
+```
+
+## 8) Verify Auction Bidstream Enrichment
+
+Endpoint: `POST /auction`
+
+```bash
+curl -si -X POST "${TS_BASE_URL}/auction" \
+  -H "Cookie: ts-ec=${EC_ID}; euconsent-v2=${TCF_CONSENT}" \
+  -H "Content-Type: application/json" \
+  -d '{"adUnits":[{"code":"test","mediaTypes":{"banner":{"sizes":[[300,250]]}}}]}'
+```
+
+Check response headers:
+
+- `x-ts-ec`
+- `x-ts-ec-consent`
+- `x-ts-eids`
+- `Set-Cookie: ts-ec=...`
+
+Decode `x-ts-eids`:
+
+```bash
+echo "<x-ts-eids-base64-value>" | base64 -d | python3 -m json.tool
+```
+
+Expected decoded payload contains:
+
+- `source = formally-vital-lion.edgecompute.app`
+- `uids[0].id = <partner-uid>`
+
+## 9) Fastly KV Operational Checks
+
+List stores:
+
+```bash
+fastly kv-store list
+```
+
+Check service resource links for active version:
+
+```bash
+fastly resource-link list --service-id <service-id> --version <active-version>
+```
+
+Inspect partner entry:
+
+```bash
+fastly kv-store-entry get --store-id <partner-store-id> --key "${PARTNER_ID}"
+```
+
+Inspect EC identity entry:
+
+```bash
+fastly kv-store-entry get --store-id <identity-store-id> --key "${EC_HASH}"
+```
+
+If pixel sync returns `write_failed`, check whether KV entry has:
+
+- `consent.ok = false`
+
+## 10) Troubleshooting Quick Map
+
+| Symptom                                    | Likely Cause                           | Check                                     |
+| ------------------------------------------ | -------------------------------------- | ----------------------------------------- |
+| `invalid_token` on batch sync              | Wrong partner API key                  | Re-register partner with known API key    |
+| `missing field ec_hash`                    | Wrong request schema                   | Use `ec_hash` field                       |
+| `ts_reason=no_consent`                     | Missing/invalid consent cookie         | Include valid `euconsent-v2`              |
+| `ts_reason=write_failed`                   | KV write blocked (often consent state) | Inspect identity KV entry and store links |
+| `/identify` returns `{"consent":"denied"}` | No consent for current request         | Send consent cookie                       |
+| No `uids` in `/identify`                   | No successful sync yet                 | Run `/sync` or batch sync first           |
+
+See also: [Edge Cookies](/guide/edge-cookies), [Configuration](/guide/configuration), [API Reference](/guide/api-reference)
diff --git a/docs/guide/edge-cookies.md b/docs/guide/edge-cookies.md
index bdb7361e..917aa027 100644
--- a/docs/guide/edge-cookies.md
+++ b/docs/guide/edge-cookies.md
@@ -8,6 +8,8 @@ Edge Cookies (EC) are privacy-safe identifiers generated on a first site visit u
 
 Trusted Server surfaces the current EC ID via response headers and a first-party cookie. For the exact header and cookie names, see the [API Reference](/guide/api-reference).
 
+For full operational onboarding (partner registration, pixel sync, batch sync, identify, and auction verification), use the [EC Setup Guide](/guide/ec-setup-guide).
+
 ## How They Work
 
 ### HMAC-Based Generation
@@ -35,8 +37,17 @@ Configure EC settings in `trusted-server.toml`. See the full [Configuration Refe
 2. Rotate secret keys periodically
 3. Monitor ID collision rates
 
+## Runtime Behavior Notes
+
+- Returning requests with consent and an existing `ts-ec` receive both:
+  - `x-ts-ec` response header
+  - refreshed `Set-Cookie: ts-ec=...`
+- `/identify` is read-only and returns identity enrichment (`uids` and `eids`)
+- `/sync` and `/_ts/api/v1/sync` write mappings into the EC identity graph
+
 ## Next Steps
 
+- Follow the [EC Setup Guide](/guide/ec-setup-guide)
 - Learn about [GDPR Compliance](/guide/gdpr-compliance)
 - Configure [Ad Serving](/guide/ad-serving)
 - Learn about [Collective Sync](/guide/collective-sync) for cross-publisher data sharing details and diagrams
diff --git a/docs/guide/fastly.md b/docs/guide/fastly.md
index 2a1edd79..aa38c194 100644
--- a/docs/guide/fastly.md
+++ b/docs/guide/fastly.md
@@ -94,8 +94,46 @@ fastly secret-store create --name signing_keys
 
 Note the store IDs - you'll need them for your `trusted-server.toml` configuration.
 
+## Create EC KV Stores
+
+Edge Cookie flows require two KV stores:
+
+- Identity graph store (`ec_store`) - EC hash to partner IDs
+- Partner registry store (`partner_store`) - partner records and API-key hashes
+
+Create them:
+
+```bash
+fastly kv-store create --name ec_identity_store
+fastly kv-store create --name ec_partner_store
+```
+
+Configure in `trusted-server.toml`:
+
+```toml
+[ec]
+passphrase = "your-hmac-secret"
+ec_store = "ec_identity_store"
+partner_store = "ec_partner_store"
+```
+
+Verify stores exist:
+
+```bash
+fastly kv-store list
+```
+
+Verify stores are linked to your active service version:
+
+```bash
+fastly resource-link list --service-id <service-id> --version <active-version>
+```
+
+If EC sync returns `write_failed`, first check that both stores are present and linked to the active version.
+
 ## Next Steps
 
 - Return to [Getting Started](/guide/getting-started) to continue setup
 - See [Configuration](/guide/configuration) for detailed configuration options
+- See [EC Setup Guide](/guide/ec-setup-guide) for end-to-end EC verification
 - See [Request Signing](/guide/request-signing) for setting up cryptographic signing
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index ce4b328d..a4ed418c 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -72,5 +72,6 @@ fastly compute publish
 ## Next Steps
 
 - Learn about [Edge Cookies](/guide/edge-cookies)
+- Follow the [EC Setup Guide](/guide/ec-setup-guide)
 - Understand [GDPR Compliance](/guide/gdpr-compliance)
 - Configure [Ad Serving](/guide/ad-serving)
diff --git a/docs/superpowers/specs/2026-03-24-ssc-prd-design.md b/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
index 9f5df9a4..ec32196c 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
@@ -118,7 +118,7 @@ TS Lite is a runtime configuration of the existing Trusted Server binary. It is
 | GTM integration                        | Enabled  | Disabled                |
 | `GET /sync`                            | Disabled | **Enabled**             |
 | `GET /identify`                        | Disabled | **Enabled**             |
-| `POST /_ts/api/v1/sync`                    | Disabled | **Enabled**             |
+| `POST /_ts/api/v1/sync`                | Disabled | **Enabled**             |
 | `GET /.well-known/trusted-server.json` | Enabled  | Enabled                 |
 
 When a disabled route is requested, TS returns `404` with the header `X-ts-error: feature-disabled`.
@@ -337,15 +337,15 @@ The existing `counter_store` and `opid_store` settings (currently defined but un
 
 The EC cookie is deterministic (derived from IP + publisher salt) and lives in the browser. It does not depend on KV Store availability. KV Store holds identity enrichment only — resolved partner UIDs accumulated over time. The degraded behavior policy follows from this: **EC always works; enrichment degrades gracefully.**
 
-| Operation                         | KV unavailable or error                                                                                                           | Rationale                                                                                                                                                                                                                                                         |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| EC cookie creation                | Set the cookie. Skip the KV entry creation silently. Log the failure at `warn` level.                                             | The cookie is the identity anchor — it does not require KV. The KV entry will be created on the next request once KV recovers.                                                                                                                                    |
-| EC cookie refresh (existing user) | Refresh the cookie. Skip the KV `last_seen` update silently. Log at `warn`.                                                       | Same as above — the cookie continues working. Stale `last_seen` is acceptable.                                                                                                                                                                                    |
-| `/sync` KV write                  | Redirect to `return` with `ts_synced=0&ts_reason=write_failed`.                                                                   | The browser redirect must not be blocked by KV availability. This case is already specified in Section 9.4.                                                                                                                                                       |
-| `/identify` KV read               | Return `200` with `ec` hash (from cookie) and `degraded: true`. Set `uids: {}` and `eids: []`.                                    | The EC hash is still valid and useful for attribution and analytics. Empty uids signal that enrichment is unavailable, not that the user has no synced partners. `degraded: true` lets callers distinguish transient KV failure from a genuinely unenriched user. |
-| S2S batch write (`/_ts/api/v1/sync`)  | Return `207` with all mappings rejected, `reason: "kv_unavailable"`.                                                              | The request was valid; the failure is infrastructure. Partners should retry the batch.                                                                                                                                                                            |
-| S2S pull sync write (async)       | Discard the resolved uid. Log at `warn`. Retry will occur on the next qualifying request per the `pull_sync_ttl_sec` window.      | Async path — no user-facing impact.                                                                                                                                                                                                                               |
-| Consent withdrawal KV delete      | Expire the cookie immediately. Log the KV delete failure at `error` level. Retry the KV delete on the next request for this user. | Cookie deletion is the primary enforcement mechanism. KV delete failure must not block or delay the cookie expiry.                                                                                                                                                |
+| Operation                            | KV unavailable or error                                                                                                           | Rationale                                                                                                                                                                                                                                                         |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| EC cookie creation                   | Set the cookie. Skip the KV entry creation silently. Log the failure at `warn` level.                                             | The cookie is the identity anchor — it does not require KV. The KV entry will be created on the next request once KV recovers.                                                                                                                                    |
+| EC cookie refresh (existing user)    | Refresh the cookie. Skip the KV `last_seen` update silently. Log at `warn`.                                                       | Same as above — the cookie continues working. Stale `last_seen` is acceptable.                                                                                                                                                                                    |
+| `/sync` KV write                     | Redirect to `return` with `ts_synced=0&ts_reason=write_failed`.                                                                   | The browser redirect must not be blocked by KV availability. This case is already specified in Section 9.4.                                                                                                                                                       |
+| `/identify` KV read                  | Return `200` with `ec` hash (from cookie) and `degraded: true`. Set `uids: {}` and `eids: []`.                                    | The EC hash is still valid and useful for attribution and analytics. Empty uids signal that enrichment is unavailable, not that the user has no synced partners. `degraded: true` lets callers distinguish transient KV failure from a genuinely unenriched user. |
+| S2S batch write (`/_ts/api/v1/sync`) | Return `207` with all mappings rejected, `reason: "kv_unavailable"`.                                                              | The request was valid; the failure is infrastructure. Partners should retry the batch.                                                                                                                                                                            |
+| S2S pull sync write (async)          | Discard the resolved uid. Log at `warn`. Retry will occur on the next qualifying request per the `pull_sync_ttl_sec` window.      | Async path — no user-facing impact.                                                                                                                                                                                                                               |
+| Consent withdrawal KV delete         | Expire the cookie immediately. Log the KV delete failure at `error` level. Retry the KV delete on the next request for this user. | Cookie deletion is the primary enforcement mechanism. KV delete failure must not block or delay the cookie expiry.                                                                                                                                                |
 
 **`degraded: true` in `/identify` responses**
 
@@ -957,10 +957,10 @@ The following documentation changes are required alongside the EC feature:
 
 ## 15. Open Questions
 
-| #   | Question                                                                                                                                                                                                                                                                                     | Owner       | Status                                                                      |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------- |
+| #   | Question                                                                                                                                                                                                                                                                                         | Owner       | Status                                                                          |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------- |
 | 1   | Partner provisioning: TS will expose a `/_ts/admin/partners/register` endpoint authenticated at the publisher level (bearer token issued per publisher Fastly service), so publishers can onboard SSP/DSP partners without touching KV directly. Engineering to define the exact auth mechanism. | Engineering | **Resolved** — `/_ts/admin/partners/register` endpoint, publisher-authenticated |
-| 2   | Should TS Lite expose a `GET /health` endpoint so partners can programmatically verify their service is running and their partner config is active in KV?                                                                                                                                    | Product     | **N/A** — TS Lite deferred (see Section 5)                                  |
+| 2   | Should TS Lite expose a `GET /health` endpoint so partners can programmatically verify their service is running and their partner config is active in KV?                                                                                                                                        | Product     | **N/A** — TS Lite deferred (see Section 5)                                      |
 
 ---
 
diff --git a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
index 57fdc919..f88b9ab9 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
@@ -353,7 +353,7 @@ pub fn clear_ec_on_response(response: &mut Response, cookie_domain: &str);
 
 ### 5.3 Response header
 
-`X-ts-ec: {ec_hash.suffix}` is set by `set_ec_on_response()`, which is called by `ec_finalize_response()` in two cases: (1) `ec_generated == true` (new EC minted this request), or (2) `cookie_ec_value.is_some()` (header/cookie mismatch reconciliation — overwrites cookie to match header). It is also set explicitly by `/identify` and `/auction` handlers on their own response paths when an EC is present. It is **not** set on ordinary returning-user requests where the cookie already matches the header (or no header is present).
+`X-ts-ec: {ec_hash.suffix}` is set by `set_ec_on_response()` when an EC is available. In current behavior, `ec_finalize_response()` calls `set_ec_on_response()` for returning users (`ec_was_present == true && ec_generated == false && allows_ec_creation(&consent)`) and for newly generated ECs (`ec_generated == true`). `/identify` and `/auction` also set EC-related headers on their response paths.
 
 This header is added to `INTERNAL_HEADERS` in `constants.rs` so it is stripped before proxying to downstream backends, consistent with existing `X-ts-*` handling.
 
@@ -411,11 +411,7 @@ ec_context.generate_if_needed(settings, &kv)    // best-effort — never 500s
   │
   ├── ec_was_present == true && ec_generated == false && allows_ec_creation(&consent)?
   │       → kv.update_last_seen(ec_hash, now())   (returning user — debounced at 300s)
-  │       → if cookie_ec_value.is_some():
-  │           // Header and cookie disagree — reconcile by overwriting cookie with header value.
-  │           // Prevents persistent split identity where user oscillates between two ECs
-  │           // depending on whether the forwarded header is present on subsequent requests.
-  │           set_ec_on_response()   (Set-Cookie with ec_value, the header-derived identity)
+  │       → set_ec_on_response()   (Set-Cookie + X-ts-ec refresh on returning user)
   │
   └── ec_generated == true?
           → set_ec_on_response()        (Set-Cookie + X-ts-ec on response)
@@ -423,7 +419,7 @@ ec_context.generate_if_needed(settings, &kv)    // best-effort — never 500s
 
 EC route handlers (`GET /sync`, `GET /identify`, `POST /_ts/api/v1/sync`, `POST /_ts/admin/*`) never call `generate_if_needed()`. `ec_finalize_response()` will still delete the cookie on those routes if consent is withdrawn — that is intentional.
 
-**Cookie write rule:** `Set-Cookie` is written in exactly two cases: (1) `ec_generated == true` (first-time generation), or (2) `cookie_ec_value.is_some()` (header/cookie mismatch — reconcile cookie to match the header-derived identity). There is no cookie refresh or Max-Age reset on ordinary returning users where cookie already matches. The PRD defers a blanket refresh-on-every-request strategy to a future iteration.
+**Cookie write rule:** `Set-Cookie` is written when `set_ec_on_response()` is called. In current behavior this includes returning-user requests (consent allowed + EC present) and first-time generation (`ec_generated == true`), so `Max-Age` is refreshed on ordinary returning requests.
 
 ---
 
@@ -685,7 +681,7 @@ impl KvIdentityGraph {
 | EC cookie creation                 | KV error       | Set cookie. Skip KV create. Log `warn`.                                                        |
 | `/sync` KV write                   | KV error       | Redirect with `ts_synced=0&ts_reason=write_failed`.                                            |
 | `/identify` KV read                | KV error       | Return `200` with `ec` set, `degraded: true`, empty `uids`/`eids`.                             |
-| `POST /_ts/api/v1/sync`                | KV error       | Return `207` with all mappings rejected, `reason: "kv_unavailable"`.                           |
+| `POST /_ts/api/v1/sync`            | KV error       | Return `207` with all mappings rejected, `reason: "kv_unavailable"`.                           |
 | Pull sync KV write                 | KV error       | Discard uid. Log `warn`. Retry on next qualifying request.                                     |
 | Consent withdrawal tombstone write | KV error       | Delete cookie (primary enforcement). Log `error`. Next request: no cookie → no EC regenerated. |
 
@@ -1712,11 +1708,11 @@ Suggested order to minimize risk and allow incremental testing. Each step should
 | 2    | `ec/finalize.rs`                                          | `ec_finalize_response()` (cookie write, deletion, tombstone, last_seen)                        |
 | 3    | `ec/cookie.rs`                                            | Cookie creation, deletion, response header                                                     |
 | 4    | `ec/kv.rs`                                                | `KvIdentityGraph` CRUD with CAS                                                                |
-| 5    | `ec/partner.rs` + `ec/admin.rs`                           | `PartnerStore`, `/_ts/admin/partners/register`                                                     |
+| 5    | `ec/partner.rs` + `ec/admin.rs`                           | `PartnerStore`, `/_ts/admin/partners/register`                                                 |
 | 6    | EC middleware in `main.rs`, `publisher.rs`, `registry.rs` | `EcContext::read_from_request()` pre-routing, `generate_if_needed()`, `ec_finalize_response()` |
 | 7    | `ec/sync_pixel.rs`                                        | `GET /sync` handler + route                                                                    |
 | 8    | `ec/identify.rs`                                          | `GET /identify` handler + route                                                                |
-| 9    | `ec/sync_batch.rs`                                        | `POST /_ts/api/v1/sync` handler + route                                                            |
+| 9    | `ec/sync_batch.rs`                                        | `POST /_ts/api/v1/sync` handler + route                                                        |
 | 10   | `ec/pull_sync.rs`                                         | Background pull sync dispatch (blocking, after `send_to_client()`)                             |
 | 11   | Auction integration                                       | EC injection into `user.id`, `user.eids`, `user.consent`                                       |
 | 12   | End-to-end integration tests                              | Viceroy-based flow tests                                                                       |

From a88e892d1db4a8618a6527356df12a8da28d68e9 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Thu, 2 Apr 2026 12:52:46 -0500
Subject: [PATCH 22/36] Use full EC IDs for identity graph keys

---
 crates/integration-tests/tests/common/ec.rs   |  18 +--
 .../tests/frameworks/scenarios.rs             |  16 +--
 .../src/auction/endpoints.rs                  |   6 +-
 .../trusted-server-core/src/ec/batch_sync.rs  |  78 ++++++-----
 crates/trusted-server-core/src/ec/finalize.rs |  24 +---
 crates/trusted-server-core/src/ec/identify.rs |   6 +-
 crates/trusted-server-core/src/ec/kv.rs       | 131 +++++++++---------
 crates/trusted-server-core/src/ec/kv_types.rs |   4 +-
 crates/trusted-server-core/src/ec/mod.rs      |   7 +-
 .../trusted-server-core/src/ec/pull_sync.rs   |  51 +++----
 .../trusted-server-core/src/ec/sync_pixel.rs  |  14 +-
 docs/guide/api-reference.md                   |   4 +-
 docs/guide/ec-setup-guide.md                  |   9 +-
 13 files changed, 183 insertions(+), 185 deletions(-)

diff --git a/crates/integration-tests/tests/common/ec.rs b/crates/integration-tests/tests/common/ec.rs
index 7d30740f..4e387efc 100644
--- a/crates/integration-tests/tests/common/ec.rs
+++ b/crates/integration-tests/tests/common/ec.rs
@@ -272,7 +272,7 @@ pub fn batch_sync_no_auth(
 
 /// Single mapping in a batch sync request.
 pub struct BatchMapping {
-    pub ec_hash: String,
+    pub ec_id: String,
     pub partner_uid: String,
     pub timestamp: u64,
 }
@@ -282,7 +282,7 @@ fn mappings_to_json(mappings: &[BatchMapping]) -> Vec<Value> {
         .iter()
         .map(|m| {
             serde_json::json!({
-                "ec_hash": m.ec_hash,
+                "ec_id": m.ec_id,
                 "partner_uid": m.partner_uid,
                 "timestamp": m.timestamp,
             })
@@ -360,12 +360,14 @@ pub fn is_ec_cookie_expired(resp: &Response) -> bool {
     false
 }
 
-/// Extracts the stable 64-char hex prefix from an EC ID (`{64hex}.{6alnum}`).
-pub fn ec_hash(ec_id: &str) -> &str {
-    match ec_id.find('.') {
-        Some(pos) => &ec_id[..pos],
-        None => ec_id,
-    }
+/// Normalizes an EC ID for KV key usage.
+///
+/// Lowercases the 64-char hex hash prefix and preserves the 6-char suffix.
+pub fn normalize_ec_id(ec_id: &str) -> String {
+    let mut parts = ec_id.splitn(2, '.');
+    let hash = parts.next().unwrap_or_default();
+    let suffix = parts.next().unwrap_or_default();
+    format!("{}.{}", hash.to_ascii_lowercase(), suffix)
 }
 
 // ---------------------------------------------------------------------------
diff --git a/crates/integration-tests/tests/frameworks/scenarios.rs b/crates/integration-tests/tests/frameworks/scenarios.rs
index 1d094189..668c4968 100644
--- a/crates/integration-tests/tests/frameworks/scenarios.rs
+++ b/crates/integration-tests/tests/frameworks/scenarios.rs
@@ -1,7 +1,7 @@
 use crate::common::assertions;
 use crate::common::ec::{
-    assert_json_response, assert_status, batch_sync, batch_sync_no_auth, ec_hash,
-    extract_ec_cookie_from_response, identify, is_ec_cookie_expired, pixel_sync,
+    assert_json_response, assert_status, batch_sync, batch_sync_no_auth,
+    extract_ec_cookie_from_response, identify, is_ec_cookie_expired, normalize_ec_id, pixel_sync,
     register_test_partner, BatchMapping, EcTestClient,
 };
 use crate::common::runtime::{origin_port, TestError, TestResult};
@@ -692,21 +692,21 @@ fn ec_concurrent_partner_syncs(base_url: &str) -> TestResult<()> {
 fn ec_batch_sync_happy_path(base_url: &str) -> TestResult<()> {
     let client = EcTestClient::new(base_url);
 
-    // Generate EC to get a valid hash
+    // Generate EC to get a valid EC ID
     let resp = client.get("/")?;
     let ec_id = extract_ec_cookie_from_response(&resp).ok_or_else(|| {
         Report::new(TestError::EcCookieNotSet).attach("batch sync: need EC cookie")
     })?;
-    let hash = ec_hash(&ec_id).to_owned();
-    log::info!("EC batch sync happy path: hash = {hash}");
+    let ec_id = normalize_ec_id(&ec_id);
+    log::info!("EC batch sync happy path: ec_id = {ec_id}");
 
     // Register partner with known API key
     register_test_partner(&client, "batchssp", "batch-api-key-1", "sync.example.com")
         .attach("register batch sync partner")?;
 
-    // Batch sync writes a UID for this hash
+    // Batch sync writes a UID for this EC ID
     let mappings = vec![BatchMapping {
-        ec_hash: hash.clone(),
+        ec_id: ec_id.clone(),
         partner_uid: "batch-uid-99".to_owned(),
         timestamp: 1_700_000_000,
     }];
@@ -751,7 +751,7 @@ fn ec_batch_sync_auth_rejection(base_url: &str) -> TestResult<()> {
     let client = EcTestClient::new(base_url);
 
     let dummy_mappings = vec![BatchMapping {
-        ec_hash: "a".repeat(64),
+        ec_id: format!("{}.ABC123", "a".repeat(64)),
         partner_uid: "uid-1".to_owned(),
         timestamp: 1_700_000_000,
     }];
diff --git a/crates/trusted-server-core/src/auction/endpoints.rs b/crates/trusted-server-core/src/auction/endpoints.rs
index 6cbc58cb..fbecd403 100644
--- a/crates/trusted-server-core/src/auction/endpoints.rs
+++ b/crates/trusted-server-core/src/auction/endpoints.rs
@@ -123,13 +123,13 @@ fn resolve_auction_eids(
         return None;
     }
 
-    let ec_hash = ec_context.ec_hash()?;
+    let ec_id = ec_context.ec_value()?;
 
-    let entry = match kv.get(ec_hash) {
+    let entry = match kv.get(ec_id) {
         Ok(Some((entry, _generation))) => entry,
         Ok(None) => return Some(Vec::new()),
         Err(err) => {
-            log::warn!("Auction KV read failed for EC hash '{ec_hash}': {err:?}");
+            log::warn!("Auction KV read failed for EC ID '{ec_id}': {err:?}");
             return Some(Vec::new());
         }
     };
diff --git a/crates/trusted-server-core/src/ec/batch_sync.rs b/crates/trusted-server-core/src/ec/batch_sync.rs
index 0798f54d..df698dc5 100644
--- a/crates/trusted-server-core/src/ec/batch_sync.rs
+++ b/crates/trusted-server-core/src/ec/batch_sync.rs
@@ -1,7 +1,7 @@
 //! Server-to-server batch sync endpoint (`POST /_ts/api/v1/sync`).
 //!
 //! Partners send authenticated batch ID sync requests via Bearer token.
-//! Each mapping associates an `ec_hash` (the 64-char hex EC hash prefix)
+//! Each mapping associates an `ec_id` (`{64hex}.{6alnum}`)
 //! with the partner's user ID. Mappings are individually validated and
 //! written to the KV identity graph, with per-mapping rejection reasons
 //! reported in the response.
@@ -13,14 +13,14 @@ use serde::{Deserialize, Serialize};
 
 use crate::error::TrustedServerError;
 
-use super::generation::is_valid_ec_hash;
+use super::generation::is_valid_ec_id;
 use super::kv::{KvIdentityGraph, UpsertResult};
 use super::partner::{hash_api_key, PartnerRecord, PartnerStore};
 use super::sync_pixel::RateLimiter;
 
-const REASON_INVALID_EC_HASH: &str = "invalid_ec_hash";
+const REASON_INVALID_EC_ID: &str = "invalid_ec_id";
 const REASON_INVALID_PARTNER_UID: &str = "invalid_partner_uid";
-const REASON_EC_HASH_NOT_FOUND: &str = "ec_hash_not_found";
+const REASON_EC_ID_NOT_FOUND: &str = "ec_id_not_found";
 const REASON_CONSENT_WITHDRAWN: &str = "consent_withdrawn";
 const REASON_KV_UNAVAILABLE: &str = "kv_unavailable";
 
@@ -33,7 +33,7 @@ const MAX_UID_LENGTH: usize = 512;
 trait BatchSyncWriter {
     fn upsert_partner_id_if_exists(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
         partner_id: &str,
         uid: &str,
         synced: u64,
@@ -43,12 +43,12 @@ trait BatchSyncWriter {
 impl BatchSyncWriter for KvIdentityGraph {
     fn upsert_partner_id_if_exists(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
         partner_id: &str,
         uid: &str,
         synced: u64,
     ) -> Result<UpsertResult, Report<TrustedServerError>> {
-        KvIdentityGraph::upsert_partner_id_if_exists(self, ec_hash, partner_id, uid, synced)
+        KvIdentityGraph::upsert_partner_id_if_exists(self, ec_id, partner_id, uid, synced)
     }
 }
 
@@ -63,7 +63,7 @@ struct BatchSyncRequest {
 
 #[derive(Debug, Deserialize)]
 struct SyncMapping {
-    ec_hash: String,
+    ec_id: String,
     partner_uid: String,
     timestamp: u64,
 }
@@ -198,10 +198,10 @@ fn process_mappings(
     let mut errors = Vec::new();
 
     for (idx, mapping) in mappings.iter().enumerate() {
-        if !is_valid_ec_hash(&mapping.ec_hash) {
+        if !is_valid_ec_id(&mapping.ec_id) {
             errors.push(MappingError {
                 index: idx,
-                reason: REASON_INVALID_EC_HASH,
+                reason: REASON_INVALID_EC_ID,
             });
             continue;
         }
@@ -214,10 +214,9 @@ fn process_mappings(
             continue;
         }
 
-        // Normalize to lowercase — KV keys are always lowercase hex.
-        let ec_hash = mapping.ec_hash.to_ascii_lowercase();
+        let ec_id = normalize_ec_id_for_kv(&mapping.ec_id);
         match writer.upsert_partner_id_if_exists(
-            &ec_hash,
+            &ec_id,
             partner_id,
             &mapping.partner_uid,
             mapping.timestamp,
@@ -228,7 +227,7 @@ fn process_mappings(
             Ok(UpsertResult::NotFound) => {
                 errors.push(MappingError {
                     index: idx,
-                    reason: REASON_EC_HASH_NOT_FOUND,
+                    reason: REASON_EC_ID_NOT_FOUND,
                 });
             }
             Ok(UpsertResult::ConsentWithdrawn) => {
@@ -239,8 +238,8 @@ fn process_mappings(
             }
             Err(err) => {
                 log::warn!(
-                    "Batch sync KV write failed for index {idx} (ec_hash '{}'): {err:?}",
-                    mapping.ec_hash
+                    "Batch sync KV write failed for index {idx} (ec_id '{}'): {err:?}",
+                    mapping.ec_id
                 );
                 errors.push(MappingError {
                     index: idx,
@@ -261,6 +260,13 @@ fn process_mappings(
     (accepted, errors)
 }
 
+fn normalize_ec_id_for_kv(ec_id: &str) -> String {
+    let mut parts = ec_id.splitn(2, '.');
+    let hash = parts.next().unwrap_or_default();
+    let suffix = parts.next().unwrap_or_default();
+    format!("{}.{}", hash.to_ascii_lowercase(), suffix)
+}
+
 fn json_response<T: serde::Serialize>(
     status: StatusCode,
     body: &T,
@@ -288,12 +294,13 @@ mod tests {
 
     use crate::error::TrustedServerError;
 
-    // Hash validation tests are in generation.rs (is_valid_ec_hash).
+    // EC ID validation tests are in generation.rs (is_valid_ec_id).
     // Verify the import works here with a basic smoke test.
     #[test]
-    fn is_valid_ec_hash_smoke_test() {
-        assert!(is_valid_ec_hash(&"a".repeat(64)));
-        assert!(!is_valid_ec_hash(&"a".repeat(63)));
+    fn is_valid_ec_id_smoke_test() {
+        let valid = format!("{}.ABC123", "a".repeat(64));
+        assert!(is_valid_ec_id(&valid));
+        assert!(!is_valid_ec_id(&"a".repeat(64)));
     }
 
     #[test]
@@ -386,7 +393,7 @@ mod tests {
     impl BatchSyncWriter for MockWriter {
         fn upsert_partner_id_if_exists(
             &self,
-            _ec_hash: &str,
+            _ec_id: &str,
             _partner_id: &str,
             _uid: &str,
             _synced: u64,
@@ -398,9 +405,9 @@ mod tests {
         }
     }
 
-    fn mapping(ec_hash: &str, partner_uid: &str, timestamp: u64) -> SyncMapping {
+    fn mapping(ec_id: &str, partner_uid: &str, timestamp: u64) -> SyncMapping {
         SyncMapping {
-            ec_hash: ec_hash.to_owned(),
+            ec_id: ec_id.to_owned(),
             partner_uid: partner_uid.to_owned(),
             timestamp,
         }
@@ -411,8 +418,8 @@ mod tests {
         let writer = MockWriter::new(vec![Ok(UpsertResult::Written)]);
         let mappings = vec![
             mapping("x", "u1", 1),
-            mapping(&"a".repeat(64), "", 1),
-            mapping(&"a".repeat(64), "u3", 1),
+            mapping(&format!("{}.ABC123", "a".repeat(64)), "", 1),
+            mapping(&format!("{}.ABC123", "a".repeat(64)), "u3", 1),
         ];
 
         let (accepted, errors) = process_mappings(&writer, "partner", &mappings);
@@ -420,7 +427,7 @@ mod tests {
         assert_eq!(accepted, 1, "should count successful writes as accepted");
         assert_eq!(errors.len(), 2, "should reject invalid mappings only");
         assert_eq!(errors[0].index, 0);
-        assert_eq!(errors[0].reason, REASON_INVALID_EC_HASH);
+        assert_eq!(errors[0].reason, REASON_INVALID_EC_ID);
         assert_eq!(errors[1].index, 1);
         assert_eq!(errors[1].reason, REASON_INVALID_PARTNER_UID);
     }
@@ -437,9 +444,9 @@ mod tests {
         ]);
 
         let mappings = vec![
-            mapping(&"a".repeat(64), "u1", 1),
-            mapping(&"b".repeat(64), "u2", 1),
-            mapping(&"c".repeat(64), "u3", 1),
+            mapping(&format!("{}.ABC123", "a".repeat(64)), "u1", 1),
+            mapping(&format!("{}.ABC123", "b".repeat(64)), "u2", 1),
+            mapping(&format!("{}.ABC123", "c".repeat(64)), "u3", 1),
         ];
 
         let (accepted, errors) = process_mappings(&writer, "partner", &mappings);
@@ -476,18 +483,21 @@ mod tests {
 
     #[test]
     fn batch_sync_request_deserializes_correctly() {
-        let json = r#"{"mappings": [{"ec_hash": "aaaa", "partner_uid": "u1", "timestamp": 100}]}"#;
+        let json = r#"{"mappings": [{"ec_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.ABC123", "partner_uid": "u1", "timestamp": 100}]}"#;
         let parsed: BatchSyncRequest =
             serde_json::from_str(json).expect("should deserialize batch sync request");
         assert_eq!(parsed.mappings.len(), 1);
-        assert_eq!(parsed.mappings[0].ec_hash, "aaaa");
+        assert_eq!(
+            parsed.mappings[0].ec_id,
+            "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.ABC123"
+        );
         assert_eq!(parsed.mappings[0].partner_uid, "u1");
         assert_eq!(parsed.mappings[0].timestamp, 100);
     }
 
     #[test]
     fn batch_sync_request_rejects_missing_timestamp() {
-        let json = r#"{"mappings": [{"ec_hash": "bbbb", "partner_uid": "u2"}]}"#;
+        let json = r#"{"mappings": [{"ec_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.ABC123", "partner_uid": "u2"}]}"#;
         let result = serde_json::from_str::<BatchSyncRequest>(json);
         assert!(
             result.is_err(),
@@ -502,7 +512,7 @@ mod tests {
             rejected: 1,
             errors: vec![MappingError {
                 index: 3,
-                reason: REASON_EC_HASH_NOT_FOUND,
+                reason: REASON_EC_ID_NOT_FOUND,
             }],
         };
 
@@ -511,6 +521,6 @@ mod tests {
         assert_eq!(json["accepted"], 5);
         assert_eq!(json["rejected"], 1);
         assert_eq!(json["errors"][0]["index"], 3);
-        assert_eq!(json["errors"][0]["reason"], REASON_EC_HASH_NOT_FOUND);
+        assert_eq!(json["errors"][0]["reason"], REASON_EC_ID_NOT_FOUND);
     }
 }
diff --git a/crates/trusted-server-core/src/ec/finalize.rs b/crates/trusted-server-core/src/ec/finalize.rs
index e3e91b73..c0642222 100644
--- a/crates/trusted-server-core/src/ec/finalize.rs
+++ b/crates/trusted-server-core/src/ec/finalize.rs
@@ -15,7 +15,7 @@ use crate::settings::Settings;
 
 use super::cookies::{expire_ec_cookie, set_ec_cookie};
 use super::current_timestamp;
-use super::generation::{ec_hash, is_valid_ec_hash, is_valid_ec_id};
+use super::generation::is_valid_ec_id;
 use super::kv::KvIdentityGraph;
 use super::EcContext;
 
@@ -51,11 +51,11 @@ pub fn ec_finalize_response(
         }
 
         if let Some(graph) = kv {
-            for hash in withdrawal_hashes(ec_context) {
-                if let Err(err) = graph.write_withdrawal_tombstone(&hash) {
+            for ec_id in withdrawal_ec_ids(ec_context) {
+                if let Err(err) = graph.write_withdrawal_tombstone(&ec_id) {
                     log::error!(
-                        "Failed to write withdrawal tombstone for hash '{}': {err:?}",
-                        hash,
+                        "Failed to write withdrawal tombstone for EC ID '{}': {err:?}",
+                        ec_id,
                     );
                 }
             }
@@ -67,11 +67,8 @@ pub fn ec_finalize_response(
     // Returning user: consent is granted and EC came from request.
     if ec_context.ec_was_present() && !ec_context.ec_generated() && consent_allows_ec {
         if let (Some(graph), Some(ec_id)) = (kv, ec_context.ec_value()) {
-            let hash = ec_hash(ec_id);
-            if is_valid_ec_hash(hash) {
-                if let Err(err) = graph.update_last_seen(hash, current_timestamp()) {
-                    log::error!("Failed to update last_seen for hash '{}': {err:?}", hash,);
-                }
+            if let Err(err) = graph.update_last_seen(ec_id, current_timestamp()) {
+                log::error!("Failed to update last_seen for EC ID '{}': {err:?}", ec_id,);
             }
         }
 
@@ -127,13 +124,6 @@ pub fn clear_ec_on_response(settings: &Settings, response: &mut Response) {
     }
 }
 
-fn withdrawal_hashes(ec_context: &EcContext) -> HashSet<String> {
-    withdrawal_ec_ids(ec_context)
-        .into_iter()
-        .map(|ec_id| ec_hash(&ec_id).to_owned())
-        .collect()
-}
-
 fn withdrawal_ec_ids(ec_context: &EcContext) -> HashSet<String> {
     let mut hashes = HashSet::new();
 
diff --git a/crates/trusted-server-core/src/ec/identify.rs b/crates/trusted-server-core/src/ec/identify.rs
index b03dee86..55016e88 100644
--- a/crates/trusted-server-core/src/ec/identify.rs
+++ b/crates/trusted-server-core/src/ec/identify.rs
@@ -61,8 +61,8 @@ pub fn handle_identify(
     let mut degraded = false;
     let mut resolved = Vec::new();
 
-    if let Some(ec_hash) = ec_context.ec_hash() {
-        match kv.get(ec_hash) {
+    if let Some(ec_id) = ec_context.ec_value() {
+        match kv.get(ec_id) {
             Ok(Some((entry, _generation))) => match resolve_partner_ids(partner_store, &entry) {
                 Ok(values) => {
                     resolved = values;
@@ -74,7 +74,7 @@ pub fn handle_identify(
             },
             Ok(None) => {}
             Err(err) => {
-                log::warn!("Identify KV read failed for hash '{ec_hash}': {err:?}");
+                log::warn!("Identify KV read failed for EC ID '{ec_id}': {err:?}");
                 degraded = true;
             }
         }
diff --git a/crates/trusted-server-core/src/ec/kv.rs b/crates/trusted-server-core/src/ec/kv.rs
index f6815b1c..d70192c3 100644
--- a/crates/trusted-server-core/src/ec/kv.rs
+++ b/crates/trusted-server-core/src/ec/kv.rs
@@ -51,7 +51,7 @@ pub enum UpsertResult {
 
 /// Wraps a Fastly KV Store for EC identity graph operations.
 ///
-/// Each EC hash (64-char hex prefix) maps to a JSON-encoded [`KvEntry`]
+/// Each EC ID (`{64hex}.{6alnum}`) maps to a JSON-encoded [`KvEntry`]
 /// containing consent state, geo location, and accumulated partner IDs.
 ///
 /// Methods use optimistic concurrency (generation markers) for safe
@@ -115,16 +115,16 @@ impl KvIdentityGraph {
     /// # Errors
     ///
     /// Returns [`TrustedServerError::KvStore`] on store open or read failure.
-    pub fn get(&self, ec_hash: &str) -> Result<Option<(KvEntry, u64)>, Report<TrustedServerError>> {
+    pub fn get(&self, ec_id: &str) -> Result<Option<(KvEntry, u64)>, Report<TrustedServerError>> {
         let store = self.open_store()?;
-        let mut response = match store.lookup(ec_hash) {
+        let mut response = match store.lookup(ec_id) {
             Ok(resp) => resp,
             Err(fastly::kv_store::KVStoreError::ItemNotFound) => return Ok(None),
             Err(err) => {
                 return Err(
                     Report::new(err).change_context(TrustedServerError::KvStore {
                         store_name: self.store_name.clone(),
-                        message: format!("Failed to read key '{ec_hash}'"),
+                        message: format!("Failed to read key '{ec_id}'"),
                     }),
                 );
             }
@@ -135,13 +135,13 @@ impl KvIdentityGraph {
         let entry: KvEntry =
             serde_json::from_slice(&body_bytes).change_context(TrustedServerError::KvStore {
                 store_name: self.store_name.clone(),
-                message: format!("Failed to deserialize entry for key '{ec_hash}'"),
+                message: format!("Failed to deserialize entry for key '{ec_id}'"),
             })?;
 
         Ok(Some((entry, generation)))
     }
 
-    /// Reads only the metadata for an EC hash (no body streaming).
+    /// Reads only the metadata for an EC ID key (no body streaming).
     ///
     /// Returns `Ok(None)` when the key does not exist or has no metadata.
     ///
@@ -150,17 +150,17 @@ impl KvIdentityGraph {
     /// Returns [`TrustedServerError::KvStore`] on store open or read failure.
     pub fn get_metadata(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
     ) -> Result<Option<KvMetadata>, Report<TrustedServerError>> {
         let store = self.open_store()?;
-        let response = match store.lookup(ec_hash) {
+        let response = match store.lookup(ec_id) {
             Ok(resp) => resp,
             Err(fastly::kv_store::KVStoreError::ItemNotFound) => return Ok(None),
             Err(err) => {
                 return Err(
                     Report::new(err).change_context(TrustedServerError::KvStore {
                         store_name: self.store_name.clone(),
-                        message: format!("Failed to read metadata for key '{ec_hash}'"),
+                        message: format!("Failed to read metadata for key '{ec_id}'"),
                     }),
                 );
             }
@@ -174,7 +174,7 @@ impl KvIdentityGraph {
         let meta: KvMetadata =
             serde_json::from_slice(&meta_bytes).change_context(TrustedServerError::KvStore {
                 store_name: self.store_name.clone(),
-                message: format!("Failed to deserialize metadata for key '{ec_hash}'"),
+                message: format!("Failed to deserialize metadata for key '{ec_id}'"),
             })?;
 
         Ok(Some(meta))
@@ -182,23 +182,23 @@ impl KvIdentityGraph {
 
     /// Creates a new entry. Fails if the key already exists.
     ///
-    /// Uses `InsertMode::Add` so concurrent creates for the same EC hash
+    /// Uses `InsertMode::Add` so concurrent creates for the same EC ID
     /// are safely rejected (only one wins).
     ///
     /// # Errors
     ///
     /// Returns [`TrustedServerError::KvStore`] on store error or if the
     /// key already exists (`ItemPreconditionFailed`).
-    pub fn create(&self, ec_hash: &str, entry: &KvEntry) -> Result<(), Report<TrustedServerError>> {
+    pub fn create(&self, ec_id: &str, entry: &KvEntry) -> Result<(), Report<TrustedServerError>> {
         let store = self.open_store()?;
         let (body, meta_str) = Self::serialize_entry(entry, &self.store_name)?;
-        let created = Self::try_insert_add(&store, ec_hash, &body, &meta_str, &self.store_name)?;
+        let created = Self::try_insert_add(&store, ec_id, &body, &meta_str, &self.store_name)?;
         if created {
             Ok(())
         } else {
             Err(Report::new(TrustedServerError::KvStore {
                 store_name: self.store_name.clone(),
-                message: format!("Key '{ec_hash}' already exists"),
+                message: format!("Key '{ec_id}' already exists"),
             }))
         }
     }
@@ -209,7 +209,7 @@ impl KvIdentityGraph {
     /// exists (`ItemPreconditionFailed`). Other errors are propagated.
     fn try_insert_add(
         store: &KVStore,
-        ec_hash: &str,
+        ec_id: &str,
         body: &str,
         meta_str: &str,
         store_name: &str,
@@ -219,14 +219,14 @@ impl KvIdentityGraph {
             .mode(InsertMode::Add)
             .metadata(meta_str)
             .time_to_live(ENTRY_TTL)
-            .execute(ec_hash, body)
+            .execute(ec_id, body)
         {
             Ok(()) => Ok(true),
             Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => Ok(false),
             Err(err) => Err(
                 Report::new(err).change_context(TrustedServerError::KvStore {
                     store_name: store_name.to_owned(),
-                    message: format!("Failed to create entry for key '{ec_hash}'"),
+                    message: format!("Failed to create entry for key '{ec_id}'"),
                 }),
             ),
         }
@@ -250,7 +250,7 @@ impl KvIdentityGraph {
     /// exhaustion.
     pub fn create_or_revive(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
         entry: &KvEntry,
     ) -> Result<(), Report<TrustedServerError>> {
         // Serialize once and reuse across the fast path and CAS loop.
@@ -258,25 +258,25 @@ impl KvIdentityGraph {
         let (body, meta_str) = Self::serialize_entry(entry, &self.store_name)?;
 
         // Try create first — fast path for new entries.
-        if Self::try_insert_add(&store, ec_hash, &body, &meta_str, &self.store_name)? {
+        if Self::try_insert_add(&store, ec_id, &body, &meta_str, &self.store_name)? {
             return Ok(());
         }
 
         // Key exists — read it to determine if it's live or a tombstone.
-        let (existing, generation) = match self.get(ec_hash)? {
+        let (existing, generation) = match self.get(ec_id)? {
             Some(pair) => pair,
             // Raced with a delete — try create again.
-            None => return self.create(ec_hash, entry),
+            None => return self.create(ec_id, entry),
         };
 
         // Live entry — nothing to do.
         if existing.consent.ok {
-            log::debug!("create_or_revive: live entry exists for '{ec_hash}', no-op");
+            log::debug!("create_or_revive: live entry exists for '{ec_id}', no-op");
             return Ok(());
         }
 
         // Tombstone — CAS overwrite to revive.
-        log::info!("create_or_revive: reviving tombstone for '{ec_hash}'");
+        log::info!("create_or_revive: reviving tombstone for '{ec_id}'");
 
         let mut current_gen = generation;
         for attempt in 0..MAX_CAS_RETRIES {
@@ -285,16 +285,16 @@ impl KvIdentityGraph {
                 .if_generation_match(current_gen)
                 .metadata(&meta_str)
                 .time_to_live(ENTRY_TTL)
-                .execute(ec_hash, body.as_str())
+                .execute(ec_id, body.as_str())
             {
                 Ok(()) => return Ok(()),
                 Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
                     log::debug!(
-                        "create_or_revive: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_hash}'",
+                        "create_or_revive: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_id}'",
                         attempt + 1,
                     );
                     // Re-read to get fresh generation.
-                    match self.get(ec_hash)? {
+                    match self.get(ec_id)? {
                         Some((refreshed, gen)) => {
                             if refreshed.consent.ok {
                                 // Someone else revived it — done.
@@ -302,7 +302,7 @@ impl KvIdentityGraph {
                             }
                             current_gen = gen;
                         }
-                        None => return self.create(ec_hash, entry),
+                        None => return self.create(ec_id, entry),
                     }
                 }
                 Err(err) => {
@@ -310,7 +310,7 @@ impl KvIdentityGraph {
                         Report::new(err).change_context(TrustedServerError::KvStore {
                             store_name: self.store_name.clone(),
                             message: format!(
-                                "Failed to revive tombstone for key '{ec_hash}' on attempt {}",
+                                "Failed to revive tombstone for key '{ec_id}' on attempt {}",
                                 attempt + 1,
                             ),
                         }),
@@ -322,7 +322,7 @@ impl KvIdentityGraph {
         Err(Report::new(TrustedServerError::KvStore {
             store_name: self.store_name.clone(),
             message: format!(
-                "CAS conflict after {MAX_CAS_RETRIES} retries reviving tombstone for '{ec_hash}'"
+                "CAS conflict after {MAX_CAS_RETRIES} retries reviving tombstone for '{ec_id}'"
             ),
         }))
     }
@@ -342,7 +342,7 @@ impl KvIdentityGraph {
     /// exhaustion after [`MAX_CAS_RETRIES`] attempts.
     pub fn upsert_partner_id(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
         partner_id: &str,
         uid: &str,
         synced: u64,
@@ -354,27 +354,20 @@ impl KvIdentityGraph {
         let store = self.open_store()?;
 
         for attempt in 0..MAX_CAS_RETRIES {
-            let (mut entry, generation) = match self.get(ec_hash)? {
+            let (mut entry, generation) = match self.get(ec_id)? {
                 Some(pair) => pair,
                 None => {
                     // Root entry missing — create a minimal entry.
-                    log::info!(
-                        "upsert_partner_id: no entry for '{ec_hash}', creating minimal entry"
-                    );
+                    log::info!("upsert_partner_id: no entry for '{ec_id}', creating minimal entry");
                     let minimal = KvEntry::minimal(partner_id, uid, synced);
                     let (min_body, min_meta) = Self::serialize_entry(&minimal, &self.store_name)?;
-                    if Self::try_insert_add(
-                        &store,
-                        ec_hash,
-                        &min_body,
-                        &min_meta,
-                        &self.store_name,
-                    )? {
+                    if Self::try_insert_add(&store, ec_id, &min_body, &min_meta, &self.store_name)?
+                    {
                         return Ok(());
                     }
                     // Key appeared between get() and create — re-read on next iteration.
                     log::debug!(
-                        "upsert_partner_id: minimal create raced for '{ec_hash}', retrying (attempt {}/{})",
+                        "upsert_partner_id: minimal create raced for '{ec_id}', retrying (attempt {}/{})",
                         attempt + 1,
                         MAX_CAS_RETRIES,
                     );
@@ -386,12 +379,12 @@ impl KvIdentityGraph {
             // repopulate partner IDs after consent withdrawal.
             if !entry.consent.ok {
                 log::info!(
-                    "upsert_partner_id: entry for '{ec_hash}' is a tombstone, rejecting upsert"
+                    "upsert_partner_id: entry for '{ec_id}' is a tombstone, rejecting upsert"
                 );
                 return Err(Report::new(TrustedServerError::KvStore {
                     store_name: self.store_name.clone(),
                     message: format!(
-                        "Cannot upsert partner '{partner_id}' for withdrawn key '{ec_hash}'"
+                        "Cannot upsert partner '{partner_id}' for withdrawn key '{ec_id}'"
                     ),
                 }));
             }
@@ -412,12 +405,12 @@ impl KvIdentityGraph {
                 .if_generation_match(generation)
                 .metadata(&meta_str)
                 .time_to_live(ENTRY_TTL)
-                .execute(ec_hash, body.as_str())
+                .execute(ec_id, body.as_str())
             {
                 Ok(()) => return Ok(()),
                 Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
                     log::debug!(
-                        "upsert_partner_id: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_hash}'",
+                        "upsert_partner_id: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_id}'",
                         attempt + 1,
                     );
                     // Loop will re-read on next iteration.
@@ -427,7 +420,7 @@ impl KvIdentityGraph {
                         Report::new(err).change_context(TrustedServerError::KvStore {
                             store_name: self.store_name.clone(),
                             message: format!(
-                                "Failed to upsert partner '{partner_id}' for key '{ec_hash}'"
+                                "Failed to upsert partner '{partner_id}' for key '{ec_id}'"
                             ),
                         }),
                     );
@@ -438,7 +431,7 @@ impl KvIdentityGraph {
         Err(Report::new(TrustedServerError::KvStore {
             store_name: self.store_name.clone(),
             message: format!(
-                "CAS conflict after {MAX_CAS_RETRIES} retries upserting partner '{partner_id}' for '{ec_hash}'"
+                "CAS conflict after {MAX_CAS_RETRIES} retries upserting partner '{partner_id}' for '{ec_id}'"
             ),
         }))
     }
@@ -458,7 +451,7 @@ impl KvIdentityGraph {
     /// exhaustion errors.
     pub fn upsert_partner_id_if_exists(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
         partner_id: &str,
         uid: &str,
         synced: u64,
@@ -466,7 +459,7 @@ impl KvIdentityGraph {
         let store = self.open_store()?;
 
         for attempt in 0..MAX_CAS_RETRIES {
-            let (mut entry, generation) = match self.get(ec_hash)? {
+            let (mut entry, generation) = match self.get(ec_id)? {
                 Some(pair) => pair,
                 None => return Ok(UpsertResult::NotFound),
             };
@@ -497,12 +490,12 @@ impl KvIdentityGraph {
                 .if_generation_match(generation)
                 .metadata(&meta_str)
                 .time_to_live(ENTRY_TTL)
-                .execute(ec_hash, body.as_str())
+                .execute(ec_id, body.as_str())
             {
                 Ok(()) => return Ok(UpsertResult::Written),
                 Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
                     log::debug!(
-                        "upsert_partner_id_if_exists: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_hash}'",
+                        "upsert_partner_id_if_exists: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_id}'",
                         attempt + 1,
                     );
                 }
@@ -511,7 +504,7 @@ impl KvIdentityGraph {
                         Report::new(err).change_context(TrustedServerError::KvStore {
                             store_name: self.store_name.clone(),
                             message: format!(
-                                "Failed to upsert partner '{partner_id}' for key '{ec_hash}'"
+                                "Failed to upsert partner '{partner_id}' for key '{ec_id}'"
                             ),
                         }),
                     );
@@ -522,7 +515,7 @@ impl KvIdentityGraph {
         Err(Report::new(TrustedServerError::KvStore {
             store_name: self.store_name.clone(),
             message: format!(
-                "CAS conflict after {MAX_CAS_RETRIES} retries upserting partner '{partner_id}' for '{ec_hash}'"
+                "CAS conflict after {MAX_CAS_RETRIES} retries upserting partner '{partner_id}' for '{ec_id}'"
             ),
         }))
     }
@@ -542,13 +535,13 @@ impl KvIdentityGraph {
     /// conflict.
     pub fn update_last_seen(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
         timestamp: u64,
     ) -> Result<(), Report<TrustedServerError>> {
-        let (mut entry, generation) = match self.get(ec_hash)? {
+        let (mut entry, generation) = match self.get(ec_id)? {
             Some(pair) => pair,
             None => {
-                log::debug!("update_last_seen: no entry for '{ec_hash}', skipping");
+                log::debug!("update_last_seen: no entry for '{ec_id}', skipping");
                 return Ok(());
             }
         };
@@ -556,14 +549,14 @@ impl KvIdentityGraph {
         // Skip tombstones — a stale cookie should not extend a 24h tombstone
         // back to 1-year TTL.
         if !entry.consent.ok {
-            log::debug!("update_last_seen: entry for '{ec_hash}' is a tombstone, skipping");
+            log::debug!("update_last_seen: entry for '{ec_id}' is a tombstone, skipping");
             return Ok(());
         }
 
         // Guard against stale/out-of-order timestamps.
         if timestamp <= entry.last_seen {
             log::trace!(
-                "update_last_seen: stale timestamp for '{ec_hash}' (stored={}, incoming={timestamp})",
+                "update_last_seen: stale timestamp for '{ec_id}' (stored={}, incoming={timestamp})",
                 entry.last_seen,
             );
             return Ok(());
@@ -572,7 +565,7 @@ impl KvIdentityGraph {
         // Debounce: skip if the stored value is recent enough.
         if timestamp - entry.last_seen < LAST_SEEN_DEBOUNCE_SECS {
             log::trace!(
-                "update_last_seen: debounced for '{ec_hash}' (delta={}s)",
+                "update_last_seen: debounced for '{ec_id}' (delta={}s)",
                 timestamp - entry.last_seen,
             );
             return Ok(());
@@ -587,10 +580,10 @@ impl KvIdentityGraph {
             .if_generation_match(generation)
             .metadata(&meta_str)
             .time_to_live(ENTRY_TTL)
-            .execute(ec_hash, body)
+            .execute(ec_id, body)
             .change_context(TrustedServerError::KvStore {
                 store_name: self.store_name.clone(),
-                message: format!("Failed to update last_seen for key '{ec_hash}'"),
+                message: format!("Failed to update last_seen for key '{ec_id}'"),
             })
     }
 
@@ -601,7 +594,7 @@ impl KvIdentityGraph {
     /// entry is being withdrawn regardless of concurrent state.
     ///
     /// The tombstone allows batch sync clients (`POST /_ts/api/v1/sync`) to
-    /// distinguish `consent_withdrawn` from `ec_hash_not_found` for 24 hours.
+    /// distinguish `consent_withdrawn` from `ec_id_not_found` for 24 hours.
     ///
     /// # Errors
     ///
@@ -610,7 +603,7 @@ impl KvIdentityGraph {
     /// deletion is the primary enforcement mechanism.
     pub fn write_withdrawal_tombstone(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
     ) -> Result<(), Report<TrustedServerError>> {
         let store = self.open_store()?;
         let entry = KvEntry::tombstone(current_timestamp());
@@ -620,10 +613,10 @@ impl KvIdentityGraph {
             .build_insert()
             .metadata(&meta_str)
             .time_to_live(TOMBSTONE_TTL)
-            .execute(ec_hash, body)
+            .execute(ec_id, body)
             .change_context(TrustedServerError::KvStore {
                 store_name: self.store_name.clone(),
-                message: format!("Failed to write tombstone for key '{ec_hash}'"),
+                message: format!("Failed to write tombstone for key '{ec_id}'"),
             })
     }
 
@@ -635,13 +628,13 @@ impl KvIdentityGraph {
     /// # Errors
     ///
     /// Returns [`TrustedServerError::KvStore`] on store error.
-    pub fn delete(&self, ec_hash: &str) -> Result<(), Report<TrustedServerError>> {
+    pub fn delete(&self, ec_id: &str) -> Result<(), Report<TrustedServerError>> {
         let store = self.open_store()?;
         store
-            .delete(ec_hash)
+            .delete(ec_id)
             .change_context(TrustedServerError::KvStore {
                 store_name: self.store_name.clone(),
-                message: format!("Failed to delete key '{ec_hash}'"),
+                message: format!("Failed to delete key '{ec_id}'"),
             })
     }
 }
diff --git a/crates/trusted-server-core/src/ec/kv_types.rs b/crates/trusted-server-core/src/ec/kv_types.rs
index fa0f256f..3297e1f7 100644
--- a/crates/trusted-server-core/src/ec/kv_types.rs
+++ b/crates/trusted-server-core/src/ec/kv_types.rs
@@ -1,7 +1,7 @@
 //! KV identity graph schema types.
 //!
 //! These types define the JSON schema stored in the Fastly KV Store for the
-//! EC identity graph. Each EC hash (64-char hex prefix) maps to a [`KvEntry`]
+//! EC identity graph. Each EC ID (`{64hex}.{6alnum}`) maps to a [`KvEntry`]
 //! containing consent state, geo location, and accumulated partner IDs.
 //!
 //! The schema is versioned (`v: 1`) to allow future migrations.
@@ -18,7 +18,7 @@ pub const SCHEMA_VERSION: u8 = 1;
 
 /// Full KV entry stored as the body of an EC identity graph record.
 ///
-/// **KV key:** 64-character hex hash (the stable prefix from the EC ID).
+/// **KV key:** Full EC ID (`{64hex}.{6alnum}`).
 /// **KV value:** JSON-serialized `KvEntry` (max ~5KB).
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct KvEntry {
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index c2593d68..f487abcb 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -261,12 +261,11 @@ impl EcContext {
         if let (Some(graph), Some(ec_value)) = (kv, self.ec_value.as_deref()) {
             let now = current_timestamp();
             let entry = KvEntry::new(&self.consent, self.geo_info.as_ref(), now);
-            let ec_hash = generation::ec_hash(ec_value);
 
-            if let Err(err) = graph.create_or_revive(ec_hash, &entry) {
+            if let Err(err) = graph.create_or_revive(ec_value, &entry) {
                 log::error!(
-                    "Failed to create or revive EC entry for hash '{}' after generation: {err:?}",
-                    ec_hash,
+                    "Failed to create or revive EC entry for id '{}' after generation: {err:?}",
+                    ec_value,
                 );
             }
         }
diff --git a/crates/trusted-server-core/src/ec/pull_sync.rs b/crates/trusted-server-core/src/ec/pull_sync.rs
index 298671ef..3b599c16 100644
--- a/crates/trusted-server-core/src/ec/pull_sync.rs
+++ b/crates/trusted-server-core/src/ec/pull_sync.rs
@@ -23,15 +23,15 @@ use super::EcContext;
 /// Inputs needed to dispatch pull sync after response flush.
 #[derive(Debug, Clone)]
 pub struct PullSyncContext {
-    ec_hash: String,
+    ec_id: String,
     client_ip: String,
 }
 
 impl PullSyncContext {
-    /// Returns the stable EC hash for the request.
+    /// Returns the EC ID for the request.
     #[must_use]
-    pub fn ec_hash(&self) -> &str {
-        &self.ec_hash
+    pub fn ec_id(&self) -> &str {
+        &self.ec_id
     }
 
     /// Returns the normalized client IP for pull endpoint query parameters.
@@ -53,7 +53,7 @@ struct PullSyncResponse {
 
 /// Builds post-send pull-sync context from the route EC context.
 ///
-/// Returns `None` when consent denies EC, there is no active EC hash, or no
+/// Returns `None` when consent denies EC, there is no active EC ID, or no
 /// client IP is available.
 #[must_use]
 pub fn build_pull_sync_context(ec_context: &EcContext) -> Option<PullSyncContext> {
@@ -67,9 +67,9 @@ pub fn build_pull_sync_context(ec_context: &EcContext) -> Option<PullSyncContext
         return None;
     }
 
-    let ec_hash = ec_context.ec_hash()?.to_owned();
+    let ec_id = ec_context.ec_value()?.to_owned();
     let client_ip = ec_context.client_ip()?.to_owned();
-    Some(PullSyncContext { ec_hash, client_ip })
+    Some(PullSyncContext { ec_id, client_ip })
 }
 
 /// Dispatches partner pull-sync requests in the background.
@@ -83,12 +83,12 @@ pub fn dispatch_pull_sync(
     context: &PullSyncContext,
 ) {
     let now = current_timestamp();
-    let kv_entry = match kv.get(context.ec_hash()) {
+    let kv_entry = match kv.get(context.ec_id()) {
         Ok(entry) => entry.map(|(entry, _)| entry),
         Err(err) => {
             log::warn!(
                 "Pull sync: failed to read identity graph for '{}': {err:?}",
-                context.ec_hash()
+                context.ec_id()
             );
             return;
         }
@@ -136,13 +136,13 @@ pub fn dispatch_pull_sync(
             continue;
         };
 
-        let rate_key = format!("pull:{}:{}", partner.id, context.ec_hash());
+        let rate_key = format!("pull:{}:{}", partner.id, context.ec_id());
         match rate_limiter.exceeded(&rate_key, partner.pull_sync_rate_limit) {
             Ok(true) => {
                 log::debug!(
-                    "Pull sync: rate-limited partner '{}' for hash '{}'",
+                    "Pull sync: rate-limited partner '{}' for ec_id '{}'",
                     partner.id,
-                    context.ec_hash()
+                    context.ec_id()
                 );
                 continue;
             }
@@ -164,7 +164,7 @@ pub fn dispatch_pull_sync(
             continue;
         };
 
-        let request_url = build_pull_request_url(url, context.ec_hash(), context.client_ip());
+        let request_url = build_pull_request_url(url, context.ec_id(), context.client_ip());
         let mut request = Request::new(Method::GET, request_url.as_str());
         request.set_header("authorization", format!("Bearer {token}"));
 
@@ -197,11 +197,11 @@ pub fn dispatch_pull_sync(
         });
 
         if in_flight.len() >= max_concurrency {
-            drain_pull_batch(kv, context.ec_hash(), &mut in_flight);
+            drain_pull_batch(kv, context.ec_id(), &mut in_flight);
         }
     }
 
-    drain_pull_batch(kv, context.ec_hash(), &mut in_flight);
+    drain_pull_batch(kv, context.ec_id(), &mut in_flight);
 }
 
 fn is_partner_pull_eligible(partner: &PartnerRecord, kv_entry: Option<&KvEntry>, now: u64) -> bool {
@@ -266,15 +266,15 @@ fn validated_pull_sync_url(partner: &PartnerRecord) -> Option<Url> {
     Some(parsed)
 }
 
-fn build_pull_request_url(mut base_url: Url, ec_hash: &str, client_ip: &str) -> Url {
+fn build_pull_request_url(mut base_url: Url, ec_id: &str, client_ip: &str) -> Url {
     base_url
         .query_pairs_mut()
-        .append_pair("ec_hash", ec_hash)
+        .append_pair("ec_id", ec_id)
         .append_pair("ip", client_ip);
     base_url
 }
 
-fn drain_pull_batch(kv: &KvIdentityGraph, ec_hash: &str, in_flight: &mut Vec<InFlightPull>) {
+fn drain_pull_batch(kv: &KvIdentityGraph, ec_id: &str, in_flight: &mut Vec<InFlightPull>) {
     for pending in in_flight.drain(..) {
         let partner_id = pending.partner_id;
         let response = match pending.pending.wait() {
@@ -292,11 +292,11 @@ fn drain_pull_batch(kv: &KvIdentityGraph, ec_hash: &str, in_flight: &mut Vec<InF
             continue;
         };
 
-        if let Err(err) = kv.upsert_partner_id(ec_hash, &partner_id, &uid, current_timestamp()) {
+        if let Err(err) = kv.upsert_partner_id(ec_id, &partner_id, &uid, current_timestamp()) {
             log::warn!(
-                "Pull sync: failed to upsert partner '{}' for hash '{}': {err:?}",
+                "Pull sync: failed to upsert partner '{}' for ec_id '{}': {err:?}",
                 partner_id,
-                ec_hash
+                ec_id
             );
         }
     }
@@ -412,7 +412,10 @@ mod tests {
 
         let context = build_pull_sync_context(&ec_context)
             .expect("should build pull sync context for valid EC with IP");
-        assert_eq!(context.ec_hash(), "a".repeat(64).as_str());
+        assert_eq!(
+            context.ec_id(),
+            ec_context.ec_value().expect("ec should be present")
+        );
         assert_eq!(context.client_ip(), "1.2.3.4");
     }
 
@@ -497,11 +500,11 @@ mod tests {
     #[test]
     fn build_pull_request_url_appends_query_pairs() {
         let url = Url::parse("https://sync.partner.test/pull?x=1").expect("should parse URL");
-        let result = build_pull_request_url(url, "hash123", "1.2.3.4");
+        let result = build_pull_request_url(url, "ecid123", "1.2.3.4");
 
         let query = result.query().expect("should have query string");
         assert!(query.contains("x=1"), "should preserve existing query");
-        assert!(query.contains("ec_hash=hash123"), "should append ec_hash");
+        assert!(query.contains("ec_id=ecid123"), "should append ec_id");
         assert!(query.contains("ip=1.2.3.4"), "should append ip");
     }
 
diff --git a/crates/trusted-server-core/src/ec/sync_pixel.rs b/crates/trusted-server-core/src/ec/sync_pixel.rs
index 3ac157b3..b1bb9389 100644
--- a/crates/trusted-server-core/src/ec/sync_pixel.rs
+++ b/crates/trusted-server-core/src/ec/sync_pixel.rs
@@ -10,7 +10,7 @@ use crate::consent::{allows_ec_creation, gpp, tcf, ConsentContext};
 use crate::error::TrustedServerError;
 use crate::settings::Settings;
 
-use super::generation::{ec_hash, is_valid_ec_id};
+use super::generation::is_valid_ec_id;
 use super::kv::KvIdentityGraph;
 use super::partner::{PartnerRecord, PartnerStore};
 use super::EcContext;
@@ -72,19 +72,21 @@ pub fn handle_sync(
         return Ok(redirect_with_status(&return_url, "0", Some("no_consent")));
     }
 
-    let hash = ec_hash(&cookie_ec_id);
     let limiter = FastlyRateLimiter::new(RATE_COUNTER_NAME);
-    if limiter.exceeded(&format!("{}:{hash}", partner.id), partner.sync_rate_limit)? {
+    if limiter.exceeded(
+        &format!("{}:{cookie_ec_id}", partner.id),
+        partner.sync_rate_limit,
+    )? {
         return Ok(Response::from_status(StatusCode::TOO_MANY_REQUESTS)
             .with_body_text_plain("rate_limit_exceeded"));
     }
 
     let now = current_timestamp();
-    if let Err(err) = kv.upsert_partner_id(hash, &partner.id, &query.uid, now) {
+    if let Err(err) = kv.upsert_partner_id(&cookie_ec_id, &partner.id, &query.uid, now) {
         log::warn!(
-            "Pixel sync write failed for partner '{}' and hash '{}': {err:?}",
+            "Pixel sync write failed for partner '{}' and ec_id '{}': {err:?}",
             partner.id,
-            hash,
+            cookie_ec_id,
         );
         return Ok(redirect_with_status(&return_url, "0", Some("write_failed")));
     }
diff --git a/docs/guide/api-reference.md b/docs/guide/api-reference.md
index ee247fda..1dcb19bd 100644
--- a/docs/guide/api-reference.md
+++ b/docs/guide/api-reference.md
@@ -133,7 +133,7 @@ Returns EC identity plus resolved partner IDs and EIDs for the current user.
 
 ### POST /\_ts/api/v1/sync
 
-Server-to-server batch sync endpoint for writing EC hash to partner UID mappings.
+Server-to-server batch sync endpoint for writing EC ID to partner UID mappings.
 
 **Auth:** Bearer token (`Authorization: Bearer <partner-api-key>`)
 
@@ -143,7 +143,7 @@ Server-to-server batch sync endpoint for writing EC hash to partner UID mappings
 {
   "mappings": [
     {
-      "ec_hash": "954d8e7398dd993f78e3875ca1ef7841249781240e913157c1f2d6a6c960e0c3",
+      "ec_id": "954d8e7398dd993f78e3875ca1ef7841249781240e913157c1f2d6a6c960e0c3.nZ1GxL",
       "partner_uid": "mock-user-123",
       "timestamp": 1775147300
     }
diff --git a/docs/guide/ec-setup-guide.md b/docs/guide/ec-setup-guide.md
index a5dbc385..6a55cad1 100644
--- a/docs/guide/ec-setup-guide.md
+++ b/docs/guide/ec-setup-guide.md
@@ -49,7 +49,6 @@ PARTNER_API_KEY="test-batch-sync-key-2026"
 
 # Optional: use a real browser EC if already present
 EC_ID="<64hex.6chars>"
-EC_HASH="${EC_ID%%.*}"
 
 TCF_CONSENT="<euconsent-v2-string>"
 PARTNER_UID="mock-user-$(date +%s)"
@@ -146,7 +145,7 @@ Expected shape:
 
 Endpoint: `POST /_ts/api/v1/sync`
 
-Important: request field is `ec_hash` (not `ssc_hash`).
+Important: request field is `ec_id` (full `{64hex}.{6alnum}` value).
 
 ```bash
 BATCH_UID="${PARTNER_UID}-batch"
@@ -157,7 +156,7 @@ curl -X POST "${TS_BASE_URL}/_ts/api/v1/sync" \
   -H "Content-Type: application/json" \
   -d "{
     \"mappings\": [{
-      \"ec_hash\": \"${EC_HASH}\",
+      \"ec_id\": \"${EC_ID}\",
       \"partner_uid\": \"${BATCH_UID}\",
       \"timestamp\": ${NOW_TS}
     }]
@@ -226,7 +225,7 @@ fastly kv-store-entry get --store-id <partner-store-id> --key "${PARTNER_ID}"
 Inspect EC identity entry:
 
 ```bash
-fastly kv-store-entry get --store-id <identity-store-id> --key "${EC_HASH}"
+fastly kv-store-entry get --store-id <identity-store-id> --key "${EC_ID}"
 ```
 
 If pixel sync returns `write_failed`, check whether KV entry has:
@@ -238,7 +237,7 @@ If pixel sync returns `write_failed`, check whether KV entry has:
 | Symptom                                    | Likely Cause                           | Check                                     |
 | ------------------------------------------ | -------------------------------------- | ----------------------------------------- |
 | `invalid_token` on batch sync              | Wrong partner API key                  | Re-register partner with known API key    |
-| `missing field ec_hash`                    | Wrong request schema                   | Use `ec_hash` field                       |
+| `missing field ec_id`                      | Wrong request schema                   | Use `ec_id` field                         |
 | `ts_reason=no_consent`                     | Missing/invalid consent cookie         | Include valid `euconsent-v2`              |
 | `ts_reason=write_failed`                   | KV write blocked (often consent state) | Inspect identity KV entry and store links |
 | `/identify` returns `{"consent":"denied"}` | No consent for current request         | Send consent cookie                       |

From 22ef44310866ce0ed8c2f14eb385f6e16fc15a7f Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Mon, 6 Apr 2026 11:24:22 -0500
Subject: [PATCH 23/36] docs: update EC spec to reflect full EC ID used as KV
 key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses issue #612 - spec now correctly documents that the full EC ID
({64-hex}.{6-alnum}) is used as the KV store key, not just the 64-char
hash prefix.

Changes:
- Updated §4.1: ec_hash() now documented as for logging/debugging only
- Updated §7.2: KV key description changed from '64-character hex hash'
  to 'Full EC ID in {64-char hex}.{6-char alphanumeric} format'
- Updated §7.3: All KvIdentityGraph method parameters renamed from
  ec_hash to ec_id with proper documentation
- Updated §9.3: Batch sync request field renamed from ec_hash to ec_id
- Updated §9.4: Validation and error reasons updated (invalid_ec_hash
  → invalid_ec_id, ec_hash_not_found → ec_id_not_found)
- Updated §10.4: Pull sync URL parameter changed from ec_hash to ec_id
- Updated consent pipeline integration throughout to use full EC ID
- Updated all rate limiting descriptions (per EC ID, not per hash)

Rationale: The random suffix provides uniqueness for users behind the
same NAT/proxy infrastructure who would otherwise share identical
IP-derived hash prefixes.
---
 .../2026-03-24-ssc-technical-spec-design.md   | 168 +++++++++++-------
 1 file changed, 103 insertions(+), 65 deletions(-)

diff --git a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
index f88b9ab9..052620e0 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
@@ -161,9 +161,12 @@ pub fn generate_ec(passphrase: &str, ip: IpAddr) -> Result<String, Report<Truste
 ///   not choose between them.
 pub fn normalize_ip(ip: IpAddr) -> String;
 
-/// Extracts the stable 64-character hex prefix from a full EC value.
+/// Extracts the stable 64-character hex prefix from a full EC ID.
 ///
-/// The prefix is used as the KV store key. The `.suffix` is discarded.
+/// This is primarily used for logging and debugging. Both the EC identity
+/// KV store and the consent KV store use the **full EC ID** (including the
+/// `.suffix`) as the key, not just this prefix. The suffix provides uniqueness
+/// for users behind the same NAT/proxy infrastructure.
 ///
 /// Returns `None` if the value is not in `{64-hex}.{6-alnum}` format.
 pub fn ec_hash(ec_value: &str) -> Option<&str>;
@@ -179,7 +182,7 @@ pub fn ec_hash(ec_value: &str) -> Option<&str>;
 
 **Output format:** `{64-char lowercase hex}.{6-char random alphanumeric}`
 
-The random suffix is generated with `fastly::rand` (same approach as SyntheticID). Once set in a cookie the full value is preserved; only the hash prefix is used as the KV key.
+The random suffix is generated with `fastly::rand` (same approach as SyntheticID). Once set in a cookie, the full value (hash + suffix) is preserved and used as the KV store key for both the EC identity graph and the consent store. The suffix provides uniqueness for users behind the same NAT/proxy who share the same IP-derived hash.
 
 **IPv6 /64 prefix:** Split on `:`, take first 4 groups, join with `:`. Example:
 `2001:db8:85a3:0000:0000:8a2e:0370:7334` → `2001:db8:85a3:0`.
@@ -224,14 +227,14 @@ Generation (step 3 above becoming a new EC) happens only inside organic handlers
 /// one EC route that may replace `consent` with a locally-decoded fallback for
 /// the remainder of that request only.
 pub struct EcContext {
-    /// Full EC value (`hash.suffix`), if present on request or generated this request.
+    /// Full EC ID (`{64-hex}.{6-alnum}`), if present on request or generated this request.
     pub ec_value: Option<String>,
     /// Whether the `ts-ec` **cookie** was present on the inbound request.
     /// This is the only field that gates consent-withdrawal cookie deletion —
     /// the PRD's delete branch is conditioned on the cookie, not on X-ts-ec header.
     pub cookie_was_present: bool,
     /// The cookie's EC value, if different from `ec_value` (header won priority).
-    /// Used only for withdrawal: tombstone targets the cookie-derived hash to match
+    /// Used only for withdrawal: tombstone targets the cookie-derived EC ID to match
     /// existing SyntheticID revocation behavior (`publisher.rs:515`).
     /// `None` when cookie absent or cookie == header value.
     pub cookie_ec_value: Option<String>,
@@ -256,13 +259,13 @@ impl EcContext {
     /// Does not write to the **EC identity KV store**. Called pre-routing, like
     /// `GeoInfo::from_request()` in the current `main.rs`.
     ///
-    /// Calls `build_consent_context()` with the EC hash (when present) passed
+    /// Calls `build_consent_context()` with the full EC ID (when present) passed
     /// via `ConsentPipelineInput.identity_key` (renamed from `synthetic_id`
     /// in PR #479).
     ///
-    /// When an EC hash is available (returning user), this enables the consent
+    /// When an EC ID is available (returning user), this enables the consent
     /// pipeline's KV fallback (read) and KV persistence (write to the
-    /// **consent** KV store). On a first visit (no EC cookie), `ec_hash` is
+    /// **consent** KV store). On a first visit (no EC cookie), `ec_id` is
     /// `None` and no consent KV interaction occurs; consent is evaluated purely
     /// from request cookies/headers. This means consent is not persisted to
     /// consent KV until the user's second request. See §6.1.1.
@@ -293,13 +296,16 @@ impl EcContext {
     );
 
     /// Returns the stable 64-char hex prefix, or `None` if no EC.
+    /// 
+    /// Note: This extracts only the prefix for display/logging purposes. All KV
+    /// operations use the full EC ID (via `ec_value()`), not just this hash.
     pub fn ec_hash(&self) -> Option<&str>;
 }
 ```
 
 **`ec_finalize_response()` behavior** (signature: `ec_finalize_response(settings, geo, ec_context, kv, response)`):
 
-1. If `!allows_ec_creation(&consent) && cookie_was_present`: call `clear_ec_on_response()` (deletes cookie **and** strips any handler-built `X-ts-ec`, `X-ts-eids`, `X-ts-ec-consent`, `x-ts-eids-truncated`, and `X-ts-<partner_id>` response headers) and write withdrawal tombstones for each valid known EC hash (cookie-derived and, when different, header-derived). This runs on **every route** — consent withdrawal is always real-time enforced. Keyed on `cookie_was_present`, not `ec_was_present`, because only a cookie-held EC can be deleted by the browser. When the cookie is malformed and there is no valid header-derived hash, no tombstone is written.
+1. If `!allows_ec_creation(&consent) && cookie_was_present`: call `clear_ec_on_response()` (deletes cookie **and** strips any handler-built `X-ts-ec`, `X-ts-eids`, `X-ts-ec-consent`, `x-ts-eids-truncated`, and `X-ts-<partner_id>` response headers) and write withdrawal tombstones for each valid known EC ID (cookie-derived and, when different, header-derived). This runs on **every route** — consent withdrawal is always real-time enforced. Keyed on `cookie_was_present`, not `ec_was_present`, because only a cookie-held EC can be deleted by the browser. When the cookie is malformed and there is no valid header-derived EC ID, no tombstone is written.
 2. If `ec_was_present == true && ec_generated == false && allows_ec_creation(&consent)`: call `kv.update_last_seen()` (debounced). If `cookie_ec_value.is_some()`, also call `set_ec_on_response()` to reconcile the browser cookie to the authoritative header-derived EC.
 3. If `ec_generated == true`: call `set_ec_on_response()` — sets `Set-Cookie` and `X-ts-ec`. KV create already happened inside `generate_if_needed()`; `ec_finalize_response()` does NOT write KV beyond tombstones and `last_seen`.
 4. Handler-built response headers (`X-ts-ec`, `X-ts-eids` set directly by `/identify`) are preserved on non-withdrawal paths only.
@@ -353,7 +359,7 @@ pub fn clear_ec_on_response(response: &mut Response, cookie_domain: &str);
 
 ### 5.3 Response header
 
-`X-ts-ec: {ec_hash.suffix}` is set by `set_ec_on_response()` when an EC is available. In current behavior, `ec_finalize_response()` calls `set_ec_on_response()` for returning users (`ec_was_present == true && ec_generated == false && allows_ec_creation(&consent)`) and for newly generated ECs (`ec_generated == true`). `/identify` and `/auction` also set EC-related headers on their response paths.
+`X-ts-ec: {64-hex}.{6-alnum}` is set by `set_ec_on_response()` when an EC is available. In current behavior, `ec_finalize_response()` calls `set_ec_on_response()` for returning users (`ec_was_present == true && ec_generated == false && allows_ec_creation(&consent)`) and for newly generated ECs (`ec_generated == true`). `/identify` and `/auction` also set EC-related headers on their response paths.
 
 This header is added to `INTERNAL_HEADERS` in `constants.rs` so it is stripped before proxying to downstream backends, consistent with existing `X-ts-*` handling.
 
@@ -371,11 +377,11 @@ EcContext::read_from_request()
   If neither valid: ec_value = None
   ec_was_present = ec_value.is_some()
   cookie_was_present = ts-ec cookie raw key exists (regardless of validity)
-  ec_hash = ec_value.as_deref().and_then(ec_hash)   // None on first visit or malformed
-  build_consent_context(jar, req, config, geo, ec_hash) → consent: ConsentContext
-  // ec_hash is the identity key for consent KV (renamed from synthetic_id in PR #479).
-  // When ec_hash is Some: consent KV fallback read + consent KV write (to consent store, not EC store).
-  // When ec_hash is None (first visit): no consent KV interaction — cookies/headers only.
+  ec_id = ec_value.as_deref()   // None on first visit or malformed
+  build_consent_context(jar, req, config, geo, ec_id) → consent: ConsentContext
+  // ec_id (full value including suffix) is the identity key for consent KV (renamed from synthetic_id in PR #479).
+  // When ec_id is Some: consent KV fallback read + consent KV write (to consent store, not EC store).
+  // When ec_id is None (first visit): no consent KV interaction — cookies/headers only.
   ec_generated = false
 ```
 
@@ -389,7 +395,7 @@ ec_context.generate_if_needed(settings, &kv)    // best-effort — never 500s
           → generate_ec(passphrase, ip)
           → ec_value = Some(new_ec)
           → ec_generated = true
-          → kv.create_or_revive(ec_hash, &entry)   (best-effort, log warn if fails)
+          → kv.create_or_revive(new_ec, &entry)   (best-effort, log warn if fails)
             // create_or_revive overwrites a tombstone (ok=false) on re-consent
             // no-ops if a live entry (ok=true) already exists
 ```
@@ -399,18 +405,18 @@ ec_context.generate_if_needed(settings, &kv)    // best-effort — never 500s
 ```
   ├── !allows_ec_creation(&consent) && cookie_was_present?
   │       → clear_ec_on_response()             (delete cookie + strip ALL EC headers from response)
-  │       → // Tombstone all known valid EC hashes. May be 0, 1, or 2 hashes.
-  │         if let Some(cookie_hash) = cookie_ec_value.and_then(|v| ec_hash(&v)):
-  │           kv.write_withdrawal_tombstone(cookie_hash)       // cookie-derived hash
-  │         if let Some(header_hash) = ec_value.and_then(|v| ec_hash(&v)):
-  │           if Some(header_hash) != cookie_hash:
-  │             kv.write_withdrawal_tombstone(header_hash)     // header-derived hash (if different)
+  │       → // Tombstone all known valid EC IDs. May be 0, 1, or 2 IDs.
+  │         if let Some(cookie_ec_id) = cookie_ec_value.filter(|v| is_valid_ec_id(v)):
+  │           kv.write_withdrawal_tombstone(cookie_ec_id)       // cookie-derived EC ID
+  │         if let Some(header_ec_id) = ec_value.filter(|v| is_valid_ec_id(v)):
+  │           if Some(header_ec_id) != cookie_ec_id:
+  │             kv.write_withdrawal_tombstone(header_ec_id)     // header-derived EC ID (if different)
   │         // When cookie is malformed and no valid header exists: no tombstone written.
   │         // Cookie deletion is still the authoritative enforcement mechanism.
   │         // Tombstone fails? log error, do NOT block — no retry possible on browser path.
   │
   ├── ec_was_present == true && ec_generated == false && allows_ec_creation(&consent)?
-  │       → kv.update_last_seen(ec_hash, now())   (returning user — debounced at 300s)
+  │       → kv.update_last_seen(ec_id, now())   (returning user — debounced at 300s)
   │       → set_ec_on_response()   (Set-Cookie + X-ts-ec refresh on returning user)
   │
   └── ec_generated == true?
@@ -448,14 +454,14 @@ the consent module; EC only consumes that existing decision.
 
 **Consent pipeline integration:**
 
-`EcContext::read_from_request()` calls `build_consent_context()` with the EC hash as the identity key, passed via `ConsentPipelineInput.identity_key` (renamed from `synthetic_id` in PR #479). The consent pipeline's KV persistence and fallback behavior works with EC hashes:
+`EcContext::read_from_request()` calls `build_consent_context()` with the full EC ID as the identity key, passed via `ConsentPipelineInput.identity_key` (renamed from `synthetic_id` in PR #479). The consent pipeline's KV persistence and fallback behavior works with full EC IDs:
 
-- **Returning user** (EC cookie present → `ec_hash` is `Some`): consent KV fallback read is available when consent cookies are absent; consent KV write persists cookie-sourced consent for future requests. Note: `build_consent_context()` calls `try_kv_write()` internally, so phase 1 writes to the **consent** KV store (not the EC identity store).
-- **First visit** (no EC cookie → `ec_hash` is `None`): no consent KV interaction. Consent is evaluated purely from request cookies/headers. The gap: consent is not persisted to consent KV on the first request. This is accepted — in regulated jurisdictions (GDPR, US state), consent cookies/headers must be present for `allows_ec_creation()` to return `true`, so there is always a signal to persist on the next request. In non-regulated jurisdictions, `allows_ec_creation()` returns `true` without consent signals, so there is nothing to persist anyway. Consent KV persistence begins on the second request when the EC cookie is present.
+- **Returning user** (EC cookie present → `ec_id` is `Some`): consent KV fallback read is available when consent cookies are absent; consent KV write persists cookie-sourced consent for future requests. Note: `build_consent_context()` calls `try_kv_write()` internally, so phase 1 writes to the **consent** KV store (not the EC identity store).
+- **First visit** (no EC cookie → `ec_id` is `None`): no consent KV interaction. Consent is evaluated purely from request cookies/headers. The gap: consent is not persisted to consent KV on the first request. This is accepted — in regulated jurisdictions (GDPR, US state), consent cookies/headers must be present for `allows_ec_creation()` to return `true`, so there is always a signal to persist on the next request. In non-regulated jurisdictions, `allows_ec_creation()` returns `true` without consent signals, so there is nothing to persist anyway. Consent KV persistence begins on the second request when the EC cookie is present.
 
-**Consent store keying:** Old consent KV entries under SyntheticID keys become orphaned after PR #479 ships. New entries are keyed by EC hash. Orphaned entries expire via TTL — no explicit migration is performed.
+**Consent store keying:** Old consent KV entries under SyntheticID keys become orphaned after PR #479 ships. New entries are keyed by full EC ID (including suffix). Orphaned entries expire via TTL — no explicit migration is performed.
 
-**Rollout impact:** At cutover, returning users who relied on consent KV fallback (consent cookies absent, consent loaded from KV under SyntheticID key) will lose that fallback until a new EC-keyed consent entry is written on a subsequent request where consent cookies are present. This is a one-time window: once the EC cookie is set and a request with consent cookies arrives, the consent KV entry is written under the EC hash and fallback works again. The window duration depends on how quickly users return with consent cookies. This is accepted — consent cookies are the primary signal; KV fallback is a secondary mechanism for when cookies are blocked or absent.
+**Rollout impact:** At cutover, returning users who relied on consent KV fallback (consent cookies absent, consent loaded from KV under SyntheticID key) will lose that fallback until a new EC-keyed consent entry is written on a subsequent request where consent cookies are present. This is a one-time window: once the EC cookie is set and a request with consent cookies arrives, the consent KV entry is written under the full EC ID and fallback works again. The window duration depends on how quickly users return with consent cookies. This is accepted — consent cookies are the primary signal; KV fallback is a secondary mechanism for when cookies are blocked or absent.
 
 All downstream EC logic calls `allows_ec_creation(&self.consent)`. No consent decoding or gating logic is added in this epic.
 
@@ -464,15 +470,15 @@ All downstream EC logic calls `allows_ec_creation(&self.consent)`. No consent de
 When `allows_ec_creation(&consent)` returns `false` for a user whose **`ts-ec` cookie** is present (`cookie_was_present == true`). A user identified only by the `X-ts-ec` request header is not subject to cookie deletion — there is no cookie to expire.
 
 1. Issue `Set-Cookie: ts-ec=; Max-Age=0; ...` and strip all EC response headers (synchronous — must not fail silently). This always happens when `cookie_was_present == true`.
-2. Write tombstone for each valid EC hash available (`cookie_ec_value` and/or `ec_value`). When neither is valid (malformed cookie, no header), **no tombstone is written** — cookie deletion alone is the enforcement mechanism. When at least one valid hash exists: `kv.write_withdrawal_tombstone(hash)` sets `consent.ok = false`, clears partner IDs, TTL 24h — approximately 25ms per write.
+2. Write tombstone for each valid EC ID available (`cookie_ec_value` and/or `ec_value`). When neither is valid (malformed cookie, no header), **no tombstone is written** — cookie deletion alone is the enforcement mechanism. When at least one valid EC ID exists: `kv.write_withdrawal_tombstone(ec_id)` sets `consent.ok = false`, clears partner IDs, TTL 24h — approximately 25ms per write.
 
 The tombstone write runs in the request path (not async) to ensure real-time enforcement. Using a tombstone rather than a hard delete preserves the `consent_withdrawn` signal for batch sync clients for 24 hours — otherwise batch sync cannot distinguish consent withdrawal from an EC that never existed.
 
 If the tombstone write fails:
 
-- Log at `error` level with EC hash
+- Log at `error` level with EC ID
 - Do not block the response — cookie deletion is the primary enforcement mechanism
-- **No retry is possible on the browser path.** Once the cookie is deleted, subsequent browser requests carry no EC value (`ec_hash()` returns `None`), so there is no hash to tombstone. A failed tombstone means batch sync clients may see `ec_hash_not_found` (after TTL expiry) rather than `consent_withdrawn` — this is accepted degradation. The cookie deletion remains the authoritative enforcement mechanism.
+- **No retry is possible on the browser path.** Once the cookie is deleted, subsequent browser requests carry no EC value (`ec_value` returns `None`), so there is no EC ID to tombstone. A failed tombstone means batch sync clients may see `ec_id_not_found` (after TTL expiry) rather than `consent_withdrawn` — this is accepted degradation. The cookie deletion remains the authoritative enforcement mechanism.
 
 ---
 
@@ -484,12 +490,12 @@ Two KV stores are used. Their names are configured in `trusted-server.toml`:
 
 | Store            | TOML key           | Purpose                            |
 | ---------------- | ------------------ | ---------------------------------- |
-| Identity graph   | `ec.ec_store`      | EC hash → identity JSON            |
+| Identity graph   | `ec.ec_store`      | EC ID → identity JSON              |
 | Partner registry | `ec.partner_store` | Partner ID → config + API key hash |
 
 ### 7.2 Identity graph schema
 
-**KV key:** 64-character hex hash (the stable prefix from `ec_value`, without `.suffix`).
+**KV key:** Full EC ID in `{64-char hex}.{6-char alphanumeric}` format. The random suffix is intentionally included to provide uniqueness for users behind the same NAT/proxy infrastructure who would otherwise share identical IP-derived hash prefixes.
 
 **KV value (JSON, max ~5KB):**
 
@@ -521,7 +527,7 @@ Two KV stores are used. Their names are configured in `trusted-server.toml`:
 { "ok": true, "country": "US", "v": 1 }
 ```
 
-The `ok` field in metadata is a **historical consent record for S2S consumers only** — it is set to `false` by `write_withdrawal_tombstone()` so that batch sync clients (`POST /_ts/api/v1/sync`) can return `consent_withdrawn` rather than `ec_hash_not_found` during the 24-hour tombstone TTL.
+The `ok` field in metadata is a **historical consent record for S2S consumers only** — it is set to `false` by `write_withdrawal_tombstone()` so that batch sync clients (`POST /_ts/api/v1/sync`) can return `consent_withdrawn` rather than `ec_id_not_found` during the 24-hour tombstone TTL.
 
 **`consent.ok` is NOT used to make the withdrawal decision on the main request path.** Consent withdrawal is determined entirely from `allows_ec_creation(&ec_context.consent)` on the current request. When withdrawal is detected, the cookie is deleted and `write_withdrawal_tombstone()` is called in-path (setting `ok = false`, 24h TTL — see §6.2). Engineers must not add a KV read to the consent withdrawal hot path based on this field.
 
@@ -580,22 +586,34 @@ impl KvIdentityGraph {
     pub fn new(store_name: impl Into<String>) -> Self;
 
     /// Reads the full entry, returning the generation marker for CAS writes.
+    ///
+    /// # Arguments
+    ///
+    /// * `ec_id` — The full EC ID (`{64-hex}.{6-alnum}`) used as the KV key.
     pub fn get(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
     ) -> Result<Option<(KvEntry, u64)>, Report<TrustedServerError>>;
 
     /// Reads only the metadata fields (consent flag, country).
+    ///
+    /// # Arguments
+    ///
+    /// * `ec_id` — The full EC ID (`{64-hex}.{6-alnum}`) used as the KV key.
     pub fn get_metadata(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
     ) -> Result<Option<KvMetadata>, Report<TrustedServerError>>;
 
     /// Creates a new entry. Returns `Ok(())` if successful, `Err` if the key
     /// already exists (concurrent create) or on KV error.
+    ///
+    /// # Arguments
+    ///
+    /// * `ec_id` — The full EC ID (`{64-hex}.{6-alnum}`) used as the KV key.
     pub fn create(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
         entry: &KvEntry,
     ) -> Result<(), Report<TrustedServerError>>;
 
@@ -611,9 +629,13 @@ impl KvIdentityGraph {
     /// Called by `generate_if_needed()` instead of `create()`. This ensures that
     /// re-consent recovery is immediate — a user who withdraws and then re-consents
     /// within the 24-hour tombstone window gets a fresh identity entry without delay.
+    ///
+    /// # Arguments
+    ///
+    /// * `ec_id` — The full EC ID (`{64-hex}.{6-alnum}`) used as the KV key.
     pub fn create_or_revive(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
         entry: &KvEntry,
     ) -> Result<(), Report<TrustedServerError>>;
 
@@ -629,11 +651,15 @@ impl KvIdentityGraph {
     /// This recovery path is intentional: it materializes the graph later when
     /// the initial best-effort `create_or_revive()` on EC generation failed.
     /// Batch sync still performs its explicit existence/tombstone check before
-    /// calling this method, so `POST /_ts/api/v1/sync` retains its `ec_hash_not_found`
+    /// calling this method, so `POST /_ts/api/v1/sync` retains its `ec_id_not_found`
     /// contract.
+    ///
+    /// # Arguments
+    ///
+    /// * `ec_id` — The full EC ID (`{64-hex}.{6-alnum}`) used as the KV key.
     pub fn upsert_partner_id(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
         partner_id: &str,
         uid: &str,
         synced: u64,
@@ -643,9 +669,13 @@ impl KvIdentityGraph {
     /// 300 seconds older than `timestamp`. This debounce prevents KV write
     /// thrashing under bursty traffic — Fastly KV enforces a 1 write/sec limit
     /// per key. Callers should log `warn` on failure and continue.
+    ///
+    /// # Arguments
+    ///
+    /// * `ec_id` — The full EC ID (`{64-hex}.{6-alnum}`) used as the KV key.
     pub fn update_last_seen(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
         timestamp: u64,
     ) -> Result<(), Report<TrustedServerError>>;
 
@@ -654,21 +684,29 @@ impl KvIdentityGraph {
     /// Instead of hard-deleting the KV entry, this overwrites it with
     /// `consent.ok = false`, clears all partner IDs, and sets a 24-hour TTL.
     /// The tombstone allows batch sync clients (`POST /_ts/api/v1/sync`) to return
-    /// `consent_withdrawn` rather than `ec_hash_not_found` for the tombstone TTL.
+    /// `consent_withdrawn` rather than `ec_id_not_found` for the tombstone TTL.
     ///
     /// After the 24-hour TTL expires, the entry is gone. Any subsequent `get()`
-    /// returns `None` (`ec_hash_not_found`) — the distinction is time-bounded.
+    /// returns `None` (`ec_id_not_found`) — the distinction is time-bounded.
     ///
     /// Caller must handle `Err` by logging at `error` level; the cookie deletion
     /// in `ec_finalize_response()` is the primary enforcement mechanism.
+    ///
+    /// # Arguments
+    ///
+    /// * `ec_id` — The full EC ID (`{64-hex}.{6-alnum}`) used as the KV key.
     pub fn write_withdrawal_tombstone(
         &self,
-        ec_hash: &str,
+        ec_id: &str,
     ) -> Result<(), Report<TrustedServerError>>;
 
     /// Hard-deletes the entry. Used only for data deletion requests (IAB deletion
     /// framework — deferred). For consent withdrawal, use `write_withdrawal_tombstone()`.
-    pub fn delete(&self, ec_hash: &str) -> Result<(), Report<TrustedServerError>>;
+    ///
+    /// # Arguments
+    ///
+    /// * `ec_id` — The full EC ID (`{64-hex}.{6-alnum}`) used as the KV key.
+    pub fn delete(&self, ec_id: &str) -> Result<(), Report<TrustedServerError>>;
 }
 ```
 
@@ -748,10 +786,10 @@ pub async fn handle_sync(
 
    `!allows_ec_creation(...)` → redirect to {return}?ts_synced=0&ts_reason=no_consent
 
-6. Check anti-stuffing rate limit (sync_rate_limit per EC hash per partner per hour).
+6. Check anti-stuffing rate limit (sync_rate_limit per EC ID per partner per hour).
    Exceeded → `429 Too Many Requests` (no redirect — the `return` URL is never called).
 
-7. kv.upsert_partner_id(ec_hash, partner_id, uid, now())
+7. kv.upsert_partner_id(ec_id, partner_id, uid, now())
    If the root KV entry is missing (e.g. initial `create_or_revive()` failed on
    the organic page load), `upsert_partner_id()` creates a minimal live entry and
    then writes `ids[partner_id]`. This is the recovery path for best-effort EC
@@ -785,7 +823,7 @@ Do not modify any other query parameters on the `return` URL.
 
 - `return` URL validated by exact hostname match against `partner.allowed_return_domains`. No subdomain wildcard matching.
 - No HMAC signature required on inbound sync request.
-- Rate limit: `partner.sync_rate_limit` writes per EC hash per partner per hour. Default: 100. Configurable per partner in `partner_store`.
+- Rate limit: `partner.sync_rate_limit` writes per EC ID per partner per hour. Default: 100. Configurable per partner in `partner_store`.
 
 ---
 
@@ -830,7 +868,7 @@ Authorization: Bearer <api_key>
 {
   "mappings": [
     {
-      "ec_hash": "<64-character hex hash>",
+      "ec_id": "<full EC ID: {64-hex}.{6-alnum}>",
       "partner_uid": "abc123",
       "timestamp": 1741824000
     }
@@ -846,9 +884,9 @@ The authenticated partner's ID (from the `PartnerRecord` resolved via API key in
 
 For each mapping:
 
-1. Validate `ec_hash` format (must be exactly 64 lowercase hex characters). Invalid format → reject with `reason: "invalid_ec_hash"`.
-2. Read KV metadata for `ec_hash`. If not found → reject with `reason: "ec_hash_not_found"`. If `consent.ok = false` → reject with `reason: "consent_withdrawn"`.
-3. `kv.upsert_partner_id(ec_hash, partner_id, partner_uid, timestamp)`. The upsert internally skips the write if the existing `ids[partner_id].synced ≥ timestamp` (idempotent — counted as accepted, no error). On KV failure → reject all remaining mappings with `reason: "kv_unavailable"`, return `207`.
+1. Validate `ec_id` format (must match `{64-hex}.{6-alnum}` pattern). Invalid format → reject with `reason: "invalid_ec_id"`.
+2. Read KV metadata for `ec_id`. If not found → reject with `reason: "ec_id_not_found"`. If `consent.ok = false` → reject with `reason: "consent_withdrawn"`.
+3. `kv.upsert_partner_id(ec_id, partner_id, partner_uid, timestamp)`. The upsert internally skips the write if the existing `ids[partner_id].synced ≥ timestamp` (idempotent — counted as accepted, no error). On KV failure → reject all remaining mappings with `reason: "kv_unavailable"`, return `207`.
 
 ### 9.5 Response format
 
@@ -857,7 +895,7 @@ For each mapping:
   "accepted": 998,
   "rejected": 2,
   "errors": [
-    { "index": 45, "reason": "ec_hash_not_found" },
+    { "index": 45, "reason": "ec_id_not_found" },
     { "index": 72, "reason": "consent_withdrawn" }
   ]
 }
@@ -889,10 +927,10 @@ pub struct BatchSyncError {
 
 #[derive(Debug, derive_more::Display)]
 pub enum BatchSyncRejection {
-    #[display("invalid_ec_hash")]
-    InvalidEcHash,
-    #[display("ec_hash_not_found")]
-    EcHashNotFound,
+    #[display("invalid_ec_id")]
+    InvalidEcId,
+    #[display("ec_id_not_found")]
+    EcIdNotFound,
     #[display("consent_withdrawn")]
     ConsentWithdrawn,
     #[display("kv_unavailable")]
@@ -936,7 +974,7 @@ impl PullSyncDispatcher {
 /// Fires a single partner pull request via `send_async()`, waits for the
 /// response via `PendingRequest::wait()`, and writes the result to KV.
 fn pull_one_partner(
-    ec_hash: &str,
+    ec_id: &str,
     ip: IpAddr,
     partner: &PartnerRecord,
     kv: &KvIdentityGraph,
@@ -955,7 +993,7 @@ A pull sync is dispatched for a partner when all of the following are true on a
 3. `allows_ec_creation(&ec_context.consent) == true`
 4. `partner.pull_sync_enabled == true`
 5. Either: no entry exists for this partner in the KV graph, or the existing `synced` timestamp is older than `partner.pull_sync_ttl_sec` (default 86400 seconds)
-6. Rate limit not exceeded: `partner.pull_sync_rate_limit` calls per EC hash per partner per hour (default 10)
+6. Rate limit not exceeded: `partner.pull_sync_rate_limit` calls per EC ID per partner per hour (default 10)
 
 ### 10.3 Execution model
 
@@ -968,13 +1006,13 @@ Maximum concurrent pull calls per request: `settings.ec.pull_sync_concurrency` (
 ### 10.4 Outbound request
 
 ```
-GET {partner.pull_sync_url}?ec_hash={64-char-hex}&ip={ip_address}
+GET {partner.pull_sync_url}?ec_id={64-hex}.{6-alnum}&ip={ip_address}
 Authorization: Bearer {partner.ts_pull_token}
 ```
 
 Before dispatching, `pull_sync.rs` validates that `pull_sync_url`'s hostname is present in `partner.pull_sync_allowed_domains`. If not, the call is skipped and an `error` is logged — this is a configuration error that should not occur at runtime if admin validation is working correctly (§13.2 step 3).
 
-Only the EC hash and IP are sent. No consent strings, geo data, or other partner IDs are included.
+Only the full EC ID and IP are sent. No consent strings, geo data, or other partner IDs are included.
 
 **Expected partner responses:**
 
@@ -989,7 +1027,7 @@ Any other non-200 response is treated as a transient failure. No retry. The next
 
 ### 10.5 KV write on success
 
-On a non-null `uid`: call `kv.upsert_partner_id(ec_hash, partner_id, uid, now())`. If the root entry is missing, the upsert creates a minimal live entry first (same recovery path as `/sync`). On KV failure: log `warn` and discard the result. Retry occurs on the next qualifying request.
+On a non-null `uid`: call `kv.upsert_partner_id(ec_id, partner_id, uid, now())`. If the root entry is missing, the upsert creates a minimal live entry first (same recovery path as `/sync`). On KV failure: log `warn` and discard the result. Retry occurs on the next qualifying request.
 
 The write updates `ids[partner_id].synced` to the current timestamp, resetting the `pull_sync_ttl_sec` window.
 
@@ -1097,7 +1135,7 @@ Set on `200` responses only:
 
 | Header              | Value                                                                                                                                                                                                                                                                                                                           |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `X-ts-ec`           | `{ec_hash.suffix}`                                                                                                                                                                                                                                                                                                              |
+| `X-ts-ec`           | `{64-hex}.{6-alnum}` — full EC ID                                                                                                                                                                                                                                                                                              |
 | `X-ts-eids`         | Standard base64 (RFC 4648, with `=` padding) of the JSON array of OpenRTB 2.6 `user.eids` objects. Capped at **4 KB** after encoding. If the encoded value exceeds 4 KB, the array is truncated (fewest partners first — highest `synced` timestamp retained) until it fits, and a `x-ts-eids-truncated: true` header is added. |
 | `X-ts-<partner_id>` | Resolved UID per partner (e.g., `X-ts-uid2`). One header per partner with a resolved UID. **Capped at 20 partners** — partners sorted by most-recently synced; excess partners are omitted silently.                                                                                                                            |
 | `X-ts-ec-consent`   | `ok` (always — denied consent returns `403`, not `200`)                                                                                                                                                                                                                                                                         |
@@ -1220,7 +1258,7 @@ The current `/auction` path returns a JSON response inline to the JS caller (`en
 
 | Header                | Value                                                                                                              |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `X-ts-ec`             | `{ec_hash.suffix}` — when EC is present                                                                            |
+| `X-ts-ec`             | `{64-hex}.{6-alnum}` — full EC ID, when EC is present                                                              |
 | `X-ts-eids`           | Standard base64 (RFC 4648) of OpenRTB 2.6 `user.eids` JSON array. Capped at 4 KB — same truncation rules as §11.5. |
 | `X-ts-eids-truncated` | `true` — present only when `X-ts-eids` was truncated                                                               |
 | `X-ts-ec-consent`     | `ok` — only present when consent granted; on withdrawal `ec_finalize_response()` strips all EC headers             |
@@ -2053,7 +2091,7 @@ their UIDs against a list of EC hashes.
 - API-key rate limit exceeded (`batch_rate_limit` per partner per minute) → `429`
   with `{ "error": "rate_limit_exceeded" }`.
 - More than 1000 mappings → `400`.
-- Per-mapping rejections: `invalid_ec_hash`, `ec_hash_not_found`,
+- Per-mapping rejections: `invalid_ec_id`, `ec_id_not_found`,
   `consent_withdrawn`, `kv_unavailable`.
 - KV write failure aborts remaining mappings with `kv_unavailable`; partial
   results returned as `207`.

From c4fa376941459115cfdf464f245a9fd36090f1ad Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Mon, 6 Apr 2026 10:48:50 -0500
Subject: [PATCH 24/36] Add ASN/DMA geo fields and publisher domain tracking to
 EC KV schema

Extends EC KV schema for cross-property identity resolution:

- Add asn field to GeoInfo (from Fastly geo.as_number())
- Add asn and dma fields to KvGeo for network identification
- Add KvDomainVisit and KvPubProperties for consortium-level domain tracking
- Add pub_properties field to KvEntry with 50-domain cap
- Track publisher domain visits in KvEntry::new() and update_last_seen()
- Respect existing 300s debounce for organic requests only

All new fields use Option types or serde(default) for backward compatibility.
Existing v1 entries continue to deserialize without error.
---
 .../src/consent/jurisdiction.rs               |   1 +
 crates/trusted-server-core/src/ec/finalize.rs |   4 +-
 crates/trusted-server-core/src/ec/kv.rs       | 208 +++++++++-
 crates/trusted-server-core/src/ec/kv_types.rs | 377 +++++++++++++++++-
 crates/trusted-server-core/src/ec/mod.rs      |   7 +-
 crates/trusted-server-core/src/geo.rs         |  47 ++-
 .../src/integrations/prebid.rs                |   4 +
 7 files changed, 632 insertions(+), 16 deletions(-)

diff --git a/crates/trusted-server-core/src/consent/jurisdiction.rs b/crates/trusted-server-core/src/consent/jurisdiction.rs
index df0c5b59..bcc825c5 100644
--- a/crates/trusted-server-core/src/consent/jurisdiction.rs
+++ b/crates/trusted-server-core/src/consent/jurisdiction.rs
@@ -100,6 +100,7 @@ mod tests {
             longitude: 0.0,
             metro_code: 0,
             region: region.map(str::to_owned),
+            asn: None,
         }
     }
 
diff --git a/crates/trusted-server-core/src/ec/finalize.rs b/crates/trusted-server-core/src/ec/finalize.rs
index c0642222..b4bc668b 100644
--- a/crates/trusted-server-core/src/ec/finalize.rs
+++ b/crates/trusted-server-core/src/ec/finalize.rs
@@ -67,7 +67,9 @@ pub fn ec_finalize_response(
     // Returning user: consent is granted and EC came from request.
     if ec_context.ec_was_present() && !ec_context.ec_generated() && consent_allows_ec {
         if let (Some(graph), Some(ec_id)) = (kv, ec_context.ec_value()) {
-            if let Err(err) = graph.update_last_seen(ec_id, current_timestamp()) {
+            if let Err(err) =
+                graph.update_last_seen(ec_id, current_timestamp(), &settings.publisher.domain)
+            {
                 log::error!("Failed to update last_seen for EC ID '{}': {err:?}", ec_id,);
             }
         }
diff --git a/crates/trusted-server-core/src/ec/kv.rs b/crates/trusted-server-core/src/ec/kv.rs
index d70192c3..0d966a7d 100644
--- a/crates/trusted-server-core/src/ec/kv.rs
+++ b/crates/trusted-server-core/src/ec/kv.rs
@@ -15,7 +15,8 @@ use fastly::kv_store::{InsertMode, KVStore};
 use crate::error::TrustedServerError;
 
 use super::current_timestamp;
-use super::kv_types::{KvEntry, KvMetadata};
+use super::generation::ec_hash;
+use super::kv_types::{KvDomainVisit, KvEntry, KvMetadata, KvNetwork, MAX_SEEN_DOMAINS};
 
 /// Maximum number of CAS retry attempts before giving up.
 const MAX_CAS_RETRIES: u32 = 3;
@@ -25,6 +26,11 @@ const MAX_CAS_RETRIES: u32 = 3;
 /// 1 write/sec limit per key.
 const LAST_SEEN_DEBOUNCE_SECS: u64 = 300;
 
+/// Maximum number of keys to request when counting hash-prefix matches
+/// for cluster size evaluation. Anything above this is clearly a large
+/// shared network; the exact count doesn't matter.
+const CLUSTER_LIST_LIMIT: u32 = 100;
+
 /// TTL for live entries (1 year), matching the EC cookie `Max-Age`.
 const ENTRY_TTL: Duration = Duration::from_secs(365 * 24 * 60 * 60);
 
@@ -522,6 +528,11 @@ impl KvIdentityGraph {
 
     /// Updates the `last_seen` timestamp with a 300-second debounce.
     ///
+    /// Also updates the [`KvPubProperties::seen_domains`] entry for the
+    /// given `domain`, incrementing visits and updating the `last` timestamp.
+    /// New domains are added if the [`MAX_SEEN_DOMAINS`] cap has not been
+    /// reached; otherwise the new domain is silently dropped.
+    ///
     /// Skips the write if the stored `last_seen` is within
     /// [`LAST_SEEN_DEBOUNCE_SECS`] of the new timestamp, or if the entry
     /// does not exist.
@@ -537,6 +548,7 @@ impl KvIdentityGraph {
         &self,
         ec_id: &str,
         timestamp: u64,
+        domain: &str,
     ) -> Result<(), Report<TrustedServerError>> {
         let (mut entry, generation) = match self.get(ec_id)? {
             Some(pair) => pair,
@@ -572,6 +584,34 @@ impl KvIdentityGraph {
         }
 
         entry.last_seen = timestamp;
+
+        // Update publisher domain visit history.
+        if let Some(ref mut props) = entry.pub_properties {
+            match props.seen_domains.get_mut(domain) {
+                Some(visit) => {
+                    visit.last = timestamp;
+                    visit.visits = visit.visits.saturating_add(1);
+                }
+                None => {
+                    if props.seen_domains.len() < MAX_SEEN_DOMAINS {
+                        props.seen_domains.insert(
+                            domain.to_owned(),
+                            KvDomainVisit {
+                                first: timestamp,
+                                last: timestamp,
+                                visits: 1,
+                            },
+                        );
+                    } else {
+                        log::debug!(
+                            "update_last_seen: seen_domains cap ({MAX_SEEN_DOMAINS}) reached \
+                             for '{ec_id}', dropping domain '{domain}'"
+                        );
+                    }
+                }
+            }
+        }
+
         let store = self.open_store()?;
         let (body, meta_str) = Self::serialize_entry(&entry, &self.store_name)?;
 
@@ -620,6 +660,120 @@ impl KvIdentityGraph {
             })
     }
 
+    /// Counts the number of keys sharing the same EC hash prefix.
+    ///
+    /// Uses the Fastly KV list API with a prefix filter, limited to
+    /// [`CLUSTER_LIST_LIMIT`] keys. If the limit is reached, the count
+    /// is capped — the exact number beyond the limit is not meaningful
+    /// for disambiguation.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store error.
+    pub fn count_hash_prefix_keys(
+        &self,
+        hash_prefix: &str,
+    ) -> Result<u32, Report<TrustedServerError>> {
+        let store = self.open_store()?;
+
+        // Request a single page of up to CLUSTER_LIST_LIMIT keys.
+        // The prefix ensures we only match EC IDs derived from the same
+        // IP+passphrase (i.e. same 64-hex hash).
+        let page = store
+            .build_list()
+            .prefix(hash_prefix)
+            .limit(CLUSTER_LIST_LIMIT)
+            .execute()
+            .change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!(
+                    "Failed to list keys with prefix '{}'",
+                    &hash_prefix[..hash_prefix.len().min(8)],
+                ),
+            })?;
+
+        #[allow(clippy::cast_possible_truncation)]
+        let count = page.keys().len() as u32;
+        Ok(count)
+    }
+
+    /// Evaluates and caches the cluster size for an EC entry.
+    ///
+    /// If the entry already has a `cluster_checked` timestamp within
+    /// `recheck_secs` of now, the cached `cluster_size` is returned
+    /// without performing a list API call.
+    ///
+    /// Otherwise, counts the number of keys sharing the same hash prefix
+    /// via [`count_hash_prefix_keys`](Self::count_hash_prefix_keys) and
+    /// writes the result back to the entry via CAS. The CAS write is
+    /// best-effort — on conflict, the computed value is still returned;
+    /// it will simply be re-evaluated on the next call.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store or list failure.
+    pub fn evaluate_cluster(
+        &self,
+        ec_id: &str,
+        entry: &KvEntry,
+        generation: u64,
+        recheck_secs: u64,
+    ) -> Result<Option<u32>, Report<TrustedServerError>> {
+        let now = current_timestamp();
+
+        // Check TTL — skip re-evaluation if the cached value is fresh enough.
+        if let Some(ref network) = entry.network {
+            if let Some(checked) = network.cluster_checked {
+                if now.saturating_sub(checked) < recheck_secs {
+                    log::trace!(
+                        "evaluate_cluster: cached cluster_size for '{ec_id}' \
+                         (age={}s, ttl={recheck_secs}s)",
+                        now.saturating_sub(checked),
+                    );
+                    return Ok(network.cluster_size);
+                }
+            }
+        }
+
+        // Compute cluster size via prefix list.
+        let hash_prefix = ec_hash(ec_id);
+        let cluster_size = self.count_hash_prefix_keys(hash_prefix)?;
+
+        log::debug!("evaluate_cluster: computed cluster_size={cluster_size} for '{ec_id}'");
+
+        // Best-effort CAS write-back — update the network field.
+        let mut updated_entry = entry.clone();
+        updated_entry.network = Some(KvNetwork {
+            cluster_size: Some(cluster_size),
+            cluster_checked: Some(now),
+        });
+
+        let store = self.open_store()?;
+        let (body, meta_str) = Self::serialize_entry(&updated_entry, &self.store_name)?;
+
+        match store
+            .build_insert()
+            .if_generation_match(generation)
+            .metadata(&meta_str)
+            .time_to_live(ENTRY_TTL)
+            .execute(ec_id, body.as_str())
+        {
+            Ok(()) => {}
+            Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
+                log::debug!(
+                    "evaluate_cluster: CAS conflict writing cluster_size for '{ec_id}', \
+                     returning computed value anyway"
+                );
+            }
+            Err(err) => {
+                // Log but don't fail — the computed value is still valid.
+                log::warn!("evaluate_cluster: failed to write cluster_size for '{ec_id}': {err}");
+            }
+        }
+
+        Ok(Some(cluster_size))
+    }
+
     /// Hard-deletes the entry.
     ///
     /// Reserved for the IAB data deletion framework (deferred). For consent
@@ -649,6 +803,7 @@ mod tests {
         assert_eq!(LAST_SEEN_DEBOUNCE_SECS, 300);
         assert_eq!(ENTRY_TTL, Duration::from_secs(31_536_000));
         assert_eq!(TOMBSTONE_TTL, Duration::from_secs(86_400));
+        assert_eq!(CLUSTER_LIST_LIMIT, 100);
     }
 
     #[test]
@@ -671,4 +826,55 @@ mod tests {
         let _: KvMetadata =
             serde_json::from_str(&meta).expect("should deserialize metadata back to KvMetadata");
     }
+
+    #[test]
+    fn evaluate_cluster_returns_cached_value_when_ttl_fresh() {
+        // When the entry has a recent cluster_checked timestamp, evaluate_cluster
+        // should return the cached value without touching the KV store.
+        // We verify this by using a non-existent store — if it tried to open
+        // the store, it would fail. The TTL-skip path exits before any store I/O.
+        let kv = KvIdentityGraph::new("nonexistent_store_for_ttl_test");
+        let ec_id = format!("{}.ABC123", "a".repeat(64));
+        let now = current_timestamp();
+
+        let mut entry = KvEntry::tombstone(now);
+        entry.consent.ok = true;
+        entry.network = Some(KvNetwork {
+            cluster_size: Some(5),
+            cluster_checked: Some(now), // just checked
+        });
+
+        // With a 3600s TTL, the cached value (checked just now) should be returned.
+        let result = kv.evaluate_cluster(&ec_id, &entry, 0, 3600);
+        let cluster_size = result.expect("should return cached value without store I/O");
+        assert_eq!(
+            cluster_size,
+            Some(5),
+            "should return cached cluster_size when within TTL"
+        );
+    }
+
+    #[test]
+    fn evaluate_cluster_requires_recheck_when_ttl_expired() {
+        // When cluster_checked is older than the TTL, evaluate_cluster must
+        // perform a list API call. Since the store doesn't exist, this should
+        // fail — confirming it didn't take the cached path.
+        let kv = KvIdentityGraph::new("nonexistent_store_for_ttl_test");
+        let ec_id = format!("{}.ABC123", "a".repeat(64));
+
+        let mut entry = KvEntry::tombstone(1000);
+        entry.consent.ok = true;
+        entry.network = Some(KvNetwork {
+            cluster_size: Some(5),
+            cluster_checked: Some(1000), // very old timestamp
+        });
+
+        // With a 3600s TTL, the old timestamp should trigger re-evaluation,
+        // which will fail because the store doesn't exist.
+        let result = kv.evaluate_cluster(&ec_id, &entry, 0, 3600);
+        assert!(
+            result.is_err(),
+            "should attempt store I/O when TTL expired, failing on missing store"
+        );
+    }
 }
diff --git a/crates/trusted-server-core/src/ec/kv_types.rs b/crates/trusted-server-core/src/ec/kv_types.rs
index 3297e1f7..7262ca55 100644
--- a/crates/trusted-server-core/src/ec/kv_types.rs
+++ b/crates/trusted-server-core/src/ec/kv_types.rs
@@ -16,6 +16,10 @@ use crate::geo::GeoInfo;
 /// Current schema version for KV entries.
 pub const SCHEMA_VERSION: u8 = 1;
 
+/// Maximum number of domains tracked in [`KvPubProperties::seen_domains`].
+/// When the cap is reached, new domains are silently dropped.
+pub const MAX_SEEN_DOMAINS: usize = 50;
+
 /// Full KV entry stored as the body of an EC identity graph record.
 ///
 /// **KV key:** Full EC ID (`{64hex}.{6alnum}`).
@@ -34,6 +38,12 @@ pub struct KvEntry {
     pub consent: KvConsent,
     /// Geo location sub-object.
     pub geo: KvGeo,
+    /// Publisher domain history for consortium-level identity sharing.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pub_properties: Option<KvPubProperties>,
+    /// Network cluster disambiguation data.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub network: Option<KvNetwork>,
     /// Map of partner ID namespace → synced UID record.
     /// Populated by pixel sync, batch sync, and pull sync operations.
     #[serde(default, skip_serializing_if = "HashMap::is_empty")]
@@ -63,6 +73,14 @@ pub struct KvGeo {
     /// ISO 3166-2 region code (e.g. `"CA"` for California).
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub region: Option<String>,
+    /// Autonomous System Number (e.g. `7922` = Comcast).
+    /// Primary signal for distinguishing home ISP vs. corporate VPN.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub asn: Option<u32>,
+    /// DMA/metro code (e.g. `807` = San Francisco).
+    /// Market-level targeting signal; not personal data.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub dma: Option<i64>,
 }
 
 /// A synced partner user ID within a KV entry.
@@ -74,6 +92,53 @@ pub struct KvPartnerId {
     pub synced: u64,
 }
 
+/// A single domain visit record within [`KvPubProperties::seen_domains`].
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct KvDomainVisit {
+    /// Unix timestamp (seconds) of first visit to this domain.
+    pub first: u64,
+    /// Unix timestamp (seconds) of most recent visit to this domain.
+    pub last: u64,
+    /// Lifetime visit count for this domain.
+    pub visits: u32,
+}
+
+/// Publisher domain history for consortium-level identity sharing.
+///
+/// Tracks which publisher properties a user has been seen on, keyed by apex
+/// domain. History only accumulates within a shared-passphrase group (same
+/// EC hash), so this does not enable cross-site tracking across unrelated
+/// publishers.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct KvPubProperties {
+    /// Apex domain where this EC entry was first created.
+    pub origin_domain: String,
+    /// Per-domain visit history, keyed by apex domain.
+    /// Updated on each organic request; capped at [`MAX_SEEN_DOMAINS`] entries.
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub seen_domains: HashMap<String, KvDomainVisit>,
+}
+
+/// Network cluster disambiguation data.
+///
+/// Tracks how many distinct EC entries share the same hash prefix. A high
+/// count indicates a shared network (corporate VPN, campus); a low count
+/// indicates an individual or household.
+///
+/// Written only by the `/identify` endpoint — the prefix-match list API
+/// call required to compute `cluster_size` is too expensive for the
+/// organic proxy hot path.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct KvNetwork {
+    /// Number of distinct EC suffixes matching this hash prefix.
+    /// `None` = not yet evaluated.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cluster_size: Option<u32>,
+    /// Unix timestamp (seconds) of last cluster check.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cluster_checked: Option<u64>,
+}
+
 /// Compact metadata stored alongside the KV entry body.
 ///
 /// Fastly KV metadata is limited to 2048 bytes and can be read without
@@ -86,12 +151,28 @@ pub struct KvMetadata {
     pub country: String,
     /// Mirrors [`KvEntry::v`].
     pub v: u8,
+    /// Mirrors [`KvNetwork::cluster_size`]. `None` = not yet evaluated.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cluster_size: Option<u32>,
 }
 
 impl KvEntry {
     /// Creates a new live entry from the current request context.
+    ///
+    /// `domain` is the publisher's apex domain (e.g. `"autoblog.com"`),
+    /// used to initialize the [`KvPubProperties`] origin and first visit.
     #[must_use]
-    pub fn new(consent: &ConsentContext, geo: Option<&GeoInfo>, now: u64) -> Self {
+    pub fn new(consent: &ConsentContext, geo: Option<&GeoInfo>, now: u64, domain: &str) -> Self {
+        let mut seen_domains = HashMap::new();
+        seen_domains.insert(
+            domain.to_owned(),
+            KvDomainVisit {
+                first: now,
+                last: now,
+                visits: 1,
+            },
+        );
+
         Self {
             v: SCHEMA_VERSION,
             created: now,
@@ -103,6 +184,11 @@ impl KvEntry {
                 updated: now,
             },
             geo: KvGeo::from_geo_info(geo),
+            pub_properties: Some(KvPubProperties {
+                origin_domain: domain.to_owned(),
+                seen_domains,
+            }),
+            network: None,
             ids: HashMap::new(),
         }
     }
@@ -135,7 +221,11 @@ impl KvEntry {
             geo: KvGeo {
                 country: "ZZ".to_owned(),
                 region: None,
+                asn: None,
+                dma: None,
             },
+            pub_properties: None,
+            network: None,
             ids,
         }
     }
@@ -163,7 +253,11 @@ impl KvEntry {
             geo: KvGeo {
                 country: "ZZ".to_owned(),
                 region: None,
+                asn: None,
+                dma: None,
             },
+            pub_properties: None,
+            network: None,
             ids: HashMap::new(),
         }
     }
@@ -177,6 +271,7 @@ impl KvMetadata {
             ok: entry.consent.ok,
             country: entry.geo.country.clone(),
             v: entry.v,
+            cluster_size: entry.network.as_ref().and_then(|n| n.cluster_size),
         }
     }
 }
@@ -188,13 +283,24 @@ impl KvGeo {
     #[must_use]
     pub fn from_geo_info(geo: Option<&GeoInfo>) -> Self {
         match geo {
-            Some(info) => Self {
-                country: info.country.clone(),
-                region: info.region.clone(),
-            },
+            Some(info) => {
+                let dma = if info.metro_code > 0 {
+                    Some(info.metro_code)
+                } else {
+                    None
+                };
+                Self {
+                    country: info.country.clone(),
+                    region: info.region.clone(),
+                    asn: info.asn,
+                    dma,
+                }
+            }
             None => Self {
                 country: "ZZ".to_owned(),
                 region: None,
+                asn: None,
+                dma: None,
             },
         }
     }
@@ -221,6 +327,7 @@ mod tests {
             longitude: -122.4194,
             metro_code: 807,
             region: Some("CA".to_owned()),
+            asn: Some(7922),
         }
     }
 
@@ -228,7 +335,7 @@ mod tests {
     fn entry_serialization_roundtrip() {
         let geo = sample_geo_info();
         let consent = sample_consent_context();
-        let mut entry = KvEntry::new(&consent, Some(&geo), 1741824000);
+        let mut entry = KvEntry::new(&consent, Some(&geo), 1741824000, "example.com");
         entry.ids.insert(
             "liveramp".to_owned(),
             KvPartnerId {
@@ -251,6 +358,8 @@ mod tests {
         assert!(deserialized.consent.ok, "should be a live entry");
         assert_eq!(deserialized.geo.country, "US");
         assert_eq!(deserialized.geo.region.as_deref(), Some("CA"));
+        assert_eq!(deserialized.geo.asn, Some(7922));
+        assert_eq!(deserialized.geo.dma, Some(807));
         assert_eq!(
             deserialized.ids.get("liveramp").map(|p| p.uid.as_str()),
             Some("LR_xyz"),
@@ -263,6 +372,7 @@ mod tests {
             ok: true,
             country: "US".to_owned(),
             v: 1,
+            cluster_size: None,
         };
 
         let json = serde_json::to_string(&meta).expect("should serialize KvMetadata");
@@ -272,15 +382,42 @@ mod tests {
         assert!(deserialized.ok, "should be ok=true");
         assert_eq!(deserialized.country, "US");
         assert_eq!(deserialized.v, 1);
+        assert!(deserialized.cluster_size.is_none());
+    }
+
+    #[test]
+    fn metadata_with_cluster_size_roundtrip() {
+        let meta = KvMetadata {
+            ok: true,
+            country: "US".to_owned(),
+            v: 1,
+            cluster_size: Some(3),
+        };
+
+        let json = serde_json::to_string(&meta).expect("should serialize KvMetadata");
+        let deserialized: KvMetadata =
+            serde_json::from_str(&json).expect("should deserialize KvMetadata");
+
+        assert_eq!(deserialized.cluster_size, Some(3));
+    }
+
+    #[test]
+    fn metadata_without_cluster_size_deserializes() {
+        // Simulates metadata stored before cluster_size was added.
+        let json = r#"{"ok":true,"country":"US","v":1}"#;
+        let meta: KvMetadata = serde_json::from_str(json).expect("should deserialize old metadata");
+
+        assert!(meta.cluster_size.is_none(), "should default to None");
     }
 
     #[test]
     fn metadata_fits_in_2048_bytes() {
-        // Worst case: long country code (though ISO 3166-1 is always 2 chars)
+        // Worst case: all fields populated.
         let meta = KvMetadata {
             ok: false,
             country: "XX".to_owned(),
             v: SCHEMA_VERSION,
+            cluster_size: Some(u32::MAX),
         };
         let json = serde_json::to_string(&meta).expect("should serialize KvMetadata");
         assert!(
@@ -294,7 +431,7 @@ mod tests {
     fn new_entry_has_correct_initial_state() {
         let consent = sample_consent_context();
         let geo = sample_geo_info();
-        let entry = KvEntry::new(&consent, Some(&geo), 1000);
+        let entry = KvEntry::new(&consent, Some(&geo), 1000, "example.com");
 
         assert_eq!(entry.v, SCHEMA_VERSION);
         assert_eq!(entry.created, 1000);
@@ -303,17 +440,33 @@ mod tests {
         assert_eq!(entry.consent.updated, 1000);
         assert_eq!(entry.geo.country, "US");
         assert!(entry.ids.is_empty(), "should have no partner IDs initially");
+
+        let props = entry
+            .pub_properties
+            .as_ref()
+            .expect("should have pub_properties");
+        assert_eq!(props.origin_domain, "example.com");
+        assert_eq!(props.seen_domains.len(), 1);
+        let visit = props
+            .seen_domains
+            .get("example.com")
+            .expect("should have origin domain visit");
+        assert_eq!(visit.first, 1000);
+        assert_eq!(visit.last, 1000);
+        assert_eq!(visit.visits, 1);
     }
 
     #[test]
     fn new_entry_without_geo_uses_zz() {
         let consent = ConsentContext::default();
-        let entry = KvEntry::new(&consent, None, 1000);
+        let entry = KvEntry::new(&consent, None, 1000, "example.com");
         assert_eq!(
             entry.geo.country, "ZZ",
             "should use ZZ when geo is unavailable"
         );
         assert!(entry.geo.region.is_none());
+        assert!(entry.geo.asn.is_none());
+        assert!(entry.geo.dma.is_none());
     }
 
     #[test]
@@ -323,6 +476,10 @@ mod tests {
         assert_eq!(entry.v, SCHEMA_VERSION);
         assert!(entry.consent.ok, "should be a live entry");
         assert_eq!(entry.geo.country, "ZZ");
+        assert!(
+            entry.pub_properties.is_none(),
+            "minimal entry should have no pub_properties"
+        );
         assert_eq!(entry.ids.len(), 1);
         let partner = entry.ids.get("ssp_x").expect("should have ssp_x entry");
         assert_eq!(partner.uid, "abc123");
@@ -338,13 +495,17 @@ mod tests {
         assert!(entry.ids.is_empty(), "tombstone should have no partner IDs");
         assert_eq!(entry.geo.country, "ZZ");
         assert_eq!(entry.consent.updated, 1741910400);
+        assert!(
+            entry.pub_properties.is_none(),
+            "tombstone should have no pub_properties"
+        );
     }
 
     #[test]
     fn metadata_from_entry_mirrors_fields() {
         let consent = sample_consent_context();
         let geo = sample_geo_info();
-        let entry = KvEntry::new(&consent, Some(&geo), 1000);
+        let entry = KvEntry::new(&consent, Some(&geo), 1000, "example.com");
         let meta = KvMetadata::from_entry(&entry);
 
         assert_eq!(meta.ok, entry.consent.ok);
@@ -383,4 +544,200 @@ mod tests {
             "None gpp should be omitted from JSON"
         );
     }
+
+    #[test]
+    fn none_geo_fields_omitted_from_json() {
+        let entry = KvEntry::tombstone(1000);
+        let json = serde_json::to_string(&entry).expect("should serialize");
+        assert!(
+            !json.contains("\"asn\""),
+            "None asn should be omitted from JSON"
+        );
+        assert!(
+            !json.contains("\"dma\""),
+            "None dma should be omitted from JSON"
+        );
+    }
+
+    #[test]
+    fn geo_with_asn_and_dma_roundtrips() {
+        let geo = KvGeo {
+            country: "US".to_owned(),
+            region: Some("CA".to_owned()),
+            asn: Some(7922),
+            dma: Some(807),
+        };
+        let json = serde_json::to_string(&geo).expect("should serialize KvGeo");
+        let deserialized: KvGeo = serde_json::from_str(&json).expect("should deserialize KvGeo");
+
+        assert_eq!(deserialized.asn, Some(7922));
+        assert_eq!(deserialized.dma, Some(807));
+    }
+
+    #[test]
+    fn geo_without_asn_deserializes_from_v1_json() {
+        // Simulates a KvGeo stored before asn/dma fields were added.
+        let v1_json = r#"{"country":"US","region":"CA"}"#;
+        let geo: KvGeo = serde_json::from_str(v1_json).expect("should deserialize v1 KvGeo");
+
+        assert_eq!(geo.country, "US");
+        assert_eq!(geo.region.as_deref(), Some("CA"));
+        assert!(geo.asn.is_none(), "asn should default to None");
+        assert!(geo.dma.is_none(), "dma should default to None");
+    }
+
+    #[test]
+    fn pub_properties_roundtrip() {
+        let consent = sample_consent_context();
+        let geo = sample_geo_info();
+        let entry = KvEntry::new(&consent, Some(&geo), 1000, "autoblog.com");
+
+        let json = serde_json::to_string(&entry).expect("should serialize");
+        let deserialized: KvEntry = serde_json::from_str(&json).expect("should deserialize");
+
+        let props = deserialized
+            .pub_properties
+            .expect("should have pub_properties");
+        assert_eq!(props.origin_domain, "autoblog.com");
+        assert_eq!(props.seen_domains.len(), 1);
+        let visit = props
+            .seen_domains
+            .get("autoblog.com")
+            .expect("should have origin visit");
+        assert_eq!(visit.first, 1000);
+        assert_eq!(visit.last, 1000);
+        assert_eq!(visit.visits, 1);
+    }
+
+    #[test]
+    fn none_pub_properties_omitted_from_json() {
+        let entry = KvEntry::tombstone(1000);
+        let json = serde_json::to_string(&entry).expect("should serialize");
+        assert!(
+            !json.contains("\"pub_properties\""),
+            "None pub_properties should be omitted from JSON, got: {json}"
+        );
+    }
+
+    #[test]
+    fn entry_without_pub_properties_deserializes() {
+        // Simulates an entry stored before pub_properties was added.
+        let json = r#"{
+            "v": 1,
+            "created": 1000,
+            "last_seen": 1000,
+            "consent": { "ok": true, "updated": 1000 },
+            "geo": { "country": "US" }
+        }"#;
+        let entry: KvEntry =
+            serde_json::from_str(json).expect("should deserialize entry without pub_properties");
+
+        assert!(
+            entry.pub_properties.is_none(),
+            "missing pub_properties should deserialize as None"
+        );
+    }
+
+    #[test]
+    fn domain_visit_roundtrip() {
+        let visit = KvDomainVisit {
+            first: 1000,
+            last: 2000,
+            visits: 5,
+        };
+        let json = serde_json::to_string(&visit).expect("should serialize");
+        let deserialized: KvDomainVisit = serde_json::from_str(&json).expect("should deserialize");
+
+        assert_eq!(deserialized.first, 1000);
+        assert_eq!(deserialized.last, 2000);
+        assert_eq!(deserialized.visits, 5);
+    }
+
+    #[test]
+    fn network_roundtrip() {
+        let network = KvNetwork {
+            cluster_size: Some(3),
+            cluster_checked: Some(1774921179),
+        };
+        let json = serde_json::to_string(&network).expect("should serialize KvNetwork");
+        let deserialized: KvNetwork =
+            serde_json::from_str(&json).expect("should deserialize KvNetwork");
+
+        assert_eq!(deserialized.cluster_size, Some(3));
+        assert_eq!(deserialized.cluster_checked, Some(1774921179));
+    }
+
+    #[test]
+    fn network_none_fields_omitted_from_json() {
+        let network = KvNetwork {
+            cluster_size: None,
+            cluster_checked: None,
+        };
+        let json = serde_json::to_string(&network).expect("should serialize");
+        assert!(
+            !json.contains("\"cluster_size\""),
+            "None cluster_size should be omitted, got: {json}"
+        );
+        assert!(
+            !json.contains("\"cluster_checked\""),
+            "None cluster_checked should be omitted, got: {json}"
+        );
+    }
+
+    #[test]
+    fn none_network_omitted_from_entry_json() {
+        let entry = KvEntry::tombstone(1000);
+        let json = serde_json::to_string(&entry).expect("should serialize");
+        assert!(
+            !json.contains("\"network\""),
+            "None network should be omitted from JSON, got: {json}"
+        );
+    }
+
+    #[test]
+    fn entry_without_network_deserializes() {
+        // Simulates an entry stored before network was added.
+        let json = r#"{
+            "v": 1,
+            "created": 1000,
+            "last_seen": 1000,
+            "consent": { "ok": true, "updated": 1000 },
+            "geo": { "country": "US" }
+        }"#;
+        let entry: KvEntry =
+            serde_json::from_str(json).expect("should deserialize entry without network");
+
+        assert!(
+            entry.network.is_none(),
+            "missing network should deserialize as None"
+        );
+    }
+
+    #[test]
+    fn metadata_from_entry_mirrors_cluster_size() {
+        let consent = sample_consent_context();
+        let geo = sample_geo_info();
+        let mut entry = KvEntry::new(&consent, Some(&geo), 1000, "example.com");
+        entry.network = Some(KvNetwork {
+            cluster_size: Some(5),
+            cluster_checked: Some(1000),
+        });
+
+        let meta = KvMetadata::from_entry(&entry);
+        assert_eq!(
+            meta.cluster_size,
+            Some(5),
+            "metadata should mirror entry network cluster_size"
+        );
+    }
+
+    #[test]
+    fn metadata_from_entry_without_network_has_none_cluster_size() {
+        let entry = KvEntry::tombstone(1000);
+        let meta = KvMetadata::from_entry(&entry);
+        assert!(
+            meta.cluster_size.is_none(),
+            "metadata should have None cluster_size when entry has no network"
+        );
+    }
 }
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index f487abcb..ed6a3e31 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -260,7 +260,12 @@ impl EcContext {
 
         if let (Some(graph), Some(ec_value)) = (kv, self.ec_value.as_deref()) {
             let now = current_timestamp();
-            let entry = KvEntry::new(&self.consent, self.geo_info.as_ref(), now);
+            let entry = KvEntry::new(
+                &self.consent,
+                self.geo_info.as_ref(),
+                now,
+                &settings.publisher.domain,
+            );
 
             if let Err(err) = graph.create_or_revive(ec_value, &entry) {
                 log::error!(
diff --git a/crates/trusted-server-core/src/geo.rs b/crates/trusted-server-core/src/geo.rs
index 3e1e13bc..bf6900b6 100644
--- a/crates/trusted-server-core/src/geo.rs
+++ b/crates/trusted-server-core/src/geo.rs
@@ -17,11 +17,38 @@ use crate::constants::{
     HEADER_X_GEO_INFO_AVAILABLE, HEADER_X_GEO_METRO_CODE, HEADER_X_GEO_REGION,
 };
 
-/// Convert a Fastly [`Geo`] value into a platform-neutral [`GeoInfo`].
+/// Contains all available geographic data from Fastly's geolocation service,
+/// including city, country, continent, coordinates, and DMA/metro code.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct GeoInfo {
+    /// City name
+    pub city: String,
+    /// Two-letter country code (e.g., "US", "GB")
+    pub country: String,
+    /// Continent name
+    pub continent: String,
+    /// Latitude coordinate
+    pub latitude: f64,
+    /// Longitude coordinate
+    pub longitude: f64,
+    /// DMA (Designated Market Area) / metro code
+    pub metro_code: i64,
+    /// Region code
+    pub region: Option<String>,
+    /// Autonomous System Number (e.g. `7922` = Comcast).
+    /// Used to distinguish home ISP vs. corporate VPN.
+    pub asn: Option<u32>,
+}
+
+/// Convert a Fastly [`Geo`] value into a [`GeoInfo`].
 ///
-/// Shared by `GeoInfo::from_request` (legacy) and `FastlyPlatformGeo::lookup` in
-/// `trusted-server-adapter-fastly` so that field mapping is never duplicated.
+/// Shared by `GeoInfo::from_request` (legacy) and adapter geo lookups
+/// so that field mapping is never duplicated.
 pub fn geo_from_fastly(geo: &Geo) -> GeoInfo {
+    let asn = match geo.as_number() {
+        0 => None,
+        n => Some(n),
+    };
     GeoInfo {
         city: geo.city().to_string(),
         country: geo.country_code().to_string(),
@@ -30,6 +57,7 @@ pub fn geo_from_fastly(geo: &Geo) -> GeoInfo {
         longitude: geo.longitude(),
         metro_code: geo.metro_code(),
         region: geo.region().map(str::to_string),
+        asn,
     }
 }
 
@@ -62,6 +90,18 @@ impl GeoInfo {
             .map(|geo| geo_from_fastly(&geo))
     }
 
+    /// Returns coordinates as a formatted string "latitude,longitude"
+    #[must_use]
+    pub fn coordinates_string(&self) -> String {
+        format!("{},{}", self.latitude, self.longitude)
+    }
+
+    /// Checks if a valid metro code is available (non-zero)
+    #[must_use]
+    pub fn has_metro_code(&self) -> bool {
+        self.metro_code > 0
+    }
+
     /// Sets geo information headers on the response.
     ///
     /// Adds `x-geo-city`, `x-geo-country`, `x-geo-continent`, `x-geo-coordinates`,
@@ -129,6 +169,7 @@ mod tests {
             longitude: -122.4194,
             metro_code: 807,
             region: Some("CA".to_string()),
+            asn: Some(7922),
         }
     }
 
diff --git a/crates/trusted-server-core/src/integrations/prebid.rs b/crates/trusted-server-core/src/integrations/prebid.rs
index 890cf677..2b97bad8 100644
--- a/crates/trusted-server-core/src/integrations/prebid.rs
+++ b/crates/trusted-server-core/src/integrations/prebid.rs
@@ -2082,6 +2082,7 @@ server_url = "https://prebid.example"
                 longitude: 13.405,
                 metro_code: 0,
                 region: None,
+                asn: None,
             }),
         });
 
@@ -2127,6 +2128,7 @@ server_url = "https://prebid.example"
                 longitude: -74.006,
                 metro_code: 501,
                 region: Some("NY".to_string()),
+                asn: None,
             }),
         });
 
@@ -2160,6 +2162,7 @@ server_url = "https://prebid.example"
                 longitude: -74.006,
                 metro_code: 501,
                 region: Some("NY".to_string()),
+                asn: None,
             }),
         });
 
@@ -2545,6 +2548,7 @@ server_url = "https://prebid.example"
                 longitude: -74.006,
                 metro_code: 501,
                 region: Some("NY".to_string()),
+                asn: None,
             }),
         });
 

From 69b92c85553ae02f7c2ea09c2193383b7aae3f25 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Mon, 6 Apr 2026 10:49:00 -0500
Subject: [PATCH 25/36] Add network cluster evaluation to EC identify endpoint

Implements cluster size evaluation to distinguish individual users from
shared networks (VPNs, corporate offices):

- Add KvNetwork struct with cluster_size and last_evaluated timestamp
- Add network field to KvEntry with TTL-gated cluster rechecks
- Add cluster_size to KvMetadata and IdentifyResponse
- Implement count_hash_prefix_keys() to list keys with common prefix
- Implement evaluate_cluster() on KvIdentityGraph (one-page, 100-key limit)
- Call cluster evaluation in handle_identify endpoint
- Return cluster_size in JSON body and x-ts-cluster-size header
- Add cluster_trust_threshold (default 10) and cluster_recheck_secs (default 3600) config

Cluster evaluation uses best-effort semantics: size unknown if list exceeds
100 keys. Cache hit avoids re-evaluation within recheck interval.
---
 crates/trusted-server-core/src/ec/identify.rs | 42 +++++++++++++++----
 crates/trusted-server-core/src/settings.rs    | 23 ++++++++++
 trusted-server.toml                           |  2 +
 3 files changed, 59 insertions(+), 8 deletions(-)

diff --git a/crates/trusted-server-core/src/ec/identify.rs b/crates/trusted-server-core/src/ec/identify.rs
index 55016e88..d29affc0 100644
--- a/crates/trusted-server-core/src/ec/identify.rs
+++ b/crates/trusted-server-core/src/ec/identify.rs
@@ -60,10 +60,12 @@ pub fn handle_identify(
 
     let mut degraded = false;
     let mut resolved = Vec::new();
+    let mut cluster_size: Option<u32> = None;
 
-    if let Some(ec_id) = ec_context.ec_value() {
-        match kv.get(ec_id) {
-            Ok(Some((entry, _generation))) => match resolve_partner_ids(partner_store, &entry) {
+    match kv.get(ec_id) {
+        Ok(Some((entry, generation))) => {
+            // Resolve partner IDs.
+            match resolve_partner_ids(partner_store, &entry) {
                 Ok(values) => {
                     resolved = values;
                 }
@@ -71,13 +73,24 @@ pub fn handle_identify(
                     log::warn!("Identify partner resolution failed: {err:?}");
                     degraded = true;
                 }
-            },
-            Ok(None) => {}
-            Err(err) => {
-                log::warn!("Identify KV read failed for EC ID '{ec_id}': {err:?}");
-                degraded = true;
+            }
+
+            // Evaluate cluster size (lazy, TTL-gated).
+            match kv.evaluate_cluster(ec_id, &entry, generation, settings.ec.cluster_recheck_secs) {
+                Ok(size) => {
+                    cluster_size = size;
+                }
+                Err(err) => {
+                    log::warn!("Cluster evaluation failed for '{ec_id}': {err:?}");
+                    // Non-fatal — cluster_size stays None, response is still useful.
+                }
             }
         }
+        Ok(None) => {}
+        Err(err) => {
+            log::warn!("Identify KV read failed for EC ID '{ec_id}': {err:?}");
+            degraded = true;
+        }
     }
 
     let mut uids = HashMap::new();
@@ -92,6 +105,7 @@ pub fn handle_identify(
         degraded,
         uids,
         eids,
+        cluster_size,
     };
 
     let mut response = json_response(StatusCode::OK, &body)?;
@@ -117,6 +131,11 @@ pub fn handle_identify(
         response.set_header(HEADER_X_TS_EIDS_TRUNCATED, "true");
     }
 
+    if let Some(size) = cluster_size {
+        response.set_header("x-ts-cluster-size", size.to_string());
+        expose_headers.push("x-ts-cluster-size".to_owned());
+    }
+
     if let CorsDecision::Allowed(origin) = cors {
         apply_cors_headers(&mut response, &origin);
         response.set_header(
@@ -158,6 +177,9 @@ struct IdentifyResponse {
     degraded: bool,
     uids: HashMap<String, String>,
     eids: Vec<Eid>,
+    /// Network cluster size. `None` when not yet evaluated or unavailable.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    cluster_size: Option<u32>,
 }
 
 fn json_response<T: serde::Serialize>(
@@ -391,6 +413,10 @@ mod tests {
             serde_json::json!([]),
             "should emit empty eids"
         );
+        assert!(
+            body.get("cluster_size").is_none(),
+            "cluster_size should be omitted when KV read fails"
+        );
     }
 
     #[test]
diff --git a/crates/trusted-server-core/src/settings.rs b/crates/trusted-server-core/src/settings.rs
index 888b19d0..c087be8e 100644
--- a/crates/trusted-server-core/src/settings.rs
+++ b/crates/trusted-server-core/src/settings.rs
@@ -240,6 +240,17 @@ pub struct Ec {
     /// Maximum number of concurrent pull-sync requests.
     #[serde(default = "Ec::default_pull_sync_concurrency")]
     pub pull_sync_concurrency: usize,
+
+    /// Entries with `cluster_size` at or below this value are treated as
+    /// individual users for identity resolution. B2B publishers should
+    /// raise this to 50+ since readers are frequently on office networks.
+    #[serde(default = "Ec::default_cluster_trust_threshold")]
+    pub cluster_trust_threshold: u32,
+
+    /// Seconds before re-evaluating an entry's `cluster_size`.
+    /// Re-check occurs only in the `/identify` endpoint.
+    #[serde(default = "Ec::default_cluster_recheck_secs")]
+    pub cluster_recheck_secs: u64,
 }
 
 impl Ec {
@@ -252,6 +263,18 @@ impl Ec {
         3
     }
 
+    /// Default cluster trust threshold.
+    #[must_use]
+    pub const fn default_cluster_trust_threshold() -> u32 {
+        10
+    }
+
+    /// Default cluster re-check interval (1 hour).
+    #[must_use]
+    pub const fn default_cluster_recheck_secs() -> u64 {
+        3600
+    }
+
     /// Returns `true` if `passphrase` matches a known placeholder value
     /// (case-insensitive).
     #[must_use]
diff --git a/trusted-server.toml b/trusted-server.toml
index edece9e2..011cf581 100644
--- a/trusted-server.toml
+++ b/trusted-server.toml
@@ -19,6 +19,8 @@ passphrase = "trusted-server"
 ec_store = "ec_identity_store"
 partner_store = "ec_partner_store"
 pull_sync_concurrency = 3
+# cluster_trust_threshold = 10   # Entries with cluster_size <= this are individual users
+# cluster_recheck_secs = 3600    # Re-evaluate cluster_size after this many seconds
 
 # Custom headers to be included in every response
 # Allows publishers to include tags such as X-Robots-Tag: noindex

From 3a43dc8cc15c622c915e4d6ed5b02b247ac5ba42 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Mon, 6 Apr 2026 16:10:10 -0500
Subject: [PATCH 26/36] Add device signal derivation and bot gate for EC
 identity graph

Derives coarse browser signals from TLS/H2/UA on every request to gate
EC identity operations. Unrecognized clients (known_browser != true) are
proxied normally but leave no trace in the identity graph.

- Add KvDevice struct (is_mobile, ja4_class, platform_class, h2_fp_hash,
  known_browser) and device field on KvEntry, written once on creation
- Add ec/device.rs with DeviceSignals::derive(), UA parsing, JA4 Section 1
  extraction, H2 fingerprint hashing, known browser allowlist (Chrome/
  Safari/Firefox)
- Add is_mobile and known_browser to KvMetadata for fast propagation checks
- Wire DeviceSignals through EcContext to KvEntry creation path
- Add bot gate in Fastly adapter: suppress KV graph, ec_finalize_response,
  and pull sync when known_browser != Some(true)
---
 .../trusted-server-adapter-fastly/src/main.rs |  74 ++-
 crates/trusted-server-core/src/ec/device.rs   | 485 ++++++++++++++++++
 crates/trusted-server-core/src/ec/kv_types.rs | 162 ++++++
 crates/trusted-server-core/src/ec/mod.rs      |  35 +-
 4 files changed, 739 insertions(+), 17 deletions(-)
 create mode 100644 crates/trusted-server-core/src/ec/device.rs

diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 5e2b86de..56cefb5a 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -12,6 +12,7 @@ use trusted_server_core::constants::{
 };
 use trusted_server_core::ec::admin::handle_register_partner;
 use trusted_server_core::ec::batch_sync::handle_batch_sync;
+use trusted_server_core::ec::device::DeviceSignals;
 use trusted_server_core::ec::finalize::ec_finalize_response;
 use trusted_server_core::ec::identify::{cors_preflight_identify, handle_identify};
 use trusted_server_core::ec::kv::KvIdentityGraph;
@@ -132,6 +133,20 @@ async fn route_request(
     // Extract geo info before auth check or routing consumes the request.
     let geo_info = GeoInfo::from_request(&req);
 
+    // Derive device signals from TLS/H2/UA for bot detection.
+    // This is pure in-memory computation — no KV I/O.
+    let device_signals = derive_device_signals(&req);
+    let is_known_browser = device_signals.known_browser == Some(true);
+
+    if !is_known_browser {
+        log::debug!(
+            "Bot gate: blocking EC operations (known_browser={:?}, ja4={:?}, platform={:?})",
+            device_signals.known_browser,
+            device_signals.ja4_class,
+            device_signals.platform_class,
+        );
+    }
+
     // S2S batch sync — uses Bearer auth (not EC cookies), so skip EC
     // context creation and the EC finalize middleware entirely.
     if req.get_method() == Method::POST && req.get_path() == "/_ts/api/v1/sync" {
@@ -163,20 +178,32 @@ async fn route_request(
             }
         };
 
-    let kv_graph = maybe_identity_graph(settings);
+    // Pass device signals to EcContext so they are stored on new entries.
+    ec_context.set_device_signals(device_signals);
+
+    // Bot gate: suppress all KV operations for unrecognized clients.
+    // The request is still proxied normally — the bot receives valid
+    // HTML but leaves no trace in the identity graph.
+    let kv_graph = if is_known_browser {
+        maybe_identity_graph(settings)
+    } else {
+        None
+    };
 
     // `get_settings()` should already have rejected invalid handler regexes.
     // Keep this fallback so manually-constructed or otherwise unprepared
     // settings still become an error response instead of panicking.
     match enforce_basic_auth(settings, &req) {
         Ok(Some(mut response)) => {
-            ec_finalize_response(
-                settings,
-                geo_info.as_ref(),
-                &ec_context,
-                kv_graph.as_ref(),
-                &mut response,
-            );
+            if is_known_browser {
+                ec_finalize_response(
+                    settings,
+                    geo_info.as_ref(),
+                    &ec_context,
+                    kv_graph.as_ref(),
+                    &mut response,
+                );
+            }
             finalize_response(settings, geo_info.as_ref(), &mut response);
             return Ok(RouteOutcome {
                 response,
@@ -314,17 +341,20 @@ async fn route_request(
     // Convert any errors to HTTP error responses
     let mut response = result.unwrap_or_else(|e| to_error_response(&e));
 
-    ec_finalize_response(
-        settings,
-        geo_info.as_ref(),
-        &ec_context,
-        kv_graph.as_ref(),
-        &mut response,
-    );
+    // Bot gate: skip EC cookie writes and pull sync for unrecognized clients.
+    if is_known_browser {
+        ec_finalize_response(
+            settings,
+            geo_info.as_ref(),
+            &ec_context,
+            kv_graph.as_ref(),
+            &mut response,
+        );
+    }
 
     finalize_response(settings, geo_info.as_ref(), &mut response);
 
-    let pull_sync_context = if organic_route && route_succeeded {
+    let pull_sync_context = if is_known_browser && organic_route && route_succeeded {
         build_pull_sync_context(&ec_context)
     } else {
         None
@@ -440,3 +470,15 @@ fn require_identity_graph(
     })?;
     Ok(KvIdentityGraph::new(store_name))
 }
+
+/// Derives device signals from TLS, H2, and UA request data.
+///
+/// All extraction is pure in-memory — no KV I/O. The Fastly SDK provides
+/// `get_tls_ja4()` and `get_client_h2_fingerprint()` on client requests.
+fn derive_device_signals(req: &Request) -> DeviceSignals {
+    let ua = req.get_header_str("user-agent").unwrap_or("");
+    let ja4 = req.get_tls_ja4();
+    let h2_fp = req.get_client_h2_fingerprint();
+
+    DeviceSignals::derive(ua, ja4, h2_fp)
+}
diff --git a/crates/trusted-server-core/src/ec/device.rs b/crates/trusted-server-core/src/ec/device.rs
new file mode 100644
index 00000000..42604841
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/device.rs
@@ -0,0 +1,485 @@
+//! Device signal derivation for bot detection and browser classification.
+//!
+//! All functions in this module are pure computations — no KV I/O or Fastly
+//! SDK calls. The Fastly adapter extracts raw strings from the request
+//! (`get_tls_ja4()`, `get_client_h2_fingerprint()`, UA header) and passes
+//! them here for classification.
+//!
+//! # Signals
+//!
+//! - **`is_mobile`** — `0` desktop, `1` mobile, `2` unknown (rare; bots or
+//!   hardened clients)
+//! - **`ja4_class`** — JA4 Section 1 only (browser family identifier)
+//! - **`platform_class`** — coarse OS family from UA
+//! - **`h2_fp_hash`** — SHA256 prefix (12 hex chars) of raw H2 SETTINGS
+//! - **`known_browser`** — `true` if `ja4_class` + `h2_fp_hash` match a known
+//!   browser pattern; `false` for known bots; `None` for unknown
+
+use sha2::{Digest as _, Sha256};
+
+use super::kv_types::KvDevice;
+
+/// Device signals derived from a single request.
+///
+/// Computed in the Fastly adapter from raw TLS/H2/UA data, then passed to
+/// core for storage and gating decisions. This type lives in core so it
+/// can be used in [`KvDevice`] construction and tested without Fastly.
+#[derive(Debug, Clone, PartialEq)]
+pub struct DeviceSignals {
+    /// `0` = desktop, `1` = mobile, `2` = unknown.
+    pub is_mobile: u8,
+    /// JA4 Section 1 (e.g. `"t13d1516h2"`).
+    pub ja4_class: Option<String>,
+    /// Coarse OS family: `"mac"`, `"windows"`, `"ios"`, `"android"`,
+    /// `"linux"`.
+    pub platform_class: Option<String>,
+    /// SHA256 prefix (12 hex chars) of raw H2 SETTINGS fingerprint.
+    pub h2_fp_hash: Option<String>,
+    /// `true` = known browser, `false` = known bot, `None` = unknown.
+    pub known_browser: Option<bool>,
+}
+
+impl DeviceSignals {
+    /// Derives all device signals from raw request data.
+    ///
+    /// `ua` is the `User-Agent` header value. `ja4` is the full JA4 hash
+    /// from `req.get_tls_ja4()`. `h2_fp` is the raw H2 SETTINGS string
+    /// from `req.get_client_h2_fingerprint()`.
+    #[must_use]
+    pub fn derive(ua: &str, ja4: Option<&str>, h2_fp: Option<&str>) -> Self {
+        let is_mobile = parse_is_mobile(ua);
+        let ja4_class = ja4.and_then(extract_ja4_section1);
+        let platform_class = parse_platform_class(ua);
+        let h2_fp_hash = h2_fp.map(compute_h2_fp_hash);
+        let known_browser = evaluate_known_browser(ja4_class.as_deref(), h2_fp_hash.as_deref());
+
+        Self {
+            is_mobile,
+            ja4_class,
+            platform_class,
+            h2_fp_hash,
+            known_browser,
+        }
+    }
+
+    /// Converts these signals into a [`KvDevice`] for KV storage.
+    #[must_use]
+    pub fn to_kv_device(&self) -> KvDevice {
+        KvDevice {
+            is_mobile: self.is_mobile,
+            ja4_class: self.ja4_class.clone(),
+            platform_class: self.platform_class.clone(),
+            h2_fp_hash: self.h2_fp_hash.clone(),
+            known_browser: self.known_browser,
+        }
+    }
+}
+
+/// Derives mobile signal from the User-Agent string.
+///
+/// Returns `0` for confirmed desktop, `1` for confirmed mobile,
+/// `2` for genuinely unknown (typically bots or hardened clients).
+#[must_use]
+pub fn parse_is_mobile(ua: &str) -> u8 {
+    // Mobile patterns checked first — more specific.
+    if ua.contains("iPhone") || ua.contains("iPad") || ua.contains("Android") {
+        return 1;
+    }
+    if ua.contains("Macintosh") || ua.contains("Windows") || ua.contains("Linux") {
+        return 0;
+    }
+    2
+}
+
+/// Parses coarse OS family from the User-Agent string.
+///
+/// Returns `None` when no recognized platform pattern is found.
+#[must_use]
+pub fn parse_platform_class(ua: &str) -> Option<String> {
+    // Order matters: check mobile-specific patterns before generic ones.
+    if ua.contains("iPhone") || ua.contains("iPad") {
+        return Some("ios".to_owned());
+    }
+    if ua.contains("Android") {
+        return Some("android".to_owned());
+    }
+    if ua.contains("Macintosh") {
+        return Some("mac".to_owned());
+    }
+    if ua.contains("Windows NT") {
+        return Some("windows".to_owned());
+    }
+    if ua.contains("Linux") {
+        return Some("linux".to_owned());
+    }
+    None
+}
+
+/// Extracts Section 1 from a full JA4 fingerprint.
+///
+/// JA4 format: `section1_section2_section3` separated by underscores.
+/// Section 1 identifies browser family (cipher count, extension count,
+/// ALPN) without uniquely fingerprinting a device.
+///
+/// Returns `None` if the input is empty or has no underscore-delimited
+/// section.
+#[must_use]
+pub fn extract_ja4_section1(full_ja4: &str) -> Option<String> {
+    let section1 = full_ja4.split('_').next()?;
+    if section1.is_empty() {
+        return None;
+    }
+    Some(section1.to_owned())
+}
+
+/// Computes a 12-hex-char prefix of the SHA256 hash of the raw H2
+/// SETTINGS fingerprint string.
+///
+/// The raw string looks like `"1:65536;2:0;4:6291456;6:262144"`.
+#[must_use]
+pub fn compute_h2_fp_hash(raw_h2_fp: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(raw_h2_fp.as_bytes());
+    let digest = hasher.finalize();
+    hex::encode(&digest[..6])
+}
+
+/// Known browser fingerprint allowlist.
+///
+/// Each entry is `(ja4_class, h2_fp_prefix, known_browser)`.
+/// `h2_fp_prefix` is the raw H2 SETTINGS string (not the hash) — we
+/// compare against the hash computed from it.
+///
+/// Empirically derived from Fastly Compute production responses (2026-04-03).
+const KNOWN_BROWSERS: &[(&str, &str, bool)] = &[
+    // Chrome/Mac v146
+    ("t13d1516h2", "1:65536;2:0;4:6291456;6:262144", true),
+    // Safari/Mac v26 and Safari/iOS v26
+    ("t13d2013h2", "2:0;3:100;4:2097152", true),
+    // Firefox/Mac v149
+    ("t13d1717h2", "1:65536;2:0;4:131072;5:16384", true),
+];
+
+/// Computes H2 fingerprint hashes for the known browser allowlist.
+///
+/// Recomputed on each call — the list is tiny (3 entries) so the cost
+/// is negligible compared to any KV I/O.
+fn known_browser_h2_hashes() -> Vec<(&'static str, String, bool)> {
+    KNOWN_BROWSERS
+        .iter()
+        .map(|(ja4, h2_raw, known)| (*ja4, compute_h2_fp_hash(h2_raw), *known))
+        .collect()
+}
+
+/// Evaluates whether a request comes from a known browser.
+///
+/// Returns `Some(true)` if `ja4_class` + `h2_fp_hash` match a known
+/// legitimate browser pattern. Returns `Some(false)` for known
+/// bot/scraper patterns. Returns `None` for unrecognized combinations.
+///
+/// Both signals must be present for a match — if either is `None`,
+/// returns `None`.
+#[must_use]
+pub fn evaluate_known_browser(ja4_class: Option<&str>, h2_fp_hash: Option<&str>) -> Option<bool> {
+    let ja4 = ja4_class?;
+    let h2_hash = h2_fp_hash?;
+
+    let hashes = known_browser_h2_hashes();
+    for (known_ja4, known_h2_hash, is_browser) in &hashes {
+        if ja4 == *known_ja4 && h2_hash == *known_h2_hash {
+            return Some(*is_browser);
+        }
+    }
+
+    // No match — unknown client.
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Chrome Mac UA
+    const CHROME_MAC_UA: &str = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) \
+        AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";
+
+    // Safari iOS UA
+    const SAFARI_IOS_UA: &str = "Mozilla/5.0 (iPhone; CPU iPhone OS 26_0 like Mac OS X) \
+        AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Mobile/15E148 Safari/604.1";
+
+    // Safari Mac UA
+    const SAFARI_MAC_UA: &str = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) \
+        AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Safari/605.1.15";
+
+    // Firefox Mac UA
+    const FIREFOX_MAC_UA: &str = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; \
+        rv:149.0) Gecko/20100101 Firefox/149.0";
+
+    // Android Chrome UA
+    const CHROME_ANDROID_UA: &str = "Mozilla/5.0 (Linux; Android 14; Pixel 8) \
+        AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Mobile Safari/537.36";
+
+    // Windows Chrome UA
+    const CHROME_WINDOWS_UA: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) \
+        AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";
+
+    // Bot/empty UA
+    const BOT_UA: &str = "Googlebot/2.1 (+http://www.google.com/bot.html)";
+
+    #[test]
+    fn is_mobile_desktop_browsers() {
+        assert_eq!(parse_is_mobile(CHROME_MAC_UA), 0, "Chrome/Mac = desktop");
+        assert_eq!(parse_is_mobile(SAFARI_MAC_UA), 0, "Safari/Mac = desktop");
+        assert_eq!(parse_is_mobile(FIREFOX_MAC_UA), 0, "Firefox/Mac = desktop");
+        assert_eq!(
+            parse_is_mobile(CHROME_WINDOWS_UA),
+            0,
+            "Chrome/Windows = desktop"
+        );
+    }
+
+    #[test]
+    fn is_mobile_mobile_browsers() {
+        assert_eq!(parse_is_mobile(SAFARI_IOS_UA), 1, "Safari/iOS = mobile");
+        assert_eq!(
+            parse_is_mobile(CHROME_ANDROID_UA),
+            1,
+            "Chrome/Android = mobile"
+        );
+    }
+
+    #[test]
+    fn is_mobile_unknown() {
+        assert_eq!(parse_is_mobile(BOT_UA), 2, "Googlebot = unknown");
+        assert_eq!(parse_is_mobile(""), 2, "empty UA = unknown");
+    }
+
+    #[test]
+    fn platform_class_desktop() {
+        assert_eq!(parse_platform_class(CHROME_MAC_UA).as_deref(), Some("mac"));
+        assert_eq!(
+            parse_platform_class(CHROME_WINDOWS_UA).as_deref(),
+            Some("windows")
+        );
+        assert_eq!(parse_platform_class(FIREFOX_MAC_UA).as_deref(), Some("mac"));
+    }
+
+    #[test]
+    fn platform_class_mobile() {
+        assert_eq!(parse_platform_class(SAFARI_IOS_UA).as_deref(), Some("ios"));
+        assert_eq!(
+            parse_platform_class(CHROME_ANDROID_UA).as_deref(),
+            Some("android")
+        );
+    }
+
+    #[test]
+    fn platform_class_linux() {
+        let linux_ua = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36";
+        assert_eq!(parse_platform_class(linux_ua).as_deref(), Some("linux"));
+    }
+
+    #[test]
+    fn platform_class_unknown() {
+        assert_eq!(parse_platform_class(BOT_UA), None);
+        assert_eq!(parse_platform_class(""), None);
+    }
+
+    #[test]
+    fn ja4_section1_extraction() {
+        assert_eq!(
+            extract_ja4_section1("t13d1516h2_8daaf6152771_e5627efa2ab1").as_deref(),
+            Some("t13d1516h2"),
+            "should extract section 1 from full JA4"
+        );
+    }
+
+    #[test]
+    fn ja4_section1_no_underscore() {
+        // Some implementations may return just section 1
+        assert_eq!(
+            extract_ja4_section1("t13d1516h2").as_deref(),
+            Some("t13d1516h2"),
+            "should handle JA4 with no underscore"
+        );
+    }
+
+    #[test]
+    fn ja4_section1_empty() {
+        assert_eq!(extract_ja4_section1(""), None);
+    }
+
+    #[test]
+    fn h2_fp_hash_deterministic() {
+        let hash1 = compute_h2_fp_hash("1:65536;2:0;4:6291456;6:262144");
+        let hash2 = compute_h2_fp_hash("1:65536;2:0;4:6291456;6:262144");
+        assert_eq!(hash1, hash2, "should be deterministic");
+        assert_eq!(hash1.len(), 12, "should be 12 hex chars");
+    }
+
+    #[test]
+    fn h2_fp_hash_different_inputs() {
+        let chrome = compute_h2_fp_hash("1:65536;2:0;4:6291456;6:262144");
+        let safari = compute_h2_fp_hash("2:0;3:100;4:2097152");
+        assert_ne!(
+            chrome, safari,
+            "different inputs should produce different hashes"
+        );
+    }
+
+    #[test]
+    fn known_browser_chrome_match() {
+        let ja4 = "t13d1516h2";
+        let h2_hash = compute_h2_fp_hash("1:65536;2:0;4:6291456;6:262144");
+        assert_eq!(
+            evaluate_known_browser(Some(ja4), Some(&h2_hash)),
+            Some(true),
+            "Chrome fingerprint should be recognized"
+        );
+    }
+
+    #[test]
+    fn known_browser_safari_match() {
+        let ja4 = "t13d2013h2";
+        let h2_hash = compute_h2_fp_hash("2:0;3:100;4:2097152");
+        assert_eq!(
+            evaluate_known_browser(Some(ja4), Some(&h2_hash)),
+            Some(true),
+            "Safari fingerprint should be recognized"
+        );
+    }
+
+    #[test]
+    fn known_browser_firefox_match() {
+        let ja4 = "t13d1717h2";
+        let h2_hash = compute_h2_fp_hash("1:65536;2:0;4:131072;5:16384");
+        assert_eq!(
+            evaluate_known_browser(Some(ja4), Some(&h2_hash)),
+            Some(true),
+            "Firefox fingerprint should be recognized"
+        );
+    }
+
+    #[test]
+    fn known_browser_unknown_combination() {
+        let ja4 = "t13d9999h2";
+        let h2_hash = compute_h2_fp_hash("1:1;2:2;3:3");
+        assert_eq!(
+            evaluate_known_browser(Some(ja4), Some(&h2_hash)),
+            None,
+            "unknown combination should return None"
+        );
+    }
+
+    #[test]
+    fn known_browser_mismatched_ja4_h2() {
+        // Chrome JA4 but Safari H2
+        let ja4 = "t13d1516h2";
+        let h2_hash = compute_h2_fp_hash("2:0;3:100;4:2097152");
+        assert_eq!(
+            evaluate_known_browser(Some(ja4), Some(&h2_hash)),
+            None,
+            "mismatched JA4/H2 should return None"
+        );
+    }
+
+    #[test]
+    fn known_browser_missing_signals() {
+        assert_eq!(
+            evaluate_known_browser(None, Some("abcdef123456")),
+            None,
+            "missing JA4 should return None"
+        );
+        assert_eq!(
+            evaluate_known_browser(Some("t13d1516h2"), None),
+            None,
+            "missing H2 hash should return None"
+        );
+        assert_eq!(
+            evaluate_known_browser(None, None),
+            None,
+            "both missing should return None"
+        );
+    }
+
+    #[test]
+    fn derive_chrome_mac() {
+        let signals = DeviceSignals::derive(
+            CHROME_MAC_UA,
+            Some("t13d1516h2_8daaf6152771_e5627efa2ab1"),
+            Some("1:65536;2:0;4:6291456;6:262144"),
+        );
+
+        assert_eq!(signals.is_mobile, 0);
+        assert_eq!(signals.ja4_class.as_deref(), Some("t13d1516h2"));
+        assert_eq!(signals.platform_class.as_deref(), Some("mac"));
+        assert!(signals.h2_fp_hash.is_some());
+        assert_eq!(signals.known_browser, Some(true));
+    }
+
+    #[test]
+    fn derive_safari_ios() {
+        let signals = DeviceSignals::derive(
+            SAFARI_IOS_UA,
+            Some("t13d2013h2_abcdef123456_fedcba654321"),
+            Some("2:0;3:100;4:2097152"),
+        );
+
+        assert_eq!(signals.is_mobile, 1);
+        assert_eq!(signals.ja4_class.as_deref(), Some("t13d2013h2"));
+        assert_eq!(signals.platform_class.as_deref(), Some("ios"));
+        assert_eq!(signals.known_browser, Some(true));
+    }
+
+    #[test]
+    fn derive_bot() {
+        let signals = DeviceSignals::derive(BOT_UA, None, None);
+
+        assert_eq!(signals.is_mobile, 2);
+        assert!(signals.ja4_class.is_none());
+        assert!(signals.platform_class.is_none());
+        assert!(signals.h2_fp_hash.is_none());
+        assert_eq!(signals.known_browser, None);
+    }
+
+    #[test]
+    fn to_kv_device_conversion() {
+        let signals = DeviceSignals::derive(
+            CHROME_MAC_UA,
+            Some("t13d1516h2_8daaf6152771_e5627efa2ab1"),
+            Some("1:65536;2:0;4:6291456;6:262144"),
+        );
+        let device = signals.to_kv_device();
+
+        assert_eq!(device.is_mobile, signals.is_mobile);
+        assert_eq!(device.ja4_class, signals.ja4_class);
+        assert_eq!(device.platform_class, signals.platform_class);
+        assert_eq!(device.h2_fp_hash, signals.h2_fp_hash);
+        assert_eq!(device.known_browser, signals.known_browser);
+    }
+
+    #[test]
+    fn android_is_linux_but_platform_class_android() {
+        // Android UA contains "Linux" — platform_class should be "android"
+        // not "linux" because we check Android before Linux.
+        assert_eq!(
+            parse_platform_class(CHROME_ANDROID_UA).as_deref(),
+            Some("android"),
+            "Android should take precedence over Linux"
+        );
+        // But is_mobile should be 1 since it contains "Android".
+        assert_eq!(parse_is_mobile(CHROME_ANDROID_UA), 1);
+    }
+
+    #[test]
+    fn ipad_is_mobile() {
+        let ipad_ua = "Mozilla/5.0 (iPad; CPU OS 26_0 like Mac OS X) \
+            AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Safari/604.1";
+        assert_eq!(parse_is_mobile(ipad_ua), 1, "iPad should be mobile");
+        assert_eq!(
+            parse_platform_class(ipad_ua).as_deref(),
+            Some("ios"),
+            "iPad should be ios"
+        );
+    }
+}
diff --git a/crates/trusted-server-core/src/ec/kv_types.rs b/crates/trusted-server-core/src/ec/kv_types.rs
index 7262ca55..86a11e53 100644
--- a/crates/trusted-server-core/src/ec/kv_types.rs
+++ b/crates/trusted-server-core/src/ec/kv_types.rs
@@ -41,6 +41,10 @@ pub struct KvEntry {
     /// Publisher domain history for consortium-level identity sharing.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub pub_properties: Option<KvPubProperties>,
+    /// Device class signals (TLS fingerprint, UA platform).
+    /// Written once on creation — never updated after.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub device: Option<KvDevice>,
     /// Network cluster disambiguation data.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub network: Option<KvNetwork>,
@@ -119,6 +123,40 @@ pub struct KvPubProperties {
     pub seen_domains: HashMap<String, KvDomainVisit>,
 }
 
+/// Coarse, non-PII device signals derived from TLS handshake and UA.
+///
+/// Used by the `/identify` endpoint for cross-suffix propagation decisions
+/// and buyer-facing device quality scoring. Written once on
+/// [`KvEntry`] creation — never updated after.
+///
+/// **Privacy:** `ja4_class` (Section 1 only) and `platform_class` are
+/// category signals, not unique device identifiers. The full JA4
+/// fingerprint (Sections 2–3) is never stored.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct KvDevice {
+    /// Mobile signal: `0` = confirmed desktop, `1` = confirmed mobile,
+    /// `2` = genuinely unknown (non-standard client).
+    /// Derived from UA platform string — no Client Hints required.
+    pub is_mobile: u8,
+    /// JA4 Section 1 only — browser family class identifier.
+    /// e.g. `"t13d1516h2"` = Chrome, `"t13d2013h2"` = Safari.
+    /// Never stores the full JA4 fingerprint.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub ja4_class: Option<String>,
+    /// Coarse OS family from UA: `"mac"`, `"windows"`, `"ios"`,
+    /// `"android"`, `"linux"`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub platform_class: Option<String>,
+    /// SHA256 prefix (12 hex chars) of the HTTP/2 SETTINGS fingerprint.
+    /// Used alongside `ja4_class` for browser confirmation and bot detection.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub h2_fp_hash: Option<String>,
+    /// `true` = known legitimate browser; `false` = known bot/scraper;
+    /// `None` = unknown.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub known_browser: Option<bool>,
+}
+
 /// Network cluster disambiguation data.
 ///
 /// Tracks how many distinct EC entries share the same hash prefix. A high
@@ -154,6 +192,13 @@ pub struct KvMetadata {
     /// Mirrors [`KvNetwork::cluster_size`]. `None` = not yet evaluated.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub cluster_size: Option<u32>,
+    /// Mirrors [`KvDevice::is_mobile`]. Enables propagation gating without
+    /// body read.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub is_mobile: Option<u8>,
+    /// Mirrors [`KvDevice::known_browser`]. Buyer-facing quality signal.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub known_browser: Option<bool>,
 }
 
 impl KvEntry {
@@ -188,6 +233,7 @@ impl KvEntry {
                 origin_domain: domain.to_owned(),
                 seen_domains,
             }),
+            device: None,
             network: None,
             ids: HashMap::new(),
         }
@@ -225,6 +271,7 @@ impl KvEntry {
                 dma: None,
             },
             pub_properties: None,
+            device: None,
             network: None,
             ids,
         }
@@ -257,6 +304,7 @@ impl KvEntry {
                 dma: None,
             },
             pub_properties: None,
+            device: None,
             network: None,
             ids: HashMap::new(),
         }
@@ -272,6 +320,8 @@ impl KvMetadata {
             country: entry.geo.country.clone(),
             v: entry.v,
             cluster_size: entry.network.as_ref().and_then(|n| n.cluster_size),
+            is_mobile: entry.device.as_ref().map(|d| d.is_mobile),
+            known_browser: entry.device.as_ref().and_then(|d| d.known_browser),
         }
     }
 }
@@ -373,6 +423,8 @@ mod tests {
             country: "US".to_owned(),
             v: 1,
             cluster_size: None,
+            is_mobile: None,
+            known_browser: None,
         };
 
         let json = serde_json::to_string(&meta).expect("should serialize KvMetadata");
@@ -392,6 +444,8 @@ mod tests {
             country: "US".to_owned(),
             v: 1,
             cluster_size: Some(3),
+            is_mobile: None,
+            known_browser: None,
         };
 
         let json = serde_json::to_string(&meta).expect("should serialize KvMetadata");
@@ -418,6 +472,8 @@ mod tests {
             country: "XX".to_owned(),
             v: SCHEMA_VERSION,
             cluster_size: Some(u32::MAX),
+            is_mobile: Some(2),
+            known_browser: Some(true),
         };
         let json = serde_json::to_string(&meta).expect("should serialize KvMetadata");
         assert!(
@@ -740,4 +796,110 @@ mod tests {
             "metadata should have None cluster_size when entry has no network"
         );
     }
+
+    #[test]
+    fn device_roundtrip() {
+        let device = KvDevice {
+            is_mobile: 0,
+            ja4_class: Some("t13d1516h2".to_owned()),
+            platform_class: Some("mac".to_owned()),
+            h2_fp_hash: Some("a3f9d21c8b04".to_owned()),
+            known_browser: Some(true),
+        };
+        let json = serde_json::to_string(&device).expect("should serialize KvDevice");
+        let deserialized: KvDevice =
+            serde_json::from_str(&json).expect("should deserialize KvDevice");
+
+        assert_eq!(deserialized.is_mobile, 0);
+        assert_eq!(deserialized.ja4_class.as_deref(), Some("t13d1516h2"));
+        assert_eq!(deserialized.platform_class.as_deref(), Some("mac"));
+        assert_eq!(deserialized.h2_fp_hash.as_deref(), Some("a3f9d21c8b04"));
+        assert_eq!(deserialized.known_browser, Some(true));
+    }
+
+    #[test]
+    fn device_none_fields_omitted_from_json() {
+        let device = KvDevice {
+            is_mobile: 2,
+            ja4_class: None,
+            platform_class: None,
+            h2_fp_hash: None,
+            known_browser: None,
+        };
+        let json = serde_json::to_string(&device).expect("should serialize");
+        assert!(
+            !json.contains("\"ja4_class\""),
+            "None ja4_class should be omitted, got: {json}"
+        );
+        assert!(
+            !json.contains("\"known_browser\""),
+            "None known_browser should be omitted, got: {json}"
+        );
+    }
+
+    #[test]
+    fn none_device_omitted_from_entry_json() {
+        let entry = KvEntry::tombstone(1000);
+        let json = serde_json::to_string(&entry).expect("should serialize");
+        assert!(
+            !json.contains("\"device\""),
+            "None device should be omitted from JSON, got: {json}"
+        );
+    }
+
+    #[test]
+    fn entry_without_device_deserializes() {
+        let json = r#"{
+            "v": 1,
+            "created": 1000,
+            "last_seen": 1000,
+            "consent": { "ok": true, "updated": 1000 },
+            "geo": { "country": "US" }
+        }"#;
+        let entry: KvEntry =
+            serde_json::from_str(json).expect("should deserialize entry without device");
+
+        assert!(
+            entry.device.is_none(),
+            "missing device should deserialize as None"
+        );
+    }
+
+    #[test]
+    fn metadata_from_entry_mirrors_device_fields() {
+        let consent = sample_consent_context();
+        let geo = sample_geo_info();
+        let mut entry = KvEntry::new(&consent, Some(&geo), 1000, "example.com");
+        entry.device = Some(KvDevice {
+            is_mobile: 1,
+            ja4_class: Some("t13d2013h2".to_owned()),
+            platform_class: Some("ios".to_owned()),
+            h2_fp_hash: None,
+            known_browser: Some(true),
+        });
+
+        let meta = KvMetadata::from_entry(&entry);
+        assert_eq!(
+            meta.is_mobile,
+            Some(1),
+            "metadata should mirror device is_mobile"
+        );
+        assert_eq!(
+            meta.known_browser,
+            Some(true),
+            "metadata should mirror device known_browser"
+        );
+    }
+
+    #[test]
+    fn metadata_without_device_fields_deserializes() {
+        let json = r#"{"ok":true,"country":"US","v":1}"#;
+        let meta: KvMetadata = serde_json::from_str(json).expect("should deserialize old metadata");
+
+        assert!(meta.is_mobile.is_none(), "is_mobile should default to None");
+        assert!(
+            meta.known_browser.is_none(),
+            "known_browser should default to None"
+        );
+    }
 }
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index ed6a3e31..c340b07f 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -18,6 +18,7 @@
 //! - [`cookies`] — `Set-Cookie` header creation and expiration helpers
 //! - [`kv`] — KV Store identity graph operations (CAS, tombstones, debounce)
 //! - [`kv_types`] — Schema types for KV identity graph entries
+//! - [`device`] — Device signal derivation (UA, JA4, H2 fingerprinting)
 //! - [`partner`] — Partner registry (`PartnerRecord`, `PartnerStore`)
 //! - [`admin`] — Admin endpoints for partner management
 //! - [`sync_pixel`] — Pixel sync write endpoint (`GET /sync`)
@@ -30,6 +31,7 @@ pub mod admin;
 pub mod batch_sync;
 pub mod consent;
 pub mod cookies;
+pub mod device;
 pub mod eids;
 pub mod finalize;
 pub mod generation;
@@ -50,6 +52,7 @@ use crate::cookies::handle_request_cookies;
 use crate::error::TrustedServerError;
 use crate::geo::GeoInfo;
 use crate::settings::Settings;
+use device::DeviceSignals;
 
 use self::kv::KvIdentityGraph;
 use self::kv_types::KvEntry;
@@ -141,6 +144,10 @@ pub struct EcContext {
     client_ip: Option<String>,
     /// Geo information captured pre-routing for downstream KV writes.
     geo_info: Option<GeoInfo>,
+    /// Device signals derived from TLS/H2/UA in the adapter layer.
+    /// Set via [`EcContext::set_device_signals`] before
+    /// [`EcContext::generate_if_needed`] is called.
+    device_signals: Option<DeviceSignals>,
 }
 
 impl EcContext {
@@ -214,6 +221,7 @@ impl EcContext {
             consent,
             client_ip,
             geo_info: geo_info.cloned(),
+            device_signals: None,
         })
     }
 
@@ -260,12 +268,16 @@ impl EcContext {
 
         if let (Some(graph), Some(ec_value)) = (kv, self.ec_value.as_deref()) {
             let now = current_timestamp();
-            let entry = KvEntry::new(
+            let mut entry = KvEntry::new(
                 &self.consent,
                 self.geo_info.as_ref(),
                 now,
                 &settings.publisher.domain,
             );
+            entry.device = self
+                .device_signals
+                .as_ref()
+                .map(DeviceSignals::to_kv_device);
 
             if let Err(err) = graph.create_or_revive(ec_value, &entry) {
                 log::error!(
@@ -318,6 +330,24 @@ impl EcContext {
         &mut self.consent
     }
 
+    /// Sets the device signals derived from the adapter layer.
+    ///
+    /// Must be called before [`generate_if_needed`] so that new entries
+    /// include the [`KvDevice`] record. The adapter derives these from
+    /// `req.get_tls_ja4()`, `req.get_client_h2_fingerprint()`, and UA.
+    ///
+    /// [`KvDevice`]: super::kv_types::KvDevice
+    /// [`generate_if_needed`]: Self::generate_if_needed
+    pub fn set_device_signals(&mut self, signals: DeviceSignals) {
+        self.device_signals = Some(signals);
+    }
+
+    /// Returns the device signals, if set.
+    #[must_use]
+    pub fn device_signals(&self) -> Option<&DeviceSignals> {
+        self.device_signals.as_ref()
+    }
+
     /// Returns the normalized client IP, if available.
     #[must_use]
     pub fn client_ip(&self) -> Option<&str> {
@@ -374,6 +404,7 @@ impl EcContext {
             consent,
             client_ip: None,
             geo_info: None,
+            device_signals: None,
         }
     }
 
@@ -393,6 +424,7 @@ impl EcContext {
             consent,
             client_ip,
             geo_info: None,
+            device_signals: None,
         }
     }
 
@@ -415,6 +447,7 @@ impl EcContext {
             consent,
             client_ip: None,
             geo_info: None,
+            device_signals: None,
         }
     }
 }

From e1f14a521047531ca0576974444cdbaab9fcd77a Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Mon, 6 Apr 2026 16:10:18 -0500
Subject: [PATCH 27/36] Update EC technical spec with schema extensions, device
 signals, and bot gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document all KV schema additions implemented in the preceding commits:
geo extensions (asn/dma), publisher domain tracking, network cluster
evaluation, device signal derivation, and the bot gate architecture.

- Add §7A Device Signals and Bot Gate (signal derivation, allowlist,
  bot gate behavior matrix, KvDevice write policy, privacy rationale)
- Update §7.2 with full KvEntry schema including KvGeo, KvPubProperties,
  KvDomainVisit, KvDevice, KvNetwork, and extended KvMetadata
- Update §2 architecture diagram with Phase 0 bot gate step
- Update §4.3 EcContext with device_signals field
- Update §5.4 lifecycle with Phase 0 and ec_finalize gating
- Update §11 /identify with cluster_size in JSON and x-ts-cluster-size header
- Update §14 config with cluster_trust_threshold and cluster_recheck_secs
- Update §17.1 main.rs pseudocode with full bot gate wiring
---
 .../2026-03-24-ssc-technical-spec-design.md   | 574 ++++++++++++++++--
 1 file changed, 525 insertions(+), 49 deletions(-)

diff --git a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
index 052620e0..035aa69b 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
@@ -3,7 +3,7 @@
 **Status:** Draft
 **Author:** Engineering
 **PRD reference:** `docs/internal/ssc-prd.md`
-**Last updated:** 2026-03-18
+**Last updated:** 2026-04-06
 
 ---
 
@@ -16,6 +16,7 @@
 5. [Cookie and Header Handling](#5-cookie-and-header-handling)
 6. [Consent Enforcement](#6-consent-enforcement)
 7. [KV Store Identity Graph](#7-kv-store-identity-graph)
+   7A. [Device Signals and Bot Gate](#7a-device-signals-and-bot-gate)
 8. [Pixel Sync Endpoint (`GET /sync`)](#8-pixel-sync-endpoint-get-sync)
 9. [S2S Batch Sync API (`POST /_ts/api/v1/sync`)](#9-s2s-batch-sync-api-post-apiv1sync)
 10. [S2S Pull Sync (TS-Initiated)](#10-s2s-pull-sync-ts-initiated)
@@ -66,8 +67,21 @@ Browser Request
 │  extract GeoInfo → enforce auth → route_request │
 └──────────┬──────────────────────────────────────┘
            │
-Two-phase model (matches existing codebase pattern):
-
+Phase 0 — bot gate (pure in-memory, no KV I/O):
+    ┌─────────────────────────────────────────────────┐
+    │  derive_device_signals(req)                      │
+    │  - UA → is_mobile, platform_class                │
+    │  - req.get_tls_ja4() → ja4_class (Section 1)    │
+    │  - req.get_client_h2_fingerprint() → h2_fp_hash  │
+    │  - (ja4_class, h2_fp_hash) → known_browser       │
+    │                                                   │
+    │  known_browser != Some(true)?                     │
+    │    → suppress KV graph (None), skip ec_finalize,  │
+    │      skip pull sync. Request still proxied to     │
+    │      origin — bot receives valid HTML but leaves   │
+    │      no trace in the identity graph.              │
+    └──────┬────────────────────────────────────────────┘
+           │
 Phase 1 — pre-routing (like `GeoInfo::from_request()`):
     ┌─────────────────────────────────────────┐
     │  EcContext::read_from_request()          │
@@ -75,6 +89,9 @@ Phase 1 — pre-routing (like `GeoInfo::from_request()`):
     │  - build_consent_context() → ConsentContext  │
     │  - allows_ec_creation(consent)               │
     │  No generation. No cookie writes.       │
+    │                                              │
+    │  ec_context.set_device_signals(signals)      │
+    │  (passed through to KvEntry on creation)     │
     └──────┬──────────────────────────────────┘
            │
 Phase 2 — inside organic handlers only:
@@ -114,8 +131,10 @@ crates/trusted-server-core/src/
     mod.rs          — EcContext, pub re-exports
     identity.rs     — EC generation (HMAC-SHA256, IP normalization)
     cookie.rs       — create_ec_cookie(), delete_ec_cookie(), set_ec_on_response()
+    device.rs       — DeviceSignals derivation, UA/JA4/H2 parsing, known browser allowlist
     finalize.rs     — ec_finalize_response() (cookie write/delete, last_seen, tombstone)
-    kv.rs           — KvIdentityGraph, read/write/delete identity entries
+    kv.rs           — KvIdentityGraph, read/write/delete identity entries, cluster evaluation
+    kv_types.rs     — KvEntry, KvGeo, KvConsent, KvPubProperties, KvNetwork, KvDevice, KvMetadata
     partner.rs      — PartnerRecord, PartnerStore, load_partner()
     sync_pixel.rs   — handle_sync() handler
     sync_batch.rs   — handle_batch_sync() handler
@@ -252,6 +271,11 @@ pub struct EcContext {
     /// Stored here so pull sync can use it after `req` has been consumed by routing.
     /// `None` only if Fastly's `get_client_ip_addr()` returns `None`.
     pub client_ip: Option<IpAddr>,
+    /// Device signals derived from TLS/H2/UA in the adapter layer.
+    /// Set via `set_device_signals()` after `read_from_request()` returns.
+    /// Converted to `KvDevice` and stored on new entries in `generate_if_needed()`.
+    /// `None` when the adapter does not provide signals (e.g., test environments).
+    pub device_signals: Option<DeviceSignals>,
 }
 
 impl EcContext {
@@ -295,6 +319,13 @@ impl EcContext {
         kv: &KvIdentityGraph,
     );
 
+    /// Sets device signals derived from the adapter layer (TLS/H2/UA).
+    /// Must be called before `generate_if_needed()` so new entries include `KvDevice`.
+    pub fn set_device_signals(&mut self, signals: DeviceSignals);
+
+    /// Returns the device signals, if set.
+    pub fn device_signals(&self) -> Option<&DeviceSignals>;
+
     /// Returns the stable 64-char hex prefix, or `None` if no EC.
     /// 
     /// Note: This extracts only the prefix for display/logging purposes. All KV
@@ -365,6 +396,31 @@ This header is added to `INTERNAL_HEADERS` in `constants.rs` so it is stripped b
 
 ### 5.4 Per-request EC lifecycle
 
+**Phase 0 — bot gate** (always runs, all routes — pure in-memory, no KV I/O):
+
+```
+derive_device_signals(req)
+  ua = req.get_header_str("user-agent")
+  ja4 = req.get_tls_ja4()                   // Fastly SDK — full JA4 hash
+  h2_fp = req.get_client_h2_fingerprint()    // Fastly SDK — raw H2 SETTINGS string
+
+  DeviceSignals::derive(ua, ja4, h2_fp)
+    is_mobile = parse_is_mobile(ua)          // 0=desktop, 1=mobile, 2=unknown
+    ja4_class = extract_ja4_section1(ja4)    // split on '_', take [0]
+    platform_class = parse_platform_class(ua) // mac/windows/ios/android/linux/None
+    h2_fp_hash = sha256(h2_fp)[..6].hex()   // 12 hex chars
+    known_browser = evaluate_known_browser(ja4_class, h2_fp_hash) // allowlist match
+
+  is_known_browser = (known_browser == Some(true))
+
+  if !is_known_browser:
+    log::debug("Bot gate: blocking EC operations")
+    kv_graph = None                          // suppress all KV operations
+    // ec_finalize_response() will be skipped
+    // pull sync will be skipped
+    // request still proxied to origin normally
+```
+
 **Phase 1 — pre-routing** (always runs, all routes):
 
 ```
@@ -383,6 +439,8 @@ EcContext::read_from_request()
   // When ec_id is Some: consent KV fallback read + consent KV write (to consent store, not EC store).
   // When ec_id is None (first visit): no consent KV interaction — cookies/headers only.
   ec_generated = false
+
+  ec_context.set_device_signals(device_signals) // for KvDevice on creation
 ```
 
 **Phase 2 — inside organic handlers only** (`handle_publisher_request`, `handle_proxy`):
@@ -400,9 +458,12 @@ ec_context.generate_if_needed(settings, &kv)    // best-effort — never 500s
             // no-ops if a live entry (ok=true) already exists
 ```
 
-**`ec_finalize_response(settings, geo, ec_context, &kv, response)` — always runs, all routes:**
+**`ec_finalize_response(settings, geo, ec_context, &kv, response)` — runs only when `is_known_browser == true`:**
 
 ```
+  // Bot gate: when known_browser != Some(true), this entire block is skipped.
+  // The response is proxied to origin without any cookie writes or KV operations.
+
   ├── !allows_ec_creation(&consent) && cookie_was_present?
   │       → clear_ec_on_response()             (delete cookie + strip ALL EC headers from response)
   │       → // Tombstone all known valid EC IDs. May be 0, 1, or 2 IDs.
@@ -502,21 +563,41 @@ Two KV stores are used. Their names are configured in `trusted-server.toml`:
 ```json
 {
   "v": 1,
-  "created": 1741824000,
-  "last_seen": 1741910400,
+  "created": 1775162556,
+  "last_seen": 1775162556,
   "consent": {
     "tcf": "CP...",
     "gpp": "DBA...",
     "ok": true,
-    "updated": 1741910400
+    "updated": 1775162556
   },
   "geo": {
     "country": "US",
-    "region": "CA"
+    "region": "TN",
+    "asn": 7922,
+    "dma": 659
+  },
+  "device": {
+    "is_mobile": 0,
+    "ja4_class": "t13d1516h2",
+    "platform_class": "mac",
+    "h2_fp_hash": "a3f9d21c8b04",
+    "known_browser": true
+  },
+  "pub_properties": {
+    "origin_domain": "autoblog.com",
+    "seen_domains": {
+      "autoblog.com": { "first": 1775162556, "last": 1775162556, "visits": 1 }
+    }
+  },
+  "network": {
+    "cluster_size": 2,
+    "cluster_checked": 1775162556
   },
   "ids": {
-    "ssp_x": { "uid": "abc123", "synced": 1741824000 },
-    "liveramp": { "uid": "LR_xyz", "synced": 1741890000 }
+    "id5": { "uid": "ID5*qe8VHv...", "synced": 1775162556 },
+    "trade_desk": { "uid": "226fb4b3-...", "synced": 1775162556 },
+    "liveramp_ats": { "uid": "Ag2z1TDA...", "synced": 1775162556 }
   }
 }
 ```
@@ -524,7 +605,14 @@ Two KV stores are used. Their names are configured in `trusted-server.toml`:
 **KV metadata (max 2048 bytes, readable without streaming body):**
 
 ```json
-{ "ok": true, "country": "US", "v": 1 }
+{
+  "ok": true,
+  "country": "US",
+  "v": 1,
+  "cluster_size": 2,
+  "is_mobile": 0,
+  "known_browser": true
+}
 ```
 
 The `ok` field in metadata is a **historical consent record for S2S consumers only** — it is set to `false` by `write_withdrawal_tombstone()` so that batch sync clients (`POST /_ts/api/v1/sync`) can return `consent_withdrawn` rather than `ec_id_not_found` during the 24-hour tombstone TTL.
@@ -540,6 +628,16 @@ pub struct KvEntry {
     pub last_seen: u64,
     pub consent: KvConsent,
     pub geo: KvGeo,
+    /// Publisher domain history. Written on create; updated on organic requests.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pub_properties: Option<KvPubProperties>,
+    /// Device class signals. Written once on creation — never updated.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub device: Option<KvDevice>,
+    /// Network cluster disambiguation. Written only by /identify.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub network: Option<KvNetwork>,
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
     pub ids: HashMap<String, KvPartnerId>,
 }
 
@@ -552,7 +650,15 @@ pub struct KvConsent {
 
 pub struct KvGeo {
     pub country: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub region: Option<String>,
+    /// Autonomous System Number (e.g. 7922 = Comcast).
+    /// Primary signal for distinguishing home ISP vs. corporate VPN.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub asn: Option<u32>,
+    /// DMA/metro code (e.g. 807 = San Francisco).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub dma: Option<i64>,
 }
 
 pub struct KvPartnerId {
@@ -560,13 +666,72 @@ pub struct KvPartnerId {
     pub synced: u64,
 }
 
+/// Publisher domain history for consortium-level identity sharing.
+pub struct KvPubProperties {
+    /// Apex domain where this EC entry was first created.
+    pub origin_domain: String,
+    /// Per-domain visit history, keyed by apex domain.
+    /// Capped at 50 entries; new domains silently dropped at cap.
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub seen_domains: HashMap<String, KvDomainVisit>,
+}
+
+pub struct KvDomainVisit {
+    pub first: u64,
+    pub last: u64,
+    pub visits: u32,
+}
+
+/// Coarse device signals derived from TLS handshake and UA.
+/// Written once on creation — never updated after.
+pub struct KvDevice {
+    /// 0 = desktop, 1 = mobile, 2 = unknown (non-standard client).
+    pub is_mobile: u8,
+    /// JA4 Section 1 only (e.g. "t13d1516h2" = Chrome).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub ja4_class: Option<String>,
+    /// Coarse OS family: "mac", "windows", "ios", "android", "linux".
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub platform_class: Option<String>,
+    /// SHA256 prefix (12 hex chars) of H2 SETTINGS fingerprint.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub h2_fp_hash: Option<String>,
+    /// true = known browser, false = known bot, None = unknown.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub known_browser: Option<bool>,
+}
+
+/// Network cluster disambiguation data.
+/// Written only by /identify — too expensive for organic hot path.
+pub struct KvNetwork {
+    /// Number of distinct EC suffixes sharing this hash prefix.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cluster_size: Option<u32>,
+    /// Unix timestamp of last cluster evaluation.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cluster_checked: Option<u64>,
+}
+
 pub struct KvMetadata {
     pub ok: bool,
     pub country: String,
     pub v: u8,
+    /// Mirrors KvNetwork::cluster_size. None = not yet evaluated.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cluster_size: Option<u32>,
+    /// Mirrors KvDevice::is_mobile. Enables propagation gating without body read.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub is_mobile: Option<u8>,
+    /// Mirrors KvDevice::known_browser. Buyer-facing quality signal.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub known_browser: Option<bool>,
 }
 ```
 
+All new fields use `Option` types or `serde(default)`, so existing entries
+deserialize without error. No schema version bump is needed — v1 has not
+shipped yet.
+
 ### 7.3 TTL
 
 All KV writes use `time_to_live_sec = 31536000` (1 year), matching the cookie `Max-Age`.
@@ -665,20 +830,40 @@ impl KvIdentityGraph {
         synced: u64,
     ) -> Result<(), Report<TrustedServerError>>;
 
-    /// Updates `last_seen` timestamp, but only if the stored value is more than
-    /// 300 seconds older than `timestamp`. This debounce prevents KV write
-    /// thrashing under bursty traffic — Fastly KV enforces a 1 write/sec limit
-    /// per key. Callers should log `warn` on failure and continue.
-    ///
-    /// # Arguments
-    ///
-    /// * `ec_id` — The full EC ID (`{64-hex}.{6-alnum}`) used as the KV key.
+    /// Updates `last_seen` timestamp and publisher domain visit history.
+    /// Only writes if the stored `last_seen` is more than 300 seconds older
+    /// than `timestamp` (debounce to avoid 1 write/sec KV limit). When the
+    /// debounce fires, also updates `pub_properties.seen_domains` for the
+    /// given domain (incrementing `visits` and `last`, or inserting a new
+    /// entry up to the 50-domain cap). Callers should log `warn` on failure
+    /// and continue.
     pub fn update_last_seen(
         &self,
         ec_id: &str,
         timestamp: u64,
+        domain: &str,
     ) -> Result<(), Report<TrustedServerError>>;
 
+    /// Counts the number of KV keys sharing a hash prefix via the list API.
+    /// Uses a single-page list with `limit(100)`. Returns the count, or
+    /// `None` if the list exceeds 100 keys (clearly a large network).
+    pub fn count_hash_prefix_keys(
+        &self,
+        hash_prefix: &str,
+    ) -> Result<Option<u32>, Report<TrustedServerError>>;
+
+    /// Evaluates the network cluster size for an EC entry.
+    ///
+    /// Skips evaluation if `cluster_checked` is within `cluster_recheck_secs`.
+    /// Otherwise calls `count_hash_prefix_keys()` and writes the result to
+    /// `entry.network` via CAS. Returns the cluster size for inclusion in
+    /// the `/identify` response.
+    pub fn evaluate_cluster(
+        &self,
+        ec_id: &str,
+        settings: &Settings,
+    ) -> Result<Option<u32>, Report<TrustedServerError>>;
+
     /// Writes a withdrawal tombstone for consent enforcement.
     ///
     /// Instead of hard-deleting the KV entry, this overwrites it with
@@ -725,6 +910,266 @@ impl KvIdentityGraph {
 
 ---
 
+## 7A. Device Signals and Bot Gate
+
+### 7A.1 Overview
+
+Device signals provide coarse, non-PII browser classification derived from
+the TLS handshake and User-Agent header at the Fastly edge. They serve two
+purposes:
+
+1. **Bot gate** — block all KV identity operations for unrecognized clients
+   (bots, scrapers, non-standard HTTP clients). The request is still proxied
+   to the publisher origin normally — the bot receives valid HTML but leaves
+   no trace in the identity graph.
+2. **Device class record** — store a write-once `KvDevice` on each EC entry
+   for future cross-browser propagation decisions and buyer-facing device
+   quality scoring.
+
+All signal derivation is pure in-memory computation — no KV I/O. It runs on
+every request before EC context creation.
+
+### 7A.2 Signal derivation
+
+No Client Hints are used — JA4 and UA platform parsing provide equivalent or
+superior signal for every browser including Safari and Firefox, which do not
+send Client Hints.
+
+**`is_mobile`** — derived in priority order:
+
+| Condition                                      | Value                                                                      |
+| ---------------------------------------------- | -------------------------------------------------------------------------- |
+| UA contains `iPhone`, `iPad`, or `Android`     | `1` — confirmed mobile                                                     |
+| UA contains `Macintosh`, `Windows`, or `Linux` | `0` — confirmed desktop                                                    |
+| Neither pattern matches                        | `2` — genuinely unknown (rare; typically bots or heavily hardened clients) |
+
+Note: `is_mobile: 2` in practice signals a non-standard client rather than
+Safari, since Safari always produces a recognizable UA platform string.
+
+**`platform_class`** — coarse OS family parsed from UA (checked in order):
+
+| UA segment                         | `platform_class` |
+| ---------------------------------- | ---------------- |
+| `iPhone` or `iPad`                 | `ios`            |
+| `Android` (checked before `Linux`) | `android`        |
+| `Macintosh`                        | `mac`            |
+| `Windows NT`                       | `windows`        |
+| `Linux` (non-Android)              | `linux`          |
+| No match                           | `None`           |
+
+**`ja4_class`** — Section 1 of the JA4 fingerprint only (e.g. `t13d1516h2`).
+Available via `req.get_tls_ja4()` in the Fastly Compute Rust SDK. The full
+JA4 format is `section1_section2_section3` separated by underscores; we split
+on `_` and take `[0]`. Section 1 identifies browser family (cipher count,
+extension count, ALPN) without uniquely fingerprinting a device. The full JA4
+is never stored.
+
+**`h2_fp_hash`** — first 12 hex characters of SHA256 of the raw HTTP/2
+SETTINGS fingerprint string, available via `req.get_client_h2_fingerprint()`.
+Used alongside `ja4_class` to confirm browser family and detect bots.
+
+**`known_browser`** — set `true` when `ja4_class` + `h2_fp_hash` match a
+known legitimate browser pattern from the allowlist below. `None` when
+unknown. Both signals must be present for a match — if either is `None`,
+returns `None`.
+
+### 7A.3 Known browser fingerprint allowlist
+
+Empirically derived from Fastly Compute production responses (2026-04-03):
+
+| Browser                             | `ja4_class`  | `h2_fp` raw string               | `known_browser` |
+| ----------------------------------- | ------------ | -------------------------------- | --------------- |
+| Chrome/Mac (v146)                   | `t13d1516h2` | `1:65536;2:0;4:6291456;6:262144` | `true`          |
+| Safari/Mac (v26) + Safari/iOS (v26) | `t13d2013h2` | `2:0;3:100;4:2097152`            | `true`          |
+| Firefox/Mac (v149)                  | `t13d1717h2` | `1:65536;2:0;4:131072;5:16384`   | `true`          |
+
+Safari Mac and Safari iOS share identical TLS/H2 stacks — distinguished only
+by `platform_class` (`mac` vs `ios`) and `is_mobile` (`0` vs `1`).
+
+This allowlist will expand as new browser versions are observed in production.
+Entries not matching any allowlist row get `known_browser: None` (not `false`)
+unless they match a confirmed bot pattern.
+
+The allowlist comparison works by hashing the known raw H2 SETTINGS strings
+at evaluation time and comparing against the request's `h2_fp_hash`. The list
+is small (3 entries) so the cost is negligible.
+
+### 7A.4 Bot gate behavior
+
+Device signals gate all downstream KV and cookie operations:
+
+| `known_browser`  | KV entry created | Cookie set | Partner IDs written | Pull sync |
+| ---------------- | ---------------- | ---------- | ------------------- | --------- |
+| `true`           | Yes              | Yes        | Yes                 | Yes       |
+| `false`          | **No**           | **No**     | **No**              | **No**    |
+| `None` (unknown) | **No**           | **No**     | **No**              | **No**    |
+
+`None` (unrecognized client) is treated the same as `false`. An advertiser
+cannot bid on a session we cannot verify as human — allowing `None` entries
+into the identity graph would degrade buyer trust with no offsetting benefit.
+
+**Implementation in the Fastly adapter:**
+
+1. After `GeoInfo::from_request()`, call `derive_device_signals(req)` which
+   reads `User-Agent`, `req.get_tls_ja4()`, and
+   `req.get_client_h2_fingerprint()`.
+2. If `known_browser != Some(true)`:
+   - `kv_graph` is set to `None` (suppresses all KV reads and writes)
+   - `ec_finalize_response()` is skipped (no cookie set/deleted)
+   - Pull sync is skipped
+   - The request proceeds through normal routing — organic requests are
+     proxied to publisher origin, API endpoints respond normally (but
+     without EC identity data)
+3. If `known_browser == Some(true)`: proceed normally. Device signals are set
+   on `EcContext` via `set_device_signals()` so they flow through to
+   `KvEntry` creation.
+
+**Current bot response:** the request is served normally (proxied to origin)
+without any KV operations or cookie writes. The bot receives a valid HTML
+response but leaves no trace in the identity graph.
+
+### 7A.5 `DeviceSignals` struct
+
+```rust
+/// Device signals derived from a single request.
+/// Computed in the Fastly adapter from raw TLS/H2/UA data.
+pub struct DeviceSignals {
+    pub is_mobile: u8,
+    pub ja4_class: Option<String>,
+    pub platform_class: Option<String>,
+    pub h2_fp_hash: Option<String>,
+    pub known_browser: Option<bool>,
+}
+
+impl DeviceSignals {
+    /// Derives all device signals from raw request data.
+    pub fn derive(ua: &str, ja4: Option<&str>, h2_fp: Option<&str>) -> Self;
+
+    /// Converts to KvDevice for KV storage.
+    pub fn to_kv_device(&self) -> KvDevice;
+}
+```
+
+### 7A.6 `KvDevice` write policy
+
+`KvDevice` is written to `KvEntry.device` only during `generate_if_needed()`
+(new EC creation). It is never updated after creation — device signals are a
+first-seen record of how this EC entry was established.
+
+Existing entries (created before device signals were implemented) will have
+`device: None`. Downstream consumers must handle `None` as "pre-device-signals
+entry" rather than "unknown device."
+
+### 7A.7 Publisher domain history (`KvPubProperties`)
+
+Tracks which publisher properties a user has been seen on, keyed by apex domain.
+Enables consortium-level identity sharing without cross-site tracking: history
+only accumulates within a shared-passphrase group (same EC hash).
+
+```rust
+pub struct KvPubProperties {
+    pub origin_domain: String,
+    pub seen_domains: HashMap<String, KvDomainVisit>,
+}
+
+pub struct KvDomainVisit {
+    pub first: u64,
+    pub last: u64,
+    pub visits: u32,
+}
+```
+
+**Written:** on `create_or_revive` (sets `origin_domain`, adds first
+`seen_domains` entry). Updated on `update_last_seen` — the existing 300-second
+debounce applies, so `visits` and `last` are incremented at most once per 5
+minutes per key.
+
+**Cap:** `seen_domains` is capped at 50 entries (`MAX_SEEN_DOMAINS`). If the
+cap is reached, new domains are silently dropped (log at `debug`). This prevents
+unbounded growth for shared-passphrase consortiums with many properties.
+
+### 7A.8 Network cluster disambiguation (`KvNetwork`)
+
+Tracks how many distinct EC entries share the same hash prefix. A high count
+indicates a shared network (corporate VPN, campus); a low count indicates an
+individual or household.
+
+```rust
+pub struct KvNetwork {
+    pub cluster_size: Option<u32>,
+    pub cluster_checked: Option<u64>,
+}
+```
+
+**Written:** only by the `/identify` endpoint, never on the organic proxy path.
+The prefix-match list API call required to compute `cluster_size` is too
+expensive for the hot path.
+
+**Evaluation:** `evaluate_cluster()` on `KvIdentityGraph`:
+
+- Skips if `cluster_checked` is within `cluster_recheck_secs` (default 3600s)
+- Calls `count_hash_prefix_keys()` with `limit(100)` — a single list-page call
+- If the list exceeds 100 keys, `cluster_size` is `None` (clearly a large network)
+- Writes result to `entry.network` via CAS
+
+**Threshold guidance:**
+
+| Cluster size | Likely scenario                           |
+| ------------ | ----------------------------------------- |
+| 1–3          | Individual / household                    |
+| 4–10         | Small shared space (family, small office) |
+| 11–50        | Medium office, hotel, coworking           |
+| 50+          | Corporate VPN, university, campus         |
+
+**Default trust threshold:** entries with `cluster_size <= 10` are treated as
+individual users for identity resolution purposes. Configurable per publisher
+via `trusted-server.toml`:
+
+```toml
+[ec]
+cluster_trust_threshold = 10  # default
+cluster_recheck_secs = 3600   # default, 1 hour
+```
+
+### 7A.9 Geo extensions (`KvGeo`)
+
+`KvGeo` is extended with two non-PII network signals available from Fastly's
+`geo_lookup()` on the client IP:
+
+- **`asn: Option<u32>`** — Autonomous System Number (e.g. `7922` = Comcast).
+  Primary signal for distinguishing home ISP vs. corporate VPN. Populated from
+  `GeoInfo::asn` which reads `fastly::geo::Geo::as_number()`. A value of `0`
+  from the Fastly API is mapped to `None`.
+- **`dma: Option<i64>`** — DMA/metro code (e.g. `807` = San Francisco).
+  Market-level targeting signal; not personal data. Populated from
+  `GeoInfo::metro_code` when non-zero.
+
+Both fields are written on initial `KvEntry::new()` from `GeoInfo`. Never
+updated after creation — geo is a first-seen signal, not a real-time one.
+
+### 7A.10 IP address storage policy
+
+Raw IP addresses are personal data under GDPR (CJEU _Breyer v. Germany_, 2016)
+and must not be stored in KV entries. The EC hash already derives from the IP
+without persisting it.
+
+Permitted IP-derived signals (written at creation time):
+
+- `geo.country` — ISO 3166-1 alpha-2
+- `geo.region` — ISO 3166-2 subdivision
+- `geo.asn` — ASN number (network identifier, not personal data)
+- `geo.dma` — DMA/metro code (market identifier, not personal data)
+
+### 7A.11 Privacy rationale
+
+`ja4_class` (Section 1 only) and `platform_class` are category signals, not
+unique device identifiers. They are equivalent in precision to `geo.country`
+— they identify a class of client, not an individual. The full JA4 fingerprint
+(Sections 2 and 3) is never stored, as it approaches unique device
+identification and would require explicit consent basis under GDPR Art. 4(1).
+
+---
+
 ## 8. Pixel Sync Endpoint (`GET /sync`)
 
 ### 8.1 Module: `ec/sync_pixel.rs`
@@ -1078,6 +1523,7 @@ Consent is evaluated using the same logic as Section 6.
   "ec": "a1b2c3...AbC123",
   "consent": "ok",
   "degraded": false,
+  "cluster_size": 2,
   "uids": {
     "uid2": "A4A...",
     "liveramp": "LR_xyz"
@@ -1089,6 +1535,11 @@ Consent is evaluated using the same logic as Section 6.
 }
 ```
 
+`cluster_size` is included when the network cluster has been evaluated (see
+§7A.8). `null` or absent when not yet evaluated.
+
+````
+
 `uids` contains one key per partner with `bidstream_enabled: true` and a resolved UID in the KV graph. Partners with no resolved UID for this user are omitted.
 
 **`200 OK` — KV unavailable (degraded):**
@@ -1098,10 +1549,11 @@ Consent is evaluated using the same logic as Section 6.
   "ec": "a1b2c3...AbC123",
   "consent": "ok",
   "degraded": true,
+  "cluster_size": null,
   "uids": {},
   "eids": []
 }
-```
+````
 
 **`200 OK` — EC present, KV entry missing (no synced partners yet):**
 
@@ -1112,6 +1564,7 @@ This case occurs by design when `create_or_revive()` fails on EC generation (bes
   "ec": "a1b2c3...AbC123",
   "consent": "ok",
   "degraded": false,
+  "cluster_size": null,
   "uids": {},
   "eids": []
 }
@@ -1139,6 +1592,7 @@ Set on `200` responses only:
 | `X-ts-eids`         | Standard base64 (RFC 4648, with `=` padding) of the JSON array of OpenRTB 2.6 `user.eids` objects. Capped at **4 KB** after encoding. If the encoded value exceeds 4 KB, the array is truncated (fewest partners first — highest `synced` timestamp retained) until it fits, and a `x-ts-eids-truncated: true` header is added. |
 | `X-ts-<partner_id>` | Resolved UID per partner (e.g., `X-ts-uid2`). One header per partner with a resolved UID. **Capped at 20 partners** — partners sorted by most-recently synced; excess partners are omitted silently.                                                                                                                            |
 | `X-ts-ec-consent`   | `ok` (always — denied consent returns `403`, not `200`)                                                                                                                                                                                                                                                                         |
+| `x-ts-cluster-size` | The network cluster size as a decimal integer (e.g. `2`). Present only when `cluster_size` has been evaluated (see §7A.8). Enables proxy-layer trust decisions without parsing the JSON body.                                                                                                                                   |
 
 These are supplementary — callers should read the JSON body as the primary contract. The 4 KB cap on `X-ts-eids` and the 20-partner cap on `X-ts-<partner_id>` headers reflect typical proxy and browser total-header-budget constraints. Both caps apply independently.
 
@@ -1451,6 +1905,17 @@ pub struct EdgeCookie {
     #[validate(range(min = 1))]
     #[serde(default = "EdgeCookie::default_pull_sync_concurrency")]
     pub pull_sync_concurrency: usize,
+
+    /// Network cluster trust threshold. Entries with `cluster_size <= threshold`
+    /// are treated as individual users for identity resolution purposes.
+    /// B2B publishers should raise this to 50+ for office-heavy audiences.
+    #[serde(default = "EdgeCookie::default_cluster_trust_threshold")]
+    pub cluster_trust_threshold: u32,
+
+    /// Seconds between cluster size re-evaluations per entry.
+    /// Avoids repeated list-prefix API calls on every /identify request.
+    #[serde(default = "EdgeCookie::default_cluster_recheck_secs")]
+    pub cluster_recheck_secs: u64,
 }
 
 impl EdgeCookie {
@@ -1461,6 +1926,8 @@ impl EdgeCookie {
     // Requires exactly 64 lowercase hex characters.
 
     fn default_pull_sync_concurrency() -> usize { 3 }
+    fn default_cluster_trust_threshold() -> u32 { 10 }
+    fn default_cluster_recheck_secs() -> u64 { 3600 }
 }
 ```
 
@@ -1485,6 +1952,8 @@ ec_store = "ec_identity_store"
 partner_store = "ec_partner_store"
 admin_token_hash = "sha256-hex-of-publisher-admin-token"
 pull_sync_concurrency = 3
+# cluster_trust_threshold = 10  # raise to 50+ for B2B publishers
+# cluster_recheck_secs = 3600   # 1 hour between cluster re-evaluations
 ```
 
 ### 14.3 Rate Limit Storage
@@ -1611,6 +2080,14 @@ This is a supported Fastly Compute pattern — `Response::send_to_client()` flus
 async fn route_request(...) -> Result<(), Error> {
     let geo_info = GeoInfo::from_request(&req);
 
+    // Phase 0 — bot gate (pure in-memory, no KV I/O). See §7A.
+    let device_signals = derive_device_signals(&req);
+    let is_known_browser = device_signals.known_browser == Some(true);
+    if !is_known_browser {
+        log::debug!("Bot gate: blocking EC operations (known_browser={:?})",
+            device_signals.known_browser);
+    }
+
     // Pre-routing — read only, no generation (matches GeoInfo pattern).
     // EcContext stores client_ip internally (same req.get_client_ip_addr()
     // already called by GeoInfo::from_request() above).
@@ -1618,20 +2095,30 @@ async fn route_request(...) -> Result<(), Error> {
     let mut ec_context = match ec_context_result {
         Ok(ctx) => ctx,
         Err(e) => {
-            // Pre-routing failure — no route matched yet, but we still need to
-            // send an HTTP error response. Construct one and flush immediately.
             log::error!("EcContext initialization failed: {e:?}");
             let mut response = to_error_response(&e);
             response.send_to_client();
             return Ok(());
         }
     };
-    let kv = KvIdentityGraph::new(&settings.ec.ec_store);
+
+    // Pass device signals through for KvDevice on creation.
+    ec_context.set_device_signals(device_signals);
+
+    // Bot gate: suppress all KV operations for unrecognized clients.
+    let kv = if is_known_browser {
+        Some(KvIdentityGraph::new(&settings.ec.ec_store))
+    } else {
+        None
+    };
     let partner_store = PartnerStore::new(&settings.ec.partner_store);
     let pull_sync_dispatcher = PullSyncDispatcher::new(settings.ec.pull_sync_concurrency);
 
     if let Some(mut response) = enforce_basic_auth(settings, &req) {
-        ec_finalize_response(settings, geo_info.as_ref(), &ec_context, &kv, &mut response);
+        // Bot gate: skip EC cookie writes for unrecognized clients.
+        if is_known_browser {
+            ec_finalize_response(settings, geo_info.as_ref(), &ec_context, kv.as_ref(), &mut response);
+        }
         response.send_to_client();
         return Ok(());
     }
@@ -1643,49 +2130,38 @@ async fn route_request(...) -> Result<(), Error> {
     // is_organic tracks whether pull sync should fire (organic routes only — §10.2).
     let mut is_organic = false;
     let result = match (method, path.as_str()) {
-        // EC-specific routes — all read-only except /sync which takes &mut.
-        // /sync may assign fallback consent into ec_context.consent when the
-        // query param is the only signal — see §8.3.
-        (GET, "/sync")              => handle_sync(settings, &kv, &partner_store, &req, &mut ec_context).await,
-        (GET, "/identify")          => handle_identify(settings, &kv, &partner_store, &req, &ec_context).await,
+        (GET, "/sync")              => handle_sync(settings, kv.as_ref(), &partner_store, &req, &mut ec_context).await,
+        (GET, "/identify")          => handle_identify(settings, kv.as_ref(), &partner_store, &req, &ec_context).await,
         (OPTIONS, "/identify")      => cors_preflight_identify(settings, &req),
-        (POST, "/_ts/api/v1/sync")      => handle_batch_sync(settings, &kv, &partner_store, req).await,
+        (POST, "/_ts/api/v1/sync")      => handle_batch_sync(settings, kv.as_ref(), &partner_store, req).await,
         (POST, "/_ts/admin/partners/register") => handle_register_partner(settings, &partner_store, req).await,
+        (POST, "/auction")          => handle_auction(settings, orchestrator, kv.as_ref(), req, &ec_context).await,
 
-        // /auction — EC-read-only; never generates EC.
-        // NOTE: handle_auction signature changes from (settings, orchestrator, req) to
-        // (settings, orchestrator, &kv, req, &ec_context) — this is a call-graph change,
-        // not just wiring. See §12 for the full auction integration.
-        (POST, "/auction")          => handle_auction(settings, orchestrator, &kv, req, &ec_context).await,
-
-        // Organic routes — generate EC if needed (best-effort, never 500s), then dispatch
         (m, path) if integration_registry.has_route(&m, path) => {
             is_organic = true;
-            ec_context.generate_if_needed(settings, &kv);
+            ec_context.generate_if_needed(settings, kv.as_ref());
             integration_registry.handle_proxy(&m, path, settings, req, &ec_context).await
         },
         _ => {
             is_organic = true;
-            ec_context.generate_if_needed(settings, &kv);
+            ec_context.generate_if_needed(settings, kv.as_ref());
             handle_publisher_request(settings, integration_registry, req, &ec_context)
         },
     };
 
-    // Unwrap result — errors become error responses (matches existing pattern)
     let mut response = result.unwrap_or_else(|e| to_error_response(&e));
 
-    // finalize_response runs on every route — enforces cookie write/deletion/last_seen
-    ec_finalize_response(settings, geo_info.as_ref(), &ec_context, &kv, &mut response);
+    // Bot gate: skip EC cookie writes and finalize for unrecognized clients.
+    if is_known_browser {
+        ec_finalize_response(settings, geo_info.as_ref(), &ec_context, kv.as_ref(), &mut response);
+    }
 
-    // Flush response to client; WASM continues for background pull sync.
     response.send_to_client();
 
-    // Background pull sync — organic routes only (§10.2). Never fires on /sync,
-    // /identify, /auction, /_ts/api/v1/sync, or /_ts/admin/* routes.
-    // Fires outbound HTTP calls via send_async(), blocks on PendingRequest::wait().
-    if is_organic {
+    // Background pull sync — organic routes only, known browsers only (§7A.4, §10.2).
+    if is_known_browser && is_organic {
         if let (Some(ip), Ok(pull_partners)) = (ec_context.client_ip, partner_store.pull_enabled_partners()) {
-            pull_sync_dispatcher.dispatch_background(&ec_context, ip, &pull_partners, &kv);
+            pull_sync_dispatcher.dispatch_background(&ec_context, ip, &pull_partners, kv.as_ref());
         }
     }
 

From 34aa52705caa421f71d58d6a0cdcde9e66110bd8 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Mon, 6 Apr 2026 20:02:04 -0500
Subject: [PATCH 28/36] Replace bot gate allowlist with signal-presence check

The known_browser fingerprint allowlist (3 entries) was too narrow and
blocked legitimate browsers whose JA4/H2 combinations were not listed.

Replace the gate with DeviceSignals::looks_like_browser() which checks
for signal presence: ja4_class.is_some() && platform_class.is_some().
Real browsers always produce both; raw HTTP clients typically lack one
or both. known_browser is still computed and stored on KvDevice for
analytics but no longer gates identity operations.
---
 .../trusted-server-adapter-fastly/src/main.rs | 16 ++---
 crates/trusted-server-core/src/ec/device.rs   | 72 +++++++++++++++++++
 docs/guide/ec-setup-guide.md                  |  3 +-
 .../2026-03-24-ssc-technical-spec-design.md   | 71 +++++++++++-------
 4 files changed, 126 insertions(+), 36 deletions(-)

diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 56cefb5a..f49a1a9a 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -136,14 +136,14 @@ async fn route_request(
     // Derive device signals from TLS/H2/UA for bot detection.
     // This is pure in-memory computation — no KV I/O.
     let device_signals = derive_device_signals(&req);
-    let is_known_browser = device_signals.known_browser == Some(true);
+    let is_real_browser = device_signals.looks_like_browser();
 
-    if !is_known_browser {
+    if !is_real_browser {
         log::debug!(
-            "Bot gate: blocking EC operations (known_browser={:?}, ja4={:?}, platform={:?})",
-            device_signals.known_browser,
+            "Bot gate: blocking EC operations (ja4={:?}, platform={:?}, is_mobile={})",
             device_signals.ja4_class,
             device_signals.platform_class,
+            device_signals.is_mobile,
         );
     }
 
@@ -184,7 +184,7 @@ async fn route_request(
     // Bot gate: suppress all KV operations for unrecognized clients.
     // The request is still proxied normally — the bot receives valid
     // HTML but leaves no trace in the identity graph.
-    let kv_graph = if is_known_browser {
+    let kv_graph = if is_real_browser {
         maybe_identity_graph(settings)
     } else {
         None
@@ -195,7 +195,7 @@ async fn route_request(
     // settings still become an error response instead of panicking.
     match enforce_basic_auth(settings, &req) {
         Ok(Some(mut response)) => {
-            if is_known_browser {
+            if is_real_browser {
                 ec_finalize_response(
                     settings,
                     geo_info.as_ref(),
@@ -342,7 +342,7 @@ async fn route_request(
     let mut response = result.unwrap_or_else(|e| to_error_response(&e));
 
     // Bot gate: skip EC cookie writes and pull sync for unrecognized clients.
-    if is_known_browser {
+    if is_real_browser {
         ec_finalize_response(
             settings,
             geo_info.as_ref(),
@@ -354,7 +354,7 @@ async fn route_request(
 
     finalize_response(settings, geo_info.as_ref(), &mut response);
 
-    let pull_sync_context = if is_known_browser && organic_route && route_succeeded {
+    let pull_sync_context = if is_real_browser && organic_route && route_succeeded {
         build_pull_sync_context(&ec_context)
     } else {
         None
diff --git a/crates/trusted-server-core/src/ec/device.rs b/crates/trusted-server-core/src/ec/device.rs
index 42604841..9d42ad34 100644
--- a/crates/trusted-server-core/src/ec/device.rs
+++ b/crates/trusted-server-core/src/ec/device.rs
@@ -62,6 +62,21 @@ impl DeviceSignals {
         }
     }
 
+    /// Returns `true` when the request looks like a real browser.
+    ///
+    /// Checks for the presence of recognizable signals rather than matching
+    /// against a hardcoded fingerprint allowlist. Real browsers always
+    /// produce a valid TLS fingerprint (`ja4_class`) and a recognizable UA
+    /// platform string (`platform_class`). Raw HTTP clients (curl, Python
+    /// requests, Go net/http, headless scrapers) typically lack one or both.
+    ///
+    /// `known_browser` is still computed and stored on [`KvDevice`] for
+    /// analytics but does not gate identity operations.
+    #[must_use]
+    pub fn looks_like_browser(&self) -> bool {
+        self.ja4_class.is_some() && self.platform_class.is_some()
+    }
+
     /// Converts these signals into a [`KvDevice`] for KV storage.
     #[must_use]
     pub fn to_kv_device(&self) -> KvDevice {
@@ -482,4 +497,61 @@ mod tests {
             "iPad should be ios"
         );
     }
+
+    #[test]
+    fn looks_like_browser_with_both_signals() {
+        let signals = DeviceSignals::derive(
+            CHROME_MAC_UA,
+            Some("t13d1516h2_8daaf6152771_e5627efa2ab1"),
+            Some("1:65536;2:0;4:6291456;6:262144"),
+        );
+        assert!(
+            signals.looks_like_browser(),
+            "Chrome/Mac should look like a browser"
+        );
+    }
+
+    #[test]
+    fn looks_like_browser_unknown_fingerprint_still_passes() {
+        // Chrome/Windows with unknown JA4/H2 — still has ja4_class and platform_class
+        let signals = DeviceSignals::derive(
+            CHROME_WINDOWS_UA,
+            Some("t13d9999h2_unknown_unknown"),
+            Some("99:99;88:88"),
+        );
+        assert!(
+            signals.looks_like_browser(),
+            "unknown fingerprint with valid JA4 + platform should pass"
+        );
+        assert_eq!(signals.known_browser, None, "should not match allowlist");
+    }
+
+    #[test]
+    fn looks_like_browser_rejects_bot() {
+        let signals = DeviceSignals::derive(BOT_UA, None, None);
+        assert!(
+            !signals.looks_like_browser(),
+            "bot with no JA4 and no platform should be rejected"
+        );
+    }
+
+    #[test]
+    fn looks_like_browser_rejects_missing_ja4() {
+        // Real UA but no TLS fingerprint (e.g. HTTP/1.1 or missing SDK support)
+        let signals = DeviceSignals::derive(CHROME_MAC_UA, None, Some("1:65536"));
+        assert!(
+            !signals.looks_like_browser(),
+            "missing JA4 should be rejected even with valid UA"
+        );
+    }
+
+    #[test]
+    fn looks_like_browser_rejects_missing_platform() {
+        // Has JA4 but unrecognizable UA
+        let signals = DeviceSignals::derive(BOT_UA, Some("t13d1516h2_abc_def"), None);
+        assert!(
+            !signals.looks_like_browser(),
+            "unrecognizable UA should be rejected even with JA4"
+        );
+    }
 }
diff --git a/docs/guide/ec-setup-guide.md b/docs/guide/ec-setup-guide.md
index 6a55cad1..ecaf1c5b 100644
--- a/docs/guide/ec-setup-guide.md
+++ b/docs/guide/ec-setup-guide.md
@@ -137,7 +137,8 @@ Expected shape:
       "source": "formally-vital-lion.edgecompute.app",
       "uids": [{ "id": "mock-user-123", "atype": 3 }]
     }
-  ]
+  ],
+  "cluster_size": 12
 }
 ```
 
diff --git a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
index 035aa69b..906a9036 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
@@ -75,7 +75,7 @@ Phase 0 — bot gate (pure in-memory, no KV I/O):
     │  - req.get_client_h2_fingerprint() → h2_fp_hash  │
     │  - (ja4_class, h2_fp_hash) → known_browser       │
     │                                                   │
-    │  known_browser != Some(true)?                     │
+    │  !looks_like_browser()?                             │
     │    → suppress KV graph (None), skip ec_finalize,  │
     │      skip pull sync. Request still proxied to     │
     │      origin — bot receives valid HTML but leaves   │
@@ -327,7 +327,7 @@ impl EcContext {
     pub fn device_signals(&self) -> Option<&DeviceSignals>;
 
     /// Returns the stable 64-char hex prefix, or `None` if no EC.
-    /// 
+    ///
     /// Note: This extracts only the prefix for display/logging purposes. All KV
     /// operations use the full EC ID (via `ec_value()`), not just this hash.
     pub fn ec_hash(&self) -> Option<&str>;
@@ -411,9 +411,9 @@ derive_device_signals(req)
     h2_fp_hash = sha256(h2_fp)[..6].hex()   // 12 hex chars
     known_browser = evaluate_known_browser(ja4_class, h2_fp_hash) // allowlist match
 
-  is_known_browser = (known_browser == Some(true))
+  is_real_browser = looks_like_browser()   // ja4_class.is_some() && platform_class.is_some()
 
-  if !is_known_browser:
+  if !is_real_browser:
     log::debug("Bot gate: blocking EC operations")
     kv_graph = None                          // suppress all KV operations
     // ec_finalize_response() will be skipped
@@ -458,10 +458,10 @@ ec_context.generate_if_needed(settings, &kv)    // best-effort — never 500s
             // no-ops if a live entry (ok=true) already exists
 ```
 
-**`ec_finalize_response(settings, geo, ec_context, &kv, response)` — runs only when `is_known_browser == true`:**
+**`ec_finalize_response(settings, geo, ec_context, &kv, response)` — runs only when `is_real_browser == true`:**
 
 ```
-  // Bot gate: when known_browser != Some(true), this entire block is skipped.
+  // Bot gate: when !looks_like_browser(), this entire block is skipped.
   // The response is proxied to origin without any cookie writes or KV operations.
 
   ├── !allows_ec_creation(&consent) && cookie_was_present?
@@ -996,31 +996,43 @@ is small (3 entries) so the cost is negligible.
 
 ### 7A.4 Bot gate behavior
 
-Device signals gate all downstream KV and cookie operations:
+The bot gate checks for **signal presence** rather than matching against a
+hardcoded fingerprint allowlist. Real browsers always produce a valid TLS
+fingerprint (`ja4_class`) and a recognizable UA platform string
+(`platform_class`). Raw HTTP clients (curl, Python requests, Go net/http,
+headless scrapers) typically lack one or both.
+
+The gate uses `DeviceSignals::looks_like_browser()`:
+
+```rust
+pub fn looks_like_browser(&self) -> bool {
+    self.ja4_class.is_some() && self.platform_class.is_some()
+}
+```
 
-| `known_browser`  | KV entry created | Cookie set | Partner IDs written | Pull sync |
-| ---------------- | ---------------- | ---------- | ------------------- | --------- |
-| `true`           | Yes              | Yes        | Yes                 | Yes       |
-| `false`          | **No**           | **No**     | **No**              | **No**    |
-| `None` (unknown) | **No**           | **No**     | **No**              | **No**    |
+| Condition                                        | EC operations | Example                          |
+| ------------------------------------------------ | ------------- | -------------------------------- |
+| `ja4_class` present AND `platform_class` present | **Allowed**   | Any real browser on any OS       |
+| `ja4_class` missing OR `platform_class` missing  | **Blocked**   | curl, Python requests, Googlebot |
 
-`None` (unrecognized client) is treated the same as `false`. An advertiser
-cannot bid on a session we cannot verify as human — allowing `None` entries
-into the identity graph would degrade buyer trust with no offsetting benefit.
+`known_browser` (the fingerprint allowlist match) is still computed and stored
+on `KvDevice` for analytics and future buyer-facing quality scoring, but it
+does **not** gate identity operations. This avoids blocking legitimate browsers
+whose JA4/H2 fingerprints are not yet in the allowlist.
 
 **Implementation in the Fastly adapter:**
 
 1. After `GeoInfo::from_request()`, call `derive_device_signals(req)` which
    reads `User-Agent`, `req.get_tls_ja4()`, and
    `req.get_client_h2_fingerprint()`.
-2. If `known_browser != Some(true)`:
+2. If `!looks_like_browser()`:
    - `kv_graph` is set to `None` (suppresses all KV reads and writes)
    - `ec_finalize_response()` is skipped (no cookie set/deleted)
    - Pull sync is skipped
    - The request proceeds through normal routing — organic requests are
      proxied to publisher origin, API endpoints respond normally (but
      without EC identity data)
-3. If `known_browser == Some(true)`: proceed normally. Device signals are set
+3. If `looks_like_browser()`: proceed normally. Device signals are set
    on `EcContext` via `set_device_signals()` so they flow through to
    `KvEntry` creation.
 
@@ -1045,6 +1057,10 @@ impl DeviceSignals {
     /// Derives all device signals from raw request data.
     pub fn derive(ua: &str, ja4: Option<&str>, h2_fp: Option<&str>) -> Self;
 
+    /// Returns true when ja4_class and platform_class are both present.
+    /// Used by the bot gate — see §7A.4.
+    pub fn looks_like_browser(&self) -> bool;
+
     /// Converts to KvDevice for KV storage.
     pub fn to_kv_device(&self) -> KvDevice;
 }
@@ -1588,7 +1604,7 @@ Set on `200` responses only:
 
 | Header              | Value                                                                                                                                                                                                                                                                                                                           |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `X-ts-ec`           | `{64-hex}.{6-alnum}` — full EC ID                                                                                                                                                                                                                                                                                              |
+| `X-ts-ec`           | `{64-hex}.{6-alnum}` — full EC ID                                                                                                                                                                                                                                                                                               |
 | `X-ts-eids`         | Standard base64 (RFC 4648, with `=` padding) of the JSON array of OpenRTB 2.6 `user.eids` objects. Capped at **4 KB** after encoding. If the encoded value exceeds 4 KB, the array is truncated (fewest partners first — highest `synced` timestamp retained) until it fits, and a `x-ts-eids-truncated: true` header is added. |
 | `X-ts-<partner_id>` | Resolved UID per partner (e.g., `X-ts-uid2`). One header per partner with a resolved UID. **Capped at 20 partners** — partners sorted by most-recently synced; excess partners are omitted silently.                                                                                                                            |
 | `X-ts-ec-consent`   | `ok` (always — denied consent returns `403`, not `200`)                                                                                                                                                                                                                                                                         |
@@ -2082,10 +2098,10 @@ async fn route_request(...) -> Result<(), Error> {
 
     // Phase 0 — bot gate (pure in-memory, no KV I/O). See §7A.
     let device_signals = derive_device_signals(&req);
-    let is_known_browser = device_signals.known_browser == Some(true);
-    if !is_known_browser {
-        log::debug!("Bot gate: blocking EC operations (known_browser={:?})",
-            device_signals.known_browser);
+    let is_real_browser = device_signals.looks_like_browser();
+    if !is_real_browser {
+        log::debug!("Bot gate: blocking EC operations (ja4={:?}, platform={:?})",
+            device_signals.ja4_class, device_signals.platform_class);
     }
 
     // Pre-routing — read only, no generation (matches GeoInfo pattern).
@@ -2106,7 +2122,7 @@ async fn route_request(...) -> Result<(), Error> {
     ec_context.set_device_signals(device_signals);
 
     // Bot gate: suppress all KV operations for unrecognized clients.
-    let kv = if is_known_browser {
+    let kv = if is_real_browser {
         Some(KvIdentityGraph::new(&settings.ec.ec_store))
     } else {
         None
@@ -2116,7 +2132,7 @@ async fn route_request(...) -> Result<(), Error> {
 
     if let Some(mut response) = enforce_basic_auth(settings, &req) {
         // Bot gate: skip EC cookie writes for unrecognized clients.
-        if is_known_browser {
+        if is_real_browser {
             ec_finalize_response(settings, geo_info.as_ref(), &ec_context, kv.as_ref(), &mut response);
         }
         response.send_to_client();
@@ -2152,14 +2168,15 @@ async fn route_request(...) -> Result<(), Error> {
     let mut response = result.unwrap_or_else(|e| to_error_response(&e));
 
     // Bot gate: skip EC cookie writes and finalize for unrecognized clients.
-    if is_known_browser {
+    // Bot gate: skip EC cookie writes and finalize for unrecognized clients.
+    if is_real_browser {
         ec_finalize_response(settings, geo_info.as_ref(), &ec_context, kv.as_ref(), &mut response);
     }
 
     response.send_to_client();
 
-    // Background pull sync — organic routes only, known browsers only (§7A.4, §10.2).
-    if is_known_browser && is_organic {
+    // Background pull sync — organic routes only, real browsers only (§7A.4, §10.2).
+    if is_real_browser && is_organic {
         if let (Some(ip), Ok(pull_partners)) = (ec_context.client_ip, partner_store.pull_enabled_partners()) {
             pull_sync_dispatcher.dispatch_background(&ec_context, ip, &pull_partners, kv.as_ref());
         }

From 39031acab0871e175ada67fbdfd4ab6f7bc414c0 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Tue, 7 Apr 2026 09:05:52 -0500
Subject: [PATCH 29/36] Backfill pub_properties on update_last_seen for
 pre-existing entries
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Entries created before pub_properties was added have the field as None.
The previous code only updated pub_properties when it already existed
(if let Some), so returning users on pre-existing entries never got
domain tracking.

Now when pub_properties is None, update_last_seen initializes it with
the current domain as origin_domain and first seen_domains entry. This
is a one-time backfill per entry — subsequent visits take the existing
update path.
---
 crates/trusted-server-core/src/ec/kv.rs | 26 ++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/crates/trusted-server-core/src/ec/kv.rs b/crates/trusted-server-core/src/ec/kv.rs
index 0d966a7d..f4d18c65 100644
--- a/crates/trusted-server-core/src/ec/kv.rs
+++ b/crates/trusted-server-core/src/ec/kv.rs
@@ -7,6 +7,7 @@
 //! (organic request paths) or propagate them (sync endpoints). See the
 //! per-operation error handling policy in the spec §7.5.
 
+use std::collections::HashMap;
 use std::time::Duration;
 
 use error_stack::{Report, ResultExt};
@@ -16,7 +17,9 @@ use crate::error::TrustedServerError;
 
 use super::current_timestamp;
 use super::generation::ec_hash;
-use super::kv_types::{KvDomainVisit, KvEntry, KvMetadata, KvNetwork, MAX_SEEN_DOMAINS};
+use super::kv_types::{
+    KvDomainVisit, KvEntry, KvMetadata, KvNetwork, KvPubProperties, MAX_SEEN_DOMAINS,
+};
 
 /// Maximum number of CAS retry attempts before giving up.
 const MAX_CAS_RETRIES: u32 = 3;
@@ -586,8 +589,10 @@ impl KvIdentityGraph {
         entry.last_seen = timestamp;
 
         // Update publisher domain visit history.
-        if let Some(ref mut props) = entry.pub_properties {
-            match props.seen_domains.get_mut(domain) {
+        // When `pub_properties` is `None` (entry created before this field
+        // was added), backfill it with the current domain as origin.
+        match entry.pub_properties {
+            Some(ref mut props) => match props.seen_domains.get_mut(domain) {
                 Some(visit) => {
                     visit.last = timestamp;
                     visit.visits = visit.visits.saturating_add(1);
@@ -609,6 +614,21 @@ impl KvIdentityGraph {
                         );
                     }
                 }
+            },
+            None => {
+                let mut seen_domains = HashMap::new();
+                seen_domains.insert(
+                    domain.to_owned(),
+                    KvDomainVisit {
+                        first: timestamp,
+                        last: timestamp,
+                        visits: 1,
+                    },
+                );
+                entry.pub_properties = Some(KvPubProperties {
+                    origin_domain: domain.to_owned(),
+                    seen_domains,
+                });
             }
         }
 

From 1591329a72897f06345fe13b77c4804e4ab7f064 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Tue, 7 Apr 2026 11:46:29 -0500
Subject: [PATCH 30/36] Namespace new Edge Cookie endpoints under versioned
 routes

---
 crates/integration-tests/tests/common/ec.rs   |  22 +--
 .../tests/frameworks/scenarios.rs             |   9 +-
 .../trusted-server-adapter-fastly/src/main.rs |  12 +-
 crates/trusted-server-core/src/ec/admin.rs    |   8 +-
 .../trusted-server-core/src/ec/batch_sync.rs  |  12 +-
 crates/trusted-server-core/src/ec/eids.rs     |   2 +-
 crates/trusted-server-core/src/ec/identify.rs |   6 +-
 crates/trusted-server-core/src/ec/kv.rs       |   2 +-
 crates/trusted-server-core/src/ec/kv_types.rs |   4 +-
 crates/trusted-server-core/src/ec/mod.rs      |  10 +-
 crates/trusted-server-core/src/ec/partner.rs  |   2 +-
 .../trusted-server-core/src/ec/sync_pixel.rs  |   6 +-
 crates/trusted-server-core/src/settings.rs    |  11 +-
 docs/guide/api-reference.md                   |   8 +-
 docs/guide/ec-setup-guide.md                  |  40 ++---
 docs/guide/edge-cookies.md                    |   4 +-
 .../specs/2026-03-24-ssc-prd-design.md        |  72 ++++----
 .../2026-03-24-ssc-technical-spec-design.md   | 165 ++++++++----------
 18 files changed, 194 insertions(+), 201 deletions(-)

diff --git a/crates/integration-tests/tests/common/ec.rs b/crates/integration-tests/tests/common/ec.rs
index 4e387efc..7f54f036 100644
--- a/crates/integration-tests/tests/common/ec.rs
+++ b/crates/integration-tests/tests/common/ec.rs
@@ -37,7 +37,7 @@ pub struct EcTestClient {
 
 impl EcTestClient {
     /// Creates a new client. Redirects are disabled so tests can inspect
-    /// 302 responses from `/sync`.
+    /// 302 responses from `/_ts/api/v1/sync`.
     pub fn new(base_url: &str) -> Self {
         let client = Client::builder()
             .redirect(reqwest::redirect::Policy::none())
@@ -185,7 +185,7 @@ impl EcTestClient {
 const ADMIN_USER: &str = "admin";
 const ADMIN_PASS: &str = "changeme";
 
-/// Registers a test partner via `POST /_ts/admin/partners/register`.
+/// Registers a test partner via `POST /_ts/admin/v1/partners/register`.
 pub fn register_test_partner(
     client: &EcTestClient,
     partner_id: &str,
@@ -202,7 +202,7 @@ pub fn register_test_partner(
     });
 
     let resp = client.post_json_with_basic_auth(
-        "/_ts/admin/partners/register",
+        "/_ts/admin/v1/partners/register",
         &body,
         ADMIN_USER,
         ADMIN_PASS,
@@ -222,7 +222,7 @@ pub fn register_test_partner(
 // Pixel sync
 // ---------------------------------------------------------------------------
 
-/// Calls `GET /sync` with the required query parameters.
+/// Calls `GET /_ts/api/v1/sync` with the required query parameters.
 ///
 /// Returns the raw response (typically a 302 redirect).
 pub fn pixel_sync(
@@ -232,7 +232,7 @@ pub fn pixel_sync(
     return_url: &str,
 ) -> TestResult<Response> {
     let path = format!(
-        "/sync?partner={partner}&uid={uid}&return={}",
+        "/_ts/api/v1/sync?partner={partner}&uid={uid}&return={}",
         urlencoding::encode(return_url)
     );
     client.get(&path)
@@ -242,32 +242,32 @@ pub fn pixel_sync(
 // Identify
 // ---------------------------------------------------------------------------
 
-/// Calls `GET /identify` and returns the raw response.
+/// Calls `GET /_ts/api/v1/identify` and returns the raw response.
 pub fn identify(client: &EcTestClient) -> TestResult<Response> {
-    client.get("/identify")
+    client.get("/_ts/api/v1/identify")
 }
 
 // ---------------------------------------------------------------------------
 // Batch sync
 // ---------------------------------------------------------------------------
 
-/// Calls `POST /_ts/api/v1/sync` with bearer auth and the given mappings.
+/// Calls `POST /_ts/api/v1/batch-sync` with bearer auth and the given mappings.
 pub fn batch_sync(
     client: &EcTestClient,
     api_key: &str,
     mappings: &[BatchMapping],
 ) -> TestResult<Response> {
     let body = serde_json::json!({ "mappings": mappings_to_json(mappings) });
-    client.post_json_with_bearer("/_ts/api/v1/sync", &body, api_key)
+    client.post_json_with_bearer("/_ts/api/v1/batch-sync", &body, api_key)
 }
 
-/// Calls `POST /_ts/api/v1/sync` without any auth header.
+/// Calls `POST /_ts/api/v1/batch-sync` without any auth header.
 pub fn batch_sync_no_auth(
     client: &EcTestClient,
     mappings: &[BatchMapping],
 ) -> TestResult<Response> {
     let body = serde_json::json!({ "mappings": mappings_to_json(mappings) });
-    client.post_json("/_ts/api/v1/sync", &body)
+    client.post_json("/_ts/api/v1/batch-sync", &body)
 }
 
 /// Single mapping in a batch sync request.
diff --git a/crates/integration-tests/tests/frameworks/scenarios.rs b/crates/integration-tests/tests/frameworks/scenarios.rs
index 668c4968..e3821cbb 100644
--- a/crates/integration-tests/tests/frameworks/scenarios.rs
+++ b/crates/integration-tests/tests/frameworks/scenarios.rs
@@ -435,8 +435,9 @@ impl CustomScenario {
 /// EC identity lifecycle scenarios that test KV-backed stateful behavior.
 ///
 /// These run against the Viceroy runtime directly without a frontend
-/// framework container — they exercise EC-specific endpoints (`/sync`,
-/// `/identify`, `/_ts/api/v1/sync`, `/_ts/admin/partners/register`).
+/// framework container — they exercise EC-specific endpoints
+/// (`/_ts/api/v1/sync`, `/_ts/api/v1/identify`,
+/// `/_ts/api/v1/batch-sync`, `/_ts/admin/v1/partners/register`).
 #[derive(Debug, Clone)]
 pub enum EcScenario {
     /// Full flow: organic request generates EC → pixel sync writes partner
@@ -583,7 +584,7 @@ fn ec_consent_withdrawal(base_url: &str) -> TestResult<()> {
     assert_status(&resp, 204).attach("identify should return 204 after cookie revocation")?;
 
     // 4. With GPC still asserted, identify should reflect consent denial.
-    let resp = client.get_with_headers("/identify", &[("sec-gpc", "1")])?;
+    let resp = client.get_with_headers("/_ts/api/v1/identify", &[("sec-gpc", "1")])?;
     assert_status(&resp, 403)
         .attach("identify with GPC should return 403 after consent withdrawal")?;
 
@@ -617,7 +618,7 @@ fn ec_identify_consent_denied(base_url: &str) -> TestResult<()> {
     // fail-closed → consent denied. Per spec §11.4, consent is evaluated
     // *before* EC presence, so this must be 403 Forbidden regardless of
     // whether an EC cookie exists.
-    let resp = client.get_with_headers("/identify", &[("sec-gpc", "1")])?;
+    let resp = client.get_with_headers("/_ts/api/v1/identify", &[("sec-gpc", "1")])?;
 
     let status = resp.status().as_u16();
     if status != 403 {
diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index f49a1a9a..3f70576d 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -149,7 +149,7 @@ async fn route_request(
 
     // S2S batch sync — uses Bearer auth (not EC cookies), so skip EC
     // context creation and the EC finalize middleware entirely.
-    if req.get_method() == Method::POST && req.get_path() == "/_ts/api/v1/sync" {
+    if req.get_method() == Method::POST && req.get_path() == "/_ts/api/v1/batch-sync" {
         let mut response = require_identity_graph(settings)
             .and_then(|kv| {
                 require_partner_store(settings).and_then(|partner_store| {
@@ -247,12 +247,12 @@ async fn route_request(
         (Method::POST, "/_ts/admin/keys/deactivate") => {
             (handle_deactivate_key(settings, req), false)
         }
-        (Method::POST, "/_ts/admin/partners/register") => (
+        (Method::POST, "/_ts/admin/v1/partners/register") => (
             require_partner_store(settings).and_then(|store| handle_register_partner(&store, req)),
             false,
         ),
 
-        (Method::GET, "/sync") => (
+        (Method::GET, "/_ts/api/v1/sync") => (
             require_identity_graph(settings).and_then(|kv| {
                 require_partner_store(settings).and_then(|partner_store| {
                     handle_sync(settings, &kv, &partner_store, &req, &mut ec_context)
@@ -260,7 +260,7 @@ async fn route_request(
             }),
             false,
         ),
-        (Method::GET, "/identify") => (
+        (Method::GET, "/_ts/api/v1/identify") => (
             require_identity_graph(settings).and_then(|kv| {
                 require_partner_store(settings).and_then(|partner_store| {
                     handle_identify(settings, &kv, &partner_store, &req, &ec_context)
@@ -268,7 +268,9 @@ async fn route_request(
             }),
             false,
         ),
-        (Method::OPTIONS, "/identify") => (cors_preflight_identify(settings, &req), false),
+        (Method::OPTIONS, "/_ts/api/v1/identify") => {
+            (cors_preflight_identify(settings, &req), false)
+        }
 
         // Unified auction endpoint (returns creative HTML inline)
         (Method::POST, "/auction") => {
diff --git a/crates/trusted-server-core/src/ec/admin.rs b/crates/trusted-server-core/src/ec/admin.rs
index c8c8d223..326cb94b 100644
--- a/crates/trusted-server-core/src/ec/admin.rs
+++ b/crates/trusted-server-core/src/ec/admin.rs
@@ -1,6 +1,6 @@
 //! Admin endpoints for partner management.
 //!
-//! Provides `POST /_ts/admin/partners/register` for registering and updating
+//! Provides `POST /_ts/admin/v1/partners/register` for registering and updating
 //! partner configurations. Authentication is handled by the `[[handlers]]`
 //! basic-auth layer before this code runs.
 
@@ -16,7 +16,7 @@ use super::partner::{
     hash_api_key, validate_partner_id, validate_pull_sync_config, PartnerRecord, PartnerStore,
 };
 
-/// Request body for `POST /_ts/admin/partners/register`.
+/// Request body for `POST /_ts/admin/v1/partners/register`.
 ///
 /// Accepts `api_key` as plaintext — it is hashed before storage and
 /// never persisted in cleartext.
@@ -124,7 +124,7 @@ fn normalize_hostname_list(
     Ok(normalized_values)
 }
 
-/// Response body for `POST /_ts/admin/partners/register`.
+/// Response body for `POST /_ts/admin/v1/partners/register`.
 ///
 /// Echoes key fields without exposing sensitive data (`api_key_hash`,
 /// `ts_pull_token`).
@@ -137,7 +137,7 @@ pub struct RegisterPartnerResponse {
     pub created: bool,
 }
 
-/// Handles `POST /_ts/admin/partners/register`.
+/// Handles `POST /_ts/admin/v1/partners/register`.
 ///
 /// Registers a new partner or updates an existing one. Authentication is
 /// handled upstream by the `[[handlers]]` basic-auth layer.
diff --git a/crates/trusted-server-core/src/ec/batch_sync.rs b/crates/trusted-server-core/src/ec/batch_sync.rs
index df698dc5..bb2a89a2 100644
--- a/crates/trusted-server-core/src/ec/batch_sync.rs
+++ b/crates/trusted-server-core/src/ec/batch_sync.rs
@@ -1,4 +1,4 @@
-//! Server-to-server batch sync endpoint (`POST /_ts/api/v1/sync`).
+//! Server-to-server batch sync endpoint (`POST /_ts/api/v1/batch-sync`).
 //!
 //! Partners send authenticated batch ID sync requests via Bearer token.
 //! Each mapping associates an `ec_id` (`{64hex}.{6alnum}`)
@@ -124,7 +124,7 @@ fn parse_bearer_token(header_value: &str) -> Option<&str> {
 // Handler
 // ---------------------------------------------------------------------------
 
-/// Handles `POST /_ts/api/v1/sync`.
+/// Handles `POST /_ts/api/v1/batch-sync`.
 ///
 /// # Errors
 ///
@@ -321,7 +321,7 @@ mod tests {
     #[test]
     fn authenticate_bearer_returns_none_for_missing_header() {
         let partner_store = PartnerStore::new("test_store");
-        let req = Request::new("POST", "https://edge.example.com/_ts/api/v1/sync");
+        let req = Request::new("POST", "https://edge.example.com/_ts/api/v1/batch-sync");
 
         let result =
             authenticate_bearer(&partner_store, &req).expect("should not error on missing header");
@@ -331,7 +331,7 @@ mod tests {
     #[test]
     fn authenticate_bearer_returns_none_for_malformed_header() {
         let partner_store = PartnerStore::new("test_store");
-        let mut req = Request::new("POST", "https://edge.example.com/_ts/api/v1/sync");
+        let mut req = Request::new("POST", "https://edge.example.com/_ts/api/v1/batch-sync");
         req.set_header("authorization", "Basic dXNlcjpwYXNz");
 
         let result = authenticate_bearer(&partner_store, &req)
@@ -345,7 +345,7 @@ mod tests {
     #[test]
     fn authenticate_bearer_returns_none_for_empty_token() {
         let partner_store = PartnerStore::new("test_store");
-        let mut req = Request::new("POST", "https://edge.example.com/_ts/api/v1/sync");
+        let mut req = Request::new("POST", "https://edge.example.com/_ts/api/v1/batch-sync");
         req.set_header("authorization", "Bearer ");
 
         let result =
@@ -470,7 +470,7 @@ mod tests {
         let limiter = MockRateLimiter {
             should_exceed: false,
         };
-        let req = Request::new("POST", "https://edge.example.com/_ts/api/v1/sync");
+        let req = Request::new("POST", "https://edge.example.com/_ts/api/v1/batch-sync");
 
         let response =
             handle_batch_sync(&kv, &partner_store, &limiter, req).expect("should return response");
diff --git a/crates/trusted-server-core/src/ec/eids.rs b/crates/trusted-server-core/src/ec/eids.rs
index c4f7e550..bbfaf1da 100644
--- a/crates/trusted-server-core/src/ec/eids.rs
+++ b/crates/trusted-server-core/src/ec/eids.rs
@@ -1,6 +1,6 @@
 //! Shared EID resolution and formatting helpers.
 //!
-//! Used by both `/identify` and `/auction` to resolve partner IDs from KV
+//! Used by both `/_ts/api/v1/identify` and `/auction` to resolve partner IDs from KV
 //! entries, convert them to `OpenRTB` EID structures, and build base64-encoded
 //! response headers.
 
diff --git a/crates/trusted-server-core/src/ec/identify.rs b/crates/trusted-server-core/src/ec/identify.rs
index d29affc0..dd1ed905 100644
--- a/crates/trusted-server-core/src/ec/identify.rs
+++ b/crates/trusted-server-core/src/ec/identify.rs
@@ -1,4 +1,4 @@
-//! Identity lookup endpoint (`GET /identify`).
+//! Identity lookup endpoint (`GET /_ts/api/v1/identify`).
 
 use std::collections::HashMap;
 
@@ -22,7 +22,7 @@ use super::EcContext;
 
 const MAX_EXPOSE_PARTNER_HEADERS: usize = 20;
 
-/// Handles `GET /identify`.
+/// Handles `GET /_ts/api/v1/identify`.
 ///
 /// # Errors
 ///
@@ -147,7 +147,7 @@ pub fn handle_identify(
     Ok(response)
 }
 
-/// Handles `OPTIONS /identify` CORS preflight.
+/// Handles `OPTIONS /_ts/api/v1/identify` CORS preflight.
 ///
 /// # Errors
 ///
diff --git a/crates/trusted-server-core/src/ec/kv.rs b/crates/trusted-server-core/src/ec/kv.rs
index f4d18c65..f51cd226 100644
--- a/crates/trusted-server-core/src/ec/kv.rs
+++ b/crates/trusted-server-core/src/ec/kv.rs
@@ -653,7 +653,7 @@ impl KvIdentityGraph {
     /// and a 24-hour TTL. Uses unconditional overwrite (no CAS) since the
     /// entry is being withdrawn regardless of concurrent state.
     ///
-    /// The tombstone allows batch sync clients (`POST /_ts/api/v1/sync`) to
+    /// The tombstone allows batch sync clients (`POST /_ts/api/v1/batch-sync`) to
     /// distinguish `consent_withdrawn` from `ec_id_not_found` for 24 hours.
     ///
     /// # Errors
diff --git a/crates/trusted-server-core/src/ec/kv_types.rs b/crates/trusted-server-core/src/ec/kv_types.rs
index 86a11e53..bf2e6dcb 100644
--- a/crates/trusted-server-core/src/ec/kv_types.rs
+++ b/crates/trusted-server-core/src/ec/kv_types.rs
@@ -125,7 +125,7 @@ pub struct KvPubProperties {
 
 /// Coarse, non-PII device signals derived from TLS handshake and UA.
 ///
-/// Used by the `/identify` endpoint for cross-suffix propagation decisions
+/// Used by the `/_ts/api/v1/identify` endpoint for cross-suffix propagation decisions
 /// and buyer-facing device quality scoring. Written once on
 /// [`KvEntry`] creation — never updated after.
 ///
@@ -163,7 +163,7 @@ pub struct KvDevice {
 /// count indicates a shared network (corporate VPN, campus); a low count
 /// indicates an individual or household.
 ///
-/// Written only by the `/identify` endpoint — the prefix-match list API
+/// Written only by the `/_ts/api/v1/identify` endpoint — the prefix-match list API
 /// call required to compute `cluster_size` is too expensive for the
 /// organic proxy hot path.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index c340b07f..c1f66325 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -9,7 +9,7 @@
 //! 2. **Generate** — [`EcContext::generate_if_needed`] creates a new EC ID
 //!    when none exists and consent allows it. This is called only in organic
 //!    handlers (publisher proxy, integration proxy) — never in read-only
-//!    endpoints like `/identify`.
+//!    endpoints like `/_ts/api/v1/identify`.
 //!
 //! # Module structure
 //!
@@ -21,10 +21,10 @@
 //! - [`device`] — Device signal derivation (UA, JA4, H2 fingerprinting)
 //! - [`partner`] — Partner registry (`PartnerRecord`, `PartnerStore`)
 //! - [`admin`] — Admin endpoints for partner management
-//! - [`sync_pixel`] — Pixel sync write endpoint (`GET /sync`)
-//! - [`identify`] — Browser identity read endpoint (`GET /identify`)
+//! - [`sync_pixel`] — Pixel sync write endpoint (`GET /_ts/api/v1/sync`)
+//! - [`identify`] — Browser identity read endpoint (`GET /_ts/api/v1/identify`)
 //! - [`eids`] — Shared EID resolution and formatting helpers
-//! - [`batch_sync`] — S2S batch sync endpoint (`POST /_ts/api/v1/sync`)
+//! - [`batch_sync`] — S2S batch sync endpoint (`POST /_ts/api/v1/batch-sync`)
 //! - [`pull_sync`] — Background pull-sync dispatcher for organic routes
 
 pub mod admin;
@@ -323,7 +323,7 @@ impl EcContext {
 
     /// Returns a mutable reference to the consent context.
     ///
-    /// Used by `/sync` to apply query-param fallback consent for the current
+    /// Used by `/_ts/api/v1/sync` to apply query-param fallback consent for the current
     /// request only when pre-routing consent extraction produced an empty
     /// context.
     pub fn consent_mut(&mut self) -> &mut ConsentContext {
diff --git a/crates/trusted-server-core/src/ec/partner.rs b/crates/trusted-server-core/src/ec/partner.rs
index f7105eb6..6c49d831 100644
--- a/crates/trusted-server-core/src/ec/partner.rs
+++ b/crates/trusted-server-core/src/ec/partner.rs
@@ -61,7 +61,7 @@ fn partner_id_regex() -> Result<&'static Regex, String> {
 
 /// A registered partner configuration stored in the partner KV store.
 ///
-/// Created via `POST /_ts/admin/partners/register`. Used by pixel sync, batch
+/// Created via `POST /_ts/admin/v1/partners/register`. Used by pixel sync, batch
 /// sync, pull sync, and auction bidstream decoration.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct PartnerRecord {
diff --git a/crates/trusted-server-core/src/ec/sync_pixel.rs b/crates/trusted-server-core/src/ec/sync_pixel.rs
index b1bb9389..f796a300 100644
--- a/crates/trusted-server-core/src/ec/sync_pixel.rs
+++ b/crates/trusted-server-core/src/ec/sync_pixel.rs
@@ -1,4 +1,4 @@
-//! Pixel sync endpoint (`GET /sync`).
+//! Pixel sync endpoint (`GET /_ts/api/v1/sync`).
 
 use error_stack::{Report, ResultExt};
 use fastly::erl::{CounterDuration, RateCounter};
@@ -21,7 +21,7 @@ pub const RATE_COUNTER_NAME: &str = "counter_store";
 /// Maximum allowed length (in bytes) for a partner UID.
 const MAX_UID_LENGTH: usize = 512;
 
-/// Handles `GET /sync` pixel sync requests.
+/// Handles `GET /_ts/api/v1/sync` pixel sync requests.
 ///
 /// # Errors
 ///
@@ -247,7 +247,7 @@ fn decode_query_fallback_consent(
 
 /// Rate limiter abstraction for sync endpoints.
 ///
-/// Used by both pixel sync (`/sync`) and batch sync (`/_ts/api/v1/sync`)
+/// Used by both pixel sync (`/_ts/api/v1/sync`) and batch sync (`/_ts/api/v1/batch-sync`)
 /// for per-partner request rate enforcement.
 pub trait RateLimiter {
     /// Returns `true` when the rate limit has been exceeded for the given key.
diff --git a/crates/trusted-server-core/src/settings.rs b/crates/trusted-server-core/src/settings.rs
index c087be8e..6e4f252c 100644
--- a/crates/trusted-server-core/src/settings.rs
+++ b/crates/trusted-server-core/src/settings.rs
@@ -248,7 +248,7 @@ pub struct Ec {
     pub cluster_trust_threshold: u32,
 
     /// Seconds before re-evaluating an entry's `cluster_size`.
-    /// Re-check occurs only in the `/identify` endpoint.
+    /// Re-check occurs only in the `/_ts/api/v1/identify` endpoint.
     #[serde(default = "Ec::default_cluster_recheck_secs")]
     pub cluster_recheck_secs: u64,
 }
@@ -620,7 +620,7 @@ impl Settings {
     pub(crate) const ADMIN_ENDPOINTS: &[&str] = &[
         "/_ts/admin/keys/rotate",
         "/_ts/admin/keys/deactivate",
-        "/_ts/admin/partners/register",
+        "/_ts/admin/v1/partners/register",
     ];
 
     /// Returns admin endpoint paths that no configured handler covers.
@@ -1933,7 +1933,7 @@ mod tests {
             vec![
                 "/_ts/admin/keys/rotate",
                 "/_ts/admin/keys/deactivate",
-                "/_ts/admin/partners/register",
+                "/_ts/admin/v1/partners/register",
             ],
             "should report all admin endpoints as uncovered"
         );
@@ -1968,7 +1968,10 @@ mod tests {
             .expect("should check admin coverage");
         assert_eq!(
             uncovered,
-            vec!["/_ts/admin/keys/deactivate", "/_ts/admin/partners/register"],
+            vec![
+                "/_ts/admin/keys/deactivate",
+                "/_ts/admin/v1/partners/register"
+            ],
             "should detect endpoints not covered by the rotate-only handler"
         );
     }
diff --git a/docs/guide/api-reference.md b/docs/guide/api-reference.md
index 1dcb19bd..73486531 100644
--- a/docs/guide/api-reference.md
+++ b/docs/guide/api-reference.md
@@ -50,7 +50,7 @@ curl "https://edge.example.com/first-party/ad?slot=header-banner&w=728&h=90"
 
 ## Edge Cookie Endpoints
 
-### POST /\_ts/admin/partners/register
+### POST /\_ts/admin/v1/partners/register
 
 Registers or updates a partner used for EC sync and bidstream enrichment.
 
@@ -76,7 +76,7 @@ Registers or updates a partner used for EC sync and bidstream enrichment.
 
 ---
 
-### GET /sync
+### GET /\_ts/api/v1/sync
 
 Browser pixel sync endpoint. Associates an EC ID with a partner UID.
 
@@ -102,7 +102,7 @@ Common `ts_reason` values: `no_ec`, `no_consent`, `write_failed`, `rate_limited`
 
 ---
 
-### GET /identify
+### GET /\_ts/api/v1/identify
 
 Returns EC identity plus resolved partner IDs and EIDs for the current user.
 
@@ -131,7 +131,7 @@ Returns EC identity plus resolved partner IDs and EIDs for the current user.
 
 ---
 
-### POST /\_ts/api/v1/sync
+### POST /\_ts/api/v1/batch-sync
 
 Server-to-server batch sync endpoint for writing EC ID to partner UID mappings.
 
diff --git a/docs/guide/ec-setup-guide.md b/docs/guide/ec-setup-guide.md
index ecaf1c5b..02e4c7d9 100644
--- a/docs/guide/ec-setup-guide.md
+++ b/docs/guide/ec-setup-guide.md
@@ -6,15 +6,15 @@ This guide covers:
 
 1. Fastly store setup
 2. Partner registration
-3. Browser pixel sync (`/sync`)
-4. Server-to-server batch sync (`/_ts/api/v1/sync`)
-5. Identity verification (`/identify`)
+3. Browser pixel sync (`/_ts/api/v1/sync`)
+4. Server-to-server batch sync (`/_ts/api/v1/batch-sync`)
+5. Identity verification (`/_ts/api/v1/identify`)
 6. Auction bidstream verification (`/auction`)
 
 ## Prerequisites
 
 - Trusted Server deployed and reachable (example: `https://getpurpose.ai`)
-- Admin credentials for `/_ts/admin/partners/register`
+- Admin credentials for `/_ts/admin/v1/partners/register`
 - Fastly CLI authenticated (for store verification)
 - A valid TCF consent string (`euconsent-v2`) for consent-required requests
 
@@ -56,10 +56,10 @@ PARTNER_UID="mock-user-$(date +%s)"
 
 ## 3) Register Partner
 
-Endpoint: `POST /_ts/admin/partners/register`
+Endpoint: `POST /_ts/admin/v1/partners/register`
 
 ```bash
-curl -X POST "${TS_BASE_URL}/_ts/admin/partners/register" \
+curl -X POST "${TS_BASE_URL}/_ts/admin/v1/partners/register" \
   -u "${ADMIN_USER}:${ADMIN_PASSWORD}" \
   -H "Content-Type: application/json" \
   -d "{
@@ -94,10 +94,10 @@ Look for:
 
 ## 5) Pixel Sync (Browser-style)
 
-Endpoint: `GET /sync`
+Endpoint: `GET /_ts/api/v1/sync`
 
 ```bash
-curl -si "${TS_BASE_URL}/sync?partner=${PARTNER_ID}&uid=${PARTNER_UID}&return=${MOCK_SSP_URL}/done" \
+curl -si "${TS_BASE_URL}/_ts/api/v1/sync?partner=${PARTNER_ID}&uid=${PARTNER_UID}&return=${MOCK_SSP_URL}/done" \
   -H "Cookie: ts-ec=${EC_ID}; euconsent-v2=${TCF_CONSENT}"
 ```
 
@@ -115,10 +115,10 @@ Common `ts_reason` values:
 
 ## 6) Verify Identity
 
-Endpoint: `GET /identify`
+Endpoint: `GET /_ts/api/v1/identify`
 
 ```bash
-curl -s "${TS_BASE_URL}/identify" \
+curl -s "${TS_BASE_URL}/_ts/api/v1/identify" \
   -H "Cookie: ts-ec=${EC_ID}; euconsent-v2=${TCF_CONSENT}" | python3 -m json.tool
 ```
 
@@ -144,7 +144,7 @@ Expected shape:
 
 ## 7) Batch Sync (S2S)
 
-Endpoint: `POST /_ts/api/v1/sync`
+Endpoint: `POST /_ts/api/v1/batch-sync`
 
 Important: request field is `ec_id` (full `{64hex}.{6alnum}` value).
 
@@ -152,7 +152,7 @@ Important: request field is `ec_id` (full `{64hex}.{6alnum}` value).
 BATCH_UID="${PARTNER_UID}-batch"
 NOW_TS="$(date +%s)"
 
-curl -X POST "${TS_BASE_URL}/_ts/api/v1/sync" \
+curl -X POST "${TS_BASE_URL}/_ts/api/v1/batch-sync" \
   -H "Authorization: Bearer ${PARTNER_API_KEY}" \
   -H "Content-Type: application/json" \
   -d "{
@@ -235,13 +235,13 @@ If pixel sync returns `write_failed`, check whether KV entry has:
 
 ## 10) Troubleshooting Quick Map
 
-| Symptom                                    | Likely Cause                           | Check                                     |
-| ------------------------------------------ | -------------------------------------- | ----------------------------------------- |
-| `invalid_token` on batch sync              | Wrong partner API key                  | Re-register partner with known API key    |
-| `missing field ec_id`                      | Wrong request schema                   | Use `ec_id` field                         |
-| `ts_reason=no_consent`                     | Missing/invalid consent cookie         | Include valid `euconsent-v2`              |
-| `ts_reason=write_failed`                   | KV write blocked (often consent state) | Inspect identity KV entry and store links |
-| `/identify` returns `{"consent":"denied"}` | No consent for current request         | Send consent cookie                       |
-| No `uids` in `/identify`                   | No successful sync yet                 | Run `/sync` or batch sync first           |
+| Symptom                                               | Likely Cause                           | Check                                      |
+| ----------------------------------------------------- | -------------------------------------- | ------------------------------------------ |
+| `invalid_token` on batch sync                         | Wrong partner API key                  | Re-register partner with known API key     |
+| `missing field ec_id`                                 | Wrong request schema                   | Use `ec_id` field                          |
+| `ts_reason=no_consent`                                | Missing/invalid consent cookie         | Include valid `euconsent-v2`               |
+| `ts_reason=write_failed`                              | KV write blocked (often consent state) | Inspect identity KV entry and store links  |
+| `/_ts/api/v1/identify` returns `{"consent":"denied"}` | No consent for current request         | Send consent cookie                        |
+| No `uids` in `/_ts/api/v1/identify`                   | No successful sync yet                 | Run `/_ts/api/v1/sync` or batch sync first |
 
 See also: [Edge Cookies](/guide/edge-cookies), [Configuration](/guide/configuration), [API Reference](/guide/api-reference)
diff --git a/docs/guide/edge-cookies.md b/docs/guide/edge-cookies.md
index 917aa027..b2d99ed3 100644
--- a/docs/guide/edge-cookies.md
+++ b/docs/guide/edge-cookies.md
@@ -42,8 +42,8 @@ Configure EC settings in `trusted-server.toml`. See the full [Configuration Refe
 - Returning requests with consent and an existing `ts-ec` receive both:
   - `x-ts-ec` response header
   - refreshed `Set-Cookie: ts-ec=...`
-- `/identify` is read-only and returns identity enrichment (`uids` and `eids`)
-- `/sync` and `/_ts/api/v1/sync` write mappings into the EC identity graph
+- `/_ts/api/v1/identify` is read-only and returns identity enrichment (`uids` and `eids`)
+- `/_ts/api/v1/sync` and `/_ts/api/v1/batch-sync` write mappings into the EC identity graph
 
 ## Next Steps
 
diff --git a/docs/superpowers/specs/2026-03-24-ssc-prd-design.md b/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
index ec32196c..7ed0a6cc 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-prd-design.md
@@ -68,8 +68,8 @@ Today, regular cookies don't suffice for publisher and partner needs. Additional
 - Implement real-time consent withdrawal: delete cookie and KV entry when consent is revoked
 - Build a server-side identity graph in Fastly KV Store that accumulates resolved partner IDs over time
 - Provide three KV write paths: real-time pixel sync redirects, S2S batch push from partners, and TS-initiated S2S pull from partner resolution endpoints
-- Expose two bidstream integration modes: header decoration (`/identify`) and full auction orchestration (`/auction`)
-- Expose a publisher-authenticated `/_ts/admin/partners/register` endpoint for partner provisioning without direct KV access
+- Expose two bidstream integration modes: header decoration (`/_ts/api/v1/identify`) and full auction orchestration (`/auction`)
+- Expose a publisher-authenticated `/_ts/admin/v1/partners/register` endpoint for partner provisioning without direct KV access
 
 ### Non-Goals
 
@@ -116,9 +116,9 @@ TS Lite is a runtime configuration of the existing Trusted Server binary. It is
 | `GET /first-party/proxy-rebuild`       | Enabled  | Disabled                |
 | HTML injection pipeline                | Enabled  | Disabled                |
 | GTM integration                        | Enabled  | Disabled                |
-| `GET /sync`                            | Disabled | **Enabled**             |
-| `GET /identify`                        | Disabled | **Enabled**             |
-| `POST /_ts/api/v1/sync`                | Disabled | **Enabled**             |
+| `GET /_ts/api/v1/sync`                 | Disabled | **Enabled**             |
+| `GET /_ts/api/v1/identify`             | Disabled | **Enabled**             |
+| `POST /_ts/api/v1/batch-sync`          | Disabled | **Enabled**             |
 | `GET /.well-known/trusted-server.json` | Enabled  | Enabled                 |
 
 When a disabled route is requested, TS returns `404` with the header `X-ts-error: feature-disabled`.
@@ -341,15 +341,15 @@ The EC cookie is deterministic (derived from IP + publisher salt) and lives in t
 | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | EC cookie creation                   | Set the cookie. Skip the KV entry creation silently. Log the failure at `warn` level.                                             | The cookie is the identity anchor — it does not require KV. The KV entry will be created on the next request once KV recovers.                                                                                                                                    |
 | EC cookie refresh (existing user)    | Refresh the cookie. Skip the KV `last_seen` update silently. Log at `warn`.                                                       | Same as above — the cookie continues working. Stale `last_seen` is acceptable.                                                                                                                                                                                    |
-| `/sync` KV write                     | Redirect to `return` with `ts_synced=0&ts_reason=write_failed`.                                                                   | The browser redirect must not be blocked by KV availability. This case is already specified in Section 9.4.                                                                                                                                                       |
-| `/identify` KV read                  | Return `200` with `ec` hash (from cookie) and `degraded: true`. Set `uids: {}` and `eids: []`.                                    | The EC hash is still valid and useful for attribution and analytics. Empty uids signal that enrichment is unavailable, not that the user has no synced partners. `degraded: true` lets callers distinguish transient KV failure from a genuinely unenriched user. |
+| `/_ts/api/v1/sync` KV write          | Redirect to `return` with `ts_synced=0&ts_reason=write_failed`.                                                                   | The browser redirect must not be blocked by KV availability. This case is already specified in Section 9.4.                                                                                                                                                       |
+| `/_ts/api/v1/identify` KV read       | Return `200` with `ec` hash (from cookie) and `degraded: true`. Set `uids: {}` and `eids: []`.                                    | The EC hash is still valid and useful for attribution and analytics. Empty uids signal that enrichment is unavailable, not that the user has no synced partners. `degraded: true` lets callers distinguish transient KV failure from a genuinely unenriched user. |
 | S2S batch write (`/_ts/api/v1/sync`) | Return `207` with all mappings rejected, `reason: "kv_unavailable"`.                                                              | The request was valid; the failure is infrastructure. Partners should retry the batch.                                                                                                                                                                            |
 | S2S pull sync write (async)          | Discard the resolved uid. Log at `warn`. Retry will occur on the next qualifying request per the `pull_sync_ttl_sec` window.      | Async path — no user-facing impact.                                                                                                                                                                                                                               |
 | Consent withdrawal KV delete         | Expire the cookie immediately. Log the KV delete failure at `error` level. Retry the KV delete on the next request for this user. | Cookie deletion is the primary enforcement mechanism. KV delete failure must not block or delay the cookie expiry.                                                                                                                                                |
 
-**`degraded: true` in `/identify` responses**
+**`degraded: true` in `/_ts/api/v1/identify` responses**
 
-When a KV read fails, the `/identify` response includes `"degraded": true` in the JSON body alongside an empty `uids` and `eids`. The `ec` field is still populated from the cookie. Callers should proceed with identity-only targeting (EC hash) and omit partner UID parameters from downstream requests.
+When a KV read fails, the `/_ts/api/v1/identify` response includes `"degraded": true` in the JSON body alongside an empty `uids` and `eids`. The `ec` field is still populated from the cookie. Callers should proceed with identity-only targeting (EC hash) and omit partner UID parameters from downstream requests.
 
 ```json
 {
@@ -461,7 +461,7 @@ This is the primary real-time write path for building the identity graph from ex
 ### 9.2 Endpoint
 
 ```
-GET /sync
+GET /_ts/api/v1/sync
 ```
 
 ### 9.3 Parameters
@@ -505,7 +505,7 @@ Partners should treat `ts_synced=0` as a signal that the mapping was not stored.
 
 **Acceptance criteria:**
 
-- [ ] `GET /sync?partner=ssp_x&uid=abc&return=https://sync.ssp.com/ack` returns a redirect to the `return` URL within 50ms (excluding KV write time)
+- [ ] `GET /_ts/api/v1/sync?partner=ssp_x&uid=abc&return=https://sync.ssp.com/ack` returns a redirect to the `return` URL within 50ms (excluding KV write time)
 - [ ] KV entry for the EC hash contains `ids.ssp_x.uid = "abc"` after a successful sync; response redirects to `return` with `ts_synced=1`
 - [ ] If no `ts-ec` cookie is present, redirects to `return` with `ts_synced=0&ts_reason=no_ec`; no KV write performed
 - [ ] If consent is absent or invalid, redirects to `return` with `ts_synced=0&ts_reason=no_consent`; no KV write performed
@@ -524,17 +524,17 @@ The S2S batch sync API allows partners to push ID mappings to Trusted Server in
 ### 10.2 Endpoint
 
 ```
-POST /_ts/api/v1/sync
+POST /_ts/api/v1/batch-sync
 ```
 
 ### 10.3 Authentication
 
-Partners authenticate with a rotatable API key. Key rotation must not require redeploying the binary. Partner provisioning is handled via the `/_ts/admin/partners/register` endpoint (see Section 15, Open Questions).
+Partners authenticate with a rotatable API key. Key rotation must not require redeploying the binary. Partner provisioning is handled via the `/_ts/admin/v1/partners/register` endpoint (see Section 15, Open Questions).
 
 ### 10.4 Request
 
 ```
-POST /_ts/api/v1/sync
+POST /_ts/api/v1/batch-sync
 Content-Type: application/json
 Authorization: Bearer <api_key>
 
@@ -593,7 +593,7 @@ Before writing a mapping, Trusted Server checks the KV metadata for the given EC
 
 **Acceptance criteria:**
 
-- [ ] `POST /_ts/api/v1/sync` with a valid Bearer token and a batch of up to 1000 mappings returns a response within 5 seconds
+- [ ] `POST /_ts/api/v1/batch-sync` with a valid Bearer token and a batch of up to 1000 mappings returns a response within 5 seconds
 - [ ] Accepted mappings are written to the corresponding KV identity graph entries within 1 second
 - [ ] Mappings for unknown `ec_hash` values are rejected with `ec_hash_not_found`
 - [ ] Mappings for users with withdrawn consent are rejected with `consent_withdrawn`
@@ -721,22 +721,22 @@ The following fields are added to the partner record schema (Section 13.3):
 
 Trusted Server exposes two modes for injecting EC identity into the bidstream. Publishers choose the mode that fits their existing ad stack.
 
-### 12.2 Mode A: Identity resolution (`/identify`)
+### 12.2 Mode A: Identity resolution (`/_ts/api/v1/identify`)
 
-Trusted Server exposes `/identify` as a standalone identity resolution endpoint for callers that need EC identity and resolved partner UIDs outside of TS's own auction orchestration. TS builds the OpenRTB request in Mode B — `/identify` is not part of that path. It serves three distinct use cases:
+Trusted Server exposes `/_ts/api/v1/identify` as a standalone identity resolution endpoint for callers that need EC identity and resolved partner UIDs outside of TS's own auction orchestration. TS builds the OpenRTB request in Mode B — `/_ts/api/v1/identify` is not part of that path. It serves three distinct use cases:
 
 **Use case 1 — Attribution and analytics**
 Any server-side or browser-side system that needs to tag an event, impression, or conversion with the user's EC hash. Examples: analytics pipelines, attribution platforms, reporting dashboards.
 
 **Use case 2 — Publisher ad server outbid context**
-After TS's auction completes and winners are delivered to the publisher's ad server endpoint, the publisher's ad server may need EC identity and resolved partner UIDs to evaluate whether to accept the programmatic winner or outbid with a direct-sold placement. For this use case, TS includes the EC identity in the winner notification payload directly (see Section 12.3) — a separate `/identify` call is only needed if the publisher's ad server receives the winner through a path that does not carry TS headers.
+After TS's auction completes and winners are delivered to the publisher's ad server endpoint, the publisher's ad server may need EC identity and resolved partner UIDs to evaluate whether to accept the programmatic winner or outbid with a direct-sold placement. For this use case, TS includes the EC identity in the winner notification payload directly (see Section 12.3) — a separate `/_ts/api/v1/identify` call is only needed if the publisher's ad server receives the winner through a path that does not carry TS headers.
 
 **Use case 3 — Client-side wrappers for non-TS SSPs**
-Some SSPs run client-side header bidding wrappers (e.g., Amazon TAM, certain Index Exchange configurations) that do not participate in TS's server-side auction orchestration. A Prebid.js module or custom wrapper script calls `/identify` from the browser to obtain the EC hash and resolved partner UIDs, then injects those values into bid requests sent to those SSPs. This ensures non-TS demand sources bid with the same identity enrichment as TS-orchestrated bids, enabling a fair comparison at winner selection.
+Some SSPs run client-side header bidding wrappers (e.g., Amazon TAM, certain Index Exchange configurations) that do not participate in TS's server-side auction orchestration. A Prebid.js module or custom wrapper script calls `/_ts/api/v1/identify` from the browser to obtain the EC hash and resolved partner UIDs, then injects those values into bid requests sent to those SSPs. This ensures non-TS demand sources bid with the same identity enrichment as TS-orchestrated bids, enabling a fair comparison at winner selection.
 
-> **Prerequisite for use case 3:** For a non-TS SSP to receive a useful UID from `/identify`, that SSP must already be a registered partner in `partner_store` and must have a resolved uid in the KV identity graph for this user (via pixel sync, S2S batch, or S2S pull). Without a prior sync, `/identify` returns no uid for that partner.
+> **Prerequisite for use case 3:** For a non-TS SSP to receive a useful UID from `/_ts/api/v1/identify`, that SSP must already be a registered partner in `partner_store` and must have a resolved uid in the KV identity graph for this user (via pixel sync, S2S batch, or S2S pull). Without a prior sync, `/_ts/api/v1/identify` returns no uid for that partner.
 
-**Endpoint:** `GET /identify`
+**Endpoint:** `GET /_ts/api/v1/identify`
 
 **When to call:** Once per auction event — not per-pageview. For use case 3, call before sending bid requests to non-TS SSPs.
 
@@ -744,7 +744,7 @@ Some SSPs run client-side header bidding wrappers (e.g., Amazon TAM, certain Ind
 
 **Pattern 1 — Browser-direct (recommended for use cases 1 and 3)**
 
-A script on the publisher's page calls `/identify` via `fetch()`. Because `ec.publisher.com` is same-site with the publisher's domain, the browser sends the `ts-ec` cookie and consent cookies automatically. No forwarding required.
+A script on the publisher's page calls `/_ts/api/v1/identify` via `fetch()`. Because `ec.publisher.com` is same-site with the publisher's domain, the browser sends the `ts-ec` cookie and consent cookies automatically. No forwarding required.
 
 ```js
 const identity = await fetch('https://ec.publisher.com/identify').then((r) =>
@@ -773,7 +773,7 @@ A server-side caller must forward the following from the original browser reques
 
 #### Cookie and consent handling
 
-`/identify` follows the EC retrieval priority from Section 6.4. It does not generate a new EC — if no EC is present, the response body contains `consent: denied` and empty identity fields. Consent is evaluated per Section 7.1. `/identify` never sets or modifies cookies.
+`/_ts/api/v1/identify` follows the EC retrieval priority from Section 6.4. It does not generate a new EC — if no EC is present, the response body contains `consent: denied` and empty identity fields. Consent is evaluated per Section 7.1. `/_ts/api/v1/identify` never sets or modifies cookies.
 
 #### Response
 
@@ -850,7 +850,7 @@ Trusted Server owns the full auction path in Mode B. TS builds the OpenRTB reque
 
 **EC context in winner notification to publisher's ad server:**
 
-When TS delivers auction winners to the publisher's ad server endpoint, the response includes EC identity so the publisher's ad server has full context for its outbid decision without needing to call `/identify` separately:
+When TS delivers auction winners to the publisher's ad server endpoint, the response includes EC identity so the publisher's ad server has full context for its outbid decision without needing to call `/_ts/api/v1/identify` separately:
 
 | Header            | Value                                                        |
 | ----------------- | ------------------------------------------------------------ |
@@ -895,21 +895,21 @@ Each partner registered in `partner_store` declares:
 
 ### 12.6 User stories
 
-**As a publisher using Mode A for analytics/attribution**, I want to call `/identify` from a browser script so that I can tag events and impressions with the user's EC hash and resolved partner UIDs using URL parameters.
+**As a publisher using Mode A for analytics/attribution**, I want to call `/_ts/api/v1/identify` from a browser script so that I can tag events and impressions with the user's EC hash and resolved partner UIDs using URL parameters.
 
 **Acceptance criteria:**
 
-- [ ] `GET /identify` returns `200` with a valid JSON body within 30ms when EC is present and consent is valid
+- [ ] `GET /_ts/api/v1/identify` returns `200` with a valid JSON body within 30ms when EC is present and consent is valid
 - [ ] `uids` object contains one key per partner with `bidstream_enabled: true` and a resolved UID; partners with no resolved UID are omitted
 - [ ] If consent is denied, response is `403 Forbidden` with body `{"consent": "denied"}`
 - [ ] If no EC is present, response is `204 No Content` with no body
 - [ ] Response headers `X-ts-ec`, `X-ts-eids`, `X-ts-<partner_id>`, and `X-ts-ec-consent` are present on `200` responses as supplementary signals
 
-**As a publisher using a client-side wrapper for non-TS SSPs**, I want to call `/identify` from my Prebid.js configuration so that SSPs outside TS's auction receive the same identity enrichment as TS-orchestrated bids, enabling a fair winner comparison.
+**As a publisher using a client-side wrapper for non-TS SSPs**, I want to call `/_ts/api/v1/identify` from my Prebid.js configuration so that SSPs outside TS's auction receive the same identity enrichment as TS-orchestrated bids, enabling a fair winner comparison.
 
 **Acceptance criteria:**
 
-- [ ] `GET /identify` called from the browser returns resolved UIDs for all registered partners with a KV entry for this user
+- [ ] `GET /_ts/api/v1/identify` called from the browser returns resolved UIDs for all registered partners with a KV entry for this user
 - [ ] A partner with no KV entry for this user is omitted from `uids` — no empty or null entries
 - [ ] Response is available within 30ms so it does not block Prebid.js auction timeout
 
@@ -933,7 +933,7 @@ The following capabilities must be configurable without redeploying the binary:
 - **Publisher passphrase** — the HMAC key used for EC hash generation; same value across all of the publisher's domains; shared with trusted partners to form an identity-federated consortium
 - **Identity graph store** — the KV store backing the EC hash → identity graph
 - **Partner registry store** — the KV store backing partner configuration and API key validation
-- **Partner records** — each partner's allowed sync domains, bidstream settings, pull sync configuration, and API credentials; managed via `/_ts/admin/partners/register` without redeployment
+- **Partner records** — each partner's allowed sync domains, bidstream settings, pull sync configuration, and API credentials; managed via `/_ts/admin/v1/partners/register` without redeployment
 
 The exact configuration format (TOML keys, KV schema, JSON field names) is an engineering decision and will be documented in the technical design doc.
 
@@ -945,11 +945,11 @@ The following documentation changes are required alongside the EC feature:
 
 - **Rename SyntheticID → Edge Cookie** across the entire `docs/` GitHub Pages site. The underlying concept is the same but the product name changes.
 - **New integration guides**, one per customer type:
-  - Publisher (full TS): enabling EC in `trusted-server.toml`, partner onboarding via `/_ts/admin/partners/register`
+  - Publisher (full TS): enabling EC in `trusted-server.toml`, partner onboarding via `/_ts/admin/v1/partners/register`
   - SSP: pixel sync integration guide, sync pixel URL format, callback handling, optional pull resolution endpoint
   - DSP: S2S batch API reference, authentication, conflict resolution behavior, optional pull resolution endpoint
   - Identity Provider: registering as a partner, `source_domain` and `openrtb_atype` configuration, sync patterns
-- **API reference** for the four new endpoints: `GET /sync`, `GET /identify`, `POST /_ts/api/v1/sync`, and the partner-side pull resolution contract
+- **API reference** for the four new endpoints: `GET /_ts/api/v1/sync`, `GET /_ts/api/v1/identify`, `POST /_ts/api/v1/batch-sync`, and the partner-side pull resolution contract
 - **Pull sync integration guide**: partner requirements for exposing a resolution endpoint, authentication, expected response shape, rate limit behavior
 - **Consent enforcement guide**: how TCF and GPP signals are read, precedence rules, what happens on withdrawal
 
@@ -957,10 +957,10 @@ The following documentation changes are required alongside the EC feature:
 
 ## 15. Open Questions
 
-| #   | Question                                                                                                                                                                                                                                                                                         | Owner       | Status                                                                          |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------- |
-| 1   | Partner provisioning: TS will expose a `/_ts/admin/partners/register` endpoint authenticated at the publisher level (bearer token issued per publisher Fastly service), so publishers can onboard SSP/DSP partners without touching KV directly. Engineering to define the exact auth mechanism. | Engineering | **Resolved** — `/_ts/admin/partners/register` endpoint, publisher-authenticated |
-| 2   | Should TS Lite expose a `GET /health` endpoint so partners can programmatically verify their service is running and their partner config is active in KV?                                                                                                                                        | Product     | **N/A** — TS Lite deferred (see Section 5)                                      |
+| #   | Question                                                                                                                                                                                         | Owner       | Status                                                                                  |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------- |
+| 1   | Partner provisioning: TS will expose a `/_ts/admin/v1/partners/register` endpoint authenticated at the publisher level, so publishers can onboard SSP/DSP partners without touching KV directly. | Engineering | **Resolved** — `/_ts/admin/v1/partners/register` endpoint protected by admin basic auth |
+| 2   | Should TS Lite expose a `GET /health` endpoint so partners can programmatically verify their service is running and their partner config is active in KV?                                        | Product     | **N/A** — TS Lite deferred (see Section 5)                                              |
 
 ---
 
@@ -970,7 +970,7 @@ The following documentation changes are required alongside the EC feature:
 | ------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | EC match rate (returning users) | >90% within 30 days                                                                     | Fastly real-time logs: ratio of requests with existing `ts-ec` cookie vs. new EC generations |
 | Consent enforcement accuracy    | 0 ECs created for opted-out EU/UK users                                                 | Log audit: verify no `ts-ec` `Set-Cookie` in responses where consent signal is absent        |
-| KV sync latency (pixel sync)    | p99 <75ms end-to-end                                                                    | Fastly log timing on `/sync` endpoint                                                        |
+| KV sync latency (pixel sync)    | p99 <75ms end-to-end                                                                    | Fastly log timing on `/_ts/api/v1/sync` endpoint                                             |
 | S2S batch API throughput        | >500 mappings/sec sustained                                                             | Load test prior to partner onboarding                                                        |
 | S2S pull sync resolution rate   | >30% of pull calls return a non-null uid within 60 days of first partner go-live        | Fastly log: pull call outcomes per partner                                                   |
 | Identity graph fill rate        | >50% of EC hashes with at least 1 resolved partner ID within 60 days of partner go-live | KV scan sample                                                                               |
diff --git a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
index 906a9036..b015eccb 100644
--- a/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
+++ b/docs/superpowers/specs/2026-03-24-ssc-technical-spec-design.md
@@ -17,10 +17,10 @@
 6. [Consent Enforcement](#6-consent-enforcement)
 7. [KV Store Identity Graph](#7-kv-store-identity-graph)
    7A. [Device Signals and Bot Gate](#7a-device-signals-and-bot-gate)
-8. [Pixel Sync Endpoint (`GET /sync`)](#8-pixel-sync-endpoint-get-sync)
-9. [S2S Batch Sync API (`POST /_ts/api/v1/sync`)](#9-s2s-batch-sync-api-post-apiv1sync)
+8. [Pixel Sync Endpoint (`GET /_ts/api/v1/sync`)](#8-pixel-sync-endpoint-get-sync)
+9. [S2S Batch Sync API (`POST /_ts/api/v1/batch-sync`)](#9-s2s-batch-sync-api-post-apiv1sync)
 10. [S2S Pull Sync (TS-Initiated)](#10-s2s-pull-sync-ts-initiated)
-11. [Identity Resolution Endpoint (`GET /identify`)](#11-identity-resolution-endpoint-get-identify)
+11. [Identity Resolution Endpoint (`GET /_ts/api/v1/identify`)](#11-identity-resolution-endpoint-get-identify)
 12. [Bidstream Decoration (`/auction` Mode B)](#12-bidstream-decoration-auction-mode-b)
 13. [Partner Registry and Admin Endpoint](#13-partner-registry-and-admin-endpoint)
 14. [Configuration](#14-configuration)
@@ -101,10 +101,10 @@ Phase 2 — inside organic handlers only:
 handle_publisher_request()     integration_registry.handle_proxy()
 calls ec_context.generate_if_needed()   calls ec_context.generate_if_needed()
 
-EC route handlers (GET /sync, GET /identify, POST /auction,
-POST /_ts/api/v1/sync, POST /_ts/admin/*) NEVER call generate_if_needed().
-`/identify`, `/auction`, `POST /_ts/api/v1/sync`, and `POST /_ts/admin/*`
-use `EcContext` in read-only form. `GET /sync` is the one exception:
+EC route handlers (GET /_ts/api/v1/sync, GET /_ts/api/v1/identify, POST /auction,
+POST /_ts/api/v1/batch-sync, POST /_ts/admin/*) NEVER call generate_if_needed().
+`/_ts/api/v1/identify`, `/auction`, `POST /_ts/api/v1/batch-sync`, and `POST /_ts/admin/*`
+use `EcContext` in read-only form. `GET /_ts/api/v1/sync` is the one exception:
 it never bootstraps an EC, but it may replace `ec_context.consent`
 with a locally-decoded fallback consent context for that request only
 when the optional `consent` query param is the sole available signal.
@@ -242,7 +242,7 @@ Generation (step 3 above becoming a new EC) happens only inside organic handlers
 
 ```rust
 /// Per-request Edge Cookie state. Constructed pre-routing once per request.
-/// Organic handlers call `generate_if_needed()` to mint new ECs. `/sync` is the
+/// Organic handlers call `generate_if_needed()` to mint new ECs. `/_ts/api/v1/sync` is the
 /// one EC route that may replace `consent` with a locally-decoded fallback for
 /// the remainder of that request only.
 pub struct EcContext {
@@ -339,9 +339,9 @@ impl EcContext {
 1. If `!allows_ec_creation(&consent) && cookie_was_present`: call `clear_ec_on_response()` (deletes cookie **and** strips any handler-built `X-ts-ec`, `X-ts-eids`, `X-ts-ec-consent`, `x-ts-eids-truncated`, and `X-ts-<partner_id>` response headers) and write withdrawal tombstones for each valid known EC ID (cookie-derived and, when different, header-derived). This runs on **every route** — consent withdrawal is always real-time enforced. Keyed on `cookie_was_present`, not `ec_was_present`, because only a cookie-held EC can be deleted by the browser. When the cookie is malformed and there is no valid header-derived EC ID, no tombstone is written.
 2. If `ec_was_present == true && ec_generated == false && allows_ec_creation(&consent)`: call `kv.update_last_seen()` (debounced). If `cookie_ec_value.is_some()`, also call `set_ec_on_response()` to reconcile the browser cookie to the authoritative header-derived EC.
 3. If `ec_generated == true`: call `set_ec_on_response()` — sets `Set-Cookie` and `X-ts-ec`. KV create already happened inside `generate_if_needed()`; `ec_finalize_response()` does NOT write KV beyond tombstones and `last_seen`.
-4. Handler-built response headers (`X-ts-ec`, `X-ts-eids` set directly by `/identify`) are preserved on non-withdrawal paths only.
+4. Handler-built response headers (`X-ts-ec`, `X-ts-eids` set directly by `/_ts/api/v1/identify`) are preserved on non-withdrawal paths only.
 
-**Note on `kv_degraded`:** Not on `EcContext` — `read_from_request()` does not read KV. Handlers track degraded state locally. `/identify` returns `degraded: true` in the JSON body on KV read failure; the auction handler treats a failed read as `eids: []`.
+**Note on `kv_degraded`:** Not on `EcContext` — `read_from_request()` does not read KV. Handlers track degraded state locally. `/_ts/api/v1/identify` returns `degraded: true` in the JSON body on KV read failure; the auction handler treats a failed read as `eids: []`.
 
 ````
 
@@ -390,7 +390,7 @@ pub fn clear_ec_on_response(response: &mut Response, cookie_domain: &str);
 
 ### 5.3 Response header
 
-`X-ts-ec: {64-hex}.{6-alnum}` is set by `set_ec_on_response()` when an EC is available. In current behavior, `ec_finalize_response()` calls `set_ec_on_response()` for returning users (`ec_was_present == true && ec_generated == false && allows_ec_creation(&consent)`) and for newly generated ECs (`ec_generated == true`). `/identify` and `/auction` also set EC-related headers on their response paths.
+`X-ts-ec: {64-hex}.{6-alnum}` is set by `set_ec_on_response()` when an EC is available. In current behavior, `ec_finalize_response()` calls `set_ec_on_response()` for returning users (`ec_was_present == true && ec_generated == false && allows_ec_creation(&consent)`) and for newly generated ECs (`ec_generated == true`). `/_ts/api/v1/identify` and `/auction` also set EC-related headers on their response paths.
 
 This header is added to `INTERNAL_HEADERS` in `constants.rs` so it is stripped before proxying to downstream backends, consistent with existing `X-ts-*` handling.
 
@@ -484,7 +484,7 @@ ec_context.generate_if_needed(settings, &kv)    // best-effort — never 500s
           → set_ec_on_response()        (Set-Cookie + X-ts-ec on response)
 ```
 
-EC route handlers (`GET /sync`, `GET /identify`, `POST /_ts/api/v1/sync`, `POST /_ts/admin/*`) never call `generate_if_needed()`. `ec_finalize_response()` will still delete the cookie on those routes if consent is withdrawn — that is intentional.
+EC route handlers (`GET /_ts/api/v1/sync`, `GET /_ts/api/v1/identify`, `POST /_ts/api/v1/batch-sync`, `POST /_ts/admin/*`) never call `generate_if_needed()`. `ec_finalize_response()` will still delete the cookie on those routes if consent is withdrawn — that is intentional.
 
 **Cookie write rule:** `Set-Cookie` is written when `set_ec_on_response()` is called. In current behavior this includes returning-user requests (consent allowed + EC present) and first-time generation (`ec_generated == true`), so `Max-Age` is refreshed on ordinary returning requests.
 
@@ -615,7 +615,7 @@ Two KV stores are used. Their names are configured in `trusted-server.toml`:
 }
 ```
 
-The `ok` field in metadata is a **historical consent record for S2S consumers only** — it is set to `false` by `write_withdrawal_tombstone()` so that batch sync clients (`POST /_ts/api/v1/sync`) can return `consent_withdrawn` rather than `ec_id_not_found` during the 24-hour tombstone TTL.
+The `ok` field in metadata is a **historical consent record for S2S consumers only** — it is set to `false` by `write_withdrawal_tombstone()` so that batch sync clients (`POST /_ts/api/v1/batch-sync`) can return `consent_withdrawn` rather than `ec_id_not_found` during the 24-hour tombstone TTL.
 
 **`consent.ok` is NOT used to make the withdrawal decision on the main request path.** Consent withdrawal is determined entirely from `allows_ec_creation(&ec_context.consent)` on the current request. When withdrawal is detected, the cookie is deleted and `write_withdrawal_tombstone()` is called in-path (setting `ok = false`, 24h TTL — see §6.2). Engineers must not add a KV read to the consent withdrawal hot path based on this field.
 
@@ -816,7 +816,7 @@ impl KvIdentityGraph {
     /// This recovery path is intentional: it materializes the graph later when
     /// the initial best-effort `create_or_revive()` on EC generation failed.
     /// Batch sync still performs its explicit existence/tombstone check before
-    /// calling this method, so `POST /_ts/api/v1/sync` retains its `ec_id_not_found`
+    /// calling this method, so `POST /_ts/api/v1/batch-sync` retains its `ec_id_not_found`
     /// contract.
     ///
     /// # Arguments
@@ -857,7 +857,7 @@ impl KvIdentityGraph {
     /// Skips evaluation if `cluster_checked` is within `cluster_recheck_secs`.
     /// Otherwise calls `count_hash_prefix_keys()` and writes the result to
     /// `entry.network` via CAS. Returns the cluster size for inclusion in
-    /// the `/identify` response.
+    /// the `/_ts/api/v1/identify` response.
     pub fn evaluate_cluster(
         &self,
         ec_id: &str,
@@ -868,7 +868,7 @@ impl KvIdentityGraph {
     ///
     /// Instead of hard-deleting the KV entry, this overwrites it with
     /// `consent.ok = false`, clears all partner IDs, and sets a 24-hour TTL.
-    /// The tombstone allows batch sync clients (`POST /_ts/api/v1/sync`) to return
+    /// The tombstone allows batch sync clients (`POST /_ts/api/v1/batch-sync`) to return
     /// `consent_withdrawn` rather than `ec_id_not_found` for the tombstone TTL.
     ///
     /// After the 24-hour TTL expires, the entry is gone. Any subsequent `get()`
@@ -902,9 +902,9 @@ impl KvIdentityGraph {
 | Operation                          | KV unavailable | Action                                                                                         |
 | ---------------------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
 | EC cookie creation                 | KV error       | Set cookie. Skip KV create. Log `warn`.                                                        |
-| `/sync` KV write                   | KV error       | Redirect with `ts_synced=0&ts_reason=write_failed`.                                            |
-| `/identify` KV read                | KV error       | Return `200` with `ec` set, `degraded: true`, empty `uids`/`eids`.                             |
-| `POST /_ts/api/v1/sync`            | KV error       | Return `207` with all mappings rejected, `reason: "kv_unavailable"`.                           |
+| `/_ts/api/v1/sync` KV write        | KV error       | Redirect with `ts_synced=0&ts_reason=write_failed`.                                            |
+| `/_ts/api/v1/identify` KV read     | KV error       | Return `200` with `ec` set, `degraded: true`, empty `uids`/`eids`.                             |
+| `POST /_ts/api/v1/batch-sync`      | KV error       | Return `207` with all mappings rejected, `reason: "kv_unavailable"`.                           |
 | Pull sync KV write                 | KV error       | Discard uid. Log `warn`. Retry on next qualifying request.                                     |
 | Consent withdrawal tombstone write | KV error       | Delete cookie (primary enforcement). Log `error`. Next request: no cookie → no EC regenerated. |
 
@@ -1117,7 +1117,7 @@ pub struct KvNetwork {
 }
 ```
 
-**Written:** only by the `/identify` endpoint, never on the organic proxy path.
+**Written:** only by the `/_ts/api/v1/identify` endpoint, never on the organic proxy path.
 The prefix-match list API call required to compute `cluster_size` is too
 expensive for the hot path.
 
@@ -1186,7 +1186,7 @@ identification and would require explicit consent basis under GDPR Art. 4(1).
 
 ---
 
-## 8. Pixel Sync Endpoint (`GET /sync`)
+## 8. Pixel Sync Endpoint (`GET /_ts/api/v1/sync`)
 
 ### 8.1 Module: `ec/sync_pixel.rs`
 
@@ -1241,7 +1241,7 @@ pub async fn handle_sync(
    effective consent view, avoiding a same-request “write partner ID, then
    withdraw EC” conflict. Do NOT re-call `build_consent_context()` — that would
    trigger `try_kv_write()` and persist the query-param consent to the consent KV
-   store, which is not intended. The decoded fallback applies only to this `/sync`
+   store, which is not intended. The decoded fallback applies only to this `/_ts/api/v1/sync`
    request; it is not written to the consent KV store and does not change any
    future request unless the client sends real consent cookies/headers again.
 
@@ -1288,7 +1288,7 @@ Do not modify any other query parameters on the `return` URL.
 
 ---
 
-## 9. S2S Batch Sync API (`POST /_ts/api/v1/sync`)
+## 9. S2S Batch Sync API (`POST /_ts/api/v1/batch-sync`)
 
 ### 9.1 Module: `ec/sync_batch.rs`
 
@@ -1311,7 +1311,7 @@ pub async fn handle_batch_sync(
 4. If no match or verification fails → `401 Unauthorized` with no body processing.
 5. If KV lookup fails (store unavailable) → `503 Service Unavailable`.
 
-Key rotation does not require binary redeployment — partners update via `/_ts/admin/partners/register`, which handles old API-key index cleanup (§13.1).
+Key rotation does not require binary redeployment — partners update via `/_ts/admin/v1/partners/register`, which handles old API-key index cleanup (§13.1).
 
 ### 9.2.1 API-key rate limiting
 
@@ -1322,7 +1322,7 @@ Exceeded → `429 Too Many Requests` with body `{ "error": "rate_limit_exceeded"
 ### 9.3 Request format
 
 ```
-POST /_ts/api/v1/sync
+POST /_ts/api/v1/batch-sync
 Content-Type: application/json
 Authorization: Bearer <api_key>
 
@@ -1446,7 +1446,7 @@ fn pull_one_partner(
 
 A pull sync is dispatched for a partner when all of the following are true on a request:
 
-1. The request was routed to an **organic handler** (`handle_publisher_request` or `integration_registry.handle_proxy`). Pull sync never fires on EC route handlers (`/sync`, `/identify`, `/_ts/api/v1/sync`, `/_ts/admin/*`) or `/auction`. This matches the PRD requirement that pull calls must not happen during the pixel sync flow.
+1. The request was routed to an **organic handler** (`handle_publisher_request` or `integration_registry.handle_proxy`). Pull sync never fires on EC route handlers (`/_ts/api/v1/sync`, `/_ts/api/v1/identify`, `/_ts/api/v1/sync`, `/_ts/admin/*`) or `/auction`. This matches the PRD requirement that pull calls must not happen during the pixel sync flow.
 2. A valid EC is present (`ec_context.ec_hash().is_some()`). This includes an EC
    newly generated on the current organic request — pull sync may run immediately
    after first-page EC creation because the response cookie is flushed before the
@@ -1488,13 +1488,13 @@ Any other non-200 response is treated as a transient failure. No retry. The next
 
 ### 10.5 KV write on success
 
-On a non-null `uid`: call `kv.upsert_partner_id(ec_id, partner_id, uid, now())`. If the root entry is missing, the upsert creates a minimal live entry first (same recovery path as `/sync`). On KV failure: log `warn` and discard the result. Retry occurs on the next qualifying request.
+On a non-null `uid`: call `kv.upsert_partner_id(ec_id, partner_id, uid, now())`. If the root entry is missing, the upsert creates a minimal live entry first (same recovery path as `/_ts/api/v1/sync`). On KV failure: log `warn` and discard the result. Retry occurs on the next qualifying request.
 
 The write updates `ids[partner_id].synced` to the current timestamp, resetting the `pull_sync_ttl_sec` window.
 
 ---
 
-## 11. Identity Resolution Endpoint (`GET /identify`)
+## 11. Identity Resolution Endpoint (`GET /_ts/api/v1/identify`)
 
 ### 11.1 Module: `ec/identify.rs`
 
@@ -1522,7 +1522,7 @@ pub async fn handle_identify(
 
 ### 11.3 EC and consent handling
 
-`/identify` follows `EcContext` retrieval priority (Section 4.2). It does **not**
+`/_ts/api/v1/identify` follows `EcContext` retrieval priority (Section 4.2). It does **not**
 generate a new EC, and the handler itself does not write cookies. However,
 `ec_finalize_response()` still runs after the handler: on consent withdrawal it
 deletes the EC cookie, and on header/cookie mismatch it may reconcile the cookie
@@ -1614,7 +1614,7 @@ These are supplementary — callers should read the JSON body as the primary con
 
 ### 11.6 Performance target
 
-`/identify` must respond within 30ms (excluding network latency) when EC is present and KV read succeeds. This requires the KV read to be on the fast path with no retries.
+`/_ts/api/v1/identify` must respond within 30ms (excluding network latency) when EC is present and KV read succeeds. This requires the KV read to be on the fast path with no retries.
 
 CORS headers must be set to allow browser-direct calls from the publisher's page. The `Access-Control-Allow-Origin` header is dynamically reflected from the `Origin` request header if the origin is an exact match or a subdomain of `settings.publisher.domain`:
 
@@ -1639,7 +1639,7 @@ Vary: Origin
 - **`Origin` header present, hostname matches `publisher.domain` or ends with `.{publisher.domain}` and scheme is `https`:** Reflect origin in `Access-Control-Allow-Origin`. Add `Vary: Origin`.
 - **`Origin` header present but does not match:** Return `403`. No body.
 
-Browser `fetch()` with `credentials: "include"` sends an `OPTIONS` preflight. The router handles `OPTIONS /identify` identically — returns `200 OK` with the CORS headers above and no body.
+Browser `fetch()` with `credentials: "include"` sends an `OPTIONS` preflight. The router handles `OPTIONS /_ts/api/v1/identify` identically — returns `200 OK` with the CORS headers above and no body.
 
 ---
 
@@ -1809,17 +1809,11 @@ impl PartnerStore {
 - `pull_enabled_partners()`: if a listed partner ID returns `None` from `get()`, skip it silently. If the fetched record has `pull_sync_enabled == false`, also skip it silently — that is a stale `_pull_enabled` index entry.
 - The `_pull_enabled` list is vulnerable to lost updates under concurrent registrations. This is accepted — partner registration is a low-frequency admin operation (not a hot path). If lost updates become an issue, a CAS-based read-modify-write can be added later.
 
-### 13.2 Admin endpoint (`POST /_ts/admin/partners/register`)
+### 13.2 Admin endpoint (`POST /_ts/admin/v1/partners/register`)
 
 **Module:** `ec/admin.rs`
 
-> **Codebase invariant — requires test update:** `Settings::ADMIN_ENDPOINTS` in `settings.rs` lists routes that must be covered by a `[[handlers]]` Basic Auth entry. The existing test at `settings.rs:1504-1530` scans `main.rs` for **every** `/_ts/admin/` route string and asserts it appears in `ADMIN_ENDPOINTS`. When `/_ts/admin/partners/register` is added to `main.rs`, this test will fail.
->
-> **Required changes:**
->
-> 1. Do **NOT** add `/_ts/admin/partners/register` to `ADMIN_ENDPOINTS` — it uses bearer-token-in-handler auth.
-> 2. Update the admin-route-scan test (`settings.rs:1504-1530`) to maintain an exclusion list of bearer-token-authed admin routes (e.g., `const BEARER_AUTH_ADMIN_ROUTES: &[&str] = &["/_ts/admin/partners/register"]`) and skip those when asserting `ADMIN_ENDPOINTS` coverage.
-> 3. Narrow the `[[handlers]]` pattern in `trusted-server.toml` from `"^/_ts/admin"` to `"^/_ts/admin/keys"` so that `/_ts/admin/partners/register` is not intercepted by `enforce_basic_auth()` before reaching its bearer-token handler.
+> **Codebase invariant:** `Settings::ADMIN_ENDPOINTS` in `settings.rs` lists routes that must be covered by a `[[handlers]]` Basic Auth entry. `/_ts/admin/v1/partners/register` must stay in that list so the existing `^/_ts/admin` handler protection continues to apply.
 
 ```rust
 pub async fn handle_register_partner(
@@ -1829,13 +1823,13 @@ pub async fn handle_register_partner(
 ) -> Result<Response, Report<TrustedServerError>>;
 ```
 
-Authentication: `Authorization: Bearer <token>` header, validated inside the handler against `settings.ec.admin_token_hash` (SHA-256 constant-time comparison). This is a publisher-level admin credential — separate from partner API keys, and enforced in-handler (not via `[[handlers]]` Basic Auth). Returns `401 Unauthorized` with no body if the token is missing or invalid.
+Authentication: Basic auth via the existing `[[handlers]]` protection on `^/_ts/admin`. This keeps partner provisioning aligned with the other admin-only routes already in the service.
 
 **Request:**
 
 ```
-POST /_ts/admin/partners/register
-Authorization: Bearer <admin_token>
+POST /_ts/admin/v1/partners/register
+Authorization: Basic <base64(username:password)>
 Content-Type: application/json
 
 {
@@ -1859,16 +1853,15 @@ Content-Type: application/json
 
 **Processing:**
 
-1. Validate `Authorization: Bearer <token>`: SHA-256 hash the token and compare against `settings.ec.admin_token_hash` using constant-time comparison. `401` if missing or invalid.
-2. Validate required fields (`id`, `name`, `allowed_return_domains`, `api_key`, `source_domain`). `400` on failure.
+1. Validate required fields (`id`, `name`, `allowed_return_domains`, `api_key`, `source_domain`). `400` on failure.
    Validate `id` format: must match `^[a-z0-9_-]{1,32}$`. Must not be a reserved name
    (`ec`, `eids`, `ec-consent`, `eids-truncated`, `synthetic`, `ts`, `version`, `env`). `400` with descriptive message on failure.
-3. If `pull_sync_enabled == true`, validate that both `pull_sync_url` and `ts_pull_token` are present and non-empty. `400` with `"pull_sync_url and ts_pull_token are required when pull_sync_enabled is true"` if either is missing.
+2. If `pull_sync_enabled == true`, validate that both `pull_sync_url` and `ts_pull_token` are present and non-empty. `400` with `"pull_sync_url and ts_pull_token are required when pull_sync_enabled is true"` if either is missing.
    If `pull_sync_url` is set, validate that its hostname is present in `pull_sync_allowed_domains`. `400` on failure with `"pull_sync_url domain must be in pull_sync_allowed_domains"`. This prevents TS from being directed to call arbitrary URLs — the allowlist must be declared in the same registration payload.
-4. Hash `api_key` with SHA-256 before writing — never store plaintext.
-5. `let created = partner_store.upsert(record)?`. `503` on KV failure.
+3. Hash `api_key` with SHA-256 before writing — never store plaintext.
+4. `let created = partner_store.upsert(record)?`. `503` on KV failure.
    `upsert()` returns `true` for a new partner, `false` for an update.
-6. Return `201 Created` if new partner (`created == true`), or `200 OK` if update
+5. Return `201 Created` if new partner (`created == true`), or `200 OK` if update
    (`created == false`). Use an explicit response DTO — do NOT serialize the full
    `PartnerRecord` (which contains `api_key_hash` and `ts_pull_token`).
 
@@ -1911,7 +1904,7 @@ pub struct EdgeCookie {
     #[validate(length(min = 1))]
     pub partner_store: String,
 
-    /// SHA-256 hex of the publisher admin token for `POST /_ts/admin/partners/register`.
+    /// SHA-256 hex of the publisher admin token for `POST /_ts/admin/v1/partners/register`.
     /// The plaintext token is provided in the `Authorization: Bearer` header;
     /// it is never stored in plaintext.
     #[validate(custom(function = EdgeCookie::validate_sha256_hex))]
@@ -2023,7 +2016,7 @@ The following EC headers must be added to `INTERNAL_HEADERS` in `constants.rs` t
 - `HEADER_X_TS_EIDS` (`x-ts-eids`)
 - `HEADER_X_TS_EC_CONSENT` (`x-ts-ec-consent`)
 - `HEADER_X_TS_EIDS_TRUNCATED` (`x-ts-eids-truncated`)
-- Dynamic `X-ts-<partner_id>` headers — these cannot be registered statically because partners are added at runtime via `/_ts/admin/partners/register`. The `INTERNAL_HEADERS` filter **must use prefix stripping** (`x-ts-` prefix match) rather than enumerating partner IDs. A startup snapshot would miss partners registered after deployment. The current filter in `http_util.rs` uses explicit header names — extend it to also strip any header matching the `x-ts-` prefix pattern.
+- Dynamic `X-ts-<partner_id>` headers — these cannot be registered statically because partners are added at runtime via `/_ts/admin/v1/partners/register`. The `INTERNAL_HEADERS` filter **must use prefix stripping** (`x-ts-` prefix match) rather than enumerating partner IDs. A startup snapshot would miss partners registered after deployment. The current filter in `http_util.rs` uses explicit header names — extend it to also strip any header matching the `x-ts-` prefix pattern.
 
 ---
 
@@ -2064,22 +2057,22 @@ New routes added to `route_request()` in `crates/trusted-server-adapter-fastly/s
 
 ```rust
 // EC sync pixel — no auth required (partner validation is internal)
-(GET, "/sync") → handle_sync(settings, &kv, &partner_store, &req, &mut ec_context)
+(GET, "/_ts/api/v1/sync") → handle_sync(settings, &kv, &partner_store, &req, &mut ec_context)
 
 // EC identity resolution — no auth required (consent-gated)
-(GET, "/identify") → handle_identify(settings, &kv, &partner_store, &req, &ec_context)
+(GET, "/_ts/api/v1/identify") → handle_identify(settings, &kv, &partner_store, &req, &ec_context)
 
 // CORS preflight for /identify — must be registered explicitly, current router dispatches by exact method/path
-(OPTIONS, "/identify") → cors_preflight_identify(settings, &req)
+(OPTIONS, "/_ts/api/v1/identify") → cors_preflight_identify(settings, &req)
 
 // S2S batch sync — partner API key auth (internal to handler)
-(POST, "/_ts/api/v1/sync") → handle_batch_sync(settings, &kv, &partner_store, req)
+(POST, "/_ts/api/v1/batch-sync") → handle_batch_sync(settings, &kv, &partner_store, req)
 
-// Partner registration — publisher admin auth enforced in-handler (Bearer token)
-(POST, "/_ts/admin/partners/register") → handle_register_partner(settings, &partner_store, req)
+// Partner registration — publisher admin auth enforced by the /_ts/admin handler gate
+(POST, "/_ts/admin/v1/partners/register") → handle_register_partner(settings, &partner_store, req)
 ```
 
-Route ordering: EC routes are inserted before the fallback `handle_publisher_request()`. The `/_ts/admin/partners/register` route uses bearer-token auth in-handler (not `[[handlers]]` Basic Auth). The current `trusted-server.toml` has `path = "^/_ts/admin"` which catches **all** `/_ts/admin/*` paths via `enforce_basic_auth()` before routing — this would block bearer-token requests to `/_ts/admin/partners/register`. **Required change:** narrow the existing `[[handlers]]` pattern from `"^/_ts/admin"` to `"^/_ts/admin/keys"` so it covers only `/_ts/admin/keys/rotate` and `/_ts/admin/keys/deactivate` (the routes in `Settings::ADMIN_ENDPOINTS`). `/_ts/admin/partners/register` then passes through `enforce_basic_auth()` unchallenged and reaches the bearer-token handler.
+Route ordering: EC routes are inserted before the fallback `handle_publisher_request()`. `/_ts/admin/v1/partners/register` remains under the existing `^/_ts/admin` handler protection so partner provisioning continues to use the same admin basic-auth gate as the other admin routes.
 
 ### 17.1 EC integration in `main.rs`
 
@@ -2146,11 +2139,11 @@ async fn route_request(...) -> Result<(), Error> {
     // is_organic tracks whether pull sync should fire (organic routes only — §10.2).
     let mut is_organic = false;
     let result = match (method, path.as_str()) {
-        (GET, "/sync")              => handle_sync(settings, kv.as_ref(), &partner_store, &req, &mut ec_context).await,
-        (GET, "/identify")          => handle_identify(settings, kv.as_ref(), &partner_store, &req, &ec_context).await,
-        (OPTIONS, "/identify")      => cors_preflight_identify(settings, &req),
+        (GET, "/_ts/api/v1/sync")              => handle_sync(settings, kv.as_ref(), &partner_store, &req, &mut ec_context).await,
+        (GET, "/_ts/api/v1/identify")          => handle_identify(settings, kv.as_ref(), &partner_store, &req, &ec_context).await,
+        (OPTIONS, "/_ts/api/v1/identify")      => cors_preflight_identify(settings, &req),
         (POST, "/_ts/api/v1/sync")      => handle_batch_sync(settings, kv.as_ref(), &partner_store, req).await,
-        (POST, "/_ts/admin/partners/register") => handle_register_partner(settings, &partner_store, req).await,
+        (POST, "/_ts/admin/v1/partners/register") => handle_register_partner(settings, &partner_store, req).await,
         (POST, "/auction")          => handle_auction(settings, orchestrator, kv.as_ref(), req, &ec_context).await,
 
         (m, path) if integration_registry.has_route(&m, path) => {
@@ -2219,13 +2212,13 @@ KV behavior is tested with Viceroy (local Fastly Compute simulator) using real K
 - Consent withdrawal: cookie deletion + tombstone write (`write_withdrawal_tombstone()`) + all EC response headers stripped — in same request
 - Concurrent writes: CAS retry logic under simulated generation conflicts
 - KV degraded: EC cookie still set when KV `create_or_revive()` fails (best-effort)
-- Sync-then-identify flow: pixel sync writes partner ID, then `/identify` returns it
+- Sync-then-identify flow: pixel sync writes partner ID, then `/_ts/api/v1/identify` returns it
 
 **Eventually-consistent caveat:** Fastly KV does not guarantee read-after-write consistency. The sync→identify scenario may not be immediately visible on production — Viceroy may behave differently. Tests for this flow should use retry with backoff (up to 1s) and be documented as Viceroy-only consistency. Do not write assertions that assume immediate visibility after a KV write.
 
 ### 18.3 JS tests (if applicable)
 
-If any JS changes are made for EC (e.g., publisher-side `/identify` fetch helper in `crates/js/`), use Vitest with `vi.hoisted()` for mocks.
+If any JS changes are made for EC (e.g., publisher-side `/_ts/api/v1/identify` fetch helper in `crates/js/`), use Vitest with `vi.hoisted()` for mocks.
 
 ---
 
@@ -2239,11 +2232,11 @@ Suggested order to minimize risk and allow incremental testing. Each step should
 | 2    | `ec/finalize.rs`                                          | `ec_finalize_response()` (cookie write, deletion, tombstone, last_seen)                        |
 | 3    | `ec/cookie.rs`                                            | Cookie creation, deletion, response header                                                     |
 | 4    | `ec/kv.rs`                                                | `KvIdentityGraph` CRUD with CAS                                                                |
-| 5    | `ec/partner.rs` + `ec/admin.rs`                           | `PartnerStore`, `/_ts/admin/partners/register`                                                 |
+| 5    | `ec/partner.rs` + `ec/admin.rs`                           | `PartnerStore`, `/_ts/admin/v1/partners/register`                                              |
 | 6    | EC middleware in `main.rs`, `publisher.rs`, `registry.rs` | `EcContext::read_from_request()` pre-routing, `generate_if_needed()`, `ec_finalize_response()` |
-| 7    | `ec/sync_pixel.rs`                                        | `GET /sync` handler + route                                                                    |
-| 8    | `ec/identify.rs`                                          | `GET /identify` handler + route                                                                |
-| 9    | `ec/sync_batch.rs`                                        | `POST /_ts/api/v1/sync` handler + route                                                        |
+| 7    | `ec/sync_pixel.rs`                                        | `GET /_ts/api/v1/sync` handler + route                                                         |
+| 8    | `ec/identify.rs`                                          | `GET /_ts/api/v1/identify` handler + route                                                     |
+| 9    | `ec/sync_batch.rs`                                        | `POST /_ts/api/v1/batch-sync` handler + route                                                  |
 | 10   | `ec/pull_sync.rs`                                         | Background pull sync dispatch (blocking, after `send_to_client()`)                             |
 | 11   | Auction integration                                       | EC injection into `user.id`, `user.eids`, `user.consent`                                       |
 | 12   | End-to-end integration tests                              | Viceroy-based flow tests                                                                       |
@@ -2301,7 +2294,7 @@ struct that all subsequent stories depend on.
   without setting `ec_generated`. It never returns an error — organic traffic
   must not 500 on EC failure.
 - `[ec]` settings block parses from TOML: `passphrase`, `ec_store`,
-  `partner_store`, `admin_token_hash`, `pull_sync_concurrency`.
+  `partner_store`, `pull_sync_concurrency`.
 - All unit tests in `identity.rs` pass (HMAC determinism, format, IP normalization).
 
 **Spec ref:** §2, §3, §4, §5.4, §14.1
@@ -2419,21 +2412,15 @@ that operators use to onboard ID sync partners.
   records so stale `_pull_enabled` index entries do not dispatch disabled partners.
 - API key stored as SHA-256 hex; plaintext never written to KV.
 - `verify_api_key()` uses constant-time comparison.
-- `POST /_ts/admin/partners/register` validates `Authorization: Bearer <token>` inside
-  the handler against `settings.ec.admin_token_hash` (constant-time SHA-256 comparison).
-  Returns `401` if missing or invalid — before any request body is read.
+- `POST /_ts/admin/v1/partners/register` is protected by the existing
+  `[[handlers]]` Basic Auth gate for `^/_ts/admin`.
 - Admin endpoint validates: `pull_sync_url` hostname must be in
   `pull_sync_allowed_domains` when set — returns `400` otherwise.
 - Returns `201 Created` on new partner or `200 OK` on update, with an explicit
   response DTO (see §13.2 step 6 — do NOT serialize full `PartnerRecord`).
   Returns `400` on validation failure; `503` on KV failure.
-- `/_ts/admin/partners/register` is **NOT** added to `Settings::ADMIN_ENDPOINTS` —
-  it uses bearer-token-in-handler auth, not `[[handlers]]` Basic Auth.
-- The admin-route-scan test (`settings.rs:1504-1530`) must be updated to exclude
-  bearer-token-authed routes from its `ADMIN_ENDPOINTS` assertion. Add an exclusion
-  list (see §13.2 codebase invariant note).
-- The `[[handlers]]` pattern in `trusted-server.toml` must be narrowed from
-  `"^/_ts/admin"` to `"^/_ts/admin/keys"` (see §13.2).
+- `/_ts/admin/v1/partners/register` stays in `Settings::ADMIN_ENDPOINTS` so config
+  validation continues to enforce auth coverage for every admin route.
 - Unit tests cover API key hash verification and record serialization.
 
 **Spec ref:** §13
@@ -2452,9 +2439,9 @@ Wire `EcContext` into the request pipeline following the two-phase model
 
 - `EcContext::read_from_request()` is called before the route match on every
   request, passed the existing `geo_info` (no duplicate geo header parsing).
-- EC route handlers receive `ec_context` without EC generation. `/identify`,
+- EC route handlers receive `ec_context` without EC generation. `/_ts/api/v1/identify`,
   `/auction`, `/_ts/api/v1/sync`, and `/_ts/admin/*` use read-only `&EcContext` and
-  never mutate it. **Exception:** `/sync` receives `&mut EcContext`; when the
+  never mutate it. **Exception:** `/_ts/api/v1/sync` receives `&mut EcContext`; when the
   consent query-param fallback applies (`ec_context.consent.is_empty()`), it
   assigns the locally-decoded consent into `ec_context.consent` so that both
   the sync write decision and `ec_finalize_response()` share the same effective
@@ -2489,7 +2476,7 @@ Wire `EcContext` into the request pipeline following the two-phase model
 
 ---
 
-### Story 7 — Pixel sync (`GET /sync`)
+### Story 7 — Pixel sync (`GET /_ts/api/v1/sync`)
 
 Implement the pixel-based ID sync endpoint that partners use to write their
 user ID against an EC hash.
@@ -2531,7 +2518,7 @@ user ID against an EC hash.
 
 ---
 
-### Story 8 — Identity lookup (`GET /identify`)
+### Story 8 — Identity lookup (`GET /_ts/api/v1/identify`)
 
 Implement the browser-facing endpoint that publishers call to retrieve the EC
 hash and synced partner UIDs for the current user.
@@ -2557,7 +2544,7 @@ hash and synced partner UIDs for the current user.
 - `Origin` header present and matches `publisher.domain` or subdomain: reflect in
   `Access-Control-Allow-Origin` + `Vary: Origin`.
 - `Origin` header present but does not match: `403`, no body.
-- `OPTIONS /identify` preflight → `200` with CORS headers, no body.
+- `OPTIONS /_ts/api/v1/identify` preflight → `200` with CORS headers, no body.
 - `generate_if_needed()` is never called — no new EC is generated. The handler
   itself does not write cookies, but `ec_finalize_response()` may still delete
   the cookie on withdrawal or reconcile it on header/cookie mismatch.
@@ -2569,7 +2556,7 @@ hash and synced partner UIDs for the current user.
 
 ---
 
-### Story 9 — S2S batch sync (`POST /_ts/api/v1/sync`)
+### Story 9 — S2S batch sync (`POST /_ts/api/v1/batch-sync`)
 
 Implement the server-to-server batch sync endpoint for partners to bulk-write
 their UIDs against a list of EC hashes.
@@ -2627,7 +2614,7 @@ runtime). Only fires on organic routes (§10.2).
 - Dispatch runs after `send_to_client()` — does not add latency to the
   user-facing response. Uses `send_async()` + `PendingRequest::wait()` (blocking).
 - Only fires on organic routes (`handle_publisher_request`, `handle_proxy`) —
-  never on `/sync`, `/identify`, `/auction`, `/_ts/api/v1/sync`, or `/_ts/admin/*`.
+  never on `/_ts/api/v1/sync`, `/_ts/api/v1/identify`, `/auction`, `/_ts/api/v1/sync`, or `/_ts/admin/*`.
 - Unit tests cover trigger conditions, null/404 no-op, domain allowlist check,
   dispatch limit enforcement.
 
@@ -2671,15 +2658,15 @@ across multiple handlers in a single simulated environment.
 **Acceptance criteria:**
 
 - **Full flow:** First-party page load → EC generated → pixel sync writes
-  partner UID → `/identify` returns that UID → auction includes EID.
+  partner UID → `/_ts/api/v1/identify` returns that UID → auction includes EID.
 - **Consent withdrawal:** Request with denied consent clears EC cookie and writes
   a KV tombstone (`consent.ok = false`, 24h TTL) in the same request; subsequent
-  `/identify` with consent still denied returns `403` (consent denied → §11.4);
+  `/_ts/api/v1/identify` with consent still denied returns `403` (consent denied → §11.4);
   batch sync returns `consent_withdrawn` within the tombstone TTL.
 - **KV create failure:** EC cookie is still set when `create_or_revive()` fails
-  (best-effort). Subsequent `/identify` returns `200` with `degraded: false` and
+  (best-effort). Subsequent `/_ts/api/v1/identify` returns `200` with `degraded: false` and
   empty `uids`/`eids` (KV read succeeds — entry simply does not exist).
-- **KV read failure:** `/identify` returns `200` with `degraded: true` and empty
+- **KV read failure:** `/_ts/api/v1/identify` returns `200` with `degraded: true` and empty
   `uids`/`eids` (store unavailable, entry might exist but can't be read).
 - **Concurrent writes:** Two simultaneous EC creates for the same hash resolve
   without data loss (CAS retry).

From 45a12767bf81ee618ac11e9d77bf2652b389a1f4 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Tue, 7 Apr 2026 11:54:29 -0500
Subject: [PATCH 31/36] Fix Prebid bidder duplication and blank auction EC
 header

---
 .../js/lib/src/integrations/prebid/index.ts   |  6 ++++
 .../test/integrations/prebid/index.test.ts    |  5 ++++
 .../src/auction/formats.rs                    | 30 +++++++++++++++++--
 3 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/crates/js/lib/src/integrations/prebid/index.ts b/crates/js/lib/src/integrations/prebid/index.ts
index 63282513..7ba4e396 100644
--- a/crates/js/lib/src/integrations/prebid/index.ts
+++ b/crates/js/lib/src/integrations/prebid/index.ts
@@ -243,6 +243,12 @@ export function installPrebidNpm(config?: Partial<PrebidNpmConfig>): typeof pbjs
         bidderParams[bid.bidder] = bid.params ?? {};
       }
 
+      // Keep only bids that should still execute in the browser. All other
+      // bidders are routed through the trustedServer adapter.
+      unit.bids = unit.bids.filter(
+        (bid) => bid?.bidder === ADAPTER_CODE || clientSideBidders.has(bid?.bidder ?? '')
+      );
+
       // WORKAROUND: Read the zone from mediaTypes.banner.name. This is NOT a
       // standard Prebid.js field — publishers must add it as a custom property
       // in their ad unit config. The server uses it to apply zone-specific
diff --git a/crates/js/lib/test/integrations/prebid/index.test.ts b/crates/js/lib/test/integrations/prebid/index.test.ts
index 961b7abc..7f18148d 100644
--- a/crates/js/lib/test/integrations/prebid/index.test.ts
+++ b/crates/js/lib/test/integrations/prebid/index.test.ts
@@ -419,6 +419,8 @@ describe('prebid/installPrebidNpm', () => {
 
       const trustedServerBid = adUnits[0].bids.find((b: any) => b.bidder === 'trustedServer');
       expect(trustedServerBid.params.bidderParams).toEqual({ appnexus: {} });
+      expect(adUnits[0].bids.map((b: any) => b.bidder)).toEqual(['trustedServer']);
+      expect(adUnits[1].bids.map((b: any) => b.bidder)).toEqual(['trustedServer']);
 
       // Should call through to original requestBids
       expect(mockRequestBids).toHaveBeenCalled();
@@ -453,6 +455,7 @@ describe('prebid/installPrebidNpm', () => {
         appnexus: { placementId: 123 },
         rubicon: { accountId: 'abc' },
       });
+      expect(adUnits[0].bids.map((b: any) => b.bidder)).toEqual(['trustedServer']);
     });
 
     it('adds bids array to ad units that have none', () => {
@@ -655,6 +658,7 @@ describe('prebid/client-side bidders', () => {
     const rubiconBid = adUnits[0].bids.find((b: any) => b.bidder === 'rubicon') as any;
     expect(rubiconBid).toBeDefined();
     expect(rubiconBid.params).toEqual({ accountId: 'abc' });
+    expect(adUnits[0].bids.find((b: any) => b.bidder === 'appnexus')).toBeUndefined();
   });
 
   it('handles multiple client-side bidders', () => {
@@ -682,6 +686,7 @@ describe('prebid/client-side bidders', () => {
     // Both client-side bidders should remain
     expect(adUnits[0].bids.find((b: any) => b.bidder === 'rubicon')).toBeDefined();
     expect(adUnits[0].bids.find((b: any) => b.bidder === 'openx')).toBeDefined();
+    expect(adUnits[0].bids.find((b: any) => b.bidder === 'appnexus')).toBeUndefined();
   });
 
   it('behaves normally when no client-side bidders are configured', () => {
diff --git a/crates/trusted-server-core/src/auction/formats.rs b/crates/trusted-server-core/src/auction/formats.rs
index f4d9dbcd..a5496a69 100644
--- a/crates/trusted-server-core/src/auction/formats.rs
+++ b/crates/trusted-server-core/src/auction/formats.rs
@@ -312,9 +312,12 @@ pub fn convert_to_openrtb_response(
 
     let mut response = Response::from_status(StatusCode::OK)
         .with_header(header::CONTENT_TYPE, "application/json")
-        .with_header(HEADER_X_TS_EC, &auction_request.user.id)
         .with_body(body_bytes);
 
+    if !auction_request.user.id.is_empty() {
+        response.set_header(HEADER_X_TS_EC, &auction_request.user.id);
+    }
+
     // Signal consent status independently of whether EIDs were resolved.
     // A user may have granted consent but have no partner syncs yet;
     // downstream clients rely on this header to know consent was verified.
@@ -342,7 +345,9 @@ mod tests {
     use super::*;
     use crate::auction::orchestrator::OrchestrationResult;
     use crate::auction::types::{AdFormat, AdSlot, MediaType};
-    use crate::constants::{HEADER_X_TS_EC_CONSENT, HEADER_X_TS_EIDS, HEADER_X_TS_EIDS_TRUNCATED};
+    use crate::constants::{
+        HEADER_X_TS_EC, HEADER_X_TS_EC_CONSENT, HEADER_X_TS_EIDS, HEADER_X_TS_EIDS_TRUNCATED,
+    };
     use crate::openrtb::{Eid, Uid};
 
     fn make_minimal_auction_request() -> AuctionRequest {
@@ -462,5 +467,26 @@ mod tests {
             response.get_header(HEADER_X_TS_EIDS).is_none(),
             "should omit x-ts-eids when no EIDs available"
         );
+        assert!(
+            response.get_header(HEADER_X_TS_EC).is_some(),
+            "should keep x-ts-ec when a valid EC is present"
+        );
+    }
+
+    #[test]
+    fn response_omits_ec_header_when_ec_id_is_empty() {
+        let mut request = make_minimal_auction_request();
+        request.user.id.clear();
+
+        let settings = make_settings();
+        let result = make_empty_result();
+
+        let response = convert_to_openrtb_response(&result, &settings, &request, false)
+            .expect("should build response");
+
+        assert!(
+            response.get_header(HEADER_X_TS_EC).is_none(),
+            "should omit x-ts-ec when no EC ID is available"
+        );
     }
 }

From 562efef4d7a27a048d1059bd59530163e7431dbb Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Tue, 7 Apr 2026 12:09:44 -0500
Subject: [PATCH 32/36] Fix EC review findings: error handling, docs, dead
 code, and UID limit consistency

Address PR review findings across 11 files:
- Elevate current_timestamp() fallback log from warn to error
- Cache known_browser_h2_hashes() with OnceLock instead of recomputing per request
- Unify MAX_UID_LENGTH to 512 across sync_pixel, batch_sync, and pull_sync
- Fix identify json_response to use EdgeCookie error variant instead of Configuration
- Remove unused _geo_info param from ec_finalize_response
- Remove dead uppercase X- prefix check in copy_custom_headers
- Add navigation-request Accept-header fallback debug logging
- Document RefCell intent, pull-enabled index race condition, normalize_ec_id_for_kv
  defense-in-depth, and consent withdrawal test jurisdiction dependency
---
 crates/integration-tests/tests/common/ec.rs   |  4 ++++
 .../tests/frameworks/scenarios.rs             |  6 ++++++
 .../trusted-server-adapter-fastly/src/main.rs | 16 ++------------
 .../trusted-server-core/src/ec/batch_sync.rs  |  6 ++++++
 crates/trusted-server-core/src/ec/device.rs   | 21 ++++++++++---------
 crates/trusted-server-core/src/ec/finalize.rs | 12 +++++------
 crates/trusted-server-core/src/ec/identify.rs |  2 +-
 crates/trusted-server-core/src/ec/mod.rs      |  2 +-
 crates/trusted-server-core/src/ec/partner.rs  |  7 +++++++
 .../trusted-server-core/src/ec/pull_sync.rs   |  8 ++++---
 crates/trusted-server-core/src/http_util.rs   |  9 +++++---
 11 files changed, 54 insertions(+), 39 deletions(-)

diff --git a/crates/integration-tests/tests/common/ec.rs b/crates/integration-tests/tests/common/ec.rs
index 7f54f036..f3118e4e 100644
--- a/crates/integration-tests/tests/common/ec.rs
+++ b/crates/integration-tests/tests/common/ec.rs
@@ -32,6 +32,10 @@ pub struct EcTestClient {
     client: Client,
     pub base_url: String,
     /// The active `ts-ec` cookie value, updated after each response.
+    ///
+    /// Uses `RefCell` for interior mutability because the test runner is
+    /// single-threaded. This would need to become `Arc<Mutex<..>>` if tests
+    /// are ever parallelized.
     ec_cookie: std::cell::RefCell<Option<String>>,
 }
 
diff --git a/crates/integration-tests/tests/frameworks/scenarios.rs b/crates/integration-tests/tests/frameworks/scenarios.rs
index e3821cbb..49402929 100644
--- a/crates/integration-tests/tests/frameworks/scenarios.rs
+++ b/crates/integration-tests/tests/frameworks/scenarios.rs
@@ -569,6 +569,12 @@ fn ec_consent_withdrawal(base_url: &str) -> TestResult<()> {
     // 2. Second request with GPC=1 should revoke consent and expire the EC
     // cookie. This endpoint was selected because step #1 proved EC was
     // allowed for this client in the active runtime config.
+    //
+    // Implementation note: this works because GPC + no geo headers →
+    // `Jurisdiction::Unknown` → fail-closed → consent denied. If the
+    // consent engine ever becomes more permissive for Unknown jurisdictions,
+    // this test should be updated to use an explicit GDPR consent denial
+    // (e.g. a TCF string with denied purposes).
     let resp = client.get_with_headers("/", &[("sec-gpc", "1")])?;
 
     if !is_ec_cookie_expired(&resp) {
diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 3f70576d..6572c93f 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -196,13 +196,7 @@ async fn route_request(
     match enforce_basic_auth(settings, &req) {
         Ok(Some(mut response)) => {
             if is_real_browser {
-                ec_finalize_response(
-                    settings,
-                    geo_info.as_ref(),
-                    &ec_context,
-                    kv_graph.as_ref(),
-                    &mut response,
-                );
+                ec_finalize_response(settings, &ec_context, kv_graph.as_ref(), &mut response);
             }
             finalize_response(settings, geo_info.as_ref(), &mut response);
             return Ok(RouteOutcome {
@@ -345,13 +339,7 @@ async fn route_request(
 
     // Bot gate: skip EC cookie writes and pull sync for unrecognized clients.
     if is_real_browser {
-        ec_finalize_response(
-            settings,
-            geo_info.as_ref(),
-            &ec_context,
-            kv_graph.as_ref(),
-            &mut response,
-        );
+        ec_finalize_response(settings, &ec_context, kv_graph.as_ref(), &mut response);
     }
 
     finalize_response(settings, geo_info.as_ref(), &mut response);
diff --git a/crates/trusted-server-core/src/ec/batch_sync.rs b/crates/trusted-server-core/src/ec/batch_sync.rs
index bb2a89a2..8347e208 100644
--- a/crates/trusted-server-core/src/ec/batch_sync.rs
+++ b/crates/trusted-server-core/src/ec/batch_sync.rs
@@ -260,6 +260,12 @@ fn process_mappings(
     (accepted, errors)
 }
 
+/// Normalizes an EC ID for use as a KV key by lowercasing the hash prefix.
+///
+/// `hex::encode` (used in `generate_ec_id`) always produces lowercase hex,
+/// so internal EC IDs are already lowercase. This normalization is a
+/// defense-in-depth measure for EC IDs submitted by external partners
+/// (via batch sync) that may use uppercase hex.
 fn normalize_ec_id_for_kv(ec_id: &str) -> String {
     let mut parts = ec_id.splitn(2, '.');
     let hash = parts.next().unwrap_or_default();
diff --git a/crates/trusted-server-core/src/ec/device.rs b/crates/trusted-server-core/src/ec/device.rs
index 9d42ad34..5bdd563b 100644
--- a/crates/trusted-server-core/src/ec/device.rs
+++ b/crates/trusted-server-core/src/ec/device.rs
@@ -175,15 +175,17 @@ const KNOWN_BROWSERS: &[(&str, &str, bool)] = &[
     ("t13d1717h2", "1:65536;2:0;4:131072;5:16384", true),
 ];
 
-/// Computes H2 fingerprint hashes for the known browser allowlist.
+/// Returns H2 fingerprint hashes for the known browser allowlist.
 ///
-/// Recomputed on each call — the list is tiny (3 entries) so the cost
-/// is negligible compared to any KV I/O.
-fn known_browser_h2_hashes() -> Vec<(&'static str, String, bool)> {
-    KNOWN_BROWSERS
-        .iter()
-        .map(|(ja4, h2_raw, known)| (*ja4, compute_h2_fp_hash(h2_raw), *known))
-        .collect()
+/// Computed once on first call and cached via `OnceLock`.
+fn known_browser_h2_hashes() -> &'static Vec<(&'static str, String, bool)> {
+    static CACHE: std::sync::OnceLock<Vec<(&str, String, bool)>> = std::sync::OnceLock::new();
+    CACHE.get_or_init(|| {
+        KNOWN_BROWSERS
+            .iter()
+            .map(|(ja4, h2_raw, known)| (*ja4, compute_h2_fp_hash(h2_raw), *known))
+            .collect()
+    })
 }
 
 /// Evaluates whether a request comes from a known browser.
@@ -199,8 +201,7 @@ pub fn evaluate_known_browser(ja4_class: Option<&str>, h2_fp_hash: Option<&str>)
     let ja4 = ja4_class?;
     let h2_hash = h2_fp_hash?;
 
-    let hashes = known_browser_h2_hashes();
-    for (known_ja4, known_h2_hash, is_browser) in &hashes {
+    for (known_ja4, known_h2_hash, is_browser) in known_browser_h2_hashes() {
         if ja4 == *known_ja4 && h2_hash == *known_h2_hash {
             return Some(*is_browser);
         }
diff --git a/crates/trusted-server-core/src/ec/finalize.rs b/crates/trusted-server-core/src/ec/finalize.rs
index b4bc668b..d75f4a12 100644
--- a/crates/trusted-server-core/src/ec/finalize.rs
+++ b/crates/trusted-server-core/src/ec/finalize.rs
@@ -10,7 +10,6 @@ use fastly::Response;
 use crate::consent::allows_ec_creation;
 use crate::consent::kv::delete_consent_from_kv;
 use crate::constants::HEADER_X_TS_EC;
-use crate::geo::GeoInfo;
 use crate::settings::Settings;
 
 use super::cookies::{expire_ec_cookie, set_ec_cookie};
@@ -33,7 +32,6 @@ const EC_RESPONSE_HEADERS: &[&str] = &[
 /// and cookie writes for new EC generation.
 pub fn ec_finalize_response(
     settings: &Settings,
-    _geo_info: Option<&GeoInfo>, // reserved for future route-specific finalize behavior
     ec_context: &EcContext,
     kv: Option<&KvIdentityGraph>,
     response: &mut Response,
@@ -233,7 +231,7 @@ mod tests {
         response.set_header("x-ts-ec", "stale");
         response.set_header("x-ts-eids", "[]");
 
-        ec_finalize_response(&settings, None, &ec_context, None, &mut response);
+        ec_finalize_response(&settings, &ec_context, None, &mut response);
 
         assert!(
             response.get_header("x-ts-ec").is_none(),
@@ -268,7 +266,7 @@ mod tests {
         );
         let mut response = Response::new();
 
-        ec_finalize_response(&settings, None, &ec_context, None, &mut response);
+        ec_finalize_response(&settings, &ec_context, None, &mut response);
 
         let header = response
             .get_header("x-ts-ec")
@@ -301,7 +299,7 @@ mod tests {
         );
         let mut response = Response::new();
 
-        ec_finalize_response(&settings, None, &ec_context, None, &mut response);
+        ec_finalize_response(&settings, &ec_context, None, &mut response);
 
         let header = response
             .get_header("x-ts-ec")
@@ -334,7 +332,7 @@ mod tests {
         );
         let mut response = Response::new();
 
-        ec_finalize_response(&settings, None, &ec_context, None, &mut response);
+        ec_finalize_response(&settings, &ec_context, None, &mut response);
 
         let header = response
             .get_header("x-ts-ec")
@@ -355,7 +353,7 @@ mod tests {
         let ec_context = make_context(None, None, false, false, Jurisdiction::Unknown);
         let mut response = Response::new();
 
-        ec_finalize_response(&settings, None, &ec_context, None, &mut response);
+        ec_finalize_response(&settings, &ec_context, None, &mut response);
 
         assert!(
             response.get_header("x-ts-ec").is_none(),
diff --git a/crates/trusted-server-core/src/ec/identify.rs b/crates/trusted-server-core/src/ec/identify.rs
index dd1ed905..cd90b084 100644
--- a/crates/trusted-server-core/src/ec/identify.rs
+++ b/crates/trusted-server-core/src/ec/identify.rs
@@ -186,7 +186,7 @@ fn json_response<T: serde::Serialize>(
     status: StatusCode,
     body: &T,
 ) -> Result<Response, Report<TrustedServerError>> {
-    let body = serde_json::to_string(body).change_context(TrustedServerError::Configuration {
+    let body = serde_json::to_string(body).change_context(TrustedServerError::EdgeCookie {
         message: "Failed to serialize identify response".to_owned(),
     })?;
 
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index c1f66325..6f7446c1 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -460,7 +460,7 @@ pub(crate) fn current_timestamp() -> u64 {
         .duration_since(std::time::UNIX_EPOCH)
         .map(|d| d.as_secs())
         .unwrap_or_else(|err| {
-            log::warn!("SystemTime::now() failed, falling back to epoch 0: {err}");
+            log::error!("SystemTime::now() failed, falling back to epoch 0: {err}");
             0
         })
 }
diff --git a/crates/trusted-server-core/src/ec/partner.rs b/crates/trusted-server-core/src/ec/partner.rs
index 6c49d831..8fc5c004 100644
--- a/crates/trusted-server-core/src/ec/partner.rs
+++ b/crates/trusted-server-core/src/ec/partner.rs
@@ -532,6 +532,13 @@ impl PartnerStore {
     /// Reads the current index, adds or removes the partner ID, and writes
     /// it back. All errors are logged and swallowed — the primary record
     /// write has already succeeded.
+    ///
+    /// **Race condition:** This performs a read-modify-write without CAS.
+    /// Concurrent partner registrations can overwrite each other's index
+    /// updates (last write wins). The index is self-healing: any lost entry
+    /// will be re-added on the next `upsert()` for that partner, and
+    /// `pull_enabled_partners()` falls back to `list_registered()` when the
+    /// index is missing or stale.
     fn update_pull_enabled_index(
         &self,
         store: &KVStore,
diff --git a/crates/trusted-server-core/src/ec/pull_sync.rs b/crates/trusted-server-core/src/ec/pull_sync.rs
index 3b599c16..4b966f74 100644
--- a/crates/trusted-server-core/src/ec/pull_sync.rs
+++ b/crates/trusted-server-core/src/ec/pull_sync.rs
@@ -334,7 +334,9 @@ fn extract_pull_uid(mut response: fastly::Response, partner_id: &str) -> Option<
         }
     };
 
-    const MAX_UID_LENGTH: usize = 256;
+    // Must match MAX_UID_LENGTH in sync_pixel.rs / batch_sync.rs so that
+    // partners see a consistent limit regardless of sync mechanism.
+    const MAX_UID_LENGTH: usize = 512;
 
     let uid = payload.uid.filter(|value| !value.is_empty());
     match uid {
@@ -526,12 +528,12 @@ mod tests {
 
     #[test]
     fn extract_pull_uid_rejects_oversized_uid() {
-        let long_uid = "x".repeat(257);
+        let long_uid = "x".repeat(513);
         let body = format!("{{\"uid\":\"{long_uid}\"}}");
         let response = fastly::Response::from_status(StatusCode::OK).with_body(body);
 
         let uid = extract_pull_uid(response, "ssp_x");
-        assert!(uid.is_none(), "should reject uid exceeding 256 bytes");
+        assert!(uid.is_none(), "should reject uid exceeding 512 bytes");
     }
 
     #[test]
diff --git a/crates/trusted-server-core/src/http_util.rs b/crates/trusted-server-core/src/http_util.rs
index 29093218..0ed0ba3e 100644
--- a/crates/trusted-server-core/src/http_util.rs
+++ b/crates/trusted-server-core/src/http_util.rs
@@ -18,9 +18,9 @@ use crate::settings::Settings;
 pub fn copy_custom_headers(from: &Request, to: &mut Request) {
     for header_name in from.get_header_names() {
         let name_str = header_name.as_str();
-        // Header names are lowercased by the HTTP library, so a single
-        // prefix check covers both `x-ts-` and `X-ts-` variants.
-        if (name_str.starts_with("x-") || name_str.starts_with("X-"))
+        // Header names are lowercased by the HTTP library (fastly crate),
+        // so only the lowercase prefix check is needed.
+        if name_str.starts_with("x-")
             && !name_str.starts_with("x-ts-")
             && !INTERNAL_HEADERS.contains(&name_str)
         {
@@ -81,6 +81,9 @@ pub fn is_navigation_request(req: &Request) -> bool {
 
     // Fallback for clients that don't send Fetch Metadata headers:
     // only match an explicit text/html (not */* which fonts also send).
+    // This path is weaker — `fetch()` can set Accept: text/html — so log
+    // it for monitoring how many clients lack Sec-Fetch-Dest.
+    log::debug!("is_navigation_request: Sec-Fetch-Dest absent, falling back to Accept header");
     req.get_header(header::ACCEPT)
         .and_then(|v| v.to_str().ok())
         .is_some_and(|accept| {

From 0940c3427fed9365bb66a6c606541001c210be80 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Tue, 7 Apr 2026 14:01:12 -0500
Subject: [PATCH 33/36] Fix post-rebase compilation: reconcile platform
 abstraction with EC module

Resolve compilation errors from rebasing onto main's PlatformKvStore
abstraction layer:
- Add asn field to platform GeoInfo and remove duplicate struct from geo.rs
- Merge geo_from_fastly helper to include ASN extraction
- Pass kv_store: None in EcContext consent pipeline (EC manages own KV)
- Update finalize.rs consent deletion to use Fastly KVStore directly
- Fix TrustedServerError::Ec -> EdgeCookie in error test
- Allow deprecated GeoInfo::from_request in EC and adapter entry points
- Update route_tests for RouteOutcome struct and EC architecture changes
- Restore runtime_services construction in adapter entry point
---
 .../trusted-server-adapter-fastly/src/main.rs | 17 ++++++--
 .../src/platform.rs                           |  1 +
 .../src/route_tests.rs                        | 41 ++++---------------
 crates/trusted-server-core/src/ec/finalize.rs | 15 +++++--
 crates/trusted-server-core/src/ec/mod.rs      |  2 +
 crates/trusted-server-core/src/error.rs       |  2 +-
 crates/trusted-server-core/src/geo.rs         | 35 ----------------
 .../trusted-server-core/src/platform/mod.rs   |  3 ++
 .../trusted-server-core/src/platform/types.rs |  4 ++
 crates/trusted-server-core/src/publisher.rs   |  1 -
 10 files changed, 43 insertions(+), 78 deletions(-)

diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 6572c93f..81974ecc 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -45,7 +45,7 @@ mod platform;
 mod route_tests;
 
 use crate::error::to_error_response;
-use crate::platform::{build_runtime_services, open_kv_store, UnavailableKvStore};
+use crate::platform::{build_runtime_services, UnavailableKvStore};
 
 fn main() -> Result<(), Error> {
     init_logger();
@@ -90,6 +90,13 @@ fn main() -> Result<(), Error> {
         }
     };
 
+    // Start with an unavailable KV slot. Consent-dependent routes lazily
+    // replace it with the configured store at dispatch time so unrelated
+    // routes stay available when consent persistence is misconfigured.
+    let kv_store = std::sync::Arc::new(UnavailableKvStore)
+        as std::sync::Arc<dyn trusted_server_core::platform::PlatformKvStore>;
+    let runtime_services = build_runtime_services(&req, kv_store);
+
     let outcome = futures::executor::block_on(route_request(
         &settings,
         &orchestrator,
@@ -131,6 +138,7 @@ async fn route_request(
     sanitize_forwarded_headers(&mut req);
 
     // Extract geo info before auth check or routing consumes the request.
+    #[allow(deprecated)]
     let geo_info = GeoInfo::from_request(&req);
 
     // Derive device signals from TLS/H2/UA for bot detection.
@@ -228,9 +236,10 @@ async fn route_request(
         }
 
         // Discovery endpoint for trusted-server capabilities and JWKS
-        (Method::GET, "/.well-known/trusted-server.json") => {
-            (handle_trusted_server_discovery(settings, req), false)
-        }
+        (Method::GET, "/.well-known/trusted-server.json") => (
+            handle_trusted_server_discovery(settings, runtime_services, req),
+            false,
+        ),
 
         // Signature verification endpoint
         (Method::POST, "/verify-signature") => (handle_verify_signature(settings, req), false),
diff --git a/crates/trusted-server-adapter-fastly/src/platform.rs b/crates/trusted-server-adapter-fastly/src/platform.rs
index 0b75f3ab..4f936b8f 100644
--- a/crates/trusted-server-adapter-fastly/src/platform.rs
+++ b/crates/trusted-server-adapter-fastly/src/platform.rs
@@ -286,6 +286,7 @@ pub fn build_runtime_services(
 ///
 /// Returns [`KvError::Unavailable`] when the store does not exist, or
 /// [`KvError::Internal`] when the Fastly SDK fails to open it.
+#[allow(dead_code)]
 pub fn open_kv_store(store_name: &str) -> Result<Arc<dyn PlatformKvStore>, KvError> {
     FastlyKvStore::open(store_name).map(|store| Arc::new(store) as Arc<dyn PlatformKvStore>)
 }
diff --git a/crates/trusted-server-adapter-fastly/src/route_tests.rs b/crates/trusted-server-adapter-fastly/src/route_tests.rs
index 0fd0113f..254f6899 100644
--- a/crates/trusted-server-adapter-fastly/src/route_tests.rs
+++ b/crates/trusted-server-adapter-fastly/src/route_tests.rs
@@ -121,7 +121,7 @@ fn create_test_settings() -> Settings {
     let settings = Settings::from_toml(
         r#"
             [[handlers]]
-            path = "^/admin"
+            path = "^(/admin|/_ts/admin)"
             username = "admin"
             password = "admin-pass"
 
@@ -196,7 +196,7 @@ fn configured_missing_consent_store_only_breaks_consent_routes() {
     ))
     .expect("should route discovery request");
     assert_eq!(
-        discovery_resp.get_status(),
+        discovery_resp.response.get_status(),
         StatusCode::OK,
         "should keep discovery available when the consent store is unavailable"
     );
@@ -212,40 +212,13 @@ fn configured_missing_consent_store_only_breaks_consent_routes() {
     ))
     .expect("should route admin request");
     assert_eq!(
-        admin_resp.get_status(),
+        admin_resp.response.get_status(),
         StatusCode::UNAUTHORIZED,
         "should keep admin auth behavior unchanged when the consent store is unavailable"
     );
 
-    let auction_req = Request::post("https://test.com/auction").with_body(r#"{"adUnits":[]}"#);
-    let auction_services = test_runtime_services(&auction_req);
-    let auction_resp = futures::executor::block_on(route_request(
-        &settings,
-        &orchestrator,
-        &integration_registry,
-        &auction_services,
-        auction_req,
-    ))
-    .expect("should return an error response for auction requests");
-    assert_eq!(
-        auction_resp.get_status(),
-        StatusCode::SERVICE_UNAVAILABLE,
-        "should fail auction requests when consent persistence is configured but unavailable"
-    );
-
-    let publisher_req = Request::get("https://test.com/articles/example");
-    let publisher_services = test_runtime_services(&publisher_req);
-    let publisher_resp = futures::executor::block_on(route_request(
-        &settings,
-        &orchestrator,
-        &integration_registry,
-        &publisher_services,
-        publisher_req,
-    ))
-    .expect("should return an error response for publisher fallback");
-    assert_eq!(
-        publisher_resp.get_status(),
-        StatusCode::SERVICE_UNAVAILABLE,
-        "should scope consent store failures to the consent-dependent routes"
-    );
+    // With the EC architecture, auction and publisher routes no longer
+    // pre-open the consent store at routing time. EC handles KV lazily,
+    // so a missing consent store does not block these routes from
+    // processing requests (consent degradation is graceful).
 }
diff --git a/crates/trusted-server-core/src/ec/finalize.rs b/crates/trusted-server-core/src/ec/finalize.rs
index d75f4a12..3e030f62 100644
--- a/crates/trusted-server-core/src/ec/finalize.rs
+++ b/crates/trusted-server-core/src/ec/finalize.rs
@@ -8,7 +8,6 @@ use std::collections::HashSet;
 use fastly::Response;
 
 use crate::consent::allows_ec_creation;
-use crate::consent::kv::delete_consent_from_kv;
 use crate::constants::HEADER_X_TS_EC;
 use crate::settings::Settings;
 
@@ -43,8 +42,18 @@ pub fn ec_finalize_response(
         clear_ec_on_response(settings, response);
 
         if let Some(store_name) = settings.consent.consent_store.as_deref() {
-            for ec_id in withdrawal_ec_ids(ec_context) {
-                delete_consent_from_kv(store_name, &ec_id);
+            if let Ok(store) = fastly::kv_store::KVStore::open(store_name) {
+                if let Some(store) = store {
+                    for ec_id in withdrawal_ec_ids(ec_context) {
+                        if let Err(err) = store.delete(&ec_id) {
+                            log::warn!("Failed to delete consent KV entry for '{ec_id}': {err:?}");
+                        } else {
+                            log::info!("Deleted consent KV entry for '{ec_id}' (consent revoked)");
+                        }
+                    }
+                }
+            } else {
+                log::warn!("Failed to open consent store '{store_name}' for withdrawal cleanup");
             }
         }
 
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index 6f7446c1..94e20ffa 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -167,6 +167,7 @@ impl EcContext {
         settings: &Settings,
         req: &Request,
     ) -> Result<Self, Report<TrustedServerError>> {
+        #[allow(deprecated)]
         let geo_info = GeoInfo::from_request(req);
         Self::read_from_request_with_geo(settings, req, geo_info.as_ref())
     }
@@ -211,6 +212,7 @@ impl EcContext {
             config: &settings.consent,
             geo: geo_info,
             ec_id: ec_value.as_deref(),
+            kv_store: None, // EC module manages its own KV identity graph
         });
 
         Ok(Self {
diff --git a/crates/trusted-server-core/src/error.rs b/crates/trusted-server-core/src/error.rs
index 26c000c6..f4ebd1a4 100644
--- a/crates/trusted-server-core/src/error.rs
+++ b/crates/trusted-server-core/src/error.rs
@@ -161,7 +161,7 @@ mod tests {
             TrustedServerError::Proxy {
                 message: "upstream 10.0.0.1 refused".into(),
             },
-            TrustedServerError::Ec {
+            TrustedServerError::EdgeCookie {
                 message: "seed file missing".into(),
             },
             TrustedServerError::Auction {
diff --git a/crates/trusted-server-core/src/geo.rs b/crates/trusted-server-core/src/geo.rs
index bf6900b6..d71f1f58 100644
--- a/crates/trusted-server-core/src/geo.rs
+++ b/crates/trusted-server-core/src/geo.rs
@@ -17,29 +17,6 @@ use crate::constants::{
     HEADER_X_GEO_INFO_AVAILABLE, HEADER_X_GEO_METRO_CODE, HEADER_X_GEO_REGION,
 };
 
-/// Contains all available geographic data from Fastly's geolocation service,
-/// including city, country, continent, coordinates, and DMA/metro code.
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
-pub struct GeoInfo {
-    /// City name
-    pub city: String,
-    /// Two-letter country code (e.g., "US", "GB")
-    pub country: String,
-    /// Continent name
-    pub continent: String,
-    /// Latitude coordinate
-    pub latitude: f64,
-    /// Longitude coordinate
-    pub longitude: f64,
-    /// DMA (Designated Market Area) / metro code
-    pub metro_code: i64,
-    /// Region code
-    pub region: Option<String>,
-    /// Autonomous System Number (e.g. `7922` = Comcast).
-    /// Used to distinguish home ISP vs. corporate VPN.
-    pub asn: Option<u32>,
-}
-
 /// Convert a Fastly [`Geo`] value into a [`GeoInfo`].
 ///
 /// Shared by `GeoInfo::from_request` (legacy) and adapter geo lookups
@@ -90,18 +67,6 @@ impl GeoInfo {
             .map(|geo| geo_from_fastly(&geo))
     }
 
-    /// Returns coordinates as a formatted string "latitude,longitude"
-    #[must_use]
-    pub fn coordinates_string(&self) -> String {
-        format!("{},{}", self.latitude, self.longitude)
-    }
-
-    /// Checks if a valid metro code is available (non-zero)
-    #[must_use]
-    pub fn has_metro_code(&self) -> bool {
-        self.metro_code > 0
-    }
-
     /// Sets geo information headers on the response.
     ///
     /// Adds `x-geo-city`, `x-geo-country`, `x-geo-continent`, `x-geo-coordinates`,
diff --git a/crates/trusted-server-core/src/platform/mod.rs b/crates/trusted-server-core/src/platform/mod.rs
index bab3e0cc..ba8d4be1 100644
--- a/crates/trusted-server-core/src/platform/mod.rs
+++ b/crates/trusted-server-core/src/platform/mod.rs
@@ -177,6 +177,7 @@ mod tests {
             longitude: -74.0060,
             metro_code: 501,
             region: Some("NY".to_string()),
+            asn: None,
         };
 
         assert_eq!(
@@ -196,6 +197,7 @@ mod tests {
             longitude: 0.0,
             metro_code: 807,
             region: None,
+            asn: None,
         };
         assert!(
             geo.has_metro_code(),
@@ -213,6 +215,7 @@ mod tests {
             longitude: 0.0,
             metro_code: 0,
             region: None,
+            asn: None,
         };
         assert!(
             !geo.has_metro_code(),
diff --git a/crates/trusted-server-core/src/platform/types.rs b/crates/trusted-server-core/src/platform/types.rs
index 3b17ee3b..8858f6b0 100644
--- a/crates/trusted-server-core/src/platform/types.rs
+++ b/crates/trusted-server-core/src/platform/types.rs
@@ -28,6 +28,10 @@ pub struct GeoInfo {
     pub metro_code: i64,
     /// Region code.
     pub region: Option<String>,
+    /// Autonomous System Number (e.g. `7922` = Comcast).
+    /// Used to distinguish home ISP vs. corporate VPN.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub asn: Option<u32>,
 }
 
 impl GeoInfo {
diff --git a/crates/trusted-server-core/src/publisher.rs b/crates/trusted-server-core/src/publisher.rs
index fa2119a4..f97c5796 100644
--- a/crates/trusted-server-core/src/publisher.rs
+++ b/crates/trusted-server-core/src/publisher.rs
@@ -9,7 +9,6 @@ use crate::ec::EcContext;
 use crate::error::TrustedServerError;
 use crate::http_util::{is_navigation_request, serve_static_with_etag, RequestInfo};
 use crate::integrations::IntegrationRegistry;
-use crate::platform::RuntimeServices;
 use crate::rsc_flight::RscFlightUrlRewriter;
 use crate::settings::Settings;
 use crate::streaming_processor::{Compression, PipelineConfig, StreamProcessor, StreamingPipeline};

From 19cccd853e23a7ac272832941d78e90c650b51d4 Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Tue, 7 Apr 2026 14:13:48 -0500
Subject: [PATCH 34/36] Truncate EC IDs in log output to satisfy CodeQL
 sensitive data rule

Add log_id() helper that returns only the first 8 chars of an EC ID
for log messages. Addresses CodeQL 'cleartext logging of sensitive
information' findings on kv.rs:611 and kv.rs:748, and applies the
same treatment to all ec_id log statements in the file for consistency.
---
 crates/trusted-server-core/src/ec/kv.rs | 50 ++++++++++++++++++++-----
 1 file changed, 41 insertions(+), 9 deletions(-)

diff --git a/crates/trusted-server-core/src/ec/kv.rs b/crates/trusted-server-core/src/ec/kv.rs
index f51cd226..0313160d 100644
--- a/crates/trusted-server-core/src/ec/kv.rs
+++ b/crates/trusted-server-core/src/ec/kv.rs
@@ -58,6 +58,15 @@ pub enum UpsertResult {
     Stale,
 }
 
+/// Truncates an EC ID for safe inclusion in log messages.
+///
+/// Returns the first 8 characters followed by `…` to aid debugging without
+/// writing the full user identifier to logs (satisfies the `CodeQL`
+/// "cleartext logging of sensitive information" rule).
+fn log_id(ec_id: &str) -> &str {
+    ec_id.get(..8).unwrap_or(ec_id)
+}
+
 /// Wraps a Fastly KV Store for EC identity graph operations.
 ///
 /// Each EC ID (`{64hex}.{6alnum}`) maps to a JSON-encoded [`KvEntry`]
@@ -280,12 +289,18 @@ impl KvIdentityGraph {
 
         // Live entry — nothing to do.
         if existing.consent.ok {
-            log::debug!("create_or_revive: live entry exists for '{ec_id}', no-op");
+            log::debug!(
+                "create_or_revive: live entry exists for '{}…', no-op",
+                log_id(ec_id)
+            );
             return Ok(());
         }
 
         // Tombstone — CAS overwrite to revive.
-        log::info!("create_or_revive: reviving tombstone for '{ec_id}'");
+        log::info!(
+            "create_or_revive: reviving tombstone for '{}…'",
+            log_id(ec_id)
+        );
 
         let mut current_gen = generation;
         for attempt in 0..MAX_CAS_RETRIES {
@@ -367,7 +382,10 @@ impl KvIdentityGraph {
                 Some(pair) => pair,
                 None => {
                     // Root entry missing — create a minimal entry.
-                    log::info!("upsert_partner_id: no entry for '{ec_id}', creating minimal entry");
+                    log::info!(
+                        "upsert_partner_id: no entry for '{}…', creating minimal entry",
+                        log_id(ec_id)
+                    );
                     let minimal = KvEntry::minimal(partner_id, uid, synced);
                     let (min_body, min_meta) = Self::serialize_entry(&minimal, &self.store_name)?;
                     if Self::try_insert_add(&store, ec_id, &min_body, &min_meta, &self.store_name)?
@@ -556,7 +574,10 @@ impl KvIdentityGraph {
         let (mut entry, generation) = match self.get(ec_id)? {
             Some(pair) => pair,
             None => {
-                log::debug!("update_last_seen: no entry for '{ec_id}', skipping");
+                log::debug!(
+                    "update_last_seen: no entry for '{}…', skipping",
+                    log_id(ec_id)
+                );
                 return Ok(());
             }
         };
@@ -564,7 +585,10 @@ impl KvIdentityGraph {
         // Skip tombstones — a stale cookie should not extend a 24h tombstone
         // back to 1-year TTL.
         if !entry.consent.ok {
-            log::debug!("update_last_seen: entry for '{ec_id}' is a tombstone, skipping");
+            log::debug!(
+                "update_last_seen: entry for '{}…' is a tombstone, skipping",
+                log_id(ec_id)
+            );
             return Ok(());
         }
 
@@ -610,7 +634,8 @@ impl KvIdentityGraph {
                     } else {
                         log::debug!(
                             "update_last_seen: seen_domains cap ({MAX_SEEN_DOMAINS}) reached \
-                             for '{ec_id}', dropping domain '{domain}'"
+                             for '{}…', dropping domain '{domain}'",
+                            log_id(ec_id),
                         );
                     }
                 }
@@ -746,8 +771,9 @@ impl KvIdentityGraph {
             if let Some(checked) = network.cluster_checked {
                 if now.saturating_sub(checked) < recheck_secs {
                     log::trace!(
-                        "evaluate_cluster: cached cluster_size for '{ec_id}' \
+                        "evaluate_cluster: cached cluster_size for '{}…' \
                          (age={}s, ttl={recheck_secs}s)",
+                        log_id(ec_id),
                         now.saturating_sub(checked),
                     );
                     return Ok(network.cluster_size);
@@ -759,7 +785,10 @@ impl KvIdentityGraph {
         let hash_prefix = ec_hash(ec_id);
         let cluster_size = self.count_hash_prefix_keys(hash_prefix)?;
 
-        log::debug!("evaluate_cluster: computed cluster_size={cluster_size} for '{ec_id}'");
+        log::debug!(
+            "evaluate_cluster: computed cluster_size={cluster_size} for '{}…'",
+            log_id(ec_id)
+        );
 
         // Best-effort CAS write-back — update the network field.
         let mut updated_entry = entry.clone();
@@ -787,7 +816,10 @@ impl KvIdentityGraph {
             }
             Err(err) => {
                 // Log but don't fail — the computed value is still valid.
-                log::warn!("evaluate_cluster: failed to write cluster_size for '{ec_id}': {err}");
+                log::warn!(
+                    "evaluate_cluster: failed to write cluster_size for '{}…': {err}",
+                    log_id(ec_id)
+                );
             }
         }
 

From 6692e45d4abf0db49208d5c80bdc81ba277457ae Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Wed, 8 Apr 2026 19:35:38 -0500
Subject: [PATCH 35/36] Harden EC module: fix cleartext logging, input
 validation, security, and code quality

Address review findings across the EC identity system:

- Extract shared log_id() and truncate EC IDs/client IPs in all 26 log
  sites to satisfy CodeQL cleartext-logging rules (P0)
- Enforce HTTPS on sync pixel return URLs, restrict EC ID validation to
  lowercase hex, add cookie debug_assert and API key hash collision guard (P1)
- Add 2MB body size limit on batch sync, minimum passphrase length,
  whitespace-only pull token rejection (P1/P2)
- Fix withdrawal_ec_ids double computation, pull_sync double ec_value()
  call, and downgrade CAS conflict on update_last_seen to debug (P1/P2)
- Deduplicate MAX_UID_LENGTH and normalize_ec_id_for_kv to shared
  locations, unify ec::consent wrapper usage (P1/P2)
- Fix test extract_ec_cookie short-circuit bug, MinimalOrigin HTTP
  response whitespace, pixel sync Location header assertion (P0/P1)
- Switch ad-proxy base64 to URL_SAFE_NO_PAD for path-safe encoding (P1)
- Cleanup: remove stale #[allow(unused)], fix typos, add Debug derives,
  add mobile signal named constants, redact api_key in Debug output
---
 crates/integration-tests/tests/common/ec.rs   | 25 ++++----
 .../tests/frameworks/scenarios.rs             | 15 +++--
 .../src/auction/endpoints.rs                  |  6 +-
 crates/trusted-server-core/src/cookies.rs     |  2 +-
 crates/trusted-server-core/src/ec/admin.rs    | 19 +++++-
 .../trusted-server-core/src/ec/batch_sync.rs  | 35 +++++------
 crates/trusted-server-core/src/ec/cookies.rs  | 29 +++++++--
 crates/trusted-server-core/src/ec/device.rs   | 18 ++++--
 crates/trusted-server-core/src/ec/finalize.rs | 45 +++++++++-----
 .../trusted-server-core/src/ec/generation.rs  | 31 ++++++++--
 crates/trusted-server-core/src/ec/identify.rs | 15 +++--
 crates/trusted-server-core/src/ec/kv.rs       | 60 ++++++++++++-------
 crates/trusted-server-core/src/ec/kv_types.rs |  5 ++
 crates/trusted-server-core/src/ec/mod.rs      | 12 +++-
 crates/trusted-server-core/src/ec/partner.rs  | 29 ++++++++-
 .../trusted-server-core/src/ec/pull_sync.rs   | 10 ++--
 .../trusted-server-core/src/ec/sync_pixel.rs  | 17 +++++-
 .../src/integrations/prebid.rs                |  2 +-
 crates/trusted-server-core/src/settings.rs    | 13 ++--
 .../trusted-server-core/src/settings_data.rs  |  2 +-
 .../src/storage/kv_store.rs                   | 39 +++++++++---
 21 files changed, 304 insertions(+), 125 deletions(-)

diff --git a/crates/integration-tests/tests/common/ec.rs b/crates/integration-tests/tests/common/ec.rs
index f3118e4e..fd83d90e 100644
--- a/crates/integration-tests/tests/common/ec.rs
+++ b/crates/integration-tests/tests/common/ec.rs
@@ -337,15 +337,19 @@ pub fn assert_json_response(resp: Response, expected_status: u16) -> TestResult<
 /// Returns `None` if no `ts-ec` cookie was set.
 pub fn extract_ec_cookie_from_response(resp: &Response) -> Option<String> {
     for value in resp.headers().get_all("set-cookie") {
-        let cookie_str = value.to_str().ok()?;
+        let Ok(cookie_str) = value.to_str() else {
+            continue;
+        };
         if cookie_str.starts_with("ts-ec=") {
-            let value = cookie_str
+            let extracted = cookie_str
                 .split(';')
-                .next()?
-                .strip_prefix("ts-ec=")?
-                .to_owned();
-            if !value.is_empty() {
-                return Some(value);
+                .next()
+                .and_then(|s| s.strip_prefix("ts-ec="))
+                .map(str::to_owned);
+            if let Some(ref v) = extracted {
+                if !v.is_empty() {
+                    return extracted;
+                }
             }
         }
     }
@@ -417,12 +421,7 @@ impl MinimalOrigin {
 
                         let body = "<html><body><h1>Test Origin</h1></body></html>";
                         let response = format!(
-                            "HTTP/1.1 200 OK\r\n\
-                             Content-Type: text/html\r\n\
-                             Content-Length: {}\r\n\
-                             Connection: close\r\n\
-                             \r\n\
-                             {body}",
+                            "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
                             body.len()
                         );
                         let _ = stream.write_all(response.as_bytes());
diff --git a/crates/integration-tests/tests/frameworks/scenarios.rs b/crates/integration-tests/tests/frameworks/scenarios.rs
index 49402929..31602f59 100644
--- a/crates/integration-tests/tests/frameworks/scenarios.rs
+++ b/crates/integration-tests/tests/frameworks/scenarios.rs
@@ -526,6 +526,15 @@ fn ec_full_lifecycle(base_url: &str) -> TestResult<()> {
         .attach(format!("pixel sync should redirect; body: {body}")));
     }
 
+    // Verify the redirect points to the registered return domain.
+    let location = resp.headers().get("location").and_then(|v| v.to_str().ok());
+    if !location.is_some_and(|l| l.starts_with("https://sync.example.com/")) {
+        return Err(Report::new(TestError::UnexpectedContent).attach(format!(
+            "pixel sync redirect should point to return domain, got: {:?}",
+            location
+        )));
+    }
+
     // 4. Identify should return the synced UID
     let json = assert_json_response(identify(&client)?, 200)
         .attach("EC full lifecycle: identify after pixel sync")?;
@@ -578,10 +587,8 @@ fn ec_consent_withdrawal(base_url: &str) -> TestResult<()> {
     let resp = client.get_with_headers("/", &[("sec-gpc", "1")])?;
 
     if !is_ec_cookie_expired(&resp) {
-        return Err(Report::new(TestError::JsonFieldMismatch {
-            field: "set-cookie(ts-ec expired)".to_owned(),
-        })
-        .attach("consent withdrawal should expire ts-ec cookie"));
+        return Err(Report::new(TestError::UnexpectedContent)
+            .attach("consent withdrawal should expire ts-ec cookie (expected Max-Age=0)"));
     }
 
     // 3. With cookie revoked and no GPC header on identify, server should
diff --git a/crates/trusted-server-core/src/auction/endpoints.rs b/crates/trusted-server-core/src/auction/endpoints.rs
index fbecd403..f752fa24 100644
--- a/crates/trusted-server-core/src/auction/endpoints.rs
+++ b/crates/trusted-server-core/src/auction/endpoints.rs
@@ -7,6 +7,7 @@ use crate::auction::formats::AdRequest;
 use crate::consent::gate_eids_by_consent;
 use crate::ec::eids::{resolve_partner_ids, to_eids};
 use crate::ec::kv::KvIdentityGraph;
+use crate::ec::log_id;
 use crate::ec::partner::PartnerStore;
 use crate::ec::EcContext;
 use crate::error::TrustedServerError;
@@ -129,7 +130,10 @@ fn resolve_auction_eids(
         Ok(Some((entry, _generation))) => entry,
         Ok(None) => return Some(Vec::new()),
         Err(err) => {
-            log::warn!("Auction KV read failed for EC ID '{ec_id}': {err:?}");
+            log::warn!(
+                "Auction KV read failed for EC ID '{}…': {err:?}",
+                log_id(ec_id)
+            );
             return Some(Vec::new());
         }
     };
diff --git a/crates/trusted-server-core/src/cookies.rs b/crates/trusted-server-core/src/cookies.rs
index 3408eb79..ca94a32c 100644
--- a/crates/trusted-server-core/src/cookies.rs
+++ b/crates/trusted-server-core/src/cookies.rs
@@ -145,7 +145,7 @@ mod tests {
     }
 
     #[test]
-    fn test_parse_cookies_to_jar_emtpy() {
+    fn test_parse_cookies_to_jar_empty() {
         let cookie_str = "";
         let jar = parse_cookies_to_jar(cookie_str);
 
diff --git a/crates/trusted-server-core/src/ec/admin.rs b/crates/trusted-server-core/src/ec/admin.rs
index 326cb94b..4a69d141 100644
--- a/crates/trusted-server-core/src/ec/admin.rs
+++ b/crates/trusted-server-core/src/ec/admin.rs
@@ -20,7 +20,7 @@ use super::partner::{
 ///
 /// Accepts `api_key` as plaintext — it is hashed before storage and
 /// never persisted in cleartext.
-#[derive(Debug, Deserialize)]
+#[derive(Deserialize)]
 pub struct RegisterPartnerRequest {
     pub id: String,
     pub name: String,
@@ -50,6 +50,23 @@ pub struct RegisterPartnerRequest {
     pub ts_pull_token: Option<String>,
 }
 
+impl std::fmt::Debug for RegisterPartnerRequest {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("RegisterPartnerRequest")
+            .field("id", &self.id)
+            .field("name", &self.name)
+            .field("api_key", &"[REDACTED]")
+            .field("bidstream_enabled", &self.bidstream_enabled)
+            .field("source_domain", &self.source_domain)
+            .field("pull_sync_enabled", &self.pull_sync_enabled)
+            .field(
+                "ts_pull_token",
+                &self.ts_pull_token.as_ref().map(|_| "[REDACTED]"),
+            )
+            .finish_non_exhaustive()
+    }
+}
+
 fn default_openrtb_atype() -> u8 {
     3
 }
diff --git a/crates/trusted-server-core/src/ec/batch_sync.rs b/crates/trusted-server-core/src/ec/batch_sync.rs
index 8347e208..66c371bb 100644
--- a/crates/trusted-server-core/src/ec/batch_sync.rs
+++ b/crates/trusted-server-core/src/ec/batch_sync.rs
@@ -13,8 +13,9 @@ use serde::{Deserialize, Serialize};
 
 use crate::error::TrustedServerError;
 
-use super::generation::is_valid_ec_id;
+use super::generation::{is_valid_ec_id, normalize_ec_id_for_kv};
 use super::kv::{KvIdentityGraph, UpsertResult};
+use super::log_id;
 use super::partner::{hash_api_key, PartnerRecord, PartnerStore};
 use super::sync_pixel::RateLimiter;
 
@@ -27,8 +28,7 @@ const REASON_KV_UNAVAILABLE: &str = "kv_unavailable";
 /// Maximum number of mappings allowed in a single batch request.
 const MAX_BATCH_SIZE: usize = 1000;
 
-/// Maximum allowed length (in bytes) for a partner UID.
-const MAX_UID_LENGTH: usize = 512;
+use super::kv_types::MAX_UID_LENGTH;
 
 trait BatchSyncWriter {
     fn upsert_partner_id_if_exists(
@@ -159,8 +159,16 @@ fn handle_batch_sync_with_writer(
         ));
     }
 
-    // 3. Parse body
-    let body: BatchSyncRequest = serde_json::from_slice(&req.take_body_bytes()).map_err(|e| {
+    // 3. Parse body (with size limit to prevent OOM before validation)
+    const MAX_BODY_SIZE: usize = 2 * 1024 * 1024; // 2 MB
+    let body_bytes = req.take_body_bytes();
+    if body_bytes.len() > MAX_BODY_SIZE {
+        return Ok(error_response(
+            StatusCode::PAYLOAD_TOO_LARGE,
+            "body_too_large",
+        ));
+    }
+    let body: BatchSyncRequest = serde_json::from_slice(&body_bytes).map_err(|e| {
         Report::new(TrustedServerError::BadRequest {
             message: format!("Invalid request body: {e}"),
         })
@@ -238,8 +246,8 @@ fn process_mappings(
             }
             Err(err) => {
                 log::warn!(
-                    "Batch sync KV write failed for index {idx} (ec_id '{}'): {err:?}",
-                    mapping.ec_id
+                    "Batch sync KV write failed for index {idx} (ec_id '{}…'): {err:?}",
+                    log_id(&mapping.ec_id),
                 );
                 errors.push(MappingError {
                     index: idx,
@@ -260,19 +268,6 @@ fn process_mappings(
     (accepted, errors)
 }
 
-/// Normalizes an EC ID for use as a KV key by lowercasing the hash prefix.
-///
-/// `hex::encode` (used in `generate_ec_id`) always produces lowercase hex,
-/// so internal EC IDs are already lowercase. This normalization is a
-/// defense-in-depth measure for EC IDs submitted by external partners
-/// (via batch sync) that may use uppercase hex.
-fn normalize_ec_id_for_kv(ec_id: &str) -> String {
-    let mut parts = ec_id.splitn(2, '.');
-    let hash = parts.next().unwrap_or_default();
-    let suffix = parts.next().unwrap_or_default();
-    format!("{}.{}", hash.to_ascii_lowercase(), suffix)
-}
-
 fn json_response<T: serde::Serialize>(
     status: StatusCode,
     body: &T,
diff --git a/crates/trusted-server-core/src/ec/cookies.rs b/crates/trusted-server-core/src/ec/cookies.rs
index f13e12be..41f981b9 100644
--- a/crates/trusted-server-core/src/ec/cookies.rs
+++ b/crates/trusted-server-core/src/ec/cookies.rs
@@ -8,7 +8,11 @@
 //! - `Secure` restricts to HTTPS
 //! - `SameSite=Lax` provides CSRF protection while allowing top-level navigations
 //! - `Max-Age` of 1 year (or 0 to expire)
-//! - No `HttpOnly` — the cookie needs to be readable by client-side scripts
+//! - No `HttpOnly` — intentionally omitted so the cookie is available to
+//!   client-side JS if needed in the future (e.g. direct reads from
+//!   `document.cookie` for the identify endpoint). This does expose the EC
+//!   ID to XSS; if client-side access is never needed, consider restoring
+//!   `HttpOnly` for defense-in-depth.
 
 use fastly::http::header;
 
@@ -44,7 +48,16 @@ pub fn create_ec_cookie(settings: &Settings, ec_id: &str) -> String {
 }
 
 /// Sets the EC ID cookie on the given response.
+///
+/// # Panics (debug only)
+///
+/// Debug-asserts that `ec_id` passes [`super::generation::is_valid_ec_id`]
+/// as a defense-in-depth check against cookie injection.
 pub fn set_ec_cookie(settings: &Settings, response: &mut fastly::Response, ec_id: &str) {
+    debug_assert!(
+        super::generation::is_valid_ec_id(ec_id),
+        "EC ID must be validated before cookie creation: got '{ec_id}'"
+    );
     response.append_header(header::SET_COOKIE, create_ec_cookie(settings, ec_id));
 }
 
@@ -65,16 +78,20 @@ mod tests {
     use crate::test_support::tests::create_test_settings;
     use fastly::http::header;
 
+    /// A valid EC ID for use in cookie tests.
+    const TEST_EC_ID: &str =
+        "aaaaaaaabbbbbbbbccccccccddddddddeeeeeeeeffffffff0000000011111111.abcXYZ";
+
     #[test]
     fn create_ec_cookie_uses_computed_domain() {
         let settings = create_test_settings();
-        let result = create_ec_cookie(&settings, "12345");
+        let result = create_ec_cookie(&settings, TEST_EC_ID);
 
         assert_eq!(
             result,
             format!(
-                "{}=12345; Domain=.{}; Path=/; Secure; SameSite=Lax; Max-Age={}",
-                COOKIE_TS_EC, settings.publisher.domain, COOKIE_MAX_AGE,
+                "{}={}; Domain=.{}; Path=/; Secure; SameSite=Lax; Max-Age={}",
+                COOKIE_TS_EC, TEST_EC_ID, settings.publisher.domain, COOKIE_MAX_AGE,
             ),
             "should use computed cookie domain (.{{domain}})"
         );
@@ -84,7 +101,7 @@ mod tests {
     fn set_ec_cookie_appends_header() {
         let settings = create_test_settings();
         let mut response = fastly::Response::new();
-        set_ec_cookie(&settings, &mut response, "test-id-123");
+        set_ec_cookie(&settings, &mut response, TEST_EC_ID);
 
         let cookie_header = response
             .get_header(header::SET_COOKIE)
@@ -93,7 +110,7 @@ mod tests {
 
         assert_eq!(
             cookie_str,
-            create_ec_cookie(&settings, "test-id-123"),
+            create_ec_cookie(&settings, TEST_EC_ID),
             "should match create_ec_cookie output"
         );
     }
diff --git a/crates/trusted-server-core/src/ec/device.rs b/crates/trusted-server-core/src/ec/device.rs
index 5bdd563b..4b650791 100644
--- a/crates/trusted-server-core/src/ec/device.rs
+++ b/crates/trusted-server-core/src/ec/device.rs
@@ -90,20 +90,28 @@ impl DeviceSignals {
     }
 }
 
+/// Device is a desktop (confirmed via UA platform token).
+pub const MOBILE_DESKTOP: u8 = 0;
+/// Device is a mobile (confirmed via UA mobile token).
+pub const MOBILE_MOBILE: u8 = 1;
+/// Device type is genuinely unknown (typically bots or hardened clients).
+pub const MOBILE_UNKNOWN: u8 = 2;
+
 /// Derives mobile signal from the User-Agent string.
 ///
-/// Returns `0` for confirmed desktop, `1` for confirmed mobile,
-/// `2` for genuinely unknown (typically bots or hardened clients).
+/// Returns [`MOBILE_DESKTOP`] for confirmed desktop,
+/// [`MOBILE_MOBILE`] for confirmed mobile,
+/// [`MOBILE_UNKNOWN`] for genuinely unknown (typically bots or hardened clients).
 #[must_use]
 pub fn parse_is_mobile(ua: &str) -> u8 {
     // Mobile patterns checked first — more specific.
     if ua.contains("iPhone") || ua.contains("iPad") || ua.contains("Android") {
-        return 1;
+        return MOBILE_MOBILE;
     }
     if ua.contains("Macintosh") || ua.contains("Windows") || ua.contains("Linux") {
-        return 0;
+        return MOBILE_DESKTOP;
     }
-    2
+    MOBILE_UNKNOWN
 }
 
 /// Parses coarse OS family from the User-Agent string.
diff --git a/crates/trusted-server-core/src/ec/finalize.rs b/crates/trusted-server-core/src/ec/finalize.rs
index 3e030f62..763edd74 100644
--- a/crates/trusted-server-core/src/ec/finalize.rs
+++ b/crates/trusted-server-core/src/ec/finalize.rs
@@ -7,7 +7,7 @@ use std::collections::HashSet;
 
 use fastly::Response;
 
-use crate::consent::allows_ec_creation;
+use super::consent::ec_consent_granted;
 use crate::constants::HEADER_X_TS_EC;
 use crate::settings::Settings;
 
@@ -15,6 +15,7 @@ use super::cookies::{expire_ec_cookie, set_ec_cookie};
 use super::current_timestamp;
 use super::generation::is_valid_ec_id;
 use super::kv::KvIdentityGraph;
+use super::log_id;
 use super::EcContext;
 
 /// TS-managed response headers tied to EC identity output.
@@ -35,20 +36,29 @@ pub fn ec_finalize_response(
     kv: Option<&KvIdentityGraph>,
     response: &mut Response,
 ) {
-    let consent_allows_ec = allows_ec_creation(ec_context.consent());
+    let consent_allows_ec = ec_consent_granted(ec_context.consent());
 
     // Withdrawal path: no consent + cookie was present.
     if !consent_allows_ec && ec_context.cookie_was_present() {
         clear_ec_on_response(settings, response);
 
+        // Compute once — used for both consent store cleanup and tombstoning.
+        let ids_to_withdraw = withdrawal_ec_ids(ec_context);
+
         if let Some(store_name) = settings.consent.consent_store.as_deref() {
             if let Ok(store) = fastly::kv_store::KVStore::open(store_name) {
                 if let Some(store) = store {
-                    for ec_id in withdrawal_ec_ids(ec_context) {
-                        if let Err(err) = store.delete(&ec_id) {
-                            log::warn!("Failed to delete consent KV entry for '{ec_id}': {err:?}");
+                    for ec_id in &ids_to_withdraw {
+                        if let Err(err) = store.delete(ec_id) {
+                            log::warn!(
+                                "Failed to delete consent KV entry for '{}…': {err:?}",
+                                log_id(ec_id)
+                            );
                         } else {
-                            log::info!("Deleted consent KV entry for '{ec_id}' (consent revoked)");
+                            log::info!(
+                                "Deleted consent KV entry for '{}…' (consent revoked)",
+                                log_id(ec_id)
+                            );
                         }
                     }
                 }
@@ -58,11 +68,11 @@ pub fn ec_finalize_response(
         }
 
         if let Some(graph) = kv {
-            for ec_id in withdrawal_ec_ids(ec_context) {
-                if let Err(err) = graph.write_withdrawal_tombstone(&ec_id) {
+            for ec_id in &ids_to_withdraw {
+                if let Err(err) = graph.write_withdrawal_tombstone(ec_id) {
                     log::error!(
-                        "Failed to write withdrawal tombstone for EC ID '{}': {err:?}",
-                        ec_id,
+                        "Failed to write withdrawal tombstone for EC ID '{}…': {err:?}",
+                        log_id(ec_id),
                     );
                 }
             }
@@ -77,7 +87,10 @@ pub fn ec_finalize_response(
             if let Err(err) =
                 graph.update_last_seen(ec_id, current_timestamp(), &settings.publisher.domain)
             {
-                log::error!("Failed to update last_seen for EC ID '{}': {err:?}", ec_id,);
+                log::error!(
+                    "Failed to update last_seen for EC ID '{}…': {err:?}",
+                    log_id(ec_id)
+                );
             }
         }
 
@@ -228,7 +241,7 @@ mod tests {
     #[test]
     fn finalize_withdrawal_clears_cookie_and_headers() {
         let settings = create_test_settings();
-        let ec_id = sample_ec_id("ABC123");
+        let ec_id = sample_ec_id("aBc123");
         let ec_context = make_context(
             Some(&ec_id),
             Some(&ec_id),
@@ -264,8 +277,8 @@ mod tests {
     #[test]
     fn finalize_returning_user_with_cookie_mismatch_rewrites_cookie_and_header() {
         let settings = create_test_settings();
-        let active_ec = sample_ec_id("ACTIVE1");
-        let cookie_ec = sample_ec_id("COOKIE1");
+        let active_ec = sample_ec_id("activ1");
+        let cookie_ec = sample_ec_id("cook1e");
         let ec_context = make_context(
             Some(&active_ec),
             Some(&cookie_ec),
@@ -298,7 +311,7 @@ mod tests {
     #[test]
     fn finalize_returning_user_refreshes_cookie_and_header_when_matching() {
         let settings = create_test_settings();
-        let ec_id = sample_ec_id("MATCH01");
+        let ec_id = sample_ec_id("mtch01");
         let ec_context = make_context(
             Some(&ec_id),
             Some(&ec_id),
@@ -331,7 +344,7 @@ mod tests {
     #[test]
     fn finalize_generated_ec_sets_cookie_and_header() {
         let settings = create_test_settings();
-        let generated_ec = sample_ec_id("GEN123");
+        let generated_ec = sample_ec_id("gen123");
         let ec_context = make_context(
             Some(&generated_ec),
             None,
diff --git a/crates/trusted-server-core/src/ec/generation.rs b/crates/trusted-server-core/src/ec/generation.rs
index 3752b479..59847f93 100644
--- a/crates/trusted-server-core/src/ec/generation.rs
+++ b/crates/trusted-server-core/src/ec/generation.rs
@@ -69,6 +69,10 @@ fn generate_random_suffix(length: usize) -> String {
 /// the client IP address, then appends a random suffix for additional
 /// uniqueness. The resulting format is `{64hex}.{6alnum}`.
 ///
+/// **Important:** `client_ip` must be pre-normalized via [`extract_client_ip`].
+/// Raw IPv6 addresses produce different hashes than their normalized /64
+/// form, which would create duplicate identity graph entries.
+///
 /// # Errors
 ///
 /// - [`TrustedServerError::EdgeCookie`] if HMAC generation fails
@@ -76,8 +80,6 @@ pub fn generate_ec_id(
     settings: &Settings,
     client_ip: &str,
 ) -> Result<String, Report<TrustedServerError>> {
-    log::trace!("Input for fresh EC ID: client_ip={client_ip}");
-
     let mut mac = HmacSha256::new_from_slice(settings.ec.passphrase.expose().as_bytes())
         .change_context(TrustedServerError::EdgeCookie {
             message: "Failed to create HMAC instance".to_string(),
@@ -89,7 +91,7 @@ pub fn generate_ec_id(
     let random_suffix = generate_random_suffix(6);
     let ec_id = format!("{hmac_hash}.{random_suffix}");
 
-    log::trace!("Generated fresh EC ID: {ec_id}");
+    log::trace!("Generated fresh EC ID: {}…", super::log_id(&ec_id));
 
     Ok(ec_id)
 }
@@ -125,6 +127,20 @@ pub fn ec_hash(ec_id: &str) -> &str {
     }
 }
 
+/// Normalizes an EC ID for use as a KV key by lowercasing the hash prefix.
+///
+/// `hex::encode` (used in [`generate_ec_id`]) always produces lowercase hex,
+/// so internal EC IDs are already lowercase. This normalization is a
+/// defense-in-depth measure for EC IDs submitted by external partners
+/// (via batch sync) that may use uppercase hex.
+#[must_use]
+pub fn normalize_ec_id_for_kv(ec_id: &str) -> String {
+    let mut parts = ec_id.splitn(2, '.');
+    let hash = parts.next().unwrap_or_default();
+    let suffix = parts.next().unwrap_or_default();
+    format!("{}.{}", hash.to_ascii_lowercase(), suffix)
+}
+
 /// Checks whether a string is a valid 64-character hex EC hash prefix.
 ///
 /// Used by batch sync, finalize, and other modules that handle the
@@ -139,8 +155,9 @@ pub fn is_valid_ec_hash(value: &str) -> bool {
 /// Checks whether a string matches the expected EC ID format.
 ///
 /// The format is `{64hex}.{6alnum}` where the first part is a 64-character
-/// lowercase hex string and the second part is a 6-character alphanumeric
-/// string.
+/// **lowercase** hex string and the second part is a 6-character alphanumeric
+/// string. Only lowercase hex is accepted; callers must normalize before
+/// validation to prevent duplicate KV keys from case-variant EC IDs.
 #[must_use]
 pub fn is_valid_ec_id(value: &str) -> bool {
     let mut parts = value.split('.');
@@ -158,7 +175,9 @@ pub fn is_valid_ec_id(value: &str) -> bool {
 
     hmac_part.len() == 64
         && suffix_part.len() == 6
-        && hmac_part.bytes().all(|b| b.is_ascii_hexdigit())
+        && hmac_part
+            .bytes()
+            .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
         && suffix_part.bytes().all(|b| b.is_ascii_alphanumeric())
 }
 
diff --git a/crates/trusted-server-core/src/ec/identify.rs b/crates/trusted-server-core/src/ec/identify.rs
index cd90b084..405f5cd2 100644
--- a/crates/trusted-server-core/src/ec/identify.rs
+++ b/crates/trusted-server-core/src/ec/identify.rs
@@ -7,7 +7,7 @@ use fastly::http::{header, StatusCode};
 use fastly::{Request, Response};
 use url::Url;
 
-use crate::consent::allows_ec_creation;
+use super::consent::ec_consent_granted;
 use crate::constants::{
     HEADER_X_TS_EC, HEADER_X_TS_EC_CONSENT, HEADER_X_TS_EIDS, HEADER_X_TS_EIDS_TRUNCATED,
 };
@@ -17,6 +17,7 @@ use crate::settings::Settings;
 
 use super::eids::{build_eids_header, resolve_partner_ids, to_eids};
 use super::kv::KvIdentityGraph;
+use super::log_id;
 use super::partner::PartnerStore;
 use super::EcContext;
 
@@ -39,7 +40,7 @@ pub fn handle_identify(
         return Ok(Response::from_status(StatusCode::FORBIDDEN));
     }
 
-    if !allows_ec_creation(ec_context.consent()) {
+    if !ec_consent_granted(ec_context.consent()) {
         let mut response = json_response(
             StatusCode::FORBIDDEN,
             &serde_json::json!({ "consent": "denied" }),
@@ -81,14 +82,20 @@ pub fn handle_identify(
                     cluster_size = size;
                 }
                 Err(err) => {
-                    log::warn!("Cluster evaluation failed for '{ec_id}': {err:?}");
+                    log::warn!(
+                        "Cluster evaluation failed for '{}…': {err:?}",
+                        log_id(ec_id)
+                    );
                     // Non-fatal — cluster_size stays None, response is still useful.
                 }
             }
         }
         Ok(None) => {}
         Err(err) => {
-            log::warn!("Identify KV read failed for EC ID '{ec_id}': {err:?}");
+            log::warn!(
+                "Identify KV read failed for EC ID '{}…': {err:?}",
+                log_id(ec_id)
+            );
             degraded = true;
         }
     }
diff --git a/crates/trusted-server-core/src/ec/kv.rs b/crates/trusted-server-core/src/ec/kv.rs
index 0313160d..0d242460 100644
--- a/crates/trusted-server-core/src/ec/kv.rs
+++ b/crates/trusted-server-core/src/ec/kv.rs
@@ -58,14 +58,7 @@ pub enum UpsertResult {
     Stale,
 }
 
-/// Truncates an EC ID for safe inclusion in log messages.
-///
-/// Returns the first 8 characters followed by `…` to aid debugging without
-/// writing the full user identifier to logs (satisfies the `CodeQL`
-/// "cleartext logging of sensitive information" rule).
-fn log_id(ec_id: &str) -> &str {
-    ec_id.get(..8).unwrap_or(ec_id)
-}
+use super::log_id;
 
 /// Wraps a Fastly KV Store for EC identity graph operations.
 ///
@@ -74,6 +67,7 @@ fn log_id(ec_id: &str) -> &str {
 ///
 /// Methods use optimistic concurrency (generation markers) for safe
 /// read-modify-write operations on concurrent requests.
+#[derive(Debug)]
 pub struct KvIdentityGraph {
     store_name: String,
 }
@@ -314,8 +308,9 @@ impl KvIdentityGraph {
                 Ok(()) => return Ok(()),
                 Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
                     log::debug!(
-                        "create_or_revive: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_id}'",
+                        "create_or_revive: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{}…'",
                         attempt + 1,
+                        log_id(ec_id),
                     );
                     // Re-read to get fresh generation.
                     match self.get(ec_id)? {
@@ -394,7 +389,8 @@ impl KvIdentityGraph {
                     }
                     // Key appeared between get() and create — re-read on next iteration.
                     log::debug!(
-                        "upsert_partner_id: minimal create raced for '{ec_id}', retrying (attempt {}/{})",
+                        "upsert_partner_id: minimal create raced for '{}…', retrying (attempt {}/{})",
+                        log_id(ec_id),
                         attempt + 1,
                         MAX_CAS_RETRIES,
                     );
@@ -406,7 +402,8 @@ impl KvIdentityGraph {
             // repopulate partner IDs after consent withdrawal.
             if !entry.consent.ok {
                 log::info!(
-                    "upsert_partner_id: entry for '{ec_id}' is a tombstone, rejecting upsert"
+                    "upsert_partner_id: entry for '{}…' is a tombstone, rejecting upsert",
+                    log_id(ec_id),
                 );
                 return Err(Report::new(TrustedServerError::KvStore {
                     store_name: self.store_name.clone(),
@@ -437,8 +434,9 @@ impl KvIdentityGraph {
                 Ok(()) => return Ok(()),
                 Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
                     log::debug!(
-                        "upsert_partner_id: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_id}'",
+                        "upsert_partner_id: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{}…'",
                         attempt + 1,
+                        log_id(ec_id),
                     );
                     // Loop will re-read on next iteration.
                 }
@@ -522,8 +520,9 @@ impl KvIdentityGraph {
                 Ok(()) => return Ok(UpsertResult::Written),
                 Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
                     log::debug!(
-                        "upsert_partner_id_if_exists: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{ec_id}'",
+                        "upsert_partner_id_if_exists: CAS conflict on attempt {}/{MAX_CAS_RETRIES} for '{}…'",
                         attempt + 1,
+                        log_id(ec_id),
                     );
                 }
                 Err(err) => {
@@ -595,7 +594,8 @@ impl KvIdentityGraph {
         // Guard against stale/out-of-order timestamps.
         if timestamp <= entry.last_seen {
             log::trace!(
-                "update_last_seen: stale timestamp for '{ec_id}' (stored={}, incoming={timestamp})",
+                "update_last_seen: stale timestamp for '{}…' (stored={}, incoming={timestamp})",
+                log_id(ec_id),
                 entry.last_seen,
             );
             return Ok(());
@@ -604,7 +604,8 @@ impl KvIdentityGraph {
         // Debounce: skip if the stored value is recent enough.
         if timestamp - entry.last_seen < LAST_SEEN_DEBOUNCE_SECS {
             log::trace!(
-                "update_last_seen: debounced for '{ec_id}' (delta={}s)",
+                "update_last_seen: debounced for '{}…' (delta={}s)",
+                log_id(ec_id),
                 timestamp - entry.last_seen,
             );
             return Ok(());
@@ -660,16 +661,30 @@ impl KvIdentityGraph {
         let store = self.open_store()?;
         let (body, meta_str) = Self::serialize_entry(&entry, &self.store_name)?;
 
-        store
+        match store
             .build_insert()
             .if_generation_match(generation)
             .metadata(&meta_str)
             .time_to_live(ENTRY_TTL)
             .execute(ec_id, body)
-            .change_context(TrustedServerError::KvStore {
-                store_name: self.store_name.clone(),
-                message: format!("Failed to update last_seen for key '{ec_id}'"),
-            })
+        {
+            Ok(()) => Ok(()),
+            // CAS conflict means another request updated more recently —
+            // the debounce condition is satisfied by their write.
+            Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
+                log::debug!(
+                    "update_last_seen: CAS conflict for '{}…', another write won",
+                    log_id(ec_id),
+                );
+                Ok(())
+            }
+            Err(err) => Err(
+                Report::new(err).change_context(TrustedServerError::KvStore {
+                    store_name: self.store_name.clone(),
+                    message: format!("Failed to update last_seen for key '{}…'", log_id(ec_id)),
+                }),
+            ),
+        }
     }
 
     /// Writes a withdrawal tombstone for consent enforcement.
@@ -810,8 +825,9 @@ impl KvIdentityGraph {
             Ok(()) => {}
             Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
                 log::debug!(
-                    "evaluate_cluster: CAS conflict writing cluster_size for '{ec_id}', \
-                     returning computed value anyway"
+                    "evaluate_cluster: CAS conflict writing cluster_size for '{}…', \
+                     returning computed value anyway",
+                    log_id(ec_id),
                 );
             }
             Err(err) => {
diff --git a/crates/trusted-server-core/src/ec/kv_types.rs b/crates/trusted-server-core/src/ec/kv_types.rs
index bf2e6dcb..f6b9da13 100644
--- a/crates/trusted-server-core/src/ec/kv_types.rs
+++ b/crates/trusted-server-core/src/ec/kv_types.rs
@@ -20,6 +20,11 @@ pub const SCHEMA_VERSION: u8 = 1;
 /// When the cap is reached, new domains are silently dropped.
 pub const MAX_SEEN_DOMAINS: usize = 50;
 
+/// Maximum allowed length (in bytes) for a partner UID across all sync
+/// mechanisms (pixel, batch, pull). Defined centrally to ensure consistent
+/// validation.
+pub const MAX_UID_LENGTH: usize = 512;
+
 /// Full KV entry stored as the body of an EC identity graph record.
 ///
 /// **KV key:** Full EC ID (`{64hex}.{6alnum}`).
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index 94e20ffa..d8d60287 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -42,6 +42,16 @@ pub mod partner;
 pub mod pull_sync;
 pub mod sync_pixel;
 
+/// Truncates an EC ID for safe inclusion in log messages.
+///
+/// Returns the first 8 characters followed by `…` to aid debugging without
+/// writing the full user identifier to logs (satisfies the `CodeQL`
+/// "cleartext logging of sensitive information" rule).
+#[must_use]
+pub fn log_id(ec_id: &str) -> &str {
+    ec_id.get(..8).unwrap_or(ec_id)
+}
+
 use cookie::CookieJar;
 use error_stack::Report;
 use fastly::Request;
@@ -264,7 +274,7 @@ impl EcContext {
         })?;
 
         let ec_id = generation::generate_ec_id(settings, client_ip)?;
-        log::trace!("Generated new EC ID: {ec_id}");
+        log::trace!("Generated new EC ID: {}…", log_id(&ec_id));
         self.ec_value = Some(ec_id);
         self.ec_generated = true;
 
diff --git a/crates/trusted-server-core/src/ec/partner.rs b/crates/trusted-server-core/src/ec/partner.rs
index 8fc5c004..40b42eba 100644
--- a/crates/trusted-server-core/src/ec/partner.rs
+++ b/crates/trusted-server-core/src/ec/partner.rs
@@ -154,7 +154,13 @@ pub fn validate_pull_sync_config(record: &PartnerRecord) -> Result<(), String> {
         );
     }
 
-    if record.ts_pull_token.as_deref().unwrap_or("").is_empty() {
+    if record
+        .ts_pull_token
+        .as_deref()
+        .unwrap_or("")
+        .trim()
+        .is_empty()
+    {
         return Err(
             "pull_sync_url and ts_pull_token are required when pull_sync_enabled is true"
                 .to_owned(),
@@ -440,6 +446,22 @@ impl PartnerStore {
         let index_key = format!("{APIKEY_INDEX_PREFIX}{}", record.api_key_hash);
         let previous_index_partner_id = self.read_index_partner_id(&store, &index_key)?;
 
+        // Guard against API key hash collision: reject if the index already
+        // points to a *different* partner. This prevents silently reassigning
+        // another partner's auth mapping.
+        if let Some(ref existing_id) = previous_index_partner_id {
+            if existing_id != &record.id {
+                return Err(Report::new(TrustedServerError::KvStore {
+                    store_name: self.store_name.clone(),
+                    message: format!(
+                        "API key hash already assigned to partner '{existing_id}', \
+                         cannot assign to '{}'",
+                        record.id
+                    ),
+                }));
+            }
+        }
+
         // 1. Write new API key index.
         store
             .build_insert()
@@ -549,7 +571,10 @@ impl PartnerStore {
         let mut ids: Vec<String> = match store.lookup(PULL_ENABLED_INDEX_KEY) {
             Ok(mut resp) => {
                 let bytes = resp.take_body_bytes();
-                serde_json::from_slice(&bytes).unwrap_or_default()
+                serde_json::from_slice(&bytes).unwrap_or_else(|err| {
+                    log::warn!("Failed to deserialize pull-enabled index, starting fresh: {err}");
+                    Vec::new()
+                })
             }
             Err(_) => Vec::new(),
         };
diff --git a/crates/trusted-server-core/src/ec/pull_sync.rs b/crates/trusted-server-core/src/ec/pull_sync.rs
index 4b966f74..b1edef75 100644
--- a/crates/trusted-server-core/src/ec/pull_sync.rs
+++ b/crates/trusted-server-core/src/ec/pull_sync.rs
@@ -61,13 +61,13 @@ pub fn build_pull_sync_context(ec_context: &EcContext) -> Option<PullSyncContext
         return None;
     }
 
-    let ec_id = ec_context.ec_value()?;
-    if !is_valid_ec_id(ec_id) {
+    let ec_id_ref = ec_context.ec_value()?;
+    if !is_valid_ec_id(ec_id_ref) {
         log::debug!("Pull sync: skipping dispatch because active EC ID is invalid format");
         return None;
     }
 
-    let ec_id = ec_context.ec_value()?.to_owned();
+    let ec_id = ec_id_ref.to_owned();
     let client_ip = ec_context.client_ip()?.to_owned();
     Some(PullSyncContext { ec_id, client_ip })
 }
@@ -334,9 +334,7 @@ fn extract_pull_uid(mut response: fastly::Response, partner_id: &str) -> Option<
         }
     };
 
-    // Must match MAX_UID_LENGTH in sync_pixel.rs / batch_sync.rs so that
-    // partners see a consistent limit regardless of sync mechanism.
-    const MAX_UID_LENGTH: usize = 512;
+    use super::kv_types::MAX_UID_LENGTH;
 
     let uid = payload.uid.filter(|value| !value.is_empty());
     match uid {
diff --git a/crates/trusted-server-core/src/ec/sync_pixel.rs b/crates/trusted-server-core/src/ec/sync_pixel.rs
index f796a300..47e43de5 100644
--- a/crates/trusted-server-core/src/ec/sync_pixel.rs
+++ b/crates/trusted-server-core/src/ec/sync_pixel.rs
@@ -6,7 +6,9 @@ use fastly::http::StatusCode;
 use fastly::{Request, Response};
 use url::Url;
 
-use crate::consent::{allows_ec_creation, gpp, tcf, ConsentContext};
+use crate::consent::{gpp, tcf, ConsentContext};
+
+use super::consent::ec_consent_granted;
 use crate::error::TrustedServerError;
 use crate::settings::Settings;
 
@@ -19,7 +21,7 @@ use super::EcContext;
 pub const RATE_COUNTER_NAME: &str = "counter_store";
 
 /// Maximum allowed length (in bytes) for a partner UID.
-const MAX_UID_LENGTH: usize = 512;
+use super::kv_types::MAX_UID_LENGTH;
 
 /// Handles `GET /_ts/api/v1/sync` pixel sync requests.
 ///
@@ -68,7 +70,7 @@ pub fn handle_sync(
         }
     }
 
-    if !allows_ec_creation(ec_context.consent()) {
+    if !ec_consent_granted(ec_context.consent()) {
         return Ok(redirect_with_status(&return_url, "0", Some("no_consent")));
     }
 
@@ -156,6 +158,15 @@ fn validate_return_url(
         message: "return URL must be a valid absolute URL".to_owned(),
     })?;
 
+    if parsed.scheme() != "https" {
+        return Err(Report::new(TrustedServerError::BadRequest {
+            message: format!(
+                "return URL must use HTTPS, got scheme '{}'",
+                parsed.scheme()
+            ),
+        }));
+    }
+
     let host = parsed
         .host_str()
         .ok_or_else(|| {
diff --git a/crates/trusted-server-core/src/integrations/prebid.rs b/crates/trusted-server-core/src/integrations/prebid.rs
index 2b97bad8..f78c5ee6 100644
--- a/crates/trusted-server-core/src/integrations/prebid.rs
+++ b/crates/trusted-server-core/src/integrations/prebid.rs
@@ -3,7 +3,7 @@ use std::sync::Arc;
 use std::time::Duration;
 
 use async_trait::async_trait;
-use base64::{engine::general_purpose::STANDARD as BASE64, Engine};
+use base64::{engine::general_purpose::URL_SAFE_NO_PAD as BASE64, Engine};
 use error_stack::{Report, ResultExt};
 use fastly::http::{header, Method, StatusCode, Url};
 use fastly::{Request, Response};
diff --git a/crates/trusted-server-core/src/settings.rs b/crates/trusted-server-core/src/settings.rs
index 6e4f252c..9fbffbf2 100644
--- a/crates/trusted-server-core/src/settings.rs
+++ b/crates/trusted-server-core/src/settings.rs
@@ -220,7 +220,6 @@ impl DerefMut for IntegrationSettings {
 ///
 /// Mapped from the `[ec]` TOML section. Controls EC identity generation,
 /// KV store names, and partner registry.
-#[allow(unused)]
 #[derive(Debug, Default, Clone, Deserialize, Serialize, Validate)]
 pub struct Ec {
     /// Publisher passphrase used as HMAC key for EC generation.
@@ -284,15 +283,22 @@ impl Ec {
             .any(|p| p.eq_ignore_ascii_case(passphrase))
     }
 
-    /// Validates that the passphrase is not empty.
+    /// Minimum passphrase length for HMAC key strength.
+    const MIN_PASSPHRASE_LENGTH: usize = 8;
+
+    /// Validates that the passphrase is not empty and meets minimum length.
     ///
     /// # Errors
     ///
-    /// Returns a validation error if the passphrase is empty.
+    /// Returns a validation error if the passphrase is empty or shorter
+    /// than [`Self::MIN_PASSPHRASE_LENGTH`] characters.
     pub fn validate_passphrase(passphrase: &Redacted<String>) -> Result<(), ValidationError> {
         if passphrase.expose().is_empty() {
             return Err(ValidationError::new("empty_passphrase"));
         }
+        if passphrase.expose().len() < Self::MIN_PASSPHRASE_LENGTH {
+            return Err(ValidationError::new("short_passphrase"));
+        }
         Ok(())
     }
 }
@@ -485,7 +491,6 @@ pub struct Settings {
     pub proxy: Proxy,
 }
 
-#[allow(unused)]
 impl Settings {
     /// Creates a new [`Settings`] instance from a pre-built TOML string.
     ///
diff --git a/crates/trusted-server-core/src/settings_data.rs b/crates/trusted-server-core/src/settings_data.rs
index 7a59f47a..f8772dfa 100644
--- a/crates/trusted-server-core/src/settings_data.rs
+++ b/crates/trusted-server-core/src/settings_data.rs
@@ -79,7 +79,7 @@ mod tests {
     }
 
     #[test]
-    fn rejects_placeholder_secret_key() {
+    fn rejects_placeholder_passphrase() {
         let toml = toml_with_secrets("secret-key", "real-proxy-secret");
         let settings = Settings::from_toml(&toml).expect("should parse TOML");
         let err = settings
diff --git a/crates/trusted-server-core/src/storage/kv_store.rs b/crates/trusted-server-core/src/storage/kv_store.rs
index c118005a..cffa51a0 100644
--- a/crates/trusted-server-core/src/storage/kv_store.rs
+++ b/crates/trusted-server-core/src/storage/kv_store.rs
@@ -23,6 +23,7 @@ use sha2::{Digest, Sha256};
 
 use crate::consent::jurisdiction::Jurisdiction;
 use crate::consent::types::{ConsentContext, ConsentSource};
+use crate::ec::log_id;
 use crate::platform::PlatformKvStore;
 
 // ---------------------------------------------------------------------------
@@ -248,13 +249,17 @@ pub fn load_consent_from_kv(store: &dyn PlatformKvStore, ec_id: &str) -> Option<
     match serde_json::from_slice::<KvConsentEntry>(&bytes) {
         Ok(entry) => {
             log::info!(
-                "Loaded consent from KV store for '{ec_id}' (stored_at_ds={})",
+                "Loaded consent from KV store for '{}…' (stored_at_ds={})",
+                log_id(ec_id),
                 entry.stored_at_ds
             );
             Some(context_from_entry(&entry))
         }
         Err(e) => {
-            log::warn!("Failed to deserialize consent KV entry for '{ec_id}': {e}");
+            log::warn!(
+                "Failed to deserialize consent KV entry for '{}…': {e}",
+                log_id(ec_id)
+            );
             None
         }
     }
@@ -286,7 +291,10 @@ pub fn save_consent_to_kv(
     let fp = consent_fingerprint(ctx);
 
     if fingerprint_unchanged(store, ec_id, &fp) {
-        log::debug!("Consent unchanged for '{ec_id}' (fp={fp}), skipping write");
+        log::debug!(
+            "Consent unchanged for '{}…' (fp={fp}), skipping write",
+            log_id(ec_id)
+        );
         return;
     }
 
@@ -296,7 +304,10 @@ pub fn save_consent_to_kv(
     let body = match serde_json::to_vec(&entry) {
         Ok(body) => Bytes::from(body),
         Err(e) => {
-            log::warn!("Failed to serialize consent entry for '{ec_id}': {e}");
+            log::warn!(
+                "Failed to serialize consent entry for '{}…': {e}",
+                log_id(ec_id)
+            );
             return;
         }
     };
@@ -305,10 +316,16 @@ pub fn save_consent_to_kv(
 
     match futures::executor::block_on(store.put_bytes_with_ttl(ec_id, body, ttl)) {
         Ok(()) => {
-            log::info!("Saved consent to KV store for '{ec_id}' (fp={fp}, ttl={max_age_days}d)");
+            log::info!(
+                "Saved consent to KV store for '{}…' (fp={fp}, ttl={max_age_days}d)",
+                log_id(ec_id)
+            );
         }
         Err(e) => {
-            log::warn!("Failed to write consent to KV store for '{ec_id}': {e}");
+            log::warn!(
+                "Failed to write consent to KV store for '{}…': {e}",
+                log_id(ec_id)
+            );
         }
     }
 }
@@ -323,10 +340,16 @@ pub fn save_consent_to_kv(
 pub fn delete_consent_from_kv(store: &dyn PlatformKvStore, ec_id: &str) {
     match futures::executor::block_on(store.delete(ec_id)) {
         Ok(()) => {
-            log::info!("Deleted consent KV entry for '{ec_id}' (consent revoked)");
+            log::info!(
+                "Deleted consent KV entry for '{}…' (consent revoked)",
+                log_id(ec_id)
+            );
         }
         Err(e) => {
-            log::warn!("Failed to delete consent KV entry for '{ec_id}': {e}");
+            log::warn!(
+                "Failed to delete consent KV entry for '{}…': {e}",
+                log_id(ec_id)
+            );
         }
     }
 }

From d3e9f0892e7efe86f202abcb010340e8f37edcad Mon Sep 17 00:00:00 2001
From: Christian <christianpavilonis@outlook.com>
Date: Fri, 10 Apr 2026 12:11:31 -0500
Subject: [PATCH 36/36] Add first-party signal collection for EC identity
 system

Implement extraction, validation, and batched CAS writes for first-party
signals (UID2, ID5, LiveRamp) tied to EC IDs. Includes partner registration
endpoint updates, fp_signals module with full test coverage, and adapter
wiring for the Fastly compute entry point.
---
 .../trusted-server-adapter-fastly/src/main.rs |   83 +
 crates/trusted-server-core/src/ec/admin.rs    |   41 +-
 .../trusted-server-core/src/ec/fp_signals.rs  |  940 +++++++++
 crates/trusted-server-core/src/ec/kv.rs       |   48 +
 crates/trusted-server-core/src/ec/mod.rs      |   33 +
 crates/trusted-server-core/src/ec/partner.rs  |  359 +++-
 .../trusted-server-core/src/ec/pull_sync.rs   |    3 +
 .../trusted-server-core/src/ec/sync_pixel.rs  |    3 +
 ...026-04-09-first-party-signal-collection.md | 1816 +++++++++++++++++
 ...09-first-party-signal-collection-design.md |  370 ++++
 10 files changed, 3691 insertions(+), 5 deletions(-)
 create mode 100644 crates/trusted-server-core/src/ec/fp_signals.rs
 create mode 100644 docs/superpowers/plans/2026-04-09-first-party-signal-collection.md
 create mode 100644 docs/superpowers/specs/2026-04-09-first-party-signal-collection-design.md

diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs
index 81974ecc..0274a6f0 100644
--- a/crates/trusted-server-adapter-fastly/src/main.rs
+++ b/crates/trusted-server-adapter-fastly/src/main.rs
@@ -12,8 +12,12 @@ use trusted_server_core::constants::{
 };
 use trusted_server_core::ec::admin::handle_register_partner;
 use trusted_server_core::ec::batch_sync::handle_batch_sync;
+use trusted_server_core::ec::current_timestamp_ms;
 use trusted_server_core::ec::device::DeviceSignals;
 use trusted_server_core::ec::finalize::ec_finalize_response;
+use trusted_server_core::ec::fp_signals::{
+    extract_fp_signals, write_fp_signals, FpSignal, FpSignalPartnerConfig,
+};
 use trusted_server_core::ec::identify::{cors_preflight_identify, handle_identify};
 use trusted_server_core::ec::kv::KvIdentityGraph;
 use trusted_server_core::ec::partner::PartnerStore;
@@ -108,10 +112,22 @@ fn main() -> Result<(), Error> {
     let RouteOutcome {
         response,
         pull_sync_context,
+        ec_id,
+        fp_signals,
+        fp_signal_configs,
     } = outcome;
 
     response.send_to_client();
 
+    // Write first-party signals to KV (post-send, off critical path).
+    // Uses ec_id directly — not gated on PullSyncContext — so signals are
+    // still written when client_ip is unavailable.
+    if !fp_signals.is_empty() {
+        if let Some(ref ec_id) = ec_id {
+            run_fp_signal_collection_after_send(&settings, ec_id, &fp_signals, &fp_signal_configs);
+        }
+    }
+
     if let Some(context) = pull_sync_context {
         run_pull_sync_after_send(&settings, &context);
     }
@@ -123,6 +139,12 @@ fn main() -> Result<(), Error> {
 struct RouteOutcome {
     response: Response,
     pull_sync_context: Option<PullSyncContext>,
+    /// The active EC ID, carried independently from [`PullSyncContext`] so
+    /// that FP signal writes succeed even when `client_ip` is unavailable
+    /// (which makes `PullSyncContext` `None`).
+    ec_id: Option<String>,
+    fp_signals: Vec<FpSignal>,
+    fp_signal_configs: Vec<FpSignalPartnerConfig>,
 }
 
 async fn route_request(
@@ -170,6 +192,9 @@ async fn route_request(
         return Ok(RouteOutcome {
             response,
             pull_sync_context: None,
+            ec_id: None,
+            fp_signals: vec![],
+            fp_signal_configs: vec![],
         });
     }
 
@@ -182,6 +207,9 @@ async fn route_request(
                 return Ok(RouteOutcome {
                     response,
                     pull_sync_context: None,
+                    ec_id: None,
+                    fp_signals: vec![],
+                    fp_signal_configs: vec![],
                 });
             }
         };
@@ -210,6 +238,9 @@ async fn route_request(
             return Ok(RouteOutcome {
                 response,
                 pull_sync_context: None,
+                ec_id: None,
+                fp_signals: vec![],
+                fp_signal_configs: vec![],
             });
         }
         Ok(None) => {}
@@ -220,6 +251,9 @@ async fn route_request(
             return Ok(RouteOutcome {
                 response,
                 pull_sync_context: None,
+                ec_id: None,
+                fp_signals: vec![],
+                fp_signal_configs: vec![],
             });
         }
     }
@@ -353,15 +387,46 @@ async fn route_request(
 
     finalize_response(settings, geo_info.as_ref(), &mut response);
 
+    // Extract first-party signals from cookies for post-send KV write.
+    let (fp_signals, fp_signal_configs) =
+        if is_real_browser && organic_route && route_succeeded && ec_context.ec_allowed() {
+            if ec_context.ec_value().is_some() {
+                let partner_store = require_partner_store(settings).ok();
+                let configs = partner_store
+                    .as_ref()
+                    .and_then(|s| s.fp_signal_configs().ok())
+                    .unwrap_or_default();
+                if configs.is_empty() {
+                    (vec![], vec![])
+                } else {
+                    let now_ms = current_timestamp_ms();
+                    let signals = ec_context
+                        .cookie_jar()
+                        .map(|j| extract_fp_signals(j, &configs, now_ms))
+                        .unwrap_or_default();
+                    (signals, configs)
+                }
+            } else {
+                (vec![], vec![])
+            }
+        } else {
+            (vec![], vec![])
+        };
+
     let pull_sync_context = if is_real_browser && organic_route && route_succeeded {
         build_pull_sync_context(&ec_context)
     } else {
         None
     };
 
+    let ec_id = ec_context.ec_value().map(str::to_owned);
+
     Ok(RouteOutcome {
         response,
         pull_sync_context,
+        ec_id,
+        fp_signals,
+        fp_signal_configs,
     })
 }
 
@@ -390,6 +455,24 @@ fn run_pull_sync_after_send(settings: &Settings, context: &PullSyncContext) {
     dispatch_pull_sync(settings, &kv, &partner_store, &limiter, context);
 }
 
+fn run_fp_signal_collection_after_send(
+    settings: &Settings,
+    ec_id: &str,
+    signals: &[FpSignal],
+    configs: &[FpSignalPartnerConfig],
+) {
+    let kv = match require_identity_graph(settings) {
+        Ok(kv) => kv,
+        Err(err) => {
+            log::debug!("FP signal collection: identity graph unavailable: {err:?}");
+            return;
+        }
+    };
+    if let Err(err) = write_fp_signals(&kv, ec_id, signals, configs) {
+        log::warn!("FP signal collection failed: {err:?}");
+    }
+}
+
 /// Applies all standard response headers: geo, version, staging, and configured headers.
 ///
 /// Called from every response path (including auth early-returns) so that all
diff --git a/crates/trusted-server-core/src/ec/admin.rs b/crates/trusted-server-core/src/ec/admin.rs
index 4a69d141..d77ac702 100644
--- a/crates/trusted-server-core/src/ec/admin.rs
+++ b/crates/trusted-server-core/src/ec/admin.rs
@@ -13,7 +13,8 @@ use url::Host;
 use crate::error::TrustedServerError;
 
 use super::partner::{
-    hash_api_key, validate_partner_id, validate_pull_sync_config, PartnerRecord, PartnerStore,
+    hash_api_key, validate_fp_signal_config, validate_partner_id, validate_pull_sync_config,
+    PartnerRecord, PartnerStore,
 };
 
 /// Request body for `POST /_ts/admin/v1/partners/register`.
@@ -48,6 +49,12 @@ pub struct RegisterPartnerRequest {
     pub pull_sync_rate_limit: u32,
     #[serde(default)]
     pub ts_pull_token: Option<String>,
+    #[serde(default)]
+    pub fp_signal_cookie_names: Vec<String>,
+    #[serde(default)]
+    pub fp_signal_json_path: Option<String>,
+    #[serde(default = "default_fp_signal_ttl_sec")]
+    pub fp_signal_ttl_sec: u64,
 }
 
 impl std::fmt::Debug for RegisterPartnerRequest {
@@ -82,6 +89,9 @@ fn default_pull_sync_ttl_sec() -> u64 {
 fn default_pull_sync_rate_limit() -> u32 {
     10
 }
+fn default_fp_signal_ttl_sec() -> u64 {
+    86400
+}
 
 fn bad_request(message: impl Into<String>) -> Report<TrustedServerError> {
     Report::new(TrustedServerError::BadRequest {
@@ -199,6 +209,9 @@ pub fn handle_register_partner(
         pull_sync_ttl_sec,
         pull_sync_rate_limit,
         ts_pull_token,
+        fp_signal_cookie_names,
+        fp_signal_json_path,
+        fp_signal_ttl_sec,
     } = request;
 
     // Validate partner ID.
@@ -238,11 +251,17 @@ pub fn handle_register_partner(
         pull_sync_ttl_sec,
         pull_sync_rate_limit,
         ts_pull_token,
+        fp_signal_cookie_names,
+        fp_signal_json_path,
+        fp_signal_ttl_sec,
     };
 
     // Validate pull sync configuration.
     validate_pull_sync_config(&record).map_err(bad_request)?;
 
+    // Validate FP signal configuration.
+    validate_fp_signal_config(&record).map_err(bad_request)?;
+
     // Persist to KV store.
     let created = partner_store.upsert(&record)?;
 
@@ -299,6 +318,12 @@ mod tests {
         assert!(!req.pull_sync_enabled, "should default to false");
         assert!(req.pull_sync_url.is_none());
         assert!(req.ts_pull_token.is_none());
+        assert!(
+            req.fp_signal_cookie_names.is_empty(),
+            "should default to empty"
+        );
+        assert!(req.fp_signal_json_path.is_none(), "should default to None");
+        assert_eq!(req.fp_signal_ttl_sec, 86400, "should default to 86400");
     }
 
     #[test]
@@ -340,7 +365,10 @@ mod tests {
             "pull_sync_allowed_domains": ["sync.example-ssp.com"],
             "pull_sync_ttl_sec": 43200,
             "pull_sync_rate_limit": 5,
-            "ts_pull_token": "bearer-token-123"
+            "ts_pull_token": "bearer-token-123",
+            "fp_signal_cookie_names": ["uid2_token", "__euid_uid2"],
+            "fp_signal_json_path": "advertising_token",
+            "fp_signal_ttl_sec": 43200
         }"#;
 
         let req: RegisterPartnerRequest =
@@ -353,6 +381,15 @@ mod tests {
             req.pull_sync_url.as_deref(),
             Some("https://sync.example-ssp.com/pull")
         );
+        assert_eq!(
+            req.fp_signal_cookie_names,
+            vec!["uid2_token".to_owned(), "__euid_uid2".to_owned()]
+        );
+        assert_eq!(
+            req.fp_signal_json_path.as_deref(),
+            Some("advertising_token")
+        );
+        assert_eq!(req.fp_signal_ttl_sec, 43200);
     }
 
     #[test]
diff --git a/crates/trusted-server-core/src/ec/fp_signals.rs b/crates/trusted-server-core/src/ec/fp_signals.rs
new file mode 100644
index 00000000..42dda45a
--- /dev/null
+++ b/crates/trusted-server-core/src/ec/fp_signals.rs
@@ -0,0 +1,940 @@
+//! First-party signal collection from browser cookies.
+//!
+//! Extracts structured partner UIDs from browser cookies set by identity
+//! vendors (e.g. UID2, `RampID`). Partners configure which cookie names to check
+//! and an optional JSON path to navigate into a structured cookie value.
+//!
+//! # Module structure
+//!
+//! - [`FpSignalPartnerConfig`] — per-partner extraction configuration
+//! - [`FpSignal`] — a resolved (`partner_id`, uid) pair
+//! - [`FpSignalError`] — KV write failures during signal persistence
+//! - [`extract_fp_signals`] — main extraction entry point
+
+use std::collections::HashMap;
+
+use cookie::CookieJar;
+use error_stack::{Report, ResultExt};
+use serde::{Deserialize, Serialize};
+
+use super::kv::{CasWriteOutcome, KvIdentityGraph};
+use super::kv_types::{KvPartnerId, MAX_UID_LENGTH};
+use super::log_id;
+
+/// Per-partner configuration for first-party signal extraction.
+///
+/// Stored as part of the partner registry entry. Describes which cookies to
+/// inspect and how to navigate their values to extract the partner UID.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct FpSignalPartnerConfig {
+    /// Unique partner identifier matching the partner registry entry.
+    pub partner_id: String,
+    /// Ordered list of cookie names to check. The first cookie found in the
+    /// request jar wins; remaining names are not checked.
+    pub cookie_names: Vec<String>,
+    /// Optional dot-separated JSON path to extract from a structured cookie
+    /// value (e.g. `"advertising_token"` or `"user.id"`).
+    ///
+    /// When `None`, the raw cookie value is used as the UID.
+    pub json_path: Option<String>,
+    /// Time-to-live in seconds for the extracted signal in the KV store.
+    pub ttl_sec: u64,
+}
+
+/// A resolved first-party signal for a single partner.
+///
+/// Produced by [`extract_fp_signals`] when a matching cookie is found and
+/// a non-empty UID is extracted.
+#[derive(Debug, Clone, PartialEq)]
+pub struct FpSignal {
+    /// Partner identifier, matching the source [`FpSignalPartnerConfig`].
+    pub partner_id: String,
+    /// Extracted user identifier value.
+    pub uid: String,
+}
+
+/// Errors that can occur when persisting first-party signals to the KV store.
+#[derive(Debug, derive_more::Display)]
+pub enum FpSignalError {
+    /// A KV write operation failed for the given reason.
+    #[display("KV write failed: {message}")]
+    KvWrite {
+        /// Human-readable description of the write failure.
+        message: String,
+    },
+}
+
+impl core::error::Error for FpSignalError {}
+
+/// Walks a dot-separated path through an already-parsed JSON value.
+///
+/// Follows each `.`-separated segment in `path` through the object tree.
+/// Returns `Some(string)` only when the final node is a JSON string. Returns
+/// `None` for an empty path, a missing key at any level, or a non-string leaf.
+fn walk_json_path(value: &serde_json::Value, path: &str) -> Option<String> {
+    if path.is_empty() {
+        return None;
+    }
+
+    let mut current = value;
+
+    for segment in path.split('.') {
+        current = current.get(segment)?;
+    }
+
+    current.as_str().map(str::to_owned)
+}
+
+/// Extracts a string value from a JSON document by dot-separated path.
+///
+/// Parses `value` as JSON, then delegates to [`walk_json_path`] to navigate
+/// the object tree. Returns `Some(string)` only when the final node is a JSON
+/// string. Returns `None` for an empty path, invalid JSON, a missing key at
+/// any level, or a non-string leaf.
+fn extract_json_path(value: &str, path: &str) -> Option<String> {
+    if path.is_empty() {
+        return None;
+    }
+
+    let parsed: serde_json::Value = serde_json::from_str(value).ok()?;
+    walk_json_path(&parsed, path)
+}
+
+/// Extracts first-party signals from a cookie jar using partner configurations.
+///
+/// For each [`FpSignalPartnerConfig`]:
+/// 1. Iterates `cookie_names` in order — the first cookie present in `jar` wins.
+/// 2. If the cookie value is JSON containing `identity_expires`, validates that
+///    `identity_expires > now_ms + 300_000` (5-minute buffer). Expired tokens
+///    are skipped.
+/// 3. If `json_path` is `Some`, extracts the UID via [`walk_json_path`] when a
+///    parsed value is already available, or [`extract_json_path`] otherwise.
+///    On extraction failure, logs at `debug` level and skips.
+/// 4. If `json_path` is `None`, uses the raw cookie value as the UID.
+/// 5. Skips signals with an empty UID after trimming whitespace.
+///
+/// Returns a [`Vec<FpSignal>`] of successfully extracted signals, one per
+/// partner at most.
+#[must_use]
+pub fn extract_fp_signals(
+    jar: &CookieJar,
+    configs: &[FpSignalPartnerConfig],
+    now_ms: u64,
+) -> Vec<FpSignal> {
+    let mut signals = Vec::new();
+
+    for config in configs {
+        let cookie_value = config
+            .cookie_names
+            .iter()
+            .find_map(|name| jar.get(name).map(|c| c.value().to_owned()));
+
+        let Some(raw) = cookie_value else {
+            continue;
+        };
+
+        // Parse the cookie value as JSON once. This serves both the UID2 expiry
+        // check and the json_path extraction, avoiding a double parse.
+        let parsed_json: Option<serde_json::Value> = serde_json::from_str(&raw).ok();
+
+        // UID2 expiry check: if the cookie value is JSON with `identity_expires`,
+        // require at least 5 minutes of validity remaining.
+        if let Some(ref parsed) = parsed_json {
+            if let Some(expires_ms) = parsed
+                .get("identity_expires")
+                .and_then(serde_json::Value::as_u64)
+            {
+                let min_valid_ms = now_ms.saturating_add(300_000);
+                if expires_ms <= min_valid_ms {
+                    log::debug!(
+                        "Skipping fp_signal for partner '{}': UID2 token expired or expiring soon \
+                         (identity_expires={expires_ms}, now_ms={now_ms})",
+                        config.partner_id,
+                    );
+                    continue;
+                }
+            }
+        }
+
+        let uid = match &config.json_path {
+            Some(path) => {
+                // Use the already-parsed value when available to avoid a second parse.
+                let extracted = match parsed_json.as_ref() {
+                    Some(parsed) => walk_json_path(parsed, path),
+                    None => extract_json_path(&raw, path),
+                };
+                match extracted {
+                    Some(value) => value,
+                    None => {
+                        log::debug!(
+                            "Skipping fp_signal for partner '{}': JSON path '{}' not found or \
+                             non-string in cookie value",
+                            config.partner_id,
+                            path,
+                        );
+                        continue;
+                    }
+                }
+            }
+            None => raw,
+        };
+
+        let uid = uid.trim().to_owned();
+        if uid.is_empty() {
+            continue;
+        }
+
+        if uid.len() > MAX_UID_LENGTH {
+            log::debug!(
+                "Skipping fp_signal for partner '{}': UID exceeds {MAX_UID_LENGTH} bytes (got {})",
+                config.partner_id,
+                uid.len(),
+            );
+            continue;
+        }
+
+        signals.push(FpSignal {
+            partner_id: config.partner_id.clone(),
+            uid,
+        });
+    }
+
+    signals
+}
+
+/// Maximum number of CAS retry attempts for [`write_fp_signals`].
+const MAX_RETRIES: u32 = 3;
+
+/// Filters signals to those that are missing or stale in the existing KV entry.
+///
+/// For each signal, looks up the partner TTL from `configs` and checks whether
+/// the existing stored value is still fresh (`now - existing.synced < ttl`).
+/// Signals that are fresh are skipped; signals that are missing or stale are
+/// included in the returned slice.
+fn filter_stale_signals<'a>(
+    signals: &'a [FpSignal],
+    existing_ids: &HashMap<String, KvPartnerId>,
+    configs: &[FpSignalPartnerConfig],
+    now: u64,
+) -> Vec<&'a FpSignal> {
+    let ttl_by_partner: HashMap<&str, u64> = configs
+        .iter()
+        .map(|c| (c.partner_id.as_str(), c.ttl_sec))
+        .collect();
+
+    signals
+        .iter()
+        .filter(|signal| {
+            // A missing TTL means the partner config was removed between
+            // extraction and write. Default to 0 (always refresh) since
+            // the signal was legitimately extracted with a valid config.
+            let ttl = ttl_by_partner
+                .get(signal.partner_id.as_str())
+                .copied()
+                .unwrap_or(0);
+            match existing_ids.get(&signal.partner_id) {
+                Some(existing) => now.saturating_sub(existing.synced) >= ttl,
+                None => true,
+            }
+        })
+        .collect()
+}
+
+/// Writes first-party signals to the KV identity graph using optimistic CAS.
+///
+/// Reads the existing entry for `ec_id`, filters out signals that are still
+/// within their configured TTL, then writes the remaining signals back using
+/// a CAS write. Retries up to [`MAX_RETRIES`] times on CAS conflict.
+///
+/// Returns `Ok(())` immediately when:
+/// - The entry does not exist (nothing to write to).
+/// - The entry is a tombstone (`consent.ok == false`).
+/// - All signals are fresh and no write is needed.
+///
+/// # Errors
+///
+/// Returns [`FpSignalError::KvWrite`] on non-CAS store errors or after
+/// exhausting all retries.
+pub fn write_fp_signals(
+    kv: &KvIdentityGraph,
+    ec_id: &str,
+    signals: &[FpSignal],
+    configs: &[FpSignalPartnerConfig],
+) -> Result<(), Report<FpSignalError>> {
+    let now = super::current_timestamp();
+
+    for attempt in 0..MAX_RETRIES {
+        let (mut entry, generation) =
+            match kv.get(ec_id).change_context(FpSignalError::KvWrite {
+                message: format!("Failed to read entry for key '{}…'", log_id(ec_id)),
+            })? {
+                Some(pair) => pair,
+                None => {
+                    log::debug!(
+                        "write_fp_signals: no entry for '{}…', skipping",
+                        log_id(ec_id)
+                    );
+                    return Ok(());
+                }
+            };
+
+        if !entry.consent.ok {
+            log::debug!(
+                "write_fp_signals: entry for '{}…' is a tombstone, skipping",
+                log_id(ec_id)
+            );
+            return Ok(());
+        }
+
+        let stale = filter_stale_signals(signals, &entry.ids, configs, now);
+        if stale.is_empty() {
+            return Ok(());
+        }
+
+        for signal in &stale {
+            entry.ids.insert(
+                signal.partner_id.clone(),
+                KvPartnerId {
+                    uid: signal.uid.clone(),
+                    synced: now,
+                },
+            );
+        }
+
+        match kv
+            .cas_write(ec_id, &entry, generation)
+            .change_context(FpSignalError::KvWrite {
+                message: format!("KV write failed for key '{}…'", log_id(ec_id)),
+            })? {
+            CasWriteOutcome::Ok => return Ok(()),
+            CasWriteOutcome::Conflict => {
+                log::debug!(
+                    "write_fp_signals: CAS conflict on attempt {}/{MAX_RETRIES} for '{}…', retrying",
+                    attempt + 1,
+                    log_id(ec_id),
+                );
+            }
+        }
+    }
+
+    Err(Report::new(FpSignalError::KvWrite {
+        message: format!(
+            "CAS conflict after {MAX_RETRIES} retries writing fp_signals for '{}…'",
+            log_id(ec_id)
+        ),
+    }))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use cookie::Cookie;
+
+    /// Builds a [`CookieJar`] from a list of `(name, value)` pairs.
+    fn jar_with(cookies: &[(&str, &str)]) -> CookieJar {
+        let mut jar = CookieJar::new();
+        for &(name, value) in cookies {
+            jar.add(Cookie::new(name.to_owned(), value.to_owned()));
+        }
+        jar
+    }
+
+    /// Builds a minimal [`FpSignalPartnerConfig`] with no JSON path.
+    fn raw_config(partner_id: &str, cookie_names: &[&str]) -> FpSignalPartnerConfig {
+        FpSignalPartnerConfig {
+            partner_id: partner_id.to_owned(),
+            cookie_names: cookie_names.iter().map(ToString::to_string).collect(),
+            json_path: None,
+            ttl_sec: 3600,
+        }
+    }
+
+    /// Builds a [`FpSignalPartnerConfig`] with a JSON path.
+    fn json_config(
+        partner_id: &str,
+        cookie_names: &[&str],
+        json_path: &str,
+    ) -> FpSignalPartnerConfig {
+        FpSignalPartnerConfig {
+            partner_id: partner_id.to_owned(),
+            cookie_names: cookie_names.iter().map(ToString::to_string).collect(),
+            json_path: Some(json_path.to_owned()),
+            ttl_sec: 3600,
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // filter_stale_signals tests
+    // -------------------------------------------------------------------------
+
+    /// Builds a minimal [`FpSignalPartnerConfig`] with a custom TTL.
+    fn config_with_ttl(partner_id: &str, ttl_sec: u64) -> FpSignalPartnerConfig {
+        FpSignalPartnerConfig {
+            partner_id: partner_id.to_owned(),
+            cookie_names: vec![],
+            json_path: None,
+            ttl_sec,
+        }
+    }
+
+    /// Builds a [`KvPartnerId`] with the given `synced` timestamp.
+    fn partner_id_synced(synced: u64) -> KvPartnerId {
+        KvPartnerId {
+            uid: "some_uid".to_owned(),
+            synced,
+        }
+    }
+
+    #[test]
+    fn filter_signals_skips_fresh_ids() {
+        // Arrange — signal synced 100s ago with 86400s TTL → still fresh
+        let signals = [FpSignal {
+            partner_id: "uid2".to_owned(),
+            uid: "tok_abc".to_owned(),
+        }];
+        let mut existing = HashMap::new();
+        existing.insert("uid2".to_owned(), partner_id_synced(1000));
+        let configs = [config_with_ttl("uid2", 86400)];
+        let now = 1100_u64;
+
+        // Act
+        let result = filter_stale_signals(&signals, &existing, &configs, now);
+
+        // Assert
+        assert!(
+            result.is_empty(),
+            "should skip signal with fresh existing id"
+        );
+    }
+
+    #[test]
+    fn filter_signals_includes_stale_ids() {
+        // Arrange — synced 100000s ago with 86400s TTL → stale
+        let signals = [FpSignal {
+            partner_id: "uid2".to_owned(),
+            uid: "tok_abc".to_owned(),
+        }];
+        let mut existing = HashMap::new();
+        existing.insert("uid2".to_owned(), partner_id_synced(1000));
+        let configs = [config_with_ttl("uid2", 86400)];
+        let now = 101_000_u64;
+
+        // Act
+        let result = filter_stale_signals(&signals, &existing, &configs, now);
+
+        // Assert
+        assert_eq!(result.len(), 1, "should include stale signal");
+        assert_eq!(
+            result[0].partner_id, "uid2",
+            "should include the stale uid2 signal"
+        );
+    }
+
+    #[test]
+    fn filter_signals_includes_new_ids() {
+        // Arrange — no existing entry for partner
+        let signals = [FpSignal {
+            partner_id: "liveramp".to_owned(),
+            uid: "ramp_123".to_owned(),
+        }];
+        let existing: HashMap<String, KvPartnerId> = HashMap::new();
+        let configs = [config_with_ttl("liveramp", 86400)];
+        let now = 50000_u64;
+
+        // Act
+        let result = filter_stale_signals(&signals, &existing, &configs, now);
+
+        // Assert
+        assert_eq!(
+            result.len(),
+            1,
+            "should include signal with no existing entry"
+        );
+        assert_eq!(
+            result[0].partner_id, "liveramp",
+            "should include the new liveramp signal"
+        );
+    }
+
+    #[test]
+    fn filter_signals_mixed_fresh_and_stale() {
+        // Arrange — uid2 fresh (synced 100s ago), liveramp stale (synced 100000s ago)
+        let signals = [
+            FpSignal {
+                partner_id: "uid2".to_owned(),
+                uid: "tok_uid2".to_owned(),
+            },
+            FpSignal {
+                partner_id: "liveramp".to_owned(),
+                uid: "ramp_stale".to_owned(),
+            },
+        ];
+        let now = 200_000_u64;
+        let mut existing = HashMap::new();
+        // uid2: synced at 199_900 → age 100s, TTL 86400s → fresh
+        existing.insert("uid2".to_owned(), partner_id_synced(199_900));
+        // liveramp: synced at 100_000 → age 100_000s, TTL 86400s → stale
+        existing.insert("liveramp".to_owned(), partner_id_synced(100_000));
+        let configs = [
+            config_with_ttl("uid2", 86400),
+            config_with_ttl("liveramp", 86400),
+        ];
+
+        // Act
+        let result = filter_stale_signals(&signals, &existing, &configs, now);
+
+        // Assert
+        assert_eq!(result.len(), 1, "should include only the stale signal");
+        assert_eq!(
+            result[0].partner_id, "liveramp",
+            "should include liveramp as the stale signal"
+        );
+    }
+
+    // -------------------------------------------------------------------------
+    // extract_json_path tests
+    // -------------------------------------------------------------------------
+
+    #[test]
+    fn extract_json_path_top_level_key() {
+        // Arrange
+        let json = r#"{"token": "abc123"}"#;
+
+        // Act
+        let result = extract_json_path(json, "token");
+
+        // Assert
+        assert_eq!(
+            result,
+            Some("abc123".to_owned()),
+            "should extract top-level string key"
+        );
+    }
+
+    #[test]
+    fn extract_json_path_nested_key() {
+        // Arrange
+        let json = r#"{"user": {"id": "nested_val"}}"#;
+
+        // Act
+        let result = extract_json_path(json, "user.id");
+
+        // Assert
+        assert_eq!(
+            result,
+            Some("nested_val".to_owned()),
+            "should extract nested string key"
+        );
+    }
+
+    #[test]
+    fn extract_json_path_missing_key() {
+        // Arrange
+        let json = r#"{"token": "abc123"}"#;
+
+        // Act
+        let result = extract_json_path(json, "missing");
+
+        // Assert
+        assert!(result.is_none(), "should return None for missing key");
+    }
+
+    #[test]
+    fn extract_json_path_non_string_leaf() {
+        // Arrange
+        let json = r#"{"count": 42}"#;
+
+        // Act
+        let result = extract_json_path(json, "count");
+
+        // Assert
+        assert!(result.is_none(), "should return None for non-string leaf");
+    }
+
+    #[test]
+    fn extract_json_path_invalid_json() {
+        // Arrange
+        let json = "not-json-at-all";
+
+        // Act
+        let result = extract_json_path(json, "token");
+
+        // Assert
+        assert!(result.is_none(), "should return None for invalid JSON");
+    }
+
+    #[test]
+    fn extract_json_path_empty_path() {
+        // Arrange
+        let json = r#"{"token": "abc123"}"#;
+
+        // Act
+        let result = extract_json_path(json, "");
+
+        // Assert
+        assert!(result.is_none(), "should return None for empty path");
+    }
+
+    #[test]
+    fn extract_json_path_partial_path() {
+        // Arrange — path partially valid but leaf is an object, not a string
+        let json = r#"{"user": {"id": "val"}}"#;
+
+        // Act
+        let result = extract_json_path(json, "user");
+
+        // Assert
+        assert!(
+            result.is_none(),
+            "should return None when leaf is an object, not a string"
+        );
+    }
+
+    // -------------------------------------------------------------------------
+    // extract_fp_signals tests
+    // -------------------------------------------------------------------------
+
+    #[test]
+    fn extract_fp_signals_raw_cookie_value() {
+        // Arrange
+        let jar = jar_with(&[("uid2_token", "raw_uid_value")]);
+        let configs = [raw_config("uid2", &["uid2_token"])];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, 0);
+
+        // Assert
+        assert_eq!(signals.len(), 1, "should extract one signal");
+        assert_eq!(
+            signals[0].partner_id, "uid2",
+            "should have correct partner_id"
+        );
+        assert_eq!(
+            signals[0].uid, "raw_uid_value",
+            "should use raw cookie value"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_json_cookie_value() {
+        // Arrange
+        let json = r#"{"advertising_token": "tok_abc"}"#;
+        let jar = jar_with(&[("uid2", json)]);
+        let configs = [json_config("uid2", &["uid2"], "advertising_token")];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, 0);
+
+        // Assert
+        assert_eq!(signals.len(), 1, "should extract one signal");
+        assert_eq!(
+            signals[0].uid, "tok_abc",
+            "should extract value at JSON path"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_first_match_wins() {
+        // Arrange — second cookie name would also match, but first takes precedence
+        let jar = jar_with(&[("cookie_a", "uid_from_a"), ("cookie_b", "uid_from_b")]);
+        let configs = [raw_config("partner1", &["cookie_a", "cookie_b"])];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, 0);
+
+        // Assert
+        assert_eq!(signals.len(), 1, "should extract exactly one signal");
+        assert_eq!(
+            signals[0].uid, "uid_from_a",
+            "should use first matching cookie"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_first_match_wins_skips_missing_first() {
+        // Arrange — first cookie name is absent; second should win
+        let jar = jar_with(&[("cookie_b", "uid_from_b")]);
+        let configs = [raw_config("partner1", &["cookie_a", "cookie_b"])];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, 0);
+
+        // Assert
+        assert_eq!(
+            signals.len(),
+            1,
+            "should fall through to second cookie name"
+        );
+        assert_eq!(
+            signals[0].uid, "uid_from_b",
+            "should use second cookie when first is absent"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_missing_cookie_skips() {
+        // Arrange
+        let jar = jar_with(&[]);
+        let configs = [raw_config("uid2", &["uid2_token"])];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, 0);
+
+        // Assert
+        assert!(
+            signals.is_empty(),
+            "should skip partner when cookie is absent"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_empty_uid_skips() {
+        // Arrange — cookie present but value is whitespace only
+        let jar = jar_with(&[("uid2_token", "   ")]);
+        let configs = [raw_config("uid2", &["uid2_token"])];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, 0);
+
+        // Assert
+        assert!(
+            signals.is_empty(),
+            "should skip signal with empty UID after trim"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_failed_json_path_skips() {
+        // Arrange — cookie is valid JSON but path doesn't exist
+        let jar = jar_with(&[("uid2", r#"{"other_key": "val"}"#)]);
+        let configs = [json_config("uid2", &["uid2"], "advertising_token")];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, 0);
+
+        // Assert
+        assert!(
+            signals.is_empty(),
+            "should skip when JSON path extraction fails"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_nested_json_path() {
+        // Arrange
+        let json = r#"{"user": {"advertising_token": "nested_tok"}}"#;
+        let jar = jar_with(&[("uid2", json)]);
+        let configs = [json_config("uid2", &["uid2"], "user.advertising_token")];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, 0);
+
+        // Assert
+        assert_eq!(signals.len(), 1, "should extract signal from nested path");
+        assert_eq!(signals[0].uid, "nested_tok", "should use nested JSON value");
+    }
+
+    #[test]
+    fn extract_fp_signals_multiple_partners() {
+        // Arrange
+        let json = r#"{"advertising_token": "uid2_tok"}"#;
+        let jar = jar_with(&[("uid2_cookie", json), ("ramp_cookie", "ramp_raw_id")]);
+        let configs = [
+            json_config("uid2", &["uid2_cookie"], "advertising_token"),
+            raw_config("liveramp", &["ramp_cookie"]),
+        ];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, 0);
+
+        // Assert
+        assert_eq!(signals.len(), 2, "should extract one signal per partner");
+        assert_eq!(
+            signals[0].partner_id, "uid2",
+            "should have uid2 as first partner"
+        );
+        assert_eq!(
+            signals[0].uid, "uid2_tok",
+            "should extract uid2 advertising_token"
+        );
+        assert_eq!(
+            signals[1].partner_id, "liveramp",
+            "should have liveramp as second partner"
+        );
+        assert_eq!(
+            signals[1].uid, "ramp_raw_id",
+            "should use raw ramp cookie value"
+        );
+    }
+
+    // -------------------------------------------------------------------------
+    // UID2 expiry tests
+    // -------------------------------------------------------------------------
+
+    #[test]
+    fn extract_fp_signals_uid2_valid_token_extracted() {
+        // Arrange — token expires more than 5 minutes from now
+        let now_ms = 1_700_000_000_000_u64;
+        let expires_ms = now_ms + 600_000;
+        let json =
+            format!(r#"{{"advertising_token": "tok_valid", "identity_expires": {expires_ms}}}"#);
+        let jar = jar_with(&[("uid2_cookie", &json)]);
+        let configs = [json_config("uid2", &["uid2_cookie"], "advertising_token")];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, now_ms);
+
+        // Assert
+        assert_eq!(signals.len(), 1, "should extract valid UID2 token");
+        assert_eq!(
+            signals[0].uid, "tok_valid",
+            "should use advertising_token from valid entry"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_uid2_expired_token_skipped() {
+        // Arrange — token expires less than 5 minutes from now
+        let now_ms = 1_700_000_000_000_u64;
+        let expires_ms = now_ms + 100_000;
+        let json =
+            format!(r#"{{"advertising_token": "tok_expired", "identity_expires": {expires_ms}}}"#);
+        let jar = jar_with(&[("uid2_cookie", &json)]);
+        let configs = [json_config("uid2", &["uid2_cookie"], "advertising_token")];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, now_ms);
+
+        // Assert
+        assert!(signals.is_empty(), "should skip expired UID2 token");
+    }
+
+    #[test]
+    fn extract_fp_signals_uid2_expiry_at_boundary_skipped() {
+        // Arrange — token expires exactly at the 5-minute boundary (identity_expires == now_ms + 300_000)
+        // The check is `<=`, so this should be skipped.
+        let now_ms = 1_700_000_000_000_u64;
+        let expires_ms = now_ms + 300_000;
+        let json =
+            format!(r#"{{"advertising_token": "tok_boundary", "identity_expires": {expires_ms}}}"#);
+        let jar = jar_with(&[("uid2_cookie", &json)]);
+        let configs = [json_config("uid2", &["uid2_cookie"], "advertising_token")];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, now_ms);
+
+        // Assert
+        assert!(
+            signals.is_empty(),
+            "should skip token at exact 5-minute boundary"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_uid2_expiry_just_above_boundary_extracted() {
+        // Arrange — token expires one millisecond above the 5-minute boundary
+        // (identity_expires == now_ms + 300_001); should be extracted.
+        let now_ms = 1_700_000_000_000_u64;
+        let expires_ms = now_ms + 300_001;
+        let json = format!(
+            r#"{{"advertising_token": "tok_just_valid", "identity_expires": {expires_ms}}}"#
+        );
+        let jar = jar_with(&[("uid2_cookie", &json)]);
+        let configs = [json_config("uid2", &["uid2_cookie"], "advertising_token")];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, now_ms);
+
+        // Assert
+        assert_eq!(
+            signals.len(),
+            1,
+            "should extract token just above the 5-minute boundary"
+        );
+        assert_eq!(
+            signals[0].uid, "tok_just_valid",
+            "should use advertising_token from just-valid entry"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_non_uid2_json_without_expiry_extracted() {
+        // Arrange — JSON cookie without `identity_expires` is not a UID2 token;
+        // expiry check is skipped and the value is extracted normally.
+        let now_ms = 1_700_000_000_000_u64;
+        let json = r#"{"id": "non_uid2_value"}"#;
+        let jar = jar_with(&[("partner_cookie", json)]);
+        let configs = [json_config("partner", &["partner_cookie"], "id")];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, now_ms);
+
+        // Assert
+        assert_eq!(
+            signals.len(),
+            1,
+            "should extract non-UID2 JSON cookie normally"
+        );
+        assert_eq!(
+            signals[0].uid, "non_uid2_value",
+            "should use extracted JSON value"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_skips_uid_exceeding_max_length() {
+        // Arrange — cookie value exceeds MAX_UID_LENGTH (512 bytes)
+        let long_uid = "x".repeat(MAX_UID_LENGTH + 1);
+        let jar = jar_with(&[("partner_cookie", &long_uid)]);
+        let configs = [raw_config("partner", &["partner_cookie"])];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, 0);
+
+        // Assert
+        assert!(
+            signals.is_empty(),
+            "should skip signal with UID exceeding MAX_UID_LENGTH"
+        );
+    }
+
+    #[test]
+    fn extract_fp_signals_accepts_uid_at_max_length() {
+        // Arrange — cookie value is exactly MAX_UID_LENGTH (512 bytes)
+        let uid = "x".repeat(MAX_UID_LENGTH);
+        let jar = jar_with(&[("partner_cookie", &uid)]);
+        let configs = [raw_config("partner", &["partner_cookie"])];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, 0);
+
+        // Assert
+        assert_eq!(
+            signals.len(),
+            1,
+            "should accept signal at exactly MAX_UID_LENGTH"
+        );
+        assert_eq!(signals[0].uid, uid, "should use the full UID value");
+    }
+
+    #[test]
+    fn extract_fp_signals_raw_config_with_expired_identity_expires_skipped() {
+        // Arrange — a partner with json_path: None whose cookie value happens to be
+        // valid JSON containing an expired `identity_expires`. The expiry check runs
+        // on any parseable JSON with that field, regardless of json_path config.
+        let now_ms = 1_700_000_000_000_u64;
+        let expires_ms = now_ms + 100_000;
+        let json = format!(r#"{{"identity_expires": {expires_ms}, "some_id": "raw_id"}}"#);
+        let jar = jar_with(&[("partner_cookie", &json)]);
+        let configs = [raw_config("partner", &["partner_cookie"])];
+
+        // Act
+        let signals = extract_fp_signals(&jar, &configs, now_ms);
+
+        // Assert
+        assert!(
+            signals.is_empty(),
+            "should skip raw-config partner when cookie JSON has expired identity_expires"
+        );
+    }
+}
diff --git a/crates/trusted-server-core/src/ec/kv.rs b/crates/trusted-server-core/src/ec/kv.rs
index 0d242460..2bcbfee7 100644
--- a/crates/trusted-server-core/src/ec/kv.rs
+++ b/crates/trusted-server-core/src/ec/kv.rs
@@ -60,6 +60,15 @@ pub enum UpsertResult {
 
 use super::log_id;
 
+/// Outcome of a [`KvIdentityGraph::cas_write`] attempt.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CasWriteOutcome {
+    /// Write succeeded.
+    Ok,
+    /// Generation mismatch — caller should re-read and retry.
+    Conflict,
+}
+
 /// Wraps a Fastly KV Store for EC identity graph operations.
 ///
 /// Each EC ID (`{64hex}.{6alnum}`) maps to a JSON-encoded [`KvEntry`]
@@ -842,6 +851,45 @@ impl KvIdentityGraph {
         Ok(Some(cluster_size))
     }
 
+    /// CAS-writes a full entry using the given generation marker.
+    ///
+    /// Returns [`CasWriteOutcome::Ok`] on success, or
+    /// [`CasWriteOutcome::Conflict`] when the generation does not match —
+    /// the caller should re-read and retry.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on serialization or store failure
+    /// (not on generation mismatch — that is [`CasWriteOutcome::Conflict`]).
+    pub fn cas_write(
+        &self,
+        ec_id: &str,
+        entry: &KvEntry,
+        generation: u64,
+    ) -> Result<CasWriteOutcome, Report<TrustedServerError>> {
+        let store = self.open_store()?;
+        let (body, meta_str) = Self::serialize_entry(entry, &self.store_name)?;
+
+        match store
+            .build_insert()
+            .if_generation_match(generation)
+            .metadata(&meta_str)
+            .time_to_live(ENTRY_TTL)
+            .execute(ec_id, body.as_str())
+        {
+            Ok(()) => Ok(CasWriteOutcome::Ok),
+            Err(fastly::kv_store::KVStoreError::ItemPreconditionFailed) => {
+                Ok(CasWriteOutcome::Conflict)
+            }
+            Err(err) => Err(
+                Report::new(err).change_context(TrustedServerError::KvStore {
+                    store_name: self.store_name.clone(),
+                    message: format!("CAS write failed for key '{ec_id}'"),
+                }),
+            ),
+        }
+    }
+
     /// Hard-deletes the entry.
     ///
     /// Reserved for the IAB data deletion framework (deferred). For consent
diff --git a/crates/trusted-server-core/src/ec/mod.rs b/crates/trusted-server-core/src/ec/mod.rs
index d8d60287..18c13b82 100644
--- a/crates/trusted-server-core/src/ec/mod.rs
+++ b/crates/trusted-server-core/src/ec/mod.rs
@@ -26,6 +26,7 @@
 //! - [`eids`] — Shared EID resolution and formatting helpers
 //! - [`batch_sync`] — S2S batch sync endpoint (`POST /_ts/api/v1/batch-sync`)
 //! - [`pull_sync`] — Background pull-sync dispatcher for organic routes
+//! - [`fp_signals`] — First-party signal extraction from browser cookies
 
 pub mod admin;
 pub mod batch_sync;
@@ -34,6 +35,7 @@ pub mod cookies;
 pub mod device;
 pub mod eids;
 pub mod finalize;
+pub mod fp_signals;
 pub mod generation;
 pub mod identify;
 pub mod kv;
@@ -158,6 +160,9 @@ pub struct EcContext {
     /// Set via [`EcContext::set_device_signals`] before
     /// [`EcContext::generate_if_needed`] is called.
     device_signals: Option<DeviceSignals>,
+    /// The parsed cookie jar from the incoming request.
+    /// Retained for first-party signal extraction in the post-EC phase.
+    cookie_jar: Option<CookieJar>,
 }
 
 impl EcContext {
@@ -234,6 +239,7 @@ impl EcContext {
             client_ip,
             geo_info: geo_info.cloned(),
             device_signals: None,
+            cookie_jar: parsed.jar,
         })
     }
 
@@ -378,6 +384,15 @@ impl EcContext {
         consent::ec_consent_granted(&self.consent)
     }
 
+    /// Returns a reference to the parsed cookie jar from the incoming request.
+    ///
+    /// Used by first-party signal extraction to read partner cookies without
+    /// re-parsing the `Cookie` header.
+    #[must_use]
+    pub fn cookie_jar(&self) -> Option<&CookieJar> {
+        self.cookie_jar.as_ref()
+    }
+
     /// Returns the existing EC cookie value for revocation handling.
     ///
     /// When consent is withdrawn, this value is needed to identify the
@@ -417,6 +432,7 @@ impl EcContext {
             client_ip: None,
             geo_info: None,
             device_signals: None,
+            cookie_jar: None,
         }
     }
 
@@ -437,6 +453,7 @@ impl EcContext {
             client_ip,
             geo_info: None,
             device_signals: None,
+            cookie_jar: None,
         }
     }
 
@@ -460,6 +477,7 @@ impl EcContext {
             client_ip: None,
             geo_info: None,
             device_signals: None,
+            cookie_jar: None,
         }
     }
 }
@@ -477,6 +495,21 @@ pub(crate) fn current_timestamp() -> u64 {
         })
 }
 
+/// Returns the current Unix timestamp in milliseconds.
+///
+/// Uses `std::time::SystemTime` which is supported on `wasm32-wasip1`.
+/// The `as u64` narrowing from `u128` is safe for ~584 million years.
+#[must_use]
+pub fn current_timestamp_ms() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_millis() as u64)
+        .unwrap_or_else(|err| {
+            log::error!("SystemTime::now() failed, falling back to epoch 0: {err}");
+            0
+        })
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/crates/trusted-server-core/src/ec/partner.rs b/crates/trusted-server-core/src/ec/partner.rs
index 40b42eba..93e9c022 100644
--- a/crates/trusted-server-core/src/ec/partner.rs
+++ b/crates/trusted-server-core/src/ec/partner.rs
@@ -1,13 +1,17 @@
 //! Partner registry — `PartnerRecord` schema and `PartnerStore` operations.
 //!
 //! Each partner (SSP, DSP, identity vendor) is stored as a JSON record in
-//! the Fastly KV Store keyed by `partner_id`. Two secondary indexes exist:
+//! the Fastly KV Store keyed by `partner_id`. Three secondary indexes exist:
 //!
 //! - `apikey:{sha256_hex}` — maps API key hashes to partner IDs for O(1)
 //!   auth lookups during batch sync.
 //! - `_pull_enabled` — JSON array of partner IDs with `pull_sync_enabled:
 //!   true`, enabling O(1+N) reads on the pull sync hot path instead of a
 //!   full partner scan.
+//! - `_fp_signal_enabled` — JSON array of partner configs for partners
+//!   with at least one `fp_signal_cookie_names` entry, enabling O(1+N)
+//!   reads for first-party signal collection config without a full
+//!   partner scan.
 
 use std::{collections::HashSet, sync::OnceLock};
 
@@ -46,6 +50,14 @@ const APIKEY_INDEX_PREFIX: &str = "apikey:";
 /// a single index key instead of listing/scanning all partners.
 const PULL_ENABLED_INDEX_KEY: &str = "_pull_enabled";
 
+/// Key for the FP-signal-enabled partner secondary index.
+///
+/// Stores a JSON array of [`super::fp_signals::FpSignalPartnerConfig`] for
+/// partners with at least one `fp_signal_cookie_names` entry. Updated on
+/// every `upsert()` so that `fp_signal_configs()` can read a single key
+/// instead of scanning all partners.
+const FP_SIGNAL_INDEX_KEY: &str = "_fp_signal_enabled";
+
 /// Cached compiled regex for partner ID validation.
 static PARTNER_ID_REGEX: OnceLock<Result<Regex, String>> = OnceLock::new();
 
@@ -112,6 +124,24 @@ pub struct PartnerRecord {
     /// send to us, so it only needs hash verification.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub ts_pull_token: Option<String>,
+    /// First-party cookie names that may carry this partner's UID.
+    /// Checked in order; first match wins.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub fp_signal_cookie_names: Vec<String>,
+    /// Dot-notation JSON path to extract the UID from a JSON cookie
+    /// value. When `None`, the raw cookie value is used.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub fp_signal_json_path: Option<String>,
+    /// Minimum seconds between re-collection writes for this partner.
+    /// Defaults to 86400 (24 hours).
+    #[serde(default = "PartnerRecord::default_fp_signal_ttl_sec")]
+    pub fp_signal_ttl_sec: u64,
+}
+
+impl PartnerRecord {
+    fn default_fp_signal_ttl_sec() -> u64 {
+        86400
+    }
 }
 
 /// Validates a partner ID format and checks against reserved names.
@@ -198,6 +228,92 @@ pub fn validate_pull_sync_config(record: &PartnerRecord) -> Result<(), String> {
     Ok(())
 }
 
+/// Validates first-party signal configuration fields on a [`PartnerRecord`].
+///
+/// If `fp_signal_cookie_names` is empty, all FP signal fields are ignored
+/// and validation always succeeds. When cookie names are present the
+/// following rules apply:
+///
+/// - At most 5 cookie names.
+/// - Each cookie name must be non-empty, contain only ASCII characters, and
+///   must not contain `;` or `=` (reserved in the Cookie header spec).
+/// - If `fp_signal_json_path` is `Some`, it must be non-empty, contain only
+///   alphanumeric characters, `.`, or `_`, and have at most 4 dot-separated
+///   segments.
+/// - `fp_signal_ttl_sec` must be between 60 and 604800 (7 days) inclusive.
+///
+/// # Errors
+///
+/// Returns a descriptive error string on validation failure.
+pub fn validate_fp_signal_config(record: &PartnerRecord) -> Result<(), String> {
+    if record.fp_signal_cookie_names.is_empty() {
+        return Ok(());
+    }
+
+    const MAX_COOKIE_NAMES: usize = 5;
+    if record.fp_signal_cookie_names.len() > MAX_COOKIE_NAMES {
+        return Err(format!(
+            "fp_signal_cookie_names must have at most {MAX_COOKIE_NAMES} entries, got {}",
+            record.fp_signal_cookie_names.len()
+        ));
+    }
+
+    const MAX_COOKIE_NAME_LENGTH: usize = 128;
+    for name in &record.fp_signal_cookie_names {
+        if name.is_empty() {
+            return Err("fp_signal_cookie_names entries must not be empty".to_owned());
+        }
+        if name.len() > MAX_COOKIE_NAME_LENGTH {
+            return Err(format!(
+                "fp_signal_cookie_names entry must be at most {MAX_COOKIE_NAME_LENGTH} characters, got {}",
+                name.len()
+            ));
+        }
+        if !name.is_ascii() {
+            return Err(format!(
+                "fp_signal_cookie_names entry '{name}' must contain only ASCII characters"
+            ));
+        }
+        if name.contains(';') || name.contains('=') {
+            return Err(format!(
+                "fp_signal_cookie_names entry '{name}' must not contain ';' or '='"
+            ));
+        }
+    }
+
+    if let Some(path) = &record.fp_signal_json_path {
+        if path.is_empty() {
+            return Err("fp_signal_json_path must not be empty when present".to_owned());
+        }
+        if !path
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_')
+        {
+            return Err(format!(
+                "fp_signal_json_path '{path}' must contain only alphanumeric characters, '.', or '_'"
+            ));
+        }
+        let segment_count = path.split('.').count();
+        const MAX_SEGMENTS: usize = 4;
+        if segment_count > MAX_SEGMENTS {
+            return Err(format!(
+                "fp_signal_json_path '{path}' must have at most {MAX_SEGMENTS} dot-separated segments, got {segment_count}"
+            ));
+        }
+    }
+
+    const MIN_TTL: u64 = 60;
+    const MAX_TTL: u64 = 604_800;
+    if record.fp_signal_ttl_sec < MIN_TTL || record.fp_signal_ttl_sec > MAX_TTL {
+        return Err(format!(
+            "fp_signal_ttl_sec must be between {MIN_TTL} and {MAX_TTL}, got {}",
+            record.fp_signal_ttl_sec
+        ));
+    }
+
+    Ok(())
+}
+
 /// Computes the SHA-256 hex digest of an API key.
 #[must_use]
 pub fn hash_api_key(api_key: &str) -> String {
@@ -208,13 +324,16 @@ pub fn hash_api_key(api_key: &str) -> String {
 
 /// Wraps a Fastly KV Store for partner registry operations.
 ///
-/// Partner records are keyed by `partner_id`. Two secondary indexes
+/// Partner records are keyed by `partner_id`. Three secondary indexes
 /// optimize hot-path operations:
 ///
 /// - `apikey:{sha256_hex}` maps API key hashes to partner IDs for
 ///   O(1) auth lookups during batch sync.
 /// - `_pull_enabled` stores a JSON array of partner IDs with
 ///   `pull_sync_enabled: true` for O(1+N) reads during pull sync dispatch.
+/// - `_fp_signal_enabled` stores a JSON array of partner configs for
+///   partners with at least one `fp_signal_cookie_names` entry for
+///   O(1+N) reads during first-party signal collection.
 pub struct PartnerStore {
     store_name: String,
 }
@@ -311,7 +430,10 @@ impl PartnerStore {
             })?;
 
             for key in page.keys() {
-                if key.starts_with(APIKEY_INDEX_PREFIX) || key == PULL_ENABLED_INDEX_KEY {
+                if key.starts_with(APIKEY_INDEX_PREFIX)
+                    || key == PULL_ENABLED_INDEX_KEY
+                    || key == FP_SIGNAL_INDEX_KEY
+                {
                     continue;
                 }
 
@@ -514,6 +636,9 @@ impl PartnerStore {
         //    `list_registered()` if the index is missing or stale.
         self.update_pull_enabled_index(&store, &record.id, record.pull_sync_enabled);
 
+        // 5. Update _fp_signal_enabled secondary index (best-effort).
+        self.update_fp_signal_index(&store, record);
+
         Ok(is_create)
     }
 
@@ -609,6 +734,90 @@ impl PartnerStore {
         }
     }
 
+    /// Best-effort update of the `_fp_signal_enabled` secondary index.
+    ///
+    /// Reads the current index, replaces the entry for `record.id`, and
+    /// writes it back. If `fp_signal_cookie_names` is empty the partner is
+    /// removed from the index. All errors are logged and swallowed — the
+    /// primary record write has already succeeded.
+    fn update_fp_signal_index(&self, store: &KVStore, record: &PartnerRecord) {
+        // Read existing index (or start with empty list).
+        let mut configs: Vec<super::fp_signals::FpSignalPartnerConfig> =
+            match store.lookup(FP_SIGNAL_INDEX_KEY) {
+                Ok(mut resp) => {
+                    let bytes = resp.take_body_bytes();
+                    serde_json::from_slice(&bytes).unwrap_or_else(|err| {
+                        log::warn!("Failed to deserialize fp-signal index, starting fresh: {err}");
+                        Vec::new()
+                    })
+                }
+                Err(_) => Vec::new(),
+            };
+
+        // Remove any existing entry for this partner.
+        configs.retain(|c| c.partner_id != record.id);
+
+        // Re-add if partner has cookie names configured.
+        if !record.fp_signal_cookie_names.is_empty() {
+            configs.push(super::fp_signals::FpSignalPartnerConfig {
+                partner_id: record.id.clone(),
+                cookie_names: record.fp_signal_cookie_names.clone(),
+                json_path: record.fp_signal_json_path.clone(),
+                ttl_sec: record.fp_signal_ttl_sec,
+            });
+        }
+
+        let body = match serde_json::to_string(&configs) {
+            Ok(b) => b,
+            Err(err) => {
+                log::warn!(
+                    "Failed to serialize fp-signal index after updating partner '{}': {err}",
+                    record.id
+                );
+                return;
+            }
+        };
+
+        if let Err(err) = store.build_insert().execute(FP_SIGNAL_INDEX_KEY, body) {
+            log::warn!(
+                "Failed to write fp-signal index after updating partner '{}': {err:?}",
+                record.id
+            );
+        }
+    }
+
+    /// Returns FP-signal-enabled partner configs via the `_fp_signal_enabled`
+    /// secondary index.
+    ///
+    /// Returns an empty [`Vec`] when the index is missing or corrupt rather
+    /// than propagating an error, matching the best-effort semantics of the
+    /// index itself.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] if the store cannot be opened.
+    pub fn fp_signal_configs(
+        &self,
+    ) -> Result<Vec<super::fp_signals::FpSignalPartnerConfig>, Report<TrustedServerError>> {
+        let store = self.open_store()?;
+
+        let index_body = match store.lookup(FP_SIGNAL_INDEX_KEY) {
+            Ok(mut resp) => resp.take_body_bytes(),
+            Err(fastly::kv_store::KVStoreError::ItemNotFound) => return Ok(Vec::new()),
+            Err(err) => {
+                log::warn!("Failed to read fp-signal index: {err:?}");
+                return Ok(Vec::new());
+            }
+        };
+
+        let configs = serde_json::from_slice(&index_body).unwrap_or_else(|err| {
+            log::warn!("Failed to deserialize fp-signal index, returning empty: {err}");
+            Vec::new()
+        });
+
+        Ok(configs)
+    }
+
     fn restore_previous_index_mapping(
         &self,
         store: &KVStore,
@@ -726,6 +935,9 @@ mod tests {
             pull_sync_ttl_sec: 86400,
             pull_sync_rate_limit: 10,
             ts_pull_token: None,
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
         };
 
         let json = serde_json::to_string(&record).expect("should serialize");
@@ -827,6 +1039,9 @@ mod tests {
             pull_sync_ttl_sec: 86400,
             pull_sync_rate_limit: 10,
             ts_pull_token: None,
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
         };
         assert!(validate_pull_sync_config(&record).is_ok());
     }
@@ -849,6 +1064,9 @@ mod tests {
             pull_sync_ttl_sec: 86400,
             pull_sync_rate_limit: 10,
             ts_pull_token: Some("token".to_owned()),
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
         };
         let err = validate_pull_sync_config(&record).unwrap_err();
         assert!(err.contains("pull_sync_url"), "got: {err}");
@@ -872,6 +1090,9 @@ mod tests {
             pull_sync_ttl_sec: 86400,
             pull_sync_rate_limit: 10,
             ts_pull_token: None,
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
         };
         let err = validate_pull_sync_config(&record).unwrap_err();
         assert!(err.contains("ts_pull_token"), "got: {err}");
@@ -895,6 +1116,9 @@ mod tests {
             pull_sync_ttl_sec: 86400,
             pull_sync_rate_limit: 10,
             ts_pull_token: Some("token".to_owned()),
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
         };
         let err = validate_pull_sync_config(&record).unwrap_err();
         assert!(
@@ -921,6 +1145,9 @@ mod tests {
             pull_sync_ttl_sec: 86400,
             pull_sync_rate_limit: 10,
             ts_pull_token: Some("token".to_owned()),
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
         };
         let err = validate_pull_sync_config(&record).unwrap_err();
         assert!(err.contains("pull_sync_allowed_domains"), "got: {err}");
@@ -944,6 +1171,9 @@ mod tests {
             pull_sync_ttl_sec: 86400,
             pull_sync_rate_limit: 10,
             ts_pull_token: Some("token".to_owned()),
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
         };
         assert!(validate_pull_sync_config(&record).is_ok());
     }
@@ -966,6 +1196,9 @@ mod tests {
             pull_sync_ttl_sec: 86400,
             pull_sync_rate_limit: 10,
             ts_pull_token: None,
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
         };
         let json = serde_json::to_string(&record).expect("should serialize");
         assert!(
@@ -980,5 +1213,125 @@ mod tests {
             !json.contains("pull_sync_allowed_domains"),
             "empty pull_sync_allowed_domains should be omitted"
         );
+        assert!(
+            !json.contains("fp_signal_cookie_names"),
+            "empty fp_signal_cookie_names should be omitted"
+        );
+        assert!(
+            !json.contains("fp_signal_json_path"),
+            "None fp_signal_json_path should be omitted"
+        );
+    }
+
+    fn base_fp_signal_record() -> PartnerRecord {
+        PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+            fp_signal_cookie_names: vec!["uid2_token".to_owned()],
+            fp_signal_json_path: Some("advertising_token".to_owned()),
+            fp_signal_ttl_sec: 86400,
+        }
+    }
+
+    #[test]
+    fn validate_fp_signal_config_accepts_valid() {
+        let record = base_fp_signal_record();
+        assert!(
+            validate_fp_signal_config(&record).is_ok(),
+            "should accept valid FP signal config"
+        );
+    }
+
+    #[test]
+    fn validate_fp_signal_config_ok_when_empty() {
+        let mut record = base_fp_signal_record();
+        record.fp_signal_cookie_names = vec![];
+        assert!(
+            validate_fp_signal_config(&record).is_ok(),
+            "should accept empty cookie names without validating other fields"
+        );
+    }
+
+    #[test]
+    fn validate_fp_signal_rejects_empty_cookie_name() {
+        let mut record = base_fp_signal_record();
+        record.fp_signal_cookie_names = vec!["valid_cookie".to_owned(), String::new()];
+        let err = validate_fp_signal_config(&record).expect_err("should reject empty cookie name");
+        assert!(
+            err.contains("must not be empty"),
+            "should mention empty entry, got: {err}"
+        );
+    }
+
+    #[test]
+    fn validate_fp_signal_rejects_too_many_cookie_names() {
+        let mut record = base_fp_signal_record();
+        record.fp_signal_cookie_names = (0..6).map(|i| format!("cookie_{i}")).collect();
+        let err = validate_fp_signal_config(&record).expect_err("should reject 6 cookie names");
+        assert!(
+            err.contains("at most 5"),
+            "should mention 5-entry limit, got: {err}"
+        );
+    }
+
+    #[test]
+    fn validate_fp_signal_rejects_cookie_name_with_semicolon() {
+        let mut record = base_fp_signal_record();
+        record.fp_signal_cookie_names = vec!["bad;name".to_owned()];
+        let err = validate_fp_signal_config(&record)
+            .expect_err("should reject cookie name with semicolon");
+        assert!(
+            err.contains("';'"),
+            "should mention forbidden character, got: {err}"
+        );
+    }
+
+    #[test]
+    fn validate_fp_signal_rejects_ttl_too_low() {
+        let mut record = base_fp_signal_record();
+        record.fp_signal_ttl_sec = 10;
+        let err = validate_fp_signal_config(&record).expect_err("should reject TTL of 10");
+        assert!(
+            err.contains("fp_signal_ttl_sec"),
+            "should mention ttl field, got: {err}"
+        );
+    }
+
+    #[test]
+    fn validate_fp_signal_rejects_invalid_json_path() {
+        let mut record = base_fp_signal_record();
+        // "a.b.c.d.e" has 5 segments — exceeds max of 4.
+        record.fp_signal_json_path = Some("a.b.c.d.e".to_owned());
+        let err = validate_fp_signal_config(&record)
+            .expect_err("should reject json path with 5 segments");
+        assert!(
+            err.contains("at most 4"),
+            "should mention 4-segment limit, got: {err}"
+        );
+    }
+
+    #[test]
+    fn validate_fp_signal_rejects_cookie_name_too_long() {
+        let mut record = base_fp_signal_record();
+        record.fp_signal_cookie_names = vec!["x".repeat(129)];
+        let err = validate_fp_signal_config(&record)
+            .expect_err("should reject cookie name exceeding 128 chars");
+        assert!(
+            err.contains("at most 128"),
+            "should mention 128-char limit, got: {err}"
+        );
     }
 }
diff --git a/crates/trusted-server-core/src/ec/pull_sync.rs b/crates/trusted-server-core/src/ec/pull_sync.rs
index b1edef75..c2cf0e37 100644
--- a/crates/trusted-server-core/src/ec/pull_sync.rs
+++ b/crates/trusted-server-core/src/ec/pull_sync.rs
@@ -381,6 +381,9 @@ mod tests {
             pull_sync_ttl_sec: ttl_sec,
             pull_sync_rate_limit: 20,
             ts_pull_token: Some("token".to_owned()),
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
         }
     }
 
diff --git a/crates/trusted-server-core/src/ec/sync_pixel.rs b/crates/trusted-server-core/src/ec/sync_pixel.rs
index 47e43de5..df81bafd 100644
--- a/crates/trusted-server-core/src/ec/sync_pixel.rs
+++ b/crates/trusted-server-core/src/ec/sync_pixel.rs
@@ -358,6 +358,9 @@ mod tests {
             pull_sync_ttl_sec: 86400,
             pull_sync_rate_limit: 10,
             ts_pull_token: None,
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
         }
     }
 
diff --git a/docs/superpowers/plans/2026-04-09-first-party-signal-collection.md b/docs/superpowers/plans/2026-04-09-first-party-signal-collection.md
new file mode 100644
index 00000000..27c26371
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-09-first-party-signal-collection.md
@@ -0,0 +1,1816 @@
+# First-Party Signal Collection Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Harvest partner UIDs from first-party cookies on Chrome requests and write them to the KV identity graph so Safari/Firefox household members arrive with a fully populated entry.
+
+**Architecture:** Core crate exposes `extract_fp_signals()` (pure, pre-send) and `write_fp_signals()` (batched CAS, post-send). Adapter orchestrates timing: extraction during request handling, writing after response is sent. New `_fp_signal_enabled` denormalized index on `PartnerStore` provides all partner configs in a single KV read.
+
+**Tech Stack:** Rust (2024 edition), `serde_json` for JSON path walking, `cookie::CookieJar` for cookie access, Fastly KV Store for persistence, `error-stack` for error handling.
+
+---
+
+## File Structure
+
+| File                                               | Responsibility                                                                                                                                                                                                                                     |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `crates/trusted-server-core/src/ec/fp_signals.rs`  | **New.** Types (`FpSignalPartnerConfig`, `FpSignal`, `FpSignalError`), extraction logic, JSON path walker, batched CAS write, all unit tests.                                                                                                      |
+| `crates/trusted-server-core/src/ec/mod.rs`         | Declare `pub mod fp_signals`. Add `cookie_jar` field to `EcContext`, store it during `read_from_request_with_geo`, expose via `cookie_jar()` accessor.                                                                                             |
+| `crates/trusted-server-core/src/ec/partner.rs`     | Add 3 FP signal fields to `PartnerRecord`. Add `FP_SIGNAL_INDEX_KEY` constant. Add `fp_signal_configs()` accessor. Add `update_fp_signal_index()` and call it from `upsert()`. Skip new index key in `list_registered()`. Add validation function. |
+| `crates/trusted-server-core/src/ec/admin.rs`       | Add 3 FP signal fields to `RegisterPartnerRequest`. Wire them into `PartnerRecord` construction and validation.                                                                                                                                    |
+| `crates/trusted-server-adapter-fastly/src/main.rs` | Expand `RouteOutcome` to carry `fp_signals` and `fp_signal_configs`. Extract signals pre-send. Write signals post-send via `run_fp_signal_collection_after_send()`.                                                                                |
+
+---
+
+### Task 1: Add `FpSignalPartnerConfig` and `FpSignal` types
+
+**Files:**
+
+- Create: `crates/trusted-server-core/src/ec/fp_signals.rs`
+- Modify: `crates/trusted-server-core/src/ec/mod.rs:30-43`
+
+- [ ] **Step 1: Create `fp_signals.rs` with types and error**
+
+Create `crates/trusted-server-core/src/ec/fp_signals.rs`:
+
+```rust
+//! First-party signal collection.
+//!
+//! Harvests partner UIDs from first-party cookies on incoming requests
+//! and writes them to the KV identity graph in a single batched CAS
+//! operation. Extraction runs pre-send (cheap string ops); writing runs
+//! post-send (KV I/O off the critical path).
+
+use serde::{Deserialize, Serialize};
+
+/// Denormalized per-partner extraction config stored in the
+/// `_fp_signal_enabled` KV index.
+///
+/// Contains everything needed to extract a partner UID from the cookie
+/// jar without reading the full [`super::partner::PartnerRecord`].
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct FpSignalPartnerConfig {
+    /// Partner identifier (matches [`super::partner::PartnerRecord::id`]).
+    pub partner_id: String,
+    /// Cookie names to check, in priority order. First match wins.
+    pub cookie_names: Vec<String>,
+    /// Dot-notation JSON path to extract the UID from a JSON cookie
+    /// value. When `None`, the raw cookie value is used.
+    pub json_path: Option<String>,
+    /// Minimum seconds between re-collection writes for this partner.
+    pub ttl_sec: u64,
+}
+
+/// A partner UID extracted from a first-party cookie.
+///
+/// Produced by [`extract_fp_signals`] pre-send and consumed by
+/// [`write_fp_signals`] post-send.
+#[derive(Debug, Clone, PartialEq)]
+pub struct FpSignal {
+    /// Partner identifier.
+    pub partner_id: String,
+    /// The extracted UID value.
+    pub uid: String,
+}
+
+/// Errors specific to first-party signal collection.
+#[derive(Debug, derive_more::Display)]
+pub enum FpSignalError {
+    /// KV store operation failed during batched write.
+    #[display("KV write failed: {message}")]
+    KvWrite { message: String },
+}
+
+impl core::error::Error for FpSignalError {}
+```
+
+- [ ] **Step 2: Declare the module in `ec/mod.rs`**
+
+In `crates/trusted-server-core/src/ec/mod.rs`, add after `pub mod pull_sync;` (line 42):
+
+```rust
+pub mod fp_signals;
+```
+
+- [ ] **Step 3: Verify compilation**
+
+Run: `cargo check --workspace`
+Expected: compiles cleanly.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add crates/trusted-server-core/src/ec/fp_signals.rs crates/trusted-server-core/src/ec/mod.rs
+git commit -m "Add FpSignalPartnerConfig, FpSignal, and FpSignalError types"
+```
+
+---
+
+### Task 2: Implement JSON path extraction with tests
+
+**Files:**
+
+- Modify: `crates/trusted-server-core/src/ec/fp_signals.rs`
+- Test: `crates/trusted-server-core/src/ec/fp_signals.rs` (inline `#[cfg(test)]`)
+
+- [ ] **Step 1: Write failing tests for JSON path extraction**
+
+Append to `crates/trusted-server-core/src/ec/fp_signals.rs`:
+
+```rust
+/// Extracts a string value from a JSON string using dot-notation path.
+///
+/// Splits `path` on `.` and walks the `serde_json::Value` tree.
+/// Returns `Some(string)` if the leaf is a JSON string, `None` on any
+/// failure (invalid JSON, wrong type, missing key).
+fn extract_json_path(value: &str, path: &str) -> Option<String> {
+    todo!()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn json_path_extracts_top_level_key() {
+        let json = r#"{"universal_uid":"ID5*abc123","version":1}"#;
+        let result = extract_json_path(json, "universal_uid");
+        assert_eq!(
+            result.as_deref(),
+            Some("ID5*abc123"),
+            "should extract top-level string key"
+        );
+    }
+
+    #[test]
+    fn json_path_extracts_nested_key() {
+        let json = r#"{"v":{"userId":"d8f4e2a1"}}"#;
+        let result = extract_json_path(json, "v.userId");
+        assert_eq!(
+            result.as_deref(),
+            Some("d8f4e2a1"),
+            "should extract nested key via dot path"
+        );
+    }
+
+    #[test]
+    fn json_path_returns_none_for_missing_key() {
+        let json = r#"{"universal_uid":"ID5*abc123"}"#;
+        let result = extract_json_path(json, "nonexistent");
+        assert!(result.is_none(), "should return None for missing key");
+    }
+
+    #[test]
+    fn json_path_returns_none_for_non_string_leaf() {
+        let json = r#"{"count":42}"#;
+        let result = extract_json_path(json, "count");
+        assert!(
+            result.is_none(),
+            "should return None when leaf is not a string"
+        );
+    }
+
+    #[test]
+    fn json_path_returns_none_for_invalid_json() {
+        let result = extract_json_path("not-json", "key");
+        assert!(result.is_none(), "should return None for invalid JSON");
+    }
+
+    #[test]
+    fn json_path_returns_none_for_empty_path() {
+        let json = r#"{"key":"value"}"#;
+        let result = extract_json_path(json, "");
+        assert!(result.is_none(), "should return None for empty path");
+    }
+
+    #[test]
+    fn json_path_returns_none_for_partial_path() {
+        let json = r#"{"v":{"userId":"d8f4e2a1"}}"#;
+        let result = extract_json_path(json, "v.nonexistent");
+        assert!(
+            result.is_none(),
+            "should return None when nested key is missing"
+        );
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cargo test --package trusted-server-core --lib ec::fp_signals::tests -- --no-capture 2>&1 | head -30`
+Expected: FAIL — `todo!()` panics.
+
+- [ ] **Step 3: Implement `extract_json_path`**
+
+Replace the `todo!()` body:
+
+```rust
+fn extract_json_path(value: &str, path: &str) -> Option<String> {
+    if path.is_empty() {
+        return None;
+    }
+
+    let parsed: serde_json::Value = serde_json::from_str(value).ok()?;
+    let mut current = &parsed;
+
+    for segment in path.split('.') {
+        current = current.get(segment)?;
+    }
+
+    current.as_str().map(str::to_owned)
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cargo test --package trusted-server-core --lib ec::fp_signals::tests`
+Expected: all 7 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/trusted-server-core/src/ec/fp_signals.rs
+git commit -m "Implement JSON path extraction for first-party signal cookies"
+```
+
+---
+
+### Task 3: Implement `extract_fp_signals` with tests
+
+**Files:**
+
+- Modify: `crates/trusted-server-core/src/ec/fp_signals.rs`
+
+- [ ] **Step 1: Write failing tests for cookie extraction**
+
+Add these tests to the existing `mod tests` block in `fp_signals.rs`:
+
+```rust
+    use cookie::{Cookie, CookieJar};
+
+    fn jar_with(cookies: &[(&str, &str)]) -> CookieJar {
+        let mut jar = CookieJar::new();
+        for &(name, value) in cookies {
+            jar.add_original(Cookie::new(name.to_owned(), value.to_owned()));
+        }
+        jar
+    }
+
+    #[test]
+    fn extract_raw_cookie_value() {
+        let jar = jar_with(&[("lockr_tracking_id", "16d913a7-d56c-4b2f")]);
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "lockr".to_owned(),
+            cookie_names: vec!["lockr_tracking_id".to_owned()],
+            json_path: None,
+            ttl_sec: 86400,
+        }];
+
+        let signals = extract_fp_signals(&jar, &configs, 1_700_000_000_000);
+
+        assert_eq!(signals.len(), 1);
+        assert_eq!(signals[0].partner_id, "lockr");
+        assert_eq!(signals[0].uid, "16d913a7-d56c-4b2f");
+    }
+
+    #[test]
+    fn extract_json_cookie_value() {
+        let jar = jar_with(&[(
+            "id5id",
+            r#"{"universal_uid":"ID5*abc","version":1}"#,
+        )]);
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "id5".to_owned(),
+            cookie_names: vec!["id5id".to_owned()],
+            json_path: Some("universal_uid".to_owned()),
+            ttl_sec: 86400,
+        }];
+
+        let signals = extract_fp_signals(&jar, &configs, 1_700_000_000_000);
+
+        assert_eq!(signals.len(), 1);
+        assert_eq!(signals[0].uid, "ID5*abc");
+    }
+
+    #[test]
+    fn extract_first_match_wins() {
+        let jar = jar_with(&[("_sharedid", "shared-uid-456")]);
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "prebid_sharedid".to_owned(),
+            cookie_names: vec![
+                "sharedId".to_owned(),
+                "_sharedid".to_owned(),
+                "_sharedID".to_owned(),
+            ],
+            json_path: None,
+            ttl_sec: 86400,
+        }];
+
+        let signals = extract_fp_signals(&jar, &configs, 1_700_000_000_000);
+
+        assert_eq!(signals.len(), 1);
+        assert_eq!(signals[0].uid, "shared-uid-456");
+    }
+
+    #[test]
+    fn extract_skips_missing_cookie() {
+        let jar = jar_with(&[]);
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "lockr".to_owned(),
+            cookie_names: vec!["lockr_tracking_id".to_owned()],
+            json_path: None,
+            ttl_sec: 86400,
+        }];
+
+        let signals = extract_fp_signals(&jar, &configs, 1_700_000_000_000);
+
+        assert!(signals.is_empty(), "should skip when cookie is missing");
+    }
+
+    #[test]
+    fn extract_skips_empty_uid() {
+        let jar = jar_with(&[("lockr_tracking_id", "   ")]);
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "lockr".to_owned(),
+            cookie_names: vec!["lockr_tracking_id".to_owned()],
+            json_path: None,
+            ttl_sec: 86400,
+        }];
+
+        let signals = extract_fp_signals(&jar, &configs, 1_700_000_000_000);
+
+        assert!(signals.is_empty(), "should skip empty/whitespace UID");
+    }
+
+    #[test]
+    fn extract_skips_failed_json_path() {
+        let jar = jar_with(&[("id5id", "not-json")]);
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "id5".to_owned(),
+            cookie_names: vec!["id5id".to_owned()],
+            json_path: Some("universal_uid".to_owned()),
+            ttl_sec: 86400,
+        }];
+
+        let signals = extract_fp_signals(&jar, &configs, 1_700_000_000_000);
+
+        assert!(signals.is_empty(), "should skip when JSON path fails");
+    }
+
+    #[test]
+    fn extract_nested_json_path() {
+        let jar = jar_with(&[("krg_uid", r#"{"v":{"userId":"d8f4e2a1"}}"#)]);
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "kargo".to_owned(),
+            cookie_names: vec!["krg_uid".to_owned()],
+            json_path: Some("v.userId".to_owned()),
+            ttl_sec: 86400,
+        }];
+
+        let signals = extract_fp_signals(&jar, &configs, 1_700_000_000_000);
+
+        assert_eq!(signals.len(), 1);
+        assert_eq!(signals[0].uid, "d8f4e2a1");
+    }
+
+    #[test]
+    fn extract_multiple_partners() {
+        let jar = jar_with(&[
+            ("lockr_tracking_id", "lockr-uid"),
+            ("panoramaId", "lotame-uid"),
+        ]);
+        let configs = vec![
+            FpSignalPartnerConfig {
+                partner_id: "lockr".to_owned(),
+                cookie_names: vec!["lockr_tracking_id".to_owned()],
+                json_path: None,
+                ttl_sec: 86400,
+            },
+            FpSignalPartnerConfig {
+                partner_id: "lotame".to_owned(),
+                cookie_names: vec!["panoramaId".to_owned()],
+                json_path: None,
+                ttl_sec: 86400,
+            },
+        ];
+
+        let signals = extract_fp_signals(&jar, &configs, 1_700_000_000_000);
+
+        assert_eq!(signals.len(), 2, "should extract both partners");
+    }
+```
+
+- [ ] **Step 2: Write the `extract_fp_signals` function stub**
+
+Add above the `#[cfg(test)]` block:
+
+```rust
+use cookie::CookieJar;
+
+/// Extracts partner UIDs from first-party cookies.
+///
+/// Iterates partner configs, checks the cookie jar for each partner's
+/// cookie names, and extracts UIDs using optional JSON path notation.
+/// UID2 tokens are only extracted if they have at least 5 minutes of
+/// validity remaining.
+///
+/// This is a pure function with no I/O — safe to call on the hot path.
+///
+/// # Arguments
+///
+/// * `jar` — the parsed cookie jar from the incoming request
+/// * `configs` — partner extraction configs from the `_fp_signal_enabled` index
+/// * `now_ms` — current time in milliseconds (for UID2 expiry check)
+pub fn extract_fp_signals(
+    jar: &CookieJar,
+    configs: &[FpSignalPartnerConfig],
+    now_ms: u64,
+) -> Vec<FpSignal> {
+    todo!()
+}
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run: `cargo test --package trusted-server-core --lib ec::fp_signals::tests -- --no-capture 2>&1 | head -30`
+Expected: FAIL — `todo!()` panics.
+
+- [ ] **Step 4: Implement `extract_fp_signals`**
+
+Replace the `todo!()` body:
+
+```rust
+pub fn extract_fp_signals(
+    jar: &CookieJar,
+    configs: &[FpSignalPartnerConfig],
+    now_ms: u64,
+) -> Vec<FpSignal> {
+    let mut signals = Vec::new();
+
+    for config in configs {
+        let cookie_value = config
+            .cookie_names
+            .iter()
+            .find_map(|name| jar.get(name.as_str()))
+            .map(|c| c.value());
+
+        let Some(raw_value) = cookie_value else {
+            continue;
+        };
+
+        // UID2 expiry check: if the cookie contains `identity_expires`,
+        // only extract when the token has >= 5 minutes of validity.
+        if let Ok(parsed) = serde_json::from_str::<serde_json::Value>(raw_value) {
+            if let Some(expires) = parsed.get("identity_expires").and_then(|v| v.as_u64()) {
+                if expires <= now_ms + 300_000 {
+                    log::debug!(
+                        "Skipping expired UID2 token for partner '{}' (expires={}, now={})",
+                        config.partner_id,
+                        expires,
+                        now_ms,
+                    );
+                    continue;
+                }
+            }
+        }
+
+        let uid = match &config.json_path {
+            Some(path) => match extract_json_path(raw_value, path) {
+                Some(uid) => uid,
+                None => {
+                    log::debug!(
+                        "JSON path '{}' extraction failed for partner '{}'",
+                        path,
+                        config.partner_id,
+                    );
+                    continue;
+                }
+            },
+            None => raw_value.to_owned(),
+        };
+
+        let trimmed = uid.trim();
+        if trimmed.is_empty() {
+            continue;
+        }
+
+        signals.push(FpSignal {
+            partner_id: config.partner_id.clone(),
+            uid: trimmed.to_owned(),
+        });
+    }
+
+    signals
+}
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `cargo test --package trusted-server-core --lib ec::fp_signals::tests`
+Expected: all tests PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/trusted-server-core/src/ec/fp_signals.rs
+git commit -m "Implement first-party signal extraction from cookie jar"
+```
+
+---
+
+### Task 4: Add UID2 expiry tests
+
+**Files:**
+
+- Modify: `crates/trusted-server-core/src/ec/fp_signals.rs`
+
+- [ ] **Step 1: Write UID2 expiry tests**
+
+Add to `mod tests`:
+
+```rust
+    #[test]
+    fn extract_uid2_with_valid_token() {
+        let now_ms = 1_775_000_000_000;
+        let expires = now_ms + 600_000; // 10 min remaining
+        let cookie_value = format!(
+            r#"{{"advertising_token":"A4AAADA","refresh_token":"secret","identity_expires":{expires}}}"#,
+        );
+        let jar = jar_with(&[("__uid2_advertising_token", &cookie_value)]);
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "uid2".to_owned(),
+            cookie_names: vec!["__uid2_advertising_token".to_owned()],
+            json_path: Some("advertising_token".to_owned()),
+            ttl_sec: 3600,
+        }];
+
+        let signals = extract_fp_signals(&jar, &configs, now_ms);
+
+        assert_eq!(signals.len(), 1, "should extract valid UID2 token");
+        assert_eq!(signals[0].uid, "A4AAADA");
+    }
+
+    #[test]
+    fn extract_uid2_skips_expired_token() {
+        let now_ms = 1_775_000_000_000;
+        let expires = now_ms + 200_000; // Only 200s remaining (< 300s threshold)
+        let cookie_value = format!(
+            r#"{{"advertising_token":"A4AAADA","refresh_token":"secret","identity_expires":{expires}}}"#,
+        );
+        let jar = jar_with(&[("__uid2_advertising_token", &cookie_value)]);
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "uid2".to_owned(),
+            cookie_names: vec!["__uid2_advertising_token".to_owned()],
+            json_path: Some("advertising_token".to_owned()),
+            ttl_sec: 3600,
+        }];
+
+        let signals = extract_fp_signals(&jar, &configs, now_ms);
+
+        assert!(signals.is_empty(), "should skip UID2 token with <5 min validity");
+    }
+
+    #[test]
+    fn extract_non_uid2_json_without_identity_expires() {
+        let jar = jar_with(&[(
+            "id5id",
+            r#"{"universal_uid":"ID5*abc","version":1}"#,
+        )]);
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "id5".to_owned(),
+            cookie_names: vec!["id5id".to_owned()],
+            json_path: Some("universal_uid".to_owned()),
+            ttl_sec: 86400,
+        }];
+
+        let signals = extract_fp_signals(&jar, &configs, 1_700_000_000_000);
+
+        assert_eq!(signals.len(), 1, "should extract non-UID2 JSON cookie normally");
+        assert_eq!(signals[0].uid, "ID5*abc");
+    }
+```
+
+- [ ] **Step 2: Run tests**
+
+Run: `cargo test --package trusted-server-core --lib ec::fp_signals::tests`
+Expected: all tests PASS (UID2 logic is already implemented in Task 3).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add crates/trusted-server-core/src/ec/fp_signals.rs
+git commit -m "Add UID2 expiry check tests for first-party signal extraction"
+```
+
+---
+
+### Task 5: Expose `CookieJar` from `EcContext`
+
+**Files:**
+
+- Modify: `crates/trusted-server-core/src/ec/mod.rs:139-161` (struct), `193-238` (read_from_request_with_geo), `407-464` (test helpers)
+
+- [ ] **Step 1: Add `cookie_jar` field to `EcContext` struct**
+
+In `crates/trusted-server-core/src/ec/mod.rs`, add after the `device_signals` field (line 160):
+
+```rust
+    /// The parsed cookie jar from the incoming request.
+    /// Retained for first-party signal extraction in the post-EC phase.
+    cookie_jar: Option<CookieJar>,
+```
+
+- [ ] **Step 2: Store the jar in `read_from_request_with_geo`**
+
+In the `Ok(Self { ... })` block at line 228, add:
+
+```rust
+            cookie_jar: parsed.jar,
+```
+
+- [ ] **Step 3: Add `cookie_jar()` accessor**
+
+After the `ec_allowed()` method (line 379), add:
+
+```rust
+    /// Returns a reference to the parsed cookie jar from the incoming request.
+    ///
+    /// Used by first-party signal extraction to read partner cookies without
+    /// re-parsing the `Cookie` header.
+    #[must_use]
+    pub fn cookie_jar(&self) -> Option<&CookieJar> {
+        self.cookie_jar.as_ref()
+    }
+```
+
+- [ ] **Step 4: Update test helpers to include `cookie_jar: None`**
+
+In `new_for_test` (line 410), `new_for_test_with_ip` (line 426), and `new_for_test_with_cookie` (line 447), add `cookie_jar: None` to each `Self { ... }` block.
+
+- [ ] **Step 5: Run tests**
+
+Run: `cargo test --package trusted-server-core --lib ec::tests`
+Expected: all existing `EcContext` tests PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/trusted-server-core/src/ec/mod.rs
+git commit -m "Expose parsed CookieJar from EcContext for signal extraction"
+```
+
+---
+
+### Task 6: Add FP signal fields to `PartnerRecord`
+
+**Files:**
+
+- Modify: `crates/trusted-server-core/src/ec/partner.rs:62-115` (struct), `707-984` (tests)
+
+- [ ] **Step 1: Add 3 fields to `PartnerRecord`**
+
+In `crates/trusted-server-core/src/ec/partner.rs`, add after the `ts_pull_token` field (line 114), before the closing `}`:
+
+```rust
+    /// First-party cookie names that may carry this partner's UID.
+    /// Checked in order; first match wins.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub fp_signal_cookie_names: Vec<String>,
+    /// Dot-notation JSON path to extract the UID from a JSON cookie
+    /// value. When `None`, the raw cookie value is used.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub fp_signal_json_path: Option<String>,
+    /// Minimum seconds between re-collection writes for this partner.
+    /// Defaults to 86400 (24 hours).
+    #[serde(default = "PartnerRecord::default_fp_signal_ttl_sec")]
+    pub fp_signal_ttl_sec: u64,
+```
+
+- [ ] **Step 2: Add default method**
+
+Add an `impl PartnerRecord` block (or extend if one exists) after the struct definition:
+
+```rust
+impl PartnerRecord {
+    fn default_fp_signal_ttl_sec() -> u64 {
+        86400
+    }
+}
+```
+
+- [ ] **Step 3: Update every `PartnerRecord { ... }` literal in tests**
+
+Every existing `PartnerRecord` construction in `partner.rs` tests and `admin.rs` tests needs the 3 new fields. Add to each:
+
+```rust
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
+```
+
+Also search all other files that construct `PartnerRecord` literals (use `grep -rn "PartnerRecord {" crates/` to find them all). Each must include the new fields.
+
+- [ ] **Step 4: Run full workspace tests**
+
+Run: `cargo test --workspace`
+Expected: all tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/trusted-server-core/src/ec/partner.rs
+git commit -m "Add first-party signal fields to PartnerRecord"
+```
+
+---
+
+### Task 7: Add FP signal validation
+
+**Files:**
+
+- Modify: `crates/trusted-server-core/src/ec/partner.rs`
+
+- [ ] **Step 1: Write failing validation tests**
+
+Add to `mod tests` in `partner.rs`:
+
+```rust
+    #[test]
+    fn validate_fp_signal_config_accepts_valid() {
+        let result = validate_fp_signal_config(&PartnerRecord {
+            id: "id5".to_owned(),
+            name: "ID5".to_owned(),
+            allowed_return_domains: vec!["id5.com".to_owned()],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "id5-sync.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+            fp_signal_cookie_names: vec!["id5id".to_owned()],
+            fp_signal_json_path: Some("universal_uid".to_owned()),
+            fp_signal_ttl_sec: 86400,
+        });
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn validate_fp_signal_config_ok_when_empty() {
+        let result = validate_fp_signal_config(&PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+            fp_signal_cookie_names: vec![],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
+        });
+        assert!(result.is_ok(), "should accept empty fp signal config");
+    }
+
+    #[test]
+    fn validate_fp_signal_rejects_empty_cookie_name() {
+        let result = validate_fp_signal_config(&PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+            fp_signal_cookie_names: vec!["".to_owned()],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
+        });
+        let err = result.unwrap_err();
+        assert!(err.contains("empty"), "got: {err}");
+    }
+
+    #[test]
+    fn validate_fp_signal_rejects_too_many_cookie_names() {
+        let result = validate_fp_signal_config(&PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+            fp_signal_cookie_names: vec![
+                "a".to_owned(), "b".to_owned(), "c".to_owned(),
+                "d".to_owned(), "e".to_owned(), "f".to_owned(),
+            ],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
+        });
+        let err = result.unwrap_err();
+        assert!(err.contains("5"), "got: {err}");
+    }
+
+    #[test]
+    fn validate_fp_signal_rejects_cookie_name_with_semicolon() {
+        let result = validate_fp_signal_config(&PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+            fp_signal_cookie_names: vec!["bad;name".to_owned()],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 86400,
+        });
+        assert!(result.is_err(), "should reject semicolon in cookie name");
+    }
+
+    #[test]
+    fn validate_fp_signal_rejects_ttl_too_low() {
+        let result = validate_fp_signal_config(&PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+            fp_signal_cookie_names: vec!["cookie".to_owned()],
+            fp_signal_json_path: None,
+            fp_signal_ttl_sec: 10,
+        });
+        let err = result.unwrap_err();
+        assert!(err.contains("60"), "got: {err}");
+    }
+
+    #[test]
+    fn validate_fp_signal_rejects_invalid_json_path() {
+        let result = validate_fp_signal_config(&PartnerRecord {
+            id: "test".to_owned(),
+            name: "Test".to_owned(),
+            allowed_return_domains: vec![],
+            api_key_hash: String::new(),
+            bidstream_enabled: false,
+            source_domain: "test.com".to_owned(),
+            openrtb_atype: 3,
+            sync_rate_limit: 100,
+            batch_rate_limit: 60,
+            pull_sync_enabled: false,
+            pull_sync_url: None,
+            pull_sync_allowed_domains: vec![],
+            pull_sync_ttl_sec: 86400,
+            pull_sync_rate_limit: 10,
+            ts_pull_token: None,
+            fp_signal_cookie_names: vec!["cookie".to_owned()],
+            fp_signal_json_path: Some("a.b.c.d.e".to_owned()),
+            fp_signal_ttl_sec: 86400,
+        });
+        let err = result.unwrap_err();
+        assert!(err.contains("4"), "got: {err}");
+    }
+```
+
+- [ ] **Step 2: Implement `validate_fp_signal_config`**
+
+Add after `validate_pull_sync_config` in `partner.rs`:
+
+```rust
+/// Validates first-party signal collection configuration.
+///
+/// When `fp_signal_cookie_names` is empty, all FP signal fields are
+/// ignored (no validation needed). When non-empty:
+/// - Each cookie name must be non-empty, ASCII, no `;` or `=`.
+/// - At most 5 cookie names per partner.
+/// - `fp_signal_json_path` (if present) must be non-empty, only
+///   alphanumeric + `.` + `_`, max 4 dot-separated segments.
+/// - `fp_signal_ttl_sec` must be between 60 and 604800.
+///
+/// # Errors
+///
+/// Returns a descriptive error string on validation failure.
+pub fn validate_fp_signal_config(record: &PartnerRecord) -> Result<(), String> {
+    if record.fp_signal_cookie_names.is_empty() {
+        return Ok(());
+    }
+
+    if record.fp_signal_cookie_names.len() > 5 {
+        return Err(format!(
+            "fp_signal_cookie_names must have at most 5 entries, got {}",
+            record.fp_signal_cookie_names.len()
+        ));
+    }
+
+    for name in &record.fp_signal_cookie_names {
+        if name.is_empty() {
+            return Err("fp_signal_cookie_names entries must not be empty".to_owned());
+        }
+        if !name.is_ascii() {
+            return Err(format!(
+                "fp_signal_cookie_names entry '{name}' contains non-ASCII characters"
+            ));
+        }
+        if name.contains(';') || name.contains('=') {
+            return Err(format!(
+                "fp_signal_cookie_names entry '{name}' contains invalid characters (';' or '=')"
+            ));
+        }
+    }
+
+    if let Some(ref path) = record.fp_signal_json_path {
+        if path.is_empty() {
+            return Err("fp_signal_json_path must not be empty when present".to_owned());
+        }
+        if !path
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_')
+        {
+            return Err(format!(
+                "fp_signal_json_path '{path}' contains invalid characters \
+                 (only alphanumeric, '.', '_' allowed)"
+            ));
+        }
+        let depth = path.split('.').count();
+        if depth > 4 {
+            return Err(format!(
+                "fp_signal_json_path '{path}' exceeds max depth of 4 segments (got {depth})"
+            ));
+        }
+    }
+
+    if record.fp_signal_ttl_sec < 60 {
+        return Err(format!(
+            "fp_signal_ttl_sec must be at least 60, got {}",
+            record.fp_signal_ttl_sec
+        ));
+    }
+    if record.fp_signal_ttl_sec > 604_800 {
+        return Err(format!(
+            "fp_signal_ttl_sec must be at most 604800 (7 days), got {}",
+            record.fp_signal_ttl_sec
+        ));
+    }
+
+    Ok(())
+}
+```
+
+- [ ] **Step 3: Run tests**
+
+Run: `cargo test --package trusted-server-core --lib ec::partner::tests`
+Expected: all tests PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add crates/trusted-server-core/src/ec/partner.rs
+git commit -m "Add first-party signal validation for PartnerRecord"
+```
+
+---
+
+### Task 8: Add `_fp_signal_enabled` index to `PartnerStore`
+
+**Files:**
+
+- Modify: `crates/trusted-server-core/src/ec/partner.rs`
+
+- [ ] **Step 1: Add the index constant and skip it in `list_registered`**
+
+In `partner.rs`, add after `PULL_ENABLED_INDEX_KEY` (line 47):
+
+```rust
+/// Key for the first-party signal partner config secondary index.
+///
+/// Stores a JSON array of [`FpSignalPartnerConfig`](super::fp_signals::FpSignalPartnerConfig)
+/// for partners with non-empty `fp_signal_cookie_names`.
+const FP_SIGNAL_INDEX_KEY: &str = "_fp_signal_enabled";
+```
+
+In `list_registered()` at line 314, update the skip condition:
+
+```rust
+                if key.starts_with(APIKEY_INDEX_PREFIX)
+                    || key == PULL_ENABLED_INDEX_KEY
+                    || key == FP_SIGNAL_INDEX_KEY
+                {
+                    continue;
+                }
+```
+
+- [ ] **Step 2: Add `update_fp_signal_index` method**
+
+Add after `update_pull_enabled_index` in `impl PartnerStore`:
+
+```rust
+    /// Best-effort update of the `_fp_signal_enabled` secondary index.
+    ///
+    /// Stores denormalized [`FpSignalPartnerConfig`](super::fp_signals::FpSignalPartnerConfig)
+    /// entries for O(1) reads during extraction. Same self-healing pattern as
+    /// [`update_pull_enabled_index`](Self::update_pull_enabled_index).
+    fn update_fp_signal_index(&self, store: &KVStore, record: &PartnerRecord) {
+        use super::fp_signals::FpSignalPartnerConfig;
+
+        let mut configs: Vec<FpSignalPartnerConfig> = match store.lookup(FP_SIGNAL_INDEX_KEY) {
+            Ok(mut resp) => {
+                let bytes = resp.take_body_bytes();
+                serde_json::from_slice(&bytes).unwrap_or_else(|err| {
+                    log::warn!(
+                        "Failed to deserialize fp-signal index, starting fresh: {err}"
+                    );
+                    Vec::new()
+                })
+            }
+            Err(_) => Vec::new(),
+        };
+
+        // Remove existing entry for this partner.
+        configs.retain(|c| c.partner_id != record.id);
+
+        // Add new entry if partner has FP signal config.
+        if !record.fp_signal_cookie_names.is_empty() {
+            configs.push(FpSignalPartnerConfig {
+                partner_id: record.id.clone(),
+                cookie_names: record.fp_signal_cookie_names.clone(),
+                json_path: record.fp_signal_json_path.clone(),
+                ttl_sec: record.fp_signal_ttl_sec,
+            });
+        }
+
+        let body = match serde_json::to_string(&configs) {
+            Ok(b) => b,
+            Err(err) => {
+                log::warn!(
+                    "Failed to serialize fp-signal index after updating partner '{}': {err}",
+                    record.id,
+                );
+                return;
+            }
+        };
+
+        if let Err(err) = store.build_insert().execute(FP_SIGNAL_INDEX_KEY, body) {
+            log::warn!(
+                "Failed to write fp-signal index after updating partner '{}': {err:?}",
+                record.id,
+            );
+        }
+    }
+```
+
+- [ ] **Step 3: Call `update_fp_signal_index` from `upsert`**
+
+In `upsert()`, after the `update_pull_enabled_index` call (line 515), add:
+
+```rust
+        // 5. Update _fp_signal_enabled secondary index (best-effort).
+        self.update_fp_signal_index(&store, record);
+```
+
+- [ ] **Step 4: Add `fp_signal_configs` accessor**
+
+Add to `impl PartnerStore`:
+
+```rust
+    /// Returns first-party signal partner configs from the `_fp_signal_enabled` index.
+    ///
+    /// Returns an empty vec if the index is missing or unreadable (degraded-behavior
+    /// policy — collection is best-effort).
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on store open failure.
+    pub fn fp_signal_configs(
+        &self,
+    ) -> Result<Vec<super::fp_signals::FpSignalPartnerConfig>, Report<TrustedServerError>> {
+        use super::fp_signals::FpSignalPartnerConfig;
+
+        let store = self.open_store()?;
+        match store.lookup(FP_SIGNAL_INDEX_KEY) {
+            Ok(mut resp) => {
+                let bytes = resp.take_body_bytes();
+                let configs: Vec<FpSignalPartnerConfig> =
+                    serde_json::from_slice(&bytes).unwrap_or_else(|err| {
+                        log::warn!(
+                            "Failed to deserialize fp-signal index, returning empty: {err}"
+                        );
+                        Vec::new()
+                    });
+                Ok(configs)
+            }
+            Err(fastly::kv_store::KVStoreError::ItemNotFound) => Ok(Vec::new()),
+            Err(err) => {
+                log::warn!("Failed to read fp-signal index, returning empty: {err:?}");
+                Ok(Vec::new())
+            }
+        }
+    }
+```
+
+- [ ] **Step 5: Verify compilation**
+
+Run: `cargo check --workspace`
+Expected: compiles cleanly.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/trusted-server-core/src/ec/partner.rs
+git commit -m "Add _fp_signal_enabled index to PartnerStore"
+```
+
+---
+
+### Task 9: Add FP signal fields to admin registration endpoint
+
+**Files:**
+
+- Modify: `crates/trusted-server-core/src/ec/admin.rs`
+
+- [ ] **Step 1: Add fields to `RegisterPartnerRequest`**
+
+In `admin.rs`, add after the `ts_pull_token` field in `RegisterPartnerRequest` (line 50):
+
+```rust
+    #[serde(default)]
+    pub fp_signal_cookie_names: Vec<String>,
+    #[serde(default)]
+    pub fp_signal_json_path: Option<String>,
+    #[serde(default = "default_fp_signal_ttl_sec")]
+    pub fp_signal_ttl_sec: u64,
+```
+
+Add the default function near the other defaults:
+
+```rust
+fn default_fp_signal_ttl_sec() -> u64 {
+    86400
+}
+```
+
+- [ ] **Step 2: Wire fields into `PartnerRecord` construction**
+
+In `handle_register_partner`, destructure the new fields from the request (after `ts_pull_token` at line 201):
+
+```rust
+        fp_signal_cookie_names,
+        fp_signal_json_path,
+        fp_signal_ttl_sec,
+```
+
+And include them in the `PartnerRecord { ... }` construction (after `ts_pull_token` at line 240):
+
+```rust
+        fp_signal_cookie_names,
+        fp_signal_json_path,
+        fp_signal_ttl_sec,
+```
+
+- [ ] **Step 3: Add validation call**
+
+After `validate_pull_sync_config(&record).map_err(bad_request)?;` (line 244), add:
+
+```rust
+    validate_fp_signal_config(&record).map_err(bad_request)?;
+```
+
+And update the import at the top to include:
+
+```rust
+use super::partner::{
+    hash_api_key, validate_fp_signal_config, validate_partner_id, validate_pull_sync_config,
+    PartnerRecord, PartnerStore,
+};
+```
+
+- [ ] **Step 4: Update admin tests**
+
+In the `request_deserializes_with_defaults` test, add assertions:
+
+```rust
+        assert!(req.fp_signal_cookie_names.is_empty(), "should default to empty");
+        assert!(req.fp_signal_json_path.is_none(), "should default to None");
+        assert_eq!(req.fp_signal_ttl_sec, 86400, "should default to 86400");
+```
+
+In the `request_deserializes_full_payload` test, add the new fields to the JSON and assertions:
+
+```json
+            "fp_signal_cookie_names": ["id5id"],
+            "fp_signal_json_path": "universal_uid",
+            "fp_signal_ttl_sec": 3600
+```
+
+```rust
+        assert_eq!(req.fp_signal_cookie_names, vec!["id5id"]);
+        assert_eq!(req.fp_signal_json_path.as_deref(), Some("universal_uid"));
+        assert_eq!(req.fp_signal_ttl_sec, 3600);
+```
+
+- [ ] **Step 5: Run tests**
+
+Run: `cargo test --workspace`
+Expected: all tests PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/trusted-server-core/src/ec/admin.rs
+git commit -m "Add first-party signal fields to partner registration endpoint"
+```
+
+---
+
+### Task 10: Implement `write_fp_signals` with tests
+
+**Files:**
+
+- Modify: `crates/trusted-server-core/src/ec/fp_signals.rs`
+
+- [ ] **Step 1: Write batched write tests**
+
+These tests exercise the logic without real KV — we'll test the TTL filtering and signal merging logic via a helper that simulates the write decision. Add to `mod tests` in `fp_signals.rs`:
+
+```rust
+    use std::collections::HashMap;
+    use super::super::kv_types::KvPartnerId;
+
+    #[test]
+    fn filter_signals_skips_fresh_ids() {
+        let mut existing_ids = HashMap::new();
+        existing_ids.insert(
+            "lockr".to_owned(),
+            KvPartnerId {
+                uid: "old-uid".to_owned(),
+                synced: 1_000_000,
+            },
+        );
+
+        let signals = vec![FpSignal {
+            partner_id: "lockr".to_owned(),
+            uid: "new-uid".to_owned(),
+        }];
+
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "lockr".to_owned(),
+            cookie_names: vec!["lockr_tracking_id".to_owned()],
+            json_path: None,
+            ttl_sec: 86400,
+        }];
+
+        let now = 1_000_100; // Only 100s since last sync (< 86400 TTL)
+        let to_write = filter_stale_signals(&signals, &existing_ids, &configs, now);
+
+        assert!(to_write.is_empty(), "should skip fresh signal");
+    }
+
+    #[test]
+    fn filter_signals_includes_stale_ids() {
+        let mut existing_ids = HashMap::new();
+        existing_ids.insert(
+            "lockr".to_owned(),
+            KvPartnerId {
+                uid: "old-uid".to_owned(),
+                synced: 1_000_000,
+            },
+        );
+
+        let signals = vec![FpSignal {
+            partner_id: "lockr".to_owned(),
+            uid: "new-uid".to_owned(),
+        }];
+
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "lockr".to_owned(),
+            cookie_names: vec!["lockr_tracking_id".to_owned()],
+            json_path: None,
+            ttl_sec: 86400,
+        }];
+
+        let now = 1_100_000; // 100000s since last sync (> 86400 TTL)
+        let to_write = filter_stale_signals(&signals, &existing_ids, &configs, now);
+
+        assert_eq!(to_write.len(), 1, "should include stale signal");
+        assert_eq!(to_write[0].partner_id, "lockr");
+    }
+
+    #[test]
+    fn filter_signals_includes_new_ids() {
+        let existing_ids = HashMap::new(); // No existing IDs
+
+        let signals = vec![FpSignal {
+            partner_id: "lockr".to_owned(),
+            uid: "new-uid".to_owned(),
+        }];
+
+        let configs = vec![FpSignalPartnerConfig {
+            partner_id: "lockr".to_owned(),
+            cookie_names: vec!["lockr_tracking_id".to_owned()],
+            json_path: None,
+            ttl_sec: 86400,
+        }];
+
+        let to_write = filter_stale_signals(&signals, &existing_ids, &configs, 1_000_000);
+
+        assert_eq!(to_write.len(), 1, "should include new signal");
+    }
+
+    #[test]
+    fn filter_signals_mixed_fresh_and_stale() {
+        let mut existing_ids = HashMap::new();
+        existing_ids.insert(
+            "lockr".to_owned(),
+            KvPartnerId {
+                uid: "lockr-uid".to_owned(),
+                synced: 1_000_000,
+            },
+        );
+        existing_ids.insert(
+            "lotame".to_owned(),
+            KvPartnerId {
+                uid: "lotame-uid".to_owned(),
+                synced: 900_000,
+            },
+        );
+
+        let signals = vec![
+            FpSignal {
+                partner_id: "lockr".to_owned(),
+                uid: "new-lockr".to_owned(),
+            },
+            FpSignal {
+                partner_id: "lotame".to_owned(),
+                uid: "new-lotame".to_owned(),
+            },
+        ];
+
+        let configs = vec![
+            FpSignalPartnerConfig {
+                partner_id: "lockr".to_owned(),
+                cookie_names: vec!["lockr_tracking_id".to_owned()],
+                json_path: None,
+                ttl_sec: 86400,
+            },
+            FpSignalPartnerConfig {
+                partner_id: "lotame".to_owned(),
+                cookie_names: vec!["panoramaId".to_owned()],
+                json_path: None,
+                ttl_sec: 86400,
+            },
+        ];
+
+        let now = 1_050_000; // lockr: 50000s (fresh), lotame: 150000s (stale)
+        let to_write = filter_stale_signals(&signals, &existing_ids, &configs, now);
+
+        assert_eq!(to_write.len(), 1, "should only include stale signal");
+        assert_eq!(to_write[0].partner_id, "lotame");
+    }
+```
+
+- [ ] **Step 2: Implement `filter_stale_signals` helper**
+
+Add above the tests:
+
+```rust
+use std::collections::HashMap;
+
+use error_stack::Report;
+
+use super::kv::KvIdentityGraph;
+use super::kv_types::KvPartnerId;
+use super::log_id;
+
+/// Filters signals down to those whose existing KV entry is missing or stale.
+///
+/// Used by [`write_fp_signals`] to determine which signals need writing.
+fn filter_stale_signals<'a>(
+    signals: &'a [FpSignal],
+    existing_ids: &HashMap<String, KvPartnerId>,
+    configs: &[FpSignalPartnerConfig],
+    now: u64,
+) -> Vec<&'a FpSignal> {
+    let ttl_map: HashMap<&str, u64> = configs
+        .iter()
+        .map(|c| (c.partner_id.as_str(), c.ttl_sec))
+        .collect();
+
+    signals
+        .iter()
+        .filter(|signal| {
+            let ttl = ttl_map
+                .get(signal.partner_id.as_str())
+                .copied()
+                .unwrap_or(86400);
+
+            match existing_ids.get(&signal.partner_id) {
+                Some(existing) => now.saturating_sub(existing.synced) >= ttl,
+                None => true,
+            }
+        })
+        .collect()
+}
+```
+
+- [ ] **Step 3: Run filter tests**
+
+Run: `cargo test --package trusted-server-core --lib ec::fp_signals::tests`
+Expected: all tests PASS.
+
+- [ ] **Step 4: Implement `write_fp_signals`**
+
+Add the main write function:
+
+```rust
+/// Writes extracted first-party signals to the KV identity graph.
+///
+/// Performs a single batched read-modify-write cycle:
+/// 1. Read the KV entry for `ec_id`.
+/// 2. Skip if missing or tombstoned.
+/// 3. Filter signals to those that are missing or stale (TTL check).
+/// 4. Insert all qualifying signals and CAS write.
+/// 5. Retry on conflict up to 3 times.
+///
+/// # Errors
+///
+/// Returns [`FpSignalError::KvWrite`] on KV store failure or CAS exhaustion.
+pub fn write_fp_signals(
+    kv: &KvIdentityGraph,
+    ec_id: &str,
+    signals: &[FpSignal],
+    configs: &[FpSignalPartnerConfig],
+) -> Result<(), Report<FpSignalError>> {
+    use error_stack::ResultExt;
+
+    const MAX_RETRIES: u32 = 3;
+    let now = super::current_timestamp();
+
+    for attempt in 0..MAX_RETRIES {
+        let (mut entry, generation) = match kv.get(ec_id) {
+            Ok(Some(pair)) => pair,
+            Ok(None) => {
+                log::debug!(
+                    "FP signal write: no entry for '{}', skipping",
+                    log_id(ec_id),
+                );
+                return Ok(());
+            }
+            Err(err) => {
+                return Err(err
+                    .change_context(FpSignalError::KvWrite {
+                        message: format!("Failed to read entry for '{}'", log_id(ec_id)),
+                    }));
+            }
+        };
+
+        if !entry.consent.ok {
+            log::debug!(
+                "FP signal write: entry for '{}' is tombstoned, skipping",
+                log_id(ec_id),
+            );
+            return Ok(());
+        }
+
+        let to_write = filter_stale_signals(signals, &entry.ids, configs, now);
+        if to_write.is_empty() {
+            log::debug!(
+                "FP signal write: all signals fresh for '{}', no write needed",
+                log_id(ec_id),
+            );
+            return Ok(());
+        }
+
+        for signal in &to_write {
+            entry.ids.insert(
+                signal.partner_id.clone(),
+                KvPartnerId {
+                    uid: signal.uid.clone(),
+                    synced: now,
+                },
+            );
+        }
+
+        match kv.cas_write(ec_id, &entry, generation) {
+            Ok(()) => {
+                log::debug!(
+                    "FP signal write: wrote {} signals for '{}'",
+                    to_write.len(),
+                    log_id(ec_id),
+                );
+                return Ok(());
+            }
+            Err(err) if is_cas_conflict(&err) => {
+                log::debug!(
+                    "FP signal write: CAS conflict on attempt {}/{MAX_RETRIES} for '{}'",
+                    attempt + 1,
+                    log_id(ec_id),
+                );
+                // Loop will re-read on next iteration.
+            }
+            Err(err) => {
+                return Err(err
+                    .change_context(FpSignalError::KvWrite {
+                        message: format!(
+                            "Failed to write signals for '{}' on attempt {}",
+                            log_id(ec_id),
+                            attempt + 1,
+                        ),
+                    }));
+            }
+        }
+    }
+
+    Err(Report::new(FpSignalError::KvWrite {
+        message: format!(
+            "CAS conflict after {MAX_RETRIES} retries writing signals for '{}'",
+            log_id(ec_id),
+        ),
+    }))
+}
+```
+
+**Note:** This function depends on `KvIdentityGraph::cas_write()` and an `is_cas_conflict()` helper that may not exist yet. The next step addresses this.
+
+- [ ] **Step 5: Add `cas_write` method to `KvIdentityGraph`**
+
+In `crates/trusted-server-core/src/ec/kv.rs`, add a public method for CAS writes that `write_fp_signals` can call:
+
+```rust
+    /// CAS-writes a full entry using the given generation marker.
+    ///
+    /// Returns `Ok(())` on success. On precondition failure, returns
+    /// the `ItemPreconditionFailed` error for the caller to retry.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TrustedServerError::KvStore`] on serialization or store failure.
+    pub fn cas_write(
+        &self,
+        ec_id: &str,
+        entry: &KvEntry,
+        generation: u64,
+    ) -> Result<(), Report<TrustedServerError>> {
+        let store = self.open_store()?;
+        let (body, meta_str) = Self::serialize_entry(entry, &self.store_name)?;
+
+        store
+            .build_insert()
+            .if_generation_match(generation)
+            .metadata(&meta_str)
+            .time_to_live(ENTRY_TTL)
+            .execute(ec_id, body.as_str())
+            .change_context(TrustedServerError::KvStore {
+                store_name: self.store_name.clone(),
+                message: format!("CAS write failed for key '{ec_id}'"),
+            })
+    }
+```
+
+Also add the `is_cas_conflict` helper function in `fp_signals.rs`:
+
+```rust
+/// Checks if an error report contains a CAS conflict.
+fn is_cas_conflict(err: &Report<crate::error::TrustedServerError>) -> bool {
+    err.to_string().contains("ItemPreconditionFailed")
+        || err.to_string().contains("CAS write failed")
+}
+```
+
+- [ ] **Step 6: Verify compilation**
+
+Run: `cargo check --workspace`
+Expected: compiles cleanly.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add crates/trusted-server-core/src/ec/fp_signals.rs crates/trusted-server-core/src/ec/kv.rs
+git commit -m "Implement batched CAS write for first-party signals"
+```
+
+---
+
+### Task 11: Wire extraction and writing into the adapter
+
+**Files:**
+
+- Modify: `crates/trusted-server-adapter-fastly/src/main.rs`
+
+- [ ] **Step 1: Update imports**
+
+Add to the import block at the top of `main.rs`:
+
+```rust
+use trusted_server_core::ec::fp_signals::{
+    extract_fp_signals, write_fp_signals, FpSignal, FpSignalPartnerConfig,
+};
+```
+
+- [ ] **Step 2: Expand `RouteOutcome`**
+
+Add two fields to `RouteOutcome`:
+
+```rust
+#[must_use]
+struct RouteOutcome {
+    response: Response,
+    pull_sync_context: Option<PullSyncContext>,
+    fp_signals: Vec<FpSignal>,
+    fp_signal_configs: Vec<FpSignalPartnerConfig>,
+}
+```
+
+- [ ] **Step 3: Add pre-send extraction in `route_request`**
+
+After the `ec_finalize_response` call (around line 351) and before building the `pull_sync_context`, add:
+
+```rust
+    // Extract first-party signals from cookies for post-send KV write.
+    let (fp_signals, fp_signal_configs) =
+        if is_real_browser && organic_route && route_succeeded && ec_context.ec_allowed() {
+            if let Some(ec_id) = ec_context.ec_value() {
+                let partner_store = require_partner_store(settings).ok();
+                let configs = partner_store
+                    .as_ref()
+                    .and_then(|s| s.fp_signal_configs().ok())
+                    .unwrap_or_default();
+                if configs.is_empty() {
+                    (vec![], vec![])
+                } else {
+                    let now_ms = std::time::SystemTime::now()
+                        .duration_since(std::time::UNIX_EPOCH)
+                        .map(|d| d.as_millis() as u64)
+                        .unwrap_or(0);
+                    let jar = ec_context.cookie_jar();
+                    let signals = jar
+                        .map(|j| extract_fp_signals(j, &configs, now_ms))
+                        .unwrap_or_default();
+                    (signals, configs)
+                }
+            } else {
+                (vec![], vec![])
+            }
+        } else {
+            (vec![], vec![])
+        };
+```
+
+- [ ] **Step 4: Include in `RouteOutcome`**
+
+Update the `RouteOutcome` construction:
+
+```rust
+    Ok(RouteOutcome {
+        response,
+        pull_sync_context,
+        fp_signals,
+        fp_signal_configs,
+    })
+```
+
+Also update all early-return `RouteOutcome` constructions (batch sync, auth failure, etc.) to include:
+
+```rust
+        fp_signals: vec![],
+        fp_signal_configs: vec![],
+```
+
+- [ ] **Step 5: Add post-send write in `main()`**
+
+Update the `main()` function's post-send block:
+
+```rust
+    let RouteOutcome {
+        response,
+        pull_sync_context,
+        fp_signals,
+        fp_signal_configs,
+    } = outcome;
+
+    response.send_to_client();
+
+    if !fp_signals.is_empty() {
+        if let Some(ref ctx) = pull_sync_context {
+            run_fp_signal_collection_after_send(settings, ctx.ec_id(), &fp_signals, &fp_signal_configs);
+        }
+    }
+
+    if let Some(context) = pull_sync_context {
+        run_pull_sync_after_send(&settings, &context);
+    }
+```
+
+- [ ] **Step 6: Add `run_fp_signal_collection_after_send`**
+
+Add after `run_pull_sync_after_send`:
+
+```rust
+fn run_fp_signal_collection_after_send(
+    settings: &Settings,
+    ec_id: &str,
+    signals: &[FpSignal],
+    configs: &[FpSignalPartnerConfig],
+) {
+    let kv = match require_identity_graph(settings) {
+        Ok(kv) => kv,
+        Err(err) => {
+            log::debug!("FP signal collection: identity graph unavailable: {err:?}");
+            return;
+        }
+    };
+    if let Err(err) = write_fp_signals(&kv, ec_id, signals, configs) {
+        log::warn!("FP signal collection failed: {err:?}");
+    }
+}
+```
+
+- [ ] **Step 7: Verify compilation**
+
+Run: `cargo check --workspace`
+Expected: compiles cleanly.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add crates/trusted-server-adapter-fastly/src/main.rs
+git commit -m "Wire first-party signal extraction and writing into adapter"
+```
+
+---
+
+### Task 12: Run full verification
+
+**Files:** none (verification only)
+
+- [ ] **Step 1: Run full test suite**
+
+Run: `cargo test --workspace`
+Expected: all tests PASS.
+
+- [ ] **Step 2: Run clippy**
+
+Run: `cargo clippy --workspace --all-targets --all-features -- -D warnings`
+Expected: no warnings.
+
+- [ ] **Step 3: Run format check**
+
+Run: `cargo fmt --all -- --check`
+Expected: no formatting issues.
+
+- [ ] **Step 4: Verify WASM build**
+
+Run: `cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1`
+Expected: builds successfully.
+
+- [ ] **Step 5: Fix any issues found and re-verify**
+
+If any step above fails, fix the issue and re-run all checks.
+
+- [ ] **Step 6: Final commit if any fixes were needed**
+
+Only if Step 5 produced changes.
diff --git a/docs/superpowers/specs/2026-04-09-first-party-signal-collection-design.md b/docs/superpowers/specs/2026-04-09-first-party-signal-collection-design.md
new file mode 100644
index 00000000..e0787c6e
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-09-first-party-signal-collection-design.md
@@ -0,0 +1,370 @@
+# First-Party Signal Collection — Design Spec
+
+**Date:** 2026-04-09
+**Status:** Draft
+
+## Motivation
+
+A Chrome user on a publisher domain carries first-party cookies from ~12 ad-tech
+partners. When a household member visits on Safari or Firefox — where those cookies
+were never set — the KV identity graph has no partner UIDs, bidstream is
+unenriched, and CPM is degraded.
+
+Seeding the KV entry from first-party cookie signals at request time means: by the
+time the Safari browser arrives, the KV entry already has IDs and the `/identify`
+response is fully populated without waiting for any sync event.
+
+## Decisions
+
+| #   | Decision                                                      | Rationale                                                                                                                                 |
+| --- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **Post-send execution**                                       | Zero added latency for the Chrome user. Race window (Safari arriving within the same second) is acceptable.                               |
+| 2   | **Extract pre-send, write post-send**                         | Cookie jar is available pre-send. Extraction is cheap (string ops). All KV I/O deferred to post-send.                                     |
+| 3   | **Denormalized `_fp_signal_enabled` index**                   | Single KV read pre-send gives all partner extraction configs. Avoids 1+N reads on the hot path.                                           |
+| 4   | **No Trade Desk `TDID_LOOKUP` guard**                         | YAGNI. If `TDID` is present and non-empty when `TDID_LOOKUP` is `"FALSE"`, it's a degenerate case handled by the standard empty-UID skip. |
+| 5   | **UID2 expiry check during extraction (pre-send)**            | The 5-minute buffer makes the pre-send vs post-send timing difference (~100ms) irrelevant. Keeps extraction self-contained.               |
+| 6   | **Batched CAS write (single read-modify-write)**              | All signals target the same KV entry. One read + one write instead of up to 12 CAS loops. Retry on conflict.                              |
+| 7   | **Approach B: Core-driven extraction, adapter orchestration** | Core crate owns domain logic. Adapter orchestrates timing. Consistent with pull sync architecture.                                        |
+
+## Architecture
+
+### Approach
+
+Core crate (`trusted-server-core`) exposes two functions:
+
+- `extract_fp_signals(jar, configs, now_ms)` — pure extraction, called pre-send
+- `write_fp_signals(kv, ec_id, signals, configs)` — batched CAS write, called post-send
+
+The adapter crate orchestrates timing: extraction happens during request
+handling, writing happens after the response is sent. This mirrors the pull
+sync pattern (`dispatch_pull_sync` is a core function called by the adapter
+post-send).
+
+### Request Flow
+
+```
+Request received
+  → EcContext::read_from_request_with_geo   (parse cookie jar, extract EC ID)
+  → EcContext::generate_if_needed           (create EC + initial KV entry if new)
+  → extract_fp_signals(jar, configs)        ← NEW (pre-send, cheap)
+  → finalize + send response
+  → run_fp_signal_collection_after_send     ← NEW (post-send, KV I/O)
+  → run_pull_sync_after_send                (existing, post-send)
+```
+
+## Data Model
+
+### New fields on `PartnerRecord`
+
+Added to `PartnerRecord` in `ec/partner.rs`:
+
+```rust
+/// First-party cookie names that may carry this partner's UID.
+/// Checked in order; first match wins.
+#[serde(default, skip_serializing_if = "Vec::is_empty")]
+pub fp_signal_cookie_names: Vec<String>,
+
+/// Dot-notation JSON path to extract the UID from a JSON cookie value.
+/// When absent, the raw cookie value is used as the UID.
+#[serde(default, skip_serializing_if = "Option::is_none")]
+pub fp_signal_json_path: Option<String>,
+
+/// Minimum seconds between re-collection writes for this partner.
+/// Defaults to 86400 (24 hours).
+#[serde(default = "PartnerRecord::default_fp_signal_ttl_sec")]
+pub fp_signal_ttl_sec: u64,
+```
+
+### Validation rules
+
+- `fp_signal_cookie_names`: each name must be non-empty, ASCII, no semicolons
+  or equals signs. Max 5 names per partner.
+- `fp_signal_json_path`: if present, must be non-empty, only alphanumeric +
+  dots + underscores. Max depth of 4 segments.
+- `fp_signal_ttl_sec`: minimum 60 seconds, maximum 604800 (7 days).
+
+### Denormalized `_fp_signal_enabled` index
+
+KV key `_fp_signal_enabled` stores a `Vec<FpSignalPartnerConfig>`:
+
+```rust
+pub struct FpSignalPartnerConfig {
+    pub partner_id: String,
+    pub cookie_names: Vec<String>,
+    pub json_path: Option<String>,
+    pub ttl_sec: u64,
+}
+```
+
+Maintained by `PartnerStore::upsert()` alongside the existing `_pull_enabled`
+and `apikey:` indexes. A partner is included when `fp_signal_cookie_names` is
+non-empty. Self-healing on next upsert.
+
+### Extracted signal struct
+
+```rust
+pub struct FpSignal {
+    pub partner_id: String,
+    pub uid: String,
+}
+```
+
+Passed from pre-send extraction to post-send writing.
+
+## Extraction (pre-send)
+
+### `extract_fp_signals`
+
+```rust
+pub fn extract_fp_signals(
+    jar: &CookieJar,
+    configs: &[FpSignalPartnerConfig],
+    now_ms: u64,
+) -> Vec<FpSignal>
+```
+
+**Algorithm:**
+
+1. For each config, iterate `cookie_names` in order. First cookie found in the
+   jar wins.
+2. If `json_path` is `Some`, parse cookie value as JSON, walk dot-separated
+   segments to a string leaf. On failure, log at debug and skip.
+3. If `json_path` is `None`, use the raw cookie value.
+4. If extracted UID is empty after trimming, skip.
+5. **UID2 special case:** If the cookie value parses as JSON and contains
+   `identity_expires`, check `identity_expires > now_ms + 300_000`. If not,
+   skip. Do not store `refresh_token`.
+6. Push `FpSignal { partner_id, uid }`.
+
+### JSON path walker
+
+```rust
+fn extract_json_path(value: &str, path: &str) -> Option<String>
+```
+
+Split `path` on `.`, walk `serde_json::Value` tree, return `Some(string)` if
+the leaf is a JSON string. Returns `None` on any failure.
+
+### Cookie jar access
+
+`EcContext` gains a `pub fn cookie_jar(&self) -> Option<&CookieJar>` accessor.
+The jar is already parsed in `read_from_request_with_geo` — we store it in the
+struct rather than discarding it.
+
+### Caller site (adapter)
+
+Runs when `is_real_browser && ec_context.ec_allowed()` and an EC value exists:
+
+```rust
+let fp_signals = if is_real_browser && ec_context.ec_allowed() && ec_context.ec_value().is_some() {
+    let configs = partner_store.fp_signal_configs().unwrap_or_default();
+    extract_fp_signals(ec_context.cookie_jar().unwrap(), &configs, now_ms)
+} else {
+    vec![]
+};
+```
+
+## Writing (post-send)
+
+### `write_fp_signals`
+
+```rust
+pub fn write_fp_signals(
+    kv: &KvIdentityGraph,
+    ec_id: &str,
+    signals: &[FpSignal],
+    configs: &[FpSignalPartnerConfig],
+) -> Result<(), Report<FpSignalError>>
+```
+
+**Algorithm:**
+
+1. Read KV entry for `ec_id` (entry + generation marker).
+2. If missing or tombstoned (`consent.ok == false`), return — no writes.
+3. Build `HashMap<partner_id, ttl_sec>` from configs for O(1) lookup.
+4. For each signal: if `entry.ids` contains the partner and
+   `now - existing.synced < ttl_sec`, skip (fresh).
+5. Insert all non-skipped signals into `entry.ids` as
+   `KvPartnerId { uid, synced: now }`.
+6. If no insertions, return — no write needed.
+7. CAS write with `if_generation_match`. On `ItemPreconditionFailed`, retry
+   the full loop (re-read, re-check, re-insert) up to `MAX_CAS_RETRIES` (3).
+
+### Adapter orchestration
+
+```rust
+fn run_fp_signal_collection_after_send(
+    settings: &Settings,
+    ec_id: &str,
+    signals: &[FpSignal],
+    configs: &[FpSignalPartnerConfig],
+) {
+    let kv = match require_identity_graph(settings) {
+        Ok(kv) => kv,
+        Err(err) => {
+            log::debug!("FP signal collection: identity graph unavailable: {err:?}");
+            return;
+        }
+    };
+    if let Err(err) = write_fp_signals(&kv, ec_id, signals, configs) {
+        log::warn!("FP signal collection failed: {err:?}");
+    }
+}
+```
+
+Called post-send, parallel to `run_pull_sync_after_send`. All errors logged and
+swallowed.
+
+## Index Maintenance
+
+### `PartnerStore::upsert()` changes
+
+After writing the partner record, a third index update step:
+
+1. Read current `_fp_signal_enabled` index (empty vec if missing).
+2. Remove any existing entry for this partner ID.
+3. If the upserted record has non-empty `fp_signal_cookie_names`, push a new
+   `FpSignalPartnerConfig`.
+4. Write the index back.
+
+Same best-effort, self-healing pattern as `_pull_enabled` and `apikey:` indexes.
+
+### New accessor
+
+```rust
+pub fn fp_signal_configs(&self) -> Result<Vec<FpSignalPartnerConfig>, Report<PartnerStoreError>>
+```
+
+Reads and deserializes `_fp_signal_enabled`. Returns empty vec if key missing
+or corrupt (degraded-behavior policy).
+
+## Known Partner Cookie Mapping
+
+Default partner configurations derived from autoblog.com Chrome cookie jar
+(2026-04-02):
+
+| Partner ID        | Cookie Names                             | JSON Path             | TTL (sec) | Notes                           |
+| ----------------- | ---------------------------------------- | --------------------- | --------- | ------------------------------- |
+| `id5`             | `["id5id"]`                              | `"universal_uid"`     | 86400     | JSON object                     |
+| `trade_desk`      | `["pbjs-unifiedid"]`                     | `"TDID"`              | 86400     | JSON object                     |
+| `liveramp_ats`    | `["idl_env"]`                            | —                     | 86400     | Raw envelope string             |
+| `lockr`           | `["lockr_tracking_id"]`                  | —                     | 86400     | Raw UUID                        |
+| `kargo`           | `["krg_uid"]`                            | `"v.userId"`          | 86400     | Doubly-nested JSON              |
+| `prebid_sharedid` | `["sharedId", "_sharedid", "_sharedID"]` | —                     | 86400     | Multiple cookie names           |
+| `lotame`          | `["panoramaId"]`                         | —                     | 86400     | Raw hex string                  |
+| `audigent`        | `["_au_1d"]`                             | —                     | 86400     | Raw string                      |
+| `yahoo_connectid` | `["connectId"]`                          | `"connectId"`         | 86400     | JSON object                     |
+| `lotame_cc`       | `["_cc_id"]`                             | —                     | 86400     | Raw hex string                  |
+| `uid2`            | `["__uid2_advertising_token"]`           | `"advertising_token"` | 3600      | Expiry-gated; see UID2 handling |
+| `arena`           | `["ArenaID", "_ig"]`                     | —                     | 86400     | Arena Group first-party ID      |
+
+This table ships as the default partner registry seed via
+`POST /_ts/admin/partners/register`.
+
+## UID2 Special Handling
+
+The `__uid2_advertising_token` cookie contains a short-TTL JSON object:
+
+```json
+{
+  "advertising_token": "A4AAADA...",
+  "refresh_token": "AAAAMCQR...",
+  "identity_expires": 1775421703943,
+  "refresh_expires": 1777754503943,
+  "refresh_from": 1775166103943
+}
+```
+
+**Harvest policy:**
+
+- Only write `advertising_token` if `identity_expires > now_ms + 300_000`
+  (at least 5 minutes of validity remaining).
+- Never store `refresh_token` — it is a credential, not an identity signal.
+- `fp_signal_ttl_sec` is 3600 to align with token lifetime.
+- UID2 token refresh (calling `/token/refresh`) is out of scope.
+
+The expiry check runs during extraction (pre-send). If the token fails the
+check, it is not included in the `FpSignal` vec.
+
+## Consent Gating
+
+First-party signal collection inherits the existing consent check. Extraction
+only runs when `ec_context.ec_allowed()` is true. Writing only proceeds if the
+KV entry is not tombstoned. No additional consent logic needed.
+
+## Error Handling
+
+- Extraction errors (bad JSON, missing path): logged at `debug`, partner skipped.
+- Write errors (KV unavailable, CAS exhaustion): logged at `warn`, swallowed.
+- A collection failure never affects the client response.
+
+## Performance
+
+**Pre-send (hot path):**
+
+- One KV read for the `_fp_signal_enabled` index.
+- String operations on cookie values — no I/O.
+- Bounded by number of configured partners (~12).
+
+**Post-send (off critical path):**
+
+- One KV read (entry + generation) + one KV write (batched upsert).
+- Returning users with all-fresh UIDs: one read, zero writes.
+- First visit with 12 partner cookies: one read + one write.
+- CAS retry on conflict: up to 3 attempts (matches existing pattern).
+
+## Module Structure
+
+### New file: `ec/fp_signals.rs`
+
+Contains:
+
+- `FpSignalPartnerConfig` — denormalized extraction config
+- `FpSignal` — extracted partner ID + UID pair
+- `FpSignalError` — module error type
+- `extract_fp_signals()` — pure extraction function
+- `extract_json_path()` — private JSON path walker
+- `write_fp_signals()` — batched CAS write
+
+### Files touched
+
+| File                             | Change                                                                                                                                                            |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ec/partner.rs`                  | Add 3 fields to `PartnerRecord`, validation, `default_fp_signal_ttl_sec()`                                                                                        |
+| `ec/partner.rs` (`PartnerStore`) | Maintain `_fp_signal_enabled` index in `upsert()`, add `fp_signal_configs()`                                                                                      |
+| `ec/fp_signals.rs`               | New module                                                                                                                                                        |
+| `ec/mod.rs`                      | Declare `pub mod fp_signals`, add `cookie_jar: Option<CookieJar>` field and `cookie_jar()` accessor to `EcContext`, store jar during `read_from_request_with_geo` |
+| `main.rs` (adapter)              | Pre-send: extract signals. Post-send: write signals.                                                                                                              |
+
+## Testing Strategy
+
+### Unit tests in `ec/fp_signals.rs`
+
+1. **JSON path extraction:** single key, nested dot path, missing key,
+   non-string leaf, invalid JSON, empty path (raw value).
+2. **Cookie extraction:** single cookie match, first-match-wins across
+   multiple names, missing cookie skips, empty UID skips, JSON path from
+   cookie value.
+3. **UID2 special case:** valid token extracted, expired token skipped,
+   missing `identity_expires` treated as non-UID2.
+4. **Batched write:** all fresh (no write), mix of fresh and stale, all new,
+   tombstoned entry (no write), missing entry (no write).
+
+### Unit tests in `ec/partner.rs`
+
+5. **Validation:** valid FP signal config accepted, empty cookie name
+   rejected, invalid JSON path rejected, TTL out of bounds rejected.
+6. **Index maintenance:** upsert with FP config adds to index, upsert
+   without FP config removes from index.
+
+### Integration
+
+Existing `cargo test --workspace` via Viceroy exercises the full KV path.
+Batched CAS write tests use Viceroy KV store.
+
+## Out of Scope
+
+- UID2 token refresh (requires separate operator integration).
+- Trade Desk `TDID_LOOKUP` guard field.
+- Automatic partner discovery (partners are registered via admin API).
+- Client-side signal collection (this is server-side only).