Portées d'opérateur

Les portées d’opérateur définissent ce qu’un client Gateway peut faire après s’être authentifié. Elles constituent un garde-fou du plan de contrôle à l’intérieur d’un domaine d’opérateur Gateway de confiance, et non une isolation multitenante hostile. Si vous avez besoin d’une séparation forte entre les personnes, les équipes ou les machines, exécutez des Gateways distincts sous des utilisateurs ou des hôtes OS distincts.

Voir aussi : Sécurité, Protocole Gateway, Jumelage Gateway, CLI des appareils.

Rôles

Les clients WebSocket Gateway se connectent avec un rôle :

operatorCLI : clients du plan de contrôle tels que le CLI, l’interface de contrôle, l’automatisation et les processus d’assistance de confiance.
nodemacOSiOSAndroid : hôtes de capacités tels que macOS, iOS, Android ou des nœuds sans interface qui exposent des commandes via node.invoke.

Les méthodes RPC d’opérateur nécessitent le rôle RPCoperator. Les méthodes originaires des nœuds nécessitent le rôle node.

Niveaux de portée

Portée	Signification
`operator.read`	Statut en lecture seule, listes, catalogue, journaux, lectures de session et autres appels de plan de contrôle non modificateurs.
`operator.write`	Actions normales modifiant l’opérateur telles que l’envoi de messages, l’appel d’outils, la mise à jour des paramètres talk/voice et le relais de commandes de nœud. Satisfait également `operator.read`.
`operator.admin`	Accès administratif au plan de contrôle. Satisfait toutes les portées `operator.*`. Requis pour la modification de la configuration, les mises à jour, les hooks natifs, les espaces de noms réservés sensibles et les approbations à haut risque.
`operator.pairing`	Gestion de l’appairage des appareils et des nœuds, y compris la liste, l’approbation, le rejet, la suppression, la rotation et la révocation des enregistrements d’appairage ou des jetons d’appareil.
`operator.approvals`	API d’approbation Exec et de plugin.
`operator.talk.secrets`	Lecture de la configuration Talk, secrets inclus.

Les étendues (scopes) operator.* inconnues futures nécessitent une correspondance exacte, sauf si l’appelant possède operator.admin.

L’étendue de la méthode est uniquement la première porte

Chaque Gateway RPC possède une étendue de méthode de moindre privilège. Cette étendue de méthode détermine si la demande peut atteindre le gestionnaire. Certains gestionnaires appliquent ensuite des vérifications plus strictes au moment de l’approbation, basées sur l’élément concret en cours d’approbation ou de modification.

Exemples :

device.pair.approve est accessible avec operator.pairing, mais l’approbation d’un appareil opérateur ne peut créer ou conserver que les étendues que l’appelant possède déjà.
node.pair.approve est accessible avec operator.pairing, puis dérive des étendues d’approbation supplémentaires à partir de la liste des commandes de nœud en attente.
chat.send est normalement une méthode à portée d’écriture, mais /config set persistantes et /config unset nécessitent operator.admin au niveau de la commande.

Cela permet aux opérateurs ayant une étendue plus réduite d’effectuer des actions d’appairage à faible risque sans avoir à rendre toutes les approbations d’appairage réservées aux administrateurs.

Approbations d’appairage d’appareil

Les enregistrements d’appairage d’appareils sont la source durable des rôles et des étendues approuvés. Les appareils déjà appairés n’obtiennent pas un accès plus large silencieusement : les reconnexions qui demandent un rôle plus large ou des étendues plus larges créent une nouvelle demande de mise à niveau en attente.

Lors de l’approbation d’une demande d’appareil :

Une demande sans rôle d’opérateur ne nécessite pas d’approbation de l’étendue du jeton d’opérateur.
Une demande pour un rôle d’appareil non-opérateur, tel que node, nécessite operator.admin, même lorsque device.pair.approve est accessible avec operator.pairing.
Une demande pour operator.read, operator.write, operator.approvals, operator.pairing, ou operator.talk.secrets exige que l’appelant détienne ces portées, ou operator.admin.
Une demande pour operator.admin nécessite operator.admin.
Une demande de réparation sans portées explicites peut hériter des portées du jeton d’opérateur existant. Si ce jeton existant a une portée admin, l’approbation nécessite quand même operator.admin.

Les sessions de secret partagé et de proxy de confiance non-admin peuvent approuver les demandes opérateur-appareil uniquement à l’intérieur de leurs propres portées d’opérateur déclarées. L’approbation de rôles non-opérateur est réservée aux administrateurs, même lorsque ces sessions peuvent autrement utiliser operator.pairing.

Pour les sessions de jeton d’appareil jumelé, la gestion est également à portée restreinte (self-scoped) sauf si l’appelant a operator.admin : les appelants non-admin ne voient que leurs propres entrées de jumelage, ne peuvent approuver ou rejeter que leur propre demande en attente, et ne peuvent faire pivoter, révoquer ou supprimer que leur propre entrée d’appareil.

Approbations de jumelage de nœud

Le node.pair.*Gateway hérité utilise un magasin de jumelage de nœud distinct appartenant au Gateway. Les nœuds WS utilisent le jumelage d’appareil avec role: node, mais le même vocabulaire de niveau d’approbation s’applique.

node.pair.approve utilise la liste des commandes de demande en attente pour dériver des portées requises supplémentaires :

Demande sans commande : operator.pairing
Commandes de nœud non-exec : operator.pairing + operator.write
system.run, system.run.prepare, ou system.which : operator.pairing + operator.admin

L’appairage de nœuds établit l’identité et la confiance. Il ne remplace pas la propre stratégie d’approbation d’exécution system.run du nœud.

Authentification par secret partagé

L’authentification par jeton/mot de passe partagé de la passerelle est traitée comme un accès opérateur de confiance pour ce Gateway. Les surfaces HTTP compatibles OpenAI, /tools/invoke, et les points de terminaison l’historique des sessions HTTP restaurent l’ensemble normal complet des étendues par défaut de l’opérateur pour l’authentification du porteur par secret partagé, même si l’appelant envoie des étendues déclarées plus étroites.

Les modes porteurs d’identité, tels que l’authentification par proxy de confiance ou l’entrée privée none, peuvent toujours honorer les étendues déclarées explicites. Utilisez des passerelles distinctes pour une séparation réelle des limites de confiance.