# KI-Shield Proxy v2.2

Chrome-Erweiterung (Manifest V3), die Texte für Claude, ChatGPT und Gemini vor
dem Senden auf personenbezogene Daten (PII) prüfen lässt und erkannte Werte im
Netzwerk-Request durch Pseudonyme ersetzt.

Die Erkennung läuft im KIShieldGuard-Proxy. Der Klartext-Entwurf wird erst beim
Senden TLS-verschlüsselt an den Proxy übertragen. Die optionale Live-Erkennung
ist standardmäßig ausgeschaltet. Antworten werden anhand kurzlebiger lokaler
Mappings im Browser re-identifiziert.

> Die Erkennung ist Best-Effort: Falsch-Negative und Falsch-Positive sind trotz
> 42 unterstützter Schutzarten möglich. Der Schutz ersetzt keine fachliche
> Prüfung bei besonders sensiblen Vorgängen.

## Neu in v2.2

- PDF-Dokumente werden ohne feste Seitenobergrenze vollständig lokal gelesen;
  300 Seiten und mehr sind unterstützt.
- Fehlt auf einer PDF-Seite eine ausreichende Textebene, rendert die Erweiterung
  genau diese Seite lokal und führt Tesseract-OCR aus. Ein OCR-Worker wird für
  das gesamte Dokument wiederverwendet.
- Es gibt keine feste Dateiobergrenze mehr. Große Dateien werden stückweise zum
  lokalen Offscreen-Extraktor übertragen, statt als eine große Browser-Nachricht.
- Umfangreiche Dokumente werden vollständig und verlustfrei in proxy-sichere
  Abschnitte zerlegt. Der Nutzer fügt und sendet jeden Abschnitt selbst.

- Alle 42 PII-Schutzarten sind einzeln schaltbar. Das Ausschalten verlangt eine
  zweite Bestätigung; „Alle 42 aktivieren“ stellt den Vollschutz wieder her.
- Direkter Pausen-/Aktivierungsschalter mit zweiter Bestätigung vor der Pause.
- Sichtbarer Status für Popup, Content-Script und Netzwerk-Hook.
- Live-Erkennung als ausdrückliches Opt-in; standardmäßig erfolgt die Prüfung
  erst beim Senden.
- Kurzlebige Last-Mile-Freigabe: Der Request-Body muss eine zuvor geprüfte
  Textvariante enthalten; die Freigabe läuft nach 12 Sekunden ab.
- Manuell markierte PII kann einem konkreten Typ zugeordnet werden.
- „Nie als PII“-Ausnahmen können direkt im Popup angelegt und einzeln oder
  gesammelt gelöscht werden.
- Ein erkannter Treffer kann im Editor ausdrücklich als Fehlalarm gemeldet
  werden. Übertragen werden nur der ausgewählte Begriff und sein PII-Typ, nie
  automatisch die vollständige Chatnachricht.
- Lokale PDF-, DOCX-, Text- und Bild/OCR-Extraktion mit Seitenfortschritt,
  PDF-OCR-Fallback und Vorschau vor dem Einfügen.
- Conversation-Mappings werden in offenen Tabs nach spätestens 24 Stunden aus
  Content- und Netzwerk-Layer entfernt. Abgelaufene Storage-Einträge werden
  beim nächsten Mapping-Zugriff oder manuell im Popup gelöscht.
- Das Legacy-Modul `engine/license.js` bleibt als inaktives
  Kompatibilitätsartefakt im Paket. Manifest und Runtime referenzieren es nicht.

## Datenfluss

```text
Editor
  │ Klick auf Senden
  ▼
content.js blockiert synchron und fragt background.js
  │ TLS: Klartext + Einstellungen
  ▼
KIShieldGuard-Proxy erkennt und pseudonymisiert
  │ maskierter Text + Treffer
  ▼
content.js zeigt Vorschau und wartet auf Bestätigung
  │ Mapping-ACK + kurzlebige Sendefreigabe
  ▼
injected.js prüft den exakten Plattform-Endpunkt und maskiert den Request-Body
  │
  ▼
Claude / ChatGPT / Gemini erhält den pseudonymisierten Text
```

Der Editor bleibt im Klartext. Der MAIN-World-Netzwerk-Hook ersetzt bekannte
Werte erst im ausgehenden `fetch`-/`XMLHttpRequest`-Body. Antworten werden lokal
zurückübersetzt.

## Komponenten

| Datei | Aufgabe |
|---|---|
| `shared/core.js` | Seiteneffektfreier Kern: 42 Typen, Storage-Regeln, URL-Klassifikation und Freigabeprüfung |
| `content.js` | Send-Block, Bestätigung, Live-Opt-in, Dokumentfluss, Mappings und Re-Identifikation |
| `injected.js` | MAIN-World-Hook für `fetch`, `XMLHttpRequest` und `sendBeacon` |
| `background.js` | Proxy-Client, explizites Fehlalarm-Feedback, Mapping-Rekonstruktion und Offscreen-Lebenszyklus |
| `offscreen.*` | Lokale PDF-/DOCX-/Text-Extraktion und Bild-OCR |
| `popup/` | Zugang, Gesundheitsstatus, Pause, 42 Kategorien und Datenverwaltung |
| `engine/license.js` | Inaktives Legacy-Artefakt; mitgeliefert, aber weder im Manifest noch in der Runtime referenziert |

## Schutzstatus und Kategorien

Ohne gespeicherten `kishield_enabled`-Wert ist der Schutz aus
Abwärtskompatibilitätsgründen aktiv. Das Popup verlangt zwei Klicks, bevor es
`kishield_enabled=false` setzt. Während der Pause bleiben Zugang,
Kategorieauswahl und lokale Daten erhalten; Texte gehen dann unverändert an den
KI-Anbieter.

Alle 42 Kategorien lassen sich einzeln deaktivieren. Jeder Wechsel von aktiv
auf inaktiv verlangt eine zweite Bestätigung und zeigt an, dass passende Werte
danach den KI-Anbieter im Klartext erreichen können. „Alle 42 aktivieren“
stellt die sichere Ausgangslage mit einem Klick wieder her.

## Whitelist und Fehlalarm-Feedback

Begriffe können im Popup direkt zur lokalen „Nie als PII“-Whitelist
hinzugefügt werden. Die Liste wird im Browserprofil gespeichert und bei einer
Erkennung als Ausnahmeeinstellung an den Proxy mitgesendet. Das reine
Hinzufügen im Popup löst keine Feedback-Meldung aus.

Bei einem vom Proxy erkannten Treffer bietet das Auswahlmenü im Editor
„Nie als PII + Fehlalarm melden“ an. Erst dieser ausdrückliche Klick sendet
den ausgewählten Begriff und den aktuellen PII-Typ an
`/api/v1/pii-feedback`. Die vollständige Chatnachricht wird durch diese
Feedback-Funktion nicht übertragen. Der Eintrag landet zur manuellen Prüfung
in der Feedback-Warteschlange; es findet keine automatische Freigabe oder
Modelländerung statt.

## Dokumente

Unterstützt werden textbasierte und gescannte PDF, DOCX, Textdateien und
gängige Bildformate. Die Datei wird im normalen, von der Erweiterung
abgefangenen Upload-Ablauf in einem Offscreen-Dokument lokal verarbeitet:

1. Datei ohne feste Datei- oder Seitenobergrenze in kleinen lokalen Chunks lesen,
2. jede PDF-Seite auslesen und bei fehlender Textebene lokal OCR ausführen,
3. vollständigen Text verlustfrei in sichere Abschnitte zerlegen,
4. Textvorschau anzeigen und den ersten Abschnitt bestätigen,
5. weitere Abschnitte nach dem jeweiligen Senden über den Dokument-Navigator
   einfügen.

Im abgefangenen Standardablauf lädt die Erweiterung die Originaldatei weder zum
KI-Anbieter noch zum KIShieldGuard-Proxy. Nach dem Einfügen durchläuft der
jeweilige extrahierte Abschnitt beim Senden den normalen Proxy-Schutz.
Bilddateien und PDF-Seiten ohne ausreichende Textebene erhalten lokale OCR.

Die Erweiterung besitzt keine feste Datei- oder Seitenbegrenzung. Die reale
Verarbeitungsdauer hängt bei Scan-PDFs von Seitenzahl, Auflösung und dem
verfügbaren Arbeitsspeicher des Geräts ab. Die technische Proxy-Grenze von
45.000 Zeichen gilt weiterhin pro einzelner Chatnachricht; deshalb erzeugt der
Dokumentfluss Abschnitte von höchstens 38.000 Zeichen. Externe Kontext- oder
Upload-Limits von Claude, ChatGPT und Gemini liegen außerhalb der Erweiterung.

## Installation im Entwicklermodus

1. `chrome://extensions/` öffnen.
2. „Entwicklermodus“ aktivieren.
3. „Entpackte Erweiterung laden“ wählen.
4. Diesen Ordner auswählen.
5. Bereits offene KI-Chat-Tabs neu laden.

Mindestversion: Chrome 111.

## Prüfen und Store-Paket bauen

```bash
./build-chrome.sh
```

Das Skript führt die Node-Vertragstests, Syntax- und Manifestprüfung aus,
erstellt aus einer festen Dateiliste ein normalisiertes ZIP in `dist/` und gibt
dessen SHA-256 aus. Es nimmt keine `.env`-, Git-, Test- oder Statusdateien in
das Store-Paket auf.

Einzelne Tests:

```bash
node --test tests/*.test.cjs
```

## Sicherheitsverhalten

Bei aktivem Schutz wird ein Chat-Send blockiert, wenn Proxy, Mapping-ACK oder
kurzlebige Netzwerkfreigabe fehlen. Unlesbare Binär-Uploads werden ebenfalls
blockiert. Bei bewusst aktivierter Pause sind diese Gates ausgeschaltet.

Die Last-Mile-Freigabe bindet einen Request daran, dass er den geprüften
Original- oder Pseudonymtext enthält. Für Plattform-Retries darf dieselbe
Freigabe innerhalb von 12 Sekunden höchstens viermal genutzt werden. Sie
bestätigt nicht, dass die First-Party-Seite keine zusätzlichen strukturellen
Felder oder historischen Chattexte in denselben Body aufgenommen hat.

Bekannte Grenzen:

- Erkennung bleibt Best-Effort.
- WebSockets und Inhalte fremder iframes sind nicht abgedeckt.
- Unbekannte oder künftig geänderte separate Upload-Endpunkte können außerhalb
  der klassifizierten Chat-Endpunkte liegen; sensible Dokumente nur nach
  erfolgreicher lokaler Vorschau weiterverwenden.
- Plattformen ändern DOM und Endpunkte; die Gesundheitsanzeige erkennt einen
  nicht antwortenden Hook, ersetzt aber keine Release-Tests auf echten Konten.
- Ein Browser-Plugin kann nicht verhindern, dass die bereits geöffnete
  First-Party-Seite Editor-Inhalte im DOM liest.

Datendetails und Speicherfristen: [PRIVACY.md](PRIVACY.md). Enthaltene
Drittsoftware: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

© 2026 KI-Shield UG (haftungsbeschränkt), HRB 524511, Amtsgericht Jena.