Clawnet-Refactor (Protokoll + Auth-Vereinheitlichung)

Hi

Hi Peter — gute Richtung; das ermoeglicht einfachere UX + staerkere Sicherheit.

Zweck

Ein einziges, rigoroses Dokument fuer:

Ist-Zustand: Protokolle, Flows, Vertrauensgrenzen.
Schmerzpunkte: Approvals, Multi-Hop-Routing, UI-Duplikation.
Vorgeschlagener Soll-Zustand: ein Protokoll, begrenzte Rollen, vereinheitlichte Auth/Pairing, TLS-Pinning.
Identitaetsmodell: stabile IDs + niedliche Slugs.
Migrationsplan, Risiken, offene Fragen.

Ziele (aus der Diskussion)

Ein Protokoll fuer alle Clients (Mac-App, CLI, iOS, Android, headless Node).
Jeder Netzwerkteilnehmer authentifiziert + gepairt.
Rollenklarheit: Nodes vs. Operators.
Zentrale Approvals, geroutet dorthin wo der Benutzer ist.
TLS-Verschluesselung + optionales Pinning fuer allen Remote-Traffic.
Minimale Code-Duplikation.
Einzelne Maschine sollte einmal erscheinen (kein UI/Node-Doppeleintrag).

Nicht-Ziele (explizit)

Capability-Separation entfernen (Least-Privilege wird weiterhin benoetigt).
Volle Gateway-Steuerungsebene ohne Scope-Pruefungen exponieren.
Auth von menschlichen Labels abhaengig machen (Slugs bleiben nicht-sicherheitsrelevant).

Ist-Zustand

Zwei Protokolle

1) Gateway WebSocket (Steuerungsebene)

Volle API-Oberflaeche: Config, Channels, Models, Sessions, Agent-Runs, Logs, Nodes usw.
Standard-Bind: Loopback. Remote-Zugang via SSH/Tailscale.
Auth: Token/Passwort via connect.
Kein TLS-Pinning (verlaesst sich auf Loopback/Tunnel).

2) Bridge (Node-Transport)

Schmale Allowlist-Oberflaeche, Node-Identitaet + Pairing.
JSONL ueber TCP; optionales TLS + Cert-Fingerprint-Pinning.
TLS bewirbt Fingerprint im Discovery-TXT.

Steuerungsebenen-Clients heute

CLI, macOS-App UI, Web Control UI, ACP — alle via Gateway WS.
Browser-Control nutzt eigenen HTTP-Control-Server.

Nodes heute

macOS-App im Node-Modus verbindet sich mit Gateway Bridge.
iOS/Android-Apps verbinden sich mit Gateway Bridge.
Pairing + Per-Node-Token auf Gateway gespeichert.

Aktueller Approval-Flow (exec)

Agent nutzt system.run via Gateway. Gateway ruft Node ueber Bridge auf. Node-Runtime entscheidet Approval. UI-Prompt auf Node-Host. Multi-Hop, UI an Node-Host gebunden.

Presence + Identitaet heute

Gateway-Presence-Eintraege von WS-Clients.
Node-Presence-Eintraege von Bridge.
Mac-App kann zwei Eintraege fuer dieselbe Maschine zeigen (UI + Node).

Probleme / Schmerzpunkte

Zwei Protokollstacks zu pflegen (WS + Bridge).
Approvals auf Remote-Nodes: Prompt erscheint auf Node-Host, nicht wo der Benutzer ist.
TLS-Pinning existiert nur fuer Bridge; WS haengt von SSH/Tailscale ab.
Identitaets-Duplikation: dieselbe Maschine erscheint als mehrere Instanzen.
Mehrdeutige Rollen: UI + Node + CLI-Capabilities nicht klar getrennt.

Vorgeschlagener Soll-Zustand (Clawnet)

Ein Protokoll, zwei Rollen

Einzelnes WS-Protokoll mit Rolle + Scope.

Rolle: Node (Capability-Host)
Rolle: Operator (Steuerungsebene)
Optionaler Scope fuer Operator: operator.read, operator.write, operator.admin

Rollenverhalten

Node: Kann Capabilities registrieren, invoke-Befehle empfangen, Events senden. Kann keine Steuerungsebenen-APIs aufrufen.

Operator: Volle Steuerungsebenen-API durch Scope begrenzt. Empfaengt alle Approvals. Routet an Nodes statt direkt auszufuehren.

Schluesselregel

Rolle ist pro Verbindung, nicht pro Geraet. Ein Geraet kann beide Rollen separat oeffnen.

Vereinheitlichte Authentifizierung + Pairing

Client-Identitaet

Jeder Client liefert: deviceId (stabil), displayName, role + scope + caps + commands.

Pairing-Flow (vereinheitlicht)

Client verbindet unauthentifiziert -> Gateway erstellt Pairing-Request -> Operator genehmigt/verweigert -> Gateway stellt Credentials aus -> Client persistiert Token, verbindet sich authentifiziert neu.

Geraetegebundene Auth

Bevorzugt: Geraete-Schluesselpaare. deviceId = fingerprint(publicKey). Gateway sendet Nonce; Geraet signiert; Gateway verifiziert.

Stilles Approval (SSH-Heuristik)

Nur lokal: Auto-Pair via Loopback/Unix-Socket.
Challenge via SSH: Gateway stellt Nonce; Client beweist SSH.
Physisches-Presence-Fenster: nach lokalem Approval kurzes Auto-Pair-Fenster.

TLS ueberall (Dev + Prod)

Bestehendes Bridge-TLS wiederverwenden und auf WS anwenden. Discovery bewirbt TLS + Fingerprint (nur Locator-Hints, nie Trust-Anchor).

Approvals-Redesign (zentralisiert)

Approval wird gateway-gehostet, UI an Operator-Clients ausgeliefert. Broadcast an alle Operators; erste Aufloesung gewinnt. Standard-Timeout: Verweigerung nach N Sekunden.

Rollenklarheits-Beispiele

iPhone-App: Node-Rolle fuer Mikrofon/Kamera/Voice; optionales operator.read.
macOS-App: Operator-Rolle standardmaessig; Node-Rolle wenn aktiviert. Dieselbe deviceId -> zusammengefuehrter UI-Eintrag.
CLI: Operator-Rolle immer. Scope nach Subbefehl.

Identitaet + Slugs

Stabile ID: Schluesselpaar-Fingerprint (aendert sich nie).
Niedlicher Slug (Lobster-themed): Nur menschliches Label (scarlet-claw, saltwave). Im Gateway-Registry gespeichert, bearbeitbar.
UI-Gruppierung: Dieselbe deviceId ueber Rollen -> einzelne Instanz-Zeile.

Migrationsstrategie

Phase 0: Dokumentieren + abstimmen.
Phase 1: Rollen/Scopes zu WS hinzufuegen.
Phase 2: Bridge-Kompatibilitaet (parallel laufen lassen).
Phase 3: Zentrale Approvals.
Phase 4: TLS-Vereinheitlichung.
Phase 5: Bridge deprecaten.
Phase 6: Geraetegebundene Auth.

Sicherheitshinweise

Rollen-/Allowlist-Durchsetzung an der Gateway-Grenze.
Pairing erforderlich fuer alle Verbindungen.
TLS + Pinning reduziert MITM-Risiko fuer Mobilgeraete.
Discovery ist niemals ein Trust-Anchor.
Capability-Claims werden gegen Server-Allowlists verifiziert.

Streaming + grosse Payloads (Node-Medien)

Optionen: WS-Binary-Frames + Chunking, separater Streaming-Endpunkt, oder Bridge laenger fuer Medien behalten. Vor Implementierung entscheiden.

Offene Fragen

Einzelnes Geraet mit beiden Rollen: separate Tokens pro Rolle empfohlen.
Operator-Scope-Granularitaet: read/write/admin + Approvals + Pairing (Minimum Viable).
Token-Rotation + Widerrufs-UX.
Discovery: Bonjour-TXT erweitern um WS-TLS-Fingerprint.
Netzwerkuebergreifendes Approval: Broadcast; erste Antwort gewinnt.

Zusammenfassung (TL;DR)

Heute: WS-Steuerungsebene + Bridge-Node-Transport.
Schmerz: Approvals + Duplikation + zwei Stacks.
Vorschlag: Ein WS-Protokoll mit expliziten Rollen + Scopes, vereinheitlichtes Pairing + TLS-Pinning, gateway-gehostete Approvals, stabile Geraete-IDs + niedliche Slugs.
Ergebnis: Einfachere UX, staerkere Sicherheit, weniger Duplikation, besseres Mobile-Routing.