feat(pairwise): add NewReversible, a reversible pairwise deriver

[osanderson]

Adds pairwise.NewReversible, the recommended pairwise deriver: it encrypts the internal subject into the pairwise sub, so the OP can map any sub it issued back to its end user without storing anything. JWT access tokens, id_token_hint/login_hint/claims sub values and resource servers all resolve through pairwise.Lookup, as with NewMapping.

Construction

SIV (Rogaway and Shrimpton, "A Provable-Security Treatment of the Key-Wrap Problem", EUROCRYPT 2006), assembled from the standard library (Go has no AES-SIV; the module has no dependencies):

A    = u32be(len(f)) || f, for f in ["fapigo ppid r1", issuer, sector]
P    = byte(len(subject)) || subject || zero padding to 152 bytes
IV   = HMAC-SHA-256(macKey, A || P)[:16]
C    = AES-256-CTR(encKey, IV, P)
body = base64url(IV || C), no padding        -- always 224 characters

• Two independent 32-byte keys; wrong size, placeholder (one byte repeated) and equal keys are refused. Custody is declared as for NewHMAC.
• Issuer and sector are associated data: a body only opens under the issuer and sector it was derived for.
• Fixed-size plaintext: every body is the same length, hiding the subject's length. Internal subjects are limited to 151 bytes (pairwise.MaxReversibleSubjectLength, ErrSubjectTooLong); 224 characters plus a 16-character prefix stays within OIDC's 255.
• Lookup refuses an issuer or sector longer than MaxInputLength (which no Input carries), then decodes strictly (exact length, canonical base64url), decrypts, and authenticates the full 16-byte IV in constant time before reading the plaintext. Any altered, truncated or foreign body is ErrSubjectNotFound, never another subject.

The docs state plainly that anyone holding both keys can map every pairwise sub ever issued back to its user, that every resource server given the keys shares that risk, and that the keys can't rotate without changing every sub. GETTING_STARTED now presents NewReversible as the recommended deriver, with NewMapping and NewHMAC as the alternatives.

Assurance

• Independent vectors: pairwise/testdata/reversible_vectors.json (11 vectors: users, sectors, issuers, a 1-byte and a 151-byte subject, a second key pair, a non-ASCII UTF-8 issuer and sector, and a subject whose IV ends in 0xfffffffd so the counter carries out of its low 32-bit word, which a 32-bit-counter port fails) generated by reversible_vectors.py — Python's hmac/hashlib for the IV and the OpenSSL CLI for AES-256-CTR. The Go code reproduces every vector in both directions.
• Fuzzing (each ≥60 s locally, now also in the scheduled fuzz workflow): round trip and cross-sector refusal; tampering with any byte; arbitrary bodies never panic and are never accepted.
• Tests: the deriver contract, every single-bit flip of a body, a forged IV re-encrypted correctly (only a full 16-byte comparison rejects it), key refusals, the subject cap, cancellation, custody, the plaintext parser's refusals, and server.New → code exchange → refresh → resource server with JWT access tokens.
• Mutation checks: 15 of 16 killed; the survivor is an equivalent mutant (the early body-length check, kept so an oversized string is never decoded).

Review follow-ups

• Long internal subjects: server.NewSubjectID accepts up to 255 bytes, so a longer subject than the reversible deriver holds now fails a pairwise completion with a server_error that names the 151-byte limit (audited, no code issued), instead of an opaque derivation failure. The limit is exported as pairwise.MaxReversibleSubjectLength and documented on NewSubjectID, SubjectConfig and in GETTING_STARTED.
• Deriver contract: the tampered-body case now changes a character to another within the base64url alphabet, so it reaches a Deriver's authentication or lookup instead of only its decoding; a test confirms it does for NewReversible.

Non-breaking: a new constructor; Derivation: pairwise.Reversible already required a pairwise.Lookup.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 94.62366% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pairwise/reversible.go	94.66%	2 Missing and 2 partials ⚠️
pairwise/contract.go	90.90%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
94.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud