RC-7

README.md

@@ -1,7 +1,12 @@
-> **V3.5 Random Guess Lottery:** Optional kann die Zahl der tatsächlich ausgewerteten Tipps pro Zeitfenster begrenzt werden. Im Admin-Tab **RUNTIME** steuern `Lotterie-Zeitfenster (s)` und `Max. gezogene Tipps je Task/Fenster` die Funktion; `0` deaktiviert sie vollständig. Die Lotterie läuft getrennt pro aktivem Task. Alle gültigen, signierten Tipps werden bis zum Ende des Zeitfensters gesammelt und anschließend mit `crypto/rand` gleichberechtigt zufällig gezogen. Nur gezogene Tipps werden gegen das geheime Ziel ausgewertet und können Score/Winner/NFT auslösen. Nicht gezogene Tipps verbrauchen ihre Sequenz, damit beim nächsten Fenster ein neuer deterministischer Tipp entsteht, zählen aber nicht als akzeptierter `guess_count`. Abgebrochene HTTP-Requests verbrauchen keinen Lotterie-Slot. Dadurch wird die mögliche Task-Abschluss-/NFT-Rate gedrosselt, ohne Gewinner oder Styles direkt zu manipulieren.
+> **V4.2 Pipeline Dockerfiles:** Server, Customer Service und Worker besitzen jetzt jeweils ein eigenes Dockerfile (`Dockerfile.server`, `Dockerfile.customer-service`, `Dockerfile.worker`). Das bestehende `Dockerfile` baut weiterhin den Server, damit vorhandene Single-Image-Pipelines kompatibel bleiben. `CS_WORKER_IMAGE` zeigt weiterhin direkt auf das veröffentlichte Worker-Image.
 
-# Neural Hunt — V3.1 RIFT Task-Style Collection + Profile Cleanup
+> **V4.0 Beacon Hunt + Hosted PrePaid Service:** Optional kann die Task-Lotterie jetzt PULSE/FLUX/ORBIT als vorab signierte Spielerentscheidung verwenden. Der Draw nutzt einen erst nach Fensterschluss verfügbaren drand-Round und speichert Round, Signatur, abgeleitete Randomness und Boost für Audit/Collectible-Traits. Zusätzlich gibt es einen separat aktivierbaren Customer-Service mit PrePaid-Zeitabrechnung, PayPal-Sandbox/Orders-v2-Flow, mehreren Docker-Workern pro Kunde, portablen Worker-Identitäten und delegiertem Reward-Owner. Details: `HOSTED_SERVICE.md`.
 
+> **V3.9 Portable Identity + Winner Originals:** Der Shell-Client verwendet standardmäßig dauerhaft `~/.neuralhunt/identity.json` (`0600`) und kann dieselbe P-256-Identität als passwortgeschützten, browser-kompatiblen JSON-Export sichern. Browser und CLI validieren beim Import Public/Private-Key-Paar und Client-ID. Nach dem Import derselben Identität sieht der Browser wieder dieselben serverseitig gebundenen Wins. Authentifizierte Gewinner erhalten unter **MEINE NFTS** Zugriff auf ihr unverändertes Original-Artefakt; andere Identitäten erhalten dafür nur `404`. Der CLI besitzt dafür `my-nfts` und `nft original <task-id> <datei>`. Öffentliche Leaderboards bleiben weiterhin ausschließlich bei Wasserzeichen-Previews.
+
+> **V3.5 Random Guess Lottery:** Optional kann die Zahl der tatsächlich ausgewerteten Tipps pro Zeitfenster begrenzt werden. Im Admin-Tab **RUNTIME** steuern `Lotterie-Zeitfenster (s)` und `Max. gezogene Tipps je Task/Fenster` die Funktion; `0` deaktiviert sie vollständig. Die Lotterie läuft getrennt pro aktivem Task. Alle gültigen, signierten Tipps werden bis zum Ende des Zeitfensters gesammelt. Im normalen Lotterie-Modus werden sie anschließend mit `crypto/rand` gleichberechtigt zufällig gezogen; bei aktiviertem Beacon Hunt übernimmt stattdessen der erst nach Fensterschluss verfügbare drand-Reveal die deterministische gewichtete Ziehung. Nur gezogene Tipps werden gegen das geheime Ziel ausgewertet und können Score/Winner/NFT auslösen. Nicht gezogene Tipps verbrauchen ihre Sequenz, damit beim nächsten Fenster ein neuer deterministischer Tipp entsteht, zählen aber nicht als akzeptierter `guess_count`. Abgebrochene HTTP-Requests verbrauchen keinen Lotterie-Slot. Dadurch wird die mögliche Task-Abschluss-/NFT-Rate gedrosselt, ohne Gewinner oder Styles direkt zu manipulieren.
+
+# Neural Hunt — V4.1 Split Images + Beacon Hunt + Hosted PrePaid Service
 
 
 > **V3.1 Admin Profile Cleanup:** Im Admin-Tab **RUNTIME** gibt es ein manuelles Bereinigungstool für alte Identitäten. Die Inaktivitätsdauer ist in Stunden/Tagen/Wochen einstellbar. Vor dem Löschen zeigt **PRÜFEN** die Anzahl löschbarer Profile. Gelöscht werden ausschließlich Profile, deren letzte Aktivität älter als die gewählte Grenze ist, die aktuell nicht verbunden sind und die niemals Gewinner eines Tasks waren. Gewinner werden immer geschützt; aktuell verbundene Clients ebenfalls. Beim Löschen werden die per Foreign Key abhängigen `task_points`, `client_unlocks` und `client_task_selection` mit entfernt. WebSocket-Verbindungsaufbau und -ende aktualisieren `clients.last_seen`, damit die Inaktivitätsgrenze tatsächliche Nutzung besser abbildet.
@@ -49,6 +54,41 @@ Danach:
 - Echtzeit-Leaderboard: `http://localhost:8080/leaderboard`
 - Admin (private listener): `http://localhost:8081/admin`
 
+### V4.1: drei Docker-Images
+
+Das Runtime-Image ist jetzt nach Rollen getrennt:
+
+```text
+neuralhunt-server:local            -> Game/API + Game-Admin
+neuralhunt-customer-service:local  -> Customer Portal / Billing / Docker-Control
+neuralhunt-worker:local            -> CLI-Agent / Hosted Worker
+```
+
+Alle drei lokal bauen:
+
+```bash
+docker build -f Dockerfile.server -t neuralhunt-server:local .
+docker build -f Dockerfile.customer-service -t neuralhunt-customer-service:local .
+docker build -f Dockerfile.worker -t neuralhunt-worker:local .
+# oder ohne Bake:
+docker compose --profile images build app customer-service worker-image
+```
+
+Für Registry-Tags:
+
+```bash
+export NEURALHUNT_SERVER_IMAGE=registry.example.com/neuralhunt/server:v4.1
+export NEURALHUNT_CUSTOMER_IMAGE=registry.example.com/neuralhunt/customer-service:v4.1
+export CS_WORKER_IMAGE=registry.example.com/neuralhunt/worker:v4.1
+# In der CI/CD-Pipeline jeweils das passende Dockerfile bauen und pushen.
+```
+
+Der Customer Service verwendet **genau** `CS_WORKER_IMAGE` für dynamisch
+erzeugte Worker. Mit `CS_WORKER_AUTO_PULL=true` darf er ein fehlendes Image bei
+Bedarf über Docker Engine nachladen. Für private Registries können dafür
+`CS_WORKER_REGISTRY_SERVER`, `CS_WORKER_REGISTRY_USERNAME` und
+`CS_WORKER_REGISTRY_PASSWORD` mit einem read-only Deploy-Token gesetzt werden.
+
 
 ## V2.5: Task-Landing-Page und Task-Serien
 
@@ -104,6 +144,8 @@ go run ./cmd/client -url http://127.0.0.1:8080
 
 Beim ersten Start wird standardmäßig `~/.neuralhunt/identity.json` mit Dateirechten `0600` erzeugt. Danach zeigt die Shell eine Task-Auswahl ähnlich der Browser-Landing-Page.
 
+Diese Datei **ist die Identität** des Shell-Clients. Solange sie erhalten bleibt, bleibt auch die daraus abgeleitete Client-ID identisch. Für Container/systemd sollte sie deshalb auf einem persistenten Volume bzw. Host-Pfad liegen. Die Raw-Datei enthält den privaten Schlüssel im Klartext und sollte nicht verteilt werden; für Backups und den Wechsel in den Browser immer den verschlüsselten Export verwenden.
+
 Wichtige Befehle:
 
 ```text
@@ -114,10 +156,12 @@ map [n]                       textuelles TARGET FIELD nach Nähe-Zonen
 leaderboard [n]               Echtzeit-Leaderboard abrufen
 leaderboard watch             Leaderboard alle 5 Sekunden anzeigen
 leaderboard stop              Watch beenden
-nfts [n]                      Winner-Artefakte mit Wasserzeichen-URLs
+nfts [n]                      öffentliche Winner-Artefakte mit Wasserzeichen-URLs
+my-nfts [n]                   eigene fertige Gewinner-Artefakte
 nft get <task-id> <datei>     öffentliche Wasserzeichen-Preview speichern
-identity                      Client-ID + lokale Identity-Datei
-identity export <datei>       browser-kompatibler verschlüsselter Export
+nft original <task-id> <datei> eigenes unverändertes Original speichern
+identity                      Client-ID + persistente Identity-Datei
+identity export <datei>       browser-kompatiblen verschlüsselten Backup-Export schreiben
 quit
 ```
 
@@ -140,6 +184,41 @@ go build -trimpath -o neuralhunt-client ./cmd/client
 ./neuralhunt-client -url https://hunt.example.org -non-interactive -task "Aurora Vault"
 ```
 
+### CLI als dediziertes Worker-Image testen
+
+Seit V4.1 enthält das Server-Image absichtlich nur noch den Game-Server. Baue das
+Worker-Image separat und mounte für die Identität ein persistentes Verzeichnis:
+
+```bash
+docker compose --profile images build worker-image
+mkdir -p ./client-identities
+
+docker run --rm -it \
+  --network neuralhunt_backend \
+  -v "$PWD/client-identities:/identity" \
+  neuralhunt-worker:local \
+  -url http://app:8080 \
+  -identity /identity/test-cli.json
+```
+
+Bei jedem weiteren Start mit genau diesem Pfad wird dieselbe Client-ID verwendet.
+Für einen browser-kompatiblen verschlüsselten Export:
+
+```bash
+export NH_PASS='correct horse battery staple'
+docker run --rm \
+  -e NEURALHUNT_IDENTITY_PASSPHRASE="$NH_PASS" \
+  -v "$PWD/client-identities:/identity" \
+  neuralhunt-worker:local \
+  -identity /identity/test-cli.json \
+  -export /identity/test-cli-browser.json
+unset NH_PASS
+```
+
+`client-identities/test-cli-browser.json` kann anschließend im Web-Client unter
+**IDENTITÄT → IMPORT** eingelesen werden. Die Raw-Datei `test-cli.json` sollte
+den Host nicht unverschlüsselt verlassen.
+
 Ein minimales systemd-Beispiel:
 
 ```ini
@@ -178,6 +257,10 @@ go run ./cmd/client \
   -export ./neuralhunt-browser-import.json
 ```
 
+Der Export ist selbstbeschreibend (`neuralhunt-identity-export`), enthält die öffentliche Client-ID und verschlüsselt das eigentliche Schlüsselmaterial mit PBKDF2-HMAC-SHA256 (250.000 Iterationen) + AES-256-GCM. Neue Exporte verlangen mindestens 12 Zeichen Passphrase. Im Browser unter **IDENTITÄT → IMPORT** Datei auswählen, dieselbe Passphrase eingeben und den Identitätswechsel bestätigen. Danach meldet sich der Browser mit derselben Client-ID an.
+
+Unter **MEINE NFTS** werden dann die fertigen Gewinner-Artefakte dieser Identität angezeigt. Nur der authentifizierte Gewinner darf das Original herunterladen; die öffentliche Galerie bleibt wassergezeichnet.
+
 **Nicht dieselbe Identity gleichzeitig im Browser und im Shell-Client verbinden.** Das ist absichtlich durch die Single-Connection-Regel gesperrt. Unterschiedliche Identities dürfen natürlich vom selben Rechner bzw. derselben IP verbunden sein.
 
 Unterstützte Shell-Parameter: