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