Files
tsumugu/docs/review/05_REFERENZARCHITEKTUR_BLUEPRINTS.md
T
LarsandCursor d6b70d8f92
Deploy Development / deploy (push) Successful in 28s
Test Suite / pytest-backend (push) Failing after 2m18s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 10s
Schließe die Connector-Kapselung ab, damit Paperless, IMAP und weitere Quellen über dieselbe Anbindung laufen.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-19 15:00:50 +02:00

89 lines
9.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 05 – Abgleich mit Referenzarchitektur und Blueprints
Die Referenzdokumente trennen **verbindliche Verträge** von **anpassbaren technischen Defaults** (A0). Eine Abweichung von einem Default ist zulässig, wenn sie im Produktauftrag begründet ist. Eine Abweichung von einem Vertrag ist ein Befund. In der Spalte „Art“ steht V für Vertrag und D für Default.
## 1. Referenzarchitektur A/B/C v0.3
| Abschnitt | Vorgabe | Art | Status | Bemerkung |
|---|---|---|---|---|
| A1 | Python 3.12, FastAPI, Pydantic 2, PostgreSQL 16, Psycopg 3 + Pool | D | ✅ | `python:3.12-slim`, `postgres:16-alpine` |
| A1 | Frontend React 19.3 / Vite 8.3 / Router 8.4 Data Mode | D | 🟡 | React 18.3, Router 6.28, Vite 5.4. Die technische Spezifikation 3.1 verlangt die A1-Linien, weil keine SPA migriert wird. Vite 5 wird laut A1 nicht mehr unterstützt (R-26) |
| A1 | Hash-gebundene Python-Locks, npm-Lockfile | D | 🟡 | `package-lock.json` vorhanden; Python nur `==`-Pins ohne Hashes; `pdfjs-dist` und `sharp` mit `^` (R-26) |
| A2 | Router → Service → Repository, Composition Root | D | 🟡 | Router → `ops.py` (Use-Cases) → SQL direkt in `ops`/`policy`/`present`. Kein Repository-Schnitt, kein Composition Root. Für die Größe vertretbar, aber `ops.py` (1 536 Zeilen) und `routes.py` (1 846 Zeilen) wachsen zu Monolithen |
| A3 | Ein Transaktionskontext je Anwendungsfall, Commit vor Antwort, Repositories committen nicht | V | 🟡 | Eine Verbindung je Request über die Dependency `get_conn`. Der Commit vor der Antwort hängt an der FastAPI-Version (R-23). Externe HTTP-/IMAP-Aufrufe laufen in der offenen Transaktion (R-22) |
| A3 | Keine DB-Arbeit beim Import | V | ✅ | Pool erst im Lifespan; Test `test_import_does_not_open_the_database_by_itself` |
| A4 | `/api/v1`, Problem Details, 401/403/404/409/422/503, `X-Request-ID` | V/D | 🟡 | Request-ID fehlt, `type` immer `about:blank` (R-24) |
| A4 | Listen mit `limit` ≤ 200, Cursor, stabile Sortierung | D | 🟡 | feste interne Limits vor der Rechteprüfung, Cursor nur in der Chronologie (R-11) |
| A5 | Migrationen: Dateimuster, Ledger mit Prüfsumme, Advisory-Lock, fehlende angewandte Dateien als Fehler, getrennte Migrationsrolle | V | 🟡 | Ledger mit SHA-256 ✅; Lock, Fehlend-Prüfung, `build_revision` und getrennte Rolle fehlen (R-09) |
| A5 | Runtime ohne DDL, nicht Owner, nicht `BYPASSRLS` | V | 🟡 | Runtime-Rolle ohne DDL ✅, aber Owner-Zugangsdaten im selben Container (R-09) |
| A6 | `APP_ENV` Pflicht, unbekannt = Startfehler | V | ✅ | `tsumugu_env: Literal["development","production"]`; `test` fehlt (D) |
| A6 | Secrets nur in Betriebsbereitstellung, Logs ohne Secrets | V | 🟡 | Host-`.env` ✅. Connector-Secrets im Klartext in der Fach-DB (R-05) |
| A7 | Data Router, Modulregistry, Transportclient mit Timeout und Abort, Session-/Scope-Store mit `epoch` | D | 🟡 | `epoch` verwirft veraltete Antworten ✅; kein Data Router, keine Registry, kein Timeout und kein Abbruch laufender Requests (R-25) |
| A7 | Persönliche API-Antworten `no-store`, PWA cached keine API | V | 🟡 | Service Worker schließt `/api/` aus ✅; Binärantworten `private, no-store` ✅; JSON-Antworten ohne `Cache-Control` |
| A8 | Ports `PrincipalResolver`, `ScopeResolver`, `AccessPolicy` fail-closed | V | ✅ | inhaltlich in `deps.get_principal` und `policy._require`; kein Allow-Schalter |
| A8 | RLS-Prüfung bei vertraulichen Mehrraumdaten (ADR-06) | V | ❌ | nicht geprüft (R-21) |
| A9 / ADR-11 | Release-Gate vor Produktion, Artefaktzuordnung, menschliche Freigabe | V | ❌ | Prod baut auf dem Host neu, ohne Gate (R-21) |
| B4 | Isolierte kurzlebige Test-DB je Lauf, Wächter vor Schemaänderung | V | 🟡 | Wächter auf `*_test` ✅; feste gemeinsame `tsumugu_test` auf der Dev-Postgres, parallele Läufe möglich (R-27) |
| C O1–O3 | Datenraum/RLS, Gitea-Sperren, Recoveryprofil festlegen | – | ❌ | nicht festgelegt (R-21) |
## 2. Auth, Session & Scope Blueprint
| Abschnitt | Vorgabe | Art | Status | Bemerkung |
|---|---|---|---|---|
| 1.1/5.1 | Opake Session, Token gehasht in der DB | V | ✅ | `secrets.token_urlsafe(32)`, SHA-256 |
| 1.1/7.1 | 30 min Leerlauf, 12 h absolut, Rotation nach 15 min | D | ❌ | 336 h absolut, kein Leerlauf, keine Rotation, keine dokumentierte Begründung (R-08) |
| 6.1 | `__Host-jinkendo-session`, HttpOnly, Secure, SameSite=Lax, kein Domain | V | 🟡 | Produktion ✅; Development über HTTP mit `jinkendo-session` ohne Secure, begründet in `MVP_ANNAHMEN.md` |
| 6.2 | Originprüfung bei unsicheren Methoden | V | ✅ | Middleware `origin_guard` |
| 6.2 | Synchronizer-CSRF je Credential | V | 🟡 | CSRF-Token je Session ✅; Vergleich nicht konstantzeitlich; keine Erneuerung |
| 6.2 | Header `X-Jinkendo-Client`, `Sec-Fetch-Site`, nur `application/json` | V | ❌ | nicht umgesetzt; Origin + CSRF decken den Kern ab |
| 6.2 | `Cache-Control: no-store` auf Auth- und persönlichen Antworten | V | 🟡 | nur Binärantworten |
| 7.2 | bcrypt mit Dummy-Vergleich für unbekannte Konten | V | ❌ | kein Dummy-Vergleich, Zeitunterschied verrät Kontoexistenz (R-08) |
| 7.2 | Passwort ≥ 15 Zeichen, ≤ 72 UTF-8-Bytes geprüft | D | 🟡 | ≥ 10 Zeichen; die 72-Byte-Grenze wird nicht vor bcrypt geprüft. Je nach bcrypt-Version wird ein längeres Passwort still gekürzt oder abgelehnt |
| 5.3/7.2 | Persistente, workerübergreifende Login-Begrenzung | V | ❌ | Dictionary im Prozessspeicher, wächst unbegrenzt (R-08) |
| 7.4 | Logout, Logout-all, Passwortwechsel mit Widerruf | V | 🟡 | Logout ✅; Logout-all und Passwortwechsel fehlen (R-08) |
| 9.1 | Headerpaar `X-Scope-Kind`/`X-Scope-Id` Pflicht, Auswahl ist keine Autorität | V | ✅ | `get_principal`; Mitgliedschaft wird je Request neu geprüft |
| 10 | Session speichert keinen autoritativen aktiven Datenraum | V | ❌ | `auth_sessions.scope_id` muss mit dem Header übereinstimmen. Mehrere Tabs mit verschiedenen Räumen lösen 403 aus |
| 11 | Betreiberaktionen nur mit MFA; Ersteinrichtung per lokaler CLI | V | ❌ | Web-Bootstrap, keine MFA (R-04) |
| 13.2 | Pflichtaudit für Session erstellt/widerrufen, Scopewahl, privilegierte Änderungen | V | ❌ | Login, Logout, Scopewechsel, Kontoanlage nicht auditiert (R-18) |
| 13.3 | Keine Client-Identitätsheader, keine Erstprofil-Fallbacks | V | ✅ | – |
## 3. Medien, Dateien & sicheres Rendering Blueprint
| Abschnitt | Vorgabe | Art | Status | Bemerkung |
|---|---|---|---|---|
| 1.1/9.1 | Lesen nur bei Parent- und Assetrecht | V | ✅ | `download_file` prüft `element_rights` im Kontext |
| 1.1 | Keine Session in Medien-URLs, kein öffentlicher `/media`-Mount | V | ✅ | Fetch + Blob-URL |
| 1.1/6 | Ungeprüfte Uploads niemals ausliefern; Typprüfung über Profil, nicht nur Magic Bytes | V | 🟡 | nur Magic Bytes, kein Dekodieren (R-31) |
| 6.1/6.3 | Rasterbilder neu kodieren, EXIF/GPS entfernen | D | ❌ | Originalbytes gespeichert und ausgeliefert (R-31) |
| 6.1 | PDF-Profil erst mit qualifiziertem Validator | D | 🟡 | PDF erlaubt (technische Spezifikation 7.1 sieht PDF als Anhang vor); Download als `attachment` ✅; Anzeige über pdf.js im Browser |
| 7 | Storage hinter Port, zufällige Keys, kein Clientpfad | V | ✅ | `asset_path` mit UUID, Pfadprüfung |
| 7.2 | U0–U3 ohne behauptete Atomarität, Reconciliation | V | 🟡 | Datei vor DB-Commit geschrieben, bei Fehler gelöscht; kein dauerhafter Intent, kein Reconciler |
| 9.3 | `no-store`, `nosniff`, Dokumente als `attachment`, restriktive CSP für Dokumentantworten | V | 🟡 | eigene Dateien ✅. Paperless `inline` inklusive `image/svg+xml`, Mail-Anlagen `inline` mit Absender-MIME, keine Sandbox-CSP (R-03) |
| 10 | Begrenzter Renderbaum, kein freies HTML | V | ✅ | Notizen als Markdown-Block, eigener Renderer ohne `dangerouslySetInnerHTML`, nur `http(s)`-Links |
| 12 | Purge mit Intent und Bestätigung | V | 🟡 | Datei wird nach Commit gelöscht; Status springt im selben Schritt auf `purged` |
| 14 | Upload-Limits, Zeitbudgets, Parallelität | D | 🟡 | 20 MiB, Nginx 21 MiB ✅; keine Parallelitätsgrenze |
## 4. Release, Betrieb & Recovery Blueprint
| Abschnitt | Vorgabe | Art | Status | Bemerkung |
|---|---|---|---|---|
| 1 | `develop → Dev → Tests → Freigabe → main → Prüfung des Kandidaten → Prod` | V | ❌ | Tests laufen nach dem Dev-Deploy; Prod ohne Gate |
| 4 | Produktprofil mit RPO/RTO | V | ❌ | nicht festgelegt |
| 7.1 | Isolierter Teststack je Lauf | V | 🟡 | feste `tsumugu_test` auf der Dev-Postgres, Tests im laufenden Dev-Image mit `pip install` (R-27) |
| 7.2 | Gates G01–G08, `required-tests.json`, kein Skip als Erfolg | V | ❌ | – |
| 10 | Konsistentes, verschlüsseltes Backup von DB und Medien, unabhängige Kopie | V | ❌ | nicht vorhanden (R-21) |
| 11–12 | Restore in neue Generation, Sessions und Konten nach Restore gesperrt | V | ❌ | nicht vorhanden |
| 13 | Recoveryübung vor externem Datenbetrieb | V | ❌ | – |
## 5. KI-Gateway, Prompt/Workflow, Entitlements
Laut technischer Spezifikation gelten diese Blueprints nur als Grenze. Geprüft wurde, dass nichts davon unkontrolliert im Code steckt.
| Grenze | Status | Bemerkung |
|---|---|---|
| Kein Modellaufruf, kein Provider-Secret, kein Egress persönlicher Daten an KI | ✅ | keine KI-Bibliothek, keine Provider-URL im Code |
| Keine Workflow-Engine, keine Prompt-Registry | ✅ | – |
| Keine kommerziellen Kontingente; technische Grenzen bleiben | ✅ | Upload-Grenze, Exportgrenze 80 MiB, Kapiteltiefe 32 |
| Naht für spätere KI: stabile IDs, Versionen, Audit | 🟡 | IDs und Versionen ✅; Audit mit Lücken (R-18) |
| Kairo-Anbindung nur über HTTP, keine gemeinsame DB | ✅ | keine Kopplung |