Non-array permission.operations throws during user-cache load, breaking authentication instance-wide (reachable via v4→v5 upgrade)

[dawsontoth]

Found by @cb1kenobi reviewing the Studio roles UI (HarperFast/studio#1628), traced against v5.2.2 (d46ea1f30) and confirmed identical in v5.0.0 and v5.1.0.

Summary

A role whose permission.operations is not an array makes the user-cache load throw, which fails authentication for every user on the instance — not just the holder of that role.

The path

security/user.ts, in the loop that builds the user cache:

for (let user of users) {
	user = _.cloneDeep(user);
	user.role = roleMapObj[user.role];
	appendSystemTablesToRole(user.role);
	cacheExpandedOperationsPerms(user.role);   // ← here
	userMap.set(user.username, user);
}

function cacheExpandedOperationsPerms(userRole: UserRole) {
	if (!userRole?.permission?.operations) return;          // truthiness only
	userRole.permission._expandedOperations = expandOperationsPerms(userRole.permission.operations);
}

expandOperationsPerms (utility/operationPermissions.ts) does for (const item of operations), so any non-array truthy value throws TypeError: operations is not iterable. That rejects listUsers() → setUsersWithRolesCache → findAndValidateUser, i.e. auth for the whole instance.

Reproduced for {tables:{…}}, {}, and true. (A bare string doesn't throw — it iterates per character and silently expands to garbage operation names, which is its own small bug.)

How a role gets into that state

add_role/alter_role reject it today (OPERATIONS_MUST_BE_ARRAY), so not through the API. The reachable path is a v4 → v5 upgrade: operations only became a reserved database name in #1016, so a v4 role granting a database named operations carries permission.operations = { tables: … } forward. Nothing rewrites it on upgrade, and the first cache load after a user holds that role takes auth down.

Only roles assigned to a user are expanded, so an orphaned role is inert until someone assigns it — which makes the failure look unrelated to the change that triggered it.

Suggested fix

Make the guard shape-aware rather than truthiness-based, and fail soft for a value that can't be expanded:

if (!Array.isArray(userRole?.permission?.operations)) return;

That leaves the role unexpanded; verifyPerms then hits the same non-iterable value at request time, so it would want the same treatment (or a normalization at upgrade). Deciding what a malformed allowlist means is the real question — deny-all is the safe reading, but silently ignoring it would also be defensible given the value predates the feature. Either beats an instance-wide auth outage.

Worth an upgrade-time check too: scanning hdb_role for a non-array operations during the v4 → v5 migration would catch it before the instance restarts.

Studio (#1628) now warns on such a role and names assignment as the trigger, but it can only do that for someone who can still log in.

---

🤖 Filed by Claude on behalf of @dawsontoth

[dawsontoth]

Two refinements from @cb1kenobi's continued review, both verified against dist/ at d46ea1f30.

1. Only non-iterable values throw. My original report implied any non-array does. Actual behavior:

THROW {"tables":{}}         TypeError: operations is not iterable
THROW true                  TypeError: operations is not iterable
THROW 42                    TypeError: operations is not iterable
OK    "read_only"        -> ["r","e","a","d","_","o","n","l","y"]   (9 entries)
OK    ["read_only", 42]  -> full read_only expansion + 42            (16 entries)

So a bare string and an array with non-string members expand successfully into a garbage allowlist rather than crashing. That's a second, quieter bug: expandOperationsPerms accepts anything iterable, so a role saved before validation tightened (or written directly to hdb_role) silently gets a nonsense allowlist that gate 1 then enforces. A shape check in cacheExpandedOperationsPerms should cover both — Array.isArray rejects the string too.

2. A database named operations breaks allowlists for every role on the instance. Separate from the crash, and reachable on a clean 5.x instance that upgraded with such a database. translateRolePermissions iterates the instance schema, not the role:

Object.keys(schema).forEach((s) => {        // s === 'operations'
	if (perms[s]) {                          // a valid allowlist array is truthy
		Object.keys(schema[s]).forEach((t) => {
			if (perms[s].tables[t])              // ['read_only'].tables -> undefined[t]

So while that database exists, any role carrying a normal operations array throws in permission translation → getRolePermissions rethrows → 500 on every request that user makes. Reproduced standalone. Skipping reserved keys in that loop (or resolving the collision at upgrade) would fix it.

Together these make the upgrade case worse than first reported: the instance can be left where allowlists cannot be used at all, and where the natural remedy (replace the record with an array) moves from one failure to another.

---

🤖 Filed by Claude on behalf of @dawsontoth