730 lines
35 KiB
Python
730 lines
35 KiB
Python
"""The lock on the door: is there a session, and what happens when there isn't.
|
|
|
|
Six things live here — when the door is locked at all, who gets past it, the
|
|
cookie and the bearer header that say so, the rule that another site's page
|
|
gets nothing changed, the password asked again from behind a session
|
|
(`confirm_password`, and `confirm_current` for a header), and the closing of a socket whose credential has ended.
|
|
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.
|
|
A reverse proxy on the same machine defeats the bind address, so an app `auto`
|
|
left open refuses any request a proxy forwarded; see
|
|
`RequireLogin._refuse_proxied`.
|
|
|
|
## Three credentials, two carriers
|
|
|
|
A session cookie is what the password and a passkey open, and it is what a
|
|
browser carries. An API token (`AuthStore.create_token`) is what a script
|
|
carries, as `Authorization: Bearer <token>`, and it is looked up on every
|
|
request the way a session is, so revoking it takes effect on the next call.
|
|
The cookie is read first and wins; the header is read only when there is no
|
|
live session. A token opens every door the session does except the account:
|
|
a request carrying one for `/api/account` or `/logout` is answered 403
|
|
(`ACCOUNT`), so a token that leaked cannot mint another, revoke the owner's
|
|
sessions or read the list of ways in. An app adds its own session-only routes
|
|
through `connect(session_only=...)`: anything that reads or replaces the
|
|
database as a file belongs there, since the file holds the password hash and
|
|
these rows, and a token that could fetch or swap it would hold the account
|
|
after all. A token that is not live is a 401 and a
|
|
WARNING line, like a wrong password; it is not counted against the lockout,
|
|
since 256 random bits are not guessed and the counter would only hand a
|
|
stranger a way to lock the owner out.
|
|
|
|
## Another site's page
|
|
|
|
`SameSite=Lax` keeps the session cookie off a cross-site `POST`, which covers
|
|
a locked app. An unlocked one on loopback has no cookie to withhold, so a page
|
|
open in the same browser could `POST` to `http://127.0.0.1:8787/api/...` with
|
|
a `text/plain` body, which needs no preflight, and every route that takes no
|
|
body acted on it; a WebSocket handshake is not subject to CORS at all, so the
|
|
same page could open `/ws/jobs` and read every job and notice. So a request
|
|
that changes something is refused when the browser says it came from another
|
|
site (`Sec-Fetch-Site`, else `Origin` against `Host` or `AuthConfig.origin`),
|
|
and a body of a type another site could send without a preflight is refused
|
|
whoever sent it: the API is JSON. Locked or not, because the rule costs two
|
|
header reads and a locked app with `secure_cookie: never` on a LAN is a real
|
|
deployment. See `cross_site`.
|
|
|
|
That comparison is against the request's own `Host`, and a page served from
|
|
`rebind.example` whose name is pointed at 127.0.0.1 arrives with a `Host` and
|
|
an `Origin` that agree. So an app `auto` left open also refuses any request
|
|
whose `Host` is not a loopback name, a `.localhost` name or the host of
|
|
`AuthConfig.origin`, with the same 421 as a forwarded one, whatever else it
|
|
carries: a browser that sends no fetch metadata and no `Origin` on a read is
|
|
still a rebound page. A loopback app is reached as `localhost` or
|
|
`127.0.0.1`, and a request that names another host for it came through a
|
|
proxy or a rebinding, neither of which the bind address can see. A test
|
|
client names the host it is given (`base_url="http://127.0.0.1"`).
|
|
|
|
## A socket outlives its handshake
|
|
|
|
The door is checked when a socket opens, and the socket stays open for the
|
|
life of the tab. So a route that ends a credential (`/logout`, a password
|
|
change, a revoked session or token) runs `close_ended_sockets` after its
|
|
answer, which asks the store about every open socket's cookie or bearer header
|
|
and closes the ones it no longer knows with 1008. Expiry ends no request, so
|
|
`connect` also runs `sweep_ended_sockets`, which does the same every `SWEEP`
|
|
seconds. A tab's reconnect then meets the door. The sockets are the app's:
|
|
`app.state.bus`, which `pipeline.web.connect` sets, and an app without one has
|
|
nothing to close.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import asyncio
|
|
import ipaddress
|
|
import logging
|
|
from typing import Any
|
|
from urllib.parse import quote, urlsplit
|
|
|
|
from fastapi import HTTPException
|
|
from starlette.requests import HTTPConnection, cookie_parser
|
|
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")
|
|
|
|
#: What a bearer token cannot reach: the account, which is managed from a
|
|
#: browser with a session, and the sign-out of a session a token has not got.
|
|
#: Matched as `OPEN` is. Everything else a session opens, a token opens.
|
|
ACCOUNT: tuple[str, ...] = ("/api/account", "/api/account/", "/logout")
|
|
|
|
#: What a request carrying a token for the account is told.
|
|
TOKEN_NOT_HERE = ("An API token opens the API, not the account. Sign in with the "
|
|
"password or a passkey to manage it.")
|
|
|
|
|
|
def matches(path: str, names: tuple[str, ...]) -> bool:
|
|
"""Whether `path` is one of `names`: a name ending in `/` is a prefix, any
|
|
other is matched whole. The one rule for `OPEN` and `ACCOUNT`."""
|
|
return any(path == name.rstrip("/") or (name.endswith("/") and path.startswith(name))
|
|
for name in names)
|
|
|
|
|
|
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.
|
|
|
|
Parsed per `;`-separated pair by Starlette's `cookie_parser`, as a browser
|
|
does, and not by `http.cookies.SimpleCookie`, whose `load` returns an
|
|
empty jar for the whole header when one cookie in it has a space or JSON
|
|
in its value: a sibling app on the parent domain setting `theme=dark mode`
|
|
signed the owner out on every request. A pair that is not a cookie is
|
|
skipped, so a garbage header is no cookie rather than a 500.
|
|
"""
|
|
scope: Any = conn.scope if isinstance(conn, HTTPConnection) else conn
|
|
for key, value in scope.get("headers", ()):
|
|
if key == b"cookie":
|
|
jar = cookie_parser(value.decode("latin-1"))
|
|
for name in cookie_names(config):
|
|
if jar.get(name):
|
|
return jar[name]
|
|
return ""
|
|
|
|
|
|
def bearer_from(conn: HTTPConnection | Scope) -> str:
|
|
"""The API token this request carries in `Authorization: Bearer`, or "".
|
|
|
|
Only that header and only that scheme: a token in a query string would
|
|
land in every access log between the script and the app, and `Basic` is
|
|
a password, which has its own door.
|
|
"""
|
|
value = _header(conn, b"authorization")
|
|
scheme, _, token = value.strip().partition(" ")
|
|
if scheme.lower() != "bearer":
|
|
return ""
|
|
return token.strip()
|
|
|
|
|
|
def _header(conn: HTTPConnection | Scope, name: bytes) -> str:
|
|
scope: Any = conn.scope if isinstance(conn, HTTPConnection) else conn
|
|
for key, value in scope.get("headers", ()):
|
|
if key == name:
|
|
return value.decode("latin-1")
|
|
return ""
|
|
|
|
|
|
def credential_live(store: AuthStore, config: AuthConfig,
|
|
conn: HTTPConnection | Scope) -> bool:
|
|
"""Whether what this request carries still opens the door: its cookie's
|
|
session, else its bearer token. What `RequireLogin` decides from, asked
|
|
again of an open socket by `close_ended_sockets`."""
|
|
token = token_from(conn, config)
|
|
if token and store.touch(token) is not None:
|
|
return True
|
|
bearer = bearer_from(conn)
|
|
return bool(bearer) and store.touch_token(bearer) is not None
|
|
|
|
|
|
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 rightmost hop of `X-Forwarded-For`, the one the proxy in front
|
|
of this app appended for the connection it accepted; every hop left of it
|
|
was in the request when it arrived and is whatever the caller wrote. nginx's
|
|
`$proxy_add_x_forwarded_for` appends rather than replaces, so the first hop
|
|
let an attacker name the address a fail2ban filter on this line bans.
|
|
Without that header, `X-Real-IP`, which such a proxy sets outright. The
|
|
claimed address and the peer are both reported when they differ, because a
|
|
header is only as trustworthy as the proxy that set it, which is why
|
|
nothing is *decided* from this, only logged. See
|
|
`AuthStore.check_password` for that argument in full.
|
|
|
|
The header is also the one piece of a stranger's writing that can end 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. The address stays the
|
|
first word after `from`, so a filter is one regex.
|
|
"""
|
|
scope: Any = conn.scope if isinstance(conn, HTTPConnection) else conn
|
|
peer = (scope.get("client") or ("", 0))[0] or "unknown"
|
|
forwarded = real = ""
|
|
for key, value in scope.get("headers", ()):
|
|
# The last of each, should a header arrive twice: a proxy that adds
|
|
# one rather than appending writes it after the caller's.
|
|
if key == b"x-forwarded-for":
|
|
forwarded = value.decode("latin-1")
|
|
elif key == b"x-real-ip":
|
|
real = value.decode("latin-1")
|
|
hop = forwarded.split(",")[-1] if forwarded.strip() else real
|
|
claimed = "".join(c for c in hop if c.isalnum() or c in ".:%-")[:45]
|
|
if claimed and claimed != peer:
|
|
return f"{claimed} via {peer}"
|
|
return peer
|
|
|
|
|
|
#: Headers a reverse proxy adds. Any one of them on a request to an app that
|
|
#: `auto` left open because it binds loopback means the bind address is not the
|
|
#: whole story: a proxy on this machine is passing on someone else.
|
|
FORWARDED = frozenset({b"forwarded", b"x-forwarded-for", b"x-forwarded-proto",
|
|
b"x-forwarded-host"})
|
|
|
|
#: What such a request is answered with, for whoever runs the proxy.
|
|
PROXIED = ("This app binds loopback and so asks for no password, but this request "
|
|
"came through a proxy. Set auth.enabled: always in config.yaml and restart.")
|
|
|
|
#: What a browser script's request naming another host is answered with.
|
|
REBOUND = ("This app binds loopback and so asks for no password, but this request "
|
|
"names a host that is not localhost. Open the app as http://localhost, or "
|
|
"set auth.enabled: always in config.yaml and restart.")
|
|
|
|
|
|
#: 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 = "",
|
|
session_only: tuple[str, ...] = ()) -> None:
|
|
self.app = app
|
|
self.store = store
|
|
self.config = config
|
|
self.open = OPEN + tuple(open)
|
|
#: What a token may not reach: the account, and whatever the app adds.
|
|
self.session_only = (*ACCOUNT, *session_only)
|
|
self.locked = locked(config, host)
|
|
#: Open only because `auto` saw loopback; see `_refuse_proxied`.
|
|
self.watch_proxy = config.enabled == "auto" and not self.locked
|
|
self.warned = False
|
|
|
|
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
|
|
if scope["type"] not in ("http", "websocket"):
|
|
return await self.app(scope, receive, send)
|
|
# Another site's page, locked or not: see the module docstring.
|
|
refused = cross_site(scope, self.config.origin)
|
|
if refused is not None:
|
|
return await self._answer(scope, receive, send, *refused)
|
|
if not self.locked:
|
|
if self.watch_proxy and _forwarded(scope):
|
|
return await self._refuse_proxied(scope, receive, send, PROXIED)
|
|
if self.watch_proxy and _rebound(scope, self.config.origin):
|
|
return await self._refuse_proxied(scope, receive, send, REBOUND)
|
|
return await self.app(scope, receive, send)
|
|
|
|
path = scope.get("path", "")
|
|
if matches(path, 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)
|
|
|
|
bearer = bearer_from(scope)
|
|
if bearer:
|
|
held = await asyncio.to_thread(self.store.touch_token, bearer)
|
|
if held is not None:
|
|
if matches(path, self.session_only):
|
|
return await self._answer(scope, receive, send, 403, TOKEN_NOT_HERE)
|
|
# The row, for a route that wants to know it was a script.
|
|
scope["auth_bearer"] = held.id
|
|
return await self.app(scope, receive, send)
|
|
# The same line a wrong password writes, for the same reader. A
|
|
# script with a bad token gets JSON whatever it asked for: a
|
|
# redirect to the login page is for a browser, and a browser does
|
|
# not send this header.
|
|
log.warning("bad token from %s", client_address(scope))
|
|
return await self._answer(scope, receive, send, 401,
|
|
"That token is not valid here.")
|
|
|
|
await self._refuse(scope, receive, send, path)
|
|
|
|
async def _answer(self, scope: Scope, receive: Receive, send: Send,
|
|
status: int, detail: str) -> None:
|
|
"""A refusal in the shape the caller can act on: `{"detail"}` with the
|
|
status, or a 1008 close before the socket is accepted."""
|
|
if scope["type"] == "websocket":
|
|
await send({"type": "websocket.close", "code": 1008})
|
|
return
|
|
await JSONResponse({"detail": detail}, status_code=status)(scope, receive, send)
|
|
|
|
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 `<desk-jobs>` 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)
|
|
|
|
async def _refuse_proxied(self, scope: Scope, receive: Receive, send: Send,
|
|
detail: str) -> None:
|
|
"""421 for a forwarded request to an app `auto` left open, and for a
|
|
request that names a host it is not reached under (`_rebound`).
|
|
|
|
`auto` reads loopback as "this machine only", and a reverse proxy on
|
|
the same machine makes that false while every request still arrives
|
|
from 127.0.0.1. The peer cannot tell the proxy from a local browser,
|
|
only the headers the proxy adds can, so a request carrying one is
|
|
refused rather than served unlocked. A client can add the headers
|
|
itself, which only gets it refused. The Vite dev server's proxy adds
|
|
none (`xfwd` is off) and forwards `Host` unchanged, so `npm run dev`
|
|
is unaffected. Logged once at WARNING, since every request through
|
|
the proxy would repeat it.
|
|
"""
|
|
if not self.warned:
|
|
self.warned = True
|
|
log.warning("refused a proxied or rebound request to an unlocked app (%s): %s",
|
|
client_address(scope), detail)
|
|
if scope["type"] == "websocket":
|
|
await send({"type": "websocket.close", "code": 1008})
|
|
return
|
|
await JSONResponse({"detail": detail}, status_code=421)(scope, receive, send)
|
|
|
|
|
|
def _forwarded(scope: Scope) -> bool:
|
|
return any(key in FORWARDED for key, _ in scope.get("headers", ()))
|
|
|
|
|
|
def _rebound(scope: Scope, configured_origin: str) -> bool:
|
|
"""Whether a request reaches this loopback app under a name that is not
|
|
loopback: the shape of a DNS rebinding, where the page's own `Origin` and
|
|
the `Host` it sends agree and `_from_here` cannot tell.
|
|
|
|
Every request is judged, whatever headers it carries. A browser that sends
|
|
neither `Sec-Fetch-Site` nor `Origin` on a read is still a page on the
|
|
rebound name reading the API, and the only names a loopback app is reached
|
|
under are a loopback address, `localhost` and its subdomains, and the host
|
|
of `AuthConfig.origin`. A missing or unparseable `Host` names none of
|
|
them and is refused too.
|
|
"""
|
|
try:
|
|
host = urlsplit("//" + _header(scope, b"host")).hostname or ""
|
|
except ValueError: # an unparseable authority, e.g. `[`
|
|
return True
|
|
if _loopback(host) or host.endswith(".localhost"):
|
|
return False
|
|
allowed = urlsplit(configured_origin).hostname if configured_origin else ""
|
|
return not host or host != (allowed or "").lower()
|
|
|
|
|
|
# ------------------------------------------------------ the password again
|
|
|
|
def claim_attempt(conn: HTTPConnection) -> None:
|
|
"""The lockout, in front of every place a password can be guessed: 429
|
|
while it holds, else the guess is counted before it is derived.
|
|
|
|
`AuthStore.claim_attempt` decides and counts in one write transaction, so
|
|
concurrent guesses each see the ones before them and a window admits five
|
|
of them, not a threadpool's worth. A refused claim counts nothing, so
|
|
hammering while locked out does not extend the lockout. The caller then
|
|
checks with `check_password(..., claimed=True)`, which clears the count
|
|
when the guess was right. Called from both doors rather than living inside
|
|
`check_password`, because the same comparison is a counted guess here and
|
|
a bootstrap comparison in `auth.bootstrap`, which must not be able to lock
|
|
anyone out of their own restart.
|
|
"""
|
|
wait = conn.app.state.auth.claim_attempt()
|
|
if wait:
|
|
warn(conn, "attempt while locked out")
|
|
raise HTTPException(429, f"Too many attempts. Try again in {_spell(wait)}.",
|
|
headers={"Retry-After": str(wait)})
|
|
|
|
|
|
def confirm_password(conn: HTTPConnection, current: str) -> None:
|
|
"""The password again, from someone already signed in: changing it, adding
|
|
a passkey, minting a token, and any app route that must not be one
|
|
borrowed browser away from the account (`connect(session_only=...)`).
|
|
Counted and gated like the front door, because `current` is a guess at the
|
|
password made from behind a session: 429 while locked out, 403 when wrong.
|
|
|
|
It has nothing to confirm on an app with no password yet, which refuses
|
|
every guess, so a route that can run there asks `has_password()` first, as
|
|
the account routes do."""
|
|
claim_attempt(conn)
|
|
if not conn.app.state.auth.check_password(current, claimed=True):
|
|
warn(conn, "wrong current password")
|
|
raise HTTPException(403, "That is not the current password.")
|
|
|
|
|
|
#: Where a route whose body is a file takes the current password. A header and
|
|
#: not a field, because the body is the file itself; read before the first byte
|
|
#: of that body, so a refusal costs no upload.
|
|
CURRENT_HEADER = "x-current-password"
|
|
|
|
|
|
def confirm_current(conn: HTTPConnection) -> None:
|
|
"""The current password from the `X-Current-Password` header, for a route
|
|
that hands out or replaces the database as a file (`connect(session_only=...)`).
|
|
|
|
A session is not enough for a route that replaces the credentials: the
|
|
restored file brings its own password hash, passkeys and tokens, so a
|
|
borrowed signed-in browser that could restore a doctored backup would own
|
|
the account. Call it before reading the body. A missing or empty header is
|
|
a WARNING line and a 403 that counts nothing against the lockout, since a
|
|
missing field is not a guess; a wrong one goes through `confirm_password`,
|
|
which counts it, warns and answers 403, or 429 while locked out. An app
|
|
that never had a password (loopback, never locked) has nothing to confirm.
|
|
|
|
The check is a deliberately slow derivation, so a coroutine route runs it
|
|
in the threadpool. newsdesk's `/api/restore` is the caller.
|
|
"""
|
|
if not conn.app.state.auth.has_password():
|
|
return
|
|
current = conn.headers.get(CURRENT_HEADER, "")
|
|
if not current:
|
|
warn(conn, f"no current password for {conn.scope.get('method', '')} "
|
|
f"{conn.scope.get('path', '')}")
|
|
raise HTTPException(403, "This takes the current password in X-Current-Password.")
|
|
confirm_password(conn, current)
|
|
|
|
|
|
def warn(conn: HTTPConnection, what: str) -> None:
|
|
"""Write down that someone got it wrong, and who.
|
|
|
|
The whole record of who is knocking. There is no access log worth the name —
|
|
uvicorn is run quietly — and no table of attempts, because the log is the
|
|
record and a second copy of it would only ever disagree. WARNING so it
|
|
survives that level, one line per refusal, and the address first after
|
|
`from` so a fail2ban filter is one regex; see documentation/Password Protection.md.
|
|
|
|
The message does not name the package, because the logger already does:
|
|
with the usual `%(name)s: %(message)s` this module is `auth.middleware`,
|
|
and a line reading `auth.middleware: auth: wrong password` says it twice
|
|
and reads like a bug in the logging.
|
|
|
|
Nothing is *decided* from the address — `AuthStore.check_password` says why
|
|
it cannot be — so this is where it earns its keep: at the layer that can
|
|
drop the connection instead of answering it.
|
|
"""
|
|
log.warning("%s from %s", what, client_address(conn))
|
|
|
|
|
|
def _spell(seconds: int) -> str:
|
|
if seconds < 60:
|
|
return f"{seconds} seconds"
|
|
return f"{round(seconds / 60)} minutes"
|
|
|
|
|
|
# --------------------------------------------- sockets whose credential ended
|
|
|
|
#: How often, in seconds, `sweep_ended_sockets` asks about every open socket:
|
|
#: the longest an expired session or token keeps the socket it opened.
|
|
SWEEP = 60.0
|
|
|
|
|
|
async def close_ended_sockets(app: Any) -> int:
|
|
"""Close every open socket whose session or token has ended. Returns how
|
|
many it closed.
|
|
|
|
The door is checked at the handshake, and a socket stays open for the
|
|
life of the tab. So signing out, changing the password or revoking a
|
|
session or a token left the socket it had opened streaming to whoever
|
|
held it. Run after each of those, as a background task of the route, and
|
|
on a clock by `sweep_ended_sockets`, this asks the store about every
|
|
socket's cookie or bearer header (`credential_live`) and closes the ones
|
|
it no longer knows with 1008; a tab's reconnect then meets the door.
|
|
|
|
The sockets are `app.state.bus`: what `pipeline.web.connect` puts there,
|
|
or anything with a `sockets` tuple and an async `close(sockets, code,
|
|
reason)`. Nothing to do on an unlocked app, which has no sessions to
|
|
end, or on one without a bus.
|
|
"""
|
|
if not getattr(app.state, "auth_locked", False):
|
|
return 0
|
|
bus = getattr(app.state, "bus", None)
|
|
if bus is None:
|
|
return 0
|
|
store, config = app.state.auth, app.state.auth_config
|
|
sockets = bus.sockets
|
|
|
|
def ended() -> list[Any]:
|
|
return [ws for ws in sockets if not credential_live(store, config, ws)]
|
|
|
|
# `to_thread`, because the store is SQLite and this is the event loop.
|
|
gone = await asyncio.to_thread(ended)
|
|
return await bus.close(gone, 1008, "signed out") if gone else 0
|
|
|
|
|
|
async def sweep_ended_sockets(app: Any, every: float = SWEEP) -> None:
|
|
"""`close_ended_sockets` every `every` seconds, until cancelled.
|
|
|
|
The door is checked at the handshake only, and the routes that end a
|
|
credential close its sockets themselves. Expiry is seen by no route: a
|
|
session or token that runs out ends no request, so its socket streamed
|
|
until the tab reconnected. This closes it within `every` seconds.
|
|
`connect` starts it on a locked app and cancels it at shutdown. A sweep
|
|
that fails is logged and the next one runs, since a loop that died on
|
|
one busy database would leave every later expiry open.
|
|
"""
|
|
while True:
|
|
await asyncio.sleep(every)
|
|
try:
|
|
await close_ended_sockets(app)
|
|
except Exception:
|
|
log.warning("the socket sweep failed", exc_info=True)
|
|
|
|
|
|
# ------------------------------------------------------------ another site
|
|
|
|
#: The methods that change something. No `GET` here changes anything (see the
|
|
#: module docstring of `auth/router.py`), so these are the ones to guard.
|
|
UNSAFE = frozenset({"POST", "PUT", "PATCH", "DELETE"})
|
|
|
|
#: The bodies another site's page may send without the browser asking first:
|
|
#: the three CORS-safelisted types, and a body with no type at all. A
|
|
#: cross-site request with any other type is preflighted, and nothing here
|
|
#: answers a preflight, so it never leaves the browser.
|
|
SIMPLE_BODIES = frozenset({"", "text/plain", "application/x-www-form-urlencoded",
|
|
"multipart/form-data"})
|
|
|
|
CROSS_SITE = ("This request came from another site's page, and nothing here "
|
|
"changes on another site's say-so.")
|
|
|
|
|
|
def cross_site(scope: Scope, configured_origin: str = "") -> tuple[int, str] | None:
|
|
"""Why a request that changes something is refused, or None.
|
|
|
|
Two checks, the first for the socket too:
|
|
|
|
- **Where it came from.** `Sec-Fetch-Site` when the browser sends it,
|
|
which a page cannot set; otherwise `Origin`, which must name this host
|
|
or `configured_origin` (`AuthConfig.origin`, for a proxy that rewrites
|
|
`Host`). No `Origin` at all is a client that is not a browser page
|
|
(`curl`, a script with a token, a test) and passes.
|
|
- **What the body is.** A body of a type another site could send without
|
|
a preflight is refused, whoever sent it: the API is JSON.
|
|
|
|
A read is never refused, wherever it came from.
|
|
"""
|
|
if scope["type"] == "websocket":
|
|
if not _from_here(scope, configured_origin):
|
|
return 403, "another site's page cannot open this socket"
|
|
return None
|
|
if scope.get("method") not in UNSAFE:
|
|
return None
|
|
if not _from_here(scope, configured_origin):
|
|
return 403, CROSS_SITE
|
|
kind = _header(scope, b"content-type").split(";")[0].strip().lower()
|
|
if _has_body(scope) and kind in SIMPLE_BODIES:
|
|
return 415, ("Send the body as application/json, not "
|
|
f"{kind or 'without a content type'}.")
|
|
return None
|
|
|
|
|
|
def _from_here(scope: Scope, configured: str) -> bool:
|
|
"""Whether the page that sent this is this app's own, as far as the
|
|
browser says.
|
|
|
|
`Sec-Fetch-Site` decides when present: the browser sets it and a page
|
|
cannot, and it stays right behind a proxy that rewrites `Host`, where an
|
|
`Origin` comparison would refuse the app's own page. `none` is a request
|
|
the user made by typing or from a bookmark. Without it, `Origin` against
|
|
`Host` (the Vite dev server forwards `Host` unchanged) or against the
|
|
configured origin. `null` is a sandboxed frame or a `file://` page and is
|
|
never this app.
|
|
"""
|
|
site = _header(scope, b"sec-fetch-site")
|
|
if site:
|
|
return site in ("same-origin", "none")
|
|
origin = _header(scope, b"origin")
|
|
if not origin:
|
|
return True
|
|
if origin == "null":
|
|
return False
|
|
if configured and origin.rstrip("/") == configured.rstrip("/"):
|
|
return True
|
|
parts = urlsplit(origin)
|
|
host = _header(scope, b"host")
|
|
return bool(host) and (_authority(parts.scheme, parts.netloc)
|
|
== _authority(parts.scheme, host))
|
|
|
|
|
|
def _authority(scheme: str, netloc: str) -> str:
|
|
"""`host[:port]`, lowercased, without the scheme's default port, so
|
|
`Host: app.example.com:443` and `Origin: https://app.example.com` agree."""
|
|
netloc = netloc.lower()
|
|
default = {"http": ":80", "ws": ":80", "https": ":443", "wss": ":443"}.get(scheme, "")
|
|
return netloc[: -len(default)] if default and netloc.endswith(default) else netloc
|
|
|
|
|
|
def _has_body(scope: Scope) -> bool:
|
|
length = _header(scope, b"content-length")
|
|
# The header's presence, not its value, says a body follows; an empty value
|
|
# is malformed and is not given the benefit of the doubt.
|
|
chunked = any(key == b"transfer-encoding" for key, _ in scope.get("headers", ()))
|
|
return (length.isdigit() and int(length) > 0) or chunked
|