role operations allowlist: grants are gate-inert for ops registered without api_name (deploy_component, get_status, …); sql bypasses the allowlist

[dawsontoth]

While building the Studio UI for permission.operations (HarperFast/studio#1627, shipped in HarperFast/studio#1628), I traced the allowlist gate through the source and believe a set of grants that add_role/alter_role accept can never match at authorization time. Static reading of main @ 21043f9 and v5.2.2 — not yet reproduced against a live instance, so please correct me if I've misread the dispatch.

The mechanism

The allowlist gate resolves the operation's name like this (utility/operation_authorization.ts:635):

const opApiName = requiredPermissions.get(op)?.api_name ?? op;
if (!allowedOps.has(opApiName)) { /* deny */ }

op is the handler function's camelCase name: serverUtilities.ts passes the handler function itself to verifyPerms (const verifyPermsResult = opAuth.verifyPerms(operation_json, functionToCheck)), and verifyPerms does op = operation.name for functions. allowedOps holds the snake_case names that validateOperations accepted at role-write time.

So for any requiredPermissions entry registered without the api_name third argument, opApiName falls back to the camelCase handler name — which can never equal a granted snake_case name. The grant validates, saves, and is silently gate-inert: gate 1 denies the operation even though it is explicitly listed, and the gate-2 SU delegation never fires.

Affected registrations (no api_name, SU-only, wire name ≠ handler name)

From utility/operation_authorization.ts on main:

• Components: deployComponent (deploy_component — the headline example in studio#1627), addComponent, dropComponent, packageComponent, setComponentFile, setCustomFunction, dropCustomFunction, dropCustomFunctionProject
• Status: status.get/set/clear (get_status, set_status, clear_status)
• System: configUtils.setConfiguration (set_configuration), restart.restartService (restart_service), npmUtilities.installModules (install_node_modules)
• Data/logs: getBackup (get_backup), schema.cleanupOrphanBlobs (cleanup_orphan_blobs), transactionLog.readTransactionLog (read_transaction_log), deleteTransactionLogsBefore, delete_.deleteFilesBefore, delete_.deleteAuditLogsBefore
• Jobs: handleGetJobsByStartDate (search_jobs_by_start_date)

(catchup also lacks api_name but its handler name equals the wire name, so the fallback happens to work. login/logout bypass verifyPerms entirely and are unaffected.)

Notably, the gate's own TODO comment says "get_backup remains the one that relies solely on this gate" — i.e. the intent is that these are delegable; the registration just never wired the name.

Ops with no requiredPermissions entry at all (e.g. audit_node_modules, add_node, update_node, set_node_replication, purge_stream, delete_job, update_job, delete_records_before) hit the same ?? op fallback and are equally ungrantable — worth sweeping in the same pass if any are meant to be user-addressable.

Related gap: sql bypasses the allowlist entirely

serverUtilities.ts routes operation === 'sql' to checkASTPermissions/verifyPermsAST instead of verifyPerms, and verifyPermsAST has no allowlist check at all. Two consequences:

1. A role restricted to e.g. operations: ["insert"] can still run arbitrary sql (subject to table CRUD perms) — the "deny anything unlisted" contract doesn't hold for sql.
2. Granting sql (or read_only, which includes it) "works" only because sql is never gate-checked in the first place.

Related nit: legacy alias spellings

validateOperations accepts both spellings of aliased ops (describe_database/describe_schema, create_schema/create_database, search_by_id/search_by_hash, *_custom_function_project/*_component), but the gate resolves to the single api_name on the registration — so granting the other spelling is gate-inert too. The predefined groups defensively include both spellings, which papers over this for group users but not for individual grants.

Suggested fix

• Pass terms.OPERATIONS_ENUM.* as api_name on every user-addressable registration (mechanical), or normalize camelCase→snake_case in the gate fallback.
• Decide whether sql should flow through gate 1 (I'd argue yes — the allowlist reads as a hard contract) and add it to the AST path if so.
• An integration test in operation-user-rbac.test.ts that grants one of the previously-unwired names (e.g. operations: ["deploy_component"]) and asserts the op passes gate 1 — today's tests only exercise ops that happen to have api_name set.
• For aliases: either expand alias pairs in expandOperationsPerms or document that grants must use the canonical spelling.

Why it matters downstream

Studio's role editor (HarperFast/studio#1628) offers every name validateOperations accepts, so today it can produce roles whose grants look right, save cleanly, and silently don't work — including the deploy-only CI role that motivated studio#1627.

---

🤖 Filed by Claude on behalf of @dawsontoth

[dawsontoth]

Follow-up from the same file, found while deep-reviewing the Studio UI (HarperFast/studio#1628): the allowlist gate is unreachable for elevated roles, which I don't think is stated anywhere.

verifyPerms clears super users — and structure users on DDL — before it reaches the operations check (utility/operation_authorization.ts, v5.2.2):

if (isSuperUser && !isSuSystemOperation) {
	//admins can do (almost) anything
	return null;
}
// …structure-user early-allows for create/drop schema/table/attribute…

// operations is an optional allowlist on the role. …
const operations = permission?.operations;
if (operations !== undefined) { /* gate 1 / gate 2 */ }

So {"super_user": true, "operations": ["read_only"]} — or even operations: [] — validates, saves, and grants full admin. role_validation.ts raises nothing, and integrationTests/server/operation-user-rbac.test.ts only ever exercises super_user: false, so nothing catches it.

That may well be intended: the feature reads as a way to scope non-SU roles (and gate 2 exists precisely to delegate SU-only ops to them). If so, the only ask is that it be explicit, because the combination is currently silently accepted and is an easy thing for an operator — or a UI — to read as "restricted super user". Options, roughly in order of how much I'd expect you to want them:

1. Document it and leave enforcement as-is.
2. Reject it at write time — add_role/alter_role error when operations is combined with super_user: true (and arguably structure_user: true), so the inert combination can't be stored.
3. Move the gate above the early returns so an allowlist narrows an SU role too. Strictly more expressive, but a behavior change for anything already relying on the current ordering.

Studio now warns on any elevated role carrying an allowlist and refuses to report it as a restriction, so nothing is blocked on this — but whichever option you pick, I'd like to match it. Happy to send the PR for (2) if that's the direction.

---

🤖 Filed by Claude on behalf of @dawsontoth

[dawsontoth]

Correction to my earlier comment, from @cb1kenobi's review of the Studio side (HarperFast/studio#1628) — I overstated the scope of the bypass, and the accurate version is more interesting for option (2).

structure_user and cluster_user do not bypass the gate. Only super_user has the unconditional early return. structure_user returns early solely for create_schema/drop_schema (when === true) and for STRUCTURE_USER_OPS — create_table, create_attribute, drop_table, drop_attribute — and falls through to the allowlist for everything else. cluster_user never appears in operation_authorization.ts at all.

And super_user/cluster_user + operations can't be stored anyway. validateNoSUPerms (validation/role_validation.ts) errors with Roles with 'super_user' set to true cannot have other permissions set. on any permission with more than one key that sets super_user: true or cluster_user: true — so add_role/alter_role reject the combination outright. structure_user is deliberately not covered by that check.

So the state today is coherent, just undocumented:

role	allowlist storable?	enforced?
super_user: true	no — 400 from validateNoSUPerms	n/a
cluster_user: true	no — 400	n/a
structure_user (bool or array)	yes	yes, except the DDL ops above

That mostly answers my own option list: option (2) is already implemented for SU/CU, and option (3) would only be meaningful for the DDL carve-out on structure_user. What's left is narrower than I first suggested:

1. Is the structure_user DDL carve-out intended to sit outside the allowlist? A role with structure_user: true, operations: ['read_only'] can still drop tables, which reads as surprising even if it's deliberate.
2. Worth documenting the SU/CU exclusivity next to the operations docs, since "restricted super user" is the natural thing to reach for and the error message doesn't mention operations.

The api_name gaps in the original report stand unchanged. Studio now models the table above exactly, so nothing is blocked either way.

---

🤖 Filed by Claude on behalf of @dawsontoth

[dawsontoth]

One addition to the api_name list, found by @cb1kenobi reviewing the Studio side: registration_info is affected too, and it has a nastier consequence than the rest.

utility/operation_authorization.ts:363:

requiredPermissions.set(regDeprecated.getRegistrationInfo.name, new (permission as any)(false, []));

No api_name, so gate 1 resolves it to the camelCase handler name and it can never match a grant. Unlike the other 22 this one is requiresSu: false, which is why my original enumeration missed it — I had filtered to SU-only entries.

Why it matters more: gate 1 denies anything not in allowedOps, so any role carrying an allowlist is denied registration_info even when it explicitly lists it. There's no spelling that works. Studio itself calls registration_info for version detection, so a scoped role can't reliably drive the very UI that creates these allowlists — and the same applies to any client that probes the version before deciding what to send.

Full corrected list is the 22 from the first comment plus registration_info. Studio badges all 23 as "not yet enforced" rather than promising a delegation.

---

🤖 Filed by Claude on behalf of @dawsontoth

[kriszyp]

Status update from QA finding triage, verified against origin/main @ e16d961 (2026-08-29) — this issue is now half fixed:

• The sql bypass is closed on main. server/serverHelpers/serverUtilities.ts:272, inside chooseOperation's sql branch, now calls opAuth.verifyOperationsAllowlist(json, json.operation) before dispatching to checkASTPermissions, with a comment citing exactly this gap. A role denied an operation can no longer reach it via sql.
• The api_name registration gap is still fully open. Counted on main: of 102 requiredPermissions.set(...) registrations in utility/operation_authorization.ts, exactly 29 still omit the third api_name argument — so a snake_case grant can never match them (get_status, deploy_component measured 403 despite an explicit grant). The affected set includes deployComponent, status.get/set/clear, setComponentFile, getBackup, cleanupOrphanBlobs, readTransactionLog, installModules.

Suggest either splitting the remaining api_name half into its own scoped item or retitling — as written, a reader would re-test the sql bypass and close the whole issue on finding it fixed.

From dispatch QA finding F-293. — Claude (Fable 5)