WebAuthn passkey registration binds credentials to the authenticated account with discoverable ceremony options, bounded challenges, and recovery paths that do not promise private-key extraction.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Offer passkeys through standards-aligned WebAuthn ceremonies after primary authentication, store only public credential material server-side, enforce challenge expiry, treat authenticator counters as risk signals when available, and handle recovery by re-establishing trust—not by exporting private keys.
Scope
- Registration and authentication ceremonies for browser clients against a relying party ID.
- Credential lifecycle states, revocation, duplicate handling, and discoverable credential login.
- User-facing enrollment prompts, labeling of synced passkeys, and honest recovery copy.
- Rate limits and audit signals for failed ceremonies.
Outside this block
- Password hashing, session cookie mechanics, or OAuth federation (see related session blocks).
- Enterprise attestation policy beyond the profile
attestationchoice. - Hardware security module provisioning or custom authenticator firmware.
Contract
- Registration challenges are issued only to an already authenticated session unless a documented recovery flow explicitly elevates trust first.
- Challenges expire after the profile TTL; expired challenges never create credentials.
- Stored credentials record credential ID, public key, sign count, transports, and backup state; private keys never touch server storage.
- Successful authentication records the authenticator counter when it is supported. A nonzero counter that does not increase is a possible clone signal handled by the profile risk policy; authenticators that report zero are not rejected solely for lacking a usable counter.
- Duplicate registration with the same credential ID is idempotent and does not create a second active row.
- Recovery without a passkey uses the profile path (for example email plus MFA or backup codes) and may register a new passkey afterward; copy must not imply passkey secrets can be downloaded or emailed.
- Recovery records a reason. A lost-device path may retain other credentials under the profile policy; suspected compromise follows a separate path that freezes or revokes affected credentials and, by default, revokes all prior passkeys before new enrollment.
- When step-up is required to add a passkey, user verification must succeed or the credential is discarded.
- Revoked credentials fail authentication immediately even if the client still holds the private key material locally.
Implementation guidance
- Follow W3C WebAuthn Level 3 ceremony shapes; prefer
residentKey: preferredwhen discoverable login is desired. - Align
rpIdwith the effective registrable domain; document any subdomain exceptions explicitly. - Surface FIDO-aligned guidance that synced passkeys depend on platform providers, not application-exportable secrets.
- Keep counter-anomaly handling separate from assertion verification. The response may require step-up, suspend the credential, or open review according to the threat profile, but must not claim that every unchanged counter proves replay.
- Map states in
passkey-states.yamlto observability events for support tooling.
Failure handling and safeguards
- On verification failure, do not leak whether a credential ID exists; use generic errors at the UI layer with detailed codes in logs.
- On authenticator cancel, return a recoverable client error without counting as a server-side failure.
- Do not collapse loss and compromise into one recovery switch. A lost-only event may retain independently held credentials, while suspected account or authenticator compromise defaults to revoking all prior passkeys and sessions defined by the incident profile.
- Rate-limit registration attempts per account and IP to slow enumeration and harassment.
Verification and operations
- Monitor ceremony success, expiry, counter anomalies, policy responses, and recovery enrollments.
- Run conformance tests against a virtual authenticator in CI for happy path and TTL expiry.
- Review UX copy quarterly so it does not over-promise recovery of passkey secrets.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - Teams must choose attestation, UV, and recovery policies appropriate to their threat model.