Scopes

Eine geschlossene Menge, resource:action. Klein genug, um sie einem Menschen als Checkbox-Liste zu zeigen, und stabil genug, dass eine gespeicherte Berechtigung ein Jahr später noch dasselbe bedeutet. In demselben Vokabular ist eine Workspace-ROLLE geschrieben, und es steuert den Zugang zu MCP-Tools, sodass ein Client mit Lesezugriff ein Sende-Tool nicht einmal sieht. Ein Alphabet, drei Oberflächen.

Ein Key kann gegen eine ROLLE ausgestellt werden, und eine Rolle ist eine Obergrenze und keine zweite Berechtigung. Was der Key tatsächlich darf, sind seine eigenen Scopes GESCHNITTEN mit den Berechtigungen dieser Rolle (key.scopes ∩ role.permissions), einmal an der Grenze berechnet, bei jeder Anfrage, bevor irgendein Endpunkt erreicht wird. Nichts dahinter weiß, dass es Rollen gibt: Ein Scope, den die Rolle nicht hält, steht schlicht nicht in der Liste, die die Scope-Prüfungen lesen.

Die beiden Listen werden also zusammen gelesen, und keine gewinnt für sich allein. Ein Key mit emails:send unter einer Rolle, die diesen Scope nicht hält, darf nicht senden; eine Rolle mit emails:send gibt einem Key, der ihn nie angefragt hat, gar nichts. Einen Scope anzuhaken heißt, Befugnis zu verlangen, und die Rolle entscheidet, wie viel vom Verlangten Sie bekommen.

Die Schnittmenge wird pro Anfrage aufgelöst und nicht bei der Ausstellung auf den Key gestempelt. Das macht das Verengen einer Rolle zu einem sofortigen Entzug, wirksam beim nächsten Aufruf des Clients und ohne dass der Key rotiert werden muss, und das Erweitern wirkt auf genau dieselbe Weise sofort; das ist die Hälfte, die man sich merken sollte.

GET /ping und GET /keys/self melden scopes neben grantedScopes und roleId, und zwar wegen eines ganz bestimmten Fehlerfalls. scopes ist die effektive Liste und die einzige, die überhaupt etwas autorisiert; grantedScopes ist das, womit der Key ausgestellt wurde. Alles, was in der zweiten steht und in der ersten fehlt, hat die Rolle weggenommen, und dieser Unterschied ist die vollständige Antwort auf „mein Key hat emails:send und ich bekomme insufficient_scope“. Die Lösung ist eine Änderung der Rolle und kein weiterer Key.

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

Unabhängig von den Scopes kann ein Key darin verengt werden, als was er senden darf. Er trägt zwei Listen. domainAllowlist enthält ganze Domains, und ein Key, der eine Domain hält, darf als jede Adresse darauf senden, auch als Adressen, die nach dem Key angelegt wurden. addressAllowlist enthält einzelne Adressen. Lassen Sie beide leer, ist der Key so weit wie der Workspace, nie weiter. GET /keys/self zeigt beide Listen, und GET /addresses meldet, was ein bestimmter Key tatsächlich verwenden darf; das ist die Antwort auf ein unerklärliches from_address_forbidden.

Dieselbe Menge verengt, was der Key liest. Gesendete Mail, Tracking und Kalender antworten nur für Adressen, als die der Key senden darf; ein Key, der auf eine Domain eingeschränkt ist, sendet und liest also nicht im Namen einer anderen. Eine ganze Domain erlaubt dem Key außerdem, den Tracking-Host dieser Domain zu setzen, was ein auf einzelne Adressen beschränkter Key nicht kann.

Also drei Verengungen, und sie wirken zusammen, statt einander zu überschreiben: die Scopes auf dem Key, die Berechtigungen der Rolle darüber und die Domains und Adressen, die er in einen From-Header setzen darf. Ein Versand braucht alle drei, und eine Ablehnung nennt nur die erste, auf die sie gestoßen ist.