Skip to content

docs(roles): state the limits of the operations allowlist #631

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dawsontoth wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(roles): state the limits of the operations allowlist #631

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions reference/users-and-roles/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,14 @@ The `operations` field in a permission object restricts which Operations API cal

Operations normally restricted to `super_user` can be selectively granted by including them in the list. If `operations` is not set, the role can call any non-`super_user` operation, subject to table CRUD permissions.

The field scopes an ordinary role; it is not a way to narrow an administrator. Three limits follow from that, and each one surprises people:

- **`super_user` and `cluster_user` roles cannot carry an allowlist at all.** `add_role` and `alter_role` reject any permission that sets either flag alongside other keys, so the combination is a validation error rather than a restricted admin. Authorization also clears a `super_user` role before the allowlist is consulted.

@gemini-code-assist gemini-code-assist Bot Aug 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The phrase 'clears a super_user role' is misleading as it might imply that the role or its permissions are being deleted or emptied. Based on the actual authorization logic, it would be clearer to state that authorization bypasses the allowlist check or returns early for super_user roles.

Suggested change
- **`super_user` and `cluster_user` roles cannot carry an allowlist at all.** `add_role` and `alter_role` reject any permission that sets either flag alongside other keys, so the combination is a validation error rather than a restricted admin. Authorization also clears a `super_user` role before the allowlist is consulted.
- **<code>super_user</code> and <code>cluster_user</code> roles cannot carry an allowlist at all.** <code>add_role</code> and <code>alter_role</code> reject any permission that sets either flag alongside other keys, so the combination is a validation error rather than a restricted admin. Authorization also bypasses the allowlist check for a <code>super_user</code> role.

- **`structure_user` roles bypass the allowlist for DDL only.** `create_table`, `create_attribute`, `drop_table`, and `drop_attribute` are reachable regardless of the list — plus `create_database`/`drop_database` when `structure_user` is `true`. When it is an array of database names, that carve-out applies only to those databases. Every other operation is still gated normally.
- **`sql` is not gated by this field.** SQL statements are authorized against table CRUD permissions on their own path, so listing `sql` neither grants nor restricts them, and omitting it does not prevent a role from running SQL. This matters when reading the `read_only` and `standard_user` groups below, both of which include the name.

The value must be an array of strings. A non-array value is rejected on write, and a role that already holds one (for example a pre-5.0 role that granted a database named `operations`) can prevent the instance from loading its user cache — see [HarperFast/harper#2194](https://github.com/HarperFast/harper/issues/2194).

@gemini-code-assist gemini-code-assist Bot Aug 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

According to the repository's guidelines, when documenting behavior changes to an existing surface (such as the change in v5.0.0 where operations became a reserved array of strings instead of allowing a database named operations), we should use the <VersionBadge type="changed" version="vX.Y.0" /> format.

Suggested change
The value must be an array of strings. A non-array value is rejected on write, and a role that already holds one (for example a pre-5.0 role that granted a database named `operations`) can prevent the instance from loading its user cache — see [HarperFast/harper#2194](https://github.com/HarperFast/harper/issues/2194).
The value must be an array of strings. <VersionBadge type="changed" version="v5.0.0" /> A non-array value is rejected on write, and a role that already holds one (for example a pre-5.0 role that granted a database named <code>operations</code>) can prevent the instance from loading its user cache — see [HarperFast/harper#2194](https://github.com/HarperFast/harper/issues/2194).
References
  1. Use the <VersionBadge type="changed" version="vX.Y.0" /> format when documenting behavior changes to existing surface, as prescribed in the repository's guidelines.


**Permission Groups**

Groups expand to a predefined set of operations and can be mixed with individual operation names:
Expand Down