Permissões

O que uma conta pode fazer num servidor é decidido por bits: cada cargo tem um número permissions, e cada canal pode liberar ou negar alguns bits por cargo ou por membro. Um bot é um membro como qualquer outro: seus cargos e a marcação de ADM decidem o que ele pode.

Bits

nome	valor	decimal	rótulo no app	o que permite
ADMINISTRATOR	1 << 0	1	Administrador	Pode tudo, inclusive o que não está nesta lista. Ignora as permissões de canal.
MANAGE_GUILD	1 << 1	2	Gerenciar o servidor	Mudar nome e ícone, ver e revogar convites, adicionar bots.
MANAGE_CHANNELS	1 << 2	4	Gerenciar canais	Criar, editar e excluir canais, salas e seções.
MANAGE_ROLES	1 << 3	8	Gerenciar cargos	Criar e editar cargos abaixo do seu e dá-los às pessoas. Num canal: editar as permissões dele.
KICK_MEMBERS	1 << 4	16	Remover pessoas	Tirar do servidor quem tem cargo abaixo do seu.
BAN_MEMBERS	1 << 5	32	Banir pessoas	Tirar e impedir de voltar, e desbanir.
MANAGE_MESSAGES	1 << 6	64	Gerenciar mensagens	Excluir mensagens de outras pessoas; fixar, trancar e moderar postagens; ignorar o modo lento.
MANAGE_NICKNAMES	1 << 7	128	Mudar apelidos	Trocar o apelido de quem tem cargo abaixo do seu.
CREATE_INVITE	1 << 8	256	Criar convites	Chamar gente nova para o servidor.
SEND_MESSAGES	1 << 9	512	Enviar mensagens	Escrever nos canais de texto e abrir postagens em fóruns.
ATTACH_FILES	1 << 10	1024	Enviar arquivos	Anexar imagens e arquivos.
CONNECT	1 << 11	2048	Entrar em salas	Entrar nas salas de voz para ouvir.
SPEAK	1 << 12	4096	Falar	Usar o microfone nas salas.
MANAGE_EMOJIS	1 << 13	8192	Gerenciar emojis	Enviar, renomear e excluir os emojis do servidor.
VIEW_CHANNEL	1 << 14	16384	Ver canais	Ver os canais e salas. Sem isso, só aparecem os canais liberados um a um.
ADD_REACTIONS	1 << 15	32768	Adicionar reações	Reagir com um emoji novo. Somar-se a uma reação que já existe sempre pode.
READ_MESSAGE_HISTORY	1 << 16	65536	Ler o histórico	Ver as mensagens enviadas antes (GET /channels/{id}/messages).
STREAM	1 << 17	131072	Vídeo e tela	Ligar a câmera e compartilhar a tela nas salas.

Todos os bits juntos valem 262143 ((1 << 18) - 1). Bits desconhecidos são descartados.

const P = { VIEW_CHANNEL: 1 << 14, SEND_MESSAGES: 1 << 9, READ_MESSAGE_HISTORY: 1 << 16 };
const pode = (perms, bit) => (perms & bit) === bit;

@everyone

Todo servidor tem o cargo @everyone, cujo id é o id do servidor. Todo membro tem esse cargo, mesmo que ele não apareça em member.roles. Num servidor novo, @everyone começa com:

CREATE_INVITE | SEND_MESSAGES | ATTACH_FILES | CONNECT | SPEAK | VIEW_CHANNEL | ADD_REACTIONS | READ_MESSAGE_HISTORY | STREAM = 253696

Ou seja: todo mundo vê os canais, conversa, manda arquivos, reage, lê o histórico, entra nas salas, fala, liga a câmera e convida gente. As permissões de gerenciamento ficam para cargos.

Permissões no servidor

As permissões de um membro no servidor inteiro são as de @everyone somadas (OU bit a bit) às de todos os cargos dele:

function base(guild, member) {
  const everyone = guild.roles.find((r) => r.id === guild.id);
  return guild.roles
    .filter((r) => member.roles.includes(r.id))
    .reduce((p, r) => p | r.permissions, everyone.permissions);
}

O membro é administrador, e pode tudo, se qualquer um destes for verdade:

• é o dono do servidor (guild.owner_id);
• é ADM (member.is_admin);
• algum cargo dele (ou @everyone) tem ADMINISTRATOR.

Permissões de canal

Cada canal de servidor pode ter uma lista de Overwrite (permission_overwrites): bits liberados (allow) e negados (deny) para um cargo (type 0) ou um membro (type 1). Só estes bits podem ser mudados por canal:

VIEW_CHANNEL, MANAGE_CHANNELS, MANAGE_ROLES, SEND_MESSAGES, ATTACH_FILES, ADD_REACTIONS, READ_MESSAGE_HISTORY, MANAGE_MESSAGES, CONNECT, SPEAK, STREAM.

As permissões de um membro num canal são calculadas como no Discord:

1. Administradores têm tudo, sempre. Pare aqui.
2. Comece pelas permissões no servidor (acima).
3. Aplique a permissão de canal de @everyone (o overwrite cujo id é o do servidor): tire o deny, ponha o allow.
4. Junte as permissões de canal de todos os cargos do membro: some todos os deny e todos os allow. Tire os deny somados, ponha os allow somados. (Então, entre cargos, liberar ganha de negar.)
5. Aplique a permissão de canal do próprio membro, se houver: tire o deny, ponha o allow.
6. Sem VIEW_CHANNEL, não sobra nada (o canal some para ele).
7. Sem SEND_MESSAGES, sai ATTACH_FILES.
8. Sem CONNECT, saem SPEAK e STREAM.

const OVERWRITE_ROLE = 0, OVERWRITE_MEMBER = 1;
const ALL = (1 << 18) - 1;

function noCanal(guild, member, channel) {
  let p = base(guild, member);
  const admin = guild.owner_id === member.user.id || member.is_admin || (p & 1) !== 0;
  if (admin) return ALL;
  const ows = channel.permission_overwrites ?? [];

  const todos = ows.find((o) => o.type === OVERWRITE_ROLE && o.id === guild.id);
  if (todos) p = (p & ~todos.deny) | todos.allow;

  let allow = 0, deny = 0;
  for (const o of ows) {
    if (o.type === OVERWRITE_ROLE && o.id !== guild.id && member.roles.includes(o.id)) {
      allow |= o.allow;
      deny |= o.deny;
    }
  }
  p = (p & ~deny) | allow;

  const meu = ows.find((o) => o.type === OVERWRITE_MEMBER && o.id === member.user.id);
  if (meu) p = (p & ~meu.deny) | meu.allow;

  if (!(p & (1 << 14))) return 0;              // VIEW_CHANNEL
  if (!(p & (1 << 9))) p &= ~(1 << 10);        // sem SEND_MESSAGES, sem ATTACH_FILES
  if (!(p & (1 << 11))) p &= ~((1 << 12) | (1 << 17)); // sem CONNECT, sem SPEAK e STREAM
  return p;
}

Detalhes:

• Postagens de fórum (tipo 11) usam as permissões do fórum. O permission_overwrites de uma postagem já vem com as do fórum.
• Um canal novo numa categoria começa com as permissões da categoria. Quando a categoria muda, os canais que ainda estavam iguais a ela mudam junto.
• Num Overwrite, deny ganha de allow para o mesmo bit; o servidor limpa o allow.
• Editar as permissões de um canal pede MANAGE_ROLES naquele canal, e só deixa mudar os bits que você tem lá.
• DMs não têm cargos: nelas as duas contas podem ver, escrever, mandar arquivos, reagir, ler o histórico e fazer chamadas.

O servidor só manda para cada conta os canais que ela pode ver (em READY, GUILD_CREATE e nos eventos). Quando um cargo ou uma permissão de canal muda, quem passou a ver um canal recebe CHANNEL_CREATE, e quem deixou de ver recebe CHANNEL_DELETE.

Hierarquia

Os cargos têm uma ordem (position: @everyone é 0; quanto maior, mais alto). O nível de um membro é a posição do seu cargo mais alto. Administradores ficam acima de todos os cargos, e o dono acima de todo mundo.

• Para editar, apagar, dar ou tirar um cargo, ele precisa estar abaixo do seu nível.
• Para remover, banir ou mudar o apelido de alguém, o nível dele precisa estar abaixo do seu. Só o dono age sobre ADMs.
• Ninguém dá ou tira uma permissão (de cargo ou de canal) que não tem.
• @everyone pode ser editado por quem tem MANAGE_ROLES, mas não apagado nem renomeado.

O cargo do bot

Um bot entra num servidor pelas mãos de alguém com Gerenciar o servidor, pelo link de convite do bot (veja Convites de bot) ou pela rota PUT /guilds/{guild_id}/bots/{bot_id}.

O link pede um número permissions. Quando o bot entra:

• se permissions não for 0, o servidor cria um cargo com o nome de exibição do bot (até 32 caracteres) e essas permissões, logo acima de @everyone, e dá esse cargo ao bot;
• quem adiciona só pode pedir permissões que tem;
• se permissions for 0, o bot fica só com @everyone.

Depois disso, é um cargo comum: o pessoal do servidor pode mudar as permissões dele, subir ou descer, ou dar outros cargos ao bot. Como o cargo nasce embaixo de todos, um bot com KICK_MEMBERS ou MANAGE_ROLES só alcança quem está abaixo dele; peça para subirem o cargo se ele precisar agir sobre outros.

O dono do servidor também pode fazer ADM um bot que seja dele (admin: true). Bots públicos de outras pessoas só recebem permissões pelo cargo.

Quanto pedir

Peça o mínimo. Um bot de comandos simples precisa de VIEW_CHANNEL | SEND_MESSAGES | READ_MESSAGE_HISTORY = 82432. Some ADD_REACTIONS (32768) se ele reagir e ATTACH_FILES (1024) se mandar arquivos.