Âmbitos

Um conjunto fechado, resource:action. Pequeno o suficiente para mostrar a uma pessoa numa lista de caixas de seleção, e estável o suficiente para que uma concessão guardada continue a significar o mesmo um ano depois. É o mesmo vocabulário em que uma FUNÇÃO de espaço de trabalho é escrita e que controla as ferramentas MCP, por isso um cliente só de leitura não consegue sequer ver uma ferramenta de envio. Um alfabeto, três superfícies.

Uma chave pode ser emitida contra uma FUNÇÃO, e uma função é um tecto e não uma segunda concessão. O que a chave pode realmente fazer são os seus próprios âmbitos INTERSETADOS com as permissões dessa função (key.scopes ∩ role.permissions), calculado uma vez na fronteira, em todos os pedidos, antes de se chegar a qualquer endpoint. Nada a jusante sabe que as funções existem: um âmbito que a função não tem simplesmente não está na lista que as verificações de âmbito leem.

Por isso as duas listas leem-se em conjunto e nenhuma ganha sozinha. Uma chave com emails:send sob uma função que não o tem não pode enviar; uma função com emails:send não dá nada a uma chave que nunca o pediu. Marcar um âmbito é pedir autoridade, e a função decide quanto do que pediu recebe.

A interseção é resolvida por pedido em vez de ficar carimbada na chave no momento da emissão. Isso torna estreitar uma função uma revogação imediata, em vigor na chamada seguinte de quem a usa sem que a chave tenha de ser rodada, e alargar uma é imediato exatamente da mesma maneira, que é a metade que vale a pena recordar.

GET /ping e GET /keys/self comunicam scopes ao lado de grantedScopes e roleId por causa de uma falha em particular. scopes é a lista efetiva e a única que autoriza o que quer que seja; grantedScopes é aquilo com que a chave foi emitida. Tudo o que esteja na segunda e falte na primeira foi retirado pela função, e essa diferença é toda a resposta a "a minha chave tem emails:send e estou a receber insufficient_scope". A correção é uma alteração de função e não mais uma chave.

curl "$OE/ping" -H "$AUTH" {  "ok": true,  "keyId": "4c1b257a66287fd113bd89d0",  "mode": "live",  "scopes": ["emails:read", "threads:read"],  "roleId": "role_c40a95f21cc65d31c2a89e07",  "grantedScopes": ["emails:send", "emails:read", "threads:read"],  "workspaceId": "10417196-e324-4283-af98-66ec62167c47"}

Independentemente dos âmbitos, uma chave pode ser restringida quanto aos remetentes que pode usar. Traz duas listas. domainAllowlist contém domínios inteiros, e uma chave que tenha um domínio pode enviar como qualquer endereço nele, incluindo endereços criados depois da chave. addressAllowlist contém endereços individuais. Deixe ambas vazias e a chave é tão ampla como o espaço de trabalho, nunca mais. GET /keys/self mostra as duas listas e GET /addresses comunica o que uma dada chave pode efetivamente usar, que é a resposta a um from_address_forbidden inexplicado.

O mesmo conjunto restringe o que a chave lê. O correio enviado, o tracking e o calendário só respondem para endereços que a chave pode usar como remetente, por isso uma chave limitada a um domínio não envia nem lê em nome de outro. Um domínio inteiro permite também à chave definir o host de tracking desse domínio, o que uma chave limitada a endereços individuais não pode fazer.

Três restrições, portanto, e compõem-se em vez de se sobreporem: os âmbitos da chave, as permissões da função acima dela, e os domínios e endereços que pode pôr num cabeçalho From. Um envio precisa das três, e uma recusa nomeia apenas a primeira com que se cruzou.