Add a pluggable Edge Cookie provider seam with the built-in HMAC provider

[jwrosewell]

This pull request is the first of six stacked pull requests and the only one with no parent, so it depends on nothing beyond main and can merge on its own. The stack is #1043, #1044, #1045, #1046, #1047 and #1094, each targeting main and each branch building on the one before. The first five decompose #838 as requested in the #986 review, and #1094 opens the integration seam on top of them. A later pull request's own change shows when its head branch is compared with the previous pull request's head branch.

The design specs for the series are carried by #1084. The spec for this pull request is 2026-07-30-pluggable-providers-design.md, which covers both this pull request (the Edge Cookie seam) and #1044 (device and geo selection). The spec is revised to match this implementation, with a revision record listing every divergence from the earlier draft and why.

What this pull request does

Edge Cookie identity generation becomes a selectable provider behind the EdgeCookieProvider trait in crates/trusted-server-core/src/ec/provider.rs, with the existing HMAC implementation as the built-in and configuration selecting it.

• [ec] provider names a block under [ec.providers.<key>]. Leaving [ec] provider out means stateless operation with no Edge Cookie, and provider = "none" spells the same choice explicitly (rejected if provider blocks are left configured). A selected provider with no block, an unreferenced stray block, and an unknown key in a block all fail at startup, so a misconfiguration is loud.
• The deprecated [ec] passphrase form still starts. It migrates to provider = "hmac" plus [ec.providers.hmac] with a deprecation warning, so a fleet can move configuration and binaries independently. Both forms together are rejected. In either form the passphrase names a secret-store key, as [ec] passphrase does on main, and the resolved value is held to the same 32-byte minimum.
• Identifier bounds are global and provider-independent, with at most 256 bytes and the alphabet [A-Za-z0-9._~-], enforced at creation, cookie read-back and cookie write. A violating identifier is rejected outright and never rewritten, so the cookie value and the identity-graph key can never silently diverge (the previous sanitize-by-stripping path is removed).
• Read-back goes through the selected provider's accepts_id, and the identity-graph key through its normalize_id_for_kv canonical form, so an opaque vendor identifier round-trips byte for byte. One test proves a non-default provider round-trips verbatim and another proves the graph is keyed by the canonical form.
• Vendor [ec.providers.<key>] blocks are captured as raw values in core and deserialized by the adapter that injects the vendor provider, so core never names a vendor.
• Every provider carries a mandatory registered four-character code, allocated in provider-code-registry.md, the registry the spec set defines. Core creates {code}~value, checks the code at read-back, and keys the identity graph with it, so identifiers from different providers can never collide and switching providers cannot silently adopt another provider's identities. The built-in provider creates hmac~<hash>.<suffix> and still reads its earlier bare form so deployed cookies keep working, and ec/provider.rs documents when that reader can be retired.
• Every path that reads or writes the identity graph keys the row by the owning provider's canonical form. Pull sync, batch sync and the admin lookup accept an identifier through AcceptedProviders, which applies the global bounds and then asks the provider that owns the identifier's code, so a code no configured provider owns is refused. Identify, EC finalization, pull sync, batch sync, the admin lookup, /auction, the publisher navigation preload and /_ts/page-bids all use the canonical key, so a provider whose canonical form differs from its cookie value still reaches the row it created. The admin lookup reports the key it read as kv_key. is_valid_ec_id stays the built-in HMAC grammar, accepting the hmac~ envelope and the legacy bare form.
• A provider may set its own cookies and headers on the response. Core refuses any effect inside its own surface, being a Set-Cookie for a ts- cookie, any x-ts- header, and the framing, hop-by-hop and cache-control headers. A refused effect makes generation return an error, and the page is served without an Edge Cookie. Headers are kept only from a provider response whose identifier generation commits, or that produced no identifier, and finalization appends them rather than replacing the origin's.
• Core no longer requires a client IP before calling a provider. It passes the empty string when the host has none, and each provider decides whether it needs one. The built-in HMAC provider refuses to create an identifier without one.
• Generation failures log at error level, not warn.

How it was verified

Every job main's CI runs was run locally against this head, 1b88e42f7, on Windows and under WSL, and all of them passed. That covers cargo fmt --all --check, Clippy with warnings denied on the Axum, Cloudflare, Spin and Fastly adapters and on both wasm targets, the Axum, Cloudflare and Spin adapter suites, the cross-adapter parity suite, the benchmark smoke run, the release wasm builds for Spin and Fastly, and the CLI, OpenRTB codegen, format-docs and template cache harness jobs that only run on Linux. The core suite passes with 2,747 tests natively and 2,741 under Viceroy, where 6 are ignored.

CI on this head is green across all 19 checks, being Run Tests, Run Format, Integration Tests and CodeQL Advanced. The integration run needed a re-run because prepare integration artifacts first failed downloading wasm-opt from GitHub releases, which skipped the three integration jobs behind it. Thank you to whoever pressed it.

Framing

Privacy is a spectrum, and this change is neutral infrastructure. It does not decide whether identity is created. It makes that decision configurable and inspectable, and the deployer selects a provider (or none) according to the laws and policies that apply to them. Trust comes from that flexibility being respected and visible in configuration rather than hard-coded.

References #777. Decomposes #838 (kept as a draft reference until this series merges). Spec baseline from #986.

[aram356]

Summary

This PR lands the Edge Cookie provider seam with the built-in HMAC provider, per the pluggable-providers design spec carried in the same change. The lifecycle contract (mint, recognition, KV keying), the global identifier bounds, startup validation, the deprecated-passphrase migration, and the partner-path envelope fix are substantially implemented, with strong test coverage, and CI is fully green.

The major blocker is architectural: vendor extensibility should lean on the existing integration system rather than introduce a parallel "provider" mechanism. The codebase has one established home for vendor code (the integration registry), and this PR adds a second seam, a second config namespace, and a second nomenclature for what a vendor ships. We want that resolved at spec level before PRs 2-5 of the series build on the current shape - see the first cross-cutting finding below.

Beyond that, changes are requested on: a reproduced bypass of the advertised 32-byte passphrase minimum on the deprecated configuration form, two points where the implementation does not do what the spec states (unknown-key rejection in the hmac block; canonical-key routing on identity-graph reads and withdrawals), and an egress guarantee the proxy paths do not honor.

4 of the inline comments below carry a one-click GitHub suggestion. Use Commit suggestion (or Add suggestion to batch) to apply them as commits on the PR branch. The remaining comments describe the fix in prose because the change spans multiple files or non-contiguous lines and cannot be auto-applied.

Blocking

🔧 wrench

• Vendor identity should lean on the integration system, not a second extension mechanism - the major blocker; cross-cutting, below
• Legacy [ec] passphrase bypasses the new 32-byte minimum - see inline at crates/trusted-server-core/src/settings.rs:658 (suggestion)
• [ec.providers.hmac] silently accepts unknown keys - see inline at crates/trusted-server-core/src/settings.rs:726 (suggestion)
• Identity-graph reads and withdrawal tombstones bypass the provider's canonical key - cross-cutting, below

❓ question

• Spec says an unrecognized cookie value is "never used or egressed", but the proxy forwarding paths egress it - cross-cutting, below

Non-blocking

♻️ refactor / 🤔 thinking / ⛏ nitpick / 📌 out of scope

• ♻️ build_provider silently returns Ok(None) for provider = "hmac" with no block - see inline at crates/trusted-server-core/src/ec/provider.rs:304 (suggestion)
• ⛏ 22-space run inside the mint-rejection error message - see inline at crates/trusted-server-core/src/ec/mod.rs:444 (suggestion)
• ♻️ EdgeCookieProvider's doc comment is fused into ProviderCode's, leaving the trait undocumented - see inline at crates/trusted-server-core/src/ec/provider.rs:177
• ⛏ ec::get_ec_id is dead code, yet was modified to accept any provider code - see inline at crates/trusted-server-core/src/ec/mod.rs:137
• ⛏ Module docs describe constructor injection that is not how RequestInfo flows - see inline at crates/trusted-server-core/src/ec/provider.rs:4
• 🤔 Cluster prefix listing splits across the envelope migration - cross-cutting, below
• ♻️ Magic strings "hmac" / "none" scattered across four call sites - cross-cutting, below
• 🤔 RequestInfo accessors have no production consumer in this PR - cross-cutting, below
• 🤔 Spec revision followed the implementation - cross-cutting, below
• 📌 Operator guides still document [ec] passphrase as the current form - cross-cutting, below

Cross-cutting / body-level findings

• 🔧 Vendor identity should lean on the integration system, not a second extension mechanism (the major blocker). The codebase already has one home for vendor code: the integration registry (IntegrationRegistration::builder(ID).with_proxy().with_head_injector()...), capability-based and config-namespaced under [integrations.<id>]. This PR adds a second vendor seam - RuntimeServices::ec_provider, a single-slot Option<Arc<dyn EdgeCookieProvider>> matched by id(), configured under [ec.providers.<key>] - and a second nomenclature ("providers"). RuntimeServices is otherwise the platform composition surface (KV store, geo, HTTP client, client info: things the host supplies); a vendor identity module is not a host capability, and a vendor realistically ships a JS integration and an identity function together, which this split forces into two mechanisms. Please rework the vendor seam onto the integration system: identity provision as a registration capability (for example .with_ec_provider(...)), with [ec] provider = "<integration id>" still supplying the select-exactly-one semantics; the built-in HMAC provider can stay hard-wired in core as the default, and geo/device rightly remain platform services. If there is a reason this cannot work, the spec should defend the separate provider mechanism against this alternative explicitly - and we want that settled at spec level before PRs 2-5 of the series build on the current shape.

• 🔧 Identity-graph reads and withdrawal tombstones bypass the provider's canonical key. The spec's lifecycle table (section 3) routes identity-graph row reads and writes through normalize_id_for_kv. Mint honors that: EcContext::generate_with_provider keys the row with provider_kv_key (ec/mod.rs:476). But handle_identify reads with the raw cookie value (kv.get(ec_id), ec/identify.rs:89), withdrawal tombstones are written under the raw value (ec/finalize.rs, the write_withdrawal_tombstone loop), and EID ingestion keys by the raw value. For the built-in HMAC provider raw and canonical coincide, so nothing misbehaves today; for the first provider whose canonical form differs from the cookie value (exactly the CanonicalizingProvider case this PR's own test proves at mint), identify misses the row written at mint, and a withdrawal tombstone lands on a key no live row uses, so the revocation never takes effect. Proposed fix: compute the canonical key once in EcContext (for example an ec_kv_key() accessor derived from the selected provider) and use it in identify, the finalize tombstones, and EID ingestion - or amend the spec to state that reads and withdrawals become canonical-form-routed only when the first canonicalizing provider ships, and track that as a follow-up.

• ❓ Spec says an unrecognized cookie value is "never used or egressed", but the proxy forwarding paths egress it. Section 3's Recognize row states that a value the selected provider does not recognize "is never used or egressed." append_ec_id (proxy.rs:1263) and handle_first_party_click (proxy.rs:1609) forward the raw ts-ec cookie / x-ts-ec header value to origin and click-target URLs through edge_cookie::get_ec_id, which checks only the character/length allowlist - so a foreign-coded value (zz00~...), or any cookie in a stateless (no-provider) deployment, is egressed on those paths. The looseness predates this PR, but the PR introduces the spec claim. Which should change - the spec (scope the guarantee to the EC lifecycle paths and note the proxy forwarding exception) or the code (route those call sites through provider ownership)?

• 🤔 Cluster prefix listing splits across the envelope migration. Section 3 says the pre-epic IP-cluster prefix listing "continues unchanged." Fresh mints are now keyed hmac~<hash>.<suffix>, so evaluate_cluster's prefix (ec_hash, ec/kv.rs:715) becomes hmac~<hash> for coded rows while legacy rows still list under the bare <hash>. Two rows for the same client IP that straddle the envelope migration therefore never count each other, and cluster_size (a NAT/fraud signal in identify responses) undercounts while both populations coexist. Worth a sentence in the spec, and possibly a follow-up to bridge the count during the migration window.

• ♻️ Magic strings "hmac" / "none" are scattered across four call sites (Ec::validate_provider_selection, build_provider, provider_owns_id's provider.id() == "hmac", and HMAC_PROVIDER_CODE in ec/generation.rs). A typed selector, for example enum EcProviderSelection { None, Hmac, Vendor(String) } with a custom deserializer (vendor keys are open-ended, so a catch-all variant is needed), would centralize the vocabulary before #1044 adds more built-ins. Non-blocking: the string form works and is startup-validated.

• 🤔 RequestInfo accessors have no production consumer in this PR. path(), query(), query_param(), header_names(), user_agent(), and header() are supplied by production code but consumed only by tests in this PR (the HMAC provider reads only client_ip()). The spec's own minimalism rule (section 4) requires a production caller in the same change that introduces a method; the consumers arrive later in the stack. For a stacked series this can be acceptable, but the spec should say which PR consumes each accessor, or the accessors should land with their consumers.

• 🤔 Spec revision followed the implementation. The spec is commendably candid that it is the 2026-07-31 draft "revised against the implementation" with a revision-record table, and that table is genuinely useful. The process consequence is worth naming, though: when the normative spec is restated to match landed code, divergences become ratifications rather than decisions, and questions like the extension-model one above surface at review time instead of design time. For the remaining PRs in the series, it would serve the spec-first intent better to land spec changes ahead of the implementing PR and let review happen against the spec before the code exists.

• 📌 Operator guides still document [ec] passphrase as the current form. docs/guide/configuration.md:1933, docs/guide/key-rotation.md:31, docs/guide/error-reference.md:72, plus ec-setup-guide.md / edge-cookies.md / fastly.md predate the provider layout, the deprecation, and the new stateless default in trusted-server.example.toml. A docs pass is needed in this series; a follow-up PR is fine.

CI Status

• cargo fmt: PASS (required)
• cargo test: PASS (required)
• format-docs: PASS (required)
• format-typescript: PASS (required)
• cargo test (axum native): PASS
• cargo test (cloudflare native + wasm32-unknown-unknown check/build): PASS
• cargo check/build/test (spin native + wasm32-wasip1): PASS
• cargo test (cross-adapter parity): PASS
• cargo test (ts CLI, native): PASS
• cargo check (cloudflare native + wasm32-unknown-unknown): PASS
• vitest: PASS
• Analyze (rust): PASS
• Analyze (javascript-typescript): PASS
• Analyze (actions): PASS
• CodeQL: PASS
• prepare integration artifacts: PASS
• integration tests: PASS
• integration tests (Fastly EC lifecycle): PASS
• browser integration tests: PASS

[ChristianPavilonis]

Reviewed the pluggable Edge Cookie provider changes at 0f5c063214ba1d46478311851f08fe9b10c2ccf8. I am requesting changes based on the inline findings. This review includes one P1, three P2s, and one non-blocking migration clarification. cargo test-fastly and all 18 GitHub checks passed at the reviewed head; these findings concern runtime and provider-contract behavior rather than test failures.

[jwrosewell]

This response was drafted with AI assistance and checked against the branches before posting.

Thank you both. Twenty observations across the two reviews. Seventeen are answered in code on this branch and three are answered in the pull request of the chain where the answer belongs, named in the Addressed elsewhere table. Each fix is separately committed, so any one can be confirmed without reading a combined diff. Two further rows in the Addressed table are not yours, being things we found while answering and fixed in the same pass.

A note on scope. Some of your observations reach past this PR into the ones before and after it, which is unavoidable because the work was split into a chain. Answering only within #1043 would be more confusing, not less, so this comment answers for the whole chain and says where each answer lives. #1043 is simply the PR the review happened on. Each commit's message ends with an Addresses: line naming the file, line and label it answers, so the mapping below is verifiable from the branch itself rather than only from this table.

The branch is rebased onto d516a9e94 and merges cleanly. Every commit was tested before the next was written, and the gate set passes on the final head of the chain, being cargo fmt, all six clippy targets, test-fastly, test-axum, test-cloudflare, test-spin, and the 62 host-target CLI tests.

We also run the core library suite natively, at 2,463 tests, and #1047 adds that run to test.yml. This matters for reading any red build, not only ours. The WebAssembly targets build with panic=abort, so their harness stops at the first failing test and reports every later one as never run, hiding them until the first is fixed. The native run reports them all at once, at the cost of one extra compilation of a crate the job already builds.

One CI note, and a small ask. CodeQL flags "Cleartext logging of sensitive information" on #1044 to #1047 and #1094. It is a false positive and we would ask you to dismiss it, since the alerts belong to this repository and we cannot. The passphrase it traces is held in a Redacted type whose Debug and Display both print [REDACTED], and the value only ever feeds the HMAC, never a log. The flagged lines log the jurisdiction and redacted identifiers, nothing sensitive. CodeQL taints the whole Edge Cookie context because it now holds the provider that carries the redacted passphrase, so it marks every log of a context field. Nothing in cleartext reaches a log.

Where each piece is, and what changed between the PRs

Two things moved since Aram's review on 27 August that are not visible from this PR alone.

The seam that the architectural finding asks this work to lean on now
exists, as a sixth body of work. #1084 is still design and no code, and it has grown since we raised it. It now carries all seven design documents, 3,925 lines across seven files, rather than the single seam spec it started as. We moved the other six out of the code PRs and into it deliberately, because a spec sitting in the same PR as a later piece of code describes behavior that does not arrive until two or three PRs further on. Merging #1084 first puts every design document in place before any code that implements one lands. Implementing the seam is a separate PR we will raise, at 34 commits and 81 files, proven end to end by a test integration that lives outside trusted-server-core and is registered through a real adapter. Keeping it out of #1043 is deliberate, so this PR stays reviewable against the finding it answers.

These are one block, and the order below is the order they should merge in. Splitting them is what creates the legacy this work exists to stop, because each one on its own leaves the core carrying a shape the next one removes. The last item is the point of the whole exercise, an unmerged vendor change landing without adding to the core, so no further legacy is added rather than removed later.

#	PR	What it is	Own change
1	#1084	the design set, no code. It now carries all seven specs, not the one it was raised with, because we moved them out of the code PRs. Mergeable today	7 files
2	#1043, this one	pluggable Edge Cookie identity, plus 20 commits responding to both reviews	44 files
3	#1044	device and geo provider selection, and the host-signal provider	32 files
4	#1045	the permission model, whose vocabulary is the IAB Privacy Taxonomy Data Uses, mapped from the IAB TCF Europe purposes where no Data Use exists yet	46 files
5	#1046	the browser-set Edge Cookie path	13 files
6	#1047	the documentation set	16 files
7	#1094	the implementation of #1084, which makes the seam real rather than specified	81 files
8	#1054 reworked, to follow	#1054, the managed LiveRamp RampID integration, reworked onto the seam. As it stands it adds 511 lines to integrations/prebid.rs inside core. On the seam a vendor module registers from its own crate, so the same feature can land with those 511 lines outside core instead. Same feature, same author, no larger core. We will do that rework and raise it	to follow

Rowena asked on 27 August whether #1044 must follow #1043, or whether #1045 could follow #1043 instead. The answer is that #1045 cannot move ahead of #1044, and here is the reason rather than the assertion.

The permission model needs a jurisdiction baseline, which is the country whose rules apply when the geo lookup returns nothing. That baseline lives on the [geo] configuration, and [geo] does not exist until #1044 creates it. #1045 adds default_country and assume_single_jurisdiction to that structure, and references the device provider trait as well. Applied to a tree without #1044 it has nothing to attach to.

The rest of the order is the same kind of dependency rather than preference. #1046 is the browser-set path for an identity #1043 defines, and #1047 documents behavior the four before it introduce, so documenting it earlier would describe code that is not there. If a different order would help you, tell us what you need and we will say honestly whether it can be done, because we would rather rework the split than have the whole thing wait on the shape we happened to choose.

Items 2 to 7 are one ordered chain, not six branches beside each other. #1043 is against main at d516a9e94 and each of the rest sits on the one above it, so none of them can merge out of order and none needs a merge commit to get in. #1084 is the exception and deliberately so, because it is seven specification files and the chain touches none of them, so it conflicts with nothing and can go in first on its own. Each of the seven passes the full gate set on its own, so none is green only because the branch above it fixes something.

The order we suggest is #1084 first, since it settles the design question and costs nothing, then #1043 to #1047 in sequence, then the implementation of #1084. That implementation is where identity, geo and device all become capabilities a registration declares, which is the architectural finding answered rather than deferred. It lands there and not here because a registration can only carry an Edge Cookie provider once that trait exists, and #1043 is what adds it, so the seam PR is the first point in the chain where both exist together. We would rather do it once, against a seam that exists, than rewrite five reviewed PRs onto a seam that did not exist when the review was written.

Addressed

Feedback	How it is addressed	Commit
Christian, P1, ec/provider.rs:317: portability adapters swallow unavailable-provider errors, so the request continues with no identity	Axum, Cloudflare and Spin now return an error response instead of an empty context, matching Fastly. All four also now check at startup that the adapter can actually supply the provider the operator selected, so a deployment that names a provider its host cannot build fails when the application starts rather than on every request. A deployment that selects no provider at all is unaffected and still serves normally.	f0ca12a (8 files)
Aram 🔧, settings.rs:658: legacy [ec] passphrase bypasses the 32-byte minimum	Validation moved inside the migration, so every construction path is covered. Your suggested wording used verbatim.	b2bb944 (settings.rs)
Aram 🔧, settings.rs:726: [ec.providers.hmac] accepts unknown keys	deny_unknown_fields added, with a test that a typo inside the block fails startup.	472218b (settings.rs)
Aram 🔧, ec/identify.rs, ec/finalize.rs: identity-graph reads and withdrawal tombstones bypass the provider's canonical key	One derivation on EcContext, used by identify, the withdrawal tombstones and EID ingestion. Three tests, one per path, using a provider whose canonical form differs from the cookie value.	343ac3e (ec/identify.rs, ec/finalize.rs, ec/mod.rs)
Aram ❓, proxy.rs:1263, :1609: the spec says an unrecognized value is never egressed, but the proxy paths egress it	The code changed, not the spec. Those paths now forward only a value the selected provider recognizes. Changes behavior, see Behavior changes below.	8684c69 (proxy.rs, edge_cookie.rs, testlight.rs)
Aram ♻️, ec/provider.rs:304: build_provider returns Ok(None) for hmac with no block	Selecting hmac with no [ec.providers.hmac] block now returns an error naming the missing block, rather than quietly building no provider and running with no identity. Configuration validation already rejects that pair, so the test reaches the seam by constructing the settings directly.	c4d2f1d (ec/provider.rs)
Aram ⛏, ec/mod.rs:444: 22-space run in the message rejecting an out-of-bounds identifier	Line continuation restored. Every other string literal in the file checked for the same fault, and this was the only one.	93cd1e8 (ec/mod.rs)
Aram ♻️, ec/provider.rs:177: the trait's doc is fused into ProviderCode's and is stale	Paragraph moved onto the trait, the Ok(None) sentence corrected to the id: None semantics, ProviderCode left with its own text.	a265c96 (ec/provider.rs)
Aram ⛏, ec/mod.rs:137: ec::get_ec_id is dead yet was loosened to accept any provider code	Deleted. No caller anywhere in the workspace, and publish = false means nothing outside can depend on it.	004581c (ec/mod.rs)
Aram ⛏, ec/provider.rs:4: module docs describe constructor injection that is not how evidence flows	Both module docs rewritten to match the trait signature. Verified nothing passes evidence by constructor.	d6041f0 (ec/provider.rs, evidence.rs)
Aram ♻️, magic strings "hmac" and "none" across four call sites	Typed EcProviderSelection { None, Named(String) }. Every provider now resolves by name through one path, including the built-in HMAC one, so a provider that happens to live in core gets no special case and no shortcut the vendor crates do not have. The configuration surface is unchanged and each form has a round-trip test.	885e3ce then b146aeb (4 files)
Aram 🤔, ec/kv.rs:715: cluster prefix listing splits across the envelope migration	Accepted rather than bridged, and now documented with the bound and the reason. Every consumer of cluster_size was checked, and it gates nothing, being reported in identify responses only.	20bb082 (ec/kv.rs, spec)
Aram 🤔, evidence.rs: accessors with no production consumer	Not done, and we think the observation is right about the rule and wrong about this interface. All the evidence is retained. The short reason is that an evidence interface describes what a request carries, not what today's code reads, and what a provider may see was never the control. What it may do with what it sees is, and that is the permission model. Full reasoning under How providers see the request. We have amended our own specification rather than leave it contradicting the code.	6cc3c91
Christian, P2, ec/finalize.rs:57: provider response effects can overwrite core-managed state	Core reserves its own surface, being the ts- cookie prefix, the x-ts- header prefix, and framing and hop-by-hop headers. A violation fails the request. A provider's own cookies still pass. Cookie names read as bytes, so a non-UTF-8 value cannot smuggle a reserved name through.	69649aa (ec/finalize.rs, ec/provider.rs, ec/mod.rs)
Christian, P2, ec/generation.rs:207: partner paths reject the next provider's identifiers	Global cookie bounds split from provider-specific validation, and both validation and KV normalization now dispatch by provider code. Non-HMAC identifiers covered in pull sync, batch sync and admin lookup tests.	53d632e (7 files)
Christian, P2, ec/mod.rs:376: generic generation requires a client IP before calling the provider	Requirement moved into HmacProvider, the only provider that reads it. A provider deriving identity from other evidence now creates an identifier on a host with no client IP.	941297f (ec/mod.rs, ec/provider.rs)
Christian, non-blocking, ec/provider.rs:145: define when the bare HMAC reader can be removed	Condition written from the real constants rather than estimates, being one year, being the longer of the cookie lifetime and the graph row TTL, measured from the last write that refreshes a bare-form row, which for a returning visitor carrying a ts-eids or sharedId cookie is later than the last release that could create one, plus rollout skew. The comment also says plainly that the observable half cannot be checked, because nothing counts a bare-form read. The one-release wording is gone.	e317190 (ec/provider.rs, ec/cookies.rs, registry doc)
Found while answering the above, the collapsed line continuation was not unique to ec/mod.rs	The same fault is in four more messages on this branch, at ec/admin.rs:373, ec/finalize.rs:125, ec/provider.rs:635 and ec/pull_sync.rs:72, plus integrations/testlight.rs:196. Two of the five are operator-visible. All are restored, and the crate was scanned for the same fault, so the claim now covers this crate rather than one file.	ada4d79 (5 files)
Found while answering the above, two item docs still described constructor injection	The earlier pass rewrote the module docs but left IdentityInput and EdgeCookieProvider::generate saying evidence arrives through injected services, which contradicted the row above it. Both now name the request_info parameter the evidence actually arrives on.	4cf202f (ec/provider.rs)

Addressed elsewhere in the chain

Each is answered in the PR of the chain where the answer belongs rather than in this one.

Feedback	How it is addressed	Where, with the commits
Aram 🔧, the major blocker: vendor identity should lean on the integration system rather than a second extension mechanism	Done, in the seam PR. A registration now declares an Edge Cookie provider and a device provider exactly as it declares a geo provider, the registry resolves each against its selector, and the adapters apply all three in one place. There is no second mechanism for identity to sit on any more. That PR also makes the three provider interfaces asynchronous and hands a provider the platform services, because until now every provider method was synchronous while every platform service was asynchronous and a provider was handed none of them, so a provider that needed to call a backend, read a store or fetch a secret could not be written at all. The traits keep their Send + Sync bound and use #[async_trait(?Send)], which is the pattern PlatformHttpClient already uses in this codebase, so the provider stays safe to share while the future stays on one thread. No provider keeps a synchronous method, including the built-in ones, and two tests drive a provider that reads a value out of the config store it is handed, so the services parameter is exercised rather than merely present. Two tests select the probe module for identity and for device and assert the resolved provider is the module's own, so its id() is seam_probe and not core's HMAC. A full generate round trip that drives the probe's provider and asserts the cookie value it produces is added in the seam PR. It could not be done on #1043 itself, because a registration can only carry an Edge Cookie provider once EdgeCookieProvider exists, and that is what #1043 adds. The seam PR is the first point in the chain where the trait and the registry exist together, which is why it lands there and why the chain has to merge in order.	The seam PR, #1094. 50fffbd carries identity and device on the registration and adds the two tests, and bedd495 completes it.
Aram 🤔: the spec revision followed the implementation, so divergences become ratifications	Taken, and the practice is changed rather than defended. #838 was opened on 2 July, before much of what is now in core, so that sequence was always going to be awkward and we are not going to pretend otherwise. What we did next is the answer, because the #1084 seam spec was written on 27 August and its implementation began on 28 August, so the design was fixed before the code existed. What implementing it then taught us is published in that spec as section 8, "What implementing this found", as its own section rather than folded quietly into the body. A reader can see what changed and why, which is the thing a ratification hides. Avoiding a repeat of it is also the practical reason this stack needs to merge now. The longer the code sits unmerged while main moves, the more the specifications describe something the tree no longer matches, and the only ways out of that are to rewrite the specs to fit what happened, which is the ratification Aram objected to, or to rewrite the code. Merging the chain in order ends that pressure rather than managing it.	#1084. 8b0f9c0 wrote the seam spec on 27 August, before any of its code existed, and 9b5b328 added section 8 recording what implementing it then found.
Aram 📌: operator guides still document [ec] passphrase as the current form	Done. The provider documentation set is #1047, the last PR of the chain, which is where the operator guides are rewritten for the new form. Putting it on #1043 would mean documenting four PRs' worth of behavior in the first of them, so a reader of #1043's guides would be reading about code that is not there yet.	#1047. e82366c adds the provider documentation set, and 5df37ef corrects it against the code.

Behavior changes

Four, each called out deliberately rather than left to be found. Every one of them is necessary rather than incidental, and every one moves in the direction this project has already chosen, which is a core that is neutral between vendors and does nothing on a deployment's behalf that the deployment did not ask for. The last is the one an operator will feel most, so it is worth reading even if the rest are skimmed.

Change	Before	After	Why we think it is right
A stateless deployment no longer egresses the Edge Cookie value	[ec] provider unset. A browser sends Cookie: ts-ec=abc123. Trusted Server forwards that value to the origin, to click targets, and testlight posts it as user.id.	Nothing is forwarded on any of those three paths. Testlight, which requires an identifier, fails rather than proxying.	Aram's ❓ asked which should change, the spec or the code. The pluggable-providers spec, Recognize row, says a value the selected provider does not recognize "is never used or egressed". We changed the code so that sentence is true, rather than weakening the sentence.
A short deprecated passphrase now fails startup	[ec] passphrase = "short", five bytes. It migrates into the new provider block, the application starts, and identifiers are created from a five-byte secret.	Startup fails. The operator sees [ec] passphrase (deprecated) is invalid: use a random secret of at least 32 bytes, placed in [ec.providers.hmac], so the message says both what is wrong and where the secret now belongs.	Aram's 🔧 at settings.rs:658, using his suggested wording verbatim. This PR already advertised a 32-byte minimum. The check simply never ran on the deprecated form, so the advertisement was false.
A provider cannot write into core's own response surface	A provider returns Set-Cookie: ts-ec=…, or an x-ts-… header. It is written to the response, bypassing core's identifier validation and its identity-graph write.	The request fails with Provider \acme` returned a response header `set-cookie` that sets a cookie in the `ts-` namespace Trusted Server manages, so the log names the provider, the header and the reason. A provider setting its own cookie, for example acme-evidence`, still passes through untouched.	Christian's P2 at finalize.rs:57 offered two remedies, validating the effects or a typed response API. We took the first, which is the smaller change and the one that keeps a provider able to set its own cookies, as he asked.
Host geolocation becomes opt-in, where it was always on	On main there is no [geo] section at all, and the Fastly adapter builds FastlyPlatformGeo unconditionally, so every deployment resolves location.	With the chain merged, [geo] default_country is required, so a config that lacks a [geo] section fails at startup with a message naming the missing key. Once the operator adds it, location resolves only if they also set provider = "platform" for the host lookup, or name a module that supplies one. Unset and "none" both resolve nothing and make no host geo call.	A deployment should not be sending client IPs to a host geo service because nobody turned it off. Making it opt-in means a default deployment is tied to no geo vendor, which is the same neutrality argument as the rest of this work. It fails loudly rather than quietly, because default_country is required, so an operator cannot upgrade without meeting the [geo] section and deciding. We would rather state this here than have a deployment discover its targeting changed.

How providers see the request

Applying the minimalism rule to the evidence interface was the wrong call, and we are reversing it. Here is the design we are implementing instead, so the reasoning is on the record rather than arriving as a surprise in a later PR.

A provider is given everything the request carries. The client IP, the User
Agent, every header, the path, the query and its parameters, the form parameters and their values, and the host signals a host can supply. Not a subset chosen by what today's callers happen to read. An interface that grows one method each time a vendor arrives is not something a vendor can write against, and it cannot be stable across a release, which is the thing a vendor needs most. 51Degrees will use all of them, to the extent a request's permissions allow.

Restricting what a provider can see is the wrong lever. The right one is
permissions, and it is two layers deep:

1. A provider advertises the permissions it requires. Core does not run it at
   all when those permissions are not available for the request. A provider that needs an identifier it may not store never executes.
2. The provider is given the resolved permissions and decides what it may use of
   what it can see.

That guards against a badly behaved provider twice over, without the interface deciding in advance what a vendor is allowed to look at.

A permission describes what, not how, and that is the whole reason this boundary is the right one. A permission names a data use, being storage on the device, or personalized marketing. It never names a technology. There is no permission saying the User-Agent header may be read, or that a cookie may be used but local storage may not. Data protection works the same way round, because it governs the purpose data is put to rather than the mechanism used to achieve it.

So restricting what a provider sees regulates the how, not the what. A provider blocked from one header can often reach the same purpose another way, and one allowed to see a header still may not use it for a purpose nobody granted. What stops the purpose is not running the provider at all, which is the first layer above.

Drawing the boundary on the purpose rather than the mechanism also buys something we would like to build on. Every provider already declares the permissions its data use requires, so a build can be asked what it will do before it serves a single request. The core can emit a manifest for a given deployment listing every permission every module in it requires, derived from the modules themselves rather than from someone's notes. That is a machine-readable statement of what a deployment does with data, which is most of the work of writing a privacy notice, and it can be generated and kept current rather than maintained by hand and quietly going stale 🙂

And the claim can be checked, which is what makes it useful. A provider declaring the permissions its data use requires is, on its own, only a claim. What turns a claim into something a publisher can rely on is that the code is open, so anyone can read what a module actually does and hold it against what the module said it would do. That is a large part of what the word trusted in Trusted Server has to mean, because a trust nobody can verify is only a reputation.

Checking used to be expensive enough that almost nobody did it. That has changed. An AI agent can read a module, read its declared permissions and report the difference in minutes, for very little, and can do it again on every release rather than once at onboarding. So a false declaration, or a module quietly doing more than it declared, moves from something findable in principle to something that will be found in practice.

The consequence should follow the finding, and it should be plain. A vendor whose modules repeatedly do not do what they say should not have modules in this project, and should not remain a member of the organization that publishes it. Simple. That is the enforcement this model needs behind it, and it is available only because the code is open and the declarations are machine-readable.

The caller is us, and it is the next step rather than part of this stack. We will use all of it, to the extent permissions allow, across the geo, device and Edge Cookie providers. We are deliberately not raising that pull request alongside these, because this stack is already a large change and a vendor module on top would make it harder to review.

What that work needs is specific rather than speculative. The evidence interface #1043 carries already exposes the client IP, the User-Agent, headers read by name, header enumeration so a module sends a complete evidence set rather than working from an allowlist compiled into it, the path, and the query and its parameters, and it is whole on #1043 as of 6cc3c91. The one addition the later work brings is a form_param accessor, because evidence conventions of this kind populate their query keys from POST bodies as well as from the query string.

So the evidence interface is whole on #1043 as of 6cc3c91, and form_param follows with the vendor work that reads a form value, alongside the code that calls it.

We will prove the evidence actually arrives. A loopback provider that
consumes every piece of evidence and returns it, used in tests, so a change that quietly stops delivering some part of the request fails rather than passing silently. That is also the beginning of the conformance suite below.

Two notes on sequencing. The advertise-and-gate half needs required_permissions on the provider trait, which the pluggable-providers spec places with the permission model, so it lands in #1045 rather than here. And form values are not reachable by a provider today, because neither the request info nor the identity input carries the body, so we are adding that lazily, meaning the body is parsed only if a provider actually asks for a form value, so a deployment whose provider never reads one pays nothing.

The gap this leaves, which we would like to fill

There is no conformance suite a provider can be run through. Core defends
itself against a provider in multiple places, being identifier bounds and alphabet, the reserved response surface, canonical key handling, behavior when evidence it needs is absent. Each is tested where it happens. None of it is expressed as a suite any implementation can be run through to show it behaves, so a vendor writing a provider cannot check their own work, and core cannot show a new provider is well behaved except by someone remembering to look. The loopback provider described above is the first piece of it, and it does not exist yet either. We think the rest belongs with the module seam rather than with this PR, and we are willing to write it. It is not filed as an issue, because the code it would test is the code these pull requests propose rather than anything on main.

Found in main while doing this, raised as issues

Eight observations about code that exists on main today, which neither review raised. Each is filed as its own issue.

We found more than these eight, but the rest are in the code these pull requests propose rather than in the code the core team has. Those are not issues, because an issue is a statement about the accepted codebase and this code is not accepted yet. They are either fixed in the pull request that introduces them or written up in that pull request as a known design question, which is where they belong.

Fixed in this stack.

• Edge Cookie identifiers leave the edge without an ownership check on the proxy and testlight paths #1096: the live edge_cookie::get_ec_id, used on the proxy replay and click paths and by testlight, accepted any well-formed value with no ownership check, so an identifier this deployment never issued was read back and egressed. This is the same trap Aram flagged on the dead ec::get_ec_id, but on a production path. Fixed in the egress commit above, and the issue is filed so the fix is traceable and closes when this merges.

• The Edge Cookie response header list is a second hand-maintained copy of the internal header list #1099: EC_RESPONSE_HEADERS in ec/finalize.rs is a second hand-maintained copy of the first entries of INTERNAL_HEADERS, with nothing keeping the two in step, so a header added to one and not the other is silently forwarded or silently stripped. The list now lives once and the internal list is assembled from it at compile time, with a test that fails if they drift.

• The Spin adapter cannot build application state, so it answers every request except the health probe with 503 #1101: the Spin adapter compiles the shipped example configuration into the binary, whose admin password is a placeholder that configuration validation rejects unconditionally, so build_state never succeeds and every request is answered with 503. No test caught it because every Spin test supplies its own settings through routes_with_settings, so the one path a deployed component takes is the one path never exercised. Settings now load from the platform config store at run time, as they do on the other three adapters.

• Inbound Edge Cookie identifiers are checked with the outbound backstop, so another deployment's identifier is accepted #1095: inbound Edge Cookie identifiers are checked only against the outbound character backstop, so a correctly shaped identifier issued by a different deployment is accepted and read back. The backstop's own doc comment says the strict path is the one for untrusted request values. x-ts-ec is also absent from the spoofable-header list, so the header is the client's to set and is preferred over the cookie. Now dispatched to the provider that owns the identifier, which is the only layer that can judge a vendor identifier it did not create.

• On Cloudflare no region is resolved, so every US privacy signal fails open #1102: the Cloudflare adapter resolves no region, so jurisdiction detection never reaches its US branch and falls through to non-regulated, where an Edge Cookie is created outright. Global Privacy Control, the GPP US sale opt-out and the US Privacy string are all consulted only on the branch that is never reached, so all three signals failed open rather than only the first. The region now comes from cf-region-code, which carries the subdivision code the privacy-state list is written in, rather than cf-region, which carries the name and would have matched nothing.

Not fixed here, reported for the core team.

• Two Edge Cookie cluster settings are parsed and documented as controls but nothing reads them #1097: cluster_trust_threshold and cluster_recheck_secs are parsed, defaulted, and documented as controlling identity resolution, and read by nothing. That unimplemented claim is what would lead a reader to believe cluster_size is a control rather than a signal.

• The non-UTF-8 cookie error in the Edge Cookie path cannot be reached on any adapter #1098: the non-UTF-8 cookie error arm is unreachable on all four adapters, because the GPT diagnostics preparer rewrites the cookie header before Edge Cookie state is built, so a malformed cookie is dropped silently rather than reported.

• Record a maintainer for every vendor integration, from the vendor #1100: no integration records a maintainer, and all nine vendor integrations were written by this project rather than by the vendor whose product they integrate. Someone reading the repository cannot tell whether a vendor stands behind the code carrying its name, which is misleading even though nobody intended it. It also suggests mirroring the mechanism Prebid already uses.

What we are asking for

These eight pull requests, merged in this order, before other changes land on main. Six exist today and two are ours to raise:

1. Add the integration provider seam design spec #1084, the design set. No code, conflicts with nothing, mergeable today.
2. Add a pluggable Edge Cookie provider seam with the built-in HMAC provider #1043, this one.
3. Add device and geo provider selection with the host-signal Edge Cookie provider #1044, device and geo provider selection.
4. Add the permission model with the Privacy Taxonomy vocabulary #1045, the permission model. Its vocabulary is not ours. It is the IAB Privacy Taxonomy Data Uses, with the IAB TCF Europe purposes mapped onto them where no Data Use exists yet, so the permissions a provider declares are stated in the industry's own terms rather than in a vocabulary we made up. Aligning the permission model this way followed a suggestion from Rowena.
5. Add the client-set Edge Cookie value path #1046, the client-set Edge Cookie path.
6. Add the provider documentation set and finish the decomposition #1047, the documentation set.
7. The implementation of Add the integration provider seam design spec #1084, which we will raise. This is where identity, geo and device all become registration capabilities, so the second extension mechanism goes away rather than being documented.
8. Add managed LiveRamp RampID integration #1054 reworked onto the seam, which we will raise. Someone else's vendor work, landing without enlarging the core, which is the whole point of the exercise.

Items 2 to 7 are one chain and cannot merge out of order. Item 1 is independent and can go first on its own. Item 8 needs the chain merged before it means anything.

This is the direction the Task Force agreed on 27 August, which is a neutral core with vendor-specific work in modules the vendors themselves own and maintain. These PRs are that direction in code. #1084 and its implementation are what make it possible for any vendor, not only us, and we have written that part at our own cost and contributed it.

The request to merge these first is practical rather than procedural, and the reason is Arena.

There is one deployment, and Arena is running on proof-of-concept code. It needs to be on an MVP and then a Release 1, and this stack is most of what moves it there. Every change that lands before this one is written against the proof-of-concept shape and has to be moved afterwards, and moving is far cheaper while there is one deployment than after there are more.

There is also a smaller running cost while the stack waits. Main took three commits on 28 August alone, and each one means rebasing seven branches. One of those rebases produced a merge that git resolved cleanly but that failed to compile, so the work is not mechanical.

Where this puts the project. The Task Force agreed the direction on 27 August, being a neutral core with vendor work in modules the vendors themselves own and maintain. Merged in the next few days, this stack delivers that at the start of September, as something done rather than something still being debated. That matters with the New York session at the end of the month, because it is the difference between presenting a direction and presenting a working answer, and it means the obvious awkward question, which is whether any of this is real yet, has already been answered.

It also gives Trusted Server capabilities nothing else in this space has, and they are worth saying out loud rather than leaving buried in a diff.

The change	What it gives a publisher
A core that is neutral between vendors	No vendor's code sits inside the core everyone depends on, so no vendor's interests are built into it
Vendor modules owned and maintained by the vendor, with a maintainer recorded	You can see who stands behind the code carrying a vendor's name, and hold them to it
Permissions expressed as what data is used for, not which technology is allowed	The rule survives the next technology, because it never named one. It is also the way data protection law is written
A permissions manifest for a build	A deployment can state what it will do with data before it serves a single request, which is most of a privacy notice, generated from the modules rather than written by hand
The same evidence available to every vendor	Nobody gets a better view of the request than anybody else, so vendors compete on what they do rather than on access
Declarations that are machine-readable, in code that is open	A claim can be checked against actual behavior cheaply, by anyone, on every release rather than once at onboarding
A conformance suite any provider can be run through	A vendor can show their module behaves before shipping it, and the project can show it too
Startup that fails rather than falls back quietly	A misconfigured deployment stops instead of doing something nobody asked for and nobody notices

Those are reasons for the wider ecosystem to engage with Trusted Server, not just reasons for us to like it. We would much rather arrive in New York with them shipped and running than describe them as a plan.

[aram356]

@jwrosewell

Wanted to flag a few process things that are making it hard for us to keep up with the review, rather than any issue with the work itself.

Force pushes. The branches are being force-pushed, which means the previous commits go away and GitHub can no longer show us what changed since our last look. On a PR this size that costs us a lot: we end up re-reading the whole diff rather than just the delta. Could you push follow-up commits on top instead? We're happy to squash at merge time, so nothing needs to stay messy in the final history.

Resolving review threads. When a comment has been addressed, hitting Resolve conversation on the thread makes a real difference. Right now we can't tell at a glance which points are done and which are still open, so we re-check all of them. Your written responses have been thorough, and this just makes them easier to track against the code.

Re-requesting review. After you've pushed changes, please click the re-request review button next to our names. That's what puts the PR back in our queue. Without it we don't get notified, so a PR can sit longer than it should while we assume you're still working on it.

None of this is a comment on the substance, which we're working through separately. It's just that the current shape makes each pass more expensive than it needs to be, and these three things would speed us up considerably.

[jwrosewell]

@aram356 Taking these in turn.

Force pushes. Agreed. Follow-up commits from here, and squash at merge.

Resolving threads. All six of Christian's now have replies in place and
five are resolved. The sixth is open deliberately, because the answer is a
deferral to #1111 and that is his call to accept or not. Resolved as we go from
here.

Re-requesting review. We cannot. Our access to this repository is read
only, so the reviewer controls are not available to us. Every review request on #1043
and #1084 was made by you, on 27 and 31 August. Happy to drive it if
someone grants the access, and happy to keep asking by email until then, which
is what we have been doing.

Something that explains more of the delay than any button. We asked for this
work as a single pull request alongside #838 and were asked to split it. The
result is a dependent stack, so PRs #1044, #1045, #1046, #1047 and #1094 each
build on the one before and none can be reviewed until #1043 lands. We never said so
plainly, which is why five pull requests look like nobody has asked you to read
them. I will put the parent and the dependency at the top of each description
shortly.

Status, so it is written down somewhere you can point at. Everything from your
four reviews and Christian's is either answered in a thread or changed in the
code, all seven pull requests are green on every check, and all seven are
rebased on 0f8b44dc0. If that is not what you are seeing, tell me.

Note on how this was written. An AI assistant drafted this comment and checked
the permissions, dates and repository state against the GitHub API. I have read
it in full and stand behind what it says.

[jwrosewell]

@aram356 @jevansnyc could one of you press re-run on the prepare integration artifacts job for 1b88e42f7? It failed fetching wasm-opt rather than on anything in the branch.

Error: Failed to fetch URL https://github.com/WebAssembly/binaryen/releases/download/version_130/binaryen-version_130-x86_64-linux.tar.gz

The release build finished before that step, the same job passed on #1084 twenty minutes earlier, and the workflow has succeeded on 23 of its last 25 runs. Because that job failed, integration tests, browser integration tests and integration tests (Fastly EC lifecycle) were skipped, so those three have not run against this head. Every other check passes, CodeQL included. My access to this repository is pull only, so gh run rerun and the check-suite rerequest API both refuse.

Failed run: https://github.com/IABTechLab/trusted-server/actions/runs/34855712510

What this push changed, in short. The branch is merged up to current main (066ea3c69), so it is no longer behind, and it carries the answers to the five review comments on this pull request. Nothing was rebased, squashed or force-pushed, so the push was a fast-forward from ebf0117ec and every commit already reviewed is still there. The same update is coming for #1044, #1045, #1046 and #1047, and #1084 is already done. I will post the full description and the replies to the review threads once this run is green.