Add the permission model with the Privacy Taxonomy vocabulary

[jwrosewell]

This description was updated on 7 October 2026, and on 8 October for the merge of main at 182fdf4. The branch now carries
the refreshed device and geo branch (#1044 at 6fc9cdf) and, through it,
the Edge Cookie seam and main at 182fdf4. 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 [permission-signal] modules, a list
   because several signals run in order, the trait is
   PermissionSignalModule, and every name this pull request adds says
   module, as the seams below it do. Each of the five crates names itself
   with module_name!(), so crates/permission-signal/gpp is
   permission-signal.gpp and the hand-written ids this branch started
   with (gpp_sale_opt_out, us_privacy) are gone. In the section the
   type folder may be left off, so the modules are selected as gpc,
   gpp, us-privacy, tcf and mtm. A configuration still carrying
   [permission_signal], sources or module is refused with the key to
   write.
2. The permission state says which permissions are still waiting for a
   signal, as awaiting beside set, narrowed to what some configured
   module could still grant, so a page can tell a prompt that has not run
   from a visitor who said no.
3. Each module owns its own unreadable signal. The override that revoked
   everything ahead of the modules when a record arrived unreadable is gone.
   A module reads its own unreadable record as the refusal it may have
   carried and says nothing about any other scheme, and the state carries
   signals, one entry for each signal a module read and found valid, as
   received. The page receives all four lists.
4. The Model Terms for Marketing module ships, a fifth scheme under
   crates/permission-signal/mtm, reading the preference a platform
   recorded in the first party cookie __mtm_pref, which any platform may
   set and Trusted Server never writes. It is the first scheme that declares
   terms.
5. The five permission signal crates' own tests run in CI through the Axum
   aliases, which did not name them before.
6. Withdrawal on this branch is the permission state's answer, so the pull
   sync marker expiry main added reads it, and the legacy consent store
   main removed is gone here too.
7. Comments and the permission model guide say what is true now. The
   integration fixture carried two notes on its geo selector that
   contradicted each other, and it, the Viceroy template, the template
   cache harness and the guide mentioned a default country setting that
   no released version had. The branch also carries Add a pluggable Edge Cookie module seam with the built-in HMAC module #1043's statement of
   what normalize_id_for_kv decides.

The commits since the merge are 66b4bf6 (the merge), 796bb47 (the no-location warning says what happens), 207d04e (which permissions are still waiting for a signal), c04649f (await only what a configured module could still grant), ddceadd (each module owns its own unreadable signal, and the state names the valid ones), 7554c3e (the Model Terms for Marketing module), fc2a355 (the permission model says module), 1e8b612 (the module crates' tests run with the Axum adapter) and 511db9b (comments and tests brought into line), then on 7 October 6489135 (the merge of #1044 at 6fc9cdf) and fd51fe8 (the permission signal modules are named by their crate folders), then 05a1cce (the merge of #1044 at cec6052), 9da9a65 (comments and the permission model guide say what is true now), c0a0f3a (the merge of #1044 at 09514b1) and 613cd18 (the merge of #1044 at fb1d369, which brings #1043's wording of the identity graph's comments as device records).

Stacks on device and location module selection (#1044), and depends on its
[geo] module selector, whose default this pull request changes to no
geolocation. Through #1044 this pull request also depends on the Edge Cookie
module seam (#1043) for the EdgeCookieModule trait, which it gates on
permissions. The stack has six pull requests
(#1043, #1044, #1045, #1046, #1047, #1094), each targeting main, with this one
third, and the first five decompose #838 as requested in the #986 review.
Compare split/2-device-geo with split/3-permissions
to see only this pull request's change.

The design specs for the series are carried by the spec pull request (#1084).
The spec for this pull request is
2026-07-30-permission-model-design.md,
revised to match this implementation, with revision records listing every
divergence and why, and section 13 covering the permission signal modules.
Reader documentation lands with this pull request at
docs/guide/permission-model.md
and
docs/guide/permission-signals.md.

What this pull request does

Permissions become the primitive that gates identity features, and consent is
one of several ways a permission is established, alongside a country baseline,
an opt-out signal and configuration.

• permissions.rs
  resolves a per-request permission state, being the country and region
  baseline from permissions.yaml amended by the signals the request carries.
  permissions.yaml is compiled into the build, and the repository sample is
  config/permissions/sample.yaml.
  Permission names follow the IAB Privacy Taxonomy Data Uses.

How the signal modules are selected

Signals are read by permission signal modules, which are crates outside core
under
crates/permission-signal/,
being Global Privacy Control, the GPP sale opt-out, the US Privacy string, TCF
v2 and the Model Terms for Marketing, each implementing the
PermissionSignalModule trait that core defines in
permission_signal/mod.rs.

[permission-signal]
modules = ["gpc", "gpp", "us-privacy", "tcf", "mtm"]

An adapter selects them once at startup from [permission-signal] modules,
refusing an unknown or repeated name there rather than on the first request,
and carries them on the request services. An unknown name is reported with the
names the build does have, so a typo is answered with the list to pick from.

Precedence is the configured order. For each permission, core asks the
modules in the order [permission-signal] modules lists them. Each answers
grant, revoke or neutral, a neutral answer leaves the prior value standing, and
the last module with an opinion decides. Leaving the list out runs every
module the adapter links, in the adapter's order, and an empty list runs
none, which leaves every permission at its country and region baseline. Every
adapter offers the five in the same default order, being gpc, gpp,
us-privacy, tcf and mtm. Global Privacy Control, a
browser setting with no interface of its own, is asked first, and the schemes
that carry a choice someone made through an interface are asked after it, which
means an answer given at a prompt amends the header the visitor arrived with. A
deployment that wants an opt-out to stand lists it after tcf.

What the state carries

The page receives the state as window.tsjs.permissions, with four lists:
set, the permissions that are set; awaiting, the permissions whose
baseline requires a signal and for which no configured module has answered,
narrowed to what some configured module could still grant, so a page can hold
what depends on them rather than read "nobody has answered" as "refused";
signals, one entry for each signal a module read and found valid, as it was
received, with the module and the scheme, so page code and bid requests rely
on exactly those signals and no other; and tdls, the terms documents the
data is available under. An empty state renders every list empty, and each
is an answer rather than a missing value.

The rest of the model

• Each module owns its own unreadable signal. What an absent, unreadable or
  expired record means for the permissions is the decision of the module for
  that scheme, taken in its own answer. The shipped modules read their own
  unreadable record as the refusal it may have carried, on the permissions
  their scheme covers, and say nothing about any other scheme, so the
  configured order decides a readable record from one scheme beside an
  unreadable one from another. After assembly the consent context keeps only
  the raw strings the valid signals name, so a corrupt record never reaches a
  bid request.
• Leaving gpc off the list stops that module, but the consent pipeline
  still turns the same header into a US Privacy opt-out for a US privacy state
  when the consent setting gpc_implies_optout is on, which it is by default,
  and the us-privacy module then acts on that record. A deployment that
  wants the header to have no effect turns that setting off as well.
• Cross-scheme tests in
  crates/trusted-server-adapter-axum/tests/permission_signals.rs
  assemble the real modules and cover the default order against each opt-out,
  the reversed order, a module left off the list, one opt-out removed while
  the others stand, and the Model Terms words.
• The TCF purpose to Data Use mapping lives in the TCF module crate
  (crates/permission-signal/tcf/src/mapping.rs),
  in code with tests, because which purpose grants which Data Use is that
  scheme's own meaning rather than a deployment's policy. permissions.yaml
  keeps what a deployment decides, being which opt-out sources revoke which
  Data Uses and whether a TCF record answers at all. The purposes are the IAB
  TCF Europe purposes and what they grant are IAB Tech Lab Privacy Taxonomy
  Data Uses, so the mapping is checked against the industry's own documents
  rather than against us. Two purposes have no Data Use yet, so the crate
  carries the proposed necessary.operations.storage key for purpose 1 and the
  TCF identifier select-basic-content for purpose 11 until the taxonomy adds
  them.
• The permission state also carries tdls, the terms documents the request's
  data is available under, declared by the modules in the order they are
  asked with duplicates removed. A permission says what may be done with the
  data and not on what basis, and a recipient offered data needs both, because
  it has to decide whether the terms are ones it accepts and whether it may
  pass the data on. Each entry addresses a published document that must never
  be edited once published, which is why a version belongs in its address, and
  the name matches the tdl member the
  Data Labels work
  puts on an OpenRTB node. Of the five schemes only the Model Terms for
  Marketing declares terms, the versioned Model Terms document, whenever an
  answer is present.
• The Model Terms for Marketing module reads one of the words standard,
  personalized and non-marketing from __mtm_pref. Both marketing words
  grant storage, contextual advertising, measurement, content performance,
  market research, product improvement and basic content selection, and only
  personalized grants the four Data Uses that depend on browsing history or
  interactions, which standard refuses because the visitor chose against
  them. non-marketing changes nothing, so the country and region rules
  decide. No word withdraws. The five schemes are a starting set rather than
  the list, and
  docs/guide/permission-signals.md
  says how a scheme is added as a crate with no change to core.
• Destructive withdrawal is narrow. A module answers withdrawal separately
  through withdraws, core scopes the answer to the storage baseline, and of
  the five only TCF answers it. Only a TCF record refusing storage in a
  jurisdiction whose baseline did not grant storage therefore expires the
  cookie, the pull sync marker and writes the identity-graph tombstone.
  Opt-outs suppress use, with Edge Cookie headers stripped and nothing sent
  beyond the edge, but never destroy an issued identifier, so lifting the
  opt-out restores the identity. This differs from main, where
  has_explicit_ec_withdrawal in
  consent/mod.rs
  also withdraws in a US privacy state for a Global Privacy Control signal, a
  GPP sale opt-out or a US Privacy sale opt-out. Under this pull request those
  opt-outs suppress use and keep the cookie, and the withdrawal tests main
  wrote around a California Global Privacy Control opt-out state the
  withdrawal on the permission state.
• Sharing beyond the edge, being the bidstream user.id, the identify response
  and partner pull sync, requires both storage and personalized-ad selection
  (StoreOnDevice and SelectPersonalisedAds in ec_sharing_allowed), the
  same pair that gates bidstream EIDs, so a storage-only grant keeps
  first-party use while withholding partner sharing.
• The Edge Cookie gate moves from raw consent to the permission model. A
  module declares required_permissions() and core runs it only when every
  one is set.
• The permission baseline and the jurisdiction to assume when no country
  resolves are declared together on the top node of the rules tree in
  permissions.yaml, so there is always a defined baseline and one file states
  the policy for both. A failed geo lookup is distinct from an unmatched
  country. It resolves at the requires-signal floor instead of the declared
  default and is logged at error level, and the one-time warning for a lookup
  that resolves no location says that the declared jurisdiction applies.
  Geolocation is off by default, and a deployment that runs an Edge Cookie
  module with no location module must set
  [geo] assume_single_jurisdiction = true, acknowledging that every request
  is treated as the declared jurisdiction.
• permissions.yaml rules use an explicit per-permission acquisition map
  (granted, requires_signal, denied). Parsing rejects an unknown group,
  Data Use, acquisition or revoke keyword, a top node missing group or
  jurisdiction, and two place codes that differ only by case, each case in
  one table of refusals. An EU-27 plus EEA coverage test locks the gdpr-eu
  mapping.

Changed from an earlier description

An earlier version of this text described precedence as a rule fixed in code,
where an opt-out always beat a consenting TCF record. Precedence is the
configured order described above. Under the default order, a visitor who sends
Sec-GPC: 1 and then consents through a consent management platform has the
Data Uses that the TCF record consents to set, which is the opposite of the old
outcome, and a deployment gets the old outcome back by listing the opt-out
after tcf. An earlier version also said an unreadable consent record revoked
everything ahead of the modules. It no longer does, for the reason given
above.

How it was verified

The head this pull request shows now is 0afd715c5, which merges #1044 at 47551a622 and, through it, main at 182fdf4 into 613cd1831. 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 0afd715c5 these ran locally on Windows: cargo fmt --all --check, a locked dependency check (cargo tree --locked) and the core suite natively (3,114 tests).

613cd1831 adds to fd51fe830
one commit of comment and guide wording and three merges of #1044, which bring
comment wording, the identity graph's comments, one doc comment and one
test. On 613cd1831 these ran
locally on Windows: cargo fmt --all --check, Clippy with warnings denied on
all four adapters and the five permission signal crates, the core suite
natively (3,114 tests), the five permission signal crates' own tests
(55 tests), and the docs lint, Prettier and VitePress build. On fd51fe830
the wider set ran locally, being the core suite under Viceroy (3,350 across
the crate's test binaries), the Axum suite with the five permission signal
crates (123 tests), the Cloudflare (56) 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 0afd715c5: every check passes, being Run Tests, Run Format, Integration Tests, Permissions Inspector and CodeQL Advanced, with the Fastly Edge Cookie lifecycle test in the integration run.

Framing

Privacy is a spectrum and technology is neutral. This model encodes no
jurisdiction's law. The deployer brings the policy in permissions.yaml and
configuration, decides their own baselines, and the code makes those decisions
inspectable and enforced. Trust comes from that flexibility being respected,
not from constraint.

References #777 and #779. Decomposes #838. Spec baseline from #986.

[aram356]

The sequencing discussion for this series is on #1084. This PR is superseded rather than rejected. The design in §3.6 is accepted and most of the provider work carries over onto the reordered base. See #1084.