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>
490 lines
21 KiB
Python
490 lines
21 KiB
Python
"""Signing in, signing out, and the one account there is.
|
|
|
|
The middleware in `auth/middleware.py` decides who gets past the door; this is
|
|
the door itself, plus the small screen for changing the key. Everything here is
|
|
deliberately about *this* user's own credential — there is no user to create,
|
|
none to list, and none to delete, because there is one.
|
|
|
|
Nothing is read from a module-level global: the store, the config and whether
|
|
the door is locked all come off `app.state`, where `connect` put them. That is
|
|
what lets two apps in one test process each have their own, and what keeps this
|
|
router importable by an app that never calls `connect` at all.
|
|
|
|
## Why the cookie is `SameSite=Lax` and there is no CSRF token
|
|
|
|
A CSRF token defends a cookie-authenticated app against another origin
|
|
submitting a form on your behalf. `SameSite=Lax` already refuses to send this
|
|
cookie on any cross-site request that is not a top-level navigation, and no
|
|
`GET` in this package changes anything — so the attack the token would stop
|
|
cannot be mounted. Adding one anyway would mean a second secret, a second thing
|
|
to rotate, and a second way for a request to fail for reasons the UI has to
|
|
explain. Where that reasoning stops being true is a browser old enough to
|
|
ignore `SameSite` entirely, which is not one that will run the login page.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
import os
|
|
from pathlib import Path
|
|
from urllib.parse import unquote, urlsplit
|
|
|
|
from fastapi import APIRouter, HTTPException, Request, Response
|
|
from fastapi.responses import FileResponse, HTMLResponse, RedirectResponse
|
|
from starlette.requests import HTTPConnection
|
|
|
|
from auth import passkeys as pk
|
|
from auth.config import AuthConfig
|
|
from auth.middleware import (
|
|
client_address, cookie_name, cookie_names, is_secure, token_from,
|
|
)
|
|
from auth.models import Account
|
|
from auth.schemas import (
|
|
LabelBody, LoginBody, PasskeyBody, PasskeyLoginBody, PasswordBody,
|
|
)
|
|
from auth.store import AuthStore
|
|
|
|
log = logging.getLogger(__name__)
|
|
|
|
router = APIRouter(tags=["auth"])
|
|
|
|
#: The page and the two scripts, shipped with the package. Served from routes
|
|
#: rather than mounted as a static directory because a router cannot mount one
|
|
#: — only an app can — and needing the app to mount something is exactly the
|
|
#: line of setup `connect` exists to remove. The same deal `/_jobs/jobs.js`
|
|
#: makes in `pipeline/web/jobs.py`.
|
|
TEMPLATES = Path(__file__).resolve().parent / "templates"
|
|
STATIC = Path(__file__).resolve().parent / "static"
|
|
|
|
#: The login page must never be cached: a proxy or a browser holding on to it
|
|
#: is a form posting to a door that has since been opened, or a page shown to
|
|
#: the next person at this machine.
|
|
NO_STORE = {"Cache-Control": "no-store"}
|
|
|
|
#: The shortest new password the account screen will take. Low, deliberately:
|
|
#: it is a floor against a typo, not a password policy. The honest advice is in
|
|
#: docs/password-protection.md — the generated password is sixteen random
|
|
#: characters and anything you choose yourself is the weak half.
|
|
MIN_LENGTH = 8
|
|
|
|
|
|
# ------------------------------------------------------- what connect left us
|
|
|
|
def _store(conn: HTTPConnection) -> AuthStore:
|
|
return conn.app.state.auth
|
|
|
|
|
|
def _config(conn: HTTPConnection) -> AuthConfig:
|
|
return conn.app.state.auth_config
|
|
|
|
|
|
def _locked(conn: HTTPConnection) -> bool:
|
|
"""Whether this app is running with the door locked.
|
|
|
|
Read off `app.state`, where `connect` put it, rather than recomputed: the
|
|
answer depends on the bind address, which the config alone does not know
|
|
and a request cannot be asked for.
|
|
"""
|
|
return bool(conn.app.state.auth_locked)
|
|
|
|
|
|
def _pinned(conn: HTTPConnection) -> str:
|
|
"""The password from the environment, or "". See `auth.bootstrap`."""
|
|
return os.environ.get(_config(conn).password_env, "")
|
|
|
|
|
|
# ---------------------------------------------------------------- the scripts
|
|
|
|
@router.get("/_auth/passkey.js", include_in_schema=False)
|
|
def passkey_js() -> FileResponse:
|
|
"""The browser half of WebAuthn, shared by the login page and the element."""
|
|
return _script("passkey.js")
|
|
|
|
|
|
@router.get("/_auth/account.js", include_in_schema=False)
|
|
def account_js() -> FileResponse:
|
|
"""`<auth-account>`: the account screen, for an app with no UI for it yet.
|
|
|
|
<script type="module" src="/_auth/account.js"></script>
|
|
<auth-account></auth-account>
|
|
"""
|
|
return _script("account.js")
|
|
|
|
|
|
def _script(name: str) -> FileResponse:
|
|
"""Cached for an hour rather than forever. These change when the package is
|
|
copied into a project and then hardly ever, and an app that wants them
|
|
fingerprinted can serve the files itself from `STATIC`."""
|
|
return FileResponse(STATIC / name, media_type="text/javascript",
|
|
headers={"Cache-Control": "public, max-age=3600"})
|
|
|
|
|
|
# ------------------------------------------------------------------- the door
|
|
|
|
@router.get("/login", response_class=HTMLResponse, include_in_schema=False)
|
|
def login_page(request: Request) -> Response:
|
|
"""The one page served without a session.
|
|
|
|
Sent only if you ask for it directly with no session cookie; with one,
|
|
there is nothing here to do, so it bounces to the front page rather than
|
|
offering a form that would replace a session you have.
|
|
"""
|
|
if not _locked(request):
|
|
return RedirectResponse("/", status_code=303)
|
|
token = token_from(request, _config(request))
|
|
if token and _store(request).touch(token):
|
|
return RedirectResponse("/", status_code=303)
|
|
|
|
config = _config(request)
|
|
store = _store(request)
|
|
# Whether to draw the passkey button at all. Decided here rather than by
|
|
# the page asking, because a button that appears and then discovers there
|
|
# is nothing to press is worse than one that was never drawn — and the page
|
|
# has no session, so it cannot ask anything else about the account.
|
|
offer = "true" if (pk.available() and store.passkey_ids()) else "false"
|
|
sheet = request.app.state.auth_stylesheet
|
|
html = (TEMPLATES / "login.html").read_text(encoding="utf-8")
|
|
html = (html
|
|
.replace("{stylesheet}",
|
|
f'<link rel="stylesheet" href="{sheet}">' if sheet else "")
|
|
.replace("{name}", config.rp_name)
|
|
.replace("{passkeys}", offer))
|
|
return HTMLResponse(html, headers=NO_STORE)
|
|
|
|
|
|
@router.post("/login", include_in_schema=False)
|
|
def sign_in(request: Request, response: Response, body: LoginBody) -> dict[str, str]:
|
|
"""Check the password, and if it is right, open a session.
|
|
|
|
The lockout is read *before* the password is checked, so hammering the
|
|
button while locked out does not extend the lockout — see
|
|
`AuthStore.locked_for`. A wrong password and an unknown one are the same
|
|
answer here for the usual reason, which is thin cover with one account but
|
|
costs nothing to keep.
|
|
"""
|
|
if not _locked(request):
|
|
raise HTTPException(400, "This app is not password-protected.")
|
|
|
|
_refuse_while_locked(request)
|
|
|
|
if not _store(request).check_password(body.password):
|
|
_warn(request, "wrong password")
|
|
raise HTTPException(401, "That is not the password.")
|
|
|
|
_open_session(request, response)
|
|
return {"next": _safe_next(body.next)}
|
|
|
|
|
|
@router.post("/logout", include_in_schema=False)
|
|
def sign_out(request: Request, response: Response) -> dict[str, bool]:
|
|
"""End this session and clear the cookie. Other devices are untouched."""
|
|
token = token_from(request, _config(request))
|
|
if token:
|
|
_store(request).close_session(token)
|
|
# Both names, because which one was set depends on `secure_cookie` and on
|
|
# the scheme the login happened over — and clearing only one of them leaves
|
|
# a cookie the browser will keep offering.
|
|
for name in cookie_names(_config(request)):
|
|
response.delete_cookie(name, path="/")
|
|
return {"ok": True}
|
|
|
|
|
|
# ---------------------------------------------------------------- the account
|
|
|
|
@router.get("/api/account")
|
|
def account(request: Request) -> Account:
|
|
"""What there is to know and what can be changed."""
|
|
store = _store(request)
|
|
config = _config(request)
|
|
return Account(
|
|
locked=_locked(request),
|
|
pinned=bool(_pinned(request)),
|
|
pinned_by=config.password_env,
|
|
password_set_at=store.changed_at(),
|
|
sessions=store.sessions(token_from(request, config)),
|
|
passkeys=store.passkeys(),
|
|
passkeys_available=pk.available(),
|
|
passkeys_blocked=pk.blocked(config, request),
|
|
)
|
|
|
|
|
|
@router.post("/api/account/password")
|
|
def change_password(request: Request, body: PasswordBody) -> dict[str, int]:
|
|
"""Change it, having proved you know the current one — or set the first.
|
|
|
|
Asking for the current password matters even though you are already signed
|
|
in: it is what makes a borrowed unlocked laptop not equal to a permanent
|
|
takeover of the account. It is asked for whenever there is one, which on a
|
|
locked app is always; see the body of the function for the one case where
|
|
there is not.
|
|
|
|
Every *other* session is closed on success. If the reason you are changing
|
|
the password is that someone may have it, leaving their session open makes
|
|
the change ceremonial — and the cost when that is not the reason is signing
|
|
in again on your phone, which is the right way round.
|
|
|
|
Which is also why this is behind the same lockout as the front door, and not
|
|
only behind a session. `current` is the password, guessed here rather than
|
|
at `/login`, and a borrowed unlocked laptop is exactly the situation the
|
|
field exists for — so leaving it ungated would leave one door counted and
|
|
one door open, at scrypt speed, ending in a password change that signs the
|
|
owner out everywhere.
|
|
"""
|
|
config = _config(request)
|
|
if _pinned(request):
|
|
raise HTTPException(
|
|
409, f"The password is pinned by {config.password_env}. Change it there.")
|
|
store = _store(request)
|
|
|
|
# The first one is set without proving anything, because there is nothing
|
|
# to prove: an app with no password is one nothing was asked for, and the
|
|
# only way to reach this route is from a session it never demanded. That
|
|
# is the unlocked laptop, and setting a password *there* — before the
|
|
# thing is ever deployed — is the order this should encourage. A locked
|
|
# app never lands here: `auth.bootstrap` gives it a password at startup,
|
|
# so `current` is always required for the app that has a door.
|
|
if store.has_password():
|
|
_refuse_while_locked(request)
|
|
if not store.check_password(body.current):
|
|
_warn(request, "wrong current password")
|
|
raise HTTPException(403, "That is not the current password.")
|
|
if len(body.new) < MIN_LENGTH:
|
|
raise HTTPException(400, f"Use at least {MIN_LENGTH} characters.")
|
|
|
|
store.set_password(body.new)
|
|
closed = store.close_all(keep=token_from(request, config))
|
|
return {"signed_out": closed}
|
|
|
|
|
|
@router.delete("/api/account/sessions/{session_id}")
|
|
def revoke(session_id: int, request: Request) -> dict[str, bool]:
|
|
"""Drop one session. Revoking your own is allowed — it is a logout with an
|
|
extra click, and refusing it would be a rule to explain for no gain."""
|
|
if not _store(request).close_by_id(session_id):
|
|
raise HTTPException(404, "That session is already gone.")
|
|
return {"ok": True}
|
|
|
|
|
|
@router.post("/api/account/sessions/close")
|
|
def close_others(request: Request) -> dict[str, int]:
|
|
"""Sign out everywhere but here. The reason sessions are rows."""
|
|
store = _store(request)
|
|
return {"signed_out": store.close_all(keep=token_from(request, _config(request)))}
|
|
|
|
|
|
# ------------------------------------------------------------------- passkeys
|
|
#
|
|
# Four routes behind the session (register in two steps, rename, revoke) and two
|
|
# in front of it (sign in). The ceremony itself is `auth/passkeys.py`; these are
|
|
# the round trips it needs, and the translation of its two exceptions into
|
|
# status codes.
|
|
|
|
|
|
@router.post("/api/account/passkeys/options")
|
|
def passkey_options(request: Request) -> dict[str, object]:
|
|
"""Step one of registering: a challenge for `navigator.credentials.create`."""
|
|
_require_passkeys(request)
|
|
return pk.register_options(_config(request), request, _store(request))
|
|
|
|
|
|
@router.post("/api/account/passkeys")
|
|
def add_passkey(request: Request, body: PasskeyBody) -> dict[str, int]:
|
|
"""Step two: check what the authenticator signed, and keep the public key.
|
|
|
|
Requires a session, like everything else under `/api/account`. Registering a
|
|
passkey is granting a new way in, so it is gated on already being in — the
|
|
password is what proves that, and the ceremony does not replace it.
|
|
"""
|
|
_require_passkeys(request)
|
|
try:
|
|
return {"id": pk.register_verify(_config(request), request, _store(request),
|
|
body.credential, body.label)}
|
|
except pk.PasskeyError as exc:
|
|
# `PasskeyMalformed` is one of these and answers the same way: from
|
|
# behind a session, a body that is not a ceremony and a ceremony that
|
|
# did not check out are both "that did not work, press it again".
|
|
raise HTTPException(400, str(exc)) from None
|
|
|
|
|
|
@router.post("/api/account/passkeys/{passkey_id}/label")
|
|
def rename_passkey(passkey_id: int, body: LabelBody, request: Request) -> dict[str, bool]:
|
|
"""Name it. A key you cannot name is one you will never dare revoke."""
|
|
if not _store(request).rename_passkey(passkey_id, body.label):
|
|
raise HTTPException(404, "That passkey is already gone.")
|
|
return {"ok": True}
|
|
|
|
|
|
@router.delete("/api/account/passkeys/{passkey_id}")
|
|
def drop_passkey(passkey_id: int, request: Request) -> dict[str, bool]:
|
|
"""Revoke one. The password is still there, so this cannot lock you out —
|
|
which is exactly why the password is still there."""
|
|
if not _store(request).delete_passkey(passkey_id):
|
|
raise HTTPException(404, "That passkey is already gone.")
|
|
return {"ok": True}
|
|
|
|
|
|
@router.post("/login/passkey/options", include_in_schema=False)
|
|
def passkey_login_options(request: Request) -> dict[str, object]:
|
|
"""Step one of signing in. Open, necessarily — there is no session yet.
|
|
|
|
Handing out a challenge to anyone who asks costs nothing: it is a random
|
|
number, single-use, and worth nothing without a private key that never left
|
|
the authenticator.
|
|
"""
|
|
_require_passkeys(request)
|
|
store = _store(request)
|
|
if not store.passkey_ids():
|
|
raise HTTPException(404, "No passkeys are registered on this app.")
|
|
return pk.login_options(_config(request), request, store)
|
|
|
|
|
|
@router.post("/login/passkey", include_in_schema=False)
|
|
def passkey_login(request: Request, response: Response,
|
|
body: PasskeyLoginBody) -> dict[str, str]:
|
|
"""Step two: a good signature from a registered key opens a session.
|
|
|
|
The same session a password opens — one kind of session, whichever door it
|
|
came through, so revoking and expiry have one implementation.
|
|
|
|
Deliberately not behind the password lockout. An attacker hammering the
|
|
front door locks it for the owner too (see `AuthStore.check_password` on
|
|
why there is one counter), and a passkey that skips that queue is what
|
|
makes it survivable. It is safe to skip: there is nothing to guess here,
|
|
only a signature to produce.
|
|
"""
|
|
if not _locked(request):
|
|
raise HTTPException(400, "This app is not password-protected.")
|
|
_require_passkeys(request)
|
|
try:
|
|
pk.login_verify(_config(request), request, _store(request), body.credential)
|
|
except pk.PasskeyMalformed as exc:
|
|
# Not a failed sign-in — a request that was never a ceremony. 400 rather
|
|
# than 401, and no warning, because there is no credential here to have
|
|
# been wrong about.
|
|
raise HTTPException(400, str(exc)) from None
|
|
except pk.PasskeyError as exc:
|
|
_warn(request, "passkey refused")
|
|
raise HTTPException(401, str(exc)) from None
|
|
|
|
_open_session(request, response)
|
|
return {"next": "/"}
|
|
|
|
|
|
def _require_passkeys(request: Request) -> None:
|
|
"""501 rather than 500 when the extra is not installed, and a sentence
|
|
saying what to install.
|
|
|
|
"Not implemented" is the honest reading: the route exists and this build
|
|
cannot perform it. The account element watches for exactly this status and
|
|
takes the passkey section off the screen, so a missing optional dependency
|
|
costs a paragraph rather than a broken page.
|
|
|
|
Only the package is checked here — an insecure origin blocks *registration*
|
|
in the browser, not these endpoints, and the account screen has already
|
|
said so.
|
|
"""
|
|
if not pk.available():
|
|
raise HTTPException(501, pk.blocked(_config(request), request))
|
|
|
|
|
|
# --------------------------------------------------------------------- helpers
|
|
|
|
def _open_session(request: Request, response: Response) -> None:
|
|
"""One session, one cookie, whichever door was used."""
|
|
config = _config(request)
|
|
token = _store(request).open_session(
|
|
request.headers.get("user-agent", ""), config.session_days)
|
|
https = request.url.scheme == "https"
|
|
response.set_cookie(
|
|
cookie_name(config, https),
|
|
token,
|
|
max_age=config.session_days * 86400,
|
|
httponly=True, # JavaScript cannot read it, so an XSS cannot post it on
|
|
secure=is_secure(config, https),
|
|
samesite="lax", # see the module docstring on why there is no CSRF token
|
|
path="/",
|
|
)
|
|
|
|
|
|
def _refuse_while_locked(request: Request) -> None:
|
|
"""The lockout, in front of every place a password can be guessed.
|
|
|
|
Read *before* the guess is looked at, so hammering while locked out does not
|
|
extend the lockout — see `AuthStore.locked_for`. Called from both doors
|
|
rather than living inside `check_password`, because the store counts and
|
|
this decides: the same wrong answer is a refusal here and a bootstrap
|
|
comparison in `auth.bootstrap`, which must not be able to lock anyone out of
|
|
their own restart.
|
|
"""
|
|
wait = _store(request).locked_for()
|
|
if wait:
|
|
_warn(request, "attempt while locked out")
|
|
raise HTTPException(429, f"Too many attempts. Try again in {_spell(wait)}.",
|
|
headers={"Retry-After": str(wait)})
|
|
|
|
|
|
def _warn(request: Request, what: str) -> None:
|
|
"""Write down that someone got it wrong, and who.
|
|
|
|
The whole record of who is knocking. There is no access log worth the name —
|
|
uvicorn is run quietly — and no table of attempts, because the log is the
|
|
record and a second copy of it would only ever disagree. WARNING so it
|
|
survives that level, one line per refusal, and the address first after
|
|
`from` so a fail2ban filter is one regex; see docs/password-protection.md.
|
|
|
|
The message does not name the package, because the logger already does:
|
|
with the usual `%(name)s: %(message)s` this module is `auth.router`, and a
|
|
line reading `auth.router: auth: wrong password` says it twice and reads
|
|
like a bug in the logging.
|
|
|
|
Nothing is *decided* from the address — `AuthStore.check_password` says why
|
|
it cannot be — so this is where it earns its keep: at the layer that can
|
|
drop the connection instead of answering it.
|
|
"""
|
|
log.warning("%s from %s", what, client_address(request))
|
|
|
|
|
|
def _safe_next(target: str) -> str:
|
|
r"""Where to go after signing in — only ever inside this app.
|
|
|
|
The classic open redirect: a real login page, a real successful sign-in, and
|
|
someone else's site afterwards. So this accepts one shape only — a path
|
|
beginning with a single `/`, with no host in it — and turns everything else
|
|
into `/`.
|
|
|
|
A backslash is refused because a browser treats it as a slash in exactly
|
|
this position: `/\evil.com` is parsed as `//evil.com` and is a host, which
|
|
is how a version of this that rejected only a literal `//` sent people to
|
|
another site. And the value is checked decoded as well as raw, because it
|
|
reaches here through a query string that `URLSearchParams` has already
|
|
unescaped once — `%5C` is a backslash to everything downstream of the
|
|
address bar, and no `next` this app produces needs an escaped slash to
|
|
survive.
|
|
"""
|
|
if not _local(target) or not _local(unquote(target)):
|
|
return "/"
|
|
return target
|
|
|
|
|
|
def _local(target: str) -> bool:
|
|
r"""Whether this is a path inside this app and nothing else.
|
|
|
|
`urlsplit` rather than more string tests, because it is the parser the
|
|
browser's own rules are written against — it strips the tabs and newlines a
|
|
browser strips, so `/\t/evil.com` is seen the way the browser will see it,
|
|
as a host, and not as the local path a naive `startswith` reads.
|
|
"""
|
|
if not target.startswith("/") or target.startswith("//") or "\\" in target:
|
|
return False
|
|
try:
|
|
parts = urlsplit(target)
|
|
except ValueError: # an unparseable authority, e.g. `//[`
|
|
return False
|
|
return not parts.scheme and not parts.netloc
|
|
|
|
|
|
def _spell(seconds: int) -> str:
|
|
if seconds < 60:
|
|
return f"{seconds} seconds"
|
|
return f"{round(seconds / 60)} minutes"
|