ANONYMISIERUNG UND SICHERHEITSKONZEPT
======================================

Stand: 2026-01-27
Status: Produktiv (v1.1)

Beschreibt das Sicherheitskonzept fuer den Umgang mit
personenbezogenen Klientendaten im Foerderbericht-System.


GRUNDPRINZIP
============

  Das LLM sieht NIEMALS echte Klientendaten.

  Echte Namen, Geburtsdaten und Adressen werden VOR der LLM-Verarbeitung
  durch Tarnnamen ersetzt. Die Zuordnung (Schluessel) liegt verschluesselt
  auf dem lokalen Rechner — NICHT im Cloud-Speicher.


ANONYMISIERUNGSPROZESS
======================

SCHRITT 1: PROFIL ERSTELLEN
----------------------------
  Eingabe: Echter Name + Geburtsdatum
  Ergebnis: AnonymProfile mit:
    - client_id: "K_xxxx" (fortlaufend)
    - tarnname: Zufaelliger deutscher Vor-+Nachname
    - fake_geburtsdatum: +/- zufaellig verschoben
    - mappings: Dict mit Zuordnungen fuer names, dates, addresses, misc

  Die Mappings enthalten:
    names:     {"Max Mustermann": "Felix Bergmann", "Max": "Felix", ...}
    dates:     {"15.03.2016": "22.07.2016"}
    addresses: {"Musterstr. 5": "Beispielweg 12"}

SCHRITT 2: DOKUMENTE ANONYMISIEREN
------------------------------------
  - Word (.docx): Jeder Paragraph und jede Tabellenzelle wird durchsucht,
    Originalbegriffe werden durch Tarnbegriffe ersetzt
  - PDF (.pdf): Originalbegriffe werden mit schwarzen Balken ueberdeckt
    (PyMuPDF Redaction) — IRREVERSIBEL
  - Text (.txt): Einfache String-Ersetzung

SCHRITT 3: SCHLUESSEL VERSCHLUESSELN
--------------------------------------
  Das AnonymProfile wird als JSON serialisiert und verschluesselt:

    Eingabe:  Passwort (nur im Kopf des Users)
    Ableitung: PBKDF2-HMAC-SHA256, 100.000 Iterationen, 16-Byte Salt
    Schluessel: Fernet-Key (AES-128-CBC mit HMAC-SHA256)
    Speicher:  %LOCALAPPDATA%\BACH\keys\<client_id>.schluessel.enc

  Dateiformat:
    Byte 0-15:  Salt (os.urandom(16))
    Byte 16-N:  Fernet-verschluesselter JSON-String

  WICHTIG: Kein Newline-Delimiter — Salt ist immer exakt 16 Bytes.


SPEICHERKONZEPT
===============

  ┌─────────────────────────────────────────────────────────┐
  │  OneDrive (synchronisiert)                              │
  │  ├── klienten/K_xxxx/                                   │
  │  │   ├── .profil.json    (Metadaten, KEIN Klartext)     │
  │  │   ├── quellen/        (anonymisierte Dokumente)      │
  │  │   └── output/         (generierte Dateien)           │
  │  └── _ready_for_export/  (de-anonymisiert, temporaer!)  │
  └─────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────┐
  │  LOKAL (%LOCALAPPDATA%\BACH\keys\)                      │
  │  └── <client_id>.schluessel.enc  (verschluesselt)       │
  │      Windows Hidden-Attribut gesetzt                    │
  └─────────────────────────────────────────────────────────┘

  Warum lokal?
  - OneDrive synchronisiert automatisch — Schluessel waeren in der Cloud
  - %LOCALAPPDATA% wird NICHT synchronisiert
  - Pro Klient isoliert (kompromittierter Schluessel betrifft nur einen)
  - Hidden-Attribut als zusaetzlicher Schutz gegen versehentliches Loeschen


DE-ANONYMISIERUNG (EXPORT)
==========================

  Ausloeser: bach bericht export <klient-ordner> -p <passwort>

  Ablauf:
  1. Schluessel entschluesseln (Passwort → PBKDF2 → Fernet → JSON)
  2. AnonymProfile wiederherstellen (Mappings)
  3. Output-Dateien nach _prepare_for_export/ kopieren
  4. In jeder .docx/.txt-Datei: Tarnnamen → echte Namen ersetzen
  5. Ergebnis nach _ready_for_export/<Echter_Name>/ verschieben
  6. _prepare_for_export/ aufraeumen

  PDFs werden NICHT de-anonymisiert (Schwaerzung ist irreversibel).
  Sie werden als Kopie in den Export-Ordner uebernommen.


PDF-SCHWAERZUNG
===============

  Technik: PyMuPDF (fitz) Redaction
  - page.search_for(wort): Findet Textposition auf der Seite
  - page.add_redact_annot(rect): Markiert Bereich zum Schwaerzen
  - page.apply_redactions(): Ueberschreibt Text mit schwarzem Balken

  Zusaetzlich: AES-256 PDF-Verschluesselung (pikepdf, R=6)
  - Owner-Passwort = User-Passwort
  - Schuetzt vor Oeffnen ohne Passwort

  WICHTIG: Schwaerzung ist DESTRUKTIV — der Originaltext wird
  physisch entfernt. Es gibt KEINEN Weg zurueck.

  Reihenfolge der Verarbeitung:
  1. Alle sensitiven Begriffe suchen (laengste zuerst)
  2. Schwarze Balken setzen und anwenden
  3. In Temp-Datei speichern (fitz-Einschraenkung)
  4. Optional: pikepdf AES-256 Verschluesselung
  5. Temp-Datei an Originalposition verschieben


BEDROHUNGSMODELL
================

  Angriffsszenario                  Schutz
  ─────────────────────────────     ─────────────────────────────
  Cloud-Speicher kompromittiert     Schluessel liegen LOKAL
  Laptop gestohlen                  Schluessel passwortgeschuetzt
  Passwort vergessen                Kein Recovery (by design)
  LLM-Daten abgefangen              LLM sieht nur Tarnnamen
  OneDrive-Sync liest Keys          Keys ausserhalb OneDrive
  PDF versehentlich geoeffnet       Texte physisch entfernt

  Nicht geschuetzt gegen:
  - Keylogger (Passwort-Eingabe)
  - Aktiver Zugriff auf laufendem System
  - Screenshots waehrend _ready_for_export/ offen ist


EMPFEHLUNGEN
============

  1. _incoming_quarantine/ nach Anonymisierung LEEREN
  2. _ready_for_export/ nach Versand LEEREN oder archivieren
  3. Unterschiedliche Passwoerter pro Klient erhoehen Sicherheit
  4. Regelmaessig pruefen: Liegen Schluessel nur unter %LOCALAPPDATA%?
  5. PDF-Export immer pruefen: Sind alle Namen geschwärzt?
  6. Keine sensiblen Daten in Dateinamen verwenden


TECHNISCHE DETAILS
==================

  Bibliotheken:
    cryptography    Fernet, PBKDF2 (pip install cryptography)
    fitz/PyMuPDF    PDF-Manipulation (pip install PyMuPDF)
    pikepdf         PDF-Encryption (pip install pikepdf)
    python-docx     Word-Dokumente (pip install python-docx)

  Dateien:
    skills/_services/document/anonymizer_service.py  Hauptmodul
    agents/_experts/report_generator/generator.py    ExportPipeline


SIEHE AUCH
==========

  wiki/foerderbericht_system.txt    Systemarchitektur
  wiki/word_template_service.txt    WordTemplateService
  user/buero/foerderplanung/README.txt   User-Anleitung
  docs/CONCEPT_foerderbericht_automation.md  Konzeptdokument
