Bring in pipeline, auth, deploy and docs from the boilerplate

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>
This commit is contained in:
WolfandClaude Opus 5.5 committed 2026-09-23 12:29:16 +02:00
1 parent 1f436104f3
commit 9d666d0937
76 files changed
+15235

No files matched your search

+160
View File
@@ -0,0 +1,160 @@
"""One password on a public hostname, in one call.
app = FastAPI()
store = connect(app, AuthStore("data/app.db"), config.auth,
host=config.server.host, open=("/static/",),
stylesheet="/static/app.css")
That is the middleware in front of everything (the WebSocket included), the
login page, the account API, the `<auth-account>` element, and the startup
bootstrap that makes sure there is a password at all. 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.
| module | |
|---|---|
| `config.py` | `AuthConfig`: the `auth:` block of the app's `config.yaml` |
| `store.py` | `AuthStore`: scrypt, the lockout, sessions, passkeys, four `auth_*` tables in whatever SQLite file it is given |
| `models.py` | `Account`, `SessionInfo`, `Passkey` — what the account screen is told, which carries no credential |
| `middleware.py` | `RequireLogin`, `locked()`, the open list, the cookie |
| `passkeys.py` | the two WebAuthn ceremonies; `webauthn` is an optional extra, imported lazily |
| `schemas.py` | the five request bodies |
| `router.py` | `/login`, `/logout`, `/api/account/*`, the passkey routes, `/_auth/*.js` |
| `templates/login.html` | the one page served without a session |
| `static/` | `passkey.js` (the browser half of WebAuthn) and `account.js` (`<auth-account>`) |
The reasoning is `docs/password-protection.md`, and this package is that
document in code. `auth/README.md` is how to copy the folder into a project
that has never heard of this one.
"""
from __future__ import annotations
import logging
import os
import secrets
from collections.abc import AsyncIterator, Iterable
from contextlib import asynccontextmanager
from typing import Any
from fastapi import FastAPI
from auth import passkeys
from auth.config import AuthConfig
from auth.middleware import OPEN, RequireLogin, client_address, locked, token_from
from auth.models import Account, Passkey, SessionInfo
from auth.router import router
from auth.store import AuthStore
log = logging.getLogger(__name__)
__all__ = [
"OPEN", "Account", "AuthConfig", "AuthStore", "Passkey", "RequireLogin",
"SessionInfo", "bootstrap", "client_address", "connect", "locked",
"passkeys", "router", "token_from",
]
def connect(app: FastAPI, store: AuthStore, config: AuthConfig, *,
open: Iterable[str] = (), stylesheet: str | None = None,
host: str = "") -> AuthStore:
"""Put `app` behind a password: middleware, routes, element, bootstrap.
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.
`store` is 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.
| keyword | |
|---|---|
| `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. |
| `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. |
| `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. |
The lifespan is wrapped rather than replaced, the same way
`pipeline.web.connect` does it, so an app's own lifespan still runs inside
this one: the password exists before the app's startup code, which may want
to say something about it.
Returns the store, for the app to keep if it wants one.
"""
app.state.auth = store
app.state.auth_config = config
#: Whether a session is required. Decided once, here, because it depends on
#: the bind address, which only the caller knows.
app.state.auth_locked = locked(config, host)
app.state.auth_stylesheet = stylesheet or ""
app.include_router(router)
app.add_middleware(RequireLogin, store=store, config=config,
open=tuple(open), host=host)
inner = app.router.lifespan_context
@asynccontextmanager
async def lifespan(this: FastAPI) -> AsyncIterator[Any]:
if app.state.auth_locked:
bootstrap(store, config)
store.purge()
# Outside the `locked` check on purpose: a passkey can be registered on
# a loopback app before it is ever deployed, which is the order this
# encourages, so an unlocked one can still have keys it cannot use.
passkeys.warn_if_missing(store)
async with inner(this) as state:
yield state
app.router.lifespan_context = lifespan
return store
def bootstrap(store: AuthStore, config: AuthConfig) -> None:
"""Make sure there is a password, and say so once if we invented one.
The variable named by `config.password_env` — `APP_PASSWORD` by default —
is authoritative while it is set: if it is in the environment, it *is* the
password, and the account screen says so and declines to change it. That is
a deliberate choice over seeding from it once — a variable that silently
stopped applying the moment you changed the password in the browser would
be worse than either rule, and this way round the environment doubles as
the way back in when you are locked out of your own server.
Re-derived only when the stored hash does not already match, so a restart is
not a write and "password last changed" keeps meaning something.
"""
pinned = os.environ.get(config.password_env, "")
if pinned:
if not store.check_password(pinned):
store.set_password(pinned)
log.info("password set from %s", config.password_env)
return
if store.has_password():
return
password = secrets.token_urlsafe(12)
store.set_password(password)
# At WARNING so it survives the default log level, and banner-shaped because
# it is printed exactly once in the life of a database and being scrolled
# past is the same as not being printed at all.
#
# ASCII, deliberately. This is the one log line whose *contents* someone has
# to read back character by character, and it is read wherever the server
# happens to be running -- a Windows console under cp1252, a `docker logs`
# pipe with no locale set. Box-drawing characters come out as `?` in both,
# which turns the frame around the password into noise around the password.
log.warning(
"\n"
" ------------------------------------------------------------\n"
" This app is locked and had no password, so here is one:\n"
"\n"
" %s\n"
"\n"
" This is the only time it is shown. Change it under Account,\n"
" or set %s to pin one.\n"
" ------------------------------------------------------------",
password, config.password_env,
)