feat(core): crypto-agility + post-quantum readiness for passkey algorithms

[wolpert]

What & why

Improves the project's post-quantum readiness through crypto-agility and honest documentation. This is not an addition of real post-quantum signature algorithms — none are standardized in the WebAuthn/COSE/FIDO2 ecosystem or supported by WebAuthn4J yet, so none could be added without inventing fake COSE identifiers. The goal is to make the algorithm choices configurable and to document the posture accurately.

No default signing or verify behavior changes, and no stored credential or issued token can stop validating.

Findings addressed

• Two divergent, hardcoded COSE algorithm lists: create-options (-7, -8, -257) in DefaultPasskeyAuthenticationService vs the verify list DEFAULT_PUB_KEY_PARAMS (ES256, EdDSA, RS256, ES384, RS384) in WebAuthn4JConverters.
• No way to report which stored credentials use which algorithm.
• No post-quantum/crypto-agility documentation anywhere.

Changes

1. One injectable source of truth for COSE algorithms

• New framework-neutral CoseAlgorithm enum.
• CeremonyConfig now carries offeredAlgorithms (advertised in create-options) and acceptedAlgorithms (enforced on verify). Both the create-options ceremony and the WebAuthn4J verify path derive their lists from this config — the two hardcoded lists are removed.
• acceptedAlgorithms is authoritative; offeredAlgorithms must be a subset and may be narrower. Operators can narrow either without code changes.
• Backward-compatible defaults: accepted = the union of everything historically accepted (ES256, EdDSA, RS256, ES384, RS384); offered = the historical create subset (ES256, EdDSA, RS256). A new 5-arg CeremonyConfig convenience constructor keeps every existing call site compiling and behaving identically.

2. Per-credential algorithm visibility (no schema change)

• CredentialAlgorithms.coseAlgorithm(record) decodes the COSE algorithm already embedded in the stored public key.
• AdminService.listCredentialsByAlgorithm(actor, target, coseAlgorithm) reports which credentials use a given (e.g. quantum-vulnerable) algorithm — the read side a future re-enrollment campaign drives off.

3. Honest JWT framing (docs/comments only)

• Replaced the misleading "HS256 dev / ES256 production" framing in pk-auth-jwt package-info and JwtKeyset.hs256: HMAC-SHA256 with a ≥256-bit key is not Shor-broken (~128-bit under Grover) and is the quantum-conservative choice for a single-issuer/single-verifier deployment; ES256 exists for untrusted third-party verification and is Shor-vulnerable but bounded by the short token TTL. No signing behavior or defaults changed.

4–6. Docs

• docs/threat-model.md: new Post-quantum readiness section (Shor-vulnerable signatures gated by hardware/CTAP/WebAuthn/COSE/WebAuthn4J; why exposure is bounded; the crypto-agility hooks; symmetric secrets already 256-bit/Grover-resistant).
• docs/operator-guide.md: new Transport security & post-quantum section — the genuine harvest-now/decrypt-later risk is recorded TLS sessions; recommend a hybrid PQC KEM (e.g. X25519MLKEM768) at the TLS terminator/CDN. Framed explicitly as an operator action, not a library change.
• BackupCodeService: short comment noting ~50-bit code entropy and that CODE_LENGTH is the lever (default unchanged).

7. ADR

• docs/adr/0019-crypto-agility-post-quantum-readiness.md (+ README index row).

Tests

• DefaultPasskeyAuthenticationServiceAlgorithmTest — (a) defaults still offer/accept the historical algorithms, (b) a custom config flows into both create options and verify params, (c) an algorithm absent from config is excluded from the verify params (so WebAuthn4J rejects it).
• CredentialAlgorithmsTest — decode ES256 from a stored key; undecodable key throws.
• DefaultAdminServiceTest — listCredentialsByAlgorithm matching/empty + authorization.

Verification

./gradlew check passes (spotless + tests + JaCoCo coverage gates), Docker available for the Testcontainers persistence suites.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud