Identity: keyed pseudonyms, generations and what is stored
Product analytics counts people without being able to read them back. Every end-user identifier (a distinct id, an email, an IP, a device id, a cookieless visitor, a survey respondent, an account key) is turned into a pseudonym before it is stored. This page is the contract.
Two schemes
v1 scopedPseudonym(projectId, value) |
v2 keyedPseudonym(projectKey, purpose, value) |
|
|---|---|---|
| Construction | sha256("<projectId>:<value>"), hex, first 32 |
HMAC-SHA256(key, "<purpose>\0<value>"), hex, first 32 |
| Secret | none (the project id is public) | a per-project key derived from AUTH_SECRET |
| Used by | existing userHash, ipHash, release-session hashes |
every new subject, visitor, respondent, device and account key |
| Status | frozen; never edited | current |
v1 lets anyone holding a leaked column test candidate emails offline. v2 does not. v1 stays because
rows already carry it; dualPseudonyms returns both so an erasure or a lookup finds either.
Purposes: subject, anon, device, account, respondent, visitor. The purpose is part of
the message, so the same string under two purposes gives unrelated values.
Keys: derived, never stored
key = HKDF-SHA256(ikm = AUTH_SECRET, salt = "bucker:pseudonym:v2",
info = "bucker:pseudonym:<generation>:<projectId>", 32 bytes)
pseudonym_generations stores (projectId, generation, keyRef, activeFrom, retiredAt). keyRef
is a one-way check of the derived key (hkdf-sha256:<32 hex>), never key material.
AUTH_SECRET cannot be rotated on its own. A new secret derives different keys, so every
stored v2 value would stop matching and an erasure would miss every row. The resolver compares
the derived key's check with the ACTIVE generation's keyRef and throws
PseudonymKeyMismatchError (pseudonym_key_mismatch) rather than compute values that cannot
join. A routine retireGeneration refuses the same way.
Moving to a new secret is a deliberate, recorded step: put the new secret on every process
first, then retireGeneration(projectId, { acceptSecretChange: true }) opens the next
generation under it. The cost is stated rather than hidden. No process can re-derive a
generation opened under the old secret, so those generations are reported in
unresolvableGenerations and the v2 values stored under them can no longer be linked to anyone
(in effect crypto-shredded). The frozen v1 beside them still matches while the dual window is
open. A process still holding the old secret refuses after the bump, because its derivation of
the new active generation fails the check; that is the safe direction.
Generations and the dual-compute window
- Generation 1 is created on a project's first write. Exactly one generation is active.
retireGeneration(projectId)retires the active one and opens the next in one transaction (serialised on the project row). It is the domain half of the operator actpseudonym_generation.retire; the console action and its two audit rows belong to PLAT-20.- New writes use the active generation.
dualPseudonyms(projectId, value, purpose?)returns{ v2, v1, retired[], all[], unresolvableGenerations[] }: the active value, the frozen v1, the retired generations' values, the full set to match, and any generation that can no longer be computed (after a secret change). A retired generation keeps matching with no time cutoff: subject, device and account rows are not telemetry and do not age out on a retention class, and dropping a generation from matching while a row still carries it would let an erasure miss that row. One HMAC per retired generation per lookup is the price. - A key object never carries its material into a log line or JSON:
materialis non-enumerable and the object is frozen. - Each process caches a project's generations for 60 seconds, so a rotation reaches other machines within that time. The retiring process drops its own entry at once.
What is and is not stored
Stored: keyed pseudonyms (subjectKey, deviceKey, visitorKey and similar), the frozen v1
beside them for the dual window, generation numbers, and the sealed draftCiphertext of an
end-user erasure draft (encrypted with the at-rest envelope).
Not stored: a raw email, IP, distinct id, device id or user agent of an end user, and no key.
api/test/schema/no-raw-identifier.test.ts lints schema.prisma so a new column named
email, distinctId, ip, userId (without Hash/Key/Digest/Ref) or documented as
holding one in the clear fails the suite. The columns that predate Phase 3 belong to
organisation members, SSO, billing and the legacy tables and are frozen by name in that test.