Files
tsumugu/docs/review/05_REFERENZARCHITEKTUR_BLUEPRINTS.md
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

9.5 KiB
Raw Permalink Blame History

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