Escopos de operador

Os escopos de operador definem o que um cliente do Gateway pode fazer depois de se autenticar. Eles são uma proteção do plano de controle dentro de um domínio confiável de operador do Gateway, não isolamento multi-inquilino hostil. Se você precisa de separação forte entre pessoas, equipes ou máquinas, execute Gateways separados sob usuários do SO ou hosts separados.

Relacionado: Segurança, Protocolo do Gateway, Emparelhamento do Gateway, CLI de dispositivos.

# Funções

Clientes WebSocket do Gateway se conectam com uma função:

• operator: clientes do plano de controle, como CLI, Control UI, automação e processos auxiliares confiáveis.
• node: hosts de capacidade, como macOS, iOS, Android ou nodes sem interface gráfica que expõem comandos por meio de node.invoke.

Métodos RPC de operador exigem a função operator. Métodos originados por Node exigem a função node.

# Níveis de escopo

Escopo	Significado
operator.read	Status somente leitura, listas, catálogo, logs, leituras de sessão e outras chamadas do plano de controle que não fazem mutação.
operator.write	Ações normais de operador que fazem mutação, como enviar mensagens, invocar ferramentas, atualizar configurações de fala/voz e retransmissão de comandos de Node. Também satisfaz operator.read.
operator.admin	Acesso administrativo ao plano de controle. Satisfaz todos os escopos operator.*. Exigido para mutação de configuração, atualizações, hooks nativos, namespaces reservados sensíveis e aprovações de alto risco.
operator.pairing	Gerenciamento de emparelhamento de dispositivos e Node, incluindo listar, aprovar, rejeitar, remover, rotacionar e revogar registros de emparelhamento ou tokens de dispositivo.
operator.approvals	APIs de aprovação de exec e Plugin.
operator.talk.secrets	Leitura da configuração do Talk com segredos incluídos.

Escopos operator.* futuros desconhecidos exigem uma correspondência exata, a menos que o chamador tenha operator.admin.

# O escopo do método é apenas a primeira barreira

Cada RPC do Gateway tem um escopo de método de menor privilégio. Esse escopo de método decide se a solicitação pode chegar ao manipulador. Alguns manipuladores então aplicam verificações mais estritas no momento da aprovação com base no item concreto que está sendo aprovado ou modificado.

Exemplos:

• device.pair.approve é acessível com operator.pairing, mas aprovar um dispositivo operador só pode emitir ou preservar escopos que o chamador já possui.
• node.pair.approve é acessível com operator.pairing e, em seguida, deriva escopos de aprovação extras da lista de comandos de Node pendente.
• chat.send normalmente é um método com escopo de escrita, mas /config set e /config unset persistentes exigem operator.admin no nível do comando.

Isso permite que operadores com escopo mais baixo realizem ações de emparelhamento de baixo risco sem tornar todas as aprovações de emparelhamento exclusivas de admin.

# Aprovações de emparelhamento de dispositivo

Registros de emparelhamento de dispositivo são a fonte durável de funções e escopos aprovados. Dispositivos já emparelhados não recebem acesso mais amplo silenciosamente: reconexões que solicitam uma função mais ampla ou escopos mais amplos criam uma nova solicitação de upgrade pendente.

Ao aprovar uma solicitação de dispositivo:

• Uma solicitação sem função de operador não precisa de aprovação de escopo de token de operador.
• Uma solicitação para operator.read, operator.write, operator.approvals, operator.pairing ou operator.talk.secrets exige que o chamador possua esses escopos ou operator.admin.
• Uma solicitação para operator.admin exige operator.admin.
• Uma solicitação de reparo sem escopos explícitos pode herdar os escopos de token de operador existentes. Se esse token existente tiver escopo de admin, a aprovação ainda exige operator.admin.

Para sessões de token de dispositivo emparelhado, o gerenciamento é autoescopado, a menos que o chamador também tenha operator.admin: chamadores não admin veem apenas suas próprias entradas de emparelhamento, podem aprovar ou rejeitar apenas sua própria solicitação pendente e podem rotacionar, revogar ou remover apenas sua própria entrada de dispositivo.

# Aprovações de emparelhamento de Node

O node.pair.* legado usa um armazenamento separado de emparelhamento de Node pertencente ao Gateway. Nodes WS usam emparelhamento de dispositivo com role: node, mas o mesmo vocabulário de nível de aprovação se aplica.

node.pair.approve usa a lista de comandos da solicitação pendente para derivar escopos necessários adicionais:

• Solicitação sem comandos: operator.pairing
• Comandos de Node não exec: operator.pairing + operator.write
• system.run, system.run.prepare ou system.which: operator.pairing + operator.admin

O emparelhamento de Node estabelece identidade e confiança. Ele não substitui a política própria de aprovação de exec system.run do Node.

# Autenticação por segredo compartilhado

Autenticação por token/senha compartilhados do gateway é tratada como acesso de operador confiável para esse Gateway. Superfícies HTTP compatíveis com OpenAI e /tools/invoke restauram o conjunto padrão normal completo de escopos de operador para autenticação bearer por segredo compartilhado, mesmo que um chamador envie escopos declarados mais restritos.

Modos com identidade, como autenticação por proxy confiável ou none em ingresso privado, ainda podem respeitar escopos declarados explícitos. Use Gateways separados para separação real de fronteiras de confiança.