Skip to content

Report CMP consent to the EC route and merge its answer into Prebid - #1622

Draft
prk-Jr wants to merge 8 commits into
feat/1594-identity-only-tsjsfrom
feat/1599-ec-route-consent-script
Draft

prk-Jr wants to merge 8 commits into
feat/1594-identity-only-tsjsfrom
feat/1599-ec-route-consent-script

Conversation

@prk-Jr

@prk-Jr prk-Jr commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Report the publisher CMP's TCF and GPP decisions from the Prebid integration to the same-origin EC route, so a reader who consents after the page loads can get identity on that page view and a withdrawal reaches the server without waiting for the next navigation. Calls go one at a time and in order; a possible withdrawal is never replaced or dropped.
  • In identity mode, merge the route's answer into publisher auctions while the mirror cookie is unchanged, and merge nothing while a possible withdrawal is pending. Auction mode reports consent but merges nothing in the browser.
  • In both modes, copy an active localStorage _pubcid_optout into the _pubcid_optout cookie the server honors (SID-2), using Prebid's own rule.

Stacked on #1620 (identity-only mode, #1594), targeting feat/1594-identity-only-tsjs; it must land first.

The server route does not exist yet. #1598 (T19) has no implementation on any branch and is itself blocked by #1591, #1592, #1593 and #1600. Reporting stays off until the server injects window.__tsjs_prebid.ecRoute, which this PR leaves to T19, so no deployment calls a missing route. The spec's request contract is what T19 must accept, including injecting ecRoute, which #1598's text does not mention yet.

What changes for existing deployments

  • Auction and identity mode, every page: a reader whose localStorage holds an active _pubcid_optout now gets a host-only _pubcid_optout=1 cookie and a _ts_pubcid_optout_src=ls marker. The copy is removed when the localStorage opt-out ends; a publisher-written cookie is left alone. Auction mode previously wrote no cookie from tsjs.
  • Identity mode: mirrored pubcid.org IDs are dropped from auctions while either opt-out is present.
  • The served Prebid shim grows by 11,016 bytes (55,103 to 66,119), mostly the GPP capture moved in from Extract existing Sourcepoint consent synchronization #1535. It ships on every Prebid page even before T19 turns reporting on. Its size guard rises from 55,500 to 66,500; the guard still fails on an accidental import of the 200 KB Prebid runtime.

Changes

File Change
crates/trusted-server-js/lib/src/integrations/prebid/tcf_reader.ts Observe the publisher's __tcfapi without installing an accessor; resubscribe on replacement; remove a superseded stub subscription through the CMP that now holds it.
crates/trusted-server-js/lib/src/integrations/prebid/gpp_capture.ts GppConsentCapture moved unchanged from #1535 apart from log prefixes.
crates/trusted-server-js/lib/src/integrations/prebid/consent_queue.ts Pure ordering: request body, grant/barrier classification, tail deduplication, one call in flight, failed barriers retained and failed grants dropped.
crates/trusted-server-js/lib/src/integrations/prebid/ec_route.ts Route client: same-origin path validation, fetch, response validation (16 KiB byte cap), discard, suppression, merge-source selection; CMP discovery and lifecycle triggers.
crates/trusted-server-js/lib/src/integrations/prebid/pubcid_optout.ts Prebid's localStorage opt-out predicate, the marked cookie copy and the opt-out check.
crates/trusted-server-js/lib/src/integrations/prebid/identity.ts Split mirror parsing, expiry and cookie reads so the merge takes its IDs from a supplied source; expire the mirror cookie on a known withdrawal.
crates/trusted-server-js/lib/src/integrations/prebid/index.ts Wire opt-out sync in both modes, the route client when ecRoute validates, and the identity-mode merge source.
crates/trusted-server-js/lib/test/integrations/prebid/*.test.ts Unit and integration tests for each module and through installPrebidNpm in both modes.
crates/trusted-server-js/lib/test/prebid-artifact-integration.test.mjs Raise the measured shim size guard.
docs/guide/integrations/prebid.md Document consent reporting, ordering, merge limits and the opt-out copy.
docs/superpowers/specs/2026-11-18-ec-route-consent-script-design.md Design, request contract for T19 and review log.
docs/superpowers/plans/2026-11-18-ec-route-consent-script.md Implementation and verification plan.

Closes

Part of #1599; does not close it. Its acceptance criteria that need the route's Set-Cookie, record, provider and Safari behavior (on Fastly and on Axum behind CloudFront) can only pass once #1598 lands. The browser-side criteria (ordering, withdrawal during an in-flight grant leaving no ID in Prebid, the localStorage opt-out copy) are covered here against a controlled responder.

Spec

Spec: EC route consent script, with four agent review rounds and an implementation review in its log.

Test plan

  • cargo test-fastly && cargo test-fastly-reuse && cargo test-axum && cargo test-cloudflare && cargo test-spin (Fastly under the pinned Viceroy 0.21.0)
  • All eight target-matched Clippy aliases
  • cargo fmt --all -- --check
  • JS tests: npx vitest run — 87 files, 3,413 tests
  • JS format and lint
  • Docs format
  • WASM build: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
  • Adapter parity tests, native build-digest test and lint, Wasm clock lint
  • URL-host lint on added lines
  • Other: negative controls — reverting each ordering, suppression, retry, discard, byte-cap and stale-listener protection fails a specific test
  • Other: runtime verification in real Chromium through the actual Axum app and Fastly under Viceroy 0.21.0, both serving tsjs byte-identical to a fresh build of this revision, with a generated Prebid 10.26 bundle

Runtime results, identical on Axum and Fastly:

  • Normal server injection (no ecRoute): identity mode makes no route call and still merges the mirror cookie into the auction; auction mode makes no route call and keeps its trustedServer bidder. An active localStorage opt-out produces _pubcid_optout=1 and the marker (host-only, Secure, SameSite=Lax), the next navigation request carries them, removing the localStorage item removes both on reload, and a publisher _pubcid_optout=pub cookie is left alone.
  • Route behavior, activated by a fixture that adds ecRoute and a controlled responder standing in for EC route in the shared app, verified on Fastly #1598: a grant sends exactly one POST with {"tcString":…} and the page Origin, and the next auction carries the route's ID. With grant A held in flight, withdrawal B and grant C arrive A, B, C with at most one call in flight; B expires the mirror at once, and auctions run while B or C is pending carry no mirror or route IDs even though A's late answer re-set the mirror. After C is answered the route's ID returns. With ecRoute absent the same CMP sequence sends nothing. While opted out, pubcid.org entries are dropped from mirror and route IDs.
  • Not verified: a real EC route in the shared app, verified on Fastly #1598 server and its Set-Cookie, Safari's cookie lifetime, real CMPs, GPP CMP readings, failing or timed-out route answers, BFCache, and HTTPS deployments.

Checklist

  • Feature PRs: spec linked above, ending in a review log of two or more agent review rounds
  • Changes follow AGENTS.md conventions
  • No unwrap() in production code — use expect("should ...")
  • Uses log macros (not println!)
  • New code has tests
  • No secrets or credentials committed

🤖 Generated with Claude Code

Define the browser half of the EC route: consent capture from the
publisher's TCF and GPP CMPs, the request contract the server route must
accept, in-order delivery that never drops or reorders a withdrawal,
merging route answers into identity-mode auctions and copying a
localStorage SharedID opt-out into its cookie. The server route (#1598)
injects the route path that turns this on.
The Prebid integration observes the publisher's TCF and GPP CMPs and
posts each decision to the injected same-origin EC route, one call at a
time and in order. A newer grant replaces a waiting grant, but a possible
withdrawal is never replaced or dropped, so it reaches the server after
any grant in flight and before any later grant. In identity mode the
route's answer is merged into publisher auctions while the mirror cookie
is unchanged, and nothing is merged while a possible withdrawal is
pending. Reporting stays off until the server injects the route path.

In both modes a localStorage SharedID opt-out is copied into the
_pubcid_optout cookie the server honors, using Prebid's own rule.

GPP capture moves in from the Sourcepoint consent extraction (#1535) with
its tests. The served shim grows by 11 KB, so its size guard rises.
@prk-Jr prk-Jr self-assigned this Nov 18, 2026
A known TCF withdrawal whose TC string cannot be sent queues nothing, so
the grant already in flight lifted suppression when it was answered and
its late mirror reached the next auction. Such a withdrawal now fences
suppression: only an answer to a call queued after it lifts it. A repeated
withdrawal that is already queued does not fence, so its own answer still
lifts suppression.

Also remove two members only tests used and make the no-route
preservation test cover auction mode too.
A known withdrawal with an unsendable TC string but a valid GPP reading
was sent without its TCF part, so the server answered from the stale
euconsent-v2 cookie and that answer lifted suppression. Fence whenever
the withdrawal's TCF reading cannot be sent, stamping its own call
before the fence. After a fence, a reading equal to the last call is
sent again, so an unchanged later reading can still lift suppression.
A grant sent after a fence that then failed left the older answered state
deduplicating the next identical reading, so merging stayed suppressed
for the rest of the page view. A fence now forgets the last answered
state instead of flagging repeats, and an identical fenced withdrawal
that is already pending or answered no longer re-fences and resends.
The spec's contract, ordering and merging sections state the fence rules.
Skipping the fence for a withdrawal whose GPP-only body matched an
earlier call let that call's answer, built from the stale euconsent-v2
cookie, lift suppression. A known TCF withdrawal with an unsendable TC
string now makes no call at all and only fences, so there is no
cookie-based answer to trust and no repeat rule to get wrong.
When an unchanged reading followed an unsendable withdrawal while the
identical call was still waiting or in flight, the reading was
deduplicated without a new stamp, so that call's answer could not lift
suppression for the rest of the page view. Re-stamp the pending call:
its answer reflects the current reading.
@prk-Jr prk-Jr linked an issue Nov 18, 2026 that may be closed by this pull request
9 tasks

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Injected script calls the EC route on consent and merges the IDs into Prebid

1 participant