collapsarr 0.1.4__tar.gz → 0.2.0__tar.gz

collapsarr-0.2.0/.env.example

@@ -0,0 +1,49 @@
+# Collapsarr configuration.
+# Copy to `.env` and adjust as needed. All variables are optional — the values
+# below are the built-in defaults. Environment variables take precedence.
+#
+# On a bare-metal/PyPI install, none of these need to be set: Collapsarr picks
+# a writable, OS-appropriate data directory automatically (see
+# COLLAPSARR_DATA_DIR below). The Docker image sets COLLAPSARR_DATA_DIR itself
+# to point at the /config volume.
+
+# Root directory for application data (the SQLite database today; logs and
+# backups later). Created automatically if it doesn't exist. Defaults to the
+# OS user-data directory, e.g. ~/.local/share/collapsarr on Linux,
+# ~/Library/Application Support/collapsarr on macOS,
+# %LOCALAPPDATA%\collapsarr on Windows.
+# COLLAPSARR_DATA_DIR=/config
+
+# Filesystem path to the SQLite database file. Defaults to
+# <COLLAPSARR_DATA_DIR>/collapsarr.db; set this to override that location
+# directly.
+# COLLAPSARR_DATABASE_PATH=/config/collapsarr.db
+
+# Full SQLAlchemy database URL. When set, overrides COLLAPSARR_DATABASE_PATH.
+# COLLAPSARR_DATABASE_URL=sqlite:////config/collapsarr.db
+
+# API server bind address and port.
+COLLAPSARR_HOST=0.0.0.0
+COLLAPSARR_PORT=8282
+
+# Log level (DEBUG, INFO, WARNING, ERROR).
+COLLAPSARR_LOG_LEVEL=INFO
+
+# First-boot credential seed for headless/declarative deploys (Docker,
+# automation): set BOTH together and a fresh install is seeded with this
+# credential on first boot -- hashed before it's persisted, never stored or
+# logged in plaintext -- and skips the interactive /setup page entirely.
+# One-shot: this never overwrites a credential that already exists, even if
+# left set on a later boot. This is also the supported password-recovery/
+# lockout escape hatch, but only for a FRESH or already-locked-out install
+# with no credential configured yet -- it does not help recover a forgotten
+# password once a credential is already set (that takes clearing the
+# existing one directly, e.g. in the database).
+# COLLAPSARR_AUTH_USERNAME=admin
+# COLLAPSARR_AUTH_PASSWORD=change-me
+
+# Optional, only applied when the credential above is actually seeded.
+# COLLAPSARR_AUTH_METHOD: forms (default) | basic
+# COLLAPSARR_AUTH_REQUIRED: local_bypass (default) | enabled
+# COLLAPSARR_AUTH_METHOD=forms
+# COLLAPSARR_AUTH_REQUIRED=local_bypass

{collapsarr-0.1.4 → collapsarr-0.2.0}/Dockerfile

@@ -65,10 +65,12 @@ COPY docker-entrypoint.sh /docker-entrypoint.sh
 RUN chmod +x /docker-entrypoint.sh
 
 # Runtime configuration. COLLAPSARR_* mirror the app defaults (collapsarr/config.py);
-# PUID/PGID are consumed by the entrypoint.
+# PUID/PGID are consumed by the entrypoint. COLLAPSARR_DATA_DIR points at the
+# /config volume; database_path derives to /config/collapsarr.db (COL-46), so
+# existing /config volumes keep landing the DB at the same path on upgrade.
 ENV COLLAPSARR_HOST=0.0.0.0 \
     COLLAPSARR_PORT=8282 \
-    COLLAPSARR_DATABASE_PATH=/config/collapsarr.db \
+    COLLAPSARR_DATA_DIR=/config \
     PUID=1000 \
     PGID=1000
 

{collapsarr-0.1.4 → collapsarr-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: collapsarr
-Version: 0.1.4
+Version: 0.2.0
 Summary: An *arr-family companion app that adds downmixed (stereo/2.1/5.1) audio tracks to media missing them, via FFmpeg.
 Project-URL: Homepage, https://github.com/JovinJovinsson/Collapsarr
 Project-URL: Repository, https://github.com/JovinJovinsson/Collapsarr
@@ -14,6 +14,8 @@ Classifier: Topic :: Multimedia :: Sound/Audio
 Requires-Python: >=3.12
 Requires-Dist: fastapi>=0.110
 Requires-Dist: httpx>=0.27
+Requires-Dist: itsdangerous>=2.0
+Requires-Dist: platformdirs>=4.0
 Requires-Dist: pydantic-settings>=2.2
 Requires-Dist: pydantic>=2.6
 Requires-Dist: sqlalchemy>=2.0
@@ -91,27 +93,30 @@ services:
     restart: unless-stopped
 ```
 
-Then open `http://localhost:8282`. `restart: unless-stopped` above means the
-container comes back automatically whenever it stops unexpectedly or the
-Docker daemon restarts (e.g. after a host reboot) — see
-[Running on startup](#running-on-startup) if you need it to survive a reboot
-on a bare-metal/PyPI install instead.
+Then open `http://localhost:8282` — you'll land on a one-time credential setup
+page (see [Authentication](#authentication) for how login is enforced,
+including the caveat if you're putting Collapsarr behind a reverse proxy).
+`restart: unless-stopped` above means the container comes back automatically
+whenever it stops unexpectedly or the Docker daemon restarts (e.g. after a
+host reboot) — see [Running on startup](#running-on-startup) if you need it
+to survive a reboot on a bare-metal/PyPI install instead.
 
 **PyPI (bare-metal):**
 
 ```bash
-pip install collapsarr
-COLLAPSARR_DATABASE_PATH=~/.local/share/collapsarr/collapsarr.db collapsarr
+pipx install collapsarr
+collapsarr
 ```
 
-The default database path (`/config/collapsarr.db`) assumes the Docker
-image's mounted `/config` volume — on a bare-metal install `/config` usually
-doesn't exist or isn't writable, so **set `COLLAPSARR_DATABASE_PATH` to a
-location your user owns**, as above (the parent directory is created for
-you). Requires FFmpeg on `PATH` — see [Requirements](#requirements) below.
-Open `http://localhost:8282`; see [Configuration](#configuration) for the
-full list of environment variables, and
-[Running on startup](#running-on-startup) for a systemd unit.
+No flags, no config file needed — Collapsarr stores its SQLite database
+under your platform's standard per-user data directory by default (e.g.
+`~/.local/share/collapsarr/collapsarr.db` on Linux; native per-OS locations
+on macOS/Windows), creating it automatically if it doesn't exist. Set
+`COLLAPSARR_DATA_DIR` if you'd rather it live somewhere else — see
+[Configuration](#configuration). Requires FFmpeg on `PATH` — see
+[Requirements](#requirements) below. Open `http://localhost:8282`; see
+[Configuration](#configuration) for the full list of environment variables,
+and [Running on startup](#running-on-startup) for a systemd unit.
 
 ## Requirements
 
@@ -130,6 +135,49 @@ full list of environment variables, and
 
   Verify with `ffmpeg -version`. Official builds/source: [ffmpeg.org/download.html](https://ffmpeg.org/download.html).
 
+## Authentication
+
+Collapsarr requires a one-time credential setup (`/setup`, first run) and,
+after that, logging in (`/login`) before the UI/API is usable — *except* from
+a caller Collapsarr considers "local". The **Login requirement** setting
+(Settings → General, `auth_required` in the API) controls this:
+
+| Mode | Behaviour |
+| --- | --- |
+| **Disabled for local addresses** (`local_bypass`, default) | A caller connecting from a loopback (`127.0.0.1`/`::1`) or private-range (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, etc.) address reaches the UI and API with no setup and no login. Anyone connecting from a routable/public address still has to authenticate normally. |
+| **Always required** (`enabled`) | Every caller is challenged, regardless of address. |
+
+**Reverse-proxy limitation:** local-address classification looks only at the
+*direct* TCP connection Collapsarr accepted — never an `X-Forwarded-For` (or
+similar) header, since that's supplied by the client and trivially spoofable.
+If Collapsarr sits behind a reverse proxy (nginx, Traefik, Cloudflare Tunnel,
+etc.), every request's direct peer is the proxy itself, which usually *is*
+local — meaning **every** client, including ones out on the internet, would
+be classified as local and skip authentication entirely. **If you run
+Collapsarr behind a reverse proxy, set the Login requirement to "Always
+required" (`auth_required=enabled`)** until a future release adds
+trusted-proxy support (a stubbed-out capability today).
+
+**Headless deploys — seeding a credential without the setup page:** a
+declarative/automated deploy (Docker Compose, Ansible, etc.) has no human
+available to click through `/setup`. Set `COLLAPSARR_AUTH_USERNAME` and
+`COLLAPSARR_AUTH_PASSWORD` (together — see
+[Configuration](#configuration)) and a fresh install seeds that credential on
+first boot instead — hashed before it's persisted, never stored or logged in
+plaintext — and comes up already past the setup gate. `COLLAPSARR_AUTH_METHOD`
+and `COLLAPSARR_AUTH_REQUIRED` are honoured at the same time if set, otherwise
+the seeded credential gets the same defaults `/setup` would (`forms`,
+`local_bypass`).
+
+This doubles as the supported password-recovery/lockout escape hatch, but
+**only for a fresh or already-locked-out install with no credential
+configured yet** — seeding runs once and never overwrites a credential that
+already exists, even if the environment variables are still set on a later
+boot. It does **not** help recover a *forgotten* password once a credential
+is already set; that requires clearing the existing `auth_username`/
+`auth_password_hash` first (e.g. directly in the database) so the instance
+has no credential again, at which point re-seeding (or `/setup`) applies.
+
 ## Development
 
 ```bash
@@ -158,11 +206,16 @@ directory. See [`.env.example`](.env.example).
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `COLLAPSARR_DATABASE_PATH` | `/config/collapsarr.db` | SQLite database file path. Override this on bare-metal installs — the default assumes Docker's `/config` volume. |
-| `COLLAPSARR_DATABASE_URL` | *(derived from path)* | Full SQLAlchemy URL override. |
+| `COLLAPSARR_DATA_DIR` | *(OS user-data dir)* | Root directory for application data — the SQLite database today, logs/backups later. Defaults to `platformdirs.user_data_dir("collapsarr")` (e.g. `~/.local/share/collapsarr` on Linux). Created automatically if missing. The Docker image sets this to `/config` (its mounted volume) — see [Quick start](#quick-start). |
+| `COLLAPSARR_DATABASE_PATH` | *(derived from `COLLAPSARR_DATA_DIR`)* | SQLite database file path. Set this to override the location directly, independent of `COLLAPSARR_DATA_DIR`. |
+| `COLLAPSARR_DATABASE_URL` | *(derived from path)* | Full SQLAlchemy URL override — takes precedence over both of the above. |
 | `COLLAPSARR_HOST` | `0.0.0.0` | API server bind address. |
 | `COLLAPSARR_PORT` | `8282` | API server bind port. |
 | `COLLAPSARR_LOG_LEVEL` | `INFO` | Log level. |
+| `COLLAPSARR_AUTH_USERNAME` | *(unset)* | First-boot credential seed: UI username. Set together with `COLLAPSARR_AUTH_PASSWORD` — see [Authentication](#authentication). |
+| `COLLAPSARR_AUTH_PASSWORD` | *(unset)* | First-boot credential seed: UI password. Hashed before being persisted; never stored or logged in plaintext. |
+| `COLLAPSARR_AUTH_METHOD` | *(unset — `forms`)* | Optional, only applied when the seed credential above is actually seeded: `forms` or `basic`. |
+| `COLLAPSARR_AUTH_REQUIRED` | *(unset — `local_bypass`)* | Optional, only applied when the seed credential above is actually seeded: `enabled` or `local_bypass`. |
 
 ## Running on startup
 

{collapsarr-0.1.4 → collapsarr-0.2.0}/README.md

@@ -65,27 +65,30 @@ services:
     restart: unless-stopped
 ```
 
-Then open `http://localhost:8282`. `restart: unless-stopped` above means the
-container comes back automatically whenever it stops unexpectedly or the
-Docker daemon restarts (e.g. after a host reboot) — see
-[Running on startup](#running-on-startup) if you need it to survive a reboot
-on a bare-metal/PyPI install instead.
+Then open `http://localhost:8282` — you'll land on a one-time credential setup
+page (see [Authentication](#authentication) for how login is enforced,
+including the caveat if you're putting Collapsarr behind a reverse proxy).
+`restart: unless-stopped` above means the container comes back automatically
+whenever it stops unexpectedly or the Docker daemon restarts (e.g. after a
+host reboot) — see [Running on startup](#running-on-startup) if you need it
+to survive a reboot on a bare-metal/PyPI install instead.
 
 **PyPI (bare-metal):**
 
 ```bash
-pip install collapsarr
-COLLAPSARR_DATABASE_PATH=~/.local/share/collapsarr/collapsarr.db collapsarr
+pipx install collapsarr
+collapsarr
 ```
 
-The default database path (`/config/collapsarr.db`) assumes the Docker
-image's mounted `/config` volume — on a bare-metal install `/config` usually
-doesn't exist or isn't writable, so **set `COLLAPSARR_DATABASE_PATH` to a
-location your user owns**, as above (the parent directory is created for
-you). Requires FFmpeg on `PATH` — see [Requirements](#requirements) below.
-Open `http://localhost:8282`; see [Configuration](#configuration) for the
-full list of environment variables, and
-[Running on startup](#running-on-startup) for a systemd unit.
+No flags, no config file needed — Collapsarr stores its SQLite database
+under your platform's standard per-user data directory by default (e.g.
+`~/.local/share/collapsarr/collapsarr.db` on Linux; native per-OS locations
+on macOS/Windows), creating it automatically if it doesn't exist. Set
+`COLLAPSARR_DATA_DIR` if you'd rather it live somewhere else — see
+[Configuration](#configuration). Requires FFmpeg on `PATH` — see
+[Requirements](#requirements) below. Open `http://localhost:8282`; see
+[Configuration](#configuration) for the full list of environment variables,
+and [Running on startup](#running-on-startup) for a systemd unit.
 
 ## Requirements
 
@@ -104,6 +107,49 @@ full list of environment variables, and
 
   Verify with `ffmpeg -version`. Official builds/source: [ffmpeg.org/download.html](https://ffmpeg.org/download.html).
 
+## Authentication
+
+Collapsarr requires a one-time credential setup (`/setup`, first run) and,
+after that, logging in (`/login`) before the UI/API is usable — *except* from
+a caller Collapsarr considers "local". The **Login requirement** setting
+(Settings → General, `auth_required` in the API) controls this:
+
+| Mode | Behaviour |
+| --- | --- |
+| **Disabled for local addresses** (`local_bypass`, default) | A caller connecting from a loopback (`127.0.0.1`/`::1`) or private-range (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, etc.) address reaches the UI and API with no setup and no login. Anyone connecting from a routable/public address still has to authenticate normally. |
+| **Always required** (`enabled`) | Every caller is challenged, regardless of address. |
+
+**Reverse-proxy limitation:** local-address classification looks only at the
+*direct* TCP connection Collapsarr accepted — never an `X-Forwarded-For` (or
+similar) header, since that's supplied by the client and trivially spoofable.
+If Collapsarr sits behind a reverse proxy (nginx, Traefik, Cloudflare Tunnel,
+etc.), every request's direct peer is the proxy itself, which usually *is*
+local — meaning **every** client, including ones out on the internet, would
+be classified as local and skip authentication entirely. **If you run
+Collapsarr behind a reverse proxy, set the Login requirement to "Always
+required" (`auth_required=enabled`)** until a future release adds
+trusted-proxy support (a stubbed-out capability today).
+
+**Headless deploys — seeding a credential without the setup page:** a
+declarative/automated deploy (Docker Compose, Ansible, etc.) has no human
+available to click through `/setup`. Set `COLLAPSARR_AUTH_USERNAME` and
+`COLLAPSARR_AUTH_PASSWORD` (together — see
+[Configuration](#configuration)) and a fresh install seeds that credential on
+first boot instead — hashed before it's persisted, never stored or logged in
+plaintext — and comes up already past the setup gate. `COLLAPSARR_AUTH_METHOD`
+and `COLLAPSARR_AUTH_REQUIRED` are honoured at the same time if set, otherwise
+the seeded credential gets the same defaults `/setup` would (`forms`,
+`local_bypass`).
+
+This doubles as the supported password-recovery/lockout escape hatch, but
+**only for a fresh or already-locked-out install with no credential
+configured yet** — seeding runs once and never overwrites a credential that
+already exists, even if the environment variables are still set on a later
+boot. It does **not** help recover a *forgotten* password once a credential
+is already set; that requires clearing the existing `auth_username`/
+`auth_password_hash` first (e.g. directly in the database) so the instance
+has no credential again, at which point re-seeding (or `/setup`) applies.
+
 ## Development
 
 ```bash
@@ -132,11 +178,16 @@ directory. See [`.env.example`](.env.example).
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `COLLAPSARR_DATABASE_PATH` | `/config/collapsarr.db` | SQLite database file path. Override this on bare-metal installs — the default assumes Docker's `/config` volume. |
-| `COLLAPSARR_DATABASE_URL` | *(derived from path)* | Full SQLAlchemy URL override. |
+| `COLLAPSARR_DATA_DIR` | *(OS user-data dir)* | Root directory for application data — the SQLite database today, logs/backups later. Defaults to `platformdirs.user_data_dir("collapsarr")` (e.g. `~/.local/share/collapsarr` on Linux). Created automatically if missing. The Docker image sets this to `/config` (its mounted volume) — see [Quick start](#quick-start). |
+| `COLLAPSARR_DATABASE_PATH` | *(derived from `COLLAPSARR_DATA_DIR`)* | SQLite database file path. Set this to override the location directly, independent of `COLLAPSARR_DATA_DIR`. |
+| `COLLAPSARR_DATABASE_URL` | *(derived from path)* | Full SQLAlchemy URL override — takes precedence over both of the above. |
 | `COLLAPSARR_HOST` | `0.0.0.0` | API server bind address. |
 | `COLLAPSARR_PORT` | `8282` | API server bind port. |
 | `COLLAPSARR_LOG_LEVEL` | `INFO` | Log level. |
+| `COLLAPSARR_AUTH_USERNAME` | *(unset)* | First-boot credential seed: UI username. Set together with `COLLAPSARR_AUTH_PASSWORD` — see [Authentication](#authentication). |
+| `COLLAPSARR_AUTH_PASSWORD` | *(unset)* | First-boot credential seed: UI password. Hashed before being persisted; never stored or logged in plaintext. |
+| `COLLAPSARR_AUTH_METHOD` | *(unset — `forms`)* | Optional, only applied when the seed credential above is actually seeded: `forms` or `basic`. |
+| `COLLAPSARR_AUTH_REQUIRED` | *(unset — `local_bypass`)* | Optional, only applied when the seed credential above is actually seeded: `enabled` or `local_bypass`. |
 
 ## Running on startup
 

collapsarr-0.2.0/collapsarr/auth/__init__.py

@@ -0,0 +1,20 @@
+"""Authentication surface: first-run setup, Forms login, session enforcement.
+
+The full auth model (COL-50): a single operator credential (COL-49) gates the
+whole UI behind a signed-cookie session, while ``/api`` still accepts the
+Sonarr/Radarr-style API key for webhooks and tooling. See the submodules:
+
+* :mod:`~collapsarr.auth.session` -- the signed-cookie session middleware and
+  its login/logout helpers.
+* :mod:`~collapsarr.auth.enforcement` -- the request-gating middleware that
+  supersedes the old opt-in ``api_key_middleware``.
+* :mod:`~collapsarr.auth.routes` -- the ``/api/auth`` endpoints.
+"""
+
+from __future__ import annotations
+
+from .enforcement import enforce_auth_middleware
+from .routes import router as auth_router
+from .session import SessionMiddleware
+
+__all__ = ["SessionMiddleware", "auth_router", "enforce_auth_middleware"]

collapsarr-0.2.0/collapsarr/auth/enforcement.py

@@ -0,0 +1,245 @@
+"""Request-gating middleware for the whole app surface (COL-50).
+
+This is the successor to the old opt-in ``api_key_middleware`` (COL-26). Auth is
+now **unconditional**, not gated on a ``ui_auth_enabled`` toggle: the app still
+launches with zero config, but the UI cannot be used until a credential exists,
+and once it does, every UI route needs a session.
+
+Routing decision, per request:
+
+* ``/health`` -- always open (the Sonarr/Radarr ``/ping``-style liveness probe).
+* Static bundle assets (any path whose final segment has a file extension, e.g.
+  ``/assets/index-abc.js``, ``/favicon.svg``) -- always open, so the ``/setup``
+  and ``/login`` pages can load their JS/CSS before a session exists. These are
+  the SPA's public bundle, not sensitive data (which lives behind ``/api``).
+* ``/api/auth/{setup,login,status}`` -- always open, so the first-run and login
+  flows can run with no session yet. (``/api/auth/logout`` is *not* here: it
+  needs a session, and enforcement below supplies that.)
+* ``/api/*`` -- open with a valid session **or** the API key (``X-Api-Key``
+  header or ``?apikey=`` query param, preserving the Sonarr/Radarr webhook
+  convention); otherwise ``401``.
+* Everything else is a browser (SPA navigation) route:
+    * While **no credential exists** -- the first-run gate -- only ``/setup`` is
+      served; every other route ``303``-redirects to ``/setup``.
+    * Once a **credential exists**, a valid session serves the route; otherwise
+      it ``303``-redirects to ``/login`` (and ``/login``/``/setup`` themselves
+      redirect a logged-in user back into the app, and pre-credential ``/login``
+      redirects to ``/setup``).
+
+Required-mode (COL-51): the routing table above is what ``auth_required=
+"enabled"`` gets. When ``auth_required="local_bypass"`` (the default -- see
+:class:`collapsarr.settings.models.GlobalSettings`) *and* the caller's direct
+peer address is loopback or a private range, every check above is skipped --
+the request passes straight through, same as ``/health``. A caller whose peer
+address is routable/public is challenged exactly per the table, regardless of
+mode. This makes a LAN/localhost self-hoster's install frictionless (no
+setup, no login, no API key) while any routable-address client -- including
+one pretending to be local -- must still authenticate.
+
+Classification (:func:`_client_is_local`) reads only the literal peer address
+the ASGI server accepted the connection from (``request.client``) -- it never
+parses ``X-Forwarded-For`` or any other client-suppliable header, which any
+caller could forge. The consequence: behind a reverse proxy, the proxy's own
+address is what gets classified, not its upstream client's -- an install
+behind a reverse proxy should set ``auth_required="enabled"`` until a later
+ticket adds trusted-proxy support (see the README's Authentication section).
+
+The Basic auth method (COL-52) slots in at the browser-route branch below:
+when ``auth_method="basic"``, an unauthenticated browser request gets a ``401``
++ ``WWW-Authenticate: Basic`` challenge instead of a redirect to ``/login``; a
+valid ``Authorization: Basic`` header verified against the same credential
+(:func:`collapsarr.settings.service.verify_auth_password` -- COL-49's single
+operator credential, shared with Forms) mints a normal session
+(:func:`collapsarr.auth.session.log_in`), so every check *after* that --
+including ``/api``'s session-or-key rule -- is untouched. Only the initial UI
+challenge's transport differs between the two methods.
+"""
+
+from __future__ import annotations
+
+import base64
+import ipaddress
+import secrets
+from collections.abc import Awaitable, Callable
+
+from fastapi import Request, Response
+from fastapi.responses import JSONResponse, RedirectResponse
+
+from ..settings.models import AUTH_METHOD_BASIC, AUTH_REQUIRED_LOCAL_BYPASS
+from ..settings.service import get_global_settings, verify_auth_password
+from .session import is_authenticated, log_in
+
+API_KEY_HEADER = "X-Api-Key"
+"""Request header carrying the API key (Sonarr/Radarr convention)."""
+
+API_KEY_QUERY = "apikey"
+"""Query-parameter fallback for callers that cannot set a custom header."""
+
+AUTHORIZATION_HEADER = "authorization"
+BASIC_SCHEME_PREFIX = "basic "
+BASIC_REALM = "Collapsarr"
+"""``WWW-Authenticate`` realm presented in the Basic auth challenge."""
+
+HEALTH_PATH = "/health"
+SETUP_PATH = "/setup"
+LOGIN_PATH = "/login"
+APP_ROOT = "/"
+API_PREFIX = "/api"
+
+OPEN_API_PATHS = frozenset({"/api/auth/setup", "/api/auth/login", "/api/auth/status"})
+"""``/api`` endpoints reachable before any session/credential exists."""
+
+_REDIRECT_STATUS = 303
+"""``See Other``: gate redirects are GET navigations, so switch method to GET."""
+
+
+def _extract_key(request: Request) -> str | None:
+    """Return the presented API key from the header, then query string, if any."""
+    header = request.headers.get(API_KEY_HEADER)
+    if header:
+        return header
+    return request.query_params.get(API_KEY_QUERY) or None
+
+
+def _parse_basic_credentials(request: Request) -> tuple[str, str] | None:
+    """Decode an ``Authorization: Basic <base64>`` header into
+    ``(username, password)``, or ``None`` if it is absent or malformed."""
+    header = request.headers.get(AUTHORIZATION_HEADER)
+    if header is None or not header.lower().startswith(BASIC_SCHEME_PREFIX):
+        return None
+    try:
+        decoded = base64.b64decode(header[len(BASIC_SCHEME_PREFIX) :].strip()).decode("utf-8")
+    except (ValueError, UnicodeDecodeError):
+        return None
+    username, separator, password = decoded.partition(":")
+    if not separator:
+        return None
+    return username, password
+
+
+def _basic_challenge() -> Response:
+    """The ``401`` + ``WWW-Authenticate: Basic`` response for an
+    unauthenticated request under the Basic auth method (COL-52)."""
+    return JSONResponse(
+        status_code=401,
+        content={"detail": "Basic authentication required."},
+        headers={"WWW-Authenticate": f'Basic realm="{BASIC_REALM}"'},
+    )
+
+
+def _client_is_local(request: Request) -> bool:
+    """Whether the request's direct TCP peer is loopback or a private-range address.
+
+    Reads ``request.client`` -- the literal address the ASGI server accepted
+    the connection from -- and nothing else. In particular this deliberately
+    does **not** consult ``X-Forwarded-For`` (or any other header): those are
+    supplied by the client and trivially spoofable, so trusting them here
+    would let any external caller claim to be local and bypass auth entirely.
+    The tradeoff (documented in the module docstring and the README) is that
+    an install behind a reverse proxy sees the proxy's own peer address, not
+    its upstream client's -- trusted-proxy support is a later stub.
+    """
+    client = request.client
+    if client is None:
+        return False
+    try:
+        address = ipaddress.ip_address(client.host)
+    except ValueError:
+        # Not a literal IP address (seen in some non-network test harnesses) --
+        # treat conservatively as not local.
+        return False
+    return address.is_loopback or address.is_private
+
+
+def _is_static_asset(path: str) -> bool:
+    """Whether ``path`` names a bundled static file (has a file extension).
+
+    SPA navigation routes are extensionless (``/``, ``/wanted``, ``/setup``);
+    built assets carry a hashed filename with an extension
+    (``/assets/index-abc.js``, ``/favicon.svg``). Serving the public JS/CSS
+    bundle unauthenticated is what lets the login/setup pages render at all.
+    """
+    return "." in path.rsplit("/", 1)[-1]
+
+
+async def enforce_auth_middleware(
+    request: Request,
+    call_next: Callable[[Request], Awaitable[Response]],
+) -> Response:
+    """Gate every request per the routing table in the module docstring."""
+    path = request.url.path
+
+    if path == HEALTH_PATH or path in OPEN_API_PATHS or _is_static_asset(path):
+        return await call_next(request)
+
+    session_factory = request.app.state.session_factory
+    with session_factory() as session:
+        settings = get_global_settings(session)
+        credential_set = settings.auth_username is not None
+        expected_key = settings.api_key
+        auth_required = settings.auth_required
+        auth_method = settings.auth_method
+        auth_username = settings.auth_username
+
+    if auth_required == AUTH_REQUIRED_LOCAL_BYPASS and _client_is_local(request):
+        # local_bypass + a loopback/private-range peer: trust the network,
+        # skip every check below (first-run gate, session, API key) same as
+        # /health. A non-local peer falls through to the normal routing.
+        return await call_next(request)
+
+    authed = is_authenticated(request)
+
+    if path.startswith(API_PREFIX):
+        if authed:
+            return await call_next(request)
+        provided = _extract_key(request)
+        if provided is not None and secrets.compare_digest(provided, expected_key):
+            return await call_next(request)
+        return JSONResponse(
+            status_code=401,
+            content={"detail": "Invalid or missing API key."},
+        )
+
+    # --- Browser (SPA navigation) routes -------------------------------------
+    if not credential_set:
+        # First-run gate: only the setup page is reachable.
+        if path == SETUP_PATH:
+            return await call_next(request)
+        return RedirectResponse(url=SETUP_PATH, status_code=_REDIRECT_STATUS)
+    assert auth_username is not None  # credential_set is True past this point
+
+    if path == SETUP_PATH:
+        # Credential already exists -- setup is done.
+        if authed:
+            return RedirectResponse(url=APP_ROOT, status_code=_REDIRECT_STATUS)
+        if auth_method == AUTH_METHOD_BASIC:
+            return _basic_challenge()
+        return RedirectResponse(url=LOGIN_PATH, status_code=_REDIRECT_STATUS)
+
+    if auth_method == AUTH_METHOD_BASIC:
+        # No Forms /login page under this method -- every other browser route
+        # (including /login itself, if visited directly) is challenged or
+        # passed the same way.
+        if authed:
+            return await call_next(request)
+        creds = _parse_basic_credentials(request)
+        if creds is not None and creds[0] == auth_username:
+            with session_factory() as session:
+                password_ok = verify_auth_password(session, creds[1])
+            if password_ok:
+                # Same credential core as Forms (COL-49) -- mint a session so
+                # this browser's subsequent /api calls keep working the
+                # unchanged session-or-key way; only the initial UI challenge
+                # differs.
+                log_in(request, auth_username, remember=False)
+                return await call_next(request)
+        return _basic_challenge()
+
+    if path == LOGIN_PATH:
+        if authed:
+            return RedirectResponse(url=APP_ROOT, status_code=_REDIRECT_STATUS)
+        return await call_next(request)
+
+    if authed:
+        return await call_next(request)
+    return RedirectResponse(url=LOGIN_PATH, status_code=_REDIRECT_STATUS)