Скоупы

Закрытый набор вида resource:action. Достаточно маленький, чтобы показать человеку списком галочек, и достаточно стабильный, чтобы сохранённая выдача означала то же самое и год спустя. На том же словаре написана РОЛЬ рабочего пространства, и он же ограничивает инструменты MCP, поэтому клиент «только на чтение» даже не увидит инструмент отправки. Один алфавит, три поверхности.

Ключ может быть выпущен под РОЛЬЮ, и роль — это потолок, а не вторая выдача прав. То, что ключ на самом деле может делать, — это его собственные скоупы, ПЕРЕСЕЧЁННЫЕ с разрешениями этой роли (key.scopes ∩ role.permissions), вычисленные один раз на границе, на каждом запросе, до того как дело дойдёт до любого эндпоинта. Ниже по стеку никто не знает, что роли существуют: скоупа, которого нет у роли, просто нет в списке, который читают проверки скоупов.

Поэтому оба списка читаются вместе и ни один сам по себе не побеждает. Ключ с emails:send под ролью, у которой этого разрешения нет, отправлять не может; роль с emails:send ничего не даёт ключу, который никогда его не просил. Отметить скоуп — значит запросить полномочие, а роль решает, сколько из запрошенного вы получите.

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

GET /ping и GET /keys/self сообщают scopes рядом с grantedScopes и roleId ради одного конкретного сбоя. scopes — это действующий список и единственный, который что-либо разрешает; grantedScopes — это то, с чем ключ был выпущен. Всё, что есть во втором и отсутствует в первом, забрала роль, и эта разница — исчерпывающий ответ на «у моего ключа есть emails:send, а я получаю insufficient_scope». Исправляется это изменением роли, а не ещё одним ключом.

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"}

Отдельно от скоупов ключ можно сузить в том, от чьего имени он может отправлять. Он несёт два списка. domainAllowlist содержит целые домены, и ключ с доменом может отправлять от любого адреса на нём, включая адреса, созданные после самого ключа. addressAllowlist содержит отдельные адреса. Оставьте оба пустыми — и ключ будет так же широк, как рабочее пространство, но никогда шире. GET /keys/self показывает оба списка, а GET /addresses сообщает, чем данный ключ действительно может пользоваться, и это ответ на необъяснимый from_address_forbidden.

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

Итого три сужения, и они складываются, а не перекрывают друг друга: скоупы на ключе, разрешения роли над ним и домены с адресами, которые он может поставить в заголовок From. Отправке нужны все три, а отказ называет только первое, на которое она наткнулась.