From d6b70d8f92e135bf5ea31103a375ec54e8291084 Mon Sep 17 00:00:00 2001 From: Lars Date: Mon, 19 Oct 2026 15:00:50 +0200 Subject: [PATCH 01/29] =?UTF-8?q?Schlie=C3=9Fe=20die=20Connector-Kapselung?= =?UTF-8?q?=20ab,=20damit=20Paperless,=20IMAP=20und=20weitere=20Quellen=20?= =?UTF-8?q?=C3=BCber=20dieselbe=20Anbindung=20laufen.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Cursor --- README.md | 17 +- backend/app/api/routes.py | 20 +- backend/app/api/schemas.py | 15 +- backend/app/api/sources.py | 247 +++++- backend/app/core/errors.py | 4 + backend/app/correspondence.py | 89 +- backend/app/db/migrate.py | 13 + backend/app/exporting.py | 16 +- backend/app/media/port.py | 247 ++++++ backend/app/ops.py | 49 +- backend/app/present.py | 42 +- backend/app/retrieval.py | 144 +--- backend/app/sourcebind.py | 211 +++++ backend/app/sourceport.py | 98 +++ backend/app/sourceregistry.py | 53 ++ backend/app/sources.py | 331 ++++++-- .../20261019T120000Z_source_storage.sql | 66 ++ .../20261019T150000Z_source_registry.sql | 5 + backend/tests/sample_source.py | 182 +++++ backend/tests/test_connector_basis.py | 333 ++++++++ backend/tests/test_correspondence.py | 2 +- backend/tests/test_export.py | 14 +- backend/tests/test_sample_source.py | 225 +++++ docs/DEPLOYMENT.md | 16 + docs/ENTWICKLUNG_UND_TESTS.md | 97 +++ docs/README.md | 93 +++ docs/architecture/API_REFERENZ.md | 22 +- docs/architecture/DATENMODELL_IST.md | 11 +- docs/architecture/RECHTEMODELL_IST.md | 100 +++ ...NNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md | 133 +++ ...RAGE_SCHLUESSEL_PRUEFAUFTRAG_2026-10-19.md | 23 + docs/architecture/TSUMUGU_TECHNICAL_SPEC.md | 2 + ...sumugu_Connector_Suite_Architektur_v0.2.md | 306 +++++++ ...CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md | 48 ++ ...GU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md | 46 ++ ...UGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md | 62 ++ ...MUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md | 64 ++ docs/product/TSUMUGU_PRODUCT_SPEC.md | 2 + ...MUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md | 2 + ...o_AI_Gateway_Provider_Privacy_Blueprint.md | 602 ++++++++++++++ .../Jinkendo_Auth_Session_Scope_Blueprint.md | 773 ++++++++++++++++++ ...ndo_Entitlements_Usage_Quotas_Blueprint.md | 584 +++++++++++++ ...do_Media_Files_Safe_Rendering_Blueprint.md | 601 ++++++++++++++ ...o_Prompt_Placeholder_Workflow_Blueprint.md | 591 +++++++++++++ ...endo_Release_Betrieb_Recovery_Blueprint.md | 612 ++++++++++++++ ...nkendo_Technical_Reference_Architecture.md | 193 +++++ ...tation_Blueprint_Application_Foundation.md | 262 ++++++ .../C_Technical_Decisions_Open_Issues.md | 80 ++ ...endo_Technical_Reference_Architecture.diff | 120 +++ ...tion_Blueprint_Application_Foundation.diff | 161 ++++ .../C_Technical_Decisions_Open_Issues.diff | 73 ++ .../_support/document_check.json | 29 + .../_support/revise_v03.py | 172 ++++ docs/review/01_METHODIK_UND_QUELLEN.md | 65 ++ docs/review/02_ANFORDERUNGEN_PRODUKT.md | 75 ++ .../03_ANFORDERUNGEN_UX_UND_AUFTRAEGE.md | 88 ++ docs/review/04_TECHNISCHE_SPEZIFIKATION.md | 101 +++ .../05_REFERENZARCHITEKTUR_BLUEPRINTS.md | 88 ++ docs/review/06_BEFUNDE.md | 294 +++++++ docs/review/07_TESTS_UND_CI.md | 78 ++ docs/review/08_DOKUMENTATION.md | 61 ++ docs/review/09_MASSNAHMENPLAN.md | 80 ++ docs/review/README.md | 70 ++ frontend/src/api.js | 8 +- frontend/src/pages/Cases.jsx | 26 +- frontend/src/pages/ExportPackage.jsx | 2 +- frontend/src/pages/Matters.jsx | 15 +- frontend/src/pages/ReadingPane.jsx | 68 +- frontend/src/pages/Sources.jsx | 169 ++-- frontend/src/pages/content.jsx | 19 +- frontend/src/pages/correspondence.jsx | 3 +- frontend/src/pages/widgets.jsx | 17 +- frontend/src/sources/registry-core.js | 23 + frontend/src/sources/registry.jsx | 223 +++++ frontend/src/sources/sample-source.js | 15 + 75 files changed, 9477 insertions(+), 414 deletions(-) create mode 100644 backend/app/media/port.py create mode 100644 backend/app/sourcebind.py create mode 100644 backend/app/sourceport.py create mode 100644 backend/app/sourceregistry.py create mode 100644 backend/migrations/20261019T120000Z_source_storage.sql create mode 100644 backend/migrations/20261019T150000Z_source_registry.sql create mode 100644 backend/tests/sample_source.py create mode 100644 backend/tests/test_connector_basis.py create mode 100644 backend/tests/test_sample_source.py create mode 100644 docs/ENTWICKLUNG_UND_TESTS.md create mode 100644 docs/README.md create mode 100644 docs/architecture/RECHTEMODELL_IST.md create mode 100644 docs/architecture/TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md create mode 100644 docs/architecture/TSUMUGU_STORAGE_SCHLUESSEL_PRUEFAUFTRAG_2026-10-19.md create mode 100644 docs/architecture/Tsumugu_Connector_Suite_Architektur_v0.2.md create mode 100644 docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md create mode 100644 docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md create mode 100644 docs/product/TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md create mode 100644 docs/product/TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md create mode 100644 docs/reference/Jinkendo_AI_Gateway_Provider_Privacy_Blueprint.md create mode 100644 docs/reference/Jinkendo_Auth_Session_Scope_Blueprint.md create mode 100644 docs/reference/Jinkendo_Entitlements_Usage_Quotas_Blueprint.md create mode 100644 docs/reference/Jinkendo_Media_Files_Safe_Rendering_Blueprint.md create mode 100644 docs/reference/Jinkendo_Prompt_Placeholder_Workflow_Blueprint.md create mode 100644 docs/reference/Jinkendo_Release_Betrieb_Recovery_Blueprint.md create mode 100644 docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md create mode 100644 docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md create mode 100644 docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md create mode 100644 docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/A_Jinkendo_Technical_Reference_Architecture.diff create mode 100644 docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/B_Implementation_Blueprint_Application_Foundation.diff create mode 100644 docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/C_Technical_Decisions_Open_Issues.diff create mode 100644 docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/document_check.json create mode 100644 docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/revise_v03.py create mode 100644 docs/review/01_METHODIK_UND_QUELLEN.md create mode 100644 docs/review/02_ANFORDERUNGEN_PRODUKT.md create mode 100644 docs/review/03_ANFORDERUNGEN_UX_UND_AUFTRAEGE.md create mode 100644 docs/review/04_TECHNISCHE_SPEZIFIKATION.md create mode 100644 docs/review/05_REFERENZARCHITEKTUR_BLUEPRINTS.md create mode 100644 docs/review/06_BEFUNDE.md create mode 100644 docs/review/07_TESTS_UND_CI.md create mode 100644 docs/review/08_DOKUMENTATION.md create mode 100644 docs/review/09_MASSNAHMENPLAN.md create mode 100644 docs/review/README.md create mode 100644 frontend/src/sources/registry-core.js create mode 100644 frontend/src/sources/registry.jsx create mode 100644 frontend/src/sources/sample-source.js diff --git a/README.md b/README.md index c38523e..773f56e 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ Remote: `http://192.168.2.144:3000/Lars/tsumugu.git` ## Stand -Die erste benutzbare Lieferung organisiert und verfolgt: Anmeldung, Datenräume, Akten und Vorgänge, Notizen, Dateien, manuelle Paperless-Referenzen, Chronologie, Aufgaben und unabhängige Fristen. Finanzfunktionen, automatische Paperless-Synchronisation, KI und externer Anwaltszugang folgen später. +Die erste benutzbare Lieferung organisiert und verfolgt: Anmeldung, Datenräume, Akten und Vorgänge, Notizen, Dateien, manuelle Paperless-Referenzen, Chronologie, Aufgaben und unabhängige Fristen. Seitdem hinzugekommen: Paperless- und IMAP-Zugänge mit Auswahl und Vorschau, Antwortbezüge zwischen Unterlagen, Kommunikationsrichtung je Einbindung, Unterkapitel und das Übergabepaket als ZIP. Finanzfunktionen, automatische Paperless-Synchronisation, virtuelle Zusammenstellungen, KI und laufender Anwaltszugang folgen später. -Ein Push auf `develop` baut und startet Development, ein Merge von `develop` nach `main` die Produktion. Der Gitea-Runner auf dem Raspberry Pi (`192.168.2.49`) übernimmt Build und Deploy. Beim Start führt das Backend die Migrationen aus. In Development legt es synthetische Beispieldaten an, in Production nicht. +Ein Push auf `develop` baut und startet Development, ein Merge von `develop` nach `main` die Produktion. Der Gitea-Runner auf dem Raspberry Pi (`192.168.2.49`) übernimmt Build und Deploy. Beim Start führt das Backend die Migrationen aus und entfernt Konten mit Herkunft `fixture`. Synthetische Beispieldaten entstehen in keiner Umgebung automatisch, nur in der Test-Suite auf einer Datenbank `*_test`. | | Development | Production | |---|---|---| @@ -19,11 +19,12 @@ Ein Push auf `develop` baut und startet Development, ein Merge von `develop` nac Details, Ports und der Synology-Reverse-Proxy: `docs/DEPLOYMENT.md`. -Development ist nach dem Deploy unter https://dev.tsumugu.jinkendo.de oder http://192.168.2.49:3094 erreichbar. Die Beispielkonten stehen auf der Anmeldeseite: +Development ist nach dem Deploy unter https://dev.tsumugu.jinkendo.de oder http://192.168.2.49:3094 erreichbar. Auf einer leeren Datenbank bietet die Anmeldeseite einmalig das Anlegen des Betreiberkontos an; der Betreiber legt danach weitere Konten unter „Verwaltung → Nutzer“ an. -| | E-Mail | Passwort | -|---|---|---| -| Ada Beispiel | ada@example.test | Beispiel-Ada-2026 | -| Ben Beispiel | ben@example.test | Beispiel-Ben-2026 | +Die synthetischen Beispielkonten „Ada Beispiel“ (`ada@example.test`) und „Ben Beispiel“ (`ben@example.test`) mit dem Mietstreit Musterstraße legt nur die Test-Suite an (`backend/app/seed.py`). Die Anmeldeseite zeigt sie ausschließlich in Development mit einer Datenbank `*_test` und `SEED_DEMO=true`. Auf `tsumugu_dev` und `tsumugu` gibt es sie nicht; der Start entfernt sie dort. -Ada führt den Mietstreit Musterstraße. Ben darf diesen Kontext bearbeiten und sieht die private Verhandlungsstrategie nicht. Vorläufige Rechte- und Löschannahmen: `docs/MVP_ANNAHMEN.md`. `/api/health` prüft weiterhin nur, ob die Anwendung und die Datenbank antworten. +Vorläufige Rechte- und Löschannahmen: `docs/MVP_ANNAHMEN.md`. `/api/health` prüft weiterhin nur, ob die Anwendung und die Datenbank antworten. + +## Dokumentation + +Übersicht aller Dokumente: [docs/README.md](docs/README.md). Lokaler Start und Tests: [docs/ENTWICKLUNG_UND_TESTS.md](docs/ENTWICKLUNG_UND_TESTS.md). Letztes Code-Review: [docs/review/](docs/review/README.md). diff --git a/backend/app/api/routes.py b/backend/app/api/routes.py index 9c8018d..aacfc4a 100644 --- a/backend/app/api/routes.py +++ b/backend/app/api/routes.py @@ -93,8 +93,8 @@ from app.auth.security import ( ) from app.core.errors import Problem, forbidden, not_found, too_many, unprocessable from app.core.timeutil import dump_date, dump_dt, utcnow -from app.media.storage import content_disposition, read_bytes -from app.media.storage import asset_path +from app.media.port import read_clear_bytes +from app.media.storage import content_disposition from app.ops import ( add_annotation, assign_task, @@ -1119,12 +1119,24 @@ def download_file( if not rights.read: raise not_found() asset = conn.execute( - "SELECT id, original_filename, content_type, status FROM media_assets WHERE element_id = %s", + """ + SELECT id, original_filename, content_type, sha256, status, + storage_instance_id, storage_generation, object_key, protection_profile + FROM media_assets WHERE element_id = %s + """, (element_id,), ).fetchone() if asset is None or asset["status"] != "active": raise not_found() - payload = read_bytes(asset_path(request.app.state.settings.media_root, asset["id"])) + payload = read_clear_bytes( + conn, + instance_id=asset["storage_instance_id"], + generation=asset["storage_generation"], + object_key=asset["object_key"] or str(asset["id"]), + media_root=request.app.state.settings.media_root, + protection_profile=asset["protection_profile"], + expected_sha256=asset["sha256"], + ) return Response( content=payload, media_type=asset["content_type"], diff --git a/backend/app/api/schemas.py b/backend/app/api/schemas.py index f6e6e89..7d407d6 100644 --- a/backend/app/api/schemas.py +++ b/backend/app/api/schemas.py @@ -278,7 +278,7 @@ class ExternalDetail(APIModel): class ExternalIn(APIModel): title: str = Field(min_length=1, max_length=200) - source: Literal["paperless", "url", "imap"] + source: str = Field(min_length=1, max_length=40) external_id: str = Field(min_length=1, max_length=200) context: ContextIn placement: ContextIn | None = None @@ -288,7 +288,13 @@ class ExternalIn(APIModel): class ConnectorIn(APIModel): - kind: Literal["paperless", "imap"] + """Kind is checked against the source registry. Source fields stay optional. + + Paperless and IMAP still send their existing fields. A further module + uses ``config`` and validates that bag itself. + """ + + kind: str = Field(min_length=1, max_length=40) name: str = Field(min_length=1, max_length=120) base_url: str | None = None token: str | None = None @@ -298,6 +304,11 @@ class ConnectorIn(APIModel): password: str | None = None mailbox: str | None = Field(default=None, max_length=200) security: Literal["ssl", "starttls"] | None = None + config: dict[str, str] | None = None + + +class SourceAssignmentIn(APIModel): + connector_id: UUID class DeleteElementIn(APIModel): diff --git a/backend/app/api/sources.py b/backend/app/api/sources.py index 1a40e65..287baf8 100644 --- a/backend/app/api/sources.py +++ b/backend/app/api/sources.py @@ -8,26 +8,25 @@ from fastapi import APIRouter, Depends from fastapi.responses import JSONResponse, Response from psycopg import Connection -from app.access.policy import element_rights, get_element, parse_query_context +from app.access.policy import Ctx, element_rights, get_element, parse_query_context from app.api.deps import Principal, get_conn, get_principal from app.api.routes import _created, _ctx_model -from app.api.schemas import ConnectorIn, ExternalIn -from app.core.errors import not_found, unprocessable +from app.api.schemas import ConnectorIn, ExternalIn, SourceAssignmentIn +from app.core.errors import not_found, unprocessable, unsupported from app.mailpack import parse_mail from app.media.storage import content_disposition from app.ops import create_external +from app.sourcebind import assign_reference +from app.sourceport import capability_payload, with_capabilities +from app.sourceregistry import get_source, require_source from app.sources import ( - clean_base_url, delete_connector, - imap_mailboxes, - imap_messages, imap_preview, list_connectors, - paperless_documents, probe, read_linked_mail, - read_linked_paperless, save_connector, + update_connector, ) _PRIVATE = { @@ -44,6 +43,12 @@ def get_connectors(principal: Principal = Depends(get_principal), conn: Connecti return {"items": list_connectors(conn, principal.account_id)} +@router.get("/api/v1/sources/capabilities") +def source_capabilities(principal: Principal = Depends(get_principal)): + del principal + return capability_payload() + + @router.post("/api/v1/connectors", status_code=201) def post_connector(body: ConnectorIn, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)): name, settings, secret = _connector_parts(body) @@ -51,6 +56,22 @@ def post_connector(body: ConnectorIn, principal: Principal = Depends(get_princip return row +@router.patch("/api/v1/connectors/{connector_id}") +def patch_connector( + connector_id: UUID, + body: ConnectorIn, + principal: Principal = Depends(get_principal), + conn: Connection = Depends(get_conn), +): + name, settings, secret = _connector_parts(body) + current = next((item for item in list_connectors(conn, principal.account_id) if item["id"] == str(connector_id)), None) + if current is None: + raise not_found() + if current["kind"] != body.kind: + raise unprocessable("Der Zugang bleibt bei seiner Quellenart.") + return update_connector(conn, principal.account_id, connector_id, name, settings, secret) + + @router.delete("/api/v1/connectors/{connector_id}", status_code=204) def remove_connector(connector_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)): delete_connector(conn, principal.account_id, connector_id) @@ -62,7 +83,7 @@ def probe_connector(connector_id: UUID, principal: Principal = Depends(get_princ @router.get("/api/v1/external-refs/{element_id}/content") -def view_paperless( +def view_external_content( element_id: UUID, context_kind: str | None = None, context_id: str | None = None, @@ -70,9 +91,10 @@ def view_paperless( conn: Connection = Depends(get_conn), ): element, context, ref = _opened_ref(conn, principal, element_id, context_kind, context_id) - if ref is None or ref["source"] != "paperless": - raise unprocessable("Nur ein Paperless-Dokument lässt sich hier als Datei ansehen.") - data, media_type, filename = read_linked_paperless(conn, principal.account_id, element, context, ref) + module = get_source(ref["source"]) if ref is not None else None + if module is None or module.open_original is None: + raise unprocessable("Für diese Quelle ist kein Dateiabruf vorgesehen.") + data, media_type, filename = module.open_original(conn, principal.account_id, element, context, ref) safe_name = (filename or "dokument.pdf").replace('"', "") return Response( content=data, @@ -126,7 +148,10 @@ def _opened_ref(conn, principal: Principal, element_id: UUID, context_kind: str if not rights.read: raise not_found() ref = conn.execute( - "SELECT source, external_id, detail FROM external_references WHERE element_id = %s", + """ + SELECT source, external_id, detail, connector_id, resolution + FROM external_references WHERE element_id = %s + """, (element_id,), ).fetchone() return element, context, ref @@ -186,8 +211,39 @@ def _mail_bytes(data: bytes, media_type: str, filename: str, inline: bool = Fals @router.get("/api/v1/sources/paperless/documents") -def search_paperless(q: str = "", principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)): - return {"items": paperless_documents(conn, principal.account_id, q.strip())} +def search_paperless( + q: str = "", + connector_id: UUID | None = None, + title: str = "", + correspondent: str = "", + document_type: str = "", + tag: str = "", + document_from: str = "", + document_to: str = "", + sort: str = "", + cursor: str = "", + principal: Principal = Depends(get_principal), + conn: Connection = Depends(get_conn), +): + return _run_search( + "paperless", + conn, + principal.account_id, + q.strip(), + connector_id, + "", + None, + { + "title": title, + "correspondent": correspondent, + "document_type": document_type, + "tag": tag, + "document_from": document_from, + "document_to": document_to, + "sort": sort, + "cursor": cursor, + }, + ) @router.get("/api/v1/sources/imap/mailboxes") @@ -196,7 +252,7 @@ def list_mailboxes( principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn), ): - return {"items": imap_mailboxes(conn, principal.account_id, connector_id)} + return _run_navigate("imap", conn, principal.account_id, connector_id) @router.get("/api/v1/sources/imap/messages") @@ -205,12 +261,38 @@ def search_mail( q: str = "", mailbox: str = "", before: int | None = None, + title: str = "", + correspondent: str = "", + document_type: str = "", + tag: str = "", + document_from: str = "", + document_to: str = "", + sort: str = "", + cursor: str = "", principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn), ): if before is not None and before < 1: raise unprocessable("Die Seitenangabe ist ungültig.") - return imap_messages(conn, principal.account_id, connector_id, q.strip(), mailbox.strip(), before) + return _run_search( + "imap", + conn, + principal.account_id, + q.strip(), + connector_id, + mailbox.strip(), + before, + { + "title": title, + "correspondent": correspondent, + "document_type": document_type, + "tag": tag, + "document_from": document_from, + "document_to": document_to, + "sort": sort, + "cursor": cursor, + }, + ) @router.get("/api/v1/sources/imap/message") @@ -228,8 +310,8 @@ def read_mail( @router.post("/api/v1/sources/link", status_code=201) def link_source(body: ExternalIn, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)): - if body.source not in {"paperless", "imap"}: - raise unprocessable("Verknüpft werden Paperless-Dokumente und E-Mails.") + if get_source(body.source) is None: + raise unprocessable("Verknüpft werden registrierte Quellen.") element = create_external( conn, principal.account_id, @@ -248,20 +330,115 @@ def link_source(body: ExternalIn, principal: Principal = Depends(get_principal), return _created(f"/api/v1/elements/{element['id']}", {"id": str(element["id"]), "title": element["title"]}) +@router.post("/api/v1/external-refs/{element_id}/assignment") +def assign_source( + element_id: UUID, + body: SourceAssignmentIn, + principal: Principal = Depends(get_principal), + conn: Connection = Depends(get_conn), +): + assign_reference(conn, principal.account_id, element_id, body.connector_id) + return {"id": str(element_id), "connector_id": str(body.connector_id), "resolution": "bound"} + + def _connector_parts(body: ConnectorIn) -> tuple[str, dict, str]: - if body.kind == "paperless": - if not body.base_url or not body.token or len(body.token.strip()) < 8: - raise unprocessable("Paperless braucht eine Adresse und einen API-Schlüssel.") - return body.name.strip(), {"base_url": clean_base_url(body.base_url)}, body.token.strip() - if not body.host or not body.username or not body.password: - raise unprocessable("Ein E-Mail-Konto braucht Server, Benutzername und Passwort.") - host = body.host.strip() - if " " in host or len(host) > 200: - raise unprocessable("Der Mailserver ist ungültig.") - return body.name.strip(), { - "host": host, - "port": body.port or 993, - "username": body.username.strip(), - "mailbox": (body.mailbox or "INBOX").strip() or "INBOX", - "security": body.security or "ssl", - }, body.password + return require_source(body.kind).parse_config(body.model_dump()) + + +_SEARCH_FLAGS = { + "title": "title", + "correspondent": "correspondent", + "document_type": "document_type", + "tag": "tags", + "document_from": "document_range", + "document_to": "document_range", + "sort": "sort", + "cursor": "continuation", +} + + +def _run_search(kind: str, conn, owner, query: str, connector_id: UUID | None, mailbox: str, before: int | None, filters: dict) -> dict: + module = require_source(kind) + search = module.capabilities["search"] + refused = [name for name, value in filters.items() if str(value or "").strip() and not search.get(_SEARCH_FLAGS.get(name, name))] + if before is not None and not search.get("continuation"): + refused.append("before") + if refused: + raise unsupported("Diese Suche unterstützt den Filter nicht: " + ", ".join(refused) + ".") + found = module.find(conn, owner, connector_id, query, {"mailbox": mailbox, "before": before}) + bound = str(found.get("connector_id") or connector_id or "") + return with_capabilities(kind, bound, found) + + +def _run_navigate(kind: str, conn, owner, connector_id: UUID) -> dict: + module = require_source(kind) + if not module.capabilities.get("navigate") or module.navigate is None: + raise unsupported("Diese Quelle hat keine Fachnavigation.") + return {"items": module.navigate(conn, owner, connector_id)} + + +@router.get("/api/v1/sources/{kind}/search") +def search_source( + kind: str, + q: str = "", + connector_id: UUID | None = None, + mailbox: str = "", + before: int | None = None, + title: str = "", + correspondent: str = "", + document_type: str = "", + tag: str = "", + document_from: str = "", + document_to: str = "", + sort: str = "", + cursor: str = "", + principal: Principal = Depends(get_principal), + conn: Connection = Depends(get_conn), +): + if before is not None and before < 1: + raise unprocessable("Die Seitenangabe ist ungültig.") + return _run_search( + kind, + conn, + principal.account_id, + q.strip(), + connector_id, + mailbox.strip(), + before, + { + "title": title, + "correspondent": correspondent, + "document_type": document_type, + "tag": tag, + "document_from": document_from, + "document_to": document_to, + "sort": sort, + "cursor": cursor, + }, + ) + + +@router.get("/api/v1/sources/{kind}/navigate") +def navigate_source( + kind: str, + connector_id: UUID, + principal: Principal = Depends(get_principal), + conn: Connection = Depends(get_conn), +): + return _run_navigate(kind, conn, principal.account_id, connector_id) + + +@router.get("/api/v1/sources/{kind}/preview") +def preview_source( + kind: str, + connector_id: UUID, + mailbox: str = "", + uid: int = 0, + item: str = "", + principal: Principal = Depends(get_principal), + conn: Connection = Depends(get_conn), +): + module = require_source(kind) + if not module.capabilities.get("read_preview") or module.preview is None: + raise unsupported("Diese Quelle hat keine Vorschau vor dem Übernehmen.") + return module.preview(conn, principal.account_id, connector_id, {"mailbox": mailbox, "uid": uid, "item": item}) diff --git a/backend/app/core/errors.py b/backend/app/core/errors.py index ce16081..e75273f 100644 --- a/backend/app/core/errors.py +++ b/backend/app/core/errors.py @@ -50,6 +50,10 @@ def unprocessable(detail: str) -> Problem: return Problem(422, "Eingabe ungültig", detail, "unprocessable") +def unsupported(detail: str) -> Problem: + return Problem(422, "Nicht unterstützt", detail, "unsupported") + + def too_many() -> Problem: return Problem(429, "Zu viele Versuche", "Bitte kurz warten und es erneut versuchen.", "too_many_requests") diff --git a/backend/app/correspondence.py b/backend/app/correspondence.py index 13a595b..ae6dfd4 100644 --- a/backend/app/correspondence.py +++ b/backend/app/correspondence.py @@ -26,9 +26,10 @@ from app.access.policy import ( require_case, require_matter, ) -from app.core.errors import conflict, not_found, unprocessable +from app.core.errors import Problem, conflict, not_found, unprocessable from app.core.timeutil import dump_date, dump_dt -from app.media.storage import asset_path, display_filename, read_bytes, sha256, write_bytes +from app.media.port import LEGACY_PROFILE, LocalAdapter, instance_for_write, publish, read_clear_bytes, stored_path +from app.media.storage import display_filename, sha256 from app.retrieval import FilePayload, MailPayload, RetrievalFailure, load_external, load_file CHANNELS = {"email": "per E-Mail", "post": "per Post", "other": "sonstiger Weg"} @@ -415,9 +416,25 @@ def load_snapshot_file(conn, snapshot_id: UUID, media_root: str) -> FilePayload row = conn.execute("SELECT * FROM dispatch_snapshots WHERE id = %s", (snapshot_id,)).fetchone() if row is None: return RetrievalFailure("missing", "Die gesicherte Fassung ist nicht mehr vorhanden.") + profile = row["protection_profile"] or "legacy-plaintext" + if profile != "legacy-plaintext": + return RetrievalFailure( + "unsupported", + "Dieser Inhalt ist geschützt und kann hier nicht im Klartext gelesen werden.", + ) try: - data = read_bytes(_snapshot_path(media_root, row["id"])) - except Exception: + data = read_clear_bytes( + conn, + instance_id=row["storage_instance_id"], + generation=row["storage_generation"], + object_key=row["object_key"] or f"dispatch/{row['id']}", + media_root=media_root, + protection_profile=profile, + expected_sha256=row["sha256"], + ) + except Problem as exc: + if exc.code == "processing": + return RetrievalFailure("missing", "Die gesicherte Fassung lässt sich nicht unverändert lesen.") return RetrievalFailure("missing", "Die gesicherte Fassung ist nicht mehr vorhanden.") if sha256(data) != row["sha256"]: return RetrievalFailure("missing", "Die gesicherte Fassung lässt sich nicht unverändert lesen.") @@ -573,7 +590,7 @@ def purge_element_dispatch_files(conn, element_id: UUID, media_root: str) -> lis (item_id,), ).fetchone() if snap is not None: - paths.append(_snapshot_path(media_root, snap["id"])) + paths.append(_snapshot_disk(conn, snap["id"], media_root)) conn.execute("DELETE FROM dispatch_snapshots WHERE id = %s", (snap["id"],)) conn.execute( """ @@ -596,7 +613,7 @@ def purge_element_dispatch_files(conn, element_id: UUID, media_root: str) -> lis (evidence_id,), ).fetchone() if snap is not None: - paths.append(_snapshot_path(media_root, snap["id"])) + paths.append(_snapshot_disk(conn, snap["id"], media_root)) conn.execute("DELETE FROM dispatch_snapshots WHERE id = %s", (snap["id"],)) conn.execute( """ @@ -916,17 +933,22 @@ def _working_bytes(conn, actor, element, media_root: str): def _store_snapshot(conn, scope_id, actor, payload: FilePayload, media_root: str, cleanup: list[Path], dispatch_item_id: UUID | None = None, evidence_id: UUID | None = None) -> UUID: snapshot_id = uuid4() - path = _snapshot_path(media_root, snapshot_id) - write_bytes(path, payload.data) - cleanup.append(path) + instance = instance_for_write(conn, media_root) + object_key = f"dispatch/{snapshot_id}" + content_revision = str(uuid4()) + adapter = LocalAdapter(instance["root_path"]) + publish(adapter, object_key, payload.data) + cleanup.append(stored_path(conn, instance["id"], instance["generation"], object_key, media_root)) digest = sha256(payload.data) conn.execute( """ INSERT INTO dispatch_snapshots ( id, dispatch_item_id, evidence_id, home_scope_id, owner_subject_id, - original_filename, content_type, byte_size, sha256 + original_filename, content_type, byte_size, sha256, + storage_instance_id, storage_generation, object_key, content_revision, + protection_profile, key_responsibility ) - VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s) + VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, 'none') """, ( snapshot_id, @@ -938,6 +960,11 @@ def _store_snapshot(conn, scope_id, actor, payload: FilePayload, media_root: str payload.media_type or "application/octet-stream", len(payload.data), digest, + instance["id"], + instance["generation"], + object_key, + content_revision, + LEGACY_PROFILE, ), ) return snapshot_id @@ -956,20 +983,36 @@ def _snapshot_file(conn, media_root: str, dispatch_item_id: UUID | None = None, ).fetchone() if row is None: raise not_found() - data = read_bytes(_snapshot_path(media_root, row["id"])) - if sha256(data) != row["sha256"]: - raise not_found() + profile = row["protection_profile"] or "legacy-plaintext" + data = read_clear_bytes( + conn, + instance_id=row["storage_instance_id"], + generation=row["storage_generation"], + object_key=row["object_key"] or f"dispatch/{row['id']}", + media_root=media_root, + protection_profile=profile, + expected_sha256=row["sha256"], + ) return FilePayload(row["original_filename"], row["content_type"], data, row["sha256"]) -def _snapshot_path(media_root: str, snapshot_id: UUID) -> Path: - root = Path(media_root).resolve() - folder = (root / "dispatch").resolve() - folder.mkdir(parents=True, exist_ok=True) - target = (folder / str(snapshot_id)).resolve() - if target.parent != folder: - raise unprocessable("Ungültiger Speicherpfad.") - return target +def _snapshot_disk(conn, snapshot_id: UUID, media_root: str) -> Path: + row = conn.execute( + """ + SELECT id, storage_instance_id, storage_generation, object_key + FROM dispatch_snapshots WHERE id = %s + """, + (snapshot_id,), + ).fetchone() + if row is None: + return stored_path(conn, None, "legacy-local-1", f"dispatch/{snapshot_id}", media_root) + return stored_path( + conn, + row["storage_instance_id"], + row["storage_generation"], + row["object_key"] or f"dispatch/{row['id']}", + media_root, + ) def _snapshot_id(conn, dispatch_item_id: UUID | None = None, evidence_id: UUID | None = None) -> str | None: @@ -1416,5 +1459,5 @@ def _delete_dispatch_files(conn, dispatch_id: UUID, media_root: str) -> list[Pat (dispatch_id, dispatch_id), ).fetchall() for row in rows: - paths.append(_snapshot_path(media_root, row["id"])) + paths.append(_snapshot_disk(conn, row["id"], media_root)) return paths diff --git a/backend/app/db/migrate.py b/backend/app/db/migrate.py index a2ff974..96b1025 100644 --- a/backend/app/db/migrate.py +++ b/backend/app/db/migrate.py @@ -49,9 +49,22 @@ def migrate(settings: Settings | None = None) -> list[str]: ) applied.append(version) _ensure_runtime_role(conn, settings) + _prepare_source_storage(settings) return applied +def _prepare_source_storage(settings: Settings) -> None: + from psycopg.rows import dict_row + + from app.media.port import ensure_legacy_instance + from app.sourcebind import backfill_source_bindings + + with psycopg.connect(settings.dsn(), row_factory=dict_row) as conn: + backfill_source_bindings(conn) + ensure_legacy_instance(conn, settings.media_root) + conn.commit() + + def _ensure_runtime_role(conn: psycopg.Connection, settings: Settings) -> None: role = sql.Identifier(settings.db_runtime_user) database = sql.Identifier(settings.db_name) diff --git a/backend/app/exporting.py b/backend/app/exporting.py index 79e614a..0bcd680 100644 --- a/backend/app/exporting.py +++ b/backend/app/exporting.py @@ -39,6 +39,7 @@ _KIND_LABEL = { "file": "Datei", "email": "E-Mail", "paperless": "Paperless", + "source": "Quelle", "url": "Webadresse", "annotation": "Anmerkung", "chapter": "Kapitel", @@ -233,7 +234,7 @@ def _plan(conn, actor, matter_id, context, selected, assignments, media_root) -> continue if node.content_kind == "file": result = load_file(conn, UUID(node.element_id), media_root) - elif node.content_kind in {"email", "paperless", "url"}: + elif node.content_kind in {"email", "paperless", "url", "source"}: result = load_external(conn, actor, UUID(node.element_id), assignments.get(node.id)) else: result = RetrievalFailure("capability", "Für diesen Inhalt ist kein Originalabruf vorgesehen.") @@ -461,13 +462,16 @@ def _content_kind(element: dict) -> str: if element["kind"] == "file": return "file" source = (element.get("external") or {}).get("source") - if source == "imap": - return "email" - if source == "paperless": - return "paperless" if source == "url": return "url" - return element["kind"] + from app.sourceregistry import get_source + + module = get_source(source) if source else None + if module is None: + return "source" + if module.representation == "email": + return "email" + return "source" def _chosen(root: ExportNode, selected: list[str]) -> set[str]: diff --git a/backend/app/media/port.py b/backend/app/media/port.py new file mode 100644 index 0000000..eb0e030 --- /dev/null +++ b/backend/app/media/port.py @@ -0,0 +1,247 @@ +"""Opaque storage port. The adapter stores bytes and does not decide who may read them. + +Cleartext for a reader goes through require_cleartext. Locked profiles stay +bytes on disk and are not decrypted here. No new cryptography is implemented. +""" + +from __future__ import annotations + +import hashlib +from pathlib import Path +from uuid import UUID + +from app.core.errors import Problem, storage_unavailable, unprocessable +from app.media.storage import read_bytes, sha256, write_bytes + +LEGACY_GENERATION = "legacy-local-1" +LEGACY_PROFILE = "legacy-plaintext" +LOCKED_PROFILES = frozenset({"managed-encrypted", "client-encrypted"}) +PROFILES = frozenset({LEGACY_PROFILE, *LOCKED_PROFILES}) + + +def require_cleartext(profile: str | None) -> None: + name = profile or LEGACY_PROFILE + if name == LEGACY_PROFILE: + return + if name in LOCKED_PROFILES: + raise Problem( + 422, + "Geschützter Inhalt", + "Dieser Inhalt ist geschützt. Ein Klartextabruf ist in dieser Lieferung nicht möglich.", + "unsupported", + ) + raise Problem( + 422, + "Nicht unterstützt", + "Dieses Schutzprofil wird nicht unterstützt.", + "unsupported", + ) + + +def check_object_key(object_key: str) -> str: + key = (object_key or "").replace("\\", "/").strip() + parts = key.split("/") + if not key or key.startswith("/") or any(part in {"", ".", ".."} for part in parts): + raise unprocessable("Ungültiger Speicherpfad.") + try: + if len(parts) == 1: + UUID(parts[0]) + elif len(parts) == 2 and parts[0] == "dispatch": + UUID(parts[1]) + else: + raise ValueError + except ValueError: + raise unprocessable("Ungültiger Speicherpfad.") from None + return key + + +def object_path(root: Path, object_key: str) -> Path: + key = check_object_key(object_key) + base = Path(root).resolve() + base.mkdir(parents=True, exist_ok=True) + target = (base / key).resolve() + if base != target and base not in target.parents: + raise unprocessable("Ungültiger Speicherpfad.") + return target + + +class LocalAdapter: + """Files stay under one recorded root. A client path is not an address.""" + + def __init__(self, root: str | Path) -> None: + self.root = Path(root) + + def put(self, object_key: str, data: bytes) -> None: + path = object_path(self.root, object_key) + path.parent.mkdir(parents=True, exist_ok=True) + write_bytes(path, data) + + def open(self, object_key: str) -> bytes: + return read_bytes(object_path(self.root, object_key)) + + def delete(self, object_key: str) -> None: + path = object_path(self.root, object_key) + try: + path.unlink(missing_ok=True) + except OSError as exc: + raise storage_unavailable() from exc + + def describe(self, object_key: str) -> dict: + path = object_path(self.root, object_key) + try: + if not path.is_file(): + raise storage_unavailable() + return {"byte_size": path.stat().st_size, "object_key": object_key} + except OSError as exc: + raise storage_unavailable() from exc + + +class MemoryAdapter: + """In-memory stand-in for the same port. It is not a second product store.""" + + def __init__(self) -> None: + self._items: dict[str, bytes] = {} + self.fail_put = False + + def put(self, object_key: str, data: bytes) -> None: + if self.fail_put: + raise storage_unavailable() + key = check_object_key(object_key) + self._items[key] = bytes(data) + + def open(self, object_key: str) -> bytes: + key = check_object_key(object_key) + try: + return self._items[key] + except KeyError as exc: + raise storage_unavailable() from exc + + def delete(self, object_key: str) -> None: + key = check_object_key(object_key) + self._items.pop(key, None) + + def describe(self, object_key: str) -> dict: + data = self.open(object_key) + return {"byte_size": len(data), "object_key": object_key} + + +def publish(adapter, object_key: str, data: bytes) -> None: + """Make bytes readable only after a checked roundtrip. A failed put leaves nothing published.""" + adapter.put(object_key, data) + try: + opened = adapter.open(object_key) + except Problem: + adapter.delete(object_key) + raise + if opened != data: + adapter.delete(object_key) + raise storage_unavailable() + + +def ensure_legacy_instance(conn, media_root: str) -> dict: + """Bind the legacy generation to the current root once. Later roots do not retarget it.""" + root = str(Path(media_root).resolve()) + conn.execute( + """ + INSERT INTO storage_instances (kind, generation, root_path) + VALUES ('local', %s, %s) + ON CONFLICT (generation) DO NOTHING + """, + (LEGACY_GENERATION, root), + ) + conn.execute( + """ + UPDATE storage_instances + SET root_path = %s + WHERE generation = %s AND root_path IS NULL + """, + (root, LEGACY_GENERATION), + ) + row = conn.execute( + """ + SELECT id, kind, generation, root_path + FROM storage_instances + WHERE generation = %s + """, + (LEGACY_GENERATION,), + ).fetchone() + conn.execute( + """ + UPDATE media_assets + SET storage_instance_id = %s + WHERE storage_generation = %s AND storage_instance_id IS NULL + """, + (row["id"], LEGACY_GENERATION), + ) + conn.execute( + """ + UPDATE dispatch_snapshots + SET storage_instance_id = %s + WHERE storage_generation = %s AND storage_instance_id IS NULL + """, + (row["id"], LEGACY_GENERATION), + ) + return row + + +def instance_for_write(conn, media_root: str) -> dict: + legacy = ensure_legacy_instance(conn, media_root) + root = str(Path(media_root).resolve()) + if legacy["root_path"] == root: + return legacy + generation = "local-" + hashlib.sha256(root.encode("utf-8")).hexdigest()[:16] + conn.execute( + """ + INSERT INTO storage_instances (kind, generation, root_path) + VALUES ('local', %s, %s) + ON CONFLICT (generation) DO NOTHING + """, + (generation, root), + ) + return conn.execute( + """ + SELECT id, kind, generation, root_path + FROM storage_instances + WHERE generation = %s + """, + (generation,), + ).fetchone() + + +def resolve_root(conn, instance_id, generation: str | None, media_root: str) -> str: + if instance_id is not None: + row = conn.execute( + "SELECT root_path FROM storage_instances WHERE id = %s", + (instance_id,), + ).fetchone() + if row is not None and row["root_path"]: + return row["root_path"] + if generation in {None, LEGACY_GENERATION}: + return ensure_legacy_instance(conn, media_root)["root_path"] + return str(Path(media_root).resolve()) + + +def stored_path(conn, instance_id, generation: str | None, object_key: str, media_root: str) -> Path: + return object_path(Path(resolve_root(conn, instance_id, generation, media_root)), object_key) + + +def read_clear_bytes( + conn, + *, + instance_id, + generation: str | None, + object_key: str, + media_root: str, + protection_profile: str | None, + expected_sha256: str | None, +) -> bytes: + require_cleartext(protection_profile) + data = LocalAdapter(resolve_root(conn, instance_id, generation, media_root)).open(object_key) + if expected_sha256 and sha256(data) != expected_sha256: + raise Problem( + 422, + "Inhalt nicht geprüft", + "Die gespeicherte Datei stimmt nicht mit dem erfassten Stand überein.", + "processing", + ) + return data diff --git a/backend/app/ops.py b/backend/app/ops.py index 628a4b9..e0da156 100644 --- a/backend/app/ops.py +++ b/backend/app/ops.py @@ -33,9 +33,11 @@ from app.access.policy import ( task_rights, ) from app.content.documents import clean_document -from app.core.errors import forbidden, not_found, unprocessable +from app.core.errors import forbidden, not_found, unprocessable, unsupported from app.core.timeutil import utcnow -from app.media.storage import asset_path, display_filename, sha256, sniff, write_bytes +from app.media.port import LEGACY_PROFILE, instance_for_write, publish, stored_path +from app.media.port import LocalAdapter +from app.media.storage import display_filename, sha256, sniff MAX_CHAPTER_DEPTH = 32 @@ -929,7 +931,7 @@ def update_note(conn, actor: UUID, element_id: UUID, expected: int, document: di document = clean_document(document) element, rights = require_element(conn, actor, element_id, context, "edit") if element["kind"] != "note": - raise not_found() + raise unsupported("Diese Fassung lässt sich nicht als Notiz bearbeiten.") if not rights.edit: raise forbidden() version = bump_version(conn, "elements", element_id, expected) @@ -998,6 +1000,10 @@ def add_annotation(conn, actor: UUID, binding_id: UUID, body: str, context: Ctx def create_external(conn, actor: UUID, scope_id: UUID, title: str, source: str, external_id: str, context: Ctx, placement: Ctx | None, chapter_id: UUID | None, document_on, sent_on, received_on, detail: dict | None = None, communication_direction: str | None = None) -> dict: + from app.sourceregistry import accepts_reference + + if not accepts_reference(source): + raise unprocessable("Diese Quelle ist nicht registriert.") target, rights_context = _placement(context, placement) require_container_edit(conn, actor, target, rights_context) element = _new_element(conn, actor, scope_id, title, "external_ref") @@ -1005,8 +1011,11 @@ def create_external(conn, actor: UUID, scope_id: UUID, title: str, source: str, "INSERT INTO external_references (element_id, source, external_id, detail) VALUES (%s, %s, %s, %s)", (element["id"], source, external_id.strip()[:200], Json(detail or {})), ) + from app.sourcebind import attach_new_reference + + attach_new_reference(conn, element["id"]) binding = insert_binding(conn, element["id"], target.kind, target.id, chapter_id, actor) - adopted = (detail or {}).get("direction") if source == "imap" else None + adopted = (detail or {}).get("direction") chosen = chosen_direction(communication_direction) or (adopted if adopted in ("in", "out") else None) store_direction(conn, binding["id"], chosen, chosen is not None) record_dates(conn, actor, scope_id, element["id"], rights_context or target, document_on, sent_on, received_on) @@ -1022,16 +1031,23 @@ def create_file(conn, actor: UUID, scope_id: UUID, title: str, filename: str, da require_container_edit(conn, actor, target, rights_context) element = _new_element(conn, actor, scope_id, title, "file") asset_id = uuid4() - path = asset_path(media_root, asset_id) - write_bytes(path, data) + content_revision = str(uuid4()) + instance = instance_for_write(conn, media_root) + object_key = str(asset_id) + adapter = LocalAdapter(instance["root_path"]) + publish(adapter, object_key, data) + path = stored_path(conn, instance["id"], instance["generation"], object_key, media_root) rollback_files.append(path) + digest = sha256(data) conn.execute( """ INSERT INTO media_assets ( id, element_id, owner_subject_id, home_scope_id, original_filename, - content_type, byte_size, sha256, status + content_type, byte_size, sha256, status, storage_instance_id, + storage_generation, object_key, content_revision, protection_profile, + key_responsibility ) - VALUES (%s, %s, %s, %s, %s, %s, %s, %s, 'active') + VALUES (%s, %s, %s, %s, %s, %s, %s, %s, 'active', %s, %s, %s, %s, %s, 'none') """, ( asset_id, @@ -1041,7 +1057,12 @@ def create_file(conn, actor: UUID, scope_id: UUID, title: str, filename: str, da display_filename(filename), content_type, len(data), - sha256(data), + digest, + instance["id"], + instance["generation"], + object_key, + content_revision, + LEGACY_PROFILE, ), ) conn.execute( @@ -1075,7 +1096,15 @@ def delete_element(conn, actor: UUID, element_id: UUID, expected: int, media_roo ) if asset is not None and asset["status"] == "active": conn.execute("UPDATE media_assets SET status = 'purging' WHERE id = %s", (asset["id"],)) - delete_after.append(asset_path(media_root, asset["id"])) + delete_after.append( + stored_path( + conn, + asset["storage_instance_id"], + asset["storage_generation"], + asset["object_key"] or str(asset["id"]), + media_root, + ) + ) conn.execute("UPDATE media_assets SET status = 'purged' WHERE id = %s", (asset["id"],)) audit(conn, actor, element["home_scope_id"], "element_deleted", "element", element_id) diff --git a/backend/app/present.py b/backend/app/present.py index b356096..2fda1e5 100644 --- a/backend/app/present.py +++ b/backend/app/present.py @@ -117,10 +117,16 @@ def _preview_meta(kind: str, content_type: str | None, source: str | None) -> di return {"available": True, "media": "image", "source": "file"} if kind == "file" and media == "application/pdf": return {"available": True, "media": "pdf", "source": "file"} - if kind == "external_ref" and source == "paperless": - return {"available": True, "media": "paperless", "source": "paperless"} - if kind == "external_ref" and source == "imap": - return {"available": True, "media": "email", "source": "imap"} + if kind == "external_ref" and source: + from app.sourceregistry import get_source + + module = get_source(source) + if module is not None: + return { + "available": bool(module.capabilities.get("read_preview")), + "media": module.representation, + "source": source, + } if kind == "file": return {"available": False, "media": "file", "source": "file"} return {"available": False, "media": "none", "source": source} @@ -175,35 +181,49 @@ def _element_body(conn, actor: UUID, element: dict) -> dict: elif element["kind"] == "file": asset = conn.execute( """ - SELECT original_filename, content_type, byte_size, status + SELECT original_filename, content_type, byte_size, status, protection_profile FROM media_assets WHERE element_id = %s """, (element["id"],), ).fetchone() if asset is not None: + profile = asset["protection_profile"] or "legacy-plaintext" payload["file"] = { "filename": asset["original_filename"], "content_type": asset["content_type"], "byte_size": asset["byte_size"], "status": asset["status"], + "protection_profile": profile, } - payload["preview"] = _preview_meta("file", asset["content_type"], "file") + if profile != "legacy-plaintext": + payload["preview"] = {"available": False, "media": "locked", "source": "file"} + else: + payload["preview"] = _preview_meta("file", asset["content_type"], "file") elif element["kind"] == "external_ref": ref = conn.execute( - "SELECT source, external_id, detail FROM external_references WHERE element_id = %s", + """ + SELECT source, external_id, detail, connector_id, resolution + FROM external_references WHERE element_id = %s + """, (element["id"],), ).fetchone() if ref is not None: detail = dict(ref["detail"] or {}) - connector_owner = _connector_owner(conn, detail.get("connector_id")) + connector_owner = _connector_owner(conn, ref["connector_id"] or detail.get("connector_id")) revealed = actor == element["owner_subject_id"] or (connector_owner is not None and actor == connector_owner) if not revealed: detail = {key: value for key, value in detail.items() if key not in _HIDDEN_SOURCE_FIELDS} - external = {"source": ref["source"], "detail": detail} + resolution = ref["resolution"] or "unresolved" + external = {"source": ref["source"], "detail": detail, "resolution": resolution} if revealed: external["external_id"] = ref["external_id"] payload["external"] = external - payload["preview"] = _preview_meta("external_ref", None, ref["source"]) + from app.sourceregistry import get_source + + if resolution in {"ambiguous", "unresolved"} and get_source(ref["source"]) is not None: + payload["preview"] = {"available": False, "media": "unassigned", "source": ref["source"]} + else: + payload["preview"] = _preview_meta("external_ref", None, ref["source"]) return payload @@ -237,7 +257,7 @@ def communication_from_row(conn, binding: dict, element: dict) -> dict: "SELECT source, detail FROM external_references WHERE element_id = %s", (element["id"],), ).fetchone() - detail = (ref["detail"] or {}) if ref is not None and ref["source"] == "imap" else {} + detail = (ref["detail"] or {}) if ref is not None else {} if detail.get("direction") in ("in", "out"): source = detail["direction"] return {"direction": source, "explicit": False} diff --git a/backend/app/retrieval.py b/backend/app/retrieval.py index 33300b4..dc041e3 100644 --- a/backend/app/retrieval.py +++ b/backend/app/retrieval.py @@ -10,17 +10,12 @@ from dataclasses import dataclass, field from uuid import UUID from app.core.errors import Problem -from app.mailpack import ParsedMail, identities_match, parse_mail -from app.media.storage import asset_path, read_bytes -from app.sources import COMPLETE_MAIL_LIMIT, pull_paperless_original, pull_rfc822 +from app.mailpack import ParsedMail +from app.media.port import read_clear_bytes +from app.sources import COMPLETE_MAIL_LIMIT EXPORT_BYTE_LIMIT = COMPLETE_MAIL_LIMIT -_TOO_LARGE = ( - "Die vollständige Nachricht überschreitet die Exportgrenze. " - "Eine gekürzte Vorschau wird nicht als Original übernommen." -) - @dataclass(frozen=True) class RetrievalFailure: @@ -45,132 +40,59 @@ class MailPayload: def load_external(conn, actor_id: UUID, element_id: UUID, assigned: UUID | None) -> FilePayload | MailPayload | RetrievalFailure: + from app.sourceregistry import get_source + ref = conn.execute( - "SELECT source, external_id, detail FROM external_references WHERE element_id = %s", + """ + SELECT source, external_id, detail, connector_id, resolution + FROM external_references WHERE element_id = %s + """, (element_id,), ).fetchone() if ref is None: return RetrievalFailure("missing", "Die Quellenreferenz fehlt.") - source = ref["source"] - detail = ref["detail"] or {} - if source == "paperless": - return _load_paperless(conn, actor_id, ref["external_id"], detail, assigned) - if source == "imap": - return _load_imap(conn, actor_id, ref["external_id"], detail, assigned) - if source == "url": - return RetrievalFailure("capability", "Für eine Webadresse ist kein Originalabruf vorgesehen.") - return RetrievalFailure("capability", "Für diese Quelle ist kein Originalabruf vorgesehen.") + module = get_source(ref["source"]) + if module is None or module.export_original is None: + return RetrievalFailure("capability", "Für diese Quelle ist kein Originalabruf vorgesehen.") + return module.export_original(conn, actor_id, ref["external_id"], ref["detail"] or {}, assigned, ref) def load_file(conn, element_id: UUID, media_root: str) -> FilePayload | RetrievalFailure: asset = conn.execute( """ - SELECT id, original_filename, content_type, sha256, status + SELECT id, original_filename, content_type, sha256, status, + storage_instance_id, storage_generation, object_key, protection_profile FROM media_assets WHERE element_id = %s """, (element_id,), ).fetchone() if asset is None or asset["status"] != "active": return RetrievalFailure("missing", "Die Originaldatei ist nicht mehr vorhanden.") + if (asset["protection_profile"] or "legacy-plaintext") != "legacy-plaintext": + return RetrievalFailure( + "unsupported", + "Dieser Inhalt ist geschützt und kann hier nicht im Klartext gelesen werden.", + ) try: - data = read_bytes(asset_path(media_root, asset["id"])) - except Problem: + data = read_clear_bytes( + conn, + instance_id=asset["storage_instance_id"], + generation=asset["storage_generation"], + object_key=asset["object_key"] or str(asset["id"]), + media_root=media_root, + protection_profile=asset["protection_profile"], + expected_sha256=asset["sha256"], + ) + except Problem as exc: + if exc.code == "unsupported": + return RetrievalFailure("unsupported", exc.detail) return RetrievalFailure("missing", "Die Originaldatei ist nicht mehr vorhanden.") if len(data) > EXPORT_BYTE_LIMIT: return RetrievalFailure("too_large", "Die Originaldatei ist für den Export zu groß.") return FilePayload(asset["original_filename"], asset["content_type"], data, asset["sha256"]) -def _load_paperless(conn, actor_id: UUID, external_id: str, detail: dict, assigned: UUID | None): - stored = _uuid(detail.get("connector_id")) - resolved = _resolve_connector(conn, actor_id, "paperless", stored, assigned) - if isinstance(resolved, RetrievalFailure): - return resolved - try: - data, media, name = pull_paperless_original( - resolved["settings"]["base_url"].rstrip("/"), - resolved["secret"], - str(external_id), - EXPORT_BYTE_LIMIT, - ) - except Problem as exc: - return _from_problem(exc) - if len(data) > EXPORT_BYTE_LIMIT: - return RetrievalFailure("too_large", "Die Originaldatei ist für den Export zu groß.") - return FilePayload(name or f"paperless-{external_id}", media, data, "") - - -def _load_imap(conn, actor_id: UUID, external_id: str, detail: dict, assigned: UUID | None): - stored = _uuid(detail.get("connector_id")) - resolved = _resolve_connector(conn, actor_id, "imap", stored, assigned) - if isinstance(resolved, RetrievalFailure): - return resolved - mailbox = str(detail.get("mailbox") or "").strip() - uid = detail.get("uid") - if isinstance(uid, str) and uid.isdigit(): - uid = int(uid) - if not mailbox or isinstance(uid, bool) or not isinstance(uid, int) or uid < 1: - return RetrievalFailure("identity", "Für diese E-Mail fehlt die Zuordnung zu Fach und Nachricht.") - try: - raw = pull_rfc822(resolved["settings"], resolved["secret"], mailbox, uid, str(external_id), EXPORT_BYTE_LIMIT) - except Problem as exc: - return _from_problem(exc) - if len(raw) > EXPORT_BYTE_LIMIT: - return RetrievalFailure("too_large", _TOO_LARGE) - parsed = parse_mail(raw) - if not identities_match(parsed.message_id, str(external_id)): - return RetrievalFailure("identity", "Die gefundene Nachricht ist nicht die referenzierte E-Mail.") - if parsed.missing: - names = ", ".join(parsed.missing[:5]) - return RetrievalFailure("attachment", f"Eine Anlage der E-Mail ließ sich nicht vollständig lesen: {names}.") - return MailPayload(raw, parsed) - - -def _resolve_connector(conn, actor_id: UUID, kind: str, stored: UUID | None, assigned: UUID | None): - rows = conn.execute( - """ - SELECT id, kind, name, settings, secret - FROM connectors - WHERE owner_id = %s AND kind = %s - ORDER BY name, id - """, - (actor_id, kind), - ).fetchall() - if stored is not None and assigned is None: - match = next((row for row in rows if row["id"] == stored), None) - if match is None: - return RetrievalFailure("missing", "Der gespeicherte Zugang für diese Quelle ist nicht mehr vorhanden.") - return match - chosen = assigned or stored - if chosen is not None: - match = next((row for row in rows if row["id"] == chosen), None) - if match is None: - return RetrievalFailure( - "assignment", - "Der gewählte Zugang gehört nicht zu diesem Konto oder passt nicht zur Quelle.", - ) - return match - if len(rows) == 1: - return rows[0] - if not rows: - return RetrievalFailure("missing", "Für diese Quelle ist kein Zugang vorhanden.") - return RetrievalFailure( - "ambiguous", - "Für diese Quelle ist kein eindeutiger Zugang zugeordnet. Die Zuordnung muss bewusst gewählt werden.", - tuple({"id": str(row["id"]), "name": row["name"]} for row in rows), - ) - - -def _uuid(value) -> UUID | None: - if not value: - return None - try: - return UUID(str(value)) - except ValueError: - return None - - -def _from_problem(exc: Problem) -> RetrievalFailure: +def failure_from_problem(exc: Problem) -> RetrievalFailure: text = exc.detail lowered = text.casefold() if "exportgrenze" in lowered or "zu groß" in lowered: diff --git a/backend/app/sourcebind.py b/backend/app/sourcebind.py new file mode 100644 index 0000000..85c18e3 --- /dev/null +++ b/backend/app/sourcebind.py @@ -0,0 +1,211 @@ +"""Bind a reference to one connector instance. + +The newest connection is never a fallback. A stored id that no longer +exists stays missing. Ambiguous stock waits for an explicit assignment. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from uuid import UUID + +from psycopg.types.json import Json + +from app.access.policy import get_element +from app.core.errors import not_found, unprocessable +from app.sourceregistry import get_source + + +@dataclass(frozen=True) +class ResolveResult: + row: dict | None + code: str + message: str + choices: tuple[dict, ...] = () + + +def _uuid(value) -> UUID | None: + if isinstance(value, UUID): + return value + if not value: + return None + try: + return UUID(str(value)) + except (TypeError, ValueError): + return None + + +def stored_id(ref) -> UUID | None: + if not ref: + return None + detail = ref["detail"] if "detail" in ref.keys() else None + detail = detail or {} + return _uuid(detail.get("connector_id")) or _uuid(ref["connector_id"] if "connector_id" in ref.keys() else None) + + +def _connectors(conn, owner_id: UUID, kind: str) -> list[dict]: + return conn.execute( + """ + SELECT id, owner_id, kind, name, settings, secret + FROM connectors + WHERE owner_id = %s AND kind = %s + ORDER BY name, id + """, + (owner_id, kind), + ).fetchall() + + +def resolve_for_read(conn, owner_id: UUID, kind: str, ref, assigned: UUID | None) -> ResolveResult: + """Resolve one access. Assignment applies only when the reference has no stored id.""" + stored = stored_id(ref) + resolution = (ref["resolution"] if ref and "resolution" in ref.keys() and ref["resolution"] else None) or "unresolved" + rows = _connectors(conn, owner_id, kind) + if stored is not None: + match = next((row for row in rows if row["id"] == stored), None) + if match is None: + return ResolveResult(None, "missing", "Der gespeicherte Zugang für diese Quelle ist nicht mehr vorhanden.") + return ResolveResult(match, "ok", "") + if assigned is not None: + match = next((row for row in rows if row["id"] == assigned), None) + if match is None: + return ResolveResult( + None, + "assignment", + "Der gewählte Zugang gehört nicht zu diesem Konto oder passt nicht zur Quelle.", + ) + return ResolveResult(match, "ok", "") + if resolution == "ambiguous" or len(rows) != 1: + if not rows: + return ResolveResult(None, "missing", "Für diese Quelle ist kein Zugang vorhanden.") + return ResolveResult( + None, + "ambiguous", + "Für diese Quelle ist kein eindeutiger Zugang zugeordnet. Die Zuordnung muss bewusst gewählt werden.", + tuple({"id": str(row["id"]), "name": row["name"]} for row in rows), + ) + return ResolveResult(rows[0], "ok", "") + + +def _set_binding(conn, element_id: UUID, connector_id: UUID | None, resolution: str, detail: dict | None = None) -> None: + if detail is None: + conn.execute( + """ + UPDATE external_references + SET connector_id = %s, resolution = %s + WHERE element_id = %s + """, + (connector_id, resolution, element_id), + ) + return + conn.execute( + """ + UPDATE external_references + SET connector_id = %s, resolution = %s, detail = %s + WHERE element_id = %s + """, + (connector_id, resolution, Json(detail), element_id), + ) + + +def attach_new_reference(conn, element_id: UUID) -> None: + row = conn.execute( + """ + SELECT er.source, er.detail, e.owner_subject_id + FROM external_references er + JOIN elements e ON e.id = er.element_id + WHERE er.element_id = %s + """, + (element_id,), + ).fetchone() + if row is None: + return + if get_source(row["source"]) is None: + _set_binding(conn, element_id, None, "none") + return + detail = dict(row["detail"] or {}) + stored = _uuid(detail.get("connector_id")) + if stored is not None: + match = conn.execute( + """ + SELECT id FROM connectors + WHERE id = %s AND owner_id = %s AND kind = %s + """, + (stored, row["owner_subject_id"], row["source"]), + ).fetchone() + _set_binding(conn, element_id, stored, "bound" if match else "unresolved") + return + rows = _connectors(conn, row["owner_subject_id"], row["source"]) + if len(rows) == 1: + detail["connector_id"] = str(rows[0]["id"]) + _set_binding(conn, element_id, rows[0]["id"], "bound", detail) + return + if len(rows) > 1: + _set_binding(conn, element_id, None, "ambiguous") + return + _set_binding(conn, element_id, None, "unresolved") + + +def backfill_source_bindings(conn) -> None: + """Idempotent. Bound and ambiguous rows stay. Unique unresolved stock is bound once.""" + conn.execute( + """ + UPDATE external_references + SET resolution = 'none' + WHERE source = 'url' AND resolution = 'unresolved' + """ + ) + rows = conn.execute( + """ + SELECT er.element_id, er.source, er.detail, e.owner_subject_id + FROM external_references er + JOIN elements e ON e.id = er.element_id + WHERE er.source <> 'url' + AND er.resolution = 'unresolved' + AND er.connector_id IS NULL + """ + ).fetchall() + for row in rows: + if get_source(row["source"]) is None: + continue + detail = dict(row["detail"] or {}) + stored = _uuid(detail.get("connector_id")) + if stored is not None: + match = conn.execute( + """ + SELECT id FROM connectors + WHERE id = %s AND owner_id = %s AND kind = %s + """, + (stored, row["owner_subject_id"], row["source"]), + ).fetchone() + _set_binding(conn, row["element_id"], stored, "bound" if match else "unresolved") + continue + found = _connectors(conn, row["owner_subject_id"], row["source"]) + if len(found) == 1: + detail["connector_id"] = str(found[0]["id"]) + _set_binding(conn, row["element_id"], found[0]["id"], "bound", detail) + elif len(found) > 1: + _set_binding(conn, row["element_id"], None, "ambiguous") + + +def assign_reference(conn, actor_id: UUID, element_id: UUID, connector_id: UUID) -> None: + element = get_element(conn, element_id) + if element is None or element["kind"] != "external_ref" or element["owner_subject_id"] != actor_id: + raise not_found() + ref = conn.execute( + "SELECT source, detail FROM external_references WHERE element_id = %s", + (element_id,), + ).fetchone() + if ref is None or get_source(ref["source"]) is None: + raise unprocessable("Diese Referenz hat keinen Quellzugang.") + connector = conn.execute( + """ + SELECT id, kind FROM connectors + WHERE id = %s AND owner_id = %s + """, + (connector_id, actor_id), + ).fetchone() + if connector is None or connector["kind"] != ref["source"]: + raise unprocessable("Der Zugang gehört nicht zu diesem Konto oder passt nicht zur Quelle.") + detail = dict(ref["detail"] or {}) + detail["connector_id"] = str(connector_id) + _set_binding(conn, element_id, connector_id, "bound", detail) diff --git a/backend/app/sourceport.py b/backend/app/sourceport.py new file mode 100644 index 0000000..01f19e0 --- /dev/null +++ b/backend/app/sourceport.py @@ -0,0 +1,98 @@ +"""Declared source and editor capabilities. + +A common contract does not invent abilities the adapter does not have. +Search filters that are false stay unavailable until a later delivery. +""" + +from __future__ import annotations + +PAPERLESS_CAPABILITIES = { + "kind": "paperless", + "navigate": False, + "read_original": True, + "read_preview": True, + "read_attachment": False, + "edit_content": False, + "edit_metadata": False, + "search": { + "query": True, + "title": False, + "correspondent": False, + "document_type": False, + "tags": False, + "document_range": False, + "sort": False, + "continuation": False, + }, +} + +IMAP_CAPABILITIES = { + "kind": "imap", + "navigate": True, + "read_original": True, + "read_preview": True, + "read_attachment": True, + "edit_content": False, + "edit_metadata": False, + "search": { + "query": True, + "title": False, + "correspondent": False, + "document_type": False, + "tags": False, + "document_range": False, + "sort": False, + "continuation": True, + }, +} + +CAPABILITIES = { + "paperless": PAPERLESS_CAPABILITIES, + "imap": IMAP_CAPABILITIES, +} + +EDITORS = { + "note": True, + "markdown_file": False, +} + +UNSUPPORTED_SEARCH = ( + "title", + "correspondent", + "document_type", + "tag", + "document_from", + "document_to", + "sort", + "cursor", +) + + +def capability_payload() -> dict: + from app.sourceregistry import registered_sources + + return { + "sources": [module.capabilities for module in registered_sources()], + "editors": EDITORS, + "protection_profiles": { + "legacy-plaintext": "cleartext", + "managed-encrypted": "locked", + "client-encrypted": "locked", + }, + } + + +def unsupported_filters(values: dict[str, str]) -> list[str]: + return [name for name in UNSUPPORTED_SEARCH if str(values.get(name) or "").strip()] + + +def with_capabilities(kind: str, connector_id: str, payload: dict) -> dict: + from app.sourceregistry import require_source + + body = dict(payload) + spec = require_source(kind).capabilities + body["connector_id"] = connector_id + body["capabilities"] = spec + body["unsupported"] = [name for name, enabled in spec["search"].items() if not enabled] + body["continuation"] = body.get("next_before") if spec["search"].get("continuation") else None + return body diff --git a/backend/app/sourceregistry.py b/backend/app/sourceregistry.py new file mode 100644 index 0000000..93e8d1e --- /dev/null +++ b/backend/app/sourceregistry.py @@ -0,0 +1,53 @@ +"""Registered source modules. Unknown kinds are rejected, not guessed.""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Callable + +from app.core.errors import unprocessable + + +@dataclass +class SourceModule: + kind: str + label: str + representation: str + capabilities: dict + parse_config: Callable[[dict], tuple[str, dict, str]] + probe: Callable + find: Callable + open_original: Callable + export_original: Callable + navigate: Callable | None = None + preview: Callable | None = None + + +_MODULES: dict[str, SourceModule] = {} + + +def register_source(module: SourceModule) -> None: + _MODULES[module.kind] = module + + +def unregister_source(kind: str) -> None: + _MODULES.pop(kind, None) + + +def registered_sources() -> list[SourceModule]: + return list(_MODULES.values()) + + +def get_source(kind: str) -> SourceModule | None: + return _MODULES.get(kind) + + +def require_source(kind: str) -> SourceModule: + module = _MODULES.get(kind) + if module is None: + raise unprocessable("Diese Quelle ist nicht registriert.") + return module + + +def accepts_reference(source: str) -> bool: + return source == "url" or source in _MODULES diff --git a/backend/app/sources.py b/backend/app/sources.py index 3bd7d2a..7552b88 100644 --- a/backend/app/sources.py +++ b/backend/app/sources.py @@ -23,25 +23,12 @@ from app.core.errors import Problem, not_found, unprocessable from app.core.settings import get_settings from app.mailpack import MailIdentityError, choose_message, identities_match, header_message_id from app.media.storage import sniff +from app.sourcebind import resolve_for_read +from app.sourceport import CAPABILITIES +from app.sourceregistry import SourceModule, get_source, register_source def save_connector(conn, owner_id: UUID, kind: str, name: str, settings: dict, secret: str) -> dict: - if kind == "paperless": - existing = conn.execute( - "SELECT id FROM connectors WHERE owner_id = %s AND kind = 'paperless'", - (owner_id,), - ).fetchone() - if existing: - row = conn.execute( - """ - UPDATE connectors - SET name = %s, settings = %s, secret = %s - WHERE id = %s - RETURNING id, kind, name, settings, created_at - """, - (name, Json(settings), secret, existing["id"]), - ).fetchone() - return _public(row) row = conn.execute( """ INSERT INTO connectors (owner_id, kind, name, settings, secret) @@ -53,6 +40,21 @@ def save_connector(conn, owner_id: UUID, kind: str, name: str, settings: dict, s return _public(row) +def update_connector(conn, owner_id: UUID, connector_id: UUID, name: str, settings: dict, secret: str) -> dict: + """Credential or name change on the same instance. The id does not move.""" + current = _owned(conn, owner_id, connector_id) + row = conn.execute( + """ + UPDATE connectors + SET name = %s, settings = %s, secret = %s + WHERE id = %s AND owner_id = %s + RETURNING id, kind, name, settings, created_at + """, + (name, Json(settings), secret, current["id"], owner_id), + ).fetchone() + return _public(row) + + def list_connectors(conn, owner_id: UUID) -> list[dict]: rows = conn.execute( """ @@ -76,24 +78,31 @@ def delete_connector(conn, owner_id: UUID, connector_id: UUID) -> None: def probe(conn, owner_id: UUID, connector_id: UUID) -> dict: row = _owned(conn, owner_id, connector_id) - if row["kind"] == "paperless": - count = _paperless_count(row["settings"]["base_url"], row["secret"]) - return {"ok": True, "detail": f"Paperless antwortet. {count} Dokumente sichtbar."} - _imap_login(row["settings"], row["secret"]) - return {"ok": True, "detail": "Das Postfach ist erreichbar."} + module = get_source(row["kind"]) + if module is None: + raise unprocessable("Diese Quelle ist nicht registriert.") + return module.probe(row) -def paperless_documents(conn, owner_id: UUID, query: str) -> list[dict]: - row = conn.execute( - """ - SELECT settings, secret FROM connectors - WHERE owner_id = %s AND kind = 'paperless' - ORDER BY created_at DESC LIMIT 1 - """, - (owner_id,), - ).fetchone() - if row is None: - raise unprocessable("Paperless ist noch nicht verbunden. Lege die Quelle unter Quellen an.") +def paperless_documents(conn, owner_id: UUID, query: str, connector_id: UUID | None = None) -> tuple[list[dict], str]: + if connector_id is not None: + row = _owned(conn, owner_id, connector_id) + if row["kind"] != "paperless": + raise unprocessable("Das ist kein Paperless-Zugang.") + else: + rows = conn.execute( + """ + SELECT id, settings, secret FROM connectors + WHERE owner_id = %s AND kind = 'paperless' + ORDER BY name, id + """, + (owner_id,), + ).fetchall() + if not rows: + raise unprocessable("Paperless ist noch nicht verbunden. Lege die Quelle unter Quellen an.") + if len(rows) != 1: + raise unprocessable("Für Paperless ist mehr als ein Zugang vorhanden. Die Suche muss einen Zugang nennen.") + row = rows[0] base = row["settings"]["base_url"].rstrip("/") payload = _paperless_get(base, row["secret"], "/api/documents/", {"query": query, "page_size": "20"}) items = [] @@ -109,7 +118,7 @@ def paperless_documents(conn, owner_id: UUID, query: str) -> list[dict]: "open_url": f"{base}/documents/{doc.get('id')}/", } ) - return items + return items, str(row["id"]) def imap_mailboxes(conn, owner_id: UUID, connector_id: UUID) -> list[dict]: @@ -177,6 +186,7 @@ def _public(row) -> dict: "name": row["name"], "settings": row["settings"], "created_at": row["created_at"].strftime("%Y-%m-%dT%H:%M:%SZ"), + "capabilities": (get_source(row["kind"]).capabilities if get_source(row["kind"]) else None), } @@ -195,19 +205,25 @@ def _paperless_count(base: str, token: str) -> int: return int(payload.get("count") or 0) -def paperless_content(conn, owner_id: UUID, document_id: str) -> tuple[bytes, str, str]: +def paperless_content(conn, owner_id: UUID, document_id: str, connector_id: UUID | None = None) -> tuple[bytes, str, str]: if not document_id.isdigit() or len(document_id) > 12: raise unprocessable("Die Paperless-Nummer ist ungültig.") - row = conn.execute( - """ - SELECT settings, secret FROM connectors - WHERE owner_id = %s AND kind = 'paperless' - ORDER BY created_at DESC LIMIT 1 - """, - (owner_id,), - ).fetchone() - if row is None: - raise unprocessable("Paperless ist für dieses Konto nicht verbunden.") + if connector_id is not None: + row = _owned(conn, owner_id, connector_id) + if row["kind"] != "paperless": + raise unprocessable("Das ist kein Paperless-Zugang.") + else: + rows = conn.execute( + """ + SELECT id, settings, secret FROM connectors + WHERE owner_id = %s AND kind = 'paperless' + ORDER BY name, id + """, + (owner_id,), + ).fetchall() + if len(rows) != 1: + raise unprocessable("Für Paperless ist kein eindeutiger Zugang zugeordnet.") + row = rows[0] return _paperless_bytes(row, document_id) @@ -240,23 +256,28 @@ def read_linked_paperless(conn, actor_id: UUID, element: dict, context: Ctx | No """The stored document. A grantee never uses a connector of their own account.""" detail = (ref or {}).get("detail") or {} external_id = str((ref or {}).get("external_id") or "") - stored = _uuid(detail.get("connector_id")) + stored = _uuid(detail.get("connector_id")) or _uuid((ref or {}).get("connector_id")) stored_owner = _connector_owner(conn, stored) if element["owner_subject_id"] == actor_id or stored_owner == actor_id: - return paperless_content(conn, actor_id, external_id) + if not external_id.isdigit() or len(external_id) > 12: + raise unprocessable("Die Paperless-Nummer ist ungültig.") + result = resolve_for_read(conn, actor_id, "paperless", ref, None) + if result.row is None: + raise unprocessable(result.message) + return _paperless_bytes(result.row, external_id) owner_id = mediated_source_owner(conn, actor_id, element, context) if owner_id is None or not external_id.isdigit() or len(external_id) > 12: raise unprocessable(ORIGINAL_UNAVAILABLE) - row = _mediated_paperless(conn, owner_id, stored, element) - if row is None: + result = resolve_for_read(conn, owner_id, "paperless", ref, None) + if result.row is None: _audit_mediated(conn, actor_id, element, context, "paperless", stored, "unavailable") raise unprocessable(ORIGINAL_UNAVAILABLE) try: - data, media, name = _paperless_bytes(row, external_id) + data, media, name = _paperless_bytes(result.row, external_id) except Problem: - _audit_mediated(conn, actor_id, element, context, "paperless", row["id"], "unavailable") + _audit_mediated(conn, actor_id, element, context, "paperless", result.row["id"], "unavailable") raise unprocessable(ORIGINAL_UNAVAILABLE) from None - _audit_mediated(conn, actor_id, element, context, "paperless", row["id"], "ok") + _audit_mediated(conn, actor_id, element, context, "paperless", result.row["id"], "ok") if external_id and external_id in (name or ""): name = "dokument.pdf" return data, media, name or "dokument.pdf" @@ -267,28 +288,31 @@ def read_linked_mail(conn, actor_id: UUID, element: dict, context: Ctx | None, r detail = (ref or {}).get("detail") or {} if ref is None or ref["source"] != "imap": raise unprocessable("Das ist keine E-Mail.") - connector_id = _uuid(detail.get("connector_id")) + connector_id = _uuid(detail.get("connector_id")) or _uuid(ref["connector_id"] if "connector_id" in ref.keys() else None) mailbox = str(detail.get("mailbox") or "").strip() uid = _mail_uid(detail.get("uid")) external_id = str(ref["external_id"]) stored_owner = _connector_owner(conn, connector_id) if element["owner_subject_id"] == actor_id or stored_owner == actor_id: - if connector_id is None or not mailbox or uid is None: + result = resolve_for_read(conn, actor_id, "imap", ref, None) + if result.row is None: + raise unprocessable(result.message) + if not mailbox or uid is None: raise unprocessable("Für diese E-Mail fehlt die Zuordnung zu Fach und Nachricht.") - return load_imap_original(conn, actor_id, connector_id, mailbox, uid, external_id) + return load_imap_original(conn, actor_id, result.row["id"], mailbox, uid, external_id) owner_id = mediated_source_owner(conn, actor_id, element, context) if owner_id is None or connector_id is None or not mailbox or uid is None: raise unprocessable(ORIGINAL_UNAVAILABLE) - row = _connector_for(conn, connector_id, owner_id, "imap") - if row is None: + result = resolve_for_read(conn, owner_id, "imap", ref, None) + if result.row is None: _audit_mediated(conn, actor_id, element, context, "imap", connector_id, "unavailable") raise unprocessable(ORIGINAL_UNAVAILABLE) try: - raw = load_imap_original(conn, owner_id, connector_id, mailbox, uid, external_id) + raw = load_imap_original(conn, owner_id, result.row["id"], mailbox, uid, external_id) except Problem: - _audit_mediated(conn, actor_id, element, context, "imap", connector_id, "unavailable") + _audit_mediated(conn, actor_id, element, context, "imap", result.row["id"], "unavailable") raise unprocessable(ORIGINAL_UNAVAILABLE) from None - _audit_mediated(conn, actor_id, element, context, "imap", connector_id, "ok") + _audit_mediated(conn, actor_id, element, context, "imap", result.row["id"], "ok") return raw @@ -329,23 +353,6 @@ def _connector_for(conn, connector_id: UUID, owner_id: UUID, kind: str): ).fetchone() -def _mediated_paperless(conn, owner_id: UUID, stored: UUID | None, element: dict): - if stored is not None: - return _connector_for(conn, stored, owner_id, "paperless") - if element["owner_subject_id"] != owner_id: - return None - return conn.execute( - """ - SELECT id, owner_id, kind, settings, secret - FROM connectors - WHERE owner_id = %s AND kind = 'paperless' - ORDER BY created_at DESC - LIMIT 1 - """, - (owner_id,), - ).fetchone() - - def _audit_mediated(conn, actor_id: UUID, element: dict, context: Ctx | None, source: str, connector_id, outcome: str) -> None: audit( conn, @@ -1014,3 +1021,175 @@ def _search_rfc822(client: imaplib.IMAP4, expected_id: str, max_bytes: int) -> l if len(found) > 5: return found return found + + +def _paperless_config(payload: dict) -> tuple[str, dict, str]: + base_url = str(payload.get("base_url") or "").strip() + token = str(payload.get("token") or "").strip() + name = str(payload.get("name") or "").strip() + if not base_url or len(token) < 8: + raise unprocessable("Paperless braucht eine Adresse und einen API-Schlüssel.") + return name, {"base_url": clean_base_url(base_url)}, token + + +def _imap_config(payload: dict) -> tuple[str, dict, str]: + host = str(payload.get("host") or "").strip() + username = str(payload.get("username") or "").strip() + password = str(payload.get("password") or "") + name = str(payload.get("name") or "").strip() + if not host or not username or not password: + raise unprocessable("Ein E-Mail-Konto braucht Server, Benutzername und Passwort.") + if " " in host or len(host) > 200: + raise unprocessable("Der Mailserver ist ungültig.") + port = payload.get("port") or 993 + return name, { + "host": host, + "port": int(port), + "username": username, + "mailbox": str(payload.get("mailbox") or "INBOX").strip() or "INBOX", + "security": payload.get("security") or "ssl", + }, password + + +def _paperless_find(conn, owner_id: UUID, connector_id: UUID | None, query: str, options: dict) -> dict: + del options + items, bound = paperless_documents(conn, owner_id, query, connector_id) + return {"items": items, "connector_id": bound} + + +def _imap_find(conn, owner_id: UUID, connector_id: UUID | None, query: str, options: dict) -> dict: + if connector_id is None: + raise unprocessable("Für dieses Postfach fehlt der Zugang.") + before = options.get("before") + return imap_messages(conn, owner_id, connector_id, query, str(options.get("mailbox") or ""), before) + + +def _export_paperless(conn, actor_id: UUID, external_id: str, detail: dict, assigned: UUID | None, ref): + from app.retrieval import EXPORT_BYTE_LIMIT, FilePayload, RetrievalFailure, failure_from_problem + + del detail + resolved = resolve_for_read(conn, actor_id, "paperless", ref, assigned) + if resolved.row is None: + return RetrievalFailure(resolved.code, resolved.message, resolved.choices) + try: + data, media, name = pull_paperless_original( + resolved.row["settings"]["base_url"].rstrip("/"), + resolved.row["secret"], + str(external_id), + EXPORT_BYTE_LIMIT, + ) + except Problem as exc: + return failure_from_problem(exc) + if len(data) > EXPORT_BYTE_LIMIT: + return RetrievalFailure("too_large", "Die Originaldatei ist für den Export zu groß.") + return FilePayload(name or f"paperless-{external_id}", media, data, "") + + +def _export_imap(conn, actor_id: UUID, external_id: str, detail: dict, assigned: UUID | None, ref): + from app.mailpack import identities_match, parse_mail + from app.retrieval import EXPORT_BYTE_LIMIT, MailPayload, RetrievalFailure, failure_from_problem + + resolved = resolve_for_read(conn, actor_id, "imap", ref, assigned) + if resolved.row is None: + return RetrievalFailure(resolved.code, resolved.message, resolved.choices) + mailbox = str(detail.get("mailbox") or "").strip() + uid = detail.get("uid") + if isinstance(uid, str) and uid.isdigit(): + uid = int(uid) + if not mailbox or isinstance(uid, bool) or not isinstance(uid, int) or uid < 1: + return RetrievalFailure("identity", "Für diese E-Mail fehlt die Zuordnung zu Fach und Nachricht.") + try: + raw = pull_rfc822(resolved.row["settings"], resolved.row["secret"], mailbox, uid, str(external_id), EXPORT_BYTE_LIMIT) + except Problem as exc: + return failure_from_problem(exc) + if len(raw) > EXPORT_BYTE_LIMIT: + return RetrievalFailure( + "too_large", + "Die vollständige Nachricht überschreitet die Exportgrenze. " + "Eine gekürzte Vorschau wird nicht als Original übernommen.", + ) + parsed = parse_mail(raw) + if not identities_match(parsed.message_id, str(external_id)): + return RetrievalFailure("identity", "Die gefundene Nachricht ist nicht die referenzierte E-Mail.") + if parsed.missing: + names = ", ".join(parsed.missing[:5]) + return RetrievalFailure("attachment", f"Eine Anlage der E-Mail ließ sich nicht vollständig lesen: {names}.") + return MailPayload(raw, parsed) + + +def _imap_bytes(conn, actor_id: UUID, element: dict, context: Ctx | None, ref) -> tuple[bytes, str, str]: + raw = read_linked_mail(conn, actor_id, element, context, ref) + return raw, "message/rfc822", "nachricht.eml" + + +class _PaperlessAdapter: + kind = "paperless" + + def capabilities(self) -> dict: + return CAPABILITIES[self.kind] + + def probe(self, row) -> dict: + count = _paperless_count(row["settings"]["base_url"], row["secret"]) + return {"ok": True, "detail": f"Paperless antwortet. {count} Dokumente sichtbar."} + + def search(self, conn, owner_id: UUID, query: str, connector_id: UUID | None): + return paperless_documents(conn, owner_id, query, connector_id) + + def find(self, conn, owner_id: UUID, connector_id: UUID | None, query: str, options: dict) -> dict: + return _paperless_find(conn, owner_id, connector_id, query, options) + + +class _ImapAdapter: + kind = "imap" + + def capabilities(self) -> dict: + return CAPABILITIES[self.kind] + + def probe(self, row) -> dict: + _imap_login(row["settings"], row["secret"]) + return {"ok": True, "detail": "Das Postfach ist erreichbar."} + + def navigate(self, conn, owner_id: UUID, connector_id: UUID) -> list[dict]: + return imap_mailboxes(conn, owner_id, connector_id) + + def search(self, conn, owner_id: UUID, connector_id: UUID, query: str, mailbox: str, before: int | None) -> dict: + return imap_messages(conn, owner_id, connector_id, query, mailbox, before) + + def find(self, conn, owner_id: UUID, connector_id: UUID | None, query: str, options: dict) -> dict: + return _imap_find(conn, owner_id, connector_id, query, options) + + +def _install_sources() -> None: + paperless = _PaperlessAdapter() + imap = _ImapAdapter() + register_source(SourceModule( + kind="paperless", + label="Paperless", + representation="pdf", + capabilities=CAPABILITIES["paperless"], + parse_config=_paperless_config, + probe=paperless.probe, + find=paperless.find, + open_original=read_linked_paperless, + export_original=_export_paperless, + navigate=None, + preview=None, + )) + register_source(SourceModule( + kind="imap", + label="E-Mail", + representation="email", + capabilities=CAPABILITIES["imap"], + parse_config=_imap_config, + probe=imap.probe, + find=imap.find, + open_original=_imap_bytes, + export_original=_export_imap, + navigate=imap.navigate, + preview=lambda conn, owner, connector_id, options: imap_preview( + conn, owner, connector_id, str(options.get("mailbox") or ""), int(options.get("uid") or 0) + ), + )) + + +_install_sources() diff --git a/backend/migrations/20261019T120000Z_source_storage.sql b/backend/migrations/20261019T120000Z_source_storage.sql new file mode 100644 index 0000000..a33b796 --- /dev/null +++ b/backend/migrations/20261019T120000Z_source_storage.sql @@ -0,0 +1,66 @@ +-- Source instance binding and opaque storage generation. +-- Connector ids are not a foreign key: deleting an access must not +-- retarget or remove an existing reference. +-- The legacy root path is bound in the migrator, not in this file. + +CREATE TABLE storage_instances ( + id uuid PRIMARY KEY DEFAULT gen_random_uuid(), + kind text NOT NULL, + generation text NOT NULL, + root_path text, + created_at timestamptz NOT NULL DEFAULT now(), + CONSTRAINT storage_instances_kind CHECK (kind IN ('local')), + CONSTRAINT storage_instances_generation UNIQUE (generation), + CONSTRAINT storage_instances_generation_len CHECK (char_length(generation) BETWEEN 1 AND 80) +); + +ALTER TABLE media_assets + ADD COLUMN storage_instance_id uuid REFERENCES storage_instances (id), + ADD COLUMN storage_generation text, + ADD COLUMN object_key text, + ADD COLUMN content_revision text, + ADD COLUMN protection_profile text NOT NULL DEFAULT 'legacy-plaintext', + ADD COLUMN key_responsibility text NOT NULL DEFAULT 'none', + ADD CONSTRAINT media_assets_protection CHECK ( + protection_profile IN ('legacy-plaintext', 'managed-encrypted', 'client-encrypted') + ), + ADD CONSTRAINT media_assets_key_responsibility CHECK ( + key_responsibility IN ('none', 'operator', 'client') + ); + +ALTER TABLE dispatch_snapshots + ADD COLUMN storage_instance_id uuid REFERENCES storage_instances (id), + ADD COLUMN storage_generation text, + ADD COLUMN object_key text, + ADD COLUMN content_revision text, + ADD COLUMN protection_profile text NOT NULL DEFAULT 'legacy-plaintext', + ADD COLUMN key_responsibility text NOT NULL DEFAULT 'none', + ADD CONSTRAINT dispatch_snapshots_protection CHECK ( + protection_profile IN ('legacy-plaintext', 'managed-encrypted', 'client-encrypted') + ), + ADD CONSTRAINT dispatch_snapshots_key_responsibility CHECK ( + key_responsibility IN ('none', 'operator', 'client') + ); + +UPDATE media_assets +SET storage_generation = 'legacy-local-1', + object_key = id::text, + content_revision = id::text, + protection_profile = 'legacy-plaintext', + key_responsibility = 'none' +WHERE object_key IS NULL; + +UPDATE dispatch_snapshots +SET storage_generation = 'legacy-local-1', + object_key = 'dispatch/' || id::text, + content_revision = id::text, + protection_profile = 'legacy-plaintext', + key_responsibility = 'none' +WHERE object_key IS NULL; + +ALTER TABLE external_references + ADD COLUMN connector_id uuid, + ADD COLUMN resolution text NOT NULL DEFAULT 'unresolved', + ADD CONSTRAINT external_references_resolution CHECK ( + resolution IN ('bound', 'ambiguous', 'unresolved', 'none') + ); diff --git a/backend/migrations/20261019T150000Z_source_registry.sql b/backend/migrations/20261019T150000Z_source_registry.sql new file mode 100644 index 0000000..57f40c9 --- /dev/null +++ b/backend/migrations/20261019T150000Z_source_registry.sql @@ -0,0 +1,5 @@ +-- Connector kinds are validated by the registered source modules. +-- A database checklist must not grow for every additional source. + +ALTER TABLE connectors DROP CONSTRAINT IF EXISTS connectors_kind; +ALTER TABLE external_references DROP CONSTRAINT IF EXISTS external_references_source; diff --git a/backend/tests/sample_source.py b/backend/tests/sample_source.py new file mode 100644 index 0000000..bd725e4 --- /dev/null +++ b/backend/tests/sample_source.py @@ -0,0 +1,182 @@ +"""Third source used only to prove that registration is enough. + +This module is not a product connector and is not imported by the application. +""" + +from __future__ import annotations + +from uuid import UUID + +from app.access.policy import mediated_source_owner +from app.core.errors import not_found, unprocessable +from app.retrieval import FilePayload, RetrievalFailure +from app.sourcebind import resolve_for_read +from app.sourceregistry import SourceModule, register_source, unregister_source +from app.sources import ORIGINAL_UNAVAILABLE, _audit_mediated, _connector_owner + +KIND = "sample" + +CATALOG = { + "alpha": { + "brief": { + "id": "brief", + "title": "Probenbrief", + "text": "Der Probenbrief bleibt lesbar.", + }, + "notiz": { + "id": "notiz", + "title": "Randnotiz", + "text": "Die Randnotiz bleibt in der Quelle.", + }, + } +} + +CAPABILITIES = { + "kind": KIND, + "navigate": False, + "read_original": True, + "read_preview": True, + "read_attachment": False, + "edit_content": False, + "edit_metadata": False, + "search": { + "query": True, + "title": False, + "correspondent": False, + "document_type": False, + "tags": False, + "document_range": False, + "sort": False, + "continuation": False, + }, +} + + +def parse_config(payload: dict) -> tuple[str, dict, str]: + config = payload.get("config") or {} + catalog = str(config.get("catalog") or "").strip() + name = str(payload.get("name") or "").strip() or catalog + if catalog not in CATALOG: + raise unprocessable("Der Katalog dieser Beispielquelle ist unbekannt.") + return name, {"catalog": catalog}, "" + + +def probe(row) -> dict: + items = _items(row) + return {"ok": True, "detail": f"Beispielquelle antwortet. {len(items)} Einträge sichtbar."} + + +def find(conn, owner_id: UUID, connector_id: UUID | None, query: str, options: dict) -> dict: + del options + row = _connector(conn, owner_id, connector_id) + needle = query.casefold() + items = list(_items(row).values()) + if needle: + items = [ + item for item in items + if needle in item["title"].casefold() or needle in item["text"].casefold() + ] + return {"items": items, "connector_id": str(row["id"])} + + +def preview(conn, owner_id: UUID, connector_id: UUID, options: dict) -> dict: + row = _connector(conn, owner_id, connector_id) + item = _items(row).get(str(options.get("item") or "")) + if item is None: + raise unprocessable("Dieser Eintrag ist in der Beispielquelle nicht vorhanden.") + return {"id": item["id"], "title": item["title"], "text": item["text"], "media": "text"} + + +def open_original(conn, actor_id: UUID, element: dict, context, ref) -> tuple[bytes, str, str]: + external_id = str((ref or {}).get("external_id") or "") + stored = ref.get("connector_id") if ref else None + stored_owner = _connector_owner(conn, stored) + if element["owner_subject_id"] == actor_id or stored_owner == actor_id: + result = resolve_for_read(conn, actor_id, KIND, ref, None) + if result.row is None: + raise unprocessable(result.message) + return _bytes(result.row, external_id) + owner_id = mediated_source_owner(conn, actor_id, element, context) + if owner_id is None: + raise unprocessable(ORIGINAL_UNAVAILABLE) + result = resolve_for_read(conn, owner_id, KIND, ref, None) + if result.row is None: + _audit_mediated(conn, actor_id, element, context, KIND, stored, "unavailable") + raise unprocessable(ORIGINAL_UNAVAILABLE) + try: + data, media, name = _bytes(result.row, external_id) + except Exception: + _audit_mediated(conn, actor_id, element, context, KIND, result.row["id"], "unavailable") + raise unprocessable(ORIGINAL_UNAVAILABLE) from None + _audit_mediated(conn, actor_id, element, context, KIND, result.row["id"], "ok") + return data, media, name + + +def export_original(conn, actor_id: UUID, external_id: str, detail: dict, assigned, ref): + del detail + result = resolve_for_read(conn, actor_id, KIND, ref, assigned) + if result.row is None: + return RetrievalFailure(result.code, result.message, result.choices) + try: + data, media, name = _bytes(result.row, str(external_id)) + except Exception as exc: + return RetrievalFailure("missing", str(getattr(exc, "detail", exc))) + return FilePayload(name, media, data, "") + + +def install_sample_source() -> None: + register_source(SourceModule( + kind=KIND, + label="Beispielquelle", + representation="text", + capabilities=CAPABILITIES, + parse_config=parse_config, + probe=probe, + find=find, + open_original=open_original, + export_original=export_original, + navigate=None, + preview=preview, + )) + + +def remove_sample_source() -> None: + unregister_source(KIND) + + +def _connector(conn, owner_id: UUID, connector_id: UUID | None): + if connector_id is not None: + row = conn.execute( + """ + SELECT id, owner_id, kind, name, settings, secret + FROM connectors WHERE id = %s AND owner_id = %s + """, + (connector_id, owner_id), + ).fetchone() + if row is None or row["kind"] != KIND: + raise not_found() + return row + rows = conn.execute( + """ + SELECT id, owner_id, kind, name, settings, secret + FROM connectors + WHERE owner_id = %s AND kind = %s + ORDER BY name, id + """, + (owner_id, KIND), + ).fetchall() + if len(rows) != 1: + raise unprocessable("Für diese Quelle ist kein eindeutiger Zugang zugeordnet.") + return rows[0] + + +def _items(row) -> dict: + catalog = (row["settings"] or {}).get("catalog") + return CATALOG.get(catalog) or {} + + +def _bytes(row, external_id: str) -> tuple[bytes, str, str]: + item = _items(row).get(external_id) + if item is None: + raise unprocessable("Dieser Eintrag ist in der Beispielquelle nicht vorhanden.") + return item["text"].encode("utf-8"), "text/plain", f"{item['id']}.txt" diff --git a/backend/tests/test_connector_basis.py b/backend/tests/test_connector_basis.py new file mode 100644 index 0000000..cadec3d --- /dev/null +++ b/backend/tests/test_connector_basis.py @@ -0,0 +1,333 @@ +"""Section A: source binding and the storage port, with today's behaviour kept.""" + +from __future__ import annotations + +import hashlib +import json +from pathlib import Path +from uuid import uuid4 + +import pytest + +from app.core.errors import Problem +from app.media.port import ( + LEGACY_GENERATION, + LocalAdapter, + MemoryAdapter, + check_object_key, + instance_for_write, + publish, + read_clear_bytes, +) +from app.sourcebind import backfill_source_bindings +from tests.support import ORIGIN, Actor, register + +PDF = b"%PDF-1.4\n1 0 obj<<>>endobj\ntrailer<<>>\n%%EOF\n" + + +def _raw(actor: Actor, path: str): + return actor.client.get( + path, + headers={ + "Origin": ORIGIN, + "X-CSRF-Token": actor.csrf, + "X-Scope-Kind": actor.scope["kind"], + "X-Scope-Id": actor.scope["id"], + }, + ) + + +def _case(actor: Actor) -> dict: + return actor.request("POST", "/api/v1/cases", json={"title": "Bestand"}, status=201) + + +def _paperless(actor: Actor, name: str, token: str) -> str: + row = actor.request( + "POST", + "/api/v1/connectors", + json={"kind": "paperless", "name": name, "base_url": "https://paper.example.test", "token": token}, + status=201, + ) + return row["id"] + + +def _link(actor: Actor, case_id: str, connector_id: str | None, external_id: str, title: str) -> str: + body = { + "title": title, + "source": "paperless", + "external_id": external_id, + "context": {"kind": "case", "id": case_id}, + } + if connector_id: + body["detail"] = {"connector_id": connector_id} + created = actor.request("POST", "/api/v1/external-refs", json=body, status=201) + return created["id"] + + +def test_storage_adapters_roundtrip_and_reject_escape(tmp_path): + payload = b"opaque-bytes" + key = str(uuid4()) + revision = "rev-1" + for adapter in (LocalAdapter(tmp_path), MemoryAdapter()): + publish(adapter, key, payload) + assert adapter.open(key) == payload + assert adapter.describe(key)["byte_size"] == len(payload) + assert adapter.open(key) == payload + assert revision == "rev-1" + memory = MemoryAdapter() + memory.fail_put = True + with pytest.raises(Problem) as failed: + publish(memory, str(uuid4()), payload) + assert failed.value.code == "storage_unavailable" + assert memory._items == {} + with pytest.raises(Problem): + check_object_key("../secret") + with pytest.raises(Problem): + check_object_key("/etc/passwd") + with pytest.raises(Problem): + LocalAdapter(tmp_path).open("dispatch/../../" + str(uuid4())) + + +def test_changed_root_does_not_retarget_legacy(db, database): + legacy = db.execute( + "SELECT id, root_path FROM storage_instances WHERE generation = %s", + (LEGACY_GENERATION,), + ).fetchone() + key = str(uuid4()) + original = b"%PDF-legacy-root" + publish(LocalAdapter(legacy["root_path"]), key, original) + other = Path(database.media_root).parent / f"other-root-{uuid4().hex}" + other.mkdir() + moved = instance_for_write(db, str(other)) + assert moved["id"] != legacy["id"] + assert moved["generation"] != LEGACY_GENERATION + publish(LocalAdapter(moved["root_path"]), key, b"%PDF-other-root") + seen = read_clear_bytes( + db, + instance_id=legacy["id"], + generation=LEGACY_GENERATION, + object_key=key, + media_root=str(other), + protection_profile="legacy-plaintext", + expected_sha256=None, + ) + assert seen == original + db.rollback() + + +def test_existing_file_keeps_id_bytes_and_revision(client, db): + register(db, "ada-file@example.test", "Ada File") + ada = Actor(client, "ada-file@example.test", "Ada File") + ada.login() + case = _case(ada) + upload = ada.request( + "POST", + "/api/v1/files", + data={"title": "Scan", "context_kind": "case", "context_id": case["id"]}, + files={"upload": ("scan.pdf", PDF, "application/pdf")}, + status=201, + ) + stored = db.execute( + """ + SELECT a.id, a.object_key, a.content_revision, a.storage_generation, a.protection_profile, + s.root_path + FROM media_assets a + JOIN storage_instances s ON s.id = a.storage_instance_id + WHERE a.element_id = %s + """, + (upload["id"],), + ).fetchone() + assert stored["protection_profile"] == "legacy-plaintext" + assert stored["object_key"] == str(stored["id"]) + assert Path(stored["root_path"]) == Path(client.app.state.settings.media_root).resolve() + assert stored["storage_generation"] + first = stored["content_revision"] + opened = _raw(ada, f"/api/v1/files/{upload['id']}/content") + assert opened.status_code == 200 + assert opened.content == PDF + again = db.execute( + "SELECT content_revision FROM media_assets WHERE element_id = %s", + (upload["id"],), + ).fetchone() + assert again["content_revision"] == first + refused = ada.client.patch( + f"/api/v1/notes/{upload['id']}", + json={"expected_version": 1, "document": {"version": 1, "blocks": [{"type": "paragraph", "text": "nein"}]}}, + headers={ + "Origin": ORIGIN, + "X-CSRF-Token": ada.csrf, + "X-Scope-Kind": ada.scope["kind"], + "X-Scope-Id": ada.scope["id"], + }, + ) + assert refused.status_code == 422 + assert refused.json()["code"] == "unsupported" + + +def test_two_paperless_instances_stay_bound_when_order_changes(client, db, monkeypatch): + register(db, "ada-two@example.test", "Ada Two") + ada = Actor(client, "ada-two@example.test", "Ada Two") + ada.login() + case = _case(ada) + older = _paperless(ada, "Zweitens", "token-older") + newer = _paperless(ada, "Erstens", "token-newer") + assert older != newer + + def fake_bytes(row, document_id): + return f"%PDF-{row['secret']}-{document_id}\n".encode(), "application/pdf", "dokument.pdf" + + monkeypatch.setattr("app.sources._paperless_bytes", fake_bytes) + left = _link(ada, case["id"], older, "15", "Altbestand") + right = _link(ada, case["id"], newer, "15", "Zweiter Bestand") + db.execute("UPDATE connectors SET created_at = now() - interval '2 days' WHERE id = %s", (newer,)) + db.execute("UPDATE connectors SET created_at = now() WHERE id = %s", (older,)) + db.commit() + assert _raw(ada, f"/api/v1/external-refs/{left}/content").content.startswith(b"%PDF-token-older-15") + assert _raw(ada, f"/api/v1/external-refs/{right}/content").content.startswith(b"%PDF-token-newer-15") + calls = [] + + def fake_get(*args, **kwargs): + calls.append(args) + return {"results": [{"id": 15, "title": "Treffer", "created": "2024-01-02"}]} + + monkeypatch.setattr("app.sources._paperless_get", fake_get) + headers = { + "Origin": ORIGIN, + "X-CSRF-Token": ada.csrf, + "X-Scope-Kind": ada.scope["kind"], + "X-Scope-Id": ada.scope["id"], + } + refused = ada.client.get("/api/v1/sources/paperless/documents", params={"q": "Treffer"}, headers=headers) + assert refused.status_code == 422 + assert calls == [] + found = ada.request( + "GET", + "/api/v1/sources/paperless/documents", + params={"q": "Treffer", "connector_id": older}, + ) + assert found["items"][0]["title"] == "Treffer" + assert found["connector_id"] == older + assert found["capabilities"]["search"]["correspondent"] is False + assert "correspondent" in found["unsupported"] + filtered = ada.client.get( + "/api/v1/sources/paperless/documents", + params={"q": "Treffer", "connector_id": older, "correspondent": "Haus"}, + headers=headers, + ) + assert filtered.status_code == 422 + assert filtered.json()["code"] == "unsupported" + assert "Haus" not in json.dumps(filtered.json()) + + +def test_ambiguous_legacy_stays_until_assignment(client, db, monkeypatch): + register(db, "ada-old@example.test", "Ada Old") + ada = Actor(client, "ada-old@example.test", "Ada Old") + ada.login() + case = _case(ada) + loose = _link(ada, case["id"], None, "15", "Ohne Instanz") + _paperless(ada, "Alpha", "token-alpha") + second = _paperless(ada, "Beta", "token-beta") + db.execute( + """ + UPDATE external_references + SET connector_id = NULL, resolution = 'unresolved', detail = '{}'::jsonb + WHERE element_id = %s + """, + (loose,), + ) + backfill_source_bindings(db) + state = db.execute( + "SELECT connector_id, resolution FROM external_references WHERE element_id = %s", + (loose,), + ).fetchone() + db.commit() + assert state["resolution"] == "ambiguous" + assert state["connector_id"] is None + blocked = _raw(ada, f"/api/v1/external-refs/{loose}/content") + assert blocked.status_code == 422 + assert "eindeutiger Zugang" in blocked.json()["detail"] + + def fake_bytes(row, document_id): + del document_id + return f"%PDF-{row['secret']}\n".encode(), "application/pdf", "dokument.pdf" + + monkeypatch.setattr("app.sources._paperless_bytes", fake_bytes) + ada.request( + "POST", + f"/api/v1/external-refs/{loose}/assignment", + json={"connector_id": second}, + ) + _paperless(ada, "Gamma", "token-gamma") + assert _raw(ada, f"/api/v1/external-refs/{loose}/content").content.startswith(b"%PDF-token-beta") + + +def test_locked_profile_serves_metadata_not_cleartext(client, db): + register(db, "ada-lock@example.test", "Ada Lock") + ada = Actor(client, "ada-lock@example.test", "Ada Lock") + ada.login() + case = _case(ada) + upload = ada.request( + "POST", + "/api/v1/files", + data={"title": "Geschuetzt", "context_kind": "case", "context_id": case["id"]}, + files={"upload": ("geheim.pdf", PDF, "application/pdf")}, + status=201, + ) + dummy = b"cipher-dummy-not-clear" + asset = db.execute( + "SELECT id, object_key, storage_instance_id FROM media_assets WHERE element_id = %s", + (upload["id"],), + ).fetchone() + root = db.execute( + "SELECT root_path FROM storage_instances WHERE id = %s", + (asset["storage_instance_id"],), + ).fetchone()["root_path"] + path = Path(root) / asset["object_key"] + path.write_bytes(dummy) + db.execute( + """ + UPDATE media_assets + SET protection_profile = 'client-encrypted', + key_responsibility = 'client', + sha256 = %s + WHERE element_id = %s + """, + (hashlib.sha256(dummy).hexdigest(), upload["id"]), + ) + db.commit() + detail = ada.request("GET", f"/api/v1/cases/{case['id']}") + rendered = json.dumps(detail) + assert "client-encrypted" in rendered + assert "Geschuetzt" in rendered + assert dummy.decode() not in rendered + opened = _raw(ada, f"/api/v1/files/{upload['id']}/content") + assert opened.status_code == 422 + assert opened.json()["code"] == "unsupported" + assert path.read_bytes() == dummy + + +def test_credential_update_keeps_the_instance(client, db): + register(db, "ada-key@example.test", "Ada Key") + ada = Actor(client, "ada-key@example.test", "Ada Key") + ada.login() + first = _paperless(ada, "Archiv", "token-first-1") + second = _paperless(ada, "Anderes Archiv", "token-second-2") + renewed = ada.request( + "PATCH", + f"/api/v1/connectors/{first}", + json={"kind": "paperless", "name": "Archiv", "base_url": "https://paper.example.test", "token": "token-renewed"}, + ) + assert renewed["id"] == first + secrets = { + str(row["id"]): row["secret"] + for row in db.execute("SELECT id, secret FROM connectors").fetchall() + } + assert secrets[first] == "token-renewed" + assert secrets[second] == "token-second-2" + caps = ada.request("GET", "/api/v1/sources/capabilities") + assert caps["editors"]["note"] is True + assert caps["editors"]["markdown_file"] is False + assert caps["protection_profiles"]["client-encrypted"] == "locked" + paperless = next(item for item in caps["sources"] if item["kind"] == "paperless") + assert paperless["search"]["query"] is True + assert paperless["edit_content"] is False diff --git a/backend/tests/test_correspondence.py b/backend/tests/test_correspondence.py index d364681..7e61a4c 100644 --- a/backend/tests/test_correspondence.py +++ b/backend/tests/test_correspondence.py @@ -230,7 +230,7 @@ def test_dispatch_keeps_the_secured_stand_and_distinct_mail_parts(client, db, mo "Fachlicher Zusatz: die Frist bleibt der 1. Juni.", [("rechnung.pdf", PDF_A), ("lage.pdf", PDF_B), ("konto.pdf", PDF_C), ("lage.pdf", PDF_D)], ) - monkeypatch.setattr("app.retrieval.pull_rfc822", lambda *args, **kwargs: raw) + monkeypatch.setattr("app.sources.pull_rfc822", lambda *args, **kwargs: raw) ada = Actor(client, "ada-versand@example.test", "Ada Versand") register(db, ada.email, ada.name) ada.login() diff --git a/backend/tests/test_export.py b/backend/tests/test_export.py index b695687..4f50ce7 100644 --- a/backend/tests/test_export.py +++ b/backend/tests/test_export.py @@ -141,9 +141,9 @@ def test_handover_package_follows_the_confirmed_selection(client, db, monkeypatc "Der vollständige Brieftext bleibt erhalten.", [("lage.pdf", PDF_A), ("lage.pdf", PDF_B)], ) - monkeypatch.setattr("app.retrieval.pull_rfc822", lambda *args, **kwargs: raw) + monkeypatch.setattr("app.sources.pull_rfc822", lambda *args, **kwargs: raw) monkeypatch.setattr( - "app.retrieval.pull_paperless_original", + "app.sources.pull_paperless_original", lambda *args, **kwargs: (PDF_B, "application/pdf", "archiv.pdf"), ) ada = Actor(client, "ada-export@example.test", "Ada Export") @@ -491,7 +491,7 @@ def test_export_names_gaps_and_hides_unreadable_counterparts(client, db, monkeyp calls.append(args) return _eml("", "darf nicht ersatzweise kommen", []) - monkeypatch.setattr("app.retrieval.pull_rfc822", pull) + monkeypatch.setattr("app.sources.pull_rfc822", pull) context = {"kind": "case", "id": case["id"]} tree = ada.request( "GET", @@ -547,7 +547,7 @@ def test_export_names_gaps_and_hides_unreadable_counterparts(client, db, monkeyp assert {item["name"] for item in pending["issues"][0]["choices"]} == {"Neu", "Weiter"} monkeypatch.setattr("app.retrieval.EXPORT_BYTE_LIMIT", 40) huge = _eml("", "GEKÜRZT-VERBOTEN " * 20, []) - monkeypatch.setattr("app.retrieval.pull_rfc822", lambda *args, **kwargs: huge) + monkeypatch.setattr("app.sources.pull_rfc822", lambda *args, **kwargs: huge) assigned = ada.request( "POST", f"/api/v1/matters/{matter['id']}/export/review", @@ -557,7 +557,7 @@ def test_export_names_gaps_and_hides_unreadable_counterparts(client, db, monkeyp assert "GEKÜRZT-VERBOTEN" not in json.dumps(assigned) wrong = _eml("", "FALSCHE-NACHRICHT", []) monkeypatch.setattr("app.retrieval.EXPORT_BYTE_LIMIT", 80 * 1024 * 1024) - monkeypatch.setattr("app.retrieval.pull_rfc822", lambda *args, **kwargs: wrong) + monkeypatch.setattr("app.sources.pull_rfc822", lambda *args, **kwargs: wrong) identity = ada.request( "POST", f"/api/v1/matters/{matter['id']}/export/review", @@ -609,7 +609,7 @@ def test_nested_chapter_export_keeps_path_and_complete_mail(client, db, monkeypa "Die Antwort bleibt vollständig.", [("lage.pdf", PDF_A), ("konto.pdf", PDF_B)], ) - monkeypatch.setattr("app.retrieval.pull_rfc822", lambda *args, **kwargs: raw) + monkeypatch.setattr("app.sources.pull_rfc822", lambda *args, **kwargs: raw) ada = Actor(client, "ada-nested-export@example.test", "Ada Verschachtelt") register(db, ada.email, ada.name) ada.login() @@ -844,7 +844,7 @@ def test_chapter_entries_share_one_numbering_sequence(client, db, monkeypatch): files={"upload": ("drittes.pdf", PDF_C, "application/pdf")}, status=201, ) - monkeypatch.setattr("app.retrieval.pull_rfc822", lambda *args, **kwargs: raw) + monkeypatch.setattr("app.sources.pull_rfc822", lambda *args, **kwargs: raw) tree = ada.request("GET", f"/api/v1/matters/{matter['id']}/export-tree")["tree"] exportable = {"binding", "annotation", "attachment", "dispatch_item", "evidence"} selected = [node["id"] for node in _walk(tree) if node["exportable"] and node["kind"] in exportable] diff --git a/backend/tests/test_sample_source.py b/backend/tests/test_sample_source.py new file mode 100644 index 0000000..428f6e4 --- /dev/null +++ b/backend/tests/test_sample_source.py @@ -0,0 +1,225 @@ +"""A third source appears only by registering its module.""" + +from __future__ import annotations + +import io +import subprocess +import zipfile +from pathlib import Path + +import pytest + +from tests.sample_source import install_sample_source, remove_sample_source +from tests.support import ORIGIN, Actor, document, register + +ROOT = Path(__file__).resolve().parents[2] +TEXT = "Der Probenbrief bleibt lesbar." + + +@pytest.fixture +def sample_source(): + install_sample_source() + try: + yield + finally: + remove_sample_source() + + +def test_registered_sample_source_links_reads_and_exports(client, db, sample_source): + del sample_source + ada = Actor(client, "ada-sample@example.test", "Ada Probe") + ben = Actor(client, "ben-sample@example.test", "Ben Probe") + register(db, ada.email, ada.name) + register(db, ben.email, ben.name) + ada.login() + refused = ada.request( + "POST", + "/api/v1/connectors", + json={"kind": "missing", "name": "Unbekannt"}, + status=422, + ) + assert refused["code"] == "unprocessable" + ada.request( + "POST", + "/api/v1/connectors", + json={"kind": "sample", "name": "Ohne Katalog", "config": {"catalog": "kein-katalog"}}, + status=422, + ) + connector_id = ada.request( + "POST", + "/api/v1/connectors", + json={"kind": "sample", "name": "Katalog Alpha", "config": {"catalog": "alpha"}}, + status=201, + )["id"] + probed = ada.request("POST", f"/api/v1/connectors/{connector_id}/probe") + assert probed["ok"] is True + assert "2 Einträge" in probed["detail"] + blocked = ada.request( + "GET", + "/api/v1/sources/sample/search", + params={"q": "Probe", "correspondent": "geheim-wert"}, + status=422, + ) + assert blocked["code"] == "unsupported" + assert "geheim-wert" not in blocked["detail"] + ada.request("GET", "/api/v1/sources/sample/navigate", params={"connector_id": connector_id}, status=422) + found = ada.request("GET", "/api/v1/sources/sample/search", params={"q": "Proben", "connector_id": connector_id}) + assert [item["id"] for item in found["items"]] == ["brief"] + preview = ada.request( + "GET", + "/api/v1/sources/sample/preview", + params={"connector_id": connector_id, "item": "brief"}, + ) + assert preview["text"] == TEXT + matter = ada.request("POST", "/api/v1/matters", json={"title": "Probenvorgang"}, status=201) + linked = ada.request( + "POST", + "/api/v1/external-refs", + json={ + "title": "Probenbrief", + "source": "sample", + "external_id": "brief", + "context": {"kind": "matter", "id": matter["id"]}, + "detail": {"connector_id": connector_id}, + }, + status=201, + ) + opened = _raw(ada, f"/api/v1/external-refs/{linked['id']}/content?context_kind=matter&context_id={matter['id']}") + assert opened.status_code == 200 + assert opened.content == TEXT.encode("utf-8") + assert opened.headers["content-type"].startswith("text/plain") + detail = ada.request("GET", f"/api/v1/matters/{matter['id']}") + element = next(item["element"] for item in detail["bindings"] if item["element"]["id"] == linked["id"]) + assert element["preview"]["media"] == "text" + written = ada.request( + "PATCH", + f"/api/v1/notes/{linked['id']}", + json={ + "expected_version": element["version"], + "document": document("Das darf nicht geschrieben werden."), + "context": {"kind": "matter", "id": matter["id"]}, + }, + status=422, + ) + assert written["code"] == "unsupported" + tree = ada.request("GET", f"/api/v1/matters/{matter['id']}/export-tree")["tree"] + selected = [node["id"] for node in _walk(tree) if node["kind"] == "binding" and node.get("exportable")] + body = {"context": {"kind": "matter", "id": matter["id"]}, "selected": selected} + review = ada.request("POST", f"/api/v1/matters/{matter['id']}/export/review", json=body) + assert review["ready"] is True, review + package = _post_zip(ada, matter["id"], body) + assert package.status_code == 200, package.text + archive = zipfile.ZipFile(io.BytesIO(package.content)) + assert any(archive.read(name) == TEXT.encode("utf-8") for name in archive.namelist()) + + ben.login() + ben.request( + "GET", + "/api/v1/sources/sample/search", + params={"connector_id": connector_id, "q": "Proben"}, + status=404, + ) + hidden = _raw(ben, f"/api/v1/external-refs/{linked['id']}/content?context_kind=matter&context_id={matter['id']}") + assert hidden.status_code == 404 + ada.login() + ada.request( + "POST", + f"/api/v1/matters/{matter['id']}/grants", + json={"email": ben.email, "can_read": True, "can_edit": False, "can_share": False, "use_owner_sources": False}, + status=201, + ) + ben.login() + denied = _raw(ben, f"/api/v1/external-refs/{linked['id']}/content?context_kind=matter&context_id={matter['id']}") + assert denied.status_code == 422 + assert denied.json()["detail"] == "Das Original ist über die Freigabe nicht abrufbar." + ada.login() + grant_id = next(item["id"] for item in ada.request("GET", f"/api/v1/matters/{matter['id']}")["grants"]) + ada.request("DELETE", f"/api/v1/grants/{grant_id}", status=204) + ada.request( + "POST", + f"/api/v1/matters/{matter['id']}/grants", + json={"email": ben.email, "can_read": True, "can_edit": False, "can_share": False, "use_owner_sources": True}, + status=201, + ) + ben.login() + shared = _raw(ben, f"/api/v1/external-refs/{linked['id']}/content?context_kind=matter&context_id={matter['id']}") + assert shared.status_code == 200 + assert shared.content == TEXT.encode("utf-8") + shown = ben.request("GET", f"/api/v1/matters/{matter['id']}") + visible = next(item["element"] for item in shown["bindings"] if item["element"]["id"] == linked["id"]) + assert "connector_id" not in (visible["external"].get("detail") or {}) + ada.login() + grant_id = next(item["id"] for item in ada.request("GET", f"/api/v1/matters/{matter['id']}")["grants"]) + ada.request("DELETE", f"/api/v1/grants/{grant_id}", status=204) + ben.login() + revoked = _raw(ben, f"/api/v1/external-refs/{linked['id']}/content?context_kind=matter&context_id={matter['id']}") + assert revoked.status_code == 404 + + +def test_sample_registration_does_not_edit_generic_modules(): + forbidden = [ + "backend/app/api/schemas.py", + "backend/app/exporting.py", + "backend/app/present.py", + "frontend/src/pages/Cases.jsx", + "frontend/src/pages/Matters.jsx", + "frontend/src/pages/ReadingPane.jsx", + "frontend/src/pages/ExportPackage.jsx", + "frontend/src/App.jsx", + "frontend/src/pages/Sources.jsx", + ] + for relative in forbidden: + text = (ROOT / relative).read_text(encoding="utf-8") + assert '"sample"' not in text and "'sample'" not in text, relative + completed = subprocess.run( + [ + "node", + "--input-type=module", + "-e", + ( + "import { installSampleSource, removeSampleSource } from './src/sources/sample-source.js';" + "import { sourceModules } from './src/sources/registry-core.js';" + "installSampleSource();" + "if (!sourceModules().some((item) => item.kind === 'sample' && item.representation === 'text')) process.exit(2);" + "removeSampleSource();" + "if (sourceModules().some((item) => item.kind === 'sample')) process.exit(3);" + ), + ], + cwd=ROOT / "frontend", + check=False, + capture_output=True, + text=True, + ) + assert completed.returncode == 0, completed.stderr + + +def _raw(actor: Actor, path: str): + return actor.client.get( + path, + headers={ + "Origin": ORIGIN, + "X-CSRF-Token": actor.csrf, + "X-Scope-Kind": actor.scope["kind"], + "X-Scope-Id": actor.scope["id"], + }, + ) + + +def _post_zip(actor: Actor, matter_id: str, body: dict): + return actor.client.post( + f"/api/v1/matters/{matter_id}/export", + json=body, + headers={ + "Origin": ORIGIN, + "X-CSRF-Token": actor.csrf, + "Content-Type": "application/json", + "X-Scope-Kind": actor.scope["kind"], + "X-Scope-Id": actor.scope["id"], + }, + ) + + +def _walk(node): + yield node + for child in node.get("children") or []: + yield from _walk(child) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 61c30f1..a6eef2b 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -42,6 +42,22 @@ Die Pflicht-Suite ist der eigene Workflow `test.yml`, nach dem Vorbild von Kansh --- +## Bekannte Betriebsgrenzen (Stand Code-Review 18.10.2026) + +Diese Punkte sind im [Code-Review](review/06_BEFUNDE.md) beschrieben. Sie stehen hier, damit sie beim Betrieb sichtbar bleiben. + +| Thema | Ist-Stand | Folge für den Betrieb | Review | +|---|---|---|---| +| Betreiberkonto | Auf einer leeren Datenbank legt die öffentliche Anmeldeseite das Betreiberkonto an. Keine MFA | Nach jedem Neuaufsetzen einer Umgebung sofort selbst anmelden, bevor die Adresse öffentlich erreichbar ist. Alternativ vorher `docker compose exec backend python -m app.cli create-account --email … --name … --password …` ausführen | R-04 | +| Sicherung | Es gibt kein Backup von Datenbank und Volume `tsumugu-media`/`dev-tsumugu-media` und keinen geprobten Restore | Laut technischer Spezifikation 8.2 nur synthetische Daten in Produktion, bis Paket P7 umgesetzt ist | R-21 | +| Release | `deploy-prod.yml` baut bei jedem Push auf `main` neu. Tests laufen nur auf `develop` nach dem Dev-Deploy | Vor dem Merge nach `main` den grünen `test.yml`-Lauf zum selben Stand prüfen | R-21, R-27 | +| Datenbankzugang | Das Backend migriert beim Start mit dem Owner-Zugang. Die Runtime-Rolle `tsumugu_runtime` erhält dasselbe Passwort wie `DB_USER` | Ein Wechsel von `DB_PASSWORD` ändert beim nächsten Start beide Rollen | R-09 | +| Quellen-Geheimnisse | Paperless-Token und IMAP-Passwörter stehen unverschlüsselt in der Tabelle `connectors` | Datenbank-Dumps wie Zugangsdaten schützen | R-05 | +| Sessions | 14 Tage gültig, keine Leerlaufabmeldung, kein Passwortwechsel in der Anwendung | Passwort nur über die Datenbank oder ein neues Konto änderbar | R-08 | +| Testläufe | `test.yml` startet je Push zweimal auf derselben Datenbank `tsumugu_test` | Ein roter Lauf kann vom parallelen Lauf verursacht sein; Ergebnis des Einzellaufs prüfen | R-27 | + +--- + ## Erreichbarkeit von außen TLS endet wie bei Kanshō auf dem Synology-NAS `192.168.2.63` (DSM Reverse Proxy), nicht auf dem Pi. diff --git a/docs/ENTWICKLUNG_UND_TESTS.md b/docs/ENTWICKLUNG_UND_TESTS.md new file mode 100644 index 0000000..456cb5a --- /dev/null +++ b/docs/ENTWICKLUNG_UND_TESTS.md @@ -0,0 +1,97 @@ +# Entwicklung und Tests – lokal + +**Stand:** 18.10.2026. Erstellt im Code-Review aus Code und Workflows. Deployment auf dem Raspberry Pi: [DEPLOYMENT.md](DEPLOYMENT.md). + +## Voraussetzungen + +- Python 3.12, Node.js (das Build-Image nutzt Node 22; lokal funktioniert auch Node 24) +- PostgreSQL 16. Der Benutzer aus `DB_USER` muss Tabellen anlegen und die Rolle `tsumugu_runtime` erstellen dürfen (`CREATEROLE`). Im Compose-Stack ist das der Superuser des Postgres-Containers. + +## Konfiguration + +Das Backend liest ausschließlich die Prozessumgebung. Eine `.env`-Datei wird nicht automatisch geladen. + +| Variable | Pflicht | Default | Bedeutung | +|---|---|---|---| +| `TSUMUGU_ENV` | ja | – | `development` oder `production`; ein anderer Wert verhindert den Start | +| `DB_NAME`, `DB_USER`, `DB_PASSWORD` | ja | – | Owner-Zugang; Migration und Runtime-Rolle | +| `DB_HOST`, `DB_PORT` | nein | `localhost`, `5432` | – | +| `DB_RUNTIME_USER` | nein | `tsumugu_runtime` | Rolle des laufenden Pools; erhält dasselbe Passwort wie `DB_USER` | +| `ALLOWED_ORIGINS` | nein | `http://localhost:5173,http://localhost:3094` | erlaubte `Origin`-Werte für schreibende Aufrufe | +| `APP_URL` | nein | `http://localhost:5173` | öffentliche Adresse | +| `MEDIA_ROOT` | nein | `data/media` | Ablage eigener Dateien | +| `PAPERLESS_MEDIA_ROOT` | nein | leer | lesender Paperless-Ablageordner als Rückfallweg | +| `SEED_DEMO` | nein | `false` | wirkt nur in Development mit Datenbank `*_test`; in Production verhindert `true` den Start | +| `SESSION_TTL_HOURS` | nein | `336` | Laufzeit einer Session | +| `UPLOAD_MAX_BYTES` | nein | `20971520` | Upload-Grenze (Nginx erlaubt 21 MiB) | + +## Backend starten + +```bash +cd backend +python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -r requirements-dev.txt +export TSUMUGU_ENV=development DB_NAME=tsumugu_local DB_USER=postgres DB_PASSWORD=… +python -m app.cli migrate +python -m app.cli create-account --email ich@example.test --name "Ich" --password "mindestens-zehn" +uvicorn main:app --reload --port 8000 +``` + +Das erste per CLI angelegte Konto wird Betreiber. Alternativ zeigt die Anmeldeseite auf einer leeren Datenbank das Formular „Betreiberkonto“ (siehe Review R-04). `python -m app.entrypoint` entspricht dem Containerstart: Migration, Entfernen von Fixture-Konten, danach Uvicorn auf Port 8000. + +## Frontend starten + +```bash +cd frontend +npm ci +npm run dev # http://localhost:5173, Proxy für /api und /health auf 127.0.0.1:8000 +``` + +Ein anderes Backend erreicht der Proxy über `VITE_API_PROXY`. Über HTTP heißt das Session-Cookie `jinkendo-session`. Die Kennzeichnung „Entwicklungsumgebung“ erscheint im Vite-Server automatisch, im Image über `VITE_TSUMUGU_ENV=development`. + +Produktionsbuild: `npm run build`. Für Development-Images ergänzt `mark-environment.mjs` danach Titel, Manifest und Farbe. + +## Tests + +### Backend + +Die Suite läuft gegen echtes PostgreSQL. Sie verweigert jede Datenbank, deren Name nicht auf `_test` endet, sowie `tsumugu`, `tsumugu_dev`, `postgres` und die Templates. Vor und nach jedem Test werden alle Tabellen geleert. + +```bash +cd backend +createdb tsumugu_local_test +export DB_NAME=tsumugu_local_test DB_USER=… DB_PASSWORD=… DB_HOST=localhost +python -m pytest tests -ra --basetemp=.pytest-tmp +``` + +- `conftest.py` setzt `TSUMUGU_ENV=development`, `ALLOWED_ORIGINS=http://testserver`, `SEED_DEMO=false` und ein temporäres `MEDIA_ROOT`. +- Unter Windows kann das Standard-Temp-Verzeichnis von pytest gesperrt sein. `--basetemp=.pytest-tmp` umgeht das; der Ordner gehört nicht ins Repository. +- Zwei Läufe dürfen nicht gleichzeitig dieselbe Testdatenbank verwenden. +- Paperless und IMAP werden in den Tests durch lokale Attrappen ersetzt. Es entsteht kein Netzzugriff. + +### Frontend + +```bash +cd frontend +node --test src/list-meta.test.mjs +``` + +Weitere Frontend-Tests gibt es nicht. Ein `npm test`-Skript ist nicht registriert. + +### In CI + +`.gitea/workflows/test.yml` erzeugt auf der Dev-Postgres die Datenbank `tsumugu_test` neu und führt die Suite im Backend-Image aus. Danach folgen ein lesender Health-Smoke der laufenden Dev-App und ein Frontend-Build. Bekannte Schwächen: [Review 07](review/07_TESTS_UND_CI.md). + +## Neue Migration + +1. Datei `backend/migrations/YYYYMMDDTHHMMSSZ_kurzname.sql` anlegen, Zeitstempel in UTC, lexikalisch nach der letzten. +2. Keine eigene Transaktionssteuerung in der Datei; der Runner kapselt jede Datei. +3. Angewandte Dateien nie ändern: Die Prüfsumme im Ledger verhindert danach den Start. +4. [DATENMODELL_IST.md](architecture/DATENMODELL_IST.md) nachziehen. + +## Neue Route + +1. Route in `api/routes.py`, `api/sources.py` oder `api/export.py` mit `Depends(get_principal)` und `Depends(get_conn)` anlegen. +2. Rechte über die Funktionen in `access/policy.py` prüfen, nie nur im Frontend. +3. Änderung samt `audit(...)` in derselben Verbindung. +4. [API_REFERENZ.md](architecture/API_REFERENZ.md) nachziehen. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7b64ac1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,93 @@ +# Tsumugu – Dokumentation + +Übersicht aller Dokumente im Repository. Verbindlichkeit laut [AGENTS.md](../AGENTS.md): Fachlich führend ist die Produktspezifikation, technisch der Entwurf in `architecture/`. Vorläufige Rechte- und Löschregeln stehen in den MVP-Annahmen. + +## Einstieg + +| Ich will … | Dokument | +|---|---| +| wissen, was Tsumugu ist und wo es läuft | [../README.md](../README.md) | +| lokal entwickeln und testen | [ENTWICKLUNG_UND_TESTS.md](ENTWICKLUNG_UND_TESTS.md) | +| deployen und Ports nachschlagen | [DEPLOYMENT.md](DEPLOYMENT.md) | +| den fachlichen Stand und offene Entscheidungen kennen | [product/TSUMUGU_PRODUCT_SPEC.md](product/TSUMUGU_PRODUCT_SPEC.md) | +| den aktuellen Qualitätsstand und offene Mängel sehen | [review/README.md](review/README.md) | + +## Produkt (`product/`) + +| Dokument | Rolle | Stand | +|---|---|---| +| [TSUMUGU_PRODUCT_SPEC.md](product/TSUMUGU_PRODUCT_SPEC.md) | führende Fachspezifikation, alle bestätigten Entscheidungen F-01 bis F-08, S-01 | 0.37 | +| [TSUMUGU_UX_MVP_ERGAENZUNG.md](product/TSUMUGU_UX_MVP_ERGAENZUNG.md) | Bedienung, Orientierung, Abnahmekriterien UX-01 bis UX-21 | 0.8 | +| [TSUMUGU_KOMPAKTE_INHALTSLISTE_AUFTRAG.md](product/TSUMUGU_KOMPAKTE_INHALTSLISTE_AUFTRAG.md) | Auftrag F-06f, hat Vorrang vor älteren Darstellungsvorgaben | 1.0 | +| [TSUMUGU_KOMMUNIKATIONSRICHTUNG_AUFTRAG.md](product/TSUMUGU_KOMMUNIKATIONSRICHTUNG_AUFTRAG.md) | Auftrag F-06e | 1.2 | +| [TSUMUGU_SYMBOLS_LOGOFRAME_AUFTRAG.md](product/TSUMUGU_SYMBOLS_LOGOFRAME_AUFTRAG.md) | Auftrag F-06c, Typ-Symbole und Logo-Rahmen | 17.10.2026 | +| [TSUMUGU_ENSO_ANIMATION_AUFTRAG.md](product/TSUMUGU_ENSO_ANIMATION_AUFTRAG.md) | Einbindung der Ensō-Animation | 17.10.2026 | +| [TSUMUGU_EXPORT_NAECHSTE_LIEFERUNG_2026-10-17.md](product/TSUMUGU_EXPORT_NAECHSTE_LIEFERUNG_2026-10-17.md) | Auftrag F-07a–c, Übergabepaket | 17.10.2026 | +| [TSUMUGU_EXPORT_PRUEFBERICHT_2026-10-17.md](product/TSUMUGU_EXPORT_PRUEFBERICHT_2026-10-17.md) | Prüfbericht der Exportlieferung | 17.10.2026 | +| [TSUMUGU_UNTERKAPITEL_AUFTRAG_2026-10-17.md](product/TSUMUGU_UNTERKAPITEL_AUFTRAG_2026-10-17.md) | Auftrag F-08a | 17.10.2026 | +| [TSUMUGU_UNTERKAPITEL_PRUEFBERICHT_2026-10-17.md](product/TSUMUGU_UNTERKAPITEL_PRUEFBERICHT_2026-10-17.md) | Prüfbericht Unterkapitel | 17.10.2026 | +| [TSUMUGU_CONNECTOREN_BEFUND_2026-10-17.md](product/TSUMUGU_CONNECTOREN_BEFUND_2026-10-17.md) | Bestandsanalyse Paperless/IMAP, Umbauschätzung | 17.10.2026 | +| [TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md](product/TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md) | begrenzter Umsetzungsauftrag, Abschnitt A beauftragt, Abschnitt B der nächste Ausbau | 19.10.2026 | +| [TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md](product/TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md) | Abschlusskriterien der Kapselung; Vorrang vor einem teilweise integrierten Zwischenstand | 19.10.2026 | +| [TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md](product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md) | Kriterium, Nachweis und Ergebnis der Kapselung | 19.10.2026 | +| [TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md](product/TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md) | früherer Zwischenstand von Abschnitt A vor den Abschlusskriterien | 19.10.2026 | +| [TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md](product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md) | Einstieg für die fachliche Weiterplanung | 17.10.2026 | +| [TECHNICAL_SPEC_HANDOFF.md](product/TECHNICAL_SPEC_HANDOFF.md) | historischer Auftrag zur technischen Spezifikation | 16.10.2026 | +| [Tsumugu_Product_Recovery_Baseline_v0.1.md](product/Tsumugu_Product_Recovery_Baseline_v0.1.md) | unveränderte historische Ausgangsbasis | 0.1 | + +## Architektur (`architecture/`) + +| Dokument | Rolle | Stand | +|---|---|---| +| [TSUMUGU_TECHNICAL_SPEC.md](architecture/TSUMUGU_TECHNICAL_SPEC.md) | technischer Entwurf (Soll): Pakete, Datenmodell, Rechte, API, Nachweise | 0.3 mit Ergänzungen | +| [API_REFERENZ.md](architecture/API_REFERENZ.md) | tatsächlich registrierte Endpunkte (Ist) | 19.10.2026 | +| [DATENMODELL_IST.md](architecture/DATENMODELL_IST.md) | Schema nach allen Migrationen (Ist) | 19.10.2026 | +| [RECHTEMODELL_IST.md](architecture/RECHTEMODELL_IST.md) | implementierte Rechteauswertung (Ist) | 19.10.2026 | +| [ARCHITECTURE_DISCOVERY.md](architecture/ARCHITECTURE_DISCOVERY.md) | Ist-Aufnahme der Jinkendo-Familie vor Tsumugu, keine Beschlüsse | 15.10.2026 | +| [TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md](architecture/TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md) | Umsetzungsvorschlag Source- und Storage-Vertrag | 19.10.2026 | +| [Tsumugu_Connector_Suite_Architektur_v0.2.md](architecture/Tsumugu_Connector_Suite_Architektur_v0.2.md) | Zielarchitektur der Connector Suite, keine pauschale Beschlussübernahme | 19.10.2026 | +| [TSUMUGU_STORAGE_SCHLUESSEL_PRUEFAUFTRAG_2026-10-19.md](architecture/TSUMUGU_STORAGE_SCHLUESSEL_PRUEFAUFTRAG_2026-10-19.md) | vorbereiteter Prüfauftrag an die Architektur-Session, nicht versandt | 19.10.2026 | + +## Design (`design/`) + +| Dokument | Rolle | Stand | +|---|---|---| +| [LIEFERUNG_2026-10-17.md](design/LIEFERUNG_2026-10-17.md) | Lieferbericht der Arbeitsfläche, bewusste Abweichungen | 17.10.2026, historisch | + +Das ausgewählte Designkonzept und die Assetpakete liegen außerhalb des Repositorys unter `C:/Dev/jinkendo-app-design-2026-10-17/`. Die übernommenen Assets stehen in `frontend/public/brand/` und `frontend/public/ui/`. + +## Referenz (`reference/`) + +Familienweite Vorgaben der Jinkendo-Anwendungen. Verbindliche Verträge und anpassbare Defaults sind dort jeweils getrennt. + +| Dokument | Geltung für Tsumugu | +|---|---| +| [A – Technische Referenzarchitektur v0.3](reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md) | verbindlich | +| [B – Implementation Blueprint Foundation v0.3](reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md) | verbindlich | +| [C – Technische Entscheidungen v0.3](reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md) | verbindlich | +| [Auth, Session & Scope](reference/Jinkendo_Auth_Session_Scope_Blueprint.md) | verbindlich | +| [Medien, Dateien & sicheres Rendering](reference/Jinkendo_Media_Files_Safe_Rendering_Blueprint.md) | verbindlich | +| [Release, Betrieb & Recovery](reference/Jinkendo_Release_Betrieb_Recovery_Blueprint.md) | verbindlich vor echtem Betrieb (Paket P7) | +| [KI-Gateway](reference/Jinkendo_AI_Gateway_Provider_Privacy_Blueprint.md), [Prompt/Workflow](reference/Jinkendo_Prompt_Placeholder_Workflow_Blueprint.md), [Entitlements](reference/Jinkendo_Entitlements_Usage_Quotas_Blueprint.md) | nur als Grenze; keine MVP-Pflicht | + +Die Links innerhalb der Referenzdokumente zeigen auf die ursprünglichen Ablageorte unter `C:/Dev/…` und funktionieren im Repository nicht. + +## Betrieb und Regeln + +| Dokument | Rolle | +|---|---| +| [DEPLOYMENT.md](DEPLOYMENT.md) | Umgebungen, Ports, Workflows, Proxy, bekannte Betriebsgrenzen | +| [MVP_ANNAHMEN.md](MVP_ANNAHMEN.md) | vorläufige Rechte- und Löschregeln, Cookie-Abweichung in Development | +| [ENTWICKLUNG_UND_TESTS.md](ENTWICKLUNG_UND_TESTS.md) | Konfiguration, lokaler Start, Tests, neue Migration und Route | + +## Review (`review/`) + +| Dokument | Inhalt | +|---|---| +| [review/README.md](review/README.md) | Code-Review vom 18.10.2026: Gesamtbewertung, Anforderungsabdeckung, Befunde, Maßnahmenplan | + +## Pflege + +- Neue Fachentscheidung → Produktspezifikation (Abschnitt 5 und Fortschreibung). +- Neue Route, Migration oder Rechteregel → die passende Ist-Datei in `architecture/` im selben Commit. +- Neuer Auftrag oder Prüfbericht → `product/`, hier in der Tabelle eintragen. diff --git a/docs/architecture/API_REFERENZ.md b/docs/architecture/API_REFERENZ.md index 73db9d2..d348417 100644 --- a/docs/architecture/API_REFERENZ.md +++ b/docs/architecture/API_REFERENZ.md @@ -1,6 +1,6 @@ # Tsumugu – API-Referenz (Ist-Stand) -**Stand:** 18.10.2026. Erstellt im Code-Review aus `backend/app/main.py`, `api/routes.py`, `api/sources.py`, `api/export.py` und `api/correspondence.py`. +**Stand:** 18.10.2026, ergänzt am 19.10.2026 um Quelleninstanzen, Fähigkeiten und Zuordnung. Erstellt im Code-Review aus `backend/app/main.py`, `api/routes.py`, `api/sources.py`, `api/export.py` und `api/correspondence.py`. Diese Datei beschreibt die tatsächlich registrierten Endpunkte. Die Sollfassung steht in der [technischen Spezifikation, Abschnitt 6.2](TSUMUGU_TECHNICAL_SPEC.md). OpenAPI ist in allen Umgebungen abgeschaltet (`docs_url=None`, `openapi_url=None`). Diese Datei ist deshalb die einzige Übersicht. Sie wird bei jeder Routenänderung mitgepflegt. @@ -153,20 +153,26 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R** | Methode | Pfad | Zweck | |---|---|---| -| GET | `/api/v1/connectors` | eigene Zugänge ohne Secret | -| POST | `/api/v1/connectors` | Paperless (überschreibt den vorhandenen) oder IMAP anlegen | -| DELETE | `/api/v1/connectors/{id}` | Zugang löschen | +| GET | `/api/v1/connectors` | eigene Zugänge ohne Secret, mit Fähigkeiten der registrierten Quelle | +| POST | `/api/v1/connectors` | neue Instanz einer registrierten Quelle; unbekannte Art wird abgewiesen; ersetzt keinen vorhandenen Zugang | +| PATCH | `/api/v1/connectors/{id}` | Name, Einstellungen und Zugangsdaten derselben Instanz | +| DELETE | `/api/v1/connectors/{id}` | Zugang löschen; bestehende Referenzen bleiben und werden nicht umgehängt | | POST | `/api/v1/connectors/{id}/probe` | Zugang prüfen | -| GET | `/api/v1/sources/paperless/documents?q=` | Paperless-Suche (letzter eigener Zugang) | +| GET | `/api/v1/sources/capabilities` | erklärte Such-, Lese- und Editorfähigkeiten; nicht Vorhandenes bleibt falsch | +| GET | `/api/v1/sources/{kind}/search` | Suche der registrierten Quelle im erklärten Umfang; unbekannte Art und nicht erklärte Filter antworten `422` | +| GET | `/api/v1/sources/{kind}/navigate?connector_id=` | Fachnavigation, wenn die Quelle sie erklärt | +| GET | `/api/v1/sources/{kind}/preview` | Vorschau vor dem Übernehmen, wenn die Quelle sie erklärt | +| GET | `/api/v1/sources/paperless/documents?q=&connector_id=` | Kompatibilitätshülle der Paperless-Suche; delegiert an dieselbe Suche | | GET | `/api/v1/sources/imap/mailboxes?connector_id=` | IMAP-Fächer | -| GET | `/api/v1/sources/imap/messages?connector_id=&mailbox=&q=&before=` | Nachrichtenliste, 30 je Seite | +| GET | `/api/v1/sources/imap/messages?connector_id=&mailbox=&q=&before=` | Nachrichtenliste, 30 je Seite, Fortsetzung über `before` | | GET | `/api/v1/sources/imap/message?connector_id=&mailbox=&uid=` | Vorschau vor dem Übernehmen | -| GET | `/api/v1/external-refs/{id}/content` | Paperless-Datei zum Ansehen (`inline`) | +| GET | `/api/v1/external-refs/{id}/content` | Original der gebundenen Instanz über das registrierte Modul (`inline`) | | GET | `/api/v1/external-refs/{id}/mail` | vollständige E-Mail als JSON, Identität per Message-ID geprüft | | GET | `/api/v1/external-refs/{id}/mail/original` | EML | | GET | `/api/v1/external-refs/{id}/mail/attachments/{index}` | Anlage (`inline`, siehe Review R-03) | +| POST | `/api/v1/external-refs/{id}/assignment` | Owner ordnet eine mehrdeutige oder ungebundene Referenz bewusst einer eigenen Instanz zu | -Quelleninhalte werden mit den Zugängen der **anfragenden** Person geladen (Review R-10). +Quelleninhalte einer eigenen Referenz laufen über die gebundene Instanz. Eine freigegebene Referenz mit `use_owner_sources` nutzt den gebundenen Zugang des Owners. Zugangsdaten und die übrigen Treffer dieses Zugangs werden nicht ausgeliefert. Eine Suche ohne `connector_id` wählt bei mehreren eigenen Instanzen nicht den zuletzt angelegten Zugang (Review R-10). ## Übergabepaket diff --git a/docs/architecture/DATENMODELL_IST.md b/docs/architecture/DATENMODELL_IST.md index 31ec7f8..aac32d0 100644 --- a/docs/architecture/DATENMODELL_IST.md +++ b/docs/architecture/DATENMODELL_IST.md @@ -1,6 +1,6 @@ # Tsumugu – Datenmodell (Ist-Stand) -**Stand:** 18.10.2026, nach den Migrationen in `backend/migrations/` (letzte: `20261018T090000Z_correspondence.sql`). Erstellt im Code-Review. +**Stand:** 19.10.2026, nach den Migrationen in `backend/migrations/` (letzte: `20261019T150000Z_source_registry.sql`). Entstanden im Code-Review vom 18.10.2026 und für die Connector-Grundlage nachgezogen. Die Arten `connectors.kind` und `external_references.source` prüft die Registrierung. Die früheren Prüflisten in der Datenbank sind entfernt. `url` bleibt eine Referenz ohne Connector. Die Sollfassung steht in der [technischen Spezifikation, Abschnitt 4](TSUMUGU_TECHNICAL_SPEC.md). Diese Datei beschreibt, was tatsächlich angelegt ist. Bei jeder neuen Migration nachziehen. @@ -42,17 +42,17 @@ Die Sollfassung steht in der [technischen Spezifikation, Abschnitt 4](TSUMUGU_TE | `elements` | Anker¹, `title`, `kind` (`note`/`file`/`external_ref`), `summary` (≤ 400) | gemeinsamer Inhaltsträger | | `note_bodies` | `element_id`, `document_json`, `version` | ein Text je Notiz; Format `{version: 1, blocks: [...]}` mit Absatz- oder einem Markdown-Block | | `correspondence_dates` | `element_id`, `document_on`, `sent_on`, `received_on` | getrennte Datumssachen; Erfassung = `elements.created_at` | -| `external_references` | `element_id`, `source` (`paperless`/`url`/`imap`), `external_id`, `detail` (JSON) | IMAP: Message-ID als `external_id`, `connector_id`, `mailbox`, `uid` im JSON; kein Eindeutigkeitsindex | +| `external_references` | `element_id`, `source` (`paperless`/`url`/`imap`), `external_id`, `detail` (JSON), `connector_id`, `resolution` (`bound`/`ambiguous`/`unresolved`/`none`) | IMAP: Message-ID als `external_id`, `mailbox` und `uid` im JSON. `connector_id` ist keine Fremdschlüsselbeziehung: ein gelöschter Zugang lässt die Referenz stehen und hängt sie nicht um. Mehrdeutiger Bestand bleibt `ambiguous`, bis der Owner zuordnet | | `bindings` | `element_id`, `context_kind` (`case`/`matter`), `context_id`, `chapter_id`, `position`, `communication_direction` (`in`/`out`/`local`/NULL), `direction_explicit`, `list_fold` (`attachment`/`evidence`/NULL) | unique (`element_id`, `context_kind`, `context_id`); kein FK auf den Kontext (polymorph). `list_fold` gilt nur für dieses Vorkommen | | `attachment_uses` | Behälter, `host_element_id`, `attachment_element_id`, `position`, optionales `label` | flache Zuordnung je Hauptschriftstück und Behälter; keine Dateikopie; kein Selbstbezug | | `dispatches` | Behälter, `host_element_id`, `channel`, `sent_on`, `counterpart`, `completeness`, `provenance`, `version` | mehrere Versände je Schreiben; `sent_on` leer bleibt undatiert | | `dispatch_items` | Rolle `host`/`attachment`, Titel, Dokumentdatum, `source_state` `snapshot`/`gap`, Hash, optionales Notiz-JSON | Manifest der übermittelten Fassung; Lücke ersetzt nicht die Arbeitsdatei | -| `dispatch_snapshots` | Bytes, Hash, Dateiname | Datei unter `MEDIA_ROOT/dispatch/`; fällt in den Löschpfad des Elements | +| `dispatch_snapshots` | Bytes, Hash, Dateiname, Speicherinstanz, Generation, Objektkennung, Inhaltsrevision, Schutzprofil | Datei unter der gebundenen Wurzel als `dispatch/`; fällt in den Löschpfad des Elements. Ein späterer Wurzelwechsel liest die alte Generation weiter am gebundenen Ort | | `dispatch_evidence` | `element_id`, Rolle `email`/`submission`/`delivery`/`other`, Identitätsprüfung, `comparisons` | manuelle Zuordnung; Einlieferung ist keine Zustellung | | `dispatch_corrections` | Zeitpunkt, Zusammenfassung | Berichtigung ohne stilles Umschreiben der Bytes | | `context_annotations` | `binding_id`, `body` (≤ 4 000), `author_subject_id` | Kaskade mit der Einbindung | | `element_references` | PK (`element_id`, `refers_to_element_id`) | kein Selbstbezug; Zyklusprüfung in der Anwendung; FK-Kaskade greift nur bei physischem Löschen, Elemente werden aber nur markiert (Review R-13) | -| `media_assets` | `id`, `element_id` (unique), Owner, Heimatraum, `original_filename`, `content_type`, `byte_size`, `sha256`, `revision`, `status` (`active`/`purging`/`purged`) | Bytes unter `MEDIA_ROOT/` | +| `media_assets` | `id`, `element_id` (unique), Owner, Heimatraum, `original_filename`, `content_type`, `byte_size`, `sha256`, `revision`, `status` (`active`/`purging`/`purged`), Speicherinstanz, Generation, `object_key`, `content_revision`, `protection_profile`, `key_responsibility` | Bytes über den lokalen Storage-Port. Bestandsgeneration `legacy-local-1`, Schlüsselzuständigkeit `none`, Profil `legacy-plaintext`. Der Bytehash bleibt intern | | `media_operations` | `element_id`, `asset_id`, `phase`, `status` | derzeit reines Protokoll | ## Rechte @@ -75,7 +75,8 @@ Die Sollfassung steht in der [technischen Spezifikation, Abschnitt 4](TSUMUGU_TE | Tabelle | Wesentliche Spalten | Regeln | |---|---|---| -| `connectors` | `owner_id`, `kind` (`paperless`/`imap`), `name`, `settings` (JSON), `secret` (Klartext, Review R-05) | Paperless höchstens einmal je Konto (in der Anwendung) | +| `connectors` | `owner_id`, `kind` (`paperless`/`imap`), `name`, `settings` (JSON), `secret` (Klartext, Review R-05) | Mehrere Instanzen je Art sind möglich. Ein POST legt eine neue Instanz an. Ein PATCH ändert Zugangsdaten derselben Id. Das Secret bleibt im Adapter und ist keine SaaS-Schlüsselhaltung | +| `storage_instances` | `kind` (`local`), `generation` (eindeutig), `root_path` | Die Bestandsgeneration `legacy-local-1` wird einmal an die Wurzel gebunden. Ein späterer Wurzelwechsel erzeugt eine neue Generation und hängt alte Referenzen nicht um | | `domain_events` | `actor_subject_id`, `scope_id`, `action`, `resource_kind`, `resource_id`, `context_kind/id`, `occurred_on`, `occurred_at`, `result` | append-only; Grundlage von Chronologie und fachlichem Verlauf | ## Nicht angelegt (bewusst) diff --git a/docs/architecture/RECHTEMODELL_IST.md b/docs/architecture/RECHTEMODELL_IST.md new file mode 100644 index 0000000..4316f09 --- /dev/null +++ b/docs/architecture/RECHTEMODELL_IST.md @@ -0,0 +1,100 @@ +# Tsumugu – Rechteauswertung (Ist-Stand) + +**Stand:** 18.10.2026, Commit `f21c64a`, ergänzt am 19.10.2026 um die Quellenauflösung. Erstellt im Code-Review aus `backend/app/access/policy.py`, `api/deps.py` und `ops.py`. + +Fachlich gelten die bestätigten Entscheidungen der [Produktspezifikation](../product/TSUMUGU_PRODUCT_SPEC.md) (F-01a–f, S-01b–d) und die vorläufigen [MVP-Annahmen](../MVP_ANNAHMEN.md). Den Sollentwurf beschreibt die [technische Spezifikation, Abschnitt 4.5 und 5](TSUMUGU_TECHNICAL_SPEC.md). Diese Datei beschreibt, wie der Code entscheidet. + +## 1. Vor jeder Fachroute + +1. **Session** (`deps._session_row`): Cookie-Hash muss zu einer nicht widerrufenen, nicht abgelaufenen Session eines aktiven Kontos gehören, sonst 401. Bei unsicheren Methoden muss `X-CSRF-Token` gleich dem Session-Token sein, sonst 403. +2. **Origin** (Middleware in `main.py`): unsichere Methoden unter `/api/` nur mit `Origin` aus `ALLOWED_ORIGINS`. +3. **Datenraum** (`deps.get_principal`): `X-Scope-Kind` und `X-Scope-Id` müssen vorhanden sein und dem in der Session bestätigten Raum entsprechen. Persönlicher Raum nur der eigene, gemeinsamer Raum nur bei aktiver Mitgliedschaft. Sonst 403. + +Der Datenraum bestimmt, **wo neue Objekte entstehen**. Er ist nicht der Rechtepfad. Objekte anderer Räume bleiben über Grants und Einbindungen erreichbar. + +## 2. Rechte und Antwortcodes + +Ein Ergebnis `Rights(read, edit, share, delete)` entsteht je Objekt und Handlungskontext. `_require` übersetzt: + +- `read` fehlt → **404** (das Objekt existiert für diese Person nicht) +- `read` vorhanden, verlangte Fähigkeit fehlt → **403** + +Ausnahmen (`access_grants.is_exception`) **entfernen** Fähigkeiten im genannten Kontext. Sie gelten für alle Personen (`grantee_subject_id IS NULL`), auch für den Owner. Nur der Owner des Objekts setzt sie (`PUT /exceptions`). + +## 3. Auswertung je Objektart + +### Akte (`case_rights`) + +| Fall | Basis | +|---|---| +| Unterakte mit `inherit_parent` | Rechte der Elternakte | +| Owner | alle Rechte | +| sonst | direkter Grant `resource_kind='case'` | + +Danach Abzug von Akten-Ausnahmen ohne Kontext (im Code vorgesehen, über die API nicht setzbar). + +### Vorgang (`matter_rights`) + +| Handlungskontext | Basis | Bedingung | +|---|---|---| +| keiner | Owner = alle Rechte, sonst direkter Grant | – | +| Akte C | Rechte der Akte C | Vorgang ist C zugeordnet, oder sein Elternvorgang ist C zugeordnet (dann Elternrechte in C) | +| Vorgang P | direkte Rechte an P | Vorgang ist Teilvorgang von P | + +Danach Abzug der Vorgangsausnahme genau in diesem Kontext. Ein Querverweis erzeugt keine Rechte. + +### Element (`element_rights`) + +| Handlungskontext | Basis | Bedingung | +|---|---|---| +| keiner | Owner = alle Rechte, sonst direkter Grant | – | +| Akte C | Rechte der Akte C | Element ist direkt in C eingebunden **oder** in einem Vorgang, der C erreicht. Im zweiten Fall darf kein `case_link_blocks`-Eintrag bestehen | +| Vorgang M | direkte Rechte an M | Element ist in M oder in einem Teilvorgang von M eingebunden | + +Danach Abzug der Elementausnahme in diesem Kontext. + +**Grenze:** Eine Ausnahme am **Vorgang** im Aktenkontext wird für Elemente dieses Vorgangs nicht abgezogen (Review R-07). + +### Aufgabe und Frist (`task_rights`, `deadline_rights`) + +| Fall | Basis | +|---|---| +| zugewiesene Person, ohne Kontext | Lesen; Aufgabe zusätzlich `edit`, falls ein Grant es gibt. Status ändern über `can_change_status` | +| ohne Kontext | Owner = alle Rechte, sonst direkter Grant | +| Kontext = eigener Vorgang | direkte Rechte am Vorgang | +| Kontext = Akte | Rechte des Vorgangs in dieser Akte | +| Kontext = Elternvorgang | nur Aufgaben; bei Fristen fehlt dieser Zweig (Review R-15) | + +Danach Abzug der jeweiligen Ausnahme. + +## 4. Schreibende Aktionen + +| Aktion | Verlangte Rechte | +|---|---| +| Inhalt in Behälter anlegen | `edit` am Zielbehälter im Kontext (`require_container_edit`) | +| Gemeinsamen Notiztext ändern | `edit` am Element im Kontext | +| In weiteren Kontext einbinden | `share` am Element im Quellkontext und `edit` am Ziel | +| Vorgang einer Akte zuordnen | `share` am Vorgang und `edit` an der Akte. Inhalte, die die Person nicht freigeben darf, landen in `case_link_blocks` | +| Zuordnung lösen | `edit` an der Akte oder `share` am Vorgang | +| Querverweis | `edit` am Quellvorgang, `read` am Ziel in einem eigenen Kontext | +| Grant erteilen | Owner oder `share`; `can_edit` nur mit eigenem `edit`, `can_share` nur mit eigenem `share` | +| Grant entziehen | Owner der Ressource oder `share` | +| Einbindung lösen | `edit` am Element im Kontext (Kontextzugehörigkeit unscharf geprüft, Review R-02) | +| Element überall löschen | nur Owner des Elements | +| Akte oder Vorgang löschen | `edit` (Review R-01: laut Rollentabelle nur Owner) | +| Reihenfolge, Kapitel, Ordnungsart | `edit` am Behälter im Kontext; nur sichtbare Einbindungen; verborgene behalten ihre Position | +| Aufgabe zuweisen | Owner oder `share`; legt ein Lese-Grant für die zugewiesene Person an | +| Export | je ausgewähltem Inhalt `read` und `share` im Kontext | + +## 5. Sichtbarkeit in Listen und Antworten + +- Listen (`list_cases`, `list_matters`) filtern grob im SQL und prüfen danach jedes Objekt einzeln. +- Einbindungen, Anmerkungen, Bezüge, Zuordnungen, Querverweise, Teilvorgänge und Elternnamen erscheinen nur, wenn die Person sie im jeweiligen Kontext lesen darf. Verborgenes wird weder benannt noch gezählt (`visible_bindings_for_element`, `matter_title_if_readable`). +- Die Chronologie zeigt nur Ereignisse, deren Ressource im Seitenkontext lesbar ist (`_event_title`). +- Breadcrumbs nennen nur lesbare Stationen. Bei mehreren lesbaren Aktenzuordnungen ohne gewählten Kontext erscheint keine Hauptakte. +- Betreiber- und Verwalterrolle verleihen kein Leserecht auf persönliche Inhalte. +- Ein Quellabruf prüft zuerst das Leserecht im Kontext. Danach wird nur der an der Referenz gebundene Zugang des Owners verwendet. Eine Suche ohne `connector_id` nimmt bei mehreren eigenen Instanzen nicht die zuletzt angelegte. Ein Empfänger erhält weder Zugangsdaten noch die übrigen Treffer des Owners. Ein Entzug gilt beim nächsten Abruf, weil jedes Lesen die Rechte erneut prüft. + +## 6. Bekannte Abweichungen + +Siehe [Review-Befunde](../review/06_BEFUNDE.md): R-01 (Behälter löschen), R-02 (Detach/Anmerkung), R-07 (Vorgangsausnahme), R-11 (Übersicht/Suche), R-12 (Teilvorgangstiefe), R-15 (Fristen im Elternkontext). diff --git a/docs/architecture/TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md b/docs/architecture/TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md new file mode 100644 index 0000000..72a4296 --- /dev/null +++ b/docs/architecture/TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md @@ -0,0 +1,133 @@ +# Tsumugu – Connector- und Storage-Vertrag + +**Version:** 0.1 · **Stand:** 19.10.2026 +**Status:** Technischer Umsetzungsvorschlag mit Migrationsplan; hier wurde keine Anwendung geändert. Der begleitende Cursor-Auftrag wird erst durch seine Übergabe zur Umsetzung erteilt. +**Ziel:** Kleine produktlokale Grundlage für Paperless, IMAP und die bestehende eigene Dateiablage. Bestehende Fachfunktionen und Daten bleiben erhalten. + +## 1. Verbindliche Grundlage und Liefergrenze + +Fachlich führen die aktuelle Produktspezifikation und die jüngsten Nutzerentscheidungen. Die Connector Suite v0.2 vom 19.10.2026 ist die Grundlage für die Connector-Zielarchitektur. Ihre Vorschläge und offenen Punkte werden nicht pauschal zu bestätigten Beschlüssen. Architekturverträge aus `C:/Dev/tsumugu/docs/reference` gelten; konkrete Dateinamen und Vertragsbezeichnungen unten sind lokale Umsetzungsvorschläge. + +Bestätigt sind: vollständiges Self-Hosting und spätere SaaS-Nutzung; Quellen als regelhafter Ort externer Originale; Fähigkeiten je Quelle/Ressource; gemeinsame UI mit möglichen Spezialansichten; getrennte Freigaben für Speicherung und Verarbeitung; optional vollständig deaktivierbare dauerhafte Cloud-Inhaltsspeicherung. SaaS-Nutzer müssen ihre Entschlüsselungsschlüssel auf eigenen Geräten beziehungsweise ihrer lokalen Runtime halten können. Diese Option ist Zielanforderung, noch kein nachgewiesenes Produktmerkmal. + +**Primäres Nutzerziel:** Tsumugu wird aktuell vorwiegend privat genutzt und kontinuierlich erweitert. Der erste Schnitt legt tragfähige Grundlagen und vermeidet später großflächige Änderungen an Datenidentitäten, Berechtigungspfaden und Modulgrenzen. Funktionale Vollständigkeit der späteren SaaS-Plattform ist keine Voraussetzung. Daraus folgt keine Garantie, dass neue Anforderungen ohne jede Anpassung bleiben; Änderungen sollen überwiegend in den zuständigen Adaptern und Komponenten möglich sein. + +**Erste Lieferung – Grundlagen:** Bestehende Paperless-/IMAP-Zugänge gemeinsam hinter Source-Verträge bringen, eigene Dateien und Versandfassungen über einen kleinen Storage-Vertrag anbinden und eine gemeinsame Frontend-Zugriffsschicht mit registrierten Darstellungs-/Quellmodulen einführen. Heutige Picker, Leser und Notizbearbeitung bleiben nutzbar. Keine vollständige Neugestaltung aller Dialoge als Fertigkriterium; gemeinsame Zustands-/Auswahlverträge dort einführen, wo dadurch bestehende Quellverzweigungen aus Fachseiten entfernt werden. + +**Nächster Funktionsausbau:** Der Quellenbrowser wird auf den gemeinsamen Bausteinen vervollständigt und die Paperless-Suche gemäß Abschnitt 6 deutlich erweitert. Neue Text-/Markdown-Dateieditoren folgen anschließend auf denselben Verträgen. Diese Fähigkeiten bleiben eingeplant und werden nicht allein für eine scheinbar kleine Basis gestrichen; sie sind separat lieferbar. + +**Spätere Lieferungen:** lokale Remote-Runtime, produktive kundenseitige Schlüsselhaltung, automatische lokale EML-Sicherung, dynamische Quellsammlungen, Dateisystem-/NAS-Source, Banking und KI. Text-/MD-Dateibearbeitung wird im Vertragsmodell berücksichtigt; die erste Lieferung implementiert vorhandene Notizbearbeitung und sichere Anzeige unterstützter Dateien. Neue MD-Dateischreibfunktionen benötigen anschließend einen konkret beauftragten Schnitt. + +## 2. Geprüfter Ausgangspunkt + +Gezielter statischer Abgleich am 19.10.2026, keine ausgeführten Anwendungstests oder Live-Quellenzugriffe: + +| Bestand | Verwendung und erforderliche Anpassung | +|---|---| +| `backend/app/sources.py`, `api/sources.py` | Vorhandene Paperless-/IMAP-Protokollarbeit wiederverwenden. Quelle und Operation sind heute an mehreren Stellen fest verzweigt. | +| `backend/app/retrieval.py`, `mailpack.py` | Vollständigen Originalabruf, EML-Parsing, Identitätsprüfung und Fehlerfälle in die gemeinsame Lesestrecke überführen. | +| `frontend/src/pages/Sources.jsx` | Zwei Picker und Quellenformulare auf gemeinsame Hülle mit quellenspezifischen Ergänzungen umstellen. | +| `ReadingPane.jsx`, `content.jsx`, `markdown.jsx` | Leser nach Darstellungsart anbinden; vorhandenen Markdown-Notizeditor weiterverwenden. | +| `media/storage.py`, `ops.create_file`, `api/routes.py` | Browserupload kopiert PDF/Fotos in die eigene Ablage. Das Ursprungsverzeichnis wird danach nicht mehr benötigt. Ablage erfolgt derzeit über `MEDIA_ROOT`, im Compose-Betrieb `/data/media`. | +| `correspondence.py`, `dispatch_snapshots` | Anlagen, Versandereignisse und gespeicherte Fassungen erhalten. Direkte Dateioperationen ebenfalls an Storage anbinden. | +| `access.policy`, `use_owner_sources` | Kontextrechte und ausdrücklichen Owner-vermittelten Abruf verknüpfter Inhalte erhalten. Keine Erweiterung auf Browsen des übrigen Owner-Quellenbestands. | + +Die heute konfigurierbare lokale Serverablage ist noch keine kundenseitige Remote-Ablage in einem SaaS-Modell. Anwendungseigene Dateiverschlüsselung ist im gelesenen Speicherpfad nicht implementiert; darunterliegende Laufwerksverschlüsselung wurde nicht geprüft. Frühere Prüfberichte belegen nur ihren jeweiligen Stand und werden nicht als aktueller Testlauf ausgegeben. + +## 3. Verantwortlichkeiten + +```text +Quellenbrowser / Ressourcenleser / Editor / Export + -> Tsumugu-Anwendungsdienst: Identität, Kontext, Objekt- und Quellrechte, DataPolicy + -> Source-Port -> Paperless-Adapter oder IMAP-Adapter + -> Content-Zugriff -> geschützter Storage-Port -> lokaler Ablageadapter + -> Fachrepository: bestehende Elemente, Einbindungen, Aufgaben, Versandstände +``` + +Die erste Adapterausführung bleibt im bestehenden Backend. Aufrufe verwenden einen expliziten Operationskontext und wohldefinierte Ein-/Ausgaben; Adapter erhalten keine Browser-Session oder frei verwendbare Fach-DB-Verbindung. Ein späterer Runtime-Transport kann dieselbe Verantwortung übernehmen. Ein Netzwerkprotokoll wird jetzt nicht implementiert. + +Authentifizierung, Kontext-/Objektprüfung und fachliche Freigabe liegen im Anwendungsdienst. Ein Adapter kann Fähigkeiten und Quellrechte zusätzlich einschränken. Der Storage-Adapter entscheidet nicht selbst, wer einen Vorgang lesen darf. Fachliches Linking bleibt Tsumugu-Funktion. + +## 4. Source-Vertrag + +Ein kleiner registrierter Adaptervertrag umfasst: + +| Operation | Ein-/Ausgabe und Zusage | +|---|---| +| Verbindung beschreiben und prüfen | Konkrete Instanz-ID, Typ, Name, Fähigkeiten und serverseitig geprüfter Verbindungszustand. Zugangsdaten bleiben im zuständigen Secret-/Transportadapter. | +| Navigieren | Parent-/Navigationskennung, begrenzter Cursor; Ergebnis sind Navigationsknoten und/oder Ressourcen. Keine beliebigen Serverpfade vom Browser übernehmen. | +| Suchen | Typisierte Suchanfrage, Suchbereich, Filter, Sortierung, Cursor; begrenzte Ergebnisseite und Fortsetzungsinformation. Nicht unterstützte Filter ausdrücklich melden. | +| Ressource auflösen | Instanzgebundene Referenz; Metadaten, Quellstand, Darstellungsarten und aktuell zulässige Operationen. Fehlendes Original löscht die Referenz nicht. | +| Inhalt lesen | Original, Vorschau, Text oder bestimmte Anlage getrennt anfordern; Typ, Größe, Quellstand und vollständiger/gekürzter Zustand sind erkennbar. | +| Bearbeiten, wenn unterstützt | Inhalts- und Metadatenänderung sind getrennte Operationen mit erwartbarem Quellstand und Konfliktbehandlung. Im ersten Source-Schnitt nicht angeboten. | + +Fähigkeiten werden je Connector und Ressource bestimmt. Die tatsächliche Ausführung prüft erneut Quelle, aktuelle Rechte und DataPolicy. Ein UI-Flag ist keine Autorität. Fehlende Fähigkeit bleibt fehlend; ein Original darf nicht durch eine gekürzte Vorschau ersetzt werden. + +Ergebnisse beschreiben mindestens Instanz und externe Ressourcenkennung, Typ, Titel, vorhandene fachliche Daten, knappen erlaubten Auszug und Darstellungsarten. Paging-Cursor sind an die konkrete Verbindung und Suchanfrage gebunden. Suchtreffer allein erzeugen keine dauerhaften Elemente. Erst ausdrückliches Einbinden schreibt Fachreferenzen. + +Bestehende Element- und Binding-IDs bleiben erhalten. Gleiche externe IDs verschiedener Instanzen sind verschieden. Eine instanzgebundene Quellkennung ist kein Anlass zum automatischen Zusammenführen bereits vorhandener Elemente. IMAP-ID, fachliches Element und Dateihash bleiben unterscheidbare Begriffe. + +Einheitliche Zustände: nicht erreichbar, nicht berechtigt, nicht auffindbar, mehrdeutig, veraltet, Konflikt, Entsperrung erforderlich, nicht unterstützte Fähigkeit/Schutzprofil, Größenlimit und Verarbeitungsfehler. Geheimnisse und verborgene Quelleninformationen gehören nicht in Fehlermeldungen. + +## 5. Gemeinsame UI und Fähigkeiten + +Produktlokale, registrierte Komponenten: + +1. Verbindungseinrichtung mit gemeinsamer Hülle und quellenspezifischen Zugangsfeldern. +2. Quellenbrowser: Navigation, Suchbereich, Filter, Ergebnisse, Paging, erhaltene Auswahl und Vorschau. +3. Übernahme: gewählte Ressourcen, aktiver Vorgang/Akte, Kapitel und sichtbare Wirkung; erfolgreiche Teilübernahmen und Wiederholungen nachvollziehbar behandeln. +4. Ressourcenleser nach Darstellungsart: PDF, Bild, Text/Markdown, E-Mail einschließlich Anlagen und Metadatenformular. +5. Editorhülle: Laden, Berechtigungszustand, ungesicherte Eingaben, Speichern/Abbrechen und Konfliktanzeige; bestehende Notizbearbeitung als erster konkreter Editor. + +Filter und Spezialansichten können als Tsumugu-eigene registrierte Ergänzungen eingebunden werden. Vom Connector gelieferter ausführbarer Frontend-Code und ein universeller Formulargenerator gehören nicht zur Lieferung. Dieselben Browserkomponenten funktionieren als Dialog oder vollständige schmale Ansicht. Tastaturfokus, Rückkehr, Abbruch und unveränderte Eingaben bei Layoutwechseln gehören zur Hülle. + +Ressourcen-ID, Zielcontainer und Handlungskontext bleiben getrennt. Mehrfachauswahl verwendet die Verbindung als Teil der Identität und bleibt bei Such-/Seitenwechsel erhalten. Ein unbemerkter Wechsel des Zielkapitels oder Datenraums darf keine Übernahme auslösen. + +## 6. Paperless: funktionaler Suchausbau + +Der unmittelbar folgende Funktionsausbau umfasst kombinierbare Freitext-/Titelsuche, Filter für Korrespondenten, Dokumenttypen und Tags, Dokumentdatumsbereich, Sortierung und vollständiges Paging im berechtigten Bestand. Auswahlwerte aus der konkreten Quelle beziehen. Bei Tagkombinationen UND/ODER-Bedeutung sichtbar machen; tatsächlich unterstützte Kombinationen gegen die eingesetzte Paperless-Version prüfen. In der Grundlagenlieferung werden dafür Anfrage-/Ergebnisvertrag, Capability-Angaben und instanzgebundene Fortsetzungsinformation festgelegt; noch nicht implementierte Suchfähigkeiten bleiben ausdrücklich nicht verfügbar. + +Dokumentdatum und Erfassungsdatum bleiben getrennt. Wenn ein weiterer Datumsfilter angeboten wird, passend beschriften. Treffer vor Einbindung lesen können. Mehrfachauswahl über mehrere Seiten/Suchläufe erhalten. Keine feste Begrenzung auf die ersten 20 Treffer und kein vollständiger lokaler Dokumentindex als Voraussetzung. + +Typgerechte Filter für benutzerdefinierte Felder bleiben der nächste Suchausbau. Der Vertrag muss sie aufnehmen können, ohne eine generische Abfragesprache oder Finanzfunktion jetzt einzuführen. Bestandsfelder nicht mit ungeprüften API-Schlüsseln gleichsetzen. + +## 7. Storage, Inhaltsrevision und Verschlüsselung + +Der kleine Storage-Port speichert, öffnet, beschreibt und löscht begrenzte Byteinhalte. Er arbeitet mit opaken Speicherreferenzen. Diese binden Speicherinstanz, Generation, Objektkennung und Inhaltsrevision. Namensanzeige und Medientyp sind Metadaten; Dateiname oder beliebiger Clientpfad sind keine Speicheradresse. + +Der lokale Adapter übernimmt zunächst bestehende Medien und Versandfassungen. Bisherige Dateien bleiben lesbar, ohne Neu-Upload oder Umbenennung im Bestand. Alte Referenzen dürfen durch Ändern des konfigurierten Wurzelverzeichnisses nicht unbemerkt auf einen anderen Speicher zeigen. + +Neue Inhalte erst nach erfolgreicher geprüfter Ablage als verfügbar melden. Dateiablage und DB sind keine gemeinsame atomare Transaktion: kurze DB-Phasen, nachvollziehbare Operationskennung/Receipts und Wiederherstellung unvollständiger Abläufe nach dem Medien-Blueprint verwenden. Bestehende Größenlimits erhalten. Externe Aufrufe und größere Dateioperationen außerhalb offener Fachtransaktionen durchführen, Zugriffs-/Versionszustand vor abschließender Veröffentlichung erneut prüfen. + +Neue Inhaltsstände erhalten neue Revisionen. Versandfassungen bleiben an ihren festgehaltenen Stand gebunden. Ein interner Bytehash prüft die jeweilige Repräsentation; er ist keine allgemeine Ressourcenidentität und wird nicht als öffentliches Fingerprint-API angeboten. + +**Speicherort und Entschlüsselung sind getrennte Verträge:** + +- Der Storage-Port verarbeitet opake Bytes und benötigt keinen Entschlüsselungsschlüssel. +- Ein versioniertes Schutzprofil bezeichnet Klartextbestand, verwaltet verschlüsselte Inhalte oder kundenseitig verschlüsselte Inhalte. Schlüsselreferenz und Schlüsselzuständigkeit sind getrennt vom Speicherort; geheime Schlüssel werden nicht in die fachliche Speicherreferenz geschrieben. +- Ein gesonderter Content-/Crypto-Zugriff bestimmt, ob die konkrete Ausführungsstelle entschlüsseln darf. Der Core darf nicht voraussetzen, dass SaaS Inhalte immer lesen kann. Kundenseitig geschützte Inhalte können als verschlüsselt/gesperrt bekannt sein, ohne einen Klartextpfad anzubieten. +- Der Dateispeicher erzwingt keine PDF-/Bildinterpretation. Typprüfung und Reader benötigen autorisierten Klartext an der passenden Stelle; spätere Browser-/Runtime-Entschlüsselung muss dort anschließbar sein. +- Der vorhandene unverschlüsselte Bestand wird als Legacy-Zustand ausdrücklich beschrieben. Die erste Basislieferung verspricht noch keine Dateiverschlüsselung. Verschlüsselte Speicherung erst nach abgeschlossenem Schlüssel-/Recovery-Entwurf und passenden Nachweisen aktivieren. Bis dahin keine Datenschutz- oder SaaS-Freigabe daraus ableiten. + +Die Vorbereitung wird durch Vertragsprüfungen mit zwei Ablageadaptern und einem gesperrten Inhaltszugriff belegt. Opake Testbytes sind kein Nachweis realer Kryptografie. Eine produktive Browser-Schlüsselhaltung wird damit nicht behauptet. + +DataPolicy unterscheidet dauerhafte Ablage, temporären Cache, Übertragung für Live-Funktionen und externe Verarbeitung. Diese Trennung gilt auch für Leser, Exporte und Versandfassungen. Die erste Ausführung bleibt im vorhandenen Self-Hosting-Betrieb; für Hybridbetrieb ist anschließend der lokale Kommunikationskanal auszuarbeiten. EML-Archivkopien bleiben nach v0.2 ausschließlich im Kundenbereich. Eine verschlüsselte SaaS-Ablage ändert diese Sonderregel nicht. + +## 8. Migrationsfolge und Erhaltung + +1. Aktuellen Bestand und Tests erfassen; nur betroffene Schutz- und Blueprint-Abweichungen in den Schnitt aufnehmen. +2. Registrierten Source-Vertrag mit vorhandenen Paperless-/IMAP-Funktionen implementieren. Alte Routen bei Bedarf als kurzlebige delegierende Kompatibilitätsadapter erhalten; keine doppelte Fachlogik. +3. Bestehende Referenzen einer konkreten Connector-Instanz zuordnen. Eindeutige Bestände migrieren; mehrdeutige oder nicht auflösbare Einträge erhalten und zur Zuordnung markieren. Niemals auf die zuletzt angelegte Verbindung zurückfallen. Credentialwechsel innerhalb derselben Quelle ist von einem Wechsel der Quellinstanz zu unterscheiden. +4. Speicherinstanz/-generation für heutige Medien und Versandstände einführen; bestehende IDs, Pfade und Bytes erhalten. Reads zuerst kompatibel machen, danach neue Writes auf den Vertrag umstellen. +5. Frontend-Zugriff, registrierte Quell-/Darstellungsmodule und Ressourcenzugriff umstellen. Auch Export, Anlagen und Nachweise über die gemeinsame autorisierte Lesestrecke führen. Quellenbrowser und erweiterte Paperless-Suche danach als eigenen nutzbaren Funktionsausbau liefern. Keine neuen Quellverzweigungen in Akten-/Vorgangsseiten ergänzen; bestehende während der Migration gezielt in die zuständigen Quellmodule überführen. +6. Fachspec, technische Beschreibung und Ist-Dokumentation gezielt nachziehen. F-02b/c bleibt bis zu einer ausdrücklichen späteren Entscheidung erhalten; dieser lesende Source-Schnitt entscheidet keinen Ersatz der bidirektionalen Feldanforderung. + +Keine automatische Umdeutung von Kapiteln, Anlagenrollen oder virtuellen Freigabezusammenstellungen. Bestehende Kontextrechte, gemeinsame Notizänderungen, lokale Ordnung, unabhängige Aufgaben/Fristen und vollständige EML-Exporte bleiben erhalten. Ein Owner-vermittelter Dokumentabruf ist weiterhin auf ausdrücklich freigegebene Ressourcen begrenzt. + +## 9. Quellen und weitere Prüfaufträge + +Projekt: `C:/Dev/tsumugu/AGENTS.md`, aktuelle Fachspec 0.38 und technische/Ist-Dateien unter `docs/architecture`; Connector Suite v0.2; vorhandene Export-, Unterkapitel- und Schreiben/Anlagen/Versand-Aufträge. Die unveränderte Connector Suite v0.2 wird dem Paket als Quelle beigelegt; vorgesehener Repositorypfad: `C:/Dev/tsumugu/docs/architecture/Tsumugu_Connector_Suite_Architektur_v0.2.md`. + +Familienreferenzen ausschließlich aus den Projektkopien unter `C:/Dev/tsumugu/docs/reference`: A/B/C v0.3, Auth/Session/Scope, Medien/Dateien/sicheres Rendering und Release/Betrieb/Recovery. KI-Gateway, Workflow und Entitlements nur bei konkretem Bedarf. Bestehende Varianten bleiben gemäß A0 zulässig; keine Frameworkmigration oder neue familienweite Referenzarchitektur. + +Begleitend: `TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md` und `TSUMUGU_STORAGE_SCHLUESSEL_PRUEFAUFTRAG_2026-10-19.md`. Der Schlüssel-Prüfauftrag geht an die bestehende Architektur-Session, ohne sie hier automatisch zu kontaktieren. diff --git a/docs/architecture/TSUMUGU_STORAGE_SCHLUESSEL_PRUEFAUFTRAG_2026-10-19.md b/docs/architecture/TSUMUGU_STORAGE_SCHLUESSEL_PRUEFAUFTRAG_2026-10-19.md new file mode 100644 index 0000000..b877ccf --- /dev/null +++ b/docs/architecture/TSUMUGU_STORAGE_SCHLUESSEL_PRUEFAUFTRAG_2026-10-19.md @@ -0,0 +1,23 @@ +# Begrenzter Prüfauftrag an die bestehende Jinkendo-Architektur-Session + +**Stand:** 19.10.2026 · **Status:** Vorbereitet, nicht versandt. Keine Implementierung und keine neue parallele Referenzarchitektur. + +## Bedarf und Eingaben + +Tsumugu entwickelt eine kleine Source-/Storage-Basis aus Paperless, IMAP und eigener Dateiablage. Die spätere SaaS-Nutzung muss sowohl kundenseitig gehaltene Schlüssel als auch optional verwaltete Verschlüsselung unterstützen. Lokale Ablage und verschlüsselte zentrale Ablage sind getrennte Speicheroptionen. Speicherung, Live-Übertragung und externe Verarbeitung haben getrennte Freigaben. EML-Archivkopien bleiben gemäß Connector Suite v0.2 lokal im Kundenbereich. + +Lies die aktuellen Projektkopien unter `C:/Dev/tsumugu/docs/reference`, besonders A/B/C, Auth/Session/Scope, Medien/Dateien/sicheres Rendering und Release/Recovery. Ergänzend die Connector Suite v0.2 und `C:/Dev/tsumugu/docs/architecture/TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md`. Prüfe vorhandene Implementierungen nur für tatsächlich wiederverwendbare Mechanismen. Ein Konzept oder vorhandener Test ist noch kein erfolgreicher Produktnachweis. + +## Eng begrenzte Fragen + +1. Passt die Trennung aus opakem Storage-Port, versionierter Speicherreferenz und gesondertem Content-/Crypto-Zugriff zum Medien-Blueprint? Benenne notwendige Korrekturen am kleinen ersten Vertrag. +2. Skizziere einen überprüfbaren Einstieg für verwaltete Dateiverschlüsselung: Secret-/Schlüsselreferenz, Schutzprofil, Inhaltsrevision, Wiederherstellung, Rotation und Backupbindung. Nutze etablierte Mechanismen; keine eigene Kryptografie entwickeln. +3. Welche Metadaten des Inhalts-/Schutzformats müssen schon jetzt berücksichtigt werden, damit spätere kundenseitige Verschlüsselung vor dem Upload möglich bleibt? Der Core darf Entschlüsselung nicht voraussetzen. Benenne bewusst, welche Metadaten weiterhin zentral lesbar sein dürfen beziehungsweise einer späteren fachlichen Festlegung bedürfen. +4. Prüfe die Grenzen eines späteren Browsermodus: Gerätebindung, Wiederherstellung, Mehrgerätezugang und Freigabe an weitere Personen. Browserausführung und Schlüsselhaltung allein nicht als Schutz gegen jede Änderung am ausgelieferten Anwendungscode darstellen. Gib Sicherheitsannahmen ausdrücklich an. +5. Definiere höchstens eine spätere Anschlussstelle für lokale Runtime beziehungsweise KI-Processing. Kein Netzwerkprotokoll, keine Providerwahl und keine multimodale Pipeline jetzt ausarbeiten. + +## Erwartetes Ergebnis + +Eine kurze Ergänzung beziehungsweise Zuordnung zu den vorhandenen Blueprints: wiederverwendbare Mechanismen mit aktuellem Nachweisgrad, vorgeschlagene Schutz-/Schlüsselgrenzen, erforderliche Erstimplementierungsentscheidungen und eine kleine Negativtestliste. Klar trennen: Was kann die erste Connector-/Storage-Basis bereits vorbereiten, was muss vor realer Verschlüsselung fertig entschieden sein, was bleibt bis zur späteren Kunden-Runtime offen? + +Kein allgemeines SaaS-Framework, neues Identitätssystem, Schlüsselserver, DMS oder vollständiges E2EE-Produkt entwerfen. Ungeklärte Schlüsselwiederherstellung darf nicht durch Betreiber-Klartextzugriff oder stillen Schlüsselupload ersetzt werden. Keine Anwendung, Secrets, Datenbank, Konfiguration oder Deployments ändern. Rückgabe an die fachliche Tsumugu-Planung; durch diesen Text wird keine andere Session kontaktiert. diff --git a/docs/architecture/TSUMUGU_TECHNICAL_SPEC.md b/docs/architecture/TSUMUGU_TECHNICAL_SPEC.md index 65b2e36..ae7e5b3 100644 --- a/docs/architecture/TSUMUGU_TECHNICAL_SPEC.md +++ b/docs/architecture/TSUMUGU_TECHNICAL_SPEC.md @@ -485,6 +485,8 @@ Erster Dateischnitt, Vorschlag der registrierten Profile: JPEG, PNG, WebP und PD Upload startet nur bei Bearbeitungsrecht am Zielkontext. Der Download nutzt den Readplan: Sessioncookie, geprüfter Scope, lesbare Einbindung, lesbares Asset, aktuelle Revision. Kein öffentlicher `/media`-Mount und keine Session in der URL. +**Stand 19.10.2026, Implementierung der Grundlage:** Eigene Dateien und Versandfassungen laufen über einen kleinen Storage-Port mit lokalem Adapter. Die Speicherreferenz trägt Instanz, Generation, Objektkennung und Inhaltsrevision. Das Schutzprofil und die Schlüsselzuständigkeit liegen daneben; geheime Schlüssel stehen nicht in der Referenz. Der vorhandene Bestand ist `legacy-plaintext`. Profile `managed-encrypted` und `client-encrypted` werden geschlossen abgelehnt und nicht entschlüsselt. Paperless und IMAP sind registrierte Source-Adapter. Die Art prüft die Registrierung, nicht eine Datenbankliste. Ein dritter Testadapter belegt, dass Fachseiten, Reader und Export dafür nicht erweitert werden. Eine Referenz bindet eine konkrete Instanz. Dieselbe externe Nummer in zwei Instanzen bleibt getrennt. Mehrdeutiger Altbestand wird nicht auf den zuletzt angelegten Zugang gelegt. F-02b und F-02c bleiben offen und werden durch diesen lesenden Schnitt nicht ersetzt. Zugangsdaten liegen weiterhin im Adapter, derzeit als Klartext in `connectors.secret`. Das ist kein Nachweis von Verschlüsselung oder SaaS-Reife. + Ausfall des Storage: neue Uploads und Downloads antworten 503 `storage_unavailable`. Bereits gespeicherte fachliche Metadaten bleiben lesbar. Die Oberfläche zeigt den Dateizustand `unavailable`, ohne einen leeren Erfolg zu melden. ### 7.2 Paperless-Felder diff --git a/docs/architecture/Tsumugu_Connector_Suite_Architektur_v0.2.md b/docs/architecture/Tsumugu_Connector_Suite_Architektur_v0.2.md new file mode 100644 index 0000000..b804d87 --- /dev/null +++ b/docs/architecture/Tsumugu_Connector_Suite_Architektur_v0.2.md @@ -0,0 +1,306 @@ +# Tsumugu – Connector Suite: Architekturkonzept + +**Version:** 0.2 · **Stand:** 19.10.2026 +**Status:** Konsolidierter fachlich-technischer Konzeptstand, **keine Implementierungsfreigabe** +**Geltungsbereich:** Tsumugu; mögliche spätere Wiederverwendung in Jinkendo nach gesonderter Prüfung +**Grundlage:** Fortgeschriebene Festlegungen in dieser Unterhaltung vom 18.–19.10.2026 und `Tsumugu_Product_Recovery_Baseline_v0.1.md` (16.10.2026). + +## 1. Zielbild und Abgrenzung + +Tsumugu ist ein **universeller Vorgangs-, Akten- und Informationsmanager**. Es führt Ressourcen und Informationen zu Vorgängen zusammen, ohne die angeschlossenen Systeme zu ersetzen. Aktenstruktur, Beziehungen, Notizen, Aufgaben, Fristen, Chronologie und fachliche Zuordnungen sind Tsumugu-eigene Informationen. Dokumente, E-Mails, Dateien und Bankbuchungen verbleiben grundsätzlich in ihren Quellen. + +Die **Connector Suite** erschließt externe Ressourcen und Dienste über eine einheitliche Integrationsarchitektur. Sie ermöglicht Navigation, Suche, Lesen, Metadaten, Darstellung, bei geeigneter Quelle Bearbeitung und selektive Aktualisierung. Sie ist **keine generelle Import-, Spiegelungs- oder Archivierungsplattform**. + +**Geschäftliches Ziel:** Dasselbe Produkt soll sowohl **vollständig selbst gehostet** als auch als **SaaS mit kundenseitig betriebener Connector Runtime** angeboten werden können. Eine SaaS-Variante mit zentralen Connectoren bleibt möglich. Self-Hosting ist insbesondere für datenschutz- und selbsthostingaffine Paperless-Nutzer relevant. Die kommerzielle Nachfrage ist eine Hypothese, keine nachgewiesene Tatsache. + +**Leitprinzipien:** +- *Source of Truth:* Externe Quelldaten bleiben im jeweiligen führenden System. +- *Reference first:* Tsumugu speichert primär Referenzen, eigene Fachdaten und nötige, freigegebene Metadaten. +- *Least privilege:* Rechte aus Quellsystem **und** Tsumugu gelten gemeinsam. +- *Policy-based placement:* Pro Connector-Instanz und Datenklasse bestimmen, was gespeichert, übertragen oder verarbeitet werden darf. Lokale Speicherung ist eine Option, keine pauschale Pflicht. +- *Cloud content opt-out:* SaaS-Kunden können die dauerhafte Cloud-Speicherung von Dokumentinhalten und KI-Artefakten vollständig deaktivieren. +- *Capability based:* Verschiedene Connectoren bieten verschiedene Operationen, Ressourcentypen und Darstellungsarten an. +- *Pragmatic UI:* Generische Tsumugu-Komponenten vor beliebig ladbarem Connector-Frontend-Code. +- *Demand driven:* Keine allgemeine Plattformkomplexität oder zusätzliche Blueprints ohne konkreten Modulbedarf. + +## 2. Logische Gesamtarchitektur + +```text + ┌──────────────────────────────────────────────┐ + │ Tsumugu UI │ + │ Akten | Ressourcenbrowser | Suche | Preview │ + │ Metadatenansicht/-editor | Aufgaben/Fristen │ + └───────────────────┬──────────────────────────┘ + │ standardisierte Ressourcen-/UI-Verträge + ┌───────────────────▼──────────────────────────┐ + │ Tsumugu Core │ + │ Akten, Links, Notizen, Metadatenindex, │ + │ CollectionBindings, Rechte, Daten-Policies │ + └───────────────────┬──────────────────────────┘ + │ autorisierte Connector-Operationen + ┌───────────────────▼──────────────────────────┐ + │ Connector Runtime / Adapter │ + │ Fähigkeiten, Quellzugang, Mapping, Sync, │ + │ Export, Zugriffskontrolle, lokale Ablage │ + └─────┬──────────┬──────────┬───────────┬─────┘ + │ │ │ │ + Paperless IMAP Dateien Bank/API + │ + Lokales NAS + Processing-Dienste (z.B. KI) als + eigener Fähigkeitsvertrag +``` + +### Betriebsformen + +**A – Self-Hosted:** Tsumugu Core und Connector Runtime laufen in einer selbst betriebenen Umgebung, gegebenenfalls auf separaten lokalen Systemen. + +**B – Hybrid-SaaS (bevorzugte Zielrichtung):** Tsumugu Core läuft beim Anbieter, die Connector Runtime optional beim Kunden. Sie verbindet lokale/zugängliche Quellsysteme und setzt Datenfreigaben durch. Tsumugu persistiert nur freigegebene Referenzen/Metadaten und eigene Fachdaten. Originaldokumente müssen nicht im SaaS-Speicher liegen. + +**C – SaaS mit zentralen Connectoren:** Für Nutzer ohne lokale Infrastruktur grundsätzlich möglich, aber nicht als Voraussetzung für die erste Umsetzung. + +**Grenze:** Eine lokale Runtime schützt Daten nicht automatisch vor Cloud-Übertragung. Vorschau, Live-Suche, KI-Anfragen, Protokolle und temporäre Verarbeitung unterliegen ebenfalls einer expliziten Datenfluss-Policy. Der sichere Kommunikationskanal (Initiierung, Authentisierung, Autorisierung, Verbindungsausfall) ist noch technisch auszugestalten. + +## 3. Connector-Kategorien + +| Kategorie | Wesentliche Aufgabe | Erste Anwendungsfälle | Architektonische Einordnung | +|---|---|---|---| +| **Source** | Datenbestand navigieren, suchen, lesen, optional bearbeiten | Paperless, IMAP, Dateien | Gemeinsamer Ressourcenkontrakt | +| **Financial** | Buchungen und Kontoinformationen strukturiert lesen | Banken / Kontoinformationsanbieter | Spezialisierte Source-Fähigkeiten, zunächst read-only | +| **Processing** | Inhalte auswerten und strukturierte Ergebnisse erzeugen | KI, perspektivisch OCR/Konvertierung | **Kein gewöhnlicher Ressourcenbrowser**; eigener Eingabe-/Ergebnisvertrag | +| **Storage** | Konfiguriert ablegen und wiederfinden | NAS-/Dateiablage, `.eml`-Archiv | Eigener Ablage-/Abrufvertrag; kann Infrastruktur mit Datei-Source teilen | + +Die vier Kategorien sind **Ordnungsbegriffe**, keine Verpflichtung zu vier separaten Servern, Frameworks oder vollständigen APIs. Gemeinsamkeiten werden nur dort standardisiert, wo sie bereits benötigt werden. + +### 3.1 Source: Paperless +- Vollständige Suche/Navigation im durch Quellidentität berechtigten Bestand, nicht nur in bereits aktenverknüpften Elementen. +- Dokumentreferenz, Quelle, Metadaten, OCR-/Textabruf auf Anfrage, Original-/Vorschauzugriff. +- Bearbeitung **führender Paperless-Metadaten** über Paperless, wenn Connector- und Quellrechte dies erlauben; Tsumugu-eigene Felder separat. +- Selektiver Metadatenindex, nicht generelle Dokument-/Volltextreplikation. +- Navigation etwa über Dokumenttypen, Korrespondenten und Tags; konkrete UI-Komponenten noch zu spezifizieren. + +### 3.2 Source: IMAP +- Postfächer und Ordner navigieren, Nachrichten suchen, Header, Inhalt und Anhänge zugänglich machen. +- **Explizite Einzelreferenzen bleiben bei Ordnerwechsel als Aktenverknüpfung bestehen.** IMAP-UID ist typischerweise ordnerbezogen; der Adapter braucht eine belastbare Wiedererkennungsstrategie bzw. meldet nicht auflösbare Referenzen, ohne sie zu löschen. +- Ordner können als **dynamische Sammlung** referenziert werden, auch für künftige passende Nachrichten. +- Optionales lokales `.eml`-Archiv, Details in Abschnitt 7. +- Umfang einer vollständigen E-Mail-Bearbeitung (Versenden, Verschieben etc.) ist **nicht** festgelegt und kein Grund für eine komplette E-Mail-Client-Nachbildung. + +### 3.3 Source: Dateien +- Zugriff auf explizit freigegebene Verzeichnisse / Netzlaufwerke, Navigation, Suche, Lesezugriff, Vorschau, Metadaten. +- Pfad und Ressource nach Möglichkeit getrennt modellieren; Verschieben/Umbenennen darf nicht ungeprüft Aktenverknüpfungen löschen. +- Schreiboperationen nur bei ausdrücklicher Fähigkeit und Berechtigung. + +### 3.4 Financial: Banken (beschlossenes Grundmodell) +- Financial ist technisch eine **spezialisierte Source-Integration**, keine eigene Banking-Plattform. +- Es werden **bestehende Banking-/Kontoinformationsdienste** integriert; zu Beginn ausschließlich **lesender Zugriff auf Einzelbuchungen**. Keine Überweisungen oder Zahlungsinitiierung. +- Vollständige Abfrage des freigegebenen Buchungsbestands ist möglich; Tsumugu speichert **standardmäßig keine komplette Umsatzhistorie**. +- Dauerhaft verbleiben insbesondere explizit zugeordnete Buchungsreferenzen und die für Rechnung, Zahlung, Teilzahlung, Sammelzahlung oder Erstattung benötigten Metadaten (etwa Betrag, Datum, Gegenpartei, Verwendungszweck), sofern durch die Datenrichtlinie freigegeben. +- Rechnungs-/Zahlungszuordnungen sind **Tsumugu-eigene Viele-zu-viele-Beziehungen** und bleiben auch erhalten, wenn der Banking-Anbieter eine frühere Buchung nicht mehr abrufen kann. +- Providerwahl, konkrete Einwilligungs-/Zugangsmechanik und Buchungsidentitäten sind integrationsbezogene Umsetzungsfragen. + +### 3.5 Processing / KI (beschlossenes Grundmodell) +- Processing Connectoren sind **Verarbeitungsdienste**, keine normale Ressourcenquelle; eigener Eingabe-/Ergebnisvertrag statt erzwungenem Source-Interface. +- Wesentliche fachliche Fähigkeiten: **Extraktion, Klassifikation, Zusammenfassung, informationsgestützte Fragen, Beziehungsanalyse und Handlungsvorschläge**. Diese Fähigkeiten sind Aufgabenarten, nicht zwingend eigenständige APIs. +- Eingaben können **Text, strukturierte Daten, Bilder und PDF-Dokumente** sein. Moderne multimodale APIs bzw. lokale Modelle können Original-PDFs/Fotos interpretieren; ein separater OCR-Dienst ist **optional, keine Pflicht**. Vorhandene Paperless-OCR-Texte sollen bei Eignung bevorzugt wiederverwendet werden. +- Ausführung **lokal oder extern** entsprechend Datenfreigabe, unterstützter Modellfähigkeit und geeigneter Kosten-/Leistungsabwägung. +- Verarbeitungsschritte dürfen **kombinierbar** sein. Keine neue umfassende KI-Agenten- oder Workflow-Plattform als Voraussetzung; bestehende Jinkendo-KI-Gateway-/Workflow-Blueprints bei konkret benötigten Modulen prüfen. +- Ergebnisse umfassen nachvollziehbare **Quellreferenz, Quellstand, Verarbeitungsart und Prüfstatus**. Vorschläge (insbesondere Fristen und finanzielle Aussagen) werden nicht ungeprüft zu bestätigten Fakten oder automatischen Aktionen. +- Wiederverwendbare Ergebnisse können persistiert werden; **reine Zwischenstände werden gelöscht**. Speicherort nach Datenrichtlinie, nicht generell lokal. +- Die **Freigabe zur temporären externen Verarbeitung** ist ausdrücklich getrennt von der **Freigabe zur dauerhaften Cloud-Speicherung**. +- Konkrete priorisierte KI-Use-Cases bleiben Produktentscheidungen; Beispiele begründen noch keine umfassende Workflow-Engine. + +### 3.6 Storage (erweiterter Fähigkeitenbereich) +- Storage dient der **konfigurierbaren, sicheren Ablage und dem autorisierten Abruf** von Artefakten: z.B. `.eml`-Archivkopien, strukturierte KI-Extraktionen, Zusammenfassungen, OCR-Volltexte oder temporäre Verarbeitungsdateien. +- Storage ist **kein eigenes DMS**, keine Pflichtspiegelung aller Quelldaten und keine Wissens- oder Workflow-Engine. +- Physische Speicherdienste können **lokal** (z.B. NAS, Dateisystem, objektbasierter Speicher) oder **zentral** bereitgestellt werden, soweit Datenrichtlinien dies zulassen. +- Fachliche Zuordnung, Herkunft und Prüfstatus verwaltet Tsumugu als **Result Management**; die Storage-Schicht verwaltet Ablage, Abruf, Integrität, Lebensdauer und Löschanforderungen. Result Management ist zunächst eine logische Funktion, **kein neuer Pflicht-Microservice**. +- Sonderregel IMAP bleibt bestehen: Aktivierte `.eml`-Archivkopien liegen **nur an einem konfigurierbaren lokalen Ablageort**, auch bei SaaS-Nutzung. + +## 4. Ressourcen- und Referenzmodell + +**Logische Konzepte – kein endgültiges Datenbankschema:** + +| Konzept | Bedeutung | +|---|---| +| `Resource` | Tsumugu-interne stabile Identität eines referenzierten fachlichen Elements | +| `ResourceLocator` | Einer von mehreren Zugriffswegen zur Ressource (z.B. IMAP-Original, NAS-Archivkopie) | +| `ResourceMetadata` | Quellmetadaten, normalisierte Suchfelder und Herkunft; Tsumugu-eigene Metadaten fachlich getrennt | +| `CollectionBinding` | Referenz auf Container/gespeicherte Abfrage mit Zuordnung zu einer Akte und dynamischer Mitgliedschaft | +| `ConnectorInstance` | Konkrete konfigurierte Verbindung samt Identität, Fähigkeiten und Datenrichtlinien | +| `DataPolicy` | Erlaubte Speicherung, Übertragung und Verarbeitung je Datenklasse/Connector-Instanz | + +**Ressourcen-Lebenszyklus:** Eine live entdeckte Ressource muss nicht automatisch dauerhaft gespeichert werden. Eine explizit zugeordnete Ressource erhält eine stabile Referenz. Ressourcen können zusätzlich durch ausdrücklich konfigurierte Indexierung aufgenommen werden. + +**Identität und Kopie:** IMAP-Original und gesicherte `.eml`-Kopie können mehrere Locator derselben Tsumugu-Ressource sein. Ein E-Mail-Anhang, der separat in Paperless eingegangen ist, ist grundsätzlich eine **eigene**, möglicherweise verknüpfte Ressource, nicht automatisch identisch. Ähnliche Inhalte werden nicht ungeprüft zusammengelegt. + +**Änderungen:** Externe Pfade sind nicht notwendigerweise stabile IDs. Bei fehlendem Original bleibt die Aktenreferenz erhalten und zeigt einen differenzierten Auflösungs-/Verfügbarkeitsstatus; wo vorhanden wird eine autorisierte alternative Repräsentation genutzt. + +## 5. Aktenzuordnung und dynamische Sammlungen + +Festgelegt sind drei Grundfälle: + +1. **Einzelreferenz:** bewusstes, dauerhaftes Verknüpfen einer Ressource mit einer oder mehreren Akten; bei Quellverschiebung bleibt die Verknüpfung bestehen. +2. **Statische Auswahl:** aktuell ausgewählte Elemente werden einzeln referenziert; sie sind unabhängig von späterer Sammlungsmitgliedschaft. +3. **Dynamische Sammlung:** Ordner, Sammlungen oder geeignete gespeicherte Suchregeln können Akten zugeordnet werden. Aktuelle und später hinzukommende passende Ressourcen werden dynamisch angezeigt, **ohne Originaldaten zu importieren**. + +**Wichtige Abgrenzung:** Eine dynamische Sammlung erzeugt nicht zwingend dauerhafte Einzelreferenzen. Explizite Einzelreferenzen bleiben auch dann erhalten, wenn eine Ressource die Sammlung verlässt. Automatische KI-Bearbeitung/Fristauslösung wird daraus nicht abgeleitet. + +**Noch offen:** Ob einzelne `CollectionBindings` bei Verlassen der Sammlung optional ein dauerhaftes Referenzieren aller bisherigen Mitglieder erlauben. Die zuletzt besprochene Empfehlung war *live/dynamisch als Standard, dauerhafte Übernahme optional*; dieser Zusatz wurde **nicht ausdrücklich endgültig entschieden**. + +## 6. Datenhoheit, selektiver Index und temporäre Verarbeitung + +| Datenklasse | Grundverhalten | +|---|---| +| Originaldokumente, E-Mail-Original, Dateien | Verbleiben in führender Quelle | +| Quellreferenzen und technische IDs | Bei Verknüpfung dauerhaft in Tsumugu | +| Tsumugu-eigene Akten, Notizen, Beziehungen, Aufgaben, Fristen, Finanzzuordnungen | Dauerhafte Tsumugu-Daten | +| Relevante Quellmetadaten | Selektiv und freigegeben indexierbar für Suche/Fristen/Navigation | +| Volltexte, OCR, PDFs, Vorschauen | Kein generelles permanentes Spiegeln; auf Abruf, bei Bedarf temporär | +| KI-Arbeitstexte/-Zwischenergebnisse | Zweckgebunden und kurzlebig; definierter Standort, Aufbewahrung und Löschung | +| KI-abgeleitete Metadaten | Vorschlag mit Herkunft/Prüfstatus; selektiv bestätigte Fakten in Tsumugu nutzbar | +| Wiederverwendbare KI-Artefakte / Analysen | Optional dauerhaft im lokalen oder zentralen Artifact Storage, gemäß Daten- und Verarbeitungsrichtlinie | +| `.eml`-Archivkopie | Nur am konfigurierten lokalen Ablageort, nicht im SaaS-Dateispeicher | +| Zugangsdaten einer lokalen Quelle | Vertrauenswürdige lokale Connector Runtime; nicht als Nutzdaten an SaaS senden | + +**Verbindliche SaaS-Option:** Kunden können **jede dauerhafte Cloud-Speicherung von Dokumentinhalten und KI-Artefakten deaktivieren**. Dann verbleiben zentral nur Tsumugu-eigene Akteninformationen, freigegebene Metadaten und Referenzen. Dies bedeutet **nicht**, dass bei gesondert genehmigter externer Analyse niemals Daten übertragen werden. Temporäre Übertragungen, Caches und Logs sind separat zu kontrollieren. + +**Datenrichtlinien** gelten **pro Connector-Instanz und Datenklasse** und unterscheiden mindestens: *dauerhaft speichern*, *temporär zwischenspeichern*, *für Live-Funktion übertragen*, *an externen Processor weitergeben*. Konkrete Feldlisten/Schutzprofile werden **bei Implementierung des jeweiligen Connectors** festgelegt, nicht als globales Vollschema aller Quellen. + +**Metadatenhoheit (bestätigt):** Quellmetadaten werden bei vorhandenen Schreibrechten **im führenden Quellsystem** bearbeitet; nach Erfolg wird der Tsumugu-Index aktualisiert. Tsumugu-eigene Felder bleiben separat. Kein automatisches Zurückschreiben von Tsumugu-Feldern in die Quelle. Bei konkurrierenden Änderungen möglichst Konflikterkennung statt stiller Überschreibung. + +**Aktualisierung (bestätigte Richtung):** Bedarfsgesteuert beim Öffnen, ereignisbasiert wenn möglich und/oder periodisch. Standardmäßig referenzierte Ressourcen und dynamische Sammlungen; optionale umfassendere Indexierung. Live-Suche des gesamten berechtigten Quellbestands bleibt unabhängig davon möglich. + +## 7. IMAP: dauerhafte Referenzen und optionale `.eml`-Sicherung + +**Verbindlich beschlossen:** Jede IMAP-Connector-Instanz erhält eine Archivierungsoption: + +| Modus | Verhalten | +|---|---| +| `automatic` (**Standard**) | Explizite Zuordnung einer E-Mail zu einer Akte löst lokale `.eml`-Sicherung aus | +| `manual` | Sicherung nur auf Nutzeraktion | +| `disabled` | Keine `.eml`-Archivierung | + +- Bloße Mitgliedschaft in einer dynamischen Sammlung löst **keine automatische Sicherung** aus. +- `.eml` wird über lokale Runtime am konfigurierbaren Ablageort, z.B. NAS, gesichert; nicht im zentralen SaaS. +- Akteneintrag kann IMAP-Original und lokale Archivkopie als alternative Locator derselben Ressource kennen. +- Erfolg erst nach geprüfter Ablage melden; Integritätsmerkmal (z.B. Prüfsumme), Zeitpunkt und Fehlerstatus festhalten. +- Archivkopie ist **nicht automatisch revisionssicheres Archiv oder vollständige Backupstrategie**. +- Der Zugriff auf lokale Archivkopien ist ebenfalls zu autorisieren; keine Erhöhung von Berechtigungen durch bloße Existenz einer Kopie. + +## 8. Berechtigungs- und Sichtbarkeitsmodell + +Der effektive Zugriff auf eine externe Ressource setzt voraus: + +1. die Erlaubnis durch **Tsumugu** (Datenraum, Akte, Freigabe bzw. Connector-Nutzung), **und** +2. die Berechtigung der **verwendeten Quellidentität** sowie die jeweilige Connector-Fähigkeit. + +Pro Connector-Instanz können **individuelle Benutzerzugänge** oder ein **verwalteter gemeinsamer Zugang** genutzt werden. Bei gemeinsamem API-Key/Service-Konto darf dessen technischer Zugriff nicht unkontrolliert auf alle Tsumugu-Nutzer übertragen werden. Der Kontext des aufrufenden Nutzers und die zulässige Delegation sind bei jeder Operation relevant. + +Die Suche und Navigation umfassen grundsätzlich den **vollständigen durch diese Rechte erreichbaren Quellbestand**, nicht bloß bereits gespeicherte Referenzen. Eine Aktenfreigabe allein darf keine unberechtigten externen Inhalte offenlegen. Offline-Status und fehlende Quellrechte müssen unterscheidbar angezeigt werden. + +## 9. Präsentationsvertrag und UI-Grenze + +Connectoren sollen neben Daten und Fähigkeiten **deklarative UI-Metadaten** liefern können (Ressourcentyp, Felder und Feldtypen, Labels, erlaubte Operationen, Navigationsstruktur, verfügbare Vorschau- oder Editorarten). + +**Bevorzugte Stufen:** +1. **Generische Tsumugu-Komponenten:** Baum/Navigation, Liste/Tabelle, Suche/Filter, Detail/Metadaten, Vorschau, Formular/Metadateneditor. +2. **Registrierte, Tsumugu-eigene Spezialansichten:** z.B. E-Mail-Thread, Buchungsdetails oder PDF-Viewer, soweit fachlich nötig. +3. **Von Connectoren gelieferter ausführbarer Frontend-Code:** **nicht Bestandteil der anfänglichen Zielarchitektur**; später nur bei nachgewiesenem Bedarf und mit eigenem Sicherheitskonzept. + +Ziel ist **kein universeller Low-Code-UI-Generator** und keine vollständige Nachbildung der Oberflächen von Paperless, E-Mail-Clients oder Bankportalen. Der volle **berechtigte Datenbestand** ist navigier-/durchsuchbar; Bearbeitung wird nur für konkret angebotene Fähigkeiten umgesetzt. + +## 10. Querschnittsfähigkeiten und Vertragsgrenzen + +**Gemeinsamer Minimalvertrag für Source-artige Connectoren (konzeptionell):** +- Identität, Instanz und angebotene Fähigkeiten ermitteln. +- Navigation/Listen und Suche innerhalb der Quellrechte. +- Ressource auflösen, Metadaten lesen, Inhalt/Vorschau bei Fähigkeit abrufen. +- Unterstützte Schreib-/Exportoperationen autorisiert ausführen. +- Änderungen erkennen bzw. selektiven Index aktualisieren, soweit unterstützt. +- Verständliche Zustände melden: nicht erreichbar, nicht berechtigt, nicht auffindbar, veraltet, Konflikt, Fehler. + +**Kein falscher Universalvertrag:** Banking benötigt transaktionale Semantik, KI einen Processing-Vertrag und lokaler Storage einen Ablage-/Abrufvertrag. Gemeinsame Technik wird nur bei konkret gemeinsamem Bedarf herausgezogen. + +**Sicherheitsgrenzen:** Quellzugangsdaten geschützt verwahren; starke Authentisierung der lokalen Runtime gegenüber SaaS; Autorisierung pro Operation; keine willkürlichen Dateipfade und keine überprivilegierten Service-Accounts; sichere Vorschau/Rendering; kontrolliertes Egress und Löschung temporärer Daten. Konkrete Technologieentscheidungen werden in den zuständigen technischen Blueprints geprüft. + +## 11. Storage- und Result-Management-Architektur (konsolidiert v0.2) + +### 11.1 Verantwortlichkeiten + +| Baustein | Verantwortlichkeit | Nicht seine Aufgabe | +|---|---|---| +| **Tsumugu Core / Result Management** | Verknüpft Ergebnis mit Akte/Ressource, kennt Herkunft, Quellstand, Status, Zugriffsrechte, Wiederverwendbarkeit und Speicherreferenz | Große Artefakte ungefragt in die Core-Datenbank aufnehmen | +| **Artifact Storage** | Speichert/liest/löscht Inhalte, gewährleistet Integritätsprüfung, Version-/Ablagebezug und geregelte Retention | Fachliche Rechnungsinterpretation oder KI-Entscheidungen | +| **Connector Runtime** | Autorisierter Zugriff auf lokale Quellen/Speicher; führt lokal erlaubte Ablage und Abholung aus | Umgehung von Quellrechten oder Datenrichtlinien | +| **Processing Connector** | Erzeugt Ergebnisse aus explizit autorisierten Eingaben | Legt Datenresidenz oder Aufbewahrung eigenmächtig fest | + +Das Modell unterstützt **eine fachliche Ressource mit mehreren Zugriffspfaden** (z.B. IMAP und gesicherte `.eml`-Kopie) und **mehrere aus ihr abgeleitete Artefakte** (z.B. OCR-Text, Extraktions-JSON, Zusammenfassung). Diese sind nicht mit dem Original identisch und müssen nicht im selben Speicher liegen. + +### 11.2 Speicherentscheidung + +**Kein pauschaler Vorrang lokaler Ablage.** Eine lokale Runtime kann langsam oder zeitweise unerreichbar sein; bei externer KI-Verarbeitung werden erlaubte Inhalte ohnehin zeitweise übertragen. Die Datenschutzwirkung hängt daher stärker vom **gesamten Datenfluss, Schlüsselzugriff und Verarbeitungsort** als nur vom physischen Speicherort ab. + +Grundsätzliche Speicheroptionen: +- **SaaS-/Managed-Storage:** Für ausdrücklich freigegebene abgeleitete Ergebnisse; gute serverseitige Verfügbarkeit. Verschlüsselung und kontrollierte Löschung sind Pflicht. Serverseitige Verschlüsselung allein bedeutet nicht, dass der Betreiber keine Klartextzugriffsmöglichkeit besitzt. +- **Lokaler Storage:** Für sensible Inhalte oder Nutzerpräferenzen; lokale Verfügbarkeit hängt von Runtime/NAS und Verbindung ab. Lokale Verarbeitung kann tatsächliche Übertragung vermeiden. +- **Hybrid:** Auswahl nach Datenklasse und Connector-Instanz, getrennt nach Speicherung, temporärem Zugriff und externer Verarbeitung. + +**SaaS-Cloud-Content-Opt-out ist verbindlich:** Originalinhalte und KI-Artefakte müssen ohne dauerhafte Cloud-Speicherung verwendbar sein. Die dafür benötigten Tsumugu-eigenen Akteninformationen und freigegebenen Metadaten bleiben separat behandelbar. + +### 11.3 Mindestfähigkeiten des Storage-Vertrags + +1. **`put/get/delete`** für typisierte Artefakte (Dateien, Text, JSON etc.), nur nach Autorisierung und Policy-Prüfung. +2. **Referenzen und alternative Speicherorte** statt ungefragter Binärkopien im Core; stabile Zuordnung zu Quellressource und ggf. Verarbeitungsstand. +3. **Integrität und nachvollziehbarer Status:** Prüfsumme, erfolgreiche bestätigte Ablage, Unterscheidung zwischen vorhanden, nicht erreichbar, nicht autorisiert und nicht mehr vorhanden. +4. **Version und Herkunft:** Ergebnis kann einem bestimmten Quell-/Analysezustand zugeordnet und bei Quelländerung als möglicherweise veraltet erkannt werden. +5. **Aufbewahrung und Löschung:** Dauerhaft vs. befristet, Löschung inklusive geregelter Cache-/Backup-Fristen; keine falsche Garantie sofortiger physischer Löschung aller Sicherungskopien. +6. **Sichere lokale Speicherpfade und Schlüsselverwaltung:** Kein vom Client frei vorgebbarer Dateisystempfad, keine Rechteausweitung durch Archivkopien. +7. **Kontrollierbare Abrufwege:** Bei lokaler Ablage kann SaaS die Referenz anzeigen, aber Inhalte nur bei erreichbarer und autorisierter lokaler Runtime ausliefern. + +Keine Pflicht zur universellen Dateiversionierung, geografischen Replikation, komplexen Storage-Abstraktion oder zentralen Search-Index-Engine für den MVP. + +### 11.4 Wiederverwendung von KI-Ergebnissen + +Ein Analyseergebnis darf nur dann als aktuell wiederverwendet werden, wenn Verarbeitungsaufgabe, Quellstand und Prüfstatus geeignet sind. Der Core verwaltet knappe, relevante Ergebnis-Metadaten; das größere Artefakt kann lokal oder zentral liegen. Fachliche Bestätigungen (z.B. ein akzeptierter Rechnungsbetrag) werden als Tsumugu-Daten geführt und nicht mit unbestätigten KI-Vorschlägen vermischt. + +### 11.5 Betriebliche Mindestfragen – zur Umsetzung, nicht jetzt als Plattformprojekt + +Für den Hybridbetrieb bleiben drei technische Klärungen: **(a)** sicherer SaaS-zu-Lokal-Kanal, vorzugsweise ohne eingehende Kundenports, **(b)** Autorisierung jeder Aktion einschließlich gemeinsamer Quellkonten, **(c)** Einrichtung, Updates und Verbindungs-/Versionskompatibilität der lokalen Runtime. Verfügbarkeit und erwartbare Abrufgeschwindigkeit sind bei der ersten produktiven Hybridstrecke praktisch zu messen. + +--- + +## 12. Technische Referenzarchitektur und Umsetzungsmodus + +Der separate Jinkendo-Architektur-Workstream betreut technische Standards/Blueprints (u.a. Auth/Scopes, Release/Recovery, KI-Gateway/Privacy, Workflows, Entitlements/Quotas, Medien/Rendering). **Tsumugu** liefert die fachlichen Modulanforderungen. Bei größeren Modulen wird zunächst geprüft, ob vorhandene Jinkendo-Implementierungen und Blueprints anwendbar sind. Neue Spezial-Blueprints nur **bei Bedarf**; keine pauschale Blueprint-Produktion. Konzepte sind nicht automatisch getestet oder produktionsreif. + +**Schlanker Realisierungspfad (Vorschlag, keine freigegebene Roadmap):** +1. Erstes durchgängiges Source-Szenario mit Paperless: Navigation/Suche → Referenzieren → Metadaten → Akte/Preview → Quell-Edit, falls nötig. +2. Gemeinsame `Resource`/`Locator`/Berechtigungs-/Datenpolicy-Prinzipien anhand IMAP inkl. optionaler `.eml`-Sicherung validieren. +3. Dynamische CollectionBindings, lokale Hybrid-Runtime und selektiver Index nach echten Use Cases absichern. +4. Banking read-only und KI/Processing jeweils als begrenzte eigene Integrationen ergänzen. + +Die Reihenfolge steht unter fachlichem MVP-Vorbehalt und ist keine Verpflichtung, alles vor dem ersten Release zu bauen. + +## 13. Nur noch wesentliche offene Architekturfragen + +| Thema | Klärung bei | Warum relevant | +|---|---|---| +| Hybrid-SaaS ↔ lokale Runtime: Verbindung, Vertrauensgrenze, Live-Zugriff | Vor Hybrid-Implementierung | Sicherheit, Erreichbarkeit, Datenschutz | +| Datenprofile pro konkreter Connector-Instanz, inkl. Vorschau, Suche, Cache/Logs | Je Connector-Implementierung | Wirkliche Datenkontrolle statt nur Marketingversprechen | +| Identität/Recovery beim Verschieben von IMAP-/Datei-Ressourcen | Bei IMAP-/Datei-Anbindung | Haltbare explizite Referenzen | +| Rechte auf Akten-/Unterakten-/Ressourcenebene und Delegation gemeinsam genutzter Quellzugänge | Vor Mehrnutzer-Freigabe | Keine Datenlecks | +| Dynamische Sammlung: optionale dauerhafte Übernahme bei Austritt | Wenn benötigt | Bewusst nicht festgelegt | +| Konkrete KI-Use-Case-Priorität, Eingabe-/Ergebnisumfang und Freigaben | Vor KI-Funktion | Verarbeitung und fachliche Korrektheit | +| Artifact-Storage-Adapter, Verschlüsselung/Schlüsselmodell, Retention und tatsächliche Löschwege | Vor Storage-Implementierung | Datenhoheit, Verfügbarkeit und Compliance | +| Banking-Anbieter/Einwilligung und Datenfeldumfang | Vor Banking-Funktion | Technische und rechtliche Realisierbarkeit | + +**Bewusst nicht jetzt vertiefen:** generisches Plugin-Sandboxing für UI-Code, universelle Editor-DSL, vollautomatisches Daten-Mirroring, jede mögliche Synchronisationskonfliktklasse, universelle KI-Workflow-Engine, zentraler Lizenz-/Billingdienst. + +## 14. Status- und Entscheidungsspur + +**Festgelegt in der aktuellen Unterhaltung (einschließlich Entscheidungen nach v0.1):** Dualer Betriebsansatz Self-Hosted/SaaS; Hybrid mit lokaler Runtime als bevorzugte Richtung; Daten überwiegend in Quellen; vollständige berechtigte Navigation/Suche; Rechte aus Quellsystem und Tsumugu; individuelle und gemeinsam verwaltete Quellzugänge; unterschiedliche Connector-Fähigkeiten; generische UI vor Connector-Frontend-Code; eigene Notizen/selektive Metadaten in Tsumugu; zeitweise Textverarbeitung; Referenzen und dynamische Sammlungen; explizite Referenzen trotz Ordnerwechsel; IMAP `.eml`-Archivmodi mit `automatic` als Standard, Archiv ausschließlich lokal; Quellmetadaten im Quellsystem editieren, eigene Tsumugu-Felder getrennt; standardmäßig referenzierte Ressourcen und dynamische Sammlungen aktualisieren, Vollindex optional; Banking zunächst read-only, keine gesamte Buchungshistorie standardmäßig, nur zugeordnete Buchungsreferenzen/-metadaten persistent; KI-Processing mit Text, Bild, PDF und strukturierten Daten sowie lokalen/externen Anbietern; bestehende OCR bevorzugt, multimodale PDF-/Bildinterpretation möglich; sechs grundlegende KI-Aufgaben, kombinierbare Verarbeitungsschritte, Wiederverwendung mit Herkunft/Prüfstatus; Ergebnisse lokal **oder** zentral nach Policy speicherbar; separate Datenfreigabe für externe Verarbeitung; ausdrücklicher SaaS-Schalter zum vollständigen Verbot dauerhafter Cloud-Speicherung von Dokumentinhalten und KI-Artefakten; Storage mit Artifact-Ablage, Integrität, Retention und Result Management. + +**Architekturvorschläge, noch keine eigenständigen Beschlüsse:** Namen der logischen Objekte und APIs; konkrete UI-Deklarationsstruktur; drei konkrete Betriebsvarianten als technische Deployments; technischer Umsetzungsplan; Cache-TTLs, Protokolle und Feldlisten; optionale Sticky-Sammlung; konkrete API-Signaturen und Speichertechnologien, Verschlüsselungs-/Schlüsselimplementierung und Retrieval-/Verfügbarkeits-SLOs. + +**Dokumentpflege:** Jede neue Entscheidung soll gezielt im betroffenen Abschnitt und in dieser Entscheidungsspur ergänzt werden. Keine stillschweigende Umdeutung der Tsumugu-Produkt-Baseline oder Erhebung einer Tsumugu-Lösung zum allgemeinen Jinkendo-Standard. diff --git a/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md b/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md new file mode 100644 index 0000000..8de80df --- /dev/null +++ b/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md @@ -0,0 +1,48 @@ +# Ergänzung zum Cursor-Auftrag: vollständige Connector-Kapselung + +**Stand:** 19.10.2026 · **Verbindliche Präzisierung aus dem aktuellen Nutzerauftrag** +**Vorgesehener Ort:** `C:/Dev/tsumugu/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md` + +Diese Ergänzung präzisiert Abschnitt A des Connector-/Storage-Auftrags und den technischen Vertrag v0.1. Sie hat Vorrang vor Formulierungen, die einen nur teilweise integrierten Zwischenstand als Abschluss zulassen. Laufende geeignete Implementierungen weiterverwenden; kein Neustart und keine vollständige Neuspezifikation. + +## 1. Erwartetes Ergebnis + +Ein funktionierendes Tsumugu mit vollständig integrierten, standardisiert angebundenen Paperless-/IMAP-Connectoren und gekapselter eigener Dateiablage. Neue Connectoren müssen durch ein eigenes Modul, Registrierung und gegebenenfalls eigene UI-Ergänzungen hinzukommen können. Der normale Erweiterungsweg verlangt keine Änderungen an Akten-/Vorgangslogik, generischen Lesern, Berechtigungslogik oder Exportabläufen. + +Der private Ersteinsatz begrenzt den benötigten Funktionsumfang. Er rechtfertigt keine verbliebenen Quellsonderfälle im allgemeinen Anwendungscode. Erweiterte Paperless-Suche, neue MD-Dateischreibfunktionen, Remote-Runtime, produktive Verschlüsselung und KI bleiben die bereits ausgewiesenen späteren Funktionsausbauten. Die technische Anbindung der heute unterstützten Funktionen wird in Abschnitt A vollständig abgeschlossen. + +## 2. Vollständige Kapselung + +**Connector-Modul:** Manifest, Konfiguration und Validierung, Verbindungsprüfung, Navigation/Suche, Mapping, Ressourcenauflösung, Metadaten, Vorschau, Original-/Anlagenabruf, Fehlerübersetzung und angebotene Schreiboperationen gehören zum zuständigen Modul. Fähigkeiten müssen die tatsächlich ausführbaren Operationen beschreiben. Nicht vorhandene Funktionen bleiben ausdrücklich nicht verfügbar. + +**Generischer Anwendungsdienst:** Verifizierte Identität, Datenraum, Handlungskontext, Objekt-/Freigaberechte und DataPolicy steuern alle Operationen. Connector und Quellidentität können weiter einschränken. Weder Quelle noch UI dürfen eine globale Freigabe oder einen Rechtebypass einführen. Bestehender Owner-vermittelter Einzelabruf bleibt erhalten, ohne Suchrechte auf den übrigen Quellenbestand zu erzeugen. + +**UI-Modul und Standardkomponenten:** Gemeinsame Hüllen für Verbindung, Browser/Auswahl, Vorschau, Übernahme und Editorzustände müssen integriert funktionieren. Quellenspezifische Filter, Navigation, Metadatenansichten und besondere Leser/Editoren sind registrierte Ergänzungen im jeweiligen Modul. Die bestehenden visuellen Regeln bleiben erhalten. Das bloße Registrieren zweier weiterhin speziell in Fachseiten verdrahteter Picker genügt nicht. + +**Generische Leser und Export:** Verfügbare Repräsentationen, Metadaten und Operationen kommen aus den Verträgen. PDF, Bild, Mail, Text oder Markdown werden über registrierte Darstellungen ausgewählt. Kein Quellname bestimmt im allgemeinen Reader, welchen Spezialendpunkt er direkt aufruft. Export, Anlagen und Versandnachweise verwenden denselben autorisierten Inhaltszugriff. + +**Storage:** Eigene Uploads, Originaldownloads aus eigenem Speicher und Versandfassungen verwenden den Storage-Vertrag. Direkte Pfad-/Dateioperationen außerhalb des zuständigen Ablageadapters werden bereinigt. Aktuelle Rechte, Inhaltsrevisionen, Speicherfehler und spätere Schlüsselzuständigkeit bleiben berücksichtigt. Eine bloße Schnittstelle neben weiter aktiven alten Dateipfaden erfüllt die Lieferung nicht. + +## 3. Wo Quellkenntnis zulässig ist + +Quellnamen und Protokolldetails sind zulässig im jeweiligen Connector-/UI-Modul, seinen Tests, der expliziten Registrierung, gezielten historischen Migrationen und der Dokumentation. Der Composition Root darf die verfügbaren Module registrieren. Generische Fachseiten, zentrale Schemas, Datenbank-Prüflisten, Reader oder Export dürfen keine Liste aller Connector-Typen kennen müssen, die bei jeder weiteren Quelle erweitert werden muss. + +Die einmalige Umstellung auf Registry-basierte Typvalidierung gehört zu diesem Schnitt. Unbekannte Typen und Fähigkeiten werden geschlossen abgewiesen. Quellenspezifische Konfigurations- und Anfragefelder validiert das registrierte Modul. Eine Registrierung ersetzt keine fachlichen Berechtigungen. + +Altrouten dürfen während der Migration auf den neuen Dienst delegieren. Bei Abschluss dürfen sie nur dokumentierte Kompatibilitätshüllen ohne eigene Protokoll-, Rechte- oder Ressourcenauflösungslogik sein. Unbenutzte Altpfade und doppelte aktive Implementierungen entfernen. Eine Textsuche nach Quellnamen allein beweist weder Vollständigkeit noch einen Fehler; Fundstellen nach ihrer Verantwortung beurteilen. + +## 4. Konkrete Abschlussnachweise + +1. **Bestehendes System:** Paperless und IMAP tatsächlich über die neue Anbindung bedienen: einrichten/prüfen, navigieren/suchen im heute unterstützten Umfang, auswählen, vor beziehungsweise nach Einbindung wie unterstützt lesen, einbinden, herunterladen und exportieren. Dateien, Notizen, Anlagen, Unterkapitel und gesicherte Versandstände funktionieren weiterhin. Keine neuen Sackgassen oder nur nominell verfügbaren Fähigkeiten. +2. **Weiterer Connector:** In der isolierten Testumgebung einen kleinen dritten Source-Adapter ergänzen. Er liefert Testkonfiguration, Suche/Navigation, Metadaten, Textvorschau und Originalabruf über Standardkomponenten. Einbinden, erneutes Öffnen und Export funktionieren. Dafür nur das Testmodul und seine Backend-/Frontend-Registrierung hinzufügen; keine Änderung an Fachseiten, zentralen Quell-Enums, Reader oder Export. Kein dritter produktiver Dienst und keine eigens für den Test gebaute Sonderoberfläche. +3. **Erweiterungsweg dokumentieren:** Die für diesen Test tatsächlich geänderten Dateien auflisten. Daraus eine kurze Anleitung für einen neuen Connector ableiten. Zusätzliche Ressourcenformate dürfen neue registrierte Darstellungen benötigen; das ist von einem Source-Adapter mit bereits unterstützten Formaten zu unterscheiden. +4. **Rechte:** Quelle, Kontext und Operation manipulieren; fehlende Quell-/Objekt-/Freigaberechte und Entzug prüfen. Ein nicht freigegebener Inhalt bleibt auch über Preview, Downloads und Export geschützt. Eine nicht unterstützte Schreiboperation wird serverseitig verweigert. +5. **Storage und spätere Schlüssel:** Zwei Storage-Adapter gegen denselben Vertrag prüfen; bestehende Referenzen bleiben stabil. Ein gesperrtes Schutzprofil wird nicht serverseitig als Klartext geöffnet. Dies ist ein Vertragsnachweis, kein Nachweis implementierter Verschlüsselung. +6. **Migration und Betrieb:** Bestands-IDs, Dateien und Referenzen erhalten; doppelte Quell-IDs verschiedener Instanzen korrekt auflösen; mehrdeutige Altreferenzen sicher behandeln. Relevante Tests und Build bestehen. Keine produktiven Datenbanken für Tests ändern. +7. **Reststellenprüfung:** Quell-/Storage-Sonderfälle im allgemeinen Anwendungscode gezielt suchen, einordnen und bereinigen. Abschließend kurze Fundstellenliste der verbleibenden, zulässigen Quellkenntnis liefern. Keine umfassende neue Repositoryinventur. + +## 5. Übergabe und Aufwand + +Bestehende Implementierung gegen diese Kriterien prüfen und nur die belegten Lücken schließen. Keine zusätzlichen Fähigkeiten zur Erfüllung abstrakter Vollständigkeit erfinden. Tests gezielt erweitern; bestandene Prüfungen nur bei neuen Änderungen oder ungelösten Fehlern erneut breit ausführen. In einer kompakten Abschlussmatrix pro Kriterium Nachweis, Ergebnis und verbleibende Grenze nennen. + +Wenn ein Kriterium technisch blockiert ist, den konkreten Blocker und seine Auswirkung benennen. Einen teilweise gekapselten Stand nicht als fertige Basis deklarieren. Diese Ergänzung autorisiert keinen Push, kein Deployment und kein Kontaktieren anderer Sessions. diff --git a/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md b/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md new file mode 100644 index 0000000..c1cf85b --- /dev/null +++ b/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md @@ -0,0 +1,46 @@ +# Abschlussmatrix der Connector-Kapselung + +**Stand:** 19.10.2026. Die Kriterien stehen in [TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md) und haben Vorrang vor dem Zwischenstand in [TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md](TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md). + +Kein Push und kein Deployment. Die Suite lief gegen `tsumugu_local_test`: **71 Tests, Exitcode 0**. Der Produktionsbau des Frontends ist durchgelaufen. Paperless und IMAP sind in den Tests nachgebildet. Es gab keinen Abruf einer lebenden Anlage. + +## Matrix + +| Kriterium | Nachweis | Ergebnis | +|---|---|---| +| Bestehendes System über die neue Anbindung | Suite, darunter `test_connector_basis.py`, `test_owner_sources.py`, `test_export.py`, `test_mailboxes.py`, `test_correspondence.py` | Bestanden. Einrichten, Prüfen, Suche und Fachnavigation, Lesen, Einbinden, Download und Export laufen über die registrierten Module. Dateien, Notizen, Anlagen, Unterkapitel und Versandfassungen bleiben in derselben Suite grün. | +| Vollständige Kapselung | `sourceregistry.py`, `sources.py`, generische Routen in `api/sources.py`, Reader über `preview.media` | Bestanden für die heute unterstützten Formate. Fähigkeiten beschreiben die ausführbaren Operationen. Nicht erklärte Filter und unbekannte Arten antworten `422`. | +| Weiterer Connector | `backend/tests/test_sample_source.py` | Bestanden. Der Testadapter `sample` sucht, zeigt Text, bindet, öffnet die Bytes erneut und exportiert sie. Fachseiten, Schema, Reader und Export enthalten die Art nicht. | +| Erweiterungsweg | dieselben Testdateien und `frontend/src/sources/sample-source.js` | Bestanden. Anleitung unten. Kein dritter produktiver Dienst und keine Sonderoberfläche. | +| Rechte | derselbe Test plus die bestehende Owner-Suite | Bestanden. Fremder Abruf ist 404. Ohne `use_owner_sources` bleibt das Original unerreichbar. Mit der Freigabe liefert der Zugang des Owners nur diese Referenz. Nach Entzug wieder 404. Eine Notizbearbeitung der Referenz ist serverseitig `unsupported`. | +| Storage und Schutzprofil | `test_connector_basis.py` | Bestanden als Vertragsnachweis. Zwei Adapter, stabile Referenzen, gesperrtes Profil ohne Klartext. Keine implementierte Verschlüsselung. | +| Migration und Betrieb | Migration `20261019T150000Z_source_registry.sql`, bestehende Bestandsfälle, Frontend-Build | Bestanden. Prüflisten der Arten sind entfernt. Produktive Datenbanken wurden nicht verwendet. | +| Reststellen | gezielte Suche in Fachseiten, Reader, Export, Schema und Ablage | Bereinigt, soweit die Fundstelle eine Typenliste war. Zulässige Fundstellen stehen unten. | + +## Anleitung für einen neuen Connector + +Für den Nachweis wurden nur diese Dateien neu angelegt: + +- `backend/tests/sample_source.py` registriert das Modul im Testprozess und wieder ab. +- `backend/tests/test_sample_source.py` prüft Konfiguration, Suche, Vorschau, Einbindung, erneutes Öffnen, Export und Rechte. +- `frontend/src/sources/sample-source.js` trägt dasselbe Modul in die Oberflächenregistrierung ein. Die Anwendung importiert diese Datei nicht. + +Ein produktiver Connector folgt demselben Schnitt: + +1. Ein Modul liefert Konfiguration, Prüfung, Suche, optional Navigation und Vorschau, Originalabruf und Export. `register_source` hängt es im Composition Root ein. +2. Die Fähigkeiten nennen nur Operationen, die das Modul ausführt. Die generische Suche lehnt andere Filter ab. +3. Die Oberfläche ruft `registerSourceModule` auf. Ohne eigenes Formular oder ohne eigene Auswahl gilt die Standardhülle. `manual` erlaubt die schlichte Referenzerfassung. Eine bereits unterstützte Darstellung (`pdf`, `image`, `text`, `email`) braucht keinen neuen Reader. +4. Ein bisher nicht dargestelltes Format braucht eine neue registrierte Darstellung. Das ist kein Eingriff in Akten, Vorgänge oder den Exportablauf. +5. Die Art kommt nicht in eine Datenbankprüfliste und nicht in ein zentrales Enum. + +## Zulässige verbleibende Quellkenntnis + +- Protokoll, Konfiguration und Auswahl von Paperless und IMAP in `backend/app/sources.py` und `frontend/src/pages/Sources.jsx`. +- Kompatibilitätsrouten `/api/v1/sources/paperless/documents` und `/api/v1/sources/imap/*`. Sie delegieren an dieselbe Suche, Navigation und Vorschau. +- Die Darstellung `email` liest über die bestehenden Mail-Endpunkte. Deren Bytes liefert heute das IMAP-Modul. Eine weitere Quelle mit den Darstellungen `pdf`, `image` oder `text` braucht diese Endpunkte nicht. +- Historische Migrationen, Testdoubles und die Dokumentation. +- Der Paperless-Dateizugriff auf ein lokales Archiv bleibt im Connector-Modul. Eigene Uploads und Versandfassungen schreiben über den Storage-Port. Die Anfrage räumt danach nur Pfade ab, die der Adapter selbst veröffentlicht hat. Die Fixture-Bereinigung löscht Bestandsdateien an derselben Objektkennung. + +## Grenzen + +Die Anfrage-Transaktion umfasst weiterhin den Quellabruf und das lokale Schreiben. Zugangsdaten liegen als Klartext in `connectors.secret`. Es gibt keine neue Verschlüsselung, keine erweiterte Paperless-Suche, keinen Markdown-Dateieditor und keinen Remote-Speicher. Der Testadapter ist kein produktiver Dienst. Lebende Paperless- und IMAP-Anlagen wurden nicht geprüft. diff --git a/docs/product/TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md b/docs/product/TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md new file mode 100644 index 0000000..d0abc44 --- /dev/null +++ b/docs/product/TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md @@ -0,0 +1,62 @@ +# Tsumugu – Ergebnis der Connector-/Storage-Grundlage + +**Stand:** 19.10.2026. Dies ist der Zwischenstand vor den Abschlusskriterien. Maßgeblich für den Abschluss ist [TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md). Die Kriterien stehen in [TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md) und haben Vorrang vor Formulierungen, die eine teilweise Integration als Abschluss zulassen. + +Lokale Umsetzung von Abschnitt A aus [TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md](TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md) nach [TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md](../architecture/TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md). + +Das ist ein Implementierungsnachweis, keine neue Fachversion. F-02b und F-02c bleiben. Abschnitt B, also der vervollständigte Quellenbrowser, die erweiterte Paperless-Suche und ein Editor für Markdown-Dateien, ist nicht begonnen. + +Es gab keinen Push und kein Deployment. + +## Übernommene Dokumente + +Aus dem Paket `TSUMUGU_CONNECTOR_PLANUNG_2026-10-19.zip` liegen unverändert im Repository: + +- `docs/architecture/TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md` +- `docs/architecture/Tsumugu_Connector_Suite_Architektur_v0.2.md` +- `docs/architecture/TSUMUGU_STORAGE_SCHLUESSEL_PRUEFAUFTRAG_2026-10-19.md` +- `docs/product/TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md` + +Die Begleitdatei `README.md` im Paket ist ein Deckblatt und wurde nicht über die Projekt-README gelegt. Der Prüfauftrag an die Architektur-Session wurde nur abgelegt, nicht versandt. + +## Was die Grundlage jetzt tut + +- Paperless und IMAP sind registrierte Adapter über den bestehenden Protokollcode. Ein POST legt eine weitere Instanz an. Ein PATCH ändert Zugangsdaten derselben Id. +- Eine externe Referenz trägt `connector_id` ohne Fremdschlüssel und `resolution` (`bound`, `ambiguous`, `unresolved`, `none`). Dieselbe externe Nummer in zwei Instanzen bleibt getrennt. Ein gelöschter Zugang wird nicht auf eine andere Instanz umgehängt. Mehrdeutiger Bestand bleibt mehrdeutig, bis der Owner zuordnet. Ein eindeutiger Bestand wird beim Anlegen und einmalig im Backfill gebunden. +- Eine Suche ohne `connector_id` ruft bei mehreren eigenen Paperless-Instanzen die Quelle nicht auf. Nicht erklärte Filter antworten `422` mit Code `unsupported`. IMAP behält Fach, Stichwort und Fortsetzung über `before`. +- Ein Empfänger mit `use_owner_sources` liest das ausdrücklich freigegebene Original über den gebundenen Zugang des Owners. Zugangsdaten und die übrigen Treffer werden nicht ausgeliefert. Ohne diese Freigabe bleibt das Original unerreichbar. +- Eigene Dateien und Versandfassungen laufen über den lokalen Storage-Port. Die Referenz trägt Instanz, Generation, Objektkennung und Inhaltsrevision. Schutzprofil und Schlüsselzuständigkeit liegen daneben. Der Bestand ist `legacy-plaintext` mit Schlüsselzuständigkeit `none`. Ein anderer `MEDIA_ROOT` erzeugt eine neue Schreibgeneration und liest die alte Generation weiter an der gebundenen Wurzel. +- Profile `managed-encrypted` und `client-encrypted` liefern Metadaten und verweigern Klartext. Es gibt keine neue Verschlüsselung. Ein gespeicherter Dummy-Geheimtext, der unverändert zurückgelesen wird, ist kein Kryptographienachweis. +- Die Oberfläche hängt die vorhandenen Paperless- und E-Mail-Auswahlen an eine gemeinsame Registrierung. Der Notizeditor bleibt der bestehende PATCH. `markdown_file` ist erklärt und nicht angeboten. + +## Tests + +Backend-Suite am 19.10.2026 gegen die lokale Datenbank `tsumugu_local_test`: **69 Tests, Exitcode 0**. Eine DeprecationWarning aus Starlette/anyio, kein Fehlschlag. Die sieben neuen Fälle in `backend/tests/test_connector_basis.py` prüfen Adapter-Rundlauf und Pfadabwehr, einen Wurzelwechsel ohne Umhängen, stabile Datei-Id und Bytes, die Ablehnung einer Notizbearbeitung an einer Datei, zwei Paperless-Instanzen mit derselben Nummer 15, eine Suche ohne Instanz ohne Quellaufruf, einen abgelehnten Korrespondent-Filter ohne Echo des Werts, mehrdeutigen Bestand bis zur Zuordnung, ein gesperrtes Profil ohne Klartext und einen PATCH, der die andere Instanz nicht verändert. + +Die bestehende Suite blieb in demselben Lauf grün, darunter Export, Kapitel, Rechte, Postfächer, Owner-Quellen und Versandfassungen. Paperless und IMAP sind in diesen Tests nachgebildet. Es gab keinen Abruf einer lebenden Paperless- oder IMAP-Anlage. Die Mocks belegen den Vertrag im Prozess, nicht die entfernte API-Fassung. + +## Oberfläche + +Der Produktionsbau des Frontends ist nach der Umbenennung der Registrierung nach `frontend/src/sources/registry.jsx` durchgelaufen. + +Zusätzlich lief die Anwendung lokal auf `127.0.0.1:8019` mit Vite auf `127.0.0.1:5173` gegen die weggeworfene Datenbank `tsumugu_browser_test`. Port 8000 war auf diesem Rechner schon belegt. Geprüft wurde: + +- die Quellenseite zeigt beide registrierten Formulare, „Paperless-Instanz verbinden“ und „Konto hinzufügen“ +- zwei Paperless-Instanzen und ein IMAP-Konto bleiben nebeneinander stehen +- „Zugang erneuern“ an Archiv Alpha sendet PATCH an dieselbe Id; das Secret der zweiten Instanz bleibt unverändert +- in der Akte verlangt die Paperless-Auswahl bei zwei Instanzen eine Wahl und nennt die heutige Stichwortgrenze +- die E-Mail-Auswahl zeigt das angelegte Konto, die IMAP-Grenze und bei einem unerreichbaren Beispielhost „Das Postfach ist nicht erreichbar“, ohne erfundene Fächer +- eine Notiz lässt sich anlegen und im Leser öffnen; nach einer zwischenzeitlich erhöhten Version antwortet das Speichern mit 409, der Satz „Der Stand hat sich geändert. Der eingegebene Text bleibt stehen. Bitte neu laden.“ erscheint, und der eingegebene Text bleibt im Feld +- bei 390 Pixel Breite bleiben Quellenseite und Leser ohne seitlichen Überlauf der Seite bedienbar + +Die Beispielhosts waren nicht die echten Quellen. Ein Vorgang wurde nicht separat angeklickt; er verwendet dieselbe Registrierung wie die Akte. + +Der Testlauf und die lokale Oberfläche benutzten eine temporäre Superuser-Rolle auf dem lokalen PostgreSQL. Diese Rolle und die Wegwerfdatenbank sind danach entfernt. Der bestehende Migrator setzt das Passwort von `tsumugu_runtime` auf das Passwort des verbindenden Owners. Damit dieses Testpasswort nicht liegen bleibt, wurde das Passwort der Runtime-Rolle lokal rotiert und nicht festgehalten. Der nächste Start mit dem Operatorpasswort setzt es wieder, wie im Datenmodell zu R-09 beschrieben. + +## Grenzen + +- Die anfragegebundene Datenbanktransaktion umschließt weiterhin den Quellabruf und das lokale Schreiben. Die Datei wird erst nach einem geprüften Rundlauf veröffentlicht, und ein Rollback entfernt die neue Datei. Das ist keine getrennte Transaktion von Datenbank und Dateisystem. +- Zugangsdaten bleiben Klartext in `connectors.secret` (Review R-05). Es gibt keinen Schlüssel-Tresor und keinen SaaS-Nachweis. +- Der Prüfauftrag zur Schlüsselhaltung wurde nicht an die Architektur-Session geschickt. +- Abschnitt B ist der nächste, getrennt zu startende Funktionsausbau. +- Der Befund R-10 beschreibt den früheren Zustand, dass der Betrachter seinen eigenen Zugang benutzte. Der Lesepfad folgt jetzt der dort empfohlenen Bindung an den Owner. Der Befundtext selbst wurde nicht umgeschrieben. diff --git a/docs/product/TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md b/docs/product/TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md new file mode 100644 index 0000000..311a522 --- /dev/null +++ b/docs/product/TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md @@ -0,0 +1,64 @@ +# Auftrag an Cursor – erste gemeinsame Connector-/Storage-Basis + +**Stand:** 19.10.2026 · **Status:** Vorbereiteter, begrenzter Umsetzungsauftrag. Durch Erstellung dieses Dokuments wurde keine Anwendung geändert. Übergabe an Cursor erteilt den Umsetzungsauftrag bis zur lokalen Prüfung. + +## Ziel und Grundlagen + +Arbeite in `C:/Dev/tsumugu`. Lies zuerst AGENTS.md, die aktuelle Fachspec, die Connector Suite v0.2 und `C:/Dev/tsumugu/docs/architecture/TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md`. Nutze die bestehenden Architekturverträge und Blueprints unter `C:/Dev/tsumugu/docs/reference`. Das Repository verwendet den Ordnernamen `reference` im Singular. + +Die Vertragsbeschreibung ist ein Umsetzungsvorschlag auf Basis der bestätigten Fachentscheidungen. Prüfe den aktuellen Code erneut. Erhalte bestehende Fremdänderungen, Fachmodell und ausgewählte Gestaltung. Vorhandene Paperless-/IMAP-Protokollarbeit, Medienablage, Reader und Notizeditor wiederverwenden. Keine neue Foundation oder parallele Connector-Anwendung. + +## Lieferpaket + +Primäres Ziel ist die belastbare Grundlage für die fortlaufende private Nutzung. Der Auftrag wird in zwei getrennt prüfbare Lieferabschnitte gegliedert. Zuerst Abschnitt A fertigstellen und lokal übergeben. Abschnitt B ist der vorbereitete nächste Funktionsausbau und wird durch diesen Basisauftrag nicht automatisch mitimplementiert. Es werden weder neue Plattformdienste noch ungenutzte Fachmodule auf Vorrat angelegt. + +### Abschnitt A – jetzt beauftragt: Grundlagen bei erhaltener Funktion + +1. Gemeinsamen Source-Vertrag und registrierte Adapter für Paperless und IMAP integrieren. Konkrete Verbindung, Ressource, Operation, Rechte und Fehlerzustand durchgängig erhalten. +2. Eigene Dateiablage und gesicherte Versandfassungen an einen kleinen Storage-Port mit lokalem Adapter anbinden. Bestandsdateien ohne Neu-Upload erhalten. Storage-/Inhaltsrevision und Schlüsselzuständigkeit gemäß Vertrag trennen. +3. Gemeinsame Frontend-Zugriffsschicht und Registry für Quell-/Darstellungsbausteine einführen. Bestehende Picker/Formulare als registrierte Quellmodule weiterverwenden. Gemeinsame Hüllen und Auswahl-/Zielkontextverträge gezielt herausziehen; eine vollständige Neugestaltung sämtlicher Dialoge ist nicht erforderlich. +4. Reader nach Darstellungsart anbinden; vorhandene Notizbearbeitung erhalten und ihre Speichern-/Konfliktzustände hinter der gemeinsamen Editor-Anschlussstelle führen. Die bestehende Notiz-API bleibt der fachliche Speicherweg für Notizen. Noch nicht vorhandene Editorarten werden nicht als nutzbar angeboten. +5. Typisierte Such-, Filter-, Sortier- und Paging-Verträge mit ausgewiesenen Fähigkeiten definieren. Die heutige Suche darf durch den Umbau keine Funktion verlieren; zusätzliche Filter werden in Abschnitt B geliefert. Ein gemeinsames Interface bedeutet keine vorgetäuschte Verfügbarkeit. +6. Vorschau, Originaldownload, Export, Anlagen und Versandnachweise über dieselbe autorisierte Ressourcenauflösung führen. Keine spontane Auswahl eines anderen Quellenzugangs. Bibliotheks-/Frameworkmigrationen sind kein Teil der Grundlagenlieferung. + +### Abschnitt B – nächster, separat zu startender Funktionsausbau + +Gemeinsamen Quellenbrowser einschließlich Preview-vor-Übernahme vervollständigen. Paperless-Suche um Freitext/Titel, Korrespondent, Dokumenttyp, Tags, Dokumentdatumsbereich, Sortierung und weitere Ergebnisseiten erweitern. Konkrete API-Fähigkeiten gegen die eingesetzte Version prüfen. Mehrfachauswahl über Such-/Seitenwechsel erhalten. Dies ist bestätigter Ausbaubedarf, aber keine Abnahmevoraussetzung für Abschnitt A. Ein neuer MD-Dateieditor ist ein weiterer eigener Schnitt. + +Beginne mit einer kurzen Bestands- und Aufwandsnotiz für diesen Schnitt; die alte Schätzung von 6–9 Tagen gilt nicht automatisch für diesen erweiterten Auftrag. Geplante und bereits vorhandene Funktionen unterscheiden. Eine erneute vollständige Produktspezifikation ist nicht erforderlich. + +## Migration und Schutz + +Bestehende Elemente, Einbindungen, Kapitel, Inhaltsdaten und Rechte erhalten. Eindeutige Quellinstanzen nachziehen; Mehrdeutigkeiten markieren und bewusst auflösen lassen. Rohdaten nicht kopieren, um Referenzen zu vereinfachen. Keine globale automatische Zusammenführung anhand externer ID oder Hash. + +Bestehende Medien- und Snapshotdateien zunächst unter stabiler Legacy-Speichergeneration lesbar machen. Metadatenmigration genügt, wo kein physischer Umzug nötig ist. Neue Repräsentationen werden erst nach geprüftem Speichererfolg veröffentlicht. Fehlgeschlagene oder wiederholte Abläufe dürfen keine falschen Erfolgsmeldungen oder stillen Verluste erzeugen. + +Keine Netzwerk-/großen Dateioperationen in offener Fachtransaktion. Aktuelle Rechte und Version vor Abschluss erneut prüfen. Quellcredentials bleiben im zuständigen Adapter. Befunde zu bestehender Credential-Speicherung und Schlüsselverwaltung ausdrücklich in der Aufwands-/Grenzennotiz behandeln; daraus keine behauptete SaaS-Reife ableiten. + +Die erste Lieferung aktiviert keine neue Kryptografie. Sie muss den späteren Content-/Crypto-Zugriff über die festgelegte Grenze ermöglichen und unbehandelte Schutzprofile geschlossen ablehnen. Eine verschlüsselte Ablage darf erst nach dem gesonderten Schlüssel-/Recovery-Prüfergebnis und einem dafür konkretisierten Implementierungsauftrag aktiviert werden. + +## Konkrete Abnahme + +Mit synthetischen Daten und getrennten Testdatenbanken prüfen: + +1. **Bestand:** PDF/Fotos, Notizen, Unterkapitel, geordnete Anlagen, Versandfassungen und Export bleiben nach Migration nutzbar. Vorhandene IDs und Originalbytes sind erhalten. +2. **Instanzbindung:** Gleiche Dokumentnummer in zwei simulierten Paperless-Instanzen führt zu korrekten, getrennten Auflösungen. Änderung der Verbindungsreihenfolge lenkt Referenzen nicht um. Mehrdeutiger Altbestand bleibt vorhanden und verlangt Zuordnung. +3. **Suche:** In Abschnitt A die heutige Suche und instanzgebundene Anfrage-/Ergebnisverträge prüfen; nicht implementierte Fähigkeiten korrekt ausweisen. Für Abschnitt B: mindestens 45 synthetische Treffer über mehrere Seiten, kombinierte Grundfilter und Sortierung prüfen, Treffer hinter Seite eins vor Einbindung öffnen. Suchwechsel erhält bewusst gewählte Ressourcen; fehlende Rechte verraten keine Titel oder Zähler. +4. **IMAP:** Ordnernavigation, Paging, Nachricht, Anlagen, eindeutige Wiedererkennung bei Verschiebung sowie klare Fehler bei fehlender/mehrdeutiger Nachricht erhalten. +5. **Owner-Abruf:** Berechtigter Empfänger liest ausdrücklich freigegebene Unterlagen über den erlaubten Owner-Zugang. Er bekommt weder Credentials noch Suchzugriff auf dessen übrigen Bestand. Entzug wirkt beim nächsten Abruf. +6. **UI:** Beide vorhandenen Auswahlwege über die neue gemeinsame Zugriffsschicht tatsächlich bedienen. Zielcontainer, Kapitel und Handlungskontext bleiben korrekt. Desktop und 390/360 px, Tastatur, Dialogfokus/-rückkehr, Abbruch sowie Fehler beim Speichern/Einbinden prüfen. Der vollständig vereinheitlichte Quellenbrowser wird zusätzlich in Abschnitt B abgenommen. +7. **Anzeige/Editor:** PDF/Bild und E-Mail korrekt anzeigen; Markdown-Notiz bearbeiten und Versionskonflikt behandeln. Nicht unterstützte Editierfähigkeit wird klar angezeigt und serverseitig verweigert. Keine künstliche MD-Dateibearbeitung durch Umwandlung in eine Notiz. +8. **Storage-Vertrag:** Lokalen Adapter und einen kleinen Testadapter gegen denselben Vertrag prüfen. Opaque Bytes roundtrip, stabile Generation, Fehlerzustände und unveränderte Inhaltsrevisionen belegen. Der Testadapter ist kein zweiter produktiver Speicherdienst. +9. **Vorbereitung kundenseitiger Schlüssel:** Ein gesperrtes/noch nicht unterstütztes Schutzprofil erlaubt Metadatenanzeige nach Recht, aber keinen stillen serverseitigen Klartextabruf. Dummy-Ciphertext unverändert speichern/lesen. Aus diesem Test keinen Verschlüsselungsnachweis ableiten. +10. **Fehlerfälle:** Speicherfehler, DB-Abschlussfehler, Wiederholung, Quellausfall, Fremd-IDs, Pfadmanipulation und veraltete Bearbeitung abdecken. Veröffentlichung erst nach verifiziertem Erfolg; verwaiste Zwischenstände nachvollziehbar bereinigen. +11. **Export:** Hierarchische Auswahl und vollständige EML samt Anlagen erhalten, auch bei separat abgewähltem Anlage-Vorkommen. Gesicherte Versandstände dürfen durch aktuelle Quellstände nicht ersetzt werden. + +Passende vorhandene Backend-Tests weiterverwenden und gezielt ergänzen. Frontend-Build und erforderliche UI-Prüfungen ausführen. Reale Quellenrechte/API-Version in einer abschließenden, ausdrücklich autorisierten Anschlussprüfung bestätigen; Mocks und tatsächliche Quellenprüfungen im Bericht unterscheiden. Keine privaten Daten in Screenshots oder Logs übernehmen. + +## Dokumentation und Abschluss + +Nach tatsächlicher Änderung die Fachspec gezielt fortschreiben; bestätigte Nutzerentscheidungen, Vorschläge und Implementierungsnachweise unterscheiden. F-02b/c bleibt erhalten: Die erste Source-Lieferung ist lesend und hebt die frühere Feldsynchronisationsanforderung nicht auf. `API_REFERENZ.md`, `DATENMODELL_IST.md`, `RECHTEMODELL_IST.md` und betroffene technische Beschreibung im selben Schnitt aktualisieren. Neue Dokumente in `docs/README.md` und der Planungsübergabe verlinken. + +Liefere Abschnitt A lokal integriert mit tatsächlichen Testergebnissen, wesentlichen Abweichungen und verbleibenden Grenzen. Benenne Abschnitt B ausdrücklich als nächsten Funktionsausbau. Alte Quellenwege nur während der Migration als delegierende Kompatibilität behalten; keine dauerhafte doppelte Fachlogik. Quellenspezifische registrierte UI-Komponenten sind zulässig, solange die Fachseiten die gemeinsamen Verträge verwenden. + +Nicht enthalten: produktiver Hybridkanal, Browser-Schlüsseltresor, neue Verschlüsselungsimplementierung, automatische EML-Archivierung, Dateisystem-/NAS-Source, neue MD-Dateischreibfunktion, dynamische Sammlungen, neue Paperless-Metadaten-Schreib-/Synchronisationsfunktion, Banking oder KI. Diese Anforderungen bleiben im Zielbild erhalten. Kein Push, Deployment, Versand oder Änderung anderer Jinkendo-Produkte. diff --git a/docs/product/TSUMUGU_PRODUCT_SPEC.md b/docs/product/TSUMUGU_PRODUCT_SPEC.md index 49be26c..16e55cf 100644 --- a/docs/product/TSUMUGU_PRODUCT_SPEC.md +++ b/docs/product/TSUMUGU_PRODUCT_SPEC.md @@ -19,6 +19,8 @@ Diese Datei sichert bestätigte Anforderungen, den Quellenabgleich und das näch **Kennzeichnung in dieser Datei:** Bestätigt = aktueller Nutzerauftrag oder direkt lesbare ursprüngliche Nutzeraussage; Rekonstruktion = nur durch Recovery belegt; Vorschlag = neue Empfehlung ohne Freigabe; Offen = noch zu entscheiden. Technische Discovery-Vorschläge werden nicht zu Fachanforderungen erhoben. +**Implementierungsnachweis 19.10.2026, ohne neue Fachversion:** Die lesende Connector-/Storage-Grundlage ist lokal umgesetzt. Das ist ein Implementierungsnachweis zum Vertrag v0.1, keine neue bestätigte Produktentscheidung und keine Aufhebung von F-02b oder F-02c. Die erste Source-Lieferung bleibt lesend. Bidirektionale Feldsynchronisation, erweiterte Paperless-Suche und der vervollständigte Quellenbrowser sind der nächste, separat zu startende Funktionsausbau. Die Abschlusskriterien in [TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md) haben Vorrang vor einem nur teilweise integrierten Zwischenstand. Nachweis, Grenzen und die Matrix stehen in [TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md). Der frühere Zwischenstand bleibt in [TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md](TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md). + ## 2. Gesicherter fachlicher Kern **Bestätigt durch aktuellen Auftrag und/oder ursprüngliche Nutzeraussagen:** diff --git a/docs/product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md b/docs/product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md index 91fa6f7..ec4b998 100644 --- a/docs/product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md +++ b/docs/product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md @@ -1,5 +1,7 @@ # Tsumugu – Übergabe zur fachlichen Weiterplanung +**Nachtrag 19.10.2026:** Die Connector-/Storage-Grundlage ist gegen die Abschlusskriterien geschlossen. Die Matrix steht in [TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md). Abschnitt B, der vervollständigte Quellenbrowser und die erweiterte Paperless-Suche, bleibt der nächste separate Funktionsausbau. F-02b und F-02c bleiben erhalten. Der übrige Text dieser Übergabe beschreibt den Stand vom 17. und 18.10.2026. + **Stand:** 17.10.2026 · **Zweck:** Einstieg in einen neuen fachlichen Planungschat nach Auswahl des Designkonzepts. Keine neue Produktentscheidung und kein zusätzlicher Implementierungsauftrag. ## 1. Aktueller Auftrag und Arbeitsweise diff --git a/docs/reference/Jinkendo_AI_Gateway_Provider_Privacy_Blueprint.md b/docs/reference/Jinkendo_AI_Gateway_Provider_Privacy_Blueprint.md new file mode 100644 index 0000000..f0124e8 --- /dev/null +++ b/docs/reference/Jinkendo_AI_Gateway_Provider_Privacy_Blueprint.md @@ -0,0 +1,602 @@ +# Jinkendo – KI-Gateway, Providerzugriff & Privacy Blueprint + +**v0.1 · 16.10.2026 · Spezial-Blueprint 2 nach Phase 3.3 · technischer Entwurf, keine Implementierung** + +## 1. Geltung und Nachweis + +Dieser Blueprint beschreibt den produktlokalen Übergang von autorisiertem Anwendungskontext zu einem KI-Modell und zurück. Er konkretisiert Providerrollen, Datenminimierung, vollständige Egressprüfung, Maskierung, Transport, Antwortvalidierung und Fehlerbehandlung. Primäres Vorbild ist Kanshōs Privacy Gateway. Mitais Prompt-/Platzhalter-/Workflow-System bleibt die primäre vorgelagerte Laufzeit; dessen eigener Spezial-Blueprint folgt gesondert. + +Grundlage sind [Referenzarchitektur A v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md), [Foundation B v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md), [Entscheidungen C v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md), [Auth-/Session-/Scope-Blueprint](C:/Dev/jinkendo-phase3-3-auth-session-scope-blueprint-2026-10-16/Jinkendo_Auth_Session_Scope_Blueprint.md) und [Release-/Betrieb-/Recovery-Blueprint](C:/Dev/jinkendo-release-betrieb-recovery-blueprint-2026-10-16/Jinkendo_Release_Betrieb_Recovery_Blueprint.md). + +Beschlossene ADRs bleiben maßgeblich, besonders ADR-02/04/09/10/12/13/14. [ADR-09](C:/Dev/jinkendo-architecture-consolidation-phase2-v0.2-2026-10-15/05_Architecture_Decision_Register.md) erlaubt produktbezogen lokale Verarbeitung oder autorisierte minimierte Weitergabe an geeignete Anbieter. Er erteilt keine pauschale Providerfreigabe und schwächt Kanshōs eigene Privacy-Invarianten nicht ab. Dieser Blueprint trifft keine neue rechtliche Bewertung und aktiviert keinen Anbieter. + +**Nachweis:** V = vorgeschlagene technische Ausgestaltung; I = vorhandene statisch nachgelesene Implementierungsreferenz; T = tatsächlich bestandener Test mit Stand, Umfang und Umgebung; K = noch nicht integrierte/getestete Kombination. Dieses Dokument samt Code-/Payloadbeispielen ist **V/K**. Produktquellen und Testassertionen sind I; es wurden keine Anwendungstests oder Modellaufrufe ausgeführt. Keine Produktionsreife und keine vollständige semantische Erkennung werden behauptet. + +Es entstehen keine gemeinsame KI-Plattform, zentrale Tenant-Datenbank, SSO-, Billing- oder Worker-Infrastruktur. Bestehende Anwendungen bleiben unverändert. Die tatsächliche spätere Umsetzung betrifft nur ein ausdrücklich benanntes Zielrepository. + +### 1.1 Verträge und Defaults + +| Verbindlicher Vertrag | Bevorzugter technischer Default | +|---|---| +| Nur aktuell autorisierte Daten aus dem expliziten Scope, für registrierten Zweck | Produktlokaler `ModelGateway`; pro Anfrage materialisierter unveränderlicher Kontext | +| Class-A-/Local-only-Inhalte verlassen ihre erlaubte Vertrauenszone nicht | Externe Generate-Aufrufe mit Klasse A verweigern; B minimieren/maskieren; C kontrolliert generisch | +| Persönlicher Egress durchläuft die vollständige Pipeline; kein Direktaufruf oder Ausfallbypass | Kanshō-Manifest, lokale semantische Detection, bestätigte Registry und Prüfung des endgültigen Payloads | +| Detect, Generate und Tools sind getrennte Empfänger-/Zweckverträge | Lokaler explizit registrierter Detect-Endpunkt; externer Generate-Adapter nur bei geeigneter Route | +| Kein ungeprüftes Downgrade, kein Export lokaler Mappings oder Sessiondaten | Kein automatischer Modell-/Providerfallback, kein Remote-Klartext-Detect im neuen Standard | +| Anbieterfähigkeit wird belegt und technisch erzwungen, nicht aus einem Boolean geraten | Versionierte Providerprofile und Policybelege; OpenRouter als vorhandener Adapterkandidat | +| Kein Netzaufruf in offener Fachtransaktion; Audit und fachlicher Ergebniswrite atomar | Drei kurze DB-Phasen um lokale Verarbeitung/HTTP herum | +| Antwort bleibt untrusted; keine selbstständigen Tools/DBwrites | Vollständig gepufferte Text-/JSONantwort; lokale Validierung und Rehydration | +| Ressourcen und Mehrfachausführung begrenzt; unbekannte Kosten nicht null | Ein Generate-Versuch pro Call; persistente lokale Call-ID/Idempotenz; Verbrauchsport für nächsten Blueprint | + +Timeouts, Größen, Dateinamen, Transportadapter und Chunkgrößen sind begründet anpassbare Defaults. Datenraum-/Privacy-/Releaseverträge bleiben bestehen. Eine begründete lokale Anpassung mit passenden Tests erfordert keinen neuen ADR oder zusätzlichen allgemeinen Freigabezyklus. + +## 2. Vorhandene Mechanismen und gezielte Anpassung + +Ausgangspunkt sind [Phase-3.1-Wissenselemente](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json), [Quellen](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/sources.json), [Tests](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/tests.jsonl) und Kanshōs führende [Guardrails](C:/Dev/Kansho/docs/architecture/functional/guardrails.md:175). Nachgelesen wurden gezielt die relevanten Funktionen; keine neue Gesamtanalyse der Repositories. + +| Referenz I | Wiederverwenden | Erforderliche Zielanpassung V/K | +|---|---|---| +| Kanshō KI-KAN-09: [Gateway](C:/Dev/Kansho/backend/privacy_gateway.py:1044), [Maskierung](C:/Dev/Kansho/backend/privacy_gateway.py:705), [Pre-Egress-Gate](C:/Dev/Kansho/backend/privacy_gateway.py:1257) | Reihenfolge vor Modellaufruf, requestbezogenes Manifest, spanbasierte Ersetzungen und lokale Rückübersetzung | Alle tatsächlich versandten Nachrichten/Felder erfassen; keine nachträglichen ungescannten Ergänzungen; Snapshot-/Payloadbindung für vorab geprüfte Mappings | +| Kanshō: [Manifesttypen](C:/Dev/Kansho/backend/privacy_gateway.py:149), [Antwortprüfung](C:/Dev/Kansho/backend/privacy_gateway.py:897) | Aktive Ersetzungen, Alias-/Oberflächenformtrennung und interne Prüffassung | Mappings nur im lokalen Callkontext; ausschließlich tatsächlich ausgegebene/aktive Tokens rehydrieren, keine fremden/inaktiven Tokens nachschlagen | +| Kanshō KI-KAN-10: [Providerrollen](C:/Dev/Kansho/backend/providers.py:160), [Transport](C:/Dev/Kansho/backend/providers.py:242), [Profilprüfung](C:/Dev/Kansho/backend/provider_settings.py:48) | Getrennte Detect-/Generate-Konfiguration, kleiner HTTP-Adapter, Usage/Finishreason | Keine pauschale Vertrauensannahme für private IPs/`.local`; keine ZDR-Zusage aus lokalem Default; exakte Endpunkt-/Routenprüfung; keine Providerfehlertexte an Clients | +| Kanshō KI-KAN-11: [Kontextaufbau](C:/Dev/Kansho/backend/context_builder.py:67), [Budgetprüfung](C:/Dev/Kansho/backend/prompt_budget.py:243) | Zweckbezogene Materialisierung und explizite Größen-/Kontextgrenze | Zugriffs- und Quellenrevisionen binden; Zeichenschätzung nicht als exakten Tokenizer oder Privacybeweis behandeln | +| Mitai KI-MIT-09/10: [Promptausführung](C:/Dev/mitai-jinkendo/backend/prompt_executor.py:166), [Modellcallback](C:/Dev/mitai-jinkendo/backend/prompt_executor.py:290) | Übergabepunkt nach vollständiger Platzhalterauflösung/Frageergänzung | Callback ruft ausschließlich Gateway auf; keine direkte Providerclosure, aufgelösten Werte/Promptvolltexte nicht automatisch debuggen; JSONschema tatsächlich validieren statt nur JSON parsen | +| Shinkan KI-SHK-08: [REST-Client](C:/Dev/shinkan-jinkendo/backend/openrouter_chat.py:95), [Textblöcke](C:/Dev/shinkan-jinkendo/backend/openrouter_chat.py:50) | Kleiner Adapter statt zusätzlichem Agentenframework; bekannte Textvarianten | Refusal/Tool-/Reasoningblöcke unterscheiden; unbekannte Formen verweigern; keine Raw-HTTP-/Providerfehlerschnipsel weiterreichen | +| Kairo KI-KAI-14: [Secretreferenzprüfung](C:/Dev/kairo-jinkendo/backend/config_service.py:17) | Konfiguration ohne rohe Secretwerte | Produktlokaler Providerprofiladapter, keine eigene zweite Connection innerhalb der Fach-UoW übernehmen | + +Kanshō dokumentiert ausdrücklich, dass technische Detectionabdeckung keine semantische Vollständigkeitsgarantie ist und neue unbekannte Identitäten ungelöste Fälle erzeugen können. [Guardrails 22.2](C:/Dev/Kansho/docs/architecture/functional/guardrails.md:682). Bestehende Remote-Detect-/Lernmodusübergänge sind produktlokal dokumentierte Ausnahmen; der neue Standard übernimmt sie nicht automatisch. Er ändert sie im Bestand auch nicht. Kein `KANSHO_ALLOW_REMOTE_DETECT`- oder Fake-Provider-Runtimeflag wird als allgemeiner Familienmechanismus eingeführt. + +## 3. Komponenten und Schnitt zur Prompt-/Workflow-Laufzeit + +```text +Fachroute → Fachservice / ContextMaterializer → Prompt-/Workflow-Renderer + → ModelGateway + → PurposePolicy / aktuelle Accessprüfung + → vollständige Textinventur / Minimierung / Detect / Registry + → MaskingManifest / finale Payloadprüfung / DispatchPermit + → genau ein registrierter ProviderTransport + → Envelope-/Inhalts-/Schema-/Privacyprüfung / lokale Rehydration + → frische Autorisierung / Fachservice-Ergebniswrite oder sichere Ausgabe +``` + +| Baustein | Aufgabe | +|---|---| +| `modules/ai_gateway/service.py` | Gesamtablauf und Phasensteuerung; keine Prompt-DB-/Workflowengine neu entwickeln | +| `contracts.py`, `policies.py` | Typisierte Calls/Ergebnisse, Zweck-/Datenklassen-/Ausgabeverträge | +| `privacy/inventory.py` | Alle endgültigen Textkanäle und kontrollierten technischen Felder erfassen | +| `privacy/detect.py`, `mask.py`, `response.py` | Kanshō-Mechanismen angepasst an unveränderliche Calls und vollständige Abdeckung | +| `profiles.py`, `routing.py` | Aktuelle Profil-/Policyrevision, Empfängerrolle, Eignung und Capabilityprüfung | +| `transports/openrouter.py`, optional `local_detect.py` | Protokolladapter mit strengem Endpoint, Secretinjektion und begrenztem HTTP | +| `repository.py` | Callledger und Audit auf explizitem Transaktionshandle | +| Fach-/Promptadapter | Scoped Quellen materialisieren, Vorlage rendern, Outputtyp registrieren; Gateway konsumieren | + +`create_app(settings, providers)`/Lifespan der Foundation verdrahten diese Adapter. Nur Transportmodule dürfen Modell-HTTP ausführen. Direkte Provider-SDK-/HTTP-Aufrufe in Renderern, Feature-Routern, Diagnosen, Lern-/Precomputejobs oder Workflownodes sind kein zulässiger zweiter KI-Pfad. Andere fachliche HTTP-Integrationen werden dadurch nicht zu Modelladaptern erklärt. + +Mitai liefert nach Auflösung aller Variablen und Augmentierungen `RenderedPrompt`, nicht bereits einen externen Call. Das Gateway darf vor Versand keinen fachlichen Promptteil auslassen. Ergebnis-/Formatinstruktionen werden **vor** der vollständigen Egressinventur ergänzt. Der nachfolgende Workflow-Blueprint muss dieselben DTOs und Fehler-/Idempotenzverträge verwenden. Jeder Modellnode und jeder erneute Aufruf erhält eine eigene Call-ID und durchläuft erneut das Gateway; eine alte Maskierungsfreigabe gilt nicht für neue Nodeinputs. + +Erster Implementierungsschnitt: Textnachrichten, keine externen Tools/Plugins, keine Bilder/Audio-/Dateiuploads oder Remote-URLs, keine autonomen Agenten. Nicht registrierte Modalitäten werden verweigert. Spätere Erweiterungen benötigen denselben Empfänger-, Inhalts-, Test- und Datenschutzvertrag; sie werden nicht durch `dict[str, Any]` still akzeptiert. + +## 4. Datenklassen, Identität und Quellenvertrag + +`RequestContext` kommt unverändert aus Phase 3.3: geprüfter Principal, expliziter Scope und Request-ID. `profile_id`, Rollen, Policyklasse, Provider-URL und `privacy_checked=true` aus einem Browserbody sind keine Autorität. Ein Fachzweck ist in einer immutable Registry registriert und bestimmt Mindestschutz, erlaubte Quellen, Modellprofil und Ausgabeschema serverseitig. + +| Klasse | Anwendung im Gateway | +|---|---| +| A / Local only | Externer Generate verweigert; Geheimnisse, vollständige Identityregistry/Mapping und nicht erforderliche Rohdaten gehören nicht in den externen Kontext. Ein lokaler Fachfallback ist eine eigene registrierte Funktion. | +| B / persönlicher Kontext | Nur notwendige autorisierte Daten, vollständige lokale Detection/Registry-/Maskierungsprüfung, geeignete externe Route. Pseudonymisierung ist keine behauptete Anonymisierung. | +| C / generischer Kontext | Nur tatsächlich nicht persönliche freigegebene Inhalte. Gemeinsamer Gateway-/Endpoint-/Fehlerpfad bleibt bestehen; C ist kein Umbenennen persönlicher Daten. | + +Materialisierung klassifiziert Quellen/Felder anhand des Produktvertrags. Enthält eine Anfrage erforderliche Local-only-Bestandteile, darf sie nicht durch bloße Gesamtkennzeichnung B/C passieren. A-Felder müssen vor externem Rendering begründet ausgeschlossen sein; sonst Blockade. Bekannter Personenbezug in vermeintlichem C führt zur strengeren B-Prüfung, sofern für den Zweck zugelassen, andernfalls Ablehnung. Fehlende/unklare Klassifikation wird nicht C. + +Im ersten Schnitt ist C auf registrierte generische Vorlagen-/Katalogquellen begrenzt. Freier Usertext, persönliche Historie oder materialisierte Personendaten sind mindestens B; ein generischer Zweckname stuft sie nicht herunter. Ein lokaler vorgelagerter ForbiddenContentGuard verweigert bekannte Secrets, Private-Keyblöcke, credentialhaltige URLs/DSNs und als Local-only definierte direkte Identifikatorfelder vor Weiterverarbeitung. Dafür werden konkrete Struktur-/Secretregeln verwendet, keine Food-/Namensheuristiken als Ersatz für semantische Detection. Auch diese Prüfung behauptet keine vollständige Erkennung unbekannter Geheimnisse in beliebigem Freitext. + +`SourceBinding` enthält lokal Objekttyp/-ID, erwartete Version, Owner-/Scopebindung und ausgewählte Felder. Alle Quellen werden mit derselben AccessPolicy und scoped Repositoryabfragen geladen, einschließlich RAG-/Graph-/Memory-/Toolresultatquellen. Öffentlicher/globaler Katalog ist eine ausdrücklich erlaubte Quellenart, kein Join auf fremde private Daten. Bereits erzeugter Modelltext bleibt untrusted Eingabe und erhält keine höhere Anweisungspriorität. + +Der Dispatcher lädt niemals „alle Profile“ als Kontext. Minimierung ist eine Produktfeld-/Quellenauswahl, kein bloßes `strip()` oder pauschales Abschneiden. Bei Budgetüberschreitung wird abgebrochen oder im Fachadapter ein ausdrücklich anderer kompakter Kontext neu erzeugt; dieser durchläuft erneut die gesamte Pipeline. Keine unsichtbare providerseitige Kontextkompression. + +## 5. Python-Verträge und lokale Identitäten + +Illustrative Schnittstellen V/K. Importpfade für `RequestContext`, `ScopeRef` und Foundation-UoW werden im Zielprojekt aus den vorhandenen Verträgen übernommen. Inhalte sind im Speicher vertraulich, auch wenn `repr=False` ihre versehentliche Repräsentation reduziert. + +```python +from dataclasses import dataclass, field +from typing import Literal, Protocol +from app.core.context import RequestContext + +@dataclass(frozen=True, slots=True) +class SourceBinding: + kind: str + source_id: str + version: str + selected_fields: tuple[str, ...] + +@dataclass(frozen=True, slots=True) +class PromptMessage: + role: Literal["system", "developer", "user", "assistant", "tool"] + content: str = field(repr=False) + +@dataclass(frozen=True, slots=True) +class RenderedPrompt: + template_id: str + template_revision: str + messages: tuple[PromptMessage, ...] = field(repr=False) + sources: tuple[SourceBinding, ...] + +@dataclass(frozen=True, slots=True) +class GatewayCall: + call_id: str + execution_id: str + node_key: str + purpose: str + rendered: RenderedPrompt = field(repr=False) + result_spec_id: str + +@dataclass(frozen=True, slots=True) +class UsageReport: + input_tokens: int | None + output_tokens: int | None + reported_cost: str | None + currency: str | None + status: Literal["reported", "estimated", "unknown"] + +@dataclass(frozen=True, slots=True) +class ModelResult: + call_id: str + content: str = field(repr=False) + result_spec_id: str + usage: UsageReport + +class ModelGateway(Protocol): + async def complete(self, context: RequestContext, + call: GatewayCall) -> ModelResult: ... +``` + +Ein `RenderedPrompt` ist ein internes Ergebnis des autorisierten Render-/Materialisierungsadapters, kein frei deserialisiertes APIobjekt. `purpose`, ResultSpec und Vorlagenrevision werden gegen registrierte serverseitige Definitionen geprüft. ResultSpec legt `text` oder ein konkretes Pydanticmodell, maximale Länge, erlaubte Werte und rehydrierbare Textpfade fest. `ModelResult.content` ist bei JSON eine validierte kanonische JSONzeichenkette; Fachadapter erhält anschließend das explizite lokale DTO. Keine rohen Providerdicts. + +Providertransport erhält **weder** `RequestContext` noch `SourceBinding` oder Manifest. Er bekommt eine interne `SealedEgress`-Struktur: Call-ID, registrierte Route-/Profil-/Policyrevision, unveränderliche Bodybytes, Bytehash, Größenlimit, Deadline und eine kurzlebige interne `DispatchPermit`. Diese Objekte werden ausschließlich durch die Gatewaypipeline erstellt, nicht aus einem Clientflag. Sie sind lokale Programmgrenzen, kein Kryptografiebeweis gegen kompromittierten Servercode. + +Hier bezeichnet `SealedEgress` den **Generate**-Ausgang. Die vorgelagerte lokale Detection verwendet einen getrennten typisierten `LocalDetectInput(call_id,inventory_revision,text_fields)` und `LocalDetectTransport`: nur nach T1/ForbiddenContentGuard, nur zum eligible lokalen Detectprofil, ohne Registry-/Rehydrationstabelle und ohne externe Generate-Permit. Der lokale Detectadapter validiert Ziel, Größen, Rolle und Antwortschema, bevor er Coverage liefert. Er kann keine Generate-Route auswählen. So entsteht kein zirkuläres „vor Detection bereits vollständig maskiert“-Erfordernis und kein als Detect getarnter externer Klartextpfad. + +Der kleine Detect-Port präzisiert die Rückgabe. Coveragebereiche werden **lokal vom Adapter** aus tatsächlich erfolgreich verarbeiteten Chunks aufgebaut, nicht aus einer Modellbehauptung übernommen. Spans werden am exakt gebundenen Text validiert. + +```python +@dataclass(frozen=True, slots=True) +class TextField: + path: str + revision: str + text: str = field(repr=False) + +@dataclass(frozen=True, slots=True) +class LocalDetectInput: + call_id: str + inventory_revision: str + text_fields: tuple[TextField, ...] = field(repr=False) + +@dataclass(frozen=True, slots=True) +class DetectedSpan: + field_path: str + start: int + end: int + observed: str = field(repr=False) + entity_type: Literal["PERSON", "PLACE", "ORG", "PROJECT"] + +@dataclass(frozen=True, slots=True) +class DetectionCoverage: + inventory_revision: str + detector_profile_revision: str + processed_ranges: tuple[tuple[str, int, int], ...] + spans: tuple[DetectedSpan, ...] = field(repr=False) + +class SemanticDetector(Protocol): + async def detect(self, request: LocalDetectInput) -> DetectionCoverage: ... +``` + +Die lokale `MaskingManifest`-Variante übernimmt Kanshōs aktive Ersetzungen, Typen, Vorkommen und Rehydrationstabelle, ergänzt aber zwingend Call-ID, Subject/Scope-Namespace, genaue Inventur-/Payloadrevision, Detection-/Registry-/Reviewrevision und technische Coverage. Keine dieser Zuordnungen wird in externe Metadaten oder globale mutable Variablen gelegt. Gleichzeitige A-/B-Calls besitzen getrennte Manifeste; kein globales `last_trace` als Quelle persönlicher Ergebnisse. + +## 6. Providerprofile, Trust Zones und Eignung + +Ein Profil ist produktlokal versioniert und enthält ausschließlich Konfiguration/Secretreferenzen. Konkrete erforderliche Felder: + +| Gruppe | Felder / Regel | +|---|---| +| Identität | `profile_id`, `revision`, `adapter_kind`, Rolle `detect|generate`, Status `disabled|unverified|eligible` | +| Ziel | Exakte erlaubte Scheme/Host/Port/Path-Kombination, TLS-/CAprofil, explizite Netzwerk-/Adressgrenze, `trust_zone_id` | +| Modell | Registrierte Modell-ID, erlaubte Rollen/Modalitäten, Contextwindow/Tokenizer bzw. Schätzverfahren, Ausgabegrenze, unterstützte Formate | +| Privacy | Policy-ID/-revision, erlaubte Zwecke/Datenklassen, erforderlicher ZDR-/No-training-/Region-/Loggingzustand, Belegreferenzen und `checked_at`/`valid_until` | +| Adapter | Erzwungene Requestparameter, erlaubte Upstreamprovider/Endpoints, Redirect-/Retry-/Transformverhalten, Transportlimitprofil | +| Secret | Ausschließlich `credential_ref`; Rohwert nur im Secret-/Transportadapter, nicht im Profil-Response oder Log | + +Ein Boolean `zdr=true` ohne Beleg/Adapterfähigkeit reicht nicht. Eignung erfordert passende aktuelle Policy, dokumentierte tatsächliche Account-/Endpointkonfiguration und technische Erzwingbarkeit der geforderten Einschränkungen. Unbekannt/abgelaufen → Route nicht eligible. Default für erneute technische Belegprüfung sieben Tage und bei Profil-/Provideränderung; lokale Gründe können andere Fristen verlangen. Dies ist ein veränderbarer technischer Prüfzyklus, keine neue Familienfreigabe. + +Aktuelle Bedingungen des konkret gewählten Empfängers sind gemäß ADR-09 vor realer persönlicher Nutzung zu prüfen. Diese Lieferung aktiviert keinen Provider und liest keine Account-/Keyeinstellungen. Tests verwenden synthetische Profile/Keys. Fehlt ein realer Beleg, bleibt der betreffende Pfad geschlossen; andere Appfunktionen können weiterlaufen. + +### 6.1 Detect, Generate und lokale Empfänger + +**Detect:** bevorzugt ein bereits vorhandener lokaler, ausdrücklich registrierter semantischer Detector. Er sieht nur den für Detection notwendigen finalen Text, keine vollständige Identityregistry, Sessioncredentials oder DBsecrets. Bestätigte lokale Identitäten werden im Gateway angewendet. Eine lokale IP oder `.local` beweist keine Vertrauenszone: Betreiber-/Zugriffs-/Logginggrenze, konkretes Ziel und Netzweg müssen zum Profil passen. + +**Generate:** nur maskierter/minimierter B-Kontext bzw. kontrolliertes C, passendes Modell und Providerpolicy. Kein derselbe Key als stiller Fallback zwischen Rollen. **Tools/Websuche/Embeddings/Transkription:** eigene spätere Zweck-/Empfängerpfade; im ersten Schnitt nicht aktiviert. OpenRouter-ZDR ist keine Freigabe aller zusätzlich einschaltbaren Tools. + +Neuer Standard: kein externer Klartext-Detect, auch nicht allein wegen `APP_ENV=development`. Persönliche Development-/Testdaten bleiben persönlich; CI arbeitet synthetisch. Kanshōs ausdrücklich beschriebene Übergänge bleiben dortige Bestandsregeln und werden im Reuseadapter als Abweichung dokumentiert. Es entsteht kein neuer Runtime-„Privacy aus“-Schalter und kein notwendiger neuer Detectdienst in diesem Auftrag. Ohne vorhandenen geeigneten Detect-/Reviewadapter bleibt B-Egress geschlossen. + +### 6.2 Endpunkt- und Secretgrenze + +Keine URL, Base-URL, Proxyadresse oder Callbackadresse aus Fach-/Browserinput. Nur registrierte Adapterziele; HTTPS mit Zertifikatsprüfung extern, HTTP ausschließlich für explizit erlaubte kontrollierte lokale Empfänger. Keine Userinfo/Secrets in URLs, keine frei wählbaren Header, keine Redirects. `openrouter.ai` wird exakt geprüft; ein Anzeigename oder `endswith('openrouter.ai')` ist keine Zielautorität. + +DNS-Auflösung und tatsächlicher Verbindungsweg müssen die registrierte Zielgrenze einhalten. Netzwerkregeln des vorhandenen Containers/Hosts begrenzen den Adapter zusätzlich; DNS-Rebinding auf Loopback/Metadata-/fremde private Ziele darf kein neues Ziel öffnen. Eine pauschale Freigabe aller RFC1918-/Link-local-Adressen ist ausgeschlossen. Erforderliche lokale Adressen werden ausdrücklich registriert. Kann ein Adapter seine Verbindungsgrenze nicht gewährleisten, wird er nicht als eligible markiert. + +HTTPX verwendet `trust_env=False`, keine impliziten Proxy-/CAumgebungswechsel, und ein ausdrücklich konfiguriertes TLS-/CAprofil. Client wird im Lifespan wiederverwendet und geschlossen; Keys werden nur für das konkrete legitime Authheaderziel injiziert. Provider-APIkeys sind notwendige Transportcredentials dieses Empfängers, keine erlaubten Modellkontextfelder. App-/DB-/Sessionsecrets und Mappingdaten gehen niemals in Payload, Attribution oder URL. [HTTPX Umgebungsvariablen](https://www.python-httpx.org/environment_variables/). + +### 6.3 Konkreter OpenRouter-Adapter + +OpenRouter ist ein vorhandener Adapterkandidat, kein Architekturzwang. Für entsprechend freigegebenen B-Egress setzt der Adapter insbesondere: + +```json +{ + "model": "registered-model-id", + "messages": [{"role": "user", "content": "Freigegebener maskierter Text"}], + "max_tokens": 2048, + "stream": false, + "provider": { + "only": ["registered-upstream-slug"], + "allow_fallbacks": false, + "require_parameters": true, + "data_collection": "deny", + "zdr": true + } +} +``` + +Platzhalter-IDs werden aus dem passenden eligible Profil eingesetzt; keine aktuelle Modell-/Providerempfehlung oder bereits erteilte Freigabe. Keine Modellfallbackliste, Auto-Router, Tools, Plugins oder dynamischen Presets. Providerseitige Kontextkompression/zusätzliche Transformation ist für persönliche Payloads nicht zugelassen; die konkrete Deaktivierung muss der eingesetzte Adapter nachweisen. Der Gatewayadapter setzt Filter selbst; ein Renderer darf sie nicht überschreiben. + +Die Parameter `only`, `allow_fallbacks`, `require_parameters` und `data_collection` werden in der [OpenRouter-Routingdokumentation](https://openrouter.ai/docs/guides/routing/provider-selection) beschrieben. Bei fehlender geeigneter Route wird abgebrochen. Ein Providername allein belegt keine verlangte Region; wenn Region verpflichtend ist, braucht das Profil einen passenden tatsächlich erzwingbaren Endpoint-/Routingnachweis. + +`provider.zdr=true` ist separat erforderlich; ein lokaler No-training-Boolean bzw. `data_collection` allein wird nicht als vollständiger Retentionsnachweis dargestellt. OpenRouter beschreibt ZDR für Inferenzrouting, weist Tools/Plugins eigene Policies zu und zählt bestimmte In-memory-Caches nicht als Retention. Daher bleibt die konkret benötigte Schutzwirkung zu prüfen. [OpenRouter ZDR](https://openrouter.ai/docs/guides/features/zdr). Das sind begrenzte technische Gegenprüfungen, keine Aussage, jeder aktuelle Endpoint erfülle Jinkendos Anforderungen. + +## 7. Ablauf und sichere Transaktionsgrenzen + +### 7.1 Phase T1: autorisierte Aufnahme + +In einer kurzen Foundation-UoW: aktuelle Session/Principal, Scope, Fachcapability und gegebenenfalls Entitlement prüfen; alle ausgewählten Quellen samt Version/Owner-/Scopegrenze materialisieren; unveränderlichen lokalen Snapshot erzeugen. Call-ID/Idempotenz registrieren und sicheren Auditmetadatensatz schreiben. Kein Modell-/Detector-/HTTP-Aufruf in dieser Transaktion. Der Renderer verarbeitet nur diesen autorisierten Snapshot und freigegebene Vorlagen-/Formatinstruktionen. + +Die Berechtigung wird nicht aus den später vom Renderer eingetragenen `SourceBinding`-Strings geglaubt. Der Materialisierungsadapter erzeugt und bindet sie serverseitig. Nicht benötigte Felder werden vor Rendering ausgeschlossen. Eine nachträglich hinzugefügte Quelle verlangt erneute autorisierte Aufnahme. + +### 7.2 Lokale Verarbeitung ohne offene DB-Transaktion + +Vollständige Vorlage inklusive System-/Developer-/Historien-/Userteilen und statischem Outputvertrag fertigstellen. Inventur/Minimierung/Budgetprüfung durchführen. Für B den gesamten endgültigen Text lokal untersuchen, bestätigte eigene Registry ergänzen, offene Konflikte behandeln, requestbezogen maskieren. Payload einschließlich Adapterparameter fertigstellen und final validieren/sealen. Reihenfolge und Bindung stehen in Abschnitt 8/9. + +Ein Reviewbedarf wird als `privacy_review_required` an den Fachadapter zurückgegeben. Generate wurde dann nicht aufgerufen. Vorhandene lokale Reviewmechanismen dürfen verwendet werden; fehlt ein geeigneter Adapter, bleibt dieser Fall geschlossen. Dieser Blueprint baut kein neues allgemeines Reviewportal und verlangt keine pauschale Bestätigung jeder Anfrage. + +### 7.3 Phase T2: aktueller Dispatchentscheid + +Unmittelbar vor Transport erneut unter kurzer UoW prüfen: aktueller Principal/Sessionsgeneration/Kontostatus, Scope/Mitgliedschaft, Fachrecht, alle Quellenversionen, Vorlagenrevision, aktive Policy-/Registry-/Providerprofilrevision und gegebenenfalls genau gebundene Reviewentscheidung. Weicht benötigter Kontext ab, `context_changed` statt Versand eines alten Snapshots. Keine stillschweigende Neuzusammenstellung nach der Privacyprüfung. + +Bei Erfolg Dispatchintent samt Call-/Payload-/Routenbindung und erforderlichem Audit committen; kurzlebige interne Permit erzeugen, Default zwei Sekunden bis Beginn des Sendens. Hat das Warten auf Transportkapazität diese Frist überschritten, erneute T2-Prüfung vor Senden. Wiederholungen dieser kurzen **lokalen Prüfung** sind keine weiteren Modellversuche. Widerruf vor dem Dispatchentscheid sperrt den Call. + +Zwischen DBcommit und externem Netzwerk besteht keine verteilte Transaktion. Eine Sperre unmittelbar nach dem Dispatchentscheid kann bereits freigegebene Bytes nicht zuverlässig zurückholen. Der Vertrag benennt deshalb diesen Autorisierungszeitpunkt, bindet den exakten Snapshot, hält das Zeitfenster klein und prüft nachher erneut. Es wird keine unmögliche Atomarität mit dem Provider behauptet. + +### 7.4 Transport und Phase T3 + +Genau ein Generate-Versuch mit den geprüften Bytes; Antwort begrenzt einlesen, validieren und lokal rehydrieren. Danach erneut aktuelles Konto/Scope/Objekt-/Ausgaberecht prüfen. Bei Entzug oder Quellenkonflikt keine persönliche Antwort anzeigen oder als Fachergebnis speichern. Verbrauchs-/Fehlermetadaten des bereits erfolgten Aufrufs dürfen der Server unter eigenem engen Auditvertrag abschließen; sie geben keine Fachrechte zurück. + +Wenn ein Fachergebnis gespeichert wird, verwenden Ausgaberecht, erwartete Objektversion, Ergebniswrite, Callabschluss und Audit dieselbe Foundation-Transaktion. Erst nach Commit Erfolg zurückgeben. Für reine Anzeige erhält T3 einen atomaren Metadatenabschluss plus aktuelle Lesefreigabe; das Ergebnis lebt nur im Antwortspeicher. Ein danach erfolgter Scopewechsel wird zusätzlich durch die Frontend-epoch abgefangen. + +Fachservice/Workflow hält über den Gatewayawait keine DB-UoW offen. Der Gateway-HTTPpfad ist tatsächlich asynchron (`httpx.AsyncClient`); synchrone Psycopg-UoWs laufen über klar abgegrenzte Threadbridge-Funktionen, beispielsweise `anyio.to_thread.run_sync`. Kein blockierender SQLaufruf direkt im Eventloop und keine Connection über `await` weiterreichen. Abbruch beendet lokale Arbeit/Transport soweit möglich; ein bereits angestoßener Providercall kann trotzdem verarbeitet/berechnet worden sein. + +## 8. Vollständige Detection und Maskierung + +### 8.1 Inventur vor Detection + +Der Adapter definiert eine geschlossene Payloadschema-Version. Für den ersten Schnitt enthält sie Modell-ID, erlaubte Textnachrichten, begrenzte numerische Parameter, Streamflag, kontrollierte Providerfilter und gegebenenfalls einen registrierten statischen Outputschema-Vertrag. Keine frei ergänzbaren `metadata`, `user`, Promptsuffixe, Plugins oder Tools. + +Die Textinventur enumeriert **alle** endgültigen Nachrichtentexte: System, gegebenenfalls unterstützter Developerkanal, User, frühere Assistanttexte sowie jeder neu zusammengesetzte Kontext/Formattext. Tooltexte und weitere Felder sind entweder ausdrücklich unterstützt und vollständig inventarisiert oder verweigert; unbekannte Kanäle werden nicht ignoriert. Statische JSONschemabeschreibungen sind ebenfalls im Textinventar. Technische Schlüssel/Modell-/Provider-IDs stammen ausschließlich aus einer kontrollierten nicht persönlichen Registry; keine dynamischen persönlichen JSONkeys oder Schemas vom Browser. Externe `$ref`-/URLauflösung ist nicht erlaubt. + +Inventareintrag: stabiler lokaler Feldpfad, Textrevision, lokale Quellenbindung, UTF-8-Bytegröße und Coveragebereiche. Derselbe Textstand wird für Detection und Maskierung verwendet. Unicode-/Zeilenendenaufbereitung findet, falls überhaupt nötig, **vor** dieser Bindung statt. Danach keine Normalisierung, die Spans verschiebt. + +### 8.2 Semantische Detection, Registry und Review + +Kanshōs requestbezogene Span-/Registrytrennung wird übernommen. Jeder notwendige Detect-Chunk muss tatsächlich erfolgreich verarbeitet und sein Ergebnis lokal am Originaltext geerdet sein: Feldpfad, Start/Ende als Python-Codepointindizes, beobachteter Text und Typ passen exakt. Schemafehler, abgeschnittene Antwort, Lücken oder Timeout verweigern B-Generate. Überlappende Chunks werden mit lokalen Offsets zusammengeführt; Randfälle dürfen weder verschwinden noch doppelt Identitäten bestätigen. + +`PERSON`, `PLACE`, `ORG`, `PROJECT` sind die vorhandenen Ausgangstypen. Erweiterung nur bei konkretem Produktbedarf. Bestätigte eigene Identitäten/Aliase bleiben lokale Autorität. Ein Detect-Ergebnis erzeugt keine dauerhaft bestätigte Identität. Homonyme werden pro Vorkommen behandelt; keine neuen globalen Food-/Wetter-/Großschreibungswortlisten und kein Regexfallback, der einen semantischen Detectausfall als erfolgreich ausgibt. + +`coverage_complete=true` bedeutet ausschließlich vollständige technische Verarbeitung des gebundenen Inventars. `semantic_identity_guaranteed=false` bleibt ausdrücklich erhalten. Ein Nulltreffer beweist nicht Identitätsfreiheit. Bekannte offene Konflikte oder erforderliche unbestätigte Entscheidungen blockieren bis zur gebundenen lokalen Klärung. Falls die konkrete Produktpolicy darüber hinaus eine geprüfte vollständige Freigabe persönlicher Eingabe verlangt, muss dieser Review-/Prüfadapter vorhanden sein; ein Fake „alles sicher“ ist unzulässig. Diese Grenze wird nicht durch neue Heuristiken verdeckt. + +Vorab berechnete Treffer/Reviews sind nur wiederverwendbar, wenn Subject/Scope, sämtliche Feld-/Payloadrevisionen, Quellen, Registry-/Detector-/Policyrevision und Ablauf exakt passen. Ein Boolean `full_detection_coverage=true` aus dem Aufrufer reicht nicht. Ein bloßer Review des letzten Nutzersatzes deckt nicht automatisch Systemtext, Historie, RAG und spätere Renderergänzungen ab. Nicht abgedeckte Felder durchlaufen weiterhin Detection. Ändert sich die Vorlage oder ein nachgelagerter Nodeinput, gilt der alte Nachweis nicht. + +### 8.3 Pseudonyme und lokales Manifest + +Spanersetzungen aus Kanshō werden von hinten nach vorne auf den gebundenen Text angewandt. Überlappungen werden deterministisch aufgelöst oder als unklar verweigert; bestätigte Alias-/Identitätsregeln bleiben getrennt von unbestätigten Treffern. Nur tatsächlich eingesetzte Ersetzungen werden aktiv. Der Manifestnamespace ist mindestens Produkt + Scope + Subject + Call; ein Token aus B wird nie über A aufgelöst. + +Vorhandenes Syntaxmuster `[[PERSON:01]]` bleibt als lokaler Adapterdefault möglich. Tokens sind innerhalb des Calls konsistent. Bestätigte lokale Identität kann intern über Calls stabil sein; extern wird standardmäßig pro Call neu zugeordnet, damit kein globales Personenkennzeichen entsteht. Kontextübergreifende stabile externe Pseudonyme sind keine Foundationpflicht. Aliase enthalten keine zusätzlichen Krankheiten, Herkunfts- oder Beziehungsinformationen. + +Untrusted Eingabe darf die reservierte Identitätstokensyntax nicht selbst als Mappingbefehl einschleusen. Default: entsprechende rohe Tokens in neuen Quell-/Usertexten mit `reserved_identity_syntax` verweigern. Ein später tatsächlich benötigter Literaladapter kann sie eindeutig getrennt kodieren und muss getestet sein; kein stilles Verschlucken legitimen Inhalts. Vertrauenswürdige Vorlagen erzeugen konkrete aktive Tokens nur über den Manifestadapter. + +Rehydrationstabelle enthält nur autorisierte **aktive** Tokens des Calls, nicht die ganze Profilregistry. Bestätigte Aliase können kanonisch, unbestätigte Requesttreffer in beobachteter Schreibweise rehydriert werden, entsprechend Kanshō. Kein Provider, Debugclient oder fremder Scope erhält diese Tabelle. Standardlebensdauer ist die Anfrage; nach Abschluss/Abbruch Referenzen freigeben. Persistente Quelldaten/Registries bleiben lokale Produktdaten und werden nicht als temporäre Diagnose gelöscht. + +## 9. Finales Egress-Gate und unveränderlicher Transport + +Nach Maskierung werden alle erlaubten Provider-/Formatparameter ergänzt, ein striktes endgültiges Payloadschema validiert und sämtliche ausgehenden Textfelder gegen das Manifest geprüft. Bekannte zu maskierende Identitätsvorkommen müssen ersetzt, technische Felder kontrolliert, Class-A-Felder entfernt und alle notwendigen Coverage-/Reviewbindungen gültig sein. Fehlender Beleg oder eine nicht unterstützte Zusatzoption sperrt den Versand. + +Der Registry-Safety-Net-Adapter prüft die erwarteten zu schützenden Vorkommen im vollständigen Inventar, nicht ausschließlich bereits erfolgreich als `manifest.replacements` eingetragene Treffer. Eine zuvor ausgelassene bekannte Identität darf nicht dadurch unsichtbar werden, dass sie nie als aktive Ersetzung registriert wurde. Vorkommensbezogene Homonym-/Reviewregeln bleiben dabei bestehen; unbekannte semantisch übersehene Identitäten werden weiterhin nicht als garantiert erkannt dargestellt. + +Serialisierung: deterministische JSONbytes in UTF-8, `ensure_ascii=False`, kompakte Separatoren, stabile Schlüsselreihenfolge, `allow_nan=False`; ungültige Surrogate oder nicht erlaubte Werte verweigern. Der interne Bytehash bindet **genau** diese Bytes an Route/Profil/Policy/Manifest/Call. Der Transport sendet `content=sealed.body` mit festem JSON-Content-Type, nicht erneut `json=`. Keine SDK-/Middleware, die anschließend Promptteile/Tools/Metadaten anhängt. + +Die einzige anschließende Ergänzung sind kontrollierte Transportheader, insbesondere der für genau diesen Empfänger benötigte Provider-Authheader. Keine Principal-/Profil-IDs, Cookie-/Sessionheader, freie Useragentzusätze oder rohe Quellnamen als Attribution. Request-ID/Call-ID bleibt lokal, sofern kein explizit geprüfter Transportvertrag eine nicht persönliche Korrelation benötigt. Finaler Endpoint und tatsächlicher Verbindungsweg sind Teil des Gates. + +Vor `.send` verlangt der Adapter gültige Permit, passende Profil-/Policyrevision, Hash/Größe und freie Kapazität. Re-Rendering oder Änderung an Body, Schema, Modell, Route, Schlüsselzuordnung oder Prompt nach dem Gate macht den Seal ungültig. Ein Sendversuch konsumiert die interne Permit. Ein zweiter Generate benötigt eine neue explizite Callentscheidung; der Workflow kann nicht dieselbe Permit beliebig wiederverwenden. + +Secretreferenzen liefern eine begrenzte Credentialversion zusätzlich zum Rohwert; die Version ist an die Route/Permit gebunden, der Rohwert bleibt nur im Transport. Eine zwischenzeitlich geänderte Zuordnung darf nicht denselben geprüften Call an ein anderes Konto/Ziel schicken. Der interne Status `sent_or_unknown` und ein begrenzter Providerrequestbezug können lokal gespeichert werden; ein möglicherweise vom Provider gelieferter Freitextbezug wird nicht ungeprüft als ID übernommen. + +Eine spätere Antwortprüfung kann einen bereits erfolgten Datenversand nicht rückgängig machen. Deshalb müssen Canary-/Wiretests den tatsächlichen Adapterausgang untersuchen und nicht nur prüfen, dass eine Maskierungsfunktion aufgerufen wurde. + +## 10. Transportgrenzen, Abbruch und Wiederholungen + +### 10.1 Ressourcenprofil + +| Einstellung | Technischer Ausgangswert | +|---|---| +| Gesamter Gatewaylauf einschließlich Detect/Queue/Generate | 90 Sekunden monotone Deadline; Fachzwecke dürfen begründet andere begrenzte Werte wählen | +| HTTP connect / pool / write / read inactivity | 5 / 2 / 10 / 30 Sekunden, jeweils zusätzlich zur verbleibenden Gesamtdauer | +| Parallelität | Zwei Gatewayläufe je Backendprozess, begrenzte Warteschlange 16; voller Eingang 503 | +| Eingabepayload | Maximal 64 KiB UTF-8 über sämtliche Textteile; Modellkontext zusätzlich prüfen | +| Detect-Chunks | Default 4.000 Codepoints mit begrenzter Überlappung 200; maximal 32 Chunks; vollständige Coverage Pflicht | +| Ausgabe | Default maximal 2.048 Outputtokens; tatsächliches Modellprofil und Zweck können kleinere Grenzen setzen | +| Providerresponse | Maximal 2 MiB decodierte Bodybytes und begrenzte Message-/Textlänge; Chunks zählen statt erst unbeschränkt `.json()` zu laden | +| Idempotenz-/Callmetadaten | Default sieben Tage, an produktbezogene Audit-/Abrechnungszwecke anpassen | + +HTTPX unterscheidet Connect-/Read-/Write-/Pooltimeouts; Readtimeout ist eine Inaktivitätsgrenze pro empfangenem Chunk und keine Gesamtlaufzeit. Die zusätzliche monotone Deadline wird z. B. mit `anyio.fail_after` umgesetzt; Netzwerkressourcen werden bei Abbruch geschlossen. [HTTPX Timeouts](https://www.python-httpx.org/advanced/timeouts/). Ein langsamer kontinuierlicher Bytestrom darf das Gesamtbudget nicht unbegrenzt verlängern. + +Connectionpool und Admissionlimit sind explizit begrenzt. Bei mehreren Prozessen werden Limits budgetiert; ein Prozesslimit ist keine zugesicherte globale Kontenquote. Tokenbudget nutzt Modellprofil, reservierte Ausgabe und Sicherheitsmarge. Wenn nur eine konservative Zeichenschätzung verfügbar ist, wird sie so bezeichnet; unbekanntes Modellfenster oder Grenzverletzung führt zu lokalem Abbruch, nicht zu blindem Versand. Automatische Kürzung/Kompression nach dem Egress-Gate ist verboten. + +### 10.2 Fehlerzustand und Kostenunsicherheit + +Kein automatischer Generate-Retry, Reparaturprompt oder Modell-/Providerwechsel. Das gilt für 429/5xx, ungültiges JSON, Refusal, Verbindungsabbruch und Antwortvalidierungsfehler. Die erste erzeugte Antwort bleibt nicht durch eine heimliche zweite ersetzt. Eine bewusst angeforderte neue fachliche Ausführung erhält eine neue Call-ID und durchläuft Autorisierung/Privacy/Budget erneut. + +`not_sent` ist nur zulässig, wenn der eigene Adapter sicher keinen Sendversuch begonnen hat. Nach Eintritt in den Transport ist bei Timeout/Abbruch der konservative Zustand `sent_or_unknown`, sofern kein engerer Nachweis existiert. Eine Exception oder Clientdisconnect bedeutet nicht „Provider hat nichts verarbeitet/keine Kosten“. Der Adapter speichert bekannte Usage, ansonsten `unknown`; keine erfundene Nullbuchung oder stille Freigabe einer möglichen Verbrauchsreservierung. + +Bekannte HTTP-429-Antwort wird in ein sicheres begrenztes Retry-After übersetzt; der Client erhält keine automatische Wiederholungsanweisung für denselben Write. SDK-/Transportretrys werden ausdrücklich deaktiviert (Default null); kein versteckter `HTTPTransport(retries=...)` oder aus Providerbibliotheken übernommener Retry. Reine lokale T2-Neuprüfung und spätere lesende Statusabfrage sind davon getrennt. + +## 11. Antwortvalidierung, JSON und Streaming + +1. Envelope streng prüfen: HTTPstatus, Content-Type, Bodylimit, eine erwartete Choice, bekannte Contentblöcke und Finishreason. Unbekanntes Format, versteckte Toolcalls oder `finish_reason=length` bei erforderlichem vollständigem Ergebnis werden nicht als erfolgreiches Fachresultat behandelt. Refusal ist ein eigenes Ergebnis/Fehlercode, kein normaler Textblock. +2. Reasoning-/Thinking-/Toolblöcke werden nicht als sichtbarer Text ausgegeben oder in spätere Prompts übernommen. Nur ausdrücklich unterstützte Textblocktypen normalisieren; keine generische Rekursion durch alle Dictionarywerte. +3. Für JSON: vollständige strikte JSONsyntax und das registrierte Pydantic-Ausgabemodell einschließlich Grenzen/Enums/`extra='forbid'` tatsächlich validieren. Kein bloßes `json.loads(schema_ignored)` und kein automatischer Repaircall. Default keine Markdown-Codefenceheuristik; ein bewusst benötigter Wrapperadapter ist eine getestete begrenzte Variante. +4. Privacy-/Tokenintegrität prüfen. Unbekannte, fremde oder inaktive Identitätstokens verweigern; keine freie Registryauflösung. Erkennbare unzulässige Identitätsvermutung/PII gemäß Produktpolicy blockiert die Antwort, ohne erneuten Generate. Homonyme bleiben vorkommensbezogen, keine globale Wortersetzung. +5. Nur bekannte aktive Tokens lokal rehydrieren. Eine interne normalisierte Prüffassung ist nicht die sichtbare Fassung. Akzeptierter modellseitiger Klartext behält seine Oberflächenform; nach Demasking keine semantische/grammatische Umschreibung des Journaltextes. Das folgt Kanshōs bestehender Trennung. JSONkeys, IDs, URLs, Datum-/Zahlenwerte oder später gedachte Toolargumente werden nicht unkontrolliert rehydriert; ResultSpec nennt erlaubte Textpfade. +6. Nach Rehydration erneut Ausgabelänge/JSONschema/zulässige Struktur prüfen und gemäß T3 autorisieren. Fachliche Plausibilität gehört zum konkreten Fachadapter; „valides JSON“ beweist weder Wahrheit noch aktuelle Gültigkeit. Kein Vorgriff auf ADR-16. + +Das Gateway validiert untrusted Ausgabe und verleiht ihr keine Befehlsgewalt. Quellen-/Modellanweisungen können weder Datenklasse, Endpoint, Scope, Zugriffspolitik noch Toolrechte erweitern. HTML/Markdown wird im Frontend nach vorhandenem sicherem Renderingvertrag behandelt; kein rohes `dangerouslySetInnerHTML` aus Modelltext. Links werden nicht serverseitig automatisch besucht. + +Auch der Browser darf keine modellseitigen Remote-Bilder, eingebetteten Inhalte oder Linkpreview-/Prefetchrequests automatisch laden. Default ist sichere Textdarstellung bzw. ein Renderer mit registrierten internen Medienreferenzen; aktive URLschemata werden verweigert. Identitätstokens in URLs/Markdown-Linkzielen werden nicht zu privaten Klartext-URLs rehydriert. Ein Modell darf lokale Demaskierung nicht in eine spätere Browserausleitung verwandeln. + +**Streamingdefault:** `stream=false`; vollständiges Ergebnis puffern und erst nach Validierung/Demaskierung freigeben. Falls ein konkretes Produkt Upstream-SSE benötigt, wird es begrenzt gesammelt und erst das vollständige geprüfte Ergebnis ausgegeben. Kein persönlicher Rohdelta-/Reasoningstream an Browser oder DebugUI. Fortschrittsanzeigen dürfen reine sichere Phasenereignisse senden, aber keine ungeprüften Tokens. Ein späteres echtes inkrementelles Freigabeverfahren braucht einen eigenen nachgewiesenen Vertrag; es wird hier nicht als bereits sicher angenommen. + +Verbindung zum Browser bei Scopewechsel/Logout schließen, alte Ergebnisse/Fehler nach epoch verwerfen. Der Caller setzt für lange KI-Operationen bewusst größere begrenzte Zeitbudgets, Default Client 105 Sekunden/Proxy 110 Sekunden bei Gatewaydeadline 90; der allgemeine Foundation-15-Sekunden-Default wird nicht global entfernt. Produktlokale längere Jobs sind Gegenstand des folgenden Workflowblueprints, kein neuer Worker in diesem Dokument. + +## 12. Callledger, Idempotenz, Audit und Quotenport + +Persistente lokale Metadaten verhindern unbemerkte doppelte Generate-Ausführung. Logischer Datensatz `ai_calls`: + +| Feldgruppe | Inhalt | +|---|---| +| Identität/Owner | `call_id UUID PK`, `subject_id`, `scope_kind`, `scope_id`, `execution_id`, `node_key`, `purpose`; Owner-/Scopefilter bei jedem Lookup | +| Inputbindung | Vorlagen-/ResultSpec-/Policy-/Profilrevisionen, Quellenversionsdigest und HMAC-Fingerprint der vollständigen semantischen Eingabe; keine Promptvolltexte | +| Zustand | `prepared`, `awaiting_review`, `dispatching`, `validated`, `completed`, `blocked`, `failed_unsent`, `unknown`, `rejected_output`, `discarded_after_revoke` | +| Versand/Nachweis | `dispatch_decided_at`, Beginn/Ende, sicherer Outcome-/Reasoncode, bekannte Modell-/Routen-ID, Technik-/Reviewcoverage und Maskierungszähler | +| Ergebnis/Verbrauch | Optional erlaubte fachliche `result_ref`, validierter Usage-/Kostenzustand, optional späterer Reservierungsbezug; keine generelle Providerresponseablage | + +Ein Unique-Constraint über Subject + Scope + `execution_id/node_key` bindet eine logische Ausführung. IDs sind begrenzt/validiert und nicht frei als Pfade verwendbar. Gleicher Schlüssel mit anderer Eingabe → 409 `call_conflict`. Während Dispatch oder bei `unknown` wird kein zweiter Call gestartet. `awaiting_review` kann nur mit derselben aktuellen Inputbindung und legitimer lokaler Reviewentscheidung fortgesetzt werden; inhaltlich geänderte Anfrage ist eine neue Ausführung. Keine HTTPbody-Flags als Freigabe. + +Fingerprints werden mit einem separaten produktlokalen `AI_FINGERPRINT_KEY` als HMAC berechnet, damit gespeicherte Hashes kurzer persönlicher Texte kein einfaches Wörterbuchorakel bilden. Rohes Payload-SHA dient nur intern zur unmittelbaren Bytebindung und wird nicht als öffentlicher Debugwert persistiert. Fingerprint bindet Subject/Scope/Zweck, Input-/Vorlagen-/Quellen-/Policy-/Profilstand und Ergebnisformat, nicht die Cookiegeneration; spätere legitime Sessionerneuerung erzeugt keine neue logische Facheingabe. Aktuelle Autorisierung bleibt trotzdem bei jedem Lookup Pflicht. + +Der Ledger speichert die Fingerprint-Key-ID; benötigte alte Keyversionen bleiben über die Idempotenz-/Aufbewahrungsfrist verfügbar bzw. werden kontrolliert migriert. Fehlt nach Rotation/Restore eine benötigte Version, wird ein bestehender unbekannter Call nicht als neue freie Ausführung behandelt. Der Recovery-Schlüsselvertrag aus dem vorherigen Blueprint umfasst diesen Bedarf, ohne den Key in Datenarchiv oder Logs zu schreiben. + +Schema/Fremdschlüssel nutzen die lokalen Account-/Scope-IDtypen der Zielanwendung; für einen neuen Foundationaufbau die in Phase 3.3 vorgesehenen Konten. Kein universeller Tenantstore. Callabschluss/Ergebniswrite/Audit committen zusammen. Netzcall und DB können nicht atomar sein: Prozessabbruch nach Dispatchintent wird konservativ als ungeklärter Aufruf behandelt, nie automatisch erneut gesendet. Nach Neustart sind offene `dispatching`-Zeilen zu klären bzw. `unknown`; ein Ablaufdatum erteilt keine neue Generate-Erlaubnis. + +Die siebentägige Standardretention betrifft abgeschlossene ungebundene Metadaten. Laufende/ungeklärte Calls und durch Fach-/Workflowausführungen referenzierte Call-IDs behalten mindestens ihren gesperrten Idempotenz-/Outcometombstone; Cleanup darf sie nicht zu unbekannten „neuen“ Ausführungen machen. Für abgeschlossene Calls außerhalb des ausdrücklich zugesicherten Idempotenzfensters wird keine unbegrenzte Wiederabrufgarantie behauptet. Eine bewusst neue Generierung verwendet eine neue Ausführungs-ID. + +Ein bereits abgeschlossenes persistiertes Fachergebnis kann nach aktueller Autorisierung per `result_ref` erneut gelesen werden. Bei reiner Anzeige ohne gespeichertes Resultat gibt es keinen langlebigen Antwortcache; Wiederabruf desselben Calls liefert `result_unavailable`, keine kostenpflichtige Neugenerierung. Der Fachauftrag kann ausdrücklich eine neue Ausführung anfordern. Keine personenbezogenen globalen Antwort-/Promptcaches. + +### 12.1 Auditgrenzen und Speicherung + +Pflichtmetadaten: Call-/Request-ID, lokale Subject-/Scopebindung, Zweck, verwendete Profil-/Policy-/Vorlagenrevision, lokale Dispatchentscheidung, Coverageart, `semantic_identity_guaranteed=false`, Zähler/Größen/Dauer, bekannter Usagezustand, Ausgabestatus und sicherer Reasoncode. Keine echten Labels, Aliase, Mappings, Cookie-/Provider-/DBsecrets, System-/Userpromptvolltexte oder Modellantworten in Log/APM/Exceptions/DebugUI. Providerfehlertexte können Eingaben spiegeln und werden daher nicht durch bloßes Abschneiden sicher. + +Der Gateway speichert standardmäßig keine Rohprompts, Rohantworten oder Manifestmappings. Fachlich bewusst bewahrte Originalquellen und akzeptierte Ergebnisse bleiben normale lokale Produktdaten mit eigener Autorisierung/Retention; Kanshōs Quellbewahrung wird dadurch nicht abgeschafft. Diagnoseberechtigung ist keine pauschale Freigabe privater Texte. Tests dürfen Wirebodies ausschließlich mit synthetischen Inhalten und für den Testlauf aufzeichnen. + +Fehlt der erforderliche Auditspeicher vor Dispatch, kein Versand. Scheitert der Abschluss nach möglichem Versand, wird kein zweiter Call zur „Reparatur“ erzeugt; Fehler und späterer Reconcile bleiben sichtbar. Das Release-/Recoveryverfahren aus dem vorherigen Blueprint muss auch Callledger und ungeklärte Zustände erhalten; Restore macht alte `dispatching`-Zeilen nicht erneut ausführbar. + +### 12.2 Anschluss an Entitlements und Verbrauch + +`EntitlementPolicy` ist zusätzlich zur AccessPolicy erforderlich, soweit das Produkt die Funktion begrenzt. Für spätere harte Kontingente gilt der kleine lokale Port: + +```python +@dataclass(frozen=True, slots=True) +class BudgetEnvelope: + call_count: int + upper_input_tokens: int | None + upper_output_tokens: int | None + maximum_cost: str | None + cost_basis_revision: str | None + +class UsageBudgetPort(Protocol): + def reserve(self, tx: object, context: RequestContext, + call_id: str, upper_bound: BudgetEnvelope) -> str: ... + def settle(self, tx: object, reservation_id: str, + actual: UsageReport) -> None: ... + def mark_unknown(self, tx: object, reservation_id: str) -> None: ... + def release_unsent(self, tx: object, reservation_id: str) -> None: ... +``` + +Dieser Port ist noch keine Billing-/Quotenimplementierung. Der folgende Entitlements-/Quota-Blueprint konkretisiert Atomarität, Perioden und Buchungsregeln. Ein Produkt ohne harte Quoten braucht nur die technischen Limits und Usageerfassung; es darf deshalb keine zugesicherte Kontingentgarantie behaupten. Ein Produkt **mit** harter Grenze bleibt ohne passenden echten Adapter geschlossen. Mitais heutiges „nach Erfolg hochzählen“ wird nicht als sichere parallele Reservierung oder Abrechnung unbekannter Ergebnisse ausgegeben. Fehlende Usage ist `unknown`, nicht kostenfrei. + +Eine Schätzung ist keine zugesicherte Obergrenze. Der Adapter erhält im `BudgetEnvelope` nur tatsächlich belastbare obere Schranken, ansonsten `None`; er darf eine verpflichtende harte Token-/Kostengrenze dann nicht durch einen Schätzwert freigeben. Die Generate-Callanzahl kann für diesen Schnitt eindeutig mit eins begrenzt werden. Detect-/Toolverbräuche erhalten gegebenenfalls eigene Budgetzwecke und werden nicht unsichtbar in einen Generateerfolg eingerechnet. + +## 13. Fach-API, Fehler und Frontendanschluss + +Es entsteht kein öffentliches „beliebigen Prompt an beliebige URL senden“-API. Fachmodule registrieren konkrete Operationen mit festem Zweck, ResultSpec und serverseitiger Quellenauflösung. Beispiel: `POST /api/v1//{resource_id}/generate` mit `{expected_version, instruction?}`; Session, CSRF/Origin und Scopeheader folgen Phase 3.3. `instruction` ist begrenzter untrusted Eingabetext und Bestandteil der Privacyinventur, keine übergeordnete Policy. + +`Idempotency-Key` ist eine begrenzte kanonische UUID des Fachauftrags; `node_key` setzt der Server. Die Call-ID wird serverseitig erzeugt. Bodyfelder wie `provider_url`, `api_key`, `data_class`, `profile_id`, `privacy_checked`, `precomputed_mappings`, `tools` und frei gewählte `model`-IDs sind im Fach-DTO nicht erlaubt. Ein zugelassener Modellwunsch wäre höchstens ein registrierter serverseitig erneut geprüfter Variantenbezeichner. + +FastAPI-Anschluss als Illustration V/K; das eigentliche Fachmodul implementiert den benannten Service. Synchrone DBphasen liegen innerhalb dessen expliziter Threadbridge, der Gatewayawait enthält keine offene DBverbindung: + +```python +from typing import Annotated +from uuid import UUID +from fastapi import APIRouter, Depends, Header, Request +from pydantic import BaseModel, ConfigDict, Field +from app.api.dependencies import scoped_context +from app.core.context import RequestContext + +class GenerateInput(BaseModel): + model_config = ConfigDict(extra="forbid", strict=True) + expected_version: int = Field(ge=1) + instruction: str | None = Field(default=None, max_length=2000) + +class GenerateOutput(BaseModel): + call_id: str + content: str + +router = APIRouter(prefix="/api/v1/feature") + +@router.post("/{resource_id}/generate", response_model=GenerateOutput) +async def generate( + resource_id: str, body: GenerateInput, request: Request, + context: Annotated[RequestContext, Depends(scoped_context)], + idempotency_key: Annotated[UUID, Header(alias="Idempotency-Key")], +): + return await request.app.state.providers.feature_service.generate( + context, resource_id, body, str(idempotency_key), + ) +``` + +Eine optionale reine Statusroute `GET /api/v1/ai/calls/{call_id}` liefert nur `call_id,status,usage_status,result_ref?` nach aktuellem Recht und Subject-/Scopefilter. Fremder oder unsichtbarer Call: 404. Sie gibt keine Prompts/Manifestlabels/Providerfehler zurück und löst keinen neuen Modellaufruf aus. Ein Review-/Fortsetzungsendpunkt ist produktlokal; er verwendet einen serverseitig gebundenen kurzlebigen Reviewbeleg, nicht `confirmed=true` aus dem Client. Er ändert keinen bestehenden Datenstand ohne den entsprechenden Fach-/CSRF-/Versionsvertrag. + +| HTTP / stabiler Code | Bedeutung und Wirkung | +|---|---| +| 401 `session_invalid` | Kein aktueller Principal; kein Dispatch oder keine Ergebnisfreigabe | +| 403 `capability_denied`, `scope_forbidden`, `ai_policy_denied` | Zugriff/Zweck/Datenklasse/Privacy nicht erlaubt; keine Daten nach außen | +| 404 `not_found` | Fachquelle/Call fremd, unsichtbar oder fehlend | +| 409 `context_changed`, `call_conflict`, `call_in_progress`, `call_outcome_unknown`, `result_unavailable` | Kontext oder Ausführungszustand benötigt bewusste neue Entscheidung; kein automatischer Callretry | +| 409 `privacy_review_required` | Generate noch nicht gesendet; Produkt kann seinen bestehenden lokalen Reviewpfad öffnen | +| 422 `validation_failed`, `prompt_budget_exceeded`, `reserved_identity_syntax`, `unsupported_modality` | Eingabe/Format/Limit vor Versand verweigert | +| 429 `ai_rate_limited` | Explizites Kontolimit bzw. sichere normalisierte Providerbegrenzung; Retry-After begrenzt, keine automatische Mutation | +| 502 `provider_invalid_response`, `output_invalid`, `model_refused` | Upstreamantwort/ResultSpec/Integrität nicht nutzbar; kein Repaircall | +| 503 `ai_unavailable`, `privacy_detection_unavailable`, `ai_busy`, `policy_unavailable` | Fehlende Pflichtadapter/Eignung/Kapazität; keine unsichere Fallbackroute | +| 504 `ai_deadline_exceeded` | Zeitlimit; Outcome kann bereits `sent_or_unknown` sein, kein Erfolg/keine Nullkostenbehauptung | + +RFC-9457-Problemformat mit sicheren Maschinen-/Requestcodes gemäß Foundation. Insbesondere keine Rohwerte in Feldfehlern, keine Unknown-Tokenlabels oder Providerantwortschnipsel in `detail`. Für alle persönlichen Erfolgs-/Fehler-/Statusantworten `Cache-Control: no-store`. Fach-DTOs nennen keine Authcredentials oder Backendproviderprofile. + +Frontend nutzt zentralen Cookie-/CSRF-/Scopeclient, setzt begrenzten KI-Timeout ausdrücklich, zeigt sichere Phasen-/Fehlermeldungen und verwirft alte Resultate/Fehler nach epoch. Ein 403/503 ist kein Logout; ein 504 löst keinen automatischen zweiten Generate aus. Kein persönliches Ergebnis im Service Worker, LocalStorage oder gemeinsamem Modellcache. Ausgabe wird mit dem jeweiligen sicheren Text-/Markdown-/Rich-Textadapter angezeigt. + +## 14. Automatisierte Negativ- und Sicherheitsprüfungen + +Die Matrix ist ein Testauftrag, kein Ergebnisbericht. Verwendet werden synthetische Personen-/Orgdaten, eigene Call-/Providerprofile, Fakedetectoren, Wire-Capture-Transport und isoliertes echtes PostgreSQL mit begrenzter Runtime-Rolle. Keine realen Providerkeys, privaten Textbestände oder Live-Modellaufrufe. Testfakes werden nur über Testproviderverdrahtung bereitgestellt; der Runtimeaufbau kann sie nicht per Flag auswählen. + +Canaries erscheinen in **jedem erlaubten Textkanal**: System-/Developertext soweit unterstützt, User, Historie, Kontext/RAG, Registryalias und JSONschemabeschreibung. Unbekannte Zusatzfelder/Modalitäten erhalten eigene Ablehnungstests. Tests prüfen die an den Providertransport übergebenen endgültigen Bytes und alle erlaubten Transportmetadaten. Nicht nur den Aufruf einer Maskierungsfunktion mocken. Synthetische Wireaufzeichnung bleibt lokal im Test; keine Produktionsdebugfunktion daraus ableiten. + +| ID / Suite | Testfall | Zwingende Assertions | +|---|---|---| +| A01 `test_gateway_access.py` | Keine/abgelaufene Session, falscher Scope, fremdes Profil/Objekt, fehlende Capability | 401/403/404 vor jedem Detect-/Generatezugriff auf fremde Inhalte; keine Cross-Profilequelle | +| A02 | Gemischte eigene/fremde RAG-/Eltern-/Memoryquellen | Jede Quelle scoped geprüft; keine fremden Inhalte/Counts in Kontext, Wire oder Fehler | +| A03 | Sitzung/Mitgliedschaft/Recht nach T1 entzogen, Quelle/Vorlage geändert | T2 verhindert alten Dispatch; kein unverifizierter Neuaufbau | +| A04 | Rechte-/Objektänderung während Generate | Keine unautorisierte Anzeige/Fachspeicherung; Callusage sicher abgeschlossen, kein zweiter Call | +| A05 | Class A, unbekannte Klasse, persönlicher Text als C, vom Client behauptete Klasse | Local-only extern nie gesendet; C nicht als Bypass; Klassifikation serverseitig | +| A06 | Bekannter Providerkey/Private-Keyblock oder credentialhaltige URL im Input | ForbiddenContentGuard blockiert vor Detect/Generate; keine Secretwerte in Fehlern oder Logs | +| I01 `test_egress_inventory.py` | Canaries in sämtlichen Textkanälen und statischer Schema-/Formatinstruktion | Vollständige Inventur/Maskierung/Prüfung; erwarteter endgültiger Body ohne zu schützenden Canaryklartext | +| I02 | Aufgelöster Platzhalter/Frageergänzung erst nach Nutzertextreview | Alte Coverage reicht nicht; fehlende finale Felder neu prüfen oder blockieren | +| I03 | Geänderte Template-/Source-/Registry-/Policyrevision bei precomputed Mappings/Review | Alte Belege zurückweisen; bloßes `full_detection_coverage=true` reicht nicht | +| I04 | Abgeschnittener/fehlender Detectchunk, UTF-8-/Unicodeoffset, Randüberlappung | Coverage-/Spangrounding korrekt; kein Generate bei technischer Lücke; kein stilles Truncation | +| I05 | Detect-Timeout, Nulltreffer, ungültiges Detectschema, unbekannter Typ | Ausfall blockiert; Nulltreffer nicht als semantische Garantie; keine Heuristik-/Wortlistenrettung | +| M01 `test_masking.py` | Vorkommensbezogener Homonymfall, Alias, überlappende Namen, Projektname | Nur passende geerdete Spans; bestätigte/unbestätigte Herkunft getrennt; kein globales Ersetzen aller gleichen Wörter | +| M02 | Zwei parallele Subjects/Scopes mit gleich aussehenden Tokens | Getrennte Manifeste/Antworten, keine globalen Traces oder Cross-Profile-Rehydration | +| M03 | Inaktives Mapping, fremder/erratener Token, reservierte Syntax aus Userquelle | Nur tatsächlich aktive eigene Tokens auflösbar; Injection/unknown Token verweigert | +| M04 | Bekannter Alias vs. unbestätigter Treffer, akzeptierter Modellklartext | Kanonisch/beobachtet korrekt; Prüffassung nicht sichtbare Ausgabe; keine grammatische Umformung | +| P01 `test_provider_policy.py` | Fehlendes/abgelaufenes Eignungsdokument, Boolean-ZDR ohne Beleg, ungeeignete Region/Endpoint | Nicht eligible, keine Generierung; keine pauschale Providerfreigabe | +| P02 | OpenRouter-Payload, ungeeigneter Fallback, nur `data_collection` gesetzt | Gültiger vollständiger Profilvertrag setzt erforderliche Filter; kein Modell-/Providerfallback oder unerlaubter Transform | +| P03 | URL aus Userinput, Suffixtrick, Redirect, DNS-Rebinding, Metadata-/fremde interne IP | Vor bzw. am Connect verweigert; kein Secret an fremdes Ziel; private IP allein ist keine Vertrauenszone | +| P04 | Impliziter Proxy/CA aus Umgebung, falsches Zertifikat, fremder Authheader | `trust_env=False`/explizite CA wirksam; falsches TLS abgelehnt; nur richtiger Profilkey am Ziel | +| P05 | Remote-Klartext-Detect per Devmodus/Flag, Fakeprovider im Runtimeaufbau | Kein Standardbypass; ungeeigneter B-Pfad geschlossen; Tests injecten Fakes ausschließlich lokal | +| P06 | LocalDetectInput gegen Generate-/externes Detectprofil oder mit Registrydaten | Typ-/Rollen-/Trust-Zone-Grenze verweigert; lokaler Detect erhält nur erlaubte Textfelder | +| T01 `test_transport.py` | Body/Modell/Profil/Policy nach Seal verändert, abgelaufene Permit | Kein Versand; Bytehash-/Revisions-/Zeitbindung greift | +| T02 | Genau ein erlaubter Send, danach erneute Permitverwendung | Keine zweite Sendung; Wirebytes entsprechen finaler Prüfung, keine nachträglichen SDKfelder | +| T03 | Connect-/Pool-/Read-/Writefehler, langsam kontinuierlicher Stream | Einzel-/Gesamtlaufzeitgrenzen; Ressourcen frei; nach möglichem Versand Outcome unknown statt kostenfrei | +| T04 | 429/5xx, ungültiges JSON, Refusal, Disconnect nach Providerannahme | Kein versteckter Retry/Repaircall; sichere Fehler; keine Behauptung „Provider hat abgebrochen“ | +| T05 | Queue/Pool voll, mehrere Prozesse, riesige Input-/Responsebody | Begrenzte Ablehnung und gemessene Limits; keine Poolumgehung oder unbeschränkte `.json()`-Allokation | +| O01 `test_model_output.py` | Falsche Envelope/Choice/Finishreason, Reasoning/Toolblocks | Nur erlaubte Formate; keine versteckten Tools/Reasoninginhalte in Ergebnis/Historie | +| O02 | Valides JSON mit falschem Schema/extra Feldern/NaN/Grenzwerten | Lokales striktes ResultSpec tatsächlich geprüft; keine TODO-Schemaannahme oder Repairgenerierung | +| O03 | Unbekannter/inaktiver Token, unzulässige Identitätsvermutung | Ausgabe verworfen, keine fremde Lookupauflösung; Egress nicht nachträglich als ungeschehen erklärt | +| O04 | Rehydration in JSONtext gegenüber Keys/IDs/Zahlen/URLs | Nur erlaubte Textpfade; Schema nach Rehydration nochmals gültig | +| O05 | Persönlicher Upstreamdelta-/Fehlerstream vor Validierung | Kein Rohdelta an Browser/Debug; begrenztes Puffern bzw. Ablehnung, nur sichere Fortschrittsereignisse | +| O06 | Modellantwort mit Remote-Bild/HTML/aktivem Link oder Identitätstoken in URL | Kein automatisches Browser-/Serverfetch und keine private Rehydration in Linkziele; sicherer Renderer | +| C01 `test_gateway_calls.py` | Parallele gleiche Idempotenz, geänderter Fingerprint, alter Scope | Ein Send höchstens, 409 bei Konflikt; jeder Lookup aktuell autorisiert | +| C02 | Prozessabbruch vor/nach Dispatchintent bzw. nach Ergebnis, vor Abschlusscommit | Keine automatische erneute Sendung; unknown/persistierte Resultreferenz korrekt | +| C03 | Metadaten-/Auditfehler vor Dispatch vs. danach | Vorher kein Versand; nachher sichtbarer ungeklärter Zustand, keine Erfolgsausgabe oder heimliche Wiederholung | +| C04 | Usage fehlt, echte Nullusage, abgeschätzte statt oberer Budgetgrenze | Unknown von null getrennt; harte Quoten nicht durch unbewiesene Schätzung freigeben | +| C05 | Restore alter offener Calls, Fingerprintkeywechsel | Alte dispatching/unknown Calls werden nicht automatisch ausführbar; Idempotenz-/Key-ID-Vertrag bleibt nachvollziehbar | +| L01 `test_ai_diagnostics.py` | Providerfehler enthält Canary/Prompt/Key, Exception/Repr/Log/APM | Keine sensitiven Spiegelungen in HTTP/Logs/DTOs; Maskierungszähler statt Labels | +| L02 | Debugberechtigung, gespeicherte Fachquelle, temporäres Mapping | Debug exportiert keine Volltexte/Mapping; Fachquellbewahrung unverändert; Callmapping nur lokal | +| F01 Frontend-/APItests | Fehlende CSRF/Scope, fremde Call-ID, extra Providerbodyfelder | Phase-3.3-/DTO-Verträge wirksam; keine generische freie Proxyroute | +| F02 | Scopewechsel/Logout mit verspäteter KIantwort/401/504 | epoch verwirft alte Antworten/Fehler; kein Autoretry, 403/503 kein Logout | + +### 14.1 Anschluss an vorhandene Testquellen I + +- [Kanshō Manifestfälle](C:/Dev/Kansho/backend/tests/test_privacy_manifest.py:70): aktive/inaktive Mappings, Homonyme, Alias-/Prüffassung und Rehydration übernehmen; um komplette Payload-/Scoped-/Wirebindung erweitern. +- [Kanshō Span-/Pre-Egress-Test](C:/Dev/Kansho/backend/tests/test_privacy_response_integrity.py:102): Spangrounding, Überlappung und Blockade vor Provider als Ausgangsfälle. +- [Kanshō Detectionverträge](C:/Dev/Kansho/backend/tests/test_privacy_detect.py:1): Fakes belegen Schema/Fail-Closed-Verhalten, ausdrücklich keine Livequalität. +- Kanshō verwendet einen [eigenen pytest-Collector](C:/Dev/Kansho/backend/tests/conftest.py:49), der Testskripte über `main()` als je einen Fall sammelt. Eine Testdatei oder gefundene Hilfsfunktion beweist deshalb weder einzelne pytest-Coverage noch Erfolg. Im neuen Zielaufbau diese Fälle als einzeln benannte native pytest-Tests mit konkreter Pflichtcollection anlegen; Bestandscollector nicht pauschal kopieren. + +Integrationstests verwenden echten isolierten PostgreSQLzustand nach dem Releaseblueprint. Reine Transformationen laufen ohne DB/Netz, Transporttests mit Fake-/Wireadapter. Nach Einführung eines tatsächlichen lokalen Detectors ist eine separate synthetische Qualitätsauswertung mit benanntem Modell/Stand nötig; sie wird nicht aus Mocktest-Erfolg abgeleitet. Reale persönliche Providererprobung ist nicht Teil dieser Lieferung oder Pflicht-CI. + +## 15. Implementierungsauftrag für Cursor und nachfolgende Blueprints + +**Dieser Abschnitt wird hier nicht ausgeführt.** Der spätere Auftrag benennt das Zielrepository und die erste tatsächliche KI-Funktion. Ohne konkrete Zielfunktion keine bestehende App als allgemeines Gatewayframework umbauen. + +1. Foundation v0.3, Phase-3.3-Kontext/Access/UoW und Releaseblueprint beibehalten. Lokales Gatewaymodul mit explizitem Composition Root/Ports aufbauen; keine Cross-Repoimporte oder neue zentrale Inferenzplattform. +2. Kanshōs Maskierungsmanifest, Span-/Alias-/Registryregeln und Pre-Egress-Reihenfolge gezielt übertragen. Aktuelle Source-/Profil-/Policy-/Inventurbindung und Callisolation ergänzen. Vorhandene Globaldiagnose, Fake-Runtimeflags und pauschale Local-URL-Vertrauensprüfung nicht übernehmen. +3. Den einen Fachzweck mit erlaubten Quellen/Feldern, B/C-Regel, Vorlage und lokalem ResultSpec registrieren. Scoped Materialisierung über vorhandene Repositories; keine neue Prompt-/Workflowengine. Mitais späteren Adapter an `RenderedPrompt`/`ModelGateway.complete` binden. +4. Echte lokale Detect-/Reviewadapter und Profil-/Secret-/Eligibilityadapter anbinden, soweit vorhanden. Für Tests ausschließlich synthetische Fakes. Fehlende reale Eignung/Detection lässt persönlichen Egress geschlossen und wird als offen dokumentiert; keine echten Keys/privaten Texte zu „Smokezwecken“ verwenden. Kein neuer Detectdienst wird automatisch installiert. +5. Payloadinventur, technische Coverage, Spangrounding, aktive Manifestmaske und den finalen Byte-Seal implementieren. Unbekannte Zusatzfelder, Klasse A, reservierte Tokeninjektion und ungeklärte Konflikte sperren. Keine ungescannten Format-/Systemtexte nachreichen. +6. Async-HTTPadapter im Lifespan mit expliziten Endpunkten/TLS/Proxygrenzen, null Retries, Pool-/Admission-/Bodylimits und monotoner Gesamtdauer implementieren. Synchrone DBphasen in getrennten Threadbridge-UoWs; kein SQL-/HTTPmix in einer offenen Transaktion. OpenRouterparameter nur bei tatsächlich entsprechend eligible Profil verwenden. +7. Callledger/Uniqueconstraints und T1/T2/T3 mit aktuellem Recht, Quellen-/Profilrevision, Dispatchintent, Audit und konservativem unknown-Zustand implementieren. Ergebniswrite atomar mit fachlichem Audit. Reviewfortsetzung exakt binden; keinen booleschen Clientnachweis akzeptieren. +8. Envelope-, JSON-/Pydantic-, Token-/Privacyprüfung und lokale Rehydration implementieren. Kein Live-Rohstream oder Repaircall. Akzeptierten Journaltext nicht nachträglich umschreiben. Usage unbekannt korrekt erhalten, Quotenport nur bei realer Anforderung verdrahten. +9. Fachrouter/Statusroute mit Auth-/CSRF-/Scope-/Idempotenzvertrag und sicheren Problemcodes anbinden. Zentralen Frontendclient/epoch beibehalten, begrenzten KI-Timeout lokal setzen, Ausgabe sicher rendern; keine persönlichen Webcaches oder Providerkeys im Frontend. +10. Native Tests aus Abschnitt 14 tatsächlich sammeln/ausführen, Wirecanaries über alle Kanäle und negative Nebenpfade prüfen. In beiden Releasevarianten blockieren fehlende/rote KI-Pflicht-Gates vor Produktion. Produktionsmodus ebenfalls isoliert mit synthetischen Profilen prüfen; kein Devflag lockert Privacy. Ergebnisbericht nennt Commit, Image-/Policy-/Profil-/Detectorstand, Tests/Umgebung und offene Adapter. Nur tatsächliche bestandene Tests als T kennzeichnen. + +Der **nächste Prompt-/Platzhalter-/Workflow-Blueprint** konkretisiert Vorlagenversionierung, Registrierungen, Graph-/Nodezustände und Wiederaufnahme. Er konsumiert diesen Gatewayvertrag; jeder Modellnode erhält ihn, ohne Privacy und Providertransport nochmals zu erfinden. Der **anschließende Entitlements-/Verbrauch-/Quota-Blueprint** konkretisiert Reservierung/Abrechnung, insbesondere parallele und unbekannte Ergebnisse. Beide werden durch dieses Dokument nicht automatisch gestartet. + +Abnahme eines späteren ersten vertikalen Slices: autorisierte synthetische Quelle → vollständig gerenderter Prompt → lokale Detection/Maskierung → nachweislich geprüfte Wirebytes zum Fakeprovider → valides maskiertes Ergebnis → nur eigene lokale Rehydration → aktuell autorisierte Ausgabe/atomarer Fachwrite. Cross-Scope-Daten, Direct-HTTP-Bypass, unbekannter Outcome und ungültige Antwort müssen dabei sichtbar verweigert werden. Ein grüner Slice bleibt ein begrenzter Integrationsnachweis, keine universelle Detektions-/Produktreifezusage. + +## 16. Prüfstand dieser Lieferung + +Erstellt wurde ausschließlich dieses neue Blueprintdokument. Produktrepos, Foundation, Auth- und Releaseblueprint blieben unverändert. Keine Codeimplementierung, Modell-/Live-APIaufrufe, produktiven Credentials/Datenbanken, privaten Testtexte, Paketinstallationen, Migrationen, Deployments oder Anwendungstestläufe. + +Dokumentprüfung umfasst lokale Referenzen/Zeilen, Python-/JSONbeispielsyntax und Konsistenz von Context-/Provider-/Payload-/Call-/Fehler-/Testverträgen. Das ist kein T-Nachweis für die geplante Lösung. Technische Providerdetails wurden begrenzt gegen offizielle OpenRouter-/HTTPX-Dokumentation geprüft; konkrete Account-/Endpointbedingungen und lokale Detectorqualität wurden nicht erhoben oder freigegeben. + +### 16.1 Lokaler Quellstand + +Lesestand 16.10.2026. Hashes über vollständige Dateien; Git-HEAD allein ist kein Beleg eines sauberen Checkouts. + +- `Kansho`: Git-HEAD `89d149684eab9211d6ef21181d018de097a61783` +- `shinkan-jinkendo`: Git-HEAD `f10c28e5cdcef52cc44e953a8494b4bbe35b77fe` +- `mitai-jinkendo`: Git-HEAD `95453d548a2113555cd7e8f01fbbf267cbe34f3f` +- `kairo-jinkendo`: Git-HEAD `ea0aa18b8dd9a55f663a996d74e63b7e3ee0dc16` + +| Gezielt verwendete Produktquelle | SHA-256 | +|---|---| +| [Kansho/backend/privacy_gateway.py](C:/Dev/Kansho/backend/privacy_gateway.py) | `0e729287b6a87ba1a8ef92c6dce27cc3c3e1e829b6958130e59b4e90ff2a3d74` | +| [Kansho/backend/providers.py](C:/Dev/Kansho/backend/providers.py) | `86b6924d680ce8fe35e723f82226ac5c76bb7abe900fbdec1c20250de7af069f` | +| [Kansho/backend/provider_settings.py](C:/Dev/Kansho/backend/provider_settings.py) | `c38b352b289bbe6cce46d5d8482f26aabc4af8e29b8e3e6cd8f16460f98a122f` | +| [Kansho/backend/engine.py](C:/Dev/Kansho/backend/engine.py) | `79b86c6ff69ff87ea4e02c26203ac39beebccf2cce7078ed246ae73971488159` | +| [Kansho/backend/context_builder.py](C:/Dev/Kansho/backend/context_builder.py) | `712cb720267b57ac7fe471d7ec2a7cb25d9cd41cf8a19d63a8b083599c96586a` | +| [Kansho/backend/prompt_budget.py](C:/Dev/Kansho/backend/prompt_budget.py) | `b95a36a6cd9e0ee704cd88b495bf9475230cdf5f0a2cb711458f27382af2be78` | +| [Kansho/backend/tests/test_privacy_manifest.py](C:/Dev/Kansho/backend/tests/test_privacy_manifest.py) | `b48e16b901668efcd31f1534575400836cd3f68e5bd658d711ac7429c23526c5` | +| [Kansho/backend/tests/test_privacy_response_integrity.py](C:/Dev/Kansho/backend/tests/test_privacy_response_integrity.py) | `b98035d558007b84c268b6d1b03e28d5b3b35f1984f821b6bbce9e9e84e6ae38` | +| [Kansho/backend/tests/test_privacy_detect.py](C:/Dev/Kansho/backend/tests/test_privacy_detect.py) | `7b1043509fbe173f02e6ef050e2527a7adb27919dfbc1265832533e5c9d50347` | +| [Kansho/docs/architecture/functional/guardrails.md](C:/Dev/Kansho/docs/architecture/functional/guardrails.md) | `deadd95b5019fe807026616f6ff74a2467d9d951702c032573d59f27c125dc4b` | +| [Kansho/docs/architecture/technical/privacy_gateway.md](C:/Dev/Kansho/docs/architecture/technical/privacy_gateway.md) | `496c8661f645b8935edc8ce46214cfda3becca2588125eae345a7a860d9a07c5` | +| [shinkan-jinkendo/backend/openrouter_chat.py](C:/Dev/shinkan-jinkendo/backend/openrouter_chat.py) | `606941440d7a7dd0a971cc0606e4ed8a5ad07f0b454374dc25dab8dd5c8a149a` | +| [mitai-jinkendo/backend/prompt_executor.py](C:/Dev/mitai-jinkendo/backend/prompt_executor.py) | `7e0e97047fe16d7b5efb92ccbe573b6459c4d32b41931aa9e33d6f00f14028da` | +| [kairo-jinkendo/backend/config_service.py](C:/Dev/kairo-jinkendo/backend/config_service.py) | `5d4f4b75216fe5915874ee9db1776354bdf91f233286f29ea71ff112e2f5555e` | +| [Kansho/backend/tests/conftest.py](C:/Dev/Kansho/backend/tests/conftest.py) | `15c8a860538203e2dd63ee459b187cfb9fb586585e32a4c665ed74646c3f5ed8` | +| [Kansho/backend/pytest.ini](C:/Dev/Kansho/backend/pytest.ini) | `cb919d485cff5f19a829ec584bf12019b4d7b6c4eb03e9254d690416b6e38a94` | + +**Ende dieses Blueprintauftrags. Keine Implementierung und kein weiterer Blueprint werden automatisch gestartet.** diff --git a/docs/reference/Jinkendo_Auth_Session_Scope_Blueprint.md b/docs/reference/Jinkendo_Auth_Session_Scope_Blueprint.md new file mode 100644 index 0000000..c151901 --- /dev/null +++ b/docs/reference/Jinkendo_Auth_Session_Scope_Blueprint.md @@ -0,0 +1,773 @@ +# Jinkendo – Auth, Session & Scope Blueprint + +**Phase 3.3 · v0.1 · 16.10.2026 · Grundlage: Application Foundation v0.3** + +## 1. Geltung, Ergebnis und Nachweis + +Dieser Blueprint konkretisiert die beschlossenen Auth-, Identitäts- und Datenraumverträge für die spätere Umsetzung in Phase 3.4. Er verwendet produktlokale Konten, PostgreSQL-Sessions, FastAPI-Abhängigkeiten und zentrale Zugriffsregeln. Es entstehen weder ein neuer zentraler Dienst noch eine gemeinsame Tenant-Fachdatenbank. Bestehende Anwendungen werden durch diesen Auftrag nicht geändert. + +Maßgeblich sind die [technische Referenzarchitektur v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md), der [Foundation-Blueprint v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md) und die [technischen Festlegungen v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md). Dieser Text ergänzt deren Ports; er ersetzt die Foundation nicht. + +Die vom Auftraggeber beschlossenen ADR-01 bis ADR-14 gelten weiter. Besonders relevant sind ADR-02/03/04/05/06/08/11/12/13/14. Der [Phase-2-Registertext](C:/Dev/jinkendo-architecture-consolidation-phase2-v0.2-2026-10-15/05_Architecture_Decision_Register.md) enthält historische Empfehlungs-/Freigabeformulierungen; daraus wird keine erneute Grundsatzfreigabe abgeleitet. ADR-15/16 werden hier nicht entschieden. + +**Nachweisstatus:** V = vorgeschlagene technische Ausgestaltung; I = vorhandene, statisch nachgelesene Implementierungsreferenz; T = tatsächlich bestandener Test mit Stand, Umgebung und Umfang; K = noch nicht integrierte oder getestete Kombination. Dieser Blueprint ist **V/K**. Seine Code- und SQL-Ausschnitte sind Spezifikationen, keine ausgeführte Implementierung. Referenzdateien und vorhandene Testassertionen sind I. In dieser Phase wurden keine Anwendungstests ausgeführt; es wird kein T-Nachweis und keine Produktionsreife behauptet. + +### 1.1 Verbindliche Verträge und technische Defaults + +| Verbindlicher Architekturvertrag | Technischer Default dieses Blueprints | +|---|---| +| Identität ausschließlich aus geprüftem Credential und aktuellem lokalem Konto; keine Clientrolle als Autorität | Opaque Browser-Session, 32 Zufallsbytes, SHA-256-Verifier in PostgreSQL | +| Server prüft Ablauf, Widerruf und Kontostatus; MFA-Zwischenzustände öffnen keine Fach-API | 30 Minuten Inaktivität, 12 Stunden absolute Laufzeit, explizite Rotation nach 15 Minuten aktiver Nutzung | +| Browser-Cookie HttpOnly/Secure, begrenzte Cookiegeltung und wirksamer CSRF-/Origin-Schutz | `__Host-jinkendo-session`, `Path=/`, kein `Domain`, `SameSite=Lax`; Synchronizer-Token | +| Datenraumgrenze, Mitgliedschaft, Capability und Objektregel müssen zusammen erfüllt sein | Explizites Headerpaar `X-Scope-Kind` / `X-Scope-Id`; lokale Registry statt zusätzlichem Policyframework | +| Fail closed; Autorisierung und Änderung teilen dieselbe Transaktion; auditpflichtige Änderung samt Audit atomar | Synchrone FastAPI-Services und Psycopg-3-UoW gemäß Foundation | +| Privilegierte Betreiberaktionen benötigen MFA, sichere Recovery und Audit | Shinkan-TOTP-Verfahren, Replayzähler, fünf Minuten MFA-Frische, lokal verschlüsseltes Faktor-Secret | +| Release-Gate vor Produktion, menschliche Freigabe und eindeutige getestete/ausgelieferte Version | Foundation R1 bevorzugt; kontrollierte getrennte Builds R2 weiterhin zulässig | + +Zahlen, Dateianordnung und konkrete Bibliotheksadapter sind begründbar anpassbare Ausgangswerte. Schutzwirkungen und veröffentlichte Schnittstellen dürfen dabei nicht stillschweigend entfallen. Anpassung und zugehöriger Testnachweis gehören in den konkreten Produktauftrag; hierfür entsteht kein zusätzlicher ADR- oder Freigabezyklus. `SameSite=None`, ein breites Cookie-Domainattribut oder ein Autorisierungs-Bypass sind keine bloße Timeoutanpassung. + +## 2. Gezielte Wiederverwendung und Quellenbasis + +Ausgangspunkt sind die [Phase-3.1-Wissenselemente](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json), das [Quellenregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/sources.json), das [Testregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/tests.jsonl) und die [Guardrailabschnitte](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/guardrails_source_register.jsonl). Nachgelesen wurden die betroffenen Mechanismen und ausgewählte Tests; keine vollständige Repository-Neuanalyse und keine neue Produktreifebewertung. + +| Referenz / Phase-3.1-Anker | Vorhandener Mechanismus I | Konkrete Übernahme und erforderliche Anpassung V/K | +|---|---|---| +| Shinkan, KI-SHK-11; [Sessionprüfung](C:/Dev/shinkan-jinkendo/backend/auth.py:74), [Login](C:/Dev/shinkan-jinkendo/backend/routers/auth.py:150) | Kryptografischer Zufall, Sessionzwecke, bcrypt-Prüfung mit Dummyvergleich, begrenzte Sessions, Widerruf | Zustandsablauf übernehmen. Cookie-Transport, gehashte Sessionverifier, Idle-/Absolutfrist, Rotation und eine atomare Abschlussprüfung ergänzen. Aktuelle Header-/Klartextspeicherung nicht kopieren. | +| Shinkan, KI-SHK-11; [Kontozustände](C:/Dev/shinkan-jinkendo/backend/account_lifecycle.py:26), [Onboardingtests](C:/Dev/shinkan-jinkendo/backend/tests/test_account_onboarding_gate.py:15) | Unbestätigt, bestätigt ohne Verein, aktives Mitglied; eigene Onboardingpfade | Zustände und gezielte Freigaben als lokaler Policyadapter. Fehlender Zustand wird niemals implizit `active_member`; Clubmitgliedschaft wird keine Voraussetzung einer reinen persönlichen App. | +| Shinkan, [Tenantauflösung](C:/Dev/shinkan-jinkendo/backend/tenant_context.py:201), [Sichtbarkeit](C:/Dev/shinkan-jinkendo/backend/tenant_context.py:57) | Aktive Mitgliedschaften und zentrale privat/Verein/offiziell-Regeln | Mitgliedschaftsprüfung und gemeinsame Listen-/Objektprädikate übernehmen. `min(club_ids)` und `invalid_header_policy="ignore"` nicht übernehmen. Plattform-Sonderleserechte bleiben eine ausdrücklich produktlokale Regel. | +| Shinkan, KI-SHK-03; [Capabilities](C:/Dev/shinkan-jinkendo/backend/capabilities.py:39), [Registry](C:/Dev/shinkan-jinkendo/backend/rights_registry.py:20) | Capabilitydefinitionen, Rollenbezug, Kontostatus und getrennte Features | Kleiner Registrierungstyp und zentrale Entscheidung. Neue Pfade erzwingen immer; kein `CAPABILITY_ENFORCE=0`. Doppelte IDs stoppen den Aufbau; Runtime synchronisiert keine Rechte per DDL/Upsert. | +| Shinkan, [TOTP](C:/Dev/shinkan-jinkendo/backend/totp_auth.py:24), [Recoveryverbrauch](C:/Dev/shinkan-jinkendo/backend/routers/auth.py:303) | TOTP-Zeitfenster und bedingtes `UPDATE … used_at IS NULL RETURNING` | Algorithmus und atomaren Einmalverbrauch übernehmen. Akzeptierten TOTP-Zähler zurückgeben und atomar speichern; stärkere Recoverycodes, verschlüsseltes Faktor-Secret und verpflichtende Betreiber-MFA ergänzen. | +| Mitai, KI-MIT-04/06; [Auth](C:/Dev/mitai-jinkendo/backend/auth.py:43), [Profilauflösung](C:/Dev/mitai-jinkendo/backend/routers/profiles.py:20) | Konto-/Profilbindung im Sessionjoin; daneben ungeprüfter Profilheader/Erstprofilfallback | Konto=Profil bleibt als Adapter möglich. `get_pid`, allgemeine Profilverwaltung mit bloßem Login und volle Sessions in Medien-/SSE-URLs werden ausdrücklich nicht übernommen. | +| Kairo, KI-KAI-03/04/06; [Actor-Token](C:/Dev/kairo-jinkendo/backend/services/actor_service_tokens.py:76), [Operational Auth](C:/Dev/kairo-jinkendo/backend/operational_auth.py:30), [Tenant](C:/Dev/kairo-jinkendo/backend/tenant_context.py:91) | Hashspeicherung, Actor/Tenant-Bindung und getrennte technische Authentifizierung; aktuelle Mitgliedschaftsprüfung | Spätere Machine-Ports an diesem Mechanismus ausrichten. Leere Rechte ergeben keine Standard-Manage-Rechte, Ablauf ist Pflicht, aktuelle Actor-/Delegationspolicy begrenzt den Token. Kein Sessiontoken im RequestContext. | +| Kanshō, KI-KAN-03/04; [Auth](C:/Dev/Kansho/backend/auth.py:31), [Journalrouter](C:/Dev/Kansho/backend/routers/journal.py:185), [Ownerfilter](C:/Dev/Kansho/backend/journal_store.py:80), [Spaceprüfung](C:/Dev/Kansho/backend/journal_store.py:124) | Identität aus Session; persönlicher Raum und Objektzugriff über `profile_id`; fremde/unsichtbare Räume verweigert | Ownergebundene Abfragen und Weitergabe des geprüften Profils übernehmen. Reflection Space bleibt fachlicher Unterraum eines persönlichen Zugriffskontexts; sein Name „Beruf“ macht ihn nicht zu einem Organisationsmandanten. | + +Relevante registrierte Shinkan-Guardrails: `GR-SHK-0015-0063` Portalrollen, `GR-SHK-0015-0072` Vereinsrollen und `GR-SHK-0015-0103` eigene Kontofunktionen/Onboarding. Diese Quellen unterscheiden Zielbeschreibung und Code. Die [Kanshō-Privacy-Invariante](C:/Dev/Kansho/docs/architecture/functional/guardrails.md:81) bleibt erhalten: Identität lokal, externe KI nur über das Privacy Gateway. Eine erfolgreiche Authentifizierung erlaubt keinen direkten Export persönlicher Kontexte an Modelle. + +Die folgenden Entscheidungen schließen gezielt die Adapterlücken. Es wird kein Produkt vollständig kopiert und kein neuer universeller Sicherheitskern entwickelt. + +## 3. Komponenten und Einbindung in die Foundation + +```text +Browser → Same-Origin-Proxy → FastAPI BrowserBoundary + → PrincipalResolver + → ScopeResolver + → Fachservice/UoW → AccessPolicy → Repository + → Audit (dieselbe Transaktion) + +Auth-Router → SessionService / MfaService → AuthRepository / AccountAdapter + → PasswordVerifier / FactorSecretCipher +``` + +| Komponente / bevorzugter Ort | Verantwortung | Darf nicht | +|---|---|---| +| `core/context.py`, `core/ports.py` | Unveränderliche Verträge, Ports; keine DB- oder Routerimporte | Passwörter, Cookie-/Bearerwerte oder persönliche Inhalte tragen | +| `api/browser_boundary.py` | Cookie-/Headermehrdeutigkeit, Origin, Fetch Metadata, CSRF-Transport, Content-Type | Mitgliedschaft durch einen Header behaupten | +| `modules/auth/router.py`, `schemas.py` | Explizite DTOs und Cookieausgabe erst nach Servicecommit | In Dependencies per `yield` nachträglich committen | +| `modules/auth/service.py`, `repository.py` | Login, Sessionzustand, Rotation, Widerruf, begrenzte Authflows | Fehlversuchszähler durch anschließendes Exception-Rollback verlieren | +| `modules/auth/mfa.py`, `credentials.py` | Shinkan-TOTP, Replay-/Recoveryprüfung, bcrypt, lokale Secretverschlüsselung | Eigene Verschlüsselung oder einen „Admin ohne MFA“-Runtimepfad ergänzen | +| `modules/access/scope.py`, `policy.py`, `registry.py` | Lokale Konto-/Scope-/Rollen-/Objektregeln; gemeinsame Sichtbarkeitsprädikate | Universelle Tenant-Fachdatenbank oder generischen ACL-Editor auf Vorrat bauen | +| `api/dependencies.py` | Ports aus `app.state.providers` beziehen, Context konstruieren | Globale mutable Profil-ID, DB-Verbindung oder Allow-all-Fallback halten | +| Produktadapter | Bestehende Konto-, Profil-, Mitgliedschafts- und Objektmodelle abbilden | Andere Repositories zur Laufzeit importieren | +| Frontend `shared/session`, `shared/api` | Session-/Scopezustand, CSRF im Speicher, epoch/Abort, ein Transportclient | Sessioncredential in Web Storage oder einen API-/KI-Cache schreiben | + +`create_app(settings, providers)` registriert explizit Browserboundary, Problemhandler und Router. `bootstrap` verdrahtet echte Adapter. Import bleibt ohne DB-/Netzkontakt möglich. Fehlende Pflichtadapter verhindern Readiness und lassen geschützte Pfade mit 503 geschlossen; kein Testfake in Runtime. Ein persönliches Produkt benötigt keinen Organisationsadapter: nicht registrierte Scopearten werden verweigert. + +`BrowserBoundary` bietet `require_request(request)` für Host/Origin/Customheader/Content-Type und `require_session_csrf(request, principal)` bzw. `require_flow_csrf(request, flow)` für unsichere Methoden. Die jeweilige Route hat genau einen Credentialzweck; diese Methoden versuchen keinen alternativen Authtransport. Sichere Reads prüfen keinen CSRF-Wert. Login-/MFA-Flows nutzen eigene Dependencies statt der folgenden Sessiondependency. + +Die Foundation-UoW liefert eine begrenzte Psycopg-3-Verbindung. Repository und Policy erhalten genau dieses `tx`; keine versteckten `get_db()`-Aufrufe. Schema/Seeds laufen über den expliziten Migrationsweg mit anderer DB-Rolle. Rechte-Registrierungen werden bei der Konstruktion unveränderlich; Duplicate-IDs und Routen mit unbekannter Capability sind Aufbaufehler. + +## 4. Identitäts- und RequestContext-Vertrag + +Die folgenden Typen präzisieren die Foundation-Verträge. IDs bleiben außen opaque Strings; bestehende numerische Profil-/Club-IDs können Adapter kanonisch als String abbilden. Keine zufällige Gleichsetzung von IDs verschiedener Produkte. + +```python +from dataclasses import dataclass +from datetime import datetime +from typing import Literal, Protocol +from fastapi import Request + +ScopeKind = Literal["personal", "club", "organization"] + +@dataclass(frozen=True, slots=True) +class ScopeRef: + kind: ScopeKind + scope_id: str + +@dataclass(frozen=True, slots=True) +class ScopeSelection: + kind: ScopeKind + scope_id: str + +@dataclass(frozen=True, slots=True) +class Principal: + kind: Literal["human", "machine"] + subject_id: str + actor_id: str | None + credential_id: str # interne Session-/Credential-ID, kein Secret + credential_generation: int + auth_time: datetime + mfa_verified_at: datetime | None + session_mode: Literal["full", "onboarding", "machine"] + +@dataclass(frozen=True, slots=True) +class RequestContext: + request_id: str + principal: Principal + scope: ScopeRef | None # None nur für explizit scopefreie Operationen + +@dataclass(frozen=True, slots=True) +class ResourceRef: + kind: str # registrierter Objekttyp + resource_id: str + +class Tx(Protocol): + """Foundation-Transaktionshandle; SQL nur in Repositoryadaptern.""" + +class PrincipalResolver(Protocol): + def resolve(self, request: Request) -> Principal: ... + +class ScopeResolver(Protocol): + def resolve(self, principal: Principal, + selection: ScopeSelection) -> ScopeRef: ... + def require_current(self, context: RequestContext, tx: Tx) -> None: ... + +class AccessPolicy(Protocol): + def require(self, context: RequestContext, capability: str, + resource: ResourceRef | None, tx: Tx) -> None: ... +``` + +Die Resolver führen kurze lokale Lese-/Sessionaktivitätstransaktionen aus und schließen sie vor dem Fachservice. Der Context ist deren verifizierter Snapshot, **keine dauerhaft gültige Berechtigung**. `AccessPolicy.require` prüft im Fachservice erneut Credential, Generation, Konto, Scope und Rechte mit demselben `tx` wie der Objektzugriff. Erst diese Prüfung autorisiert die konkrete Operation. Rollen und Capabilities werden aus aktuellem serverseitigem Zustand geladen; UI-Capabilitylisten sind reine Darstellungshilfen. + +Für Menschen gilt `actor_id=None`, sofern das Produkt keinen echten Human-Actor benötigt. Für Maschinen ist `subject_id` die lokale technische Identität und `actor_id` erforderlich; kein erfundenes Benutzerkonto. Browser-MFA-Zwischenflows erzeugen überhaupt keinen Principal. `request_id` stammt aus dem Foundation-Vertrag; beliebige Clientstrings werden nicht unvalidiert geloggt. + +### 4.1 FastAPI-Anschluss des geschützten Fachpfads + +Illustration V/K für `api/dependencies.py` und einen Fachrouter. Die hier verwendeten Adaptermethoden werden in Abschnitt 3/6/9 beschrieben; `scope_selection_from_headers` validiert das strikte Headerpaar und liefert eine `ScopeSelection`. Der RequestContext enthält keine Connection; der Service öffnet seine eigene UoW und wiederholt dort die aktuelle Accessprüfung. + +```python +from typing import Annotated +from fastapi import APIRouter, Depends, Request +from pydantic import BaseModel, ConfigDict, Field +from app.core.context import Principal, RequestContext + +def browser_principal(request: Request) -> Principal: + providers = request.app.state.providers + providers.browser_boundary.require_request(request) + principal = providers.principal_resolver.resolve(request) + providers.browser_boundary.require_session_csrf(request, principal) + return principal + +def scoped_context( + request: Request, + principal: Annotated[Principal, Depends(browser_principal)], +) -> RequestContext: + providers = request.app.state.providers + selection = providers.scope_selection_from_headers(request.headers) + scope = providers.scope_resolver.resolve(principal, selection) + return RequestContext(request.state.request_id, principal, scope) + +class RenameInput(BaseModel): + model_config = ConfigDict(extra="forbid", strict=True) + title: str = Field(min_length=1, max_length=200) + expected_version: int = Field(ge=1) + +class RecordOutput(BaseModel): + id: str + title: str + version: int + +router = APIRouter(prefix="/api/v1/personal/records") + +@router.patch("/{record_id}", response_model=RecordOutput) +def rename_record( + record_id: str, body: RenameInput, request: Request, + context: Annotated[RequestContext, Depends(scoped_context)], +): + return request.app.state.providers.record_service.rename_record( + context, record_id, body, + ) +``` + +Das Beispiel baut kein neues Fachmodul. Es zeigt die unmittelbar zu verwendende DI-Form. Scopefreie Kontooperationen erhalten eine eigene `account_context`-Dependency mit `scope=None` und fester Self-Policy; dieselbe Funktion darf nicht automatisch scoped Fachrouten versorgen. Responseklassen im späteren Fachmodul werden konsistent benannt; `RecordView` im Servicebeispiel meint dessen explizites Ausgabe-DTO. + +### 4.2 Konto- und Profilautorität + +Der lokale AccountAdapter liefert mindestens `subject_id`, `status`, `security_epoch`, `email_verified`, `password_hash`, `password_revision` und eine explizite Zuordnung zum eigenen Profil sowie zur Betreiberrolle. `status ∈ {enabled, disabled, deleted}`; unbekannt/fehlend verweigert. Passwort oder Faktor-Secret verlassen den Credentialadapter nicht. + +Für den Neuaufbau ist ein lokales Konto zugleich der Eigentümer des persönlichen Scopes (`scope_id=subject_id`). Mitais Bestandsvariante darf `subject_id=profile_id` abbilden. Ein Produkt mit getrenntem Login-/Personenprofil führt eine eindeutige serverseitige Zuordnung; kein Raten nach E-Mail oder erstem Datensatz. Mehrprofildelegation wird erst mit ausdrücklichem Fachvertrag ergänzt. + +`email_verified` und aktive Clubmitgliedschaft sind zusätzliche Policybedingungen. Shinkans `unverified → verified_pending_club → active_member` bleibt im Clubadapter. Ein aktiver Club in A gibt keine Berechtigung in B. Ein persönliches Produkt darf nach seiner expliziten Accountpolicy `active_personal` verwenden. Unbekannte Zustände oder fehlende Policydefinitionen ergeben keine aktive Mitgliedschaft. Die Plattformrolle ersetzt weder die Kontosperre noch die Verifikation einer persönlichen Eigentümerschaft. + +Unbestätigte Konten dürfen eine Session im Modus `onboarding` erhalten. Deren feste Allowlist umfasst nur Sessionanzeige, Logout, eigenen Kontostatus, Passwortänderung sowie tatsächlich registrierte Verifikations-/Beitrittsfunktionen. Fach-API, Export, persönliche KI und Organisationsdaten bleiben geschlossen. Nach Freigabe wird der Modus serverseitig bei Rotation neu bestimmt; der Client kann ihn nicht wählen. + +## 5. Lokale Datenstrukturen und Invarianten + +Die Strukturen sind ein Schemaauftrag für den später ausdrücklich benannten Zielaufbau. Bestehende Produkte bleiben unverändert. Vorhandene äquivalente Kontotabellen werden über Adapter genutzt; keine doppelte Identitätsquelle. Die nachfolgenden Tabellen gehören zur jeweiligen Produktdatenbank und enthalten keine familienweiten Fachdaten. + +### 5.1 Kontodatensatz und Session + +Neue lokale `auth_accounts`: `id UUID PK`, `email_norm TEXT UNIQUE NOT NULL`, `password_hash TEXT NOT NULL`, `password_revision BIGINT NOT NULL DEFAULT 1`, `status TEXT NOT NULL CHECK IN ('enabled','disabled','deleted')`, `email_verified BOOLEAN NOT NULL DEFAULT false`, `security_epoch BIGINT NOT NULL DEFAULT 1`, `platform_role TEXT NOT NULL DEFAULT 'user' CHECK IN ('user','operator')`, `created_at/updated_at TIMESTAMPTZ NOT NULL`. Ein Anzeigename ist ein explizites eigenes DTO-Feld, keine Identitätsautorität. Bei Profiladapter ersetzt dessen Tabelle diesen Datensatz; Fremdschlüssel werden entsprechend lokal angepasst. + +Konkrete Sessionstruktur für diesen Neuanlagenfall: + +```sql +CREATE TABLE auth_sessions ( + id UUID PRIMARY KEY, + subject_id UUID NOT NULL REFERENCES auth_accounts(id), + token_hash BYTEA NOT NULL UNIQUE CHECK (octet_length(token_hash) = 32), + generation BIGINT NOT NULL DEFAULT 1 CHECK (generation > 0), + account_epoch BIGINT NOT NULL, + mode TEXT NOT NULL CHECK (mode IN ('full', 'onboarding')), + csrf_secret TEXT NOT NULL, + created_at TIMESTAMPTZ NOT NULL, + auth_time TIMESTAMPTZ NOT NULL, + last_seen_at TIMESTAMPTZ NOT NULL, + rotated_at TIMESTAMPTZ NOT NULL, + idle_expires_at TIMESTAMPTZ NOT NULL, + absolute_expires_at TIMESTAMPTZ NOT NULL, + mfa_verified_at TIMESTAMPTZ, + mfa_method TEXT CHECK (mfa_method IN ('totp', 'recovery')), + mfa_failed_attempts INTEGER NOT NULL DEFAULT 0, + revoked_at TIMESTAMPTZ, + CHECK (idle_expires_at <= absolute_expires_at), + CHECK (mfa_failed_attempts >= 0), + CHECK ((mfa_verified_at IS NULL) = (mfa_method IS NULL)), + CHECK (absolute_expires_at > created_at) +); +CREATE INDEX auth_sessions_subject_idx ON auth_sessions(subject_id); +``` + +Cookieinhalt: `secrets.token_urlsafe(32)`, kanonisch 43 ASCII-Zeichen. DB-`token_hash`: `sha256(raw.encode('ascii')).digest()`. Nur diese zufälligen hochentropischen Secrets werden mit einem schnellen Hash verifiziert; Passwörter verwenden weiterhin bcrypt. Eine vollständig kompromittierte schreibbare Datenbank ist dadurch nicht abgesichert. Die Hashspeicherung begrenzt die Wiederverwendung bei bloßem Auslesen des Sessionspeichers. [Begrenzte externe Gegenprüfung: OWASP Session Management](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#server-side-session-token-storage). + +`csrf_secret` sind unabhängige 32 Zufallsbytes in URL-safe-Darstellung. Es darf serverseitig wieder auslesbar gespeichert werden, weil es ohne Sessioncookie keine Authentifizierung ermöglicht. Es gehört trotzdem weder in Logs noch in Fach-DTOs. Kein Sessiontoken im DB-Klartext, Response-JSON, RequestContext, Audit oder Browser-Web-Storage. Alle Zeitpunkte sind UTC; Ablaufentscheidungen nutzen die DB-Uhr, keine Clientzeit. + +### 5.2 Zweckgebundene Authflows + +Separate Tabelle `auth_flows` mit `id UUID PK`, `token_hash BYTEA UNIQUE NOT NULL` (32 Bytes), `csrf_secret TEXT NOT NULL`, `purpose ∈ {login_prepare,mfa_login,mfa_enroll}`, `subject_id UUID NULL FK`, `account_epoch BIGINT NULL`, `password_revision BIGINT NULL`, `password_verified_at TIMESTAMPTZ NULL`, `failed_attempts INTEGER NOT NULL DEFAULT 0`, `expires_at TIMESTAMPTZ NOT NULL`, `consumed_at TIMESTAMPTZ NULL`, `initiating_session_id UUID NULL FK auth_sessions(id)`, `pending_factor_ciphertext TEXT NULL`, `factor_key_id TEXT NULL`. Bei `login_prepare` ist kein Subject gebunden; bei MFA-Zwecken sind Subject, Epoch, Passwortrevision und Prüfzeit Pflicht. DB-Checks erzwingen diese Zuordnung. Ein Pending-Secret existiert nur bei `mfa_enroll`. + +Das Flowcredential lebt in `__Host-jinkendo-preauth`, ebenfalls nur als Hash gespeichert. Es kann niemals über `PrincipalResolver` eine Session ersetzen. Endpunkte erlauben jeweils genau die in Abschnitt 8/11 genannten Zwecke. Ablauf: Loginvorbereitung 10 Minuten, MFA-Login 5 Minuten, erste MFA-Einrichtung 10 Minuten, jeweils ohne Verlängerung durch Fehlversuche. Übergänge ersetzen Flowtoken und CSRF; alte Flows werden atomar verbraucht. Verifikations-/Passwortresettokens erhalten bei späterem Bedarf eigene Zwecke und Resolver, niemals den Sessionresolver. + +### 5.3 MFA, Fehlversuche und Widerruf + +`auth_mfa_factors`: `subject_id UUID PK/FK`, `secret_ciphertext TEXT NOT NULL`, `key_id TEXT NOT NULL`, `enabled_at TIMESTAMPTZ NOT NULL`, `last_accepted_counter BIGINT NOT NULL DEFAULT -1`. + +`auth_recovery_codes`: `id UUID PK`, `subject_id UUID FK NOT NULL`, `code_hash BYTEA UNIQUE NOT NULL`, `created_at TIMESTAMPTZ NOT NULL`, `used_at TIMESTAMPTZ NULL`. Pro Ausgabe acht unabhängige Codes aus je 16 Zufallsbytes; Anzeige einmalig in lesbaren Hexgruppen, normalisiert nur definierte Bindestriche entfernen und ASCII-Hex kleinschreiben. Keine freie Entfernung beliebiger Zeichen. SHA-256 über den normalisierten hochentropischen Code; kein vier Byte langes Shinkan-Original übernehmen. + +Gemeinsame lokale Tabelle `auth_attempt_windows`: `bucket_key BYTEA`, `bucket_kind TEXT`, `window_start TIMESTAMPTZ`, `attempts INTEGER`, PK über die ersten drei Felder. Schlüssel aus HMAC-SHA-256 mit eigenem lokal bereitgestellten `AUTH_RATE_KEY`; keine E-Mail im Bucketschlüssel oder Log. Zwei unabhängige Buckets je Versuch: normalisierte Loginadresse und vertrauenswürdig ermittelte Quell-IP. Fehlende IP verwendet einen gemeinsamen begrenzten Bucket. `window_start` ist der Beginn eines festen 15-Minuten-UTC-Fensters aus der DB-Uhr. Zähler werden atomar per Upsert erhöht und der zurückgegebene Wert gegen das Limit geprüft; auch eine limitüberschreitende Verweigerung wird committed. Alle Worker verwenden dieselbe Produkt-DB, kein Redisdienst nötig. Defaults: 8 Anmeldeversuche/Loginadresse/15 Minuten, 30 Anmeldeversuche/IP/15 Minuten; begrenzte Fenster statt dauerhafter Kontosperre. Unbekannte Adressen erhalten denselben Kontobucket. Jeder Versuch reserviert vor Passwortprüfung atomar je einen Budgetplatz; auch Erfolge setzen das Fenster nicht zurück. Die beiden Buckets werden in sortierter Reihenfolge unter derselben kurzen Transaktion aktualisiert; bei Überschreitung bleibt die Verweigerung wirksam. Loginprepare ebenfalls IP-begrenzt (30/15 Minuten). MFA-Flow maximal fünf Fehlversuche; zusätzlich Konto-/IP-Buckets über mehrere neue Flows hinweg. Details der Fenster sind Defaults, wirksame Begrenzung und persistenter Fehlversuch sind Pflicht. + +Sessionablauf ist unabhängig vom Aufräumen. Lokaler Wartungsbefehl entfernt abgelaufene/verbrauchte Flows und alte Buckets; widerrufene Sessions nach dem benötigten kurzen Diagnosefenster. Default: Flows/Buckets spätestens am Folgetag, Sessionmetadaten sieben Tage nach Ablauf/Widerruf; Auditfristen bleiben produktbezogen. Wartung läuft über vorhandene Betriebswege, kein neuer zentraler Scheduler. + +## 6. Browsergrenze: Cookie, Origin und CSRF + +### 6.1 Cookievertrag + +Ausgabe erst nach erfolgreichem DB-Commit: + +```python +response.set_cookie( + key="__Host-jinkendo-session", + value=issued.raw_cookie, # Secret bleibt nur in diesem internen Ausgabeobjekt + httponly=True, secure=True, samesite="lax", path="/", + max_age=issued.remaining_absolute_seconds, +) +``` + +Kein `Domain`, kein JWT-/Rolleninhalt, keine Session in URL. Das Preauth-Cookie nutzt dieselben Attribute mit seiner kürzeren Restlaufzeit. Cookie-Max-Age kann die serverseitige Idlefrist nicht verlängern. Löschen bei erfolgreichem Logout erfolgt mit identischem Namen/Path/SameSite/Secure und `Max-Age=0`. **401-Responses löschen oder überschreiben niemals Cookies:** Eine verspätete Antwort darf eine inzwischen erneuerte Session nicht im Browser entfernen. + +Neue Apps laufen auch lokal hinter einem HTTPS-Proxy; Tests verwenden eine HTTPS-Basis-URL. Kein `Secure=False`-Produktionsschalter. Mehrere Produkte auf demselben Host benötigen unterschiedliche feste Produkt-Cookienamen und weiterhin Same-Origin-Routing; bevorzugt erhält jede App ihren eigenen Host. Verschiedene localhost-Ports trennen Cookies nicht. Familienweite Domaincookies sind ausdrücklich ausgeschlossen. + +### 6.2 Konkrete Requestprüfung + +Für Browser-JSON-API gilt: + +1. `Host` gegen konfigurierte Hostliste prüfen. `PUBLIC_ORIGIN` ist ein explizites Scheme/Host/Port-Tupel ohne Pfad, in Produktion HTTPS. Nicht aus beliebigem `Host` oder `X-Forwarded-Host` rekonstruieren. Forwarded-IP/Proto nur von ausdrücklich konfigurierten Proxyadressen/-netzen; „jede private IP ist vertrauenswürdig“ wird nicht aus Shinkan übernommen. +2. Browser-JSON-Aufrufe verlangen `X-Jinkendo-Client: browser-v1`, auch `/auth/bootstrap` und Sessionanzeige. Kein Cross-Origin-CORS für diese API; insbesondere keine Credentialsfreigabe für fremde Origins und kein `*`. Gleiches Origin im Entwicklungsproxy erhalten. +3. Falls `Sec-Fetch-Site` vorhanden: nur `same-origin` akzeptieren. `same-site` ist für einen fremden Geschwisterhost nicht ausreichend. Fehlt der Header, bleibt die Prüfung aus 2/4/5 erforderlich. +4. Alle unsicheren Methoden (`POST`, `PUT`, `PATCH`, `DELETE`, andere unbekannte Methoden) verlangen `Origin == PUBLIC_ORIGIN`. Falls Origin fehlt, darf ausschließlich ein streng geparstes Referer-Origin exakt passen. `Origin: null`, mehrere/mehrdeutige Werte oder beide Quellen fehlend: 403. Bei vorhandenem Origin gibt es keinen Referer-Fallback bei Abweichung. Für sichere JSON-Reads einen vorhandenen fremden Origin ebenfalls ablehnen. +5. Unsichere Requests verlangen `X-CSRF-Token`, maximal 128 ASCII-Zeichen, konstantzeitlich mit dem **zum verwendeten Credential gehörenden** `csrf_secret` verglichen. Sessionendpunkte verwenden Session-CSRF, Login-/MFA-Flowendpunkte Flow-CSRF. Keine freie Wahl zwischen beiden. +6. JSON-Mutationen akzeptieren nur `application/json` (optionaler Charsetparameter); keine Form-/`text/plain`-Fallbacks. Authbodies maximal 4 KiB. Ein später registrierter Upload prüft Origin/CSRF ebenfalls vor Verarbeitung; Multipart hebt den Schutz nicht auf. + +`GET /auth/bootstrap` erstellt nur einen begrenzten Voranmeldeflow; es ändert keine Konten oder Fachobjekte und ersetzt keine gültige Session. Ein passender, noch gültiger Preauthflow wird wiederverwendet, damit mehrere Tabs ihn nicht gegenseitig überschreiben. Der Response enthält den Flow-CSRF-Wert im JSON. Ein fremder Browser-Origin kann den benötigten Customheader nicht ohne CORS-Preflight senden und erhält keine CORS-Freigabe. Session-CSRF kommt nur über die geschützte Sessionanzeige an den Same-Origin-Client, bleibt im JS-Speicher und wird bei Rotation neu ausgegeben. Es gibt kein zweites lesbares CSRF-Cookie. + +Das ist die kleine zustandsbehaftete Synchronizer-Variante, passend zum bereits vorhandenen Sessionspeicher. CSRF wird pro Credentialgeneration erneuert; keine Rotation pro Fachrequest und kein eigenes Signaturprotokoll. Origin und SameSite wirken ergänzend. [Begrenzte Gegenprüfung: OWASP CSRF, Synchronizer-Token und Originprüfung](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html). + +Bei ungültigem Credential liefert ein geschützter Sessionendpunkt nach der allgemeinen Originprüfung 401; bei gültigem Credential und falschem CSRF 403. DB-/Adapterausfall bleibt 503. Diese Reihenfolge verhindert, dass ein ausgelaufenes Konto nur wegen eines alten CSRF-Werts als weiter angemeldet erscheint. + +Alle Auth-/persönlichen Responses einschließlich Fehler: `Cache-Control: no-store`, kein CDN-/PWA-Fachdatencache, `Referrer-Policy: no-referrer`. Cookie-, Authorization- und CSRF-Header sowie Passwort-/Codebodies werden am Proxy und in der App redigiert. Same-Origin-SSE/Medien verwenden Cookies ohne volle Session in der URL; fremde Medien benötigen gegebenenfalls separate begrenzte Grants nach ADR-03, kein Sessionalias. + +Für den ersten Foundation-Slice lädt der zentrale Fetchclient persönliche Bilder/Downloads mit Cookie **und Scopeheadern**; erzeugte Blob-URLs werden bei Scopewechsel/Logout widerrufen. Ein späterer SSE-Client verwendet bei diesem Scopevertrag `fetch`/ReadableStream statt eines nativen EventSource-Aufrufs ohne Scopeheader. Native Medien-/Rangeadapter dürfen erst bei konkretem Bedarf eine ausdrücklich validierte Scopehint-Variante erhalten; ein Objektpfad oder URLhint ist weiterhin keine Autorität. Es gibt keine pauschale CSRF-/Scopeausnahme für alle Medienrouten. + +## 7. Sessionablauf, Erneuerung und Logout + +### 7.1 Sessionzustände und Gültigkeit + +Eine Session ist nur gültig, wenn gleichzeitig gilt: + +```text +Hash des einen korrekt geformten Sessioncookies findet genau eine Zeile +AND revoked_at IS NULL +AND DB-Zeit < idle_expires_at AND DB-Zeit < absolute_expires_at +AND Account existiert, status = enabled +AND session.account_epoch = account.security_epoch +AND Sessionmodus ist bekannt und für die Operation zugelassen +``` + +Gleichheit mit einer Ablaufgrenze bedeutet bereits abgelaufen. Fehlende Spalte, unbekannter Zweck, gelöschtes Profil oder inkonsistente Zuordnung wird nicht durch Defaults geheilt. Für Fachoperationen wiederholt die Policy diese Prüfung einschließlich `credential_generation`. Rollen werden nicht für zwölf Stunden in der Session eingefroren. + +Sessionanzeige, Readiness und automatische Erneuerungsversuche zählen nicht als Aktivität. Ein erfolgreich authentifizierter Fachrequest oder ausdrücklich ausgeführter Scopewechsel aktualisiert in einer kurzen Transaktion `last_seen_at` und `idle_expires_at=min(DB-Zeit+30 Minuten, absolute_expires_at)`. Die bestehende Frist wird zuvor unter Zeilensperre geprüft; abgelaufene Sessions können nicht wiederbelebt werden. Auch ein authentifizierter, später fachlich verweigerter Request kann so Aktivität zählen. Das behauptet keine Erkennung menschlicher Aktivität; Background-Polling darf deshalb nicht als Keepalive für die Session konzipiert werden. + +Neu erzeugte Session: Idlefrist 30 Minuten, Absolutfrist zwölf Stunden, Generation 1. Mehrere Geräte erhalten getrennte Sessions. Browser schließen ist kein verlässlicher Widerruf. Serverseitiger Ablauf/Widerruf bleibt ausschlaggebend, unabhängig von Cookieanzeige und Frontendtimer. + +### 7.2 Login und atomare Erstellung + +1. Browser holt Bootstrap, sendet Login mit Flowcookie, Origin, Customheader und Flow-CSRF. +2. Service validiert DTO, IP-/Kontobudget und zweckgebundenen Flow. Loginadresse wird getrimmt und einheitlich kleingeschrieben; keine providerabhängige Punkt-/Plusadressänderung. E-Mail-Validator verweigert Steuerzeichen. Bestehende Normalisierung wird im Produktadapter konsistent gehalten. +3. Credentialadapter liest Kontosnapshot. Passwortvergleich erfolgt mit bcrypt und bei unbekanntem Konto mit einem festen bcrypt-Dummyhash gleicher Kosten. Kein Netzaufruf, keine lang gehaltene Fachtransaktion während des teuren Vergleichs. +4. Abschlusstransaktion sperrt Konto und Flow, prüft erneut Status, `password_revision`, `security_epoch`, Flowzweck und Frist gegen den zuvor geprüften Snapshot. Passwortreset/Sperre zwischen Vergleich und Abschluss verhindert den Login. Fehlversuch und Limits werden **committed**, erst anschließend als 401/429 ausgegeben. Keine Exception innerhalb der UoW, die diese Zähler zurückrollt. +5. Bei aktiviertem Faktor: Preauthflow atomar zu `mfa_login` ersetzen, frisches Flowcookie setzen; noch keine Session. Bei Betreiberkonto ohne eingerichteten Faktor: nur `mfa_enroll` nach geprüftem Passwort. Bei normalem Konto ohne Faktor: passende `full`-/`onboarding`-Session, CSRF und Pflichtaudit in derselben Transaktion anlegen, Vorflow verbrauchen. +6. Response-DTO validieren, committen, dann Cookie setzen und minimales Session-/Flow-DTO zurückgeben. Sessionrawtoken erscheint nie im JSON. Ein bereits angemeldeter Browser muss vor einem Login als andere Person ausloggen; kein stiller Kontowechsel mit persönlichen Altzuständen (409 `already_authenticated`). + +Passwortadapter verwendet das vorhandene bcrypt-Muster, für neue Hashes Kostenfaktor 12 als Default. Neue Passwörter mindestens 15 Zeichen und höchstens 72 UTF-8-Bytes; kein Abschneiden, Trimmen oder Normalisieren des Passworts. Die Bytegrenze wird vor bcrypt validiert, auch bei Login, und verständlich im UI gezeigt. Ein Reset/Wechsel erfüllt denselben Vertrag. Im Neuaufbau keine SHA-256-Passworthashes. Ein später ausdrücklich beauftragter Bestandsadapter darf vorhandene Legacyhashes gezielt verifizieren und atomar auf bcrypt heben; das wird keine allgemeine Fallbackverifikation beliebiger Hashformate. + +Unbekannte Adresse, falsches Passwort und gesperrtes/gelöschtes Konto liefern beim Login dieselbe 401-Antwort `invalid_credentials`. Verifikation eines bekannten Kontos wird erst nach korrektem Passwort im eingeschränkten Modus sichtbar. 429 nennt eine begrenzte Wartezeit, keine Kontoexistenz. Fehlversuchszähler, Flow und Faktorprüfung funktionieren workerübergreifend; reine In-Memory-Limiter reichen hierfür nicht. + +### 7.3 Erneuerung und Rotation + +`POST /api/v1/auth/session/renew` verlangt aktuelle Session und Session-CSRF. Unter Konto-/Sessionsperre werden Status, Epoch, Generation und Fristen geprüft; dann `token_hash`, `csrf_secret`, `generation+=1` und `rotated_at` atomar ersetzt. Die logische Session-ID bleibt gleich. Das alte Credential ist nach Commit sofort ungültig; keine akzeptierte Vorgängerversion und kein stiller Grace-Login. Absolute Frist, `auth_time` und `mfa_verified_at` bleiben erhalten. Erneuerung allein verlängert die Idlefrist nicht. Der Modus wird aus aktueller Accountpolicy neu ermittelt, eine Kontosperre oder MFA-Pflicht dabei nicht umgangen. + +Der Frontendclient rotiert nach 15 Minuten nur, wenn ohnehin eine Nutzeraktion/Fachanfrage ansteht. Aktive Operationen pro Browser werden für Login/Rotation/Step-up/Logout durch einen gleich benannten Web Lock serialisiert. Browser ohne Web Locks verwenden eine gewählte Tabkoordination; bei Konflikt ist erneute Anmeldung der sichere Fallback, keine schwächere Serverregel. Der Server bleibt unabhängig davon korrekt: zwei Erneuerungen mit derselben Generation lassen genau eine gewinnen; die andere erhält 401 ohne Cookieänderung. Inaktive Tabs beziehen über Sessionanzeige den aktuellen CSRF-Wert, bevor sie wieder schreiben. + +Vor einer eigenen Rotation pausiert der Client neue Fachmutationen und wartet laufende Mutationen ab. Danach erhöht er seine epoch, übernimmt den bestätigten Sessionzustand und invalidiert ausstehende Loader. Normale nicht idempotente Fachwrites werden nach 401, Timeout oder Rotation nie automatisch wiederholt. Bei verlorenem Rotationsresponse darf ein einmaliger sicherer Session-GET klären, ob der Browser bereits das neue Cookie hat. Ist kein gültiges Credential vorhanden, erfolgt Login. Kein „altes Token wieder aktivieren“ zur Komfortrettung. + +### 7.4 Logout, globaler Widerruf und Kontoveränderung + +`POST /auth/logout`: Originprüfung immer; bei gültiger Session zusätzlich deren CSRF. In einer Transaktion Session widerrufen und Audit schreiben; danach Cookie löschen, 204. Bereits fehlende/ungültige Session: nach Origin-/Customheaderprüfung 204 und Cookie löschen, ohne Account-/Scopezustand offenzulegen. Ein noch gültiges Cookie mit falschem CSRF bleibt 403 und wird nicht gelöscht. + +Eine vor konkurrierender Rotation bereits verifizierte Logoutanfrage darf die logische Session-ID trotz inzwischen höherer Generation widerrufen, wenn ihr ursprünglicher CSRF zur verifizierten Generation passte. Dieser eng begrenzte Widerrufspfad gewährt keine Fachrechte. Kommt ein alter Token erst nach Rotation an, ist er unbekannt; der Client klärt den aktuellen Zustand unter seinem Authlock und wiederholt gegebenenfalls Logout mit aktuellem Cookie/CSRF. Ein verspätet gesetztes Cookie einer bereits widerrufenen Session bleibt serverseitig wirkungslos. Kein Rotationspfad kann eine widerrufene Zeile reaktivieren. + +`POST /auth/logout-all`: aktuelle Session/CSRF, Konto exklusiv sperren, `security_epoch+=1`, alle Sessions und gebundenen Authflows widerrufen/verbrauchen, Audit atomar. Aktuelles Cookie löschen, 204. Kein MFA-Zwang zum Beenden eigener Sessions. Eine DB-/Auditstörung liefert 503: Das UI darf lokal persönliche Daten leeren, aber keinen bestätigten serverseitigen Widerruf behaupten. Es zeigt den fehlgeschlagenen Logout und ermöglicht Wiederholung. + +Passwortwechsel/-reset, Kontodeaktivierung/-löschung sowie MFA-Reset/-Deaktivierung erhöhen in derselben Transaktion die Epoch und widerrufen alle Sessions/Flows. Passwortwechsel erhöht zusätzlich `password_revision`. Der Default ist danach erneuter Login, keine verdeckte neue Vollsession. Mitgliedschafts-/Rollenentzug braucht keinen globalen Logout: aktuelle Scope-/Policyprüfungen greifen unmittelbar; eine Betreiberrollenerhöhung widerruft dagegen Sessions und erzwingt vollständigen Login mit MFA. Verifikations- und Onboardingänderungen eröffnen keine Rechte durch einen Clientreload; der Sessionmodus wird bei kontrollierter Rotation aktualisiert. + +## 8. API-Vertrag und Fehler + +Alle Pfade beginnen mit `/api/v1`. Input-DTOs verwenden Pydantic 2 mit `extra='forbid'`, strikte Stringgrenzen und expliziten Ausgabemodellen. Keine Ausgabe ganzer Konto-/Sessionzeilen. `session_id` wird nur bei einem später benötigten Geräteverwaltungsendpunkt angezeigt, nicht als Browsercredential verwendet. + +| Methode / Authpfad | Input / Credential und CSRF | Erfolgsverhalten | +|---|---|---| +| `GET /auth/bootstrap` | Browser-Customheader; optional vorhandenes Preauthcookie | 200 `{state, csrf_token, expires_at}`; begrenzten Flow erzeugen oder gültigen wiederverwenden; Preauthcookie. `state`: `login_prepare`, `mfa_login` oder `mfa_enroll`. | +| `POST /auth/login` | `{email,password}`; `login_prepare` + Flow-CSRF | 200 `SessionView` und Sessioncookie oder 202 `FlowView` und frisches Preauthcookie; keine Mischantwort mit Volltoken | +| `POST /auth/mfa/verify` | `{code, method}`; `mfa_login` + Flow-CSRF; `method=totp|recovery` | 200 `SessionView`; Flow einmalig verbraucht, Sessioncookie, Preauthcookie löschen | +| `GET /auth/session` | Sessioncookie, Browser-Customheader | 200 `SessionView`, keine Fristverlängerung, kein `Set-Cookie`; ungültig 401 | +| `POST /auth/session/renew` | `{}`; Session + Session-CSRF | 200 neues `SessionView`, rotiertes Cookie | +| `POST /auth/logout` | `{}`; Session-CSRF bei gültiger Session | 204 nach serverseitigem Widerruf bzw. bereits fehlender Session | +| `POST /auth/logout-all` | `{}`; Session + Session-CSRF | 204; Epoch erhöht, alle Sessions/Flows ungültig | +| `GET /auth/scopes` | Session, Browser-Customheader | 200 `{items, next_cursor}` mit ausschließlich aktuell auswählbaren Scopes; kein implizit gewählter Raum | +| `POST /auth/session/scope` | `{kind,scope_id}`; Session + Session-CSRF | 200 `{scope:{kind,scope_id}}`; frische Auflösungs-/Policyprüfung und Scopewechsel-Audit; setzt keinen globalen autoritativen Sessiontenant | +| `GET /auth/me` | Session; feste Self-Capability, scopefrei | 200 explizites eigenes Kontostatus-DTO; keine beliebige `profile_id` | +| `POST /auth/password/change` | `{current_password,new_password}`; Session + Session-CSRF; bei Faktorpflicht frische MFA | 204 nach Vergleich/Revisionsprüfung und atomarem Widerruf aller Sessions; Cookie löschen | + +MFA-Verwaltungsendpunkte und deren enge Zwecke stehen vollständig in Abschnitt 11. Kein allgemeiner `/profiles/{id}`-AuthCRUD, kein öffentliches Erstadministrations-Signup. Normale Registrierung, Einladungen, Mailversand und Passwortresetversand bleiben konkrete Produktfunktionen; ihre Session-/Widerrufshooks sind hier festgelegt. Eine App ohne diese Funktionen registriert auch keine scheinbar funktionierenden Endpunkte. + +`SessionView` enthält ausschließlich: + +```json +{ + "principal": {"kind": "human", "subject_id": "opaque-local-id"}, + "account_state": "active_personal", + "session_mode": "full", + "auth_time": "2026-10-16T08:00:00Z", + "mfa_verified_at": null, + "idle_expires_at": "2026-10-16T08:30:00Z", + "absolute_expires_at": "2026-10-16T20:00:00Z", + "generation": 1, + "csrf_token": "opaque-csrf-value" +} +``` + +`FlowView={state,csrf_token,expires_at}` entspricht dem Bootstrapformat. Ein Flowzustand im Response ist kein Principal. `/auth/scopes` listet `ScopeView={kind,scope_id,display_name}`. Ein späteres Fachmodul kann ein separates Capability-DTO für den gewählten Raum anbieten; es ersetzt keine Policyprüfung. + +| HTTP / stabiler Problemcode | Bedeutung / Clientverhalten | +|---|---| +| 401 `authentication_required`, `session_invalid` | Kein gültiger Principal; aktueller UI-Kontext wird beendet. Keine automatische Cookieänderung. | +| 401 `invalid_credentials`, `challenge_invalid` | Login-/Flowfehler; Loginansicht verarbeitet selbst, kein globaler Logout einer anderen laufenden Session. | +| 403 `origin_forbidden`, `csrf_invalid`, `account_not_ready`, `capability_denied`, `scope_forbidden`, `mfa_required` | Request verweigert; ändert keine Identität. Bei `mfa_required` gezielte Step-up-Ansicht. | +| 404 `not_found` | Objekt fremd, unsichtbar oder nicht vorhanden; gleiche sichere Antwort. Keine Bestätigung fremder Profile/Räume. | +| 409 `already_authenticated`, `version_conflict` | Bewusste Kontowechsel-/Objektversionsentscheidung nötig; kein automatischer Write-Retry. | +| 422 `validation_failed`, `scope_required` | DTO/Scopepaar fehlt oder ist syntaktisch falsch. Keine Tokens/Passwörter in `errors`. | +| 422 `scope_not_allowed`, `ambiguous_credentials`, `unsupported_auth_header` | Unerwartete Scopeheader bzw. mehrdeutige/nicht unterstützte Authquelle; kein Fallback. | +| 403 `browser_header_required`; 413 `payload_too_large`; 415 `unsupported_media_type` | Browserheader fehlt bzw. Body-/Medientypgrenze verletzt; vor Verarbeitung verweigert. | +| 429 `auth_rate_limited` | Begrenzter Retry-After; keine Umgehung durch neuen Worker/Flow. | +| 503 `auth_unavailable`, `policy_unavailable` | DB, Schlüssel oder Pflichtadapter fehlt/gestört; kein Logout und keine Zugriffserlaubnis daraus ableiten. | + +RFC-9457-Problemformat gemäß Foundation: `type,title,status,detail,instance,code,request_id`, optional sichere `errors`. `detail` bleibt allgemein; keine fremde ID, SQL-, Faktor-, Provider- oder Secretinformationen. Zunächst syntaktische Browsergrenze/Origin, dann Credential, dann dessen CSRF, dann Konto-/Scope-/Objektpolicy. Unbekannte fremde Objekte werden erst nach Prüfung des aktuellen eigenen Kontextes als 404 behandelt; ein fehlendes eigenes Recht kann vorher 403 ergeben. + +## 9. Datenraumauflösung, Rollen und Objektberechtigung + +### 9.1 Auswahl ist keine Autorität + +Fachrouten mit Datenraum verlangen **beide** Header `X-Scope-Kind` und `X-Scope-Id`; Whitelist der registrierten Arten, kanonische begrenzte IDs (maximal 128 Zeichen), keine mehrfachen Headerwerte. Ein fehlendes/halbes/ungültiges Paar: 422. Keine Auswahl bei mehreren Vereinen: 422 `scope_required`; kein erster, kleinster oder zuvor unvalidiert gespeicherter Verein. Scopefreie Kontorouten erzeugen `scope=None` über eine ausdrücklich eigene Dependency und akzeptieren keine scopeabhängigen Fachoperationen. Mitgesendete Scopeheader werden dort mit 422 `scope_not_allowed` verweigert; der Transportclient hängt sie nur an als scoped registrierte Fachaufrufe, nicht pauschal an Authrequests. + +Ein manipulierter Header darf höchstens einen Auswahlversuch auslösen. Server prüft anhand des Principal: + +| Scopeart | Verifizierte Bedingung | Bewusst erhaltene Produktvariante | +|---|---|---| +| `personal` | Scope-ID entspricht dem serverseitig zugeordneten eigenen Profil/Account; Konto nutzbar | Mitai Konto=Profil; Kanshō zusätzliche Reflection-/Journalräume stets darunter mit Ownerfilter | +| `club` | Club existiert/aktiv, Mitgliedschaft des Subjects ist aktuell aktiv; Rollen nur aus dieser Mitgliedschaft | Shinkan Club-/Bibliothekssicht und gezieltes Onboarding | +| `organization` | Produktorganisation aktiv; aktuelle aktive Mitgliedschaft bzw. ausdrücklich definierte technische Delegation | Kairo-Vertrauensraum kann allen aktiven Mitgliedern tenantweite Lesesicht geben; selektive Beteiligung nur bei realem Fachbedarf | + +Kairo und Shinkan dürfen vor Scopewahl eigene Konto-/Einrichtungsseiten anzeigen (`scope=None`). Daraus folgt kein Fachzugriff ohne Raum. „Kein Scope“ bedeutet niemals „alle Tenants“. Ein persönliches Produkt kann den einzigen vom Server als **eigenen** gelieferten Personal-Scope im UI vorauswählen; die Fachanfrage trägt ihn dennoch ausdrücklich. Dies ist keine freie Profilwahl und kein SQL-Erstprofilfallback. + +### 9.2 Capabilityvertrag + +Lokale immutable `CapabilityDefinition`: `id`, `module`, `allowed_scope_kinds` (inklusive ausdrücklichem scopefreiem Fall), `mutating`, `allowed_account_states`, `allowed_session_modes`, `requires_mfa`, `max_mfa_age_seconds`, `object_policy`. Nur tatsächlich implementierte Funktionen registrieren. Unknown Capability, fehlender Objekttyp oder nicht registrierte Regel: verweigern; Routenregistrierung mit solcher Lücke stoppt zusätzlich den Appaufbau. + +Rollen sind Bündel von Capabilities, keine universelle Rangzahl. Portal-/Betreiberrollen und Club-/Organisationsrollen bleiben getrennt. Mehrere Rollen **innerhalb derselben aktiven Mitgliedschaft** können Rechte vereinigen; Rechte aus Club A werden nie in B vereinigt. Die Eigentümerregel ist eine eigene Objektbedingung. Ein Produktfeature/Abonnement wird erst nach Zugriff durch die getrennte Foundation-`EntitlementPolicy` geprüft; ein bezahltes Feature erzeugt kein Leserecht auf fremde Daten. + +Beispielmatrix für den ersten vertikalen Slice; fachliche Bezeichnungen ersetzt das Zielprodukt durch seine tatsächlichen Funktionen: + +| Capability | Scope / Objektregel | Serverrechte | +|---|---|---| +| `account.read_self`, `account.password.change` | Scopefrei, Subject ausschließlich selbst | Eigener bekannter Kontostatus; Passwortänderung mit aktuellem Passwort und ggf. MFA | +| `personal.record.read/update` | `personal`, Objekt gehört eigenem Profil | `full`, explizit aktiver persönlicher Kontostatus; Betreiberrolle allein genügt nicht | +| `club.library.read` | `club`, zentrale Shinkan-Sichtbarkeit | Aktive Mitgliedschaft, lokale registrierte Leserolle | +| `club.library.update` | `club`, Clubobjekt im gewählten Club | Aktive Mitgliedschaft mit expliziter Pflege-Capability; private/offizielle Objekte haben eigene Änderungsregeln | +| `organization.record.read` | `organization`, gleiche Org-ID | Aktive Mitgliedschaft plus lokale Leserolle; Vertrauensraummodell ist ausdrücklich produktlokal | +| `operator.account.disable` | Scopefrei, explizite Operatorfunktion | Aktuelle Betreiberzuordnung, verpflichtende frische MFA, Pflichtaudit; kein allgemeines Datenleserecht | + +Diese Matrix vergibt noch keine neuen Produktrollen. Im Zielaufbau werden nur benötigte Zeilen registriert und getestet. Eine noch fehlende Orgfunktion bleibt unregistriert/geschlossen. + +### 9.3 Gemeinsame Sichtbarkeit und Transaktion + +Shinkans zentrale SQL-Prädikate werden in einen lokalen `VisibilityPolicy`-/Repositoryadapter überführt. Listen, Detail, Suche, Counts, Export, Downloads und referenzierte Kindobjekte verwenden dieselbe Sichtbarkeitssemantik. Die Policy unterscheidet Lesen und Ändern. Shinkans `official` bedeutet für die entsprechende Bibliothek sichtbarer Inhalt; daraus entsteht kein familienweiter öffentlicher Datenraum und kein Schreibrecht auf offizielle Inhalte. + +Der Bestand erlaubt Plattformrollen an bestimmten Bibliotheksobjekten erweiterte private/Club-Lesesicht. Diese I-Regel wird nicht auf persönliche Mitai-/Kanshō-Daten übertragen. Ein neuer produktbezogener Sonderlesepfad muss eine eigene Capability, Zweckbindung und Audit besitzen; für den persönlichen Standardadapter existiert er nicht. + +Fachservice-Muster, V/K, mit denselben Verträgen wie Foundation B2: + +```python +def rename_record(self, ctx, record_id, command): + with self.uow.transaction() as tx: + self.access.require( + ctx, "personal.record.update", + ResourceRef("personal.record", record_id), tx, + ) + row = self.records.rename_owned( + tx, ctx.scope, ctx.principal.subject_id, + record_id, command.expected_version, command.title, + ) + result = RecordView.model_validate(row) + self.audit.changed(tx, ctx, "record.renamed", record_id) + return result +``` + +`rename_owned` akzeptiert keinen Besitzer aus dem Body. Es filtert im SQL nach ID **und** geprüftem Scope/Eigentümer sowie erwarteter Version. Policy lädt das sichtbare Objekt unter derselben Transaktion; fremd/unsichtbar ergibt 404. Erst bei einem sichtbaren Objekt ist eine abweichende Version 409. Der Runtimecode fragt keine fremde Zeile zur Unterscheidung nach. + +Eltern-/Kindzuordnungen werden ebenfalls scoped geladen. Kombinierte Foreign Keys wie `(parent_id,scope_id)` verhindern bei organisatorischen Daten falsche Cross-Scope-Verknüpfungen; persönliche Tabellen verwenden entsprechend `(parent_id,owner_id)`. Bulk-/Exportpfade dürfen Filter nicht erst nach dem Laden anwenden. Scope-/Ownerwerte sind bei normalem Update unveränderlich; Verschieben/Teilen ist ein eigener Fachanwendungsfall und kein Payloadfeld von `update`. + +### 9.4 Gleichzeitiger Entzug und Änderung + +Im Default bleibt PostgreSQL bei `READ COMMITTED`; ein definierter Sperrvertrag verhindert das klassische „vor Transaktion geprüft, danach trotzdem geschrieben“: + +1. Accountzeile gemeinsam sperren, Status/Epoch aktuell prüfen. +2. Sessionzeile gemeinsam sperren, Generation/Fristen/Widerruf aktuell prüfen. Bei Sessionmutation exklusiv sperren. Subject-/Credentialbezug muss dem Context entsprechen. +3. Bei Club/Org den lokalen Raum-/Berechtigungsanker und die Mitgliedschaft gemeinsam sperren und neu prüfen; danach relevante Rollen/Grants lesen. Der Mitgliedschafts-/Rollenwiderruf sperrt dieselben Anker exklusiv, bevor er ändert. Auch entfernte Mitgliedschaftszeilen werden nicht durch einen fehlenden Join als Freigabe interpretiert. +4. Betroffene Objektzeile für Writes exklusiv, für konsistente Reads gemeinsam sperren; scoped ändern/lesen und DTO erzeugen; Audit vor Commit. + +Globale Reihenfolge: Account → Session → Raumanker → Mitgliedschaft → Objekt; mehrere gleichartige IDs sortiert. Logout-all/Kontosperre nimmt Account exklusiv, dann Sessions. Produktadapter dokumentieren den tatsächlichen Raumanker, beispielsweise vorhandene Club-/Orgzeile; es braucht keine generische zentrale Guardtabelle. Rollenänderungen dürfen nicht nur eine Grant-Kindzeile ändern und diese Sperre umgehen. Eine Upgrade-Sperre wird im jeweiligen Änderungsservice von Beginn an exklusiv angefordert. + +Ein bereits autorisierter Write kann vor dem konkurrierenden Widerruf committen; dann wird der Widerruf danach wirksam. Hat der Widerruf zuerst committed, kann der Write nicht mehr unter dem alten Zustand committen. Derselbe Vertrag gilt für Kontosperre, Mitgliedschaftsentzug und Sessionwiderruf. DB-Locktimeouts liefern einen sicheren Fehler und keinen ungeprüften Retry. Kein externer Netzaufruf, Passwortvergleich oder Dateistream während dieser gesperrten Fachtransaktion. + +RLS folgt weiterhin ADR-06: eingeschränkte Runtime-Rolle, tenantkonsistente Constraints und belegte App-Policyabdeckung; vertrauliche Mehrraumprodukte prüfen zusätzliche RLS-Ausprägung ausdrücklich. Wenn vorhanden, nur transaktionslokaler DB-Kontext und Tests gegen Poolwiederverwendung. RLS ersetzt keine Capability-/Objektpolicy, und dieser Blueprint behauptet keinen bereits getesteten RLS-Adapter. + +## 10. Sichere Scopewechsel im Browser + +`POST /auth/session/scope` bestätigt ausschließlich die gewünschte, aktuell erlaubte Auswahl. **Die Session speichert keinen globalen autoritativen aktiven Tenant.** Eine letzte UI-Präferenz darf später lokal gespeichert werden, muss jedoch vor Wiederverwendung erneut aufgelöst werden. Verschiedene Tabs können verschiedene berechtigte Räume verwenden, ohne einander im Backend umzulenken. + +Ablauf eines Wechsels A → B: + +1. Frontend blockiert neue Mutationen aus A, behandelt ungespeicherte Änderungen und erhöht seine lokale epoch. Alle Loader/Requests aus A werden abgebrochen; persönliche Listen, Detailansichten, Fehlermeldungen und Caches werden geleert. +2. Bestätigungsrequest mit aktuellem Session-CSRF und explizitem Ziel B. Service prüft Konto, Session, Mitgliedschaft und Auswahl neu; Audit `scope.selected` mit Actor-/Scope-IDs in derselben Transaktion. +3. Erst bei Erfolg erhält der Store den bestätigten Scope B. Neue Fachrequests tragen exakt dieses Headerpaar. Scheitert die Auswahl, bleibt die Fachansicht geschlossen; keine heimliche Rückkehr auf einen anderen Verein. +4. Jede Antwort und jeder Fehler trägt clientseitig beim Start eingefangene epoch/Subject/Scope/Generation. Weicht sie beim Eintreffen ab, wird die Antwort verworfen. Das gilt ausdrücklich auch für alte 401/403/503 und abgebrochene Loader. + +Ein Abort macht keinen bereits angekommenen Serverwrite rückgängig. Ein solcher Request kann ausschließlich im unveränderlich mitgesendeten Scope A arbeiten, nie nachträglich in B. Der Browser startet ihn nicht automatisch erneut. Für unklare Writeergebnisse gelten die Foundationregeln zu Idempotenz/Objektversionen. UI-epoch ist Schutz vor alten Anzeigen, keine Backendberechtigung. + +Logout/Kontowechsel erhöht die epoch und leert Zustand ebenfalls; ein kleiner BroadcastChannel verteilt nur „Session geändert/abgemeldet“, keine Credentials, CSRF-Werte oder persönlichen Inhalte. Andere Tabs prüfen ihre Session neu. Ein aktueller 401 des Fachclients beendet den lokalen Sessionzustand; 403/503 tun das nicht. Fehler von Login-/Flowendpunkten werden lokal verarbeitet. + +Bei später benötigtem SSE/WebSocket bleibt der Verbindungs-Scope unveränderlich; Wechsel schließt und öffnet neu. Handshake prüft Cookie/Origin/Scope, jedes ausgehende persönliche Ereignis erneut aktuelle Zugriffslage (alternativ kontrollierte kurze Batches mit sofortigem Widerrufssignal). Keine stundenlange Berechtigung aus dem Handshake und keine während des Streams gehaltene DB-Transaktion. Solche Transporte werden erst bei realer Funktion implementiert und separat negativ getestet. + +## 11. Privilegierte Zugriffe und MFA + +### 11.1 Bevorzugter Faktor und sichere Secretablage + +Shinkans TOTP-Verfahren wird lokal übernommen: 20 Zufallsbytes, Base32, HMAC-SHA-1, sechs ASCII-Ziffern, 30-Sekunden-Schritt, Fenster ±1. Der Prüfer wird so angepasst, dass er den **akzeptierten Counter** statt nur `True` zurückgibt. Unter Faktorsperre gilt `accepted_counter > last_accepted_counter`; Update des Counters, Verbrauch des Flows und Sessionerstellung/Step-up erfolgen atomar. Auch derselbe Code gegen zwei verschiedene Challenges kann nur einmal gewinnen. Der erste Einrichtungsnachweis speichert den Counter bereits. [RFC 6238, Abschnitt 5.2](https://www.rfc-editor.org/rfc/rfc6238#section-5.2) verlangt, einen bereits erfolgreich verwendeten OTP nicht nochmals zu akzeptieren. + +Faktor-Secret wird mit einem lokalen `FactorSecretCipher` verschlüsselt. Bevorzugter kleiner Adapter: `cryptography.fernet.Fernet`; authentifizierte Verschlüsselung statt eigener Kryptografie. Diese zusätzliche lokale Bibliothek löst allein die wieder lesbare Secretablage, führt keinen Dienst ein und wird im Ziel-Lockfile gepinnt. Ein bereits vorhandener gleichwertiger Produktadapter hat Vorrang nach Schnittstellenprüfung. + +`MFA_ACTIVE_KEY_ID` und die Key-ID→Fernet-Key-Zuordnung werden ausdrücklich über gemountete Secrets bereitgestellt; keine DB-/Passwort-/Dev-Fallbackschlüssel. Nur `key_id` und Ciphertext stehen in DB/Backups. Neue Verschlüsselungen verwenden den aktiven Key; alte Key-IDs bleiben während einer kontrollierten lokalen Neuverschlüsselung lesbar. Fehlender/ungültiger Key verhindert MFA-Readiness und liefert im MFA-Pfad 503, keine Passwort-only-Ausnahme. Schlüsselmaterial niemals ausgeben. Verschlüsselte Backups und zugehörige Schlüssel benötigen die produktbezogene Recoveryvorsorge aus der Foundation. + +### 11.2 MFA-Endpunkte und Zweckbindung + +Alle POSTs sind JSON mit der allgemeinen Browser-/Originprüfung. `EnrollmentView={otpauth_uri,secret,expires_at}` enthält ein einmal ausgegebenes Faktor-Secret; ausschließlich Einrichtungsansicht, `no-store`, keine Telemetrie. Ein verlorener Einrichtungsresponse erfordert Neustart mit neuem Secret. `RecoveryView={codes:[...]}` wird ebenfalls nur einmal ausgegeben. + +| Methode / Pfad unter `/api/v1/auth` | Erlaubter Zustand / Nachweis | Verhalten | +|---|---|---| +| `POST /mfa/enrollment/start` `{}` | Nur `mfa_enroll`-Flow + Flow-CSRF nach Betreiberlogin; keine gültige Vollsession | 200 EnrollmentView; genau ein Pending-Secret erzeugen. Bereits aktiver Faktor: 409. | +| `POST /mfa/enrollment/confirm` `{code}` | Nur derselbe `mfa_enroll`-Flow + Flow-CSRF; Pending-Secret vorhanden, keine gültige Vollsession | TOTP prüfen, Faktor+Counter, Recoveryhashes und Audit atomar. Vorhandene Sessions/Flows widerrufen, Epoch erhöhen; nach geprüftem Passwort+Faktor neue Session. 200 `{session:SessionView,recovery_codes:[...]}`, frisches Cookie, Preauthcookie löschen. | +| `POST /session/mfa/enrollment/start` `{current_password}` | Nur aktuelle Vollsession + Session-CSRF und aktuelles Passwort für erstmalige freiwillige Einrichtung | 200 EnrollmentView; Pending-Flow an Konto/Session/Epoch/Passwortrevision binden, Ablauf 10 Minuten. Bereits aktiver Faktor: 409. | +| `POST /session/mfa/enrollment/confirm` `{code}` | Nur initiierende Vollsession + Session-CSRF; gebundener Pending-Flow vorhanden | Gleicher atomarer Abschluss wie beim Betreiberflow; 200 `{session:SessionView,recovery_codes:[...]}`, neue Session-ID und Cookie; alte Sessions/Flows ungültig | +| `POST /mfa/verify` `{code,method}` | Nur `mfa_login`-Flow + dessen CSRF | 200 SessionView nach TOTP oder einmaligem Recoverycode, Flowverbrauch, Audit; bereits gültige Vollsession: 409, kein stiller Kontowechsel | +| `POST /mfa/step-up` `{current_password,code,method}` | Aktuelle Vollsession + Session-CSRF; aktiver Faktor | Passwort erneut prüfen, aktuelle Revision/Epoch prüfen; TOTP/Recovery atomar verbrauchen. `auth_time`/`mfa_verified_at` auf DB-Zeit, Sessioncredential/CSRF rotieren; Absolute-Frist nicht verlängern. 200 SessionView. | +| `POST /mfa/recovery-codes/replace` `{current_password}` | Vollsession, Session-CSRF, frische echte TOTP-MFA (siehe unten), aktuelles Passwort | Alte Codes löschen, neue Hashes/Audit atomar; 200 RecoveryView. Keine Anzeige bereits ausgegebener Codes. | +| `POST /mfa/disable` `{current_password}` | Normales Konto, Vollsession/Session-CSRF, frische echte TOTP-MFA, aktuelles Passwort | Faktor/Codes löschen, Epoch erhöhen, alle Sessions/Flows widerrufen, Audit; 204/Cookie löschen. Für Betreiberrolle 403 `mfa_required`. | + +Die Sessionvariante der Einrichtung verwendet **kein** alternativ akzeptiertes Preauthcredential. Pending-Enrollmentdaten liegen in einer `mfa_enroll`-Flowzeile, gebunden an `subject_id`, Epoch, Passwortrevision und die initiierende `session_id` über `initiating_session_id` aus Abschnitt 5. Start ersetzt alte Pending-Enrollments dieses Kontos. Confirm prüft die noch gültige initiierende Session und den gleichen Faktorentwurf. Der Flow wird nicht über einen vom Client frei gesetzten Subjectwert gefunden. Nach Erfolg hat die neue Session eine neue ID und die im Flow gespeicherte Prüfzeit des bestätigten Passworts als `auth_time`; eine neue zwölfstündige Absolutfrist ist nach diesem vollständigen Neunachweis zulässig. + +Beim Preauth-Start wird das Pending-Secret auf dem bereits legitimierten, weiterhin gültigen `mfa_enroll`-Flow ersetzt; dessen Ablauf wird nicht verlängert und er wird dabei nicht selbst verbraucht. Andere offene Enrollmentflows dieses Kontos werden geschlossen. Beim Session-Start entsteht eine neue an die initiierende Session gebundene Zeile; ihr internes zufälliges Token wird nicht als zweites Browsercredential ausgegeben. Confirm findet sie über Session/Subject/Zweck. Ein partieller Unique-Index über `subject_id` für unverbrauchte `mfa_enroll`-Zeilen und Kontosperre beim Start sichern die Eindeutigkeit. Ein abgelaufener Vorgänger wird vor Neuanlage als verbraucht markiert. Die getrennten Endpointpaare verhindern ein automatisches Wechseln zwischen Session- und Flow-CSRF. + +Die in Abschnitt 5 definierte Spalte `auth_sessions.mfa_method` hält die Herkunft des MFA-Nachweises fest. Principal/SessionView benötigen dafür kein zusätzliches öffentliches Vertrauensfeld: der aktuelle Access-/MFA-Service liest es aus der Zeile. Ein Recoverycode kann Login und Step-up ermöglichen; der Nachweis wird als `recovery` auditiert. Faktoren deaktivieren oder Recoverycodes ersetzen verlangt `mfa_method='totp'` innerhalb des Fünfminutenfensters. Betreiberaktionen können mit Recovery nach Passwortnachweis stattfinden und werden besonders auditiert; ein Recoverycode allein erlaubt keinen Faktorwechsel und keine neue Codeausgabe. + +Bei falschem Code werden Zähler committed, ab dem fünften Fehlversuch der Flow verbraucht. Bei Step-up ohne Flow gilt dieselbe Grenze pro Session plus Konto-/IP-Limit; dafür dient `auth_sessions.mfa_failed_attempts` aus Abschnitt 5. Fünf Fehler widerrufen diese Session, erfolgreiche Verifikation setzt den Zähler zurück. Keine unbegrenzten Fehlversuche durch neue Challenges. Codes werden exakt nach gewähltem `method` geparst; kein „TOTP schlägt fehl, dann dieselbe Eingabe als Recovery probieren“. + +### 11.3 Betreiber, Reauth und Recoverygrenze + +Jede privilegierte Betreiberfunktion ist ausdrücklich registriert, benötigt eine aktuelle Betreiberzuordnung, `full`-Session, vorhandenen aktiven Faktor und MFA-Nachweis jünger als fünf Minuten. Ein normaler Login mit Faktor darf das Frischefenster erfüllen. `auth_time` allein ersetzt MFA nicht; `/session/renew` erneuert die MFA-Zeit nicht. Auch ein Betreiber darf persönliche Daten anderer Konten nicht über Standard-Personal-Policies lesen. Eine spätere fachlich benötigte Support-/Exportfunktion wäre ein gesonderter, eng begrenzter und auditierter Produktpfad. + +Fehlt Betreiber-MFA, darf nach richtigem Passwort nur der Einrichtungsflow öffnen. Kein optionales `REQUIRE_ADMIN_TOTP=0`, keine Ausnahme wegen leerer DB. Neue Betreiberrolle macht alte Sessions ungültig und erzwingt diese Reihenfolge. Die Ersteinrichtung erfolgt gemäß ADR-05 über eine lokale administrative CLI: explizit ausgewähltes Konto, Passwort verdeckt eingeben, atomare Einmaligkeit unter DB-Advisory-Lock; keine offene „erster Registrierer wird Admin“-Route. CLI erstellt nur ein zur MFA-Einrichtung verpflichtetes Betreiberkonto. Normale Accounts erzeugt ein separater ausdrücklich autorisierter Einladungs-/Produktweg. + +Bei Faktorverlust nutzt die Person Passwort plus unbenutzten Recoverycode. Sind alle Faktoren/Codes verloren, ist **keine anonyme Online-Faktorresetroute** vorhanden. Der vorhandene lokale Betriebszugang erlaubt einen ausdrücklich adressierten Recoverybefehl mit verdeckter Passwortneuvergabe, Reset von Faktor/Codes, Epoch-Erhöhung, Widerruf aller Sessions/Flows und Pflichtaudit. Danach erneut MFA-Einrichtung. Dieser Betriebsweg ist kein Bestandteil der Web-API und erhält keine Runtime-Superuserrechte. Eine passende begrenzte Betriebs-/Recoveryrolle wird bei Umsetzung verwendet. Der geprobte Testfall ist Pflicht vor privilegierter Nutzung; in dieser Phase wurde er nicht ausgeführt. + +## 12. Maschinenidentitäten und spätere SSO-Anbindung + +### 12.1 Technische Identitäten: Port vorbereiten, keine Infrastruktur bauen + +Die Browserrouten akzeptieren ausschließlich ihr Sessioncookie. Sie akzeptieren weder `X-Profile-Id` als Autorität noch Header-/URL-Sessions. Ein eigener späterer Operational-Router darf `Authorization: Bearer` verwenden. Mehrere Credentials auf einer solchen Route (z. B. Browsercookie plus Bearer oder mehrere Authorizationwerte) werden als mehrdeutig verweigert; keine Prioritätswahl, kein Zusammenmischen von Berechtigungen. Browser-JSON-Routen verweigern unerwartete zusätzliche Authheader ebenfalls. + +Minimale spätere Adapterverträge, noch keine Tabellen oder Tokenverwaltungsendpunkte auf Vorrat: + +```python +class MachineCredentialVerifier(Protocol): + def resolve(self, raw_bearer: str) -> Principal: ... + +class MachineAuthority(Protocol): + def require_current(self, context: RequestContext, capability: str, + resource: ResourceRef | None, tx: Tx) -> None: ... + +@dataclass(frozen=True, slots=True) +class VerifiedExternalIdentity: + issuer: str + subject: str + auth_time: datetime + methods: frozenset[str] + +class ExternalIdentityLinker(Protocol): + def resolve_local_subject(self, identity: VerifiedExternalIdentity, + tx: Tx) -> str: ... +``` + +Ein echter späterer Machine-Adapter verwendet Kairos Hash-/Actor-/Tenantmuster mit folgenden verbindlichen Grenzen: eigener Actor und Credential-ID, explizit nicht leere Capabilitymenge, endlicher Ablauf und Widerruf; Scope fest an das Credential gebunden; effektives Recht = Tokenallowlist ∩ aktuelle Actorpolicy ∩ gegebenenfalls aktuelle Delegation. Delegierte menschliche Rechte entfallen bei Sperre/Entzug. Clientheader können den Credentialscope nicht erweitern. Aktueller Actor, Organisation und Token müssen aktiv sein. Langzeit-Claims allein genügen nicht. Maschinenwrites benutzen dieselben Fachservices/UoW, Objektfilter und das Pflichtaudit mit Actor, Credential-ID, Scope und Ressource. Keine direkten DB-Writes, Browser-MFA-Ausnahmen oder Übernahme menschlicher Cookies durch Agenten. Toolallowlists und ggf. Kostenkontrolle bleiben zusätzliche Grenzen. + +Ohne implementierten Adapter wird der Operational-Router nicht exponiert. Die hier benannten Ports sind eine technische Naht; es werden in Phase 3.3 weder Actor-Tabellen noch ein MCP-/Tokenausgabedienst entwickelt. Spätere relevante Fälle sind in der Testmatrix als bedingte Adaptertests gekennzeichnet. + +### 12.2 SSO später: externe Identität lokal verknüpfen + +Bei einem tatsächlich beauftragten SSO-Adapter entsteht `VerifiedExternalIdentity` nur nach vollständiger serverseitiger Prüfung des gewählten Protokolls (bei OIDC u. a. Issuer, Audience, Signatur, Ablauf, State, Nonce und PKCE). Dieser Blueprint implementiert kein OIDC-Protokoll. Der Linker ordnet das eindeutige Paar `(issuer,subject)` einem lokalen Konto zu; keine automatische Verknüpfung allein wegen gleicher E-Mail, keine Übernahme fremder Tenant-/Adminclaims. + +Nach erfolgreicher Verknüpfung gelten lokaler Kontostatus, Scope-/Objektpolicy und die produktlokale Cookie-Session unverändert. Ein externer MFA-Claim wird erst nach expliziter Adaptervertrauensregel akzeptiert; standardmäßig entsteht daraus kein lokaler Betreiber-MFA-Nachweis. Kein familienweites Cookie, keine gemeinsame Sessiontabelle, keine Tenant-Fachdatenmigration und kein bereits versprochenes globales Logout. Es wird jetzt weder ein Identity Provider ausgewählt noch ein SSO-Dienst gebaut; dies blockiert die lokale Implementierung nicht. + +## 13. Fail-Closed-Verhalten, Audit und Anti-Patterns + +### 13.1 Entscheidungsreihenfolge der AccessPolicy + +`require(context, capability, resource, tx)` führt in fester Reihenfolge aus: + +1. Registrierte Capability und passende Principalart feststellen. `machine` ist bei reinem Browseradapter immer verboten. +2. Aktuellen Konto-/Credentialzustand und Sessionmodus prüfen; bei Widerruf/Sperre/Generationwechsel 401, bei nicht ausreichendem Onboardingstatus 403. Zwischenflow kann diesen Pfad nie erreichen. +3. Vorgeschriebenen Scope und dessen aktuelle Eigentums-/Mitgliedschaftsgrenze gemäß Sperrvertrag prüfen; fremde Auswahl 403. Keine Scopeauswahl bei Raumfreiheit als Hintertür verwenden. +4. Rollen/Capabilities nur aus diesem aktuellen Kontext bestimmen. Bei Betreiberfunktion zusätzlich Faktoraktivität, MFA-Herkunft und Frische prüfen. Kein Rollenrang oder `is_admin`-Shortcut überspringt die Objektregel. +5. Falls Objekt erforderlich: ausschließlich scoped/sichtbar laden; unsichtbar/fremd/fehlend 404; konkrete Lese-/Schreibregel durchsetzen. Auch alle referenzierten Eltern/Quellen prüfen. +6. Fachoperation durchführen, gegebenenfalls getrennte Entitlementprüfung, sichere DTO-Ausgabe und erforderliches Audit in derselben UoW; Commit vor Response. + +Ein technischer Ausfall der aktuellen Policyauflösung wird 503, nicht „leere Rollen, dann Standardrecht“ oder Allow. Ein unbekannter Kontostatus wird verweigert und intern diagnostiziert. Runtime-Flags `AUTH_DISABLED`, `CAPABILITY_ENFORCE=0`, „Probe erlaubt“ und `X-Admin` existieren in der neuen Implementierung nicht. Testfakes entstehen ausschließlich in Tests und sind im Produktionsprovideraufbau nicht auswählbar. + +### 13.2 Audit und Datensparsamkeit + +Pflicht-Ereignisse: Session erstellt/rotiert/widerrufen, Logout-all, Passwortänderung/-reset, Kontosperre/-reaktivierung, Betreiberrollenänderung, Scopewahl, MFA eingerichtet/verwendet/deaktiviert/zurückgesetzt, Recoverycode verbraucht/ersetzt und jede privilegierte Änderung. Audit trägt Foundationfelder: Ereignis-ID, UTC-Zeit, Request-ID, Subject-/Actor-ID, Credential-ID, Aktion, Scope, Objekttyp/-ID, Ergebnis und begrenzten Reasoncode. Keine E-Mail, Passwörter, Cookie-/CSRF-/Recovery-/Faktorwerte oder private Texte. Failed-Login-Ereignisse verwenden den nicht rückrechenbaren Rate-Bucketbezug statt der eingegebenen Adresse; aufbewahrte Securitylogs bleiben zugriffsbeschränkt und produktbezogen befristet. + +Zustandsänderung und Pflichtaudit committen gemeinsam. Fehlender Auditadapter verhindert die kritische Aktion. Fehlversuchszähler/Challengefehler werden in einer eigenen kurzen Authtransaktion samt Ereignis committed, bevor der Service ein Fehlerergebnis zurückgibt. Das ist bewusst anders als eine Exception, die dieselbe UoW zurückrollt. Allgemeine Origin-/CSRF-Verweigerungen nutzen begrenztes strukturiertes Securitylogging; ein Logausfall darf die verweigerte Anfrage nicht erlauben. + +Weder Produkt-DB-Inhalte noch Principal/RequestContext gehen ungefiltert an KI-Provider oder globale Diagnose-Widgets. Für spätere persönliche KI gilt nach erfolgreicher Objektberechtigung weiterhin Kanshōs Privacy Gateway. Auth ist keine Ausnahme von dieser Egressgrenze. + +### 13.3 Ausdrücklich zu vermeidende Muster + +| Anti-Pattern | Geforderte Umsetzung | +|---|---| +| Mitai `get_pid(X-Profile-Id)` oder `ORDER BY created LIMIT 1` | Eigenes Profil ausschließlich aus geprüftem lokalen Konto; fremde Auswahl verweigern | +| Eingeloggtes Konto reicht für beliebigen Profil-CRUD/Export | Self-Endpunkt oder ausdrückliche Capability plus scoped Objektregel und explizite DTOs | +| Shinkan `min(club_ids)`, ungültigen Header ignorieren, fehlender Kontostatus gilt als aktiv | Auswahl erforderlich; fehlerhaft/fremd verweigern; bekannter serverseitiger Zustand Pflicht | +| UI blendet Button aus, Backend macht ungeprüft weiter | Serverseitige gemeinsame Policy für jede Route/Objektoperation | +| Sessionrolle bleibt bis Cookieablauf gültig | Kontostatus, Mitgliedschaft und effektive Rechte aktuell prüfen; Sperrvertrag bei Transaktionen | +| Volltoken in JSON, URL, LocalStorage, SSE-Query oder Context | HttpOnly-Cookie; getrennte zweckgebundene Grants nur bei echtem Bedarf | +| Cookie-SameSite ersetzt CSRF oder `Origin.endswith('jinkendo.de')` | Credentialgebundener CSRF-Wert und exakte konfigurierte Originprüfung | +| Beliebige private Proxy-IP legitimiert Forwarded-Header | Explizite tatsächliche Proxyallowlist; untrusted Header verwerfen | +| MFA-Challenge gilt schon als Session; Betreiber-MFA nur per Flag | Getrennte Flowtabelle/Resolver, feste Endpointzwecke, Operator-MFA verpflichtend | +| TOTP nur als `bool`, Recoverycode mehrfach einlösbar | Atomar gespeicherter akzeptierter Counter bzw. bedingtes einmaliges Update | +| Zufallsarme Recoverycodes oder DB-Passwort als Faktorschlüssel | 128-Bit-Recoverysecrets, separater lokal bereitgestellter Verschlüsselungsschlüssel | +| Kairo leere Tokenrechte → breite Defaultrechte; unbegrenzte Laufzeit | Explizite enge Rechte, Ablauf, aktuelle Actor-/Delegationsbegrenzung | +| Ein globaler Sessiontenant lenkt nach Scopewechsel alte Requests um | Unveränderlicher Scope pro Anfrage; serverseitige Prüfung und UI-epoch | +| Audit oder Membershipprüfung öffnet eigene Connection im Fachwrite | Gemeinsames `tx`, Rollback bei Pflichtfehler, Commit vor Erfolg | +| Nach 401/Timeout einen Write automatisch erneut senden | Ergebnis klären; gegebenenfalls explizite Idempotenz/Version des Fachmoduls | +| Kontolöschung oder Passwortreset lässt MFA-/Resetflows gültig | Epoch erhöhen, alle Sessions und Authflows atomar widerrufen/verbrauchen | +| Gleiche E-Mail in zwei Apps wird SSO-Autorität | Später explizit geprüfte `(issuer,subject)`-Verknüpfung zum lokalen Konto | + +Cookieparser muss doppelte Werte des sicherheitsrelevanten Cookienamens im rohen Cookieheader erkennen und verweigern; kein stilles Last-value-wins des Frameworkdicts. Session-/Flowcredential muss dem kanonischen Format entsprechen, leere/zu lange/nicht ASCII-/CSV-Werte ergeben 401. Mehrdeutige Authquellen werden vor Fachlogik verweigert (422 `ambiguous_credentials`). Nicht unterstützte Legacy-Profil-/Sessionheader (`X-Profile-Id`, `X-Auth-Token`, `X-Actor-Token`) werden auf den neuen Browserrouten mit 422 `unsupported_auth_header` zurückgewiesen, statt als unsichtbare Nebenautorität weiterzuleben. Diese beiden Codes ergänzen die Fehlerliste in Abschnitt 8. + +## 14. Automatisierte Sicherheits- und Negativtests + +Dies ist ein konkreter Testauftrag für Phase 3.4, kein Bericht bestandener Tests. Alle hier als Pflicht bezeichneten Fälle müssen im späteren Zielaufbau tatsächlich gesammelt und ausgeführt werden. Unitfakes prüfen reine Zustandsregeln; DB-Rennen und Filterinvarianten werden gegen isoliertes echtes PostgreSQL mit begrenzter Runtime-Rolle geprüft. Keine synthetischen Schreibtests gegen vorhandene Anwendungen oder produktive Datenbanken. + +### 14.1 Testdaten und Harness + +Fixture: Personen A/B; A aktiv in Club/Org 1 und 2 mit unterschiedlichen Rollen, B nur in 2; Person C deaktiviert; ein unbestätigtes Konto; ein bestätigtes Konto ohne Club; Operator O mit Faktor; Operator N ohne Faktor. Je ein persönliches Objekt von A/B, Organisationsobjekte in 1/2, privates/eigenes/fremdes, Club- und offizielles Bibliotheksobjekt, Eltern-/Kindreferenzen sowie eine Reihe Export-/Medienressourcen. Alle IDs und Texte synthetisch. Nicht implementierte Produktarten sind statt dieser Fachfixtures durch „Scopeart nicht registriert“ abgedeckt. + +Testapp über dieselbe `create_app`-Factory. Time/Clockadapter für reine Algorithmen; DB-Ablaufprüfungen setzen Fristspalten deterministisch relativ zur DB-Uhr. HTTP-Clients verwenden `https://test.invalid`, passende Origin-/Custom-/CSRF-Header und echte Cookiejars. Fixtures setzen keinen Allow-all-Schalter. Zwei DB-Verbindungen/Worker und explizite Barrieren steuern Rennen; keine zufälligen Sleeps als Beweis. Poolgrenze klein halten und Connections nach jedem Fehler zurückgeben. + +### 14.2 Pflichtmatrix des Browser-/Personal-Kerns + +| ID / bevorzugte Testdatei | Automatisierter Fall | Zwingende Assertions | +|---|---|---| +| S01 `test_auth_sessions.py` | Login korrekt, falsch, unbekannt, Konto gesperrt/gelöscht | Nur korrekter aktiver Account erhält Cookie; generische 401 bei Fehlfällen; kein Sessiontoken im JSON/Log/DB-Klartext; bcrypt-Dummyweg aufgerufen | +| S02 | Passwort über 72 UTF-8-Bytes, Unicodegrenze, leeres/fehlendes Passwort, zusätzliche Rollenfelder | 422 vor bcrypt bei Bytegrenze; kein Abschneiden; `extra='forbid'`; kein Rechtewechsel | +| S03 | Idle-/Absolutfrist vor, auf, nach DB-Zeitgrenze | Ab Grenze 401; Cookie-Max-Age/Clientzeit ändern nichts; abgelaufene Session wird nicht reaktiviert | +| S04 | Erfolgreiche Fachaktivität, Session-GET und Renewal | Nur definierte Aktivität schiebt Idlefrist; nie über Absolutfrist; Pollingkonzept ohne Keepalive | +| S05 | Rotation | Genau ein neuer Hash/CSRF und höhere Generation; alter Cookie/CSRF scheitert; `auth_time`, MFA-Zeit und Absolutfrist bleiben gleich | +| S06 | Logout / zweimal Logout / falscher CSRF | Widerruf nach Commit; zweimal 204; falscher CSRF bei gültiger Session 403 ohne Widerruf; Cookie korrekt gelöscht | +| S07 | Logout-all, Passwortwechsel, Kontosperre, Faktorreset | Alle Geräte-Sessions und Authflows ungültig; Epoch erhöht; Passwortrevision nur bei Passwortänderung; kein wiederverwendbarer Zwischenflow | +| S08 | Passwortwechsel ohne/falsches aktuelles Passwort | Verweigert, Hash/Epoch unverändert; korrektes Passwort bewirkt atomaren Widerruf, keine verdeckte neue Session | +| B01 `test_auth_boundary.py` | Set-Cookie bei Login/Rotation/Logout | HttpOnly, Secure, SameSite=Lax, Path=/, kein Domain; Sessionwert nie JS-DTO; HTTPS-Browsertest liest Cookie nicht via `document.cookie` | +| B02 | Fremder Origin, Geschwisterhost, Suffixtrick, null, fehlende Origin+Referer, doppelter Origin | 403 vor Mutation; exakt passender Referer nur bei fehlendem Origin erlaubt; vorhandener falscher Origin nicht überstimmt | +| B03 | CSRF fehlt/falsch/von anderer Session/von anderer Generation | 403 bei gültigem Credential, keine Mutation; korrekter eigener Wert erlaubt den autorisierten Pfad | +| B04 | Login-CSRF, Preauth als Vollsession, Session-CSRF auf Flowroute | Ohne korrekt gebundenen Vorflow verweigert; kein Fachzugriff mit MFA-/Loginpreparecookie; kein Wechsel zwischen CSRF-Quellen | +| B05 | Fehlender Customheader, Cross-Origin-Preflight, Form-/textplain-POST, übergroßer Body | Verweigert (Header 403, Medientyp 415, Body 413); keine Credentials-CORS-Freigabe, keine Fach-/Authmutation | +| B06 | Doppelcookie, falsches Tokenformat, Querytoken, Profilheader, Cookie+Bearer | Kein Last-value-wins oder Authfallback; 401/422 gemäß Abschnitt 13; Session aus URL niemals akzeptiert | +| B07 | Gefälschte Forwarded-IP/Host von untrusted Peer | Keine Umgehung von Origin-/Rateprüfung; nur ausdrücklich konfigurierter Proxy beeinflusst Client-IP | +| B08 | Auth-DB/Policy/Schlüssel/Audit nicht verfügbar | 503 bei Pflichtabhängigkeit; keine Allow-Antwort, keine Cookieausgabe vor Commit; keine internen Details im Problem | +| A01 `test_account_lifecycle.py` | Unverified / pending Club / aktiver Personalaccount / unbekannter Zustand | Onboarding-Allowlist korrekt; keine Fachfreigabe für eingeschränkte Session; persönliche App benötigt keinen Club; fehlender Status verweigert | +| A02 | Gleichzeitiges Erstoperator-Provisionieren | Genau ein autorisierter CLI-Bootstrap gewinnt; kein offener Web-Erstadminweg; Operator ohne Faktor erhält nur Enrollmentflow | +| P01 `test_access_isolation.py` | Eigenes/fremdes persönliches Objekt in GET/Liste/Count/Suche/Export/Update/Delete/Medien | Eigene Daten erlaubt nach Capability; fremde 404 oder aus Listen entfernt; keine B-Inhalte/Counts/Dateien; kein Besitzer aus Body/Profilheader akzeptiert | +| P02 | Objektversion, fremde Eltern-ID, fremde Quellen-ID, Scope-/Owneränderung im Body | Unsichtbares Ziel 404 vor Versionstest, sichtbarer Konflikt 409; Cross-Owner-FK/Policy verhindert Einfügen; keine Mutation/kein Erfolgsaudit | +| P03 | Capability unbekannt, doppelt registriert, fehlende Objektpolicy, nicht registrierter Scope | Aufbaufehler bei Registry-/Routendefekt; verbleibender Laufzeitpfad verweigert; keine Standardrechte | +| P04 | Kein/malformiertes Headerpaar, Personal-Scope von B, Scope auf scopefreier Fachoperation | 422/403 gemäß Vertrag; keine Erstprofil-/Erstclubwahl und kein scopefreier Fachzugriff | +| P05 | Betreiber O auf persönlichem Objekt von B | Standardpersonalpolicy verweigert trotz Betreiberrolle und MFA | +| R01 `test_auth_races.py` | Passwortprüfung pausiert; danach Passwortreset/Kontosperre; Loginabschluss | Kein Sessioncommit mit altem Snapshot; Revisions-/Epochprüfung greift | +| R02 | Zwei Renewals derselben Generation | Genau ein Erfolg; Verlierer 401 ohne Set-Cookie; kein altes Credential gültig; UI verarbeitet nicht zwei Identitäten | +| R03 | Logout und Rotation in beiden Sperrreihenfolgen | Nach bestätigtem Widerruf keine gültige Session; spätes Cookie kann keine widerrufene Zeile beleben; in-flight Logout kann logische Session widerrufen | +| R04 | Logout-all/Kontosperre gegen Fachwrite, beide Commitreihenfolgen | Write vor Widerruf oder Verweigerung nach Widerruf; kein nach Widerruf autorisierter Commit; Audit passend, keine Teiländerung | +| R05 | Auditfehler und Commitfehler bei Login/Scopewahl/privilegierter Änderung | Alles rollt zurück; kein Success/Cookie vor Commit; Connections werden freigegeben | +| R06 | Mehrere Authworker, parallele Fehlversuche, Rollbackfallen | Atomare Rate-/Fehlversuchszähler und Challengeverbrauch; 429/gesperrter Flow bleibt trotz Fehlerresponse gespeichert | +| F01 `shared/session.test.js` | A→B, A→Logout und Kontowechsel mit verspätetem Erfolg/401/403/503 | Keine Altansicht/Altfehlermeldung; alte 401 beendet keine neue Session; aktueller 401 beendet, 403/503 nicht | +| F02 | Abgebrochener Write, verlorene Rotation, Cross-Tab-Renewal | Kein automatischer Fachwrite-Retry; sicherer Session-GET kann Status klären; Authmutationen serialisiert; unklarer Zustand bleibt geschlossen | +| E01 `tests/e2e/auth.spec.js` | Browsercookie, Reload, CSRF, Logout, Back-Navigation | Session bleibt HttpOnly, CSRF nur Speicher, kein persönlicher Browser-/PWA-Cache, nach Logout keine alten Inhalte; echte Browserattribute geprüft | + +413/415 und Headerfehler sind ergänzende stabile Problemcodes `payload_too_large`, `unsupported_media_type`, `browser_header_required`. Sie werden wie alle übrigen Fehler über den Foundation-Problemhandler ausgegeben, ohne angeforderten Body zu spiegeln. + +### 14.3 MFA-Pflichtmatrix + +| ID / `test_mfa_security.py` | Automatisierter Fall | Zwingende Assertions | +|---|---|---| +| M01 | Deterministische RFC-TOTP-Vektoren, Zeitfenster ±1, Nicht-ASCII-/falsche Eingabe | Korrekte Algorithmenwerte; bei sechs Stellen die letzten sechs Stellen des passenden RFC-Achtstellenvektors; außerhalb Fenster oder nicht exakt sechs ASCII-Ziffern verweigert | +| M02 | Derselbe TOTP mehrfach und gleichzeitig gegen zwei Challenges | Genau ein Commit; `last_accepted_counter` steigt atomar; Replay auch innerhalb Zeitfenster verweigert | +| M03 | Fünf falsche Codes, danach richtiger; neue Flows/andere Worker | Flow dauerhaft verbraucht bzw. Session widerrufen; Konto-/IP-Limits nicht umgangen; Fehlerzähler trotz 401 committed | +| M04 | Recoverycode zweimal/gleichzeitig, normalisierte/falsch formatierte Codes | Genau ein Verbrauch; nur definierte Normalisierung; Hash statt Code in DB; kein Code im Log | +| M05 | MFA-Flow abgelaufen, anderer Subject, nach Epoch-/Passwortänderung | Keine Vollsession, keine Wiederbelebung; Zweck-/Bindungsprüfung atomar | +| M06 | Operator ohne Faktor / vorhandene alte Passwortsession / Betreiberrollenerhöhung | Nur Enrollment; Fach-/Opszugriff verweigert; alte Session widerrufen; keine Runtime-Flagumgehung | +| M07 | Enrollment bestätigt, Counter verbraucht, Responseverlust/Neustart | Faktor/Codes/Session/Audit atomar; einmalige Secretausgabe; verlorene Pending-Ausgabe nur mit neuem Secret; keine alte Pending-Bindung verwendbar | +| M08 | MFA-Frist exakt fünf Minuten, Renewal, Step-up mit falschem/richtigem Passwort | Ab Frist `mfa_required`; Renewal frischt nicht auf; vollständiger Step-up rotiert Credential/CSRF und erhält Absolutfrist | +| M09 | Recovery-Login, Codeersatz/Disable ohne echten frischen TOTP, Operator-Disable | Login nach Passwort+Recovery möglich; Faktor-/Codeverwaltung verweigert; Betreiber kann MFA nicht abschalten | +| M10 | Ciphertext verändert, Key fehlt/rotiert, alter Key während Übergang | 503/keine MFA-Ausnahme bei Defekt; kontrollierte Neuverschlüsselung erhält Faktor; keinerlei Key-/Secretwert im Fehler | +| M11 | Lokale Recovery mit vollständigem Faktorverlust | Alle Sessions/Flows ungültig; Reset auditiert; danach nur erneute MFA-Einrichtung; Webresetroute nicht vorhanden | + +### 14.4 Bedingte Adaptertests bei tatsächlichem Funktionsumfang + +Diese Fälle werden Pflicht, sobald der Zielauftrag die betreffende Funktion registriert. Fehlt sie, prüft der Kern ausdrücklich die Nichtverfügbarkeit; keine als „bestanden“ verkaufte Skip-Suite. + +| ID / Bereich | Pflichtfälle bei Integration | +|---|---| +| O01 Club/Org | Mitglied in 1/2, unterschiedliche Rollen; Reader in 2 erhält keine Writerrechte aus 1; Mitgliedschaft inaktiv/gelöscht, Raum deaktiviert, Auswahl fremd; keine Mehrclubfallbacks | +| O02 Sichtbarkeit | Shinkan-Matrix privat eigen/fremd, Club passend/fremd, official; Leserecht erzeugt kein Änderungsrecht; Listen/Details/Graphreferenzen/Export/Medien gleich; lokale Plattformausnahme nicht auf persönliche Daten übertragen | +| O03 Entzugrennen | Mitgliedschaft, organisationsweite Rolle und einzelne Rollenzuordnung gegen Objektwrite; beide Commitreihenfolgen nach Abschnitt 9.4; Grantänderung sperrt gemeinsamen Raumanker | +| O04 Parent-/Poolgrenze | Cross-Tenant-Eltern/Kind-FK, Bulkimport, Export; falls RLS: zwei Scopes auf wiederverwendeter Connection und fehlender Transaktionskontext dürfen nichts freigeben | +| X01 Maschine | Abgelaufen/widerrufen, falscher Tenant, Actor deaktiviert, Delegation entzogen, leere Rechte, zusätzliche nicht erlaubte Capability, Cookie+Bearer; Tokenrechte ∩ aktuelle Policy; vollständiges Writeaudit | +| X02 externer Login | Ohne Adapter keine externe Identität akzeptieren; bei späterem SSO zusätzlich falscher Issuer/Audience/State/Nonce/PKCE, Account-Link per fremder gleicher E-Mail und unerlaubter MFA-Claim verweigert | +| X03 Streaming | Cookie/Origin beim Start, Ereignisse nach Rechteentzug/Logout, Scopewechsel, kein URL-Sessiontoken, keine DB-Verbindung über Verbindungsdauer gehalten | + +### 14.5 Konkreter Anschluss an vorhandene Tests I + +- [Shinkan Sessionprofil-Test](C:/Dev/shinkan-jinkendo/backend/tests/test_security_release.py:37): prüft mit Dependencyoverride, dass `/api/profile` nur das Sessionprofil verwendet. Für die Foundation auf echte Cookie-/Principalabhängigkeit übertragen und Profilheader-/Cross-Profile-Fälle ergänzen; der Bestandstest allein beweist die neue Cookieintegration nicht. +- [Shinkan Kontostatus-/Rollentests](C:/Dev/shinkan-jinkendo/backend/tests/test_account_capabilities.py:14) und [Onboardingverweigerung](C:/Dev/shinkan-jinkendo/backend/tests/test_account_onboarding_gate.py:15): Zustandsmatrix übernehmen, aktive Defaults/Disable-Flags im neuen Aufbau nicht übernehmen. +- [Shinkan Graphsichtbarkeit](C:/Dev/shinkan-jinkendo/backend/tests/test_exercise_progression_graph_visibility.py:26) und [Löschpolicy](C:/Dev/shinkan-jinkendo/backend/tests/test_exercises_delete_policy.py:65): konkrete Privat-/Club-/Official-Grenzen und Trennung Lesen/Ändern als Parametermatrix übertragen. +- [Shinkan Auth-Hardening](C:/Dev/shinkan-jinkendo/backend/tests/test_auth_hardening.py:23): TOTP, erforderliches aktuelles Passwort, Steuerzeichen und Tokenformate liefern Ausgangsfälle. Die vorhandene TOTP-Assertion ersetzt weder RFC-Vektoren noch DB-Replay-/Recoveryrennen; diese kommen gemäß M01–M11 hinzu. + +Die Testquellen wurden gelesen, nicht ausgeführt. Anpassung erfolgt im späteren Zielrepository; keine pauschalen Imports alter `main.py`-Apps und keine umfassenden Testläufe im Bestand. + +## 15. Konkreter Implementierungsauftrag für Cursor – Phase 3.4 + +**Dieser Abschnitt ist ein später ausführbarer Auftrag. Er wird in Phase 3.3 nicht ausgeführt.** Zielrepository und tatsächliche Fachfunktionen benennt der Implementierungsauftrag. Fehlt diese Zielangabe, keine bestehende App als vermeintliche Foundation umbauen. Innerhalb des benannten Zielauftrags gelten die folgenden Defaults ohne neue Grundsatz-/Freigabefragen. + +1. **Foundationstand prüfen.** A/B/C v0.3 verwenden; Composition Root, UoW, Problems, Settings und Frontendepoch beibehalten. Nur das benannte Zielrepository ändern, keine Quellproduktimporte zur Laufzeit. Vorhandene äquivalente Account-/DB-/Kryptografieadapter gezielt an die Verträge anschließen; kein Frameworkwechsel. +2. **Lokales Profil konkretisieren.** Wenn der Auftrag kein abweichendes Datenraummodell nennt: geschlossenes persönliches Produkt, Konto=Person, eigener Personal-Scope, lokaler administrativer Kontoprovisionierungsweg, keine öffentliche Registrierung. Club/Org erst bei tatsächlichem Fachbedarf über die beschriebenen Adapter. Keine Tenant-, Actor-, SSO- oder ACL-Editorstruktur auf Vorrat. Ein lokales Provisionierungskommando hält die ausdrücklich bestätigte Konto-/Adressprüfung fest; es darf unbekannte Webregistrierungen nicht als verifiziert kennzeichnen. +3. **Registry und Contracts implementieren.** Contexttypen aus Abschnitt 4; Session-/Scope-/Accessports produktlokal; feste Capabilitydefinitionen für tatsächlich vorhandene Routen. Alle geschützten Fachrouten benötigen Contextdependency und Servicepolicy. Eine automatisierte Routenprüfung scheitert bei nicht als öffentlich, scopefrei oder scoped klassifizierter API-Route; reine Middleware ist kein Ersatz. +4. **Schema atomar migrieren.** Lokales Accountmodell anbinden; Session-/Flow-/Faktor-/Recovery-/Rate-Strukturen aus Abschnitt 5 einschließlich der in Abschnitt 11 konkretisierten Felder anlegen. `auth_flows.initiating_session_id` und MFA-Herkunft/-Fehlversuchszähler vollständig berücksichtigen. Runtime braucht weder Owner-/DDL- noch BYPASSRLS-Rechte. Keine Migration gegen produktive DB in Tests. +5. **Browserboundary und Credentialadapter bauen.** HTTPS-Cookies, kein Domain, strikt begrenzte Proxy-/Hostkonfiguration, Origin/Referer, Fetch Metadata, Customheader, Credentialgebundener CSRF, Form-/Duplicate-/Legacy-Abwehr; Secretlogging redigieren. bcrypt und Shinkan-Dummyvergleich verwenden; 72-Byte-Grenze vor Hashaufruf. Faktoren lokal mit dem benannten Cipheradapter schützen, Key-ID-Readiness prüfen. Konfiguration bei unbekannter Umgebung/fehlendem Pflichtsecret verweigern. +6. **SessionService und MFA abschließen.** Endpunkte und DTOs aus Abschnitt 8/11 implementieren. Passwortvergleich vor Abschlusstransaktion, Revisionsprüfung darin. Fehlerresultate erst nach persistierten Fehlversuchen ausgeben; Cookies ausschließlich nach erfolgreichem Commit. Epoch-, Zweck-, Replay- und Recoveryverbrauch vollständig abdecken. Keine faktorlose Betreiber-Vollsession. Lokale Bootstrap-/Recoverykommandos gegen isolierte Test-DB prüfen. +7. **Scope-/Objektadapter integrieren.** Eigentümerbindung für den persönlichen Slice; bei Club/Org Shinkan/Kairo-Referenzen gezielt übertragen. Explizite Auswahl, gemeinsame Listen-/Objektprädikate, scoped SQL und Eltern-/Kindconstraints, frische Accessprüfung in Fach-UoW. Sperrvertrag für alle entsprechenden Entzugs-/Rollenänderungen implementieren, nicht nur für Leser. +8. **Frontend anschließen.** Ein Same-Origin-Client, Cookiecredentials, JSON-Customheader, richtiger Session-/Flow-CSRF. CSRF nur Speicher. Authmutationlock, bewusstes Scopewechselverfahren, epoch/Abort/Cacheleerung, kein automatischer Write-Retry; Login-/MFAfehler lokal behandeln. Keine neue globale Statebibliothek ohne konkreten Bedarf. +9. **Pflichttests ausführen.** Abschnitt 14: Kern und MFA vollständig; bedingte Adapterfälle für tatsächlich registrierte Funktionen. Gewählte Testbefehle und Pfade im Zielprojekt konsistent machen, reale Testcollection kontrollieren, isoliertes PostgreSQL samt Runtime-Rolle nachweisen. Ein absichtlich roter erforderlicher Securitytest muss das Gate blockieren; keine Skip- oder Exitcode-Unterdrückung. Kein Test gegen laufende Kunden-/Bestandscontainer. +10. **Lieferstand konkret belegen.** Commit, Lockfiles, OpenAPI, Testbefehle/-umgebung, tatsächlich ausgeführte Test-IDs/-Ergebnisse sowie noch nicht integrierte Adapter knapp dokumentieren. Fehlende Adapter bleiben sichtbar geschlossen. Nur bestandenes Verhalten als T markieren. Der Blueprintstatus V/K wird nicht durch Vorhandensein von Testdateien automatisch geändert. + +Die normale Gitea-Folge bleibt `develop → Development → Tests → bewusste menschliche Freigabe → main → Produktion`. Vor Produktion müssen die erforderlichen Auth-/Scope-/MFA-Gates wirksam bestanden sein und getesteter sowie ausgelieferter Quell-/Build-/Artefaktstand eindeutig zusammenpassen. R1 „Build once, deploy many“ bleibt bevorzugt; R2 kontrollierte reproduzierbare getrennte Builds bleibt erlaubt, mit Qualifikation des konkreten Produktionskandidaten vor dessen Einsatz. Keine neue CI/CD-Infrastruktur, kein Test ausschließlich nach Produktionsdeploy als Ersatz. Die spätere menschliche Produktionsfreigabe ist bestehender Betriebskontrakt, keine zusätzliche Blueprint-Freigabeschleife. + +## 16. Prüfstand dieser Lieferung und Grenzen + +In Phase 3.3 entstanden ausschließlich dieser vollständige Blueprint und seine darin eingebetteten Schnittstellen-, Schema- und Testspezifikationen. Produkt-Repositories, Foundation v0.3 und ältere Dokumentversionen wurden nicht bearbeitet. Es gab keine Codeimplementierung, Paketinstallation, Migration, produktive DB-/Credentialnutzung, SSO-Einrichtung oder Anwendungstestläufe. + +Dokumentprüfung umfasst lokale Linkziele, Python-Syntax der illustrativen Ausschnitte, Abdeckung der zwölf beauftragten Themen und Konsistenz der Session-/Scope-/MFA-/Fehlerverträge. Das ist kein T-Nachweis für die geplante Anwendung. Der untenstehende Quellstand dokumentiert die gezielt verwendeten lokalen Dateien; eine Git-HEAD-Angabe allein behauptet keinen sauberen Checkout. Die Hashes beschreiben die tatsächlich gelesenen Dateiinhalte. Es erfolgt keine erneute Produktreifebewertung. + +Externe Gegenprüfung war auf drei Primärquellen begrenzt: OWASP Session Management (Hashspeicherung), OWASP CSRF (Synchronizer/Origin) und RFC 6238 (TOTP-Replay). Sie dient der Prüfung kritischer Details und ersetzt weder die Jinkendo-Referenzen noch eine umfassende neue Recherche. + +### 16.1 Lokaler Quellstand + +Lesestand 16.10.2026; SHA-256 jeweils über die vollständige Quelldatei, nicht nur den zitierten Ausschnitt. + +- `shinkan-jinkendo`: Git-HEAD `f10c28e5cdcef52cc44e953a8494b4bbe35b77fe` +- `mitai-jinkendo`: Git-HEAD `95453d548a2113555cd7e8f01fbbf267cbe34f3f` +- `kairo-jinkendo`: Git-HEAD `ea0aa18b8dd9a55f663a996d74e63b7e3ee0dc16` +- `Kansho`: Git-HEAD `89d149684eab9211d6ef21181d018de097a61783` + +| Gelesene Implementierungs-/Testquelle | SHA-256 | +|---|---| +| [shinkan-jinkendo/backend/auth.py](C:/Dev/shinkan-jinkendo/backend/auth.py) | `a7ff535b8d6d746d325327d9eb198849ca26f921d58a6ddf588e84eafc0adb7c` | +| [shinkan-jinkendo/backend/routers/auth.py](C:/Dev/shinkan-jinkendo/backend/routers/auth.py) | `54a2d89dc0deded68678512faefee31da2183eb3bc8416ccc81f14b2f8a7883f` | +| [shinkan-jinkendo/backend/account_lifecycle.py](C:/Dev/shinkan-jinkendo/backend/account_lifecycle.py) | `9884b1446de4476038b4f0a46a84f40c12bb2d562526e17ef43865fdafa9e2ae` | +| [shinkan-jinkendo/backend/account_onboarding_gate.py](C:/Dev/shinkan-jinkendo/backend/account_onboarding_gate.py) | `348e863027f097fb7942cb49da06e3bbab540fc76a977fafae1dbd0dfcbe386c` | +| [shinkan-jinkendo/backend/tenant_context.py](C:/Dev/shinkan-jinkendo/backend/tenant_context.py) | `41048e11fec89981c4cba33d887e9dfb8b4c9e1d7b78a2be6b3f31b2170cd6be` | +| [shinkan-jinkendo/backend/capabilities.py](C:/Dev/shinkan-jinkendo/backend/capabilities.py) | `b31e0648e4c0709d69835bc52c727873784830fba1f589f3dde6f06e697a799e` | +| [shinkan-jinkendo/backend/rights_registry.py](C:/Dev/shinkan-jinkendo/backend/rights_registry.py) | `49992f1993b2e0d0e3bc7e50d44862d423bd68907b5a5d7f2f019edb99385555` | +| [shinkan-jinkendo/backend/totp_auth.py](C:/Dev/shinkan-jinkendo/backend/totp_auth.py) | `00c39c9c1bcf9ed78f6ba71019e025a92101d81df4a5caee4927f784e0128e62` | +| [shinkan-jinkendo/backend/tests/test_security_release.py](C:/Dev/shinkan-jinkendo/backend/tests/test_security_release.py) | `94f5b353eed18d86159f834a8d831c054280c7aa61c20cf4fd29b900811d15f0` | +| [shinkan-jinkendo/backend/tests/test_auth_hardening.py](C:/Dev/shinkan-jinkendo/backend/tests/test_auth_hardening.py) | `329eb0ddf1cf636fc56f55220274a14c41ce8e92ce758e31e960dd7cca5a348e` | +| [shinkan-jinkendo/backend/tests/test_account_onboarding_gate.py](C:/Dev/shinkan-jinkendo/backend/tests/test_account_onboarding_gate.py) | `9d8cda30c838bc24a4d922e347188ce84156faf3b724a306e3541af6e6b13fa3` | +| [shinkan-jinkendo/backend/tests/test_exercises_delete_policy.py](C:/Dev/shinkan-jinkendo/backend/tests/test_exercises_delete_policy.py) | `594f201c107098397521ff41a25ebb619138ee2c88ca04f6301356575bb201fd` | +| [shinkan-jinkendo/backend/tests/test_exercise_progression_graph_visibility.py](C:/Dev/shinkan-jinkendo/backend/tests/test_exercise_progression_graph_visibility.py) | `0c14fd49ba0df953278ab53bfc2f0fd172035dd3c1fa9bc9841d14522b80bc94` | +| [mitai-jinkendo/backend/auth.py](C:/Dev/mitai-jinkendo/backend/auth.py) | `25d666b3f69cac0d18fa7abc969f51b16b889d6b6ff41d6f054d0d39941e8c1b` | +| [mitai-jinkendo/backend/routers/profiles.py](C:/Dev/mitai-jinkendo/backend/routers/profiles.py) | `8d017775507e24181cdaf966bd9f403572cd3eb91037d3425c3197b40271718e` | +| [kairo-jinkendo/backend/tenant_context.py](C:/Dev/kairo-jinkendo/backend/tenant_context.py) | `f40b7379cef5449e94a997791f36a48a0340de8cf58e539b908bed5e3cd08df1` | +| [kairo-jinkendo/backend/operational_auth.py](C:/Dev/kairo-jinkendo/backend/operational_auth.py) | `765150b8a85e4e2d5802a4365d4b19aa6531c00fcebedc6f2306562dc9b83c36` | +| [kairo-jinkendo/backend/services/actor_service_tokens.py](C:/Dev/kairo-jinkendo/backend/services/actor_service_tokens.py) | `c2a66ee02d1e745cedf9f0ce49d442e75bd21727a85c91ce97a78c501fc7c4a9` | +| [Kansho/backend/auth.py](C:/Dev/Kansho/backend/auth.py) | `53956af1767fa8fbe32d8262b273c14dc2f1f1786dff01ed1c5a8c4fdd41d111` | +| [Kansho/backend/journal_store.py](C:/Dev/Kansho/backend/journal_store.py) | `d3b825bc977adb25cfd05c37c44dbd5f202c5674cfa571c8a10e50b0b9d4ae88` | +| [Kansho/backend/routers/journal.py](C:/Dev/Kansho/backend/routers/journal.py) | `9ee1e6fb5434a96e247833a2102151c744eb1e58507db55de158c8f4f91546b9` | +| [Kansho/docs/architecture/functional/guardrails.md](C:/Dev/Kansho/docs/architecture/functional/guardrails.md) | `deadd95b5019fe807026616f6ff74a2467d9d951702c032573d59f27c125dc4b` | + +**Ende des Phase-3.3-Auftrags. Die tatsächliche Implementierung beginnt erst mit dem gesonderten Phase-3.4-Auftrag.** diff --git a/docs/reference/Jinkendo_Entitlements_Usage_Quotas_Blueprint.md b/docs/reference/Jinkendo_Entitlements_Usage_Quotas_Blueprint.md new file mode 100644 index 0000000..1e41af6 --- /dev/null +++ b/docs/reference/Jinkendo_Entitlements_Usage_Quotas_Blueprint.md @@ -0,0 +1,584 @@ +# Jinkendo – Entitlements, Usage & Quotas Blueprint + +**v0.1 · 16.10.2026 · Spezialblueprint 4 nach Release, KI-Gateway und Workflow-Laufzeit · technischer Entwurf V/K** + +## 1. Ziel und bestehende Verträge + +Dieser Blueprint spezifiziert produktlokale Funktionsfreigaben, Verbrauchserfassung und atomare Kontingentgrenzen. Er konkretisiert `EntitlementPolicy` der Application Foundation und den `UsageBudgetPort` des KI-Gateways. Cursor kann damit einen benannten Fachfall umsetzen, sobald ein Implementierungsauftrag vorliegt. Hier wird ausschließlich dieses Dokument erstellt. + +Grundlagen: + +- [Technische Referenzarchitektur A v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md), [Application Foundation B v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md), [Entscheidungen C v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md). +- [Auth, Session & Scope](C:/Dev/jinkendo-phase3-3-auth-session-scope-blueprint-2026-10-16/Jinkendo_Auth_Session_Scope_Blueprint.md), [Release, Betrieb & Recovery](C:/Dev/jinkendo-release-betrieb-recovery-blueprint-2026-10-16/Jinkendo_Release_Betrieb_Recovery_Blueprint.md), [KI-Gateway](C:/Dev/jinkendo-ki-gateway-provider-privacy-blueprint-2026-10-16/Jinkendo_AI_Gateway_Provider_Privacy_Blueprint.md) und [Prompt-/Platzhalter-/Workflow-Laufzeit](C:/Dev/jinkendo-prompt-placeholder-workflow-blueprint-2026-10-16/Jinkendo_Prompt_Placeholder_Workflow_Blueprint.md). +- Beschlossene ADR-01 bis ADR-14 aus dem [Entscheidungsregister](C:/Dev/jinkendo-architecture-consolidation-phase2-v0.2-2026-10-15/05_Architecture_Decision_Register.md), insbesondere ADR-10 für atomare harte Grenzen und ADR-13 für produktlokale Umsetzung. Historische Freigabeformulierungen eröffnen keine neue Freigabeschleife; ADR-15/16 bleiben offen. +- [Phase-3.1-Wissenselemente](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json): KI-MIT-05, KI-SHK-03 und ergänzend KI-KAI-05; [Quellenregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/sources.json), [Testregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/tests.jsonl), [Guardrailregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/guardrails_source_register.jsonl). + +Es entsteht kein zentraler Billingdienst, Zahlungsanbieter, Checkout, Rechnungswesen oder gemeinsamer Tenantstore. Preise, Steuern, Zahlungsbedingungen und neue Produktpakete werden nicht festgelegt. Die Begriffe Kosten/Verbrauch beschreiben technische Budgetkontrolle, keine Rechnung an Kunden. Shinkans manuell gesetzte Vereinspläne bleiben ein zulässiger lokaler Einstieg. Ein Produkt ohne kommerzielle Kontingente benötigt nur seine tatsächlich erforderlichen Funktions- und technischen Sicherheitsgrenzen. + +| Nachweisgrad | Aussage | +|---|---| +| **V** | Vorgeschlagener technischer Standard für eine spätere Umsetzung | +| **I** | Statisch gelesene vorhandene Implementierung oder Dokumentquelle | +| **T** | Tatsächlich ausgeführte Prüfung mit ausdrücklich begrenztem Umfang | +| **K** | Noch nicht integrierte/getestete Kombination | + +Alle neuen Schnittstellen, SQLmuster und Abläufe sind **V/K**. Bestehende Testdateien sind **I**, kein bestandener Testlauf. Der abschließende Dokumentcheck ist nur T für Dateiintegrität, Verweise und Beispielsyntax. Blueprint und Foundation sind keine bereits produktionsreife Referenzimplementierung. + +### 1.1 Verbindliche Architekturverträge und technische Defaults + +| Verbindlich | Anpassbarer technischer Default | +|---|---| +| Identität, Scope, Capability, Objektzugriff und Entitlement getrennt; alle nötigen Prüfungen bestehen | Benennung von Features, Plänen und Capabilities | +| Server bestimmt Kontingentsubjekt und Messgröße; kein Client wählt ein fremdes oder günstigeres Konto | Lokale Abbildung Account/Profil bei Mitai, Club bei Shinkan | +| Harte Grenze erfordert atomare Zulassung und idempotente Buchung; unbekannte Wirkung ist keine Null | Produktlokale PostgreSQLzeilensperren und Ledgerstruktur | +| Fehlende/defekte Policy ist keine unbegrenzte Erlaubnis | UTC-Kalendermonate als erste periodische Variante | +| Externe Kosten ohne belastbare obere Schranke dürfen keine zugesicherte harte Kostengrenze passieren | Zuerst harte Callanzahl; Token-/Kostenmetriken zunächst beobachtend | +| Kein Netzwerk in offener Fachtransaktion; Resultat, Callabschluss, Verbrauch und Audit konsistent | Adapter-/Dateipfade, technische Größen-/Zeitgrenzen | +| Quoten-Ausnahme erteilt keine Objekt-, Privacy- oder Maschinenrechte | Befristete featurebezogene Ausnahmen mit bestehender Capabilitytechnik | +| Release-Gates, Quell-/Buildzuordnung und menschliche Produktionsfreigabe nach ADR-11 | R1 bevorzugt; kontrollierte separate Builds R2 bleiben zulässig | + +Ein anderer Default ist bei begründetem Produktbedarf möglich. Dazu gehören ein anderes Kalenderfenster oder eine andere klar benannte Verbrauchseinheit. Eine Änderung der verkauften Einheit wird dadurch nicht automatisch autorisiert; dieser Blueprint legt keine neuen Kundenzusagen fest. + +## 2. Gezielte Implementierungsreferenzen + +| Quelle I | Wiederverwenden | Gezielte Ergänzung V/K | +|---|---|---| +| Mitai [Featureprüfung](C:/Dev/mitai-jinkendo/backend/auth.py:173), [Tarifauflösung](C:/Dev/mitai-jinkendo/backend/auth.py:129), KI-MIT-05 | Registrierung bekannter Features, lokale Plans-/Grantauflösung, differenzierte Ablehnungsgründe | Auslesen und späteres Erhöhen ist keine atomare Zulassung. Fehlende Profile nicht als Free-Identität behandeln. Kein interner Commit beim prüfenden Aufruf. | +| Mitai [Verbrauchserhöhung](C:/Dev/mitai-jinkendo/backend/auth.py:318), [Subscriptionansicht](C:/Dev/mitai-jinkendo/backend/routers/subscription.py:16), [Featuremapping](C:/Dev/mitai-jinkendo/.claude/docs/technical/FEATURE_ENFORCEMENT_MAPPING.md:1) | Nutzerverständliche Limits/Verbrauch und Zuordnung von Funktionen zu Features | Historisches Mapping und Statusvermerke beweisen keine aktuelle vollständige Routeabdeckung. Eigene Connection/Commit und Reset beim Lesen nicht übernehmen. | +| Mitai [Widgetentitlements](C:/Dev/mitai-jinkendo/backend/dashboard_widget_entitlements.py:27), [mehrere Anforderungen](C:/Dev/mitai-jinkendo/backend/widget_feature_requirements_db.py:29) | Explizite AND-Verknüpfung benötigter Features, unbekannte Widget-ID geschlossen | UIentscheidung ist keine APIautorität. „Keine Anforderung“ muss bewusst registriert sein, nicht durch Ladefehler entstehen. | +| Shinkan [Entitlements](C:/Dev/shinkan-jinkendo/backend/entitlements.py:57), [Registry](C:/Dev/shinkan-jinkendo/backend/rights_registry.py:20), KI-SHK-03 | Account-/Clubrollen, Capabilities und Vereinsfeatures getrennt zu einem Snapshot zusammenführen; `enforcement_subject` | Neues Snapshotmodell aus verifiziertem Scope, ohne ungesicherte Queryumleitung. Registryduplikate als Fehler behandeln; keine automatische DDL-/Planänderung im Startup. | +| Shinkan [Clubpläne/Overrides](C:/Dev/shinkan-jinkendo/backend/club_features.py:60), [Bestandszählung](C:/Dev/shinkan-jinkendo/backend/club_features.py:131) | Verein als Kontingentsubjekt und explizite Bestandsfilter, etwa aktive Mitglieder | Bestand, periodischer Verbrauch und Boolean getrennt typisieren. Defekte numerische Limits nicht zu `None`/unbegrenzt normalisieren. | +| Shinkan [Consume](C:/Dev/shinkan-jinkendo/backend/club_features.py:423), [Planningmeter](C:/Dev/shinkan-jinkendo/backend/planning_llm_usage.py:19) | Zentrale Verbrauchsfassade und Zählen tatsächlicher untergeordneter Modellaufrufe | Der ContextVar-Zähler zählt erfolgreiche Antworten im Requestspeicher. Er deckt weder Crash noch parallele Reservierung oder unbekannte Kosten. Kein pauschales „ein Workflow = ein Call“. | +| Shinkan [Quoten-Ausnahmen](C:/Dev/shinkan-jinkendo/backend/club_quota_bypass.py:83) | Benannte Capability statt pauschaler Adminsonderfall | Aufnahmeausnahme befristen/binden/auditieren; Verbrauch weiterhin erfassen. Keine Ausnahme von Privacy-/Objekt-/technischen Kostenlimits. | +| [Familienmodell](C:/Dev/shinkan-jinkendo/docs/jinkendo-family/FAMILY_ENTITLEMENT_MODEL.md:25), [offene Atomarität](C:/Dev/shinkan-jinkendo/docs/jinkendo-family/FAMILY_ENTITLEMENT_MODEL.md:287) | Vier unabhängige Prüfebenen und produktspezifisches zahlendes Subjekt | Diese konkrete Reservierungs-/Buchungsspezifikation schließt die technische Lücke für neue Implementierungen; keine Bestandskonformität behaupten. | +| Shinkan [lokale Abozusammenfassung](C:/Dev/shinkan-jinkendo/docs/product-readiness/03-abo-entitlements-abrechnung.md:1) | Bestehende Vereinsgrenze und manuell gesetzter Plan; Zahlungsdienst bleibt späterer Adapter | Kein Kopieren des persönlichen Mitai-Tiers nach Shinkan; keine neue Pricing-/Reifeanalyse. | +| Kairo [Featureregistrierung](C:/Dev/kairo-jinkendo/backend/feature_registry.py:37), [Entitlementsnapshot](C:/Dev/kairo-jinkendo/backend/entitlements.py:37), KI-KAI-05 | Ergänzend Duplikatsperre und explizite Metadatenregistrierung | Aktive globale Features und `probe` belegen weder lokale Planzusage noch harte Quoten. Kein Kairo-KI-/Workflowausbau. | + +Die [Mitai-Featurelogs](C:/Dev/mitai-jinkendo/backend/feature_logger.py:36) und [Shinkan-Featurelogs](C:/Dev/shinkan-jinkendo/backend/club_feature_logger.py:43) sind Diagnosemuster; eine Logzeile ist keine atomare Verbrauchsbuchung. Importseitiges Anlegen von Logdateien und `allowed=True` als Fehlerfallback gehören nicht in die Foundation. Kanshōs Privacy bleibt über das Gateway wirksam; hier wird keine neue Kanshō-Subscription oder zentrale Familienabrechnung erfunden. Tsumugu ist keine Implementierungsquelle. + +## 3. Begriffe, Subjekte und Prüfreihenfolge + +### 3.1 Vier unabhängige Fragen + +Eine Aktion benötigt eine aktuelle Identität, die fachliche Capability, den konkreten Objektzugriff und die erforderliche Funktions-/Kontingentfreigabe. Die AccessPolicy des Auth-Blueprints prüft Identität, Scope und Objekt. Die EntitlementPolicy ersetzt sie nicht. Vor der Ausgabe kommerzieller Detailinformationen wird bereits Objektsichtbarkeit geprüft; ein fremder Datensatz liefert weiterhin 404, nicht „dessen Tarif ist erschöpft“. + +`EntitlementPolicy.require(context, feature, tx)` prüft in derselben UoW die aktuelle Funktionsfreigabe. Für eine harte mengenabhängige Aktion ist anschließend zusätzlich die atomare Mengenprüfung/Buchung nötig; ein früherer `require`-Aufruf oder UI-Snapshot reserviert nichts. Planname, Kaufstatus und Rollen werden nicht in Router-/Widgetbedingungen vermischt. + +### 3.2 Actor, Datenraum und Kontingentsubjekt + +| Begriff | Bedeutung | Beispiel | +|---|---|---| +| Principal | Wer den Auftrag verantwortlich ausführt | Lokales aktives Nutzerkonto oder künftig echte begrenzte Maschinenidentität | +| Scope | In welchem autorisierten Datenraum die Aktion stattfindet | Persönlicher Raum bzw. ausgewählter Club | +| QuotaSubject | Wessen Kontingent belastet wird | Mitais persönliches Konto, Shinkans Club | +| OperationalBudget | Zusätzliche technische Begrenzung des Produktbetriebs | Produktlokales externes Modellbudget, falls tatsächlich benötigt | + +`QuotaSubjectResolver` ermittelt das Subjekt ausschließlich serverseitig aus dem verifizierten Scope und einer registrierten Produkt-/Featurebindung. Bei Mitai kann der lokale Adapter das vorhandene Profil als Kontingentschlüssel beibehalten, muss es aber eindeutig dem authentifizierten Account zuordnen. Profil-ID und Principal sind keine austauschbaren Begriffe. Shinkans gemeinsamer Vereinsverbrauch bleibt am Club; ein Trainerwechsel oder anderes Mitglied erzeugt kein neues Kontingent. + +Für einen persönlichen Scope darf kein Club als Sponsor gewählt werden und für einen Clubauftrag kein persönlicher Free-Tarif als Ausweichkonto. Hybrid-/Sponsoringmodelle sind erst mit einer konkreten Produktregel zulässig, nicht durch ein Requestfeld `billing_subject_id`. Im ersten Schnitt belastet jedes Feature genau ein kommerzielles Subjekt. Optionale technische Produktbudgets werden zusätzlich per AND geprüft und besitzen eine eigene lokale Budgetklasse; sie schaffen keine gemeinsame Fachdatenbank. + +Ein Quotenstatus enthält keine persönlichen Fachwerte, Prompttexte oder fremden Nutzernamen. Ein Clubmitglied darf nicht allein durch Ausführungsrecht die detaillierten Einzelverbräuche aller Mitglieder sehen. `entitlements.read`, `usage.read_own` und gegebenenfalls `usage.read_club_summary` sind eigene Capabilities. + +## 4. Registrierte Features und effektive Freigaben + +### 4.1 Featurevertrag + +Ein `FeatureSpec` trägt ID, Revision, Modul, Beschreibung, erlaubte Scopearten, `subject_binding`, erforderliche Capabilityzuordnung, `kind`, Messgrößen/Einheiten, Periodenregel, Defaultpolicy und explizite Semantik der Zählauslöser. Registrierung erfolgt im Bootstrap, danach wird die Registry eingefroren. Doppelte IDs/Revisionen, unbekannte Meter, unvollständige Bindungen oder nicht implementierte Handler schließen das betroffene Modul. Code definiert die verfügbaren Funktionen; ein späterer Zahlungsdienst darf nur registrierte Plan-/Vertragszustände aktualisieren. + +| `kind` | Bedeutung | Beispiel / Behandlung | +|---|---|---| +| `boolean` | Funktion erlaubt/verweigert | Workflowfunktion an/aus; kein Mengenverbrauch | +| `periodic` | Verbrauch von Ereignissen in einem klaren Zeitfenster | Modell-Sendeversuche oder angelegte Einheiten pro UTC-Monat | +| `inventory` | Aktueller fachlich definierter Bestand | Aktive Mitglieder, nicht archivierte Übungen | + +Ein fehlender Eintrag ist `not_configured`, eine ausdrücklich unbegrenzte registrierte Menge ist `unlimited`, eine ausgeschaltete Funktion ist `disabled`. Diese Zustände werden nicht gemeinsam als SQL-/JSON-`null` interpretiert. Im lokalen Kompatibilitätsadapter kann `NULL` aus einer tatsächlich vorhandenen Limitzeile weiterhin unbegrenzt bedeuten; keine Zeile, ungültiger Typ oder negative Zahl darf dadurch nicht unbegrenzt werden. Legacy `-1` erfordert eine ausdrücklich benannte Übersetzung, keine großzügige Laufzeitnormalisierung. + +Booleanwerte sind echte Booleans, keine numerischen `limit=1` im neuen DTO. Mengen sind nichtnegative ganze Einheiten. Bei `limit=0` werden keine positiven Mengen zugelassen; das ist von der generellen Funktionsfreigabe unterscheidbar. `0`, fehlend, unbegrenzt und defekt sind vier verschiedene Zustände. Ein Feature ohne kommerzielles Gate wird ausdrücklich mit freier Policy registriert; Ladefehler erzeugen diesen Zustand nicht. + +`observe` erfasst Mengen ohne Kapazitätszusage, `soft` ergänzt erkennbare Überschreitungshinweise ohne Sperre durch die Mengenhöhe, `hard` erzwingt die atomare Admission. Identitäts-, Capability-, Objekt-, Funktions- und Privacyregeln gelten in allen drei Modi. Der Modus ist eine registrierte Produktpolicy, kein Request-/Environmentflag zum Abschalten eines zugesicherten Hardlimits. Auch beobachtende Mengen behalten ehrliche Unknownzustände. + +### 4.2 Plan, Grant, Override und Sperre + +Pläne sind versionierte lokale Zuordnungen bekannter Features; Subjektzustand besitzt eine monotone `entitlement_revision`. Änderungen an Plan, Override, Grant, Ausnahme oder Sperre sperren dieselbe stabile Subjektzeile wie Zulassungen und erhöhen die Revision. Keine neue Bucket-ID durch bloßen Planwechsel. + +Pragmatische Auflösung: registriertes Feature und technischer Kill-Switch zuerst; aktive explizite Sperre/Verweigerung gewinnt; ein gültiger Featureoverride ersetzt die konkrete kommerzielle Policy; ansonsten genau ein aktiver benannter Plangrant, dann lokale aktive Subscription/Planbindung, dann ein ausdrücklich registrierter Basistarif. Unklare/überlappende Grants ohne definierte Priorität werden beim Schreiben verweigert; defekte Bestandsdaten ergeben `policy_unavailable`. Nicht anhand des spätesten Ablaufdatums oder lexikografisch höchsten Tarifnamens raten. Ein zeitlicher Grant gilt im halboffenen Intervall `[valid_from, valid_until)`. + +Die Produktsemantik für `past_due`, Kündigung und Probephase wird als lokale Policy hinterlegt. Default einer neuen technischen Implementierung: kein automatischer Gratiszeitraum; ein beendeter Grant fällt nur auf eine ausdrücklich vorhandene Basispolicy zurück. Konto-/Objektrechte bleiben unabhängig. Kein erneuter Governanceentscheid und keine Änderung bestehender Kundenverträge durch diesen Blueprint. + +Eine Planreduktion löscht weder Daten noch Verbrauch. Liegen Bestand oder bereits beanspruchte Menge über der neuen Grenze, bleiben aktuelle Lese-/Lösch-/Korrekturrechte nach Authvertrag erhalten; neue positive Inanspruchnahmen werden gesperrt. Bestehende Nutzerinhalte nicht erst hinter einer neu erworbenen Rolle verstecken. Produkte definieren die nötigen nichtkommerziellen Datenzugangs-/Auskunftsprozesse separat; ein Premiumexportflag ist dafür keine allgemeine Autorisierungsentscheidung. + +## 5. Komponenten und Python-Schnittstellen + +Defaultstruktur: `app/modules/entitlements/{registry,models,resolver,policy,repository,service,api}.py` und `app/modules/usage/{models,periods,quota,repository,gateway_budget,reconcile}.py`. Kein eigener Netzwerkdienst. `create_app(settings, providers)` verdrahtet produktlokale Adapter. Registrierung ist DB-/netzfrei; explizite SQLmigrationen/Seeds ändern das Schema und bekannte Katalogstände vor Runtime gemäß Foundation, nicht im Import oder Appstart. + +```python +from dataclasses import dataclass +from datetime import datetime +from typing import Literal, Protocol +from app.core.context import RequestContext, Tx + +@dataclass(frozen=True, slots=True) +class QuotaSubjectRef: + kind: Literal["account", "club", "organization"] + subject_id: str + +@dataclass(frozen=True, slots=True) +class PeriodRef: + policy_revision: str + starts_at: datetime + ends_at: datetime + +@dataclass(frozen=True, slots=True) +class FeatureDecision: + feature_id: str + enabled: bool + reason: str + entitlement_revision: int + subject: QuotaSubjectRef + +class QuotaSubjectResolver(Protocol): + def resolve(self, tx: Tx, context: RequestContext, + feature_id: str) -> QuotaSubjectRef: ... + +class EntitlementPolicy(Protocol): + def require(self, context: RequestContext, + feature: str, tx: Tx) -> None: ... + +class LocalUsagePort(Protocol): + def consume(self, tx: Tx, context: RequestContext, *, + operation_id: str, feature_id: str, + quantity: int) -> None: ... +``` + +`FeatureDecision` ist ein interner Snapshot, keine dauerhaft gültige Freigabe. `quantity` ist eine strikt positive serverseitig aus der tatsächlichen Fachoperation ermittelte Ganzzahl, kein Clientverbrauch. Der Port gilt für registrierte periodische lokale Ereignisse und besitzt einen eindeutigen Operationseintrag; Bestand nutzt den eigenen Adapter aus Abschnitt 11. `Tx` stammt aus der Foundation; sämtliche beteiligten Repositories nutzen denselben Handle und committen nicht selbst. + +Für KI wird der bestehende Port **unverändert** verwendet; seine Typen werden nicht parallel nachdefiniert: + +```python +from typing import Protocol +from app.core.context import RequestContext +from app.modules.ai.contracts import BudgetEnvelope, UsageReport + +class UsageBudgetPort(Protocol): + def reserve(self, tx: object, context: RequestContext, + call_id: str, upper_bound: BudgetEnvelope) -> str: ... + def settle(self, tx: object, reservation_id: str, + actual: UsageReport) -> None: ... + def mark_unknown(self, tx: object, reservation_id: str) -> None: ... + def release_unsent(self, tx: object, reservation_id: str) -> None: ... +``` + +Der konkrete Adapter verlangt intern einen echten Foundation-Tx; `object` erhält die bereits veröffentlichte Signatur. `BudgetEnvelope` enthält `call_count`, `upper_input_tokens`, `upper_output_tokens`, `maximum_cost` und `cost_basis_revision`. `UsageReport` enthält optionale Input-/Outputtokens, `reported_cost`, `currency` und `status='reported'|'estimated'|'unknown'`. `reserve` löst Feature, kommerzielles Subjekt, Währung und optionale technische Budgets aus der serverseitigen Call-/Purposebindung auf, nicht aus zusätzlichen frei wählbaren Parametern. + +Ein internes `GatewayBudgetCoordinator.require_dispatchable(tx, context, call_id)` prüft nach vorhandener Callbindung die aktuelle Admission-/Policy-/Perioden-/Ausnahmebindung in T2. Das ist ein lokaler Koordinatorvertrag, keine neue öffentliche Gatewaymethode. `settle/mark_unknown/release_unsent` erhalten ihre Autorität aus dem unveränderlichen Call-/Reservierungsbezug und einem vertrauenswürdigen Gateway-/Recoverypfad; sie sind keine öffentlichen Kundenendpoints. + +## 6. Messgrößen und belastbare Obergrenzen + +### 6.1 Erste sichere Einheit: Modell-Sendeversuch + +Technischer Default für neue Modellkontingente ist **ein logischer Generate-Sendeversuch pro Call**, als Meter `generate_attempt`. Eine externe Antwort einschließlich Ablehnung/429/ungültigem Output belegt einen Versuch; sie garantiert keine fachlich erfolgreiche Analyse und keinen bestimmten Providerpreis. Sicher vor Sendbeginn verweigerte Arbeit zählt nicht. Möglicher Versand ohne Nachweis bleibt reserviert/ungeklärt. + +Das ist ausdrücklich eine technische Einheit. Ein Bestandsfeature namens `ai_calls`, das bisher erfolgreiche Analysen zählt, darf nicht stillschweigend umgedeutet werden. Sein Produktadapter muss die tatsächlich zugesicherte Einheit abbilden oder bei späterer Einführung eine versionierte neue Meterdefinition verwenden. Keine Kundentarife werden hier verändert. Unabhängig von der kommerziellen Einheit erfasst das technische Ledger jeden externen Versuch und jede Kostenunsicherheit. + +Ein Workflow mit drei ausgeführten Analysisnodes kann drei solche Versuche verursachen. Übersprungene Nodes verursachen keinen Generateverbrauch; lokale Pure Nodes ebenfalls nicht. Detection-/Tool-/Renderingkosten sind gegebenenfalls getrennte registrierte Zwecke und laufen nicht unsichtbar unter „ein erfolgreicher Workflow“. Im bisherigen Gatewaystandard ist Detection lokal; entsteht dort ein tatsächlich zu begrenzender Kostenverbrauch, benötigt er einen eigenen wirksamen Adapter. + +### 6.2 Token- und Kostenbudgets + +Token-/Kostenmetriken können beobachtend, soft oder hart sein. `estimated` bleibt eine Schätzung. Keine Umdeutung in `reported`, keine fehlende Usage als Null. Die Generate-Callzahl besitzt die klare Obergrenze eins. Für Token-/Kostenobergrenzen reicht weder Zeichenlänge noch ein pauschales „Tokens ungefähr Zeichen/4“. + +Eine harte Tokenobergrenze verlangt einen für das konkrete Modell/Tokenizer-/Providerprofil gültigen oberen Inputwert einschließlich aller versendeten System-/Schema-/Fragefelder und einer wirksam erzwungenen Obergrenze aller erfassten Output-/Reasoninganteile. Eine harte Kostenobergrenze verlangt zusätzlich eine überprüfte versionierte Kostenbasis mit Währung, Preis-/Rundungsregel und allen erfassten Komponenten. Routing, Cachepreise, Reasoning, Tools und Gebühren dürfen keine ungebundene zusätzliche Wirkung erlauben. Der konkrete Adapter muss dies vor realer Nutzung nachweisen; in dieser Dokumentphase wird kein solcher Provider ausgewählt oder qualifiziert. + +Default ist deshalb harte Callanzahl plus beobachtende Tokens/Kosten. Wenn eine Produktpolicy eine harte Token-/Kostengrenze fordert und eine notwendige obere Schranke im `BudgetEnvelope` `None` ist, bleibt der Call mit `budget_bound_unavailable` geschlossen. Das ist keine Aufforderung, eine Schätzung als Maximum einzutragen. Technische Längen-/Outputgrenzen des Gateways bleiben zusätzlich bestehen. + +Kosten werden intern mit `Decimal` und festen ganzzahligen Untereinheiten je registrierter Währung geführt; Default Skala sechs Nachkommastellen. Obergrenzen und erfasste Beträge werden konservativ zur nächsten Untereinheit aufgerundet, nie nach unten oder über Binärfloat konvertiert. Die zugrunde liegende normalisierte Dezimalbeobachtung kann getrennt erhalten bleiben. Kein automatischer Währungswechsel oder FXkurs. Währung und Preisbasis stammen aus dem gebundenen Serverprofil; Widerspruch/Missingwert bedeutet unbekannte Kosten, keine Währungsvorgabe aus dem Browser. + +`reported_cost` ist zunächst eine validierte Providerbeobachtung. Ob sie für das jeweilige Budget als endgültige Kostengröße taugt, bestimmt der qualifizierte Adapter. Ein Providerfeld ist keine Kundenrechnung und keine Zusage über spätere externe Korrekturen. Ohne entsprechende Endgültigkeit bleibt die Restbindung eines harten Kostenbudgets bestehen. + +## 7. Persistenz und rechnerische Invarianten + +Logische produktlokale Tabellen; konkrete Namen sind Defaults. Ein bestehendes Produkt darf seine Plan-/Granttabellen über Adapter weiterverwenden, sofern der vollständige Transaktionsvertrag erfüllt wird. Neue Tabellen werden nicht vorsorglich für ungenutzte Features angelegt. + +| Tabelle | Felder / Constraints | +|---|---| +| `entitlement_subjects` | PK aus Subjektart/lokaler ID; `entitlement_revision`, `row_version`, `recovery_blocked`, `integrity_blocked`; stabile Sperrzeile unabhängig von Plan und Monat | +| bestehende Plan-/Grant-/Overridetabellen | Bekannte Plan-/Featurerevision, explizite enabled-/Limitpolicy, Gültigkeitsfenster, erwartete Version, Auditactor; keine unbekannten Tarifnamen als freie Berechtigung | +| `quota_buckets` | Unique `(subject_kind, subject_id, meter_id, period_start, period_end, currency)`; Meterschema-/Periodenrevision, `used_known`, `held_total`, `held_unknown`, separat entsprechende Exemptmengen, `row_version`; nichtnegative Integer | +| `usage_reservations` | UUID, unique `call_id`; unveränderliche Actor-/Scope-/QuotaSubjectbindung, Purpose-/Meterrevisionen, Input-/Envelope-HMAC samt Key-ID, Admissionzeit/-revision, Entitlement-/Kostenbasisrevision, Ausnahmebezug, Zustand/Version; FK zum bestehenden `ai_calls` | +| `usage_reservation_lines` | Unique `(reservation_id, bucket_id)`; obere Menge, bekannte endgültige Menge, verbleibender Hold, Teilstatus, validierte Beobachtung; alle Einheiten explizit | +| `usage_events` | Append-only ID, unique `(operation_id, event_kind, meter_id, revision)`; Reservation-/Callbezug oder lokale Fachoperation, Mengenänderung, Evidence-/Reasoncode, UTCzeit; kein Prompt-/Responsevolltext | +| `quota_exemptions` | Bekannte Capability-/Feature-/Subjektbindung, Gültigkeitsfenster, Grantrevision, vergeben durch/Begründung; nur soweit Produkt solche Ausnahmen benötigt | +| bestehendes Audit und `ai_calls` | Fach-/Administrationsaudit und Callzustand weiterverwenden; kein zweiter Provider-Callledger | + +`currency` ist ein nichtnull kanonischer Wert: ISOcode bei Kosten, registrierter neutraler Wert für Zählmetriken. Damit erzeugen SQL-NULLs keine mehrfachen scheinbar gleichen Buckets. FK-/Unique-Bindungen verhindern das Vertauschen von Call, Scope, Reservation und Subjekt; UUIDbesitz allein verleiht kein Buchungsrecht. Alte Subjekte werden bei Kontolöschung nicht als neue unbelastete Identität wiederverwendet. Minimalnachweise folgen dem lokalen Lösch-/Recoveryvertrag. + +Für eine endliche Menge `L` gelten bei einer neuen normalen Zulassung mit Obergrenze `q`: + +```text +beansprucht = used_known + held_total +zulassen genau dann, wenn enabled und nicht gesperrt und + q >= 0 und beansprucht + q <= L + +remaining = max(0, L - used_known - held_total) +0 <= held_unknown <= held_total +``` + +`held_unknown` ist eine Teilmenge des gesamten Holds, wird also bei `remaining` nicht nochmals abgezogen. Verbindliche technische Budgets zählen zusätzlich alle als kommerziell exempt markierten Mengen. Alle betroffenen Dimensionen/Subjekte bestehen per AND oder die gesamte Reservierung rollt zurück. Kein erfolgreiches Reservieren der Callzahl, wenn die notwendige Kostendimension gleichzeitig scheitert. + +Für einen Generatecall ist `BudgetEnvelope.call_count` strikt eins; zusätzliche Mengenobergrenzen können ausdrücklich null sein, wenn dieser Wert tatsächlich belastbar ist. Nullkosten sind kein Ersatz für fehlende Kosteninformation. Lokaler Ereignisverbrauch verlangt weiterhin eine positive serverseitige Menge. Integerüberlauf und übergroße numerische Eingaben werden vor Addition bzw. SQLwrite verweigert. + +Die Bedingung wird unter DBsperre geprüft und mit Bucket-/Reservierungs-/Event-/Auditwrite gemeinsam committed. Es gibt keinen DBconstraint `used+held <= aktueller Planlimit`: Downgrades und echte Providerabweichungen können einen bereits entstandenen Überhang verursachen. Dieser wird wahrheitsgemäß gespeichert und sperrt neue Zulassungen; er darf nicht zum Verlust tatsächlicher Usage führen. Nichtnegative Mengen, FKs, eindeutige Ereignisse und Zustandsversionen bleiben technisch erzwungen. + +Ein Bucket ist die atomar gepflegte Projektion des Ledgers. Reconciliation prüft beide Richtungen und markiert Abweichungen `integrity_blocked`; sie erfindet keine fehlenden Buchungen aus Logs. Bei Unsicherheit keine neue harte Zulassung. Reservations-/Operationstombstones verhindern nach Cleanup die erneute Buchung desselben bekannten Vorgangs. + +## 8. Atomarität, Sperren und Idempotenz + +### 8.1 Gemeinsame Sperrordnung + +Für Fachphasen gilt weiterhin der Auth-/Workflowvertrag: **Account → Session → Datenraum → Mitgliedschaft → geschütztes Fachobjekt bzw. Execution → Node/Call**. Der Quotenvertrag ergänzt danach **Entitlement-/Budgetsubjekte in stabiler Reihenfolge → Buckets in stabiler Reihenfolge → Reservation/Ereignis → Ergebnis/Audit**. Die Subjektreihenfolge ist kanonisch nach Klasse, Art und ID; keine Sortierung nach veränderlichem Plannamen. Jeder Adapter hält dieselbe Reihenfolge ein. + +Plan-/Grantänderungen sperren nur die betroffenen Entitlementsubjekte und danach ihre Konfiguration/Audit; sie laden anschließend keine Fachobjekte/Calls unter Sperre nach. Technische Usageabschlüsse finden die unveränderlichen Bezüge zuerst lesend, sperren dann nötige Execution-/Callzeilen und Subjekte in obiger Ordnung, niemals später ein Nutzerkonto. Bereits gehaltene Transaktionslocks bleiben bis Commit bestehen; keine zweite Connection für den Quotencheck. + +Ein Subjekt wird kontrolliert provisioniert oder per eindeutiger `INSERT ... ON CONFLICT DO NOTHING`-Anlage erzeugt und anschließend gesperrt. Zwei erstmalige Zugriffe dürfen keine parallelen freien Zähler erzeugen. Mit `READ COMMITTED` werden nach Erwerb der stabilen Sperre die effektive Policy und Buckets frisch gelesen. Andere Isolationsstufen benötigen passende Serialisierungsbehandlung; kein blinder Retry um eine Phase, die externen Versand enthalten könnte. + +### 8.2 Reservieren + +`reserve` wird vom Gateway in **T2**, nach Rendering, Privacy-/Providerprüfung und Feststellung der belastbaren Bounds, unmittelbar vor dem Dispatchintent aufgerufen. T1 prüft frühzeitig die Funktion und Materialisierungsrechte; sie reserviert noch keine unbekannten Token-/Kostenwerte. Kostenpflichtige vorgelagerte Arbeit benötigte ihren eigenen registrierten Budgetvertrag. + +Die T2-UoW prüft aktuelle Identität, Scope/Objekt, Executionfence/Cancelzustand, Quellen und Policy; sperrt die Callbindung und alle nötigen Quotasubjekte; bestimmt DBzeit/Perioden und aktuelle Entitlementrevision; prüft alle Dimensionen; erzeugt Reservation, Holds und Reservierungsevent. Danach schreibt **dieselbe** UoW Dispatchintent/Bindings/Audit und markiert die Reservation als `dispatched` bzw. möglicherweise versendbar. Commit erst nach vollständigem Erfolg. Bei fehlgeschlagenem Commit gibt es keine gültige Dispatchpermit und keinen Send. + +Admissionzeit ist ein einmalig **nach Erwerb der Sperren** gelesener aktueller DBzeitwert, in PostgreSQL beispielsweise `clock_timestamp()`. Ein beim Transaktionsbeginn eingefrorenes `CURRENT_TIMESTAMP` darf nach Wartezeit nicht einen bereits abgelaufenen Grant oder Vormonat freigeben. Derselbe erfasste Wert bestimmt Gültigkeits- und Periodenentscheid; die Dispatchpermit begrenzt anschließend die Zeit bis Sendbeginn. + +Wiederholtes `reserve` derselben Call-ID mit derselben unveränderlichen Eingabe/Envelopebindung liefert dieselbe Reservation ohne zweiten Hold. Es muss den Ledgerzustand beachten: `dispatched/unknown` ist keine erneute Versanderlaubnis. Unterschiedliches Subjekt, Input, Purpose oder Envelope ergibt `reservation_conflict`. Eine legitime Sessionerneuerung verändert den HMAC der Facheingabe nicht, erfordert aber aktuelle Authprüfung. Der Gatewaykoordinator behandelt eine neue Policy-/Preis-/Quellenbindung als `context_changed`, nicht als kostenloses Resize einer bereits dispatchten Reservation. + +Eine Erneuerung der kurzen Gatewaypermit ohne jemals begonnenen Transport darf die bestehende Reservierung nur nach überprüfbarer exklusiver Sendkontrolle weiterverwenden. Kann der Adapter den Nichtversand nicht sicher belegen, bleibt `unknown`. Ein abgelaufenes Permit oder eine freie Workerlease allein ist kein Nachweis. Eine inzwischen andere Kalenderperiode oder kommerzielle Limitrevision erfordert gegebenenfalls Freigabe der sicher unversendeten alten Bindung und eine konsistente neue Admission. Inhaltliche Eingabe, Gateway-/Privacy-/Providerpolicy, Route und unveränderliche Envelopebindung werden dabei nicht still geändert; solche Änderungen bleiben `context_changed` und benötigen nach Gateway-/Workflowvertrag eine neue Ausführung. + +Für einen belegbar `failed_unsent`/`released_unsent` gebliebenen Call kann der interne Koordinator eine neue `admission_revision` derselben Reservation/Call-ID anlegen und Holds erneut atomar erwerben. Vorherige Admissions bleiben als Events erhalten; aktuelle Lines sind ihre Projektion, Ereignisschlüssel enthalten die Admissionrevision. Keine reaktive Admission bei `dispatched/unknown`, endgültig verbrauchter Menge oder fehlendem Nichtversandnachweis. Das ist der explizite Wiederaufnahmefall unversendeter Arbeit aus dem Workflow-Blueprint, kein allgemeiner Modellretry. Ein gewöhnliches Wiederholen von `reserve` allein reaktiviert keine freigegebene Reservation. + +### 8.3 Idempotente Buchung und begrenzte Korrektur + +`settle`, `mark_unknown` und `release_unsent` sind zustandsgeprüfte Ereignisse mit eindeutigen Schlüsseln. Gleiches erneut angewendetes Ereignis ist ein No-op. Ein anderes angebliches Endergebnis für eine bereits endgültig gebuchte Metrik liefert `usage_conflict`; spätere tatsächliche Korrekturen laufen als benannte Reconciliationereignisse mit eigener Revision/Evidence, nicht als Überschreiben der Historie. + +`release_unsent` ist ausschließlich für bewiesenen Nichtversand zulässig. Ein nach Dispatchintent verlorener Prozess kann das nicht allein anhand fehlender Antwort beweisen. Im üblichen T2-Ablauf entstehen Reserve und Dispatchintent zusammen; es gibt daher kein reguläres langes „reserviert, aber noch nicht entschieden“-Zeitfenster. Ein benötigter lokaler Vorhaltefall muss die Reservation ausdrücklich `held_unsent` lassen und darf noch keinen Dispatch erlauben. + +Kein Kunde kann Reservation-ID, Usagewerte, `not_sent` oder einen Bypass per Body bestätigen. Interne Operationen sind fest an Call und registrierte Provideradapter gebunden. Begrenzte DBwiederholungen vor Dispatch bleiben lokale Transaktionswiederholungen; sie erzeugen keine zusätzlichen Modellversuche. + +## 9. Abschluss, unbekannte Wirkung und Reconciliation + +### 9.1 Zustände je Reservation und Metrik + +| Zustand | Bedeutung | Buchungsfolge | +|---|---|---| +| `held_unsent` | Nur vorgehalten, Sendbeginn sicher ausgeschlossen | Obergrenze belegt; nach erneutem Check dispatchen oder beweisbar freigeben | +| `dispatched` | Dispatchintent committed, externe Wirkung möglich | Hold bleibt belegt; kein Replay und kein TTLrefund | +| `unknown` | Versand/Verbrauch nicht abschließend geklärt | Ungeklärte Holds zählen weiter; neue externe Zulassung nach Default gesperrt | +| `partially_settled` | Einige Metriken endgültig, andere unsicher | Bekannte Werte buchen; nur ungeklärte Restmetriken halten | +| `settled` | Alle benötigten Budgetmetriken endgültig geklärt | Endgültige Mengen und freigegebene Restbindungen dokumentiert | +| `released_unsent` | Nichtversand bewiesen | Alle nicht verbrauchten Holds atomar freigegeben; Calltombstone bleibt | + +`mark_unknown` verschiebt den noch offenen Hold in den Unknownanteil, ohne ihn zu erhöhen oder freizugeben. Für Metriken ohne endliche Reservierung wird eine sichere Unknownbeobachtung erfasst; fehlende Boundwerte werden nicht zu Null. `settle` kann z. B. die bekannte Callzahl eins und gemeldete Inputtokens buchen, während fehlende Kosten weiter unbekannt bleiben. Eine Headerphase wird aus allen Lines abgeleitet; sie ersetzt deren Gewissheitszustand nicht. + +Für eine endgültig verlässliche tatsächliche Menge `a <= q` verschiebt Settlement atomar `a` nach `used_known` und entfernt den gesamten zugehörigen Hold `q`; `q-a` wird damit frei. Für einen geschätzten Wert wird nur die Beobachtung gespeichert, nicht die harte Restbindung freigegeben. Ein tatsächlich gemeldeter endgültiger Nullwert ist möglich; ein nicht vorhandenes Feld ist kein Nullnachweis. Kosten und Tokens haben jeweils eigene Qualifikations-/Endgültigkeitsregeln, auch wenn `UsageReport.status` als Gesamthinweis nur einen Wert besitzt. + +Ein validierter tatsächlicher Verbrauch oberhalb der angenommenen Obergrenze wird vollständig und unverfälscht gebucht. Zusätzlich Integritätsincident und Sperre für neue betroffene Aufrufe; im Default keine fachliche Erfolgsfreigabe für den verletzten Budgetvertrag. Kein Clampen auf das reservierte Maximum und kein Rollback, das echte externe Wirkung verschwinden lässt. Eine harte Grenze kann nur unter der Voraussetzung nachgewiesener und eingehaltenen Transport-/Providerbounds zugesichert werden; die reine Reservierung verhindert keine Falschmeldung oder vertragswidrige Mehrverarbeitung des Providers. + +### 9.2 Abschluss zusammen mit Gateway/Workflow + +Erfolgsfall T3: aktuelle Ausgabe-/Quellenrechte, Gatewayvalidierung und gegebenenfalls `WorkflowResultSink`; Ergebnis-/Nodecheckpoint, Callabschluss, `settle` und Audit in **derselben** Foundation-UoW. Scheitert ein auditpflichtiger Teil, ist der Fachcommit nicht erfolgreich. Der Workflow erhöht keine Zähler nochmals am Endknoten oder in einem HTTPresponsehook. + +Bei Entzug, Cancel, ungültigem Output oder fehlgeschlagenem Fachcommit kann bereits Verbrauch existieren. Ein enger interner Gatewayabschluss schreibt dann in einer **eigenen kurzen technischen UoW** ausschließlich bekannte Usage oder `unknown`, Calloutcome und Audit unter der unveränderten ursprünglichen Subjekt-/Reservierungsbindung. Er gibt keine Fachrechte, speichert keinen verworfenen persönlichen Output und erzeugt keinen neuen Call. `settle` verlangt deshalb keinen weiterhin berechtigten Endnutzercontext; seine Autorität ist die vertrauenswürdige technische Callbindung. Diese Ausnahme von fachlicher Nutzerfreigabe berechtigt ausschließlich zur wahrheitsgemäßen Buchung bereits entstandener Wirkung. + +Ist die Datenbank nicht verfügbar oder stürzt auch dieser Abschluss ab, bleibt der vorher atomar gespeicherte Dispatchhold bestehen. Recovery setzt offene `dispatched`-Vorgänge konservativ auf `unknown`, statt erneut zu senden oder die Reservation freizugeben. Ein HTTPfehler, Provider429, Timeout, verlorenes Browserfenster oder Cancel ist allein keine Aussage über Kostenfreiheit. + +### 9.3 Ungeklärte Fälle und spätere Belege + +Ein automatischer Job darf bekannte Ledgerzustände rekonstruieren, Holds prüfen und auf Integritätsfehler schließen. Er darf keine modellgenerierende Wiederholung auslösen. Lesende providerbezogene Statusklärung ist nur über einen bereits qualifizierten Adapter mit stabiler Requestreferenz und ohne zusätzlichen Generate zulässig; ein solcher Adapter ist keine Voraussetzung dieses ersten Schnitts und wird hier nicht entwickelt. + +Ohne technische Endinformation bleibt der Fall blockiert oder wird über einen ausdrücklich berechtigten lokalen Reconciliationservice geklärt. Dieser erhält einen vorhandenen Call-/Reservierungsbezug, erwartete Version, eindeutigen Evidencebezug, betroffene Metrik und die begründete Art `final_usage` oder `proved_unsent`. Er prüft keine freien Kundendaten als Beweis. Konfligierende Belege oder fehlende klare Zuordnung verweigern die Änderung. Kein öffentliches „Verbrauch zurücksetzen“-Endpoint. + +Eine kulante zusätzliche Nutzungsfreigabe ist eine eigene befristete Entitlement-/Allowanceänderung. Sie darf im Ledger nicht so tun, als sei der alte unsichere Call kostenlos gewesen; technische Kostenlimits und Unknownsperre bleiben bestehen, soweit die neue Freigabe sie nicht unter einem ausdrücklich begrenzten echten Risiko-/Reconciliationvertrag adressiert. Dieser Blueprint führt keinen solchen automatischen Kreditmechanismus ein. + +## 10. Perioden, Planwechsel und Quoten-Ausnahmen + +### 10.1 Unveränderliche Zeitfenster + +Default sind UTC-Kalendertag oder UTC-Kalendermonat in `[starts_at, ends_at)`; ein Monatsende ist kein Zeitraum von pauschal 30 Tagen. Die DBzeit beim verbindlichen T2-/lokalen Buchungsentscheid bestimmt die Zuordnung, nicht Browserzeit, Antwortzeit oder letzter Login. Der bis zum Sendbeginn höchstens kurz gültige Dispatchpermit kann über eine Periodengrenze reichen; Zuordnung bleibt ausdrücklich der dokumentierte Dispatchentscheidzeitpunkt. + +Ein neuer Monat erzeugt einen neuen Bucket, setzt aber keinen alten Zähler auf Null. Späte Antworten und Korrekturen buchen weiter in die ursprünglichen Buckets. Reads sind nebenwirkungsfrei und benötigen keinen Resetcommit. `inventory` hat keine Monatsperiode; `never` ist kein Synonym für „jeden Monat neu“ und in diesem ersten Schnitt kein pauschaler unendlicher Ereigniszähler. + +Unknowns werden durch einen Periodenwechsel nicht vergessen. Konservativer Default: ein ungeklärter externer Call sperrt neue externe Reservations desselben kommerziellen Subjekts und derselben Purpose-/Metergruppe auch über Perioden hinweg, bis er geklärt ist. Endgültig bekannte Metriken ohne unbekannte harte Budgetkomponente lösen diese Sperre nicht aus. Beobachtend fehlende Token-/Kostenfelder sperren reine Callkontingente nicht, solange der Callversuch selbst geklärt ist. Ein Produkt kann statt dieser konservativen Sperre später eine nachgewiesen begrenzte offene Risikoobergrenze verwenden; bloßes TTLablaufen reicht nicht. + +Zeitzone, Periodenart, Metersemantik und Währung werden innerhalb eines laufenden Fensters nicht gewechselt. Eine notwendige spätere Umstellung benötigt ausdrücklich gebundene Übergangsfenster ohne kostenlose Doppelkontingente; im ersten Schnitt nur zum kompatiblen Folgebeginn. Ein Client kann keine Monats-ID mitsenden und so einen alten/unbelasteten Bucket auswählen. + +### 10.2 Plan-/Grantwechsel + +Upgrade, Downgrade und zeitlicher Grant ändern die effektive verfügbare Menge, **nicht** die Bucketidentität oder den bisherigen Verbrauch. Vor Dispatch wird die aktuelle Revision unter derselben Subjektsperre geprüft. Eine nach Dispatch geänderte Berechtigung ändert die historische Subjekt-/Ausnahme-/Preisbindung dieses bereits möglichen Verbrauchs nicht. Aufnahme und neue Nodes müssen den aktuellen Stand erneut bestehen. + +Für sicher unversendete Vorreservierungen prüft T2 bei Planänderung neu. Reicht der neue Plan nicht, keine Dispatchfreigabe; alte unversendete Holds werden konsistent freigegeben. Bereits mögliche externe Wirkung wird weiterhin gebucht, selbst wenn der neue Plan keinen weiteren Call mehr erlauben würde. Grantablauf kann auch ohne DBupdate eintreten; daher Zeitfenster und nächste Gültigkeitsgrenze bei jedem Aufnahme-/Dispatchentscheid frisch prüfen, nicht nur `entitlement_revision` vergleichen. + +### 10.3 Explizite Ausnahmen + +Shinkans Bypasscapabilities bleiben die geeignete Referenz. Im neuen Vertrag braucht eine Ausnahme eine bekannte Capability, ein Feature/Meter, ein zulässiges Subjekt, Zeitraum, Grantrevision und Audit. Kein pauschales `is_admin => unlimited`, kein `ENFORCE=0` für harte zugesagte Features. Vergabe/Änderung einer privilegierten Ausnahme nutzt aktuelle Betreiberrechte und MFA-Step-up des Auth-Blueprints. Default maximal 30 Tage, danach nur erneute ausdrücklich begründete Verwaltung, kein automatisches Verlängern. + +Die kommerzielle Ausnahme überspringt nur die bezeichnete endliche kommerzielle Menge. Feature-Kill-Switch, fehlende Funktionsfreigabe, AccessPolicy, Quell-/Privacygrenzen, Maschinenbefugnisse und technische Betriebsbudgets bleiben wirksam. Eine Freischaltung einer sonst deaktivierten Funktion ist ein eigener expliziter Grant. + +Exemptverbrauch wird vollständig mit derselben Call-/Operationidentität erfasst, als solcher getrennt ausgewiesen und im Default nicht vom normalen Vereinskontingent abgezogen; technische Gesamtkostenbudgets zählen ihn mit. Dazu gehören auch Exemptholds und Unknownmengen. Ein entfallener Grant nach Dispatch macht historische Vorgänge nicht rückwirkend normal oder kostenfrei. Der gewählte Admissionstatus bleibt im Ledger gebunden; neue Aktionen erhalten keine alte Ausnahme. + +## 11. Lokale Fachwrites und Bestandsgrenzen + +### 11.1 Periodischer lokaler Verbrauch + +Bei einer reinen DBfachaktion werden aktuelle Rechte, Featurefreigabe, atomare Kapazität, fachlicher Write, Verbrauchsevent und Audit in einer Transaktion verarbeitet. Eine separate Reservation über Netzwerkphasen ist dafür unnötig. `LocalUsagePort.consume` und Fachwrite dürfen niemals unabhängig committen. + +Illustration V/K für einen registrierten lokalen periodischen Zähler; Services und Repositories sind konkret im Zielprodukt zu verdrahten: + +```python +def create_training_unit(self, context, command): + with self.uow.transaction() as tx: + self.access.require(context, "training_units.create", None, tx) + self.entitlements.require(context, "training_units", tx) + existing = self.operations.find_existing(tx, context, command.operation_id) + if existing is not None: + result = self.units.read_authorized(tx, context, existing.result_id) + else: + self.usage.consume( + tx, context, operation_id=command.operation_id, + feature_id="training_units", quantity=1, + ) + row = self.units.create(tx, context, command) + self.operations.complete(tx, context, command.operation_id, row.id) + self.audit.changed(tx, context, "training_unit.created", row.id) + result = self.outputs.training_unit(row) + return result +``` + +`operations.find_existing` steht für den transaktionalen Idempotenzadapter: er bindet Subject/Scope und Input-HMAC, verhindert parallele Doppelaufnahme durch Uniqueconstraint/Sperre und liefert bei anderer Eingabe 409. Der dargestellte Kontrollfluss allein wäre ohne diese Semantik nicht konkurrenzsicher. Auch ein Wiederabruf prüft aktuelle Objektleserechte. Auditfehler, fachlicher Konflikt oder nicht erfolgreicher Commit rollen Verbrauch und Fachwrite zusammen zurück. + +Bei periodischem Ereignisverbrauch gibt das Löschen einer früher angelegten Einheit das historische Ereignis nicht automatisch zurück. Die jeweilige Zähleinheit muss dies klar sagen. Ein Bestandslimit verhält sich dagegen wie folgt. + +### 11.2 Inventar / Bestand + +Der Bestandsadapter zählt exakt die in der registrierten Definition festgelegten Objekte, z. B. aktive Mitgliedschaften oder nicht archivierte Übungen des Clubs. Alle bestandsändernden Pfade – Anlegen, Löschen, Archivieren, Wiederherstellen, Statuswechsel, Import und administrative Mutation – sperren dieselbe stabile Subjektzeile und prüfen Delta und tatsächlichen Bestand in derselben Fach-UoW. Der Subjektlock serialisiert diese Writer; ein nacktes `SELECT COUNT` ohne gemeinsamen Writervertrag genügt nicht. + +Für den ersten Schnitt ist der echte indizierte DBbestand unter Sperre maßgeblich; keine unqualifizierte Synchronisierung eines separaten In-Memory-Zählers. `delta>0` verlangt `Bestand + delta <= Limit`. Bestandssenkung bleibt bei bestehendem Zugriffsrecht auch nach Downgrade möglich. Doppelte/deaktivierte Datensätze, Wiederaktivierung und mehrere physische Tabellen derselben Fachmenge müssen im registrierten Selektor ausdrücklich definiert sein. Shinkans Livebestandsfilter sind dafür gezielte Ausgangspunkte, kein universeller `COUNT(*)` über alle Tabellen. + +Harte Bestandsgrenzen sind erst nachgewiesen, wenn **alle** Writer im Zielprodukt diesen Vertrag erfüllen. Direkte privilegierte DBwrites und unadaptierte Altrouten können ihn umgehen; bis deren tatsächliche Abdeckung geklärt ist, nur Softlimit zusagen. Dieser Blueprint behauptet diese Bestandsabdeckung nicht und nimmt keine Repoanpassung vor. + +### 11.3 Bulk/Import und technische Abgrenzung + +Ein Import bindet valide Eingaben und tatsächliche Duplikat-/Änderungsregeln; unter dem Subjektlock wird die wirkliche positive Menge bestimmt. Default: gesamter begrenzter Batch in einer UoW, keine Teilerfolge ohne expliziten Fachvertrag. Limitverletzung oder Auditfehler rollt alle neuen Zeilen und die Buchung zurück. Bereits vorhandene Duplikate verbrauchen bei einem Bestandslimit keinen zusätzlichen Platz; historische periodische Importereignisse sind eine andere registrierte Einheit. Keine Usageeinheit aus dem Dateinamen oder der Zahl ungeprüfter Uploadzeilen ableiten. + +Dateispeicher, Renderingjobs, Webhooks und andere externe Wirkungen sind kein reiner DBwrite. Sie benötigen ihren eigenen passenden Wirkungs-/Reservierungsadapter; der lokale `consume`-Port ist dafür allein ungeeignet. Dieser Blueprint erfindet keine neue Medien-/Importengine und keinen Zahlungswebhook. An bestehende Adapterschnittstellen später gezielt anschließen. + +## 12. API, Fehler und Frontend + +### 12.1 Lesender Entitlementsnapshot + +Default `GET /api/v1/me/entitlements` verwendet den verifizierten Scope aus Phase 3.3; kein frei umleitender Queryparameter für fremde Clubs. Er liefert aktuelle Capabilitydarstellung und registrierte Featureentscheidungen. Der kommerzielle Teil enthält `quota_subject` nur soweit sichtbar, `entitlement_revision`, UTC-`as_of`, Feature-/Meterrevisionen, Zähleinheit, Periodenbezug, `admission_mode='observe'|'soft'|'hard'` und sichere Reasoncodes. + +Bei sichtbarer endlicher Menge: expliziter Limitmodus und Wert, `used_known`, `held_total`, `held_unknown`, `remaining`, getrennte Exemptaggregate und `period_start/end`. Bei unbegrenzt: `limit.mode='unlimited'`, kein behauptetes unendliches Remaining. Bei nicht erlaubter Verbrauchssicht: `visibility='hidden'` und keine Beträge; dies bedeutet nicht unbegrenzt. Ein berechtigtes Mitglied kann trotzdem `feature.enabled` und eine sichere Aussage `available/exhausted/temporarily_blocked` für seine Aktion sehen. Einzelne fremde Verbräuche bleiben verborgen. + +Beispiel eines synthetischen sichtbaren Featureausschnitts; Menge/Plan ist keine Produktempfehlung: + +```json +{ + "feature_id": "analysis_generate", + "enabled": true, + "meter_id": "generate_attempt.v1", + "unit": "generate_attempt", + "admission_mode": "hard", + "visibility": "summary", + "limit": {"mode": "finite", "value": 10}, + "used_known": 3, + "held_total": 2, + "held_unknown": 0, + "remaining": 5, + "period_start": "2026-10-01T00:00:00Z", + "period_end": "2026-11-01T00:00:00Z", + "reason": "available" +} +``` + +`GET /api/v1/usage` liefert nur berechtigte eigene/ausdrücklich freigegebene aggregierte Einträge mit `{items,next_cursor}`. Ein Clubsummary erfordert die benannte Capability. Ein Defaultnutzer erhält keine ProviderrequestIDs, internen Evidencebelege, anderen Actor-IDs oder Kosten anderer Räume. Detailedger ist eine getrennte Betreiber-/Abrechnungsfunktion mit aktuellem Zugriffs-/MFAvertrag, kein allgemeiner Frontendzustand. + +Schreibende Fachrouten bleiben beim Produkt/Gateway. Es gibt kein öffentliches `POST reserve`, `settle`, `increment`, `refund` oder `reset_usage`. Lokale Plan-/Grant-/Ausnahmeverwaltung nutzt bestehende privilegierte Verwaltungsrouten oder einen schmalen späteren Adapter mit `expected_version`, vollständiger Subjektbindung und Audit. Neue Payment-/Checkoutendpoints werden nicht angelegt. + +### 12.2 Fehlervertrag + +RFC-9457-`application/problem+json` gemäß Foundation mit sicheren Codes und `request_id`; keine Rohprovider-, SQL-, Usage-Evidence- oder persönlichen Werte in Errors. + +| HTTP / Code | Bedeutung / Verhalten | +|---|---| +| 401 `session_required/session_expired` | Keine aktuelle Identität; keine Reservierung/Neuzulassung | +| 403 `capability_required/feature_not_enabled` | Eigene Aktion fachlich oder kommerziell nicht freigeschaltet | +| 404 `not_found` | Fremdes/unsichtbares Objekt, Quotasubjekt oder Consumptiondetail | +| 409 `quota_exhausted/inventory_limit` | Verbindliche Aktion passt nicht in vorhandene Kapazität; keine automatische Mutationwiederholung | +| 409 `context_changed/reservation_conflict/usage_conflict/version_conflict` | Bindung, Policy oder erwarteter Stand ist widersprüchlich | +| 409 `usage_unresolved/quota_recovery_required` | Mögliche externe Wirkung bzw. wiederhergestellter unvollständiger Stand blockiert neue harte Aufnahme | +| 422 `input_invalid/quota_quantity_invalid` | Ungültige fachliche Eingabe, negative/typfalsche Menge; keine großzügige Konvertierung | +| 429 `execution_capacity/rate_limited` | Technische Frequenz-/Parallelitätsgrenze, nicht das erworbene Monatskontingent | +| 503 `entitlement_policy_unavailable/budget_bound_unavailable/quota_integrity_failed` | Erforderliche technische Policy/Bound/Integrität fehlt; kein Fallback auf unbegrenzt | + +Ein erschöpftes Monatskontingent kann einen sicheren `period_end`-Hinweis enthalten; das Frontend startet deshalb keinen automatischen POSTretry. Provider429 bleibt der Gatewayfehler und wird nicht als sichere Quotenfreigabe interpretiert. Ein GET des eigenen Laufstatus kann weiterhin 200 mit `paused_unknown` oder anderer sicherer Statusinformation liefern; das bedeutet keine erfolgreiche Neuzulassung. + +### 12.3 Frontendanschluss + +Plan-/Featureentscheidungen kommen vom Snapshot, nicht aus hardcodierten Tarifnamen. Widgetanforderungen verwenden dieselbe explizite Featurezuordnung wie Backend und Registry; bei mehreren Anforderungen gilt AND. Neue Requirements und fehlgeschlagene Loads werden nicht als „keine Anforderungen“ behandelt. Ausblenden/Deaktivieren im UI ersetzt niemals die erneute serverseitige Prüfung der Fachaktion. + +Nach relevanter Mutation kann der Server einen sicheren aktuellen Usageausschnitt aus dem committed Zustand liefern. Der Client darf ihn lesen und später neu laden; er erhöht keine Zähler optimistisch als Wahrheit. Bestehender gemeinsamer APIclient, HttpOnly-/Secure-/SameSite-Cookies, CSRF/Origin, `no-store`, Scopeepoch und Abort gelten unverändert. Nach Scopewechsel alte Erfolgs-/Fehler-/401-/Usageantworten verwerfen. Keine Tokens oder persönlichen Consumptiondetails in LocalStorage/PWAcache. Ein Planupgradebutton ist in dieser Phase kein Auftrag für Checkout oder Zahlungsintegration. + +## 13. Betrieb, Restore und Datenschutz + +Aufbewahrung bezieht sich auf minimale technische Mengen, Actor-/Scope-/Call-/Reservationsbezüge und sichere Evidencecodes; keine Prompt-/Outputvolltexte, Gesundheitswerte, E-Mailadressen oder Credentialinhalte im Usageledger. Interne Kontoreferenzen sind geschützt, keine frei exportierbaren anonymen Statistiken. Finale technische Buchungsdaten bleiben standardmäßig für den laufenden und die zwölf vorherigen Kalendermonate verfügbar; das ist ein anpassbarer technischer Ausgangswert, keine gesetzliche Aufbewahrungsfrist. Private Fachdaten folgen weiterhin ihren eigenen Fristen. + +Offene/ungeklärte, referenzierte und für zugesicherte Idempotenz benötigte Bindungen werden nicht durch eine pauschale Retention gelöscht. Nach zulässiger Verdichtung bleiben erforderliche Outcome-/Deduptombstones und Aggregatkonsistenz erhalten. Cleanup gibt keine Holds frei, setzt keine unbekannten Werte auf Null und schafft keine neue freie Operation. HMAC-Key-ID und nötige alte Keyversionen folgen dem Gateway-/Recoveryvertrag. + +Backup/Restore umfasst Buckets, Reservations, Events, Callledger und fachliche Ergebnisreferenzen im selben Datenkonsistenzpunkt. Writerfreeze beinhaltet Gateway-T2/T3, Workflowrunner, lokale Fachwriter, Reconciliation, Plan-/Grantverwaltung und Cleanup. Bei Restore auf einen älteren Stand können bereits versendete, im Backup aber fehlende Calls existieren. Ein leerer wiederhergestellter Zähler ist deshalb kein Beweis freien Budgets. + +Default nach Restore: aktuelle Sessions/Claims gemäß Auth-/Recoveryvertrag invalidieren und alle betroffenen wiederhergestellten Quotasubjekte für neue harte Zulassungen `recovery_blocked` setzen. Das betrifft neben externen Calls auch historische periodische DBereignisse, soweit deren Ledger seit dem Backup unvollständig sein kann. Offene Dispatches/Reservierungen bleiben ungeklärt, alte Workflows starten nicht automatisch neu. Fehlende Buchungen seit Backup werden aus vertrauenswürdigen vorhandenen Belegen rekonstruiert oder konservativ als ungeklärte Risikoexposition behandelt; bloßes Neuansetzen des laufenden Monats reicht nicht. Reine Bestandsgrenzen können nach überprüfter Integrität am tatsächlich restaurierten Bestand wieder qualifiziert werden; sie beweisen keinen vollständigen historischen Ereignisverbrauch. Ohne ausreichenden Nachweis bleibt die betroffene harte Aufnahme geschlossen. Freischaltung ist eine gezielte protokollierte Recoveryoperation, kein neuer pauschaler Familienfreigabeprozess. + +Es wird kein zusätzlicher zentraler Dienst oder vermeintlich atomarer DB-/Provider-/Dateijournalmechanismus verlangt. Bestehendes geschütztes Operationsjournal und tatsächlich verfügbare Provider-/Operationsbelege können beim späteren Reconcile helfen; ihre Vollständigkeit wird nicht vorausgesetzt. Image-Rollback auf eine unveränderte aktuelle DB setzt keine Kontingente zurück; tatsächlicher Datenrestore braucht die obige Nachbehandlung. Reconciliation und Recovery sind selbst idempotent und mit erwarteter Ziel-/Zeilenversion geschützt. + +## 14. Technische Defaults und Anti-Patterns + +| Default | Wahl / Grenze | +|---|---| +| Erste KI-Hardquota | Call-/Generateversuchseinheit, ausdrücklich produktseitig benannt; Tokens/Kosten beobachtend | +| Perioden | UTC-Kalendermonat, bei tatsächlichem Bedarf UTC-Kalendertag; keine rollierende 30-Tage-Imitation | +| Mengen | Nichtnegative `BIGINT`-Untereinheiten, strikte Eingabegrenzen vor Arithmetic; Kosten Decimal, Skala 6, konservatives Aufrunden | +| Konkurrenz | Produktlokale PostgreSQLsperren, stabile Subjektzeile; kein prozesslokaler Lock als einzige Garantie | +| Vorhaltefrist | Falls wirklich `held_unsent` benötigt: 2 Minuten; Freigabe nur mit positivem Nichtversandnachweis; dispatched/unknown ohne TTLrefund | +| Unknownverhalten | Neue externe Aufnahme derselben Subjekt-/Purposegruppe blockiert, soweit ein harter Budgetbestandteil ungeklärt ist | +| Verwaltung | `expected_version`, begründete Änderungen, bestehendes MFA; Quoten-Ausnahme im Default höchstens 30 Tage | +| Lokaler Bulk | Maximal 1.000 fachlich validierte Zeilen pro atomarem Batch; engere Produkt-/DBgrenzen gelten | +| Readmodel | Persönlich/Scopegebunden, no-store; im ersten Schnitt keine erlaubnisgebende Entitlementcache-Schicht | +| Ledgerretention | Laufender plus 12 vorherige Monate für finale technische Buchungen; offene/referenzierte Bindungen gesondert erhalten | + +Vermeiden: + +- Plan/Tier als Rolle oder Objekterlaubnis verwenden; UIbadge als APIgate; fremdes `billing_subject_id` aus einem Request akzeptieren. +- Fehlender Featureeintrag, kaputter Integer, SQLfehler oder nicht konfigurierter Adapter ergibt `unlimited`; probe/off als zugesicherte harte Grenze ausgeben. +- `check → externer Call → increment` ohne Reservation; Parallelität mit einem Pythonlock oder einer ContextVar als gelöst betrachten. +- Monatlichen Zähler beim GET zurücksetzen; Planwechsel erzeugt neuen Bucket; spätes Ergebnis dem Antwortmonat zurechnen. +- Schätzung als Obergrenze, fehlende Usage als Null, Timeout/Cancel/429 als Kostenfreiheit oder TTL als Refundbeleg behandeln. +- Usage nur nach gültigem Fachoutput buchen; Callledger erfolgreich abschließen und Ergebnis-/Verbrauchscommit später getrennt schreiben. +- Pauschaler Adminbypass oder Ausnahme ohne Scope/Feature/Zeit; exempten Verbrauch unsichtbar machen oder technische Gesamtkostenbudgets umgehen. +- Bestand und historische Ereignisse vermischen; Duplikate oder Löschungen mit unpassender Zähleinheit buchen; unadaptierte Writer bei Hardquotazusage ignorieren. +- Alte Calls durch Retention/Restore vergessen, bekannte Call-ID erneut ausführen, unterschiedliche Endabrechnungen still überschreiben oder echte Überhänge wegclampen. + +## 15. Automatisierte Sicherheits-, Konkurrenz- und Negativtests + +Die Matrix ist ein **Testauftrag V/K**, kein Bericht bestandener Prüfungen. Synthetische Fixtures: zwei persönliche Subjekte, zwei Clubs mit mehreren Mitgliedern, ein Operator ohne private Objektleserechte, eine explizite begrenzte Ausnahme, zwei Planrevisionen, kontrollierte UTCzeit sowie mindestens zwei echte unabhängige DBconnections. Modell-/Providerzugriff ausschließlich als Fake mit Sendzähler und genau gesetzten Crashbarrieren. + +| ID | Prüfung | Erwartung | +|---|---|---| +| EUQ-01 | Unbekanntes Feature, Meter, doppelte Registry-ID oder nicht implementierter Adapter | Geschlossen; kein stilles Defaultrecht | +| EUQ-02 | Missing, `0`, `NULL` in vorhandener Limitzeile, negativer/defekter Wert | Disabled/finite/unlimited/unavailable eindeutig; kein unfreiwilliges Unlimited | +| EUQ-03 | Fehlendes/fremdes Profil, manipuliertes billing_subject oder Clubscope | Keine Fallbackidentität; kein fremdes oder billigeres Kontingent | +| EUQ-04 | Zweites Mitglied desselben Clubs führt denselben Featuretyp aus | Gemeinsamer Clubbucket, keine Quote pro Session/Trainer | +| EUQ-05 | Capability fehlt trotz freiem Kontingent; fremdes Objekt trotz Premium | AccessPolicy verweigert; kein kommerzielles Gate erweitert Objektzugriff | +| EUQ-06 | Zwei Features nötig, eines gesperrt; UIrequirementsload scheitert | AND verweigert; Ladefehler wird nicht zur leeren Anforderung | +| EUQ-07 | Operator ohne Ausnahme und ohne private Leserechte | Kein automatischer Bypass und kein Fremdledgerzugriff | +| EUQ-08 | Aktive/abgelaufene/fremde featurebezogene Ausnahme | Nur exakt gebundene zulässig; Ablauf bei Aufnahme erneut geprüft | +| EUQ-09 | Exemptcall mit technischem Produktbudget nahe Grenze | Kommerziell getrennt erfasst; technisches Gesamtbudget weiter bindend | +| EUQ-10 | Zwei unabhängige Reservierungen bei `L=1` gleichzeitig | Genau eine neue Aufnahme, ein Hold; zweiter Call null Sends | +| EUQ-11 | Gleiche Call-ID parallel und später erneut, gleiche/andere Envelopebindung | Eine Reservation; idempotenter Wiederabruf oder 409, kein Doppelhold | +| EUQ-12 | Erstmalige konkurrierende Subjekt-/Bucketanlage | Eine stabile Sperrzeile/ein Bucket; keine freie Parallelkapazität | +| EUQ-13 | Mehrere Metriken/Subjekte, zweite Grenze erschöpft | Vollständiger Rollback aller ersten Holds/Events | +| EUQ-14 | Audit-/Reservierungs-/Dispatchwrite oder Commit in T2 scheitert | Kein Send, keine gültige Permit; keine Teilbuchung | +| EUQ-15 | Crash unmittelbar nach T2commit, vor/bei/nach Sendbeginn | Persistenter Hold; konservativ unknown, keine automatische Generatewiederholung | +| EUQ-16 | Erfolgreiche Antwort und Crash nach T3commit vor Rückgabe | Ergebnis-/Node-/Call-/Usagecheckpoint gemeinsam; kein doppelter Verbrauch | +| EUQ-17 | Fach-/Node-/Auditwrite scheitert in T3 nach bekanntem Verbrauch | Kein Facherfolg; enger technischer Abschluss erfasst bekannte Usage/unknown | +| EUQ-18 | Rechteentzug, Sessionexpiry, Cancel oder Scopewechsel während Await | Keine verspätete Fachfreigabe; ursprünglicher Verbrauch bleibt korrekt zugeordnet | +| EUQ-19 | Ungültiger Output, Refusal, HTTP429/5xx, Timeout und Clientdisconnect | Kein Refund aus Fehlerstatus allein; bekannte Versuche und unsichere Metriken unterschieden | +| EUQ-20 | `release_unsent` nach bewiesenem Nichtversand vs. nach Dispatchintent ohne Beweis | Nur erster Fall gibt Hold frei; zweiter bleibt ungeklärt | +| EUQ-21 | Wiederholtes mark_unknown, settle und release; widersprüchlicher Endreport | No-op für Gleiches; sicherer Konflikt für Widerspruch | +| EUQ-22 | Report enthält bekannte Callzahl/Inputtokens, aber keine Kosten/Outputtokens | Teilsettlement; kein fehlendes Feld als Null; Resthold bleibt | +| EUQ-23 | Estimated gegenüber endgültig qualifiziertem reported-Wert | Estimate gibt Hardhold nicht frei; Endbeleg erlaubt korrekte Differenzfreigabe | +| EUQ-24 | Tatsächlicher Verbrauch über Bound | Vollständig gebucht, Incident und Neuaufnahmesperre; kein Clampen/Verlust | +| EUQ-25 | Harte Tokens/Kosten verlangt, notwendiger Bound None oder nur Schätzung | budget_bound_unavailable, Sendzähler null | +| EUQ-26 | Dezimalgrenzen, Float/NaN/Infinity, negative Menge, falsche Währung | Strikte Ablehnung bzw. sichere Unklarheit; korrektes konservatives Rundungsverhalten | +| EUQ-27 | Monatswechsel, Dezember/Januar, UTCgrenze, verspätete Antwort | Exakte halboffene Fenster; ursprünglicher Bucket für Antwort/Settlement | +| EUQ-28 | GET am Periodenende und wiederholte Snapshots | Nebenwirkungsfrei, kein Reset-/Commit-/Usageevent | +| EUQ-29 | Unknown aus Vormonat und Beginn neuen Monats | Historischer Hold bleibt; Default-Neuaufnahmesperre wirksam | +| EUQ-30 | Wechsel Plan/Override/Grant unmittelbar vor/nach Dispatch | Frische Zulassung; historische Bindung nach Dispatch bleibt; kein freies Neukontingent | +| EUQ-31 | Grantablauf ohne Update der Revision | Zeitprüfung erkennt Ablauf trotzdem | +| EUQ-32 | Überlappende Grants, kaputte Planzuordnung oder nicht erlaubte Periodenumstellung | Schreiben/Admission geschlossen; keine willkürliche Auswahl | +| EUQ-33 | Downgrade unter Bestand/used+held | Keine Datenlöschung; neue positive Menge blockiert, erlaubtes Lesen/Löschen möglich | +| EUQ-34 | Zwei lokale DBcreates für letzten Ereignis-/Bestandsplatz | Höchstens ein zusätzlicher Commit; Ledger und Fachdaten stimmen | +| EUQ-35 | Fehlgeschlagener lokaler Write, Duplicate/Idempotenzretry, Auditfehler | Kein Phantomverbrauch, keine doppelte fachliche Operation | +| EUQ-36 | Archivieren, Reaktivieren, Löschen und neuer Import desselben Bestands | Exakter registrierter Filter/Delta; alle Writer teilen den Lock | +| EUQ-37 | Bulk mit Duplikaten, Limit mitten im Batch oder ungültiger Zeile | Wirkliche Menge; Default vollständiger Rollback bei Verletzung | +| EUQ-38 | Periodischer Ereignisverbrauch und spätere Löschung | Kein unberechtigter Refund; Bestandssicht separat korrekt | +| EUQ-39 | Workflow mit drei Analysisnodes, einem Skip und einem Pure Node | Nur tatsächliche logische Modellversuche gezählt; kein zweites Endknotenbilling | +| EUQ-40 | Caller versucht UsageReport, not_sent oder Exemption frei einzusenden | Öffentliche DTOs verweigern; nur vertrauenswürdiger interner Adapter | +| EUQ-41 | Fremder Club-/Member-/Reservierungslookup und vertauschte FKs | Kein Fremdverbrauch/Leak; sichere 404/403; DB-/Servicebindung wirksam | +| EUQ-42 | Scopeepochwechsel mit altem Usageerfolg/Fehler/401 | Alte Antworten verworfen; kein falsches Quotenbadge/Logout | +| EUQ-43 | Verlorene HMAC-Keyversion, Bucket-/Eventdrift, kaputte Projektion | integrity_blocked; keine neue freie Operation oder automatische Kostenlöschung | +| EUQ-44 | Cleanup von finalem vs. offenem/referenziertem Ledger | Fristen korrekt, benötigte Tombstones/Holds bleiben; kein Replay | +| EUQ-45 | Restore eines Backups vor weiteren externen Calls | Recoveryblocked statt vollem frischem Budget; alte Sessions/Claims gesperrt | +| EUQ-46 | Doppelte Reconciliation, fremder/mehrdeutiger Beleg oder stale Version | Eindeutiger idempotenter Abschluss oder Verweigerung; keine Doppelgutschrift | +| EUQ-47 | Logs/Problem-/Status-/Entitlement-DTO mit privaten Canarywerten | Keine Prompt-/Output-/Credential-/Fremdmitgliedswerte; Sichtbarkeit korrekt | +| EUQ-48 | Import API/Runner ohne DB/Provider, Ausfall erforderlicher Policy | Keine Importnebenwirkung; geschlossene Runtimeentscheidung statt Unlimited | +| EUQ-49 | Parallel Planwechsel, reservieren, canceln, settle und reconcile | Einheitliche Lockordnung; keine Doppelbuchung, kein unkontrollierter Retry | +| EUQ-50 | Kompatibilitätsadapter für bestehendes `ai_calls` mit anderer Einheit | Explizite Version/Zuordnung; keine stille Umdeutung erfolgreicher Analyse in Sendeversuch | +| EUQ-51 | Sperrwartezeit über Monats-/Grantgrenze | Nach Lock gelesene aktuelle DBzeit entscheidet; kein Freigeben mit alter Transaktionsstartzeit | +| EUQ-52 | Resume nach bewiesenem failed_unsent/released_unsent gegenüber unknown | Explizite neue Admissionrevision derselben Call-/Reservation-ID nur im belegbar unversendeten Fall; keine Doppelholds/Replay | + +PostgreSQL-Parallelität, FKs, echte Commits/Rollbacks, Erstzeilenrennen, Perioden und Lockordnung werden gegen eine isolierte echte PostgreSQLinstanz mit Foundationtreiber getestet. SQLite oder ausschließlich Mocks reichen dafür nicht. Keine echten Providerkeys/-calls oder produktiven Datenbanken. Die Testauswahl muss die Fall-IDs tatsächlich sammeln; übersprungene Assertions oder bloße Dateiexistenz sind kein Nachweis einer Hardquota. + +Vorhandene Testquellen I: Shinkan [Entitlementsnapshot](C:/Dev/shinkan-jinkendo/backend/tests/test_entitlements.py:8), [Limit-/Resethelpers](C:/Dev/shinkan-jinkendo/backend/tests/test_club_features.py:7), [M5-Verbrauchsfassade](C:/Dev/shinkan-jinkendo/backend/tests/test_club_feature_m5.py:25), [Ausnahmen](C:/Dev/shinkan-jinkendo/backend/tests/test_club_feature_exemptions.py:38), [Planningmeter](C:/Dev/shinkan-jinkendo/backend/tests/test_planning_llm_usage.py:13); Mitai [Import-Enforcement](C:/Dev/mitai-jinkendo/backend/tests/test_activity_import_feature_enforcement.py:12), [Widgets](C:/Dev/mitai-jinkendo/backend/tests/test_dashboard_widget_entitlements.py:5), [mehrere Featureanforderungen](C:/Dev/mitai-jinkendo/backend/tests/test_widget_feature_requirements_db.py:4). Diese wurden hier nicht ausgeführt. Vor Übernahme Assertions prüfen: bestehende Tests für negative Limits oder deaktiviertes Enforcement bestätigen gerade nicht die neue Fail-Closed-Semantik. + +## 16. Implementierungsanweisung für Cursor + +1. **Einen Ziel-Fachfall benennen und vorhandene Adapter verwenden.** Kein Familienbilling auf Vorrat. Persönliche Quoten zuerst am eindeutigen Mitai-Account-/Profilbezug, Vereinsquoten am Shinkan-Clubvertrag ausrichten. Lokale produktbezogene Arbeitsregeln bei der tatsächlichen Umsetzung lesen. Keine Produktänderung durch diesen Dokumentauftrag. +2. **Messgröße und Zusage explizit registrieren.** Boolean, Ereignis oder Bestand trennen; lokale Meter-/Perioden-/Defaultpolicyversion festlegen. Bestehende `ai_calls`-Semantik prüfen, nicht umdeuten. Zunächst harte Callanzahl und beobachtende Token-/Kostendaten, sofern keine andere konkrete Zusage vorliegt. +3. **Foundation/Auth anschließen.** `EntitlementPolicy` bleibt zusätzlich zu aktueller AccessPolicy. Server bestimmt Subjekt und Scope. Strikte DTOs, sichere Fehler, no-store, vorhandenes MFA für privilegierte Verwaltung; kein allow-all/probe-Schalter als Hardquotaersatz. +4. **Registry und Policyauflösung adaptieren.** Mitai-/Shinkan-Feature-/Planmuster und Shinkans Capability-/Bypassgrenzen wiederverwenden. Defekte Limits, Überschneidungen und unbekannte Features schließen. Keine automatische Zahlungsintegration, globale Billingdatenbank oder Startup-DDL/Planmutation. +5. **Ledger und stabile Sperrzeile migrieren.** Nur benötigte Tabellen/FKs/Uniqueconstraints, gemeinsame Lockordnung, Zeitfenster, HMAC-/Keybindung, Idempotenz und Audit. Explizite isolierte SQLmigration gemäß Foundation; keine Anwendung gegen produktive Datenbanken. +6. **Zuerst echte Konkurrenz nachweisen.** Zwei DBconnections, letzter freier Platz, Erstzeilenrennen, gleiche/andere Callbindung, Mehrfachdimension, Rollback und Planwechsel. Ein Unit-Test von `remaining` genügt nicht. +7. **Gateway-T2/T3 verbinden.** Unveränderten `UsageBudgetPort` implementieren; Reservation und Dispatchintent zusammen; Ergebnis/Workflowcheckpoint/Usage/Callabschluss/Audit zusammen. Enger technischer Abschluss bei Widerruf oder fachlichem Fehler. Kein automatisch erzeugter Ersatzcall. +8. **Unknown, Perioden und lokale Fachwrites qualifizieren.** Keine TTLrefunds; Teilsettlement; Originalfenster; zeitlicher Grantablauf; Inventarwriter und Bulksemantik vollständig abdecken. Nicht belegte Token-/Kostenbounds halten eine geforderte Hardquota geschlossen. +9. **UI und Betrieb ergänzen.** Entitlementsnapshot mit klarer Einheit/Limitmodus/Sichtbarkeit, keine Tariflogik im UI; Scopeepochtests. Cleanup/Reconciliation/Restoreblockierung an bestehenden Recoveryvertrag anschließen, Writerdrain ergänzen. Kein Zählerreset durch Restore oder Imagewechsel. +10. **Nachweis abliefern und anhalten.** Ausgeführte EUQ-Fälle mit Code-/Buildstand, Umgebung, Ergebnis und verbleibenden K-Punkten dokumentieren. Pflicht-Gates und menschliche Produktionsfreigabe bleiben erhalten; R1 und R2 gemäß ADR-11 sind zulässig. Kein Live-Rollout, Zahlungsanbieter oder weiterer Blueprint ohne konkreten Auftrag. + +Abnahme eines implementierten ersten Fachfalls verlangt: **aktueller Principal/Scope + Objektzugriff → wirksame Featurepolicy → eindeutiges Kontingentsubjekt → atomare Zulassung → tatsächliche Wirkung → idempotente Buchung oder ausdrücklich unknown**, einschließlich Parallelität, Widerruf, Plan-/Periodenwechsel und Crash nach möglichem Versand. Ein Entitlementsnapshot oder ein nach Erfolg erhöhter Zähler allein erfüllt dies nicht. + +## 17. Prüfstand dieser Lieferung + +Es wurden die vorhandenen Phase-3.1-Register und gezielt die in Abschnitt 2 benannten Mechanismen gelesen. Keine umfassende Repository-Neuanalyse, keine erneute Governance-/Produktreifebewertung und keine zusätzlichen ADRs. Bestehende Anwendungen und bisherige Ergebnisdokumente wurden nicht geändert. Keine Implementierung, Provideranfrage, produktive Datenbank, Zugangsdaten, Migration, Zahlungsintegration oder umfassender Bestands-Testlauf. + +**T – mechanischer Dokumentcheck am 16.10.2026:** 41 lokale Dateiverweise einschließlich angegebener Zeilen geprüft; drei Pythonbeispiele erfolgreich als AST geparst und ein JSONbeispiel erfolgreich gelesen; 52 eindeutige und lückenlos nummerierte Testspezifikationen erfasst; 25 Quellhashes gegen den lokalen Stand geprüft. Alle 49 zur Kontrolle erfassten Bestandsdateien sind gegenüber der Aufnahme vor Erstellung unverändert. Das Ergebnisverzeichnis enthält ausschließlich dieses Markdowndokument. Keines der Beispiele wurde als Anwendung ausgeführt; die 52 Testfälle sind nicht implementiert oder ausgeführt. Die Quellhashes unten sind kein Nachweis einer produktionsreifen Lösung. + +### 17.1 Lokaler Quellstand + +SHA-256 der gezielt verwendeten vorhandenen Quellen; relative Pfade ab `C:/Dev`. Produktdokumente und Testdateien sind Referenzen I, keine bestätigten Laufresultate. + +| Quelle | SHA-256 | +|---|---| +| `mitai-jinkendo/backend/auth.py` | `25d666b3f69cac0d18fa7abc969f51b16b889d6b6ff41d6f054d0d39941e8c1b` | +| `mitai-jinkendo/backend/routers/subscription.py` | `ffdd96e1184efc2f69974db6c6df552a13f76346f10bd86a93260725019e1b0d` | +| `mitai-jinkendo/backend/routers/features.py` | `96db39825e27c54e1a649baefaf9e23f9f3d47504caa98d474a862074d383141` | +| `mitai-jinkendo/backend/feature_logger.py` | `9d609d90fedc0febbbccc2eba947aec89b8365d0aa8166c25ab594965a18af37` | +| `mitai-jinkendo/backend/dashboard_widget_entitlements.py` | `cadcfe5da58260f44d65c5dc47ec22a03f2bb2cdf9a68ec50071bebd6bc4f821` | +| `mitai-jinkendo/backend/widget_feature_requirements_db.py` | `1b8f2b04046e1efc6bea46e4dc0fdb7bc810668f557bf40a03711400d4e1ea52` | +| `mitai-jinkendo/.claude/docs/technical/FEATURE_ENFORCEMENT_MAPPING.md` | `71d24076a247b28e4950ac0eedb07ee20f0852bb7f6d956670bca2ce75a9dc0e` | +| `mitai-jinkendo/backend/tests/test_activity_import_feature_enforcement.py` | `fca5134d3cbae3dc63fcc8b07054781806876fa1c73a57b91e00713921ae6f91` | +| `mitai-jinkendo/backend/tests/test_dashboard_widget_entitlements.py` | `cd53efad484673fd320998a659f07c0c2e07c2436dcb3d4a3449ab956728d7bf` | +| `mitai-jinkendo/backend/tests/test_widget_feature_requirements_db.py` | `51f0e2af1535989e2ef5e678f69c42a4a5d7a74e482b760e4197646fef1a1587` | +| `shinkan-jinkendo/backend/entitlements.py` | `b92c71806ba8394fc8055e50893e1ea66c8f38163a120d90ac796768d1a963cc` | +| `shinkan-jinkendo/backend/rights_registry.py` | `49992f1993b2e0d0e3bc7e50d44862d423bd68907b5a5d7f2f019edb99385555` | +| `shinkan-jinkendo/backend/club_features.py` | `429c68551bd8b0515ce9a4e5a372927c5074cdeb41dabc968e8ab8a3152788c9` | +| `shinkan-jinkendo/backend/club_quota_bypass.py` | `74e7eec110b28032cd0d93fb2451a19424c238fe4f33d33429254a3ebbf8a1e4` | +| `shinkan-jinkendo/backend/planning_llm_usage.py` | `955f65799572b1fe9031d8df6cea1c16618a1b980735b0b4b43b1bbfd9cc73cd` | +| `shinkan-jinkendo/backend/club_feature_logger.py` | `fa08d9527625f04016832b42ebf98e377dd2571e471331df36cc85ee121e94d4` | +| `shinkan-jinkendo/backend/tests/test_entitlements.py` | `0cf0d986adf340c4191a6f8fd575cddb42884a48c89e4c91819f72af77cb2eed` | +| `shinkan-jinkendo/backend/tests/test_club_features.py` | `cf0db96c17b14efa9ebd01fd704f2734e6d7e9c2f6adc8b09f44e5ec2243c512` | +| `shinkan-jinkendo/backend/tests/test_club_feature_m5.py` | `f9c9a8608c7902391537ed06ca27ea226ed8b0a435176f55f565eb78cad9fda8` | +| `shinkan-jinkendo/backend/tests/test_club_feature_exemptions.py` | `25115cdee347bde330772f78d5e783bd6ab748ec55507e149558312f09cb5623` | +| `shinkan-jinkendo/backend/tests/test_planning_llm_usage.py` | `3f7da3a5d6eb5824d48e5e034c0f75fc2fd4e2592ff37e819911f70d8c67b1bb` | +| `shinkan-jinkendo/docs/jinkendo-family/FAMILY_ENTITLEMENT_MODEL.md` | `ca43f58181b971ab6f5d508d38a0c78980037f6f75ab61d7df8fa8a95b42d1bf` | +| `shinkan-jinkendo/docs/product-readiness/03-abo-entitlements-abrechnung.md` | `43142140594d2f53c49c750dbc784658124eb5f78b8ca41443fc1da38d37a44a` | +| `kairo-jinkendo/backend/feature_registry.py` | `9e37bc6bda763ea99c960aa183b9165a9b11a8be1f20f73095b408b1b7a99c47` | +| `kairo-jinkendo/backend/entitlements.py` | `76a5b3a972c752619579042a932d3d0c1b413ce6a18606d0bde2343b174846a1` | + + diff --git a/docs/reference/Jinkendo_Media_Files_Safe_Rendering_Blueprint.md b/docs/reference/Jinkendo_Media_Files_Safe_Rendering_Blueprint.md new file mode 100644 index 0000000..9bfb40f --- /dev/null +++ b/docs/reference/Jinkendo_Media_Files_Safe_Rendering_Blueprint.md @@ -0,0 +1,601 @@ +# Jinkendo – Medien, Dateien & sicheres Rendering Blueprint + +**v0.1 · 16.10.2026 · Ergänzungsblueprint · technisch konkreter Entwurf V/K** + +## 1. Ziel, Einordnung und Grenzen + +Dieser Blueprint konkretisiert den sicheren produktlokalen Umgang mit Uploads, gespeicherten Dateien, Medienverweisen, Downloads, Rich Text und erzeugten Dokumenten. Die zunächst priorisierten Spezialblueprints sind erstellt. Dieser Ergänzungsblueprint ist sinnvoll, weil Shinkan bereits Medienarchiv, Übungsmedien und Rich Text besitzt, Mitai persönliche Fotos und PDFberichte verwendet und Kanshō private Journalmedien einbindet. Er ist kein Anlass für eine neue Architekturkonsolidierung oder Produktreifebewertung. + +Grundlagen: + +- [Referenzarchitektur A v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md), [Application Foundation B v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md) und [Entscheidungen C v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md). +- [Auth, Session & Scope](C:/Dev/jinkendo-phase3-3-auth-session-scope-blueprint-2026-10-16/Jinkendo_Auth_Session_Scope_Blueprint.md), [Release, Betrieb & Recovery](C:/Dev/jinkendo-release-betrieb-recovery-blueprint-2026-10-16/Jinkendo_Release_Betrieb_Recovery_Blueprint.md), [KI-Gateway](C:/Dev/jinkendo-ki-gateway-provider-privacy-blueprint-2026-10-16/Jinkendo_AI_Gateway_Provider_Privacy_Blueprint.md), [Prompt-/Workflow-Laufzeit](C:/Dev/jinkendo-prompt-placeholder-workflow-blueprint-2026-10-16/Jinkendo_Prompt_Placeholder_Workflow_Blueprint.md), [Entitlements, Usage & Quotas](C:/Dev/jinkendo-entitlements-usage-quotas-blueprint-2026-10-16/Jinkendo_Entitlements_Usage_Quotas_Blueprint.md). +- Beschlossene ADR-01 bis ADR-14 im [Entscheidungsregister](C:/Dev/jinkendo-architecture-consolidation-phase2-v0.2-2026-10-15/05_Architecture_Decision_Register.md). ADR-15/16 werden hier nicht entschieden. Technische Herkunfts-/Versionsbindungen sind keine Festlegung familienweiter Quellhoheit oder aktueller fachlicher Gültigkeit. +- [Phase-3.1-Wissenselemente](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json), besonders KI-SHK-10/16/19, KI-MIT-06/19, KI-KAN-02/22; [Quellen](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/sources.json), [Testregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/tests.jsonl) und [Guardrails](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/guardrails_source_register.jsonl). + +| Nachweisgrad | Bedeutung | +|---|---| +| **V** | Vorgeschlagener technischer Standard für spätere Umsetzung | +| **I** | Gezielte statische Implementierungs-/Dokumentreferenz | +| **T** | Tatsächlich ausgeführte Prüfung mit ausdrücklich begrenztem Umfang | +| **K** | Noch nicht integrierte oder getestete Kombination | + +Neue Schnittstellen und Abläufe sind **V/K**. Vorhandener Code und Testdateien sind **I**, kein Nachweis bestandener Tests. Der abschließende Dokumentcheck ist ausschließlich T für Dateiintegrität, Verweise und Beispielsyntax. Foundation und Blueprint werden nicht als produktionsreife Referenzimplementierung ausgegeben. + +Es erfolgen keine Änderungen bestehender Anwendungen, keine Codeimplementierung, keine Datenbank-/Provideraufrufe, keine Paketinstallation, kein Deployment und keine umfassenden Bestands-Testläufe. Kein zentraler Dateidienst, neues S3system, CDN, Virenscanningdienst, universeller Dokumentkonverter oder KI-Bild-/Audioegress als Voraussetzung. Tsumugu ist keine Implementierungsquelle. Ein Produkt ohne Dateien braucht dieses Modul nicht. + +### 1.1 Verbindliche Verträge und technische Defaults + +| Verbindlicher Architekturvertrag | Begründet anpassbarer Default | +|---|---| +| Aktuelle Identität, Scope und Objekt-/Assetberechtigung; Fail-Closed | Capabilitynamen und konkrete Fachobjekttypen | +| Keine Session in Medien-URLs; Scopehinweise sind keine Autorität | Same-Origin-Fetch mit Blob-URLs; eng definierter nativer Videopfad bei Bedarf | +| Ungeprüfte Uploads niemals ausliefern; Typ-/Ressourcen-/Pfadgrenzen wirksam | Zuerst JPEG/PNG/WebP, konkrete Größen und Normalisierungsprofile | +| Keine behauptete Atomarität von DB und Dateisystem; dauerhafte Zustände und Recovery | Lokales versioniertes Dateiverzeichnis hinter einem Storageport | +| Rendern führt weder untrusted Code noch beliebige Datei-/Netzwerkzugriffe aus | Typisierter begrenzter Renderbaum, ReportLab für einen benötigten PDFadapter | +| Referenzen, Retention, Sperren und tatsächliches Löschen konsistent | Shinkan-nahe Lifecyclezustände und konfigurierbare Fristen | +| Harte Kapazitätsgrenzen atomar; keine Freigabe nur aufgrund logischer Löschung | Produktlokale Kapazitätsreservierung; keine neue Plattform | +| Verbindliche Release-Gates, Buildzuordnung und menschliche Produktionsfreigabe | R1 bevorzugt, kontrollierte getrennte Builds R2 weiter zulässig | + +Ein anderer Dateityp oder Grenzwert benötigt einen geeigneten lokalen Adapter und dessen Negativtests. Eine zusätzliche Dateiendung allein ist keine sichere Erweiterung. Anpassungen verlangen keinen zusätzlichen familienweiten ADR oder Freigabezyklus. + +## 2. Referenzen und gezielte Anpassungen + +| Quelle I | Wiederverwenden | Grenze / Ergänzung V/K | +|---|---|---| +| Shinkan [Medienarchivnorm](C:/Dev/shinkan-jinkendo/.claude/docs/technical/MEDIA_ASSETS_AND_ARCHIVE_SPEC.md:1), [Uploadspec](C:/Dev/shinkan-jinkendo/.claude/docs/technical/MEDIA_UPLOAD_SPEC.md:1), [Assetrouter](C:/Dev/shinkan-jinkendo/backend/routers/media_assets.py:64) | Asset von Fachverknüpfung trennen; Wiederverwendung, Lifecycle und Speicheradapter | Produktnormen bleiben in Shinkan maßgeblich. Neue Familienadapter übernehmen keine automatischen globalen Privatdatenrechte und keine implizite Sichtbarkeitspromotion. | +| Shinkan [Pfadgrenze](C:/Dev/shinkan-jinkendo/backend/media_storage.py:125), [Downloadpfad](C:/Dev/shinkan-jinkendo/backend/routers/exercises.py:3214) | Registrierte Speicherwurzel, Asset-/Übungsbezug, GET/HEAD/Range | Keine Fallbackwurzel nach Konfigurationsfehler, kein späterer Dateiaufruf über beliebigen DBpfad. Geöffnete Datei und geprüfte Version binden; Asset- und Elternrechte als Schnittmenge prüfen. | +| Shinkan [Range-/Headerhelfer](C:/Dev/shinkan-jinkendo/backend/routers/exercises.py:3065) | Dateinamenbereinigung, Inline/Attachment, Single-Range | Unterstützte und ignorierte Rangefälle explizit festlegen; kein versehentliches erstes Segment einer Mehrfachrange. Gleiches Authverhalten für HEAD, 206 und Fehler. | +| Shinkan [Mediengrant](C:/Dev/shinkan-jinkendo/backend/media_grant.py:22), KI-SHK-10 | Kurzlebiger gesonderter Medienzugang statt voller Session in einer URL | Vorhandener Grant bindet Profil/Ablauf, nicht eine konkrete Assetrevision. DBpasswort-/Devsecretfallback und profilweiter Sessionalias werden nicht übernommen. Default braucht keinen URLtoken. | +| Shinkan [serverseitiger Richtext](C:/Dev/shinkan-jinkendo/backend/exercise_rich_text.py:31), [Browser-Sanitizer](C:/Dev/shinkan-jinkendo/frontend/src/utils/exerciseRichTextSanitize.js:68), KI-SHK-16 | Feste Tags/Attribute, geprüfte Medien-ID, Größe und Caption; server-/clientseitige Schutzschicht | Sanitizing ist keine Objektberechtigung. HTML-/Markdownparser und Renderadapter müssen dieselbe begrenzte Semantik erhalten; kein Regex als alleiniger XSSbeweis. | +| Shinkan [Lifecycle](C:/Dev/shinkan-jinkendo/backend/media_lifecycle.py:28), [Purge](C:/Dev/shinkan-jinkendo/backend/media_lifecycle.py:184), [Hold](C:/Dev/shinkan-jinkendo/backend/media_legal_hold.py:43), [Retentionjob](C:/Dev/shinkan-jinkendo/backend/scripts/media_retention_job.py:26), KI-SHK-19 | Verfügbarkeit, Löschschutz, Managementrechte und zeitgesteuerte Übergänge getrennt | Eigene Commits/Dateilöschung innerhalb eines Helfers nicht kopieren. Dauerhaften Purgeintent, tatsächlichen Löschreceipt und Racevertrag ergänzen. Ein geloggter Unlinkfehler ist kein erfolgreicher Purge. | +| Mitai [persönlicher Fotoabruf](C:/Dev/mitai-jinkendo/backend/routers/photos.py:132), [Pfadauflösung](C:/Dev/mitai-jinkendo/backend/routers/photos.py:30), KI-MIT-06 | Foto nur für zugehöriges Profil ausliefern | Sichere Einzelroute schützt nicht automatisch Liste/Upload/Löschen. Header-/Erstprofilfallback, absolute Altpfade und ungeprüfte Dateiendungen nicht als neuen Standard übernehmen. | +| Mitai [PDFbericht](C:/Dev/mitai-jinkendo/backend/report_pdf_render.py:64), KI-MIT-19 | Typisierte Berichtsblöcke, ReportLab und explizites Textescaping als lokale Renderreferenz | Kein freier HTML-/URLrenderer. Daten einmal autorisiert materialisieren; keine neuen DBconnections während des Renderns. Alle Text-/Fehlerpfade escapen, auch Teilpfade ohne bisheriges `escape`. | +| Kanshō [Medienstore](C:/Dev/Kansho/backend/media_store.py:146), [Metadatenbehandlung](C:/Dev/Kansho/backend/media_store.py:87), KI-KAN-22 | Private Journal-/Profileigentümerschaft, Größenlimits, lokale Medien und Metadatenminimierung | Signaturerkennung mit Declared-Type-Fallback ist keine vollständige Validierung. Gelesener Store entfernt nicht sämtliche möglichen Metadaten/Video-GPS; neuer Normalisierer muss sein Profil ausdrücklich nachweisen. | +| Kanshō [Medientokens](C:/Dev/Kansho/frontend/src/journal/document.js:8), [Editor-Mediennode](C:/Dev/Kansho/frontend/src/journal/KanshoMedia.jsx:54), KI-KAN-02 | Medien-ID statt Dateipfad im Dokument; Wortlaut, Caption und Platzierung erhalten | IDsyntax ist keine Lesefreigabe. Fremde oder nicht zugeordnete Medien nicht nachladen; kein externer Bild-URLfallback. | + +Kanshōs [Agentenleitfaden](C:/Dev/Kansho/AGENTS.md), [Kontextindex](C:/Dev/Kansho/docs/architecture/functional/documentation_index.md:1) und [Guardrails](C:/Dev/Kansho/docs/architecture/functional/guardrails.md:1) bleiben Bezug für private Inhalte. Bilder können erkennbare Personen oder Orte enthalten; Metadatenentfernung macht sie nicht anonym. Externe KI erhält keine Datei oder beliebige Medien-URL über diesen Blueprint. Der bestehende Gatewaystandard unterstützt hier keinen automatischen Bild-/Audioegress. + +Kairo wird mangels benötigter spezieller Dateireferenz nicht als führender Upload-/Renderingmechanismus herangezogen. Die Auswahl betrifft einzelne vorhandene Bausteine, keine Rangfolge der Produkte. Keine Cross-Repo-Runtimeimports; ein gemeinsames Paket erst bei zwei tatsächlichen Konsumenten und stabilem Vertrag. + +## 3. Komponenten und Verantwortlichkeiten + +```text +Fachrouter / Dokumenteditor + -> MediaService + aktuelle AccessPolicy + EntitlementPolicy + -> UploadIntent / Kapazitätsreservierung (kurze UoW) + -> QuarantineWriter -> TypeInspector / Normalizer (außerhalb UoW) + -> StoragePort.publish_once -> Receipt (außerhalb UoW) + -> Asset + Fachlink + Usage/Audit gemeinsam finalisieren + +Autorisierter Dokumentinhalt -> begrenzter RenderDocument-Baum + -> React-/Richtextanzeige mit berechtigten Medienrefs + -> optional lokaler PDFadapter -> geprüftes erzeugtes Asset + +Autorisierter Dateilesepfad -> ReadPlan / geöffnetes Handle / erneute Freigabe + -> begrenzter Stream; keine DBtransaktion über die Auslieferung + +Retention / explizites Löschen -> Purgeintent -> tatsächliches Löschen + -> bestätigter Abschluss / Reconciliation / Recovery +``` + +| Komponente | Zuständigkeit | +|---|---| +| `MediaService` | Uploadaufnahme, Link-/Lifecycleoperationen, Readplan und klare UoWgrenzen | +| `MediaPolicy` | AccessPolicy für Parent und Asset, Verfügbarkeit/Scope, gültige Attachmentbezüge; keine Tarif-/Rollenlogik im Storage | +| `MediaTypeRegistry` | Unterstützte MIME-/Codec-/Normalisierungsprofile mit konkreter Revision, Größen-/Ressourcenlimits | +| `QuarantineWriter` | Begrenzt Bytes empfangen, Hash/Receipt bilden, ausschließlich interne temporäre Keys verwenden | +| `MediaNormalizer` | Typ prüfen, begrenzt dekodieren/normalisieren, gereinigte Ausgabe und technische Prüfergebnisse erstellen | +| `StoragePort` | Opaque Keys in registrierter Generation; immutable Publish, gebundenes Öffnen, nachvollziehbares Löschen | +| `MediaCapacityPort` | Tatsächlich benötigte physische Kapazität inklusive temporärer und Trashbytes reservieren/finalisieren | +| `DocumentAdapter` / `DocumentRenderer` | Begrenzte Text-/Mediensemantik aus bestehendem Format herstellen, sichere Anzeige/PDFausgabe | +| `MediaReconciler` | Unvollständige Upload-/Purgeoperationen anhand persistierter Zustände und echter Storagebelege klären | + +Default: `app/modules/media/{models,types,policy,service,repository,storage,upload,normalize,lifecycle,api}.py` und `app/modules/documents/{models,adapters,render,pdf}.py`. Renderer nur anlegen, wenn das Produkt ihn benötigt. `bootstrap` verdrahtet Adapter; Lifespan verwaltet Ressourcen. API-/Modulimporte erstellen keine Verzeichnisse, Logdateien, DBschemas oder Netzverbindungen. + +## 4. Datenmodell und Python-Verträge + +### 4.1 Logische Datenstrukturen + +| Struktur | Wesentliche Felder / Bindungen | +|---|---| +| `media_assets` | UUID, Owner/Scope, Fachsichtbarkeit nach Produktvertrag, immutable Dateirevision, Rowversion, geprüfter MIME, Größe, interner Bytehash, Typ-/Normalisierungsrevision, Storagebezug, Verfügbarkeits-/Lifecyclezustand, Hold-/Rightsstatus | +| `media_attachments` | Parenttyp/-ID/-Version, Asset-ID, erlaubter Kontext, Caption/Sortierung; scoped FKs bzw. gleichwertige Service-/Constraintbindung | +| `media_variants` | Optional geprüfte Thumbnail-/Vorschaurevision; eigene Größe/Hash/Storageobjekt und dieselben Schutz-/Purgegrenzen | +| `media_operations` | Upload-/Render-/Purge-ID, Subject/Scope/Parentbindung, Input-HMAC/Key-ID, erwartete Version, Zustandsrevision, Attempt/Fence, Storagegeneration/-key, Prüfreceipts, Capacityref, sichere Fehlercodes/Zeiten | +| `media_read_leases` | Kurzlebige Asset-/Dateirevision, Session-ID/-Generation, Scope/Parentbezug, Ablauf/Status; keine Cookiewerte | +| bestehendes Audit / Usage | Fachliche Lifecycle-/Link-/Verwaltungsereignisse und genau einmalige Verbrauchsbuchung; keine privaten Dateiinhalte | + +`StorageRef` ist immutable und enthält Backend-ID, Generation und zufälligen Objektkey. Konfigurationsänderungen biegen alte Keys nicht auf eine neue Wurzel um. Dateiinhalte werden nie unter derselben Dateirevision überschrieben; Ersatz ist eine neue Revision mit neuem Key und geprüftem Pointerwechsel. Metadatenänderung besitzt eine gesonderte Rowversion. Ein starker Downloadvalidator kann eine opake zufällige Dateirevision sein; kein öffentliches SHA-Orakel persönlicher Dateien. + +Dateiname ist bereinigte Anzeigemetadaten, weder Pfad noch MIMEautorität. Scope-/Parent-/Assetzuordnungen sind serverseitig gesetzt und bei jeder Mutation aktuell geprüft. Es gibt keine frei beschreibbaren Felder `storage_key`, `owner_id`, `is_clean`, `privacy_checked`, `absolute_path` oder `public_url` im Upload-DTO. Ein zulässiger Datums-/Captionwert bleibt fachliche Benutzereingabe, keine technische Berechtigung. + +```python +from dataclasses import dataclass +from typing import BinaryIO, Literal, Protocol +from app.core.context import RequestContext, Tx + +@dataclass(frozen=True, slots=True) +class StorageRef: + backend_id: str + generation: str + object_key: str + +@dataclass(frozen=True, slots=True) +class VerifiedFile: + operation_id: str + attempt: int + profile_revision: str + mime_type: str + byte_size: int + sha256: str + staging_ref: StorageRef + +@dataclass(frozen=True, slots=True) +class PublishReceipt: + operation_id: str + file_ref: StorageRef + byte_size: int + sha256: str + durability_profile: str + +class StoragePort(Protocol): + def publish_once(self, source: VerifiedFile, + target: StorageRef) -> PublishReceipt: ... + def open_verified(self, receipt: PublishReceipt) -> BinaryIO: ... + def delete_verified(self, file_ref: StorageRef, + operation_id: str) -> Literal["deleted", "already_absent"]: ... + +class MediaCapacityPort(Protocol): + def reserve_upper(self, tx: Tx, context: RequestContext, + operation_id: str, maximum_stored_bytes: int) -> str: ... + def finalize(self, tx: Tx, capacity_id: str, + retained_bytes: int) -> None: ... + def release_deleted(self, tx: Tx, capacity_id: str, + delete_operation_id: str) -> None: ... +``` + +Die Dataclasses sind interne Ergebnisse vertrauenswürdiger Adapter, keine clientdeserialisierten Beweise. `open_verified` prüft die zugehörige registrierte Generation, Größe/Integrität und die Unveränderlichkeit des tatsächlich geöffneten regulären Objekts; der Aufrufer erhält kein später neu aufzulösendes Dateinamensversprechen. Alle Handles werden bei Erfolg, Fehler und Disconnect geschlossen. Kein Storageadapter prüft selbstständig Nutzerrollen oder committtet die Fach-DB. + +Der Kapazitätsport ist ein **lokaler Medienadapter** zu den Atomaritätsregeln des Quotenblueprints, kein Missbrauch von `UsageBudgetPort` mit fingierten KI-Call-IDs. Aktuelle physische Speicherbelegung, periodische Uploadereignisse und Attachment-/Assetbestand sind getrennte Metriken. Port und tatsächlicher Storage müssen bei Hardquotazusage gemeinsam qualifiziert werden; sie sind hier noch K. + +Die Kapazitätsprojektion bindet einzelne interne Storageobjekte und ihre nachgewiesenen Größen. `finalize` hält bei U3 auch Roh-/Stagingdateien belegt, die noch tatsächlich existieren. Späteres `release_deleted` reduziert nur die durch die benannte abgeschlossene Deleteoperation nachgewiesenen Objekte, idempotent und ohne verbleibende Asset-/Variantenbytes freizugeben. Kein frei übergebener Kundenwert `removed_bytes` und kein pauschales Freigeben der ganzen Uploadreservation nach dem Löschen nur des Originals. Dasselbe gilt bei Bereinigung einer fehlgeschlagenen Aufnahme. + +## 5. Uploadannahme vor Parser und Verarbeitung + +### 5.1 Enger HTTPvertrag + +Default ist ein zweistufiger Upload: JSONaufnahme erzeugt eine Uploadoperation; danach wird **genau eine rohe Datei** per `PUT /media/uploads/{id}/content` als begrenzter Bytestrom empfangen. Das vermeidet einen verpflichtenden Multipartparser vor der Autorisierung. JSONaufnahme besitzt strikte Metadaten und bekannten Parent, aber kein freies Owner-/Scopefeld. Cookie, CSRF, Origin und Scopeheader gelten auch für den Content-PUT. + +Bereits ein vorgelagerter ASGI-/Proxyadapter prüft Route, aktuelle grundlegende Session-/Browsergrenze, maximale Requestgröße und erforderliche Header, bevor der Uploadbody verarbeitet/auf Platte gespult wird. `Content-Length` ist ein früher Plausibilitätscheck, keine Vertrauensquelle; tatsächliche gelesene Bytes werden zusätzlich gezählt. Chunked oder HTTP/2-Daten umgehen das Limit nicht. `Content-Encoding` ist im ersten Schnitt nur `identity`; automatische Dekompression ist ausgeschlossen. Endlossendungen, langsame Bodies und Disconnects erhalten harte Gesamt-/Idlebudgets. + +Eine vorhandene Multipartproduktroute kann bleiben, wenn sie dieselben vorgeschalteten Grenzen, begrenzte Teilezahl/-größen, sicheren Spool und frühe Auth-/CSRFprüfung nachweist. `UploadFile` allein belegt das nicht. Kein Parser-/Frameworkupdate ist in diesem Dokument beauftragt. + +### 5.2 Uploadaufnahme U0 + +Kurze Foundation-UoW: aktuellen Principal/Scope, Parenteditrecht, `media.upload`, Funktionsfreigabe und zulässigen Typkandidaten prüfen; Operation-ID/Idempotenz/HMAC samt erwarteter Parentversion binden; atomar technische Spoolkapazität und gegebenenfalls harte kommerzielle Kapazität reservieren; Audit schreiben. Erst nach Commit Aufnahme bestätigen. Parallelität und maximale offene Operationen werden unter dem gemeinsamen Subjektlock begrenzt. + +Eine abgegebene Session oder später entzogene Mitgliedschaft erlaubt keinen Abschluss. Es werden keine Cookiewerte in einer Uploadoperation gespeichert. Session-ID/-Generation und Owner-/Scopebindung folgen dem Authvertrag; nach Ablauf bleibt die Operation unzugänglich bis zu einem ausdrücklich erlaubten Rebind des gleichen Subjects im gleichen Scope. Ein Rebind darf weder Parent noch Byteeingabe verändern und ist im ersten Schnitt nur vor endgültiger Aktivierung zulässig. + +Für Metadatenaufnahme gilt Idempotenz je Subject/Scope/Operationkey. Derselbe Key mit anderer Eingabe liefert 409. Wiederholtes Senden einer noch unklar laufenden Contentübertragung überschreibt keine Dateien: ein aktueller CAS/Fence beansprucht genau einen Attempt; gleichzeitiger zweiter Upload liefert `upload_in_progress`. Abgebrochene unbestätigte Attempts werden zuerst anhand ihres Receipts/temporären Keys geklärt oder verworfen, erst danach darf ein neuer begrenzter Attempt starten. + +## 6. Quarantäne, Typprüfung und Metadaten + +U1 läuft **ohne offene DBtransaktion**. Der Quarantänewriter schreibt nur in ein internes zufälliges Attemptverzeichnis, nie unter Originaldateiname oder beliebigen Clientpfad. Quarantäne und vorbereitete Objekte sind für alle normalen Downloadrouten unsichtbar. Rohdaten werden nach vollständigem Empfang gehasht; Content-Typ, Bytes und technische Grenzen werden vor Aktivierung geprüft. + +### 6.1 Registrierte Profile + +| Profil | Pragmatische Ausführung / erster Stand | +|---|---| +| `raster_image.v1` | JPEG, PNG, WebP; Signatur und begrenztes vollständiges Dekodieren, Dimensionen/Framezahl prüfen; Orientierung lokal anwenden; frisches Bild mit festem Farbprofil ohne fremde Metadaten neu encodieren | +| `video_local.v1` | Bei tatsächlichem Produktbedarf MP4 mit explizit qualifiziertem Container-/Codecprofil; begrenztes lokales Prüfen und erforderliches Remux/Transcode ohne Netz, Entfernung unzulässiger Metadaten und Zusatzstreams nach Profil | +| `pdf_attachment.v1` | Nur bei qualifiziertem begrenztem Parser/Prüfprofil; keine Inlineausführung im Apporigin, keine Vorschau ohne eigenen sicheren Renderadapter | +| `generated_pdf.v1` | Ausgabe eines registrierten lokalen Renderadapters; dessen Output ebenfalls auf Größe/Format prüfen und durch denselben Publish-/Lesepfad führen | + +Der erste Foundation-Fachschnitt implementiert `raster_image.v1`. Video/PDF sind wegen konkreter Shinkanverwendung spezifizierte Erweiterungsgrenzen, bleiben aber geschlossen, bis ihre tatsächlich benötigten lokalen Validatoren verfügbar und getestet sind. Ein bereits vorhandenes Produkt wird dadurch nicht nachträglich umkonfiguriert. GIF-/APNG-/animierte WebPdateien, SVG, HTML, XML, Office-/ZIParchive, Audio und beliebige Binärformate sind im neuen ersten Profil nicht zugelassen. Eine Animation wird nicht stillschweigend auf ein Bild reduziert. + +Deklarierte MIME/Endung und tatsächlicher Typ müssen zum registrierten Profil passen; bekannte harmlose Aliasformen werden explizit kanonisiert. Bei widersprüchlicher oder unklarer Erkennung verweigern, kein `declared in allowlist` als Ersatz. Magic Bytes allein reichen nicht. Nach Bildprüfung nur die neu encodierte Darstellung speichern/ausliefern; angehängte uninterpretierte Bytes nicht mitkopieren. + +Pillow dokumentiert einen Schutz über die Pixelzahl und eine `DecompressionBombWarning`; der qualifizierte Adapter behandelt Überschreitungen als Fehler und verwendet zusätzlich eigene harte Dekodier-/Ressourcenlimits. Den Schutz nicht deaktivieren. [Pillow Image-Dokumentation](https://pillow.readthedocs.io/en/stable/reference/Image.html) + +### 6.2 Isolierte lokale Verarbeitung + +Decoder und nötige Renderer laufen als begrenzter lokaler Kindprozess aus demselben qualifizierten Backendimage: feste Argumentliste, `shell=False`, keine frei übergebenen Tools/Filter/Skripte, keine Netzwerkfähigkeit, keine DB-/Providercredentials, keine Docker-/Hoststeuerung. Nur der eigene Input-/Outputspool ist zugänglich; Rootdateisystem und feste Fonts sind read-only. Prozess-/Speicher-/CPU-/Dateigrößenlimits und harte Abbruchfrist werden tatsächlich auf Betriebssystemebene bzw. durch den überwachten Prozessadapter erzwungen. Ein Pythonthread-Timeout allein stoppt einen hängenden nativen Decoder nicht. + +Ein späterer FFmpeg-/PDFadapter erhält nur geöffnete lokale Eingaben und feste erlaubte Parameter; keine M3U-/HLS-/Netz-/`file://`-Protokollauflösung oder externe Ressourcen. Fehlen wirksame Sandbox-/Ressourcenadapter, wird das betreffende Profil nicht geöffnet. Dafür ist kein neuer zentraler Scan-/Renderingdienst erforderlich. Antivirus kann ein zusätzliches vorhandenes Profil sein; weder dessen Fehlen noch eine Signaturprüfung wird als Beweis vollständiger Malwarefreiheit dargestellt. + +### 6.3 Metadaten und fachlicher Wortlaut + +Normalisierte Bilder übernehmen keine EXIF-/XMP-/Kommentar-/Textchunks oder beliebigen eingebetteten Profile. Farbumwandlung und Orientierung werden vor dem Entfernen kontrolliert angewendet. Die konkreten Ausgabebytes werden erneut auf den vereinbarten Metadatenumfang geprüft. Originale werden im Default nach erfolgreicher Aktivierung nicht als dauerhafter paralleler Download behalten. + +Ein fachlich benötigtes Aufnahmedatum, etwa in Mitai, kann der lokale Adapter vor Normalisierung als begrenzten **unbestätigten Kandidaten mit Herkunft** auslesen und nach dem Produktvertrag übernehmen. Keine GPS-/Geräte-/Seriennummern speichern, wenn sie nicht ausdrücklich erforderlich sind; kein erratenes Zeitzonen-/Wahrheitsversprechen. Nicht Metadaten still entfernen und gleichzeitig behaupten, alle fachlichen Informationen des Originals seien unverändert erhalten. + +Die Bildinhalte selbst können persönliche Informationen tragen. Keine Gesichtserkennung, automatische Persönlichkeitsableitung, OCR oder Übertragung an externe Modelle als Teil des Uploads. Kanshōs Privacy Gateway wird nicht durch einen Dateilink umgangen. Originalwortlaut und Captions von Nutzer-/Journaltexten werden durch Sicherheitsvalidierung nicht inhaltlich umformuliert. + +## 7. Storagevertrag und Veröffentlichung ohne falsche Atomarität + +### 7.1 Registrierte Wurzel und immutable Objekte + +Der erste Storageadapter nutzt das bestehende lokale/NAS-Dateiverzeichnis hinter `StoragePort`. Jede Generation besitzt eine explizite Basiswurzel, einen geprüften Identitätsmarker und das erwartete Mount-/Durabilityprofil. Fehlender Mount darf nicht unbemerkt in ein gleichnamiges lokales Verzeichnis schreiben. Keine automatische Fallbackwurzel bei Konfigurationsfehlern; Startup/Readiness bleibt geschlossen. + +Keys sind zufällige opaque interne Bezeichner mit einer strikten Segmentgrammatik. Absolute Pfade, `..`, Backslashes als alternative Traversal, Windows-Laufwerke/UNC/Alternate Data Streams, NUL-/Steuerzeichen, URLschemas und überlange Segmente sind unzulässig. Auch DBwerte sind Eingabe an diese Grenze. Elternverzeichnisse dürfen keine durch Benutzer veränderbaren Symlinks/Reparsepunkte enthalten. Der Adapter öffnet/veröffentlicht relativ zur registrierten Wurzel mit einem qualifizierten Schutz gegen Linkwechsel und prüft reguläre Dateien. `resolve()` plus späteres ungebundenes `open(path)` ist kein vollständiger Schutz gegen Austauschrennen. + +Physische Dateinamen enthalten im Default weder Profilnamen, Vereinsnamen noch einen öffentlichen Inhaltshash. Sichtbarkeitsänderung benennt die Bytes nicht um. Speicherbackend/-generation wird am Asset gebunden; ein aktiver Konfigurationspointer gilt für neue Objekte, nicht als stiller Umzug vorhandener Daten. Ein späterer Umzug besitzt eigenes Receipt und erwartete Generation, keine HTTPaktion „MEDIA_ROOT umstellen und alte Keys neu interpretieren“. + +### 7.2 U2, Dateieffekt und U3 + +| Phase | Dauerhafter Nachweis | Fehler-/Recoveryverhalten | +|---|---|---| +| U0 `accepted` | Autorisierte Uploadoperation + reservierte Kapazität committed | Ohne Commit kein gültiger Contentauftrag | +| U1 `receiving/verified` | Aktueller Attempt/Fence, begrenzter Quarantänekey, vollständiger Prüfreceipt | Teilfile bleibt unsichtbar; neuer Attempt erst nach Klärung | +| U2 `publishing` | Erwartete geprüfte Größe/Hash/Typ, Zielkey/-generation und Operationsrevision committed | Kein normaler Auslieferungspfad; Reconciler kennt genaue mögliche Dateiwirkung | +| F `publish_once` | Tatsächliche immutable Datei plus PublishReceipt | Keine DBtransaktion offen; bei unklarer Dateiwirkung Receipt/Datei prüfen, nicht neuen Pfad erfinden | +| U3 `ready` | Aktuelle Rechte/Parentversion, Asset + Link + Kapazitätsfinalisierung + nötiger Uploadverbrauch + Audit gemeinsam committed | Erst danach 201 bzw. aktivierbarer Content; kein Teil-Facherfolg | +| `rejected/aborted/expired` | Sicherer Grund, keine aktive Asset-/Linkfreigabe | Temporäre und unverknüpfte Dateien nachvollziehbar bereinigen; Kapazität erst nach wirklicher Löschung freigeben | + +`publish_once` veröffentlicht ohne Überschreiben auf einen ausschließlich diesem Vorgang zugeordneten Key. Bei lokaler Same-Filesystem-Variante darf eine qualifizierte atomare Veröffentlichung mit Datei-/Verzeichnis-Durability genutzt werden; Quarantäne und Ziel müssen dafür dieselbe geeignete Generation verwenden. Ein filesystemübergreifendes Rename oder allgemeines NASversprechen wird nicht als atomar/dauerhaft ausgegeben. Der Adapter weist sein tatsächliches Durabilityprofil nach; unerfüllte zugesicherte Haltbarkeit verhindert `ready`. + +Existiert der Zielkey schon, prüft ein Wiederanlauf Operationsbindung, vollständige Größe/Hash und Receipt. Nur derselbe verifizierte Inhalt ergibt idempotenten Erfolg. Andere Bytes sind `storage_conflict`; kein Überschreiben. Ein Crash nach F und vor U3 hinterlässt ein nicht auslieferbares Objekt mit bekanntem Intent. Vor U3 werden Session-/Scope-/Objekt-/Hold-/Quotenrechte erneut geprüft; bei Entzug keine Aktivierung, sondern begrenzte Bereinigung. Ist der Parent inzwischen geändert, kein stilles Einhängen an dessen neue Version. + +Für Renderjobs gilt derselbe Publishvertrag. Externes Storage ist ein späterer Adapter mit eigenen Konsistenz-/Delete-/Receiptgarantien, kein Pflichtbestandteil. Die DB beschreibt den letzten **nachgewiesenen** Zustand; ein erfolgreicher DBcommit beweist nicht automatisch vorhandene/dauerhafte Bytes. + +## 8. Kapazität, Deduplizierung und Verknüpfungen + +Technische Spool-/Diskgrenzen gelten unabhängig von bezahlten Plänen. U0 reserviert eine belastbare obere **gleichzeitige** Belegung aus Rohdatei, normalisiertem Ergebnis, Varianten und gegebenenfalls Publishkopie. Passt ein tatsächlicher Zwischenschritt nicht in diese Grenze, abbrechen; keine spontane ungebundene Erweiterung. Aktuelle/Trash-/gesperrte Originale und Varianten zählen physisch weiter, bis sie nachweislich gelöscht sind. Nicht auffindbare oder unklar vorhandene Bytes geben keine zusätzliche freie Kapazität. + +Ein periodisches Feature „Uploads“ bucht genau nach seiner registrierten Einheit, im Default einmal bei erfolgreicher U3aktivierung. Datei-/Assetbestand, belegte Bytes und Parentattachments sind getrennt. Wiederverwendung eines bestehenden Assets ist kein neuer physischer Upload, kann aber die Attachmentgrenze des Parents beanspruchen. Alle beteiligten Quoten-/Usage-/Fachwrites verwenden denselben U3-Tx; tatsächliche Dateiwirkung bleibt außerhalb und wird durch die Operation gebunden. Nach auditpflichtigem Commitfehler kein Usererfolg und kein unberechtigter Quotenrefund. + +Default ist explizite **logische Assetwiederverwendung**, keine globale physische Hashdeduplizierung. Der Benutzer verknüpft nur ein bereits sichtbares, aktives, geeignetes Asset. Identischer Inhalt eines anderen persönlichen Raums wird nicht über Treffer/Timing/IDs offenbart. Bei später wirklich benötigter Bytededuplizierung nur innerhalb derselben Schutz-/Hold-/Retentiondomäne und mit separatem Blob-/Referenzvertrag; kein globales „Hash bekannt, fremdes Asset verknüpfen“. + +`attach` prüft in einer UoW Parenteditrecht, Assetleserecht, Scopekompatibilität, active-Status, Rights-/Holdvertrag, erwartete Parent-/Assetversion und Attachmentkapazität. Assetmetadaten ändern verlangt zusätzlich das eigene Assetrecht. `detach` entfernt nur den Parentlink; das Asset kann anderen berechtigten Verknüpfungen weiter dienen. Ordner-/Besitznamen auf der Platte ersetzen diese Prüfungen nicht. + +Eine Parentfreigabe veröffentlicht private Medien nicht automatisch. Der erste sichere Default ist: kompatible Assetfreigabe vorher ausdrücklich herstellen oder die Parentpromotion mit `media_visibility_conflict` verweigern. Ein Shinkanproduktadapter kann seinen vorhandenen expliziten Promotionsablauf erhalten, muss aber alle betroffenen Assetrechte, aktuelle Rightsdeclarations und Versionen gemeinsam prüfen. Betreiber-/Superadminrechte verleihen im Familienvertrag kein pauschales Leserecht auf persönliche Kanshō-/Mitai-Dateien. + +## 9. Lesen, Download und native Medien + +### 9.1 Autorisierter Readplan + +Der aktuelle Accessvertrag ist **Parent lesbar AND Asset lesbar AND Link gültig AND konkrete Revision verfügbar**. Ein direkter Assetabruf ohne Parent ist nur im dafür registrierten Archiv-/Ownermodus zulässig und prüft dieselben Assetgrenzen; er ist kein Ausweg aus einer verborgenen Parentreferenz. Listen, Counts, Thumbnail, Original, Varianten, HEAD und Range verwenden denselben Filter. Unsichtbare Medien 404; keine Größe, ETag, Filename oder Holdinformation vor Autorisierung. + +R1: kurze UoW löst berechtigten Scope, Parent/Asset/Dateirevision, aktuelle Sessiongeneration und Lifecycle auf. Außerhalb der UoW wird ein gebundenes reguläres Handle auf exakt dieses immutable Storageobjekt geöffnet. R2: kurze UoW prüft die aktuelle Freigabe/Version erneut und erfasst eine begrenzte Readlease. Bei Konflikt Handle schließen und keine Bytes ausgeben. Ein Purgeintent zwischen R1 und R2 verhindert R2. Der Stream hält anschließend keine DBtransaktion/Connection offen. + +Konkreter interner Planvertrag V/K; der Storagebezug wird ausschließlich vom autorisierten R1-Adapter erzeugt: + +```python +from dataclasses import dataclass +from typing import Protocol +from app.core.context import RequestContext, ResourceRef, Tx +from app.modules.media.models import PublishReceipt + +@dataclass(frozen=True, slots=True) +class MediaReadPlan: + subject_id: str + credential_id: str + credential_generation: int + scope_kind: str + scope_id: str + asset_id: str + file_revision: str + attachment_id: str | None + parent: ResourceRef | None + parent_version: int | None + receipt: PublishReceipt + +class MediaReadPolicy(Protocol): + def plan(self, tx: Tx, context: RequestContext, *, + asset_id: str, attachment_id: str | None) -> MediaReadPlan: ... + def require_current(self, tx: Tx, context: RequestContext, + plan: MediaReadPlan) -> None: ... +``` + +Ein fehlender Parent ist ausschließlich im ausdrücklich autorisierten Archiv-/Ownermodus gültig. `require_current` vergleicht Plan, Sessionbindung, Scope, Asset-/Attachment-/Parentstand und Verfügbarkeit; nicht nur die Dateirevision. Die Readlease wird vom Readerkoordinator nach dieser Prüfung in derselben R2-UoW angelegt bzw. erneuert. Ein `MediaReadPlan` ist keine langlebige externe Downloadpermit und kein aus dem Client zu akzeptierendes Objekt. + +Längere Streams prüfen die Session-/Scope-/Asset-/Linkfreigabe und Readlease mindestens nach dem festgelegten Zeitbudget erneut, mit kurzen separaten Transaktionen. Defaultrhythmus eine Sekunde, Chunk maximal 64 KiB; bei abgelaufener Lease oder Prüffehler keine weiteren Appchunks senden. Nach bereits gesendeten Headern wird der Stream beendet, kein JSONfehler in Binärdaten gemischt. Bereits an Browser/Netz übergebene Bytes sind nicht rückholbar; Widerruf wird spätestens an der nächsten lokalen Prüfung wirksam. Keine unmögliche rückwirkende Lösch-/Widerrufsgarantie. + +Readleases sind Schutz gegen konkurrierenden Purge, kein Ersatz für Nutzerrechte. Sie besitzen feste Ablauf-/Gesamtgrenzen, werden aktuell erneuert und bei EOF/Abbruch geschlossen. Nach Prozessabbruch dürfen abgelaufene Leases verschwinden; ein noch lebender alter Stream darf danach nicht ohne Prüfung fortfahren. Asset- und Purgeservice serialisieren das Erzeugen/Beenden von Readleases am Assetdatensatz. + +### 9.2 Fetch/Blob und eng begrenzter nativer Pfad + +Für kleine persönliche Medien bleibt der Phase-3.3-Default: zentraler Fetchclient sendet Same-Origin-Cookie **und verifizierte Scopeheader**, prüft Response/MIME/Größe und erzeugt Blob-URLs. Bei Scopewechsel, Logout, Componentunmount und Fehler werden alte Fetches abgebrochen, URLs widerrufen und Viewer geleert. Es gibt keinen öffentlichen statischen `/media`-Mount als Umgehung. + +Für benötigtes natives Video mit Range kann ein **einziger registrierter GET/HEAD-Adapter** Scopehinweise `scope_kind/scope_id` und die Dateirevision in der URL akzeptieren. Er verlangt dieselbe aktuelle volle Sessioncookie, verifiziert den ausgewählten Scope und das Zielobjekt serverseitig; der URLhint selbst erteilt keine Rechte. Diese eng definierte Lesroute verwendet überprüfte Same-Origin-Fetch-Metadaten (`Sec-Fetch-Site` und passendes `Sec-Fetch-Dest`) und, soweit vorhanden, exakt geprüften Origin/Referer statt des bei nativen Elementen fehlenden Customheaders. Fehlende/inkompatible Browsermetadaten ergeben geschlossenen nativen Pfad und den Fetchfallback, keinen generellen Auth-/Scopebypass. + +Mutationen bleiben unverändert CSRF-/Origin-/Customheadergeschützt. Ein nativer Scopehint wird nicht als allgemeine Queryvariante aller Fachrouten eingeführt. Native Player setzen bei Scopeepochwechsel `src` zurück, beenden Laden/Wiedergabe und übernehmen keine verspätete alte Quelle. Jede neue Rangeanfrage prüft aktuell erneut; persönliche Medien erhalten keine freigebenden CORSantworten an fremde Origins. + +Ein separater Cross-Origin-/Drittplayer-Grant wird im ersten Schnitt **nicht implementiert**. Bei echtem späterem Bedarf muss er Asset **und Dateirevision**, Subject, Scope/Parent, Session-ID/-Generation, GET/HEADzweck, kurze Gültigkeit und Widerruf binden; keine DBpasswort-/Defaultschlüsselableitung. Native Rangezugriffe benötigen mehrere Reads und dürfen nicht versehentlich durch einen angeblich einmaligen Downloadgrant gebrochen werden. Die bestehende Shinkan-Grantidee ist Referenz, ihre profilweite Form kein ausreichender Ersatz. Keine volle Session oder gleichwertiger Sessionalias im Querystring. + +### 9.3 HTTPbinärvertrag + +Alle geschützten Binärantworten und Fehler: `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`, konkreter geprüfter MIMEtyp. Bilder und qualifiziertes Video dürfen inline; PDF und sonstige künftig ausdrücklich erlaubte Dokumente im Default `Content-Disposition: attachment`. Dateiname ist längenbegrenzt, ohne Pfad-/Steuerzeichen/CRLF; Headerencoding wird durch einen geprüften Adapter erzeugt. Kein Nutzerdateiname als roher Headerstring. + +Für Dokument-/Attachmentantworten ergänzt der Adapter eine restriktive `Content-Security-Policy` ohne Skript-/Netzressourcen und mit Sandbox, soweit der Browser sie verwendet. Das ist eine zusätzliche Auslieferungsgrenze, keine Garantie gegen aktive Inhalte beim späteren Öffnen einer heruntergeladenen Datei in einem anderen Programm. + +Für Single-Range gelten die HTTPregeln: HEAD ignoriert Range und sendet keinen Body; GET mit erfüllbarer `bytes=start-end`, offener Endrange oder Suffixrange liefert 206 mit korrekter Länge/Content-Range; eine syntaktisch gültige, nicht erfüllbare Einzelrange liefert nach Autorisierung 416 und `bytes */N`. Unbekannte Rangeeinheit wird ignoriert. Mehrfachranges und syntaktisch defekte Angaben werden im ersten Adapter vollständig ignoriert und als normale 200antwort behandelt; kein stilles Abschneiden auf das erste Segment. `If-Range` mit nicht passendem starken Validator führt zum vollständigen 200inhalt. [RFC 9110, Range](https://www.rfc-editor.org/rfc/rfc9110.html#section-14), [If-Range](https://www.rfc-editor.org/rfc/rfc9110.html#section-13.1.5) + +Die Anwendung begrenzt Headerlänge/Ziffernzahl vor Integerkonvertierung. Native Voll- und Rangeantworten bleiben unter Datei-/Deadline-/Parallelitätsgrenzen; Range ist kein grenzenloser Speicher-/CPUverstärker. Kein dynamisches HTTPkomprimieren des Bytestroms, das Offsets/Validatoren ändern würde. Eine 304-/ETagprüfung erfolgt ebenfalls erst nach Autorisierung; no-store bleibt bestehen. ETag ist an unveränderliche ausgelieferte Bytes gebunden, kein privater Contenthash in Logs. + +## 10. Rich Text, Markdown und Dokumentreferenzen + +### 10.1 Ein begrenzter interner Rendervertrag + +Das Produkt behält sein fachliches Speicherformat, z. B. Kanshō-Markdown oder Shinkan-Rich-HTML. Dieser Blueprint verlangt keine Bestandsformatmigration. Ein expliziter `DocumentAdapter` wandelt den gespeicherten Text/Editorinhalt mit Format-/Policyrevision in einen begrenzten internen `RenderDocument`-Baum. Für eine neue Anwendung kann typisiertes Editor-JSON ein Default sein; es ist kein Pflichtformat aller Produkte. + +Erlaubter erster Baum: Absätze, begrenzte Überschriften, Text mit fett/kursiv/Code, Listen, Zeilenwechsel, sichere explizite Links und `media_ref`. Kein beliebiges HTML, Skript, CSS, Objektattribute, iframe, SVG/MathML, Templatecode oder durch Daten definierte Reactkomponente. Unbekannte Formate/Nodes werden beim Schreiben mit sicherer Diagnose verweigert, nicht stillschweigend als erfolgreicher leerer Text gespeichert. Ein Readadapter für ausdrücklich markierten Legacyinhalt darf diesen sicher als Literaltext anzeigen und den Formatzustand kenntlich machen. + +```json +{ + "schema_revision": "render_document.v1", + "nodes": [ + {"type": "paragraph", "children": [{"type": "text", "text": "Notiz zum Training."}]}, + {"type": "media_ref", "attachment_id": "11111111-1111-4111-8111-111111111111", "size": "medium", "caption": "Bewegungsfolge"} + ] +} +``` + +`attachment_id` ist eine opaque Fachverknüpfung des aktuellen Parents, nicht ein frei gewählter Dateipfad. Ein Kanshōadapter kann seine vorhandene Asset-ID verwenden, wenn er deren Entryzugehörigkeit aktuell prüft; ein Shinkanadapter übersetzt `exercise_media.id`. IDs werden über Adapter kanonisiert, nicht durch Abschneiden von Zeichen. Captions sind begrenzter Text und werden niemals als HTML oder URL ausgewertet. + +Beim Speichern werden **alle** Medienreferenzen aus dem tatsächlich geparsten Dokument erfasst. Parenteditrecht und gültiger Link-/Asset-/Scopebezug werden in derselben UoW geprüft wie der Dokumentwrite; erwartete Version verhindert eine verlorene Aktualisierung. Beim Lesen/Rendern werden Referenzen erneut auf Verfügbarkeit und aktuelle Rechte gefiltert. Ein früher erlaubter Link gibt keine dauerhafte Lesebefugnis. Erlaubte fehlende Medien erhalten einen neutralen Platzhalter ohne Fremdmetadaten; ein ungültiger neuer Fremdverweis wird nicht gespeichert. + +### 10.2 Rendering und Sanitizer + +Bevorzugte Reactausgabe erzeugt Text/Elemente direkt aus dem validierten Baum; Text wird über normales Reactescaping eingefügt. Bestehende Rich-HTML-Adapter behalten eine feste serverseitige Allowlist und unmittelbar vor dem einzigen HTMLsink die Shinkan-nahe DOMPurifykonfiguration. Auch dort nur registrierte Tags/Attribute und überprüfte ID-/Caption-/Größenfelder; kein `dangerouslySetInnerHTML` mit Rohtext. + +Nach Sanitizing kein untrusted Markup durch Stringverkettung, Editorplugins oder nachgeschaltete Bibliotheken wieder einfügen. Die DOMPurifydokumentation weist ausdrücklich auf diese Grenze hin. Vertrauenswürdige Medienkomponenten erhalten nur autorisierte IDs/Blobs und validierte Props; sie bauen kein HTML aus Captions. [DOMPurify-Dokumentation](https://github.com/cure53/DOMPurify) + +Server-/Browseradapter teilen eine begrenzte semantische Testsuite einschließlich fehlerhaft verschachtelter und mutationsanfälliger HTMLfälle. Eine Bibliotheksbezeichnung allein belegt keine sichere Konfiguration. Keine deaktivierten Sanitizer bei Admininhalten und kein `raw_html=true` für Modellausgaben. Bibliotheks-/Decoderstände werden bei der späteren Implementierung gemeinsam gelockt und qualifiziert; hier keine neuen Versionslinien oder Paketupdates. + +Normale Links akzeptieren im Default nur geprüfte absolute HTTP(S)-Ziele ohne Credentials/Steuerzeichen; `javascript:`, `data:`, `file:`, `blob:` aus gespeicherten Daten und protokollrelative Umwege sind geschlossen. `blob:` erzeugt ausschließlich der eigene autorisierte Browseradapter. Externe Textlinks werden erst auf Nutzeraktion geöffnet, mit `noopener/noreferrer`; kein Prefetch oder automatische Linkvorschau. Modell-/Journaltext darf keine Remoteimages nachladen. + +## 11. Lokales PDF-/Dokumentrendering + +Wenn das Produkt ein PDF benötigt, wird zuerst Mitais strukturierter ReportLabansatz adaptiert: nur registrierte Berichtsblöcke, explizite Typen, begrenzte lokale Diagramme und korrekt escaped Text. Es entsteht kein Universal-HTML-zu-PDFdienst. Aktuelle Fachwerte und erlaubte Bildrefs werden vor dem Rendern in einer kurzen autorisierten Materialisierungs-UoW mit Quellen-/Objektversionen gebunden; der eigentliche Renderer besitzt keine DBverbindung. + +```python +from dataclasses import dataclass, field +from typing import Protocol +from app.modules.media.models import PublishReceipt, VerifiedFile + +@dataclass(frozen=True, slots=True) +class RenderSnapshot: + operation_id: str + scope_binding: str + document_revision: str + source_bindings: tuple[tuple[str, str], ...] + canonical_document_json: str = field(repr=False) + image_receipts: tuple[PublishReceipt, ...] = field(repr=False) + +class DocumentRenderer(Protocol): + def render_pdf(self, snapshot: RenderSnapshot) -> VerifiedFile: ... +``` + +`PublishReceipt` und `VerifiedFile` stammen aus Abschnitt 4; keine unabhängigen Typduplikate. Der tatsächliche Renderer erhält nur vorbereitete geprüfte Bildbytes/Handles aus diesen Receipts, keinen freien Pfadresolver. `canonical_document_json` ist intern typgeprüft und größenbegrenzt, nicht das freie APIbody. ReportLab-`Paragraph` erhält nur korrekt escaped Nutztext oder vom Adapter fest erzeugte Tags; kein usergesteuertes ``, Linkmarkup oder Attributfragment. Diagrammfehlermeldungen werden ebenso behandelt wie der normale Textpfad. + +Feste Fonts, lokale bereits geprüfte Bilder und explizit begrenzte Charts sind erlaubt. Keine Remote-URL, CSSimporte, Dateisystemsuche, Templateausdrücke, externe Webfonts oder URLfetcher. Links bleiben im ersten PDFadapter gedruckter Text; interaktive externe Aktionen sind kein notwendiger Standard. Rendering läuft mit denselben isolierten Ressourcen-/Zeitgrenzen wie Decoder. Mehrseiten-, Tabellen-, Text-/Bildanzahl- und Gesamtgrößenlimits schützen vor übergroßen Layouts. + +Nach der Erstellung Ausgabegröße/Format prüfen, optionaler PDFprüfadapter gemäß Profil. Danach aktuelles Konto/Scope, Quellen-/Dokument-/Assetversion und Ausgabe-/Speicherrecht erneut in U3 prüfen. Ein inzwischen widerrufener Snapshot darf nicht als Datei aktiv werden; ein geändertes Dokument wird nicht still unter alter Beschreibung ausgegeben. Keine Netz-/Dateirenderphase in einer offenen Fach-UoW. + +Ein erzeugtes PDF ist ein eigenes geschütztes Asset mit technischen SourceBindings und eigener Retention, kein Livefenster auf spätere Quelländerungen. Zugriff auf ein bereits erzeugtes Dokument richtet sich nach dem konkreten Produktvertrag und aktuellen Leserechten; aus seiner Existenz folgt keine Freigabe fremder Quellen. Diese technische Bindung entscheidet ADR-16 nicht. KIerzeugter Text durchläuft vor einer Übernahme weiterhin den bestehenden Gateway-/Fachvertrag; der PDFrenderer ist kein zusätzlicher Modellaufruf. + +## 12. Lifecycle, Löschschutz und physischer Purge + +### 12.1 Logische Zustände + +| Zustand | Neue Links | Normale vorhandene Anzeige | Bedeutung | +|---|---|---|---| +| `processing` | nein | nein | Upload-/Renderoperation nicht aktiviert | +| `active` | ja, nach allen Rechten | ja, nach allen Rechten | Geprüfte verfügbare Dateirevision | +| `trash_soft` | nein | Produktadapter kann bestehende Links mit Hinweis anzeigen | Shinkan-nahe Auslaufstufe, keine behauptete bereits erfolgte Löschung | +| `trash_hidden` | nein | nein | Versteckt; Wiederherstellung nur ausdrücklich berechtigt | +| `purging` | nein | nein | Verbindlicher Löschintent, irreversibler Dateischritt kann begonnen haben | +| `purged` | nein | nein | Tatsächliche Entfernung bestätigt; minimaler Tombstone | + +Availability-/Rightsblock und Hold sind zusätzliche orthogonale Schutzfelder. Ein Hold kann im Shinkanadapter normale Nutzung blockieren und physisches Löschen verhindern. Er verleiht niemandem Zugriff auf den Inhalt. Der hier verwendete technische Löschschutz setzt bestehende Produktentscheidungen um; das Dokument gibt keine neue rechtliche Bewertung oder Fristpflicht vor. + +Default für ein benötigtes Shinkan-artiges Archiv sind dessen konfigurierbare 30 Tage soft bis hidden und 90 Tage hidden bis fälligem Purge. Persönliches „verbergen/löschen“ kann nach bestehendem Produktvertrag direkt `trash_hidden` setzen; es darf nicht mit einer weiterhin sichtbaren Datei als vollständig gelöscht beantwortet werden. Wiederherstellung prüft gegen aktuellen Hold-/Rights-/Scope-/Kapazitätsstand, nie pauschal wegen einer Adminrolle. Kein automatisches Wiederaktivieren nach Ende einer Sperre. + +### 12.2 Dauerhafter Purgevertrag + +1. **P0 vorbereiten:** kurze UoW mit aktueller Management-/Retentionbefugnis, Frist, erwarteter Assetversion, vollständiger Referenzprüfung, Holdstatus und Readleases. Default nur ohne aktive/verbleibende Fachreferenz physisch löschen; bloßes Abnehmen eines einzelnen Links reicht nicht. Ein späterer ausdrücklich beauftragter Löschfall mit mehreren Referenzen muss diese zuvor konsistent entkoppeln/tombstonen, keine stillen Kaskaden im Dateiadapter. +2. **P1 Intent committen:** Assetzeile sperren, Hold/Refs/Readleases erneut prüfen, `purging` und irreversible Operationsbindung samt Storagegeneration/-objekten/Varianten/Audit setzen. Neue Links, Wiederaktivierung und Readleases ab jetzt geschlossen. +3. **P2 physischer Schritt:** außerhalb der UoW ausschließlich die gebundenen Objekte über `delete_verified` entfernen. `already_absent` ist nur bei richtig verifizierter Wurzel/Generation und genauem Key ein Beleg; fehlendes NAS oder falsche Wurzel ist kein Erfolg. Teilerfolg, Timeout oder Zugriffsfehler bleibt `purging` mit sicherem Grund. +4. **P3 bestätigen:** kurze UoW verifiziert dieselbe Operation/Assetversion und alle Deletebelege, schreibt `purged`, beendet Retention-/Referenztombstones nach Vertrag, gibt tatsächlich entfernte Kapazität frei und auditiert. Erst danach ist physischer Purge bestätigt. Repositories/Storagehelfer committen nicht selbst. + +Holdsetzen und Purgeentscheidung werden am selben Assetdatensatz serialisiert. Commit des Holds vor P1 verhindert Purge. Nach committed P1 kann ein späterer Hold nicht wahrheitsgemäß „Datei sicher erhalten“ bestätigen; er liefert `purge_in_progress` und verlangt gezielte Recoveryklärung, keine falsche Schutzgarantie. Dasselbe gilt für Restore/Reaktivierung während eines schon gestarteten Purges. Keine offene DBsperre über den Dateilöschaufruf als vermeintliche gemeinsame Transaktion. + +Ein Stream mit gültiger Readlease blockiert P1 bis zu seinem begrenzten Ende; ein Hold-/Zugriffswiderruf stoppt weitere Chunks nach Abschnitt 9. Retention wartet oder meldet diesen Zustand, statt unter dem Stream neue Dateinamen aufzulösen. Nach altem Leaseablauf muss ein verbleibender Stream seine Berechtigung erneuern, sonst beenden. Produktweiter Writerfreeze stoppt auch Leser, soweit sie DBleases schreiben oder eine Löschung/Backupaufnahme beeinflussen. + +### 12.3 Retention und Reconciliation + +Der lokale Retentionentrypoint benötigt keinen erfundenen Nutzerprincipal. Ein eng verdrahteter Maintenance-Service darf ausschließlich fällige, policygebundene Vorgänge des Produkts abarbeiten und unter eigener technischer Auditursache dokumentieren. Kein öffentliches „System=true“-Flag, kein allgemeiner Servicezugang und keine neue Maschinen-SSO-Infrastruktur. Manuelle privilegierte Übergänge behalten aktuelle Auth-/MFA-/Objektrechte. + +Reconciliation prüft `publishing`/`purging` anhand tatsächlicher File-/Receiptzustände und der erwarteten Generation. Wiederholen eines lokalen idempotenten Publishes/Deletes ist nur innerhalb genau derselben Operation zulässig. Keine neue freie Operation aus ungeklärtem Dateizustand. Orphans sind zunächst unsichtbar und kapazitätsbelegt; nach positiver Referenz-/Operationsprüfung und einer Gracefrist können sie gebunden gelöscht werden. Dateifunde werden nie anhand Ähnlichkeit von Dateinamen als Nutzerassets veröffentlicht. + +Minimalmetadaten und Holds können längere Aufbewahrung als normale private Dateien verlangen; Fristen stammen aus dem Produktvertrag, keine neu erfundene Familienrechtsnorm. Retention ist kein Backup und keine Garantie, dass entfernte Bytes bereits aus jedem älteren Backup verschwunden sind. Das muss der bestehende Backup-/Löschvertrag getrennt behandeln. + +## 13. API und sichere Fehler + +Default unter `/api/v1`; Fachprodukte können bestehende Pfade über gleiche Serviceverträge adaptieren. Strikte DTOs, sichere Foundation-Problem-Details, opaque IDs, UTC mit `Z`, `expected_version` und aktuelle Scopebindung. JSONmutationen behalten CSRF-/Origin-/Headervertrag; Content-PUT ist eine ausdrücklich registrierte Binärroute mit gleichwertiger Browsergrenze. + +| Endpoint | Verhalten | +|---|---| +| `POST /media/uploads` | JSON mit registriertem Parenttyp/-ID, erwarteter Version, bereinigbarem Anzeigedateinamen und Typkandidat; `Idempotency-Key`; 201 mit Upload-ID/Zustand/Version/Contentpfad nach U0 | +| `PUT /media/uploads/{id}/content` | Roher begrenzter Bytestrom; genau ein geclaimter Attempt; 201 mit Asset-/Attachmentrefs erst nach U3; kein frei wählbarer Speicherpfad | +| `GET /media/operations/{id}` | Eigener autorisierter sicherer Status; IDs, Phase, Reasoncode; keine Volltexte/Pfade/Prüfdateien | +| `GET /media/assets/{id}` | Berechtigte Assetmetadaten und Dateirevision; explizite Whitelist | +| `GET/HEAD /media/assets/{id}/content` | Archiv-/Ownermodus oder expliziter Parent-/Attachmentkontext; voller aktueller Readvertrag | +| `POST //{id}/media-links` | Bekanntes sichtbares Asset, erwartete Parent-/Assetversion; aktive kompatible Verknüpfung erstellen | +| `DELETE //{id}/media-links/{link_id}` | Autorisiertes Detach, 204 ohne Body nach Commit; keine implizite Dateilöschung | +| `POST /media/assets/{id}/lifecycle` | Benannte zulässige Transition und `expected_version`; sofortige logische Änderung oder 202 mit Purgeoperation; kein freier Statusstring | +| `POST /documents/{id}/render` | Konkrete Dokument-/Quellversion und registriertes Ausgabeprofil; lokale Renderoperation; begrenzter erster Schnitt synchron, Status trotzdem dauerhaft | + +Render- oder Dateioperationen, die den HTTPzeitrahmen überschreiten, benötigen einen explizit persistenten lokalen Runner; kein verlorenes BackgroundTask. Der erste Schnitt hält nur die dafür gewählten kurzen Raster-/PDFprofile offen. Ein neuer universeller Worker-/Orchestrierungsdienst ist keine Voraussetzung. Fachlicher Import/Export erhält später seinen eigenen Blueprint; diese Routen sind kein vollständiger Datenportabilitäts-/Batchvertrag. + +| HTTP / Code | Bedeutung | +|---|---| +| 401 `session_required/session_expired` | Keine gültige Identität; keine Datei-/Uploadfreigabe | +| 403 `capability_required/media_blocked/csrf_failed` | Bekannter eigener Kontext, erforderliche Befugnis/Browservoraussetzung fehlt | +| 404 `not_found` | Fremdes/unsichtbares Asset, Parent, Attachment oder nicht verfügbarer Inhalt; keine Existenz-/Größenlecks | +| 409 `version_conflict/upload_in_progress/storage_conflict/media_visibility_conflict/purge_in_progress` | Konkurrierende/inkonsistente Operation; kein automatischer Mutationsretry | +| 409 `media_capacity_exhausted` | Harte Kapazität reicht nicht; keine Teilaktivierung | +| 413 `payload_too_large` | Tatsächlicher Body/Datei-/Ausgabeumfang verletzt Grenze | +| 415 `unsupported_media_type` | Nicht registrierter oder widersprüchlicher Typ/Encoding | +| 422 `media_invalid/document_invalid/media_reference_invalid` | Ungültige Bytes/Struktur/Frames/Referenz, sicherer feldbezogener Code ohne Rohinhalt | +| 416 `range_not_satisfiable` | Nach aktueller Autorisierung gültige, nicht erfüllbare Einzelrange; korrekter Content-Range | +| 429 `media_capacity_busy` | Technische Parallel-/Spoolaufnahmegrenze; keine ungebundene weitere Operation | +| 503 `storage_unavailable/media_profile_unavailable/media_integrity_failed` | Benötigter Mount, Validator, Durability- oder Integritätsnachweis fehlt; kein Ersatzpfad | + +Nach begonnenem Stream nur sauber beenden/abbrechen; Fehler nicht in Bild-/Videobytes injizieren. Keine Rohdecoder-/Dateisystem-/PDF-/Proxytracebacks oder Dateiinhalte in Responses/Audit/Logs. Caption und Originaldateiname sind ebenfalls private Metadaten. Logging nennt sichere Operation-/Asset-/Profilrevisionen und begrenzte Reasoncodes; Querys mit möglichen zukünftigen Grants werden am Proxy redigiert. + +## 14. Grenzen, Betrieb und Restore + +| Technischer Default | Ausgangswert / Bedeutung | +|---|---| +| Rasterupload | Maximal 8 MiB Eingang, 12 Millionen Pixel, maximale Kante 8.192; genau ein Frame | +| Rasterausgabe | Maximal 16 MiB normalisierte Hauptdatei, zusammen maximal 1 MiB Thumbnail; keine ungebundene Neucodierausgabe | +| Physische Aufnahme | Reservation für Rohfile + Ausgabe + Varianten + tatsächliche Publishkopie; Same-FS-Profil ohne Kopie zunächst mindestens 25 MiB pro maximalem Rastervorgang | +| Erweiterungen Video/PDF | Nur registriert/qualifiziert; erster Kandidat Video 64 MiB, PDF 16 MiB; keine automatische Freischaltung | +| Netzwerk | Uploadidle 10 Sekunden; gesamter Uploadrequest einschließlich Verarbeitung/Finalisierung maximal 120 Sekunden; Streamgesamtzeit 120 Sekunden; begrenzte Chunks 64 KiB | +| Client-/Proxybudgets | Spezielle Upload-/Contentrouten Client 130, Proxy 135 Sekunden; begrenzter PDFrequest 45, Client 50, Proxy 55 Sekunden; kein pauschales Erhöhen aller APItimeouts und keine automatischen Writewiederholungen | +| Parallelität | Zwei aktive Upload-/Readvorgänge pro Subject, acht pro Produkt; Shared-Zulassung statt nur prozesslokaler Zähler | +| Decoder / Raster | Lokaler Kindprozess maximal 5 Sekunden, 512 MiB Speicher; keine zusätzlichen Threads/Prozesse nach freier Eingabe | +| PDFadapter | Maximal 30 Sekunden, 512 MiB, 100 Seiten, 256 KiB Dokumenttext, 32 Bildrefs, 16 MiB Ergebnis | +| Rich Text | Maximal 256 KiB UTF-8, 5.000 Nodes, Tiefe 16, 100 Medienrefs; Caption 500 Zeichen, Link 2.048 Zeichen | +| Readlease | Laufend höchstens 15 Sekunden bis Erneuerung, aktuelle Auth-/Verfügbarkeitsprüfung mindestens jede Sekunde; Gesamtrequestlimit bleibt wirksam | +| Temporärdaten | Ungeklärte Aufnahme default nach einer Stunde zur Reconciliation fällig; Orphangrace 24 Stunden; nicht blind während aktiver Operation löschen | +| Archiv-Lifecycle | Bei benötigtem Shinkanprofil 30 Tage soft, danach 90 Tage hidden; keine neu festgelegte gesetzliche Frist | + +Die engere Datei-, Request-, Pool-, Quota- oder Produktgrenze gilt. Zahlen sind anpassbar, wirkliche Grenzen bleiben Pflicht. Grenzwerte müssen auch nach Decoder-/Normalisierungsexpansion gelten. Bei fehlendem Storage/DBvalidator keine Freigabe aufgrund eines alten UIstatus. + +Der Release-/Recoveryvertrag registriert Upload, Publish, Render, Readleasepflege, Retention, Löschworker, Reconciliation und temporäres Cleanup als Writer bzw. beeinflussende Leser. Vor Backup/Restore: neue Aufnahmen stoppen, Vorgänge begrenzt drainen, ausstehende Operationen in bekanntem Zustand belassen, alle Filewriter einfrieren. Assettabellen, Operations-/Capacityledger und tatsächliche immutable Objekte/Varianten bilden einen gemeinsamen Konsistenzpunkt. Staging-/Orphanobjekte werden entweder bewusst mitmanifestiert oder vor Capture nachvollziehbar entfernt; sie verschwinden nicht implizit aus dem Nachweis. + +Restore verwendet die neue DB-/Mediengeneration aus dem vorhandenen Recovery-Blueprint. Asset-/Receipt-/Operationsbezüge werden kontrolliert an die tatsächlich restaurierte Generation gebunden und geprüft, nie durch Umstellen einer globalen Wurzel umgedeutet. Fehlende Bytes, falsche Hashes/Größen und unbekannte Mountidentität blockieren die entsprechende Freigabe. Alte Sessions, Readleases und gegebenenfalls Grants werden invalidiert; offene Purges/Publishes nicht blind erneut ausführen. Ein gelöschtes/gesperrtes Medium wird durch ein älteres Backup nicht automatisch wieder sichtbar. + +Neuere Hold-/Lösch-/Rechtezustände aus dem Verlustfenster können im Backup fehlen. Bis die betroffenen Zustände unter dem Recoveryvertrag geklärt sind, bleiben restaurierte Medien quarantänisiert bzw. ihr Lesen/Löschen blockiert. Eine Hashprüfung allein rekonstruiert diese aktuelle Befugnis nicht. Der Quotenadapter behält erforderliche Recoveryblocked-Zustände; tatsächlicher Speicherbestand und wiederhergestellte Zähler werden vor neuer Hardaufnahme abgeglichen. + +## 15. Automatisierte Sicherheits- und Negativtests + +Diese Matrix ist **V/K – Implementierungsauftrag**, kein ausgeführter Produktnachweis. Synthetische Fixtures: persönliche Räume A/B, Clubs 1/2, mehrere Parent-/Assetkombinationen, Operator ohne private Leserechte, zwei Sessiongenerationen, kontrollierte Uhr und zwei unabhängige DBconnections. Für Storage eigene temporäre Testwurzel, Mount-/Generation-/Deletefehlerfakes und echte sichere Testfiles; keine Produktdaten oder Live-Dateilöschung. + +| ID | Prüfung | Erwartung | +|---|---|---| +| MFR-01 | Fremde/fehlende Session, Scopeheader oder manipulierter Parent/Owner | Kein Upload-/Read-/Linkrecht; keine Profil-/Clubfallbacks | +| MFR-02 | CSRF/Originfehler auf JSON-/Binär-/Multipartmutation | Ablehnung vor Bodyverarbeitung/Spooling; kein ungültiger Freispeicherverbrauch | +| MFR-03 | Lügenhafte Content-Length, chunked Übergröße, gzip, Slowbody, Disconnect | Tatsächliche harte Byte-/Idle-/Gesamtgrenzen; kontrollierter unsichtbarer Teilfile | +| MFR-04 | Doppelte Uploadaufnahme und paralleler Content-PUT | Eine Operation/ein aktueller Attempt; keine gegenseitige Überschreibung | +| MFR-05 | Endung/MIME/Signatur widersprüchlich, Bild mit Anhängsel/defektem Container | Validierung oder frische kanonische Ausgabe; keine ungeprüften Originalbytes | +| MFR-06 | Pixelbombe, übergroße Dimensionen, Animation, Decoderhang | Harte Limits/Prozessabbruch; kein bloßer Threadtimeout oder stilles Framewegwerfen | +| MFR-07 | EXIF/XMP/GPS/Textchunks/Kommentare und Orientation | Definiertes Ausgabeprofil ohne fremde Metadaten; korrekte Orientierung; keine Anonymitätsbehauptung | +| MFR-08 | Metadatumsdatum und Dateizeit ohne sicheren Zeitzonenbezug | Begrenzte Herkunft/Kandidatenkennzeichnung, keine erfundene fachliche Sicherheit | +| MFR-09 | Nicht qualifiziertes Video/PDF/SVG/HTML/Archiv | Profil geschlossen; kein Erlauben allein aufgrund Endung oder Adminrolle | +| MFR-10 | Decoder versucht Netz, freie Pfade, Unterprozess oder Zugriff auf Secrets | Qualifizierte Sandbox verweigert; sichere Fehler ohne Rohdaten | +| MFR-11 | Traversal, absolute/UNC/Laufwerk-/ADS-/Symlink-/Reparsepfade aus Client und DB | Nur registrierte Generation/Keys; kein Lesen/Schreiben außerhalb der Wurzel | +| MFR-12 | NAS ungemountet, Marker falsch, Konfiguration fehlt | storage_unavailable; kein lokales Fallbackverzeichnis | +| MFR-13 | Storagekonfigurationswechsel bei vorhandenem Asset | Alte gebundene Generation unverändert; kein Umleiten alter Keys | +| MFR-14 | Crash nach U0, während U1, nach U2, nach Publish vor U3 | Nie ungeprüft auslieferbar; Reconcile nutzt genaue Operation und echte Receipts | +| MFR-15 | U3-Audit-/Quota-/Link-/Commitfehler | Kein Asseterfolg; Dateiwirkung bleibt unsichtbar und kapazitätsbelegt bis Klärung | +| MFR-16 | Rechteentzug, Sessionrotation, Parentänderung oder Hold zwischen U0 und U3 | Keine ungeprüfte Aktivierung; nur ausdrücklich zulässiger gleicher Rebind | +| MFR-17 | publish_once wiederholt: gleiche und andere Bytes am selben Key | Gleicher verifizierter Vorgang idempotent; andere Bytes Konflikt ohne Overwrite | +| MFR-18 | Parallele letzte Kapazität, Decoderexpansion, Publishkopie und nur teilweise bereinigter Rohspool | Vollständiger Worstcase belegt; Freigabe nur belegbar entfernter Objektbytes, keine ungeplante Zusatzbelegung | +| MFR-19 | Gleicher Inhalt in fremdem Privat-/Clubraum | Kein fremder Deduptreffer/Assetlink/Hashleak | +| MFR-20 | Wiederverwendung eines sichtbaren Assets, Detach eines von zwei Links | Gültiger neuer Link; anderes Parent bleibt unverändert, kein Dateipurge | +| MFR-21 | Parent sichtbar, Asset fremd/gesperrt; Asset sichtbar, Parent fremd | Schnittmenge verweigert; keine indirekte Dateifreigabe | +| MFR-22 | Thumbnail, Liste, Count, Original, HEAD, 206 und 416 für fremde Datei | Einheitliche Autorisierung vor Metadaten/Größe/ETag; sichere 404 | +| MFR-23 | Asset/Linkwechsel zwischen Readplan, Open und R2 | Gebundenes Handle/Version oder Verweigerung; keine Dateiaustauschlücke | +| MFR-24 | Konto-/Mitgliedschafts-/Session-/Holdentzug während Stream | Nächste lokale Prüfung stoppt neue Chunks; keine Connection über gesamte Streamphase | +| MFR-25 | EOF, Disconnect, Streamtimeout, Leaseverlust | Handles/Leases geschlossen bzw. Ablauf wirksam; kein Weiterstreamen mit abgelaufener Lease | +| MFR-26 | Scopewechsel im UI bei Blob-/Nativevideo-/Fehler-/401antwort | Alte Epoch verworfen, URLs widerrufen, src/Viewer geleert | +| MFR-27 | Nativer GET ohne Customheader, aber manipuliertem Scopehint/Origin/Fetchnachweis | Nur eng registrierter Adapter mit voller aktueller Session; sonst geschlossen/Fetchfallback | +| MFR-28 | Volle Session oder profilweiter Sessionalias als URLparameter | Nicht akzeptiert; kein ungeprüfter Grant-/Secretsfallback | +| MFR-29 | GET Einzelranges, Suffix/offene Range, HEAD, If-Range | Dokumentierte 200/206/416 und korrekte Länge; HEAD ohne Body | +| MFR-30 | Multi-/defekte/unknown-unit-/extrem lange Range | Bewusster ganzer 200fall bzw. frühe Headergrenze; kein stilles erstes Segment oder Parserüberlauf | +| MFR-31 | Filename CRLF/Quotes/Pfad/Unicode und falscher gespeicherter MIME | Sicherer Header, geprüfter Inhaltstyp, nosniff/no-store; kein Headerinjection | +| MFR-32 | Script/Eventhandler/iframe/SVG/MathML/CSS in Rich HTML/Markdown | Begrenzter Baum/sicheres Literal; kein ausführbarer Browserinhalt | +| MFR-33 | Fehlerhafte HTMLverschachtelung, Mutation-XSS und nachträgliches Markup | Server-/Browserfallkorpus wirksam; kein untrusted Nachbearbeiten nach Sanitizing | +| MFR-34 | Fremde/fehlende Medien-ID, gültige Syntax ohne Parentlink, manipulierte Caption | Schreibpfad verweigert; Readplatzhalter ohne Fremdmetadaten; Caption Text | +| MFR-35 | javascript/data/file/protokollrelative URL, externe Bilder oder Linkpreview | Keine automatische Ausleitung/Dateiauflösung; nur sichere explizite Textlinks | +| MFR-36 | Admin-/KIinhalt mit HTMLpayload | Gleicher Schutz wie Nutzerinhalt; keine trusted-content-Abkürzung | +| MFR-37 | Richtext-/Node-/Tiefe-/Caption-/Referenzgrenzen | Vor teurer Verarbeitung/Write begrenzt; keine stille Inhaltsänderung | +| MFR-38 | PDFusertext mit ReportLabmarkup und eingebetteter URL-/Dateianforderung | Textescaped, keine freien Ressourcen/DB-/Netzzugriffe | +| MFR-39 | PDF-/Chartlayoutbombe, Renderhang, zu große Ausgabe | Kindprozess-/Seiten-/Bytegrenzen wirksam; kein unbeschränktes RAMrendern | +| MFR-40 | Quelle/Dokument/Assetrecht ändert sich zwischen Materialisieren und Ausgabe | Kein U3erfolg unter veraltetem Snapshot; keine fremde Datei | +| MFR-41 | Promotion Parent ohne entsprechende Assetfreigabe/Rightsdeckung | Konflikt oder expliziter gleichwertiger Produktadapter; keine stille Privatveröffentlichung | +| MFR-42 | active/soft/hidden, neue/alte Links, Recovery und Operatorprivatdatei | Definierte Verfügbarkeit und getrennte Manage-/Leserechte | +| MFR-43 | Hold vor P1 gegenüber Hold nach committed P1 | Vorher kein Purge; danach kein falscher Erhaltungsnachweis, klarer Konflikt | +| MFR-44 | Noch referenziertes Asset, laufende Readlease, gleichzeitiges Attach/Retention | Kein unzulässiger Purge; gemeinsame Assetserialisierung | +| MFR-45 | Crash vor/nach tatsächlichem Delete, Teilverlust einer Variante, Deletefehler | purging bleibt bis echten Belegen; keine falsche Lösch-/Quotaerfolgsmeldung | +| MFR-46 | already_absent bei richtigem Key vs. fehlendem Mount/falscher Generation | Nur echter Abwesenheitsnachweis abschließbar | +| MFR-47 | Cleanup neben aktivem Upload/Render/Read, Orphan ohne sichere Operationsbindung | Kein blindes Entfernen; Grace/Receipts/CAS wirksam | +| MFR-48 | Backupfreeze während Publish/Purge/Readleasepflege | Alle beeinflussenden Prozesse eingefroren; konsistentes DB-/Medienmanifest | +| MFR-49 | Restore vor neuerer Löschung/Hold/Rechteänderung oder mit fehlenden Bytes | Quarantäne/Recoveryblock; keine automatische Wiederveröffentlichung oder neuer Purge | +| MFR-50 | Logging/Problem-/Status-/Preview mit privaten Canarydaten | Keine Datei-/Prompt-/Caption-/Originalnamen-/Cookie-/Keyvolltexte in technischen Ausgaben | +| MFR-51 | API-/Modulimport bei fehlender DB/Storage | Keine Seiteneffekte; fehlender benötigter Adapter bleibt geschlossen | +| MFR-52 | Persönliche API/Medien mit ServiceWorker/CDN-/Browsercache und fremdem CORS | no-store und Scopegrenzen tatsächlich wirksam; kein Cross-Origin-Bypass | + +DB-/Link-/Quota-/Hold-/Leasekonkurrenz und atomare Fachwrites später gegen isoliertes echtes PostgreSQL prüfen; Dateieffekte zusätzlich mit echter temporärer Testwurzel und injizierten Fehlern. Nicht nur Mockmethoden zählen. Testberichte nennen Fall-ID, Quell-/Buildstand, Umgebung, ausgeführte Assertions und verbleibende K-Punkte. Kein bestandener Dokumentcheck ersetzt diese Tests. + +Vorhandene Testquellen I: Shinkan [Downloadzugriff](C:/Dev/shinkan-jinkendo/backend/tests/test_exercise_media_download.py:31), [Archiv/Lifecycle](C:/Dev/shinkan-jinkendo/backend/tests/test_media_assets_archive.py:44), [Rightsdeclarations](C:/Dev/shinkan-jinkendo/backend/tests/test_media_rights_declaration.py:1), [Hold](C:/Dev/shinkan-jinkendo/backend/tests/test_p11_legal_hold.py:1), [serverseitiger Richtext](C:/Dev/shinkan-jinkendo/backend/tests/test_exercise_rich_text.py:18), [Browser-Sanitizer](C:/Dev/shinkan-jinkendo/frontend/src/utils/exerciseRichTextSanitize.test.js:1), [Storagekonfiguration](C:/Dev/shinkan-jinkendo/backend/tests/test_platform_media_storage.py:27); Kanshō [Journalbodytest](C:/Dev/Kansho/backend/tests/test_journal_body.py:1). Letzterer besitzt einen eigenen `main`-/`expect`-Pfad; bloßes pytest-Dateisammeln belegt dessen Assertions nicht. Diese Quellen wurden hier nicht ausgeführt. + +## 16. Implementierungsanweisung für Cursor und verbleibende Themen + +1. **Zielprodukt und ersten Dateifall festlegen.** Rasterupload zu genau einem vorhandenen Parenttyp, persönlichem oder Clubscope. Bestehende Produkt-/Agentenregeln bei der tatsächlichen Umsetzung lesen. Shinkanarchive, Mitai-Fotos und Kanshō-Journalmedien über Adapter wiederverwenden; kein Familien-Dateidienst. +2. **Ports anschließen.** Foundation v0.3, aktuelle Auth-/Scope-/AccessPolicy, Entitlements und lokale Kapazitätsports verdrahten. Native Medienroute nur bei konkretem Videobedarf und mit dem engen Vertrag, nicht als allgemeine Authausnahme. +3. **Reine Profile/Modelle bauen.** Strikte Operation-/Asset-/Link-/Read-/Render-DTOs, eingefrorene Typregistry, sichere Keys/Storagegeneration und begrenzte Dokumentadapter. Zuerst Fremdzugriff, Syntax-/Dateityp-/HTML-/URL-/Grenzfälle testen. +4. **Dauerhafte Operationen und SQLmigration ergänzen.** Nur benötigte Tabellen, FKs/Uniqueconstraints, erwartete Versionen, Operationsfences, Idempotenz/HMAC und Audit. Authlockordnung behalten: Account/Session/Scope/Mitgliedschaft, Parents/Assets stabil sortiert, danach nötige Entitlement-/Capacitysubjekte. Maintenancejobs sperren Assets und laden danach keine Nutzerzeilen nach. +5. **U0–U3 mit lokalem Storage implementieren.** Begrenzt aufnehmen, Quarantäne/Normalizer ohne UoW, Publishintent, echter Receipt, aktuelle Aktivierung und gemeinsame Link-/Usage-/Auditbuchung. Kein allumfassender `FileResponse(path)`-/`save(file)`-Helper mit versteckten Commits. +6. **Readpfad und Darstellung qualifizieren.** Parent/Asset als Schnittmenge, gebundenes Handle, R2/Readlease, Logout-/Scopewechsel, Header und gegebenenfalls Range. Medienrefs im Dokument beim Schreiben und Lesen verifizieren, sichere Renderer statt Roh-HTML. +7. **Lifecycle/Purge separat beweisen.** Hold-/Referenz-/Readrace, dauerhafter Intent, echter Deleteabschluss, Kapazität erst nach tatsächlicher Löschung frei. Shinkans funktionale Stufen erhalten, ohne dessen internen Commit-/Unlinkablauf ungeprüft zu kopieren. +8. **Erweiterung nur für den echten Fachbedarf.** PDF zuerst mit Mitais begrenzten strukturierten Blöcken und vollständigem Escaping; Video erst mit qualifiziertem lokalem Prüf-/Normalisierungsprofil. Kein freier URLfetcher, externer Klartext-/Medien-KIpfad oder neuer zentraler Dienst. +9. **Betrieb/Restore einbinden.** Writerinventory/-freeze, Generation-/Mountprüfung, Quarantäne/Reconciliation, fehlende Bytes und neuere Hold-/Löschzustände testen. Beide ADR-11-Buildvarianten behalten Gates und menschliche Produktionsfreigabe; keine neuen CI/CDsysteme verlangen. +10. **Nachweis abliefern und stoppen.** Tatsächlich ausgeführte MFRfälle mit Umgebung/Revision und verbleibenden K-Punkten dokumentieren. Kein Live-Rollout oder Umbau bestehender Produkte durch den Blueprintauftrag. + +Abnahme des ersten implementierten Fachfalls verlangt **aktuelle Session + Scope + Parentrecht → begrenzte Aufnahme → nachgewiesene Normalisierung → immutable Publish → atomare Asset-/Link-/Quoten-/Auditaktivierung → aktuell autorisierte Anzeige → nachvollziehbare Löschung/Recovery**, einschließlich aller kritischen Crash- und Fremdzugriffsfälle. Ein funktionierendes Bild im Browser reicht nicht. + +| Weiteres Thema nach diesem Dokument | Einordnung | +|---|---| +| **Import, Export & Batch-Verarbeitung** | Weiterer sinnvoller offener Ergänzungsblueprint: Mitais CSVregistry/-Executor und vorhandene Exportpfade sind konkrete Referenzen. Zustands-/Duplikat-/Fehler-/Transaktionsverträge fehlen als vollständiger gemeinsamer Blueprint. Hier nicht nebenbei erstellt. | +| **Quellen und persönliche Ableitungen** | Fachliche Grundentscheidung ADR-16 weiter offen; technische Versionsbezüge aus bestehenden Blueprints entscheiden sie nicht. Kein vorgezogener universeller Quellen-/Wahrheitsdienst. | +| **Maschinenzugriffe** | Begrenzte Anschlusspunkte vorhanden. Vollständiger Blueprint erst bei konkretem ausführendem Produktfall; keine vorsorgliche Agenten-/SSOplattform. | + +## 17. Prüfstand dieser Lieferung + +Gezieltes Nachlesen registrierter Mechanismen, keine neue Repositoryinventur oder Reife-/Governanceanalyse. Ergänzend wurden ausschließlich drei Primärreferenzen für Rangeverhalten, Decodergrenzen und Sanitizergrenzen geprüft; keine umfassende Recherche oder Versionsmigration. Es wurde genau dieses Markdowndokument in einem neuen Ergebnisverzeichnis erstellt. Bestehende Anwendungen und bisherige Ergebnisdokumente bleiben unverändert. + +**T – mechanischer Dokumentcheck am 16.10.2026:** 44 lokale Dateiverweise einschließlich angegebener Zeilen geprüft; drei Pythonbeispiele erfolgreich als AST geparst und ein JSONbeispiel erfolgreich gelesen; 52 eindeutige, lückenlos nummerierte Testspezifikationen erfasst; 29 Quellhashes gegen die vorhandenen Dateien geprüft. Alle 54 vor Erstellung zur Kontrolle erfassten Bestandsdateien sind unverändert. Das Ergebnisverzeichnis enthält genau dieses Markdowndokument. Es wurde kein Beispiel als Anwendung ausgeführt; die 52 Sicherheitsszenarien sind weder implementiert noch ausgeführt. Die Quellhashes unten sind kein Beleg produktiver Konformität. + +### 17.1 Lokaler Quellstand + +SHA-256 der gezielt verwendeten Implementierungs-, Test- und Produktdokumentquellen; Pfade relativ zu `C:/Dev`. Testquellen wurden nicht ausgeführt. + +| Quelle | SHA-256 | +|---|---| +| `shinkan-jinkendo/backend/media_grant.py` | `2de9f849324bebd21a4ff82c0b1c287affe5234d31c394572517c712b966f5ca` | +| `shinkan-jinkendo/backend/media_storage.py` | `b555b035079f0e7fecaa22c1b66bcde3ebd1b25e158db9606888730d6b90a5bd` | +| `shinkan-jinkendo/backend/media_lifecycle.py` | `7b73bd5d28dd7fbb1af6387bca2e3a9fc913a83346cbf869a981b7fc4bb9baf8` | +| `shinkan-jinkendo/backend/media_legal_hold.py` | `423946ca491a2c66183712e5c74d088791be58a2919b053565097108b90018a3` | +| `shinkan-jinkendo/backend/media_rights.py` | `f76ab9a336c454d2b63d126a898a7f6139edf722bf3d5474e50b4698748ef31b` | +| `shinkan-jinkendo/backend/exercise_rich_text.py` | `af818008ac4c1dcecd967cedf2706fb2d51d511639a7bb67f983ed3cbae68844` | +| `shinkan-jinkendo/backend/routers/exercises.py` | `db5c2c5c0906f95e091edcee794d6ea6a65993773914b49a24ddac0e1528fc53` | +| `shinkan-jinkendo/backend/routers/media_assets.py` | `b268a26ac9f78ae17b142503ac1b3228ca7e5b61edd798e6a57a082d391150ea` | +| `shinkan-jinkendo/backend/scripts/media_retention_job.py` | `b73ba786b08a22c1cd65df079a8f7123249cefb9a95a958e0af31fc90392c406` | +| `shinkan-jinkendo/frontend/src/utils/exerciseRichTextSanitize.js` | `808c077cc59fc27d0a4fdb1c0f525d924bf295d31cb8effd1ed815d6a611683c` | +| `shinkan-jinkendo/frontend/src/utils/exerciseRichTextSanitize.test.js` | `c636969aca99e1e9facd0b397472777d6cd1477c00cd816f845fb264e8d51002` | +| `shinkan-jinkendo/backend/tests/test_exercise_media_download.py` | `a0a72757c153053070721323b8f71a4c0b3273e3602f2e890e7529f93d214696` | +| `shinkan-jinkendo/backend/tests/test_media_assets_archive.py` | `5ca7d8a4bdb34da1ae4230afa7abdf533e4e5a732bc938aca8c44ac7a7d61c05` | +| `shinkan-jinkendo/backend/tests/test_media_rights_declaration.py` | `2b29152453de8938c7cf9c43185dfaee07350b4bf178da0a4e87e3e0c1c04270` | +| `shinkan-jinkendo/backend/tests/test_p11_legal_hold.py` | `cd53ec9c0457688112384b1d4c691e554568c8d9cca41e490022c5592c9517a2` | +| `shinkan-jinkendo/backend/tests/test_exercise_rich_text.py` | `acf98ea48aacd3ad843a9c14436928a4e9b30f0dbabf6d90337db34e1f3e4212` | +| `shinkan-jinkendo/backend/tests/test_platform_media_storage.py` | `0d20d32743ffc97cb96a20ab219d468ca17f1892f8a253b38e293728ae8f5baf` | +| `shinkan-jinkendo/.claude/docs/technical/MEDIA_ASSETS_AND_ARCHIVE_SPEC.md` | `4dcccfcf66a3c077a5a38c27c69933265639f5f89aed7718b82718f2b2436017` | +| `shinkan-jinkendo/.claude/docs/technical/MEDIA_UPLOAD_SPEC.md` | `8e61086c8f627dca0cb6cc66fdd27e4d9ab70bc9cb6c7e11d920c88a71f83527` | +| `mitai-jinkendo/backend/routers/photos.py` | `794298b690b54300af6644d0919bedc72b64960c1314b0a8f8ce35b22b0398cf` | +| `mitai-jinkendo/backend/report_pdf_render.py` | `fbb51d82382b87513a4aff3a250045d6d4688ac0528d085cf3acc9359029851e` | +| `Kansho/AGENTS.md` | `d21fb90d51a5b3a2dc9064bef7118381eee5462bf622ef2adf1fb13bb1f1f19b` | +| `Kansho/backend/media_store.py` | `fac2d9593af15dd6df13d3f3ffe461dd0051bcb34b1a217e97de3409125340fb` | +| `Kansho/frontend/src/journal/KanshoMedia.jsx` | `a185224d9abf76ed6148a4a41fd0859a05d7959df9d907b37349218d0c50c5dc` | +| `Kansho/frontend/src/journal/document.js` | `f9fdfe038670c7db24364237a7f9fb6fc356c9c893c8e3dd96adc35814fcb1ba` | +| `Kansho/backend/tests/test_journal_body.py` | `9150aaaf5e4e87509921ac67590a6ca49fa4436ef3fafd57fc1cacf671496f9e` | +| `Kansho/docs/architecture/functional/documentation_index.md` | `af4035d05d03b401bfbb8ed1e07731106723418db90dfe0d3ef4290d7e6eb6d0` | +| `Kansho/docs/architecture/functional/guardrails.md` | `deadd95b5019fe807026616f6ff74a2467d9d951702c032573d59f27c125dc4b` | +| `Kansho/docs/architecture/technical/voice_and_media.md` | `83db25e53f82ed2149f91869f37fdfeed02b3525deab70f9984af13ea9aeb279` | + + diff --git a/docs/reference/Jinkendo_Prompt_Placeholder_Workflow_Blueprint.md b/docs/reference/Jinkendo_Prompt_Placeholder_Workflow_Blueprint.md new file mode 100644 index 0000000..da40861 --- /dev/null +++ b/docs/reference/Jinkendo_Prompt_Placeholder_Workflow_Blueprint.md @@ -0,0 +1,591 @@ +# Jinkendo – Prompt-, Platzhalter- & Workflow-Laufzeit Blueprint + +**v0.1 · 16.10.2026 · Spezialblueprint 3 nach Release und KI-Gateway · technischer Entwurf V/K** + +## 1. Ziel, Geltung und Nachweis + +Dieser Blueprint spezifiziert die produktlokale Ausführung versionierter Prompts und begrenzter Workflowgraphen: Registrierung, Datenauflösung, Rendering, Entscheidungssignale, Zustandsübergänge, Abbruch und Wiederaufnahme. Primäre Implementierungsreferenz ist Mitai. Modelltransport, Privacy und Maskierung bleiben im bereits beschriebenen KI-Gateway; Identität und Datenraumgrenzen bleiben im Auth-Blueprint. Die Implementierung erfolgt erst in einem gesonderten Coding-Auftrag. + +Kompatibilitätsgrundlagen: + +- [Application Foundation A v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md), [Foundation B v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md) und [Entscheidungen C v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md). +- [Auth, Session & Scope](C:/Dev/jinkendo-phase3-3-auth-session-scope-blueprint-2026-10-16/Jinkendo_Auth_Session_Scope_Blueprint.md), [Release, Betrieb & Recovery](C:/Dev/jinkendo-release-betrieb-recovery-blueprint-2026-10-16/Jinkendo_Release_Betrieb_Recovery_Blueprint.md) und [KI-Gateway, Providerzugriff & Privacy](C:/Dev/jinkendo-ki-gateway-provider-privacy-blueprint-2026-10-16/Jinkendo_AI_Gateway_Provider_Privacy_Blueprint.md). +- [Phase-3.1-Wissenselemente](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json), insbesondere KI-MIT-08/09/10/11, KI-SHK-07 und ergänzend KI-KAI-11; [Quellenregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/sources.json), [Testregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/tests.jsonl) und [Guardrailregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/guardrails_source_register.jsonl). +- Beschlossene ADR-01 bis ADR-14 aus dem [Entscheidungsregister](C:/Dev/jinkendo-architecture-consolidation-phase2-v0.2-2026-10-15/05_Architecture_Decision_Register.md). Der historische Freigabewortlaut dieses Registers wird durch den erklärten Beschlussstatus eingeordnet. ADR-15/16 werden hier nicht entschieden. + +| Kennzeichen | Bedeutung in diesem Dokument | +|---|---| +| **V** | Vorgeschlagener technischer Standard für die spätere Umsetzung | +| **I** | Gezielte statische Implementierungsreferenz mit benanntem Quellabschnitt | +| **T** | Tatsächlich ausgeführte Prüfung mit engem, ausdrücklich benanntem Umfang | +| **K** | Noch nicht integrierte oder getestete Kombination | + +Alle neuen Schnittstellen und Abläufe sind **V/K**. Vorhandene Testdateien sind **I**, kein Nachweis eines bestandenen Laufs. Die Dokumentprüfung am Ende ist ausschließlich T für Dateiintegrität, Verweise und Beispielsyntax. Weder dieser Blueprint noch die Foundation sind dadurch eine produktionsreife Referenzimplementierung. + +Es entstehen kein zentraler Workflowdienst, keine gemeinsame Fachdatenbank, kein SSO und kein allgemeines Agenten- oder Automatisierungsframework. Ein Produkt ohne Workflows benötigt nur den registrierten Einzelpromptpfad. Bestehende Anwendungen und bisherige Ergebnisverzeichnisse bleiben unverändert; Tsumugu ist keine Implementierungsquelle. + +### 1.1 Verbindliche Verträge und technische Defaults + +| Verbindlicher Architekturvertrag | Technischer Default / begründet anpassbare Wahl | +|---|---| +| Verifizierter Principal, expliziter Datenraum, aktuelle Objekt-/Capabilityprüfung, Fail-Closed | Konkrete Capabilitynamen und Dateipfade | +| Unveränderliche ausführbare Definitionen und eindeutige Versionsbindung je Ausführung | UUIDs für Definitionen, Ganzzahlrevisionen und SHA-256 für unpersönliche Definitionsinhalte | +| Registrierte, typisierte Auflösung; fehlende Werte und Fehler unterscheidbar; keine ungeprüften Clientwerte als Fachquellen | Grammatik `{{key}}`, `d`/`x`, konkrete Ausgabeformatierung | +| Sicher begrenzter Graph; keine beliebige Codeausführung aus Definitionen | Sequenzieller DAG mit fünf Mitai-Knotentypen, genau einem Endknoten | +| Jeder Modellaufruf durch das Gateway; keine automatische Wiederholung ungeklärter externer Wirkung | Produktlokaler DB-Runner ohne Broker, Polling- und Leasewerte | +| Aktuelle Rechteprüfung und Ergebnis-/Checkpoint-/Auditwrite in derselben Transaktion; kein Netzwerk in offener UoW | Tabellenaufteilung, technische TTLs und Grenzwerte | +| Keine persönlichen Volltexte in technischen Logs, Fehlermeldungen oder Fortschrittsereignissen | Aufbewahrungsfrist für ausdrücklich gespeicherte private Ausführungsergebnisse | +| Pflicht-Gates und nachvollziehbare Build-/Quellversionen gemäß ADR-11 | R1 bevorzugt; R2 weiter zulässig; keine neue CI/CD-Infrastruktur | + +Ein Default darf mit begründetem Produktbedarf angepasst werden. Das erlaubt keine Umgehung der zugehörigen Verträge. Insbesondere ist eine größere Laufzeitgrenze keine Erlaubnis für unbeschränkte Graphen oder automatische Modellretries. + +## 2. Vorhandene Mechanismen gezielt wiederverwenden + +| Quelle I | Übernehmen / adaptieren | Grenze des Nachweises und notwendige Ergänzung V/K | +|---|---|---| +| Mitai [Modelle](C:/Dev/mitai-jinkendo/backend/workflow_models.py:16), [Graphprüfung](C:/Dev/mitai-jinkendo/backend/workflow_engine.py:67), [Reihenfolge](C:/Dev/mitai-jinkendo/backend/workflow_engine.py:412), KI-MIT-08 | `start`, `analysis`, `logic`, `join`, `end`; DAG, Erreichbarkeit, strukturierte Bedingungen | Zusätzlich doppelte IDs, Knotenschemata, Ports, Dominanz von Referenzen, Grenzen und gebundene Versionen prüfen. Editorpositionen sind keine Laufzeitsemantik. | +| Mitai [Executor](C:/Dev/mitai-jinkendo/backend/workflow_executor.py:39), [Analysis](C:/Dev/mitai-jinkendo/backend/workflow_executor.py:278), [Joins](C:/Dev/mitai-jinkendo/backend/workflow_executor.py:558) | Trennung von Knotenausführung, Routing, Signalen und Ergebnisaggregation | Der gelesene Executor verwaltet wesentliche Laufzustände im Speicher und speichert den Gesamtzustand zum Abschluss/Fehler. Das ersetzt keine Checkpoints je Node, Lease oder Crashbehandlung. Der direkte Modellcallback und die dort feste Modellwahl werden durch den Gatewayport ersetzt. | +| Mitai [Registry](C:/Dev/mitai-jinkendo/backend/placeholder_registry.py:57), [Duplikatsperre](C:/Dev/mitai-jinkendo/backend/placeholder_registry.py:169), [Registrierungen](C:/Dev/mitai-jinkendo/backend/placeholder_registrations/__init__.py:1), KI-MIT-09/10 | Ein Katalog für Metadaten, Resolver, Picker, Validierung und Export; doppelte Keys als Fehler | Im Foundation-Bootstrap explizit aufbauen und anschließend einfrieren. Keine verteilten Parallelkataloge oder Datenbankzugriffe beim Import. | +| Mitai [Rendering](C:/Dev/mitai-jinkendo/backend/prompt_executor.py:18), [Resolver](C:/Dev/mitai-jinkendo/backend/placeholder_resolver.py:1708), [Modifier-Tests](C:/Dev/mitai-jinkendo/backend/tests/test_placeholder_modifier_d.py:98) | `{{key}}`, `{{key|d}}`, `{{key|x}}`, `{{key|d,x}}`; Datenauflösung und Darstellung trennen | Unbekannte Keys nicht als unaufgelösten Text versenden. Keine Legacy-Fehlerstrings als Wert; unbekannte Modifier ablehnen. Nur verwendete und erlaubte Daten materialisieren. | +| Mitai [Normalisierung](C:/Dev/mitai-jinkendo/backend/normalization_engine.py:16), [Logik](C:/Dev/mitai-jinkendo/backend/logic_evaluator.py:25), [Joinprüfung](C:/Dev/mitai-jinkendo/backend/join_evaluator.py:142) | Endliche Antwortspektren und deklarative Operatoren; explizite Pfadzusammenführung | Strikte Typen und Dreiwertlogik ergänzen. `unknown`/Fehler ist kein boolesches `false`. `wait_any`/`best_effort` nicht als implizite Sicherheitsfehlerbehandlung übernehmen. | +| Mitai [Metadatenstandard](C:/Dev/mitai-jinkendo/.claude/docs/audit/platzhalter/PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md:1), [Framework](C:/Dev/mitai-jinkendo/.claude/docs/technical/PLACEHOLDER_REGISTRY_FRAMEWORK.md:1), [Evidencehelper](C:/Dev/mitai-jinkendo/backend/placeholder_registrations/_evidence.py:15) | Semantik, Typ, Einheit, Zeitfenster, Herkunft und Fehlwerte als Verträge; Evidence kenntlich machen | `code-derived` beschreibt technische Herkunft. Es beweist weder fachliche Richtigkeit noch aktuelle Gültigkeit einer persönlichen Ableitung. Keine Vorentscheidung von ADR-16. | +| Mitai [Promptvalidator](C:/Dev/mitai-jinkendo/backend/prompt_executor.py:116), [Debugwerte](C:/Dev/mitai-jinkendo/backend/workflow_executor.py:1073), KI-MIT-11 | Struktur des Prüf-/Diagnosebedarfs berücksichtigen | Das Schemaargument enthält dort noch eine TODO; `json.loads` allein genügt nicht. Debugtexte und aufgelöste Werte werden nicht in den gemeinsamen Standard kopiert. | +| Shinkan [Jobfassade](C:/Dev/shinkan-jinkendo/backend/ai_prompt_job.py:14), [Kontextmodell](C:/Dev/shinkan-jinkendo/backend/ai_prompt_context.py:19), [Laufzeit](C:/Dev/shinkan-jinkendo/backend/ai_prompt_runtime.py:31), KI-SHK-07 | Typisierten Fachkontext getrennt von Promptladung/Rendering und Fassade halten | Ein Modul namens Job ist kein dauerhafter Queuevertrag. Konto-, Club- und Objektzugriff übernimmt der bestehende Auth-/Scope-Vertrag. | +| Kairo [Eingabevalidierung](C:/Dev/kairo-jinkendo/backend/prompt_validation.py:48), KI-KAI-11 | Ergänzender Vergleich für registrierte Pflichtwerte und Typen | Unbekannte Keys/Typen werden dort nicht automatisch verweigert; der neue Vertrag tut dies. Keine Aktivierung eingefrorener Kairo-KI-/Workflowfunktionen. | +| Kanshō über den [fertigen Gateway-Blueprint](C:/Dev/jinkendo-ki-gateway-provider-privacy-blueprint-2026-10-16/Jinkendo_AI_Gateway_Provider_Privacy_Blueprint.md) | Datenminimierung, lokale Detection, Maskierung, Egress-Gate und kontrollierte Rehydrierung | Hier keine zweite Maskierungslogik. Auch vorherige Modellausgaben werden bei erneutem Versand vollständig durch das Gateway geprüft. | + +Die Wiederverwendung betrifft lokale Muster und geeignete Algorithmen. Kein Produkt importiert Laufzeitmodule aus einem anderen Repository. Eine gemeinsame Bibliothek wird erst bei zwei konkreten Konsumenten mit stabilem Vertrag und Verantwortung extrahiert. + +## 3. Komponenten und Foundation-Anschluss + +```text +Fachrouter / autorisierte Promptverwaltung + -> WorkflowService / PromptService + -> DefinitionCompiler + eingefrorene Registries + -> ScopeMaterializer -> TypedSnapshot -> TemplateRenderer + -> ExecutionRepository + Audit (kurze gemeinsame UoW) + -> produktlokaler Runner + -> ExecutionContextResolver + AccessPolicy + -> Scheduler -> PureNodeHandlers + -> ModelGateway.complete(context, GatewayCall) + -> bestehende Privacy-/Providerpipeline + -> WorkflowResultSink innerhalb Gateway-T3 + -> Checkpoint / nächster Zustand / safe Progress +``` + +| Komponente | Verantwortung | Darf nicht | +|---|---|---| +| `DefinitionCompiler` | Definitionen/Referenzen prüfen, Platzhalter-Tokenplan und Graphplan erzeugen | Daten auflösen, Provider kontaktieren, Rechte aus dem Graph übernehmen | +| `PlaceholderRegistry` | Metadaten und vertrauenswürdige Resolverregistrierung | Benutzerwerte, Session oder globales aktuelles Profil speichern | +| `HandlerRegistry` / `ResultSpecRegistry` | Codehandler und Ergebnisverträge mit ID/Revision registrieren | Importpfade oder ausführbaren Code aus DB-/Requeststrings laden | +| `ScopeMaterializer` | Benötigte Quellen in einem autorisierten Snapshot mit Versionen auflösen | Erstes/minimales Profil wählen oder Profildaten aller Nutzer einsammeln | +| `TemplateRenderer` | Vorcompilierte Tokens einmalig mit typisierten Werten ersetzen | Daten laden, rekursiv rendern, Netzwerk oder Templatescripting ausführen | +| `WorkflowService` | Start, Verwaltung, Abbruch, Wiederaufnahme; Berechtigungen, Idempotenz und Audit | Nodeoutputs oder privaten Graphkontext in HTTPfehler schreiben | +| `Runner` / `Scheduler` | Dauerhaften Zustand lesen, Lease halten, genau den nächsten freigegebenen Knoten koordinieren | In-Memory-Zustand als dauerhafte Wahrheit oder Lease als Benutzerrecht behandeln | +| `WorkflowResultSink` | Validierten Gatewayoutput und Nodecheckpoint atomar in T3 speichern | Direkt mit Provider sprechen oder ungeprüften Output übernehmen | +| `ProgressReader` | Gefilterten Status nach aktuellem Zugriff lesen | Modelltokens oder beliebige Debugtexte durchreichen | + +Verzeichnisdefault innerhalb der Foundation: `app/modules/prompts/{models,registry,compiler,renderer,service,repository,api}.py` und `app/modules/workflows/{models,compiler,scheduler,handlers,runner,context,result_sink,service,repository,api}.py`. Produktresolver liegen im jeweiligen Fachmodul. Kein neues generisches CRUD-, DI- oder Pluginframework. + +`create_app(settings, providers)` erhält diese Adapter aus `bootstrap`. Reine Registrierung ist DB-/netzfrei; Lifespan verwaltet Pool und Gatewayclients. API und Runner nutzen dieselbe Factory/Adapterzusammensetzung und denselben expliziten Modulbestand. Nicht registrierte Features bleiben geschlossen. Der minimale dauerhafte Runner ist ein eigener Prozess aus dem bestehenden Backendimage mit Einstieg `python -m app.modules.workflows.runner`; er nutzt dieselbe Produktdatenbank und läuft nur, wenn das Produkt Workflows benötigt. Kein Redis, RabbitMQ, Celery, Temporal oder neuer zentraler Dienst als Voraussetzung. + +Der zusätzliche lokale Prozess ist später Teil des bestehenden Produktbetriebs und muss in dessen Start-/Stop-/Drainablauf eingebunden werden. Dieses Dokument legt keine neuen Container, Deploymentdateien oder CIjobs an. Ein flüchtiges FastAPI-`BackgroundTasks`-Objekt ersetzt ihn nicht. + +## 4. Konkrete Python-Verträge + +Die Beispiele sind Schnittstellen V/K, keine vollständigen Module. `RequestContext`, `ScopeRef`, `ResourceRef` und `Tx` werden aus Phase 3.3 übernommen; Gatewaytypen aus dem vorherigen Blueprint. Gezeigte Importpfade sind konsistent anzupassende Defaults. + +```python +from dataclasses import dataclass, field +from typing import Literal, Protocol +from app.core.context import RequestContext, Tx +from app.modules.ai.contracts import SourceBinding, RenderedPrompt + +@dataclass(frozen=True, slots=True) +class DefinitionRef: + definition_id: str + revision: int + +@dataclass(frozen=True, slots=True) +class ResolvedValue: + key: str + available: bool + value_json: str | None = field(repr=False) + missing_reason: Literal[ + "no_data", "insufficient_data", "not_applicable" + ] | None + sources: tuple[SourceBinding, ...] + +@dataclass(frozen=True, slots=True) +class MaterializedInput: + snapshot_id: str + execution_id: str + values: tuple[ResolvedValue, ...] = field(repr=False) + sources: tuple[SourceBinding, ...] + +@dataclass(frozen=True, slots=True) +class LeaseClaim: + execution_id: str + worker_id: str + fence: int + +class ScopeMaterializer(Protocol): + def load(self, tx: Tx, context: RequestContext, + execution_id: str, plan_id: str) -> MaterializedInput: ... + +class TemplateRenderer(Protocol): + def render(self, prompt: DefinitionRef, plan_id: str, + materialized: MaterializedInput) -> RenderedPrompt: ... + +class ExecutionContextResolver(Protocol): + def resolve(self, tx: Tx, claim: LeaseClaim) -> RequestContext: ... + +class WorkflowRunner(Protocol): + async def run_claim(self, claim: LeaseClaim) -> None: ... +``` + +`value_json` ist die begrenzte kanonische JSONdarstellung eines bereits typgeprüften Werts, nicht beliebiger JSONtext aus dem Client. Dies hält das eingefrorene Objekt auch intern unveränderlich; `available=true` kann bei nullablem Vertrag ausdrücklich JSON `null` enthalten. `available=false` hat `value_json=None` und einen erlaubten `missing_reason`. Fehler in Resolver, Datenbank oder Berechtigung sind Exceptions mit sicherem Code, keine Fehlwerte. JSON-`NaN`/Infinity, doppelte Objektkeys, falsche Typen und übergroße Werte werden abgelehnt. `bool` gilt nicht als numerischer Messwert. + +Der Renderer erhält einen intern erzeugten Plan, kein vom Client frei deserialisiertes `MaterializedInput`. Er prüft die gespeicherte Bindung von Snapshot, Plan, Definition und Ausführung. `RenderedPrompt.sources` umfasst auch sämtliche übernommenen Nodeoutputs; Vorlagenrevision ist die konkrete veröffentlichte Revision, nicht `latest`. + +`ExecutionContextResolver` ist ein enger interner Adapter gemäß Abschnitt 11. Ein selbst konstruierter `Principal(subject_id=...)` ist keine Identitätsprüfung. Rollen, Capabilities und Entitlements stehen nicht im Snapshot als dauerhafte Autorität. + +## 5. Registries und Erweiterungsvertrag + +### 5.1 Eine Metadatenquelle für Platzhalter + +Jeder `PlaceholderSpec` enthält: `key`, `revision`, Beschreibung, `output_spec_id`, atomar/roh/interpretiert/Score/Meta, Einheit, explizites Zeitfenster, Semantik, Fehlwertvertrag, erforderliche Capabilities, erlaubte Scopearten, Quellen-/Feldselektor, Resolver-ID, Herkunft/Evidence je Metadatum, bekannte Grenzen, Deprecation und optionalen Nachfolger. Erklärung/Caption für `|x` und Kurzbeschreibung für `|d` entstehen aus derselben Definition. Beispiele im Katalog sind ausschließlich synthetisch. + +Ein Key folgt als Default `[a-z][a-z0-9_]{0,63}`. Änderungen an Typ, Semantik, Einheit oder Zeitfenster erhalten eine neue Revision oder einen neuen Nachfolger; bestehende Prompts wechseln nicht stillschweigend. Technisch unbekannte Herkunft wird als unbekannt markiert. Ein produktiv verwendeter Resolver braucht einen ausführbaren Typ-/Quellen-/Zugriffsvertrag; eine bloß unbekannte Beschreibung ist keine Erlaubnis, beliebige Daten zu laden. + +Fehlwertvorgaben sind pro Promptbindung `required` oder `optional`. Bei `required` verhindert ein zulässiger Fehlwert die Ausführung (`input_unavailable`). Bei `optional` rendert der Renderer eine feste typisierte Fehlwertdarstellung, beispielsweise kanonisches `{"available":false,"reason":"no_data"}`. Kein freies Ersatzprompt aus dem Request, keine erfundene Null oder Nullzahl. Die Kennzeichnung ist Teil des versendeten Inhalts und durchläuft das Gateway. Unberechtigte Quellen werden auch bei `optional` verweigert. + +### 5.2 Resolver- und Funktionsregistrierung + +Vertrauenswürdige Module registrieren im Bootstrap etwa `register_placeholders(registry)` und `register_handlers(registry)`. Doppelte `(id, revision)`, unbekannte Typen oder fehlende Handler verhindern den Start des betroffenen Moduls. Nach Aufbau `freeze()`; APIrequests können keine Pythonfunktionen registrieren. Ein vorhandenes Produkt kann seine Importregistrierungen hinter diesem Adapter weiterverwenden, soweit sie keine DB-/Netzseitenwirkung beim Import besitzen. + +Ein `HandlerSpec` trägt ID, Revision, erlaubten Knotentyp, Input-/Output-Spec, maximale Ausgabe, Capabilitybedarf und Effektklasse. Im ersten Schnitt gibt es nur `pure` und `model_gateway`. Pure Handler arbeiten auf übergebenen Snapshots, lesen keine DB und führen weder HTTP, E-Mail, Dateien, SQL noch Unterprozesse aus. Fachberechnungen bleiben im vorhandenen Data Layer, werden vom autorisierten Materializer aufgerufen und nicht im Exporter/Template nachgebaut. + +Die Registry ist damit der Registrierungslayer für neue Funktionen, aber kein universeller Toolzugang. Ein späterer lokaler Fachwrite benötigt einen benannten Serviceport, aktuelle Objektprüfung, Idempotenz und einen gemeinsamen UoW-Vertrag. Externe Aktionen benötigen zusätzlich einen eigenen Wirkungs-/Reconciliationvertrag; sie sind in dieser Laufzeitversion nicht als freier Handler zugelassen. Text aus einer Modellausgabe kann keinen Handler oder seine Rechte auswählen. + +Picker, Validator, Renderer und Metadatenexport lesen denselben eingefrorenen Katalog. Ein Metadatenexport enthält keine Resolvercallables, Zugangsdaten oder persönlichen Werte. Wertepreview und Metadatenkatalog haben getrennte Rechte-/Responseverträge. + +## 6. Prompt- und Workflowversionen + +### 6.1 Entwurf, Veröffentlichung und Aktivierung + +`draft` ist mit `expected_version` bearbeitbar. `publish` prüft das vollständige Paket und erstellt eine **unveränderliche** Revision mit Compilerrevision und Inhaltsdigest. Für generische produktweite Definitionen ist dies SHA-256; für private Definitionsinhalte gilt die geschützte HMAC-/Key-ID-Bindung, kein öffentliches Volltext-Hashorakel. `activate` ändert nur den aktiven Pointer unter erwarteter Pointerversion und Audit; bereits gestartete Ausführungen bleiben gebunden. Ein erfolgreich veröffentlichter Prompt kann dennoch fachlich ungeeignet sein; Publikation ist keine Modellqualitätsbewertung. + +Promptrevision: geordnete Rollen-/Textbausteine, Placeholderbindings, Frageergänzungen mit IDs/Spektren, `purpose`, `result_spec_id` samt Revision, erlaubte Scopearten und Quellenplan. Keine ProviderURL, Schlüssel oder ungeprüfte Modell-ID. Rollen stammen aus der vertrauenswürdigen Definition; Clientinstruktionen werden als erlaubte Nutzereingabe gebunden, niemals zur System-/Developerrolle hochgestuft. Tools, Bilder und Providerplugins bleiben gemäß Gatewaystandard geschlossen. + +Workflowrevision: kanonischer Graph, konkrete Promptrevision je `analysis`, Handler-/Placeholder-/ResultSpec-Revisionen, Normalisierungstabellen, Quellenplan, Grenzen und Ausgabevertrag. Inlineprompts aus Mitai sind als eingebettete unveränderliche Promptrevision Teil desselben Pakets zulässig. Ein Slug ist eine Verwaltungshilfe; Auflösung nach `latest` während eines laufenden Knotens ist verboten. + +Snapshotbindung umfasst Definitionen, Inputs, ausgewählte Quellenfelder und Versionen. Aktuelle Security-, Privacy- und Providerpolicy darf nicht zugunsten einer alten Snapshotpolicy umgangen werden. Ist ein gebundener Stand technisch nicht mehr vorhanden/kompatibel, `definition_unavailable`; ist ein sicherheitsrelevanter Stand geändert, `context_changed`. Kein stilles Upgrade. Eine neue Ausführung kann die aktuelle Kombination ausdrücklich neu binden. + +### 6.2 Rechte auf Definitionen + +Definitionen können produktweit betreiberverwaltet oder scopegebunden sein. Produktweite Definitionen enthalten generische Instruktionen und erlaubte Resolverbezeichner; keine persönlichen Inhalte. Scopegebundene Definitionen und private Freitextentwürfe bleiben in ihrem Datenraum. Verwenden einer freigegebenen Vorlage, Lesen ihres vollständigen Inhalts, Bearbeiten und Aktivieren sind getrennte Capabilities, als Default `prompt.use`, `prompt.read`, `prompt.edit`, `prompt.publish` und entsprechende Workflowrechte. + +Ein Clubnutzer mit Ausführungsrecht erhält dadurch kein Leserecht auf fremde private Daten oder auf Betreiberkonfiguration. Aktuelle operatorpflichtige Publikations-/Aktivierungsaktionen nutzen MFA-Step-up des Auth-Blueprints. Ein Graph kann weder die eigene Scopeart ändern noch zusätzliche Capabilities erteilen. + +Löschen einer referenzierten Revision wird durch FK/Serviceprüfung verweigert; Deaktivieren verhindert neue Starts. Ein gesondertes `revoked_at` sperrt auch noch laufende Ausführungen bei Sicherheitsbedarf. Revisionen bleiben für Nachvollziehbarkeit erhalten, solange gebundene Ausführungen sie benötigen. Private Inhalte unterliegen trotzdem dem Lösch-/Retentionvertrag aus Abschnitt 9. + +## 7. Datenauflösung und einmaliges Rendering + +1. Compiler tokenisiert sämtliche zu rendernden Textfelder einschließlich Frageergänzungen und Ergebnisformatbeschreibungen. Unbekannte Keys, Modifier, doppelte/mehrdeutige Bindungen und Syntaxfehler verhindern Publikation bzw. Ausführung eines Entwurfs. +2. Der Materializer lädt ausschließlich die im Plan verwendeten Fachquellen im verifizierten Scope. Persönliche Profile werden über die eindeutige lokale Account-Profil-Zuordnung ermittelt; kein erstes Profil und kein vom Browser gesetztes `profile_id`. In Clubkontexten müssen Personenbezug und konkrete Objektsichtbarkeit ebenfalls erlaubt sein. Cross-Scope-Komposition ist in diesem Schnitt nicht erlaubt. +3. Kurze Transaktion: Accessprüfung und autorisierte SELECTs auf demselben `tx`; gemeinsamer Snapshot für mehrere Abfragen über gezielt gesetztes `REPEATABLE READ`. Bei Aggregaten bindet der Adapter einen in derselben Transaktion gepflegten Datenraum-/Quellenrevisionszähler, der auch Inserts und Deletes erfasst. Ein `max(updated_at)` oder alleinige Zeilenzahl ist kein belastbarer Versionsnachweis. Fehlt ein verlässlicher Versionsadapter, startet der entsprechende Resolver nicht. +4. Werte streng gegen ihre Specs prüfen, Snapshot mit konkretem UTC-`as_of`, festen Zeitfenstergrenzen und `SourceBinding` speichern. Flüchtige Angaben wie „heute“ werden hier gebunden; Wiederaufnahme berechnet sie nicht neu. Einzelne Berechtigungsfehler, defekte Berechnungen oder fehlende Registryeinträge brechen ab. +5. Renderer ersetzt Tokens aus dem vorcompilierten Plan genau einmal. Eingesetzter Text ist Dateninhalt; darin enthaltene `{{...}}` werden nicht erneut ausgeführt. Nur der originale Template-Tokenplan wird auf vollständige Auflösung geprüft, nicht eine naive Regex über bereits eingesetzte Nutzerdaten. +6. Alle Rollen, festen Instruktionen, Beschreibungen, eigenen Eingaben und ausgewählten Vorgängerausgaben zusammen ergeben den vollständigen `RenderedPrompt`. Anschließend prüft das Gateway die gesamte endgültige Textinventur. Ein früherer Privacycheck des Snapshots ersetzt diesen Schritt nicht. + +Mitai-kompatible Modifier: `d` fügt Kurzbeschreibung an den Wert; `x` ohne `d` liefert nur Erklärung; `d,x` liefert Wert, Beschreibung, Erklärung. Für reine `x`-Verwendung wird kein persönlicher Messwert materialisiert; der Metadatenzugriff muss erlaubt sein. Fehlende benötigte Beschreibung/Erklärung ist ein Definitionsfehler, kein stilles Weglassen. Unbekannte Modifier werden nicht ignoriert. Schreibweise und Modifierreihenfolge werden im Compiler normalisiert. + +Kein Jinja2-Environment, `eval`, Python-Formatattributzugriff, Methodenaufruf oder Template-Include im ersten Schnitt. Mitais Endknoten-Templating ist als vorhandener Komfortmechanismus anerkannt; übernommen wird seine Funktion, nicht die unbeschränkte Engine. Endausgaben verwenden eine Liste expliziter `OutputBinding(node_id, field_path, required)` mit fester Textschablone und derselben einmaligen Tokenersetzung. Feldpfade werden gegen das konkrete DTOschema compiliert, niemals gegen Pythonobjektattribute ausgewertet. Ein späterer Import bestehender Jinja-Vorlagen muss die verwendeten Konstrukte ausdrücklich abbilden oder die Vorlage als nicht unterstützt melden. + +Importierte Markdown-/Freitexte und Modelloutputs bleiben untrusted content. Sie können keine Rollen, Policies, Provider, Quellen oder Handler verändern. Der Vertrag begrenzt Wirkung; er behauptet keine vollständige Verhinderung semantischer Promptinjektion. Im Frontend nur als Text oder durch den bestehenden sicheren Markdown-/HTMLpfad anzeigen; kein `innerHTML` aus Modelltext und kein automatisches URL-/Bildnachladen. + +## 8. Graph-, Signal- und Joinsemantik + +### 8.1 Publikationsprüfung + +Veröffentlichen akzeptiert nur: eindeutige Node-/Edge-IDs; vorhandene Endpunkte; genau einen Start ohne Eingang und genau ein Ende ohne Ausgang; keine Zyklen; jeder Knoten vom Start erreichbar und mit Pfad zum Ende; gültige und eindeutige Ports; unterstützte Knotentypen; alle erforderlichen Felder und keine fremden Felder (`extra='forbid'`). Rekursion, Schleifen und dynamische Teilgraphen sind geschlossen. Der strengere Ein-Ende-Default vereinfacht einen eindeutigen finalen Commit; die Bestandsmodelle erlauben mehrere Enden und sind nicht automatisch kompatibel. + +`start`/`analysis`/`join` aktivieren nach erfolgreichem Abschluss ihre ausgehenden Kanten. Fan-out ist erlaubt, Ausführung bleibt sequenziell. `logic` besitzt genau eine `true`- und eine `false`-Kante, optional eine `uncertain`-Kante; `end` hat keine ausgehende Kante. Mehrfache Eingänge sind nur bei `join` erlaubt, alle anderen Nichtstartknoten besitzen genau einen Eingang. Nicht ausgewählte Kanten werden ausdrücklich `inactive`; nicht besuchte Pfade sind bis zur Entscheidung `unresolved`, niemals stillschweigend `true` oder `skipped`. + +Compiler prüft Input-/Outputtypen, konkrete Referenzpfade und Abhängigkeiten: Ein erforderlicher Vorgängerwert muss auf jedem Weg zum Konsumenten verfügbar sein (Dominanz-/Pfadprüfung). Ein nur bedingt erreichbarer Wert benötigt einen expliziten optionalen Inputvertrag. Jede Datenreferenz erzeugt zusätzlich eine Ausführungsabhängigkeit; vorwärtsgerichtete/zyklische Abhängigkeiten werden verweigert. Zwei Signale mit gleichem Namen aus verschiedenen Nodes werden über `(node_id, question_id)` unterschieden. + +### 8.2 Deterministische Ausführung + +Der Scheduler besucht den compilierten Graph in stabiler topologischer Ordnung, bei Gleichstand lexikografisch nach Node-ID. Er führt einen Knoten erst aus, wenn alle eingehenden Kanten entschieden und alle Datenabhängigkeiten abgeschlossen sind. Hat ein normaler Knoten keinen aktiven Eingang, wird er `skipped`, seine ausgehenden Kanten werden ebenfalls `inactive`. Skipentscheidungen werden dauerhaft gespeichert; sie hängen nicht von der zufälligen Besuchsreihenfolge eines BFS ab. + +| Knotentyp | Eingabe / Ausgabe | Wirkung | +|---|---|---| +| `start` | Gebundene freigegebene Eingabe | Aktiviert Startpfade; kein Modellcall | +| `analysis` | Konkrete Promptrevision plus freigegebene Inputs | Genau ein logischer Gatewaycall; typisierter Output und benannte Signale | +| `logic` | Geprüfte Signale / erlaubte skalare Felder | Endlicher deklarativer Ausdruck; Routing `true`/`false`/`unknown` | +| `join` | Entschiedene eingehende Pfade, getrennte Outputs | Strukturierte Zusammenführung mit expliziter Pfadabdeckung | +| `end` | Explizite Outputbindings | Finales Ergebnis samt Vollständigkeit; keine automatische Modellzusammenfassung | + +Frageergänzungen folgen Mitais Vorrangregel: Nodefragen ersetzen gleichnamige Promptdefaults; zusätzliche IDs ergänzen sie. Die endgültige Liste, Fragetexte, Spektren und Synonyme sind bereits beim Veröffentlichen eindeutig gebunden. Keine Änderung anhand einer Modellantwort. + +Signale enthalten `question_id`, `status` (`valid`, `normalized`, `unclear`, `invalid`, `not_decidable`), erlaubten Normalwert oder `null`, sowie Normalisierungsrevision. Der Gateway-ResultSpec erlaubt für ein unsicheres Signal ausdrücklich eine unsichere/null-Ausprägung; unerlaubte zusätzliche Felder oder völlig fremde Werte sind dagegen ungültiger Modelloutput. Normalisierung verwendet nur veröffentlichte exakte Werte, eine eindeutige Case-/Whitespace-Regel oder eindeutige Synonymtabellen. Mehrdeutige Synonyme verhindern Publikation; kein weiterer Modellcall zur Interpretation. + +Logik unterstützt Mitais `eq`, `neq`, `in`, `not_in`, `gt`, `lt`, `gte`, `lte`, `contains`, `and`, `or`, `not` mit streng geprüften Operandentypen und Begrenzung der Tiefe. Keine Truthiness von Strings, keine automatische Zahlkonvertierung. Semantisch unsichere/fehlende Signale ergeben `unknown`. Dreiwertlogik: `false AND unknown = false`, `true AND unknown = unknown`; `true OR unknown = true`, `false OR unknown = unknown`; `NOT unknown = unknown`. Technische Fehler oder fehlende Berechtigung sind keine Dreiwertoperandwerte, sondern stoppen die Ausführung. + +`unknown` routet nur auf eine ausdrücklich definierte `uncertain`-Kante. Ohne diese pausiert der Lauf als `paused_input`. Resume allein entscheidet das Signal nicht: im ersten Schnitt ist dann eine neue Ausführung mit neuer autorisierter Eingabe nötig. Ein späterer fachlicher Reviewadapter müsste Entscheidung und unveränderte Inputbindung versioniert speichern. `default_path`/`conservative_skip` aus Mitai dürfen nur über einen expliziten Importadapter mit gleichwertig erklärter Fachsemantik übernommen werden; kein allgemeines `except: else`. + +### 8.3 Joins und Teilergebnisse + +Default ist `wait_all` plus `ignore_skipped`: Nach Entscheidung sämtlicher Eingänge müssen alle **aktiven** Pfade erfolgreich sein und mindestens ein aktiver Pfad existieren. Inaktive Zweige zählen nicht als Fehler. Sind sämtliche Eingänge inaktiv, wird der Join selbst übersprungen. `min_paths` ist eine positive veröffentlichte Mindestzahl erfolgreicher aktiver Pfade und kann die Sicherheitsprüfung nicht reduzieren. + +`wait_any` ist im sequenziellen Default **kein Rennen** und kein vorzeitiger Commit: erst alle Eingänge entscheiden, dann mindestens einen erfolgreichen aktiven Pfad verlangen. `best_effort` darf ausschließlich ausdrücklich als optional markierte fachliche Nodefehler auslassen, sobald alle Eingänge terminal sind. Solche Fehler sind z. B. `input_unavailable` bei einem optionalen Analyseschritt, nicht Gateway-/Privacy-/Autorisierungsfehler. Die zulässigen Codes und Mindestzahl erfolgreicher Pfade stehen im veröffentlichten Vertrag; Default ist keine Fehlerausnahme und `min_paths=1`. + +`unknown` nach Versand, `paused_auth`, Privacyreview, aktuelle Quellkonflikte und Sicherheitsfehler lassen sich durch keinen Join konsumieren oder in Erfolg umwandeln. Keine Zeitüberschreitung erzeugt automatisch einen Ersatzpfad. Der historische `best_effort.timeout_seconds`-Parameter wird für diesen sequenziellen Schnitt nicht unterstützt und beim Import gemeldet. + +Zusammenführung erhält je Ursprung `node_id`, Outputref, Status und Coverage. Kein last-write-wins zwischen gleichnamigen Signalen. Ein erlaubtes Teilergebnis trägt `complete=false`, sichere ausgelassene Node-/Reasoncodes und erfüllt weiterhin das konkrete Ausgabe-DTO. Das Endergebnis erhält dann `completed_partial`. Sind nach Routing alle Wege zum Ende inaktiv oder fehlen erforderliche Werte, `failed`/`no_result`; kein leeres `completed`. + +## 9. Dauerhafte Datenstrukturen + +Logische Tabellen in der **jeweiligen Produktdatenbank**; IDs und Scope-FKs folgen dem lokalen Authmodell. Keine gemeinsame Tenant-Fachdatenbank. Migrationen werden später gemäß Foundation separat und transaktional ausgeführt, nie beim Appstart. + +| Tabelle | Wesentliche Felder / Constraints | +|---|---| +| `prompt_definitions`, `prompt_revisions` | Owner-/Scopeart oder explizit `product`; Draftversion, aktive Revision/Pointerversion; immutable Revision mit Inhalt, Schemas/Bindings/Compilerrevision/Digest, Publishactor, `revoked_at`; unique `(definition_id, revision)` | +| `workflow_definitions`, `workflow_revisions` | Dieselbe Trennung; kanonischer Graph, gebundene Referenzen, Grenzen, Inhaltshash; keine persönlichen Beispielwerte in produktweiten Revisionen | +| `workflow_executions` | UUID, `subject_id`, unveränderlicher `scope_kind/scope_id`, Workflowrevision, Status/Reason, `row_version`, Start-/Deadline-/Expiryzeit, aktuelle Autorisierungsbindung `(credential_id, credential_generation)`, Snapshotref, Input-HMAC mit Key-ID, Idempotenzschlüssel, `cancel_requested_at`, Leaseowner/Expiry/Fence, Zähler und optionale `result_ref` | +| `workflow_input_snapshots` | Ausführungs-FK, streng begrenzte private kanonische Inputwerte, konkrete SourceBindings/Versionsdigest und Zeitfenster, Delete-/Expiryzustand; Owner/Scope wie Execution | +| `workflow_node_runs` | PK `(execution_id, node_id)`; Status, Inputbindung, Start/Ende, Fence, sichere Reasoncodes, Outputref und bei Analyse `call_id`; ein logischer Analysecall pro Node, keine neue ID bei Recovery | +| `workflow_edge_states` | PK `(execution_id, edge_id)`, `unresolved/active/inactive`, verursachender Nodecheckpoint; keine impliziten Defaults | +| `workflow_outputs` | Ausführungs-/Nodebezug, private immutable Ausgabe mit eigener Outputrevision, Specrevision, SourceBindings, `complete`; nur autorisiert lesbar, nicht Rohproviderantwort oder Chat-/Reasoningdump | +| `workflow_events` | Monotone Eventsequenz je Lauf, sichere Zustands-/Reasoncodes, IDs/Zeit; unique `(execution_id, sequence)`; Teil des jeweiligen Commits, keine Volltexte | +| bestehendes `ai_calls` / Audit | Gatewayledger und Foundation-Audit weiterverwenden; Call-/Checkpoint-Verknüpfung statt zweitem Providerledger | + +Alle privaten Lookups filtern bereits im Repository nach Subject/Scope bzw. explizitem Objektzugriffsvertrag; UUIDbesitz genügt nicht. Scope und Execution-ID werden in zusammengesetzten FKs/Unique-Constraints gegen das Vertauschen von Snapshot-, Output- und Nodezeilen abgesichert. Produktweite Vorlagen erzeugen trotzdem ausschließlich scopegebundene Ausführungen. Owner eines Laufs ist im Default der startende Mensch; Clubmitglieder sehen fremde Läufe nur über einen konkret registrierten Fachfreigabevertrag, der hier nicht vorausgesetzt wird. + +Idempotenz: unique `(subject_id, scope_kind, scope_id, idempotency_key)` für Start. Derselbe Schlüssel mit gleichem serverseitig gebundenem Input liefert denselben Lauf nach aktueller Autorisierung; andere Eingabe liefert 409 `execution_conflict`. Ein Startretry nach Änderung des aktiven Pointers löst eine bereits vorhandene Bindung nicht neu auf. Keys sind begrenzte kanonische UUIDs. HMAC und Key-ID folgen dem Gateway-Keyvertrag, nicht einem öffentlichen Hash persönlicher Eingaben. + +Privater Input- und Outputspeicher ist hier ausdrücklich erforderlich, damit erfolgreiche Nodes nach einem Crash fortgesetzt werden können. Es ist kein allgemeiner Prompt-/Responsecache: nur benötigte Werte/validierte DTOs, kein komplett gerenderter Prompt, keine rohe Providerantwort oder Pseudonymtabelle. Betriebs-/Backup-/Zugriffsgrenzen entsprechen dem geschützten Produktdatenraum. `repr=False` ist nur zusätzliche Loghygiene, keine Verschlüsselung. + +Default: private Ausführungsinhalte bis sieben Tage nach terminalem Abschluss, pausierte Läufe höchstens 24 Stunden ohne Fortsetzung; produktbezogene Abweichungen mit Löschkonzept möglich. Ablauf/Löschung storniert den Lauf und entfernt private Snapshots/Outputs nach sicherem Stop. Minimale ID-/Outcome-/Dedup-Tombstones für ungeklärte bzw. referenzierte Calls bleiben gemäß Gatewayvertrag erhalten; Cleanup erteilt niemals eine neue Versanderlaubnis. Fachlich übernommene Ergebnisse werden über einen expliziten Fachservice mit eigener Retention gespeichert, nicht durch stilles Verlassen der Workflowfrist. + +Referenzierte Definitionsinhalte und personenbezogene Freitexte werden getrennt aufbewahrt; nach zulässiger Löschung privater Inhalte darf nur der technische Nachweis übrig bleiben. Für gelöschte Inhalte gibt es keine Wiederaufnahmegarantie. Export/Backup ist kein Retentions-Bypass; Wiederherstellung beachtet die Sperr- und Invalidierungsregeln des Recovery-Blueprints. + +## 10. Zustände, Abbruch und Wiederaufnahme + +### 10.1 Execution und Node + +| Executionzustand | Bedeutung / erlaubter nächster Schritt | +|---|---| +| `queued` | Start samt Snapshot committed, noch kein aktiver Claim | +| `running` | Aktueller Runnerclaim; nächste Node ausschließlich nach aktuellen Prüfungen | +| `paused_auth` | Session abgelaufen/erneuert oder frischer MFA-Nachweis nötig; nur explizites Resume desselben Owners mit gültiger Session im selben Scope | +| `paused_review` | Gateway verlangt lokale Privacyklärung; nur vorhandener autorisierter Reviewadapter mit exakter Bindung erlaubt Fortsetzen | +| `paused_dependency` | Nachweislich unversendete Arbeit durch technische Abhängigkeit blockiert; explizites Resume nach Wiederverfügbarkeit und erneuter Prüfung, keine automatische Generatewiederholung | +| `paused_input` | Nicht entscheidbares Fachsignal; keine freie Cliententscheidung, im ersten Schnitt neue Eingabe/neuer Lauf | +| `blocked_context` | Quelle/Definition/Policy nicht mehr gebunden oder verfügbar; kein automatisches Neubinden; neuer Lauf nötig | +| `paused_unknown` | Mindestens ein Call möglicherweise versendet; keine automatische Wiederholung oder Fortsetzung abhängiger Nodes | +| `cancel_requested` | Dauerhafte Abbruchanforderung; keine neuen Dispatchentscheide; bereits laufender Transport kann noch verarbeitet/berechnet werden | +| `completed`, `completed_partial` | Finaler erlaubter Output und Abschluss gemeinsam committed | +| `cancelled`, `failed`, `expired` | Terminal, keine weiteren Nodes; Grund und bekannte/ungeklärte Callwirkung getrennt erhalten | + +Nodezustände: `pending`, `running`, `awaiting_review`, `succeeded`, `skipped`, `failed`, `unknown`, `cancelled`. `running` ist kein Versandergebnis; dafür gilt ausschließlich das Gatewayledger. Ein pausierter Lauf lässt die blockierte Node je nach Ursache `pending`, `awaiting_review` oder `unknown`. Erfolgreiche Nodes werden nicht erneut berechnet. Zustandsübergänge erfolgen nur per erwarteter `row_version` und aktuellem Fence, zusammen mit Edgezuständen, Event und Audit in einer UoW. + +`completed_partial` setzt einen publizierten fachlichen Teilvertrag voraus. Ein fehlgeschlagener Sicherheitscheck wird weder `skipped` noch `completed_partial`. Der endgültige Status kann nicht allein aus „Schleife beendet“ oder der Zahl besuchter Knoten entstehen. + +### 10.2 Cancellation + +Cancel ist ein idempotenter autorisierter POST. Der Service sperrt gemäß Auth-Lockordnung zunächst Account/Session/Scope, dann Execution, prüft Owner/Capability und schreibt `cancel_requested_at`, Status und Audit. Runnerprüfungen und Gateway-T2 konsultieren denselben dauerhaften Zustand. Ein bereits terminaler Lauf bleibt terminal und liefert seinen aktuellen Status. Für dieses Objekt erfolgt keine globale Session-/Tenantänderung. + +Lokaler Abbruch/Verbindungsabbruch sind verschieden: Schließen des Browserfensters cancelt keinen angenommenen Auftrag. Ein ausdrücklicher Cancel stoppt vor dem nächsten Dispatch, bricht laufendes lokales Await soweit möglich ab und verwirft nachträgliche Inhalte. Nach möglichem Versand bleibt Usage gegebenenfalls `unknown`; `cancelled` behauptet weder Nullkosten noch erfolgreichen Providerabbruch. Die Rückgabe kann zunächst `cancel_requested` sein, endgültig erst nach koordiniertem Stop/Recovery. + +### 10.3 Recoveryentscheidung + +| Persistierter Stand nach Crash/Leaseverlust | Verhalten | +|---|---| +| Pure Node `running`, keine fremde Wirkung | Neuer Claim darf dieselbe reine Berechnung aus demselben Snapshot erneut ausführen; Commit bleibt per Fence/CAS geschützt | +| Analysisnode noch ohne Dispatch, Ledger `prepared`/nachweislich `failed_unsent` | Gleiche Node-/Call-ID; erneute aktuelle Prüfung und vollständige Gatewaypipeline, solange alle Inputbindungen unverändert sind | +| `dispatching` oder `unknown`, kein atomarer Ergebnischeckpoint | `paused_unknown`; kein erneutes Generate und keine automatische Ausweichroute | +| Ledger `completed` mit erlaubter `result_ref` und erfolgreichem Nodecheckpoint | Vorhandenes Ergebnis nach aktueller Autorisierung weiterverwenden; keine Neugenerierung | +| Ledger `completed`, aber Ergebnis nicht gespeichert/gelöscht | `result_unavailable`, Lauf blockiert; keine Rekonstruktion durch kostenlosen Retry behaupten | +| Gatewayantwort im RAM, T3 nicht committed | Keine wiederherstellbare Antwort; je Ledger konservativ ungeklärt, nicht automatisch erneut senden | +| Snapshot/Definition/Quellenversion oder alte HMAC-Keyversion fehlt | `blocked_context`; vorhandene Call-ID bleibt gesperrt | + +Ein neuer Lauf nach ungeklärtem Call ist nur eine ausdrückliche Benutzeraktion mit neuer Start-ID und sichtbarem Hinweis auf mögliche zusätzliche Kosten; er löst den alten Call nicht auf. Es gibt keinen pauschalen `/retry`-Endpoint, der intern Node-/Call-IDs austauscht. Wiederaufnahme gibt keine Garantie identischer Modellausgaben; sie verwendet bereits gespeicherte Ergebnisse oder führt bislang nicht versendete Arbeit aus. + +### 10.4 Einheitliche Fehlerzuordnung + +Der Koordinator übernimmt sichere Gateway-Reasoncodes, ohne eine zweite Wirkungsbewertung zu erfinden: `awaiting_review` führt zu `paused_review`; nach möglichem Versand `unknown`/ungeklärte Deadline zu `paused_unknown`. Nachweislich unversendete technische Abhängigkeitsfehler führen zu `paused_dependency`; kein Polling startet dadurch einen neuen Generateversuch. `blocked_context` umfasst Quell-/Definitions-/Policykonflikte. Ungültiger/refusierter Modelloutput führt zu `node=failed` und im Default `execution=failed`, ohne Repaircall. Verweigertes Konto-/Scope-/Objektrecht stoppt den Lauf gemäß Abschnitt 11; ein bereits verworfenes Resultat wird nicht durch späteres Resume wieder freigegeben. + +`paused_dependency` kann nur mit aktuellen Rechten und unveränderten Bindungen explizit fortgesetzt werden, sofern der Ledger tatsächlich keinen Versand erlaubt bzw. begonnen hat. Gibt es bereits `dispatching`, `unknown`, verworfenen Output oder fehlende gespeicherte Antwort, gilt die konservativere Recoveryregel. Privacyreview setzt einen vorhandenen vertrauenswürdigen Reviewadapter voraus; ohne ihn bleibt die Pause bestehen. `paused_auth` kann nur noch nicht versendete Arbeit oder bereits erfolgreich gecheckpointete Nodes weiterführen. Bestätigte technische Handlerfehler sind terminal, außer der veröffentlichte optionale Fachvertrag erlaubt genau ihren sicheren Fachcode. + +## 11. Runner, Sessionbindung und Konkurrenz + +### 11.1 Produktlokaler Claim + +Der Runner beansprucht einen bereiten Lauf per kurzer DB-Transaktion mit Zeilensperre, beispielsweise `FOR UPDATE SKIP LOCKED`, erhöht den monotonen Fence und setzt Leaseowner/-ablauf. Default: ein Runnerprozess mit einer aktiven Ausführung; zusätzliche Prozesse nutzen denselben Claimvertrag. Polling ist nur für fällige `queued`/recoveryfähige Zustände, nicht für pausierte/terminale Läufe. + +DBzeit bestimmt Ablauf; Heartbeat erneuert die Lease in kurzen separaten Transaktionen. Er verleiht keine Berechtigung und verlängert keine Benutzersession. Keine Connection wird über Modellawaits gehalten; synchrone Psycopg-UoWs laufen im Asyncpfad über die Foundation-Threadbridge. Heartbeat und Modellawait werden koordiniert; bei verlorener Lease stoppt der alte Runner lokale Arbeit und darf keinen weiteren Nodecheckpoint schreiben. + +Jeder technische Write prüft `(execution_id, worker_id, fence, lease_expires_at > DBzeit)` plus erwartete Zustandsversion. Claim/Leaseverwaltung sperrt nur die Execution und fasst danach keine Account-/Scopezeilen an. Autorisierte Fachphasen halten die Reihenfolge **Account → Session → Datenraum → Mitgliedschaft → Execution → Node/Call → Output/Audit** ein. So entsteht keine inverse Lockordnung zwischen technischem Claim und Accessprüfung. SQLadapter prüfen nach `UPDATE` die tatsächlich geänderte Zeile; kein Ignorieren fehlgeschlagener CAS. + +### 11.2 Autorisierung eines dauerhaften Laufs + +Im ersten Schnitt ist jeder Lauf an die **bestehende lokale Humansession** des Starts gebunden. Gespeichert werden nur interne Session-ID und Generation, keine Cookiebytes, CSRFtokens oder Passwörter. Der interne Contextresolver liest diese Session unter aktuellem Kontostatus, Account-/Sessionepoch, Generation, Idle-/Absolute-Expiry, Sessionmode, MFA und Scopevertrag. Er darf nur an eine existierende Execution/Claimbindung anknüpfen. Er exponiert keine öffentliche „Principal aus User-ID“-API. + +Der Zugriff auf die Sessionzeile erfolgt hier aufgrund des bereits autorisierten persistierten Auftrags, nicht aufgrund einer ID aus einem neuen Request. Der Runner verlängert `last_seen` nicht und erzeugt keine Session. Nur eine gültige volle Humansession ergibt einen Arbeitscontext. Browserrequests behalten ihren unveränderten Cookie-/CSRF-/Originvertrag. Der interne Adapter ist eine lokale Erweiterung der Authports, kein neuer Anmeldemechanismus und keine allgemeine Delegationsberechtigung. + +Sessionablauf oder legitime Rotation pausiert den Lauf als `paused_auth`. Ein aktueller Browserrequest desselben Subjects kann ihn im selben Datenraum mit `expected_version` erneut binden, nachdem Konto, Ausführungs-/Quellenrechte, unveränderte Inputs und erforderliches MFA geprüft wurden. Dieser Rebind ersetzt lediglich Session-ID/Generation und wird auditiert; Workflow-, Scope-, Input- und Callidentitäten bleiben unverändert. `paused_unknown`, `blocked_context`, `paused_input` und terminale Läufe werden dadurch nicht freigegeben. + +Explizites Logout/Widerruf der gebundenen Session, Kontosperre/-löschung oder Entzug der Mitgliedschaft bzw. Fähigkeit stoppt den Lauf; Default terminal `cancelled` mit sicherem Reasoncode. Bereits gestartete Modellwirkung kann weiter ungeklärt bleiben. Eine spätere Wiedererteilung von Rechten weckt solche Läufe nicht automatisch. Konto-/Objektprüfung erfolgt vor jedem Materialisieren, jeder Nodefreigabe, Gateway-T2, Gateway-T3 und jeder Anzeige erneut. Ein Operator kann fremde private Läufe nicht durch seinen Betreiberstatus übernehmen. + +### 11.3 Lease, Dispatch und Racegrenze + +Eine Lease verhindert nicht allein einen doppelten externen Call. Entscheidend ist die Gatewaybindung: stabile Call-ID, unique logische Nodeidentität, atomarer Übergang `prepared -> dispatching` und kein neuer Versand bei `dispatching/unknown`. Gateway-T2 prüft zusätzlich den aktuellen Executionzustand und Fence. Ein neuer Claim kann dadurch nicht die bereits erteilte Sendeberechtigung duplizieren. + +Dabei persistiert T2 den freigebenden Fence als `dispatch_fence` an der Node-/Callbindung in derselben Transaktion wie den Dispatchintent. Nach diesem Entscheid wird er für diesen Call nicht auf einen neuen Claim umgeschrieben. T3 vergleicht genau diesen gebundenen Fence mit der aktuellen Executionlease; bloß die neueste Fencezahl zu laden und als eigenen Claim auszugeben wäre unsicher. Eine neue Lease darf einen alten unversendeten Pure-/Preparedversuch übernehmen, aber keinen alten Dispatch als ihren eigenen Erfolg bestätigen. + +Zwischen dem letzten DBentscheid und dem externen Netzwerk besteht weiterhin keine verteilte Transaktion. Ein Cancel, Widerruf oder Leaseverlust direkt nach diesem Entscheid kann bereits freigegebene Bytes nicht zurückholen; der kurze Gateway-Dispatchpermit begrenzt das Fenster. T3 prüft erneut und verwirft dann Inhalte. Es gibt keinen Exactly-once-Anspruch für Netzwerk und Datenbank. Lokal sorgt ein eindeutiger erfolgreicher Checkpoint dafür, dass ein bereits gespeichertes Nodeergebnis nicht doppelt fachlich übernommen wird. + +## 12. Analysisnode und Gatewayintegration + +### 12.1 Aufnahme und stabile Callbindung + +Startservice: aktueller Context, `workflow.execute` und konkrete Quellen-/Objektrechte prüfen; veröffentlichte Version und alle Inputs einmalig binden; Snapshot, Execution, Nodes/Edges, Startidempotenz und Audit atomar speichern; erst nach Commit `202 Accepted`. Der Runner darf keine neuen vom Browser gelieferten `variables`, Rollen, Profile oder Graphfragmente nachladen. + +Vor einer Analysisnode: aktuelle Session-/Scope-/Quellen-/Definitionsprüfung und Lease/CAS in kurzer UoW. Persistente Call-ID wird **vor** jedem möglichen Versand einmalig dem Node zugeordnet. `GatewayCall.execution_id` ist die Execution-UUID, `node_key` die unveränderliche Node-ID. Die serverseitige `purpose`-/ResultSpecbindung stammt aus der veröffentlichten Promptrevision. Ein Resume ändert keine dieser Identitäten. + +```python +from app.core.context import RequestContext +from app.modules.ai.contracts import GatewayCall, ModelGateway, RenderedPrompt + +async def invoke_analysis(gateway: ModelGateway, context: RequestContext, + *, call_id: str, execution_id: str, + node_id: str, purpose: str, + rendered: RenderedPrompt, + result_spec_id: str): + call = GatewayCall( + call_id=call_id, + execution_id=execution_id, + node_key=node_id, + purpose=purpose, + rendered=rendered, + result_spec_id=result_spec_id, + ) + return await gateway.complete(context, call) +``` + +Die Funktion illustriert ausschließlich den unveränderten Gatewayaufruf; Auflösung, Claim, Ledger und Commitadapter sind verpflichtende vorgelagerte/interne Schritte. Sie ist kein eigenständig sicherer Router oder Ersatz für das vollständige Protokoll. + +### 12.2 Checkpoint im bestehenden T3 + +Eine Lücke zwischen „Gateway erfolgreich“ und späterem Nodewrite würde die Wiederaufnahme unsicher machen. Deshalb wird die im Gateway schon vorgesehene **atomare Fachergebnisablage** hier als `WorkflowResultSink` konkretisiert. Öffentliche Signatur `ModelGateway.complete(context, call)` bleibt unverändert. Der vertrauenswürdige Purposeadapter findet den internen Sink anhand der persistierten Call-/Execution-/Nodebindung; kein Funktionscallback oder Sinkname aus dem HTTPbody. + +```python +from typing import Protocol +from app.core.context import RequestContext, Tx +from app.modules.ai.contracts import GatewayCall, ModelResult + +class WorkflowResultSink(Protocol): + def commit_validated(self, tx: Tx, context: RequestContext, + call: GatewayCall, + result: ModelResult) -> str: + """Return private output_ref; caller owns commit and ai_calls finish.""" + ... +``` + +In derselben Gateway-T3-UoW: aktuelle Autorisierung, Quelle und Policy prüfen; gebundenen Dispatchfence gegen aktuelle Lease und Cancelzustand prüfen; validierten/rehydrierten JSONoutput in das konkrete DTO übernehmen; Output + `node=succeeded` + Edge-/Eventcheckpoint + Audit schreiben; `ai_calls=completed` und `result_ref` auf diese Outputzeile setzen. Gateway besitzt Commit; Sink und Repositories committen nicht. Ein Fehler oder verlorener Fence verhindert den gesamten Ergebniscommit. Gateway kann anschließend unter seinem engen technischen Vertrag bekannte Usage/Discardmetadaten abschließen; daraus folgt kein Nodeerfolg. + +Der Workflow stellt weder `ai_calls=completed` noch Quotenabrechnung eigenmächtig nach. Stürzt der Runner nach T3 vor Rückkehr des Awaits ab, liest der nächste Claim den bereits erfolgreichen Checkpoint. Existiert eine im Gateway gültig gespeicherte Antwort, ist kein zweiter Generate erforderlich. Runtime und Gateway müssen diese Integration durch Transaktions-/Crashprüfungen nachweisen; sie ist bislang K. + +### 12.3 Nachfolgeknoten, Privacy und Quoten + +Nur freigegebene Felder erfolgreicher Vorgänger gelangen in den nächsten Prompt. Jedes übernimmt eine SourceBinding, z. B. `kind='workflow_output'`, `source_id=output_id`, `version=output_revision`, `selected_fields=(...)`; der Quellenadapter prüft Owner, Scope, Execution und ungelöschten Stand. Weder „bereits maskiert“ noch „kam vom Modell“ ist eine Egressfreigabe: nächste Analysisnode durchläuft mit eigener Call-ID die vollständige Privacy-/Providerpipeline neu. + +Der Runner behandelt modellgenerierte Routing-/Textwerte nicht als Autorität für persönliche Datenzugriffe. Ein Klassifizierungssignal kann einen erlaubten Fachzweig auswählen, aber kein verborgenes Profil, eine neue Quelle oder ein neues Providerprofil hinzufügen. Detektion, Reviewcoverage, Maskierungstoken und Rehydrierung bleiben Eigentum des Gateways; keine Workflow-Pseudonymtabelle. + +Laufweite Grenzen zählen alle vorgesehenen/beanspruchten Analysisnodes, auch einen später `unknown` gewordenen Call. Zusätzlich nutzt **jeder** Call den `UsageBudgetPort` des Gateway-Blueprints für Reserve, tatsächliche Usage, `release_unsent` oder `mark_unknown`. Keine zweite Abrechnung am Endknoten; keine Rückerstattung allein wegen Cancel oder Workflowfehler. Harte konsum-/kostenabhängige Grenzen bleiben ohne wirksamen Adapter geschlossen. Der spätere Entitlements-/Usage-/Quota-Blueprint konkretisiert dies; hier entsteht kein Billingmodell und kein familienweiter Verbrauchsdienst. + +## 13. API, Fehler und Frontend + +Fachprodukte können ihre eigenen Ausführungsrouten verwenden; folgendes ist der konkrete gemeinsame APIdefault. Alle schreibenden Browserrouten nutzen HttpOnly-/Secure-/SameSite-Session, CSRF/Origin und verifizierte Scopeauswahl aus Phase 3.3. Persönliche Responses und Fehler `Cache-Control: no-store`. IDs sind opaque; `expected_version` ist die fachliche/CAS-Version, keine Templateversionvermutung. + +| Endpoint unter `/api/v1` | Input / Erfolg | Bedingungen | +|---|---|---| +| `GET /prompts/placeholders` | Gefilterte Metadaten `{items,next_cursor}` | Keine persönlichen Werte, internen Callables oder Quelltabellendetails für normale Nutzer | +| `POST /prompts`, `PATCH /prompts/{id}` | Strenges Draft-DTO; bei PATCH `expected_version`; 201/200 | Bearbeitungsrecht im Definitionsscope; kein frei gewählter Owner | +| `POST /prompts/{id}/validate` | Draftversion; 200 mit sicheren strukturierten Diagnosen | Nur statische Prüfung, kein Modellcall; keine resolverinternen Tracebacks | +| `POST /prompts/{id}/publish`, `/activate` | Erwartete Draft-/Pointerversion und bekannte Revision; 201/200 | Publish-/Aktivierungsrecht, aktuelles nötiges MFA; Audit | +| entsprechende `/workflows`-Routen | Strenges Graph-Draft-/Versions-DTO | Derselbe Verwaltungsvertrag; Konflikte bleiben 409 | +| `POST /prompts/{id}/preview` | Konkrete Revision, benannte fachliche Inputs; 200 | Lokales autorisiertes Rendering; keine Provideranfrage, separate `prompt.preview_values`-Berechtigung | +| `POST /workflow-executions` | `workflow_id`, optional konkrete veröffentlichte `revision`, registriertes Fachinput-DTO; `Idempotency-Key`; 202 + `Location` | Aktive Revision einmalig serverseitig auflösen; Start nach Commit | +| `GET /workflow-executions/{id}` | Status, `version`, sichere Nodezustände, Progress-/Resultref; 200 | Aktueller Owner-/Scope-/Objektzugriff; keine Inputs oder Rohfehler | +| `GET /workflow-executions/{id}/result` | Konkretes validiertes Ausgabe-DTO; 200 | Aktueller Ergebnis-/Quellenzugriff, verfügbarer Output; keine automatische Neugenerierung | +| `POST /workflow-executions/{id}/cancel` | `expected_version`; 200 aktueller Status | Idempotent gemäß Abschnitt 10; kein Scopewechsel | +| `POST /workflow-executions/{id}/resume` | `expected_version`; 202/200 | Nur unterstützte Pauseursache und exakte Bindung; neue aktuelle Humansession des gleichen Subjects | + +Einzelpromptausführung kann intern als begrenzter `start -> analysis -> end`-Plan mit denselben Call-/Resultatverträgen laufen. Der Benutzer braucht dafür weder einen Workfloweditor noch einen allgemeinen Graphbody. Ein zusätzliches öffentliches Universalendpoint `execute arbitrary graph/variables/model` ist ausgeschlossen. + +Ein Startresponse enthält nur `{id,status,version}` und Links/Refs nach dem Foundation-DTOvertrag. Node-/Outputendpoints verwenden explizite Whitelists; kein `model_dump()` des gesamten internen Executionobjekts. Previewvolltext darf ausschließlich als private no-store-Response an den berechtigten Benutzer gehen, nie als Audit-/Progresswert. Preview bindet nichts für einen späteren Produktionscall; dieser materialisiert und prüft neu. + +| HTTP / sicherer Code | Verhalten | +|---|---| +| 401 `session_required/session_expired` | Aktueller Browserrequest ohne gültige Session; Runner pausiert/stoppt separat | +| 403 `capability_required/mfa_required` | Identität bekannt, eigene Aktion unzulässig; kein Modellcall | +| 404 `not_found` | Fremde/unsichtbare Definition, Execution, Quelle oder Output; Existenz nicht offenlegen | +| 409 `version_conflict/execution_conflict/execution_in_progress` | Versions-/Idempotenzkonflikt; kein automatischer POSTretry | +| 409 `context_changed/resume_not_allowed/call_outcome_unknown/result_unavailable` | Bindung nicht fortsetzbar bzw. bereits versendete Wirkung ungeklärt | +| 409 `privacy_review_required` | Nur exakte vorhandene lokale Reviewintegration; kein Browserflag als Freigabe | +| 422 `definition_invalid/placeholder_unknown/input_invalid/input_unavailable/graph_limit` | Sichere feldbezogene Diagnose; keine Eingabewerte/Providerinhalte im Problemobjekt | +| 429 `execution_capacity` | Begrenzt angenommene Queue; sicherer Retryhinweis, kein autonomer Startretry | +| 502/503/504 gemäß Gateway | Technischer Provider-/Output-/Abhängigkeits-/Deadlinefehler; mögliche Wirkung separat vermerken | + +Asynchron auftretende Fehler ändern den gespeicherten Laufstatus; ein `GET` liefert 200 mit sicherem Zustands-/Reasoncode, solange dieses Objekt sichtbar ist. Fehler vor Auftragsannahme nutzen RFC-9457-`application/problem+json` mit Foundationfeldern und `request_id`. Keine SQL-, Regex-, Pfad-, Prompt-, Pydanticinput- oder Providerfehlermeldung ungefiltert durchreichen. + +Frontenddefault: Statuspolling während sichtbarer Ausführung; optional später sichere SSE-Statusereignisse aus dem persistierten Eventbestand. Nie rohe Modellstreamdeltas. APIclient verwendet den vorhandenen Session-/Scope-Store mit Epoch und Abort: nach Scopewechsel alte Responses, Fortschritte, 401 und Fehler verwerfen; laufende Backendexecution bleibt an ihrem ursprünglichen Scope. Ergebnisanzeige prüft erneut Zugriff. Keine Tokens/Prompts in LocalStorage, ServiceWorker-/PWAcache oder URLparametern. Wiederaufnahme und eine bewusst neue kostenpflichtige Ausführung sind getrennte Nutzeraktionen. + +## 14. Wichtige Anti-Patterns + +- Registryeinträge und `PLACEHOLDER_MAP` parallel pflegen; Export-/GUI-Metadaten unabhängig erfinden; eine neue Metrik außerhalb des Registrierungslayers verstecken. +- Alle Profilwerte vorab laden und später „nur das Nötige verwenden“; globale mutable Profilheader; `first profile`, `MIN(club_id)` oder Scopefallback bei Fehlern. +- Platzhalter unaufgelöst weiterreichen, Resolverfehler in `"n/a"` umwandeln, `0`, `false`, `null`, leer und fehlend vermischen oder eingesetzten Inhalt erneut als Template interpretieren. +- Slug/`latest`, Zeitfenster oder aktive Registry mitten im Lauf neu auflösen; veröffentlichte Definition in-place ändern; unbekannte Handler-/Schematypen tolerieren. +- Beliebiges Jinja/Python/SQL/HTTP in Nodes; vom Modell gewählte Toolnamen; `unknown` als `false`; `best_effort` über Autorisierungs-/Privacyfehler. +- BFS-Besuchsstatus mit Abhängigkeitsbereitschaft verwechseln; Join vor Entscheidung seiner Eingänge ausführen; Signalnamen unqualifiziert überschreiben. +- In-Memory-Queue oder Browser-SSE als dauerhaften Ausführungsnachweis verwenden; nach Neustart alle `running`-Nodes mit neuen Call-IDs starten. +- Erfolgreichen Gatewaycall zuerst abschließen und Ergebnischeckpoint später separat committen; eine Lease als Exactly-once-Beweis behandeln. +- Automatischer Modellretry, Reparaturcall, Fallbackprovider oder Replay bei Timeout/Cancel/`unknown`; ungeklärte Calls durch Cleanup vergessen. +- Abgelaufene Nutzersession durch eine pauschale Serviceidentität ersetzen; Runnerheartbeat als Nutzeraktivität buchen; Operator übernimmt fremde Privatläufe. +- Gerenderte Prompts, Signalsätze, Rohantworten oder persönliche Resolverwerte in normale Logs, Fehlerdetails, Profiler, Telemetrie oder Debugpanels schreiben. + +## 15. Technische Ausgangswerte + +Alle Zahlen sind **Defaults**, zusätzlich zu unverändert geltenden Gateway-/Foundationgrenzen. Der jeweils engere Grenzwert gilt. Anpassungen müssen die zugehörigen Speicher-, Deadline-, Queue- und Negativtests mitführen. + +| Parameter | Default / Bedeutung | +|---|---| +| Graph | maximal 32 Nodes, 64 Edges, 10 Analysisnodes; keine Schleifen/Subworkflows | +| Logik | maximale Tiefe 8, maximal 64 Ausdruckselemente; endliche Spektren bis 32 Werte | +| Platzhalter | maximal 128 verschiedene Bindungen pro Ausführung; nur tatsächlich verwendete Werte materialisieren | +| Definitions-/Privatdaten | Graphpaket maximal 128 KiB UTF-8; Snapshot maximal 256 KiB; gespeicherte Outputs insgesamt maximal 256 KiB je Lauf | +| Gatewayinput | Weiterhin 64 KiB gemäß Gateway; keine Workflowerhöhung dieses Limits, auch wenn Snapshot größer ist | +| Laufzeit | maximal 15 Minuten kumulierte aktive Laufzeit; absolute Ausführungsexpiry 24 Stunden ab Start; Ablauf vor neuem Dispatch prüfen | +| Einzelnode | Gatewaydeadline weiterhin 90 Sekunden; lokale reine Node maximal 2 Sekunden, Materialisierung durch DB-Statement-/Transaktionsgrenzen begrenzt | +| Runner | 1 aktive Execution, sequenzielle Nodes; Queue maximal 16 angenommene wartende Läufe pro Produktinstanz und 2 pro Subject/Scope; Aufnahme transaktional gegen Überschreitung schützen | +| Lease | 30 Sekunden, Heartbeat alle 10 Sekunden; Heartbeat im Modellawait unabhängig fortführen; bei Verlust kein neuer Write/Dispatch | +| Polling | Runner 1 Sekunde ohne Busyloop, Frontend 2 Sekunden nur bei sichtbarem Lauf; Backoff bei technischen Fehlern | +| Nodecheckpoint | Nach jeder Node und jeder Skip-/Routingentscheidung; kein Intervallverlust zugunsten von Performance | +| Retention | Private Inhalte 7 Tage nach terminalem Abschluss; pausierte Läufe höchstens bis absoluter Expiry; Minimalledger gemäß Gatewayvertrag | +| Ausgabemodus | Gepufferter validierter Text/JSON, keine Rohstreamausgabe; Render-/Graphpreview lokal ohne Provider | + +Die reine Nodefrist ist kein nachträglicher Timeout um unkontrollierten Pythoncode: zugelassene Handler müssen nach Inputgröße und Algorithmus begrenzt sein, ohne ungebundene Regex-/Rekursionskosten. Fehlt dieser Nachweis, nicht registrieren. Die kumulierte Laufzeit wird an Checkpoints und Heartbeats konservativ fortgeschrieben; nach Crash zählt der beanspruchte Zeitraum, statt das Budget zurückzusetzen. Eine Pause setzt weder Callanzahl noch Deadline zurück. + +## 16. Automatisierte Sicherheits- und Negativtests + +Die folgende Matrix ist ein verbindlicher **Testauftrag V/K**, kein Bericht bestandener Tests. Cursor implementiert die Prüfungen mit synthetischen Daten und deterministischen Fakes. Mindestens zwei Subjects mit persönlichen Räumen, zwei Clubs mit unterschiedlichen Mitgliedschaften, ein Operator ohne private Leserechte, zwei Sessions/Generationen, zwei Workerfences und eine kontrollierte Uhr. Keine produktiven Daten oder echten Providercalls. + +| ID | Prüfung | Erwartung | +|---|---|---| +| PW-01 | Doppelte Placeholder-/Handler-ID, unbekannter Resolver-/ResultSpec-Typ | Betroffenes Modul/Publish geschlossen; kein stilles Überschreiben | +| PW-02 | Picker, Validator, Renderer und Export für denselben Key | Gleiche Revision/Metadaten; kein separater Parallelkatalog | +| PW-03 | Unbekannter Key, Modifier, kaputte Tokenklammer oder überschrittene Grenze | Statischer Fehler; Providerfake zählt null Sends | +| PW-04 | `d`, `x`, `d,x`; `x` ohne benötigten Messwert | Exakte Mitaisemantik; reines `x` löst keine persönlichen Werte auf | +| PW-05 | `0`, `false`, erlaubtes JSON-null, leerer Wert vs. missing | Werte bleiben typgetreu; nur echte Fehlwerte lösen Missingpolicy aus | +| PW-06 | Resolverexception, SQLfehler oder verweigerte Quelle bei optionalem Binding | Abbruch mit sicherem Code; keine Umwandlung in missing/Leertext | +| PW-07 | Nutzerdaten enthalten `{{secret}}`, Templatekonstrukte und HTML | Einmaliges Ersetzen, keine zweite Auflösung/Codeausführung; sichere Darstellung | +| PW-08 | Versuchte `profile_id`-/Owner-/Scope-/Variableninjektion | DTO verweigert oder Auflösung ignoriert Autoritätsanspruch; kein Fremdzugriff | +| PW-09 | Aggregat ändert sich durch Insert/Delete bei gleichem `max(updated_at)` | Verlässlicher Quellenrevisionsadapter erkennt Konflikt; kein Dispatch | +| PW-10 | Mehrere Quellabfragen bei konkurrierendem Write | Konsistenter Snapshot oder klarer Konflikt; keine Mischversion | +| PW-11 | Doppelte Node-/Edge-ID, dangling Edge, Zyklus, unerreichbare Node, kein Endpfad | Publish verweigert, keine aus Dictüberschreibung abgeleitete Gültigkeit | +| PW-12 | Falsche Ports/Knotenfelder, mehrere Enden, Mehrfacheingang ohne Join | Striktes Schema/Compiler verweigert; Importadapter meldet inkompatibel | +| PW-13 | Erforderliche Referenz auf nur bedingt verfügbaren/vorwärtsliegenden Output | Dominanz-/Abhängigkeitsprüfung verweigert; optionaler Vertrag explizit nötig | +| PW-14 | Gleicher Graph mit geänderter Arrayreihenfolge und mehreren bereiten Pfaden | Gleiche kanonische Reihenfolge/Routing-/Joinergebnisse | +| PW-15 | Nicht aktiver Branch mit nachfolgendem Join | Persistenter Skip und entschiedene Kanten; keine vorzeitige BFS-Ausführung | +| PW-16 | Normalisierung exakter/Synonym-/mehrdeutiger Werte, falsche Typen | Nur eindeutige registrierte Normalisierung; unsicher bleibt unknown; bool nicht Zahl | +| PW-17 | Dreiwertlogik inkl. NOT/AND/OR und fehlender uncertain-Kante | Definierte Wahrheitstabelle; Pause statt stiller Elsepfad | +| PW-18 | wait_all, wait_any, best_effort, alle Pfade inaktiv, min_paths | Dokumentierte Coverage; kein leeres completed oder zufälliger Sieger | +| PW-19 | Optionaler Fachfehler gegenüber Auth-/Privacy-/Unknownfehler im Join | Nur publizierter Fachfehler auslassbar; Sicherheits-/Unknownfall stoppt | +| PW-20 | Aktivierung neuer Prompt-/Workflowrevision während laufender Execution | Alter Lauf bleibt vollständig gebunden, neuer Start nimmt neue Revision | +| PW-21 | In-place-Änderung/Revisionslöschung oder unbekannte Compiler-/Handlerrevision | DB-/Servicevertrag verhindert Änderung bzw. blockiert Ausführung | +| PW-22 | Gleicher Startkey gleichzeitig, gleicher/anderer Input, aktiver Pointerwechsel | Genau eine Execution; Wiederabruf oder 409; keine neue Bindung für bestehenden Key | +| PW-23 | Fremdes Subject/Club versucht Status, Preview, Output, Cancel, Resume | 404/403 nach Vertrag; keine Existenz-/Wert-/Progresslecks | +| PW-24 | Operator mit Publishrecht liest private Execution ohne Fachrecht | Verweigert; MFA/Betreiberstatus erteilt kein Privatrecht | +| PW-25 | Sessionexpiry/Rotation während Queue/Nodeawait; frischer gleicher Owner resumiert | paused_auth, legitimer Rebind ohne neue Call-ID und ohne verlängerte Sessionaktivität | +| PW-26 | Logout, Disable, Membership-/Capabilityentzug während Ausführung | Kein nächster Dispatch; T3/Lesen verweigert; keine automatische Wiederbelebung | +| PW-27 | Zwei Worker claimen denselben Lauf, Heartbeatverlust, alter Fence schreibt | Ein gültiger Claim; alter CAS/Checkpoint zurückgewiesen | +| PW-28 | Alter Dispatchpermit und neuer Claim konkurrieren | Ledger-CAS verhindert zweiten Send; verbleibende Netzwerkgrenze sichtbar | +| PW-29 | Crash nach Startcommit, nach Call-ID, vor Dispatchintent | Wiederaufnahme derselben Execution/Node/Call-ID; bislang unversendete Arbeit darf fortfahren | +| PW-30 | Crash nach Dispatchintent, nach Send oder vor T3commit | paused_unknown, exakt kein automatischer zweiter Modellsend | +| PW-31 | Crash nach T3commit vor Gatewayrückgabe | Resultref und Nodecheckpoint gemeinsam vorhanden; kein erneuter Send | +| PW-32 | Output-, Edge-, Event-, Ledger- oder Auditwrite schlägt in T3 fehl | Gesamter Ergebniscommit rollt zurück; kein falscher Node-/Lauferfolg | +| PW-33 | Cancel vor T2, direkt danach und nach Antwort vor T3 | Vor T2 kein Send; danach möglicher Verbrauch, aber keine freigegebene verspätete Ausgabe | +| PW-34 | Ungültiges JSON, fremde Felder, unerlaubte Signale, Refusal | Gateway-/ResultSpecfehler, kein reparierender Modellcall | +| PW-35 | Klartextname/Token/Injection aus Vorgängerausgabe wird Input nächster Node | Vollständiger neuer Gatewaydurchlauf; keine Umgehung über „bereits geprüft“ | +| PW-36 | Ergebnis nur in RAM oder durch Retention gelöscht | result_unavailable, kein versteckter Generate beim GET/Resume | +| PW-37 | Callbudget, Queue-, Byte-, Logik-, Zeitlimit und wiederholte Resumeversuche | Grenzen auch nach Crash/Pause wirksam; engeres Gatewaylimit bleibt bestehen | +| PW-38 | Unknown/Cancel und Usageadapter | Keine unberechtigte Freigabe von Reservierung; mark_unknown statt Nullverbrauch | +| PW-39 | Quellen-/Policyänderung zwischen Rendering, T2 und T3 | Bindung erneut geprüft; kein stilles Rebase oder alter Privacy-Bypass | +| PW-40 | Logs, Fehler, Event-/Status-DTO, Telemetrie mit eindeutigen Canarywerten | Keine privaten Input-/Prompt-/Output-/Cookie-/Keywerte enthalten | +| PW-41 | Scopewechsel im Frontend bei verspätetem Erfolg/401/Fehler | Alte Epoch komplett verworfen; kein Fremdraumresultat/ungewollter Logout | +| PW-42 | Missing CSRF/Origin, fremde Sessiongeneration, ungeprüfter Principal-IDadapter | Geschlossene Browser-/interne Grenze; kein Start/Resume/Providercall | +| PW-43 | Restore mit alten Sessions, Leases und dispatching-Calls | Sessioninvalidierung; kein automatisches Aufwecken/Replay; Kontext neu autorisieren | +| PW-44 | Cleanup eines ungeklärten/referenzierten Calls und verlorener HMAC-Key | Minimalbindung bleibt gesperrt; keine neue freie Ausführung | +| PW-45 | API-/Runnerimport ohne DB-/Providerverfügbarkeit | Keine Importnebenwirkung; getrennt kontrollierte Readiness bleibt geschlossen | + +DB-Konkurrenz-, Fence-, Snapshot-, FK-, Idempotenz- und Rollbackprüfungen laufen später gegen isoliertes echtes PostgreSQL mit dem Foundationtreiber; SQLite oder alleinige In-Memory-Fakes reichen dafür nicht. Netzwerkadapter als Fake mit sichtbaren Sendzählern und präzisen Crashbarrieren; Transportunsicherheit realistisch simulieren, keine echten Tokens/Providerzugänge. Frontendtests kontrollieren Scopeepoch und Cacheverhalten. Testberichte benennen Fall-IDs, Revision, Umgebung und Ergebnis; übersprungene Tests belegen keine Konformität. + +Vorhandene Testquellen I dienen als Startpunkt: Mitai [Graphvalidierung](C:/Dev/mitai-jinkendo/tests/backend/test_workflow_engine.py:86), [Executor/Aggregation](C:/Dev/mitai-jinkendo/tests/backend/test_phase2_workflow_executor.py:14), [Branching/Fallback](C:/Dev/mitai-jinkendo/tests/backend/test_phase3_workflow_branching.py:40), [Modifier](C:/Dev/mitai-jinkendo/backend/tests/test_placeholder_modifier_d.py:13) und [Metadatentypen/Herkunft](C:/Dev/mitai-jinkendo/backend/tests/test_placeholder_metadata_v2.py:29). Vor Übernahme tatsächliche Assertions und Fixtureabhängigkeiten prüfen. Namen/Existenz belegen weder die neue Semantik noch einen bestandenen Lauf; in dieser Lieferung werden sie nicht ausgeführt. + +## 17. Implementierungsanweisung für Cursor + +Der spätere Auftrag benennt ein Zielprodukt und dessen benötigten ersten Fachfall. Die folgenden Schritte bilden die vollständige Reihenfolge, ohne jetzt Produktänderungen zu beauftragen: + +1. **Verträge anschließen.** Foundation v0.3, Phase-3.3-Auth und KI-Gatewayports prüfen; konkrete lokale Account-/Scope-/Quellen-IDtypen verwenden. Benötigte Module explizit registrieren. Bei fehlendem Auth-/Quellen-/Privacyadapter geschlossen bleiben; kein Dev-Bypass und keine Ersatz-Serviceidentität. +2. **Mitai-Kern adaptieren.** Registry-/Metadatenvertrag, Tokenmodifier, Graphprüfung, Signale und deklarative Logik aus den benannten Quellen isoliert portieren. Legacycallback, Debugvolltexte, permissive Typen und In-Memory-Dauerzustand gezielt ersetzen. Keine parallele neue Promptengine neben dem adaptierten Kern. +3. **Reine Definitionsebene bauen.** Strikte diskriminierte Node-DTOs, immutable Revisionen, Compiler/Tokenplan, Referenz-/Dominanz-/Größenprüfung und eingefrorene Registries. Zuerst PW-01 bis PW-07 sowie PW-11 bis PW-21 mit synthetischen Inputs prüfen. +4. **Lokale Persistenz ergänzen.** Explizite SQLmigrationen und scoped Repositories für die wirklich benötigten Tabellen; Definitions-FKs, Node-/Edgezustände, Idempotenz, HMAC-Keybindung, CAS/Fence und Audit. Migrationen nur im isolierten Qualifikationssystem ausführen. Kein Produkt-DBzugriff aus diesem Blueprintauftrag. +5. **Einen Fachresolver integrieren.** Bestehenden Data Layer und berechtigten Profil-/Clubbezug verwenden; nur benötigte Felder; belastbare SourceBindings auch für Aggregatänderungen. Snapshot-/Missing-/Typ-/Fremdzugriffstests vor echten Modellaufrufen fertigstellen. +6. **Ausführung ohne Provider qualifizieren.** Deterministischer sequenzieller Scheduler, Joins/Skip/Coverage, private Outputs, Start-/Cancel-/Resume-APIs; Runnerprozess aus demselben Image. DB- und Konkurrenzprüfungen mit kontrollierter Uhr und zwei Fences. +7. **Gateway atomar verbinden.** Ein Analysisnode über unverändertes `complete` und internen `WorkflowResultSink`; ResultSpec tatsächlich validieren. Stable IDs und T3checkpoint in derselben UoW. Crashbarrieren vor/nach Dispatch und Commit, null automatische Modellretries. Die ganze Kette zunächst mit Fakegateway/-transport prüfen. +8. **Auth, Privacy und UI nachweisen.** Sessionpause/Rebind, Widerruf, Quelle/Policyänderung, privater Preview, neue Privacyprüfung je Nachfolgenode, Scopeepoch, no-store, Logs und Löschung. Ungeklärte Ausführung bleibt sichtbar ungeklärt. Erst danach erlaubte zusätzliche Graphformen/Fachresolver ergänzen. +9. **Betrieb einbinden.** Runner als Writer in Drain/Shutdown/Restore behandeln: keine neuen Claims, aktuelle lokale Arbeit begrenzt beenden/abbrechen, Leases/Calls konservativ hinterlassen. Wiederhergestellte offene Läufe werden vor einem nächsten Dispatch unter aktueller Session-/Rechtebindung geprüft; alte Sessions/Claims dürfen nichts wiederbeleben. Beide ADR-11-Releasevarianten behalten Pflicht-Gates und menschliche Produktionsfreigabe. +10. **Nachweis abliefern und stoppen.** Betroffene Prüffälle, Source-/Buildversion, tatsächlich ausgeführte Ergebnisse und verbleibende K-Punkte dokumentieren. Keine Migration bestehender Anwendungen, kein Produktivrollout und kein familienweites Paket ohne eigenen konkreten Auftrag. Der nächste Entitlements-/Usage-/Quota-Blueprint wird hier nicht implementiert. + +Abnahme des ersten implementierten Fachfalls verlangt die End-to-End-Kette **gültige Session + Scope → konkrete immutable Definition → autorisierter Snapshot → einmaliges Rendering → Gateway → atomarer Nodecheckpoint → typisiertes Ergebnis**, einschließlich negativem Fremdzugriff, Widerruf, Cancel und Crash nach möglichem Versand. Ein erfolgreicher Demo-Prompt oder ein Unit-Test der Topologiesortierung genügt nicht. + +## 18. Prüfstand dieser Lieferung + +Diese Lieferung enthält ausschließlich dieses Dokument. Es wurden gezielt die bereits registrierten Mechanismen gelesen; keine vollständige Repository-Neuanalyse, keine Änderungen an Produktrepositories, keine neuen ADRs und keine neue Produktreifebewertung. Es gab keine Provideranfragen, produktiven Datenbankzugriffe, Implementierung, Deploymentänderungen oder umfassenden Testläufe in Bestandsanwendungen. + +**T – mechanischer Dokumentcheck am 16.10.2026:** 41 lokale Dateiverweise einschließlich angegebener Zeilen auf Existenz/Gültigkeit geprüft; drei Pythonbeispiele erfolgreich als AST geparst; 45 eindeutige und lückenlos nummerierte Prüfspezifikationen erfasst; 22 Quellhashes gegen die Dateien geprüft. Alle 46 zur Kontrolle erfassten Bestandsdateien waren gegenüber dem vor Erstellung aufgenommenen Stand unverändert. Das Ergebnisverzeichnis enthält genau dieses eine Markdowndokument. Kein Pythonbeispiel wurde als Anwendung ausgeführt; insbesondere wurden die 45 Sicherheitsszenarien nicht implementiert oder ausgeführt. Die Quellhashes unten sind weder Test- noch Reifebeweis. + +### 18.1 Lokaler Quellstand + +SHA-256 der gezielt verwendeten Implementierungs- und Testquellen. Pfade sind zusätzlich in Abschnitt 2/16 verlinkt; bestehende Testquellen wurden nicht ausgeführt. + +| Quelle relativ zu `C:/Dev` | SHA-256 | +|---|---| +| `mitai-jinkendo/backend/workflow_models.py` | `824d481c2b29a6f43edff4e04c675626b0a117621d929dc947fa269e3ad4840a` | +| `mitai-jinkendo/backend/workflow_engine.py` | `482c2b6bb95928476b7db75966026e50b54518402e3daf1f846fd6fd3c910d18` | +| `mitai-jinkendo/backend/workflow_executor.py` | `7877bbbfa2374910f97575d2817f59e9b6d3f8f58a7169692f84a8ca1fecec47` | +| `mitai-jinkendo/backend/placeholder_registry.py` | `b554bf003ad9954ac60a4edaa728b7fa92e2bcb986efc51ec4a231cc3e76d021` | +| `mitai-jinkendo/backend/placeholder_resolver.py` | `c87f7262819a1340380b75f6232d7bebbb2a0ae36809f2756b696a37a36e74ae` | +| `mitai-jinkendo/backend/prompt_executor.py` | `7e0e97047fe16d7b5efb92ccbe573b6459c4d32b41931aa9e33d6f00f14028da` | +| `mitai-jinkendo/backend/placeholder_registrations/_evidence.py` | `17e613a280befad298c0c87e5a1cf9be3134a00702e31bc4bdc3df7dca5dd387` | +| `mitai-jinkendo/backend/placeholder_registrations/__init__.py` | `9887a72b65a110f91380e1a003d927704790202496cf6b7b469196154fae1c70` | +| `mitai-jinkendo/backend/normalization_engine.py` | `5d112dd55557d0f7767a64be217c1511e97ea06921c4ab530d8c9d2f888cdece` | +| `mitai-jinkendo/backend/logic_evaluator.py` | `bd7fc9cfb46d78a31d427ab7c274226f303b27015890eb9870e8f347d6ce5cf3` | +| `mitai-jinkendo/backend/join_evaluator.py` | `36c085ae87cddd4334bb0b464257b771e7a0e6a9b94ceda465435ea112ed6081` | +| `mitai-jinkendo/tests/backend/test_workflow_engine.py` | `7cc274960b5eeab351768eb823d9bbdf3e5c633d10f4f52f75a8aaf929db1ab5` | +| `mitai-jinkendo/tests/backend/test_phase2_workflow_executor.py` | `6d4e82220350b7d0ae03da54dd16c93163272e5fdeea25ebdd1667fe0200d0fd` | +| `mitai-jinkendo/tests/backend/test_phase3_workflow_branching.py` | `15be1726334cf45d6f6f26908b37477991b25a9e9ccd829fc05686837e02a46d` | +| `mitai-jinkendo/backend/tests/test_placeholder_modifier_d.py` | `e26b1e4ce07ac4541ced6c3dc1b6cbec17502cd7f65d2451f5553bba48e5da84` | +| `mitai-jinkendo/backend/tests/test_placeholder_metadata_v2.py` | `4a1ef9342f5ab18bfa42b3549b56fcaf8a7fc085554e3ded2761626500ebeb65` | +| `mitai-jinkendo/.claude/docs/technical/PLACEHOLDER_REGISTRY_FRAMEWORK.md` | `aeee694cb0612ff44cc86d2133ce2883acdfaa9d6b8cffdaa101016c1b51ffa2` | +| `mitai-jinkendo/.claude/docs/audit/platzhalter/PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md` | `6cd5f2963e9dc92ecd07cedaf9c6b2bb01fc55c6260475c3c0c3f4f6e9e5c8f0` | +| `shinkan-jinkendo/backend/ai_prompt_job.py` | `64a11272e814ad4372e709d91057af423b668a94f152b5d88f772ea58cc1d9ab` | +| `shinkan-jinkendo/backend/ai_prompt_context.py` | `04bcfd13cef2c04b2d3e3bbc0275cc86ca7584490e8c00cb93c21ceb9f7bb79d` | +| `shinkan-jinkendo/backend/ai_prompt_runtime.py` | `b1154e2bf30feb25ee9b9d743c98d946f943542a63fe58a7d6748d43be09d24d` | +| `kairo-jinkendo/backend/prompt_validation.py` | `359379291badc51b67bd85124b905540ecb332f2fd4c93036da455dbe14662a8` | + + diff --git a/docs/reference/Jinkendo_Release_Betrieb_Recovery_Blueprint.md b/docs/reference/Jinkendo_Release_Betrieb_Recovery_Blueprint.md new file mode 100644 index 0000000..d5b0b42 --- /dev/null +++ b/docs/reference/Jinkendo_Release_Betrieb_Recovery_Blueprint.md @@ -0,0 +1,612 @@ +# Jinkendo – Release, Betrieb & Recovery Blueprint + +**v0.1 · 16.10.2026 · Spezial-Blueprint nach Phase 3.3 · keine Implementierung oder Betriebsfreigabe** + +## 1. Auftrag, Grundlage und Nachweis + +Dieser Blueprint konkretisiert den Weg vom qualifizierten Quellstand bis zum nachvollziehbaren Produktionsbetrieb und zur Wiederherstellung nach einem Fehler. Er ist ein Implementierungsauftrag für Cursor im später ausdrücklich benannten Zielrepository. In dieser Lieferung werden ausschließlich Dokumente erstellt. Bestehende Anwendungen, Gitea-Einstellungen, Runner, Server, Datenbanken und Sicherungen bleiben unverändert. + +Grundlagen sind [Referenzarchitektur A v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md), [Foundation B v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md), [Entscheidungen C v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md) und der [Auth-/Session-/Scope-Blueprint](C:/Dev/jinkendo-phase3-3-auth-session-scope-blueprint-2026-10-16/Jinkendo_Auth_Session_Scope_Blueprint.md). Die beschlossenen ADR-01 bis ADR-14 bleiben maßgeblich, insbesondere ADR-06/07/11/12/14. Es entstehen keine zusätzlichen ADRs, zentralen Dienste oder neuen Freigabegremien. + +**Nachweis:** V = vorgeschlagene technische Ausgestaltung; I = vorhandene statisch nachgelesene Implementierungsreferenz; T = tatsächlich bestandener Test mit Umfang, Stand und Umgebung; K = noch nicht integrierte/getestete Kombination. Dieser Blueprint und seine Beispiele sind **V/K**. Quellenverweise sind I. Tests, Release-Gates, Backups und Restores wurden hier nicht ausgeführt; kein T-Nachweis und keine Produktionsreife werden behauptet. + +Der bestehende Ablauf bleibt: + +```text +develop → Development → Tests → bewusste menschliche Freigabe → main + → konkreten Produktionskandidaten prüfen → Produktion → Read-only-Smoke +``` + +**R1 – Build once, deploy many** ist bevorzugt. **R2 – kontrollierte reproduzierbare getrennte Builds für Dev/Prod** bleibt nach ADR-11 zulässig. Beide benötigen vor Produktionsumschaltung vollständige Pflicht-Gates und eine eindeutige Zuordnung von Quellstand, Build, Freigabe und tatsächlich eingesetzten Artefakten. Die menschliche Annahme des Release-PR bleibt die Produktionsfreigabe; R2 erzeugt keine zweite menschliche Freigabeschleife. + +### 1.1 Verbindliche Verträge und technische Defaults + +| Verbindlich | Bevorzugter, begründet anpassbarer Default | +|---|---| +| Produktionsversion ist qualifiziert, freigegeben und eindeutig identifizierbar | Docker-Image-Archive mit SHA-256, Image-ID und Plattform; bestehende OCI-Registry ist Alternative | +| Keine synthetischen Mutationstests gegen Live-Dev-/Prod-Daten; kein Erfolg durch fehlende/skippende Pflichtsuiten | Kurzlebiges eigenes Compose-Projekt, PostgreSQL-Instanz und Testnetz je Run | +| Runtime ohne DDL/Owner-/Superuser-/BYPASSRLS-Rechte; Migration separat und nachweisbar | Bestehender SQL-Runnervertrag der Foundation, Migrationen vor Prozessumschaltung | +| Release, Backup und Restore dürfen dieselbe Datenbasis nicht konkurrierend verändern | Ein Deployhost je Produkt/Umgebung; gemeinsamer lokaler `flock`, persistentes Operationsjournal | +| DB und Medien eines Backups bilden einen definierten konsistenten Wiederherstellungspunkt | Kurzes Wartungsfenster, alle Writer stoppen/drainen, DB-Dump und Medienkopie einfrieren | +| Persönliche Sicherungen geschützt, wiederherstellbar und von Hostverlust unabhängig verfügbar | `age`-verschlüsseltes Archiv, verifizierte Kopie auf getrenntem vorhandenen Gerät/Host, Schlüssel getrennt | +| Restore aktiviert keine alten Sessions oder ungeprüft zurückgerollten Rechte | Neue Ziel-DB/Mediengeneration, Security-Nachbehandlung und zunächst gesperrte restaurierte Konten | +| RPO/RTO und Aufbewahrung sind explizit; Erreichbarkeit wird durch Übungen belegt | Startprofil: RPO 24 h, RTO 4 h; Sicherung alle zwölf Stunden; 7 tägliche + 4 wöchentliche + 3 monatliche Stände | + +Die Zahlen sind Planungsdefaults, keine gemessenen Zusagen. Sie müssen vor dem ersten externen datenverändernden Betrieb im Produktprofil ausdrücklich gewählt und mit gemessener Restorezeit/Backupabständen abgeglichen sein. Eine lokale Begründung genügt; keine neue Familienfreigabe. Quellenpfade, Modulnamen, Tooladapter und Zeitbudgets können angepasst werden, ohne Schutz- oder Releaseverträge abzuschwächen. Dieser Entwurf verlangt weder Kubernetes, neue Registry, neuen Runnerdienst, zentrales Monitoring noch einen Backupserver. + +## 2. Gezielte Referenzen und Übernahmegrenzen + +Verwendet wurden das [Phase-3.1-Wissensregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json), dessen [Quellenregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/sources.json) und die folgenden ausgewählten Dateien. Es gab keine vollständige Repository-Neuanalyse oder erneute Produktreifebewertung. + +| Referenz I | Übernehmen | Im Zielaufbau gezielt ändern V/K | +|---|---|---| +| Shinkan KI-SHK-12, [Security-Runner](C:/Dev/shinkan-jinkendo/backend/scripts/security_release_checks.py:17), [Testworkflow](C:/Dev/shinkan-jinkendo/.gitea/workflows/test.yml:15) | Explizite Securitysuite und propagierter Testexitcode | Keine Paketinstallation/Mutationstests im laufenden Kunden-/Dev-Container; exakte Testfall- und Artefaktzuordnung | +| Shinkan KI-SHK-13, [Produktionsworkflow](C:/Dev/shinkan-jinkendo/.gitea/workflows/deploy-prod.yml:11) | Bestehende Branch-/Compose-/Smoke-Aufteilung | Kein ungeprüftes `build --no-cache → up`; Gate vor Umschaltung, Laufzeit-/Imageidentität, kontrollierte Migration | +| Kairo KI-KAI-16, [isolierter PR-Stack](C:/Dev/kairo-jinkendo/.gitea/workflows/test.yml:96), [Dev-Deploy](C:/Dev/kairo-jinkendo/.gitea/workflows/deploy-dev.yml:26) | Eigener Teststack und Backend-/Frontend-Smoke | Projektnamen/Ports je Run statt fester Namen; garantiertes Cleanup auch bei Fehlern; unveränderte Images testen; keine parallelen Push-/Deployläufe als Zuordnungsbeweis | +| Kanshō KI-KAN-14, [Testtrennung](C:/Dev/Kansho/.gitea/workflows/test.yml:36) | Testdaten von Live-Dev unterscheiden, Providerkeys nicht für Tests verwenden, Live-Smoke read-only | Eigene kurzlebige PostgreSQL-Instanz statt fester DB auf Dev-Postgres; Schutz vor falschem Ziel und parallelen Läufen | +| Mitai KI-MIT-20, [Custom-Dump](C:/Dev/mitai-jinkendo/scripts/backup/mitai_pg_dump.sh:24) | `pg_dump -Fc`, Owner-/ACL-unabhängiger Dump | Explizites Ziel ohne Produktionsdefault, Medienkonsistenz, Verschlüsselung, externe Kopie, Wiederherstellung in neue DB statt `--clean` auf Live-DB | +| Kanshō KI-KAN-20, [Backupmanifest](C:/Dev/Kansho/backend/local_backup.py:170), [Archivprüfung](C:/Dev/Kansho/backend/local_backup.py:221), [Restore](C:/Dev/Kansho/backend/local_backup.py:275) | Manifest, Prüfsummen, Formatversion und Sicherheitskopie vor Ersatz | SQLite bleibt lokale Produktvariante. PostgreSQL-Pfad separat; Archive nicht unverschlüsselt verteilen; Pfad-/Größenprüfung vor Extraktion; DB-/Medienwechsel nicht als dateisystemübergreifend atomar behaupten | +| Kanshō KI-KAN-21, [PG-Skript](C:/Dev/Kansho/scripts/backup-postgres.sh:23) | Vorhandener PostgreSQL-Betriebsweg | Die gesonderte Medienkopie wird in einen gemeinsamen Konsistenz-/Backupzustand eingebunden | + +Kanshōs [Runtime-Dokument](C:/Dev/Kansho/docs/architecture/technical/runtime_and_deploy.md:74) beschreibt lokale Entscheidungen und historische Transferwege. Daraus folgt weder ein familienweiter Produktionspfad noch die Erlaubnis, persönliche Sicherungen generell in Git abzulegen. Für diesen Neuaufbau gilt der explizite Foundation-Migrations-/Releasevertrag. Die vorhandenen Produkte erhalten keinen automatischen Umbauauftrag. + +## 3. Komponentenschnitt und Zuständigkeiten + +```text +Gitea qualification → isolierter Image-Teststack → geschützte Releaseablage +Release-PR auf main → menschlicher Merge → Production-Workflow + → vertrauenswürdiger ReleaseController auf bestehendem Deployhost + → Provenienz-/Gateprüfung → Hostlock → Backup/Migration → Compose + → Read-only-Smoke → DeploymentReceipt + +Vorhandener Scheduler / explizite CLI → BackupController → verschlüsselte Kopien +Explizite Recovery-CLI → RestoreController → neue DB/Medien → Prüfung → Umschaltung +``` + +| Baustein | Verantwortung | +|---|---| +| `scripts/ci/qualify` | Isolierten Run aufbauen, Artefakte testen, JUnit-/Browsernachweise und Pflichtfallabdeckung auswerten | +| `ops/contracts.py`, `ops/manifest.py` | Strikte versionierte Metadaten, Hash-/Datei-/ID-Validierung; keine Secrets | +| `ops/gitea.py` | Tatsächliche Server-/Runnerfähigkeiten und vertrauenswürdige Run-/Commit-/Mergebelege lesen; versionspassender Adapter | +| `ops/release.py` | R1/R2-Kandidat verifizieren, Releasezustandsautomat und Deployment koordinieren | +| `ops/host.py` | Registrierte lokale Profile, Lock, Journal, Wartung, Writerkontrolle, atomare Zeigerdateien | +| `ops/backup.py`, `ops/restore.py` | Gemeinsame DB-/Mediensicherung, sichere Verschlüsselung/Kopie, Wiederherstellung in neue Generation | +| `ops/postgres.py` | Identitätsprüfung, expliziter Foundation-Migrationsaufruf, `pg_dump`/`pg_restore`, Rollen-/Schema-/Integritätsprüfung | +| `ops/health.py` | Kurze begrenzte Read-only-Smokes; sichere Meldung von Revision/Readiness | +| Produktadapter | Tatsächliche Writer, Medienreferenzen, Schlüsselreferenzen, Restore-Securityhooks und fachliche Integrität liefern | + +Dies sind produktlokale Werkzeuge/Module, keine Web-Verwaltungs-API und kein neuer Plattformdienst. Linux auf dem vorhandenen Deployhost ist der Betriebsdefault; Windows kann Dokumente/Code bearbeiten. Die folgenden Betriebsbefehle werden hier nicht ausgeführt. + +Der privilegierte Controller und seine Profil-/Vertrauenskonfiguration liegen auf dem Host in einem versionierten, gegen Änderung durch untrusted Jobs geschützten Werkzeugverzeichnis. Sein getesteter Stand wird im Operationsjournal festgehalten. Er führt keine beliebigen Shellskripte aus eingereichten PR-Artefakten mit Produktionsrechten aus. Produktmigrationen laufen ausschließlich als freigegebene SQL-Dateien unter der begrenzten Migrationsrolle. Eine spätere Controlleränderung wird selbst getestet/versioniert und bewusst über den bestehenden administrativen Betriebsweg bereitgestellt. + +### 3.1 Rechte und Secrets + +| Identität | Darf | Darf nicht | +|---|---|---| +| Untrusted PR-Check | Begrenzte Checks in bereits vorhandener isolierter Ausführung | Prod-/Deploysecrets, Produktionsnetz/Volumes/Dockersocket des Hosts erreichen | +| Vertrauenswürdige Qualification | Ausgewählten geschützten Quellstand bauen/testen, Qualifikationsartefakte schreiben | Prod-DB oder Recovery-Privatschlüssel verwenden | +| Production-Workflow/Controller | Freigegebenen Kandidaten lesen und registrierte Produktoperation ausführen | Beliebigen Upload/Tag ungeprüft deployen oder fremde Produktziele wählen | +| App-Runtime | Begrenzte Fach-DML und Health | Migration/DDL, Backupschlüssel, Dockersteuerung, Betriebskonfiguration ändern | +| Migration/Restore | Benannte Produkt-DB/schema besitzen/verändern; keine fremden DBs | Credentials dem Backend dauerhaft hinterlassen | +| Backup | Vollständigen eigenen Datenbestand lesen und auf erlaubtes Ziel verschlüsseln | App-Secrets/Entschlüsselungsschlüssel als Archivinhalt einsammeln | +| Recoveryoperator | Separat bereitgestellte Entschlüsselungs-/Faktorschlüssel verwenden und geplanten Restore ausführen | Diese Schlüssel in CI-Logs oder Runtimeimages ablegen | + +Wenn der vorhandene Runner Fremdcode nicht sicher vom Produktionshost trennen kann, laufen dort keine untrusted PR-Ausführungen mit Hostrechten. Vorhandene isolierte Ausführung verwenden oder vollständige Qualifikation erst auf dem ausdrücklich vertrauenswürdigen `develop`-Stand ausführen. Fehlende Isolation wird nicht durch einen neuen Runnerdienst in diesem Blueprint kaschiert. `runs-on: ubuntu-latest` allein beweist keine Isolation. + +## 4. Produkt-/Betriebsprofil + +Alle Commands verlangen einen ausdrücklich gewählten Profilpfad; fehlende/ungültige Umgebung bricht ab. Es gibt kein „sonst prod“. Das Profil enthält nur erlaubte Ziele und Secretreferenzen. Beispiel mit fiktiven Werten, V/K: + +```json +{ + "format_version": 1, + "product_id": "demo-product", + "environment": "production", + "host_id": "registered-deploy-host", + "platform": "linux/arm64", + "public_origin": "https://demo.invalid", + "compose_project": "demo-product-prod", + "operations_root": "/srv/jinkendo/demo-product/operations", + "releases_root": "/srv/jinkendo/demo-product/releases", + "media_generations_root": "/srv/jinkendo/demo-product/media", + "database_ref": "product-prod-db", + "database_instance_id": "provisioned-opaque-instance-id", + "writers": ["backend"], + "build_variant": "R1", + "rpo_seconds": 86400, + "rto_seconds": 14400, + "scheduled_backup_seconds": 43200, + "backup_store_ref": "registered-independent-storage", + "backup_recipient_file_ref": "data-backup-recipients", + "secret_recovery_ref": "separate-recovery-material", + "drain_timeout_seconds": 30, + "startup_timeout_seconds": 120, + "lock_wait_seconds": 60 +} +``` + +Pflichtauflösung vor Betrieb: konkretes Repository/Gitea, Host/Plattform, Proxy-/Wartungsschalter, Composeversion, Service-/Writerliste, DB-/Volumeidentitäten, vertrauenswürdige Runner/Workflows, Ablage und unabhängiger Sicherungsspeicher, verfügbare Schlüssel-ID-Referenzen. RPO/RTO werden ausdrücklich übernommen oder begründet geändert. Ein fehlendes Pflichtfeld erzeugt `profile_incomplete`, keinen geratenen Pfad. Alle absoluten Pfade werden vor Move/Extraktion/Cleanup gegen ihre registrierte Wurzel geprüft; Symlinkausbrüche und fremde Mounts sind verboten. + +Einmalige Zielprovisionierung setzt eine zufällige Produkt-/Umgebungs-/Instanz-ID in einer kleinen DB-Identitätstabelle und im geschützten Hostprofil. Commands prüfen beide sowie tatsächlichen DB-Namen/Server/Compose-Labels. Diese Prüfung ergänzt getrennte Zugriffsrechte/Netze; ein selbst gesetztes `APP_ENV` reicht nicht. Restore überschreibt diese Tabelle im neuen Ziel nach dem Einlesen mit dessen bewusst provisionierter Zielidentität. Reale Adressen, Dienste, Secretwerte oder Einstellungen wurden für dieses Dokument nicht abgefragt. + +Bei Erstinstallation ist die erwartete Runtimegeneration ausdrücklich `uninitialized`, die Produkt-DB leer und provisioniert. Es gibt keinen vorigen Image-Rollback; die leere Ausgangs-DB/-Medienwurzel kann als Pre-release-Ausgangspunkt gesichert werden. Erstinstallationsmigration und Erstoperatorweg folgen Foundation/Phase 3.3. Ein fehlender Vorgänger ist nur in diesem verifizierten Fall erlaubt. Der spätere erste externe Datenbetrieb verlangt trotzdem den vorherigen synthetischen Recoverydurchlauf. + +## 5. Artefakte und Nachweisverträge + +### 5.1 Releasepaket + +```text +releases// + release.json # immutable Build-/Quell-/Artefaktmetadaten + runtime/backend.tar # oder vorhandene OCI-Referenz + runtime/frontend.tar + runtime/compose.release.yml # keine build:-Abschnitte/Live-Quellmounts + migrations/ # vollständige bisherige SQL-Folge + reports/qualification.json + reports/junit-*.xml + reports/browser-results.json + reports/schema-compatibility.json +``` + +`release_id`, `build_id`, `run_id` sind begrenzte IDs aus einer Allowlistzeichenmenge; keine Pfade oder frei ausführbaren Werte. Auflösung ausschließlich innerhalb registrierter Roots. Dateipfade im Paket relativ, keine Links/Geräte/absoluten Pfade. Plattform der getesteten Images entspricht dem Ziel; ein x86-Test qualifiziert nicht still ein separat gebautes ARM-Image. + +Erforderliche Felder von `release.json` v1: + +| Gruppe | Inhalt / Prüfung | +|---|---| +| Identität | `format_version`, `product_id`, `release_id`, `build_variant`, `created_at`, `controller_contract_version` | +| Source | Repo-ID, Dev-Commit/Tree, Prod-Commit/Tree, Build-Rezept-/Lockfile-/Basisimagehashes, Plattform/Toolchain, explizite öffentliche Buildparameter | +| Build | Dev-/Prod-Build-ID, je Image Archiv-SHA-256 **und** Docker-Image-ID, alternativ unveränderliche OCI-Digests | +| Gate | Run-IDs, Workflowidentität/-revision, Qualification-Reporthashes, Pflichtspezifikationshash, Policy-/Konfigurationsprofilhash, getestete Plattform | +| Schema | Hash der geordneten Migrationsdateiliste samt Inhalten, erwarteter Ledgerhead/-digest, benötigte Extension-/DB-Versionslinie | +| Wiederanlauf | Voriges Artefaktpaar, Schema-Kompatibilitätsnachweis oder ausdrückliche Kennzeichnung „kein Image-Rollback qualifiziert“ | + +Das Manifest enthält keinen eigenen Hash. Sein SHA-256 wird im vertrauenswürdigen Ablageindex/Deploymentjournal referenziert. Der spätere Freigabe-/Mergebeleg ist ein separater `approval-proof.json`/vertrauenswürdiger Lookup, damit ein vor dem Merge erzeugtes R1-Paket nachträglich nicht verändert werden muss. Kein Secret, Cookie, persönliches Testdatum oder Providerprompt im Manifest. + +SHA-256 schützt gegen versehentliche Änderung, belegt allein aber keine Herkunft. Der Controller nimmt Nachweise nur vom passenden geschützten Gitea-Run oder aus einer ausschließlich durch die vertrauenswürdige Qualification beschreibbaren lokalen Ablage an. Beliebig hochgeladenes Manifest plus passende selbst berechnete Hashes genügen nicht. Controller/Profil legen erlaubte Repo-, Workflow-, Run- und Herausgeberidentitäten fest. Eine Registry oder Signaturinfrastruktur muss dafür nicht neu eingeführt werden. + +Docker-Archivhash, Image-ID und OCI-Digest sind unterschiedliche Kennungen. Beim Archivweg: Archivhash vor Load prüfen, danach geladene Image-ID/Plattform und schließlich `container.Image` prüfen. Ein eindeutiger lokaler Releasetag dient nur zur Composeadressierung. Er wird vor und nach Start gegen die erwartete Image-ID aufgelöst; bewegbares `latest` ist kein Nachweis. [Docker image save](https://docs.docker.com/reference/cli/docker/image/save/) beschreibt den vorhandenen Archivtransport. + +### 5.2 Qualifikationsbericht und Deploymentbeleg + +`qualification.json` v1 enthält: Produkt, Build-ID, vollständige Image-/Sourcezuordnung, Environment=`test`, Test-Run-ID, Start/Ende, Toolversionen, Pflichtfallliste/-hash, je Fall stabilen Namen/Parameter, Status und Suite, Collectionzählung, Failed/Error/Skipped/XFail-Zähler sowie Hashes der Rohberichte. Ein erfolgreicher Gesamt-Exitcode ohne erforderliche Einzeltests reicht nicht. Ein Pflichtfall muss tatsächlich `passed` sein; skip/xfail/unerwartetes xpass gelten nicht als Erfüllung. Manifest und Berichte sind zusammen unveränderlich aufbewahrt. + +`deployment-receipt.json` entsteht nach erfolgreichem Umschalten: Host-/Profilhash, Release-/Manifest-ID, freigegebener Main-Commit und Merge-/Menschbeleg, konkrete Quell-/Build-/Image-IDs, vorheriger Release, Preflight-/Backup-/Migrationsreferenz, tatsächlicher Ledgerstand, Controllerrevision, Wartungs-/Umschaltzeiten, tatsächliche Container-Image-IDs und sichere Smokeergebnisse. Ein fehlgeschlagener Lauf erhält einen Fehlerbeleg mit letzter sicherer Phase; er wird nicht als Deploymenterfolg ausgegeben. + +Das lokale Operationsjournal lebt außerhalb der App-DB, damit ein DB-Restore den neuesten Betriebszustand nicht zurückdreht. Pro Operation immutable ID und Phase, Ergebnis, sichere Reasoncodes; Updates atomar via temporärer Datei, `fsync`, `os.replace` und Verzeichnissynchronisierung. Lokale Journalrotation/geschützte unabhängige Kopie erhalten den benötigten Wiederanlaufstand; keine Zugangsdaten oder personenbezogenen Bodies. + +## 6. R1/R2, menschliche Freigabe und Gitea-Anbindung + +| Schritt | R1: bevorzugt | R2: zulässig | +|---|---|---| +| Dev-Kandidat | Aus eindeutigem geschütztem Commit mit gelockten Inputs bauen; immutable Images identifizieren | Eigener eindeutig identifizierter Dev-Build mit gelockten Inputs | +| Development/Test | Genau diese Images in Dev bereitstellen und separat im isolierten Stack qualifizieren | Dev-Build ebenso qualifizieren | +| Menschliche Freigabe | Release-PR nach erfolgreicher Dev-Qualifikation bewusst nach `main` übernehmen | Gleiche Freigabe; deklarierte Prod-Buildinputs dazugehören | +| Prod-Kandidat | Qualifizierte Images wiederverwenden; Main-/Treebeziehung beweisen | Aus dem freigegebenen Stand separat kontrolliert bauen; tatsächlichen Prod-Build vollständig qualifizieren | +| Gate vor Prod | Vertrauenswürdige Reports, Hashes, Quell-/Mainbeziehung und Betriebsbedingungen prüfen | Dasselbe, einschließlich eigener Prod-Build-/Qualification-ID; unterschiedlicher Dev-/Prod-Hash erlaubt | +| Deployment | Ausschließlich geprüfte Images/Deploymentdefinitionen, kein weiterer Build | Genau den separat qualifizierten Prod-Build, ebenfalls kein weiterer ungeprüfter Build | + +Main-HEAD wird am Start des Vorgangs auf den konkreten freigegebenen Commit festgehalten. Der Controller prüft: zum Produkt gehörender Release-PR, erfolgreiche passende Dev-Qualifikation, tatsächlicher menschlicher Mergeactor aus dem erlaubten Personenkreis und keine ungeprüften Änderungen nach diesem Stand. Git-Commit-Autorname oder ein frei gesetztes Manifestfeld ist kein Menschbeleg. Administratorrechte allein ersetzen diesen normalen Freigabepfad nicht; Direct-Push-/Force-Push-Umgehung ist für normale Releases gesperrt. + +R1-Default: qualifizierter Sourcecommit ist im freigegebenen Main enthalten und die relevanten Source-Trees sind identisch. Abweichende Trees benötigen ausdrücklich die Qualifikation des passenden tatsächlich freigegebenen Kandidaten; sonst Abbruch. R1 erlaubt dabei keinen versteckten Prod-Neubuild: Neu gebaute Produktionsartefakte werden als R2 qualifiziert, oder der passende Dev-Kandidat wird vor Übernahme neu qualifiziert und eindeutig an die bereits erteilte Quellfreigabe gebunden. R2 darf separate Inputs und Artefakte haben, dokumentiert alle Abweichungen und prüft genau den Prod-Kandidaten. Öffentliche Parameter wie Origin sind keine Secrets; bevorzugt bleibt Same-Origin-Laufzeitkonfiguration. Netzwerkzugriffe beim Build sind auf gelockte Abhängigkeiten und gepinnte Basisimages beschränkt. R2 bedeutet kontrollierbar wiederholbarer Aufbau; bitidentische Dev-/Prod-Archive werden nicht verlangt. + +Bei Einführung oder Änderung des Buildrezepts/der Toolchain wird ein Wiederaufbau aus den protokollierten Inputs im isolierten Umfeld geprüft. Abweichungen werden bis zu den Laufzeit-/Assetinhalten erklärt; nichtdeterministische Archiv-/Zeitmetadaten dürfen nicht als unerklärte fachliche Änderung durchgehen. Das verlangt keinen zweiten Build jedes Releases und keine Gleichheit von bewusst unterschiedlich parametrisierten Dev-/Prod-Builds. + +### 6.1 Logische Workflows im bestehenden Gitea + +1. **Qualification (`develop`)**: exakten Commit auschecken, prüfen/builden, Dev bereitstellen, isolierte Pflicht-Gates auf diesen Images ausführen, sicheren Report veröffentlichen. Mutierende Tests sprechen nur den isolierten Stack. Mehrere Runs dürfen sich nicht gegenseitig als „aktuelles Dev“ qualifizieren; Dev-Deployment und devbezogener Smoke sind pro Umgebung serialisiert. +2. **Release-PR nach `main`**: Pflichtstatus für den richtigen PR-Head/qualifizierten Source, bestehende bewusste menschliche Annahme. Tatsächliche Statuskontextnamen werden aus dem eingesetzten Gitea ermittelt, nicht geraten. +3. **Production (`main`)**: konkrete Merge-/Sourcezuordnung auflösen, R1 übernehmen bzw. R2-Prod-Kandidat qualifizieren, Controller auf registriertem Ziel aufrufen. Ein `workflow_run`-Trigger allein ist kein Nachweis von Reihenfolge oder Artifactidentität. Bestehende Workflowdateien können die drei Aufgaben abbilden; keine neue CI-Plattform. + +Vor tatsächlicher Integration wird lesend ein `gitea-capabilities.json` erfasst: Server-/Runnerversion, effektive Main-/Develop-Schutzregeln inklusive Ausnahmen, erlaubte Merge-/Pushidentitäten, exakte Pflichtstatuskontexte, Run-/Artefaktlookup und Runner-/Secret-/Socket-/Netzgrenzen. Fehlende Fähigkeit wird sichtbar als nicht verifiziert geführt. Das ist eine technische Bestandsprüfung zu C/O2, keine neue Governance-Analyse. Der Adapter verwendet die API der tatsächlich installierten Version; keine ungeprüften API-/Permissionsbeispiele aus aktueller Cloud-Dokumentation. + +Gitea dokumentiert Branchschutz und erforderliche Statuschecks, ignoriert aber `jobs..environment`. Deshalb ist ein YAML-Environment kein menschliches Gate. [Gitea Branchschutz](https://docs.gitea.com/usage/access-control/protected-branches/), [Actions-Unterschiede](https://docs.gitea.com/usage/actions/comparison/). Zusätzlich verweigert der Controller selbst fehlende/rote Nachweise; ein Merge allein darf einen technisch unqualifizierten Kandidaten nicht deployen. + +Qualification-Reports aus untrusted PR-Ausführung dürfen weder Produktionssecrets erreichen noch als geschützte Releasenachweise gelten. Herkunft wird über den vertrauenswürdigen Run/Store geprüft; Actions sind kompatibel gepinnt. Shellbefehle erhalten ausschließlich validierte IDs/Argumentlisten. Benutzerbeeinflussbare Event-/Branchtexte werden nicht als `${{ ... }}` direkt in Shellcode eingesetzt. Produktionscredentials erscheinen nie im Checkout, Buildkontext, JUnit oder Artefakt. + +## 7. Isolierter Test- und Gatevertrag + +### 7.1 Stackidentität und Schutz vor falschem DB-Ziel + +Je Qualification: eindeutiger `run_id`, Composeprojekt `jk-test-`, eigenes internes Netz, eigene PostgreSQL-Volumes und zufällige kurzlebige Testcredentials. PostgreSQL hat keinen veröffentlichten Hostport. Browser/HTTPtests laufen im Testnetz; nötiger HTTPS-Testproxy nutzt synthetisches Testzertifikat. `PUBLIC_ORIGIN` entspricht diesem Testorigin. Proxyunterschiede werden als Testkonfiguration dokumentiert; die tatsächlich gebauten Appimages bleiben unverändert. + +Vor jedem Schemaaufbau/-reset prüft ein Wächter kumulativ: `APP_ENV=test`, registrierte Testwurzel, Compose-/Netz-/Volume-Labels mit Run-ID, erlaubten aufgelösten DB-Service, Run-ID im DB-Namen, `current_database()`, tatsächliche Benutzerrolle und provisionierten Testmarker. Die anfängliche Markeranlage erfolgt erst nach Bestätigung der separaten Run-Instanz unter deren einmaliger Provisionierungsrolle. Kein Zugriff auf reale Dev-/Prod-Endpunkte/Volumes; Netz-/Rollenisolation verhindert diese Ziele zusätzlich. Ein bloßer Name wie `*_test` reicht nicht. + +Testprovisionierung darf ihre eigene DB/Rollen anlegen; Migration- und Runtime-Rolle werden danach getrennt. Beide Negativfälle werden tatsächlich geprüft: Runtime kann Fach-DML im eigenen Scope, aber kein DDL/Owner-/Bypassverhalten. Kein SQLiteersatz. Provider-/SMTP-/Webhookcredentials fehlen; Testadapter und Netzwerkblockade verhindern echte externe Nebenwirkungen. Quellcode wird nicht über das Runtimeimage gemountet. Der Testdriver ist ein getrennt gebautes gelocktes Werkzeugimage bzw. Container, der das unveränderte Runtimeimage über HTTP anspricht; DB-Vertragstests laufen mit demselben Runtimecode/-Abhängigkeiten, Testtools ändern dessen Pins nicht. + +Die **Testumgebung** ist vom **App-Laufzeitmodus** zu unterscheiden: Der Wächter/Testdriver läuft mit `APP_ENV=test` gegen den isolierten Teststack. Zusätzlich wird das unveränderte Runtimeimage dort mit `APP_ENV=production`, synthetischen Pflichtsecrets und HTTPS-Testorigin geprüft. DB/Netz/Volumes bleiben trotzdem ausschließlich die registrierten Testressourcen. Dadurch sind Produktionsstart, sichere Fehler/Diagnosegrenzen und tatsächlich verwendete Konfigurationszweige abgedeckt. `qualification.json` erfasst Testtarget und App-Laufzeitmodus getrennt. Ein erfolgreicher Testmodus allein qualifiziert keinen unbekannten Produktionskonfigurationspfad. + +### 7.2 Pflicht-Gates + +| Gate-ID | Pflichtinhalt | +|---|---| +| G01 `source-config` | Source-/Tree-/Lock-/Build-/Plattformbindung; keine unbekannte Umgebung oder fehlender Pflichtadapter | +| G02 `unit-api` | Imports ohne DB-Nebeneffekt, OpenAPI-/Problemvertrag, explizite DTOs, sichere Fehler/204 | +| G03 `db-migrations` | Leere DB, Upgrade von unterstütztem Vorstand, Prüfsummen/fehlende Dateien, Konkurrenz, Ledger-/SQL-Atomarität, Poolrückgabe/Runtime-Rolle | +| G04 `auth-scope` | Registrierte Auth-/MFA-/Scopefälle aus Phase 3.3, Cross-Profile-/Cross-Tenant-Negativfälle und Entzugrennen | +| G05 `frontend-browser` | Build, Client-/epoch-Fehlerfälle, direkte SPA-Route, Login/Logout/CSRF, Scopewechsel und sichere Darstellung | +| G06 `image-runtime` | Tatsächliche gebaute Images, Start/Readiness/Revision/Plattform, keine Live-Quellmounts oder nachträgliche Paketänderungen | +| G07 `schema-compatibility` | Geplante Migration/Start mit Zielimage und explizit qualifizierter Rückweg; bei fehlendem Image-Rollback Nachweis des gewählten Restore-/Forward-Fix-Pfads | +| G08 `operations-contracts` | Controller-/Gate-/Zielschutztests, Fehlerfortsetzung, Backup-/Restoreintegration mit synthetischen Daten, Pflichtfallabdeckung | + +Pflichtfälle werden im Zielrepository in einer versionierten `required-tests.json` je Funktionsprofil explizit benannt. Kleine Apps erhalten keine erfundenen Org-/KI-Funktionen; deren Nichtregistrierung wird geprüft. Auth-/MFA-Pflichtfälle sind mit integriertem Adapter verpflichtend. Eine Testsuite mit null Fällen, fehlender Datei, anderem Commit, falschen parametrisierten IDs oder erforderlichem Skip ist rot. JUnit wird gegen Collection und Pflichtliste geprüft; Rohberichte und deren Hashes bleiben erhalten. Ein `|| true`, `npm ci || npm install` oder automatisch nachinstalliertes Testpaket kann kein grünes Gate erzeugen. + +Exitcode und Pflichtreportprüfung müssen beide erfolgreich sein. Tests dürfen im CI beliebig spät fehlschlagen: Cleanup läuft im `finally`/Workflow-`always`, Fehlerexitcode bleibt erhalten. Entfernt werden nur Ressourcen mit passender Projekt-/Run-ID und explizitem Inventory. Keine globalen Docker-Prunes und kein `down -v` gegen registrierte Liveprojekte. Ein Hostabbruch wird durch einen späteren eng begrenzten Stale-Run-Cleanup behandelt, der noch aktive Runs ausschließt. + +Live-Dev-/Prod-Smoke ist ausschließlich read-only: Liveness, Readiness, sichere Buildkennung, SPA-/Proxyantwort. Kein Testnutzer anlegen, kein Testlogin mit Kundenkonto, kein Import oder DBreset. Inhaltliche Mutationstests gehören in den isolierten Stack und sind vor Prod abgeschlossen. + +## 8. Deploymentzustände, Hostlock und Fehlerfortsetzung + +Ein exklusiver Lock je `product_id/environment` umfasst Release, Writerfreeze, Backupaufnahme, Migration, Restore, Umschaltung und zugehöriges Cleanup. Default: Linux-`flock` auf einer registrierten lokalen Datei, 60 Sekunden Wartebudget. Kein Lock anhand beliebiger Argumentpfade. Ein Controller übergibt seine Lease an untergeordnete Backup-/Migrationsschritte, die nicht erneut denselben Lock anfordern. Mehrhostdeployment wird durch dieses lokale Profil nicht unterstützt; ein entsprechendes Profil bricht ab, statt eine verteilte Sperre zu behaupten. + +Journalphasen: + +```text +PLANNED → PREFLIGHT_OK → MAINTENANCE → WRITERS_FROZEN + → BACKUP_COMPLETE → MIGRATING → SCHEMA_READY + → CANDIDATE_STARTED → SMOKE_OK → COMMITTED → SERVING + +Fehler vor Mutation: FAILED_SAFE +Fehler nach möglicher Mutation: FAILED_MAINTENANCE → RECONCILE / ROLLBACK / RESTORE +``` + +Jede Phase wird vor/nach dem externen Effekt mit Operation-ID und erwartetem Vorgängerstand protokolliert. Der Exitcode des Prozessschritts allein beweist nach Stromausfall nicht dessen Zustand. `reconcile` liest tatsächliche Images, Schema, Wartungsschalter, DB-/Mediengeneration und vorhandene Receipts, bevor es einen erlaubten nächsten Schritt plant. Blindes Wiederholen einer unbekannt abgeschlossenen Migration oder Umschaltung ist verboten. Session-Advisory-Lock und Migrationledger bleiben der spezielle DB-Schutz aus A5; der Hostlock ersetzt sie nicht. + +### 8.1 Produktionsablauf + +1. **Plan/Preflight:** Profil und erwarteten aktuellen Receipt prüfen; unveränderlichen freigegebenen Commit festhalten; R1-/R2-Nachweise und Artifactdateien prüfen. DB-Identität, Schema-/Lock-/Disk-/Speicherbudget, Schlüsselreferenzen, Sicherungsspeicher und Writerliste auflösen. Letzten erfolgreichen Recoverytest gegen den benötigten Umfang prüfen. Ein paralleler oder inzwischen neuerer Deploystand macht den Plan ungültig. +2. **Wartung:** Bestehender Reverse Proxy liefert für neue öffentliche App-/APIrequests einen sicheren 503-Wartungszustand. Der Schalter ist außerhalb des Appcontainers persistent. Direkte Backendzugänge sind auf das notwendige interne Netz beschränkt. Interner read-only Health bleibt für den Controller möglich. +3. **Drain/Freeze:** Neue Job-/Cron-/Workerstarts stoppen, laufende Requests/Jobs begrenzt drainen, alle registrierten Writer einschließlich Backend stoppen. Bestätigen, dass weder Upload-/Löschprozesse noch Fachtransaktionen weiterlaufen. DB bleibt für Dump/Migration verfügbar. Kein „nur Browser gesperrt, Worker schreibt weiter“. +4. **Pre-release-Sicherung:** Konsistenten DB-/Medienstand nach Abschnitt 10 aufnehmen, verschlüsseln und unabhängig verifiziert ablegen. Der Betriebsdefault verlangt diesen frischen Stand vor der Migration; ein älterer nächtlicher Dump wird nicht als Sicherung unmittelbar vor dem Eingriff ausgegeben. +5. **Migration:** Exakten freigegebenen Migrationssatz unter getrenntem Credential ausführen. Ledger/Head/Checksummen prüfen; Migrationscredential danach entfernen. Kein App-Startup führt Migration/Seed aus. Fehler bleibt Wartungszustand; keine Erfolgsausgabe. +6. **Start:** Backend/Frontend aus qualifizierten Image-IDs über die registrierte Release-Compose-Datei starten, externe Writer weiter pausiert. Keine Runtimebuilds, Paketinstallationen oder Livequellmounts. Composeauflösung darf weder DB-Volume noch fremde Produktressourcen ersetzen. +7. **Prüfen:** Begrenzte interne Liveness/Readiness, erwartete Backendrevision und Container-Image-IDs; Frontendrevision aus eigenem statischen `build.json` und tatsächlicher Frontend-Image-ID. Eine durchgereichte Backendantwort allein prüft kein Frontendimage. App muss den Zielledgerstand akzeptieren. Anschließend Proxyweg read-only prüfen, ohne Wartung allgemein zu öffnen. +8. **Commit/Öffnen:** Geprüfte Runtimegeneration und Receipt atomar veröffentlichen, dann Wartung lösen und registrierte Worker starten. Veröffentlichung von Dateizeiger und Containerprozess ist keine gemeinsame Transaktion; Journal/Reconcile behandeln jedes Zwischenstadium. Nach außen niemals eine gemischte alte/neue Generation freigeben. Sicherer öffentlicher Smoke schließt den Vorgang ab. + +Compose-Default für den bereits verifizierten Kandidaten: `docker compose ... up -d --no-build --pull never --wait --wait-timeout 120`. Die Release-Datei enthält keine `build:`-Abschnitte; eindeutige lokale Tags lösen zu erwarteten IDs auf. [Docker Compose up](https://docs.docker.com/reference/cli/docker/compose/up/) dokumentiert die verwendeten Optionen. `--wait` ersetzt weder Revision-/Schema-/Imageprüfung noch den anwendungsbezogenen Smoke. Das Datenbankimage bleibt separat gepinnt; dieser Workflow führt kein PostgreSQL-Majorupgrade aus. + +### 8.2 Fehlerreaktionen + +| Fehlerphase | Verbindliches Verhalten | +|---|---| +| Vor Wartung/Mutation | Abbruch ohne Änderung der laufenden App; Fehlerreceipt | +| Freeze/Backup scheitert, DB-/Medienstand sicher unverändert | Alte Generation prüfen und kontrolliert wieder öffnen; sonst Wartung erhalten | +| Migration gescheitert | Tatsächlichen Ledgerstand feststellen. Frühere Dateien können bereits committed sein; keine pauschale Behauptung vollständiger Rücknahme | +| Start/Smoke scheitert | Wartung behalten; nur qualifiziert kompatibles voriges Artefaktpaar starten oder Forward-Fix/Restore planen | +| Öffnung/Writerstart nur teilweise abgeschlossen | Journal als unvollständig führen; Reconcile auf tatsächliche Runtime, keine parallele neue Releaseoperation | +| Host-/Controllerabbruch | Lock wird vom Betriebssystem frei, Wartungs-/Journalzustand bleibt. Nachfolgender Lauf prüft unvollständige Operation zuerst | + +Aufräumen entfernt temporäre Ressourcen, aber löst nach möglicher Mutation nicht blind Wartung oder löscht alte Volumes/Backups. Ein „finally: alles wieder starten“ ist für diesen Zustand falsch. Normale getestete Releaseübergänge brauchen keine weitere menschliche Bestätigung. Ein datenrücksetzender Restore ist ein ausdrücklich ausgeführter Recoveryvorgang mit gebundenem Plan; er wird nie als automatischer Image-Rollback versteckt. + +## 9. Migration, Schemakompatibilität und Rückweg + +Foundation A5 bleibt unverändert: SQLdateien und Ledgereinträge auf derselben Connection/Transaktion pro Datei, Session-Advisory-Lock, Prüfsummenprüfung aller angewandten Dateien, kein SQLsplit an Semikola, keine psql-Metabefehle/eigenen Commits. Nach Fehlern zählt das tatsächliche Ledger. Runtime ist nicht der Migrationsbenutzer. Restore- und Migrationrechte bleiben vom Appbetrieb getrennt. + +`schema-compatibility.json` bindet vorigen/neuen Build samt Image-IDs, Migrationsdigest, alten/neuen Ledgerstand und tatsächliche Kompatibilitätstest-Runs. Default: Expand/Contract. Ein Release erweitert zunächst kompatibel; destruktive Entfernung erst nach Ablauf des vereinbarten Rückrollfensters und überprüfter Umstellung aller betroffenen Pfade. Readiness muss den tatsächlich geplanten Stand akzeptieren; eine behauptete Datenkompatibilität genügt nicht, wenn das vorige Image dort nicht startet. + +Im isolierten Stack wird vorab geprüft: alten synthetischen Datenstand anlegen → geplante Migration durchführen → neues Image starten und Pflichtfälle ausführen → qualifizierten vorherigen Build auf diesem Schema starten und dessen relevanten Read-/Write-/Authvertrag testen. Das erneute Testen des unveränderten alten Images ist ein Kompatibilitätsnachweis, kein Produktionswrite. Bei bewusst nicht kompatiblem Eingriff wird `image_rollback_qualified=false` dokumentiert und stattdessen die vollständige Restore-/Forward-Fix-Vorsorge getestet. Kein Feld darf fehlende Tests zu Kompatibilität erklären. + +**Image-Rollback:** voriges qualifiziertes Backend-/Frontendpaar auf demselben aktuellen Datenbestand starten, ohne DB-Downgrade. **Restore:** Daten und Medien auf den Sicherungsstand zurücksetzen, mit möglichem Verlust späterer Änderungen. **Forward-Fix:** neu qualifizierter korrigierter Kandidat über denselben Freigabe-/Gatevertrag. Diese drei Vorgänge haben unterschiedliche Wirkungen und Receipts. Es gibt kein automatisches produktives „Down“ und keinen ungetesteten Hotfix direkt auf dem Host. + +Das aktuelle und mindestens das vorherige qualifizierte Artefaktpaar bleiben über das Rückrollfenster verfügbar; Default sieben Tage. Zu jedem aufbewahrten Backup bleiben ein passendes lauffähiges Restoreimagepaar, Schema-/Konfigurationsstand und benötigte Faktorschlüsselreferenzen verfügbar. Der produktübergreifende Betriebsweg darf nicht versehentlich alle Produkte desselben Hosts stoppen oder deren Datenbankimages aktualisieren. + +## 10. Konsistentes Backup von DB und Medien + +### 10.1 Umfang und Konsistenzpunkt + +Ein vollständiger Recoveryset umfasst: + +- PostgreSQL-Custom-Dump einschließlich Fach-, Audit-, Auth-, Rechte- und Migrationsdaten. +- Alle für diesen Datenstand referenzierten persistenten Medien/Dateien sowie benötigte fachliche Versionen; kein Docker-Containerfilesystem als Datenspeicher. +- Inneres versioniertes Manifest mit Quellprodukt/-umgebung/-instanz, Release-/Image-/Ledgerstand, Freeze-/Snapshotzeit, Dateiliste, Größe und SHA-256 je Datei, Konfigurationshashes und benötigten **Schlüssel-IDs**. +- Separat verfügbare passende Runtimeimages, Deployment-/Rollen-/Schema-Rezepte und Recovery-Schlüsselmaterial. Sie gehören nicht ungeprüft in denselben Datenarchiveinhalt. + +Ein `pg_dump` ist DB-intern konsistent; es koordiniert nicht automatisch eine außerhalb liegende Medienablage. Der Default friert deshalb sämtliche Writer ein, bevor DB-Dump und Medienkopie beginnen. Die **Snapshotzeit** ist der bestätigte Freezezeitpunkt; seitdem verändern sich keine eingeschlossenen Daten. Das DB-Dumpformat wird aus Mitai übernommen, das Medien-/Checksummenmanifest aus Kanshō gezielt angepasst. [PostgreSQL pg_dump](https://www.postgresql.org/docs/16/app-pgdump.html). + +Default-Dumpargumente als getrennte Subprocessargumente: `pg_dump --format=custom --no-owner --no-privileges --file --dbname `. Host/Benutzer/Credential kommen aus dem registrierten Adapter, Passwort über geschützte Passfile-/Servicebereitstellung statt Kommandozeilen-URL. Tool aus passender gepinnter PostgreSQL-16-Linie. Exitcode/Warnungen prüfen; Dumpinventar lesbar, Datei nicht leer. Rollen/Clusterkonfiguration werden aus dem kontrollierten Bereitstellungsrezept rekonstruiert, nicht blind als globale SQLrolle importiert. + +Bei RLS braucht die Backupidentität nachweislich vollständige Lesesicht auf die eigene Produkt-DB; fehlende Rechte müssen den Dump scheitern lassen. Kein stiller RLS-gefilterter Teildump als Vollsicherung. Die dafür nötigen Rechte sind getrennt vom Runtimekonto und bleiben auf registrierte Produktziele begrenzt. + +### 10.2 Ablauf und Backupzustände + +```text +PLANNED → WRITERS_FROZEN → SNAPSHOT_CAPTURED → VERIFIED_LOCAL + → ENCRYPTED → COPIED_INDEPENDENT → COMPLETE +Fehler: FAILED; teilweise Dateien behalten den Zusatz .partial +``` + +1. Gemeinsame Operationslease halten, DB-/Pfadidentität und Platzbudget prüfen, Wartung/Drain durchführen. Release kann seinen bereits bestehenden Freeze übergeben. +2. Privates Staging unter freigegebener Wurzel (`0700`, Dateien `0600`) erstellen. DBdump aufnehmen; registrierte Medienwurzeln ohne Symlink-/Mountausbruch kopieren. Quelldateien bleiben im Freeze unverändert. +3. Produktadapter prüft DB-Medienreferenzen gegen Manifest: jede erforderliche Datei vorhanden, Größe/Hash passend; verwaiste Dateien nach expliziter lokaler Regel gesondert ausweisen. Keine fehlenden Medien als „leere Ablage“ akzeptieren. Manifest erst nach vollständiger Kopie schreiben. +4. Bei regulärer Sicherung können Writer nach dem unveränderlichen lokalen Snapshot und dessen Verifikation kontrolliert wieder anlaufen; Verschlüsselung/Kopie verwenden ausschließlich das unveränderliche Staging. Bei Pre-release-Backup bleiben Writer bis zum Releaseabschluss gestoppt, und unabhängige Kopie muss vor Migration vollständig vorliegen. +5. Datenarchiv verschlüsseln, Exitcode prüfen, Ciphertexthash/-größe erzeugen, über vorhandenen Transport auf registrierten unabhängigen Speicher kopieren, dort Hash/Größe erneut lesen und vergleichen. Keine Kopie innerhalb desselben Hostdatenträgers als Hostverlustschutz zählen. +6. Erst dann äußeren `backup-receipt.json` atomar als `COMPLETE` veröffentlichen. Staging nach erfolgreicher Prüfung unter sicherer Rootkontrolle entfernen; keine Rohdaten in CIartefakte oder Git hochladen. Fehler hinterlassen einen sichtbaren fehlgeschlagenen Lauf und lösen keinen Retentionslauf aus. + +Der äußere Receipt enthält nur Backup-ID, Produkt, Snapshot-/Abschlusszeit, Datenformat, Ciphertexthash/-größe, Speicher-ID, Empfänger-Key-IDs und Referenz zum passenden Recoverymaterial. Die sensible Dateiliste bleibt im verschlüsselten inneren Manifest. `COMPLETE` bedeutet vollständig aufgenommen, verschlüsselt und unabhängig kopiert; **es bedeutet nicht „dieses Backup wurde bereits restored“**. `restore_verified_at` und Drillreport sind getrennte Belege. + +Fehlgeschlagenes Rohdatenstaging bleibt ausschließlich unter privater Rootkontrolle und erhält eine explizite kurze Ablaufzeit; Default spätestens 24 Stunden. Der begrenzte Cleanup entfernt nur nachweislich inaktive Staging-IDs unter Operationslock. `.partial` wird nie in COMPLETE umbenannt, ohne die fehlenden Schritte nachzuholen. Bestehende Host-/Datenträgerverschlüsselung und verfügbare sichere Stagingkapazität werden im Betriebsprofil erfasst; das Tool behauptet kein kryptografisch sicheres Löschen auf unbekannten Datenträgern. + +### 10.3 Verschlüsselung, Schlüssel und Aufbewahrung + +Bevorzugter lokaler Verschlüsselungsadapter ist `age` mit ausdrücklich bereitgestellter Empfängerliste (`age -R `); Entschlüsselung nur über separat bereitgestellte Identitätsdatei. Binaryversion und Prüfsumme werden gelockt. Das ist ein kleines lokales Werkzeug, kein neuer Dienst; gleichwertige vorhandene Verschlüsselung kann nach Adapter-/Restoretest verwendet werden. Keine eigene Kryptografie und kein Passwort aus dem DBcredential ableiten. [age-Projektdokumentation](https://github.com/FiloSottile/age). + +Der Sicherungsprozess benötigt nur öffentliche Empfängerkeys. Recoveryprivatschlüssel werden nicht dauerhaft auf dem Produktionshost oder in CI gehalten und werden gegen Hostverlust selbst gesichert. Im autorisierten Recoveryvorgang sind sie nur temporär in der geschützten Recovery-/Operatorumgebung verfügbar und werden anschließend wieder entzogen. Mindestens eine Wiederherstellung mit tatsächlich zu diesem Profil gehörenden Entschlüsselungsrechten wird vor dem ersten externen Datenbetrieb geprobt; kein angenommener Zugriff aufgrund einer Key-ID. CI verwendet ausschließlich synthetische Testkeys. + +MFA-Faktorschlüssel aus Phase 3.3 sind **nicht** die age-Entschlüsselungsschlüssel. Das Datenmanifest listet alle benötigten MFA-Key-IDs auf. Die passenden Werte kommen aus einem gesondert geschützten, verschlüsselten Recoveryset bzw. vorhandener gesicherter Secretbereitstellung; dieser Zugriff muss ohne den ausgefallenen Host möglich sein. DBrollenpasswörter und Provider-/SMTPtokens werden bei Recovery über den vorhandenen Betriebsweg neu bereitgestellt oder rotiert. `.env`, Logs, Providerkeys und private Schlüssel werden nicht durch pauschales Archivieren des Appverzeichnisses eingesammelt. + +Default: geplante Sicherung alle zwölf Stunden für ein RPO-Ziel von 24 Stunden; dadurch bleibt Puffer für Laufzeit/Wiederholung. Vor strukturellen Produktionsänderungen zusätzlich Pre-release-Sicherung. Retention: 7 tägliche, 4 wöchentliche, 3 monatliche komplette Stände; zusätzlich letzte vollständige Sicherung und durch aktuelle Releases/Drills gebundene Stände. Ein Backup kann mehrere Aufbewahrungsklassen erfüllen. Löschen nur explizit gelisteter nicht mehr gebundener Backup-IDs unter Hostlock, ohne gesetzte lokale Löschsperre; kein freier Verzeichnis-Prune. + +Schlüssel und Restoreimages werden erst entfernbar, wenn kein aufbewahrter Recoveryset sie mehr benötigt. Löschungen im Produkt verschwinden nicht automatisch rückwirkend aus Backups; sie werden über die festgelegte Retention ausgetragen. Produktspezifische Lösch-/Hold-Anforderungen bleiben erhalten. Dieser Blueprint legt dafür keinen neuen familienweiten Rechts-/Aufbewahrungskatalog fest. + +## 11. Restoreverfahren und konsistente Umschaltung + +### 11.1 Plan und sichere Zielwahl + +`restore plan` ist read-only und bindet Backup-ID/Ciphertexthash, Profil-/Host-/DBidentität, erwartete aktuelle Runtimegeneration, Zielgeneration, benötigte Images/Keys, Integritätsprüfungen und geschätzten Datenverlust seit Snapshot. Der Plan hat einen Hash und Ablauf (Default 30 Minuten). `restore apply` benötigt genau diesen Planhash und erwarteten Vorgängerstand. Änderungen dazwischen machen ihn ungültig. Das ist ein technischer Schutz gegen falsche Ziele; die ausdrückliche Recoveryausführung ist keine zusätzliche allgemeine Freigabeschleife. + +Der Default restored in **eine neue leere Datenbank und eine neue Mediengeneration**, während die alte Generation erhalten bleibt. Kein `pg_restore --clean` auf einer laufenden Produktdatenbank. Neue DB von sauberem Template, passende Extensions/Rollen aus geprüftem Rezept, kein Schema-/Seedautostart. Neue Zielnamen/Volumes bleiben innerhalb der registrierten Produkt-/Umgebungsgrenze. Ein eigener DB-Nutzer mit eingeschränkten Rechten restauriert die eine Ziel-DB; AppRuntime ist weder Restaurator noch Eigentümer. + +Archive werden nur aus vertrauenswürdigem eigenem Backupstore angenommen. Erst Ciphertexthash/Quelle, dann vollständige Entschlüsselung und Archivprüfung, erst danach DBrestore. Geprüft werden Formatversion, relative kanonische Pfade, Eindeutigkeit, erlaubte Dateitypen, Dateianzahl, Einzel-/Gesamtgröße und Hashes; keine absoluten/`..`-Pfade, Symlinks, Hardlinks, Geräte oder Archivbomben. Inhalte werden nicht vor Validierung in die Zielwurzel extrahiert. Grenzwerte stammen aus dem Produktprofil und werden vor Ressourcennutzung geprüft. + +### 11.2 Ausführung + +1. Lease und Wartung setzen, Writer drainen/stoppen, aktuellen tatsächlichen Stand journalisieren. Wenn lesbar, eigenen Pre-restore-Sicherheitsstand aufnehmen; bei zerstörter Quelle dessen Fehlen ausdrücklich protokollieren statt ein vorhandenes Backup zu überschreiben. +2. Neue Ziel-DB/-Mediengeneration provisionieren, vertrauenswürdiges Archiv/Schlüssel prüfen. Geheime Daten nur im privaten Recovery-Staging verarbeiten. Keine Provider-/SMTP-/Webhookverbindung während Prüfung/Wiederanlauf. +3. Dump in die neue DB importieren: `pg_restore --no-owner --no-privileges --exit-on-error --single-transaction --dbname `. Kein paralleler `--jobs` bei diesem Default. [PostgreSQL pg_restore](https://www.postgresql.org/docs/16/app-pgrestore.html) beschreibt diese Restoreoptionen. Unter diesem Rollenmodell werden explizite Runtimegrants und ggf. RLS anschließend aus dem kontrollierten Bereitstellungsrezept gesetzt; Runtime wird nicht Owner. +4. Medien in eigene neue Generation extrahieren und nochmals gegen Manifest prüfen; Herkunfts-DBidentität/Ledger gegen inneres Manifest abgleichen, dann neue Zielidentität setzen. Fehlende Dateien/Keys/Constraints brechen ab. Restore wird nicht als erfolgreich markiert, nur weil `pg_restore` Exit 0 meldet. +5. Sicherheitszustand gemäß Abschnitt 12 nachbehandeln, in eigener DBtransaktion auditieren. Anschließend passendes gesichertes Imagepaar intern starten; keine automatisch nachgezogenen Migrationen. Ein späteres Upgrade wäre ein eigener normaler Releasevorgang. +6. Technische/fachliche Read-only-Integritätsprüfungen auf der wiederhergestellten Generation: Ledger/Checksummen, FKs/Constraints/Sequenzen, sichere Aggregat-/Manifestabgleiche, Medienreferenzen, Faktor-Key-Auflösung, Runtimeprivilegien und Auth-/Scope-Sperrwirkung. Reale persönliche Inhalte nicht in Prüfberichte oder Screenshots übernehmen. Mutationstests bleiben auf synthetischen Drilldaten. +7. Unter fortbestehender Wartung den privaten Runtimezeiger auf ein Konfigurationspaar `{release_id,database_ref,media_generation}` umschalten und betroffene Services neu starten. Beide Ressourcen bleiben gekoppelt. Erst nach Readiness/Revision-/Image-/Referenzprüfung die öffentliche Wartung lösen. Das funktioniert über Stillstand plus Journal; es ist keine behauptete atomare Transaktion zwischen DB und Dateisystem. +8. `restore-receipt.json` mit Backup-/Plan-/Quell-/Ziel-/Image-/Schemaidentitäten, Sicherheitsmaßnahmen, Zeitmessung und verbleibender Kontenquarantäne schreiben. Alte Generation bleibt für das vereinbarte Sicherheitsfenster privat erhalten, ohne Appzugriff; Default sieben Tage unter denselben Schutz-/Speicherregeln. + +Fehler vor Umschaltung lässt die alte Generation unangetastet. Fehler während Umschaltung hält Wartung aktiv; `reconcile` prüft beide Ressourcen. Hat nach Öffnung bereits ein neuer Write stattgefunden, darf ein Zurückschalten auf die alte Generation nicht als verlustfreier technischer Retry erfolgen. Es braucht einen neuen Recoveryplan mit benanntem Datenverlust. Keine automatische Löschung der alten DB/Medien im Fehlerhandler. + +Für einen vollständigen Hostverlust werden zuvor Hostwerkzeuge, PostgreSQL-/Compose-/Proxybasis, Produktprofil und neue DBrollen/Runtimecredentials aus den gesicherten Rezepten bereitgestellt. Danach gilt derselbe Restoreablauf. Appdatenbackup ersetzt weder den Gitea-/Runner-Backupbetrieb noch die Sicherung der gesamten privaten Infrastruktur; der Scope dieses Dokuments bleibt das jeweilige Produkt. + +## 12. Authentifizierung und Rechte nach Restore + +Restore kann Sicherheitszustand zurückdrehen: vor dem Snapshot noch gültige Sessions, später verbrauchte Recoverycodes, inzwischen deaktivierte Konten oder entzogene Mitgliedschaften. Deshalb reicht ein Neustart des Backends nicht. + +Pflicht-Port des Auth-/Produktadapters: `invalidate_restored_security_state(tx, restore_id)`. Er führt für die neue Generation vor Öffnung atomar aus: + +1. Alle restaurierten Browser-Sessions widerrufen, Konto-`security_epoch` erhöhen, alle Login-/MFA-/Enrollment-/Reset-/Bestätigungsflows verbrauchen. +2. Alle restaurierten Recoverycodes ungültig machen; Tokens/grants für Medien und gegebenenfalls technische Credentials ebenfalls gemäß registriertem Produktadapter widerrufen. Ein nicht integrierter erforderlicher Adapter hält Wiederanlauf geschlossen. +3. Bei TOTP den gespeicherten akzeptierten Counter mindestens auf den aktuellen DB-Zeitschritt anheben, niemals senken; ein Code aus dem gerade laufenden bereits möglicherweise benutzten Zeitfenster wird nicht erneut akzeptiert. Faktor-Secrets nur mit passenden gesicherten Key-IDs verwenden, nie durch Defaultsecret ersetzen. +4. **Default Kontenquarantäne:** Restaurierte Konten zunächst `disabled`; keine automatische Aktivierung alter Betreiber-/Club-/Orgzuordnungen. Wiederfreigabe ausschließlich anhand geprüften aktuellen Kontostatus und aktueller Mitgliedschafts-/Rollenlage. Fehlt eine verlässliche aktuelle Credentiallage, Passwort neu setzen. Backuprechte sind keine Autorität für spätere Entzüge. +5. Genau einen ausdrücklich ausgewählten Betreiber über den vorhandenen lokalen Recovery-/Provisionierungsweg aus Phase 3.3 wiederherstellen, alte Sessions/Codes dabei geschlossen lassen und erforderliche MFA-Einrichtung/-Prüfung erzwingen. Danach Konten/Zugänge gezielt rekonstruieren; kein pauschales „enable all“ im Restorekommando. + +Ein Produkt mit unabhängig vollständig rekonstruierbarem aktuellem Sperr-/Entzugsstand kann einen entsprechenden Abgleichadapter anstelle der pauschalen Kontenquarantäne verwenden. Er muss alle Konto-, Rollen-/Mitgliedschafts-, Token- und Recoveryänderungen seit Snapshot abdecken und negativ getestet sein; ein älteres Audit aus demselben Dump genügt nicht. Dies ist eine begründete Produktvariante mit gleicher Schutzwirkung, kein neuer zentraler Entzugsdienst. + +Die technische Verfügbarkeit einer restaurierten App und die Wiederfreigabe ihrer Konten werden getrennt gemessen. `service_restored_at` bedeutet geprüfter Dienst erreichbar; `user_access_restored_at` gehört zum konkret gewählten RTO-Ziel und schließt notwendige Konten-/MFA-/Berechtigungsrekonstruktion ein. Der Restorebericht darf vier Stunden RTO nicht allein durch grünes Health behaupten, während alle regulären Zugänge ungeplant gesperrt bleiben. + +## 13. Betriebsbeobachtung und Recoveryübungen + +`ops status` liest Journal/Receipts, tatsächliche Runtime-/DBidentität, sichere Health-/Builddaten und Backupalter. Ausgabe: `healthy`, `degraded`, `maintenance` oder `failed`, mit sicheren Reasoncodes; keine Personeninhalte, DBpasswörter oder vollständigen Logs. Readiness prüft die Laufzeitabhängigkeiten; ein Backupstatus wird separat berichtet und nicht als Authlogout interpretiert. + +RPO-Messwert = aktuelle Zeit bzw. Incidentzeit minus **Snapshotzeit** des jüngsten unabhängigen `COMPLETE`-Backups; nicht dessen Kopierabschlusszeit. Default Warnschwelle 18 Stunden, Zielverletzung ab 24 Stunden. Bei Zielverletzung werden neue Produktionsreleases blockiert und über den vorhandenen Betriebskanal/Jobfehler sichtbar gemeldet; die laufende Anwendung wird nicht unbemerkt abgeschaltet. Fehlender Empfänger/Überwachungskanal bleibt eine sichtbar fehlende Betriebsanbindung, keine erfundene Benachrichtigung. + +Vorhandener Scheduler (z. B. Hosttimer) ruft die lokale Backup-CLI auf; kein Scheduler in der App und keine Automationsanlage in diesem Auftrag. Überwacht werden auch erfolglose/nie gestartete Jobs über Alter des letzten Receipts. Retentionsjobs sind nur nach vollständiger erfolgreicher Sicherung zulässig. RTO misst Incident-/Übungsbeginn bis zum im Produktprofil definierten Wiederherstellungsziel, einschließlich Beschaffung der Keys/Images, Restore, Integrität und erforderlicher Zugangsfreigabe. + +Pflichtübungen im späteren Zielaufbau: + +- Vor externem datenveränderndem Betrieb: synthetische End-to-End-Sicherung/Restore mit repräsentativem Medienvolumen, tatsächlichem gewählten Schlüssel-/Speicherweg und begrenzter Runtime-Rolle. +- Vor einer Änderung von Backupformat, Schlüssel-/Speicherweg oder nicht kompatibler Migration: betroffenen Recoverypfad erneut ausführen. +- Regelmäßig, Default monatlich: Restore eines ausgewählten vollständigen Recoverysets; mindestens eine Übung beginnt auf leerer Ersatzumgebung. Produktive Archive gehören nur in eine ausdrücklich autorisierte abgeschottete eigene Recoveryumgebung, niemals in normale CI oder einen fremden Dienst. CI verwendet synthetische Daten und eigene Keys. + +Drillbericht: Backup-/Key-/Image-/Schema-/Profilreferenzen, Umfang/Umgebung, Befehlseinstiegspunkte, tatsächliches Ergebnis/Abbruchphase, Daten-/Medienabgleich, Sicherheitsnachbehandlung, gemessene RPO/RTO und verbleibende Lücken. Ein alter erfolgreicher Drill belegt keinen unbekannten neuen Schlüsselsatz oder größeren Datenbestand. Ergebnisse erhalten erst nach tatsächlichem Erfolg den Status T. + +## 14. Konkrete Python-/CLI-Verträge + +Der Controller ist ein produktlokales Pythonpaket außerhalb der FastAPI-Runtime. Abhängigkeiten werden separat gelockt; keine Importnebenwirkungen und keine globale Ziel-DB. Ein kleiner Composition Root verdrahtet die folgenden Ports. Datenobjekte werden mit strikten versionierten Schemas validiert, zusätzliche unbekannte Felder verweigert. Die Abkürzungen im Beispiel stehen für die oben definierten vollständigen Manifest-/Profilverträge. + +```python +from contextlib import AbstractContextManager +from dataclasses import dataclass +from pathlib import Path +from typing import Literal, Protocol + +@dataclass(frozen=True, slots=True) +class TargetRef: + product_id: str + environment: Literal["development", "test", "production"] + host_id: str + profile_sha256: str + database_instance_id: str + +@dataclass(frozen=True, slots=True) +class ReleaseRef: + release_id: str + manifest_sha256: str + +@dataclass(frozen=True, slots=True) +class VerifiedRelease: + ref: ReleaseRef + approved_main_commit: str + source_tree: str + backend_image_id: str + frontend_image_id: str + migrations_sha256: str + qualification_run_ids: tuple[str, ...] + +@dataclass(frozen=True, slots=True) +class OperationPlan: + operation_id: str + action: Literal["deploy", "image_rollback", "restore"] + target: TargetRef + expected_generation_id: str + target_generation_id: str + target_database_instance_id: str + release: ReleaseRef + backup_id: str | None + expires_at: str + +class Lease(Protocol): + """Interne geprüfte Operationslease; nie aus CLI/JSON deserialisieren.""" + +class FrozenWriters(Protocol): + """Bestätigter Writerstillstand unter einer gehaltenen Lease.""" + +class ProvenanceVerifier(Protocol): + def require_qualified_and_approved( + self, target: TargetRef, release: ReleaseRef, + ) -> VerifiedRelease: ... + +class HostCoordinator(Protocol): + def exclusive(self, target: TargetRef, + operation_id: str) -> AbstractContextManager[Lease]: ... + def freeze(self, lease: Lease) -> FrozenWriters: ... + +class BackupController(Protocol): + def capture(self, lease: Lease, frozen: FrozenWriters) -> str: + """Liefert ausschließlich die ID eines COMPLETE-Backups.""" + ... + +class RecoveryHooks(Protocol): + def require_media_consistency(self, tx: object, media_root: Path, + manifest: dict) -> None: ... + def invalidate_restored_security_state(self, tx: object, + restore_id: str) -> None: ... +``` + +`VerifiedRelease`, Lease und FrozenWriters sind interne Ergebnisse echter Adapterprüfungen. Ein CLIflag `--verified`, ein JSONstatus oder ein Testfake darf sie im Produktionsaufbau nicht ersetzen. Alle zustandsverändernden Schritte prüfen den gehaltenen Lock und erwartete tatsächliche Zielgeneration erneut. Auth-/Medien-/Integritätsadapter erhalten explizite Transaktionshandles; ihre Pflichtänderungen und Audit committen zusammen. Subprocessaufrufe erfolgen mit Argumentlisten und `shell=False`, begrenzter Laufzeit, redigierter Ausgabe und geprüftem Exitcode. Keine Passwörter in Arguments/Exceptions. + +### 14.1 Vorgesehene Einstiegspunkte + +Die folgenden Befehle sind Spezifikation, nicht in dieser Lieferung angelegte oder ausgeführte Programme. `<...>` bezeichnet ausdrücklich zu wählende IDs/registrierte Pfade. + +| Befehl | Wirkung | +|---|---| +| `python -m ops.release inspect --profile ` | Read-only: registriertes Ziel, aktueller Stand, effektive Giteafähigkeiten, offene Voraussetzungen als sicheres JSON | +| `python -m ops.release verify --profile --release-id ` | Quell-/Gate-/Merge-/Artefaktbeziehung lesen und prüfen; keine Liveänderung | +| `python -m ops.release plan --profile --release-id --expect-current ` | Gebundenen Deploymentplan und dessen Hash in geschützter Planablage erzeugen | +| `python -m ops.release apply --profile --plan-id --plan-sha256 ` | Unter Lock nach erneuter Prüfung den geplanten Release ausführen | +| `python -m ops.release reconcile --profile --operation-id ` | Tatsächlichen Zustand lesen und zulässigen Fortsetzungsplan erstellen; Änderungen erst über dessen `apply` | +| `python -m ops.backup create --profile ` | Gemeinsame Lease, konsistent aufnehmen, verschlüsseln, unabhängig kopieren, Receipt | +| `python -m ops.backup verify --profile --backup-id ` | Äußere Hash-/Speicherprüfung; meldet ausdrücklich, ob nur Ciphertext oder auch Inhalt geprüft wurde | +| `python -m ops.backup retention-plan --profile ` | Read-only-Plan der löschbaren IDs einschließlich Bindungs-/Holdprüfung erzeugen | +| `python -m ops.backup prune --profile --plan-id --plan-sha256 ` | Ausschließlich zuvor berechnete ungebundene Backup-IDs entfernen; kein automatischer Erfolgspfad bei fehlgeschlagener Sicherung | +| `python -m ops.restore plan --profile --backup-id --expect-current ` | Restoreziel, Datenstand, Keys/Images, Verlustfenster und Quarantäne planen | +| `python -m ops.restore apply --profile --plan-id --plan-sha256 ` | Neuen DB-/Medienstand vorbereiten, prüfen und kontrolliert umschalten | +| `python -m ops.restore drill --profile --fixture-set ` | Synthetische End-to-End-Übung ohne Livecredentials; Ergebnisbericht | +| `python -m ops.status --profile ` | Laufzeit-/Backup-/Wartungs-/Recoveryzustand lesen, keine Reparatur | + +Planer für Deployment, Restore und Retention teilen die versionierte Planablage; Retention hat eine eigene Planschemaart mit expliziten Lösch-IDs. Der gezeigte `OperationPlan` beschreibt Runtimewechsel. Plan-IDs werden unter registrierter Operationswurzel aufgelöst; kein beliebiger vom Workflow hochgeladener Plan wird privilegiert ausgeführt. Planhash liegt außerhalb des kanonisch serialisierten Planinhalts; Zeitwerte sind UTC und werden gegen vertrauenswürdige Hostzeit validiert. CLI und Journals schreiben sichere technische IDs, keine Kundennamen oder Secretreferenzen mit eingebetteten Werten. + +Wiederholtes `apply` derselben bereits erfolgreichen Operation führt keinen zweiten Write aus: Nur wenn Receipt und tatsächliche aktuelle Generation noch übereinstimmen, darf der bestehende Erfolg zurückgegeben werden. Nach zwischenzeitlich neuerem Release oder verändertem Ziel ist der Plan stale. Unvollständige Operationen verlangen Reconcile; keine versteckten pauschalen Retries von Restore/Mutation. + +### 14.2 Fehler- und Exitcodevertrag + +| Exit | Codegruppe | Verhalten | +|---|---|---| +| 0 | `ok` | Vollständig nachgewiesene angeforderte Operation; Read-only-Reports unterscheiden ihre Prüftiefe | +| 2 | `profile_invalid`, `manifest_invalid`, `plan_invalid` | Schema/Parameter unbekannt oder unvollständig; keine Zielmutation | +| 3 | `provenance_denied`, `gate_missing`, `gate_failed`, `approval_missing`, `artifact_mismatch` | Nicht qualifiziert/freigegeben oder falsches Artefakt; Produktion unverändert | +| 4 | `target_mismatch`, `stale_plan`, `preflight_failed`, `backup_stale` | Ziel-/Betriebsbedingung nicht erfüllt; geänderten Plan nicht anwenden | +| 5 | `dependency_unavailable`, `backup_failed`, `key_unavailable` | Abhängigkeit/Sicherung gestört; Fehlerzustand und sichere Phase melden | +| 6 | `migration_failed`, `switch_incomplete`, `recovery_required` | Mögliche Mutation, Wartung erhalten und Reconcile/Recovery erforderlich | +| 7 | `restore_validation_failed`, `recovery_objective_missed` | Übung/Integrität/Ziel nicht nachgewiesen; keine Erfolgsmarkierung | +| 8 | `operation_busy` | Lock nicht rechtzeitig erhalten; keine parallele Operation | + +Fehlerobjekt: `operation_id,code,phase,target_id,retry_class,request_or_run_id`; sichere Kurzbeschreibung, keine rohen SQL-/Docker-/Secret-/Archivdaten. `retry_class` ist `read_only_retry`, `replan` oder `reconcile_required`; keine automatische Wiederholung eines unklar abgeschlossenen Write. Das Hosttool hält die ursprüngliche Fehlerursache/Exitnummer trotz fehlgeschlagenem Cleanup fest. + +## 15. Automatisierte Prüfungen und Abnahme + +Die folgende Matrix ist ein konkreter Implementierungs-/Testauftrag, keine ausgeführte Testliste. Testdaten: Produkt A/B und Dev/Prod als getrennte synthetische Identitäten, zwei Source-/Buildstände, mindestens ein migrierter Datensatz mit Medienreferenz, Auth-/MFA-/Mitgliedschaftsfixtures aus Phase 3.3, eigene Backup-/Faktorschlüssel. Echtes isoliertes PostgreSQL und lokale Testvolumes; keine Produktserver oder produktiven Schlüssel verwenden. + +| ID / Suite | Testfall | Verlangter Nachweis | +|---|---|---| +| P01 `test_provenance.py` | R1 mit gleichem Tree, abweichendem Mergecommit; R2 mit separaten Dev-/Prodhashes | Nur korrekte Quell-/Merge-/Buildbeziehung erlaubt; beide Varianten ohne Sonderfreigabeschleife | +| P02 | Roter/fehlender/geskippter Pflichtfall, null Collection, xfail, falsche parametrische ID, fremder Run | Gate verweigert; bloß grüne Workflowzusammenfassung genügt nicht | +| P03 | Manipuliertes Manifest/Archiv/Tag, eigener Upload mit passenden selbst erzeugten Hashes | Hash **und** vertrauenswürdige Herkunft nötig; geladene/gestartete Image-ID stimmt exakt | +| P04 | Falscher Main-Commit, Bot-/Autorname als Menschbeleg, Directpush, Freigabe nach anderer Qualifikation | Kein Deployment; tatsächlicher erlaubter menschlicher Merge ist eindeutig gebunden | +| P05 | Unverifiziertes Gitea-Environment/Branchschutz-/Runlookup oder fehlende Plattform | Konfiguration nicht als wirksam behauptet; Produktivgate geschlossen | +| P06 | Pflichtliste im Kandidaten ausgedünnt, Gateprofil geändert | Hostseitiger Mindestvertrag/-version und freigegebener Profilhash verhindern eigenmächtiges Weglassen obligatorischer Gategruppen | +| P07 | Wiederaufbau bei neuem Rezept/Toolchainstand | Protokollierte Inputs rekonstruierbar; unerklärte Laufzeit-/Assetabweichung verweigert; Metadatenunterschiede explizit eingeordnet | +| I01 `test_test_isolation.py` | Testziel zeigt auf Dev/Prod, falschen Marker/Benutzer/Run/Netz/Volume | Vor erstem Schemawrite abgebrochen; Livezustand unverändert | +| I02 | Zwei parallele Qualificationruns | Eigene DBs/Netze/Ports/Volumes, keine Kollision oder fremde Cleanups | +| I03 | Test-/Buildfehler, Abbruch und Stale-Run-Cleanup | Ressourcen nur der eigenen Run-ID entfernt; Fehlerexit erhalten; aktive/fremde Runs geschützt | +| I04 | Provider-/SMTP-/Webhookzugriff und Produktions-Dockersocket aus Testjob | Netz-/Credentialgrenze blockiert; keine reale externe Nebenwirkung | +| D01 `test_release_controller.py` | Vollständiger Deploy R1 und R2, wiederholtes Apply | Richtige Images/Revision/Schema, genau ein Runtimewechsel, vollständiger Receipt | +| D02 | Zwei Deploys bzw. Deploy/Backup/Restore gleichzeitig | Gemeinsamer Lock serialisiert; kein zweite Controllerlease im Kindschritt | +| D03 | Ziel-/Generation-/Profiländerung nach Plan | Staleplan verweigert; keine falsche DB oder fremdes Produkt betroffen | +| D04 | Stromausfall/Exception an jeder Journalphase vor/nach Effekt | Wartung/Journal bleiben konsistent; Reconcile erkennt tatsächlichen Zustand, kein blindes Restart/Öffnen | +| D05 | Kandidatready mit falscher Image-/Build-ID, falschem Frontend oder falschem Schema | Smoke/Gate rot trotz HTTP 200; kein Servingcommit | +| D06 | Fehler vor Migration vs. Fehler nach möglicher Migration | Nur sicher unveränderte alte Generation kontrolliert öffnen; sonst Wartung und gewählter Recoveryweg | +| D07 | Produktionsmodus im isolierten Image-Test mit synthetischer Konfiguration | Production-Startup/Secure-/Diagnosegrenzen tatsächlich geprüft; physisches Testtarget bleibt von Live getrennt | +| M01 `test_migration_recovery.py` | SQL-/Ledgerfehler, paralleler Runner, Dollar-quoted SQL, Drift/fehlende Datei | Foundation-A5-Atomarität/Prüfsummen/Lock erfüllt; keine Migration beim Runtimeimport/-start | +| M02 | Upgrade und altes Image auf neuem Schema; bewusst inkompatibler Eingriff | Rollback nur bei tatsächlichem Start-/Vertragstest; sonst Restore/Forward-Fix-Vorsorge belegt | +| M03 | Runtimeprivilegien nach Migration und nach Restore | Runtime nicht Owner/Superuser/BYPASSRLS und kein DDL; tatsächliche Fachzugriffe funktionieren | +| B01 `test_backup.py` | DBwrite, Upload und Löschjob beim Freeze | Alle registrierten Writer gestoppt/drained; gleicher DB-/Medienkonsistenzpunkt; kein fehlendes Referenzobjekt | +| B02 | Leerer/abgebrochener Dump, fehlendes Medium, voller Datenträger | Kein COMPLETE; keine Retentionslöschung oder Erfolgsmeldung | +| B03 | Verschlüsselung scheitert, Empfänger falsch, externe Kopie unvollständig, gleicher Hostpfad | Kein unabhängiger COMPLETE-Nachweis; klare Prüftiefe; keine Keys/Rohdaten in Logs/Artefakten | +| B04 | Retention mit aktuellem/pinned/gesperrtem/letztem Backup, benötigten alten Keys/Images | Benötigte Sets bleiben erhalten; nur explizite ungebundene IDs gelöscht | +| B05 | Snapshotalter vs. Abschlussalter, verpasster Schedulerlauf | RPO korrekt aus Snapshotzeit; Warnung/Zielverletzung sichtbar; neues Release bei verletzter Bedingung gesperrt | +| R01 `test_restore.py` | Synthetischer Komplettrestore auf leerer Ersatzumgebung | DB-/Medien-/Hash-/Schema-/Key-/Imagebindung stimmt; RPO/RTO einschließlich gewählter Zugangsrekonstruktion gemessen | +| R02 | Pfadtraversal, Symlink/Hardlink, Duplikate, Archivbombe, fremde Quelle/Hash | Vor Extraktion/DBimport verweigert; keine Datei außerhalb Staging/Zielwurzel | +| R03 | Importfehler und fehlende Rollen/Extensions/Keys/Medien | Neue Generation nicht öffentlich; alte Generation erhalten; keine still ignorierten Fehlobjekte | +| R04 | Abbruch nach DBrestore, nach Medienextraktion, während Zeiger-/Containerwechsel | Kein gemischtes DB-/Medienpaar öffentlich; Wartung/Reconcile funktioniert | +| R05 | Rückschalten nach ersten neuen Writes | Kein automatischer verlustfreier Retry behauptet; neuer Recoveryplan nötig | +| R06 | Alte Session, verbrauchter Recoverycode, widerrufener Maschinen-/Medienzugang im Snapshot | Nach Restore nicht nutzbar; Epoch/Flows/Codes/Adapter tatsächlich invalidiert | +| R07 | Nach Snapshot gesperrtes Konto/entzogene Mitgliedschaft im Backup wieder aktiv | Quarantäne bzw. vollständiger aktueller Abgleich verhindert erneuten Zugriff; kein pauschales Enable-all | +| R08 | TOTP-Replaycounter, Betreiber-Recovery und fehlender Faktor-Key | Counter nicht abgesenkt, aktuelle alte OTP nicht akzeptiert; keine Faktorlos-Ausnahme; gezielter sicherer Betreiberwiederanlauf | +| R09 | Gleicher Dump auf falschem Produkt/Umgebung/Instanz | Plan-/Manifest-/Zielprüfung verweigert, außer ausdrücklich als isolierter Testclone registrierter synthetischer Drill | + +Zusätzlich: statischer Konfigurationscheck auf `build:`/Livequellmounts im Releasecompose, Secretwerte in Manifesten, unzulässige Runner-/Deployrechte sowie fehlende Fach-/Auth-/Medienhooks. Syntaktische Checks ersetzen die oben genannten Effekt-/Negativtests nicht. + +Die hostseitige Gatepolicy fixiert Mindestgruppen/Vertragsversion und erwartete Funktionsadapter. Ein Kandidat kann seine eigene Pflichtliste nicht beliebig auf eine triviale Suite reduzieren. Geänderte zulässige Pflichtfälle bleiben Teil des bewusst geprüften Quell-/Controller-/Profilstands; keine neue zentrale Governanceplattform. + +Pflicht-Gateprobe: Einen erforderlichen Test absichtlich rot machen, danach einmal dessen Report entfernen und einmal einen erforderlichen Test skippen. Jede Variante muss Produktionsverifikation stoppen, bevor Wartung/Migration beginnt. Danach den unveränderten qualifizierten Erfolgsfall vollständig durchlaufen. Diese Probe findet ausschließlich in der isolierten Abnahmeumgebung statt. + +## 16. Implementierungsanweisung für Cursor + +**Späterer Auftrag; hier wird nichts implementiert oder betrieben.** Das konkrete Zielrepository und registrierte Betriebsziel werden im tatsächlichen Umsetzungsauftrag benannt. Der Auth-Blueprint bleibt Phase-3.3-Grundlage; dieser Text startet nicht automatisch dessen Phase-3.4-Implementierung. + +1. Foundation v0.3 und diesen Blueprint im benannten Zielaufbau verwenden. Vorhandene Reusekandidaten aus Abschnitt 2 gezielt übernehmen, einschließlich Herkunft/Abweichungen. Keine anderen Produktrepos ändern oder zur Laufzeit importieren. +2. Kleine getrennte `ops`-Toolchain mit Strictschemas, Ziel-/Pfadprüfungen, Dataclasses/Ports und redigiertem Fehlervertrag erstellen. Commands ohne Wirkung importierbar; `inspect/verify/plan` strikt read-only gegenüber Livezustand. Keine FastAPI-Betriebsverwaltung entwickeln. +3. Profil und Controllervertrauen konkret verdrahten. Tatsächliche Gitea-/Runner-/Proxy-/Host-/Speicherfähigkeiten lesend erfassen, O2/O3 mit konkreten technischen Werten ausfüllen. Fehlende Zugänge/Ziele im Implementierungsbericht als nicht verifiziert führen; keine erfundenen Servereinstellungen oder pauschalen Neuinstallationen. Neue Produktions-/Giteakonfiguration nur im ausdrücklich autorisierten späteren Integrationsumfang vornehmen. +4. Isolierten Qualificationstack und `required-tests.json` aufbauen, Runtimeimages exakt identifizieren, Testrollen/Marker/Wächter einrichten, Rohberichte auswerten. Feste Devtestdatenbanken und Tests gegen laufende Appcontainer nicht kopieren. Keine Provider-/Kundenschlüssel nutzen. +5. Gitea-Workflows im vorhandenen System auf Qualification → menschlich freigegebenen Main → geprüftes Deployment binden. R1 als Default unterstützen, R2 gleichwertig gatefähig halten. Fehlende/rote/geskippte Pflichtbelege und untrusted Artefakte blockieren in beiden Varianten. Keine neue Registry, kein ausschließlich nachgelagerter Produktionstest als Gateersatz. +6. Hostlock, persistenten Wartungsschalter, Writerinventory/-drain und Journalzustandsautomaten implementieren. Controllerstand geschützt bereitstellen, tatsächliche Laufzeitidentität prüfen, Wiederanlauf nach jedem möglichen Abbruch testen. Der App-Prozess erhält keine Controller-/Docker-/Migrationsrechte. +7. Foundation-SQL-Runner anbinden, Image-/Schemakompatibilität tatsächlich testen, frische Pre-release-Sicherung vor Migration verlangen. Kein produktives Schema-Down, keine Container-Migration beim Start und kein automatisches Rollback in unklaren Datenzustand. +8. Mitai-Custom-Dump und Kanshō-Manifest als kleine Adapter auf PostgreSQL/Medien übertragen. Gemeinsamen Freeze, vollständige Referenzprüfung, Verschlüsselung, unabhängige Kopie und Retention mit gebundenen Recoverysets implementieren. Nur registrierte Medienpfade, kein Appverzeichnis-Vollbackup mit Secrets. +9. Restore in neue DB-/Mediengeneration, Ziel-/Archivschutz, gekoppelte Umschaltung und Auth-/Berechtigungsnachbehandlung implementieren. Fehlende Hooks schließen Recoveryfreigabe. Keine aktive Live-DB durch `--clean` ersetzen. Synthetische Hostverlust-/Abbruchübungen samt Keys/Images/RPO/RTO ausführen. +10. Matrix aus Abschnitt 15 tatsächlich ausführen; bestandene Ergebnisse mit Commit/Build-/Controller-/Profilstand und Umgebung dokumentieren. Erzeugte CLI-/JSON-/Compose-/Workflowdateien, Lockfiles, OpenAPI-/Authintegration soweit betroffen und nachvollziehbare Reports liefern. Nicht implementierte Produktadapter sichtbar schließen und korrekt als K/offen führen. + +Ein sinnvoller erster Referenzdurchlauf verwendet ein synthetisches persönliches Objekt mit einer Mediendatei: qualifiziertes Image → freigegebener Release → Migration → konsistentes Backup → absichtlich fehlschlagender Kandidat → qualifizierter Rückweg → Restore in neue Generation → überprüfte Session-/Zugriffssperre. Der Durchlauf muss keine neuen KI-/Billing-/SSO-Funktionen erfinden. Bestehende Appdaten werden dafür nicht benötigt. + +Abnahme des späteren Zielaufbaus: erforderliche Tests bestanden, rotes Gate verhindert nachweislich Deployment, Runtime entspricht dem freigegebenen qualifizierten Artefakt, DB-/Medienrestore und Sicherheitsnachbehandlung funktionieren, Betriebs-/Recoveryziele mit realen Messwerten und Grenzen dokumentiert. Das ist noch keine pauschale Reifeaussage für sämtliche Fachfunktionen eines Produkts. + +## 17. Prüfstand dieser Lieferung + +Erstellt wurde ausschließlich dieses neue Blueprintdokument. Quellen-/Vorgängerdokumente und Produktrepos wurden nicht bearbeitet. Keine DBverbindungen, Credentials, persönlichen Sicherungen, Live-APIaufrufe, Migrationen, Deployments, Runner-/Branchschutzänderungen, Paketinstallationen oder Anwendungstestläufe. Alle angegebenen Betriebsprogramme, JSON-/Pythonbeispiele und Tests sind Spezifikation V/K. + +Dokumentprüfung: lokale Linkziele/-zeilen, Syntax der Python-/JSONbeispiele, Abdeckung von R1/R2, Gate-/Zielschutz, Backup-/Medienkonsistenz, Restore-/Securityhooks, Testmatrix und Cursorauftrag. Dies validiert das Dokument, nicht die geplante Anwendung. Der tatsächliche Gitea-/Host-/Backupzustand bleibt unbekannt, bis die ausdrücklich benannte spätere Integration ihn erfasst. + +Externe Gegenprüfung beschränkte sich auf offizielle Gitea-, PostgreSQL-, Docker- und age-Primärquellen für die benannten technischen Details. Es gab keine neue umfassende Recherche. Quellcode und Dokumentation sind statische Referenzen I; der Blueprint bleibt V/K, ohne T-Gesamtnachweis. + +### 17.1 Lokaler Quellstand + +Lesestand 16.10.2026. Hashes über vollständige Dateien; Git-HEAD allein behauptet keinen sauberen Checkout. + +- `shinkan-jinkendo`: Git-HEAD `f10c28e5cdcef52cc44e953a8494b4bbe35b77fe` +- `kairo-jinkendo`: Git-HEAD `ea0aa18b8dd9a55f663a996d74e63b7e3ee0dc16` +- `Kansho`: Git-HEAD `89d149684eab9211d6ef21181d018de097a61783` +- `mitai-jinkendo`: Git-HEAD `95453d548a2113555cd7e8f01fbbf267cbe34f3f` + +| Gezielt verwendete Produktquelle | SHA-256 | +|---|---| +| [shinkan-jinkendo/backend/scripts/security_release_checks.py](C:/Dev/shinkan-jinkendo/backend/scripts/security_release_checks.py) | `cc1288ea039fb110c82b989fd3f05ee2a39bd031e6b1aece15af0d9b276666b2` | +| [shinkan-jinkendo/.gitea/workflows/test.yml](C:/Dev/shinkan-jinkendo/.gitea/workflows/test.yml) | `d4f63d4f41de2d29c1b05aa23ac772caba8e089a77cb401dcb0c60600e3ee0ec` | +| [shinkan-jinkendo/.gitea/workflows/deploy-prod.yml](C:/Dev/shinkan-jinkendo/.gitea/workflows/deploy-prod.yml) | `b874b49c0efc29e85794d4c557bb7c6c7fce928846421d2f38391451ce784b2a` | +| [kairo-jinkendo/.gitea/workflows/test.yml](C:/Dev/kairo-jinkendo/.gitea/workflows/test.yml) | `e4d4d02aac13835ff82e4af7e96d3fc1c39d8fd3e736c51188bcd0dc64897591` | +| [kairo-jinkendo/.gitea/workflows/deploy-dev.yml](C:/Dev/kairo-jinkendo/.gitea/workflows/deploy-dev.yml) | `c28ef680d325fa52d6361050bc5e3905e81aadc0de7206f9b1304c5f36e2b8aa` | +| [kairo-jinkendo/.cursor/rules/kairo-deployment-testing.mdc](C:/Dev/kairo-jinkendo/.cursor/rules/kairo-deployment-testing.mdc) | `54d7026512de97a3cb17461f44ba1d6256984b861dceb0af5511809bcadf8830` | +| [Kansho/.gitea/workflows/test.yml](C:/Dev/Kansho/.gitea/workflows/test.yml) | `9454086f07554af9824280e4a1b4c253f3667b4bf10f2084c1d6c8adce39d574` | +| [Kansho/scripts/backup-postgres.sh](C:/Dev/Kansho/scripts/backup-postgres.sh) | `d80060974eeffedbfd2930d83b8a2be1488790135d426a1570fb418bc729a729` | +| [Kansho/backend/local_backup.py](C:/Dev/Kansho/backend/local_backup.py) | `be02a9e2d1f6c3c5f01acf7b8d8a602d0ca87cf2879eda58adff27a6ffc8d9ff` | +| [Kansho/docs/architecture/technical/runtime_and_deploy.md](C:/Dev/Kansho/docs/architecture/technical/runtime_and_deploy.md) | `00cea03867fb09c1bb17dae908b629eb22d512d8f79082a1a005ee7e0e7d58dc` | +| [Kansho/docs/architecture/technical/security.md](C:/Dev/Kansho/docs/architecture/technical/security.md) | `69e6c39111072e45dc54bfa86d98c2be75e9a9c6ba735acfdf4fa6b1529ae747` | +| [mitai-jinkendo/scripts/backup/mitai_pg_dump.sh](C:/Dev/mitai-jinkendo/scripts/backup/mitai_pg_dump.sh) | `44b16b5ed7c48b25cec1deb6dce349ab9a6b265a3ec32b6b094099c7f61f7a6f` | +| [mitai-jinkendo/.gitea/workflows/deploy-prod.yml](C:/Dev/mitai-jinkendo/.gitea/workflows/deploy-prod.yml) | `9eeae07067cb2f4bbba050b6eafdc05ec9679d5e5425bcc8cc166a0da1caf179` | + +**Ende dieses Blueprintauftrags. Kein weiterer Blueprint und keine Implementierung werden automatisch gestartet.** diff --git a/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md new file mode 100644 index 0000000..f280c18 --- /dev/null +++ b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md @@ -0,0 +1,193 @@ +# A – Jinkendo Technical Reference Architecture + +**Phase 3.2 · v0.3 · 16.10.2026 · vorgeschlagener Referenzstandard für neue Anwendungen** + +Empfohlen wird eine modulare FastAPI-Anwendung mit React/Vite, PostgreSQL, expliziten Transaktionen und einem Gitea-Ablauf mit verpflichtenden Release-Gates und nachvollziehbarer Zuordnung von Quellstand, Build und getesteter Produktionsversion. Die Module bleiben zunächst produktlokal. Authentifizierung, Datenraum, Berechtigungen, KI und Subscriptions werden über klar definierte Grenzen angebunden. + +Die Referenz wird **pro Mechanismus** ausgewählt: Mitai für Prompt-/Workflow-Ausführung und Registry-Verträge, Shinkan für Nutzer-/Vereinssichten und Zugriffsschutz, Kanshō für private KI-Daten und Maskierung. Kairo ergänzt einzelne Struktur-, Konfigurations- und Maschinenzugriffsmuster. Keine Anwendung ist als Ganzes die führende oder am besten betriebsbewährte Referenz. Die folgende Foundation ist eine gezielte Synthese mit expliziten Anpassungen. + +Diese Empfehlung ist keine Freigabe für Produktionsänderungen. ADR-01 bis ADR-14 und Reuse First gelten als beschlossen; ADR-15 und ADR-16 bleiben offen. Bestehende Apps werden durch dieses Dokument nicht zur Migration verpflichtet. Die visuelle Gestaltung gehört weiterhin in die Frontend Design Guideline. + +**Lesereihenfolge:** A definiert die technischen Verträge, [B](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md) macht daraus einen Implementierungsauftrag, [C](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md) begründet die Auswahl und nennt drei offene Produkt-/Betriebspunkte. + +## A0 – Verbindliche Verträge, technische Defaults und Nachweis + +Die Zielarchitektur in A und ihre Ausgestaltung in B sind ein **vorgeschlagener technischer Standard**. Die bereits beschlossenen Architekturverträge gelten unabhängig davon; technische Detailvorschläge werden durch dieses Dokument nicht automatisch zu weiteren beschlossenen Familienverträgen. + +| Einordnung | Geltung in dieser Referenz | +|---|---| +| **Verbindliche Architekturverträge** | Verifizierte Identität und Datenraumgrenzen; Fail-Closed-Autorisierung neuer geschützter Funktionen; wirksame Objekt-/Scopeprüfung; sichere atomare Transaktionsgrenzen; verlässlicher Migrations-/Erfolgsnachweis; Secret-/Privacy-Grenzen; verpflichtende Release-Gates und eindeutige Zuordnung zur produktiven Version. Maßgeblich bleiben die beschlossenen ADRs und produktbezogenen Schutzgrenzen. | +| **Technische Defaults** | Bevorzugte Framework-/Versionslinien in A1, Verzeichnis- und Dateidetails in A2/B1, konkrete Modul-/Hilfsnamen, numerische Listenlimits in A4, Poolgrößen und Zeitbudgets in A5, Clienttimeout in A7/B3 sowie Artefakttransport und bevorzugtes Build-Verfahren in A9/B5. Sie sind begründet anpassbare Ausgangspunkte. | + +Bei begründetem Produktbedarf dürfen Defaults angepasst werden. Grund, gewählter Wert bzw. Ersatz und geeigneter Funktions-/Kompatibilitätsnachweis werden kurz im Produktauftrag oder in der Produktkonfiguration festgehalten; dafür wird kein neuer ADR oder zusätzlicher Freigabezyklus verlangt. Begründete Varianten dürfen keinen verbindlichen Schutz-, Transaktions- oder Releasevertrag abschwächen. Anpassbare Verzeichnisnamen ändern beispielsweise nicht die Verantwortungsgrenzen; anpassbare Timeouts beseitigen keine wirksamen Ressourcenlimits. Die gewählten Versionen müssen weiterhin unterstützt und untereinander kompatibel sein. Nach außen veröffentlichte API-Verträge bleiben gegenüber ihren Clients kompatibel, auch wenn interne Details angepasst werden. + +Für die folgenden Abschnitte gilt diese Nachweiskennzeichnung: + +| Nachweisgrad | Bedeutung / aktueller Stand | +|---|---| +| **V – Vorgeschlagener technischer Standard** | Zielentscheidungen und Implementierungsvorgaben in A/B; technisch konkret, noch keine ausgeführte Referenzimplementierung. | +| **I – Bereits vorhandene Implementierungsreferenz** | Benannte Produktdateien und Mechanismen aus v0.2; statisch untersuchte Vorbilder. Vorhandener Code oder eine Testdatei allein ist kein erfolgreicher Testnachweis. | +| **T – Tatsächlich durch Tests validierte Lösung** | Nur mit konkretem Testumfang, bestandenem Ergebnis, Quell-/Buildstand und Ausführungsumgebung. Für die hier vorgeschlagene Foundation wird kein solcher Gesamtnachweis behauptet; v0.3 führt keine Tests aus. | +| **K – Noch nicht integrierte oder getestete Kombination** | Die produktübergreifende Foundation-Synthese, Adapterkombinationen und kleinen Codebeispiele. Zusammenwirken und Versionskompatibilität müssen bei der Umsetzung erst validiert werden. | + +Eine Passage kann V und K zugleich sein; ein I-Verweis hebt sie nicht automatisch auf T. B beschreibt einen künftigen Aufbau und dessen Abnahmebedingungen, keine bereits produktionsreife Referenzimplementierung. Die Versions-/Supportangaben aus A1 werden als bisheriger Dokumentstand übernommen, in v0.3 nicht erneut recherchiert. + +## A1 – Technologiestack und zulässige Varianten + +| Bestandteil | Technischer Default für eine neue App | Verwendung | +|---|---|---| +| Backend | Python 3.12, FastAPI, Uvicorn, Pydantic 2 | HTTP, Validierung, Dependency Injection; überwiegend synchrone DB-Anwendungsfälle | +| Datenbank | PostgreSQL 16, Psycopg 3 und dessen `psycopg_pool` | Parametrisiertes SQL; begrenzter Pool; kein ORM als Foundation-Abhängigkeit | +| Frontend | React/React DOM 19.3, JavaScript/JSX mit JSDoc, Vite 8.3, React Router 8.4 im Data Mode | SPA; explizite Routen, Loader, Actions und Modulregistrierung | +| Build | Node.js 24 LTS, npm, Docker Compose | Statischer Frontend-Build, Backend-Image, bestehender Reverse-Proxy mit TLS | +| Tests | pytest, HTTPX/TestClient; Vitest 5, jsdom, React Testing Library; Playwright | Unit-, HTTP-/DB-Vertrags-, Komponenten- und wenige Browsertests | +| Abhängigkeiten | npm-Lockfile; Python-Lockfiles mit `pip-tools` als Build-Werkzeug | Exakte, überprüfbare Auflösung einschließlich transitiver Pakete und Python-Pakethashes | +| Betrieb | Gitea Actions, Docker Compose, strukturierte Standard-Logs | Bestehende Betriebsform; kein neuer Plattformdienst | + +Versionen sind **Versionslinien, keine erzeugten Paket-Lockfiles**. Beim Anlegen der App werden stabile Patchstände und kompatible Plugins aufgelöst, exakt gelockt und gemeinsam getestet. FastAPI bleibt in der stabilen 0.x-Linie, Psycopg in 3.x; Pydantic in 2.x. Keine Vorabversion aus einer „latest“-Dokumentation installieren. Runtime-/Build-Basisbilder werden mit Version und Digest festgehalten. Starlette und andere transitive Pakete nicht unabhängig gegen FastAPIs Anforderungen pinnen. [FastAPI-Versionierung](https://fastapi.tiangolo.com/deployment/versions/) + +Die Python-Locks werden mit `pip-compile --generate-hashes` für die Zielumgebung erstellt und mit Hashprüfung installiert; ihre Erzeugung ist kein Runtime-Schritt. [pip-tools](https://pip-tools.pypa.io/en/stable/) + +Die neuere Frontend-Basis ist eine gezielte Aktualisierung desselben Stacks: Vite 5 wird offiziell nicht mehr unterstützt, Node 20 ist EOL. React 19.3 und Router 8.4 sind die beim Nachschlagen aktuellen stabilen Linien; Vitest nennt passende Mindestanforderungen für Vite/Node. PostgreSQL 16 bleibt unterstützt. [Vite](https://vite.dev/releases), [Node](https://nodejs.org/en/about/previous-releases), [React](https://react.dev/versions), [Router](https://reactrouter.com/start/data/installation), [Vitest](https://vitest.dev/guide/), [PostgreSQL](https://www.postgresql.org/support/versioning/) + +**Bestandsvarianten:** React 18/Router 6, Psycopg 2 und heutige Projektpfade bleiben bei Erweiterungen nutzbar; der Änderungsschnitt muss die Verträge dieses Dokuments erfüllen. Eine Versionsmigration ist ein separater Auftrag. Kanshōs SQLite-Adapter bleibt eine lokale Produktvariante, kein zweites Standard-Backend für neue Apps. Asynchrone DB-Zugriffe, ORM, globaler State-Store, PWA oder Worker kommen erst bei einem konkreten Anwendungsfall hinzu. Kein SSR, SSO oder Billing-Service auf Vorrat. + +## A2 – Projektstruktur und Abhängigkeiten + +**Technischer Strukturdefault:** Eine Anwendung bleibt ein Repository mit Backend, Frontend, Migrationen, Tests und Deploymentdefinitionen. Verzeichnisdetails und Zuschnitt dürfen gemäß A0 angepasst werden; die Verantwortungs- und Schutzgrenzen bleiben erhalten. Backend und Frontend werden getrennt gebaut. Innerhalb des Backends hat jedes Fachmodul Router, Schemas, Service und Repository. Kleine reine Berechnungen können im selben Modul bleiben; zusätzliche Schichten entstehen nur für eine tatsächliche Zuständigkeit. + +```mermaid +flowchart LR + UI[Route / Komponente] --> API[Frontend API-Modul] + API --> Router[FastAPI Router] + Router --> Service[Anwendungsservice] + Service --> TX[Transaktion / Repository] + TX --> PG[(PostgreSQL)] + Service --> Ports[Access / Entitlement / KI-Ports] + Root[Composition Root] -. verdrahtet .-> Router + Root -. verdrahtet .-> Service + Root -. verdrahtet .-> Ports +``` + +Die Abhängigkeitsrichtung lautet `Router → Service → Repository/Port`. Repositories kennen SQL, Services kennen den Anwendungsfall, Router kennen HTTP. Nur der Composition Root kennt alle konkreten Implementierungen. `core` importiert keine Fachmodule; Fachmodule importieren keine fremden Router. Benötigte fremde Funktionalität läuft über eine explizite Service-Schnittstelle. Keine generische Basisklasse oder Repository-Abstraktion ohne zweiten realen Bedarf. + +Die Zielaufteilung ist ein Referenzentwurf aus vorhandenen Teilmechanismen, keine unveränderte Kairo-Architektur. Mitai zeigt [explizit übergebene Cursor](C:/Dev/mitai-jinkendo/backend/data_layer/activity_persistence_orchestrator.py:171) und registrierte Resolver; Kairo zeigt gesonderte Router/Services. Sein [Router](C:/Dev/kairo-jinkendo/backend/routers/actions.py:8) greift jedoch sowohl auf Services als auch auf Read Models zu, der [Data Layer](C:/Dev/kairo-jinkendo/backend/data_layer/actions.py:9) importiert private Service-Helfer und führt selbst SQL aus. Das ist kein durchgängig eingehaltenes `Router → Service → Repository`. Zusätzliche Connections in Serviceprüfungen werden ebenfalls nicht übernommen. Für neue Anwendungsfälle gilt A3; die genaue Zielstruktur steht einmalig in B1. + +## A3 – Backend, Dependency Injection und Transaktionen + +`create_app(settings, providers)` baut eine App ohne DB-Migration, Seed oder Provideraufruf beim Modulimport. `bootstrap` registriert konkrete Module und bindet ihre Abhängigkeiten. FastAPI `Depends` liefert Services und den verifizierten Requestkontext; es ist kein Service-Locator innerhalb der Fachlogik. Poolöffnung und Poolschluss gehören in den App-Lifespan. + +Mit synchronem Psycopg verwenden DB-Router normale `def`-Handler. Blockierende Treiber werden nicht direkt aus einem `async def`-Handler aufgerufen. Echte asynchrone I/O-Pfade erhalten einen durchgehend passenden Adapter; reine Hilfsfunktionen wechseln ihren Ausführungsmodus nicht automatisch. [FastAPI-Ausführungsmodell](https://fastapi.tiangolo.com/async/) + +**Transaktionsvertrag:** Ein Anwendungsservice öffnet genau einen Transaktionskontext für eine atomare Operation. Alle beteiligten Repositories, veränderungsrelevanten Scope-Prüfungen, Quotenbuchungen und erforderlichen Audit-Einträge nutzen diese Verbindung. Normaler Blockabschluss committed, jede Exception rollt zurück; Rückgabe an den Router erfolgt erst danach. Repositories committen nicht. Kein nachgelagerter Commit in einer Request-Dependency nach Rückgabe der HTTP-Antwort. + +Lesepfade schließen ihren kurzen Transaktionskontext ebenfalls zuverlässig. Externe HTTP-/KI-Aufrufe liegen außerhalb offener DB-Transaktionen. Falls eine spätere Operation Reservierung/Bestätigung benötigt, erhält sie einen expliziten Zustands-/Idempotenzvertrag; ein DB-Commit wird nicht als Atomarität mit einem externen Anbieter dargestellt. + +Die gemeinsame Cursor-Nutzung und SAVEPOINT-Lektion aus Mitais [Import-Leitfaden](C:/Dev/mitai-jinkendo/.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md:27) wird übernommen. Standard ist vollständiges Rollback. Nur ein ausdrücklich als teilweise erfolgreich definierter Batch darf einzelne Zeilen über Savepoints isolieren. + +Fachfehler sind kleine explizite Exception-Typen, etwa `NotFound`, `PermissionDenied` und `Conflict`. Nur der HTTP-Adapter übersetzt sie in Antworten. Bekannte Constraint-Verletzungen werden gezielt übersetzt; unbekannte DB-Fehler bleiben Serverfehler. Kein pauschales `except Exception: return []` und kein stilles Weiterarbeiten nach einem DB-Fehler. + +## A4 – API Contract + +Neue Fach-APIs beginnen unter `/api/v1`. JSON-Felder verwenden `snake_case`, IDs sind opake Zeichenketten, Zeitpunkte ISO 8601 in UTC mit `Z`; reine Datumswerte bleiben `YYYY-MM-DD`. Geldwerte sind Dezimalzeichenketten plus Währung. Request-Modelle verbieten unbekannte Felder. Output-Modelle erlauben nur explizit freigegebene Felder; DB-Zeilen werden nicht direkt serialisiert. + +| Vertrag | Festlegung | +|---|---| +| Erfolg | Einzelobjekt direkt; Listen `{items, next_cursor}`; keine zusätzliche globale `data`-Hülle | +| Listen | Numerische Defaults: `limit` 50, Maximum 200; begründet anpassbar. Begrenzte Abfragen, validierter Cursor und stabile Sortierung mit ID als Tiebreaker bleiben der Vertrag. | +| Status | 201 plus `Location` für Anlage; 200 für Lesen/Ändern; 204 ohne Body für Löschen | +| Fehler | RFC-9457-Problem-Details mit `type`, `title`, `status`, sicherem `detail`, `instance`; Erweiterungen `code`, `request_id`, optional `errors` | +| Feldfehler | `errors: [{path, code, message}]`; keine Rohwerte, Passwörter oder Pydantic-`input`-Felder zurückgeben | +| Codes | 401 ohne gültige Identität; 403 fehlende Befugnis; 404 nicht sichtbares Objekt; 409 Konflikt; 422 ungültige Eingabe; 503 nicht verfügbare Abhängigkeit | +| Nachvollziehbarkeit | Server erzeugt Request-ID; Antwortheader `X-Request-ID`; nur validierte eigene Proxy-ID übernehmen | +| Änderung | Additiv innerhalb v1, inkompatible öffentliche Änderungen unter v2; OpenAPI-Vertragsdiff in CI | + +`type` ist eine stabile URI-Referenz, zum Beispiel `urn:jinkendo:problem:validation`; `code` ist ein stabiler Maschinenwert, kein übersetzter Text. Bei 500/503 werden interne SQL-/Provider-/Proxyinhalte nicht ausgegeben. [Problem Details](https://www.rfc-editor.org/rfc/rfc9457.html) + +`/health/live` prüft den Prozess, `/health/ready` Pool, kompatiblen Migrationsstand und erforderliche Adapter. Beide sind read-only, geben bei Fehlern nur einen sicheren Status aus und besitzen kurze Timeouts. Die Build-ID erscheint als `X-Build-Revision`; volle Releaseinformationen bleiben im Betriebsartefakt. Kein automatischer DB-Reparaturversuch über Health. + +## A5 – PostgreSQL, Connection-Handling und Migrationen + +Psycopg 3 ist bereits in [Kanshō](C:/Dev/Kansho/backend/requirements.txt) vorhanden. Übernommen wird der Treiber, **nicht** die SQLite-förmige SQL-Übersetzung. SQL verwendet native PostgreSQL-Platzhalter und parametrisierte Werte. Dynamische Bezeichner werden nur aus einer erlaubten Menge über `psycopg.sql` zusammengesetzt. Keine SQL-Fragmente aus Requestdaten. + +Ein threadgeeigneter `psycopg_pool.ConnectionPool` pro Backend-Prozess begrenzt Verbindungen. **Anpassbare technische Defaults:** ein Prozess, Pool 1–5, Wartezeit 3 Sekunden, höchstens 20 Wartende. Verbindungsaufbau 5 Sekunden; Standard-Statement 5 Sekunden, Lock-Wartezeit 2 Sekunden. Größere Aufgaben dürfen begründete eigene Zeitbudgets erhalten. Mehr Prozesse benötigen eine neue Connection-Budgetrechnung; keine automatische Poolvervielfachung ohne Grenze. + +Der Pool liefert `autocommit=True`-Verbindungen ausschließlich an den DB-Adapter. Dieser führt jeden fachlichen Zugriff in `connection.transaction()` aus und gibt die Verbindung sauber zurück. Poolerschöpfung wird 503; sie wird nicht durch unbegrenzte zusätzliche Verbindungen umgangen. [Psycopg-Pool](https://www.psycopg.org/psycopg3/docs/advanced/pool.html), [Transaktionskontexte](https://www.psycopg.org/psycopg3/docs/basic/transactions.html) + +**Migrationsverfahren:** vorhandenes SQL-Dateimuster gezielt härten, kein neuer Alembic-/ORM-Wechsel. Ein expliziter CLI-Lauf vor Prozesswechsel verwendet eine getrennte Migrationsrolle und eine ungepoolte Verbindung. Runtime darf kein DDL ausführen und ist weder Superuser noch `BYPASSRLS`-Rolle. + +Neue IDs folgen `20261016T120000Z_short_name.sql`; vollständige IDs und Zeitpräfixe sind eindeutig, Reihenfolge ist lexikalisch. Ein Ledger `schema_migrations(id, sha256, applied_at, build_revision)` ist maßgeblich. Der Runner: + +1. Validiert Dateinamen und Duplikate im Paket. +2. Serialisiert Ledgerprüfung und Ausführung mit einem PostgreSQL-Session-Advisory-Lock auf derselben Verbindung und einem festen dokumentierten Schlüssel; nach einem begrenzten Wartebudget bricht er ab (technischer Default: 60 Sekunden). Auf leerer DB legt der Runner unter diesem Lock ausschließlich sein Ledger an. Danach liest er den Stand und prüft sämtliche angewandten Prüfsummen; angewandte, aber fehlende Dateien sind ein Fehler. +3. Führt jede noch offene SQL-Datei und ihren Ledger-Eintrag **in derselben Transaktion und Verbindung** aus. Scheitert eine Datei, endet der Lauf ungleich null; frühere erfolgreich committete Dateien bleiben angewandt. +4. Gibt den Lock im `finally` frei und schließt die Verbindung. Ein Wiederanlauf überspringt nur nachweislich erfolgreiche Dateien. + +SQL-Dateien enthalten weder eigene Transaktionssteuerung noch psql-Metabefehle. Parameterlose SQL-Dateien werden als Ganzes ausgeführt, nicht per Semikolon zerlegt. Dollar-quoted Funktionen müssen funktionieren. Nichttransaktionale DDL benötigt einen separaten geplanten Betriebsschritt. Entwicklungsdaten-Seeds laufen gesondert und niemals automatisch in Produktion. [Psycopg: mehrere Statements](https://www.psycopg.org/psycopg3/docs/basic/from_pg2.html) + +SQL-Dateien und Runner sind in [Shinkan](C:/Dev/shinkan-jinkendo/backend/run_migrations.py:194), [Mitai](C:/Dev/mitai-jinkendo/backend/db_init.py:155) und [Kairo](C:/Dev/kairo-jinkendo/backend/run_migrations.py:110) vorhanden. Keiner dieser Runner wird hier als vollständig passende Standardimplementierung ausgezeichnet. Der Vertrag kombiniert das bestehende SQL-Verfahren mit kleinen gezielten Korrekturen; insbesondere wird Kairos separater SQL-Prozess mit späterem Ledger-Commit nicht übernommen. Historische IDs bestehender Apps werden nicht umbenannt. Neue Apps starten mit einer Initialmigration; Bestandsübernahmen benötigen eine gezielte Baseline. Expand/Contract hält das vorige Image bei einem notwendigen Rollback möglichst lauffähig; kein automatisches produktives „Down“. + +## A6 – Konfiguration, Secrets und technische Funktionen + +Eine zentrale Pydantic-Settings-Struktur validiert beim Start eine explizit zusammengestellte Prozessumgebung. `APP_ENV` ist verpflichtend und genau `development`, `test` oder `production`; unbekannt bedeutet Startfehler. Benötigt werden Produktkennung, öffentliche Origin, Runtime-DB-Verbindung und Buildrevision. Produktionsmodus verlangt HTTPS-Origin und eine vollständige Schutzkonfiguration. + +Secrets kommen aus der bestehenden Betriebsbereitstellung als Prozessumgebung oder gemountete Secret-Datei, nie aus dem Frontend, einem Seed oder einem Default-Passwort. Nur der Secret-Adapter kennt Rohwerte. Keine eigene produktive `.env`-Schreibfunktion. Lokale Entwicklungsdateien dürfen durch die Startumgebung injiziert werden; die App lädt sie nicht still beim Import nach. Migrationszugangsdaten werden nicht dem laufenden Backend überlassen. + +Technische Feature-Schlüssel sind registriert und typisiert. Unbekannte Schlüssel sind Fehler; fehlende optionale Funktionen bleiben aus. Auth-, Scope- und Pflichtprüfungen sind nicht deaktivierbare „Features“. Anbieter-/Netzwerkfunktionen sind ohne vollständige Konfiguration aus. Kairos [Secretreferenz-Prüfung](C:/Dev/kairo-jinkendo/backend/config_service.py:17) ist das Vorbild für DB-Konfiguration ohne Klartext-Secrets. Kanshōs [Fallback auf development](C:/Dev/Kansho/backend/env_loader.py:28) wird nicht übernommen. + +Logs verwenden `logging` mit kleinem produktlokalem JSON-Formatter: Zeit, Level, Ereigniscode, Request-ID, Modul und Dauer. Keine Bodies, Prompts, Cookies, Zugangsdaten oder vollständigen Querystrings. Erforderliche Fachaudits nennen Subject-/Actor-ID, Scope, Aktion, Ressourcen-ID und Ergebnis; bei DB-Änderungen teilen sie deren Transaktion. Fehlgeschlagene Autorisierungsversuche bekommen einen getrennten sicheren Security-Logpfad. Kairos [Audit-Helfer](C:/Dev/kairo-jinkendo/backend/services/audit.py:11) liefert das Ereignismuster, nicht die unabhängige Audit-Connection. + +## A7 – Technische Frontend-Architektur + +Eine explizite Modulregistrierung liefert Routen und Navigation; doppelte IDs oder Pfade brechen den Aufbau ab. Data Router wird einmal außerhalb des React-Renderns erzeugt. Routen besitzen Loader/Actions und lokale Fehlergrenzen. Kein Router-Neuaufbau beim Wechsel des gewählten Datenraums. [Router Data Mode](https://reactrouter.com/start/data/installation) + +Ein gemeinsamer `request`-Client kapselt ausschließlich Transport und Fehler. Fachliche API-Funktionen liegen im jeweiligen Modul. Transportdefault: relative Same-Origin-URLs und 15 Sekunden Timeout; begründete Anpassungen folgen A0. Cookie-Credentials, AbortSignal, Prüfung von Content-Type/Status und Unterstützung von 204 gehören zum beschriebenen Transportvertrag. Keine Session in Local Storage oder URLs. Keine ungeprüfte HTML-Fehlerausgabe und keine automatischen Wiederholungen von Schreiboperationen. Cookie/CSRF- und Loginlogik bleibt im Auth-Adapter. + +Serverdaten gehören in Route-Loader bzw. modulbezogene Hooks. Formulare und flüchtiger UI-Zustand bleiben lokal in `useState`/`useReducer`. Ein kleiner Session-/Scope-Store enthält nur bestätigten Kontext und einen monotonen `epoch`-Wert. Bei Logout oder Scopewechsel werden Requests abgebrochen, personenbezogene Ergebnisse verworfen und Loader neu ausgeführt. Antworten einer alten Epoche dürfen nicht in die neue Ansicht gelangen. Ein weiterer Cache ist kein Foundation-Bestandteil. + +Mitai ist das primäre Vorbild für explizite Registrierung: Die [Placeholder-Registry](C:/Dev/mitai-jinkendo/backend/placeholder_registry.py:169) verweigert doppelte Schlüssel und bindet Metadaten/Resolver; die [UI-Registry](C:/Dev/mitai-jinkendo/frontend/src/widgetSystem/dashboardWidgetRegistry.jsx:18) verbindet Komponenten mit einer Fehlergrenze. Die Duplikatsperre der ersten ist bei Übernahme auch für die zweite erforderlich. Kairos [Slice-Lader](C:/Dev/kairo-jinkendo/frontend/src/registry/operatingSliceLoaders.js:53) sind eine ergänzende Referenz für tatsächlich benötigtes selektives Nachladen; ihr stilles `catch → null` wird nicht kopiert. Aus Shinkan stammen [Rücknavigation/Dirty-Form-Schutz](C:/Dev/shinkan-jinkendo/frontend/src/hooks/useUnsavedChangesBlocker.js:8). Deren Routerannahmen werden auf der neuen Version getestet. + +SPA-Dateien können lange mit Hash gecacht werden; `index.html` wird revalidiert. Persönliche API-Antworten erhalten `Cache-Control: no-store`. PWA ist optional; wenn vorhanden, werden persönliche APIs nicht im Service Worker gecacht. Kanshōs [NetworkOnly-Konfiguration](C:/Dev/Kansho/frontend/vite.config.js:25) dient als Richtung, deren tatsächliches URL-Matching muss getestet werden. Gestaltung und visuelle Komponentenverträge werden hier nicht familienweit festgelegt. + +## A8 – Schnittstellen zu Security, Datenraum, KI und Subscriptions + +| Grenze | Foundation-Vertrag | Bewusst nicht vorweggenommen | +|---|---|---| +| Identität | `PrincipalResolver` liefert verifizierte eigene User-/Maschinenidentität; kein Profil aus Clientheadern | Login-, MFA-, Recovery- und Session-Spezialimplementierung | +| Datenraum | `ScopeResolver` validiert eine Auswahl gegen Identität/Mitgliedschaft; Service/Repository verlangen expliziten Scope | Universelle Tenanttabelle oder RLS für alle Produkte | +| Zugriff | `AccessPolicy` prüft aktuelle Befugnis und Objektsichtbarkeit, standardmäßig verweigernd | Dauerhafter Probe-Modus oder UI als Sicherheitsgrenze | +| Subscriptions | `EntitlementPolicy` prüft produktlokale Features/Quoten zusätzlich zur Befugnis | Zentrales Billing oder Vermischung von Kaufstatus und Objektberechtigung | +| KI/Agenten | `ModelGateway`/Tool-Adapter erhält autorisierten minimalen Kontext; Tool ruft denselben Service auf | Externe Freigabe einzelner Anbieter, Memory-Kern, autonome DB-Zugriffe | + +**Konkrete Herkunft dieser Grenzen:** Shinkans [Sichtbarkeitsfunktion](C:/Dev/shinkan-jinkendo/backend/tenant_context.py:57) trennt offiziell, privat und Verein einschließlich aktiver Mitgliedschaft; [Kontozustände](C:/Dev/shinkan-jinkendo/backend/account_lifecycle.py:26), Capabilities und Security-Regressionen ergänzen den Zugriffsschutz. Dieser fachlich konkrete Bestand ist die primäre Referenz für Scope-/Policy-Adapter, keine bloße Navigationshilfe. + +Für KI-Funktionen wird zuerst Mitais vorhandene [Workflow-Ausführung](C:/Dev/mitai-jinkendo/backend/workflow_executor.py:39), [Promptauflösung](C:/Dev/mitai-jinkendo/backend/prompt_executor.py:18) und [Placeholder-Registry](C:/Dev/mitai-jinkendo/backend/placeholder_registry.py:159) auf passende Wiederverwendung geprüft. Kanshō liefert die [Maskierung](C:/Dev/Kansho/backend/privacy_gateway.py:705) und [Prüfung vor dem Anbieteraufruf](C:/Dev/Kansho/backend/privacy_gateway.py:1257). Der Zielfluss lautet bei entsprechendem Bedarf: autorisierter Kontext → Prompt-/Workflow-Laufzeit → produktbezogene Privacy-Prüfung/Maskierung → Anbieter. Diese Kombination ist ein vorgeschlagener Schnittstellenfluss, keine bereits gemeinsam getestete Integration. Die Foundation importiert nicht vorsorglich einen Workflow-Editor oder jede Privacy-Implementierung in jede App. + +`RequestContext` trägt `request_id`, verifizierten Principal und ausgewählten Scope. Ein Client darf den Scope **auswählen**, aber nie seine Berechtigung oder Identität bestimmen. Keine Auswahl des ersten Profils/Clubs als stiller Sicherheitsfallback. Personen-, Club- und Organisationsräume sind Varianten dieses Vertrags, keine einheitliche Fachdomäne. + +Neue Same-Origin-Browser-Apps planen serverseitige Sessions mit `HttpOnly`, `Secure`, geeignetem SameSite sowie CSRF-/Originprüfung für unsichere Methoden. Fehlende Adapter sperren geschützte Funktionen; Testidentitäten existieren ausschließlich in Testverdrahtung. Separate begrenzte Agentenidentitäten werden erst bei echtem Maschinenbedarf ergänzt. Kanshōs lokale Privacy-Grenzen bleiben verbindlich, einschließlich Detect-/Generate-Trennung und Prüfung des vollständigen Egress. + +Risikobasierte Isolation folgt ADR-06: App-Policies plus Constraints und eingeschränkte Runtime-Rolle sind die kleine Basis; vertrauliche Mehrraumprodukte müssen zusätzlichen RLS-Schutz ausdrücklich prüfen. Bei RLS gehört DB-Kontext transaktionslokal gesetzt und darf nicht zwischen Poolnutzern überleben. Fremde Eltern-/Kindreferenzen müssen auch durch passende DB-Constraints verhindert werden. + +## A9 – Testing, Deployment und Reuse + +Die erforderlichen Mindestnachweise und ihre technischen Umsetzungsvorschläge (Befehle und Abläufe) stehen in B4/B5; konkrete Pfade und Befehle dürfen im Rahmen von A0 konsistent angepasst werden. Grundsatz der technischen Umsetzung: isolierte PostgreSQL-Testdaten, echte Negativtests, Import-/OpenAPI-Prüfung, Frontend-Fehler-/Scopewechseltests und ein kleiner Browserdurchlauf gegen das tatsächlich gebaute Image. Verpflichtende DB-Suiten dürfen weder vollständig skippen noch durch fehlende Konfiguration still als erfolgreich gelten. + +**Verbindlicher Releasevertrag gemäß ADR-11:** Der Weg bleibt `develop → Dev → Tests → bewusste Freigabe → main → Prod`. Pflicht-Gates müssen vor der Produktionsumschaltung bestanden sein. Quellstand, Build-Eingaben, Testläufe und tatsächlich eingesetzte Artefakte müssen eindeutig zusammengehören. Ein nachgelagerter Health-Smoke ersetzt das Release-Gate nicht. Die bewusste menschliche Produktionsfreigabe bleibt erhalten. + +| Technische Variante | Umsetzung / Nachweis | +|---|---| +| **R1 – Bevorzugter Default: Build once, deploy many** | Die in Dev qualifizierten Backend-/Frontend-Artefakte werden unverändert nach Prod übernommen. Hashes/Digests und Buildrevision binden Test und Deployment; kein weiterer Build ist für diese Variante nötig. | +| **R2 – Zulässige ADR-11-Variante: kontrollierte separate Builds** | Dev- und Prod-Artefakte dürfen getrennt aus nachvollziehbaren Quellständen und reproduzierbar festgehaltenen Build-Eingaben entstehen. Lockfiles, Build-Rezept, Toolchain/Basisimages und erlaubte öffentliche Build-Parameter werden dokumentiert. Der konkrete Prod-Build erhält vor der Umschaltung seine erforderlichen Tests/Gates und eine eigene Artefakt-/Buildkennung. Ein grüner Dev-Build allein qualifiziert kein neu gebautes Prod-Artefakt. Unterschiedliche Artefakthashes zwischen Dev und Prod sind dabei zulässig. | + +In beiden Varianten verknüpft der Releasenachweis getesteten Quell-/Buildstand, menschlich freigegebenen main-Stand und tatsächlich deployte Artefakte. Bei Merge-Commits wird die Beziehung über Commit und Source-Tree nachgewiesen. Der Default ist ein mit dem qualifizierten Stand identischer Tree; abweichender Produktionsquellstand oder abweichende Build-Eingaben benötigen die passenden dokumentierten Gate-Ergebnisse für den konkreten Kandidaten, keine ungeprüfte Gleichsetzung mit dem Dev-Lauf. Reproduzierbarkeit ersetzt diese Tests nicht. + +Default für den Artefakttransport sind Docker-Image-Archive mit SHA-256 und Release-Manifest über die vorhandene Ablage; eine vorhandene Gitea-OCI-Registry mit Digestbindung ist ebenfalls zulässig. Keine Variante verlangt neue CI/CD-Infrastruktur. Die Freigabe erfolgt über geschützten `main` und bewusst angenommenen Release-PR, nicht über ein vermeintliches GitHub-Environment-Gate: Gitea ignoriert `jobs..environment`. [Gitea-Kompatibilität](https://docs.gitea.com/usage/actions/comparison/) + +**Reuse First konkret:** zunächst lokale Implementierung nach denselben Verträgen und Contracttests. Kandidaten für eine spätere Library sind API-Fehlernormalisierung, Registry-Validierung, Settings-/Problem-Modelle und Migrationsrunner. Extraktion erst bei zwei tatsächlichen Nutzern, stabilem Vertrag und Maintainer. Auth, KI-Policy und Subscriptions bleiben produktlokale Adapter; zentrale Dienste sind keine automatische Folge ähnlichen Codes. Keine gemeinsame Fachdatenbank, keine Imports zwischen laufenden Produkt-Repositories. + +Eine extrahierte Library erhält eine kleine öffentliche API, versionierte Releases, exakte Consumer-Pins und Contracttests in beiden Produkten. Ihr Maintainer verantwortet Sicherheitsfixes und eine erkennbare Update-/Kompatibilitätspolitik. Bis dahin werden übernommene lokale Bausteine mit Herkunft und relevanten Abweichungen dokumentiert; die Ähnlichkeit zweier Dateien allein löst keine Paketgründung aus. + +## Nachweisgrenze + +Basis sind [A01 des Inventars](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json), dessen Dependency-/Guardrailregister und konkrete ausgewählte Quellen. Die genannten Mechanismen sind statisch nachvollzogen. In v0.2 wurde die pauschale Vorrangstellung Kairos entfernt und die Herkunft von Registry-, Zugriffs- und Privacy-Verträgen konkretisiert. Produktreife, Umfang eines Mechanismus, Testquellen und tatsächliche erfolgreiche Nutzung bleiben getrennte Nachweise; es gibt keine belegte Gesamtrangfolge der Produkte. Nach A0 sind die Zielangaben V, die benannten Produktmechanismen I und die Foundation-Synthese samt Beispielen K. Ein T-Gesamtnachweis liegt nicht vor: Referenzkombination, Versionskompatibilität und Beispiele wurden nicht als Anwendung ausgeführt. Auch die neuen Release-Varianten sind dokumentierte Vorgaben, keine in diesem Auftrag getesteten Pipelines. Keine Produktdateien, Migrationen, Deployments oder Gitea-Einstellungen wurden verändert. diff --git a/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md new file mode 100644 index 0000000..4451f20 --- /dev/null +++ b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md @@ -0,0 +1,262 @@ +# B – Implementation Blueprint: Application Foundation + +**Phase 3.2 · v0.3 · 16.10.2026 · vorgeschlagener Blueprint, keine ausgeführte Referenzimplementierung** + +Dieser Blueprint setzt [A](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md) um. Er beauftragt hier keine Umsetzung. Ein späterer Coding-Auftrag darf damit die Foundation einer benannten App aufbauen; Fachfunktionen, vollständige Auth-/KI-/Subscription-Blueprints und Bestandsmigrationen gehören nicht automatisch dazu. + +**Geltung und Nachweis:** Dieser Blueprint ist V und als kombinierte Lösung K gemäß A0. Benannte Produktdateien sind I; geforderte Mindesttests sind noch keine T-Ergebnisse. Weder die Beispielausschnitte noch die gesamte Foundation sind hier integriert, getestet oder als produktionsreif nachgewiesen. Die tatsächliche Implementierung muss die erforderlichen Nachweise erst erbringen. + +**Verträge und Defaults:** Verbindlich bleiben insbesondere Datenraum-/Privacy-Grenzen, Fail-Closed-Zugriff, sichere Transaktionen und Release-Gates. Verzeichnisdetails, Modulnamen, Framework-/Versionslinien und numerische Einstellungen sind technische Defaults gemäß A0. Begründete Anpassungen sind im Produktauftrag bzw. in dessen Konfiguration kurz festzuhalten; keine zusätzliche Freigabeschleife. Die Aussage „gemäß A“ meint diese Unterscheidung, keinen starren Zwang zu jedem Beispielwert. + +## B1 – Auftrag und Zielstruktur + +**Auftrag an den Coding-Agenten:** Erstelle im ausdrücklich benannten neuen Produkt-Repository eine Foundation nach den Verträgen dieses Blueprints. Nutze den folgenden Verzeichnisbaum und die Versionslinien aus A1 als technische Defaults; begründete Anpassungen folgen A0. Löse stabile kompatible Patchstände auf und committe Lockfiles. Übernimm die unten genannten vorhandenen Mechanismen nach Anpassung ihrer Schnittstellen. Verändere keine anderen Produkt-Repositories. Erzeuge weder Beispiel-Fachprodukt noch allgemeines Framework. Lege leere Fachmodulordner erst mit der ersten echten Funktion an. + +```text +/ +├── AGENTS.md # verweist auf A/B und lokale Produktgrenzen +├── backend/ +│ ├── app/ +│ │ ├── __init__.py +│ │ ├── main.py # create_app; ASGI-Einstieg +│ │ ├── bootstrap.py # konkrete Module und Adapter verdrahten +│ │ ├── core/ +│ │ │ ├── settings.py +│ │ │ ├── context.py # Principal, ScopeRef, RequestContext +│ │ │ ├── ports.py # nur tatsächlich benötigte Adapterverträge +│ │ │ ├── errors.py +│ │ │ └── logging.py +│ │ ├── api/ +│ │ │ ├── dependencies.py +│ │ │ ├── problems.py +│ │ │ └── health.py +│ │ ├── db/ +│ │ │ ├── pool.py +│ │ │ ├── transaction.py +│ │ │ └── migrate.py +│ │ ├── modules// # später: router, schemas, service, repository +│ │ └── integrations/ # nur für tatsächlich benötigte externe Adapter +│ ├── migrations/ # einzige SQL-Migrationsfolge +│ ├── tests/ +│ │ ├── unit/ +│ │ ├── api/ +│ │ ├── integration/ +│ │ ├── migrations/ +│ │ ├── fixtures/ +│ │ └── conftest.py +│ ├── requirements.in / requirements.lock +│ ├── requirements-dev.in / requirements-dev.lock +│ ├── pytest.ini +│ └── Dockerfile +├── frontend/ +│ ├── src/ +│ │ ├── app/ # bootstrap, router, providers, module registry +│ │ ├── shared/api/ # request client, ApiError +│ │ ├── shared/session/ # kleiner Session-/Scope-Store mit epoch +│ │ ├── shared/ui/ # produktlokale Darstellung nach Design Guideline +│ │ ├── modules// # api, loaders/actions, routes, components +│ │ └── main.jsx +│ ├── tests/ # gemeinsame API-/Routing-/Scope-Verträge +│ ├── package.json / package-lock.json +│ ├── vite.config.js +│ └── Dockerfile +├── tests/e2e/ # Playwright gegen isolierten gebauten Stack +├── scripts/ci/ # Gate, Test-DB-Wächter, Artefaktprüfung +├── deploy/ # Compose-Varianten, Proxykonfiguration +├── .gitea/workflows/ # qualification und production; kein Live-Umbau hier +└── docs/ # OpenAPI-Baseline, kurze Start-/Betriebshinweise +``` + +Im dargestellten Strukturdefault läuft Python mit `backend` als Working Directory, Imports beginnen mit `app.`. Bei anderer begründeter Verzeichnisstruktur werden Importpfade und Befehle konsistent angepasst; keine impliziten Importnebenwirkungen. Jede Package-Ebene enthält `__init__.py`; keine `sys.path`-Reparaturen oder Importe wie `from main import ...`. API-/DB-/Modulimporttests müssen ohne Kontakt zu DB oder Anbieter funktionieren. Der Runner legt nur sein eigenes Ledger unter Lock an. Die erste SQL-Migration erstellt den tatsächlich benötigten Infrastrukturzustand, etwa den transaktionalen Audit-Speicher mit den Feldern aus A6; keine erfundenen Tenant-, Actor-, Billing- oder Memorytabellen. + +## B2 – Backend bauen + +### Konstruktion und Adapter + +`create_app(settings, providers)` registriert Fehlerhandler, Health und explizit ausgewählte Router. `bootstrap` erzeugt Pool, Transaktionsfactory und konkrete Services. Testapp und Runtime verwenden dieselbe Factory; nur Tests injizieren Fakes. Kein globales veränderliches Profil und keine Imports mit Startnebenwirkungen. + +| Baustein | Mindestschnittstelle | Verhalten | +|---|---|---| +| Principal | `kind`, `subject_id`, optional `actor_id` | Typisierte eigene Identität; keine mitgesendete Rolle als Autorität | +| ScopeRef | `kind`, `scope_id` | Verifizierter persönlicher/Club-/Organisationskontext; konkrete Fachsemantik bleibt lokal | +| RequestContext | `request_id`, `principal`, `scope` | Unveränderlicher Kontext; kein Credential und kein Promptinhalt | +| PrincipalResolver | `resolve(request) -> Principal` | Fehlende/abgelaufene Session: 401; nicht verdrahteter Adapter: 503 | +| ScopeResolver | `resolve(principal, selection) -> ScopeRef` | Mitgliedschaft prüfen; fremde/fehlende erforderliche Auswahl verweigern | +| AccessPolicy | `require(context, capability, resource, tx)` | Rechte/Objektsichtbarkeit, bei Writes aktuellen Zustand in derselben Transaktion prüfen | +| EntitlementPolicy | `require(context, feature, tx)` | Zusätzlich zum Zugriff; ohne aktuelle Anforderung keine vorsorgliche Quotenmaschine | +| TransactionFactory | `transaction() -> ContextManager[Tx]` | Eine Verbindung je Anwendungsfall; Commit vor erfolgreicher Rückgabe | + +**Wiederverwendung an diesen Grenzen:** Scope-/Access-Adapter werden zuerst gegen Shinkans [Sichtbarkeit](C:/Dev/shinkan-jinkendo/backend/tenant_context.py:57), [Kontozustand](C:/Dev/shinkan-jinkendo/backend/account_lifecycle.py:26) und zugehörige Negativtests abgeglichen. Für benötigte Prompt-/Workflow-Funktionen ist Mitais Ausführungs-/Registrierungssystem die erste Referenz; für private Modellkontexte Kanshōs Gateway. Nicht durch neue generische Platzhalterlösungen ersetzen, bevor ein konkreter vorhandener Mechanismus geprüft wurde. Kairo ist kein globales Ausgangsgerüst. + +Die Ports sind Typverträge, keine externen Dienste. Nur aktuell benötigte Ports werden implementiert. Ohne echten Auth-Adapter bleiben geschützte Routen geschlossen; es gibt keinen `AUTH_DISABLED`-/`ALLOW_ALL`-Runtime-Schalter. Ein geschützter Test-Router darf ausschließlich in der Testapp existieren. Die Foundation kann intern Health bereitstellen; daraus folgt keine Produktfreigabe für persönliche Fachdaten. + +### Transaktionsmuster + +Nicht integrierte und nicht ausgeführte Illustration (K) des DB-Adapters; Pool-Konfiguration und Fehlerübersetzung kommen aus A5/A4. `timeout=3` ist ein technischer Default, keine unveränderliche Architekturgrenze: + +```python +from contextlib import contextmanager + +class UnitOfWork: + def __init__(self, pool): + self.pool = pool # Pool liefert autocommit=True-Verbindungen + + @contextmanager + def transaction(self): + with self.pool.connection(timeout=3) as conn: + with conn.transaction(): + yield conn # in Services nur als Tx-Handle weiterreichen +``` + +Die Poolöffnung erfolgt einmal im Lifespan, `pool.wait()` ist zeitlich begrenzt; Shutdown schließt ihn. Kein Lazy-Neuaufbau eines Pools in jedem Repository. Für die eigene Architekturgrenze gilt: Nur Repository-/DB-Adapter rufen SQL auf diesem Handle auf. + +Ein Anwendungsservice folgt diesem Muster, ohne daraus ein generisches CRUD-Framework zu bauen: + +```python +def rename_resource(self, context, resource_id, command): + with self.uow.transaction() as tx: + self.access.require(context, "resource.update", resource_id, tx) + repo = self.repositories.resources(tx) + row = repo.rename_in_scope(context.scope, resource_id, command) + result = ResourceResponse.model_validate(row) + self.audit.changed(tx, context, "resource.updated", resource_id) + return result # auch der Commit muss erfolgreich gewesen sein +``` + +Alle hier verwendeten Typen/Methoden sind illustrative lokale Modulverträge. Response-DTO vor Verlassen des Blocks validieren; keine rohe DB-Zeile an FastAPI geben. Auditfehler verhindern den Commit einer auditpflichtigen Änderung. Ein späterer Scope- oder Entitlement-Adapter darf nicht unbemerkt eine zweite Connection öffnen. Bei konkurrierend bearbeiteten Ressourcen versieht das Fachmodul Updates mit erwarteter Objektversion und 409 bei Versionskonflikt. + +### Migration und Konfiguration + +Implementiere `python -m app.db.migrate --directory migrations` gemäß A5. Runtime startet den Runner nicht selbst. Ein nicht erfolgreicher Migrationslauf verhindert den Prozesswechsel. Der CLI liest ausschließlich den expliziten Migrationszugang, nicht einen privilegierten Ersatz für den Runtime-Pool. + +Unter dem Advisory-Lock wird gegebenenfalls das eigene Ledger angelegt; danach werden Ledger und Prüfsummen gelesen. Bei SQL-Ausführung und Ledger-Insert gibt es keinen zweiten Prozess/keine zweite Verbindung. `DO $$ … $$`, mehrere Statements ohne Parameter und Fehler in der Dateimitte erhalten eigene Tests. Keine einfache Semikolon-Zerlegung. Nichttransaktionale DDL wird zurückgewiesen; ihr eigener Betriebsschritt ist kein versteckter Runner-Fallback. + +| Konfiguration | Vorgabe | +|---|---| +| `APP_ENV`, `PRODUCT_ID`, `PUBLIC_ORIGIN` | Verpflichtend; Environment-Enum und zulässige Origin validieren | +| `DATABASE_URL` | Secret ohne Default; Runtime-Rolle, kein DDL/Owner/Superuser | +| `MIGRATION_DATABASE_URL` | Nur Migrationsprozess; fehlt im Runtime-Container | +| `BUILD_REVISION` | Source-Commit des gebauten Images, im Image festgehalten; nicht durch Deploy überschreiben | +| `EXPECTED_SCHEMA_HEAD` | Aus dem qualifizierten Deploy-Manifest; Readiness vergleicht mit tatsächlichem Ledger-Head | +| Pool-/SQL-Zeitbudgets | Numerische Defaults aus A5 begründet anpassbar; typisierte Validierung und wirksame Grenzen bleiben erforderlich. | +| `FEATURE_FLAGS` | Validiertes Objekt registrierter boolescher Schlüssel; fehlende optionale Funktion aus | +| Provider-/Cookie-/Auth-Secrets | Erst mit dem jeweiligen echten Adapter; nie unsichere Entwicklungsdefaults | + +Readiness kontrolliert zusätzlich die Prüfsummen der dem Image bekannten Migrationen. Neuere angewandte Migrationen sind nur mit qualifiziertem Kompatibilitätsnachweis für dieses Image zulässig; `EXPECTED_SCHEMA_HEAD` allein ist keine Freigabe für unbekanntes Schema. Das Deploy-Manifest hält den dafür erlaubten Schemahead fest. Bei unvollständiger Konfiguration Start abbrechen, keine Secrets mitloggen. + +`requirements.in` enthält direkte Pakete innerhalb der festgelegten Versionslinien; `requirements-dev.in` ergänzt Testwerkzeuge. `pip-tools` erzeugt hashgebundene vollständige Locks. Runtime-/Dev-Lock müssen gleiche Runtime-Pins haben. CI installiert aus Locks und löst nicht neu auf; Docker verwendet Runtime-Lock und enthält weder Tests noch Test-Secrets. + +## B3 – Frontend bauen + +Verwende für den Registry-Vertrag zuerst Mitais [Schlüsselregistrierung mit Duplikatsperre](C:/Dev/mitai-jinkendo/backend/placeholder_registry.py:169) und die produktlokale Komponentenregistry als Vorbilder; übertrage den kleinen Vertrag, nicht den gesamten fachlichen Placeholder-Katalog. Baue einen Data Router aus einer statischen Liste lokaler Moduldefinitionen. Definiere den Modulvertrag als JSDoc mit `id`, `routes`, `navigation` und benötigten Capability-/Feature-Schlüsseln. Registryaufbau prüft doppelte IDs/Pfade und unbekannte Schlüssel, statt sie zu überschreiben. UI-Gates verbessern die Bedienung; der Server prüft jeden Zugriff selbst. + +Der vorgeschlagene Transportvertrag (V) wird durch folgenden nicht ausgeführten Ausschnitt (K) illustriert; `timeoutMs: 15000` ist ein anpassbarer technischer Default: + +```javascript +request(path, { + method: 'GET', + json: undefined, + signal: undefined, + timeoutMs: 15000, + scopeSelection: undefined, +}) // Promise; Fehler: ApiError +``` + +`path` ist relativ zu `/api/v1`; externe URLs, `//host` und Weiterleitungen werden nicht als Fach-API akzeptiert. Credentials und Basis-URL sind keine frei überschreibbaren Moduloptionen. Eine Scopeauswahl ist nur ein serverseitig zu prüfender Hinweis. Der Auth-Adapter ergänzt den CSRF-Nachweis bei unsicheren Methoden. Upload-/Streamingvarianten verwenden dieselben Identitäts-/Fehlergrenzen mit ausdrücklich anderem Body-/Antwortmodus. + +`ApiError` besitzt `status`, `code`, `requestId`, `fieldErrors`; Netzfehler, Timeout, Abbruch und ungültige Antwort sind unterscheidbar. Der Client gibt niemals ungeprüften Response-Text als Fehlermeldung aus. Er erkennt 204 ohne JSON-Parsing. Bei einem Timeout nach einer Schreiboperation wird kein automatischer zweiter Write gesendet; das Ergebnis kann bereits committed sein. Wiederholung braucht den ausdrücklichen Idempotenzvertrag des Endpunkts. + +Der Session-Store wird einmal im Bootstrap erzeugt und per Provider/Dependency weitergereicht. Er besitzt `getSnapshot`, `subscribe`, `invalidate` und eine Operation zum bestätigten Scopewechsel. React kann ihn mit `useSyncExternalStore` lesen. Enthalten sind nur Sessionstatus, Principal-Metadaten, ausgewählter Scope und `epoch`; keine Listen, Formulare oder Credentials. + +Loader/Actions halten beim Start Scope und Epoche fest. Scopewechsel/Logout erhöht die Epoche, bricht aktive Requests ab und entfernt alte persönliche Ergebnisse; neue Loader beginnen leer. Sowohl erfolgreiche als auch fehlerhafte verspätete Antworten werden bei abweichender Epoche ignoriert. Ein alter 401 darf eine inzwischen neue Session nicht abmelden. Aktueller 401 leert die Session; 403 zeigt fehlende Rechte; 503 wird nicht als Logout interpretiert. + +Formulare nutzen lokalen Zustand. Mutationen invalidieren die betroffenen Loader, keinen pauschalen Full-Page-Reload. Routen haben Fehlergrenzen für nicht verfügbare Module und Transportfehler. Produktlokale darstellende Komponenten importieren keinen eigenen Live-API-Client. Die Design Guideline wird verwendet, ohne in diesem Blueprint neue visuelle Tokens festzulegen. + +Bevorzugter Frontend-Default sind relative Same-Origin-API-Pfade ohne Dev-/Prod-Origins im Build; damit kann R1 dasselbe Frontend-Image verwenden. R2 darf nachvollziehbar deklarierte öffentliche Build-Parameter unterscheiden und muss den konkreten Prod-Build validieren. Secrets und private VITE-Variablen bleiben in beiden Varianten ausgeschlossen. Keine PWA in der Grundstruktur; bei realem Installationsbedarf gilt A7, einschließlich Test der persönlichen API-Cachegrenze. + +## B4 – Mindesttests und lokale Befehle + +Die folgenden Fälle sind Abnahmebedingungen für die spätere Umsetzung, keine in Phase 3.2 ausgeführten Tests. + +| Suite | Verpflichtender Nachweis | +|---|---| +| Imports/Start | Router und App-Factory importierbar ohne DB-/Netzwerkzugriff; Factory mit Testprovidern; OpenAPI generierbar; unbekannte Konfiguration verhindert Start | +| Transaktion | Zwei zusammengehörige Writes plus Audit committen gemeinsam; Fehler beim zweiten Write/Audit hinterlässt keinen ersten Write; Commitfehler ergibt keinen 2xx-Erfolg | +| Datenraum | Nutzer A kann Testobjekt von B weder lesen noch ändern; gefälschte Auswahl/Elternreferenz scheitert; eingeschränkte Runtime-Rolle darf kein DDL | +| Auth/Policy | Keine Session 401, fehlende Capability 403, unsichtbares Objekt 404, unverdrahteter Pflichtadapter 503; Entitlement ersetzt keine Berechtigung | +| API | 422/409/500/503 im vereinbarten Problemformat; unbekannte Inputfelder verweigert; Response enthält keine internen Felder/Rohwerte; 204 ohne Body | +| Migration | Leere DB; Upgrade von voriger Basis; Wiederholung; geänderte/fehlende angewandte Datei; doppelte IDs; Konkurrenz; SQL-/Ledger-Fehler; Dollar-quoted SQL | +| Pool | Saubere Rückgabe nach Exception; begrenzte Erschöpfung; kein fremder Transaktions-/Scopezustand beim nächsten Entleiher | +| Client/State | JSON/204/HTML/Netzfehler/Timeout; keine automatische Write-Wiederholung; Scopewechsel mit verspäteter Antwort und verspätetem 401 | +| Modul/Route | Doppelte IDs/Pfade verweigert; unbekannter Schlüssel; Loaderfehler lokal; fehlende UI-Rechte; Dirty-Form-Blocker auf tatsächlicher Routerversion | +| Browser | Gebauter Stack: SPA-Direktaufruf, API-Fehlerzustand, Testidentitäts-/Scopewechsel; Cookie-/CSRF-Fälle erst mit echtem Auth-Adapter verpflichtend ergänzen | +| Release | In R1 und R2 sperren rote/fehlende Pflicht-Gates und nicht passende Quell-/Build-/Artefaktnachweise das Deployment. R1 prüft identische qualifizierte Artefakte; R2 prüft auch den separaten Prod-Kandidaten vor der Umschaltung. | + +DB-Tests laufen gegen PostgreSQL 16 mit eigenem kurzlebigem Compose-Projekt je Run und synthetischen Daten. Keine lokale/private oder laufende Dev-/Prod-DB als Testtarget. Der Wächter verlangt `APP_ENV=test`, passende Run-ID im DB-Namen, erlaubtes CI-Netz und erfolgreichen Abgleich von `current_database()` **vor** jeder Schemaänderung. Runtime- und Migrationsrolle werden auch im Test getrennt. Cleanup ist garantiert, auch bei Fehlern; keine gemeinsam fest benannte Testdatenbank für parallele Runs. + +Fakes werden über `create_app(..., providers=...)` oder FastAPI-Testoverrides eingebracht, nicht durch Umgebungsflags in den Runtime-Code. Echte DB-Vertragsfälle nutzen keine SQLite-Ersatzdatenbank. Marker `integration`, `migration`, `negative` dienen der Auswahl. Gitea prüft ausgewählte Mindestfallnamen und JUnit-Ergebnisse: null gesammelte Tests oder ein Skip eines erforderlichen Falls ist ein Fehler. Keine pauschale Coverage-Prozentzahl als Ersatz für die obigen Fälle. + +Im später erzeugten Repository sind diese Einstiegspunkte einzurichten: + +| Ort | Befehl | Zweck | +|---|---|---| +| `backend` | `python -m pytest tests/unit tests/api -ra` | schnelle Tests mit sicheren Testprovidern | +| `backend`, isolierter DB-Stack | `python -m pytest tests/integration tests/migrations -ra --junitxml=results.xml` | Runtime-Rolle, Transaktionen, Migrationsvertrag | +| `frontend` | `npm ci` und `npm run build` | gesperrte Installation und Produktionsbuild | +| `frontend` | `npm run test` mit `vitest run` | Client-/Komponenten-/Routingtests, kein Watchmodus | +| CI-Testcontainer | `npx --no-install playwright test` | bereits gelockte Playwright-Installation, isolierter Image-Stack | +| `backend`, expliziter Migrationsprozess | `python -m app.db.migrate --directory migrations` | im Deploy vor Umschaltung, niemals als Test gegen Kundendaten | + +Die Browser-Testwerkzeuge liegen in der gelockten Frontend-Toolchain; die Konfiguration verweist auf `tests/e2e` im Repository. Ein Testimage darf Werkzeuge ergänzen, aber keine Runtime-Pins ersetzen. Browser-/HTTP-Image-Tests sprechen das unveränderte gebaute Runtime-Image an; Quellmounts dürfen dessen Anwendung nicht überlagern. + +## B5 – Gitea-Ablauf und Build-Nachvollziehbarkeit + +**Verbindlich:** `develop → Dev → Tests → bewusste Freigabe → main → Prod`, erforderliche Release-Gates, menschliche Freigabe und eindeutige Versions-/Artefaktzuordnung. **Technische Varianten:** R1 „Build once, deploy many“ ist der bevorzugte Default; R2 sind nach ADR-11 weiterhin zulässige kontrollierte, reproduzierbare getrennte Dev-/Prod-Builds. Beides sind noch nicht ausgeführte Verfahrensvorgaben (V/K), keine hier validierten Pipelines. + +Die bestehenden Gitea-Prozesse werden entsprechend genutzt. Zwei logische Aufgaben – Dev-Qualifikation und Produktionsfreigabe/-deployment – können in den vorhandenen Workflows abgebildet werden; Dateinamen und Jobaufteilung sind Defaults, keine neue Infrastrukturvorgabe. Nicht vertrauenswürdige PR-Checks erhalten weder Deploy-/Prod-Secrets noch Zugriff auf produktive Docker-Sockets. Deploy-Jobs laufen nur für geschützte eigene Branches auf berechtigten Runnern. Actions werden auf geprüfte Commitstände gepinnt und müssen zur eingesetzten Gitea-/Runner-Version passen. Siehe C, O2. + +| Stufe | R1 – bevorzugt: identische Artefakte | R2 – zulässig: separate Builds | +|---|---|---| +| 1 · develop | Quellcommit S/Tree T, Lockfiles und Build-Eingaben festhalten; schnelle Tests und Import-/OpenAPI-Prüfung. | Derselbe Dev-Vertrag; Dev-Build-Rezept und Parameter eindeutig aufzeichnen. | +| 2 · Dev | Backend-/Frontend-Artefakte bauen und identifizieren, explizite Dev-Migration und Dev-Deployment; Read-only-Smoke. | Identifizierte Dev-Artefakte bauen und nach Dev deployen; Migration und Read-only-Smoke wie R1. | +| 3 · Tests | Die gebauten Artefakte im isolierten Stack mit Pflichtsuiten aus B4 und Browserfällen qualifizieren. | Die Dev-Artefakte mit den erforderlichen Suiten qualifizieren. Das Ergebnis gilt für diesen Dev-Build, nicht automatisch für einen späteren Prod-Build. | +| 4 · Bewusste Freigabe | Mensch nimmt den Release-PR nach erfolgreicher Dev-Qualifikation auf geschütztes `main` an. | Dieselbe menschliche Freigabe; freigegebener Quellstand und deklarierte Produktions-Build-Eingaben bleiben nachvollziehbar. | +| 5 · Prod-Kandidat / Gate | Qualifizierte Artefakte aus dem passenden vertrauenswürdigen Run übernehmen, Hashes und Quellbeziehung prüfen. Default: S ist in main enthalten und `tree(main) == T`. | Aus dem freigegebenen Stand mit gelockten Abhängigkeiten, festgehaltenem Build-Rezept, Toolchain/Basisimages und deklarierten Parametern reproduzierbar separat bauen. Den konkreten Prod-Kandidaten im isolierten Stack vor Deployment durch seine Pflicht-Gates führen; eigener Validierungsrun und eigene Artefaktkennungen. | +| 6 · Prod | Erst bei vollständigem Nachweis: Deployment serialisieren, Schema-/Backupbedingung prüfen, explizite Prod-Migration, qualifizierte Artefakte umschalten. | Erst nach erfolgreichen Gates für den separaten Prod-Build dieselben Betriebsbedingungen prüfen und genau diesen Prod-Kandidaten umschalten. Keine ungetestete zusätzliche Änderung oder weiterer ungeprüfter Build. | +| 7 · Smoke | Read-only-Smoke und eingesetzte Build-/Artefaktkennung protokollieren. | Identische Nachweispflicht für die tatsächlich eingesetzte Prod-Version. | + +Ein rotes, fehlendes oder übersprungenes Pflicht-Gate stoppt beide Varianten. `main` enthält den bewusst freigegebenen Stand; eine Abweichung vom Dev-Tree darf nicht unter dessen grünem Ergebnis als mitgetestet gelten. Sie benötigt die zugehörigen Tests und Nachweise für den tatsächlich freigegebenen Produktionsquellstand. Änderungen außerhalb dieser menschlich freigegebenen Eingaben sind kein bereits genehmigter Release. Ein weiterer menschlicher Freigabezyklus nur wegen der Wahl von R2 wird nicht eingeführt. + +Der Produktionstest läuft isoliert gegen den konkreten Prod-Kandidaten, niemals mit synthetischen Mutationen in einer Kundendatenbank. Weder Reproduzierbarkeit noch ein Health-Smoke nach Deployment ersetzen dieses Gate. Runtime-/Build-Eingaben werden kontrolliert aufgelöst; spontane Paketupdates oder nicht dokumentierte Build-Änderungen sind in keiner Variante erlaubt. Ein kontrollierter Prod-Build in R2 ist ausdrücklich zulässig. + +**Releasenachweis für beide Varianten:** getesteter Quell-/Buildstand, freigegebener main-Stand und tatsächlich deployte Artefakte werden verknüpft. Das nachstehende Manifest ist das bevorzugte technische Format; gleichwertige vorhandene Gitea-Nachweise dürfen es abbilden. Verbindlich ist die vollständige Zuordnung, nicht ein bestimmter JSON-Feldname oder zusätzlicher Dienst. + +```text +product_id, build_variant (R1/R2), approved_main_commit, +dev_source_commit/tree, dev_build_id, dev_qualification_run_id, +prod_source_commit/tree, prod_build_id, prod_validation_run_id, +backend/frontend_artifact_ids und Hashes/Digests je Build, +Lockfilehashes, Build-Rezept/Toolchain/Basisimages und öffentliche Build-Parameter, +migrations_digest, expected_schema_head, +gate_results je qualifiziertem Build mit Ausführungs-/Skipnachweisen, +deployed_build_id und tatsächlich eingesetzte Artefakthashes, +qualified_rollback_images +``` + +In R1 dürfen Dev- und Prod-Build-/Validierungsreferenzen auf denselben qualifizierten Build verweisen. In R2 sind die getrennten Builds und ihre Ergebnisse explizit zugeordnet; unterschiedliche Hashes sind kein Fehler, wenn gerade das eingesetzte Prod-Artefakt qualifiziert ist. Merge-Commits werden über Commit und Source-Tree den Freigaben zugeordnet. Eine inzwischen weitergelaufene Dev-Instanz ersetzt keinen dieser Nachweise. + +Production vertraut den Nachweisen der passenden geschützten Workflow-Runs, nicht einem beliebig hochgeladenen JSON oder bewegbaren `latest`-Tag. Artefakte bleiben mindestens über das vereinbarte Rollbackfenster nachvollziehbar verfügbar. Archive mit SHA-256 und eine bereits vorhandene OCI-Registry mit Digestbindung sind Transportvarianten; keine neue CI/CD-Infrastruktur wird verlangt. + +Gitea `environment: production` zählt nicht als manuelle Freigabe. Workflowübergreifende Reihenfolge und Deploymentserialisierung werden ausdrücklich hergestellt. Ein produkt-/umgebungsspezifischer Hostlock ist ein technischer Default bei Jobs auf demselben Deploy-Host, keine Pflicht zu genau diesem Mechanismus. Fehler geben die gewählte Sperre und temporäre Teststacks zuverlässig frei. + +Rollback verwendet ein auf dem aktuellen Schema qualifiziertes voriges Artefaktpaar. Migrationen laufen nicht automatisch rückwärts. Ohne erforderliche Kompatibilität stoppt das Release vor der Migration; nach unerwarteten Fehlern gelten kontrollierter Forward-Fix oder vorbereiteter Restore. Die Backup-/Recoverybedingungen des Produktprofils bleiben für beide Build-Varianten unverändert. + +## B6 – Erweiterung und Fertigstellung + +Ein neues Fachmodul ergänzt Router/Schemas, Anwendungsservice und scoped Repository, registriert sich im Backend-Bootstrap und gegebenenfalls in der Frontend-Modulliste, bringt seine Migration und Negativtests mit und ändert keine fremden Router. Ein neuer externer Adapter wird nur im Composition Root eingebunden. Wiederverwendbare Komponenten erhalten einen Testvertrag; eine Library wird erst bei zwei tatsächlichen Abnehmern extrahiert. + +**Nicht übernehmen:** Clientheader als Identität, erste Profil-/Club-ID als Fallback, Probe als neue Schutzvorgabe, dynamisch importierte Clientmodule, Commit nach Response, versteckte zweite DB-Verbindung, Migration beim Import, Erfolgsledger nach separatem SQL-Prozess, pauschales `catch → null`, persönliche API-Caches, ungeplant neu aufgelöste Pakete im Release, ungeprüfter Prod-Neubuild, Tests mit Kundendaten oder Anbieter-Schlüsseln. + +Abnahmebedingungen für eine künftige Foundation-Implementierung sind: Struktur und Verträge umgesetzt, Pflichtfälle der tatsächlich registrierten Funktionen nachweislich bestanden, Lockfiles/OpenAPI vorhanden und wirksame Release-Sperren belegt. Diese Bedingungen sind hier Vorgaben, kein Bericht bereits bestandener Tests. Auch ihre spätere Erfüllung ersetzt keine produktbezogene Produktionsreifeprüfung. Fehlende Spezialadapter bleiben sichtbar geschlossen; sie werden nicht durch Fakes produktionsreif erklärt. Der Implementierungsbericht nennt Commit, Testbefehle/Umgebung, Ergebnisse und verbleibende Produktadapter knapp. Kein zusätzlicher ADR-Zyklus ist dafür erforderlich. + +**Vorhandene Vorbilder nach Mechanismus:** Mitai: [Registry/Resolver](C:/Dev/mitai-jinkendo/backend/placeholder_registry.py:159), [Prompt-/Workflow-Laufzeit](C:/Dev/mitai-jinkendo/backend/workflow_executor.py:39) bei echtem KI-Bedarf, [gemeinsamer Cursor/Savepoints](C:/Dev/mitai-jinkendo/.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md:27). Shinkan: [Sichten/Zugriff](C:/Dev/shinkan-jinkendo/backend/tenant_context.py:57), [Security-Regressionen](C:/Dev/shinkan-jinkendo/backend/tests/test_security_release.py:37), Navigation. Kanshō: [Maskierung und Egress-Gate](C:/Dev/Kansho/backend/privacy_gateway.py:1257) sowie getrennte Testdaten. Kairo: einzelne Service-/Konfigurations-/Maschinenzugriffsbausteine als ergänzende Kandidaten. Kein Produkt wird vollständig kopiert; die Zieltransaktion ist die in A/B beschriebene gezielte Referenzlösung. diff --git a/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md new file mode 100644 index 0000000..e968f3c --- /dev/null +++ b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md @@ -0,0 +1,80 @@ +# C – Technical Decisions & Open Issues + +**Phase 3.2 · v0.3 · 16.10.2026 · technischer Vorschlag, keine Produktionsfreigabe** + +## Management-Zusammenfassung + +Die Referenz bleibt beim vorhandenen Stack: FastAPI, React/Vite, PostgreSQL, Docker Compose und Gitea. Neu zusammengeführt werden eine modulare Struktur, explizite Transaktionen, ein einheitlicher HTTP-Vertrag und ein Release-Verfahren mit verpflichtenden Gates und nachvollziehbarer Quell-/Build-/Artefaktzuordnung. Für neue Apps werden unterstützte Versionslinien verwendet; vorhandene Apps erhalten keinen pauschalen Upgradeauftrag. + +Die frühere Hervorhebung Kairos als „Hauptvorbild“ war zu weitgehend und wird zurückgenommen. Ich hatte die sichtbare Service-/Registry-Struktur für die Foundation übergewichtet und die spezialisierten, tatsächlich vorhandenen Mechanismen der anderen Produkte zu stark auf Nebenrollen reduziert. Daraus folgt weder Kairos höhere Produktreife noch ein belegter Vorsprung bei den meisten belastbaren Mustern. + +Die korrigierte Referenzwahl ist bereichsspezifisch: **Mitai für Prompt-/Workflow-Laufzeit und Registrierungsverträge; Shinkan für Nutzer-/Vereinssichten, Berechtigungen und Security-Mechanismen; Kanshō für Maskierung privater KI-Daten; Kairo für einzelne ergänzende Struktur-, Konfigurations- und Actor-Token-Muster.** Die Foundation bleibt eine Synthese. Transaktions-, Migrations- und Releaseverträge werden dort gezielt ergänzt, wo keine vorhandene Implementierung vollständig genügt. + +Die drei offenen Punkte unten betreffen die erste konkrete Produkteinführung. Die Foundation benötigt dafür keine weitere Grundsatzentscheidung. Der nächste sinnvolle Spezial-Blueprint ist **Auth, Session & Scope**: sichere Cookies/CSRF, verlässliche Datenraumauflösung, Objektzugriff und geschlossene Ersteinrichtung. Kein weiterer Arbeitsschritt wurde automatisch gestartet. + +## Gezielte Korrekturen in v0.3 + +1. **ADR-11 / Release:** R1 „Build once, deploy many“ bleibt bevorzugter technischer Default. R2 – kontrollierte, reproduzierbare getrennte Dev-/Prod-Builds – bleibt zulässig. Beide benötigen Pflicht-Gates vor Prod, menschliche Freigabe und eindeutige Zuordnung der tatsächlich eingesetzten Version. Bei R2 wird der konkrete Prod-Kandidat zusätzlich qualifiziert. Branchstrategie und bestehende Infrastruktur bleiben erhalten. +2. **Nachweis:** A/B sind V (vorgeschlagener technischer Standard) und als Kombination K (noch nicht integriert/getestet). Produkt-Codeverweise sind I (vorhandene Implementierungsreferenz). T setzt bestandene Tests mit Umfang, Stand und Umgebung voraus; für die Foundation wird kein T-Gesamtnachweis oder Produktionsreife behauptet. Die früher benannten Testquellen werden dadurch nicht zu Testergebnissen. +3. **Verträge / Defaults:** A0 unterscheidet verbindliche Schutz-, Datenraum-, Transaktions- und Releaseverträge von anpassbaren technischen Defaults wie Poolgröße, Timeout, Verzeichnisdetail und Framework-Version. Begründete Anpassung im Produktauftrag bzw. in der Konfiguration genügt; keine neuen ADRs oder Freigabeschleifen. + +Die bereichsspezifische Referenzauswahl und die bisherigen drei offenen Produkt-/Betriebspunkte bleiben unverändert. Die nachstehende Einordnung wird aus v0.2 übernommen; v0.3 führt keine erneute Produktreifebewertung oder Konsolidierung durch. + +## Überprüfung der bisherigen Gewichtung + +**Nutzerangabe:** Kairo ist noch nicht im Einsatz und der MVP enthält erhebliche Baustellen bis zur nutzbringenden Verwendung. Das ist relevante Erfahrung des Produkteigentümers und widerspricht einer Darstellung als besonders betriebsbewährtes Gesamtvorbild. Es ist keine hier neu erhobene Nutzungsmetrik; für die anderen Produkte wird daraus ebenfalls kein pauschaler Produktionsnachweis abgeleitet. + +**Prüfmaßstab:** Ein klarer Ordnername ist ein Strukturhinweis. Ein konkreter implementierter Mechanismus ist stärker. Testassertionen, tatsächlich bestandene Tests eines bekannten Standes und erfolgreiche Nutzung sind weitere, getrennte Nachweise. Im Ergänzungsreview wurden Code und ausgewählte Testassertionen gelesen, keine Tests ausgeführt. „Am meisten belastbar“ ist damit als Gesamtranking nicht belegt. + +| Produkt / primärer Referenzbereich | Konkret nachgelesener Mechanismus | Was daraus folgt / was offen bleibt | +|---|---|---| +| Mitai · Prompt-/Workflow-System | Graphvalidierung und topologische Ordnung, ausführender Workflow mit Verzweigungen/Joins, Platzhalterauflösung, Metadaten/Resolver und Duplikatsperre. [Engine](C:/Dev/mitai-jinkendo/backend/workflow_engine.py:67), [Executor](C:/Dev/mitai-jinkendo/backend/workflow_executor.py:39), [Registry](C:/Dev/mitai-jinkendo/backend/placeholder_registry.py:169), [Testquelle](C:/Dev/mitai-jinkendo/tests/backend/test_workflow_engine.py:86) | Vorrangiger vorhandener Implementierungskandidat für diese Funktionen und für kleine Registry-Verträge. Nicht nur Widgets. Ein Schemaargument im Prompt-JSON-Validator wird noch nicht als JSON-Schema validiert; Legacypfade und Diagnoseinhalte benötigen Anpassung. | +| Shinkan · Sichten, Rechte, Security | Gemeinsame SQL-Sichtbarkeit für privat/Verein/offiziell, aktive Mitgliedschaft, Kontozustände; Tests für Sessionprofil, Produktionsdiagnose, öffentliche Medien und Nosniff sowie Graphsichtbarkeit. [Policy](C:/Dev/shinkan-jinkendo/backend/tenant_context.py:57), [Account](C:/Dev/shinkan-jinkendo/backend/account_lifecycle.py:26), [Securitytests](C:/Dev/shinkan-jinkendo/backend/tests/test_security_release.py:37), [Sichtbarkeitstests](C:/Dev/shinkan-jinkendo/backend/tests/test_exercise_progression_graph_visibility.py:26) | Primäres konkretes Vorbild für Scope-/Access-Verträge. Die vorherige Verkürzung auf Navigation/Securitychecks war sachlich unzureichend. Vorhandener Layer und geprüfte Einzelregeln belegen noch keine vollständige produktive Security-/Datenschutzabnahme. | +| Kanshō · Maskierung/Privacy-Gateway | Requestbezogenes Maskierungsmanifest, aktive Ersetzungen, Vorabprüfung und Blockade vor dem Modellaufruf, lokale Rückübersetzung. [Maskierung](C:/Dev/Kansho/backend/privacy_gateway.py:705), [Gate](C:/Dev/Kansho/backend/privacy_gateway.py:1257), [Testquelle](C:/Dev/Kansho/backend/tests/test_privacy_manifest.py:70) | Primäres Vorbild für persönliche KI-Datenflüsse; nicht lediglich ein Psycopg-/Test-DB-Beispiel. Semantisch vollständige Erkennung jedes privaten Datums und alle Egress-Pfade sind damit nicht bewiesen. | +| Kairo · ergänzende Teilmechanismen | Separate Services, deklarative Registrierungen, Secret-Referenzprüfung und Actor Tokens sind vorhanden. Im untersuchten Action-Pfad greift der Router auf Services und Read Models zu; Data Layer importiert private Servicehelfer und führt selbst SQL aus. [Router](C:/Dev/kairo-jinkendo/backend/routers/actions.py:8), [Data Layer](C:/Dev/kairo-jinkendo/backend/data_layer/actions.py:9), [Connection-Prüfungen](C:/Dev/kairo-jinkendo/backend/services/actions.py:152) | Nützliche isolierte Kandidaten, aber keine durchgängig nachgewiesene `Router → Service → Repository`-Implementierung. Kein Vorrang des Gesamtprodukts und kein Betriebsreife-Beleg. | + +Die Kritik ändert die **Gewichtung und Wiederverwendungsherkunft**, nicht automatisch jede technische Zielentscheidung. Der begrenzte Phase-3.2-Fokus auf Foundation rechtfertigt, einen umfangreichen Workflow-Editor nicht in jede neue App einzubauen. Er rechtfertigt nicht, das bereits vorhandene Prompt-/Registrierungssystem bei der Referenzwahl abzuwerten. Für KI-Funktionen werden Mitais Laufzeit und Kanshōs Privacy-Vertrag ausdrücklich vor einer neuen Eigenlösung herangezogen; Zugriffsverträge werden an Shinkans konkreten Sichten und Regeln ausgerichtet. + +## Technische Empfehlungen und wichtigste Alternativen + +Nachweisstatus: Die bevorzugten Zielausgestaltungen sind V, ihre noch nicht ausgeführte Kombination K; die Herkunftsspalte nennt bestehende Referenzen I. Keine Zeile wird hier als durch Tests validierte Foundation-Lösung T ausgewiesen. Die Geltung verbindlicher Verträge gegenüber technischen Defaults folgt A0. + +| ID / Bereich | Bevorzugte Lösung und Begründung | Wichtigste Alternative / bewusste Grenze | Konkrete Herkunft | +|---|---|---|---| +| TF-01 · Struktur | Produktlokaler modularer Monolith; Router → Service → Repository/Port; ein Composition Root. Aus vorhandenen Teilmechanismen abgeleiteter Zielentwurf, noch keine validierte Gesamtimplementierung; kein neuer Betrieb. | Großer Router-Monolith wird nicht fortgesetzt; Microservices oder allgemeiner Domänenkern bringen für die Foundation keinen belegten Vorteil. | Gezielte Synthese: [Mitai-Cursorvertrag](C:/Dev/mitai-jinkendo/backend/data_layer/activity_persistence_orchestrator.py:171), Kairo-Serviceabgrenzung als Teilbeispiel; dort keine durchgängige Zielschichtung. | +| TF-02 · Backend | FastAPI/Pydantic, explizite DI, synchrone PostgreSQL-Anwendungsfälle, ein Transaktionskontext je atomarem Service. | Durchgehend async nur bei realem I/O-Bedarf. Keine zweite Connection in verschachtelten Validierungen, kein später Response-Commit. | KI-MIT-02/17; [Cursor-/Savepoint-Regeln](C:/Dev/mitai-jinkendo/.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md:27); Anpassungsbedarf im [Kairo-Service](C:/Dev/kairo-jinkendo/backend/services/actions.py:152) | +| TF-03 · Frontend | React-SPA, explizite Modulregistry, Data Router, lokaler Formularzustand; kleiner Session-/Scope-Store statt globalem Fachdaten-Context. | Kein Redux/TanStack-Query-Zwang ohne konkreten Bedarf; kein SSR-/RSC-Wechsel. Registry darf Fehler nicht verschlucken. | Vorrangig [Mitai-Registryvertrag](C:/Dev/mitai-jinkendo/backend/placeholder_registry.py:169) und [Widgets](C:/Dev/mitai-jinkendo/frontend/src/widgetSystem/dashboardWidgetRegistry.jsx:18); [Shinkan-Navigation](C:/Dev/shinkan-jinkendo/frontend/src/hooks/useUnsavedChangesBlocker.js:8); Kairo-Slices ergänzend. | +| TF-04 · API | `/api/v1`, explizite Pydantic-DTOs, OpenAPI und Problem Details; ein Browser-Transportclient. | Heutige verschiedenförmige `detail`-/HTML-Fehler werden nur im Bestandsadapter toleriert; kein vollständiges neues RPC-/GraphQL-System. | KI-MIT-04; [vorhandene Fehlernormalisierung](C:/Dev/mitai-jinkendo/frontend/src/utils/api.js:11), [Problem Details](https://www.rfc-editor.org/rfc/rfc9457.html) | +| TF-05 · Datenbank | PostgreSQL 16, Psycopg 3 mit begrenztem nativen Pool; SQL-Dateien mit Lock, Prüfsumme und atomarem Ledger. | Psycopg 2 ist Bestandsvariante. Kein ORM-/Alembic-Wechsel zur Lösung eines klar begrenzten Runner-Problems; kein SQLite-SQL-Übersetzer im Standard. | KI-SHK-06, KI-KAI-08, KI-KAN-06; [bestehender Pool](C:/Dev/shinkan-jinkendo/backend/db.py:19), [Runner](C:/Dev/kairo-jinkendo/backend/run_migrations.py:110), [Psycopg 3](C:/Dev/Kansho/backend/requirements.txt) | +| TF-06 · Konfiguration | Explizite Prozessumgebung und Pydantic-Validierung; Secrets nur in Adapter/Betriebsbereitstellung; unbekannte Umgebung stoppt. | Kein zusätzlicher Secret-Server. Kein Default-Passwort, kein automatisches development, kein Secretwert in technischer DB-Konfiguration. | KI-KAI-14, KI-KAN-16; [Secretreferenz-Prüfung](C:/Dev/kairo-jinkendo/backend/config_service.py:17), [Env-Fallback als Gegenbeispiel](C:/Dev/Kansho/backend/env_loader.py:28) | +| TF-07 · Testing | pytest und echtes isoliertes PostgreSQL; Vitest/RTL und wenige Image-Browsertests; Pflichtfälle statt bloßer Dateipräsenz. | Keine produktiven Mutationen, kein SQLite-Ersatz, keine Testinstallation in laufenden App-Containern und keine still übersprungenen Pflichtsuiten. | KI-SHK-12, KI-KAN-14; [Sicherheitschecks](C:/Dev/shinkan-jinkendo/backend/scripts/security_release_checks.py:17), [Test-DB-Trennung](C:/Dev/Kansho/.gitea/workflows/test.yml:36) | +| TF-08 · Deployment | Verbindlich: bestehende Branchfolge, menschliche Freigabe, Release-Gates und Quell-/Build-/Artefaktzuordnung. Default R1: identische qualifizierte Images übernehmen. | ADR-11-Variante R2: kontrollierte reproduzierbare separate Builds mit Pflicht-Gates für den konkreten Prod-Build vor Deployment. Keine neue Infrastruktur; Tests nur nach Prod reichen nicht. | KI-KAI-16, KI-SHK-13; [isolierter Kairo-PR-Stack](C:/Dev/kairo-jinkendo/.gitea/workflows/test.yml), [Gitea: environment ignoriert](https://docs.gitea.com/usage/actions/comparison/) | +| TF-09 · Extension/Reuse | Erst lokaler Vertragsstandard; kleine Library bei zwei tatsächlichen Abnehmern und benanntem Maintainer. | Keine Cross-Repo-Runtime-Imports, gemeinsame Fachdatenbank, SSO- oder Billing-Plattform auf Vorrat. Zentrale Dienste benötigen echten Betriebsnutzen. | Beschlossener ADR-13 / Reuse First; [vorhandenes Register](C:/Dev/jinkendo-architecture-consolidation-phase2-v0.2-2026-10-15/05_Architecture_Decision_Register.md) | + +### Gezielte Anpassungen statt unveränderter Kopie + +Die vorhandenen Muster sind Referenzen, kein bereits gemeinsam getestetes Foundation-Paket. Insbesondere wird Kairos `psql`-Migrationspfad nicht als atomar übernommen: SQL wird dort in einem separaten Prozess committed, der Ledger-Eintrag danach. Die Referenz führt beides auf derselben Connection zusammen. Mitais und Shinkans Pool-/Contextmanager liefern die Richtung, der neue native Psycopg-Pool ersetzt deren konkrete Poolklasse. Die heutige gemischte Cursor-/Connection-Erzeugung wird nicht vererbt. + +Bei Registry-Bausteinen wird Überschreiben doppelter IDs durch Aufbaufehler ersetzt; Ladefehler bleiben unterscheidbar statt `null`. Der gemeinsame API-Client übernimmt Fehlernormalisierung, aber weder das [mutable Profilheader-Muster](C:/Dev/mitai-jinkendo/frontend/src/utils/api.js:54) noch [ungeprüfte Profilauflösung](C:/Dev/mitai-jinkendo/backend/routers/profiles.py:20). Aktuelle App-Regeln über HTML-Sanitizer, Datenschutz oder Importtransaktionen bleiben für tatsächlich übernommene Funktionen relevant. + +`psycopg_pool` ist eine zusätzliche native Treiberkomponente für begrenzte threadsichere Connections, keine neue Infrastruktur. `pip-tools` ist die einzige zusätzliche Build-Hilfe für Python-Lockfiles mit transitiven Pins/Hashes. Beides löst ein konkretes Foundation-Problem; weitere Frameworks werden nicht vorsorglich ergänzt. + +Die Frontend-Versionsaktualisierung gilt ausschließlich für den vorgeschlagenen Neuaufbau. Bestehende React-/Router-Anwendungslogik kann angepasst übernommen werden; eine Kompatibilitätsprüfung der neuen Paketkombination erfolgt beim späteren Aufbau mit Lockfiles und B4. Daraus wird kein getesteter Paketstand behauptet. Die Versions-/Supportquellen und ihre Einordnung als technische Defaults stehen in A1/A0; v0.3 nimmt keine neue Versionsrecherche vor. + +## Drei offene Punkte + +| Punkt | Was bei der ersten konkreten App festzulegen ist | Default / Auswirkung auf die Foundation | +|---|---|---| +| O1 · Datenraum und Schutzbedarf | Konto=Person, Club oder Organisationsraum; welche vertraulichen Mehrraumdaten zusätzlichen RLS-Schutz benötigen. | Expliziter Scope-/Policyvertrag und eingeschränkte Runtime-Rolle stehen fest. Keine universelle Tenanttabelle, kein stiller Erstprofilfallback. Keine externe Freigabe vertraulicher Mehrraumfunktionen ohne diese Produktausprägung. | +| O2 · Wirksame Gitea-Sperren | Tatsächliche Server-/Runnerfähigkeiten, erforderliche Statuschecks, Main-Schutz, getrennte Berechtigungen und verfügbare Artefaktablage bestätigen. | Menschliche Freigabe, Release-Gates und eindeutige Versionszuordnung sind festgelegt; gleiche Images sind Default R1, getrennte qualifizierte Builds zulässige Variante R2. Ohne wirksame Sperren gibt es keine Prod-Promotion; bloßes `environment: production` zählt nicht. Die tatsächliche Server-/Runnerkonfiguration wurde nicht abgefragt oder verändert. | +| O3 · Recoveryprofil | RPO/RTO, Restorefenster, Medien-/Schlüsselumfang und Schutz der Backups des ersten Produkts. | PostgreSQL-Backup und geprobter Restore vor datenverändernder externer Freigabe; kompatibles altes Image oder kontrollierter Forward-Fix. Keine pauschalen SaaS-Verfügbarkeitszusagen. | + +Das sind keine weiteren familienweiten Architekturfreigaben. Die Angaben werden Teil des konkreten Produkt-/Betriebsauftrags; sie verhindern die technische Grundstruktur nicht. ADR-15 und ADR-16 werden in dieser Phase weder bestätigt noch als Voraussetzung für die Foundation behandelt. + +## Quellen- und Prüfstand + +Verwendet wurden die benannten [Phase-3.1-Wissenselemente](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json), [Abhängigkeiten](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/B01_dependency_matrix.csv), [Guardrailabschnitte](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/C01_guardrails_lessons_register.csv) und [Kandidaten](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/E01_candidates.json). Für konkrete Entscheidungen wurden gezielt Codeabschnitte nachgelesen, keine neue Inventur erstellt. Die Guardrail-Originalabschnitte wurden nach den betroffenen Regeln/Erfahrungen ausgewählt. + +Die Auswahl folgt den tatsächlichen A01-Einträgen und Codepfaden: Mitais CSV-Registry/Aggregation sind KI-MIT-17/18, der PDF-Export KI-MIT-19. Einzelne E01-Kandidatenzuordnungen enthalten zusätzlich andere Themen; sie werden nicht ungeprüft als Implementierungsnachweis fortgeschrieben. Phase 3.1 bleibt unverändert. + +Die ursprüngliche Fassung erfasste 103 gezielte Eingaben; der Ergänzungsreview in v0.2 dokumentierte die Referenzgewichtung. Diese historischen Quellprüfungen werden in v0.3 nicht wiederholt. Für v0.3 wurden ausschließlich die drei v0.2-Dokumente an den beauftragten Punkten geändert und auf Konsistenz geprüft. v0.2 bleibt unverändert. Es wurden weder Produkt-Repositories geändert noch Code, Produkttests, Paketinstallationen, Laufzeitprüfungen, Migrationen, Deployments oder Gitea-Änderungen ausgeführt. Die Beispiele und Zielkombinationen bleiben K; Dokumentationsprüfungen sind keine T-Validierung der Foundation. diff --git a/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/A_Jinkendo_Technical_Reference_Architecture.diff b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/A_Jinkendo_Technical_Reference_Architecture.diff new file mode 100644 index 0000000..98fa412 --- /dev/null +++ b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/A_Jinkendo_Technical_Reference_Architecture.diff @@ -0,0 +1,120 @@ +--- A_Jinkendo_Technical_Reference_Architecture_v0.2 ++++ A_Jinkendo_Technical_Reference_Architecture_v0.3 +@@ -1,18 +1,40 @@ + # A – Jinkendo Technical Reference Architecture + +-**Phase 3.2 · v0.2 · 16.10.2026 · vorgeschlagener Referenzstandard für neue Anwendungen** ++**Phase 3.2 · v0.3 · 16.10.2026 · vorgeschlagener Referenzstandard für neue Anwendungen** + +-Empfohlen wird eine modulare FastAPI-Anwendung mit React/Vite, PostgreSQL, expliziten Transaktionen und einem Gitea-Ablauf, der geprüfte Build-Artefakte bis zur Produktion erhält. Die Module bleiben zunächst produktlokal. Authentifizierung, Datenraum, Berechtigungen, KI und Subscriptions werden über klar definierte Grenzen angebunden. ++Empfohlen wird eine modulare FastAPI-Anwendung mit React/Vite, PostgreSQL, expliziten Transaktionen und einem Gitea-Ablauf mit verpflichtenden Release-Gates und nachvollziehbarer Zuordnung von Quellstand, Build und getesteter Produktionsversion. Die Module bleiben zunächst produktlokal. Authentifizierung, Datenraum, Berechtigungen, KI und Subscriptions werden über klar definierte Grenzen angebunden. + + Die Referenz wird **pro Mechanismus** ausgewählt: Mitai für Prompt-/Workflow-Ausführung und Registry-Verträge, Shinkan für Nutzer-/Vereinssichten und Zugriffsschutz, Kanshō für private KI-Daten und Maskierung. Kairo ergänzt einzelne Struktur-, Konfigurations- und Maschinenzugriffsmuster. Keine Anwendung ist als Ganzes die führende oder am besten betriebsbewährte Referenz. Die folgende Foundation ist eine gezielte Synthese mit expliziten Anpassungen. + + Diese Empfehlung ist keine Freigabe für Produktionsänderungen. ADR-01 bis ADR-14 und Reuse First gelten als beschlossen; ADR-15 und ADR-16 bleiben offen. Bestehende Apps werden durch dieses Dokument nicht zur Migration verpflichtet. Die visuelle Gestaltung gehört weiterhin in die Frontend Design Guideline. + +-**Lesereihenfolge:** A definiert die technischen Verträge, [B](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.2-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md) macht daraus einen Implementierungsauftrag, [C](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.2-2026-10-16/C_Technical_Decisions_Open_Issues.md) begründet die Auswahl und nennt drei offene Produkt-/Betriebspunkte. ++**Lesereihenfolge:** A definiert die technischen Verträge, [B](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md) macht daraus einen Implementierungsauftrag, [C](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md) begründet die Auswahl und nennt drei offene Produkt-/Betriebspunkte. ++ ++## A0 – Verbindliche Verträge, technische Defaults und Nachweis ++ ++Die Zielarchitektur in A und ihre Ausgestaltung in B sind ein **vorgeschlagener technischer Standard**. Die bereits beschlossenen Architekturverträge gelten unabhängig davon; technische Detailvorschläge werden durch dieses Dokument nicht automatisch zu weiteren beschlossenen Familienverträgen. ++ ++| Einordnung | Geltung in dieser Referenz | ++|---|---| ++| **Verbindliche Architekturverträge** | Verifizierte Identität und Datenraumgrenzen; Fail-Closed-Autorisierung neuer geschützter Funktionen; wirksame Objekt-/Scopeprüfung; sichere atomare Transaktionsgrenzen; verlässlicher Migrations-/Erfolgsnachweis; Secret-/Privacy-Grenzen; verpflichtende Release-Gates und eindeutige Zuordnung zur produktiven Version. Maßgeblich bleiben die beschlossenen ADRs und produktbezogenen Schutzgrenzen. | ++| **Technische Defaults** | Bevorzugte Framework-/Versionslinien in A1, Verzeichnis- und Dateidetails in A2/B1, konkrete Modul-/Hilfsnamen, numerische Listenlimits in A4, Poolgrößen und Zeitbudgets in A5, Clienttimeout in A7/B3 sowie Artefakttransport und bevorzugtes Build-Verfahren in A9/B5. Sie sind begründet anpassbare Ausgangspunkte. | ++ ++Bei begründetem Produktbedarf dürfen Defaults angepasst werden. Grund, gewählter Wert bzw. Ersatz und geeigneter Funktions-/Kompatibilitätsnachweis werden kurz im Produktauftrag oder in der Produktkonfiguration festgehalten; dafür wird kein neuer ADR oder zusätzlicher Freigabezyklus verlangt. Begründete Varianten dürfen keinen verbindlichen Schutz-, Transaktions- oder Releasevertrag abschwächen. Anpassbare Verzeichnisnamen ändern beispielsweise nicht die Verantwortungsgrenzen; anpassbare Timeouts beseitigen keine wirksamen Ressourcenlimits. Die gewählten Versionen müssen weiterhin unterstützt und untereinander kompatibel sein. Nach außen veröffentlichte API-Verträge bleiben gegenüber ihren Clients kompatibel, auch wenn interne Details angepasst werden. ++ ++Für die folgenden Abschnitte gilt diese Nachweiskennzeichnung: ++ ++| Nachweisgrad | Bedeutung / aktueller Stand | ++|---|---| ++| **V – Vorgeschlagener technischer Standard** | Zielentscheidungen und Implementierungsvorgaben in A/B; technisch konkret, noch keine ausgeführte Referenzimplementierung. | ++| **I – Bereits vorhandene Implementierungsreferenz** | Benannte Produktdateien und Mechanismen aus v0.2; statisch untersuchte Vorbilder. Vorhandener Code oder eine Testdatei allein ist kein erfolgreicher Testnachweis. | ++| **T – Tatsächlich durch Tests validierte Lösung** | Nur mit konkretem Testumfang, bestandenem Ergebnis, Quell-/Buildstand und Ausführungsumgebung. Für die hier vorgeschlagene Foundation wird kein solcher Gesamtnachweis behauptet; v0.3 führt keine Tests aus. | ++| **K – Noch nicht integrierte oder getestete Kombination** | Die produktübergreifende Foundation-Synthese, Adapterkombinationen und kleinen Codebeispiele. Zusammenwirken und Versionskompatibilität müssen bei der Umsetzung erst validiert werden. | ++ ++Eine Passage kann V und K zugleich sein; ein I-Verweis hebt sie nicht automatisch auf T. B beschreibt einen künftigen Aufbau und dessen Abnahmebedingungen, keine bereits produktionsreife Referenzimplementierung. Die Versions-/Supportangaben aus A1 werden als bisheriger Dokumentstand übernommen, in v0.3 nicht erneut recherchiert. + + ## A1 – Technologiestack und zulässige Varianten + +-| Bestandteil | Bevorzugte Basis für eine neue App | Verwendung | ++| Bestandteil | Technischer Default für eine neue App | Verwendung | + |---|---|---| + | Backend | Python 3.12, FastAPI, Uvicorn, Pydantic 2 | HTTP, Validierung, Dependency Injection; überwiegend synchrone DB-Anwendungsfälle | + | Datenbank | PostgreSQL 16, Psycopg 3 und dessen `psycopg_pool` | Parametrisiertes SQL; begrenzter Pool; kein ORM als Foundation-Abhängigkeit | +@@ -32,7 +54,7 @@ + + ## A2 – Projektstruktur und Abhängigkeiten + +-Eine Anwendung bleibt ein Repository mit Backend, Frontend, Migrationen, Tests und Deploymentdefinitionen. Backend und Frontend werden getrennt gebaut. Innerhalb des Backends hat jedes Fachmodul Router, Schemas, Service und Repository. Kleine reine Berechnungen können im selben Modul bleiben; zusätzliche Schichten entstehen nur für eine tatsächliche Zuständigkeit. ++**Technischer Strukturdefault:** Eine Anwendung bleibt ein Repository mit Backend, Frontend, Migrationen, Tests und Deploymentdefinitionen. Verzeichnisdetails und Zuschnitt dürfen gemäß A0 angepasst werden; die Verantwortungs- und Schutzgrenzen bleiben erhalten. Backend und Frontend werden getrennt gebaut. Innerhalb des Backends hat jedes Fachmodul Router, Schemas, Service und Repository. Kleine reine Berechnungen können im selben Modul bleiben; zusätzliche Schichten entstehen nur für eine tatsächliche Zuständigkeit. + + ```mermaid + flowchart LR +@@ -72,7 +94,7 @@ + | Vertrag | Festlegung | + |---|---| + | Erfolg | Einzelobjekt direkt; Listen `{items, next_cursor}`; keine zusätzliche globale `data`-Hülle | +-| Listen | `limit` Standard 50, Maximum 200; opaker validierter Cursor; stabile Sortierung mit ID als Tiebreaker | ++| Listen | Numerische Defaults: `limit` 50, Maximum 200; begründet anpassbar. Begrenzte Abfragen, validierter Cursor und stabile Sortierung mit ID als Tiebreaker bleiben der Vertrag. | + | Status | 201 plus `Location` für Anlage; 200 für Lesen/Ändern; 204 ohne Body für Löschen | + | Fehler | RFC-9457-Problem-Details mit `type`, `title`, `status`, sicherem `detail`, `instance`; Erweiterungen `code`, `request_id`, optional `errors` | + | Feldfehler | `errors: [{path, code, message}]`; keine Rohwerte, Passwörter oder Pydantic-`input`-Felder zurückgeben | +@@ -88,7 +110,7 @@ + + Psycopg 3 ist bereits in [Kanshō](C:/Dev/Kansho/backend/requirements.txt) vorhanden. Übernommen wird der Treiber, **nicht** die SQLite-förmige SQL-Übersetzung. SQL verwendet native PostgreSQL-Platzhalter und parametrisierte Werte. Dynamische Bezeichner werden nur aus einer erlaubten Menge über `psycopg.sql` zusammengesetzt. Keine SQL-Fragmente aus Requestdaten. + +-Ein threadgeeigneter `psycopg_pool.ConnectionPool` pro Backend-Prozess begrenzt Verbindungen. Ausgangswerte: ein Prozess, Pool 1–5, Wartezeit 3 Sekunden, höchstens 20 Wartende. Verbindungsaufbau 5 Sekunden; Standard-Statement 5 Sekunden, Lock-Wartezeit 2 Sekunden. Größere Aufgaben dürfen begründete eigene Zeitbudgets erhalten. Mehr Prozesse benötigen eine neue Connection-Budgetrechnung; keine automatische Poolvervielfachung ohne Grenze. ++Ein threadgeeigneter `psycopg_pool.ConnectionPool` pro Backend-Prozess begrenzt Verbindungen. **Anpassbare technische Defaults:** ein Prozess, Pool 1–5, Wartezeit 3 Sekunden, höchstens 20 Wartende. Verbindungsaufbau 5 Sekunden; Standard-Statement 5 Sekunden, Lock-Wartezeit 2 Sekunden. Größere Aufgaben dürfen begründete eigene Zeitbudgets erhalten. Mehr Prozesse benötigen eine neue Connection-Budgetrechnung; keine automatische Poolvervielfachung ohne Grenze. + + Der Pool liefert `autocommit=True`-Verbindungen ausschließlich an den DB-Adapter. Dieser führt jeden fachlichen Zugriff in `connection.transaction()` aus und gibt die Verbindung sauber zurück. Poolerschöpfung wird 503; sie wird nicht durch unbegrenzte zusätzliche Verbindungen umgangen. [Psycopg-Pool](https://www.psycopg.org/psycopg3/docs/advanced/pool.html), [Transaktionskontexte](https://www.psycopg.org/psycopg3/docs/basic/transactions.html) + +@@ -97,7 +119,7 @@ + Neue IDs folgen `20261016T120000Z_short_name.sql`; vollständige IDs und Zeitpräfixe sind eindeutig, Reihenfolge ist lexikalisch. Ein Ledger `schema_migrations(id, sha256, applied_at, build_revision)` ist maßgeblich. Der Runner: + + 1. Validiert Dateinamen und Duplikate im Paket. +-2. Serialisiert Ledgerprüfung und Ausführung mit einem PostgreSQL-Session-Advisory-Lock auf derselben Verbindung und einem festen dokumentierten Schlüssel; nach höchstens 60 Sekunden Wartezeit bricht er ab. Auf leerer DB legt der Runner unter diesem Lock ausschließlich sein Ledger an. Danach liest er den Stand und prüft sämtliche angewandten Prüfsummen; angewandte, aber fehlende Dateien sind ein Fehler. ++2. Serialisiert Ledgerprüfung und Ausführung mit einem PostgreSQL-Session-Advisory-Lock auf derselben Verbindung und einem festen dokumentierten Schlüssel; nach einem begrenzten Wartebudget bricht er ab (technischer Default: 60 Sekunden). Auf leerer DB legt der Runner unter diesem Lock ausschließlich sein Ledger an. Danach liest er den Stand und prüft sämtliche angewandten Prüfsummen; angewandte, aber fehlende Dateien sind ein Fehler. + 3. Führt jede noch offene SQL-Datei und ihren Ledger-Eintrag **in derselben Transaktion und Verbindung** aus. Scheitert eine Datei, endet der Lauf ungleich null; frühere erfolgreich committete Dateien bleiben angewandt. + 4. Gibt den Lock im `finally` frei und schließt die Verbindung. Ein Wiederanlauf überspringt nur nachweislich erfolgreiche Dateien. + +@@ -119,7 +141,7 @@ + + Eine explizite Modulregistrierung liefert Routen und Navigation; doppelte IDs oder Pfade brechen den Aufbau ab. Data Router wird einmal außerhalb des React-Renderns erzeugt. Routen besitzen Loader/Actions und lokale Fehlergrenzen. Kein Router-Neuaufbau beim Wechsel des gewählten Datenraums. [Router Data Mode](https://reactrouter.com/start/data/installation) + +-Ein gemeinsamer `request`-Client kapselt ausschließlich Transport und Fehler. Fachliche API-Funktionen liegen im jeweiligen Modul. Standard: relative Same-Origin-URLs, Cookie-Credentials, 15 Sekunden Timeout, AbortSignal, Prüfung von Content-Type/Status und Unterstützung von 204. Keine Session in Local Storage oder URLs. Keine ungeprüfte HTML-Fehlerausgabe und keine automatischen Wiederholungen von Schreiboperationen. Cookie/CSRF- und Loginlogik bleibt im Auth-Adapter. ++Ein gemeinsamer `request`-Client kapselt ausschließlich Transport und Fehler. Fachliche API-Funktionen liegen im jeweiligen Modul. Transportdefault: relative Same-Origin-URLs und 15 Sekunden Timeout; begründete Anpassungen folgen A0. Cookie-Credentials, AbortSignal, Prüfung von Content-Type/Status und Unterstützung von 204 gehören zum beschriebenen Transportvertrag. Keine Session in Local Storage oder URLs. Keine ungeprüfte HTML-Fehlerausgabe und keine automatischen Wiederholungen von Schreiboperationen. Cookie/CSRF- und Loginlogik bleibt im Auth-Adapter. + + Serverdaten gehören in Route-Loader bzw. modulbezogene Hooks. Formulare und flüchtiger UI-Zustand bleiben lokal in `useState`/`useReducer`. Ein kleiner Session-/Scope-Store enthält nur bestätigten Kontext und einen monotonen `epoch`-Wert. Bei Logout oder Scopewechsel werden Requests abgebrochen, personenbezogene Ergebnisse verworfen und Loader neu ausgeführt. Antworten einer alten Epoche dürfen nicht in die neue Ansicht gelangen. Ein weiterer Cache ist kein Foundation-Bestandteil. + +@@ -149,11 +171,18 @@ + + ## A9 – Testing, Deployment und Reuse + +-Die verbindlichen Mindestfälle, Testbefehle und der genaue Ablauf stehen in B4/B5. Grundsatz der technischen Umsetzung: isolierte PostgreSQL-Testdaten, echte Negativtests, Import-/OpenAPI-Prüfung, Frontend-Fehler-/Scopewechseltests und ein kleiner Browserdurchlauf gegen das tatsächlich gebaute Image. Verpflichtende DB-Suiten dürfen weder vollständig skippen noch durch fehlende Konfiguration still als erfolgreich gelten. ++Die erforderlichen Mindestnachweise und ihre technischen Umsetzungsvorschläge (Befehle und Abläufe) stehen in B4/B5; konkrete Pfade und Befehle dürfen im Rahmen von A0 konsistent angepasst werden. Grundsatz der technischen Umsetzung: isolierte PostgreSQL-Testdaten, echte Negativtests, Import-/OpenAPI-Prüfung, Frontend-Fehler-/Scopewechseltests und ein kleiner Browserdurchlauf gegen das tatsächlich gebaute Image. Verpflichtende DB-Suiten dürfen weder vollständig skippen noch durch fehlende Konfiguration still als erfolgreich gelten. + +-Der Releaseweg bleibt `develop → Dev → Tests → bewusste Freigabe → main → Prod`. Testresultate und unveränderliche Images werden an Source-Commit, Source-Tree und Buildrevision gebunden. Merge-Commits dürfen eine andere SHA haben; ihr Tree muss exakt dem qualifizierten Tree entsprechen. Produktion bekommt die qualifizierten Images ohne Neubuild. Nachgelagerter Health-Smoke bleibt erhalten, ersetzt das Test-Gate aber nicht. ++**Verbindlicher Releasevertrag gemäß ADR-11:** Der Weg bleibt `develop → Dev → Tests → bewusste Freigabe → main → Prod`. Pflicht-Gates müssen vor der Produktionsumschaltung bestanden sein. Quellstand, Build-Eingaben, Testläufe und tatsächlich eingesetzte Artefakte müssen eindeutig zusammengehören. Ein nachgelagerter Health-Smoke ersetzt das Release-Gate nicht. Die bewusste menschliche Produktionsfreigabe bleibt erhalten. + +-Bevorzugt werden Docker-Image-Archive mit SHA-256 und Release-Manifest über die vorhandene Artefaktablage. Eine bereits verfügbare Gitea-OCI-Registry ist eine gleichwertige Transportvariante mit Digestbindung. Keine neue Registry-Infrastruktur wird vorausgesetzt. Die Freigabe erfolgt über geschützten `main` und bewusst angenommenen Release-PR, nicht über ein vermeintliches GitHub-Environment-Gate: Gitea ignoriert `jobs..environment`. [Gitea-Kompatibilität](https://docs.gitea.com/usage/actions/comparison/) ++| Technische Variante | Umsetzung / Nachweis | ++|---|---| ++| **R1 – Bevorzugter Default: Build once, deploy many** | Die in Dev qualifizierten Backend-/Frontend-Artefakte werden unverändert nach Prod übernommen. Hashes/Digests und Buildrevision binden Test und Deployment; kein weiterer Build ist für diese Variante nötig. | ++| **R2 – Zulässige ADR-11-Variante: kontrollierte separate Builds** | Dev- und Prod-Artefakte dürfen getrennt aus nachvollziehbaren Quellständen und reproduzierbar festgehaltenen Build-Eingaben entstehen. Lockfiles, Build-Rezept, Toolchain/Basisimages und erlaubte öffentliche Build-Parameter werden dokumentiert. Der konkrete Prod-Build erhält vor der Umschaltung seine erforderlichen Tests/Gates und eine eigene Artefakt-/Buildkennung. Ein grüner Dev-Build allein qualifiziert kein neu gebautes Prod-Artefakt. Unterschiedliche Artefakthashes zwischen Dev und Prod sind dabei zulässig. | ++ ++In beiden Varianten verknüpft der Releasenachweis getesteten Quell-/Buildstand, menschlich freigegebenen main-Stand und tatsächlich deployte Artefakte. Bei Merge-Commits wird die Beziehung über Commit und Source-Tree nachgewiesen. Der Default ist ein mit dem qualifizierten Stand identischer Tree; abweichender Produktionsquellstand oder abweichende Build-Eingaben benötigen die passenden dokumentierten Gate-Ergebnisse für den konkreten Kandidaten, keine ungeprüfte Gleichsetzung mit dem Dev-Lauf. Reproduzierbarkeit ersetzt diese Tests nicht. ++ ++Default für den Artefakttransport sind Docker-Image-Archive mit SHA-256 und Release-Manifest über die vorhandene Ablage; eine vorhandene Gitea-OCI-Registry mit Digestbindung ist ebenfalls zulässig. Keine Variante verlangt neue CI/CD-Infrastruktur. Die Freigabe erfolgt über geschützten `main` und bewusst angenommenen Release-PR, nicht über ein vermeintliches GitHub-Environment-Gate: Gitea ignoriert `jobs..environment`. [Gitea-Kompatibilität](https://docs.gitea.com/usage/actions/comparison/) + + **Reuse First konkret:** zunächst lokale Implementierung nach denselben Verträgen und Contracttests. Kandidaten für eine spätere Library sind API-Fehlernormalisierung, Registry-Validierung, Settings-/Problem-Modelle und Migrationsrunner. Extraktion erst bei zwei tatsächlichen Nutzern, stabilem Vertrag und Maintainer. Auth, KI-Policy und Subscriptions bleiben produktlokale Adapter; zentrale Dienste sind keine automatische Folge ähnlichen Codes. Keine gemeinsame Fachdatenbank, keine Imports zwischen laufenden Produkt-Repositories. + +@@ -161,4 +190,4 @@ + + ## Nachweisgrenze + +-Basis sind [A01 des Inventars](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json), dessen Dependency-/Guardrailregister und konkrete ausgewählte Quellen. Die genannten Mechanismen sind statisch nachvollzogen. In v0.2 wurde die pauschale Vorrangstellung Kairos entfernt und die Herkunft von Registry-, Zugriffs- und Privacy-Verträgen konkretisiert. Produktreife, Umfang eines Mechanismus, Testquellen und tatsächliche erfolgreiche Nutzung bleiben getrennte Nachweise; es gibt keine belegte Gesamtrangfolge der Produkte. Die Referenzkombination, Versionskompatibilität und kleinen Beispiele wurden nicht als Anwendung ausgeführt. Keine Produktdateien, Migrationen, Deployments oder Gitea-Einstellungen wurden verändert. ++Basis sind [A01 des Inventars](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json), dessen Dependency-/Guardrailregister und konkrete ausgewählte Quellen. Die genannten Mechanismen sind statisch nachvollzogen. In v0.2 wurde die pauschale Vorrangstellung Kairos entfernt und die Herkunft von Registry-, Zugriffs- und Privacy-Verträgen konkretisiert. Produktreife, Umfang eines Mechanismus, Testquellen und tatsächliche erfolgreiche Nutzung bleiben getrennte Nachweise; es gibt keine belegte Gesamtrangfolge der Produkte. Nach A0 sind die Zielangaben V, die benannten Produktmechanismen I und die Foundation-Synthese samt Beispielen K. Ein T-Gesamtnachweis liegt nicht vor: Referenzkombination, Versionskompatibilität und Beispiele wurden nicht als Anwendung ausgeführt. Auch die neuen Release-Varianten sind dokumentierte Vorgaben, keine in diesem Auftrag getesteten Pipelines. Keine Produktdateien, Migrationen, Deployments oder Gitea-Einstellungen wurden verändert. diff --git a/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/B_Implementation_Blueprint_Application_Foundation.diff b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/B_Implementation_Blueprint_Application_Foundation.diff new file mode 100644 index 0000000..9f24ec9 --- /dev/null +++ b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/B_Implementation_Blueprint_Application_Foundation.diff @@ -0,0 +1,161 @@ +--- B_Implementation_Blueprint_Application_Foundation_v0.2 ++++ B_Implementation_Blueprint_Application_Foundation_v0.3 +@@ -1,12 +1,16 @@ + # B – Implementation Blueprint: Application Foundation + +-**Phase 3.2 · v0.2 · 16.10.2026 · unmittelbar nutzbare Implementierungsvorlage** +- +-Dieser Blueprint setzt [A](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.2-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md) um. Er beauftragt hier keine Umsetzung. Ein späterer Coding-Auftrag darf damit die Foundation einer benannten App aufbauen; Fachfunktionen, vollständige Auth-/KI-/Subscription-Blueprints und Bestandsmigrationen gehören nicht automatisch dazu. ++**Phase 3.2 · v0.3 · 16.10.2026 · vorgeschlagener Blueprint, keine ausgeführte Referenzimplementierung** ++ ++Dieser Blueprint setzt [A](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md) um. Er beauftragt hier keine Umsetzung. Ein späterer Coding-Auftrag darf damit die Foundation einer benannten App aufbauen; Fachfunktionen, vollständige Auth-/KI-/Subscription-Blueprints und Bestandsmigrationen gehören nicht automatisch dazu. ++ ++**Geltung und Nachweis:** Dieser Blueprint ist V und als kombinierte Lösung K gemäß A0. Benannte Produktdateien sind I; geforderte Mindesttests sind noch keine T-Ergebnisse. Weder die Beispielausschnitte noch die gesamte Foundation sind hier integriert, getestet oder als produktionsreif nachgewiesen. Die tatsächliche Implementierung muss die erforderlichen Nachweise erst erbringen. ++ ++**Verträge und Defaults:** Verbindlich bleiben insbesondere Datenraum-/Privacy-Grenzen, Fail-Closed-Zugriff, sichere Transaktionen und Release-Gates. Verzeichnisdetails, Modulnamen, Framework-/Versionslinien und numerische Einstellungen sind technische Defaults gemäß A0. Begründete Anpassungen sind im Produktauftrag bzw. in dessen Konfiguration kurz festzuhalten; keine zusätzliche Freigabeschleife. Die Aussage „gemäß A“ meint diese Unterscheidung, keinen starren Zwang zu jedem Beispielwert. + + ## B1 – Auftrag und Zielstruktur + +-**Auftrag an den Coding-Agenten:** Erstelle im ausdrücklich benannten neuen Produkt-Repository die folgende Foundation. Verwende die Versionslinien aus A1, löse stabile Patchstände auf und committe Lockfiles. Übernimm die unten genannten vorhandenen Mechanismen nach Anpassung ihrer Schnittstellen. Verändere keine anderen Produkt-Repositories. Erzeuge weder Beispiel-Fachprodukt noch allgemeines Framework. Lege leere Fachmodulordner erst mit der ersten echten Funktion an. ++**Auftrag an den Coding-Agenten:** Erstelle im ausdrücklich benannten neuen Produkt-Repository eine Foundation nach den Verträgen dieses Blueprints. Nutze den folgenden Verzeichnisbaum und die Versionslinien aus A1 als technische Defaults; begründete Anpassungen folgen A0. Löse stabile kompatible Patchstände auf und committe Lockfiles. Übernimm die unten genannten vorhandenen Mechanismen nach Anpassung ihrer Schnittstellen. Verändere keine anderen Produkt-Repositories. Erzeuge weder Beispiel-Fachprodukt noch allgemeines Framework. Lege leere Fachmodulordner erst mit der ersten echten Funktion an. + + ```text + / +@@ -63,7 +67,7 @@ + └── docs/ # OpenAPI-Baseline, kurze Start-/Betriebshinweise + ``` + +-Python läuft mit `backend` als Working Directory, Imports beginnen mit `app.`. Jede Package-Ebene enthält `__init__.py`; keine `sys.path`-Reparaturen oder Importe wie `from main import ...`. API-/DB-/Modulimporttests müssen ohne Kontakt zu DB oder Anbieter funktionieren. Der Runner legt nur sein eigenes Ledger unter Lock an. Die erste SQL-Migration erstellt den tatsächlich benötigten Infrastrukturzustand, etwa den transaktionalen Audit-Speicher mit den Feldern aus A6; keine erfundenen Tenant-, Actor-, Billing- oder Memorytabellen. ++Im dargestellten Strukturdefault läuft Python mit `backend` als Working Directory, Imports beginnen mit `app.`. Bei anderer begründeter Verzeichnisstruktur werden Importpfade und Befehle konsistent angepasst; keine impliziten Importnebenwirkungen. Jede Package-Ebene enthält `__init__.py`; keine `sys.path`-Reparaturen oder Importe wie `from main import ...`. API-/DB-/Modulimporttests müssen ohne Kontakt zu DB oder Anbieter funktionieren. Der Runner legt nur sein eigenes Ledger unter Lock an. Die erste SQL-Migration erstellt den tatsächlich benötigten Infrastrukturzustand, etwa den transaktionalen Audit-Speicher mit den Feldern aus A6; keine erfundenen Tenant-, Actor-, Billing- oder Memorytabellen. + + ## B2 – Backend bauen + +@@ -88,7 +92,7 @@ + + ### Transaktionsmuster + +-Illustration des DB-Adapters; Pool-Konfiguration und Fehlerübersetzung kommen aus A5/A4: ++Nicht integrierte und nicht ausgeführte Illustration (K) des DB-Adapters; Pool-Konfiguration und Fehlerübersetzung kommen aus A5/A4. `timeout=3` ist ein technischer Default, keine unveränderliche Architekturgrenze: + + ```python + from contextlib import contextmanager +@@ -134,7 +138,7 @@ + | `MIGRATION_DATABASE_URL` | Nur Migrationsprozess; fehlt im Runtime-Container | + | `BUILD_REVISION` | Source-Commit des gebauten Images, im Image festgehalten; nicht durch Deploy überschreiben | + | `EXPECTED_SCHEMA_HEAD` | Aus dem qualifizierten Deploy-Manifest; Readiness vergleicht mit tatsächlichem Ledger-Head | +-| Pool-/SQL-Zeitbudgets | Typisiert und begrenzt entsprechend A5; keine negativen/ungeprüften Zahlen | ++| Pool-/SQL-Zeitbudgets | Numerische Defaults aus A5 begründet anpassbar; typisierte Validierung und wirksame Grenzen bleiben erforderlich. | + | `FEATURE_FLAGS` | Validiertes Objekt registrierter boolescher Schlüssel; fehlende optionale Funktion aus | + | Provider-/Cookie-/Auth-Secrets | Erst mit dem jeweiligen echten Adapter; nie unsichere Entwicklungsdefaults | + +@@ -146,7 +150,7 @@ + + Verwende für den Registry-Vertrag zuerst Mitais [Schlüsselregistrierung mit Duplikatsperre](C:/Dev/mitai-jinkendo/backend/placeholder_registry.py:169) und die produktlokale Komponentenregistry als Vorbilder; übertrage den kleinen Vertrag, nicht den gesamten fachlichen Placeholder-Katalog. Baue einen Data Router aus einer statischen Liste lokaler Moduldefinitionen. Definiere den Modulvertrag als JSDoc mit `id`, `routes`, `navigation` und benötigten Capability-/Feature-Schlüsseln. Registryaufbau prüft doppelte IDs/Pfade und unbekannte Schlüssel, statt sie zu überschreiben. UI-Gates verbessern die Bedienung; der Server prüft jeden Zugriff selbst. + +-Der Transportvertrag lautet: ++Der vorgeschlagene Transportvertrag (V) wird durch folgenden nicht ausgeführten Ausschnitt (K) illustriert; `timeoutMs: 15000` ist ein anpassbarer technischer Default: + + ```javascript + request(path, { +@@ -168,7 +172,7 @@ + + Formulare nutzen lokalen Zustand. Mutationen invalidieren die betroffenen Loader, keinen pauschalen Full-Page-Reload. Routen haben Fehlergrenzen für nicht verfügbare Module und Transportfehler. Produktlokale darstellende Komponenten importieren keinen eigenen Live-API-Client. Die Design Guideline wird verwendet, ohne in diesem Blueprint neue visuelle Tokens festzulegen. + +-Der Frontend-Build enthält keine Dev-/Prod-Origins oder privaten VITE-Variablen. API-Pfade bleiben Same-Origin, damit exakt dasselbe Frontend-Image in Dev und Prod nutzbar ist. Keine PWA in der Grundstruktur; bei realem Installationsbedarf gilt A7, einschließlich Test der persönlichen API-Cachegrenze. ++Bevorzugter Frontend-Default sind relative Same-Origin-API-Pfade ohne Dev-/Prod-Origins im Build; damit kann R1 dasselbe Frontend-Image verwenden. R2 darf nachvollziehbar deklarierte öffentliche Build-Parameter unterscheiden und muss den konkreten Prod-Build validieren. Secrets und private VITE-Variablen bleiben in beiden Varianten ausgeschlossen. Keine PWA in der Grundstruktur; bei realem Installationsbedarf gilt A7, einschließlich Test der persönlichen API-Cachegrenze. + + ## B4 – Mindesttests und lokale Befehle + +@@ -186,7 +190,7 @@ + | Client/State | JSON/204/HTML/Netzfehler/Timeout; keine automatische Write-Wiederholung; Scopewechsel mit verspäteter Antwort und verspätetem 401 | + | Modul/Route | Doppelte IDs/Pfade verweigert; unbekannter Schlüssel; Loaderfehler lokal; fehlende UI-Rechte; Dirty-Form-Blocker auf tatsächlicher Routerversion | + | Browser | Gebauter Stack: SPA-Direktaufruf, API-Fehlerzustand, Testidentitäts-/Scopewechsel; Cookie-/CSRF-Fälle erst mit echtem Auth-Adapter verpflichtend ergänzen | +-| Release | Rotes Pflicht-Gate, fehlende DB-Suite, falsche Tree-SHA, verändertes Image-Archiv oder falsche Buildrevision verhindern Promotion | ++| Release | In R1 und R2 sperren rote/fehlende Pflicht-Gates und nicht passende Quell-/Build-/Artefaktnachweise das Deployment. R1 prüft identische qualifizierte Artefakte; R2 prüft auch den separaten Prod-Kandidaten vor der Umschaltung. | + + DB-Tests laufen gegen PostgreSQL 16 mit eigenem kurzlebigem Compose-Projekt je Run und synthetischen Daten. Keine lokale/private oder laufende Dev-/Prod-DB als Testtarget. Der Wächter verlangt `APP_ENV=test`, passende Run-ID im DB-Namen, erlaubtes CI-Netz und erfolgreichen Abgleich von `current_database()` **vor** jeder Schemaänderung. Runtime- und Migrationsrolle werden auch im Test getrennt. Cleanup ist garantiert, auch bei Fehlern; keine gemeinsam fest benannte Testdatenbank für parallele Runs. + +@@ -207,44 +211,52 @@ + + ## B5 – Gitea-Ablauf und Build-Nachvollziehbarkeit + +-Implementiere später zwei logische Workflows: **Qualification** für `develop` und **Production** nach bewusster Freigabe auf `main`. Nicht vertrauenswürdige PR-Checks erhalten weder Deploy-/Prod-Secrets noch Zugriff auf produktive Docker-Sockets. Deploy-Jobs laufen nur für geschützte eigene Branches auf berechtigten Runnern. Verwendete Actions werden auf geprüfte Commitstände gepinnt; Artefaktaktionen müssen zur tatsächlich eingesetzten Gitea-/Runner-Version passen. Giteas tatsächliche Schutz-/Runnerkonfiguration ist vor dem ersten Release nachzuweisen; siehe C, O2. +- +-| Stufe | Konkreter Ablauf / Gate | +-|---|---| +-| 1 · develop | Exakten Commit S auschecken; Source-Tree T und Lockfilehashes festhalten. Schnelle Tests, Import/OpenAPI-Diff und gelockter Build müssen bestehen. | +-| 2 · Build/Dev | Backend-/Frontend-Images einmal bauen, mit S labeln, Digests und Archiv-SHA-256 festhalten. Explizite Dev-Migration; genau diese Images nach Dev. Read-only-Smoke prüft Health und Buildrevision. | +-| 3 · Tests | Dieselben Images in isoliertem Compose-Stack mit PostgreSQL und Testkonfiguration prüfen; Pflichtsuiten aus B4 sowie Browserfälle. Kein pytest/pip install im laufenden Dev-/Prod-Container. | +-| 4 · Qualifiziert | Erst nach allen Gates Release-Manifest und unveränderliche Artefakte aus einem vertrauenswürdigen Job ablegen; fehlende/übersprungene Pflichtfälle sperren. | +-| 5 · Bewusste Freigabe | Mensch nimmt Release-PR `develop → main` an. Geschützter Branch verlangt den Qualification-Status; keine pauschale Admin-Bypassroutine. | +-| 6 · main/Prod | Manifest des freigegebenen Runs laden; S muss in main enthalten sein und `tree(main) == T`. Alle Hashes, Gates und Artefakte prüfen. Bei Abweichung stoppen und über develop neu qualifizieren; kein ungeprüfter Ersatzbuild. | +-| 7 · Umschaltung | Pro Umgebung Deployment serialisieren; Kompatibilität/Backupbedingung prüfen, explizite Prod-Migration, Images laden und umschalten, Read-only-Smoke. Ergebnis mit main- und Buildrevision protokollieren. | +- +-Der Qualification-Status allein ist kein Prod-Secret. Production vertraut nur dem Manifest des erfolgreichen geschützten Workflow-Runs, dessen ID und Commit zum Release gehören; kein beliebig hochgeladenes JSON und kein nachträglich bewegbares `latest`-Tag. Artefakte werden mit Zugriffsschutz mindestens über das vereinbarte Rollbackfenster aufbewahrt. Ein bereits vorhandener OCI-Transport darf die Archive ersetzen, nicht die Gate-/Digestprüfung. +- +-Das Release-Manifest enthält verbindlich: ++**Verbindlich:** `develop → Dev → Tests → bewusste Freigabe → main → Prod`, erforderliche Release-Gates, menschliche Freigabe und eindeutige Versions-/Artefaktzuordnung. **Technische Varianten:** R1 „Build once, deploy many“ ist der bevorzugte Default; R2 sind nach ADR-11 weiterhin zulässige kontrollierte, reproduzierbare getrennte Dev-/Prod-Builds. Beides sind noch nicht ausgeführte Verfahrensvorgaben (V/K), keine hier validierten Pipelines. ++ ++Die bestehenden Gitea-Prozesse werden entsprechend genutzt. Zwei logische Aufgaben – Dev-Qualifikation und Produktionsfreigabe/-deployment – können in den vorhandenen Workflows abgebildet werden; Dateinamen und Jobaufteilung sind Defaults, keine neue Infrastrukturvorgabe. Nicht vertrauenswürdige PR-Checks erhalten weder Deploy-/Prod-Secrets noch Zugriff auf produktive Docker-Sockets. Deploy-Jobs laufen nur für geschützte eigene Branches auf berechtigten Runnern. Actions werden auf geprüfte Commitstände gepinnt und müssen zur eingesetzten Gitea-/Runner-Version passen. Siehe C, O2. ++ ++| Stufe | R1 – bevorzugt: identische Artefakte | R2 – zulässig: separate Builds | ++|---|---|---| ++| 1 · develop | Quellcommit S/Tree T, Lockfiles und Build-Eingaben festhalten; schnelle Tests und Import-/OpenAPI-Prüfung. | Derselbe Dev-Vertrag; Dev-Build-Rezept und Parameter eindeutig aufzeichnen. | ++| 2 · Dev | Backend-/Frontend-Artefakte bauen und identifizieren, explizite Dev-Migration und Dev-Deployment; Read-only-Smoke. | Identifizierte Dev-Artefakte bauen und nach Dev deployen; Migration und Read-only-Smoke wie R1. | ++| 3 · Tests | Die gebauten Artefakte im isolierten Stack mit Pflichtsuiten aus B4 und Browserfällen qualifizieren. | Die Dev-Artefakte mit den erforderlichen Suiten qualifizieren. Das Ergebnis gilt für diesen Dev-Build, nicht automatisch für einen späteren Prod-Build. | ++| 4 · Bewusste Freigabe | Mensch nimmt den Release-PR nach erfolgreicher Dev-Qualifikation auf geschütztes `main` an. | Dieselbe menschliche Freigabe; freigegebener Quellstand und deklarierte Produktions-Build-Eingaben bleiben nachvollziehbar. | ++| 5 · Prod-Kandidat / Gate | Qualifizierte Artefakte aus dem passenden vertrauenswürdigen Run übernehmen, Hashes und Quellbeziehung prüfen. Default: S ist in main enthalten und `tree(main) == T`. | Aus dem freigegebenen Stand mit gelockten Abhängigkeiten, festgehaltenem Build-Rezept, Toolchain/Basisimages und deklarierten Parametern reproduzierbar separat bauen. Den konkreten Prod-Kandidaten im isolierten Stack vor Deployment durch seine Pflicht-Gates führen; eigener Validierungsrun und eigene Artefaktkennungen. | ++| 6 · Prod | Erst bei vollständigem Nachweis: Deployment serialisieren, Schema-/Backupbedingung prüfen, explizite Prod-Migration, qualifizierte Artefakte umschalten. | Erst nach erfolgreichen Gates für den separaten Prod-Build dieselben Betriebsbedingungen prüfen und genau diesen Prod-Kandidaten umschalten. Keine ungetestete zusätzliche Änderung oder weiterer ungeprüfter Build. | ++| 7 · Smoke | Read-only-Smoke und eingesetzte Build-/Artefaktkennung protokollieren. | Identische Nachweispflicht für die tatsächlich eingesetzte Prod-Version. | ++ ++Ein rotes, fehlendes oder übersprungenes Pflicht-Gate stoppt beide Varianten. `main` enthält den bewusst freigegebenen Stand; eine Abweichung vom Dev-Tree darf nicht unter dessen grünem Ergebnis als mitgetestet gelten. Sie benötigt die zugehörigen Tests und Nachweise für den tatsächlich freigegebenen Produktionsquellstand. Änderungen außerhalb dieser menschlich freigegebenen Eingaben sind kein bereits genehmigter Release. Ein weiterer menschlicher Freigabezyklus nur wegen der Wahl von R2 wird nicht eingeführt. ++ ++Der Produktionstest läuft isoliert gegen den konkreten Prod-Kandidaten, niemals mit synthetischen Mutationen in einer Kundendatenbank. Weder Reproduzierbarkeit noch ein Health-Smoke nach Deployment ersetzen dieses Gate. Runtime-/Build-Eingaben werden kontrolliert aufgelöst; spontane Paketupdates oder nicht dokumentierte Build-Änderungen sind in keiner Variante erlaubt. Ein kontrollierter Prod-Build in R2 ist ausdrücklich zulässig. ++ ++**Releasenachweis für beide Varianten:** getesteter Quell-/Buildstand, freigegebener main-Stand und tatsächlich deployte Artefakte werden verknüpft. Das nachstehende Manifest ist das bevorzugte technische Format; gleichwertige vorhandene Gitea-Nachweise dürfen es abbilden. Verbindlich ist die vollständige Zuordnung, nicht ein bestimmter JSON-Feldname oder zusätzlicher Dienst. + + ```text +-product_id, source_commit, source_tree, qualification_run_id, +-backend_image_id/digest, frontend_image_id/digest, +-backend_archive_sha256, frontend_archive_sha256 # bei Archivtransport +-runtime_lock_sha256, frontend_lock_sha256, ++product_id, build_variant (R1/R2), approved_main_commit, ++dev_source_commit/tree, dev_build_id, dev_qualification_run_id, ++prod_source_commit/tree, prod_build_id, prod_validation_run_id, ++backend/frontend_artifact_ids und Hashes/Digests je Build, ++Lockfilehashes, Build-Rezept/Toolchain/Basisimages und öffentliche Build-Parameter, + migrations_digest, expected_schema_head, +-gate_results mit Pflichtsuiten und Anzahl ausgeführter/übersprungener Fälle, +-dev_smoke_build_revision, qualified_rollback_images +-``` +- +-Der main-Merge-Commit wird im Promotionprotokoll zusätzlich festgehalten. Er ist nicht zwangsläufig S; Gleichheit des vollständigen Trees und Erreichbarkeit von S erhalten die Bindung an den geprüften Inhalt. Die Freigabe eines älteren qualifizierten S bleibt möglich, wenn diese Bedingungen erfüllt sind; eine inzwischen weitergelaufene Dev-Instanz ersetzt seinen Nachweis nicht. +- +-Gitea `environment: production` zählt nicht als manuelle Freigabe. Workflowübergreifende Reihenfolge und Deploymentserialisierung werden ausdrücklich hergestellt, nicht aus `workflow_run` oder GitHub-Kompatibilität vermutet. Als kleine lokale Sperre genügt ein produkt-/umgebungsspezifischer Hostlock um den gesamten Deploy-Schritt, sofern die Jobs auf demselben Deploy-Host laufen. Fehler geben Lock und temporären Teststack zuverlässig frei. +- +-Rollback verwendet nur ein auf dem aktuellen Schema qualifiziertes voriges Imagepaar. Migrationen laufen nicht automatisch rückwärts. Ist die Kompatibilität nicht nachgewiesen, stoppt die Promotion vor der Migration; nach einem unerwarteten Fehler sind kontrollierter Forward-Fix oder der ausdrücklich vorbereitete Restore erforderlich. Vor datenverändernden Releases gelten die Backup-/Recoverybedingungen des Produktprofils; Health allein belegt keine Wiederherstellbarkeit. ++gate_results je qualifiziertem Build mit Ausführungs-/Skipnachweisen, ++deployed_build_id und tatsächlich eingesetzte Artefakthashes, ++qualified_rollback_images ++``` ++ ++In R1 dürfen Dev- und Prod-Build-/Validierungsreferenzen auf denselben qualifizierten Build verweisen. In R2 sind die getrennten Builds und ihre Ergebnisse explizit zugeordnet; unterschiedliche Hashes sind kein Fehler, wenn gerade das eingesetzte Prod-Artefakt qualifiziert ist. Merge-Commits werden über Commit und Source-Tree den Freigaben zugeordnet. Eine inzwischen weitergelaufene Dev-Instanz ersetzt keinen dieser Nachweise. ++ ++Production vertraut den Nachweisen der passenden geschützten Workflow-Runs, nicht einem beliebig hochgeladenen JSON oder bewegbaren `latest`-Tag. Artefakte bleiben mindestens über das vereinbarte Rollbackfenster nachvollziehbar verfügbar. Archive mit SHA-256 und eine bereits vorhandene OCI-Registry mit Digestbindung sind Transportvarianten; keine neue CI/CD-Infrastruktur wird verlangt. ++ ++Gitea `environment: production` zählt nicht als manuelle Freigabe. Workflowübergreifende Reihenfolge und Deploymentserialisierung werden ausdrücklich hergestellt. Ein produkt-/umgebungsspezifischer Hostlock ist ein technischer Default bei Jobs auf demselben Deploy-Host, keine Pflicht zu genau diesem Mechanismus. Fehler geben die gewählte Sperre und temporäre Teststacks zuverlässig frei. ++ ++Rollback verwendet ein auf dem aktuellen Schema qualifiziertes voriges Artefaktpaar. Migrationen laufen nicht automatisch rückwärts. Ohne erforderliche Kompatibilität stoppt das Release vor der Migration; nach unerwarteten Fehlern gelten kontrollierter Forward-Fix oder vorbereiteter Restore. Die Backup-/Recoverybedingungen des Produktprofils bleiben für beide Build-Varianten unverändert. + + ## B6 – Erweiterung und Fertigstellung + + Ein neues Fachmodul ergänzt Router/Schemas, Anwendungsservice und scoped Repository, registriert sich im Backend-Bootstrap und gegebenenfalls in der Frontend-Modulliste, bringt seine Migration und Negativtests mit und ändert keine fremden Router. Ein neuer externer Adapter wird nur im Composition Root eingebunden. Wiederverwendbare Komponenten erhalten einen Testvertrag; eine Library wird erst bei zwei tatsächlichen Abnehmern extrahiert. + +-**Nicht übernehmen:** Clientheader als Identität, erste Profil-/Club-ID als Fallback, Probe als neue Schutzvorgabe, dynamisch importierte Clientmodule, Commit nach Response, versteckte zweite DB-Verbindung, Migration beim Import, Erfolgsledger nach separatem SQL-Prozess, pauschales `catch → null`, persönliche API-Caches, neu aufgelöste Pakete im Release, rebuild in Prod, Tests mit Kundendaten oder Anbieter-Schlüsseln. +- +-Die Foundation ist implementiert, wenn Struktur und Verträge stehen, die Pflichtfälle ihrer tatsächlich registrierten Funktionen laufen, Lockfiles und OpenAPI vorliegen und der Releaseweg reproduzierbar sperren kann. Fehlende Spezialadapter bleiben sichtbar geschlossen; sie werden nicht durch Fakes produktionsreif erklärt. Der Implementierungsbericht nennt Commit, Testbefehle/Umgebung, Ergebnisse und verbleibende Produktadapter knapp. Kein zusätzlicher ADR-Zyklus ist dafür erforderlich. ++**Nicht übernehmen:** Clientheader als Identität, erste Profil-/Club-ID als Fallback, Probe als neue Schutzvorgabe, dynamisch importierte Clientmodule, Commit nach Response, versteckte zweite DB-Verbindung, Migration beim Import, Erfolgsledger nach separatem SQL-Prozess, pauschales `catch → null`, persönliche API-Caches, ungeplant neu aufgelöste Pakete im Release, ungeprüfter Prod-Neubuild, Tests mit Kundendaten oder Anbieter-Schlüsseln. ++ ++Abnahmebedingungen für eine künftige Foundation-Implementierung sind: Struktur und Verträge umgesetzt, Pflichtfälle der tatsächlich registrierten Funktionen nachweislich bestanden, Lockfiles/OpenAPI vorhanden und wirksame Release-Sperren belegt. Diese Bedingungen sind hier Vorgaben, kein Bericht bereits bestandener Tests. Auch ihre spätere Erfüllung ersetzt keine produktbezogene Produktionsreifeprüfung. Fehlende Spezialadapter bleiben sichtbar geschlossen; sie werden nicht durch Fakes produktionsreif erklärt. Der Implementierungsbericht nennt Commit, Testbefehle/Umgebung, Ergebnisse und verbleibende Produktadapter knapp. Kein zusätzlicher ADR-Zyklus ist dafür erforderlich. + + **Vorhandene Vorbilder nach Mechanismus:** Mitai: [Registry/Resolver](C:/Dev/mitai-jinkendo/backend/placeholder_registry.py:159), [Prompt-/Workflow-Laufzeit](C:/Dev/mitai-jinkendo/backend/workflow_executor.py:39) bei echtem KI-Bedarf, [gemeinsamer Cursor/Savepoints](C:/Dev/mitai-jinkendo/.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md:27). Shinkan: [Sichten/Zugriff](C:/Dev/shinkan-jinkendo/backend/tenant_context.py:57), [Security-Regressionen](C:/Dev/shinkan-jinkendo/backend/tests/test_security_release.py:37), Navigation. Kanshō: [Maskierung und Egress-Gate](C:/Dev/Kansho/backend/privacy_gateway.py:1257) sowie getrennte Testdaten. Kairo: einzelne Service-/Konfigurations-/Maschinenzugriffsbausteine als ergänzende Kandidaten. Kein Produkt wird vollständig kopiert; die Zieltransaktion ist die in A/B beschriebene gezielte Referenzlösung. diff --git a/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/C_Technical_Decisions_Open_Issues.diff b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/C_Technical_Decisions_Open_Issues.diff new file mode 100644 index 0000000..c619645 --- /dev/null +++ b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/C_Technical_Decisions_Open_Issues.diff @@ -0,0 +1,73 @@ +--- C_Technical_Decisions_Open_Issues_v0.2 ++++ C_Technical_Decisions_Open_Issues_v0.3 +@@ -1,16 +1,24 @@ + # C – Technical Decisions & Open Issues + +-**Phase 3.2 · v0.2 · 16.10.2026 · technischer Vorschlag, keine Produktionsfreigabe** ++**Phase 3.2 · v0.3 · 16.10.2026 · technischer Vorschlag, keine Produktionsfreigabe** + + ## Management-Zusammenfassung + +-Die Referenz bleibt beim vorhandenen Stack: FastAPI, React/Vite, PostgreSQL, Docker Compose und Gitea. Neu zusammengeführt werden eine modulare Struktur, explizite Transaktionen, ein einheitlicher HTTP-Vertrag und eine nachweisbare Promotion geprüfter Images. Für neue Apps werden unterstützte Versionslinien verwendet; vorhandene Apps erhalten keinen pauschalen Upgradeauftrag. ++Die Referenz bleibt beim vorhandenen Stack: FastAPI, React/Vite, PostgreSQL, Docker Compose und Gitea. Neu zusammengeführt werden eine modulare Struktur, explizite Transaktionen, ein einheitlicher HTTP-Vertrag und ein Release-Verfahren mit verpflichtenden Gates und nachvollziehbarer Quell-/Build-/Artefaktzuordnung. Für neue Apps werden unterstützte Versionslinien verwendet; vorhandene Apps erhalten keinen pauschalen Upgradeauftrag. + + Die frühere Hervorhebung Kairos als „Hauptvorbild“ war zu weitgehend und wird zurückgenommen. Ich hatte die sichtbare Service-/Registry-Struktur für die Foundation übergewichtet und die spezialisierten, tatsächlich vorhandenen Mechanismen der anderen Produkte zu stark auf Nebenrollen reduziert. Daraus folgt weder Kairos höhere Produktreife noch ein belegter Vorsprung bei den meisten belastbaren Mustern. + + Die korrigierte Referenzwahl ist bereichsspezifisch: **Mitai für Prompt-/Workflow-Laufzeit und Registrierungsverträge; Shinkan für Nutzer-/Vereinssichten, Berechtigungen und Security-Mechanismen; Kanshō für Maskierung privater KI-Daten; Kairo für einzelne ergänzende Struktur-, Konfigurations- und Actor-Token-Muster.** Die Foundation bleibt eine Synthese. Transaktions-, Migrations- und Releaseverträge werden dort gezielt ergänzt, wo keine vorhandene Implementierung vollständig genügt. + + Die drei offenen Punkte unten betreffen die erste konkrete Produkteinführung. Die Foundation benötigt dafür keine weitere Grundsatzentscheidung. Der nächste sinnvolle Spezial-Blueprint ist **Auth, Session & Scope**: sichere Cookies/CSRF, verlässliche Datenraumauflösung, Objektzugriff und geschlossene Ersteinrichtung. Kein weiterer Arbeitsschritt wurde automatisch gestartet. ++ ++## Gezielte Korrekturen in v0.3 ++ ++1. **ADR-11 / Release:** R1 „Build once, deploy many“ bleibt bevorzugter technischer Default. R2 – kontrollierte, reproduzierbare getrennte Dev-/Prod-Builds – bleibt zulässig. Beide benötigen Pflicht-Gates vor Prod, menschliche Freigabe und eindeutige Zuordnung der tatsächlich eingesetzten Version. Bei R2 wird der konkrete Prod-Kandidat zusätzlich qualifiziert. Branchstrategie und bestehende Infrastruktur bleiben erhalten. ++2. **Nachweis:** A/B sind V (vorgeschlagener technischer Standard) und als Kombination K (noch nicht integriert/getestet). Produkt-Codeverweise sind I (vorhandene Implementierungsreferenz). T setzt bestandene Tests mit Umfang, Stand und Umgebung voraus; für die Foundation wird kein T-Gesamtnachweis oder Produktionsreife behauptet. Die früher benannten Testquellen werden dadurch nicht zu Testergebnissen. ++3. **Verträge / Defaults:** A0 unterscheidet verbindliche Schutz-, Datenraum-, Transaktions- und Releaseverträge von anpassbaren technischen Defaults wie Poolgröße, Timeout, Verzeichnisdetail und Framework-Version. Begründete Anpassung im Produktauftrag bzw. in der Konfiguration genügt; keine neuen ADRs oder Freigabeschleifen. ++ ++Die bereichsspezifische Referenzauswahl und die bisherigen drei offenen Produkt-/Betriebspunkte bleiben unverändert. Die nachstehende Einordnung wird aus v0.2 übernommen; v0.3 führt keine erneute Produktreifebewertung oder Konsolidierung durch. + + ## Überprüfung der bisherigen Gewichtung + +@@ -29,16 +37,18 @@ + + ## Technische Empfehlungen und wichtigste Alternativen + ++Nachweisstatus: Die bevorzugten Zielausgestaltungen sind V, ihre noch nicht ausgeführte Kombination K; die Herkunftsspalte nennt bestehende Referenzen I. Keine Zeile wird hier als durch Tests validierte Foundation-Lösung T ausgewiesen. Die Geltung verbindlicher Verträge gegenüber technischen Defaults folgt A0. ++ + | ID / Bereich | Bevorzugte Lösung und Begründung | Wichtigste Alternative / bewusste Grenze | Konkrete Herkunft | + |---|---|---|---| +-| TF-01 · Struktur | Produktlokaler modularer Monolith; Router → Service → Repository/Port; ein Composition Root. Vorhanden, einfach zu erweitern, kein neuer Betrieb. | Großer Router-Monolith wird nicht fortgesetzt; Microservices oder allgemeiner Domänenkern bringen für die Foundation keinen belegten Vorteil. | Gezielte Synthese: [Mitai-Cursorvertrag](C:/Dev/mitai-jinkendo/backend/data_layer/activity_persistence_orchestrator.py:171), Kairo-Serviceabgrenzung als Teilbeispiel; dort keine durchgängige Zielschichtung. | ++| TF-01 · Struktur | Produktlokaler modularer Monolith; Router → Service → Repository/Port; ein Composition Root. Aus vorhandenen Teilmechanismen abgeleiteter Zielentwurf, noch keine validierte Gesamtimplementierung; kein neuer Betrieb. | Großer Router-Monolith wird nicht fortgesetzt; Microservices oder allgemeiner Domänenkern bringen für die Foundation keinen belegten Vorteil. | Gezielte Synthese: [Mitai-Cursorvertrag](C:/Dev/mitai-jinkendo/backend/data_layer/activity_persistence_orchestrator.py:171), Kairo-Serviceabgrenzung als Teilbeispiel; dort keine durchgängige Zielschichtung. | + | TF-02 · Backend | FastAPI/Pydantic, explizite DI, synchrone PostgreSQL-Anwendungsfälle, ein Transaktionskontext je atomarem Service. | Durchgehend async nur bei realem I/O-Bedarf. Keine zweite Connection in verschachtelten Validierungen, kein später Response-Commit. | KI-MIT-02/17; [Cursor-/Savepoint-Regeln](C:/Dev/mitai-jinkendo/.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md:27); Anpassungsbedarf im [Kairo-Service](C:/Dev/kairo-jinkendo/backend/services/actions.py:152) | + | TF-03 · Frontend | React-SPA, explizite Modulregistry, Data Router, lokaler Formularzustand; kleiner Session-/Scope-Store statt globalem Fachdaten-Context. | Kein Redux/TanStack-Query-Zwang ohne konkreten Bedarf; kein SSR-/RSC-Wechsel. Registry darf Fehler nicht verschlucken. | Vorrangig [Mitai-Registryvertrag](C:/Dev/mitai-jinkendo/backend/placeholder_registry.py:169) und [Widgets](C:/Dev/mitai-jinkendo/frontend/src/widgetSystem/dashboardWidgetRegistry.jsx:18); [Shinkan-Navigation](C:/Dev/shinkan-jinkendo/frontend/src/hooks/useUnsavedChangesBlocker.js:8); Kairo-Slices ergänzend. | + | TF-04 · API | `/api/v1`, explizite Pydantic-DTOs, OpenAPI und Problem Details; ein Browser-Transportclient. | Heutige verschiedenförmige `detail`-/HTML-Fehler werden nur im Bestandsadapter toleriert; kein vollständiges neues RPC-/GraphQL-System. | KI-MIT-04; [vorhandene Fehlernormalisierung](C:/Dev/mitai-jinkendo/frontend/src/utils/api.js:11), [Problem Details](https://www.rfc-editor.org/rfc/rfc9457.html) | + | TF-05 · Datenbank | PostgreSQL 16, Psycopg 3 mit begrenztem nativen Pool; SQL-Dateien mit Lock, Prüfsumme und atomarem Ledger. | Psycopg 2 ist Bestandsvariante. Kein ORM-/Alembic-Wechsel zur Lösung eines klar begrenzten Runner-Problems; kein SQLite-SQL-Übersetzer im Standard. | KI-SHK-06, KI-KAI-08, KI-KAN-06; [bestehender Pool](C:/Dev/shinkan-jinkendo/backend/db.py:19), [Runner](C:/Dev/kairo-jinkendo/backend/run_migrations.py:110), [Psycopg 3](C:/Dev/Kansho/backend/requirements.txt) | + | TF-06 · Konfiguration | Explizite Prozessumgebung und Pydantic-Validierung; Secrets nur in Adapter/Betriebsbereitstellung; unbekannte Umgebung stoppt. | Kein zusätzlicher Secret-Server. Kein Default-Passwort, kein automatisches development, kein Secretwert in technischer DB-Konfiguration. | KI-KAI-14, KI-KAN-16; [Secretreferenz-Prüfung](C:/Dev/kairo-jinkendo/backend/config_service.py:17), [Env-Fallback als Gegenbeispiel](C:/Dev/Kansho/backend/env_loader.py:28) | + | TF-07 · Testing | pytest und echtes isoliertes PostgreSQL; Vitest/RTL und wenige Image-Browsertests; Pflichtfälle statt bloßer Dateipräsenz. | Keine produktiven Mutationen, kein SQLite-Ersatz, keine Testinstallation in laufenden App-Containern und keine still übersprungenen Pflichtsuiten. | KI-SHK-12, KI-KAN-14; [Sicherheitschecks](C:/Dev/shinkan-jinkendo/backend/scripts/security_release_checks.py:17), [Test-DB-Trennung](C:/Dev/Kansho/.gitea/workflows/test.yml:36) | +-| TF-08 · Deployment | Bestehende Branchfolge; einmal gebaute qualifizierte Images, Tree-/Commit-/Hash-Nachweis, menschlich angenommener Release-PR auf geschütztes main. | Nur Tests nach Prod reichen nicht. Bestehender OCI-Transport ist erlaubt; keine neue Registry erforderlich. GitHub-Environment-Approval wird nicht vorausgesetzt. | KI-KAI-16, KI-SHK-13; [isolierter Kairo-PR-Stack](C:/Dev/kairo-jinkendo/.gitea/workflows/test.yml), [Gitea: environment ignoriert](https://docs.gitea.com/usage/actions/comparison/) | ++| TF-08 · Deployment | Verbindlich: bestehende Branchfolge, menschliche Freigabe, Release-Gates und Quell-/Build-/Artefaktzuordnung. Default R1: identische qualifizierte Images übernehmen. | ADR-11-Variante R2: kontrollierte reproduzierbare separate Builds mit Pflicht-Gates für den konkreten Prod-Build vor Deployment. Keine neue Infrastruktur; Tests nur nach Prod reichen nicht. | KI-KAI-16, KI-SHK-13; [isolierter Kairo-PR-Stack](C:/Dev/kairo-jinkendo/.gitea/workflows/test.yml), [Gitea: environment ignoriert](https://docs.gitea.com/usage/actions/comparison/) | + | TF-09 · Extension/Reuse | Erst lokaler Vertragsstandard; kleine Library bei zwei tatsächlichen Abnehmern und benanntem Maintainer. | Keine Cross-Repo-Runtime-Imports, gemeinsame Fachdatenbank, SSO- oder Billing-Plattform auf Vorrat. Zentrale Dienste benötigen echten Betriebsnutzen. | Beschlossener ADR-13 / Reuse First; [vorhandenes Register](C:/Dev/jinkendo-architecture-consolidation-phase2-v0.2-2026-10-15/05_Architecture_Decision_Register.md) | + + ### Gezielte Anpassungen statt unveränderter Kopie +@@ -49,14 +59,14 @@ + + `psycopg_pool` ist eine zusätzliche native Treiberkomponente für begrenzte threadsichere Connections, keine neue Infrastruktur. `pip-tools` ist die einzige zusätzliche Build-Hilfe für Python-Lockfiles mit transitiven Pins/Hashes. Beides löst ein konkretes Foundation-Problem; weitere Frameworks werden nicht vorsorglich ergänzt. + +-Die Frontend-Versionsaktualisierung gilt ausschließlich für den vorgeschlagenen Neuaufbau. Bestehende React-/Router-Anwendungslogik kann angepasst übernommen werden; eine Kompatibilitätsprüfung der neuen Paketkombination erfolgt beim späteren Aufbau mit Lockfiles und B4. Daraus wird kein getesteter Paketstand behauptet. Die Versions-/Supportquellen stehen in A1. ++Die Frontend-Versionsaktualisierung gilt ausschließlich für den vorgeschlagenen Neuaufbau. Bestehende React-/Router-Anwendungslogik kann angepasst übernommen werden; eine Kompatibilitätsprüfung der neuen Paketkombination erfolgt beim späteren Aufbau mit Lockfiles und B4. Daraus wird kein getesteter Paketstand behauptet. Die Versions-/Supportquellen und ihre Einordnung als technische Defaults stehen in A1/A0; v0.3 nimmt keine neue Versionsrecherche vor. + + ## Drei offene Punkte + + | Punkt | Was bei der ersten konkreten App festzulegen ist | Default / Auswirkung auf die Foundation | + |---|---|---| + | O1 · Datenraum und Schutzbedarf | Konto=Person, Club oder Organisationsraum; welche vertraulichen Mehrraumdaten zusätzlichen RLS-Schutz benötigen. | Expliziter Scope-/Policyvertrag und eingeschränkte Runtime-Rolle stehen fest. Keine universelle Tenanttabelle, kein stiller Erstprofilfallback. Keine externe Freigabe vertraulicher Mehrraumfunktionen ohne diese Produktausprägung. | +-| O2 · Wirksame Gitea-Sperren | Tatsächliche Server-/Runnerfähigkeiten, erforderliche Statuschecks, Main-Schutz, getrennte Berechtigungen und verfügbare Artefaktablage bestätigen. | Release-PR, Manifestprüfung und gleiche Images sind festgelegt. Ohne wirksame Sperren gibt es keine Prod-Promotion; bloßes `environment: production` zählt nicht. Die tatsächliche Server-/Runnerkonfiguration wurde nicht abgefragt oder verändert. | ++| O2 · Wirksame Gitea-Sperren | Tatsächliche Server-/Runnerfähigkeiten, erforderliche Statuschecks, Main-Schutz, getrennte Berechtigungen und verfügbare Artefaktablage bestätigen. | Menschliche Freigabe, Release-Gates und eindeutige Versionszuordnung sind festgelegt; gleiche Images sind Default R1, getrennte qualifizierte Builds zulässige Variante R2. Ohne wirksame Sperren gibt es keine Prod-Promotion; bloßes `environment: production` zählt nicht. Die tatsächliche Server-/Runnerkonfiguration wurde nicht abgefragt oder verändert. | + | O3 · Recoveryprofil | RPO/RTO, Restorefenster, Medien-/Schlüsselumfang und Schutz der Backups des ersten Produkts. | PostgreSQL-Backup und geprobter Restore vor datenverändernder externer Freigabe; kompatibles altes Image oder kontrollierter Forward-Fix. Keine pauschalen SaaS-Verfügbarkeitszusagen. | + + Das sind keine weiteren familienweiten Architekturfreigaben. Die Angaben werden Teil des konkreten Produkt-/Betriebsauftrags; sie verhindern die technische Grundstruktur nicht. ADR-15 und ADR-16 werden in dieser Phase weder bestätigt noch als Voraussetzung für die Foundation behandelt. +@@ -67,4 +77,4 @@ + + Die Auswahl folgt den tatsächlichen A01-Einträgen und Codepfaden: Mitais CSV-Registry/Aggregation sind KI-MIT-17/18, der PDF-Export KI-MIT-19. Einzelne E01-Kandidatenzuordnungen enthalten zusätzlich andere Themen; sie werden nicht ungeprüft als Implementierungsnachweis fortgeschrieben. Phase 3.1 bleibt unverändert. + +-Die ursprüngliche Fassung erfasste 103 gezielte Eingaben. Der Ergänzungsreview bezieht die oben benannten Code-/Testquellen hinzu; Herkunft und unveränderte Eingaben werden unter `_support/review_input_snapshot.json` festgehalten. Die frühere Phase-3.2-Fassung bleibt vollständig erhalten; v0.2 korrigiert die Schlussfolgerung, keine Produktdateien. Abschlusskontrollen betreffen nur Eingabeintegrität, lokale Verweise, die drei Dokumente und ihre Vertragskonsistenz. Kein Produkttest, Paketinstallationsversuch, Laufzeitcheck, Migrations- oder Deploylauf wurde ausgeführt. Die kleinen Codebeispiele erläutern den Vertrag und sind keine vollständige oder ausgeführte Beispielanwendung. ++Die ursprüngliche Fassung erfasste 103 gezielte Eingaben; der Ergänzungsreview in v0.2 dokumentierte die Referenzgewichtung. Diese historischen Quellprüfungen werden in v0.3 nicht wiederholt. Für v0.3 wurden ausschließlich die drei v0.2-Dokumente an den beauftragten Punkten geändert und auf Konsistenz geprüft. v0.2 bleibt unverändert. Es wurden weder Produkt-Repositories geändert noch Code, Produkttests, Paketinstallationen, Laufzeitprüfungen, Migrationen, Deployments oder Gitea-Änderungen ausgeführt. Die Beispiele und Zielkombinationen bleiben K; Dokumentationsprüfungen sind keine T-Validierung der Foundation. diff --git a/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/document_check.json b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/document_check.json new file mode 100644 index 0000000..8638e55 --- /dev/null +++ b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/document_check.json @@ -0,0 +1,29 @@ +{ + "version": "v0.3", + "main_documents": [ + "A_Jinkendo_Technical_Reference_Architecture.md", + "B_Implementation_Blueprint_Application_Foundation.md", + "C_Technical_Decisions_Open_Issues.md" + ], + "v02_files_hashed_unchanged": 7, + "v02_sha256": { + "C:\\Dev\\jinkendo-phase3-2-technical-reference-architecture-v0.2-2026-10-16\\A_Jinkendo_Technical_Reference_Architecture_V2.md": "a6fe2850237a79c013e63a2dc3f0ba01abbb156303bbb5935cea7b915aaf21a1", + "C:\\Dev\\jinkendo-phase3-2-technical-reference-architecture-v0.2-2026-10-16\\B_Implementation_Blueprint_Application_Foundation_V2.md": "d55be0db5d3cb8b907684f6fb4b79d2ae5ada21f6b61e3fb21df69527d1cf937", + "C:\\Dev\\jinkendo-phase3-2-technical-reference-architecture-v0.2-2026-10-16\\C_Technical_Decisions_Open_Issues_V2.md": "6cd7fb86c30af8c61bf4d0a939940e9a1c3d9d90b20081807ae1fe3bf0a759ee", + "C:\\Dev\\jinkendo-phase3-2-technical-reference-architecture-v0.2-2026-10-16\\Jinkendo_Phase3_2_Technical_Reference_Architecture_v0.2.zip": "58f0f06ad4826e475a02310f94216e106b760c2e75687c3ab4697640c559d291", + "C:\\Dev\\jinkendo-phase3-2-technical-reference-architecture-v0.2-2026-10-16\\_support\\review_delivery_check.json": "5384d7c7e1cacdfcacd2517bd672b38ea47f7a195ad048e7423a02db75a2effb", + "C:\\Dev\\jinkendo-phase3-2-technical-reference-architecture-v0.2-2026-10-16\\_support\\review_input_snapshot.json": "1f0cb1646bae14834d8fbdc0d3db69cf4ac1b206e3b7384eddfa9f5561e6a4d2", + "C:\\Dev\\jinkendo-phase3-2-technical-reference-architecture-v0.2-2026-10-16\\_support\\revise_reference.py": "3447b5168adec6ea25d38c4a966fb1663ed7bde50c9ed326771526b1363afdf5" + }, + "v02_unchanged": true, + "reference_weighting_section_unchanged": true, + "security_scope_privacy_section_unchanged": true, + "python_and_javascript_examples_unchanged": true, + "new_product_tests": 0, + "new_research": false, + "correction_scope": [ + "ADR-11 release variants", + "evidence status", + "binding contracts vs adaptable defaults" + ] +} \ No newline at end of file diff --git a/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/revise_v03.py b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/revise_v03.py new file mode 100644 index 0000000..0ce8f6c --- /dev/null +++ b/docs/reference/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/_support/revise_v03.py @@ -0,0 +1,172 @@ +"""Only the three requested documentation corrections; no product access or execution.""" +from pathlib import Path +import hashlib,json,re,difflib + +O=Path(__file__).resolve().parents[1] +S=Path('C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.2-2026-10-16') +N=['A_Jinkendo_Technical_Reference_Architecture','B_Implementation_Blueprint_Application_Foundation','C_Technical_Decisions_Open_Issues'] +before={str(p):hashlib.sha256(p.read_bytes()).hexdigest() for p in S.rglob('*') if p.is_file()} +original={n:(S/(n+'_V2.md')).read_text(encoding='utf-8') for n in N} +def rep(t,a,b): + assert a in t,a[:120] + return t.replace(a,b,1) +def prep(n):return original[n].replace('· v0.2 ·','· v0.3 ·',1).replace(S.as_posix(),O.as_posix()) + +a=prep(N[0]) +a=rep(a,'einem Gitea-Ablauf, der geprüfte Build-Artefakte bis zur Produktion erhält.','einem Gitea-Ablauf mit verpflichtenden Release-Gates und nachvollziehbarer Zuordnung von Quellstand, Build und getesteter Produktionsversion.') +anchor='## A1 – Technologiestack und zulässige Varianten' +a=rep(a,anchor,'''## A0 – Verbindliche Verträge, technische Defaults und Nachweis + +Die Zielarchitektur in A und ihre Ausgestaltung in B sind ein **vorgeschlagener technischer Standard**. Die bereits beschlossenen Architekturverträge gelten unabhängig davon; technische Detailvorschläge werden durch dieses Dokument nicht automatisch zu weiteren beschlossenen Familienverträgen. + +| Einordnung | Geltung in dieser Referenz | +|---|---| +| **Verbindliche Architekturverträge** | Verifizierte Identität und Datenraumgrenzen; Fail-Closed-Autorisierung neuer geschützter Funktionen; wirksame Objekt-/Scopeprüfung; sichere atomare Transaktionsgrenzen; verlässlicher Migrations-/Erfolgsnachweis; Secret-/Privacy-Grenzen; verpflichtende Release-Gates und eindeutige Zuordnung zur produktiven Version. Maßgeblich bleiben die beschlossenen ADRs und produktbezogenen Schutzgrenzen. | +| **Technische Defaults** | Bevorzugte Framework-/Versionslinien in A1, Verzeichnis- und Dateidetails in A2/B1, konkrete Modul-/Hilfsnamen, numerische Listenlimits in A4, Poolgrößen und Zeitbudgets in A5, Clienttimeout in A7/B3 sowie Artefakttransport und bevorzugtes Build-Verfahren in A9/B5. Sie sind begründet anpassbare Ausgangspunkte. | + +Bei begründetem Produktbedarf dürfen Defaults angepasst werden. Grund, gewählter Wert bzw. Ersatz und geeigneter Funktions-/Kompatibilitätsnachweis werden kurz im Produktauftrag oder in der Produktkonfiguration festgehalten; dafür wird kein neuer ADR oder zusätzlicher Freigabezyklus verlangt. Begründete Varianten dürfen keinen verbindlichen Schutz-, Transaktions- oder Releasevertrag abschwächen. Anpassbare Verzeichnisnamen ändern beispielsweise nicht die Verantwortungsgrenzen; anpassbare Timeouts beseitigen keine wirksamen Ressourcenlimits. Die gewählten Versionen müssen weiterhin unterstützt und untereinander kompatibel sein. Nach außen veröffentlichte API-Verträge bleiben gegenüber ihren Clients kompatibel, auch wenn interne Details angepasst werden. + +Für die folgenden Abschnitte gilt diese Nachweiskennzeichnung: + +| Nachweisgrad | Bedeutung / aktueller Stand | +|---|---| +| **V – Vorgeschlagener technischer Standard** | Zielentscheidungen und Implementierungsvorgaben in A/B; technisch konkret, noch keine ausgeführte Referenzimplementierung. | +| **I – Bereits vorhandene Implementierungsreferenz** | Benannte Produktdateien und Mechanismen aus v0.2; statisch untersuchte Vorbilder. Vorhandener Code oder eine Testdatei allein ist kein erfolgreicher Testnachweis. | +| **T – Tatsächlich durch Tests validierte Lösung** | Nur mit konkretem Testumfang, bestandenem Ergebnis, Quell-/Buildstand und Ausführungsumgebung. Für die hier vorgeschlagene Foundation wird kein solcher Gesamtnachweis behauptet; v0.3 führt keine Tests aus. | +| **K – Noch nicht integrierte oder getestete Kombination** | Die produktübergreifende Foundation-Synthese, Adapterkombinationen und kleinen Codebeispiele. Zusammenwirken und Versionskompatibilität müssen bei der Umsetzung erst validiert werden. | + +Eine Passage kann V und K zugleich sein; ein I-Verweis hebt sie nicht automatisch auf T. B beschreibt einen künftigen Aufbau und dessen Abnahmebedingungen, keine bereits produktionsreife Referenzimplementierung. Die Versions-/Supportangaben aus A1 werden als bisheriger Dokumentstand übernommen, in v0.3 nicht erneut recherchiert. + +'''+anchor) +a=rep(a,'| Bestandteil | Bevorzugte Basis für eine neue App | Verwendung |','| Bestandteil | Technischer Default für eine neue App | Verwendung |') +a=rep(a,'Eine Anwendung bleibt ein Repository mit Backend, Frontend, Migrationen, Tests und Deploymentdefinitionen.', '**Technischer Strukturdefault:** Eine Anwendung bleibt ein Repository mit Backend, Frontend, Migrationen, Tests und Deploymentdefinitionen. Verzeichnisdetails und Zuschnitt dürfen gemäß A0 angepasst werden; die Verantwortungs- und Schutzgrenzen bleiben erhalten.') +a=rep(a,'| Listen | `limit` Standard 50, Maximum 200; opaker validierter Cursor; stabile Sortierung mit ID als Tiebreaker |','| Listen | Numerische Defaults: `limit` 50, Maximum 200; begründet anpassbar. Begrenzte Abfragen, validierter Cursor und stabile Sortierung mit ID als Tiebreaker bleiben der Vertrag. |') +a=rep(a,'Ausgangswerte: ein Prozess, Pool 1–5, Wartezeit 3 Sekunden, höchstens 20 Wartende.', '**Anpassbare technische Defaults:** ein Prozess, Pool 1–5, Wartezeit 3 Sekunden, höchstens 20 Wartende.') +a=rep(a,'nach höchstens 60 Sekunden Wartezeit bricht er ab.', 'nach einem begrenzten Wartebudget bricht er ab (technischer Default: 60 Sekunden).') +a=rep(a,'Standard: relative Same-Origin-URLs, Cookie-Credentials, 15 Sekunden Timeout, AbortSignal, Prüfung von Content-Type/Status und Unterstützung von 204.', 'Transportdefault: relative Same-Origin-URLs und 15 Sekunden Timeout; begründete Anpassungen folgen A0. Cookie-Credentials, AbortSignal, Prüfung von Content-Type/Status und Unterstützung von 204 gehören zum beschriebenen Transportvertrag.') +old='''Der Releaseweg bleibt `develop → Dev → Tests → bewusste Freigabe → main → Prod`. Testresultate und unveränderliche Images werden an Source-Commit, Source-Tree und Buildrevision gebunden. Merge-Commits dürfen eine andere SHA haben; ihr Tree muss exakt dem qualifizierten Tree entsprechen. Produktion bekommt die qualifizierten Images ohne Neubuild. Nachgelagerter Health-Smoke bleibt erhalten, ersetzt das Test-Gate aber nicht. + +Bevorzugt werden Docker-Image-Archive mit SHA-256 und Release-Manifest über die vorhandene Artefaktablage. Eine bereits verfügbare Gitea-OCI-Registry ist eine gleichwertige Transportvariante mit Digestbindung. Keine neue Registry-Infrastruktur wird vorausgesetzt. Die Freigabe erfolgt über geschützten `main` und bewusst angenommenen Release-PR, nicht über ein vermeintliches GitHub-Environment-Gate: Gitea ignoriert `jobs..environment`. [Gitea-Kompatibilität](https://docs.gitea.com/usage/actions/comparison/)''' +new='''**Verbindlicher Releasevertrag gemäß ADR-11:** Der Weg bleibt `develop → Dev → Tests → bewusste Freigabe → main → Prod`. Pflicht-Gates müssen vor der Produktionsumschaltung bestanden sein. Quellstand, Build-Eingaben, Testläufe und tatsächlich eingesetzte Artefakte müssen eindeutig zusammengehören. Ein nachgelagerter Health-Smoke ersetzt das Release-Gate nicht. Die bewusste menschliche Produktionsfreigabe bleibt erhalten. + +| Technische Variante | Umsetzung / Nachweis | +|---|---| +| **R1 – Bevorzugter Default: Build once, deploy many** | Die in Dev qualifizierten Backend-/Frontend-Artefakte werden unverändert nach Prod übernommen. Hashes/Digests und Buildrevision binden Test und Deployment; kein weiterer Build ist für diese Variante nötig. | +| **R2 – Zulässige ADR-11-Variante: kontrollierte separate Builds** | Dev- und Prod-Artefakte dürfen getrennt aus nachvollziehbaren Quellständen und reproduzierbar festgehaltenen Build-Eingaben entstehen. Lockfiles, Build-Rezept, Toolchain/Basisimages und erlaubte öffentliche Build-Parameter werden dokumentiert. Der konkrete Prod-Build erhält vor der Umschaltung seine erforderlichen Tests/Gates und eine eigene Artefakt-/Buildkennung. Ein grüner Dev-Build allein qualifiziert kein neu gebautes Prod-Artefakt. Unterschiedliche Artefakthashes zwischen Dev und Prod sind dabei zulässig. | + +In beiden Varianten verknüpft der Releasenachweis getesteten Quell-/Buildstand, menschlich freigegebenen main-Stand und tatsächlich deployte Artefakte. Bei Merge-Commits wird die Beziehung über Commit und Source-Tree nachgewiesen. Der Default ist ein mit dem qualifizierten Stand identischer Tree; abweichender Produktionsquellstand oder abweichende Build-Eingaben benötigen die passenden dokumentierten Gate-Ergebnisse für den konkreten Kandidaten, keine ungeprüfte Gleichsetzung mit dem Dev-Lauf. Reproduzierbarkeit ersetzt diese Tests nicht. + +Default für den Artefakttransport sind Docker-Image-Archive mit SHA-256 und Release-Manifest über die vorhandene Ablage; eine vorhandene Gitea-OCI-Registry mit Digestbindung ist ebenfalls zulässig. Keine Variante verlangt neue CI/CD-Infrastruktur. Die Freigabe erfolgt über geschützten `main` und bewusst angenommenen Release-PR, nicht über ein vermeintliches GitHub-Environment-Gate: Gitea ignoriert `jobs..environment`. [Gitea-Kompatibilität](https://docs.gitea.com/usage/actions/comparison/)''' +a=rep(a,old,new) +a=rep(a,'Die verbindlichen Mindestfälle, Testbefehle und der genaue Ablauf stehen in B4/B5.', 'Die erforderlichen Mindestnachweise und ihre technischen Umsetzungsvorschläge (Befehle und Abläufe) stehen in B4/B5; konkrete Pfade und Befehle dürfen im Rahmen von A0 konsistent angepasst werden.') +a=rep(a,'Die Referenzkombination, Versionskompatibilität und kleinen Beispiele wurden nicht als Anwendung ausgeführt.', 'Nach A0 sind die Zielangaben V, die benannten Produktmechanismen I und die Foundation-Synthese samt Beispielen K. Ein T-Gesamtnachweis liegt nicht vor: Referenzkombination, Versionskompatibilität und Beispiele wurden nicht als Anwendung ausgeführt. Auch die neuen Release-Varianten sind dokumentierte Vorgaben, keine in diesem Auftrag getesteten Pipelines.') + +b=prep(N[1]) +b=rep(b,'· unmittelbar nutzbare Implementierungsvorlage**','· vorgeschlagener Blueprint, keine ausgeführte Referenzimplementierung**') +anchor='## B1 – Auftrag und Zielstruktur' +b=rep(b,anchor,'''**Geltung und Nachweis:** Dieser Blueprint ist V und als kombinierte Lösung K gemäß A0. Benannte Produktdateien sind I; geforderte Mindesttests sind noch keine T-Ergebnisse. Weder die Beispielausschnitte noch die gesamte Foundation sind hier integriert, getestet oder als produktionsreif nachgewiesen. Die tatsächliche Implementierung muss die erforderlichen Nachweise erst erbringen. + +**Verträge und Defaults:** Verbindlich bleiben insbesondere Datenraum-/Privacy-Grenzen, Fail-Closed-Zugriff, sichere Transaktionen und Release-Gates. Verzeichnisdetails, Modulnamen, Framework-/Versionslinien und numerische Einstellungen sind technische Defaults gemäß A0. Begründete Anpassungen sind im Produktauftrag bzw. in dessen Konfiguration kurz festzuhalten; keine zusätzliche Freigabeschleife. Die Aussage „gemäß A“ meint diese Unterscheidung, keinen starren Zwang zu jedem Beispielwert. + +'''+anchor) +b=rep(b,'Erstelle im ausdrücklich benannten neuen Produkt-Repository die folgende Foundation. Verwende die Versionslinien aus A1, löse stabile Patchstände auf und committe Lockfiles.', 'Erstelle im ausdrücklich benannten neuen Produkt-Repository eine Foundation nach den Verträgen dieses Blueprints. Nutze den folgenden Verzeichnisbaum und die Versionslinien aus A1 als technische Defaults; begründete Anpassungen folgen A0. Löse stabile kompatible Patchstände auf und committe Lockfiles.') +b=rep(b,'Python läuft mit `backend` als Working Directory, Imports beginnen mit `app.`.', 'Im dargestellten Strukturdefault läuft Python mit `backend` als Working Directory, Imports beginnen mit `app.`. Bei anderer begründeter Verzeichnisstruktur werden Importpfade und Befehle konsistent angepasst; keine impliziten Importnebenwirkungen.') +b=rep(b,'Illustration des DB-Adapters; Pool-Konfiguration und Fehlerübersetzung kommen aus A5/A4:', 'Nicht integrierte und nicht ausgeführte Illustration (K) des DB-Adapters; Pool-Konfiguration und Fehlerübersetzung kommen aus A5/A4. `timeout=3` ist ein technischer Default, keine unveränderliche Architekturgrenze:') +b=rep(b,'| Pool-/SQL-Zeitbudgets | Typisiert und begrenzt entsprechend A5; keine negativen/ungeprüften Zahlen |','| Pool-/SQL-Zeitbudgets | Numerische Defaults aus A5 begründet anpassbar; typisierte Validierung und wirksame Grenzen bleiben erforderlich. |') +b=rep(b,'Der Transportvertrag lautet:', 'Der vorgeschlagene Transportvertrag (V) wird durch folgenden nicht ausgeführten Ausschnitt (K) illustriert; `timeoutMs: 15000` ist ein anpassbarer technischer Default:') +b=rep(b,'Der Frontend-Build enthält keine Dev-/Prod-Origins oder privaten VITE-Variablen. API-Pfade bleiben Same-Origin, damit exakt dasselbe Frontend-Image in Dev und Prod nutzbar ist.', 'Bevorzugter Frontend-Default sind relative Same-Origin-API-Pfade ohne Dev-/Prod-Origins im Build; damit kann R1 dasselbe Frontend-Image verwenden. R2 darf nachvollziehbar deklarierte öffentliche Build-Parameter unterscheiden und muss den konkreten Prod-Build validieren. Secrets und private VITE-Variablen bleiben in beiden Varianten ausgeschlossen.') +b=rep(b,'| Release | Rotes Pflicht-Gate, fehlende DB-Suite, falsche Tree-SHA, verändertes Image-Archiv oder falsche Buildrevision verhindern Promotion |','| Release | In R1 und R2 sperren rote/fehlende Pflicht-Gates und nicht passende Quell-/Build-/Artefaktnachweise das Deployment. R1 prüft identische qualifizierte Artefakte; R2 prüft auch den separaten Prod-Kandidaten vor der Umschaltung. |') +start=b.index('## B5 – Gitea-Ablauf und Build-Nachvollziehbarkeit') +end=b.index('## B6 – Erweiterung und Fertigstellung') +b5='''## B5 – Gitea-Ablauf und Build-Nachvollziehbarkeit + +**Verbindlich:** `develop → Dev → Tests → bewusste Freigabe → main → Prod`, erforderliche Release-Gates, menschliche Freigabe und eindeutige Versions-/Artefaktzuordnung. **Technische Varianten:** R1 „Build once, deploy many“ ist der bevorzugte Default; R2 sind nach ADR-11 weiterhin zulässige kontrollierte, reproduzierbare getrennte Dev-/Prod-Builds. Beides sind noch nicht ausgeführte Verfahrensvorgaben (V/K), keine hier validierten Pipelines. + +Die bestehenden Gitea-Prozesse werden entsprechend genutzt. Zwei logische Aufgaben – Dev-Qualifikation und Produktionsfreigabe/-deployment – können in den vorhandenen Workflows abgebildet werden; Dateinamen und Jobaufteilung sind Defaults, keine neue Infrastrukturvorgabe. Nicht vertrauenswürdige PR-Checks erhalten weder Deploy-/Prod-Secrets noch Zugriff auf produktive Docker-Sockets. Deploy-Jobs laufen nur für geschützte eigene Branches auf berechtigten Runnern. Actions werden auf geprüfte Commitstände gepinnt und müssen zur eingesetzten Gitea-/Runner-Version passen. Siehe C, O2. + +| Stufe | R1 – bevorzugt: identische Artefakte | R2 – zulässig: separate Builds | +|---|---|---| +| 1 · develop | Quellcommit S/Tree T, Lockfiles und Build-Eingaben festhalten; schnelle Tests und Import-/OpenAPI-Prüfung. | Derselbe Dev-Vertrag; Dev-Build-Rezept und Parameter eindeutig aufzeichnen. | +| 2 · Dev | Backend-/Frontend-Artefakte bauen und identifizieren, explizite Dev-Migration und Dev-Deployment; Read-only-Smoke. | Identifizierte Dev-Artefakte bauen und nach Dev deployen; Migration und Read-only-Smoke wie R1. | +| 3 · Tests | Die gebauten Artefakte im isolierten Stack mit Pflichtsuiten aus B4 und Browserfällen qualifizieren. | Die Dev-Artefakte mit den erforderlichen Suiten qualifizieren. Das Ergebnis gilt für diesen Dev-Build, nicht automatisch für einen späteren Prod-Build. | +| 4 · Bewusste Freigabe | Mensch nimmt den Release-PR nach erfolgreicher Dev-Qualifikation auf geschütztes `main` an. | Dieselbe menschliche Freigabe; freigegebener Quellstand und deklarierte Produktions-Build-Eingaben bleiben nachvollziehbar. | +| 5 · Prod-Kandidat / Gate | Qualifizierte Artefakte aus dem passenden vertrauenswürdigen Run übernehmen, Hashes und Quellbeziehung prüfen. Default: S ist in main enthalten und `tree(main) == T`. | Aus dem freigegebenen Stand mit gelockten Abhängigkeiten, festgehaltenem Build-Rezept, Toolchain/Basisimages und deklarierten Parametern reproduzierbar separat bauen. Den konkreten Prod-Kandidaten im isolierten Stack vor Deployment durch seine Pflicht-Gates führen; eigener Validierungsrun und eigene Artefaktkennungen. | +| 6 · Prod | Erst bei vollständigem Nachweis: Deployment serialisieren, Schema-/Backupbedingung prüfen, explizite Prod-Migration, qualifizierte Artefakte umschalten. | Erst nach erfolgreichen Gates für den separaten Prod-Build dieselben Betriebsbedingungen prüfen und genau diesen Prod-Kandidaten umschalten. Keine ungetestete zusätzliche Änderung oder weiterer ungeprüfter Build. | +| 7 · Smoke | Read-only-Smoke und eingesetzte Build-/Artefaktkennung protokollieren. | Identische Nachweispflicht für die tatsächlich eingesetzte Prod-Version. | + +Ein rotes, fehlendes oder übersprungenes Pflicht-Gate stoppt beide Varianten. `main` enthält den bewusst freigegebenen Stand; eine Abweichung vom Dev-Tree darf nicht unter dessen grünem Ergebnis als mitgetestet gelten. Sie benötigt die zugehörigen Tests und Nachweise für den tatsächlich freigegebenen Produktionsquellstand. Änderungen außerhalb dieser menschlich freigegebenen Eingaben sind kein bereits genehmigter Release. Ein weiterer menschlicher Freigabezyklus nur wegen der Wahl von R2 wird nicht eingeführt. + +Der Produktionstest läuft isoliert gegen den konkreten Prod-Kandidaten, niemals mit synthetischen Mutationen in einer Kundendatenbank. Weder Reproduzierbarkeit noch ein Health-Smoke nach Deployment ersetzen dieses Gate. Runtime-/Build-Eingaben werden kontrolliert aufgelöst; spontane Paketupdates oder nicht dokumentierte Build-Änderungen sind in keiner Variante erlaubt. Ein kontrollierter Prod-Build in R2 ist ausdrücklich zulässig. + +**Releasenachweis für beide Varianten:** getesteter Quell-/Buildstand, freigegebener main-Stand und tatsächlich deployte Artefakte werden verknüpft. Das nachstehende Manifest ist das bevorzugte technische Format; gleichwertige vorhandene Gitea-Nachweise dürfen es abbilden. Verbindlich ist die vollständige Zuordnung, nicht ein bestimmter JSON-Feldname oder zusätzlicher Dienst. + +```text +product_id, build_variant (R1/R2), approved_main_commit, +dev_source_commit/tree, dev_build_id, dev_qualification_run_id, +prod_source_commit/tree, prod_build_id, prod_validation_run_id, +backend/frontend_artifact_ids und Hashes/Digests je Build, +Lockfilehashes, Build-Rezept/Toolchain/Basisimages und öffentliche Build-Parameter, +migrations_digest, expected_schema_head, +gate_results je qualifiziertem Build mit Ausführungs-/Skipnachweisen, +deployed_build_id und tatsächlich eingesetzte Artefakthashes, +qualified_rollback_images +``` + +In R1 dürfen Dev- und Prod-Build-/Validierungsreferenzen auf denselben qualifizierten Build verweisen. In R2 sind die getrennten Builds und ihre Ergebnisse explizit zugeordnet; unterschiedliche Hashes sind kein Fehler, wenn gerade das eingesetzte Prod-Artefakt qualifiziert ist. Merge-Commits werden über Commit und Source-Tree den Freigaben zugeordnet. Eine inzwischen weitergelaufene Dev-Instanz ersetzt keinen dieser Nachweise. + +Production vertraut den Nachweisen der passenden geschützten Workflow-Runs, nicht einem beliebig hochgeladenen JSON oder bewegbaren `latest`-Tag. Artefakte bleiben mindestens über das vereinbarte Rollbackfenster nachvollziehbar verfügbar. Archive mit SHA-256 und eine bereits vorhandene OCI-Registry mit Digestbindung sind Transportvarianten; keine neue CI/CD-Infrastruktur wird verlangt. + +Gitea `environment: production` zählt nicht als manuelle Freigabe. Workflowübergreifende Reihenfolge und Deploymentserialisierung werden ausdrücklich hergestellt. Ein produkt-/umgebungsspezifischer Hostlock ist ein technischer Default bei Jobs auf demselben Deploy-Host, keine Pflicht zu genau diesem Mechanismus. Fehler geben die gewählte Sperre und temporäre Teststacks zuverlässig frei. + +Rollback verwendet ein auf dem aktuellen Schema qualifiziertes voriges Artefaktpaar. Migrationen laufen nicht automatisch rückwärts. Ohne erforderliche Kompatibilität stoppt das Release vor der Migration; nach unerwarteten Fehlern gelten kontrollierter Forward-Fix oder vorbereiteter Restore. Die Backup-/Recoverybedingungen des Produktprofils bleiben für beide Build-Varianten unverändert. + +''' +b=b[:start]+b5+b[end:] +b=rep(b,'neu aufgelöste Pakete im Release, rebuild in Prod,', 'ungeplant neu aufgelöste Pakete im Release, ungeprüfter Prod-Neubuild,') +b=rep(b,'Die Foundation ist implementiert, wenn Struktur und Verträge stehen, die Pflichtfälle ihrer tatsächlich registrierten Funktionen laufen, Lockfiles und OpenAPI vorliegen und der Releaseweg reproduzierbar sperren kann.', 'Abnahmebedingungen für eine künftige Foundation-Implementierung sind: Struktur und Verträge umgesetzt, Pflichtfälle der tatsächlich registrierten Funktionen nachweislich bestanden, Lockfiles/OpenAPI vorhanden und wirksame Release-Sperren belegt. Diese Bedingungen sind hier Vorgaben, kein Bericht bereits bestandener Tests. Auch ihre spätere Erfüllung ersetzt keine produktbezogene Produktionsreifeprüfung.') + +c=prep(N[2]) +c=rep(c,'Neu zusammengeführt werden eine modulare Struktur, explizite Transaktionen, ein einheitlicher HTTP-Vertrag und eine nachweisbare Promotion geprüfter Images.', 'Neu zusammengeführt werden eine modulare Struktur, explizite Transaktionen, ein einheitlicher HTTP-Vertrag und ein Release-Verfahren mit verpflichtenden Gates und nachvollziehbarer Quell-/Build-/Artefaktzuordnung.') +anchor='## Überprüfung der bisherigen Gewichtung' +c=rep(c,anchor,'''## Gezielte Korrekturen in v0.3 + +1. **ADR-11 / Release:** R1 „Build once, deploy many“ bleibt bevorzugter technischer Default. R2 – kontrollierte, reproduzierbare getrennte Dev-/Prod-Builds – bleibt zulässig. Beide benötigen Pflicht-Gates vor Prod, menschliche Freigabe und eindeutige Zuordnung der tatsächlich eingesetzten Version. Bei R2 wird der konkrete Prod-Kandidat zusätzlich qualifiziert. Branchstrategie und bestehende Infrastruktur bleiben erhalten. +2. **Nachweis:** A/B sind V (vorgeschlagener technischer Standard) und als Kombination K (noch nicht integriert/getestet). Produkt-Codeverweise sind I (vorhandene Implementierungsreferenz). T setzt bestandene Tests mit Umfang, Stand und Umgebung voraus; für die Foundation wird kein T-Gesamtnachweis oder Produktionsreife behauptet. Die früher benannten Testquellen werden dadurch nicht zu Testergebnissen. +3. **Verträge / Defaults:** A0 unterscheidet verbindliche Schutz-, Datenraum-, Transaktions- und Releaseverträge von anpassbaren technischen Defaults wie Poolgröße, Timeout, Verzeichnisdetail und Framework-Version. Begründete Anpassung im Produktauftrag bzw. in der Konfiguration genügt; keine neuen ADRs oder Freigabeschleifen. + +Die bereichsspezifische Referenzauswahl und die bisherigen drei offenen Produkt-/Betriebspunkte bleiben unverändert. Die nachstehende Einordnung wird aus v0.2 übernommen; v0.3 führt keine erneute Produktreifebewertung oder Konsolidierung durch. + +'''+anchor) +c=rep(c,'## Technische Empfehlungen und wichtigste Alternativen','## Technische Empfehlungen und wichtigste Alternativen\n\nNachweisstatus: Die bevorzugten Zielausgestaltungen sind V, ihre noch nicht ausgeführte Kombination K; die Herkunftsspalte nennt bestehende Referenzen I. Keine Zeile wird hier als durch Tests validierte Foundation-Lösung T ausgewiesen. Die Geltung verbindlicher Verträge gegenüber technischen Defaults folgt A0.') +c=rep(c,'ein Composition Root. Vorhanden, einfach zu erweitern, kein neuer Betrieb.', 'ein Composition Root. Aus vorhandenen Teilmechanismen abgeleiteter Zielentwurf, noch keine validierte Gesamtimplementierung; kein neuer Betrieb.') +c=rep(c,'| TF-08 · Deployment | Bestehende Branchfolge; einmal gebaute qualifizierte Images, Tree-/Commit-/Hash-Nachweis, menschlich angenommener Release-PR auf geschütztes main. | Nur Tests nach Prod reichen nicht. Bestehender OCI-Transport ist erlaubt; keine neue Registry erforderlich. GitHub-Environment-Approval wird nicht vorausgesetzt. |', '| TF-08 · Deployment | Verbindlich: bestehende Branchfolge, menschliche Freigabe, Release-Gates und Quell-/Build-/Artefaktzuordnung. Default R1: identische qualifizierte Images übernehmen. | ADR-11-Variante R2: kontrollierte reproduzierbare separate Builds mit Pflicht-Gates für den konkreten Prod-Build vor Deployment. Keine neue Infrastruktur; Tests nur nach Prod reichen nicht. |') +c=rep(c,'Release-PR, Manifestprüfung und gleiche Images sind festgelegt.', 'Menschliche Freigabe, Release-Gates und eindeutige Versionszuordnung sind festgelegt; gleiche Images sind Default R1, getrennte qualifizierte Builds zulässige Variante R2.') +c=rep(c,'Die Versions-/Supportquellen stehen in A1.', 'Die Versions-/Supportquellen und ihre Einordnung als technische Defaults stehen in A1/A0; v0.3 nimmt keine neue Versionsrecherche vor.') +old=c[c.index('Die ursprüngliche Fassung erfasste 103 gezielte Eingaben.'):] +c=rep(c,old,'''Die ursprüngliche Fassung erfasste 103 gezielte Eingaben; der Ergänzungsreview in v0.2 dokumentierte die Referenzgewichtung. Diese historischen Quellprüfungen werden in v0.3 nicht wiederholt. Für v0.3 wurden ausschließlich die drei v0.2-Dokumente an den beauftragten Punkten geändert und auf Konsistenz geprüft. v0.2 bleibt unverändert. Es wurden weder Produkt-Repositories geändert noch Code, Produkttests, Paketinstallationen, Laufzeitprüfungen, Migrationen, Deployments oder Gitea-Änderungen ausgeführt. Die Beispiele und Zielkombinationen bleiben K; Dokumentationsprüfungen sind keine T-Validierung der Foundation. +''') + +for n,t in zip(N,[a,b,c]):(O/(n+'.md')).write_text(t,encoding='utf-8') + +# Exact v0.2 preservation and narrow scope verification; never open product source. +after={str(p):hashlib.sha256(p.read_bytes()).hexdigest() for p in S.rglob('*') if p.is_file()} +assert before==after,'v0.2 changed' +docs={n:(O/(n+'.md')).read_text(encoding='utf-8') for n in N} +# Existing reference selection, open questions and examples are preserved; only the requested classifications/release text differ. +def section(t,start,end):return t.split(start,1)[1].split(end,1)[0] +assert section(original[N[2]],'## Überprüfung der bisherigen Gewichtung','## Technische Empfehlungen und wichtigste Alternativen')==section(c,'## Überprüfung der bisherigen Gewichtung','## Technische Empfehlungen und wichtigste Alternativen') +assert section(original[N[0]],'## A8 – Schnittstellen zu Security, Datenraum, KI und Subscriptions','## A9 – Testing, Deployment und Reuse')==section(a,'## A8 – Schnittstellen zu Security, Datenraum, KI und Subscriptions','## A9 – Testing, Deployment und Reuse') +for n in N: + assert re.findall(r'^```python\n(.*?)^```',original[n],re.M|re.S)==re.findall(r'^```python\n(.*?)^```',docs[n],re.M|re.S) + assert re.findall(r'^```javascript\n(.*?)^```',original[n],re.M|re.S)==re.findall(r'^```javascript\n(.*?)^```',docs[n],re.M|re.S) + assert '· v0.3 ·' in docs[n] + assert docs[n].count('\n```')%2==0 + for target in re.findall(r'\]\(([^)]+)\)',docs[n]): + if target.startswith('https://'):continue + path=re.sub(r':\d+$','',target) + if path.startswith(O.as_posix()):assert Path(path).is_file(),target + diff=''.join(difflib.unified_diff(original[n].splitlines(True),docs[n].splitlines(True),fromfile=n+'_v0.2',tofile=n+'_v0.3')) + (O/'_support'/(n+'.diff')).write_text(diff,encoding='utf-8') +result={'version':'v0.3','main_documents':[n+'.md' for n in N],'v02_files_hashed_unchanged':len(before),'v02_sha256':before,'v02_unchanged':True,'reference_weighting_section_unchanged':True,'security_scope_privacy_section_unchanged':True,'python_and_javascript_examples_unchanged':True,'new_product_tests':0,'new_research':False,'correction_scope':['ADR-11 release variants','evidence status','binding contracts vs adaptable defaults']} +(O/'_support/document_check.json').write_text(json.dumps(result,ensure_ascii=False,indent=2),encoding='utf-8') +print(json.dumps(result,ensure_ascii=False)) diff --git a/docs/review/01_METHODIK_UND_QUELLEN.md b/docs/review/01_METHODIK_UND_QUELLEN.md new file mode 100644 index 0000000..fdacde2 --- /dev/null +++ b/docs/review/01_METHODIK_UND_QUELLEN.md @@ -0,0 +1,65 @@ +# 01 – Methodik, Quellen und Grenzen + +## Gegenstand + +Repository `C:\Dev\tsumugu`, Branch `develop`, Commit `f21c64a` („Ziehe die Struktur enger …“). Ungetrackt im Arbeitsverzeichnis lagen die Testhilfsordner `backend/.pytest-tmp/` und `backend/.pytest-export-tmp/` (nicht bewertet) sowie der Ordner `docs/reference/` mit Referenzarchitektur und Blueprints. Er ist Grundlage dieses Reviews, aber noch nicht versioniert. + +## Gelesene Anforderungs- und Referenzquellen + +| Bereich | Dokumente | Umfang | +|---|---|---| +| Produkt | `TSUMUGU_PRODUCT_SPEC.md` (0.37), `TSUMUGU_UX_MVP_ERGAENZUNG.md` (0.8), Aufträge zu Export, Unterkapitel, Kommunikationsrichtung, kompakter Liste, Symbolen/Logo-Rahmen und Ensō-Animation, Connectoren-Befund, Weiterplanungs-Übergabe, Prüfberichte Export und Unterkapitel, `TECHNICAL_SPEC_HANDOFF.md` | vollständig | +| Produkt, historisch | `Tsumugu_Product_Recovery_Baseline_v0.1.md` | nur eingeordnet; durch die Fachspec präzisiert | +| Architektur | `TSUMUGU_TECHNICAL_SPEC.md` (0.3), `ARCHITECTURE_DISCOVERY.md` | vollständig | +| Design | `docs/design/LIEFERUNG_2026-10-17.md` | vollständig. Das eigentliche Designkonzept (`C:/Dev/jinkendo-app-design-2026-10-17/…`) liegt außerhalb des Repositorys und war nicht Gegenstand des Reviews | +| Betrieb | `README.md`, `docs/DEPLOYMENT.md`, `docs/MVP_ANNAHMEN.md`, `AGENTS.md` | vollständig | +| Referenzarchitektur | A, B, C v0.3 | vollständig | +| Blueprints | Auth/Session/Scope | vollständig | +| | Medien/Dateien/sicheres Rendering | Abschnitte 1–14 vollständig, Testmatrix überblickt | +| | Release/Betrieb/Recovery | Abschnitte 1–4, 7, 10–13 vollständig, übrige überblickt | +| | KI-Gateway, Prompt/Workflow, Entitlements | Gliederung und Verträge; laut technischer Spezifikation nur Grenze, keine MVP-Pflicht | + +## Gelesener Code + +Vollständig gelesen: alle Backend-Module (`backend/app/**`), alle elf Migrationen, `conftest.py`, `support.py`, ausgewählte Tests, Dockerfiles, Compose-Dateien, Gitea-Workflows, `frontend/nginx.conf`, `nginx/*.conf`. + +Frontend: vollständig `api.js`, `App.jsx`, `main.jsx`, `session.js`, `environment.js`, `sw.js`, `markdown.jsx`, `content-symbol.mjs`, `Login.jsx`, `Settings.jsx`, `Users.jsx`, `Rooms.jsx`. Gezielt geprüft (Rendering-Senken, Rechteanzeige, Drag-and-drop, Ansichten, Endpunktnutzung): `ReadingPane.jsx`, `content.jsx`, `Cases.jsx`, `Matters.jsx`, `Shell.jsx`, `widgets.jsx`, `ExportPackage.jsx`. `styles.css` wurde nicht inhaltlich geprüft. + +## Ausgeführte Prüfungen + +| Prüfung | Befehl | Ergebnis | +|---|---|---| +| Frontend-Produktionsbuild | `npx --no-install vite build --outDir %TEMP%/tsumugu-review-dist` | erfolgreich, 66 Module, kein Fehler. Ausgabe außerhalb des Repositorys | +| Frontend-Unit-Tests | `node --test src/list-meta.test.mjs` | 4 von 4 bestanden | +| Python-Syntax | `python -I -m py_compile` über alle getrackten Backend-Module | erfolgreich | + +**Nicht ausgeführt:** Die Backend-Suite (`pytest`) verlangt eine PostgreSQL-Datenbank `*_test`. Im Review stand keine zur Verfügung. Die übernommenen Ergebnisse der Prüfberichte (46 bzw. 52 bestandene Tests) sind kein Nachweis dieses Reviews. Browserbedienung, Drag-and-drop, Paperless und IMAP wurden nicht live geprüft. Kein Deploy, kein Zugriff auf laufende Systeme. + +## Nachweiskennzeichnung + +In den Abgleichstabellen gilt: + +| Kennzeichen | Bedeutung | +|---|---| +| ✅ umgesetzt | Code vorhanden und statisch nachvollzogen; wo genannt, durch einen Testfall abgedeckt | +| 🟡 teilweise | Kernfunktion vorhanden, Teile fehlen oder weichen ab | +| ❌ fehlt | nicht umgesetzt, obwohl für den jeweiligen Lieferstand gefordert | +| ⏸ zurückgestellt | laut Fachspec bewusst später; kein Mangel des Lieferstands | +| ❔ ohne Nachweis | Umsetzung wahrscheinlich, aber im Review nicht prüfbar (z. B. Browserinteraktion) | + +## Schweregrade der Befunde + +| Schwere | Kriterium | +|---|---| +| Kritisch | unmittelbare Gefahr für vertrauliche Daten oder Datenverlust ohne besondere Voraussetzung | +| Hoch | verletzt einen verbindlichen Vertrag (Rechte, Datenraum, Transaktion, Release, Privacy) oder führt im normalen Gebrauch zu falschem Ergebnis bzw. Datenverlust | +| Mittel | Abweichung mit begrenzter Ausnutzbarkeit, Robustheits- oder Betriebsrisiko, deutliche Funktionslücke | +| Niedrig | Qualitäts-, Konsistenz- oder Wartbarkeitsmangel ohne direkte Fehlwirkung | +| Hinweis | Beobachtung ohne Handlungszwang | + +## Grenzen + +- Statisches Review. Rechtsfehler wurden durch Nachvollziehen der Codepfade belegt, nicht durch Ausführen. +- Pixelgenaue Darstellungsvorgaben (Zeilenhöhen, Dreiecksgrößen, Farben) wurden nicht gemessen. +- Host-Konfiguration auf dem Raspberry Pi und dem Synology-Proxy (HSTS, Timeouts, `.env`) wurde nicht eingesehen. +- Ob die Produktion bereits echte personenbezogene Daten hält, ist dem Review nicht bekannt. Die Bewertung von R-21 hängt davon ab. diff --git a/docs/review/02_ANFORDERUNGEN_PRODUKT.md b/docs/review/02_ANFORDERUNGEN_PRODUKT.md new file mode 100644 index 0000000..cffda5d --- /dev/null +++ b/docs/review/02_ANFORDERUNGEN_PRODUKT.md @@ -0,0 +1,75 @@ +# 02 – Abgleich mit der Produktspezifikation + +Grundlage: `docs/product/TSUMUGU_PRODUCT_SPEC.md`, Arbeitsstand 0.37. Kennzeichen siehe [01](01_METHODIK_UND_QUELLEN.md#nachweiskennzeichnung). + +## 1. Interviewentscheidungen F-01 bis F-08 und S-01 + +| ID | Anforderung (Kurzform) | Status | Umsetzung / Beleg | Abweichung, Befund | +|---|---|---|---|---| +| F-01a | Aktenrechte mit expliziten Einschränkungen; Rechte im jeweiligen Kontext; Zugriff über B öffnet A nicht | ✅ | `access/policy.py` (`Ctx`, `case_rights`, `matter_rights`, `element_rights`); Test `test_t_context_uses_only_the_requested_case`, `test_t_iso_…` | Vorgangsausnahmen wirken nicht auf Inhalte → R-07 | +| F-01b | Gemeinsamer Notizinhalt, kontextbezogene Anmerkungen | ✅ | `note_bodies` einmal je Element; `context_annotations` an `bindings`; Test `test_t_share_text_annotation_and_hidden_binding_count` | – | +| F-01c | Bearbeitungsrecht aus der Akte, Schreibschutz im Kontext, Bearbeitung von jeder berechtigten Einbindung | ✅ | `update_note` prüft `element_rights(…, context)`; Ausnahme `remove_edit` über `PUT /exceptions` | – | +| F-01d | „Aus Vorgang entfernen“ ≠ „überall löschen“ | ✅ | `detach_binding`, `delete_element` (nur Owner); Test `test_t_detach_keeps_the_other_binding` | Detach prüft die Kontextzugehörigkeit nicht → R-02 | +| F-01e | Freigeben ist eigenes Recht, getrennt vom Bearbeiten | ✅ | `bind_element` verlangt `share` an der Quelle und `edit` am Ziel; Test `test_t_grant_edit_does_not_create_a_new_binding` | – | +| F-01f | Datenraumübergreifende Freigabe am selben Element; ursprüngliche Hoheit des Anlegers | 🟡 | Grants über E-Mail an beliebige Konten; Owner = Anleger; keine Kopie | Ownership-Übertragung und delegiertes Löschen fehlen, wie in F-01f offen gelassen. Kontoauflösung per E-Mail ermöglicht Aufzählung → R-08 | +| S-01a | Akte, Vorgang, Teilvorgang, Sicht, virtuelle Zusammenstellung | 🟡 | Akte, Vorgang, Teilvorgang vollständig. Sichten nur als feste Übersichten (offene Aufgaben/Fristen, zuletzt bearbeitet) | Gespeicherte dynamische Sichten und virtuelle Zusammenstellungen ⏸ (P5b) | +| S-01b | Vorgang ohne Akte; mehrere Akten; derselbe Bearbeitungsstand | ✅ | `matter_case_links`, Version unverändert; Test `test_matter_without_a_case_and_same_version_in_two_cases` | – | +| S-01c | Teilvorgang mit genau einem Elternvorgang; Querverweise ohne Kopie | ✅ | `parent_matter_id`, `matter_cross_links` | `move_matter` erlaubt eine zweite Teilvorgangsebene → R-12 | +| S-01d | Kapitel ohne Rechte/Status; Unterakten mit eigenen Rechten | ✅ | `chapters` ohne Grants; `cases.rights_mode` (`inherit_parent`/`explicit`) | – | +| S-01e | Virtuelle Zusammenstellung als Sammelfreigabe, später Anwalt | ⏸ | – | nicht im ersten Schnitt (F-05a). Das Übergabepaket F-07a deckt den unmittelbaren Anwaltsbedarf | +| S-01f | Nachträglich ergänzte Inhalte erst nach weiterer Freigabe | ⏸ | – | wie S-01e | +| F-02a | Eigene Dateien neben externen Referenzen | ✅ | `media_assets` (PDF, PNG, JPEG, WebP), `external_references` (Paperless, IMAP, URL) | keine Normalisierung, EXIF bleibt erhalten → R-31 | +| F-02b–d | Bidirektionaler Paperless-Abgleich, Konfliktregel, Bestandsfelder | ⏸ | – | P6, laut F-05a später | +| F-03a–e | Rechnungen, Zahlungen, Erstattungen, Eigenanteil | ⏸ | – | P4b, laut F-05a/F-07a später | +| F-04a | Frist unabhängig von Aufgabe | ✅ | getrennte Tabellen, `task_deadline_links` ohne Statuskopplung; Test `test_t_dl_completed_task_leaves_the_deadline_open` | Fristen eines Teilvorgangs im Elternkontext → R-15 | +| F-05a | Erste Lieferung „Organisieren und Nachverfolgen“ | 🟡 | siehe Abschnitt 2 | Betriebsvoraussetzungen für echte Daten fehlen → R-21 | +| F-06a | Orientierung, Ordnung je Container, getrenntes Änderungsprotokoll | ✅ | `content_order`, `bindings.position`, Ansichten „Fachlicher Verlauf“, „Änderungsprotokoll“, „Zuordnungen“ (`content.jsx`) | – | +| F-06b | Vorschauzeilen, stabile Breadcrumbs, zentrale Arbeitsfläche, Drag-and-drop | 🟡 | `present.matter_trail`, `placements`, Pointer-Drag in `content.jsx` | Drag-and-drop ohne Bedienungsnachweis (UX-17) | +| F-06c | Typ-Symbole statt unbrauchbarer Miniaturen | ✅ | `content-symbol.mjs`, Symbolpaket unter `public/ui/content-symbols-v1`, Miniatur nur für Bilder | – | +| F-06d | Bezug zwischen Unterlagen, Lücke bleibt sichtbar | ✅ | `element_references`, Zyklusprüfung, Leser-Schriftwechsel; Test `test_reply_names_its_letter_and_leaves_the_gap` | Gelöschte Bezugsziele bleiben gespeichert → R-13 | +| F-06e | Kommunikationsrichtung je Einbindung, keine Ableitung aus Daten | ✅ | `bindings.communication_direction` + `direction_explicit`; IMAP-Vorbelegung nur aus Posteingang/Gesendet; Tests in `test_direction.py` | – | +| F-06f | Kompakte Liste, Richtung direkt am Zeichen, Lokal als Punkt | ✅ / ❔ | `DirectionChoice`, Symbole `communication-local`/`-unspecified` | Zeilenhöhen nicht gemessen | +| F-07a | Vollständiges Übergabepaket | ✅ | `exporting.py`, ZIP mit HTML-/Markdown-Übersicht, Originalen, EML | ZIP im Speicher, keine Gesamtgröße → R-22 | +| F-07b | Hierarchische Auswahl nach Vorkommen mit Zwischenzustand | ✅ | `ExportPackage.jsx`, `_chosen`; Test `test_handover_package_follows_the_confirmed_selection` | – | +| F-07c | Ausgewählte E-Mail enthält alle Anlagen | ✅ | `_emit_email`, SHA-256-Hinweis; Test `test_duplicate_attachments_stay_distinct_and_identity_is_exact` | – | +| F-08a | Unterkapitel als reine Gliederung, Schutzgrenze 32 | ✅ | Migration `20261017T210000Z_chapter_parent.sql` (Trigger), `ops._assert_chapter_parent`; Tests in `test_chapters.py` | – | + +## 2. Erster praktischer Abnahmeablauf F-05a + +| Schritt | Status | Beleg | +|---|---|---| +| Miet-/Rechtsstreitvorgang anlegen | ✅ | `POST /api/v1/matters`, Vorgangsliste | +| Mit einer Akte verbinden | ✅ | `POST /matters/{id}/case-links`, erfordert Freigaberecht am Vorgang und Bearbeitungsrecht an der Akte | +| Schreiben referenzieren oder als Datei ablegen | ✅ | Paperless-Picker, `POST /files`, `POST /external-refs` | +| Notiz ergänzen | ✅ | `POST /notes` (Markdown-Block) | +| Aufgabe mit Arbeitstermin und unabhängige Frist | ✅ | `POST /tasks`, `POST /deadlines` | +| Beide erscheinen in der zentralen Übersicht | 🟡 | `GET /views/open-tasks`, `/open-deadlines`. Bei mehr als 200 offenen Einträgen im System fallen sichtbare weg → R-11 | +| Vorbereitung erledigen, Frist bleibt offen | ✅ | Test `test_t_dl_…` | +| Gemeinsamer Kontext, private Inhalte bleiben unzugänglich | ✅ | Test `test_manager_does_not_read_a_personal_case`, `test_t_iso_…` | +| Chronologie mit unterscheidbaren fachlichen Zeitbezügen | ✅ | `course_items`, Ereignisse `correspondence_document/sent/received/recorded` | + +## 3. Zurückgestellte Fähigkeiten + +Alle in F-05a und F-07a zurückgestellten Fähigkeiten fehlen im Code, wie vorgesehen. Es gibt keine halben Strukturen, die eine spätere Lieferung vorwegnehmen. Die technische Spezifikation erlaubt eine leere Tabelle `external_field_states` und Finanztabellen. Sie wurden nicht angelegt. Das ist zulässig. + +| Fähigkeit | Paket | Status | +|---|---|---| +| Rechnungen, Zahlungen, Erstattungen, Eigenanteil | P4b | ⏸ | +| Bidirektionaler Paperless-Abgleich | P6 | ⏸ | +| Virtuelle Zusammenstellungen, Erstattungssicht, frei definierbare Sichten | P5b | ⏸ | +| Laufender Anwaltszugang | – | ⏸ (Übergabepaket als erster Schritt umgesetzt) | +| Aufgaben in Kairo, KI-Kontextpakete | – | ⏸, kein Code und keine Provideranbindung | +| Ownership-Übertragung, mehrere Eigentümer, delegiertes Löschen | – | ⏸ | + +## 4. Umsetzung über die Spezifikation hinaus + +Folgende Funktionen sind implementiert, stehen aber weder in der Fachspec noch in der technischen Spezifikation (→ R-17): + +- Aufgabenabhängigkeiten (`task_dependencies`, `POST /tasks/{id}/dependencies`) mit Zyklusprüfung +- Verknüpfung von Aufgaben mit Inhalten (`task_element_links`, `PUT /tasks/{id}/elements`) +- Verschieben eines Vorgangs zwischen Akten und Elternvorgängen (`POST /matters/{id}/move`) +- Löschen von Akten und Vorgängen (`POST /cases/{id}/delete`, `/matters/{id}/delete`) – mit der Rechtsfrage aus R-01 +- Betreiber legt Konten direkt mit Passwort an (`POST /api/v1/accounts`), zusätzlich zur Einladung +- Web-Bootstrap des Betreiberkontos (`/api/v1/auth/bootstrap`) → R-04 + +Diese Funktionen sind fachlich naheliegend. Sie brauchen trotzdem einen dokumentierten Fachpunkt oder eine ausdrückliche Bestätigung, weil sie Rechte (Löschen) und Hierarchie (Verschieben) berühren. diff --git a/docs/review/03_ANFORDERUNGEN_UX_UND_AUFTRAEGE.md b/docs/review/03_ANFORDERUNGEN_UX_UND_AUFTRAEGE.md new file mode 100644 index 0000000..9d430ff --- /dev/null +++ b/docs/review/03_ANFORDERUNGEN_UX_UND_AUFTRAEGE.md @@ -0,0 +1,88 @@ +# 03 – Abgleich mit UX-Ergänzung und Einzelaufträgen + +Grundlage: `TSUMUGU_UX_MVP_ERGAENZUNG.md` Fassung 0.8 sowie die Aufträge im Produktordner. Darstellung und Bedienung wurden aus dem Code abgeleitet, nicht im Browser bedient. Kennzeichen siehe [01](01_METHODIK_UND_QUELLEN.md#nachweiskennzeichnung). + +## 1. Abnahmekriterien UX-01 bis UX-21 + +| ID | Kriterium (Kurzform) | Status | Beleg | Bemerkung | +|---|---|---|---|---| +| UX-01 | Eigenständiger Vorgang ohne Akte anlegbar, später zuordnen | ✅ | `Matters.jsx`, `POST /matters`, `POST /matters/{id}/case-links` | – | +| UX-02 | Hierarchie über objektbezogenen Breadcrumb und Gliederung; Aktenzuordnung separat | ✅ | `present.case_trail`, `matter_trail`, `matter_placements` | – | +| UX-03 | Inhalte unmittelbar, keine leeren Strukturabschnitte davor | ✅ | Vorgangsseite mit einer zentralen Fläche | – | +| UX-04 | Stabile Datumssortierung, undatiert am Ende, Erfassungsdatum kein Ersatz | ✅ | `order.arrange`; Test `test_date_order_keeps_undated_last_and_ignores_recorded_time` | – | +| UX-05 | Eigene Reihenfolge bleibt nach Neuladen/Anmeldung und Moduswechsel | ✅ | Test `test_custom_order_survives_reload_login_and_date_mode` | – | +| UX-06 | Dasselbe Element mit unabhängigen Positionen in zwei Containern | ✅ | Test `test_same_element_has_independent_positions` | – | +| UX-07 | Kapitel bleiben beim Sortieren; direkte Akteninhalte von Vorgangsinhalten unterscheidbar | ✅ | Tests `test_chapters_and_contained_matters_stay_distinct`, `test_chapters_follow_the_container_not_the_entry` | – | +| UX-08 | Unterlage öffnet mit Vorschau bzw. Text als Hauptinhalt | ✅ | `ReadingPane.jsx` (pdf.js, Bild, E-Mail, Notiz) | Auslieferung aktiver Inhalte → R-03 | +| UX-09 | Protokoll separat; Verlauf ohne technische Mehrfachabbilder | ✅ | Ansichten in `content.jsx`; Test `test_course_is_not_a_copy_of_the_audit_log` | Einzelne Aktionen ohne Label → R-18 | +| UX-10 | Aufgabe und Frist erfassen, zentral wiederfinden, getrennte Erledigung | 🟡 | `Work.jsx`, Übersicht | zentrale Liste begrenzt vor Rechteprüfung → R-11 | +| UX-11 | Leser ändern keine Ordnung; manipulierte IDs ohne Wirkung; keine verborgenen Titel/Anzahlen | ✅ | Test `test_reorder_rejects_readers_foreign_ids_and_conflicts` | Detach ohne Kontextprüfung → R-02 | +| UX-12 | Bestandsdaten bleiben nach Migrationen | ✅ | Migrationen additiv; Test `test_existing_position_mode_is_not_rewritten`, `test_flat_chapters_keep_identity_order_and_bindings` | – | +| UX-13 | Desktop und schmaler Bildschirm, Alternative zum Ziehen, Tastatur | ❔ | „Nach oben/unten“ im Zeilenmenü vorhanden | Bedienung nicht geprüft; Prüfberichte nennen 390/360 px | +| UX-14 | Gleicher Struktur-Breadcrumb über Liste, Akte, Direktlink | ✅ | Tests `test_direct_matter_trail_invents_no_case`, `test_teilvorgang_keeps_its_parent_in_the_trail` | – | +| UX-15 | Genau eine zentrale Ansicht, kein Block „Struktur und Zuordnung“ | ✅ | `content.jsx` Ansichtswechsel | – | +| UX-16 | Typ-Symbol, Titel, Datum/„Ohne Datum“, Typ/Quelle getrennt, Auszug | ✅ | `EntryMark`, `contentSymbol` | – | +| UX-17 | Echtes Drag-and-drop mit Zeiger, mindestens acht Einträge, inkl. Abbruch und Scrollen | ❔ | Pointer-Capture, Einfügelinie, Auto-Scroll (`content.jsx:1356–1417`) | Ein dokumentierter Bedienungsnachweis fehlt. `LIEFERUNG_2026-10-17.md` nennt Drag-and-drop ausdrücklich „nicht ausgeführt“ | +| UX-18 | Fehler/Konflikte verständlich; kein wirkungsloses Drag im Datumsmodus | 🟡 | `canSort && custom` steuert die Aktionen | Konfliktanzeige nicht geprüft | +| UX-19 | „Alle Inhalte“ einer Akte mit Herkunft | ✅ | `case_detail.contained`, Ansicht „Überblick“ | – | +| UX-20 | Vorschauen bleiben auch über Direktabruf geschützt | ✅ | Vorschauen laufen über dieselben geprüften Endpunkte, kein Cache, `no-store` | Vorgangsausnahme wirkt nicht auf Element-Endpunkte → R-07 | +| UX-21 | Bereichswahl vor Kapitel-/Inhaltsaktion; neues Kapitel vorausgewählt | ✅ | Test `test_chapters_follow_the_container_not_the_entry`; `ChapterForm` | – | + +**Weitere UX-Vorgaben:** + +| Abschnitt | Vorgabe | Status | Bemerkung | +|---|---|---|---| +| 4 | Hauptnavigation Übersicht, Vorgänge, Akten, Aufgaben & Fristen; Verwaltung gebündelt | ✅ | `Shell.jsx` | +| 4 | Übersicht mit zuletzt bearbeiteten Vorgängen | ✅ | `GET /views/recent-matters` | +| 10 | Warnung bei ungesicherten Eingaben vor dem Verlassen | 🟡 | nur in Modals, beim Datenraum- und Kontextwechsel (`isDirty`). Kein Routen-Blocker, kein `beforeunload` | +| 10 | Mehrfachanlage verhindern, Fehler am Feld | 🟡 | `pending`-Sperre vorhanden; Fehler meist als Sammelmeldung | +| 11 | Ladezustand, Leerzustand, Fehler, fehlende Berechtigung unterscheidbar | ❔ | nicht systematisch geprüft | +| 12 | Kein öffentlicher Nebenweg für Vorschauen | ✅ | nur Blob-URLs aus geprüften Abrufen | + +## 2. Einzelaufträge + +### Symbole und Logo-Rahmen (`TSUMUGU_SYMBOLS_LOGOFRAME_AUFTRAG.md`) + +| Vorgabe | Status | Beleg | +|---|---|---| +| Notiz als Sprechblase mit Stift, hell/dunkel | ✅ | `public/ui/content-symbols-v1/{light,dark}/note.svg`, Hash-Revision in `content-symbol.mjs` | +| Typ-Symbol in jeder Zeile, Miniatur nur bei Bildern | ✅ | `EntryMark` lädt nur bei `symbol === "image"` | +| Paperless nicht automatisch als PDF | ✅ | `contentSymbol` gibt für Paperless ohne MIME `file` zurück | +| Lucide-Lizenz übernommen | ✅ | `LICENSE-LUCIDE.txt` | +| Logo auf dunkler Fläche mit transparenter Rundung | ✅ | `public/brand/logos-on-dark-v1/`, `logo-frame.css` | + +### Ensō-Animation + +| Vorgabe | Status | Beleg | +|---|---|---| +| Intro beim Login, Busy nur bei laufender Anmeldung | ✅ | `Login.jsx`: `markMotion = pending ? "busy" : …` | +| Reduced Motion, Poster-Fallback | ❔ | in `JinkendoMark.jsx`/CSS angelegt, nicht im Browser geprüft | + +### Kommunikationsrichtung 1.2 und kompakte Inhaltsliste 1.0 + +| Vorgabe | Status | Beleg | +|---|---|---| +| Richtung je Einbindung, Werte `in`/`out`/`local`/leer | ✅ | Migrationen `…180000Z…`, `…193000Z…` | +| Bewusstes Leeren bleibt gespeichert | ✅ | `direction_explicit`; Test `test_dates_do_not_invent_a_direction_and_explicit_choice_survives` | +| Keine Ableitung aus Versand-/Zugangsdatum | ✅ | `communication_from_row` | +| IMAP-Vorbelegung nur bei eindeutigem Fach | ✅ | `sources._direction` (Posteingang/Gesendet) | +| Zweite Einbindung behält eigene Richtung | ✅ | Test `test_a_second_binding_keeps_its_own_direction` | +| Ein Beleg klassifiziert nicht das Kapitel | ✅ | Test `test_one_beleg_does_not_classify_the_chapter` | +| Zeichen als einziges Bedienelement, kein Dauer-Dropdown | ✅ | `DirectionChoice` | +| Bezüge als kompakter Auslöser ohne Klammern | ✅ | Auslöser „Bezüge n“ mit Popover (`content.jsx:576–588`); keine Regel `.preview-row--linked` mehr in `styles.css` | +| Zeilenhöhen 80–110 px bzw. 100–140 px | ❔ | nicht gemessen | + +### Übergabepaket (Export-Auftrag und Prüfbericht) + +| Abnahmeschritt | Status | Beleg | +|---|---|---| +| 1–3 Auswahl mit Zwischenzustand, vollständige E-Mail | ✅ | `test_export.py` | +| 4 ZIP ohne Tsumugu nutzbar, relative Links | ✅ | `_html_overview`, `_relative` | +| 5 Gleichnamige Anlagen, Größe über Vorschaugrenze | ✅ | `_unique_path`, 80-MiB-Grenze | +| 6 Unerreichbare Quelle → kein irreführendes Paket | ✅ | `RetrievalFailure` blockiert `ready` | +| 7 Eingeschränkter Benutzer, verborgene Gegenstücke | 🟡 | Freigabe wird geprüft. Ein unlesbares Bezugsziel blockiert das Paket und verrät, dass ein Bezug existiert → R-13 | +| 8 Späterer Stand ändert altes ZIP nicht | ✅ | Paket wird nicht gespeichert | + +### Unterkapitel (Auftrag und Prüfbericht) + +Alle acht Abnahmeschritte sind im Code nachvollziehbar: Anlage unter Elternkapitel, Mehrfacheinordnung (`POST …/bindings/chapters`), Umhängen mit Zyklus- und Tiefenprüfung (App und DB-Trigger), Auflösen mit Aufrücken, Export als Verzeichnisse. Die Tests stehen in `test_chapters.py` und `test_export.py::test_nested_chapter_export_keeps_path_and_complete_mail`. Die Bedienung mit 390/360 px ist nur durch den Prüfbericht belegt. diff --git a/docs/review/04_TECHNISCHE_SPEZIFIKATION.md b/docs/review/04_TECHNISCHE_SPEZIFIKATION.md new file mode 100644 index 0000000..5d4753d --- /dev/null +++ b/docs/review/04_TECHNISCHE_SPEZIFIKATION.md @@ -0,0 +1,101 @@ +# 04 – Abgleich mit der technischen Spezifikation 0.3 + +Grundlage: `docs/architecture/TSUMUGU_TECHNICAL_SPEC.md`. Kennzeichen siehe [01](01_METHODIK_UND_QUELLEN.md#nachweiskennzeichnung). + +## 1. Umsetzungspakete + +| Paket | Soll laut Abschnitt 8 | Status | Belege und Abweichungen | +|---|---|---|---| +| P0 Foundation und Rand | `create_app`, Settings, Pool, Migrations-CLI, sichere Health-URLs, Problem-Details, Backend nur an `127.0.0.1`, Security-Header, Runtime-Rolle ohne DDL | 🟡 | ✅ Health `{status, app}`, `/health/live`, `/health/ready`, OpenAPI aus, Backend-Port `127.0.0.1`, CSP und Header im Frontend-Nginx, Psycopg 3 mit Pool, Runtime-Rolle ohne `CREATE` (Test `test_runtime_role_cannot_create_tables`), unbekannte Umgebung startet nicht. Abweichungen: Runtime-Rolle mit dem Owner-Passwort, Migration ohne Advisory-Lock, Backend-Container hält DDL-Zugang (R-09); `app = create_app()` beim Import liest Settings (Import ohne Umgebung scheitert); keine Request-ID (R-24) | +| P1 Identität und Policy | Einladung, Session-Cookie, persönlicher und gemeinsamer Raum, Grant-Auswertung, Audit | 🟡 | ✅ Cookie-Session mit gehashtem Token, CSRF, Originprüfung, Räume und Mitgliedschaft, Grants, 401/403/404-Semantik. Abweichungen: Betreiber über Web-Bootstrap statt CLI mit MFA (R-04), 14 Tage Laufzeit, keine Rotation (R-08), Auditlücken (R-18), Einladung ohne Oberfläche (R-29) | +| P2 Struktur und Notizen | Akte, Unterakte, Vorgang, Teilvorgang, Kapitel, Einbindung, Anmerkung, Chronologie, Oberfläche | ✅ | Tests T-ISO, T-SHARE, T-DETACH, T-CONTEXT. Einzelbefunde R-01, R-02, R-07, R-12 | +| P3 Eigene Dateien und Referenzen | Upload, geschützter Download, externe Referenz ohne Live-Abgleich, Storage-Ausfall 503 | 🟡 | ✅ PDF/PNG/JPEG/WebP per Magic-Byte-Prüfung, Download mit Einbindungs- und Assetrecht, Detach löscht keine Bytes, `storage_unavailable` 503. Abweichungen: einstufiger Multipart-Upload ohne Quarantäne, Normalisierung und Metadatenentfernung (R-31); Paperless und IMAP über Live-Connectoren statt nur manueller Referenz (über die Spezifikation hinaus, durch Folgeaufträge gedeckt) | +| P4a Aufgaben und Fristen | Aufgaben, unabhängige Fristen, Verknüpfungen | ✅ | Tests T-DL-01, T-ANCHOR-01. Befund R-15 | +| P5a Übersicht und Suche | Offene Aufgaben/Fristen, berechtigte Suche, Counts | 🟡 | ohne Trefferleck. Limit vor Rechteprüfung lässt sichtbare Treffer fallen (R-11) | +| P4b Finanzen | – | ⏸ | – | +| P5b Sichten und Zusammenstellungen | – | ⏸ | – | +| P6 Paperless-Abgleich | – | ⏸ | – | +| P7 Erster echter Betrieb | Qualifiziertes Release, Backup DB und Medien, Restore-Übung, RLS-Prüfung, HSTS-Nachweis, RPO/RTO | ❌ | nichts davon im Repository; `main` deployt direkt (R-21) | + +## 2. Datenmodell (Abschnitt 4) + +| Vorgabe | Status | Bemerkung | +|---|---|---| +| UUIDs, `version` für 409, `home_scope_id`, Owner, `deleted_at` an Ankern | ✅ | `cases`, `matters`, `elements`, `tasks`, `deadlines` | +| Strukturelle Elternschaft im selben Heimatraum per Composite-FK (Invariante 3) | ✅ | `cases_parent_same_scope`, `matters_parent_same_scope`, `chapters_*_same_scope`, Trigger für Kapitel-Eltern | +| Zuordnung, Querverweis, Einbindung, Grant dürfen Datenraum kreuzen (Invariante 4) | ✅ | keine Scope-Gleichheit an `bindings`, `matter_case_links`, `access_grants` | +| `bindings` mit Position, Kapitel, Richtung je Einbindung | ✅ | `release_state` fehlt, gehört zu P5b | +| `correspondence_dates` getrennt, `recorded_at = created_at` | ✅ | – | +| `access_grants` mit Ausnahmen in einem Schema | ✅ | `is_exception`, `grantee_subject_id IS NULL` für Kontextausnahme | +| `domain_events` append-only, ohne Notiztexte | ✅ | Audit trägt `context_kind/id` und `occurred_on`. `result` immer `ok` | +| Medientabellen nach Datei-Blueprint | 🟡 | `media_assets`, `media_operations` minimal; keine Leases, keine Purge-Zwischenzustände mit Wirkung (Status wird im selben Schritt auf `purged` gesetzt) | +| `content_order`, `content_order_dir`, Startwert Datum aufsteigend für neue Objekte | ✅ | Bestand bleibt `position` | +| Nicht spezifiziert, aber vorhanden | – | `connectors`, `external_references.detail`, `element_references`, `task_element_links`, `task_dependencies`, `case_link_blocks`, `auth_invitations`, `auth_accounts.is_superadmin/origin` (siehe [DATENMODELL_IST](../architecture/DATENMODELL_IST.md)) | + +## 3. Invarianten (Abschnitt 4.4) + +| Nr. | Invariante | Status | Bemerkung | +|---|---|---|---| +| 1 | Genau ein Heimatraum und Owner; Einbindung, Zuordnung, Zuweisung ändern sie nicht | ✅ | – | +| 2 | Teilvorgang genau ein Elternvorgang | ✅ | Spaltenmodell. Tiefe über `move_matter` ungeprüft (R-12) | +| 3 | Strukturelle Elternschaft im Heimatraum | ✅ | Composite-FKs | +| 4 | Querbeziehungen dürfen Räume kreuzen | ✅ | – | +| 5 | Notiztext einmal | ✅ | – | +| 6 | Anmerkung an genau einer Einbindung | ✅ | Kontextprüfung beim Anlegen unscharf (R-02) | +| 7 | Sicht nur mit Leseprädikat | ✅ | feste Sichten filtern pro Objekt | +| 8 | `pending` in Zusammenstellungen | ⏸ | P5b | +| 9 | Detach löscht Einbindung, Element bleibt | ✅ | – | +| 10–11, 13 | Finanzinvarianten | ⏸ | – | +| 12 | Unsichtbares fehlt in Liste, Suche, Count, Chronologie, Download, Export, ohne Titel und Anzahl | 🟡 | eingehalten in Liste, Suche, Chronologie, Export-Baum. Abweichungen: Export-Prüfung meldet „Antwortbezug lässt sich nicht auflösen“ für ein unsichtbares Gegenstück (R-13); Element-Endpunkte ignorieren Vorgangsausnahmen (R-07) | + +## 4. Zugriff (Abschnitt 5) + +| Vorgabe | Status | Bemerkung | +|---|---|---| +| 5.1 Kein Leserecht für Betreiber oder Manager auf persönliche Inhalte | ✅ | Test `test_manager_does_not_read_a_personal_case` | +| 5.2 Rollentabelle: Löschen des Behälters nur Owner | ❌ | `delete_case`/`delete_matter` verlangen nur `edit` (R-01) | +| 5.2 Owner ist `owner_subject_id`, keine Übertragung | ✅ | – | +| 5.3 Auswertung im Handlungskontext, keine Vereinigung, Lesen fehlt → 404, Fähigkeit fehlt → 403 | ✅ | `_require` in `policy.py` | +| 5.3 Schritt 4: Ausnahme im Kontext entfernt Rechte | 🟡 | Element- und Vorgangsausnahmen wirken. Vorgangsausnahmen wirken nicht auf Inhalte (R-07) | +| 5.4 Neue Einbindung: `share` am Element und `edit` am Ziel | ✅ | `bind_element` | +| 5.4 Globales Löschen nur Owner, Paperless bleibt | ✅ | `delete_element` | +| 5.4 Querverweis nur sichtbar, wenn Ziel lesbar | ✅ | `matter_title_if_readable` | +| 5.5 Zugewiesene Person: lesen und Status ändern, sonst nichts | ✅ | `task_rights`, `can_change_status`. Zuweisen nur per API (R-29) | +| 5.6 RLS als zweite Linie vor echtem Betrieb | ❌ | nicht geprüft, nicht vorhanden (R-21) | + +## 5. API-Verzeichnis (Abschnitt 6.2) + +Die vollständige Liste der registrierten Endpunkte steht in [API_REFERENZ.md](../architecture/API_REFERENZ.md). + +| Vorgabe | Status | Bemerkung | +|---|---|---| +| `/api/v1`, `snake_case`, UTC mit `Z`, `YYYY-MM-DD` | ✅ | – | +| Eingaben ohne unbekannte Felder | ✅ | `APIModel(extra="forbid")`. Multipart-Upload ausgenommen | +| Anlage 201 mit `Location`, Löschen 204, Listen `{items, next_cursor}` | 🟡 | `POST /cases/{id}/delete` und `/matters/{id}/delete` antworten 200 `{ok: true}`; `next_cursor` fast überall `null` ohne echte Seiten (R-11) | +| Problem-Details | 🟡 | Felder `type, title, status, detail, instance, code`; `type` immer `about:blank`, keine `request_id` (R-24) | +| Handlungskontext als Query bzw. `context` im Body | ✅ | durchgängig | +| `POST /invitations`, `/accept` | ✅ | API vorhanden, keine Oberfläche | +| `PATCH /notes/{id}` mit `visible_bindings` und stehendem Hinweis | ✅ | `note_update_payload`, `SHARED_NOTICE` | +| `/views/open-reimbursements`, Finanz- und Zusammenstellungsrouten | ⏸ | korrekt nicht registriert | +| Medienpfade nach Datei-Blueprint (U0–U3) | 🟡 | einfacher Multipart-Upload `POST /files` | + +## 6. Geplante Nachweise (Abschnitt 8.1) + +| ID | Status | Testfall | +|---|---|---| +| T-ISO-01, T-ISO-02 | ✅ | `test_rights.py::test_t_iso_hides_unshared_case_note_file_search_and_chronology` | +| T-SHARE-01 bis 04 | ✅ | `test_rights.py::test_t_share_text_annotation_and_hidden_binding_count` | +| T-CONTEXT-01 | ✅ | `test_rights.py::test_t_context_uses_only_the_requested_case` | +| T-DETACH-01 | ✅ | `test_rights.py::test_t_detach_keeps_the_other_binding` (nur Positivfall, siehe R-02) | +| T-GRANT-01 | ✅ | `test_rights.py::test_t_grant_edit_does_not_create_a_new_binding` | +| T-DL-01 | ✅ | `test_tracking.py::test_t_dl_completed_task_leaves_the_deadline_open` | +| T-ANCHOR-01 | ✅ | `test_tracking.py::test_t_anchor_assignee_sees_the_task_but_not_the_hidden_matter` | +| T-COMP-01/02, T-ANCHOR-02, T-FIN-01 bis 06, T-META-01/02 | ⏸ | gehören zu P4b, P5b, P6 | + +## 7. Betrieb (Abschnitt 8.2) + +Laut Spezifikation darf Entwicklung den heutigen Deploy-Weg für synthetische Daten nutzen; „Produktion mit echten Akten wartet auf P7“. Der Workflow `deploy-prod.yml` baut und startet bei jedem Push auf `main`, ohne vorgelagerte Tests und ohne Backup. Ob die Produktion schon echte Daten hält, war im Review nicht feststellbar. Siehe R-21. + +## 8. Rückfragen (Abschnitt 10) + +Die vier Produktfragen sind als vorläufige Annahmen in `docs/MVP_ANNAHMEN.md` übernommen und im Code so umgesetzt: Kontext der Aktion gilt, neue Sicht nur mit Freigabe- und Zielbearbeitungsrecht, Detach entfernt Einbindung samt Anmerkungen, globales Löschen nur durch den Owner, Aktenvererbung mit `case_link_blocks` für nicht freigebbare Inhalte. Nicht durch die Annahmen gedeckt ist das Löschen ganzer Behälter durch Bearbeiter (R-01). diff --git a/docs/review/05_REFERENZARCHITEKTUR_BLUEPRINTS.md b/docs/review/05_REFERENZARCHITEKTUR_BLUEPRINTS.md new file mode 100644 index 0000000..a26c250 --- /dev/null +++ b/docs/review/05_REFERENZARCHITEKTUR_BLUEPRINTS.md @@ -0,0 +1,88 @@ +# 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 | diff --git a/docs/review/06_BEFUNDE.md b/docs/review/06_BEFUNDE.md new file mode 100644 index 0000000..108a6c0 --- /dev/null +++ b/docs/review/06_BEFUNDE.md @@ -0,0 +1,294 @@ +# 06 – Befunde + +Schweregrade siehe [01](01_METHODIK_UND_QUELLEN.md#schweregrade-der-befunde). Fundstellen beziehen sich auf Commit `f21c64a`. Die Reihenfolge folgt der ID, nicht der Schwere. + +## Übersicht + +| ID | Schwere | Bereich | Kurzbeschreibung | +|---|---|---|---| +| R-01 | Hoch | Rechte | Bearbeiter löschen Akten und Vorgänge | +| R-02 | Hoch | Rechte | Detach und Anmerkung ohne Prüfung der Einbindung gegen den Handlungskontext | +| R-03 | Hoch | Sicherheit | Aktive Inhalte werden `inline` aus dem App-Origin ausgeliefert | +| R-04 | Hoch | Auth | Betreiber per öffentlichem Web-Bootstrap, keine Betreiber-MFA | +| R-05 | Mittel | Secrets | Paperless-Token und IMAP-Passwörter im Klartext in der Fach-DB | +| R-06 | Mittel | Sicherheit | SSRF und Token-Weitergabe bei frei wählbaren Quellenadressen | +| R-07 | Mittel | Rechte | Vorgangsausnahmen wirken nicht auf die Inhalte des Vorgangs | +| R-08 | Hoch | Auth | Session- und Login-Härtung unter dem Blueprint-Vertrag | +| R-09 | Mittel | Datenbank | Gemeinsame Zugangsdaten für Runtime und Migration, Migrator ohne Lock | +| R-10 | Mittel | Quellen | Quelleninhalte werden über den Zugang des Betrachters geladen | +| R-11 | Hoch | Korrektheit | `LIMIT` vor der Rechteprüfung in Übersicht und Suche | +| R-12 | Mittel | Korrektheit | Verschieben erzeugt eine zweite Teilvorgangsebene | +| R-13 | Mittel | Export | Gelöschte oder unsichtbare Bezugsziele blockieren das Übergabepaket | +| R-14 | Mittel | Daten | Gelöschte Akte oder gelöschter Vorgang lässt Inhalte unauffindbar zurück | +| R-15 | Niedrig | Rechte | Fristen eines Teilvorgangs im Elternkontext ohne Rechte | +| R-16 | Niedrig | Frontend | „Überall löschen“ an Behälter- statt Element-Owner gebunden | +| R-17 | Hinweis | Dokumentation | Funktionen über die Spezifikation hinaus ohne Fachpunkt | +| R-18 | Mittel | Audit | Auditlücken, fehlende Labels, falscher Kontext | +| R-19 | Niedrig | Suche | Volltextsuche trifft JSON-Schlüssel | +| R-20 | Niedrig | Robustheit | Unbekannter Zeichensatz in E-Mails führt zu 500 | +| R-21 | Hoch | Betrieb | P7 fehlt: Backup, Restore, Release-Gate, RLS | +| R-22 | Mittel | Transaktion | Externe Aufrufe in offener DB-Transaktion, Export vollständig im Speicher | +| R-23 | Mittel | Transaktion | Commit-Zeitpunkt hängt an der FastAPI-Version | +| R-24 | Niedrig | API | Keine Request-ID, generische Problem-Typen, flache Readiness | +| R-25 | Niedrig | Frontend | Transportclient ohne Timeout und Abbruch, kein Data Router | +| R-26 | Niedrig | Abhängigkeiten | Keine Hash-Locks, Vite 5 außerhalb des Supports | +| R-27 | Mittel | CI | Doppelte Testläufe auf derselben DB, Tests im Laufzeitimage | +| R-28 | Niedrig | Rand | Nginx reicht `X-Forwarded-Proto` des Clients durch | +| R-29 | Mittel | Funktion | Verwaltungsfunktionen fehlen in Oberfläche oder API | +| R-30 | Hinweis | Hygiene | Testhilfsordner nicht in `.gitignore` | +| R-31 | Hoch | Privacy | Uploads ohne Normalisierung, EXIF/GPS bleibt erhalten | + +--- + +## R-01 – Bearbeiter löschen Akten und Vorgänge (Hoch) + +**Fundstelle:** [ops.py:518–544](../../backend/app/ops.py#L518-L544), [Matters.jsx:500](../../frontend/src/pages/Matters.jsx#L500) + +`delete_case` und `delete_matter` verlangen nur das Recht `edit`. Die Rollentabelle der technischen Spezifikation (5.2) gibt „Löschen des Behälters“ ausschließlich dem Owner. Die Oberfläche zeigt „Löschen“ jedem Bearbeiter (`canEdit`). + +**Szenario:** Ada teilt die Akte „Mietstreit“ mit Ben zum Bearbeiten. Der Vorgang „Mängelanzeige“ ist dieser Akte und zusätzlich Adas privater Akte zugeordnet. Ben öffnet den Vorgang im Aktenkontext und löscht ihn. Der Vorgang verschwindet auch aus Adas privater Akte, obwohl Ben dort keine Rechte hat. Die Ownership des Vorgangs spielt keine Rolle. + +**Empfehlung:** Behälter löschen nur für `owner_subject_id == actor` (alternativ `can_delete` aus einem expliziten Grant). Oberfläche an `is_owner` koppeln. Negativtest ergänzen: Bearbeiter erhält 403. + +## R-02 – Detach und Anmerkung ohne Kontextbindung (Hoch) + +**Fundstelle:** [ops.py:937–953](../../backend/app/ops.py#L937-L953), [ops.py:956–979](../../backend/app/ops.py#L956-L979) + +`detach_binding` prüft das Bearbeitungsrecht am Element im übergebenen Kontext. Es vergleicht aber nur die Kontext**art** der Einbindung (`case`/`matter`), nicht deren ID. `add_annotation` lässt im Aktenkontext jede Vorgangs-Einbindung zu, ohne zu prüfen, ob dieser Vorgang der Akte zugeordnet ist. Die korrekte Hilfsfunktion `_binding_in_page` existiert bereits und wird für die Kommunikationsrichtung verwendet. + +**Szenario:** Eine Notiz ist in Akte A (nur Ada) und Akte B (Ben bearbeitet) eingebunden. Ben ruft `DELETE /api/v1/bindings/{ID der Einbindung in A}?context_kind=case&context_id={B}` auf. Die Rechteprüfung läuft gegen B und ist erfolgreich. Gelöscht wird die Einbindung in A samt ihren Anmerkungen. Voraussetzung ist die Kenntnis der UUID; die Oberfläche gibt sie für A nicht heraus. Es bleibt ein Verstoß gegen F-01d und das Prinzip „fremde IDs gewähren keinen Zugriff“. + +**Empfehlung:** In beiden Funktionen `_binding_in_page(conn, binding, action_context)` verlangen, sonst 404. Negativtest mit fremder Einbindungs-ID ergänzen. + +## R-03 – Aktive Inhalte aus dem App-Origin (Hoch) + +**Fundstelle:** [api/sources.py:176–195](../../backend/app/api/sources.py#L176-L195), [api/sources.py:79–88](../../backend/app/api/sources.py#L79-L88), [sources.py:264–273](../../backend/app/sources.py#L264-L273), [ReadingPane.jsx:532](../../frontend/src/pages/ReadingPane.jsx#L532), [ReadingPane.jsx:582](../../frontend/src/pages/ReadingPane.jsx#L582) + +E-Mail-Anlagen werden mit `Content-Disposition: inline` und dem Medientyp aus der E-Mail ausgeliefert. Diesen Typ bestimmt der Absender. Paperless-Inhalte gelten als anzeigbar, sobald der Typ mit `image/` beginnt; das schließt `image/svg+xml` ein. Die Oberfläche öffnet nicht darstellbare Blobs per Link in einem neuen Tab. Ein Blob aus einer Same-Origin-Antwort trägt den Origin der App. Eine HTML- oder SVG-Anlage läuft dann im App-Origin. Die Nginx-CSP mit `script-src 'self'` blockiert Inline-Skripte, nicht aber Skripte von derselben Origin und nicht Phishing-Formulare. + +**Empfehlung:** Laut Datei-Blueprint 9.3: Anlagen und Fremddokumente als `attachment` ausliefern; `inline` nur für eine Allowlist (PDF, PNG, JPEG, WebP), SVG ausschließen; Binärantworten zusätzlich mit `Content-Security-Policy: sandbox; default-src 'none'`. Im Frontend Blob-Links nur für erlaubte Typen anbieten, sonst Download erzwingen. + +## R-04 – Web-Bootstrap des Betreibers, keine MFA (Hoch) + +**Fundstelle:** [routes.py:292–310](../../backend/app/api/routes.py#L292-L310), [Login.jsx:73–91](../../frontend/src/pages/Login.jsx#L73-L91) + +Solange kein Betreiber existiert, kann jeder, der die öffentliche Adresse erreicht, über die Anmeldeseite das Betreiberkonto anlegen. Der Auth-Blueprint (11.3, ADR-05) und die technische Spezifikation (3.1) verlangen eine lokale CLI und verpflichtende MFA für Betreiberaktionen. Eine CLI existiert (`python -m app.cli create-account`). Sie macht das erste Konto zum Betreiber, ohne MFA. Betreiberrechte erlauben Kontoanlage mit frei gesetztem Passwort. + +**Szenario:** Eine neue Umgebung wird deployt, zum Beispiel nach einem Datenbankverlust oder ein neues Dev-Volume hinter der öffentlichen Dev-Domain. Bis zur ersten Anmeldung kann ein Fremder das Betreiberkonto übernehmen. + +**Empfehlung:** Web-Bootstrap entfernen oder an einen einmaligen, auf dem Host erzeugten Token binden. Betreiber-MFA (TOTP) nach Blueprint 11 ergänzen. Bis dahin die Abweichung in `DEPLOYMENT.md` als bewusstes Risiko führen (im Review ergänzt). + +## R-05 – Quellen-Geheimnisse im Klartext (Mittel) + +**Fundstelle:** [Migration connectors](../../backend/migrations/20261016T222500Z_connectors.sql), [sources.py:27–52](../../backend/app/sources.py#L27-L52) + +`connectors.secret` speichert Paperless-API-Token und IMAP-Passwörter unverschlüsselt. Jeder DB-Dump enthält sie. A6 verlangt, dass nur der Secret-Adapter Rohwerte kennt. Der Auth-Blueprint nennt für wieder lesbare Secrets einen lokalen `Fernet`-Cipher mit separat bereitgestelltem Schlüssel. + +**Empfehlung:** Secrets mit einem lokal bereitgestellten Schlüssel verschlüsseln (Key-ID in der Zeile). Für Backups dokumentieren, dass der Schlüssel getrennt gesichert wird. + +## R-06 – SSRF und Token-Weitergabe (Mittel) + +**Fundstelle:** [sources.py:182–190](../../backend/app/sources.py#L182-L190), [sources.py:276–292](../../backend/app/sources.py#L276-L292), [sources.py:352–363](../../backend/app/sources.py#L352-L363), [sources.py:373–388](../../backend/app/sources.py#L373-L388) + +Jede angemeldete Person kann eine beliebige Paperless-Adresse und einen beliebigen IMAP-Host eintragen. Das Backend verbindet sich aus dem Heimnetz dorthin und meldet Erfolg oder Fehler zurück. Damit lassen sich interne Dienste ansprechen. `_paperless_get` und `_paperless_metadata` folgen Weiterleitungen mit gesetztem `Authorization`-Header. Nur der Dateiabruf prüft den Zielhost nach der Weiterleitung. + +**Empfehlung:** Weiterleitungen für alle Paperless-Aufrufe abschalten oder auf denselben Host begrenzen. Optional eine Allowlist erlaubter Hosts in der Betriebskonfiguration. + +## R-07 – Vorgangsausnahmen wirken nicht auf Inhalte (Mittel) + +**Fundstelle:** [policy.py:313–328](../../backend/app/access/policy.py#L313-L328) + +`element_rights` im Aktenkontext verwendet die Aktenrechte abzüglich einer Elementausnahme. Eine Ausnahme am Vorgang in diesem Aktenkontext (`PUT /exceptions` mit `resource_kind=matter`) wird für dessen Inhalte nicht berücksichtigt. Das gilt auch für Teilvorgänge. Die Aktenansicht blendet den gesperrten Vorgang aus. Element-Endpunkte wie `GET /files/{id}/content?context_kind=case&context_id=…`, `GET /external-refs/{id}/…` oder `PATCH /notes/{id}` mit Aktenkontext liefern bzw. ändern den Inhalt weiter. + +**Szenario:** Ada sperrt den Vorgang „Interne Strategie“ in der mit Ben geteilten Akte für das Lesen. Ben kennt die Element-ID einer Datei aus einem früheren Aufruf. Er lädt die Datei weiter im Aktenkontext. + +**Empfehlung:** In `element_rights` für Einbindungen, die nur über einen Vorgang die Akte erreichen, zusätzlich `matter_rights(…, Ctx("case", …))` des tragenden Vorgangs bzw. Teilvorgangs schneiden. Negativtest ergänzen. + +## R-08 – Session- und Login-Härtung (Hoch) + +**Fundstelle:** [settings.py:27](../../backend/app/core/settings.py#L27), [routes.py:163–238](../../backend/app/api/routes.py#L163-L238), [routes.py:544–549](../../backend/app/api/routes.py#L544-L549), [deps.py:46–68](../../backend/app/api/deps.py#L46-L68) + +- Sessions gelten 336 Stunden ohne Leerlaufablauf, ohne Rotation, mit unveränderlichem CSRF-Token. Der Blueprint nennt 30 Minuten Leerlauf und 12 Stunden absolut als Default; eine Begründung für die Abweichung fehlt. +- Die Login-Begrenzung ist ein Dictionary im Prozessspeicher (`_login_attempts`). Es wächst mit jedem neuen Schlüssel, wird nie aufgeräumt und gilt nicht über Neustarts. Der Blueprint verlangt eine persistente Begrenzung. +- Für unbekannte Konten läuft kein bcrypt-Dummyvergleich. Die Antwortzeit verrät, ob ein Konto existiert. +- `GET /api/v1/principals?email=` liefert jeder angemeldeten Person ID und Anzeigenamen beliebiger Konten. +- Es gibt keinen Passwortwechsel, kein Logout-all und keine Kontosperre über die Oberfläche oder API. +- Der CSRF-Vergleich ist nicht konstantzeitlich. + +**Empfehlung:** Leerlaufablauf und Rotation nach Blueprint 7 einführen oder die längere Laufzeit begründet im Produktauftrag festhalten. Begrenzung in die DB verlagern (`auth_attempt_windows`). Dummy-Vergleich. Kontoauflösung auf Raummitglieder bzw. exakte Treffer ohne ID begrenzen. Passwortwechsel und Logout-all mit Widerruf aller Sessions. `secrets.compare_digest` für CSRF. + +## R-09 – Gemeinsame Zugangsdaten, Migrator ohne Lock (Mittel) + +**Fundstelle:** [migrate.py:20–90](../../backend/app/db/migrate.py#L20-L90), [entrypoint.py](../../backend/app/entrypoint.py), [docker-compose.yml](../../docker-compose.yml) + +Der Backend-Container erhält Owner-Zugangsdaten (`DB_USER`/`DB_PASSWORD`), migriert damit beim Start und legt die Runtime-Rolle mit **demselben Passwort** an. Der laufende Prozess kennt damit DDL-Zugang. Der Migrator setzt keinen Advisory-Lock, erkennt angewandte, aber fehlende Dateien nicht und schreibt keine `build_revision`. + +**Empfehlung:** Eigenes Passwort für die Runtime-Rolle (`DB_RUNTIME_PASSWORD`). Migration als eigener Compose-Schritt mit Owner-Zugang; das Backend erhält nur Runtime-Zugang. Advisory-Lock und Fehlend-Prüfung nach A5 ergänzen. + +## R-10 – Quellen über den Zugang des Betrachters (Mittel) + +**Fundstelle:** [api/sources.py:78](../../backend/app/api/sources.py#L78), [api/sources.py:144](../../backend/app/api/sources.py#L144), [sources.py:197–209](../../backend/app/sources.py#L197-L209) + +Die Paperless-Vorschau lädt mit dem zuletzt angelegten Paperless-Zugang **der ansehenden Person**. Die E-Mail-Ansicht verlangt einen Zugang dieser Person. Ben sieht eine von Ada eingebundene Paperless-Referenz deshalb entweder gar nicht oder mit einem eigenen Paperless-Zugang. Ist dort zufällig dieselbe Dokumentnummer vergeben, zeigt Tsumugu ein **anderes Dokument**. Ein von Ada übernommenes E-Mail kann Ben nie öffnen. Der Export nutzt ebenfalls nur Zugänge der exportierenden Person. + +**Empfehlung:** Zugang fest an die Referenz binden (`connector_id` als Spalte, wie im Connectoren-Befund vorgeschlagen). Den Abruf über den Zugang des Element-Owners führen, nachdem das Leserecht im Kontext geprüft ist. Bis dahin die Grenze in der Oberfläche benennen. + +## R-11 – `LIMIT` vor der Rechteprüfung (Hoch) + +**Fundstelle:** [routes.py:1328–1359](../../backend/app/api/routes.py#L1328-L1359), [routes.py:1412–1423](../../backend/app/api/routes.py#L1412-L1423) + +`/views/open-tasks` und `/views/open-deadlines` lesen die ersten 200 offenen Einträge **aller Konten** und filtern danach auf die sichtbaren. Die Suche liest die ersten 100 passenden Elemente aller Konten. Mit wachsendem Datenbestand mehrerer Personen fehlen eigene offene Aufgaben, Fristen oder Treffer stillschweigend. F-05a verlangt eine zentrale Übersicht offener Arbeit. + +**Szenario:** Ada hat 250 offene Aufgaben mit frühem Termin. Ben legt eine Aufgabe an. Bens zentrale Übersicht bleibt leer, weil seine Aufgabe nicht unter den ersten 200 ist. + +**Empfehlung:** Kandidaten im SQL auf eigene, zugewiesene, per Grant oder über lesbare Vorgänge erreichbare Objekte vorfiltern und danach seitenweise mit Cursor ausliefern. + +## R-12 – Zweite Teilvorgangsebene durch Verschieben (Mittel) + +**Fundstelle:** [ops.py:557–595](../../backend/app/ops.py#L557-L595), vgl. [ops.py:352–355](../../backend/app/ops.py#L352-L355) + +`create_matter` verbietet einen Teilvorgang unter einem Teilvorgang. `move_matter` prüft das nicht: Ein Vorgang mit eigenen Teilvorgängen lässt sich unter einen anderen Vorgang hängen, und ein Ziel, das selbst Teilvorgang ist, wird akzeptiert. Die Rechtefunktionen (`matter_rights`, `_matter_reaches_case`, `element_rights`) kennen nur eine Ebene. Enkel sind über den Aktenkontext nicht mehr erreichbar. + +**Empfehlung:** In `move_matter` dieselbe Regel wie beim Anlegen erzwingen: Ziel ist Wurzelvorgang, der verschobene Vorgang hat keine Teilvorgänge. + +## R-13 – Bezugsziele blockieren den Export (Mittel) + +**Fundstelle:** [exporting.py:422–444](../../backend/app/exporting.py#L422-L444), [ops.py:1044–1059](../../backend/app/ops.py#L1044-L1059) + +Ist ein Bezugsziel global gelöscht oder für die exportierende Person nicht lesbar, meldet die Prüfung „Ein Antwortbezug lässt sich nicht auflösen“ und gibt kein Paket frei. `delete_element` entfernt `element_references` nicht; der Fremdschlüssel kaskadiert nur beim physischen Löschen, das nie stattfindet. Die Oberfläche blendet den toten Bezug aus und bietet kein Lösen an. Das Paket bleibt dauerhaft gesperrt. Bei unsichtbarem Ziel verrät die Meldung zudem, dass ein Bezug existiert. Der Exportauftrag sagt: Gegenstücke außerhalb der Auswahl werden nicht benannt. + +**Empfehlung:** Beim globalen Löschen Bezüge entfernen. Unsichtbare oder gelöschte Ziele im Export still auslassen, ohne Hinweis. + +## R-14 – Inhalte gelöschter Behälter (Mittel) + +**Fundstelle:** [ops.py:518–544](../../backend/app/ops.py#L518-L544), [Matters.jsx:251](../../frontend/src/pages/Matters.jsx#L251) + +Das Löschen setzt nur `deleted_at`. Einbindungen, Kapitel, Aufgaben und Fristen bleiben am gelöschten Behälter. Inhalte, die nur dort eingebunden waren, erscheinen in keiner Liste mehr; auch `GET /elements` (nicht eingebundene Elemente) findet sie nicht, weil die Einbindung formal noch besteht. Der Bestätigungsdialog sagt „Inhalte bleiben erhalten“. Eine Wiederherstellung gibt es nicht. + +**Empfehlung:** Beim Löschen Einbindungen lösen, sodass die Elemente beim Owner unter „nicht eingebunden“ auftauchen, oder eine Wiederherstellung anbieten. Dialogtext an die tatsächliche Wirkung anpassen. + +## R-15 – Fristen eines Teilvorgangs im Elternkontext (Niedrig) + +**Fundstelle:** [policy.py:382](../../backend/app/access/policy.py#L382) gegenüber [policy.py:389–413](../../backend/app/access/policy.py#L389-L413) + +`task_rights` hat einen Zweig für den Kontext „Elternvorgang“, `deadline_rights` nicht. Fristen eines Teilvorgangs sind im Elternkontext ohne Rechte, Aufgaben dagegen sichtbar. + +**Empfehlung:** Zweig angleichen und testen. + +## R-16 – „Überall löschen“ an falsche Ownership gekoppelt (Niedrig) + +**Fundstelle:** [content.jsx:941](../../frontend/src/pages/content.jsx#L941), [Cases.jsx:522](../../frontend/src/pages/Cases.jsx#L522), [Matters.jsx:470](../../frontend/src/pages/Matters.jsx#L470) + +Die Schaltfläche erscheint, wenn die Person Owner der Akte bzw. des Vorgangs ist. Das Backend erlaubt das globale Löschen dem Owner des **Elements**. Die Owner einer Akte sehen eine Aktion, die mit 404 scheitert; Element-Owner in fremden Akten sehen sie nicht. + +**Empfehlung:** `element.owner_subject_id === session.account.id` verwenden. + +## R-17 – Funktionen ohne Fachpunkt (Hinweis) + +Aufgabenabhängigkeiten, Aufgaben-Inhaltsverknüpfungen, Verschieben von Vorgängen, Löschen von Behältern und direkte Kontoanlage durch den Betreiber sind umgesetzt, aber in Fach- und technischer Spezifikation nicht beschrieben (siehe [02, Abschnitt 4](02_ANFORDERUNGEN_PRODUKT.md#4-umsetzung-über-die-spezifikation-hinaus)). Empfehlung: als Fachpunkt nachtragen oder bestätigen lassen. + +## R-18 – Auditlücken (Mittel) + +**Fundstelle:** [ops.py](../../backend/app/ops.py), [routes.py](../../backend/app/api/routes.py), [present.py:929–964](../../backend/app/present.py#L929-L964), [ops.py:1483](../../backend/app/ops.py#L1483) + +Ohne Audit bleiben: Titel- und Statusänderung von Akte und Vorgang (`patch_case`, `patch_matter`), Friständerung (`patch_deadline`), Zuweisung (`assign_task`), Ausnahmen (`set_exception`), Querverweis löschen, Raum anlegen, Mitgliedschaft ändern, Konto anlegen, Login, Logout und Scopewechsel. Der Auth-Blueprint (13.2) verlangt Pflichtereignisse für Session, Scopewahl und privilegierte Änderungen. Mehrere protokollierte Aktionen haben kein Label (`chapter_renamed`, `chapter_deleted`, `communication_direction`, `matter_moved`, `matter_deleted`, `case_deleted`) und erscheinen als „Ereignis“. `update_dates` schreibt ohne Kontext ein Ereignis mit `Ctx("matter", element_id)`, also einer Element-ID als Vorgangskontext. + +**Empfehlung:** Fehlende Ereignisse in derselben Transaktion ergänzen, Labels nachziehen, in `update_dates` den echten Kontext oder `None` verwenden. + +## R-19 – Suche über JSON-Schlüssel (Niedrig) + +**Fundstelle:** [routes.py:1418](../../backend/app/api/routes.py#L1418) + +Die Suche vergleicht `document_json::text`. Begriffe wie „text“, „type“, „blocks“, „markdown“ oder „paragraph“ treffen jede Notiz. + +**Empfehlung:** Nur die Textwerte der Blöcke durchsuchen (zum Beispiel per `jsonb_path_query`), langfristig Volltextindex. + +## R-20 – Unbekannter Zeichensatz (Niedrig) + +**Fundstelle:** [mailpack.py:145–167](../../backend/app/mailpack.py#L145-L167), [sources.py:672–678](../../backend/app/sources.py#L672-L678) + +`bytes.decode(charset, errors="replace")` wirft `LookupError`, wenn eine E-Mail einen unbekannten Zeichensatz deklariert. Leser und Export brechen mit 500 ab. + +**Empfehlung:** `LookupError` abfangen und auf UTF-8 mit `replace` zurückfallen. + +## R-21 – P7 fehlt (Hoch) + +**Fundstelle:** [deploy-prod.yml](../../.gitea/workflows/deploy-prod.yml), technische Spezifikation 8, Release-Blueprint 1, 7, 10–13 + +Es gibt kein Backup von Datenbank und Medien, keinen geprobten Restore, kein Release-Gate vor der Produktion, keine Artefaktzuordnung, keine RLS-Prüfung und keinen HSTS-Nachweis. Ein Push auf `main` baut auf dem Host neu und startet die Produktion. Die Tests laufen nur auf `develop` und erst nach dem Dev-Deploy. Die technische Spezifikation 8.2 sagt: Produktion mit echten Akten wartet auf P7. + +**Empfehlung:** Bis P7 in der Produktion nur synthetische Daten führen oder die Produktion anhalten. P7 nach Release-Blueprint umsetzen, mindestens: verschlüsseltes Backup von DB und Medien mit unabhängiger Kopie, ein geprobter Restore, Gate „Tests grün für genau diesen Tree“ vor `deploy-prod`. + +## R-22 – Externe Aufrufe in offener Transaktion, Export im Speicher (Mittel) + +**Fundstelle:** [deps.py:30–43](../../backend/app/api/deps.py#L30-L43), [api/sources.py](../../backend/app/api/sources.py), [api/export.py](../../backend/app/api/export.py), [exporting.py:806–815](../../backend/app/exporting.py#L806-L815) + +Jede Route hält eine Pool-Verbindung mit offener Transaktion für die gesamte Laufzeit, auch während Paperless- und IMAP-Aufrufen mit 12–30 Sekunden Timeout und während einer Ordnersuche über alle IMAP-Fächer. Der Pool hat zehn Verbindungen. A3 und die technische Spezifikation 6 schließen externe Kommunikation bei offener Transaktion aus. Der Export baut das ZIP vollständig im Speicher; jedes Original darf 80 MiB groß sein, eine Gesamtgrenze fehlt. Auf dem Raspberry Pi kann ein großes Paket den Prozess beenden. + +**Empfehlung:** Für Quellen- und Exportrouten die Rechteprüfung in einer kurzen Transaktion abschließen und externe Abrufe danach ohne Verbindung ausführen. Export als Stream (`zipfile` auf temporäre Datei oder `StreamingResponse`) mit Gesamtgrenze. + +## R-23 – Commit-Zeitpunkt hängt an der FastAPI-Version (Mittel) + +**Fundstelle:** [deps.py:30–43](../../backend/app/api/deps.py#L30-L43), [requirements.txt](../../backend/requirements.txt) + +Der Commit steht im Exit-Teil einer `yield`-Dependency. In FastAPI 0.115 läuft er vor dem Senden der Antwort. Spätere Versionen haben diese Reihenfolge wieder geändert. Ein Upgrade kann stillschweigend dazu führen, dass der Client 2xx erhält, obwohl der Commit scheitert. A3 verbietet den Commit nach der Antwort. Auch das Löschen der Dateien „nach Commit“ hängt an diesem Ablauf. + +**Empfehlung:** Transaktion im Use-Case explizit öffnen und committen (UoW nach B2), oder die Dependency mit `scope="function"` festlegen und einen Test „Commit-Fehler ergibt keinen 2xx“ ergänzen. + +## R-24 – Request-ID, Problem-Typen, Readiness (Niedrig) + +**Fundstelle:** [main.py](../../backend/app/main.py), [errors.py](../../backend/app/core/errors.py) + +Keine `X-Request-ID`, `type` immer `about:blank`, `/health/ready` prüft nur `SELECT 1` ohne Migrationsstand. OpenAPI ist auch in Development aus; es entsteht kein Vertragsartefakt für einen API-Diff in CI. + +**Empfehlung:** Request-ID-Middleware, stabile `urn:jinkendo:problem:*`-Typen, Readiness mit Ledger-Abgleich, OpenAPI in Development und als CI-Artefakt. + +## R-25 – Frontend-Transport und Router (Niedrig) + +**Fundstelle:** [api.js:38–68](../../frontend/src/api.js#L38-L68), [main.jsx](../../frontend/src/main.jsx) + +Der Transportclient hat keinen Timeout und bricht laufende Requests beim Datenraumwechsel nicht ab. Eine Nicht-JSON-Fehlerantwort (zum Beispiel ein 502 von Nginx) führt in `JSON.parse` zu einem unbehandelten Fehler. Statt eines Data Routers mit Loadern und einer Modulregistry (A7/B3) gibt es `BrowserRouter` mit Effekten je Seite. Ein 401 leert die Session-Variablen, der React-Zustand bleibt aber angemeldet. + +**Empfehlung:** Timeout und `AbortController`, robustes Fehlerparsing, bei 401 den Session-Kontext zurücksetzen. Der Wechsel zum Data Router ist ein eigener Auftrag. + +## R-26 – Abhängigkeiten (Niedrig) + +**Fundstelle:** [requirements.txt](../../backend/requirements.txt), [package.json](../../frontend/package.json), [frontend/Dockerfile](../../frontend/Dockerfile) + +Python-Pins ohne Hashes, `pdfjs-dist` und `sharp` mit `^`, Vite 5 (laut A1 ohne Support), Node 22 im Build-Image gegenüber Node 24 in A1, Basisimages ohne Digest. + +**Empfehlung:** `pip-compile --generate-hashes`, exakte npm-Versionen, Basisimages mit Digest. Versionssprung als eigener Auftrag. + +## R-27 – CI (Mittel) + +**Fundstelle:** [test.yml](../../.gitea/workflows/test.yml) + +`test.yml` startet bei jedem Push auf `develop` **und** nach dem erfolgreichen Dev-Deploy. Zwei Läufe arbeiten dann parallel auf derselben Datenbank `tsumugu_test`; einer verwirft sie, während der andere testet. Der Export-Prüfbericht nennt genau diese Fehlerquelle. Pytest läuft im Laufzeitimage nach `pip install` und gegen den eingehängten Checkout, nicht gegen das gebaute Image. Der Node-Test `list-meta.test.mjs` läuft in CI nicht. Ein roter Testlauf hält weder Dev noch Prod auf. + +**Empfehlung:** Nur einen Auslöser verwenden, Testdatenbank je Lauf benennen oder kurzlebige Postgres-Instanz starten, Concurrency-Gruppe setzen, Node-Tests ergänzen, Testlauf zum Gate vor `deploy-prod` machen. + +## R-28 – Durchgereichtes `X-Forwarded-Proto` (Niedrig) + +**Fundstelle:** [frontend/nginx.conf:24](../../frontend/nginx.conf#L24), [security.py:43](../../backend/app/auth/security.py#L43) + +Der Frontend-Nginx übernimmt `X-Forwarded-Proto` vom Client. Das Backend wählt in Development danach den Cookie-Namen und das Secure-Attribut. Ein Client über HTTP kann so ein `__Host-`-Cookie anfordern, das der Browser verwirft. Eine Sicherheitslücke entsteht daraus nicht, aber eine schwer erklärbare fehlgeschlagene Anmeldung. + +**Empfehlung:** Den Header nur vom bekannten Synology-Proxy übernehmen. + +## R-29 – Fehlende Verwaltungsfunktionen (Mittel) + +Einladung (`POST /invitations`) und Aufgabenzuweisung (`POST /tasks/{id}/assignee`) haben keine Oberfläche. Mitglieder lassen sich nur als „Mitglied“ hinzufügen, nicht entfernen oder zum Verwalter machen (API vorhanden, Oberfläche fehlt). Konten lassen sich weder deaktivieren noch löschen; ein Passwortwechsel fehlt in API und Oberfläche. Die technische Spezifikation nennt Zuweisung und Einladung als Teil von P1 bzw. P4a. + +**Empfehlung:** Kleine Verwaltungsdialoge ergänzen, Kontosperre mit Widerruf aller Sessions. + +## R-30 – `.gitignore` (Hinweis) + +`backend/.pytest-tmp/` und `backend/.pytest-export-tmp/` erscheinen als ungetrackt. Empfehlung: in `.gitignore` aufnehmen. + +## R-31 – Uploads ohne Normalisierung (Hoch) + +**Fundstelle:** [media/storage.py:19–28](../../backend/app/media/storage.py#L19-L28), [ops.py:999–1041](../../backend/app/ops.py#L999-L1041) + +Uploads werden nur an den ersten Bytes erkannt und unverändert gespeichert und ausgeliefert. Fotos behalten EXIF-Daten einschließlich GPS-Position und Gerätedaten. Diese Daten erreichen alle, mit denen der Inhalt geteilt wird, und das Übergabepaket für den Anwalt. Der Datei-Blueprint (6.1, 6.3) sieht für Rasterbilder ein Neukodieren ohne fremde Metadaten vor. Angehängte Bytes hinter einem gültigen Bildkopf werden ebenfalls übernommen. + +**Empfehlung:** Rasterbilder serverseitig mit Pillow neu kodieren (Pixel- und Größengrenzen, Orientierung anwenden, Metadaten verwerfen). Falls das Original fachlich erhalten bleiben muss, beide Fassungen kennzeichnen und die bereinigte für Anzeige und Freigabe verwenden. diff --git a/docs/review/07_TESTS_UND_CI.md b/docs/review/07_TESTS_UND_CI.md new file mode 100644 index 0000000..9e1783a --- /dev/null +++ b/docs/review/07_TESTS_UND_CI.md @@ -0,0 +1,78 @@ +# 07 – Tests und CI + +## 1. Bestand + +| Datei | Tests | Schwerpunkt | +|---|---|---| +| `test_accounts.py` | 2 | 401 ohne Session; Bootstrap einmalig, Betreiber legt Konten an | +| `test_boundary.py` | 8 | Testdatenbank-Wächter, unbekannte Umgebung, Seed nie auf Dev/Prod, Produktion verweigert `SEED_DEMO`, Import ohne DB, kleine Health-Antwort, Runtime-Rolle ohne DDL, Fixture-Bereinigung | +| `test_chapters.py` | 4 | flache Bestandskapitel, drei Ebenen, Mehrfacheinordnung, Umhängen, Auflösen, Zyklen, Tiefe 32, Teilvorgangskapitel | +| `test_direction.py` | 4 | Richtung je Einbindung, bewusstes Leeren, keine Ableitung aus Daten, Umbenennen/Verschieben | +| `test_element_title.py` | 1 | Titel ändern | +| `test_export.py` | 5 | Anlagenidentität, Paperless-Original statt Vorschau, Auswahl, Lücken und verborgene Gegenstücke, verschachtelter Export | +| `test_mailboxes.py` | 5 | Fächer, Seiten, fremdes Postfach, übergroße Nachricht, vollständige Übernahme | +| `test_order.py` | 13 | Datums- und eigene Ordnung, Positionen je Container, Kapitel und Vorgänge, Verlauf ≠ Audit, Reorder-Rechte, Breadcrumbs, Vorschau-Rechte | +| `test_paperless_files.py` | 2 | Archivlesen, Pfadausbruch | +| `test_references.py` | 1 | Bezug und Lücke | +| `test_rights.py` | 7 | Manager liest nichts Persönliches, T-ISO, T-SHARE, T-CONTEXT, T-DETACH, T-GRANT, Vorgang in zwei Akten | +| `test_tracking.py` | 2 | T-DL, T-ANCHOR-01 | +| **Backend gesamt** | **54** | | +| `frontend/src/list-meta.test.mjs` | 4 | Metadatenzeile der Liste (Node Test Runner) | + +Die Tests arbeiten über HTTP mit echtem PostgreSQL und echten Cookies. Das entspricht B4: keine SQLite-Attrappe, keine Allow-all-Schalter. Positiv: Negativfälle für Rechte und Konflikte sind breit vorhanden. + +## 2. Ergebnis in diesem Review + +| Prüfung | Ergebnis | +|---|---| +| Backend-Suite | **nicht ausgeführt**: keine PostgreSQL-Instanz verfügbar | +| Frontend-Build | erfolgreich | +| `list-meta.test.mjs` | 4/4 bestanden | +| `py_compile` | erfolgreich | + +Übernommene Angaben: Der Unterkapitel-Prüfbericht nennt 52 bestandene Tests auf `e438026`. Seitdem kamen zwei Commits hinzu. Ein aktueller Lauf liegt dem Review nicht vor. + +## 3. Lücken gegenüber den geplanten Nachweisen + +### Technische Spezifikation 8.1 + +Alle Nachweise des ersten Schnitts sind vorhanden (siehe [04, Abschnitt 6](04_TECHNISCHE_SPEZIFIKATION.md#6-geplante-nachweise-abschnitt-81)). T-DETACH-01 prüft nur den Positivfall; der Gegenfall „fremde Einbindung über eigenen Kontext“ fehlt (R-02). + +### Fehlende Negativtests zu den Befunden + +| Befund | Fehlender Test | +|---|---| +| R-01 | Bearbeiter löscht Akte bzw. Vorgang → 403 | +| R-02 | Detach und Anmerkung mit Einbindung aus fremdem Kontext → 404 | +| R-07 | Vorgangsausnahme `remove_read` im Aktenkontext → Datei, Notiz und Referenz des Vorgangs 404 | +| R-11 | Mehr als 200 offene Fremdaufgaben → eigene Aufgabe bleibt in der Übersicht | +| R-12 | Verschieben unter einen Teilvorgang bzw. mit eigenen Teilvorgängen → 422 | +| R-13 | Globales Löschen eines Bezugsziels → Export weiter möglich, kein Hinweis | +| R-15 | Frist eines Teilvorgangs im Elternkontext lesbar | +| R-23 | Commit-Fehler ergibt keinen 2xx | + +### Auth-Blueprint 14 + +Die Pflichtmatrix S01–S08, B01–B08, A01–A02, P01–P05, R01–R06, M01–M11 ist nur zu einem kleinen Teil abgedeckt (401 ohne Session, Originprüfung implizit, Runtime ohne DDL). Es fehlen insbesondere: Cookie-Attribute (B01), fremder Origin und Suffixtricks (B02), CSRF anderer Session (B03), Fristen und Ablauf (S03), Logout mit falschem CSRF (S06), konkurrierende Logins und Rotation (R01–R03). + +### Frontend + +Keine Komponenten- oder Browsertests (A9/B4 sieht Vitest und wenige Playwright-Läufe vor). Drag-and-drop, Scopewechsel mit verspäteter Antwort und Dirty-Form-Schutz sind nicht automatisiert geprüft. `list-meta.test.mjs` ist nicht in `package.json` registriert und läuft nicht in CI. + +## 4. CI-Workflows + +| Workflow | Beobachtung | Bewertung | +|---|---|---| +| `deploy-dev.yml` | Checkout, `.env` anlegen, `build --no-cache`, `up --wait`, Health-Smoke | funktioniert als Dev-Pfad; keine Artefaktkennung | +| `deploy-prod.yml` | wie Dev, ausgelöst durch Push auf `main`; keine Tests, kein Backup vor Migration | verletzt ADR-11 und den Release-Blueprint (R-21) | +| `test.yml` | Auslöser Push **und** `workflow_run` nach dem Dev-Deploy → zwei Läufe je Push; beide verwerfen und erzeugen `tsumugu_test` neu; Pytest im laufenden Backend-Image mit `pip install`; Frontend-Build im Deploy-Verzeichnis | Doppellauf und gemeinsame DB machen Ergebnisse unzuverlässig (R-27) | + +Positiv: Der Workflow schreibt nie in `tsumugu_dev` oder `tsumugu`; der Wächter in `conftest.py` verweigert andere Datenbanknamen; der Live-Smoke ist rein lesend. + +## 5. Empfehlungen + +1. `test.yml` auf einen Auslöser reduzieren, Concurrency-Gruppe setzen und Testdatenbanken je Lauf benennen (`tsumugu_test_`). +2. Pytest gegen das gebaute Image ausführen; Testwerkzeuge in einem getrennten Testimage. +3. `npm test` mit `node --test` registrieren und in CI ausführen. +4. Negativtests aus Abschnitt 3 ergänzen, bevor die Befunde behoben werden. So wird der Fehler zuerst sichtbar und danach die Korrektur belegt. +5. Ein Gate vor `deploy-prod`: Testlauf grün für exakt den Tree von `main`. diff --git a/docs/review/08_DOKUMENTATION.md b/docs/review/08_DOKUMENTATION.md new file mode 100644 index 0000000..187ddc4 --- /dev/null +++ b/docs/review/08_DOKUMENTATION.md @@ -0,0 +1,61 @@ +# 08 – Vollständigkeit der Dokumentation + +## 1. Bestand vor dem Review + +| Dokument | Zustand | Befund | +|---|---|---| +| `README.md` | veraltet | Behauptete, Development lege Beispieldaten an und die Anmeldeseite zeige Ada und Ben. Der Code entfernt Fixture-Konten in jeder Umgebung; die Beispielkonten erscheinen nur bei `*_test` mit `SEED_DEMO=true`. Spätere Lieferungen (Quellen, Export, Unterkapitel) fehlten im Stand. Kein Verweis auf weitere Dokumente | +| `AGENTS.md` | aktuell | – | +| `docs/DEPLOYMENT.md` | weitgehend aktuell | Kein Hinweis auf fehlende Sicherung, Web-Bootstrap des Betreibers, gemeinsame DB-Passwörter, Klartext-Secrets der Quellen | +| `docs/MVP_ANNAHMEN.md` | aktuell | Löschen ganzer Behälter durch Bearbeiter ist nicht abgedeckt (Code-Abweichung, R-01) | +| `product/TSUMUGU_PRODUCT_SPEC.md` | aktuell (0.37) | Historische Etappensätze („keine Implementierung“) sind als solche markiert. Nicht beschrieben: Aufgabenabhängigkeiten, Aufgaben-Inhaltsverknüpfung, Vorgang verschieben, Behälter löschen (R-17) | +| `product/TSUMUGU_UX_MVP_ERGAENZUNG.md` | aktuell (0.8) | – | +| `product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md` | leicht veraltet | nennt die Produktspezifikation „aktuell 0.34“ | +| `architecture/TSUMUGU_TECHNICAL_SPEC.md` | teilweise veraltet | Kopf „Stand 16.10.2026, Fassung 0.3“, enthält aber Ergänzungen bis F-08a. Abschnitt 1.3 sagt, es gebe keine Fachanwendung; Abschnitt 8 empfiehlt „nur P0“ als ersten Auftrag. Das API-Verzeichnis 6.2 hat 39 Zeilen (teils mit mehreren Pfaden, teils Ausbauentwurf); registriert sind 105 Routen. Nicht beschrieben: Connectoren, Export-API, Bezüge, Aufgabenabhängigkeiten, Kontoanlage durch Betreiber, Web-Bootstrap, Sessionlaufzeit | +| `architecture/ARCHITECTURE_DISCOVERY.md` | historisch | ausdrücklich keine Beschlüsse; in Ordnung | +| `design/LIEFERUNG_2026-10-17.md` | historisch, teils überholt | „Ein Service Worker ist bewusst nicht enthalten“: inzwischen registriert (`public/sw.js`, Commit `db40632`). Drag-and-drop „nicht ausgeführt“: ein späterer Nachweis fehlt | +| `docs/design/` | unvollständig | Das ausgewählte Designkonzept (`JINKENDO_APP_DESIGN_CONCEPT.md`, Umsetzungsauftrag, Assetpakete) liegt nur außerhalb des Repositorys. Für Leser des Repositorys ist die Gestaltungsgrundlage nicht nachvollziehbar | +| `docs/reference/` | vorhanden, aber **nicht versioniert** | Der Ordner ist ungetrackt; ohne Commit fehlt er in jedem anderen Checkout. Interne Links zeigen auf `C:/Dev/…` außerhalb des Repositorys | + +### Fehlende Dokumentarten vor dem Review + +| Dokumentart | Bedarf | +|---|---| +| Dokumentationsindex | Orientierung über knapp 30 Dokumente mit unterschiedlicher Verbindlichkeit | +| API-Referenz des Ist-Stands | OpenAPI ist abgeschaltet; es gab keine vollständige Endpunktliste | +| Ist-Datenmodell | Schema nur aus elf Migrationen rekonstruierbar | +| Ist-Rechteauswertung | Kern der Fachlichkeit, nur im Code nachvollziehbar | +| Entwicklung und Tests | keine Anleitung für lokalen Start, Konfiguration und Testdatenbank | +| Betriebshandbuch Sicherung/Wiederherstellung | fehlt, weil P7 fehlt; muss mit P7 entstehen | +| Änderungsprotokoll / Lieferstand | Stand nur über Commits und Prüfberichte rekonstruierbar | +| Abweichungsregister (begründete Default-Anpassungen nach A0) | A0 verlangt eine kurze Begründung je angepasstem Default (Sessionlaufzeit, Frontend-Versionen, Upload-Verfahren). Es gibt keine solche Stelle | + +## 2. Im Review ergänzt oder korrigiert + +| Datei | Art | Inhalt | +|---|---|---| +| `docs/README.md` | neu | Dokumentationslandkarte mit Rolle, Stand und Verbindlichkeit | +| `docs/architecture/API_REFERENZ.md` | neu | alle registrierten Endpunkte mit Zweck und Rechten | +| `docs/architecture/DATENMODELL_IST.md` | neu | alle Tabellen, Regeln, Beziehungsdiagramm, bewusst fehlende Tabellen | +| `docs/architecture/RECHTEMODELL_IST.md` | neu | Auswertung je Objektart, schreibende Aktionen, Sichtbarkeit, bekannte Abweichungen | +| `docs/ENTWICKLUNG_UND_TESTS.md` | neu | Konfiguration, lokaler Start, Tests, Vorgehen bei Migration und Route | +| `docs/review/*` | neu | dieser Bericht | +| `README.md` | korrigiert | Beispieldaten richtiggestellt, Stand ergänzt, Verweise auf Dokumentation und Review | +| `docs/DEPLOYMENT.md` | ergänzt | Abschnitt „Bekannte Betriebsgrenzen“ | +| `docs/architecture/TSUMUGU_TECHNICAL_SPEC.md` | ergänzt | Hinweis zum Ist-Stand am Anfang; der Inhalt der Spezifikation bleibt unverändert | + +Fachspezifikation, UX-Ergänzung, Aufträge, Prüfberichte und historische Dokumente wurden nicht verändert. Ihre Aussagen sind Entscheidungs- bzw. Lieferstände und sollen als solche erhalten bleiben. + +## 3. Verbleibende Lücken + +| Lücke | Empfehlung | Verantwortung | +|---|---|---| +| Fachpunkte für Mehrumfang (R-17) | in der Produktspezifikation nachtragen oder Funktionen bestätigen | Produkt | +| Technische Spezifikation 0.4 | Abschnitt 1.3 und 8 auf den Ist-Stand bringen; API-Verzeichnis auf `API_REFERENZ.md` verweisen; Abweichungen (Session, Upload, Connectoren, Bootstrap) entweder beheben oder als begründete Default-Anpassung eintragen | Technik | +| Abweichungsregister nach A0 | kurze Tabelle „Default, gewählter Wert, Grund, Nachweis“ in der technischen Spezifikation | Technik | +| Referenzarchitektur und Blueprints versionieren | `docs/reference/` committen, damit Verweise aus `docs/README.md` und diesem Review in jedem Checkout auflösen | Technik | +| Designgrundlage im Repository | Designkonzept und Umsetzungsauftrag nach `docs/design/` kopieren oder dauerhaft verlinken | Design | +| Betriebshandbuch Backup/Restore | mit Paket P7 erstellen | Betrieb | +| Lieferstand / Änderungsprotokoll | `docs/CHANGELOG.md` mit Lieferungen und geprüftem Commit je Lieferung | Technik | +| Prüfbericht zu UX-17 | echten Drag-and-drop-Nachweis mit acht Einträgen dokumentieren | Technik | +| Pflege der Ist-Dokumente | bei jeder Route/Migration im selben Commit nachziehen (Regel in `docs/README.md`) | alle | diff --git a/docs/review/09_MASSNAHMENPLAN.md b/docs/review/09_MASSNAHMENPLAN.md new file mode 100644 index 0000000..4705ffa --- /dev/null +++ b/docs/review/09_MASSNAHMENPLAN.md @@ -0,0 +1,80 @@ +# 09 – Maßnahmenplan + +Die Reihenfolge ist ein Vorschlag. Jede Stufe ist für sich lieferbar. Befund-IDs siehe [06_BEFUNDE.md](06_BEFUNDE.md). Vor jeder Korrektur zuerst den fehlenden Negativtest aus [07](07_TESTS_UND_CI.md#fehlende-negativtests-zu-den-befunden) schreiben. So wird der Fehler sichtbar und danach die Behebung belegt. + +## Stufe 0 – sofort, ohne Code + +| Maßnahme | Befund | Abnahme | +|---|---|---| +| Klären, ob die Produktion echte personenbezogene Daten hält. Falls ja: manuelles verschlüsseltes Backup von DB und Medien-Volume auf ein getrenntes Gerät, einmal probeweise zurückspielen | R-21 | Backup und erfolgreicher Testrestore dokumentiert | +| Merge nach `main` nur nach grünem Einzellauf von `test.yml` für denselben Commit | R-21, R-27 | Regel in `DEPLOYMENT.md` | +| Nach jedem Neuaufsetzen einer Umgebung sofort das Betreiberkonto anlegen | R-04 | in `DEPLOYMENT.md` vermerkt (erledigt) | + +## Stufe 1 – Rechte und Datenintegrität (klein, hohe Wirkung) + +| Maßnahme | Befund | Aufwand | Abnahme | +|---|---|---|---| +| Behälter löschen nur durch Owner; Oberfläche an `is_owner` koppeln | R-01 | klein | Bearbeiter erhält 403; Owner löscht | +| `_binding_in_page` in Detach und Anmerkung verwenden | R-02 | klein | fremde Einbindungs-ID → 404 | +| Vorgangs- und Teilvorgangsausnahmen in `element_rights` für den Aktenkontext abziehen | R-07 | klein | Datei eines gesperrten Vorgangs im Aktenkontext → 404 | +| `move_matter`: Ziel muss Wurzelvorgang sein, verschobener Vorgang ohne Teilvorgänge | R-12 | klein | zweite Ebene → 422 | +| `deadline_rights` um den Elternkontext ergänzen | R-15 | klein | Frist eines Teilvorgangs im Elternkontext lesbar | +| Globales Löschen entfernt `element_references`; Export lässt unsichtbare und gelöschte Ziele still weg | R-13 | klein | Export nach Löschen des Ziels möglich, kein Hinweis | +| Behälter löschen: Einbindungen lösen oder Wiederherstellung anbieten; Dialogtext anpassen | R-14 | klein bis mittel | Inhalte erscheinen beim Owner unter „nicht eingebunden“ | +| „Überall löschen“ an Element-Owner koppeln | R-16 | klein | Schaltfläche nur beim Element-Owner | + +## Stufe 2 – Übersicht, Suche, Auslieferung + +| Maßnahme | Befund | Aufwand | Abnahme | +|---|---|---|---| +| Offene Aufgaben, Fristen und Suche im SQL auf erreichbare Objekte vorfiltern, Cursor-Paging | R-11 | mittel | eigene Aufgabe sichtbar trotz 250 fremder offener Aufgaben | +| Anlagen und Fremddokumente als `attachment`, Inline-Allowlist ohne SVG, Sandbox-CSP; Frontend öffnet nur erlaubte Typen | R-03 | klein | HTML-Anlage wird heruntergeladen, nicht gerendert | +| Rasterbilder serverseitig neu kodieren, Metadaten entfernen | R-31 | mittel | hochgeladenes Foto ohne EXIF/GPS | +| Suche nur über Blocktexte | R-19 | klein | „paragraph“ findet keine beliebige Notiz | +| Unbekannte Zeichensätze abfangen | R-20 | klein | Mail mit `charset=x-unknown` lesbar | + +## Stufe 3 – Auth- und Transaktionsverträge + +| Maßnahme | Befund | Aufwand | Abnahme | +|---|---|---|---| +| Web-Bootstrap durch Host-Token oder CLI ersetzen; Betreiber-MFA (TOTP) | R-04 | mittel | kein Betreiber ohne MFA; Bootstrap-Route ohne Token 404 | +| Sessions: Leerlaufablauf, Rotation, persistente Login-Begrenzung, bcrypt-Dummy, konstantzeitlicher CSRF-Vergleich, Passwortwechsel, Logout-all; alternativ längere Laufzeit begründet festhalten | R-08 | mittel | Auth-Blueprint S01–S08, B03, R06 als Tests | +| Kontoauflösung per E-Mail begrenzen | R-08 | klein | keine ID-Auskunft über beliebige Konten | +| Transaktion explizit im Use-Case; externe Aufrufe außerhalb der Transaktion | R-22, R-23 | mittel | Test „Commit-Fehler → kein 2xx“; Quellenaufruf ohne gehaltene Verbindung | +| Export streamen, Gesamtgrenze | R-22 | mittel | Paket über Grenze wird vor dem Bauen abgelehnt | +| Eigenes Runtime-Passwort, Migration als eigener Schritt, Advisory-Lock, Fehlend-Prüfung | R-09 | mittel | Backend-Container ohne Owner-Zugang | +| Quellen-Secrets verschlüsseln | R-05 | klein | Dump enthält keine Klartext-Token | +| Paperless-Weiterleitungen sperren, optional Host-Allowlist | R-06 | klein | Weiterleitung auf fremden Host → Fehler ohne Token-Weitergabe | +| Zugang fest an die Referenz binden, Abruf über den Element-Owner | R-10 | mittel | Ben sieht Adas Paperless-Dokument, nie ein fremdes gleicher Nummer | +| Fehlende Audit-Ereignisse und Labels | R-18 | klein | Protokoll zeigt Login, Scopewechsel, Statusänderung, Zuweisung | + +## Stufe 4 – Paket P7 und CI + +| Maßnahme | Befund | Aufwand | Abnahme | +|---|---|---|---| +| Produktprofil mit RPO/RTO (Start: 24 h / 4 h) | R-21 | klein | Profil dokumentiert | +| Backup DB + Medien nach gemeinsamem Freeze, `age`-verschlüsselt, unabhängige Kopie, Aufbewahrung 7/4/3 | R-21 | mittel | `COMPLETE`-Beleg; monatliche Restore-Übung | +| Restore in neue Generation, Sessions widerrufen, Konten zunächst gesperrt | R-21 | mittel | synthetischer Drill mit gemessener Dauer | +| Release-Gate vor `deploy-prod` (R2: Prod-Kandidat bauen, testen, dann umschalten) | R-21 | mittel | roter Test verhindert Prod-Umschaltung | +| `test.yml`: ein Auslöser, Concurrency, Testdatenbank je Lauf, Node-Tests | R-27 | klein | keine Doppelläufe | +| RLS-Prüfung nach ADR-06 und technischer Spezifikation 5.6 | R-21 | mittel | dokumentierte Entscheidung, bei Einführung Pool-Tests | +| HSTS am Synology-Proxy nachweisen, `X-Forwarded-Proto` nur vom Proxy | R-21, R-28 | klein | Header-Nachweis | + +## Stufe 5 – Qualität und Pflege + +| Maßnahme | Befund | +|---|---| +| Request-ID, stabile Problem-Typen, Readiness mit Migrationsstand, OpenAPI in Development als CI-Artefakt | R-24 | +| Transport mit Timeout und Abbruch, robustes Fehlerparsing, 401 setzt Sitzung zurück | R-25 | +| Hash-gebundene Python-Locks, exakte npm-Versionen, Basisimages mit Digest; Versionssprung React/Vite/Router als eigener Auftrag | R-26 | +| Verwaltungsdialoge: Einladung, Zuweisung, Mitglied entfernen/befördern, Konto sperren | R-29 | +| Mehrumfang als Fachpunkte nachtragen; technische Spezifikation 0.4 mit Abweichungsregister | R-17 | +| `.gitignore` um Testhilfsordner ergänzen | R-30 | +| Drag-and-drop-Nachweis UX-17 dokumentieren | – | + +## Abhängigkeiten + +- Stufe 1 ist unabhängig und sollte vor jeder Erweiterung kommen. +- R-10 (Zugang an der Referenz) entspricht dem ersten Schritt des Connector-Umbaus aus dem Connectoren-Befund. Beide sollten gemeinsam geplant werden. +- R-22/R-23 (Transaktionsschnitt) erleichtert R-10 und den Export-Stream. Daher zuerst R-23. +- Stufe 4 ist Voraussetzung für echte personenbezogene Daten in der Produktion und muss vor dem Finanzausbau (P4b) stehen, weil dann noch sensiblere Daten hinzukommen. diff --git a/docs/review/README.md b/docs/review/README.md new file mode 100644 index 0000000..e146a55 --- /dev/null +++ b/docs/review/README.md @@ -0,0 +1,70 @@ +# Code-Review Tsumugu – Gesamtbericht + +**Stand:** 18.10.2026 · **Geprüfter Code:** Branch `develop`, Commit `f21c64a` · **Art:** statisches Review mit Build- und Syntaxprüfung, ohne Codeänderung + +Dieser Ordner enthält den vollständigen Review-Bericht. Geprüft wurde, ob die Anforderungen aus `docs/product`, `docs/architecture` und `docs/design` umgesetzt sind und ob der Code die Referenzarchitektur A/B/C v0.3 und die Spezial-Blueprints aus `docs/reference` einhält. Zusätzlich wurde die Dokumentation auf Vollständigkeit geprüft und ergänzt. + +## Dokumente dieses Reviews + +| Datei | Inhalt | +|---|---| +| [01_METHODIK_UND_QUELLEN.md](01_METHODIK_UND_QUELLEN.md) | Vorgehen, gelesene Quellen, ausgeführte Prüfungen, Grenzen, Bewertungsskala | +| [02_ANFORDERUNGEN_PRODUKT.md](02_ANFORDERUNGEN_PRODUKT.md) | Abgleich mit der Produktspezifikation (F-01 bis F-08, S-01, F-05a-Abnahme) | +| [03_ANFORDERUNGEN_UX_UND_AUFTRAEGE.md](03_ANFORDERUNGEN_UX_UND_AUFTRAEGE.md) | Abgleich mit UX-Ergänzung 0.8 (UX-01 bis UX-21) und den Einzelaufträgen (Symbole, Richtung, kompakte Liste, Export, Unterkapitel, Ensō) | +| [04_TECHNISCHE_SPEZIFIKATION.md](04_TECHNISCHE_SPEZIFIKATION.md) | Abgleich mit der technischen Spezifikation 0.3: Pakete P0–P7, Datenmodell, Invarianten, API-Verzeichnis, Nachweise T-* | +| [05_REFERENZARCHITEKTUR_BLUEPRINTS.md](05_REFERENZARCHITEKTUR_BLUEPRINTS.md) | Vertragsweiser Abgleich mit A/B/C v0.3, Auth/Session/Scope, Medien/Dateien, Release/Betrieb/Recovery sowie den Grenzen KI, Prompt, Entitlements | +| [06_BEFUNDE.md](06_BEFUNDE.md) | Alle Code-Befunde mit ID, Schweregrad, Fundstelle, Szenario und Empfehlung | +| [07_TESTS_UND_CI.md](07_TESTS_UND_CI.md) | Testabdeckung gegen die geplanten Nachweise, CI-Workflows, Lücken | +| [08_DOKUMENTATION.md](08_DOKUMENTATION.md) | Inventar, Widersprüche, im Review ergänzte Dokumente, verbleibende Lücken | +| [09_MASSNAHMENPLAN.md](09_MASSNAHMENPLAN.md) | Priorisierte Maßnahmen mit Reihenfolge und Abnahme | + +## Gesamtbewertung + +Die erste Lieferung „Organisieren und Nachverfolgen“ (F-05a) ist fachlich weitgehend vollständig umgesetzt. Hinzu kommen die späteren Aufträge: UX-Überarbeitung, Typ-Symbole, Antwortbezüge, Kommunikationsrichtung, kompakte Liste, Übergabepaket (F-07a–c) und Unterkapitel (F-08a). Das kontextbezogene Rechtemodell ist sorgfältig gebaut. Unsichtbare Objekte werden in Listen, Suche, Chronologie und Export weggelassen, ohne Titel und ohne Anzahl. Die Backend-Suite deckt die wichtigsten fachlichen Prüfszenarien der technischen Spezifikation ab (T-ISO, T-SHARE, T-CONTEXT, T-DETACH, T-GRANT, T-DL, T-ANCHOR-01). Bewusst zurückgestellte Fähigkeiten sind nicht stillschweigend gestrichen: Finanzen, Paperless-Abgleich, virtuelle Zusammenstellungen, gespeicherte Sichten, KI und Anwaltszugang. + +Die Schwächen liegen in drei Bereichen: + +1. **Rechte- und Datenintegrität an Einzelstellen.** Bearbeiter können ganze Akten und Vorgänge löschen, obwohl laut Rollentabelle nur der Owner Behälter löschen darf. Das Lösen einer Einbindung prüft nicht, ob sie zum Handlungskontext gehört. Vorgangsausnahmen wirken nicht auf die Inhalte des Vorgangs. Die zentrale Übersicht und die Suche begrenzen die Treffer vor der Rechteprüfung, sodass bei wachsendem Datenbestand eigene Einträge stillschweigend fehlen. +2. **Abweichungen von verbindlichen Blueprint-Verträgen.** Das Betreiberkonto entsteht über eine öffentliche Web-Route statt über die lokale CLI mit MFA. Betreiber-MFA fehlt. Sessions laufen 14 Tage ohne Leerlaufablauf und ohne Rotation. Runtime und Migration nutzen dieselben DB-Zugangsdaten. Quellen-Geheimnisse liegen im Klartext in der Datenbank. Externe Aufrufe zu Paperless und IMAP laufen bei offener DB-Transaktion. E-Mail-Anlagen werden `inline` mit vom Absender bestimmtem Medientyp ausgeliefert. +3. **Betrieb mit echten Daten.** Paket P7 fehlt vollständig: Backup, Restore, Release-Gate, RLS-Prüfung und HSTS-Nachweis. Ein Merge nach `main` deployt trotzdem direkt in die Produktion, ohne vorgelagerten Test. Laut technischer Spezifikation 8.2 wartet Produktion mit echten Akten auf P7. + +Nichts davon verlangt einen Umbau. Die meisten Punkte lassen sich gezielt im Bestand beheben (siehe [Maßnahmenplan](09_MASSNAHMENPLAN.md)). + +## Kennzahlen + +| Bereich | Ergebnis | +|---|---| +| Bestätigte Fachentscheidungen der ersten Lieferung (F-01a–f, S-01a–d, F-04a, F-05a) | umgesetzt; Einzellücken unter R-01, R-02, R-07 | +| Spätere Aufträge F-06a–f, F-07a–c, F-08a | umgesetzt; Einschränkungen unter R-13, R-22 | +| Zurückgestellt laut F-05a/F-07a (Finanzen, P6, P5b, Anwaltszugang, KI) | nicht umgesetzt, wie vorgesehen | +| UX-Abnahmekriterien UX-01 bis UX-21 | 17 statisch belegt, 2 teilweise (UX-10, UX-18), 2 ohne Nachweis (UX-13 Bedienung, UX-17 echtes Drag-and-drop mit Zeiger) | +| Befunde | 31 insgesamt: 0 kritisch, 8 hoch, 13 mittel, 8 niedrig, 2 Hinweise | +| Backend-Tests | 54 Testfunktionen in 12 Dateien; nicht ausgeführt (keine PostgreSQL-Instanz im Review) | +| Frontend | Produktionsbuild erfolgreich; 4 von 4 Node-Tests bestanden | +| Python | `py_compile` aller Module erfolgreich | + +## Wichtigste Befunde + +| ID | Schwere | Kurzbeschreibung | +|---|---|---| +| R-21 | Hoch | P7 fehlt: kein Backup/Restore, kein Release-Gate, keine RLS-Prüfung. `main` deployt ohne vorgelagerte Tests nach Produktion | +| R-01 | Hoch | Bearbeiter dürfen Akte und Vorgang löschen. Laut Rollentabelle darf das nur der Owner | +| R-02 | Hoch | `DELETE /bindings/{id}` prüft die Zugehörigkeit der Einbindung zum Handlungskontext nicht | +| R-03 | Hoch | E-Mail-Anlagen und Paperless-Bilder (auch SVG) werden `inline` aus dem App-Origin ausgeliefert | +| R-04 | Hoch | Betreiberkonto über eine öffentliche Web-Route, ohne MFA (Abweichung von ADR-05 und Auth-Blueprint 11.3) | +| R-11 | Hoch | Offene Aufgaben, Fristen und Suche: `LIMIT` vor der Rechteprüfung. Sichtbare Treffer fallen weg | +| R-08 | Hoch | Sessions 14 Tage ohne Leerlaufablauf und Rotation, Login-Begrenzung nur im Prozessspeicher, kein Passwortwechsel | +| R-31 | Hoch | Hochgeladene Fotos behalten EXIF- und GPS-Metadaten, es gibt keine Normalisierung | + +Die vollständige Liste steht in [06_BEFUNDE.md](06_BEFUNDE.md). + +## Im Review ergänzte Dokumentation + +- [docs/README.md](../README.md): Dokumentationslandkarte +- [docs/architecture/API_REFERENZ.md](../architecture/API_REFERENZ.md): tatsächlich registrierte Endpunkte +- [docs/architecture/DATENMODELL_IST.md](../architecture/DATENMODELL_IST.md): Schema nach allen Migrationen +- [docs/architecture/RECHTEMODELL_IST.md](../architecture/RECHTEMODELL_IST.md): implementierte Rechteauswertung +- [docs/ENTWICKLUNG_UND_TESTS.md](../ENTWICKLUNG_UND_TESTS.md): lokaler Start, Tests, Builds +- Korrekturen in `README.md`, `docs/DEPLOYMENT.md` und ein Ist-Hinweis in `docs/architecture/TSUMUGU_TECHNICAL_SPEC.md` + +Anwendungscode, Migrationen, Workflows und Konfiguration wurden nicht verändert. diff --git a/frontend/src/api.js b/frontend/src/api.js index c2a3c0a..261a807 100644 --- a/frontend/src/api.js +++ b/frontend/src/api.js @@ -101,7 +101,7 @@ export async function downloadMailPart(elementId, context, suffix, filename) { setTimeout(() => URL.revokeObjectURL(url), 60000); } -export async function fetchPaperless(elementId, context) { +export async function fetchExternal(elementId, context) { const params = new URLSearchParams(); if (context?.kind && context?.id) { params.set("context_kind", context.kind); @@ -113,11 +113,15 @@ export async function fetchPaperless(elementId, context) { }); if (!response.ok) { const data = await response.json().catch(() => null); - throw new Error(data?.detail || "Das Paperless-Dokument ist nicht verfügbar."); + throw new Error(data?.detail || "Die Quelle stellt die Datei nicht bereit."); } return response.blob(); } +export async function fetchPaperless(elementId, context) { + return fetchExternal(elementId, context); +} + export async function fetchFile(elementId, context) { const params = new URLSearchParams(); if (context?.kind && context?.id) { diff --git a/frontend/src/pages/Cases.jsx b/frontend/src/pages/Cases.jsx index 5c05a1d..d6c9d00 100644 --- a/frontend/src/pages/Cases.jsx +++ b/frontend/src/pages/Cases.jsx @@ -4,7 +4,8 @@ import { api, markDirty, textToDocument } from "../api.js"; import { SessionContext } from "../session.js"; import { chapterPathLabel, siblingChapterIds, trailWithChapter } from "./chapters.js"; import { Modal } from "./Modal.jsx"; -import { MailPicker, PaperlessPicker } from "./Sources.jsx"; +import "./Sources.jsx"; +import { SourcePicker, moduleFor, sourceModules } from "../sources/registry.jsx"; import { ErrorNote, ShareBox } from "./widgets.jsx"; import { ContentBoard, DateField, DirectionChoice, MarkdownEditor, ObjectMenu, OrderChoice, RecordTree, SurfaceView, TargetLine, Trail, WorkLists, WorkSwitch, saveChapterOrder, writeSelection } from "./content.jsx"; import { ReadingPane } from "./ReadingPane.jsx"; @@ -635,8 +636,9 @@ export function CaseDetail() { {addChapterId ? : null} - - + {sourceModules().map((module) => ( + + ))} setModal("")}> @@ -645,11 +647,8 @@ export function CaseDetail() { setModal("")}> { load(); if (finished) setModal(""); }} /> - setModal("")}> - { setModal(""); load(); }} /> - - setModal("")}> - { setModal(""); load(); }} /> + setModal("")}> + { setModal(""); load(); }} /> setModal("")}> { setModal(""); load(); }} /> @@ -717,8 +716,7 @@ function BindingTiles({ items, onOpen, empty }) { function sourceKind(element) { if (element.kind === "note") return "Notiz"; if (element.kind === "file") return "Datei"; - if (element.external?.source === "paperless") return "Paperless"; - if (element.external?.source === "imap") return "E-Mail"; + if (element.external?.source) return moduleFor(element.external.source)?.addLabel || moduleFor(element.external.source)?.title || "Referenz"; return "Referenz"; } @@ -1157,7 +1155,8 @@ export function FileForm({ context, placement, chapters = [], initialChapter = " function ExternalForm({ context, placement, chapters = [], initialChapter = "", targetLabel = "", onChange }) { const [title, setTitle] = useState(""); const [externalId, setExternalId] = useState(""); - const [source, setSource] = useState("paperless"); + const sourceChoices = [{ kind: "url", title: "Andere Quelle" }, ...sourceModules().filter((item) => item.manual)]; + const [source, setSource] = useState(() => sourceChoices.find((item) => item.kind !== "url")?.kind || "url"); const [chapterId, setChapterId] = useState(initialChapter); const [documentOn, setDocumentOn] = useState(""); const [sentOn, setSentOn] = useState(""); @@ -1197,11 +1196,10 @@ function ExternalForm({ context, placement, chapters = [], initialChapter = "", return (
-

Paperless oder andere Referenz

+

Referenz erfassen

setTitle(event.target.value)} placeholder="Anzeigetitel" required /> setExternalId(event.target.value)} placeholder="Externe ID" required /> diff --git a/frontend/src/pages/ExportPackage.jsx b/frontend/src/pages/ExportPackage.jsx index fb5a57f..864df0b 100644 --- a/frontend/src/pages/ExportPackage.jsx +++ b/frontend/src/pages/ExportPackage.jsx @@ -71,7 +71,7 @@ function symbolFor(node) { if (node.kind === "matter") return node.label === "Teilvorgang" ? "submatter" : "matter"; if (node.kind === "annotation" || node.content_kind === "note") return "note"; if (node.content_kind === "email") return "email"; - if (node.content_kind === "paperless") return "source-archive"; + if (node.content_kind === "source") return "source-archive"; if (node.content_kind === "url") return "link"; return "file"; } diff --git a/frontend/src/pages/Matters.jsx b/frontend/src/pages/Matters.jsx index 252e9d9..104dbee 100644 --- a/frontend/src/pages/Matters.jsx +++ b/frontend/src/pages/Matters.jsx @@ -3,7 +3,8 @@ import { Link, useNavigate, useParams, useSearchParams } from "react-router-dom" import { api, isDirty, markDirty } from "../api.js"; import { SessionContext } from "../session.js"; import { Modal } from "./Modal.jsx"; -import { MailPicker, PaperlessPicker } from "./Sources.jsx"; +import "./Sources.jsx"; +import { SourcePicker, moduleFor, sourceModules } from "../sources/registry.jsx"; import { ErrorNote, ShareBox } from "./widgets.jsx"; import { chapterPathLabel, siblingChapterIds, trailWithChapter } from "./chapters.js"; import { ChapterForm, FileForm, NoteForm } from "./Cases.jsx"; @@ -580,8 +581,9 @@ export function MatterDetail() { {addChapterId ? : null} - - + {sourceModules().map((module) => ( + + ))} setModal("")}> @@ -590,11 +592,8 @@ export function MatterDetail() { setModal("")}> { load(); if (finished) setModal(""); }} /> - setModal("")}> - { setModal(""); load(); }} /> - - setModal("")}> - { setModal(""); load(); }} /> + setModal("")}> + { setModal(""); load(); }} /> setModal("")}> { setModal(""); load(); }} /> diff --git a/frontend/src/pages/ReadingPane.jsx b/frontend/src/pages/ReadingPane.jsx index 84d2962..516efd4 100644 --- a/frontend/src/pages/ReadingPane.jsx +++ b/frontend/src/pages/ReadingPane.jsx @@ -1,5 +1,6 @@ import { useEffect, useRef, useState } from "react"; -import { documentToText, downloadMailPart, fetchFile, fetchMailPart, fetchPaperless, markDirty, textToDocument, api } from "../api.js"; +import { documentToText, downloadMailPart, fetchExternal, fetchFile, fetchMailPart, markDirty, textToDocument, api } from "../api.js"; +import { SourceAssignment, noteEditor, representationOf } from "../sources/registry.jsx"; import { ErrorNote } from "./widgets.jsx"; import { UnitDetail } from "./correspondence.jsx"; import { dateCaption, DateField, DirectionChoice, DirectionColumn, directionValue, directionWord, formatDate, mailFacts, MarkdownEditor, sourceLabel } from "./content.jsx"; @@ -83,6 +84,7 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca const [pages, setPages] = useState(0); const [scale, setScale] = useState(1); const [text, setText] = useState(""); + const [sourceText, setSourceText] = useState(""); const [note, setNote] = useState(""); const [summary, setSummary] = useState(""); const [documentOn, setDocumentOn] = useState(""); @@ -114,15 +116,15 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca useEffect(() => { if (!element) return undefined; - const mail = element.external?.source === "imap"; - if (element.kind === "note" || mail) setPhase("ready"); - else if (!element.preview?.available) setPhase("missing"); + const kind = representationOf(element); + if (kind === "note" || kind === "mail") setPhase("ready"); + else if (kind === "locked" || kind === "unassigned" || !element.preview?.available) setPhase("missing"); setError(""); return undefined; - }, [element?.id, element?.kind, element?.external?.source, element?.preview?.available]); + }, [element?.id, element?.kind, element?.external?.source, element?.external?.resolution, element?.file?.protection_profile, element?.preview?.available]); useEffect(() => { - if (!element || element.kind === "note" || element.external?.source === "imap" || !element.preview?.available) return undefined; + if (!element || representationOf(element) === "note" || representationOf(element) === "mail" || representationOf(element) === "locked" || representationOf(element) === "unassigned" || !element.preview?.available) return undefined; let alive = true; let url = ""; setPage(1); @@ -136,9 +138,16 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca } setBlobUrl(""); setPhase("loading"); - const load = element.external?.source === "paperless" ? fetchPaperless(element.id, context) : fetchFile(element.id, context); + const view = representationOf(element); + const load = view === "source-file" || view === "text" ? fetchExternal(element.id, context) : fetchFile(element.id, context); load.then(async (blob) => { if (!alive) return; + if (view === "text") { + setSourceText(await blob.text()); + setMedia("text"); + setPhase("ready"); + return; + } url = URL.createObjectURL(blob); setBlobUrl(url); if (blob.type.startsWith("image/")) { @@ -179,10 +188,10 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca alive = false; if (url) URL.revokeObjectURL(url); }; - }, [element?.id, element?.kind, element?.external?.source, element?.preview?.available, context?.kind, context?.id]); + }, [element?.id, element?.kind, element?.external?.source, element?.external?.resolution, element?.file?.protection_profile, element?.preview?.available, context?.kind, context?.id]); useEffect(() => { - if (!element || element.external?.source !== "imap") return undefined; + if (!element || representationOf(element) !== "mail") return undefined; if (shownIndex === null) { setPhase("ready"); setPdf(null); @@ -251,7 +260,7 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca }, [element?.id, element?.external?.source, shownIndex, letter, context?.kind, context?.id]); useEffect(() => { - if (!element || element.external?.source !== "imap") return undefined; + if (!element || representationOf(element) !== "mail") return undefined; let alive = true; const params = new URLSearchParams(); if (context?.kind && context?.id) { @@ -330,8 +339,9 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca async function openOriginal() { setError(""); try { - const blob = element.external?.source === "paperless" - ? await fetchPaperless(element.id, context) + const view = representationOf(element); + const blob = view === "source-file" || view === "text" + ? await fetchExternal(element.id, context) : await fetchFile(element.id, context); const url = URL.createObjectURL(blob); window.open(url, "_blank", "noopener"); @@ -345,14 +355,20 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca event.preventDefault(); setError(""); try { - const updated = await api(`/api/v1/notes/${element.id}`, { - method: "PATCH", - body: { expected_version: element.version, document: textToDocument(text), context }, + const updated = await noteEditor.save({ + api, + element, + context, + document: textToDocument(text), }); markDirty(false); setNotice(updated.notice || "Der gemeinsame Text ist gespeichert."); onReload(); } catch (err) { + if (err.status === 409) { + setError("Der Stand hat sich geändert. Der eingegebene Text bleibt stehen. Bitte neu laden."); + return; + } setError(err.message); } } @@ -478,7 +494,10 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca const communication = binding.communication || {}; const shownDirection = communication.direction || null; - const isMail = element.external?.source === "imap"; + const kind = representationOf(element); + const isMail = kind === "mail"; + const locked = kind === "locked"; + const unassigned = kind === "unassigned"; const mailDetail = letter || element.external?.detail || {}; const shownFile = isMail ? (letter?.attachments || []).find((item) => item.index === shownIndex) || null : null; @@ -564,7 +583,7 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca )} ) : null} - {element.kind === "note" ? ( + {element.kind === "note" && noteEditor.available ? ( { setText(value); markDirty(true); }} />

Diese Änderung betrifft den gemeinsamen Inhalt der Notiz, nicht die hiesige Anmerkung. Gespeichert wird Markdown.

@@ -580,8 +599,18 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca />

Keine Angabe bleibt leer. Versand- und Zugangsdatum ändern die Richtung nicht.

- {!isMail && phase === "loading" ?

Vorschau wird geladen …

: null} - {!isMail && phase === "missing" ? ( + {!isMail && locked ? ( +
+

Die Metadaten sind sichtbar. Der Inhalt ist geschützt und wird in dieser Lieferung nicht entschlüsselt.

+
+ ) : null} + {!isMail && unassigned ? ( +
+ +
+ ) : null} + {!isMail && !locked && !unassigned && phase === "loading" ?

Vorschau wird geladen …

: null} + {!isMail && !locked && !unassigned && phase === "missing" ? (

Für diesen Inhalt gibt es keine eingebaute Vorschau.

@@ -593,6 +622,7 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca
) : null} + {!isMail && media === "text" ?
{sourceText}
: null} {!isMail && media === "image" && blobUrl ? ( {element.title} ) : null} diff --git a/frontend/src/pages/Sources.jsx b/frontend/src/pages/Sources.jsx index 91b86a0..eb86a8e 100644 --- a/frontend/src/pages/Sources.jsx +++ b/frontend/src/pages/Sources.jsx @@ -1,7 +1,13 @@ import { useEffect, useState } from "react"; import { Link } from "react-router-dom"; import { api } from "../api.js"; -import { TargetLine, formatDate } from "./content.jsx"; +import { SourceFrame, defineSourceModules, moduleFor, sourceModules } from "../sources/registry.jsx"; + +const SEARCH_LIMITS = { + paperless: "Suche in dieser Lieferung: Stichwort. Korrespondent, Dokumenttyp, Tags, Zeitraum und Sortierung sind noch nicht verfügbar.", + imap: "Suche im gewählten Fach: Stichwort und weitere Seiten. Korrespondent, Dokumenttyp, Tags und Sortierung sind noch nicht verfügbar.", +}; +import { formatDate } from "./content.jsx"; import { NavIcon } from "./icons.jsx"; import { ErrorNote } from "./widgets.jsx"; @@ -9,6 +15,9 @@ export function Sources() { const [items, setItems] = useState([]); const [error, setError] = useState(""); const [notice, setNotice] = useState(""); + const [renew, setRenew] = useState(null); + const modules = sourceModules(); + const RenewForm = renew ? moduleFor(renew.kind)?.Form : null; async function load() { const data = await api("/api/v1/connectors"); @@ -32,41 +41,59 @@ export function Sources() {
{items.map((item) => (
- {item.kind === "paperless" ? "Paperless" : "IMAP"} + {moduleFor(item.kind)?.title || item.kind} {item.name} - {item.kind === "paperless" ? item.settings.base_url : item.settings.username} + {item.settings.base_url || item.settings.username || item.settings.catalog || ""}
+
))}
-
-

Paperless

- -
-
-

E-Mail-Konto

- -
+ {renew ? ( +
+

Zugang erneuern: {renew.name}

+

Dasselbe Konto behält seine Instanz. Eine weitere Instanz legst du darunter neu an.

+ {RenewForm ? ( + { setRenew(null); await load(); }} + onError={setError} + /> + ) : ( +

Dieser Zugang wird über sein Modul erneuert.

+ )} +
+ ) : null} + {modules.filter((module) => module.Form).map((module) => ( +
+

{module.title}

+ +
+ ))} ); } -function PaperlessForm({ onSaved, onError }) { - const [name, setName] = useState("Paperless"); - const [baseUrl, setBaseUrl] = useState(""); +function PaperlessForm({ onSaved, onError, connectorId = "", initialName = "Paperless", initialUrl = "", settings = null }) { + const [name, setName] = useState(initialName); + const [baseUrl, setBaseUrl] = useState(settings?.base_url || initialUrl); const [token, setToken] = useState(""); async function submit(event) { event.preventDefault(); onError(""); try { - await api("/api/v1/connectors", { - method: "POST", - body: { kind: "paperless", name, base_url: baseUrl, token }, - }); + const body = { kind: "paperless", name, base_url: baseUrl, token }; + if (connectorId) { + await api(`/api/v1/connectors/${connectorId}`, { method: "PATCH", body }); + } else { + await api("/api/v1/connectors", { method: "POST", body }); + } setToken(""); await onSaved(); } catch (err) { @@ -79,36 +106,48 @@ function PaperlessForm({ onSaved, onError }) { - + ); } -function MailForm({ onSaved, onError }) { - const [name, setName] = useState(""); - const [host, setHost] = useState(""); - const [port, setPort] = useState("993"); - const [username, setUsername] = useState(""); +function MailForm({ + onSaved, + onError, + connectorId = "", + initialName = "", + initialHost = "", + initialPort = "993", + initialUsername = "", + initialSecurity = "ssl", + settings = null, +}) { + const [name, setName] = useState(initialName); + const [host, setHost] = useState(settings?.host || initialHost); + const [port, setPort] = useState(String(settings?.port || initialPort)); + const [username, setUsername] = useState(settings?.username || initialUsername); const [password, setPassword] = useState(""); - const [security, setSecurity] = useState("ssl"); + const [security, setSecurity] = useState(settings?.security || initialSecurity); async function submit(event) { event.preventDefault(); onError(""); try { - await api("/api/v1/connectors", { - method: "POST", - body: { - kind: "imap", - name: name || username, - host, - port: Number(port), - username, - password, - security, - mailbox: "INBOX", - }, - }); + const body = { + kind: "imap", + name: name || username, + host, + port: Number(port), + username, + password, + security, + mailbox: "INBOX", + }; + if (connectorId) { + await api(`/api/v1/connectors/${connectorId}`, { method: "PATCH", body }); + } else { + await api("/api/v1/connectors", { method: "POST", body }); + } setPassword(""); await onSaved(); } catch (err) { @@ -130,7 +169,7 @@ function MailForm({ onSaved, onError }) { - + ); } @@ -143,16 +182,35 @@ function paperlessLabel(item) { export function PaperlessPicker({ context, placement, chapterId = "", chapterTitle = "", targetLabel = "", onDone, onInserted }) { const [query, setQuery] = useState(""); const [items, setItems] = useState([]); + const [connectors, setConnectors] = useState([]); + const [connectorId, setConnectorId] = useState(""); const [picked, setPicked] = useState(() => new Map()); const [pending, setPending] = useState(false); const [error, setError] = useState(""); + useEffect(() => { + api("/api/v1/connectors") + .then((data) => { + const paper = (data.items || []).filter((item) => item.kind === "paperless"); + setConnectors(paper); + if (paper.length === 1) setConnectorId(paper[0].id); + }) + .catch((err) => setError(err.message)); + }, []); + async function search(event) { event.preventDefault(); setError(""); + if (connectors.length > 1 && !connectorId) { + setError("Wähle zuerst den Paperless-Zugang."); + return; + } try { - const data = await api(`/api/v1/sources/paperless/documents?q=${encodeURIComponent(query)}`); + const params = new URLSearchParams({ q: query }); + if (connectorId) params.set("connector_id", connectorId); + const data = await api(`/api/v1/sources/paperless/documents?${params}`); setItems(data.items); + if (data.connector_id) setConnectorId(data.connector_id); } catch (err) { setError(err.message); } @@ -185,10 +243,11 @@ export function PaperlessPicker({ context, placement, chapterId = "", chapterTit context, ...(placement ? { placement } : {}), ...(chapterId ? { chapter_id: chapterId } : {}), - ...(item.document_on || item.correspondent || item.open_url + ...(item.document_on || item.correspondent || item.open_url || connectorId ? { dates: { document_on: item.document_on || null, sent_on: null, received_on: null }, detail: { + ...(connectorId ? { connector_id: connectorId } : {}), ...(item.correspondent ? { correspondent: item.correspondent } : {}), ...(item.open_url ? { open_url: item.open_url } : {}), }, @@ -216,13 +275,24 @@ export function PaperlessPicker({ context, placement, chapterId = "", chapterTit } return ( -
- + + {connectors.length > 1 ? ( + + ) : null}
setQuery(event.target.value)} placeholder="Titel oder Stichwort" />
+

{SEARCH_LIMITS.paperless}

Die Verbindung richtest du unter Quellen ein. Mehrere Treffer lassen sich zusammen einfügen.

{items.length || picked.size ? (
- + ); } @@ -539,8 +609,7 @@ export function MailPicker({ context, placement, chapterId = "", chapterTitle = const selected = items.find((item) => `${mailbox}:${item.uid || item.id}` === selectedKey) || null; return ( -
- +
- + ); } @@ -631,3 +701,8 @@ async function remove(id, load, setError) { setError(err.message); } } + +defineSourceModules([ + { kind: "paperless", title: "Paperless", addLabel: "Paperless", manual: true, searchHint: SEARCH_LIMITS.paperless, Form: PaperlessForm, Picker: PaperlessPicker }, + { kind: "imap", title: "E-Mail-Konto", addLabel: "E-Mail", wide: true, searchHint: SEARCH_LIMITS.imap, Form: MailForm, Picker: MailPicker }, +]); diff --git a/frontend/src/pages/content.jsx b/frontend/src/pages/content.jsx index a8d802c..968e0fa 100644 --- a/frontend/src/pages/content.jsx +++ b/frontend/src/pages/content.jsx @@ -1,7 +1,8 @@ import { useEffect, useLayoutEffect, useRef, useState } from "react"; import { createPortal } from "react-dom"; import { Link } from "react-router-dom"; -import { api, fetchFile, fetchPaperless } from "../api.js"; +import { api, fetchExternal, fetchFile } from "../api.js"; +import { moduleFor } from "../sources/registry-core.js"; import { contentSourceSymbol, contentSymbol, symbolUrl } from "../content-symbol.mjs"; import { bezugCount, counterpartLabel, directionSymbol } from "../list-meta.mjs"; import { MarkdownView } from "../markdown.jsx"; @@ -307,20 +308,24 @@ const SYMBOL_LABEL = { }; function elementSymbol(element) { - if (element?.external?.source === "imap") return "email"; + const media = element?.preview?.media; + const representation = moduleFor(element?.external?.source)?.representation; + if (media === "email" || representation === "email") return "email"; return contentSymbol(element || {}); } export function sourceLabel(element) { const type = SYMBOL_LABEL[elementSymbol(element)] || "Datei"; - if (element.external?.source === "paperless") return `${type} · Paperless`; - if (element.external?.source === "imap") return "E-Mail"; + const module = moduleFor(element.external?.source); + if (module?.representation === "email") return module.addLabel || "E-Mail"; + if (module) return `${type} · ${module.addLabel || module.title}`; if (element.kind === "external_ref" && type === "Verweis") return "Referenz"; return type; } export function mailFacts(element) { - if (element?.external?.source !== "imap") return ""; + const module = moduleFor(element?.external?.source); + if (element?.preview?.media !== "email" && module?.representation !== "email") return ""; const detail = element.external.detail || {}; const from = detail.message_from ? `Von: ${detail.message_from}` : ""; const to = detail.message_to ? `An: ${detail.message_to}` : ""; @@ -872,7 +877,7 @@ function EntryMark({ element, context, assignable = false, dropId = "", hot = fa if (!photo) return undefined; let alive = true; let current = ""; - const load = element.preview.source === "paperless" ? fetchPaperless(element.id, context) : fetchFile(element.id, context); + const load = element.kind === "external_ref" ? fetchExternal(element.id, context) : fetchFile(element.id, context); load.then((blob) => { if (!alive || !blob.type.startsWith("image/")) return; current = URL.createObjectURL(blob); @@ -1963,7 +1968,7 @@ export function ContentBoard({ async function placeReceipt(hostBinding, payload, element) { if (!payload || payload.elementId === hostBinding.element.id) return; - const role = element?.external?.source === "imap" ? "email" : "other"; + const role = moduleFor(element?.external?.source)?.representation === "email" ? "email" : "other"; setPending(true); setError(""); try { diff --git a/frontend/src/pages/correspondence.jsx b/frontend/src/pages/correspondence.jsx index 8f3cf5a..6254aa4 100644 --- a/frontend/src/pages/correspondence.jsx +++ b/frontend/src/pages/correspondence.jsx @@ -1,6 +1,7 @@ import { useEffect, useMemo, useRef, useState } from "react"; import { Link } from "react-router-dom"; import { api } from "../api.js"; +import { moduleFor } from "../sources/registry-core.js"; import { buildChapterSections, sectionCounts } from "./chapters.js"; function formatDate(value) { @@ -65,7 +66,7 @@ export function receiptRoleLabel(role, fallback = "") { } function receiptCaption(proof) { - if (proof.role === "email" && proof.source !== "imap") return "Beleg"; + if (proof.role === "email" && moduleFor(proof.source)?.representation !== "email") return "Beleg"; return receiptRoleLabel(proof.role, proof.role_label); } diff --git a/frontend/src/pages/widgets.jsx b/frontend/src/pages/widgets.jsx index 973b80b..40686c7 100644 --- a/frontend/src/pages/widgets.jsx +++ b/frontend/src/pages/widgets.jsx @@ -1,6 +1,7 @@ import { useEffect, useRef, useState } from "react"; import { Link } from "react-router-dom"; -import { api, documentToText, downloadFile, fetchPaperless, markDirty, textToDocument } from "../api.js"; +import { api, documentToText, downloadFile, fetchExternal, markDirty, textToDocument } from "../api.js"; +import { moduleFor } from "../sources/registry-core.js"; import { Modal } from "./Modal.jsx"; export function ErrorNote({ error }) { @@ -53,11 +54,11 @@ function Binding({ binding, context, canEdit, isOwner, onChange }) { if (previewUrl) URL.revokeObjectURL(previewUrl); }, [previewUrl]); - async function viewPaperless() { + async function viewOriginal() { setError(""); setViewing(true); try { - const blob = await fetchPaperless(element.id, context); + const blob = await fetchExternal(element.id, context); if (previewUrl) URL.revokeObjectURL(previewUrl); setPreviewUrl(URL.createObjectURL(blob)); } catch (err) { @@ -212,12 +213,12 @@ function Binding({ binding, context, canEdit, isOwner, onChange }) { {element.kind === "external_ref" && element.external ? (

- {element.external.source === "paperless" ? "Paperless" : element.external.source === "imap" ? "E-Mail" : "Externe Adresse"} + {moduleFor(element.external.source)?.addLabel || moduleFor(element.external.source)?.title || "Externe Adresse"} {element.external.detail?.correspondent ? ` · ${element.external.detail.correspondent}` : ""} {element.external.detail?.message_from ? ` · ${element.external.detail.message_from}` : ""}

- {element.external.source === "paperless" ? ( - + {moduleFor(element.external.source)?.representation && moduleFor(element.external.source).representation !== "email" ? ( + ) : ( Verknüpft, ohne die Quelle zu kopieren. )} @@ -314,8 +315,8 @@ function kindLabel(element) { const kind = element.kind; if (kind === "note") return "Notiz"; if (kind === "file") return "Datei"; - if (element.external?.source === "paperless") return "Paperless"; - if (element.external?.source === "imap") return "E-Mail"; + const module = moduleFor(element.external?.source); + if (module) return module.addLabel || module.title; if (kind === "external_ref") return "Referenz"; return kind; } diff --git a/frontend/src/sources/registry-core.js b/frontend/src/sources/registry-core.js new file mode 100644 index 0000000..793e640 --- /dev/null +++ b/frontend/src/sources/registry-core.js @@ -0,0 +1,23 @@ +const modules = new Map(); + +export function registerSourceModule(module) { + modules.set(module.kind, module); + return module; +} + +export function unregisterSourceModule(kind) { + modules.delete(kind); +} + +export function defineSourceModules(list) { + modules.clear(); + for (const item of list) modules.set(item.kind, item); +} + +export function sourceModules() { + return [...modules.values()]; +} + +export function moduleFor(kind) { + return modules.get(kind) || null; +} diff --git a/frontend/src/sources/registry.jsx b/frontend/src/sources/registry.jsx new file mode 100644 index 0000000..778eb52 --- /dev/null +++ b/frontend/src/sources/registry.jsx @@ -0,0 +1,223 @@ +import { useEffect, useState } from "react"; +import { api } from "../api.js"; +import { TargetLine } from "../pages/content.jsx"; +import { ErrorNote } from "../pages/widgets.jsx"; +import { defineSourceModules, moduleFor, registerSourceModule, sourceModules, unregisterSourceModule } from "./registry-core.js"; + +export { defineSourceModules, moduleFor, registerSourceModule, sourceModules, unregisterSourceModule }; + +export function pickerFor(kind) { + const item = moduleFor(kind); + if (!item?.Picker) throw new Error(`Quelle ${kind} ist nicht registriert.`); + return item.Picker; +} + +export function SourceFrame({ targetLabel = "", chapterId = "", chapterTitle = "", children }) { + return ( +
+ + {children} +
+ ); +} + +export function representationOf(element) { + if (!element) return "none"; + if (element.kind === "note") return "note"; + if (element.file?.protection_profile && element.file.protection_profile !== "legacy-plaintext") return "locked"; + const media = element.preview?.media; + if (media === "locked") return "locked"; + if (media === "unassigned") return "unassigned"; + if (media === "email") return "mail"; + if (media === "text") return "text"; + if (element.kind === "external_ref" && (media === "pdf" || media === "image" || media === "file")) return "source-file"; + if (element.kind === "file") return "file"; + return "unsupported"; +} + +export function SourcePicker(props) { + const module = moduleFor(props.sourceKind); + if (!module) return

Diese Quelle ist nicht registriert.

; + const Picker = module.Picker || StandardSourcePicker; + return ; +} + +export function StandardSourcePicker({ sourceKind, context, placement, chapterId, chapterTitle, targetLabel, onDone, onInserted }) { + const module = moduleFor(sourceKind); + const [connectors, setConnectors] = useState([]); + const [connectorId, setConnectorId] = useState(""); + const [query, setQuery] = useState(""); + const [items, setItems] = useState([]); + const [error, setError] = useState(""); + const [pending, setPending] = useState(false); + const hint = module?.searchHint || "Suche im heute unterstützten Umfang dieser Quelle."; + + useEffect(() => { + api("/api/v1/connectors") + .then((data) => { + const matches = (data.items || []).filter((item) => item.kind === sourceKind); + setConnectors(matches); + if (matches.length === 1) setConnectorId(matches[0].id); + }) + .catch((err) => setError(err.message)); + }, [sourceKind]); + + async function search(event) { + event.preventDefault(); + setError(""); + if (connectors.length > 1 && !connectorId) { + setError("Wähle zuerst den Zugang."); + return; + } + const params = new URLSearchParams({ q: query }); + if (connectorId) params.set("connector_id", connectorId); + try { + const data = await api(`/api/v1/sources/${sourceKind}/search?${params}`); + setItems(data.items || []); + if (data.connector_id) setConnectorId(data.connector_id); + } catch (err) { + setError(err.message); + } + } + + async function adopt(item) { + if (pending) return; + setPending(true); + setError(""); + try { + await api("/api/v1/external-refs", { + method: "POST", + body: { + title: item.title, + source: sourceKind, + external_id: String(item.id), + context, + ...(placement ? { placement } : {}), + ...(chapterId ? { chapter_id: chapterId } : {}), + ...(connectorId ? { detail: { connector_id: connectorId } } : {}), + }, + }); + onInserted?.(); + onDone?.(); + } catch (err) { + setError(err.message); + } finally { + setPending(false); + } + } + + return ( + + {connectors.length > 1 ? ( + + ) : null} + {!connectors.length ?

Die Verbindung richtest du unter Quellen ein.

: null} +
+ setQuery(event.target.value)} placeholder="Titel oder Stichwort" /> + +
+ +

{hint}

+
+ {items.map((item) => ( +
+ {item.title} + {item.text ?
{item.text}
: null} + +
+ ))} +
+
+ ); +} + +export const noteEditor = { + id: "note", + available: true, + async save({ api: request, element, context, document }) { + return request(`/api/v1/notes/${element.id}`, { + method: "PATCH", + body: { expected_version: element.version, document, context }, + }); + }, +}; + +export const editors = { + note: noteEditor, + markdown_file: { id: "markdown_file", available: false }, +}; + +export function SourceAssignment({ element, onAssigned }) { + const external = element?.external; + const resolution = external?.resolution; + const source = external?.source; + const [items, setItems] = useState([]); + const [choice, setChoice] = useState(""); + const [error, setError] = useState(""); + const [pending, setPending] = useState(false); + const open = source && (resolution === "ambiguous" || resolution === "unresolved"); + + useEffect(() => { + if (!open || !external?.external_id) return undefined; + let alive = true; + api("/api/v1/connectors") + .then((data) => { + if (!alive) return; + const matches = (data.items || []).filter((item) => item.kind === source); + setItems(matches); + setChoice(matches[0]?.id || ""); + }) + .catch((err) => { + if (alive) setError(err.message); + }); + return () => { + alive = false; + }; + }, [open, source, external?.external_id]); + + if (!open) return null; + if (!external.external_id) { + return

Der Zugang zu dieser Quelle ist nicht zugeordnet.

; + } + + async function submit(event) { + event.preventDefault(); + if (!choice) return; + setPending(true); + setError(""); + try { + await api(`/api/v1/external-refs/${element.id}/assignment`, { + method: "POST", + body: { connector_id: choice }, + }); + onAssigned?.(); + } catch (err) { + setError(err.message); + } finally { + setPending(false); + } + } + + return ( +
+

Diese Referenz hat noch keinen eindeutigen Zugang. Die Zuordnung bleibt bei der gewählten Instanz.

+ + + + + ); +} diff --git a/frontend/src/sources/sample-source.js b/frontend/src/sources/sample-source.js new file mode 100644 index 0000000..62409d2 --- /dev/null +++ b/frontend/src/sources/sample-source.js @@ -0,0 +1,15 @@ +import { registerSourceModule, unregisterSourceModule } from "./registry-core.js"; + +export function installSampleSource() { + return registerSourceModule({ + kind: "sample", + title: "Beispielquelle", + addLabel: "Beispielquelle", + representation: "text", + manual: true, + }); +} + +export function removeSampleSource() { + unregisterSourceModule("sample"); +} -- 2.43.0 From c3a07cee64f88393ce0565affe3f8ca68914ccd5 Mon Sep 17 00:00:00 2001 From: Lars Date: Mon, 19 Oct 2026 16:58:50 +0200 Subject: [PATCH 02/29] Stelle bestehende Quellzuordnungen wieder her und halte Connectoren beim eigenen Konto. Co-authored-by: Cursor --- backend/app/db/migrate.py | 4 + backend/app/present.py | 14 +- backend/app/sourcebind.py | 12 +- backend/tests/test_connector_basis.py | 206 ++++++++++++++++++ backend/tests/test_owner_sources.py | 10 + ...GU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md | 2 + frontend/src/pages/ReadingPane.jsx | 7 +- frontend/src/sources/registry.jsx | 4 +- 8 files changed, 250 insertions(+), 9 deletions(-) diff --git a/backend/app/db/migrate.py b/backend/app/db/migrate.py index 96b1025..fb805b4 100644 --- a/backend/app/db/migrate.py +++ b/backend/app/db/migrate.py @@ -58,7 +58,11 @@ def _prepare_source_storage(settings: Settings) -> None: from app.media.port import ensure_legacy_instance from app.sourcebind import backfill_source_bindings + from app.sources import _install_sources + # The process that migrates has not imported the application yet. + # Without the modules, a legacy reference would stay unresolved. + _install_sources() with psycopg.connect(settings.dsn(), row_factory=dict_row) as conn: backfill_source_bindings(conn) ensure_legacy_instance(conn, settings.media_root) diff --git a/backend/app/present.py b/backend/app/present.py index 2fda1e5..4e8a7ec 100644 --- a/backend/app/present.py +++ b/backend/app/present.py @@ -218,12 +218,20 @@ def _element_body(conn, actor: UUID, element: dict) -> dict: if revealed: external["external_id"] = ref["external_id"] payload["external"] = external + from app.sourcebind import resolve_for_read from app.sourceregistry import get_source - if resolution in {"ambiguous", "unresolved"} and get_source(ref["source"]) is not None: - payload["preview"] = {"available": False, "media": "unassigned", "source": ref["source"]} - else: + module = get_source(ref["source"]) + if module is None: payload["preview"] = _preview_meta("external_ref", None, ref["source"]) + else: + resolved = resolve_for_read(conn, element["owner_subject_id"], ref["source"], ref, None) + if resolved.code == "ok": + payload["preview"] = _preview_meta("external_ref", None, ref["source"]) + elif actor == element["owner_subject_id"]: + payload["preview"] = {"available": False, "media": "unassigned", "source": ref["source"]} + else: + payload["preview"] = {"available": False, "media": "none", "source": ref["source"]} return payload diff --git a/backend/app/sourcebind.py b/backend/app/sourcebind.py index 85c18e3..f61ee52 100644 --- a/backend/app/sourcebind.py +++ b/backend/app/sourcebind.py @@ -146,7 +146,15 @@ def attach_new_reference(conn, element_id: UUID) -> None: def backfill_source_bindings(conn) -> None: - """Idempotent. Bound and ambiguous rows stay. Unique unresolved stock is bound once.""" + """Idempotent. Unique stock is bound once. A stored id is never retargeted. + + Startup calls this before the application has imported the connector + modules. Register them first, otherwise every existing reference stays + unresolved and the case or matter can no longer open its originals. + """ + from app.sources import _install_sources + + _install_sources() conn.execute( """ UPDATE external_references @@ -160,7 +168,7 @@ def backfill_source_bindings(conn) -> None: FROM external_references er JOIN elements e ON e.id = er.element_id WHERE er.source <> 'url' - AND er.resolution = 'unresolved' + AND er.resolution IN ('unresolved', 'ambiguous') AND er.connector_id IS NULL """ ).fetchall() diff --git a/backend/tests/test_connector_basis.py b/backend/tests/test_connector_basis.py index cadec3d..e145875 100644 --- a/backend/tests/test_connector_basis.py +++ b/backend/tests/test_connector_basis.py @@ -243,6 +243,9 @@ def test_ambiguous_legacy_stays_until_assignment(client, db, monkeypatch): db.commit() assert state["resolution"] == "ambiguous" assert state["connector_id"] is None + opened = ada.request("GET", f"/api/v1/cases/{case['id']}") + assert opened["bindings"][0]["element"]["id"] == loose + assert opened["bindings"][0]["element"]["preview"]["media"] == "unassigned" blocked = _raw(ada, f"/api/v1/external-refs/{loose}/content") assert blocked.status_code == 422 assert "eindeutiger Zugang" in blocked.json()["detail"] @@ -261,6 +264,100 @@ def test_ambiguous_legacy_stays_until_assignment(client, db, monkeypatch): assert _raw(ada, f"/api/v1/external-refs/{loose}/content").content.startswith(b"%PDF-token-beta") +def test_legacy_stock_rebinds_and_case_and_matter_open(client, db, monkeypatch): + from app.sourceregistry import get_source, unregister_source + + register(db, "ada-keep@example.test", "Ada Keep") + ada = Actor(client, "ada-keep@example.test", "Ada Keep") + ada.login() + case = _case(ada) + matter = ada.request("POST", "/api/v1/matters", json={"title": "Bestand"}, status=201) + kept = _paperless(ada, "Archiv", "token-kept") + case_ref = _link(ada, case["id"], None, "15", "Vertragsakte") + matter_ref = ada.request( + "POST", + "/api/v1/external-refs", + json={ + "title": "Vertragsvorgang", + "source": "paperless", + "external_id": "16", + "context": {"kind": "matter", "id": matter["id"]}, + }, + status=201, + )["id"] + db.execute( + """ + UPDATE external_references + SET connector_id = NULL, resolution = 'unresolved', detail = '{}'::jsonb + WHERE element_id IN (%s, %s) + """, + (case_ref, matter_ref), + ) + db.commit() + unregister_source("paperless") + unregister_source("imap") + assert get_source("paperless") is None + try: + backfill_source_bindings(db) + db.commit() + for element_id in (case_ref, matter_ref): + state = db.execute( + "SELECT connector_id::text AS connector_id, resolution FROM external_references WHERE element_id = %s", + (element_id,), + ).fetchone() + assert state["resolution"] == "bound" + assert state["connector_id"] == kept + assert get_source("paperless") is not None + case_page = ada.request("GET", f"/api/v1/cases/{case['id']}") + matter_page = ada.request("GET", f"/api/v1/matters/{matter['id']}") + assert case_page["bindings"][0]["element"]["preview"]["available"] is True + assert case_page["bindings"][0]["element"]["preview"]["media"] == "pdf" + assert matter_page["bindings"][0]["element"]["preview"]["available"] is True + monkeypatch.setattr( + "app.sources._paperless_bytes", + lambda row, document_id: (f"%PDF-{row['secret']}-{document_id}\n".encode(), "application/pdf", "dokument.pdf"), + ) + assert _raw(ada, f"/api/v1/external-refs/{case_ref}/content").content.startswith(b"%PDF-token-kept-15") + assert _raw(ada, f"/api/v1/external-refs/{matter_ref}/content").content.startswith(b"%PDF-token-kept-16") + finally: + from app.sources import _install_sources + + _install_sources() + + +def test_connectors_remain_with_their_account(client, db, monkeypatch): + calls = [] + monkeypatch.setattr( + "app.sources._paperless_get", + lambda *args, **kwargs: calls.append(args) or {"results": []}, + ) + register(db, "ada-own@example.test", "Ada Own") + register(db, "ben-own@example.test", "Ben Own") + ada = Actor(client, "ada-own@example.test", "Ada Own") + ben = Actor(client, "ben-own@example.test", "Ben Own") + ada.login() + ada_paper = _paperless(ada, "Ada Archiv", "token-ada") + ben.login() + ben_paper = _paperless(ben, "Ben Archiv", "token-ben") + listed = ben.request("GET", "/api/v1/connectors") + ids = {item["id"] for item in listed["items"]} + assert ben_paper in ids + assert ada_paper not in ids + assert all(item["name"] != "Ada Archiv" for item in listed["items"]) + ben.request("POST", f"/api/v1/connectors/{ada_paper}/probe", status=404) + ben.request( + "GET", + "/api/v1/sources/paperless/documents", + params={"q": "fremd", "connector_id": ada_paper}, + status=404, + ) + assert calls == [] + ada.login() + own = {item["id"] for item in ada.request("GET", "/api/v1/connectors")["items"]} + assert ada_paper in own + assert ben_paper not in own + + def test_locked_profile_serves_metadata_not_cleartext(client, db): register(db, "ada-lock@example.test", "Ada Lock") ada = Actor(client, "ada-lock@example.test", "Ada Lock") @@ -331,3 +428,112 @@ def test_credential_update_keeps_the_instance(client, db): paperless = next(item for item in caps["sources"] if item["kind"] == "paperless") assert paperless["search"]["query"] is True assert paperless["edit_content"] is False + + +def test_legacy_reference_stays_bound_and_foreign_connectors_stay_hidden(client, db, database, monkeypatch): + """A startup without loaded modules must still keep the one existing connection.""" + from app.db.migrate import _prepare_source_storage + from app.sourceregistry import unregister_source + from app.sources import _install_sources + + def fake_bytes(row, document_id): + del document_id + return f"%PDF-{row['secret']}\n".encode(), "application/pdf", "dokument.pdf" + + monkeypatch.setattr("app.sources._paperless_bytes", fake_bytes) + register(db, "ada-legacy@example.test", "Ada Legacy") + register(db, "ben-legacy@example.test", "Ben Legacy") + ada = Actor(client, "ada-legacy@example.test", "Ada Legacy") + ben = Actor(client, "ben-legacy@example.test", "Ben Legacy") + ada.login() + case = _case(ada) + matter = ada.request("POST", "/api/v1/matters", json={"title": "Altbestand"}, status=201) + connector = _paperless(ada, "Archiv", "token-legacy") + case_ref = _link(ada, case["id"], None, "15", "Akte") + matter_ref = ada.request( + "POST", + "/api/v1/external-refs", + json={ + "title": "Vorgang", + "source": "paperless", + "external_id": "16", + "context": {"kind": "matter", "id": matter["id"]}, + }, + status=201, + )["id"] + db.execute( + """ + UPDATE external_references + SET connector_id = NULL, resolution = 'unresolved', detail = '{}'::jsonb + WHERE element_id IN (%s, %s) + """, + (case_ref, matter_ref), + ) + db.commit() + + opened = ada.request("GET", f"/api/v1/cases/{case['id']}") + shown = next(item["element"] for item in opened["bindings"] if item["element"]["id"] == case_ref) + assert shown["preview"]["media"] == "pdf" + assert shown["preview"]["available"] is True + assert _raw(ada, f"/api/v1/external-refs/{case_ref}/content?context_kind=case&context_id={case['id']}").content.startswith( + b"%PDF-token-legacy" + ) + matter_view = ada.request("GET", f"/api/v1/matters/{matter['id']}") + matter_element = next(item["element"] for item in matter_view["bindings"] if item["element"]["id"] == matter_ref) + assert matter_element["preview"]["media"] == "pdf" + + unregister_source("paperless") + unregister_source("imap") + try: + _prepare_source_storage(database) + finally: + _install_sources() + state = db.execute( + "SELECT connector_id::text AS connector_id, resolution FROM external_references WHERE element_id = %s", + (case_ref,), + ).fetchone() + assert state["connector_id"] == connector + assert state["resolution"] == "bound" + + ben.login() + own = _paperless(ben, "Bens Archiv", "token-ben") + listed = {item["id"] for item in ben.request("GET", "/api/v1/connectors")["items"]} + assert listed == {own} + ben.request("POST", f"/api/v1/connectors/{connector}/probe", status=404) + ben.request( + "GET", + "/api/v1/sources/paperless/documents", + params={"q": "Alt", "connector_id": connector}, + status=404, + ) + ada.login() + ada.request( + "POST", + f"/api/v1/matters/{matter['id']}/grants", + json={"email": ben.email, "can_read": True, "can_edit": False, "can_share": False, "use_owner_sources": False}, + status=201, + ) + ben.login() + shared = ben.request("GET", f"/api/v1/matters/{matter['id']}") + shared_element = next(item["element"] for item in shared["bindings"] if item["element"]["id"] == matter_ref) + assert "connector_id" not in shared_element["external"]["detail"] + assert "external_id" not in shared_element["external"] + blocked = _raw( + ben, + f"/api/v1/external-refs/{matter_ref}/content?context_kind=matter&context_id={matter['id']}", + ) + assert blocked.status_code == 422 + ada.login() + ada.request( + "POST", + f"/api/v1/matters/{matter['id']}/grants", + json={"email": ben.email, "can_read": True, "can_edit": False, "can_share": False, "use_owner_sources": True}, + status=201, + ) + ben.login() + allowed = _raw( + ben, + f"/api/v1/external-refs/{matter_ref}/content?context_kind=matter&context_id={matter['id']}", + ) + assert allowed.status_code == 200 + assert allowed.content.startswith(b"%PDF-token-legacy") diff --git a/backend/tests/test_owner_sources.py b/backend/tests/test_owner_sources.py index 1f37837..3333195 100644 --- a/backend/tests/test_owner_sources.py +++ b/backend/tests/test_owner_sources.py @@ -294,6 +294,16 @@ def test_grantee_reads_linked_originals_only_through_the_owner(client, db, monke assert opened.headers["referrer-policy"] == "no-referrer" assert calls == [{"token": OWNER_TOKEN, "path": "/api/documents/15/preview/"}] assert GRANTEE_TOKEN not in json.dumps(calls) + own_connectors = {item["id"] for item in ben.request("GET", "/api/v1/connectors")["items"]} + assert paper not in own_connectors + assert mailbox not in own_connectors + ben.request("POST", f"/api/v1/connectors/{paper}/probe", status=404) + ben.request( + "GET", + "/api/v1/sources/paperless/documents", + params={"q": "Geheim", "connector_id": paper}, + status=404, + ) search = ben.request("GET", "/api/v1/sources/paperless/documents", params={"q": "Geheim"}) assert "Geheimes Archivdokument" not in json.dumps(search) assert all(item["token"] != OWNER_TOKEN for item in calls if "query" in item) diff --git a/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md b/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md index c1cf85b..305a364 100644 --- a/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md +++ b/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md @@ -4,6 +4,8 @@ Kein Push und kein Deployment. Die Suite lief gegen `tsumugu_local_test`: **71 Tests, Exitcode 0**. Der Produktionsbau des Frontends ist durchgelaufen. Paperless und IMAP sind in den Tests nachgebildet. Es gab keinen Abruf einer lebenden Anlage. +**Korrektur am selben Tag:** Der Start hat die Module noch nicht geladen. Bestehende Referenzen ohne gespeicherte Instanz blieben `unresolved`, Akte und Vorgang zeigten sie als nicht zugeordnet. Die Vorbereitung registriert die Module jetzt vor dem Abgleich. Ein eindeutiger Bestand wird gebunden und lässt sich wieder öffnen. Mehrere Zugänge ohne gespeicherte Instanz bleiben bewusst offen, die Akte selbst bleibt lesbar. Liste, Prüfung und Suche sehen nur Zugänge des angemeldeten Kontos. Ein freigegebener Vorgang nutzt den Zugang des Owners nur für die konkrete Referenz und nur mit `use_owner_sources`. Die Suite dazu: **74 Tests, Exitcode 0**. + ## Matrix | Kriterium | Nachweis | Ergebnis | diff --git a/frontend/src/pages/ReadingPane.jsx b/frontend/src/pages/ReadingPane.jsx index 516efd4..634247c 100644 --- a/frontend/src/pages/ReadingPane.jsx +++ b/frontend/src/pages/ReadingPane.jsx @@ -1,4 +1,5 @@ -import { useEffect, useRef, useState } from "react"; +import { useContext, useEffect, useRef, useState } from "react"; +import { SessionContext } from "../session.js"; import { documentToText, downloadMailPart, fetchExternal, fetchFile, fetchMailPart, markDirty, textToDocument, api } from "../api.js"; import { SourceAssignment, noteEditor, representationOf } from "../sources/registry.jsx"; import { ErrorNote } from "./widgets.jsx"; @@ -75,6 +76,8 @@ function Correspondence({ element, direction, onOpenRelated }) { export function ReadingPane({ binding, context, backLabel, onClose, onReload, canDetach, canDestroy, onOpenRelated }) { const element = binding?.element; + const { session } = useContext(SessionContext) || {}; + const ownsElement = Boolean(session?.account?.id && element?.owner_subject_id === session.account.id); const [error, setError] = useState(""); const [phase, setPhase] = useState("idle"); const [media, setMedia] = useState(""); @@ -606,7 +609,7 @@ export function ReadingPane({ binding, context, backLabel, onClose, onReload, ca ) : null} {!isMail && unassigned ? (
- +
) : null} {!isMail && !locked && !unassigned && phase === "loading" ?

Vorschau wird geladen …

: null} diff --git a/frontend/src/sources/registry.jsx b/frontend/src/sources/registry.jsx index 778eb52..e21d75f 100644 --- a/frontend/src/sources/registry.jsx +++ b/frontend/src/sources/registry.jsx @@ -153,7 +153,7 @@ export const editors = { markdown_file: { id: "markdown_file", available: false }, }; -export function SourceAssignment({ element, onAssigned }) { +export function SourceAssignment({ element, onAssigned, owner = false }) { const external = element?.external; const resolution = external?.resolution; const source = external?.source; @@ -161,7 +161,7 @@ export function SourceAssignment({ element, onAssigned }) { const [choice, setChoice] = useState(""); const [error, setError] = useState(""); const [pending, setPending] = useState(false); - const open = source && (resolution === "ambiguous" || resolution === "unresolved"); + const open = owner && source && (resolution === "ambiguous" || resolution === "unresolved"); useEffect(() => { if (!open || !external?.external_id) return undefined; -- 2.43.0 From 7e39fbb2bd1e0e256bf1c2c0e7649069cbcf256d Mon Sep 17 00:00:00 2001 From: Lars Date: Tue, 20 Oct 2026 07:34:14 +0200 Subject: [PATCH 03/29] =?UTF-8?q?Mache=20gro=C3=9Fe=20IMAP-F=C3=A4cher,=20?= =?UTF-8?q?die=20Paperless-Suche=20und=20die=20interne=20Markdown-Notiz=20?= =?UTF-8?q?=C3=BCber=20die=20gemeinsamen=20Schnittstellen=20benutzbar.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Cursor --- backend/app/api/deps.py | 12 +- backend/app/api/sources.py | 49 +- backend/app/correspondence.py | 10 +- backend/app/exporting.py | 4 +- backend/app/media/port.py | 50 +- backend/app/ops.py | 10 +- backend/app/sourceaccess.py | 138 + backend/app/sourceport.py | 22 +- backend/app/sourceregistry.py | 1 + backend/app/sources.py | 471 +- backend/tests/sample_source.py | 27 +- backend/tests/test_connector_basis.py | 16 +- backend/tests/test_connector_followup.py | 770 ++++ docs/README.md | 1 + ...GU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md | 33 +- ...P_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md | 141 + docs/product/TSUMUGU_PRODUCT_SPEC.md | 2 +- ...MUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md | 2 +- frontend/package-lock.json | 3937 ++++++++++++++++- frontend/package.json | 1 + frontend/src/api.js | 11 + frontend/src/markdown.jsx | 44 +- frontend/src/notes.jsx | 174 + frontend/src/pages/ReadingPane.jsx | 71 +- frontend/src/pages/Sources.jsx | 293 +- frontend/src/pages/content.jsx | 16 +- frontend/src/pages/widgets.jsx | 42 +- frontend/src/sources/registry.jsx | 11 +- frontend/src/styles.css | 14 + 29 files changed, 6053 insertions(+), 320 deletions(-) create mode 100644 backend/app/sourceaccess.py create mode 100644 backend/tests/test_connector_followup.py create mode 100644 docs/product/TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md create mode 100644 frontend/src/notes.jsx diff --git a/backend/app/api/deps.py b/backend/app/api/deps.py index dbf6482..47ccdf2 100644 --- a/backend/app/api/deps.py +++ b/backend/app/api/deps.py @@ -4,6 +4,14 @@ from __future__ import annotations from dataclasses import dataclass from pathlib import Path + + +def discard_stored(item) -> None: + discard = getattr(item, "discard", None) + if callable(discard): + discard() + return + Path(item).unlink(missing_ok=True) from uuid import UUID from fastapi import Depends, Request @@ -35,11 +43,11 @@ def get_conn(request: Request): yield conn conn.commit() for path in getattr(request.state, "delete_after_commit", []): - Path(path).unlink(missing_ok=True) + discard_stored(path) except Exception: conn.rollback() for path in getattr(request.state, "cleanup_files", []): - Path(path).unlink(missing_ok=True) + discard_stored(path) raise diff --git a/backend/app/api/sources.py b/backend/app/api/sources.py index 287baf8..ba464c7 100644 --- a/backend/app/api/sources.py +++ b/backend/app/api/sources.py @@ -16,6 +16,7 @@ from app.core.errors import not_found, unprocessable, unsupported from app.mailpack import parse_mail from app.media.storage import content_disposition from app.ops import create_external +from app.retrieval import RetrievalFailure from app.sourcebind import assign_reference from app.sourceport import capability_payload, with_capabilities from app.sourceregistry import get_source, require_source @@ -23,8 +24,8 @@ from app.sources import ( delete_connector, imap_preview, list_connectors, + paperless_content, probe, - read_linked_mail, save_connector, update_connector, ) @@ -158,7 +159,13 @@ def _opened_ref(conn, principal: Principal, element_id: UUID, context_kind: str def _complete_mail(conn, principal: Principal, element, context, ref): - raw = read_linked_mail(conn, principal.account_id, element, context, ref) + module = get_source(ref["source"]) if ref is not None else None + if module is None or module.representation != "email": + raise unprocessable("Das ist keine E-Mail.") + opened = module.open_original(conn, principal.account_id, element, context, ref) + if isinstance(opened, RetrievalFailure): + raise unprocessable(opened.message) + raw = opened[0] if isinstance(opened, tuple) else opened parsed = parse_mail(raw) if parsed.missing: names = ", ".join(parsed.missing[:5]) @@ -246,6 +253,34 @@ def search_paperless( ) +@router.get("/api/v1/sources/{kind}/facets") +def source_facets( + kind: str, + connector_id: UUID, + principal: Principal = Depends(get_principal), + conn: Connection = Depends(get_conn), +): + module = require_source(kind) + if module.facets is None: + raise unsupported("Diese Quelle hat keine Auswahllisten.") + return module.facets(conn, principal.account_id, connector_id) + + +@router.get("/api/v1/sources/paperless/documents/{document_id}/preview") +def preview_paperless_document( + document_id: str, + connector_id: UUID, + principal: Principal = Depends(get_principal), + conn: Connection = Depends(get_conn), +): + data, media, name = paperless_content(conn, principal.account_id, document_id, connector_id) + return Response( + content=data, + media_type=media, + headers={**_PRIVATE, "Content-Disposition": content_disposition(name).replace("attachment;", "inline;", 1)}, + ) + + @router.get("/api/v1/sources/imap/mailboxes") def list_mailboxes( connector_id: UUID, @@ -269,6 +304,7 @@ def search_mail( document_to: str = "", sort: str = "", cursor: str = "", + uidvalidity: int | None = None, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn), ): @@ -292,6 +328,7 @@ def search_mail( "sort": sort, "cursor": cursor, }, + uidvalidity, ) @@ -357,7 +394,7 @@ _SEARCH_FLAGS = { } -def _run_search(kind: str, conn, owner, query: str, connector_id: UUID | None, mailbox: str, before: int | None, filters: dict) -> dict: +def _run_search(kind: str, conn, owner, query: str, connector_id: UUID | None, mailbox: str, before: int | None, filters: dict, uidvalidity: int | None = None) -> dict: module = require_source(kind) search = module.capabilities["search"] refused = [name for name, value in filters.items() if str(value or "").strip() and not search.get(_SEARCH_FLAGS.get(name, name))] @@ -365,7 +402,11 @@ def _run_search(kind: str, conn, owner, query: str, connector_id: UUID | None, m refused.append("before") if refused: raise unsupported("Diese Suche unterstützt den Filter nicht: " + ", ".join(refused) + ".") - found = module.find(conn, owner, connector_id, query, {"mailbox": mailbox, "before": before}) + options = {"mailbox": mailbox, "before": before} + if uidvalidity is not None: + options["uidvalidity"] = uidvalidity + options.update({key: value for key, value in filters.items() if str(value or "").strip()}) + found = module.find(conn, owner, connector_id, query, options) bound = str(found.get("connector_id") or connector_id or "") return with_capabilities(kind, bound, found) diff --git a/backend/app/correspondence.py b/backend/app/correspondence.py index ae6dfd4..9e5ddfb 100644 --- a/backend/app/correspondence.py +++ b/backend/app/correspondence.py @@ -28,7 +28,7 @@ from app.access.policy import ( ) from app.core.errors import Problem, conflict, not_found, unprocessable from app.core.timeutil import dump_date, dump_dt -from app.media.port import LEGACY_PROFILE, LocalAdapter, instance_for_write, publish, read_clear_bytes, stored_path +from app.media.port import LEGACY_PROFILE, StoredHandle, adapter_for, instance_for_write, publish, read_clear_bytes, removal_for, stored_path from app.media.storage import display_filename, sha256 from app.retrieval import FilePayload, MailPayload, RetrievalFailure, load_external, load_file @@ -936,9 +936,9 @@ def _store_snapshot(conn, scope_id, actor, payload: FilePayload, media_root: str instance = instance_for_write(conn, media_root) object_key = f"dispatch/{snapshot_id}" content_revision = str(uuid4()) - adapter = LocalAdapter(instance["root_path"]) + adapter = adapter_for(instance) publish(adapter, object_key, payload.data) - cleanup.append(stored_path(conn, instance["id"], instance["generation"], object_key, media_root)) + cleanup.append(StoredHandle(adapter, object_key)) digest = sha256(payload.data) conn.execute( """ @@ -1005,8 +1005,8 @@ def _snapshot_disk(conn, snapshot_id: UUID, media_root: str) -> Path: (snapshot_id,), ).fetchone() if row is None: - return stored_path(conn, None, "legacy-local-1", f"dispatch/{snapshot_id}", media_root) - return stored_path( + return removal_for(conn, None, "legacy-local-1", f"dispatch/{snapshot_id}", media_root) + return removal_for( conn, row["storage_instance_id"], row["storage_generation"], diff --git a/backend/app/exporting.py b/backend/app/exporting.py index 0bcd680..904ebfa 100644 --- a/backend/app/exporting.py +++ b/backend/app/exporting.py @@ -496,8 +496,8 @@ def _note_text(conn, element_id: UUID) -> str: parts = [] for block in document.get("blocks") or []: if isinstance(block, dict): - text = str(block.get("text") or "").strip() - if text: + text = str(block.get("text") or "") + if text.strip(): parts.append(text) return "\n\n".join(parts) diff --git a/backend/app/media/port.py b/backend/app/media/port.py index eb0e030..47fd9a8 100644 --- a/backend/app/media/port.py +++ b/backend/app/media/port.py @@ -208,6 +208,47 @@ def instance_for_write(conn, media_root: str) -> dict: ).fetchone() +class StoredHandle: + """Rollback and delete go through the adapter that owns the bytes.""" + + def __init__(self, adapter: StoragePort, object_key: str): + self._adapter = adapter + self._key = object_key + + def discard(self) -> None: + self._adapter.delete(self._key) + + +_FACTORIES: dict[str, callable] = {} + + +def _local_factory(row: dict) -> StoragePort: + return LocalAdapter(row["root_path"]) + + +_FACTORIES["local"] = _local_factory + + +def adapter_for(row: dict) -> StoragePort: + factory = _FACTORIES.get(row["kind"]) + if factory is None or not row.get("root_path") and row["kind"] == "local": + raise storage_unavailable() + return factory(row) + + +def removal_for(conn, instance_id, generation: str | None, object_key: str, media_root: str) -> StoredHandle: + row = None + if instance_id is not None: + row = conn.execute( + "SELECT id, kind, generation, root_path FROM storage_instances WHERE id = %s", + (instance_id,), + ).fetchone() + if row is None: + root = resolve_root(conn, instance_id, generation, media_root) + return StoredHandle(LocalAdapter(root), object_key) + return StoredHandle(adapter_for(row), object_key) + + def resolve_root(conn, instance_id, generation: str | None, media_root: str) -> str: if instance_id is not None: row = conn.execute( @@ -236,7 +277,14 @@ def read_clear_bytes( expected_sha256: str | None, ) -> bytes: require_cleartext(protection_profile) - data = LocalAdapter(resolve_root(conn, instance_id, generation, media_root)).open(object_key) + row = None + if instance_id is not None: + row = conn.execute( + "SELECT id, kind, generation, root_path FROM storage_instances WHERE id = %s", + (instance_id,), + ).fetchone() + adapter = adapter_for(row) if row is not None else LocalAdapter(resolve_root(conn, instance_id, generation, media_root)) + data = adapter.open(object_key) if expected_sha256 and sha256(data) != expected_sha256: raise Problem( 422, diff --git a/backend/app/ops.py b/backend/app/ops.py index e0da156..417b502 100644 --- a/backend/app/ops.py +++ b/backend/app/ops.py @@ -35,8 +35,7 @@ from app.access.policy import ( from app.content.documents import clean_document from app.core.errors import forbidden, not_found, unprocessable, unsupported from app.core.timeutil import utcnow -from app.media.port import LEGACY_PROFILE, instance_for_write, publish, stored_path -from app.media.port import LocalAdapter +from app.media.port import LEGACY_PROFILE, StoredHandle, adapter_for, instance_for_write, publish, removal_for from app.media.storage import display_filename, sha256, sniff MAX_CHAPTER_DEPTH = 32 @@ -1034,10 +1033,9 @@ def create_file(conn, actor: UUID, scope_id: UUID, title: str, filename: str, da content_revision = str(uuid4()) instance = instance_for_write(conn, media_root) object_key = str(asset_id) - adapter = LocalAdapter(instance["root_path"]) + adapter = adapter_for(instance) publish(adapter, object_key, data) - path = stored_path(conn, instance["id"], instance["generation"], object_key, media_root) - rollback_files.append(path) + rollback_files.append(StoredHandle(adapter, object_key)) digest = sha256(data) conn.execute( """ @@ -1097,7 +1095,7 @@ def delete_element(conn, actor: UUID, element_id: UUID, expected: int, media_roo if asset is not None and asset["status"] == "active": conn.execute("UPDATE media_assets SET status = 'purging' WHERE id = %s", (asset["id"],)) delete_after.append( - stored_path( + removal_for( conn, asset["storage_instance_id"], asset["storage_generation"], diff --git a/backend/app/sourceaccess.py b/backend/app/sourceaccess.py new file mode 100644 index 0000000..a6de756 --- /dev/null +++ b/backend/app/sourceaccess.py @@ -0,0 +1,138 @@ +"""Rights stay in one place. A source module only fetches its own bytes.""" + +from __future__ import annotations + +from dataclasses import dataclass +from uuid import UUID + +import psycopg + +from app.access.policy import Ctx, audit, mediated_source_owner +from app.core.errors import Problem, not_found, unprocessable +from app.sourcebind import resolve_for_read + +ORIGINAL_UNAVAILABLE = "Das Original ist über die Freigabe nicht abrufbar." + + +@dataclass +class BorrowedOriginal: + row: dict + external_id: str + mediated: bool + actor_id: UUID + owner_id: UUID + element: dict + context: Ctx | None + kind: str + + +def release_for_external(conn) -> None: + """External calls must not sit inside an open domain transaction.""" + if conn.info.transaction_status != psycopg.pq.TransactionStatus.IDLE: + conn.commit() + + +def connector_owner(conn, connector_id: UUID | None) -> UUID | None: + if connector_id is None: + return None + row = conn.execute("SELECT owner_id FROM connectors WHERE id = %s", (connector_id,)).fetchone() + return row["owner_id"] if row else None + + +def assert_still_owned(conn, connector_id, owner_id: UUID) -> None: + row = conn.execute( + "SELECT id FROM connectors WHERE id = %s AND owner_id = %s", + (connector_id, owner_id), + ).fetchone() + if row is None: + raise not_found() + + +def audit_mediated(conn, actor_id: UUID, element: dict, context: Ctx | None, source: str, connector_id, outcome: str) -> None: + audit( + conn, + actor_id, + element["home_scope_id"], + "source_read_mediated", + "element", + element["id"], + context, + result="ok" if outcome == "ok" else "unavailable", + detail={ + "source": source, + "connector_id": str(connector_id) if connector_id else None, + "outcome": outcome, + }, + ) + if outcome != "ok": + conn.commit() + + +def _uuid(value) -> UUID | None: + if isinstance(value, UUID): + return value + try: + return UUID(str(value)) + except (TypeError, ValueError): + return None + + +def borrow_original(conn, actor_id: UUID, element: dict, context: Ctx | None, ref, kind: str) -> BorrowedOriginal: + """Resolve the owner's connector. A grantee never supplies another account's connector.""" + detail = (ref or {}).get("detail") or {} + external_id = str((ref or {}).get("external_id") or "") + stored = _uuid(detail.get("connector_id")) or _uuid((ref or {}).get("connector_id")) + stored_owner = connector_owner(conn, stored) + mediated = not (element["owner_subject_id"] == actor_id or stored_owner == actor_id) + if mediated: + owner_id = mediated_source_owner(conn, actor_id, element, context) + if owner_id is None: + raise unprocessable(ORIGINAL_UNAVAILABLE) + else: + owner_id = actor_id + result = resolve_for_read(conn, owner_id, kind, ref, None) + if result.row is None: + if mediated: + audit_mediated(conn, actor_id, element, context, kind, stored, "unavailable") + raise unprocessable(ORIGINAL_UNAVAILABLE) + raise unprocessable(result.message) + return BorrowedOriginal( + row=result.row, + external_id=external_id, + mediated=mediated, + actor_id=actor_id, + owner_id=owner_id, + element=element, + context=context, + kind=kind, + ) + + +def _recheck(conn, borrowed: BorrowedOriginal) -> None: + if borrowed.mediated: + owner_id = mediated_source_owner(conn, borrowed.actor_id, borrowed.element, borrowed.context) + if owner_id != borrowed.owner_id: + audit_mediated(conn, borrowed.actor_id, borrowed.element, borrowed.context, borrowed.kind, borrowed.row["id"], "unavailable") + raise unprocessable(ORIGINAL_UNAVAILABLE) + row = conn.execute("SELECT owner_id FROM connectors WHERE id = %s", (borrowed.row["id"],)).fetchone() + if row is None or row["owner_id"] != borrowed.owner_id: + if borrowed.mediated: + audit_mediated(conn, borrowed.actor_id, borrowed.element, borrowed.context, borrowed.kind, borrowed.row["id"], "unavailable") + raise unprocessable(ORIGINAL_UNAVAILABLE) + raise not_found() + + +def complete_borrow(conn, borrowed: BorrowedOriginal, fetch): + """Run the adapter fetch outside the open transaction, then check the grant again.""" + release_for_external(conn) + try: + value = fetch(borrowed.row) + except Problem: + if borrowed.mediated: + audit_mediated(conn, borrowed.actor_id, borrowed.element, borrowed.context, borrowed.kind, borrowed.row["id"], "unavailable") + raise unprocessable(ORIGINAL_UNAVAILABLE) from None + raise + _recheck(conn, borrowed) + if borrowed.mediated: + audit_mediated(conn, borrowed.actor_id, borrowed.element, borrowed.context, borrowed.kind, borrowed.row["id"], "ok") + return value diff --git a/backend/app/sourceport.py b/backend/app/sourceport.py index 01f19e0..b211f8e 100644 --- a/backend/app/sourceport.py +++ b/backend/app/sourceport.py @@ -1,7 +1,7 @@ """Declared source and editor capabilities. A common contract does not invent abilities the adapter does not have. -Search filters that are false stay unavailable until a later delivery. +A filter is offered only when that module implements it. """ from __future__ import annotations @@ -16,13 +16,13 @@ PAPERLESS_CAPABILITIES = { "edit_metadata": False, "search": { "query": True, - "title": False, - "correspondent": False, - "document_type": False, - "tags": False, - "document_range": False, - "sort": False, - "continuation": False, + "title": True, + "correspondent": True, + "document_type": True, + "tags": True, + "document_range": True, + "sort": True, + "continuation": True, }, } @@ -94,5 +94,9 @@ def with_capabilities(kind: str, connector_id: str, payload: dict) -> dict: body["connector_id"] = connector_id body["capabilities"] = spec body["unsupported"] = [name for name, enabled in spec["search"].items() if not enabled] - body["continuation"] = body.get("next_before") if spec["search"].get("continuation") else None + if spec["search"].get("continuation"): + body["continuation"] = body.get("next_before") if body.get("next_before") is not None else body.get("next_page") + else: + body["continuation"] = None + body["incomplete"] = bool(body.get("incomplete")) return body diff --git a/backend/app/sourceregistry.py b/backend/app/sourceregistry.py index 93e8d1e..1548f29 100644 --- a/backend/app/sourceregistry.py +++ b/backend/app/sourceregistry.py @@ -21,6 +21,7 @@ class SourceModule: export_original: Callable navigate: Callable | None = None preview: Callable | None = None + facets: Callable | None = None _MODULES: dict[str, SourceModule] = {} diff --git a/backend/app/sources.py b/backend/app/sources.py index 7552b88..886db00 100644 --- a/backend/app/sources.py +++ b/backend/app/sources.py @@ -18,12 +18,21 @@ from uuid import UUID from psycopg.types.json import Json -from app.access.policy import Ctx, audit, mediated_source_owner +from app.access.policy import Ctx from app.core.errors import Problem, not_found, unprocessable from app.core.settings import get_settings from app.mailpack import MailIdentityError, choose_message, identities_match, header_message_id from app.media.storage import sniff from app.sourcebind import resolve_for_read +from app.sourceaccess import ( + ORIGINAL_UNAVAILABLE, + assert_still_owned, + audit_mediated as _audit_mediated, + borrow_original, + complete_borrow, + connector_owner as _connector_owner, + release_for_external, +) from app.sourceport import CAPABILITIES from app.sourceregistry import SourceModule, get_source, register_source @@ -81,30 +90,109 @@ def probe(conn, owner_id: UUID, connector_id: UUID) -> dict: module = get_source(row["kind"]) if module is None: raise unprocessable("Diese Quelle ist nicht registriert.") - return module.probe(row) + release_for_external(conn) + result = module.probe(row) + assert_still_owned(conn, row["id"], owner_id) + return result -def paperless_documents(conn, owner_id: UUID, query: str, connector_id: UUID | None = None) -> tuple[list[dict], str]: +def _paperless_choice(value, label: str) -> str | None: + text = str(value or "").strip() + if not text: + return None + if not text.isdigit() or len(text) > 12: + raise unprocessable(f"{label} ist keine Auswahl dieser Instanz.") + return text + + +def _paperless_day(value, label: str) -> str | None: + text = str(value or "").strip() + if not text: + return None + if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", text): + raise unprocessable(f"{label} ist kein Datum.") + return text + + +def _paperless_params(query: str, options: dict | None) -> dict: + """Paperless-ngx document date is the created field, not the upload or modified time.""" + options = options or {} + params = {"page_size": "20"} + text = " ".join(str(query or "").split()) + if text: + params["query"] = text + title = " ".join(str(options.get("title") or "").split()) + if title: + params["title__icontains"] = title + correspondent = _paperless_choice(options.get("correspondent"), "Der Korrespondent") + if correspondent: + params["correspondent__id"] = correspondent + document_type = _paperless_choice(options.get("document_type"), "Der Dokumenttyp") + if document_type: + params["document_type__id"] = document_type + raw_tags = options.get("tag") or options.get("tags") or "" + if isinstance(raw_tags, (list, tuple)): + parts = [str(item) for item in raw_tags] + else: + parts = str(raw_tags).split(",") + tag_ids = [chosen for chosen in (_paperless_choice(part, "Ein Tag") for part in parts) if chosen] + if tag_ids: + params["tags__id__all"] = ",".join(tag_ids) + start = _paperless_day(options.get("document_from"), "Das Dokumentdatum von") + end = _paperless_day(options.get("document_to"), "Das Dokumentdatum bis") + if start and end and start > end: + raise unprocessable("Das Dokumentdatum von liegt nach dem Dokumentdatum bis.") + if start: + params["created__date__gte"] = start + if end: + params["created__date__lte"] = end + sort = str(options.get("sort") or "").strip() + if sort: + if sort not in {"created", "-created", "title", "-title", "score", "-score"}: + raise unprocessable("Diese Sortierung gibt es nicht.") + if sort in {"score", "-score"}: + if not text: + raise unprocessable("Die Relevanz gilt zusammen mit einem Suchtext.") + # Paperless-ngx 2.20.6 has no ordering field named score. A query without + # ordering is the relevance order of the full-text index. + else: + params["ordering"] = sort + cursor = str(options.get("cursor") or "").strip() + if cursor: + if not cursor.isdigit() or not 1 <= int(cursor) <= 10000: + raise unprocessable("Die Seite ist ungültig.") + params["page"] = cursor + return params + + +def _paperless_row(conn, owner_id: UUID, connector_id: UUID | None): if connector_id is not None: row = _owned(conn, owner_id, connector_id) if row["kind"] != "paperless": raise unprocessable("Das ist kein Paperless-Zugang.") - else: - rows = conn.execute( - """ - SELECT id, settings, secret FROM connectors - WHERE owner_id = %s AND kind = 'paperless' - ORDER BY name, id - """, - (owner_id,), - ).fetchall() - if not rows: - raise unprocessable("Paperless ist noch nicht verbunden. Lege die Quelle unter Quellen an.") - if len(rows) != 1: - raise unprocessable("Für Paperless ist mehr als ein Zugang vorhanden. Die Suche muss einen Zugang nennen.") - row = rows[0] + return row + rows = conn.execute( + """ + SELECT id, settings, secret FROM connectors + WHERE owner_id = %s AND kind = 'paperless' + ORDER BY name, id + """, + (owner_id,), + ).fetchall() + if not rows: + raise unprocessable("Paperless ist noch nicht verbunden. Lege die Quelle unter Quellen an.") + if len(rows) != 1: + raise unprocessable("Für Paperless ist mehr als ein Zugang vorhanden. Die Suche muss einen Zugang nennen.") + return rows[0] + + +def paperless_documents(conn, owner_id: UUID, query: str, connector_id: UUID | None = None, options: dict | None = None) -> dict: + row = _paperless_row(conn, owner_id, connector_id) base = row["settings"]["base_url"].rstrip("/") - payload = _paperless_get(base, row["secret"], "/api/documents/", {"query": query, "page_size": "20"}) + params = _paperless_params(query, options) + release_for_external(conn) + payload = _paperless_get(base, row["secret"], "/api/documents/", params) + assert_still_owned(conn, row["id"], owner_id) items = [] for doc in payload.get("results") or []: created = str(doc.get("created") or "")[:10] @@ -118,18 +206,56 @@ def paperless_documents(conn, owner_id: UUID, query: str, connector_id: UUID | N "open_url": f"{base}/documents/{doc.get('id')}/", } ) - return items, str(row["id"]) + page = int(params.get("page") or 1) + count = payload.get("count") + if isinstance(count, int): + next_page = str(page + 1) if page * 20 < count else None + else: + next_page = str(page + 1) if len(items) == 20 else None + return {"items": items, "connector_id": str(row["id"]), "next_page": next_page, "incomplete": False} + + +def paperless_facets(conn, owner_id: UUID, connector_id: UUID) -> dict: + row = _paperless_row(conn, owner_id, connector_id) + base = row["settings"]["base_url"].rstrip("/") + token = row["secret"] + release_for_external(conn) + body = { + "correspondents": _paperless_names(base, token, "/api/correspondents/"), + "document_types": _paperless_names(base, token, "/api/document_types/"), + "tags": _paperless_names(base, token, "/api/tags/"), + "tag_mode": "all", + } + assert_still_owned(conn, row["id"], owner_id) + return body + + +def _paperless_names(base: str, token: str, path: str) -> list[dict]: + found = [] + for page in range(1, 21): + payload = _paperless_get(base, token, path, {"page": str(page), "page_size": "100"}) + rows = payload.get("results") or [] + for item in rows: + if item.get("id") is None: + continue + found.append({"id": str(item["id"]), "name": str(item.get("name") or item["id"])[:200]}) + if len(rows) < 100: + break + return found def imap_mailboxes(conn, owner_id: UUID, connector_id: UUID) -> list[dict]: row = _owned(conn, owner_id, connector_id) if row["kind"] != "imap": raise unprocessable("Das ist kein E-Mail-Konto.") + release_for_external(conn) client = _imap_login(row["settings"], row["secret"]) try: - return _imap_mailboxes(client) + items = _imap_mailboxes(client) finally: _imap_logout(client) + assert_still_owned(conn, row["id"], owner_id) + return items def imap_messages( @@ -139,6 +265,7 @@ def imap_messages( query: str, mailbox: str, before: int | None, + uidvalidity: int | None = None, ) -> dict: row = _owned(conn, owner_id, connector_id) if row["kind"] != "imap": @@ -147,11 +274,14 @@ def imap_messages( raise unprocessable("Der Fachname ist ungültig.") if len(query) > 200: raise unprocessable("Die Suche ist zu lang.") + release_for_external(conn) client = _imap_login(row["settings"], row["secret"]) try: - return _imap_page(client, mailbox, query, before) + page = _imap_page(client, mailbox, query, before, uidvalidity) finally: _imap_logout(client) + assert_still_owned(conn, row["id"], owner_id) + return page def imap_preview(conn, owner_id: UUID, connector_id: UUID, mailbox: str, uid: int) -> dict: @@ -208,23 +338,11 @@ def _paperless_count(base: str, token: str) -> int: def paperless_content(conn, owner_id: UUID, document_id: str, connector_id: UUID | None = None) -> tuple[bytes, str, str]: if not document_id.isdigit() or len(document_id) > 12: raise unprocessable("Die Paperless-Nummer ist ungültig.") - if connector_id is not None: - row = _owned(conn, owner_id, connector_id) - if row["kind"] != "paperless": - raise unprocessable("Das ist kein Paperless-Zugang.") - else: - rows = conn.execute( - """ - SELECT id, settings, secret FROM connectors - WHERE owner_id = %s AND kind = 'paperless' - ORDER BY name, id - """, - (owner_id,), - ).fetchall() - if len(rows) != 1: - raise unprocessable("Für Paperless ist kein eindeutiger Zugang zugeordnet.") - row = rows[0] - return _paperless_bytes(row, document_id) + row = _paperless_row(conn, owner_id, connector_id) + release_for_external(conn) + fetched = _paperless_bytes(row, document_id) + assert_still_owned(conn, row["id"], owner_id) + return fetched def _paperless_bytes(row, document_id: str) -> tuple[bytes, str, str]: @@ -249,35 +367,18 @@ def _paperless_bytes(row, document_id: str) -> tuple[bytes, str, str]: raise unprocessable("Paperless stellt diese Datei nicht zum Ansehen bereit.") -ORIGINAL_UNAVAILABLE = "Das Original ist über die Freigabe nicht abrufbar." - - def read_linked_paperless(conn, actor_id: UUID, element: dict, context: Ctx | None, ref) -> tuple[bytes, str, str]: """The stored document. A grantee never uses a connector of their own account.""" - detail = (ref or {}).get("detail") or {} external_id = str((ref or {}).get("external_id") or "") + detail = (ref or {}).get("detail") or {} stored = _uuid(detail.get("connector_id")) or _uuid((ref or {}).get("connector_id")) - stored_owner = _connector_owner(conn, stored) - if element["owner_subject_id"] == actor_id or stored_owner == actor_id: - if not external_id.isdigit() or len(external_id) > 12: + owner_path = element["owner_subject_id"] == actor_id or _connector_owner(conn, stored) == actor_id + if not external_id.isdigit() or len(external_id) > 12: + if owner_path: raise unprocessable("Die Paperless-Nummer ist ungültig.") - result = resolve_for_read(conn, actor_id, "paperless", ref, None) - if result.row is None: - raise unprocessable(result.message) - return _paperless_bytes(result.row, external_id) - owner_id = mediated_source_owner(conn, actor_id, element, context) - if owner_id is None or not external_id.isdigit() or len(external_id) > 12: raise unprocessable(ORIGINAL_UNAVAILABLE) - result = resolve_for_read(conn, owner_id, "paperless", ref, None) - if result.row is None: - _audit_mediated(conn, actor_id, element, context, "paperless", stored, "unavailable") - raise unprocessable(ORIGINAL_UNAVAILABLE) - try: - data, media, name = _paperless_bytes(result.row, external_id) - except Problem: - _audit_mediated(conn, actor_id, element, context, "paperless", result.row["id"], "unavailable") - raise unprocessable(ORIGINAL_UNAVAILABLE) from None - _audit_mediated(conn, actor_id, element, context, "paperless", result.row["id"], "ok") + borrowed = borrow_original(conn, actor_id, element, context, ref, "paperless") + data, media, name = complete_borrow(conn, borrowed, lambda row: _paperless_bytes(row, external_id)) if external_id and external_id in (name or ""): name = "dokument.pdf" return data, media, name or "dokument.pdf" @@ -292,28 +393,18 @@ def read_linked_mail(conn, actor_id: UUID, element: dict, context: Ctx | None, r mailbox = str(detail.get("mailbox") or "").strip() uid = _mail_uid(detail.get("uid")) external_id = str(ref["external_id"]) - stored_owner = _connector_owner(conn, connector_id) - if element["owner_subject_id"] == actor_id or stored_owner == actor_id: - result = resolve_for_read(conn, actor_id, "imap", ref, None) - if result.row is None: - raise unprocessable(result.message) + owner_path = element["owner_subject_id"] == actor_id or _connector_owner(conn, connector_id) == actor_id + if owner_path: if not mailbox or uid is None: raise unprocessable("Für diese E-Mail fehlt die Zuordnung zu Fach und Nachricht.") - return load_imap_original(conn, actor_id, result.row["id"], mailbox, uid, external_id) - owner_id = mediated_source_owner(conn, actor_id, element, context) - if owner_id is None or connector_id is None or not mailbox or uid is None: + elif connector_id is None or not mailbox or uid is None: raise unprocessable(ORIGINAL_UNAVAILABLE) - result = resolve_for_read(conn, owner_id, "imap", ref, None) - if result.row is None: - _audit_mediated(conn, actor_id, element, context, "imap", connector_id, "unavailable") - raise unprocessable(ORIGINAL_UNAVAILABLE) - try: - raw = load_imap_original(conn, owner_id, result.row["id"], mailbox, uid, external_id) - except Problem: - _audit_mediated(conn, actor_id, element, context, "imap", result.row["id"], "unavailable") - raise unprocessable(ORIGINAL_UNAVAILABLE) from None - _audit_mediated(conn, actor_id, element, context, "imap", result.row["id"], "ok") - return raw + borrowed = borrow_original(conn, actor_id, element, context, ref, "imap") + + def fetch(row): + return load_imap_original(conn, borrowed.owner_id, row["id"], mailbox, uid, external_id) + + return complete_borrow(conn, borrowed, fetch) def _uuid(value) -> UUID | None: @@ -335,13 +426,6 @@ def _mail_uid(value) -> int | None: return None -def _connector_owner(conn, connector_id: UUID | None) -> UUID | None: - if connector_id is None: - return None - row = conn.execute("SELECT owner_id FROM connectors WHERE id = %s", (connector_id,)).fetchone() - return row["owner_id"] if row else None - - def _connector_for(conn, connector_id: UUID, owner_id: UUID, kind: str): return conn.execute( """ @@ -353,26 +437,6 @@ def _connector_for(conn, connector_id: UUID, owner_id: UUID, kind: str): ).fetchone() -def _audit_mediated(conn, actor_id: UUID, element: dict, context: Ctx | None, source: str, connector_id, outcome: str) -> None: - audit( - conn, - actor_id, - element["home_scope_id"], - "source_read_mediated", - "element", - element["id"], - context, - result="ok" if outcome == "ok" else "unavailable", - detail={ - "source": source, - "connector_id": str(connector_id) if connector_id else None, - "outcome": outcome, - }, - ) - if outcome != "ok": - conn.commit() - - def _paperless_file( base: str, token: str, @@ -534,6 +598,8 @@ def _imap_login(settings: dict, secret: str) -> imaplib.IMAP4: PAGE_SIZE = 30 +UID_WINDOW = 400 +UID_ROUNDS = 8 _LIST_LINE = re.compile( r'^\((?P[^)]*)\)\s+(?P"(?:\\.|[^"])*"|NIL)\s+(?P"(?:\\.|[^"])*"|\S+)\s*$' ) @@ -565,7 +631,96 @@ def _imap_mailboxes(client: imaplib.IMAP4) -> list[dict]: return items -def _imap_page(client: imaplib.IMAP4, mailbox: str, query: str, before: int | None) -> dict: +def _untagged_int(client: imaplib.IMAP4, name: str) -> int | None: + values = (getattr(client, "untagged_responses", None) or {}).get(name) or [] + if not values: + return None + raw = values[-1] + if isinstance(raw, bytes): + raw = raw.decode("ascii", "replace") + try: + return int(str(raw).strip()) + except ValueError: + return None + + +def _uids_from(data, low: int | None, high: int | None) -> list[int]: + if data is None or isinstance(data, (bytes, str)): + raise unprocessable("Das Postfach hat eine unbrauchbare Antwort geliefert.") + chunks = [] + for part in data: + if part is None: + continue + if isinstance(part, bytes): + chunks.append(part) + elif isinstance(part, str): + chunks.append(part.encode("utf-8")) + else: + raise unprocessable("Das Postfach hat eine unbrauchbare Antwort geliefert.") + found = [] + for piece in b" ".join(chunks).split(): + if not piece.isdigit(): + continue + uid = int(piece) + if low is not None and uid < low: + continue + if high is not None and uid > high: + continue + found.append(uid) + return found + + +def _uid_call(client: imaplib.IMAP4, *args): + try: + return client.uid(*args) + except imaplib.IMAP4.abort as exc: + raise unprocessable("Die Verbindung zum Postfach ist abgebrochen.") from exc + except TimeoutError as exc: + raise unprocessable("Das Postfach hat nicht rechtzeitig geantwortet.") from exc + except imaplib.IMAP4.error as exc: + raise unprocessable("Das Postfach kann diese Suche nicht ausführen. Blättere im Fach oder kürze den Suchtext.") from exc + + +def _search_status(status) -> None: + if status in {"NO", "BAD"}: + raise unprocessable("Das Postfach hat die Suche abgelehnt.") + if status != "OK": + raise unprocessable("Das Postfach hat eine unbrauchbare Antwort geliefert.") + + +def _uid_window(client: imaplib.IMAP4, query: str, low: int, high: int) -> list[int]: + needle = " ".join(query.split()) + uid_range = f"{low}:{high}" + if not needle: + status, data = _uid_call(client, "SEARCH", None, "UID", uid_range) + else: + quoted = '"' + needle.replace("\\", "\\\\").replace('"', '\\"') + '"' + if needle.isascii(): + status, data = _uid_call( + client, "SEARCH", None, "UID", uid_range, + "OR", "OR", "SUBJECT", quoted, "FROM", quoted, "TEXT", quoted, + ) + else: + encoded = quoted.encode("utf-8") + status, data = _uid_call( + client, "SEARCH", "CHARSET", "UTF-8", "UID", uid_range, + "OR", "OR", "SUBJECT", encoded, "FROM", encoded, "TEXT", encoded, + ) + _search_status(status) + return _uids_from(data, low, high) + + +def _highest_uid(client: imaplib.IMAP4) -> int: + uidnext = _untagged_int(client, "UIDNEXT") + if uidnext is not None: + return max(0, uidnext - 1) + status, data = _uid_call(client, "SEARCH", None, "UID", "*") + _search_status(status) + found = _uids_from(data, None, None) + return max(found) if found else 0 + + +def _imap_page(client: imaplib.IMAP4, mailbox: str, query: str, before: int | None, claimed_validity: int | None = None) -> dict: folders = _imap_mailboxes(client) chosen = mailbox or "INBOX" match = next((item for item in folders if item["name"] == chosen), None) @@ -573,38 +728,60 @@ def _imap_page(client: imaplib.IMAP4, mailbox: str, query: str, before: int | No raise unprocessable("Dieses Fach gibt es in dem Konto nicht.") try: status, _ = client.select(chosen, readonly=True) + except imaplib.IMAP4.abort as exc: + raise unprocessable("Die Verbindung zum Postfach ist abgebrochen.") from exc + except TimeoutError as exc: + raise unprocessable("Das Postfach hat nicht rechtzeitig geantwortet.") from exc except imaplib.IMAP4.error as exc: raise unprocessable("Dieses Fach lässt sich nicht öffnen.") from exc if status != "OK": raise unprocessable("Dieses Fach lässt sich nicht öffnen.") - status, data = _uid_search(client, query) - if status != "OK" or not data or not data[0]: - return {"mailbox": chosen, "items": [], "next_before": None} - uids = sorted(int(part) for part in data[0].split() if part.isdigit()) - if before is not None: - uids = [uid for uid in uids if uid < before] - page = uids[-PAGE_SIZE:] - next_before = page[0] if len(uids) > PAGE_SIZE else None - items = [] - for uid in reversed(page): - item = _fetch_header(client, uid, chosen) - if item is not None: - items.append(item) - return {"mailbox": chosen, "items": items, "next_before": next_before} - - -def _uid_search(client: imaplib.IMAP4, query: str): - needle = " ".join(query.split()) - if not needle: - return client.uid("SEARCH", None, "ALL") - quoted = '"' + needle.replace("\\", "\\\\").replace('"', '\\"') + '"' - try: - if needle.isascii(): - return client.uid("SEARCH", None, "OR", "SUBJECT", quoted, "FROM", quoted) - encoded = quoted.encode("utf-8") - return client.uid("SEARCH", "CHARSET", "UTF-8", "OR", "SUBJECT", encoded, "FROM", encoded) - except imaplib.IMAP4.error as exc: - raise unprocessable("Das Postfach kann diese Suche nicht ausführen. Blättere im Fach oder kürze den Suchtext.") from exc + validity = _untagged_int(client, "UIDVALIDITY") + restarted = False + if claimed_validity is not None and validity is not None and int(claimed_validity) != validity: + before = None + restarted = True + high = before - 1 if before is not None else _highest_uid(client) + collected = [] + attempts = 0 + failures = 0 + low = 1 + rounds = 0 + while high >= 1 and len(collected) < PAGE_SIZE and rounds < UID_ROUNDS: + low = max(1, high - UID_WINDOW + 1) + for uid in sorted(_uid_window(client, query, low, high), reverse=True): + if len(collected) >= PAGE_SIZE: + break + attempts += 1 + item = _fetch_header(client, uid, chosen) + if item is None: + failures += 1 + continue + collected.append(item) + rounds += 1 + if len(collected) >= PAGE_SIZE or low == 1: + break + high = low - 1 + if attempts and failures == attempts: + raise unprocessable("Die Nachrichtenköpfe dieses Fachs konnten nicht gelesen werden.") + incomplete = bool(collected) is False and low > 1 and high >= 1 and rounds >= UID_ROUNDS + if len(collected) < PAGE_SIZE and low > 1 and rounds >= UID_ROUNDS: + incomplete = True + oldest = collected[-1]["uid"] if collected else None + if len(collected) >= PAGE_SIZE and oldest and oldest > 1: + next_before = oldest + elif incomplete: + next_before = low + else: + next_before = None + return { + "mailbox": chosen, + "items": collected, + "next_before": next_before, + "incomplete": incomplete, + "restarted": restarted, + "uidvalidity": validity, + } def _check_mailbox(mailbox: str) -> None: @@ -1052,16 +1229,23 @@ def _imap_config(payload: dict) -> tuple[str, dict, str]: def _paperless_find(conn, owner_id: UUID, connector_id: UUID | None, query: str, options: dict) -> dict: - del options - items, bound = paperless_documents(conn, owner_id, query, connector_id) - return {"items": items, "connector_id": bound} + return paperless_documents(conn, owner_id, query, connector_id, options) def _imap_find(conn, owner_id: UUID, connector_id: UUID | None, query: str, options: dict) -> dict: if connector_id is None: raise unprocessable("Für dieses Postfach fehlt der Zugang.") before = options.get("before") - return imap_messages(conn, owner_id, connector_id, query, str(options.get("mailbox") or ""), before) + validity = options.get("uidvalidity") + return imap_messages( + conn, + owner_id, + connector_id, + query, + str(options.get("mailbox") or ""), + before, + int(validity) if validity else None, + ) def _export_paperless(conn, actor_id: UUID, external_id: str, detail: dict, assigned: UUID | None, ref): @@ -1133,11 +1317,15 @@ class _PaperlessAdapter: return {"ok": True, "detail": f"Paperless antwortet. {count} Dokumente sichtbar."} def search(self, conn, owner_id: UUID, query: str, connector_id: UUID | None): - return paperless_documents(conn, owner_id, query, connector_id) + found = paperless_documents(conn, owner_id, query, connector_id) + return found["items"], found["connector_id"] def find(self, conn, owner_id: UUID, connector_id: UUID | None, query: str, options: dict) -> dict: return _paperless_find(conn, owner_id, connector_id, query, options) + def facets(self, conn, owner_id: UUID, connector_id: UUID) -> dict: + return paperless_facets(conn, owner_id, connector_id) + class _ImapAdapter: kind = "imap" @@ -1174,6 +1362,7 @@ def _install_sources() -> None: export_original=_export_paperless, navigate=None, preview=None, + facets=paperless.facets, )) register_source(SourceModule( kind="imap", diff --git a/backend/tests/sample_source.py b/backend/tests/sample_source.py index bd725e4..e8a5bf3 100644 --- a/backend/tests/sample_source.py +++ b/backend/tests/sample_source.py @@ -7,12 +7,11 @@ from __future__ import annotations from uuid import UUID -from app.access.policy import mediated_source_owner from app.core.errors import not_found, unprocessable from app.retrieval import FilePayload, RetrievalFailure from app.sourcebind import resolve_for_read from app.sourceregistry import SourceModule, register_source, unregister_source -from app.sources import ORIGINAL_UNAVAILABLE, _audit_mediated, _connector_owner +from app.sourceaccess import borrow_original, complete_borrow KIND = "sample" @@ -88,28 +87,8 @@ def preview(conn, owner_id: UUID, connector_id: UUID, options: dict) -> dict: def open_original(conn, actor_id: UUID, element: dict, context, ref) -> tuple[bytes, str, str]: - external_id = str((ref or {}).get("external_id") or "") - stored = ref.get("connector_id") if ref else None - stored_owner = _connector_owner(conn, stored) - if element["owner_subject_id"] == actor_id or stored_owner == actor_id: - result = resolve_for_read(conn, actor_id, KIND, ref, None) - if result.row is None: - raise unprocessable(result.message) - return _bytes(result.row, external_id) - owner_id = mediated_source_owner(conn, actor_id, element, context) - if owner_id is None: - raise unprocessable(ORIGINAL_UNAVAILABLE) - result = resolve_for_read(conn, owner_id, KIND, ref, None) - if result.row is None: - _audit_mediated(conn, actor_id, element, context, KIND, stored, "unavailable") - raise unprocessable(ORIGINAL_UNAVAILABLE) - try: - data, media, name = _bytes(result.row, external_id) - except Exception: - _audit_mediated(conn, actor_id, element, context, KIND, result.row["id"], "unavailable") - raise unprocessable(ORIGINAL_UNAVAILABLE) from None - _audit_mediated(conn, actor_id, element, context, KIND, result.row["id"], "ok") - return data, media, name + borrowed = borrow_original(conn, actor_id, element, context, ref, KIND) + return complete_borrow(conn, borrowed, lambda row: _bytes(row, borrowed.external_id)) def export_original(conn, actor_id: UUID, external_id: str, detail: dict, assigned, ref): diff --git a/backend/tests/test_connector_basis.py b/backend/tests/test_connector_basis.py index e145875..be1b56f 100644 --- a/backend/tests/test_connector_basis.py +++ b/backend/tests/test_connector_basis.py @@ -207,16 +207,16 @@ def test_two_paperless_instances_stay_bound_when_order_changes(client, db, monke ) assert found["items"][0]["title"] == "Treffer" assert found["connector_id"] == older - assert found["capabilities"]["search"]["correspondent"] is False - assert "correspondent" in found["unsupported"] - filtered = ada.client.get( + assert found["capabilities"]["search"]["correspondent"] is True + assert "correspondent" not in found["unsupported"] + filtered = ada.request( + "GET", "/api/v1/sources/paperless/documents", - params={"q": "Treffer", "connector_id": older, "correspondent": "Haus"}, - headers=headers, + params={"q": "Treffer", "connector_id": older, "correspondent": "4"}, ) - assert filtered.status_code == 422 - assert filtered.json()["code"] == "unsupported" - assert "Haus" not in json.dumps(filtered.json()) + assert filtered["items"][0]["title"] == "Treffer" + assert calls[-1][3]["correspondent__id"] == "4" + assert calls[-1][3]["query"] == "Treffer" def test_ambiguous_legacy_stays_until_assignment(client, db, monkeypatch): diff --git a/backend/tests/test_connector_followup.py b/backend/tests/test_connector_followup.py new file mode 100644 index 0000000..c536e15 --- /dev/null +++ b/backend/tests/test_connector_followup.py @@ -0,0 +1,770 @@ +"""Follow-up checks for paging, filters, storage resolution and notes. + +IMAP and Paperless doubles stand in for the external servers. They do not +prove a live mailbox or a live Paperless instance. +""" + +from __future__ import annotations + +import io +import zipfile +from email.parser import BytesParser + +from app.media.port import MemoryAdapter +from app.sourceaccess import borrow_original, complete_borrow +from app.sourceregistry import SourceModule, unregister_source, register_source +from tests.support import ORIGIN, Actor, document, register + +PDF = b"%PDF-1.4\n1 0 obj<<>>endobj\ntrailer<<>>\n%%EOF\nM\n" +LETTER = ( + b"From: Ada \r\n" + b"To: Ben \r\n" + b"Subject: Brief\r\n" + b"Message-ID: \r\n" + b"MIME-Version: 1.0\r\n" + b'Content-Type: multipart/mixed; boundary="grenze"\r\n' + b"\r\n" + b"--grenze\r\n" + b"Content-Type: text/plain; charset=utf-8\r\n" + b"\r\n" + b"Hallo aus der zweiten Quelle.\r\n" + b"--grenze\r\n" + b"Content-Type: application/pdf\r\n" + b'Content-Disposition: attachment; filename="plan.pdf"\r\n' + b"\r\n" + b"%PDF-plan\r\n" + b"--grenze--\r\n" +) + + +def _headers(actor: Actor) -> dict: + return { + "Origin": ORIGIN, + "X-CSRF-Token": actor.csrf, + "X-Scope-Kind": actor.scope["kind"], + "X-Scope-Id": actor.scope["id"], + } + + +def _install_letterbox() -> None: + def parse_config(payload: dict): + name = str(payload.get("name") or "Briefkasten").strip() or "Briefkasten" + return name, {"catalog": "letters"}, "letter-secret" + + def probe(row): + return {"ok": True, "detail": "Der Briefkasten antwortet."} + + def find(conn, owner_id, connector_id, query, options): + del conn, owner_id, query, options + return {"items": [{"id": "", "title": "Brief"}], "connector_id": str(connector_id)} + + def open_original(conn, actor_id, element, context, ref): + borrowed = borrow_original(conn, actor_id, element, context, ref, "letterbox") + return complete_borrow(conn, borrowed, lambda row: (LETTER, "message/rfc822", "nachricht.eml")) + + def export_original(conn, actor_id, external_id, detail, assigned, ref): + del conn, actor_id, external_id, detail, assigned, ref + from app.retrieval import FilePayload + + return FilePayload("nachricht.eml", "message/rfc822", LETTER, "") + + register_source(SourceModule( + kind="letterbox", + label="Briefkasten", + representation="email", + capabilities={ + "kind": "letterbox", + "navigate": False, + "read_original": True, + "read_preview": False, + "read_attachment": True, + "edit_content": False, + "edit_metadata": False, + "search": {"query": True, "continuation": False}, + }, + parse_config=parse_config, + probe=probe, + find=find, + open_original=open_original, + export_original=export_original, + )) + + +class RangeIMAP: + searches: list = [] + validity = b"3" + uidnext = b"50001" + fail_headers = False + search_status = "OK" + parts = False + + def __init__(self, *args, **kwargs): + self.untagged_responses = {} + + def login(self, username, secret): + assert secret == "Postfach-Geheim" + return "OK", [b"logged"] + + def list(self): + return "OK", [b'(\\HasNoChildren) "/" "INBOX"'] + + def select(self, mailbox, readonly=False): + assert readonly is True + self.untagged_responses = {"UIDVALIDITY": [type(self).validity], "UIDNEXT": [type(self).uidnext]} + return "OK", [b"1"] + + def uid(self, command, *args): + if command == "SEARCH": + type(self).searches.append(args) + if type(self).search_status != "OK": + return type(self).search_status, [None] + if "*" in args and not any(isinstance(arg, str) and ":" in arg for arg in args): + return "OK", [b"50000"] + low, high = _range_of(args) + if type(self).parts and low <= 5 <= high: + return "OK", [b"4 5", b"3"] + needle = _needle(args) + if needle: + hit = 80 if low <= 80 <= high else None + if needle.startswith("=?") or "nderung" in needle or "Änderung" in needle: + hit = 80 if low <= 80 <= high else None + return ("OK", [str(hit).encode()]) if hit else ("OK", [b""]) + found = [str(uid).encode() for uid in range(low, high + 1)] + return "OK", [b" ".join(found)] + uid = int(args[0]) + if type(self).fail_headers: + return "NO", [None] + subject = "Seltener Treffer" if uid == 80 else f"Nachricht {uid}" + header = ( + f"From: Ada \r\nSubject: {subject}\r\n" + f"Date: Thu, 02 May 2024 08:00:00 +0000\r\n" + ).encode() + return "OK", [(b"body", header), b")"] + + def logout(self): + return "BYE", [b""] + + +def _range_of(args) -> tuple[int, int]: + for arg in args: + text = arg.decode() if isinstance(arg, bytes) else str(arg) + if ":" in text and text.replace(":", "").isdigit(): + low, high = text.split(":", 1) + return int(low), int(high) + raise AssertionError(args) + + +def _needle(args) -> str: + for arg in args: + text = arg.decode() if isinstance(arg, bytes) else str(arg) + if text.startswith('"') or "nderung" in text or "Änderung" in text: + return text + return "" + + +def _account(monkeypatch, actor: Actor, fake) -> str: + import app.sources as sources + + monkeypatch.setattr(sources.imaplib, "IMAP4_SSL", fake) + created = actor.request( + "POST", + "/api/v1/connectors", + json={ + "kind": "imap", + "name": "Kanzlei", + "host": "imap.example.test", + "port": 993, + "username": "ada@example.test", + "password": "Postfach-Geheim", + "security": "ssl", + }, + status=201, + ) + return created["id"] + + +def _spans(searches) -> list[int]: + spans = [] + for args in searches: + if any(arg == "*" for arg in args): + continue + low, high = _range_of(args) + spans.append(high - low + 1) + return spans + + +def test_large_folder_is_bounded_and_a_late_hit_is_not_empty(client, db, monkeypatch): + import app.sources as sources + + ada = Actor(client, "ada-range@example.test", "Ada Bereich") + register(db, ada.email, ada.name) + ada.login() + RangeIMAP.searches = [] + RangeIMAP.validity = b"3" + RangeIMAP.uidnext = b"50001" + RangeIMAP.fail_headers = False + RangeIMAP.search_status = "OK" + RangeIMAP.parts = False + account = _account(monkeypatch, ada, RangeIMAP) + first = ada.request("GET", "/api/v1/sources/imap/messages", params={"connector_id": account, "mailbox": "INBOX"}) + assert first["items"][0]["title"] == "Nachricht 50000" + assert len(first["items"]) == sources.PAGE_SIZE + assert first["incomplete"] is False + assert first["next_before"] is not None + assert _spans(RangeIMAP.searches) + assert max(_spans(RangeIMAP.searches)) <= sources.UID_WINDOW + assert all("ALL" not in args for args in RangeIMAP.searches) + RangeIMAP.searches = [] + page = first + seen = {item["uid"] for item in page["items"]} + hops = 0 + while 80 not in seen: + hops += 1 + assert hops < 40 + assert page["next_before"] or page["incomplete"] + page = ada.request( + "GET", + "/api/v1/sources/imap/messages", + params={"connector_id": account, "mailbox": "INBOX", "q": "Seltener", "before": page["next_before"]}, + ) + if not page["items"] and page["incomplete"]: + assert page["next_before"] + seen.update(item["uid"] for item in page["items"]) + assert any(item["title"] == "Seltener Treffer" for item in page["items"]) + assert max(_spans(RangeIMAP.searches)) <= sources.UID_WINDOW + + +def test_imap_errors_are_not_reported_as_an_empty_folder(client, db, monkeypatch): + ada = Actor(client, "ada-imap-state@example.test", "Ada Zustand") + register(db, ada.email, ada.name) + ada.login() + RangeIMAP.searches = [] + RangeIMAP.uidnext = b"1" + RangeIMAP.fail_headers = False + RangeIMAP.search_status = "OK" + RangeIMAP.parts = False + account = _account(monkeypatch, ada, RangeIMAP) + empty = ada.request("GET", "/api/v1/sources/imap/messages", params={"connector_id": account, "mailbox": "INBOX"}) + assert empty["items"] == [] + assert empty["incomplete"] is False + RangeIMAP.uidnext = b"31" + RangeIMAP.search_status = "NO" + refused = ada.request( + "GET", + "/api/v1/sources/imap/messages", + params={"connector_id": account, "mailbox": "INBOX"}, + status=422, + ) + assert "abgelehnt" in refused["detail"] + assert "leer" not in refused["detail"].casefold() + RangeIMAP.search_status = "OK" + RangeIMAP.fail_headers = True + failed = ada.request( + "GET", + "/api/v1/sources/imap/messages", + params={"connector_id": account, "mailbox": "INBOX"}, + status=422, + ) + assert "Nachrichtenköpfe" in failed["detail"] + assert "leer" not in failed["detail"].casefold() + + +def test_uidvalidity_change_restarts_and_split_responses_join(client, db, monkeypatch): + ada = Actor(client, "ada-validity@example.test", "Ada Geltung") + register(db, ada.email, ada.name) + ada.login() + RangeIMAP.searches = [] + RangeIMAP.validity = b"4" + RangeIMAP.uidnext = b"11" + RangeIMAP.fail_headers = False + RangeIMAP.search_status = "OK" + RangeIMAP.parts = False + account = _account(monkeypatch, ada, RangeIMAP) + first = ada.request("GET", "/api/v1/sources/imap/messages", params={"connector_id": account, "mailbox": "INBOX"}) + RangeIMAP.validity = b"9" + restarted = ada.request( + "GET", + "/api/v1/sources/imap/messages", + params={ + "connector_id": account, + "mailbox": "INBOX", + **({"before": first["next_before"]} if first["next_before"] else {}), + "uidvalidity": first["uidvalidity"], + }, + ) + assert restarted["restarted"] is True + assert restarted["items"][0]["title"] == "Nachricht 10" + RangeIMAP.validity = b"4" + RangeIMAP.parts = True + RangeIMAP.uidnext = b"6" + joined = ada.request("GET", "/api/v1/sources/imap/messages", params={"connector_id": account, "mailbox": "INBOX"}) + assert [item["uid"] for item in joined["items"]] == [5, 4, 3] + + +def test_paperless_filters_reach_the_api_and_cross_pages(client, db, monkeypatch): + import app.sources as sources + + calls = [] + + def fake_get(base, token, path, params): + calls.append({"path": path, "params": dict(params), "token": token}) + if path != "/api/documents/": + return {"count": 1, "results": [{"id": 4, "name": "Haus"}]} + page = int(params.get("page") or 1) + start = (page - 1) * 20 + return { + "count": 45, + "results": [ + {"id": number + 1, "title": f"Titel {number + 1}", "created": "2024-03-01"} + for number in range(start, min(start + 20, 45)) + ], + } + + def fake_bytes(row, document_id): + return f"%PDF-{row['secret']}-{document_id}\n".encode(), "application/pdf", "dokument.pdf" + + monkeypatch.setattr(sources, "_paperless_get", fake_get) + monkeypatch.setattr(sources, "_paperless_bytes", fake_bytes) + ada = Actor(client, "ada-filter@example.test", "Ada Filter") + register(db, ada.email, ada.name) + ada.login() + first = ada.request( + "POST", + "/api/v1/connectors", + json={"kind": "paperless", "name": "Archiv", "base_url": "https://paper.example.test", "token": "token-alpha"}, + status=201, + ) + second = ada.request( + "POST", + "/api/v1/connectors", + json={"kind": "paperless", "name": "Zweitarchiv", "base_url": "https://paper.example.test", "token": "token-bravo"}, + status=201, + ) + facets = ada.request("GET", "/api/v1/sources/paperless/facets", params={"connector_id": first["id"]}) + assert facets["tag_mode"] == "all" + assert facets["correspondents"] == [{"id": "4", "name": "Haus"}] + ada.request( + "GET", + "/api/v1/sources/paperless/documents", + params={"connector_id": first["id"], "document_from": "2024-05-02", "document_to": "2024-01-01"}, + status=422, + ) + found = ada.request( + "GET", + "/api/v1/sources/paperless/documents", + params={ + "connector_id": first["id"], + "q": "nurinhalt", + "title": "Vertrag", + "correspondent": "4", + "document_type": "8", + "tag": "2,5", + "document_from": "2024-01-01", + "document_to": "2024-12-31", + "sort": "-created", + "cursor": "3", + }, + ) + sent = calls[-1]["params"] + assert sent["query"] == "nurinhalt" + assert sent["title__icontains"] == "Vertrag" + assert sent["correspondent__id"] == "4" + assert sent["document_type__id"] == "8" + assert sent["tags__id__all"] == "2,5" + assert sent["created__date__gte"] == "2024-01-01" + assert sent["created__date__lte"] == "2024-12-31" + assert sent["ordering"] == "-created" + assert sent["page"] == "3" + ada.request( + "GET", + "/api/v1/sources/paperless/documents", + params={"connector_id": first["id"], "q": "nurinhalt", "sort": "-score"}, + ) + assert "ordering" not in calls[-1]["params"] + assert found["items"][0]["id"] == "41" + assert found["connector_id"] == first["id"] + preview = ada.client.get( + "/api/v1/sources/paperless/documents/41/preview", + params={"connector_id": first["id"]}, + headers=_headers(ada), + ) + assert preview.status_code == 200 + assert preview.content.startswith(b"%PDF-token-alpha-41") + matter = ada.request("POST", "/api/v1/matters", json={"title": "Suche"}, status=201) + linked = ada.request( + "POST", + "/api/v1/external-refs", + json={ + "title": "Seite drei", + "source": "paperless", + "external_id": "41", + "context": {"kind": "matter", "id": matter["id"]}, + "detail": {"connector_id": first["id"]}, + }, + status=201, + ) + other = ada.request( + "POST", + "/api/v1/external-refs", + json={ + "title": "Dieselbe Nummer", + "source": "paperless", + "external_id": "41", + "context": {"kind": "matter", "id": matter["id"]}, + "detail": {"connector_id": second["id"]}, + }, + status=201, + ) + opened = ada.client.get(f"/api/v1/external-refs/{linked['id']}/content", headers=_headers(ada)) + twin = ada.client.get(f"/api/v1/external-refs/{other['id']}/content", headers=_headers(ada)) + assert opened.content.startswith(b"%PDF-token-alpha-41") + assert twin.content.startswith(b"%PDF-token-bravo-41") + ben = Actor(client, "ben-filter@example.test", "Ben Filter") + register(db, ben.email, ben.name) + ben.login() + ben.request("GET", "/api/v1/sources/paperless/facets", params={"connector_id": first["id"]}, status=404) + ben.request( + "GET", + "/api/v1/sources/paperless/documents", + params={"connector_id": first["id"], "q": "nurinhalt"}, + status=404, + ) + + +def test_revoked_grant_hides_bytes_fetched_during_the_call(client, db, monkeypatch): + import app.sources as sources + + def fake_bytes(row, document_id): + db.execute("UPDATE access_grants SET can_read = false") + db.commit() + return b"%PDF-1.4\nsecret\n", "application/pdf", "geheim.pdf" + + monkeypatch.setattr(sources, "_paperless_bytes", fake_bytes) + ada = Actor(client, "ada-revoke@example.test", "Ada Widerruf") + ben = Actor(client, "ben-revoke@example.test", "Ben Widerruf") + register(db, ada.email, ada.name) + register(db, ben.email, ben.name) + ada.login() + paper = ada.request( + "POST", + "/api/v1/connectors", + json={"kind": "paperless", "name": "Archiv", "base_url": "https://paper.example.test", "token": "token-alpha"}, + status=201, + ) + matter = ada.request("POST", "/api/v1/matters", json={"title": "Freigabe"}, status=201) + linked = ada.request( + "POST", + "/api/v1/external-refs", + json={ + "title": "Vertrag", + "source": "paperless", + "external_id": "15", + "context": {"kind": "matter", "id": matter["id"]}, + "detail": {"connector_id": paper["id"]}, + }, + status=201, + ) + ada.request( + "POST", + f"/api/v1/matters/{matter['id']}/grants", + json={"email": ben.email, "can_read": True, "can_edit": False, "can_share": False, "use_owner_sources": True}, + status=201, + ) + ben.login() + hidden = ben.client.get( + f"/api/v1/external-refs/{linked['id']}/content", + params={"context_kind": "matter", "context_id": matter["id"]}, + headers=_headers(ben), + ) + assert hidden.status_code == 422 + assert b"secret" not in hidden.content + + +def test_email_representation_uses_the_mail_reader_without_imap(client, db): + ada = Actor(client, "ada-letter@example.test", "Ada Brief") + register(db, ada.email, ada.name) + ada.login() + _install_letterbox() + try: + box = ada.request("POST", "/api/v1/connectors", json={"kind": "letterbox", "name": "Briefe"}, status=201) + matter = ada.request("POST", "/api/v1/matters", json={"title": "Post"}, status=201) + linked = ada.request( + "POST", + "/api/v1/external-refs", + json={ + "title": "Brief", + "source": "letterbox", + "external_id": "", + "context": {"kind": "matter", "id": matter["id"]}, + "detail": {"connector_id": box["id"]}, + }, + status=201, + ) + mail = ada.request("GET", f"/api/v1/external-refs/{linked['id']}/mail") + assert mail["attachments"][0]["filename"] == "plan.pdf" + attachment = ada.client.get( + f"/api/v1/external-refs/{linked['id']}/mail/attachments/0", + headers=_headers(ada), + ) + assert attachment.status_code == 200 + assert attachment.content.startswith(b"%PDF-plan") + raw = ada.client.get(f"/api/v1/external-refs/{linked['id']}/mail/original", headers=_headers(ada)) + parsed = BytesParser().parsebytes(raw.content) + assert parsed.get("subject") == "Brief" + finally: + unregister_source("letterbox") + + +def test_domain_storage_uses_the_resolved_adapter(client, db, monkeypatch): + import app.media.port as port + + memory = MemoryAdapter() + monkeypatch.setitem(port._FACTORIES, "local", lambda row: memory) + ada = Actor(client, "ada-store@example.test", "Ada Speicher") + register(db, ada.email, ada.name) + ada.login() + matter = ada.request("POST", "/api/v1/matters", json={"title": "Ablage"}, status=201) + ctx = {"kind": "matter", "id": matter["id"]} + note = ada.request( + "POST", + "/api/v1/notes", + json={"title": "Schreiben", "document": document("Text"), "context": ctx}, + status=201, + ) + uploaded = ada.request( + "POST", + "/api/v1/files", + data={"title": "Plan", "context_kind": "matter", "context_id": matter["id"], "document_on": "2024-01-02"}, + files={"upload": ("plan.pdf", PDF, "application/pdf")}, + status=201, + ) + detail = ada.request("GET", f"/api/v1/matters/{matter['id']}") + host = next(item for item in detail["bindings"] if item["element"]["id"] == note["id"]) + ada.request( + "POST", + f"/api/v1/elements/{note['id']}/attachments", + json={ + "expected_version": host["element"]["version"], + "context": ctx, + "attachment_element_ids": [uploaded["id"]], + "fold": "attachment", + }, + status=201, + ) + folded = ada.request("GET", f"/api/v1/matters/{matter['id']}") + host = next(item for item in folded["bindings"] if item["element"]["id"] == note["id"]) + dispatch = ada.request( + "POST", + f"/api/v1/elements/{note['id']}/dispatches", + json={ + "expected_version": host["element"]["version"], + "context": ctx, + "channel": "post", + "sent_on": "2024-02-02", + "attachment_element_ids": [uploaded["id"]], + "capture_editions": True, + }, + status=201, + ) + content = ada.client.get(f"/api/v1/files/{uploaded['id']}/content", headers=_headers(ada)) + assert content.content == PDF + item = next(entry for entry in dispatch["items"] if entry["element_id"] == uploaded["id"]) + snapshot = ada.client.get( + f"/api/v1/dispatches/{dispatch['id']}/items/{item['id']}/content", + params={"context_kind": "matter", "context_id": matter["id"]}, + headers=_headers(ada), + ) + assert snapshot.content == PDF + asset = db.execute( + "SELECT object_key, storage_generation, sha256 FROM media_assets WHERE element_id = %s", + (uploaded["id"],), + ).fetchone() + assert memory.open(asset["object_key"]) == PDF + tree = ada.request("GET", f"/api/v1/matters/{matter['id']}/export-tree")["tree"] + selected = [ + node["id"] + for node in _walk(tree) + if node.get("exportable") and node.get("kind") in {"binding", "attachment", "dispatch_item"} + ] + package = ada.client.post( + f"/api/v1/matters/{matter['id']}/export", + json={"context": ctx, "selected": selected}, + headers={**_headers(ada), "Content-Type": "application/json"}, + ) + assert package.status_code == 200, package.text + archive = zipfile.ZipFile(io.BytesIO(package.content)) + assert any(archive.read(name) == PDF for name in archive.namelist()) + version = next( + item["element"]["version"] + for item in ada.request("GET", f"/api/v1/matters/{matter['id']}")["bindings"] + if item["element"]["id"] == uploaded["id"] + ) + ada.request( + "POST", + f"/api/v1/elements/{uploaded['id']}/delete", + json={"expected_version": version}, + status=204, + ) + try: + memory.open(asset["object_key"]) + except Exception: + removed = True + else: + removed = False + assert removed is True + assert asset["storage_generation"] + + +def test_note_markdown_is_shared_exported_and_kept_on_conflict(client, db): + ada = Actor(client, "ada-note-md@example.test", "Ada Notiz") + ben = Actor(client, "ben-note-md@example.test", "Ben Notiz") + register(db, ada.email, ada.name) + register(db, ben.email, ben.name) + ada.login() + left = ada.request("POST", "/api/v1/matters", json={"title": "Links"}, status=201) + right = ada.request("POST", "/api/v1/matters", json={"title": "Rechts"}, status=201) + body = "\n".join([ + "# Überschrift", + "", + "Ein **fetter** und *kursiver* Satz.", + "", + "- erster", + "- zweiter", + "", + "> Zitat", + "", + "Siehe [Quelle](https://example.test/hinweis).", + "", + "`code`", + "", + "```", + "block", + "```", + "", + "", + "", + "![bild](https://example.test/bild.png)", + ]) + created = ada.request( + "POST", + "/api/v1/notes", + json={ + "title": "Merkzettel", + "document": {"version": 1, "blocks": [{"type": "markdown", "text": body}]}, + "context": {"kind": "matter", "id": left["id"]}, + }, + status=201, + ) + ada.request( + "POST", + "/api/v1/bindings", + json={ + "element_id": created["id"], + "source_context": {"kind": "matter", "id": left["id"]}, + "target": {"kind": "matter", "id": right["id"]}, + }, + status=201, + ) + detail = ada.request("GET", f"/api/v1/matters/{left['id']}") + element = next(item["element"] for item in detail["bindings"] if item["element"]["id"] == created["id"]) + changed = "Geändert in beiden Vorgängen.\n\n" + body + ada.request( + "PATCH", + f"/api/v1/notes/{created['id']}", + json={ + "expected_version": element["version"], + "document": {"version": 1, "blocks": [{"type": "markdown", "text": changed}]}, + "context": {"kind": "matter", "id": right["id"]}, + }, + ) + again = ada.request("GET", f"/api/v1/matters/{left['id']}") + shared = next(item["element"] for item in again["bindings"] if item["element"]["id"] == created["id"]) + assert changed in _text(shared) + ada.request( + "POST", + f"/api/v1/bindings/{next(item['id'] for item in again['bindings'] if item['element']['id'] == created['id'])}/annotations", + json={"body": "Nur links"}, + params={"context_kind": "matter", "context_id": left["id"]}, + status=201, + ) + left_detail = ada.request("GET", f"/api/v1/matters/{left['id']}") + right_detail = ada.request("GET", f"/api/v1/matters/{right['id']}") + left_binding = next(item for item in left_detail["bindings"] if item["element"]["id"] == created["id"]) + right_binding = next(item for item in right_detail["bindings"] if item["element"]["id"] == created["id"]) + assert any(note["body"] == "Nur links" for note in left_binding["annotations"]) + assert all(note["body"] != "Nur links" for note in right_binding["annotations"]) + ada.request( + "POST", + f"/api/v1/matters/{left['id']}/grants", + json={"email": ben.email, "can_read": True, "can_edit": False, "can_share": False}, + status=201, + ) + ben.login() + ben.request( + "PATCH", + f"/api/v1/notes/{created['id']}", + json={ + "expected_version": shared["version"], + "document": {"version": 1, "blocks": [{"type": "markdown", "text": "fremd"}]}, + "context": {"kind": "matter", "id": left["id"]}, + }, + status=403, + ) + ada.login() + current = next( + item["element"]["version"] + for item in ada.request("GET", f"/api/v1/matters/{left['id']}")["bindings"] + if item["element"]["id"] == created["id"] + ) + conflict = ada.request( + "PATCH", + f"/api/v1/notes/{created['id']}", + json={ + "expected_version": current - 1, + "document": {"version": 1, "blocks": [{"type": "markdown", "text": "darf nicht überschreiben"}]}, + "context": {"kind": "matter", "id": left["id"]}, + }, + status=409, + ) + assert conflict["code"] == "conflict" + stored = next( + item["element"] + for item in ada.request("GET", f"/api/v1/matters/{left['id']}")["bindings"] + if item["element"]["id"] == created["id"] + ) + assert "darf nicht überschreiben" not in _text(stored) + assert "" in _text(stored) + tree = ada.request("GET", f"/api/v1/matters/{left['id']}/export-tree")["tree"] + selected = [node["id"] for node in _walk(tree) if node.get("kind") == "binding" and node.get("exportable")] + package = ada.client.post( + f"/api/v1/matters/{left['id']}/export", + json={"context": {"kind": "matter", "id": left["id"]}, "selected": selected}, + headers={**_headers(ada), "Content-Type": "application/json"}, + ) + assert package.status_code == 200, package.text + archive = zipfile.ZipFile(io.BytesIO(package.content)) + exported = "\n".join( + archive.read(name).decode("utf-8", errors="replace") + for name in archive.namelist() + if name.endswith((".md", ".txt")) + ) + assert "```" in exported + assert "" in exported + assert "https://example.test/bild.png" in exported + + +def _text(element: dict) -> str: + return "\n".join(block.get("text") or "" for block in (element.get("document") or {}).get("blocks") or []) + + +def _walk(node): + if isinstance(node, dict) and "kind" in node: + yield node + for child in node.get("children") or []: + yield from _walk(child) + elif isinstance(node, dict): + for value in node.values(): + yield from _walk(value) + elif isinstance(node, list): + for item in node: + yield from _walk(item) diff --git a/docs/README.md b/docs/README.md index 7b64ac1..ab22634 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,6 +30,7 @@ | [TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md](product/TSUMUGU_CONNECTOR_UMBAU_AUFTRAG_2026-10-19.md) | begrenzter Umsetzungsauftrag, Abschnitt A beauftragt, Abschnitt B der nächste Ausbau | 19.10.2026 | | [TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md](product/TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md) | Abschlusskriterien der Kapselung; Vorrang vor einem teilweise integrierten Zwischenstand | 19.10.2026 | | [TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md](product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md) | Kriterium, Nachweis und Ergebnis der Kapselung | 19.10.2026 | +| [TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md](product/TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md) | Nacharbeit: IMAP-Seiten, Paperless-Suche, Markdown-Notiz | 19.10.2026 | | [TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md](product/TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md) | früherer Zwischenstand von Abschnitt A vor den Abschlusskriterien | 19.10.2026 | | [TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md](product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md) | Einstieg für die fachliche Weiterplanung | 17.10.2026 | | [TECHNICAL_SPEC_HANDOFF.md](product/TECHNICAL_SPEC_HANDOFF.md) | historischer Auftrag zur technischen Spezifikation | 16.10.2026 | diff --git a/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md b/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md index 305a364..15f7fd4 100644 --- a/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md +++ b/docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md @@ -43,6 +43,35 @@ Ein produktiver Connector folgt demselben Schnitt: - Historische Migrationen, Testdoubles und die Dokumentation. - Der Paperless-Dateizugriff auf ein lokales Archiv bleibt im Connector-Modul. Eigene Uploads und Versandfassungen schreiben über den Storage-Port. Die Anfrage räumt danach nur Pfade ab, die der Adapter selbst veröffentlicht hat. Die Fixture-Bereinigung löscht Bestandsdateien an derselben Objektkennung. -## Grenzen +## Grenzen vor der Nacharbeit -Die Anfrage-Transaktion umfasst weiterhin den Quellabruf und das lokale Schreiben. Zugangsdaten liegen als Klartext in `connectors.secret`. Es gibt keine neue Verschlüsselung, keine erweiterte Paperless-Suche, keinen Markdown-Dateieditor und keinen Remote-Speicher. Der Testadapter ist kein produktiver Dienst. Lebende Paperless- und IMAP-Anlagen wurden nicht geprüft. +Dieser Absatz beschreibt den Stand vor der Nacharbeit am selben Tag. Die Anfrage-Transaktion umfasste damals noch den Quellabruf. Zugangsdaten liegen als Klartext in `connectors.secret`. Es gibt keine neue Verschlüsselung und keinen Remote-Speicher. Der Testadapter ist kein produktiver Dienst. + +## Nacharbeit am 19.10.2026 + +Auftrag: [TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md](TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md). Die historische Suite oben bleibt unverändert. Die neue Suite `tests` lief danach mit **82 Tests, Exitcode 0**. Der Paperless-Filtertest wurde nach der Relevanzzuordnung einzeln erneut ausgeführt und ist grün. Der Frontend-Build ist durchgelaufen. Kein Push und kein Deployment. + +IMAP, Paperless-Treffer und der Speicheradapter in `test_connector_followup.py` sind nachgebildet. Das ist kein lebender Postfach- oder Dokumentabruf. Die laufende Paperless-Instanz `paperless-webserver-1` wurde nur am Schema gelesen: Paperless-ngx **2.20.6**. `query` ist die Volltextsuche, `title__icontains` das eigene Titelfeld, `tags__id__all` die Und-Verknüpfung, `created` das Dokumentdatum neben `added` und `modified`. `score` ist kein Sortierfeld. Eine Suche ohne `ordering` ist dort die Relevanzreihenfolge. Dokumentinhalte wurden nicht gelesen. + +| Paket | Nachweis | Ergebnis | +|---|---|---| +| A Gemeinsamer Zugriff, Darstellung, Speicher | `sourceaccess.py`, Briefkasten-Test ohne IMAP, Speicherstest über `adapter_for` | Bestanden in der nachgebildeten Suite. Upload, erneutes Lesen, Versandfassung, Export und Löschen laufen über die aufgelöste Instanz. Fehlende Instanzzeile bleibt der bisherige lokale Pfad. | +| B IMAP-Seiten | `test_large_folder_is_bounded_and_a_late_hit_is_not_empty`, Fehler- und UIDVALIDITY-Tests | Bestanden gegen den nachgebildeten Server. Ein Fach mit Lücken bleibt seitenweise begrenzt. Ein Treffer hinter der ersten Seite ist kein leeres Fach. NO, abgebrochene Köpfe und ein UIDVALIDITY-Wechsel sind eigene Zustände. Ein lebendes Postfach wurde nicht geprüft. | +| C Paperless-Suche | Filtertest und Schema 2.20.6 | Bestanden gegen den nachgebildeten Abruf und das gelesene Schema. Inhalt, Titel, Korrespondent, Typ, mehrere Tags, Dokumentdatum, Seite 3 und zwei Instanzen derselben Dokumentnummer sind getrennt. Eine Suche in den echten Dokumenten steht aus. | +| D Markdown-Notiz | Notiztest und Browser am lokalen Testkonto | Bestanden für gemeinsamen Text, Export, Leserecht und Konflikt. Die formatierte Bearbeitung mit `@mdxeditor/editor` 3.52.4, MIT, ist im Browser geöffnet worden: Leiste, Quelltextumschaltung, gespeicherte Ansicht, Abbrechen. Ein Listenstrich und ein Stern gelten beim Öffnen als dieselbe Liste. Jede andere Abweichung bleibt im Quelltext. `markdown_file` bleibt aus. | + +## Anleitung für ein weiteres Modul + +Ein Quellenmodul registriert sich mit `register_source` und liefert nur Fähigkeiten, die es ausführt. Die Oberfläche ruft `registerSourceModule` auf und ersetzt die Registrierung nicht. Eine bekannte Darstellung wird mit `registerRepresentation` gebunden; die Notiz nutzt `markdown` → `note` und erscheint nicht unter Quellen. Ein Speicheradapter kommt in die Fabrik von `adapter_for` und wird über die gespeicherte Instanz aufgelöst. Ein Editor hängt an derselben Ressourcenansicht. Fachseiten, Rechte und das Schema zählen die Art nicht auf. + +## Weiterhin zulässige Quellkenntnis + +- Protokoll, Konfiguration, Suche und Auswahl von Paperless und IMAP in `backend/app/sources.py` und `frontend/src/pages/Sources.jsx`. +- Die Kompatibilitätsrouten delegieren an dieselben Dienste. +- Die Darstellung `email` öffnet das registrierte Modul und danach den gemeinsamen Mail-Leser. +- Stammdaten, Seitenzahl und Vorschau bleiben an Instanz und Recht gebunden. +- Historische Migrationen, Testdoubles und diese Dokumentation. + +## Laufzeit und Erweiterbarkeit + +Der Netzwerkabruf wird vor dem externen Aufruf aus der offenen Fachtransaktion gelöst und danach auf Recht und Instanz geprüft. Große IMAP-Fächer lesen begrenzte UID-Fenster, nicht die gesamte Liste je Seite. Paperless-Seiten sind die eigene Seitennummer, keine weitergereichte Fortsetzungsadresse. Die Erweiterung um eine Quelle, eine Darstellung oder einen Editor braucht kein neues Rechtsschema. Eine neue Speicherart braucht eine Fabrik und bleibt an die gespeicherte Instanz gebunden. Es gibt keine zusätzliche Verschlüsselung und keinen weiteren Produkt-Speicher. diff --git a/docs/product/TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md b/docs/product/TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md new file mode 100644 index 0000000..a994d3e --- /dev/null +++ b/docs/product/TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md @@ -0,0 +1,141 @@ +# Cursor-Auftrag: Connector-Kapselung abschließen, IMAP und Paperless verbessern, Markdown-Notizen bearbeiten + +**Stand:** 19.10.2026 +**Zielort:** `C:/Dev/tsumugu/docs/product/TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md` +**Status:** Umsetzungsauftrag nach Übergabe an Cursor, bis zur lokalen Prüfung. Dieses Dokument selbst ändert keine Anwendung. Kein Push und kein Deployment. + +## 1. Ziel und Verbindlichkeit + +Arbeite im vorhandenen Repository `C:/Dev/tsumugu`. Erhalte laufende Änderungen, Bestandsdaten, bestätigte Fachentscheidungen und die ausgewählte Gestaltung. Liefere ein funktionierendes System mit standardisiert erweiterbaren Connectoren und den drei konkret benötigten Verbesserungen. Eine Registrierung neben weiter bestehenden Sonderwegen genügt nicht. + +Lies gezielt: + +1. `AGENTS.md` und die einschlägigen Abschnitte der aktuellen `docs/product/TSUMUGU_PRODUCT_SPEC.md`, insbesondere gemeinsamer Notizinhalt, kontextbezogene Rechte, Quellen und Export. +2. `docs/product/TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md` und die aktuelle Abschlussmatrix. Die Matrix ist eine zu prüfende Ergebnisbehauptung, keine Ausnahme von den Anforderungen. +3. `docs/architecture/TSUMUGU_CONNECTOR_STORAGE_VERTRAG_v0.1_2026-10-19.md` und die Connector Suite v0.2 im selben Verzeichnis; ergänzend den bisherigen Umbauauftrag für bestehende Schnittstellen und Abnahme. +4. Die betroffenen Architekturregeln und Blueprints unter **`docs/reference/`**, insbesondere Auth/Session/Scope, Medien/Dateien/sicheres Rendering und die Regeln zu kurzen Transaktionen in der Referenzarchitektur. Der Verzeichnisname ist `reference`, nicht `references`. Lokale Kopien verwenden; alte absolute Pfade in diesen Dokumenten sind kein Auftrag zur Änderung anderer Produkte. + +Dieser Auftrag startet die hier beschriebene erweiterte Paperless-Suche ausdrücklich. Er erweitert die bisher zurückgestellte Notizbedienung. Er startet keine bidirektionale Paperless-Synchronisation und keine allgemeine MD-Dateischreibfunktion. Frühere gegenteilige Umfangsgrenzen sind nur für diese ausdrücklich genannten Funktionen überholt. Keine erneute vollständige Produktspezifikation oder Repositoryinventur. + +## 2. Befund und gewünschtes Verhalten unterscheiden + +**Nutzerbeobachtungen:** Große IMAP-Ordner erscheinen leer; auch einschränkende Suche liefert dort nichts. Die Paperless-Suche wirkt wie reine Titelsuche und bietet keine weiteren Eingrenzungen. Notizen sollen nach dem Speichern formatiert lesbar sein; gewünscht ist ein echter Markdown-Editor, bevorzugt auch direkte Bearbeitung in der formatierten Ansicht mit Schaltern. + +**Gezielte Codebefunde vor Übergabe, erneut am tatsächlichen Arbeitsstand prüfen:** + +- `backend/app/sources.py::_imap_page` ruft eine ordnerweite UID-Suche auf, wertet nur `data[0]` aus und liefert auch bei `status != OK` eine leere Trefferliste. `_fetch_header` verwirft einzelne Abruffehler still. Das belegt problematische Fehlerbehandlung; die konkrete Ursache im betroffenen Ordner ist noch nicht nachgewiesen. +- `paperless_documents` sendet bereits `query` an `/api/documents/`, begrenzt auf 20 Ergebnisse und reicht keine Fortsetzung weiter. Daraus folgt **kein** Beweis einer technisch ausschließlich auf Titel beschränkten Suche. `_paperless_find` verwirft zusätzliche Optionen; der allgemeine Suchaufruf reicht Filter nicht vollständig weiter. +- `MarkdownEditor` ist derzeit ein Textfeld mit einfacher Vorschau. Der Reader bleibt auch nach dem Speichern im Bearbeitungsformular. `frontend/src/markdown.jsx` enthält einen begrenzten selbstgebauten Renderer. +- Der dritte Source-Test belegt Backend-Aufrufe und eine Frontend-Registrierung, aber keinen vollständigen Bedienablauf. Der zweite Storage-Adapter wird isoliert geprüft; die Anwendung erzeugt an mehreren Stellen weiterhin direkt `LocalAdapter`. + +Reproduziere Fehler vor der Behebung und kennzeichne Vermutungen als solche. Kein Bericht darf aus synthetischen Tests einen erfolgreichen Abruf der echten Nutzerquelle ableiten. + +## 3. A – Kapselung tatsächlich abschließen + +### Quellen, Rechte und Inhaltszugriff + +- Protokoll, Konfiguration, Suchoptionen, Navigation, Ressourcenauflösung, Mapping und Fehlerübersetzung gehören zum registrierten Connector-Modul. Quellspezifische Formulare und Filter gehören zu dessen UI-Modul. Gemeinsame Seiten setzen diese Module zusammen. +- Ein gemeinsamer Zugriffsdienst verantwortet Tsumugu-Identität, Datenraum, Kontextrechte, konkrete Quellinstanz und erlaubte Owner-Vermittlung. Ein neuer Adapter darf diese Freigabe- und Auditabläufe nicht kopieren müssen. Quellseitige zusätzliche Einschränkungen bleiben beim Adapter. Bestehende Rechte werden nicht erweitert. +- Quelle und Darstellung trennen: Eine Quelle, die E-Mail-Originale bereitstellt, muss den vorhandenen Mail-Leser einschließlich Anlagen nutzen können. `_complete_mail` darf nicht direkt auf einen ausschließlich IMAP-fähigen Zugriff festgelegt bleiben. Analog PDF, Bild und Text über autorisierten Ressourcenabruf führen. +- Leser und Editoren als registrierte Komponenten mit gemeinsamem Lebenszyklus anbinden. Neue Darstellungen dürfen eigene registrierte Bausteine benötigen, ohne Änderungen in Akten-/Vorgangsseiten oder Exportsteuerung. Eine Funktion, die nur feste Darstellungsnamen umbenennt, ist noch keine solche Registrierung. +- Typisierte, vom jeweiligen Modul validierte Optionen und Ressourcenkennungen vollständig durchreichen. Keine dauerhafte zentrale Liste aller providerspezifischen Suchfelder. Bestehende Standardfelder können gemeinsame Verträge bleiben. Kompatibilitätsrouten delegieren an dieselben Dienste; keine zweite aktive Fachlogik. +- Neue Module werden an einem ausdrücklichen Einstieg registriert. Eine Fachseite darf nicht beim Import die bereits gefüllte Registry löschen und neu mit zwei festen Quellen belegen. + +### Storage und Transaktionen + +- Den tatsächlichen Adapter anhand der gespeicherten Storage-Instanz über eine gemeinsame Auflösung beziehen. Uploads, Lesen, Löschen, Rollback-Bereinigung und Versandfassungen verwenden diesen Zugang. Direkte Konstruktion von `LocalAdapter` in Fachoperationen beseitigen; lokale Pfade gehören zum lokalen Adapter. +- Den vorhandenen Testadapter durch diese echte Zugriffsstrecke prüfen, nicht nur seine Methoden nebeneinander aufrufen. Kein zusätzlicher produktiver Cloud-/NAS-Dienst erforderlich. Bestandsreferenzen, Generationen und Inhaltsrevisionen erhalten. +- Externe Abrufe und größere Dateioperationen aus offenen Fachtransaktionen lösen. Autorisierten Abruf vorbereiten, externe Arbeit ausführen, vor Veröffentlichung beziehungsweise endgültiger Ausgabe erforderliche Rechte und Versionen erneut prüfen. DB und Ablage nicht als gemeinsame atomare Transaktion behandeln; Fehler und Bereinigung nach dem bestehenden Vertrag abwickeln. +- Nicht unterstützte Schutzprofile bleiben gesperrt. Keine neue Verschlüsselung in diesem Auftrag. + +## 4. B – IMAP: große Ordner korrekt anzeigen und durchsuchen + +**Ergebnis:** Ein großer, befüllter Ordner ist durchblätterbar. Eine Suche erfasst den gesamten gewählten Ordner, auch Treffer außerhalb der ersten Seite. Leer, keine Treffer, unvollständiger Abruf und Fehler sind unterschiedliche Zustände. + +1. Ursache mit aussagekräftigen, inhaltsarmen Diagnosen eingrenzen: Ordnerauswahl, Anzahl/UID-Bereich soweit verfügbar, Suchstatus, Antwortumfang und -form, Timeout/Protokollfehler und Headerabruf. Keine Zugangsdaten, Nachrichtentexte oder vollständigen privaten Header protokollieren. +2. Erfolgreiche leere Suche von `NO`, `BAD`, Verbindungsabbruch, Timeout und ungültiger Antwort unterscheiden. Bei Fehlern keine Meldung „Ordner leer“ oder „keine Treffer“ ausgeben. Stille Fehler beim Headerabruf dürfen einen befüllten Ordner nicht scheinbar leeren. +3. Ordnernavigation und Suche für große UID-Bestände begrenzen und seitenweise verarbeiten. Nicht bei jedem Blättern beliebig große vollständige UID-Listen übertragen und sortieren. Geeignete Serverfähigkeiten nutzen; eine kompatible, begrenzte Strategie für Server ohne zusätzliche Sucherweiterungen erhalten. Nicht pauschal globale Bibliothekslimits erhöhen oder Timeouts unbegrenzt verlängern. +4. Suchkriterien serverseitig auf den ganzen Ordner anwenden beziehungsweise bei begrenzter Bereichssuche nachweisbar vollständig fortsetzen. Ein nicht untersuchter Rest darf nicht als endgültig trefferlos gelten. Eine Antwort enthält eine Fortsetzung oder einen erkennbaren unvollständigen Zustand, wenn die Suche noch nicht abgeschlossen ist. +5. Cursor an Zugang, Ordner, Suchanfrage und nötigen Identitätsstand binden; UID-Lücken, entfernte Nachrichten und UIDVALIDITY-Wechsel sicher behandeln. Bei wechselndem Bestand keine unbemerkte Verwechslung mit einer anderen Nachricht. +6. Antwortzeiten und Zahl externer Aufrufe für den Regressionstest dokumentieren. Nur Metadaten für die aktuelle Seite laden; vollständige Nachrichten und Anlagen erst auf Anforderung. Nur lesender Zugriff, keine Veränderung des Gelesen-Status. +7. Bei schnellem Ordner-/Suchwechsel dürfen verspätete Antworten nicht die neue Ansicht überschreiben. Auswahl und Zielkontext bleiben korrekt. Fremde oder entzogene Zugänge bleiben geschützt. + +## 5. C – Paperless: brauchbare Suche mit Eingrenzungen + +**Ergebnis:** Dokumente lassen sich über ihren Inhalt finden und über sichtbare fachliche Filter eingrenzen. Die Suche funktioniert auch jenseits der ersten Ergebnisseite. + +Liefern: + +- Freitextsuche mit klarer Beschriftung für Titel und Dokumentinhalt sowie ein getrenntes Titelfeld zur zusätzlichen Eingrenzung. Inhaltsbegriffe, die nicht im Titel stehen, müssen im passenden Testbestand Treffer liefern. +- Korrespondent und Dokumenttyp als Auswahl anhand der am konkreten Zugang sichtbaren Stammdaten; Tags als Mehrfachauswahl. Für mehrere Tags eine klar erkennbare Verknüpfung anbieten, mindestens „alle ausgewählten Tags“. Keine still wechselnde UND-/ODER-Semantik. +- Dokumentdatum von/bis, mit sichtbarer Bedeutung; nicht ungefragt Upload-/Änderungsdatum verwenden. Leere Grenzen zulassen, ungültige Bereiche verständlich ablehnen. +- Sortierung mindestens nach Dokumentdatum und Titel, auf-/absteigend; Relevanz anbieten, soweit die eingesetzte API dies für die gewählte Suche unterstützt. Stabile Fortsetzung berücksichtigen. +- Weitere Ergebnisseiten, aktiven Filterzustand, Zurücksetzen und Vorschau vor Übernahme. Bereits bewusst gewählte Dokumente bei Seiten-/Suchwechsel erhalten und sichtbar machen; Auswahl nach Instanz und Ressourcen-ID führen. + +Suchtext und verschiedene Filter werden gemeinsam angewendet. Filterdaten bleiben im zuständigen Connector. Der gemeinsame Dienst darf validierte Filter nicht nach der Prüfung verwerfen. Fähigkeiten erst aktiv ausweisen, wenn die Operation ausführbar ist. Nicht unterstützte Parameter dürfen nicht still ignoriert werden. + +Die konkret eingesetzte Paperless-Version und deren API-Schema prüfen. Moderne Dokumentation ist keine Zusage über eine ältere Nutzerinstanz. Kein eigener Volltextindex und keine lokale Nachfilterung lediglich der ersten 20 Treffer. Von der API gelieferte Fortsetzungsadressen nur innerhalb der vertrauenswürdigen Instanz verwenden; keine Credential-Weitergabe an fremde Hosts. Instanz- und Rechtebindung gilt auch für Stammdaten, Zähler und Vorschau. + +Die generelle Sucherweiterung ist beauftragt. Individuelle Finanzfelder, benutzerdefinierte Feldabfragen und Metadatenänderungen sind hier kein zusätzlicher Pflichtumfang. + +## 6. D – Notizen: Markdown bearbeiten, anschließend formatiert lesen + +### Fachliche Einordnung und Pflichtverhalten + +Eine interne Notiz muss nicht als externe Quelle unter „Quellen“ erscheinen. Benötigt werden ein registrierter interner Notiz-Zugriff und ein wiederverwendbarer Markdown-Leser/Editor über die gemeinsame Ressourcen-/Editor-Schnittstelle. Notizen behalten ihre vorhandene Identität und Speicherung; sie werden nicht automatisch zu Dateien oder pro Einbindung kopiert. Eine spätere MD-Datei kann denselben Editor mit einem anderen Speicheradapter nutzen; das Schreiben externer MD-Dateien ist jetzt nicht beauftragt. + +- **Öffnen:** Gespeicherte Notizen zunächst gerendert anzeigen. Bei Bearbeitungsrecht gibt es „Bearbeiten“; bei reinem Leserecht keinen aktiven Editor. Das gilt auch beim erneuten Öffnen und für bestehende Notizen. +- **Bearbeiten:** Eine klar erkennbare Bearbeitungsansicht mit Formatierungsleiste und Markdown-Quelltextmodus. Entwurf, Auswahl und Inhalt beim Moduswechsel erhalten. +- **Speichern:** Nach erfolgreichem Speichern in die gerenderte Leseansicht wechseln und den tatsächlich gespeicherten Stand zeigen. Bei Fehlern im Editor bleiben. „Abbrechen“ stellt den gespeicherten Stand wieder her. Navigation mit ungesicherten Änderungen bewusst behandeln. +- **Inhalt:** Markdown bleibt die maßgebliche Darstellung. Kein HTML als unbemerkter Ersatz. Vorhandene Dokumenthüllen kompatibel adaptieren; eine neue DB-Struktur nur bei belegter Notwendigkeit und ohne Inhaltsverlust. Export gibt vollständiges Markdown aus. +- **Umfang:** Überschriften, fett, kursiv, Listen, Links, Zitate, Inline-Code und Codeblöcke konsistent lesen und bearbeiten. Formatierungsschalter haben zugängliche Namen und sichtbaren Zustand. Bestehende Inhalte außerhalb des visuell unterstützten Umfangs unverändert erhalten und nötigenfalls im Quelltextmodus bearbeiten; keine verlustbehaftete Konvertierung. +- **Rechte und Konflikte:** Gemeinsamer Notizinhalt bleibt in allen Einbindungen derselbe, lokale Anmerkungen bleiben lokal. Kontextbezogene Rechte und optimistische Versionsprüfung erhalten. Bei `409` bleibt der Entwurf erhalten; kein stilles Überschreiben und kein bloßes Neuladen mit Textverlust. +- **Rendering:** Sicheren Markdown-Parser/Renderer verwenden oder den vorhandenen Mechanismus belastbar ersetzen. Rohes HTML, Skripte und gefährliche Linkprotokolle nicht ausführen. Externe Medien nicht automatisch nachladen. Keine Notizinhalte an einen externen Editordienst senden. + +### Bevorzugtes Ziel: direkt formatiert bearbeiten + +Der Nutzer wünscht idealerweise Bearbeitung direkt in der formatierten Ansicht mit Formatierungsschaltern. Setze das bevorzugt mit einer geeigneten, lokal eingebundenen und gepflegten Editor-Komponente um; Quelltext bleibt umschaltbar. Kein eigener Rich-Text-Editor auf Basis unkontrollierter DOM-/HTML-Konvertierung und keine breite Bibliotheksstudie. Eine kurze begründete Komponentenwahl genügt; aktuelle Version, Markdown-Roundtrip und Lizenz prüfen. + +Das ist die bevorzugte Bedienung dieser Lieferung, keine Erlaubnis zu stillen Inhaltsverlusten. Falls sie sich im Bestand nicht zuverlässig umsetzen lässt, die konkrete Grenze und eine funktionsfähige Alternative aus Markdown-Bearbeitung, Formatierungsleiste und gerenderter Leseansicht benennen. Dann den Wunsch nach direkter formatierter Bearbeitung ausdrücklich als offen ausweisen; eine einfache Textarea mit Vorschau nicht als vollständig erfülltes Ideal melden. Die übrigen Pakete deshalb nicht anhalten. + +## 7. Vorgehen und konkrete Abnahme + +Erst eine kurze Liste: welche Punkte im aktuellen Stand bereits belegt sind, welche Lücken tatsächlich bestehen und in welcher Reihenfolge sie geschlossen werden. Dann implementieren. Keine wochenlange Rahmenwerksarbeit. Sinnvolle Reihenfolge: notwendige gemeinsame Anschlussstellen korrigieren, IMAP-Fehler beheben, Paperless-Suche ausbauen, Markdown-Bedienung integrieren. Technisch unabhängige Aufgaben müssen nicht auf eine vollständige Umstellung aller Details warten; am Ende die gemeinsame Integration prüfen. + +| Nr. | Szenario und beobachtbares Ergebnis | +|---|---| +| A1 | Dritten Test-Connector nur durch Modul und ausdrückliche Registrierung anbinden. In der Testoberfläche einrichten, suchen/navigieren, vor Übernahme öffnen, einbinden, erneut öffnen und exportieren. Für sein Formular ist ein eigenes registriertes Modul zulässig; eine nicht vorhandene Standardform nicht behaupten. Keine Source-Sonderzweige in Fachseiten, generischem Reader oder Export ergänzen. | +| A2 | Eine Testquelle mit E-Mail-Darstellung über den vorhandenen Leser einschließlich Anlagen öffnen. Der Zugriff läuft über ihre registrierte Ressourcenoperation, ohne IMAP-Zwang. Keine zusätzliche produktive Quelle erforderlich. | +| A3 | Vorhandenen Test-Storage über die echte Speicherauflösung für Upload, erneutes Lesen, Export, Versandfassung und Löschen/Bereinigung verwenden. Einheitenprüfungen an zwei unverbundenen Adapterobjekten genügen nicht. IDs, Generationen und Originalbytes erhalten. | +| A4 | Fehlende und entzogene Kontext-/Quellfreigabe sowie manipulierte Instanz und Ressource prüfen. Suche, Vorschau, Original, Anlagen und Export bleiben geschützt. Adapter wiederholen keine Tsumugu-Freigabelogik. Externen Abruf und Rechteentzug zwischen Vorbereitung und Abschluss prüfen. | +| B1 | Großen Ordner mit mindestens 50.000 synthetischen UID-Einträgen, Lücken und mehr als einer Seite reproduzieren. Erste und weitere Seiten liefern Nachrichten, Suche findet einen gezielt außerhalb der ersten Seite liegenden Treffer. Große Antwort bzw. begrenzte Antwortstrategie prüfen; eine lange UID-Liste allein in einem Fake beweist keine reale Protokollverträglichkeit. Aufruf-/Datenumfang bleibt begrenzt. | +| B2 | Erfolgreich leerer Ordner und erfolgreiche Suche ohne Treffer zeigen einen Leerzustand. `NO`, `BAD`, Timeout, Abbruch und fehlgeschlagene Headerabrufe zeigen passende Fehler/Teilzustände. Der vollständige Ausfall einer Ergebnisseite wird nicht „leer“. | +| B3 | UIDVALIDITY-Wechsel, neue/gelöschte Nachrichten, Unicode-Suchtext und schneller Ordnerwechsel führen zu korrekter Fortsetzung oder verständlichem Neustart. Keine falsche Nachricht, kein veränderter Gelesen-Status. | +| C1 | Mindestens 45 synthetische Paperless-Dokumente über mehrere Seiten: Ein Suchwort nur im Inhalt wird gefunden; ein getrenntes Titelfeld grenzt zusätzlich ein. Filter für Korrespondent, Typ, mehrere Tags und Datum werden einzeln und kombiniert bis zur API nachweisbar übergeben und korrekt angewandt. | +| C2 | Sortierung und Seitenwechsel erhalten Filter und bewusste Mehrfachauswahl. Treffer hinter Seite eins vor Übernahme öffnen, einbinden, erneut öffnen und exportieren. Zwei Instanzen mit gleicher Dokument-ID bleiben getrennt. Fremde/entzogene Stammdaten und Treffer bleiben verborgen. | +| D1 | Bestehende Notiz öffnen: gerenderte Ansicht. Bearbeiten mit Formatierungsleiste, Moduswechsel, Speichern: gerenderter neuer Stand; erneutes Öffnen identisch. Abbrechen und Navigation verlieren keinen Entwurf unbeabsichtigt. Formatierte Direktbearbeitung entweder vorführen oder als offen begründen. | +| D2 | Dieselbe Notiz in zwei Vorgängen: berechtigte Änderung erscheint in beiden, lokale Anmerkung nur in ihrem Kontext. Leserecht erlaubt keine Änderung. Versionskonflikt bewahrt den Entwurf und überschreibt keinen anderen Stand. | +| D3 | Markdown mit Links, Listen, Überschriften, Zitaten, Code und bisher nicht visuell unterstützter Syntax über Öffnen/Speichern/Moduswechsel erhalten. Kein Inhaltsverlust; schädliches HTML/Links werden nicht ausgeführt, externe Bilder nicht automatisch abgerufen. | +| E1 | Bestehende Exportauswahl, Unterkapitel, eigene Dateien und gesicherte Versandstände funktionieren. E-Mail enthält weiterhin alle Anlagen, auch wenn ein separates Anlage-Vorkommen abgewählt ist. Gesicherte Versandbytes nicht durch aktuelle Quelldaten ersetzen. | +| E2 | Betroffene Bedienabläufe auf Desktop und bei 390/360 px prüfen: Tastatur, Fokus und Rückkehr, Laden/Fehler/leer, Speichern/Abbrechen. Vorhandene Designrichtung und kompakte Listen erhalten. | + +Vorhandene Tests gezielt erweitern. Nach den Änderungen relevante Regressionstests und Frontend-Build ausführen. Bestandene Prüfungen ohne neue Änderung oder ungelöste Sorge nicht wiederholt breit laufen lassen. Keine produktiven Datenbanken für automatisierte Tests verwenden. + +Für tatsächliche Quellenchecks nur vorhandene autorisierte lokale Verbindungen lesend verwenden; keine neuen Credentials beschaffen und keine Inhalte veröffentlichen. Wenn ein echter Anschluss nicht verfügbar ist, synthetischen Nachweis und verbleibende reale Abnahme getrennt ausweisen. Keine Erfolgsmeldung für eine nicht durchgeführte Prüfung. Der Nutzer hat bereits grundsätzlich funktionierende Alltagsabläufe beobachtet; diese Beobachtung ersetzt keinen gezielten Großordner- oder Filtertest. + +## 8. Dokumentation, Grenzen und Übergabe + +- Dieses Dokument im vorgesehenen Produktverzeichnis ablegen und in `docs/README.md` sowie der Planungsübergabe verlinken. Die Fachspec gezielt um die aktuellen Nutzeranforderungen und spätere Implementierungsnachweise ergänzen; bevorzugte Bedienung und noch offene Punkte klar kennzeichnen. +- Betroffene API-/Datenmodell-/Rechte-Dokumentation nur im nötigen Umfang nachführen. Die bestehende Abschlussmatrix korrigieren: alte Testergebnisse historisch erhalten, behobene Lücken mit neuen konkreten Nachweisen ergänzen. Nicht pauschal alles auf „bestanden“ setzen. +- Abschlussbericht kurz halten: vier Arbeitspakete A–D mit Ergebnis, konkret ausgeführten Tests, realer oder nachgebildeter Quelle und verbleibender Grenze. Dazu Anleitung für neue Source-/Storage-/Darstellungs-/Editor-Module und Liste der weiterhin zulässigen Quellkenntnis. Laufzeitverhalten und Erweiterbarkeit getrennt bewerten. +- Kein Push, Deployment, externer Versand oder Änderung anderer Produkte. Keine neue SaaS-/Runtime-/Kryptografieplattform, keine KI, Finanzfunktionen oder bidirektionalen Paperless-Schreiboperationen. Bestehende Schlüssel-/Storage-Zielanforderungen erhalten. + +## 9. Technische Quellen für die Umsetzung + +Die folgenden Primärquellen sind Orientierung, keine Zusage über die installierte Version. Vor konkretem Mapping die eingesetzte Version/API prüfen: + +- [Paperless-ngx: REST API](https://docs.paperless-ngx.com/api/) – Suchmöglichkeiten, Filter und API-Versionierung. Die offizielle Dokumentation beschreibt Inhalts-/Titelsuche; der aktuelle lokale `query`-Aufruf belegt daher nicht die Ursache der beobachteten Titelsuche. +- [Python: imaplib](https://docs.python.org/3/library/imaplib.html) – Rückgabestatus, Fehler und UID-Zugriff. Technische Details gegen die im Projekt eingesetzte Python-Version prüfen. +- [RFC 9051: IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051.html) – Protokoll- und Identitätsregeln. Bestehende IMAP4rev1-Server weiterhin unterstützen; rev2 ist keine neue Mindestanforderung. + +Die Notiz-Editorbibliothek wird mit kurzer Begründung im Repository festgelegt; dieser Auftrag schreibt keine unüberprüfte Bibliothek oder Version vor. diff --git a/docs/product/TSUMUGU_PRODUCT_SPEC.md b/docs/product/TSUMUGU_PRODUCT_SPEC.md index 16e55cf..4ca07f4 100644 --- a/docs/product/TSUMUGU_PRODUCT_SPEC.md +++ b/docs/product/TSUMUGU_PRODUCT_SPEC.md @@ -19,7 +19,7 @@ Diese Datei sichert bestätigte Anforderungen, den Quellenabgleich und das näch **Kennzeichnung in dieser Datei:** Bestätigt = aktueller Nutzerauftrag oder direkt lesbare ursprüngliche Nutzeraussage; Rekonstruktion = nur durch Recovery belegt; Vorschlag = neue Empfehlung ohne Freigabe; Offen = noch zu entscheiden. Technische Discovery-Vorschläge werden nicht zu Fachanforderungen erhoben. -**Implementierungsnachweis 19.10.2026, ohne neue Fachversion:** Die lesende Connector-/Storage-Grundlage ist lokal umgesetzt. Das ist ein Implementierungsnachweis zum Vertrag v0.1, keine neue bestätigte Produktentscheidung und keine Aufhebung von F-02b oder F-02c. Die erste Source-Lieferung bleibt lesend. Bidirektionale Feldsynchronisation, erweiterte Paperless-Suche und der vervollständigte Quellenbrowser sind der nächste, separat zu startende Funktionsausbau. Die Abschlusskriterien in [TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md) haben Vorrang vor einem nur teilweise integrierten Zwischenstand. Nachweis, Grenzen und die Matrix stehen in [TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md). Der frühere Zwischenstand bleibt in [TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md](TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md). +**Implementierungsnachweis 19.10.2026, ohne neue Fachversion:** Die lesende Connector-/Storage-Grundlage ist lokal umgesetzt. Das ist ein Implementierungsnachweis zum Vertrag v0.1, keine neue bestätigte Produktentscheidung und keine Aufhebung von F-02b oder F-02c. Die erste Source-Lieferung bleibt lesend. Bidirektionale Feldsynchronisation bleibt der spätere Ausbau. Die Nacharbeit an großen IMAP-Fächern, der Paperless-Suche und der internen Markdown-Notiz ist beauftragt und lokal umgesetzt: [TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md](TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md). Eine Notiz bleibt ein interner Gegenstand. Beim Öffnen erscheint zuerst die gesetzte Markdown-Fassung. Mit Bearbeitungsrecht folgt eine formatierte Bearbeitung mit Formatierungsleiste und umschaltbarem Markdown-Quelltext. Weicht die formatierte Ansicht vom gespeicherten Markdown ab, bleibt der Quelltext maßgeblich. Die Abschlusskriterien in [TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSKRITERIEN_2026-10-19.md) haben Vorrang vor einem nur teilweise integrierten Zwischenstand. Nachweis, Grenzen und die Matrix stehen in [TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md). Der frühere Zwischenstand bleibt in [TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md](TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md). ## 2. Gesicherter fachlicher Kern diff --git a/docs/product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md b/docs/product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md index ec4b998..8706de0 100644 --- a/docs/product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md +++ b/docs/product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md @@ -1,6 +1,6 @@ # Tsumugu – Übergabe zur fachlichen Weiterplanung -**Nachtrag 19.10.2026:** Die Connector-/Storage-Grundlage ist gegen die Abschlusskriterien geschlossen. Die Matrix steht in [TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md). Abschnitt B, der vervollständigte Quellenbrowser und die erweiterte Paperless-Suche, bleibt der nächste separate Funktionsausbau. F-02b und F-02c bleiben erhalten. Der übrige Text dieser Übergabe beschreibt den Stand vom 17. und 18.10.2026. +**Nachtrag 19.10.2026:** Die Connector-/Storage-Grundlage ist gegen die Abschlusskriterien geschlossen. Die Matrix steht in [TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md](TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md). Die Nacharbeit an großen IMAP-Fächern, der Paperless-Suche und der internen Markdown-Notiz ist lokal umgesetzt; Auftrag und Grenzen stehen in [TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md](TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md). F-02b und F-02c bleiben erhalten; eine bidirektionale Paperless-Schreibsynchronisation startet dieser Auftrag nicht. Der übrige Text dieser Übergabe beschreibt den Stand vom 17. und 18.10.2026. **Stand:** 17.10.2026 · **Zweck:** Einstieg in einen neuen fachlichen Planungschat nach Auswahl des Designkonzepts. Keine neue Produktentscheidung und kein zusätzlicher Implementierungsauftrag. diff --git a/frontend/package-lock.json b/frontend/package-lock.json index 41f4817..596d206 100644 --- a/frontend/package-lock.json +++ b/frontend/package-lock.json @@ -6,6 +6,7 @@ "": { "name": "tsumugu-frontend", "dependencies": { + "@mdxeditor/editor": "3.52.4", "pdfjs-dist": "^4.10.38", "react": "18.3.1", "react-dom": "18.3.1", @@ -252,6 +253,15 @@ "@babel/core": "^7.0.0-0" } }, + "node_modules/@babel/runtime": { + "version": "7.29.10", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.10.tgz", + "integrity": "sha512-NpugTzbKgGrNe45Ui32cN8vCFFMxVtP/9rtfwv0nP5FRDAjvYBxJcLVpYA9mr1jxP6cnIT7x9LUzuDTbWYYNRA==", + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, "node_modules/@babel/template": { "version": "7.29.7", "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.29.7.tgz", @@ -300,6 +310,485 @@ "node": ">=6.9.0" } }, + "node_modules/@codemirror/autocomplete": { + "version": "6.20.4", + "resolved": "https://registry.npmjs.org/@codemirror/autocomplete/-/autocomplete-6.20.4.tgz", + "integrity": "sha512-yF8RhOf2SXlg00+qtupzLhrglcas61boqaONiNcbPIebHCpJocpqTBA6dyrtUrQO47hqyTdeob/3XnYilT7TaQ==", + "license": "MIT", + "dependencies": { + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.17.0", + "@lezer/common": "^1.0.0" + } + }, + "node_modules/@codemirror/commands": { + "version": "6.11.1", + "resolved": "https://registry.npmjs.org/@codemirror/commands/-/commands-6.11.1.tgz", + "integrity": "sha512-O/4hG3SC1YwcmQ0d2UVNDs+AsaNWd1iHVxbTeEBuqH+6bExAiPK3iS/BvpY6rZGURALv4ZD3sIgcCmRvw3ehBg==", + "license": "MIT", + "dependencies": { + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.7.0", + "@codemirror/view": "^6.27.0", + "@lezer/common": "^1.1.0" + } + }, + "node_modules/@codemirror/lang-angular": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/@codemirror/lang-angular/-/lang-angular-0.1.4.tgz", + "integrity": "sha512-oap+gsltb/fzdlTQWD6BFF4bSLKcDnlxDsLdePiJpCVNKWXSTAbiiQeYI3UmES+BLAdkmIC1WjyztC1pi/bX4g==", + "license": "MIT", + "dependencies": { + "@codemirror/lang-html": "^6.0.0", + "@codemirror/lang-javascript": "^6.1.2", + "@codemirror/language": "^6.0.0", + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.3.3" + } + }, + "node_modules/@codemirror/lang-cpp": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/@codemirror/lang-cpp/-/lang-cpp-6.0.3.tgz", + "integrity": "sha512-URM26M3vunFFn9/sm6rzqrBzDgfWuDixp85uTY49wKudToc2jTHUrKIGGKs+QWND+YLofNNZpxcNGRynFJfvgA==", + "license": "MIT", + "dependencies": { + "@codemirror/language": "^6.0.0", + "@lezer/cpp": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-css": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/@codemirror/lang-css/-/lang-css-6.3.1.tgz", + "integrity": "sha512-kr5fwBGiGtmz6l0LSJIbno9QrifNMUusivHbnA1H6Dmqy4HZFte3UAICix1VuKo0lMPKQr2rqB+0BkKi/S3Ejg==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@lezer/common": "^1.0.2", + "@lezer/css": "^1.1.7" + } + }, + "node_modules/@codemirror/lang-go": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/@codemirror/lang-go/-/lang-go-6.0.1.tgz", + "integrity": "sha512-7fNvbyNylvqCphW9HD6WFnRpcDjr+KXX/FgqXy5H5ZS0eC5edDljukm/yNgYkwTsgp2busdod50AOTIy6Jikfg==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/language": "^6.6.0", + "@codemirror/state": "^6.0.0", + "@lezer/common": "^1.0.0", + "@lezer/go": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-html": { + "version": "6.4.12", + "resolved": "https://registry.npmjs.org/@codemirror/lang-html/-/lang-html-6.4.12.tgz", + "integrity": "sha512-pw2ReWKUqSkbvh76RAT4NYxiogRu+PWkR2ukAwO9uOgrm8uipkzjtKKtNpyeAQwHOqxEeSvAXZ6vr3AfyB9y/w==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/lang-css": "^6.0.0", + "@codemirror/lang-javascript": "^6.0.0", + "@codemirror/language": "^6.4.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.17.0", + "@lezer/common": "^1.0.0", + "@lezer/css": "^1.1.0", + "@lezer/html": "^1.3.12" + } + }, + "node_modules/@codemirror/lang-java": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/@codemirror/lang-java/-/lang-java-6.0.2.tgz", + "integrity": "sha512-m5Nt1mQ/cznJY7tMfQTJchmrjdjQ71IDs+55d1GAa8DGaB8JXWsVCkVT284C3RTASaY43YknrK2X3hPO/J3MOQ==", + "license": "MIT", + "dependencies": { + "@codemirror/language": "^6.0.0", + "@lezer/java": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-javascript": { + "version": "6.2.5", + "resolved": "https://registry.npmjs.org/@codemirror/lang-javascript/-/lang-javascript-6.2.5.tgz", + "integrity": "sha512-zD4e5mS+50htS7F+TYjBPsiIFGanfVqg4HyUz6WNFikgOPf2BgKlx+TQedI1w6n/IqRBVBbBWmGFdLB/7uxO4A==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/language": "^6.6.0", + "@codemirror/lint": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.17.0", + "@lezer/common": "^1.0.0", + "@lezer/javascript": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-jinja": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/@codemirror/lang-jinja/-/lang-jinja-6.0.1.tgz", + "integrity": "sha512-P5kyHLObzjtbGj16h+hyvZTxJhSjBEeSx4wMjbnAf3b0uwTy2+F0zGjMZL4PQOm/mh2eGZ5xUDVZXgwP783Nsw==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/lang-html": "^6.0.0", + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.0.0", + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.2.0", + "@lezer/lr": "^1.4.0" + } + }, + "node_modules/@codemirror/lang-json": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/@codemirror/lang-json/-/lang-json-6.0.2.tgz", + "integrity": "sha512-x2OtO+AvwEHrEwR0FyyPtfDUiloG3rnVTSZV1W8UteaLL8/MajQd8DpvUb2YVzC+/T18aSDv0H9mu+xw0EStoQ==", + "license": "MIT", + "dependencies": { + "@codemirror/language": "^6.0.0", + "@lezer/json": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-less": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/@codemirror/lang-less/-/lang-less-6.0.2.tgz", + "integrity": "sha512-EYdQTG22V+KUUk8Qq582g7FMnCZeEHsyuOJisHRft/mQ+ZSZ2w51NupvDUHiqtsOy7It5cHLPGfHQLpMh9bqpQ==", + "license": "MIT", + "dependencies": { + "@codemirror/lang-css": "^6.2.0", + "@codemirror/language": "^6.0.0", + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-liquid": { + "version": "6.3.3", + "resolved": "https://registry.npmjs.org/@codemirror/lang-liquid/-/lang-liquid-6.3.3.tgz", + "integrity": "sha512-U9EnyzWuAx1TX3MZSKDXydKH734n1Aogk/ijKdW+jdIwmbf9zSPQYOIKggC/b2PTRjQb7ddvMktmxnfTLuv/SQ==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/lang-html": "^6.0.0", + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.0.0", + "@lezer/common": "^1.0.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.3.1" + } + }, + "node_modules/@codemirror/lang-markdown": { + "version": "6.5.2", + "resolved": "https://registry.npmjs.org/@codemirror/lang-markdown/-/lang-markdown-6.5.2.tgz", + "integrity": "sha512-AwBOdkWYuA//WcM0xO5PfHPUcmz/O2i5o0Nsg1U69SII/loCJlFI1Romd9xp2HYb1kYJRGZotyqRghuHH5n8Kw==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.7.1", + "@codemirror/lang-html": "^6.0.0", + "@codemirror/language": "^6.3.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.0.0", + "@lezer/common": "^1.2.1", + "@lezer/markdown": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-php": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/@codemirror/lang-php/-/lang-php-6.0.2.tgz", + "integrity": "sha512-ZKy2v1n8Fc8oEXj0Th0PUMXzQJ0AIR6TaZU+PbDHExFwdu+guzOA4jmCHS1Nz4vbFezwD7LyBdDnddSJeScMCA==", + "license": "MIT", + "dependencies": { + "@codemirror/lang-html": "^6.0.0", + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@lezer/common": "^1.0.0", + "@lezer/php": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-python": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/@codemirror/lang-python/-/lang-python-6.2.1.tgz", + "integrity": "sha512-IRjC8RUBhn9mGR9ywecNhB51yePWCGgvHfY1lWN/Mrp3cKuHr0isDKia+9HnvhiWNnMpbGhWrkhuWOc09exRyw==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.3.2", + "@codemirror/language": "^6.8.0", + "@codemirror/state": "^6.0.0", + "@lezer/common": "^1.2.1", + "@lezer/python": "^1.1.4" + } + }, + "node_modules/@codemirror/lang-rust": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/@codemirror/lang-rust/-/lang-rust-6.0.2.tgz", + "integrity": "sha512-EZaGjCUegtiU7kSMvOfEZpaCReowEf3yNidYu7+vfuGTm9ow4mthAparY5hisJqOHmJowVH3Upu+eJlUji6qqA==", + "license": "MIT", + "dependencies": { + "@codemirror/language": "^6.0.0", + "@lezer/rust": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-sass": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/@codemirror/lang-sass/-/lang-sass-6.0.2.tgz", + "integrity": "sha512-l/bdzIABvnTo1nzdY6U+kPAC51czYQcOErfzQ9zSm9D8GmNPD0WTW8st/CJwBTPLO8jlrbyvlSEcN20dc4iL0Q==", + "license": "MIT", + "dependencies": { + "@codemirror/lang-css": "^6.2.0", + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@lezer/common": "^1.0.2", + "@lezer/sass": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-sql": { + "version": "6.10.0", + "resolved": "https://registry.npmjs.org/@codemirror/lang-sql/-/lang-sql-6.10.0.tgz", + "integrity": "sha512-6ayPkEd/yRw0XKBx5uAiToSgGECo/GY2NoJIHXIIQh1EVwLuKoU8BP/qK0qH5NLXAbtJRLuT73hx7P9X34iO4w==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-vue": { + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/@codemirror/lang-vue/-/lang-vue-0.1.3.tgz", + "integrity": "sha512-QSKdtYTDRhEHCfo5zOShzxCmqKJvgGrZwDQSdbvCRJ5pRLWBS7pD/8e/tH44aVQT6FKm0t6RVNoSUWHOI5vNug==", + "license": "MIT", + "dependencies": { + "@codemirror/lang-html": "^6.0.0", + "@codemirror/lang-javascript": "^6.1.2", + "@codemirror/language": "^6.0.0", + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.3.1" + } + }, + "node_modules/@codemirror/lang-wast": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/@codemirror/lang-wast/-/lang-wast-6.0.2.tgz", + "integrity": "sha512-Imi2KTpVGm7TKuUkqyJ5NRmeFWF7aMpNiwHnLQe0x9kmrxElndyH0K6H/gXtWwY6UshMRAhpENsgfpSwsgmC6Q==", + "license": "MIT", + "dependencies": { + "@codemirror/language": "^6.0.0", + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-xml": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/@codemirror/lang-xml/-/lang-xml-6.1.0.tgz", + "integrity": "sha512-3z0blhicHLfwi2UgkZYRPioSgVTo9PV5GP5ducFH6FaHy0IAJRg+ixj5gTR1gnT/glAIC8xv4w2VL1LoZfs+Jg==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/language": "^6.4.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.0.0", + "@lezer/common": "^1.0.0", + "@lezer/xml": "^1.0.0" + } + }, + "node_modules/@codemirror/lang-yaml": { + "version": "6.1.3", + "resolved": "https://registry.npmjs.org/@codemirror/lang-yaml/-/lang-yaml-6.1.3.tgz", + "integrity": "sha512-AZ8DJBuXGVHybpBQhmZtgew5//4hv3tdkXnr3vDmOUMJRuB6vn/uuwtmTOTlqEaQFg3hQSVeA90NmvIQyUV6FQ==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.2.0", + "@lezer/lr": "^1.0.0", + "@lezer/yaml": "^1.0.0" + } + }, + "node_modules/@codemirror/language": { + "version": "6.13.1", + "resolved": "https://registry.npmjs.org/@codemirror/language/-/language-6.13.1.tgz", + "integrity": "sha512-zfvU2r3TyylQLMj/te+5CnQ0rSqZi8B1oTCBbQkagcLW4Xc6imab6qN+pEJhsuNOLaJqiRyBXp9UhWA1DhVvDw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@codemirror/state": "^6.0.0", + "@codemirror/streamparser": "^6.0.0", + "@codemirror/view": "^6.23.0", + "@lezer/common": "^1.5.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0", + "style-mod": "^4.0.0" + } + }, + "node_modules/@codemirror/language-data": { + "version": "6.5.2", + "resolved": "https://registry.npmjs.org/@codemirror/language-data/-/language-data-6.5.2.tgz", + "integrity": "sha512-CPkWBKrNS8stYbEU5kwBwTf3JB1kghlbh4FSAwzGW2TEscdeHHH4FGysREW86Mqnj3Qn09s0/6Ea/TutmoTobg==", + "license": "MIT", + "dependencies": { + "@codemirror/lang-angular": "^0.1.0", + "@codemirror/lang-cpp": "^6.0.0", + "@codemirror/lang-css": "^6.0.0", + "@codemirror/lang-go": "^6.0.0", + "@codemirror/lang-html": "^6.0.0", + "@codemirror/lang-java": "^6.0.0", + "@codemirror/lang-javascript": "^6.0.0", + "@codemirror/lang-jinja": "^6.0.0", + "@codemirror/lang-json": "^6.0.0", + "@codemirror/lang-less": "^6.0.0", + "@codemirror/lang-liquid": "^6.0.0", + "@codemirror/lang-markdown": "^6.0.0", + "@codemirror/lang-php": "^6.0.0", + "@codemirror/lang-python": "^6.0.0", + "@codemirror/lang-rust": "^6.0.0", + "@codemirror/lang-sass": "^6.0.0", + "@codemirror/lang-sql": "^6.0.0", + "@codemirror/lang-vue": "^0.1.1", + "@codemirror/lang-wast": "^6.0.0", + "@codemirror/lang-xml": "^6.0.0", + "@codemirror/lang-yaml": "^6.0.0", + "@codemirror/language": "^6.0.0", + "@codemirror/legacy-modes": "^6.4.0" + } + }, + "node_modules/@codemirror/legacy-modes": { + "version": "6.5.5", + "resolved": "https://registry.npmjs.org/@codemirror/legacy-modes/-/legacy-modes-6.5.5.tgz", + "integrity": "sha512-9ltT214oMb3Y1w5eAZMSigzrjzZnMI2Wa3Feq73rU/i4C56MkwrpfswfQYOr28C5pXr6dWwspNTMyeHXlzWMxg==", + "license": "MIT", + "dependencies": { + "@codemirror/streamparser": "^6.0.0" + } + }, + "node_modules/@codemirror/lint": { + "version": "6.9.7", + "resolved": "https://registry.npmjs.org/@codemirror/lint/-/lint-6.9.7.tgz", + "integrity": "sha512-28/+iWLYxKxsvGYhSYL7zaCZqLz5+FFFDq9tVsvGv9kv8RY4fFAchJ5WX9M3YrrRlTIsECjsXPqeNgnSmNP2dg==", + "license": "MIT", + "dependencies": { + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.42.0", + "crelt": "^1.0.5" + } + }, + "node_modules/@codemirror/merge": { + "version": "6.12.3", + "resolved": "https://registry.npmjs.org/@codemirror/merge/-/merge-6.12.3.tgz", + "integrity": "sha512-Wq9wXrp41cW/nIpi1CQPyNwD+36kg8KIX676ym0Hyfn3Dpr+XQHNAIsZYVNlaivuVB4SAASbreG3V0VXinbqZA==", + "license": "MIT", + "dependencies": { + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.17.0", + "@lezer/highlight": "^1.0.0", + "style-mod": "^4.1.0" + } + }, + "node_modules/@codemirror/search": { + "version": "6.7.2", + "resolved": "https://registry.npmjs.org/@codemirror/search/-/search-6.7.2.tgz", + "integrity": "sha512-gUYkYhT2+n/+VGZ+8EzE5WFkYZUZYm1VOKDudIsNqh42uRVQJ0a6Yss9sdKT3MeOYfuL1N6AZA57oza0Oyr0LA==", + "license": "MIT", + "dependencies": { + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.37.0", + "crelt": "^1.0.5" + } + }, + "node_modules/@codemirror/state": { + "version": "6.7.6", + "resolved": "https://registry.npmjs.org/@codemirror/state/-/state-6.7.6.tgz", + "integrity": "sha512-kAz+AncRtKuIknedxT1bq4XwXv4UowhbkHU1myPrtVb/jZtImWuV5BXzv5vK6i3kYACsdiZiQKFQQ5Mq7elW8w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@marijn/find-cluster-break": "^1.0.0" + } + }, + "node_modules/@codemirror/streamparser": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@codemirror/streamparser/-/streamparser-6.0.0.tgz", + "integrity": "sha512-JTFPF6xrfjt0mnfGPgzcLiMwYmvIyNaoizp8BYzv8FE8KrT6GBGDZ190rtt+O7Wke3gG/MFHyiY9YGNeimof4w==", + "license": "MIT" + }, + "node_modules/@codemirror/view": { + "version": "6.43.15", + "resolved": "https://registry.npmjs.org/@codemirror/view/-/view-6.43.15.tgz", + "integrity": "sha512-HHsfpqFeHyXLs983pSRe38Xajs0vFWZQ2BuX0m7Ki8w3jZ5iD8cuR3lBz2/5/X53Dhf32SBHKh6rtSTB6tKeGw==", + "license": "MIT", + "peer": true, + "dependencies": { + "@codemirror/state": "^6.7.0", + "crelt": "^1.0.6", + "style-mod": "^4.1.0", + "w3c-keyname": "^2.2.4" + } + }, + "node_modules/@codesandbox/nodebox": { + "version": "0.1.8", + "resolved": "https://registry.npmjs.org/@codesandbox/nodebox/-/nodebox-0.1.8.tgz", + "integrity": "sha512-2VRS6JDSk+M+pg56GA6CryyUSGPjBEe8Pnae0QL3jJF1mJZJVMDKr93gJRtBbLkfZN6LD/DwMtf+2L0bpWrjqg==", + "license": "SEE LICENSE IN ./LICENSE", + "dependencies": { + "outvariant": "^1.4.0", + "strict-event-emitter": "^0.4.3" + } + }, + "node_modules/@codesandbox/sandpack-client": { + "version": "2.19.8", + "resolved": "https://registry.npmjs.org/@codesandbox/sandpack-client/-/sandpack-client-2.19.8.tgz", + "integrity": "sha512-CMV4nr1zgKzVpx4I3FYvGRM5YT0VaQhALMW9vy4wZRhEyWAtJITQIqZzrTGWqB1JvV7V72dVEUCUPLfYz5hgJQ==", + "license": "Apache-2.0", + "dependencies": { + "@codesandbox/nodebox": "0.1.8", + "buffer": "^6.0.3", + "dequal": "^2.0.2", + "mime-db": "^1.52.0", + "outvariant": "1.4.0", + "static-browser-server": "1.0.3" + } + }, + "node_modules/@codesandbox/sandpack-react": { + "version": "2.20.0", + "resolved": "https://registry.npmjs.org/@codesandbox/sandpack-react/-/sandpack-react-2.20.0.tgz", + "integrity": "sha512-takd1YpW/PMQ6KPQfvseWLHWklJovGY8QYj8MtWnskGKbjOGJ6uZfyZbcJ6aCFLQMpNyjTqz9AKNbvhCOZ1TUQ==", + "license": "Apache-2.0", + "dependencies": { + "@codemirror/autocomplete": "^6.4.0", + "@codemirror/commands": "^6.1.3", + "@codemirror/lang-css": "^6.0.1", + "@codemirror/lang-html": "^6.4.0", + "@codemirror/lang-javascript": "^6.1.2", + "@codemirror/language": "^6.3.2", + "@codemirror/state": "^6.2.0", + "@codemirror/view": "^6.7.1", + "@codesandbox/sandpack-client": "^2.19.8", + "@lezer/highlight": "^1.1.3", + "@react-hook/intersection-observer": "^3.1.1", + "@stitches/core": "^1.2.6", + "anser": "^2.1.1", + "clean-set": "^1.1.2", + "dequal": "^2.0.2", + "escape-carriage": "^1.3.1", + "lz-string": "^1.4.4", + "react-devtools-inline": "4.4.0", + "react-is": "^17.0.2" + }, + "peerDependencies": { + "react": "^16.8.0 || ^17 || ^18 || ^19", + "react-dom": "^16.8.0 || ^17 || ^18 || ^19" + } + }, "node_modules/@emnapi/runtime": { "version": "1.11.3", "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz", @@ -702,6 +1191,59 @@ "node": ">=12" } }, + "node_modules/@floating-ui/core": { + "version": "1.8.0", + "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.8.0.tgz", + "integrity": "sha512-0CIZ5itps/8x7BG8dEIhs53BvCUH2PCoogtakwRTut+Arm58sJooJ0AuZhLw2HJYIR5cMLNPBSS728sPho2khQ==", + "license": "MIT", + "dependencies": { + "@floating-ui/utils": "^0.2.12" + } + }, + "node_modules/@floating-ui/dom": { + "version": "1.8.0", + "resolved": "https://registry.npmjs.org/@floating-ui/dom/-/dom-1.8.0.tgz", + "integrity": "sha512-yXSrzeHZBTZadLOlfyhCkJHNeLJnHRnRInwdZ40L7ZiaAtrBwoYlsDrX3v5zB1Utk7CLfzcOVnVVWoXEky7Ceg==", + "license": "MIT", + "dependencies": { + "@floating-ui/core": "^1.8.0", + "@floating-ui/utils": "^0.2.12" + } + }, + "node_modules/@floating-ui/react": { + "version": "0.27.20", + "resolved": "https://registry.npmjs.org/@floating-ui/react/-/react-0.27.20.tgz", + "integrity": "sha512-CMqMy7OaXl9W0eq1Uy7L7i2Y/anPvHmFmESd2CEw0t5YvZhcVCeo4MBevAmswRllX7Y2dEidA4ozGPunLSTQpw==", + "license": "MIT", + "dependencies": { + "@floating-ui/react-dom": "^2.1.9", + "@floating-ui/utils": "^0.2.12", + "tabbable": "^6.0.0" + }, + "peerDependencies": { + "react": ">=17.0.0", + "react-dom": ">=17.0.0" + } + }, + "node_modules/@floating-ui/react-dom": { + "version": "2.1.9", + "resolved": "https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-2.1.9.tgz", + "integrity": "sha512-JDjEFGCpImxDCA7JJKviA0M9+RtmJdj0m/NVU5IMgBK+AmZouAQQ7/+2GLH0GXXY0YMw9oXPB8hKdbPYg5QLYg==", + "license": "MIT", + "dependencies": { + "@floating-ui/dom": "^1.8.0" + }, + "peerDependencies": { + "react": ">=16.8.0", + "react-dom": ">=16.8.0" + } + }, + "node_modules/@floating-ui/utils": { + "version": "0.2.12", + "resolved": "https://registry.npmjs.org/@floating-ui/utils/-/utils-0.2.12.tgz", + "integrity": "sha512-HpCo8tmWzLVad5s2d19EhAz5zqrrQ6s69qd6moPMQvkOuSwDT1YgRfWSVuc4ennqrgv3OHppiOGMQ7oC13yIww==", + "license": "MIT" + }, "node_modules/@img/colour": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz", @@ -1279,6 +1821,529 @@ "@jridgewell/sourcemap-codec": "^1.4.14" } }, + "node_modules/@lexical/clipboard": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/clipboard/-/clipboard-0.35.0.tgz", + "integrity": "sha512-ko7xSIIiayvDiqjNDX6fgH9RlcM6r9vrrvJYTcfGVBor5httx16lhIi0QJZ4+RNPvGtTjyFv4bwRmsixRRwImg==", + "license": "MIT", + "dependencies": { + "@lexical/html": "0.35.0", + "@lexical/list": "0.35.0", + "@lexical/selection": "0.35.0", + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/code": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/code/-/code-0.35.0.tgz", + "integrity": "sha512-ox4DZwETQ9IA7+DS6PN8RJNwSAF7RMjL7YTVODIqFZ5tUFIf+5xoCHbz7Fll0Bvixlp12hVH90xnLwTLRGpkKw==", + "license": "MIT", + "dependencies": { + "@lexical/utils": "0.35.0", + "lexical": "0.35.0", + "prismjs": "^1.30.0" + } + }, + "node_modules/@lexical/devtools-core": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/devtools-core/-/devtools-core-0.35.0.tgz", + "integrity": "sha512-C2wwtsMCR6ZTfO0TqpSM17RLJWyfHmifAfCTjFtOJu15p3M6NO/nHYK5Mt7YMQteuS89mOjB4ng8iwoLEZ6QpQ==", + "license": "MIT", + "dependencies": { + "@lexical/html": "0.35.0", + "@lexical/link": "0.35.0", + "@lexical/mark": "0.35.0", + "@lexical/table": "0.35.0", + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + }, + "peerDependencies": { + "react": ">=17.x", + "react-dom": ">=17.x" + } + }, + "node_modules/@lexical/dragon": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/dragon/-/dragon-0.35.0.tgz", + "integrity": "sha512-SL6mT5pcqrt6hEbJ16vWxip5+r3uvMd0bQV5UUxuk+cxIeuP86iTgRh0HFR7SM2dRTYovL6/tM/O+8QLAUGTIg==", + "license": "MIT", + "dependencies": { + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/hashtag": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/hashtag/-/hashtag-0.35.0.tgz", + "integrity": "sha512-LYJWzXuO2ZjKsvQwrLkNZiS2TsjwYkKjlDgtugzejquTBQ/o/nfSn/MmVx6EkYLOYizaJemmZbz3IBh+u732FA==", + "license": "MIT", + "dependencies": { + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/history": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/history/-/history-0.35.0.tgz", + "integrity": "sha512-onjDRLLxGbCfHexSxxrQaDaieIHyV28zCDrbxR5dxTfW8F8PxjuNyuaG0z6o468AXYECmclxkP+P4aT6poHEpQ==", + "license": "MIT", + "dependencies": { + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/html": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/html/-/html-0.35.0.tgz", + "integrity": "sha512-rXGFE5S5rKsg3tVnr1s4iEgOfCApNXGpIFI3T2jGEShaCZ5HLaBY9NVBXnE9Nb49e9bkDkpZ8FZd1qokCbQXbw==", + "license": "MIT", + "dependencies": { + "@lexical/selection": "0.35.0", + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/link": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/link/-/link-0.35.0.tgz", + "integrity": "sha512-+0Wx6cBwO8TfdMzpkYFacsmgFh8X1rkiYbq3xoLvk3qV8upYxaMzK1s8Q1cpKmWyI0aZrU6z7fiK4vUqB7+69w==", + "license": "MIT", + "dependencies": { + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/list": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/list/-/list-0.35.0.tgz", + "integrity": "sha512-owsmc8iwgExBX8sFe8fKTiwJVhYULt9hD1RZ/HwfaiEtRZZkINijqReOBnW2mJfRxBzhFSWc4NG3ISB+fHYzqw==", + "license": "MIT", + "dependencies": { + "@lexical/selection": "0.35.0", + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/mark": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/mark/-/mark-0.35.0.tgz", + "integrity": "sha512-W0hwMTAVeexvpk9/+J6n1G/sNkpI/Meq1yeDazahFLLAwXLHtvhIAq2P/klgFknDy1hr8X7rcsQuN/bqKcKHYg==", + "license": "MIT", + "dependencies": { + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/markdown": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/markdown/-/markdown-0.35.0.tgz", + "integrity": "sha512-BlNyXZAt4gWidMw0SRWrhBETY1BpPglFBZI7yzfqukFqgXRh7HUQA28OYeI/nsx9pgNob8TiUduUwShqqvOdEA==", + "license": "MIT", + "dependencies": { + "@lexical/code": "0.35.0", + "@lexical/link": "0.35.0", + "@lexical/list": "0.35.0", + "@lexical/rich-text": "0.35.0", + "@lexical/text": "0.35.0", + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/offset": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/offset/-/offset-0.35.0.tgz", + "integrity": "sha512-DRE4Df6qYf2XiV6foh6KpGNmGAv2ANqt3oVXpyS6W8hTx3+cUuAA1APhCZmLNuU107um4zmHym7taCu6uXW5Yg==", + "license": "MIT", + "dependencies": { + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/overflow": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/overflow/-/overflow-0.35.0.tgz", + "integrity": "sha512-B25YvnJQTGlZcrNv7b0PJBLWq3tl8sql497OHfYYLem7EOMPKKDGJScJAKM/91D4H/mMAsx5gnA/XgKobriuTg==", + "license": "MIT", + "dependencies": { + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/plain-text": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/plain-text/-/plain-text-0.35.0.tgz", + "integrity": "sha512-lwBCUNMJf7Gujp2syVWMpKRahfbTv5Wq+H3HK1Q1gKH1P2IytPRxssCHvexw9iGwprSyghkKBlbF3fGpEdIJvQ==", + "license": "MIT", + "dependencies": { + "@lexical/clipboard": "0.35.0", + "@lexical/selection": "0.35.0", + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/react": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/react/-/react-0.35.0.tgz", + "integrity": "sha512-uYAZSqumH8tRymMef+A0f2hQvMwplKK9DXamcefnk3vSNDHHqRWQXpiUo6kD+rKWuQmMbVa5RW4xRQebXEW+1A==", + "license": "MIT", + "dependencies": { + "@floating-ui/react": "^0.27.8", + "@lexical/devtools-core": "0.35.0", + "@lexical/dragon": "0.35.0", + "@lexical/hashtag": "0.35.0", + "@lexical/history": "0.35.0", + "@lexical/link": "0.35.0", + "@lexical/list": "0.35.0", + "@lexical/mark": "0.35.0", + "@lexical/markdown": "0.35.0", + "@lexical/overflow": "0.35.0", + "@lexical/plain-text": "0.35.0", + "@lexical/rich-text": "0.35.0", + "@lexical/table": "0.35.0", + "@lexical/text": "0.35.0", + "@lexical/utils": "0.35.0", + "@lexical/yjs": "0.35.0", + "lexical": "0.35.0", + "react-error-boundary": "^3.1.4" + }, + "peerDependencies": { + "react": ">=17.x", + "react-dom": ">=17.x" + } + }, + "node_modules/@lexical/rich-text": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/rich-text/-/rich-text-0.35.0.tgz", + "integrity": "sha512-qEHu8g7vOEzz9GUz1VIUxZBndZRJPh9iJUFI+qTDHj+tQqnd5LCs+G9yz6jgNfiuWWpezTp0i1Vz/udNEuDPKQ==", + "license": "MIT", + "dependencies": { + "@lexical/clipboard": "0.35.0", + "@lexical/selection": "0.35.0", + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/selection": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/selection/-/selection-0.35.0.tgz", + "integrity": "sha512-mMtDE7Q0nycXdFTTH/+ta6EBrBwxBB4Tg8QwsGntzQ1Cq//d838dpXpFjJOqHEeVHUqXpiuj+cBG8+bvz/rPRw==", + "license": "MIT", + "dependencies": { + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/table": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/table/-/table-0.35.0.tgz", + "integrity": "sha512-9jlTlkVideBKwsEnEkqkdg7A3mije1SvmfiqoYnkl1kKJCLA5iH90ywx327PU0p+bdnURAytWUeZPXaEuEl2OA==", + "license": "MIT", + "dependencies": { + "@lexical/clipboard": "0.35.0", + "@lexical/utils": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/text": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/text/-/text-0.35.0.tgz", + "integrity": "sha512-uaMh46BkysV8hK8wQwp5g/ByZW+2hPDt8ahAErxtf8NuzQem1FHG/f5RTchmFqqUDVHO3qLNTv4AehEGmXv8MA==", + "license": "MIT", + "dependencies": { + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/utils": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/utils/-/utils-0.35.0.tgz", + "integrity": "sha512-2H393EYDnFznYCDFOW3MHiRzwEO5M/UBhtUjvTT+9kc+qhX4U3zc8ixQalo5UmZ5B2nh7L/inXdTFzvSRXtsRA==", + "license": "MIT", + "dependencies": { + "@lexical/list": "0.35.0", + "@lexical/selection": "0.35.0", + "@lexical/table": "0.35.0", + "lexical": "0.35.0" + } + }, + "node_modules/@lexical/yjs": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/@lexical/yjs/-/yjs-0.35.0.tgz", + "integrity": "sha512-3DSP7QpmTGYU9bN/yljP0PIao4tNIQtsR4ycauWNSawxs/GQCZtSmAPcLRnCm6qpqsDDjUtKjO/1Ej8FRp0m0w==", + "license": "MIT", + "dependencies": { + "@lexical/offset": "0.35.0", + "@lexical/selection": "0.35.0", + "lexical": "0.35.0" + }, + "peerDependencies": { + "yjs": ">=13.5.22" + } + }, + "node_modules/@lezer/common": { + "version": "1.5.3", + "resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.3.tgz", + "integrity": "sha512-H0iErY4e43LpXbYDyBci5W4v/RwTgGV3YzYOlJPiGZ8RY8w51kVE+xLn1tg3Z6UmSfyETvtsUK3r7YsgDQEI7Q==", + "license": "MIT" + }, + "node_modules/@lezer/cpp": { + "version": "1.1.6", + "resolved": "https://registry.npmjs.org/@lezer/cpp/-/cpp-1.1.6.tgz", + "integrity": "sha512-vh9gWWJOXFVY8HBHK3Twzq8MgwG2iN4GSyzBP9sCGTe37P15x2R14VaBQk0VA0ezTRN1KHYBBsHhvpGZ2Xy/pA==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@lezer/css": { + "version": "1.3.9", + "resolved": "https://registry.npmjs.org/@lezer/css/-/css-1.3.9.tgz", + "integrity": "sha512-ZmzgvTOBdJWGIsY/ItAfN7UW8DV802oZG+jeG6E508SwEzz5YhuAajptpWPICvIyqYAD2+VjMdOS40GgGkyEOQ==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.3.0" + } + }, + "node_modules/@lezer/go": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/@lezer/go/-/go-1.0.1.tgz", + "integrity": "sha512-xToRsYxwsgJNHTgNdStpcvmbVuKxTapV0dM0wey1geMMRc9aggoVyKgzYp41D2/vVOx+Ii4hmE206kvxIXBVXQ==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.3.0" + } + }, + "node_modules/@lezer/highlight": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/@lezer/highlight/-/highlight-1.2.5.tgz", + "integrity": "sha512-O1GMVKgtf5YspFaRzpmqkVgMtIk2HG9uMAbH6wdAIdNh3TVzCsch/+cRi+6l2//UGDKe6NB9BW3cvuR5ezMQ0w==", + "license": "MIT", + "peer": true, + "dependencies": { + "@lezer/common": "^1.3.0" + } + }, + "node_modules/@lezer/html": { + "version": "1.3.13", + "resolved": "https://registry.npmjs.org/@lezer/html/-/html-1.3.13.tgz", + "integrity": "sha512-oI7n6NJml729m7pjm9lvLvmXbdoMoi2f+1pwSDJkl9d68zGr7a9Btz8NdHTGQZtW2DA25ybeuv/SyDb9D5tseg==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@lezer/java": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/@lezer/java/-/java-1.1.5.tgz", + "integrity": "sha512-JppTd1iKHpeNlLYw/Zl8JX7zSY5HqAzK4zZ05lpn8l8Sk7Fo5KAKiDiMiezKoT5lfeC2xZf8HeKp1tSctj4G6Q==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@lezer/javascript": { + "version": "1.5.6", + "resolved": "https://registry.npmjs.org/@lezer/javascript/-/javascript-1.5.6.tgz", + "integrity": "sha512-sEvOqpl4vJQca0NugSQK02vQPbc5KrvoojnYGoqqFgFO0MtcYhwGiHKVEB+LuXYJnfyXo4QPA8ztbrEa4Fw5NA==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.1.3", + "@lezer/lr": "^1.3.0" + } + }, + "node_modules/@lezer/json": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@lezer/json/-/json-1.0.3.tgz", + "integrity": "sha512-BP9KzdF9Y35PDpv04r0VeSTKDeox5vVr3efE7eBbx3r4s3oNLfunchejZhjArmeieBH+nVOpgIiBJpEAv8ilqQ==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@lezer/lr": { + "version": "1.4.11", + "resolved": "https://registry.npmjs.org/@lezer/lr/-/lr-1.4.11.tgz", + "integrity": "sha512-UwgZcl1R66H2hDzBrA7kWyYmX6s8p5TQ+e/t7CuvgCtBEPxbEPaHYHu+pJBvTvDotEJpuQkJjbXuHiw5Cixxgw==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.0.0" + } + }, + "node_modules/@lezer/markdown": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/@lezer/markdown/-/markdown-1.8.1.tgz", + "integrity": "sha512-M5YmEcKWO4mJ45Y1hECwqyu8cLv25EiXOK554PVOvDOWOP0olwelHHQUWr9sjF+d1bENVhy0nfJ8E57XZUTiXg==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.5.0", + "@lezer/highlight": "^1.0.0" + } + }, + "node_modules/@lezer/php": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/@lezer/php/-/php-1.0.6.tgz", + "integrity": "sha512-QJ2xNXPmsm/Z3IpThq8fnJrEIVpxhsIoj6GZBW0JYEd/l9zxpJZW216X4fzqQY4vgpdGIumypvI4uQjd4tnYtw==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.1.0" + } + }, + "node_modules/@lezer/python": { + "version": "1.1.19", + "resolved": "https://registry.npmjs.org/@lezer/python/-/python-1.1.19.tgz", + "integrity": "sha512-MhQIURHRytsNzP/YXnqpYKW6la6voAH3kyplTOOiCdjyFY6cWWGFVmYVdHIPrElqSDf4iCDktQCockB9FxuhzQ==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@lezer/rust": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@lezer/rust/-/rust-1.0.3.tgz", + "integrity": "sha512-XxErOjZzQ7yJt1agUT4fu9qQvESZ3acgoxpPaPTPOiUx+duCjaVAtZGFIgphkHxlN05djdVAIOy/wItShMEjqQ==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@lezer/sass": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@lezer/sass/-/sass-1.1.0.tgz", + "integrity": "sha512-3mMGdCTUZ/84ArHOuXWQr37pnf7f+Nw9ycPUeKX+wu19b7pSMcZGLbaXwvD2APMBDOGxPmpK/O6S1v1EvLoqgQ==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@lezer/xml": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/@lezer/xml/-/xml-1.0.6.tgz", + "integrity": "sha512-CdDwirL0OEaStFue/66ZmFSeppuL6Dwjlk8qk153mSQwiSH/Dlri4GNymrNWnUmPl2Um7QfV1FO9KFUyX3Twww==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.0.0" + } + }, + "node_modules/@lezer/yaml": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@lezer/yaml/-/yaml-1.0.4.tgz", + "integrity": "sha512-2lrrHqxalACEbxIbsjhqGpSW8kWpUKuY6RHgnSAFZa6qK62wvnPxA8hGOwOoDbwHcOFs5M4o27mjGu+P7TvBmw==", + "license": "MIT", + "dependencies": { + "@lezer/common": "^1.2.0", + "@lezer/highlight": "^1.0.0", + "@lezer/lr": "^1.4.0" + } + }, + "node_modules/@marijn/find-cluster-break": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@marijn/find-cluster-break/-/find-cluster-break-1.0.4.tgz", + "integrity": "sha512-Wy0V7+SGUjnF9/TkiM1hKVDPj7jKXduPNboMVtHTA8dySMURWqfg/JZ9E2Sq8JgSJmkl7k7Qe9FLeMSrSraWmQ==", + "license": "MIT" + }, + "node_modules/@mdxeditor/editor": { + "version": "3.52.4", + "resolved": "https://registry.npmjs.org/@mdxeditor/editor/-/editor-3.52.4.tgz", + "integrity": "sha512-Tr/QKR7pVrle9xF3ZCsUESOlLY8UZ0N/8RZcyyRWvnuEvePi4EAcbthwnyDkVpnwGppkUxPNrFTAnL7Y0R1Hwg==", + "license": "MIT", + "dependencies": { + "@codemirror/commands": "^6.2.4", + "@codemirror/lang-markdown": "^6.2.3", + "@codemirror/language-data": "^6.5.1", + "@codemirror/merge": "^6.4.0", + "@codemirror/state": "^6.4.0", + "@codemirror/view": "^6.23.0", + "@codesandbox/sandpack-react": "^2.20.0", + "@lexical/clipboard": "^0.35.0", + "@lexical/link": "^0.35.0", + "@lexical/list": "^0.35.0", + "@lexical/markdown": "^0.35.0", + "@lexical/plain-text": "^0.35.0", + "@lexical/react": "^0.35.0", + "@lexical/rich-text": "^0.35.0", + "@lexical/selection": "^0.35.0", + "@lexical/utils": "^0.35.0", + "@mdxeditor/gurx": "^1.2.4", + "@radix-ui/colors": "^3.0.0", + "@radix-ui/react-dialog": "^1.1.11", + "@radix-ui/react-icons": "^1.3.2", + "@radix-ui/react-popover": "^1.1.11", + "@radix-ui/react-popper": "^1.2.4", + "@radix-ui/react-select": "^2.2.2", + "@radix-ui/react-toggle-group": "^1.1.7", + "@radix-ui/react-toolbar": "^1.1.7", + "@radix-ui/react-tooltip": "^1.2.4", + "classnames": "^2.3.2", + "cm6-theme-basic-light": "^0.2.0", + "codemirror": "^6.0.1", + "downshift": "^7.6.0", + "js-yaml": "4.1.1", + "lexical": "^0.35.0", + "mdast-util-directive": "^3.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-frontmatter": "^2.0.1", + "mdast-util-gfm-strikethrough": "^2.0.0", + "mdast-util-gfm-table": "^2.0.0", + "mdast-util-gfm-task-list-item": "^2.0.0", + "mdast-util-highlight-mark": "^1.2.2", + "mdast-util-mdx": "^3.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-to-markdown": "^2.1.0", + "micromark-extension-directive": "^3.0.0", + "micromark-extension-frontmatter": "^2.0.0", + "micromark-extension-gfm-strikethrough": "^2.0.0", + "micromark-extension-gfm-table": "^2.0.0", + "micromark-extension-gfm-task-list-item": "^2.0.1", + "micromark-extension-highlight-mark": "^1.2.0", + "micromark-extension-mdx-jsx": "^3.0.0", + "micromark-extension-mdx-md": "^2.0.0", + "micromark-extension-mdxjs": "^3.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.1", + "micromark-util-symbol": "^2.0.0", + "react-hook-form": "^7.56.1", + "unidiff": "^1.0.2" + }, + "engines": { + "node": ">=16" + }, + "peerDependencies": { + "react": ">= 18 || >= 19", + "react-dom": ">= 18 || >= 19" + } + }, + "node_modules/@mdxeditor/gurx": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@mdxeditor/gurx/-/gurx-1.2.4.tgz", + "integrity": "sha512-9ZykIFYhKaXaaSPCs1cuI+FvYDegJjbKwmA4ASE/zY+hJY6EYqvoye4esiO85CjhOw9aoD/izD/CU78/egVqmg==", + "license": "MIT", + "engines": { + "node": ">=16" + }, + "peerDependencies": { + "react": ">= 18 || >= 19", + "react-dom": ">= 18 || >= 19" + } + }, "node_modules/@napi-rs/canvas": { "version": "0.1.100", "resolved": "https://registry.npmjs.org/@napi-rs/canvas/-/canvas-0.1.100.tgz", @@ -1546,6 +2611,805 @@ "node": "^22.20 || ^24.12 || >=25" } }, + "node_modules/@open-draft/deferred-promise": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@open-draft/deferred-promise/-/deferred-promise-2.2.0.tgz", + "integrity": "sha512-CecwLWx3rhxVQF6V4bAgPS5t+So2sTbPgAzafKkVizyi7tlwpcFpdFqq+wqF2OwNBmqFuu6tOyouTuxgpMfzmA==", + "license": "MIT" + }, + "node_modules/@radix-ui/colors": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/@radix-ui/colors/-/colors-3.0.0.tgz", + "integrity": "sha512-FUOsGBkHrYJwCSEtWRCIfQbZG7q1e6DgxCIOe1SUQzDe/7rXXeA47s8yCn6fuTNQAj1Zq4oTFi9Yjp3wzElcxg==", + "license": "MIT" + }, + "node_modules/@radix-ui/number": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/number/-/number-1.1.3.tgz", + "integrity": "sha512-Road2bidD0uu/1BGDOWNdPI06g0lIRy6IF9GZcIrDK2KGItfor8IQwQa+yM2ERgHM1MmHxaxpTzk0/Jp42lNfA==", + "license": "MIT" + }, + "node_modules/@radix-ui/primitive": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.2.0.tgz", + "integrity": "sha512-KABY+VMIRPJL+Vyzv/335FEhXXD/xDv8BMb1kl48/aXJZMH0LtHCTx5ga5RnxaEP3nZHtmTLf1P9vanmFX46bw==", + "license": "MIT" + }, + "node_modules/@radix-ui/react-arrow": { + "version": "1.1.17", + "resolved": "https://registry.npmjs.org/@radix-ui/react-arrow/-/react-arrow-1.1.17.tgz", + "integrity": "sha512-67jjcVvxjXCCStnTW3Z+M7jmaFMuMR7M2JgpDzH4w7JSRrikmzhjfYgP/09ECb8n7whnsgh1ifJ+Ie96qEj+pQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-primitive": "2.2.0" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-collection": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.2.0.tgz", + "integrity": "sha512-+yiQzqcc7Sy7/5s0jrMCjpPRFB3538VNrXPWdTLZhE/SCfgEws4aI6lHWN/vvcnyhHndROWBzqmqB4QBrITZ9Q==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.5", + "@radix-ui/react-context": "1.3.0", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-slot": "1.5.0", + "@radix-ui/react-use-layout-effect": "1.1.4" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-compose-refs": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.5.tgz", + "integrity": "sha512-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-context": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.3.0.tgz", + "integrity": "sha512-v5AYEocMISkbJ+1fTXzZpiFv7NRr3D2WiYbLIKf+FkmJ8VkP6d503eV2n34MFussHXY1pcoq3yfJiQH77dc4Mg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dialog": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dialog/-/react-dialog-1.3.1.tgz", + "integrity": "sha512-+0E4qvVTwjAWra9sEhJ+9BTsvHE00zkUuNw1VGh7S+Gc13dfYk+S1PVQdchWDj+XYHhAai7Z7IpzXVDCGsDplg==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.2.0", + "@radix-ui/react-compose-refs": "1.1.5", + "@radix-ui/react-context": "1.3.0", + "@radix-ui/react-dismissable-layer": "1.2.1", + "@radix-ui/react-focus-guards": "1.2.0", + "@radix-ui/react-focus-scope": "1.3.1", + "@radix-ui/react-id": "1.1.4", + "@radix-ui/react-portal": "1.2.0", + "@radix-ui/react-presence": "1.1.11", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-slot": "1.5.0", + "@radix-ui/react-use-controllable-state": "1.3.0", + "@radix-ui/react-use-layout-effect": "1.1.4", + "aria-hidden": "^1.2.4", + "react-remove-scroll": "^2.7.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-direction": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.2.0.tgz", + "integrity": "sha512-FtRA52a/r+LKStFT+neLUm+8vSe7wbzkbQGGeU8ixFiwC8NU14Evoq9ATECqL3eGbcUzJR4fyfA4KkK/q6dfqg==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-dismissable-layer": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.2.1.tgz", + "integrity": "sha512-KIfDcAsx+oVylFZ4xryVKusJUrLLhTQmfnJW4kwk4Km5myvhHCrj04hnWWUC166+xD4DHdH8tQGylwYX1h6+Pg==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.2.0", + "@radix-ui/react-compose-refs": "1.1.5", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-use-callback-ref": "1.1.5", + "@radix-ui/react-use-effect-event": "0.0.5" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-focus-guards": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.2.0.tgz", + "integrity": "sha512-MPm5R0iRGUDrDnPNxmLBkv+X7pN4XKzt+MbWJEuJQsH3NFH4omrbpXpucyYCCKTSt+na/ZxGhEWQrWTZ0285cA==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-focus-scope": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-scope/-/react-focus-scope-1.3.1.tgz", + "integrity": "sha512-ugeMhbXt4y5S2T1GnIqbWDKEN962PDwnX1fN0eKOOgf5f63Dh2mn8F1FUySlgW0iF6GiVsRF32DzuDIWTUyQJg==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.5", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-use-callback-ref": "1.1.5" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-icons": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@radix-ui/react-icons/-/react-icons-1.3.2.tgz", + "integrity": "sha512-fyQIhGDhzfc9pK2kH6Pl9c4BDJGfMkPqkyIgYDthyNYoNg3wVhoJMMh19WS4Up/1KMPFVpNsT2q3WmXn2N1m6g==", + "license": "MIT", + "peerDependencies": { + "react": "^16.x || ^17.x || ^18.x || ^19.0.0 || ^19.0.0-rc" + } + }, + "node_modules/@radix-ui/react-id": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.1.4.tgz", + "integrity": "sha512-TMQp2llA+RYn7JcjnrMnz7wN4pcVttPZnRZo52PLQsoLVKzNlVwUeHmfePgTgRluXFvlD3GD5g5MOVVTJCO0qA==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-layout-effect": "1.1.4" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popover": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-popover/-/react-popover-1.3.1.tgz", + "integrity": "sha512-ZNxvXRx5W2Wos4fXCXb5lpdqN0Z5chf+mStOUOTr4ik7d+62MRvoe9rzCA/eGNg36lxXqSrKEKmwuZEcUrIstw==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.2.0", + "@radix-ui/react-compose-refs": "1.1.5", + "@radix-ui/react-context": "1.3.0", + "@radix-ui/react-dismissable-layer": "1.2.1", + "@radix-ui/react-focus-guards": "1.2.0", + "@radix-ui/react-focus-scope": "1.3.1", + "@radix-ui/react-id": "1.1.4", + "@radix-ui/react-popper": "1.4.0", + "@radix-ui/react-portal": "1.2.0", + "@radix-ui/react-presence": "1.1.11", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-slot": "1.5.0", + "@radix-ui/react-use-controllable-state": "1.3.0", + "@radix-ui/react-use-layout-effect": "1.1.4", + "aria-hidden": "^1.2.4", + "react-remove-scroll": "^2.7.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-popper": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.4.0.tgz", + "integrity": "sha512-yCWRvLeGv9Pz3+efwHqGPp70mZ56r3kfIgQVF56Oj2aAa4uP/Tb+IE59wNcc+758rctqbCKx4LbK8II/r7Bn0Q==", + "license": "MIT", + "dependencies": { + "@floating-ui/react-dom": "^2.0.0", + "@radix-ui/react-arrow": "1.1.17", + "@radix-ui/react-compose-refs": "1.1.5", + "@radix-ui/react-context": "1.3.0", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-use-callback-ref": "1.1.5", + "@radix-ui/react-use-layout-effect": "1.1.4", + "@radix-ui/react-use-rect": "1.1.4", + "@radix-ui/react-use-size": "1.1.5", + "@radix-ui/rect": "1.1.3" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-portal": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.2.0.tgz", + "integrity": "sha512-StX7xXnaRU41VvFtMm9zlhVGz8XF6GmWWTXftkQaY+tqVkbs/R9UmAp5mLzHHapk5hM9RMZQvO/3usyIP/g42g==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-use-layout-effect": "1.1.4" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-presence": { + "version": "1.1.11", + "resolved": "https://registry.npmjs.org/@radix-ui/react-presence/-/react-presence-1.1.11.tgz", + "integrity": "sha512-Z7/atlkab36Z8hm+V8zYc79r0W+tiOB1o0tun1By94JyadkekLQmtEAnBSP9XKXBNQsStoStS4+gX10JpS5akA==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-layout-effect": "1.1.4" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-primitive": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.2.0.tgz", + "integrity": "sha512-HCTSPMNqv55Qk0IX4geJbpyXazmqulcimwuyjxTkKi29v+QZbG2Zho9BnbBq4YS2PF+KlNb2CXoLz66uUmblkg==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-slot": "1.5.0" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-roving-focus": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-roving-focus/-/react-roving-focus-1.2.1.tgz", + "integrity": "sha512-UwraORzVUeEPMclhO1p0vz0qI+TbdDLO9i+FiOqhJyHKwdpCRCck9yVEscUnAMIzCiuNoQa8D4A9bIpOPXGt6Q==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.2.0", + "@radix-ui/react-collection": "1.2.0", + "@radix-ui/react-compose-refs": "1.1.5", + "@radix-ui/react-context": "1.3.0", + "@radix-ui/react-direction": "1.2.0", + "@radix-ui/react-id": "1.1.4", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-use-callback-ref": "1.1.5", + "@radix-ui/react-use-controllable-state": "1.3.0", + "@radix-ui/react-use-is-hydrated": "0.1.3", + "@radix-ui/react-use-layout-effect": "1.1.4" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-select": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-select/-/react-select-2.4.1.tgz", + "integrity": "sha512-888ZwW0Md6GyptuqYABRX9nLKgoYfcooCyBBvVaX5Jp3e+8Jp2i4Zo/Uy50Hm+Ysn2JfloQXstW4U36w8teVtg==", + "license": "MIT", + "dependencies": { + "@radix-ui/number": "1.1.3", + "@radix-ui/primitive": "1.2.0", + "@radix-ui/react-collection": "1.2.0", + "@radix-ui/react-compose-refs": "1.1.5", + "@radix-ui/react-context": "1.3.0", + "@radix-ui/react-direction": "1.2.0", + "@radix-ui/react-dismissable-layer": "1.2.1", + "@radix-ui/react-focus-guards": "1.2.0", + "@radix-ui/react-focus-scope": "1.3.1", + "@radix-ui/react-id": "1.1.4", + "@radix-ui/react-popper": "1.4.0", + "@radix-ui/react-portal": "1.2.0", + "@radix-ui/react-presence": "1.1.11", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-slot": "1.5.0", + "@radix-ui/react-use-callback-ref": "1.1.5", + "@radix-ui/react-use-controllable-state": "1.3.0", + "@radix-ui/react-use-layout-effect": "1.1.4", + "@radix-ui/react-visually-hidden": "1.2.13", + "aria-hidden": "^1.2.4", + "react-remove-scroll": "^2.7.2" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-separator": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@radix-ui/react-separator/-/react-separator-1.2.0.tgz", + "integrity": "sha512-1jUAap0wZEqVP05Ou7kJgRxe/W+Qftng+rUNWGa0qkKbv9r5pWTG3E7a3ELKo2eJoHKMECnzuYrZpSyO1YgcYQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-primitive": "2.2.0" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-slot": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.5.0.tgz", + "integrity": "sha512-tyYd9ddPXAysAbdbD9eYxgwpCSv6f3PncqVSNKQFSR5lcJVLz3cb/pANDoYrLiHBpXv7skortyUgGUWsYuPPFQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-compose-refs": "1.1.5" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toggle": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-toggle/-/react-toggle-1.2.1.tgz", + "integrity": "sha512-+3MUq+WyiBplXYqQ0EIYlq8R4sLQ0T5NbOK7DMdDLCKO93pe2uE0DUJTWWfTBprpJJXxfoF3eMW0xpakVZrYsg==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.2.0", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-use-controllable-state": "1.3.0" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toggle-group": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-toggle-group/-/react-toggle-group-1.2.1.tgz", + "integrity": "sha512-O8Ldx5ao4p4KoW+DO8/PmkOe5mdKNi3F2SseqjVj88wvDGDHe60cUmO0Zm/uHsKrvNgQGV8Efpuh95Tht/h4vw==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.2.0", + "@radix-ui/react-context": "1.3.0", + "@radix-ui/react-direction": "1.2.0", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-roving-focus": "1.2.1", + "@radix-ui/react-toggle": "1.2.1", + "@radix-ui/react-use-controllable-state": "1.3.0" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-toolbar": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-toolbar/-/react-toolbar-1.2.1.tgz", + "integrity": "sha512-Cm8m7JTEeUdbfA6T9xgyu8HfOpyvSx8pB/wj0DlEuWaJe9FilIs4Az9wci/lU9RbthV/UkltszMw5WnnD+m/Ug==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.2.0", + "@radix-ui/react-context": "1.3.0", + "@radix-ui/react-direction": "1.2.0", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-roving-focus": "1.2.1", + "@radix-ui/react-separator": "1.2.0", + "@radix-ui/react-toggle-group": "1.2.1" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-tooltip": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/@radix-ui/react-tooltip/-/react-tooltip-1.4.1.tgz", + "integrity": "sha512-NxLFGSFtZ78zVfcoOhTwR1xwqo5qx1Jh8Pw6FMZ9McCaqfRzz7/gIRahs2Oy5XlPgQ+8QkUcKbN5B0U44J/kCg==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.2.0", + "@radix-ui/react-compose-refs": "1.1.5", + "@radix-ui/react-context": "1.3.0", + "@radix-ui/react-dismissable-layer": "1.2.1", + "@radix-ui/react-focus-scope": "1.3.1", + "@radix-ui/react-id": "1.1.4", + "@radix-ui/react-popper": "1.4.0", + "@radix-ui/react-portal": "1.2.0", + "@radix-ui/react-presence": "1.1.11", + "@radix-ui/react-primitive": "2.2.0", + "@radix-ui/react-slot": "1.5.0", + "@radix-ui/react-use-controllable-state": "1.3.0", + "@radix-ui/react-use-layout-effect": "1.1.4", + "@radix-ui/react-visually-hidden": "1.2.13" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-callback-ref": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.5.tgz", + "integrity": "sha512-Y5GBf4NKeADoXI1geiMlMuMoURT3k9MizzzKhGb/m55H94aGigZ01PIpkvsO6lML13BA6XYAXSJ6gza7vTn5nw==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-layout-effect": "1.1.4" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-controllable-state": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.3.0.tgz", + "integrity": "sha512-TAcBI7bw2ljYCbv4+zuTSd6zICu8pRt6SDN2vJ/Z06K2MXh6I9WYFe/A9ovlFDtR5HVHGm5iDxDoABm/++dbKg==", + "license": "MIT", + "dependencies": { + "@radix-ui/primitive": "1.2.0", + "@radix-ui/react-use-effect-event": "0.0.5", + "@radix-ui/react-use-layout-effect": "1.1.4" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-effect-event": { + "version": "0.0.5", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-effect-event/-/react-use-effect-event-0.0.5.tgz", + "integrity": "sha512-7cshFL8HGS/7HEiHH+9kL9HBwp2sa9yX18Knwek6KYWmXwM7pegMgta2AXMQKI+rq3JnfSj9x8wYqFMTdG1Jgg==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-layout-effect": "1.1.4" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-is-hydrated": { + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-is-hydrated/-/react-use-is-hydrated-0.1.3.tgz", + "integrity": "sha512-umO/aJ+82CpOnhDZUTbILCQf7kU/g0iv+oGs/Q8jw7IkhWBzaEP4sA268PhFAJTFetbwp3ICc6ktpI4TqtxcIw==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-layout-effect": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.4.tgz", + "integrity": "sha512-K20DkRkUwDnxEYMBPcg3Y6voLkEy5p5QQmszZgLngKKiC7dzBR/aEuK3w1qlx2JWDUNH6FluahYdgR3BP+QbYw==", + "license": "MIT", + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-rect": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-rect/-/react-use-rect-1.1.4.tgz", + "integrity": "sha512-cSOCh6JlkmfjLyNcLiu2nB4v+nm+dkZ+Q5KHWk/soo4U7ZLiEQFKHK9/YmtBHjfCEaU43IBKQOc4/uJmCaiCTQ==", + "license": "MIT", + "dependencies": { + "@radix-ui/rect": "1.1.3" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-use-size": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/@radix-ui/react-use-size/-/react-use-size-1.1.5.tgz", + "integrity": "sha512-V1McDQkMGzgivwqdu7u96APs7oi0Jvj9LTzgq3WWrDZqxWdAqU9yZnZQqk5OizGFR8badUQwZsrlao7MOlWYOA==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-use-layout-effect": "1.1.4" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/@radix-ui/react-visually-hidden": { + "version": "1.2.13", + "resolved": "https://registry.npmjs.org/@radix-ui/react-visually-hidden/-/react-visually-hidden-1.2.13.tgz", + "integrity": "sha512-feijiN1oPk4rck4u9Dm9tsU4mT6Wp9oeEEhaz1WUEs1VuqLf8xzsFG+Qk+uWq6TnMH9O+WRECRg0NftyP9E4Fw==", + "license": "MIT", + "dependencies": { + "@radix-ui/react-primitive": "2.2.0" + }, + "peerDependencies": { + "@types/react": "*", + "@types/react-dom": "*", + "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", + "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "@types/react-dom": { + "optional": true + } + } + }, + "node_modules/@radix-ui/rect": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/@radix-ui/rect/-/rect-1.1.3.tgz", + "integrity": "sha512-JtyZR+mqgBibTo8xea3B6ZRmzZiM/YeVBtUkas6zMuXjAlfIFIW2FgqeM9eLyvEaYX66vr6DJMK+4U6LV0KhNw==", + "license": "MIT" + }, + "node_modules/@react-hook/intersection-observer": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/@react-hook/intersection-observer/-/intersection-observer-3.1.2.tgz", + "integrity": "sha512-mWU3BMkmmzyYMSuhO9wu3eJVP21N8TcgYm9bZnTrMwuM818bEk+0NRM3hP+c/TqA9Ln5C7qE53p1H0QMtzYdvQ==", + "license": "MIT", + "dependencies": { + "@react-hook/passive-layout-effect": "^1.2.0", + "intersection-observer": "^0.10.0" + }, + "peerDependencies": { + "react": ">=16.8" + } + }, + "node_modules/@react-hook/passive-layout-effect": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@react-hook/passive-layout-effect/-/passive-layout-effect-1.2.1.tgz", + "integrity": "sha512-IwEphTD75liO8g+6taS+4oqz+nnroocNfWVHWz7j+N+ZO2vYrc6PV1q7GQhuahL0IOR7JccFTsFKQ/mb6iZWAg==", + "license": "MIT", + "peerDependencies": { + "react": ">=16.8" + } + }, "node_modules/@remix-run/router": { "version": "1.21.0", "resolved": "https://registry.npmjs.org/@remix-run/router/-/router-1.21.0.tgz", @@ -1905,6 +3769,12 @@ "win32" ] }, + "node_modules/@stitches/core": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@stitches/core/-/core-1.2.8.tgz", + "integrity": "sha512-Gfkvwk9o9kE9r9XNBmJRfV8zONvXThnm1tcuojL04Uy5uRyqg93DC83lDebl0rocZCfKSjUv+fWYtMQmEDJldg==", + "license": "MIT" + }, "node_modules/@types/babel__core": { "version": "7.20.5", "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz", @@ -1950,11 +3820,58 @@ "@babel/types": "^7.28.2" } }, + "node_modules/@types/debug": { + "version": "4.1.13", + "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz", + "integrity": "sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==", + "license": "MIT", + "dependencies": { + "@types/ms": "*" + } + }, "node_modules/@types/estree": { "version": "1.0.9", "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz", "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==", - "dev": true, + "license": "MIT" + }, + "node_modules/@types/estree-jsx": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/@types/estree-jsx/-/estree-jsx-1.0.5.tgz", + "integrity": "sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==", + "license": "MIT", + "dependencies": { + "@types/estree": "*" + } + }, + "node_modules/@types/hast": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.5.tgz", + "integrity": "sha512-rp/ezSWaD1m44dPKICGhiskI13nVr7qTloFwDa/IYkhhf5nzwP+zIQcIJh3WIFSBOy/H1PzB40jPjMDksN4F+g==", + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/mdast": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", + "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==", + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/ms": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz", + "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==", + "license": "MIT" + }, + "node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", "license": "MIT" }, "node_modules/@vitejs/plugin-react": { @@ -1977,6 +3894,72 @@ "vite": "^4.2.0 || ^5.0.0 || ^6.0.0" } }, + "node_modules/acorn": { + "version": "8.19.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.19.0.tgz", + "integrity": "sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==", + "license": "MIT", + "peer": true, + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/acorn-jsx": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz", + "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==", + "license": "MIT", + "peerDependencies": { + "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" + } + }, + "node_modules/anser": { + "version": "2.3.5", + "resolved": "https://registry.npmjs.org/anser/-/anser-2.3.5.tgz", + "integrity": "sha512-vcZjxvvVoxTeR5XBNJB38oTu/7eDCZlwdz32N1eNgpyPF7j/Z7Idf+CUwQOkKKpJ7RJyjxgLHCM7vdIK0iCNMQ==", + "license": "MIT" + }, + "node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "license": "Python-2.0" + }, + "node_modules/aria-hidden": { + "version": "1.2.6", + "resolved": "https://registry.npmjs.org/aria-hidden/-/aria-hidden-1.2.6.tgz", + "integrity": "sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==", + "license": "MIT", + "dependencies": { + "tslib": "^2.0.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/base64-js": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz", + "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, "node_modules/baseline-browser-mapping": { "version": "2.11.29", "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.29.tgz", @@ -2025,6 +4008,30 @@ "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7" } }, + "node_modules/buffer": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz", + "integrity": "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT", + "dependencies": { + "base64-js": "^1.3.1", + "ieee754": "^1.2.1" + } + }, "node_modules/caniuse-lite": { "version": "1.0.30001816", "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001816.tgz", @@ -2046,6 +4053,101 @@ ], "license": "CC-BY-4.0" }, + "node_modules/ccount": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz", + "integrity": "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz", + "integrity": "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-html4": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-2.1.0.tgz", + "integrity": "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-legacy": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz", + "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-reference-invalid": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz", + "integrity": "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/classnames": { + "version": "2.5.1", + "resolved": "https://registry.npmjs.org/classnames/-/classnames-2.5.1.tgz", + "integrity": "sha512-saHYOzhIQs6wy2sVxTM6bUDsQO4F50V9RQ22qBpEdCW+I+/Wmke2HOl6lS6dTpdxVhb88/I6+Hs+438c3lfUow==", + "license": "MIT" + }, + "node_modules/clean-set": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/clean-set/-/clean-set-1.1.2.tgz", + "integrity": "sha512-cA8uCj0qSoG9e0kevyOWXwPaELRPVg5Pxp6WskLMwerx257Zfnh8Nl0JBH59d7wQzij2CK7qEfJQK3RjuKKIug==", + "license": "MIT" + }, + "node_modules/cm6-theme-basic-light": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/cm6-theme-basic-light/-/cm6-theme-basic-light-0.2.0.tgz", + "integrity": "sha512-1prg2gv44sYfpHscP26uLT/ePrh0mlmVwMSoSd3zYKQ92Ab3jPRLzyCnpyOCQLJbK+YdNs4HvMRqMNYdy4pMhA==", + "license": "MIT", + "peerDependencies": { + "@codemirror/language": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.0.0", + "@lezer/highlight": "^1.0.0" + } + }, + "node_modules/codemirror": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/codemirror/-/codemirror-6.0.2.tgz", + "integrity": "sha512-VhydHotNW5w1UGK0Qj96BwSk/Zqbp9WbnyK2W/eVMv4QyF41INRGpjUhFJY7/uDNuudSc33a/PKr4iDqRduvHw==", + "license": "MIT", + "dependencies": { + "@codemirror/autocomplete": "^6.0.0", + "@codemirror/commands": "^6.0.0", + "@codemirror/language": "^6.0.0", + "@codemirror/lint": "^6.0.0", + "@codemirror/search": "^6.0.0", + "@codemirror/state": "^6.0.0", + "@codemirror/view": "^6.0.0" + } + }, + "node_modules/compute-scroll-into-view": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/compute-scroll-into-view/-/compute-scroll-into-view-2.0.4.tgz", + "integrity": "sha512-y/ZA3BGnxoM/QHHQ2Uy49CLtnWPbt4tTPpEEZiEmmiWBFKjej7nEyH8Ryz54jH0MLXflUYA3Er2zUxPSJu5R+g==", + "license": "MIT" + }, "node_modules/convert-source-map": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz", @@ -2053,11 +4155,29 @@ "dev": true, "license": "MIT" }, + "node_modules/crelt": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/crelt/-/crelt-1.0.7.tgz", + "integrity": "sha512-aK6BbWfhf4U/wCcLHKPJl/xa6VkVstRaPywWtMKGwuOLc/wZTyQYuoxgvZnNsBvv7Kg3YTBQYYBCggcviQczuA==", + "license": "MIT" + }, + "node_modules/d": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/d/-/d-1.0.2.tgz", + "integrity": "sha512-MOqHvMWF9/9MX6nza0KgvFH4HpMU0EF5uUDXqX/BtxtU8NfB0QzRtJ8Oe/6SuS4kbhyzVJwjd97EA4PKrzJ8bw==", + "license": "ISC", + "dependencies": { + "es5-ext": "^0.10.64", + "type": "^2.7.2" + }, + "engines": { + "node": ">=0.12" + } + }, "node_modules/debug": { "version": "4.4.3", "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", - "dev": true, "license": "MIT", "dependencies": { "ms": "^2.1.3" @@ -2071,6 +4191,28 @@ } } }, + "node_modules/decode-named-character-reference": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.3.0.tgz", + "integrity": "sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==", + "license": "MIT", + "dependencies": { + "character-entities": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/dequal": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", + "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, "node_modules/detect-libc": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz", @@ -2081,6 +4223,62 @@ "node": ">=8" } }, + "node_modules/detect-node-es": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/detect-node-es/-/detect-node-es-1.1.0.tgz", + "integrity": "sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==", + "license": "MIT" + }, + "node_modules/devlop": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz", + "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", + "license": "MIT", + "dependencies": { + "dequal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/diff": { + "version": "5.2.2", + "resolved": "https://registry.npmjs.org/diff/-/diff-5.2.2.tgz", + "integrity": "sha512-vtcDfH3TOjP8UekytvnHH1o1P4FcUdt4eQ1Y+Abap1tk/OB2MWQvcwS2ClCd1zuIhc3JKOx6p3kod8Vfys3E+A==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/dotenv": { + "version": "16.6.1", + "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz", + "integrity": "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==", + "license": "BSD-2-Clause", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://dotenvx.com" + } + }, + "node_modules/downshift": { + "version": "7.6.2", + "resolved": "https://registry.npmjs.org/downshift/-/downshift-7.6.2.tgz", + "integrity": "sha512-iOv+E1Hyt3JDdL9yYcOgW7nZ7GQ2Uz6YbggwXvKUSleetYhU2nXD482Rz6CzvM4lvI1At34BYruKAL4swRGxaA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.14.8", + "compute-scroll-into-view": "^2.0.4", + "prop-types": "^15.7.2", + "react-is": "^17.0.2", + "tslib": "^2.3.0" + }, + "peerDependencies": { + "react": ">=16.12.0" + } + }, "node_modules/electron-to-chromium": { "version": "1.5.458", "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.458.tgz", @@ -2088,6 +4286,46 @@ "dev": true, "license": "ISC" }, + "node_modules/es5-ext": { + "version": "0.10.64", + "resolved": "https://registry.npmjs.org/es5-ext/-/es5-ext-0.10.64.tgz", + "integrity": "sha512-p2snDhiLaXe6dahss1LddxqEm+SkuDvV8dnIQG0MWjyHpcMNfXKPE+/Cc0y+PhxJX3A4xGNeFCj5oc0BUh6deg==", + "hasInstallScript": true, + "license": "ISC", + "dependencies": { + "es6-iterator": "^2.0.3", + "es6-symbol": "^3.1.3", + "esniff": "^2.0.1", + "next-tick": "^1.1.0" + }, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/es6-iterator": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/es6-iterator/-/es6-iterator-2.0.3.tgz", + "integrity": "sha512-zw4SRzoUkd+cl+ZoE15A9o1oQd920Bb0iOJMQkQhl3jNc03YqVjAhG7scf9C5KWRU/R13Orf588uCC6525o02g==", + "license": "MIT", + "dependencies": { + "d": "1", + "es5-ext": "^0.10.35", + "es6-symbol": "^3.1.1" + } + }, + "node_modules/es6-symbol": { + "version": "3.1.4", + "resolved": "https://registry.npmjs.org/es6-symbol/-/es6-symbol-3.1.4.tgz", + "integrity": "sha512-U9bFFjX8tFiATgtkJ1zg25+KviIXpgRvRHS8sau3GfhVzThRQrOeksPeT0BWW2MNZs1OEWJ1DPXOQMn0KKRkvg==", + "license": "ISC", + "dependencies": { + "d": "^1.0.2", + "ext": "^1.7.0" + }, + "engines": { + "node": ">=0.12" + } + }, "node_modules/esbuild": { "version": "0.21.5", "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz", @@ -2137,6 +4375,103 @@ "node": ">=6" } }, + "node_modules/escape-carriage": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/escape-carriage/-/escape-carriage-1.3.1.tgz", + "integrity": "sha512-GwBr6yViW3ttx1kb7/Oh+gKQ1/TrhYwxKqVmg5gS+BK+Qe2KrOa/Vh7w3HPBvgGf0LfcDGoY9I6NHKoA5Hozhw==", + "license": "MIT" + }, + "node_modules/escape-string-regexp": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz", + "integrity": "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/esniff": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/esniff/-/esniff-2.0.1.tgz", + "integrity": "sha512-kTUIGKQ/mDPFoJ0oVfcmyJn4iBDRptjNVIzwIFR7tqWXdVI9xfA2RMwY/gbSpJG3lkdWNEjLap/NqVHZiJsdfg==", + "license": "ISC", + "dependencies": { + "d": "^1.0.1", + "es5-ext": "^0.10.62", + "event-emitter": "^0.3.5", + "type": "^2.7.2" + }, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/estree-util-is-identifier-name": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/estree-util-is-identifier-name/-/estree-util-is-identifier-name-3.0.0.tgz", + "integrity": "sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-visit": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/estree-util-visit/-/estree-util-visit-2.0.0.tgz", + "integrity": "sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/event-emitter": { + "version": "0.3.5", + "resolved": "https://registry.npmjs.org/event-emitter/-/event-emitter-0.3.5.tgz", + "integrity": "sha512-D9rRn9y7kLPnJ+hMq7S/nhvoKwwvVJahBi2BPmx3bvbsEdK3W9ii8cBSGjP+72/LnM4n6fo3+dkCX5FeTQruXA==", + "license": "MIT", + "dependencies": { + "d": "1", + "es5-ext": "~0.10.14" + } + }, + "node_modules/ext": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/ext/-/ext-1.7.0.tgz", + "integrity": "sha512-6hxeJYaL110a9b5TEJSj0gojyHQAmA2ch5Os+ySCiA1QGdS697XWY1pzsrSjqA9LDEEgdB/KypIlR59RcLuHYw==", + "license": "ISC", + "dependencies": { + "type": "^2.7.2" + } + }, + "node_modules/fault": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/fault/-/fault-2.0.1.tgz", + "integrity": "sha512-WtySTkS4OKev5JtpHXnib4Gxiurzh5NCGvWrFaZ34m6JehfTUhKZvn9njTfw48t6JumVQOmrKqpmGcdwxnhqBQ==", + "license": "MIT", + "dependencies": { + "format": "^0.2.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/format": { + "version": "0.2.2", + "resolved": "https://registry.npmjs.org/format/-/format-0.2.2.tgz", + "integrity": "sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww==", + "engines": { + "node": ">=0.4.x" + } + }, "node_modules/fsevents": { "version": "2.3.3", "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", @@ -2162,12 +4497,114 @@ "node": ">=6.9.0" } }, + "node_modules/get-nonce": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/get-nonce/-/get-nonce-1.0.1.tgz", + "integrity": "sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/ieee754": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz", + "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "BSD-3-Clause" + }, + "node_modules/intersection-observer": { + "version": "0.10.0", + "resolved": "https://registry.npmjs.org/intersection-observer/-/intersection-observer-0.10.0.tgz", + "integrity": "sha512-fn4bQ0Xq8FTej09YC/jqKZwtijpvARlRp6wxL5WTA6yPe2YWSJ5RJh7Nm79rK2qB0wr6iDQzH60XGq5V/7u8YQ==", + "deprecated": "The Intersection Observer polyfill is no longer needed and can safely be removed. Intersection Observer has been Baseline since 2019.", + "license": "W3C-20150513" + }, + "node_modules/is-alphabetical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", + "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-alphanumerical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz", + "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==", + "license": "MIT", + "dependencies": { + "is-alphabetical": "^2.0.0", + "is-decimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-decimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz", + "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-hexadecimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz", + "integrity": "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/isomorphic.js": { + "version": "0.2.5", + "resolved": "https://registry.npmjs.org/isomorphic.js/-/isomorphic.js-0.2.5.tgz", + "integrity": "sha512-PIeMbHqMt4DnUP3MA/Flc0HElYjMXArsw1qwJZcm9sqR8mq3l8NYizFMty0pWwE/tzIGH3EKK5+jes5mAr85yw==", + "license": "MIT", + "funding": { + "type": "GitHub Sponsors ❤", + "url": "https://github.com/sponsors/dmonad" + } + }, "node_modules/js-tokens": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==", "license": "MIT" }, + "node_modules/js-yaml": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz", + "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==", + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, "node_modules/jsesc": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz", @@ -2194,6 +4631,52 @@ "node": ">=6" } }, + "node_modules/kleur": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz", + "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/lexical": { + "version": "0.35.0", + "resolved": "https://registry.npmjs.org/lexical/-/lexical-0.35.0.tgz", + "integrity": "sha512-3VuV8xXhh5xJA6tzvfDvE0YBCMkIZUmxtRilJQDDdCgJCc+eut6qAv2qbN+pbqvarqcQqPN1UF+8YvsjmyOZpw==", + "license": "MIT" + }, + "node_modules/lib0": { + "version": "0.2.119", + "resolved": "https://registry.npmjs.org/lib0/-/lib0-0.2.119.tgz", + "integrity": "sha512-vh+TiejVy8Xm+hCdnRfn9BthGNvNUZdEXltNjVZL3TzRIKP3s1lnQh8pWd/Q0wCgY0FPAGVVjFF4ZiHUV3LFgA==", + "license": "MIT", + "dependencies": { + "isomorphic.js": "^0.2.4" + }, + "bin": { + "0ecdsa-generate-keypair": "bin/0ecdsa-generate-keypair.js", + "0gentesthtml": "bin/gentesthtml.js", + "0serve": "bin/0serve.js" + }, + "engines": { + "node": ">=16" + }, + "funding": { + "type": "GitHub Sponsors ❤", + "url": "https://github.com/sponsors/dmonad" + } + }, + "node_modules/longest-streak": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/longest-streak/-/longest-streak-3.1.0.tgz", + "integrity": "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/loose-envify": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz", @@ -2216,11 +4699,1013 @@ "yallist": "^3.0.2" } }, + "node_modules/lz-string": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz", + "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==", + "license": "MIT", + "bin": { + "lz-string": "bin/bin.js" + } + }, + "node_modules/markdown-table": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-3.0.4.tgz", + "integrity": "sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/mdast-util-directive": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/mdast-util-directive/-/mdast-util-directive-3.1.1.tgz", + "integrity": "sha512-Gqpa3MHorXYEZ0VfbroyvBlVKUfz371V6mIERqOYMcb0W1D3LwmFq1ZW4O2TDrbn+4ZmGLwMWeFRJgYZ+bc5fQ==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "micromark-util-character": "^2.0.0", + "parse-entities": "^4.0.0", + "stringify-entities": "^4.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-from-markdown": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.1.0.tgz", + "integrity": "sha512-KRLgmPaP2H1ul2bpoJkOS+9pAcDAAj9Nu1mqLnh8NLeJG5tlvj42TH80PIGBpROWlRXLk0lDrWNuZCFy/tsB4A==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "mdast-util-to-string": "^4.0.0", + "micromark": "^4.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-decode-string": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-frontmatter": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-frontmatter/-/mdast-util-frontmatter-2.0.1.tgz", + "integrity": "sha512-LRqI9+wdgC25P0URIJY9vwocIzCcksduHQ9OF2joxQoyTNVduwLAFUzjoopuRJbJAReaKrNQKAZKL3uCMugWJA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "escape-string-regexp": "^5.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "micromark-extension-frontmatter": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-strikethrough": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-strikethrough/-/mdast-util-gfm-strikethrough-2.0.1.tgz", + "integrity": "sha512-OuJHqvr455pwu2OaOrir7dbzqs4jlWKOtlu9L6GjcIjjQwNyw02VntQsr/Ek6/A13vgnXfUhBekWRUP1OkNivw==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-table": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-table/-/mdast-util-gfm-table-2.0.0.tgz", + "integrity": "sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "markdown-table": "^3.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-task-list-item": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-task-list-item/-/mdast-util-gfm-task-list-item-2.0.0.tgz", + "integrity": "sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-highlight-mark": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/mdast-util-highlight-mark/-/mdast-util-highlight-mark-1.2.2.tgz", + "integrity": "sha512-OYumVoytj+B9YgwzBhBcYUCLYHIPvJtAvwnMyKhUXbfUFuER5S+FDZyu9fadUxm2TCT5fRYK3jQXh2ioWAxrMw==", + "license": "MIT", + "dependencies": { + "micromark-extension-highlight-mark": "1.2.0" + } + }, + "node_modules/mdast-util-mdx": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-mdx/-/mdast-util-mdx-3.0.0.tgz", + "integrity": "sha512-JfbYLAW7XnYTTbUsmpu0kdBUVe+yKVJZBItEjwyYJiDJuZ9w4eeaqks4HQO+R7objWgS2ymV60GYpI14Ug554w==", + "license": "MIT", + "dependencies": { + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-mdx-expression": "^2.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx-expression": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-mdx-expression/-/mdast-util-mdx-expression-2.0.1.tgz", + "integrity": "sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx-jsx": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-mdx-jsx/-/mdast-util-mdx-jsx-3.2.0.tgz", + "integrity": "sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "devlop": "^1.1.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "parse-entities": "^4.0.0", + "stringify-entities": "^4.0.0", + "unist-util-stringify-position": "^4.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdxjs-esm": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-mdxjs-esm/-/mdast-util-mdxjs-esm-2.0.1.tgz", + "integrity": "sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-phrasing": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-phrasing/-/mdast-util-phrasing-4.1.0.tgz", + "integrity": "sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-markdown": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-2.2.0.tgz", + "integrity": "sha512-2Jn/ADrHFFyyniBMi0bncTbJqU78K3/TEYvzvwrWWzD9MYPUa/Gm4r3nOeKFQg/PDM5BsbDYdc8ackW4NTY6NA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "longest-streak": "^3.0.0", + "mdast-util-phrasing": "^4.0.0", + "mdast-util-to-string": "^4.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-decode-string": "^2.0.0", + "micromark-util-html-tag-name": "^2.0.0", + "unist-util-visit": "^5.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-string": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-4.0.0.tgz", + "integrity": "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.3.tgz", + "integrity": "sha512-oGYfQzHSG5dOMovQcJ3fyTmZlWAWpi0XA0sJwJs+i6OT88o1+Jtw/8z0CmdowSLxGhhFK89rQ/oXph/wN02PNw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/debug": "^4.0.0", + "debug": "^4.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-edit-map": "^1.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-core-commonmark": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-2.0.4.tgz", + "integrity": "sha512-wxEeE8v8XVvOrxn1TZj74qYhAtTQsSqufHVS3uNVyT1MupXxhyaHk8/9xDNPh9BmL77QNDgWTkZ3RsYHB2ry7w==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-destination": "^2.0.0", + "micromark-factory-label": "^2.0.0", + "micromark-factory-space": "^2.1.0", + "micromark-factory-title": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-edit-map": "^1.0.0", + "micromark-util-html-tag-name": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.3" + } + }, + "node_modules/micromark-extension-directive": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/micromark-extension-directive/-/micromark-extension-directive-3.0.2.tgz", + "integrity": "sha512-wjcXHgk+PPdmvR58Le9d7zQYWy+vKEU9Se44p2CrCDPiLr2FMyiT4Fyb5UFKFC66wGB3kPlgD7q3TnoqPS7SZA==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "parse-entities": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-frontmatter": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-frontmatter/-/micromark-extension-frontmatter-2.0.0.tgz", + "integrity": "sha512-C4AkuM3dA58cgZha7zVnuVxBhDsbttIMiytjgsM2XbHAB2faRVaHRle40558FBN+DJcrLNCoqG5mlrpdU4cRtg==", + "license": "MIT", + "dependencies": { + "fault": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-strikethrough": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-strikethrough/-/micromark-extension-gfm-strikethrough-2.1.0.tgz", + "integrity": "sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-table": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.2.tgz", + "integrity": "sha512-pRzm4kDTu0MjlmBkxmS9yYhw60nncfcEwu9NNdPFSQEFXS95ZKyIIyTSHu/o3ReBUrLKYEq+7YaXCRn/bPB4MA==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-task-list-item": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-task-list-item/-/micromark-extension-gfm-task-list-item-2.1.0.tgz", + "integrity": "sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==", + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-highlight-mark": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/micromark-extension-highlight-mark/-/micromark-extension-highlight-mark-1.2.0.tgz", + "integrity": "sha512-huGtbd/9kQsMk8u7nrVMaS5qH/47yDG6ZADggo5Owz5JoY8wdfQjfuy118/QiYNCvdFuFDbzT0A7K7Hp2cBsXA==", + "license": "MIT", + "dependencies": { + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "uvu": "^0.5.6" + } + }, + "node_modules/micromark-extension-mdx-expression": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-expression/-/micromark-extension-mdx-expression-3.0.1.tgz", + "integrity": "sha512-dD/ADLJ1AeMvSAKBwO22zG22N4ybhe7kFIZ3LsDI0GlsNr2A3KYxb0LdC1u5rj4Nw+CHKY0RVdnHX8vj8ejm4Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-mdx-expression": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-extension-mdx-jsx": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-jsx/-/micromark-extension-mdx-jsx-3.0.2.tgz", + "integrity": "sha512-e5+q1DjMh62LZAJOnDraSSbDMvGJ8x3cbjygy2qFEi7HCeUT4BDKCvMozPozcD6WmOt6sVvYDNBKhFSz3kjOVQ==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "micromark-factory-mdx-expression": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdx-md": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-md/-/micromark-extension-mdx-md-2.0.0.tgz", + "integrity": "sha512-EpAiszsB3blw4Rpba7xTOUptcFeBFi+6PY8VnJ2hhimH+vCQDirWgsMpz7w1XcZE7LVrSAUGb9VJpG9ghlYvYQ==", + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdxjs": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdxjs/-/micromark-extension-mdxjs-3.0.0.tgz", + "integrity": "sha512-A873fJfhnJ2siZyUrJ31l34Uqwy4xIFmvPY1oj+Ean5PHcPBYzEsvqvWGaWcfEIr11O5Dlw3p2y0tZWpKHDejQ==", + "license": "MIT", + "dependencies": { + "acorn": "^8.0.0", + "acorn-jsx": "^5.0.0", + "micromark-extension-mdx-expression": "^3.0.0", + "micromark-extension-mdx-jsx": "^3.0.0", + "micromark-extension-mdx-md": "^2.0.0", + "micromark-extension-mdxjs-esm": "^3.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdxjs-esm": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdxjs-esm/-/micromark-extension-mdxjs-esm-3.0.0.tgz", + "integrity": "sha512-DJFl4ZqkErRpq/dAPyeWp15tGrcrrJho1hKK5uBS70BCtfrIFg81sqcTVu3Ta+KD1Tk5vAtBNElWxtAa+m8K9A==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-position-from-estree": "^2.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-factory-destination": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz", + "integrity": "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-label": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-2.0.1.tgz", + "integrity": "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-mdx-expression": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-factory-mdx-expression/-/micromark-factory-mdx-expression-2.0.3.tgz", + "integrity": "sha512-kQnEtA3vzucU2BkrIa8/VaSAsP+EJ3CKOvhMuJgOEGg9KDC6OAY6nSnNDVRiVNRqj7Y4SlSzcStaH/5jge8JdQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-position-from-estree": "^2.0.0", + "vfile-message": "^4.0.0" + } + }, + "node_modules/micromark-factory-space": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-2.1.0.tgz", + "integrity": "sha512-fS8hnLIjnjvdQIj39Geug8wWsR0HrYZ43KShKxNfwT7t2LOHo/LbWZEzEaSOjwtjdCsjoE6syHhonEzW0zv0+Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-title": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-2.0.1.tgz", + "integrity": "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-whitespace": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-2.0.1.tgz", + "integrity": "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-character": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz", + "integrity": "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-chunked": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-2.0.1.tgz", + "integrity": "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-classify-character": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-2.0.1.tgz", + "integrity": "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-combine-extensions": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-2.0.1.tgz", + "integrity": "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-chunked": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-numeric-character-reference": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-2.0.2.tgz", + "integrity": "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-string": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-decode-string/-/micromark-util-decode-string-2.0.1.tgz", + "integrity": "sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-edit-map": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/micromark-util-edit-map/-/micromark-util-edit-map-1.0.0.tgz", + "integrity": "sha512-Pa2ljlsEL6sVwFaYeyrOLSYbQt73JvGbPOYFq+9AElXiSnfI5Q4465RRZ1sHv7lDjDOnGRDDaqPXqClqWK/q1Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-encode": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.1.tgz", + "integrity": "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-events-to-acorn": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-util-events-to-acorn/-/micromark-util-events-to-acorn-2.0.3.tgz", + "integrity": "sha512-jmsiEIiZ1n7X1Rr5k8wVExBQCg5jy4UXVADItHmNk1zkwEVhBuIUKRu3fqv+hs4nxLISi2DQGlqIOGiFxgbfHg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/unist": "^3.0.0", + "devlop": "^1.0.0", + "estree-util-visit": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "vfile-message": "^4.0.0" + } + }, + "node_modules/micromark-util-html-tag-name": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-2.0.1.tgz", + "integrity": "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-normalize-identifier": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-2.0.1.tgz", + "integrity": "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-resolve-all": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-2.0.1.tgz", + "integrity": "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-sanitize-uri": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.1.tgz", + "integrity": "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-subtokenize": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-2.1.0.tgz", + "integrity": "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-symbol": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.1.tgz", + "integrity": "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-types": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.3.tgz", + "integrity": "sha512-oxB2Ik03hI0gv+VNn9tnh1t1YEe9MDPptViAEgfdf3YQHsn0pzGTgCdlSCJXcwhqm8phaEuM7zeEu3QQzVBrPg==", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/mime-db": { + "version": "1.54.0", + "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz", + "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mri": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz", + "integrity": "sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==", + "license": "MIT", + "engines": { + "node": ">=4" + } + }, "node_modules/ms": { "version": "2.1.3", "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", - "dev": true, "license": "MIT" }, "node_modules/nanoid": { @@ -2242,6 +5727,12 @@ "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" } }, + "node_modules/next-tick": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/next-tick/-/next-tick-1.1.0.tgz", + "integrity": "sha512-CXdUiJembsNjuToQvxayPZF9Vqht7hewsvy2sOWafLvi2awflj9mOC6bHIg50orX8IJvWKY9wYQ/zB2kogPslQ==", + "license": "ISC" + }, "node_modules/node-releases": { "version": "2.0.59", "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.59.tgz", @@ -2252,6 +5743,46 @@ "node": ">=18" } }, + "node_modules/object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/outvariant": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/outvariant/-/outvariant-1.4.0.tgz", + "integrity": "sha512-AlWY719RF02ujitly7Kk/0QlV+pXGFDHrHf9O2OKqyqgBieaPOIeuSkL8sRK6j2WK+/ZAURq2kZsY0d8JapUiw==", + "license": "MIT" + }, + "node_modules/parse-entities": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz", + "integrity": "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "character-entities-legacy": "^3.0.0", + "character-reference-invalid": "^2.0.0", + "decode-named-character-reference": "^1.0.0", + "is-alphanumerical": "^2.0.0", + "is-decimal": "^2.0.0", + "is-hexadecimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/parse-entities/node_modules/@types/unist": { + "version": "2.0.11", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz", + "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==", + "license": "MIT" + }, "node_modules/pdfjs-dist": { "version": "4.10.38", "resolved": "https://registry.npmjs.org/pdfjs-dist/-/pdfjs-dist-4.10.38.tgz", @@ -2300,6 +5831,32 @@ "node": "^10 || ^12 || >=14" } }, + "node_modules/prismjs": { + "version": "1.30.0", + "resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.30.0.tgz", + "integrity": "sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/prop-types": { + "version": "15.8.1", + "resolved": "https://registry.npmjs.org/prop-types/-/prop-types-15.8.1.tgz", + "integrity": "sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==", + "license": "MIT", + "dependencies": { + "loose-envify": "^1.4.0", + "object-assign": "^4.1.1", + "react-is": "^16.13.1" + } + }, + "node_modules/prop-types/node_modules/react-is": { + "version": "16.13.1", + "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz", + "integrity": "sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==", + "license": "MIT" + }, "node_modules/react": { "version": "18.3.1", "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz", @@ -2313,6 +5870,15 @@ "node": ">=0.10.0" } }, + "node_modules/react-devtools-inline": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/react-devtools-inline/-/react-devtools-inline-4.4.0.tgz", + "integrity": "sha512-ES0GolSrKO8wsKbsEkVeiR/ZAaHQTY4zDh1UW8DImVmm8oaGLl3ijJDvSGe+qDRKPZdPRnDtWWnSvvrgxXdThQ==", + "license": "MIT", + "dependencies": { + "es6-symbol": "^3" + } + }, "node_modules/react-dom": { "version": "18.3.1", "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz", @@ -2327,6 +5893,50 @@ "react": "^18.3.1" } }, + "node_modules/react-error-boundary": { + "version": "3.1.4", + "resolved": "https://registry.npmjs.org/react-error-boundary/-/react-error-boundary-3.1.4.tgz", + "integrity": "sha512-uM9uPzZJTF6wRQORmSrvOIgt4lJ9MC1sNgEOj2XGsDTRE4kmpWxg7ENK9EWNKJRMAOY9z0MuF4yIfl6gp4sotA==", + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.12.5" + }, + "engines": { + "node": ">=10", + "npm": ">=6" + }, + "peerDependencies": { + "react": ">=16.13.1" + } + }, + "node_modules/react-hook-form": { + "version": "7.90.0", + "resolved": "https://registry.npmjs.org/react-hook-form/-/react-hook-form-7.90.0.tgz", + "integrity": "sha512-+NdG0FLzCPhFOp2NNxaUYLF9fyZhNjx9FTBBSYWF71/l6BBlmIc/j6xlp3DbaHWLJbIG7Zd8oznA19xJClU97w==", + "license": "MIT", + "engines": { + "node": ">=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/react-hook-form" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8.0 || ^17 || ^18 || ^19" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/react-is": { + "version": "17.0.2", + "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz", + "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==", + "license": "MIT" + }, "node_modules/react-refresh": { "version": "0.14.2", "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.14.2.tgz", @@ -2337,6 +5947,53 @@ "node": ">=0.10.0" } }, + "node_modules/react-remove-scroll": { + "version": "2.7.2", + "resolved": "https://registry.npmjs.org/react-remove-scroll/-/react-remove-scroll-2.7.2.tgz", + "integrity": "sha512-Iqb9NjCCTt6Hf+vOdNIZGdTiH1QSqr27H/Ek9sv/a97gfueI/5h1s3yRi1nngzMUaOOToin5dI1dXKdXiF+u0Q==", + "license": "MIT", + "dependencies": { + "react-remove-scroll-bar": "^2.3.7", + "react-style-singleton": "^2.2.3", + "tslib": "^2.1.0", + "use-callback-ref": "^1.3.3", + "use-sidecar": "^1.1.3" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/react-remove-scroll-bar": { + "version": "2.3.8", + "resolved": "https://registry.npmjs.org/react-remove-scroll-bar/-/react-remove-scroll-bar-2.3.8.tgz", + "integrity": "sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==", + "license": "MIT", + "dependencies": { + "react-style-singleton": "^2.2.2", + "tslib": "^2.0.0" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, "node_modules/react-router": { "version": "6.28.1", "resolved": "https://registry.npmjs.org/react-router/-/react-router-6.28.1.tgz", @@ -2369,6 +6026,28 @@ "react-dom": ">=16.8" } }, + "node_modules/react-style-singleton": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/react-style-singleton/-/react-style-singleton-2.2.3.tgz", + "integrity": "sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==", + "license": "MIT", + "dependencies": { + "get-nonce": "^1.0.0", + "tslib": "^2.0.0" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, "node_modules/rollup": { "version": "4.64.7", "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.64.7.tgz", @@ -2415,6 +6094,18 @@ "fsevents": "~2.3.2" } }, + "node_modules/sade": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/sade/-/sade-1.8.1.tgz", + "integrity": "sha512-xal3CZX1Xlo/k4ApwCFrHVACi9fBqJ7V+mwhBsuf/1IOKbBy098Fex+Wa/5QMubw09pSZ/u8EY8PWgevJsXp1A==", + "license": "MIT", + "dependencies": { + "mri": "^1.1.0" + }, + "engines": { + "node": ">=6" + } + }, "node_modules/scheduler": { "version": "0.23.2", "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz", @@ -2507,13 +6198,138 @@ "node": ">=0.10.0" } }, + "node_modules/static-browser-server": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/static-browser-server/-/static-browser-server-1.0.3.tgz", + "integrity": "sha512-ZUyfgGDdFRbZGGJQ1YhiM930Yczz5VlbJObrQLlk24+qNHVQx4OlLcYswEUo3bIyNAbQUIUR9Yr5/Hqjzqb4zA==", + "license": "Apache-2.0", + "dependencies": { + "@open-draft/deferred-promise": "^2.1.0", + "dotenv": "^16.0.3", + "mime-db": "^1.52.0", + "outvariant": "^1.3.0" + } + }, + "node_modules/strict-event-emitter": { + "version": "0.4.6", + "resolved": "https://registry.npmjs.org/strict-event-emitter/-/strict-event-emitter-0.4.6.tgz", + "integrity": "sha512-12KWeb+wixJohmnwNFerbyiBrAlq5qJLwIt38etRtKtmmHyDSoGlIqFE9wx+4IwG0aDjI7GV8tc8ZccjWZZtTg==", + "license": "MIT" + }, + "node_modules/stringify-entities": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz", + "integrity": "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==", + "license": "MIT", + "dependencies": { + "character-entities-html4": "^2.0.0", + "character-entities-legacy": "^3.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/style-mod": { + "version": "4.1.4", + "resolved": "https://registry.npmjs.org/style-mod/-/style-mod-4.1.4.tgz", + "integrity": "sha512-XXWIQt633/EpAFx8aZDOTjBzrCaGmhvEQlQo6MVPfa2OzO2cWo+4hV9h+6UkHYlXGfy+ODXKUdP7Pthmcu5ATw==", + "license": "MIT" + }, + "node_modules/tabbable": { + "version": "6.5.0", + "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.5.0.tgz", + "integrity": "sha512-wieBHXygIm7OyQOu5hQlkk62/WyCFYGlWg7L6/ZCUZwx0o398Zkn4pVmMyfYhfMG8kGrj/Krt8eIk6UKC6VzwA==", + "license": "MIT" + }, "node_modules/tslib": { "version": "2.8.1", "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", - "dev": true, - "license": "0BSD", - "optional": true + "license": "0BSD" + }, + "node_modules/type": { + "version": "2.7.3", + "resolved": "https://registry.npmjs.org/type/-/type-2.7.3.tgz", + "integrity": "sha512-8j+1QmAbPvLZow5Qpi6NCaN8FB60p/6x8/vfNqOk/hC+HuvFZhL4+WfekuhQLiqFZXOgQdrs3B+XxEmCc6b3FQ==", + "license": "ISC" + }, + "node_modules/unidiff": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/unidiff/-/unidiff-1.0.4.tgz", + "integrity": "sha512-ynU0vsAXw0ir8roa+xPCUHmnJ5goc5BTM2Kuc3IJd8UwgaeRs7VSD5+eeaQL+xp1JtB92hu/Zy/Lgy7RZcr1pQ==", + "license": "MIT", + "dependencies": { + "diff": "^5.1.0" + } + }, + "node_modules/unist-util-is": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.1.tgz", + "integrity": "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-position-from-estree": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/unist-util-position-from-estree/-/unist-util-position-from-estree-2.0.0.tgz", + "integrity": "sha512-KaFVRjoqLyF6YXCbVLNad/eS4+OfPQQn2yOd7zF/h5T/CSL2v8NpN6a5TPvtbXthAGw5nG+PuTtq+DdIZr+cRQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-stringify-position": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz", + "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.1.0.tgz", + "integrity": "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-parents": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-6.0.2.tgz", + "integrity": "sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } }, "node_modules/update-browserslist-db": { "version": "1.3.4", @@ -2546,6 +6362,81 @@ "browserslist": ">= 4.21.0" } }, + "node_modules/use-callback-ref": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/use-callback-ref/-/use-callback-ref-1.3.3.tgz", + "integrity": "sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==", + "license": "MIT", + "dependencies": { + "tslib": "^2.0.0" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/use-sidecar": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/use-sidecar/-/use-sidecar-1.1.3.tgz", + "integrity": "sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==", + "license": "MIT", + "dependencies": { + "detect-node-es": "^1.1.0", + "tslib": "^2.0.0" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "@types/react": "*", + "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + } + } + }, + "node_modules/uvu": { + "version": "0.5.6", + "resolved": "https://registry.npmjs.org/uvu/-/uvu-0.5.6.tgz", + "integrity": "sha512-+g8ENReyr8YsOc6fv/NVJs2vFdHBnBNdfE49rshrTzDWOlUx4Gq7KOS2GD8eqhy2j+Ejq29+SbKH8yjkAqXqoA==", + "license": "MIT", + "dependencies": { + "dequal": "^2.0.0", + "diff": "^5.0.0", + "kleur": "^4.0.3", + "sade": "^1.7.3" + }, + "bin": { + "uvu": "bin.js" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/vfile-message": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.3.tgz", + "integrity": "sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/vite": { "version": "5.4.11", "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.11.tgz", @@ -2607,12 +6498,46 @@ } } }, + "node_modules/w3c-keyname": { + "version": "2.2.8", + "resolved": "https://registry.npmjs.org/w3c-keyname/-/w3c-keyname-2.2.8.tgz", + "integrity": "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==", + "license": "MIT" + }, "node_modules/yallist": { "version": "3.1.1", "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz", "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==", "dev": true, "license": "ISC" + }, + "node_modules/yjs": { + "version": "13.6.33", + "resolved": "https://registry.npmjs.org/yjs/-/yjs-13.6.33.tgz", + "integrity": "sha512-q/UYvr1gOk4XII+Cu1CW2dINjYqJJFifTzogEaIARznrvX7uOlHsdTEXcnOBMuIsrCGEEKdNxi74kyMLZlKVfw==", + "license": "MIT", + "peer": true, + "dependencies": { + "lib0": "^0.2.99" + }, + "engines": { + "node": ">=16.0.0", + "npm": ">=8.0.0" + }, + "funding": { + "type": "GitHub Sponsors ❤", + "url": "https://github.com/sponsors/dmonad" + } + }, + "node_modules/zwitch": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz", + "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } } } } diff --git a/frontend/package.json b/frontend/package.json index a9a3d19..4e0351c 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -8,6 +8,7 @@ "preview": "vite preview" }, "dependencies": { + "@mdxeditor/editor": "3.52.4", "pdfjs-dist": "^4.10.38", "react": "18.3.1", "react-dom": "18.3.1", diff --git a/frontend/src/api.js b/frontend/src/api.js index 261a807..3af0986 100644 --- a/frontend/src/api.js +++ b/frontend/src/api.js @@ -160,6 +160,17 @@ export async function downloadFile(elementId, context, filename) { URL.revokeObjectURL(url); } +export async function fetchBlob(path) { + const response = await fetch(path, { credentials: "include", headers: scopeHeaders() }); + if (!response.ok) { + const data = await response.json().catch(() => null); + const error = new Error(data?.detail || "Die Vorschau ist nicht verfügbar."); + error.status = response.status; + throw error; + } + return response.blob(); +} + export async function downloadPost(path, body, fallbackName) { const headers = { ...scopeHeaders(), "Content-Type": "application/json" }; if (csrf) headers["X-CSRF-Token"] = csrf; diff --git a/frontend/src/markdown.jsx b/frontend/src/markdown.jsx index 14fce46..d3826ae 100644 --- a/frontend/src/markdown.jsx +++ b/frontend/src/markdown.jsx @@ -14,9 +14,7 @@ function inline(text, keyPrefix) { else if (token.startsWith("`")) nodes.push({token.slice(1, -1)}); else { const linked = token.match(/^\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)$/); - if (linked) { - nodes.push({linked[1]}); - } + if (linked) nodes.push({linked[1]}); } last = match.index + token.length; index += 1; @@ -29,13 +27,37 @@ export function MarkdownView({ text }) { const lines = String(text || "").replace(/\r\n/g, "\n").split("\n"); const blocks = []; let list = null; + let index = 0; function closeList() { if (!list) return; - const items = list.items.map((item, index) =>
  • {inline(item, `${list.key}-${index}`)}
  • ); + const items = list.items.map((item, itemIndex) =>
  • {inline(item, `${list.key}-${itemIndex}`)}
  • ); blocks.push(list.ordered ?
      {items}
    :
      {items}
    ); list = null; } - lines.forEach((line, index) => { + while (index < lines.length) { + const line = lines[index]; + if (line.startsWith("```")) { + closeList(); + const body = []; + index += 1; + while (index < lines.length && !lines[index].startsWith("```")) { + body.push(lines[index]); + index += 1; + } + blocks.push(
    {body.join("\n")}
    ); + index += 1; + continue; + } + if (line.startsWith(">")) { + closeList(); + const body = []; + while (index < lines.length && lines[index].startsWith(">")) { + body.push(lines[index].replace(/^>\s?/, "")); + index += 1; + } + blocks.push(
    {body.map((item, itemIndex) =>

    {inline(item, `q-${index}-${itemIndex}`)}

    )}
    ); + continue; + } const heading = line.match(/^(#{1,3})\s+(.*)$/); const bullet = line.match(/^\s*[-*]\s+(.*)$/); const numbered = line.match(/^\s*\d+\.\s+(.*)$/); @@ -43,7 +65,8 @@ export function MarkdownView({ text }) { closeList(); const Tag = heading[1].length === 1 ? "h3" : heading[1].length === 2 ? "h4" : "h5"; blocks.push({inline(heading[2], `h-${index}`)}); - return; + index += 1; + continue; } if (bullet || numbered) { if (!list || list.ordered !== Boolean(numbered)) { @@ -51,15 +74,18 @@ export function MarkdownView({ text }) { list = { key: `l-${index}`, ordered: Boolean(numbered), items: [] }; } list.items.push((bullet || numbered)[1]); - return; + index += 1; + continue; } closeList(); if (!line.trim()) { blocks.push(); - return; + index += 1; + continue; } blocks.push(

    {inline(line, `p-${index}`)}

    ); - }); + index += 1; + } closeList(); return
    {blocks}
    ; } diff --git a/frontend/src/notes.jsx b/frontend/src/notes.jsx new file mode 100644 index 0000000..d4c6ef3 --- /dev/null +++ b/frontend/src/notes.jsx @@ -0,0 +1,174 @@ +import { useRef, useState } from "react"; +import { + BlockTypeSelect, + BoldItalicUnderlineToggles, + CodeToggle, + CreateLink, + DiffSourceToggleWrapper, + InsertCodeBlock, + ListsToggle, + MDXEditor, + UndoRedo, + codeBlockPlugin, + codeMirrorPlugin, + diffSourcePlugin, + headingsPlugin, + linkDialogPlugin, + linkPlugin, + listsPlugin, + markdownShortcutPlugin, + quotePlugin, + toolbarPlugin, +} from "@mdxeditor/editor"; +import "@mdxeditor/editor/style.css"; +import { MarkdownView } from "./markdown.jsx"; + +const LABELS = { + "toolbar.bold": "Fett", + "toolbar.removeBold": "Fett aufheben", + "toolbar.italic": "Kursiv", + "toolbar.removeItalic": "Kursiv aufheben", + "toolbar.richText": "Formatierte Ansicht", + "toolbar.source": "Markdown-Quelltext", + "toolbar.undo": "Rückgängig {{shortcut}}", + "toolbar.redo": "Wiederholen {{shortcut}}", + "toolbar.bulletedList": "Aufzählung", + "toolbar.numberedList": "Nummerierte Liste", + "toolbar.inlineCode": "Code im Text", + "toolbar.removeInlineCode": "Code im Text aufheben", + "toolbar.link": "Link", + "toolbar.codeBlock": "Codeblock", + "toolbar.blockTypes.paragraph": "Absatz", + "toolbar.blockTypes.quote": "Zitat", + "toolbar.blockTypes.heading": "Überschrift {{level}}", + "toolbar.toggleGroup": "Ansicht", + "dialog.link.url": "Adresse", + "dialog.link.text": "Text", + "dialog.link.title": "Link", + "dialog.link.save": "Übernehmen", + "dialog.link.cancel": "Abbrechen", +}; + +function translate(key, fallback, interpolations) { + let text = LABELS[key] || fallback; + if (interpolations) { + for (const [name, value] of Object.entries(interpolations)) { + text = text.replaceAll(`{{${name}}}`, String(value)); + } + } + return text; +} + +function comparable(value) { + return String(value || "").replace(/\r\n/g, "\n").replace(/\s+$/g, "").replace(/^(\s*)[-+*](\s+)/gm, "$1-$2"); +} + +function wrapSelection(field, before, after, onChange) { + const start = field.selectionStart ?? 0; + const end = field.selectionEnd ?? start; + const selected = field.value.slice(start, end) || "Text"; + const next = `${field.value.slice(0, start)}${before}${selected}${after}${field.value.slice(end)}`; + onChange(next); + requestAnimationFrame(() => { + field.focus(); + field.setSelectionRange(start + before.length, start + before.length + selected.length); + }); +} + +function SourceEditor({ value, onChange, disabled }) { + const field = useRef(null); + const [preview, setPreview] = useState(false); + function apply(before, after) { + if (field.current) wrapSelection(field.current, before, after, onChange); + } + return ( +
    +
    + + + + + + + + +
    + {preview ? : ( +