rebreak-monorepo/backend/docs/consent-gap-plan.md

Consent-Gap-Plan — Art. 9 DSGVO Mail-Auto-Delete

Stand: 2026-05-13 Autor: rebreak-backend-agent Status: Implementiert (Backend), TODOs für mo + rebreak-native-ui

---

Was wurde implementiert

Schema (Migration 20260513_art9_consent_log)

Neue Spalten in mail_connections:

• consent_at TIMESTAMPTZ NULL — wann eingewilligt, NULL = "Re-Consent pending"
• consent_version TEXT NULL — z.B. "art9-mail-v1-2026-05-13"
• consent_ip_address TEXT NULL — IP zum Zeitpunkt der Einwilligung

Neue Tabelle consent_logs:

• Append-only Audit-Trail für alle Einwilligungen und Widerrufe
• Wird NIEMALS gelöscht (Beweispflicht Art. 7 Abs. 1 DSGVO)

Backend-Dateien

Datei	Zweck
server/utils/consent-texts.ts	Versionierte Consent-Texte (DE + EN)
server/db/consent.ts	DB-Layer: writeConsentGrant, writeConsentRevoke, getConsentLogsByUser, setMailConnectionConsent
server/api/mail-connections/consent.post.ts	POST /api/mail-connections/consent
server/api/mail-connections/[id].post.ts	POST /api/mail-connections/:id (mit Consent-Gate 412)
server/api/mail-connections/[id].delete.ts	DELETE /api/mail-connections/:id (mit Widerruf-Log)
server/api/user/delete.delete.ts	Erweitert: schreibt Widerruf für alle Connections bei Account-Löschung

Aktuelle Consent-Version

"art9-mail-v1-2026-05-13" — definiert in server/utils/consent-texts.ts.

---

TODO #1 — mo (Mail-Stack / Daemon)

Daemon pausiert Verarbeitung wenn consent_at = NULL

Kontext: Alle Bestandsrows nach Migration haben consent_at = NULL. Das bedeutet "Re-Consent pending". Der Daemon darf für diese Connections KEIN Auto-Delete ausführen bis der User explizit eingewilligt hat.

Implementierung in imap-idle/index.mjs (oder wherever der Scan-Loop läuft):

// Beim Laden einer Connection für den Scan-Loop:
if (!connection.consent_at) {
  log(`[consent] Skipping ${connection.email}: Re-Consent pending (consent_at = NULL)`);
  // Verbindung aus dem aktiven Scan-Pool auslassen — KEIN Fehler, kein Error-State.
  // isActive bleibt true. Wenn User Re-Consent gibt, wird consent_at gesetzt
  // und die Connection beim nächsten Loop-Cycle wieder aufgenommen.
  continue;
}

Checklist:

• mo — imap-idle/index.mjs: consent_at-Check im Connection-Load
• mo — scan.post.ts / scan-internal.post.ts: gleiches Check (On-Demand-Scans)

---

TODO #2 — mo (OAuth Token-Revoke bei Disconnect)

Wenn OAuth-Connections getrennt werden: Token bei Microsoft revoken

Kontext: Wenn authMethod === 'oauth2_microsoft' (Outlook-OAuth, noch nicht live), muss beim Disconnect der Refresh-Token bei Microsoft widerrufen werden.

Placeholder-Comments existieren bereits in:

• server/api/mail-connections/[id].delete.ts (User-Disconnect)
• server/api/user/delete.delete.ts (Account-Löschung)

Implementierung wenn OAuth-Phase startet:

if (conn.authMethod === 'oauth2_microsoft') {
  const refreshToken = decrypt(conn.oauthRefreshToken);
  let revoked = false;
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      await fetch('https://login.microsoftonline.com/common/oauth2/v2.0/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
          grant_type: 'revoke',
          token: refreshToken,
          client_id: process.env.MS_OAUTH_CLIENT_ID,
          client_secret: process.env.MS_OAUTH_CLIENT_SECRET,
        }),
      });
      revoked = true;
      break;
    } catch (e) {
      // Retry
    }
  }
  // Audit-Log: Token-Revoke success/failure
  // Dann trotzdem DB-Row löschen (DSB-Memo Abschnitt 5.1)
}

---

TODO #3 — Datenexport (Art. 15 DSGVO)

consent_logs für den User in den Datenexport aufnehmen

Es gibt aktuell keinen /api/data-export-Endpoint im Backend. Wenn er gebaut wird (separater Sprint), muss er enthalten:

• consent_logs für den User (aus getConsentLogsByUser(userId) in server/db/consent.ts)
• Für jede MailConnection: Provider, verbundene E-Mail-Adresse, Verbindungs-Zeitpunkt, erteilte OAuth-Scopes (lesbar, kein Token-Inhalt), Token-Ablaufdatum

DSB-Memo Abschnitt 5.2 + Hans-Müller-To-Do-Liste Item #6.

---

Frontend-Spec für rebreak-native-ui (UI-Agent)

Re-Consent-Modal (für Bestandsuser)

Trigger: App-Open + Auth-User eingeloggt + mindestens eine MailConnection mit consent_at = NULL (Backend: GET /api/mail/status liefert connections mit consentAt-Feld — Null-Check im Frontend).

Alternativ: neuer Endpoint GET /api/mail-connections/pending-consent der nur die IDs der Connections ohne Consent zurückgibt.

Modal-Inhalt:

• Titel: aus getConsentText("art9-mail-v1-2026-05-13").de (oder .en je nach Locale)
• Zwei Buttons: "Einwilligen" → POST /api/mail-connections/consent, "Verbindung trennen" → DELETE /api/mail-connections/:id

Nach "Einwilligen":

• Pro Connection ein POST /api/mail-connections/consent senden
• Body: { mailConnectionId: "<uuid>", consentVersion: "art9-mail-v1-2026-05-13" }
• Bei 200: Modal schließen, Toast "Einwilligung erteilt"
• Bei 409 (version_mismatch): sollte nicht passieren wenn Frontend aktuelle Version nutzt

ConnectMailSheet — Consent-Gate

Neuer Flow:

1. User gibt Email + Passwort ein
2. Vor dem Abschicken: Consent-Text anzeigen (Checkbox oder expliziter Button)
3. POST /api/mail-connections/:id mit consentVersion im Body
4. Bei 412 (consent_required): Consent-Modal anzeigen (sollte nicht vorkommen wenn Schritt 2 korrekt implementiert ist)
5. Bei 200: Connection verbunden

Der consentVersion-Wert muss das Frontend kennen. Empfehlung: Backend liefert ihn via GET /api/mail/status oder einem neuen GET /api/mail-connections/consent-version- Endpoint. Alternativ: hardcoded im Frontend, aber dann muss er bei jedem Text-Bump synchronisiert werden.

Empfehlung: GET /api/mail-connections/consent-version

Einfacher Endpoint ohne Auth:

GET /api/mail-connections/consent-version
→ { version: "art9-mail-v1-2026-05-13", texts: { de: "...", en: "..." } }

Damit muss das Frontend die Version nie hardcoden. Noch nicht implementiert — als TODO für rebreak-backend falls UI-Agent es braucht.

---

Consent-Text-Bump-Workflow (für künftige DSB-Updates)

1. Hans-Müller gibt neuen Text frei
2. Neuen Eintrag in server/utils/consent-texts.ts hinzufügen
3. CURRENT_ART9_MAIL_VERSION auf neue Version setzen
4. Alle bestehenden Connections mit alter Version bekommen automatisch Re-Consent-Modal (Daemon-Check: connection.consent_version !== CURRENT_ART9_MAIL_VERSION → pausieren)
5. Deploy via GitHub Actions Pipeline

---

Nicht gemacht (explizit aus Scope ausgeschlossen)

• Migration lokal ausgeführt — nein, Pipeline deployt
• Frontend-Änderungen — UI-Agent-Task
• Daemon-Logik angefasst — mo's Domain
• git push — kein User-GO erteilt