89 lines
9.5 KiB
Markdown
89 lines
9.5 KiB
Markdown
# 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 |
|