pyramid/docs/SQLCIPHER_MIGRATION.md

# SQLCipher-Migration der `pyramid.sqlite` – Umsetzungsplan (PC-Termin)

> **STATUS 2026-07-06: UMGESETZT (`lib/core/app_database.dart`) und auf
> Windows mit Bernds echter 14-MB-DB praxisgetestet** (Migration gelaufen,
> 23 Tabellen verifiziert, Login/E2EE danach intakt, Neustart öffnet die
> verschlüsselte DB, `flutter test` deckt Migration/Fehlpfade mit echtem
> SQLCipher ab). **Android bleibt UNGETESTET** (Punkt 4 des Testplans unten:
> Migration auf Gerät, Push-Isolate + secure_storage) – erst danach Release
> und Uta. **Abweichung vom Plan unten:** Die Annahme „keine Desktop-Binaries"
> ist seit sqlcipher_flutter_libs 0.6.x überholt – das Plugin baut SQLCipher
> auf Windows/Linux als `sqlite3.dll`/`libsqlite3.so` mit (im Build-Output
> verifiziert). Deshalb ist Phase 1 NICHT Android-only: Windows/Linux
> verschlüsseln ebenfalls, ein Test-Override ist unnötig. iOS/macOS bleiben
> Klartext (SQLCipher-Pod kollidiert mit firebase_messaging, kein Release-Ziel).

## Für Bernd in einfach

Die Datenbank der App (Nachrichten, Zugangs-Token, Verschlüsselungs-Schlüssel)
liegt heute **unverschlüsselt** auf dem Gerät – geschützt nur durch die
Android-App-Sandbox. Ein Angreifer bräuchte Root oder physischen Zugriff mit
Entwickler-Tools, um sie zu lesen. Dieser Plan verschlüsselt die Datei selbst.
Der riskante Teil ist nicht die Verschlüsselung, sondern die **einmalige
Umwandlung bestehender Installationen** (Utas Handy!) – deshalb: erst am PC
mit Testdaten, dann eigenes Gerät, dann erst Release.

**Offene Entscheidung (Frage in PROGRESS.md):** Priorität vor/nach M2?

## Ist-Zustand (verifiziert im Code)

| Stelle | Datei | Factory heute |
|---|---|---|
| Haupt-App Android/iOS | `lib/core/matrix_client.dart:24` | `sqflite_native.databaseFactory` (System-SQLite, **kann kein SQLCipher**) |
| Haupt-App Desktop | `lib/core/matrix_client.dart:27` | `databaseFactoryFfi` (gebündeltes sqlite3) |
| Push-Isolate (nur Android) | `lib/core/background_push.dart` `_buildClient()` | `sqflite_native.databaseFactory` |

- `sqlcipher_flutter_libs ^0.6.8` ist bereits in `pubspec.yaml`, wird nirgends benutzt.
- `flutter_secure_storage ^10` ist bereits da (→ Schlüsselablage im Android Keystore).
- Beide Prozesse öffnen **dieselbe Datei** (`pyramid.sqlite`, WAL-Modus,
  `busy_timeout 5000`).

## Zielarchitektur

1. **Ein gemeinsamer DB-Öffner** `lib/core/app_database.dart` (neues Storage-Modul
   im Sinne von M2): kapselt Factory-Wahl, PRAGMAs, Schlüsselbeschaffung und
   Migration. `matrix_client.dart` und `background_push.dart` rufen NUR noch
   diese Fassade – damit verschwindet auch die heutige Code-Duplikation der
   PRAGMA-Blöcke.
2. **Android:** nicht mehr `sqflite_native`, sondern `databaseFactoryFfi` mit
   SQLCipher-Lib:
   ```dart
   import 'package:sqlite3/open.dart';
   import 'package:sqlcipher_flutter_libs/sqlcipher_flutter_libs.dart';
   open.overrideFor(OperatingSystem.android, openCipherOnAndroid);
   ```
   **Achtung Push-Isolate:** `databaseFactoryFfi` spawnt ein eigenes Isolate –
   im Firebase-Background-Isolate ist das genau die Fallenklasse, an der schon
   `NativeImplementationsIsolate` scheiterte (Kommentar in
   `background_push.dart`). Dort deshalb `databaseFactoryFfiNoIsolate` benutzen.
3. **Schlüssel:** 32 Byte kryptografisch zufällig (`Random.secure()`), hex-kodiert
   in `flutter_secure_storage` unter `db_cipher_key`. Beide Prozesse lesen
   denselben Eintrag. Schlüssel wird bei ERSTER Nutzung erzeugt; existiert schon
   eine verschlüsselte DB, aber kein Schlüssel im Storage → harter Fehler mit
   Klartext-Meldung, NIEMALS still neue DB anlegen (Datenverlust-Regel!).
4. **Öffnen:** `PRAGMA key = "x'<hex>'"` als allererstes Statement
   (`OpenDatabaseOptions(onConfigure: ...)`), danach wie bisher WAL + busy_timeout.
5. **Windows/Linux-Desktop:** `sqlcipher_flutter_libs` liefert dort KEINE
   Binaries. Phase 1 = nur Android verschlüsseln (dort liegt das echte Risiko,
   dort sind die echten Nutzer); Desktop bleibt vorerst Klartext, klar im Code
   kommentiert. Desktop-SQLCipher später als eigener Punkt (eigene DLL bündeln).

## Migration bestehender Klartext-DBs (der heikle Teil)

Reihenfolge beim App-Start, VOR `MatrixSdkDatabase.init`, VOR jedem Push-Zugriff:

1. Erkennung: Datei beginnt mit `SQLite format 3\0` → Klartext → Migration nötig.
   (Verschlüsselte SQLCipher-Dateien haben keinen lesbaren Header.)
2. WAL eindampfen: Klartext-DB kurz normal öffnen,
   `PRAGMA wal_checkpoint(TRUNCATE)`, schließen – sonst verlieren wir Daten,
   die noch in `pyramid.sqlite-wal` liegen.
3. **Backup:** `pyramid.sqlite` → `pyramid.sqlite.premigration` kopieren
   (Bytes, nicht rename). Bleibt bis zum verifizierten Erfolg liegen.
4. Export in NEUE Datei (Original bleibt unangetastet):
   ```sql
   ATTACH DATABASE 'pyramid.enc.sqlite' AS enc KEY "x'<hex>'";
   SELECT sqlcipher_export('enc');
   DETACH DATABASE enc;
   ```
   (läuft über die SQLCipher-FFI-Verbindung auf der Klartext-DB)
5. Verifikation: `pyramid.enc.sqlite` mit Schlüssel öffnen,
   `PRAGMA integrity_check` == ok UND Zeilenzahl einer Kerntabelle
   (z. B. `box_inbound_group_session`, Name gegen matrix-6.2.0
   `matrix_sdk_database.dart:139` verifiziert) identisch mit Original. Schlägt IRGENDWAS
   fehl → `pyramid.enc.sqlite` löschen, App startet normal mit Klartext-DB
   weiter, Fehler in `auth_log.txt`. **Kein Zustand darf die Klartext-DB
   beschädigt zurücklassen.**
6. Tausch: Original + `-wal`/`-shm` löschen, `pyramid.enc.sqlite` →
   `pyramid.sqlite` (rename, gleiche Partition = atomar).
7. `.premigration`-Backup erst nach N erfolgreichen Tagen / manuell löschen
   (Entscheidung Bernd: sonst liegt weiter eine Klartext-Kopie herum –
   Kompromiss: nach 7 Tagen beim Start automatisch löschen).

### Race mit dem Push-Isolate

Kommt ein FCM-Push, während die Haupt-App migriert, würde das Isolate die DB
mittendrin öffnen. Lösung: Marker-Datei `pyramid.sqlite.migrating` vor Schritt 2
anlegen, nach Schritt 6 löschen; `_buildClient()` im Push-Pfad bricht bei
vorhandenem Marker sofort ab (Notification zeigt dann einmalig den
„Neue Nachricht"-Platzhalter – akzeptabel). Zusätzlich erkennt das Isolate
selbst Klartext vs. verschlüsselt am Datei-Header und wählt PRAGMA key
entsprechend – es migriert aber NIE selbst.

## Testplan (PC-Termin, in dieser Reihenfolge)

1. Windows-Build mit Test-Account: Migration Klartext→SQLCipher durchlaufen
   lassen (Desktop kriegt fürs TESTEN die FFI-SQLCipher-Variante per lokalem
   Override, auch wenn Phase 1 sie im Release nicht aktiviert).
2. Kernflow danach: Login erhalten? Alte verschlüsselte Nachrichten lesbar?
   Logout → Neu-Login → immer noch lesbar? (`docs/PC_TESTPLAN.md` Abschnitt 1)
3. Fehlerpfade erzwingen: Migration mit vollem Datenträger / Kill mitten in
   Schritt 4 → App muss mit unversehrter Klartext-DB weiterlaufen.
4. Android-Testgerät (eigenes, NICHT Uta): frische Installation (Neuanlage
   verschlüsselt), dann Update-Szenario (bestehende Klartext-DB migriert),
   dann Push-Test (Isolate liest verschlüsselte DB; secure_storage-Zugriff
   aus dem Background-Isolate explizit verifizieren – bekanntes Risiko).
5. Erst wenn 1–4 grün: Release, Uta informieren (ihr Gerät migriert beim
   ersten Start automatisch; vorher ihr Key-Backup verifizieren!).

## Bewusst NICHT im Scope

- `auth_log.txt`, `SharedPreferences`, Media-Cache bleiben Klartext (keine
  Geheimnisse bzw. nur Cache; einzeln bewerten, falls Bernd es wünscht).
- Passphrase-basierter Schlüssel (Nutzer-Eingabe): bewusst nein – Schlüssel
  liegt im Keystore, gleiche Vertrauensstufe wie der Rest der App-Daten,
  aber Datei-Exfiltration allein reicht dann nicht mehr.