Cluster · разработчикам

Права

Права модуля описываются в permissions пакета. Пользователь выбирает granted при установке. Ядро проверяет их при каждом действии, одного названия в описании недостаточно.

Описание

Для описания типов используем обычный TypedDict:

from typing import Literal, NotRequired, TypedDict

class Rule(TypedDict):
    chats: NotRequired[list[int] | Literal["*"]]
    users: NotRequired[list[int] | Literal["*"]]
    domains: NotRequired[list[str] | Literal["*"]]
    modules: NotRequired[list[str] | Literal["*"]]

type Permissions = dict[str, Rule]

permissions: Permissions = {
    "db.read": {},
    "db.write": {},
    "telegram.send": {"chats": [-1001234567890]},
    "web.request": {"domains": ["example.com"]},
    "modules.call": {"modules": ["MODULE_ID"]},
}

Это описание формата, а не обязательный импорт в модуле. В manifest.json те же данные записываются как JSON. Ключи Permissions берутся из перечня ниже, произвольные строки ядро не принимает.

{} у указанного права означает отсутствие дополнительных ограничений. Отсутствие самого права означает запрет. Список задаёт конкретные значения, "*" разрешает любые значения этого вида. Пустой список, например {"chats": []}, запрещает обращения в чаты. Пустой объект прав {} не даёт ничего.

Ограничения: chats, users, domains, modules. Чаты и пользователи задаются числами, сайты именами без схемы, порта и пути. Поддомены выбираются отдельно: example.com не включает api.example.com. ID модуля является ID публикации, профиль экземпляра выбирается отдельно.

Нельзя принять незаявленное право или расширить его список сверх описания автора. Неизвестное право и неизвестное ограничение отклоняются.

Перечень

Право	Возможность
`db.read`	Получение значения и ключей своего раздела
`db.write`	Запись и удаление своего раздела
`db.full`	Прикладные разделы других экземпляров того же юзербота
`telegram.read`	Свой профиль, сообщения, получение вложений и разрешённые события
`telegram.send`	Отправка, изменение и удаление сообщений, отправка файла
`telegram.profile`	Имя, описание, username и фотография аккаунта
`telegram.full`	Полный набор открытых методов Telegram, включая общий TL-запрос
`bot.read`	Сведения о личном боте и разрешённые события
`bot.send`	Сообщения, клавиатуры и файлы личного бота
`bot.full`	Открытый перечень Bot API с общими параметрами
`web.request`	HTTPS/WSS с ограничением сайтов
`web.full`	Любые внешние сайты через вебклиент ядра
`modules.call`	Функции и события выбранных модулей
`exchange.request`	Запрос, получение и использование договора своего экземпляра
`tasks.create`	Создание, состояние, отмена и удаление задач своего экземпляра
`files.read`	Список и получение доступных файлов
`files.write`	Загрузка и удаление своих файлов
`files.full`	Файлы других разделов того же юзербота
`logs.write`	Запись в журнал
`requests.manage`	Создание и отзыв ключа входящего запроса
`core.info`	Ник, версия ядра, время работы, префикс и число модулей
`core.configure`	Префикс, язык уведомлений, срок хранения журнала и обычные уведомления по действующему событию овнера в личном чате
`modules.configure`	Просмотр и изменение обычных настроек и названий команд выбранных модулей по действующему событию овнера в личном чате; без секретов и файлов
`config.read`	Получение конфигурации экземпляра
`interface.read`	Получение значений своей страницы
`interface.write`	Запись значений своей страницы

Полное право семейства разрешает его отдельные операции. Например, db.full позволяет читать и изменять прикладные разделы своего юзербота. Ограничения пользователя продолжают действовать. Полное право не открывает данные другого юзербота или служебную базу.

Настройки пользователя

Овнер задаёт общие rules юзербота и, при необходимости, правила экземпляра. Локальное правило той же операции перекрывает общее. Отсутствие локального правила наследует общее. Явный пустой список локального правила запрещает соответствующий доступ.

Пример общего правила: {"telegram.send": {"chats": "*"}}. Для одного экземпляра можно задать {"telegram.send": {"chats": [-1001234567890]}}. Остальные экземпляры сохранят общее правило. Это не добавляет telegram.send модулю, который его не заявил или не получил.

telegram.full и bot.full не отменяют ограничения отдельных методов. Общий запрос с непроверяемыми адресатами отклоняется при ограничении по чатам или пользователям. Не нужно выдавать его для обычной отправки сообщения.

Овнеры и доверка

Овнер управляет юзерботом и его прикладными данными. Первоначального овнера удалить нельзя. Дополнительный овнер входит через свой профиль, критические действия подтверждает своим паролем и TOTP.

Доверка получает список действий и необязательные списки для экземпляров. Локальный список заменяет общий, пустой список отключает доступ к этому экземпляру. В командах можно разрешить все команды через command.execute либо конкретную через command.ID.

Доступ обработчика задаётся как owner, trusted или public. Доверка не становится овнером из-за доступа к одной команде. Изменение Telegram-профиля, обращение вне чата команды и получение полного прикладного доступа требуют соответствующего действия доверки. Терминал доверке не выдаётся.

Вызов и остановка

Событие связано с юзерботом, экземпляром, текущим подключением и человеком. Передача функции или события другому модулю сохраняет полномочия исходного вызова. Каждый участник цепочки проверяется, более привилегированная зависимость не отменяет ограничения вызывающего.

Остановка отзывает подключение. Новые запросы через старый ключ не принимаются. Уже отправленное внешнее действие нельзя отменить задним числом; после неизвестного результата вызывающий проверяет фактическое состояние.

Модуль не получает фактическую Telegram-сессию, токен личного бота, операторский сокет или API запуска терминала при любом наборе прав. API принимает данные JSON, а не объекты клиента, пути сервера или произвольное выражение для выполнения в ядре.