From cba69cc5d8b9109db305c018ca9fe12a175c56bc Mon Sep 17 00:00:00 2001 From: prk-Jr Date: Mon, 16 Nov 2026 17:25:23 +0530 Subject: [PATCH 1/3] Add shared identity conformance fixtures and Fastly coverage --- .github/workflows/test.yml | 8 + .../src/identity_conformance.rs | 268 +++++++ .../trusted-server-adapter-fastly/src/main.rs | 30 +- .../src/platform.rs | 24 +- .../trusted-server-core/src/ec/kv_backend.rs | 11 +- .../trusted-server-core/src/test_support.rs | 2 + .../src/test_support/identity_conformance.rs | 654 ++++++++++++++++++ .../README.md | 37 + .../plans/2026-11-16-identity-conformance.md | 180 +++++ .../2026-11-16-identity-conformance-design.md | 122 ++++ scripts/test-identity-conformance.mjs | 50 ++ scripts/test-identity-conformance.test.mjs | 63 ++ 12 files changed, 1440 insertions(+), 9 deletions(-) create mode 100644 crates/trusted-server-adapter-fastly/src/identity_conformance.rs create mode 100644 crates/trusted-server-core/src/test_support/identity_conformance.rs create mode 100644 docs/superpowers/plans/2026-11-16-identity-conformance.md create mode 100644 docs/superpowers/specs/2026-11-16-identity-conformance-design.md create mode 100644 scripts/test-identity-conformance.mjs create mode 100644 scripts/test-identity-conformance.test.mjs diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 1a339ac5f0..366a85f9f5 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -55,6 +55,11 @@ jobs: - name: Run tests run: cargo test-fastly + - name: Verify identity conformance selection and Fastly lifecycle + run: | + node --test scripts/test-identity-conformance.test.mjs + node scripts/test-identity-conformance.mjs fastly + - name: Run Fastly absolute deadline slow-network tests run: node crates/trusted-server-adapter-fastly/tests/deadline-origin.mjs "$(command -v viceroy)" @@ -165,6 +170,9 @@ jobs: - name: Run Axum adapter tests run: cargo test-axum + - name: Verify native identity conformance rejection controls + run: cargo test -p trusted-server-core --lib identity_conformance + - name: Verify finalization harness process cleanup run: cargo test --manifest-path crates/trusted-server-integration-tests/Cargo.toml --target x86_64-unknown-linux-gnu --features html-eof-runtime --test html_eof_runtime diff --git a/crates/trusted-server-adapter-fastly/src/identity_conformance.rs b/crates/trusted-server-adapter-fastly/src/identity_conformance.rs new file mode 100644 index 0000000000..bda4e9dd30 --- /dev/null +++ b/crates/trusted-server-adapter-fastly/src/identity_conformance.rs @@ -0,0 +1,268 @@ +//! EC conformance through the Fastly application and its production finalizer. + +use crate::sandbox::RetainedApp; +use base64::Engine as _; +use base64::engine::general_purpose::URL_SAFE_NO_PAD; +use edgezero_adapter_fastly::delivery::FastlyResponseCommitState; +use edgezero_adapter_fastly::delivery::testing::response_delivery; +use edgezero_adapter_fastly::request::FastlyService; +use edgezero_core::http::StatusCode; +use edgezero_core::response_egress_framing::ResponseEgressFramingMode; +use futures::executor::block_on; +use std::cell::RefCell; +use trusted_server_core::ec::kv::KvIdentityGraph; +use trusted_server_core::test_support::identity_conformance::{ + Adapter, Consent, Geo, Navigation, Observation, RecordingStore, Scenario, +}; +use trusted_server_core::test_support::scripted_client::{ + ScriptedHttpClient, ScriptedReply, TestClock, +}; + +use edgezero_core::outbound::HttpClient; +use std::time::{SystemTime, UNIX_EPOCH}; + +use super::{FinalizeInputs, assemble_app, handle_delivery, with_finalization}; +use crate::platform::RequestGeo; +use crate::sandbox::SandboxCounters; +use fastly::Request as FastlyRequest; +use trusted_server_core::ec::device::DeviceSignals; +use trusted_server_core::geo::GeoInfo; +use trusted_server_core::platform::ClientInfo; +use trusted_server_core::settings::Settings; + +const DOCUMENT: &str = "Example article"; +const ORIGIN: &str = "https://origin.example.com/article"; +const USER_AGENT: &str = + "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/146.0.0.0 Safari/537.36"; + +thread_local! { + static GRAPH: RefCell> = const { RefCell::new(None) }; +} + +pub(crate) fn fixture_graph(settings: &Settings) -> Option { + if settings.ec.ec_store.as_deref() == Some("identity-conformance") { + GRAPH.with_borrow(Clone::clone) + } else { + None + } +} + +struct GraphGuard(Option); + +impl GraphGuard { + fn install(store: &RecordingStore) -> Self { + Self(GRAPH.replace(Some(KvIdentityGraph::new(store.clone())))) + } +} + +impl Drop for GraphGuard { + fn drop(&mut self) { + GRAPH.replace(self.0.take()); + } +} + +fn settings() -> Settings { + Settings::from_toml( + r#" + [[handlers]] + path = "^/_ts/admin" + username = "example-admin" + password = "example-password" + [publisher] + domain = "publisher.example.com" + cookie_domain = ".publisher.example.com" + origin_url = "https://origin.example.com" + proxy_secret = "example-proxy-secret" + [ec] + passphrase = "example-secret-at-least-32-bytes-long" + ec_store = "identity-conformance" + [request_signing] + enabled = false + config_store_id = "example-config" + secret_store_id = "example-secrets" + "#, + ) + .expect("should parse conformance settings") +} + +fn consent_cookie(granted: bool) -> String { + let mut core = [0_u8; 32]; + // TCF v2, followed by current Created and LastUpdated decisecond fields. + core[0] = 2 << 2; + let now = SystemTime::now() + .duration_since(UNIX_EPOCH) + .expect("should read fixture time") + .as_secs() + * 10; + for offset in [6, 42] { + for bit in 0..36 { + if now & (1 << (35 - bit)) != 0 { + core[(offset + bit) / 8] |= 1 << (7 - (offset + bit) % 8); + } + } + } + // Purpose 1 is the first purpose-consent bit, at offset 152. + core[19] = if granted { 0x80 } else { 0 }; + format!("euconsent-v2={}", URL_SAFE_NO_PAD.encode(core)) +} + +struct FastlyAdapter { + settings: Settings, + retained: RetainedApp, + origin: ScriptedHttpClient, + store: RecordingStore, +} + +impl FastlyAdapter { + fn new(store: RecordingStore) -> Self { + let settings = settings(); + let clock = TestClock::new(); + let origin = ScriptedHttpClient::new(&clock); + let mut retained = assemble_app(Ok(settings.clone()), &"") + .expect("should assemble the conformance application"); + retained.app.set_monotonic_clock(clock.monotonic_clock()); + Self { + settings, + retained, + origin, + store, + } + } +} + +impl Adapter for FastlyAdapter { + fn navigate(&mut self, navigation: &Navigation) -> Observation { + let _guard = GraphGuard::install(&self.store); + self.origin.respond_to( + edgezero_core::http::Method::GET, + ORIGIN, + ScriptedReply::status(StatusCode::OK) + .header("content-type", "text/html") + .body(DOCUMENT), + ); + let geo = (navigation.geo == Geo::Gdpr).then(|| GeoInfo { + country: "DE".to_owned(), + city: String::new(), + continent: "EU".to_owned(), + latitude: 0.0, + longitude: 0.0, + metro_code: 0, + region: None, + asn: None, + }); + let counters = SandboxCounters { + ordinal: 1, + builds: 1, + request_id: "example-conformance-request".to_owned(), + }; + let inputs = FinalizeInputs { + settings: &self.settings, + geo: geo.as_ref(), + counters: &counters, + }; + let mut cookies = Vec::new(); + match navigation.consent { + Consent::Granted => cookies.push(consent_cookie(true)), + Consent::Denied => cookies.push(consent_cookie(false)), + Consent::Missing => {} + } + if let Some(identity) = &navigation.ec_cookie { + cookies.push(format!("ts-ec={identity}")); + } + let request = FastlyRequest::get("https://publisher.example.com/article") + .with_header("sec-fetch-dest", navigation.destination) + .with_header( + "accept", + if navigation.destination == "document" { + "text/html" + } else { + "*/*" + }, + ) + .with_header("user-agent", USER_AGENT) + .with_header("cookie", cookies.join("; ")); + let mut observation = None; + let origin = self.origin.clone(); + let delivery = with_finalization(&inputs, |finalize| { + FastlyService::new(&self.retained.app).run_request_with_hooks_for_test( + request, + |_request, extensions| { + extensions.insert(HttpClient::with_client(origin)); + let ip = Some("192.0.2.7".parse().expect("should parse fixture IP")); + extensions.insert(ClientInfo { + client_ip: ip, + ..ClientInfo::default() + }); + extensions.insert(if navigation.geo == Geo::Failed { + RequestGeo::failing(ip) + } else { + RequestGeo::new(ip, geo.clone()) + }); + if navigation.browser { + extensions.insert(DeviceSignals::derive( + USER_AGENT, + Some("t13d1516h2_example_example"), + None, + )); + } + }, + finalize, + |envelope| { + let (prepared, _policy, mut attempt, clock) = envelope + .begin(ResponseEgressFramingMode::HostAutomatic) + .unwrap_or_else(|_| panic!("should prepare the document response")); + let response = prepared.into_response(); + self.store.response_released(); + let status = response.status(); + let cookies = response + .headers() + .get_all("set-cookie") + .iter() + .map(|value| { + value + .to_str() + .expect("should decode response cookie") + .to_owned() + }) + .collect(); + assert!( + attempt.begin_writing(), + "should start releasing the response" + ); + let body = block_on(response.into_body().into_bytes_bounded(1024 * 1024)) + .expect("should consume the complete document"); + assert!( + attempt.account_bytes(body.len() as u64, clock.now()), + "should account body bytes" + ); + assert!( + attempt.complete(clock.now()), + "should complete the document response" + ); + observation = Some(Observation { + status, + cookies, + body: body.to_vec(), + }); + response_delivery( + FastlyResponseCommitState::Committed, + attempt.into_terminal_report(), + Ok(()), + ) + }, + ) + }); + handle_delivery(delivery, &counters, |_| {}); + observation.expect("should deliver a finalized response") + } +} + +#[test] +fn identity_conformance_fastly() { + for scenario in Scenario::FASTLY_BASELINE { + let store = RecordingStore::new(scenario == Scenario::WriteFailure); + let mut adapter = FastlyAdapter::new(store.clone()); + log::info!("Running Fastly identity scenario {scenario:?}"); + scenario.verify(&mut adapter, &store); + } +} diff --git a/crates/trusted-server-adapter-fastly/src/main.rs b/crates/trusted-server-adapter-fastly/src/main.rs index 6984c7abc4..3718ea8dba 100644 --- a/crates/trusted-server-adapter-fastly/src/main.rs +++ b/crates/trusted-server-adapter-fastly/src/main.rs @@ -38,6 +38,8 @@ mod deadline_network; mod delivery; mod ec_kv; mod esi_assembly; +#[cfg(test)] +mod identity_conformance; mod management_api; mod middleware; mod platform; @@ -352,18 +354,28 @@ fn serve( geo: request_geo.geo(), counters, }; - let delivery = send_request_with_registries_and_hooks( - &retained.app, - TrustedServerApp::stores(), - req, - prepare, - |response: &mut HttpResponse| finalize_response(response, &inputs), - ); + let delivery = with_finalization(&inputs, |finalize| { + send_request_with_registries_and_hooks( + &retained.app, + TrustedServerApp::stores(), + req, + prepare, + finalize, + ) + }); handle_delivery(delivery, counters, |state| { run_post_delivery(state, &queue, settings, &counters.log_context()); }); } +/// Supplies the production finalization callback to a request lifecycle. +fn with_finalization( + inputs: &FinalizeInputs<'_>, + send: impl FnOnce(&mut dyn FnMut(&mut HttpResponse) -> Option) -> T, +) -> T { + send(&mut |response| finalize_response(response, inputs)) +} + /// What the native work reads from the SDK client request before `EdgeZero` converts it. /// /// Only the client request exposes the trusted forwarder, the resolved client @@ -730,6 +742,10 @@ fn build_ja4_debug_response(req: &FastlyRequest) -> FastlyResponse { } pub(crate) fn maybe_identity_graph(settings: &Settings) -> Option { + #[cfg(test)] + if let Some(graph) = identity_conformance::fixture_graph(settings) { + return Some(graph); + } settings .ec .ec_store diff --git a/crates/trusted-server-adapter-fastly/src/platform.rs b/crates/trusted-server-adapter-fastly/src/platform.rs index 0fdfe23c6a..bc7b0fbd4f 100644 --- a/crates/trusted-server-adapter-fastly/src/platform.rs +++ b/crates/trusted-server-adapter-fastly/src/platform.rs @@ -225,6 +225,8 @@ fn geo_from_fastly(geo: &Geo) -> GeoInfo { /// one host geo lookup however many steps use geo. #[derive(Debug, Clone, Default)] pub(crate) struct RequestGeo { + #[cfg(test)] + fail_lookup: bool, client_ip: Option, geo: Option, } @@ -233,12 +235,28 @@ impl RequestGeo { /// Holds `geo` as the lookup result for `client_ip`. #[cfg(test)] pub(crate) fn new(client_ip: Option, geo: Option) -> Self { - Self { client_ip, geo } + Self { + client_ip, + geo, + fail_lookup: false, + } + } + + /// Simulates a failed platform lookup without changing production geo handling. + #[cfg(test)] + pub(crate) fn failing(client_ip: Option) -> Self { + Self { + client_ip, + geo: None, + fail_lookup: true, + } } /// Looks up `client_ip` once with Fastly's geo database. pub(crate) fn lookup_once(client_ip: Option) -> Self { Self { + #[cfg(test)] + fail_lookup: false, client_ip, geo: client_ip .and_then(geo_lookup) @@ -264,6 +282,10 @@ impl PlatformGeo for RequestGeo { /// Any other IP gets `Ok(None)`: there is no data for an IP this request /// did not resolve. fn lookup(&self, client_ip: Option) -> Result, Report> { + #[cfg(test)] + if self.fail_lookup { + return Err(Report::new(PlatformError::Geo)); + } if client_ip == self.client_ip { Ok(self.geo.clone()) } else { diff --git a/crates/trusted-server-core/src/ec/kv_backend.rs b/crates/trusted-server-core/src/ec/kv_backend.rs index bfe74ca6f3..36b587f822 100644 --- a/crates/trusted-server-core/src/ec/kv_backend.rs +++ b/crates/trusted-server-core/src/ec/kv_backend.rs @@ -171,7 +171,7 @@ pub trait EcKvStore { fn delete(&self, key: &str) -> Result<(), Report>; } -#[cfg(test)] +#[cfg(any(test, feature = "test-utils"))] pub(crate) mod test_support { use std::collections::BTreeMap; use std::sync::Mutex; @@ -180,11 +180,13 @@ pub(crate) mod test_support { /// [`EcKvStore`] wrapper that counts `lookup` calls through a shared counter /// so tests can prove exactly how many reads a flow performs. + #[cfg(test)] pub(crate) struct CountingEcKv { inner: InMemoryEcKv, lookups: std::sync::Arc, } + #[cfg(test)] impl CountingEcKv { pub(crate) fn new( name: impl Into, @@ -197,6 +199,7 @@ pub(crate) mod test_support { } } + #[cfg(test)] impl EcKvStore for CountingEcKv { fn store_name(&self) -> &str { self.inner.store_name() @@ -242,12 +245,14 @@ pub(crate) mod test_support { /// /// With `list_fails` set, the list API errors instead, modelling a store /// that can neither find the key nor prove it absent. + #[cfg(test)] pub(crate) struct StaleLookupEcKv { inner: InMemoryEcKv, stale_lookups_remaining: Mutex, list_fails: bool, } + #[cfg(test)] impl StaleLookupEcKv { pub(crate) fn new(name: impl Into, stale_lookups: u32, list_fails: bool) -> Self { Self { @@ -258,6 +263,7 @@ pub(crate) mod test_support { } } + #[cfg(test)] impl EcKvStore for StaleLookupEcKv { fn store_name(&self) -> &str { self.inner.store_name() @@ -408,10 +414,12 @@ pub(crate) mod test_support { /// [`EcKvStore`] that fails every operation, mimicking a missing or /// unreachable platform store. + #[cfg(test)] pub(crate) struct FailingEcKv { name: String, } + #[cfg(test)] impl FailingEcKv { pub(crate) fn new(name: impl Into) -> Self { Self { name: name.into() } @@ -425,6 +433,7 @@ pub(crate) mod test_support { } } + #[cfg(test)] impl EcKvStore for FailingEcKv { fn store_name(&self) -> &str { &self.name diff --git a/crates/trusted-server-core/src/test_support.rs b/crates/trusted-server-core/src/test_support.rs index 5bc2786a79..8c5a6ae801 100644 --- a/crates/trusted-server-core/src/test_support.rs +++ b/crates/trusted-server-core/src/test_support.rs @@ -1,6 +1,8 @@ #[cfg(test)] pub(crate) mod body_read; #[cfg(any(test, feature = "test-utils"))] +pub mod identity_conformance; +#[cfg(any(test, feature = "test-utils"))] pub mod logging; #[cfg(any(test, feature = "test-utils"))] pub mod publisher_input_cap; diff --git a/crates/trusted-server-core/src/test_support/identity_conformance.rs b/crates/trusted-server-core/src/test_support/identity_conformance.rs new file mode 100644 index 0000000000..0af23a7072 --- /dev/null +++ b/crates/trusted-server-core/src/test_support/identity_conformance.rs @@ -0,0 +1,654 @@ +//! Portable record-store fixtures for adapter identity conformance. + +use std::sync::{Arc, Mutex}; + +use cookie::Cookie; +use error_stack::Report; + +use crate::consent::now_deciseconds; +use crate::ec::normalize_ec_id_for_kv; +use http::StatusCode; + +use crate::ec::generation::is_valid_ec_id; +use crate::ec::kv::KvIdentityGraph; +use crate::ec::kv_backend::test_support::InMemoryEcKv; +use crate::ec::kv_backend::{EcKvLookup, EcKvStore, EcKvWrite, EcKvWriteOutcome}; +use crate::error::TrustedServerError; + +/// An observed persistence or response-release boundary in a conformance run. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Event { + /// A write successfully persisted the named key. + Persisted(String), + /// The fixture refused a write to the named key. + Rejected(String), + /// The runner began releasing a finalized response. + ResponseReleased, +} + +struct StoreState { + inner: InMemoryEcKv, + events: Mutex>, + fail_writes: bool, +} + +/// An inspectable store sharing authoritative state across request-local graphs. +/// +/// Reads and conditional writes reuse the EC tests' generation-aware store. +/// Only available in test builds or with the `test-utils` feature. +#[derive(Clone)] +pub struct RecordingStore(Arc); + +impl RecordingStore { + /// Creates an empty store, optionally rejecting writes while preserving reads. + /// + /// # Examples + /// + /// ``` + /// use trusted_server_core::test_support::identity_conformance::RecordingStore; + /// let store = RecordingStore::new(false); + /// assert!(store.events().is_empty()); + /// ``` + #[must_use] + pub fn new(fail_writes: bool) -> Self { + Self(Arc::new(StoreState { + inner: InMemoryEcKv::new("identity-conformance"), + events: Mutex::new(Vec::new()), + fail_writes, + })) + } + + /// Returns the ordered observations recorded so far. + /// + /// # Panics + /// + /// Panics if a previous fixture operation poisoned the event lock. + #[must_use] + pub fn events(&self) -> Vec { + self.0 + .events + .lock() + .expect("should lock fixture events") + .clone() + } + + /// Records the boundary at which the finalized response is released. + /// + /// # Panics + /// + /// Panics if a previous fixture operation poisoned the event lock. + pub fn response_released(&self) { + self.0 + .events + .lock() + .expect("should lock fixture events") + .push(Event::ResponseReleased); + } +} + +impl EcKvStore for RecordingStore { + fn store_name(&self) -> &str { + self.0.inner.store_name() + } + + fn lookup(&self, key: &str) -> Result, Report> { + self.0.inner.lookup(key) + } + + fn key_exists(&self, key: &str) -> Result> { + self.0.inner.key_exists(key) + } + + fn insert( + &self, + key: &str, + write: EcKvWrite<'_>, + ) -> Result> { + if self.0.fail_writes { + self.0 + .events + .lock() + .expect("should lock fixture events") + .push(Event::Rejected(key.to_owned())); + return Err(Report::new(TrustedServerError::KvStore { + store_name: self.store_name().to_owned(), + message: "fixture rejects record creation".to_owned(), + })); + } + let outcome = self.0.inner.insert(key, write)?; + if outcome == EcKvWriteOutcome::Written { + self.0 + .events + .lock() + .expect("should lock fixture events") + .push(Event::Persisted(key.to_owned())); + } + Ok(outcome) + } + + fn list_keys_with_prefix( + &self, + prefix: &str, + limit: u32, + ) -> Result, Report> { + self.0.inner.list_keys_with_prefix(prefix, limit) + } + + fn delete(&self, key: &str) -> Result<(), Report> { + self.0.inner.delete(key) + } +} + +/// Consent sent through the adapter's real request parser in GDPR geo. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Consent { + /// Serialized TCF Purpose 1 consent is granted. + Granted, + /// Serialized TCF Purpose 1 consent is denied. + Denied, + /// No consent cookie is sent. + Missing, +} + +/// Location available at the platform-service boundary. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Geo { + /// A GDPR location. + Gdpr, + /// No location was found. + Missing, + /// The location service failed. + Failed, +} + +/// A request to execute through an adapter's complete application lifecycle. +pub struct Navigation { + /// Consent cookie representation to encode. + pub consent: Consent, + /// Previously issued EC cookie, if any. + pub ec_cookie: Option, + /// The platform's location result. + pub geo: Geo, + /// Whether to supply the current browser policy's positive metadata. + pub browser: bool, + /// Fetch destination; a script is deliberately ineligible for creation. + pub destination: &'static str, +} + +impl Default for Navigation { + fn default() -> Self { + Self { + consent: Consent::Granted, + ec_cookie: None, + geo: Geo::Gdpr, + browser: true, + destination: "document", + } + } +} + +/// Finalized response observed at delivery, after consuming the actual body. +pub struct Observation { + /// Final HTTP status. + pub status: StatusCode, + /// Each raw Set-Cookie header, kept separately. + pub cookies: Vec, + /// The completely consumed document body. + pub body: Vec, +} + +/// An adapter runner supplies platform fixtures, never EC business logic. +pub trait Adapter { + /// Executes the request through routing, finalization and body delivery. + fn navigate(&mut self, navigation: &Navigation) -> Observation; +} + +/// One reusable application conformance scenario. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Scenario { + /// A new cookie matches a new persisted row. + Fresh, + /// Rejected record creation emits no cookie. + WriteFailure, + /// A returning identity survives a missing location. + UnknownGeo, + /// A returning identity survives a failed location service. + GeoFailure, + /// Denied GDPR storage consent prevents creation. + DeniedConsent, + /// Missing GDPR storage consent prevents creation. + MissingConsent, + /// Subresource responses cannot create identity. + Subresource, + /// Returning navigation preserves identity. + Returning, + /// Missing browser metadata is refused on the inspected pre-T12 baseline. + MissingBrowserMetadata, +} + +impl Scenario { + /// The complete current Fastly scenario set, with no runtime-only cases. + pub const FASTLY_BASELINE: [Self; 9] = [ + Self::Fresh, + Self::WriteFailure, + Self::UnknownGeo, + Self::GeoFailure, + Self::DeniedConsent, + Self::MissingConsent, + Self::Subresource, + Self::Returning, + Self::MissingBrowserMetadata, + ]; + + /// Executes the scenario and checks the response against authoritative storage. + /// + /// # Panics + /// + /// Panics on any missing document, cookie/record mismatch, failed fixture gate, + /// identity rotation or persistence occurring after response release. + /// + /// # Examples + /// + /// ```ignore + /// Scenario::Fresh.verify(&mut adapter, &store); + /// ``` + pub fn verify(self, adapter: &mut impl Adapter, store: &RecordingStore) { + let graph = KvIdentityGraph::new(store.clone()); + assert!( + store + .list_keys_with_prefix("", 100) + .expect("should inspect empty store") + .is_empty(), + "should start every scenario without seeded identities" + ); + let mut request = Navigation::default(); + match self { + Self::DeniedConsent => request.consent = Consent::Denied, + Self::MissingConsent => request.consent = Consent::Missing, + Self::Subresource => request.destination = "script", + Self::MissingBrowserMetadata => request.browser = false, + _ => {} + } + let response = adapter.navigate(&request); + assert_document(&response); + match self { + Self::WriteFailure + | Self::DeniedConsent + | Self::MissingConsent + | Self::Subresource + | Self::MissingBrowserMetadata => { + assert!( + ec_cookies(&response).is_empty(), + "should not issue or delete an EC for a fresh denied request" + ); + assert!( + store + .list_keys_with_prefix("", 100) + .expect("should inspect fixture rows") + .is_empty(), + "should not persist an identity" + ); + if self == Self::WriteFailure { + let events = store.events(); + let rejected = events + .iter() + .position( + |event| matches!(event, Event::Rejected(key) if is_valid_ec_id(key)), + ) + .expect("should reach the rejected creation write"); + let released = events + .iter() + .position(|event| *event == Event::ResponseReleased) + .expect("should release the document response"); + assert!( + rejected < released, + "should reject creation before releasing the response" + ); + } + } + _ => { + let identity = assert_created(&response, store); + if matches!(self, Self::UnknownGeo | Self::GeoFailure | Self::Returning) { + let keys = store + .list_keys_with_prefix("", 100) + .expect("should inspect issued rows"); + request.ec_cookie = Some(identity.clone()); + request.geo = match self { + Self::UnknownGeo => Geo::Missing, + Self::GeoFailure => Geo::Failed, + _ => Geo::Gdpr, + }; + let returning = adapter.navigate(&request); + assert_document(&returning); + let mut jar = IdentityJar(Some(identity.clone())); + jar.apply(&returning); + assert_eq!( + jar.0.as_deref(), + Some(identity.as_str()), + "should retain the reader's cookie" + ); + let (record, _) = graph + .get(&identity) + .expect("should read returning record") + .expect("should retain the returning record"); + assert!( + record.consent.ok, + "should retain a live record on returning navigation" + ); + request.ec_cookie = jar.0; + let replay = adapter.navigate(&request); + assert_document(&replay); + let mut replay_jar = IdentityJar(request.ec_cookie.clone()); + replay_jar.apply(&replay); + assert_eq!( + replay_jar.0.as_deref(), + Some(identity.as_str()), + "should preserve identity on replay" + ); + let (record, _) = graph + .get(&identity) + .expect("should inspect replayed identity") + .expect("should retain the existing record"); + assert!( + record.consent.ok, + "should retain a live record after replay" + ); + assert_eq!( + store + .list_keys_with_prefix("", 100) + .expect("should inspect returning rows"), + keys, + "should not create a second identity" + ); + } + } + } + } +} + +fn assert_document(response: &Observation) { + assert_eq!( + response.status, + StatusCode::OK, + "should serve the publisher document" + ); + assert!( + String::from_utf8_lossy(&response.body).contains("Example article"), + "should consume the real publisher body" + ); +} + +fn ec_cookies(response: &Observation) -> Vec<&str> { + response + .cookies + .iter() + .filter(|cookie| cookie.starts_with("ts-ec=")) + .map(String::as_str) + .collect() +} + +fn assert_created(response: &Observation, store: &RecordingStore) -> String { + let cookies = ec_cookies(response); + assert_eq!(cookies.len(), 1, "should issue exactly one EC cookie"); + let mut jar = IdentityJar(None); + jar.apply(response); + assert!(jar.0.is_some(), "should issue a live identity cookie"); + let identity = cookies[0] + .strip_prefix("ts-ec=") + .expect("should have EC prefix") + .split(';') + .next() + .expect("should have cookie value"); + assert!( + is_valid_ec_id(identity), + "should issue a valid EC identifier" + ); + let graph = KvIdentityGraph::new(store.clone()); + let key = normalize_ec_id_for_kv(identity); + let (record, _) = graph + .get(&key) + .expect("should inspect issued identity") + .expect("should persist the record matching the issued cookie"); + assert!(record.created > 0, "should persist creation metadata"); + assert!(record.consent.ok, "should hold a live authoritative record"); + let events = store.events(); + let persisted = events + .iter() + .position(|event| matches!(event, Event::Persisted(written) if written == &key)) + .expect("should observe the issued identity write"); + let released = events + .iter() + .position(|event| *event == Event::ResponseReleased) + .expect("should observe response release"); + assert!( + persisted < released, + "should persist before releasing the cookie" + ); + assert_eq!( + store + .list_keys_with_prefix("", 100) + .expect("should inspect created records") + .len(), + 1, + "should create exactly one identity record" + ); + identity.to_owned() +} + +/// The reader's EC cookie state after applying each response's expiry directives. +struct IdentityJar(Option); + +impl IdentityJar { + fn apply(&mut self, response: &Observation) { + for raw in ec_cookies(response) { + let cookie = Cookie::parse(raw).expect("should parse the response EC cookie"); + // Max-Age takes precedence over Expires, as in a browser cookie jar. + let expired = cookie.max_age().map_or_else( + || { + cookie.expires_datetime().is_some_and(|expiry| { + expiry.unix_timestamp() <= (now_deciseconds() / 10) as i64 + }) + }, + |age| age.whole_seconds() <= 0, + ); + self.0 = if expired { + None + } else { + Some(cookie.value().to_owned()) + }; + } + } +} + +#[cfg(all(test, not(target_arch = "wasm32")))] +mod tests { + use super::*; + use crate::consent::types::ConsentContext; + use crate::ec::kv_types::KvEntry; + + const IDENTITY: &str = + "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.Ab1234"; + + fn response(cookie: &str) -> Observation { + Observation { + status: StatusCode::OK, + cookies: vec![cookie.to_owned()], + body: b"Example article".to_vec(), + } + } + + fn create(store: &RecordingStore, identity: &str) { + let mut record = KvEntry::new(&ConsentContext::default(), None, 100, "example.com"); + record.consent.ok = true; + KvIdentityGraph::new(store.clone()) + .create(identity, &record) + .expect("should create the control record"); + } + + #[test] + #[should_panic(expected = "should hold a live authoritative record")] + fn identity_conformance_rejects_cookie_for_tombstone() { + let store = RecordingStore::new(false); + KvIdentityGraph::new(store.clone()) + .create(IDENTITY, &KvEntry::tombstone(100)) + .expect("should persist a withdrawal control"); + store.response_released(); + assert_created(&response(&format!("ts-ec={IDENTITY}")), &store); + } + + #[test] + #[should_panic(expected = "should persist the record matching the issued cookie")] + fn identity_conformance_rejects_cookie_without_record() { + let store = RecordingStore::new(false); + store.response_released(); + assert_created(&response(&format!("ts-ec={IDENTITY}")), &store); + } + + #[test] + #[should_panic(expected = "should persist before releasing the cookie")] + fn identity_conformance_rejects_unrelated_early_write() { + let store = RecordingStore::new(false); + create(&store, &IDENTITY.replace("Ab1234", "Cd5678")); + store.response_released(); + create(&store, IDENTITY); + assert_created(&response(&format!("ts-ec={IDENTITY}")), &store); + } + + struct DeletingAdapter { + store: RecordingStore, + expiry: &'static str, + } + + impl Adapter for DeletingAdapter { + fn navigate(&mut self, navigation: &Navigation) -> Observation { + let cookie = if navigation.ec_cookie.is_none() { + create(&self.store, IDENTITY); + format!("ts-ec={IDENTITY}") + } else { + assert_eq!( + navigation.ec_cookie.as_deref(), + Some(IDENTITY), + "should replay the issued cookie" + ); + format!("ts-ec={IDENTITY}; {}", self.expiry) + }; + self.store.response_released(); + response(&cookie) + } + } + + struct TombstoningAdapter(DeletingAdapter); + + impl Adapter for TombstoningAdapter { + fn navigate(&mut self, navigation: &Navigation) -> Observation { + let response = self.0.navigate(navigation); + if navigation.ec_cookie.is_some() { + self.0 + .store + .delete(IDENTITY) + .expect("should replace the fixture record"); + KvIdentityGraph::new(self.0.store.clone()) + .create(IDENTITY, &KvEntry::tombstone(100)) + .expect("should model a returning identity becoming unusable"); + } + response + } + } + + #[test] + #[should_panic(expected = "should retain a live record on returning navigation")] + fn identity_conformance_rejects_tombstoned_returning_identity() { + let store = RecordingStore::new(false); + Scenario::Returning.verify( + &mut TombstoningAdapter(DeletingAdapter { + store: store.clone(), + expiry: "Path=/", + }), + &store, + ); + } + + #[test] + #[should_panic(expected = "should retain the reader's cookie")] + fn identity_conformance_rejects_negative_max_age() { + let store = RecordingStore::new(false); + Scenario::UnknownGeo.verify( + &mut DeletingAdapter { + store: store.clone(), + expiry: "Max-Age=-1", + }, + &store, + ); + } + + #[test] + #[should_panic(expected = "should retain the reader's cookie")] + fn identity_conformance_rejects_past_expiry() { + let store = RecordingStore::new(false); + Scenario::UnknownGeo.verify( + &mut DeletingAdapter { + store: store.clone(), + expiry: "Expires=Thu, 01 Jan 1970 00:00:00 GMT", + }, + &store, + ); + } + + struct LateRejectionAdapter(RecordingStore); + + impl Adapter for LateRejectionAdapter { + fn navigate(&mut self, _navigation: &Navigation) -> Observation { + self.0.response_released(); + let _error = KvIdentityGraph::new(self.0.clone()) + .create( + IDENTITY, + &KvEntry::new(&ConsentContext::default(), None, 100, "example.com"), + ) + .expect_err("should trigger the rejected write after release"); + Observation { + status: StatusCode::OK, + cookies: Vec::new(), + body: b"Example article".to_vec(), + } + } + } + + #[test] + #[should_panic(expected = "should reject creation before releasing the response")] + fn identity_conformance_rejects_late_failure() { + let store = RecordingStore::new(true); + Scenario::WriteFailure.verify(&mut LateRejectionAdapter(store.clone()), &store); + } +} + +#[cfg(test)] +mod portable_tests { + use super::*; + use crate::consent::types::ConsentContext; + use crate::ec::kv::CreateIfAbsentOutcome; + use crate::ec::kv_types::KvEntry; + + const IDENTITY: &str = + "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.Ab1234"; + + #[test] + fn identity_conformance_preserves_conditional_write_preconditions() { + let store = RecordingStore::new(false); + let graph = KvIdentityGraph::new(store.clone()); + let record = KvEntry::new(&ConsentContext::default(), None, 100, "example.com"); + assert_eq!( + graph + .create_if_absent(IDENTITY, &record) + .expect("should create absent identity"), + CreateIfAbsentOutcome::Written, + "should persist an absent key" + ); + assert_eq!( + graph + .create_if_absent(IDENTITY, &record) + .expect("should inspect existing identity"), + CreateIfAbsentOutcome::AlreadyExists, + "should refuse a duplicate create" + ); + } +} diff --git a/crates/trusted-server-integration-tests/README.md b/crates/trusted-server-integration-tests/README.md index 0a5ba222e3..1d78c43480 100644 --- a/crates/trusted-server-integration-tests/README.md +++ b/crates/trusted-server-integration-tests/README.md @@ -41,3 +41,40 @@ gitignored `trusted-server.toml`. See [Testing](../../TESTING.md) for the complete gate matrix and [`scripts/README.md`](../../scripts/README.md) for inputs and cleanup behavior. + +## Identity conformance + +The reusable EC contract lives in core test support, with the current Fastly +runner in `trusted-server-adapter-fastly/src/identity_conformance.rs`. Run from +the repository root with the repository-pinned Rust, Node and Viceroy: + +```bash +node --test scripts/test-identity-conformance.test.mjs +node scripts/test-identity-conformance.mjs fastly +cargo test -p trusted-server-core --lib identity_conformance +``` + +The launcher lists the required Fastly test before executing it and rejects +zero-test success. Selecting `axum`, `cloudflare` or `spin` fails explicitly +until its runner is available. Native core tests check the assertion contract; +they do not claim Axum identity support. + +The Fastly application test executes nine isolated scenarios: fresh creation, +rejected writes, missing and failed geo, denied and absent GDPR consent, +subresources, returning readers, and the current missing-browser-metadata gate. +It uses the real request conversion, router, shared production finalization +callback composition and consumed HTML response. Platform metadata, record +storage and the publisher origin are controlled test fixtures. Successful +issuance requires the matching record before response release; failed writes +must be observed before release. Returning scenarios apply cookie expiry rules +and replay the resulting identity. The missing-metadata expectation describes +the current pre-T12 policy and must change when #1592 permits absent JA4. + +This is application conformance, not fresh-browser qualification through an +unmodified deployed artifact. Viceroy 0.21 does not expose JA4, so the current +production browser gate prevents fresh issuance over ordinary local HTTP. +The existing seeded Fastly runtime tests remain useful for their separate +boundary. Startup capability rejection, removal of adapter-owned identity +calls (#1600), Axum activation (#1574), later adapter integrations and deployed +browser/provider qualification remain outstanding under #1586. Infrastructure +delivery alone must not close that issue. diff --git a/docs/superpowers/plans/2026-11-16-identity-conformance.md b/docs/superpowers/plans/2026-11-16-identity-conformance.md new file mode 100644 index 0000000000..8d3d9dcc3a --- /dev/null +++ b/docs/superpowers/plans/2026-11-16-identity-conformance.md @@ -0,0 +1,180 @@ +# Identity conformance implementation plan + +**Goal:** Deliver T5's reusable EC lifecycle contract and document the integrations needed for complete #1586 acceptance. + +**Architecture:** Shared test scenarios run through thin native and WASM application runners. Deterministic platform fixtures prove storage/cookie behavior; separate runtime tests prove executable wiring and identify any remaining ingress qualification gap. + +**Tech stack:** Rust test targets, existing EdgeZero application lifecycle, Viceroy, the native Axum server, existing integration-test helpers and GitHub Actions. + +**Execution status:** Suite implementation authorized on 2026-11-16, on `feat/1586-identity-conformance` based at `cc811fc7aa0d234e447a868af5b8ab4ea359326a`. Read the [specification](../specs/2026-11-16-identity-conformance-design.md) first. Tasks 1–4 cover this delivery; dependency-bound Tasks 5–6 remain outstanding. Implementation workers must follow the repository's incremental development and verification workflow. + +## Base and execution gates + +- T5 is blocked by #1507. If PR #1506 is still open, stack code on its approved `spec/edgezero-pr275-migration` head; otherwise branch from main containing the cutover. Record the exact SHA and inspect its instructions and CI before starting. +- The inspected source baseline is main `1810c763a`, with a read-only check of #1506 at `cc811fc7aa0d234e447a868af5b8ab4ea359326a`. API names below are design responsibilities, not claims that future shared-app constructors already exist. +- #1600 owns shared identity application extraction and removal of direct adapter identity calls. #1574 owns Axum activation. Do not implement either to make T5 green. +- Plan Tasks 1–4 establish suite delivery. Tasks 5–6 establish later integration/qualification; leave their results outstanding until their prerequisites exist. No infrastructure-only PR should auto-close #1586. +- A missing fixture path or unsupported runtime is a qualification gap, not permission to bypass production gates or count a skipped scenario as passed. + +## File map + +Paths marked proposed are created only during authorized implementation. Reconfirm their placement after choosing the cutover base. + +| Path | Responsibility | +| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| `crates/trusted-server-core/src/test_support/identity_conformance.rs` (proposed) | Portable scenario inputs, observations and assertions, behind existing test support configuration | +| `crates/trusted-server-core/src/test_support.rs` | Export test support only where its existing feature contract allows | +| `crates/trusted-server-core/src/ec/kv_backend.rs` test support and existing `kv.rs` test wrappers | Reuse record-store semantics; extend fixture recording/fault injection only if necessary | +| `crates/trusted-server-adapter-fastly/src/main.rs` | Exact production lifecycle helper and minimal test-only store injection if Task 1 requires it | +| `crates/trusted-server-adapter-fastly/src/app.rs` test module | WASM adapter application runner, with complete lifecycle rather than router-only assertions | +| `crates/trusted-server-adapter-axum/src/app.rs` test module | Native application runner when #1574 supplies identity | +| `crates/trusted-server-integration-tests/tests/identity_conformance.rs` (proposed) | Host orchestration and adapter result reporting | +| `crates/trusted-server-integration-tests/tests/common/identity_conformance.rs` (proposed) | Runtime lifecycle scenarios using existing clients and process helpers | +| `crates/trusted-server-integration-tests/Cargo.toml` | Runtime test target registration only if required | +| `.github/workflows/test.yml`, `.github/workflows/integration-tests.yml` | Explicit PR execution and runtime artifact prerequisites | +| `scripts/lint-identity-boundaries.mjs` (proposed) and adjacent `.test.mjs` | SH-5 production-call check and positive/negative fixtures | +| `crates/trusted-server-integration-tests/README.md` | Commands, evidence levels, prerequisite and outstanding integration documentation | + +Reuse existing helpers before adding these files. The architecture check and runtime layers can increase the initial 6–12-file estimate; record the final inventory rather than treating the estimate as a constraint. + +## Task 1: Establish the actual fixture and lifecycle contract + +**Inspect:** Fastly `src/app.rs`, `src/main.rs`, core `src/ec/{mod,finalize,kv_backend}.rs`, selected-base application constructors, integration `tests/common/ec.rs`, `tests/environments/fastly.rs`, `tests/html_eof_runtime/`, and the resolved EdgeZero/Viceroy APIs. + +- [x] Record the chosen base, current tool pins and supported identity configuration. Confirm which components build state and which execute response finalization. +- [x] Locate or add a narrowly scoped test-only way to supply the app's platform services: store, geo, client info and typed browser metadata. Prefer existing injection points; never add an externally selectable bypass. +- [x] Write the smallest application-path acceptance probe: empty store, GDPR geo, serialized TCF Purpose-1 grant parsed from the actual request, successful origin response and trusted browser metadata. Require a new cookie and matching newly saved record. Do not invoke identity helpers manually from the runner. +- [x] Remove the trusted metadata and separately deny consent; show that the controls reach the intended gates. On the inspected baseline both prevent creation; after T12/#1592, absent JA4 must follow ID-7/DEC-18 and must not itself prevent creation. In this GDPR fixture, Purpose-1 denial or missing TCF consent always prevents fresh issuance. Preserve the existing non-regulated policy that permits creation without consent signals. Record operation counts and final response collection ordering. +- [x] Reconfirm the Viceroy constraint at execution: installed 0.21.0 `downstream_tls_ja4` returns absent metadata, so the unmodified production artifact cannot mint on local HTTP. Do not assume a UA header creates JA4. Also reassess after T12/#1592 permits absent JA4 under ID-7/DEC-18: that change can unblock local issuance without supplying real JA4, while real metadata extraction still requires separate qualification. Run a permitted local runtime probe during implementation if a documented mechanism exists. +- [x] Decide the evidence boundary from the probe. If the application cannot reach C1 through an existing or minimal test seam, stop detailed runner implementation and revise the design with the user. If only the production runtime ingress is unavailable, continue deterministic tests with that named qualification gap. + +Expected result: a demonstrated C1 path with meaningful controls, plus a recorded blocked conclusion for production-artifact fresh issuance under Viceroy 0.21.0 unless a newly verified capability changes that fact. Merely seeing `is_real_browser = true` is insufficient to pass this task. + +## Task 2: Build the shared scenario contract and fixture observations + +**Files:** proposed core test-support module; existing core test-support exports/store fakes. + +- [x] Define portable scenario descriptions for C1–C7 and observations for all response cookies, normalized record identity, final store contents and ordered store/response events. Keep native HTTP clients and process code out of portable support. +- [x] Add failing fixture tests demonstrating that an always-present fake record and a rejected write cannot satisfy C1. Inspect existing store tests before implementing another fake. Current backend fakes are private `cfg(test)` items: if reused downstream, minimally expose the necessary fixture under `cfg(any(test, feature = "test-utils"))` through test support, not as an unconditional production API. +- [x] Reuse or minimally extend the store fake to record successful and rejected creation, support generation/conditional-write semantics and inject the intended write failure without corrupting unrelated requests. +- [x] Implement shared assertions: C1 matches cookie to authoritative new row; C2 requires the injected creation error to have occurred; C3 rejects deletion/rotation; C5 checks both Purpose-1 denial and absent TCF consent in GDPR geo; C6 rejects creation on assets/APIs; C7 replays the issued identity. +- [x] Ensure assertions do not require all adapters to have identical incidental headers or timestamps. Preserve production cookie attribute assertions already covered by existing tests. +- [x] Verify on both the native target and `wasm32-wasip1`; keep the module under existing test-support features and add no production dependency. + +Commands from repository root, after confirming the selected base's aliases: + +```bash +cargo test -p trusted-server-core --lib identity_conformance +cargo test -p trusted-server-core --target wasm32-wasip1 --lib identity_conformance +cargo fmt --all -- --check +``` + +Expected: the intended tests execute (nonzero test count) and pass in both environments; a missing runner or compilation failure is not behavioral evidence. + +## Task 3: Run Fastly scenarios through the application lifecycle + +**Files:** Fastly app tests and the lifecycle test entry point identified in Task 1; portable support. + +- [x] Add C1 first and demonstrate a behavioral failure if response finalization is disconnected. Use a successful origin fixture so a fallback proxy error cannot mask the intended path. +- [x] Connect the runner to the real entry-point lifecycle or the exact production lifecycle callable used by that entry point, with test-only service injection. If that callable must be exposed, keep the change minimal and verify production still invokes it. +- [x] Add C2 with an explicit failed-write observation and response boundary assertion. Release no response before the creation outcome is known. +- [x] Add C3 for absent geo and geo errors, C5, C6 and C7. Check raw cookies as well as client replay behavior. +- [x] Keep existing seeded integration scenarios and withdrawal tests. Report missing C4/shared-app behavior as an outstanding prerequisite rather than adding a second Fastly startup policy. +- [x] Run target-matched verification: + +```bash +cargo test-fastly identity_conformance +cargo test-fastly +cargo test-fastly-reuse +cargo clippy-fastly +``` + +Expected: selected Fastly scenarios execute and pass. Full acceptance is still pending where #1600 or other integration work is required. Fix ownership of exposed runtime defects before changing production behavior. + +## Task 4: Add explicit CI execution and suite-delivery documentation + +**Files:** workflow files, `scripts/test-identity-conformance.mjs` and its tests, and the integration README. The existing native core and WASM Cargo test targets are sufficient; use a small launcher rather than add a host target that recompiles unrelated adapters. + +- [x] Add host orchestration that lists required scenarios for each explicitly selected adapter and fails if an expected runner or scenario is missing. Distinguish startup-rejection checks from supported-adapter lifecycle tests. +- [x] Add a PR job invoking Fastly conformance under Viceroy and the portable core fixture tests on the native target (not a positive Axum identity claim before Task 5), using the repository's tool setup and Node pin before cargo. Never label a runner with zero positive cases as conformance. +- [x] Document the exact invocation, required artifacts, supported adapter list and outstanding issue dependencies. Early suite delivery selects Fastly explicitly; this is not an assertion that Axum is supported. +- [ ] Include the runtime commands added in Task 5 in the runtime workflow only when they execute the advertised scenarios. An ignored test must have an explicit invocation with failures propagated. +- [x] Verify deliberately selecting an unavailable Axum lifecycle runner fails with an actionable message. CI must not convert it to a pass or silently omit it from a claimed MVP matrix. +- [ ] Run the available conformance targets and required checks before a suite-only handoff. Report remaining #1586 criteria without closing the issue. + +Suite launcher command: + +```bash +node scripts/test-identity-conformance.mjs fastly +``` + +Expected: assertions cover the advertised selected adapters and report the exact scenario set; qualification gaps remain explicit in the handoff. + +## Task 5: Integrate Axum, startup rejection and actual runtime requests + +**Prerequisites:** #1600 and #1574 for Axum positive behavior; shared startup/store capability validation for C4. These are follow-on integration obligations, not T5 production implementation tasks. + +**Files:** Axum tests, runtime target/helpers, integration workflow and README. + +- [ ] Run the unchanged C1–C7 contract on Axum through the shared app. Add C4 through the real startup initializer with valid configuration except the deliberately unsupported capability; prove the port never becomes available. Add an identity-disabled startup control. +- [ ] Run C4 for Cloudflare/Spin while unsupported, using their real initialization boundaries; do not pretend the host wrapper is the deployed runtime. When support lands, replace that unsupported expectation with the full positive contract for its valid capability configuration. +- [ ] Launch current native Axum and Fastly WASM artifacts with isolated config/store/origin resources, bounded startup/request deadlines and reliable cleanup after failure. Reuse the managed-process helpers instead of inventing another lifecycle framework. +- [ ] Send real HTTP navigation and replay requests, inspect cookies and records, and capture the build revision and artifact path. On Axum use the trusted proxy configuration for geo/client metadata; verify forged metadata from an untrusted peer cannot activate identity. +- [ ] Execute fresh creation on the production artifact only where Task 1 established supported runtime metadata. If an alternate fixture binary is needed, name that evidence level explicitly and keep production ingress qualification outstanding. +- [ ] Implement local runtime scenarios under the `identity_runtime_` test prefix in the new host target, explicitly invoked by CI with `--ignored --test-threads=1` if they require prebuilt artifacts. The command below runs both required runtime runners; absence of either must fail the selected MVP invocation. + +```bash +cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1 +cargo build --package trusted-server-adapter-axum +cargo test --manifest-path crates/trusted-server-integration-tests/Cargo.toml --test identity_conformance identity_runtime_ -- --ignored --test-threads=1 +cargo test-axum +cargo clippy-axum +``` + +The implementation must document the configuration/artifact environment selected by these tests using the existing integration harness conventions. These commands describe follow-on runtime targets; they are not implemented or exercised by the suite-only delivery. Local runtime success does not certify a deployed provider or real TLS ingress. + +## Task 6: Enforce the architecture and qualify the claims + +**Prerequisite:** #1600 removes existing production adapter-owned identity calls before the clean architecture check can become blocking. + +**Files:** boundary lint script and tests; workflow; README. + +- [ ] Inventory production EC generation/finalization and handler call sites on the selected base, including aliases. Keep this separate from behavior assertions. +- [ ] Add regression fixtures for direct calls, renamed imports, qualified calls, test-only modules, external test files and unrelated similarly named methods. Choose a narrow parser or existing tooling; do not add a general Rust parser dependency without justification. +- [ ] Run `node --test scripts/lint-identity-boundaries.test.mjs` and `node scripts/lint-identity-boundaries.mjs`. After #1600, require no production violations in all adapter crates. Before it, report violations; do not make a permanent allowlist or return success for a failed requirement. +- [ ] In a disposable copy, run the five behavioral broken controls listed in the spec, with a clean baseline and restored result. Retain the intended assertion failure, rather than counting compile errors as detections. +- [ ] Run the full applicable `AGENTS.md` CI gate list, including target-matched lints, adapter suites, parity, JS/docs formatting, domain lint and the native build-digest checks. The scenario commands supplement those gates. Apply conditional EOF/runtime gates if changes reach those surfaces. +- [ ] Prepare a matrix separating application conformance, local runtime integration and production qualification for each adapter. Record revisions and tools, failures, skips, unexecuted paths and remaining dependencies. +- [ ] Prepare, but do not execute without authorization, production ingress qualification: deploy the exact tested artifact to an approved isolated service, navigate with a fresh real browser, inspect the matching provider record, replay the cookie and clean up owned fixture data. Never use a deployed fault injection that can affect unrelated users. + +Expected: a truthful suite-delivery or integrated-conformance conclusion. Production qualification remains pending until actually executed; #1586's startup and SH-5 criteria remain pending until their real integration passes. Publication and deployment require separate authorization; this implementation does not publish changes. + +## Planning validation + +Validate Markdown formatting and relative links for the two planning documents. Do not run Rust builds or claim behavior verification merely to review documentation. Reconcile independent reviews against the entire final spec and plan before handing them back to the user. + +## Review log + +- Round 1 (Codex): no blocking plan findings. Added the Fastly entry-point file to the map, clarified gated reuse of private store fakes, separated portable native tests from Axum activation, and scoped missing-JA4 rejection to the current baseline. + +- Round 2 (Codex, independent session): no blocking findings in the full plan. Confirmed target/feature wiring, scenario coverage and dependency boundaries. Corrected the inspection path from nonexistent `ec/context.rs` to `ec/mod.rs`. Review was source-only; commands and runtime scenarios remain unexecuted. + +## Suite delivery progress + +Tasks 1–3 and Task 4's selector, CI and documentation wiring are implemented. +The shared suite currently executes nine Fastly scenarios. Eight native tests +check the assertion/store contract, including rejected tombstones, late writes, +late failures and expired returning cookies; a portable store test also executes +under WASM. Five launcher tests reject unavailable adapters and vacuous success. + +An isolated copy passed conformance, failed at the missing-cookie assertion when +the shared production finalization callback was disconnected, and passed again +after restoration. No production browser or store-provider qualification was +performed. The application's ordinary and reusable Fastly test suites and target +clippy are checked locally; the full PR gate list remains required before handoff. + +The supplemental native core all-targets/test-utils clippy invocation reports +`result_large_err` in the existing `run_pre_dispatch_hook` helper. Restoring core +sources to the unchanged cutover base in an isolated copy reproduces that lint. +It is not suppressed or changed by this suite. Tasks 5–6, including startup, +Axum activation, SH-5 enforcement and production qualification, remain pending. diff --git a/docs/superpowers/specs/2026-11-16-identity-conformance-design.md b/docs/superpowers/specs/2026-11-16-identity-conformance-design.md new file mode 100644 index 0000000000..79e0c29df5 --- /dev/null +++ b/docs/superpowers/specs/2026-11-16-identity-conformance-design.md @@ -0,0 +1,122 @@ +# Identity conformance across adapters + +Status: approved for suite implementation on 2026-11-16. Tasks 1–4 are in progress; later integration and production qualification remain outstanding. + +Issue: [#1586](https://github.com/IABTechLab/trusted-server/issues/1586) (T5). +Implementation plan: [identity conformance](../plans/2026-11-16-identity-conformance.md). +Program requirements: ID-1 and SH-5 in the [server-side identity design](https://github.com/IABTechLab/trusted-server/blob/c7dc9de77d31692412aec2768ae3f11fe0d52bbb/docs/superpowers/specs/2026-11-11-server-side-identity-all-adapters-design.md). + +## Problem and outcome + +An Edge Cookie (`ts-ec`) identifies a reader's server-side record. A new cookie must only leave the application after its matching record has been persisted. An unknown location must not erase a returning reader's identity. Every adapter must either support the identity contract or reject identity-enabled startup explicitly. + +Core already implements parts of these rules. The missing assurance is that each adapter actually runs the complete lifecycle. Tests of a helper cannot detect an adapter that forgets finalization, and equality between two empty responses cannot prove successful identity creation. + +T5 supplies reusable behavioral scenarios, adapter runners, failure fixtures, architecture checks and CI execution. It does not implement the shared identity application or add production identity to Axum. + +## Source baseline and feasibility + +Inspected on 2026-11-16: main `1810c763add220dd34fd5faaffe2c69aab1d556f` and cutover PR #1506 at `cc811fc7aa0d234e447a868af5b8ab4ea359326a`. These are source observations, not runtime qualification. + +| Source | Established fact | Design consequence | +| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| `crates/trusted-server-core/src/ec/finalize.rs` | New cookies require an authoritative record; unknown jurisdiction has preservation coverage | Exercise these rules through application entry points; retain existing tests | +| `crates/trusted-server-adapter-fastly/src/app.rs` and `src/main.rs` | Fastly owns EC dispatch and response finalization today | Router-only assertions are insufficient; the runner must execute response finalization too | +| `crates/trusted-server-adapter-axum/src/app.rs` | Axum does not yet mount the full identity lifecycle | Axum's positive conformance result depends on #1574 | +| `crates/trusted-server-integration-tests/tests/parity.rs` | Host adapter parity excludes Fastly | Share scenarios across host and WASM runners, not one host executable that imports Fastly | +| `crates/trusted-server-integration-tests/tests/integration.rs`, `test_ec_lifecycle_fastly` | Existing runtime scenarios seed a record because local HTTP lacks browser fingerprints | Seeded tests remain useful but cannot certify fresh creation | +| Fastly `browser_device_signals_from_extension_reach_ec_finalize_state` | Typed device metadata can reach the app's browser gate | Controlled application fixtures are feasible; this does not establish metadata arrival through a production network ingress | + +Before implementing runners, repeat these checks against the selected cutover revision and prove a supported fixture can reach fresh creation. The locally installed Viceroy 0.21.0 source (`viceroy-lib`, `src/wiggle_abi/http_downstream.rs`, `downstream_tls_ja4`) explicitly returns absent metadata. Its device-detection configuration does not supply JA4. The current browser gate requires a nonempty parsed JA4 section and recognized UA platform (`core/src/ec/device.rs`); H2 metadata is not an additional minting requirement. Therefore local HTTP to the unmodified Fastly artifact cannot prove fresh creation on this runtime. Retain that qualification gap rather than weakening browser checks. + +## Delivery boundaries and stacking + +PR #1506 implements blocker #1507 and was open when inspected. Base the code PR on its branch, `spec/edgezero-pr275-migration`, if it remains unmerged and that head is still the approved cutover base. Otherwise use main after the cutover lands. Record and revalidate the exact base SHA before coding. Do not stack on the superseded Axum-specific #1536, #1537 or #1566 wiring. + +The planning documents can be reviewed independently of that code stack. No PR creation, push or deployment is part of this planning task. + +The program deliberately schedules T5 before #1600 (T21, shared identity app) and #1574 (A2, Axum activation). Consequently: + +1. **Suite delivery:** T5 defines the contract and runs applicable Fastly scenarios. Explicitly report missing startup, shared-app or Axum capabilities as outstanding integration obligations. Existing defects exposed by these tests are not silently fixed inside T5. +2. **MVP integration:** #1600 removes direct identity calls from adapter orchestration; #1574 enables Axum and runs the same full scenario set. This is required before claiming Fastly/Axum conformance and closing the corresponding acceptance obligations. +3. **Later platforms:** #1588 and the Spin rollout supply their platform support and execute the same contract. Until then, identity-enabled startup must reject unsupported capabilities once the common startup validation exists. + +T5 must not be described as fulfilling all of #1586's acceptance criteria merely because its test infrastructure merged. No ignored, empty or silently omitted scenario counts as a pass. Track remaining acceptance in the PR description and linked issues; do not auto-close #1586 on infrastructure delivery alone. + +## Design + +### Shared scenarios and observations + +Define adapter-neutral inputs and expected outcomes once in test support. Each scenario gets an isolated store namespace, settings, client identity and origin. A runner supplies startup, request execution, response collection, store inspection and teardown. Share behavior and assertions; keep runtime startup and transport specific to the adapter. + +Observe all `Set-Cookie` headers separately, normalized EC keys, persisted record contents and a fixture operation log. The log distinguishes a successful durable write from an attempted or rejected write. The response returned to the scenario must include the application's real response-finalization stage. Never have a test call EC generation or finalization manually to repair missing application wiring. + +Use existing EC clients, minimal origins, process cleanup helpers and settings constructors where suitable. Avoid a new general-purpose test framework or production dependency. WASM tests and native tests may compile the same portable scenario module separately; do not require native-only test crates in the Fastly target. + +### Acceptance scenarios + +| ID | Input and setup | Required observations | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| C1 Fresh creation | Empty store; no EC cookie; serialized TCF Purpose-1 grant parsed by the application; GDPR geo; trusted browser metadata; successful HTML navigation | Successful publisher document response; exactly one non-deletion `ts-ec`; its normalized key identifies the new authoritative record; persistence completes before response release | +| C2 Write failure | Same reachable input as C1; fail the record-creation write | Fault log proves creation was attempted and rejected; publisher page remains available; no non-deletion `ts-ec`; no newly persisted identity | +| C3 Unknown geo | Valid existing EC and record; no withdrawal; geo absent or lookup error | Existing cookie value remains the client's identity; no expiry or replacement; no new identity record | +| C4 Unsupported startup | Identity explicitly enabled; record contract or required platform capability unsupported | Startup fails with an actionable capability error before serving requests; a generic configuration parse failure does not satisfy the assertion | +| C5 No consent | Fresh C1 input in GDPR geo with serialized Purpose-1 denial or missing TCF consent | No identity created and no new EC cookie; consent fixture is checked against the actual parser | +| C6 Ineligible response | Asset/API request using otherwise eligible input | No new identity cookie or record; retain existing withdrawal behavior in its own tests | +| C7 Returning reader | Replay C1 cookie with known geo and existing record | Same identity remains usable on the next request; no second identity minted | + +C1/C2/C5 use an explicitly GDPR-regulated location and consent encoded in the request representation consumed by the real parser, never a hand-built `ConsentContext`. Verify both denied and missing consent variants in C5. Absence of consent in a non-regulated jurisdiction currently permits creation; preserve that policy and its existing tests. + +C3 checks raw response headers and a replaying cookie jar: an omitted response cookie is acceptable; deletion, rotation or replacement is not. Check both unknown-geo forms. C2 and C5 cannot pass by taking the non-browser fallback: they inherit C1's successful ingress setup and assert the relevant gate or failed operation was reached. + +Identity startup validation must distinguish identity enablement from ordinary EC cryptographic settings used by consent-only adapters. Reuse the configuration contract delivered by the shared-app/store work; do not invent a second enablement key in T5. A disabled identity startup control must succeed with otherwise valid settings. + +The EC route is delivered by #1598. When it becomes available, apply C1/C2/C5 to its supported POST flow and test its separate GET semantics there. Do not introduce the route in this PR or claim it was exercised before that integration lands. + +### Fixtures and production boundaries + +The browser gate observations above describe the inspected baseline only. Program ID-7/DEC-18 later permits absent or unrecognized trusted JA4 and rejects a known family contradiction. T5 must follow the active production policy rather than freeze the old absence rejection: keep the current missing-metadata probe as baseline evidence, and update its expectation when #1592 delivers T12. C1–C7 do not require an absent-JA4 rejection. Reassess whether ordinary Viceroy HTTP can exercise fresh creation after that change; inability to expose JA4 remains a limit on testing real fingerprint extraction, not necessarily on minting. + +Provide a deterministic store with recording and fault injection at the platform-service boundary used by the application. Preserve conditional-write semantics, generation markers and authoritative reads needed by the EC contract. A fake that always returns a record cannot test creation or write failure. Existing EC backend fakes are private under `cfg(test)` on the inspected baseline. If downstream runners need them, expose only the necessary fixture under `cfg(any(test, feature = "test-utils"))` through test support, preserving private production internals. Reuse existing core store fakes where their semantics match; use real provider tests to cover provider-specific durability and consistency. + +Inject location and device metadata as typed platform services or request extensions in a test-only runner. No public request header, production environment override or relaxed browser gate may activate these fixtures. Do not prepopulate C1's record, construct its EC context manually or bypass consent parsing. Check the supported metadata contract again after #1506 and #1600, since their APIs are moving. + +### End-to-end evidence + +Use complementary levels; report their results separately: + +1. **Application conformance:** controlled platform inputs pass through the real router, identity lifecycle and finalization, with response and record assertions. This is mandatory and deterministic, including C2 failure injection. +2. **Local runtime integration:** real HTTP to current Fastly WASM under Viceroy and the native Axum executable, a minimal publisher origin and isolated stores. Assert document response, cookie persistence/replay and matching records wherever the runtime exposes the required trusted metadata. A fixture-specific binary may prove runtime lifecycle mechanics, but must be labeled as such and cannot certify the unmodified production ingress. +3. **Production ingress qualification:** fresh browser navigation to the unmodified deployed artifact, using trusted platform metadata and a supported record provider, followed by independent record inspection and a returning navigation. Required before declaring production ingress fully qualified. Deployment and credential use require separate authorization. Storage fault guarantees remain primarily established by controlled application tests, not destructive failure injection into a live service. + +For Fastly, local positive creation through the unmodified artifact is blocked by the inspected Viceroy 0.21.0 JA4 hostcall implementation. Task 1 in the plan must determine whether the pinned simulator supports the required metadata. If not, application conformance plus seeded runtime tests may ship with an explicit gap, but cannot be reported as complete runtime or production qualification. For Axum, trusted proxy metadata must be supplied through the configured trusted-peer path, with a forged untrusted-peer negative control. + +These tests cover the EC contract, not the entire provider, SharedID, mirror-cookie or CMP-script program. Those features and their browser tests retain their own tickets. + +### Architecture and CI + +Keep a distinct SH-5 check for production adapter source calling EC generation, finalization or identity handlers directly. Implement a narrow syntax-aware check using existing repository tooling, or inspect imports and aliases as well as calls in a scoped script with regression fixtures. Exclude test modules and test targets without excluding production modules. Demonstrate it rejects both a direct call and an imported alias. No broad search for a single function spelling counts as proof of this requirement. + +Before #1600, report existing violations explicitly and leave the requirement outstanding. After #1600, the check becomes blocking for all adapter crates, including unsupported adapters. Do not establish a permanent exception list for legacy calls. + +Run the deterministic conformance jobs on pull requests. Run required runtime scenarios explicitly in `.github/workflows/integration-tests.yml`; an ignored Rust test needs an explicit CI invocation and result. Require the selected supported adapter's full applicable scenario set, not a runner that returns success for zero scenarios. Publish a concise adapter/scenario/evidence-level summary, with unexecuted obligations visible. + +## Compatibility, privacy and exclusions + +T5 adds no operator configuration and changes no cookie or consent semantics. Use fictional identifiers and example domains; never log identity values outside isolated fixture diagnostics. Keep production secrets out of fixtures. Do not add provider implementations, new platform capabilities, an Axum store, application extraction, provider fan-out, rate limits or deployment infrastructure here. + +Preserve existing EC unit tests, seeded Fastly scenarios, withdrawal/tombstone behavior, cookie attributes and asset cache behavior. If tests expose a production defect, record it and resolve its ownership before extending this PR. + +## Verification and completion + +Demonstrate the suite rejects plausible broken behavior in an isolated disposable copy: suppress record persistence while issuing a cookie (C1), issue a cookie after the injected write failure (C2), expire or rotate on unknown geo (C3), accept unsupported startup (C4), and drop application finalization (C1). Setup or compilation failures are inconclusive, not successful negative controls. + +The implementation runs target-matched checks plus the complete applicable gate list in `AGENTS.md` before handoff. Record exact revisions, tool versions, feature sets and which fixture or production artifact each runtime used. A suite-only delivery and complete issue acceptance are separate conclusions. This document is not runtime evidence. + +Expected implementation size: medium, approximately 6–12 files and 500–1,000 lines for suite infrastructure if prerequisite test seams are available. Full runtime qualification or substantial missing seams may exceed that estimate and require a scope reassessment. + +## Review log + +- Round 1 (Codex): found that the no-consent scenario could incorrectly reject valid non-regulated behavior. Pinned creation/failure/consent fixtures to GDPR with parsed TCF Purpose-1 grant, denial and absent-signal variants. Clarified the present JA4 presence check and future ID-7/DEC-18 behavior. + +- Round 2 (Codex, independent session): no blocking findings after checking the full revised specification and plan against source. Confirmed GDPR fixture reach, finalization/persistence assertions, future absent-JA4 policy, and explicit integration/qualification obligations. Review was source-only; no runtime behavior was verified. diff --git a/scripts/test-identity-conformance.mjs b/scripts/test-identity-conformance.mjs new file mode 100644 index 0000000000..7ddfec4bb7 --- /dev/null +++ b/scripts/test-identity-conformance.mjs @@ -0,0 +1,50 @@ +#!/usr/bin/env node + +import { spawnSync } from "node:child_process"; +import { pathToFileURL } from "node:url"; + +const testName = "identity_conformance::identity_conformance_fastly"; + +export function runSuite(adapter, run = runCargo) { + if (adapter === "axum") + throw new Error("Axum identity runner awaits #1574 and #1600"); + if (adapter === "cloudflare" || adapter === "spin") { + throw new Error(`${adapter} identity runner is not available yet`); + } + if (adapter !== "fastly") throw new Error(`Unknown adapter: ${adapter}`); + const args = ["test-fastly", testName, "--locked"]; + const listed = run([...args, "--", "--list"]); + if (!listed.stdout.split(/\r?\n/).includes(`${testName}: test`)) { + throw new Error(`Missing required conformance test: ${testName}`); + } + const result = run([...args, "--", "--exact", "--nocapture"]); + if (!/test result: ok\. 1 passed; 0 failed;/.test(result.stdout)) { + throw new Error("Required conformance test did not execute successfully"); + } + return result.stdout; +} + +function runCargo(args) { + const result = spawnSync("cargo", args, { + encoding: "utf8", + maxBuffer: 16 * 1024 * 1024, + }); + if (result.error) throw result.error; + if (result.status !== 0) { + throw new Error(result.stderr || result.stdout || "Identity suite failed"); + } + process.stderr.write(result.stderr); + return result; +} + +if ( + process.argv[1] && + import.meta.url === pathToFileURL(process.argv[1]).href +) { + try { + process.stdout.write(runSuite(process.argv[2] ?? "fastly")); + } catch (error) { + process.stderr.write(`${error.message}\n`); + process.exitCode = 1; + } +} diff --git a/scripts/test-identity-conformance.test.mjs b/scripts/test-identity-conformance.test.mjs new file mode 100644 index 0000000000..98e63609c7 --- /dev/null +++ b/scripts/test-identity-conformance.test.mjs @@ -0,0 +1,63 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { runSuite } from "./test-identity-conformance.mjs"; + +const testName = "identity_conformance::identity_conformance_fastly"; + +test("an unavailable adapter fails before invoking cargo", () => { + let invoked = false; + assert.throws( + () => + runSuite("axum", () => { + invoked = true; + return { stdout: "" }; + }), + /Axum.*#1574/, + ); + assert.equal(invoked, false); +}); + +test("an unknown adapter fails explicitly", () => { + assert.throws( + () => runSuite("example", () => ({ stdout: "" })), + /Unknown adapter/, + ); +}); + +test("a successful cargo command listing no conformance test is rejected", () => { + assert.throws( + () => runSuite("fastly", () => ({ stdout: "0 tests, 0 benchmarks\n" })), + /Missing required/, + ); +}); + +test("a zero-test execution is rejected after a successful listing", () => { + let calls = 0; + assert.throws( + () => + runSuite("fastly", () => ({ + stdout: + ++calls === 1 + ? `${testName}: test\n` + : "test result: ok. 0 passed; 0 failed; 0 ignored;\n", + })), + /did not execute/, + ); +}); + +test("the exact listed conformance test must pass", () => { + const commands = []; + const output = runSuite("fastly", (args) => { + commands.push(args); + return { + stdout: + commands.length === 1 + ? `${testName}: test\n` + : "test result: ok. 1 passed; 0 failed; 0 ignored;\n", + }; + }); + assert.match(output, /1 passed/); + assert.ok(commands[0].includes("--list")); + assert.ok(commands[1].includes("--exact")); + assert.ok(commands.every((command) => command.includes(testName))); +}); From 0fc2ff0a2bf36e9c479bc7495d6c9e4632b7d969 Mon Sep 17 00:00:00 2001 From: prk-Jr Date: Mon, 16 Nov 2026 18:08:11 +0530 Subject: [PATCH 2/3] Document the conformance post-delivery boundary and normalize returning lookups --- .../src/test_support/identity_conformance.rs | 5 +++-- crates/trusted-server-integration-tests/README.md | 5 +++++ .../specs/2026-11-16-identity-conformance-design.md | 2 ++ 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/crates/trusted-server-core/src/test_support/identity_conformance.rs b/crates/trusted-server-core/src/test_support/identity_conformance.rs index 0af23a7072..c45ca5f78d 100644 --- a/crates/trusted-server-core/src/test_support/identity_conformance.rs +++ b/crates/trusted-server-core/src/test_support/identity_conformance.rs @@ -309,6 +309,7 @@ impl Scenario { _ => { let identity = assert_created(&response, store); if matches!(self, Self::UnknownGeo | Self::GeoFailure | Self::Returning) { + let key = normalize_ec_id_for_kv(&identity); let keys = store .list_keys_with_prefix("", 100) .expect("should inspect issued rows"); @@ -328,7 +329,7 @@ impl Scenario { "should retain the reader's cookie" ); let (record, _) = graph - .get(&identity) + .get(&key) .expect("should read returning record") .expect("should retain the returning record"); assert!( @@ -346,7 +347,7 @@ impl Scenario { "should preserve identity on replay" ); let (record, _) = graph - .get(&identity) + .get(&key) .expect("should inspect replayed identity") .expect("should retain the existing record"); assert!( diff --git a/crates/trusted-server-integration-tests/README.md b/crates/trusted-server-integration-tests/README.md index 1d78c43480..0e9756c02a 100644 --- a/crates/trusted-server-integration-tests/README.md +++ b/crates/trusted-server-integration-tests/README.md @@ -70,6 +70,11 @@ must be observed before release. Returning scenarios apply cookie expiry rules and replay the resulting identity. The missing-metadata expectation describes the current pre-T12 policy and must change when #1592 permits absent JA4. +The suite ends when the finalized response is delivered. Post-delivery work +(queued telemetry and EC pull sync) does not run, and pull sync opens its own +store rather than the recording fixture, so release-ordering assertions cover +writes made during finalization only. + This is application conformance, not fresh-browser qualification through an unmodified deployed artifact. Viceroy 0.21 does not expose JA4, so the current production browser gate prevents fresh issuance over ordinary local HTTP. diff --git a/docs/superpowers/specs/2026-11-16-identity-conformance-design.md b/docs/superpowers/specs/2026-11-16-identity-conformance-design.md index 79e0c29df5..8f20e59aca 100644 --- a/docs/superpowers/specs/2026-11-16-identity-conformance-design.md +++ b/docs/superpowers/specs/2026-11-16-identity-conformance-design.md @@ -93,6 +93,8 @@ For Fastly, local positive creation through the unmodified artifact is blocked b These tests cover the EC contract, not the entire provider, SharedID, mirror-cookie or CMP-script program. Those features and their browser tests retain their own tickets. +Application conformance ends when the finalized response is delivered. The Fastly runner does not run post-delivery work (queued telemetry and EC pull sync), and pull sync opens its own store through `require_identity_graph` rather than the recording fixture. The release-ordering assertions therefore cover writes made during finalization only. A post-delivery write or deletion that changes a returning reader's record is outside this suite; pull sync's partner writes keep their own tests. + ### Architecture and CI Keep a distinct SH-5 check for production adapter source calling EC generation, finalization or identity handlers directly. Implement a narrow syntax-aware check using existing repository tooling, or inspect imports and aliases as well as calls in a scoped script with regression fixtures. Exclude test modules and test targets without excluding production modules. Demonstrate it rejects both a direct call and an imported alias. No broad search for a single function spelling counts as proof of this requirement. From 399bb67122c29642d17c1b0d713c1726a5140073 Mon Sep 17 00:00:00 2001 From: prk-Jr Date: Tue, 17 Nov 2026 10:54:17 +0530 Subject: [PATCH 3/3] Run identity conformance through production prepare and require refusal before writes The Fastly runner now uses the production native request read and prepare, replacing only the client IP, geo result and JA4-backed device signals that Viceroy cannot supply. Refused scenarios must stop before any write attempt, with a native control proving the check rejects one. Docs describe the failed-geo fixture and record current progress. --- .../src/identity_conformance.rs | 47 +++++++++++-------- .../src/test_support/identity_conformance.rs | 19 ++++++++ .../README.md | 14 ++++-- .../plans/2026-11-16-identity-conformance.md | 17 +++++-- .../2026-11-16-identity-conformance-design.md | 4 +- 5 files changed, 70 insertions(+), 31 deletions(-) diff --git a/crates/trusted-server-adapter-fastly/src/identity_conformance.rs b/crates/trusted-server-adapter-fastly/src/identity_conformance.rs index bda4e9dd30..a8df3bfebc 100644 --- a/crates/trusted-server-adapter-fastly/src/identity_conformance.rs +++ b/crates/trusted-server-adapter-fastly/src/identity_conformance.rs @@ -21,9 +21,12 @@ use trusted_server_core::test_support::scripted_client::{ use edgezero_core::outbound::HttpClient; use std::time::{SystemTime, UNIX_EPOCH}; -use super::{FinalizeInputs, assemble_app, handle_delivery, with_finalization}; +use super::{ + ClientRequestValues, FinalizeInputs, assemble_app, handle_delivery, with_finalization, +}; use crate::platform::RequestGeo; use crate::sandbox::SandboxCounters; +use crate::tinybird::TelemetryQueue; use fastly::Request as FastlyRequest; use trusted_server_core::ec::device::DeviceSignals; use trusted_server_core::geo::GeoInfo; @@ -169,7 +172,7 @@ impl Adapter for FastlyAdapter { if let Some(identity) = &navigation.ec_cookie { cookies.push(format!("ts-ec={identity}")); } - let request = FastlyRequest::get("https://publisher.example.com/article") + let mut request = FastlyRequest::get("https://publisher.example.com/article") .with_header("sec-fetch-dest", navigation.destination) .with_header( "accept", @@ -181,30 +184,36 @@ impl Adapter for FastlyAdapter { ) .with_header("user-agent", USER_AGENT) .with_header("cookie", cookies.join("; ")); + // Production's native read and `prepare` run unchanged. The fixture + // replaces only the values Viceroy cannot supply: a routable client IP, + // its geo result and, for browser scenarios, JA4-backed device signals. + let mut values = ClientRequestValues::read(&mut request, &self.settings, false); + let ip = Some("192.0.2.7".parse().expect("should parse fixture IP")); + values.client_info = ClientInfo { + client_ip: ip, + ..ClientInfo::default() + }; + values.request_geo = if navigation.geo == Geo::Failed { + RequestGeo::failing(ip) + } else { + RequestGeo::new(ip, geo.clone()) + }; + if navigation.browser { + values.device_signals = Some(DeviceSignals::derive( + USER_AGENT, + Some("t13d1516h2_example_example"), + None, + )); + } + let queue = TelemetryQueue::default(); let mut observation = None; let origin = self.origin.clone(); let delivery = with_finalization(&inputs, |finalize| { FastlyService::new(&self.retained.app).run_request_with_hooks_for_test( request, |_request, extensions| { + values.prepare(extensions, &self.settings, &queue); extensions.insert(HttpClient::with_client(origin)); - let ip = Some("192.0.2.7".parse().expect("should parse fixture IP")); - extensions.insert(ClientInfo { - client_ip: ip, - ..ClientInfo::default() - }); - extensions.insert(if navigation.geo == Geo::Failed { - RequestGeo::failing(ip) - } else { - RequestGeo::new(ip, geo.clone()) - }); - if navigation.browser { - extensions.insert(DeviceSignals::derive( - USER_AGENT, - Some("t13d1516h2_example_example"), - None, - )); - } }, finalize, |envelope| { diff --git a/crates/trusted-server-core/src/test_support/identity_conformance.rs b/crates/trusted-server-core/src/test_support/identity_conformance.rs index c45ca5f78d..7d4e1aa8de 100644 --- a/crates/trusted-server-core/src/test_support/identity_conformance.rs +++ b/crates/trusted-server-core/src/test_support/identity_conformance.rs @@ -288,6 +288,18 @@ impl Scenario { .is_empty(), "should not persist an identity" ); + if self != Self::WriteFailure { + // These scenarios share Fresh's successful setup and change + // one input, so its gate must refuse before any write; a + // creation attempt that merely failed would not satisfy it. + assert!( + !store + .events() + .iter() + .any(|event| matches!(event, Event::Persisted(_) | Event::Rejected(_))), + "should refuse creation before attempting a write" + ); + } if self == Self::WriteFailure { let events = store.events(); let rejected = events @@ -620,6 +632,13 @@ mod tests { let store = RecordingStore::new(true); Scenario::WriteFailure.verify(&mut LateRejectionAdapter(store.clone()), &store); } + + #[test] + #[should_panic(expected = "should refuse creation before attempting a write")] + fn identity_conformance_rejects_denied_consent_write_attempt() { + let store = RecordingStore::new(true); + Scenario::DeniedConsent.verify(&mut LateRejectionAdapter(store.clone()), &store); + } } #[cfg(test)] diff --git a/crates/trusted-server-integration-tests/README.md b/crates/trusted-server-integration-tests/README.md index 0e9756c02a..acde4abbd0 100644 --- a/crates/trusted-server-integration-tests/README.md +++ b/crates/trusted-server-integration-tests/README.md @@ -62,12 +62,16 @@ they do not claim Axum identity support. The Fastly application test executes nine isolated scenarios: fresh creation, rejected writes, missing and failed geo, denied and absent GDPR consent, subresources, returning readers, and the current missing-browser-metadata gate. -It uses the real request conversion, router, shared production finalization -callback composition and consumed HTML response. Platform metadata, record -storage and the publisher origin are controlled test fixtures. Successful +It uses the production native request read and `prepare`, the real request +conversion, router, shared production finalization callback composition and +consumed HTML response. The client IP, geo result, browser device signals, +record storage and publisher origin are controlled test fixtures. Successful issuance requires the matching record before response release; failed writes -must be observed before release. Returning scenarios apply cookie expiry rules -and replay the resulting identity. The missing-metadata expectation describes +must be observed before release. Refused scenarios must stop before any write +is attempted. Returning scenarios apply cookie expiry rules and replay the +resulting identity. Fastly's production geo lookup reports a failure as missing +geo, so the failed-geo scenario uses a test-only failing lookup to check the +shared contract that other platforms' error results must also preserve. The missing-metadata expectation describes the current pre-T12 policy and must change when #1592 permits absent JA4. The suite ends when the finalized response is delivered. Post-delivery work diff --git a/docs/superpowers/plans/2026-11-16-identity-conformance.md b/docs/superpowers/plans/2026-11-16-identity-conformance.md index 8d3d9dcc3a..3e566e42cb 100644 --- a/docs/superpowers/plans/2026-11-16-identity-conformance.md +++ b/docs/superpowers/plans/2026-11-16-identity-conformance.md @@ -100,7 +100,7 @@ Expected: selected Fastly scenarios execute and pass. Full acceptance is still p - [x] Document the exact invocation, required artifacts, supported adapter list and outstanding issue dependencies. Early suite delivery selects Fastly explicitly; this is not an assertion that Axum is supported. - [ ] Include the runtime commands added in Task 5 in the runtime workflow only when they execute the advertised scenarios. An ignored test must have an explicit invocation with failures propagated. - [x] Verify deliberately selecting an unavailable Axum lifecycle runner fails with an actionable message. CI must not convert it to a pass or silently omit it from a claimed MVP matrix. -- [ ] Run the available conformance targets and required checks before a suite-only handoff. Report remaining #1586 criteria without closing the issue. +- [x] Run the available conformance targets and required checks before a suite-only handoff. Report remaining #1586 criteria without closing the issue. Suite launcher command: @@ -162,10 +162,17 @@ Validate Markdown formatting and relative links for the two planning documents. ## Suite delivery progress Tasks 1–3 and Task 4's selector, CI and documentation wiring are implemented. -The shared suite currently executes nine Fastly scenarios. Eight native tests -check the assertion/store contract, including rejected tombstones, late writes, -late failures and expired returning cookies; a portable store test also executes -under WASM. Five launcher tests reject unavailable adapters and vacuous success. +The shared suite currently executes nine Fastly scenarios through the +production native request read and `prepare`. Nine native tests check the +assertion/store contract: eight rejection controls, covering rejected +tombstones, late writes, late failures, expired returning cookies and a write +attempted by a refused scenario, plus a conditional-write store test that also +executes under WASM. Five launcher tests reject unavailable adapters and vacuous +success. + +Removing the device-signals insertion from production `prepare` made the Fastly +suite fail at "should issue exactly one EC cookie"; it passed again after +restoration. An isolated copy passed conformance, failed at the missing-cookie assertion when the shared production finalization callback was disconnected, and passed again diff --git a/docs/superpowers/specs/2026-11-16-identity-conformance-design.md b/docs/superpowers/specs/2026-11-16-identity-conformance-design.md index 8f20e59aca..e551d8ab7d 100644 --- a/docs/superpowers/specs/2026-11-16-identity-conformance-design.md +++ b/docs/superpowers/specs/2026-11-16-identity-conformance-design.md @@ -1,6 +1,6 @@ # Identity conformance across adapters -Status: approved for suite implementation on 2026-11-16. Tasks 1–4 are in progress; later integration and production qualification remain outstanding. +Status: approved for suite implementation on 2026-11-16. Tasks 1–4 are implemented for suite delivery; later integration and production qualification remain outstanding. Issue: [#1586](https://github.com/IABTechLab/trusted-server/issues/1586) (T5). Implementation plan: [identity conformance](../plans/2026-11-16-identity-conformance.md). @@ -67,7 +67,7 @@ Use existing EC clients, minimal origins, process cleanup helpers and settings c C1/C2/C5 use an explicitly GDPR-regulated location and consent encoded in the request representation consumed by the real parser, never a hand-built `ConsentContext`. Verify both denied and missing consent variants in C5. Absence of consent in a non-regulated jurisdiction currently permits creation; preserve that policy and its existing tests. -C3 checks raw response headers and a replaying cookie jar: an omitted response cookie is acceptable; deletion, rotation or replacement is not. Check both unknown-geo forms. C2 and C5 cannot pass by taking the non-browser fallback: they inherit C1's successful ingress setup and assert the relevant gate or failed operation was reached. +C3 checks raw response headers and a replaying cookie jar: an omitted response cookie is acceptable; deletion, rotation or replacement is not. Check both unknown-geo forms. C2 and C5 cannot pass by taking the non-browser fallback: they inherit C1's successful ingress setup and change one input. C2 asserts the rejected creation write occurred; C5 asserts creation was refused before any write was attempted. Identity startup validation must distinguish identity enablement from ordinary EC cryptographic settings used by consent-only adapters. Reuse the configuration contract delivered by the shared-app/store work; do not invent a second enablement key in T5. A disabled identity startup control must succeed with otherwise valid settings.