Surface role operation-level grants (permission.operations) in the roles/users UI

[heskew]

Harper's roles support operation-level RBAC that Studio's role/user editor doesn't surface yet. Requested by @dawsontoth so the UI can expose it. This outlines the full capability surface and which Harper versions support each piece, verified against the Harper source and release tags.

The capability

A role's permission object accepts an optional operations array — an allowlist of Operations API operation names (snake_case) and/or predefined group names:

{
  "operation": "add_role",
  "role": "ci_deploy",
  "permission": {
    "operations": ["deploy_component", "get_status"]
    // table CRUD permissions may appear alongside as usual
  }
}

Semantics (two-gate check, first thing in authorization):

1. Gate 1 — hard allowlist. When operations is present, any operation not listed is denied, before table CRUD permissions are even considered. Omitting operations entirely = current behavior (no allowlist).
2. Gate 2 — scoped super_user delegation. An operation that normally requires super_user, when explicitly listed, is treated as a deliberate admin grant and allowed without super_user. This is what makes e.g. a deploy-only CI user possible: operations: ["deploy_component", "get_status"] on a non-SU role yields a user that can run exactly those two operations and nothing else.
3. Non-SU operations that pass gate 1 still go through normal table CRUD permission checks.

Predefined groups (usable in the array alongside individual names, expanded server-side):

Group	Contents (summary)
read_only	searches, SQL, describes, user/analytics reads
admin_read	SU-only reads: get_configuration, logs, component views
standard_user	read_only + full DML + bulk load (no DDL, no user/role mgmt)
agent	agent session operations (agent_prompt, get_agent_session, …)

Write-time validation. add_role / alter_role reject an operations array containing an unknown name — the server validates, but a UI picker still needs the list of valid names (see open question below).

Not delegable by design. A small set of SU-only operations self-enforce super_user in their handlers and cannot be granted through the allowlist: the secrets-store operations, managed-backup operations, and get_deployment_payload. A UI should not offer these as grantable.

Impersonation. Inline role assertions (impersonation with a role in the request body) accept and validate the same operations field.

Version support

Harper version	What's available
5.0.0+	permission.operations allowlist, both gates, groups read_only / admin_read / standard_user, write-time validation, impersonation support
5.2.0+	agent group; component-registered operations (server.registerOperation with a declared permission) become grantable custom names (HarperFast/harper#1599)
In flight	HarperFast/harper#2173 (OIDC trusted publishing, draft) adds add/list/drop_oidc_trust + trust policies that name a Harper user — a Studio trust-policy UI would pair naturally with a "scoped CI user" flow. HarperFast/harper#2174 (draft, direction undecided) would add per-token operation narrowing. Neither is merged; don't build against them yet.

Suggested UI surface (yours to design, obviously)

• Role editor: an "Operations" section — group toggles plus an operation picker, with a badge on operations that are normally super_user-only (so granting them reads as the deliberate act it is).
• Role/user view: effective operations summary (groups expanded).
• A "scoped service user" flow (create role + user in one pass) would line up well with the CI trusted-publishing work when it lands.

Open question

There is no discovery operation that returns valid operation/group names for a picker (describe_all doesn't cover it, and 5.2's component-registered names are dynamic per instance). Options: ship a static list per supported Harper version, or ask for a small list_grantable_operations operation in Harper core — happy to file that issue if useful.

Source references (Harper repo)

• Gate logic: utility/operation_authorization.ts (search "operations is an optional allowlist")
• Groups + validation: utility/operationPermissions.ts
• Role write-time validation: validation/role_validation.ts
• Integration tests showing exact request shapes: integrationTests/server/operation-user-rbac.test.ts

---

🤖 Filed by Claude on behalf of @heskew