Gateway

Області дії оператора

Області дії оператора обмежують можливості клієнта Gateway після автентифікації. Вони є запобіжником площини керування в межах одного довіреного домену оператора Gateway, а не ізоляцією від ворожих орендарів у багатокористувацькому середовищі. Для надійного розмежування між людьми, командами або машинами запускайте окремі Gateway від імені окремих користувачів ОС або на окремих хостах.

Пов’язані матеріали: Безпека, Протокол Gateway, Сполучення Gateway, CLI пристроїв.

Ролі

Кожен WebSocket-клієнт Gateway підключається з однією роллю:

operator: клієнти площини керування, як-от CLI, інтерфейс керування, засоби автоматизації та довірені допоміжні процеси.
node: хости можливостей (macOS, iOS, Android, без графічного інтерфейсу), які надають команди через node.invoke.

Методи RPC оператора потребують ролі operator; методи, ініційовані вузлом, потребують ролі node.

Рівні областей дії

Область дії	Значення
`operator.read`	Стан, списки, каталог, журнали, читання сеансів та інші виклики, що не вносять змін, лише для читання.
`operator.write`	Дії оператора, що вносять зміни: надсилання повідомлень, виклик інструментів, оновлення налаштувань розмови й голосу, ретрансляція команд вузла. Також задовольняє вимогу `operator.read`.
`operator.admin`	Адміністративний доступ. Задовольняє вимоги всіх областей `operator.*`. Потрібний для зміни конфігурації, оновлень, нативних хуків, зарезервованих просторів імен і схвалень із високим ризиком.
`operator.pairing`	Керування сполученням пристроїв і вузлів: перегляд списку, схвалення, відхилення, видалення, ротація, відкликання.
`operator.approvals`	API схвалення виконання команд і плагінів.
`operator.talk.secrets`	Читання конфігурації розмови з включеними секретами.

Майбутні невідомі області operator.* потребують точного збігу, якщо викликач ще не має operator.admin.

Область дії методу — лише перша перевірка

Кожен RPC Gateway має область дії методу за принципом найменших привілеїв, яка визначає, чи дійде запит до його обробника. Деякі обробники потім застосовують суворіші перевірки залежно від конкретного об’єкта, який схвалюють або змінюють:

device.pair.approve доступний з operator.pairing, але схвалення пристрою оператора може створити або зберегти лише ті області дії, які вже має викликач.
node.pair.approve доступний з operator.pairing, а потім визначає додаткові області дії для схвалення зі списку команд, оголошених вузлом, що очікує схвалення.
chat.send є методом з областю дії запису, але команди чату /config set і /config unset додатково потребують operator.admin, незалежно від області дії викликача для надсилання повідомлень чату.

Це дає операторам із меншими областями дії змогу виконувати низькоризикові дії зі сполучення, не вимагаючи адміністративного доступу для всіх схвалень сполучення.

Схвалення сполучення пристроїв

Записи сполучення пристроїв є постійним джерелом схвалених ролей та областей дії. Уже сполучений пристрій не отримує ширший доступ непомітно: повторне підключення, що запитує ширшу роль або ширші області дії, створює новий запит на розширення доступу, який очікує схвалення.

Схвалення запиту пристрою:

Запит без ролі оператора не потребує схвалення області дії оператора.
Запит ролі пристрою, відмінної від оператора (наприклад, node), потребує operator.admin, хоча сам device.pair.approve потребує лише operator.pairing.
Запит operator.read, operator.write, operator.approvals, operator.pairing або operator.talk.secrets вимагає, щоб викликач уже мав відповідну область дії або operator.admin.
Запит operator.admin потребує operator.admin.
Запит на відновлення без явно вказаних областей дії може успадкувати області дії наявного токена оператора; якщо цей токен має адміністративну область дії, схвалення все одно потребує operator.admin.

Сеанси зі спільним секретом без адміністративних прав і сеанси довіреного проксі можуть схвалювати запити пристроїв оператора лише в межах власних оголошених областей дії оператора; схвалення неоператорських ролей доступне лише адміністратору, навіть якщо ці сеанси в інших випадках можуть використовувати operator.pairing.

Для сеансів із токеном сполученого пристрою керування обмежене власним пристроєм, якщо викликач не має operator.admin: викликач без адміністративних прав бачить лише власні записи сполучення та може схвалювати, відхиляти, ротувати, відкликати або видаляти лише запис власного пристрою.

Схвалення сполучення вузлів

Застарілі методи node.pair.* використовують окреме сховище сполучень вузлів, яким володіє Gateway. Вузли WS натомість використовують сполучення пристроїв (role: node), але застосовується та сама термінологія схвалення. Відомості про зв’язок між цими двома сховищами див. у розділі Сполучення Gateway.

node.pair.approve визначає додаткові потрібні області дії зі списку команд у запиті, що очікує схвалення:

Оголошені команди	Потрібні області дії
немає	`operator.pairing`
команди вузла, не пов’язані з виконанням	`operator.pairing` + `operator.write`
`system.run`, `system.run.prepare` або `system.which`	`operator.pairing` + `operator.admin`

Схвалення декларації вузла не вмикає команди, для яких існує окрема перевірка списку дозволів під час виконання. Наприклад, схвалення вузла, що оголошує computer.act, потребує області сполучення та запису, але лише реєструє цю можливість. Адміністратор або власник усе одно має активувати computer.act. Поки ця можливість залишається активованою, її виклик через метод node.invoke з областю дії запису не потребує адміністративної області дії для кожної операції.

Сполучення вузла встановлює ідентичність і довіру; воно не замінює власну політику схвалення виконання system.run цього вузла.

Автентифікація зі спільним секретом

Автентифікація за допомогою спільного токена або пароля Gateway вважається довіреним доступом оператора до цього Gateway. HTTP-інтерфейси, сумісні з OpenAI, /tools/invoke та HTTP-кінцеві точки історії сеансів відновлюють повний стандартний набір областей дії оператора для автентифікації носія зі спільним секретом, навіть якщо викликач надсилає вужчі оголошені області дії.

Режими з ідентифікацією, як-от автентифікація через довірений проксі або none для приватного вхідного доступу, можуть і надалі враховувати явно оголошені області дії. Для справжнього розмежування меж довіри використовуйте окремі Gateway.

Was this useful?