Ámbitos

Un conjunto cerrado, resource:action. Lo bastante pequeño como para mostrárselo a una persona en una lista de casillas, y lo bastante estable como para que una concesión guardada siga significando lo mismo un año después. Ese mismo vocabulario es con el que se escribe un ROL de espacio de trabajo y el que controla el acceso a las herramientas MCP, de modo que un cliente de solo lectura ni siquiera puede ver una herramienta de envío. Un alfabeto, tres superficies.

Una clave puede emitirse contra un ROL, y un rol es un techo, no una segunda concesión. Lo que la clave puede hacer realmente son sus propios ámbitos INTERSECADOS con los permisos de ese rol (key.scopes ∩ role.permissions), calculado una vez en el límite, en cada petición, antes de llegar a ningún endpoint. Nada de lo que hay más abajo sabe que existen los roles: un ámbito que el rol no tiene simplemente no está en la lista que leen las comprobaciones de ámbito.

Así que las dos listas se leen juntas y ninguna gana por sí sola. Una clave que lleva emails:send bajo un rol que no lo tiene no puede enviar; un rol que tiene emails:send no le da nada a una clave que nunca lo pidió. Marcar un ámbito es pedir autoridad, y el rol decide cuánto de lo que pediste recibes.

La intersección se resuelve en cada petición en lugar de grabarse en la clave en el momento de emitirla. Eso convierte restringir un rol en una revocación en vivo, en vigor en la siguiente llamada del cliente sin necesidad de rotar la clave, y ampliarlo actúa en vivo exactamente igual, que es la mitad que conviene recordar.

GET /ping y GET /keys/self informan de scopes junto a grantedScopes y roleId por un fallo en particular. scopes es la lista efectiva y la única que autoriza algo; grantedScopes es aquello con lo que se emitió la clave. Todo lo que esté en la segunda y falte en la primera se lo quitó el rol, y esa diferencia es la respuesta completa a «mi clave tiene emails:send y estoy recibiendo insufficient_scope». La solución es un cambio de rol, no otra clave.

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

Al margen de los ámbitos, una clave puede restringirse en cuanto a la identidad con la que puede enviar. Lleva dos listas. domainAllowlist contiene dominios enteros, y una clave que tiene un dominio puede enviar como cualquier dirección de ese dominio, incluidas las creadas después que la clave. addressAllowlist contiene direcciones sueltas. Deja las dos vacías y la clave es tan amplia como el espacio de trabajo, nunca más. GET /keys/self muestra ambas listas y GET /addresses informa de lo que una clave dada puede usar realmente, que es la respuesta a un from_address_forbidden inexplicable.

El mismo conjunto restringe lo que la clave lee. El correo enviado, el seguimiento y el calendario solo responden para las direcciones con las que la clave puede enviar, así que una clave acotada a un dominio ni envía ni lee en nombre de otro. Un dominio entero permite además que la clave configure el host de seguimiento de ese dominio, algo que una clave limitada a direcciones sueltas no puede hacer.

Tres restricciones, entonces, y se componen en lugar de anularse: los ámbitos de la clave, los permisos del rol que tiene por encima, y los dominios y direcciones que puede poner en una cabecera From. Un envío necesita las tres, y un rechazo nombra solo la primera con la que se topó.