auth
One password on a public hostname. scrypt, a lockout counted in the database, sessions you can revoke, passkeys, API tokens for scripts, and one middleware in front of everything — the WebSocket included. No user management: there is one user, they are the person who deployed it, and the only questions are whether the door is locked and what opens it: the password, a passkey, or a token.
Needs Python 3.12+, fastapi and pydantic. webauthn is optional and only for passkeys; every import of it is inside a function, and the passkey routes answer 501 with a sentence saying what to install when it is missing.
The source of truth is boilerplate/auth/. Copies elsewhere are copies: take the whole folder, and run its tests where it lands.
cp -r boilerplate/auth yourproject/auth
python -m pytest yourproject/auth/tests
Then add auth* to that project's pyproject.toml packages, "auth" = ["templates/*.html", "static/*"] to its package data, and auth/tests to its testpaths. The boilerplate's documentation/Password Protection.md is the reasoning behind every decision below, at length.
Five lines
from fastapi import FastAPI
import auth
app = FastAPI()
auth.connect(app, auth.AuthStore(config.database), config.auth,
host=config.server.host, open=("/static/",),
stylesheet="/static/app.css")
Call it first, before the app's own routers. Starlette wraps the whole router in its middleware whenever the routes were added, so the socket and every page are covered either way — but written first it is also read first, and nobody reviewing the file has to work out whether the socket is behind the password.
That gives you /login (the page and the POST), /logout, /api/account, /api/account/password, /api/account/sessions/{id} and /api/account/sessions/close, the four passkey routes, the three token routes (POST /api/account/tokens, POST /api/account/tokens/{id}/label, DELETE /api/account/tokens/{id}), /_auth/passkey.js and /_auth/account.js — and a startup bootstrap that makes sure there is a password at all.
connect(app, store, config, ...) |
|
|---|---|
store |
an AuthStore on whatever database the app keeps. Handing it in rather than building it here is what lets the app decide there is one file. |
config |
an AuthConfig. The app's own config model carries it as a field; see below. |
host= |
the address the server binds — config.server.host. What enabled: auto decides from, and deliberately not taken from a request, since a Host header is written by whoever is talking. |
open= |
extra paths reachable without a session, added to middleware.OPEN. A name ending in / is a prefix; any other is matched whole. ("/static/",) is what an app with a stylesheet passes. |
session_only= |
extra paths an API token may not reach, added to middleware.ACCOUNT and matched the same way. Anything that reads or replaces the database as a file belongs here, since the file holds the password hash and the token rows. |
stylesheet= |
a URL the login page links, so it looks like the rest of the app. Optional: the page carries enough inline CSS to be presentable on its own. |
The account screen is two lines in a template, the same deal <desk-jobs> makes:
<script type="module" src="/_auth/account.js"></script>
<auth-account></auth-account>
It draws the lot — locked or not, change the password, the sessions with revoke and close-others, the passkeys with register, rename and revoke, the API tokens with create, rename and revoke, and sign out — and it is themed from outside by the same --desk-jobs-* custom properties the queue's elements read, so desk-jobs, desk-schedules, auth-account { ... } in one stylesheet is all three. Under 40rem a row's buttons drop under its name when they do not fit beside it and a form's fields take the width; under a coarse pointer every button is a thumb's height and no field is under 16px. The login page does the same for itself, since it is served before any of the app's CSS.
The config block
AuthConfig is pydantic and imports nothing from the app, so an app's own config model carries it as a field:
from auth import AuthConfig
class Config(Section):
auth: AuthConfig = Field(default_factory=AuthConfig)
auth:
enabled: auto # auto | always | never
session_days: 30
secure_cookie: auto # `always` behind a proxy that terminates TLS
rp_id: "" # app.example.com -- passkeys are bound to a domain
rp_name: app # what the authenticator shows you
origin: "" # https://app.example.com
password_env: APP_PASSWORD
cookie: app_session
enabled: auto is the setting that matters: locked unless the server binds a loopback address. Deciding from the bind address rather than defaulting to off prevents the failure that actually happens — you deploy, it works, and nothing anywhere tells you the door is open. Production says always anyway, so the lock does not depend on the bind address or on how the process was started. Under auto an app left open on loopback answers any request carrying X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host or Forwarded with 421 and logs a warning once, since a proxy on the same machine would otherwise serve it to the network without a password. The Vite dev server's proxy sends none of these headers.
password_env and cookie are settings because this folder is copied into projects that are not called app, and two of those on one hostname would otherwise share a cookie and sign each other out.
Getting in the first time
The password is never in the config file — only ever an scrypt hash in the database. The first locked start takes $APP_PASSWORD if it is set, and otherwise invents one and prints it to the log once, in a plain ASCII banner you can read back off docker compose logs.
APP_PASSWORD is authoritative while it is set: the Account screen says so and declines to change it. That is the way back in when a login is lost — set it, get in, empty it, recreate the container, then change the password in the app. A variable that silently stopped applying the moment you changed the password in the browser would be worse than either rule. When it replaces a stored password, the start closes every session, since whoever had the old password may be signed in, and logs at WARNING how many API tokens and passkeys remain; review them under Account, or tick the revoke box on the next password change.
What the app has to provide
Almost nothing, and that is the point.
- A SQLite path.
AuthStorecreates fiveauth_*tables in whatever file it is given, so it can share the app's own. - The bind host, for
enabled: auto. - Nothing for the open list, as a rule.
/login,/login/,/_auth/and/healthare opened by this package; the app adds/static/if it serves one, or the login page arrives unstyled. Everything else stays shut — a module's own scripts and sockets included, so in this repository/_jobs/jobs.jsand/ws/jobsneed a session like the pages that load them. - An error handler that keeps
{"detail": "..."}for/api,/wsand/_auth, if it has one. Every refusal here is already that shape. app.state.bus, if it holds sockets open: an object with asocketstuple and an asyncclose(sockets, code, reason), which is whatpipeline.web.connectputs there. Without one, a socket stays open after its credential ends until the tab reconnects.
What it must not do is protect its own routes. Everything is shut except the open list, which is four entries long and asserted in a test — so a router added next month is safe because it exists, not because somebody remembered.
The decisions, in one paragraph each
One door, in front of everything. The door is one middleware, installed once by connect, in front of every route and the socket. A route checks no credential itself, and the only exceptions are the open list. A route that needs the password again, such as a restore whose body is the database, calls auth.confirm_password(request, current), which is counted and gated like the front door; when the body is a file, it calls auth.confirm_current(request) instead, which reads current from an X-Current-Password header before the body, and answers 403 without counting when the header is missing. A socket is checked at its handshake and closed with 1008 when its credential ends: on a revoke by close_ended_sockets, which /logout, the password change and the session and token revokes run after their answer, and on expiry by sweep_ended_sockets, which connect runs on a locked app every SWEEP (60) seconds.
scrypt, not SHA-256. Memory-hard rather than merely slow: one guess costs 16 MB, which is what takes a stolen database file out of range of a GPU. A wrong answer costs a full derivation too, so the delay an attacker meets is the one the honest user meets.
A session is 32 random bytes, and the table holds only its SHA-256. No signing key to generate, store, keep out of backups and rotate; signing out everywhere is one DELETE, which no self-contained token can offer without keeping exactly this state.
The lockout is counted in the file and claimed before the check. A counter on the process is a free reset for whoever is guessing, on a server that reloads. Each guess is claimed before its derivation, in one BEGIN IMMEDIATE that reads locked_until and counts the attempt, and a right answer clears the count afterwards; read before the derivation and written after it, thirty concurrent guesses all found the door open. A claim refused while locked counts nothing, so hammering the button does not extend your own lockout, which would punish the owner far harder than the attacker who is not watching. Five wrong answers are free, then 30 s doubling to a quarter of an hour, with the exponent capped so a bot cannot turn arithmetic into a 500.
One counter, not one per address. Behind a proxy the only address the app sees is one the caller wrote. Keyed on that, an attacker gets a fresh counter per request while the owner still gets locked out by their own typos. So the address is logged — one WARNING per refusal, auth.middleware: wrong password from <addr>, stripped to the characters an address is made of — and decided from at the layer that knows who connected. The address is the rightmost hop of X-Forwarded-For, which the proxy appended, else X-Real-IP, else the peer; the hops left of it are the caller's own writing. documentation/Password Protection.md has the nginx and fail2ban half.
No CSRF token. SameSite=Lax refuses to send this cookie on any cross-site request that is not a top-level navigation, and no GET here changes anything, so the attack a token would stop cannot be mounted. A second secret to rotate, and a second way for a request to fail, buys nothing.
Passkeys need a real hostname. A passkey is bound to an origin, and that binding is what makes it unphishable — so it needs HTTPS, with localhost the one exception, which is what lets it be tried before deploying. Behind a proxy, set rp_id and origin explicitly or every ceremony fails as an origin mismatch. Changing rp_id later invalidates every key registered against the old one. The password never goes away, which is why revoking a key can never lock you out.
A passkey is added only with the password. A session is not enough: a passkey stays valid after every session ends and after a password change, so a borrowed signed-in browser must not be able to add one. POST /api/account/passkeys/options takes current, checked behind the same lockout as the front door. An app with no password yet (loopback, never locked) registers without it. Changing the password leaves the passkeys registered; revoke any you do not recognise.
An API token is a session for a script. POST /api/account/tokens takes the password like a passkey does, and answers with the token once; the table keeps its SHA-256, a label, the first eight characters so the owner can tell the rows apart, and an optional expiry. A script sends it as Authorization: Bearer <token> and it is looked up on every request, so revoking the row takes effect on the next call. It opens everything a session opens except /api/account, /logout and what the app names in connect(session_only=...), which answer 403 to a token: a token that leaked cannot mint another, revoke the owner's sessions or read the list of ways in. A route that downloads or restores the database belongs on that list, because the file holds the password hash and the token rows, and a token that could fetch or swap it would hold the account after all. A token the store does not know is a 401 and a WARNING line like a wrong password, and is not counted against the lockout, since 256 random bits are not guessed and the counter would only hand a stranger a way to lock the owner out. A password change leaves tokens in place, as it does passkeys, unless revoke_all is sent with it, which deletes every token and passkey; the answer counts the sessions closed and the tokens and passkeys revoked and left.
Another site's page changes nothing. SameSite=Lax covers a locked app, and an unlocked one on loopback has no cookie to withhold: a page open in the same browser could POST a text/plain body to any route that takes none, and open /ws/jobs, which CORS does not cover. So the middleware refuses a request that changes something when Sec-Fetch-Site, or Origin against Host or auth.origin, says it came from another site, refuses a body of a type a page can send without a preflight (the API is JSON), and refuses a socket handshake from another origin. A read is never refused, and a request with no Origin at all (curl, a script with a token) passes. The comparison is against the request's own Host, which a DNS rebinding page matches, so an app auto left open also answers 421 to any request whose Host is not a loopback name, a .localhost name or the host of auth.origin, whatever other headers it carries: a loopback app is reached as localhost, and nothing else should be naming it. A test client of an unlocked app therefore names one, e.g. TestClient(app, base_url="http://127.0.0.1").
Tests
uv run pytest auth/tests
The passkey ceremonies are tested against auth/tests/softkey.py, a real WebAuthn authenticator that happens to be in software: it produces the same CBOR, the same authenticator data and the same ECDSA signatures a hardware key does, so a wrong origin fails because the origin is signed over and a clone is caught because the counter went backwards. Those tests skip without the extra; what the app does without it is test_without_passkeys.py, which always runs.