Gram Rbac

Gram's RBAC is a scope-and-selector model. The server ships with a fixed set of scopes grouped into system roles (admin, member). A grant binds a scope to a selector (a Kubernetes-style map[string]string of resource_kind, resource_id, plus optional narrowing dimensions like tool or disposition) for a given principal (user or custom role). Handlers enforce scopes by calling authz.Engine.Require(ctx, authz.Check{...}); the dashboard renders the same scope vocabulary through a matching TypeScript union that is hand-maintained in lockstep with the server.

Concepts and terminology

Scope. A named permission that authorizes an operation on a particular kind of resource.

Resource type. The kind of resource a scope protects — for example org, project, assistant, or mcp. Every scope has exactly one resource type.

Scope expansion. Higher-privilege scopes satisfy lower-privilege ones. In the read/write/connect family the privilege order is write > read > connect: mcp:write satisfies a mcp:read check, and either mcp:read or mcp:write satisfies a mcp:connect check (connect is the broadest, easiest-to-satisfy gate). The mapping lives in scopeExpansions in authz/scopes.go — key = required scope, value = higher-privilege scopes that also satisfy it.

Selector. A map[string]string of constraints attached to a grant or check. Always carries resource_kind and resource_id (both required); MCP scopes additionally allow tool and disposition. Wildcards are explicit values — {"resource_kind":"*","resource_id":"*"}, never empty {}. Defined in server/internal/authz/selector.go.

Selector matching. A grant selector satisfies a check selector when, for every key the grant constrains, either the values are equal or the grant value is "*". Keys present on the grant but absent from the check are skipped — this is what lets a disposition-scoped grant ({"disposition":"read_only"}) still satisfy a connection-level check that doesn't constrain disposition.

Grant. A tuple of {Scope, Selector} held by a principal. The API-visible forms are RoleGrant (carrying Selectors []Selector) and ListRoleGrant (which also carries the transitively-implied sub_scopes). Use authz.NewGrant(scope, resourceID) to construct one — it derives the selector's resource_kind from the scope family.

Principal. Who holds a grant — a urn.Principal with a type (user, role, service account) and an id.

Principal precedence. Blocklist exclusions (*:blocked_*) normally subtract from allows regardless of which principal holds either. One exception: a grant made directly to the user (user:<id>) that names a concrete resource (resource_id not *) outranks a block the user inherits from a role or user:all. Agent grants never outrank, because agent owners can write them without being administrators. The user's own blocks always apply, wildcard direct grants never outrank, roles and user:all share one level, a narrowed direct grant outranks only as far as it reaches, and risk_policy:bypass is never outranked. The rule lives in server/internal/authz/precedence.go (IsDirectGrant, DirectOverrideGrants, ExclusionYieldsToDirectGrants) and is mirrored in ListAccessibleMCPServersForUser / ListAccessibleSkillsForUser, runtimepolicy.DelegationContained, access.listGrants (direct_selectors), and the dashboard's useRBAC and per-server access list. Any new code that evaluates exclusions outside authz.Engine must apply it too.

Dimensions. Optional narrowing keys on a Check beyond resource_id. Today: tool and disposition for MCP scopes (see server/internal/authz/checks.go and MCPToolCallCheck), and project_id for MCP, environment, and assistant scopes. A project_id dimension is how a per-resource check inherits project-wide grants: the check names the resource and its project, so {"resource_id":"*","project_id":P} covers every resource in P while {"resource_id":R} covers only R (MCPCheck, AssistantCheck). Allowed keys per scope family are enforced by ValidateSelector; new dimensions must be added to allowedSelectorKeys in selector.go.

Disposition. A snake_case bucket derived from MCP tool annotation hints — read_only, destructive, idempotent, open_world. Constants live in authz/selector.go; conv.DispositionFromAnnotations(annotations) is the canonical conversion from *types.ToolAnnotations.

System role. A built-in role shipped with the server. Gram defines two: admin (every scope) and member (the read-and-connect subset). Constants authz.SystemRoleAdmin and authz.SystemRoleMember.

Enforcement. Inside a handler, authorization is an explicit one-line check: the handler names the scope (and resource, if project-scoped) it needs, and the RBAC engine either allows the call or returns a forbidden error.

Auth context invariant. Organization-scoped handlers can assume ActiveOrganizationID is populated. During login, session authentication can briefly produce an org-less context; Engine.PrepareContext handles that middleware boundary by installing zero grants instead of trying organization-scoped principal resolution. Endpoints already exposed during login keep their explicit org-less behavior: for example, access.ListGrants returns no grants, productfeatures.GetProductFeatures returns unauthorized, and auth.Info continues the login flow. Do not spread defensive empty-org checks into other handlers.

Server

RBAC is split across two Go packages: server/internal/authz/ holds the enforcement primitives, and server/internal/access/ implements the Goa management service that exposes them over HTTP. When adding new authorization primitives (scopes, checks, enforcement logic) edit authz; when adding or changing the management API (role/member endpoints) edit access.

authz package — the enforcer

Scope vocabulary, grant types, and enforcement logic are defined here. authz's imports are deliberately minimal (DB, logger, cache, WorkOS, urn) so any package that gates on RBAC can depend on it without import cycles — never add an import to authz from a package that transitively depends on authz, since the split exists specifically to prevent the cycles that motivated it.

Scope declarations. Scope type and every Scope* constant live in server/internal/authz/scopes.go. Constants follow the Scope<Name> pattern; string values follow <resource>:<verb> (e.g. mcp:read, org:admin). ScopeRoot is reserved for service-internal superadmin overrides. The file also holds the scopeExpansions map and computes the inverse scopeSubScopes in init(). CalculateSubScopes(scope) exposes the inverse to callers.

System role grants. SystemRoleGrants in server/internal/authz/grants.go — admin and member defaults. Adding a scope usually means adding it to admin, and optionally to member if end users should get it by default. SeedSystemRoleGrants upserts the full set; SyncGrants upserts grants for a single role slug.

authz.Engine. The central enforcer. Methods: PrepareContext, Require(ctx, checks...), RequireAny(ctx, checks...), Filter(ctx, scope, ids), ShouldEnforce, InvalidateRoleCache, InvalidateAllRoleCaches, GetScopeOverrides. Constructed in server/cmd/gram/start.go via authz.NewEngine(logger, db, chDB, challengeLogging, membership, opts...) and injected into every service that gates on RBAC. RBAC is always enforced for eligible authenticated requests; the MembershipFetcher is the WorkOS client used for role-slug lookups.

Organization provisioning. authz.Provisioner seeds both built-in roles and their grants for every organization created through Gram. ProvisionOrganizationAdmin performs that seed and assigns the first user to SystemRoleAdmin in one transaction. The identity leaf package never imports authz. WorkOS organization event reconciliation calls SeedSystemRoleGrantsTx for organizations discovered through WorkOS.

authz.Check. {Scope, ResourceKind, ResourceID, Dimensions} — the thing a handler asks Require to enforce. For the common single-resource case, leave ResourceKind: "" (auto-derived from the scope family) and Dimensions: nil; exhaustruct requires every field at every call site. ResourceID is typically authCtx.ProjectID.String() for project-scoped scopes. Defined in server/internal/authz/access.go.

authz.Filter for list endpoints. When a handler lists resources the caller might only partially own, s.authz.Filter(ctx, scope, candidateIDs) ([]string, error) returns the subset of IDs the caller holds the scope for. The standard pattern is: gather candidate IDs from the repo, call Filter, then rebuild the response from the allowed IDs. Prefer this over a post-hoc per-item Require loop. Canonical call sites: server/internal/projects/impl.go (projects list) and server/internal/toolsets/impl.go (toolsets list).

Auth context accessor. contextvalues.GetAuthContext(ctx) returns the current *AuthContext. RBAC-relevant fields: ActiveOrganizationID, ProjectID, UserID, Email, IsAdmin, APIKeyID, SessionID. AccountType is billing metadata and does not control RBAC enforcement.

Scope overrides. A local-dev/superadmin header can inject a restricted grant set for the request, parsed in override.go and surfaced via Engine.GetScopeOverrides. access.ListGrants returns the override set verbatim when active so the dashboard reflects what the engine will enforce.

Error model. errors.go defines sentinel errors (ErrDenied, ErrMissingGrants, ErrNoChecks, ErrInvalidCheck) and typed errors (DeniedError, InvalidCheckError). The engine maps these to oops codes — ErrDenied → oops.CodeForbidden, everything else → oops.CodeUnexpected with a logged message.

Grant loading. LoadGrants(ctx, db, orgID, principals) reads the principal URN set and returns the flattened []Grant. Called by both Engine.PrepareContext (middleware path) and access.ListGrants (user-facing). Each row's selectors JSONB is parsed via SelectorFromRow. It also supplies unrestricted assistant:read/assistant:write defaults for the built-in Admin and Member role principals (role:global:<id>), because organizations seeded before the assistant scopes have no stored rows for them and system-role grants are immutable.

Sync semantics. SyncGrants distinguishes nil from empty: RoleGrant{Selectors: nil} writes a single wildcard row; RoleGrant{Selectors: []Selector{}} writes nothing (no access). Each non-nil selector is validated by ValidateSelector before insert.

access package — the management API

server/internal/access/ implements the Goa access service on top of authz. Every handler calls s.authz.Require(...) with the appropriate scope before doing work. The package also owns queries.sql and the generated server/internal/access/repo/ SQLc package that both access and authz use to read and write grant rows.

Scope metadata. ListScopes in server/internal/access/impl.go returns one {Slug, Description, ResourceType} entry per scope; this is what the dashboard consumes to render the scope picker.

Full-access grant list. ListGrants returns a hard-coded full-access scope list when enforcement is intentionally skipped, such as sessionless or API-key requests. That inline list in server/internal/access/impl.go must grow whenever a new scope is added. The parallel test expectation is expectedFullAccessScopes in server/internal/access/listusergrants_test.go.

System role gating. isSystemRole(slug) in impl.go checks against authz.SystemRoleAdmin and authz.SystemRoleMember. System roles cannot be renamed, deleted, or have their grant set edited; only member assignment is allowed.

Non-generated files

Generated files

Server-client contract

Scope and resource-type changes on the server ripple into the generated SDK types (via gen:sdk) and a few hand-maintained docs and tests — adding a scope is not purely a server-package change.

HTTP routes (design: server/design/access/design.go):

• /rpc/access.listScopes — every scope the server knows about, with resource_type and description.
• /rpc/access.listRoles, getRole, createRole, updateRole, deleteRole — custom role CRUD.
• /rpc/access.listMembers, updateMemberRole — org membership and role assignment.
• /rpc/access.listUserGrants — the caller's effective grants.

Three-place enum lockstep. server/design/access/design.go repeats the scope slug enum in three places — RoleGrantModel.scope, ListRoleGrantModel.scope, and its sub_scopes element — plus ScopeModel.slug for the listing endpoint. All three must stay synchronized with authz/scopes.go, and ScopeModel.resource_type must contain every resource type in use. Adding a new resource type also means adding it to SelectorModel.resource_kind's enum (project, mcp, org, *) — the model that backs RoleGrant.selectors and ListRoleGrant.selectors.

Generated SDK types. client/dashboard/src/sdk/src/models/components/scopedefinition.ts, rolegrant.ts, listrolegrant.ts, selector.ts, etc. Regenerated by mise run gen:sdk after every design change.

UI-owned access-page types. client/dashboard/src/pages/access/types.ts owns the dashboard-only abstractions layered over the generated SDK: the ResourceType string-literal union, AnnotationHint, CustomTab, ActivePanel, PolicyEffect, ScopeRule, a UI RoleGrant interface (selectors: Selector[] | null, distinct from the SDK's RoleGrant), and toRoleSlug. It also owns the ANNOTATION_TO_DISPOSITION / DISPOSITION_TO_ANNOTATION maps that mirror the disposition vocabulary in authz/selector.go — keep these in lockstep when adding or renaming dispositions. It imports Scope / Selector / SelectorDisposition from the SDK for local use in those definitions.

Client

The dashboard pages under client/dashboard/src/pages/access/ render membership and role management on top of the generated SDK and the listScopes response. RBAC-aware UI across the rest of the dashboard gates itself through a shared hook and component.

Conventions

useRBAC hook. client/dashboard/src/hooks/useRBAC.ts wraps the generated useGrants React Query hook and exposes hasScope(scope, resourceId?, projectId?), hasAllScopes(scopes, resourceId?, projectId?), hasAnyScope(scopes, resourceId?, projectId?), plus isLoading, grants, and error. Returns false from the has* checks while grants are loading. The module also exports selectorMatches(grant, check) and resourceKindForScope(scope) — direct mirrors of the server-side helpers in authz/selector.go — for code that needs parity with backend matching outside the standard hasScope flow.

RequireScope component. client/dashboard/src/components/require-scope.tsx is the primary rendering gate. Props: scope: Scope | Scope[], all?: boolean (AND vs OR when multiple scopes), resourceId?: string, projectId?: string (the project the resource belongs to, for scope families with a project_id dimension), level: "page" | "section" | "component", children, and level-specific extras (fallback for page/section, reason/className for component).

• level="page" — renders a full Unauthorized fallback page when the scope is missing.
• level="section" — hides the children entirely.
• level="component" — renders disabled with a tooltip explaining why (good for buttons and inputs).

Scope vocabulary import. useRBAC, RequireScope, and the access pages import the Scope union directly from the generated SDK (@gram/client/models/components/rolegrant.js). That union is regenerated from the server scope enum by gen:sdk, so keeping server/design/access/design.go in lockstep with authz/scopes.go is what makes the client gates type-check.

Dashboard grant reference. docs/rbac.md contains the "Dashboard Grant Reference" table that maps dashboard pages and actions to the grants required to use them. Whenever adding a new scope, changing a system-role grant default, adding a new dashboard RBAC gate, or changing the grant required by a dashboard feature, update that table in the same change. The table is the first place to answer questions like "what grant is required to create a project?"

Non-generated files

Jobs to be done

How to gate a handler with an existing scope

1. Inject *authz.Engine into the service struct (if it isn't already) and keep it on s.authz.
2. At the top of the handler — before any database work — call s.authz.Require(ctx, authz.Check{Scope: authz.Scope<Name>, ResourceKind: "", ResourceID: authCtx.ProjectID.String(), Dimensions: nil}) and return the error as-is. The exhaustruct linter requires every Check field — leave ResourceKind empty to auto-derive from the scope family and Dimensions nil unless you're narrowing by tool/disposition.
3. Choose the narrowest scope for the operation: *:read for GET/list, *:write for mutations, *:connect for runtime usage. Scope expansions mean write callers are still permitted to read.
4. Use RequireAny instead of Require when a single handler legitimately satisfies multiple equivalent scopes.
5. In the handler's test, add one case that builds the context without the scope and asserts an oops.CodeForbidden response, and one case that builds the context with the scope via authztest.WithExactGrants(t, ctx, authz.NewGrant(authz.Scope<Name>, resourceID)). Construct grants with authz.NewGrant (or authz.NewGrantWithSelector for non-trivial selectors) — never set Grant.Selector by hand.