feat: ship agent-first mission control v0.2.57

docs/OPENCLAW_GATEWAY_CONNECTION.md

@@ -0,0 +1,248 @@
+# OpenClaw Gateway connection contract
+
+**Status:** Attach-&-Adopt-Vertrag implementiert; produktive externe
+Client-Identität und Live-Abnahme offen
+**Stand:** 2026-07-30
+
+Nexus ist die einzige browserseitige Control Plane. OpenClaw bleibt die
+Runtime- und Datenautorität. Gateway-Credentials, Ed25519-Private-Key,
+Device-Token, Provider-Secrets und OpenAI-Schlüssel bleiben serverseitig und
+werden weder an den Browser noch in OpenClaw-Projektionen oder PostgreSQL
+gegeben.
+
+## Produktions- und Kompatibilitätsgrenze
+
+- Der Connector verwendet Gateway Protocol v4 und ist standardmäßig auf den
+  geprüften OpenClaw-Stand `2026.7.1` gepinnt.
+- Nexus verwendet die externe Client-ID `nexus` und imitiert weder
+  `gateway-client/backend` noch Control UI oder CLI. Diese Identitäten sind
+  OpenClaw-intern reserviert.
+- Die stabile OpenClaw-Client-ID-Registry des gepinnten Stands unterstützt noch
+  keine externe Nexus-/Generic-Operator-ID. Deshalb bleibt der produktive
+  Connector standardmäßig mit
+  `OpenClawSetup:ExternalClientIdentitySupported=false` beziehungsweise
+  `OPENCLAW_EXTERNAL_CLIENT_ID_SUPPORTED=false` experimentell blockiert.
+- Das Flag darf erst für eine OpenClaw-Version aktiviert werden, deren
+  dokumentierter Client-Vertrag die verwendete externe Identität tatsächlich
+  akzeptiert und gegen die Nexus-Contract-Tests gepinnt wurde.
+- Lokale Mock-, Contract- und UI-Tests beweisen nicht, dass dieser Upstream-
+  Blocker gelöst ist. Eine produktive Verbindung oder Managementfreigabe darf
+  bis dahin nicht behauptet werden.
+
+## Autorisierungsgrenze
+
+- ASP.NET Core verwendet eine authenticated-by-default Fallback Policy. Nur die
+  Auth-Bootstrap-/Session-Endpunkte und explizite Liveness-/Gateway-Health-
+  Probes sind anonym.
+- Alle Setup-, Agent-Datei-, Workspace- und Config-Routen sind owner-only.
+  Andere `/api/v1/openclaw/*`-Leserouten sind authentifiziert; Control- und
+  Run-Mutationen bleiben owner-only.
+- `X-Agent-Id` ist niemals Authentifizierung. Der Header ist nur nach bereits
+  verifizierter Service- oder privilegierter Benutzeridentität ein
+  allow-gelisteter Actor-Hinweis.
+- OpenClaw-Schreibzugriffe benötigen gleichzeitig:
+  - einen vom Gateway beworbenen RPC;
+  - den erforderlichen Operator-Scope;
+  - die lokal persistierte `ManagementEnabled`-Freigabe;
+  - Rate Limit, Audit und einen Idempotency Key; sowie
+  - den aktuellen Ressourcen- oder Config-Hash.
+
+## Persistiertes Profil und Secret Ownership
+
+Nexus verwaltet in der ersten Ausbaustufe exakt ein Profil mit der festen ID
+`primary`. PostgreSQL speichert nur nicht geheime Verbindungs- und
+Adoptionsmetadaten:
+
+- normalisierten Endpoint und Discovery-Quelle;
+- erforderliche OpenClaw-Version und optionalen TLS-Fingerprint;
+- Setup-/Adoption-State und lokale Managementfreigabe;
+- Capability-Hash;
+- Zeitstempel und Concurrency-Version.
+
+Der Device-Key und ein ausgestellter Device-Token liegen ausschließlich im
+serverseitigen Device-State. Der Token ist an normalisierten Endpoint,
+TLS-Fingerprint, Rolle und Scopes gebunden. OpenAI-Schlüssel,
+Gateway-Passwörter und Provider-Secrets werden nicht in diesem Profil
+gespeichert.
+
+Ein Bootstrap-Token kann beim Attach entweder maskiert im Owner-Formular oder
+über eine serverseitige Secret-Referenz übergeben werden. Der Klartext lebt nur
+im Arbeitsspeicher, bis OpenClaw einen gebundenen Device-Token ausstellt. Nexus
+gibt ihn nicht zurück und schreibt ihn weder in PostgreSQL noch in Auditdaten.
+
+`GatewayConnector:DeviceStatePath` enthält Private Key, Public-Key-Metadaten
+und gebundene Device-Tokens.
+`GatewayConnector:OperationAuditPath` enthält den append-only
+Mutationsledger. Compose verwendet dafür:
+
+- `/var/lib/nexus/openclaw/device-state.json`;
+- `/var/lib/nexus/openclaw/operation-audit.jsonl`; und
+- das benannte Volume `nexus-openclaw-device`.
+
+Auf Unix setzt Nexus Verzeichnisse auf `0700` und Dateien auf `0600`. Ein
+korruptes Identity- oder Audit-File scheitert geschlossen; Nexus rotiert nicht
+still eine neue Identität und wiederholt keinen unklaren Schreibvorgang.
+
+## Transport- und Discovery-Regeln
+
+Discovery ist absichtlich begrenzt. Nexus prüft nur:
+
+- einen bereits konfigurierten Endpoint;
+- Baos bekannten Docker-DNS-Kandidaten `openclaw-gateway:18789`;
+- Loopback;
+- `host.docker.internal`; und
+- mDNS nur nach einer ausdrücklichen Owner-Aktion. Der aktuelle Build meldet
+  mDNS als `unsupported` und führt dann ebenfalls keinen Netzwerkscan aus.
+
+Es gibt keinen Subnetzscan und keinen Zugriff auf den Docker-Socket.
+
+Externe Ziele benötigen `wss://` und einen bestätigten SHA-256-
+Zertifikatfingerprint. Klares `ws://` ist nur für Loopback oder eine ausdrücklich
+erlaubte interne Docker-Verbindung zulässig. Ein Endpoint- oder TLS-Pin-Wechsel
+erzwingt eine neue Vertrauensprüfung; ein alter gebundener Device-Token darf
+nicht still weiterverwendet werden.
+
+## Owner-Flow: Erkennen, Verbinden und Übernehmen
+
+Der Setup Center in `/settings` führt durch einen zustandsbehafteten,
+read-only-first Ablauf:
+
+1. **Erkennen:** Bekannte Kandidaten finden oder einen expliziten Endpoint
+   eingeben.
+2. **Prüfen:** Transport, TLS-Pin, Version, Protokoll, externe Client-
+   Kompatibilität und erreichbare Capabilities prüfen.
+3. **Verbinden:** Mit einem einmaligen Bootstrap-Secret nur `operator.read`
+   anfordern und bei Bedarf die exakte `PAIRING_REQUIRED`-Request-ID anzeigen.
+4. **Verifizieren:** Nach externer Pairing-Freigabe Endpoint, Device, Rolle,
+   Scopes und Capabilities erneut prüfen.
+5. **Read-only-Inventar:** Agenten, Agent-Dateien, Modelle, Cron Jobs und weitere
+   beworbene Ressourcen live lesen.
+6. **Übernehmen:** Live-Inventar zurückgeben und nur Profilzustand,
+   Capability-Hash und Adoptionszeitpunkte persistieren. Nexus kopiert keine
+   Agent-Dateien, Cron Jobs, Channels, Nodes, Modelle oder
+   Provider-Credentials.
+7. **Verwaltung freigeben:** In einer separaten, sichtbaren Aktion
+   `operator.read` plus die tatsächlich benötigten Adminrechte anfordern. Die
+   Scope-Erweiterung benötigt eine neue OpenClaw-Pairing-Freigabe. Erst danach
+   kann die lokale `ManagementEnabled`-Freigabe aktiv werden.
+
+Eine bereits mit Admin-Scope verbundene, aber noch nicht adoptierte Instanz
+erfüllt den read-only-first Vertrag nicht und kann nicht still übernommen
+werden.
+
+## Setup-API
+
+Alle Routen sind owner-only und für Mutationen rate-limited:
+
+| Methode | Pfad | Zweck |
+|---|---|---|
+| `GET` | `/api/v1/openclaw/setup` | Profil-, Pairing-, Trust-, Scope- und Adoptionsstatus |
+| `POST` | `/api/v1/openclaw/setup/discover` | Ausschließlich bekannte Kandidaten ermitteln |
+| `POST` | `/api/v1/openclaw/setup/probe` | Endpoint und Vertrauensvertrag ohne Adoption prüfen |
+| `POST` | `/api/v1/openclaw/setup/attach` | Read-only-Verbindung mit flüchtigem Bootstrap-Secret beginnen |
+| `POST` | `/api/v1/openclaw/setup/verify` | Pairing, Scopes, Version und Capabilities neu verifizieren |
+| `POST` | `/api/v1/openclaw/setup/adopt` | Read-only-Live-Inventar und Fingerprints übernehmen |
+| `POST` | `/api/v1/openclaw/setup/management` | Bewussten Management-Scope-Upgrade starten oder bestätigen |
+| `DELETE` | `/api/v1/openclaw/setup/connection` | Bestätigt detachieren |
+
+Detach verlangt den bestätigten Endpoint und die Device-ID. Nexus entfernt das
+`primary`-Profil, schließt den aktiven Socket, deaktiviert das lokale
+Management-Gate und entfernt den an diese Verbindung gebundenen Device-Token.
+Der langfristige Nexus-Device-Key bleibt bestehen. Ein separat konfiguriertes
+Bootstrap-Secret muss der Operator weiterhin an dessen serverseitiger Quelle
+entfernen.
+
+## Offizieller OpenClaw-Wizard
+
+Für ein erreichbares neues OpenClaw rendert Nexus den offiziellen Gateway-
+Wizard, statt Installations- oder Migrationslogik nachzubauen:
+
+| Methode | Pfad | OpenClaw-RPC |
+|---|---|---|
+| `POST` | `/api/v1/openclaw/setup/wizard/start` | `wizard.start` |
+| `POST` | `/api/v1/openclaw/setup/wizard/next` | `wizard.next` |
+| `GET` | `/api/v1/openclaw/setup/wizard/{sessionId}` | `wizard.status` |
+| `POST` | `/api/v1/openclaw/setup/wizard/{sessionId}/cancel` | `wizard.cancel` |
+
+Der Wizard ist nur für eine verbundene, management-freigegebene Instanz mit
+beworbenen `wizard.*`-Methoden und `operator.admin` verfügbar. Nexus erzwingt
+den Setup-Flow mit `installDaemon=false`, redigiert sensible Schritte und
+akzeptiert keine Secret-Antwort aus einem unsicheren Browserfeld. Nexus
+installiert keine Pakete, startet keine SSH-Installation und führt weder
+`migrate` noch `doctor --fix` automatisch aus.
+
+## Runtime-, Config- und Cron-Autorität
+
+Nach Adoption liest Nexus OpenClaw-Ressourcen weiterhin live:
+
+- Agenten über `agents.list`;
+- erlaubte Bootstrap-Dateien über `agents.files.list/get/set`;
+- weitere Workspace-Dateien read-only über
+  `agents.workspace.list/get`;
+- Konfiguration über `config.schema.lookup`, `config.get` und `config.patch`;
+- Cron Jobs und deren Run-Historie über die typisierten `cron.*`-RPCs; und
+- Modell-Authentifizierungsstatus über eine redigierte
+  `models.authStatus`-Projektion.
+
+Datei- und Config-Schreibvorgänge re-readen vor der Mutation, lehnen Drift mit
+`409` ab und verifizieren das Ergebnis anschließend durch erneutes Lesen. Die
+UI behauptet keinen Hot Reload, wenn OpenClaw ihn nicht ausdrücklich bestätigt.
+Secrets werden nie aus einem Config-Snapshot oder Modell-Authstatus projiziert.
+
+## Mutation correlation und Idempotenz
+
+Der Backend-Layer leitet oder akzeptiert:
+
+- `Idempotency-Key`;
+- `X-Correlation-ID`;
+- W3C `traceparent`; und
+- den authentifizierten Actor (`sub`).
+
+Actor, Ziel, Operationszustand, Intent-Fingerprint und ein SHA-256-Hash des
+Idempotency Keys werden lokal ohne Prompts, Dateiinhalt, Tool-Argumente,
+ungefilterte Ergebnisse oder Credentials auditiert. Unterstützt das gepinnte
+OpenClaw-Schema kein `idempotencyKey`, dedupliziert Nexus lokal und sendet kein
+undokumentiertes Feld. Ein unklarer `in_doubt`-Zustand wird nicht automatisch
+wiederholt.
+
+Der JSONL-Ledger ist ein Single-Writer-Vertrag für genau eine Nexus-API-Instanz.
+Mehrere Replikas benötigen vor Schreibfreigabe einen gemeinsamen
+transaktionalen Ledger.
+
+## Event- und Run-Projektionen
+
+`GET /api/v1/openclaw/events` ist eine authentifizierte SSE-Projektion über den
+begrenzten Gateway-Eventpuffer. Sie unterstützt `Last-Event-ID`, Connection-,
+Heartbeat- und Gap-Signale und redigiert Payloads vor der Browsergrenze. Ein
+Cursor außerhalb des Puffers erzwingt einen autoritativen Refresh.
+
+Nexus persistiert Durable Runs und ihre Transitionen in PostgreSQL, ohne
+OpenClaws Runtimezustand zu übernehmen. Start, exakter Stop und korrelierter
+Retry sind implementiert. Same-run Resume bleibt explizit `unsupported`, bis
+der gepinnte Gateway-Vertrag einen belegten RPC bereitstellt.
+
+## Abnahmegrenze
+
+Lokale Contract-, Backend-, Frontend- und Browserprüfungen können Routing,
+Validierung, Redaction, Least Privilege, Hashkonflikte, Idempotenz und
+UI-Zustände belegen. Sie beweisen nicht:
+
+- eine offiziell unterstützte externe Nexus-/Generic-Client-ID;
+- eine reale Remote-Pairing- und Scope-Upgrade-Sequenz;
+- Live-Schreibvorgänge gegen eindeutig benannte Testobjekte auf Baos OpenClaw;
+  oder
+- einen vollständigen `Nexus -> OpenClaw -> OpenAI -> Nexus`-Lauf.
+
+Diese Nachweise sind verpflichtende Produktionsblocker. Live-Schreibtests,
+Pairing-Freigaben, OpenClaw-Patches, Deployment und Zugriffe außerhalb von
+Baos ausdrücklich freigegebenen Ressourcen gehören nicht zu diesem
+Implementierungscheckpoint.
+
+## Offizielle Protokollquellen
+
+- <https://github.com/openclaw/openclaw/blob/v2026.7.1/packages/gateway-protocol/src/client-info.ts>
+- <https://github.com/openclaw/openclaw/blob/v2026.7.1/docs/gateway/protocol.md>
+- <https://docs.openclaw.ai/gateway/operator-scopes>
+- <https://docs.openclaw.ai/gateway/configuration>
+- <https://docs.openclaw.ai/reference/wizard>
+- <https://docs.openclaw.ai/cli/cron>