docs: restructure docs to diataxis and finalize DOCS-RESTRUCTURE-001

docs/explanation-sicherheitsmodell.md

@@ -0,0 +1,113 @@
+# Sicherheitsmodell
+
+Letzte Aktualisierung: 2026-03-06
+
+## Ziel
+
+Kurze, verbindliche Übersicht der Sicherheitsmechanik für Web und API.
+
+## Sicherheitskette pro Request
+
+1. Firewall/Request-Grenze
+2. Authentifizierung
+3. Permission-Check
+4. Tenant-Scope-Check
+5. Endpoint-spezifische Regeln (z. B. Exporte, Media, Audit)
+
+Kein Layer allein reicht aus.
+
+## Public vs. Protected
+
+- Public-Routen kommen aus `config/routes.php` (`public => true`).
+- Zusätzlich sind Präfixe technisch immer public (`branding/`, `flash/`, `auth/microsoft/`, `api/`) in `lib/Http/AccessControl.php`.
+- Alles andere erfordert Login.
+
+API-Sonderfall:
+
+- `pages/api/v1/auth/login().php` nutzt `ApiBootstrap::init(false)` (public Login-Endpunkt).
+- Geschützte API-Endpunkte nutzen `ApiBootstrap::init()`.
+
+## Auth und Login
+
+- Web-Login ist session-basiert (`pages/auth/login().php`).
+- Remember-Me-Autologin läuft früh in `web/index.php`.
+- Multi-Tenant-Login wählt Tenant-Kontext serverseitig.
+- Microsoft-SSO läuft über OIDC (`auth/microsoft/start` + `auth/microsoft/callback`) mit `state`, `nonce`, PKCE und ID-Token-Validierung.
+
+## Permission und Tenant-Scope
+
+- Rechte werden serverseitig geprüft (`PermissionService` + Policies).
+- UI-Sichtbarkeit wird ebenfalls serverseitig vorbereitet (`UiAccessService` + `$viewAuth`), nicht im Template selbst entschieden.
+- Globaler Scope-Bypass ist explizit: `tenant.scope.global`.
+- Beispiel für harte Feature-Gates:
+  - `users.access_pdf`
+  - `custom_fields.manage`, `custom_fields.edit_values`
+  - `tenants.sso_manage`
+  - `api_audit.view`
+
+## API-Schutz
+
+- Zentrale API-Rate-Limits laufen in `lib/Http/ApiBootstrap.php`.
+- API-Audit läuft zentral über `ApiAuditService`:
+  - loggt Metadaten (Pfad, Status, Dauer, Kontext)
+  - redigiert sensible Query-Parameter
+  - speichert keine Request-/Response-Bodies
+
+## Edge-Hardening (Nginx)
+
+- Security-Header werden zentral im Nginx gesetzt.
+- Baseline:
+  - `X-Content-Type-Options: nosniff`
+  - `X-Frame-Options: SAMEORIGIN`
+  - `Referrer-Policy: strict-origin-when-cross-origin`
+  - `Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=()`
+  - `X-Permitted-Cross-Domain-Policies: none`
+- Produktion ergänzt:
+  - `Strict-Transport-Security: max-age=31536000`
+- Lokale Entwicklung setzt bewusst kein HSTS, um HTTP-/localhost-Workflows nicht zu beeinflussen.
+
+## System-Audit (fachliche Aktionen)
+
+- Separater Audit-Stream: `system_audit_log` (unabhängig von `api_audit_log`).
+- Scope V2:
+  - Web: Auth-Events + Admin-Write-Aktionen.
+  - API: selektive `api.request`-Events (Write-Requests, `>=500`, Security-Endpunkte bei `>=400`).
+  - Scheduler: `scheduler.run` (Runner-Zusammenfassung) und `scheduler.job.run` (pro Joblauf).
+  - CLI: `cli.command` für zentrale Betriebsbefehle (z. B. `bin/doctor.php`).
+- Privacy-Default:
+  - keine Request-/Response-Bodies
+  - keine Klartext-Secrets/Passwörter/Tokens/E-Mails
+  - IP/User-Agent nur gehasht (HMAC)
+- Globaler Schalter über Settings:
+  - `system_audit_enabled` (hard-off: keine neuen Events)
+  - `system_audit_retention_days` (Retention/Purge)
+- RBAC:
+  - `system_audit.view`
+  - `system_audit.purge`
+
+## Schreibschutz
+
+- Web-Schreibaktionen laufen mit CSRF-Token.
+- Kritische Actions sind POST-only + serverseitige Validierung.
+- API nutzt Bearer-Auth und eigenes Schutzmodell (kein Form-CSRF).
+
+## Betriebschecks
+
+- Permission-Set und Rollen regelmäßig prüfen.
+- Tenant-Entzug/Scope-Verhalten testen.
+- Rate-Limits und `429`-Verhalten bei Login/API testen.
+- Audit-Streams bewusst getrennt nutzen:
+  - `system_audit_log`: fachliche/sicherheitsrelevante Ereignisse (summary-level)
+  - `api_audit_log`: API-Request-Telemetrie (Status, Dauer, Pfad)
+  - `import_audit_runs`, `user_lifecycle_audit_log`, `scheduled_job_runs`: Domänen-/Betriebsdetails
+- Audit-Retention prüfen:
+  - API-Audit: 90 Tage
+  - Import-Audit: 90 Tage
+  - User-Lifecycle-Audit: 365 Tage
+  - System-Audit: konfigurierbar (Default 365 Tage)
+
+## Vertiefung
+
+- `/docs/howto-anfragelimits.md`
+- `/docs/tutorial-07-security-tenant-scope.md`
+- `/docs/howto-rbac-permissions-playbook.md`