223 lines
7.1 KiB
Markdown
223 lines
7.1 KiB
Markdown
# AI Disclosure Standard 1.6.2
|
|
|
|
Ein zustandsloser Go-Dienst für sichtbare und maschinenlesbare Erklärungen zur KI-Nutzung in Artikeln, Webseiten und einzelnen Inhaltsbestandteilen.
|
|
|
|
## Funktionen
|
|
|
|
- einzelne Deklarationen und zusammengefasste Artikel-/Webseiten-Deklarationen;
|
|
- SVG-Badges, HTML-Erklärung und JSON-LD unter einem gemeinsamen Link;
|
|
- Text, Titelbild, weitere Bilder, Recherche, Übersetzung, Audio, Video und Code getrennt erfassbar;
|
|
- automatisch erzeugte, professionell formulierte Zusammenfassung als Fließtext und strukturierte Tabelle;
|
|
- frei wählbare Nachweisgrundlage: Selbsterklärung, technisch protokolliert, signiert oder verifiziert;
|
|
- Deutsch, Englisch, Französisch, Spanisch, Italienisch, Niederländisch, Portugiesisch und Polnisch;
|
|
- Sprachumschalter direkt auf der Ergebnisseite;
|
|
- mehrsprachige Hintergrundseite zu Artikel 50 des EU AI Act, Kennzeichnungspflichten und freiwilliger Transparenz;
|
|
- optionale lizenzierte Funktionen für eigene Texte und Badge-Darstellung;
|
|
- Offline-, Hybrid- und Online-Prüfung über die eigenständige Universal License Platform;
|
|
- Health-, Readiness- und Prometheus-Endpunkte;
|
|
- Docker-, Kubernetes- und Docker-Swarm-Deployment.
|
|
|
|
## Start unter Windows
|
|
|
|
```powershell
|
|
go run .\cmd\server
|
|
```
|
|
|
|
Danach:
|
|
|
|
```text
|
|
Generator: http://localhost:8080/
|
|
Produktseite: http://localhost:8080/product
|
|
Hintergrund: http://localhost:8080/background
|
|
Healthcheck: http://localhost:8080/healthz
|
|
Funktionen: http://localhost:8080/v1/capabilities
|
|
```
|
|
|
|
Go lädt `.env` nicht selbst. Unter PowerShell kann die Datei vor dem Start in die Prozessumgebung übernommen werden oder Docker Compose mit `--env-file .env` verwendet werden.
|
|
|
|
## Docker Compose
|
|
|
|
```powershell
|
|
Copy-Item .env.example .env
|
|
docker compose --env-file .env up -d --build
|
|
```
|
|
|
|
## Lizenzprüfung
|
|
|
|
Dieses Projekt stellt **keine Lizenzen aus** und enthält keine Schlüsselgenerierung, privaten Schlüssel, Lizenzverwaltung, Admin-Oberfläche oder eigenen Lizenzserver. Diese Aufgaben gehören ausschließlich in die separat betriebene **Universal License Platform**.
|
|
|
|
Der Produktserver enthält nur den Laufzeit-Client und akzeptiert:
|
|
|
|
```env
|
|
LICENSE_TOKEN=...
|
|
LICENSE_MODE=offline
|
|
LICENSE_SERVER_URL=
|
|
LICENSE_INSTANCE_ID=
|
|
```
|
|
|
|
Der Produktname ist fest verdrahtet:
|
|
|
|
```text
|
|
ai-disclosure-standard
|
|
```
|
|
|
|
Für die vorhandenen Funktionen verwendet die Plattform diese Feature-IDs:
|
|
|
|
```text
|
|
custom_text
|
|
custom_badge
|
|
white_label
|
|
```
|
|
|
|
### Vertrauensschlüssel einbetten
|
|
|
|
Die öffentlichen Issuer- und Lease-Schlüssel werden von der Universal License Platform bereitgestellt. Lade dort den Trust Store herunter und ersetze vor dem Build:
|
|
|
|
```text
|
|
internal/app/trusted_keys.json
|
|
```
|
|
|
|
PowerShell-Beispiel:
|
|
|
|
```powershell
|
|
Invoke-WebRequest `
|
|
"https://licenses.example.org/api/v1/trust-store" `
|
|
-OutFile ".\internal\app\trusted_keys.json"
|
|
|
|
go build .\cmd\server
|
|
```
|
|
|
|
Der Trust Store wird mit `go:embed` fest in das Binary eingebaut. Es gibt absichtlich kein `LICENSE_PUBLIC_KEY` und keinen zur Laufzeit austauschbaren Trust Store.
|
|
|
|
### Prüfmodi
|
|
|
|
**Offline** prüft den signierten Lizenz-Token ausschließlich lokal.
|
|
|
|
```env
|
|
LICENSE_MODE=offline
|
|
LICENSE_TOKEN=...
|
|
```
|
|
|
|
**Hybrid** fragt die Universal License Platform ab und speichert ein kurzlebiges, signiertes Lease. Bei temporärer Nichterreichbarkeit kann das letzte gültige Lease innerhalb der in der Lizenz festgelegten Grace-Periode verwendet werden.
|
|
|
|
```env
|
|
LICENSE_MODE=hybrid
|
|
LICENSE_TOKEN=...
|
|
LICENSE_CACHE_FILE=/data/license-lease.json
|
|
```
|
|
|
|
**Online** benötigt eine erfolgreiche aktuelle Prüfung durch die Plattform.
|
|
|
|
```env
|
|
LICENSE_MODE=online
|
|
LICENSE_TOKEN=...
|
|
```
|
|
|
|
Bei Hybrid- und Online-Lizenzen übernimmt der Client bevorzugt die von der Plattform signiert in der Lizenz gespeicherte Server-URL. `LICENSE_SERVER_URL` ist nur ein expliziter Override beziehungsweise Fallback.
|
|
|
|
Der Client verwendet die Plattform-API:
|
|
|
|
```text
|
|
POST /api/v1/licenses/validate
|
|
```
|
|
|
|
und unterstützt für bestehende Installationen weiterhin:
|
|
|
|
```text
|
|
POST /v1/introspect
|
|
```
|
|
|
|
Weitere Einzelheiten stehen in [`docs/LICENSE-INTEGRATION.md`](docs/LICENSE-INTEGRATION.md). Für bestehende 1.5-Installationen siehe [`docs/MIGRATION-1.5-TO-1.6.md`](docs/MIGRATION-1.5-TO-1.6.md).
|
|
|
|
## Konfiguration
|
|
|
|
| Variable | Standard | Bedeutung |
|
|
|---|---|---|
|
|
| `LISTEN_ADDRESS` | `:8080` | HTTP-Adresse |
|
|
| `BASE_URL` | `http://localhost:8080` | öffentliche kanonische URL und Domainprüfung |
|
|
| `PUBLIC_NAME` | `AI Usage Disclosure` | sichtbarer Produktname |
|
|
| `CONTACT_URL` | Projektseite | Kontakt-/Informationsseite |
|
|
| `DEFAULT_LANGUAGE` | `de` | Standardsprache |
|
|
| `TRUST_PROXY` | `false` | Proxy-Header für Client-IP berücksichtigen |
|
|
| `LICENSE_TOKEN` | leer | von der Universal License Platform ausgestellter Token |
|
|
| `LICENSE_MODE` | `offline` | Mindestmodus `offline`, `hybrid` oder `online` |
|
|
| `LICENSE_SERVER_URL` | leer | optionaler Prüfserver-Override |
|
|
| `LICENSE_INSTANCE_ID` | leer | optionale Instanzbindung |
|
|
| `LICENSE_CACHE_FILE` | `./data/license-lease.json` | signierter Hybrid-Lease-Cache |
|
|
| `LICENSE_REFRESH_INTERVAL` | `15m` | Hintergrundaktualisierung |
|
|
| `LICENSE_REQUEST_TIMEOUT` | `5s` | Timeout der Onlineprüfung |
|
|
|
|
## API
|
|
|
|
```text
|
|
GET /badge/{preset}.svg
|
|
GET /v1/badge.svg
|
|
GET /background
|
|
GET /declaration
|
|
GET /v1/declaration.json
|
|
POST /v1/validate
|
|
GET /v1/capabilities
|
|
GET /healthz
|
|
GET /readyz
|
|
GET /metrics
|
|
```
|
|
|
|
Beispiel für eine Artikelerklärung:
|
|
|
|
```text
|
|
/declaration?mode=article&textExtent=none&textReview=none&imageExtent=full&imageReview=editorial&researchExtent=assisted&researchReview=expert&assurance=technicallyRecorded&lang=de
|
|
```
|
|
|
|
|
|
### Nachweisgrundlage
|
|
|
|
Der Generator bietet vier interoperable Werte. Sie werden über den Query-Parameter `assurance` an HTML- und JSON-LD-Ausgaben übertragen:
|
|
|
|
| Wert | Bedeutung |
|
|
|---|---|
|
|
| `selfDeclared` | Die veröffentlichende Person oder Organisation stellt die Angaben selbst bereit. |
|
|
| `technicallyRecorded` | Die Angaben wurden im Erstellungs- oder Veröffentlichungsprozess technisch protokolliert. |
|
|
| `signed` | Die Erklärung wurde digital signiert; Herkunft und Unverändertheit können geprüft werden. |
|
|
| `verified` | Die Angaben wurden nach einem dokumentierten Verfahren zusätzlich verifiziert. |
|
|
|
|
Eine digitale Signatur bestätigt die Herkunft und Integrität der Erklärung, nicht automatisch die inhaltliche Richtigkeit ihrer Angaben. Nicht zutreffende Nachweisstufen sollten nicht ausgewählt werden.
|
|
|
|
## Entwicklung und Prüfung
|
|
|
|
```powershell
|
|
go test .\...
|
|
go vet .\...
|
|
```
|
|
|
|
Der eingebundene, reine Laufzeit-Client wird separat geprüft:
|
|
|
|
```powershell
|
|
Set-Location .\third_party\license-platform-client
|
|
go test .\...
|
|
```
|
|
|
|
Gesamtprüfung über Make:
|
|
|
|
```bash
|
|
make check
|
|
```
|
|
|
|
## Projektgrenze
|
|
|
|
Im Hauptprojekt verbleiben ausschließlich:
|
|
|
|
- ein eingebetteter öffentlicher Trust Store;
|
|
- ein verifikationsfähiger Client;
|
|
- Feature- und Limit-Abfragen;
|
|
- optionaler signierter Lease-Cache.
|
|
|
|
Nicht enthalten sind:
|
|
|
|
- private Schlüssel;
|
|
- Keygen oder Lizenzsignierung;
|
|
- Lizenzportal oder Admin-API;
|
|
- Lizenzdatenbank;
|
|
- Widerrufsverwaltung oder Lease-Signierung.
|
|
|
|
Diese Funktionen werden nur in der eigenständigen Universal License Platform betrieben.
|