Add pluggable Edge Cookie, device, and geo providers gated by a permission model

Replace three hard-wired request-time decisions with
configuration-selected providers behind small traits: Edge Cookie
identity (EdgeCookieProvider), the device classification the bot gate
uses (DeviceProvider), and geolocation (PlatformGeo). Gate a provider's
execution on a technical permission model that separates legal policy
from the core, and remove the country-based allows_ec_creation
branching.

Permissions are the single currency every service and provider reads,
and none reads consent directly. Consent is one of several sources (the
country and region baseline, a consent signal, a configuration decision,
or data from elsewhere) that set a request's permissions. Feature and
provider code works against a clean, stable set that does not change as
laws or consent frameworks change; a source needing a new distinction
adds a permission to the model rather than leaking a branch into
consumers. The country and region rules live in a human-editable
permissions.yaml embedded into the build (include_str! in
permissions.rs), so a policy owner changes them in version control
rather than in code. It defines named groups that each spell out every
permission flag (gdpr-eu, gdpr-uk, us-opt-out) and rules mapping a
country or country/state to a group, with optional +permission (granted)
or -permission (denied) overrides. Rule keys use the ISO 3166-1 alpha-2
country and ISO 3166-2 subdivision codes a geo provider returns, matched
case-insensitively, so any geo provider feeds the same rules without
translation. PermissionMaps::standard() parses the file once into a
static cache and hands out a shared reference (no per-request clone). A
request that matches no rule, or whose country the geo provider cannot
resolve, uses the deployer's [geo] default_country. Trusted Server does
not assume a jurisdiction, so that default is required and validated at
startup: startup fails when it is unset or does not resolve to a known
rule. The shipped example uses the most protective baseline (FR,
GDPR-EU, where every permission requires a signal); a deployer sets the
jurisdiction that governs its traffic. Because policy is a declarative
map rather than branching code, a third party can read permissions.yaml
and see exactly what each permission resolves to for any country or
region.

Control stays in the core. A provider advertises the permissions its
data use requires (required_permissions()), and the core, not the
provider, decides whether it runs: it resolves the request's
PermissionState once (in EcContext) and refuses to execute a provider
whose required permissions are not set, so generate_if_needed returns
before the provider is even built.

Route every Trusted Server data decision through the resolved
permissions, not Edge Cookie creation alone. Bidstream EID transmission
gates on the resolved store-on-device and select-personalised-ads
permissions (gate_eids_by_permissions) instead of re-inspecting TCF and
a raw gdpr_applies flag. A request whose permissions do not allow the
Edge Cookie always has its EC response headers stripped, but the
destructive step (expire the browser cookie, delete the consent KV
entry, write the identity-graph tombstone) fires only on an explicit
withdrawal signal (ec_storage_withdrawn: a TCF record refusing storage,
or a US-style opt-out), never on a merely not-permitted state. This
holds on every path: ec_finalize_response, the publisher proxy
(apply_ec_headers), and both adapter bot gates. A pre-consent or
fail-closed request therefore suppresses the Edge Cookie for that
response but does not destroy an already-issued identifier before the
user has had the chance to consent. The jurisdiction-gated
has_explicit_ec_withdrawal and ec_consent_withdrawn are gone.

Map consent to a per-permission signal in one place (permission_signal).
A TCF record is authoritative wherever present, so the EU defers to the
CMP; a US-style opt-out (GPC, GPP sale opt-out, US Privacy opt-out)
revokes a granted baseline, and the map decides where a revoke has an
effect. Precedence is explicit: a present TCF record wins over a
US-style opt-out. Downstream RTB partners (Prebid, APS) still receive
the full regulatory context forwarded verbatim and run their own
enforcement; the permission model governs only Trusted Server's own
actions.

Wire providers by dependency injection. A provider reads request
evidence through the RequestInfo and HostSignals traits (evidence.rs)
rather than a fixed field struct, borrowed at call time so no
per-request HeaderMap is cloned. RequestInfo carries request data any
host can supply (client IP, User-Agent, headers); HostSignals carries
the host-computed TLS JA4 and HTTP/2 fingerprints and is opt-in, so a
neutral provider triggers no host fingerprint call. The adapter is the
composition root: it captures host signals once at the entry point and
supplies them, and a provider that needs a service the host cannot
supply cannot be built, so the request stops rather than minting a
degraded identifier. Core defines the traits and the neutral built-in
defaults and never calls a host SDK.

Support two Edge Cookie provider shapes behind the one trait. A
server-side provider mints at the edge: the built-in HMAC provider (over
the client IP), or a host-signal provider that derives the identifier
from the host fingerprints and client IP on any host that supplies a
HostSignals. A client-side provider defers on the page request, lets the
browser do the work, and posts the result to a new POST
/_ts/api/v1/ec/resolve endpoint that mints the cookie from the verified
value on its own response; verifying the posted value is the provider's
responsibility, so a client cannot forge an Edge Cookie. A neutral
client-fixed demo provider (client and server share one fixed known word
the server verifies) exercises the path end to end with a page script
shipped in the tsjs bundle when it is selected, and is for testing only.

Move the opt-in Fastly device and host geo providers into their own
crates (crates/device/fastly, crates/geo/fastly), selected and injected
by the adapter, so core keeps only the DeviceProvider and PlatformGeo
traits and the neutral defaults. The Fastly device provider reads the
User-Agent from the borrowed RequestInfo and the fingerprints from a
FastlyHostSignals built from the live request, and the adapter shares
that FastlyHostSignals as the host-signal service so the host-signal
Edge Cookie provider can use it too. A placeholder crates/edgecookie
directory marks where vendor Edge Cookie provider crates will live.

Restructure the [ec] configuration section (breaking change). The flat
[ec] passphrase field is removed and [ec] rejects unknown fields, so a
config carrying it fails to parse; the HMAC key moves to
[ec.providers.hmac] passphrase. Edge Cookie identity is off by default:
EC runs only when [ec] provider names a configured provider, so a config
that adds [ec.providers.hmac] but omits provider = "hmac" parses cleanly
and runs statelessly. Migration for an existing deployment:

    [ec]
    provider = "hmac"

    [ec.providers.hmac]
    passphrase = "your-existing-passphrase"

The provider selectors ([ec]/[device]/[geo] provider) and the mandatory
[geo] default_country are validated inside
Settings::finalize_deserialized, the single point every deserialization
path shares (TOML file, the runtime config-store blob, and the ts CLI
config push), so no load path can bypass the checks.
trusted-server.example.toml is the checked-in template and shows the new
sections. The default jurisdiction baseline is logged once per settings
load so an operator can see which permissions the unmatched-request
default grants without a signal.

Add an IntegrationResponseMutator hook for outbound response headers. No
built-in integration registers one yet; the registry carries the hook so
an integration crate (for example bot protection emitting Accept-CH) can
register a mutator without a core change.

Standardize spelling on US English, recorded as the convention in
CLAUDE.md, keeping external-source terms such as the IAB TCF purpose
names as their source spells them. Add the provider-architecture and
permission-model sections to CLAUDE.md, and document the model, the
provider selectors, and the permission sources in the guides.

Cover Windows in CI. The Rust adapter test jobs run on both
ubuntu-latest and windows-latest. The Docker-based integration suite and
the Cloudflare worker build remain Linux tools, run through WSL on
Windows as CLAUDE.md documents. The integration app-config fixture
selects the HMAC provider and sets [geo] default_country = US/CA, so a
request with no resolvable geolocation under Viceroy maps to a US
opt-out baseline and the GPC-withdrawal scenario exercises
permission-driven cookie expiry.

Author: jwrosewell

.github/workflows/test.yml

@@ -11,8 +11,12 @@ on:
 
 jobs:
   test-rust:
-    name: cargo test
-    runs-on: ubuntu-latest
+    name: cargo test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
     steps:
       - uses: actions/checkout@v4
 
@@ -50,8 +54,12 @@ jobs:
         run: cargo test-fastly
 
   test-axum:
-    name: cargo test (axum native)
-    runs-on: ubuntu-latest
+    name: cargo test (axum native, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
     steps:
       - uses: actions/checkout@v4
 
@@ -92,8 +100,12 @@ jobs:
         run: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
 
   test-cloudflare:
-    name: cargo check (cloudflare native + wasm32-unknown-unknown)
-    runs-on: ubuntu-latest
+    name: cargo check (cloudflare native + wasm32-unknown-unknown, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
     steps:
       - uses: actions/checkout@v4
 

.gitignore

@@ -16,6 +16,9 @@
 /spin
 /spin.sig
 
+# logs
+*.log
+
 # EdgeZero local KV store (created by edgezero-adapter-axum framework)
 .edgezero/
 /dist/prebid/

CLAUDE.md

@@ -19,6 +19,10 @@ crates/
   trusted-server-adapter-cloudflare/    # Cloudflare Workers entry point (wasm32-unknown-unknown binary)
   trusted-server-adapter-spin/          # Fermyon Spin entry point (wasm32-wasip1 component)
   trusted-server-cli/                   # Host-target `ts` operator CLI
+  device/
+    fastly/                             # trusted-server-device-fastly (opt-in TLS/H2 device provider)
+  edgecookie/                           # vendor Edge Cookie provider crates (built-in HMAC default is in core)
+  geo/                                  # vendor geo provider crates (host geo is injected by the adapter)
   trusted-server-js/                    # TypeScript/JS build — per-integration IIFE bundles
     lib/         # TS source, Vitest tests, esbuild pipeline
 ```
@@ -57,7 +61,9 @@ fastly compute serve
 # Deploy to Fastly
 fastly compute publish
 
-# Run Axum dev server (native — no Viceroy)
+# Run Axum dev server (native — no Viceroy). Settings load at runtime from the
+# platform config store on every adapter; publish an operator config with
+# `ts config push` (see trusted-server.example.toml for the template).
 cargo run -p trusted-server-adapter-axum
 
 # Test Axum adapter only
@@ -141,6 +147,20 @@ cd crates/trusted-server-js/lib && node build-all.mjs
 cargo install viceroy --version 0.17.0 --locked --force
 ```
 
+### Windows (use WSL for the Linux-only tests)
+
+The Rust adapter tests run natively on Windows through the cargo aliases
+(`cargo test-fastly` via Viceroy, `cargo test-axum`, `cargo test-cloudflare`),
+and CI runs these on both `ubuntu-latest` and `windows-latest`.
+
+The Docker-based integration suite (`scripts/integration-tests.sh`) and the
+Cloudflare worker build (`crates/trusted-server-adapter-cloudflare/build.sh`,
+which uses `worker-build` + `wrangler dev`) are Linux tools. On Windows run them
+inside WSL (Ubuntu) with Docker Desktop's WSL integration enabled. Provision the
+WSL distro with the same toolchain as `.tool-versions` (rustup + the
+`wasm32-wasip1` / `wasm32-unknown-unknown` targets, Node, Viceroy, wrangler), then
+run the scripts from a clone on the WSL native filesystem for fast builds.
+
 ---
 
 ## Coding Conventions
@@ -268,12 +288,34 @@ impl core::error::Error for MyError {}
 
 ## Other guidelines
 
+- Use US English spelling everywhere: code, identifiers, comments,
+  documentation, tests, commit messages, and configuration. For example, write
+  `color`, `behavior`, and `optimize`, not `colour`, `behaviour`, or `optimise`.
+  Where a term comes from an external source (for example the IAB TCF purpose
+  names), match that source's spelling even when it is not US English.
 - Use only example or fictional information in comments, tests, docs, examples,
   and similar non-runtime materials. (eg. for urls use: example.com domains only)
 - Do not write or commit real domains, customer names, credentials,
   configuration values, or other potentially sensitive real-world information in
   comments, tests, docs, or examples.
 
+### Permission model terminology
+
+Permissions are the primitive. A provider declares the permissions it requires
+(`required_permissions`) and the system decides whether each is _set_. Consent
+is only one of several ways a permission may be established. Country or
+jurisdiction rules (a `Granted` group baseline), legitimate interest, or
+configuration can set a permission with no consent at all.
+
+- A provider that needs nothing **requires no permission**. Never write that it
+  "runs without any consent".
+- A gated provider **runs once its required permissions are set**, by whatever
+  method.
+- Reserve "consent" for the consent subsystem (`consent/`, `ConsentContext`,
+  GDPR and TCF strings) where it genuinely means a consent signal. In the
+  permission layer prefer "permission", "set" / "unset", and "signal" (consent
+  is one kind of signal, alongside privacy and opt-out signals).
+
 ---
 
 ## Git Commit Conventions
@@ -290,6 +332,41 @@ Bad: `"fix: added feature flags"`
 
 ---
 
+## Provider Architecture
+
+Each vendor-differentiated capability is pluggable behind its own trait, so a
+deployment selects an implementation and the core stays neutral:
+
+| Capability            | Trait                                    | Selector            | Built-in (core)                         | Vendor / host crates         |
+| --------------------- | ---------------------------------------- | ------------------- | --------------------------------------- | ---------------------------- |
+| Edge Cookie identity  | `EdgeCookieProvider` (`ec/provider.rs`)  | `[ec] provider`     | HMAC, client-fixed (opt-in, no default) | `crates/edgecookie/<vendor>` |
+| Device detection      | `DeviceProvider` (`ec/device.rs`)        | `[device] provider` | User-Agent only (default)               | `crates/device/<vendor>`     |
+| Geo / IP intelligence | `PlatformGeo` (`platform/traits.rs`)     | `[geo] provider`    | Disabled, no location (default)         | `crates/geo/<vendor>`        |
+
+Principles for adding or changing a provider:
+
+- **Core stays neutral.** The trait and the host-neutral default live in
+  `trusted-server-core`. Host-specific and vendor implementations live in their
+  own crates and are injected by the adapter (for example `build_device_provider`
+  and `build_geo_provider`), so core never depends on a host SDK or a vendor, and
+  the default request path makes no host-specific calls.
+- **Providers read request evidence, not a fixed parameter set.** A provider must
+  be able to see everything about the request it needs (User-Agent, headers, and
+  host signals such as the TLS JA4 and HTTP/2 fingerprints) through an evidence
+  abstraction rather than a hard-coded struct of fields. Host signals come from
+  the host (the Fastly SDK) and are opt-in, so a neutral provider triggers no
+  host fingerprint calls.
+- **Providers are separated by capability but composed per request, and one may
+  need another's output.** Geo resolves the country and region the permission
+  model uses, and the permission model gates whether the Edge Cookie provider
+  runs. Device signals gate Edge Cookie writes (the browser / bot gate). When
+  several vendor providers share a backend (for example a vendor's Edge Cookie,
+  geo, and device provider on one cloud pipeline) they share a single call per
+  request rather than calling independently. Give a provider the inputs and
+  upstream results it needs explicitly, rather than having it reach into globals.
+
+---
+
 ## Integration System
 
 Integrations register in Rust via:
@@ -323,7 +400,7 @@ IntegrationRegistration::builder(ID)
 | --------------------- | ---------------------------------------------------------- |
 | `edgezero.toml`                 | EdgeZero app/platform manifest and logical stores               |
 | `fastly.toml`                   | Fastly service configuration and build settings                 |
-| `trusted-server.example.toml`   | Source-controlled Trusted Server app-config template            |
+| `trusted-server.example.toml`   | Source-controlled app-config template (includes the `[ec]` / `[geo]` / `[device]` provider selectors and `[geo] default_country`) |
 | `trusted-server.toml`           | Operator-owned app config; gitignored; `ts config push` publishes it as an EdgeZero blob envelope |
 | `rust-toolchain.toml`           | Pins Rust version to 1.95.0                                     |
 | `.env.dev`                      | Local development environment variables                         |

Cargo.lock

@@ -1,6 +1,8 @@
 [workspace]
 resolver = "2"
 members = [
+    "crates/device/fastly",
+    "crates/geo/fastly",
     "crates/trusted-server-adapter-axum",
     "crates/trusted-server-adapter-cloudflare",
     "crates/trusted-server-adapter-fastly",
@@ -92,6 +94,7 @@ rustls-pemfile = "2"
 scraper = "0.24.0"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0.149"
+serde_yaml_ng = "0.10"
 sha2 = "0.10.9"
 simple_logger = "5"
 spin-sdk = { version = "~6.0", default-features = false, features = ["http", "key-value", "variables"] }
@@ -106,6 +109,8 @@ toml = "1.1"
 toml_edit = "0.23.10"
 tower = "0.4"
 trusted-server-core = { path = "crates/trusted-server-core" }
+trusted-server-device-fastly = { path = "crates/device/fastly" }
+trusted-server-geo-fastly = { path = "crates/geo/fastly" }
 trusted-server-js = { path = "crates/trusted-server-js" }
 trusted-server-openrtb = { path = "crates/trusted-server-openrtb" }
 url = "2.5.8"

Cargo.toml

@@ -0,0 +1,10 @@
+# Device providers
+
+Device-detection provider crates live here, one per vendor. The Fastly provider
+(`trusted-server-device-fastly`) classifies a request with the host's TLS and
+HTTP/2 fingerprints; future vendor providers (for example
+`crates/device/<vendor>`) slot in alongside it.
+
+The built-in default provider (User-Agent only) ships in `trusted-server-core`
+(`ec::device`). Adapters select and inject the vendor provider via
+`build_device_provider`.

crates/device/README.md

@@ -0,0 +1,18 @@
+[package]
+name = "trusted-server-device-fastly"
+description = "Fastly host device provider exposing opt-in TLS and HTTP/2 signals."
+authors = { workspace = true }
+edition = { workspace = true }
+license = { workspace = true }
+publish = { workspace = true }
+version = { workspace = true }
+
+[lib]
+doctest = false
+
+[lints]
+workspace = true
+
+[dependencies]
+trusted-server-core = { workspace = true }
+fastly = { workspace = true }