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>
105 lines
5.2 KiB
Python
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"
|