Escopos do operador

Os escopos de operador controlam o que um cliente do Gateway pode fazer após 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 um isolamento multitenant contra agentes hostis. Para uma separação forte entre pessoas, equipes ou máquinas, execute Gateways separados sob usuários do sistema operacional ou hosts distintos.

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

Funções

Cada cliente WebSocket do Gateway se conecta com uma função:

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

Os métodos RPC de operador exigem a função operator; os métodos originados em um Node exigem a função node.

Níveis de escopo

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

O escopo do método é apenas a primeira barreira

Cada RPC do Gateway tem um escopo de método com privilégio mínimo que determina se uma solicitação chega ao seu manipulador. Alguns manipuladores aplicam verificações mais rigorosas com base no item específico que está sendo aprovado ou alterado:

• device.pair.approve pode ser acessado com operator.pairing, mas a aprovação de um dispositivo de operador só pode emitir ou preservar escopos que o chamador já possui.
• node.pair.approve pode ser acessado com operator.pairing e, em seguida, deriva escopos adicionais de aprovação da lista de comandos declarada pelo Node pendente.
• chat.send é um método com escopo de escrita, mas os comandos de chat /config set e /config unset exigem também operator.admin, independentemente do escopo de envio de chat do chamador.

Isso permite que operadores com escopos menores realizem ações de emparelhamento de baixo risco sem fazer com que toda aprovação de emparelhamento seja exclusiva de administradores.

Aprovações de emparelhamento de dispositivos

Os registros de emparelhamento de dispositivos são a fonte persistente das funções e dos escopos aprovados. Um dispositivo já emparelhado não recebe silenciosamente um acesso mais amplo: uma reconexão que solicita uma função ou escopos mais amplos cria uma nova solicitação de atualização pendente.

Ao aprovar uma solicitação de dispositivo:

• Uma solicitação sem a função de operador não precisa de aprovação de escopo de operador.
• Uma solicitação de função de dispositivo que não seja de operador (por exemplo, node) exige operator.admin, embora device.pair.approve precise apenas de operator.pairing.
• Uma solicitação de operator.read, operator.write, operator.approvals, operator.pairing ou operator.talk.secrets exige que o chamador já tenha esse escopo ou operator.admin.
• Uma solicitação de operator.admin exige operator.admin.
• Uma solicitação de reparo sem escopos explícitos pode herdar os escopos do token de operador existente; se esse token tiver escopo administrativo, a aprovação ainda exigirá operator.admin.

Sessões não administrativas de segredo compartilhado e de proxy confiável só podem aprovar solicitações de dispositivos de operador dentro de seus próprios escopos de operador declarados; a aprovação de funções que não sejam de operador é exclusiva de administradores, mesmo quando essas sessões podem usar operator.pairing para outras finalidades.

Para sessões de token de dispositivo emparelhado, o gerenciamento é limitado ao próprio dispositivo, a menos que o chamador tenha operator.admin: um chamador não administrativo vê apenas suas próprias entradas de emparelhamento e só pode aprovar, rejeitar, rotacionar, revogar ou remover a entrada do próprio dispositivo.

Aprovações de emparelhamento de Nodes

Os métodos legados node.pair.* usam um armazenamento separado de emparelhamento de Nodes pertencente ao Gateway. Os Nodes WS usam o emparelhamento de dispositivos (role: node), mas o mesmo vocabulário de aprovação se aplica. Consulte Emparelhamento do Gateway para saber como os dois armazenamentos se relacionam.

node.pair.approve deriva escopos obrigatórios adicionais da lista de comandos da solicitação pendente:

A aprovação da declaração de um Node não habilita comandos que tenham uma barreira separada de lista de permissões em tempo de execução. Por exemplo, aprovar um Node que declara computer.act exige escopo de emparelhamento e de escrita, mas apenas registra a superfície. Um administrador ou proprietário ainda precisa ativar computer.act. Enquanto ele permanecer ativado, sua invocação por meio do método node.invoke, com escopo de escrita, não exigirá escopo administrativo para cada ação.

O emparelhamento de Nodes estabelece identidade e confiança; ele não substitui a política de aprovação de execução de system.run do próprio Node.

Autenticação por segredo compartilhado

A autenticação por token/senha compartilhada do Gateway é tratada como acesso confiável de operador para esse Gateway. Superfícies HTTP compatíveis com a OpenAI, /tools/invoke e endpoints HTTP de histórico de sessões restauram o conjunto completo de escopos padrão de operador para autenticação de portador por segredo compartilhado, mesmo que um chamador envie escopos declarados mais restritos.

Modos que incluem identidade, como autenticação por proxy confiável ou none em ingresso privado, ainda podem respeitar escopos declarados explicitamente. Use Gateways separados para uma separação real dos limites de confiança.