Operator-Geltungsbereiche

Operator-Scopes definieren, was ein Gateway-Client nach der Authentifizierung tun darf. Sie sind ein Control-Plane-Schutzmechanismus innerhalb einer vertrauenswürdigen Gateway-Operator-Domäne, keine Isolation gegenüber feindlichen Mandanten in einer Mehrmandantenumgebung. Wenn Sie eine starke Trennung zwischen Personen, Teams oder Maschinen benötigen, betreiben Sie separate Gateways unter separaten OS-Benutzern oder Hosts.

Verwandt: Sicherheit, Gateway-Protokoll, Gateway-Kopplung, Geräte-CLI.

# Rollen

Gateway-WebSocket-Clients verbinden sich mit einer Rolle:

• operator: Control-Plane-Clients wie CLI, Control UI, Automatisierung und vertrauenswürdige Hilfsprozesse.
• node: Capability-Hosts wie macOS, iOS, Android oder headless Nodes, die Befehle über node.invoke bereitstellen.

Operator-RPC-Methoden erfordern die Rolle operator. Von Nodes ausgehende Methoden erfordern die Rolle node.

# Scope-Ebenen

Scope	Bedeutung
operator.read	Schreibgeschützter Status, Listen, Katalog, Logs, Sitzungslesevorgänge und andere nicht verändernde Control-Plane-Aufrufe.
operator.write	Normale verändernde Operator-Aktionen wie das Senden von Nachrichten, Aufrufen von Tools, Aktualisieren von Talk-/Voice-Einstellungen und Node-Befehlsweiterleitung. Erfüllt auch operator.read.
operator.admin	Administrativer Control-Plane-Zugriff. Erfüllt jeden operator.*-Scope. Erforderlich für Konfigurationsänderungen, Updates, native Hooks, sensible reservierte Namespaces und Genehmigungen mit hohem Risiko.
operator.pairing	Geräte- und Node-Kopplungsverwaltung, einschließlich Auflisten, Genehmigen, Ablehnen, Entfernen, Rotieren und Widerrufen von Kopplungsdatensätzen oder Gerätetokens.
operator.approvals	Exec- und Plugin-Genehmigungs-APIs.
operator.talk.secrets	Lesen der Talk-Konfiguration einschließlich Geheimnissen.

Unbekannte zukünftige operator.*-Scopes erfordern eine exakte Übereinstimmung, sofern der Aufrufer nicht operator.admin besitzt.

# Methoden-Scope ist nur die erste Schranke

Jeder Gateway-RPC hat einen Least-Privilege-Methoden-Scope. Dieser Methoden-Scope entscheidet, ob die Anfrage den Handler erreichen kann. Einige Handler wenden anschließend strengere Prüfungen zum Genehmigungszeitpunkt an, basierend auf dem konkreten Objekt, das genehmigt oder verändert wird.

Beispiele:

• device.pair.approve ist mit operator.pairing erreichbar, aber das Genehmigen eines Operator-Geräts kann nur Scopes ausstellen oder beibehalten, die der Aufrufer bereits besitzt.
• node.pair.approve ist mit operator.pairing erreichbar und leitet anschließend zusätzliche Genehmigungs-Scopes aus der ausstehenden Node-Befehlsliste ab.
• chat.send ist normalerweise eine Methode mit Schreib-Scope, aber persistente /config set und /config unset erfordern operator.admin auf Befehlsebene.

Dadurch können Operatoren mit niedrigerem Scope risikoarme Kopplungsaktionen durchführen, ohne alle Kopplungsgenehmigungen ausschließlich Admins vorzubehalten.

# Gerätekopplungsgenehmigungen

Gerätekopplungsdatensätze sind die dauerhafte Quelle für genehmigte Rollen und Scopes. Bereits gekoppelte Geräte erhalten nicht stillschweigend umfassenderen Zugriff: Wiederverbindungen, die eine umfassendere Rolle oder umfassendere Scopes anfordern, erzeugen eine neue ausstehende Upgrade-Anfrage.

Beim Genehmigen einer Geräteanfrage:

• Eine Anfrage ohne Operator-Rolle benötigt keine Scope-Genehmigung für Operator-Tokens.
• Eine Anfrage für operator.read, operator.write, operator.approvals, operator.pairing oder operator.talk.secrets erfordert, dass der Aufrufer diese Scopes oder operator.admin besitzt.
• Eine Anfrage für operator.admin erfordert operator.admin.
• Eine Reparaturanfrage ohne explizite Scopes kann die vorhandenen Operator-Token-Scopes übernehmen. Wenn dieses vorhandene Token Admin-Scope hat, erfordert die Genehmigung weiterhin operator.admin.

Für Token-Sitzungen gekoppelter Geräte ist die Verwaltung selbstbezogen, sofern der Aufrufer nicht zusätzlich operator.admin besitzt: Nicht-Admin-Aufrufer sehen nur ihre eigenen Kopplungseinträge, können nur ihre eigene ausstehende Anfrage genehmigen oder ablehnen und können nur ihren eigenen Geräteeintrag rotieren, widerrufen oder entfernen.

# Node-Kopplungsgenehmigungen

Das ältere node.pair.* verwendet einen separaten, Gateway-eigenen Node-Kopplungsspeicher. WS-Nodes verwenden Gerätekopplung mit role: node, aber dasselbe Vokabular für Genehmigungsebenen gilt.

node.pair.approve verwendet die ausstehende Anfragebefehlsliste, um zusätzliche erforderliche Scopes abzuleiten:

• Anfrage ohne Befehle: operator.pairing
• Nicht-Exec-Node-Befehle: operator.pairing + operator.write
• system.run, system.run.prepare oder system.which: operator.pairing + operator.admin

Node-Kopplung etabliert Identität und Vertrauen. Sie ersetzt nicht die eigene system.run-Exec-Genehmigungsrichtlinie des Nodes.

# Shared-Secret-Authentifizierung

Authentifizierung per gemeinsamem Gateway-Token/Passwort wird als vertrauenswürdiger Operator-Zugriff für dieses Gateway behandelt. OpenAI-kompatible HTTP-Oberflächen und /tools/invoke stellen den normalen vollständigen Standard-Scope-Satz für Operatoren bei Shared-Secret-Bearer-Authentifizierung wieder her, selbst wenn ein Aufrufer engere deklarierte Scopes sendet.

Identitätstragende Modi, wie vertrauenswürdige Proxy-Authentifizierung oder Private-Ingress-none, können weiterhin explizit deklarierte Scopes berücksichtigen. Verwenden Sie separate Gateways für eine echte Trennung von Vertrauensgrenzen.