Скрыть кнопку в интерфейсе недостаточно. Административная команда должна иметь ограничения при регистрации и повторную проверку в handler перед изменением ролей, каналов или данных. Так ошибка синхронизации команды не превращается в выполненное действие.
Начните с тестового сервера и трёх ролей: обычный участник, модератор с требуемым permission и Administrator. Сохраните command ID, guild ID, channel ID, member permissions и результат проверки. Токен бота, подпись interaction и имена пользователей в лог не попадают.
Доступ складывается из нескольких слоёв
| Слой | Что контролирует | Типичная ошибка |
|---|---|---|
| contexts | Guild, bot DM, private channel | Опасная команда доступна вне guild |
| default_member_permissions | Права по умолчанию для команды | Поле не задано и команда открыта |
| Guild command overrides | Роли, пользователи и каналы | Старое разрешающее исключение |
| Channel permissions | Эффективные права в месте вызова | Проверены только роли по имени |
| Handler policy | Конкретный target и бизнес-условия | Действие запускается до проверки |
| Bot permissions | Может ли бот выполнить операцию | Проверен пользователь, но не app_permissions |
Discord хранит permissions как строковое целое и рекомендует Big Integer для устойчивой обработки. Сравнение названия роли или преобразование bitset в обычный 32-битный number даёт ложные решения при новых флагах.
Регистрация задаёт безопасное значение по умолчанию
required = Permissions.MANAGE_GUILD
command.contexts = [InteractionContextType.GUILD]
command.default_member_permissions = required.toString()
onInteraction(i):
if i.guild_id is null: denyEphemeral("Guild only")
if (BigInt(i.member.permissions) & required) != required:
denyEphemeral("Not permitted")
authorizeTarget(i.member, i.options)
requireBotPermissions(i.app_permissions)
performActionOnce(i.id)default_member_permissions — сериализованный bitset. Значение "0" запрещает команду всем по умолчанию, кроме администраторов и явных overrides. Если по бизнес-правилу даже Administrator не должен выполнять операцию, это ограничение реализуется в собственной policy handler, потому что Discord позволяет администраторам использовать все команды.
Права по имени роли дают неверный ответ
- Роль можно переименовать без изменения полномочий.
- Несколько ролей объединяют базовые permissions.
- Channel overwrite может разрешить или запретить действие.
- Administrator обходит channel overwrites.
- Member-specific overwrite применяется после role overwrites.
Если продукт использует собственную allowlist ролей, храните role IDs конкретного guild и всё равно учитывайте контекст канала и целевой объект. Чужой guild не должен пройти только потому, что там существует роль с тем же названием.
Проверка стоит перед первым side effect
Не создавайте audit row, очередь удаления или внешний запрос до авторизации, если сам факт операции чувствителен. После отказа верните ephemeral-ответ без лишних деталей. Успешную команду делайте идемпотентной по interaction ID, чтобы retry не повторил изменение.
Синхронизация команды не стирает исключения незаметно
При переименовании или удалении команды её permissions могут быть потеряны. Деплой сравнивает зарегистрированный JSON с ожидаемым и отдельно проверяет guild overrides. Для быстрого теста используйте guild command, а глобальную публикацию выполняйте после проверки модели доступа.
HTTP endpoint принимает только подлинные interactions
Если interactions приходят через HTTP, сервер проверяет подписи Discord до разбора команды. Это другой слой, чем member permissions: подпись подтверждает источник запроса, но не право пользователя на административное действие. Оба условия обязательны.
Матрица тестов включает отказ
- Обычный участник не видит команду и получает отказ при прямом вызове.
- Модератор с требуемым permission выполняет разрешённый target.
- Тот же модератор получает отказ в закрытом channel при нужной политике.
- Вызов в DM отвергается до бизнес-логики.
- Administrator проходит или блокируется собственной policy согласно требованиям.
- Повтор одного interaction ID не выполняет side effect второй раз.
Для разбора подготовьте JSON команды без application token, список ожидаемых permission flags, обезличенный interaction и решение policy для одного target. Этого достаточно, чтобы отделить ошибку регистрации от ошибки обработчика и не давать доступ к рабочему серверу Discord.