"""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"