Source code for argos.server.auth
"""Bearer-token authentication and the origin allow-list.
The server binds 127.0.0.1, but any web page the observer opens can still
*reach* localhost. Two independent guards keep such pages out:
- a per-launch random token (``secrets.token_urlsafe``) that every route but
``GET /api/health`` requires — as ``Authorization: Bearer`` over HTTP, as
``?token=`` on WebSockets, because browsers cannot set WebSocket headers;
- an origin allow-list: CORS for HTTP, and an explicit ``Origin`` check on
WebSockets, which CORS does not cover;
- a ``Host`` allow-list (loopback names only, when the server is bound to
loopback) and a refusal of any HTTP request whose ``Origin`` is foreign.
CORS only stops a page from *reading* an answer; a DNS-rebinding page is
same-origin once its hostname resolves to 127.0.0.1, so it needs no
preflight and its request would still *run*. Its ``Host`` (and ``Origin``)
name the attacker's domain, which these checks refuse.
"""
from __future__ import annotations
import re
import secrets
from fastapi import Request
from argos.server.errors import ApiError
#: Origins the front-end can legitimately run from: the Vite dev server or a
#: preview on any localhost port, and the Tauri webview on each platform.
ALLOWED_ORIGIN_REGEX = (
r"^(http://(localhost|127\.0\.0\.1)(:\d{1,5})?"
r"|tauri://localhost"
r"|http://tauri\.localhost)$"
)
_ALLOWED_ORIGIN = re.compile(ALLOWED_ORIGIN_REGEX)
#: Host names a loopback-bound server answers to (the Tauri webview included).
LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1", "tauri.localhost"})
#: WebSocket close codes (4000–4999 is the application range).
WS_CLOSE_UNAUTHORIZED = 4401
WS_CLOSE_FORBIDDEN_ORIGIN = 4403
[docs]
def make_token() -> str:
"""A fresh random token for one server launch."""
return secrets.token_urlsafe(32)
[docs]
def origin_allowed(origin: str | None) -> bool:
"""True when *origin* may talk to the server.
A missing ``Origin`` header means a non-browser client (curl, a test, the
Tauri sidecar supervisor): the token alone authenticates it.
"""
return origin is None or bool(_ALLOWED_ORIGIN.match(origin))
[docs]
def is_loopback(host: str) -> bool:
"""True for the interfaces that keep the server off the network."""
return host.strip("[]") in ("127.0.0.1", "localhost", "::1")
[docs]
def host_name(header: str | None) -> str | None:
"""The host part of a ``Host`` header, lower-cased, without port or brackets."""
if not header:
return None
header = header.strip().lower()
if header.startswith("["): # [::1]:8742
end = header.find("]")
return header[1:end] if end > 0 else None
return header.rsplit(":", 1)[0] if header.count(":") == 1 else header
[docs]
def allowed_hosts(bound_host: str) -> frozenset[str] | None:
"""Host names to accept, or ``None`` (any) when bound to a network interface.
A server deliberately bound to a LAN address is reached under names and
addresses this process cannot know; the token and the origin checks then
stand alone (the CLI already warns about such a bind).
"""
if not is_loopback(bound_host):
return None
return LOOPBACK_HOSTS | {bound_host.strip("[]").lower()}
def host_allowed(header: str | None, allowed: frozenset[str] | None) -> bool:
if allowed is None:
return True
name = host_name(header)
return name is not None and name in allowed
[docs]
class TokenAuth:
"""Constant-time comparison against the launch token."""
def __init__(self, token: str) -> None:
if not token:
raise ValueError("token must not be empty")
self._token = token.encode("utf-8")
def check(self, presented: str | None) -> bool:
if not presented:
return False
return secrets.compare_digest(presented.encode("utf-8"), self._token)
[docs]
def require(self, request: Request) -> None:
"""FastAPI dependency: raise ``401 unauthorized`` without a valid bearer token."""
header = request.headers.get("authorization", "")
scheme, _, value = header.partition(" ")
if scheme.lower() != "bearer" or not self.check(value.strip()):
raise ApiError(
401,
"unauthorized",
"Missing or invalid bearer token",
headers={"WWW-Authenticate": "Bearer"},
)