feat(roles): surface operation-level grants (permission.operations) in the roles/users UI

AGENTS.md

@@ -260,3 +260,39 @@ before the `'*'`. `search_by_conditions` accepts `search_attribute: ['rel', 'sub
 into the related table; when the sub-property IS the related primary key AND we know the local
 foreign key, we query the FK directly instead (indexed, and works on 5.1's ops API which can't
 execute relationship joins).
+
+## Role `permission.operations` — the semantics are not what the shape suggests
+
+Harper 5.0+ roles accept an `operations` allowlist. Almost every intuitive reading of it is wrong,
+and each of these cost a review round on #1628 — verify against the Harper source before changing
+`src/features/instance/config/roles/operations/**` or `src/integrations/api/localRolePermission.ts`.
+
+- **It does not restrict super users.** `verifyPerms` returns early for `super_user`
+  ("admins can do (almost) anything") _before_ the allowlist gate. The allowlist is a way to scope
+  a NON-super role (gate 2 then lets it hold otherwise-SU operations), not a way to narrow an admin.
+- **`super_user`/`cluster_user` + `operations` cannot even be saved.** `validateNoSUPerms` rejects
+  any permission with more than one key that sets either flag, so the combination 400s. Strip the
+  allowlist for those roles rather than sending it.
+- **`structure_user` is different and IS gated** — only `create_table`/`create_attribute`/
+  `drop_table`/`drop_attribute` (plus create/drop database for the boolean form) short-circuit. The
+  array form scopes that carve-out to its listed databases and never reaches create/drop database.
+- **~23 operations are inert when granted.** Their `requiredPermissions` entry omits `api_name`, so
+  the gate compares a camelCase handler name against a snake_case grant and never matches
+  (`deploy_component`, `get_status`, `registration_info`, …). Filed as HarperFast/harper#2175.
+  `sql` is worse: it routes to `verifyPermsAST`, which never consults the allowlist at all.
+- **Alias spellings are inert too** (`describe_database`, `search_by_id`, `create_schema`, …): both
+  spellings dispatch to one handler whose entry carries only the canonical `api_name`.
+- **A non-iterable value takes the instance down.** `listUsers` expands every assigned role's
+  allowlist behind a truthiness-only guard, so a record/`true`/number reaches `expandOperationsPerms`
+  and its `for…of` throws — rejecting the user-cache load and failing authentication for EVERY user.
+  A bare string or an array with non-strings iterates fine (a string per character), so those are
+  invalid but not fatal. Reachable via a v4 upgrade of a role granting a database named `operations`.
+  Filed as HarperFast/harper#2194.
+- **A database named `operations` breaks allowlists instance-wide.** `translateRolePermissions`
+  loops the instance schema, so `perms.operations.tables[t]` runs against the allowlist array and
+  throws for any role carrying one.
+
+Practical consequence for the UI: never describe a restriction the server does not enforce, and
+never advise "fixing" an `operations` value in place — both mistakes shipped and were caught in
+review. `classifyOperationsValue` needs the instance version because the same shape means different
+things on either side of the 5.0.0-alpha.8 floor (the feature's first tagged build, not 5.0.0).

src/features/instance/config/roles/constants/tableDefinition.tsx

@@ -1,6 +1,17 @@
+import { AllowlistSupportedContext } from '@/features/instance/config/roles/operations/AllowlistSupportedContext';
+import {
+	expandEffectiveOperations,
+	summarizeOperations,
+} from '@/features/instance/config/roles/operations/operationsCatalog';
 import { LocalRole } from '@/integrations/api/api.patch';
+import {
+	classifyOperationsValue,
+	getOperationsAllowlist,
+	rolePreventsOperationsAllowlist,
+} from '@/integrations/api/localRolePermission';
 import { ColumnDef, createColumnHelper } from '@/lib/table';
 import { translateSecondsToAgo } from '@/lib/translateSecondsToAgo';
+import { useContext } from 'react';
 
 const columnHelper = createColumnHelper<LocalRole>();
 
@@ -53,4 +64,64 @@ export const dataTableColumns: Array<ColumnDef<LocalRole>> = [
 		enableSorting: false,
 		cell: (props) => (props.row.original.permission.structure_user ? 'Yes' : 'No'),
 	}),
+	columnHelper.display({
+		header: 'Operations',
+		id: 'operations',
+		enableSorting: false,
+		cell: (props) => <OperationsCell permission={props.row.original.permission} />,
+	}),
 ];
+
+/**
+ * A component rather than an inline cell renderer: the verdict for a non-array `operations` value
+ * depends on the instance version, which takes a hook to read.
+ */
+function OperationsCell({ permission }: { permission: LocalRole['permission'] }) {
+	// One observer for the whole table: the query is shared, but a hook per row would still
+	// allocate an observer and query options for every one of them.
+	const allowlistSupported = useContext(AllowlistSupportedContext);
+	if (allowlistSupported === undefined) {
+		// The verdict depends on the version; render nothing rather than guess it for a frame.
+		return null;
+	}
+	const kind = classifyOperationsValue(permission, allowlistSupported);
+	// Below the floor the key is either a real database grant or inert; neither is a restriction.
+	if (kind === 'absent' || kind === 'database' || kind === 'inert') {
+		// aria-label is not exposed on a roleless span, so the text itself has to carry it.
+		return (
+			<>
+				<span aria-hidden>—</span>
+				<span className="sr-only">No operation restriction</span>
+			</>
+		);
+	}
+	if (kind === 'breaks-auth') {
+		return (
+			<span
+				className="text-destructive"
+				title="Harper cannot expand this value; assigning the role breaks authentication instance-wide"
+			>
+				breaks auth
+			</span>
+		);
+	}
+	if (kind === 'malformed') {
+		return <span className="text-destructive" title="Not a list of operation names">invalid</span>;
+	}
+	if (rolePreventsOperationsAllowlist(permission)) {
+		return (
+			<span className="text-destructive" title="Harper rejects an allowlist on a super_user or cluster_user role">
+				conflicts with role
+			</span>
+		);
+	}
+	const effective = expandEffectiveOperations(getOperationsAllowlist(permission) ?? []);
+	const summary = summarizeOperations(effective);
+	return (
+		<span title={summary}>
+			{effective.length} allowed
+			{/* title is hover-only, so the names need a path that reaches keyboard and screen readers. */}
+			<span className="sr-only">: {summary}</span>
+		</span>
+	);
+}

src/features/instance/config/roles/defaultCalculator.test.ts

@@ -0,0 +1,67 @@
+import { calculateDefaultPermissions } from '@/features/instance/config/roles/defaultCalculator';
+import { InstanceDatabaseMap, LocalRolePermission } from '@/integrations/api/api.patch';
+import { orderPermissionKeys, withOperations } from '@/integrations/api/localRolePermission';
+import { describe, expect, it } from 'vitest';
+
+// JSON.parse, not an object literal: a literal `__proto__` key sets the prototype instead of
+// creating an own property, so the fixture itself has to come from parsed JSON.
+const databaseMap = (json: string) => JSON.parse(json) as InstanceDatabaseMap;
+const oneTable = '{"dog":{"attributes":[{"attribute":"id"}]}}';
+
+describe('calculateDefaultPermissions', () => {
+	it('keeps a database named __proto__ as an own, serializable key', () => {
+		// Plain assignment would hit the prototype setter: the database would vanish from the
+		// template and from JSON.stringify, so the role could never be granted it.
+		const result = calculateDefaultPermissions({
+			instanceDatabaseMap: databaseMap(`{"__proto__":{"dog":{"attributes":[{"attribute":"id"}]}}}`),
+			currentRolePermissions: {},
+			version: '5.2.2',
+			showAttributes: false,
+		});
+
+		expect(Object.hasOwn(result, '__proto__')).toBe(true);
+		// Read the own property explicitly: `parsed.__proto__` would resolve the prototype instead.
+		const serialized = JSON.parse(JSON.stringify(result)) as object;
+		const record = Object.getOwnPropertyDescriptor(serialized, '__proto__')?.value as
+			| { tables: Record<string, unknown> }
+			| undefined;
+		expect(record?.tables).toHaveProperty('dog');
+		// The round trip the editor actually performs must preserve it too.
+		const roundTripped = JSON.parse(JSON.stringify(withOperations(orderPermissionKeys(result), ['sql'])));
+		expect(Object.hasOwn(roundTripped, '__proto__')).toBe(true);
+	});
+
+	it('skips a database named like a reserved key when the instance reserves it', () => {
+		const map = databaseMap(`{"operations":{"dog":{"attributes":[{"attribute":"id"}]}}}`);
+		// 5.2 reserves `operations` for the allowlist, so writing the database there would clobber it.
+		expect(
+			calculateDefaultPermissions({
+				instanceDatabaseMap: map,
+				currentRolePermissions: { operations: ['sql'] },
+				version: '5.2.2',
+				showAttributes: false,
+			}).operations,
+		).toEqual(['sql']);
+
+		// Below the allowlist floor the same name is just a database, so it gets a permission record.
+		const legacy = calculateDefaultPermissions({
+			instanceDatabaseMap: map,
+			currentRolePermissions: {},
+			version: '4.7.3',
+			showAttributes: false,
+		}).operations as unknown as { tables: Record<string, unknown> };
+		expect(legacy.tables).toHaveProperty('dog');
+	});
+
+	it('preserves an existing allowlist while rebuilding table permissions', () => {
+		const permission: LocalRolePermission = { operations: ['read_only'] };
+		const result = calculateDefaultPermissions({
+			instanceDatabaseMap: databaseMap(`{"data":${oneTable}}`),
+			currentRolePermissions: permission,
+			version: '5.2.2',
+			showAttributes: false,
+		});
+		expect(result.operations).toEqual(['read_only']);
+		expect(result.data).toBeDefined();
+	});
+});

src/features/instance/config/roles/defaultCalculator.ts

@@ -1,9 +1,12 @@
+import { supportsOperationsAllowlist } from '@/features/instance/config/roles/operations/operationsCatalog';
 import {
 	InstanceDatabaseMap,
 	LocalLegacyRolePermissionTable,
 	LocalRolePermission,
 	LocalRolePermissionTable,
+	LocalRoleSchemaRecord,
 } from '@/integrations/api/api.patch';
+import { getDatabasePermissionRecord, RESERVED_PERMISSION_KEYS } from '@/integrations/api/localRolePermission';
 import { keyBy } from '@/lib/keyBy';
 
 export function calculateDefaultPermissions({
@@ -28,25 +31,44 @@ export function calculateDefaultPermissions({
 	const [major, minor, patch] = version.split('.').map(number => parseInt(number, 10));
 	const legacy = version !== '2.0.000' && major <= 2 && minor <= 1 && patch <= 2;
 
+	// Plain assignment of a `__proto__` key would hit the prototype setter rather than create an own
+	// property, so the database would vanish from the template. Harper permits the name, so define
+	// the property instead of dropping the database.
+	const setDatabase = (name: string, record: LocalRoleSchemaRecord) => {
+		Object.defineProperty(permissionStructure, name, {
+			value: record,
+			writable: true,
+			enumerable: true,
+			configurable: true,
+		});
+		return record;
+	};
+
+	const allowlistSupported = supportsOperationsAllowlist(version);
+
 	for (const databaseName in instanceDatabaseMap) {
-		permissionStructure[databaseName] = {
-			tables: {},
-		};
+		if (RESERVED_PERMISSION_KEYS.has(databaseName) && (databaseName !== 'operations' || allowlistSupported)) {
+			// A database named like a reserved permission key cannot be expressed in role JSON —
+			// writing it here would clobber the reserved value (e.g. a 5.0+ operations allowlist).
+			// Pre-5.0 Harper has no reserved `operations`, so there a database by that name is real.
+			continue;
+		}
+		const databaseRecord = setDatabase(databaseName, { tables: {} });
+		const extantDatabasePermissions = currentRolePermissions
+			&& getDatabasePermissionRecord(currentRolePermissions, databaseName, allowlistSupported);
 		for (const tableName in instanceDatabaseMap[databaseName]) {
 			const thisTable = instanceDatabaseMap[databaseName][tableName];
 			const attributes = thisTable.attributes.map((a) => a.attribute).sort();
+			const extantTablePermissions = extantDatabasePermissions
+				&& extantDatabasePermissions.tables?.[tableName];
 			if (legacy) {
-				const extantTablePermissions = currentRolePermissions && currentRolePermissions[databaseName]
-					&& currentRolePermissions[databaseName].tables[tableName];
-				permissionStructure[databaseName].tables[tableName] = buildLegacy(
+				databaseRecord.tables[tableName] = buildLegacy(
 					extantTablePermissions as LocalLegacyRolePermissionTable,
 					attributes,
 					showAttributes,
 				);
 			} else {
-				const extantTablePermissions = currentRolePermissions && currentRolePermissions[databaseName]
-					&& currentRolePermissions[databaseName].tables[tableName];
-				permissionStructure[databaseName].tables[tableName] = buildCurrent(
+				databaseRecord.tables[tableName] = buildCurrent(
 					extantTablePermissions as LocalRolePermissionTable,
 					attributes,
 					showAttributes,

src/features/instance/config/roles/index.tsx

@@ -4,6 +4,7 @@ import { Button } from '@/components/ui/button';
 import { useInstanceClientIdParams } from '@/config/useInstanceClient';
 import { dataTableColumns } from '@/features/instance/config/roles/constants/tableDefinition';
 import { AddRoleModal } from '@/features/instance/config/roles/modals/AddRoleModal';
+import { AllowlistSupportedProvider } from '@/features/instance/config/roles/operations/AllowlistSupportedContext';
 import { useRefreshClick } from '@/hooks/useRefreshClick';
 import { LocalRole } from '@/integrations/api/api.patch';
 import { getListRolesQueryOptions } from '@/integrations/api/instance/auth/getListRoles';
@@ -66,25 +67,27 @@ export function ConfigRolesIndex() {
 
 	return (
 		<Suspense fallback={<Loading className="flex flex-col items-center justify-center h-full" text="Loading..." />}>
-			<SimpleBrowseDataTable
-				columns={dataTableColumns}
-				data={localRoles}
-				isFetching={isFetching}
-				onRowClick={onRowClick}
-			>
-				<Button variant="defaultOutline" onClick={onRefreshClick} accessKey="r" disabled={isFetching || isRefetching}>
-					<RefreshCwIcon />
-					<span className="hidden lg:inline-block">
-						<u>R</u>efresh
-					</span>
-				</Button>
-				<Button variant="positiveOutline" onClick={onAddClicked} accessKey="a" disabled={isAddModalOpen}>
-					<PlusIcon />
-					<span>
-						<u>A</u>dd
-					</span>
-				</Button>
-			</SimpleBrowseDataTable>
+			<AllowlistSupportedProvider>
+				<SimpleBrowseDataTable
+					columns={dataTableColumns}
+					data={localRoles}
+					isFetching={isFetching}
+					onRowClick={onRowClick}
+				>
+					<Button variant="defaultOutline" onClick={onRefreshClick} accessKey="r" disabled={isFetching || isRefetching}>
+						<RefreshCwIcon />
+						<span className="hidden lg:inline-block">
+							<u>R</u>efresh
+						</span>
+					</Button>
+					<Button variant="positiveOutline" onClick={onAddClicked} accessKey="a" disabled={isAddModalOpen}>
+						<PlusIcon />
+						<span>
+							<u>A</u>dd
+						</span>
+					</Button>
+				</SimpleBrowseDataTable>
+			</AllowlistSupportedProvider>
 			<AddRoleModal isModalOpen={isAddModalOpen} onChangesSaved={onRoleAdded} setIsModalOpen={setIsAddModalOpen} />
 			{isEditModalOpen && (
 				<EditRoleModal