Add the integration provider seam design spec

[jwrosewell]

Why this PR exists

PRs #1043 to #1047 open the identity, device and geo seams. A vendor can
ship an Edge Cookie provider in its own crate and an adapter injects it,
with no core change.

The nine vendor integrations already inside trusted-server-core (APS,
DataDome, Didomi, Google Tag Manager, GPT, Lockr, Osano, Permutive,
Sourcepoint) do not sit behind those seams. They hang off the integration
registry, which is a private table in core, so none of them can move out
until that table is opened.

This PR adds the design spec for that one core change, so the migration
of every existing vendor is a single defined piece of work rather than a
question asked again for each vendor.

Spec:
docs/superpowers/specs/2026-08-27-integration-provider-seam-design.md

This PR adds one file, the spec, and no code. It targets main
directly so the diff is only that file. It reads alongside the series'
specs, which land with #1047.

What the spec says

Read against the tree at split/5-response-hook-docs, with file and line
references for every claim:

1. The registry is closed. IntegrationRegistry::new takes only
   &Settings and iterates a pub(crate) table
   (integrations/registry.rs:797, integrations/mod.rs:290). The
   payload type is already public, so an outside crate can build a
   registration but has nowhere to hand it.
2. Browser JavaScript is fixed at build time. js_module_ids serves
   a module only when trusted_server_js::module_bundle(id).is_some()
   (registry.rs:1169).
3. Startup validation names every vendor (config.rs:136 to :166).
4. Auction providers are a second closed table
   (auction/mod.rs:49).
5. Two vendors reach further into core, DataDome through the cache
   privacy and origin fetch decision (publisher.rs:4367 to :4387)
   and GPT diagnostics through direct calls in all four adapters.

The proposed change opens each of those in turn, keeps new's signature
so no existing caller changes behavior, and names no vendor in core. It
also generalizes the bid renderer contract (BidRenderer in
auction/types.rs:216 has one variant, Aps), so APS moves out whole.
The change is complete in itself: after it, no vendor move needs a core
change. It then sets out the migration of all nine integrations, one PR
each, with what each one needs.

Acceptance the spec sets for the implementation

• A round trip with an integration defined outside
  trusted-server-core, carrying its own JavaScript, registering
  through an adapter and appearing in the served bundle with the right
  hash. A seam is only proven by an implementation that is not the
  built-in one.
• Parity: the existing integration and parity suites pass unchanged.
• The deploy-validation guarantee survives in a vendor-neutral form.
• All CI gates in CLAUDE.md, on all four adapters.

Governance question this raises

The spec's §2 states a principle for the task force rather than for the
compiler: Tech Lab engineering owns core and reviews vendor crates, and
vendors ship and maintain their own integrations. That is the change that
removes the per-vendor core work the project pays for today, most
recently in #1054.

Declared interest

51Degrees is a vendor and would use this seam for its own integration
(#1072). The reasoning here applies to every vendor on the same terms,
ourselves included, and our own provider follows the same route.

Provenance

An AI assistant produced this spec under my direction, from a read of the
current code. I have reviewed it. It needs human review before the
implementation is written.

[aram356]

Summary

Thank you for this, and for §8 in particular. Publishing what implementing the seam actually found, including three items that say your own work is not finished, is the right instinct and it is what makes the design half of this trustworthy.

The design is accepted. §3.6's rule is correct, and it is the rule the work below implements. Things the host supplies are platform services. Things a vendor supplies are capabilities of that vendor's module. What is being changed is the order and the structure, not the direction.

Five changes to sequencing and structure follow. Tell me where the reasoning is wrong and I will change my view, but I want these settled before more code lands on the current shape. The two items that need wider sign-off are named at the end.

1. One crates/trusted-server-integrations crate first, with a discovering build.rs

Move all thirteen integrations into a single crate and generate the registration table at build time by scanning the crate's own directories, in the manner crates/trusted-server-js/build.rs already scans dist/tsjs-*.js.

This is the change that delivers the neutrality goal. Core stops naming vendors in builders(), in validate_enabled_integrations, and in migration_guards.rs, and it stops naming them because nobody writes the list, not because the list moved. Three of §1's four hardcoded vendor tables become generated output.

It also resolves several of §8's findings without further design:

• §8.2, the hand-carried module hash and its line-ending fragility, goes away because hashes are generated exactly as core's are today.
• §8.6, a module's validate running nowhere, is solvable in the generated table.
• §1.2, the compile-time JS map, is solved by one scan that finds Rust and TypeScript together.
• The migration_guards.rs drift is structurally impossible once generated. Worth noting that this drift is not hypothetical: osano is registered in builders() and has no entry in migration_guards.rs at all on main. Nobody noticed because both lists are hand-written.

prebid stays in core as protocol support, as §3.4 already says.

The runtime injection seam in §3.1 is not required for any of the thirteen integrations you have, because they are all compiled from source in this repository. It becomes the right mechanism when a genuinely external vendor crate exists, and it should be added then, with that vendor as its first consumer.

2. Crate layout follows from that

§4 proposes nine vendor crates, one PR each. We are not doing that now. One crate holds all thirteen integrations, and a vendor gets its own crate when that vendor takes over maintaining it, which none of them does today. Every integration on main imports the same roughly twelve crates, all of which core already depends on, so nothing about dependencies argues for splitting them either. Splitting later is a directory move against a module that already has clean boundaries.

Two consequences for what is in #1094 now:

• Directory name equals package name, as everywhere else in the repository. The crate is crates/trusted-server-integrations. crates/geo/fastly as package trusted-server-geo-fastly breaks that convention, and crates/geo/ is a category folder holding one item.
• Host code stays in its adapter. FastlyPlatformGeo is 52 lines that already live at crates/trusted-server-adapter-fastly/src/platform.rs:687, and the Fastly adapter is its only possible consumer. Extracting it into a crate gains nothing and contradicts §3.6's own rule that host-supplied things are platform services. The same applies to the 103-line Fastly device provider. crates/edgecookie/ contains only a README and should be deleted until a vendor crate lands. seam-probe is a test fixture and should not be a permanent workspace member.

3. Permissions policy belongs in trusted-server.toml; permissions.yaml should not exist

Policy belongs in a [permissions] section of trusted-server.toml, beside the existing [consent]. We should not add a second configuration format, and policy should not be compiled into the binary.

The permission-model spec's §3.1 gives the reason for YAML. The draft required policy to flow through the runtime config pipeline, and that activation apparatus does not exist. That conflates two things. ts config push does exist. It publishes trusted-server.toml as a blob envelope, and TrustedServerAppConfig already carries the entire Settings struct. What does not exist is the staged multi-revision activation protocol the draft designed, with fleet quiescence, admission leases, and a hash-linked journal. No other setting needs that machinery. The publisher domain, the proxy secret, the EC passphrase, and every integration config all push atomically today, and policy is not different in kind.

What the move gains:

• One place to configure everything. Today policy is the only control that bypasses ts config validate and ts config push, and it is the most compliance-sensitive one.
• The validation we already have, being deny_unknown_fields, Validate, and startup errors, instead of a bespoke parser reimplementing duplicate-key and case-collision checks.
• A publisher can correct a jurisdiction rule with a config push rather than rebuilding and redeploying a WebAssembly binary. For a compliance control that may have to change on a regulator's timeline, that difference is the point.
• §3.1's own recorded defect, that the include_str! path reaches above the crate root, disappears.

Alongside the move, please trim the fifty-three Data Uses that have no signal mapping and no enforcement point. Only two carry enforcement weight today. Moving fifty-three inert flags into trusted-server.toml would carry the misleading operator view across rather than fix it, and the spec already acknowledges this departs from its own rule that a permission appears only with both a mapping and an enforcement point.

4. The EC provider spec rebases onto 1 and 3

Rewritten against a seam that already exists and policy that lives in settings, the EC provider work is materially smaller than #1043 as it stands:

• No RuntimeServices::ec_provider slot to add and then delete, and no resolved_ec_provider second field. Note that #1094 currently has both, plus the registration path, so identity has three injection paths where §3.6 specifies one. §3.6's sentence that the ec_provider slot "goes" is not yet honored.
• No per-adapter resolution divergence. Related, and worth fixing wherever this lands: on #1094 resolve_geo_provider and resolve_device_provider return Result and fail loudly on a bad selector, while resolve_ec_provider returns a bare Option and falls back silently. §3.6 says an unresolvable selector is a startup error.
• No double configuration migration. This is the strongest reason for the reordering. As it stands, #1043 migrates operators from [ec] passphrase to [ec.providers.hmac], and §3.6 with sign-off row 8 then migrates them again to [integrations.<id>]. Two breaking configuration changes in one release cycle, the second withdrawing the first. Reordered, operators migrate once, into the final shape.

5. Some of this belongs in edgezero, not Trusted Server

edgezero-core already owns the platform layer, being app_config, blob_envelope, config_store, secret_store, key_value_store, store_registry, the router, the middleware, and the four adapters. Hooks::stores() returning StoresMetadata is already the seam run_app uses to inject store registries. Before we build more platform machinery in this repository, we should be explicit about which side of that line each piece sits on.

• The Fastly composition gap (§8 item 7) is probably an edgezero fix rather than a Trusted Server one. trusted-server-adapter-fastly wraps edgezero-adapter-fastly. If a deployment composes its modules through Hooks, the pattern already exists upstream and no Trusted Server adapter needs a new library target. Adding a [lib] here would work around the absence of something that may already exist one level down.
• RuntimeServices overlaps edgezero substantially. It carries a config store, a secret store, a KV store, an HTTP client, and a backend. edgezero-core models all five. Adding identity, device, and geo provider slots to it builds up a second platform abstraction beside edgezero's rather than using edgezero's.
• PlatformGeo has no edgezero counterpart. There is no geo abstraction in edgezero-core today. Either a geo lookup is a host capability edgezero should expose the way it exposes a KV store, or it stays here. Whichever it is, that should be a stated call rather than a default that follows from where the code happens to have been written.
• TrustedServerApp implements Hooks::name() and Hooks::routes() but not Hooks::stores() (crates/trusted-server-adapter-cloudflare/src/app.rs:332). The store-injection seam edgezero already provides is unused here, which is worth resolving before we design another one.

Which of these should move is a question for whoever owns edgezero. I would rather ask it now than build a second mechanism here and answer it afterwards. It also makes change 1 smaller: if composition runs through Hooks, the integrations crate needs less new machinery than either this spec or #1094 assumes.

Spec corrections, verified against the tree

• Five of the seven specs are statused "Implemented" for code that is not on main. EdgeCookieProvider, PermissionSet, and resolve_from_client are all absent from origin/main. Merging this set as written would tell every later reader that shipped behavior exists when it does not. Please status everything unmerged as "Proposed".
• §4, "thirteen vendor files" in migration_guards.rs, is wrong. There are eighteen vendor files across twenty integrations/ entries; nextjs alone contributes six. Thirteen is the count of builders. And as above, osano has no entry at all, which §4's migration plan depends on.
• §3.5, GPT diagnostics "called by name from all four adapters", undercounts. There are nine prepare_request call sites plus one finalize_response, so the hook work in §3.5 is larger than stated.
• §8.3, "a provider is resolved more than once per request", does not hold on main. No integration or proxy calls geo. A real double resolution does exist, but it is core against core: handle_auction at auction/endpoints.rs:262 and the adapter's build_ec_context both call lookup on POST /auction. The underlying gap, that there is no per-request provider context, is real and worth keeping.
• §8.5 understates the Spin gap. Spin does not merely skip inline admin stubs; it skips all six first-party route bindings (proxy, click, sign, proxy-rebuild), which carry real traffic. Cloudflare, by contrast, has no health route and so covers everything.
• Line references to correct: settings.rs:166 should be :215; auction/mod.rs:49 points at the function header rather than the list; publisher.rs:4361 should be :4369.

§8 item 7 is the load-bearing finding

Your assessment is right and the cause is more fundamental than the text states. The Fastly adapter has no [lib] section and no src/lib.rs, and every module is declared bare mod, so nothing in the crate is externally reachable. This is not a visibility modifier to widen; it is a missing library target. Axum, Cloudflare, and Spin each expose pub fn routes_with_settings and pub struct TrustedServerApp; Fastly exposes neither.

As things stand the seam is proven on the dev server and unreachable on the primary deployment target. §6's acceptance criteria should require the round trip on Fastly specifically, not on any adapter. Under change 1 this stops blocking the immediate work, since in-tree integrations compile in and nothing needs runtime injection. It must still be fixed before the first external vendor crate, and per change 5 the fix may belong in edgezero rather than here.

Disposition of the open pull requests

#1043 through #1047 and #1094 are superseded rather than rejected. The design in §3.6 is accepted, and most of the provider logic carries over onto the reordered base. Please do not read this as the work being discarded.

The order, with the first two independent and able to run in parallel:

1. One crates/trusted-server-integrations crate with a discovering build.rs, against main.
2. Permissions into trusted-server.toml, permissions.yaml deleted.
3. The EC provider work, rebased onto 1 and 2.
4. Device and geo selection, in the same shape.
5. Per-vendor crate extraction, if and when a vendor takes over maintaining one.

Happy to discuss who does what. The Fastly composition gap is core infrastructure rather than vendor contribution, and per change 5 it may not belong in this repository at all.

The jurisdiction default should not name a country

[geo] default_country is required in every mode, and it must resolve to a rule in the policy file. There are three groups today, being gdpr-eu, gdpr-uk, and us-opt-out, so a deployment with global traffic and no geo provider has to nominate one country and then apply that country's law to every visitor. That is the wrong shape. It makes a neutral product take a position on whose rules apply, and the operator's honest answer is usually "I do not know where this visitor is", not "treat everyone as French".

The default should be a policy baseline rather than a country. Two forms worth considering, and I do not mind which:

• A named group, so an operator selects gdpr-eu or a strictest-available baseline directly without claiming a location.
• A per-permission baseline written inline, for an operator who wants to state exactly what is allowed with no signal.

Either way the value says what is permitted, not where the visitor supposedly is. The requires-signal floor already exists for a failed lookup, so the machinery for a location-free baseline is there.

This also removes most of what I was going to send to the task force. The UK row shipping necessary.operations.storage: granted while the EU requires a signal, and Australia mapping to us-opt-out, are still policy positions that need someone with the relevant expertise to confirm with a citation, and the shipped table should carry that citation. But nobody has to ratify a default that no longer asserts a jurisdiction.

The crate layout, the configuration format, and the merge order are not task force questions. They are engineering calls and we should settle them here.

One further item to fix wherever the permission work lands: §7 of the permission-model spec records that publisher navigation and page-bids attach user.id under the provider gate rather than the sharing pair, so a storage-only grant can still place the EC identifier in user.id on those paths while /auction pair-gates it. That is an open inconsistency in the sharing boundary, and it should be closed rather than tracked.

[jwrosewell]

Thank you for this. It is a serious review and it moves the design forward. Taking your points in order.

1. One integrations crate with a discovering build.rs. Agreed as the destination. Generating the registration table removes a whole class of drift rather than one instance of it, and the hand-enumerated shape it replaces is the existing Trusted Server convention our PRs followed rather than introduced. It is out of scope for these PRs and the current specification though, so we suggest iterating toward it rather than blocking on it. The halfway house to move to now is the one that most helps code review, being vendors actually separated, with a hard build failure when a vendor change reaches into core. Reviewers then get a clean line between vendor changes and core changes today, and the generated registration lands as its own later step. The runtime injection seam is already built in #1094, so nothing there needs to wait for an external vendor.

2. Crate layout. Here we differ. Whether a vendor wrote the code, or the Tech Lab team wrote it for them, should not decide whether it gets its own crate. Separating per vendor now makes ownership legible, and a crate boundary is enforced by the compiler, while a CODEOWNERS entry only assigns review ownership and constrains nothing about what code can reach. The maintainer can be the Tech Lab team today. If the Tech Lab team built the Permutive integration, the Permutive crate is theirs until Permutive take it over, and the handover then changes one line, not the structure. We take the point that host code stays in its adapter, which §3.6 already says, and we will follow the repository's crate-naming convention. The disagreement is only on timing.

3. Permissions. This one is fundamental for us and not something we can change 🙂. Deleting the dedicated permissions file breaks a deployment model that is very hard to change later.

The transparency point first. A single, dedicated permissions policy that anyone can open and read is how Trusted Server shows exactly what a publisher permits, on its own rather than buried beside proxy secrets and backend hosts.

Then the mechanism. Trusted Server should not decide policy for the deployer, and there should be no automatic default. Selecting the policy is a conscious choice when an environment is set up for the first time. The entity that compiles a deployment provides the policy it wants as part of the build, which is why the policy has to be a build-time artifact and not only a runtime config section, and that same entity can expose configuration override so the operator of the compiled variant can adjust it without rebuilding. Consider a provider in Europe that compiles Trusted Server with a European base and ships it to its customers, who get an interface to tune it. Two actors and two moments, with the integrator setting the base at build time and the operator adjusting it at runtime. A single runtime config section cannot express that, and neither can a compiled-only policy, so both layers are required. The repository should also carry multiple policy files for different test scenarios, because exercising the permission model across scenarios is part of the robustness of the service.

Three things follow. Policy is not locked in the binary forever. The compiled base is the layer these PRs implement, and the operator override is the follow-on the permission-model spec already records as deferred, so a jurisdiction rule can change on a regulator's timeline without a rebuild. What the shipped jurisdiction rules should say, the UK storage row and the country baselines included, is a policy question for the group to confirm with citations, which is your point in the jurisdiction section too, and we would take it there rather than settle it in code review. And which file carries the compiled-in base and which one arrives through configuration at runtime is not something engineers need to debate. That choice sits with the people deploying, and testing proves every mutation of base and override works.

4. The EC provider and one injection path. Agreed. §3.6 specifies one identity injection path and we will honor it, collapsing to the single registration path. An unresolvable selector will fail loudly, while an absent selector keeps today's behavior of running with no Edge Cookie provider. Rebased onto a seam that already exists, the double configuration migration also goes, so operators migrate once.

5. What belongs where. The distinction that matters is which repository these live in. The geo provider, the device provider and the Edge Cookie provider are part of Trusted Server, not EdgeZero. EdgeZero supplies the host plumbing, and the provider capabilities are Trusted Server's domain, which is where a vendor goes to plug in. They are also deliberately off by default. Only User-Agent device detection runs by default, geo resolves no location until a provider is configured, and the Edge Cookie provider is selected by configuration, which is the same conscious-choice principle as point 3. Vendor code already lives in Trusted Server as the registered integrations, and the provider seam exists so a vendor can be added the same way. We are asking to use it for the purpose it was built. Where you are right is the platform plumbing rather than the providers. The config, secret and KV stores that RuntimeServices carries are things the host already models, and we should route those through the existing store seam rather than a second abstraction beside it.

Spec corrections. Taken, and thank you for checking against the tree.

• Statuses. Some specs are marked Implemented for code that is not yet on main. We marked them Implemented because the code is in the PRs, which was the wrong signal, and we will restatus everything unmerged as Proposed.
• Counts. These were taken from the builder registrations rather than a file count, which undercounts the real files and call sites. We will correct them against the tree.
• The osano entry missing from the migration-guard hand-list is real, and exactly the drift that change 1 removes structurally. There will be more of these as we iterate, which is the argument for generating the list.
• The Fastly composition point and §6's acceptance criteria. Agreed the round trip should be proven on the primary target, not only the dev server, and we will come back with the specifics.

On merging. We agree with most of this and will make the changes. The differences are narrow, being per-vendor separation now rather than later and keeping a dedicated permissions file. Rather than treat the current PRs as superseded and reset, could we agree a concrete sequence and owners for landing this so the provider work merges soon? We would like to keep this a direct back and forth to a merge. Thanks again for the depth of the review.

[ChristianPavilonis]

Summary

Requesting changes for three security or authorization failures and three contract gaps in the normative design. These findings are distinct from the existing feedback on sequencing, implementation status, Fastly composition, policy placement, and jurisdiction defaults.

Reviewed 180060402f91b4efa96f5823da8934d19c1c78f8 against d516a9e94249e10cbc36e41beb4269f9255cf407.

[ChristianPavilonis]

🔧 P1: Do not authorize every publisher subdomain to set identity

Authorizing every origin below publisher.domain recreates the identity-fixation path for a delegated, user-controlled, or compromised sibling subdomain. Such a page passes this suffix check and can issue the simple credentialed POST described in the threat model, while the EC cookie is scoped to .publisher.domain. Control of the DNS namespace does not imply that every subdomain is a trusted identity-setting origin. Please use an explicit serialized-origin allowlist and match scheme, normalized host, and effective port exactly. Add rejection cases for a sibling subdomain, the wrong scheme, and the wrong port.

[ChristianPavilonis]

🔧 P1: Enforce or reject device-provider permission declarations

DeviceProvider::required_permissions is public but deliberately has no enforcement point, while the integration seam exposes DeviceProvider as an external vendor capability with request evidence and a possible shared backend. An external provider can therefore declare that its use requires permission and still run on every request. Operator selection is not a per-request consent decision. Please enforce the declaration before invoking a device provider, or reject nonempty device requirements until that gate exists. If the built-in classifier must run without advertising permissions, split that security role into a separate, narrowly scoped authority with restricted evidence and no general vendor egress.

[ChristianPavilonis]

🔧 P1: Duplicate request headers must not disable DataDome

Two instances of any admitted singleton header, including user-agent, origin, or authorization, currently skip the entire DataDome call through the fail-open path. Header multiplicity is attacker-controlled, and this spec requires adapters to preserve repeated field lines, so a bot can deliberately add a duplicate and receive the publisher response without validation. Please reject ambiguous security-singleton requests at the HTTP boundary, or omit an optional ambiguous field while still calling DataDome. Do not convert multiplicity into a protection bypass. Add duplicate-header cases to every adapter's qualification suite.

[ChristianPavilonis]

🔧 P2: Define the browser permission-gating mechanism

This requires the vendor module to check the server's resolved permissions before vendor contact, but the design does not say how those permissions reach TSJS or combine with a fresh CMP check. Integration modules are self-executing IIFEs selected by provider configuration, while the endpoint gate runs only after the module may already have derived identity or contacted its vendor. A CMP signal alone also cannot reproduce the server's jurisdiction policy. Please define the browser-side authorization mechanism before the first vendor module lands, require module initialization to be side-effect free until that check passes, and add a browser test proving the vendor endpoint receives no request when permission is absent or withdrawn, including after BFCache restoration.

[ChristianPavilonis]

🔧 P2: Bind the resolve marker to the selected provider

ts-ecr=1 records only that some client-cycle provider resolved in the past. On a switch from provider A to provider B, A's coded EC becomes unrecognized, but this marker remains until withdrawal or its one-year expiry. B's page script therefore sees the marker and never calls resolve, even though the migration contract says the switch restarts identity. Please bind the marker to the selected provider code and behavior revision, or expire it whenever the incoming EC is not recognized by the selected provider. Add an A-to-B client-provider switch test.

[ChristianPavilonis]

🔧 P2: Add a browser renderer registration seam before moving APS

Generalizing Rust's BidRenderer is not enough to move APS out whole. TSJS core still imports parseApsRendererDescriptor from APS in core/auction.ts, imports APS dispatch in core/request.ts, and fixes AuctionBidRenderer to ApsRendererV1 in core/types.ts. Because build-all.mjs builds core/index.ts as a self-contained IIFE, those static imports remain in tsjs-core.js independently of carried integration modules. Please specify a browser renderer registry keyed by descriptor type. Integration modules should register their parser and dispatcher, core should reject unknown types safely, and a cross-language test should prove APS can be removed without changing or breaking the core bundle.

[jwrosewell]

Thanks. Great review and I've checked the points. All six hold up. Five are changing in this stack, and one is real but is new design work that these PRs are not the place for. In order.

P1, subdomain identity fixation. Agreed, and it is worse than you say. The check in ec/resolve.rs is a suffix match on publisher.domain, and it also accepts an http:// origin and discards the port before comparing, so all three of your rejection cases pass today. The Edge Cookie really is Domain=.publisher.domain, from ec_cookie_domain() in settings.rs, so an identity authorized from a sibling subdomain does land on the apex. The justification I put in the spec, that the sibling concern belongs to Sec-Fetch-Site and not to a suffix match on the apex, does not hold, because the two admit the same set of origins. I've withdrawn that sentence.

The fix is the same-origin test of RFC 6454, so the request Origin and each allowed origin are compared as the scheme, host and port triple of §4 under the §5 rule, with a missing port meaning the scheme's default, and a value that is not a serialized origin under §6.1 never matches. Your three rejection cases are tests. One refinement on the default. A strict allowlist would mean the endpoint does nothing until an operator configures it, so the default is the single exact origin https://{publisher.domain} and nothing else, with an optional configured list adding further exact origins for a publisher whose pages are served from www or another domain. That also closes the open question I had left at §7.5, so the two are one piece of work.

One more point on severity. The origin check is defense in depth here, not the primary control. The primary control is the provider's envelope verification with audience and session binding, which §3.9 parks out of v1. An exact allowlist does not help against a subdomain that legitimately serves publisher pages and is later compromised, so §3.9 still has to land with the vendor scheme.

P1, device provider permissions. Agreed. DeviceProvider::required_permissions has no production reader anywhere, and the only place detect is called runs before permissions are assembled at all. Before the module seam that was a documented no-op, because core and the host supplied the only two providers. With the seam a vendor crate can implement the trait, so the method now reads as a promise that is not kept.

I've taken your second option. A nonempty required_permissions from a module-supplied device provider is rejected at registry resolution and fails loudly at startup, rather than being silently ignored. That closes the false assurance now. Enforcing the declaration properly, which is where this has to end up, needs a per-request device gate that does not exist yet, so I'd rather refuse the declaration than pretend to honor it.

P1, duplicate headers and DataDome. Agreed on the risk, and I've changed the approach rather than patched the rule. One correction on the framing first. Nothing skips the call today because a header arrived twice. protection.rs reads each mapped field through a single headers().get() in header_value and goes on to call the Protection API however many lines arrived, and the only skips it has are its own rules, being the test bypass, the OPTIONS preflight and the configured exclusions. The clause in my spec would have created the duplicate-header bypass rather than described one, so this is caught before it ships rather than found in running code. Good catch.

I haven't taken either remedy exactly, because both still have core deciding what to do with a vendor's evidence. Core should not invent header normalization for a vendor, and it certainly should not decide to skip a vendor call. Core passes the request headers through as received, repeated field lines preserved, and the vendor integration decides how to interpret multiplicity, because that is the vendor's detection logic and not core's business. The one field I am leaving out of that is content-length, which is HTTP framing handled by the host HTTP layer beneath Trusted Server and which no integration reads as a value, so there is no vendor decision in it.

The wider point, and it is the same separation argument running through this whole review. The DataDome logic sits in core today. Vendor detection logic of that kind belongs in the vendor's own module, behind the seam, not in the shared engine. Getting it there is the direction, and this rule is a small example of why.

P2, the ts-ecr marker. Agreed. Read-back, the identity-graph key and withdrawal are all bound to the provider code envelope. The marker is the one identity-adjacent artifact left unnamespaced, a bare ts-ecr=1 that only withdrawal expires, so after a switch a visitor sits with no identity rather than a restarted one. The provider-switching section of the pluggable-providers spec lists read-back, the browser cookie and the graph rows and never mentions the marker, so that is a hole in my text as much as in the code.

I've taken your second remedy rather than your first. Core expires the marker on any request carrying a ts-ec that the selected provider does not own. Binding the value to the provider code would work only if every vendor's page script compares the value correctly, and the demo script we would be handing vendors as the pattern does not compare it at all, so making correctness depend on each vendor's copy of that check is the weaker half. Expiring it in core does not depend on anyone's page script.

P2, browser permission gating. Agreed, the mechanism was undefined. It is defined and delivered now, in the permissions PR (#1045). There are two deliveries. On the server, integration request filters receive the permission state resolved for the request, next to the geo result they already get, on the Fastly adapter, which is the only adapter that runs the filter step today. On the page, that same state arrives as window.tsjs.permissions, an object {"set": [...]} naming the Data Uses set for the request. Under inline assembly it goes in as a script at the open of <head>, before the bundle. Under a shared template the head is shared across visitors and cannot carry anything request-scoped, so the value is spliced into the per-request </body> seam script instead, and a permissions-only seam script is emitted even when the ad stack did not run, so a bot-classified visitor, or one for whom the auction was gated off, still gets the state resolved for the request rather than nothing.

Because the arrival point moves, core exposes tsjs.whenPermissions(), a promise that resolves when the value arrives, or with the empty state at DOMContentLoaded if nothing arrived, which a module reads as nothing set. That gives you side-effect free until the check passes. A page module waits on it and does nothing with identity and contacts no vendor before it resolves. You are also right that a CMP signal cannot reproduce the server's jurisdiction policy, which is precisely why permissions rather than consent are the primitive here. The server's resolved decision is the authority and an in-page CMP read is a withdrawal re-check layered under it, never a substitute.

A page module is treated the same way as any other provider. It declares the permissions it requires and checks them against the state it is handed before it does anything. The client-fixed demo script does exactly that now, declaring necessary.operations.storage (the same Data Use its server-side provider requires, held in step by a test) and posting only when the promise resolves with it in the set. The page itself renders with that state passed to everything running on it, so what ran and why is visible to anyone looking, which is the point of the trust in the name. Your browser test, meaning no vendor request when a required permission is unset or withdrawn, including after BFCache restoration, is a test of a module's declaration, so it gets written with the first module that declares one.

P2, the browser renderer seam. You are right, and it is out of scope for this stack. core/auction.ts imports parseApsRendererDescriptor from the APS integration, core/request.ts imports the APS dispatch, and core/types.ts fixes AuctionBidRenderer to ApsRendererV1. Two things to add, and both help your case. There is no integrations/aps/index.ts at all, so APS is not a discovered browser module in the first place, and that code is pre-existing on main and byte identical on this branch, so no PR in this stack introduces or changes it.

I've corrected the §4 APS migration row so it names the browser-side work as well as the Rust side, and added the coupling as a §8 finding. Designing the browser renderer registry belongs with the APS migration, not here, and I have filed it as #1111 so it is not lost in this thread.

On scope. This stack is not adding new designs or features. It implements the seam that was agreed, and where it overclaims I've corrected the text rather than widened the specs to cover work these PRs will not deliver. The browser renderer registry is genuinely new design work. It is a good agenda item for the next meeting and I'd rather settle it there than in a review thread.

Five changes are in the stack now, being the exact origin check with its rejection tests, the device permission rejection, the marker expiry, the DataDome pass-through rule, and the page and filter carriage of the resolved permissions. The other one is a spec correction that says plainly what is not yet designed.

[aram356]

Permissions policy should use the existing typed app-config path

Requesting changes on the permissions.yaml decision.

The argument for a dedicated YAML file does not establish a technical guarantee. YAML is editable before a build, and include_str! only records a snapshot in that binary. It does not prove who selected the policy, that the repository file matches the deployed binary, or that a later build or deployment preserves it. If an immutable distributor floor is required, that needs an explicit trust model—such as signed build provenance, an exposed policy digest, and a merge rule under which runtime configuration can only tighten the floor. The file format itself does not provide that.

The current design also does not yet deliver the two-layer model described in the discussion: permissions.yaml is compiled in, while runtime overrides are deferred. As written, operational policy changes require rebuilding and redeploying, and the most compliance-sensitive configuration bypasses ts config validate, ts config diff, and ts config push.

We already have an appropriate configuration path:

• Add permissions: PermissionsConfig to Settings, beside consent.
• Serialize and deserialize it through TrustedServerAppConfig.
• Validate group references, permission identifiers, acquisition values, normalized location keys, and provider enforcement coverage in validate_settings_for_deploy.
• Publish it in the existing BlobEnvelope with ts config push.
• Construct PermissionMaps from settings.permissions once at startup.

The TOML can represent the same concepts: a location-independent default_group, named groups or baselines, country/region-to-group rules, and consent-signal mappings. A default_group also avoids pretending that a visitor with unknown geography belongs to a made-up default_country.

Please revise the spec so the effective operational policy lives under [permissions] in trusted-server.toml and participates in the existing typed configuration lifecycle. If a compiled distributor floor is still required, specify it as a separate optional layer and define exactly:

1. Who is trusted to choose it.
2. How a deployed binary proves which floor it contains.
3. Whether runtime configuration may only tighten it—for example, granted < requires_signal < denied.
4. How the effective merged policy and its digest are exposed for audit.

Without those guarantees, a separate compiled YAML file adds a second configuration system and a rebuild requirement without delivering the immutability or auditability used to justify it.

[aram356]

Vendor-owned crates should be an extension path, not the default migration

This is blocking because §4 makes separate vendor crates the required structure for integrations that are currently maintained together in this repository. I agree with the goal of allowing vendors to own their integrations independently. I do not agree that we should create those ownership boundaries before the owners and independent lifecycles actually exist.

A crate boundary should represent a real maintenance boundary: an independent owner, release process, dependency or licensing requirements, security-response responsibility, and compatibility commitments. The current integrations are reviewed under the same project governance, released with Trusted Server, and use largely the same dependencies. Moving each one into its own crate does not make it vendor-maintained. Unless a vendor has explicitly accepted those responsibilities, the Trusted Server team still owns the integration—only now it also owns another manifest, release surface, CI path, dependency-update stream, and compatibility obligation.

Separate Rust crates provide compile-time package boundaries. They do not by themselves provide runtime isolation, independent deployment, or the ability to add an integration without rebuilding Trusted Server. If all of these crates remain workspace dependencies compiled into the same binary, most deployment characteristics remain unchanged while repository and release complexity increase.

The current integrations should instead live as vendor modules in one crate:

crates/trusted-server-integrations/
  src/
    vendor_a/
    vendor_b/
    vendor_c/

That crate can still provide the intended provider interface, generated registration, and shared conformance tests. The interface should also allow an independently maintained external crate to implement the same contract. A vendor contribution can therefore start as a module in the shared crate or as a genuinely external implementation, depending on who owns its lifecycle.

An integration should be extracted into its own crate when at least one concrete boundary exists, for example:

1. The vendor commits to owning releases, compatibility testing, and security fixes.
2. The integration has materially different dependency or licensing requirements.
3. It needs an independent release cadence.
4. A real external integration demonstrates that the provider seam requires the separation.

Whether Trusted Server supports independently maintained vendor integrations is a product and governance decision. Whether every existing integration needs a separate crate is an engineering packaging decision, and the current ownership and release model does not justify it.

Please revise the spec to use one trusted-server-integrations crate for the integrations maintained here, with vendor-specific crates supported as an optional extraction path when real owners and lifecycle boundaries emerge. This preserves the vendor-owned extension model without creating a separate package for every hypothetical future owner.

[aram356]

Blocking: define and sequence the EdgeZero boundary before adding another platform layer

This is blocking. §3.6 states the right high-level rule—host-supplied capabilities are platform services—but the design does not carry that rule through to repository ownership or implementation sequence. Trusted Server already runs on EdgeZero. If we add the missing host-service and composition machinery here first, we create a second platform abstraction that every adapter and future integration must understand.

The overlap is concrete on current main:

• edgezero-core owns Hooks, RequestContext, app configuration, BlobEnvelope, config/secret/KV store registries, proxying, routing, and middleware.
• Hooks::stores() is already the portable declaration that EdgeZero adapter runners use to provision and inject stores.
• RequestContext already exposes named and default config, secret, and KV handles.
• Each EdgeZero adapter already owns extraction of its native request context.
• Trusted Server's RuntimeServices separately carries config store, secret store, KV store, HTTP client, backend, geo lookup, and client information.

That leaves the boundary ambiguous: some platform services flow through EdgeZero, while others are rebuilt and selected in Trusted Server. The provider seam should not make that duplication permanent.

What belongs in EdgeZero

1. Portable host-service access. Config, secret, and KV handles must continue to flow through EdgeZero's store registries and RequestContext. Generic outbound HTTP/proxy access and platform transport/backend capabilities should also have one EdgeZero-owned contract. Trusted Server may use thin type adapters where its error or data types differ, but it should not own a second service registry or a second adapter-selection mechanism for the same host resources.

2. Normalized host evidence. Client IP, TLS protocol/cipher, JA4/HTTP2 evidence, and host-provided geographic data are facts extracted by the deployment adapter. The portable evidence types and capability-presence metadata belong in edgezero-core; the Fastly, Cloudflare, Spin, and Axum implementations belong in their EdgeZero adapters. Trusted Server should consume normalized evidence rather than reaching into platform SDKs or inventing a separate cross-adapter host context.

3. Generic adapter lifecycle/composition hooks. If loading an application-supplied module requires a new startup, request-extension, or composition hook, the generic hook belongs in edgezero_core::app::Hooks and must be honored by all four EdgeZero adapter runners. Fastly cannot have a separate composition rule. The payload carried through that hook can be Trusted Server-specific, but the adapter lifecycle mechanism cannot be.

4. Host capability discovery. EdgeZero should expose which optional host capabilities are available so an application can fail startup when a selected provider requires unavailable evidence or transport. The provider requirement remains a Trusted Server concept; the authoritative statement of what the current adapter supplies belongs to EdgeZero.

What remains in Trusted Server

• IntegrationRegistration, vendor JavaScript, prepare/finalize hooks, auction providers, configuration selection, and conformance tests.
• EdgeCookieProvider, GeoProvider, and DeviceProvider behavior, including vendor calls, selection, per-request sharing, and permission enforcement.
• HMAC identity, the User-Agent classifier, and other Tech Lab-owned implementations.
• Permission and jurisdiction policy.
• Auction telemetry and other ad-tech-specific request/response behavior.

The important distinction is that a host geo lookup belongs in EdgeZero, while a vendor geo provider that interprets or augments geo data belongs behind the Trusted Server integration seam. Likewise, raw TLS/JA4/H2 evidence belongs in EdgeZero, while device classification based on that evidence remains Trusted Server behavior. Identity remains a Trusted Server provider, while the KV and secret-store plumbing it consumes remains EdgeZero infrastructure.

Required changes to this spec

Please make the dependency direction and sequencing normative:

1. Define the missing portable host-evidence, transport, capability-discovery, and lifecycle/composition contracts in EdgeZero.
2. Land and version those EdgeZero changes first.
3. Upgrade Trusted Server to that EdgeZero version and consume the contracts through Hooks and RequestContext.
4. Make TrustedServerApp declare its stores through Hooks::stores() instead of leaving the existing EdgeZero injection seam unused.
5. Keep RuntimeServices, if it remains, as a Trusted Server request/provider context over EdgeZero handles and normalized evidence—not as an independently owned platform layer.
6. Require the external-registration round trip on Fastly, Axum, Cloudflare, and Spin through the same lifecycle contract. Any Trusted Server-specific library entry point can remain here, but it must not compensate for a missing generic EdgeZero adapter hook.

Until those prerequisites and ownership lines are recorded, §3.6 permits two competing platform seams and leaves each implementation PR to decide ad hoc what belongs upstream. That is exactly the architectural drift this design is supposed to prevent.

[jwrosewell]

For reviewers of this spec: the permission model it governs can now be seen working rather than read about. The inspector at https://jwrosewell.github.io/trusted-server/tools/permissions-inspector/ runs trusted-server-core compiled to WebAssembly against the repository's sample policy and shows which Data Uses are set for any visitor location and consent signals, with the reason per Data Use, the taxonomy definition behind each one, and the engine's version, branch and commit stated on the page. It ships in #1045 at tools/permissions-inspector, and the hosting above is temporary from my fork until the repository hosts its own.