docs: add WebAuthn passkey auth roadmap

[larimonious]

Summary

• Adds a post-v0.4.9 WebAuthn/passkeys phase to DD-043 after PR 3 and the template integration proof
• Breaks the phase into four recommended PRs: foundation/storage, registration helpers, authentication/session completion, and template UX/policy hardening
• Records key security constraints: server-side ceremony state, credential-ID uniqueness, sign-counter handling, RP/origin config, non-PII user handles, and optional attestation policy

Verification

• git diff --check
• cargo fmt -- --check
• cargo test auth -- --test-threads=1

Notes

• WebAuthn/passkeys are explicitly post-v0.4.9 and should not delay the password reset + template proof work.
• NTNT_AUTH_TEST_POSTGRES_URL and NTNT_AUTH_TEST_REDIS_URL were set during auth test verification.

[greptile-apps]

Greptile Summary

This PR appends a post-v0.4.9 WebAuthn/passkey phase to DD-043, decomposed into four WA-PRs covering foundation/storage, registration helpers, authentication/session completion, and template UX/policy hardening. The security constraints recorded (server-side ceremony state, credential-ID uniqueness, sign-counter rejection semantics, RP/origin config, non-PII user handles, and optional attestation) are consistent with the WebAuthn Level 2 spec and webauthn-rs design. Previously raised issues — sign-counter reject semantics, WA-PR/PR 3 naming collision, and the missing req on begin_passkey_authentication — are all correctly resolved in this diff.

Confidence Score: 5/5

Documentation-only change; safe to merge.

No P0 or P1 findings. The design posture is spec-conformant (server-side ceremony state, counter rejection semantics, credential-ID uniqueness, non-PII user handles). Previously reviewed issues are fully addressed. No code is introduced.

No files require special attention.

Important Files Changed

Filename	Overview
design-docs/dd-043-auth-excellence.md	Adds ~100-line WebAuthn/passkeys roadmap section with four WA-PRs, updated Done Criteria, and Advanced Refinements stub; all previously flagged issues resolved correctly.

Sequence Diagram

sequenceDiagram
    participant Browser
    participant App
    participant std/auth WebAuthn
    participant ServerStorage

    Note over Browser,ServerStorage: WA-PR 2 — Passkey Registration
    Browser->>App: POST /passkey/register/begin
    App->>std/auth WebAuthn: begin_passkey_registration(req, user)
    std/auth WebAuthn->>ServerStorage: store ceremony state (TTL, one-time)
    std/auth WebAuthn-->>App: PublicKeyCredentialCreationOptions
    App-->>Browser: JSON creation options
    Browser->>Browser: navigator.credentials.create({ publicKey })
    Browser->>App: POST /passkey/register/finish (credential response)
    App->>std/auth WebAuthn: finish_passkey_registration(req, credential_response)
    std/auth WebAuthn->>ServerStorage: consume ceremony state (replay check)
    std/auth WebAuthn->>ServerStorage: enforce credential-ID uniqueness
    std/auth WebAuthn->>ServerStorage: store passkey record
    std/auth WebAuthn-->>App: Result<Map, String>

    Note over Browser,ServerStorage: WA-PR 3 — Passkey Authentication
    Browser->>App: POST /passkey/auth/begin
    App->>std/auth WebAuthn: begin_passkey_authentication(req, identifier?)
    std/auth WebAuthn->>ServerStorage: store challenge state (TTL, one-time)
    std/auth WebAuthn-->>App: PublicKeyCredentialRequestOptions
    App-->>Browser: JSON request options
    Browser->>Browser: navigator.credentials.get({ publicKey })
    Browser->>App: POST /passkey/auth/finish (assertion response)
    App->>std/auth WebAuthn: finish_passkey_authentication(req, credential_response)
    std/auth WebAuthn->>ServerStorage: consume challenge state
    std/auth WebAuthn->>ServerStorage: validate sign counter (reject if equal/lower non-zero)
    std/auth WebAuthn->>ServerStorage: update counter + last-used
    std/auth WebAuthn-->>App: Result<Map, String> (subject/session data)
    App->>std/auth WebAuthn: sign_in_session(response, req, session)
    std/auth WebAuthn-->>Browser: session cookie (rotation/migration applied)

Loading

_{Reviews (5): Last reviewed commit: "docs: align passkey finish helper shape" | Re-trigger Greptile}