Files
WolfandClaude Opus 5.5 9d666d0937 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>
2026-09-23 12:29:16 +02:00

105 lines
5.2 KiB
Python

"""What the app is allowed to say about the door.
Pydantic, and nothing imported from the app around it: a config section is the
one piece of a module folder that a project has to merge into its own settings,
and one that dragged the app's `Config` in with it could not be merged at all.
The app writes `auth: AuthConfig = Field(default_factory=AuthConfig)` and is
done.
There is one user, so there is no user management here — only whether the door
is locked, how long a session lasts, and the three strings a passkey is bound
to. The password is not in this file and never will be: it lives in the
database as an scrypt hash, is changed from the Account tab, and is seeded on
first run either from the environment variable named by `password_env` or by a
generated one printed to the log once.
"""
from __future__ import annotations
from typing import Literal
from pydantic import BaseModel, ConfigDict, Field
class AuthConfig(BaseModel):
"""The `auth:` block of `config.yaml`. See docs/password-protection.md."""
#: Unknown keys are refused rather than ignored, the same rule the app's
#: own sections keep: a setting you believe you have changed and have not
#: is the expensive kind of typo.
model_config = ConfigDict(extra="forbid")
#: `auto` is the setting that matters, and it means: locked unless the
#: server is bound to loopback. An app on 127.0.0.1 is reachable by whoever
#: is already sitting at the machine, so a password would be a second lock
#: on an open door; the same app on 0.0.0.0 is reachable by the network,
#: and that is a different application with the same code.
#:
#: Deciding from the bind address rather than defaulting to off is the
#: whole point. The failure this prevents is the one that actually happens:
#: you deploy, it works, and nothing anywhere tells you the door is open.
#: `always` locks it on localhost too and is what a deployment behind a
#: TLS-terminating proxy needs, since there every request looks local to
#: the app and is not. `never` is for putting some other authentication in
#: front of this one, and means exactly what it says.
enabled: Literal["auto", "always", "never"] = "auto"
#: How long a login lasts before it has to be done again. Long, because
#: this is one person on their own devices, and the security value of a
#: short session here is close to zero while the cost -- typing a password
#: into a phone on the bus -- is not.
session_days: int = Field(30, ge=1)
#: Whether the session cookie is marked `Secure`, so a browser will only
#: ever send it back over HTTPS. `auto` sets it when the request itself
#: arrived over HTTPS, which is right when the app terminates TLS and wrong
#: behind a reverse proxy that terminates it for you -- there the app sees
#: plain HTTP and `auto` reads as "no". Set `always` when something else is
#: doing TLS. `never` exists for testing over http on a LAN and is the
#: setting to be uncomfortable with.
secure_cookie: Literal["auto", "always", "never"] = "auto"
# --------------------------------------------------------------- passkeys
#
# A passkey is bound to a *domain*, not to a server, and that binding is the
# entire security property: the browser will only offer a credential back to
# the origin it was created for, which is why a passkey cannot be phished
# the way a password can. Two settings below name that domain, and both are
# blank by default because on a laptop the request itself is the honest
# answer and on a server it is not.
#: The domain passkeys are registered against -- `app.example.com`. Blank
#: derives it from the request's `Host`, which is right in development and
#: is the setting to pin in production: `Host` is client-supplied, and a
#: proxy that passed a forged one through would otherwise move the RP ID.
#:
#: **Changing this invalidates every registered passkey**, because a
#: credential for one domain is not a credential for another. It is not a
#: setting to tune; it is the name of the thing, set once.
rp_id: str = ""
#: What the authenticator shows when it asks you to confirm. Cosmetic, and
#: the one string here a person actually reads.
rp_name: str = "app"
#: The full origin the browser must be at -- `https://app.example.com`.
#: Blank derives it from the request, which behind a TLS-terminating proxy
#: derives `http://` and then rejects every real ceremony as a mismatch.
#: If `secure_cookie: always` applies to you, so does this.
origin: str = ""
# ---------------------------------------------------------- the two names
#
# Named rather than hard-coded because this folder is copied into projects
# that are not called `app`, and two of them on one hostname would otherwise
# share a cookie and overwrite each other's sessions.
#: The environment variable that pins the password. Authoritative while it
#: is set: the Account tab says so and declines to change it. See
#: `auth.bootstrap`.
password_env: str = "APP_PASSWORD"
#: The session cookie's name. `__Host-` is prefixed to it when the cookie
#: will be Secure -- see `auth.middleware.cookie_name`.
cookie: str = "app_session"