Name the declared permissions in the device refusal and align the guides with the flow

The startup refusal for a module device provider that declares permissions now names the Data Uses it declared, which the pluggable-providers spec already said it did. The permission-model guide and the permissions module doc no longer say a device or geo declaration is recorded rather than enforced, because a module device declaration is refused at startup and a geo declaration is not consulted. The guide now says request filters receive the state on the Fastly adapter, the only adapter that runs the filter step, that the head script needs a head to inject into, that a bot-classified visitor receives the state resolved for the request rather than an empty one, and that the client-fixed demo script declares and checks its required Data Use. The integration guide gains a section on what a module sees of the permission state, because it said nothing about it.

Author: jwrosewell

crates/trusted-server-core/src/integrations/registry.rs

@@ -964,9 +964,15 @@ fn resolve_device_provider(
     if let Some(provider) = resolved.as_ref()
         && provider.required_permissions() != crate::permissions::PermissionSet::none()
     {
+        let declared = provider
+            .required_permissions()
+            .iter()
+            .map(crate::permissions::Permission::as_str)
+            .collect::<Vec<_>>()
+            .join(", ");
         let message = format!(
-            "integration module `{}` declares a device provider with required permissions, \
-             and Trusted Server has no per-request gate that can enforce them yet, so the \
+            "integration module `{}` declares a device provider requiring `{declared}`, \
+             and Trusted Server has no per-request gate that can enforce that yet, so the \
              selection is refused rather than silently ignored",
             selector.unwrap_or_default(),
         );
@@ -3773,7 +3779,10 @@ mod tests {
             "the failure should name the module, got: {rendered}"
         );
         assert!(
-            rendered.contains("required permissions"),
+            rendered.contains(&format!(
+                "requiring `{}`",
+                crate::permissions::Permission::StoreOnDevice.as_str()
+            )),
             "the failure should say why it was refused, got: {rendered}"
         );
     }

crates/trusted-server-core/src/permissions.rs

@@ -5,8 +5,11 @@
 //! signals and the country it resolves to, and refuses to run the Edge Cookie
 //! provider when its required permissions are not set. The device and geo
 //! providers declare their requirements through the same method, and the
-//! built-in ones require none; gating their execution on that declaration is
-//! follow-up work.
+//! built-in and host ones require none. A device provider supplied by an
+//! integration module that declares any permission is refused at startup,
+//! because no per-request device gate exists yet to honor it. A geo
+//! declaration is not consulted, because geo runs before the permissions are
+//! assembled and supplies the country they depend on.
 //!
 //! The vocabulary is the IAB Privacy Taxonomy Data Uses, mapped from the IAB TCF
 //! Europe purposes and used **only** as a technical identifier for a permission.

docs/guide/integration-guide.md

@@ -317,6 +317,28 @@ The three delivery choices are exclusive and the last call wins, so a builder ch
 
 A module may declare a geo, identity or device provider that no selector chooses, which is a configuration a deployment can hold while it switches providers, so the registry logs a warning naming the unselected capability rather than refusing to start.
 
+### What a Module Sees of the Permission State
+
+Trusted Server resolves the permission state for a request once, at the start
+of the request cycle, and hands it to a module in two places rather than having
+the module derive its own.
+
+- A request filter receives `permissions: Option<&PermissionState>` on its
+  `RequestFilterInput`, next to the geo result. The filter step runs on the
+  Fastly adapter today, and there the state is built before any filter runs.
+- A page module reads `window.tsjs.permissions`, an object `{"set": [...]}` of
+  the Data Use names set for the request, and waits on `tsjs.whenPermissions()`
+  because the value arrives at `<head>` open under inline assembly and at the
+  `</body>` seam under a shared template. A module declares the permissions it
+  requires in its own source, the same names its server-side provider declares,
+  and does nothing with identity and contacts no vendor until the promise
+  resolves with those names in the set. The client-fixed demo script under
+  `integrations/ec_client_fixed` is the worked example.
+
+A device provider a module supplies must require no permission, because no
+per-request device gate exists yet; a module that declares one is refused at
+startup. See the permission model guide for the model itself.
+
 ### How an Adapter Composes It In
 
 The Axum, Cloudflare and Spin adapters take the builders as arguments, so no adapter names a vendor.

docs/guide/permission-model.md

@@ -47,12 +47,16 @@ vendor-neutral default needs no consent prompt and no per-request
 policy interaction.
 
 Device and geo providers declare their required permissions through the same
-method, and the core does not yet gate either of them on what they declare, so
-for those two the declaration is recorded rather than enforced. The only place
-a declaration currently decides whether a provider runs is the Edge Cookie
-path, in `ec/mod.rs`. Treat a device or geo declaration as a statement of
-intent until that gap is closed, and do not rely on it to keep a provider from
-running.
+method. The built-in and host providers require none. A device provider that
+an integration module supplies and that declares any permission is refused at
+startup, with a message naming the module and the permissions it declared,
+because device classification runs before the permission state for the request
+is assembled and there is no per-request gate that could honor the
+declaration. Refusing it is preferred to recording a requirement that never
+binds. A geo declaration is not consulted, because geo runs first and supplies
+the country the permission baseline depends on. The only declaration that
+decides whether a provider runs per request is the Edge Cookie provider's, in
+`ec/mod.rs`.
 
 ## Evidence is not rationed, use is
 
@@ -388,7 +392,9 @@ its own, so there is a single decision per request.
 **Server side.** An integration request filter receives
 `permissions: Option<&PermissionState>` on its `RequestFilterInput`, alongside
 the geo result it already receives, so a filter can skip or narrow what it does
-when a permission it depends on is unset. None of the shipped filters changes
+when a permission it depends on is unset. Request filters run on the Fastly
+adapter today, which is the only adapter that runs the filter step, and there
+the state is built before the filters run. None of the shipped filters changes
 its behavior on that input yet, so for now the state is carried and available
 rather than acted on.
 
@@ -409,22 +415,28 @@ the `permissions.yaml` keys and `Permission::as_str()`.
 Delivery follows the pattern already used for `adSlots` and `bids`, and the
 timing depends on how the page is assembled. Under inline assembly the value is
 injected as a `<script>` at the open of `<head>`, before the tsjs bundle, on
-every HTML document, so it is there before any page module runs. Under
+every HTML document that has a `<head>`, so it is there before any page module
+runs. Under
 shared-template (ESI) assembly the `<head>` is part of a template shared across
 visitors and must carry nothing request-scoped, so the value is spliced into the
 per-request script at the `</body>` seam instead. A permissions-only seam script
-is emitted even when the ad stack did not run, so a visitor whose consent was
-denied or who was classified as a bot still receives the state, empty in that
-case rather than missing.
+is emitted even when the ad stack did not run, so a visitor who was
+classified as a bot, or for whom the auction was gated off, still receives the
+state resolved for the request rather than nothing.
 
 Because the arrival point moves, a page module must not read `tsjs.permissions`
 directly at load. TSJS core defaults the value to `{ set: [] }` and exposes
 `tsjs.whenPermissions()`, a promise that resolves when the real value arrives,
 immediately in the head-first case or at the body seam, with a
 `DOMContentLoaded` fallback. That promise is the waiting point for a vendor page
 module, which does nothing with identity and contacts no vendor until the
-promise resolves. Wiring the existing integrations' JavaScript to wait on it is
-follow-up work.
+promise resolves. If nothing arrived by `DOMContentLoaded` the promise resolves
+with the empty state, which a module reads as nothing set. The client-fixed
+demo page script does exactly this. It declares the same Data Use its
+server-side provider requires, `necessary.operations.storage`, and posts to the
+resolve endpoint only when the promise resolves with that Data Use in the set,
+so it is the pattern a vendor page module follows. Wiring the other existing
+integration scripts to wait on the promise is follow-up work.
 
 The page cannot work this out for itself. Consent is only one of the ways a
 permission is set, and the country and region baselines and the deployer's