roledesk is built on the boilerplate from here on: pipeline 2.0 (queue and scheduler), auth (one password, sessions, passkeys), the deploy kit and its docs, plus the coupling and packaging tests. Downstream copies, unedited. Refreshed from boilerplate/d56949f7d0f6c0bfe5745478e09007bfad67ae87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
399 lines
18 KiB
Python
399 lines
18 KiB
Python
"""WebAuthn: the two ceremonies, and the three things that decide whether they
|
|
can run at all.
|
|
|
|
A passkey and a YubiKey are the same feature. Both are WebAuthn authenticators;
|
|
the difference is only where the private key lives — in the phone's secure
|
|
enclave, in the browser profile, or on a stick in a USB port — and none of that
|
|
reaches this module. One registration flow covers all of them, which is why
|
|
there is no "YubiKey" anywhere in this package.
|
|
|
|
## What this is worth having
|
|
|
|
A password can be typed into the wrong site. A passkey cannot: the browser will
|
|
only hand a credential back to the origin it was created for, and it checks
|
|
that itself, before anything of ours runs. That property is the whole reason
|
|
this exists, and it is also the reason for every constraint below — the binding
|
|
to an origin is not a detail to be relaxed when it is inconvenient.
|
|
|
|
## The three things that can stop it
|
|
|
|
**The package.** `webauthn` is an optional extra, so every import of it is
|
|
inside a function and `available()` is what the account screen asks before
|
|
offering a button. A missing extra is a sentence about `uv sync`, not a 500.
|
|
|
|
**The origin.** WebAuthn refuses to run on an insecure origin — `localhost` is
|
|
specifically exempted, everything else needs HTTPS. So an app served over plain
|
|
HTTP on a LAN address can hold passkeys and verify them, and cannot register
|
|
one, and the account screen says so rather than showing a button that fails
|
|
inside the browser with an error nobody surfaces.
|
|
|
|
**The RP ID.** Derived from the request's `Host` when `rp_id` is blank, which
|
|
is right on a laptop and wrong the moment anything can forge that header. See
|
|
`AuthConfig.rp_id` for why production pins it.
|
|
|
|
## The password does not go away
|
|
|
|
Registering a passkey does not remove the password, and this module offers no
|
|
way to. A lost key with no fallback is an app nobody can reach — and the
|
|
recovery path for that would have to be at least as strong as the password it
|
|
replaced, which is to say: the password.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import logging
|
|
from typing import Any
|
|
from urllib.parse import urlsplit
|
|
|
|
from starlette.requests import Request
|
|
|
|
from auth.config import AuthConfig
|
|
from auth.store import AuthStore
|
|
|
|
log = logging.getLogger(__name__)
|
|
|
|
#: The one user's handle. A constant, and deliberately so: WebAuthn wants a
|
|
#: user id to tell accounts apart, and there is one account. Making it random
|
|
#: per install would buy nothing — two apps cannot share an RP ID, since the RP
|
|
#: ID *is* the domain — and would cost a stable value to store and migrate. It
|
|
#: is also not PII, which the spec asks of this field.
|
|
#:
|
|
#: One real consequence, and it is the one you want: re-registering on the same
|
|
#: authenticator replaces the resident credential rather than adding a second,
|
|
#: because (rp_id, user_handle) is what a discoverable credential is keyed on.
|
|
USER_HANDLE = b"app"
|
|
|
|
#: What the authenticator shows in its own list, beside `rp_name`. Not a login
|
|
#: — there is no username here — but the field is required and something has to
|
|
#: be in it.
|
|
USER_NAME = "app"
|
|
|
|
#: How to get the extra, said once and reused by every message that says it.
|
|
#:
|
|
#: The parenthetical is not padding. `uv sync --extra passkeys` *replaces* the
|
|
#: installed extras rather than adding to them, so running exactly what the
|
|
#: obvious instruction says will silently uninstall whatever else the project
|
|
#: uses — and the symptom of that is not an error at install time, it is
|
|
#: something unrelated failing later on. Anyone following this instruction is by
|
|
#: definition not thinking about their other extras, which is exactly when they
|
|
#: need to be told.
|
|
INSTALL_HINT = ("Run `uv sync --extra passkeys`, listing any other extras you "
|
|
"use in the same command — uv replaces the set rather than "
|
|
"adding to it — then restart.")
|
|
|
|
|
|
def available() -> bool:
|
|
"""Whether the `passkeys` extra is installed."""
|
|
try:
|
|
import webauthn # noqa: F401
|
|
except ImportError:
|
|
return False
|
|
return True
|
|
|
|
|
|
def warn_if_missing(store: AuthStore) -> None:
|
|
"""Say so at startup if there are passkeys here that cannot be used.
|
|
|
|
The case this exists for: `uv sync` without `--extra passkeys` quietly
|
|
removes the package, and the next start has registered keys it cannot
|
|
verify. Without this the first sign anything is wrong is a login page with
|
|
no passkey button on it — which looks like the passkeys were lost, when they
|
|
are sitting in the database intact.
|
|
|
|
Silent when nothing is registered, because then there is nothing to lose and
|
|
nothing to warn about: an install with no passkeys and no `webauthn` is just
|
|
an install that does not use passkeys.
|
|
"""
|
|
if available():
|
|
return
|
|
registered = store.passkey_ids()
|
|
if not registered:
|
|
return
|
|
log.warning(
|
|
"%d passkey(s) are registered but the `passkeys` extra is not "
|
|
"installed, so they cannot be used. They are still stored and nothing "
|
|
"is lost. %s Until then, sign in with the password.",
|
|
len(registered), INSTALL_HINT,
|
|
)
|
|
|
|
|
|
def rp_id(config: AuthConfig, request: Request) -> str:
|
|
"""The domain to bind credentials to.
|
|
|
|
The configured value wins. Falling back to the request's host is what makes
|
|
development work without configuration — and is why the config docstring
|
|
says to pin it in production, since `Host` arrives from the client.
|
|
"""
|
|
if config.rp_id:
|
|
return config.rp_id
|
|
return request.url.hostname or "localhost"
|
|
|
|
|
|
def origin(config: AuthConfig, request: Request) -> str:
|
|
"""The exact origin the browser must be at, scheme and port included.
|
|
|
|
Derived from the request when unset, which is right when the app is the
|
|
thing the browser connected to and wrong behind a proxy that terminated TLS
|
|
— there this derives `http://` and every ceremony fails verification with an
|
|
origin mismatch. That is the failure `AuthConfig.origin` exists for.
|
|
"""
|
|
if config.origin:
|
|
return config.origin.rstrip("/")
|
|
url = request.url
|
|
port = f":{url.port}" if url.port not in (None, 80, 443) else ""
|
|
return f"{url.scheme}://{url.hostname}{port}"
|
|
|
|
|
|
def blocked(config: AuthConfig, request: Request) -> str:
|
|
"""Why a passkey cannot be *registered* from this request, or "".
|
|
|
|
Registration is the half that needs a secure context; verification does not,
|
|
because by then the browser has already done its own checks. So this is
|
|
asked when the account screen renders, not when a login is attempted.
|
|
"""
|
|
if not available():
|
|
return f"Passkeys need the `passkeys` extra, which is not installed. {INSTALL_HINT}"
|
|
where = origin(config, request)
|
|
host = urlsplit(where).hostname or ""
|
|
# The exact rule browsers apply: HTTPS anywhere, or HTTP on loopback.
|
|
# `.localhost` is in the same boat by RFC 6761 and Chrome honours it.
|
|
secure = (where.startswith("https://") or host == "localhost"
|
|
or host.endswith(".localhost") or host == "127.0.0.1" or host == "::1")
|
|
if not secure:
|
|
return (f"Passkeys need HTTPS. This app is being served at {where}, and "
|
|
f"a browser will not create one on an insecure origin. Put TLS "
|
|
f"in front of it, then set `auth.origin` in config.yaml.")
|
|
return ""
|
|
|
|
|
|
# -------------------------------------------------------------- registration
|
|
|
|
def register_options(config: AuthConfig, request: Request,
|
|
store: AuthStore) -> dict[str, Any]:
|
|
"""The challenge for adding a passkey, as the browser's `create()` wants it.
|
|
|
|
`exclude_credentials` is every key already registered, which is what makes
|
|
an authenticator say "you already have one of these" instead of quietly
|
|
creating a second credential that `add_passkey` would then reject on the
|
|
unique index — an error at the end of a ceremony you had already touched the
|
|
key for.
|
|
"""
|
|
from webauthn import generate_registration_options, options_to_json
|
|
from webauthn.helpers.structs import (
|
|
AuthenticatorSelectionCriteria, PublicKeyCredentialDescriptor,
|
|
ResidentKeyRequirement, UserVerificationRequirement,
|
|
)
|
|
|
|
options = generate_registration_options(
|
|
rp_id=rp_id(config, request),
|
|
rp_name=config.rp_name,
|
|
user_id=USER_HANDLE,
|
|
user_name=USER_NAME,
|
|
user_display_name=config.rp_name,
|
|
exclude_credentials=[PublicKeyCredentialDescriptor(id=cid)
|
|
for cid in store.passkey_ids()],
|
|
authenticator_selection=AuthenticatorSelectionCriteria(
|
|
# `preferred`, not `required`: a resident (discoverable) credential
|
|
# is what lets the login page offer "use a passkey" with nothing
|
|
# typed first, and it is worth asking for. Requiring it would turn
|
|
# away older security keys that have no room to store one, and a
|
|
# key that works as a second factor is still worth having.
|
|
resident_key=ResidentKeyRequirement.PREFERRED,
|
|
# Likewise: ask for a PIN or a fingerprint, do not insist. Insisting
|
|
# locks out keys with no PIN set, for a property the password behind
|
|
# this does not have either.
|
|
user_verification=UserVerificationRequirement.PREFERRED,
|
|
),
|
|
)
|
|
store.remember_challenge(options.challenge, "register")
|
|
return json.loads(options_to_json(options))
|
|
|
|
|
|
def register_verify(config: AuthConfig, request: Request, store: AuthStore,
|
|
credential: dict[str, Any], label: str) -> int:
|
|
"""Check what the authenticator sent back and keep it. Returns the row id.
|
|
|
|
Raises `PasskeyError` with a sentence fit to show, because every failure
|
|
here is either a stale ceremony or a misconfigured origin, and both have a
|
|
specific thing to do about them.
|
|
"""
|
|
from webauthn import verify_registration_response
|
|
from webauthn.helpers.exceptions import (
|
|
InvalidRegistrationResponse, WebAuthnException,
|
|
)
|
|
|
|
challenge = _challenge_from(credential)
|
|
if not store.take_challenge(challenge, "register"):
|
|
raise PasskeyError("That registration took too long, or was already "
|
|
"used. Press Add a passkey and try again.")
|
|
try:
|
|
verified = verify_registration_response(
|
|
credential=credential,
|
|
expected_challenge=challenge,
|
|
expected_rp_id=rp_id(config, request),
|
|
expected_origin=origin(config, request),
|
|
)
|
|
except InvalidRegistrationResponse as exc:
|
|
raise PasskeyError(_explain(exc, config, request)) from None
|
|
except (WebAuthnException, ValueError) as exc:
|
|
raise PasskeyMalformed(_malformed(exc)) from None
|
|
|
|
transports = ",".join(
|
|
t if isinstance(t, str) else t.value
|
|
for t in (credential.get("response", {}).get("transports") or []))
|
|
return store.add_passkey(
|
|
credential_id=verified.credential_id,
|
|
public_key=verified.credential_public_key,
|
|
sign_count=verified.sign_count,
|
|
transports=transports,
|
|
label=label or "Passkey",
|
|
)
|
|
|
|
|
|
# ---------------------------------------------------------------- signing in
|
|
|
|
def login_options(config: AuthConfig, request: Request,
|
|
store: AuthStore) -> dict[str, Any]:
|
|
"""The challenge for signing in.
|
|
|
|
`allow_credentials` lists what is registered, which is what makes a security
|
|
key light up rather than the browser asking the user to pick from nothing.
|
|
For a discoverable credential it is redundant; for a key registered without
|
|
one it is the only thing that works.
|
|
"""
|
|
from webauthn import generate_authentication_options, options_to_json
|
|
from webauthn.helpers.structs import (
|
|
PublicKeyCredentialDescriptor, UserVerificationRequirement,
|
|
)
|
|
|
|
options = generate_authentication_options(
|
|
rp_id=rp_id(config, request),
|
|
allow_credentials=[PublicKeyCredentialDescriptor(id=cid)
|
|
for cid in store.passkey_ids()],
|
|
user_verification=UserVerificationRequirement.PREFERRED,
|
|
)
|
|
store.remember_challenge(options.challenge, "login")
|
|
return json.loads(options_to_json(options))
|
|
|
|
|
|
def login_verify(config: AuthConfig, request: Request, store: AuthStore,
|
|
credential: dict[str, Any]) -> int:
|
|
"""Check a signature against a registered key. Returns the passkey's id.
|
|
|
|
Raises `PasskeyError` on anything that is not a good signature from a key
|
|
this app knows.
|
|
"""
|
|
from webauthn import verify_authentication_response
|
|
from webauthn.helpers import base64url_to_bytes
|
|
from webauthn.helpers.exceptions import (
|
|
InvalidAuthenticationResponse, WebAuthnException,
|
|
)
|
|
|
|
challenge = _challenge_from(credential)
|
|
if not store.take_challenge(challenge, "login"):
|
|
raise PasskeyError("That sign-in took too long, or was already used. "
|
|
"Try again.")
|
|
|
|
known = store.passkey_for(base64url_to_bytes(credential.get("rawId", "")))
|
|
if known is None:
|
|
# Deliberately the same sentence as a bad signature. There is one user,
|
|
# so this leaks little, but "that key is not registered" is an oracle
|
|
# for enumerating keys and costs nothing to withhold.
|
|
raise PasskeyError("That passkey is not registered here.")
|
|
passkey_id, public_key, stored_count = known
|
|
|
|
try:
|
|
verified = verify_authentication_response(
|
|
credential=credential,
|
|
expected_challenge=challenge,
|
|
expected_rp_id=rp_id(config, request),
|
|
expected_origin=origin(config, request),
|
|
credential_public_key=public_key,
|
|
credential_current_sign_count=stored_count,
|
|
)
|
|
except InvalidAuthenticationResponse as exc:
|
|
raise PasskeyError(_explain(exc, config, request)) from None
|
|
except (WebAuthnException, ValueError) as exc:
|
|
raise PasskeyMalformed(_malformed(exc)) from None
|
|
|
|
# The clone check — a counter that goes backwards means two authenticators
|
|
# are answering for one credential — is the library's, not ours: it is
|
|
# inside `verify_authentication_response`, which is handed the stored count
|
|
# above and raises before returning. All that is left to do is translate its
|
|
# message; see `_explain`.
|
|
store.record_passkey_use(passkey_id, verified.new_sign_count)
|
|
return passkey_id
|
|
|
|
|
|
# -------------------------------------------------------------------- helpers
|
|
|
|
class PasskeyError(Exception):
|
|
"""A ceremony that did not complete, with a sentence worth showing."""
|
|
|
|
|
|
class PasskeyMalformed(PasskeyError):
|
|
"""A body that was never a ceremony — the caller's mistake, not a refusal.
|
|
|
|
The distinction is only worth making at the login route, where a
|
|
`PasskeyError` is a 401 because something was wrong with the *credential*.
|
|
Nothing about a request missing half its fields says a credential was
|
|
refused, and answering 401 to it invites a retry of a request that cannot
|
|
ever work. It is a subclass so that anywhere the difference does not matter
|
|
— registering, behind a session — one `except` still covers both.
|
|
"""
|
|
|
|
|
|
def _challenge_from(credential: dict[str, Any]) -> bytes:
|
|
"""The challenge the browser echoed back inside `clientDataJSON`.
|
|
|
|
Read from the response rather than remembered per session, because the login
|
|
ceremony has no session to remember it in. That is safe *only* because
|
|
`take_challenge` then checks it against what was actually handed out, for
|
|
the right purpose, unexpired, and deletes it — a challenge this server never
|
|
issued matches nothing, and one it did issue works once.
|
|
"""
|
|
from webauthn.helpers import base64url_to_bytes
|
|
|
|
try:
|
|
raw = credential["response"]["clientDataJSON"]
|
|
data = json.loads(base64url_to_bytes(raw))
|
|
return base64url_to_bytes(data["challenge"])
|
|
except (KeyError, TypeError, ValueError) as exc:
|
|
raise PasskeyMalformed("That response was not a passkey.") from exc
|
|
|
|
|
|
def _malformed(exc: Exception) -> str:
|
|
"""A body the library could not read at all, said without a stack trace.
|
|
|
|
`verify_*_response` raises a family of these — `InvalidJSONStructure` for a
|
|
missing field, and its siblings for CBOR and key material — and they are not
|
|
`Invalid{Registration,Authentication}Response`, so catching only that one
|
|
leaves the rest to come out of an unauthenticated endpoint as a 500 with a
|
|
traceback. The type is worth keeping in the message; the traceback is not,
|
|
because there is no bug here to find.
|
|
"""
|
|
return f"That was not a passkey response: {type(exc).__name__}: {exc}"
|
|
|
|
|
|
def _explain(exc: Exception, config: AuthConfig, request: Request) -> str:
|
|
"""A verification failure, said in terms of what to change.
|
|
|
|
The library's own message names the mismatch precisely and means nothing to
|
|
anyone who has not read the spec; the useful half is which of the two
|
|
settings is wrong, which is almost always the origin behind a proxy.
|
|
"""
|
|
detail = str(exc)
|
|
if "sign count" in detail.lower():
|
|
# The one failure here that is not a misconfiguration. Two devices are
|
|
# answering for one credential and one of them is a copy — or, far more
|
|
# often, a key was restored from a backup that predates its own counter.
|
|
return ("That passkey looks cloned — its counter went backwards. "
|
|
"Revoke it under Account and register a new one.")
|
|
if "origin" in detail.lower() or "rp id" in detail.lower():
|
|
return (f"This passkey was not created for {origin(config, request)} "
|
|
f"(domain {rp_id(config, request)}). Behind a proxy that "
|
|
f"terminates TLS, set `auth.origin` and `auth.rp_id` in "
|
|
f"config.yaml to the address you actually use.")
|
|
return f"That passkey could not be verified: {detail}"
|