"""The lock on the door: is there a session, and what happens when there isn't. Three things live here — when the door is locked at all, who gets past it, and the cookie that says so. The password itself is `auth/store.py`; this module never sees a hash. ## Why a middleware and not a dependency The FastAPI-shaped answer is `Depends(current_session)` on every route, and it is the wrong one here for two reasons. The first is the WebSocket. `/ws/jobs` is a real socket, and route dependencies on a WebSocket endpoint are awkward at best — but a cookie rides the handshake like any other request, so one ASGI middleware in front of everything covers the socket and the JSON with the same six lines. The second is the failure mode. A dependency is opt-in: protection is applied by remembering to apply it, and the cost of forgetting is not a broken page but a quiet hole — an API served to the internet, and nothing on screen different. An app adds routers regularly, and the next one should be safe because it exists, not because someone remembered. So the rule is inverted: everything is shut, and the few things that must be open are named in one list you can read at a glance. ## What being locked means `auto` decides from the bind address, which is the only setting that ever mattered: bound to loopback, the door is already the machine's own login, and a password is a second lock on it; bound to anything else, the app is on a network and needs its own. The alternative — default off, switch it on when you deploy — fails silently in the exact case it exists for, because an app serving the internet with no password looks and behaves precisely like one that is fine. """ from __future__ import annotations import asyncio import ipaddress import logging from http.cookies import SimpleCookie from typing import Any from urllib.parse import quote from starlette.requests import HTTPConnection from starlette.responses import JSONResponse, RedirectResponse, Response from starlette.types import ASGIApp, Receive, Scope, Send from auth.config import AuthConfig from auth.store import AuthStore log = logging.getLogger(__name__) #: Reachable without a session, and nothing else is. `/login` has to be, or #: there is no way in, and the passkey ceremony under `/login/` with it; #: `/_auth/` carries the two scripts the login page and the account element #: are; `/health` is for a proxy probe that has no session to offer. The app #: adds its own — `/static/`, normally, or the login page arrives unstyled. #: #: A name ending in `/` is a prefix, any other is matched whole, so `/health` #: does not open `/healthz` and `/login` does not open `/loginx`. Matched #: against the path only — a query string cannot widen this. OPEN: tuple[str, ...] = ("/login", "/login/", "/_auth/", "/health") def locked(config: AuthConfig, host: str) -> bool: """Whether this app should ask for a password. See `AuthConfig.enabled`. `host` is the address the server binds, which is the app's own `server.host` setting and not anything a request carries: a `Host` header is written by whoever is talking, and a door that could be talked out of being a door is not one. """ if config.enabled == "always": return True if config.enabled == "never": return False return not _loopback(host) def _loopback(host: str) -> bool: """Whether binding here means "this machine only". `localhost` by name, and anything in 127.0.0.0/8 or ::1 by number. An empty host, or `0.0.0.0`, or a LAN address is not loopback — and an unparseable one is treated as not loopback too, because the failure to be careful about is guessing "private" and being wrong. """ if host in ("localhost", "::1"): return True try: return ipaddress.ip_address(host).is_loopback except ValueError: return False def cookie_name(config: AuthConfig, scope_secure: bool) -> str: """`__Host-` when the cookie will be Secure, plain otherwise. That prefix is a promise to the browser that the cookie is Secure, path-scoped to `/` and carries no Domain, and a browser will refuse to store one that is not — which presents as a login that appears to succeed and lands you back on the login page, with nothing in any log. So the name is chosen per deployment rather than fixed. """ return f"__Host-{config.cookie}" if is_secure(config, scope_secure) else config.cookie def cookie_names(config: AuthConfig) -> tuple[str, str]: """Both names, secure first. Read and cleared together, because which one was set depends on `secure_cookie` and on the scheme the login happened over — and clearing only one leaves a cookie the browser goes on offering.""" return f"__Host-{config.cookie}", config.cookie def is_secure(config: AuthConfig, scope_secure: bool) -> bool: setting = config.secure_cookie if setting == "always": return True if setting == "never": return False return scope_secure def token_from(conn: HTTPConnection | Scope, config: AuthConfig) -> str: """The session token this request carries, or "". Both cookie names are looked for, so flipping `secure_cookie` or moving behind TLS does not strand a live session under the other name. """ scope: Any = conn.scope if isinstance(conn, HTTPConnection) else conn for key, value in scope.get("headers", ()): if key == b"cookie": jar = SimpleCookie() try: jar.load(value.decode("latin-1")) except Exception: # a cookie header that is not one return "" for name in cookie_names(config): if name in jar: return jar[name].value return "" def client_address(conn: HTTPConnection | Scope) -> str: """Who is asking, as well as it can be known, for the log to say so. Behind a reverse proxy the peer is a container on the same Docker network and says nothing about who is at the other end; the address worth writing down is the first hop of `X-Forwarded-For`, which the proxy sets. Both are reported when they differ, because the header is only as trustworthy as whoever sent it — which is why nothing is *decided* from this, only logged. See `AuthStore.check_password` for that argument in full. That header is also the one piece of a stranger's own writing that ends up in the log, so only the characters an address is made of survive the trip: a line in this log is something fail2ban reads and a person believes, and neither should be forgeable by whoever is knocking. """ scope: Any = conn.scope if isinstance(conn, HTTPConnection) else conn peer = (scope.get("client") or ("", 0))[0] or "unknown" for key, value in scope.get("headers", ()): if key == b"x-forwarded-for": first = value.decode("latin-1").split(",")[0] claimed = "".join(c for c in first if c.isalnum() or c in ".:%-")[:45] if claimed and claimed != peer: return f"{claimed} via {peer}" return peer #: Prefixes whose refusal is JSON rather than a redirect. A caller that asked #: for data and is sent a login page reads it as a 200 full of HTML where its #: JSON should be; `{"detail": ...}` with a 401 is something it can act on. JSON_PREFIXES = ("/api", "/ws", "/_jobs", "/_auth") class RequireLogin: """Everything is shut except the open list. Raw ASGI, so it covers sockets. Deliberately not `BaseHTTPMiddleware`, which only sees `http` scopes — a WebSocket would pass straight under it, and `/ws/jobs` streams the state of every job in the app. Whether the door is locked at all is decided once, at construction, from the config and the bind address: neither changes while the process runs, and deciding per request would mean re-deriving the same answer a thousand times a minute and having no single place to read it off. """ def __init__(self, app: ASGIApp, store: AuthStore, config: AuthConfig, open: tuple[str, ...] = (), host: str = "") -> None: self.app = app self.store = store self.config = config self.open = OPEN + tuple(open) self.locked = locked(config, host) async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: if scope["type"] not in ("http", "websocket") or not self.locked: return await self.app(scope, receive, send) path = scope.get("path", "") if any(path == p.rstrip("/") or (p.endswith("/") and path.startswith(p)) for p in self.open): return await self.app(scope, receive, send) token = token_from(scope, self.config) # `to_thread`, because the store is SQLite and this is the event loop. session = await asyncio.to_thread(self.store.touch, token) if token else None if session is not None: # Parked on the scope so `/api/account` can flag which row in the # sessions list is the browser asking, and `/logout` can end the # right one. Not a header and not a dependency: the middleware is # the only thing that has verified it. scope["auth_token"] = token return await self.app(scope, receive, send) await self._refuse(scope, receive, send, path) async def _refuse(self, scope: Scope, receive: Receive, send: Send, path: str) -> None: """No session. Say so in whatever the caller can understand.""" if scope["type"] == "websocket": # Sent before accepting, which the ASGI server turns into an HTTP # 403 on the handshake. The reconnect backoff in `` then # does the right thing by itself. await send({"type": "websocket.close", "code": 1008}) return response: Response # A GET of anything that is not an API path is a page being asked for, # whatever the caller put in `Accept` — curl and a browser want the # same thing there, and a 401 in place of the login page is a worse # answer to both. Everything else is JSON, including a POST to a page # path: a form submitted without a session has nowhere useful to land. if scope.get("method") == "GET" and not path.startswith(JSON_PREFIXES): # Carry where they were going, so a bookmarked deep link survives # the login. Only ever a path from this app's own scope — but it is # being written into a query string, and the scope has already # decoded it, so a path holding a `&` or a `%` would arrive at the # login page as a different path or as nothing. `quote` puts it back # the way `URLSearchParams` will read it. target = "/login" + (f"?next={quote(path)}" if path not in ("/", "") else "") response = RedirectResponse(target, status_code=303) else: response = JSONResponse({"detail": "Not signed in"}, status_code=401) await response(scope, receive, send)