Files
ServiceMap-Public/backend/app/auth.py
NuklearRabbit adc2c70c21 ServiceMap: update tests and backend/app (+7 areas)
Public changes compared with the previous published export:
89 files changed.

Affected areas:
- backend/app: 21 files
- dependencies: 5 files
- deployment and CI: 6 files
- documentation: 2 files
- frontend: 3 files
- frontend/src: 20 files
- project files: 1 file
- tests: 30 files
- unraid: 1 file

Changed files:
- Updated: ".env.example"
- Updated: "Dockerfile.unraid"
- Updated: "README.md"
- Updated: "backend/Dockerfile"
- Added: "backend/app/alerts.py"
- Updated: "backend/app/auth.py"
- Added: "backend/app/backups.py"
- Updated: "backend/app/config_io.py"
- Updated: "backend/app/demo.py"
- Updated: "backend/app/discovery.py"
- Updated: "backend/app/discovery_store.py"
- Updated: "backend/app/docker_discovery.py"
- Updated: "backend/app/events.py"
- Updated: "backend/app/evidence.py"
- Updated: "backend/app/health.py"
- Updated: "backend/app/incidents.py"
- Added: "backend/app/loops.py"
- Updated: "backend/app/main.py"
- Updated: "backend/app/models.py"
- Updated: "backend/app/observation.py"
- Updated: "backend/app/probes.py"
- Added: "backend/app/response_cache.py"
- Updated: "backend/app/scheduler.py"
- Updated: "backend/app/semantic.py"
- Updated: "backend/app/store.py"
- Updated: "backend/pyproject.toml"
- Updated: "backend/tests/test_api.py"
- Updated: "backend/tests/test_config_io.py"
- Updated: "backend/tests/test_demo.py"
- Updated: "backend/tests/test_discovery_v120.py"
- Updated: "backend/tests/test_health.py"
- Updated: "backend/tests/test_probes.py"
- Updated: "backend/tests/test_scheduler.py"
- Updated: "backend/tests/test_v130_probe_reachability.py"
- Updated: "backend/tests/test_v160_evidence_changes.py"
- Added: "backend/tests/test_v163_alerts.py"
- Added: "backend/tests/test_v163_backups.py"
- Added: "backend/tests/test_v163_data_integrity.py"
- Added: "backend/tests/test_v163_efficiency.py"
- Added: "backend/tests/test_v163_health_performance.py"
- Added: "backend/tests/test_v163_loops.py"
- Added: "backend/tests/test_v163_management.py"
- Added: "backend/tests/test_v163_realtime.py"
- Added: "backend/tests/test_v163_security.py"
- Added: "backend/tests/test_v163_semantic_etag.py"
- Added: "compose.demo.yaml"
- Updated: "compose.yaml"
- Added: "docker-compose.broker.yml"
- Updated: "docker-compose.yml"
- Updated: "docs/ARCHITECTURE.md"
- Added: "frontend/e2e/a11y.spec.ts"
- Updated: "frontend/e2e/demo.spec.ts"
- Updated: "frontend/index.html"
- Updated: "frontend/nginx.conf"
- Updated: "frontend/package-lock.json"
- Updated: "frontend/package.json"
- Updated: "frontend/playwright.config.ts"
- Updated: "frontend/src/App.tsx"
- Updated: "frontend/src/LivingEdge.tsx"
- Added: "frontend/src/activityView.test.ts"
- Added: "frontend/src/activityView.ts"
- Updated: "frontend/src/api.ts"
- Added: "frontend/src/apiAuth.test.ts"
- Added: "frontend/src/components/ActionsMenu.tsx"
- Added: "frontend/src/components/ConfirmDialog.test.tsx"
- Added: "frontend/src/components/ConfirmDialog.tsx"
- Added: "frontend/src/components/StatusIcon.tsx"
- Updated: "frontend/src/demo/DemoWalkthrough.test.ts"
- Updated: "frontend/src/demo/DemoWalkthrough.tsx"
- Added: "frontend/src/elk-worker-url.d.ts"
- Added: "frontend/src/labels.ts"
- Updated: "frontend/src/main.tsx"
- Added: "frontend/src/realtime/refreshPlan.test.ts"
- Added: "frontend/src/realtime/refreshPlan.ts"
- Updated: "frontend/src/realtime/useRealtimeEvents.ts"
- Added: "frontend/src/routing/urlState.test.ts"
- Added: "frontend/src/routing/urlState.ts"
- Updated: "frontend/src/styles.css"
- Added: "frontend/src/topology/GraphListView.test.tsx"
- Added: "frontend/src/topology/GraphListView.tsx"
- Updated: "frontend/src/topology/ServiceNode.tsx"
- Updated: "frontend/src/topology/TopologyCommandBar.tsx"
- Added: "frontend/src/topology/semanticGraph.test.ts"
- Updated: "frontend/src/topology/semanticGraph.ts"
- Added: "frontend/src/topologyLayout.test.ts"
- Updated: "frontend/src/topologyLayout.ts"
- Updated: "package-lock.json"
- Updated: "package.json"
- Updated: "unraid/my-servicemap.xml"

Export provenance/manifests refreshed; excluded from the change summary.

Publish curated ServiceMap source from af46f684e468dffd3a5190e28d3b572d4c26bfd7
2026-11-20 13:51:46 +01:00

320 lines
12 KiB
Python

"""ServiceMap API authorization.
Modes (``SERVICEMAP_AUTH_MODE``):
* ``disabled`` - no authentication (v1.5 behaviour). Cross-site mutations are
still refused by the Origin check below.
* ``token`` - reads stay anonymous on the LAN (integrations such as ITWorx
Forge and monitors keep working); every mutating request needs
``Authorization: Bearer <admin token>``. The token lives in a 0600 file
next to the database and is generated on first start.
* ``oidc`` - fail-closed bearer JWT validation with viewer/operator/admin
roles mapped from claims or groups.
"""
from __future__ import annotations
import hmac
import logging
import os
import secrets
from dataclasses import dataclass
from functools import lru_cache
from pathlib import Path
from threading import Lock
from urllib.parse import urlparse
import httpx
import jwt
from fastapi import HTTPException, Request, status
class AuthorizationError(RuntimeError):
pass
_ROLE_ORDER = {"viewer": 1, "operator": 2, "admin": 3}
def _csv(name: str) -> set[str]:
return {item.strip().casefold() for item in os.getenv(name, "").split(",") if item.strip()}
@dataclass(frozen=True)
class AuthConfig:
mode: str
issuer: str | None = None
audience: str | None = None
role_claims: tuple[str, ...] = ("groups", "roles")
viewer_groups: frozenset[str] = frozenset()
operator_groups: frozenset[str] = frozenset()
admin_groups: frozenset[str] = frozenset()
@classmethod
def from_environment(cls) -> AuthConfig:
mode = os.getenv("SERVICEMAP_AUTH_MODE", "disabled").strip().casefold() or "disabled"
if mode in {"disabled", "token"}:
return cls(mode=mode)
if mode != "oidc":
raise AuthorizationError("SERVICEMAP_AUTH_MODE must be 'disabled', 'token' or 'oidc'")
issuer = os.getenv("SERVICEMAP_OIDC_ISSUER", "").strip().rstrip("/")
audience = os.getenv("SERVICEMAP_OIDC_AUDIENCE", "").strip()
parsed = urlparse(issuer)
local_http = os.getenv("SERVICEMAP_AUTH_ALLOW_HTTP_FOR_LOCAL", "false").casefold() == "true"
if (
not issuer
or not audience
or not parsed.netloc
or (parsed.scheme != "https" and not local_http)
):
raise AuthorizationError("OIDC mode requires a valid HTTPS issuer and audience")
claims = tuple(
item.strip()
for item in os.getenv("SERVICEMAP_OIDC_ROLE_CLAIMS", "groups,roles").split(",")
if item.strip()
)
return cls(
mode=mode,
issuer=issuer,
audience=audience,
role_claims=claims or ("groups", "roles"),
viewer_groups=frozenset(_csv("SERVICEMAP_OIDC_VIEWER_GROUPS")),
operator_groups=frozenset(_csv("SERVICEMAP_OIDC_OPERATOR_GROUPS")),
admin_groups=frozenset(_csv("SERVICEMAP_OIDC_ADMIN_GROUPS")),
)
@lru_cache(maxsize=8)
def _jwks_client(issuer: str) -> jwt.PyJWKClient:
try:
document = httpx.get(f"{issuer}/.well-known/openid-configuration", timeout=5.0).json()
jwks_uri = str(document.get("jwks_uri", "")) if isinstance(document, dict) else ""
except (httpx.HTTPError, ValueError) as exc:
raise AuthorizationError("OIDC discovery is unavailable") from exc
parsed = urlparse(jwks_uri)
issuer_host = urlparse(issuer).hostname
if not parsed.netloc or parsed.scheme != "https" or parsed.hostname != issuer_host:
raise AuthorizationError("OIDC discovery returned an invalid JWKS URI")
return jwt.PyJWKClient(jwks_uri, cache_keys=True, lifespan=300)
def _claim_values(claims: dict[str, object], names: tuple[str, ...]) -> set[str]:
values: set[str] = set()
for name in names:
raw = claims.get(name)
if isinstance(raw, str):
values.add(raw.casefold())
elif isinstance(raw, list):
values.update(str(item).casefold() for item in raw if isinstance(item, (str, int)))
return values
def _roles_for(claims: dict[str, object], config: AuthConfig) -> set[str]:
values = _claim_values(claims, config.role_claims)
roles: set[str] = set()
# Explicit role claims remain useful with a constrained issuer; group
# mapping gives operators a stable least-privilege model in Authentik.
roles.update(value for value in values if value in _ROLE_ORDER)
if values & config.viewer_groups:
roles.add("viewer")
if values & config.operator_groups:
roles.add("operator")
if values & config.admin_groups:
roles.add("admin")
if "admin" in roles:
roles.update({"operator", "viewer"})
elif "operator" in roles:
roles.add("viewer")
return roles
def verify_bearer(token: str, config: AuthConfig) -> set[str]:
if not config.issuer or not config.audience:
raise AuthorizationError("OIDC configuration is incomplete")
try:
signing_key = _jwks_client(config.issuer).get_signing_key_from_jwt(token)
claims = jwt.decode(
token,
signing_key.key,
algorithms=[signing_key.algorithm_name],
audience=config.audience,
issuer=config.issuer,
options={"require": ["exp", "sub", "iss", "aud"]},
)
except jwt.PyJWTError as exc:
raise AuthorizationError("Bearer token verification failed") from exc
if not isinstance(claims, dict):
raise AuthorizationError("Bearer token claims are invalid")
return _roles_for(claims, config)
SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
# Reads that expose secrets need write access even where reads are open
# (an ntfy topic is effectively a secret on a public server).
SECRET_READ_PREFIXES = ("/api/v1/config", "/api/v1/settings", "/api/v1/backups")
# A backup contains every record, so listing and downloading need the token too.
TOKEN_READ_PREFIXES = ("/api/v1/settings", "/api/v1/backups")
_MIN_TOKEN_LENGTH = 24
_logger = logging.getLogger("servicemap.auth")
_token_lock = Lock()
_token_cache: dict[str, str] = {}
def admin_token_path() -> Path:
configured = os.getenv("SERVICEMAP_ADMIN_TOKEN_FILE", "").strip()
if configured:
return Path(configured)
database = Path(os.getenv("SERVICEMAP_DB", "data/servicemap.db"))
return database.parent / "admin-token"
def admin_token() -> str:
"""Read the admin token, generating it on first use.
The value is never logged; only its location is. Read it on the host
with e.g. ``docker exec servicemap cat /data/admin-token``.
"""
path = admin_token_path()
key = str(path)
with _token_lock:
cached = _token_cache.get(key)
if cached:
return cached
if not path.exists():
path.parent.mkdir(parents=True, exist_ok=True)
generated = secrets.token_urlsafe(32)
descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
handle.write(generated + "\n")
_logger.warning("Generated a new ServiceMap admin token at %s", path)
token = path.read_text(encoding="utf-8").strip()
if len(token) < _MIN_TOKEN_LENGTH:
raise AuthorizationError(
f"The admin token in {path} must be at least {_MIN_TOKEN_LENGTH} characters"
)
_token_cache[key] = token
return token
def reset_token_cache() -> None:
with _token_lock:
_token_cache.clear()
def required_role(request: Request) -> str:
path = request.url.path
if request.method in SAFE_METHODS:
# A full configuration export contains every endpoint and target;
# settings hold notification targets.
return "admin" if path.startswith(SECRET_READ_PREFIXES) else "viewer"
if path.startswith(
(
"/api/v1/config",
"/api/v1/discovery",
"/api/v1/docker",
"/api/v1/maintenance",
# Demo replaces the whole live topology.
"/api/v1/demo",
"/api/v1/settings",
"/api/v1/backups",
)
):
return "admin"
return "operator"
_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
def _host_name(value: str) -> str:
value = value.strip().casefold()
if value.startswith("["): # IPv6 literal with optional port
return value[1:].split("]", 1)[0]
return value.rsplit(":", 1)[0] if value.count(":") == 1 else value
def check_request_origin(request: Request) -> None:
"""Refuse DNS-rebinding hosts and cross-site mutations.
* ``SERVICEMAP_ALLOWED_HOSTS`` (comma separated, optional): when set,
requests for any other Host are refused. Loopback is always allowed
for the container healthcheck.
* A mutating request whose ``Origin`` is not this server, or that a
browser marks ``Sec-Fetch-Site: cross-site``, is refused. Requests
without these headers (curl, integrations) are unaffected.
"""
host_header = request.headers.get("host", "")
# Behind a reverse proxy the public name arrives as X-Forwarded-Host.
forwarded = request.headers.get("x-forwarded-host", "").split(",")[0].strip()
public_host = _host_name(forwarded or host_header)
allowed = _csv("SERVICEMAP_ALLOWED_HOSTS")
if allowed and public_host not in allowed | _LOOPBACK_HOSTS and _host_name(host_header) not in _LOOPBACK_HOSTS:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Deze host is niet toegestaan")
if request.method in SAFE_METHODS:
return
if request.headers.get("sec-fetch-site", "").casefold() == "cross-site":
raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Verzoek van een andere site geweigerd")
origin = request.headers.get("origin")
if origin is not None:
parsed = urlparse(origin)
# Hostnames are compared without ports: proxies (nginx ``$host``,
# NPM) commonly drop the port from Host while Origin keeps it.
if origin == "null" or not parsed.hostname or parsed.hostname.casefold() != public_host:
raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Verzoek van een andere origin geweigerd")
def authorize_request(request: Request) -> None:
"""Authorize API requests; health and static content remain reachable.
Disabled mode preserves v1.5 behavior intentionally. Enabling OIDC with
incomplete configuration fails closed on the API while `/health` remains
available for recovery and deployment diagnostics.
"""
check_request_origin(request)
if request.url.path in {"/health", "/ready"} or not request.url.path.startswith("/api/"):
return
try:
config = AuthConfig.from_environment()
except AuthorizationError as exc:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc)
) from exc
if config.mode == "disabled":
return
header = request.headers.get("Authorization", "")
if config.mode == "token":
if request.method in SAFE_METHODS and not request.url.path.startswith(TOKEN_READ_PREFIXES):
return
try:
expected = admin_token()
except (AuthorizationError, OSError) as exc:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="Het beheerderstoken is niet beschikbaar"
) from exc
supplied = header.removeprefix("Bearer ").strip() if header.startswith("Bearer ") else ""
if not supplied or not hmac.compare_digest(supplied.encode(), expected.encode()):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Bewerken vraagt het ServiceMap-beheerderstoken",
headers={"WWW-Authenticate": "Bearer"},
)
return
if not header.startswith("Bearer "):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED, detail="Bearer-authenticatie is vereist"
)
try:
roles = verify_bearer(header.removeprefix("Bearer ").strip(), config)
except AuthorizationError as exc:
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=str(exc)) from exc
if (
_ROLE_ORDER.get(max(roles, key=lambda item: _ROLE_ORDER[item]) if roles else "", 0)
< _ROLE_ORDER[required_role(request)]
):
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN, detail="Onvoldoende ServiceMap-rol"
)