Passkeys: Security protocol

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 attestation choice.
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: preferred when discoverable login is desired.
Align rpId with 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.yaml to 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.yaml are an adoption profile, not universal defaults.
Teams must choose attestation, UV, and recovery policies appropriate to their threat model.