Proposal: pseudonym interchange spec with cross-language test vectors

[mazzasaverio]

Context

The token format already has an ADR (docs/adr/0002-token-format.md) and the alias derivation is deliberately boring cryptography: HMAC-SHA256, explicit key and namespace boundaries. What it is not, yet, is a specification: something a Go service, a TypeScript frontend or a Rust pipeline can implement and get byte-identical aliases for the same key, namespace and value.

That gap matters more than it looks:

• Polyglot consistency. Real organizations are not Python-only. Today, consistent pseudonyms across a TS frontend, a Python backend and a Go pipeline require routing everything through one service, which is the vault vendors' business model. A spec plus test vectors makes it a library problem in every language.
• Pseudonymous joins. Two parties sharing a key and namespace can join datasets on aliases without exchanging identifiers: a poor-man's data clean room with no vendor in the middle. Data clean rooms are a growing market precisely because cross-border and cross-org constraints are tightening; the EDPB pseudonymisation guidelines describe exactly this split (identifying data stays, tokens travel).
• Consolidation-proofing. 2025-26 M&A absorbed most independent privacy vendors into platforms. A format with multiple implementations cannot be bought off the market; the originating project keeps the reference-implementation and test-vector authority (the Argon2/BLAKE3 pattern).

Proposal

1. Write the derivation and token grammar as a versioned spec (SPEC.md, marked Draft): inputs, normalization, HMAC construction, alias encoding, namespace derivation, the reserved token grammar, and explicit non-goals (no reversibility without stored mappings).
2. Ship language-neutral test vectors as JSON: (key, namespace, entity type, value) → alias, covering Unicode normalization edges, plus token-grammar accept/reject cases. The Python test suite consumes the same file, so the vectors can never drift from the implementation.
3. A conformance checklist for third-party implementations; ports themselves are left to the community and explicitly out of the maintenance promise.
4. Timing honors vision principle 9 ("earn compatibility after the architecture is proven"): the spec stays Draft and versioned until the stable milestone, then freezes with it.

Order-of-effects reasoning

• First order: polyglot teams get consistent aliases without a central service.
• Second order: consistent aliases across systems enable pseudonymous matching between organizations, with the key exchange as the only trust ceremony.
• Third order: implementations attract implementations; the format accrues network effects the way JWT and JSON Schema did, independently of any single library's popularity.
• Fourth order: if pseudonym interoperability becomes assumed infrastructure, the moat is no longer the code (commoditized, forkable, acquirable) but the format authority, which compounds and cannot be acquired.

🤖 Generated with Claude Code

https://claude.ai/code/session_012JiX3zWeEC28kmy5KmAXvf