cuonztech-privacy-chaos-gate 0.2.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,97 @@
+CuonzTech Privacy Chaos Gate (CPCG) — Lizenz / License
+
+Copyright (c) 2026 CuonzTech · Carlo Cuonz. Alle Rechte vorbehalten. / All rights reserved.
+
+Source-available, proprietär. Der Quelltext ist einsehbar, aber nicht frei im Sinne einer
+Open-Source-Lizenz. Gilt ab Version 0.2.1.
+Fassung vom 2026-10-23 (Revision 2). / Revision of 2026-10-23 (revision 2).
+
+HINWEIS ZU FRÜHEREN VERSIONEN
+Die bereits auf npm veröffentlichten Versionen 0.1.0 und 0.2.0 wurden unter der MIT-Lizenz
+veröffentlicht. Für Empfänger dieser Versionen bleiben sie unter MIT. Diese Lizenz gilt für
+Version 0.2.1 und alle späteren Versionen.
+
+
+================================================================================
+DEUTSCH
+================================================================================
+
+1. Was ohne Lizenzschlüssel erlaubt ist
+   Sie dürfen die Software herunterladen, installieren und ausführen, um Websites zu
+   scannen und das Konsolen-Gate (Ergebnis in der Konsole, Exit-Code, JSON-Report) in der
+   CI zu verwenden. Das gilt auch für kommerzielle und interne Zwecke. Ziele auf dem
+   eigenen Rechner (localhost, Loopback) sind immer frei. Frei ist ebenso der lokale
+   Auto-Fix: Patches erzeugen und im eigenen Arbeitsverzeichnis anwenden, ohne Commit und
+   ohne Pull Request.
+
+2. Was eine gültige Lizenz von CuonzTech erfordert
+   a) Erzeugen eines PDF-Reports sowie eines Kundenreports (HTML/Markdown mit --client),
+   b) Auto-Fix als Commit oder Pull Request (Code-Patches in ein Repository schreiben,
+      nicht das lokale Anwenden im Arbeitsverzeichnis).
+   Eine Lizenz erhalten Sie über cuonztech.ch (Pilot, Pro, Agency). Der Umfang der Tarife
+   steht auf der Produktseite und in der Lizenzmail. Die Zahl der Domains je Tarif beruht
+   auf Vertrauen; die Software zählt sie nicht.
+
+3. Was nicht erlaubt ist
+   - Die Software oder Teile davon zu kopieren, zu verkaufen, weiterzugeben,
+     unterzulizenzieren oder als eigenes Produkt oder als Dienstleistung anzubieten,
+     soweit dies über Ziffer 1 hinausgeht.
+   - Lizenzprüfungen, Lizenzschlüssel, Signaturprüfungen oder Hinweise auf diese Lizenz zu
+     entfernen, zu umgehen, zu deaktivieren oder zu fälschen.
+   - Lizenzschlüssel Dritten zugänglich zu machen oder zu veröffentlichen.
+   - Copyright- und Lizenzhinweise zu entfernen.
+   Die Einsicht in den Quelltext begründet kein Recht, ihn zu verändern oder
+   weiterzuverbreiten.
+
+4. Keine Gewährleistung, keine Rechtsberatung
+   Die Software wird «wie besehen» geliefert, ohne Zusicherung der Eignung für einen
+   bestimmten Zweck, der Vollständigkeit der Befunde oder der Konformität einer Website mit
+   dem revDSG, der DSGVO oder anderem Recht. Sie ist ein technisches Hilfsmittel und
+   ersetzt keine Rechtsberatung. Die Haftung ist im gesetzlich zulässigen Rahmen
+   ausgeschlossen, insbesondere für indirekte Schäden und entgangenen Gewinn.
+
+5. Drittkomponenten
+   Die Software verwendet Open-Source-Bibliotheken (zum Beispiel Playwright, Commander, Zod)
+   unter deren jeweiligen Lizenzen. Diese Lizenz ändert sie nicht.
+
+6. Beendigung
+   Verstösse gegen Ziffer 3 beenden die Berechtigung nach Ziffer 1 und 2 ohne weitere
+   Mitteilung.
+
+7. Anwendbares Recht
+   Schweizer Recht. Gerichtsstand ist der Sitz von CuonzTech, soweit zwingendes Recht nichts
+   anderes vorsieht.
+
+8. Kontakt
+   support@cuonztech.ch · https://cuonztech.ch
+
+
+================================================================================
+ENGLISH (short version; the German text above governs in case of doubt)
+================================================================================
+
+Copyright (c) 2026 CuonzTech · Carlo Cuonz. All rights reserved. Source-available,
+proprietary, from version 0.2.1.
+
+Versions 0.1.0 and 0.2.0 were published on npm under the MIT License and remain under MIT
+for their recipients. This license applies to version 0.2.1 and later.
+
+Without a license key you may install and run the software to scan websites and use the
+console gate (console output, exit code, JSON report) in CI, including for commercial and
+internal use. Local targets (localhost, loopback) are always free. Local auto-fix (creating
+and applying patches in your own working directory, without a commit or pull request) is free
+as well.
+
+A valid license from CuonzTech is required for: the PDF report and customer reports (HTML,
+Markdown with --client) and auto-fix as a commit or pull request (writing patches into a repository).
+The number of domains per plan is based on trust and is not counted by the software.
+
+You may not copy, sell, redistribute or sublicense the software, offer it as your own
+product or service, or remove, bypass, disable or forge license checks, license keys or
+license notices. Viewing the source code grants no right to modify or redistribute it.
+
+The software is provided "as is", without warranty of any kind. It is a technical aid, not
+legal advice, and does not guarantee compliance with the Swiss revFADP, the GDPR or any
+other law. Liability is excluded to the extent permitted by law.
+
+Swiss law applies. Contact: support@cuonztech.ch

package/README.md

@@ -9,22 +9,55 @@ läuft erlaubtes Tracking nach dem Akzeptieren korrekt an?
 
 ## Installieren
 
+Voraussetzung: Node.js 20 oder neuer.
+
 ```bash
-pnpm add -D @cuonztech/privacy-chaos-gate
-# oder direkt
-npx @cuonztech/privacy-chaos-gate scan --url https://staging.example.com --license CPCG-…
+# 1. CLI installieren (Befehl: cpcg)
+npm install -g cuonztech-privacy-chaos-gate     # oder im Projekt: npm install -D cuonztech-privacy-chaos-gate
+
+# 2. Prüf-Browser installieren (einmalig pro Rechner)
+npx playwright install chromium
+
+# 3. Ersten Scan starten (Scan und Konsolen-Gate brauchen keine Lizenz)
+cpcg --url https://staging.example.com
 ```
 
-## Lizenz
+Ohne Installation: `npx cuonztech-privacy-chaos-gate --url https://staging.example.com`
+(der Browser aus Schritt 2 muss trotzdem vorhanden sein; auf Linux-CI zusätzlich mit Systembibliotheken:
+`npx playwright install --with-deps chromium`). Fehlt der Browser, meldet das CLI das und beendet sich mit Exit 3.
+
+Das CLI hat keine Subcommands: alle Angaben sind Optionen von `cpcg`.
 
+## Lizenz und Preise
+
+Das Paket ist proprietär und source-available (Datei `LICENSE`, ab 0.2.1; die Versionen 0.1.0 und 0.2.0 wurden unter MIT veröffentlicht und bleiben es).
 Online-Kauf → Code per Mail.
 
 ```bash
-export CPCG_LICENSE="CPCG-…"
-cpcg scan --url https://staging.example.com --jurisdiction CH
+export CPCG_LICENSE="CPCG-…"      # Lizenzcode (Pilot/Einmal) oder Kunden-Key CPCG-K-… (Abo)
+cpcg --url https://staging.example.com --jurisdiction CH
 ```
 
-Ohne Lizenz: localhost/Test-Fixtures; Produktiv-URLs mit Warnung (Trial-Modus).
+In CI die Lizenz als Secret setzen und per Umgebungsvariable `CPCG_LICENSE` übergeben, nicht als Argument.
+
+**Frei, ohne Lizenz** (auch kommerziell und intern, auch gegen Produktiv-URLs): Scan, Konsolen-Gate (Exit-Code, JSON-Report, neutraler Evidence-Report ohne Kundenbezug), lokales `--auto-fix` ohne Commit/PR. Ziele auf `localhost`, `127.0.0.1` und `::1` sind immer frei.
+
+**Nur mit gültiger Lizenz:**
+
+| Funktion | Option |
+|----------|--------|
+| PDF-Report sowie Kundenreport (HTML/Markdown mit `--client`) | `--report-pdf`, `--client` |
+| Auto-Fix als Commit oder Pull Request | `--git-commit`, `--create-pr` |
+
+Ohne Lizenz werden diese Funktionen mit einem Hinweis übersprungen; der Exit-Code bleibt der des Gates. Exit 2 gibt es nur bei einer **ungültigen, abgelaufenen oder gesperrten** Lizenz, nicht bei fehlender Lizenz und nicht bei einem nicht erreichbaren Lizenzserver.
+
+| Plan | Preis (netto, CHF) | Umfang |
+|------|--------------------|--------|
+| Pilot / Evidence | 890 einmalig | Kundenreport, Auto-Fix-PR, 1 Domain, 90 Tage |
+| Pro | 69 je Domain und Monat | Kundenreport, Auto-Fix-PR, GitHub Action und CLI-Lizenz |
+| Agency | 349 je Monat | Pro für bis zu 10 Domains |
+
+Die Domain-Anzahl beruht auf Vertrauen: das CLI zählt Domains nicht. Scans werden nicht gezählt. Monatlich kündbar. Kauf und Fragen: `support@cuonztech.ch`.
 
 ## Was das Tool prüft
 
@@ -61,32 +94,104 @@ JustRelate, Didomi, Axeptio, Sourcepoint, Consentmanager, Borlabs, Klaro.
 Jeder Scan schreibt ein Evidence-Paket:
 
 ```
-report.json          LeakReport (maschinenlesbar)
-report-evidence.md   Kunden-Report (Markdown)
-report-evidence.html Kunden-Report (HTML, CuonzTech-Brand)
-evidence/            Screenshots (portabel, relative Pfade)
-report-deluxe.pdf    Deluxe-PDF mit Deckblatt (mit --report-pdf)
+reports/privacy-chaos-report.json           LeakReport (maschinenlesbar), Pfad per --report-output
+reports/privacy-chaos-report-evidence.md    Evidence-Report (Markdown); mit Lizenz und --client als Kundenreport
+reports/privacy-chaos-report-evidence.html  Evidence-Report (HTML, CuonzTech-Brand); mit Lizenz und --client als Kundenreport
+reports/privacy-chaos-report-deluxe.pdf     Deluxe-PDF mit Deckblatt (mit --report-pdf, nur mit Lizenz)
+reports/evidence/                           Screenshots (portabel, relative Pfade)
 ```
 
-Der Report führt **Befunde** (Regelverstösse) und **beobachtete Requests**
+Die Dateinamen richten sich nach dem JSON-Pfad: `<name>.json` ergibt `<name>-evidence.md`, `<name>-evidence.html`
+und `<name>-deluxe.pdf` im selben Ordner, die Screenshots liegen in `evidence/` daneben. Standard ist
+`reports/privacy-chaos-report.json`; mit `--report-output reports/scan.json` heissen die Dateien `reports/scan-evidence.md` usw.
+
+Der Report führt **Befunde** (Regelverstösse), **Hinweise** und **beobachtete Requests**
 (Timelines) getrennt — und ordnet jedes Ergebnis mehreren Rechtsräumen zu
 (CH, EU, UK, US-CA, BR, ROW). Keine globale Compliance-Aussage.
 
+**Hinweise sind kein Blocker.** Rein funktionale Drittanbieter (etwa Google Fonts) erscheinen
+als Hinweis und blockieren das Gate nicht. Mit `--strict` blockieren auch Hinweise.
+Bekannte, bewusst akzeptierte Befunde lassen sich mit `--ignore` ausnehmen; sie stehen im Report weiterhin
+als «ignoriert».
+
 ## Flags
 
 ```bash
-cpcg scan \
-  --url https://staging.example.com \
-  --license CPCG-… \
-  --report-pdf            # Deluxe-PDF (Deckblatt + Evidence) erzeugen
-  --client "Firma AG"     # Kundenname fürs Deckblatt
-  --demo                  # Report als synthetische Testdaten kennzeichnen
-  --jurisdiction CH       # CH | EU | UK | US-CA | BR | ROW
-  --auto-fix true         # Auto-Fix generieren
-  --fail-on-leak true     # Exit 1 bei Leaks (CI-Gate)
+cpcg --url https://staging.example.com \
+  --report-pdf \
+  --client "Firma AG" \
+  --jurisdiction CH \
   --report-output reports/scan.json
 ```
 
+| Option | Wirkung |
+|--------|---------|
+| `--url <url>` | Ziel (Pflicht) |
+| `--license <code>` | Lizenzcode oder Kunden-Key; besser per Env `CPCG_LICENSE` |
+| `--jurisdiction <code>` | `CH`, `EU`, `UK`, `US-CA`, `BR` oder `ROW` |
+| `--report-output <pfad>` | JSON-Report (weitere Dateien daneben) |
+| `--report-pdf [boolean]` | Deluxe-PDF (Deckblatt + Evidence) — Lizenz erforderlich |
+| `--client <name>` | Kundenname für Kundenreport und Deckblatt — Lizenz erforderlich |
+| `--demo [boolean]` | Report als synthetische Testdaten kennzeichnen |
+| `--fail-on-leak [boolean]` | Exit 1 bei Leaks (CI-Gate, Standard `true`) |
+| `--fail-on-uncheckable [boolean]` | Exit 4, wenn Kernszenarien nicht prüfbar sind (Standard `true`); bei `false` Exit 0, das Ergebnis bleibt als unvollständig markiert |
+| `--strict [boolean]` | Auch Hinweise (z. B. Google Fonts) blockieren das Gate (Standard `false`) |
+| `--ignore <liste>` | Befunde ausnehmen: Tracker-Name oder Host-Muster, kommagetrennt oder mehrfach (`fonts.googleapis.com,*.hotjar.com`); im Report als «ignoriert». `*`/`**` und nackte TLDs (`com`, `ch`) werden **immer** abgelehnt, auch mit `--allow-broad-ignore` (zum Abschalten der Blockierung dient `--fail-on-leak false`); ganze Zonen (`*.com`, `.ch`) nur mit `--allow-broad-ignore`. Die Konsole nennt, wie viele Befunde ausgenommen wurden; ein Szenario, dessen Befunde alle ausgenommen sind, steht als «bestanden (Befunde ignoriert)» |
+| `--allow-broad-ignore [boolean]` | Ganze Zonen als `--ignore`-Muster (`*.com`, `*.co.uk`, `.ch`) bewusst zulassen; sie erscheinen in Konsole und Report als Warnung. `*` und nackte TLDs bleiben abgelehnt (Standard `false`) |
+| `--accept-selector <css>` | Eigener Selektor des Akzeptieren-Buttons, wenn die Erkennung ihn nicht findet (mehrfach oder kommagetrennt) |
+| `--reject-selector <css>` | Eigener Selektor des Ablehnen-Buttons |
+| `--settings-selector <css>` | Eigener Selektor des Einstellungen-Buttons |
+| `--banner-frame <teilstring>` | Teil der URL des iframes, in dem der Banner liegt (CMP im Frame); findet der Scan keinen solchen Frame, warnt er |
+| `--banner-wait <sekunden>` | Wartefenster auf einen spät erscheinenden Banner, 1 bis 60 (Standard 8; Umgebung `CPCG_BANNER_WAIT`). Mit Angabe wird das Fenster ausgeschöpft, ebenso bei `--accept-selector`/`--reject-selector`; die Schlussprüfung wartet zusätzlich eine Nachfrist |
+| `--max-subpages <n>` | Obergrenze der Unterseiten-Stichprobe (Szenario `subpage-spa`), 1 bis 40 (Standard 12; Umgebung `CPCG_MAX_SUBPAGES`); das Zeitbudget wächst moderat mit (45 s bis 12, 90 s bis 24, sonst 120 s) |
+| `--auto-fix [boolean]` | Patches erzeugen und im Quellverzeichnis anwenden (Standard `true` nur mit ausdrücklichem `--source-dir`) |
+| `--source-dir <dir>` | Quellcode für Auto-Fix; ein nicht vorhandenes Verzeichnis ist ein Fehler (Exit 3). Für `--git-commit`/`--create-pr` gilt das Git-Repository, in dem es liegt (nicht das Arbeitsverzeichnis) |
+| `--git-commit [boolean]` | Fix in den Git-Branch committen — Lizenz erforderlich |
+| `--create-pr [boolean]` | Fix als Pull Request öffnen (Token in Env `GITHUB_TOKEN`, ersatzweise `--github-token`) — Lizenz erforderlich; hat Vorrang vor `--git-commit` |
+| `--base-branch <branch>`, `--branch-prefix <prefix>` | Basisbranch und Branch-Präfix des Fix-PRs |
+| `--llm-remediation [boolean]` | Opt-in: Quellcode darf an den LLM-Anbieter gesendet werden (Standard `false`) |
+| `--llm-provider`, `--llm-model`, `--api-key` | Nur `openai` ist umgesetzt; andere Anbieter fallen auf die Regel-Engine zurück |
+| `--headless [boolean]`, `--timeout-ms <ms>` | Browser-Modus und Timeout je Szenario-Navigation |
+
+Alle Optionen und Standardwerte: `cpcg --help`.
+
+**Exit-Codes** (für CI): `0` ok · `1` Leaks gefunden (auch wenn ein Fix nur vorgeschlagen, aber nicht verifiziert ist) ·
+`2` Lizenz **ungültig, abgelaufen oder gesperrt** (eine fehlende Lizenz oder ein nicht erreichbarer Lizenzserver ist kein Exit 2) ·
+`3` Fehler (Ziel unerreichbar oder HTTP 4xx/5xx, Konfiguration, Browser fehlt, falsche Argumente) ·
+`4` unvollständig, Kernszenarien nicht prüfbar.
+Ein Lauf, der nichts abschliessend prüfen konnte, ist nie grün: `--fail-on-uncheckable` (Standard) macht daraus Exit 4.
+
+### Unterseiten-Stichprobe
+
+Das Szenario `subpage-spa` prüft höchstens `--max-subpages` verlinkte Unterseiten (verschiedene erste Pfadsegmente zuerst, Impressum und Datenschutz zuletzt). Sind mehr Unterseiten verlinkt als geprüft wurden, steht das nicht nur im Report: Die Konsole meldet «Unterseiten: X von Y geprüft — nicht geprüfte Routen können Verstösse enthalten; --max-subpages erhöhen», `report.json` führt es unter `gate.sampling`, die Step-Summary und der Report-Kopf zeigen «PASS, aber Stichprobe», und `gate.incomplete` ist `true`. Der Exit-Code bleibt bei PASS `0` (nicht `4`).
+
+### Banner nicht gefunden: Selektoren und Frames
+
+Findet die Erkennung den Banner oder einen Button nicht, wird das Szenario «nicht prüfbar» (nie grün). Dann helfen die Overrides:
+
+```bash
+cpcg --url https://staging.example.com \
+  --accept-selector "#meine-zustimmung" \
+  --reject-selector "button[data-consent=reject]" \
+  --settings-selector ".cookie-einstellungen" \
+  --banner-frame "consent.mein-cmp.example"
+```
+
+Erscheint der Banner erst spät, verlängert `--banner-wait <sekunden>` das Wartefenster (Standard 8 s). Der Scan behauptet «kein Banner» nur, wenn die Seite stabil lud und die Schlussprüfung das Fenster samt Nachfrist ohne Banner-Hinweis durchlief. Sonst steht eine eigene Meldung: «Banner erschien nach dem Wartefenster — mit --banner-wait erhöhen», «Banner vorhanden, aber nicht über Ablehnen/Akzeptieren bedienbar» (zum Beispiel nur ein Schliessen-Kreuz) oder «Seite instabil (Reload-Schleife) — Banner nicht auswertbar».
+
+## Auto-Fix: Grenzen und Consent-Anbindung
+
+`--auto-fix` verschiebt Tracker-Skripte hinter die Einwilligung. Das Ergebnis ist ein Vorschlag, den die Review-Stufe prüft;
+ein nicht verifizierter Fix macht das Gate nicht grün.
+
+- **OneTrust und Cookiebot** werden automatisch gelesen (Kategorien Statistik und Marketing); ein Hook ist nicht nötig. OneTrust wird auch ohne CDN-Marker erkannt, etwa bei selbst gehostetem SDK (`Optanon…`-Symbole, `OptanonConsent`-Cookie).
+- **Eigene Banner** melden die Einwilligung an die eingefügte Runtime, zum Beispiel `window.cpcgGrantConsent("analytics")` (Statistik) oder `window.cpcgGrantConsent("marketing")`, ohne Argument alle Kategorien. Der Report nennt die passenden Hooks. Ohne dieses Signal startet kein Tracker; «Ablehnen» ruft nichts auf.
+- **Andere Consent-Plattformen** (zum Beispiel Usercentrics, Sourcepoint, Didomi, iubenda) sind **nicht automatisch behebbar**: der Auto-Fix kann ihre Kategorie-Einwilligung nicht sicher lesen und erzeugt keinen Patch, sondern eine Anleitung zur manuellen Behebung.
+- **Tracker, die nicht im Quelltext stehen** (über Tag Manager, Server, CMS oder Drittanbieter geladen) bleiben «manuell zu beheben».
+- **LLM-gestützte Patches** sind ein Opt-in (`--llm-remediation`), nur mit OpenAI umgesetzt, und senden den Quellcode an den Anbieter. Ein API-Key allein genügt nicht und sendet nichts.
+- **Commit und Pull Request** (`--git-commit`, `--create-pr`) brauchen eine Lizenz; das lokale Anwenden der Patches nicht. Git läuft im Repository, in dem `--source-dir` liegt; liegt es in keinem, bleibt der Fix lokal und der Lauf meldet das ausdrücklich.
+- **Teilfix:** Bleiben gemeldete Tracker offen, zählt das Gate nur diese als «ungepatcht»; Score und «Passed» des Review-Agenten gelten dann ausdrücklich nur für den gepatchten Teil.
+
 ## Demo-Portal
 
 Reproduzierbare Testseite mit fünf absichtlichen Consent-Leaks
@@ -94,16 +199,19 @@ Reproduzierbare Testseite mit fünf absichtlichen Consent-Leaks
 
 ```bash
 node demo-portal/server.mjs     # http://127.0.0.1:8787
-pnpm exec tsx scripts/scan-demo-portal.mts   # voller Scan + Report
-pnpm exec tsx scripts/make-deluxe-report.mts # Deluxe-PDF daraus
+npx tsx scripts/scan-demo-portal.mts    # voller Scan + Report
+npx tsx scripts/make-deluxe-report.mts  # Deluxe-PDF daraus
 ```
 
+Die Skripte in `scripts/` sind TypeScript: `node scripts/x.mts` scheitert an den Importen, deshalb `npx tsx`.
+
 Erwartet: Gate **BLOCKED**, Szenarien «auffällig» — exakt dieselben Zahlen bei jedem Lauf.
 
 ## GitHub Action
 
 ```yaml
 - uses: cuonztech/privacy-chaos-gate@v1
+  id: cpcg
   with:
     staging-url: ${{ vars.STAGING_URL }}
     license: ${{ secrets.CPCG_LICENSE }}
@@ -111,7 +219,57 @@ Erwartet: Gate **BLOCKED**, Szenarien «auffällig» — exakt dieselben Zahlen
     client-name: "Firma AG"
 ```
 
-Die Action nutzt `dist/cli.js` aus dem Action-Path; erst bei fehlendem Build greift `npx`.
+Die Action installiert das veröffentlichte Paket `cuonztech-privacy-chaos-gate` in der Version, die in `action.yml`
+fest eingetragen ist (`npm install --ignore-scripts`, ohne Secrets in der Umgebung dieses Schritts), samt dem passenden
+Chromium (`playwright install --with-deps chromium`). Nur wenn im Action-Pfad ein eigener Build (`dist/cli.js`) liegt,
+etwa im CI dieses Repos, wird dieser verwendet. Kennt die installierte CLI eine angeforderte Option nicht, gibt die Action
+eine Warnung aus, statt sie still wegzulassen.
+
+Scan und Konsolen-Gate laufen ohne Lizenz. `report-pdf`, `client-name`, `git-commit` und `create-pr` brauchen eine gültige Lizenz;
+ohne sie werden sie mit Hinweis übersprungen.
+
+| Input | Standard | Bedeutung |
+|-------|----------|-----------|
+| `staging-url` | Pflicht | Zu prüfende URL |
+| `license` | leer | Lizenzcode oder Kunden-Key; wird nur per Umgebungsvariable `CPCG_LICENSE` übergeben |
+| `fail-on-leak` | `true` | Build blockieren (Exit 1), wenn Leaks bleiben |
+| `fail-on-uncheckable` | `true` | Build blockieren (Exit 4), wenn Kernszenarien nicht prüfbar sind |
+| `strict` | `false` | Auch Hinweise (z. B. Google Fonts) blockieren das Gate |
+| `ignore` | leer | Befunde ausnehmen (Tracker-Name oder Host-Muster, eine Angabe je Zeile oder kommagetrennt) |
+| `accept-selector`, `reject-selector`, `settings-selector` | leer | Eigene CSS-Selektoren der Banner-Buttons (eine Angabe je Zeile) |
+| `banner-frame` | leer | Teil der URL des iframes mit dem Banner |
+| `auto-fix` | `false` | Patches auf dem Runner erzeugen und anwenden; ein Gate ändert Dateien nicht stillschweigend |
+| `create-pr` | `false` | Fix als Pull Request öffnen (braucht `auto-fix: true`, `github-token` und eine Lizenz) |
+| `github-token` | leer | Token für `create-pr` (`contents: write`, `pull-requests: write`) |
+| `git-commit` | `false` | Fix in den ausgecheckten Branch committen (braucht `auto-fix: true` und eine Lizenz) |
+| `target-source-dir` | `.` | Quellcode-Verzeichnis für Auto-Fix |
+| `report-output` | `reports/privacy-chaos-report.json` | Pfad des JSON-Reports |
+| `report-pdf`, `client-name` | `false`, leer | Deluxe-PDF und Kundenname (Lizenz erforderlich) |
+| `jurisdiction` | `CH` | Rechtsraum |
+| `llm-remediation`, `api-key`, `llm-provider`, `llm-model` | `false`, leer, `openai`, `gpt-4o` | Optional: LLM-gestützte Patches. Nur OpenAI ist umgesetzt; der Quellcode wird dann an den Anbieter gesendet; ohne `llm-remediation: true` wirkt der Key nicht |
+
+`--max-subpages` und `--banner-wait` sind noch keine Inputs der Action. Bis dahin lassen sie sich im Job über `env:` setzen (`CPCG_MAX_SUBPAGES`, `CPCG_BANNER_WAIT`); als Inputs wären die Namen `max-subpages` und `banner-wait` (Werte wie beim CLI) vorgesehen.
+
+Beispiel mit Pull Request als Ergebnis:
+
+```yaml
+permissions:
+  contents: write
+  pull-requests: write
+steps:
+  - uses: actions/checkout@v4
+  - uses: cuonztech/privacy-chaos-gate@v1
+    with:
+      staging-url: ${{ vars.STAGING_URL }}
+      license: ${{ secrets.CPCG_LICENSE }}
+      auto-fix: true
+      create-pr: true
+      github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Outputs: `leaks-found`, `leaks-count`, `patch-applied`, `report-path` sowie `gate_state`, `incomplete`, `uncheckable_count`,
+`leak_requests` und `exit_code` (geschrieben vom CLI nach `GITHUB_OUTPUT`; leer, wenn die installierte CLI sie nicht kennt).
+Beispiel: `if: steps.cpcg.outputs.gate_state == 'blocked'`.
 
 ## Jurisdiktion
 
@@ -131,13 +289,17 @@ Die Action nutzt `dist/cli.js` aus dem Action-Path; erst bei fehlendem Build gre
 
 ```bash
 pnpm install
-pnpm test        # 136 Tests
+pnpm test                # Vitest-Suite (inkl. PHP-Lizenzdienst, falls Docker läuft; action.yml-Pin und Optionsweitergabe)
 pnpm build
-pnpm exec tsx scripts/e2e-cli-deluxe.mts   # E2E: echte CLI gegen Demo-Portal
+pnpm typecheck:all       # src + tests + scripts
+npx tsx scripts/e2e-cli-deluxe.mts   # E2E: echte CLI gegen Demo-Portal
 ```
 
+Der Lizenzdienst liegt in `server/license-api/` (eigene README mit Deploy-Checkliste und Betrieb)
+und gehört nicht zum veröffentlichten Paket.
+
 Secrets (Stripe, Lizenz-Secret) nur über Env/KeePass — nie im Repo.
 
 ---
 
-© CuonzTech · Carlo Cuonz · [cuonztech.ch](https://cuonztech.ch)
+© CuonzTech · Carlo Cuonz · [cuonztech.ch](https://cuonztech.ch) · Lizenz: siehe [LICENSE](LICENSE)

package/action.yml

@@ -10,11 +10,15 @@ inputs:
     description: "The URL of the staging or localhost web environment to stress-test"
     required: true
   api-key:
-    description: "API key for the auto-remediation LLM (e.g. OpenAI, Anthropic, Gemini)"
+    description: "API key for the optional LLM patch generation. Only OpenAI is implemented (llm-provider openai); other providers fall back to the built-in rules. Has no effect without llm-remediation: true. Passed via the CPCG_LLM_API_KEY environment variable."
     required: false
     default: ""
+  llm-remediation:
+    description: "Opt-in: allow the source code to be sent to the LLM provider (OpenAI only) to generate patches (needs api-key). Off by default; only passed on if the installed CLI supports it."
+    required: false
+    default: "false"
   llm-provider:
-    description: "LLM Provider to use for auto-remediation ('openai', 'anthropic', 'gemini')"
+    description: "LLM provider for auto-remediation. Only 'openai' is implemented; 'anthropic' and 'gemini' fall back to the built-in rules."
     required: false
     default: "openai"
   llm-model:
@@ -22,13 +26,49 @@ inputs:
     required: false
     default: "gpt-4o"
   auto-fix:
-    description: "Automatically generate and apply code patches when tracker leaks are detected"
+    description: "Generate and apply code patches on the runner when tracker leaks are detected. Off by default: a gate should not silently change files; combine with create-pr to receive the fix as a pull request."
     required: false
-    default: "true"
+    default: "false"
   fail-on-leak:
     description: "Block the build (exit code 1) if unpatched critical leaks remain"
     required: false
     default: "true"
+  fail-on-uncheckable:
+    description: "Block the build (exit code 4) if core scenarios could not be checked conclusively (e.g. consent banner not found). Only passed on if the installed CLI supports it; otherwise a warning is printed."
+    required: false
+    default: "true"
+  strict:
+    description: "Hints (purely functional third parties such as Google Fonts) also block the gate. Off by default: they are reported as hints, not as blockers. Only passed on if the installed CLI supports it."
+    required: false
+    default: "false"
+  ignore:
+    description: "Findings to ignore: tracker name or host pattern, one per line or comma-separated (e.g. fonts.googleapis.com or *.hotjar.com). Ignored findings are listed as ignored in the report."
+    required: false
+    default: ""
+  accept-selector:
+    description: "Own CSS selector of the accept button, one per line (when the built-in CMP detection does not find it)"
+    required: false
+    default: ""
+  reject-selector:
+    description: "Own CSS selector of the reject button, one per line"
+    required: false
+    default: ""
+  settings-selector:
+    description: "Own CSS selector of the settings button, one per line"
+    required: false
+    default: ""
+  banner-frame:
+    description: "Part of the URL of the iframe that contains the consent banner (CMP inside a frame)"
+    required: false
+    default: ""
+  max-subpages:
+    description: "Maximum number of linked subpages checked for trackers (default 12, max 40; larger values take longer)"
+    required: false
+    default: ""
+  banner-wait:
+    description: "Seconds to wait for a late consent banner (1-60; default as in the CLI)"
+    required: false
+    default: ""
   report-output:
     description: "File path where the JSON LeakReport will be written"
     required: false
@@ -38,23 +78,31 @@ inputs:
     required: false
     default: "."
   git-commit:
-    description: "Automatically commit generated privacy fixes into the branch"
+    description: "Commit generated privacy fixes into the checked-out branch (requires auto-fix and a valid license; skipped without one)"
+    required: false
+    default: "false"
+  create-pr:
+    description: "Create a fix branch and open a GitHub Pull Request with the generated fix (requires auto-fix, github-token and a valid license; takes precedence over git-commit)"
     required: false
     default: "false"
+  github-token:
+    description: "GitHub token for create-pr (contents: write and pull-requests: write). Passed via the GITHUB_TOKEN environment variable, never on the command line."
+    required: false
+    default: ""
   license:
-    description: "CuonzTech CPCG Lizenzcode (CPCG-…) — aus Secrets, nach Online-Kauf"
+    description: "CuonzTech CPCG license (CPCG-… or customer key CPCG-K-…) — from secrets, after online purchase. Not needed for scan and console gate; required for customer report/PDF, git-commit and create-pr. Passed via the CPCG_LICENSE environment variable."
     required: false
     default: ""
   report-pdf:
-    description: "Deluxe-PDF (Deckblatt + Evidence) nach dem Scan erzeugen"
+    description: "Create the deluxe PDF (cover page + evidence) after the scan. Requires a valid license; skipped without one."
     required: false
     default: "false"
   client-name:
-    description: "Kundenname für das PDF-Deckblatt"
+    description: "Client name for the customer report and the PDF cover page. Requires a valid license."
     required: false
     default: ""
   jurisdiction:
-    description: "Rechtsraum für Bewertung: CH | EU | UK | US-CA | BR | ROW"
+    description: "Jurisdiction highlighted in the console and report: CH | EU | UK | US-CA | BR | ROW"
     required: false
     default: "CH"
 
@@ -71,6 +119,21 @@ outputs:
   report-path:
     description: "Absolute or relative path to the generated JSON report"
     value: ${{ steps.cpcg-run.outputs.report_path }}
+  gate_state:
+    description: "Gate result as written by the CLI (for example blocked, fix-proposed, inconclusive, passed). Empty if the installed CLI predates this output."
+    value: ${{ steps.cpcg-run.outputs.gate_state }}
+  incomplete:
+    description: "'true' if core scenarios could not be checked conclusively"
+    value: ${{ steps.cpcg-run.outputs.incomplete }}
+  uncheckable_count:
+    description: "Number of scenarios that could not be checked"
+    value: ${{ steps.cpcg-run.outputs.uncheckable_count }}
+  leak_requests:
+    description: "Number of tracker requests observed before consent"
+    value: ${{ steps.cpcg-run.outputs.leak_requests }}
+  exit_code:
+    description: "Exit code of the CLI (0 ok, 1 leaks, 2 license invalid or revoked, 3 error, 4 incomplete)"
+    value: ${{ steps.cpcg-run.outputs.exit_code }}
 
 runs:
   using: "composite"
@@ -80,30 +143,128 @@ runs:
       with:
         node-version: "20"
 
+    # Installationsschritt: bewusst ohne Secrets (Lizenz, Token, API-Key) in der Umgebung. Nur hier läuft npm.
+    - name: Install Privacy Chaos Gate
+      id: cpcg-install
+      shell: bash
+      env:
+        ACTION_PATH: ${{ github.action_path }}
+        CPCG_PINNED_VERSION: "0.2.1" # = package.json version; bei jedem Release mit anheben (tests/action-pin.test.ts prüft das)
+      run: |
+        set -euo pipefail
+
+        CLI_PATH="$ACTION_PATH/dist/cli.js"
+        if [ -f "$CLI_PATH" ]; then
+          # Eigener Build im Action-Pfad (Repo-CI): Abhängigkeiten und Browser bringt der Workflow mit.
+          echo "cli=$CLI_PATH" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        # Veröffentlichtes Paket in der gepinnten Version. Lifecycle-Skripte der Abhängigkeiten laufen nicht
+        # (--ignore-scripts); der Playwright-Browser wird unten ausdrücklich installiert.
+        TOOL_DIR="$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/cpcg-XXXXXX")"
+        npm install --prefix "$TOOL_DIR" --ignore-scripts --no-audit --no-fund --loglevel=error "cuonztech-privacy-chaos-gate@${CPCG_PINNED_VERSION}"
+        PW_CLI="$TOOL_DIR/node_modules/playwright/cli.js"
+        if [ -f "$PW_CLI" ]; then
+          node "$PW_CLI" install --with-deps chromium
+        else
+          npx --yes playwright install --with-deps chromium
+        fi
+        echo "cli=$TOOL_DIR/node_modules/cuonztech-privacy-chaos-gate/dist/cli.js" >> "$GITHUB_OUTPUT"
+
     - name: Run Privacy Chaos Gate
       id: cpcg-run
       shell: bash
+      # Alle Inputs gelangen nur über env in das Skript (keine ${{ }}-Interpolation im run-Block:
+      # sonst könnten Input-Werte als Shell-Code ausgeführt werden). Die Lizenz steht nie in der Kommandozeile.
       env:
+        CPCG_CLI: ${{ steps.cpcg-install.outputs.cli }}
         CPCG_LLM_API_KEY: ${{ inputs.api-key }}
         CPCG_LLM_PROVIDER: ${{ inputs.llm-provider }}
         CPCG_LLM_MODEL: ${{ inputs.llm-model }}
         CPCG_LICENSE: ${{ inputs.license }}
+        GITHUB_TOKEN: ${{ inputs.github-token }}
+        IN_STAGING_URL: ${{ inputs.staging-url }}
+        IN_LLM_REMEDIATION: ${{ inputs.llm-remediation }}
+        IN_AUTO_FIX: ${{ inputs.auto-fix }}
+        IN_FAIL_ON_LEAK: ${{ inputs.fail-on-leak }}
+        IN_FAIL_ON_UNCHECKABLE: ${{ inputs.fail-on-uncheckable }}
+        IN_STRICT: ${{ inputs.strict }}
+        IN_IGNORE: ${{ inputs.ignore }}
+        IN_ACCEPT_SELECTOR: ${{ inputs.accept-selector }}
+        IN_REJECT_SELECTOR: ${{ inputs.reject-selector }}
+        IN_SETTINGS_SELECTOR: ${{ inputs.settings-selector }}
+        IN_BANNER_FRAME: ${{ inputs.banner-frame }}
+        IN_MAX_SUBPAGES: ${{ inputs.max-subpages }}
+        IN_BANNER_WAIT: ${{ inputs.banner-wait }}
+        IN_REPORT_OUTPUT: ${{ inputs.report-output }}
+        IN_SOURCE_DIR: ${{ inputs.target-source-dir }}
+        IN_GIT_COMMIT: ${{ inputs.git-commit }}
+        IN_CREATE_PR: ${{ inputs.create-pr }}
+        IN_REPORT_PDF: ${{ inputs.report-pdf }}
+        IN_CLIENT: ${{ inputs.client-name }}
+        IN_JURISDICTION: ${{ inputs.jurisdiction }}
       run: |
-        CLI_PATH="${{ github.action_path }}/dist/cli.js"
-        if [ -f "$CLI_PATH" ]; then
-          RUNNER="node $CLI_PATH"
-        else
-          RUNNER="npx @cuonztech/privacy-chaos-gate"
+        set -euo pipefail
+
+        RUNNER=(node "$CPCG_CLI")
+
+        # Optionen immer als --name=wert: ein Wert, der mit "-" beginnt, wird so nie als eigene Option gelesen.
+        ARGS=(
+          "--url=$IN_STAGING_URL"
+          "--auto-fix=$IN_AUTO_FIX"
+          "--fail-on-leak=$IN_FAIL_ON_LEAK"
+          "--report-output=$IN_REPORT_OUTPUT"
+          "--source-dir=$IN_SOURCE_DIR"
+          "--git-commit=$IN_GIT_COMMIT"
+          "--create-pr=$IN_CREATE_PR"
+          "--report-pdf=$IN_REPORT_PDF"
+          "--jurisdiction=$IN_JURISDICTION"
+        )
+        if [ -n "$IN_CLIENT" ]; then
+          ARGS+=("--client=$IN_CLIENT")
         fi
 
-        $RUNNER \
-          --url "${{ inputs.staging-url }}" \
-          --auto-fix "${{ inputs.auto-fix }}" \
-          --fail-on-leak "${{ inputs.fail-on-leak }}" \
-          --report-output "${{ inputs.report-output }}" \
-          --source-dir "${{ inputs.target-source-dir }}" \
-          --git-commit "${{ inputs.git-commit }}" \
-          --license "${{ inputs.license }}" \
-        --report-pdf "${{ inputs.report-pdf }}" \
-        --client "${{ inputs.client-name }}" \
-          --jurisdiction "${{ inputs.jurisdiction }}"
+        # Neuere Optionen nur weitergeben, wenn die installierte CLI sie kennt (ältere Versionen würden sonst mit
+        # "unknown option" abbrechen). Kennt sie eine gewünschte Option nicht, wird das gemeldet, nicht still übergangen.
+        HELP="$("${RUNNER[@]}" --help 2>&1 || true)"
+        supports() { printf '%s\n' "$HELP" | grep -q -- "$1"; }
+        warn_unsupported() {
+          echo "::warning title=CPCG::Die installierte CLI kennt --$1 nicht; der Input wird ignoriert. Paket- und Action-Version angleichen."
+        }
+        # Boolesche Option: übergeben, wenn bekannt; unbekannt und angefordert ("true") → Warnung.
+        opt_bool() {
+          if supports "--$1"; then
+            ARGS+=("--$1=$2")
+          elif [ "$2" = "true" ]; then
+            warn_unsupported "$1"
+          fi
+          return 0
+        }
+        # Wert-Option (mehrzeilig erlaubt: je nichtleere Zeile eine Option): nur wenn gesetzt.
+        opt_lines() {
+          local flag="$1" value="$2" line
+          [ -n "${value//[[:space:]]/}" ] || return 0
+          if ! supports "--$flag"; then
+            warn_unsupported "$flag"
+            return 0
+          fi
+          while IFS= read -r line; do
+            line="${line#"${line%%[![:space:]]*}"}"
+            line="${line%"${line##*[![:space:]]}"}"
+            if [ -n "$line" ]; then ARGS+=("--$flag=$line"); fi
+          done <<< "$value"
+          return 0
+        }
+        opt_bool fail-on-uncheckable "$IN_FAIL_ON_UNCHECKABLE"
+        opt_bool llm-remediation "$IN_LLM_REMEDIATION"
+        opt_bool strict "$IN_STRICT"
+        opt_lines ignore "$IN_IGNORE"
+        opt_lines accept-selector "$IN_ACCEPT_SELECTOR"
+        opt_lines reject-selector "$IN_REJECT_SELECTOR"
+        opt_lines settings-selector "$IN_SETTINGS_SELECTOR"
+        opt_lines banner-frame "$IN_BANNER_FRAME"
+        opt_lines max-subpages "$IN_MAX_SUBPAGES"
+        opt_lines banner-wait "$IN_BANNER_WAIT"
+
+        "${RUNNER[@]}" "${ARGS[@]}"