docs: README with architecture, security model and test instructions

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

README.md

@@ -5,19 +5,57 @@ Sichere Datenbank für Transaktionen zwischen zwei Personen
 
 Alle Datensätze werden **im Browser** verschlüsselt
 (XChaCha20-Poly1305, Schlüsselableitung per Argon2id aus der Passphrase).
-Der Server sieht ausschließlich Chiffretext.
+Der Server sieht ausschließlich Chiffretext – auch bei vollständiger
+Serverkompromittierung bleiben die Inhalte ohne Passphrase vertraulich.
 
 ## Starten (HTTPS, Dev mit self-signed Zertifikat)
 
 ```bash
 python3 -m venv venv
 ./venv/bin/pip install -r requirements.txt
-./run.sh
+./venv/bin/python run.py
 # → https://127.0.0.1:8443
 ```
 
 Ein selbstsigniertes Zertifikat wird bei Bedarf automatisch erzeugt
-(`certs/`). Im Browser auftretende Zertifikatswarnungen in der
-Entwicklung bestätigen.
+(`certs/`). Zertifikatswarnungen im Browser sind in der Entwicklung
+erwartet und zu bestätigen.
+
+## Tests
+
+```bash
+./venv/bin/python -m pytest backend/test_integrity.py -v   # Integrität/Replay
+node .e2e.mjs  # optional: End-to-End (siehe unten)
+```
+
+## Architektur
+
+| Komponente |Datei | Aufgabe |
+|---|---|---|
+| Speicher | `backend/storage.py` | SQLite, speichert nur Chiffretext (uuid, ciphertext, nonce, salt, version) |
+| API | `backend/app.py` | Flask REST API, Validierung nur von Form/Größe, Versions-Konfliktprüfung |
+| Krypto (Client) | `backend/static/crypto.js` | Argon2id-KDF + XChaCha20-Poly1305, uuid+salt als AEAD-AAD gebunden |
+| UI | `backend/static/ui.js` + `index.html`/`style.css` | Tabelle, Erstellen, Bearbeiten, Löschen; Passphrase bleibt im RAM |
+| Server | `run.py` | HTTPS (self-signed Dev-Zertifikat), DB-Init |
+
+## Sicherheitsmodell
+
+- Passphrase → Argon2id (t=2, m=16 MiB) → 256-Bit-Sitzungsschlüssel,
+  ausschließlich im Browser/im Arbeitsspeicher; niemals am Server.
+- Jeder Datensatz: eigene zufällige 16-Byte-Salt + 24-Byte-Nonce.
+  uuid + salt sind als AEAD-Associated-Data gebunden – Vertauschen oder
+  Um-Salten wird beim Entschlüsseln sicher erkannt.
+- Monotoner Versionszähler pro Datensatz: veraltete Updates/Deletes
+  (Replay alter Stände) → `409`, Duplikate → `409`.
+- Klartexte werden clientseitig nie persistiert; beim Sperren/Beenden
+  wird der Schlüssel verworfen (`wipeKey`).
+- HTTPS (Dev: self-signed; Prod: eigenes Zertifikat hinterlegen).
+
+## Bekannte Grenzen
+
+- Datenverlust (Löschen/Überschreiben) durch Angreifer bleibt möglich –
+  Vertraulichkeit ist geschützt, Verfügbarkeit nicht.
+- Backups der SQLite-Datei enthalten ausschließlich Chiffretext.
+- Backups des Passphrasen-Verlusts = Datenverlust (by design).
 
 Siehe `spezification.txt` für die Anforderungen.