Passkeys

Status: Accepted (2026-09-15) · Amends: ADR-0024, ADR-0043

Context#

ADR-0024 puts passkeys in v0.3: WebAuthn registration and sign-in, a configured relying-party ID and allowed origins, passkeys counting as a strong second factor, and apple-app-site-association and assetlinks.json for native apps. ADR-0043 built two-factor authentication with TOTP, a sign-in challenge (POST /v1/auth/login → 202 → POST /v1/auth/login/mfa), sessions verified with a second factor, and roles that require one.

Threat model row 16 (passkey phishing or origin confusion) is addressed by validating the relying-party ID and allowed origins. TOTP stays phishable; passkeys are the factor that isn't.

Three choices were made with the maintainer (2026-09-15):

Options#

WebAuthn implementation#

Option 1, isolated behind a package so apps never import its types (threat 22).

Decision#

Who owns what (as ADR-0038)#

It is a separate package of the modules/auth module, so apps that don't import it don't compile it.

Configuration (environment)#

• The display name is the app's ServiceName.
• LoadConfig checks that every origin is https (or http://localhost in development) and that its host is the RP ID or a subdomain of it; the library checks the rest when it starts.
• Without WEBAUTHN_RP_ID in production, passkeys are unavailable (503 passkeys_unavailable); the rest of the app runs. Passkeys are optional per deployment, unlike AUTH_ENCRYPTION_KEYS.
• Android apps become allowed origins (android:apk-key-hash:<base64url of the certificate SHA-256>), derived from WEBAUTHN_ANDROID_APPS.
• What developers provide, where they get each value, and how the app reports what's configured (the .env.example block, AUTH_PROVIDERS.md, the Sign-in methods status at start, auth-providers and GET /ops/auth/providers) follow ADR-0045.

Native app association files#

Otherwise both are 404. The files must be reachable on the RP ID's domain; when that domain is a separate web frontend, it proxies or copies them (documented).

Tables#

Registering a passkey#

At most 10 passkeys per user (409 passkey_limit_reached).

Signing in#

Passwordless. POST /v1/auth/passkeys/login/options (public) returns a ceremony_token and options for navigator.credentials.get() with no allowed credentials (a discoverable sign-in) and user verification required. POST /v1/auth/passkeys/login takes the ceremony_token, credential and transport, finds the account by user handle and credential ID, and returns 200 with a session verified with a second factor, like POST /v1/auth/login/mfa. The account must have a verified email. Unknown credentials, wrong signatures, a missing user-verification flag, expired or used ceremonies, and deleted accounts all return 401 invalid_passkey.

Second factor. For a user with passkeys, the 202 challenge from POST /v1/auth/login lists passkey in methods. POST /v1/auth/login/mfa/passkey takes the challenge_token and returns a ceremony_token and options limited to that user's passkeys; POST /v1/auth/login/mfa then accepts {"challenge_token", "passkey": {"ceremony_token", "credential"}, "transport"}. Failures count as challenge attempts, as with codes (ADR-0043).

Rules#

Audit actions and emails#

auth.passkey.registered, auth.passkey.renamed, auth.passkey.removed, auth.login.succeeded (metadata method: passkey), auth.login.failed (reason invalid_passkey), auth.mfa.challenge_succeeded (method passkey), auth.passkey.clone_warning. Credential IDs are recorded as the passkey's row ID, never the raw credential. Emails: passkey added, passkey removed.

Error codes#

invalid_passkey (401), passkey_not_found (404), passkey_limit_reached (409), passkeys_unavailable (503); mfa_required_by_role (409) and invalid_mfa (401) as in ADR-0043.

Why#

• Passkeys resist phishing: the browser binds each signature to the origin, and the server checks the RP ID and origins it was configured with.
• Environment configuration keeps the phishing-relevant part of passkeys out of reach of a compromised ops account (threat 23).
• A maintained library for WebAuthn's parsing and verification is safer than new cryptographic code; wrapping it keeps apps free of its types and its churn.
• Treating a passkey sign-in as verified lets ops users drop TOTP entirely.
• A software authenticator in tests exercises the real verification path instead of mocks.

Trade-offs#

• Seven more modules in modules/auth's graph, compiled only into apps that import passkey.
• Browsers need HTTPS or localhost, and the RP ID can't be an IP address: http://127.0.0.1:8080 can't use passkeys in development; use http://localhost:8080.
• Rejecting a counter that goes backwards can lock out an authenticator with a buggy counter; the user signs in another way and removes it.
• Association files on a domain the API doesn't serve need the frontend's help.
• No seed passkey: registering one needs a browser or device.

Consequences#

• modules/auth/passkey and passkeytest (public API, ADR-0015); modules/auth gains SendPasskeyAdded and SendPasskeyRemoved emails.
• The Full preset gains a migration, repository files, use cases, endpoints, the .well-known routes, WEBAUTHN_* in .env.example, and tests for registration, both sign-in paths, exclusions, limits, counters, the last-factor rule and the association files.
• ADR-0043's "two-factor authentication on" becomes TOTP or passkeys; reset-mfa removes passkeys too.
• Threat model row 16 is addressed when this ships.

Amendment: confirming the user (2026-09-15)#

A principal-engineer review before merge found that a session stayed "verified with a second factor" for its whole life. A stolen session verified weeks earlier could register the attacker's passkey without the password, and the passkey outlived password reset and logout-all. Accounts with only passkeys also had no way to give a second factor outside sign-in, so deleting the account needed a recovery code.

Rate limits stay per instance (ADR-0043); limits shared across instances are a v1.0 hardening item.

Implementation notes (2026-09-15)#

• modules/auth/passkey adds seven modules to modules/auth's graph (fxamacker/cbor, go-viper/mapstructure, go-webauthn/x, golang-jwt/jwt, google/go-tpm, google/uuid, tinylib/msgp) and rsc.io/qr for authenticator app QR codes; all tests and lint pass on Go 1.26.
• The library's credential record and ceremony state are stored as jsonb and passed back unchanged; the app never parses them.
• Two-factor authentication is on with a confirmed authenticator app or at least one passkey: sign-in challenges list only the methods this server can check (totp needs AUTH_ENCRYPTION_KEYS, passkey needs WEBAUTHN_RP_ID), plus recovery_code.
• Turning the authenticator app off keeps the recovery codes while a passkey remains; removing the last second factor deletes them.
• Replacing recovery codes, account deletion and turning the authenticator app off take a passkey response too (see Amendment).
• auth_cleanup removes ceremonies once they expire.
• A failed passkey sign-in records auth.login.failed with reason invalid_passkey; a successful one records auth.login.succeeded with mfa_method: passkey.