Add device and geo module selection with the host-signal Edge Cookie module

.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"
 # Feature-on counterpart of `test-fastly`. `test-fastly` does NOT pass
 # --all-features, so without this the reusable-sandbox code is linted by
 # `clippy-fastly` but its tests never execute.

Cargo.toml

@@ -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",
@@ -120,6 +122,8 @@ toml_edit = "0.23.10"
 tower = "0.4"
 tracing = "0.1"
 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"

crates/device/README.md

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

crates/device/fastly/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "trusted-server-device-fastly"
+description = "Fastly host device module 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 }
+
+# The visible owner of this vendor crate, the way Prebid.js requires a named
+# maintainer of every adapter. Fastly has not yet adopted this crate, so the
+# Trusted Server maintainers own it until a vendor owner steps up.
+[package.metadata.maintainers]
+owner = "Trusted Server maintainers"
+status = "seeking vendor owner"

crates/device/fastly/src/lib.rs

@@ -0,0 +1,98 @@
+//! The Fastly device module and host-signal capture.
+//!
+//! [`FastlyDeviceModule`] strengthens the built-in User-Agent classification
+//! with the host's TLS (JA4) and HTTP/2 signals, for deployments on Fastly
+//! Compute. It is selected by `[device] module = "fastly"` and wired in by the
+//! Fastly adapter, which injects the request info and the captured host signals.
+//!
+//! [`FastlyHostSignals`] captures those signals from a live Fastly request
+//! (`get_tls_ja4()`, `get_client_h2_fingerprint()`) into owned values, so it can
+//! be shared as an injected [`HostSignals`] service that outlives the borrow of
+//! the request. Capturing through the SDK is why this crate depends on the
+//! `fastly` crate and builds only for the `wasm32-wasip1` target; off-host the
+//! accessors return `None`, so classification degrades to User-Agent only. The
+//! platform-neutral [`HostSignals`], [`RequestInfo`], and [`DeviceModule`]
+//! traits and the built-in default live in `trusted-server-core`, where the
+//! `DeviceSignals` classification logic stays unit-tested.
+
+use std::sync::Arc;
+
+use fastly::Request as FastlyRequest;
+use trusted_server_core::ec::device::{DeviceModule, DeviceSignals};
+use trusted_server_core::evidence::{HostSignals, RequestInfo};
+
+/// Host-computed client signals captured from a live Fastly request.
+///
+/// Reads the TLS JA4 and HTTP/2 signals once through the Fastly SDK and
+/// owns them, so the value can be injected as a [`HostSignals`] service that
+/// outlives the borrow of the request it was captured from. Off-host the SDK
+/// accessors return `None`, so the signals are simply absent.
+#[derive(Debug, Clone, Default)]
+pub struct FastlyHostSignals {
+    ja4: Option<String>,
+    h2: Option<String>,
+}
+
+impl FastlyHostSignals {
+    /// Builds host signals from already-captured signal values.
+    ///
+    /// Use this when the adapter has read the signals once (for example
+    /// into the client metadata, or from the trusted internal headers the entry
+    /// point injects) and wants to share them without another SDK call.
+    #[must_use]
+    pub fn new(ja4: Option<String>, h2: Option<String>) -> Self {
+        Self { ja4, h2 }
+    }
+
+    /// Captures the TLS JA4 and HTTP/2 signals from a live Fastly request.
+    #[must_use]
+    pub fn from_request(req: &FastlyRequest) -> Self {
+        Self {
+            ja4: req.get_tls_ja4().map(str::to_string),
+            h2: req.get_client_h2_fingerprint().map(str::to_string),
+        }
+    }
+}
+
+impl HostSignals for FastlyHostSignals {
+    fn ja4(&self) -> Option<&str> {
+        self.ja4.as_deref()
+    }
+
+    fn h2(&self) -> Option<&str> {
+        self.h2.as_deref()
+    }
+}
+
+/// The Fastly device module, opt-in via `[device] module = "fastly"`.
+///
+/// Classifies a request with [`DeviceSignals::derive`], which strengthens the
+/// User-Agent classification with the host signals. It reads the User-Agent
+/// from its injected [`RequestInfo`] and the TLS and HTTP/2 signals from its
+/// injected [`HostSignals`], so the browser/bot gate is backed by the live
+/// request.
+pub struct FastlyDeviceModule {
+    host_signals: Arc<dyn HostSignals>,
+}
+
+impl FastlyDeviceModule {
+    /// Creates the module with its injected host signals.
+    #[must_use]
+    pub fn new(host_signals: Arc<dyn HostSignals>) -> Self {
+        Self { host_signals }
+    }
+}
+
+impl DeviceModule for FastlyDeviceModule {
+    fn id(&self) -> &'static str {
+        "fastly"
+    }
+
+    fn detect(&self, request_info: &dyn RequestInfo) -> DeviceSignals {
+        DeviceSignals::derive(
+            request_info.user_agent(),
+            self.host_signals.ja4(),
+            self.host_signals.h2(),
+        )
+    }
+}

crates/edgecookie/README.md

@@ -0,0 +1,18 @@
+# Edge Cookie modules
+
+Vendor Edge Cookie module crates live here, one per vendor, for example
+`crates/edgecookie/<vendor>`. Each implements the `EdgeCookieModule` trait
+from `trusted-server-core` and is wired in by an adapter.
+
+The built-in HMAC module (HMAC over the client IP) ships in
+`trusted-server-core` (`ec::module`), so no crate is needed for it. There is
+no default module, and a deployment selects one explicitly with
+`[ec] module`.
+
+A module's own settings live in the `[ec.<name>]` table the selector names.
+The name is the module's implementation id, the same string its
+`EdgeCookieModule::id` returns, unless the table names one with
+`implementation = "<id>"`, which lets an operator configure a module under a
+name of their own choosing. A module with no settings needs no table.
+
+This directory is a placeholder until a vendor module is added.

crates/fastly.toml

@@ -0,0 +1,13 @@
+# Minimal Viceroy config for testing crates nested one level deeper than the
+# adapters (for example `crates/device/fastly` and `crates/geo/fastly`).
+#
+# The shared wasm test runner in `.cargo/config.toml` starts Viceroy with
+# `-C ../../fastly.toml`, resolved from the crate directory. For a two-level
+# crate such as `crates/trusted-server-adapter-fastly` that reaches the
+# repository root manifest. For a three-level crate it resolves here, to
+# `crates/fastly.toml`. These crates' unit tests use no backends, KV stores,
+# or dictionaries, only a manifest Viceroy can start from.
+manifest_version = 3
+name = "trusted-server-nested-crate-tests"
+
+[local_server]

crates/geo/README.md

@@ -0,0 +1,20 @@
+# Geo modules
+
+Geo and IP-intelligence module crates live here, one per implementation, each
+implementing the `PlatformGeo` trait from `trusted-server-core`:
+
+- `crates/geo/fastly` (`trusted-server-geo-fastly`) is the host platform geo
+  module for Fastly Compute, wrapping Fastly's `geo_lookup`. The Fastly adapter
+  injects it via `build_geo_module`. It depends on the Fastly SDK, so it builds
+  only for `wasm32-wasip1`.
+- Vendor geo modules (for example `crates/geo/<vendor>`) will live alongside
+  it, one per vendor, selected by the `[geo] module` setting.
+
+Whatever the source, a module returns the same `GeoInfo` coding. The country
+is an ISO 3166-1 alpha-2 code (`US`) and the region is the ISO 3166-2 subdivision
+code with no country prefix (`CA`), so the Fastly and other modules feed the
+same downstream rules without translation.
+
+The platform-neutral `PlatformGeo` trait and the `DisabledGeo` default (no
+location) both live in `trusted-server-core`, so the default deployment resolves
+no location until a module is selected.

crates/geo/fastly/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "trusted-server-geo-fastly"
+description = "Fastly host geo module backed by the Fastly geolocation API."
+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 }
+error-stack = { workspace = true }
+fastly = { workspace = true }
+
+# The visible owner of this vendor crate, the way Prebid.js requires a named
+# maintainer of every adapter. Fastly has not yet adopted this crate, so the
+# Trusted Server maintainers own it until a vendor owner steps up.
+[package.metadata.maintainers]
+owner = "Trusted Server maintainers"
+status = "seeking vendor owner"

crates/geo/fastly/src/lib.rs

@@ -0,0 +1,47 @@
+//! The Fastly host geo module.
+//!
+//! [`FastlyPlatformGeo`] implements [`PlatformGeo`] using Fastly's `geo_lookup`,
+//! for deployments on Fastly Compute. It is the host platform's geo module,
+//! injected by the Fastly adapter via `build_geo_module`. With no selector,
+//! or `module = "platform"`, this host lookup resolves the location, and
+//! `module = "none"` disables geo instead.
+//!
+//! Like the Fastly device module, this crate calls the Fastly SDK directly,
+//! so it depends on the `fastly` crate and builds only for the `wasm32-wasip1`
+//! target. The platform-neutral `PlatformGeo` trait and the `DisabledGeo`
+//! default both live in `trusted-server-core`.
+
+use std::net::IpAddr;
+
+use error_stack::Report;
+use fastly::geo::{Geo, geo_lookup};
+use trusted_server_core::platform::{GeoInfo, PlatformError, PlatformGeo};
+
+/// Convert a Fastly [`Geo`] value into a platform-neutral [`GeoInfo`].
+fn geo_from_fastly(geo: &Geo) -> GeoInfo {
+    GeoInfo {
+        city: geo.city().to_string(),
+        country: geo.country_code().to_string(),
+        continent: format!("{:?}", geo.continent()),
+        latitude: geo.latitude(),
+        longitude: geo.longitude(),
+        metro_code: geo.metro_code(),
+        region: geo.region().map(str::to_string),
+        asn: None,
+    }
+}
+
+/// Fastly geo-lookup implementation of [`PlatformGeo`].
+///
+/// The host platform geo module for Fastly Compute. The adapter injects it via
+/// `build_geo_module`. With no selector, or `module = "platform"`, it
+/// resolves the location, and `module = "none"` disables geo instead.
+pub struct FastlyPlatformGeo;
+
+impl PlatformGeo for FastlyPlatformGeo {
+    fn lookup(&self, client_ip: Option<IpAddr>) -> Result<Option<GeoInfo>, Report<PlatformError>> {
+        Ok(client_ip
+            .and_then(geo_lookup)
+            .map(|geo| geo_from_fastly(&geo)))
+    }
+}