Skip to content
bucker

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 act pseudonym_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: material is 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.