ADR-0014: Hosting, Deployment & Auth

Kontext

mvest braucht eine öffentlich erreichbare Web-UI für die Konsumation der Agent-Outputs. Die Domain mvest.malte.io steht zur Verfügung (DNS zeigt bereits auf den Server 148.251.126.27). Der Server hostet bereits andere nginx-basierte Anwendungen. Da Trades nicht ausgeführt werden, ist die Angriffsfläche begrenzt, aber Portfolio-Hypothesen, Watchlists und Empfehlungs-Historie sind nicht öffentlich gedacht.

Entscheidungstreiber

• Single-Developer-Setup: minimaler Operations-Overhead, schneller Dev-Loop.
• Sicherheit: öffentlich erreichbare Endpunkte erfordern Authentifizierung und TLS.
• Reversibilität: Setup soll lokal nachvollziehbar bleiben und nicht in proprietäre Infrastruktur sperren.
• Bestehende Infrastruktur: nginx und certbot sind auf dem Host installiert und in Betrieb.
• Erweiterbarkeit Multi-User: v1 nur ein User, aber Schema soll Multi-User-fähig sein.

Hosting-Entscheidung

Domain & TLS

• Domain: mvest.malte.io (A-Record auf 148.251.126.27).
• TLS: Let's Encrypt via certbot --nginx. Zertifikat eingerichtet (gültig bis 2026-08-13). Auto-Renewal über certbot.timer.
• HTTP → HTTPS Redirect erzwungen (durch certbot eingerichtet).

Reverse-Proxy

nginx als Reverse-Proxy. Pfad-Aufteilung:

• /adr/ → statisches Verzeichnis (/home/malte/mvest/adr/), public lesbar ohne Auth. ADRs sind dokumentarisch, nicht sensibel.
• / → 302-Redirect auf /adr/ (vorläufig). Später: Proxy auf die FastAPI-App.
• Künftige App-Pfade (z. B. /app/ oder /) → Proxy auf 127.0.0.1:8000 (uvicorn), Auth durch die App selbst.

Code-Location & Service-User

• Code-Verzeichnis: /home/malte/mvest. Pragmatisch für Single-Dev-Setup; Dev-Loop simpel. Migration nach /opt/mvest bei Bedarf möglich.
• Service-User: malte. Kein dedizierter mvest-User in v1 (würde Permissions-Management für SQLite-Datei und Logs verkomplizieren). Bei Bedarf später nachzuholen.

Prozess-Management

• systemd-Unit mvest.service startet uvicorn auf 127.0.0.1:8000, restart on failure, läuft als malte.
• Logs via journald (journalctl -u mvest).
• Auto-Start beim Boot aktiviert.

Deployment

• v1 Workflow: git pull && uv sync && systemctl restart mvest. Kein CI/CD nötig solange Single-Dev.
• Static-Assets (ADRs, CSS): direkt aus dem Repo serviert; git pull macht sie sofort live.

Auth-Entscheidung

Auth erfolgt in der Webapp selbst — kein nginx-Auth-Layer, keine externen IdPs in v1.

Auth-Bausteine

• Passwörter: Klartext in data/users.yaml. Vergleich über secrets.compare_digest() (constant-time, gegen Timing-Attacken). Begründung: private Hobby-Anwendung, minimale Angriffsfläche, File-Permission 0600 als zentrale Schutzwand. Migration zu argon2id ist trivial nachzuziehen, wenn Multi-User oder Public-Use kommt.
• User-Storage: YAML-Datei data/users.yaml (gitignored, chmod 600 beim Schreiben). Lade beim Start in den Speicher, schreibe bei jeder Änderung. Atomic write via os.replace. Kein SQLite für User in v1.
• Session-Modell: In-Memory Dict session_id → SessionData. Session-ID ist 32 Byte URL-safe random, im HttpOnly + Secure + SameSite=Lax-Cookie. Bei Server-Restart sind alle ausgeloggt (akzeptiert für v1).
• Session-Lifetime: 30 Tage Sliding-Window (jeder authentifizierte Request verlängert expires_at). Periodic-Cleanup expired Sessions im Hintergrund.
• CSRF: Token in allen POST-Forms (signed via itsdangerous), wird vom Server gegen Session validiert.
• Login-Rate-Limit: max. 5 Fehlversuche / 15 min / IP, danach 15 min Sperre.
• Logout: Server entfernt Session aus dem Dict, Cookie wird invalidiert.

Storage-Format

data/users.yaml (gitignored, chmod 600)

users:
  - username: malte
    password: "klartext-passwort"
    is_active: true
    created_at: 2026-05-15T10:30:00Z
    last_login_at: null

Sessions — kein Schema, In-Memory

SessionData(BaseModel):
    session_id: str            # 32 bytes urlsafe random
    username: str
    created_at: datetime
    expires_at: datetime
    last_used_at: datetime

# Storage: dict[session_id, SessionData], in-memory only

Warum YAML statt SQLite für Users? Für v1 ist die User-Anzahl winzig (1), Änderungen sind selten. Eine Textdatei ist trivial zu inspizieren, manuell zu editieren und zu sichern. Sessions hingegen sind kurzlebig und volatil — in-memory ist hier angemessen. Migration zu SQLite ist möglich, wenn Multi-User in v2 kommt.

Initial-User-Setup

Beim ersten Boot prüft die App, ob die users-Tabelle leer ist. Wenn ja: liest sie die Env-Vars MVEST_INITIAL_USER und MVEST_INITIAL_PASSWORD, legt den User an und logged in. Anschließend werden die Env-Vars bei jedem weiteren Boot ignoriert (Bedingung: users ist nicht leer).

Sicherheit: Initial-Passwort steht im Klartext in .env. Nach erstem erfolgreichem Login sollte das Passwort über die Settings-Seite in der Web-UI geändert und anschließend die beiden Env-Vars aus .env entfernt werden.

Multi-User-Vorbereitung

• Schema unterstützt mehrere Users (UNIQUE username, kein Singleton-Constraint).
• v1: nur ein User. User-Self-Service direkt in der Web-UI (Settings-Seite): Passwort ändern, Account-Daten aktualisieren. Keine separate CLI.
• v2: User-Verwaltungs-UI für Multi-User (Admins legen neue Accounts an), ggf. Roles (admin/viewer).
• Recovery: Falls der einzige Account gesperrt ist, manuelle SQLite-Korrektur (z. B. neuen Hash setzen oder Tabelle users leeren — danach greift wieder der ENV-Bootstrap).

Implementierungsstatus (Stand 2026-05-15)

Konsequenzen

Positiv

• Minimaler Infrastruktur-Footprint.
• Volle Kontrolle über Auth-Flow.
• Standardbausteine (argon2id, Server-Sessions, CSRF) — kein Reinvention von Krypto.
• Skalierbar zu Multi-User ohne Schema-Migration.

Negativ

• Eigener Auth-Code muss korrekt geschrieben sein. Mitigation: kleine Code-Surface, Reviews, Tests gegen klassische Fehler (Timing-Attacken bei Login, Session-Fixation).
• Single-Server-Setup ohne Hochverfügbarkeit. Akzeptiert für v1.
• Logs nur lokal in journald. Externe Aggregation (z. B. Loki) wäre v2-Thema.