Open the integration seam so a vendor module can live outside core

.cargo/config.toml

@@ -26,10 +26,10 @@ test_details = "test --target aarch64-apple-darwin"
 # native crate needs no change here. Axum (native), Cloudflare
 # (wasm32-unknown-unknown), Spin, the CLI (native), and integration-tests
 # (native) are simply not listed.
-build-fastly = "build -p trusted-server-core -p trusted-server-adapter-fastly -p trusted-server-js -p trusted-server-openrtb --target wasm32-wasip1"
-check-fastly = "check -p trusted-server-core -p trusted-server-adapter-fastly -p trusted-server-js -p trusted-server-openrtb --target wasm32-wasip1"
-clippy-fastly = "clippy -p trusted-server-core -p trusted-server-adapter-fastly -p trusted-server-js -p trusted-server-openrtb --all-targets --all-features --target wasm32-wasip1 -- -D warnings"
-test-fastly = "test -p trusted-server-core -p trusted-server-adapter-fastly -p trusted-server-js -p trusted-server-openrtb --target wasm32-wasip1"
+build-fastly = "build -p trusted-server-core -p trusted-server-adapter-fastly -p trusted-server-device-fastly -p trusted-server-geo-fastly -p trusted-server-js -p trusted-server-openrtb --target wasm32-wasip1"
+check-fastly = "check -p trusted-server-core -p trusted-server-adapter-fastly -p trusted-server-device-fastly -p trusted-server-geo-fastly -p trusted-server-js -p trusted-server-openrtb --target wasm32-wasip1"
+clippy-fastly = "clippy -p trusted-server-core -p trusted-server-adapter-fastly -p trusted-server-device-fastly -p trusted-server-geo-fastly -p trusted-server-js -p trusted-server-openrtb --all-targets --all-features --target wasm32-wasip1 -- -D warnings"
+test-fastly = "test -p trusted-server-core -p trusted-server-adapter-fastly -p trusted-server-device-fastly -p trusted-server-geo-fastly -p trusted-server-js -p trusted-server-openrtb --target wasm32-wasip1"
 
 # --- Axum adapter (native dev server) ---
 build-axum = "build -p trusted-server-adapter-axum"

.env.example

@@ -40,41 +40,33 @@ TRUSTED_SERVER__REQUEST_SIGNING__ENABLED=false
 # =============================================================================
 # Integrations
 # =============================================================================
+# Which integrations run is set in the TOML file, as
+# `[integration] provider = ["prebid", "nextjs"]`. There is no per-integration
+# enabled flag any more. An overlay below changes a setting the file already
+# carries, and it cannot add one the file leaves out.
 
-# Prebid
-TRUSTED_SERVER__INTEGRATIONS__PREBID__ENABLED=false
-# TRUSTED_SERVER__INTEGRATIONS__PREBID__SERVER_URL=https://prebid-server.example.com/openrtb2/auction
-# TRUSTED_SERVER__INTEGRATIONS__PREBID__TIMEOUT_MS=1000
-# TRUSTED_SERVER__INTEGRATIONS__PREBID__BIDDERS=kargo,rubicon,appnexus
-# TRUSTED_SERVER__INTEGRATIONS__PREBID__BID_PARAM_OVERRIDES='{"bidder-name":{"param1":12345,"param2":"value"}}'
-# Compatibility env shape for bidder -> zone -> params overrides
-# TRUSTED_SERVER__INTEGRATIONS__PREBID__BID_PARAM_ZONE_OVERRIDES='{"kargo":{"header":{"placementId":"_abc"}}}'
-# Preferred canonical env shape for future generic rules
-# TRUSTED_SERVER__INTEGRATIONS__PREBID__BID_PARAM_OVERRIDE_RULES='[{"when":{"bidder":"kargo","zone":"header"},"set":{"placementId":"_abc"}}]'
-# TRUSTED_SERVER__INTEGRATIONS__PREBID__SUPPRESS_NURL_BIDDERS=exampleBidder,anotherBidder
-# TRUSTED_SERVER__INTEGRATIONS__PREBID__AUTO_CONFIGURE=false
-# TRUSTED_SERVER__INTEGRATIONS__PREBID__DEBUG=false
-# TRUSTED_SERVER__INTEGRATIONS__PREBID__TEST_MODE=false
+# Prebid, the browser side. The Prebid Server endpoint is a demand source now,
+# so it is set under Demand sources below rather than here.
+# TRUSTED_SERVER__INTEGRATION__PREBID__ACCOUNT_ID=
+# TRUSTED_SERVER__INTEGRATION__PREBID__TIMEOUT_MS=1000
+# TRUSTED_SERVER__INTEGRATION__PREBID__CLIENT_SIDE_BIDDERS__0=kargo
+# TRUSTED_SERVER__INTEGRATION__PREBID__DEBUG=false
 
 # Next.js
-TRUSTED_SERVER__INTEGRATIONS__NEXTJS__ENABLED=false
-# TRUSTED_SERVER__INTEGRATIONS__NEXTJS__REWRITE_ATTRIBUTES=href,link,url
+# TRUSTED_SERVER__INTEGRATION__NEXTJS__REWRITE_ATTRIBUTES=href,link,url
 
 # Didomi
-TRUSTED_SERVER__INTEGRATIONS__DIDOMI__ENABLED=false
-# TRUSTED_SERVER__INTEGRATIONS__DIDOMI__SDK_ORIGIN=https://sdk.privacy-center.org
-# TRUSTED_SERVER__INTEGRATIONS__DIDOMI__API_ORIGIN=https://api.privacy-center.org
+# TRUSTED_SERVER__INTEGRATION__DIDOMI__SDK_ORIGIN=https://sdk.privacy-center.org
+# TRUSTED_SERVER__INTEGRATION__DIDOMI__API_ORIGIN=https://api.privacy-center.org
 
 # Permutive
-TRUSTED_SERVER__INTEGRATIONS__PERMUTIVE__ENABLED=false
-# TRUSTED_SERVER__INTEGRATIONS__PERMUTIVE__ORGANIZATION_ID=
-# TRUSTED_SERVER__INTEGRATIONS__PERMUTIVE__WORKSPACE_ID=
-# TRUSTED_SERVER__INTEGRATIONS__PERMUTIVE__PROJECT_ID=
+# TRUSTED_SERVER__INTEGRATION__PERMUTIVE__ORGANIZATION_ID=
+# TRUSTED_SERVER__INTEGRATION__PERMUTIVE__WORKSPACE_ID=
+# TRUSTED_SERVER__INTEGRATION__PERMUTIVE__PROJECT_ID=
 
 # Lockr
-TRUSTED_SERVER__INTEGRATIONS__LOCKR__ENABLED=false
-# TRUSTED_SERVER__INTEGRATIONS__LOCKR__APP_ID=
-# TRUSTED_SERVER__INTEGRATIONS__LOCKR__CACHE_TTL_SECONDS=3600
+# TRUSTED_SERVER__INTEGRATION__LOCKR__APP_ID=
+# TRUSTED_SERVER__INTEGRATION__LOCKR__CACHE_TTL_SECONDS=3600
 
 # =============================================================================
 # Rewrite Configuration (optional)

.github/workflows/inspector.yml

@@ -0,0 +1,26 @@
+name: "Permissions Inspector"
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build-inspector-wasm:
+    name: build inspector wasm
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Retrieve Rust version
+        id: rust-version
+        run: echo "rust-version=$(grep -oP 'channel = "\K[^"]+' rust-toolchain.toml)" >> "$GITHUB_OUTPUT"
+      - name: Set up Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: ${{ steps.rust-version.outputs.rust-version }}
+          target: wasm32-unknown-unknown
+      - name: Build the inspector engine
+        run: ./scripts/build-inspector-wasm.sh

.github/workflows/test.yml

@@ -66,8 +66,12 @@ jobs:
         run: BID_DELAY=3 ./scripts/template-cache-local-test.sh inline
 
   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
 
@@ -104,12 +108,33 @@ jobs:
         run: |
           cargo test --package trusted-server-openrtb-codegen --target "$(rustc -vV | sed -n 's/host: //p')"
 
+      # The core library's unit tests otherwise run only on the WebAssembly
+      # targets, which build with panic=abort, so their harness stops at the
+      # first failing test and reports every later one as never run. A run that
+      # looks like a single failure can hide many more. This native run reports
+      # them all at once, which is what makes a red build readable.
+      - name: Run host-target core library tests
+        run: |
+          cargo test --package trusted-server-core --target "$(rustc -vV | sed -n 's/host: //p')"
+
+      # The seam-probe fixture crate's own unit tests only run when invoked on
+      # the host target, because no adapter alias compiles its test target. Run
+      # them here so a fault in the seam fixture cannot sit unseen behind a
+      # green gate set.
+      - name: Run host-target seam-probe integration tests
+        run: |
+          cargo test --package trusted-server-integration-seam-probe --target "$(rustc -vV | sed -n 's/host: //p')"
+
       - name: Verify Fastly WASM release build
         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/

AGENTS.md

@@ -21,6 +21,11 @@ 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 provider is in core)
+  geo/                                  # vendor geo provider crates (host geo is injected by the adapter)
+  permission-signal/                    # permission signal provider crates, one per scheme (gpc, gpp, tcf, us-privacy), and core links none
   trusted-server-js/                    # TypeScript/JS build — per-integration IIFE bundles
     lib/         # TS source, Vitest tests, esbuild pipeline
 ```
@@ -59,7 +64,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
@@ -145,6 +152,24 @@ 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 them on `ubuntu-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.
+The CLI crate (`trusted-server-cli`) does not build on a Windows host either,
+because its dependency `edgezero-adapter-fastly` uses a standard library
+feature that is unstable on Windows, so run its tests and the template cache
+harness (`scripts/template-cache-local-test.sh`), which builds it, in WSL too.
+
 ---
 
 ## Coding Conventions
@@ -272,12 +297,48 @@ 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 many 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.
+
+**Evidence is not rationed, use is.** Every provider and every integration sees
+all the evidence available for a request, including host signals such as the TLS
+JA4 and HTTP/2 signals. The core never decides which vendor may see what,
+because withholding a signal from one vendor and not another discriminates
+between them, and the core stays neutral. What a vendor may *do* with the
+evidence is governed by the permissions it declares and the system sets. Access
+is universal, use is gated.
+
+The practical consequence: never "fix" a vendor's access to a signal by hiding
+the signal. If a use needs controlling, express it as a permission. A change
+that removes evidence from a provider's reach is working against the
+architecture, not protecting it.
+
+- 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
@@ -294,6 +355,54 @@ 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. Every
+pluggable thing follows one configuration convention, which is a top-level
+table named for the job, a `provider` key that selects what runs, and a
+`[<type>.<name>]` table for a provider that has settings. The rules and what
+is checked when are in `docs/guide/configuration-rules.md`, which is the page
+to read before changing any provider configuration.
+
+| Capability            | Trait                                    | Selector                  | Built-in (core)                              | Vendor / host crates         |
+| --------------------- | ---------------------------------------- | ------------------------- | -------------------------------------------- | ---------------------------- |
+| Edge Cookie identity  | `EdgeCookieProvider` (`ec/provider.rs`)  | `[ec] provider`           | `hmac`, `host_signals`, `client_fixed` (opt-in, no default) | `crates/edgecookie/<vendor>` |
+| Device detection      | `DeviceProvider` (`ec/device.rs`)        | `[device] provider`       | `builtin`, User-Agent only (the default)     | `crates/device/<vendor>`     |
+| Geo / IP intelligence | `PlatformGeo` (`platform/traits.rs`)     | `[geo] provider`          | None, no location (the default), or `platform` | `crates/geo/<vendor>`      |
+| Permission signals    | `PermissionSignalProvider` (`permission_signal/mod.rs`) | `[permission_signal] provider` (an ordered list) | `gpc`, `gpp_sale_opt_out`, `us_privacy`, `tcf`, all of them with no list | `crates/permission-signal/<scheme>` |
+| Auction demand        | `DemandImplementation` (`auction/demand.rs`) | `[demand] provider` (a list) | `openrtb`, `prebid_server`, `aps`        | an integration builder       |
+| Ad server             | `AdServerImplementation` (`auction/demand.rs`) | `[adserver] provider` | `adserver_mock`                            | an integration builder       |
+| Page integrations     | `IntegrationBuilder` (`integrations/mod.rs`) | `[integration] provider` (a list) | `datadome`, `didomi`, `google_tag_manager`, `gpt`, `gpt_diagnostics`, `js_asset_proxy`, `lockr`, `nextjs`, `osano`, `permutive`, `prebid`, `sourcepoint`, `testlight` | an adapter-supplied builder |
+
+`openrtb`, `prebid_server`, `aps` and `adserver_mock` supply implementations
+only. They are not page integrations and cannot be named in
+`[integration] provider`.
+
+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 signals) 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 signal 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
+  multiple 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:
@@ -307,7 +416,8 @@ IntegrationRegistration::builder(ID)
 ```
 
 - Integration IDs match JS directory names: `prebid` (deferred), `lockr`, `permutive`, `datadome`, `didomi`, `testlight`.
-- `creative` is JS-only (no Rust registration); `nextjs`, `aps`, `adserver_mock` are Rust-only.
+- An integration runs when `[integration] provider` names it. There is no `enabled` flag.
+- `creative` is JS-only (no Rust registration), and `nextjs` is Rust-only. `openrtb`, `prebid_server`, `aps` and `adserver_mock` register demand or ad server implementations rather than page integrations.
 - Integrations opt into deferred loading via `.with_deferred_js()` on the registration builder. Deferred modules are served as separate `<script defer>` tags instead of being concatenated into the main bundle.
 - `IntegrationRegistry::js_module_ids_immediate()` returns modules for the main bundle; `js_module_ids_deferred()` returns modules loaded with `defer`.
 
@@ -317,7 +427,7 @@ IntegrationRegistration::builder(ID)
 - Output: `dist/tsjs-core.js`, `dist/tsjs-{integration}.js`.
 - `build.rs` auto-generates `tsjs_modules.rs` with `include_str!()` for each discovered file.
 - `bundle.rs` provides `concatenate_modules(ids)` and `concatenated_hash(ids)` APIs.
-- Runtime: Rust server concatenates core + enabled integration JS files at request time.
+- Runtime: Rust server concatenates core + the JS files of the integrations that run, at request time.
 
 ---
 
@@ -327,7 +437,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]`, `[permission_signal]`, `[demand]`, `[adserver]` and `[integration]` provider selectors) |
 | `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                         |