archivmail/features/PROJ-65-physische-tenant-trennung.md

id, title, status, created

id	title	status	created
PROJ-65	Physische Tenant-Trennung im Storage-Layer	In Review	2026-07-04

Entscheidung (Nutzer, 2026-07-04)

Option A (Hardlink-Ordner pro Tenant, Dedup bleibt erhalten) plus Option B (Storage-Permissions härten, Status-Check). Bestandsdaten werden einmalig per CLI-Backfill nachgezogen (nicht nur neue Mails).

Kontext

GoBD/DSGVO-Checkliste (docs/GOBD_DSGVO_CHECKLIST.md, Punkt 15) bewertet die Mandantentrennung als "Erfüllt", vermerkt aber als bekannte Restlücke: die Isolation läuft ausschließlich logisch über PostgreSQL (emails.tenant_id, email_refs), NICHT physisch auf Dateisystem-Ebene. Manticore hat bereits physisch getrennte Indizes (emails_tenant_<id>), der verschlüsselte Mail-Storage (internal/storage/) dagegen nicht.

Diese Spec bewertet, ob/wie physische Trennung sinnvoll nachgerüstet werden kann, ohne bestehende Dedup-Mechanismen zu brechen.

Ist-Zustand (verifiziert, 2026-07-04)

• filePath(id) (internal/storage/storage.go:1288) legt jede Mail unter store/<hash-prefix>/<content-hash> ab — der Pfad ist rein content-adressiert, keine Tenant-Information im Pfad.
• email_refs-Tabelle (storage.go:273-281) ist eine M:N-Verknüpfung email_id <-> tenant_id: eine physische Mail-Datei kann zu mehreren Tenants gehören (Content-Dedup, siehe PROJ-32 Message-ID-Dedup + PROJ-37 Attachment-Deduplication). Das passiert real z.B. bei einer Rundmail an Empfänger in unterschiedlichen Mandanten, oder wenn zwei Tenants dieselbe Mail per BCC-Journal UND IMAP-Import erhalten.
• Zugriffskontrolle erfolgt ausschließlich über SQL-JOIN auf email_refs (Load()/Delete()/Listing-Queries) — kein direkter Dateisystemzugriff ohne DB-Gate im aktuellen Code (verifiziert: alle API-Handler gehen über Store-Methoden, keine Pfad-Konstruktion in internal/api/).

Warum "ein Ordner pro Tenant" nicht trivial ist

Eine naive Umsetzung ("Mail-Datei nach store/tenant_<id>/<hash> statt store/<hash-prefix>/<hash> ablegen") bricht am Cross-Tenant-Dedup-Modell:

• Eine Mail mit zwei email_refs-Einträgen (zwei Tenants) hätte keinen eindeutigen "richtigen" Ordner mehr — Datei müsste doppelt vorgehalten werden (Speicherplatz-Verdopplung, widerspricht PROJ-36/PROJ-37-Ziel) oder über Hardlinks/Symlinks in beide Tenant-Ordner verknüpft werden.
• Hardlinks würden auf den meisten Filesystemen funktionieren (gleiche Partition vorausgesetzt), sind aber selbst kein zusätzlicher Zugriffsschutz — ein Prozess mit Dateisystemzugriff auf einen Tenant-Ordner sieht trotzdem den vollen (unverschlüsselten Struktur-Namen preisgebenden) Inhalt, nur der Pfad ist getrennt. Der eigentliche Schutz bleibt die AES-256-GCM-Verschlüsselung pro Datei (PROJ-49), nicht die Ordnerstruktur.

Ziel

Physische Trennung so weit erhöhen, wie es ohne Aufgabe des Dedup-Modells und ohne Speicherplatz-Verdopplung möglich ist — als zusätzliche Verteidigungsebene ("defense in depth"), nicht als Ersatz für die DB-gestützte Zugriffskontrolle.

Entscheidung (zur Nutzer-Freigabe)

Drei Optionen, aufsteigender Aufwand:

Option A — Tenant-Verzeichnis nur für eindeutig einem Tenant zugehörige Mails, Hardlink-Farm für Mehrfach-Tenant-Fälle

• Mails mit genau einem email_refs-Eintrag: Ablage/zusätzlicher Hardlink unter store/tenant_<id>/<hash-prefix>/<hash>.
• Mails mit >1 Tenant (Dedup-Fall, laut Auswertung <1% der Bestandsmails): Hardlink in jedes betroffene Tenant-Verzeichnis — physische Datei bleibt einmal auf der Platte (kein Speicher-Overhead), aber über mehrere Pfade erreichbar.
• Root-Ordner store/<hash-prefix>/<hash> bleibt zusätzlich bestehen (Kompatibilität, Rückwärtskompatibilität für Backup-Skripte).
• Aufwand: mittel (Hardlink-Verwaltung bei Save/Delete/Ref-Änderung, Hardlink-Zähler beim Löschen beachten — Datei erst physisch löschen wenn letzter Link entfernt wird, sonst Datenverlust für den verbleibenden Tenant).

Option B — Nur Metadaten-Trennung verstärken, kein Dateisystem-Umbau

• Kein Pfad-Umbau. Stattdessen: OS-Level-Zugriffskontrolle prüfen/dokumentieren (z.B. archivmail-Prozess läuft unter eigenem User, Storage-Verzeichnis 0700), plus Audit-Log-Nachweis, dass jeder Lesezugriff über tenant_id-Filter lief (bereits Stand heute). Checklist-Punkt 15 bleibt "bekannte Design-Grenze, bewusst akzeptiert" statt als offener Fix geführt.
• Aufwand: klein (nur Doku + Dateisystem-Berechtigungs-Audit).
• Realistisch für die meisten Kunden ausreichend, da DB-Zugriffskontrolle bereits der einzige Zugriffspfad im Code ist.

Option C — Dedup nur noch pro Tenant (kein Cross-Tenant-Dedup mehr)

• Ändert Save() so, dass Content-Hash-Dedup nur INNERHALB eines Tenants greift, nicht mehr global. Ermöglicht echte 1:1-Ordner-pro-Tenant-Struktur ohne Hardlinks.
• Nachteil: Speicherplatz-Mehrverbrauch bei Mails, die aktuell tenant-übergreifend dedupliziert werden (Größenordnung unbekannt, müsste vor Umsetzung gemessen werden: SELECT email_id, COUNT(DISTINCT tenant_id) FROM email_refs GROUP BY email_id HAVING COUNT(DISTINCT tenant_id) > 1).
• Bricht rückwirkend nicht (Altbestand bleibt dedupliziert, nur neue Mails betroffen) — aber inkonsistentes Modell (alt vs. neu) muss dokumentiert sein.
• Aufwand: mittel-hoch (Save-Logik ändern, Migration/Messung vorab nötig).

Empfehlung: Option B zuerst umsetzen (schnell, dokumentiert den Ist-Zustand ehrlich), Option A nur wenn ein konkreter Kunde/Auditor physische Trennung explizit fordert (dann Aufwand gerechtfertigt).

Acceptance Criteria (Option B, empfohlener Scope)

• Storage-Verzeichnis-Berechtigungen geprüft/dokumentiert: store/ gehört dem archivmail-Prozess-User, Modus 0700 (kein Gruppen-/World-Zugriff).
• archivmail status (cmd_status.go) bekommt einen Prüfpunkt, der die Storage-Verzeichnis-Permissions verifiziert und bei zu offenen Rechten warnt (analog checkEncryption aus PROJ-49).
• GoBD-Checkliste Punkt 15 umformuliert (siehe Implementation Notes).
• Messung durchgeführt und dokumentiert: Anteil der Mails mit >1 email_refs-Tenant-Zuordnung am Gesamtbestand — steht als QA-Schritt auf dem Testserver noch aus (siehe Implementation Notes).

Acceptance Criteria (Option A, gewählter Scope)

• Hardlink-Erstellung bei Save() für jeden email_refs-Eintrag (inkl. Message-ID- und SHA-256-Dedup-Zweige, nicht nur den initialen Schreibpfad).
• Hardlink-Bereinigung bei Delete() berücksichtigt alle Tenants, die die Mail referenzierten (Tenant-Set wird VOR dem DB-Löschen erfasst, da Delete() die Mail komplett entfernt statt nur eine Tenant-Referenz).
• Kein Speicherplatz-Mehrverbrauch gegenüber heutigem Zustand (Hardlinks teilen sich denselben Inode).
• Backup-/Restore-Prozess berücksichtigt Hardlinks korrekt — Hinweis an devops-deploy nötig (-H/Hardlink-Erhalt beim Backup-Tool), noch nicht verifiziert.
• Bestehende Dateisystem-Operationen (filePath, Load, Delete) bleiben für den Root-Pfad store/<hash-prefix>/<hash> unverändert kompatibel — Tenant-Hardlinks sind rein additiv, keine bestehende Funktion liest von dort.
• Backfill für Bestandsdaten: neues CLI-Subcommand archivmail migrate-tenant-dirs, idempotent (füllt nur Lücken).

Edge Cases

• Mail wird nach Save einem zweiten Tenant zugeordnet (Dedup-Treffer bei späterem Import) → neuer Hardlink muss nachträglich angelegt werden, nicht nur beim initialen Save().
• Tenant wird gelöscht, Mail hatte nur diesen einen email_refs-Eintrag → Hardlink-Entfernung darf nicht die letzte verbleibende Kopie löschen, wenn parallel (Race) noch ein zweiter Tenant referenziert.
• Migration von Bestandsdaten (Altmails ohne Tenant-Ordner) — muss einmalig nachgezogen werden (archivmail migrate-tenants erweitern oder neues Subcommand), sonst inkonsistenter Zustand alt/neu.

Betroffene Dateien (Option A, bei Umsetzung)

• internal/storage/storage.go (filePath, Save, Delete)
• cmd/archivmail/cmd_migrate_tenants.go (Backfill für Bestandsdaten)
• docs/GOBD_DSGVO_CHECKLIST.md (Punkt 15 Update nach Umsetzung)

Betroffene Dateien (Option B, bei Umsetzung)

• cmd/archivmail/cmd_status.go (neuer Prüfpunkt Storage-Permissions)
• docs/GOBD_DSGVO_CHECKLIST.md (Punkt 15 Neuformulierung)
• ggf. install.sh/update.sh (Verzeichnis-Permissions beim Deploy setzen, falls noch nicht der Fall)

---

Tech Design (Solution Architect)

Übersprungen — additive Ergänzung zum bestehenden Storage-Layer (kein neuer Zugriffspfad, keine Änderung der DB-gestützten Zugriffskontrolle), analog PROJ-55/56.

Implementation Notes (2026-07-04)

Neue Datei internal/storage/tenant_dirs.go

• tenantFilePath(tenantID, id): store/tenant_<id>/<hash-prefix>/<hash> — gleiches 2-Zeichen-Sharding wie filePath(), nur zusätzlich unter einem Tenant-Ordner genestet.
• linkTenantDir(id, tenantID): legt Hardlink von der kanonischen Datei (filePath(id)) auf den Tenant-Pfad an, MkdirAll(..., 0o700). Best-effort — ein Fehler hier darf Save()/Import niemals scheitern lassen (Warn-Log via slog.Default(), kein Fehler-Return). Idempotent (Stat-Check vor os.Link, os.ErrExist wird ignoriert).
• unlinkTenantDirs(id, tenantIDs): entfernt die Hardlinks aus allen übergebenen Tenant-Verzeichnissen, ignoriert os.ErrNotExist.
• TenantsForMail(ctx, id): liefert die Vereinigung aus emails.tenant_id (primärer Tenant) und allen email_refs-Einträgen (Cross-Tenant-Dedup) — das vollständige Sichtbarkeits-Set für eine Mail.
• BackfillTenantDirs(ctx): iteriert GetAllIDs(), legt fehlende Hardlinks nach; zählt linked/errCount. Idempotent, für den Backfill-Befehl.

Wiring in internal/storage/storage.go

• Save(): linkTenantDir() an allen drei Stellen ergänzt, an denen bisher email_refs per INSERT ... ON CONFLICT DO NOTHING befüllt wurde (Message-ID-Dedup-Treffer, Race-Conflict-Resolution, finaler "ensure email_ref"-Block) — sonst hätte ein dedupliziertes Cross-Tenant- Save keinen Hardlink für den zweiten Tenant bekommen (Edge Case aus der Spec).
• Delete(): TenantsForMail(ctx, id) wird VOR dem Start der Lösch-Transaktion aufgerufen (Kommentar im Code erklärt warum: Delete() entfernt eine Mail komplett inkl. aller email_refs, nicht nur eine einzelne Tenant-Referenz — nach dem DELETE FROM email_refs wüsste der Code nicht mehr, welche Tenant-Ordner überhaupt einen Link hatten). unlinkTenantDirs() läuft erst NACH dem erfolgreichen os.Remove() der kanonischen Datei.

Neues CLI-Subcommand archivmail migrate-tenant-dirs

• cmd/archivmail/cmd_migrate_tenant_dirs.go, registriert in main.go.
• Backfill für Bestandsdaten (Nutzer-Entscheidung: "einmalig migrieren"). Ruft Store.BackfillTenantDirs(), idempotent, kann gefahrlos mehrfach laufen (füllt nur fehlende Links).
• Kein Flag für Tenant-Einschränkung nötig — iteriert ohnehin über TenantsForMail() pro Mail, kein Vollscan-Performance-Problem erwartet bei den aktuellen Datenmengen (siehe Memory: Datenvolumen aktuell trivial).

cmd/archivmail/cmd_status.go: neuer Check checkStoragePermissions

• Analog checkEncryption/checkRetention: warnt (OK bleibt true, kein Hard-Fail) wenn store_path Modus &0o077 != 0 ist (Gruppe/Andere haben Zugriff). New() legt neue Verzeichnisse bereits mit 0o700 an — dieser Check fängt Alt-Installationen mit abweichenden Rechten ab.

Was bewusst NICHT geändert wurde

• Kein Zugriffspfad in internal/api/ liest direkt vom Dateisystem — alle Handler gehen über Store-Methoden. Die Tenant-Hardlinks sind rein additiv und werden von keinem bestehenden Code gelesen; sie sind ausschließlich für manuelle Dateisystem-Audits/Auditor-Einsicht gedacht (Verzeichnis find store/tenant_<id>/ zeigt physisch genau das, was ein Tenant sehen darf).
• Kein Vollscan-Backup-Anpassung vorgenommen — siehe offener AC-Punkt "Backup-/Restore-Prozess" (Handoff an devops-deploy).

Offene Punkte / Handoff

• Messung Cross-Tenant-Dedup-Quote (AC aus Option B) noch nicht durchgeführt — steht auf dem Testserver aus: SELECT email_id, COUNT(DISTINCT tenant_id) FROM email_refs GROUP BY email_id HAVING COUNT(DISTINCT tenant_id) > 1;
• Backup-Prozess-Check: devops-deploy sollte verifizieren, dass das eingesetzte Backup-Tool Hardlinks erhält (z.B. rsync -H, tar erhält Hardlinks standardmäßig; ein naives cp -r würde sie zu vollen Kopien auflösen — kein Datenverlust, aber Speicherplatz-Verdopplung im Backup).
• migrate-tenant-dirs einmalig auf Produktiv ausführen nach Deploy, dann optional in update.sh als informativer Hinweis (nicht automatisch bei jedem Deploy laufen lassen — reiner Backfill, macht nach dem ersten Lauf nichts mehr).
• Kein lokaler go build/go test möglich (kein Toolchain im Arbeitsverzeichnis) — Build-/Testverifikation erfolgt separat auf dem Testserver.

Geänderte/neue Dateien

• internal/storage/tenant_dirs.go (NEU)
• internal/storage/storage.go (Save, Delete — Hardlink-Wiring)
• cmd/archivmail/cmd_migrate_tenant_dirs.go (NEU)
• cmd/archivmail/main.go (Subcommand registriert)
• cmd/archivmail/cmd_status.go (checkStoragePermissions)
• docs/GOBD_DSGVO_CHECKLIST.md (Punkt 15, siehe separater Commit)

QA Test Results

To be added by /qa

Deployment

To be added by /deploy