feat(auth): B-2.6 WebAuthn / Passkey support (FIDO2 + biometric 2FA)
Adds phishing-resistant 2nd factor via FIDO2 hardware keys (YubiKey etc.) and device biometrics (Touch ID, Windows Hello, etc.). Reuses the existing B-2.5 TOTP gate so a passkey is a 3rd valid option on /2fa/verify, alongside TOTP code and recovery code. Post-login enrolment lives at /2fa/passkey/setup. Wraps python-webauthn==2.5.2 in a thin service layer (src/auth/webauthn.py) that persists credentials in the existing User.webauthn_credentials JSON column (added in B-2.1 — no schema change). Each credential dict carries id, public_key, sign_count, transports, name, and created_at. sign_count is updated after every successful authentication for WebAuthn anti-cloning (§6.1.1). Backend: 6 new auth routes (passkey_setup, register/begin, register/finish, delete, auth/begin, auth/finish). The 4 JSON endpoints are CSRF-exempt at Flask-WTF level because CSRFProtect cannot read tokens from a JSON body without app-wide config; the X-CSRFToken header is still sent as defence-in-depth. The form-POST delete route DOES enforce CSRF. The @csrf_exempt decorator was previously a no-op label; init_auth_extensions now walks module-level functions and applies real csrf.exempt() to any flagged with _csrf_exempt=True. Login gate now fires when the user has TOTP enabled OR at least one passkey, and totp_verify_login passes has_passkeys + has_totp flags so the template can show only the relevant sections. Frontend: templates/auth/totp_verify.html updated IN PLACE with a passkey button section (above TOTP) and an "ou" divider. New templates/auth/passkey_setup.html for managing/enrolling passkeys. New static/js/webauthn-client.js (no external deps, ES2020) wraps navigator.credentials and exchanges base64url payloads with the backend. Tailwind CSS rebuilt. Tests: 22 new tests in tests/test_webauthn_passkey.py covering the service layer (b64url helpers, RP config, list/has, begin/finish for both registration and authentication, delete) and the route flow (CSRF-exempt JSON endpoints, login gate redirection, sign_count anti-cloning persistence). Mocks python-webauthn's verify_* functions so tests run without a real authenticator. Windows manual driver follows the existing no-conftest pattern. Self-review: 22/22 new tests pass; 21/21 prior TOTP, 16/16 email, 21/21 OAuth tests still pass (no regression). Env: config/env.oauth.example documents WEBAUTHN_RP_ID, WEBAUTHN_RP_NAME, WEBAUTHN_ORIGIN with full deployment notes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -67,3 +67,35 @@
|
||||
# - 15-minute expiry, signed with SECRET_KEY + salt 'magic-link-login'
|
||||
# - No DB column — tokens are not single-use within the 15-min window
|
||||
# - SMTP must be configured (see env.email.example) for the link to send
|
||||
|
||||
###############################################################################
|
||||
# WebAuthn / Passkey (B-2.6)
|
||||
###############################################################################
|
||||
# Phishing-resistant 2nd factor via FIDO2 hardware keys (YubiKey etc.) and
|
||||
# device biometrics (Touch ID, Windows Hello). Browsers strictly enforce that
|
||||
# the values below match the page making the WebAuthn API call:
|
||||
#
|
||||
# - WEBAUTHN_RP_ID : the registrable host name (NO scheme, NO port). Must
|
||||
# match the eTLD+1 of the page or be a parent domain. For dictia.ca use
|
||||
# 'dictia.ca'; for staging at app.staging.dictia.ca use 'dictia.ca' or
|
||||
# 'staging.dictia.ca'. Defaults to 'localhost' for local development.
|
||||
#
|
||||
# - WEBAUTHN_RP_NAME : the display name shown to the user inside their
|
||||
# authenticator's prompt (e.g. 'Sign in to DictIA'). Defaults to 'DictIA'.
|
||||
#
|
||||
# - WEBAUTHN_ORIGIN : the FULL origin including scheme + host + optional
|
||||
# port. MUST equal window.location.origin on the client side. Mismatches
|
||||
# are rejected by the browser before the request even reaches the server.
|
||||
# Defaults to 'http://localhost:8899' for local development.
|
||||
#
|
||||
# Credentials are persisted in user.webauthn_credentials (JSON column,
|
||||
# added in B-2.1). Each credential dict contains base64url id, public_key,
|
||||
# sign_count (anti-cloning per WebAuthn §6.1.1), transports, name, and
|
||||
# created_at. The 4 JSON endpoints (register/begin, register/finish,
|
||||
# auth/begin, auth/finish) are CSRF-exempt at Flask-WTF level because
|
||||
# CSRFProtect cannot read tokens from a JSON body without app-wide config.
|
||||
# An X-CSRFToken header is still sent by the client as defence-in-depth.
|
||||
#
|
||||
# WEBAUTHN_RP_ID=dictia.ca
|
||||
# WEBAUTHN_RP_NAME=DictIA
|
||||
# WEBAUTHN_ORIGIN=https://dictia.ca
|
||||
|
||||
Reference in New Issue
Block a user