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

[jwrosewell]

This description was updated on 7 October 2026, and on 8 October for the merge of main at 182fdf4. The branch now carries
main at 182fdf4, so it has the identity-graph changes merged on
28 September (conditional writes, tombstones from a snapshot, grouped batch
sync, the pull sync marker and the EID sync source) and the reusable sandbox
in the Fastly entry point, with the seam on top of them. Since the last
version of this text:

1. What an operator selects is a module, and a module is named by its
   crate folder. The selector reads [ec] module, the trait is
   EdgeCookieModule, the file is ec/module.rs, and every name this pull
   request adds says module. A module name is parts joined by ., each of lower case letters,
   digits, _ or -, and a module from a crate is named by its folder
   below crates/, so it is written in full, as edgecookie.<name>, or
   with the type folder left off inside its own table.
   module_name.rs holds the rule, module_name!() derives a crate's name
   from CARGO_MANIFEST_DIR when the crate is built, and [ec] resolves a
   written name against the modules it has, so a name that is not a module
   name is refused with the rule in the message. Core's own hmac keeps
   its bare name. The retired [ec.providers] table keeps its literal in
   the refusal that names its replacement.
2. Orphan recovery sees the request's headers, path and query. The evidence
   snapshot is captured for a document navigation as well as for a request
   with no identifier, so a module asked for a replacement during recovery
   reads the same evidence as at creation.
3. Comments and docs say what the code does, with the history and plans
   taken out, and the tests are folded into tables where they repeated.
4. The pull sync marker key, which main derives from ec.passphrase,
   derives from the selected module's HMAC passphrase, or from the proxy
   secret for a module that has none, since ec.passphrase is only the
   deprecated location on this branch.
5. Comments say what the code does and why, with the history taken out.
6. The trait says what normalize_id_for_kv decides, the point raised
   on this pull request on 19 and 20 September. The returned value is the
   identity two visits must share, so a module whose identifier has a part
   reissued each time (a signature, a nonce, a timestamp) returns the
   stable part. Core asks accepts_id about the returned string as well
   as about the identifier as issued, so a module must accept its own
   canonical form. A fixture module with a stable part and a reissued part
   pins it, with two issues of one identity reaching one identity-graph
   key.

The commits since the merge are 53f16ab (the merge), 797c919 (orphan recovery sees the request's evidence), fbe302a (the cookie reading test that only read its own double is deleted), 977456e (push validation keeps a labeled block's other errors), 4da2a39 (comments, docs and tests brought into line) and 1e25353 (the seam says module), then on 7 October 6b2e303 (a module is named by its crate folder), ef4c013 (comments say what the code does), 5d808f2 (the trait says what normalize_id_for_kv decides, with a fixture test) and 6f52771 (the identity graph's comments describe device records, not person records). The last changes two comments and no behavior. The comment on the count of Edge Cookies that share a network read a low count as "an individual or household", and it now says a small network, such as a home connection. The partner identifiers are described as each partner's identifier for the same browser on the same device, never an identifier for a person.

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 the spec pull request (#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 the device and
location seam (#1044). 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 module behind the
EdgeCookieModule trait in
crates/trusted-server-core/src/ec/module.rs,
with the existing HMAC implementation as the built-in and configuration
selecting it.

How a module is selected

[ec] follows the convention the rest of the stack follows:

[ec]
module = "hmac"              # the module that runs
ec_store = "ec_identity_store"

[ec.hmac]                    # that module's own settings
passphrase = "ec_passphrase" # a key name in trusted_server_secrets

• [ec] module names one module, and [ec.<name>] holds that module's
  settings. Leaving [ec] module out means stateless operation with no Edge
  Cookie, and module = "none" spells the same choice explicitly.
• The table's name is the implementation it configures. A table may instead
  carry implementation = "<id>" and take a name of its own, which is what
  lets a deployment label a module for what it does rather than for what it
  is.
• A name or an implementation id is a module name, which is parts joined
  by ., each of lower case letters, digits, _ or -, and anything else
  is refused at startup with the rule in the message.
• A selected module with no table, a table the selector does not name, and a
  key a module does not know all fail at startup, so a misconfiguration is
  loud rather than silent. [ec] keeps its own settings beside module,
  being the store name, the partner registry and the cluster thresholds, and
  those are not mistaken for module tables.
• The deprecated [ec] passphrase form still starts. It migrates to
  module = "hmac" plus [ec.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.

The identifier and the identity graph

• Identifier bounds are global and module-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 module'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 module round-trips verbatim, another proves the graph is
  keyed by the canonical form, and a third proves that two issues of one
  identity share one key when the module returns the stable part.
• Vendor [ec.<name>] tables are captured as raw values in core and
  deserialized by the adapter that injects the vendor module, so core never
  names a vendor.
• Every module 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 modules can never collide and switching modules cannot silently
  adopt another module's identities. The built-in module creates
  hmac~<hash>.<suffix> and still reads its earlier bare form so deployed
  cookies keep working.
• Every path that reads or writes the identity graph keys the row by the owning
  module's canonical form. Pull sync, batch sync and the admin lookup accept
  an identifier through AcceptedModules, which applies the global bounds
  and then asks the module that owns the identifier's code, so a code no
  configured module owns is refused. Identify, Edge Cookie finalization, pull
  sync, batch sync, the admin lookup, /auction, the publisher navigation
  preload and /_ts/page-bids all use the canonical key, so a module 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.
• On main's identity-graph flow, EID ingestion, orphan recovery and the
  withdrawal tombstones are keyed the same way, so an ingested EID lands on
  the live row and a withdrawal tombstones the row the identifier is stored
  under.

What a module may do to the response

• A module may set its own cookies and headers. 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 module 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 module. It passes the
  empty string when the host has none, and each module decides whether it
  needs one. The built-in HMAC module refuses to create an identifier without
  one.
• A module asked for a replacement identifier during orphan recovery reads
  the request's headers, path and query, the evidence it reads at creation.
• Generation failures log at error level, not warn.

How it was verified

The head this pull request shows now is d33507b32, which merges main at 182fdf4 into 6f527710a. The merge brings the ts dev lint domains and ts dev install-hooks commands (#733) and a design document (#930), and changes none of this pull request's own code. No dependency of core or of an adapter changed version, and the one line of core the merge touches gains a comment. On d33507b32 these ran locally on Windows: cargo fmt --all --check, a locked dependency check (cargo tree --locked) and the core suite natively (3,003 tests).

6f527710a adds three commits to
6b2e303f1, one of comment wording, one that documents
normalize_id_for_kv and adds a test, and one that words the identity
graph's comments as device records. On 6f527710a these ran locally on
Windows: cargo fmt --all --check, Clippy with warnings denied on all four
adapters, the core suite natively (3,003 tests), and the docs lint,
Prettier and VitePress build. On 6b2e303f1 the wider set ran locally,
being the core suite under Viceroy (3,239 across the crate's test binaries),
the Axum (45 tests), Cloudflare (55) and Spin (90) adapter suites and the
cross-adapter parity suite (17), and CI runs all of them on this head. The
CLI tests, the browser integration tests and the Fastly Edge Cookie
lifecycle test run only in CI.

CI on d33507b32: every check passes, being Run Tests, Run Format, Integration Tests and CodeQL Advanced, with the Fastly Edge Cookie lifecycle test in the integration run.

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 module, 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 and #778. Decomposes #838, which is 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 seam design specs #1084, the design set. No code, conflicts with nothing, mergeable today.
2. Add a pluggable Edge Cookie module seam with the built-in HMAC module #1043, this one.
3. Add device and geo module selection with the host-signal Edge Cookie module #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 module documentation set and finish the decomposition #1047, the documentation set.
7. The implementation of Add the integration seam design specs #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.

[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.

[jwrosewell]

normalize_id_for_kv decides whether a provider can have long lived sessions, and the trait does not say so

Raised from implementing a provider against this seam and deploying it.

provider_kv_key builds the identity store key from the provider code and
whatever normalize_id_for_kv returns. That makes this one method the decision
about what two visits have to have in common before they are treated as the
same visitor, which is a larger contract than the name suggests.

The documentation on the trait method describes normalisation, so the obvious
implementation for a provider whose identifier is case sensitive is to return
the value unchanged. That is correct as normalisation and wrong as a key, for
any provider whose identifier carries a signed envelope.

Why an envelope breaks it

Several identifier formats wrap a stable payload in an envelope carrying a date
and a signature. The envelope is what makes the identifier verifiable, and it
is reissued, so it differs every time even when the payload is identical.

If the whole identifier becomes the key, two identifiers for the same device
produce two different keys and two unrelated rows. Nothing accumulated under
the first is ever found again under the second, so the identity graph never
holds more than one visit and the store may as well not be there.

The fodid crate on crates.io, which reads one such format, documents the
point directly on its match_key accessor:

This is the stable field for comparing two 51Dids: two identifiers for the
same inputs share the same match key even though their wrapping envelopes
(date, signature) differ on every issue. Compare match keys, never envelopes.

So the format itself says the envelope must not be compared, and the seam as
documented leads an implementer to key on exactly that.

What would help

Say in the trait documentation what the key is for. Something to the effect
that the returned value is the identity two visits must share to be treated as
the same visitor, and that a provider whose identifier carries a signature,
nonce, timestamp or any other per-issue field must return the stable part and
not the transported value. One sentence there turns a silent data fault into an
obvious implementation requirement.

Consider whether the method name carries its weight. normalize_id_for_kv
reads as a formatting concern, which is what leads to the identity
implementation. Something naming the stable identity would be harder to get
wrong, though renaming it is a bigger change than this PR probably wants.

A test in the seam's own suite would pin it. A fixture provider whose
identifier is a stable payload plus a varying suffix, asserting that two
identifiers differing only in the suffix produce one key, would fail for any
implementation that returns the value unchanged and would document the contract
by example.

Not a defect in this PR

The seam is doing what it says. The built-in HMAC provider is unaffected, since
its identifier has no envelope. This is about what the seam tells the next
implementer, and it is worth fixing here rather than in each provider, because
every provider that gets it wrong gets it wrong silently and only in
production, where the symptom is an identity graph that quietly never grows.

Happy to open a PR against this branch with the documentation change and the
fixture test if that is useful.

[jwrosewell]

Correcting my earlier comment: I overstated how often this bites

In my comment above I wrote that two identifiers for the same device produce
two unrelated rows, and let that stand as though it happened on every visit. It
does not, and the difference is large enough that the comment should not be
read as it was written.

The Edge Cookie is reused when the request already carries one. The generation
path returns immediately in that case, and the cookie has a one-year lifetime,
so the identifier is stable for as long as the reader holds it. A new row is
written on reissue, not on each visit.

So the consequence is that identity does not survive a reissue, rather than
that the store never accumulates anything. Still real, considerably smaller,
and I should have traced the reuse path before describing the effect.

What I still think is worth doing here is unchanged, and it is the part
that is about this pull request rather than about any one provider:

normalize_id_for_kv decides what two visits must have in common to be treated
as the same visitor, which is a larger contract than the name suggests. The
documentation describes normalisation, so the obvious implementation for a
case-sensitive identifier is to return the value unchanged, and that is correct
as normalisation and wrong as a key for any identifier carrying a per-issue
field such as a signature or a timestamp. An implementer who gets it wrong gets
it wrong silently and only in production.

A sentence in the trait documentation saying the returned value is the identity
two visits must share, and a fixture provider in the seam's own tests whose
identifier is a stable payload plus a varying suffix, would both close it. The
offer to raise that as a pull request against this branch stands.

Apologies for the noise of a correction. Better than leaving the first version
standing.