On a pod, a role the plane narrows holds at the caller's next command: the guard answers the scopes that command runs with, the mirror's role intersected with the token's; it narrows and never widens¶
Decision 859 · accepted · 2026-10-11 · issue #494
Issue #494. A pod's ACL mirror only revoked: when the plane changed a person's role on a
session with session.grant, the pod recorded the new role and then ignored it, because
the connection's scopes were fixed from the token at initialize. Somebody granted owner
and then made a collaborator kept admin on the pod, and with it shell.run (Decision
813), until the token expired, at most fifteen minutes later.
The issue allowed either making the narrowing reach the running pod or stating the bound.
Making it reach the pod needed no new mechanism: the plane already pushes the new role as
acl.changed (Troupe.Plane.Harness.push_acl/2), the worker already mirrors it
(Troupe.Worker.Auth.put_acl/4), and the guard is already asked before every command.
What was missing was a way for the guard's answer to reach the dispatcher's scope checks,
so stating the bound would have documented a gap that was a few lines wide.
- The guard says how many scopes the command gets. A remote endpoint's guard may answer
{:ok, scopes}as well as:okand{:error, _}.Troupe.Gateway.Connectiondispatches that one command with the connection's scopes filtered to those, and keeps its own scopes as they were, so a later push that restores the role restores the scopes with it. Every check downstream sees the narrowed set: the method table's required scope and the handlers' own (session_owner/1, which is what refusesshell.runto a collaborator). Rejected: a list in the worker of the methods each role may call, which would repeat the dispatcher's table and miss every in-handler check,shell.run's among them. - It narrows and never widens. The connection intersects, so no guard can grant a
scope the token did not carry. A collaborator the plane makes an owner keeps
controluntil their next token, whichauth.refreshbrings within the token's lifetime: a wider role is something a signature should vouch for, a narrower one is not. - The mirror's role is the role. No mirrored entry leaves the token as the only word,
as before; a revocation still refuses with
access revoked; a role gives its scopes fromTroupe.Protocol.Token.scopes_for/1. A token with no session in it that names several sessions gets the fewest scopes of the roles mirrored for them. - What a narrowed caller sees is the refusal a token of the narrower role gets:
forbiddenwithdata.required_scope, andshell.run's sentence for the owner's check. The connection'sinitializeanswer still shows the token's scopes and role; it is a description of the token, and the next one will say the new role.
Proof: Troupe.Worker.HarnessAuthTest ("an owner the plane narrows to a collaborator is
refused a command at once, and a viewer steering", which on the chunk's tip ran the
command; and "a collaborator the plane makes an owner keeps their token's scopes until the
next one"), over a real pod connection with a plane-minted token, and
Troupe.Worker.AuthTest ("a role the plane narrows": the guard's answer, and the fewest
scopes across sessions). The bound for widening is in
roles-and-permissions.md section 5 and PROTOCOL.md.
Governs: apps/troupe_worker/lib/troupe/worker/auth.ex, apps/troupe_gateway/lib/troupe/gateway/connection.ex, apps/troupe_protocol/lib/troupe/protocol/endpoint.ex