From 64eb4e846530af497edaf34e2f412acbda5eb9f2 Mon Sep 17 00:00:00 2001 From: faligam Date: Sun, 6 Sep 2026 16:59:34 +0200 Subject: [PATCH] Update reset handoff for API authentication work --- HANDOFF.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 71 insertions(+), 4 deletions(-) diff --git a/HANDOFF.md b/HANDOFF.md index 75b9fc2..6f77363 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -1,6 +1,73 @@ # NSCT – Handoff für neue Threads -> Diese Datei wird **nicht** in Git gepushed. Sie dient nur als Brücke zwischen Threads. +> Diese Datei ist der aktuelle, committebare Übergabestand für einen Reset oder +> einen neuen Thread. Zugangsdaten gehören weder hier noch in Git-Remotes hinein. + +--- + +## Aktueller Stand — 2026-09-06 + +### Laufende Deployments + +- **Backend-Repository:** `/home/faligam/apps/NSCT---Neutral-Search-Crawler-Tool` + - Stack läuft mit `nsct-api`, `nsct-postgres` und `nsct-searxng`. + - Liveness: `curl http://localhost:8080/health` → HTTP 200. + - Research-API: `/v1/research/*`. +- **Frontend-Repository:** `/home/faligam/apps/NSCT-FrontEnd` + - Stack läuft mit `nsct-web` und `nsct-caddy`. + - Frontend: `http://localhost`; direkter Webserver: `http://localhost:3000`. + - Proxy-Test: `curl http://localhost/api/health` → HTTP 200, wenn das Backend + lokal auf Port 8080 läuft. + +### Getrennte Rechner: verbindliche Architektur + +Frontend und Backend sollen auf unterschiedlichen Rechnern betrieben werden. +Sie verwenden **kein gemeinsames Docker-Netzwerk**: + +```text +Browser → Frontend-Caddy (/api/*) → Backend-Host:8080 → nsct-api +``` + +- Das Frontend setzt `NSCT_API_UPSTREAM=backend.example.com:8080` in seiner + `.env` (Host:Port, ohne Schema und ohne Pfad). +- Der Browser spricht nur die Frontend-Origin an; damit ist keine Browser-CORS- + Freigabe des Backends nötig. +- Am Backend Port 8080 ausschließlich für den Frontend-Rechner bzw. dessen Netz + freigeben. Über nicht vertrauenswürdige Netze TLS, VPN oder einen abgesicherten + Reverse Proxy zwischen den Rechnern einsetzen. + +Relevante gepushte Commits: + +- Frontend `37636e1` — reproduzierbarer Docker-Build und Caddy-Serving. +- Frontend `fac3d1c` — externer Backend-Upstream via Caddy. +- Frontend `c6f1889` — Dokumentation für getrennte Deployments. +- Backend `9830acf` — Dokumentation für Frontend-Integration auf separatem Host. + +### Nächste Aufgabe: echte API-Key-Authentifizierung + +Die Authentifizierung ist aktuell **nicht implementiert**. Das Frontend speichert +einen eingegebenen Key im `localStorage` und sendet `X-API-Key`, aber das Backend +prüft diesen Header nicht. Die in `.env` gesetzten `NSCT_LLM_API_KEY`, +`NSCT_VISION_API_KEY` und `NSCT_AUDIO_API_KEY` sind ausschließlich Credentials +für externe Modellanbieter — niemals als Benutzer- oder Frontend-Keys verwenden. + +Empfohlene Umsetzung in diesem Repository: + +1. Ein Auth-Modul als FastAPI-Dependency ergänzen, das `X-API-Key` prüft. +2. Eine persistente User-/API-Key-Tabelle per Migration/Schema anlegen; nur einen + starken, langsamen Hash speichern, niemals den Klartext-Key. +3. Einen administrativen CLI-Workflow für Erstellen, Auflisten, Ablauf und + Widerruf implementieren. Kein Key-Management-Endpunkt ohne separate Admin- + Authentifizierung. +4. `/health`, `/ready` und ggf. `/docs` bewusst als öffentlich oder geschützt + festlegen; alle Research-Endpunkte konsistent schützen. +5. Tests für gültige, fehlende, ungültige, abgelaufene und widerrufene Keys + ergänzen. Erst danach im Frontend Login/API-Fehlerbild verifizieren. + +Vor der Implementierung zuerst die vorhandenen SQL-Beispiele in +`ADMIN-Backend.md`, die tatsächlichen SQLAlchemy-Modelle und die FastAPI-Router +abgleichen: Die Dokumentation beschreibt derzeit nur eine vorbereitete Struktur, +keine aktive Authentifizierung. --- @@ -10,7 +77,7 @@ Webquellen recherchieren, Inhalte extrahieren, Quellen/Claims vergleichen, neutralen Bericht erzeugen. **Repository:** `https://git.frerkc.de/opencode/NSCT---Neutral-Search-Crawler-Tool.git` -**Branch:** `main` — alle Commits sind bereits gepusht. +**Branch:** `main` — aktuellen Status vor Beginn mit `git status` und `git log -1` prüfen. --- @@ -152,7 +219,7 @@ Wenn ein neuer Thread weiterarbeiten soll, einfach **Stage X** nennen und mit de ## GIT-Information -- **Remote:** `https://df918b...f9da@git.frerkc.de/opencode/NSCT---Neutral-Search-Crawler-Tool.git` +- **Remote:** `https://git.frerkc.de/opencode/NSCT---Neutral-Search-Crawler-Tool.git` - **Branch:** `main` - **Credentials:** `user.email="nsct@frerkc.de"`, `user.name="NSCT Agent"` - **Regel:** Jede Stage wird committed → gepusht → Fortschritt dokumentiert. @@ -171,4 +238,4 @@ Wenn ein neuer Thread weiterarbeiten soll, einfach **Stage X** nennen und mit de ## Start-Command für neuen Thread -Wenn ein neuer Thread weiterarbeiten soll, einfach **Stage X** nennen und mit der Arbeit beginnen. Der neue Thread liest prompt.md (liegt im Repo als `/home/faligam/nsct/prompt.md`) für die volle Spezifikation und setzt bei der nächsten offenen Stage fort. \ No newline at end of file +Wenn ein neuer Thread weiterarbeiten soll, einfach **Stage X** nennen und mit der Arbeit beginnen. Der neue Thread liest prompt.md (liegt im Repo als `/home/faligam/nsct/prompt.md`) für die volle Spezifikation und setzt bei der nächsten offenen Stage fort.