From e2475555c0d9ab8c21271a32d0ebdc7e2be0498c Mon Sep 17 00:00:00 2001 From: Stommer Date: Fri, 23 Oct 2026 06:59:45 +0200 Subject: [PATCH] =?UTF-8?q?Aktualisiere=20die=20Dokumentation=20f=C3=BCr?= =?UTF-8?q?=20Download-Regel,=20HTML-Mail,=20Bilder=20und=20R-11.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/MVP_ANNAHMEN.md | 3 +++ docs/architecture/API_REFERENZ.md | 21 ++++++++++++--------- docs/architecture/BENUTZERVERWALTUNG.md | 4 ++++ docs/architecture/DATENMODELL_IST.md | 2 ++ docs/architecture/RECHTEMODELL_IST.md | 4 ++-- docs/review/06_BEFUNDE.md | 2 +- docs/review/README.md | 2 +- 7 files changed, 25 insertions(+), 13 deletions(-) diff --git a/docs/MVP_ANNAHMEN.md b/docs/MVP_ANNAHMEN.md index 697cb65..cafad8d 100644 --- a/docs/MVP_ANNAHMEN.md +++ b/docs/MVP_ANNAHMEN.md @@ -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. diff --git a/docs/architecture/API_REFERENZ.md b/docs/architecture/API_REFERENZ.md index c1cf502..4d67450 100644 --- a/docs/architecture/API_REFERENZ.md +++ b/docs/architecture/API_REFERENZ.md @@ -1,6 +1,6 @@ # Tsumugu – API-Referenz (Ist-Stand) -**Stand:** 18.10.2026, ergänzt am 19.10.2026 um Quelleninstanzen, Fähigkeiten und Zuordnung. Erstellt im Code-Review aus `backend/app/main.py`, `api/routes.py`, `api/sources.py`, `api/export.py` und `api/correspondence.py`. +**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. @@ -33,6 +33,7 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R** |---|---|---|---| | 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 | @@ -59,6 +60,7 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R** | 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 | | 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 | @@ -142,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) | @@ -174,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 | @@ -198,10 +200,11 @@ Legende Spalte „Auth“: **–** öffentlich, **S** gültige Session, **S+R** | 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, Fortsetzung über `before` | | GET | `/api/v1/sources/imap/message?connector_id=&mailbox=&uid=` | Vorschau vor dem Übernehmen | -| GET | `/api/v1/external-refs/{id}/content` | Original der gebundenen Instanz über das registrierte Modul (`inline`) | -| GET | `/api/v1/external-refs/{id}/mail` | vollständige E-Mail als JSON, Identität per Message-ID geprüft | -| GET | `/api/v1/external-refs/{id}/mail/original` | EML | -| GET | `/api/v1/external-refs/{id}/mail/attachments/{index}` | Anlage (`inline`, siehe Review R-03) | +| 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 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). @@ -212,7 +215,7 @@ Quelleninhalte einer eigenen Referenz laufen über die gebundene Instanz. Eine f |---|---|---| | 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 diff --git a/docs/architecture/BENUTZERVERWALTUNG.md b/docs/architecture/BENUTZERVERWALTUNG.md index 72d387e..bdf9ca7 100644 --- a/docs/architecture/BENUTZERVERWALTUNG.md +++ b/docs/architecture/BENUTZERVERWALTUNG.md @@ -112,3 +112,7 @@ Die Mail wird formatiert (Standard) oder als Text gezeigt. Der Server bereinigt ### 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. diff --git a/docs/architecture/DATENMODELL_IST.md b/docs/architecture/DATENMODELL_IST.md index 5a0d308..e800dc8 100644 --- a/docs/architecture/DATENMODELL_IST.md +++ b/docs/architecture/DATENMODELL_IST.md @@ -21,6 +21,8 @@ Die Sollfassung steht in der [technischen Spezifikation, Abschnitt 4](TSUMUGU_TE | `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`/`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 | diff --git a/docs/architecture/RECHTEMODELL_IST.md b/docs/architecture/RECHTEMODELL_IST.md index aaae5b5..5759345 100644 --- a/docs/architecture/RECHTEMODELL_IST.md +++ b/docs/architecture/RECHTEMODELL_IST.md @@ -14,7 +14,7 @@ Der Datenraum bestimmt, **wo neue Objekte entstehen**. Er ist nicht der Rechtepf ## 2. Rechte und Antwortcodes -Ein Ergebnis `Rights(read, edit, share, delete)` entsteht je Objekt und Handlungskontext. `_require` übersetzt: +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** @@ -100,4 +100,4 @@ Danach Abzug der jeweiligen Ausnahme. ## 6. Bekannte Abweichungen -Siehe [Review-Befunde](../review/06_BEFUNDE.md): R-01 (Behälter löschen), R-02 (Detach/Anmerkung), R-07 (Vorgangsausnahme), R-11 (Übersicht/Suche), R-12 (Teilvorgangstiefe), R-15 (Fristen im Elternkontext). +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). diff --git a/docs/review/06_BEFUNDE.md b/docs/review/06_BEFUNDE.md index 0cf958e..04ccc62 100644 --- a/docs/review/06_BEFUNDE.md +++ b/docs/review/06_BEFUNDE.md @@ -16,7 +16,7 @@ Schweregrade siehe [01](01_METHODIK_UND_QUELLEN.md#schweregrade-der-befunde). Fu | R-08 | Hoch | Auth | Session- und Login-Härtung unter dem Blueprint-Vertrag | | R-09 | Mittel | Datenbank | Gemeinsame Zugangsdaten für Runtime und Migration, Migrator ohne Lock | | R-10 | Mittel | Quellen | Quelleninhalte werden über den Zugang des Betrachters geladen | -| R-11 | Hoch | Korrektheit | `LIMIT` vor der Rechteprüfung in Übersicht und Suche | +| R-11 | Hoch | Korrektheit | `LIMIT` vor der Rechteprüfung in Übersicht und Suche (behoben am 23.10.2026) | | R-12 | Mittel | Korrektheit | Verschieben erzeugt eine zweite Teilvorgangsebene | | R-13 | Mittel | Export | Gelöschte oder unsichtbare Bezugsziele blockieren das Übergabepaket | | R-14 | Mittel | Daten | Gelöschte Akte oder gelöschter Vorgang lässt Inhalte unauffindbar zurück | diff --git a/docs/review/README.md b/docs/review/README.md index e146a55..7d3c586 100644 --- a/docs/review/README.md +++ b/docs/review/README.md @@ -52,7 +52,7 @@ Nichts davon verlangt einen Umbau. Die meisten Punkte lassen sich gezielt im Bes | R-02 | Hoch | `DELETE /bindings/{id}` prüft die Zugehörigkeit der Einbindung zum Handlungskontext nicht | | R-03 | Hoch | E-Mail-Anlagen und Paperless-Bilder (auch SVG) werden `inline` aus dem App-Origin ausgeliefert | | R-04 | Hoch | Betreiberkonto über eine öffentliche Web-Route, ohne MFA (Abweichung von ADR-05 und Auth-Blueprint 11.3) | -| R-11 | Hoch | Offene Aufgaben, Fristen und Suche: `LIMIT` vor der Rechteprüfung. Sichtbare Treffer fallen weg | +| R-11 | Hoch | **Behoben am 23.10.2026.** Offene Aufgaben, Fristen und Suche lesen in Blöcken und prüfen die Rechte vor der Begrenzung (Vorfilterung im SQL bleibt eine spätere Optimierung) | | R-08 | Hoch | Sessions 14 Tage ohne Leerlaufablauf und Rotation, Login-Begrenzung nur im Prozessspeicher, kein Passwortwechsel | | R-31 | Hoch | Hochgeladene Fotos behalten EXIF- und GPS-Metadaten, es gibt keine Normalisierung |