roles.yaml cannot grant an operation the same component registers: roles plugin loads before jsResource

[dawsontoth]

A component's own roles.yaml cannot grant an operation that the same component's resources.js registers, because the roles plugin runs before jsResource in the same worker. Static trace against main @ ddb2716; not reproduced against a live instance, so please correct me if I've misread the load order.

This is adjacent to but distinct from the cross-thread grantability gap being fixed separately (companion PR linked below) — that one was main-thread validateOperations never learning about worker registrations at all. This one is a same-thread ordering problem and survives that fix.

The mechanism

server.registerOperation({ requiresSuperUser }) calls registerOperationPermission, which marks the operation grantable in the registering thread's module-local set (utility/operationPermissions.ts → dynamicallyRegisteredOps). A component's roles.yaml is applied by resources/roles.ts → handleApplication, which calls addRole/alterRole (security/role.ts) → addRoleValidation → validateOperations.

Both run in the same worker (componentLoader.ts:669 gates handleApplication on resources.isWorker), so grantability is visible in principle. The problem is ordering:

• components/DEFAULT_CONFIG.ts declares plugins in the order rest, graphqlSchema, roles, jsResource, fastifyRoutes, static.
• componentLoader.ts:542 iterates with for (const componentName in config) — insertion order.

So roles is processed before jsResource. When roles.yaml is validated, the registerOperation calls in resources.js have not run yet, the name is not in dynamicallyRegisteredOps, and the role is rejected with INVALID_OPERATIONS_OP:

Invalid operations value '<op>'. Must be a valid operation name or group (e.g. 'read_only').

Why it matters

Declaring an operation and the role that may call it in the same component is the natural shape — it's the whole point of shipping roles.yaml alongside resources.js. Today an author has to either grant the operation out-of-band via the add_role API after deploy, or split the operation and its role across two components ordered so the registering one loads first.

It fails closed (a rejected role, never a widened one), so this is a DX/correctness bug, not a security hole.

Repro sketch

A single component with:

// resources.js
server.registerOperation({
	name: 'my_component_op',
	requiresSuperUser: true,
	execute: async function myComponentOp() { return { ok: true }; },
});

# roles.yaml
my_op_role:
  operations:
    - my_component_op

Expected: the role is created with the grant. Actual (expected from the trace): component load reports the role as invalid.

Possible directions

• Order jsResource before roles in DEFAULT_CONFIG — smallest change, but relies on object key order as a load-order contract, and only helps the default config (an explicit component config with its own key order would still be able to get this wrong).
• Defer roles.yaml application until after the component's other plugins have loaded (e.g. apply on the existing deploy:end/ready hook rather than inline at handleEntry) — resources/roles.ts already has a deploy:end reconcile path, so this may be mostly a matter of which pass performs the first application.
• Make load order explicit rather than incidental, so a plugin can declare that it must run after jsResource.

I'd lean toward the second — the reconcile pass already exists and ordering-by-key-insertion is a fragile contract to lean on.

Tests worth adding

An integration test with a single fixture component that registers a grantable operation in resources.js and grants it in its own roles.yaml, asserting the role exists with the grant after load. integrationTests/components/registered-operation.test.ts now covers the API-side (add_role) path across the worker/main boundary but nothing exercises roles.yaml.

---

🤖 Filed by Claude on behalf of @dawsontoth

[dawsontoth]

Companion PR for the cross-thread half of this: #2260 (carries grantable on the OPERATION_REGISTERED announcement so main-thread validateOperations accepts worker-registered names). It does not fix this issue — roles.yaml is applied on the same worker that registers the operation, so the gap here is load ordering rather than cross-thread propagation, and it survives that fix.

[kriszyp]

Live confirmation of #2203, plus a larger blast radius than filed

#2203 says "Static trace against main @ ddb2716; not reproduced against a live instance, so
please correct me if I've misread the load order." The load order is read correctly, and it
reproduces. But the consequence is bigger than one rejected role.

What happens

A component shipping both resources.js (calling server.registerOperation) and its own
roles.yaml granting that operation loses the failing role and every role listed after it in
the same file — including roles that grant only built-in operations and reference nothing the
component owns.

With the failing role listed first in a 3-role file:

QA-914b roles present: ["super_user"]
QA-914b roles missing: ["qa914b_first_failing_role","qa914b_after_builtin_role","qa914b_after_second_builtin_role"]

qa914b_after_builtin_role grants only describe_all; qa914b_after_second_builtin_role grants
only search_by_value. Neither mentions the component's operation. Both are gone.

With the failing role listed last, the two roles before it are created correctly and work
end-to-end (the control user calling describe_all gets 200). So the blast radius is a suffix
of the file, not the whole file.

Downstream, the role's absence is total rather than a dropped grant:

add_user (role: qa914_role)  -> 404 {"error":"qa914_role role not found"}
subsequent op call as that user -> 401 {"error":"Login failed"}

It fails closed — a missing role, never a widened one — so this is silent authorization
drift, not a security hole. It does not self-heal across a full restart against the same
data directory (verified: role still absent after killHarper + startHarper).

Repro

harper 689023f14 (= origin/main). No non-default config beyond logging: {console:true, level:'error'}.

npm run test:integration -- "integrationTests/qa-scratch/qa914b-roles-abort-cascade.test.ts"

Fixture — a component with no config.yaml (so it falls back to DEFAULT_CONFIG):

// resources.js
server.registerOperation({
  name: 'my_component_op_b', requiresSuperUser: true,
  execute: async () => ({ ok: true }),
});

# roles.yaml
qa914b_first_failing_role:        { super_user: false, operations: [my_component_op_b] }
qa914b_after_builtin_role:        { super_user: false, operations: [describe_all] }
qa914b_after_second_builtin_role: { super_user: false, operations: [search_by_value] }

The spec includes a load-control that must be read alongside the result: a superuser calling
my_component_op_b returns 200 {"ok":true}, which proves jsResource ran and the operation
registered. Without it, "only super_user exists" would be equally explained by the component
never loading at all.

Mechanism

• components/DEFAULT_CONFIG.ts:6-10 — roles is declared before jsResource.
• components/componentLoader.ts:542 — plugins iterate in object insertion order; a component
  with no config.yaml gets DEFAULT_CONFIG directly (componentLoader.ts:470).
• components/componentLoader.ts:703 awaits sequentiallyHandleApplication per plugin, which
  awaits handleApplication and scope.waitForInitialLoads() (:348). This is a hard
  barrier, not a race: roles.yaml fully completes before resources.js is imported
  (resources/jsResource.ts:77, awaited via Scope.ts:480).
• So the name is absent from dynamicallyRegisteredOps (utility/operation_authorization.ts:126),
  validateOperations rejects it (utility/operationPermissions.ts:94), role_validation.ts:148
  → security/role.ts:43 throws INVALID_OPERATIONS_OP.
• The cascade: resources/roles.ts:85 is for (let roleName in rolesToDefine) { ...; await ensureRoleFn(role); } with no per-role try/catch. The throw kills the loop. enqueue
  (roles.ts:23) catches only to keep the queue usable for later events — it does not resume the
  aborted loop.

This is order-dependent, not "components without config.yaml": an explicit config.yaml
listing roles before jsResource is equally affected, and one listing jsResource first is
predicted safe (source-supported, not measured).

Suggested fix shape

Two independent changes, and the first is worth doing regardless of how #2203 is resolved:

1. Per-role isolation at resources/roles.ts:85 — catch per role, log the role name and the
   validation reason, continue. One bad role should never silently delete its file's suffix.
2. The ordering itself — the issue's own option 2 (defer the first roles.yaml application
   until the component's other plugins have loaded, reusing the existing deploy:end reconcile
   path) is the durable one; reordering DEFAULT_CONFIG keys only fixes the default config and
   leans on key-insertion order as a load contract.

Existing work checked

Searched HarperFast/harper (1083 issues, 800 PRs) and HarperFast/harper-pro (226 issues, 518
PRs), all states, on roles.yaml, role/grant, registerOperation, plugin/load order, jsResource.

• roles.yaml cannot grant an operation the same component registers: roles plugin loads before jsResource #2203 (OPEN) — this issue; filed the single-role symptom from a static trace only.
• Allow a component-registered operation to be granted in a role's operations allowlist #2260 (OPEN, draft) — carries grantable on the OPERATION_REGISTERED announcement for
  the cross-thread case. Its author states it does not fix roles.yaml cannot grant an operation the same component registers: roles plugin loads before jsResource #2203, and it is not on origin/main.
• server.registerOperation() calls in a component's resources.js are unreachable via the ops API #1736 / PR fix: make server.registerOperation() from components reachable via the ops API (#1736) #1743 (both closed/merged) — made component-registered ops reachable via the ops
  API; different layer. Registered operations can't declare permissions — forces hardcoded inline super_user checks #1598 / PR feat(auth): let registered operations declare permissions for scoped delegation #1599 — let registered operations declare permissions.
• role operations allowlist: grants are gate-inert for ops registered without api_name (deploy_component, get_status, …); sql bypasses the allowlist #2175, export_local/export_to_s3 via operations allowlist bypasses table-level grants (non-SQL nested search) #2215, Direct sql operation bypasses the operations allowlist (gate 1) #2216 — operations-allowlist gaps; adjacent, none is this.
• Nothing tracks the suffix cascade.

What this does NOT prove

• Single-worker only — harness default THREADS_COUNT=1. Each worker holds its own
  dynamicallyRegisteredOps; multi-worker was not exercised.
• Not tested on a live deploy_component. resources/roles.ts:49's deploy:end reconcile
  re-runs handleFile per cached file with a try/catch, and it completes all roles in isolation
  once the failure condition clears — so a real deploy may self-heal where a boot does not. This is
  the single fact that decides whether production deploys are affected.
• Not bisected — the sequential-await structure looks long-standing, but "predates a recent
  change" is inference, not verification.
• The config.yaml reordering workaround is source-predicted, not measured.

---

From dispatch QA finding F-303, re-verified against harper origin/main e16d961, 2026-08-29 (roles.ts loop still has no per-role try/catch; #2260 merged 2026-08-26 adds the cross-thread grantable registry but does not reorder loading or isolate the loop). -- Claude (Fable 5)