R188/R189-01 aus dem Pentest umgesetzt - Klasse statt Instanz

Beide Findings der Pentesterin waren berechtigt. Ihre Patches liessen
sich nicht anwenden (Basis 791711c, seitdem 42 Commits, sync-roles.ts
kollidiert), und an zwei Stellen greifen sie zu kurz.

R188 - ungueltige IDs im Pfad
-----------------------------
Gemeldet: GET /api/users/:id gibt bei nicht-numerischer ID 500 statt 400.
Ihr Fix schliesst nebenbei mehr, als sie beansprucht: parseInt('12abc')
ergibt 12, also lieferte /api/users/12abc bisher Benutzer 12 aus.

Es waren aber 181 ungepruefte Stellen in 19 Controllern, nicht eine. 181
Einzel-Guards waeren genau der Fehler aus R186-01 gewesen - drei
Filterlisten, die dasselbe bedeuten sollten und auseinanderliefen.
Stattdessen router.param(), an einer Stelle fuer alle 33 Router
registriert, ueber einen mounte()-Helfer, der Pruefung und Einhaengen
zusammenbindet.

Antwort ist 404, nicht 400: Ein Pfadsegment, das keine ID sein kann,
benennt keine Ressource. Der bestehende Praezedenzfall in
provider.controller.ts (Pentest Mai 2026) hatte es genauso entschieden.

Dabei eine aeltere Heuristik abgeloest (Pentest Runde 7). Ihr eigener
Kommentar nannte den Grund fuer sie - "app.param() greift nicht auf in
Sub-Router gemounteten Routes" - und genau das loest mounte(). Sie war zu
eng (/users/abc ging durch und endete als 500) und zu weit (ein
Einstellungs-Schluessel 12abc unter :key wurde geblockt, obwohl das keine
ID ist), und sie antwortete 400, wo jetzt 404 steht.

R189-01 - DSGVO-Rechte ohne Traeger
------------------------------------
Gemeldet: gdpr:* und audit:read/export haengen an DSGVO und Developer,
die Admin-Rolle hat sie nicht, und nach einem frischen Seed war DSGVO
keinem Konto zugewiesen. Auskunft nach Art. 15 und Loeschung nach Art. 17
konnte niemand ausfuehren.

Seed weist admin@admin.com jetzt zusaetzlich die DSGVO-Rolle zu; die
Admin-Rolle selbst bleibt ohne diese Rechte, die Trennung aus R186 bleibt
also erhalten. Label ehrlich gemacht.

Beim Pruefen ihres Patches ein eigener Fund: seed.ts vergab an die
DSGVO-Rolle weiterhin audit:* komplett, inklusive audit:admin - die
Buendelung, die fc6f39e aufgeloest hat. Ich hatte damals zwei Listen
gefunden und die dritte uebersehen. Gerettet hat es nur die Reihenfolge
im Containerstart; ein einzelnes `npm run db:seed` brachte sie zurueck.

Der Seed hilft nur bei Neuinstallation (update: {}). Deshalb zusaetzlich
eine Wache beim Start: Gibt es fuer gdpr:export, gdpr:delete oder
audit:read kein aktives Konto, steht das mit Handlungsanweisung im Log -
Erkennung der ABWESENHEIT einer Faehigkeit, wie beim Heartbeat. Bewusst
nur melden, nicht automatisch vergeben.

Getestet ueber HTTP gegen eine Wegwerf-Instanz: alle ID-Varianten quer
ueber sechs Controller, Nicht-ID-Parameter unveraendert, frischer Seed,
Wache mit und ohne vergebene Rechte.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.dockerignore

@@ -12,7 +12,7 @@ backend/dist
 .vscode
 .idea
 *.md
-!docker/README.md
+
 
 # Environment files (use Docker environment instead)
 .env

.env.example

@@ -53,6 +53,51 @@ JWT_REFRESH_EXPIRES_IN=7d
 # Generieren: openssl rand -hex 32
 ENCRYPTION_KEY=change-this-to-64-hex-characters-please-rotate-before-production-xx
 
+# ---------- Optionaler Reverse-Proxy (Caddy) ----------
+# Brauchst du nur, wenn du KEINEN eigenen Reverse-Proxy hast (nginx, Nginx
+# Proxy Manager, Traefik) und Caddy das SSL übernehmen soll.
+#
+# EIN/AUS über diesen Schalter – nichts auskommentieren:
+#   leer         -> Caddy AUS, wird nicht einmal angelegt   ← Standard
+#   caddy        -> Caddy startet bei jedem `docker-compose up -d` mit
+# Der Schalter wirkt auch bei `down`, `logs` usw. – im Gegensatz zum
+# Kommandozeilen-Flag `--profile caddy`, das man leicht vergisst.
+COMPOSE_PROFILES=              # leer lassen = Caddy aus
+
+# Die folgenden drei Werte werden NUR gebraucht, wenn oben `caddy` steht.
+# Ohne Caddy kannst du sie ignorieren.
+DOMAIN=crm.example.com
+CADDY_DIR=./data/caddy
+CADDY_CONFIG_DIR=./data/caddy-config
+
+# ---------- Siegel für das Audit-Log ----------
+# OpenCRM protokolliert, wer wann welche Daten gesehen oder geändert hat – die
+# Beweisspur bei Streit oder Datenschutz-Nachfragen. Dieser Schlüssel versieht
+# jeden neuen Eintrag mit einem Siegel, das sich nur damit erzeugen lässt. Er
+# liegt AUSSERHALB der Datenbank; wer nur die Datenbank in die Hände bekommt,
+# kann damit nichts fälschen, ohne dass es auffliegt.
+#
+# Generieren: openssl rand -hex 32   (pro Umgebung ein eigener Wert)
+#
+# Ohne Wert läuft alles normal weiter, nur eben ungesiegelt – nichts fällt aus.
+# Nachträglich setzen ist jederzeit möglich: bestehende Einträge bleiben gültig,
+# ab dem Neustart werden neue gesiegelt (keine Fehlalarme dadurch).
+#
+# ACHTUNG – einmal gesetzt, nicht wieder entfernen: Einträge, die ohne Schlüssel
+# entstehen, werden beanstandet, sobald er zurück ist (ein ungesiegelter Eintrag
+# inmitten gesiegelter ist von einer Fälschung nicht zu unterscheiden).
+# Schlüssel sichern wie ein Passwort – geht er verloren, sind die damit
+# gesiegelten Einträge dauerhaft nicht mehr prüfbar.
+# Ausführlich erklärt in der README, Abschnitt "Audit-Siegel".
+AUDIT_HMAC_KEY=
+
+# Nur beim Schlüsselwechsel füllen: die FRÜHEREN Schlüssel, kommagetrennt und
+# jüngster zuerst. Damit bleiben die bisherigen Einträge prüfbar, während neue
+# schon mit dem neuen Schlüssel gesiegelt werden. Nicht voreilig leeren – sonst
+# werden die alten Einträge als "manipuliert" gemeldet.
+#   Beispiel: AUDIT_HMAC_KEY_OLD=<vorheriger>,<davor>
+AUDIT_HMAC_KEY_OLD=
+
 # Server
 NODE_ENV=development
 PORT=3001                  # Backend-internal Port (Dev: localhost:3001)

.gitignore

@@ -36,6 +36,18 @@ data/factory-defaults/*
 data/backups/*
 !data/backups/.gitkeep
 
+# Gegenbuch (laeuft auf eigener Maschine): enthaelt das Buch selbst, den
+# Signaturschluessel und den Beobachtungsspeicher. Nichts davon gehoert ins
+# Repository - der Schluessel schon gar nicht.
+tools/audit-notary/data/*
+!tools/audit-notary/data/.gitkeep
+!tools/audit-notary/data/prod/
+tools/audit-notary/data/prod/*
+!tools/audit-notary/data/prod/.gitkeep
+!tools/audit-notary/data/staging/
+tools/audit-notary/data/staging/*
+!tools/audit-notary/data/staging/.gitkeep
+
 # Factory-Defaults-Drop-Box (Export-ZIPs zwischen dev/prod hin und her)
 factory-exports/*
 !factory-exports/.gitkeep

Caddyfile

@@ -0,0 +1,42 @@
+# OpenCRM Caddyfile
+# ===================
+# Wird NUR gebraucht, wenn du den optionalen Caddy-Dienst startest:
+#     docker-compose --profile caddy up -d
+# Caddy holt und erneuert dann das SSL-Zertifikat automatisch fuer ${DOMAIN}.
+# Betreibst du bereits einen eigenen Reverse-Proxy (nginx, NPM, Traefik),
+# brauchst du diese Datei nicht - dann laeuft alles ueber deinen Proxy.
+
+{$DOMAIN:localhost} {
+    # Reverse proxy to OpenCRM app
+    reverse_proxy opencrm:3001
+
+    # Logging
+    log {
+        output stdout
+        format console
+    }
+
+    # Security headers
+    header {
+        # Clickjacking protection
+        X-Frame-Options "SAMEORIGIN"
+        # XSS protection
+        X-Content-Type-Options "nosniff"
+        X-XSS-Protection "1; mode=block"
+        # Referrer policy
+        Referrer-Policy "strict-origin-when-cross-origin"
+    }
+
+    # Gzip compression – NUR fuer statische Assets, NICHT fuer /api/*.
+    # Komprimierte API-Antworten ermoeglichen die BREACH-Attacke
+    # (CVE-2013-3587): aus der Antwortgroesse liessen sich unter bestimmten
+    # Bedingungen Geheimnisse aus JSON-Responses ableiten. Statische Dateien
+    # sind davon nicht betroffen und bleiben komprimiert.
+    @nicht_api not path /api/*
+    encode @nicht_api gzip
+
+    # Handle file uploads (increase body limit)
+    request_body {
+        max_size 50MB
+    }
+}

README.md

@@ -281,6 +281,10 @@ LISTEN_ADDR=127.0.0.1
 
 # Bei separatem Frontend-Host: erlaubte Origins
 CORS_ORIGINS=https://crm.deine-domain.de
+
+# Siegel fuer das Audit-Log – schuetzt die Beweisspur vor nachtraeglicher
+# Faelschung. Siehe Abschnitt "Audit-Siegel" weiter unten.
+AUDIT_HMAC_KEY=$(openssl rand -hex 32)
 ```
 
 ### Deployment-Modus: On-Prem vs. Cloud
@@ -298,6 +302,279 @@ SSRF-Schalter:
 SSRF_BLOCK_PRIVATE_IPS=true
 ```
 
+### Audit-Siegel (`AUDIT_HMAC_KEY`)
+
+**Worum geht es?**
+OpenCRM führt ein Audit-Log: eine lückenlose Aufzeichnung, wer wann welche
+Daten gesehen oder geändert hat. Das ist die Beweisspur, wenn es Streit gibt,
+etwas verschwindet oder der Datenschutz nachfragt.
+
+Damit diese Aufzeichnung etwas wert ist, muss man ihr ansehen können, ob
+jemand nachträglich daran herumgeschrieben hat. Dafür trägt jeder Eintrag
+einen Fingerabdruck, der auch den Fingerabdruck des vorherigen Eintrags
+enthält – wie eine Kette. Ändert jemand einen alten Eintrag, passen die
+Fingerabdrücke nicht mehr und es fällt auf.
+
+**Und wozu dann noch ein Schlüssel?**
+Weil jemand mit Zugriff auf die Datenbank die ganze Kette neu berechnen
+könnte. Er ändert also einen Eintrag – zum Beispiel einen fehlgeschlagenen
+Login-Versuch in einen erfolgreichen – und zieht anschließend alle
+Fingerabdrücke glatt. Danach sieht die Fälschung echt aus.
+
+Mit `AUDIT_HMAC_KEY` bekommt jeder Eintrag zusätzlich ein **Siegel**, das sich
+nur mit diesem Schlüssel erzeugen lässt. Der Schlüssel liegt in der
+`.env`-Datei, also **außerhalb der Datenbank**. Wer nur die Datenbank in die
+Hände bekommt, kann damit nichts fälschen, ohne dass es auffliegt.
+
+> Bildlich: Die Fingerabdruck-Kette ist die fortlaufende Nummerierung der
+> Aktenseiten. Der Schlüssel ist der Stempel des Notars. Die Akte steht zwar
+> im Schrank – aber den Stempel hat nur der Notar.
+
+**Einrichten**
+
+```bash
+# Einmalig pro Umgebung einen Schlüssel erzeugen
+openssl rand -hex 32
+```
+
+**In welche Datei?** Das hängt davon ab, wie du OpenCRM betreibst:
+
+| Betrieb | Datei |
+|---|---|
+| **Docker** (Standard) | **`.env` im Projektstamm** |
+| Backend direkt, ohne Container (Entwicklung) | `backend/.env` |
+
+Beim Docker-Betrieb reicht der Eintrag in der Stamm-`.env` – `docker-compose.yml`
+reicht die Variable an den Container weiter. Ein Eintrag in `backend/.env` wirkt
+dort **nicht**, weil der Container diese Datei nicht liest.
+
+Wichtig: **pro Umgebung ein eigener Schlüssel** (Entwicklung, Test, Produktion)
+– und niemals ins Git-Repository.
+
+**Bestehende Installation: bisher kein Schlüssel gesetzt?**
+
+Genau so ist es gedacht – der Schlüssel kam mit einem Update dazu. Du kannst
+ihn jederzeit nachträglich setzen:
+
+1. Schlüssel erzeugen (`openssl rand -hex 32`), in die `.env` eintragen
+2. Backend neu starten
+3. Fertig – mehr ist nicht nötig
+
+Was dabei mit deinen **bereits vorhandenen** Einträgen passiert:
+
+- Sie bleiben **unverändert** und weiterhin gültig. Es wird nichts neu
+  berechnet und nichts nachträglich gesiegelt.
+- Ab dem Neustart werden **neue** Einträge gesiegelt. Alt und neu liegen
+  friedlich nebeneinander, die Prüfung erkennt für jeden Eintrag automatisch,
+  nach welchem Verfahren er zu prüfen ist.
+- Es gibt **keine** Fehlalarme dadurch. (Nachgemessen auf einer Installation
+  mit 4903 alten, 57 mittleren und 67 gesiegelten Einträgen: 0 Beanstandungen.)
+
+Rückwirkend lässt sich der Schutz nicht herstellen – ältere Einträge bleiben
+ungesiegelt. Das ist kein Fehler, sondern liegt in der Natur der Sache: Ein
+Siegel kann man nur beim Anlegen vergeben, nicht nachträglich. Je früher du
+den Schlüssel setzt, desto größer der geschützte Zeitraum.
+
+> ⚠️ **Einmal gesetzt, nicht wieder abschalten.** Fehlt der Schlüssel später
+> (z. B. weil er beim Container-Rebuild aus der `.env` verlorenging), läuft die
+> Anwendung normal weiter – aber die in dieser Zeit entstandenen Einträge sind
+> ungesiegelt und werden von der Prüfung **beanstandet**, sobald der Schlüssel
+> wieder da ist. Das ist Absicht: Ein ungesiegelter Eintrag inmitten
+> gesiegelter ist von einer Fälschung nicht zu unterscheiden. Nimm den
+> Schlüssel deshalb in deine Deploy-Checkliste auf.
+
+Ein noch nicht ersetzter Platzhalter (`<hier-eigenen-wert-eintragen>`) zählt
+bewusst **nicht** als Schlüssel – sonst würde mit einem öffentlich bekannten
+Wert gesiegelt. Das Backend schreibt in diesem Fall eine Warnung ins Log und
+lässt das Siegel aus.
+
+**Häufige Fragen**
+
+| Frage | Antwort |
+|---|---|
+| Was, wenn ich den Schlüssel gar nicht setze? | Nichts fällt aus. Das Audit-Log läuft normal weiter, nur ohne dieses zusätzliche Siegel. |
+| Was, wenn ich ihn verliere? | Lässt du das Feld dann **leer**, gelten die gesiegelten Einträge als **„nicht prüfbar"** – ausdrücklich nicht als gefälscht, also kein Fehlalarm. Der Nachweis für diesen Zeitraum ist aber weg. Deshalb: sichern wie ein Passwort. |
+| Und wenn ich stattdessen einen **neuen** Schlüssel eintrage? | Dann werden die alten Einträge als **„manipuliert" gemeldet** – das System kann einen falschen Schlüssel nicht von einer echten Fälschung unterscheiden. Trage den alten Schlüssel deshalb zusätzlich unter `AUDIT_HMAC_KEY_OLD` ein (siehe unten). |
+| Muss ich ihn irgendwo eintragen außer in der `.env`? | Nein. Einmal setzen, Backup anlegen, fertig. |
+| Verlangsamt das etwas? | Nein, spürbar nicht. |
+
+**Wichtig bei einer bestehenden Installation: den Altbestand versiegeln**
+
+Das Siegel gilt nur für Einträge, die **ab** dem Setzen des Schlüssels
+geschrieben werden. Alles, was vorher im Protokoll steht, bleibt ungeschützt –
+Änderungen daran wären nicht erkennbar. Die Integritätsprüfung sagt das auch:
+
+    Hinweis: Der Altbestand ist nicht versiegelt – Änderungen daran wären
+    nicht erkennbar. Behebbar mit POST /api/audit-logs/seal-backlog
+    {"confirm":"SEAL"}.
+
+Das ist ein **einmaliger** Schritt: Er zieht ein Siegel über den vorhandenen
+Bestand, sodass spätere Änderungen daran auffallen. Der Ablauf – wer es darf
+(Haken **„Audit-Betrieb"** in der Benutzerverwaltung), was vorher zu prüfen ist
+und wie man das Ergebnis gegenprüft – steht Schritt für Schritt unter
+**[Den Altbestand versiegeln](tools/audit-notary/README.md#den-altbestand-versiegeln-einmalig-im-crm)**.
+Die Anleitung liegt beim Gegenbuch, gilt aber **auch ohne** – es ist ein
+Vorgang im CRM.
+
+Den Zustand siehst du jederzeit unter **Einstellungen → Audit-Protokoll**, ganz
+oben.
+
+**Schlüssel wechseln (`AUDIT_HMAC_KEY_OLD`)**
+
+Möchtest du den Schlüssel austauschen – etwa weil du vermutest, dass er in
+falsche Hände geraten ist – geht das ohne Datenverlust:
+
+```env
+AUDIT_HMAC_KEY=<neuer Schlüssel>
+AUDIT_HMAC_KEY_OLD=<bisheriger Schlüssel>
+```
+
+Neue Einträge werden ab sofort mit dem neuen Schlüssel gesiegelt, die
+bisherigen bleiben über den alten Schlüssel weiterhin prüfbar.
+
+> ⚠️ **`AUDIT_HMAC_KEY_OLD` nicht voreilig leeren.** Solange Einträge
+> existieren, die mit einem alten Schlüssel gesiegelt wurden, muss dieser dort
+> stehen bleiben. Entfernst du ihn, werden diese Einträge als **„manipuliert"
+> gemeldet** – nicht als „nicht prüfbar". Das System kann einen falschen
+> Schlüssel nicht von einer echten Fälschung unterscheiden. Leeren kannst du
+> das Feld gefahrlos erst, wenn die betroffenen Einträge durch die
+> Aufbewahrungsfristen ohnehin gelöscht sind.
+
+**Mehrfach gewechselt?** Das Feld nimmt mehrere Schlüssel kommagetrennt auf –
+vom jüngsten zum ältesten:
+
+```env
+AUDIT_HMAC_KEY=<aktueller Schlüssel>
+AUDIT_HMAC_KEY_OLD=<vorheriger>,<davor>,<ganz alter>
+```
+
+Ohne das würde beim zweiten Wechsel der zuerst genutzte Schlüssel verloren
+gehen – und alle damit gesiegelten Einträge fälschlich als manipuliert
+erscheinen.
+
+**Prüfen, ob alles in Ordnung ist**
+
+Die Prüfung läuft derzeit nur über die API (eine Schaltfläche in der Oberfläche
+gibt es dafür noch nicht) – als angemeldeter Benutzer mit dem Recht
+`audit:read`:
+
+```bash
+curl -X POST https://crm.deine-domain.de/api/audit-logs/verify \
+     -H "Authorization: Bearer <Access-Token>"
+```
+
+Die Antwort enthält einen Klartext-Satz im Feld `message` und unterscheidet
+zwei Dinge:
+
+- **„Manipulierte Einträge"** – jemand hat einen bestehenden Eintrag
+  nachträglich verändert. Das ist ernst.
+- **„Strukturelle Lücken"** – die Kette hat eine Unterbrechung, die Inhalte
+  sind aber unverändert. Meist harmlos (z. B. gelöschte alte Einträge).
+  Notiere dir die Zahl nach dem ersten Deploy: Bleibt sie konstant, ist alles
+  in Ordnung. Steigt sie, lohnt ein Blick.
+
+### Gegenbuch – optionaler Zusatzschutz auf zweitem Rechner
+
+Das Audit-Siegel schützt die Einträge **innerhalb** der Anwendung. Es liegt aber
+in derselben Datenbank, die es absichert: Wer vollen Zugriff auf den Server hat,
+kommt am Ende auch an das Siegel.
+
+Dagegen gibt es das **Gegenbuch**. Ein zweiter Rechner holt regelmäßig einen
+kurzen Kontrollwert vom CRM und schreibt ihn mit. Wird später im CRM etwas
+nachträglich verändert oder gelöscht, widerspricht das dem Gegenbuch und fällt
+beim nächsten Durchlauf auf.
+
+Die Richtung ist dabei entscheidend:
+
+```
+Gegenbuch  ──holt lesend──>  OpenCRM      (HTTPS, Konto nur mit audit:read)
+OpenCRM    ─────────────────>  (kennt das Gegenbuch nicht)
+```
+
+Wer OpenCRM übernimmt, kommt damit nicht an das Gegenbuch. Das CRM braucht
+dafür **keinerlei Konfiguration** – es liefert nur einen lesbaren Prüfwert, der
+keine Geheimnisse enthält.
+
+**Einrichten** (auf einem anderen Rechner als dem CRM):
+
+```bash
+git clone <dieses Repository> opencrm
+cd opencrm/tools/audit-notary
+cp .env.example .env      # CRM-Adresse und Dienstkonto eintragen
+docker compose up -d
+```
+
+**Vorher im CRM anlegen:** eine Rolle mit ausschließlich dem Recht
+`audit:read` und einen Benutzer damit. Das Gegenbuch meldet sich mit diesem
+Konto bei jedem Durchlauf selbst an – ein dauerhaftes Token gibt es nicht, weil
+Zugangstoken nach 15 Minuten ablaufen.
+
+Zwei Bücher auf einer Maschine – etwa für Produktion und Test – sind
+vorgesehen. Alles Weitere in
+[tools/audit-notary/README.md](tools/audit-notary/README.md).
+
+> **Optional.** Ohne Gegenbuch bleibt der Schutz innerhalb der Anwendung
+> vollständig erhalten. Es deckt zusätzlich den Fall ab, dass jemand den
+> CRM-Server selbst übernimmt.
+
+<details>
+<summary><b>Technische Details</b> (für Entwickler/Admins)</summary>
+
+**Verfahren.** Jeder Audit-Eintrag trägt einen Hash über seine Inhaltsspalten
+plus den Hash des Vorgängers (`previousHash`) – daraus entsteht die Kette. Es
+gibt drei Hash-Versionen, die Spalte `hashVersion` hält fest, welche verwendet
+wurde:
+
+| Version | Verfahren | Abdeckung |
+|---|---|---|
+| 1 | SHA-256 | 7 Felder – Altbestand vor der Härtung |
+| 2 | SHA-256 | alle 24 Inhaltsspalten, unsigniert |
+| 3 | **HMAC-SHA256** mit `AUDIT_HMAC_KEY` | alle 24 Inhaltsspalten, signiert |
+
+Bestandsdaten werden **nicht** nachträglich neu berechnet – ein Rehash würde die
+Beweiskraft der Vergangenheit überschreiben. Alte Einträge bleiben mit ihrer
+Version gültig.
+
+**Version-Floor.** Die zu erwartende Version wird aus der Kette abgeleitet
+(erste je mit Version *n* geschriebene Zeile), **nicht** aus der Selbstauskunft
+der Zeile. Sonst ließe sich per Downgrade (`hashVersion` 3 → 1) die schwächere
+Prüfung erzwingen und anschließend ein gültiger Hash über die wenigen
+abgedeckten Felder nachziehen. Zusätzlich gilt: Eine unerklärte Lücke direkt vor
+einer signierten Zeile ist ein Befund, kein struktureller Zufall – deren
+`previousHash` lässt sich ohne Schlüssel nicht fälschen.
+
+**Löschungen.** `POST /api/audit-logs/cleanup` schreibt ein Manifest
+(ID-Bereich, Anzahl, Policy, Cutoff) als eigenen verketteten Eintrag. Die
+Prüfung liest es aus und meldet nur Lücken **ohne** dokumentierte Löschung als
+erklärungsbedürftig (`unexplainedGaps`) – sonst könnte sich eine böswillige
+Löschung als harmlose Lücke tarnen.
+
+**Rückgabe von `POST /api/audit-logs/verify`:**
+
+| Feld | Bedeutung |
+|---|---|
+| `tamperedEntries` | Inhalt nachträglich verändert, Versions-Downgrade oder gebrochener Anker – **ernst** |
+| `chainGaps` | Verkettung unterbrochen (alle) |
+| `unexplainedGaps` | Teilmenge davon ohne dokumentierte Löschung |
+| `unverifiableEntries` | signiert, aber kein Schlüssel konfiguriert – **kein** Manipulationsverdacht |
+
+**Fail-safe.** Ohne `AUDIT_HMAC_KEY` schreibt der Dienst weiter Version 2; das
+Logging fällt nie wegen fehlender Konfiguration aus.
+
+**Bekannte Grenze.** Der Anker schützt gegen reinen Datenbank-Schreibzugriff.
+Wer Schlüssel *und* Datenbank kontrolliert, kann die Kette konsistent neu
+rechnen. Eine Off-Site-Notarisierung (regelmäßiger Export/Versiegelung des
+Kettenkopfes außerhalb des Systems) wäre die nächste Stufe.
+
+**Achtung – zwei Endpunkte mit Nebenwirkung:**
+`POST /api/audit-logs/rehash` berechnet alle Hashes neu; danach meldet die
+Prüfung überall „gültig", aber eine bestehende Fälschung würde mitbesiegelt.
+`POST /api/audit-logs/cleanup` löscht nach Aufbewahrungsregeln, jede gelöschte
+Zeile erzeugt eine Lücke. Beide laufen nur manuell und schreiben einen Marker
+ins Log.
+
+</details>
+
 Cloud-Metadata-Endpoints (`169.254.169.254`, `metadata.google.internal` etc.)
 sind UNABHÄNGIG vom Flag **immer** geblockt – das ist Mindestschutz gegen
 AWS/GCP/Azure-IMDS-Diebstahl.
@@ -604,39 +881,49 @@ docker-compose down -v     # Container stoppen + Daten löschen
 docker-compose logs -f     # Logs anzeigen
 ```
 
-### Docker (Produktion)
+### Betrieb mit eigenem SSL (optionaler Caddy-Dienst)
 
-Im `docker/` Verzeichnis liegt ein komplettes Produktions-Setup:
+Es gibt **eine** `docker-compose.yml` und **eine** `.env` im Projektstamm.
+Standardmässig bringt der Stack **keinen** Reverse-Proxy mit – die Annahme ist,
+dass du bereits einen hast (nginx, Nginx Proxy Manager, Traefik) und OpenCRM
+dahinter hängst.
+
+Hast du **keinen**, kannst du Caddy als optionalen Dienst dazuschalten. Er holt
+und erneuert das SSL-Zertifikat automatisch:
+
+Dafür gibt es einen Schalter in der `.env` – nichts muss auskommentiert werden:
+
+```env
+COMPOSE_PROFILES=caddy      # leer = kein Caddy (Standard)
+DOMAIN=crm.example.de
+HTTPS_ENABLED=true
+```
 
 ```bash
-cd docker
+docker-compose up -d        # startet jetzt zusätzlich Caddy
-
-# Image bauen
-docker-compose build
-
-# Container starten
-docker-compose up -d
-
-# Logs anzeigen
-docker-compose logs -f app
 ```
 
-**Komponenten:**
+Solange `COMPOSE_PROFILES` leer ist, wird der Caddy-Dienst **gar nicht erst
-- **MariaDB 10.11**: Datenbank
+angelegt** – der Stack verhält sich exakt wie ohne ihn. Der Schalter wirkt auch
-- **App**: Backend + Frontend in einem Container
+bei `down`, `logs` und `ps`, im Gegensatz zum Flag `--profile caddy`, das man
-- **Caddy**: Reverse-Proxy mit automatischem SSL
+bei Folgebefehlen leicht vergisst.
 
-**Umgebungsvariablen (`docker/.env`):**
+**Was dabei zu beachten ist:**
-```env
+
-MYSQL_ROOT_PASSWORD=sicheres-root-passwort
+- Die Zertifikate liegen unter `./data/caddy`. Diesen Ordner **nicht löschen**,
-MYSQL_DATABASE=opencrm
+  sonst werden bei jedem Start neue Zertifikate angefordert und du läufst in
-MYSQL_USER=opencrm
+  die Mengenbegrenzung von Let's Encrypt.
-MYSQL_PASSWORD=sicheres-passwort
+- Die Domain muss vorher per DNS auf den Server zeigen, sonst schlägt die
-JWT_SECRET=sehr-langer-zufaelliger-string
+  Zertifikatsausstellung fehl.
-ENCRYPTION_KEY=64-zeichen-hex-string
+- `HTTPS_ENABLED=true` setzen – das aktiviert das `Secure`-Attribut am
-DOMAIN=crm.example.com
+  Refresh-Cookie und die korrekte Proxy-Erkennung.
-RUN_SEED=true  # Nur beim ersten Start
+- Der direkte App-Port (`OPENCRM_PORT`, Standard 3010) bleibt weiterhin offen.
-```
+  Wenn nur Caddy von aussen erreichbar sein soll, schliesse ihn per Firewall
+  oder setze ihn in der `.env` auf einen Wert, den du nicht freigibst.
+
+Die Konfiguration liegt in der `Caddyfile` im Projektstamm. Sie liefert
+Sicherheits-Header mit und komprimiert bewusst **nicht** die API-Antworten
+(BREACH-Schutz, siehe Abschnitt zum Reverse-Proxy oben).
 
 ## Projektstruktur
 
@@ -688,7 +975,8 @@ opencrm/
 │   │   ├── types/          # TypeScript-Typen
 │   │   └── App.tsx         # Haupt-Komponente
 │   └── package.json
-├── docker/                  # Docker-Deployment
+├── Caddyfile                # Optionaler Reverse-Proxy (nur mit --profile caddy)
+├── tools/audit-notary/      # Gegenbuch – läuft auf einem zweiten Rechner
 │   ├── Dockerfile          # Multi-Stage Build
 │   ├── docker-compose.yml  # Produktion (MariaDB, App, Caddy)
 │   ├── Caddyfile           # Reverse-Proxy mit SSL

backend/.env.example

@@ -19,3 +19,110 @@ ENCRYPTION_KEY="32-byte-hex-key-for-aes-256-gcm"
 # Server
 PORT=3001
 NODE_ENV=development
+
+# ==================== AUDIT-SIEGEL ====================
+# Was ist das Audit-Log?
+#   OpenCRM protokolliert luekenlos, wer wann welche Daten gesehen oder
+#   geaendert hat. Das ist die Beweisspur, wenn es Streit gibt oder der
+#   Datenschutz nachfragt.
+#
+# Wogegen schuetzt dieser Schluessel?
+#   Ohne ihn koennte jemand mit Zugriff auf die Datenbank einen Eintrag
+#   nachtraeglich umschreiben - zum Beispiel einen fehlgeschlagenen
+#   Login-Versuch in einen erfolgreichen verwandeln - und die Faelschung so
+#   glattziehen, dass die Pruefung sie fuer echt haelt.
+#   Mit dem Schluessel bekommt jeder Eintrag ein Siegel, das sich nur mit
+#   diesem Schluessel erzeugen laesst. Wer ihn nicht hat, kann nichts
+#   faelschen, ohne dass es auffliegt. Bildlich: Der Schluessel ist der
+#   Stempel des Notars - die Akte liegt zwar im Schrank, aber den Stempel
+#   hat nur der Notar.
+#
+# Wie einrichten?
+#   Einmalig einen Schluessel erzeugen und hier eintragen:
+#       openssl rand -hex 32
+#   Pro Umgebung ein EIGENER Schluessel (Entwicklung, Test, Produktion).
+#
+# Was passiert, wenn ich ihn weglasse?
+#   Nichts faellt aus. Das Audit-Log laeuft normal weiter, nur eben ohne
+#   dieses zusaetzliche Siegel.
+#
+# Ich habe bisher keinen Schluessel - kann ich ihn nachtraeglich setzen?
+#   Ja. Schluessel erzeugen, eintragen, Backend neu starten - fertig.
+#   Bestehende Eintraege bleiben unveraendert gueltig, ab dem Neustart
+#   werden neue gesiegelt. Alt und neu liegen nebeneinander, es gibt
+#   dadurch KEINE Fehlalarme. Rueckwirkend siegeln geht nicht - je frueher
+#   gesetzt, desto groesser der geschuetzte Zeitraum.
+#
+# ACHTUNG: einmal gesetzt, nicht wieder abschalten.
+#   Fehlt der Schluessel spaeter (z. B. beim Container-Rebuild verlorengegangen),
+#   laeuft alles weiter - aber die in dieser Zeit entstandenen Eintraege sind
+#   ungesiegelt und werden beanstandet, sobald der Schluessel wieder da ist.
+#   Ein ungesiegelter Eintrag inmitten gesiegelter ist von einer Faelschung
+#   nicht zu unterscheiden. Also: in die Deploy-Checkliste aufnehmen.
+#
+# Was passiert, wenn ich ihn verliere?
+#   Laesst du das Feld LEER, gelten die gesiegelten Eintraege als
+#   "nicht pruefbar" - NICHT als gefaelscht, also kein Fehlalarm. Der
+#   Nachweis fuer diesen Zeitraum ist aber weg.
+#   Traegst du stattdessen einen NEUEN Schluessel ein, ohne den alten unten
+#   zu hinterlegen, werden die alten Eintraege als "manipuliert" gemeldet -
+#   ein falscher Schluessel ist von einer Faelschung nicht zu unterscheiden.
+#   Deshalb: Schluessel sichern, so wie ein Passwort.
+#
+# Eigenen Wert erzeugen mit:   openssl rand -hex 32
+# Der Platzhalter unten zaehlt NICHT als Schluessel - laesst du ihn stehen,
+# bleibt das Siegel aus (es wird also nicht versehentlich mit einem oeffentlich
+# bekannten Wert gesiegelt). Leer lassen ist ebenfalls in Ordnung.
+AUDIT_HMAC_KEY=<hier-eigenen-wert-eintragen>
+
+# Frueher verwendete Schluessel - beim Wechsel hier eintragen.
+#   Moechtest du den Schluessel oben austauschen (z. B. weil du vermutest,
+#   dass er in falsche Haende geraten ist), trage den ALTEN Schluessel hier
+#   ein und den NEUEN oben. Dann bleiben die bisherigen Eintraege pruefbar,
+#   waehrend neue schon mit dem neuen Schluessel gesiegelt werden.
+#
+#   ACHTUNG: Dieses Feld NICHT voreilig leeren. Solange Eintraege existieren,
+#   die mit einem alten Schluessel gesiegelt wurden, muessen sie hier stehen.
+#   Sonst werden diese Eintraege als "manipuliert" gemeldet (nicht als
+#   "nicht pruefbar"). Gefahrlos leeren kannst du erst, wenn die betroffenen
+#   Eintraege durch die Aufbewahrungsfristen ohnehin geloescht sind.
+#
+#   Mehrfach gewechselt? Mehrere Schluessel kommagetrennt, juengster zuerst:
+#       AUDIT_HMAC_KEY_OLD=<vorheriger>,<davor>,<ganz alter>
+#
+# Beim ersten Einrichten leer lassen - erst beim Schluesselwechsel noetig.
+AUDIT_HMAC_KEY_OLD=
+
+# --- Technisch (fuer Entwickler/Admins) ---------------------------------
+# Verfahren : HMAC-SHA256 ueber alle Inhaltsspalten eines Audit-Eintrags,
+#             inkl. previousHash (Verkettung). Entspricht Hash-Version 3.
+# Abdeckung : Version 1 = 7 Felder (Altbestand), Version 2 = alle 24
+#             Inhaltsspalten (SHA-256, unsigniert), Version 3 = wie 2, aber
+#             HMAC-signiert. Die erwartete Version wird aus der Kette
+#             abgeleitet (Version-Floor), nicht aus der Selbstauskunft der
+#             Zeile - sonst liesse sich per Downgrade die schwaechere
+#             Pruefung erzwingen.
+# Fail-safe : Ohne Schluessel schreibt der Dienst weiter Version 2. Bereits
+#             signierte Zeilen landen dann in `unverifiableEntries`,
+#             ausdruecklich NICHT in `tamperedEntries`.
+# Rotation  : AUDIT_HMAC_KEY_OLD (kommagetrennte Liste) wird bei der
+#             Pruefung zusaetzlich akzeptiert - Wechsel ohne Rehash. Ein
+#             falscher/fehlender Alt-Schluessel liefert einen HMAC-Mismatch
+#             und damit einen Manipulations-Befund; das ist nicht von einer
+#             echten Faelschung unterscheidbar und daher Absicht.
+# Grenze    : Schuetzt gegen DB-Schreibzugriff ohne Schluessel. Wer Schluessel
+#             UND Datenbank hat, kann die Kette konsistent neu rechnen.
+# Erzeugung : openssl rand -hex 32 (256 Bit)
+
+# ==================== DIENSTKONTO-WACHHUND ====================
+# Nach wie vielen Minuten Stille eines Dienstkontos (z. B. des Gegenbuchs)
+# ein Sicherheitsereignis erzeugt wird.
+#
+# Hintergrund: Die planmaessigen Anmeldungen selbst sind bewusst als Routine
+# eingestuft, damit sie die CRITICAL-Stufe nicht entwerten. Das Signal ist
+# deshalb die ABWESENHEIT: Wer das Gegenbuch stilllegt, setzt darauf, dass
+# Stille nicht auffaellt.
+#
+# Faustregel: etwa das Dreifache des Gegenbuch-Takts. Bei stuendlichem Takt
+# also 180. Ohne Dienstkonten im System passiert nichts.
+SERVICE_ACCOUNT_MAX_SILENCE_MINUTES=180

backend/prisma/migrations/20260818140000_audit_chain_lock/migration.sql

@@ -0,0 +1,15 @@
+-- Einzeiliger Mutex fuer die Audit-Hash-Kette (Pentest R166-01).
+--
+-- Vorher wurde ueber GET_LOCK serialisiert. Dessen RELEASE_LOCK muss auf
+-- derselben Verbindung laufen und stand daher im finally INNERHALB des
+-- Transaktions-Callbacks - also VOR dem COMMIT. In diesem Fenster konnte der
+-- naechste Schreiber die Sperre holen und das Kettenende lesen, bevor die
+-- Vorgaengerzeile committed war: beide haengten sich an denselben Vorgaenger
+-- (Fork). InnoDB-Zeilensperren fallen dagegen erst beim COMMIT.
+CREATE TABLE IF NOT EXISTS `AuditChainLock` (
+  `id`        INT NOT NULL,
+  `updatedAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+INSERT IGNORE INTO `AuditChainLock` (`id`, `updatedAt`) VALUES (1, NOW(3));

backend/prisma/migrations/20260818150000_audit_hash_version/migration.sql

@@ -0,0 +1,13 @@
+-- Hash-Versionierung fuer Audit-Eintraege (Pentest R166-02).
+--
+-- Der bisherige Hash deckte nur 7 Felder ab (userEmail, action, resourceType,
+-- resourceId, endpoint, createdAt, previousHash). NICHT gehasht waren u. a.
+-- changesBefore/changesAfter (die eigentliche Nutzlast), success, ipAddress,
+-- resourceLabel, dataSubjectId, userId/customerId - ein nachtraeglicher
+-- Einzeledit an genau diesen Feldern blieb also unsichtbar.
+--
+-- Version 2 hasht alle Inhaltsspalten. Bestandszeilen behalten Version 1 und
+-- werden weiterhin mit dem alten Verfahren geprueft - kein Rehash noetig,
+-- die Beweiskraft der Vergangenheit bleibt erhalten.
+ALTER TABLE `AuditLog`
+  ADD COLUMN IF NOT EXISTS `hashVersion` INT NOT NULL DEFAULT 1;

backend/prisma/migrations/20260818160000_refresh_token_replay/migration.sql

@@ -0,0 +1,28 @@
+-- Replay-Schutz fuer Refresh-Tokens (Pentest R164-02).
+--
+-- Die bisherige Rotation bot keinen Replay-Schutz: der alte Token blieb bis exp
+-- gueltig (7 Tage), ein gestohlener Token war also parallel zum legitimen
+-- nutzbar. Jetzt traegt jeder Refresh-Token eine jti und gehoert zu einer
+-- Sitzungsfamilie; beim Einloesen wird die jti verbraucht. Taucht sie erneut
+-- auf, wird die gesamte Familie widerrufen und der Vorfall gemeldet.
+CREATE TABLE IF NOT EXISTS `RefreshTokenRecord` (
+  `id`               INT NOT NULL AUTO_INCREMENT,
+  `jti`              VARCHAR(191) NOT NULL,
+  `familyId`         VARCHAR(191) NOT NULL,
+  `userId`           INT NULL,
+  `customerId`       INT NULL,
+  `isCustomerPortal` TINYINT(1) NOT NULL DEFAULT 0,
+  `issuedAt`         DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  `expiresAt`        DATETIME(3) NOT NULL,
+  `usedAt`           DATETIME(3) NULL,
+  `replacedByJti`    VARCHAR(191) NULL,
+  `reuseCount`       INT NOT NULL DEFAULT 0,
+  `revokedAt`        DATETIME(3) NULL,
+  `revokedReason`    VARCHAR(191) NULL,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `RefreshTokenRecord_jti_key` (`jti`),
+  KEY `RefreshTokenRecord_familyId_idx` (`familyId`),
+  KEY `RefreshTokenRecord_expiresAt_idx` (`expiresAt`),
+  KEY `RefreshTokenRecord_userId_idx` (`userId`),
+  KEY `RefreshTokenRecord_customerId_idx` (`customerId`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

backend/prisma/migrations/20260818170000_audit_backlog_seal/migration.sql

@@ -0,0 +1,16 @@
+-- Bestandssiegel fuer den nicht signierbaren Altbestand (Pentest R171-02).
+--
+-- Bei Hash-Version 1 sind nur 7 von 24 Spalten gehasht. Ein Schreibzugriff auf
+-- die Datenbank kann dort Felder wie `success` oder `resourceLabel` aendern,
+-- ohne den gespeicherten Hash zu beruehren - die Pruefung meldet weiterhin
+-- "gueltig". Live gezeigt: ein fehlgeschlagener Login liess sich unsichtbar in
+-- einen erfolgreichen umschreiben.
+--
+-- Rueckwirkend signieren geht nicht. Stattdessen wird der Altbestand einmalig
+-- versiegelt: je Zeile ein Blattwert ueber den vollen Inhalt, die Wurzel
+-- darueber in einem HMAC-signierten Marker.
+CREATE TABLE IF NOT EXISTS `AuditBacklogSeal` (
+  `auditLogId` INT NOT NULL,
+  `leafHash`   VARCHAR(191) NOT NULL,
+  PRIMARY KEY (`auditLogId`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

backend/prisma/migrations/20260822100000_user_service_account/migration.sql

@@ -0,0 +1,9 @@
+-- Dienstkonto-Kennzeichen (Pentest R182).
+--
+-- Das Gegenbuch meldet sich stuendlich an. Diese Anmeldung wurde bisher als
+-- Authentication/CRITICAL protokolliert - also das vorhersagbarste Ereignis im
+-- System auf der hoechsten Stufe. Damit trainiert die Routine den Betreiber
+-- darauf, CRITICAL wegzuklicken, und der erste ECHTE Vorfall erbt diesen
+-- Reflex. Mit dem Kennzeichen werden solche Anmeldungen als Routine gefuehrt.
+ALTER TABLE `User`
+  ADD COLUMN IF NOT EXISTS `isServiceAccount` BOOLEAN NOT NULL DEFAULT false;

backend/prisma/migrations/20260826120000_audit_seal_changed_event/migration.sql

@@ -0,0 +1,17 @@
+-- Neuer SecurityEventType AUDIT_SEAL_CHANGED (Pentest R185-01).
+--
+-- Das Setzen oder Ersetzen des Bestandssiegels veraendert die Grundlage, gegen
+-- die spaeter Manipulation nachgewiesen wird. Bisher landete das ausschliesslich
+-- als CRITICAL-Zeile im Audit-Log - also in einem Kanal, den ein Mensch lesen
+-- muss. Der Alarmkanal ist ein separater Store; ohne eigenen Ereignistyp gab es
+-- dort gar keinen Eintrag, und `valid` bleibt bei einem ersetzenden Siegel
+-- konstruktionsbedingt `true`.
+--
+-- MODIFY COLUMN ist idempotent (setzt die Enum-Definition, mehrfach ausfuehrbar).
+ALTER TABLE `SecurityEvent`
+  MODIFY COLUMN `type` ENUM(
+    'LOGIN_FAILED','LOGIN_SUCCESS','RATE_LIMIT_HIT','ACCESS_DENIED',
+    'SSRF_BLOCKED','PASSWORD_RESET_REQUEST','PASSWORD_RESET_CONFIRM',
+    'LOGOUT','TOKEN_REJECTED','PERMISSION_CHANGED','AUDIT_SEAL_CHANGED',
+    'SUSPICIOUS'
+  ) NOT NULL;

backend/prisma/schema.prisma

@@ -76,6 +76,11 @@ model User {
   firstName          String
   lastName           String
   isActive           Boolean   @default(true)
+  /// Dienstkonto (z. B. das Gegenbuch). Meldet sich planmaessig und haeufig an.
+  /// Solche Anmeldungen werden im Audit-Log als Routine gefuehrt statt als
+  /// CRITICAL - sonst trainiert das vorhersagbarste Ereignis im System den
+  /// Betreiber darauf, die hoechste Stufe wegzuklicken (Pentest R182).
+  isServiceAccount   Boolean   @default(false)
   tokenInvalidatedAt DateTime? // Zeitpunkt ab dem alle Tokens ungültig sind (für Zwangslogout bei Rechteänderung)
 
   // Passwort-Reset
@@ -1221,6 +1226,76 @@ model CarInsuranceDetails {
 
 // ==================== AUDIT LOGGING (DSGVO) ====================
 
+/// Einzeiliger Mutex fuer die Audit-Hash-Kette (genau eine Zeile, id = 1).
+///
+/// Warum eine eigene Tabelle statt GET_LOCK oder `SELECT … FOR UPDATE` auf
+/// AuditLog selbst:
+///  - GET_LOCK muss auf derselben Verbindung freigegeben werden. Innerhalb des
+///    Prisma-Transaktions-Callbacks faellt das Release damit VOR den COMMIT –
+///    der naechste Schreiber liest das Kettenende, bevor die Vorgaengerzeile
+///    sichtbar ist, und haengt sich an denselben Vorgaenger (Fork, R166-01).
+///  - `FOR UPDATE` auf das Kettenende von AuditLog nimmt Gap-/Next-Key-Locks,
+///    die mit den gleichzeitigen INSERTs kollidieren (Deadlocks, dabei gingen
+///    38 von 40 Eintraegen verloren).
+/// InnoDB-Zeilensperren werden erst beim COMMIT freigegeben – genau das
+/// schliesst das Fenster.
+model AuditChainLock {
+  id        Int      @id
+  updatedAt DateTime @updatedAt
+}
+
+/// Ausgegebene Refresh-Tokens (Pentest R164-02).
+///
+/// Vorher war die Rotation wirkungslos: Der alte Token blieb bis `exp`
+/// gueltig, ein gestohlener Token also bis zu 7 Tage parallel nutzbar.
+/// Jetzt traegt jeder Refresh-Token eine `jti` und gehoert zu einer
+/// Sitzungs-`familyId`. Beim Einloesen wird die `jti` verbraucht; taucht sie
+/// danach erneut auf, gilt das als Replay und die GESAMTE Familie wird
+/// widerrufen (Angreifer und legitimer Nutzer fliegen raus, der Vorfall wird
+/// gemeldet) - das uebliche Vorgehen aus der OAuth-Sicherheits-BCP.
+///
+/// Der Token selbst wird NICHT gespeichert - die Signatur authentifiziert ihn
+/// bereits, und ein DB-Leck soll keine nutzbaren Sitzungen preisgeben.
+model RefreshTokenRecord {
+  id              Int       @id @default(autoincrement())
+  jti             String    @unique
+  familyId        String
+  userId          Int?
+  customerId      Int?
+  isCustomerPortal Boolean  @default(false)
+  issuedAt        DateTime  @default(now())
+  expiresAt       DateTime
+  /// Gesetzt, sobald der Token eingeloest wurde (Einmalverwendung).
+  usedAt          DateTime?
+  replacedByJti   String?
+  /// Wiederverwendungen innerhalb des Kulanzfensters (parallele Tabs).
+  reuseCount      Int       @default(0)
+  revokedAt       DateTime?
+  revokedReason   String?
+
+  @@index([familyId])
+  @@index([expiresAt])
+  @@index([userId])
+  @@index([customerId])
+}
+
+/// Blattwerte des Bestandssiegels (Pentest R171-02 / R172).
+///
+/// Der Altbestand (Hash-Version 1/2) laesst sich nicht rueckwirkend signieren –
+/// ein Siegel vergibt man beim Anlegen. Bei V1 sind nur 7 von 24 Spalten
+/// gehasht, ein DB-Schreiber kann dort z. B. `success` von false auf true
+/// setzen, ohne den Hash zu beruehren: die Pruefung meldet weiterhin "gueltig".
+///
+/// Das Bestandssiegel schliesst das, ohne irgendetwas umzuschreiben: Zum
+/// Zeitpunkt X wird je Altzeile ein Blattwert ueber den VOLLEN Inhalt
+/// (alle Spalten inkl. id und hashVersion) gebildet; die Wurzel darueber
+/// steht in einem HMAC-signierten Marker. Jede spaetere Aenderung an einer
+/// Altzeile bricht Blatt und Wurzel.
+model AuditBacklogSeal {
+  auditLogId Int    @id
+  leafHash   String
+}
+
 enum AuditAction {
   CREATE
   READ
@@ -1284,6 +1359,9 @@ model AuditLog {
   createdAt        DateTime         @default(now())
   hash             String?          // SHA-256 Hash des Eintrags
   previousHash     String?          // Hash des vorherigen Eintrags
+  /// 1 = Alt-Hash ueber 7 Felder, 2 = Hash ueber alle Inhaltsspalten
+  /// (Pentest R166-02). Bestandszeilen bleiben mit Version 1 gueltig.
+  hashVersion      Int              @default(1)
 
   @@index([userId])
   @@index([customerId])
@@ -1404,6 +1482,7 @@ enum SecurityEventType {
   LOGOUT                  // expliziter Logout
   TOKEN_REJECTED          // ungültiger / abgelaufener / manipulierter JWT
   PERMISSION_CHANGED      // Admin hat Rolle/Permission geändert
+  AUDIT_SEAL_CHANGED      // Bestandssiegel gesetzt oder ersetzt (Beweis-Grundlage)
   SUSPICIOUS              // generischer Catch-All
 }
 

backend/prisma/seed.ts

@@ -106,7 +106,7 @@ async function main() {
     update: {},
     create: {
       name: 'Admin',
-      description: 'Voller Zugriff auf alle Funktionen',
+      description: 'Voller Zugriff auf alle Fachfunktionen (ohne Audit & Datenschutz – dafür die separaten Rollen DSGVO und Audit-Betrieb)',
       permissions: {
         create: adminPermissions.map((p) => ({ permissionId: p.id })),
       },
@@ -129,16 +129,29 @@ async function main() {
   });
   await syncRolePermissions(developerRole.id, developerPermissions.map((p) => p.id));
 
-  // DSGVO - audit and gdpr permissions (hidden role, controlled via hasGdprAccess)
+  // DSGVO - Datenschutz-Verwaltung plus LESENDER Zugriff aufs Audit-Protokoll.
+  //
+  // Bewusst OHNE `audit:admin`: Wer das Protokoll beaufsichtigt, darf seine
+  // eigene Beweisgrundlage nicht ersetzen koennen (Pentest R186). Die
+  // eingreifenden Rechte liegen in der Rolle `Audit-Betrieb`.
+  //
+  // Diese Liste stand hier bis 09/2026 noch auf `audit:*` komplett und war
+  // damit die dritte Stelle, die denselben Rechtesatz beschrieb - neben
+  // `sync-roles.ts` und dem Notfallpfad in `user.service.ts`. Gerettet hat es
+  // nur die Reihenfolge im Container-Start (sync-roles laeuft danach und
+  // raeumt Ueberzaehliges weg); ein einzelnes `npm run db:seed` brachte die
+  // Buendelung zurueck.
   const gdprPermissions = allPermissions.filter(
-    (p) => p.resource === 'audit' || p.resource === 'gdpr'
+    (p) =>
+      p.resource === 'gdpr' ||
+      (p.resource === 'audit' && (p.action === 'read' || p.action === 'export'))
   );
   const gdprRole = await prisma.role.upsert({
     where: { name: 'DSGVO' },
     update: {},
     create: {
       name: 'DSGVO',
-      description: 'DSGVO-Zugriff: Audit-Logs und Datenschutz-Verwaltung',
+      description: 'DSGVO-Zugriff: Audit-Logs lesen und Datenschutz-Verwaltung',
       permissions: {
         create: gdprPermissions.map((p) => ({ permissionId: p.id })),
       },
@@ -265,8 +278,19 @@ async function main() {
       password: hashedPassword,
       firstName: 'Admin',
       lastName: 'User',
+      // Zusaetzlich die DSGVO-Rolle (Pentest R189-01).
+      //
+      // Ohne sie kann nach einem frischen Seed NIEMAND eine Auskunft nach
+      // Art. 15 oder eine Loeschung nach Art. 17 ausfuehren - die Rechte
+      // haengen an DSGVO und Developer, und beide waren keinem Konto
+      // zugewiesen. Ein Ausfall mit Fristwirkung, ausgeloest durch nichts
+      // weiter als eine Neuinstallation.
+      //
+      // Die Trennung bleibt: Die Admin-ROLLE bekommt diese Rechte weiterhin
+      // nicht. Nur dieses eine Bootstrap-Konto traegt beide, damit ueberhaupt
+      // jemand handlungsfaehig ist.
       roles: {
-        create: [{ roleId: adminRole.id }],
+        create: [{ roleId: adminRole.id }, { roleId: gdprRole.id }],
       },
     },
   });

backend/prisma/sync-roles.ts

@@ -93,9 +93,52 @@ async function main() {
   // Developer: alles
   const developerPermIds = allPermissions.map((p) => p.id);
 
-  // DSGVO: audit + gdpr komplett
+  // DSGVO: Datenschutz-Verwaltung plus LESENDEN Zugriff aufs Audit-Protokoll.
+  //
+  // Bewusst OHNE `audit:admin`. Diese Rolle beaufsichtigt das Protokoll - sie
+  // darf es nicht umschreiben koennen. Mit `audit:admin` haette ein
+  // DSGVO-Beauftragter `seal-backlog`, `rehash` und `cleanup`, also die Mittel,
+  // seine eigene Beweisgrundlage zu ersetzen. Wer prueft und wer eingreift,
+  // sind zwei Rollen (Pentest R186, im Anschluss an R184-02: falsche Domaene,
+  // zu breit gebuendelt).
   const gdprPermIds = allPermissions
-    .filter((p) => p.resource === 'audit' || p.resource === 'gdpr')
+    .filter(
+      (p) =>
+        p.resource === 'gdpr' ||
+        (p.resource === 'audit' && (p.action === 'read' || p.action === 'export')),
+    )
+    .map((p) => p.id);
+
+  // Audit-Betrieb: die eingreifenden Rechte am Protokoll - versiegeln,
+  // neu berechnen, aufraeumen, Aufbewahrung aendern. Plus `audit:read`, denn
+  // siegeln zu duerfen ohne das Ergebnis sehen zu koennen waere unbrauchbar.
+  //
+  // Eigene versteckte Rolle statt einem Anhaengsel an Admin: So weitet sich
+  // durch die Umstellung fuer KEIN bestehendes Konto etwas aus. Wer eingreifen
+  // koennen soll, bekommt es ausdruecklich - und diese Zuweisung ist selbst
+  // ein sichtbarer Vorgang.
+  const auditBetriebPermIds = allPermissions
+    .filter(
+      (p) => p.resource === 'audit' && (p.action === 'read' || p.action === 'admin'),
+    )
+    .map((p) => p.id);
+
+  // Gegenbuch: NUR audit:read.
+  //
+  // Der externe Notar ruft genau zwei Endpunkte auf, /audit-logs/checkpoint
+  // und /audit-logs/verify, und beide verlangen audit:read. Bis hierher gab es
+  // dafuer keine passende Rolle: Wer dem Dienstkonto Leserechte aufs Protokoll
+  // geben wollte, musste den DSGVO-Haken setzen - und der vergibt `audit:*`
+  // KOMPLETT, also auch `audit:admin` mit seal-backlog, rehash und cleanup.
+  //
+  // Damit haette ein Einbruch auf der Gegenbuch-Maschine nicht nur den
+  // Waechter gehabt, sondern gleich die Mittel, das Bewachte umzuschreiben -
+  // genau die Waesche aus R185-01, und genau die Trennung, wegen der das
+  // Gegenbuch ueberhaupt auf einer eigenen Maschine laeuft. Das Kennwort des
+  // Dienstkontos liegt dort im Klartext in der .env; es muss deshalb so wenig
+  // wert sein wie moeglich.
+  const gegenbuchPermIds = allPermissions
+    .filter((p) => p.resource === 'audit' && p.action === 'read')
     .map((p) => p.id);
 
   // Mitarbeiter: customers + contracts + read auf Stammdaten
@@ -132,11 +175,13 @@ async function main() {
     .map((p) => p.id);
 
   const rolesSpec: Array<{ name: string; description: string; permIds: number[] }> = [
-    { name: 'Admin', description: 'Voller Zugriff auf alle Funktionen', permIds: adminPermIds },
+    { name: 'Admin', description: 'Voller Zugriff auf alle Fachfunktionen (ohne Audit & Datenschutz – dafür die separaten Rollen DSGVO und Audit-Betrieb)', permIds: adminPermIds },
     { name: 'Developer', description: 'Voller Zugriff inkl. Entwickler-Tools', permIds: developerPermIds },
-    { name: 'DSGVO', description: 'DSGVO-Zugriff: Audit-Logs und Datenschutz-Verwaltung', permIds: gdprPermIds },
+    { name: 'DSGVO', description: 'DSGVO-Zugriff: Audit-Logs lesen und Datenschutz-Verwaltung', permIds: gdprPermIds },
+    { name: 'Audit-Betrieb', description: 'Darf das Audit-Protokoll versiegeln, aufräumen und die Aufbewahrung ändern', permIds: auditBetriebPermIds },
     { name: 'Mitarbeiter', description: 'Kann Kunden und Verträge verwalten', permIds: employeePermIds },
     { name: 'Mitarbeiter (Nur-Lesen)', description: 'Kann nur lesen, keine Änderungen', permIds: readOnlyPermIds },
+    { name: 'Gegenbuch', description: 'Darf das Audit-Protokoll nur lesen und prüfen – sonst nichts', permIds: gegenbuchPermIds },
     { name: 'Kunde', description: 'Kann nur eigene Daten lesen', permIds: readOnlyPermIds },
   ];
 

backend/src/controllers/auditLog.controller.ts

@@ -3,46 +3,119 @@ import { AuthRequest } from '../types/index.js';
 import * as auditService from '../services/audit.service.js';
 import { logChange } from '../services/audit.service.js';
 import { AuditAction, AuditSensitivity } from '@prisma/client';
+import { emit as emitSecurityEvent, contextFromRequest } from '../services/securityMonitor.service.js';
+
+/**
+ * Filterwerte aus der Query pruefen (Pentest R185-02).
+ *
+ * Vorher gingen `action` und `sensitivity` als roher String an die Enum-Spalte.
+ * Ein ungueltiger Wert liess Prisma auflaufen und der Handler antwortete 500.
+ * Das ist zweierlei: eine fehlende Validierung – und ein Fehler-Orakel. Wer
+ * 200 gegen 500 vergleicht, liest die Enum-Mitglieder aus, ohne sie zu kennen.
+ * Ein ungueltiger Filter ist eine schlechte ANFRAGE, keine Server-Panne: 400.
+ *
+ * Dasselbe gilt fuer Datumsangaben (`new Date('foo')` ergibt Invalid Date und
+ * sprengt die Query erst in der Datenbank) und fuer Zahlen (`parseInt('x')`
+ * ergibt NaN).
+ */
+class FilterFehler extends Error {}
+
+const AUDIT_ACTIONS = Object.values(AuditAction) as string[];
+const AUDIT_SENSITIVITIES = Object.values(AuditSensitivity) as string[];
+
+function pruefeEnum<T extends string>(
+  wert: unknown, erlaubt: string[], feld: string,
+): T | undefined {
+  if (wert === undefined || wert === '') return undefined;
+  if (typeof wert !== 'string' || !erlaubt.includes(wert)) {
+    // Die erlaubten Werte stehen ohnehin in der Oberflaeche und im Schema –
+    // sie zu nennen verraet nichts und erspart Rateversuche.
+    throw new FilterFehler(
+      `Ungültiger Wert für "${feld}". Erlaubt: ${erlaubt.join(', ')}.`,
+    );
+  }
+  return wert as T;
+}
+
+function pruefeDatum(wert: unknown, feld: string): Date | undefined {
+  if (wert === undefined || wert === '') return undefined;
+  const d = new Date(wert as string);
+  if (Number.isNaN(d.getTime())) {
+    throw new FilterFehler(`Ungültiges Datum für "${feld}".`);
+  }
+  return d;
+}
+
+function pruefeZahl(wert: unknown, feld: string): number | undefined {
+  if (wert === undefined || wert === '') return undefined;
+  const n = Number(wert);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new FilterFehler(`Ungültige Zahl für "${feld}".`);
+  }
+  return n;
+}
+
+/** Freitextfelder begrenzen – unbegrenzte LIKE-Muster sind teuer. */
+function pruefeText(wert: unknown, feld: string, maxLaenge = 200): string | undefined {
+  if (wert === undefined || wert === '') return undefined;
+  if (typeof wert !== 'string' || wert.length > maxLaenge) {
+    throw new FilterFehler(`Ungültiger Wert für "${feld}" (max. ${maxLaenge} Zeichen).`);
+  }
+  return wert;
+}
+
+/**
+ * Filter aus der Query lesen – EINE Stelle fuer Liste und Export (R186-01).
+ *
+ * Vorher pflegte jeder Endpunkt seine eigene Liste, und die des Exports war
+ * kuerzer: `userId`, `customerId`, `dataSubjectId`, `resourceId`, `success` und
+ * `search` wurden dort stillschweigend verworfen. Ein bewusst eingegrenzter
+ * Export – „nur die Spur von Benutzer X“ fuer eine DSGVO-Auskunft oder eine
+ * Innentaeter-Pruefung – lieferte damit das VOLLSTAENDIGE Protokoll aller
+ * Nutzer zurueck. Mit HTTP 200 und ohne jeden Hinweis: ein beruhigendes
+ * Signal ueber einem Ergebnis, das genau das Gegenteil dessen ist, was
+ * angefragt wurde. Auf einem datenminimierungspflichtigen Export ist das
+ * nicht nur ein fehlender Filter, sondern eine Weitergabe.
+ *
+ * Zwei Listen, die dasselbe bedeuten sollen, laufen frueher oder spaeter
+ * auseinander. Deshalb gibt es jetzt nur noch diese eine.
+ */
+function leseFilter(req: AuthRequest) {
+  const q = req.query;
+  return {
+    userId: pruefeZahl(q.userId, 'userId'),
+    customerId: pruefeZahl(q.customerId, 'customerId'),
+    dataSubjectId: pruefeZahl(q.dataSubjectId, 'dataSubjectId'),
+    action: pruefeEnum<AuditAction>(q.action, AUDIT_ACTIONS, 'action'),
+    sensitivity: pruefeEnum<AuditSensitivity>(q.sensitivity, AUDIT_SENSITIVITIES, 'sensitivity'),
+    resourceType: pruefeText(q.resourceType, 'resourceType', 100),
+    resourceId: pruefeText(q.resourceId, 'resourceId', 100),
+    startDate: pruefeDatum(q.startDate, 'startDate'),
+    endDate: pruefeDatum(q.endDate, 'endDate'),
+    success: q.success !== undefined ? q.success === 'true' : undefined,
+    search: pruefeText(q.search, 'search'),
+  };
+}
 
 /**
  * Audit-Logs mit Filtern abrufen
  */
 export async function getAuditLogs(req: AuthRequest, res: Response) {
   try {
-    const {
-      userId,
-      customerId,
-      dataSubjectId,
-      action,
-      sensitivity,
-      resourceType,
-      resourceId,
-      startDate,
-      endDate,
-      success,
-      search,
-      page,
-      limit,
-    } = req.query;
-
     const result = await auditService.searchAuditLogs({
-      userId: userId ? parseInt(userId as string) : undefined,
+      ...leseFilter(req),
-      customerId: customerId ? parseInt(customerId as string) : undefined,
+      page: pruefeZahl(req.query.page, 'page') || 1,
-      dataSubjectId: dataSubjectId ? parseInt(dataSubjectId as string) : undefined,
+      // Deckel: sonst laesst sich ueber `limit` die gesamte Tabelle in einem
-      action: action as AuditAction | undefined,
+      // Zug ziehen, an der Seitenlogik vorbei.
-      sensitivity: sensitivity as AuditSensitivity | undefined,
+      limit: Math.min(pruefeZahl(req.query.limit, 'limit') || 50, 200),
-      resourceType: resourceType as string | undefined,
-      resourceId: resourceId as string | undefined,
-      startDate: startDate ? new Date(startDate as string) : undefined,
-      endDate: endDate ? new Date(endDate as string) : undefined,
-      success: success !== undefined ? success === 'true' : undefined,
-      search: search as string | undefined,
-      page: page ? parseInt(page as string) : 1,
-      limit: limit ? parseInt(limit as string) : 50,
     });
 
     res.json({ success: true, ...result });
   } catch (error) {
+    if (error instanceof FilterFehler) {
+      res.status(400).json({ success: false, error: error.message });
+      return;
+    }
     console.error('Fehler beim Abrufen der Audit-Logs:', error);
     res.status(500).json({ success: false, error: 'Fehler beim Abrufen der Audit-Logs' });
   }
@@ -96,25 +169,8 @@ export async function getAuditLogsByCustomer(req: AuthRequest, res: Response) {
  */
 export async function exportAuditLogs(req: AuthRequest, res: Response) {
   try {
-    const format = (req.query.format as 'json' | 'csv') || 'json';
+    const format = req.query.format === 'csv' ? 'csv' : 'json';
-    const {
+    const content = await auditService.exportAuditLogs(leseFilter(req), format);
-      action,
-      sensitivity,
-      resourceType,
-      startDate,
-      endDate,
-    } = req.query;
-
-    const content = await auditService.exportAuditLogs(
-      {
-        action: action as AuditAction | undefined,
-        sensitivity: sensitivity as AuditSensitivity | undefined,
-        resourceType: resourceType as string | undefined,
-        startDate: startDate ? new Date(startDate as string) : undefined,
-        endDate: endDate ? new Date(endDate as string) : undefined,
-      },
-      format
-    );
 
     if (format === 'csv') {
       const filename = `audit-logs-${new Date().toISOString().split('T')[0]}.csv`;
@@ -126,6 +182,10 @@ export async function exportAuditLogs(req: AuthRequest, res: Response) {
       res.json({ success: true, data: JSON.parse(content) })
     }
   } catch (error) {
+    if (error instanceof FilterFehler) {
+      res.status(400).json({ success: false, error: error.message });
+      return;
+    }
     console.error('Fehler beim Exportieren der Audit-Logs:', error);
     res.status(500).json({ success: false, error: 'Fehler beim Exportieren' });
   }
@@ -148,14 +208,148 @@ export async function verifyIntegrity(req: AuthRequest, res: Response) {
     // echten Angriff aussehen liess (und damit die Meldung entwertete).
     const tampered = result.tamperedEntries.length;
     const gaps = result.chainGaps.length;
+    const unexplained = result.unexplainedGaps.length;
+    // Beglaubigte Alt-Luecken sind kein offener Befund mehr, verschwinden aber
+    // auch nicht aus dem Bericht - sie werden eigens benannt.
+    const beglaubigt = result.attestedGaps.length;
+    const offeneGaps = gaps - beglaubigt;
+    const offeneUnexplained = result.unexplainedGaps.filter(
+      (id) => !result.attestedGaps.includes(id),
+    ).length;
 
+    const luecken = offeneGaps > 0
+      ? `${offeneGaps} strukturelle Lücke${offeneGaps === 1 ? '' : 'n'}` +
+        (offeneUnexplained === 0
+          ? ' (alle durch protokollierte Löschungen erklärt)'
+          : offeneUnexplained < offeneGaps
+            ? `, davon ${offeneUnexplained} ohne dokumentierte Löschung`
+            : ' ohne dokumentierte Löschung')
+      : '';
+
+    // Der Satz erscheint IMMER, wenn beglaubigte Luecken existieren - auch
+    // neben einem Befund. Wer den Bericht liest, soll nie den Eindruck
+    // bekommen, die Kette sei lueckenlos, wenn sie es nicht ist.
+    const weitere = tampered > 0 || offeneGaps > 0 ? 'weitere ' : '';
+    const beglaubigtText =
+      beglaubigt === 0
+        ? ''
+        : beglaubigt === 1
+          ? ` Eine ${weitere}Lücke stammt aus der Zeit vor dem Bestandssiegel und ist darin als ` +
+            `Vorbefund beglaubigt (ID ${result.attestedGaps[0]}); der betroffene Eintrag selbst ` +
+            'ist unverändert.'
+          : ` ${beglaubigt} ${weitere}Lücken stammen aus der Zeit vor dem Bestandssiegel und sind ` +
+            `darin als Vorbefund beglaubigt (IDs ${result.attestedGaps.join(', ')}); ` +
+            'die betroffenen Einträge selbst sind unverändert.';
+
+    const unverifiable = result.unverifiableEntries.length;
+    const keinSchluessel = unverifiable > 0
+      ? ` ${unverifiable} Einträge sind HMAC-signiert und ohne konfigurierten AUDIT_HMAC_KEY nicht prüfbar.`
+      : '';
+
+    const siegel =
+      result.backlogSealStatus === 'gebrochen'
+        ? ' ⚠ Bestandssiegel GEBROCHEN:' +
+          (result.backlogTampered.length
+            ? ` ${result.backlogTampered.length} Alteinträge nachträglich verändert.`
+            : '') +
+          (result.backlogMissing.length
+            ? ` ${result.backlogMissing.length} gesiegelte Einträge wurden ENTFERNT (${result.backlogMissing.join(', ')}).`
+            : '') +
+          (!result.backlogTampered.length && !result.backlogMissing.length
+            ? ' Der Blattbestand des Siegels stimmt nicht mehr mit der signierten Wurzel überein.'
+            : '')
+        : result.backlogSealStatus === 'entfernt'
+          ? ' ⚠ Bestandssiegel ENTFERNT: Es liegen versiegelte Blattwerte vor, aber kein gültiger ' +
+            'Siegel-Marker mehr. Der Marker wurde gelöscht oder unbrauchbar gemacht – Änderungen am ' +
+            'Altbestand wären dadurch wieder unsichtbar. Das ist KEIN Normalzustand.'
+          : result.backlogSealStatus === 'leer'
+            ? ' Hinweis: Es besteht ein Bestandssiegel, das aber NICHTS umschließt – ' +
+              'zum Zeitpunkt des Siegelns gab es keine unsignierten Alteinträge. Es sichert ' +
+              'also nichts ab. Das ist kein Fehler, aber auch keine Zusage.'
+          : result.backlogSealStatus === 'nicht_noetig'
+            ? ' Ein Bestandssiegel wird hier nicht gebraucht: Es gibt keine unsignierten Alteinträge.'
+            : result.backlogSealStatus === 'kein_siegel'
+              ? ' Hinweis: Der Altbestand ist nicht versiegelt – Änderungen daran wären nicht erkennbar. ' +
+                'Behebbar mit POST /api/audit-logs/seal-backlog {"confirm":"SEAL"}.'
+              : '';
+
+    // Eine Neuberechnung der Kette gehoert IMMER erwaehnt – auch und gerade,
+    // wenn sonst alles grün ist. Nach einem Rehash ist die Kette
+    // zwangslaeufig stimmig, auch ueber Loeschungen hinweg. „Lueckenlos
+    // verkettet“ heisst dann nur noch „seit dem Rehash“, und wer das nicht
+    // mitliest, nimmt eine Entwarnung mit, die es so nicht gibt.
+    const rehashText = (() => {
+      if (result.rehashes.length === 0) return '';
+      const letzter = result.rehashes[result.rehashes.length - 1];
+      const datum = new Date(letzter.zeitpunkt).toLocaleString('de-DE', {
+        dateStyle: 'short',
+        timeStyle: 'short',
+      });
+      const wieOft =
+        result.rehashes.length === 1
+          ? 'Die Kette wurde einmal neu berechnet'
+          : `Die Kette wurde ${result.rehashes.length}× neu berechnet, zuletzt`;
+      // Nur benennen, was es zu benennen gibt. Bei sauberem Vorzustand ist die
+      // Auskunft „nichts uebertuencht“ selbst eine nuetzliche Information –
+      // ein Rehash ueber einer unbeanstandeten Kette wiegt anders als einer
+      // ueber 700 Luecken.
+      const vb = letzter.vorbefund;
+      const uebertuencht = !vb
+        ? ' Der Zustand vor dieser Neuberechnung ist nicht mehr feststellbar.'
+        : vb.manipuliert === 0 && vb.luecken === 0
+          ? ' Die Kette war unmittelbar davor unbeanstandet – es wurde nichts überdeckt.'
+          : ' Unmittelbar davor: ' +
+            `${vb.manipuliert} beanstandete${vb.manipuliert === 1 ? 'r Eintrag' : ' Einträge'}` +
+            ` und ${vb.luecken} Lücke${vb.luecken === 1 ? '' : 'n'}. ` +
+            'Diese Spuren sind seitdem nicht mehr in der Kette sichtbar, sondern nur noch im ' +
+            `Vorbefund des Rehash-Eintrags (id ${letzter.id}).`;
+      const ohneSignatur = result.rehashes.some((r) => !r.signiert)
+        ? ' Achtung: Mindestens ein Rehash-Eintrag trägt keine gültige Signatur.'
+        : '';
+      return (
+        ` ⚠ ${wieOft} am ${datum}` +
+        (letzter.neuBerechnet !== null ? ` (${letzter.neuBerechnet} Einträge)` : '') +
+        '. Ein Rehash verknüpft alle Einträge neu – die Aussage dieser Prüfung ' +
+        'reicht deshalb nur bis dorthin zurück, nicht weiter.' +
+        uebertuencht +
+        ohneSignatur
+      );
+    })();
+
+    // Erneutes Siegeln kann legitim sein, verdient aber einen Blick: es
+    // ersetzt die zuvor beglaubigte Wurzel (Pentest R173-03).
+    const mehrfach =
+      result.backlogSealCount > 1
+        ? ` Hinweis: Der Altbestand wurde ${result.backlogSealCount}× versiegelt – der jüngste Marker gilt. ` +
+          'Jeder Marker enthält den Befund vor dem Siegeln; bei Zweifeln dort vergleichen.'
+        : '';
+
+    // Bei problematischem Siegel darf KEIN beruhigender Einstiegssatz stehen –
+    // sonst entwertet er die nachfolgende Warnung (Pentest R174-01).
+    const siegelProblem =
+      result.backlogSealStatus === 'gebrochen' || result.backlogSealStatus === 'entfernt';
+
+    // „Keine Manipulation“ darf NICHT dastehen, solange `valid` falsch ist
+    // (Pentest R183-02). Nach einem Cleanup mit abgesenkter Aufbewahrung waren
+    // tausende Anmeldeprotokolle endgueltig geloescht – die Luecken durch
+    // Tombstones „erklaert“, die Meldung las sich beruhigend, und der Befund
+    // stand nur noch im Feld `valid`. Wer die Prosa liest statt des Felds,
+    // klickt genau das weg, was ihn haette warnen sollen.
     const message = tampered > 0
-      ? `${tampered} MANIPULIERTE Einträge gefunden` +
+      ? `${tampered} MANIPULIERTE Einträge gefunden` + (offeneGaps > 0 ? ` (zusätzlich ${luecken})` : '')
-        (gaps > 0 ? ` (zusätzlich ${gaps} strukturelle Lücken)` : '')
+      : siegelProblem
-      : gaps > 0
+        ? 'Die Kette selbst ist rechnerisch stimmig, ABER:'
-        ? `Keine Manipulation. ${gaps} strukturelle Lücken in der Verkettung ` +
+        : offeneGaps > 0
-          '(parallel geschriebene oder gelöschte Einträge) – Inhalte unverändert.'
+          ? `Die Kette ist nicht mehr lückenlos: ${luecken}. Die verbliebenen Inhalte sind ` +
-        : 'Alle Einträge sind unverändert und lückenlos verkettet';
+            'unverändert – aber gelöschte Einträge lassen sich naturgemäß nicht mehr prüfen. ' +
+            'Dokumentierte Löschungen sind erwartbar; unerwartete gehören nachgegangen.'
+          : beglaubigt > 0
+            ? 'Alle Einträge sind unverändert. Seit dem Bestandssiegel ist keine neue Lücke ' +
+              'entstanden.'
+            : result.rehashes.length > 0
+              ? 'Alle Einträge sind unverändert und lückenlos verkettet – allerdings erst ' +
+                'seit der letzten Neuberechnung.'
+              : 'Alle Einträge sind unverändert und lückenlos verkettet.';
 
     res.json({
       success: true,
@@ -167,8 +361,20 @@ export async function verifyIntegrity(req: AuthRequest, res: Response) {
         tamperedEntries: result.tamperedEntries,
         // Meist harmlos: Verkettung unterbrochen, Inhalte selbst unversehrt.
         chainGaps: result.chainGaps,
+        // Nur Lücken ohne protokollierte Löschung sind erklärungsbedürftig.
+        unexplainedGaps: result.unexplainedGaps,
+        // Alt-Lücken, die das Bestandssiegel als bereits vorhanden beglaubigt.
+        attestedGaps: result.attestedGaps,
+        // Protokollierte Neuberechnungen – begrenzen die Reichweite der Aussage.
+        rehashes: result.rehashes,
         tampered: tampered > 0,
-        message,
+        message: message + beglaubigtText + rehashText + keinSchluessel + siegel + mehrfach,
+        unverifiableEntries: result.unverifiableEntries,
+        // Zustand des Bestandssiegels ueber den nicht signierbaren Altbestand.
+        backlogSealStatus: result.backlogSealStatus,
+        backlogTampered: result.backlogTampered,
+        backlogMissing: result.backlogMissing,
+        backlogSealCount: result.backlogSealCount,
       },
     });
   } catch (error) {
@@ -182,7 +388,26 @@ export async function verifyIntegrity(req: AuthRequest, res: Response) {
  */
 export async function rehashAll(req: AuthRequest, res: Response) {
   try {
-    const result = await auditService.rehashAll();
+    // Ausdrueckliche Bestaetigung verlangen (Pentest R170-01).
+    //
+    // Ein Rehash macht die Kette rechnerisch stimmig und setzt damit die
+    // Beweiskraft der Vergangenheit zurueck - das darf kein Nebeneffekt eines
+    // versehentlichen oder tastenden POST sein. Genau so wurde der Endpunkt
+    // bei einer Methoden-Erkundung unbeabsichtigt ausgeloest.
+    if (req.body?.confirm !== 'REHASH') {
+      res.status(400).json({
+        success: false,
+        error:
+          'Rehash setzt die Beweiskraft der bestehenden Einträge zurück und ist nicht ' +
+          'umkehrbar. Zum Bestätigen {"confirm":"REHASH"} mitsenden.',
+      });
+      return;
+    }
+
+    const result = await auditService.rehashAll({
+      userEmail: req.user?.email,
+      ipAddress: req.ip || (req.socket as any)?.remoteAddress,
+    });
     res.json({
       success: true,
       data: result,
@@ -194,6 +419,131 @@ export async function rehashAll(req: AuthRequest, res: Response) {
   }
 }
 
+/**
+ * Kontrollwert fuer das externe Gegenbuch (Notarisierung).
+ *
+ * Bewusst nur lesend und ohne Geheimnisse - die Gegenstelle braucht keinerlei
+ * Schreibrecht auf dieses System, und dieses System kennt den Schluessel der
+ * Gegenstelle nicht. Genau diese Trennung ist der Schutz.
+ */
+export async function getCheckpoint(req: AuthRequest, res: Response) {
+  try {
+    const roh = req.query.atId as string | undefined;
+    const atId = roh !== undefined ? parseInt(roh, 10) : undefined;
+    if (roh !== undefined && Number.isNaN(atId as number)) {
+      res.status(400).json({ success: false, error: 'atId muss eine Zahl sein' });
+      return;
+    }
+    const data = await auditService.getCheckpoint(atId);
+    res.json({ success: true, data });
+  } catch (error) {
+    console.error('Fehler beim Erstellen des Kontrollwerts:', error);
+    res.status(500).json({ success: false, error: 'Fehler beim Erstellen des Kontrollwerts' });
+  }
+}
+
+/**
+ * Altbestand versiegeln (Pentest R171-02).
+ *
+ * Einmalige, NICHT destruktive Aktion: schreibt nichts um, sondern haelt den
+ * Ist-Inhalt der nicht signierbaren Alteintraege fest.
+ */
+export async function sealBacklog(req: AuthRequest, res: Response) {
+  try {
+    // Erst nachsehen, ob schon ein Siegel steht (Pentest R185-01).
+    //
+    // Ein zweites Siegeln ist etwas grundlegend anderes als das erste: Es
+    // ERSETZT die Grundlage, gegen die Manipulation nachgewiesen wird. Wer den
+    // Altbestand per Datenbankzugriff beschneidet und danach neu siegelt,
+    // bekommt eine passende Wurzel und eine ueber den neuen Vorbefund
+    // beglaubigte Luecke - und `valid` steht wieder auf `true`. Deshalb
+    // verlangt das Ersetzen ein eigenes Wort und nicht dasselbe wie das
+    // Einrichten.
+    const vorher = await auditService.verifyIntegrity();
+    const siegelSteht =
+      vorher.backlogSealStatus === 'intakt' ||
+      vorher.backlogSealStatus === 'gebrochen' ||
+      vorher.backlogSealStatus === 'entfernt';
+
+    const erwartet = siegelSteht ? 'RESEAL' : 'SEAL';
+    if (req.body?.confirm !== erwartet) {
+      res.status(400).json({
+        success: false,
+        error: siegelSteht
+          ? 'Es besteht bereits ein Bestandssiegel. Erneutes Siegeln ERSETZT die ' +
+            'bisherige Beweisgrundlage: bestehende Lücken werden neu beglaubigt und ' +
+            'ein Befund am Altbestand verschwindet aus der Prüfung. Das ist kein ' +
+            'Wartungsschritt. Zum Bestätigen {"confirm":"RESEAL"} mitsenden – und ' +
+            'vorher klären, warum das bisherige Siegel nicht mehr passt.'
+          : 'Versiegelt den aktuellen Stand des Altbestands. Zum Bestätigen ' +
+            '{"confirm":"SEAL"} mitsenden.',
+        aktuellerSiegelzustand: vorher.backlogSealStatus,
+      });
+      return;
+    }
+
+    const result = await auditService.sealBacklog({
+      userEmail: req.user?.email,
+      ipAddress: req.ip || (req.socket as any)?.remoteAddress,
+    });
+
+    // In den ALARMKANAL, nicht nur ins Audit-Log (Pentest R185-01).
+    //
+    // Die CRITICAL-Zeile im Audit-Log gab es schon - aber die muss jemand
+    // lesen, und genau das ist die R183-02/R184-01-Klasse. Der automatische
+    // Rueckhalt des Gegenbuchs haengt an `valid`, und `valid` ueberlebt ein
+    // ersetzendes Siegel per Konstruktion. Der einzige maschinell erkennbare
+    // Anker ist der Wechsel der Wurzel - der gehoert dorthin, wo etwas von
+    // selbst passiert.
+    const ctx = contextFromRequest(req);
+    emitSecurityEvent({
+      type: 'AUDIT_SEAL_CHANGED',
+      severity: siegelSteht ? 'CRITICAL' : 'HIGH',
+      message: siegelSteht
+        ? `Bestandssiegel ERSETZT (${result.sealedCount} Alteinträge, id ${result.fromId}–` +
+          `${result.toId}). Die bisherige Beweisgrundlage gilt nicht mehr; der Zustand ` +
+          `davor war "${vorher.backlogSealStatus}". Wenn das keine geplante Maßnahme war, ` +
+          'ist es ein Befund.'
+        : `Bestandssiegel erstmals gesetzt (${result.sealedCount} Alteinträge, id ` +
+          `${result.fromId}–${result.toId}). Ab jetzt fallen Änderungen am Altbestand auf.`,
+      ipAddress: ctx.ipAddress,
+      userId: req.user?.userId,
+      userEmail: req.user?.email,
+      endpoint: ctx.endpoint,
+      details: {
+        ersetzt: siegelSteht,
+        zustandVorher: vorher.backlogSealStatus,
+        wurzelVorher: vorher.backlogSealRoot,
+        wurzelNachher: result.root,
+        befundVorher: {
+          manipuliert: vorher.tamperedEntries,
+          luecken: vorher.chainGaps,
+          altbestandVeraendert: vorher.backlogTampered,
+          altbestandFehlend: vorher.backlogMissing,
+        },
+      },
+    });
+
+    res.json({
+      success: true,
+      data: result,
+      message:
+        `${result.sealedCount} Alteinträge (id ${result.fromId}–${result.toId}) versiegelt. ` +
+        'Spätere Änderungen an diesen Einträgen fallen ab sofort auf.' +
+        (siegelSteht
+          ? ' ACHTUNG: Dies war ein ERSETZENDES Siegel – die vorherige Beweisgrundlage ' +
+            'gilt nicht mehr.'
+          : ''),
+    });
+  } catch (error) {
+    console.error('Fehler beim Versiegeln des Altbestands:', error);
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Fehler beim Versiegeln',
+    });
+  }
+}
+
 /**
  * Retention-Policies abrufen
  */
@@ -218,6 +568,48 @@ export async function updateRetentionPolicy(req: AuthRequest, res: Response) {
     }
     const { retentionDays, description, legalBasis, isActive } = req.body;
 
+    // Die Richtlinie bestimmt, WAS der Cleanup vernichtet – sie ist die
+    // geladene Waffe, der Cleanup nur der Abzug (Pentest R183-01). Bisher war
+    // ausgerechnet der Abzug gegatet und die Waffe frei zugaenglich: Ein
+    // `retentionDays: 0` ging ohne Bestaetigung durch und wurde nur als MEDIUM
+    // protokolliert, waehrend seine Wirkung CRITICAL ist. Die ausloesende Tat
+    // war damit leiser als die Folge – und lag unter der Schwelle, bei der
+    // jemand hinsieht.
+    const bisher = (await auditService.getRetentionPolicies()).find((p) => p.id === id);
+    if (!bisher) {
+      return res.status(404).json({ success: false, error: 'Aufbewahrungsrichtlinie nicht gefunden' });
+    }
+
+    const neueTage = typeof retentionDays === 'number' ? retentionDays : bisher.retentionDays;
+
+    // Untergrenze: Auth-Eintraege sind der Einbruchsbeleg schlechthin. Eine
+    // Aufbewahrung von faktisch null macht sie mit dem naechsten Cleanup
+    // spurlos entfernbar – ueber einen sanktionierten Pfad.
+    const UNTERGRENZE: Record<string, number> = { Authentication: 30, AuditLog: 30 };
+    const grenze = UNTERGRENZE[bisher.resourceType];
+    if (grenze !== undefined && neueTage < grenze) {
+      return res.status(400).json({
+        success: false,
+        error:
+          `Für ${bisher.resourceType} sind mindestens ${grenze} Tage Aufbewahrung vorgeschrieben ` +
+          `(angefragt: ${neueTage}). Diese Einträge belegen Anmeldungen und Zugriffe – eine ` +
+          `Aufbewahrung nahe null macht sie beim nächsten Cleanup spurlos entfernbar.`,
+      });
+    }
+
+    // Absenken ist die gefaehrliche Richtung und braucht dieselbe ausdrueckliche
+    // Bestaetigung wie der Cleanup selbst.
+    const senktAb = neueTage < bisher.retentionDays;
+    if (senktAb && req.body?.confirm !== 'SHORTEN') {
+      return res.status(400).json({
+        success: false,
+        error:
+          `Das verkürzt die Aufbewahrung von ${bisher.retentionDays} auf ${neueTage} Tage. ` +
+          'Beim nächsten Cleanup werden dadurch Einträge endgültig gelöscht, die heute noch ' +
+          'da sind. Zum Bestätigen {"confirm":"SHORTEN"} mitsenden.',
+      });
+    }
+
     const policy = await auditService.updateRetentionPolicy(id, {
       retentionDays,
       description,
@@ -228,7 +620,15 @@ export async function updateRetentionPolicy(req: AuthRequest, res: Response) {
     await logChange({
       req, action: 'UPDATE', resourceType: 'RetentionPolicy',
       resourceId: id.toString(),
-      label: `Aufbewahrungsrichtlinie aktualisiert`,
+      // Absenkung wird wie ihre Folge eingestuft: CRITICAL, nicht MEDIUM.
+      sensitivity: senktAb ? 'CRITICAL' : undefined,
+      label: senktAb
+        ? `Aufbewahrung VERKÜRZT für ${bisher.resourceType}` +
+          (bisher.sensitivity ? `/${bisher.sensitivity}` : '') +
+          `: ${bisher.retentionDays} → ${neueTage} Tage`
+        : `Aufbewahrungsrichtlinie aktualisiert`,
+      before: { retentionDays: bisher.retentionDays },
+      details: { retentionDays: neueTage },
     });
 
     res.json({ success: true, data: policy });
@@ -243,6 +643,18 @@ export async function updateRetentionPolicy(req: AuthRequest, res: Response) {
  */
 export async function runRetentionCleanup(req: AuthRequest, res: Response) {
   try {
+    // Auch hier ausdrueckliche Bestaetigung: Cleanup loescht Audit-Zeilen
+    // endgueltig und reisst dabei die Kette auf (Pentest R170-01).
+    if (req.body?.confirm !== 'CLEANUP') {
+      res.status(400).json({
+        success: false,
+        error:
+          'Cleanup löscht Audit-Einträge endgültig. Zum Bestätigen ' +
+          '{"confirm":"CLEANUP"} mitsenden.',
+      });
+      return;
+    }
+
     const result = await auditService.runRetentionCleanup();
 
     res.json({

backend/src/controllers/auth.controller.ts

@@ -309,11 +309,16 @@ export async function logout(req: AuthRequest, res: Response): Promise<void> {
         where: { id: user.customerId },
         data: { portalTokenInvalidatedAt: new Date() },
       });
+      // Ausgegebene Refresh-Tokens zusätzlich hart widerrufen (R164-02):
+      // der Zeitstempel-Vergleich allein greift erst beim nächsten Refresh,
+      // der Widerruf macht die Tokens sofort unbrauchbar.
+      await authService.revokeAllRefreshTokens({ customerId: user.customerId }, 'Logout');
     } else if (user.userId) {
       await prisma.user.update({
         where: { id: user.userId },
         data: { tokenInvalidatedAt: new Date() },
       });
+      await authService.revokeAllRefreshTokens({ userId: user.userId }, 'Logout');
     }
     // Refresh-Cookie löschen, sonst könnte der Browser einen abgemeldeten User
     // direkt wieder einloggen (server-seitige Invalidation oben fängt das ab,
@@ -370,14 +375,31 @@ export async function refresh(req: Request, res: Response): Promise<void> {
     const ctx = contextFromRequest(req);
     const code = (error as { code?: string })?.code;
     const msg = error instanceof Error ? error.message : 'Refresh fehlgeschlagen';
-    const benign = code === 'REFRESH_EXPIRED' || /invalidiert/i.test(msg);
+
-    emitSecurityEvent({
+    if (code === 'REFRESH_REPLAY') {
-      type: 'TOKEN_REJECTED',
+      // Ein bereits eingelöster Refresh-Token wurde erneut vorgelegt. Das ist
-      severity: benign ? 'LOW' : 'HIGH',
+      // kein Betriebsfehler, sondern der Abdruck eines gestohlenen Tokens –
-      message: `Refresh-Token abgelehnt: ${msg}`,
+      // die Sitzungsfamilie ist bereits widerrufen (R164-02).
-      ipAddress: ctx.ipAddress,
+      emitSecurityEvent({
-      endpoint: ctx.endpoint,
+        type: 'SUSPICIOUS',
-    });
+        severity: 'CRITICAL',
+        message: 'Refresh-Token-Replay erkannt – Sitzungsfamilie widerrufen',
+        ipAddress: ctx.ipAddress,
+        endpoint: ctx.endpoint,
+      });
+    } else {
+      // REFRESH_LEGACY = Token aus der Zeit vor dem Replay-Schutz; das ist eine
+      // einmalige Neuanmeldung nach dem Deploy, kein Angriffsindiz.
+      const benign = code === 'REFRESH_EXPIRED' || code === 'REFRESH_LEGACY'
+        || code === 'REFRESH_REVOKED' || /invalidiert/i.test(msg);
+      emitSecurityEvent({
+        type: 'TOKEN_REJECTED',
+        severity: benign ? 'LOW' : 'HIGH',
+        message: `Refresh-Token abgelehnt: ${msg}`,
+        ipAddress: ctx.ipAddress,
+        endpoint: ctx.endpoint,
+      });
+    }
     res.status(401).json({
       success: false,
       error: msg,

backend/src/controllers/user.controller.ts

@@ -3,7 +3,9 @@ import bcrypt from 'bcryptjs';
 import prisma from '../lib/prisma.js';
 import * as userService from '../services/user.service.js';
 import { logChange } from '../services/audit.service.js';
+import { AUDIT_OPS_ROLLE } from '../services/user.service.js';
 import { ApiResponse, AuthRequest } from '../types/index.js';
+import { emit as emitSecurityEvent, contextFromRequest } from '../services/securityMonitor.service.js';
 import { pickUserCreate, pickUserUpdate, isValidEmail, sanitizePhoneField } from '../utils/sanitize.js';
 import { validatePasswordComplexity, STAFF_MIN_PASSWORD_LENGTH } from '../utils/passwordGenerator.js';
 
@@ -99,7 +101,7 @@ export async function createUser(req: Request, res: Response): Promise<void> {
   }
 }
 
-export async function updateUser(req: Request, res: Response): Promise<void> {
+export async function updateUser(req: AuthRequest, res: Response): Promise<void> {
   try {
     const userId = parseInt(req.params.id);
     // `permissions` und `password` darf der generische Update nicht
@@ -161,9 +163,89 @@ export async function updateUser(req: Request, res: Response): Promise<void> {
           ...beforeUser,
           hasGdprAccess: beforeUser.roles.some((ur) => ur.role.name === 'DSGVO'),
           hasDeveloperAccess: beforeUser.roles.some((ur) => ur.role.name === 'Developer'),
+          hasAuditOpsAccess: beforeUser.roles.some((ur) => ur.role.name === AUDIT_OPS_ROLLE),
         }
       : null;
 
+    // Der Audit-Betrieb-Haken vergibt die EINGREIFENDEN Rechte am Protokoll
+    // (versiegeln, neu berechnen, aufraeumen, Aufbewahrung). Ihn zu setzen ist
+    // kein gewoehnliches Benutzer-Update: Er entscheidet, wer die
+    // Beweisgrundlage ersetzen darf.
+    //
+    // Eine eigene Rechte-Huerde davorzusetzen scheitert am Henne-Ei-Problem -
+    // nach der Aufteilung haelt zunaechst niemand `audit:admin`, und dann
+    // koennte ihn auch niemand vergeben. Stattdessen wird die Vergabe LAUT:
+    // CRITICAL im Protokoll und zusaetzlich in den Alarmkanal, so wie beim
+    // Dienstkonto-Kennzeichen (R184-01).
+    const setztAuditBetrieb =
+      data.hasAuditOpsAccess !== undefined &&
+      before !== null &&
+      data.hasAuditOpsAccess !== (before as any).hasAuditOpsAccess;
+    const aktiviertAuditBetrieb = data.hasAuditOpsAccess === true;
+
+    // Das Dienstkonto-Kennzeichen SENKT die Alarmstufe der Anmeldungen dieses
+    // Kontos (Pentest R184). Damit ist es selbst ein Hebel zur Waesche: Wer sein
+    // Konto so markiert, laesst die eigenen auffaelligen Anmeldungen als
+    // Routine erscheinen. Es bekommt deshalb dieselbe Behandlung wie das
+    // Absenken einer Aufbewahrungsfrist – Bestaetigung, laute Protokollierung,
+    // und kein Selbstbedienen.
+    const setztDienstkonto =
+      typeof (data as any).isServiceAccount === 'boolean' &&
+      (data as any).isServiceAccount !== before?.isServiceAccount;
+    const aktiviertDienstkonto = setztDienstkonto && (data as any).isServiceAccount === true;
+
+    // R184-02: Das Kennzeichen ist ein Audit-Governance-Eingriff, kein
+    // gewoehnliches Benutzerfeld – es ist Geschwister von retention-shorten,
+    // seal-backlog, rehash und cleanup, die alle `audit:admin` verlangen. Es
+    // haengt aber an der Route mit `users:update`. Heute deckungsgleich, weil
+    // nur die Administratorrolle beides hat – aber jede kuenftige Rolle mit
+    // „Benutzer bearbeiten“ wuerde still „Login-Alarme herunterstufen“ erben.
+    // Deshalb hier zusaetzlich auf die Domaene pruefen, in der der Schaden
+    // liegt.
+    if (setztDienstkonto && !(req.user?.permissions || []).includes('audit:admin')) {
+      res.status(403).json({
+        success: false,
+        error:
+          'Das Dienstkonto-Kennzeichen ändert, wie Anmeldungen im Audit-Log bewertet werden. ' +
+          'Dafür genügt „Benutzer bearbeiten“ nicht – es erfordert die Berechtigung ' +
+          'audit:admin, wie das Verkürzen von Aufbewahrungsfristen auch.',
+      } as ApiResponse);
+      return;
+    }
+
+    if (setztDienstkonto && req.user?.userId === userId) {
+      res.status(403).json({
+        success: false,
+        error:
+          'Das Dienstkonto-Kennzeichen lässt sich nicht am eigenen Konto setzen oder entfernen. ' +
+          'Es stuft Anmeldungen dieses Kontos als Routine ein – wer das für sich selbst täte, ' +
+          'könnte die eigenen Anmeldungen unauffällig machen. Bitte von einem anderen ' +
+          'Administrator vornehmen lassen.',
+      } as ApiResponse);
+      return;
+    }
+
+    // Gate in BEIDE Richtungen (Pentest R184-01). Das Entfernen war ungegatet –
+    // und es ist der gefaehrlichere Weg: Ein un-geflaggtes Konto faellt aus der
+    // Heartbeat-Wache, weil diese am Live-Kennzeichen haengt. Genau das
+    // „stilllegen und auf Stille setzen“, gegen das der Wachhund gebaut wurde.
+    if (setztDienstkonto && req.body?.confirm !== 'SERVICE_ACCOUNT') {
+      res.status(400).json({
+        success: false,
+        error: aktiviertDienstkonto
+          ? `Damit werden künftige Anmeldungen von ${before?.email ?? 'diesem Konto'} im ` +
+            'Audit-Log als Routine geführt statt als kritisches Ereignis. Das ist für ' +
+            'planmäßig arbeitende Dienste gedacht (etwa das Gegenbuch) – für ein Konto, das ' +
+            'ein Mensch benutzt, wäre es eine Tarnung. ' +
+            'Zum Bestätigen {"confirm":"SERVICE_ACCOUNT"} mitsenden.'
+          : `Damit fällt ${before?.email ?? 'dieses Konto'} aus der Überwachung heraus: Es wird ` +
+            'dann nicht mehr gemeldet, wenn es sich nicht mehr anmeldet. Bei einem laufenden ' +
+            'Dienst wie dem Gegenbuch hieße das, sein Ausfall bliebe unbemerkt. ' +
+            'Zum Bestätigen {"confirm":"SERVICE_ACCOUNT"} mitsenden.',
+      } as ApiResponse);
+      return;
+    }
+
     const user = await userService.updateUser(userId, data as any);
     if (user) {
       // Audit: Geänderte Felder ermitteln und loggen
@@ -172,6 +254,8 @@ export async function updateUser(req: Request, res: Response): Promise<void> {
         const fieldLabels: Record<string, string> = {
           email: 'E-Mail', firstName: 'Vorname', lastName: 'Nachname', isActive: 'Aktiv',
           hasGdprAccess: 'DSGVO-Zugriff', hasDeveloperAccess: 'Entwicklerzugriff',
+          hasAuditOpsAccess: 'Audit-Betrieb (versiegeln, aufräumen, Aufbewahrung)',
+          isServiceAccount: 'Dienstkonto (Anmeldungen als Routine)',
         };
         for (const [key, newVal] of Object.entries(data)) {
           if (['id', 'createdAt', 'updatedAt'].includes(key)) continue;
@@ -191,9 +275,63 @@ export async function updateUser(req: Request, res: Response): Promise<void> {
         await logChange({
           req, action: 'UPDATE', resourceType: 'User',
           resourceId: user.id.toString(),
-          label: changeList ? `Benutzer ${user.firstName} ${user.lastName} aktualisiert: ${changeList}` : `Benutzer ${user.firstName} ${user.lastName} aktualisiert`,
+          label: setztDienstkonto
+            ? `Dienstkonto-Kennzeichen ${aktiviertDienstkonto ? 'GESETZT' : 'entfernt'} für ` +
+              `${user.email} – Anmeldungen werden künftig ` +
+              `${aktiviertDienstkonto ? 'als Routine' : 'wieder als kritisch'} geführt`
+            : changeList
+              ? `Benutzer ${user.firstName} ${user.lastName} aktualisiert: ${changeList}`
+              : `Benutzer ${user.firstName} ${user.lastName} aktualisiert`,
+          // Die Aenderung dieses Kennzeichens wird wie ihre Wirkung eingestuft:
+          // Sie beeinflusst, wie kuenftige Anmeldungen bewertet werden.
+          sensitivity: setztDienstkonto || setztAuditBetrieb ? 'CRITICAL' : undefined,
           details: Object.keys(changes).length > 0 ? changes : undefined,
         });
+
+        // Zusaetzlich in den Alarmkanal (Pentest R184-01). Eine CRITICAL-Zeile
+        // im Audit-Log muss jemand LESEN – das ist die R183-02-Klasse. Das
+        // Entfernen des Kennzeichens nimmt das Konto aus der Heartbeat-Wache;
+        // ab dann faellt sein Ausbleiben nicht mehr auf. Diese Aenderung
+        // gehoert deshalb dorthin, wo automatisch reagiert wird.
+        if (setztDienstkonto) {
+          const ctx = contextFromRequest(req);
+          emitSecurityEvent({
+            type: 'PERMISSION_CHANGED',
+            severity: 'CRITICAL',
+            message: aktiviertDienstkonto
+              ? `Konto ${user.email} als Dienstkonto markiert – seine Anmeldungen gelten ab ` +
+                'jetzt als Routine statt als kritisches Ereignis.'
+              : `Konto ${user.email} ist KEIN Dienstkonto mehr – es fällt damit aus der ` +
+                'Überwachung heraus: Ein Ausbleiben seiner Anmeldungen wird nicht mehr gemeldet.',
+            ipAddress: ctx.ipAddress,
+            userId: req.user?.userId,
+            userEmail: req.user?.email,
+            endpoint: ctx.endpoint,
+            details: { betroffenesKonto: user.email, aktiviert: aktiviertDienstkonto },
+          });
+        }
+
+        if (setztAuditBetrieb) {
+          const ctx = contextFromRequest(req);
+          emitSecurityEvent({
+            type: 'PERMISSION_CHANGED',
+            severity: 'CRITICAL',
+            message: aktiviertAuditBetrieb
+              ? `Konto ${user.email} darf ab jetzt am Audit-Protokoll EINGREIFEN: versiegeln, ` +
+                'neu berechnen, aufräumen, Aufbewahrung ändern. Damit kann es die Grundlage ' +
+                'ersetzen, gegen die Manipulation nachgewiesen wird.'
+              : `Konto ${user.email} darf nicht mehr am Audit-Protokoll eingreifen.`,
+            ipAddress: ctx.ipAddress,
+            userId: req.user?.userId,
+            userEmail: req.user?.email,
+            endpoint: ctx.endpoint,
+            details: {
+              betroffenesKonto: user.email,
+              aktiviert: aktiviertAuditBetrieb,
+              selbstvergabe: user.id === req.user?.userId,
+            },
+          });
+        }
       } else {
         await logChange({
           req, action: 'UPDATE', resourceType: 'User',

backend/src/index.ts

@@ -1,4 +1,4 @@
-import express from 'express';
+import express, { Router } from 'express';
 import cookieParser from 'cookie-parser';
 import cors from 'cors';
 import helmet from 'helmet';
@@ -69,8 +69,11 @@ import { startContractStatusScheduler } from './services/contractStatusScheduler
 import { startBlzUpdateScheduler } from './services/blzUpdateScheduler.service.js';
 import { startSecurityMonitorScheduler } from './services/securityAlert.service.js';
 import monitoringRoutes from './routes/monitoring.routes.js';
+import { registriereIdPruefung } from './middleware/routeIds.js';
 import { auditContextMiddleware } from './middleware/auditContext.js';
 import { auditMiddleware } from './middleware/audit.js';
+import { starteHeartbeatMonitor } from './services/heartbeatMonitor.service.js';
+import { pruefePflichtrechte } from './services/pflichtrechte.service.js';
 import { authenticate } from './middleware/auth.js';
 
 // ==================== SECURITY: Pflicht-Umgebungsvariablen prüfen ====================
@@ -325,69 +328,76 @@ app.use('/api', (_req, res, next) => {
   next();
 });
 
-// Numerische ID-Parameter strikt validieren. parseInt('6abc') liefert 6, was
+// HIER STAND eine Pfad-Heuristik gegen abgeschnittene IDs (Pentest Runde 7,
-// dazu führt, dass `/api/customers/6abc` als `/api/customers/6` interpretiert
+// 2026-05-17): Sie blockte Segmente der Form `^\d+[a-zA-Z]+$` – also `6abc`,
-// wurde – kein Auth-Bypass (Prisma fängt SQL-Injection), aber fehlende Input-
+// weil `parseInt('6abc')` die 6 ergibt und `/api/customers/6abc` still als
-// Validierung. Pentest Runde 7 (2026-05-17), LOW.
+// Kunde 6 gelesen wurde. Ihr eigener Kommentar nannte den Grund fuer die
+// Heuristik: „`app.param()` greift nicht auf in Sub-Router gemounteten Routes".
 //
-// `app.param()` greift nicht auf in Sub-Router gemounteten Routes, deshalb
+// Genau das loest `mounte()` weiter unten – die Pruefung wird an jedem Router
-// machen wir es als Pfad-Heuristik. Geblockt wird NUR `^\d+[a-zA-Z]+$` –
+// registriert, nicht am App-Objekt. Damit ist die Heuristik abgeloest, und
-// reine Ziffern gefolgt von reinen Buchstaben (`6abc`, `12foo`). UUIDs wie
+// zwar in beide Richtungen:
-// `3018c9b9-b337-4c9a-a402-b47872f8ddae` (Consent-Hash) und Datumsstrings
+//
-// `2024-05-17` haben Bindestriche / gemischten Aufbau und werden korrekt
+//   – Sie war zu eng: `/api/users/abc` ging durch (keine Ziffer vorn) und
-// nicht geblockt.
+//     endete als 500. Die Parameter-Pruefung kennt dagegen die tatsaechlichen
-const TRUNCATED_ID_PATTERN = /^\d+[a-zA-Z]+$/;
+//     ID-Parameter und laesst nur kanonische Zahlen zu.
-app.use('/api', (req, res, next) => {
+//   – Sie war zu weit: Ein Einstellungs-Schluessel `12abc` unter
-  for (const seg of req.path.split('/')) {
+//     `/api/settings/:key` wurde geblockt, obwohl `:key` gar keine ID ist.
-    if (seg.length > 0 && TRUNCATED_ID_PATTERN.test(seg)) {
+//
-      res.status(400).json({ success: false, error: 'Ungültige ID im URL-Pfad' });
+// Und sie antwortete 400, wo die Parameter-Pruefung 404 gibt – zwei Antworten
-      return;
+// fuer dieselbe Eingabeklasse. Siehe middleware/routeIds.ts.
-    }
-  }
-  next();
-});
 
 // Globaler Backstop-Rate-Limiter für ALLE /api-Requests (Pentest R148).
 // Großzügige Obergrenze pro IP – ergänzt die feineren Limiter (Login etc.),
 // die als erste greifen. Siehe middleware/rateLimit.ts für die Begründung.
 app.use('/api', apiBackstopRateLimiter);
 
+// Router einhängen – IMMER über `mounte`, nie über `app.use` direkt.
+//
+// `mounte` haengt die zentrale Pruefung numerischer Pfad-Parameter an (R188)
+// und montiert danach. Wer hier kuenftig `app.use` schreibt, umgeht sie
+// stillschweigend – deshalb steht die Pruefung im selben Handgriff wie das
+// Einhaengen und nicht in einer zweiten Liste, die man vergessen kann.
+const mounte = (pfad: string, router: Router): void => {
+  app.use(pfad, registriereIdPruefung(router));
+};
+
 // Öffentliche Routes (OHNE Authentifizierung)
-app.use('/api/public/consent', consentPublicRoutes);
+mounte('/api/public/consent', consentPublicRoutes);
 
 // Routes
-app.use('/api/auth', authRoutes);
+mounte('/api/auth', authRoutes);
-app.use('/api/customers', customerRoutes);
+mounte('/api/customers', customerRoutes);
-app.use('/api/addresses', addressRoutes);
+mounte('/api/addresses', addressRoutes);
-app.use('/api/bank-cards', bankcardRoutes);
+mounte('/api/bank-cards', bankcardRoutes);
-app.use('/api/documents', documentRoutes);
+mounte('/api/documents', documentRoutes);
-app.use('/api/meters', meterRoutes);
+mounte('/api/meters', meterRoutes);
-app.use('/api/stressfrei-emails', stressfreiEmailRoutes);
+mounte('/api/stressfrei-emails', stressfreiEmailRoutes);
-app.use('/api/contracts', contractRoutes);
+mounte('/api/contracts', contractRoutes);
-app.use('/api/credit-notes', creditNoteRoutes);
+mounte('/api/credit-notes', creditNoteRoutes);
-app.use('/api/company-profile', companyProfileRoutes);
+mounte('/api/company-profile', companyProfileRoutes);
-app.use('/api/platforms', platformRoutes);
+mounte('/api/platforms', platformRoutes);
-app.use('/api/cancellation-periods', cancellationPeriodRoutes);
+mounte('/api/cancellation-periods', cancellationPeriodRoutes);
-app.use('/api/contract-durations', contractDurationRoutes);
+mounte('/api/contract-durations', contractDurationRoutes);
-app.use('/api/providers', providerRoutes);
+mounte('/api/providers', providerRoutes);
-app.use('/api/tariffs', tariffRoutes);
+mounte('/api/tariffs', tariffRoutes);
-app.use('/api/users', userRoutes);
+mounte('/api/users', userRoutes);
-app.use('/api/upload', uploadRoutes);
+mounte('/api/upload', uploadRoutes);
-app.use('/api/developer', developerRoutes);
+mounte('/api/developer', developerRoutes);
-app.use('/api/contract-categories', contractCategoryRoutes);
+mounte('/api/contract-categories', contractCategoryRoutes);
-app.use('/api', contractTaskRoutes);
+mounte('/api', contractTaskRoutes);
-app.use('/api/settings', appSettingRoutes);
+mounte('/api/settings', appSettingRoutes);
-app.use('/api/email-providers', emailProviderRoutes);
+mounte('/api/email-providers', emailProviderRoutes);
-app.use('/api', cachedEmailRoutes);
+mounte('/api', cachedEmailRoutes);
-app.use('/api/energy-details', invoiceRoutes);
+mounte('/api/energy-details', invoiceRoutes);
-app.use('/api', contractHistoryRoutes);
+mounte('/api', contractHistoryRoutes);
-app.use('/api/audit-logs', auditLogRoutes);
+mounte('/api/audit-logs', auditLogRoutes);
-app.use('/api/gdpr', gdprRoutes);
+mounte('/api/gdpr', gdprRoutes);
-app.use('/api/email-logs', emailLogRoutes);
+mounte('/api/email-logs', emailLogRoutes);
-app.use('/api/pdf-templates', pdfTemplateRoutes);
+mounte('/api/pdf-templates', pdfTemplateRoutes);
-app.use('/api/birthdays', birthdayRoutes);
+mounte('/api/birthdays', birthdayRoutes);
-app.use('/api/factory-defaults', factoryDefaultsRoutes);
+mounte('/api/factory-defaults', factoryDefaultsRoutes);
-app.use('/api/monitoring', monitoringRoutes);
+mounte('/api/monitoring', monitoringRoutes);
 
 // Health check – BEWUSST ohne Auth (Container-Healthcheck und Reverse-Proxy
 // pingen das ohne Bearer-Token). Antwort enthält absichtlich nur statisch
@@ -487,6 +497,12 @@ app.use((err: any, req: express.Request, res: express.Response, _next: express.N
 const LISTEN_ADDR = process.env.LISTEN_ADDR
   || (process.env.NODE_ENV === 'production' ? '127.0.0.1' : '0.0.0.0');
 
+// Wachhund auf ausbleibende Dienstkonto-Anmeldungen (Pentest R182/R183):
+// Ein stillgelegtes Gegenbuch soll auffallen, nicht als Ruhe durchgehen.
+starteHeartbeatMonitor();
+// Erkennt die ABWESENHEIT der DSGVO-/Audit-Faehigkeit (R189-01).
+void pruefePflichtrechte();
+
 app.listen(PORT as number, LISTEN_ADDR, () => {
   console.log(`Server läuft auf ${LISTEN_ADDR}:${PORT}`);
   // Hintergrund-Scheduler (Geburtstagsgrüße etc.) starten

backend/src/middleware/audit.ts

@@ -167,6 +167,37 @@ const ACTION_LABELS: Record<string, string> = {
   TOKEN_REFRESH: 'Sitzung verlängert',
 };
 
+/**
+ * Ist das die planmaessige Anmeldung eines Dienstkontos? (Pentest R182)
+ *
+ * Vorhersagbare Ereignisse sind miserable Alarme und exzellente Grundlinien.
+ * Das Gegenbuch meldet sich stuendlich an – als CRITICAL gefuehrt trainiert
+ * genau diese Routine den Betreiber darauf, die hoechste Stufe wegzuklicken,
+ * und der erste ECHTE Vorfall erbt den Reflex. Der Eintrag bleibt (man soll
+ * sehen, dass das Gegenbuch arbeitet), aber als Routine.
+ */
+function istDienstkontoAnmeldung(responseBody: unknown, success: boolean): boolean {
+  if (!success || !responseBody || typeof responseBody !== 'object') return false;
+  const data = (responseBody as { data?: { user?: { isServiceAccount?: boolean } } }).data;
+  return data?.user?.isServiceAccount === true;
+}
+
+/**
+ * Unterscheidet die drei Ausgaenge von POST /auth/refresh (Pentest R166-03).
+ *
+ * "Kein Cookie vorhanden" ist KEIN Ablehnungsfall: Der Frontend-Interceptor
+ * ruft /refresh beim App-Start auch dann, wenn nie ein Token gesetzt war
+ * (normaler Erstbesuch). Das als HIGH/"abgelehnt" zu fuehren erzeugt genau das
+ * Rauschen, das mit der Entrauschung beseitigt werden sollte.
+ */
+function refreshOutcome(responseBody: unknown, success: boolean): 'ok' | 'no-token' | 'rejected' {
+  if (success) return 'ok';
+  const err = responseBody && typeof responseBody === 'object' && 'error' in responseBody
+    ? String((responseBody as { error?: unknown }).error ?? '')
+    : '';
+  return /kein refresh-token/i.test(err) ? 'no-token' : 'rejected';
+}
+
 /**
  * Erzeugt ein menschenlesbares Label für den Audit-Log-Eintrag
  */
@@ -203,14 +234,21 @@ function generateHumanLabel(
   // Auth
   if (path.includes('/auth/login') || path.includes('/auth/customer-login')) {
     const email = req.body?.email || '';
+    if (action === 'LOGIN' && istDienstkontoAnmeldung(responseBody, true)) {
+      return `Dienstkonto ${email} angemeldet (planmäßig)`;
+    }
     return action === 'LOGIN'
       ? `Benutzer ${email} hat sich angemeldet`
       : `Anmeldung fehlgeschlagen für ${email}`;
   }
   if (path.includes('/auth/logout')) return 'Benutzer hat sich abgemeldet';
   if (path.includes('/auth/refresh')) {
-    const failed = responseBody && typeof responseBody === 'object' && (responseBody as { success?: boolean }).success === false;
+    const success = !(responseBody && typeof responseBody === 'object' && (responseBody as { success?: boolean }).success === false);
-    return failed ? 'Token-Refresh abgelehnt (ungültig/abgelaufen)' : 'Sitzung verlängert (Token erneuert)';
+    switch (refreshOutcome(responseBody, success)) {
+      case 'ok': return 'Sitzung verlängert (Token erneuert)';
+      case 'no-token': return 'Token-Refresh ohne vorliegenden Token (kein Cookie)';
+      default: return 'Token-Refresh abgelehnt (ungültig/abgelaufen)';
+    }
   }
 
   // Kunden-Operationen
@@ -460,10 +498,15 @@ export function auditMiddleware(req: AuthRequest, res: Response, next: NextFunct
           isCustomerPortal: req.user?.isCustomerPortal,
           action,
           // Erfolgreicher Token-Refresh ist Routine → LOW statt CRITICAL (sonst Log-Flut).
-          // Fehlgeschlagener Refresh (Replay/Brute-Force-Verdacht) → HIGH, damit er in
+          // Abgelehnter Refresh (Replay/Brute-Force-Verdacht) → HIGH, damit er in der
-          // der Triage nicht neben legitimen Refreshes untergeht (Pentest R164-01).
+          // Triage nicht neben legitimen Refreshes untergeht (Pentest R164-01).
+          // "Kein Cookie vorhanden" ist dagegen der normale Erstbesuch → LOW (R166-03).
           // Andere Auth-Events behalten ihre Default-Sensitivität (Authentication → CRITICAL).
-          sensitivity: action === 'TOKEN_REFRESH' ? (responseSuccess ? 'LOW' : 'HIGH') : undefined,
+          sensitivity: action === 'TOKEN_REFRESH'
+            ? (refreshOutcome(responseBody, responseSuccess) === 'rejected' ? 'HIGH' : 'LOW')
+            : action === 'LOGIN' && istDienstkontoAnmeldung(responseBody, responseSuccess)
+              ? 'LOW'
+              : undefined,
           resourceType: mapping.type,
           resourceId,
           resourceLabel,

backend/src/middleware/routeIds.ts

@@ -0,0 +1,106 @@
+import { Request, Response, NextFunction, Router, RequestParamHandler } from 'express';
+import { ApiResponse } from '../types/index.js';
+
+/**
+ * Numerische Pfad-Parameter zentral pruefen (Pentest R188).
+ *
+ * Ausgangslage: In den Controllern stand 181-mal `parseInt(req.params.<x>)`
+ * ohne Pruefung. Das hatte zwei Folgen, und die zweite ist die unangenehmere:
+ *
+ *   1. Ein nicht-numerisches Segment ergab `NaN`, Prisma lief auf und der
+ *      Handler antwortete mit **500**. `GET /api/users/permissions` etwa
+ *      trifft `/:id` und war damit ein Serverfehler statt „gibt es nicht".
+ *
+ *   2. `parseInt` liest so weit, wie es kann: `parseInt('12abc')` ist **12**.
+ *      `GET /api/users/12abc` lieferte also Benutzer 12 aus. Eine schlampig
+ *      geratene ID wurde stillschweigend zu einer gueltigen gemacht.
+ *
+ * Die naheliegende Antwort waere gewesen, an allen 181 Stellen einen Guard
+ * einzusetzen. Genau daran haben wir uns in dieser Reihe mehrfach die Finger
+ * verbrannt: Was an vielen Stellen gepflegt werden muss, laeuft auseinander
+ * (zuletzt R186-01, drei Filterlisten, die dasselbe bedeuten sollten). Deshalb
+ * eine Stelle statt 181 – und eine neue Route ist automatisch mit abgedeckt.
+ *
+ * Umgesetzt ueber `router.param()`: Express ruft den Callback, bevor der
+ * Handler laeuft, und nur fuer Routen, die den Parameter wirklich benutzen.
+ *
+ * **Antwort ist 404, nicht 400.** Ein Pfad-Segment, das keine ID sein kann,
+ * benennt keine Ressource – das ist „nicht gefunden", nicht „falsch gefragt".
+ * Der Codebestand hat es an der einzigen bereits abgesicherten Stelle
+ * (`provider.controller.ts`, Pentest Mai 2026) genauso entschieden. Nebenbei
+ * verraet eine einheitliche 404 einem Probierenden nicht, ob ein Endpunkt
+ * existiert und eine Zahl erwartet oder ob es den Pfad gar nicht gibt.
+ */
+
+/**
+ * Parameternamen, die eine Datenbank-ID bezeichnen – abgeglichen mit allen
+ * Routendateien. Bewusst NICHT dabei und deshalb unberuehrt: `consentType`,
+ * `filename`, `hash`, `key`, `localPart`, `name`, `tableName`.
+ *
+ * Die Namensregel „heisst `id` oder endet auf `Id`" gilt im gesamten Bestand;
+ * eine neue Route mit `:fooId` gehoert hier ergaenzt.
+ */
+const ID_PARAMETER = [
+  'id',
+  'contractId',
+  'contractMeterId',
+  'customerId',
+  'documentId',
+  'ecdId',
+  'emailId',
+  'entryId',
+  'invoiceId',
+  'meterId',
+  'phoneNumberId',
+  'providerId',
+  'readingId',
+  'referralId',
+  'representativeId',
+  'simCardId',
+  'subtaskId',
+  'taskId',
+] as const;
+
+/** Obergrenze von MySQL INT – darueber gibt es keine Zeile, nur einen Fehler. */
+const MAX_ID = 2147483647;
+
+/**
+ * Gueltig ist ausschliesslich eine kanonische positive Ganzzahl.
+ *
+ * Fuehrende Nullen werden abgelehnt: `007` und `7` wuerden dieselbe Zeile
+ * bezeichnen, und zwei Schreibweisen fuer dieselbe Ressource sind eine
+ * unnoetige Einladung – etwa fuer Zaehler, Zwischenspeicher oder Sperren, die
+ * auf dem Pfad als Schluessel arbeiten.
+ */
+export function istGueltigeId(wert: string): boolean {
+  if (!/^[1-9][0-9]*$/.test(wert)) return false;
+  const n = Number(wert);
+  return Number.isSafeInteger(n) && n <= MAX_ID;
+}
+
+const pruefeIdParameter: RequestParamHandler = (
+  _req: Request,
+  res: Response,
+  next: NextFunction,
+  wert: unknown,
+) => {
+  if (typeof wert === 'string' && istGueltigeId(wert)) {
+    next();
+    return;
+  }
+  // Bewusst ohne Angabe, WELCHER Parameter beanstandet wurde: Die Meldung
+  // soll nicht zur Landkarte werden, welche Endpunkte welche IDs erwarten.
+  res.status(404).json({ success: false, error: 'Nicht gefunden' } as ApiResponse);
+};
+
+/**
+ * Haengt die Pruefung an einen Router. Namen, die der Router gar nicht
+ * verwendet, kosten nichts – Express ruft den Callback nur fuer Parameter,
+ * die in einer getroffenen Route vorkommen.
+ */
+export function registriereIdPruefung<T extends Router>(router: T): T {
+  for (const name of ID_PARAMETER) {
+    router.param(name, pruefeIdParameter);
+  }
+  return router;
+}

backend/src/routes/auditLog.routes.ts

@@ -7,29 +7,50 @@ const router = Router();
 // Alle Routen erfordern Authentifizierung
 router.use(authenticate);
 
+// ACHTUNG Reihenfolge: Alle konkreten Pfade MÜSSEN vor der Parameter-Route
+// '/:id' stehen, sonst schluckt diese sie und antwortet mit
+// "Ungültige Audit-Log-ID". Genau so war GET /retention-policies unerreichbar
+// (Pentest R166-04).
+
 // Audit-Logs abrufen
 router.get('/', requirePermission('audit:read'), auditLogController.getAuditLogs);
 
-// Audit-Logs exportieren (muss VOR /:id stehen!)
+// Audit-Logs exportieren
-router.get('/export', requirePermission('audit:read'), auditLogController.exportAuditLogs);
+//
+// Verlangt `audit:export`, nicht `audit:read`. Die Berechtigung stand im
+// Katalog und in der Rollenverwaltung, gatete aber NICHTS - jeder Leser
+// konnte das vollstaendige Protokoll in einem Zug herausziehen.
+//
+// Das ist etwas anderes als Blaettern: Der Export liefert `changesBefore` und
+// `changesAfter`, also die vollstaendigen Vorher/Nachher-Datensaetze, dazu
+// `resourceLabel` mit Klartextnamen, IP-Adressen und User-Agents. Aufgefallen
+// am Dienstkonto des Gegenbuchs: Es soll ausschliesslich Pruefwerte lesen -
+// und konnte Personendaten exportieren.
+router.get('/export', requirePermission('audit:export'), auditLogController.exportAuditLogs);
+
+// Retention-Policies
+router.get('/retention-policies', requirePermission('audit:admin'), auditLogController.getRetentionPolicies);
+router.put('/retention-policies/:id', requirePermission('audit:admin'), auditLogController.updateRetentionPolicy);
+
+// Kontrollwert für das externe Gegenbuch (nur lesend, ohne Geheimnisse)
+router.get('/checkpoint', requirePermission('audit:read'), auditLogController.getCheckpoint);
 
 // Audit-Logs für einen Kunden (DSGVO)
 router.get('/customer/:customerId', requirePermission('audit:read'), auditLogController.getAuditLogsByCustomer);
 
-// Einzelnes Audit-Log abrufen
-router.get('/:id', requirePermission('audit:read'), auditLogController.getAuditLogById);
-
 // Hash-Ketten-Integrität prüfen
 router.post('/verify', requirePermission('audit:read'), auditLogController.verifyIntegrity);
 
 // Hash-Kette reparieren
 router.post('/rehash', requirePermission('audit:admin'), auditLogController.rehashAll);
 
-// Retention-Policies
+// Altbestand versiegeln (nicht destruktiv)
-router.get('/retention-policies', requirePermission('audit:admin'), auditLogController.getRetentionPolicies);
+router.post('/seal-backlog', requirePermission('audit:admin'), auditLogController.sealBacklog);
-router.put('/retention-policies/:id', requirePermission('audit:admin'), auditLogController.updateRetentionPolicy);
 
 // Retention-Cleanup manuell ausführen
 router.post('/cleanup', requirePermission('audit:admin'), auditLogController.runRetentionCleanup);
 
+// Einzelnes Audit-Log abrufen – als LETZTE GET-Route, siehe Hinweis oben
+router.get('/:id', requirePermission('audit:read'), auditLogController.getAuditLogById);
+
 export default router;

backend/src/services/auth.service.ts

@@ -23,10 +23,194 @@ export function signAccessToken(payload: JwtPayload): string {
     expiresIn: ACCESS_TOKEN_EXPIRES_IN,
   });
 }
-export function signRefreshToken(payload: JwtPayload): string {
+export function signRefreshToken(payload: JwtPayload, jti?: string, familyId?: string): string {
-  return jwt.sign({ ...payload, type: 'refresh' }, process.env.JWT_SECRET as string, {
+  return jwt.sign(
-    expiresIn: REFRESH_TOKEN_EXPIRES_IN,
+    { ...payload, type: 'refresh', ...(jti ? { jti } : {}), ...(familyId ? { fam: familyId } : {}) },
+    process.env.JWT_SECRET as string,
+    { expiresIn: REFRESH_TOKEN_EXPIRES_IN },
+  );
+}
+
+// ===================== Refresh-Token-Replay-Schutz (R164-02) =====================
+//
+// Kulanzfenster: Mehrere Tabs teilen sich denselben Cookie und koennen einen
+// Refresh praktisch gleichzeitig ausloesen. Ohne Toleranz wuerde der zweite
+// legitime Aufruf als Replay gewertet und die Sitzung gesprengt. Die Toleranz
+// ist bewusst eng (Sekunden UND Anzahl begrenzt): ein Burst mit vielen
+// Wiederverwendungen - das typische Bild beim Missbrauch eines gestohlenen
+// Tokens - schlaegt weiterhin an.
+const REFRESH_REUSE_GRACE_MS = 15_000;
+const REFRESH_REUSE_MAX = 3;
+
+/** Legt einen neuen Sitzungs-Refresh-Token an (neue Familie). */
+export async function issueRefreshToken(
+  payload: JwtPayload,
+  opts: {
+    userId?: number;
+    customerId?: number;
+    isCustomerPortal: boolean;
+    familyId?: string;
+    /** Beim Rotieren bereits beim Einloesen reservierte jti des Nachfolgers. */
+    jti?: string;
+  },
+): Promise<string> {
+  const jti = opts.jti || crypto.randomUUID();
+  const familyId = opts.familyId || crypto.randomUUID();
+  const token = signRefreshToken(payload, jti, familyId);
+  const decoded: any = jwt.decode(token);
+
+  await prisma.refreshTokenRecord.create({
+    data: {
+      jti,
+      familyId,
+      userId: opts.userId ?? null,
+      customerId: opts.customerId ?? null,
+      isCustomerPortal: opts.isCustomerPortal,
+      expiresAt: new Date((decoded?.exp ?? 0) * 1000),
+    },
   });
+  return token;
+}
+
+/** Widerruft eine komplette Sitzungsfamilie. */
+async function revokeFamily(familyId: string, reason: string): Promise<void> {
+  await prisma.refreshTokenRecord.updateMany({
+    where: { familyId, revokedAt: null },
+    data: { revokedAt: new Date(), revokedReason: reason },
+  });
+}
+
+/** Widerruft alle Familien eines Subjekts (Logout, Rechteaenderung). */
+export async function revokeAllRefreshTokens(
+  subject: { userId?: number; customerId?: number },
+  reason: string,
+): Promise<void> {
+  const where = subject.userId != null ? { userId: subject.userId } : { customerId: subject.customerId };
+  await prisma.refreshTokenRecord.updateMany({
+    where: { ...where, revokedAt: null },
+    data: { revokedAt: new Date(), revokedReason: reason },
+  });
+}
+
+/** Abgelaufene Datensaetze entfernen (beim Login, seltener als beim Refresh). */
+async function pruneExpiredRefreshTokens(): Promise<void> {
+  try {
+    await prisma.refreshTokenRecord.deleteMany({ where: { expiresAt: { lt: new Date() } } });
+  } catch {
+    // Aufraeumen darf den Login nie blockieren.
+  }
+}
+
+/**
+ * Prueft die jti eines vorgelegten Refresh-Tokens und verbraucht sie.
+ * Wirft mit `code = 'REFRESH_REPLAY'`, wenn ein bereits eingeloester Token
+ * erneut auftaucht - der Controller meldet das als Sicherheitsvorfall.
+ */
+async function consumeRefreshJti(decoded: any): Promise<{
+  familyId: string;
+  /** Frische Rotation: Datensatz fuer diese jti muss noch angelegt werden. */
+  issueJti?: string;
+  /** Kulanz: dieser bereits ausgestellte Nachfolger wird erneut ausgegeben. */
+  reuseJti?: string;
+}> {
+  const jti: string | undefined = decoded?.jti;
+  const fam: string | undefined = decoded?.fam;
+
+  if (!jti || !fam) {
+    // Token aus der Zeit vor dem Replay-Schutz: bewusst fail-closed, damit
+    // kein Altbestand die Einmalverwendung umgehen kann. Kostet einmalig
+    // eine Neuanmeldung.
+    const err: any = new Error('Sitzung muss erneuert werden – bitte neu anmelden');
+    err.code = 'REFRESH_LEGACY';
+    throw err;
+  }
+
+  const rec = await prisma.refreshTokenRecord.findUnique({ where: { jti } });
+  if (!rec) {
+    const err: any = new Error('Refresh-Token ungültig oder abgelaufen');
+    err.code = 'REFRESH_INVALID';
+    throw err;
+  }
+  if (rec.revokedAt) {
+    const err: any = new Error('Refresh-Token wurde invalidiert (Logout/Rechteänderung)');
+    err.code = 'REFRESH_REVOKED';
+    throw err;
+  }
+
+  // Einloesen MUSS atomar sein. Ein Lesen-dann-Schreiben wuerde bei parallelen
+  // Anfragen nichts verhindern: alle wuerden den Token als "noch unbenutzt"
+  // sehen und durchgelassen (im Test kamen 90 gleichzeitige Requests
+  // ausnahmslos durch). Deshalb wird der Zustandswechsel als bedingtes UPDATE
+  // ausgefuehrt - die Datenbank entscheidet, wer zuerst war.
+  // Die jti des Nachfolgers wird SCHON HIER festgelegt und im selben UPDATE
+  // hinterlegt. Dadurch weiss eine spaetere Wiedervorlage, welcher Nachfolger
+  // bereits ausgestellt wurde - Grundlage der idempotenten Kulanz (R168-01).
+  const nachfolgerJti = crypto.randomUUID();
+  const beansprucht = await prisma.refreshTokenRecord.updateMany({
+    where: { jti, usedAt: null, revokedAt: null },
+    data: { usedAt: new Date(), replacedByJti: nachfolgerJti },
+  });
+  if (beansprucht.count === 1) {
+    return { familyId: rec.familyId, issueJti: nachfolgerJti };
+  }
+
+  // Bereits eingeloest. Innerhalb des engen Kulanzfensters begrenzt tolerieren
+  // (parallele Tabs) - als bedingtes UPDATE, damit die Obergrenze unter Last
+  // wirklich haelt.
+  const fensterAb = new Date(Date.now() - REFRESH_REUSE_GRACE_MS);
+  const toleriert = await prisma.refreshTokenRecord.updateMany({
+    where: {
+      jti,
+      revokedAt: null,
+      usedAt: { gte: fensterAb },
+      reuseCount: { lt: REFRESH_REUSE_MAX },
+    },
+    data: { reuseCount: { increment: 1 } },
+  });
+  if (toleriert.count === 1) {
+    // IDEMPOTENT: denselben, bereits ausgestellten Nachfolger zurueckgeben -
+    // NICHT erneut rotieren (Pentest R168-01).
+    //
+    // Vorher entstand bei jeder Kulanz-Wiedervorlage eine frische Linie mit
+    // eigenem, zurueckgesetztem Zaehler. Ein Angreifer mit gestohlenem Token
+    // konnte damit aus dem erkennbaren Replay-Zustand in eine eigene,
+    // sauber weiterrotierende Sitzung entkommen, die nie wieder mit der des
+    // Opfers kollidiert - also dauerhaft unsichtbar blieb.
+    //
+    // Jetzt laufen parallele Tabs auf DIESELBE Linie zusammen. Wer den Token
+    // spaeter erneut vorlegt (also ausserhalb des Fensters), kollidiert
+    // zwangslaeufig und loest den Familien-Widerruf aus.
+    const aktuell = await prisma.refreshTokenRecord.findUnique({ where: { jti } });
+    if (aktuell?.replacedByJti) {
+      const nachfolger = await prisma.refreshTokenRecord.findUnique({
+        where: { jti: aktuell.replacedByJti },
+      });
+      if (nachfolger?.revokedAt) {
+        const err: any = new Error('Refresh-Token wurde invalidiert (Logout/Rechteänderung)');
+        err.code = 'REFRESH_REVOKED';
+        throw err;
+      }
+      return { familyId: rec.familyId, reuseJti: aktuell.replacedByJti };
+    }
+    // Kein Nachfolger hinterlegt: nicht ersatzweise rotieren (das waere genau
+    // der Fork). Fail-closed als Replay behandeln.
+  }
+
+  // Weder frei noch tolerierbar: War der Token zwischenzeitlich widerrufen
+  // (z. B. durch einen parallelen Replay-Fund), ist das kein neuer Vorfall.
+  const aktuell = await prisma.refreshTokenRecord.findUnique({ where: { jti } });
+  if (aktuell?.revokedAt) {
+    const err: any = new Error('Refresh-Token wurde invalidiert (Logout/Rechteänderung)');
+    err.code = 'REFRESH_REVOKED';
+    throw err;
+  }
+
+  // Replay: gesamte Familie widerrufen - der Angreifer verliert den Zugang,
+  // der legitime Nutzer muss sich neu anmelden und merkt es dadurch.
+  await revokeFamily(rec.familyId, 'Replay eines bereits eingelösten Refresh-Tokens');
+  const err: any = new Error('Refresh-Token wurde bereits verwendet – Sitzung aus Sicherheitsgründen beendet');
+  err.code = 'REFRESH_REPLAY';
+  throw err;
 }
 
 // Kurzlebiger Download-Token (60s, single-purpose). Wird vom Frontend
@@ -133,8 +317,10 @@ export async function login(email: string, password: string) {
     isCustomerPortal: false,
   };
 
+  await pruneExpiredRefreshTokens();
   const accessToken = signAccessToken(payload);
-  const refreshToken = signRefreshToken(payload);
+  // Neue Sitzungsfamilie (Replay-Schutz, R164-02)
+  const refreshToken = await issueRefreshToken(payload, { userId: user.id, isCustomerPortal: false });
 
   return {
     accessToken,
@@ -147,6 +333,9 @@ export async function login(email: string, password: string) {
       permissions: Array.from(permissions),
       customerId: user.customerId,
       isCustomerPortal: false,
+      // Wird von der Audit-Middleware gelesen, um planmaessige
+      // Dienstkonto-Anmeldungen als Routine einzustufen (R182).
+      isServiceAccount: user.isServiceAccount,
     },
   };
 }
@@ -244,8 +433,10 @@ export async function customerLogin(email: string, password: string) {
     representedCustomerIds,
   };
 
+  await pruneExpiredRefreshTokens();
   const accessToken = signAccessToken(payload);
-  const refreshToken = signRefreshToken(payload);
+  // Neue Sitzungsfamilie (Replay-Schutz, R164-02)
+  const refreshToken = await issueRefreshToken(payload, { customerId: customer.id, isCustomerPortal: true });
 
   return {
     accessToken,
@@ -296,6 +487,22 @@ export async function refreshAccessToken(refreshToken: string): Promise<{
   if (decoded.type !== 'refresh') {
     throw new Error('Falscher Token-Typ');
   }
+  // Einmalverwendung durchsetzen und Sitzungsfamilie bestimmen (R164-02).
+  // Wirft bei Replay – danach ist die gesamte Familie widerrufen.
+  const rotation = await consumeRefreshJti(decoded);
+  // Bei Kulanz wird derselbe, bereits ausgestellte Nachfolger erneut signiert -
+  // ohne neuen Datensatz, damit keine zweite Linie entsteht (R168-01).
+  const naechsterRefreshToken = async (
+    payload: JwtPayload,
+    subjekt: { userId?: number; customerId?: number; isCustomerPortal: boolean },
+  ): Promise<string> =>
+    rotation.reuseJti
+      ? signRefreshToken(payload, rotation.reuseJti, rotation.familyId)
+      : issueRefreshToken(payload, {
+          ...subjekt,
+          familyId: rotation.familyId,
+          jti: rotation.issueJti,
+        });
   const issuedAt = decoded.iat ? decoded.iat * 1000 : 0;
 
   // Mitarbeiter
@@ -325,7 +532,9 @@ export async function refreshAccessToken(refreshToken: string): Promise<{
     };
     return {
       accessToken: signAccessToken(payload),
-      refreshToken: signRefreshToken(payload),
+      // Nachfolger bleibt in derselben Familie – ein Replay des Vorgaengers
+      // sprengt damit auch alle daraus entstandenen Tokens.
+      refreshToken: await naechsterRefreshToken(payload, { userId: user.id, isCustomerPortal: false }),
       user: {
         id: user.id,
         email: user.email,
@@ -356,7 +565,10 @@ export async function refreshAccessToken(refreshToken: string): Promise<{
     };
     return {
       accessToken: signAccessToken(payload),
-      refreshToken: signRefreshToken(payload),
+      refreshToken: await naechsterRefreshToken(payload, {
+        customerId: customer.id,
+        isCustomerPortal: true,
+      }),
       user: portalUser,
     };
   }

backend/src/services/heartbeatMonitor.service.ts

@@ -0,0 +1,83 @@
+import prisma from '../lib/prisma.js';
+import { emit as emitSecurityEvent } from './securityMonitor.service.js';
+
+/**
+ * Wachhund auf den AUSBLEIBENDEN Heartbeat (Pentest R182/R183).
+ *
+ * Dienstkonten – allen voran das Gegenbuch – melden sich in festem Takt an.
+ * Diese Anmeldungen sind bewusst als Routine eingestuft, damit sie die
+ * CRITICAL-Stufe nicht entwerten. Damit fehlt aber die andere Haelfte: Wer das
+ * Gegenbuch stilllegt, setzt genau darauf, dass STILLE nicht auffaellt. Ein
+ * gestopptes Gegenbuch ist sonst nicht von „laeuft ruhig“ zu unterscheiden.
+ *
+ * Das Sicherheitssignal ist deshalb nicht die Anwesenheit der Anmeldung,
+ * sondern ihre Abweichung: bleibt sie aus, wird es gemeldet.
+ *
+ * Bewusste Zurueckhaltung: Ohne jemals gesehene Anmeldung gibt es keine
+ * Grundlinie – dann wird geschwiegen statt geraten. Und pro Ausfall wird nur
+ * einmal gemeldet, nicht bei jedem Durchlauf.
+ */
+const PRUEFTAKT_MS = 15 * 60 * 1000;
+const MAX_ALTER_MINUTEN = Number.parseInt(process.env.SERVICE_ACCOUNT_MAX_SILENCE_MINUTES || '180', 10);
+
+export async function pruefeHeartbeats(): Promise<void> {
+  const konten = await prisma.user.findMany({
+    where: { isServiceAccount: true, isActive: true },
+    select: { id: true, email: true },
+  });
+  if (konten.length === 0) return;
+
+  const grenze = new Date(Date.now() - MAX_ALTER_MINUTEN * 60 * 1000);
+
+  for (const konto of konten) {
+    const letzte = await prisma.auditLog.findFirst({
+      where: { userId: konto.id, action: 'LOGIN' },
+      orderBy: { createdAt: 'desc' },
+      select: { createdAt: true },
+    });
+
+    // Nie angemeldet = keine Grundlinie. Schweigen statt raten.
+    if (!letzte) continue;
+    if (letzte.createdAt >= grenze) continue;
+
+    // Pro Ausfall nur einmal melden.
+    const schonGemeldet = await prisma.securityEvent.findFirst({
+      where: {
+        type: 'SUSPICIOUS',
+        userEmail: konto.email,
+        createdAt: { gte: letzte.createdAt },
+        message: { contains: 'Dienstkonto' },
+      },
+    });
+    if (schonGemeldet) continue;
+
+    const stillSeit = Math.round((Date.now() - letzte.createdAt.getTime()) / 60000);
+    await emitSecurityEvent({
+      type: 'SUSPICIOUS',
+      severity: 'CRITICAL',
+      message:
+        `Dienstkonto ${konto.email} meldet sich seit ${stillSeit} Minuten nicht mehr ` +
+        `(erwartet mindestens alle ${MAX_ALTER_MINUTEN} Minuten). ` +
+        'Entweder steht der zugehörige Dienst – etwa das Gegenbuch – oder er wurde stillgelegt. ' +
+        'Stille ist hier kein guter Zustand: Ohne laufendes Gegenbuch fällt eine nachträgliche ' +
+        'Änderung am Audit-Log nicht mehr auf.',
+      userEmail: konto.email,
+      userId: konto.id,
+      endpoint: 'heartbeat-monitor',
+    });
+  }
+}
+
+export function starteHeartbeatMonitor(): void {
+  if (!Number.isFinite(MAX_ALTER_MINUTEN) || MAX_ALTER_MINUTEN <= 0) {
+    console.warn('[Heartbeat] SERVICE_ACCOUNT_MAX_SILENCE_MINUTES ungültig – Wachhund bleibt aus.');
+    return;
+  }
+  const lauf = () => {
+    pruefeHeartbeats().catch((e) => console.error('[Heartbeat] Fehler:', e));
+  };
+  // Nicht sofort beim Start: Nach einem Neustart darf ein kurz zurueckliegender
+  // Ausfall nicht doppelt melden, und die DB soll erst oben sein.
+  setTimeout(lauf, 60_000);
+  setInterval(lauf, PRUEFTAKT_MS).unref();
+}

backend/src/services/pflichtrechte.service.ts

@@ -0,0 +1,82 @@
+import prisma from '../lib/prisma.js';
+
+/**
+ * Prueft beim Start, ob die gesetzlich gebundenen Rechte ueberhaupt jemand
+ * ausueben kann (Pentest R189-01).
+ *
+ * Hintergrund: `gdpr:export`, `gdpr:delete` und `gdpr:admin` haengen an den
+ * Rollen DSGVO und Developer – nicht an der Admin-Rolle. Nach einem frischen
+ * Seed war keine der beiden einem Konto zugewiesen. Ergebnis: Eine Auskunft
+ * nach Art. 15 oder eine Loeschung nach Art. 17 konnte NIEMAND ausfuehren,
+ * obwohl mehrere „Admin"-Konten existierten. Ein Ausfall mit Fristwirkung,
+ * ausgeloest durch nichts weiter als eine Neuinstallation.
+ *
+ * Der Seed weist das Recht jetzt zu – aber nur bei NEUINSTALLATION. Auf einer
+ * laufenden Datenbank aendert er nichts, und niemand merkt es, bis es darauf
+ * ankommt. Deshalb diese Wache: Sie erkennt die ABWESENHEIT einer Faehigkeit,
+ * so wie der Heartbeat das Ausbleiben eines Dienstkontos erkennt.
+ *
+ * Bewusst nur eine Meldung, keine automatische Vergabe: Rechte zu verteilen,
+ * ohne dass ein Mensch es veranlasst hat, waere der groessere Fehler.
+ */
+
+/** Rechte, deren Fehlen ein rechtliches und kein technisches Problem ist. */
+const PFLICHTRECHTE: Array<{ resource: string; action: string; wofuer: string }> = [
+  { resource: 'gdpr', action: 'export', wofuer: 'Auskunft nach Art. 15 DSGVO' },
+  { resource: 'gdpr', action: 'delete', wofuer: 'Löschung nach Art. 17 DSGVO' },
+  { resource: 'audit', action: 'read', wofuer: 'Prüfung des Audit-Protokolls' },
+];
+
+export async function pruefePflichtrechte(): Promise<void> {
+  try {
+    const fehlend: string[] = [];
+
+    for (const recht of PFLICHTRECHTE) {
+      const traeger = await prisma.user.count({
+        where: {
+          isActive: true,
+          roles: {
+            some: {
+              role: {
+                permissions: {
+                  some: {
+                    permission: { resource: recht.resource, action: recht.action },
+                  },
+                },
+              },
+            },
+          },
+        },
+      });
+      if (traeger === 0) {
+        fehlend.push(`${recht.resource}:${recht.action} (${recht.wofuer})`);
+      }
+    }
+
+    if (fehlend.length === 0) return;
+
+    console.warn(
+      '\n' +
+      '========================================================================\n' +
+      '  ACHTUNG: Für folgende Rechte gibt es KEIN aktives Konto:\n' +
+      fehlend.map((f) => `    – ${f}\n`).join('') +
+      '\n' +
+      '  Das ist kein Fehler der Anwendung, sondern eine Lücke in der\n' +
+      '  Rechtevergabe – und sie fällt erst auf, wenn eine Frist läuft.\n' +
+      '\n' +
+      '  Beheben: In der Benutzerverwaltung bei einem verantwortlichen Konto\n' +
+      '  den Haken „DSGVO-Zugriff" setzen (Audit-Protokoll lesen und\n' +
+      '  Datenschutz-Verwaltung). Für Eingriffe am Protokoll – versiegeln,\n' +
+      '  aufräumen, Aufbewahrung ändern – zusätzlich „Audit-Betrieb".\n' +
+      '========================================================================\n',
+    );
+  } catch (err) {
+    // Eine Wache darf den Start nicht verhindern. Aber schweigen darf sie
+    // auch nicht: „nicht geprüft" ist nicht dasselbe wie „nichts gefunden".
+    console.warn(
+      '[Pflichtrechte] Prüfung nicht möglich – der Zustand der Rechtevergabe ist ' +
+      'damit UNBEKANNT, nicht in Ordnung:',
+      err instanceof Error ? err.message : err,
+    );
+  }
+}

backend/src/services/user.service.ts

@@ -44,6 +44,7 @@ export async function getAllUsers(filters: UserFilters) {
         firstName: true,
         lastName: true,
         isActive: true,
+        isServiceAccount: true,
         customerId: true,
         whatsappNumber: true,
         telegramUsername: true,
@@ -64,9 +65,10 @@ export async function getAllUsers(filters: UserFilters) {
   ]);
 
   // Get hidden role IDs
-  const [developerRole, gdprRole] = await Promise.all([
+  const [developerRole, gdprRole, auditOpsRole] = await Promise.all([
     prisma.role.findFirst({ where: { name: 'Developer' } }),
     prisma.role.findFirst({ where: { name: 'DSGVO' } }),
+    prisma.role.findFirst({ where: { name: AUDIT_OPS_ROLLE } }),
   ]);
 
   return {
@@ -77,11 +79,15 @@ export async function getAllUsers(filters: UserFilters) {
       const hasGdprAccess = gdprRole
         ? u.roles.some((ur) => ur.roleId === gdprRole.id)
         : false;
+      const hasAuditOpsAccess = auditOpsRole
+        ? u.roles.some((ur) => ur.roleId === auditOpsRole.id)
+        : false;
       return {
         ...u,
         roles: u.roles.map((r) => r.role),
         hasDeveloperAccess,
         hasGdprAccess,
+        hasAuditOpsAccess,
       };
     }),
     pagination: buildPaginationResponse(page, limit, total),
@@ -97,6 +103,7 @@ export async function getUserById(id: number) {
       firstName: true,
       lastName: true,
       isActive: true,
+      isServiceAccount: true,
       customerId: true,
       whatsappNumber: true,
       telegramUsername: true,
@@ -144,6 +151,7 @@ export async function createUser(data: {
   customerId?: number;
   hasDeveloperAccess?: boolean;
   hasGdprAccess?: boolean;
+  hasAuditOpsAccess?: boolean;
   whatsappNumber?: string;
   telegramUsername?: string;
   signalNumber?: string;
@@ -170,6 +178,7 @@ export async function createUser(data: {
       firstName: true,
       lastName: true,
       isActive: true,
+      isServiceAccount: true,
       customerId: true,
       roles: {
         include: { role: true },
@@ -187,6 +196,10 @@ export async function createUser(data: {
     await setUserGdprAccess(user.id, true);
   }
 
+  if (data.hasAuditOpsAccess) {
+    await setUserAuditOpsAccess(user.id, true);
+  }
+
   return user;
 }
 
@@ -198,16 +211,18 @@ export async function updateUser(
     firstName?: string;
     lastName?: string;
     isActive?: boolean;
+    isServiceAccount?: boolean;
     roleIds?: number[];
     customerId?: number;
     hasDeveloperAccess?: boolean;
     hasGdprAccess?: boolean;
+    hasAuditOpsAccess?: boolean;
     whatsappNumber?: string;
     telegramUsername?: string;
     signalNumber?: string;
   }
 ) {
-  const { roleIds, password, hasDeveloperAccess, hasGdprAccess, ...userData } = data;
+  const { roleIds, password, hasDeveloperAccess, hasGdprAccess, hasAuditOpsAccess, ...userData } = data;
 
   // Check if this would remove the last admin
   const isBeingDeactivated = userData.isActive === false;
@@ -344,6 +359,10 @@ export async function updateUser(
     await setUserGdprAccess(id, hasGdprAccess);
   }
 
+  if (hasAuditOpsAccess !== undefined) {
+    await setUserAuditOpsAccess(id, hasAuditOpsAccess);
+  }
+
   return getUserById(id);
 }
 
@@ -403,6 +422,16 @@ async function setUserDeveloperAccess(userId: number, enabled: boolean) {
   }
 }
 
+/**
+ * Name der versteckten Rolle fuer eingreifende Audit-Rechte.
+ *
+ * Getrennt von `DSGVO`, weil Aufsicht und Eingriff nicht dieselbe Rolle sein
+ * duerfen: Wer das Protokoll beaufsichtigt, darf seine Beweisgrundlage nicht
+ * ersetzen koennen (Pentest R186). Die Rolle wird von `sync-roles.ts` beim
+ * Containerstart angelegt.
+ */
+export const AUDIT_OPS_ROLLE = 'Audit-Betrieb';
+
 // Helper to set GDPR access for a user
 async function setUserGdprAccess(userId: number, enabled: boolean) {
   // Get or create DSGVO role
@@ -411,17 +440,24 @@ async function setUserGdprAccess(userId: number, enabled: boolean) {
   });
 
   if (!gdprRole) {
-    // Create DSGVO role with all audit:* and gdpr:* permissions
+    // Rechte-Satz identisch zu sync-roles.ts: gdpr komplett, vom Audit-
+    // Protokoll nur LESEN und EXPORTIEREN. Ohne `audit:admin` - sonst
+    // brächte dieser Notfallpfad genau die Bündelung zurück, die wir gerade
+    // aufgelöst haben (zwei Listen, die dasselbe bedeuten sollen, laufen
+    // auseinander).
     const gdprPermissions = await prisma.permission.findMany({
       where: {
-        OR: [{ resource: 'audit' }, { resource: 'gdpr' }],
+        OR: [
+          { resource: 'gdpr' },
+          { resource: 'audit', action: { in: ['read', 'export'] } },
+        ],
       },
     });
 
     gdprRole = await prisma.role.create({
       data: {
         name: 'DSGVO',
-        description: 'DSGVO-Zugriff: Audit-Logs und Datenschutz-Verwaltung',
+        description: 'DSGVO-Zugriff: Audit-Logs lesen und Datenschutz-Verwaltung',
         permissions: {
           create: gdprPermissions.map((p) => ({ permissionId: p.id })),
         },
@@ -453,6 +489,50 @@ async function setUserGdprAccess(userId: number, enabled: boolean) {
   }
 }
 
+/**
+ * Eingreifende Audit-Rechte setzen: versiegeln, neu berechnen, aufraeumen,
+ * Aufbewahrung aendern. Bewusst getrennt vom DSGVO-Haken (siehe
+ * `AUDIT_OPS_ROLLE`).
+ */
+async function setUserAuditOpsAccess(userId: number, enabled: boolean) {
+  let rolle = await prisma.role.findFirst({ where: { name: AUDIT_OPS_ROLLE } });
+
+  if (!rolle) {
+    // Rechte-Satz identisch zu sync-roles.ts.
+    const rechte = await prisma.permission.findMany({
+      where: { resource: 'audit', action: { in: ['read', 'admin'] } },
+    });
+    rolle = await prisma.role.create({
+      data: {
+        name: AUDIT_OPS_ROLLE,
+        description: 'Darf das Audit-Protokoll versiegeln, aufräumen und die Aufbewahrung ändern',
+        permissions: { create: rechte.map((p) => ({ permissionId: p.id })) },
+      },
+    });
+  }
+
+  const hatRolle = await prisma.userRole.findFirst({
+    where: { userId, roleId: rolle.id },
+  });
+
+  if (enabled && !hatRolle) {
+    await prisma.userRole.create({ data: { userId, roleId: rolle.id } });
+    // Token invalidieren bei Rechteaenderung
+    await prisma.user.update({
+      where: { id: userId },
+      data: { tokenInvalidatedAt: new Date() },
+    });
+  } else if (!enabled && hatRolle) {
+    await prisma.userRole.delete({
+      where: { userId_roleId: { userId, roleId: rolle.id } },
+    });
+    await prisma.user.update({
+      where: { id: userId },
+      data: { tokenInvalidatedAt: new Date() },
+    });
+  }
+}
+
 export async function deleteUser(id: number) {
   // Check if user is an admin
   const user = await prisma.user.findUnique({

backend/src/utils/sanitize.ts

@@ -640,6 +640,10 @@ const USER_UPDATABLE_FIELDS = [
   'firstName',
   'lastName',
   'isActive',
+  // Kennzeichnet planmaessig arbeitende Konten (z. B. das Gegenbuch). Ihre
+  // Anmeldungen werden als Routine statt CRITICAL gefuehrt, dafuer wacht der
+  // Heartbeat-Monitor ueber ihr AUSBLEIBEN (Pentest R182/R183).
+  'isServiceAccount',
   'whatsappNumber',
   'telegramUsername',
   'signalNumber',
@@ -650,6 +654,10 @@ const USER_UPDATABLE_FIELDS = [
   // stehen, damit pick() sie nicht aus dem Request entfernt.
   'hasGdprAccess',
   'hasDeveloperAccess',
+  // Eingreifende Audit-Rechte (versiegeln/aufraeumen/Aufbewahrung), bewusst
+  // getrennt von hasGdprAccess: Aufsicht und Eingriff sind zwei Rollen
+  // (Pentest R186). Mappt auf die versteckte Rolle 'Audit-Betrieb'.
+  'hasAuditOpsAccess',
   // Nicht: id, customerId, tokenInvalidatedAt, passwordResetToken, passwordResetExpiresAt
   // Nicht: password – wird über dedizierten Endpoint POST /users/:id/password
   // gesetzt (Pentest Runde 12 (2026-05-18) – MITTEL: generisches User-Update

docker-compose.yml

@@ -62,6 +62,12 @@ services:
       JWT_EXPIRES_IN: ${JWT_EXPIRES_IN:-15m}
       JWT_REFRESH_EXPIRES_IN: ${JWT_REFRESH_EXPIRES_IN:-7d}
       ENCRYPTION_KEY: ${ENCRYPTION_KEY}
+      # Siegel für das Audit-Log: signiert jeden Eintrag mit einem Schlüssel,
+      # der außerhalb der Datenbank liegt. Ohne Wert läuft alles normal weiter,
+      # nur ungesiegelt (fail-safe). AUDIT_HMAC_KEY_OLD nur beim Wechsel füllen
+      # (kommagetrennte Liste früherer Schlüssel).
+      AUDIT_HMAC_KEY: ${AUDIT_HMAC_KEY:-}
+      AUDIT_HMAC_KEY_OLD: ${AUDIT_HMAC_KEY_OLD:-}
       NODE_ENV: production
       PORT: 3001
       LISTEN_ADDR: 0.0.0.0
@@ -84,6 +90,34 @@ services:
       # Auto-aktualisierter BLZ-/Bankdaten-Datensatz (Bundesbank-Bankleitzahlen)
       - ${BANKDATA_DIR:-./data/bankdata}:/app/bankdata
 
+  # Optionaler Reverse-Proxy mit automatischem SSL – nur fuer Betreiber OHNE
+  # eigenen Proxy. Wird standardmaessig NICHT angelegt.
+  #
+  # Einschalten ueber die .env (kein Auskommentieren noetig):
+  #     COMPOSE_PROFILES=caddy
+  # Danach reicht wie gewohnt `docker-compose up -d`. Alternativ einmalig per
+  # Flag: `docker-compose --profile caddy up -d`.
+  # Wer nginx / Nginx Proxy Manager / Traefik davor hat, laesst das Feld leer.
+  caddy:
+    image: caddy:2-alpine
+    container_name: opencrm-caddy
+    restart: unless-stopped
+    profiles: ["caddy"]
+    depends_on:
+      - opencrm
+    environment:
+      DOMAIN: ${DOMAIN:-localhost}
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      # Zertifikate liegen wie alle Daten unter ./data/ – nicht loeschen,
+      # sonst werden bei jedem Start neue Zertifikate angefordert
+      # (Let's-Encrypt-Limits!).
+      - ${CADDY_DIR:-./data/caddy}:/data
+      - ${CADDY_CONFIG_DIR:-./data/caddy-config}:/config
+
   adminer:
     image: adminer:latest
     container_name: opencrm-adminer

docker/.env.example

@@ -1,29 +0,0 @@
-# OpenCRM Docker Environment
-# ============================
-# Copy this file to .env and adjust the values
-
-# Domain (for Caddy SSL certificate)
-# Use your actual domain, e.g., crm.example.com
-DOMAIN=localhost
-
-# Database
-DB_ROOT_PASSWORD=change-this-root-password
-DB_NAME=opencrm
-DB_USER=opencrm
-DB_PASSWORD=change-this-password
-
-# JWT Authentication
-# Generate with: openssl rand -base64 32
-JWT_SECRET=change-this-to-a-secure-random-string
-# Access-Token kurz (XSS-Schutz, Token lebt nur im JS-Memory).
-# Refresh-Token lang im httpOnly-Cookie.
-JWT_EXPIRES_IN=15m
-JWT_REFRESH_EXPIRES_IN=7d
-
-# Encryption Key (for portal credentials)
-# Generate with: openssl rand -hex 32
-ENCRYPTION_KEY=change-this-to-a-32-byte-hex-key
-
-# First Install: Set to "true" to seed database on first startup
-# After first successful start, set back to "false"
-RUN_SEED=true

docker/Caddyfile

@@ -1,34 +0,0 @@
-# OpenCRM Caddyfile
-# ===================
-# Replace {$DOMAIN} with your actual domain or use environment variable
-# For local development without SSL, use localhost:80
-
-{$DOMAIN:localhost} {
-    # Reverse proxy to OpenCRM app
-    reverse_proxy app:3001
-
-    # Logging
-    log {
-        output stdout
-        format console
-    }
-
-    # Security headers
-    header {
-        # Clickjacking protection
-        X-Frame-Options "SAMEORIGIN"
-        # XSS protection
-        X-Content-Type-Options "nosniff"
-        X-XSS-Protection "1; mode=block"
-        # Referrer policy
-        Referrer-Policy "strict-origin-when-cross-origin"
-    }
-
-    # Gzip compression
-    encode gzip
-
-    # Handle file uploads (increase body limit)
-    request_body {
-        max_size 50MB
-    }
-}

docker/Dockerfile

@@ -1,97 +0,0 @@
-# ===================================
-# Stage 1: Build Frontend
-# ===================================
-FROM node:20-alpine AS frontend-builder
-
-WORKDIR /app/frontend
-
-# Copy package files
-COPY frontend/package*.json ./
-
-# Install dependencies
-RUN npm ci
-
-# Copy frontend source
-COPY frontend/ ./
-
-# Build frontend
-RUN npm run build
-
-# ===================================
-# Stage 2: Build Backend
-# ===================================
-FROM node:20-alpine AS backend-builder
-
-WORKDIR /app/backend
-
-# Install OpenSSL for Prisma
-RUN apk add --no-cache openssl
-
-# Copy package files
-COPY backend/package*.json ./
-
-# Install dependencies (including dev for build)
-RUN npm ci
-
-# Copy backend source
-COPY backend/ ./
-
-# Generate Prisma client
-RUN npx prisma generate
-
-# Build TypeScript
-RUN npm run build
-
-# ===================================
-# Stage 3: Production Runtime
-# ===================================
-FROM node:20-alpine AS production
-
-WORKDIR /app
-
-# Install OpenSSL for Prisma runtime and netcat for DB health check
-RUN apk add --no-cache openssl netcat-openbsd
-
-# Create non-root user
-RUN addgroup -g 1001 -S nodejs && \
-    adduser -S opencrm -u 1001 -G nodejs
-
-# Copy backend package files
-COPY backend/package*.json ./
-
-# Install production dependencies + tsx for seed script
-RUN npm ci --omit=dev && npm install tsx
-
-# Copy Prisma schema and generate client
-COPY backend/prisma ./prisma
-RUN npx prisma generate
-
-# Copy built backend
-COPY --from=backend-builder /app/backend/dist ./dist
-
-# Copy built frontend to public directory
-COPY --from=frontend-builder /app/frontend/dist ./public
-
-# Copy seed file for factory reset
-COPY backend/prisma/seed.ts ./prisma/
-
-# Copy entrypoint script
-COPY docker/entrypoint.sh ./entrypoint.sh
-
-# Create directories for uploads and backups
-RUN mkdir -p uploads backups && \
-    chmod +x entrypoint.sh && \
-    chown -R opencrm:nodejs /app
-
-# Switch to non-root user
-USER opencrm
-
-# Expose port
-EXPOSE 3001
-
-# Health check
-HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
-    CMD wget --no-verbose --tries=1 --spider http://localhost:3001/api/health || exit 1
-
-# Start the application with entrypoint
-ENTRYPOINT ["./entrypoint.sh"]

docker/README.md

@@ -1,139 +0,0 @@
-# OpenCRM Docker Deployment
-
-## Schnellstart
-
-1. **Umgebungsvariablen konfigurieren:**
-   ```bash
-   cd docker
-   cp .env.example .env
-   nano .env  # Sichere Werte setzen
-   ```
-
-2. **Container starten (erster Start mit RUN_SEED=true):**
-   ```bash
-   docker compose up -d
-   ```
-
-   Beim ersten Start wird automatisch:
-   - Auf die Datenbank gewartet
-   - Migrationen ausgeführt
-   - Seed-Daten geladen (wenn `RUN_SEED=true`)
-
-3. **Nach erfolgreicher Installation:**
-   ```bash
-   # RUN_SEED in .env auf false setzen
-   sed -i 's/RUN_SEED=true/RUN_SEED=false/' .env
-   ```
-
-4. **Anwendung aufrufen:**
-   - Mit Domain: `https://your-domain.com`
-   - Lokal: `http://localhost`
-
-5. **Login:**
-   - E-Mail: `admin@admin.com`
-   - Passwort: `admin`
-
-## Architektur
-
-```
-                    ┌─────────────┐
-                    │   Caddy     │
-                    │  (SSL/TLS)  │
-                    │   :80/:443  │
-                    └──────┬──────┘
-                           │
-                    ┌──────▼──────┐
-                    │   OpenCRM   │
-                    │   (Node.js) │
-                    │    :3001    │
-                    └──────┬──────┘
-                           │
-                    ┌──────▼──────┐
-                    │   MariaDB   │
-                    │    :3306    │
-                    └─────────────┘
-```
-
-## Befehle
-
-### Container verwalten
-```bash
-# Starten
-docker compose up -d
-
-# Stoppen
-docker compose down
-
-# Logs anzeigen
-docker compose logs -f app
-
-# Neustart
-docker compose restart app
-```
-
-### Datenbank
-```bash
-# Migration ausführen
-docker compose exec app npx prisma migrate deploy
-
-# Seed-Daten laden
-docker compose exec app npx tsx prisma/seed.ts
-
-# Prisma Studio (Datenbank-UI)
-docker compose exec app npx prisma studio
-```
-
-### Backup & Restore
-```bash
-# Backup-Verzeichnis ist unter /app/backups gemountet
-# Backups werden über die Anwendung erstellt/wiederhergestellt
-```
-
-### Update
-```bash
-# Image neu bauen und Container aktualisieren
-docker compose build --no-cache
-docker compose up -d
-# Migrationen werden automatisch beim Start ausgeführt
-```
-
-## Volumes
-
-| Volume | Beschreibung |
-|--------|--------------|
-| `mariadb_data` | Datenbank-Dateien |
-| `uploads_data` | Hochgeladene Dokumente |
-| `backups_data` | Backup-Dateien |
-| `caddy_data` | SSL-Zertifikate |
-| `caddy_config` | Caddy-Konfiguration |
-
-## SSL-Zertifikat
-
-Caddy holt automatisch ein Let's Encrypt Zertifikat wenn:
-- Die Domain in `.env` korrekt gesetzt ist
-- Port 80 und 443 von außen erreichbar sind
-- DNS auf den Server zeigt
-
-Für lokale Entwicklung mit `DOMAIN=localhost` wird ein selbstsigniertes Zertifikat verwendet.
-
-## Troubleshooting
-
-### Container startet nicht
-```bash
-docker compose logs app
-```
-
-### Datenbank-Verbindung fehlgeschlagen
-```bash
-# Warten bis MariaDB bereit ist
-docker compose logs db
-```
-
-### SSL-Zertifikat Probleme
-```bash
-docker compose logs caddy
-# Caddy-Daten zurücksetzen
-docker compose down
-docker volume rm opencrm_caddy_data opencrm_caddy_config
-docker compose up -d
-```

docker/docker-compose.yml

@@ -1,88 +0,0 @@
-version: '3.8'
-
-services:
-  # ===================================
-  # MariaDB Database
-  # ===================================
-  db:
-    image: mariadb:10.11
-    container_name: opencrm-db
-    restart: unless-stopped
-    environment:
-      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-rootpassword}
-      MYSQL_DATABASE: ${DB_NAME:-opencrm}
-      MYSQL_USER: ${DB_USER:-opencrm}
-      MYSQL_PASSWORD: ${DB_PASSWORD:-opencrm123}
-    volumes:
-      - mariadb_data:/var/lib/mysql
-    networks:
-      - opencrm-network
-    healthcheck:
-      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
-      start_period: 10s
-      interval: 10s
-      timeout: 5s
-      retries: 3
-
-  # ===================================
-  # OpenCRM Application
-  # ===================================
-  app:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-    container_name: opencrm-app
-    restart: unless-stopped
-    environment:
-      NODE_ENV: production
-      PORT: 3001
-      DATABASE_URL: mysql://${DB_USER:-opencrm}:${DB_PASSWORD:-opencrm123}@db:3306/${DB_NAME:-opencrm}
-      JWT_SECRET: ${JWT_SECRET:?JWT_SECRET is required}
-      JWT_EXPIRES_IN: ${JWT_EXPIRES_IN:-7d}
-      ENCRYPTION_KEY: ${ENCRYPTION_KEY:?ENCRYPTION_KEY is required}
-      RUN_SEED: ${RUN_SEED:-false}
-    volumes:
-      - uploads_data:/app/uploads
-      - backups_data:/app/backups
-    networks:
-      - opencrm-network
-    depends_on:
-      db:
-        condition: service_healthy
-    healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3001/api/health"]
-      start_period: 60s
-      interval: 30s
-      timeout: 10s
-      retries: 3
-
-  # ===================================
-  # Caddy Reverse Proxy (with auto SSL)
-  # ===================================
-  caddy:
-    image: caddy:2-alpine
-    container_name: opencrm-caddy
-    restart: unless-stopped
-    ports:
-      - "80:80"
-      - "443:443"
-    volumes:
-      - ./Caddyfile:/etc/caddy/Caddyfile:ro
-      - caddy_data:/data
-      - caddy_config:/config
-    networks:
-      - opencrm-network
-    depends_on:
-      app:
-        condition: service_healthy
-
-networks:
-  opencrm-network:
-    driver: bridge
-
-volumes:
-  mariadb_data:
-  uploads_data:
-  backups_data:
-  caddy_data:
-  caddy_config:

docker/entrypoint.sh

@@ -1,40 +0,0 @@
-#!/bin/sh
-set -e
-
-echo "=== OpenCRM Startup ==="
-
-# Wait for database to be ready
-echo "Waiting for database connection..."
-MAX_RETRIES=30
-RETRY_COUNT=0
-
-while ! nc -z db 3306 2>/dev/null; do
-    RETRY_COUNT=$((RETRY_COUNT + 1))
-    if [ $RETRY_COUNT -ge $MAX_RETRIES ]; then
-        echo "Error: Database not available after $MAX_RETRIES attempts"
-        exit 1
-    fi
-    echo "  Attempt $RETRY_COUNT/$MAX_RETRIES - waiting..."
-    sleep 2
-done
-echo "Database is ready!"
-
-# Run migrations
-echo "Running database migrations..."
-npx prisma migrate deploy
-
-# Seed database if RUN_SEED is set (first install)
-if [ "$RUN_SEED" = "true" ]; then
-    echo "Seeding database..."
-    npx tsx prisma/seed.ts
-fi
-
-# Einmal-Bereinigung für Pentest-Reste (Runde 12): XSS-Strings aus
-# Customer/User-Feldern entfernen + unbekannte AppSettings löschen.
-# Idempotent – läuft bei jedem Container-Start ohne Risiko.
-echo "Running data cleanup..."
-npx tsx prisma/cleanup-xss-and-mass-assignment.ts || echo "  (Cleanup übersprungen, nicht-kritisch)"
-
-# Start the application
-echo "Starting OpenCRM server..."
-exec node dist/index.js

frontend/src/pages/settings/AuditIntegrityCard.tsx

@@ -0,0 +1,209 @@
+import { useQuery } from '@tanstack/react-query';
+import { auditLogApi, IntegrityResult } from '../../services/api';
+import Card from '../../components/ui/Card';
+import Button from '../../components/ui/Button';
+import {
+  ShieldCheck, ShieldAlert, ShieldQuestion, RefreshCw, Loader2, ChevronDown, ChevronUp,
+} from 'lucide-react';
+import { useState } from 'react';
+
+/**
+ * Statuskarte fuer die Unversehrtheit des Audit-Protokolls.
+ *
+ * Die Prueflast steigt mit der Groesse des Protokolls (die Pruefung liest die
+ * gesamte Kette). Deshalb laeuft sie beim Oeffnen der Seite EINMAL und wird
+ * fuenf Minuten lang wiederverwendet; wer sofort neu pruefen will, nutzt den
+ * Knopf.
+ */
+
+type Ampel = 'ok' | 'befund' | 'hinweis' | 'unbekannt';
+
+function ampelFuer(r: IntegrityResult): Ampel {
+  if (!r.valid) return 'befund';
+  // Gueltig, aber nicht vollstaendig pruefbar: kein gruenes Licht vortaeuschen.
+  if (r.unverifiableEntries.length > 0) return 'unbekannt';
+  if (r.backlogSealStatus === 'kein_siegel') return 'hinweis';
+  return 'ok';
+}
+
+const AMPEL_STIL: Record<Ampel, { box: string; titel: string; text: string }> = {
+  ok:        { box: 'bg-green-50 border-green-200',  titel: 'text-green-900',  text: 'text-green-800' },
+  befund:    { box: 'bg-red-50 border-red-200',      titel: 'text-red-900',    text: 'text-red-800' },
+  hinweis:   { box: 'bg-yellow-50 border-yellow-200',titel: 'text-yellow-900', text: 'text-yellow-800' },
+  unbekannt: { box: 'bg-gray-50 border-gray-200',    titel: 'text-gray-900',   text: 'text-gray-700' },
+};
+
+function AmpelIcon({ ampel }: { ampel: Ampel }) {
+  const c = 'w-7 h-7 shrink-0';
+  if (ampel === 'ok') return <ShieldCheck className={`${c} text-green-600`} />;
+  if (ampel === 'befund') return <ShieldAlert className={`${c} text-red-600`} />;
+  if (ampel === 'hinweis') return <ShieldAlert className={`${c} text-yellow-600`} />;
+  return <ShieldQuestion className={`${c} text-gray-500`} />;
+}
+
+const AMPEL_TITEL: Record<Ampel, string> = {
+  ok: 'Protokoll unversehrt',
+  befund: 'Befund – das gehört angesehen',
+  hinweis: 'Unversehrt, aber ungeschützter Altbestand',
+  unbekannt: 'Nicht vollständig prüfbar',
+};
+
+const SIEGEL_TEXT: Record<IntegrityResult['backlogSealStatus'], string> = {
+  intakt: 'versiegelt und intakt',
+  leer: 'Siegel vorhanden, aber ohne Inhalt',
+  kein_siegel: 'nicht versiegelt',
+  nicht_noetig: 'nicht nötig (alles signiert)',
+  gebrochen: 'GEBROCHEN',
+  entfernt: 'ENTFERNT',
+};
+
+/** Zeigt eine Zahl nur, wenn sie ungleich null ist – sonst bleibt es ruhig. */
+function Zahl({ label, ids, ton }: { label: string; ids: number[]; ton: string }) {
+  if (ids.length === 0) return null;
+  const gekuerzt = ids.length > 12 ? `${ids.slice(0, 12).join(', ')} … (+${ids.length - 12})` : ids.join(', ');
+  return (
+    <div className="flex items-baseline gap-2 text-sm">
+      <span className={`font-medium ${ton}`}>{label}:</span>
+      <span className="text-gray-600">{ids.length}</span>
+      <span className="text-gray-400 font-mono text-xs break-all">({gekuerzt})</span>
+    </div>
+  );
+}
+
+export default function AuditIntegrityCard() {
+  const [offen, setOffen] = useState(false);
+  const { data, isFetching, isError, error, refetch } = useQuery({
+    queryKey: ['audit-integrity'],
+    queryFn: () => auditLogApi.verifyIntegrity(),
+    staleTime: 5 * 60 * 1000,
+    refetchOnWindowFocus: false,
+    retry: false,
+  });
+
+  const ergebnis = data?.data;
+
+  return (
+    <Card
+      className="mb-6"
+      title="Unversehrtheit des Protokolls"
+      actions={
+        <Button variant="secondary" onClick={() => refetch()} disabled={isFetching}>
+          {isFetching
+            ? <Loader2 className="w-4 h-4 mr-2 animate-spin" />
+            : <RefreshCw className="w-4 h-4 mr-2" />}
+          Neu prüfen
+        </Button>
+      }
+    >
+      {isFetching && !ergebnis && (
+        <div className="flex items-center gap-3 text-gray-500">
+          <Loader2 className="w-5 h-5 animate-spin" />
+          <span>Die Kette wird geprüft …</span>
+        </div>
+      )}
+
+      {isError && (
+        <div className="flex items-start gap-4 p-4 rounded-lg border bg-gray-50 border-gray-200">
+          <ShieldQuestion className="w-7 h-7 shrink-0 text-gray-500" />
+          <div>
+            <p className="font-medium text-gray-900">Prüfung nicht möglich</p>
+            <p className="text-sm text-gray-700 mt-1">
+              {error instanceof Error ? error.message : 'Unbekannter Fehler'}
+            </p>
+            <p className="text-sm text-gray-600 mt-2">
+              Das ist <strong>keine</strong> Entwarnung – der Zustand der Kette ist damit
+              schlicht unbekannt.
+            </p>
+          </div>
+        </div>
+      )}
+
+      {ergebnis && (() => {
+        const ampel = ampelFuer(ergebnis);
+        const stil = AMPEL_STIL[ampel];
+        return (
+          <>
+            <div className={`flex items-start gap-4 p-4 rounded-lg border ${stil.box}`}>
+              <AmpelIcon ampel={ampel} />
+              <div className="min-w-0">
+                <p className={`font-medium ${stil.titel}`}>
+                  {AMPEL_TITEL[ampel]}
+                  {ampel === 'ok' && ergebnis.rehashes.length > 0 && (
+                    <span className="font-normal"> – seit der letzten Neuberechnung</span>
+                  )}
+                </p>
+                <p className={`text-sm mt-1 ${stil.text}`}>{ergebnis.message}</p>
+                <p className="text-sm text-gray-500 mt-2">
+                  {ergebnis.checkedCount.toLocaleString('de-DE')} Einträge geprüft ·
+                  {' '}Altbestand: {SIEGEL_TEXT[ergebnis.backlogSealStatus]}
+                  {ergebnis.backlogSealCount > 1 && ` · ${ergebnis.backlogSealCount}× versiegelt`}
+                </p>
+              </div>
+            </div>
+
+            <button
+              type="button"
+              onClick={() => setOffen(o => !o)}
+              className="mt-3 flex items-center gap-1 text-sm text-gray-600 hover:text-gray-900"
+            >
+              {offen ? <ChevronUp className="w-4 h-4" /> : <ChevronDown className="w-4 h-4" />}
+              Einzelheiten
+            </button>
+
+            {offen && (
+              <div className="mt-3 space-y-2 border-t pt-3">
+                <Zahl label="Nachträglich verändert" ids={ergebnis.tamperedEntries} ton="text-red-700" />
+                <Zahl label="Gesiegelte Alteinträge verändert" ids={ergebnis.backlogTampered} ton="text-red-700" />
+                <Zahl label="Gesiegelte Alteinträge entfernt" ids={ergebnis.backlogMissing} ton="text-red-700" />
+                <Zahl label="Verkettung unterbrochen" ids={ergebnis.chainGaps} ton="text-yellow-700" />
+                <Zahl label="davon ohne dokumentierte Löschung" ids={ergebnis.unexplainedGaps} ton="text-yellow-700" />
+                <Zahl label="davon vom Siegel beglaubigt" ids={ergebnis.attestedGaps} ton="text-gray-700" />
+                <Zahl label="Ohne Schlüssel nicht prüfbar" ids={ergebnis.unverifiableEntries} ton="text-gray-700" />
+                {ergebnis.tamperedEntries.length === 0 &&
+                  ergebnis.chainGaps.length === 0 &&
+                  ergebnis.unverifiableEntries.length === 0 &&
+                  ergebnis.rehashes.length === 0 && (
+                    <p className="text-sm text-gray-500 italic">Nichts zu berichten.</p>
+                  )}
+                {ergebnis.rehashes.length > 0 && (
+                  <div className="pt-2 border-t mt-2">
+                    <p className="text-sm font-medium text-gray-700">Neuberechnungen der Kette</p>
+                    {ergebnis.rehashes.map((r) => (
+                      <p key={r.id} className="text-sm text-gray-600 mt-1">
+                        {new Date(r.zeitpunkt).toLocaleString('de-DE')} · Eintrag {r.id}
+                        {r.neuBerechnet !== null && ` · ${r.neuBerechnet} Einträge neu verkettet`}
+                        {r.vorbefund && (
+                          <span className="text-gray-500">
+                            {' '}· davor: {r.vorbefund.manipuliert} beanstandet,{' '}
+                            {r.vorbefund.luecken} Lücken
+                          </span>
+                        )}
+                        {!r.signiert && (
+                          <span className="text-red-700"> · ohne gültige Signatur</span>
+                        )}
+                      </p>
+                    ))}
+                    <p className="text-xs text-gray-500 mt-2">
+                      Ein Rehash verknüpft alle Einträge neu. Was davor als Lücke oder
+                      Beanstandung sichtbar war, ist danach nicht mehr in der Kette zu sehen –
+                      nur noch im Vorbefund des jeweiligen Eintrags. Die Aussage dieser Prüfung
+                      reicht deshalb bis zur letzten Neuberechnung zurück, nicht weiter.
+                    </p>
+                  </div>
+                )}
+                <p className="text-xs text-gray-500 pt-2">
+                  <strong>Verändert</strong> heißt: der Inhalt einer bestehenden Zeile passt nicht
+                  mehr zu ihrer Prüfsumme – das ist ernst.
+                  {' '}<strong>Verkettung unterbrochen</strong> heißt: die Zeilen selbst sind
+                  unversehrt, aber ein Glied fehlt oder wurde parallel geschrieben.
+                  {' '}<strong>Beglaubigt</strong> sind Lücken, die beim Versiegeln des Altbestands
+                  bereits bestanden und im signierten Siegel festgehalten sind.
+                </p>
+              </div>
+            )}
+          </>
+        );
+      })()}
+    </Card>
+  );
+}

frontend/src/pages/settings/AuditLogs.tsx

@@ -1,12 +1,14 @@
 import { useState } from 'react';
 import { useQuery } from '@tanstack/react-query';
 import { useNavigate } from 'react-router-dom';
+import { useAuth } from '../../context/AuthContext';
 import { auditLogApi, AuditLogSearchParams, authApi } from '../../services/api';
 import type { AuditLog, AuditAction, AuditSensitivity } from '../../types';
 import Card from '../../components/ui/Card';
 import Button from '../../components/ui/Button';
 import Input from '../../components/ui/Input';
 import Select from '../../components/ui/Select';
+import AuditIntegrityCard from './AuditIntegrityCard';
 import { ArrowLeft, Download, Eye, Shield, ShieldAlert, RefreshCw, ChevronLeft, ChevronRight, X } from 'lucide-react';
 
 const ACTION_OPTIONS = [
@@ -278,6 +280,10 @@ function DetailModal({ log, onClose }: DetailModalProps) {
 
 export default function AuditLogs() {
   const navigate = useNavigate();
+  // Export haengt an `audit:export`, Lesen an `audit:read` – ein Konto darf
+  // blaettern duerfen, ohne das gesamte Protokoll herausziehen zu koennen.
+  // Ohne diese Abfrage stuenden hier Knoepfe, die zuverlaessig 403 liefern.
+  const { hasPermission } = useAuth();
   const [page, setPage] = useState(1);
   const [filters, setFilters] = useState<AuditLogSearchParams>({
     page: 1,
@@ -307,11 +313,16 @@ export default function AuditLogs() {
         const downloadToken = await authApi.getDownloadToken();
         const params = new URLSearchParams();
         params.set('format', 'csv');
-        if (filters.action) params.set('action', filters.action);
+        // ALLE aktiven Filter mitgeben (Pentest R186-01). Vorher standen hier
-        if (filters.sensitivity) params.set('sensitivity', filters.sensitivity);
+        // nur fuenf – wer im Suchfeld eingrenzte und dann CSV klickte, bekam
-        if (filters.resourceType) params.set('resourceType', filters.resourceType);
+        // stillschweigend das gesamte Protokoll statt seiner Auswahl.
-        if (filters.startDate) params.set('startDate', filters.startDate);
+        // `page`/`limit` gehoeren nicht dazu: der Export ist bewusst
-        if (filters.endDate) params.set('endDate', filters.endDate);
+        // vollstaendig ueber die gefilterte Menge.
+        for (const [schluessel, wert] of Object.entries(filters)) {
+          if (schluessel === 'page' || schluessel === 'limit') continue;
+          if (wert === undefined || wert === null || wert === '') continue;
+          params.set(schluessel, String(wert));
+        }
         window.open(`/api/audit-logs/export?${params}&token=${downloadToken ?? ''}`, '_blank');
       } else {
         const result = await auditLogApi.export({ ...filters, format });
@@ -341,6 +352,8 @@ export default function AuditLogs() {
         <h1 className="text-2xl font-bold">Audit-Protokoll</h1>
       </div>
 
+      <AuditIntegrityCard />
+
       {/* Filter */}
       <Card className="mb-6">
         <div className="grid grid-cols-1 md:grid-cols-4 gap-4 mb-4">
@@ -385,14 +398,18 @@ export default function AuditLogs() {
               <RefreshCw className="w-4 h-4 mr-2" />
               Aktualisieren
             </Button>
-            <Button variant="secondary" onClick={() => handleExport('json')}>
+            {hasPermission('audit:export') && (
-              <Download className="w-4 h-4 mr-2" />
+              <Button variant="secondary" onClick={() => handleExport('json')}>
-              JSON
+                <Download className="w-4 h-4 mr-2" />
-            </Button>
+                JSON
-            <Button variant="secondary" onClick={() => handleExport('csv')}>
+              </Button>
-              <Download className="w-4 h-4 mr-2" />
+            )}
-              CSV
+            {hasPermission('audit:export') && (
-            </Button>
+              <Button variant="secondary" onClick={() => handleExport('csv')}>
+                <Download className="w-4 h-4 mr-2" />
+                CSV
+              </Button>
+            )}
           </div>
         </div>
       </Card>

frontend/src/pages/settings/Monitoring.tsx

@@ -37,6 +37,7 @@ const TYPE_OPTIONS: { value: SecurityEventType | ''; label: string }[] = [
   { value: 'LOGOUT', label: 'Logout' },
   { value: 'TOKEN_REJECTED', label: 'Token abgelehnt' },
   { value: 'PERMISSION_CHANGED', label: 'Berechtigung geändert' },
+  { value: 'AUDIT_SEAL_CHANGED', label: 'Bestandssiegel gesetzt/ersetzt' },
   { value: 'SUSPICIOUS', label: 'Verdächtig (Threshold)' },
 ];
 

frontend/src/pages/users/UserList.tsx

@@ -121,7 +121,7 @@ export default function UserList() {
                       <td className="py-3 px-4">{user.email}</td>
                       <td className="py-3 px-4">
                         <div className="flex gap-1 flex-wrap">
-                          {user.roles?.filter((role: any) => !['Developer', 'Kunde', 'DSGVO'].includes(role.name)).map((role: any) => (
+                          {user.roles?.filter((role: any) => !['Developer', 'Kunde', 'DSGVO', 'Audit-Betrieb'].includes(role.name)).map((role: any) => (
                             <Badge key={role.id || role.name} variant="info">
                               {role.name}
                             </Badge>
@@ -246,7 +246,9 @@ function UserModal({
     roleIds: [] as number[],
     isActive: true,
     hasDeveloperAccess: false,
+    hasAuditOpsAccess: false,
     hasGdprAccess: false,
+    isServiceAccount: false,
     whatsappNumber: '',
     telegramUsername: '',
     signalNumber: '',
@@ -263,10 +265,12 @@ function UserModal({
           currentPassword: '',
           firstName: user.firstName,
           lastName: user.lastName,
-          roleIds: user.roles?.filter((r: any) => !['Developer', 'Kunde', 'DSGVO'].includes(r.name)).map((r: any) => r.id) || [],
+          roleIds: user.roles?.filter((r: any) => !['Developer', 'Kunde', 'DSGVO', 'Audit-Betrieb'].includes(r.name)).map((r: any) => r.id) || [],
           isActive: (user as any).isActive ?? true,
           hasDeveloperAccess: (user as any).hasDeveloperAccess ?? false,
+          hasAuditOpsAccess: (user as any).hasAuditOpsAccess ?? false,
           hasGdprAccess: (user as any).hasGdprAccess ?? false,
+          isServiceAccount: (user as any).isServiceAccount ?? false,
           whatsappNumber: (user as any).whatsappNumber || '',
           telegramUsername: (user as any).telegramUsername || '',
           signalNumber: (user as any).signalNumber || '',
@@ -281,7 +285,9 @@ function UserModal({
           roleIds: [],
           isActive: true,
           hasDeveloperAccess: false,
+    hasAuditOpsAccess: false,
           hasGdprAccess: false,
+          isServiceAccount: false,
           whatsappNumber: '',
           telegramUsername: '',
           signalNumber: '',
@@ -323,7 +329,16 @@ function UserModal({
         roleIds: formData.roleIds,
         isActive: formData.isActive,
         hasDeveloperAccess: formData.hasDeveloperAccess,
+        hasAuditOpsAccess: formData.hasAuditOpsAccess,
         hasGdprAccess: formData.hasGdprAccess,
+        isServiceAccount: formData.isServiceAccount,
+        // Das Kennzeichen senkt die Alarmstufe der Anmeldungen dieses Kontos.
+        // Der Server verlangt dafür eine ausdrückliche Bestätigung; der Haken
+        // im Formular IST diese Bestätigung.
+        // Das Kennzeichen senkt bzw. hebt die Bewertung der Anmeldungen dieses
+        // Kontos. Der Server verlangt in BEIDE Richtungen eine ausdrückliche
+        // Bestätigung; der Haken im Formular ist diese Bestätigung.
+        confirm: 'SERVICE_ACCOUNT',
         whatsappNumber: formData.whatsappNumber || undefined,
         telegramUsername: formData.telegramUsername || undefined,
         signalNumber: formData.signalNumber || undefined,
@@ -358,7 +373,16 @@ function UserModal({
         lastName: formData.lastName,
         roleIds: formData.roleIds,
         hasDeveloperAccess: formData.hasDeveloperAccess,
+        hasAuditOpsAccess: formData.hasAuditOpsAccess,
         hasGdprAccess: formData.hasGdprAccess,
+        isServiceAccount: formData.isServiceAccount,
+        // Das Kennzeichen senkt die Alarmstufe der Anmeldungen dieses Kontos.
+        // Der Server verlangt dafür eine ausdrückliche Bestätigung; der Haken
+        // im Formular IST diese Bestätigung.
+        // Das Kennzeichen senkt bzw. hebt die Bewertung der Anmeldungen dieses
+        // Kontos. Der Server verlangt in BEIDE Richtungen eine ausdrückliche
+        // Bestätigung; der Haken im Formular ist diese Bestätigung.
+        confirm: 'SERVICE_ACCOUNT',
         whatsappNumber: formData.whatsappNumber || undefined,
         telegramUsername: formData.telegramUsername || undefined,
         signalNumber: formData.signalNumber || undefined,
@@ -470,7 +494,7 @@ function UserModal({
         <div>
           <label className="block text-sm font-medium text-gray-700 mb-2">Rollen</label>
           <div className="space-y-2">
-            {roles.filter((role) => !['Developer', 'Kunde', 'DSGVO'].includes(role.name)).map((role) => (
+            {roles.filter((role) => !['Developer', 'Kunde', 'DSGVO', 'Audit-Betrieb'].includes(role.name)).map((role) => (
               <label key={role.id} className="flex items-center gap-2">
                 <input
                   type="checkbox"
@@ -487,6 +511,22 @@ function UserModal({
           </div>
           <label className="block text-sm font-medium text-gray-700 mt-4 mb-2">Zusätzliche Berechtigungen</label>
           <div className="space-y-2">
+            <label className="flex items-start gap-2">
+              <input
+                type="checkbox"
+                checked={formData.isServiceAccount}
+                onChange={(e) => setFormData({ ...formData, isServiceAccount: e.target.checked })}
+                className="mt-1 rounded border-blue-300 text-blue-600 focus:ring-blue-500"
+              />
+              <span>
+                <span className="font-medium">Dienstkonto</span>
+                <span className="block text-sm text-gray-500">
+                  Für Konten, die sich planmäßig und regelmäßig anmelden – etwa das Gegenbuch.
+                  Ihre Anmeldungen erscheinen im Audit-Log als Routine statt als kritisches
+                  Ereignis. Dafür wird gemeldet, wenn ein solches Konto <em>ausbleibt</em>.
+                </span>
+              </span>
+            </label>
             <label className="flex items-center gap-2">
               <input
                 type="checkbox"
@@ -498,7 +538,28 @@ function UserModal({
                 <Shield className="w-4 h-4 text-blue-600" />
                 DSGVO-Zugriff
               </span>
-              <span className="text-sm text-gray-500">(Audit-Logs, Datenschutz)</span>
+              <span className="text-sm text-gray-500">(Audit-Protokoll lesen, Datenschutz)</span>
+            </label>
+            <label className="flex items-start gap-2">
+              <input
+                type="checkbox"
+                checked={formData.hasAuditOpsAccess}
+                onChange={(e) => setFormData({ ...formData, hasAuditOpsAccess: e.target.checked })}
+                className="mt-1 rounded border-amber-300 text-amber-600 focus:ring-amber-500"
+              />
+              <span>
+                <span className="flex items-center gap-1">
+                  <Shield className="w-4 h-4 text-amber-600" />
+                  Audit-Betrieb
+                  <span className="text-sm text-gray-500">(versiegeln, aufräumen, Aufbewahrung)</span>
+                </span>
+                <span className="block text-sm text-gray-500 mt-0.5">
+                  Erlaubt Eingriffe am Audit-Protokoll: Bestandssiegel setzen oder
+                  ersetzen, aufräumen, Aufbewahrungsfristen ändern. Bewusst getrennt
+                  vom DSGVO-Zugriff – wer das Protokoll beaufsichtigt, soll seine
+                  eigene Beweisgrundlage nicht ersetzen können.
+                </span>
+              </span>
             </label>
             <label className="flex items-center gap-2">
               <input

frontend/src/services/api.ts

@@ -1548,11 +1548,12 @@ export const userApi = {
     const res = await api.get<ApiResponse<User>>(`/users/${id}`);
     return res.data;
   },
-  create: async (data: { email: string; password: string; firstName: string; lastName: string; roleIds: number[]; customerId?: number; hasDeveloperAccess?: boolean; hasGdprAccess?: boolean; whatsappNumber?: string; telegramUsername?: string; signalNumber?: string }) => {
+  create: async (data: { email: string; password: string; firstName: string; lastName: string; roleIds: number[]; customerId?: number; hasDeveloperAccess?: boolean; hasGdprAccess?: boolean;
+    hasAuditOpsAccess?: boolean; isServiceAccount?: boolean; confirm?: string; whatsappNumber?: string; telegramUsername?: string; signalNumber?: string }) => {
     const res = await api.post<ApiResponse<User>>('/users', data);
     return res.data;
   },
-  update: async (id: number, data: Partial<User> & { password?: string; roleIds?: number[] }) => {
+  update: async (id: number, data: Partial<User> & { password?: string; roleIds?: number[]; isServiceAccount?: boolean; hasGdprAccess?: boolean; hasDeveloperAccess?: boolean; hasAuditOpsAccess?: boolean; confirm?: string }) => {
     const res = await api.put<ApiResponse<User>>(`/users/${id}`, data);
     return res.data;
   },
@@ -1734,6 +1735,42 @@ export interface AuditLogSearchParams {
   search?: string;
 }
 
+/** Ergebnis der Integritaetspruefung des Audit-Protokolls. */
+export interface IntegrityResult {
+  valid: boolean;
+  checkedCount: number;
+  /** Noch offene Beanstandungen – nur hieran haengt `valid`. */
+  invalidEntries: number[];
+  /** ERNST: Inhalt einer bestehenden Zeile wurde nachtraeglich veraendert. */
+  tamperedEntries: number[];
+  /** Verkettung unterbrochen; die Zeilen selbst koennen unversehrt sein. */
+  chainGaps: number[];
+  /** Luecken ohne protokolliertes Loeschungs-Manifest. */
+  unexplainedGaps: number[];
+  /** Alt-Luecken, die das Bestandssiegel als bereits vorhanden beglaubigt. */
+  attestedGaps: number[];
+  /**
+   * Protokollierte Neuberechnungen der Kette. Nach einem Rehash ist die Kette
+   * zwangslaeufig stimmig - auch ueber Loeschungen hinweg. Die Aussage der
+   * Pruefung reicht dann nur bis zur letzten Neuberechnung zurueck.
+   */
+  rehashes: Array<{
+    id: number;
+    zeitpunkt: string;
+    neuBerechnet: number | null;
+    signiert: boolean;
+    vorbefund: { manipuliert: number; luecken: number } | null;
+  }>;
+  /** Signierte Zeilen, die ohne AUDIT_HMAC_KEY nicht pruefbar sind. */
+  unverifiableEntries: number[];
+  backlogSealStatus: 'kein_siegel' | 'intakt' | 'leer' | 'gebrochen' | 'entfernt' | 'nicht_noetig';
+  backlogTampered: number[];
+  backlogMissing: number[];
+  backlogSealCount: number;
+  tampered: boolean;
+  message: string;
+}
+
 export const auditLogApi = {
   search: async (params?: AuditLogSearchParams) => {
     const res = await api.get<ApiResponse<AuditLog[]>>('/audit-logs', { params });
@@ -1752,7 +1789,7 @@ export const auditLogApi = {
     return res.data;
   },
   verifyIntegrity: async () => {
-    const res = await api.post<ApiResponse<{ valid: boolean; checkedCount: number; invalidEntries: number[]; tamperedEntries: number[]; chainGaps: number[]; tampered: boolean; message: string }>>('/audit-logs/verify');
+    const res = await api.post<ApiResponse<IntegrityResult>>('/audit-logs/verify');
     return res.data;
   },
   rehash: async () => {
@@ -1848,7 +1885,7 @@ export interface EmailLog {
 export type SecurityEventType =
   | 'LOGIN_FAILED' | 'LOGIN_SUCCESS' | 'RATE_LIMIT_HIT' | 'ACCESS_DENIED'
   | 'SSRF_BLOCKED' | 'PASSWORD_RESET_REQUEST' | 'PASSWORD_RESET_CONFIRM'
-  | 'LOGOUT' | 'TOKEN_REJECTED' | 'PERMISSION_CHANGED' | 'SUSPICIOUS';
+  | 'LOGOUT' | 'TOKEN_REJECTED' | 'PERMISSION_CHANGED' | 'AUDIT_SEAL_CHANGED' | 'SUSPICIOUS';
 
 export type SecuritySeverity = 'INFO' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
 

tools/audit-notary/.env.example

@@ -0,0 +1,96 @@
+# ============================================================
+#  Gegenbuch für OpenCRM
+# ============================================================
+# Diese Datei gehört auf den Gegenbuch-Rechner – NICHT auf den CRM-Server.
+#
+# Was hier passiert: Der Rechner holt regelmäßig einen kurzen Kontrollwert von
+# OpenCRM ab und schreibt ihn in ein Buch, das nur hier liegt. Wird später im
+# CRM etwas nachträglich verändert, widerspricht das dem Buch.
+
+
+# ============================================================
+#  Welche Bücher sollen laufen?
+# ============================================================
+# Gültige Werte:  prod  |  staging  |  prod,staging  |  (leer = keins)
+# Genau so geschrieben – nicht "production" oder "test".
+#
+# Nur Staging testen:        COMPOSE_PROFILES=staging
+# Später Prod dazunehmen:    COMPOSE_PROFILES=prod,staging
+# Danach: docker compose up -d   (der laufende Dienst bleibt unberührt)
+COMPOSE_PROFILES=staging
+
+# Steht in den Einträgen des Buchs. Beliebiger Text, nur Kosmetik.
+NOTAR_EMAIL=gegenbuch@example.de
+
+
+# ============================================================
+#  Produktion
+# ============================================================
+# Adresse der OpenCRM-Instanz, von der geholt wird.
+# Gültig: vollständige URL mit https:// und OHNE Schrägstrich am Ende.
+PROD_CRM_URL=https://crm.example.de
+
+# Zugang: ein eigenes Benutzerkonto im CRM, das NUR das Recht "audit:read" hat.
+# Wie man es anlegt, steht in der README unter "Zugang einrichten".
+#
+# Das Gegenbuch meldet sich damit bei jedem Durchlauf selbst an. Ein fest
+# hinterlegtes Token gibt es bewusst nicht – Zugangstoken laufen nach
+# 15 Minuten ab und wären beim nächsten Durchlauf längst ungültig.
+PROD_CRM_EMAIL=gegenbuch@deine-domain.de
+PROD_CRM_PASSWORD=
+
+# Wie oft geprüft wird, in Sekunden.
+# Gültig: ganze Zahl > 0.   Üblich: 3600 (stündlich), 900 (viertelstündlich)
+# Kürzer heißt: kleineres Zeitfenster, in dem eine Änderung unbemerkt bliebe.
+PROD_INTERVAL=3600
+
+# Beim ALLERERSTEN Start einmalig setzen, danach wieder leeren.
+# Gültige Werte:  true  |  (leer)
+# Grund: Die erste Eintragung legt fest, was als Ausgangszustand gilt – das
+# soll nicht versehentlich passieren.
+PROD_GENESIS_ACK=
+
+# Normalerweise leer lassen.
+# Gültige Werte:  true  |  (leer)
+# Nur nötig, wenn das Datenverzeichnis verlorenging (z. B. gelöscht) UND du
+# geklärt hast, warum. Siehe README, Abschnitt "Wenn das Gedächtnis fehlt".
+PROD_ADOPT_ACK=
+
+# Normalerweise leer lassen.
+# Gültige Werte:  die neue Siegelwurzel (mind. 16 Zeichen)  |  (leer)
+# Das Gegenbuch schlägt Alarm, wenn sich die Wurzel des Bestandssiegels
+# ändert – denn ein erneutes Siegeln ersetzt die Grundlage, gegen die
+# Manipulation nachgewiesen wird. War der Wechsel gewollt, hier die Wurzel
+# eintragen, die der Alarm nennt, einmal laufen lassen und wieder leeren.
+# Bewusst KEIN "true": ein stehen gelassener Wert passt beim nächsten
+# Wechsel nicht mehr und kann darum keinen weiteren stillschweigend
+# durchwinken.
+PROD_SEAL_ACK=
+
+# Normalerweise leer lassen.
+# Gültige Werte:  die ID des Rehash-Eintrags  |  (leer)
+# Das Gegenbuch schlägt Alarm, wenn die Hash-Kette neu berechnet wurde. Ein
+# Rehash verknüpft alle Einträge neu – Lücken, die eine Löschung sichtbar
+# gemacht hätten, verschwinden dabei aus der Kette, und die Prüfung im CRM
+# meldet danach wieder „lückenlos". War die Neuberechnung geplant, hier die
+# ID eintragen, die der Alarm nennt, einmal laufen lassen und wieder leeren.
+PROD_REHASH_ACK=
+
+# Wo das Buch liegt – relativ zu diesem Verzeichnis.
+# DIESES VERZEICHNIS GEHÖRT INS BACKUP (enthält Buch und Signaturschlüssel).
+PROD_DIR=./data/prod
+
+
+# ============================================================
+#  Test / Staging
+# ============================================================
+# Gleiche Regeln wie oben, eigenes Konto und eigenes Verzeichnis.
+STAGING_CRM_URL=https://staging.example.de
+STAGING_CRM_EMAIL=gegenbuch@deine-domain.de
+STAGING_CRM_PASSWORD=
+STAGING_INTERVAL=3600
+STAGING_GENESIS_ACK=
+STAGING_ADOPT_ACK=
+STAGING_SEAL_ACK=
+STAGING_REHASH_ACK=
+STAGING_DIR=./data/staging

tools/audit-notary/Dockerfile

@@ -0,0 +1,27 @@
+# Gegenbuch – läuft auf einem EIGENEN Rechner, nicht dort, wo OpenCRM läuft.
+#
+# Der Container holt lesend einen Kontrollwert vom CRM (HTTPS + Token mit
+# audit:read) und legt seine Einträge in einem Git-Repository auf DIESER
+# Maschine ab. Er braucht keinen SSH-Zugang zum CRM, keine Datenbank, keine
+# Shell dort. Umgekehrt kennt OpenCRM dieses Gegenbuch überhaupt nicht.
+FROM node:20-slim
+
+# git für das Buch, openssh-client für die Signaturen (ssh-keygen).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      git openssh-client ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY notary.mjs /opt/notary/notary.mjs
+COPY entrypoint.sh /opt/notary/entrypoint.sh
+RUN chmod +x /opt/notary/entrypoint.sh
+
+# Der Container STARTET als root – aber nur, um die Rechte auf dem
+# Datenverzeichnis geradezuziehen. Danach gibt der entrypoint die Privilegien
+# ab und arbeitet als unprivilegierter Benutzer weiter.
+#
+# Grund: Das Datenverzeichnis kommt als Bind-Mount vom Host. Wer das Projekt
+# als root geklont hat, hat dort root-eigene Verzeichnisse – ein Container, der
+# direkt als UID 1000 startet, kann darin nichts anlegen.
+WORKDIR /gegenbuch
+
+ENTRYPOINT ["/opt/notary/entrypoint.sh"]

tools/audit-notary/README.md

@@ -0,0 +1,737 @@
+# Gegenbuch (externe Notarisierung)
+
+Alle Schutzmechanismen im CRM selbst – Hash-Kette, Versionsgrenze,
+Löschungs-Manifest, Bestandssiegel – liegen in **derselben Datenbank**, die sie
+absichern sollen. Wer dort schreiben kann, sitzt am Ende immer schon auf der
+Ebene, die den Beweis führt. Genau das hat der Pentest über mehrere Runden
+Schicht für Schicht gezeigt.
+
+Das Gegenbuch durchbricht das: Ein **zweiter Rechner** holt regelmäßig einen
+kurzen Kontrollwert vom CRM, prüft ihn gegen seine eigene Historie und schreibt
+ihn signiert fort. Wird später im CRM etwas nachträglich verändert,
+widerspricht das dem Gegenbuch.
+
+## Was du hier suchst
+
+**Einrichten**
+[Betriebsart wählen](#zwei-betriebsarten--erst-hier-entscheiden) ·
+[mit Docker](#einrichten-mit-docker-empfohlen) ·
+[erster Start](#erster-start--drei-schritte) ·
+[Zugangskonto im CRM](#zugang-einrichten-das-brauchst-du-vorher) ·
+[ohne Docker](#einrichten-ohne-docker)
+
+**Im Betrieb**
+[**Altbestand versiegeln**](#den-altbestand-versiegeln-einmalig-im-crm) ·
+[Rückgabecodes](#rückgabecodes) ·
+[Überwachung](#überwachung) ·
+[wo die Daten liegen](#wo-die-daten-liegen)
+
+**Wenn Alarm kommt**
+[Siegelwurzel hat gewechselt](#wenn-sich-die-siegelwurzel-ändert-alarm-und-warum) ·
+[Kette wurde neu berechnet](#wenn-die-kette-neu-berechnet-wurde-ebenfalls-alarm) ·
+[Zurückspulen erkannt](#der-rewind-wächter) ·
+[Gedächtnis fehlt](#wenn-das-gedächtnis-trotzdem-fehlt)
+
+**Zum Nachlesen**
+[was erkannt wird](#was-das-skript-erkennt) ·
+[was nicht – ehrlich](#was-es-nicht-leistet--ehrlich) ·
+[Prüfmodus für Auditoren](#prüfmodus-für-auditoren)
+
+> **Nur schnell versiegeln?** Der Abschnitt
+> [Altbestand versiegeln](#den-altbestand-versiegeln-einmalig-im-crm) ist
+> eigenständig und gilt **auch ohne Gegenbuch** – es ist ein Vorgang im CRM,
+> nicht hier.
+
+## Zwei Betriebsarten – erst hier entscheiden
+
+| | **Lokal** (Normalfall) | **Mit externem Repository** |
+|---|---|---|
+| Das Buch liegt | auf dem Gegenbuch-Rechner | zusätzlich auf einem dritten Server |
+| Aufwand | Docker starten, fertig | privates Git-Repo, Schlüssel, Server-Regeln |
+| Schützt gegen | jemand verändert Daten **im CRM** | zusätzlich: jemand übernimmt den **Gegenbuch-Rechner** |
+
+**Für die allermeisten Installationen ist „lokal" die richtige Wahl.** Der
+Schutz, um den es geht – nachträgliche Änderungen im CRM auffliegen zu lassen –
+steht damit vollständig. Die zweite Variante deckt einen Angreifer ab, der
+zusätzlich den Gegenbuch-Rechner übernimmt; sie kostet spürbar mehr Einrichtung
+und laufende Aufmerksamkeit.
+
+Diese Anleitung beschreibt zuerst den lokalen Betrieb. Alles zur zweiten
+Variante steht gesammelt unter **„Zusätzliche Härtung"** weiter unten – wer
+lokal betreibt, kann diesen ganzen Teil überspringen.
+
+## Die eine nicht verhandelbare Bedingung
+
+**Der Signaturschlüssel und das Push-Recht dürfen nicht in den Deploy-Secrets
+des CRM liegen.** Sonst ist der zweite Schlüssel im selben Zugriffsbereich wie
+der erste – es sieht nach doppeltem Boden aus und ist keiner. Das CRM braucht
+für dieses Verfahren **gar nichts** zu wissen: Es liefert nur einen lesbaren
+Kontrollwert, der keine Geheimnisse enthält.
+
+## Einrichten mit Docker (empfohlen)
+
+Auf dem **Gegenbuch-Rechner** – nicht auf dem CRM-Server:
+
+```bash
+git clone <dieses Repository> opencrm
+cd opencrm/tools/audit-notary
+cp .env.example .env
+# .env ausfüllen: CRM-Adresse und Token eintragen
+docker compose up -d
+```
+
+### Erster Start – drei Schritte
+
+Beim allerersten Lauf meldet der Container `exit=4` und verlangt eine
+Bestätigung. Das ist Absicht: Der erste Eintrag legt fest, was als
+Ausgangszustand gilt.
+
+```bash
+# 1. In der .env freigeben
+STAGING_GENESIS_ACK=true
+
+# 2. Neu starten (kein --build nötig, nur die Umgebung ändert sich)
+docker compose up -d && docker compose logs -f
+#    Erwartet: "OK: Checkpoint 1 erstellt" und exit=3
+#    exit=3 ist hier richtig – beim ersten Mal gibt es nichts zu vergleichen.
+
+# 3. Wieder leeren und erneut starten
+STAGING_GENESIS_ACK=
+docker compose up -d
+```
+
+Ab dem nächsten Durchlauf steht dort `exit=0 (in Ordnung)`.
+
+**Warum Schritt 3 wichtig ist:** Bleibt die Zeile auf `true`, würde der
+Container nach einem Verlust des Datenverzeichnisses stillschweigend eine neue
+Grundlage setzen, statt zu fragen – genau davor schützt die Abfrage.
+
+Für Produktion später dasselbe mit `PROD_GENESIS_ACK`. Schnell nachsehen ohne
+Logs: `cat data/staging/status.txt`.
+
+Beim ersten Start einmalig `PROD_GENESIS_ACK=true` setzen (und danach wieder
+leeren) – die erste Eintragung legt fest, was als Ausgangszustand gilt, und das
+soll nicht versehentlich passieren.
+
+**Zwei Bücher auf einer Maschine** sind vorgesehen: `prod` und `staging` sind
+getrennte Dienste mit getrennten Verzeichnissen und getrennten Schlüsseln.
+Welche laufen, steuert `COMPOSE_PROFILES` in der `.env`.
+
+### Den Altbestand versiegeln (einmalig, im CRM)
+
+Ein CRM, das schon länger läuft, hat fast immer einen **Altbestand** – Einträge
+aus der Zeit, bevor das Protokoll signiert wurde. Solange der nicht versiegelt
+ist, meldet die Prüfung `valid: false`, das Gegenbuch schlägt zu Recht Alarm –
+und, wichtig: **es beglaubigt so lange gar nichts.** Es bricht vor dem Anhängen
+ab, weil ein Checkpoint über einen ungeklärten Zustand diesen mitbeglaubigen
+würde. Ein unversiegeltes CRM ist also nicht „bewacht mit Warnung", sondern
+unbewacht.
+
+Das Siegeln ist **einmalig** und passiert im CRM, nicht hier.
+
+#### Wer darf das
+
+Das Recht `audit:admin`. Das bekommt man über den Haken **„Audit-Betrieb"** in
+der Benutzerverwaltung – **nicht** über die Admin-Rolle (die hat bewusst keine
+Audit-Rechte) und **nicht** über den DSGVO-Haken (der darf lesen, nicht
+eingreifen). Das Gegenbuch-Dienstkonto hat es erst recht nicht.
+
+```bash
+CRM=https://<crm>
+read -s -p "Passwort: " PASS; echo
+AT=$(curl -s -X POST $CRM/api/auth/login -H 'Content-Type: application/json' \
+  -d "{\"email\":\"…\",\"password\":\"$PASS\"}" | jq -r '.data.token')
+curl -s -X POST $CRM/api/auth/login -H 'Content-Type: application/json' \
+  -d "{\"email\":\"…\",\"password\":\"$PASS\"}" | jq -r '.data.user.permissions[]' | grep audit
+```
+
+Muss `audit:read` **und** `audit:admin` zeigen.
+
+#### Erst nachsehen, was du festschreibst
+
+Das Siegel hält den **aktuellen** Zustand fest, samt aller vorhandenen Lücken.
+Wer blind siegelt, beglaubigt womöglich eine Lücke, die von einer Löschung
+stammt. Der Schritt ist praktisch einwegs: Danach ist die Beglaubigung tragend,
+und ein Siegel wieder zu entfernen erzeugt den Zustand `entfernt` – also selbst
+einen Befund.
+
+```bash
+B="Authorization: Bearer $AT"
+curl -s -X POST $CRM/api/audit-logs/verify -H "$B" \
+  | jq '.data | {valid, checkedCount, rehashes, chainGaps, unexplainedGaps,
+                 tamperedEntries, backlogSealStatus}'
+```
+
+Vier Dinge müssen stimmen:
+
+| Feld | Erwartung | Warum |
+|---|---|---|
+| `rehashes` | `[]` | Eine Neuberechnung verknüpft alles neu – danach ist die Kette *zwangsläufig* stimmig, auch über Löschungen hinweg. Steht hier etwas, sagt `chainGaps` nichts über die Zeit davor aus. |
+| `tamperedEntries` | `[]` | Veränderter Inhalt gehört geklärt, nicht beglaubigt. |
+| `chainGaps` | erklärbar | siehe unten |
+| `backlogSealStatus` | `kein_siegel` | sonst ist es kein Erst-Siegeln (siehe nächster Abschnitt) |
+
+**Lücken einordnen.** Sieh dir die betroffenen IDs und ihre Nachbarn an:
+
+```bash
+for id in <lücke-1> <nachbar> …; do
+  printf '%-6s ' "$id"
+  curl -s -o /tmp/r.json -w 'HTTP %{http_code}  ' "$CRM/api/audit-logs/$id" -H "$B"
+  jq -r 'if .success then (.data|"\(.createdAt[0:19])  v\(.hashVersion)  \(.action)/\(.resourceType)") else .error end' /tmp/r.json
+done
+```
+
+> **Den HTTP-Code mit ausgeben, immer.** Zugangstoken laufen nach 15 Minuten ab.
+> Ohne den Code liest sich eine abgelehnte Anfrage (401) wie ein fehlender
+> Eintrag – ein Prüfwerkzeug, das ein verweigertes Lesen als Löschung meldet.
+> Uns ist genau das passiert, mitten in der Vorbereitung eines Prod-Siegels.
+
+Liegen die Lücken jeweils **innerhalb einer Sekunde** zusammen mit ihren
+Nachbarn, betreffen nur `Authentication` und fehlt kein Eintrag, sind es
+Schreibkollisionen aus parallelen Anfragen – harmlos, historisch, nicht mehr
+reproduzierbar. Fehlt dagegen ein Eintrag oder passt eine Lücke nicht in dieses
+Bild: **erst klären, dann siegeln.**
+
+*(Ein abgeschnittener **Anfang** des Protokolls wird seit dem Anfangs-Detektor
+mitgeprüft: Die erste Zeile eines Protokolls trägt einen leeren `previousHash`;
+trägt die erste vorhandene Zeile einen Wert, fehlt eine Vorgängerin. Das
+erscheint als ganz niedrige Lücke und kippt `valid` – du musst es nicht selbst
+suchen.)*
+
+#### Siegeln
+
+```bash
+curl -s -X POST $CRM/api/audit-logs/seal-backlog -H "$B" \
+  -H 'Content-Type: application/json' -d '{"confirm":"SEAL"}' | jq
+```
+
+`SEAL` ist das Erst-Siegeln. Besteht bereits ein Siegel, verlangt der Endpunkt
+stattdessen `RESEAL` – siehe nächster Abschnitt. Notiere `root` aus der Antwort.
+
+#### Danach: drei Punkte gegenprüfen
+
+```bash
+curl -s -X POST $CRM/api/audit-logs/verify -H "$B" \
+  | jq '.data | {valid, chainGaps, attestedGaps, backlogSealStatus, backlogSealCount}'
+
+SID=$(curl -s "$CRM/api/audit-logs?resourceType=AuditBacklogSeal&limit=1" -H "$B" | jq -r '.data[0].id')
+curl -s "$CRM/api/audit-logs/$SID" -H "$B" \
+  | jq '{vorbefund:.data.changesBefore.befund.ketten_luecken, siegel:.data.changesAfter}'
+```
+
+1. `valid: true`, und `chainGaps` = `attestedGaps` = die bekannten Lücken
+2. `backlogSealStatus: "intakt"` – **nicht** `leer`. `leer` heißt: Das Siegel
+   umschließt nichts, es gab keinen Altbestand. Kein Fehler, aber auch keine
+   Zusage.
+3. Die Lücken stehen im `changesBefore.befund.ketten_luecken` des Markers –
+   genau daran hängt die Beglaubigung.
+
+Die Lücken verschwinden also **nicht** aus dem Bericht. Sie zählen nur nicht
+mehr als offener Befund. Jede **neue** Lücke, jede veränderte oder entfernte
+Altzeile und jedes gebrochene Siegel lösen weiterhin sofort Alarm aus.
+
+#### Zuletzt: das Gegenbuch quittieren
+
+Der nächste Lauf meldet **einmal** `exit=2` („Erstmals ein Bestandssiegel
+gesetzt") – erwartet, kein Befund. Wurzel aus `data/<instanz>/status.txt` in
+`PROD_SEAL_ACK` bzw. `STAGING_SEAL_ACK` eintragen, `docker compose up -d`, nach
+dem Lauf mit `exit=0` wieder leeren. Details im nächsten Abschnitt.
+
+Ab da schreibt das Gegenbuch wieder Checkpoints fort – und setzt im selben Lauf
+die Grundlage für die Rehash-Überwachung.
+
+### Wenn sich die Siegelwurzel ändert: Alarm, und warum
+
+Erneutes Siegeln **ersetzt** die Grundlage, gegen die Manipulation nachgewiesen
+wird. Wer eine Altzeile per Datenbankzugriff entfernt und danach neu siegelt,
+bekommt eine passende Wurzel und eine beglaubigte Lücke — und die Prüfung im
+CRM meldet wieder `valid: true`. Der Wechsel der Wurzel ist die einzige Spur
+davon, die eine Maschine sehen kann.
+
+Deshalb ist er ein **Alarm** (exit 2), kein Hinweis. Vorher stand hier eine
+Zeile Prosa, während der Rückgabecode auf 0 blieb — also genau das Muster, das
+wir dem CRM selbst zweimal angekreidet haben.
+
+Der Alarm nennt die alte und die neue Wurzel samt Blattzahl. Ein Sprung von
+`10 Blätter` auf `9 Blätter` sagt sofort, was passiert ist.
+
+**War der Wechsel gewollt** (typisch: dein einmaliges Erstsiegeln), bestätigst
+du ihn mit der Wurzel, die der Alarm ausgibt:
+
+```bash
+# in der .env
+PROD_SEAL_ACK=72062c88a8b6e2b53b30496b483885cd
+
+docker compose up -d          # ein Lauf – die neue Wurzel wird beglaubigt
+PROD_SEAL_ACK=                # danach wieder leeren
+```
+
+Bestätigt wird bewusst **nicht** mit `true`, sondern mit der Wurzel selbst.
+Ein versehentlich stehen gelassener Wert passt beim nächsten Wechsel nicht mehr
+und kann deshalb keinen weiteren Austausch stillschweigend durchwinken.
+
+**War er nicht gewollt**, sieh im CRM nach: das Sicherheits-Ereignis
+`AUDIT_SEAL_CHANGED` (Einstellungen → Monitoring) und die CRITICAL-Zeile zu
+`/api/audit-logs/seal-backlog` im Audit-Protokoll nennen Konto, Zeitpunkt und
+den Befund, der vor dem Siegeln galt.
+
+Im CRM selbst ist erneutes Siegeln zusätzlich gegatet: es verlangt
+`{"confirm":"RESEAL"}` statt `{"confirm":"SEAL"}` — ein Austausch der
+Beweisgrundlage soll nicht dasselbe Wort haben wie das Einrichten.
+
+### Wenn die Kette neu berechnet wurde: ebenfalls Alarm
+
+Ein **Rehash** verknüpft alle Einträge neu. Danach ist die Kette
+zwangsläufig stimmig — auch über Löschungen hinweg, die vorher als Lücken
+sichtbar gewesen wären. Die Reihenfolge `cleanup` → `rehash` macht aus einem
+beschnittenen Protokoll ein scheinbar makelloses, und die Prüfung im CRM meldet
+danach wieder „lückenlos verkettet". Beides braucht nur `audit:admin`, keinen
+Datenbankzugriff.
+
+Genau das ist im Betrieb vorgekommen: Auf einer Testinstanz wurden 3.155
+Einträge gelöscht und anschließend neu berechnet. Die Prüfung war danach grün,
+die 656 Kettenlücken standen nur noch im Vorbefund des Rehash-Eintrags — den
+niemand liest. Das Gegenbuch war der einzige Zeuge.
+
+Deshalb ist eine neue Neuberechnung seit der letzten Beglaubigung ein **Alarm**
+(exit 2). Er nennt Zeitpunkt, Zahl der betroffenen Zeilen und den Befund, der
+unmittelbar davor galt:
+
+```
+ALARM: Die Hash-Kette wurde neu berechnet (1 neuer Vorgang seit der letzten Beglaubigung).
+  zuletzt: 2026-08-26T16:28:25.467Z (Eintrag 13, 9 Zeilen)
+  Befund unmittelbar davor: 1 beanstandet, 1 Lücken
+  …
+  NOTARY_REHASH_ACK=13
+```
+
+**War die Neuberechnung gewollt**, bestätigst du sie mit der genannten ID:
+
+```bash
+# in der .env
+PROD_REHASH_ACK=13
+docker compose up -d
+PROD_REHASH_ACK=          # danach wieder leeren
+```
+
+Auch hier wird nicht mit `true` bestätigt, sondern mit einem Wert, der zum
+Vorgang gehört. IDs steigen streng — ein stehen gelassener Wert passt bei der
+nächsten Neuberechnung nicht mehr.
+
+**Warum ein eigener Melder, wo doch schon der Kettenkopf verglichen wird?**
+Eine Neuberechnung ändert jeden Hash, der beglaubigte Kopf stimmt also
+ohnehin nicht mehr — der Alarm käme auch so. Aber als *Nebenwirkung*, nicht als
+gebaute Warnung: Verschöbe sich der Anker irgendwann, wäre der Melder lautlos
+weg. Und die Meldung hieße „Eintrag wurde verändert" statt „die Kette wurde neu
+berechnet" — die Wirkung statt der Ursache. Deshalb hängt der Alarm an der
+Sache selbst und steht **vor** dem Kopf-Vergleich; nach einer bestätigten
+Neuberechnung wird dieser übersprungen, weil der veränderte Kopf dann die
+erwartete Folge ist.
+
+Ein fehlender beglaubigter Eintrag bleibt davon unberührt und alarmiert immer:
+Bestätigt wird die Neuberechnung, nicht das Verschwinden von Zeilen.
+
+### Zugang einrichten (das brauchst du vorher)
+
+Das Gegenbuch braucht ein **eigenes Benutzerkonto** im CRM – kein Token. Der
+Grund: Zugangstoken laufen nach 15 Minuten ab und wären beim nächsten
+stündlichen Durchlauf längst ungültig. Das Gegenbuch meldet sich deshalb bei
+jedem Lauf selbst an.
+
+Im CRM, als Administrator:
+
+1. **Benutzer anlegen**, z. B. `gegenbuch@deine-domain.de`, mit einem langen,
+   zufälligen Passwort.
+2. Ihm die Rolle **`Gegenbuch`** geben – **nur diese**. Sie bringt genau ein
+   Recht mit: `audit:read`.
+3. Zusätzlich **„Dienstkonto"** ankreuzen. Dann gelten seine Anmeldungen als
+   Routine statt als kritisches Ereignis – und sein *Ausbleiben* wird gemeldet.
+4. E-Mail und Passwort in die `.env` des Gegenbuchs eintragen
+   (`PROD_CRM_EMAIL` / `PROD_CRM_PASSWORD`).
+
+> **Weder den DSGVO- noch den Audit-Betrieb-Haken setzen.** Der DSGVO-Haken
+> gibt zusätzlich Leserechte auf personenbezogene Daten und den Export; der
+> Haken „Audit-Betrieb" gibt `audit:admin` mit `seal-backlog`, `rehash` und
+> `cleanup`. Ein Einbruch auf dieser Maschine hätte damit nicht nur den
+> Wächter, sondern gleich die Mittel, das Bewachte umzuschreiben. Das Passwort
+> steht hier im Klartext in der `.env`; es muss so wenig wert sein wie möglich.
+
+Mit `audit:read` allein kann dieses Konto **nur Prüfwerte lesen** – keine
+Kundendaten, keine Verträge, nichts ändern und nichts versiegeln. Selbst wenn
+die Zugangsdaten abhandenkommen, ist damit nichts anzufangen.
+
+Gegenprobe nach dem Einrichten – **200, dann dreimal 403**:
+
+```bash
+B="Authorization: Bearer $TOKEN"
+curl -s -o /dev/null -w 'checkpoint    %{http_code}\n' https://<crm>/api/audit-logs/checkpoint -H "$B"
+curl -s -o /dev/null -w 'export        %{http_code}\n' https://<crm>/api/audit-logs/export     -H "$B"
+curl -s -o /dev/null -w 'seal-backlog  %{http_code}\n' -X POST https://<crm>/api/audit-logs/seal-backlog -H "$B" -H 'Content-Type: application/json' -d '{}'
+curl -s -o /dev/null -w 'kunden        %{http_code}\n' https://<crm>/api/customers -H "$B"
+```
+
+Der Export gehört ausdrücklich dazu: Er liefert `changesBefore`/`changesAfter`,
+also die vollständigen Vorher/Nachher-Datensätze samt Klartextnamen. Prüfwerte
+lesen und das Protokoll herausziehen sind zwei verschiedene Dinge – deshalb
+hängt der Export an `audit:export`, das die Rolle `Gegenbuch` nicht hat.
+
+Für Produktion und Test jeweils ein eigenes Konto in der jeweiligen Instanz.
+
+> Jede Anmeldung erscheint im Audit-Log der jeweiligen Instanz. Das ist so
+> gewollt: Man sieht, dass das Gegenbuch arbeitet – und wenn es aufhört, fällt
+> auch das auf.
+
+### Wer redet mit wem
+
+```
+Gegenbuch  ──holt lesend──>  OpenCRM      (HTTPS, Konto nur mit audit:read)
+OpenCRM    ─────────────────>  (kennt das Gegenbuch nicht)
+```
+
+Das ist der eigentliche Schutz. Das Gegenbuch **holt** – es lässt sich nichts
+schicken. OpenCRM kennt weder Adresse noch Schlüssel des Gegenbuchs. Wer
+OpenCRM übernimmt, kommt hier nicht heran.
+
+Das Token kann ausschließlich Prüfwerte lesen: keine Kundendaten, keine
+Änderungen. Selbst wenn es abhandenkommt, ist damit nichts anzufangen.
+
+Der Signaturschlüssel wird beim ersten Start **auf dem Gegenbuch-Rechner
+erzeugt** und verlässt ihn nie.
+
+### Wo die Daten liegen
+
+Im Projektverzeichnis, nicht in Docker-Volumes:
+
+```
+tools/audit-notary/data/prod/
+  buch/                 das Gegenbuch selbst (ein Git-Repository)
+  schluessel/           Signaturschlüssel – wird beim ersten Start erzeugt
+  beobachtungen.jsonl   was zuletzt gesehen wurde
+  status.txt            Ergebnis des letzten Durchlaufs
+```
+
+Der Inhalt ist vom Repository ausgenommen – der Signaturschlüssel gehört dort
+nicht hinein.
+
+**Zu Dateirechten:** Der Container startet kurz als `root`, setzt das
+Datenverzeichnis auf den Arbeitsbenutzer um und gibt die Privilegien dann ab.
+Das ist nötig, weil das Verzeichnis vom Host kommt – wer das Projekt als `root`
+geklont hat, hätte sonst ein Verzeichnis, in das der Container nicht schreiben
+darf. Passiert automatisch, du musst nichts tun. Ein anderer Zielbenutzer geht
+über `PUID`/`PGID`. Die Verzeichnisse selbst sind über `.gitkeep` vorhanden, damit
+sie nach einem `git clone` schon existieren und Docker sie nicht als `root`
+anlegt.
+
+**Ins Backup gehört genau dieses Verzeichnis.** Geht es verloren, beginnt die
+Beobachtung von vorn – und der nächste Lauf sagt das ausdrücklich, statt „alles
+gut" zu melden.
+
+### Überwachung
+
+Jeder Durchlauf schreibt seinen Stand nach `data/<instanz>/status.txt`:
+
+```
+2026-08-22T16:49:50+00:00 exit=0 in Ordnung
+```
+
+**Alles außer `exit=0` gehört angesehen.** Wer eine Überwachung hat, greift
+diese Datei ab; wer keine hat, schaut regelmäßig mit `docker compose logs`
+hinein. Ein Alarm, den niemand liest, ist keiner.
+
+### Was dieser Betrieb abdeckt – und was nicht
+
+**Abgedeckt:** Jemand verändert oder löscht nachträglich Einträge im CRM –
+auch mit direktem Datenbankzugriff. Das widerspricht dem Gegenbuch und fällt
+beim nächsten Durchlauf auf.
+
+**Nicht abgedeckt:** Jemand übernimmt den Gegenbuch-Rechner selbst. Dagegen
+hülfe nur eine zusätzliche Ablage außerhalb (z. B. ein privates Git-Repository
+auf einem dritten Server) – das ist vorbereitet, aber für die meisten
+Installationen mehr Aufwand als Nutzen. Die Erfolgsmeldung benennt diese Grenze
+bei jedem Lauf, damit sie nicht in Vergessenheit gerät.
+
+---
+
+---
+
+# Zusätzliche Härtung: externes Repository
+
+> **Alles ab hier gilt nur für die zweite Betriebsart.** Wer das Gegenbuch
+> lokal auf einer eigenen Maschine betreibt – der Normalfall, siehe oben – kann
+> diesen gesamten Abschnitt überspringen. Die Anforderungen darin (Git-Server,
+> Rewind-Sperre, geschützte Refs) beziehen sich auf ein zusätzliches Repository
+> auf einem dritten Server und existieren im lokalen Betrieb nicht.
+
+Sinn der Variante: Beim lokalen Betrieb liegt das Buch auf demselben Rechner
+wie der Signaturschlüssel. Wer diesen Rechner übernimmt, kann beides
+manipulieren. Ein zusätzliches Repository auf einem dritten Server, das nur
+Anhängen erlaubt, schließt auch das – vorausgesetzt, dessen Regeln stimmen.
+
+## Einrichten ohne Docker
+
+Auf einem **anderen** Rechner als dem CRM-Server:
+
+```bash
+git clone git@host:dein/audit-gegenbuch.git
+cd audit-gegenbuch
+
+export CRM_URL=https://crm.example.de
+export CRM_TOKEN=<Access-Token eines Benutzers mit audit:read>
+
+node /pfad/zu/notary.mjs
+```
+
+Als Cronjob, stündlich:
+
+```cron
+0 * * * * cd /pfad/zum/gegenbuch && CRM_URL=https://crm.example.de \
+  CRM_TOKEN=... node /pfad/notary.mjs >> notary.log 2>&1
+```
+
+**Force-Push serverseitig sperren – das ist Pflicht, nicht Empfehlung.**
+
+Konkret muss der Server **non-fast-forward-Pushes verbieten** (Rewind-Schutz),
+nicht nur „irgendeine" Branch-Protection. Der Grund ist nicht offensichtlich:
+
+Das Skript prüft jede Signatur. Aber ein Angreifer mit Force-Push-Recht muss
+gar nichts fälschen – er kann die Reihe schlicht auf einen **älteren, echt
+signierten Stand zurückspulen** und die Datenbank passend kürzen. Alle
+Signaturen bleiben gültig, der Fingerabdruck stimmt, die Nummerierung ist
+lückenlos. Kryptographisch ist daran nichts auszusetzen; es fehlt nur das Ende.
+
+Ein Notar-Rechner, der die höhere Nummer noch lokal kennt, merkt es. Ein
+**frischer Klon merkt es nicht** – und das ist ausgerechnet der Auditoren-Fall.
+
+Deshalb zusätzlich:
+
+```bash
+# Die zuletzt bekannte Nummer mitgeben – dann fällt ein Rewind auch ohne
+# lokalen Zustand auf. Das Skript nennt sie am Ende jedes Laufs.
+NOTARY_MIN_SEQ=42 node notary.mjs --check
+```
+
+## Der Rewind-Wächter
+
+Das Skript merkt sich bei jedem Lauf den beobachteten Remote-Kopf in einer
+Datei **außerhalb des Klons** (Standard `~/.opencrm-notary/beobachtungen.jsonl`,
+per `NOTARY_STATE_FILE` änderbar). Beim nächsten Lauf muss der neue Kopf ein
+Nachfahre des alten sein. Ist er das nicht, wurde zurückgespult – und zwar
+**unabhängig davon, ob es einen serverseitigen Schutz gibt**.
+
+Das ist der Grund, warum hier *kein* Probe-Push stattfindet: Ein solcher Test
+würde die eigene Push-Identität messen, nicht die des Angreifers (Bypass-Rechte
+für Administratoren gehen genau dann auseinander, wenn es zählt), er gälte nur
+für den geprobten Ref, und die bestätigende Beobachtung wäre derselbe Vorgang
+wie der Schaden. Deshalb wird das **Ereignis** erkannt statt die Regel
+abgefragt.
+
+### Das Gedächtnis liegt im Server, nicht nur auf diesem Rechner
+
+Jeder verankerte Checkpoint bekommt zusätzlich einen eigenen unveränderlichen
+Ref `refs/notary/seq-N`. Der überlebt einen Force-Push auf `main`, weil er ein
+**anderer Ref** ist. Damit lässt sich die höchste je existierende Nummer aus dem
+Server rekonstruieren – auch wenn der lokale Beobachtungsspeicher fehlt.
+
+Warum das nötig ist: Läge das Gedächtnis nur lokal, müsste ein Angreifer nach
+einem Zurückspulen bloß diese Datei löschen. Der nächste Lauf meldete dann
+„erste Beobachtung" – **ein einziges** Code-3, das im Alltag neben echten
+Remote-Ausfällen untergeht – und würde anschließend den zurückgespulten Stand
+als Ausgangspunkt übernehmen. Ab da wäre alles dauerhaft grün. Ein gutartiger
+Standardzustand, den ein Angreifer gezielt herstellen kann, ist kein sicherer
+Standardzustand.
+
+> ### ⚠ Ohne serverseitigen Schutz dieser Refs bringt das Verfahren nichts
+>
+> `refs/notary/*` muss auf dem Server **gegen Löschen und Überschreiben**
+> gesperrt sein. Das ist keine Empfehlung, sondern die tragende Voraussetzung –
+> genauso wie die Rewind-Sperre auf `main`.
+>
+> Der Grund ist eine unangenehme Asymmetrie: Das Skript kennt nur den
+> **höchsten noch vorhandenen** Anker, nicht den höchsten je erzeugten. Wer
+> *alle* Anker löscht, fliegt auf (Code 4). Wer nur die **obersten** löscht und
+> einen niedrigeren stehen lässt, senkt damit den Vergleichswert selbst – und
+> in-repo ist das von „gab es nie" nicht zu unterscheiden.
+>
+> **Die Notar-Identität braucht dort eine eng gefasste Ausnahme:** Sie muss
+> `refs/notary/*` **anlegen** dürfen, aber ausdrücklich **nicht löschen oder
+> überschreiben**. Sonst hebelt eine kompromittierte Notar-Identität genau den
+> Schutz aus, um den es hier geht. Server-seitig ist das unterscheidbar – ein
+> `pre-receive`-Hook sieht beim Anlegen die Null-OID als alten Wert:
+>
+> ```sh
+> # refs/notary/*: nur anlegen, niemals ändern oder löschen
+> case "$ref" in refs/notary/*)
+>   [ "$old" = "0000000000000000000000000000000000000000" ] || exit 1 ;;
+> esac
+> ```
+>
+> Deshalb begründen Anker **keine** Unversehrtheit. Sie können ein
+> Zurückspulen *widerlegen* (wenn ein hoher Anker nicht mehr im Kopf steckt),
+> aber nie belegen, dass nichts fehlt. Ein `--check` aus frischem Klon erkennt
+> eine Anker-Löschung **nicht** – es meldet dann Code 3 mit Vorbehalt, nicht 0.
+
+### Wenn das Gedächtnis trotzdem fehlt
+
+Das Skript unterscheidet zwei Fälle – der Unterschied entscheidet alles:
+
+| Lage | Bedeutung | Verhalten |
+|---|---|---|
+| kein Speicher, **keine** notarisierte Historie | echte Erstinbetriebnahme | einmalig `NOTARY_GENESIS_ACK=true`, sonst Code 4 |
+| kein Speicher, **aber** Historie vorhanden | Gedächtnis ging *nach* der Etablierung verloren | **Code 4**, keine stille Übernahme; erst nach `NOTARY_ADOPT_ACK=true` |
+
+Eine Baseline zu setzen heißt „ich verbürge mich, *das* ist der wahre Kopf".
+Dieser Akt wird nicht automatisch wiederholt.
+
+Zwei Konsequenzen für den Betrieb:
+
+- **Die Datei gehört nicht in den Klon** und sollte möglichst auf getrenntem
+  Speicher liegen. Geht sie verloren, beginnt die Beobachtung von vorn – der
+  erste Lauf danach meldet ehrlich „erste Beobachtung", nicht „alles gut".
+- **Der allererste Lauf endet mit Code 3.** Was man nie gesehen hat, kann man
+  nicht vergleichen. Das ist kein Fehler, sondern die ehrliche Auskunft.
+
+**`NOTARY_MIN_SEQ` ersetzt die serverseitige Sperre nicht.** Der Wert ist eine
+*Untergrenze* und immer nur so frisch wie deine letzte Beobachtung. Wer
+stündlich beglaubigt, aber wöchentlich prüft, läuft mit einem Wert herum, der
+um rund 168 hinterherhinkt – ein Zurückspulen in dieses Fenster bliebe
+unbemerkt und der gewaschene Stand würde sogar ausdrücklich bestätigt.
+
+Ist der Rewind-Schutz auf dem Server tatsächlich eingerichtet, bestätige das:
+
+```bash
+NOTARY_REWIND_PROTECTED=true
+```
+
+**Nur diese Zusicherung** blendet den Vorbehalt aus – nicht die bloße Angabe
+einer Zahl. Solange sie fehlt, endet jeder Lauf mit **Code 3** statt 0:
+„nicht abschließend feststellbar". Das ist Absicht, denn ein Cronjob liest den
+Rückgabecode, nicht den Fließtext – ein Hinweis, der nur in der Ausgabe steht,
+erreicht die Überwachung nie.
+
+## Der entscheidende Punkt: es wird tatsächlich geprüft
+
+Die erste Fassung dieses Skripts hat signiert – aber **nie eine Signatur
+geprüft**. Es las seine Wahrheit aus der lokalen Arbeitsdatei. Wer den
+Notar-Rechner beschreiben konnte, hat ihm damit beliebige „beglaubigte"
+Zeilen untergeschoben und einen abgeschnittenen Datenbestand als neue Wahrheit
+festgeschrieben, ohne Alarm. Signieren ohne prüfenden Leser ist wertlos.
+
+Deshalb gilt jetzt:
+
+- Wahrheitsquelle ist der **signierte Commit-Baum** (bevorzugt der Remote-Kopf),
+  nicht die Arbeitsdatei
+- **Jeder** Commit, der das Gegenbuch ändert, muss eine gültige Signatur tragen
+- Weicht die Arbeitsdatei vom signierten Stand ab, wird abgebrochen
+- Geschrieben wird erst nach erfolgreichem, signiertem Commit – scheitert er,
+  wird die Datei zurückgerollt
+
+## Voraussetzungen, die wirklich Voraussetzungen sind
+
+- **`allowed_signers` muss den Notar-Schlüssel enthalten.** Das Skript
+  akzeptiert ausschließlich Signaturen, die git als `G` bewertet – bei
+  SSH-Signaturen heißt das wörtlich „Schlüssel steht in `allowed_signers`".
+  Ein fremder, selbst erzeugter Schlüssel liefert `U` und wird abgelehnt.
+  *(Bei GPG statt SSH liefert auch ein legitimer Schlüssel ohne Ownertrust ein
+  `U` – dann Ownertrust setzen, nicht `U` wieder zulassen.)*
+- **Ein Remote muss erreichbar sein.** Ist er es nicht, bricht das Skript mit
+  Code 3 ab, statt dem lokalen Stand zu glauben. Ein Gegenbuch, dessen
+  beglaubigter Stand sich nicht feststellen lässt, gibt kein grünes Licht.
+- **Genau ein Schlüssel zählt, nicht die ganze Liste.** `allowed_signers` kann
+  mehrere Principals enthalten – ein Kollege, ein Alt-Schlüssel, eine global
+  geteilte Datei. Jeder davon würde sonst als „gültig" durchgehen und könnte
+  das Gegenbuch umschreiben. Deshalb prüft das Skript zusätzlich den
+  **Fingerabdruck** des Signierschlüssels.
+
+  Er wird automatisch aus `user.signingkey` abgeleitet. Lässt er sich nicht
+  bestimmen, bricht das Skript ab – statt stillschweigend die ganze Liste zu
+  akzeptieren. Explizit setzen geht auch:
+
+  ```bash
+  export NOTARY_SIGNER_FINGERPRINT=$(git log -1 --format=%GF)
+  ```
+
+  Wichtig: exakt der `%GF`-Wert (`SHA256:…`), nicht die vollständige Ausgabe
+  von `ssh-keygen -lf`.
+
+## Rückgabecodes
+
+| Code | Bedeutung |
+|---|---|
+| 0 | alles in Ordnung, Checkpoint angehängt (bzw. Prüfung bestanden) |
+| 1 | Betriebsfehler (Konfiguration, Commit oder Push fehlgeschlagen) |
+| 2 | **Befund** – Widerspruch zwischen CRM und Gegenbuch, ungültige Signatur, oder die Wurzel des Bestandssiegels hat sich geändert (`NOTARY_SEAL_ACK`) |
+| 5 | **Anker unvollständig** – die Kette ist gültig, aber `refs/notary/seq-N` fehlt. Reparierbar durch einen Notar-Schreiblauf |
+| 4 | **Wächter-Gedächtnis fehlt** – Erstinbetriebnahme unbestätigt, oder Speicher nach der Etablierung verloren |
+| 3 | beglaubigter Stand nicht abschließend feststellbar – Remote fehlt/unerreichbar, erste Beobachtung, Zurückspulen nicht ausschließbar, **oder** Checkpoint erstellt aber nicht verankert |
+
+Für Cron gilt: **jeder** Code außer 0 gehört gemeldet. Code 2 ist der Alarm,
+Code 3 heißt „ich weiß es nicht" – und das ist ausdrücklich kein Freibrief.
+
+## Prüfmodus für Auditoren
+
+```bash
+node notary.mjs --check
+```
+
+Führt alle Kontrollen aus, **verändert nichts** und braucht kein Schreibrecht –
+auch dann nicht, wenn dabei ein fehlender Anker auffällt. Der wird gemeldet
+(Code 5), nicht repariert; Reparieren ist Sache des Notar-Laufs.
+
+Das ist kein Detail: Die Serversperre für `refs/notary/*` lehnt Schreibzugriffe
+ja gerade ab. Würde der Prüfmodus dort nachtragen wollen, bekäme jeder
+read-only prüfende Auditor dauerhaft einen Fehler auf einer völlig gültigen
+Kette – und könnte ihn nicht beheben.
+
+## Anhängen ist selbst ein Beglaubigungsakt
+
+Ein Schreiblauf erweitert nicht nur die Kette – er signiert damit zugleich über
+alles darunter. Deshalb prüft das Skript **vor** dem Anhängen und verweigert
+es, wenn die Grundlage nicht feststeht. Sonst wäre das Anhängen selbst das
+Waschmittel: eine frische Signatur über einen ungeklärten Vorzustand beglaubigt
+diesen mit.
+
+Ebenso gilt: **erstellt ist nicht verankert.** Klappt der Push nicht, endet der
+Lauf mit Code 3 und der ausdrücklichen Auskunft „erstellt, aber NICHT
+verankert" – niemals mit 0. Der nächste Lauf hält den ungepushten Commit dann
+an, bis er geklärt ist.
+
+## Was das Skript erkennt
+
+| Angriff | Erkennung |
+|---|---|
+| Beglaubigter Eintrag nachträglich verändert | Hash an der beglaubigten Position stimmt nicht mehr |
+| Einträge am Ende abgeschnitten | aktuelle höchste ID kleiner als die beglaubigte |
+| Bestandssiegel verschwunden | vorher beglaubigt, jetzt nicht mehr vorhanden |
+| Gegenbuch selbst gekürzt | Lücke in der fortlaufenden Nummer |
+| **Reihe zurückgespult (Force-Push)** | **Remote-Kopf ist kein Nachfahre des zuletzt beobachteten** |
+| Gegenbuch lokal manipuliert | Arbeitsdatei weicht vom signierten Stand ab |
+| Untergeschobener Commit | Commit ohne gültige Signatur in der Historie |
+| Nie gepushte lokale Commits | Abgleich gegen den Remote-Kopf |
+| Bestandssiegel-Blätter entfernt | beglaubigte Blattzahl auf null gefallen |
+| **Altzeile gelöscht und neu gesiegelt** (Wäsche) | **Wurzel des Bestandssiegels hat gewechselt – `valid` allein bleibt dabei `true`** |
+| Erstmals gesiegelt, ohne dass es jemand veranlasst hat | vorher keine Wurzel beglaubigt, jetzt eine |
+| **`cleanup` + `rehash` ohne erneutes Siegeln** (Wäsche ohne Datenbankzugriff) | **neue Neuberechnung seit der letzten Beglaubigung – `valid` und Kette sind danach makellos** |
+
+Bei jedem dieser Fälle bricht das Skript mit **Exit-Code 2** ab und **hängt
+nichts an** – der manipulierte Zustand wird also nicht als neue Wahrheit
+festgeschrieben. Für Cron heißt das: Exit-Code überwachen, sonst geht der Alarm
+im Log unter.
+
+## Was es nicht leistet – ehrlich
+
+- **Restfenster:** Einträge zwischen dem letzten Kontrollwert und jetzt sind
+  noch nicht beglaubigt und am Ende fälsch- oder kürzbar. Häufigerer Lauf
+  verkleinert das Fenster, beseitigt es aber nicht. Das gilt für jedes
+  periodische Verfahren dieser Art.
+- **Stiller Ausfall:** Läuft der Cronjob nicht mehr, entsteht keine Warnung im
+  CRM – dort ist ja nichts konfiguriert. Der Ausfall muss auf dem
+  Gegenbuch-Rechner überwacht werden (z. B. Alarm, wenn der jüngste Commit
+  älter als zwei Intervalle ist).
+- **`NOTARY_SIGN=false`** existiert nur für Tests ohne hinterlegten Schlüssel
+  und verlangt zusätzlich `NOTARY_INSECURE_ACK=…`. Der Reflex „Cron hakt, also
+  Signatur abschalten" soll bewusst nicht ausreichen – er würde eine
+  ungeschützte Kette festschreiben.
+- **Der Remote-Server muss Force-Push verhindern.** Das Skript prüft die
+  Signaturen, aber wenn jemand die Historie am Server überschreiben kann,
+  ersetzt er auch die signierten Commits durch eigene. Branch-Protection ist
+  Teil des Schutzes, nicht Zubehör.

tools/audit-notary/data/.gitkeep

@@ -0,0 +1,7 @@
+Hier liegen die Gegenbuch-Daten (je Instanz ein Unterverzeichnis):
+
+  data/prod/      Buch, Signaturschlüssel, Beobachtungsspeicher, status.txt
+  data/staging/   dasselbe für die Testinstanz
+
+Der Inhalt wird bewusst NICHT im Repository geführt – er enthält den
+Signaturschlüssel. Dieses Verzeichnis gehört ins Backup.

tools/audit-notary/data/prod/.gitkeep

@@ -0,0 +1,3 @@
+Gegenbuch-Daten der Produktivinstanz.
+Inhalt wird nicht im Repository gefuehrt (enthaelt den Signaturschluessel).
+Dieses Verzeichnis gehoert ins Backup.

tools/audit-notary/data/staging/.gitkeep

@@ -0,0 +1,2 @@
+Gegenbuch-Daten der Testinstanz.
+Inhalt wird nicht im Repository gefuehrt.

tools/audit-notary/docker-compose.yml

@@ -0,0 +1,63 @@
+# Gegenbuch für OpenCRM
+# =====================
+# Gehört auf einen EIGENEN Rechner – nicht dorthin, wo OpenCRM läuft.
+#
+# Richtung der Verbindung (das ist der eigentliche Schutz):
+#   Gegenbuch  ──holt lesend──>  OpenCRM     (HTTPS, Token nur mit audit:read)
+#   OpenCRM    ─────────────────>  (kennt das Gegenbuch nicht)
+#
+# Wer OpenCRM übernimmt, kommt damit nicht an dieses Buch heran. Deshalb holt
+# das Gegenbuch selbst, statt sich etwas schicken zu lassen.
+#
+# Start:
+#   cp .env.example .env     # Werte eintragen
+#   docker compose up -d
+#
+# Zwei Bücher auf einer Maschine sind vorgesehen (Produktion und Test): zwei
+# getrennte Dienste mit getrennten Verzeichnissen und getrennten Schlüsseln.
+# Welche laufen, steuert COMPOSE_PROFILES in der .env.
+
+services:
+  prod:
+    build: .
+    container_name: gegenbuch-prod
+    restart: unless-stopped
+    profiles: ["prod"]
+    environment:
+      INSTANZ: prod
+      CRM_URL: ${PROD_CRM_URL}
+      CRM_EMAIL: ${PROD_CRM_EMAIL}
+      CRM_PASSWORD: ${PROD_CRM_PASSWORD}
+      NOTARY_INTERVAL: ${PROD_INTERVAL:-3600}
+      NOTAR_EMAIL: ${NOTAR_EMAIL:-gegenbuch@localhost}
+      # Nur beim allerersten Lauf einmalig auf true, danach wieder leeren:
+      NOTARY_GENESIS_ACK: ${PROD_GENESIS_ACK:-}
+      # Nur nach geklärtem Verlust des Beobachtungsspeichers, siehe README:
+      NOTARY_ADOPT_ACK: ${PROD_ADOPT_ACK:-}
+      # Nur nach einem GEWOLLTEN Siegelwechsel, mit der neuen Wurzel:
+      NOTARY_SEAL_ACK: ${PROD_SEAL_ACK:-}
+      # Nur nach einer GEWOLLTEN Neuberechnung, mit der ID des Rehash-Eintrags:
+      NOTARY_REHASH_ACK: ${PROD_REHASH_ACK:-}
+    volumes:
+      # Buch, Schlüssel, Beobachtungsspeicher und Statusdatei.
+      # Dieses Verzeichnis ist das Gegenbuch – es gehört ins Backup.
+      - ${PROD_DIR:-./data/prod}:/gegenbuch
+
+  staging:
+    build: .
+    container_name: gegenbuch-staging
+    restart: unless-stopped
+    profiles: ["staging"]
+    environment:
+      INSTANZ: staging
+      CRM_URL: ${STAGING_CRM_URL}
+      CRM_EMAIL: ${STAGING_CRM_EMAIL}
+      CRM_PASSWORD: ${STAGING_CRM_PASSWORD}
+      NOTARY_INTERVAL: ${STAGING_INTERVAL:-3600}
+      NOTAR_EMAIL: ${NOTAR_EMAIL:-gegenbuch@localhost}
+      NOTARY_GENESIS_ACK: ${STAGING_GENESIS_ACK:-}
+      NOTARY_ADOPT_ACK: ${STAGING_ADOPT_ACK:-}
+      NOTARY_SEAL_ACK: ${STAGING_SEAL_ACK:-}
+      NOTARY_REHASH_ACK: ${STAGING_REHASH_ACK:-}
+    volumes:
+      - ${STAGING_DIR:-./data/staging}:/gegenbuch

tools/audit-notary/entrypoint.sh

@@ -0,0 +1,107 @@
+#!/bin/bash
+# Gegenbuch-Schleife: einrichten, dann in festem Takt beglaubigen.
+set -uo pipefail
+
+: "${INSTANZ:?INSTANZ fehlt (z. B. prod oder staging)}"
+: "${CRM_URL:?CRM_URL fehlt – von welcher OpenCRM-Instanz soll geholt werden?}"
+: "${CRM_EMAIL:?CRM_EMAIL fehlt – Dienstkonto im CRM mit dem Recht audit:read}"
+: "${CRM_PASSWORD:?CRM_PASSWORD fehlt – Passwort dieses Dienstkontos}"
+
+INTERVALL="${NOTARY_INTERVAL:-3600}"
+BUCH=/gegenbuch/buch
+SCHLUESSEL=/gegenbuch/schluessel
+export NOTARY_STATE_FILE=/gegenbuch/beobachtungen.jsonl
+export NOTARY_ALLOW_LOCAL=true          # Buch liegt auf dieser Maschine
+export NOTARY_PUSH=false                # es gibt kein Ziel zum Pushen
+
+# --- Rechte geraderuecken, dann Privilegien abgeben ------------------------
+# Laeuft der Container als root, gehoert das Bind-Mount-Verzeichnis vermutlich
+# ebenfalls root (typisch, wenn das Projekt als root geklont wurde). Wir setzen
+# es auf den Arbeitsbenutzer um und starten uns selbst als dieser neu.
+BENUTZER_UID="${PUID:-1000}"
+BENUTZER_GID="${PGID:-1000}"
+if [ "$(id -u)" = "0" ]; then
+  if ! chown -R "$BENUTZER_UID:$BENUTZER_GID" /gegenbuch 2>/dev/null; then
+    echo "[$INSTANZ] HINWEIS: Rechte auf /gegenbuch liessen sich nicht setzen." >&2
+    echo "[$INSTANZ]   Falls es gleich an fehlenden Schreibrechten scheitert, auf dem Host:" >&2
+    echo "[$INSTANZ]   chown -R $BENUTZER_UID:$BENUTZER_GID <datenverzeichnis>" >&2
+  fi
+  exec setpriv --reuid="$BENUTZER_UID" --regid="$BENUTZER_GID" --init-groups \
+       --inh-caps=-all "$0" "$@"
+fi
+
+echo "[$INSTANZ] Gegenbuch startet – Quelle: $CRM_URL, Takt: ${INTERVALL}s"
+
+# --- Signaturschlüssel: einmalig auf DIESER Maschine erzeugen ---------------
+# Er verlässt den Rechner nie. OpenCRM kennt ihn nicht.
+mkdir -p "$SCHLUESSEL"
+if [ ! -f "$SCHLUESSEL/id_ed25519" ]; then
+  echo "[$INSTANZ] Erzeuge Signaturschlüssel..."
+  ssh-keygen -t ed25519 -f "$SCHLUESSEL/id_ed25519" -N "" -C "gegenbuch-$INSTANZ" -q
+fi
+chmod 600 "$SCHLUESSEL/id_ed25519"
+if [ ! -f "$SCHLUESSEL/allowed_signers" ]; then
+  echo "gegenbuch-$INSTANZ namespaces=\"git\" $(cat "$SCHLUESSEL/id_ed25519.pub")" \
+    > "$SCHLUESSEL/allowed_signers"
+fi
+
+# --- Buch anlegen, falls noch nicht vorhanden ------------------------------
+if [ ! -d "$BUCH/.git" ]; then
+  echo "[$INSTANZ] Lege Gegenbuch an..."
+  mkdir -p "$BUCH"
+  git -C "$BUCH" init -q -b main
+fi
+cd "$BUCH" || exit 1
+
+git config user.email "${NOTAR_EMAIL:-gegenbuch@localhost}"
+git config user.name  "Gegenbuch $INSTANZ"
+git config gpg.format ssh
+git config user.signingkey "$SCHLUESSEL/id_ed25519.pub"
+git config gpg.ssh.allowedSignersFile "$SCHLUESSEL/allowed_signers"
+
+# Ein erster Commit, damit es eine Historie gibt, an die angehängt werden kann.
+if ! git rev-parse HEAD >/dev/null 2>&1; then
+  git commit -q -S --allow-empty -m "Gegenbuch $INSTANZ angelegt"
+fi
+
+# --- Schleife ---------------------------------------------------------------
+# Jeder Rückgabecode außer 0 gehört angesehen. Der letzte Stand steht
+# zusätzlich in status.txt, damit eine Überwachung ihn abgreifen kann, ohne
+# Logs zu durchsuchen.
+while true; do
+  ZEIT=$(date -Iseconds)
+  # Ausgabe mitschneiden, um den GRUND in die Statusdatei zu bekommen.
+  #
+  # Vorher stand dort nur das Etikett ("BEFUND"), und das ist fuer jeden
+  # Exit-2 dasselbe - ein echter Widerspruch sieht darin aus wie eine
+  # quittierpflichtige Erstsiegelung. Wer nur die Statusdatei liest, kann
+  # nicht entscheiden, ob er handeln muss. Genau die Sorte Signal, gegen die
+  # dieses Werkzeug gebaut ist.
+  node /opt/notary/notary.mjs > /tmp/lauf.log 2>&1
+  CODE=$?
+  cat /tmp/lauf.log
+  case $CODE in
+    0) LAGE="in Ordnung" ;;
+    1) LAGE="Betriebsfehler (Konfiguration, CRM nicht erreichbar, Commit)" ;;
+    2) LAGE="BEFUND – Widerspruch zwischen CRM und Gegenbuch" ;;
+    3) LAGE="nicht abschliessend feststellbar (u. a. erster Lauf)" ;;
+    4) LAGE="Gedaechtnis fehlt – Bestaetigung noetig, siehe README" ;;
+    5) LAGE="Anker unvollstaendig" ;;
+    *) LAGE="unbekannter Code" ;;
+  esac
+  echo "[$INSTANZ] $ZEIT exit=$CODE ($LAGE)"
+  # Die aussagekraeftigste Zeile mitnehmen, nicht einfach die erste.
+  #
+  # Bei Alarm ist das die ALARM-Zeile. Sonst die Zusammenfassung ("OK: …") -
+  # denn ein Lauf kann davor beilaeufige Hinweise ausgeben (etwa das einmalige
+  # Setzen einer Ueberwachungs-Grundlage), und die verdeckten sonst das
+  # Ergebnis. Erst wenn beides fehlt, die erste Zeile ueberhaupt.
+  GRUND=$(grep -m1 '^ALARM: ' /tmp/lauf.log | sed 's/^ALARM: //')
+  [ -z "$GRUND" ] && GRUND=$(grep -m1 '^OK: ' /tmp/lauf.log)
+  [ -z "$GRUND" ] && GRUND=$(grep -m1 -v '^[[:space:]]*$' /tmp/lauf.log)
+  {
+    printf '%s exit=%s %s\n' "$ZEIT" "$CODE" "$LAGE"
+    [ -n "$GRUND" ] && printf 'Grund: %s\n' "$GRUND"
+  } > /gegenbuch/status.txt
+  sleep "$INTERVALL"
+done