Neues Release mit Multiroom und Mandantenfähigkeiten #9

Merged
Lars merged 29 commits from develop into main 2026-10-23 13:12:27 +02:00
169 changed files with 28251 additions and 2079 deletions

No files matched your search

+9 -8
View File
@@ -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).
+26
View File
@@ -0,0 +1,26 @@
"""The one place where subscription limits will be checked.
Today there are no limits. The checks are called where a limit will matter, so that a plan
can be added without touching the callers.
Target model (see the entitlements blueprint): the quota subject is the owner of a room, a main
user, like the club at Shinkan. A plan, set by the operator, may later cap the number of active
employees per main user and per room. The count comes from the database, never from the client.
"""
from __future__ import annotations
from uuid import UUID
def ensure_can_create_room(conn, owner_id: UUID) -> None:
"""Called before a main user creates a room."""
del conn, owner_id
def ensure_can_add_member(conn, owner_id: UUID, room_id: UUID) -> None:
"""Called before a person becomes an active member of a room or is invited to it.
``owner_id`` is the owner of the room, the future quota subject.
"""
del conn, owner_id, room_id
+105 -7
View File
@@ -24,30 +24,52 @@ class Rights:
edit: bool = False
share: bool = False
delete: bool = False
# Saving or opening the original outside of Tsumugu. Reading in the app does not need it.
download: bool = False
@classmethod
def full(cls) -> Rights:
return cls(True, True, True, True)
return cls(True, True, True, True, True)
@classmethod
def from_row(cls, row: dict | None) -> Rights:
def from_row(cls, row: dict | None, download: bool = False) -> Rights:
if row is None:
return cls()
return cls(bool(row["can_read"]), bool(row["can_edit"]), bool(row["can_share"]), bool(row["can_delete"]))
return cls(bool(row["can_read"]), bool(row["can_edit"]), bool(row["can_share"]), bool(row["can_delete"]), download and bool(row["can_read"]))
def union(self, other: Rights) -> Rights:
return Rights(
self.read or other.read,
self.edit or other.edit,
self.share or other.share,
self.delete or other.delete,
self.download or other.download,
)
def without(self, blocked: Rights) -> Rights:
# An exception that takes away reading takes away downloading too.
return Rights(
self.read and not blocked.read,
self.edit and not blocked.edit,
self.share and not blocked.share,
self.delete and not blocked.delete,
self.download and not blocked.read,
)
def allows(self, need: str) -> bool:
return bool(getattr(self, need))
def as_dict(self) -> dict[str, bool]:
return {"read": self.read, "edit": self.edit, "share": self.share, "delete": self.delete}
return {"read": self.read, "edit": self.edit, "share": self.share, "delete": self.delete, "download": self.read and self.download}
# The room share: what a room role may do with a case or matter that is shared with the room.
# Sharing, deleting and ownership never come from a room role. An unknown role gets nothing.
ROOM_RIGHTS = {
"reader": Rights(read=True),
"member": Rights(read=True, edit=True),
"manager": Rights(read=True, edit=True),
}
@dataclass(frozen=True)
@@ -189,7 +211,25 @@ def _direct_grant(conn, actor: UUID, kind: str, resource_id: UUID) -> Rights:
""",
(actor, kind, resource_id),
).fetchone()
return Rights.from_row(row)
if row is None:
return Rights()
return Rights.from_row(row, _direct_download(conn, kind, resource_id))
def _direct_download(conn, kind: str, resource_id: UUID) -> bool:
"""Direct recipients follow the download setting `direct` of the owner of the entry."""
table = {"case": "cases", "matter": "matters", "element": "elements"}.get(kind)
if table is None:
return False
row = conn.execute(
f"""
SELECT a.download_defaults
FROM {table} r JOIN auth_accounts a ON a.id = r.owner_subject_id
WHERE r.id = %s
""",
(resource_id,),
).fetchone()
return bool(row and row["download_defaults"].get("direct", False))
def _exceptions(conn, actor: UUID, kind: str, resource_id: UUID, context: Ctx | None) -> Rights:
@@ -223,6 +263,37 @@ def _exceptions(conn, actor: UUID, kind: str, resource_id: UUID, context: Ctx |
return blocked
def room_default(conn, actor: UUID, kind: str, resource_id: UUID) -> Rights:
"""Rights of the current members of the rooms a case or matter is shared with.
A room is a team. The rights of one share are the role of the person in that room,
capped by the share (`read` or `edit`). Several shares add up. Only an active room,
an active membership and an active account count. Anything unclear gives no rights.
"""
rows = conn.execute(
"""
SELECT m.role, s.access, r.download_roles
FROM room_shares s
JOIN room_memberships m ON m.room_id = s.room_id AND m.subject_id = %s AND m.status = 'active'
JOIN data_rooms r ON r.id = s.room_id AND r.kind = 'organization' AND r.status = 'active'
JOIN auth_accounts a ON a.id = m.subject_id AND a.status = 'active'
WHERE s.resource_kind = %s AND s.resource_id = %s
""",
(actor, kind, resource_id),
).fetchall()
result = Rights()
for row in rows:
rights = ROOM_RIGHTS.get(row["role"], Rights())
if row["access"] == "read":
rights = Rights(read=rights.read)
elif row["access"] != "edit":
rights = Rights()
if rights.read and row["download_roles"].get(row["role"], False):
rights = Rights(rights.read, rights.edit, rights.share, rights.delete, True)
result = result.union(rights)
return result
def case_rights(conn, actor: UUID, case: dict) -> Rights:
if case["parent_case_id"] is not None and case["rights_mode"] == "inherit_parent":
parent = get_case(conn, case["parent_case_id"])
@@ -230,7 +301,7 @@ def case_rights(conn, actor: UUID, case: dict) -> Rights:
elif case["owner_subject_id"] == actor:
base = Rights.full()
else:
base = _direct_grant(conn, actor, "case", case["id"])
base = _direct_grant(conn, actor, "case", case["id"]).union(room_default(conn, actor, "case", case["id"]))
return base.without(_exceptions(conn, actor, "case", case["id"], None))
@@ -244,7 +315,10 @@ def _linked(conn, matter_id: UUID, case_id: UUID) -> bool:
def matter_rights(conn, actor: UUID, matter: dict, context: Ctx | None) -> Rights:
if context is None:
base = Rights.full() if matter["owner_subject_id"] == actor else _direct_grant(conn, actor, "matter", matter["id"])
if matter["owner_subject_id"] == actor:
base = Rights.full()
else:
base = _direct_grant(conn, actor, "matter", matter["id"]).union(room_default(conn, actor, "matter", matter["id"]))
return base.without(_exceptions(conn, actor, "matter", matter["id"], None))
if context.kind == "case":
@@ -571,6 +645,12 @@ def list_cases(conn, actor: UUID) -> list[dict]:
AND g.grantee_subject_id = %(actor)s AND NOT g.is_exception AND g.can_read
AND g.context_id IS NULL
)
OR (EXISTS (
SELECT 1 FROM room_shares sh
JOIN room_memberships sm ON sm.room_id = sh.room_id AND sm.subject_id = %(actor)s AND sm.status = 'active'
JOIN data_rooms sr ON sr.id = sh.room_id AND sr.kind = 'organization' AND sr.status = 'active'
WHERE sh.resource_kind = 'case' AND sh.resource_id = c.id
))
OR (
c.rights_mode = 'inherit_parent' AND c.parent_case_id IS NOT NULL AND EXISTS (
SELECT 1 FROM cases p
@@ -583,6 +663,12 @@ def list_cases(conn, actor: UUID) -> list[dict]:
AND g.grantee_subject_id = %(actor)s AND NOT g.is_exception
AND g.can_read AND g.context_id IS NULL
)
OR (EXISTS (
SELECT 1 FROM room_shares sh
JOIN room_memberships sm ON sm.room_id = sh.room_id AND sm.subject_id = %(actor)s AND sm.status = 'active'
JOIN data_rooms sr ON sr.id = sh.room_id AND sr.kind = 'organization' AND sr.status = 'active'
WHERE sh.resource_kind = 'case' AND sh.resource_id = p.id
))
)
)
)
@@ -613,6 +699,12 @@ def list_matters(conn, actor: UUID) -> list[tuple[dict, list[dict]]]:
AND g.grantee_subject_id = %(actor)s AND NOT g.is_exception AND g.can_read
AND g.context_id IS NULL
)
OR (EXISTS (
SELECT 1 FROM room_shares sh
JOIN room_memberships sm ON sm.room_id = sh.room_id AND sm.subject_id = %(actor)s AND sm.status = 'active'
JOIN data_rooms sr ON sr.id = sh.room_id AND sr.kind = 'organization' AND sr.status = 'active'
WHERE sh.resource_kind = 'matter' AND sh.resource_id = m.id
))
OR EXISTS (
SELECT 1 FROM matter_case_links l
JOIN cases c ON c.id = l.case_id AND c.deleted_at IS NULL
@@ -625,6 +717,12 @@ def list_matters(conn, actor: UUID) -> list[tuple[dict, list[dict]]]:
AND g.grantee_subject_id = %(actor)s AND NOT g.is_exception
AND g.can_read AND g.context_id IS NULL
)
OR (EXISTS (
SELECT 1 FROM room_shares sh
JOIN room_memberships sm ON sm.room_id = sh.room_id AND sm.subject_id = %(actor)s AND sm.status = 'active'
JOIN data_rooms sr ON sr.id = sh.room_id AND sr.kind = 'organization' AND sr.status = 'active'
WHERE sh.resource_kind = 'case' AND sh.resource_id = c.id
))
)
)
)
+106
View File
@@ -0,0 +1,106 @@
"""Fixed role bundles. Rights are read from the current database state, never from the session.
Platform: operator or user. Data room: member, manager or reader. There is no role editor.
An operator has no read right on content. Unknown role or status is refused.
"""
from __future__ import annotations
from uuid import UUID
from app.core.errors import forbidden
ROOM_ROLES = ("member", "manager", "reader")
ROOM_ROLE_LABELS = {
"member": "Mitglied",
"manager": "Verwalter",
"reader": "Leser",
}
def account_kind(conn, account_id: UUID) -> str | None:
row = conn.execute("SELECT account_kind FROM auth_accounts WHERE id = %s AND status = 'active'", (account_id,)).fetchone()
return row["account_kind"] if row else None
def require_main_user(conn, account_id: UUID) -> None:
"""Employees work in the rooms they were invited to. They create no rooms of their own."""
if account_kind(conn, account_id) != "main":
raise forbidden("Als Mitarbeiter arbeitest du in den Räumen, in die du eingeladen wurdest.")
def is_operator(conn, account_id: UUID) -> bool:
row = conn.execute(
"SELECT is_superadmin FROM auth_accounts WHERE id = %s AND status = 'active'",
(account_id,),
).fetchone()
return bool(row and row["is_superadmin"])
def require_operator(conn, account_id: UUID) -> None:
if not is_operator(conn, account_id):
raise forbidden("Das darf nur der Betreiber.")
def room_role(conn, account_id: UUID, room_id: UUID) -> str | None:
"""The active role of an account in an organization room, or None."""
row = conn.execute(
"""
SELECT m.role
FROM room_memberships m
JOIN data_rooms r ON r.id = m.room_id
WHERE m.room_id = %s AND m.subject_id = %s AND m.status = 'active' AND r.kind = 'organization'
""",
(room_id, account_id),
).fetchone()
if row is None or row["role"] not in ROOM_ROLES:
return None
return row["role"]
def require_room_manager(conn, account_id: UUID, room_id: UUID) -> None:
if room_role(conn, account_id, room_id) != "manager":
raise forbidden("Das darf nur ein Verwalter dieses Datenraums.")
def require_room_write(conn, account_id: UUID, room: dict) -> None:
"""Creating content needs the own personal room or a member or manager role."""
if room["kind"] == "personal":
if room["id"] != account_id:
raise forbidden("Der persönliche Datenraum gehört zu einem anderen Konto.")
require_main_user(conn, account_id)
return
role = room_role(conn, account_id, room["id"])
if role in {"member", "manager"}:
return
if role == "reader":
raise forbidden("Als Leser kannst du in diesem Datenraum nichts anlegen.")
raise forbidden("Du bist in diesem Datenraum nicht Mitglied.")
def count_active_operators(conn, *, lock: bool = False) -> int:
suffix = " FOR UPDATE" if lock else ""
rows = conn.execute(f"SELECT id FROM auth_accounts WHERE is_superadmin AND status = 'active'{suffix}").fetchall()
return len(rows)
def count_active_managers(conn, room_id: UUID, *, lock: bool = False) -> int:
suffix = " FOR UPDATE" if lock else ""
rows = conn.execute(
f"""
SELECT m.subject_id FROM room_memberships m
JOIN auth_accounts a ON a.id = m.subject_id
WHERE m.room_id = %s AND m.role = 'manager' AND m.status = 'active' AND a.status = 'active'{suffix}
""",
(room_id,),
).fetchall()
return len(rows)
def ensure_can_create(conn, account_id: UUID, scope_id: UUID) -> None:
"""Gate for every operation that creates content with this home room."""
room = conn.execute("SELECT id, kind FROM data_rooms WHERE id = %s", (scope_id,)).fetchone()
if room is None:
raise forbidden("Der gewählte Datenraum ist nicht verfügbar.")
require_room_write(conn, account_id, room)
+273
View File
@@ -0,0 +1,273 @@
"""Account administration for the operator and the own account (password, sessions)."""
from __future__ import annotations
from uuid import UUID
from fastapi import APIRouter, Depends, Response
from fastapi.responses import JSONResponse
from psycopg import Connection
from app.access.policy import audit
from app.access.roles import require_operator
from app.api.deps import Principal, get_conn, get_principal, get_session
from app.api.schemas import AccountIn, AccountPatchIn, PasswordChangeIn
from app.auth.accounts import (
promote_to_main,
change_own_password,
create_account,
generate_password,
reset_password,
revoke_sessions,
set_display_name,
set_operator,
set_status,
)
from app.core.errors import not_found, unprocessable
from app.core.timeutil import dump_dt
router = APIRouter()
_NO_STORE = {"Cache-Control": "no-store"}
def _account_item(row) -> dict:
return {
"id": str(row["id"]),
"email": row["email"],
"display_name": row["display_name"],
"is_superadmin": row["is_superadmin"],
"status": row["status"],
"must_change_password": row["must_change_password"],
"created_at": dump_dt(row["created_at"]),
"last_login_at": dump_dt(row["last_login_at"]),
"account_kind": row["account_kind"],
"sponsor_id": str(row["sponsor_id"]) if row["sponsor_id"] else None,
"sponsor_name": row.get("sponsor_name"),
}
@router.get("/api/v1/accounts")
def accounts(
status: str | None = None,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_operator(conn, principal.account_id)
if status not in {None, "active", "disabled"}:
raise unprocessable("Der Statusfilter ist ungültig.")
rows = conn.execute(
"""
SELECT id, email, display_name, is_superadmin, status, must_change_password, created_at, last_login_at,
account_kind, sponsor_id,
(SELECT s.display_name FROM auth_accounts s WHERE s.id = auth_accounts.sponsor_id) AS sponsor_name
FROM auth_accounts
WHERE origin = 'operator' AND (%s::text IS NULL OR status = %s::text)
ORDER BY status, display_name, email
""",
(status, status),
).fetchall()
return {"items": [_account_item(row) for row in rows], "next_cursor": None}
@router.get("/api/v1/accounts/{account_id}")
def account_detail(account_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
require_operator(conn, principal.account_id)
row = conn.execute(
"""
SELECT id, email, display_name, is_superadmin, status, must_change_password, created_at, last_login_at,
account_kind, sponsor_id,
(SELECT s.display_name FROM auth_accounts s WHERE s.id = auth_accounts.sponsor_id) AS sponsor_name
FROM auth_accounts WHERE id = %s AND origin = 'operator'
""",
(account_id,),
).fetchone()
if row is None:
raise not_found()
rooms = conn.execute(
"""
SELECT r.id, r.name, r.status, m.role
FROM room_memberships m
JOIN data_rooms r ON r.id = m.room_id
WHERE m.subject_id = %s AND m.status = 'active' AND r.kind = 'organization'
ORDER BY r.name, r.id
""",
(account_id,),
).fetchall()
sessions = conn.execute(
"""
SELECT count(*) AS n FROM auth_sessions
WHERE account_id = %s AND revoked_at IS NULL AND expires_at > now()
""",
(account_id,),
).fetchone()
body = _account_item(row)
body["rooms"] = [
{"id": str(room["id"]), "name": room["name"], "status": room["status"], "role": room["role"]} for room in rooms
]
body["active_sessions"] = sessions["n"]
employees = conn.execute(
"""
SELECT id, display_name, email, status FROM auth_accounts
WHERE sponsor_id = %s ORDER BY display_name, id
""",
(account_id,),
).fetchall()
body["employees"] = [
{"id": str(e["id"]), "display_name": e["display_name"], "email": e["email"], "status": e["status"]} for e in employees
]
return JSONResponse(body, headers=_NO_STORE)
@router.post("/api/v1/accounts")
def post_account(body: AccountIn, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
require_operator(conn, principal.account_id)
password = body.password or generate_password()
account = create_account(
conn,
body.email,
body.display_name,
password,
is_superadmin=body.is_operator,
must_change_password=True,
)
audit(conn, principal.account_id, None, "account_created", "account", account["id"])
if body.is_operator:
audit(conn, principal.account_id, None, "operator_granted", "account", account["id"])
payload = {
"id": str(account["id"]),
"email": account["email"],
"display_name": account["display_name"],
"is_superadmin": account["is_superadmin"],
"status": account["status"],
"must_change_password": True,
"account_kind": account["account_kind"],
}
if not body.password:
payload["temporary_password"] = password
return JSONResponse(
status_code=201,
content=payload,
headers={"Location": f"/api/v1/accounts/{account['id']}", **_NO_STORE},
)
@router.patch("/api/v1/accounts/{account_id}")
def patch_account(
account_id: UUID,
body: AccountPatchIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_operator(conn, principal.account_id)
exists = conn.execute("SELECT 1 FROM auth_accounts WHERE id = %s AND origin = 'operator'", (account_id,)).fetchone()
if exists is None:
raise not_found()
if body.display_name is not None:
set_display_name(conn, principal.account_id, account_id, body.display_name)
if body.account_kind == "main":
promote_to_main(conn, principal.account_id, account_id)
if body.is_operator is not None:
set_operator(conn, principal.account_id, account_id, body.is_operator)
if body.status is not None:
set_status(conn, principal.account_id, account_id, body.status)
row = conn.execute(
"""
SELECT id, email, display_name, is_superadmin, status, must_change_password, created_at, last_login_at,
account_kind, sponsor_id,
(SELECT s.display_name FROM auth_accounts s WHERE s.id = auth_accounts.sponsor_id) AS sponsor_name
FROM auth_accounts WHERE id = %s
""",
(account_id,),
).fetchone()
return _account_item(row)
@router.post("/api/v1/accounts/{account_id}/password-reset")
def post_password_reset(
account_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_operator(conn, principal.account_id)
password = reset_password(conn, principal.account_id, account_id)
return JSONResponse({"temporary_password": password}, headers=_NO_STORE)
@router.post("/api/v1/accounts/{account_id}/sessions/revoke")
def post_revoke_sessions(
account_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_operator(conn, principal.account_id)
if conn.execute("SELECT 1 FROM auth_accounts WHERE id = %s", (account_id,)).fetchone() is None:
raise not_found()
count = revoke_sessions(conn, account_id)
audit(conn, principal.account_id, None, "sessions_revoked", "account", account_id, detail={"count": count})
return {"revoked": count}
@router.post("/api/v1/auth/password", status_code=204)
def post_own_password(
body: PasswordChangeIn,
session: dict = Depends(get_session),
conn: Connection = Depends(get_conn),
):
change_own_password(conn, session["account_id"], session["id"], body.current_password, body.new_password)
return Response(status_code=204)
@router.get("/api/v1/auth/sessions")
def own_sessions(session: dict = Depends(get_session), conn: Connection = Depends(get_conn)):
rows = conn.execute(
"""
SELECT id, label, created_at, last_seen_at, expires_at
FROM auth_sessions
WHERE account_id = %s AND revoked_at IS NULL AND expires_at > now()
ORDER BY created_at DESC, id
""",
(session["account_id"],),
).fetchall()
return JSONResponse(
{
"items": [
{
"id": str(row["id"]),
"label": row["label"] or "Browser",
"created_at": dump_dt(row["created_at"]),
"last_seen_at": dump_dt(row["last_seen_at"]),
"expires_at": dump_dt(row["expires_at"]),
"current": row["id"] == session["id"],
}
for row in rows
]
},
headers=_NO_STORE,
)
@router.delete("/api/v1/auth/sessions/{session_id}", status_code=204)
def end_own_session(session_id: UUID, session: dict = Depends(get_session), conn: Connection = Depends(get_conn)):
if session_id == session["id"]:
raise unprocessable("Diese Sitzung beendest du mit Abmelden.")
row = conn.execute(
"""
UPDATE auth_sessions SET revoked_at = now()
WHERE id = %s AND account_id = %s AND revoked_at IS NULL
RETURNING id
""",
(session_id, session["account_id"]),
).fetchone()
if row is None:
raise not_found()
audit(conn, session["account_id"], None, "session_ended", "session", session_id)
return Response(status_code=204)
@router.post("/api/v1/auth/sessions/revoke-others")
def end_other_sessions(session: dict = Depends(get_session), conn: Connection = Depends(get_conn)):
count = revoke_sessions(conn, session["account_id"], keep=session["id"])
audit(conn, session["account_id"], None, "sessions_revoked", "account", session["account_id"], detail={"count": count})
return {"revoked": count}
+31 -6
View File
@@ -2,8 +2,18 @@
from __future__ import annotations
import secrets
from dataclasses import dataclass
from datetime import timedelta
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
@@ -11,10 +21,19 @@ from psycopg import Connection
from app.access.policy import ensure_member_or_personal
from app.auth.security import hash_secret, read_session_token
from app.core.errors import forbidden, unauthorized
from app.core.errors import forbidden, password_change_required, scope_changed, unauthorized
from app.core.timeutil import utcnow
# While a one-time password is set, only these routes answer.
PASSWORD_CHANGE_PATHS = frozenset({
"/api/v1/auth/session",
"/api/v1/auth/password",
"/api/v1/auth/logout",
})
SEEN_INTERVAL = timedelta(minutes=5)
@dataclass(frozen=True)
class Principal:
account_id: UUID
@@ -35,11 +54,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
@@ -50,7 +69,8 @@ def _session_row(conn: Connection, request: Request) -> dict:
row = conn.execute(
"""
SELECT s.id, s.account_id, s.csrf_token, s.scope_kind, s.scope_id, s.epoch,
s.expires_at, s.revoked_at, a.email, a.display_name, a.status AS account_status
s.expires_at, s.revoked_at, s.last_seen_at, a.email, a.display_name,
a.status AS account_status, a.must_change_password
FROM auth_sessions s
JOIN auth_accounts a ON a.id = s.account_id
WHERE s.secret_hash = %s
@@ -61,10 +81,15 @@ def _session_row(conn: Connection, request: Request) -> dict:
raise unauthorized()
if row["account_status"] != "active":
raise unauthorized()
if row["must_change_password"] and request.url.path not in PASSWORD_CHANGE_PATHS:
raise password_change_required()
if request.method not in {"GET", "HEAD", "OPTIONS"}:
sent = request.headers.get("x-csrf-token") or ""
if not sent or sent != row["csrf_token"]:
if not sent or not secrets.compare_digest(sent, row["csrf_token"]):
raise forbidden("Die Anfrage konnte der Sitzung nicht zugeordnet werden.")
seen = row["last_seen_at"]
if seen is None or utcnow() - seen > SEEN_INTERVAL:
conn.execute("UPDATE auth_sessions SET last_seen_at = now() WHERE id = %s", (row["id"],))
return row
@@ -83,7 +108,7 @@ def get_principal(request: Request, conn: Connection = Depends(get_conn)) -> Pri
except ValueError as exc:
raise forbidden("Der Datenraum ist nicht gewählt.") from exc
if kind != row["scope_kind"] or scope_id != row["scope_id"]:
raise forbidden("Der gewählte Datenraum entspricht nicht mehr der Sitzung.")
raise scope_changed()
room = ensure_member_or_personal(conn, row["account_id"], kind, scope_id)
return Principal(
account_id=row["account_id"],
+82
View File
@@ -0,0 +1,82 @@
"""Download policy: which room role may save the original of a document or mail.
Reading inside the app stays possible. The policy is a rule of use, not a copy protection:
what the screen shows has to reach the browser.
"""
from __future__ import annotations
from uuid import UUID
from fastapi import APIRouter, Depends
from fastapi.responses import JSONResponse
from psycopg import Connection
from psycopg.types.json import Json
from app.access.policy import audit
from app.access.roles import require_main_user, room_role
from app.api.deps import Principal, get_conn, get_principal
from app.api.schemas import DownloadPolicyIn
from app.core.errors import forbidden, not_found
router = APIRouter()
_NO_STORE = {"Cache-Control": "no-store"}
ROOM_KEYS = ("manager", "member", "reader")
def _policy(raw: dict, keys: tuple[str, ...]) -> dict[str, bool]:
return {key: bool(raw.get(key, True)) for key in keys}
def _room_of_member(conn, account_id: UUID, room_id: UUID) -> dict:
# A stranger and an unknown room answer alike.
room = conn.execute("SELECT * FROM data_rooms WHERE id = %s AND kind = 'organization'", (room_id,)).fetchone()
if room is None or room_role(conn, account_id, room_id) is None:
raise not_found()
return room
@router.get("/api/v1/rooms/{room_id}/download-policy")
def get_room_policy(room_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
room = _room_of_member(conn, principal.account_id, room_id)
return JSONResponse(
{"roles": _policy(room["download_roles"], ROOM_KEYS), "can_change": room["owner_id"] == principal.account_id},
headers=_NO_STORE,
)
@router.put("/api/v1/rooms/{room_id}/download-policy")
def put_room_policy(
room_id: UUID,
body: DownloadPolicyIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
room = _room_of_member(conn, principal.account_id, room_id)
if room["owner_id"] != principal.account_id:
raise forbidden("Das darf nur der Eigentümer des Datenraums.")
roles = {"manager": body.manager, "member": body.member, "reader": body.reader}
conn.execute("UPDATE data_rooms SET download_roles = %s WHERE id = %s", (Json(roles), room_id))
audit(conn, principal.account_id, room_id, "room_download_policy_changed", "room", room_id, detail=roles)
return JSONResponse({"roles": roles, "can_change": True}, headers=_NO_STORE)
@router.get("/api/v1/auth/download-defaults")
def get_defaults(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
require_main_user(conn, principal.account_id)
row = conn.execute("SELECT download_defaults FROM auth_accounts WHERE id = %s", (principal.account_id,)).fetchone()
return JSONResponse({"roles": _policy(row["download_defaults"], (*ROOM_KEYS, "direct"))}, headers=_NO_STORE)
@router.put("/api/v1/auth/download-defaults")
def put_defaults(
body: DownloadPolicyIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_main_user(conn, principal.account_id)
roles = {"manager": body.manager, "member": body.member, "reader": body.reader, "direct": True if body.direct is None else body.direct}
conn.execute("UPDATE auth_accounts SET download_defaults = %s WHERE id = %s", (Json(roles), principal.account_id))
audit(conn, principal.account_id, None, "download_defaults_changed", "account", principal.account_id, detail=roles)
return JSONResponse({"roles": roles}, headers=_NO_STORE)
+8 -2
View File
@@ -8,10 +8,10 @@ from uuid import UUID
from fastapi import APIRouter, Depends, Request, Response
from psycopg import Connection
from app.access.policy import Ctx, parse_query_context
from app.access.policy import Ctx, get_matter, matter_rights, parse_query_context
from app.api.deps import Principal, get_conn, get_principal
from app.api.schemas import ExportIn
from app.core.errors import unprocessable
from app.core.errors import DOWNLOAD_REFUSED, forbidden, unprocessable
from app.exporting import build_export, export_tree, review_export
router = APIRouter()
@@ -79,6 +79,12 @@ def post_export(
conn: Connection = Depends(get_conn),
):
selected, assignments = _selection(body)
matter = get_matter(conn, matter_id)
if matter is not None:
rights = matter_rights(conn, principal.account_id, matter, _context(body.context))
# Without any right the export itself answers as before. With read but no download right: refuse.
if rights.read and not rights.download:
raise forbidden(DOWNLOAD_REFUSED)
filename, payload = build_export(
conn,
principal.account_id,
+119
View File
@@ -0,0 +1,119 @@
"""Library endpoints: rooms as tiles, what lies in a room, and sharing several entries at once."""
from __future__ import annotations
from uuid import UUID
from fastapi import APIRouter, Depends
from fastapi.responses import JSONResponse
from psycopg import Connection
from app.access.policy import parse_query_context, require_case, require_matter
from app.access.roles import room_role
from app.api.deps import Principal, get_conn, get_principal
from app.api.schemas import BatchShareIn
from app.core.errors import forbidden
from app.library import case_items, case_outline, matter_items, matter_outline, room_contents, room_effect
from app.ops import share_with_room
router = APIRouter()
_NO_STORE = {"Cache-Control": "no-store"}
@router.get("/api/v1/rooms/overview")
def rooms_overview(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
"""The team rooms of the person as tiles. Names of members are only shown to managers."""
actor = principal.account_id
rooms = conn.execute(
"""
SELECT r.id, r.name, r.owner_id, r.default_visibility, m.role,
(SELECT count(*) FROM room_memberships x WHERE x.room_id = r.id AND x.status = 'active') AS members
FROM room_memberships m JOIN data_rooms r ON r.id = m.room_id
WHERE m.subject_id = %s AND m.status = 'active' AND r.kind = 'organization' AND r.status = 'active'
ORDER BY r.name, r.id
""",
(actor,),
).fetchall()
items = []
for room in rooms:
cases, matters = room_contents(conn, actor, room["id"])
people = []
if room["role"] == "manager":
people = [
row["display_name"]
for row in conn.execute(
"""
SELECT a.display_name FROM room_memberships x JOIN auth_accounts a ON a.id = x.subject_id
WHERE x.room_id = %s AND x.status = 'active'
ORDER BY a.display_name, a.id LIMIT 6
""",
(room["id"],),
).fetchall()
]
items.append(
{
"id": str(room["id"]),
"name": room["name"],
"role": room["role"],
"is_owner": room["owner_id"] == actor,
"private": room["members"] <= 1,
"default_visibility": room["default_visibility"],
"member_count": room["members"],
"members": people,
"case_count": sum(1 for case, _ in cases if not case["parent_case_id"]),
"matter_count": sum(1 for matter, _ in matters if not matter["parent_matter_id"]),
}
)
return JSONResponse({"items": items}, headers=_NO_STORE)
@router.get("/api/v1/rooms/{room_id}/contents")
def contents(room_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
"""Cases and matters shared with the room that the person may read."""
if room_role(conn, principal.account_id, room_id) is None:
raise forbidden()
cases, matters = room_contents(conn, principal.account_id, room_id)
return JSONResponse(
{
"cases": case_items(conn, principal.account_id, cases),
"matters": matter_items(conn, principal.account_id, matters),
},
headers=_NO_STORE,
)
@router.post("/api/v1/rooms/{room_id}/shares")
def share_many(
room_id: UUID,
body: BatchShareIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
"""Share several own entries with the room. All or none: one failure rolls the request back."""
for item in body.items:
share_with_room(conn, principal.account_id, item.kind, item.id, room_id, body.access)
return {
"shared": len(body.items),
"access": body.access,
"effect": room_effect(conn, room_id, principal.account_id, body.access),
}
@router.get("/api/v1/cases/{case_id}/outline")
def case_outline_view(case_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
case, _rights = require_case(conn, principal.account_id, case_id, "read")
return JSONResponse(case_outline(conn, principal.account_id, case), headers=_NO_STORE)
@router.get("/api/v1/matters/{matter_id}/outline")
def matter_outline_view(
matter_id: UUID,
context_kind: str | None = None,
context_id: str | None = None,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
context = parse_query_context(context_kind, context_id)
matter, _rights = require_matter(conn, principal.account_id, matter_id, context, "read")
return JSONResponse(matter_outline(conn, principal.account_id, matter, context), headers=_NO_STORE)
+711
View File
@@ -0,0 +1,711 @@
"""Data rooms: members, roles, invitations, and the operator's room overview and audit."""
from __future__ import annotations
from datetime import timedelta
from uuid import UUID, uuid4
from fastapi import APIRouter, Depends, Response
from fastapi.responses import JSONResponse
from psycopg import Connection
from app.access.policy import account_by_email, audit
from app.access.limits import ensure_can_add_member, ensure_can_create_room
from app.access.roles import (
ROOM_ROLES,
account_kind,
count_active_managers,
require_main_user,
require_operator,
require_room_manager,
room_role,
)
from app.api.deps import Principal, get_conn, get_principal
from app.api.schemas import (
InvitationIn,
MemberIn,
MemberRoleIn,
OperatorManagerIn,
OperatorOwnerIn,
OwnerIn,
RoomIn,
RoomPatchIn,
VisibilityIn,
)
from app.auth.accounts import normalize_email
from app.auth.security import hash_secret, new_secret
from app.core.errors import forbidden, not_found, unprocessable
from app.core.timeutil import dump_dt, utcnow
from app.present import LABELS
router = APIRouter()
_NO_STORE = {"Cache-Control": "no-store"}
INVITATION_DAYS = 7
def _created(path: str, payload: dict) -> JSONResponse:
return JSONResponse(status_code=201, content=payload, headers={"Location": path, **_NO_STORE})
def _require_owner(conn, account_id: UUID, room_id: UUID) -> dict:
# An unknown room and a room owned by someone else answer alike: no way to probe ids.
room = conn.execute(
"SELECT * FROM data_rooms WHERE id = %s AND kind = 'organization'", (room_id,)
).fetchone()
if room is None or room["owner_id"] != account_id:
raise forbidden("Das darf nur der Eigentümer des Datenraums.")
return room
def _protect_owner(room: dict, subject_id: UUID) -> None:
if room["owner_id"] == subject_id:
raise unprocessable("Der Eigentümer bleibt Verwalter. Übertrage den Datenraum zuerst.")
def _room(conn, room_id: UUID) -> dict:
row = conn.execute("SELECT * FROM data_rooms WHERE id = %s AND kind = 'organization'", (room_id,)).fetchone()
if row is None:
raise not_found()
return row
def _audit_membership(conn, actor: UUID, room_id: UUID, subject_id: UUID, action: str, role: str | None = None) -> None:
audit(
conn,
actor,
room_id,
action,
"membership",
subject_id,
detail={"room_id": str(room_id), **({"role": role} if role else {})},
)
def _drop_edit_rights_in_room(conn, subject_id: UUID, room_id: UUID) -> None:
"""A reader neither edits nor shares objects of this room. Read grants stay."""
conn.execute(
"""
UPDATE access_grants g
SET can_edit = false, can_share = false
WHERE g.grantee_subject_id = %s AND NOT g.is_exception AND (g.can_edit OR g.can_share)
AND (
(g.resource_kind = 'case' AND g.resource_id IN (SELECT id FROM cases WHERE home_scope_id = %s))
OR (g.resource_kind = 'matter' AND g.resource_id IN (SELECT id FROM matters WHERE home_scope_id = %s))
OR (g.resource_kind = 'element' AND g.resource_id IN (SELECT id FROM elements WHERE home_scope_id = %s))
OR (g.resource_kind = 'task' AND g.resource_id IN (SELECT id FROM tasks WHERE home_scope_id = %s))
OR (g.resource_kind = 'deadline' AND g.resource_id IN (SELECT id FROM deadlines WHERE home_scope_id = %s))
)
""",
(subject_id, room_id, room_id, room_id, room_id, room_id),
)
def _drop_shares_of(conn, room_id: UUID, subject_id: UUID) -> None:
"""Whoever leaves a team, or may no longer write in it, takes the shares of their own entries with them."""
conn.execute(
"""
DELETE FROM room_shares s
WHERE s.room_id = %s
AND (
(s.resource_kind = 'case' AND s.resource_id IN (SELECT id FROM cases WHERE owner_subject_id = %s))
OR (s.resource_kind = 'matter' AND s.resource_id IN (SELECT id FROM matters WHERE owner_subject_id = %s))
)
""",
(room_id, subject_id, subject_id),
)
def _set_role(conn, actor: UUID, room_id: UUID, subject_id: UUID, role: str, *, added: bool) -> None:
if role not in ROOM_ROLES:
raise unprocessable("Diese Raumrolle gibt es nicht.")
conn.execute(
"""
INSERT INTO room_memberships (room_id, subject_id, role, status)
VALUES (%s, %s, %s, 'active')
ON CONFLICT (room_id, subject_id) DO UPDATE SET role = EXCLUDED.role, status = 'active'
""",
(room_id, subject_id, role),
)
if role == "reader":
_drop_edit_rights_in_room(conn, subject_id, room_id)
_drop_shares_of(conn, room_id, subject_id)
_audit_membership(conn, actor, room_id, subject_id, "membership_added" if added else "membership_role_changed", role)
def _membership(conn, room_id: UUID, subject_id: UUID, *, lock: bool = False) -> dict | None:
suffix = " FOR UPDATE" if lock else ""
return conn.execute(
f"SELECT role, status FROM room_memberships WHERE room_id = %s AND subject_id = %s{suffix}",
(room_id, subject_id),
).fetchone()
@router.get("/api/v1/rooms")
def rooms(
include_archived: bool = False,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
from app.auth.accounts import list_rooms
items = list_rooms(conn, principal.account_id)
if include_archived:
archived = conn.execute(
"""
SELECT r.id, r.name, m.role, r.owner_id
FROM room_memberships m JOIN data_rooms r ON r.id = m.room_id
WHERE m.subject_id = %s AND m.status = 'active' AND r.kind = 'organization' AND r.status = 'archived'
ORDER BY r.name, r.id
""",
(principal.account_id,),
).fetchall()
items += [
{
"id": str(row["id"]),
"kind": "organization",
"name": row["name"],
"role": row["role"],
"status": "archived",
"is_owner": row["owner_id"] == principal.account_id,
}
for row in archived
]
return {"items": items, "next_cursor": None}
@router.post("/api/v1/rooms")
def create_room(body: RoomIn, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
require_main_user(conn, principal.account_id)
ensure_can_create_room(conn, principal.account_id)
room_id = uuid4()
name = body.name.strip()
conn.execute(
"""
INSERT INTO data_rooms (id, kind, name, created_by, owner_id, default_visibility, download_roles)
SELECT %s, 'organization', %s, %s, %s, %s,
jsonb_build_object(
'manager', COALESCE((download_defaults ->> 'manager')::boolean, true),
'member', COALESCE((download_defaults ->> 'member')::boolean, true),
'reader', COALESCE((download_defaults ->> 'reader')::boolean, true)
)
FROM auth_accounts WHERE id = %s
""",
(room_id, name, principal.account_id, principal.account_id, body.default_visibility, principal.account_id),
)
conn.execute(
"INSERT INTO room_memberships (room_id, subject_id, role) VALUES (%s, %s, 'manager')",
(room_id, principal.account_id),
)
audit(conn, principal.account_id, room_id, "room_created", "room", room_id)
return _created(
f"/api/v1/rooms/{room_id}",
{"id": str(room_id), "kind": "organization", "name": name, "default_visibility": body.default_visibility},
)
@router.patch("/api/v1/rooms/{room_id}")
def patch_room(
room_id: UUID,
body: RoomPatchIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_room_manager(conn, principal.account_id, room_id)
room = _room(conn, room_id)
if body.name is not None and body.name.strip() != room["name"]:
conn.execute("UPDATE data_rooms SET name = %s WHERE id = %s", (body.name.strip(), room_id))
audit(conn, principal.account_id, room_id, "room_renamed", "room", room_id)
if body.default_visibility is not None and body.default_visibility != room["default_visibility"]:
_require_owner(conn, principal.account_id, room_id)
conn.execute("UPDATE data_rooms SET default_visibility = %s WHERE id = %s", (body.default_visibility, room_id))
audit(
conn,
principal.account_id,
room_id,
"room_default_changed",
"room",
room_id,
detail={"visibility": body.default_visibility},
)
if body.status is not None and body.status != room["status"]:
_require_owner(conn, principal.account_id, room_id)
conn.execute("UPDATE data_rooms SET status = %s WHERE id = %s", (body.status, room_id))
if body.status == "archived":
# Sessions working in the room return to their personal room.
conn.execute(
"""
UPDATE auth_sessions
SET scope_kind = 'personal', scope_id = account_id, epoch = epoch + 1
WHERE scope_id = %s AND revoked_at IS NULL
""",
(room_id,),
)
audit(
conn,
principal.account_id,
room_id,
"room_archived" if body.status == "archived" else "room_restored",
"room",
room_id,
)
row = _room(conn, room_id)
return {
"id": str(row["id"]),
"name": row["name"],
"status": row["status"],
"default_visibility": row["default_visibility"],
}
def _set_owner(conn, actor: UUID, room_id: UUID, new_owner: UUID, previous: UUID | None) -> None:
conn.execute("UPDATE data_rooms SET owner_id = %s WHERE id = %s", (new_owner, room_id))
conn.execute(
"""
INSERT INTO room_memberships (room_id, subject_id, role, status)
VALUES (%s, %s, 'manager', 'active')
ON CONFLICT (room_id, subject_id) DO UPDATE SET role = 'manager', status = 'active'
""",
(room_id, new_owner),
)
audit(
conn,
actor,
room_id,
"room_owner_changed",
"room",
room_id,
detail={"from": str(previous) if previous else None, "to": str(new_owner)},
)
@router.post("/api/v1/rooms/{room_id}/owner")
def transfer_owner(
room_id: UUID,
body: OwnerIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
"""The owner hands the room to an active member. The new owner becomes manager."""
room = _require_owner(conn, principal.account_id, room_id)
target = _membership(conn, room_id, body.subject_id, lock=True)
account = conn.execute("SELECT status FROM auth_accounts WHERE id = %s", (body.subject_id,)).fetchone()
if target is None or target["status"] != "active" or account is None or account["status"] != "active":
raise unprocessable("Der Datenraum geht nur an ein aktives Mitglied.")
if account_kind(conn, body.subject_id) != "main":
raise unprocessable("Ein Mitarbeiter-Konto kann keinen Datenraum besitzen.")
if body.subject_id == room["owner_id"]:
raise unprocessable("Diese Person ist bereits Eigentümer.")
_set_owner(conn, principal.account_id, room_id, body.subject_id, room["owner_id"])
return {"owner_id": str(body.subject_id)}
@router.get("/api/v1/rooms/{room_id}/exposure")
def exposure(room_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
"""Own cases and matters: shared with this room (`room`) or filed here but not shared (`private`)."""
if room_role(conn, principal.account_id, room_id) is None:
raise forbidden()
result: dict = {}
for table, kind in (("cases", "case"), ("matters", "matter")):
row = conn.execute(
f"""
SELECT
count(*) FILTER (WHERE EXISTS (
SELECT 1 FROM room_shares s
WHERE s.resource_kind = %s AND s.resource_id = t.id AND s.room_id = %s)) AS shared,
count(*) FILTER (WHERE t.home_scope_id = %s AND NOT EXISTS (
SELECT 1 FROM room_shares s
WHERE s.resource_kind = %s AND s.resource_id = t.id AND s.room_id = %s)) AS filed
FROM {table} t
WHERE t.owner_subject_id = %s AND t.deleted_at IS NULL
""",
(kind, room_id, room_id, kind, room_id, principal.account_id),
).fetchone()
result[table] = {"room": row["shared"], "private": row["filed"]}
return JSONResponse(result, headers=_NO_STORE)
@router.post("/api/v1/rooms/{room_id}/my-content/visibility")
def set_my_content(
room_id: UUID,
body: VisibilityIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
"""`room`: share every own entry filed in this room with it. `private`: end all own shares to it."""
role = room_role(conn, principal.account_id, room_id)
if role is None:
raise forbidden()
changed = 0
if body.visibility == "room":
if role not in {"member", "manager"}:
raise forbidden("Als Leser kannst du nichts mit dem Datenraum teilen.")
for table, kind in (("cases", "case"), ("matters", "matter")):
rows = conn.execute(
f"""
INSERT INTO room_shares (resource_kind, resource_id, room_id, access, created_by)
SELECT %s, t.id, %s, 'edit', %s FROM {table} t
WHERE t.home_scope_id = %s AND t.owner_subject_id = %s AND t.deleted_at IS NULL
ON CONFLICT DO NOTHING
RETURNING id
""",
(kind, room_id, principal.account_id, room_id, principal.account_id),
).fetchall()
changed += len(rows)
else:
for table, kind in (("cases", "case"), ("matters", "matter")):
rows = conn.execute(
f"""
DELETE FROM room_shares s
WHERE s.room_id = %s AND s.resource_kind = %s
AND s.resource_id IN (SELECT id FROM {table} WHERE owner_subject_id = %s)
RETURNING s.id
""",
(room_id, kind, principal.account_id),
).fetchall()
changed += len(rows)
if changed:
audit(
conn,
principal.account_id,
room_id,
"visibility_changed",
"room",
room_id,
detail={"visibility": body.visibility, "count": changed},
)
return {"changed": changed}
@router.get("/api/v1/rooms/{room_id}/members")
def members(room_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
require_room_manager(conn, principal.account_id, room_id)
owner_id = _room(conn, room_id)["owner_id"]
rows = conn.execute(
"""
SELECT m.subject_id, m.role, a.email, a.display_name, a.status
FROM room_memberships m
JOIN auth_accounts a ON a.id = m.subject_id
WHERE m.room_id = %s AND m.status = 'active'
ORDER BY a.display_name, a.id
""",
(room_id,),
).fetchall()
return {
"items": [
{
"subject_id": str(row["subject_id"]),
"email": row["email"],
"display_name": row["display_name"],
"role": row["role"],
"account_status": row["status"],
"is_owner": row["subject_id"] == owner_id,
}
for row in rows
]
}
@router.post("/api/v1/rooms/{room_id}/members")
def add_member(
room_id: UUID,
body: MemberIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_room_manager(conn, principal.account_id, room_id)
account = account_by_email(conn, body.email)
if account is None or account["status"] != "active":
raise not_found()
existing = _membership(conn, room_id, account["id"], lock=True)
if body.role != "manager":
_protect_owner(_room(conn, room_id), account["id"])
if existing and existing["status"] == "active" and existing["role"] == "manager" and body.role != "manager":
if count_active_managers(conn, room_id, lock=True) <= 1:
raise unprocessable("Der letzte Verwalter bleibt Verwalter.")
was_active = bool(existing and existing["status"] == "active")
if not was_active:
ensure_can_add_member(conn, _room(conn, room_id)["owner_id"], room_id)
_set_role(conn, principal.account_id, room_id, account["id"], body.role, added=not was_active)
return {"subject_id": str(account["id"]), "role": body.role}
@router.patch("/api/v1/rooms/{room_id}/members/{subject_id}")
def change_member_role(
room_id: UUID,
subject_id: UUID,
body: MemberRoleIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_room_manager(conn, principal.account_id, room_id)
count_active_managers(conn, room_id, lock=True)
current = _membership(conn, room_id, subject_id, lock=True)
if current is None or current["status"] != "active":
raise not_found()
if current["role"] == body.role:
return {"subject_id": str(subject_id), "role": body.role}
_protect_owner(_room(conn, room_id), subject_id)
if current["role"] == "manager" and count_active_managers(conn, room_id) <= 1:
raise unprocessable("Der letzte Verwalter bleibt Verwalter.")
_set_role(conn, principal.account_id, room_id, subject_id, body.role, added=False)
return {"subject_id": str(subject_id), "role": body.role}
@router.delete("/api/v1/rooms/{room_id}/members/{subject_id}", status_code=204)
def remove_member(
room_id: UUID,
subject_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_room_manager(conn, principal.account_id, room_id)
count_active_managers(conn, room_id, lock=True)
current = _membership(conn, room_id, subject_id, lock=True)
if current is None or current["status"] != "active":
raise not_found()
_protect_owner(_room(conn, room_id), subject_id)
if current["role"] == "manager" and count_active_managers(conn, room_id) <= 1:
raise unprocessable("Der letzte Verwalter kann den Datenraum nicht verlassen.")
conn.execute(
"UPDATE room_memberships SET status = 'removed' WHERE room_id = %s AND subject_id = %s",
(room_id, subject_id),
)
_drop_shares_of(conn, room_id, subject_id)
# The removed person works in the personal room again; own entries stay visible there.
conn.execute(
"""
UPDATE auth_sessions
SET scope_kind = 'personal', scope_id = account_id, epoch = epoch + 1
WHERE account_id = %s AND scope_id = %s AND revoked_at IS NULL
""",
(subject_id, room_id),
)
_audit_membership(conn, principal.account_id, room_id, subject_id, "membership_removed")
return Response(status_code=204)
@router.post("/api/v1/invitations")
def invite(
body: InvitationIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
# Only the owner, a main user, brings new people in; they become employee accounts.
room = _require_owner(conn, principal.account_id, body.room_id)
require_main_user(conn, principal.account_id)
ensure_can_add_member(conn, room["owner_id"], room["id"])
email = normalize_email(body.email)
if account_by_email(conn, email):
raise unprocessable("Es gibt bereits ein Konto. Füge die Person als Mitglied hinzu.")
token = new_secret()
row = conn.execute(
"""
INSERT INTO auth_invitations (email, room_id, token_hash, invited_by, expires_at, role)
VALUES (%s, %s, %s, %s, %s, %s)
RETURNING id, expires_at
""",
(email, room["id"], hash_secret(token), principal.account_id, utcnow() + timedelta(days=INVITATION_DAYS), body.role),
).fetchone()
audit(conn, principal.account_id, room["id"], "invitation_created", "invitation", row["id"], detail={"role": body.role})
return _created(
f"/api/v1/invitations/{row['id']}",
{"id": str(row["id"]), "email": email, "role": body.role, "expires_at": dump_dt(row["expires_at"]), "token": token},
)
@router.get("/api/v1/rooms/{room_id}/invitations")
def invitations(room_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
require_room_manager(conn, principal.account_id, room_id)
rows = conn.execute(
"""
SELECT id, email, role, expires_at, created_at
FROM auth_invitations
WHERE room_id = %s AND accepted_at IS NULL AND revoked_at IS NULL AND expires_at > now()
ORDER BY created_at DESC, id
""",
(room_id,),
).fetchall()
return JSONResponse(
{
"items": [
{
"id": str(row["id"]),
"email": row["email"],
"role": row["role"],
"expires_at": dump_dt(row["expires_at"]),
"created_at": dump_dt(row["created_at"]),
}
for row in rows
]
},
headers=_NO_STORE,
)
@router.delete("/api/v1/rooms/{room_id}/invitations/{invitation_id}", status_code=204)
def revoke_invitation(
room_id: UUID,
invitation_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_room_manager(conn, principal.account_id, room_id)
row = conn.execute(
"""
UPDATE auth_invitations SET revoked_at = now()
WHERE id = %s AND room_id = %s AND accepted_at IS NULL AND revoked_at IS NULL
RETURNING id
""",
(invitation_id, room_id),
).fetchone()
if row is None:
raise not_found()
audit(conn, principal.account_id, room_id, "invitation_revoked", "invitation", invitation_id)
return Response(status_code=204)
@router.get("/api/v1/admin/rooms")
def admin_rooms(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
"""Metadata only: names, state and who manages. No content."""
require_operator(conn, principal.account_id)
rows = conn.execute(
"""
SELECT r.id, r.name, r.status, r.created_at,
(SELECT o.display_name FROM auth_accounts o WHERE o.id = r.owner_id) AS owner_name,
EXISTS (
SELECT 1 FROM auth_accounts o
JOIN room_memberships om ON om.subject_id = o.id AND om.room_id = r.id AND om.status = 'active'
WHERE o.id = r.owner_id AND o.status = 'active'
) AS owner_active,
(SELECT count(*) FROM room_memberships m WHERE m.room_id = r.id AND m.status = 'active') AS members,
COALESCE((
SELECT json_agg(a.display_name ORDER BY a.display_name)
FROM room_memberships m JOIN auth_accounts a ON a.id = m.subject_id
WHERE m.room_id = r.id AND m.status = 'active' AND m.role = 'manager' AND a.status = 'active'
), '[]'::json) AS managers
FROM data_rooms r
WHERE r.kind = 'organization'
ORDER BY r.name, r.id
"""
).fetchall()
return {
"items": [
{
"id": str(row["id"]),
"name": row["name"],
"status": row["status"],
"members": row["members"],
"owner": row["owner_name"],
"owner_active": row["owner_active"],
"managers": row["managers"],
"has_manager": bool(row["managers"]),
"created_at": dump_dt(row["created_at"]),
}
for row in rows
],
"next_cursor": None,
}
@router.post("/api/v1/admin/rooms/{room_id}/managers")
def admin_assign_manager(
room_id: UUID,
body: OperatorManagerIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
"""Only for a room without an active manager, so it does not stay orphaned."""
require_operator(conn, principal.account_id)
_room(conn, room_id)
if count_active_managers(conn, room_id, lock=True) > 0:
raise forbidden("Dieser Datenraum hat bereits einen Verwalter.")
account = account_by_email(conn, body.email)
if account is None or account["status"] != "active":
raise not_found()
existing = _membership(conn, room_id, account["id"], lock=True)
_set_role(
conn,
principal.account_id,
room_id,
account["id"],
"manager",
added=not (existing and existing["status"] == "active"),
)
return {"subject_id": str(account["id"]), "role": "manager"}
@router.post("/api/v1/admin/rooms/{room_id}/owner")
def admin_set_owner(
room_id: UUID,
body: OperatorOwnerIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
"""The operator steps in only when the owner can no longer act: disabled or not a member any more."""
require_operator(conn, principal.account_id)
room = _room(conn, room_id)
owner = conn.execute("SELECT status FROM auth_accounts WHERE id = %s", (room["owner_id"],)).fetchone()
active_owner = bool(owner and owner["status"] == "active" and room_role(conn, room["owner_id"], room_id))
if active_owner:
raise forbidden("Der Eigentümer ist aktiv. Er überträgt den Datenraum selbst.")
account = account_by_email(conn, body.email)
if account is None or account["status"] != "active":
raise not_found()
if account_kind(conn, account["id"]) != "main":
raise unprocessable("Ein Mitarbeiter-Konto kann keinen Datenraum besitzen.")
_set_owner(conn, principal.account_id, room_id, account["id"], room["owner_id"])
return {"owner_id": str(account["id"])}
_ADMIN_KINDS = ("account", "session", "room", "membership", "invitation")
@router.get("/api/v1/admin/events")
def admin_events(
cursor: int = 0,
limit: int = 50,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_operator(conn, principal.account_id)
limit = max(1, min(limit, 100))
cursor = max(0, cursor)
rows = conn.execute(
"""
SELECT e.id, e.action, e.resource_kind, e.resource_id, e.occurred_at, e.result, e.scope_id,
actor.display_name AS actor_name,
subject.display_name AS subject_name,
room.name AS room_name
FROM domain_events e
LEFT JOIN auth_accounts actor ON actor.id = e.actor_subject_id
LEFT JOIN auth_accounts subject ON subject.id = e.resource_id AND e.resource_kind IN ('account', 'membership')
LEFT JOIN data_rooms room ON room.id = COALESCE(e.scope_id, CASE WHEN e.resource_kind = 'room' THEN e.resource_id END)
AND room.kind = 'organization'
WHERE e.resource_kind = ANY(%s)
ORDER BY e.occurred_at DESC, e.id DESC
OFFSET %s LIMIT %s
""",
(list(_ADMIN_KINDS), cursor, limit + 1),
).fetchall()
page = rows[:limit]
return JSONResponse(
{
"items": [
{
"id": str(row["id"]),
"action": row["action"],
"label": LABELS.get(row["action"], "Ereignis"),
"resource_kind": row["resource_kind"],
"actor": row["actor_name"],
"subject": row["subject_name"],
"room": row["room_name"],
"occurred_at": dump_dt(row["occurred_at"]),
"result": row["result"],
}
for row in page
],
"next_cursor": cursor + limit if len(rows) > limit else None,
},
headers=_NO_STORE,
)
+139
View File
@@ -0,0 +1,139 @@
"""Room shares of a case or matter. A room is a team: the owner shares an entry with any of the
rooms he is a member of, independent of where the entry is filed."""
from __future__ import annotations
from uuid import UUID
from fastapi import APIRouter, Depends, Response
from fastapi.responses import JSONResponse
from psycopg import Connection
from app.access.policy import ROOM_RIGHTS, Rights
from app.api.deps import Principal, get_conn, get_principal
from app.api.schemas import ExclusionIn, RoomShareIn
from app.library import room_effect
from app.ops import _shareable, set_person_exclusion, share_with_room, unshare_from_room
router = APIRouter()
_NO_STORE = {"Cache-Control": "no-store"}
def _capped(role: str, access: str) -> Rights:
rights = ROOM_RIGHTS.get(role, Rights())
return Rights(read=rights.read) if access == "read" else rights
def _view(conn, actor: UUID, kind: str, resource_id: UUID) -> dict:
_shareable(conn, actor, kind, resource_id)
shares = conn.execute(
"""
SELECT s.room_id, s.access, r.name, r.status
FROM room_shares s JOIN data_rooms r ON r.id = s.room_id
WHERE s.resource_kind = %s AND s.resource_id = %s
ORDER BY r.name, r.id
""",
(kind, resource_id),
).fetchall()
result = []
for share in shares:
members = conn.execute(
"""
SELECT m.subject_id, m.role, a.display_name,
EXISTS (
SELECT 1 FROM access_grants g
WHERE g.is_exception AND g.grantee_subject_id = m.subject_id
AND g.resource_kind = %s AND g.resource_id = %s AND g.context_kind IS NULL
) AS excluded
FROM room_memberships m
JOIN auth_accounts a ON a.id = m.subject_id
WHERE m.room_id = %s AND m.status = 'active' AND m.subject_id <> %s
ORDER BY a.display_name, a.id
""",
(kind, resource_id, share["room_id"], actor),
).fetchall()
result.append(
{
"room_id": str(share["room_id"]),
"room_name": share["name"],
"archived": share["status"] != "active",
"access": share["access"],
"members": [
{
"subject_id": str(row["subject_id"]),
"display_name": row["display_name"],
"role": row["role"],
"excluded": row["excluded"],
"rights": {
"read": _capped(row["role"], share["access"]).read,
"edit": _capped(row["role"], share["access"]).edit,
},
}
for row in members
],
}
)
shared_ids = {item["room_id"] for item in result}
candidates = conn.execute(
"""
SELECT r.id, r.name, m.role
FROM room_memberships m JOIN data_rooms r ON r.id = m.room_id
WHERE m.subject_id = %s AND m.status = 'active' AND m.role IN ('member', 'manager')
AND r.kind = 'organization' AND r.status = 'active'
ORDER BY r.name, r.id
""",
(actor,),
).fetchall()
return {
"id": str(resource_id),
"shares": result,
"available": [
{"id": str(row["id"]), "name": row["name"]} for row in candidates if str(row["id"]) not in shared_ids
],
}
def _register(kind: str, plural: str) -> None:
base = f"/api/v1/{plural}/{{resource_id}}/room-share"
@router.get(base, name=f"get_{kind}_room_share")
def get_share(resource_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
return JSONResponse(_view(conn, principal.account_id, kind, resource_id), headers=_NO_STORE)
@router.put(base + "/rooms/{room_id}", name=f"put_{kind}_room_share")
def put_share(
resource_id: UUID,
room_id: UUID,
body: RoomShareIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
shared = share_with_room(conn, principal.account_id, kind, resource_id, room_id, body.access)
shared["effect"] = room_effect(conn, room_id, principal.account_id, body.access)
return shared
@router.delete(base + "/rooms/{room_id}", status_code=204, name=f"delete_{kind}_room_share")
def delete_share(
resource_id: UUID,
room_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
unshare_from_room(conn, principal.account_id, kind, resource_id, room_id)
return Response(status_code=204)
@router.put(base + "/people/{subject_id}", name=f"put_{kind}_room_share_person")
def put_person(
resource_id: UUID,
subject_id: UUID,
body: ExclusionIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
set_person_exclusion(conn, principal.account_id, kind, resource_id, subject_id, body.excluded)
return {"subject_id": str(subject_id), "excluded": body.excluded}
_register("case", "cases")
_register("matter", "matters")
+131 -266
View File
@@ -12,6 +12,7 @@ from psycopg import Connection
from app.access.policy import (
Ctx,
account_by_email,
audit,
case_rights,
deadline_rights,
element_rights,
@@ -31,10 +32,10 @@ from app.access.policy import (
require_matter,
task_rights,
)
from app.access.limits import ensure_can_add_member
from app.api.deps import Principal, get_conn, get_principal, get_session
from app.api.schemas import (
AcceptInviteIn,
AccountIn,
AnnotationIn,
BootstrapIn,
AssigneeIn,
@@ -60,18 +61,15 @@ from app.api.schemas import (
ExternalIn,
FulfillIn,
GrantIn,
InvitationIn,
LoginIn,
MatterIn,
MatterPatch,
MemberIn,
BindingOrderIn,
ContentOrderIn,
ChapterMoveIn,
DatesPatch,
NoteIn,
NotePatch,
RoomIn,
ScopeIn,
TaskDeadlineIn,
ElementReferenceIn,
@@ -82,19 +80,31 @@ from app.api.schemas import (
TaskIn,
TaskPatch,
)
from app.auth.accounts import create_account, list_rooms, normalize_email, start_session
from app.auth.accounts import (
clear_login_attempts,
create_account,
initial_scope,
list_rooms,
login_blocked,
normalize_email,
record_failed_login,
start_session,
)
from app.auth.security import (
clear_session_cookie,
device_label,
hash_secret,
login_bucket,
new_secret,
session_expiry,
set_session_cookie,
verify_password,
verify_unknown_account,
)
from app.core.errors import Problem, forbidden, not_found, too_many, unprocessable
from app.core.errors import DOWNLOAD_REFUSED, 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,
@@ -157,10 +167,11 @@ from app.present import (
note_update_payload,
task_payload,
)
from app.library import case_items, matter_items
from app.ops import share_with_room as _share_with_room
from app.seed import demo_public
router = APIRouter()
_login_attempts: dict[str, list[datetime]] = {}
def _chosen_home(conn, principal: Principal, requested: UUID | None) -> UUID:
@@ -192,7 +203,7 @@ def _chapter_payload(row) -> dict:
def _session_body(conn, account_id: UUID, scope_kind: str, scope_id: UUID, csrf: str, epoch: int) -> dict:
account = conn.execute(
"SELECT id, email, display_name, is_superadmin FROM auth_accounts WHERE id = %s",
"SELECT id, email, display_name, is_superadmin, must_change_password, account_kind FROM auth_accounts WHERE id = %s",
(account_id,),
).fetchone()
room = conn.execute("SELECT id, kind, name FROM data_rooms WHERE id = %s", (scope_id,)).fetchone()
@@ -202,6 +213,8 @@ def _session_body(conn, account_id: UUID, scope_kind: str, scope_id: UUID, csrf:
"email": account["email"],
"display_name": account["display_name"],
"is_superadmin": account["is_superadmin"],
"must_change_password": account["must_change_password"],
"account_kind": account["account_kind"],
},
"scope": {"kind": scope_kind, "id": str(room["id"]), "name": room["name"]},
"rooms": list_rooms(conn, account_id),
@@ -210,29 +223,30 @@ def _session_body(conn, account_id: UUID, scope_kind: str, scope_id: UUID, csrf:
}
def _limit_login(key: str) -> None:
now = utcnow()
window = [item for item in _login_attempts.get(key, []) if now - item < timedelta(minutes=10)]
if len(window) >= 8:
_login_attempts[key] = window
raise too_many()
window.append(now)
_login_attempts[key] = window
@router.post("/api/v1/auth/login")
def login(body: LoginIn, request: Request, conn: Connection = Depends(get_conn)):
email = normalize_email(body.email)
_limit_login(f"{request.client.host if request.client else 'local'}:{email}")
bucket = login_bucket(request.client.host if request.client else "local", email)
if login_blocked(conn, bucket):
raise too_many()
account = conn.execute(
"SELECT * FROM auth_accounts WHERE email = %s",
(email,),
).fetchone()
if account is None or account["status"] != "active" or not verify_password(body.password, account["password_hash"]):
if account is None or account["status"] != "active":
# Same time and same answer as a wrong password.
verify_unknown_account(body.password)
valid = False
else:
valid = verify_password(body.password, account["password_hash"])
if not valid:
record_failed_login(conn, bucket)
raise Problem(401, "Anmeldung fehlgeschlagen", "E-Mail oder Passwort ist nicht richtig.", "unauthorized")
clear_login_attempts(conn, bucket)
settings = request.app.state.settings
token, csrf = start_session(conn, settings, account["id"])
payload = _session_body(conn, account["id"], "personal", account["id"], csrf, 1)
token, csrf = start_session(conn, settings, account["id"], device_label(request.headers.get("user-agent")))
scope_kind, scope_id = initial_scope(conn, account["id"])
payload = _session_body(conn, account["id"], scope_kind, scope_id, csrf, 1)
response = JSONResponse(payload)
set_session_cookie(response, request, settings, token)
return response
@@ -241,6 +255,7 @@ def login(body: LoginIn, request: Request, conn: Connection = Depends(get_conn))
@router.post("/api/v1/auth/logout", status_code=204)
def logout(request: Request, session: dict = Depends(get_session), conn: Connection = Depends(get_conn)):
conn.execute("UPDATE auth_sessions SET revoked_at = now() WHERE id = %s", (session["id"],))
audit(conn, session["account_id"], None, "session_ended", "session", session["id"])
response = Response(status_code=204)
clear_session_cookie(response, request, request.app.state.settings)
return response
@@ -303,99 +318,13 @@ def bootstrap(body: BootstrapIn, request: Request, conn: Connection = Depends(ge
raise not_found()
account = create_account(conn, body.email, body.display_name, body.password, is_superadmin=True)
settings = request.app.state.settings
token, csrf = start_session(conn, settings, account["id"])
token, csrf = start_session(conn, settings, account["id"], device_label(request.headers.get("user-agent")))
payload = _session_body(conn, account["id"], "personal", account["id"], csrf, 1)
response = JSONResponse(status_code=201, content=payload)
set_session_cookie(response, request, settings, token)
return response
def _require_superadmin(conn: Connection, principal: Principal) -> None:
row = conn.execute(
"SELECT is_superadmin FROM auth_accounts WHERE id = %s",
(principal.account_id,),
).fetchone()
if row is None or not row["is_superadmin"]:
raise forbidden("Nur der Betreiber kann Nutzer anlegen.")
@router.get("/api/v1/accounts")
def accounts(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
_require_superadmin(conn, principal)
rows = conn.execute(
"""
SELECT id, email, display_name, is_superadmin, created_at
FROM auth_accounts
WHERE origin = 'operator' AND status = 'active'
ORDER BY display_name, email
"""
).fetchall()
return {
"items": [
{
"id": str(row["id"]),
"email": row["email"],
"display_name": row["display_name"],
"is_superadmin": row["is_superadmin"],
"created_at": dump_dt(row["created_at"]),
}
for row in rows
],
"next_cursor": None,
}
@router.post("/api/v1/accounts")
def post_account(body: AccountIn, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
_require_superadmin(conn, principal)
account = create_account(conn, body.email, body.display_name, body.password)
return _created(
f"/api/v1/accounts/{account['id']}",
{
"id": str(account["id"]),
"email": account["email"],
"display_name": account["display_name"],
"is_superadmin": account["is_superadmin"],
},
)
@router.post("/api/v1/invitations")
def invite(
body: InvitationIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
room = conn.execute("SELECT * FROM data_rooms WHERE id = %s", (body.room_id,)).fetchone()
if room is None or room["kind"] != "organization":
raise not_found()
membership = conn.execute(
"""
SELECT role FROM room_memberships
WHERE room_id = %s AND subject_id = %s AND status = 'active'
""",
(room["id"], principal.account_id),
).fetchone()
if membership is None or membership["role"] != "manager":
raise forbidden()
email = normalize_email(body.email)
if account_by_email(conn, email):
raise unprocessable("Es gibt bereits ein Konto. Füge die Person als Mitglied hinzu.")
token = new_secret()
row = conn.execute(
"""
INSERT INTO auth_invitations (email, room_id, token_hash, invited_by, expires_at)
VALUES (%s, %s, %s, %s, %s)
RETURNING id, expires_at
""",
(email, room["id"], hash_secret(token), principal.account_id, utcnow() + timedelta(days=7)),
).fetchone()
return _created(
f"/api/v1/invitations/{row['id']}",
{"id": str(row["id"]), "email": email, "expires_at": row["expires_at"].isoformat(), "token": token},
)
@router.post("/api/v1/invitations/{invitation_id}/accept")
def accept_invite(
invitation_id: UUID,
@@ -404,143 +333,46 @@ def accept_invite(
conn: Connection = Depends(get_conn),
):
row = conn.execute("SELECT * FROM auth_invitations WHERE id = %s", (invitation_id,)).fetchone()
if row is None or row["accepted_at"] is not None or row["expires_at"] <= utcnow():
if (
row is None
or row["accepted_at"] is not None
or row["revoked_at"] is not None
or row["expires_at"] <= utcnow()
):
raise not_found()
if row["token_hash"] != hash_secret(body.token):
raise not_found()
account = create_account(conn, row["email"], body.display_name, body.password)
room = conn.execute("SELECT owner_id FROM data_rooms WHERE id = %s AND status = 'active'", (row["room_id"],)).fetchone()
if room is None:
raise not_found()
ensure_can_add_member(conn, room["owner_id"], row["room_id"])
# An invitation creates an employee account. The owner of the room is the sponsor.
account = create_account(
conn,
row["email"],
body.display_name,
body.password,
account_kind="employee",
sponsor_id=room["owner_id"],
)
conn.execute(
"""
INSERT INTO room_memberships (room_id, subject_id, role)
VALUES (%s, %s, 'member')
VALUES (%s, %s, %s)
""",
(row["room_id"], account["id"]),
(row["room_id"], account["id"], row["role"]),
)
conn.execute("UPDATE auth_invitations SET accepted_at = now() WHERE id = %s", (invitation_id,))
audit(conn, account["id"], row["room_id"], "invitation_accepted", "invitation", invitation_id)
settings = request.app.state.settings
token, csrf = start_session(conn, settings, account["id"])
payload = _session_body(conn, account["id"], "personal", account["id"], csrf, 1)
token, csrf = start_session(conn, settings, account["id"], device_label(request.headers.get("user-agent")))
scope_kind, scope_id = initial_scope(conn, account["id"])
payload = _session_body(conn, account["id"], scope_kind, scope_id, csrf, 1)
response = JSONResponse(status_code=201, content=payload)
set_session_cookie(response, request, settings, token)
return response
@router.get("/api/v1/rooms")
def rooms(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
return {"items": list_rooms(conn, principal.account_id), "next_cursor": None}
@router.post("/api/v1/rooms")
def create_room(body: RoomIn, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
from uuid import uuid4
room_id = uuid4()
conn.execute(
"""
INSERT INTO data_rooms (id, kind, name, created_by)
VALUES (%s, 'organization', %s, %s)
""",
(room_id, body.name.strip(), principal.account_id),
)
conn.execute(
"""
INSERT INTO room_memberships (room_id, subject_id, role)
VALUES (%s, %s, 'manager')
""",
(room_id, principal.account_id),
)
return _created(f"/api/v1/rooms/{room_id}", {"id": str(room_id), "kind": "organization", "name": body.name.strip()})
@router.get("/api/v1/rooms/{room_id}/members")
def members(room_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
_require_manager(conn, principal, room_id)
rows = conn.execute(
"""
SELECT m.subject_id, m.role, a.email, a.display_name
FROM room_memberships m
JOIN auth_accounts a ON a.id = m.subject_id
WHERE m.room_id = %s AND m.status = 'active'
ORDER BY a.display_name, a.id
""",
(room_id,),
).fetchall()
return {
"items": [
{
"subject_id": str(row["subject_id"]),
"email": row["email"],
"display_name": row["display_name"],
"role": row["role"],
}
for row in rows
]
}
@router.post("/api/v1/rooms/{room_id}/members")
def add_member(
room_id: UUID,
body: MemberIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
_require_manager(conn, principal, room_id)
account = account_by_email(conn, body.email)
if account is None or account["status"] != "active":
raise not_found()
conn.execute(
"""
INSERT INTO room_memberships (room_id, subject_id, role, status)
VALUES (%s, %s, %s, 'active')
ON CONFLICT (room_id, subject_id) DO UPDATE SET role = EXCLUDED.role, status = 'active'
""",
(room_id, account["id"], body.role),
)
return {"subject_id": str(account["id"]), "role": body.role}
@router.delete("/api/v1/rooms/{room_id}/members/{subject_id}", status_code=204)
def remove_member(
room_id: UUID,
subject_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
_require_manager(conn, principal, room_id)
if subject_id == principal.account_id:
managers = conn.execute(
"""
SELECT count(*) AS n FROM room_memberships
WHERE room_id = %s AND role = 'manager' AND status = 'active'
""",
(room_id,),
).fetchone()
if managers["n"] <= 1:
raise unprocessable("Der letzte Verwalter kann den Datenraum nicht verlassen.")
conn.execute(
"""
UPDATE room_memberships SET status = 'removed'
WHERE room_id = %s AND subject_id = %s
""",
(room_id, subject_id),
)
return Response(status_code=204)
def _require_manager(conn, principal: Principal, room_id: UUID) -> None:
membership = conn.execute(
"""
SELECT role FROM room_memberships
WHERE room_id = %s AND subject_id = %s AND status = 'active'
""",
(room_id, principal.account_id),
).fetchone()
room = conn.execute("SELECT kind FROM data_rooms WHERE id = %s", (room_id,)).fetchone()
if room is None or room["kind"] != "organization" or membership is None or membership["role"] != "manager":
raise forbidden()
@router.get("/api/v1/principals")
def find_principal(email: str, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
account = account_by_email(conn, email)
@@ -551,18 +383,7 @@ def find_principal(email: str, principal: Principal = Depends(get_principal), co
@router.get("/api/v1/cases")
def cases(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
items = []
for case, rights in list_cases(conn, principal.account_id):
summary = case_summary(case, rights)
summary["home_scope_name"] = room_name(conn, case["home_scope_id"])
summary["kind_label"] = "Unterakte" if case["parent_case_id"] else "Akte"
summary["parent_title"] = None
if case["parent_case_id"]:
parent = get_case(conn, case["parent_case_id"])
if parent is not None and case_rights(conn, principal.account_id, parent).read:
summary["parent_title"] = parent["title"]
items.append(summary)
return {"items": items, "next_cursor": None}
return {"items": case_items(conn, principal.account_id, list_cases(conn, principal.account_id)), "next_cursor": None}
@router.post("/api/v1/cases")
@@ -575,6 +396,8 @@ def post_case(body: CaseIn, principal: Principal = Depends(get_principal), conn:
body.parent_case_id,
body.rights_mode,
)
if body.share_with_room_id is not None:
_share_with_room(conn, principal.account_id, "case", case["id"], body.share_with_room_id, "edit")
rights = case_rights(conn, principal.account_id, case)
return _created(f"/api/v1/cases/{case['id']}", case_summary(case, rights))
@@ -659,8 +482,7 @@ def post_case_grant(
@router.get("/api/v1/matters")
def matters(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
items = [matter_summary(conn, principal.account_id, matter) for matter, _contexts in list_matters(conn, principal.account_id)]
return {"items": items, "next_cursor": None}
return {"items": matter_items(conn, principal.account_id, list_matters(conn, principal.account_id)), "next_cursor": None}
@router.post("/api/v1/matters")
@@ -673,6 +495,8 @@ def post_matter(body: MatterIn, principal: Principal = Depends(get_principal), c
body.parent_matter_id,
_ctx_model(body.context),
)
if body.share_with_room_id is not None:
_share_with_room(conn, principal.account_id, "matter", matter["id"], body.share_with_room_id, "edit")
return _created(f"/api/v1/matters/{matter['id']}", matter_summary(conn, principal.account_id, matter))
@@ -1108,6 +932,7 @@ def download_file(
request: Request,
context_kind: str | None = None,
context_id: str | None = None,
save: bool = False,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
@@ -1118,13 +943,27 @@ def download_file(
rights = element_rights(conn, principal.account_id, element, context)
if not rights.read:
raise not_found()
if save and not rights.download:
raise forbidden(DOWNLOAD_REFUSED)
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"],
@@ -1343,37 +1182,61 @@ def post_fulfill(
return deadline_payload(conn, principal.account_id, deadline)
VIEW_LIMIT = 200
SEARCH_LIMIT = 50
SCAN_BATCH = 200
SCAN_CAP = 20000
def _scan(conn, sql: str, params: tuple = ()):
"""Rows in the order of the query, read in batches.
The rights are checked per row after reading. A fixed LIMIT in the query would count rows
of other people too, so the own ones could fall off the end. The reader stops once it has
enough. `SCAN_CAP` bounds the work on very large data sets.
"""
offset = 0
while offset < SCAN_CAP:
rows = conn.execute(f"{sql} LIMIT %s OFFSET %s", (*params, SCAN_BATCH, offset)).fetchall()
yield from rows
if len(rows) < SCAN_BATCH:
return
offset += SCAN_BATCH
@router.get("/api/v1/views/open-tasks")
def open_tasks(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
rows = conn.execute(
items = []
for task in _scan(
conn,
"""
SELECT * FROM tasks
WHERE deleted_at IS NULL AND task_status = 'open'
ORDER BY due_on NULLS LAST, created_at, id
LIMIT 200
"""
).fetchall()
items = []
for task in rows:
""",
):
if _task_visible(conn, principal.account_id, task):
items.append(task_payload(conn, principal.account_id, task))
if len(items) >= VIEW_LIMIT:
break
return {"items": items, "next_cursor": None}
@router.get("/api/v1/views/open-deadlines")
def open_deadlines(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
rows = conn.execute(
items = []
for deadline in _scan(
conn,
"""
SELECT * FROM deadlines
WHERE deleted_at IS NULL AND deadline_status = 'open'
ORDER BY due_on, created_at, id
LIMIT 200
"""
).fetchall()
items = []
for deadline in rows:
""",
):
if _deadline_visible(conn, principal.account_id, deadline):
items.append(deadline_payload(conn, principal.account_id, deadline))
if len(items) >= VIEW_LIMIT:
break
return {"items": items, "next_cursor": None}
@@ -1427,19 +1290,21 @@ def search(q: str, principal: Principal = Depends(get_principal), conn: Connecti
],
}
)
elements = conn.execute(
elements = _scan(
conn,
"""
SELECT e.*
FROM elements e
LEFT JOIN note_bodies n ON n.element_id = e.id
WHERE e.deleted_at IS NULL
AND (e.title ILIKE %s ESCAPE '\\' OR COALESCE(n.document_json::text, '') ILIKE %s ESCAPE '\\')
ORDER BY e.updated_at DESC
LIMIT 100
ORDER BY e.updated_at DESC, e.id
""",
(pattern, pattern),
).fetchall()
)
for element in elements:
if len(items) >= SEARCH_LIMIT:
break
from app.access.policy import visible_bindings_for_element
bindings = visible_bindings_for_element(conn, principal.account_id, element)
@@ -1467,7 +1332,7 @@ def search(q: str, principal: Principal = Depends(get_principal), conn: Connecti
],
}
)
return {"items": items[:50], "next_cursor": None}
return {"items": items[:SEARCH_LIMIT], "next_cursor": None}
@router.patch("/api/v1/cases/{case_id}/content-order")
+91 -4
View File
@@ -27,9 +27,28 @@ class BootstrapIn(APIModel):
class AccountIn(APIModel):
"""Without a password the server generates a one-time password."""
email: Email
display_name: str = Field(min_length=1, max_length=120)
password: str = Field(min_length=10, max_length=200)
password: str | None = Field(default=None, min_length=10, max_length=200)
is_operator: bool = False
class AccountPatchIn(APIModel):
display_name: str | None = Field(default=None, min_length=1, max_length=120)
is_operator: bool | None = None
status: Literal["active", "disabled"] | None = None
account_kind: Literal["main"] | None = None
class TeamPatchIn(APIModel):
status: Literal["active", "disabled"]
class PasswordChangeIn(APIModel):
current_password: str = Field(min_length=1, max_length=200)
new_password: str = Field(min_length=10, max_length=200)
class ScopeIn(APIModel):
@@ -46,15 +65,61 @@ class AcceptInviteIn(APIModel):
class InvitationIn(APIModel):
email: Email
room_id: UUID
role: Literal["member", "manager", "reader"] = "member"
class RoomIn(APIModel):
name: str = Field(min_length=1, max_length=160)
default_visibility: Literal["private", "room"] = "room"
class VisibilityIn(APIModel):
visibility: Literal["private", "room"]
class ShareItemIn(APIModel):
kind: Literal["case", "matter"]
id: UUID
class BatchShareIn(APIModel):
items: list[ShareItemIn] = Field(min_length=1, max_length=200)
access: Literal["read", "edit"] = "edit"
class RoomShareIn(APIModel):
access: Literal["read", "edit"] = "edit"
class ExclusionIn(APIModel):
excluded: bool
class OwnerIn(APIModel):
subject_id: UUID
class OperatorOwnerIn(APIModel):
email: Email
class MemberIn(APIModel):
email: Email
role: Literal["member", "manager"]
role: Literal["member", "manager", "reader"]
class MemberRoleIn(APIModel):
role: Literal["member", "manager", "reader"]
class RoomPatchIn(APIModel):
name: str | None = Field(default=None, min_length=1, max_length=160)
status: Literal["active", "archived"] | None = None
default_visibility: Literal["private", "room"] | None = None
class OperatorManagerIn(APIModel):
email: Email
class ContextIn(APIModel):
@@ -67,6 +132,7 @@ class CaseIn(APIModel):
parent_case_id: UUID | None = None
rights_mode: Literal["inherit_parent", "explicit"] = "inherit_parent"
home_scope_id: UUID | None = None
share_with_room_id: UUID | None = None
class CasePatch(APIModel):
@@ -142,6 +208,7 @@ class MatterIn(APIModel):
parent_matter_id: UUID | None = None
context: ContextIn | None = None
home_scope_id: UUID | None = None
share_with_room_id: UUID | None = None
class MatterPatch(APIModel):
@@ -278,7 +345,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 +355,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 +371,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 | int | None] | None = None
class SourceAssignmentIn(APIModel):
connector_id: UUID
class DeleteElementIn(APIModel):
@@ -441,3 +519,12 @@ class DispatchCorrectIn(APIModel):
clear_sent_on: bool = False
counterpart: str | None = Field(default=None, max_length=200)
clear_counterpart: bool = False
class DownloadPolicyIn(APIModel):
"""Who may save or open the original outside of Tsumugu. `direct` only applies to the account default."""
manager: bool
member: bool
reader: bool
direct: bool | None = None
+318 -51
View File
@@ -8,26 +8,30 @@ 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.mailpack import parse_mail
from app.api.schemas import ConnectorIn, ExternalIn, SourceAssignmentIn
from app.core.errors import DOWNLOAD_REFUSED, forbidden, not_found, unprocessable, unsupported
from app.mailpack import _inline_images, parse_mail, sanitize_html
from app.remoteimages import RemoteImages
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
from app.sources import (
clean_base_url,
connector_detail,
delete_connector,
imap_mailboxes,
imap_messages,
imap_preview,
list_connectors,
paperless_documents,
owned_connector,
paperless_content,
parse_connector,
probe,
read_linked_mail,
read_linked_paperless,
save_connector,
update_connector,
)
_PRIVATE = {
@@ -44,13 +48,38 @@ 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)
name, settings, secret = _connector_parts(body, None)
row = save_connector(conn, principal.account_id, body.kind, name, settings, secret)
return row
@router.get("/api/v1/connectors/{connector_id}")
def get_connector(connector_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
return connector_detail(conn, principal.account_id, connector_id)
@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),
):
current = owned_connector(conn, principal.account_id, connector_id)
if current["kind"] != body.kind:
raise unprocessable("Der Zugang bleibt bei seiner Quellenart.")
name, settings, secret = _connector_parts(body, current)
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,24 +91,27 @@ 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,
save: bool = False,
principal: Principal = Depends(get_principal),
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)
safe_name = (filename or "dokument.pdf").replace('"', "")
if save:
_require_download(conn, principal, element, context)
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)
return Response(
content=data,
media_type=media_type,
headers={
**_PRIVATE,
"Content-Disposition": f'inline; filename="{safe_name}"',
"Content-Disposition": content_disposition(filename or "dokument.pdf").replace("attachment;", "inline;", 1),
},
)
@@ -101,14 +133,19 @@ def view_mail(
"message_to": parsed.recipient,
"message_cc": parsed.copy,
"text": parsed.text,
"text_truncated": False,
"complete": True,
"html": parsed.html,
"remote_images": len(parsed.remote_images),
"text_truncated": parsed.text_truncated,
"complete": not parsed.missing,
"notices": parsed.notices,
"attachments": [
{
"index": index,
"filename": item.filename,
"filename": item.display_name or item.filename,
"archive_name": item.filename,
"content_type": item.media_type,
"byte_size": len(item.data),
"inline": item.inline,
}
for index, item in enumerate(parsed.attachments)
],
@@ -117,6 +154,11 @@ def view_mail(
)
def _require_download(conn, principal: Principal, element, context) -> None:
if not element_rights(conn, principal.account_id, element, context).download:
raise forbidden(DOWNLOAD_REFUSED)
def _opened_ref(conn, principal: Principal, element_id: UUID, context_kind: str | None, context_id: str | None):
element = get_element(conn, element_id)
if element is None or element["kind"] != "external_ref":
@@ -126,14 +168,23 @@ 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
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])
@@ -141,6 +192,25 @@ def _complete_mail(conn, principal: Principal, element, context, ref):
return parsed, raw
@router.get("/api/v1/external-refs/{element_id}/mail/html-with-images")
def view_mail_with_images(
element_id: UUID,
context_kind: str | None = None,
context_id: str | None = None,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
"""The formatted mail with its pictures from other servers, loaded by the server on request."""
element, context, ref = _opened_ref(conn, principal, element_id, context_kind, context_id)
parsed, _raw = _complete_mail(conn, principal, element, context, ref)
loader = RemoteImages()
rendered = sanitize_html(parsed.html_source, _inline_images(parsed.attachments), remote=loader) if parsed.html_source else ""
return JSONResponse(
content={"html": rendered, "loaded": loader.loaded, "failed": loader.failed},
headers={"Cache-Control": "private, no-store", "Referrer-Policy": "no-referrer"},
)
@router.get("/api/v1/external-refs/{element_id}/mail/original")
def download_mail(
element_id: UUID,
@@ -150,8 +220,9 @@ def download_mail(
conn: Connection = Depends(get_conn),
):
element, context, ref = _opened_ref(conn, principal, element_id, context_kind, context_id)
_parsed, raw = _complete_mail(conn, principal, element, context, ref)
return _mail_bytes(raw, "message/rfc822", "nachricht.eml")
_require_download(conn, principal, element, context)
parsed, raw = _complete_mail(conn, principal, element, context, ref)
return _mail_bytes(raw, "message/rfc822", f"{parsed.subject or 'nachricht'}.eml")
@router.get("/api/v1/external-refs/{element_id}/mail/attachments/{index}")
@@ -160,21 +231,29 @@ def download_mail_attachment(
index: int,
context_kind: str | None = None,
context_id: str | None = None,
save: bool = False,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
element, context, ref = _opened_ref(conn, principal, element_id, context_kind, context_id)
if save:
_require_download(conn, principal, element, context)
parsed, _raw = _complete_mail(conn, principal, element, context, ref)
if index < 0 or index >= len(parsed.attachments):
raise not_found()
item = parsed.attachments[index]
return _mail_bytes(item.data, item.media_type or "application/octet-stream", item.filename, inline=True)
name = item.display_name or item.filename or "anlage"
media = (item.media_type or "application/octet-stream").split(";", 1)[0].strip()
if item.data[:1024].lstrip(b"\xef\xbb\xbf\r\n\t ").startswith(b"%PDF"):
media = "application/pdf"
if not name.lower().endswith(".pdf"):
leaf = name.replace("\\", "/").split("/")[-1]
name = name if "." in leaf else f"{name}.pdf"
return _mail_bytes(item.data, media or "application/octet-stream", name, inline=True)
def _mail_bytes(data: bytes, media_type: str, filename: str, inline: bool = False) -> Response:
disposition = content_disposition(filename)
if inline:
disposition = disposition.replace("attachment;", "inline;", 1)
disposition = content_disposition(filename, inline=inline)
return Response(
content=data,
media_type=media_type,
@@ -186,8 +265,67 @@ 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/{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")
@@ -196,7 +334,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 +343,40 @@ 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 = "",
uidvalidity: int | None = None,
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,
},
uidvalidity,
)
@router.get("/api/v1/sources/imap/message")
@@ -228,8 +394,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 +414,121 @@ 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"]})
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
@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, current: dict | None) -> tuple[str, dict, str]:
"""The registered module validates. Flat fields of the first release are folded into ``config``."""
flat = body.model_dump(exclude={"kind", "name", "config"})
return parse_connector(body.kind, body.name, flat, body.config, current)
_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, 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))]
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) + ".")
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)
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})
+245
View File
@@ -0,0 +1,245 @@
"""Team of a main user and the operator's overview of all teams.
A main user sees the people in the rooms he owns and manages the employees he invited.
The operator sees main users with their employees, rooms and roles: accounts and roles, never content.
"""
from __future__ import annotations
import csv
import io
from uuid import UUID
from fastapi import APIRouter, Depends, Response
from fastapi.responses import JSONResponse
from psycopg import Connection
from app.access.policy import audit
from app.access.roles import require_main_user, require_operator
from app.api.deps import Principal, get_conn, get_principal
from app.api.rooms import _audit_membership, _drop_shares_of
from app.api.schemas import TeamPatchIn
from app.auth.accounts import reset_password, set_status
from app.core.errors import forbidden
from app.core.timeutil import dump_dt
router = APIRouter()
_NO_STORE = {"Cache-Control": "no-store"}
def _own_employee(conn, owner_id: UUID, account_id: UUID) -> dict:
"""An employee this main user invited. Unknown and foreign accounts answer alike."""
row = conn.execute(
"SELECT id, status FROM auth_accounts WHERE id = %s AND account_kind = 'employee' AND sponsor_id = %s",
(account_id, owner_id),
).fetchone()
if row is None:
raise forbidden("Das ist keiner deiner Mitarbeiter.")
return row
@router.get("/api/v1/team")
def team(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
require_main_user(conn, principal.account_id)
me = principal.account_id
people = conn.execute(
"""
SELECT DISTINCT a.id, a.display_name, a.email, a.status, a.account_kind, a.last_login_at,
(a.sponsor_id = %s) AS mine
FROM auth_accounts a
WHERE a.id <> %s AND (
a.sponsor_id = %s
OR EXISTS (
SELECT 1 FROM room_memberships m JOIN data_rooms r ON r.id = m.room_id
WHERE m.subject_id = a.id AND m.status = 'active'
AND r.kind = 'organization' AND r.owner_id = %s
)
)
ORDER BY a.display_name, a.id
""",
(me, me, me, me),
).fetchall()
rooms = conn.execute(
"""
SELECT m.subject_id, r.id AS room_id, r.name, r.status, m.role
FROM room_memberships m JOIN data_rooms r ON r.id = m.room_id
WHERE m.status = 'active' AND r.kind = 'organization' AND r.owner_id = %s AND m.subject_id <> %s
ORDER BY r.name, r.id
""",
(me, me),
).fetchall()
by_person: dict = {}
for row in rooms:
by_person.setdefault(row["subject_id"], []).append(
{"room_id": str(row["room_id"]), "name": row["name"], "archived": row["status"] != "active", "role": row["role"]}
)
return JSONResponse(
{
"items": [
{
"id": str(person["id"]),
"display_name": person["display_name"],
"email": person["email"],
"status": person["status"],
"account_kind": person["account_kind"],
"last_login_at": dump_dt(person["last_login_at"]),
"mine": person["mine"],
"rooms": by_person.get(person["id"], []),
}
for person in people
]
},
headers=_NO_STORE,
)
@router.patch("/api/v1/team/{account_id}")
def patch_team_member(
account_id: UUID,
body: TeamPatchIn,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_main_user(conn, principal.account_id)
_own_employee(conn, principal.account_id, account_id)
set_status(conn, principal.account_id, account_id, body.status)
return {"id": str(account_id), "status": body.status}
@router.post("/api/v1/team/{account_id}/password-reset")
def reset_team_password(
account_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
require_main_user(conn, principal.account_id)
_own_employee(conn, principal.account_id, account_id)
password = reset_password(conn, principal.account_id, account_id)
audit(conn, principal.account_id, None, "employee_password_reset", "account", account_id)
return JSONResponse({"temporary_password": password}, headers=_NO_STORE)
@router.delete("/api/v1/team/{account_id}/memberships", status_code=204)
def remove_from_my_rooms(
account_id: UUID,
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
"""End the memberships of one person in all rooms this main user owns."""
require_main_user(conn, principal.account_id)
rows = conn.execute(
"""
SELECT m.room_id FROM room_memberships m JOIN data_rooms r ON r.id = m.room_id
WHERE m.subject_id = %s AND m.status = 'active' AND r.kind = 'organization' AND r.owner_id = %s
FOR UPDATE OF m
""",
(account_id, principal.account_id),
).fetchall()
if account_id == principal.account_id or not rows:
raise forbidden("Diese Person ist in keinem deiner Räume Mitglied.")
for row in rows:
room_id = row["room_id"]
conn.execute(
"UPDATE room_memberships SET status = 'removed' WHERE room_id = %s AND subject_id = %s",
(room_id, account_id),
)
_drop_shares_of(conn, room_id, account_id)
conn.execute(
"""
UPDATE auth_sessions
SET scope_kind = 'personal', scope_id = account_id, epoch = epoch + 1
WHERE account_id = %s AND scope_id = %s AND revoked_at IS NULL
""",
(account_id, room_id),
)
_audit_membership(conn, principal.account_id, room_id, account_id, "membership_removed")
audit(conn, principal.account_id, None, "employee_removed", "account", account_id, detail={"rooms": len(rows)})
return Response(status_code=204)
def _csv_cell(value) -> str:
text = "" if value is None else str(value)
# A cell that starts like a formula would run in a spreadsheet.
return "'" + text if text[:1] in {"=", "+", "-", "@", "\t", "\r"} else text
@router.get("/api/v1/admin/team")
def admin_team(
format: str = "json",
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
"""Main users with their employees, rooms and roles. Metadata only."""
require_operator(conn, principal.account_id)
owners = conn.execute(
"""
SELECT a.id, a.display_name, a.email, a.status
FROM auth_accounts a
WHERE a.account_kind = 'main'
AND (EXISTS (SELECT 1 FROM auth_accounts e WHERE e.sponsor_id = a.id)
OR EXISTS (SELECT 1 FROM data_rooms r WHERE r.owner_id = a.id AND r.kind = 'organization'))
ORDER BY a.display_name, a.id
"""
).fetchall()
employees = conn.execute(
"""
SELECT e.id, e.sponsor_id, e.display_name, e.email, e.status, e.last_login_at
FROM auth_accounts e WHERE e.account_kind = 'employee'
ORDER BY e.display_name, e.id
"""
).fetchall()
memberships = conn.execute(
"""
SELECT m.subject_id, r.id AS room_id, r.name, r.status, r.owner_id, m.role
FROM room_memberships m JOIN data_rooms r ON r.id = m.room_id
WHERE m.status = 'active' AND r.kind = 'organization'
ORDER BY r.name, r.id
"""
).fetchall()
rooms_of: dict = {}
for row in memberships:
rooms_of.setdefault(row["subject_id"], []).append(row)
result = []
for owner in owners:
mine = [e for e in employees if e["sponsor_id"] == owner["id"]]
result.append(
{
"id": str(owner["id"]),
"display_name": owner["display_name"],
"email": owner["email"],
"status": owner["status"],
"employees": [
{
"id": str(e["id"]),
"display_name": e["display_name"],
"email": e["email"],
"status": e["status"],
"last_login_at": dump_dt(e["last_login_at"]),
"rooms": [
{"room_id": str(r["room_id"]), "name": r["name"], "archived": r["status"] != "active", "role": r["role"]}
for r in rooms_of.get(e["id"], [])
],
}
for e in mine
],
}
)
if format == "csv":
out = io.StringIO()
writer = csv.writer(out)
writer.writerow(["Hauptnutzer", "Mitarbeiter", "E-Mail", "Status", "Datenraum", "Rolle"])
for owner in result:
for e in owner["employees"]:
if not e["rooms"]:
writer.writerow([_csv_cell(v) for v in (owner["display_name"], e["display_name"], e["email"], e["status"], "", "")])
for room in e["rooms"]:
writer.writerow(
[_csv_cell(v) for v in (owner["display_name"], e["display_name"], e["email"], e["status"], room["name"], room["role"])]
)
return Response(
content=out.getvalue(),
media_type="text/csv; charset=utf-8",
headers={"Content-Disposition": 'attachment; filename="team-uebersicht.csv"', **_NO_STORE},
)
return JSONResponse({"items": result}, headers=_NO_STORE)
+258 -18
View File
@@ -1,18 +1,42 @@
"""Accounts, personal rooms and sessions."""
"""Accounts, personal rooms, sessions and the administrative account actions."""
from __future__ import annotations
import secrets
from uuid import UUID, uuid4
from app.auth.security import hash_password, hash_secret, new_secret, session_expiry
from app.core.errors import unprocessable
from app.access.policy import audit
from app.access.roles import count_active_operators
from app.auth.security import (
hash_password,
hash_secret,
new_secret,
session_expiry,
verify_password,
)
from app.core.errors import not_found, unprocessable
from app.core.settings import Settings
MIN_PASSWORD = 10
MAX_PASSWORD_BYTES = 72
def normalize_email(email: str) -> str:
return email.strip().lower()
def check_password_policy(password: str) -> None:
if len(password) < MIN_PASSWORD:
raise unprocessable(f"Das Passwort braucht mindestens {MIN_PASSWORD} Zeichen.")
if len(password.encode("utf-8")) > MAX_PASSWORD_BYTES:
raise unprocessable("Das Passwort ist zu lang. Erlaubt sind höchstens 72 Byte.")
def generate_password() -> str:
"""A one-time password for hand-over. It is shown once and must be changed at the first login."""
return secrets.token_urlsafe(12)
def create_account(
conn,
email: str,
@@ -21,50 +45,255 @@ def create_account(
*,
is_superadmin: bool = False,
origin: str = "operator",
must_change_password: bool = False,
account_kind: str = "main",
sponsor_id: UUID | None = None,
) -> dict:
email = normalize_email(email)
display_name = display_name.strip()
if origin not in {"operator", "fixture"}:
raise unprocessable("Die Kontenherkunft ist ungültig.")
if account_kind not in {"main", "employee"} or (account_kind == "employee") != (sponsor_id is not None):
raise unprocessable("Die Kontoart ist ungültig.")
check_password_policy(password)
if conn.execute("SELECT 1 FROM auth_accounts WHERE email = %s", (email,)).fetchone():
raise unprocessable("Für diese E-Mail gibt es bereits ein Konto.")
account_id = uuid4()
password_hash = hash_password(password)
conn.execute(
"""
INSERT INTO auth_accounts (id, email, display_name, password_hash, is_superadmin, origin)
VALUES (%s, %s, %s, %s, %s, %s)
INSERT INTO auth_accounts (
id, email, display_name, password_hash, is_superadmin, origin,
must_change_password, password_changed_at, account_kind, sponsor_id
)
VALUES (%s, %s, %s, %s, %s, %s, %s, now(), %s, %s)
""",
(account_id, email, display_name, password_hash, is_superadmin, origin),
(
account_id, email, display_name, password_hash, is_superadmin, origin,
must_change_password, account_kind, sponsor_id,
),
)
conn.execute(
"""
INSERT INTO data_rooms (id, kind, name, created_by)
VALUES (%s, 'personal', 'Persönlicher Raum', %s)
INSERT INTO data_rooms (id, kind, name, created_by, owner_id)
VALUES (%s, 'personal', 'Persönlicher Raum', %s, %s)
""",
(account_id, account_id),
(account_id, account_id, account_id),
)
return conn.execute(
"SELECT id, email, display_name, is_superadmin FROM auth_accounts WHERE id = %s",
"""
SELECT id, email, display_name, is_superadmin, status, must_change_password, account_kind
FROM auth_accounts WHERE id = %s
""",
(account_id,),
).fetchone()
def start_session(conn, settings: Settings, account_id: UUID) -> tuple[str, str]:
def promote_to_main(conn, actor: UUID, account_id: UUID) -> None:
"""Only the operator turns an employee into a main user."""
account = _account(conn, account_id, lock=True)
if account["account_kind"] == "main":
return
conn.execute("UPDATE auth_accounts SET account_kind = 'main', sponsor_id = NULL WHERE id = %s", (account_id,))
# A raised kind starts from a fresh login.
revoke_sessions(conn, account_id)
audit(conn, actor, None, "employee_promoted", "account", account_id)
def initial_scope(conn, account_id: UUID) -> tuple[str, UUID]:
"""Where a new session starts: the personal room, or for an employee the first team room."""
account = conn.execute("SELECT account_kind FROM auth_accounts WHERE id = %s", (account_id,)).fetchone()
if account is not None and account["account_kind"] == "employee":
room = conn.execute(
"""
SELECT r.id FROM room_memberships m JOIN data_rooms r ON r.id = m.room_id
WHERE m.subject_id = %s AND m.status = 'active' AND r.kind = 'organization' AND r.status = 'active'
ORDER BY r.name, r.id LIMIT 1
""",
(account_id,),
).fetchone()
if room is not None:
return "organization", room["id"]
return "personal", account_id
def start_session(conn, settings: Settings, account_id: UUID, label: str | None = None) -> tuple[str, str]:
token = new_secret()
csrf = new_secret()
conn.execute(
scope_kind, scope_id = initial_scope(conn, account_id)
session = conn.execute(
"""
INSERT INTO auth_sessions (
account_id, secret_hash, csrf_token, scope_kind, scope_id, expires_at
account_id, secret_hash, csrf_token, scope_kind, scope_id, expires_at, label, last_seen_at
)
VALUES (%s, %s, %s, 'personal', %s, %s)
VALUES (%s, %s, %s, %s, %s, %s, %s, now())
RETURNING id
""",
(account_id, hash_secret(token), csrf, account_id, session_expiry(settings)),
)
(account_id, hash_secret(token), csrf, scope_kind, scope_id, session_expiry(settings), (label or None) and label[:80]),
).fetchone()
conn.execute("UPDATE auth_accounts SET last_login_at = now() WHERE id = %s", (account_id,))
audit(conn, account_id, None, "session_started", "session", session["id"])
return token, csrf
def _account(conn, account_id: UUID, *, lock: bool = False) -> dict:
suffix = " FOR UPDATE" if lock else ""
row = conn.execute(f"SELECT * FROM auth_accounts WHERE id = %s{suffix}", (account_id,)).fetchone()
if row is None:
raise not_found()
return row
def revoke_sessions(conn, account_id: UUID, *, keep: UUID | None = None) -> int:
rows = conn.execute(
"""
UPDATE auth_sessions SET revoked_at = now()
WHERE account_id = %s AND revoked_at IS NULL AND (%s::uuid IS NULL OR id <> %s::uuid)
RETURNING id
""",
(account_id, keep, keep),
).fetchall()
return len(rows)
def set_display_name(conn, actor: UUID, account_id: UUID, display_name: str) -> None:
name = " ".join(display_name.split())
if not name or len(name) > 120:
raise unprocessable("Der Name ist ungültig.")
_account(conn, account_id)
conn.execute("UPDATE auth_accounts SET display_name = %s WHERE id = %s", (name, account_id))
audit(conn, actor, None, "account_renamed", "account", account_id)
def set_status(conn, actor: UUID, account_id: UUID, status: str) -> None:
"""Disable or enable. A disabled account keeps its content, owner links and audit trail."""
if status not in {"active", "disabled"}:
raise unprocessable("Der Kontostatus ist ungültig.")
# Lock the operators first so two parallel changes cannot remove the last one.
operators = count_active_operators(conn, lock=True)
account = _account(conn, account_id, lock=True)
if account["status"] == status:
return
if status == "disabled":
if account_id == actor:
raise unprocessable("Du kannst dein eigenes Konto nicht deaktivieren.")
owned = _owned_shared_rooms(conn, account_id)
if owned:
raise unprocessable(
f"Das Konto ist Eigentümer von {owned} Datenraum(en) mit weiteren Mitgliedern. "
"Der Eigentümer überträgt sie zuerst, oder der Betreiber setzt einen neuen Eigentümer ein."
)
if account["is_superadmin"] and operators <= 1:
raise unprocessable("Der letzte Betreiber lässt sich nicht deaktivieren.")
conn.execute(
"UPDATE auth_accounts SET status = 'disabled', disabled_at = now(), disabled_by = %s WHERE id = %s",
(actor, account_id),
)
revoke_sessions(conn, account_id)
audit(conn, actor, None, "account_disabled", "account", account_id)
else:
conn.execute(
"UPDATE auth_accounts SET status = 'active', disabled_at = NULL, disabled_by = NULL WHERE id = %s",
(account_id,),
)
audit(conn, actor, None, "account_enabled", "account", account_id)
def set_operator(conn, actor: UUID, account_id: UUID, value: bool) -> None:
operators = count_active_operators(conn, lock=True)
account = _account(conn, account_id, lock=True)
if bool(account["is_superadmin"]) == value:
return
if value:
if account["status"] != "active":
raise unprocessable("Ein deaktiviertes Konto kann nicht Betreiber werden.")
conn.execute("UPDATE auth_accounts SET is_superadmin = true WHERE id = %s", (account_id,))
# A raised role starts from a fresh login (Auth blueprint).
revoke_sessions(conn, account_id)
audit(conn, actor, None, "operator_granted", "account", account_id)
return
if account["status"] == "active" and operators <= 1:
raise unprocessable("Der letzte Betreiber lässt sich nicht zurückstufen.")
conn.execute("UPDATE auth_accounts SET is_superadmin = false WHERE id = %s", (account_id,))
audit(conn, actor, None, "operator_revoked", "account", account_id)
def reset_password(conn, actor: UUID, account_id: UUID) -> str:
if account_id == actor:
raise unprocessable("Dein eigenes Passwort änderst du unter Mein Konto.")
account = _account(conn, account_id, lock=True)
if account["status"] != "active":
raise unprocessable("Für ein deaktiviertes Konto lässt sich kein Passwort setzen.")
password = generate_password()
conn.execute(
"""
UPDATE auth_accounts
SET password_hash = %s, must_change_password = true, password_changed_at = now()
WHERE id = %s
""",
(hash_password(password), account_id),
)
revoke_sessions(conn, account_id)
audit(conn, actor, None, "password_reset", "account", account_id)
return password
def change_own_password(conn, account_id: UUID, session_id: UUID, current: str, new: str) -> None:
account = _account(conn, account_id, lock=True)
if not verify_password(current, account["password_hash"]):
raise unprocessable("Das aktuelle Passwort ist nicht richtig.")
check_password_policy(new)
if verify_password(new, account["password_hash"]):
raise unprocessable("Das neue Passwort muss sich vom bisherigen unterscheiden.")
conn.execute(
"""
UPDATE auth_accounts
SET password_hash = %s, must_change_password = false, password_changed_at = now()
WHERE id = %s
""",
(hash_password(new), account_id),
)
revoke_sessions(conn, account_id, keep=session_id)
audit(conn, account_id, None, "password_changed", "account", account_id)
def login_blocked(conn, bucket: str, *, limit: int = 8, minutes: int = 10) -> bool:
row = conn.execute(
"""
SELECT count(*) AS n FROM auth_login_attempts
WHERE bucket = %s AND attempted_at > now() - make_interval(mins => %s)
""",
(bucket, minutes),
).fetchone()
return row["n"] >= limit
def record_failed_login(conn, bucket: str) -> None:
"""Committed at once: the failed request rolls back, the count must survive."""
conn.execute("DELETE FROM auth_login_attempts WHERE attempted_at < now() - interval '1 day'")
conn.execute("INSERT INTO auth_login_attempts (bucket) VALUES (%s)", (bucket,))
conn.commit()
def clear_login_attempts(conn, bucket: str) -> None:
conn.execute("DELETE FROM auth_login_attempts WHERE bucket = %s", (bucket,))
def _owned_shared_rooms(conn, account_id: UUID) -> int:
row = conn.execute(
"""
SELECT count(*) AS n FROM data_rooms r
WHERE r.kind = 'organization' AND r.status = 'active' AND r.owner_id = %s
AND EXISTS (
SELECT 1 FROM room_memberships m
WHERE m.room_id = r.id AND m.status = 'active' AND m.subject_id <> %s
)
""",
(account_id, account_id),
).fetchone()
return int(row["n"])
def list_rooms(conn, account_id: UUID) -> list[dict]:
personal = conn.execute(
"SELECT id, kind, name FROM data_rooms WHERE id = %s AND kind = 'personal'",
@@ -75,7 +304,8 @@ def list_rooms(conn, account_id: UUID) -> list[dict]:
rooms.append({"id": str(personal["id"]), "kind": personal["kind"], "name": personal["name"], "role": "owner"})
shared = conn.execute(
"""
SELECT r.id, r.kind, r.name, m.role
SELECT r.id, r.kind, r.name, m.role, r.owner_id, r.default_visibility,
(SELECT count(*) FROM room_memberships x WHERE x.room_id = r.id AND x.status = 'active') AS members
FROM room_memberships m
JOIN data_rooms r ON r.id = m.room_id
WHERE m.subject_id = %s AND m.status = 'active' AND r.status = 'active' AND r.kind = 'organization'
@@ -84,5 +314,15 @@ def list_rooms(conn, account_id: UUID) -> list[dict]:
(account_id,),
).fetchall()
for room in shared:
rooms.append({"id": str(room["id"]), "kind": room["kind"], "name": room["name"], "role": room["role"]})
rooms.append(
{
"id": str(room["id"]),
"kind": room["kind"],
"name": room["name"],
"role": room["role"],
"is_owner": room["owner_id"] == account_id,
"private": room["members"] <= 1,
"default_visibility": room["default_visibility"],
}
)
return rooms
+28
View File
@@ -5,6 +5,7 @@ from __future__ import annotations
import hashlib
import secrets
from datetime import timedelta
from functools import lru_cache
import bcrypt
from fastapi import Request, Response
@@ -27,6 +28,33 @@ def verify_password(password: str, password_hash: str) -> bool:
return False
@lru_cache
def _dummy_hash() -> str:
return hash_password("kein-konto-nur-zeitausgleich")
def verify_unknown_account(password: str) -> None:
"""Spend the same time as a real check so the answer time does not reveal an account."""
verify_password(password, _dummy_hash())
def login_bucket(host: str, email: str) -> str:
"""Rate-limit key. The address is never stored in the clear."""
return hashlib.sha256(f"{host}|{email}".encode("utf-8")).hexdigest()
_BROWSERS = (("Edg/", "Edge"), ("OPR/", "Opera"), ("Firefox/", "Firefox"), ("Chrome/", "Chrome"), ("Safari/", "Safari"))
_SYSTEMS = (("Windows", "Windows"), ("iPhone", "iPhone"), ("iPad", "iPad"), ("Android", "Android"), ("Mac OS", "macOS"), ("Linux", "Linux"))
def device_label(user_agent: str | None) -> str:
"""A short, readable hint for the session list. The full user agent is not kept."""
agent = user_agent or ""
browser = next((name for marker, name in _BROWSERS if marker in agent), "Browser")
system = next((name for marker, name in _SYSTEMS if marker in agent), "")
return f"{browser} auf {system}" if system else browser
def new_secret() -> str:
return secrets.token_urlsafe(32)
+25
View File
@@ -33,6 +33,9 @@ def forbidden(detail: str = "Diese Aktion ist im gewählten Kontext nicht erlaub
return Problem(403, "Keine Berechtigung", detail, "forbidden")
DOWNLOAD_REFUSED = "Das Herunterladen ist für dich in diesem Datenraum nicht freigegeben. Du kannst das Dokument in Tsumugu lesen."
def not_found() -> Problem:
return Problem(404, "Nicht gefunden", "Der Eintrag ist nicht vorhanden.", "not_found")
@@ -50,6 +53,28 @@ 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 scope_changed() -> Problem:
return Problem(
403,
"Datenraum gewechselt",
"Der gewählte Datenraum entspricht nicht mehr der Sitzung. Die Ansicht wird neu geladen.",
"scope_changed",
)
def password_change_required() -> Problem:
return Problem(
403,
"Passwortwechsel erforderlich",
"Bitte lege zuerst ein eigenes Passwort fest.",
"password_change_required",
)
def too_many() -> Problem:
return Problem(429, "Zu viele Versuche", "Bitte kurz warten und es erneut versuchen.", "too_many_requests")
+281 -65
View File
@@ -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, 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
CHANNELS = {"email": "per E-Mail", "post": "per Post", "other": "sonstiger Weg"}
@@ -210,11 +211,36 @@ def record_dispatch(
raise unprocessable("Dieselbe Anlage ist mehrfach im Versand genannt.")
container_row, page, scope = open_container(conn, actor, context, placement, "edit")
host = _bound_element(conn, actor, host_id, page, scope)
bump_version(conn, "elements", host_id, expected)
known = {row["attachment_element_id"] for row in _uses(conn, scope, host_id)}
if any(item not in known for item in attachment_ids):
raise unprocessable("Mitversendet werden nur Anlagen dieses Schreibens.")
counterpart_text = _counterpart(counterpart)
edition_plans = []
if capture_editions:
edition_plans.append(_plan_edition(conn, actor, host, "host", 0, page, historical_gap, media_root, cleanup))
ordered = [row for row in _uses(conn, scope, host_id) if row["attachment_element_id"] in set(attachment_ids)]
position_of = {item: index for index, item in enumerate(attachment_ids)}
ordered.sort(key=lambda row: position_of[row["attachment_element_id"]])
for index, row in enumerate(ordered, start=1):
element = _readable(conn, actor, row["attachment_element_id"], page)
if element is None:
raise not_found()
edition_plans.append(
_plan_edition(conn, actor, element, "attachment", index, page, historical_gap, media_root, cleanup)
)
evidence_plans = []
for item in evidence:
element = _readable(conn, actor, item["element_id"], page)
if element is None:
raise not_found()
evidence_plans.append(
_plan_evidence(
conn, actor, element, item["role"], item.get("fold") or "keep", page, media_root, cleanup, container_row["home_scope_id"]
)
)
container_row, page, scope = open_container(conn, actor, context, placement, "edit")
host = _bound_element(conn, actor, host_id, page, scope)
bump_version(conn, "elements", host_id, expected)
dispatch = conn.execute(
"""
INSERT INTO dispatches (
@@ -236,37 +262,11 @@ def record_dispatch(
actor,
),
).fetchone()
states = []
if capture_editions:
states.append(_capture_item(conn, actor, dispatch, host, "host", 0, page, historical_gap, media_root, cleanup))
ordered = [row for row in _uses(conn, scope, host_id) if row["attachment_element_id"] in set(attachment_ids)]
position_of = {item: index for index, item in enumerate(attachment_ids)}
ordered.sort(key=lambda row: position_of[row["attachment_element_id"]])
for index, row in enumerate(ordered, start=1):
element = _readable(conn, actor, row["attachment_element_id"], page)
if element is None:
raise not_found()
states.append(
_capture_item(conn, actor, dispatch, element, "attachment", index, page, historical_gap, media_root, cleanup)
)
evidence_rows = []
for item in evidence:
evidence_rows.append(
_add_evidence(
conn,
actor,
container_row,
page,
scope,
dispatch,
item["element_id"],
item["role"],
item.get("fold") or "keep",
media_root,
cleanup,
log=False,
)
)
states = [_write_edition(conn, dispatch, plan) for plan in edition_plans]
evidence_rows = [
_write_evidence(conn, actor, container_row, page, scope, dispatch, plan, log=False)
for plan in evidence_plans
]
completeness = _completeness(states) if capture_editions else "secured"
conn.execute(
"UPDATE dispatches SET completeness = %s, updated_at = now() WHERE id = %s",
@@ -291,11 +291,16 @@ def add_dispatch_evidence(
) -> dict:
container_row, page, scope = open_container(conn, actor, context, placement, "edit")
dispatch = _dispatch_in(conn, dispatch_id, scope)
_bump_dispatch(conn, dispatch_id, expected)
row = _add_evidence(
conn, actor, container_row, page, scope, dispatch, element_id, role, fold, media_root, cleanup, log=True
element = _readable(conn, actor, element_id, page)
if element is None:
raise not_found()
plan = _plan_evidence(
conn, actor, element, role, fold, page, media_root, cleanup, container_row["home_scope_id"], dispatch_id
)
return row
container_row, page, scope = open_container(conn, actor, context, placement, "edit")
dispatch = _dispatch_in(conn, dispatch_id, scope)
_bump_dispatch(conn, dispatch_id, expected)
return _write_evidence(conn, actor, container_row, page, scope, dispatch, plan, log=True)
def detach_dispatch_evidence(
@@ -415,9 +420,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 +594,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 +617,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(
"""
@@ -743,7 +764,7 @@ def _identify_evidence(conn, actor, dispatch, element, page, media_root, cleanup
if isinstance(loaded, RetrievalFailure):
return False, loaded.message, None, None, [], None
if isinstance(loaded, MailPayload):
comparisons = _compare_mail(conn, actor, dispatch["id"], page, loaded)
comparisons = _compare_mail(conn, actor, dispatch["id"], page, loaded) if dispatch is not None else []
payload = FilePayload("nachweis.eml", "message/rfc822", loaded.raw, sha256(loaded.raw))
return True, None, loaded.parsed.message_id or None, payload.sha256, comparisons, payload
payload = FilePayload(loaded.filename, loaded.media_type, loaded.data, sha256(loaded.data))
@@ -914,22 +935,191 @@ def _working_bytes(conn, actor, element, media_root: str):
return None, "Für diesen Inhalt ist keine sicherbare Fassung vorgesehen.", None, None, None
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:
def _stage_snapshot(conn, media_root: str, data: bytes, cleanup: list) -> dict:
"""Publish bytes only while the domain transaction is idle. The row comes later."""
from app.sourceaccess import release_for_external
instance = instance_for_write(conn, media_root)
snapshot_id = uuid4()
path = _snapshot_path(media_root, snapshot_id)
write_bytes(path, payload.data)
cleanup.append(path)
digest = sha256(payload.data)
object_key = f"dispatch/{snapshot_id}"
adapter = adapter_for(instance)
release_for_external(conn)
publish(adapter, object_key, data)
cleanup.append(StoredHandle(adapter, object_key))
return {
"id": snapshot_id,
"instance": instance,
"object_key": object_key,
"content_revision": str(uuid4()),
}
def _plan_edition(conn, actor, element, role, position, page, historical_gap, media_root, cleanup) -> dict:
dates = _dates(conn, element["id"])
payload = None
gap_reason = None
note_document = None
external_source = None
external_id = None
if historical_gap:
state = "gap"
gap_reason = _HISTORICAL_GAP
else:
payload, gap_reason, note_document, external_source, external_id = _working_bytes(
conn, actor, element, media_root
)
state = "snapshot" if payload is not None else "gap"
staged = _stage_snapshot(conn, media_root, payload.data, cleanup) if payload is not None else None
return {
"element": element,
"role": role,
"position": position,
"dates": dates,
"state": state,
"payload": payload,
"gap_reason": gap_reason,
"note_document": note_document,
"external_source": external_source,
"external_id": external_id,
"staged": staged,
}
def _write_edition(conn, dispatch, plan: dict) -> str:
payload = plan["payload"]
filename = payload.filename if payload is not None else None
content_type = payload.media_type if payload is not None else None
digest = sha256(payload.data) if payload is not None else None
byte_size = len(payload.data) if payload is not None else None
item = conn.execute(
"""
INSERT INTO dispatch_items (
dispatch_id, role, position, element_id, title, document_on, filename,
content_type, byte_size, content_sha256, source_state, gap_reason,
note_document, external_source, external_id
)
VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
RETURNING id
""",
(
dispatch["id"],
plan["role"],
plan["position"],
plan["element"]["id"],
plan["element"]["title"],
plan["dates"]["document_on"],
filename,
content_type,
byte_size,
digest,
plan["state"],
plan["gap_reason"],
Json(plan["note_document"]) if plan["note_document"] is not None else None,
plan["external_source"],
plan["external_id"],
),
).fetchone()
if plan["staged"] is not None and payload is not None:
_record_snapshot(conn, dispatch["home_scope_id"], dispatch["recorded_by"], payload, plan["staged"], dispatch_item_id=item["id"])
return plan["state"]
def _plan_evidence(conn, actor, element, role, fold, page, media_root, cleanup, scope_id, dispatch_id=None) -> dict:
if role not in EVIDENCE_ROLES:
raise unprocessable("Die Rolle des Nachweises ist nicht vorgesehen.")
if fold not in {"keep", "evidence"}:
raise unprocessable("Die Darstellung des Nachweises ist nicht festgelegt.")
if dispatch_id is not None and conn.execute(
"SELECT id FROM dispatch_evidence WHERE dispatch_id = %s AND element_id = %s",
(dispatch_id, element["id"]),
).fetchone():
raise unprocessable("Dieser Nachweis ist dem Versand bereits zugeordnet.")
dispatch = {"id": dispatch_id} if dispatch_id is not None else None
identified, gap_reason, message_id, digest, comparisons, snapshot = _identify_evidence(
conn, actor, dispatch, element, page, media_root, cleanup, scope_id
)
staged = _stage_snapshot(conn, media_root, snapshot.data, cleanup) if snapshot is not None else None
return {
"element": element,
"role": role,
"fold": fold,
"identified": identified,
"gap_reason": gap_reason,
"message_id": message_id,
"digest": digest,
"comparisons": comparisons,
"snapshot": snapshot,
"staged": staged,
}
def _write_evidence(conn, actor, container_row, page, scope, dispatch, plan: dict, log: bool) -> dict:
snapshot = plan["snapshot"]
comparisons = plan["comparisons"]
if snapshot is not None and snapshot.media_type == "message/rfc822":
from app.mailpack import parse_mail
comparisons = _compare_mail(conn, actor, dispatch["id"], page, MailPayload(snapshot.data, parse_mail(snapshot.data)))
proof = conn.execute(
"""
INSERT INTO dispatch_evidence (
dispatch_id, element_id, role, source_state, gap_reason, message_id,
identity_sha256, comparisons, manual, created_by
)
VALUES (%s, %s, %s, %s, %s, %s, %s, %s, true, %s)
RETURNING *
""",
(
dispatch["id"],
plan["element"]["id"],
plan["role"],
"identified" if plan["identified"] else "gap",
plan["gap_reason"],
plan["message_id"],
plan["digest"],
Json(comparisons),
actor,
),
).fetchone()
if plan["staged"] is not None and snapshot is not None:
_record_snapshot(
conn,
container_row["home_scope_id"],
actor,
snapshot,
plan["staged"],
evidence_id=proof["id"],
)
if plan["fold"] == "evidence":
_set_binding_fold(conn, scope, plan["element"]["id"], "evidence")
if log:
_log(conn, dispatch["id"], actor, f"Nachweis ergänzt: {EVIDENCE_ROLES[plan['role']]}")
audit(conn, actor, container_row["home_scope_id"], "dispatch_evidence", "element", plan["element"]["id"], page)
return {
"id": str(proof["id"]),
"element_id": str(plan["element"]["id"]),
"role": plan["role"],
"role_label": EVIDENCE_ROLES[plan["role"]],
"source_state": proof["source_state"],
"gap_reason": plan["gap_reason"],
"manual": True,
"comparisons": comparisons,
}
def _record_snapshot(conn, scope_id, actor, payload: FilePayload, staged: dict, dispatch_item_id=None, evidence_id=None) -> UUID:
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,
staged["id"],
dispatch_item_id,
evidence_id,
scope_id,
@@ -937,10 +1127,20 @@ def _store_snapshot(conn, scope_id, actor, payload: FilePayload, media_root: str
display_filename(payload.filename),
payload.media_type or "application/octet-stream",
len(payload.data),
digest,
sha256(payload.data),
staged["instance"]["id"],
staged["instance"]["generation"],
staged["object_key"],
staged["content_revision"],
LEGACY_PROFILE,
),
)
return snapshot_id
return staged["id"]
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:
staged = _stage_snapshot(conn, media_root, payload.data, cleanup)
return _record_snapshot(conn, scope_id, actor, payload, staged, dispatch_item_id, evidence_id)
def _snapshot_file(conn, media_root: str, dispatch_item_id: UUID | None = None, evidence_id: UUID | None = None) -> FilePayload:
@@ -956,20 +1156,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 removal_for(conn, None, "legacy-local-1", f"dispatch/{snapshot_id}", media_root)
return removal_for(
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 +1632,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
+17
View File
@@ -49,9 +49,26 @@ 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
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)
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)
+44 -10
View File
@@ -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]:
@@ -492,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)
@@ -691,9 +695,18 @@ def _emit_one(node, prefix, add, entries, loaded, notice_for, generated: str) ->
links = [("EML-Original", eml)]
try:
parsed = payload.parsed if isinstance(payload, MailPayload) else parse_mail(raw)
reading = _mail_reading_html(parsed)
if reading is not None:
reading_path = add(prefix + ["lesefassung.html"], reading)
links.append(("Formatierte Lesefassung", reading_path))
else:
notice = "\n".join(part for part in [notice, "Eine formatierte Lesefassung liegt für diese Nachricht nicht vor. Die vereinfachte Textfassung steht in der Übersicht."] if part)
for attachment in parsed.attachments:
label = attachment.display_name or attachment.filename
path = add(prefix + ["anlagen", attachment.filename], attachment.data)
links.append((attachment.filename, path))
links.append((label, path))
if parsed.notices:
notice = "\n".join(part for part in [notice, *parsed.notices] if part)
except Exception:
links.append(("Hinweis", eml))
entries.append(_entry(node, eml, links, notice or None))
@@ -1219,6 +1232,21 @@ def _note_markdown(node: ExportNode, body: str, generated: str) -> str:
return "\n".join(lines)
def _mail_reading_html(parsed) -> bytes | None:
if not getattr(parsed, "html", ""):
return None
page = (
"<!DOCTYPE html><html lang=\"de\"><head><meta charset=\"utf-8\">"
"<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'; img-src data:; style-src 'none'; script-src 'none'\">"
"<title>Lesefassung</title></head><body>"
f"{parsed.html}"
"<p>Vereinfachte Textfassung und das unveränderte EML-Original stehen daneben. "
"Die Ansicht ist nicht pixelgleich zur Postfachdarstellung.</p>"
"</body></html>"
)
return page.encode("utf-8")
def _mail_markdown(node, mail: MailPayload, text_path: str, eml_path: str, attachments, notice: str, generated: str) -> str:
parsed = mail.parsed
lines = [f"# {node.title}", "", "Lesefassung. Das unveränderte Original ist die EML-Datei.", ""]
@@ -1230,7 +1258,13 @@ def _mail_markdown(node, mail: MailPayload, text_path: str, eml_path: str, attac
if parsed.copy:
lines.append(f"- Kopie: {parsed.copy}")
lines.append(f"- [EML-Original]({_href(_relative(text_path, eml_path))})")
lines.extend(["", parsed.text or "Der Text steht im EML-Original.", ""])
lines.extend([
"",
"Vereinfachte Textfassung. Sie ist nicht die formatierte Ansicht und nicht das EML-Original.",
"",
parsed.text or "Der Text steht im EML-Original.",
"",
])
if attachments:
lines.append("## Anlagen")
lines.append("")
+170
View File
@@ -0,0 +1,170 @@
"""Overviews for the library: cases and matters as tiles, and what lies in a room.
A room is a virtual folder. Cases and matters stay where they are; a share puts them into a room.
Counts only include what the person may read. Hidden entries are neither named nor counted.
"""
from __future__ import annotations
from collections import Counter
from uuid import UUID
from app.access.policy import (
ROOM_RIGHTS,
Ctx,
Rights,
case_rights,
get_case,
list_cases,
list_matters,
matter_rights,
room_name,
)
from app.present import _chapters, _matter_tree, case_summary, matter_summary
def shared_rooms(conn, kind: str, resource_id: UUID) -> list[dict]:
rows = conn.execute(
"""
SELECT r.id, r.name, s.access FROM room_shares s JOIN data_rooms r ON r.id = s.room_id
WHERE s.resource_kind = %s AND s.resource_id = %s
ORDER BY r.name, r.id
""",
(kind, resource_id),
).fetchall()
return [{"id": str(row["id"]), "name": row["name"], "access": row["access"]} for row in rows]
def readable_matter_count(conn, actor: UUID, case: dict) -> int:
rows = conn.execute(
"""
SELECT m.* FROM matter_case_links l JOIN matters m ON m.id = l.matter_id
WHERE l.case_id = %s AND m.deleted_at IS NULL AND m.parent_matter_id IS NULL
""",
(case["id"],),
).fetchall()
context = Ctx("case", case["id"])
return sum(1 for matter in rows if matter_rights(conn, actor, matter, context).read)
def case_items(conn, actor: UUID, visible: list[tuple[dict, Rights]]) -> list[dict]:
children = Counter(case["parent_case_id"] for case, _ in visible if case["parent_case_id"])
items = []
for case, rights in visible:
summary = case_summary(case, rights)
owner = case["owner_subject_id"] == actor
summary["home_scope_name"] = room_name(conn, case["home_scope_id"])
summary["kind_label"] = "Unterakte" if case["parent_case_id"] else "Akte"
summary["parent_title"] = None
summary["is_owner"] = owner
summary["shared_with"] = shared_rooms(conn, "case", case["id"]) if owner else []
summary["child_cases"] = children.get(case["id"], 0)
summary["matter_count"] = readable_matter_count(conn, actor, case)
if case["parent_case_id"]:
parent = get_case(conn, case["parent_case_id"])
if parent is not None and case_rights(conn, actor, parent).read:
summary["parent_title"] = parent["title"]
items.append(summary)
return items
def matter_items(conn, actor: UUID, visible: list[tuple[dict, list[dict]]]) -> list[dict]:
children = Counter(matter["parent_matter_id"] for matter, _ in visible if matter["parent_matter_id"])
items = []
for matter, _contexts in visible:
summary = matter_summary(conn, actor, matter)
summary["child_matters"] = children.get(matter["id"], 0)
items.append(summary)
return items
def room_contents(conn, actor: UUID, room_id: UUID) -> tuple[list[tuple[dict, Rights]], list[tuple[dict, list[dict]]]]:
"""Cases and matters shared with the room that the person may read, with their readable sub-entries."""
rows = conn.execute(
"SELECT resource_kind, resource_id FROM room_shares WHERE room_id = %s",
(room_id,),
).fetchall()
case_ids = {row["resource_id"] for row in rows if row["resource_kind"] == "case"}
matter_ids = {row["resource_id"] for row in rows if row["resource_kind"] == "matter"}
cases = [
(case, rights)
for case, rights in list_cases(conn, actor)
if case["id"] in case_ids
or (case["rights_mode"] == "inherit_parent" and case["parent_case_id"] in case_ids)
]
matters = [
(matter, contexts)
for matter, contexts in list_matters(conn, actor)
if matter["id"] in matter_ids or matter["parent_matter_id"] in matter_ids
]
return cases, matters
def room_effect(conn, room_id: UUID, actor: UUID, access: str) -> list[dict]:
"""Who gets which rights through a share with this room."""
rows = conn.execute(
"""
SELECT m.subject_id, m.role, a.display_name
FROM room_memberships m JOIN auth_accounts a ON a.id = m.subject_id
WHERE m.room_id = %s AND m.status = 'active' AND a.status = 'active' AND m.subject_id <> %s
ORDER BY a.display_name, a.id
""",
(room_id, actor),
).fetchall()
effect = []
for row in rows:
rights = ROOM_RIGHTS.get(row["role"], Rights())
if access == "read":
rights = Rights(read=rights.read)
effect.append(
{
"display_name": row["display_name"],
"role": row["role"],
"rights": {"read": rights.read, "edit": rights.edit},
}
)
return effect
def case_outline(conn, actor: UUID, case: dict) -> dict:
"""What the navigation tree shows below a case. Only readable entries; no bindings or texts."""
chapters = _chapters(conn, "case", case["id"], case.get("content_order") or "position", case.get("content_order_dir") or "asc")
subcases = []
for row in conn.execute(
"SELECT * FROM cases WHERE parent_case_id = %s AND deleted_at IS NULL ORDER BY title, id",
(case["id"],),
).fetchall():
if case_rights(conn, actor, row).read:
subcases.append({"id": str(row["id"]), "title": row["title"], "status": row["record_status"]})
linked = []
for link in conn.execute(
"""
SELECT m.* FROM matter_case_links l JOIN matters m ON m.id = l.matter_id
WHERE l.case_id = %s AND m.deleted_at IS NULL ORDER BY m.title, m.id
""",
(case["id"],),
).fetchall():
if matter_rights(conn, actor, link, Ctx("case", case["id"])).read:
linked.append(link)
return {
"kind": "case",
"id": str(case["id"]),
"chapters": chapters,
"subcases": subcases,
"matters": _matter_tree(conn, actor, case["id"], linked),
}
def matter_outline(conn, actor: UUID, matter: dict, context: Ctx | None) -> dict:
"""What the navigation tree shows below a matter: its chapters and its readable Teilvorgänge."""
chapters = _chapters(
conn, "matter", matter["id"], matter.get("content_order") or "position", matter.get("content_order_dir") or "asc"
)
children = []
for row in conn.execute(
"SELECT * FROM matters WHERE parent_matter_id = %s AND deleted_at IS NULL ORDER BY title, id",
(matter["id"],),
).fetchall():
if matter_rights(conn, actor, row, context).read:
children.append({"id": str(row["id"]), "title": row["title"], "status": row["record_status"]})
return {"kind": "matter", "id": str(matter["id"]), "chapters": chapters, "submatters": children}
+409 -66
View File
@@ -1,16 +1,46 @@
"""Pure mail identity and attachment extraction for a complete export.
A preview cutoff does not belong here. Duplicate attachment names stay distinct.
The same tree feeds preview, reading, attachment download and export.
"""
from __future__ import annotations
import base64
import hashlib
import html
import re
from dataclasses import dataclass, field
from email import policy
from email.header import decode_header, make_header
from email.message import EmailMessage
from email.parser import BytesParser
from email.utils import parsedate_to_datetime
from html.parser import HTMLParser
_UID_PREFIX = "uid:"
_POLICY = policy.default
_ALLOWED_TAGS = {
"a", "p", "br", "div", "span", "strong", "em", "b", "i", "u",
"ul", "ol", "li", "table", "thead", "tbody", "tr", "th", "td",
"blockquote", "pre", "code", "h1", "h2", "h3", "h4", "h5", "h6", "img",
"font", "center", "hr", "small", "sub", "sup", "s", "strike", "caption", "tfoot", "section", "article",
}
_VOID_TAGS = {"br", "img", "hr"}
# Formatting a mail may keep. Nothing here loads anything, positions an element or runs code.
_STYLE_PROPS = {
"color", "background-color", "font-family", "font-size", "font-weight", "font-style", "text-align",
"text-decoration", "line-height", "vertical-align", "white-space", "letter-spacing",
"margin", "margin-top", "margin-bottom", "margin-left", "margin-right",
"padding", "padding-top", "padding-bottom", "padding-left", "padding-right",
"border", "border-top", "border-bottom", "border-left", "border-right", "border-color", "border-width",
"border-style", "border-collapse", "width", "max-width", "height", "text-indent", "list-style-type",
}
_STYLE_VALUE = re.compile(r"^[#%a-z0-9 .,()\-+'\"]{1,100}$", re.IGNORECASE)
_STYLE_DENIED = re.compile(r"url|expression|var\(|attr\(|image|@|javascript|behavior|\\", re.IGNORECASE)
_COLOR = re.compile(r"^(#[0-9a-f]{3,8}|[a-z]{3,20}|rgb\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*\))$", re.IGNORECASE)
_SAFE_LINK = re.compile(r"^(https?://|mailto:)", re.IGNORECASE)
_DATA_IMAGE = re.compile(r"^data:image/(?:png|jpeg|gif|webp);base64,[a-z0-9+/=\s]+$", re.IGNORECASE)
class MailIdentityError(Exception):
@@ -25,6 +55,9 @@ class AttachmentBytes:
media_type: str
data: bytes
sha256: str
display_name: str = ""
content_id: str = ""
inline: bool = False
@dataclass
@@ -37,10 +70,16 @@ class ParsedMail:
text: str
attachments: list[AttachmentBytes] = field(default_factory=list)
missing: list[str] = field(default_factory=list)
html: str = ""
html_source: str = ""
remote_images: list[str] = field(default_factory=list)
notices: list[str] = field(default_factory=list)
text_truncated: bool = False
document_on: str | None = None
def header_message_id(raw: bytes) -> str:
message = BytesParser().parsebytes(raw)
message = BytesParser(policy=_POLICY).parsebytes(raw)
return str(message.get("Message-ID") or "").strip()
@@ -69,67 +108,404 @@ def choose_message(candidate: bytes | None, alternates: list[bytes], expected: s
raise MailIdentityError("Die gespeicherte Nachricht lässt sich nicht eindeutig wiederfinden.")
def header_text(value) -> str:
"""Decode encoded-words. A raw MIME header is not a display name."""
if value is None:
return ""
raw = str(value).replace("\r", " ").replace("\n", " ")
try:
text = str(make_header(decode_header(raw)))
except (UnicodeError, LookupError, ValueError):
text = raw
return re.sub(r"\s+", " ", text).strip()
def parse_mail(raw: bytes) -> ParsedMail:
message = BytesParser().parsebytes(raw)
message = BytesParser(policy=_POLICY).parsebytes(raw)
attachments: list[AttachmentBytes] = []
missing: list[str] = []
notices: list[str] = []
used: set[str] = set()
plain: list[str] = []
html_parts: list[str] = []
index = 0
for part in message.walk():
if part.is_multipart():
for kind, part in _walk(message):
if kind == "message":
index += 1
label = header_text(part.get_filename()) or f"nachricht-{index}.eml"
data = _message_bytes(part)
if data is None:
missing.append(label)
notices.append(f"Die angehängte Nachricht {label} ließ sich nicht vollständig lesen.")
continue
name = _unique_filename(label, used)
attachments.append(_attachment(part, name, label, data, inline=False))
continue
filename = part.get_filename()
disposition = (part.get_content_disposition() or "").lower()
if not filename and disposition != "attachment":
media = part.get_content_type()
filename = part.get_filename()
content_id = _content_id(part)
body = media in {"text/plain", "text/html"} and disposition != "attachment" and not filename
if body:
text = _decoded_text(part)
if text is None:
notices.append("Ein Textteil ließ sich nicht sicher dekodieren.")
continue
if media == "text/plain":
plain.append(text)
else:
html_parts.append(text)
continue
if not filename and disposition != "attachment" and not content_id:
continue
index += 1
label = _header_text(filename) if filename else f"anlage-{index}.bin"
payload = part.get_payload(decode=True)
if not isinstance(payload, (bytes, bytearray)):
label = header_text(filename) if filename else f"anlage-{index}.bin"
data = _leaf_bytes(part)
if data is None:
missing.append(label or f"Anlage {index}")
notices.append(f"Die Anlage {label or index} ließ sich nicht vollständig lesen.")
continue
data = _unwrap_pdf_payload(data, media, label)
if _is_pdf(data):
media = "application/pdf"
label = _pdf_filename(label)
name = _unique_filename(label or f"anlage-{index}.bin", used)
data = bytes(payload)
attachments.append(
AttachmentBytes(
filename=name,
media_type=(part.get_content_type() or "application/octet-stream")[:120],
data=data,
sha256=hashlib.sha256(data).hexdigest(),
)
)
text = _body_text(message)
inline = disposition == "inline" or bool(content_id)
attachments.append(_attachment(part, name, label or name, data, inline=inline, media=media))
simplified = "\n".join(chunk for chunk in plain if chunk).strip()
rendered = ""
if html_parts:
source = "\n".join(html_parts)
remote_found: list[str] = []
rendered = sanitize_html(source, _inline_images(attachments), found=remote_found)
if not simplified:
simplified = simplified_text("\n".join(html_parts))
if missing:
notices.append("Mindestens eine Anlage fehlt in der Aufbereitung.")
return ParsedMail(
message_id=str(message.get("Message-ID") or "").strip(),
subject=_header_text(message.get("Subject")) or "(ohne Betreff)",
sender=_header_text(message.get("From")),
recipient=_header_text(message.get("To")),
copy=_header_text(message.get("Cc")),
text=text,
subject=header_text(message.get("Subject")) or "(ohne Betreff)",
sender=header_text(message.get("From")),
recipient=header_text(message.get("To")),
copy=header_text(message.get("Cc")),
text=simplified,
attachments=attachments,
missing=missing,
html=rendered,
html_source=source if html_parts else "",
remote_images=remote_found if html_parts else [],
notices=notices,
document_on=_message_date(message.get("Date")),
)
def decode_transfer(payload: bytes, charset: str | None) -> str:
return bytes(payload).decode(charset or "utf-8", errors="replace")
def simplified_text(value: str) -> str:
"""A recognizable plain reading. It is not the formatted view."""
class Collector(HTMLParser):
def __init__(self) -> None:
super().__init__(convert_charrefs=True)
self.parts: list[str] = []
self.skip = 0
def handle_starttag(self, tag, attrs):
name = tag.lower()
if name in {"script", "style"}:
self.skip += 1
return
if name in {"br", "p", "div", "tr", "li", "h1", "h2", "h3", "h4", "h5", "h6", "blockquote"}:
self.parts.append("\n")
elif name in {"td", "th"}:
self.parts.append("\t")
def handle_endtag(self, tag):
name = tag.lower()
if name in {"script", "style"} and self.skip:
self.skip -= 1
return
if name in {"p", "div", "tr", "li", "table", "h1", "h2", "h3", "h4", "h5", "h6"}:
self.parts.append("\n")
def handle_data(self, data):
if not self.skip:
self.parts.append(data)
collector = Collector()
try:
collector.feed(value)
collector.close()
except Exception:
return ""
text = "".join(collector.parts)
text = text.replace("\r", "")
text = re.sub(r"[ \t]+\n", "\n", text)
text = re.sub(r"\n{3,}", "\n\n", text)
return text.strip()
def sanitize_html(value: str, images: dict[str, str] | None = None, *, remote=None, found: list[str] | None = None) -> str:
"""Keep a formatted reading. Scripts and active content stay out.
Pictures from other servers stay out too, unless `remote` turns an address into an inline picture.
`found` collects the addresses that were met."""
images = images or {}
class Cleaner(HTMLParser):
def __init__(self) -> None:
super().__init__(convert_charrefs=True)
self.parts: list[str] = []
self.skip = 0
def handle_starttag(self, tag, attrs):
name = tag.lower()
if name in {"script", "style", "iframe", "object", "embed", "form", "link", "meta"}:
self.skip += 1
return
if self.skip or name not in _ALLOWED_TAGS:
return
rendered = _clean_attrs(name, attrs, images, remote, found)
if rendered is None:
return
self.parts.append(f"<{name}{rendered}>")
def handle_endtag(self, tag):
name = tag.lower()
if name in {"script", "style", "iframe", "object", "embed", "form", "link", "meta"}:
if self.skip:
self.skip -= 1
return
if self.skip or name not in _ALLOWED_TAGS or name in _VOID_TAGS:
return
self.parts.append(f"</{name}>")
def handle_data(self, data):
if not self.skip:
self.parts.append(html.escape(data))
def handle_entityref(self, name):
if not self.skip:
self.parts.append(f"&{name};")
def handle_charref(self, name):
if not self.skip:
self.parts.append(f"&#{name};")
cleaner = Cleaner()
try:
cleaner.feed(value)
cleaner.close()
except Exception:
return ""
return "".join(cleaner.parts).strip()
def _safe_style(value: str) -> str:
kept = []
for declaration in (value or "").split(";"):
prop, _, raw = declaration.partition(":")
prop, raw = prop.strip().lower(), raw.strip().replace("!important", "").strip()
if prop not in _STYLE_PROPS or not raw or _STYLE_DENIED.search(raw) or not _STYLE_VALUE.match(raw):
continue
kept.append(f"{prop}: {raw}")
return "; ".join(kept)
def _clean_attrs(tag: str, attrs, images: dict[str, str], remote=None, found: list[str] | None = None) -> str | None:
kept: list[str] = []
for key, value in attrs:
name = (key or "").lower()
if name.startswith("on") or name == "srcset":
continue
if name == "style":
style = _safe_style(value or "")
if style:
kept.append(f' style="{html.escape(style, quote=True)}"')
continue
if name in {"bgcolor", "color"} and _COLOR.match((value or "").strip()):
kept.append(f' {name}="{html.escape(value.strip(), quote=True)}"')
continue
if name in {"width", "height"} and re.fullmatch(r"\d{1,4}%?", (value or "").strip()):
kept.append(f' {name}="{value.strip()}"')
continue
if name in {"border", "cellpadding", "cellspacing", "size"} and str(value or "").strip().isdigit():
kept.append(f' {name}="{int(value)}"')
continue
if name in {"align", "valign"} and (value or "").strip().lower() in {"left", "right", "center", "justify", "top", "middle", "bottom"}:
kept.append(f' {name}="{value.strip().lower()}"')
continue
if tag == "a" and name == "href":
target = (value or "").strip()
if not _SAFE_LINK.match(target):
continue
kept.append(f' href="{html.escape(target, quote=True)}" title="{html.escape(target, quote=True)}"')
elif tag == "img" and name == "src":
source = (value or "").strip()
if source.lower().startswith("cid:"):
token = source[4:].strip().strip("<>")
source = images.get(token.casefold(), "")
elif re.match(r"https://", source, re.IGNORECASE):
if found is not None and source not in found:
found.append(source)
source = remote(source) if remote is not None else ""
if not _DATA_IMAGE.match(source):
continue
kept.append(f' src="{source}"')
elif tag == "img" and name == "alt":
kept.append(f' alt="{html.escape(value or "", quote=True)}"')
elif name in {"colspan", "rowspan"} and str(value or "").isdigit():
kept.append(f" {name}=\"{int(value)}\"")
if tag == "img" and not any(item.startswith(" src=") for item in kept):
return None
if tag == "a":
kept.append(' rel="noreferrer noopener" target="_blank"')
return "".join(kept)
def _walk(message: EmailMessage):
if message.get_content_maintype() == "message" and message.get_content_subtype() == "rfc822":
yield "message", message
return
if message.is_multipart():
for child in message.iter_parts():
yield from _walk(child)
return
yield "leaf", message
def _decoded_text(part: EmailMessage) -> str | None:
try:
payload = part.get_payload(decode=True)
except Exception:
return None
if not isinstance(payload, (bytes, bytearray)):
raw = part.get_payload()
return raw.strip() if isinstance(raw, str) else None
charset = part.get_content_charset() or "utf-8"
try:
return decode_transfer(bytes(payload), charset).strip()
except LookupError:
return decode_transfer(bytes(payload), "utf-8").strip()
def _leaf_bytes(part: EmailMessage) -> bytes | None:
try:
payload = part.get_payload(decode=True)
except Exception:
return None
if isinstance(payload, (bytes, bytearray)):
return bytes(payload)
return None
def _message_bytes(part: EmailMessage) -> bytes | None:
payload = part.get_payload()
if isinstance(payload, list) and payload:
inner = payload[0]
if isinstance(inner, EmailMessage):
return inner.as_bytes()
data = _leaf_bytes(part)
return data or None
def _content_id(part: EmailMessage) -> str:
token = str(part.get("Content-ID") or "").strip().strip("<>").strip()
return token
def _is_pdf(data: bytes) -> bool:
return data[:1024].lstrip(b"\xef\xbb\xbf\r\n\t ").startswith(b"%PDF")
def _unwrap_pdf_payload(data: bytes, media: str, name: str) -> bytes:
"""A PDF that arrived as undecoded Base64 is still the PDF, not the transfer text."""
if _is_pdf(data):
return data
declared = (media or "").split(";", 1)[0].strip().lower()
hinted = "pdf" in declared or (name or "").lower().endswith(".pdf") or declared in {
"application/octet-stream",
"application/x-octet-stream",
"binary/octet-stream",
}
if not hinted:
return data
stripped = b"".join(data.split())
if len(stripped) < 16 or re.fullmatch(rb"[A-Za-z0-9+/=]+", stripped) is None:
return data
try:
decoded = base64.b64decode(stripped, validate=True)
except Exception:
return data
return decoded if _is_pdf(decoded) else data
def _pdf_filename(name: str) -> str:
text = (name or "").strip() or "anlage"
if text.lower().endswith(".pdf"):
return text
if text.lower().endswith(".bin"):
text = text[:-4].rstrip(" .") or "anlage"
leaf = text.replace("\\", "/").split("/")[-1]
if "." in leaf:
return text
return f"{text}.pdf"
def _attachment(part: EmailMessage, filename: str, label: str, data: bytes, inline: bool, media: str | None = None) -> AttachmentBytes:
resolved = (media or part.get_content_type() or "application/octet-stream").split(";", 1)[0].strip()
return AttachmentBytes(
filename=filename,
media_type=(resolved or "application/octet-stream")[:120],
data=data,
sha256=hashlib.sha256(data).hexdigest(),
display_name=label or filename,
content_id=_content_id(part),
inline=inline,
)
def _inline_images(attachments: list[AttachmentBytes]) -> dict[str, str]:
import base64
images: dict[str, str] = {}
for item in attachments:
if not item.content_id or not item.media_type.startswith("image/"):
continue
if len(item.data) > 1_500_000:
continue
subtype = item.media_type.split("/", 1)[1].split(";", 1)[0].lower()
if subtype == "jpg":
subtype = "jpeg"
if subtype not in {"png", "jpeg", "gif", "webp"}:
continue
encoded = base64.b64encode(item.data).decode("ascii")
images[item.content_id.casefold()] = f"data:image/{subtype};base64,{encoded}"
return images
def _message_date(value) -> str | None:
if not value:
return None
try:
return parsedate_to_datetime(str(value)).date().isoformat()
except (TypeError, ValueError, OverflowError):
return None
def _bare(value: str) -> str:
return value.strip().strip("<>").strip().casefold()
def _header_text(value) -> str:
if value is None:
return ""
text = str(value).replace("\r", " ").replace("\n", " ")
return re.sub(r"\s+", " ", text).strip()
def _unique_filename(name: str, used: set[str]) -> str:
cleaned = name.replace("\\", "/").split("/")[-1].strip() or "anlage.bin"
cleaned = cleaned[:180]
cleaned = re.sub(r"[\r\n\x00]", "", cleaned)[:180] or "anlage.bin"
if cleaned not in used:
used.add(cleaned)
return cleaned
stem, dot, ext = cleaned.rpartition(".")
if not dot:
if not dot or not stem:
stem, ext = cleaned, ""
else:
ext = f".{ext}"
@@ -140,36 +516,3 @@ def _unique_filename(name: str, used: set[str]) -> str:
used.add(candidate)
return candidate
number += 1
def _body_text(message) -> str:
plain: list[str] = []
html: list[str] = []
parts = message.walk() if message.is_multipart() else [message]
for part in parts:
if part.is_multipart() or part.get_content_disposition() == "attachment" or part.get_filename():
continue
kind = part.get_content_type()
payload = part.get_payload(decode=True)
if isinstance(payload, (bytes, bytearray)):
charset = part.get_content_charset() or "utf-8"
text = bytes(payload).decode(charset, errors="replace").strip()
else:
raw = part.get_payload()
text = raw.strip() if isinstance(raw, str) else ""
if kind == "text/plain":
plain.append(text)
elif kind == "text/html":
html.append(_html_text(text))
body = "\n".join(chunk for chunk in plain if chunk).strip()
if not body:
body = "\n".join(chunk for chunk in html if chunk).strip()
return body
def _html_text(value: str) -> str:
text = re.sub(r"(?is)<(script|style)\b.*?>.*?</\1>", " ", value)
text = re.sub(r"(?i)<br\s*/?>", "\n", text)
text = re.sub(r"(?i)</p>", "\n", text)
text = re.sub(r"<[^>]+>", " ", text)
return re.sub(r"[ \t]{2,}", " ", text).strip()
+12
View File
@@ -9,8 +9,14 @@ from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from app.api.accounts import router as accounts_router
from app.api.correspondence import router as correspondence_router
from app.api.downloads import router as downloads_router
from app.api.export import router as export_router
from app.api.library import router as library_router
from app.api.rooms import router as rooms_router
from app.api.roomshare import router as roomshare_router
from app.api.team import router as team_router
from app.api.routes import router
from app.api.sources import router as sources_router
from app.core.errors import Problem, problem_response
@@ -116,8 +122,14 @@ def create_app() -> FastAPI:
)
app.include_router(router)
app.include_router(accounts_router)
app.include_router(library_router)
app.include_router(rooms_router)
app.include_router(roomshare_router)
app.include_router(team_router)
app.include_router(sources_router)
app.include_router(export_router)
app.include_router(downloads_router)
app.include_router(correspondence_router)
return app
+295
View File
@@ -0,0 +1,295 @@
"""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()
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(
"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)
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,
"Inhalt nicht geprüft",
"Die gespeicherte Datei stimmt nicht mit dem erfassten Stand überein.",
"processing",
)
return data
+15 -3
View File
@@ -4,6 +4,7 @@ from __future__ import annotations
import hashlib
from pathlib import Path
from urllib.parse import quote
from uuid import UUID
from app.core.errors import storage_unavailable, unprocessable
@@ -66,6 +67,17 @@ def display_filename(name: str) -> str:
return text[:240]
def content_disposition(filename: str) -> str:
safe = display_filename(filename).replace('"', "")
return f'attachment; filename="{safe}"'
def content_disposition(filename: str, *, inline: bool = False) -> str:
"""The real name goes along in UTF-8 (RFC 5987), with a plain ASCII fallback for old clients."""
name = display_filename(filename)
kind = "inline" if inline else "attachment"
suffix = ""
leaf = name.rsplit(".", 1)
if len(leaf) == 2 and leaf[1].isascii() and leaf[1].isalnum():
suffix = f".{leaf[1]}"
fallback = name.encode("ascii", "replace").decode("ascii").replace("?", "_").replace('"', "").replace("\\", "_").replace(";", "_")
fallback = " ".join(fallback.split())
if suffix and not fallback.lower().endswith(suffix.lower()):
fallback = f"{fallback}{suffix}".strip()
fallback = fallback or f"datei{suffix}"
return f"{kind}; filename=\"{fallback}\"; filename*=UTF-8''{quote(name, safe='')}"
+194 -15
View File
@@ -8,6 +8,7 @@ from uuid import UUID, uuid4
from psycopg.types.json import Json
from app.access.roles import ensure_can_create, room_role
from app.access.policy import (
Ctx,
Rights,
@@ -33,9 +34,10 @@ 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, StoredHandle, adapter_for, instance_for_write, publish, removal_for
from app.media.storage import display_filename, sha256, sniff
MAX_CHAPTER_DEPTH = 32
@@ -72,7 +74,135 @@ def _placement(context: Ctx, placement: Ctx | None) -> tuple[Ctx, Ctx]:
return target, context if context.kind == "case" or placement is not None else None
def default_visibility(conn, scope_id: UUID) -> str:
"""Whether new cases and matters are shared with their room at once. The personal room never is."""
room = conn.execute("SELECT kind, default_visibility FROM data_rooms WHERE id = %s", (scope_id,)).fetchone()
if room is not None and room["kind"] == "organization" and room["default_visibility"] == "room":
return "room"
return "private"
def _auto_share(conn, actor: UUID, kind: str, resource: dict) -> None:
if default_visibility(conn, resource["home_scope_id"]) == "room":
conn.execute(
"""
INSERT INTO room_shares (resource_kind, resource_id, room_id, access, created_by)
VALUES (%s, %s, %s, 'edit', %s)
ON CONFLICT DO NOTHING
""",
(kind, resource["id"], resource["home_scope_id"], actor),
)
def _shareable(conn, actor: UUID, kind: str, resource_id: UUID) -> dict:
"""The own case or matter. Only the owner decides which rooms it is shared with."""
if kind == "case":
resource = get_case(conn, resource_id)
elif kind == "matter":
resource = get_matter(conn, resource_id)
else:
raise unprocessable("Die Raumfreigabe gilt für Akten und Vorgänge.")
if resource is None or resource["owner_subject_id"] != actor:
raise not_found()
return resource
def _target_room(conn, actor: UUID, room_id: UUID) -> dict:
room = conn.execute("SELECT id, kind, status FROM data_rooms WHERE id = %s", (room_id,)).fetchone()
if room is None or room["kind"] != "organization" or room["status"] != "active":
raise not_found()
if room_role(conn, actor, room_id) not in {"member", "manager"}:
raise forbidden("Du kannst nur mit Datenräumen teilen, in denen du Mitglied oder Verwalter bist.")
return room
def share_with_room(conn, actor: UUID, kind: str, resource_id: UUID, room_id: UUID, access: str) -> dict:
if access not in {"read", "edit"}:
raise unprocessable("Die Freigabeart ist ungültig.")
resource = _shareable(conn, actor, kind, resource_id)
_target_room(conn, actor, room_id)
existing = conn.execute(
"SELECT access FROM room_shares WHERE resource_kind = %s AND resource_id = %s AND room_id = %s",
(kind, resource_id, room_id),
).fetchone()
conn.execute(
"""
INSERT INTO room_shares (resource_kind, resource_id, room_id, access, created_by)
VALUES (%s, %s, %s, %s, %s)
ON CONFLICT (resource_kind, resource_id, room_id) DO UPDATE SET access = EXCLUDED.access
""",
(kind, resource_id, room_id, access, actor),
)
if existing is None or existing["access"] != access:
audit(
conn,
actor,
resource["home_scope_id"],
"room_shared" if existing is None else "room_share_changed",
kind,
resource_id,
detail={"room_id": str(room_id), "access": access},
)
return {"room_id": str(room_id), "access": access}
def unshare_from_room(conn, actor: UUID, kind: str, resource_id: UUID, room_id: UUID) -> None:
resource = _shareable(conn, actor, kind, resource_id)
row = conn.execute(
"DELETE FROM room_shares WHERE resource_kind = %s AND resource_id = %s AND room_id = %s RETURNING id",
(kind, resource_id, room_id),
).fetchone()
if row is None:
raise not_found()
audit(conn, actor, resource["home_scope_id"], "room_unshared", kind, resource_id, detail={"room_id": str(room_id)})
def set_person_exclusion(conn, actor: UUID, kind: str, resource_id: UUID, subject_id: UUID, excluded: bool) -> None:
"""Take one person out of the room shares of an own case or matter."""
resource = _shareable(conn, actor, kind, resource_id)
if subject_id == actor:
raise unprocessable("Du kannst dich nicht selbst ausnehmen.")
member = conn.execute(
"""
SELECT 1 FROM room_shares s
JOIN room_memberships m ON m.room_id = s.room_id AND m.subject_id = %s AND m.status = 'active'
WHERE s.resource_kind = %s AND s.resource_id = %s
""",
(subject_id, kind, resource_id),
).fetchone()
if member is None:
raise not_found()
conn.execute(
"""
DELETE FROM access_grants
WHERE is_exception AND grantee_subject_id = %s AND resource_kind = %s AND resource_id = %s
AND context_kind IS NULL
""",
(subject_id, kind, resource_id),
)
if excluded:
conn.execute(
"""
INSERT INTO access_grants (
grantee_subject_id, resource_kind, resource_id,
can_read, can_edit, can_share, can_delete, is_exception, created_by
)
VALUES (%s, %s, %s, true, true, true, true, true, %s)
""",
(subject_id, kind, resource_id, actor),
)
audit(
conn,
actor,
resource["home_scope_id"],
"person_excluded" if excluded else "person_included",
kind,
resource_id,
)
def create_case(conn, actor: UUID, scope_id: UUID, title: str, parent_case_id: UUID | None, rights_mode: str) -> dict:
ensure_can_create(conn, actor, scope_id)
title = title.strip()
if parent_case_id is None:
row = conn.execute(
@@ -103,6 +233,7 @@ def create_case(conn, actor: UUID, scope_id: UUID, title: str, parent_case_id: U
""",
(parent["home_scope_id"], actor, actor, title, parent["id"], rights_mode),
).fetchone()
_auto_share(conn, actor, "case", row)
audit(conn, actor, row["home_scope_id"], "case_created", "case", row["id"])
return row
@@ -338,6 +469,7 @@ def set_chapter_date(
def create_matter(conn, actor: UUID, scope_id: UUID, title: str, parent_matter_id: UUID | None, context: Ctx | None) -> dict:
ensure_can_create(conn, actor, scope_id)
title = title.strip()
if parent_matter_id is None:
row = conn.execute(
@@ -363,6 +495,7 @@ def create_matter(conn, actor: UUID, scope_id: UUID, title: str, parent_matter_i
""",
(parent["home_scope_id"], actor, actor, title, parent["id"]),
).fetchone()
_auto_share(conn, actor, "matter", row)
audit(conn, actor, row["home_scope_id"], "matter_created", "matter", row["id"], context)
return row
@@ -516,8 +649,9 @@ def move_bindings_chapter(
def delete_case(conn, actor: UUID, case_id: UUID, expected: int) -> None:
case, rights = require_case(conn, actor, case_id, "edit")
if not rights.edit:
case, rights = require_case(conn, actor, case_id, "read")
# Deleting the container is the owner's right. Editing, also through the room share, is not enough.
if case["owner_subject_id"] != actor and not rights.delete:
raise forbidden()
children = conn.execute(
"SELECT id FROM cases WHERE parent_case_id = %s AND deleted_at IS NULL",
@@ -532,7 +666,9 @@ def delete_case(conn, actor: UUID, case_id: UUID, expected: int) -> None:
def delete_matter(conn, actor: UUID, matter_id: UUID, expected: int, context: Ctx | None) -> None:
matter, _rights = require_matter(conn, actor, matter_id, context, "edit")
matter, rights = require_matter(conn, actor, matter_id, context, "read")
if matter["owner_subject_id"] != actor and not rights.delete:
raise forbidden()
children = conn.execute(
"SELECT id FROM matters WHERE parent_matter_id = %s AND deleted_at IS NULL",
(matter_id,),
@@ -701,6 +837,12 @@ def _actor_rights_for(conn, actor: UUID, kind: str, resource_id: UUID, context:
return rights
def _is_reader_of_home(conn, account_id: UUID, home_scope_id: UUID) -> bool:
from app.access.roles import room_role
return room_role(conn, account_id, home_scope_id) == "reader"
def grant_access(
conn,
actor: UUID,
@@ -740,6 +882,8 @@ def grant_access(
).fetchone()
if account is None:
raise not_found()
if (can_edit or can_share) and _is_reader_of_home(conn, grantee_id, resource["home_scope_id"]):
raise unprocessable("Diese Person ist in dem Datenraum der Akte nur Leser und kann nicht bearbeiten oder freigeben.")
existing = conn.execute(
"""
SELECT id, use_owner_sources FROM access_grants
@@ -908,6 +1052,7 @@ def create_note(
received_on: date | None = None,
communication_direction: str | None = None,
) -> dict:
ensure_can_create(conn, actor, scope_id)
document = clean_document(document)
target, rights_context = _placement(context, placement)
require_container_edit(conn, actor, target, rights_context)
@@ -929,7 +1074,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 +1143,11 @@ 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:
ensure_can_create(conn, actor, scope_id)
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 +1155,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)
@@ -1015,23 +1168,34 @@ def create_external(conn, actor: UUID, scope_id: UUID, title: str, source: str,
def create_file(conn, actor: UUID, scope_id: UUID, title: str, filename: str, data: bytes, context: Ctx, placement: Ctx | None, chapter_id: UUID | None, document_on, sent_on, received_on, media_root: str, max_bytes: int, rollback_files: list[Path], communication_direction: str | None = None) -> dict:
ensure_can_create(conn, actor, scope_id)
if not data or len(data) > max_bytes:
raise unprocessable("Die Datei ist leer oder zu groß.")
content_type = sniff(data)
target, rights_context = _placement(context, placement)
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)
rollback_files.append(path)
content_revision = str(uuid4())
instance = instance_for_write(conn, media_root)
object_key = str(asset_id)
adapter = adapter_for(instance)
from app.sourceaccess import release_for_external
release_for_external(conn)
publish(adapter, object_key, data)
rollback_files.append(StoredHandle(adapter, object_key))
require_container_edit(conn, actor, target, rights_context)
element = _new_element(conn, actor, scope_id, title, "file")
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 +1205,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,12 +1244,21 @@ 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(
removal_for(
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)
def create_task(conn, actor: UUID, scope_id: UUID, title: str, due_on: date | None, matter_id: UUID | None, context: Ctx | None) -> dict:
ensure_can_create(conn, actor, scope_id)
if matter_id is not None:
require_matter(conn, actor, matter_id, context, "edit")
row = conn.execute(
@@ -1186,6 +1364,7 @@ def assign_task(conn, actor: UUID, task_id: UUID, assignee_id: UUID | None, cont
def create_deadline(conn, actor: UUID, scope_id: UUID, title: str, due_on: date, matter_id: UUID | None, context: Ctx | None) -> dict:
ensure_can_create(conn, actor, scope_id)
if matter_id is not None:
require_matter(conn, actor, matter_id, context, "edit")
row = conn.execute(
+90 -11
View File
@@ -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,57 @@ 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.sourcebind import resolve_for_read
from app.sourceregistry import get_source
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
@@ -237,7 +265,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}
@@ -719,8 +747,23 @@ def matter_contexts(conn, actor: UUID, matter: dict) -> list[dict]:
return contexts
def _shared_rooms(conn, kind: str, resource_id: UUID) -> list[dict]:
rows = conn.execute(
"""
SELECT r.id, r.name, s.access FROM room_shares s JOIN data_rooms r ON r.id = s.room_id
WHERE s.resource_kind = %s AND s.resource_id = %s
ORDER BY r.name, r.id
""",
(kind, resource_id),
).fetchall()
return [{"id": str(row["id"]), "name": row["name"], "access": row["access"]} for row in rows]
def matter_summary(conn, actor: UUID, matter: dict) -> dict:
owner = matter["owner_subject_id"] == actor
return {
"is_owner": owner,
"shared_with": _shared_rooms(conn, "matter", matter["id"]) if owner else [],
"id": str(matter["id"]),
"title": matter["title"],
"status": matter["record_status"],
@@ -1003,4 +1046,40 @@ LABELS = {
"chapter_moved": "Kapitel umgehängt",
"content_order": "Ordnungsart geändert",
"content_reordered": "Eigene Reihenfolge geändert",
"account_created": "Konto angelegt",
"account_renamed": "Kontoname geändert",
"account_disabled": "Konto deaktiviert",
"account_enabled": "Konto aktiviert",
"operator_granted": "Betreiberrolle vergeben",
"operator_revoked": "Betreiberrolle entzogen",
"password_reset": "Passwort zurückgesetzt",
"password_changed": "Passwort geändert",
"sessions_revoked": "Sitzungen beendet",
"session_started": "Angemeldet",
"session_ended": "Abgemeldet",
"room_created": "Datenraum angelegt",
"room_renamed": "Datenraum umbenannt",
"room_archived": "Datenraum archiviert",
"room_restored": "Datenraum wieder aktiviert",
"membership_added": "Mitglied hinzugefügt",
"membership_role_changed": "Raumrolle geändert",
"membership_removed": "Mitglied entfernt",
"invitation_created": "Einladung erstellt",
"invitation_revoked": "Einladung widerrufen",
"invitation_accepted": "Einladung angenommen",
"visibility_changed": "Raumfreigabe geändert",
"employee_promoted": "Mitarbeiter zum Hauptnutzer gemacht",
"employee_disabled": "Mitarbeiter-Konto deaktiviert",
"employee_enabled": "Mitarbeiter-Konto aktiviert",
"employee_password_reset": "Passwort eines Mitarbeiters zurückgesetzt",
"employee_removed": "Mitarbeiter aus allen Räumen entfernt",
"room_shared": "Mit Datenraum geteilt",
"room_share_changed": "Freigabe an Datenraum geändert",
"room_unshared": "Freigabe an Datenraum beendet",
"person_excluded": "Person von der Raumfreigabe ausgenommen",
"person_included": "Person wieder in die Raumfreigabe aufgenommen",
"room_owner_changed": "Eigentümer des Datenraums gewechselt",
"room_default_changed": "Voreinstellung des Datenraums geändert",
"room_download_policy_changed": "Download-Regel des Datenraums geändert",
"download_defaults_changed": "Standard für Downloads geändert",
}
+133
View File
@@ -0,0 +1,133 @@
"""Fetching the pictures a mail refers to, on the server and only on request.
The browser never contacts the sender: the server loads each picture, checks that it really is
a PNG, JPEG, GIF or WebP, and hands it over inline. This hides the reader's address and device.
It cannot hide that the mail was opened, because the sender sees the request.
Only public https addresses are fetched. The address is resolved once, every result must be a
public one, and the connection goes to exactly that address, so a changing DNS answer cannot
lead to an internal host. Redirects are followed a few times with the same checks.
"""
from __future__ import annotations
import base64
import http.client
import ipaddress
import socket
import ssl
from urllib.parse import urljoin, urlsplit
MAX_IMAGE_BYTES = 1_500_000
MAX_REDIRECTS = 3
TIMEOUT_SECONDS = 5
MAX_IMAGES = 12
MAX_TOTAL_BYTES = 6_000_000
_SIGNATURES = (
(b"\x89PNG\r\n\x1a\n", "png"),
(b"\xff\xd8\xff", "jpeg"),
(b"GIF87a", "gif"),
(b"GIF89a", "gif"),
)
class _Pinned(http.client.HTTPSConnection):
"""An https connection that goes to a fixed, already checked address."""
def __init__(self, host: str, address: str, port: int) -> None:
super().__init__(host, port, timeout=TIMEOUT_SECONDS, context=ssl.create_default_context())
self._address = address
def connect(self) -> None:
sock = socket.create_connection((self._address, self.port), self.timeout)
self.sock = self._context.wrap_socket(sock, server_hostname=self.host)
def is_public(address: str) -> bool:
try:
ip = ipaddress.ip_address(address)
except ValueError:
return False
return ip.is_global and not ip.is_multicast
def _public_address(host: str, port: int) -> str | None:
try:
found = {item[4][0] for item in socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)}
except OSError:
return None
if not found or not all(is_public(address) for address in found):
return None
return sorted(found)[0]
def _kind(data: bytes) -> str | None:
for signature, kind in _SIGNATURES:
if data.startswith(signature):
return kind
if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
return "webp"
return None
def fetch_image(url: str) -> bytes | None:
"""The bytes of a picture, or None when anything about it is not safe."""
for _ in range(MAX_REDIRECTS + 1):
parts = urlsplit(url)
if parts.scheme != "https" or not parts.hostname or parts.username or parts.password:
return None
port = parts.port or 443
if port != 443:
return None
address = _public_address(parts.hostname, port)
if address is None:
return None
target = (parts.path or "/") + (f"?{parts.query}" if parts.query else "")
connection = _Pinned(parts.hostname, address, port)
try:
connection.request("GET", target, headers={"User-Agent": "Mozilla/5.0", "Accept": "image/png,image/jpeg,image/gif,image/webp", "Connection": "close"})
response = connection.getresponse()
if response.status in {301, 302, 303, 307, 308}:
location = response.getheader("Location")
if not location:
return None
url = urljoin(url, location)
continue
if response.status != 200:
return None
data = response.read(MAX_IMAGE_BYTES + 1)
except (OSError, http.client.HTTPException, ssl.SSLError):
return None
finally:
connection.close()
if len(data) > MAX_IMAGE_BYTES or _kind(data) is None:
return None
return data
return None
class RemoteImages:
"""Loads the pictures of one mail within a budget and remembers each address once."""
def __init__(self) -> None:
self.cache: dict[str, str] = {}
self.total = 0
self.loaded = 0
self.failed = 0
def __call__(self, url: str) -> str:
if url in self.cache:
return self.cache[url]
result = ""
if len(self.cache) < MAX_IMAGES and self.total < MAX_TOTAL_BYTES:
data = fetch_image(url)
if data is not None:
self.total += len(data)
result = f"data:image/{_kind(data)};base64,{base64.b64encode(data).decode('ascii')}"
self.cache[url] = result
if result:
self.loaded += 1
else:
self.failed += 1
return result
+33 -111
View File
@@ -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 element_id, 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:
+3 -3
View File
@@ -87,11 +87,11 @@ def seed_demo(settings: Settings | None = None) -> bool:
ben = create_account(conn, BEN_EMAIL, "Ben Beispiel", BEN_PASSWORD, origin="fixture")
room = conn.execute(
"""
INSERT INTO data_rooms (id, kind, name, created_by)
VALUES (gen_random_uuid(), 'organization', 'Haushalt Musterstraße', %s)
INSERT INTO data_rooms (id, kind, name, created_by, owner_id)
VALUES (gen_random_uuid(), 'organization', 'Haushalt Musterstraße', %s, %s)
RETURNING id
""",
(ada["id"],),
(ada["id"], ada["id"]),
).fetchone()
conn.execute(
"INSERT INTO room_memberships (room_id, subject_id, role) VALUES (%s, %s, 'manager'), (%s, %s, 'member')",
+138
View File
@@ -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
+258
View File
@@ -0,0 +1,258 @@
"""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. 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
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 IN ('unresolved', 'ambiguous')
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)
def remember_imap_location(
conn,
element_id: UUID,
external_id: str,
previous_mailbox: str,
previous_uid: int,
mailbox: str,
uid: int,
) -> None:
"""Store the folder and UID of a message found at a new place.
Only the previous place is replaced. The message identity, the connector
and an adopted direction stay as they were.
"""
if (
not mailbox
or any(char in mailbox for char in "\r\n\x00")
or uid < 1
or (mailbox == previous_mailbox and uid == previous_uid)
):
return
conn.execute(
"""
UPDATE external_references
SET detail = jsonb_set(
jsonb_set(detail, '{mailbox}', to_jsonb(%s::text)),
'{uid}',
to_jsonb(%s::bigint)
)
WHERE element_id = %s
AND source = 'imap'
AND external_id = %s
AND detail->>'mailbox' = %s
AND detail->>'uid' = %s
""",
(mailbox, uid, element_id, external_id, previous_mailbox, str(previous_uid)),
)
+111
View File
@@ -0,0 +1,111 @@
"""Declared source and editor capabilities.
A common contract does not invent abilities the adapter does not have.
A filter is offered only when that module implements it.
"""
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": True,
"correspondent": True,
"document_type": True,
"tags": True,
"document_range": True,
"sort": True,
"continuation": True,
},
}
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()],
"modules": [
{
"kind": module.kind,
"label": module.label,
"representation": module.representation,
"config_fields": [item.public() for item in module.config_fields],
}
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]
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
+162
View File
@@ -0,0 +1,162 @@
"""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
FIELD_TYPES = ("text", "url", "number", "password", "select")
@dataclass(frozen=True)
class ConfigField:
"""One configuration field a module declares for its connector instances.
At most one field per module is a secret. Its value is stored apart from
the settings and is never handed out again.
"""
key: str
label: str
type: str = "text"
required: bool = False
secret: bool = False
default: str | int | None = None
options: tuple[tuple[str, str], ...] = ()
help: str = ""
placeholder: str = ""
minimum: int | None = None
maximum: int | None = None
max_length: int = 200
def public(self) -> dict:
return {
"key": self.key,
"label": self.label,
"type": self.type,
"required": self.required,
"secret": self.secret,
"default": self.default,
"options": [{"value": value, "label": label} for value, label in self.options],
"help": self.help,
"placeholder": self.placeholder,
"minimum": self.minimum,
"maximum": self.maximum,
"max_length": self.max_length,
}
@dataclass
class SourceModule:
kind: str
label: str
representation: str
capabilities: dict
probe: Callable
find: Callable
open_original: Callable
export_original: Callable
# A module either declares fields (generic validation) or parses the payload itself.
parse_config: Callable[[dict], tuple[str, dict, str]] | None = None
config_fields: tuple[ConfigField, ...] = ()
normalize_config: Callable[[dict, str], dict] | None = None
navigate: Callable | None = None
preview: Callable | None = None
facets: Callable | None = None
_MODULES: dict[str, SourceModule] = {}
def register_source(module: SourceModule) -> None:
if module.parse_config is None and not module.config_fields:
raise ValueError(f"Quelle {module.kind} braucht Konfigurationsfelder oder parse_config.")
if sum(1 for item in module.config_fields if item.secret) > 1:
raise ValueError(f"Quelle {module.kind} darf höchstens ein Geheimnisfeld haben.")
for item in module.config_fields:
if item.type not in FIELD_TYPES:
raise ValueError(f"Feldtyp {item.type} ist unbekannt.")
_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
def _blank(value) -> bool:
return value is None or (isinstance(value, str) and not value.strip())
def _coerce(field: ConfigField, value):
if field.type == "number":
try:
number = int(str(value).strip())
except (TypeError, ValueError):
raise unprocessable(f"{field.label} muss eine ganze Zahl sein.") from None
if field.minimum is not None and number < field.minimum:
raise unprocessable(f"{field.label} ist zu klein.")
if field.maximum is not None and number > field.maximum:
raise unprocessable(f"{field.label} ist zu groß.")
return number
text = str(value) if field.secret else str(value).strip()
if len(text) > field.max_length:
raise unprocessable(f"{field.label} ist zu lang.")
if field.type == "select" and text not in {option for option, _label in field.options}:
raise unprocessable(f"{field.label} ist keine zulässige Auswahl.")
return text
def parse_fields(
fields: tuple[ConfigField, ...],
values: dict,
current_settings: dict | None = None,
current_secret: str = "",
) -> tuple[dict, str]:
"""Validate declared fields. Unknown keys are refused, a blank secret keeps the stored one."""
known = {item.key for item in fields}
extra = sorted(key for key, value in values.items() if key not in known and not _blank(value))
if extra:
raise unprocessable("Unbekanntes Konfigurationsfeld: " + ", ".join(extra[:3]) + ".")
current_settings = current_settings or {}
settings: dict = {}
secret = current_secret
for item in fields:
raw = values.get(item.key)
if item.secret:
if _blank(raw):
if not current_secret and item.required:
raise unprocessable(f"{item.label} fehlt.")
continue
secret = _coerce(item, raw)
continue
if _blank(raw):
raw = current_settings.get(item.key)
if _blank(raw):
raw = item.default
if _blank(raw):
if item.required:
raise unprocessable(f"{item.label} fehlt.")
continue
settings[item.key] = _coerce(item, raw)
return settings, secret
+1026 -219
View File
File diff suppressed because it is too large. Load diff
@@ -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')
);
@@ -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;
@@ -0,0 +1,8 @@
-- Last connection check per connector instance. Display only: it grants nothing
-- and carries no secret.
ALTER TABLE connectors
ADD COLUMN last_probe_at timestamptz,
ADD COLUMN last_probe_ok boolean,
ADD COLUMN last_probe_detail text,
ADD CONSTRAINT connectors_probe_detail_len CHECK (last_probe_detail IS NULL OR char_length(last_probe_detail) <= 300);
@@ -0,0 +1,31 @@
-- Benutzerverwaltung: Kontostatus, Sitzungsübersicht, persistente Login-Begrenzung,
-- Raumrolle "Leser" und Rollen in Einladungen. Bestehende Zeilen bleiben gültig.
ALTER TABLE auth_accounts
ADD COLUMN must_change_password boolean NOT NULL DEFAULT false,
ADD COLUMN password_changed_at timestamptz,
ADD COLUMN last_login_at timestamptz,
ADD COLUMN disabled_at timestamptz,
ADD COLUMN disabled_by uuid REFERENCES auth_accounts (id);
ALTER TABLE auth_sessions
ADD COLUMN last_seen_at timestamptz,
ADD COLUMN label text,
ADD CONSTRAINT auth_sessions_label_len CHECK (label IS NULL OR char_length(label) <= 80);
-- Der Bucket ist ein Hash aus Adresse und E-Mail. Die Roh-E-Mail wird nie gespeichert.
CREATE TABLE auth_login_attempts (
bucket text NOT NULL,
attempted_at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX auth_login_attempts_bucket ON auth_login_attempts (bucket, attempted_at);
ALTER TABLE room_memberships DROP CONSTRAINT room_memberships_role;
ALTER TABLE room_memberships
ADD CONSTRAINT room_memberships_role CHECK (role IN ('member', 'manager', 'reader'));
ALTER TABLE auth_invitations
ADD COLUMN role text NOT NULL DEFAULT 'member',
ADD COLUMN revoked_at timestamptz,
ADD CONSTRAINT auth_invitations_role CHECK (role IN ('member', 'manager', 'reader'));
@@ -0,0 +1,21 @@
-- Raum-Eigentümer und Raumfreigabe. Bestehende Akten und Vorgänge bleiben privat.
ALTER TABLE data_rooms
ADD COLUMN owner_id uuid REFERENCES auth_accounts (id),
ADD COLUMN default_visibility text NOT NULL DEFAULT 'private',
ADD CONSTRAINT data_rooms_default_visibility CHECK (default_visibility IN ('private', 'room'));
UPDATE data_rooms SET owner_id = created_by;
ALTER TABLE data_rooms
ADD CONSTRAINT data_rooms_owner CHECK (kind = 'personal' OR owner_id IS NOT NULL);
CREATE INDEX data_rooms_owner ON data_rooms (owner_id) WHERE kind = 'organization';
ALTER TABLE cases
ADD COLUMN visibility text NOT NULL DEFAULT 'private',
ADD CONSTRAINT cases_visibility CHECK (visibility IN ('private', 'room'));
ALTER TABLE matters
ADD COLUMN visibility text NOT NULL DEFAULT 'private',
ADD CONSTRAINT matters_visibility CHECK (visibility IN ('private', 'room'));
@@ -0,0 +1,32 @@
-- Raum als Team: Eine Akte oder ein Vorgang wird mit beliebigen Datenräumen geteilt,
-- unabhängig vom Heimatraum. Der Heimatraum bleibt Ablage. Die Freigabe zum Heimatraum
-- aus 20261021T090000Z_room_access.sql wird übernommen, danach entfallen die Spalten.
CREATE TABLE room_shares (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
resource_kind text NOT NULL,
resource_id uuid NOT NULL,
room_id uuid NOT NULL REFERENCES data_rooms (id),
-- Obergrenze der Freigabe: 'edit' = Rechte nach Raumrolle, 'read' = höchstens Lesen.
access text NOT NULL DEFAULT 'edit',
created_by uuid NOT NULL REFERENCES auth_accounts (id),
created_at timestamptz NOT NULL DEFAULT now(),
CONSTRAINT room_shares_kind CHECK (resource_kind IN ('case', 'matter')),
CONSTRAINT room_shares_access CHECK (access IN ('read', 'edit')),
UNIQUE (resource_kind, resource_id, room_id)
);
CREATE INDEX room_shares_room ON room_shares (room_id);
INSERT INTO room_shares (resource_kind, resource_id, room_id, access, created_by)
SELECT 'case', c.id, c.home_scope_id, 'edit', c.owner_subject_id
FROM cases c
WHERE c.visibility = 'room';
INSERT INTO room_shares (resource_kind, resource_id, room_id, access, created_by)
SELECT 'matter', m.id, m.home_scope_id, 'edit', m.owner_subject_id
FROM matters m
WHERE m.visibility = 'room';
ALTER TABLE cases DROP CONSTRAINT cases_visibility, DROP COLUMN visibility;
ALTER TABLE matters DROP CONSTRAINT matters_visibility, DROP COLUMN visibility;
@@ -0,0 +1,13 @@
-- Hauptnutzer und Mitarbeiter. Alle bestehenden Konten sind Hauptnutzer.
-- Ein Mitarbeiter-Konto entsteht durch eine Einladung und hat den einladenden Eigentümer als Förderer.
ALTER TABLE auth_accounts
ADD COLUMN account_kind text NOT NULL DEFAULT 'main',
ADD COLUMN sponsor_id uuid REFERENCES auth_accounts (id),
ADD CONSTRAINT auth_accounts_kind CHECK (account_kind IN ('main', 'employee')),
ADD CONSTRAINT auth_accounts_sponsor CHECK (
(account_kind = 'employee' AND sponsor_id IS NOT NULL)
OR (account_kind = 'main' AND sponsor_id IS NULL)
);
CREATE INDEX auth_accounts_sponsor ON auth_accounts (sponsor_id) WHERE sponsor_id IS NOT NULL;
@@ -0,0 +1,11 @@
-- Herunterladen des Originals: je Rolle steuerbar. Voreinstellung am Konto des Hauptnutzers,
-- Übernahme beim Anlegen eines Raums, danach je Raum änderbar. "direct" gilt für Personen,
-- die einen Eintrag direkt erhalten haben (ohne Raum). Bestehende Daten bleiben erlaubt.
ALTER TABLE auth_accounts
ADD COLUMN download_defaults jsonb NOT NULL
DEFAULT '{"manager": true, "member": true, "reader": true, "direct": true}'::jsonb;
ALTER TABLE data_rooms
ADD COLUMN download_roles jsonb NOT NULL
DEFAULT '{"manager": true, "member": true, "reader": true}'::jsonb;
+1 -4
View File
@@ -43,6 +43,7 @@ def _reset(settings) -> None:
TRUNCATE TABLE
media_operations,
domain_events,
auth_login_attempts,
auth_accounts,
data_rooms
RESTART IDENTITY CASCADE
@@ -86,13 +87,9 @@ def client(database):
@pytest.fixture(autouse=True)
def clean(database, client):
from app.api import routes
routes._login_attempts.clear()
client.cookies.clear()
_reset(database)
yield
routes._login_attempts.clear()
client.cookies.clear()
_reset(database)
+165
View File
@@ -0,0 +1,165 @@
"""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.core.errors import not_found, unprocessable
from app.retrieval import FilePayload, RetrievalFailure
from app.sourcebind import resolve_for_read
from app.sourceregistry import ConfigField, SourceModule, register_source, unregister_source
from app.sourceaccess import borrow_original, complete_borrow
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,
},
}
CONFIG_FIELDS = (
ConfigField("catalog", "Katalog", required=True, default="alpha", help="Name des Beispielkatalogs."),
)
def normalize_config(settings: dict, secret: str) -> dict:
del secret
if settings["catalog"] not in CATALOG:
raise unprocessable("Der Katalog dieser Beispielquelle ist unbekannt.")
return settings
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]:
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):
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,
config_fields=CONFIG_FIELDS,
normalize_config=normalize_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"
+2 -1
View File
@@ -35,7 +35,8 @@ def test_bootstrap_once_then_superadmin_creates_users(client):
status=201,
)
assert created["is_superadmin"] is False
assert "password" not in created
assert created["must_change_password"] is True
assert "password" not in created and "temporary_password" not in created
listed = owner.request("GET", "/api/v1/accounts")
assert {item["email"] for item in listed["items"]} == {"betreiber@example.test", "mitglied@example.test"}
assert all("password_hash" not in item and "password" not in item for item in listed["items"])
+539
View File
@@ -0,0 +1,539 @@
"""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 True
assert "correspondent" not in found["unsupported"]
filtered = ada.request(
"GET",
"/api/v1/sources/paperless/documents",
params={"q": "Treffer", "connector_id": older, "correspondent": "4"},
)
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):
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
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"]
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_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")
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
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")
+215
View File
@@ -0,0 +1,215 @@
"""Connector configuration: fields come from the module, secrets never leave the server."""
from __future__ import annotations
import pytest
from app.core.errors import Problem
from app.sourceregistry import ConfigField, parse_fields
from tests.sample_source import install_sample_source, remove_sample_source
from tests.support import Actor, register
SECRET_WORDS = ("secret", "token-geheim-1234", "passwort-geheim")
PAPERLESS = {"kind": "paperless", "name": "Archiv", "base_url": "https://paper.example.test", "token": "token-geheim-1234"}
IMAP = {
"kind": "imap",
"name": "Postfach",
"host": "imap.example.test",
"port": 993,
"username": "ada",
"password": "passwort-geheim",
"security": "ssl",
}
@pytest.fixture
def sample_source():
install_sample_source()
try:
yield
finally:
remove_sample_source()
def _ada(client, db) -> Actor:
ada = Actor(client, "ada-config@example.test", "Ada Konfig")
register(db, ada.email, ada.name)
ada.login()
return ada
def _stored(db, connector_id: str) -> dict:
return db.execute("SELECT settings, secret FROM connectors WHERE id = %s", (connector_id,)).fetchone()
def test_parse_fields_checks_types_and_refuses_unknown_keys():
fields = (
ConfigField("host", "Server", required=True),
ConfigField("port", "Port", type="number", default=993, minimum=1, maximum=65535),
ConfigField("mode", "Modus", type="select", default="a", options=(("a", "A"), ("b", "B"))),
ConfigField("key", "Schlüssel", type="password", required=True, secret=True),
)
settings, secret = parse_fields(fields, {"host": " h ", "key": "k"})
assert settings == {"host": "h", "port": 993, "mode": "a"}
assert secret == "k"
for bad in (
{"host": "h", "key": "k", "port": "abc"},
{"host": "h", "key": "k", "port": 0},
{"host": "h", "key": "k", "mode": "c"},
{"host": "h", "key": "k", "fremd": "x"},
{"key": "k"},
{"host": "h"},
):
with pytest.raises(Problem) as caught:
parse_fields(fields, bad)
assert caught.value.status == 422
kept_settings, kept_secret = parse_fields(fields, {"host": "neu", "key": ""}, {"host": "alt", "port": 143}, "bleibt")
assert kept_settings["host"] == "neu" and kept_settings["port"] == 143
assert kept_secret == "bleibt"
def test_capabilities_list_the_fields_of_each_module(client, db):
ada = _ada(client, db)
modules = {item["kind"]: item for item in ada.request("GET", "/api/v1/sources/capabilities")["modules"]}
assert {"paperless", "imap"} <= set(modules)
paperless = {item["key"]: item for item in modules["paperless"]["config_fields"]}
assert paperless["token"]["secret"] is True and paperless["base_url"]["required"] is True
imap = {item["key"]: item for item in modules["imap"]["config_fields"]}
assert imap["password"]["secret"] is True
assert imap["port"]["type"] == "number" and imap["port"]["default"] == 993
assert [option["value"] for option in imap["security"]["options"]] == ["ssl", "starttls"]
assert imap["mailbox"]["default"] == "INBOX"
def test_create_with_config_and_flat_fields_gives_the_same_stored_result(client, db):
ada = _ada(client, db)
flat = ada.request("POST", "/api/v1/connectors", json=PAPERLESS, status=201)
config = ada.request(
"POST",
"/api/v1/connectors",
json={
"kind": "paperless",
"name": "Zweites Archiv",
"config": {"base_url": "https://paper.example.test/", "token": "token-geheim-1234"},
},
status=201,
)
assert _stored(db, flat["id"]) == _stored(db, config["id"])
assert _stored(db, flat["id"])["settings"] == {"base_url": "https://paper.example.test"}
def test_secrets_never_leave_the_server(client, db):
ada = _ada(client, db)
created = ada.request("POST", "/api/v1/connectors", json=IMAP, status=201)
detail = ada.request("GET", f"/api/v1/connectors/{created['id']}")
listed = ada.request("GET", "/api/v1/connectors")
for body in (created, detail, listed):
text = str(body)
assert not any(word in text for word in SECRET_WORDS if word != "secret"), text
assert "'secret'" not in text and "'password'" not in text and "'token'" not in text
assert detail["has_secret"] is True
assert detail["settings"]["mailbox"] == "INBOX"
assert detail["settings"]["port"] == 993
assert detail["protection_profile"] == "legacy-plaintext"
assert detail["references"] == 0
assert detail["probe"] is None
def test_change_without_secret_keeps_the_stored_one_and_the_instance(client, db):
ada = _ada(client, db)
created = ada.request("POST", "/api/v1/connectors", json=IMAP, status=201)
changed = ada.request(
"PATCH",
f"/api/v1/connectors/{created['id']}",
json={"kind": "imap", "name": "Umbenannt", "config": {"host": "mail.example.test", "port": "143", "security": "starttls"}},
)
assert changed["id"] == created["id"]
assert changed["name"] == "Umbenannt"
stored = _stored(db, created["id"])
assert stored["secret"] == "passwort-geheim"
assert stored["settings"]["host"] == "mail.example.test"
assert stored["settings"]["port"] == 143
assert stored["settings"]["security"] == "starttls"
assert stored["settings"]["username"] == "ada"
renewed = ada.request(
"PATCH",
f"/api/v1/connectors/{created['id']}",
json={"kind": "imap", "name": "Umbenannt", "config": {"password": "neues-passwort"}},
)
assert renewed["id"] == created["id"]
assert _stored(db, created["id"])["secret"] == "neues-passwort"
def test_module_validation_refuses_bad_input(client, db):
ada = _ada(client, db)
ada.request("POST", "/api/v1/connectors", json={**PAPERLESS, "base_url": "ftp://paper.example.test"}, status=422)
ada.request("POST", "/api/v1/connectors", json={**PAPERLESS, "token": "kurz"}, status=422)
ada.request("POST", "/api/v1/connectors", json={**IMAP, "host": "mail server"}, status=422)
ada.request("POST", "/api/v1/connectors", json={**IMAP, "port": 70000}, status=422)
ada.request("POST", "/api/v1/connectors", json={**IMAP, "password": None}, status=422)
ada.request(
"POST",
"/api/v1/connectors",
json={"kind": "paperless", "name": "Fremdfeld", "config": {"base_url": "https://paper.example.test", "token": "token-geheim-1234", "host": "x"}},
status=422,
)
created = ada.request("POST", "/api/v1/connectors", json=PAPERLESS, status=201)
ada.request(
"PATCH",
f"/api/v1/connectors/{created['id']}",
json={**PAPERLESS, "kind": "imap"},
status=422,
)
assert _stored(db, created["id"])["settings"] == {"base_url": "https://paper.example.test"}
def test_a_foreign_instance_is_not_found(client, db):
ada = _ada(client, db)
ben = Actor(client, "ben-config@example.test", "Ben Konfig")
register(db, ben.email, ben.name)
created = ada.request("POST", "/api/v1/connectors", json=PAPERLESS, status=201)
ben.login()
ben.request("GET", f"/api/v1/connectors/{created['id']}", status=404)
ben.request("PATCH", f"/api/v1/connectors/{created['id']}", json=PAPERLESS, status=404)
ben.request("DELETE", f"/api/v1/connectors/{created['id']}", status=404)
def test_probe_result_is_kept_for_display(client, db, sample_source):
del sample_source
ada = _ada(client, db)
created = ada.request(
"POST",
"/api/v1/connectors",
json={"kind": "sample", "name": "Katalog", "config": {"catalog": "alpha"}},
status=201,
)
probed = ada.request("POST", f"/api/v1/connectors/{created['id']}/probe")
detail = ada.request("GET", f"/api/v1/connectors/{created['id']}")
assert detail["probe"]["ok"] is True
assert detail["probe"]["detail"] == probed["detail"]
ada.request(
"PATCH",
f"/api/v1/connectors/{created['id']}",
json={"kind": "sample", "name": "Katalog", "config": {"catalog": "alpha"}},
)
assert ada.request("GET", f"/api/v1/connectors/{created['id']}")["probe"] is None
def test_a_module_with_fields_needs_no_central_schema(client, db, sample_source):
del sample_source
ada = _ada(client, db)
modules = {item["kind"]: item for item in ada.request("GET", "/api/v1/sources/capabilities")["modules"]}
assert [item["key"] for item in modules["sample"]["config_fields"]] == ["catalog"]
ada.request(
"POST",
"/api/v1/connectors",
json={"kind": "sample", "name": "Ohne Wert", "config": {}},
status=201,
)
ada.request(
"POST",
"/api/v1/connectors",
json={"kind": "sample", "name": "Falsch", "config": {"catalog": "kein-katalog"}},
status=422,
)
+770
View File
@@ -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 <ada@example.test>\r\n"
b"To: Ben <ben@example.test>\r\n"
b"Subject: Brief\r\n"
b"Message-ID: <brief@example.test>\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": "<brief@example.test>", "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 <ada@example.test>\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": "<brief@example.test>",
"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",
"```",
"",
"<script>alert(1)</script>",
"",
"![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 "<script>alert(1)</script>" 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 "<script>alert(1)</script>" 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)
+503
View File
@@ -0,0 +1,503 @@
"""Corrections K1–K3 and K7. Synthetic only; no live mailbox or Paperless."""
from __future__ import annotations
import hashlib
import imaplib
import psycopg
import pytest
from email.message import EmailMessage
import app.sources as sources
from app.core.errors import unprocessable
from app.mailpack import parse_mail
from tests.support import Actor, register
def test_mailbox_names_are_quoted_protocol_strings():
client = imaplib.IMAP4.__new__(imaplib.IMAP4)
client.sent = []
client.state = "AUTH"
client._encoding = "ascii"
client.tagpre = b"T"
client.tagnum = 1
client.tagged_commands = {}
client.untagged_responses = {}
client.is_readonly = True
client.literal = None
client.debug = 0
client._mesg = lambda *args: None
client._log = lambda *args: None
client.send = lambda data: client.sent.append(data)
value = "Sent Items"
client._command("EXAMINE", sources._mailbox_argument(value))
assert client.sent[-1] == b'T1 EXAMINE "Sent Items"\r\n'
value = 'Ordner "A"\\B'
client._command("EXAMINE", sources._mailbox_argument(value))
assert client.sent[-1] == b'T2 EXAMINE "Ordner \\"A\\"\\\\B"\r\n'
assert sources._mailbox_argument("INBOX") == "INBOX"
with pytest.raises(Exception):
sources._mailbox_argument("Sent\nItems")
def test_parse_mail_keeps_names_html_and_attached_messages():
inner = EmailMessage()
inner["Subject"] = "Innen"
inner.set_content("innen bleibt drin")
inner.add_attachment(b"innen-pdf", maintype="application", subtype="pdf", filename="innen.pdf")
outer = EmailMessage()
outer["From"] = "Ada <ada@example.test>"
outer["To"] = "Ben <ben@example.test>"
outer["Subject"] = "=?utf-8?q?Aussen?="
outer.set_content("aussen bleibt aussen")
outer.add_attachment(b"%PDF-same", maintype="application", subtype="pdf", filename="lage.pdf")
outer.add_attachment(b"%PDF-other", maintype="application", subtype="pdf", filename="lage.pdf")
outer.add_attachment(inner, subtype="rfc822", filename="weitergeleitet.eml")
html = (
"<p>A &amp; B</p><table><tr><td>Zelle</td><td>Zwei</td></tr></table>"
"<script>alert(1)</script><img src=\"https://evil.test/a.png\">"
"<a href=\"javascript:alert(1)\">x</a><img src=\"cid:logo@x\">"
)
mixed = EmailMessage()
mixed["Subject"] = "HTML"
mixed.set_content("nur text")
mixed.add_alternative(html, subtype="html")
logo = b"\x89PNG\r\n"
mixed.add_attachment(logo, maintype="image", subtype="png", filename="logo.png", cid="<logo@x>")
encoded = EmailMessage()
encoded["Subject"] = "Namen"
encoded.set_content("datei")
encoded.add_attachment(
b"pdf",
maintype="application",
subtype="pdf",
filename="=?utf-8?q?Buero_Uebergabe=2Epdf?=",
)
parsed = parse_mail(outer.as_bytes())
assert parsed.subject == "Aussen"
assert parsed.text == "aussen bleibt aussen"
assert "innen" not in parsed.text
names = [item.display_name for item in parsed.attachments]
assert "weitergeleitet.eml" in names
assert names.count("lage.pdf") == 2
archives = [item.filename for item in parsed.attachments]
assert len(set(archives)) == len(archives)
attached = next(item for item in parsed.attachments if item.display_name == "weitergeleitet.eml")
assert b"innen bleibt drin" in attached.data or b"Innen" in attached.data
assert attached.sha256 == hashlib.sha256(attached.data).hexdigest()
view = parse_mail(mixed.as_bytes())
assert "<table>" in view.html
assert "<script" not in view.html
assert "https://evil.test" not in view.html
assert "javascript:" not in view.html
assert "data:image/png;base64," in view.html
assert "A & B" in view.html or "A &amp; B" in view.html
assert "Zelle" in view.html
named = parse_mail(encoded.as_bytes())
assert named.attachments[0].display_name == "Buero Uebergabe.pdf"
assert "=?utf-8?" not in named.attachments[0].display_name
assert named.attachments[0].data == b"pdf"
def test_an_undecoded_pdf_stays_a_named_pdf():
import base64
from app.media.storage import content_disposition
pdf = b"%PDF-1.4\n1 0 obj\n<<>>\nendobj\ntrailer\n<<>>\n%%EOF\n"
raw = (
b"Subject: Scan\r\n"
b"MIME-Version: 1.0\r\n"
b"Content-Type: multipart/mixed; boundary=bound\r\n"
b"\r\n"
b"--bound\r\n"
b"Content-Type: text/plain; charset=utf-8\r\n"
b"\r\n"
b"text\r\n"
b"--bound\r\n"
b"Content-Type: application/octet-stream\r\n"
b"Content-Transfer-Encoding: 8bit\r\n"
b"Content-Disposition: attachment; filename=\"scan-7f3a9c\"\r\n"
b"\r\n"
+ base64.b64encode(pdf) + b"\r\n"
b"--bound--\r\n"
)
item = parse_mail(raw).attachments[0]
assert item.data.startswith(b"%PDF")
assert item.media_type == "application/pdf"
assert item.display_name == "scan-7f3a9c.pdf"
header = content_disposition("\u00dcbergabe.pdf", inline=True)
assert header.startswith("inline;")
header.encode("ascii")
assert ".pdf" in header
assert "filename*=UTF-8''" in header
assert "%C3%9Cbergabe.pdf" in header
class QuotedIMAP:
def __init__(self, *args, **kwargs):
self.untagged_responses = {}
def login(self, username, secret):
return "OK", [b"logged"]
def list(self):
return "OK", [b'(\\HasNoChildren) "/" "Sent Items"']
def select(self, mailbox, readonly=False):
assert readonly is True
assert mailbox == '"Sent Items"'
self.untagged_responses = {
"EXISTS": [b"4200"],
"UIDVALIDITY": [b"8"],
"UIDNEXT": [b"2"],
}
return "OK", [b"4200"]
def uid(self, command, *args):
if command == "SEARCH":
return "OK", [b""]
header = b"From: Ada <ada@example.test>\r\nSubject: Leer\r\nDate: Thu, 02 May 2024 08:00:00 +0000\r\n"
return "OK", [(b"body", header), b")"]
def logout(self):
return "BYE", [b""]
def test_a_filled_folder_with_spaces_is_not_reported_empty(client, db, monkeypatch):
monkeypatch.setattr(sources.imaplib, "IMAP4_SSL", QuotedIMAP)
ada = Actor(client, "ada-sent@example.test", "Ada Gesendet")
register(db, ada.email, ada.name)
ada.login()
account = ada.request(
"POST",
"/api/v1/connectors",
json={
"kind": "imap",
"name": "Post",
"host": "imap.example.test",
"port": 993,
"username": "ada@example.test",
"password": "Postfach-Geheim",
"security": "ssl",
},
status=201,
)
page = ada.request(
"GET",
"/api/v1/sources/imap/messages",
params={"connector_id": account["id"], "mailbox": "Sent Items"},
)
assert page["items"] == []
assert page["contradictory"] is True
assert page["exists"] == 4200
assert "leer" not in str(page).casefold()
def _multipart(text: str, name: str, payload: bytes) -> bytes:
message = EmailMessage()
message["From"] = "Ada <ada@example.test>"
message["To"] = "Ben <ben@example.test>"
message["Subject"] = "Grenze"
message["Message-ID"] = "<grenze@example.test>"
message.set_content(text)
message.add_attachment(payload, maintype="application", subtype="pdf", filename=name)
return message.as_bytes()
class LimitIMAP:
raw = b""
def __init__(self, *args, **kwargs):
self.untagged_responses = {}
def login(self, username, secret):
return "OK", [b"ok"]
def list(self):
return "OK", [b'(\\HasNoChildren) "/" "INBOX"']
def select(self, mailbox, readonly=False):
self.untagged_responses = {"UIDVALIDITY": [b"1"], "UIDNEXT": [b"3"], "EXISTS": [b"1"]}
return "OK", [b"1"]
def uid(self, command, *args):
spec = " ".join(str(part) for part in args[1:])
if "BODY.PEEK[]" in spec and "<" not in spec:
return "OK", [(b"rfc822", type(self).raw)]
if "BODYSTRUCTURE" in spec:
structure = (
b'(("TEXT" "PLAIN" ("CHARSET" "utf-8") NIL NIL "7BIT" 12 1 NIL NIL NIL NIL)'
b'("APPLICATION" "PDF" NIL NIL NIL "BASE64" 20 NIL '
b'("ATTACHMENT" ("FILENAME" "=?utf-8?q?Buero_Uebergabe=2Epdf?=")) NIL NIL)'
b' "MIXED" ("BOUNDARY" "b") NIL NIL NIL)'
)
return "OK", [(b"body", structure)]
if "BODY.PEEK[1]" in spec:
return "OK", [(b"part", b"gleicher text")]
if "BODY.PEEK[2]" in spec:
return "OK", [(b"part", b"nicht text")]
header = (
b"From: Ada <ada@example.test>\r\nTo: Ben <ben@example.test>\r\n"
b"Subject: Grenze\r\nDate: Thu, 02 May 2024 08:00:00 +0000\r\n"
)
return "OK", [(b"body", header), b")"]
def logout(self):
return "BYE", [b""]
def test_preview_below_and_above_the_limit_uses_the_same_parts(client, db, monkeypatch):
payload = b"%PDF-plan"
small = _multipart("gleicher text", "Buero Uebergabe.pdf", payload)
LimitIMAP.raw = small + b"X" * 50
monkeypatch.setattr(sources, "PREVIEW_BYTE_LIMIT", len(small))
monkeypatch.setattr(sources.imaplib, "IMAP4_SSL", LimitIMAP)
ada = Actor(client, "ada-limit@example.test", "Ada Grenze")
register(db, ada.email, ada.name)
ada.login()
account = ada.request(
"POST",
"/api/v1/connectors",
json={
"kind": "imap",
"name": "Post",
"host": "imap.example.test",
"port": 993,
"username": "ada@example.test",
"password": "Postfach-Geheim",
"security": "ssl",
},
status=201,
)
under = ada.request(
"GET",
"/api/v1/sources/imap/message",
params={"connector_id": account["id"], "mailbox": "INBOX", "uid": 1},
)
LimitIMAP.raw = small + b"Y"
over = ada.request(
"GET",
"/api/v1/sources/imap/message",
params={"connector_id": account["id"], "mailbox": "INBOX", "uid": 1},
)
assert "gleicher text" in under["text"]
assert "gleicher text" in over["text"]
assert under["attachments"][0]["filename"] == "Buero Uebergabe.pdf"
assert over["attachments"][0]["filename"] == "Buero Uebergabe.pdf"
assert "Content-Transfer-Encoding" not in over["text"]
assert "BASE64" not in over["text"].upper()
assert over["preview_limited"] is True
def test_upload_and_mail_fetch_leave_the_domain_transaction(client, db, monkeypatch):
seen = []
import app.api.routes as routes
import app.ops as ops
from app.media.port import publish as real_publish
def watching(adapter, key, data):
seen.append(("publish", ops_conn[0].info.transaction_status))
return real_publish(adapter, key, data)
ops_conn = [None]
real_create = ops.create_file
def wrapped_create(conn, *args, **kwargs):
ops_conn[0] = conn
return real_create(conn, *args, **kwargs)
monkeypatch.setattr(ops, "publish", watching)
monkeypatch.setattr(routes, "create_file", wrapped_create)
ada = Actor(client, "ada-idle@example.test", "Ada Leerlauf")
register(db, ada.email, ada.name)
ada.login()
case = ada.request("POST", "/api/v1/cases", json={"title": "Ablage"}, status=201)
ada.request(
"POST",
"/api/v1/files",
data={"title": "Scan", "context_kind": "case", "context_id": case["id"]},
files={"upload": ("scan.pdf", b"%PDF-1.4\n", "application/pdf")},
status=201,
)
assert seen[0][1] == psycopg.pq.TransactionStatus.IDLE
import app.sourceaccess as sourceaccess
phase = {"external": False, "status": None}
real_release = sourceaccess.release_for_external
def spy_release(conn):
real_release(conn)
phase["external"] = True
phase["status"] = conn.info.transaction_status
def spy_owned(*args, **kwargs):
if phase["external"]:
raise AssertionError("Datenbankzugriff im externen Abschnitt")
return real_owned(*args, **kwargs)
def spy_pull(*args, **kwargs):
assert phase["status"] == psycopg.pq.TransactionStatus.IDLE
return _multipart("brief", "a.pdf", b"%PDF")
real_owned = sources._owned
monkeypatch.setattr(sourceaccess, "release_for_external", spy_release)
monkeypatch.setattr(sources, "_owned", spy_owned)
monkeypatch.setattr(sources, "pull_rfc822", spy_pull)
monkeypatch.setattr(sources.imaplib, "IMAP4_SSL", QuotedIMAP)
account = ada.request(
"POST",
"/api/v1/connectors",
json={
"kind": "imap",
"name": "Post",
"host": "imap.example.test",
"port": 993,
"username": "ada@example.test",
"password": "Postfach-Geheim",
"security": "ssl",
},
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": "imap",
"external_id": "<grenze@example.test>",
"context": {"kind": "matter", "id": matter["id"]},
"detail": {"connector_id": account["id"], "mailbox": "Sent Items", "uid": 4},
},
status=201,
)
opened = ada.request("GET", f"/api/v1/external-refs/{linked['id']}/mail")
assert opened["text"]
assert phase["status"] == psycopg.pq.TransactionStatus.IDLE
def test_failed_conclusion_keeps_no_partial_file(client, db, monkeypatch):
import app.ops as ops
def fail(*args, **kwargs):
raise unprocessable("Abschluss fehlgeschlagen")
monkeypatch.setattr(ops, "_new_element", fail)
ada = Actor(client, "ada-fail@example.test", "Ada Abschluss")
register(db, ada.email, ada.name)
ada.login()
case = ada.request("POST", "/api/v1/cases", json={"title": "Ablage"}, status=201)
ada.request(
"POST",
"/api/v1/files",
data={"title": "Scan", "context_kind": "case", "context_id": case["id"]},
files={"upload": ("scan.pdf", b"%PDF-FAIL-CONCLUSION\n", "application/pdf")},
status=422,
)
stored = db.execute("SELECT count(*) AS n FROM elements WHERE title = 'Scan'").fetchone()
assert stored["n"] == 0
from pathlib import Path
from app.core.settings import get_settings
root = Path(get_settings().media_root)
left = [path for path in root.rglob("*") if path.is_file() and b"PDF-FAIL-CONCLUSION" in path.read_bytes()]
assert left == []
def test_paperless_filters_change_the_hits(client, db, monkeypatch):
catalog = []
for number in range(1, 46):
catalog.append({
"id": number,
"title": "Vertrag" if number % 5 == 0 else f"Schrift {number}",
"content": "nurinhalt" if number == 41 else f"text {number}",
"correspondent": 4 if number % 2 == 0 else 9,
"document_type": 8 if number < 30 else 1,
"tags": [2, 5] if number % 3 == 0 else [2],
"created": "2024-06-01" if number > 20 else "2023-01-01",
})
def fake_get(base, token, path, params):
if path != "/api/documents/":
return {"count": 1, "results": [{"id": 4, "name": "Haus"}]}
matched = []
for item in catalog:
query = params.get("query") or ""
title = params.get("title__icontains") or ""
if query and query.casefold() not in f"{item['title']} {item['content']}".casefold():
continue
if title and title.casefold() not in item["title"].casefold():
continue
if params.get("correspondent__id") and str(item["correspondent"]) != params["correspondent__id"]:
continue
if params.get("document_type__id") and str(item["document_type"]) != params["document_type__id"]:
continue
if params.get("tags__id__all"):
needed = {int(part) for part in params["tags__id__all"].split(",") if part}
if not needed.issubset(set(item["tags"])):
continue
start = params.get("created__date__gte")
end = params.get("created__date__lte")
if start and item["created"] < start:
continue
if end and item["created"] > end:
continue
matched.append(item)
page = int(params.get("page") or 1)
start_at = (page - 1) * 20
rows = matched[start_at:start_at + 20]
return {
"count": len(matched),
"results": [{"id": item["id"], "title": item["title"], "created": item["created"]} for item in rows],
}
monkeypatch.setattr(sources, "_paperless_get", fake_get)
ada = Actor(client, "ada-sense@example.test", "Ada Sinn")
register(db, ada.email, ada.name)
ada.login()
account = ada.request(
"POST",
"/api/v1/connectors",
json={"kind": "paperless", "name": "Archiv", "base_url": "https://paper.example.test", "token": "token-alpha"},
status=201,
)
content = ada.request(
"GET",
"/api/v1/sources/paperless/documents",
params={"connector_id": account["id"], "q": "nurinhalt"},
)
assert [item["id"] for item in content["items"]] == ["41"]
title = ada.request(
"GET",
"/api/v1/sources/paperless/documents",
params={"connector_id": account["id"], "title": "Vertrag"},
)
assert title["items"]
assert all("Vertrag" in item["title"] for item in title["items"])
assert all(item["id"] != "41" for item in title["items"])
combined = ada.request(
"GET",
"/api/v1/sources/paperless/documents",
params={
"connector_id": account["id"],
"correspondent": "4",
"document_type": "8",
"tag": "2,5",
"document_from": "2023-01-01",
"document_to": "2024-12-31",
},
)
plain = ada.request(
"GET",
"/api/v1/sources/paperless/documents",
params={"connector_id": account["id"], "cursor": "2"},
)
assert [item["id"] for item in combined["items"]] == ["6", "12", "18", "24"]
assert [item["id"] for item in plain["items"]][0] == "21"
+1 -1
View File
@@ -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()
+7 -7
View File
@@ -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("<stored@example.test>", "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("<offen@example.test>", "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("<andere@example.test>", "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]
+273
View File
@@ -0,0 +1,273 @@
"""Bibliothek: Zähler nur aus Lesbarem, Rauminhalt, Raumübersicht und Teilen im Stapel."""
from __future__ import annotations
import pytest
from fastapi.testclient import TestClient
from app.auth.accounts import create_account
from tests.support import PASSWORD, Actor, matter_of
def _second_client():
from app.main import app
return TestClient(app)
def _actor(client, db, key: str, *, main: bool = False) -> Actor:
actor = Actor(client if main else _second_client(), f"{key}-bib@example.test", key.title())
create_account(db, actor.email, actor.name, PASSWORD)
db.commit()
actor.login()
return actor
@pytest.fixture
def world(client, db):
ada = _actor(client, db, "ada", main=True)
ben = _actor(client, db, "ben")
cem = _actor(client, db, "cem")
dan = _actor(client, db, "dan")
room = ada.request("POST", "/api/v1/rooms", json={"name": "Werkstatt", "default_visibility": "private"}, status=201)["id"]
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": ben.email, "role": "member"})
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": cem.email, "role": "reader"})
return {"ada": ada, "ben": ben, "cem": cem, "dan": dan, "room": room}
def _share(actor, plural, resource_id, room, status=200):
return actor.request("PUT", f"/api/v1/{plural}/{resource_id}/room-share/rooms/{room}", json={"access": "edit"}, status=status)
def _link(actor, matter, case):
actor.request("POST", f"/api/v1/matters/{matter}/case-links", json={"case_id": case}, status=201)
def test_counts_include_only_what_the_person_may_read(world):
ada, ben, room = world["ada"], world["ben"], world["room"]
case = ada.request("POST", "/api/v1/cases", json={"title": "Vermietung"}, status=201)
child = ada.request(
"POST", "/api/v1/cases",
json={"title": "Nebenkosten", "parent_case_id": case["id"], "rights_mode": "inherit_parent"}, status=201,
)
one = matter_of(ada, "Mietminderung")
two = matter_of(ada, "Eigenbedarf intern")
_link(ada, one["id"], case["id"])
_link(ada, two["id"], case["id"])
_share(ada, "cases", case["id"], room)
mine = next(i for i in ada.request("GET", "/api/v1/cases")["items"] if i["id"] == case["id"])
assert (mine["child_cases"], mine["matter_count"]) == (1, 2)
assert [s["name"] for s in mine["shared_with"]] == ["Werkstatt"]
# One matter is withheld from the room members in this case.
ada.request(
"PUT", "/api/v1/exceptions",
json={"resource_kind": "matter", "resource_id": two["id"], "context": {"kind": "case", "id": case["id"]}, "remove_read": True},
)
seen = next(i for i in ben.request("GET", "/api/v1/cases")["items"] if i["id"] == case["id"])
assert seen["matter_count"] == 1 and seen["shared_with"] == [] and seen["is_owner"] is False
assert child["title"] == "Nebenkosten"
def test_a_room_shows_its_contents_to_members_only(world):
ada, ben, cem, dan, room = world["ada"], world["ben"], world["cem"], world["dan"], world["room"]
case = ada.request("POST", "/api/v1/cases", json={"title": "Im Raum"}, status=201)
sub = ada.request(
"POST", "/api/v1/cases",
json={"title": "Unter der Akte", "parent_case_id": case["id"], "rights_mode": "inherit_parent"}, status=201,
)
ada.request("POST", "/api/v1/cases", json={"title": "Bleibt privat"}, status=201)
matter = matter_of(ada, "Vorgang im Raum")
_share(ada, "cases", case["id"], room)
_share(ada, "matters", matter["id"], room)
for member in (ada, ben, cem):
found = member.request("GET", f"/api/v1/rooms/{room}/contents")
assert {c["title"] for c in found["cases"]} == {"Im Raum", "Unter der Akte"}
assert [m["title"] for m in found["matters"]] == ["Vorgang im Raum"]
dan.request("GET", f"/api/v1/rooms/{room}/contents", status=403)
# A person who is excluded does not see the entry in the room either.
ada.request("PUT", f"/api/v1/cases/{case['id']}/room-share/people/{_id(ada, ben)}", json={"excluded": True})
titles = {c["title"] for c in ben.request("GET", f"/api/v1/rooms/{room}/contents")["cases"]}
assert "Im Raum" not in titles
assert sub["title"] == "Unter der Akte"
def test_the_room_overview_names_members_only_to_managers(world):
ada, ben, room = world["ada"], world["ben"], world["room"]
case = ada.request("POST", "/api/v1/cases", json={"title": "Gezählt"}, status=201)
_share(ada, "cases", case["id"], room)
mine = next(r for r in ada.request("GET", "/api/v1/rooms/overview")["items"] if r["id"] == room)
assert mine["is_owner"] is True and mine["role"] == "manager" and mine["member_count"] == 3
assert mine["case_count"] == 1 and mine["matter_count"] == 0
assert set(mine["members"]) == {"Ada", "Ben", "Cem"}
theirs = next(r for r in ben.request("GET", "/api/v1/rooms/overview")["items"] if r["id"] == room)
assert theirs["members"] == [] and theirs["member_count"] == 3 and theirs["is_owner"] is False
assert world["dan"].request("GET", "/api/v1/rooms/overview")["items"] == []
def test_several_entries_are_shared_at_once_or_not_at_all(world):
ada, ben, room = world["ada"], world["ben"], world["room"]
a = ada.request("POST", "/api/v1/cases", json={"title": "Eins"}, status=201)
b = ada.request("POST", "/api/v1/cases", json={"title": "Zwei"}, status=201)
m = matter_of(ada, "Drei")
done = ada.request(
"POST", f"/api/v1/rooms/{room}/shares",
json={"items": [{"kind": "case", "id": a["id"]}, {"kind": "case", "id": b["id"]}, {"kind": "matter", "id": m["id"]}], "access": "read"},
)
assert done["shared"] == 3
assert {(e["display_name"], e["role"], e["rights"]["edit"]) for e in done["effect"]} == {("Ben", "member", False), ("Cem", "reader", False)}
assert ben.request("GET", f"/api/v1/cases/{a['id']}")["rights"]["edit"] is False
foreign = ben.request("POST", "/api/v1/cases", json={"title": "Von Ben"}, status=201)
c = ada.request("POST", "/api/v1/cases", json={"title": "Vier"}, status=201)
ada.request(
"POST", f"/api/v1/rooms/{room}/shares",
json={"items": [{"kind": "case", "id": c["id"]}, {"kind": "case", "id": foreign["id"]}]}, status=404,
)
assert room not in [s["room_id"] for s in ada.request("GET", f"/api/v1/cases/{c['id']}/room-share")["shares"]]
# An outsider cannot put his own entry into the room, and nobody shares an entry of someone else.
own = world["dan"].request("POST", "/api/v1/cases", json={"title": "Von Dan"}, status=201)
world["dan"].request("POST", f"/api/v1/rooms/{room}/shares", json={"items": [{"kind": "case", "id": own["id"]}]}, status=403)
world["cem"].request("POST", f"/api/v1/rooms/{room}/shares", json={"items": [{"kind": "case", "id": c["id"]}]}, status=404)
def test_creating_an_entry_can_put_it_into_a_room_and_reports_the_effect(world):
ada, ben, room = world["ada"], world["ben"], world["room"]
case = ada.request("POST", "/api/v1/cases", json={"title": "Gleich im Raum", "share_with_room_id": room}, status=201)
matter = ada.request("POST", "/api/v1/matters", json={"title": "Vorgang im Raum", "share_with_room_id": room}, status=201)
ben.request("GET", f"/api/v1/cases/{case['id']}")
ben.request("GET", f"/api/v1/matters/{matter['id']}")
other = ada.request("POST", "/api/v1/cases", json={"title": "Ohne Raum"}, status=201)
ben.request("GET", f"/api/v1/cases/{other['id']}", status=404)
answer = _share(ada, "cases", other["id"], room)
assert {e["display_name"] for e in answer["effect"]} == {"Ben", "Cem"}
world["dan"].request("POST", "/api/v1/cases", json={"title": "Fremd", "share_with_room_id": room}, status=403)
def _id(owner: Actor, person: Actor) -> str:
from app.core.settings import get_settings
import psycopg
with psycopg.connect(get_settings().dsn(), row_factory=psycopg.rows.dict_row) as conn:
return str(conn.execute("SELECT id FROM auth_accounts WHERE email = %s", (person.email,)).fetchone()["id"])
def test_the_outline_lists_only_what_the_person_may_read(world):
ada, ben, cem, dan, room = world["ada"], world["ben"], world["cem"], world["dan"], world["room"]
case = ada.request("POST", "/api/v1/cases", json={"title": "Gliederung"}, status=201)
ada.request("POST", f"/api/v1/cases/{case['id']}/chapters", json={"title": "Schriftverkehr"}, status=201)
sub = ada.request(
"POST", "/api/v1/cases",
json={"title": "Unterakte", "parent_case_id": case["id"], "rights_mode": "inherit_parent"}, status=201,
)
open_matter = matter_of(ada, "Offener Vorgang")
hidden_matter = matter_of(ada, "Verborgener Vorgang")
child = ada.request("POST", "/api/v1/matters", json={"title": "Teilvorgang", "parent_matter_id": open_matter["id"]}, status=201)
ada.request("POST", f"/api/v1/matters/{open_matter['id']}/chapters", json={"title": "Belege"}, status=201)
_link(ada, open_matter["id"], case["id"])
_link(ada, hidden_matter["id"], case["id"])
_share(ada, "cases", case["id"], room)
ada.request(
"PUT", "/api/v1/exceptions",
json={"resource_kind": "matter", "resource_id": hidden_matter["id"], "context": {"kind": "case", "id": case["id"]}, "remove_read": True},
)
mine = ada.request("GET", f"/api/v1/cases/{case['id']}/outline")
assert [c["title"] for c in mine["chapters"]] == ["Schriftverkehr"]
assert [c["title"] for c in mine["subcases"]] == ["Unterakte"]
# An exception in the case context hides the matter there for everyone, the owner included.
assert {m["title"] for m in mine["matters"]} == {"Offener Vorgang"}
seen = ben.request("GET", f"/api/v1/cases/{case['id']}/outline")
assert {m["title"] for m in seen["matters"]} == {"Offener Vorgang"}
assert [c["title"] for c in seen["matters"][0]["children"]] == ["Teilvorgang"]
assert sub["id"] in [c["id"] for c in seen["subcases"]]
matter = ada.request("GET", f"/api/v1/matters/{open_matter['id']}/outline")
assert [c["title"] for c in matter["chapters"]] == ["Belege"]
assert [c["title"] for c in matter["submatters"]] == ["Teilvorgang"]
in_case = ben.request(
"GET", f"/api/v1/matters/{open_matter['id']}/outline",
params={"context_kind": "case", "context_id": case["id"]},
)
assert [c["title"] for c in in_case["submatters"]] == ["Teilvorgang"]
ben.request("GET", f"/api/v1/matters/{open_matter['id']}/outline", status=404)
assert child["title"] == "Teilvorgang"
unknown = "00000000-0000-4000-8000-000000000000"
seen_status = dan.request("GET", f"/api/v1/cases/{case['id']}/outline", status=404)
missing = dan.request("GET", f"/api/v1/cases/{unknown}/outline", status=404)
assert seen_status["detail"] == missing["detail"]
dan.request("GET", f"/api/v1/matters/{open_matter['id']}/outline", status=404)
assert cem.request("GET", f"/api/v1/cases/{case['id']}/outline")["id"] == case["id"]
def test_unlinking_keeps_the_matter_and_its_other_cases(world):
ada, ben = world["ada"], world["ben"]
first = ada.request("POST", "/api/v1/cases", json={"title": "Vermietung"}, status=201)["id"]
second = ada.request("POST", "/api/v1/cases", json={"title": "Steuer"}, status=201)["id"]
matter = matter_of(ada, "Nebenkosten")["id"]
ada.request("POST", f"/api/v1/matters/{matter}/case-links", json={"case_id": first}, status=201)
ada.request("POST", f"/api/v1/matters/{matter}/case-links", json={"case_id": second}, status=201)
links = ada.request("GET", f"/api/v1/matters/{matter}")["case_links"]
assert {item["case_id"] for item in links} == {first, second}
link = next(item for item in links if item["case_id"] == first)
# A stranger cannot detach it and learns nothing about it.
ben.request("DELETE", f"/api/v1/matter-case-links/{link['id']}", status=404)
ada.request("DELETE", f"/api/v1/matter-case-links/{link['id']}", status=204)
opened = ada.request("GET", f"/api/v1/matters/{matter}")
assert [item["case_id"] for item in opened["case_links"]] == [second]
assert opened["title"] == "Nebenkosten"
assert matter in {item["id"] for item in ada.request("GET", "/api/v1/matters")["items"]}
ada.request("DELETE", f"/api/v1/matter-case-links/{link['id']}", status=404)
def test_download_policy_follows_the_room_role(world):
ada, ben, cem, dan, room = world["ada"], world["ben"], world["cem"], world["dan"], world["room"]
matter = matter_of(ada, "Nebenkosten")["id"]
file = ada.request(
"POST",
"/api/v1/files",
data={"title": "Vertrag", "context_kind": "matter", "context_id": matter},
files={"upload": ("vertrag.pdf", b"%PDF-1.4\n1 0 obj<<>>endobj\ntrailer<<>>\n%%EOF\n", "application/pdf")},
status=201,
)["id"]
_share(ada, "matters", matter, room)
path = f"/api/v1/files/{file}/content"
query = {"context_kind": "matter", "context_id": matter}
def fetch(person, **extra):
from tests.support import ORIGIN
headers = {"Origin": ORIGIN, "X-CSRF-Token": person.csrf}
if person.scope is not None:
headers["X-Scope-Kind"], headers["X-Scope-Id"] = person.scope["kind"], person.scope["id"]
return person.client.get(path, params={**query, **extra}, headers=headers)
# By default every role may save the original.
for person in (ben, cem):
assert fetch(person, save="true").status_code == 200
seen = ben.request("GET", f"/api/v1/matters/{matter}")
assert seen["rights"]["download"] is True
# The owner turns it off for readers. Reading stays possible, saving does not.
assert cem.request("GET", f"/api/v1/rooms/{room}/download-policy")["can_change"] is False
cem.request("PUT", f"/api/v1/rooms/{room}/download-policy", json={"manager": True, "member": True, "reader": False}, status=403)
ada.request("PUT", f"/api/v1/rooms/{room}/download-policy", json={"manager": True, "member": True, "reader": False})
assert fetch(cem).status_code == 200
refused = fetch(cem, save="true")
assert refused.status_code == 403
assert "freigegeben" in refused.json()["detail"]
assert cem.request("GET", f"/api/v1/matters/{matter}")["rights"]["download"] is False
assert fetch(ben, save="true").status_code == 200
# A stranger learns nothing about the policy of the room.
dan.request("GET", f"/api/v1/rooms/{room}/download-policy", status=404)
# The owner's default is copied into a new room.
ada.request("PUT", "/api/v1/auth/download-defaults", json={"manager": True, "member": False, "reader": False, "direct": True})
fresh = ada.request("POST", "/api/v1/rooms", json={"name": "Neu", "default_visibility": "private"}, status=201)["id"]
assert ada.request("GET", f"/api/v1/rooms/{fresh}/download-policy")["roles"] == {"manager": True, "member": False, "reader": False}
assert ada.request("GET", f"/api/v1/rooms/{room}/download-policy")["roles"]["member"] is True
+81
View File
@@ -0,0 +1,81 @@
"""HTML mail: formatting stays, everything active or loading from outside is removed."""
from __future__ import annotations
from app.mailpack import sanitize_html
def test_formatting_stays_and_active_content_goes():
cleaned = sanitize_html(
'<div style="color:#333;font-size:14px" onclick="steal()"><font color="red" size="3">Hallo</font>'
'<table bgcolor="#eee" width="100%"><tr><td align="center">x</td></tr></table><hr>'
'<script>alert(1)</script><iframe src="http://x"></iframe><form action="http://x"><input></form></div>'
)
assert 'style="color: #333; font-size: 14px"' in cleaned
assert '<font color="red" size="3">' in cleaned
assert 'bgcolor="#eee"' in cleaned and "<hr>" in cleaned
for forbidden in ("onclick", "script", "iframe", "<form", "<input", "alert"):
assert forbidden not in cleaned
def test_styles_cannot_load_or_position():
cleaned = sanitize_html(
'<p style="background:url(http://track/p.png);position:fixed;width:expression(alert(1));'
'color:red;behavior:url(x.htc);margin:4px">Text</p>'
)
assert "url" not in cleaned and "position" not in cleaned and "expression" not in cleaned and "behavior" not in cleaned
assert "color: red" in cleaned and "margin: 4px" in cleaned
def test_links_and_images_are_limited():
cleaned = sanitize_html(
'<a href="javascript:alert(1)">a</a><a href="https://ok.example/x">b</a><a href="data:text/html,x">c</a>'
'<img src="http://track/p.gif"><img src="data:image/png;base64,AAAA" alt="logo"><img src="data:image/svg+xml;base64,AAAA">'
)
assert "javascript" not in cleaned and "data:text" not in cleaned and "track" not in cleaned and "svg" not in cleaned
assert 'href="https://ok.example/x"' in cleaned
assert 'rel="noreferrer noopener"' in cleaned and 'target="_blank"' in cleaned
assert 'src="data:image/png;base64,AAAA"' in cleaned
def test_remote_pictures_stay_out_unless_the_server_loads_them():
source = '<img src="https://cdn.example/a.png" alt="a"><img src="http://plain.example/b.png"><p>Text</p>'
found: list[str] = []
assert "<img" not in sanitize_html(source, found=found)
assert found == ["https://cdn.example/a.png"]
loaded = sanitize_html(source, remote=lambda url: "data:image/png;base64,AAAA" if "cdn" in url else "")
assert loaded.count("<img") == 1 and 'src="data:image/png;base64,AAAA"' in loaded
def test_the_server_never_fetches_internal_or_odd_addresses():
from app.remoteimages import RemoteImages, fetch_image, is_public
for address in ("127.0.0.1", "10.0.0.5", "192.168.1.1", "169.254.169.254", "::1", "fd00::1", "224.0.0.1", "not-an-ip"):
assert is_public(address) is False
assert is_public("93.184.216.34") is True
for url in (
"http://example.org/a.png",
"https://127.0.0.1/a.png",
"https://localhost/a.png",
"https://[::1]/a.png",
"https://example.org:8443/a.png",
"https://user:pw@example.org/a.png",
"file:///etc/passwd",
"https:///a.png",
):
assert fetch_image(url) is None
assert RemoteImages()("https://127.0.0.1/a.png") == ""
def test_remote_pictures_are_checked_by_content_and_limited(monkeypatch):
import app.remoteimages as module
png = b"\x89PNG\r\n\x1a\n" + b"0" * 20
monkeypatch.setattr(module, "fetch_image", lambda url: png if url.endswith(".png") else None)
loader = module.RemoteImages()
assert loader("https://a.example/1.png").startswith("data:image/png;base64,")
assert loader("https://a.example/1.png").startswith("data:image/png")
assert loader("https://a.example/1.svg") == ""
assert (loader.loaded, loader.failed) == (1, 1)
assert module._kind(b"<svg xmlns='http://www.w3.org/2000/svg'></svg>") is None
assert module._kind(b"RIFF\x00\x00\x00\x00WEBPVP8 ") == "webp"
+197 -2
View File
@@ -180,9 +180,12 @@ def test_foreign_mailbox_stays_hidden(client, db, monkeypatch):
class HugeIMAP(FakeIMAP):
def uid(self, command, *args):
spec = " ".join(str(part) for part in args[1:]) if len(args) > 1 else ""
if command == "FETCH" and "BODY.PEEK[]" in spec:
if command == "FETCH" and "BODY.PEEK[]" in spec and "<" not in spec:
return "OK", [(b"rfc822", b"x" * 8_000_001)]
if "BODY.PEEK[TEXT]" in spec:
if "BODYSTRUCTURE" in spec:
structure = b'("TEXT" "PLAIN" ("CHARSET" "utf-8") NIL NIL "7BIT" 40 1 NIL NIL NIL NIL)'
return "OK", [(b"body", structure)]
if "BODY.PEEK[1]" in spec:
return "OK", [(b"text", "Kurzer Auszug der grossen Nachricht.".encode())]
return super().uid(command, *args)
@@ -282,3 +285,195 @@ def test_an_adopted_message_loads_in_full_with_its_attachment(client, db, monkey
ada.request("GET", f"/api/v1/external-refs/{wrong['element']['id']}/mail", status=422)
ben.login()
ben.request("GET", f"/api/v1/external-refs/{created['id']}/mail", status=404)
def _letter(message_id: str, body: str) -> bytes:
return (
f"From: Ada Beispiel <ada@example.test>\r\n"
f"To: Gegenseite <gegen@example.test>\r\n"
f"Subject: Verschoben\r\n"
f"Date: Thu, 02 May 2024 08:00:00 +0000\r\n"
f"Message-ID: {message_id}\r\n"
f"MIME-Version: 1.0\r\n"
f"Content-Type: text/plain; charset=utf-8\r\n"
f"\r\n"
f"{body}\r\n"
).encode()
class RelocatingIMAP:
"""The saved UID holds another message. The Message-ID lives in Archiv."""
log: list[tuple] = []
copies: dict[tuple[str, int], bytes] = {}
header_uids: dict[str, bytes] | None = None
def __init__(self, *args, **kwargs):
self.selected = ""
def login(self, username, secret):
assert secret == "Postfach-Geheim"
return "OK", [b"logged"]
def list(self):
return "OK", [
b'(\\HasNoChildren) "/" "INBOX"',
b'(\\HasNoChildren) "/" "Archiv"',
]
def select(self, mailbox, readonly=False):
assert readonly is True
self.selected = mailbox
RelocatingIMAP.log.append(("select", mailbox))
return "OK", [b"2"]
def uid(self, command, *args):
if command == "SEARCH":
if args and args[0] == "HEADER":
RelocatingIMAP.log.append(("header", self.selected))
override = (RelocatingIMAP.header_uids or {}).get(self.selected)
if override is not None:
return "OK", [override]
found = [
str(uid)
for (folder, uid), raw in RelocatingIMAP.copies.items()
if folder == self.selected and b"Message-ID: <moved@example.test>" in raw
]
return "OK", [" ".join(found).encode()]
return "OK", [b""]
uid = int(args[0])
spec = " ".join(str(part) for part in args[1:])
if "BODY.PEEK[]" in spec:
RelocatingIMAP.log.append(("fetch", self.selected, uid))
raw = RelocatingIMAP.copies.get((self.selected, uid))
if raw is None:
return "OK", [None]
return "OK", [(b"rfc822", raw)]
return "OK", [None]
def logout(self):
return "BYE", [b""]
def _stored_mail(db, element_id: str) -> dict:
row = db.execute(
"SELECT detail FROM external_references WHERE element_id = %s",
(element_id,),
).fetchone()
return dict(row["detail"])
def _linked_mail(actor: Actor, account: str, matter_id: str) -> dict:
return actor.request(
"POST",
"/api/v1/external-refs",
json={
"title": "Verschoben",
"source": "imap",
"external_id": "<moved@example.test>",
"context": {"kind": "matter", "id": matter_id},
"detail": {
"connector_id": account,
"mailbox": "INBOX",
"uid": 2,
"direction": "in",
},
},
status=201,
)
def test_a_moved_message_remembers_its_new_folder(client, db, monkeypatch):
from uuid import UUID
from app.retrieval import MailPayload, load_external
ada = Actor(client, "ada-move@example.test", "Ada Umzug")
account_row = register(db, ada.email, ada.name)
ada.login()
RelocatingIMAP.log = []
RelocatingIMAP.header_uids = None
RelocatingIMAP.copies = {
("INBOX", 2): _letter("<other@example.test>", "Eine andere Nachricht."),
("Archiv", 9): _letter("<moved@example.test>", "Der Brief liegt jetzt im Archiv."),
}
account = _account(monkeypatch, ada)
monkeypatch.setattr(sources.imaplib, "IMAP4_SSL", RelocatingIMAP)
matter = matter_of(ada, "Ablage")
created = _linked_mail(ada, account, matter["id"])
opened = ada.request("GET", f"/api/v1/external-refs/{created['id']}/mail")
assert "Archiv" in opened["text"]
stored = _stored_mail(db, created["id"])
assert stored["mailbox"] == "Archiv"
assert stored["uid"] == 9
assert stored["direction"] == "in"
assert stored["connector_id"] == account
assert any(item[0] == "header" for item in RelocatingIMAP.log)
RelocatingIMAP.log = []
again = ada.request("GET", f"/api/v1/external-refs/{created['id']}/mail")
assert again["text"] == opened["text"]
assert ("fetch", "Archiv", 9) in RelocatingIMAP.log
assert not any(item[0] == "header" for item in RelocatingIMAP.log)
assert _stored_mail(db, created["id"])["uid"] == 9
db.execute(
"""
UPDATE external_references
SET detail = jsonb_set(
jsonb_set(detail, '{mailbox}', to_jsonb('INBOX'::text)),
'{uid}',
to_jsonb(2)
)
WHERE element_id = %s
""",
(created["id"],),
)
db.commit()
RelocatingIMAP.log = []
loaded = load_external(db, account_row["id"], UUID(created["id"]), None)
assert isinstance(loaded, MailPayload)
assert "Archiv" in loaded.parsed.text
exported = _stored_mail(db, created["id"])
assert exported["mailbox"] == "Archiv"
assert exported["uid"] == 9
assert exported["direction"] == "in"
assert any(item[0] == "header" for item in RelocatingIMAP.log)
def test_an_ambiguous_or_truncated_move_does_not_replace_the_stored_place(client, db, monkeypatch):
ada = Actor(client, "ada-ambiguous@example.test", "Ada Zweifach")
register(db, ada.email, ada.name)
ada.login()
RelocatingIMAP.header_uids = None
RelocatingIMAP.copies = {
("INBOX", 2): _letter("<other@example.test>", "Altbestand."),
("INBOX", 4): _letter("<moved@example.test>", "Erste Kopie."),
("Archiv", 9): _letter("<moved@example.test>", "Zweite Kopie."),
}
account = _account(monkeypatch, ada)
monkeypatch.setattr(sources.imaplib, "IMAP4_SSL", RelocatingIMAP)
matter = matter_of(ada, "Zweifach")
created = _linked_mail(ada, account, matter["id"])
ada.request("GET", f"/api/v1/external-refs/{created['id']}/mail", status=422)
assert _stored_mail(db, created["id"])["mailbox"] == "INBOX"
assert _stored_mail(db, created["id"])["uid"] == 2
RelocatingIMAP.copies = {
("INBOX", 2): _letter("<other@example.test>", "Altbestand."),
("INBOX", 11): _letter("<moved@example.test>", "Treffer in der abgebrochenen Suche."),
("INBOX", 12): _letter("<a@example.test>", "a"),
("INBOX", 13): _letter("<b@example.test>", "b"),
("INBOX", 14): _letter("<c@example.test>", "c"),
("INBOX", 15): _letter("<d@example.test>", "d"),
("INBOX", 16): _letter("<e@example.test>", "e"),
("Archiv", 9): _letter("<moved@example.test>", "Eigentlich auch hier."),
}
RelocatingIMAP.header_uids = {"INBOX": b"11 12 13 14 15 16"}
RelocatingIMAP.log = []
opened = ada.request("GET", f"/api/v1/external-refs/{created['id']}/mail")
assert "abgebrochenen Suche" in opened["text"]
assert not any(item == ("header", "Archiv") for item in RelocatingIMAP.log)
assert _stored_mail(db, created["id"])["mailbox"] == "INBOX"
assert _stored_mail(db, created["id"])["uid"] == 2
+10
View File
@@ -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)
+1 -1
View File
@@ -14,7 +14,7 @@ def test_manager_does_not_read_a_personal_case(client, db):
ada = Actor(client, "ada@example.test", "Ada")
ada.login()
private = case_of(ada, "Persoenliche Akte")
room = ada.request("POST", "/api/v1/rooms", json={"name": "Haushalt"}, status=201)
room = ada.request("POST", "/api/v1/rooms", json={"name": "Haushalt", "default_visibility": "private"}, status=201)
ada.request("POST", f"/api/v1/rooms/{room['id']}/members", json={"email": "ben@example.test", "role": "manager"})
ben = Actor(client, "ben@example.test", "Ben")
ben.login()
+377
View File
@@ -0,0 +1,377 @@
"""Raum als Team: Akten und Vorgänge werden mit Datenräumen geteilt, unabhängig vom Heimatraum."""
from __future__ import annotations
import pytest
from fastapi.testclient import TestClient
from app.auth.accounts import create_account
from tests.support import PASSWORD, Actor, document, matter_of, note_on
def _second_client():
from app.main import app
return TestClient(app)
def _make(db, email: str, name: str):
account = create_account(db, email, name, PASSWORD)
db.commit()
return account
def _actor(client, db, key: str, email: str, *, main: bool = False) -> Actor:
actor = Actor(client if main else _second_client(), email, key.title())
_make(db, actor.email, actor.name)
actor.login()
return actor
def _id(db, email: str) -> str:
row = db.execute("SELECT id FROM auth_accounts WHERE email = %s", (email,)).fetchone()
db.rollback()
return str(row["id"])
def _share(actor: Actor, plural: str, resource_id: str, room: str, access: str = "edit", status: int = 200):
return actor.request("PUT", f"/api/v1/{plural}/{resource_id}/room-share/rooms/{room}", json={"access": access}, status=status)
def _unshare(actor: Actor, plural: str, resource_id: str, room: str, status: int = 204):
return actor.request("DELETE", f"/api/v1/{plural}/{resource_id}/room-share/rooms/{room}", status=status)
@pytest.fixture
def world(client, db):
"""Ada owns the room; Ben is a member, Cem a reader, Dan is outside."""
actors = {
"ada": _actor(client, db, "ada", "ada-raum@example.test", main=True),
"ben": _actor(client, db, "ben", "ben-raum@example.test"),
"cem": _actor(client, db, "cem", "cem-raum@example.test"),
"dan": _actor(client, db, "dan", "dan-raum@example.test"),
}
ada = actors["ada"]
room = ada.request("POST", "/api/v1/rooms", json={"name": "Werkstatt"}, status=201)
assert room["default_visibility"] == "room"
ada.request("POST", f"/api/v1/rooms/{room['id']}/members", json={"email": actors["ben"].email, "role": "member"})
ada.request("POST", f"/api/v1/rooms/{room['id']}/members", json={"email": actors["cem"].email, "role": "reader"})
ada.use_room(room["id"])
actors["room"] = room["id"]
return actors
def test_a_new_entry_follows_the_room_preset_and_rights_follow_the_role(world, db):
ada, ben, cem, dan, room = world["ada"], world["ben"], world["cem"], world["dan"], world["room"]
shared = ada.request("POST", "/api/v1/cases", json={"title": "Gemeinsame Akte"}, status=201)
view = ada.request("GET", f"/api/v1/cases/{shared['id']}/room-share")
assert [(s["room_name"], s["access"]) for s in view["shares"]] == [("Werkstatt", "edit")]
assert ben.request("GET", f"/api/v1/cases/{shared['id']}")["rights"] == {
"read": True, "edit": True, "share": False, "delete": False, "download": True,
}
assert cem.request("GET", f"/api/v1/cases/{shared['id']}")["rights"] == {
"read": True, "edit": False, "share": False, "delete": False, "download": True,
}
dan.request("GET", f"/api/v1/cases/{shared['id']}", status=404)
assert "Gemeinsame Akte" in {item["title"] for item in ben.request("GET", "/api/v1/cases")["items"]}
assert dan.request("GET", "/api/v1/cases")["items"] == []
version = ben.request("GET", f"/api/v1/cases/{shared['id']}")["version"]
ben.request("PATCH", f"/api/v1/cases/{shared['id']}", json={"expected_version": version, "title": "Von Ben geändert"})
cem.request("PATCH", f"/api/v1/cases/{shared['id']}", json={"expected_version": version + 1, "title": "Nein"}, status=403)
ben.request("POST", f"/api/v1/cases/{shared['id']}/delete", json={"expected_version": version + 1}, status=403)
ben.request("POST", f"/api/v1/cases/{shared['id']}/grants", json={"email": dan.email, "can_read": True}, status=403)
def test_unsharing_and_leaving_take_the_rights_back_at_once(world, db):
ada, ben, room = world["ada"], world["ben"], world["room"]
case = ada.request("POST", "/api/v1/cases", json={"title": "Zeitweise sichtbar"}, status=201)
ben.request("GET", f"/api/v1/cases/{case['id']}")
_unshare(ada, "cases", case["id"], room)
ben.request("GET", f"/api/v1/cases/{case['id']}", status=404)
_share(ada, "cases", case["id"], room)
ben.request("GET", f"/api/v1/cases/{case['id']}")
ada.request("DELETE", f"/api/v1/rooms/{room}/members/{_id(db, ben.email)}", status=204)
ben.request("GET", f"/api/v1/cases/{case['id']}", status=404)
assert ben.request("GET", "/api/v1/cases")["items"] == []
def test_an_archived_room_shares_nothing_until_it_is_restored(world, db):
ada, ben, room = world["ada"], world["ben"], world["room"]
case = ada.request("POST", "/api/v1/cases", json={"title": "Archivtest"}, status=201)
ben.request("GET", f"/api/v1/cases/{case['id']}")
db.execute("UPDATE data_rooms SET status = 'archived' WHERE id = %s", (room,))
db.commit()
ben.request("GET", f"/api/v1/cases/{case['id']}", status=404)
db.execute("UPDATE data_rooms SET status = 'active' WHERE id = %s", (room,))
db.commit()
ben.request("GET", f"/api/v1/cases/{case['id']}")
def test_the_owner_sees_all_own_entries_whatever_happens_to_the_room(world, db):
ada, ben, room = world["ada"], world["ben"], world["room"]
mine = ada.request("POST", "/api/v1/cases", json={"title": "Meine Akte im Raum"}, status=201)
personal = Actor(ada.client, ada.email, ada.name)
personal_body = personal.login()
personal.request("POST", "/api/v1/cases", json={"title": "Meine persönliche Akte"}, status=201)
# Ben owns an entry filed in the room; Ada, the owner of the room, does not see it.
ben.use_room(room)
bens = ben.request("POST", "/api/v1/cases", json={"title": "Bens Akte"}, status=201)
def titles(actor):
return {item["title"] for item in actor.request("GET", "/api/v1/cases")["items"]}
assert {"Meine Akte im Raum", "Meine persönliche Akte"} <= titles(personal)
assert "Bens Akte" in titles(personal) # shared with the room by the preset
_unshare(ben, "cases", bens["id"], room)
assert "Bens Akte" not in titles(personal)
assert "Bens Akte" in titles(ben)
# Ben leaves the room, the room is archived: he still sees and edits what he owns.
personal.request("DELETE", f"/api/v1/rooms/{room}/members/{_id(db, ben.email)}", status=204)
# Ben's old room headers no longer fit his session; he is told to reload, then lists everything he owns.
assert ben.request("GET", "/api/v1/cases", status=403)["code"] == "scope_changed"
body = ben.request("GET", "/api/v1/auth/session")
assert body["scope"]["kind"] == "personal"
ben.scope, ben.csrf = body["scope"], body["csrf_token"]
assert "Bens Akte" in titles(ben)
ben.request("GET", f"/api/v1/cases/{bens['id']}")
db.execute("UPDATE data_rooms SET status = 'archived' WHERE id = %s", (room,))
db.commit()
assert {"Meine Akte im Raum", "Meine persönliche Akte"} <= titles(personal)
personal.request("GET", f"/api/v1/cases/{mine['id']}")
assert personal_body["account"]["email"] == ada.email
def test_one_member_can_be_excluded(world, db):
ada, ben, cem, dan = world["ada"], world["ben"], world["cem"], world["dan"]
case = ada.request("POST", "/api/v1/cases", json={"title": "Ohne Ben"}, status=201)
view = ada.request("GET", f"/api/v1/cases/{case['id']}/room-share")
assert {(m["display_name"], m["role"]) for m in view["shares"][0]["members"]} == {("Ben", "member"), ("Cem", "reader")}
base = f"/api/v1/cases/{case['id']}/room-share/people"
ada.request("PUT", f"{base}/{_id(db, ben.email)}", json={"excluded": True})
ben.request("GET", f"/api/v1/cases/{case['id']}", status=404)
cem.request("GET", f"/api/v1/cases/{case['id']}")
assert any(m["excluded"] for m in ada.request("GET", f"/api/v1/cases/{case['id']}/room-share")["shares"][0]["members"])
ada.request("PUT", f"{base}/{_id(db, ben.email)}", json={"excluded": False})
ben.request("GET", f"/api/v1/cases/{case['id']}")
ada.request("PUT", f"{base}/{_id(db, ada.email)}", json={"excluded": True}, status=422)
ada.request("PUT", f"{base}/{_id(db, dan.email)}", json={"excluded": True}, status=404)
ben.request("PUT", f"{base}/{_id(db, cem.email)}", json={"excluded": True}, status=404)
def test_contents_follow_the_room_role(world, db):
ada, ben, cem, dan = world["ada"], world["ben"], world["cem"], world["dan"]
case = ada.request("POST", "/api/v1/cases", json={"title": "Akte mit Notiz"}, status=201)
note = note_on(ada, "Notiz in der Akte", "Raumtext", case["id"])
detail = ben.request("GET", f"/api/v1/cases/{case['id']}")
assert any(b["element"]["title"] == "Notiz in der Akte" for b in detail["bindings"])
context = {"kind": "case", "id": case["id"]}
ben.request("PATCH", f"/api/v1/notes/{note['id']}", json={"expected_version": note["version"], "document": document("Von Ben ergänzt"), "context": context})
cem.request("PATCH", f"/api/v1/notes/{note['id']}", json={"expected_version": note["version"] + 1, "document": document("Nein"), "context": context}, status=403)
dan.request("GET", f"/api/v1/cases/{case['id']}", status=404)
assert dan.request("GET", "/api/v1/search", params={"q": "Notiz in der Akte"})["items"] == []
assert any(i["title"] == "Notiz in der Akte" for i in cem.request("GET", "/api/v1/search", params={"q": "Notiz in der Akte"})["items"])
def test_a_standalone_matter_is_shared_like_a_case(world, db):
ada, ben, cem, room = world["ada"], world["ben"], world["cem"], world["room"]
matter = matter_of(ada, "Eigener Vorgang")
assert ben.request("GET", f"/api/v1/matters/{matter['id']}")["rights"]["edit"] is True
assert cem.request("GET", f"/api/v1/matters/{matter['id']}")["rights"] == {
"read": True, "edit": False, "share": False, "delete": False, "download": True,
}
ben.request("POST", f"/api/v1/matters/{matter['id']}/delete", json={"expected_version": matter["version"]}, status=403)
_unshare(ada, "matters", matter["id"], room)
ben.request("GET", f"/api/v1/matters/{matter['id']}", status=404)
assert "Eigener Vorgang" not in {item["title"] for item in ben.request("GET", "/api/v1/matters")["items"]}
def test_subcases_follow_their_parent(world, db):
ada, ben, room = world["ada"], world["ben"], world["room"]
parent = ada.request("POST", "/api/v1/cases", json={"title": "Eltern"}, status=201)
child = ada.request(
"POST", "/api/v1/cases",
json={"title": "Kind", "parent_case_id": parent["id"], "rights_mode": "inherit_parent"}, status=201,
)
ben.request("GET", f"/api/v1/cases/{child['id']}")
_unshare(ada, "cases", parent["id"], room)
_unshare(ada, "cases", child["id"], room)
ben.request("GET", f"/api/v1/cases/{child['id']}", status=404)
def test_an_entry_in_the_personal_room_can_be_shared_with_a_team(world, db):
ada, ben, dan, room = world["ada"], world["ben"], world["dan"], world["room"]
personal = Actor(ada.client, ada.email, ada.name)
personal.login()
case = personal.request("POST", "/api/v1/cases", json={"title": "Aus dem persönlichen Raum"}, status=201)
assert personal.request("GET", f"/api/v1/cases/{case['id']}/room-share")["shares"] == []
ben.request("GET", f"/api/v1/cases/{case['id']}", status=404)
shared = personal.request("GET", f"/api/v1/cases/{case['id']}/room-share")
assert [item["name"] for item in shared["available"]] == ["Werkstatt"]
_share(personal, "cases", case["id"], room)
ben.request("GET", f"/api/v1/cases/{case['id']}")
dan.request("GET", f"/api/v1/cases/{case['id']}", status=404)
def test_one_matter_goes_to_the_lawyer_and_the_rest_of_the_case_stays_hidden(client, db):
ada = _actor(client, db, "ada", "ada-anwalt@example.test", main=True)
lawyer = _actor(client, db, "anwalt", "anwalt@example.test")
team = ada.request("POST", "/api/v1/rooms", json={"name": "Anwalt Müller", "default_visibility": "private"}, status=201)
ada.request("POST", f"/api/v1/rooms/{team['id']}/members", json={"email": lawyer.email, "role": "member"})
case = ada.request("POST", "/api/v1/cases", json={"title": "Vermietung"}, status=201)
shared = ada.request("POST", "/api/v1/matters", json={"title": "Mietminderung"}, status=201)
hidden = ada.request("POST", "/api/v1/matters", json={"title": "Eigenbedarf intern"}, status=201)
for matter in (shared, hidden):
ada.request("POST", f"/api/v1/matters/{matter['id']}/case-links", json={"case_id": case["id"]}, status=201)
note_on(ada, "Schreiben des Mieters", "Minderung", case["id"])
_share(ada, "matters", shared["id"], team["id"], access="edit")
lawyer.request("GET", f"/api/v1/cases/{case['id']}", status=404)
assert lawyer.request("GET", "/api/v1/cases")["items"] == []
listed = {item["title"] for item in lawyer.request("GET", "/api/v1/matters")["items"]}
assert listed == {"Mietminderung"}
lawyer.request("GET", f"/api/v1/matters/{hidden['id']}", status=404)
assert lawyer.request("GET", f"/api/v1/matters/{shared['id']}")["rights"]["edit"] is True
def test_the_share_caps_the_role_and_several_rooms_add_up(world, db):
ada, ben, room = world["ada"], world["ben"], world["room"]
other = ada.request("POST", "/api/v1/rooms", json={"name": "Zweites Team", "default_visibility": "private"}, status=201)
ada.request("POST", f"/api/v1/rooms/{other['id']}/members", json={"email": ben.email, "role": "member"})
case = ada.request("POST", "/api/v1/cases", json={"title": "Begrenzt"}, status=201)
_share(ada, "cases", case["id"], room, access="read")
assert ben.request("GET", f"/api/v1/cases/{case['id']}")["rights"]["edit"] is False
_share(ada, "cases", case["id"], other["id"], access="edit")
assert ben.request("GET", f"/api/v1/cases/{case['id']}")["rights"]["edit"] is True
_unshare(ada, "cases", case["id"], other["id"])
assert ben.request("GET", f"/api/v1/cases/{case['id']}")["rights"]["edit"] is False
_unshare(ada, "cases", case["id"], other["id"], status=404)
def test_only_the_owner_shares_and_only_into_rooms_where_he_writes(world, db):
ada, ben, cem, dan, room = world["ada"], world["ben"], world["cem"], world["dan"], world["room"]
case = ada.request("POST", "/api/v1/cases", json={"title": "Nur Ada teilt"}, status=201)
ben.request("PUT", f"/api/v1/cases/{case['id']}/room-share/rooms/{room}", json={"access": "edit"}, status=404)
ben.request("DELETE", f"/api/v1/cases/{case['id']}/room-share/rooms/{room}", status=404)
bens = ben.request("GET", "/api/v1/auth/session") # Ben may share his own entries into rooms he writes in
assert any(r["id"] == room for r in bens["rooms"])
ben.use_room(room)
own = ben.request("POST", "/api/v1/cases", json={"title": "Bens"}, status=201)
# A reader may not share into the room; an outsider cannot even see it.
cem.use_room(room)
cem_own = Actor(cem.client, cem.email, cem.name)
cem_own.login()
mine = cem_own.request("POST", "/api/v1/cases", json={"title": "Von Cem"}, status=201)
cem_own.request("PUT", f"/api/v1/cases/{mine['id']}/room-share/rooms/{room}", json={"access": "edit"}, status=403)
dan_own = Actor(dan.client, dan.email, dan.name)
dan_own.login()
theirs = dan_own.request("POST", "/api/v1/cases", json={"title": "Von Dan"}, status=201)
dan_own.request("PUT", f"/api/v1/cases/{theirs['id']}/room-share/rooms/{room}", json={"access": "edit"}, status=403)
assert own["title"] == "Bens"
def test_leaving_the_team_takes_the_own_shares_along(world, db):
ada, ben, cem, room = world["ada"], world["ben"], world["cem"], world["room"]
ben.use_room(room)
bens = ben.request("POST", "/api/v1/cases", json={"title": "Bens Freigabe"}, status=201)
cem.request("GET", f"/api/v1/cases/{bens['id']}")
ada.request("PATCH", f"/api/v1/rooms/{room}/members/{_id(db, ben.email)}", json={"role": "reader"})
cem.request("GET", f"/api/v1/cases/{bens['id']}", status=404)
ben.request("GET", f"/api/v1/cases/{bens['id']}")
def test_the_bulk_action_and_the_exposure_count_own_entries(world, db):
ada, ben, room = world["ada"], world["ben"], world["room"]
old = ada.request("POST", "/api/v1/cases", json={"title": "Bestand"}, status=201)
db.execute("DELETE FROM room_shares WHERE resource_id = %s", (old["id"],))
db.commit()
ben.request("GET", f"/api/v1/cases/{old['id']}", status=404)
assert ada.request("GET", f"/api/v1/rooms/{room}/exposure")["cases"] == {"room": 0, "private": 1}
assert ada.request("POST", f"/api/v1/rooms/{room}/my-content/visibility", json={"visibility": "room"}) == {"changed": 1}
ben.request("GET", f"/api/v1/cases/{old['id']}")
assert ada.request("GET", f"/api/v1/rooms/{room}/exposure")["cases"] == {"room": 1, "private": 0}
ben.use_room(room)
theirs = ben.request("POST", "/api/v1/cases", json={"title": "Bens"}, status=201)
ada.request("POST", f"/api/v1/rooms/{room}/my-content/visibility", json={"visibility": "private"})
ben.request("GET", f"/api/v1/cases/{old['id']}", status=404)
ben.request("GET", f"/api/v1/cases/{theirs['id']}")
world["dan"].request("GET", f"/api/v1/rooms/{room}/exposure", status=403)
def test_a_room_can_start_without_sharing(client, db):
ada = _actor(client, db, "ada", "ada-start@example.test", main=True)
ben = _actor(client, db, "ben", "ben-start@example.test")
room = ada.request("POST", "/api/v1/rooms", json={"name": "Privat", "default_visibility": "private"}, status=201)
ada.use_room(room["id"])
case = ada.request("POST", "/api/v1/cases", json={"title": "Nur ich"}, status=201)
ada.request("POST", f"/api/v1/rooms/{room['id']}/members", json={"email": ben.email, "role": "member"})
ben.request("GET", f"/api/v1/cases/{case['id']}", status=404)
ada.request("PATCH", f"/api/v1/rooms/{room['id']}", json={"default_visibility": "room"})
other = ada.request("POST", "/api/v1/cases", json={"title": "Jetzt geteilt"}, status=201)
ben.request("GET", f"/api/v1/cases/{other['id']}")
ben.request("PATCH", f"/api/v1/rooms/{room['id']}", json={"default_visibility": "private"}, status=403)
def test_lists_tell_the_owner_what_is_shared_and_rooms_are_managed_from_any_room(world, db):
ada, ben, room = world["ada"], world["ben"], world["room"]
case = ada.request("POST", "/api/v1/cases", json={"title": "Liste"}, status=201)
item = next(i for i in ada.request("GET", "/api/v1/cases")["items"] if i["id"] == case["id"])
assert item["is_owner"] is True and [s["name"] for s in item["shared_with"]] == ["Werkstatt"]
seen = next(i for i in ben.request("GET", "/api/v1/cases")["items"] if i["id"] == case["id"])
assert seen["is_owner"] is False and seen["shared_with"] == []
matter = matter_of(ada, "Listenvorgang")
row = next(i for i in ada.request("GET", "/api/v1/matters")["items"] if i["id"] == matter["id"])
assert row["is_owner"] is True and [s["name"] for s in row["shared_with"]] == ["Werkstatt"]
# The owner manages the team while working in the personal room, without switching.
personal = Actor(ada.client, ada.email, ada.name)
body = personal.login()
assert body["scope"]["kind"] == "personal"
members = personal.request("GET", f"/api/v1/rooms/{room}/members")["items"]
assert {m["role"] for m in members} == {"manager", "member", "reader"}
personal.request("PATCH", f"/api/v1/rooms/{room}/members/{_id(db, ben.email)}", json={"role": "reader"})
personal.request("PATCH", f"/api/v1/rooms/{room}", json={"name": "Werkstatt neu"})
assert [r["name"] for r in personal.request("GET", "/api/v1/rooms")["items"] if r["id"] == room] == ["Werkstatt neu"]
def test_room_endpoints_are_closed_to_outsiders_and_do_not_reveal_which_ids_exist(world, db):
import uuid
ada, ben, cem, dan, room = world["ada"], world["ben"], world["cem"], world["dan"], world["room"]
foreign = str(uuid.uuid4())
dan_id = _id(db, dan.email)
ben_id = _id(db, ben.email)
attempts = [
("GET", "/members", None),
("POST", "/members", {"email": dan.email, "role": "manager"}),
("PATCH", f"/members/{ben_id}", {"role": "manager"}),
("DELETE", f"/members/{ben_id}", None),
("GET", "/invitations", None),
("PATCH", "", {"name": "Übernommen"}),
("POST", "/owner", {"subject_id": dan_id}),
("GET", "/exposure", None),
("POST", "/my-content/visibility", {"visibility": "room"}),
]
for method, suffix, body in attempts:
# Dan is no member, Cem is a reader, Ben a plain member: none of them administers the room.
for actor in (dan, cem, ben):
if method == "GET" and suffix == "/exposure" and actor in (cem, ben):
continue # members may read their own exposure counts
if method == "POST" and suffix == "/my-content/visibility" and actor is ben:
continue # members may share their own entries
actor.request(method, f"/api/v1/rooms/{room}{suffix}", json=body, status=403)
# A room that does not exist answers like a room that is closed to the caller.
dan.request(method, f"/api/v1/rooms/{foreign}{suffix.replace(ben_id, dan_id)}", json=body, status=403)
dan.request("POST", "/api/v1/invitations", json={"email": "x@example.test", "room_id": room}, status=403)
dan.request("POST", "/api/v1/invitations", json={"email": "x@example.test", "room_id": foreign}, status=403)
dan.request("GET", "/api/v1/admin/rooms", status=403)
dan.request("POST", f"/api/v1/admin/rooms/{room}/owner", json={"email": dan.email}, status=403)
dan.request("GET", "/api/v1/admin/events", status=403)
# Nothing changed.
members = ada.request("GET", f"/api/v1/rooms/{room}/members")["items"]
assert {m["email"]: m["role"] for m in members}[ben.email] == "member"
assert dan.email not in {m["email"] for m in members}
assert db.execute("SELECT name FROM data_rooms WHERE id = %s", (room,)).fetchone()["name"] == "Werkstatt"
db.rollback()
+249
View File
@@ -0,0 +1,249 @@
"""Datenraumrollen (Mitglied, Verwalter, Leser), Einladungen, Betreiberübersicht."""
from __future__ import annotations
from fastapi.testclient import TestClient
from tests.support import ORIGIN, PASSWORD, Actor, register
def _second_client():
from app.main import app
return TestClient(app)
def _setup(client, db):
ada = Actor(client, "ada-rolle@example.test", "Ada Rolle")
ben = Actor(_second_client(), "ben-rolle@example.test", "Ben Rolle")
cem = Actor(_second_client(), "cem-rolle@example.test", "Cem Rolle")
for actor in (ada, ben, cem):
register(db, actor.email, actor.name)
actor.login()
room = ada.request("POST", "/api/v1/rooms", json={"name": "Verein"}, status=201)
ada.use_room(room["id"])
return ada, ben, cem, room["id"]
def test_manager_sets_roles_and_a_reader_creates_nothing(client, db):
ada, ben, cem, room = _setup(client, db)
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": ben.email, "role": "reader"})
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": cem.email, "role": "member"})
members = {item["email"]: item["role"] for item in ada.request("GET", f"/api/v1/rooms/{room}/members")["items"]}
assert members == {ada.email: "manager", ben.email: "reader", cem.email: "member"}
ben.use_room(room)
cem.use_room(room)
refused = ben.request("POST", "/api/v1/cases", json={"title": "Nicht erlaubt"}, status=403)
assert "Leser" in refused["detail"]
ben.request("POST", "/api/v1/matters", json={"title": "Auch nicht"}, status=403)
cem.request("POST", "/api/v1/cases", json={"title": "Erlaubt"}, status=201)
# The role is read from the database at every request.
ada.request("PATCH", f"/api/v1/rooms/{room}/members/{_subject(ada, room, ben.email)}", json={"role": "member"})
ben.request("POST", "/api/v1/cases", json={"title": "Jetzt erlaubt"}, status=201)
ada.request("PATCH", f"/api/v1/rooms/{room}/members/{_subject(ada, room, ben.email)}", json={"role": "reader"})
ben.request("POST", "/api/v1/cases", json={"title": "Wieder nicht"}, status=403)
def test_a_reader_gets_no_edit_grant_and_loses_existing_ones(client, db):
ada, ben, cem, room = _setup(client, db)
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": ben.email, "role": "member"})
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": cem.email, "role": "reader"})
case = ada.request("POST", "/api/v1/cases", json={"title": "Gemeinsam"}, status=201)
refused = ada.request(
"POST",
f"/api/v1/cases/{case['id']}/grants",
json={"email": cem.email, "can_read": True, "can_edit": True, "can_share": False},
status=422,
)
assert "Leser" in refused["detail"]
ada.request(
"POST",
f"/api/v1/cases/{case['id']}/grants",
json={"email": cem.email, "can_read": True, "can_edit": False, "can_share": False},
status=201,
)
ada.request(
"POST",
f"/api/v1/cases/{case['id']}/grants",
json={"email": ben.email, "can_read": True, "can_edit": True, "can_share": True},
status=201,
)
ada.request("PATCH", f"/api/v1/rooms/{room}/members/{_subject(ada, room, ben.email)}", json={"role": "reader"})
grant = db.execute(
"SELECT can_read, can_edit, can_share FROM access_grants WHERE grantee_subject_id = (SELECT id FROM auth_accounts WHERE email = %s)",
(ben.email,),
).fetchone()
db.rollback()
assert grant == {"can_read": True, "can_edit": False, "can_share": False}
def test_the_last_manager_stays(client, db):
ada, ben, _cem, room = _setup(client, db)
me = _subject(ada, room, ada.email)
ada.request("PATCH", f"/api/v1/rooms/{room}/members/{me}", json={"role": "member"}, status=422)
ada.request("DELETE", f"/api/v1/rooms/{room}/members/{me}", status=422)
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": ada.email, "role": "reader"}, status=422)
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": ben.email, "role": "manager"})
# Ada owns the room and stays manager until she hands it over.
ada.request("PATCH", f"/api/v1/rooms/{room}/members/{me}", json={"role": "member"}, status=422)
ada.request("POST", f"/api/v1/rooms/{room}/owner", json={"subject_id": _subject(ada, room, ben.email)})
ada.request("PATCH", f"/api/v1/rooms/{room}/members/{me}", json={"role": "member"})
# Ben is owner and the only manager now.
ben.use_room(room)
ben.request("DELETE", f"/api/v1/rooms/{room}/members/{_subject(ben, room, ben.email)}", status=422)
ada.request("GET", f"/api/v1/rooms/{room}/members", status=403)
def test_owner_transfer_and_operator_step_in(client, db):
ada, ben, cem, room = _setup(client, db)
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": ben.email, "role": "member"})
ben.use_room(room)
ben_id = _subject(ben, room, ben.email)
ben.request("POST", f"/api/v1/rooms/{room}/owner", json={"subject_id": ben_id}, status=403)
ada.request("POST", f"/api/v1/rooms/{room}/owner", json={"subject_id": _subject(ada, room, cem.email)}, status=422)
ada.request("POST", f"/api/v1/rooms/{room}/owner", json={"subject_id": _subject(ada, room, ada.email)}, status=422)
# Ada cannot leave or be demoted while she owns the room, and cannot be disabled while members depend on it.
ada_id = _subject(ada, room, ada.email)
db.execute("UPDATE auth_accounts SET origin = 'operator' WHERE id = %s", (ada_id,))
db.commit()
operator = Actor(_second_client(), "betreiber-eigner@example.test", "Betreiber Eigner")
register(db, operator.email, operator.name, superadmin=True)
operator.login()
operator.request("PATCH", f"/api/v1/accounts/{ada_id}", json={"status": "disabled"}, status=422)
operator.request("POST", f"/api/v1/admin/rooms/{room}/owner", json={"email": ben.email}, status=403)
ada.request("POST", f"/api/v1/rooms/{room}/owner", json={"subject_id": ben_id})
ben.request("GET", f"/api/v1/rooms/{room}/members")
owners = [r for r in ben.request("GET", "/api/v1/auth/session")["rooms"] if r["id"] == room]
assert owners[0]["is_owner"] is True
ada.request("PATCH", f"/api/v1/rooms/{room}", json={"status": "archived"}, status=403)
ben.request("PATCH", f"/api/v1/rooms/{room}", json={"default_visibility": "private"})
# The old owner may be disabled now; the room keeps its owner. A disabled owner is replaced by the operator.
operator.request("PATCH", f"/api/v1/accounts/{ada_id}", json={"status": "disabled"})
db.execute("UPDATE data_rooms SET owner_id = %s WHERE id = %s", (ada_id, room))
db.commit()
stepped = operator.request("POST", f"/api/v1/admin/rooms/{room}/owner", json={"email": ben.email})
assert stepped["owner_id"] == ben_id
events = operator.request("GET", "/api/v1/admin/events", params={"limit": 100})["items"]
assert "room_owner_changed" in [item["action"] for item in events]
def test_a_removed_member_loses_the_room_at_once(client, db):
ada, ben, _cem, room = _setup(client, db)
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": ben.email, "role": "member"})
ben.use_room(room)
ben.request("GET", "/api/v1/cases")
ada.request("DELETE", f"/api/v1/rooms/{room}/members/{_subject(ada, room, ben.email)}", status=204)
ben.request("GET", "/api/v1/cases", status=403)
def test_invitations_carry_a_role_and_can_be_revoked(client, db):
ada, ben, _cem, room = _setup(client, db)
invited = ada.request(
"POST",
"/api/v1/invitations",
json={"email": "neu-rolle@example.test", "room_id": room, "role": "reader"},
status=201,
)
assert invited["role"] == "reader" and invited["token"]
ada.request("POST", "/api/v1/invitations", json={"email": ben.email, "room_id": room}, status=422)
open_items = ada.request("GET", f"/api/v1/rooms/{room}/invitations")["items"]
assert [item["email"] for item in open_items] == ["neu-rolle@example.test"]
assert "token" not in open_items[0]
ben.request("GET", f"/api/v1/rooms/{room}/invitations", status=403)
guest = _second_client()
accepted = guest.post(
f"/api/v1/invitations/{invited['id']}/accept",
json={"token": invited["token"], "display_name": "Neu Gast", "password": PASSWORD},
headers={"Origin": ORIGIN},
)
assert accepted.status_code == 201, accepted.text
assert [(r["name"], r["role"]) for r in accepted.json()["rooms"] if r["kind"] == "organization"] == [("Verein", "reader")]
again = _second_client().post(
f"/api/v1/invitations/{invited['id']}/accept",
json={"token": invited["token"], "display_name": "Zweiter", "password": PASSWORD},
headers={"Origin": ORIGIN},
)
assert again.status_code == 404
second = ada.request("POST", "/api/v1/invitations", json={"email": "widerruf@example.test", "room_id": room}, status=201)
ada.request("DELETE", f"/api/v1/rooms/{room}/invitations/{second['id']}", status=204)
refused = _second_client().post(
f"/api/v1/invitations/{second['id']}/accept",
json={"token": second["token"], "display_name": "Widerruf", "password": PASSWORD},
headers={"Origin": ORIGIN},
)
assert refused.status_code == 404
ada.request("DELETE", f"/api/v1/rooms/{room}/invitations/{second['id']}", status=404)
def test_rooms_are_renamed_archived_and_restored_by_a_manager(client, db):
ada, ben, _cem, room = _setup(client, db)
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": ben.email, "role": "member"})
ben.request("PATCH", f"/api/v1/rooms/{room}", json={"name": "Fremd"}, status=403)
renamed = ada.request("PATCH", f"/api/v1/rooms/{room}", json={"name": "Verein e.V."})
assert renamed["name"] == "Verein e.V."
ada.request("PATCH", f"/api/v1/rooms/{room}", json={"status": "archived"})
# The session of the archiving manager moved back to the personal room.
ada.request("GET", "/api/v1/rooms", status=403)
body = ada.request("GET", "/api/v1/auth/session")
assert body["scope"]["kind"] == "personal"
ada.scope, ada.csrf = body["scope"], body["csrf_token"]
listed = ada.request("GET", "/api/v1/rooms", params={"include_archived": "true"})["items"]
assert any(item["id"] == room and item.get("status") == "archived" for item in listed)
ada.request("POST", "/api/v1/auth/session/scope", json={"kind": "organization", "id": room}, status=403)
ada.request("PATCH", f"/api/v1/rooms/{room}", json={"status": "active"})
ada.use_room(room)
def test_operator_sees_rooms_without_content_and_fills_an_orphaned_room(client, db):
ada, ben, _cem, room = _setup(client, db)
operator = Actor(_second_client(), "betreiber-rolle@example.test", "Betreiber Rolle")
register(db, operator.email, operator.name, superadmin=True)
operator.login()
ada.request("POST", "/api/v1/cases", json={"title": "Nur für Ada"}, status=201)
overview = operator.request("GET", "/api/v1/admin/rooms")["items"]
row = next(item for item in overview if item["id"] == room)
assert row["managers"] == ["Ada Rolle"] and row["members"] == 1 and row["has_manager"] is True
assert row["owner"] == "Ada Rolle" and row["owner_active"] is True
assert "Nur für Ada" not in str(overview)
operator.request("GET", f"/api/v1/rooms/{room}/members", status=403)
ben.request("GET", "/api/v1/admin/rooms", status=403)
operator.request("POST", f"/api/v1/admin/rooms/{room}/managers", json={"email": ben.email}, status=403)
db.execute("UPDATE auth_accounts SET status = 'disabled' WHERE email = %s", (ada.email,))
db.commit()
assigned = operator.request("POST", f"/api/v1/admin/rooms/{room}/managers", json={"email": ben.email})
assert assigned["role"] == "manager"
ben.use_room(room)
assert {item["email"] for item in ben.request("GET", f"/api/v1/rooms/{room}/members")["items"]} >= {ben.email}
def test_room_events_reach_the_operator_audit_without_secrets(client, db):
ada, ben, _cem, room = _setup(client, db)
operator = Actor(_second_client(), "audit-rolle@example.test", "Audit Rolle")
register(db, operator.email, operator.name, superadmin=True)
operator.login()
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": ben.email, "role": "reader"})
invited = ada.request("POST", "/api/v1/invitations", json={"email": "audit-gast@example.test", "room_id": room}, status=201)
events = operator.request("GET", "/api/v1/admin/events", params={"limit": 50})
actions = [item["action"] for item in events["items"]]
assert {"room_created", "membership_added", "invitation_created"} <= set(actions)
text = str(events)
assert "audit-gast@example.test" not in text and invited["token"] not in text
ben.request("GET", "/api/v1/admin/events", status=403)
page = operator.request("GET", "/api/v1/admin/events", params={"limit": 1})
assert len(page["items"]) == 1 and page["next_cursor"] == 1
def _subject(actor: Actor, room: str, email: str) -> str:
# A manager lists the members; Ada manages in these tests. Fall back to the account table.
from app.core.settings import get_settings
import psycopg
with psycopg.connect(get_settings().dsn(), row_factory=psycopg.rows.dict_row) as conn:
return str(conn.execute("SELECT id FROM auth_accounts WHERE email = %s", (email,)).fetchone()["id"])
+226
View File
@@ -0,0 +1,226 @@
"""A third source appears only by registering its module."""
from __future__ import annotations
import io
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
# The backend image that runs this suite has no Node. The sample module is
# small enough to check against the registry operations it calls.
sample = (ROOT / "frontend/src/sources/sample-source.js").read_text(encoding="utf-8")
registry = (ROOT / "frontend/src/sources/registry-core.js").read_text(encoding="utf-8")
assert "registerSourceModule" in sample and "unregisterSourceModule" in sample
assert 'kind: "sample"' in sample and 'representation: "text"' in sample
assert 'unregisterSourceModule("sample")' in sample
assert "modules.set(module.kind, module)" in registry
assert "modules.delete(kind)" in registry
modules: dict[str, dict] = {}
def register(module: dict) -> dict:
modules[module["kind"]] = module
return module
def unregister(kind: str) -> None:
modules.pop(kind, None)
register({"kind": "sample", "representation": "text"})
assert any(item["kind"] == "sample" and item["representation"] == "text" for item in modules.values())
unregister("sample")
assert not any(item["kind"] == "sample" for item in modules.values())
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)
+220
View File
@@ -0,0 +1,220 @@
"""Hauptnutzer, Mitarbeiter und Teamverwaltung."""
from __future__ import annotations
import uuid
import pytest
from fastapi.testclient import TestClient
from app.auth.accounts import create_account
from app.core.errors import unprocessable
from tests.support import ORIGIN, PASSWORD, Actor
def _second_client():
from app.main import app
return TestClient(app)
def _main(client, db, key: str, *, main: bool = False, superadmin: bool = False) -> Actor:
actor = Actor(client if main else _second_client(), f"{key}-team@example.test", key.title())
create_account(db, actor.email, actor.name, PASSWORD, is_superadmin=superadmin)
db.commit()
actor.login()
return actor
def _invite(owner: Actor, room: str, email: str, role: str = "member", name: str = "Mitarbeiter") -> Actor:
invited = owner.request("POST", "/api/v1/invitations", json={"email": email, "room_id": room, "role": role}, status=201)
client = _second_client()
response = client.post(
f"/api/v1/invitations/{invited['id']}/accept",
json={"token": invited["token"], "display_name": name, "password": PASSWORD},
headers={"Origin": ORIGIN},
)
assert response.status_code == 201, response.text
employee = Actor(client, email, name)
employee.login()
return employee
def _id(db, email: str) -> str:
row = db.execute("SELECT id FROM auth_accounts WHERE email = %s", (email,)).fetchone()
db.rollback()
return str(row["id"])
@pytest.fixture
def world(client, db):
ada = _main(client, db, "ada", main=True)
room = ada.request("POST", "/api/v1/rooms", json={"name": "Kanzlei"}, status=201)["id"]
ada.use_room(room)
employee = _invite(ada, room, "emp-team@example.test", name="Eva Mitarbeiterin")
return {"ada": ada, "room": room, "emp": employee}
def test_an_invitation_creates_an_employee_account_sponsored_by_the_owner(world, db):
row = db.execute("SELECT account_kind, sponsor_id FROM auth_accounts WHERE email = 'emp-team@example.test'").fetchone()
db.rollback()
assert row["account_kind"] == "employee"
assert str(row["sponsor_id"]) == _id(db, world["ada"].email)
assert world["emp"].request("GET", "/api/v1/auth/session")["account"]["account_kind"] == "employee"
assert world["ada"].request("GET", "/api/v1/auth/session")["account"]["account_kind"] == "main"
def test_an_employee_works_only_in_the_rooms_he_was_invited_to(world, db):
emp, room = world["emp"], world["room"]
emp.request("POST", "/api/v1/rooms", json={"name": "Eigener Raum"}, status=403)
# The session starts in the team room, not in a personal room.
assert emp.scope["kind"] == "organization" and emp.scope["id"] == room
# In the personal room nothing is created.
personal = emp.request("POST", "/api/v1/auth/session/scope", json={"kind": "personal", "id": _id(db, emp.email)})
emp.scope, emp.csrf = personal["scope"], personal["csrf_token"]
emp.request("POST", "/api/v1/cases", json={"title": "Privat"}, status=403)
emp.request("POST", "/api/v1/matters", json={"title": "Privat"}, status=403)
emp.use_room(room)
case = emp.request("POST", "/api/v1/cases", json={"title": "Im Team"}, status=201)
world["ada"].request("GET", f"/api/v1/cases/{case['id']}")
# Rights follow the role: a reader only reads.
world["ada"].request("PATCH", f"/api/v1/rooms/{room}/members/{_id(db, emp.email)}", json={"role": "reader"})
emp.request("POST", "/api/v1/cases", json={"title": "Nicht mehr"}, status=403)
emp.request("GET", f"/api/v1/cases/{case['id']}")
def test_only_the_owner_invites_and_an_employee_never_does(world, client, db):
ada, emp, room = world["ada"], world["emp"], world["room"]
ben = _main(client, db, "ben")
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": ben.email, "role": "manager"})
ben.use_room(room)
# A manager who is not the owner adds existing accounts but creates no new ones.
ben.request("POST", "/api/v1/invitations", json={"email": "neu-team@example.test", "room_id": room}, status=403)
ben.request("POST", f"/api/v1/rooms/{room}/members", json={"email": emp.email, "role": "reader"})
emp.request("POST", "/api/v1/invitations", json={"email": "neu-team@example.test", "room_id": room}, status=403)
def test_an_employee_cannot_own_a_room(world, db):
ada, emp, room = world["ada"], world["emp"], world["room"]
ada.request("POST", f"/api/v1/rooms/{room}/owner", json={"subject_id": _id(db, emp.email)}, status=422)
operator = _main(world["ada"].client.__class__ and _second_client(), db, "betreiber", superadmin=True)
db.execute("UPDATE auth_accounts SET status = 'disabled' WHERE id = %s", (_id(db, ada.email),))
db.commit()
operator.request("POST", f"/api/v1/admin/rooms/{room}/owner", json={"email": emp.email}, status=422)
def test_my_team_lists_only_people_in_my_rooms_and_acts_only_on_my_employees(world, client, db):
ada, emp = world["ada"], world["emp"]
cara = _main(client, db, "cara")
emp_id = _id(db, emp.email)
listed = ada.request("GET", "/api/v1/team")["items"]
assert [(p["email"], p["mine"], p["rooms"][0]["role"]) for p in listed] == [(emp.email, True, "member")]
assert cara.request("GET", "/api/v1/team")["items"] == []
emp.request("GET", "/api/v1/team", status=403)
unknown = str(uuid.uuid4())
for actor in (cara,):
foreign = actor.request("PATCH", f"/api/v1/team/{emp_id}", json={"status": "disabled"}, status=403)
missing = actor.request("PATCH", f"/api/v1/team/{unknown}", json={"status": "disabled"}, status=403)
assert foreign["detail"] == missing["detail"]
actor.request("POST", f"/api/v1/team/{emp_id}/password-reset", status=403)
actor.request("DELETE", f"/api/v1/team/{emp_id}/memberships", status=403)
# A main user is not a sponsored employee: no team action on him, not even by the owner.
cara_id = _id(db, cara.email)
ada.request("PATCH", f"/api/v1/team/{cara_id}", json={"status": "disabled"}, status=403)
ada.request("POST", f"/api/v1/team/{cara_id}/password-reset", status=403)
def test_the_owner_disables_resets_and_removes_an_employee(world, db):
ada, emp, room = world["ada"], world["emp"], world["room"]
emp_id = _id(db, emp.email)
ada.request("PATCH", f"/api/v1/team/{emp_id}", json={"status": "disabled"})
emp.request("GET", "/api/v1/auth/session", status=401)
login = emp.client.post("/api/v1/auth/login", json={"email": emp.email, "password": PASSWORD}, headers={"Origin": ORIGIN})
assert login.status_code == 401
ada.request("PATCH", f"/api/v1/team/{emp_id}", json={"status": "active"})
reset = ada.request("POST", f"/api/v1/team/{emp_id}/password-reset")
emp.password = reset["temporary_password"]
assert emp.login()["account"]["must_change_password"] is True
emp.request("GET", "/api/v1/cases", status=403)
ada.request("DELETE", f"/api/v1/team/{emp_id}/memberships", status=204)
assert ada.request("GET", "/api/v1/team")["items"][0]["rooms"] == []
# Without a room the employee lands in the personal room, where he can do nothing but change his password.
assert emp.login()["scope"]["kind"] == "personal"
ada.request("DELETE", f"/api/v1/team/{emp_id}/memberships", status=403)
ada.request("DELETE", f"/api/v1/team/{_id(db, ada.email)}/memberships", status=403)
assert room
def test_the_operator_sees_the_teams_as_metadata_and_exports_them_safely(world, client, db):
ada, room = world["ada"], world["room"]
_invite(ada, room, "formel-team@example.test", role="reader", name="=SUM(1+1)")
operator = _main(_second_client(), db, "betreiber", superadmin=True)
note = ada.request("POST", "/api/v1/cases", json={"title": "Geheimer Inhalt"}, status=201)
overview = operator.request("GET", "/api/v1/admin/team")["items"]
owner = next(item for item in overview if item["email"] == ada.email)
assert {e["email"] for e in owner["employees"]} == {"emp-team@example.test", "formel-team@example.test"}
assert all(r["name"] == "Kanzlei" for e in owner["employees"] for r in e["rooms"])
assert "Geheimer Inhalt" not in str(overview) and note["title"] == "Geheimer Inhalt"
response = operator.client.get(
"/api/v1/admin/team",
params={"format": "csv"},
headers={"Origin": ORIGIN, "X-Scope-Kind": operator.scope["kind"], "X-Scope-Id": operator.scope["id"]},
)
assert response.status_code == 200 and response.headers["content-type"].startswith("text/csv")
lines = response.text.splitlines()
assert lines[0] == "Hauptnutzer,Mitarbeiter,E-Mail,Status,Datenraum,Rolle"
assert any("'=SUM(1+1)" in line for line in lines)
assert not any(line.split(",")[1].startswith("=") for line in lines[1:])
world["emp"].request("GET", "/api/v1/admin/team", status=403)
ada.request("GET", "/api/v1/admin/team", status=403)
def test_only_the_operator_promotes_an_employee(world, client, db):
ada, emp, room = world["ada"], world["emp"], world["room"]
emp_id = _id(db, emp.email)
ada.request("PATCH", f"/api/v1/accounts/{emp_id}", json={"account_kind": "main"}, status=403)
operator = _main(_second_client(), db, "betreiber", superadmin=True)
listed = {a["email"]: a for a in operator.request("GET", "/api/v1/accounts")["items"]}
assert listed[emp.email]["account_kind"] == "employee" and listed[emp.email]["sponsor_name"] == "Ada"
assert operator.request("GET", f"/api/v1/accounts/{_id(db, ada.email)}")["employees"][0]["email"] == emp.email
operator.request("PATCH", f"/api/v1/accounts/{emp_id}", json={"account_kind": "main"})
emp.request("GET", "/api/v1/cases", status=401)
fresh = Actor(emp.client, emp.email, emp.name)
assert fresh.login()["account"]["account_kind"] == "main"
fresh.request("POST", "/api/v1/rooms", json={"name": "Eigener Raum"}, status=201)
assert room
def test_limits_have_one_place_and_are_checked_where_they_matter(world, client, db, monkeypatch):
ada, room = world["ada"], world["room"]
seen = []
def block_room(conn, owner_id):
seen.append(("room", owner_id))
raise unprocessable("Grenze erreicht.")
def block_member(conn, owner_id, room_id):
seen.append(("member", owner_id, room_id))
raise unprocessable("Grenze erreicht.")
cem = _main(client, db, "cem")
monkeypatch.setattr("app.api.rooms.ensure_can_create_room", block_room)
ada.request("POST", "/api/v1/rooms", json={"name": "Noch ein Raum"}, status=422)
monkeypatch.setattr("app.api.rooms.ensure_can_add_member", block_member)
ada.request("POST", f"/api/v1/rooms/{room}/members", json={"email": cem.email, "role": "member"}, status=422)
ada.request("POST", "/api/v1/invitations", json={"email": "grenze-team@example.test", "room_id": room}, status=422)
assert [entry[0] for entry in seen] == ["room", "member", "member"]
assert all(entry[1] == uuid.UUID(_id(db, ada.email)) for entry in seen)
# Changing the role of an existing member needs no check.
monkeypatch.undo()
invited = ada.request("POST", "/api/v1/invitations", json={"email": "spaet-team@example.test", "room_id": room}, status=201)
monkeypatch.setattr("app.api.routes.ensure_can_add_member", block_member)
refused = _second_client().post(
f"/api/v1/invitations/{invited['id']}/accept",
json={"token": invited["token"], "display_name": "Spät", "password": PASSWORD},
headers={"Origin": ORIGIN},
)
assert refused.status_code == 422
assert db.execute("SELECT 1 FROM auth_accounts WHERE email = 'spaet-team@example.test'").fetchone() is None
db.rollback()
+1 -1
View File
@@ -81,7 +81,7 @@ def test_t_anchor_assignee_sees_the_task_but_not_the_hidden_matter(client, db):
ada = Actor(client, "ada@example.test", "Ada")
ada.login()
matter = ada.request("POST", "/api/v1/matters", json={"title": "Geheimer Vorgang Anker"}, status=201)
room = ada.request("POST", "/api/v1/rooms", json={"name": "Gleicher Raum"}, status=201)
room = ada.request("POST", "/api/v1/rooms", json={"name": "Gleicher Raum", "default_visibility": "private"}, status=201)
ada.request("POST", f"/api/v1/rooms/{room['id']}/members", json={"email": "ben@example.test", "role": "member"})
ada.request("POST", f"/api/v1/rooms/{room['id']}/members", json={"email": "cara@example.test", "role": "member"})
ada.use_room(room["id"])
+261
View File
@@ -0,0 +1,261 @@
"""Kontoverwaltung: Einmal-Passwort, Deaktivieren, Betreiberrolle, Sitzungen, Login-Begrenzung."""
from __future__ import annotations
import pytest
from fastapi.testclient import TestClient
from app.auth.accounts import create_account
from tests.support import ORIGIN, PASSWORD, Actor
NEW_PASSWORD = "Neues-Passwort-2026"
def register(conn, email: str, name: str, *, superadmin: bool = False):
"""Accounts of the operator kind, because the account list hides fixture accounts."""
account = create_account(conn, email, name, PASSWORD, is_superadmin=superadmin)
conn.commit()
return account
@pytest.fixture
def operator(client, db) -> Actor:
actor = Actor(client, "betreiber-admin@example.test", "Betreiber Admin")
register(db, actor.email, actor.name, superadmin=True)
actor.login()
return actor
def _user(client, db, email: str = "nutzer-admin@example.test", name: str = "Nutzer Admin") -> Actor:
actor = Actor(client, email, name)
register(db, actor.email, actor.name)
return actor
def _second_client():
from app.main import app
return TestClient(app)
def test_operator_creates_an_account_with_a_one_time_password(client, operator):
created = operator.request(
"POST",
"/api/v1/accounts",
json={"email": "neu@example.test", "display_name": "Neu"},
status=201,
)
temporary = created["temporary_password"]
assert len(temporary) >= 10
assert created["must_change_password"] is True
fresh = Actor(client, "neu@example.test", "Neu")
fresh.password = temporary
body = fresh.login()
assert body["account"]["must_change_password"] is True
refused = fresh.request("GET", "/api/v1/cases", status=403)
assert refused["code"] == "password_change_required"
fresh.request("GET", "/api/v1/auth/session")
fresh.request(
"POST",
"/api/v1/auth/password",
json={"current_password": "falsch-falsch-1", "new_password": NEW_PASSWORD},
status=422,
)
fresh.request("POST", "/api/v1/auth/password", json={"current_password": temporary, "new_password": temporary}, status=422)
fresh.request("POST", "/api/v1/auth/password", json={"current_password": temporary, "new_password": "kurz"}, status=422)
fresh.request(
"POST",
"/api/v1/auth/password",
json={"current_password": temporary, "new_password": NEW_PASSWORD},
status=204,
)
fresh.request("GET", "/api/v1/cases")
assert fresh.request("GET", "/api/v1/auth/session")["account"]["must_change_password"] is False
again = Actor(client, "neu@example.test", "Neu")
again.password = NEW_PASSWORD
again.login()
old = client.post(
"/api/v1/auth/login",
json={"email": "neu@example.test", "password": temporary},
headers={"Origin": ORIGIN},
)
assert old.status_code == 401
def test_only_the_operator_manages_accounts(client, db, operator):
user = _user(client, db)
target = operator.request("GET", "/api/v1/accounts")["items"][0]["id"]
user.login()
user.request("GET", "/api/v1/accounts", status=403)
user.request("GET", f"/api/v1/accounts/{target}", status=403)
user.request("PATCH", f"/api/v1/accounts/{target}", json={"status": "disabled"}, status=403)
user.request("POST", f"/api/v1/accounts/{target}/password-reset", status=403)
user.request("POST", f"/api/v1/accounts/{target}/sessions/revoke", status=403)
user.request("POST", "/api/v1/accounts", json={"email": "x@example.test", "display_name": "X"}, status=403)
def test_a_disabled_account_cannot_sign_in_and_its_sessions_end(client, db, operator):
user = _user(client, db)
other = _second_client()
victim = Actor(other, user.email, user.name)
victim.login()
victim.request("GET", "/api/v1/cases")
operator.request("PATCH", f"/api/v1/accounts/{_id(operator, user.email)}", json={"status": "disabled"})
victim.request("GET", "/api/v1/cases", status=401)
refused = client.post(
"/api/v1/auth/login",
json={"email": user.email, "password": PASSWORD},
headers={"Origin": ORIGIN},
)
assert refused.status_code == 401
listed = operator.request("GET", "/api/v1/accounts", params={"status": "disabled"})
assert [item["email"] for item in listed["items"]] == [user.email]
operator.request("PATCH", f"/api/v1/accounts/{_id(operator, user.email)}", json={"status": "active"})
Actor(client, user.email, user.name).login()
def test_the_last_operator_and_the_own_account_are_protected(client, db, operator):
me = _id(operator, operator.email)
operator.request("PATCH", f"/api/v1/accounts/{me}", json={"status": "disabled"}, status=422)
operator.request("PATCH", f"/api/v1/accounts/{me}", json={"is_operator": False}, status=422)
user = _user(client, db)
other = _id(operator, user.email)
operator.request("PATCH", f"/api/v1/accounts/{other}", json={"is_operator": True})
# A second operator exists now, so the first may step down.
operator.request("PATCH", f"/api/v1/accounts/{me}", json={"is_operator": False})
promoted = Actor(client, user.email, user.name)
promoted.login()
promoted.request("PATCH", f"/api/v1/accounts/{promoted_id(promoted)}", json={"status": "disabled"}, status=422)
promoted.request("PATCH", f"/api/v1/accounts/{promoted_id(promoted)}", json={"is_operator": False}, status=422)
def test_granting_the_operator_role_ends_the_target_sessions(client, db, operator):
user = _user(client, db)
other = _second_client()
target = Actor(other, user.email, user.name)
target.login()
target.request("GET", "/api/v1/cases")
operator.request("PATCH", f"/api/v1/accounts/{_id(operator, user.email)}", json={"is_operator": True})
target.request("GET", "/api/v1/cases", status=401)
fresh = Actor(other, user.email, user.name)
assert fresh.login()["account"]["is_superadmin"] is True
def test_password_reset_sets_a_one_time_password_and_ends_sessions(client, db, operator):
user = _user(client, db)
other = _second_client()
target = Actor(other, user.email, user.name)
target.login()
account_id = _id(operator, user.email)
operator.request("POST", f"/api/v1/accounts/{operator_id(operator)}/password-reset", status=422)
reset = operator.request("POST", f"/api/v1/accounts/{account_id}/password-reset")
target.request("GET", "/api/v1/cases", status=401)
renewed = Actor(other, user.email, user.name)
renewed.password = reset["temporary_password"]
assert renewed.login()["account"]["must_change_password"] is True
renewed.request("GET", "/api/v1/cases", status=403)
detail = operator.request("GET", f"/api/v1/accounts/{account_id}")
assert detail["must_change_password"] is True
assert detail["active_sessions"] == 1
revoked = operator.request("POST", f"/api/v1/accounts/{account_id}/sessions/revoke")
assert revoked["revoked"] == 1
renewed.request("GET", "/api/v1/auth/session", status=401)
def test_own_sessions_can_be_listed_and_ended(client, db):
user = _user(client, db)
user.login()
other = _second_client()
second = Actor(other, user.email, user.name)
second.login()
items = user.request("GET", "/api/v1/auth/sessions")["items"]
assert len(items) == 2
assert sum(1 for item in items if item["current"]) == 1
current = next(item for item in items if item["current"])
foreign = next(item for item in items if not item["current"])
user.request("DELETE", f"/api/v1/auth/sessions/{current['id']}", status=422)
user.request("DELETE", f"/api/v1/auth/sessions/{foreign['id']}", status=204)
second.request("GET", "/api/v1/cases", status=401)
third = Actor(other, user.email, user.name)
third.login()
assert user.request("POST", "/api/v1/auth/sessions/revoke-others")["revoked"] == 1
third.request("GET", "/api/v1/cases", status=401)
user.request("GET", "/api/v1/cases")
def test_login_attempts_are_counted_in_the_database_without_the_address(client, db):
user = _user(client, db)
for _ in range(8):
response = client.post(
"/api/v1/auth/login",
json={"email": user.email, "password": "falsch-falsch-1"},
headers={"Origin": ORIGIN},
)
assert response.status_code == 401
blocked = client.post(
"/api/v1/auth/login",
json={"email": user.email, "password": PASSWORD},
headers={"Origin": ORIGIN},
)
assert blocked.status_code == 429
rows = db.execute("SELECT bucket FROM auth_login_attempts").fetchall()
assert len(rows) == 8
assert all(user.email not in row["bucket"] and len(row["bucket"]) == 64 for row in rows)
db.rollback()
# Another address is a separate bucket and still works.
other = _user(client, db, "andere-adresse@example.test", "Andere")
Actor(client, other.email, other.name).login()
def test_unknown_and_wrong_password_answer_alike(client, db):
user = _user(client, db)
wrong = client.post(
"/api/v1/auth/login",
json={"email": user.email, "password": "falsch-falsch-1"},
headers={"Origin": ORIGIN},
)
unknown = client.post(
"/api/v1/auth/login",
json={"email": "gibt-es-nicht@example.test", "password": "falsch-falsch-1"},
headers={"Origin": ORIGIN},
)
assert wrong.status_code == unknown.status_code == 401
assert wrong.json()["detail"] == unknown.json()["detail"]
def test_admin_actions_are_audited_without_secrets(client, db, operator):
created = operator.request(
"POST",
"/api/v1/accounts",
json={"email": "audit-ziel@example.test", "display_name": "Audit Ziel"},
status=201,
)
account_id = created["id"]
operator.request("POST", f"/api/v1/accounts/{account_id}/password-reset")
operator.request("PATCH", f"/api/v1/accounts/{account_id}", json={"status": "disabled"})
rows = db.execute(
"SELECT action, detail FROM domain_events WHERE resource_kind = 'account' AND resource_id = %s ORDER BY occurred_at",
(account_id,),
).fetchall()
assert [row["action"] for row in rows] == ["account_created", "password_reset", "account_disabled"]
text = str(rows) + str(db.execute("SELECT * FROM domain_events").fetchall())
assert "audit-ziel@example.test" not in text
assert created["temporary_password"] not in text
def _id(actor: Actor, email: str) -> str:
items = actor.request("GET", "/api/v1/accounts")["items"]
return next(item["id"] for item in items if item["email"] == email)
def operator_id(actor: Actor) -> str:
return _id(actor, actor.email)
def promoted_id(actor: Actor) -> str:
return _id(actor, actor.email)
+46
View File
@@ -0,0 +1,46 @@
"""R-11: other people's rows must not push your own out of the overview and the search."""
from __future__ import annotations
from tests.support import Actor, case_of, note_on, register
def test_own_entries_are_found_behind_many_foreign_ones(client, db, monkeypatch):
from fastapi.testclient import TestClient
from app.api import routes
from app.main import app
# A tiny batch size makes the paging visible with few rows.
monkeypatch.setattr(routes, "SCAN_BATCH", 2)
register(db, "ada-scan@example.test", "Ada")
register(db, "ben-scan@example.test", "Ben")
ada = Actor(client, "ada-scan@example.test", "Ada")
ben = Actor(TestClient(app), "ben-scan@example.test", "Ben")
ada.login()
ben.login()
ada_case = case_of(ada, "Adas Akte")
for index in range(7):
matter = ada.request("POST", "/api/v1/matters", json={"title": f"Adas Vorgang {index}"}, status=201)
ada.request("POST", "/api/v1/tasks", json={"title": f"Frühe Aufgabe {index}", "due_on": "2026-01-0%d" % (index + 1), "matter_id": matter["id"]}, status=201)
ada.request("POST", "/api/v1/deadlines", json={"title": f"Frühe Frist {index}", "due_on": "2026-01-0%d" % (index + 1), "matter_id": matter["id"]}, status=201)
note_on(ada, f"Gemeinsames Stichwort {index}", "Zebrastreifen", ada_case["id"])
ben_matter = ben.request("POST", "/api/v1/matters", json={"title": "Bens Vorgang"}, status=201)
ben.request("POST", "/api/v1/tasks", json={"title": "Bens späte Aufgabe", "due_on": "2027-01-01", "matter_id": ben_matter["id"]}, status=201)
ben.request("POST", "/api/v1/deadlines", json={"title": "Bens späte Frist", "due_on": "2027-01-01", "matter_id": ben_matter["id"]}, status=201)
ben_case = case_of(ben, "Bens Akte")
note_on(ben, "Bens Zebrastreifen-Notiz", "Zebrastreifen", ben_case["id"])
assert [item["title"] for item in ben.request("GET", "/api/v1/views/open-tasks")["items"]] == ["Bens späte Aufgabe"]
assert [item["title"] for item in ben.request("GET", "/api/v1/views/open-deadlines")["items"]] == ["Bens späte Frist"]
found = ben.request("GET", "/api/v1/search", params={"q": "Zebrastreifen"})["items"]
assert [item["title"] for item in found] == ["Bens Zebrastreifen-Notiz"]
# The own entries still come in order and the cap on the list holds.
monkeypatch.setattr(routes, "VIEW_LIMIT", 3)
first = ada.request("GET", "/api/v1/views/open-tasks")["items"]
assert [item["title"] for item in first] == ["Frühe Aufgabe 0", "Frühe Aufgabe 1", "Frühe Aufgabe 2"]
monkeypatch.setattr(routes, "SEARCH_LIMIT", 4)
assert len(ada.request("GET", "/api/v1/search", params={"q": "Zebrastreifen"})["items"]) == 4
+16
View File
@@ -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.
+97
View File
@@ -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.
+3
View File
@@ -7,6 +7,9 @@ Diese Regeln sind die Arbeitsgrundlage der ersten Lieferung. Sie sind keine endg
3. **Einbindung und Löschen.** „Aus diesem Kontext entfernen“ löscht die Einbindung und ihre Anmerkungen. Das Element bleibt bei der Eigentümerin oder dem Eigentümer, auch ohne Einbindung. „Überall löschen“ darf nur diese Person. Paperless-Originale werden nicht gelöscht.
4. **Aktenvererbung.** Die Zuordnung eines Vorgangs gibt die Rechte dieser Akte an den Vorgang und an Inhalte ohne ausdrückliche Ausnahme weiter. Was die zuordnende Person nicht weitergeben darf, bleibt in diesem Aktenkontext unsichtbar, ohne Titel und ohne Anzahl. Querverweise vererben nichts. Die Ownership bleibt unverändert.
5. **Herunterladen von Originalen.** Das Recht „Herunterladen“ ist getrennt vom Lesen, standardmäßig überall erlaubt und je Raum und Rolle abschaltbar (Voreinstellung am Konto des Hauptnutzers). Es ist eine Nutzungsregel, kein Kopierschutz: Lesen in der App bleibt möglich, Abfotografieren und Entwicklerwerkzeuge verhindert die Regel nicht. Ob später eine strengere Rechtegrundlage nötig ist, entscheiden Datenschutz und Recht.
6. **Bilder in E-Mails.** Bilder fremder Server werden nicht automatisch geladen. Auf Wunsch lädt der Server sie für die Person nach, das Gerät kontaktiert den Absender nicht. Dass die Nachricht geöffnet wurde, kann der Absender erkennen.
Der gewählte Datenraum legt fest, wo neue Objekte entstehen. Er ist nicht selbst der Rechtepfad. Eine gültige Sitzung muss einen Datenraum gewählt haben; der Server prüft danach den mitgeschickten Handlungskontext.
Technische Anpassung: Das Session-Cookie heißt in Production `__Host-jinkendo-session` und ist `Secure`. Development nutzt diesen Namen nur bei HTTPS. Über die dokumentierten HTTP-Adressen im LAN heißt es `jinkendo-session`, weil ein `__Host-`-Cookie dort nicht gespeichert werden kann.
+99
View File
@@ -0,0 +1,99 @@
# 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_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_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md](product/TSUMUGU_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md) | Korrektur K1–K7: IMAP-Ordner, MIME, Transaktion, Markdown, Leser, Paperless-Antworten | 20.10.2026 |
| [TSUMUGU_IMAP_SENT_ITEMS_MIME_BEFUND_UND_FIXAUFTRAG_2026-10-20.md](product/TSUMUGU_IMAP_SENT_ITEMS_MIME_BEFUND_UND_FIXAUFTRAG_2026-10-20.md) | Befund zu Sent Items und MIME, unverändert übernommen | 20.10.2026 |
| [TSUMUGU_RELEASE_GATE_BACKUP_AUFTRAG_2026-10-22.md](product/TSUMUGU_RELEASE_GATE_BACKUP_AUFTRAG_2026-10-22.md) | Auftrag P7: Release-Gate, Backup und Restore vor Produktion (R-21), für eine eigene Sitzung | 22.10.2026 |
| [TSUMUGU_CONNECTOR_NACHARBEIT_REVIEW_2026-10-20.md](product/TSUMUGU_CONNECTOR_NACHARBEIT_REVIEW_2026-10-20.md) | Review der Nacharbeit, unverändert übernommen | 20.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 |
| [BENUTZERVERWALTUNG.md](architecture/BENUTZERVERWALTUNG.md) | Konten, Rollen, Einmal-Passwort, Einladungen, Audit (Ist) und Abgrenzung zum Sicherheitskonzept | 20.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.
+66 -25
View File
@@ -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 und am 23.10.2026 um Download-Regeln, HTML-Mail mit Bildern, Übersicht und Suche. 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.
@@ -31,28 +31,61 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R**
| Methode | Pfad | Auth | Zweck |
|---|---|---|---|
| POST | `/api/v1/auth/login` | – | E-Mail, Passwort → Session-Sicht und Cookie. 8 Versuche je IP+E-Mail in 10 min (Prozessspeicher) |
| POST | `/api/v1/auth/login` | – | E-Mail, Passwort → Session-Sicht und Cookie. 8 Fehlversuche je Bucket (Hash aus IP und E-Mail) in 10 min, gezählt in `auth_login_attempts` |
| POST | `/api/v1/auth/logout` | S | Session widerrufen, Cookie löschen, 204 |
| GET / PUT | `/api/v1/auth/download-defaults` | S+R, Hauptnutzer | Voreinstellung je Rolle und `direct` (direkt freigegebene Personen); neue Räume übernehmen die drei Rollenwerte. Audit `download_defaults_changed` |
| GET | `/api/v1/auth/session` | S | Konto, bestätigter Datenraum, Räume, CSRF-Token, Epoche |
| POST | `/api/v1/auth/session/scope` | S | Datenraum wechseln (`kind`, `id`); erhöht die Epoche |
| GET | `/api/v1/auth/bootstrap` | – | `{available: true}`, solange kein Betreiber existiert, sonst 404 |
| POST | `/api/v1/auth/bootstrap` | – | erstes Konto als Betreiber anlegen, nur ohne vorhandenen Betreiber |
| GET | `/api/v1/auth/demo` | – | Beispielkonten; nur Development mit Datenbank `*_test` und `SEED_DEMO=true`, sonst 404 |
| GET | `/api/v1/accounts` | S+R, B | aktive Betreiberkonten (`origin='operator'`) |
| POST | `/api/v1/accounts` | S+R, B | Konto mit Passwort anlegen, erhält persönlichen Raum |
| GET | `/api/v1/accounts` | S+R, B | Betreiberkonten (`origin='operator'`) mit Status, Rolle, letzter Anmeldung; Filter `status=active\|disabled` |
| GET | `/api/v1/accounts/{id}` | S+R, B | Detail mit Raummitgliedschaften und Zahl aktiver Sitzungen |
| POST | `/api/v1/accounts` | S+R, B | Konto anlegen, persönlicher Raum, `must_change_password`. Ohne `password` erzeugt der Server ein Einmal-Passwort und liefert es einmal als `temporary_password`. `is_operator` optional |
| PATCH | `/api/v1/accounts/{id}` | S+R, B | `display_name`, `is_operator`, `status` (`active`/`disabled`), `account_kind: main` (Mitarbeiter zum Hauptnutzer machen). Letzter Betreiber und eigenes Konto sind geschützt |
| POST | `/api/v1/accounts/{id}/password-reset` | S+R, B | neues Einmal-Passwort, beendet alle Sitzungen; nicht für das eigene Konto |
| POST | `/api/v1/accounts/{id}/sessions/revoke` | S+R, B | alle Sitzungen des Kontos beenden |
| POST | `/api/v1/auth/password` | S | eigenes Passwort ändern (`current_password`, `new_password`); beendet die anderen Sitzungen; 204. Erlaubt auch bei `must_change_password` |
| GET | `/api/v1/auth/sessions` | S | eigene aktive Sitzungen (Gerätehinweis, zuletzt aktiv) |
| DELETE | `/api/v1/auth/sessions/{id}` | S | eigene andere Sitzung beenden; die aktuelle über Abmelden |
| POST | `/api/v1/auth/sessions/revoke-others` | S | überall sonst abmelden |
| GET | `/api/v1/principals?email=` | S+R | aktives Konto per E-Mail auflösen (ID, Anzeigename) |
| POST | `/api/v1/invitations` | S+R, M | Einladung in einen gemeinsamen Raum; Antwort enthält das Token einmalig. Keine Oberfläche |
| POST | `/api/v1/invitations/{id}/accept` | – | Token, Anzeigename, Passwort → Konto, Mitgliedschaft, Session |
| POST | `/api/v1/invitations` | S+R, M | Einladung in einen gemeinsamen Raum mit `role` (`member`/`manager`/`reader`); Antwort enthält das Token einmalig |
| POST | `/api/v1/invitations/{id}/accept` | – | Token, Anzeigename, Passwort → Konto, Mitgliedschaft mit der Rolle der Einladung, Session. Widerrufene, benutzte oder abgelaufene Einladung: 404 |
## Datenräume
| Methode | Pfad | Auth | Zweck |
|---|---|---|---|
| GET | `/api/v1/rooms` | S+R | wählbare Räume |
| GET | `/api/v1/rooms` | S+R | wählbare Räume; `include_archived=true` ergänzt die archivierten Räume der Person |
| POST | `/api/v1/rooms` | S+R | gemeinsamen Raum anlegen, Anlegende Person wird Verwalter |
| GET | `/api/v1/rooms/{id}/members` | S+R, M | Mitglieder |
| POST | `/api/v1/rooms/{id}/members` | S+R, M | bestehendes Konto als `member` oder `manager` aufnehmen |
| DELETE | `/api/v1/rooms/{id}/members/{subject_id}` | S+R, M | Mitgliedschaft beenden; letzter Verwalter bleibt. Keine Oberfläche |
| PATCH | `/api/v1/rooms/{id}` | S+R, M / E | `name` (Verwalter); `status` und `default_visibility` nur der Eigentümer (E). Archivieren setzt Sitzungen im Raum auf den persönlichen Raum zurück |
| GET / PUT | `/api/v1/rooms/{id}/download-policy` | S+R, Mitglied / E | je Rolle (`manager`, `member`, `reader`), ob das Original gespeichert oder geöffnet werden darf; `can_change` nennt, ob die Person ändern darf. Fremde und unbekannte Räume: 404. Audit `room_download_policy_changed` |
| GET | `/api/v1/rooms/{id}/members` | S+R, M | Mitglieder mit Rolle und Kontostatus |
| POST | `/api/v1/rooms/{id}/members` | S+R, M | bestehendes Konto als `member`, `manager` oder `reader` aufnehmen oder dessen Rolle setzen |
| PATCH | `/api/v1/rooms/{id}/members/{subject_id}` | S+R, M | Rolle ändern; letzter Verwalter bleibt. Rückstufung auf `reader` entzieht Bearbeiten- und Freigeben-Grants auf Objekte des Raums |
| DELETE | `/api/v1/rooms/{id}/members/{subject_id}` | S+R, M | Mitgliedschaft beenden; letzter Verwalter bleibt |
| GET | `/api/v1/rooms/{id}/invitations` | S+R, M | offene Einladungen ohne Token |
| DELETE | `/api/v1/rooms/{id}/invitations/{invitation_id}` | S+R, M | Einladung widerrufen |
| POST | `/api/v1/rooms/{id}/owner` | S+R, E | Raum an ein aktives Mitglied übertragen (Eigentümer); der neue Eigentümer wird Verwalter |
| GET | `/api/v1/rooms/{id}/exposure` | S+R, Mitglied | eigene Akten und Vorgänge: mit dem Raum geteilt (`room`) oder dort abgelegt, aber nicht geteilt (`private`) |
| POST | `/api/v1/rooms/{id}/my-content/visibility` | S+R, Mitglied | `room`: alle eigenen im Raum abgelegten Akten und Vorgänge mit dem Raum teilen; `private`: alle eigenen Freigaben an diesen Raum beenden |
| GET | `/api/v1/cases/{id}/room-share`, `/api/v1/matters/{id}/room-share` | S+R, Owner | Freigaben des Eintrags an Datenräume (mit Mitgliedern, Rolle, Ausnahme) und die Räume, mit denen er noch teilen kann |
| PUT / DELETE | `/api/v1/cases/{id}/room-share/rooms/{room_id}` (PUT antwortet zusätzlich mit `effect`), `/api/v1/matters/{id}/room-share/rooms/{room_id}` | S+R, Owner | mit dem Raum teilen (`access`: `edit` = Rechte nach Rolle, `read` = höchstens Lesen) oder die Freigabe beenden; nur in Räumen, in denen der Owner Mitglied oder Verwalter ist |
| PUT | `/api/v1/cases/{id}/room-share/people/{subject_id}`, `/api/v1/matters/{id}/room-share/people/{subject_id}` | S+R, Owner | eine Person von der Raumfreigabe ausnehmen (`excluded`) |
| POST | `/api/v1/admin/rooms/{id}/owner` | S+R, B | Betreiber setzt einen Eigentümer ein, nur wenn der bisherige nicht mehr handeln kann (Konto deaktiviert oder nicht mehr Mitglied) |
| GET | `/api/v1/rooms/overview` | S+R | Räume der Person als Kacheln: Rolle, Eigentümer, Zahl der Mitglieder und der lesbaren Akten und Vorgänge; Mitgliedernamen nur für Verwalter |
| GET | `/api/v1/rooms/{id}/contents` | S+R, Mitglied | Akten und Vorgänge, die mit dem Raum geteilt und für die Person lesbar sind, mit Zählern |
| POST | `/api/v1/rooms/{id}/shares` | S+R, Mitglied | mehrere eigene Einträge auf einmal mit dem Raum teilen (alle oder keiner); Antwort nennt die Wirkung je Mitglied |
| GET | `/api/v1/cases/{id}/outline`, `/api/v1/matters/{id}/outline` | S+R | Struktur für den Navigationsbaum: Kapitel, Unterakten und Vorgänge bzw. Teilvorgänge, nur aus Lesbarem; für Vorgänge optional `context_kind=case&context_id=` |
| GET | `/api/v1/team` | S+R, Hauptnutzer | Personen in den eigenen Räumen mit Rolle je Raum; `mine` = selbst eingeladen |
| PATCH | `/api/v1/team/{id}` | S+R, Hauptnutzer | `status` eines selbst eingeladenen Mitarbeiters; fremde und unbekannte ID: 403 |
| POST | `/api/v1/team/{id}/password-reset` | S+R, Hauptnutzer | Einmal-Passwort für einen selbst eingeladenen Mitarbeiter |
| DELETE | `/api/v1/team/{id}/memberships` | S+R, Hauptnutzer | Person aus allen eigenen Räumen entfernen |
| GET | `/api/v1/admin/team` | S+R, B | Hauptnutzer mit Mitarbeitern, Räumen und Rollen; `format=csv` für den Export |
| GET | `/api/v1/admin/rooms` | S+R, B | alle gemeinsamen Räume mit Zustand, Mitgliederzahl, Verwaltern; keine Inhalte |
| POST | `/api/v1/admin/rooms/{id}/managers` | S+R, B | Verwalter einsetzen, nur wenn der Raum keinen aktiven Verwalter hat |
| GET | `/api/v1/admin/events` | S+R, B | Verwaltungsprotokoll (`cursor`, `limit`) für Konto, Sitzung, Raum, Mitgliedschaft, Einladung |
## Akten
@@ -111,7 +144,7 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R**
| POST | `/api/v1/notes` | Notiz mit Einbindung (`context`, optional `placement`, `chapter_id`, `dates`, `communication_direction`) |
| PATCH | `/api/v1/notes/{id}` | gemeinsamen Text ändern; Antwort mit `visible_bindings` und `notice` |
| POST | `/api/v1/files` | Datei hochladen (Multipart: `title`, `context_kind`, `context_id`, `upload`, optional Platzierung, Kapitel, Daten, Richtung); PDF, PNG, JPEG, WebP bis 20 MiB |
| GET | `/api/v1/files/{id}/content` | Datei als `attachment`, `no-store` |
| GET | `/api/v1/files/{id}/content` | Datei als `attachment` mit Dateiname (UTF-8, `filename*`), `no-store`. Mit `save=true` zusätzlich das Download-Recht, sonst 403 |
| POST | `/api/v1/external-refs` | externe Referenz (`paperless`, `imap`, `url`) mit `detail` |
| POST | `/api/v1/sources/link` | wie oben, nur `paperless`/`imap` (doppelter Weg, siehe Connectoren-Befund) |
| GET | `/api/v1/elements` | eigene, nicht eingebundene Elemente (max. 100) |
@@ -143,8 +176,8 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R**
| POST | `/api/v1/deadlines` | Frist |
| PATCH | `/api/v1/deadlines/{id}` | Titel, Datum |
| POST | `/api/v1/deadlines/{id}/fulfill` | als erfüllt kennzeichnen |
| GET | `/api/v1/views/open-tasks` | offene sichtbare Aufgaben (siehe Review R-11) |
| GET | `/api/v1/views/open-deadlines` | offene sichtbare Fristen (siehe Review R-11) |
| GET | `/api/v1/views/open-tasks` | offene sichtbare Aufgaben, höchstens 200. Gelesen wird in Blöcken mit Rechteprüfung je Zeile (R-11 behoben) |
| GET | `/api/v1/views/open-deadlines` | offene sichtbare Fristen, wie oben |
| GET | `/api/v1/views/recent-matters` | acht zuletzt geänderte sichtbare Vorgänge |
| GET | `/api/v1/placement-targets` | bearbeitbare Akten und Vorgänge als Ziele |
| GET | `/api/v1/search?q=` | Akten, Vorgänge, Elemente (Titel und Notiztext), max. 50 |
@@ -153,20 +186,28 @@ 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 |
| POST | `/api/v1/connectors/{id}/probe` | Zugang prüfen |
| GET | `/api/v1/sources/paperless/documents?q=` | Paperless-Suche (letzter eigener Zugang) |
| GET | `/api/v1/connectors` | eigene Zugänge ohne Secret, mit Fähigkeiten der registrierten Quelle, `has_secret` und letztem Prüfstand (`probe`) |
| GET | `/api/v1/connectors/{id}` | Detail eines eigenen Zugangs: nicht geheime Einstellungen, `has_secret`, Fähigkeiten, Schutzprofil, Prüfstand und Zahl der eigenen Verknüpfungen. Nie das Secret. Fremde Instanz: 404 |
| POST | `/api/v1/connectors` | neue Instanz einer registrierten Quelle; Body `{kind, name, config}`. `config` wird gegen das Feldmanifest des Moduls geprüft (`modules[].config_fields` aus `/api/v1/sources/capabilities`); unbekannte Art oder unbekanntes Feld wird abgewiesen; ersetzt keinen vorhandenen Zugang. Die flachen Felder der ersten Lieferung (`base_url`, `token`, `host`, …) gelten nur als Kompatibilität und werden in `config` übersetzt |
| PATCH | `/api/v1/connectors/{id}` | Name, Einstellungen und Zugangsdaten derselben Instanz. Ein leeres Geheimnisfeld behält das gespeicherte Geheimnis; der letzte Prüfstand wird zurückgesetzt |
| DELETE | `/api/v1/connectors/{id}` | Zugang löschen; bestehende Referenzen bleiben und werden nicht umgehängt |
| POST | `/api/v1/connectors/{id}/probe` | gespeicherten Zugang prüfen; Ergebnis (auch ein Fehler) wird als Prüfstand festgehalten. Es gibt keine Prüfung mit ungespeicherten Entwürfen |
| 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}/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) |
| GET | `/api/v1/external-refs/{id}/content` | Original der gebundenen Instanz über das registrierte Modul (`inline`, mit Dateiname). Mit `save=true` zusätzlich das Download-Recht |
| GET | `/api/v1/external-refs/{id}/mail` | vollständige E-Mail als JSON, Identität per Message-ID geprüft; `html` ist bereinigt, `remote_images` zählt Bilder fremder Server |
| GET | `/api/v1/external-refs/{id}/mail/html-with-images` | dieselbe bereinigte Mail, die Bilder fremder Server lädt der Server auf Anforderung und liefert sie eingebettet (`loaded`, `failed`) |
| GET | `/api/v1/external-refs/{id}/mail/original` | EML unter dem Betreff als Name; verlangt das Download-Recht (403 sonst) |
| GET | `/api/v1/external-refs/{id}/mail/attachments/{index}` | Anlage (`inline`, siehe Review R-03); mit `save=true` das Download-Recht |
| 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
@@ -174,7 +215,7 @@ Quelleninhalte werden mit den Zugängen der **anfragenden** Person geladen (Revi
|---|---|---|
| GET | `/api/v1/matters/{id}/export-tree` | Auswahlbaum mit `exportable` und Grund |
| POST | `/api/v1/matters/{id}/export/review` | Prüfung: `ready`, `issues`, `notices`, `entries` mit Paketpfaden |
| POST | `/api/v1/matters/{id}/export` | ZIP nur bei `ready`; Audit `export_created`. Knoten `attachment`, `dispatch-item` und `evidence` gehören zur Auswahl |
| POST | `/api/v1/matters/{id}/export` | ZIP nur bei `ready` und mit Download-Recht am Vorgang (403 sonst); Audit `export_created`. Knoten `attachment`, `dispatch-item` und `evidence` gehören zur Auswahl |
## Anlagen und Versand
+118
View File
@@ -0,0 +1,118 @@
# Benutzerverwaltung, Rollen und Rechte (Ist, 20.10.2026)
Erster Schnitt der Administration. Er baut auf den vorhandenen Mechanismen auf (Kontext-Grants, Datenräume, Audit über `domain_events`) und führt kein neues Fachmodell ein. Die Auswertung der Objektrechte bleibt unverändert, siehe [RECHTEMODELL_IST.md](RECHTEMODELL_IST.md).
## Rollen
Feste Bündel, kein Rolleneditor (Technische Spezifikation 5.2). Rollen werden bei jeder Anfrage aus der Datenbank gelesen, nicht in der Session gehalten (`backend/app/access/roles.py`).
| Ebene | Rolle | Darf |
|---|---|---|
| Plattform | Betreiber (`is_superadmin`, mehrere möglich) | Konten anlegen, deaktivieren und aktivieren, Passwort zurücksetzen, Sitzungen beenden, Betreiberrolle vergeben und entziehen, Räume mit Verwaltern sehen, Verwalter in einen Raum ohne Verwalter einsetzen, Verwaltungsprotokoll lesen. **Kein Leserecht auf Inhalte.** |
| Plattform | Nutzer | eigenes Passwort ändern, eigene Sitzungen ansehen und beenden |
| Datenraum | Verwalter (`manager`) | Mitglieder und Rollen verwalten, Einladungen, Raum umbenennen, archivieren und wieder aktivieren |
| Datenraum | Mitglied (`member`) | Inhalte im Raum anlegen. Objektrechte weiter nur per Grant |
| Datenraum | Leser (`reader`) | Raum wählen und freigegebene Inhalte lesen. Legt im Raum nichts an. Erhält für Objekte dieses Raums keine Bearbeiten- oder Freigeben-Grants |
### Schutzregeln
- Der letzte aktive Betreiber lässt sich weder deaktivieren noch zurückstufen. Niemand deaktiviert das eigene Konto.
- Der letzte aktive Verwalter eines Raums bleibt Verwalter. Er kann weder zurückgestuft noch entfernt werden.
- Wer zum Betreiber befördert wird, verliert alle Sitzungen und meldet sich neu an.
- Konten werden **deaktiviert, nicht gelöscht**. Inhalte, Owner-Bezüge und Protokoll bleiben. Löschen oder Anonymisieren ist ein eigener späterer Schnitt.
### Wirkung der Leser-Rolle
Einzelfreigaben (Grants) hängen am Objekt, nicht am Raum. Der Leser begrenzt daher zusätzlich zur Raumfreigabe (siehe unten, dort liest er nur) drei Stellen:
1. Anlegen von Akte, Vorgang, Notiz, Datei, Referenz, Aufgabe und Frist mit diesem Heimatraum (`ensure_can_create` in `ops.py`).
2. Vergabe neuer Bearbeiten- oder Freigeben-Grants an einen Leser für Objekte dieses Raums (`grant_access`).
3. Beim Zurückstufen auf Leser werden dessen vorhandene Bearbeiten- und Freigeben-Grants auf Objekte dieses Raums in derselben Transaktion entzogen. Lese-Grants bleiben.
Grants auf Objekte anderer Räume bleiben unberührt.
## Datenräume, Eigentümer und Raumfreigabe (seit 21.10.2026)
- **Mehrere Räume:** Jede Person kann beliebig viele gemeinsame Datenräume anlegen. Ein Raum mit nur dem Eigentümer als Mitglied ist **privat**, mit weiteren Mitgliedern **Mehrbenutzer**. Der persönliche Raum bleibt unverändert.
- **Eigentümer** (`data_rooms.owner_id`): der Ersteller. Er ist stets Verwalter, lässt sich nicht entfernen oder zurückstufen und überträgt den Raum an ein aktives Mitglied. Nur er archiviert und stellt wieder her und ändert die Voreinstellung für neue Einträge. Ein Konto, das einen Raum mit weiteren Mitgliedern besitzt, lässt sich erst nach Übertragung deaktivieren. Ist der Eigentümer nicht mehr handlungsfähig, setzt der Betreiber einen neuen ein (protokolliert). Die Eigentümerrolle verleiht kein Leserecht.
- **Raumfreigabe:** Ein Raum ist ein Team. Der Owner teilt eine Akte, Unterakte oder einen Vorgang mit einem oder mehreren seiner Räume, unabhängig davon, wo der Eintrag abgelegt ist. Mitglieder erhalten Rechte nach Rolle (Leser lesen; Mitglied und Verwalter bearbeiten; Weitergeben und Löschen nie), die Freigabe kann auf „nur lesen“ begrenzt werden, einzelne Personen lassen sich ausnehmen. Ein einzelner Vorgang lässt sich teilen, ohne die Akte offenzulegen (Beispiel: nur die Vorgänge, die der Anwalt sehen soll). Die Voreinstellung eines Raums teilt neu angelegte Einträge, die in diesem Raum entstehen, automatisch mit ihm. Der Owner sieht seine Einträge unabhängig von Raum und Mitgliedschaft. Wer ein Team verlässt oder Leser wird, nimmt seine Freigaben an dieses Team mit; wer aus einem Raum entfernt wird, arbeitet danach im persönlichen Raum. Beim ersten weiteren Mitglied zeigt die Oberfläche, was bereits mit dem Raum geteilt ist. Bestehende Freigaben wurden übernommen, nicht geteilte Einträge blieben privat.
- **Quellzugänge:** Die Raumfreigabe gibt keine Paperless- oder Mail-Zugänge des Owners frei. Dafür bleibt die ausdrückliche Freigabe mit der Option nötig.
- **Löschen:** Akte und Vorgang löscht nur der Owner (oder wer ein Löschrecht hat), nicht jeder Bearbeiter.
## Zugang
- **Einmal-Passwort:** Der Betreiber legt ein Konto an oder setzt das Passwort zurück. Tsumugu erzeugt ein Passwort und zeigt es einmal an. Das Konto steht auf `must_change_password`, bis die Person ein eigenes festgelegt hat. Bis dahin antworten nur `auth/session`, `auth/password` und `auth/logout`, alles andere mit 403 `password_change_required`.
- **Einladungslink:** Ein Verwalter erstellt eine Einladung mit Rolle. Der Link enthält das Token im URL-Fragment (`/invite/{id}#{token}`), es erreicht also keinen Server-Log. Der Link gilt 7 Tage und einmal und lässt sich widerrufen. Es gibt keinen E-Mail-Versand.
- **Passwortregel:** mindestens 10 Zeichen, höchstens 72 UTF-8-Byte (bcrypt). Beim Ändern des eigenen Passworts enden alle anderen Sitzungen.
## Anmeldung
- Die Versuchsbegrenzung steht in der Tabelle `auth_login_attempts` (8 Fehlversuche in 10 Minuten je Bucket). Der Bucket ist ein SHA-256 aus Adresse und E-Mail, die Roh-E-Mail wird nicht gespeichert. Ein erfolgreicher Login löscht den Bucket.
- Unbekannte und deaktivierte Konten laufen durch einen bcrypt-Vergleich und erhalten dieselbe Antwort wie ein falsches Passwort.
- Der CSRF-Vergleich ist konstantzeitlich. `last_seen_at` wird höchstens alle 5 Minuten geschrieben.
## Audit
Alle schreibenden Aktionen schreiben in `domain_events`, ohne E-Mail, Passwort und Token. Ressourcenarten: `account`, `session`, `room`, `membership`, `invitation`. Der Betreiber liest sie unter `GET /api/v1/admin/events`. Nicht protokolliert werden fehlgeschlagene Anmeldungen (die Begrenzung zählt sie in `auth_login_attempts`).
## Bewusst nicht enthalten (Sicherheitskonzept)
MFA (später optional für alle Konten), Leerlaufablauf und Rotation der Sitzung, Änderung der Sitzungsdauer von 14 Tagen, Härtung des Web-Bootstraps für das erste Betreiberkonto (R-04), Mindestlänge 15, Einschränkung von `GET /api/v1/principals`, E-Mail-Versand, Löschen und Anonymisieren von Konten, Übertragung von Ownership.
## Bedienung (21.10.2026)
- **Eine Stelle für Datenräume:** Verwaltung → Datenräume listet alle eigenen Räume mit Zustand, Rolle und Eigentümer. Ein Klick öffnet die Verwaltung des Raums (`/rooms/{id}`): Mitglieder, Rollen, Einladungen, Umbenennen, Voreinstellung, Übertragung, Archivieren. Dafür ist kein Wechsel in den Raum nötig. Der Betreiber sieht darunter zusätzlich alle Räume mit Eigentümer und Verwalter.
- **Nutzer ist etwas anderes:** Verwaltung → Nutzer (nur Betreiber) verwaltet Konten, Verwaltungsprotokoll das Audit. Mein Konto betrifft das eigene Passwort und die Geräte.
- **Ablage mit Ordnerbaum und Kacheln** (Akten, Vorgänge, Räume): Links ein Ordnerbaum („Meine Ablage“ mit Akten und Vorgängen, darunter „Räume“), rechts Kacheln: Ordnersymbol für Akte und Unterakte, Dokumentstapel für Vorgang, Teamordner für Räume. Umschaltbar auf eine kompakte Liste. Ein Klick öffnet den Eintrag, „Inhalt ›“ wechselt in den Ordner (Unterakten und Vorgänge der Akte). Am Handy liegt der Baum hinter „Ordner anzeigen“.
- **Räume sind virtuelle Ordner:** Ein Eintrag kann in mehreren Räumen liegen, ohne verschoben zu werden. „In Raum legen“ und „Aus Raum nehmen“ ändern nur die Zuordnung. Auf jeder Kachel zeigen Marken, in welchen Räumen der Eintrag liegt (nur dem Owner).
- **Vier Wege zum Zuordnen:** (1) im Raum „Hinzufügen“ mit Auswahl eigener Akten und Vorgänge, (2) eine Kachel auf einen Raum im Baum oder auf eine Raumkachel ziehen, (3) Knopf „In Raum legen“ auf der Kachel (auch am Handy), (4) die Marke auf der Kachel öffnen und „Aus Raum nehmen“. Jede Aktion nennt danach, wer Zugriff hat (zum Beispiel „Ben bearbeitet, Cem liest“).
- **Neu anlegen** fragt nicht mehr nach dem Heimatraum. In der Raumansicht entsteht ein Eintrag gleich mit diesem Raum geteilt.
## Betreiber, Hauptnutzer und Mitarbeiter (seit 22.10.2026)
| Ebene | Kontoart | Aufgabe |
|---|---|---|
| Betreiber | Hauptnutzer mit `is_superadmin` | SaaS-Betreiber: verwaltet Hauptnutzer, sieht Räume und Team-Übersicht (Metadaten), keine Inhalte |
| Hauptnutzer | `account_kind = main` | privater Raum und eigene Team-Räume; Eigentümer; lädt Mitarbeiter ein und verwaltet sie |
| Mitarbeiter | `account_kind = employee` | arbeitet nur in eingeladenen Räumen nach Raumrolle; legt keine Räume an; kein privater Arbeitsbereich |
- **Einladung:** nur der Eigentümer des Raums (als Hauptnutzer). Das neue Konto ist ein Mitarbeiter; `sponsor_id` ist der Eigentümer. Ein Verwalter ohne Eigentum nimmt nur bestehende Konten auf.
- **Mitarbeiter-Sitzung:** beginnt im ersten Team-Raum, in dem die Person Mitglied ist. Im persönlichen Raum legt ein Mitarbeiter nichts an. Ohne Raum kann er sich anmelden, aber nichts tun.
- **Eigentümer:** nur ein Hauptnutzer kann Raum-Eigentümer sein, auch bei Übertragung und beim Einsetzen durch den Betreiber.
- **Mein Team** (`/team`): zeigt die Personen in den eigenen Räumen mit Rolle je Raum. Für selbst eingeladene Mitarbeiter: deaktivieren/aktivieren, Einmal-Passwort, Entfernen aus allen eigenen Räumen. Fremde und unbekannte Konten antworten gleich mit 403.
- **Betreiber:** `/admin/team` zeigt Hauptnutzer mit ihren Mitarbeitern, Räumen und Rollen (auch als CSV, mit Schutz vor Formeleingabe). Nur der Betreiber macht einen Mitarbeiter zum Hauptnutzer; die Person meldet sich dann neu an.
### Vorbereitung Subscription
`backend/app/access/limits.py` ist die einzige Stelle für Grenzen. `ensure_can_create_room(conn, owner_id)` läuft beim Anlegen eines Raums, `ensure_can_add_member(conn, owner_id, room_id)` beim Aufnehmen, Einladen und Annehmen einer Einladung. Heute lassen beide alles zu. Das Kontingentsubjekt ist der Eigentümer des Raums, ein Hauptnutzer, wie der Verein bei Shinkan (Entitlements-Blueprint). Vorgesehene Messgrößen: aktive Mitarbeiter je Hauptnutzer und je Raum, aus der Datenbank gezählt. Der Betreiber setzt den Plan. Zahlungsdienst und Tarife gehören nicht in diese Stufe. Offene Entscheidung: Ein Mitarbeiter, den ein zweiter Hauptnutzer als bestehendes Konto aufnimmt, zählt beim Raum-Eigentümer; die Zuständigkeit bei Grenzen klärt das Tarifkonzept.
### Ein Navigationsbaum für Ablage, Akten und Vorgänge (seit 23.10.2026)
Der Baum „Meine Ablage“ steht links auf den Listenseiten und auf den Seiten von Akte und Vorgang. Die frühere Spalte „Struktur“ ist darin aufgegangen.
- **Aufklappen mit Fokus:** Ein Klick auf eine Akte oder einen Vorgang öffnet ihn und klappt seine Struktur auf. Der Pfad dorthin bleibt offen, die aktuelle Zeile (auch ein Kapitel) ist hervorgehoben. Nach dem Neuladen der Seite stimmt der Fokus wieder.
- **Unter einer Akte:** Überblick, „Direkt in dieser Akte“, Kapitel mit Unterkapiteln, Unterakten und die Vorgänge der Akte. **Unter einem Vorgang:** „Alle Inhalte“, Kapitel, Teilvorgänge. „Neues Kapitel“ und die Pfeile zum Verschieben stehen im Baum, solange der Eintrag offen ist.
- **Direkt von Vorgang zu Vorgang:** Ein Vorgang erscheint unter jeder Akte, in der er liegt, und unter „Vorgänge“. Ein Klick unter einer Akte öffnet ihn in diesem Aktenkontext, unter „Vorgänge“ ohne Akte. Die frühere Auswahl des Handlungskontexts entfällt. Querverweise und weitere Akten stehen unter dem Titel des Vorgangs.
- **Nachladen:** Die Wurzeln kommen aus `/cases` und `/matters`, die Struktur eines Knotens aus `GET /cases/{id}/outline` und `GET /matters/{id}/outline`, einmal beim Aufklappen. Die Antworten enthalten nur Lesbares (keine Inhalte). Ändert sich der offene Eintrag (Kapitel, Unterakte, Vorgang), lädt der Baum seine Struktur neu.
- **Breite und Dichte:** Der Baum lässt sich an seiner rechten Kante mit der Maus ziehen (200 bis 560 Pixel, Pfeiltasten auf dem Griff, Doppelklick setzt zurück). Die Breite wird im Browser gemerkt (`localStorage`, Schlüssel `tsumugu-tree-width`); ohne Speicher gilt die Standardbreite. Zeilen und Einrückung sind kompakt, damit tiefe Strukturen hineinpassen.
- **Vorgang aus einer Akte lösen:** Im Menü des Vorgangs steht „Aus Akte lösen“, wenn er in Akten liegt. Gelöst wird nur die Zuordnung zur gewählten Akte (`DELETE /matter-case-links/{id}`); der Vorgang, seine Inhalte und seine anderen Akten bleiben. Erlaubt ist es mit Bearbeitungsrecht in der Akte oder mit Teilen-Recht am Vorgang.
### Herunterladen von Originalen (seit 23.10.2026)
- **Regel je Rolle:** Das Recht „Herunterladen“ ist neben Lesen, Bearbeiten, Teilen und Löschen ein eigenes Recht. Der Eigentümer hat es immer. Über einen Raum folgt es der Rolle (Verwalter, Mitglied, Leser) laut Regel des Raums; direkt freigegebene Personen folgen dem Wert „direkt“ des Eigentümers. Ohne Leserecht gibt es kein Herunterladen.
- **Wo einstellen:** Voreinstellung am Konto des Hauptnutzers („Mein Konto“, wird beim Anlegen eines Raums übernommen), danach je Raum in der Raumverwaltung (nur Eigentümer). Bestehende Daten bleiben erlaubt (Migration `20261023T090000Z_download_policy.sql`).
- **Was geprüft wird (serverseitig):** Speichern oder Öffnen des Originals (`?save=true` bei Dateien, Paperless-Dokumenten und Mail-Anlagen), die vollständige E-Mail (`.eml`) und das Übergabepaket. Lesen in Tsumugu bleibt möglich; die Regel ist ein Nutzungsrecht, kein Kopierschutz (Abfotografieren oder Entwicklerwerkzeuge verhindert sie nicht).
- **Dateiname:** Gespeichert wird unter dem echten Namen (UTF-8, `filename*`), die E-Mail unter ihrem Betreff.
- **Endpunkte:** `GET/PUT /rooms/{id}/download-policy`, `GET/PUT /auth/download-defaults`.
### E-Mails als HTML
Die Mail wird formatiert (Standard) oder als Text gezeigt. Der Server bereinigt das HTML mit einer Positivliste (keine Skripte, Formulare, Rahmen, `<style>`-Blöcke; Formatierung nur aus erlaubten Eigenschaften, ohne `url()`, Position oder Ausdrücke; Bilder nur eingebettet als PNG/JPEG/GIF/WebP; Links nur `http(s)` und `mailto`, mit `noopener`). Im Browser läuft die Ansicht in einem Rahmen mit leerem `sandbox` (eigene Herkunft, keine Skripte), Content-Security-Policy `default-src 'none'; img-src data:` und ohne Referrer. Fremde Bilder werden nicht geladen.
### Bilder in E-Mails nachladen
Bilder von fremden Servern bleiben standardmäßig draußen. „Bilder nachladen“ (oder die Einstellung „Automatisch nachladen“ unter „Mein Konto“, getrennt für Computer und Touch-Geräte, gespeichert im Browser; die Gerätegruppe folgt `pointer: coarse`) ruft `GET /external-refs/{id}/mail/html-with-images` auf. Der Server lädt die Bilder selbst und liefert sie eingebettet zurück, das Gerät kontaktiert den Absender nicht. Schutz (`app/remoteimages.py`): nur `https` auf Port 443, keine Zugangsdaten in der Adresse, Auflösung der Adresse einmal und Verbindung genau dorthin (kein DNS-Rebinding), alle Ergebnisse müssen öffentliche Adressen sein (kein Loopback, privat, Link-Local, Metadaten), höchstens drei Weiterleitungen mit gleicher Prüfung, 5 Sekunden, 1,5 MB je Bild, 12 Bilder und 6 MB je Nachricht, Prüfung des Inhalts an der Dateikennung (PNG, JPEG, GIF, WebP; kein SVG). Restrisiko: Der Absender sieht den Abruf und weiß damit, dass die Nachricht geöffnet wurde.
### Handy
PDFs werden auf iPhone und iPad seitenweise mit pdf.js (Legacy-Build) gezeichnet, weil Safari PDFs in einem Rahmen nicht zuverlässig anzeigt (`pages/DocumentView.jsx`); die PDF-Vorschau in der Liste ist dort weiterhin eingeschränkt, die Leseansicht funktioniert. Der Rahmen der Ablage begrenzt die Höhe, damit die Liste in Akte und Vorgang scrollt, und der Kopf der Leseansicht ist am Handy kompakt.
+15 -9
View File
@@ -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: `20261022T090000Z_account_kinds.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.
@@ -16,11 +16,16 @@ Die Sollfassung steht in der [technischen Spezifikation, Abschnitt 4](TSUMUGU_TE
| Tabelle | Wesentliche Spalten | Regeln |
|---|---|---|
| `auth_accounts` | `id`, `email` (unique), `display_name`, `password_hash` (bcrypt), `status` (`active`/`disabled`), `is_superadmin`, `origin` (`operator`/`fixture`) | Konten mit `origin='fixture'` entfernt der Start in jeder Umgebung |
| `auth_sessions` | `id`, `account_id`, `secret_hash` (SHA-256, unique), `csrf_token`, `scope_kind`, `scope_id`, `epoch`, `expires_at`, `revoked_at` | der bestätigte Datenraum steht in der Session |
| `auth_invitations` | `email`, `room_id`, `token_hash`, `invited_by`, `expires_at`, `accepted_at` | 7 Tage gültig |
| `auth_accounts` | `id`, `email` (unique), `display_name`, `password_hash` (bcrypt), `status` (`active`/`disabled`), `is_superadmin`, `origin` (`operator`/`fixture`), `must_change_password`, `password_changed_at`, `last_login_at`, `disabled_at`, `disabled_by`, `account_kind` (`main`/`employee`), `sponsor_id` (Förderer eines Mitarbeiters; nur bei `employee`) | Konten mit `origin='fixture'` entfernt der Start in jeder Umgebung |
| `auth_sessions` | `id`, `account_id`, `secret_hash` (SHA-256, unique), `csrf_token`, `scope_kind`, `scope_id`, `epoch`, `expires_at`, `revoked_at`, `last_seen_at`, `label` (kurzer Gerätehinweis) | der bestätigte Datenraum steht in der Session |
| `auth_invitations` | `email`, `room_id`, `token_hash`, `invited_by`, `expires_at`, `accepted_at`, `role`, `revoked_at` | 7 Tage gültig |
| `data_rooms` | `id`, `kind` (`personal`/`organization`), `name`, `status` (`active`/`archived`), `created_by` | persönlicher Raum: `id = account_id` |
| `room_memberships` | PK (`room_id`, `subject_id`), `role` (`member`/`manager`), `status` (`active`/`removed`) | – |
| `room_memberships` | PK (`room_id`, `subject_id`), `role` (`member`/`manager`/`reader`), `status` (`active`/`removed`) | – |
| `auth_accounts` (Spalte seit 23.10.2026) | `download_defaults` (jsonb: `manager`, `member`, `reader`, `direct`; Voreinstellung für das Herunterladen von Originalen, Standard überall erlaubt) | Neue Räume übernehmen die drei Rollenwerte |
| `data_rooms` (Spalte seit 23.10.2026) | `download_roles` (jsonb: `manager`, `member`, `reader`) | Regel je Raum, nur der Eigentümer ändert sie |
| `data_rooms` (Spalten seit 21.10.2026) | `owner_id` (Eigentümer; für persönliche Räume das Konto), `default_visibility` (`private`/`room`, Voreinstellung für neue Akten und Vorgänge) | Bestehende Räume `private`, Eigentümer aus `created_by` |
| `room_shares` | `resource_kind` (`case`/`matter`), `resource_id`, `room_id`, `access` (`read`/`edit`), `created_by` | Freigabe einer Akte oder eines Vorgangs an einen Datenraum (Team); eindeutig je Eintrag und Raum. Endet, wenn der Freigebende den Raum verlässt oder Leser wird |
| `auth_login_attempts` | `bucket` (SHA-256 aus Adresse und E-Mail), `attempted_at` | zählt Fehlversuche; erfolgreicher Login löscht den Bucket |
## Struktur
@@ -42,17 +47,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/<id>`; 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/<id>`; 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/<asset_id>` |
| `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 +80,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), `last_probe_at`/`last_probe_ok`/`last_probe_detail` (nur Anzeige des letzten Prüfstands) | 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)
+103
View File
@@ -0,0 +1,103 @@
# 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, download)` entsteht je Objekt und Handlungskontext. `download` (Original speichern oder öffnen, Übergabepaket) hat der Owner immer; über einen Raum folgt es `data_rooms.download_roles` der Rolle, bei direkten Grants dem Wert `direct` im Konto des Owners. Es setzt Leserecht voraus, und eine Ausnahme, die das Lesen entzieht, entzieht auch das Herunterladen. Verweigert wird mit 403 und einem erklärenden Text; Lesen in der App bleibt möglich. `_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.
- **Raumfreigabe** (Tabelle `room_shares`): Der Owner teilt eine Akte oder einen Vorgang mit beliebigen Datenräumen, in denen er Mitglied oder Verwalter ist. Der Heimatraum spielt dafür keine Rolle. Aktive Mitglieder eines aktiven Raums erhalten Rechte nach Rolle: Leser lesen, Mitglied und Verwalter lesen und bearbeiten, Weitergeben und Löschen nie (`ROOM_RIGHTS`, `room_default` in `policy.py`). Die Obergrenze der Freigabe (`access = read`) begrenzt auf Lesen. Mehrere Freigaben addieren sich, danach wirken Ausnahmen. Eine Personenausnahme (Grant mit `is_exception` auf eine Person, Kontext leer) nimmt eine Person aus. Elemente und Aufgaben ohne Akte oder Vorgang bleiben beim Owner. Die Rechte der Akte reichen in Vorgänge und Inhalte wie bisher; ein Vorgang kann einzeln geteilt werden, ohne dass die Akte sichtbar wird. Der Owner sieht seine Einträge unabhängig von Raum und Mitgliedschaft. Das Löschen von Akte und Vorgang verlangt Owner oder ausdrückliches Löschrecht, nicht mehr nur Bearbeiten (schließt R-01 des Reviews).
- Kontoarten: Ein Mitarbeiter-Konto legt keine Räume an und keine Inhalte im persönlichen Raum an; es arbeitet in den eingeladenen Räumen nach Raumrolle (`ensure_can_create`, `require_main_user`). Raum-Eigentümer und Einladende sind Hauptnutzer. Beschreibung in [BENUTZERVERWALTUNG.md](BENUTZERVERWALTUNG.md).
- Plattform- und Raumrollen (Betreiber, Verwalter, Mitglied, Leser) und ihre Schutzregeln beschreibt [BENUTZERVERWALTUNG.md](BENUTZERVERWALTUNG.md). Der Leser legt im Raum nichts an und erhält dort keine Bearbeiten- oder Freigeben-Grants; die Auswertung der Objektrechte bleibt unverändert.
- 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-12 (Teilvorgangstiefe), R-15 (Fristen im Elternkontext).
@@ -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.
@@ -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.
@@ -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
@@ -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.
@@ -0,0 +1,61 @@
# Bestandsaufnahme Gitea und Runner (P7, Schritt 1)
**Stand:** 22.10.2026 · Auftrag: [Release-Gate, Backup und Restore](../product/TSUMUGU_RELEASE_GATE_BACKUP_AUFTRAG_2026-10-22.md), Abschnitt 5.1 · Nur lesend erhoben, nichts am Server oder Pi verändert.
**Nachweisarten:** **B** = am Server beobachtet (anonyme API, öffentliche Job-Logs) · **D** = aus Gitea-Dokumentation für 1.22, am Server nicht ausprobiert · **O** = offen, braucht Admin-Zugang oder Sicht auf den Pi.
## 1. Gitea-Server `192.168.2.144:3000` (auch `gitea.stommer.de`)
| Punkt | Befund | Art |
|---|---|---|
| Version | Gitea **1.22.0** | B |
| Sichtbarkeit des Repos | `Lars/tsumugu` ist **öffentlich**. Code, Pull Requests, Commit-Status und **Job-Logs** sind ohne Anmeldung lesbar (z. B. `/Lars/tsumugu/actions/runs/149/jobs/0/logs`). | B |
| Branch-Schutz | `main` und `develop`: `protected=false`, keine Pflicht-Statuschecks, keine Pflicht-Reviews. Jeder mit Schreibrecht kann direkt auf `main` pushen und damit Prod deployen. | B |
| Merge-Stile | Merge, Rebase, Squash und Fast-Forward-only sind erlaubt; Default `merge` | B |
| Bisheriger Release-Weg | PR #1–#8 `develop → main`, jeweils von `Lars` gemergt. `main` steht auf `1bc464e` (18.10.2026). | B |
| Statuskontexte | Gitea setzt sie als `<Workflow-Name> / <Job> (<Event>)`, z. B. `Test Suite / pytest-backend (push)`, `Deploy Production / deploy (push)`. Diese Namen wären als Pflichtchecks verwendbar. | B |
| Pflicht-Statuschecks im Branch-Schutz | vorhanden, mit Mustern | D |
| Menschliche Freigabe per Review | Gitea lässt keine Freigabe des eigenen PR zu. Bei einem einzigen Nutzer `Lars` ist „1 Approval nötig“ nicht erfüllbar. Als Freigabe bleibt der bewusste Merge des Release-PR durch eine Person auf der Merge-Whitelist. | D |
| `jobs.<id>.environment` | wird ignoriert, ist kein Gate (Technische Spezifikation 8.2) | D |
| `concurrency` in Workflows | in 1.22 nicht unterstützt. Serialisierung muss auf dem Host entstehen (`flock`). | D |
| `workflow_dispatch` | Trigger vorhanden; Bedienung über Weboberfläche am Server noch nicht geprüft | D/O |
| Effektive Rechte, Collaborators, Push-/Merge-Whitelist, Repo-Secrets | Anonym nicht lesbar (`branch_protections` → 401) | O |
## 2. Runner
| Punkt | Befund | Art |
|---|---|---|
| Runner | `Raspi5-Paperless`, act_runner **v0.2.11**, Label `ubuntu-latest` | B (Job-Log) |
| Ausführungsmodus | **Host-Modus.** Die Logs zeigen kein Job-Image und kein `docker pull`; die Schritte arbeiten direkt in `/home/lars/docker/tsumugu*` und rufen `docker compose` des Hosts auf. | B |
| Isolation | **Keine.** Jeder Job läuft als Nutzer des Runners auf dem Pi mit Zugriff auf den Docker-Socket, also faktisch mit Root-Rechten. Er erreicht Prod-Checkout, `.env` mit `DB_PASSWORD`, Volumes `tsumugu-db-data` und `tsumugu-media` sowie die Stacks der anderen Produkte auf demselben Pi. | B |
| Mitbenutzung | Die Job-Nummern (8466, 8795) deuten auf einen Runner für mehrere Repositories. Workflows anderer Produkte haben damit dieselbe Reichweite auf Tsumugu-Prod. | B (Indiz) / O |
| Parallelität | Dev-Deploy und Test liefen auch bisher gleichzeitig; Kapazität des Runners nicht gesehen | O |
| Untrusted Code | Heute startet kein Workflow bei `pull_request`. Ein Fork-PR führt daher keinen Code aus. **Das muss so bleiben**, solange der Runner im Host-Modus läuft und das Repo öffentlich ist. | B |
| Werkzeuge auf dem Pi | `age`, `flock`, freier Platz, Ziel für eine Kopie außerhalb des Hosts | O |
## 3. Weitere Beobachtungen für P7
- Die öffentlichen Job-Logs sind ein Kanal nach außen. Backup-, Restore- und Deploy-Schritte dürfen dort keine Secrets, Dateinamen aus der Medienablage oder Inhalte ausgeben.
- `backend/Dockerfile` enthält `tests/` nicht; heute läuft pytest im Laufzeitimage nach `pip install` gegen den eingehängten Checkout (R-27). Für „das gebaute Image testen“ braucht es eine Test-Stufe, die auf genau diesen Image-Schichten aufsetzt.
- Basisimages sind nicht gepinnt (`python:3.12-slim`, `postgres:16-alpine`, Frontend-Basis). Zwei Builds desselben Commits können sich unterscheiden.
- Der Migrator kapselt jede Datei in eine eigene Transaktion. Scheitert Datei *n*, bleiben 1…*n−1* committed. `docker compose up` hat den alten Backend-Container dann schon ersetzt; Prod steht still, bis ein Rückweg greift.
- Zwischen `main` (Prod) und `develop` liegen sieben Migrationen, darunter `20261021T150000Z_room_shares.sql` mit der nicht umkehrbaren Entfernung von `visibility`. Der nächste Merge nach `main` ist damit der erste, für den ein Backup vor der Migration zwingend ist.
- Für die Kontenquarantäne nach Restore gibt es schon `auth_accounts.status` (`active`/`disabled`) und die Tabelle `auth_sessions`.
## 4. Folgerungen für den Entwurf
1. **Gate im Prod-Workflow selbst, nicht im Branch-Schutz allein.** Der Branch-Schutz kann Pflichtchecks und eine Merge-Whitelist erzwingen, das ist ein guter Zusatz. Weil der Runner aber jeden Workflow eines Branches ausführt, prüft `deploy-prod` selbst: Merge-Commit stammt aus einem gemergten PR, der Develop-Stand hat einen grünen Qualifikationsnachweis im Host-Verzeichnis, Trees stimmen überein, frisches Backup liegt vor. Fehlt etwas, bricht der Lauf vor jeder Änderung ab.
2. **Menschliche Freigabe** = Merge des Release-PR durch `Lars` (Merge-Whitelist). Ein zusätzliches Review ist bei einem einzigen Nutzer technisch nicht möglich.
3. **Qualifikationsnachweise** liegen in einem Host-Verzeichnis außerhalb der Checkouts. Workflows können es trotzdem beschreiben; die Herkunft sichert nur der Branch-Schutz plus der Umstand, dass nur `develop`- und `main`-Pushes Workflows starten. Diese Grenze wird im Runbook benannt, nicht kaschiert.
4. **Testlauf** als eigenes Compose-Projekt je Lauf (`tsumugu-test-<run>`), eigene Postgres ohne Hostport, Aufräumen auch bei Fehler. Serialisierung über `flock`, weil `concurrency` fehlt.
5. **Keine Workflows mit `pull_request`-Trigger** auf diesem Runner.
## 5. Offene Punkte für den Nutzer
| Nr. | Frage | Warum |
|---|---|---|
| O-1 | Bleibt das Repository öffentlich? | Öffentliche Job-Logs; ein privates Repo senkt das Risiko ohne Umbau |
| O-2 | Branch-Schutz für `main` setzen (kein direkter Push, Merge nur `Lars`, Pflichtcheck auf den Qualifikationslauf)? | Gitea-Einstellung, nur durch den Nutzer |
| O-3 | Lesender Blick auf den Pi: Runner-Konfiguration (`config.yaml`, Kapazität), Nutzer des Runners, `age`/`flock` vorhanden, freier Platz | Nicht anonym ermittelbar; ich habe keinen SSH-Zugang |
| O-4 | Ziel der Kopie außerhalb des Hosts (z. B. Synology `192.168.2.63`) und Transportweg | Lieferpunkt 4 |
| O-5 | Wo liegt der private `age`-Schlüssel (nicht auf dem Pi, nicht in CI)? | Lieferpunkt 4, Blueprint 10.3 |
@@ -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.
@@ -0,0 +1,101 @@
# 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.
**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 |
|---|---|---|
| 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 vor der Nacharbeit
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.
## Korrektur am 20.10.2026
Auftrag: [TSUMUGU_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md](TSUMUGU_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md). Die Befunde vom selben Tag bleiben unverändert. Die historische Suite oben bleibt unverändert. `tests/test_correction_k1_k7.py` lief danach mit 7 bestandenen Tests. Export, Connector-Nacharbeit und Connector-Basis liefen in derselben lokalen Testdatenbank mit 26 bestandenen Tests. Die Versandtests liefen mit 3 bestandenen Tests. Der Frontend-Build ist durchgelaufen. Kein Push und kein Deployment.
Die Bedienprüfung lief gegen eine lokale API mit nachgebildetem IMAP und einem verzögerten Paperless-Stellvertreter. Das ist keine Prüfung des bestehenden Postfachs und keine Dokumentabfrage der bestehenden Paperless-Instanz.
| Korrektur | Geändertes Verhalten | Nachweis | Ergebnis | Grenze |
|---|---|---|---|---|
| K1 Ordnernamen | Fachnamen, die kein IMAP-Atom sind, werden gequotet. `INBOX` bleibt ungequotet. Ein Fach mit gemeldetem Bestand und leerer abgeschlossener Liste gilt nicht als leer. | Synthetisch: `test_mailbox_names_are_quoted_protocol_strings`, `test_a_filled_folder_with_spaces_is_not_reported_empty`. Bedienung: der Stellvertreter erhielt `INBOX` und `"Sent Items"`; Sent Items zeigte Nachrichten und die Richtung Ausgang. | Synthetisch und in der Bedienung bestanden. | Das bestehende Postfach mit mehr als 4.000 Nachrichten wurde nicht gelesen. |
| K2 MIME | Eine Auswertung für Vorschau, Leser und Export. Anzeigename und Archivname sind getrennt. HTML wird bereinigt; die Textfassung ist gekennzeichnet. Eine angehängte Nachricht bleibt eine Anlage. | Synthetisch: `test_parse_mail_keeps_names_html_and_attached_messages`, `test_preview_below_and_above_the_limit_uses_the_same_parts`. Bedienung: Tabelle, `A & B`, Dateiname `Buero Uebergabe.pdf`, keine Skripte, keine fremde Bildadresse, Textfassung sichtbar. | Synthetisch und am Stellvertreter bestanden. | Keine Nutzermail. Bytezahl und SHA-256 zwischen Download, ZIP und Originalanlage einer betroffenen Mail sind nicht verglichen. |
| K3 Transaktion | IMAP-Lesen, Export und Dateiveröffentlichung laufen ohne offene Fachtransaktion. Der Fachabschluss folgt danach. Ein fehlgeschlagener Abschluss lässt weder den Eintrag noch die veröffentlichten Bytes stehen. | Synthetisch: `test_upload_and_mail_fetch_leave_the_domain_transaction` sah `IDLE` am Upload und am Mailabruf. `test_failed_conclusion_keeps_no_partial_file` ließ keinen Eintrag und keine Prüfbytes zurück. Die bestehenden Versandtests blieben grün. | Für diese beiden Grenzen bestanden. | Entzug während der Veröffentlichung und ein gleichzeitiger Versionskonflikt sind nicht eigens geprüft. |
| K4 Markdown | Der Leser nutzt einen Markdown-Renderer für die Ebenen 1–6, verschachtelte Listen und den Listenstart. HTML, `javascript:`-Links und externe Bilder werden nicht ausgeführt. | Markup-Prüfung der Leserhülle. Bedienung: gespeicherte Notiz mit den genannten Strukturen, Vorschau aus dem Quelltext, Abbrechen stellt die Ansicht wieder her. Bei 360 und 390 px kein Überlauf, Schaltfläche 44 px. | Lesen und Quelltextvorschau bestanden. | Die formatierte Leiste öffnete diese Notiz nicht, weil sie den gespeicherten Text verändert hätte. Der Quelltext blieb maßgeblich. |
| K5 Registrierung | Die Leserhülle ruft die registrierte Darstellung auf. Die Beispielquelle bringt Formular und Registrierung in ihrem eigenen Modul mit und erscheint in der Produktauslieferung nicht. | Die Leserhülle rendert die Testdarstellung und speichert über den registrierten Testeditor. Bedienung mit `?probe=1`: Beispielquelle verbinden, nach „Proben“ suchen, übernehmen, öffnen, erneut öffnen, Übergabepaket prüfen und herunterladen. Der Download antwortete mit 200; der Prüfstand nannte `Probenbrief/Probenbrief.txt`. | Bestanden in der Testoberfläche. | Die Beispielquelle ist kein Produktzugang. |
| K6 Paperless-Antworten | Eine verspätete Suche oder Facette schreibt nicht in die inzwischen gewählte Instanz. Der Instanzwechsel leert Filter und Trefferliste. | Bedienung am Stellvertreter: Suche auf „Alt“ starten, zu „Neu“ wechseln, die späte Antwort abwarten. Zugang, leere Suche und Facette blieben bei Neu. Die anschließende Suche zeigte „Treffer Neu“. Schließen während einer laufenden Suche ließ die Vorgangsliste unverändert. | In der Bedienung bestanden. | Keine echte Paperless-Instanz. |
| K7 Filter und reale Quellen | Der synthetische Paperless-Abruf filtert den Katalog nach Inhalt, Titel, Metadaten, Datum und Seite. | `test_paperless_filters_change_the_hits`: nur der Inhaltstreffer, nur Titel „Vertrag“, die kombinierte Teilmenge und die zweite Seite unterscheiden sich. | Synthetisch bestanden. | Weder die bestehende Paperless-Dokumentabfrage noch das bestehende Postfach wurden ausgeführt. Schema-Lesen vom 19.10. ersetzt das nicht. |
## Konfigurationsansicht am 20.10.2026
Die Konfiguration einer Instanz gehört dem Modul. Ein Modul deklariert `config_fields` (`ConfigField` in `backend/app/sourceregistry.py`) und optional `normalize_config` für Protokollprüfungen. `parse_fields` validiert Pflicht, Typ, Grenzen und unbekannte Schlüssel; ein leeres Geheimnisfeld behält das gespeicherte. `/api/v1/sources/capabilities` liefert die Felder unter `modules`. Die Oberfläche (`frontend/src/sources/config-form.jsx`, `connector-config.jsx`, Route `sources/:connectorId`) rendert sie generisch; ein Modul kann mit `Form` im UI-Registereintrag eine eigene Maske mitbringen. Paperless (Adresse, API-Schlüssel) und IMAP (Server, Port, Verbindung, Benutzer, Passwort, Standardfach) sind darauf umgestellt; die flachen Felder der ersten Lieferung bleiben nur als Kompatibilität in `ConnectorIn`.
Neuer Connector: Modul mit `config_fields` in `register_source` eintragen, UI-Modul mit `registerSourceModule` registrieren. Kein Eingriff in `ConnectorIn`, `Sources.jsx` oder die Fachseiten.
Nachweis und Grenzen: `backend/tests/test_connector_config.py` (Manifest, Geheimnis, Instanzerhalt, Fremdzugriff, Prüfstand) und `frontend/src/sources/config-core.test.mjs` (6 Node-Tests bestanden), Frontend-Build erfolgreich. Die Backend-Tests wurden in dieser Umgebung **nicht ausgeführt** (kein Python, keine PostgreSQL-Instanz). Keine Bedienprüfung im Browser. Zugangsdaten bleiben im Klartext (R-05); Archivmodus und DataPolicy sind nicht Teil dieses Schnitts.
@@ -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.
@@ -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.
@@ -0,0 +1,69 @@
# Prüfung der Connector-Nacharbeit
**Stand:** 20.10.2026. Geprüfter Arbeitsstand: `C:/Dev/tsumugu`. Keine Änderung an Anwendung, Repositorydokumenten oder Datenbanken; kein Push oder Deployment.
## Ergebnis
Die Nacharbeit ist im Code vorhanden und ein deutlicher Fortschritt. Eine vollständige Abnahme des Auftrags ist noch nicht belegt. Die folgenden vier Restpunkte sind konkret eingegrenzt. Ein erneuter Architekturentwurf oder zusätzliche Produktfunktionen sind dafür nicht erforderlich.
## Was tatsächlich hinzugekommen ist
- Gemeinsame Quellenfreigabe über `sourceaccess.py`; der allgemeine E-Mail-Endpunkt verwendet das registrierte Modul statt eines fest eingebauten IMAP-Abrufs.
- Paperless-Filter werden weitergereicht und auf Query, Titel, Korrespondent, Dokumenttyp, Tags, Dokumentdatum und Sortierung abgebildet. Ergebnisseiten und Stammdatenauswahl sind vorhanden.
- IMAP verwendet begrenzte UID-Fenster, unterscheidet Suchfehler von leeren Ergebnissen und führt UIDVALIDITY sowie unvollständige Suchzustände mit.
- Uploads und Versandfassungen verwenden `adapter_for`; die Lösch-/Bereinigungsobjekte können den zuständigen Adapter aufrufen.
- MDXEditor ist lokal eingebunden. Notizen öffnen gerendert, lassen sich mit Formatierungsleiste bearbeiten und wechseln nach dem Speichern zurück zur Leseansicht.
## 1. Externe Abrufe laufen weiterhin teilweise innerhalb einer Fachtransaktion
**Beleg:** `backend/app/sourceaccess.py:125` beendet zunächst die Transaktion. Der IMAP-Callback in `backend/app/sources.py:387` ruft anschließend aber `load_imap_original` auf. Diese Funktion liest in `backend/app/sources.py:1123` über `_owned` erneut aus der Datenbank und startet damit vor `pull_rfc822` wieder eine Transaktion.
Auch `backend/app/sources.py:1251` und `:1272`, die Paperless-/IMAP-Originale für Export und Versandfassungen laden, lösen die Transaktion vor ihrem Netzwerkabruf nicht. Die Freigabeprüfung nach dem Abruf aus der gemeinsamen Lesestrecke wird dort ebenfalls nicht verwendet. Dateiveröffentlichungen in `ops.py` und `correspondence.py` erfolgen weiterhin zwischen Fachschreiboperationen.
**Eigener Nachweis:** Zwei isolierte Python-Prüfungen ohne DB und Netzwerk haben die tatsächlichen Funktionen mit kleinen Verbindungs-/Transportattrappen aufgerufen. Beim Einstieg in den externen Transport war der Status sowohl im IMAP-Lesepfad als auch im Paperless-Exportpfad `INTRANS`.
**Gezielte Nacharbeit:** Die freigegebenen Verbindungsdaten vor dem externen Teil vollständig auflösen. Im externen Teil keine DB-Nachfrage einbauen, die die Transaktion erneut eröffnet. Für Export und Versandfassung ebenfalls vorbereiten, extern lesen und danach erforderliche Rechte/Versionen erneut prüfen. Schreibabläufe ausdrücklich in vorbereitende und abschließende Phasen teilen; kein pauschales Zwischen-Commit als Ersatz für einen sicheren Ablauf. Die abschließende Korrektheit bei Fehler und Entzug testen.
## 2. Markdown-Editor und gespeicherte Leseansicht unterstützen unterschiedliche Formatierung
**Beleg:** `frontend/src/notes.jsx:154` aktiviert Überschriften ohne Einschränkung. Das installierte Plugin bietet Ebenen 1 bis 6 an. `frontend/src/markdown.jsx:61` rendert dagegen nur Ebenen 1 bis 3. Der Renderer behandelt eingerückte Listenelemente als gleichrangig und beginnt geordnete Listen stets bei 1.
**Eigener Nachweis:** Den tatsächlichen `MarkdownView` mit dem vorhandenen JSX-Werkzeug im Speicher übersetzt und mit React serverseitig gerendert. Kein Build und keine Dateischreiboperation im Repository nötig:
- `#### Unterpunkt` ergibt einen Absatz mit sichtbaren vier Rauten statt einer Überschrift.
- `- Ebene 1` mit eingerücktem `- Ebene 2` ergibt zwei gleichrangige Listenelemente.
- Eine mit `5.` beginnende geordnete Liste enthält kein `start`-Attribut und wird damit ab 1 angezeigt.
Der gespeicherte Quelltext wird durch diesen Befund nicht nachweislich verändert. Die Leseansicht stellt seine Bedeutung aber falsch dar.
**Gezielte Nacharbeit:** Einen zum Editor passenden sicheren Markdown-Renderer verwenden und den gemeinsamen unterstützten Umfang testen. Keine weitere Sammlung einzelner Regex-Sonderfälle. Überschriften, verschachtelte Listen und Listenstartwerte nach Bearbeiten, Speichern, erneutem Öffnen und Quelltextwechsel prüfen. Bisherige Schutzregeln zu HTML, gefährlichen Links und externen Medien erhalten.
## 3. Die Darstellungs-/Editor-Registrierung ist noch keine Registrierung ausführbarer Komponenten
**Beleg:** `frontend/src/sources/registry.jsx:29` registriert eine Zuordnung von Mediennamen auf Leserkennungen. `ReadingPane.jsx` entscheidet weiterhin anhand fest eingebauter Kennungen, welche Anzeige ausgeführt wird. Es importiert `NoteEditor` direkt und bindet ihn bei `element.kind === "note"` ein. Die `editors`-Struktur in `registry.jsx:160` ist eine feste Objektliste; ein neuer registrierter Editor wird daraus nicht dynamisch ausgeführt.
Dadurch lassen sich Quellen mit vorhandenen Standardformaten besser ergänzen. Ein neuer Leser oder Editor kann aber weiterhin Änderungen im allgemeinen Reader benötigen. Die Abschlussmatrix beschreibt diesen Teil weitergehend als der Code.
**Gezielte Nacharbeit:** Tatsächliche Komponenten und ihre gemeinsamen Lade-/Speicher-/Konfliktverträge registrieren. Die allgemeine Hülle muss die registrierte Komponente aufrufen. Die interne Notiz bleibt eine Notiz mit ihrem bisherigen Speicherweg; ihre fachliche Identität muss dafür nicht geändert werden.
**Abnahme:** Eine kleine zusätzliche Testdarstellung und einen Testeditor allein durch Module und Registrierung einhängen und über die echte Leserhülle ausführen. Kein neuer produktiver Connector erforderlich. Eine bloße Stringzuordnung genügt nicht.
## 4. Verspätete Paperless-Suchantworten können einen neueren Zustand überschreiben
**Beleg:** `frontend/src/pages/Sources.jsx:256` übernimmt nach jedem Suchaufruf ungeprüft `items`, `next_page` und `connector_id`. Währenddessen kann über das Auswahlfeld bei `:369` die Instanz gewechselt oder eine weitere Suche gestartet werden. Es fehlt eine Anfragenkennung beziehungsweise eine andere Sicherung gegen verspätete Antworten. Der IMAP-Picker hat eine solche Sicherung bereits.
**Auswirkung aus dem Codeablauf:** Eine langsame Suche A kann nach dem Wechsel auf B oder nach einer neueren Suche noch eintreffen und die aktuelle Trefferliste und Instanzauswahl zurücksetzen. Das ist ein belegter möglicher Ablauf; eine Browser-Reproduktion mit künstlicher Verzögerung wurde hier nicht ausgeführt.
**Gezielte Nacharbeit:** Such-, Vorschau- und Stammdatenantworten an Instanz und konkrete Anfrage binden. Überholte Antworten ignorieren beziehungsweise abbrechen. Nach Instanzwechsel fremde Filter-IDs zurücksetzen oder ausdrücklich neu validieren. Bewusst gewählte Treffer weiter anhand ihrer gespeicherten Instanz erhalten.
**Abnahme:** Antwort A künstlich verzögern, zu Instanz B beziehungsweise Suche B wechseln, A erst danach freigeben. Treffer, Vorschau, Filterzustand und Auswahl dürfen nicht auf A zurückspringen.
## Nachweisgrenzen
Die Abschlussmatrix nennt 82 bestandene Backend-Tests und einen erfolgreichen Frontend-Build. Diese vollständigen Läufe wurden bei dieser Prüfung nicht wiederholt. Die zusätzliche Prüfung war gezielt und lesend; sie hat keine echte Quelle und keine Datenbank angesprochen.
Der neue Paperless-Test belegt Parameterübertragung und Paging, sein Fake berechnet jedoch keine echte Filterwirkung: Er liefert dieselben Seitendaten unabhängig vom Suchinhalt. Die tatsächliche Filtersemantik an der Nutzerinstanz ist damit weiterhin offen. Laut Matrix wurde nur deren Schema gelesen.
Der bestehende dritte Source-Test prüft weiterhin die Frontend-Registrierung in Node und die Backend-Strecke. Er belegt keinen vollständigen Bedienablauf des dritten Connectors in der Oberfläche. Für den neuen Editor nennt die Matrix Browserprüfungen; eine zusätzliche eigene Browserprüfung wurde hier nicht vorgenommen.
Die reale Großordner-Abnahme bei IMAP und die Inhalts-/Filterabnahme bei Paperless bleiben nach dem vorliegenden Bericht offen. Bei Abschluss klar zwischen Codeänderung, synthetischem Nachweis und erfolgreichem Test an der echten Quelle unterscheiden.
@@ -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.
@@ -0,0 +1,84 @@
# Sent Items und MIME-Aufbereitung: Befund und gezielter Cursor-Auftrag
**Stand:** 20.10.2026. Geprüft: `C:/Dev/tsumugu`. Keine Änderung an Anwendung oder Repository; keine echte Quelle und keine Datenbank angesprochen.
## Nutzerbeobachtung und Grenzen
Der Ordner „Sent Items“ enthält laut Outlook mehr als 4.000 Nachrichten, erscheint in Tsumugu aber leer. Einige E-Mails mit großen Anlagen wirken in Anzeige und Export verändert; die EML-Datei wird in Outlook korrekt dargestellt.
**Nutzerpräzisierung:** Betroffen sind Dateiname beziehungsweise Anzeige. Eine Veränderung heruntergeladener Dateiinhalte oder fehlende Anlagen wurde vom Nutzer nicht berichtet. Entsprechend liegt der Schwerpunkt auf korrekten Namen und Darstellung; die Byteprüfung ist eine zusätzliche Integritätskontrolle. Der unten separat reproduzierte Verlust angehängter EML-Dateien ist ein zusätzlicher Parserbefund, keine nachträgliche Umdeutung der Nutzerbeobachtung.
Diese beiden Beobachtungen sind ernst zu nehmen. Sie beweisen noch nicht, dass Outlook und Tsumugu denselben serverseitigen Ordner sehen oder dass extrahierte Binäranlagen verändert wurden. Die konkrete Nutzerquelle wurde hier nicht geprüft. Es wurden aber die folgenden Codefehler unabhängig reproduziert.
## Belegte Befunde
### 1. IMAP-Ordnernamen mit Leerzeichen sind nicht korrekt geschützt
`backend/app/sources.py:730` und `:798` übergeben den entquoteten Ordnernamen direkt an `client.select`. Die tatsächlich installierte Python-Bibliothek setzt diesen Parameter in den Befehl ein, ohne ihn automatisch zu quotieren.
Eine Prüfung ohne Socket mit dem tatsächlichen IMAP-Befehlsencoder ergab für `Sent Items`:
```text
T1 EXAMINE Sent Items
```
Für diesen Namen ist eine korrekte IMAP-Stringdarstellung erforderlich, beispielsweise `"Sent Items"`, einschließlich richtigem Escaping. Das ist ein belegter Protokollfehler, aber noch kein Nachweis, dass genau diese Serverantwort beim Nutzer zum Leerzustand führt. Ein strikt ablehnender Server sollte einen Fehler erzeugen; warum der Nutzer „leer“ sieht, muss zusätzlich entlang Serverantwort und UI verfolgt werden.
### 2. Der Sonderweg für große Mailvorschauen verliert den MIME-Kontext
`_fetch_message` wechselt bei mehr als 8.000.000 Rohbytes in `_oversized_message`. `_partial_text` holt einen Ausschnitt von `BODY.PEEK[TEXT]` und parst ihn mit einem künstlichen Subject-Header, aber ohne die ursprünglichen MIME-Header und Multipart-Grenzinformationen.
Ein synthetischer Multipart-Test an der echten `_partial_text`-Funktion zeigte MIME-Header und Base64-Anlageninhalt als Nachrichtentext. Dieser Befund erklärt eine größenabhängig kaputte Vorschau sehr konkret. Er beweist keine Veränderung der Originalanlage im Export; dessen vollständiger Abruf läuft anders.
### 3. Anzeige und Export verwenden eine verlustbehaftete Textfassung
`backend/app/mailpack.py::_html_text` entfernt HTML-Tags mit regulären Ausdrücken. Tabellenstruktur, Layout und Inline-Bilder bleiben dabei nicht erhalten; HTML-Entities werden nicht zuverlässig als Zeichen ausgegeben. Ein Test mit einer HTML-Mail lieferte `A &amp; B` statt `A & B` und eine flache Zeichenfolge statt der Tabelle.
Der Export schreibt `mail.raw` als EML, die Lesefassung aber aus `mail.parsed.text`. Deshalb können EML und Lesefassung unterschiedlich aussehen. Das erklärt die Beobachtung einer Umformatierung, ohne daraus bereits einen Defekt der extrahierten PDF-/Bilddateien abzuleiten.
### 4. Angefügte EML-Nachrichten können unbemerkt fehlen
`parse_mail` überspringt alle Parts mit `is_multipart()`. Das trifft auch auf `message/rfc822` zu. Der anschließende Baumdurchlauf kann dafür den inneren Text einer angehängten E-Mail dem äußeren Nachrichtentext zuschlagen.
Eigener Test: Eine Nachricht mit `weitergeleitet.eml` als Anlage wurde mit **null Anlagen**, **keinem Fehlhinweis** und einer Mischung aus äußerem und innerem Text aufbereitet. Das betrifft auch den Export und seine Vollständigkeitsbehauptung.
### 5. Große Anlagen sind nicht grundsätzlich beschädigt
Eine synthetische gewöhnliche Base64-Anlage mit 9.000.000 Bytes wurde von `parse_mail` mit gleicher Länge und identischem SHA-256 extrahiert. Die konkrete Anlage des Nutzers muss deshalb anhand ihrer tatsächlichen MIME-Struktur und der heruntergeladenen Bytes geprüft werden; „groß“ allein ist noch keine Ursache.
### 6. MIME-kodierte Dateinamen werden je nach Zugriff verschieden angezeigt
Die Vorschau nutzt `_decode`, der vollständige Parser dagegen `_header_text`, das solche Header nicht dekodiert. Mit derselben synthetischen E-Mail wurde reproduziert:
- Vorschau: `Buero Uebergabe.pdf`.
- Reader/Export: `=?utf-8?q?Buero_Uebergabe=2Epdf?=`.
Das passt unmittelbar zur Nutzerpräzisierung. MIME-/Headerdekodierung für Anzeigename und Exportnamen vereinheitlichen, einschließlich RFC-2231-Parametern. Einen sicheren Archiv-Dateinamen vom angezeigten Originalnamen trennen; notwendige Pfadbereinigung und Kollisionsbehandlung erhalten.
## Umsetzungsauftrag an Cursor
Erhalte die bestehende Connector-Architektur und die übrige Nacharbeit. Schließe gezielt diese Fehler, ohne neue Grundlagenanalyse oder zusätzliche Produktfunktionen.
1. Ordnernamen an allen IMAP-Auswahl-/Abrufstellen korrekt als Protokollstrings behandeln. Leerzeichen, Anführungszeichen, Backslash und erforderliche Zeichenkodierung testen. CR/LF weiter ablehnen. Rohname für die Protokolladresse und lesbares Label getrennt halten.
2. Den echten betroffenen Ordner ausschließlich lesend diagnostizieren, soweit eine bestehende autorisierte Verbindung zugänglich ist: Konto/Host und vollständigen Ordnerpfad vergleichen, LIST-Zuordnung, EXAMINE-Status und EXISTS, UIDNEXT/UIDVALIDITY und begrenzte Suchantwort erfassen. Keine Credentials oder privaten Inhalte protokollieren. Outlook-Cache beziehungsweise ein anderer Ordner ist eine zu prüfende Möglichkeit, keine feststehende Erklärung.
3. Wenn EXAMINE einen befüllten Ordner meldet, aber die Aufbereitung keine Einträge ergibt, Leerzustand nicht ungeprüft behaupten. Fehler, nicht abgeschlossene Suche, widersprüchliche Antworten und wirklich leer unterscheiden. Das große-Folder-Paging erhalten; nicht unbegrenzt alle Nachrichten laden.
4. Die große Vorschau über korrekt ausgewählte Text-/HTML-MIME-Parts und deren Transfer-Encoding/Charset aufbauen. Keine beliebig abgeschnittene Multipart-Rohstruktur als fertigen Mailtext ausgeben. Falls eine vollständige Vorschau nicht möglich ist, klar als begrenzt kennzeichnen; MIME-Fragmente und Base64-Blöcke nicht als Nutztext ausgeben.
5. Einen gemeinsamen MIME-Baum für Vorschau, Lesen, Anlagenabruf und Export auswerten. Alternative Körperdarstellungen, related/Inline-Ressourcen und echte Anlagen trennen. Angehängte E-Mails als eigene vollständige Anlage erhalten; deren Inhalt nicht in die äußere Nachricht einmischen. Doppelte Namen bleiben getrennt.
6. EML-Originalbytes unverändert erhalten. Originalanlagen als korrekt transferdekodierte Nutzbytes liefern; keine Bild-/PDF-Neuerzeugung und keine Textdekodierung binärer Nutzdaten. Unbekannte oder nicht sicher dekodierbare MIME-Parts ausdrücklich als Grenze melden, statt unbemerkt Vollständigkeit zu behaupten.
MIME-kodierte Dateinamen in Vorschau, Reader, Download und Export konsistent dekodieren. Anzeigename und sicherer Archiv-Dateiname bleiben unterscheidbar; technische Sicherheitsbereinigung darf keinen unverständlichen MIME-Header als Namen hinterlassen.
7. Für HTML-Mails eine sichere formatierte Ansicht mit vorhandenen lokalen Inline-Ressourcen vorsehen. Skripte, aktive Inhalte und automatische externe Nachladezugriffe sperren. Eine vereinfachte Textfassung darf zusätzlich bestehen, muss als solche erkennbar sein. Keine Zusage pixelgleicher Outlook-Darstellung. Im Export Original-EML und Originalanlagen erhalten; eine formatierte Lesefassung sicher bereitstellen oder verbleibende Darstellungsgrenzen klar benennen. Nicht das unveränderte EML durch eine neu serialisierte Mail ersetzen.
## Konkrete Abnahme
- Sent Items mit Leerzeichen und mehr als 4.000 Nachrichten: derselbe serverseitige Ordner liefert erste Seite und spätere Treffer; Suche findet einen bekannten Treffer. Serverantwort und Anzeige passen zusammen. Zusätzlich Ordnernamen mit Quote/Backslash und ein echter leerer Ordner.
- Dieselbe synthetische MIME-Struktur unterhalb und oberhalb der Vorschaugrenze: gleicher lesbarer Körper und gleiche Anlagenliste, abgesehen von einer ausdrücklich angegebenen Textkürzung. Kein sichtbarer MIME-/Base64-Rest.
- HTML-Tabelle, Entities, Unicode-/kodierte Header und Dateinamen, quoted-printable und Base64, Inline-CID-Bild und angehängte EML prüfen. Innere EML bleibt als Anlage vollständig und getrennt. Nicht unterstützte Sonderformate als solche behandeln.
- Für eine betroffene Nutzer-Mail EML lokal vergleichen. Danach jede extrahierte Anlage zwischen Tsumugu-Download, ZIP-Export und der aus derselben EML korrekt gespeicherten Anlage vergleichen: Bytezahl und SHA-256. Bericht trennt Dateiname, Darstellung und tatsächliche Byteabweichung.
- Export meldet eine ausgelassene oder fehlerhafte Anlage; kein stiller Verlust. Die bestehende Regel „vollständige E-Mail einschließlich aller Anlagen trotz separat abgewähltem Vorkommen“ erhalten.
- Tests synthetisch und an echten Quellen getrennt berichten. Nicht verfügbare Nutzerfälle bleiben offen. Keine produktive DB für Regressionstests, kein Push und kein Deployment.
## Primärquellen
- [RFC 9051 – IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051.html): Mailboxnamen, Protokollstrings, Auswahl und Identität. Weiterhin bestehende IMAP4rev1-Server unterstützen.
- [Python – email.message](https://docs.python.org/3/library/email.message.html): MIME-Baum und `is_multipart()`, insbesondere `message/rfc822`. Details mit der eingesetzten Python-Version abgleichen.
- [RFC 2045 – MIME](https://www.rfc-editor.org/rfc/rfc2045.html): Content-Type und Transfer-Encoding.
@@ -0,0 +1,129 @@
# Korrekturauftrag an Cursor: Connectoren, IMAP, Mailaufbereitung und Markdown
**Stand:** 20.10.2026
**Repository:** `C:/Dev/tsumugu`
**Zielort:** `docs/product/TSUMUGU_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md`
**Umfang:** Die nachstehend gebündelten Korrekturen und ihre lokale Abnahme sind beauftragt. Kein Push und kein Deployment.
## 1. Führender Auftrag und Befundquellen
Dieser Auftrag bündelt beide Prüfberichte vom 20.10.2026. Er ist der gemeinsame Umsetzungseinstieg; die Einzelberichte bleiben die Quellen für Reproduktion, Fundstellen und Nachweisgrenzen. Doppelte Aufgaben nur einmal lösen. Frühere bereits korrekt umgesetzte Funktionen erhalten.
**R – vorherige Prüfung:** [Connector-Nacharbeit: Review vom 20.10.2026](TSUMUGU_CONNECTOR_NACHARBEIT_REVIEW_2026-10-20.md)
- R1 = Abschnitt 1: externe Abrufe und Fachtransaktionen.
- R2 = Abschnitt 2: unterschiedlicher Markdown-Umfang in Editor und Leser.
- R3 = Abschnitt 3: nur nominelle Leser-/Editor-Registrierung.
- R4 = Abschnitt 4: verspätete Paperless-Antworten.
- R-N = Abschnitt „Nachweisgrenzen“: echte Filterwirkung und Bediennachweis des dritten Connectors.
**M – ergänzende Mailprüfung:** [Sent Items und MIME: Befund und Fixauftrag](TSUMUGU_IMAP_SENT_ITEMS_MIME_BEFUND_UND_FIXAUFTRAG_2026-10-20.md)
- M1 = Befund 1: ungeschützte IMAP-Ordnernamen mit Leerzeichen.
- M2 = Befund 2: verlorener MIME-Kontext in großen Vorschauen.
- M3 = Befund 3: verlustbehaftete HTML-Textfassung.
- M4 = Befund 4: ausgelassene angehängte EML und vermischte Nachrichtentexte.
- M5 = Befund 5: synthetischer Integritätsnachweis für eine normale große Anlage.
- M6 = Befund 6: unterschiedliche Dekodierung von Dateinamen.
Die Berichte liegen bei Übergabe gemeinsam mit diesem Auftrag unter:
`C:/Users/lars/Documents/Codex/2026-10-17/lies-zuerst-c-dev-tsumugu-docs/outputs/`
Übernimm die drei Dokumente nach `docs/product`, damit die relativen Verweise dort funktionieren. Verlinke den gemeinsamen Auftrag in `docs/README.md` und der Planungsübergabe. Keine Änderungen an den historischen Befundbehauptungen, um inzwischen erfolgte Korrekturen zu verdecken; neue Ergebnisse ergänzen.
Lies außerdem `AGENTS.md`, die betroffenen bestätigten Entscheidungen in `docs/product/TSUMUGU_PRODUCT_SPEC.md`, die bisherigen Connector-Abschlusskriterien und den Source-/Storage-Vertrag. Die Architekturvorlagen liegen unter **`docs/reference/`**. Bestehende Gestaltung, Fachmodell und Fremdänderungen erhalten. Kein Neustart der Grundlagenarbeit.
## 2. Beobachtung, Befund und offene Ursache
- „Sent Items“ ist laut Nutzer in Outlook mit mehr als 4.000 Nachrichten befüllt, erscheint in Tsumugu aber leer. Die ungeschützte Übermittlung des Namens ist reproduziert; die tatsächliche Ursache des Leerzustands an dieser Nutzerquelle ist noch nicht abschließend nachgewiesen.
- Der Nutzer hat die Anlagenbeobachtung präzisiert: **Dateiname beziehungsweise Anzeige verändert**. Er hat keine beschädigten heruntergeladenen Dateiinhalte und keine fehlenden Anlagen berichtet.
- Die Auslassung angehängter EML ist ein zusätzlicher synthetisch reproduzierter Parserfehler. Sie ist keine Umdeutung der Nutzerbeobachtung.
- Eine gewöhnliche Base64-Anlage mit 9.000.000 Bytes wurde synthetisch bytegleich extrahiert. Das beweist weder einen generellen Defekt großer Anlagen noch die Korrektheit aller MIME-Sonderfälle.
- Die bisherigen 82 Tests und der Build sind gemeldete historische Ergebnisse. Sie ersetzen die gezielte Abnahme der folgenden Korrekturen nicht.
## 3. Gebündelte Korrekturen und Abnahme
### K1 – Sent Items und andere IMAP-Ordner korrekt öffnen
**Quellen:** M1, Nutzerbeobachtung im Mailbericht.
- Ordnernamen in allen Auswahl-/Abrufpfaden als korrekte IMAP-Protokollstrings behandeln: Leerzeichen, Quotes, Backslash und notwendige Zeichenkodierung. Rohname und sichtbares Label getrennt halten. CR/LF weiter ablehnen.
- Den betroffenen Ordner über eine vorhandene autorisierte Verbindung lesend diagnostizieren, soweit erreichbar: Konto/Host und vollständigen Ordnerpfad, LIST-Zuordnung, EXAMINE-Status/EXISTS, UIDNEXT/UIDVALIDITY sowie begrenzte Suchantwort vergleichen. Keine privaten Inhalte oder Credentials protokollieren. Gleichen Ordner in Outlook und IMAP prüfen; nicht ungeprüft Outlook-Cache oder Ordnergröße zur Ursache erklären.
- Bei widersprüchlichen Antworten, fehlgeschlagenem Abruf oder nicht abgeschlossener Suche keinen endgültigen Leerzustand melden. Begrenztes Paging erhalten.
**Abnahme:** Ordner mit Leerzeichen und mehr als 4.000 Nachrichten liefert die erste Seite und einen bekannten späteren Suchtreffer. Zusätzlich echte Leere, Suchfehler, UID-Lücken und Namen mit Quote/Backslash prüfen. Ist die echte Quelle nicht verfügbar, synthetischen Nachweis liefern und die reale Nutzerabnahme ausdrücklich offen lassen.
### K2 – MIME-Aufbereitung, Namen und Maildarstellung vereinheitlichen
**Quellen:** M2, M3, M4, M5, M6.
- Vorschau, vollständiges Lesen, Anlagenabruf und Export verwenden dieselbe fachlich korrekte MIME-Auswertung. Unterschiedliche Größenlimits dürfen keinen Wechsel zu einer falsch interpretierten Rohstruktur erzeugen.
- Große Vorschauen gezielt aus passenden Text-/HTML-Parts und deren Transfer-Encoding/Charset gewinnen. Abgeschnittene Multipart-Fragmente nicht mit künstlichen Headern als fertige Mail parsen. Bei Begrenzung einen klaren Zustand liefern; keine MIME-Header oder Base64-Anlagen als Nachrichtentext anzeigen.
- MIME-kodierte Header und Dateinamen in allen Ansichten konsistent dekodieren, einschließlich RFC-2231-Parametern. Angezeigten Originalnamen von sicherem Archiv-Dateinamen trennen; Pfadbereinigung und Kollisionsbehandlung erhalten.
- Echte Anlagen, HTML-/Textalternativen und lokale Inline-Ressourcen unterscheiden. Angehängte `message/rfc822`-Nachrichten vollständig als eigene Anlage erhalten. Deren Text nicht in die äußere Nachricht mischen. Doppelte Dateinamen bleiben getrennt.
- Eine sichere formatierte HTML-Mailansicht mit lokalen Inline-Ressourcen bereitstellen. Keine Skripte, aktiven Inhalte oder automatischen externen Nachladezugriffe. Eine zusätzliche vereinfachte Textfassung bleibt als solche erkennbar. Keine Zusage pixelgleicher Outlook-Darstellung.
- Original-EML unverändert erhalten. Anlagen als korrekt transferdekodierte Original-Nutzbytes ausgeben, keine PDF-/Bild-Neuerzeugung. Export enthält weiterhin die vollständige EML und alle Anlagen; eine formatierte Lesefassung sicher bereitstellen oder verbleibende Darstellungsgrenzen klar benennen. Fehlerhafte oder ausgelassene Teile nicht still als vollständig melden.
**Abnahme:** Dieselbe MIME-Struktur unter und über der bisherigen 8-MB-Vorschaugrenze; konsistente Körperdarstellung und Anlagenliste. Zusätzlich kodierte Dateinamen, HTML-Tabelle/Entities, Unicode, Base64/quoted-printable, Inline-CID-Bild, doppelte Namen und angehängte EML. Für eine betroffene Nutzer-Mail die Namen und Darstellung direkt vergleichen. Bytezahl und SHA-256 der extrahierten Anlagen zwischen Download, ZIP und korrekt aus derselben EML gespeicherter Anlage als Integritätskontrolle vergleichen. Separat abgewählte Anlage-Vorkommen dürfen weiterhin nicht die Anlagen der exportierten E-Mail entfernen.
### K3 – Externe Arbeit und Fachtransaktion wirklich trennen
**Quelle:** R1.
- Verbindungsdaten vor dem externen Abruf vollständig auflösen. Im externen Abschnitt keine DB-Nachfrage einbauen, die unmittelbar wieder eine Transaktion eröffnet.
- IMAP-Lesen, Quellenexport und Abruf für Versandfassungen über dieselben belastbaren Zugriffsgrenzen führen. Nach externer Arbeit erforderliche aktuelle Rechte, Instanz und Version erneut prüfen.
- Upload-/Snapshot-Veröffentlichung mit sicheren vorbereitenden und abschließenden DB-Phasen sowie nachvollziehbarer Bereinigung ausführen. Ein pauschales Zwischen-Commit ersetzt keinen korrekten Schreibablauf. Bestandsreferenzen, Generationen und gesicherte Versandbytes erhalten.
**Abnahme:** An den tatsächlichen Transport-/Speichergrenzen nachweisen, dass keine Fachtransaktion offen ist; nicht nur prüfen, ob eine Hilfsfunktion vorher `commit` aufruft. Entzug, konkurrierende Änderung, externer Fehler und abschließender DB-Fehler führen zu keiner unberechtigten Ausgabe oder scheinbar vollständig gespeicherten Teilfassung. Keine neue Kryptografie.
### K4 – Gespeicherte Markdown-Ansicht entspricht dem Editor
**Quelle:** R2.
- Einen sicheren, zum Editor passenden Markdown-Renderer einsetzen. Keine weiteren Regex-Sonderfälle als Ersatz für korrekte Markdown-Struktur.
- Vom Editor angebotene Überschriften, verschachtelte Listen und Anfangswerte geordneter Listen im Leser korrekt darstellen. Quelltext außerhalb des unterstützten visuellen Umfangs verlustfrei erhalten.
- Notiz öffnet gerendert; Bearbeiten, Speichern, Abbrechen und Konflikterhalt funktionieren weiterhin. Gemeinsamer Notizinhalt bleibt gemeinsam, lokale Anmerkungen lokal.
**Abnahme:** Überschriften 1–6, verschachtelte Listen, Liste ab 5, Zitate, Links und Code im Editor, nach Speichern, nach Wiederöffnung und nach Quelltextwechsel vergleichen. Quelltext/Export ohne Inhaltsverlust, schädliches HTML/Links und externe Medien weiterhin geschützt.
### K5 – Ausführbare Leser und Editoren registrieren
**Quelle:** R3; ergänzend R-N.
- Tatsächliche Anzeige-/Editorkomponenten mit gemeinsamen Lade-, Speicher-, Abbruch- und Konfliktverträgen registrieren. Die allgemeine Leserhülle ruft die registrierte Komponente auf.
- Eine Zuordnung neuer Mediennamen auf weiterhin fest eingebaute Leserzweige genügt nicht. Neue Leser-/Editorbausteine dürfen keine Änderung an Akten-/Vorgangsseiten oder am allgemeinen Reader verlangen.
- Interne Notizen behalten ihren bisherigen Speicherweg und ihre Identität. Kein künstlicher externer Notiz-Connector und keine neue MD-Dateischreibfunktion.
**Abnahme:** Eine zusätzliche Testdarstellung und einen Testeditor nur durch ihre Module und Registrierung integrieren und tatsächlich über die Leserhülle bedienen. Vorhandenen dritten Test-Connector in der Testoberfläche einrichten, suchen, öffnen, einbinden, erneut öffnen und exportieren. Keine weiteren produktiven Dienste erforderlich; ein reiner Registry-Test in Node genügt nicht.
### K6 – Paperless-Antworten an die aktuelle Anfrage binden
**Quelle:** R4.
- Überholte Such-, Vorschau- und Stammdatenantworten beim Instanz-/Suchwechsel ignorieren oder abbrechen. Sie dürfen weder Ergebnisse noch Instanzauswahl zurücksetzen.
- Fremde Filter-IDs beim Instanzwechsel zurücksetzen oder ausdrücklich neu validieren. Bewusste Auswahl weiterhin unter gespeicherter Instanz und Ressourcen-ID erhalten.
**Abnahme:** Antwort A verzögern, zu Instanz beziehungsweise Suche B wechseln, danach A zustellen. Ergebnisse, Vorschau, Filter und Zugang bleiben bei B. Dasselbe für mehrfache schnelle Wechsel und Schließen der Ansicht prüfen.
### K7 – Noch fehlende Nachweise sauber schließen
**Quelle:** R-N; reale Abnahme im Mailbericht.
- Paperless-Tests müssen Filterwirkung auf unterscheidbaren Testdaten belegen, zusätzlich zur Parameterübertragung: Suchwort nur im Inhalt, getrennte Titeleingrenzung, kombinierte Metadaten-/Datumsfilter und mehrere Seiten. Ein Fake, der unabhängig von den Parametern dieselben Treffer liefert, belegt keine Suchsemantik.
- Reale Paperless-Abnahme an der vorhandenen autorisierten Instanz lesend ausführen, soweit verfügbar. Schemaauslesen und tatsächliche Dokumentabfrage sind verschiedene Nachweise.
- Reale IMAP-Abnahme aus K1 und konkrete problematische Mail aus K2 prüfen, soweit verfügbar. Nicht verfügbare Anschlüsse oder fehlende konkrete Beispieldaten als offen benennen; keine Credentials beschaffen oder Inhalte extern veröffentlichen.
**Abnahme:** Der Abschlussbericht trennt je Punkt Umsetzung, synthetischen Funktionsnachweis, Bediennachweis und tatsächlichen Quellencheck. Ein nicht ausgeführter Realtest erhält keinen Status „bestanden“.
## 4. Durchführung und Abschluss
1. Aktuellen Code gezielt gegen K1–K7 prüfen. Bereits behobene Punkte mit ihrem konkreten Nachweis übernehmen; keine Änderungen nur zum Nachbauen alter Fundstellen. Zeilenangaben in den Berichten beziehen sich auf den damaligen Stand.
2. Mit den unmittelbar störenden Mailproblemen K1/K2 beginnen und die nötigen gemeinsamen Änderungen aus K3/K5 einbeziehen. Bestehende Funktionen weiterverwenden. Die übrigen Korrekturen gehören zum selben Auftrag und werden nicht still zurückgestellt.
3. Passende Regressionstests gezielt ergänzen, dann relevante Gesamttests und Frontend-Build ausführen. Bestandene breite Läufe ohne neue Änderung oder offene Sorge nicht ständig wiederholen. Keine produktive DB für automatisierte Tests.
4. Betroffene UI auf Desktop und bei 390/360 px prüfen: Fokus, Tastatur, Fehler, Laden, Leerzustand und Abbruch. Gewählte Gestaltung und kompakte Inhaltslisten erhalten.
5. Bestehende Abschlussmatrix und betroffene API-/Architekturdokumentation gezielt nachführen. Keine neue vollständige Grundlagen-Spezifikation.
Liefere abschließend eine kurze Matrix mit **K1–K7, geändertem Verhalten, konkretem Nachweis, Ergebnis und verbleibender Grenze**. Bei Blockern deren Auswirkung benennen, während unabhängige Korrekturen weiterlaufen. Ein funktionierender Zwischenstand darf als solcher übergeben werden; den gesamten Auftrag erst bei erfüllten Kriterien als abgeschlossen melden.
Weiterhin außerhalb dieses Auftrags: Finanzfunktionen, KI, bidirektionale Paperless-Synchronisation, neue SaaS-/Runtime-/Kryptografieplattform und produktive weitere Speicheranbieter. Kein Push, Deployment, externer Versand oder Eingriff in andere Produkte.
+16
View File
@@ -19,6 +19,10 @@ 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 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).
**Implementierungsnachweis 20.10.2026, ohne neue Fachversion:** Die Korrektur K1–K7 ist lokal umgesetzt: [TSUMUGU_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md](TSUMUGU_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md). IMAP-Fachnamen mit Leerzeichen, Anführungszeichen oder Backslash gehen als gequotete Protokollargumente an den Server. Die gemeinsame MIME-Auswertung trennt Anzeigenamen und Archivnamen und liefert eine bereinigte HTML-Ansicht neben einer gekennzeichneten Textfassung. Externe Abrufe und die Veröffentlichung von Dateibytes laufen außerhalb der offenen Fachtransaktion; der fachliche Abschluss folgt danach. Der Markdown-Leser stellt die Ebenen 1–6, verschachtelte Listen und den Listenstart dar. Neue Leser hängen an der Registrierung. Verspätete Paperless-Antworten ändern nicht die inzwischen gewählte Instanz. F-02b und F-02c bleiben offen. Eine echte Postfach- und Dokumentprüfung an den bestehenden Zugängen ist nicht erfolgt.
## 2. Gesicherter fachlicher Kern
**Bestätigt durch aktuellen Auftrag und/oder ursprüngliche Nutzeraussagen:**
@@ -432,6 +436,18 @@ Der Nutzer nennt folgende tatsächlich genutzte Felder. Schreibweisen sind als G
**Lieferung und Grenzen zu F-08b/c:** Der gemeinsame [Anforderungs- und Cursor-Auftrag vom 18.10.2026](TSUMUGU_SCHREIBEN_ANLAGEN_VERSAND_AUFTRAG_2026-10-18.md) konkretisiert Anlage-/Nachweisrollen, gesicherte Fassungen, Listen-/Chronologiedarstellung, Bestandsübergang, Kontextrechte und Export einschließlich vollständiger EML gemäß F-07c. Er ersetzt die historische Zurückstellung eines Hauptdokuments/Dokumentpakets für diese neue Lieferung; F-08a bleibt als Kapitelmodell erhalten. Detailregeln des Auftrags sind die aktuelle Umsetzungsausgestaltung, keine Behauptung bereits implementierter oder früher einzeln bestätigter Funktionen. Dieses Dokumentationspaket ändert keine Anwendung, Datenbank oder Bereitstellung.
### R-01 – Datenräume als Teams, Raum-Eigentümer und Raumfreigabe: bestätigt am 20.10.2026
**Beschluss:** Der Nutzer bestätigt: (1) Ein Datenraum ist ein **Team**, kein Ablageort einer Akte. Jede Person kann mehrere Räume anlegen. Ein Raum ist privat, solange nur der Eigentümer Mitglied ist, und wird durch Aufnehmen von Personen zum Mehrbenutzer-Raum. Der persönliche Raum bleibt unverändert. (2) Der Ersteller ist Eigentümer, solange er die Rolle innehat. Er verwaltet Mitglieder, Rollen, Name, Archivierung und Übertragung, liest aber über diese Rolle keine fremden Inhalte. Der Raum ist übertragbar; der Betreiber kann protokolliert einspringen. (3) **Raumfreigabe:** Der Owner einer Akte, Unterakte oder eines Vorgangs teilt sie mit einem oder mehreren seiner Räume, unabhängig davon, wo der Eintrag abgelegt ist. Die Mitglieder erhalten Rechte nach ihrer Rolle im Raum: Leser lesen, Mitglied und Verwalter bearbeiten. Die Freigabe kann auf „nur lesen“ begrenzt werden. Der Owner kann einzelne Personen ausnehmen. Weitergeben, Löschen und Eigentum bleiben beim Owner. Ein Vorgang lässt sich einzeln teilen, ohne dass die Akte oder die übrigen Vorgänge sichtbar werden. (4) Der Owner sieht seine Einträge unabhängig von jedem Raum.
**Begründung und Auswirkungen:** Die Akte bleibt der Rechteanker (F-01, S-01); die Raumfreigabe ist eine zweite, dynamische Rechtequelle neben den Einzelfreigaben je Person. Der Heimatraum eines Eintrags ist nur noch Ablage und Mandantengrenze (Technische Spezifikation 4.1) und bestimmt keine Rechte. Bestehende Freigaben der ersten Fassung (Freigabe an den Heimatraum) wurden in Raumfreigaben übernommen; Einträge ohne Freigabe bleiben privat. Quellzugänge des Owners (Paperless, Mail) werden durch die Raumfreigabe nicht mitgegeben, sondern brauchen weiter die ausdrückliche Freigabe. Elemente und Aufgaben ohne Akte oder Vorgang bleiben beim Owner. Verlässt eine Person ein Team oder wird sie Leser, enden ihre Freigaben an dieses Team. Umsetzungsstand: [BENUTZERVERWALTUNG.md](../architecture/BENUTZERVERWALTUNG.md).
### R-02 – Betreiber, Hauptnutzer und Mitarbeiter: bestätigt am 22.10.2026
**Beschluss:** Der Nutzer bestätigt das SaaS-Zielbild. (1) Der **Betreiber** ist der Superadmin des Dienstes. Er verwaltet die Hauptnutzer, sieht alle Datenräume (Konten, Rollen, Zustand, keine Inhalte) und eine Übersicht aller Teammitglieder, um seiner Rechenschaftspflicht nachzukommen. (2) Ein **Hauptnutzer** erhält später über ein Subscription-Modell seinen eigenen Arbeitsbereich. Er hat einen privaten Raum und beliebig viele Team-Räume, ist deren Eigentümer, lädt Mitarbeiter ein und verwaltet sie und ihre Rechte je Raum. (3) Ein **Mitarbeiter** arbeitet nur in den Räumen, in die er eingeladen wurde, nach der zugewiesenen Rolle. Er legt keine Räume an und führt keinen eigenen privaten Arbeitsbereich. Eine Einladung erzeugt immer ein Mitarbeiter-Konto; vollwertig wird ein Konto nur durch den Betreiber. (4) Die Subscription begrenzt später die Zahl der Mitarbeiter je Hauptnutzer und gegebenenfalls je Raum.
**Begründung und Auswirkungen:** Ohne diese Trennung könnte jeder Raum-Verwalter unbegrenzt vollwertige Konten erzeugen, und der Betreiber hätte keinen Überblick. Umgesetzt sind Kontoart, Förderer, Mein Team, die Team-Übersicht des Betreibers und eine zentrale Prüfstelle für Grenzen ohne Tarife (`access/limits.py`). Offen und für das Sicherheits- und Tarifkonzept vorgesehen: Pläne und Zahlung, die Grenzen selbst, Quellzugänge von Mitarbeitern. Umsetzungsstand: [BENUTZERVERWALTUNG.md](../architecture/BENUTZERVERWALTUNG.md).
## 6. Fortschreibung
16.10.2026, Arbeitsstand 0.1: Recovery vollständig gelesen, Repository-Unterlagen gezielt abgeglichen, ursprüngliche Nutzernachrichten geprüft und Ergänzungen gesichert. Historische Baseline unverändert übernommen.
@@ -0,0 +1,65 @@
# Auftrag: Release-Gate, Backup und Restore für Produktion (P7, Review R-21)
**Stand:** 22.10.2026 · **Status:** Vorbereiteter Umsetzungsauftrag für eine eigene Sitzung, getrennt von der Fachentwicklung. Kein Push auf `main`, kein Eingriff in die laufende Produktion ohne ausdrückliche Freigabe.
## 1. Ziel
Bevor echte personenbezogene Daten in Produktion liegen, muss ein Merge nach `main` sicher sein. Heute baut `deploy-prod.yml` bei jedem Push auf `main` auf dem Host neu und startet die Produktion, ohne Test davor, ohne Backup und ohne Rückweg. Die Migrationen laufen beim Start des Backends und sind teils nicht umkehrbar (zum Beispiel entfernt `20261021T150000Z_room_shares.sql` die Spalten `visibility`).
Gewünscht ist die Reihenfolge des Release-Blueprints: `develop → Dev → Tests → Freigabe → main → Prüfung des Kandidaten → Prod`.
## 2. Lieferumfang
1. **Release-Gate vor Produktion:** `deploy-prod` läuft nur, wenn die Tests für genau diesen Stand grün sind. Zusätzlich eine menschliche Freigabe (Gitea-`environment` allein ersetzt sie nicht, siehe Technische Spezifikation 8.2). Ein roter oder übersprungener Test gilt nie als Erfolg.
2. **Isolierter Testlauf:** Die Tests laufen gegen eine kurzlebige Datenbank je Lauf, nicht gegen die gemeinsame `tsumugu_test`, und nicht doppelt parallel (Review R-27). Der Testlauf prüft das gebaute Image, nicht einen Checkout im Laufzeitcontainer.
3. **Backup vor jeder Migration in Produktion:** konsistente Sicherung von PostgreSQL und Medien (`tsumugu-media`) zu einem gemeinsamen Zeitpunkt, mit Prüfsumme und dokumentiertem Zustand. Das Deploy bricht ab, wenn die Sicherung fehlschlägt.
4. **Aufbewahrung und unabhängige Kopie:** Startprofil laut Blueprint und Spezifikation: RPO 24 h, RTO 4 h, Sicherung alle zwölf Stunden, sieben tägliche, vier wöchentliche, drei monatliche Stände. Mindestens eine Kopie außerhalb des Hosts. Verschlüsselung der Sicherungen, der Schlüssel liegt getrennt vom Backup.
5. **Restore, geprobt:** Wiederherstellung in eine neue Umgebung (nicht über die laufende), zuerst mit synthetischen Daten auf Dev. Nach einem Restore sind alle Sitzungen ungültig, und die Konten werden vor der Freigabe geprüft (Auth-Blueprint 12).
6. **Rückweg bei fehlgeschlagenem Deploy:** Der Ablauf bei einer fehlgeschlagenen Migration oder einem nicht gesunden Start ist beschrieben und getestet: Prod bleibt auf dem alten Stand oder wird aus dem Backup zurückgeholt.
7. **Dokumentation:** `docs/DEPLOYMENT.md` und die Betriebsgrenzen werden fortgeschrieben, ein kurzes Runbook für Backup, Restore und Rückweg ergänzt.
Nicht Teil: Fachfunktionen, ein Umbau der Anwendung, Hybrid- oder Cloud-Betrieb, ein externer Registry-Dienst (R1 mit Imageablage ist bevorzugt, bis dahin ein kontrollierter getrennter Build mit eigenem Gate für genau diesen Kandidaten).
## 3. Grundlagen (zuerst lesen)
- `AGENTS.md`, `docs/DEPLOYMENT.md`, `docs/ENTWICKLUNG_UND_TESTS.md`.
- `docs/reference/Jinkendo_Release_Betrieb_Recovery_Blueprint.md`, insbesondere Abschnitte 1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 und 15. Der Verzeichnisname ist `reference`, Singular.
- `docs/architecture/TSUMUGU_TECHNICAL_SPEC.md`, Paket P7 und Abschnitt 8.2.
- `docs/review/06_BEFUNDE.md` (R-21, R-23, R-27, R-09) und `docs/review/10_NACHPRUEFUNG_2026-10-20.md`.
## 4. Ausgangslage im Repository
- Workflows in `.gitea/workflows/`: `deploy-dev.yml` (Push auf `develop`), `deploy-prod.yml` (Push auf `main`), `test.yml` (Push auf `develop` und nach dem Dev-Deploy, gegen die feste Datenbank `tsumugu_test` der Dev-Postgres).
- Compose: `docker-compose.yml` (Produktion, Volumes `tsumugu-media` und Postgres) und `docker-compose.dev-env.yml` (Dev). Der Host ist ein Raspberry Pi; der Runner läuft dort.
- Migrationen führt das Backend beim Start aus (`backend/app/entrypoint.py`, `backend/app/db/migrate.py`): Ledger mit Prüfsumme, aber ohne Advisory-Lock, ohne Fehlend-Prüfung und mit denselben Zugangsdaten für Migration und Laufzeit (R-09).
- Tests: `powershell -File <lokales Skript> tests` laufen lokal gegen eine eigene PostgreSQL 16 (siehe Abschnitt 6). Zahl der Tests Stand 22.10.2026: 143.
- Es gibt kein Backup, keinen Restore und keinen Rückweg.
## 5. Vorgehen und Grenzen
1. Zuerst eine kurze Bestandsaufnahme: Was kann der Gitea-Server auf `192.168.2.144` an Branch-Schutz, Environments und Freigaben, und wie isoliert ist der Runner? Das ist laut Spezifikation ungeprüft. Ergebnis als kurze Notiz, bevor gebaut wird.
2. Reihenfolge der Arbeit: Testlauf isolieren → Backup und Restore auf Dev bauen und proben → Gate und Freigabe → Anbindung an `deploy-prod` → Rückweg → Runbook.
3. Produktion nicht anhalten und nicht verändern, bevor Backup und Restore auf Dev nachweislich funktionieren. Eine Änderung an `deploy-prod.yml` wird erst nach Freigabe auf `main` wirksam; bis dahin auf `develop` arbeiten.
4. Keine Zugangsdaten, Schlüssel oder Passwörter ins Repository. Secrets liegen in der Betriebsbereitstellung.
5. Vor jedem Push `git pull --rebase`. Die Fachentwicklung läuft parallel auf `develop` in `backend/app`, `frontend/src` und `docs/architecture`. Dieser Auftrag fasst vor allem `.gitea/workflows/`, `docker-compose*.yml`, Betriebsskripte und `docs/DEPLOYMENT.md` an.
6. Kein Push auf `main` und kein Merge ohne ausdrückliche Anweisung des Nutzers. Jede Aktion am Raspberry Pi (Anlegen von Verzeichnissen, Cron/Timer, Schlüssel) ist vorher zu benennen und freizugeben.
## 6. Lokale Testumgebung
Auf dem Entwicklungsrechner liegt eine isolierte Umgebung unter `C:\dev\tsumugu-local` (portable PostgreSQL 16 auf `127.0.0.1:55432`, Python 3.12, virtuelle Umgebung). Der Aufruf `powershell -File C:\dev\tsumugu-local\run-tests.ps1 tests` startet die Datenbank und führt die Suite aus (rund vier Minuten). Sie berührt keine Server. Die Testdatenbank muss auf `_test` enden; das erzwingt die Suite.
## 7. Abnahme
| Nr. | Nachweis |
|---|---|
| 1 | Ein roter Test oder ein fehlendes Backup verhindert das Produktions-Deploy; der Ablauf bricht ab und meldet den Grund. |
| 2 | Zwei gleichzeitige Testläufe stören sich nicht (eigene Datenbank je Lauf). |
| 3 | Eine Sicherung von Datenbank und Medien entsteht vor der Migration, mit Prüfsumme; Restore in eine neue Umgebung stellt beide wieder her. Das Ergebnis wird mit synthetischen Daten geprüft. |
| 4 | Nach dem Restore sind Sitzungen ungültig und Konten gesperrt, bis sie freigegeben sind. |
| 5 | Ein absichtlich fehlerhafter Migrationsstand auf Dev lässt die Umgebung nicht halb migriert zurück; der Rückweg ist beschrieben und geprobt. |
| 6 | Aufbewahrung und die Kopie außerhalb des Hosts sind eingerichtet und überprüft. |
| 7 | Runbook und `docs/DEPLOYMENT.md` sind aktuell. Reale Prod-Aktionen sind vom Nutzer freigegeben und im Bericht von synthetischen Nachweisen getrennt. |
## 8. Übergabe
Kurzer Abschlussbericht: je Lieferpunkt Ergebnis, ausgeführte Tests, was nur synthetisch nachgewiesen und was an Prod noch offen ist. Neue Dokumente in `docs/README.md` verlinken und die Befunde R-21 und R-27 im Review fortschreiben.
@@ -1,5 +1,9 @@
# Tsumugu – Übergabe zur fachlichen Weiterplanung
**Nachtrag 20.10.2026:** Der Korrekturauftrag K1–K7 ist lokal umgesetzt und nicht deployed. Auftrag, Mailbefund und Review stehen in [TSUMUGU_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md](TSUMUGU_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md). Die Nachweise und die offenen echten Quellenprüfungen stehen am Ende der [Abschlussmatrix](TSUMUGU_CONNECTOR_ABSCHLUSSMATRIX_2026-10-19.md). Ein lebendes Postfach und eine echte Paperless-Dokumentabfrage bleiben offen.
**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.
## 1. Aktueller Auftrag und Arbeitsweise
@@ -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=<veränderliches dict>`. 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/<feature>/{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.**
@@ -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.**
@@ -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` |
@@ -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 `<img>`, 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 /<parent>/{id}/media-links` | Bekanntes sichtbares Asset, erwartete Parent-/Assetversion; aktive kompatible Verknüpfung erstellen |
| `DELETE /<parent>/{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` |
@@ -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` |
@@ -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_id>/
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.<job_id>.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-<safe_run_id>`, 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 <staging/db.dump> --dbname <approved_db_name>`. 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 <recipient_file>`); 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 <new_target_db> <verified_db.dump>`. 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 <profile>` | Read-only: registriertes Ziel, aktueller Stand, effektive Giteafähigkeiten, offene Voraussetzungen als sicheres JSON |
| `python -m ops.release verify --profile <profile> --release-id <id>` | Quell-/Gate-/Merge-/Artefaktbeziehung lesen und prüfen; keine Liveänderung |
| `python -m ops.release plan --profile <profile> --release-id <id> --expect-current <generation>` | Gebundenen Deploymentplan und dessen Hash in geschützter Planablage erzeugen |
| `python -m ops.release apply --profile <profile> --plan-id <id> --plan-sha256 <hash>` | Unter Lock nach erneuter Prüfung den geplanten Release ausführen |
| `python -m ops.release reconcile --profile <profile> --operation-id <id>` | Tatsächlichen Zustand lesen und zulässigen Fortsetzungsplan erstellen; Änderungen erst über dessen `apply` |
| `python -m ops.backup create --profile <profile>` | Gemeinsame Lease, konsistent aufnehmen, verschlüsseln, unabhängig kopieren, Receipt |
| `python -m ops.backup verify --profile <profile> --backup-id <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 <profile>` | Read-only-Plan der löschbaren IDs einschließlich Bindungs-/Holdprüfung erzeugen |
| `python -m ops.backup prune --profile <profile> --plan-id <id> --plan-sha256 <hash>` | Ausschließlich zuvor berechnete ungebundene Backup-IDs entfernen; kein automatischer Erfolgspfad bei fehlgeschlagener Sicherung |
| `python -m ops.restore plan --profile <profile> --backup-id <id> --expect-current <generation>` | Restoreziel, Datenstand, Keys/Images, Verlustfenster und Quarantäne planen |
| `python -m ops.restore apply --profile <profile> --plan-id <id> --plan-sha256 <hash>` | Neuen DB-/Medienstand vorbereiten, prüfen und kontrolliert umschalten |
| `python -m ops.restore drill --profile <test-profile> --fixture-set <id>` | Synthetische End-to-End-Übung ohne Livecredentials; Ergebnisbericht |
| `python -m ops.status --profile <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.**
@@ -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.<job_id>.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.
@@ -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
<product>/
├── 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/<feature>/ # 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/<feature>/ # 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<DTO | undefined>; 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.
@@ -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.
@@ -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.<job_id>.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.<job_id>.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.
@@ -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
<product>/
@@ -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.
Loaded 100 of 169 files, more files were not shown because too many files have changed in this diff. Show more