ADR 0014: Passkeys as second factor with a minimal WebAuthn implementation¶
- Status: Accepted
- Date: 2026-11-12
- Extends: ADR 0009
Context¶
TOTP codes (ADR 0009) work everywhere but have to be typed. Passkeys (WebAuthn) are faster and phishing-resistant: the browser binds the signature to the origin (#39).
Decision¶
- Passkeys are an additional second factor: after the correct password
the login answers
202with a single-use ticket and a challenge; the browser signs it with one of the account's passkeys (POST /api/auth/passkeys/login). TOTP and recovery codes keep working as alternatives. An account whose only second factor is a passkey gets recovery codes with its first passkey. Without TOTP set up, six-digit codes are never accepted (only recovery codes). - Owner and guests can register up to 10 passkeys each (Settings → Account).
- Own minimal implementation in
internal/platform/webauthn(standard library only, ~400 lines incl. a bounded CBOR decoder) instead ofgo-webauthn/webauthn, whose dependency tree (CBOR, TPM, JWT libraries) conflicts with ADR 0011. Scope: attestationnoneis requested and attestation statements are not evaluated (no enterprise attestation needed for a home start page); algorithms ES256, EdDSA and RS256; checks of ceremony type, challenge, origin, RP ID hash, user presence and the signature; signature counters must increase (clone detection), counters of 0 are accepted for authenticators without counters. - WebAuthn needs a fixed origin and a secure context: passkeys are only
offered when
PUBLIC_URLis set to anhttps://origin (orhttp://localhost). Behind a plainhttp://<ip>:8090they stay disabled with an explanation in the settings. - The browser API is isolated in
web/src/features/auth/adapter/browser; use cases and UI stay testable withoutnavigator.credentials.
Consequences¶
- No new dependency; the implementation is covered by tests with a simulated authenticator (accepted ceremonies for ES256/EdDSA, rejected wrong challenge, phishing origin, foreign RP ID, missing user presence, tampered data, wrong ceremony type, foreign key, CBOR bombs) and an end-to-end test over HTTP.
- Passwordless login (passkey without password) is a possible follow-up; the ticket design keeps the password as first factor for now.