feat(rbac): resolver + RequirePermission middleware (PR 2a of 4)

[mcharles-square]

First half of PR 2 of the four-part granular RBAC plan (the plan PR). Building on the foundation in #283.

This PR introduces the permission resolver and the RequirePermission middleware — the security gate the rest of the codebase will route through. Critically, no callsites are swapped yet: every existing RequireAdmin check still gates handler entry, this PR is purely additive. The gate exists, but nothing reads it. PR 2b will flip the switch (swap callers and neutralize the legacy user_organization.role_id column).

Splitting PR 2 in half keeps the "live security gate flip" change small and reviewable — see #283's review history for context (five rounds, many design-level pivots). The resolver-and-middleware piece doesn't change behavior, so it can settle in review without holding up the swap.

What landed

domain/authz/effective.go — in-memory decision type

EffectivePermissions is the per-request immutable snapshot of one user's authorization state within one organization.

• Has(key, ResourceContext) implements narrowing semantics from the plan:
  • Org-scope assignment grants the action everywhere within the org.
  • Site-scope assignment overrides the org grant at that site only, so admins can add a smaller site-scoped role to narrow a user without revoking their org-wide access.
  • Org-scoped actions (no site context in the request) are never shadowed by site-scope grants — there's no site key to narrow on.
• FlatKeys() projects the union for UserInfo.permissions (client-side coarse gate; the server still enforces scope via Has() on every call).
• Pure data structure with no I/O; built test-first with 10 unit tests covering the narrowing matrix, multi-site union, empty deny, unknown-key deny, and the FIELD_TECH AE.

domain/authz/resolver.go — PermissionResolver

• LoadEffective(ctx, userID, orgID) runs one query (ListEffectivePermissionsForUser) against user_organization_role × role × role_permission and materializes the result into an EffectivePermissions.
• Groups flat (assignment_id, scope, permission_key) rows by assignment id so multi-permission roles fold into one Assignment value.
• A user with no live assignments gets a non-nil empty value — the fail-closed default for a deactivated user or a user who was never in this org.
• 5 DB-backed integration tests (via testutil.GetTestDB) cover SUPER_ADMIN-at-org-scope, FIELD_TECH-at-site-scope, narrowing end-to-end with two assignments, soft-delete is ignored, and empty deny-all.

handlers/middleware/permission.go — RequirePermission

The runtime call site each handler will use in place of RequireAdmin. Returns the session.Info for handlers that need the caller's identity, or one of:

• Unauthenticated — no session.Info on context.
• Internal — fail-closed; EffectivePermissions missing from context (the interceptor failed to populate it). ALLOW is never the fail-closed default.
• PermissionDenied with structured JSON body:

  {"required": "<permission_key>", "scope": {"site_id": <N>}}

  Scope echoes the caller's ResourceContext only — never server-side assignment IDs, role names, or the caller's effective permission list.

Internal-actor short-circuit: when session.Info.Actor is non-empty (scheduler, curtailment-reconciler, etc.), RequirePermission short-circuits to ALLOW without consulting EffectivePermissions. Synthesized sessions have no real user; they're trusted by virtue of running in-process.

WithEffectivePermissions(ctx, eff) is the public stash function used by the interceptor; the read path is private to enforce that handlers only consume via RequirePermission.

8 unit tests cover allow, deny (both org-scoped and site-scoped payload shape), unauthenticated, fail-closed-on-missing, scheduler short-circuit, curtailment-reconciler short-circuit, and the narrowing matrix.

handlers/interceptors/authentication.go — wiring

Both authenticateWithSession and authenticateWithApiKey end with a shared loadEffectivePermissions(ctx, info) helper that calls resolver.LoadEffective and stashes the result via middleware.WithEffectivePermissions before returning the request context.

• API-key callers inherit the user's current effective set on every request (live inheritance). Revocation propagates on next request. Snapshot-at-issue is out of scope (noted in resolver godoc).
• DB or wiring errors from LoadEffective flow through the same classifyLookupError path as user/role lookups — broken resolver path fails closed.
• main.go constructs the resolver after Reconcile (so per-org built-in rows exist) and threads it into NewAuthInterceptor.
• testutil.ServiceProvider gains a PermissionResolver field; all NewAuthInterceptor callsites updated.

What this PR does NOT do

• Does not swap any RequireAdmin callers — every handler still uses the old gate. PR 2b.
• Does not introduce the rpc_permissions.go declaration map or the contract test — PR 2b.
• Does not rename user_organization.role_id or add the raising trigger — PR 2b.
• Does not delete handlers/middleware/admin.go — kept until callers move in PR 2b.

Test plan

• go build ./... clean
• go vet ./... clean
• lefthook run pre-push (golangci-lint) clean
• Non-DB tests pass: 10 EffectivePermissions tests + 8 RequirePermission middleware tests, all green
• DB-dependent resolver integration tests (5 functions) — need Docker for the full reconcile+assign+resolve loop
• Behavior smoke: existing handler gates still work because no callsite was swapped; lefthook run pre-push covers the typecheck for the interceptor threading the new resolver in

Rollback

Reverting this PR removes the resolver call from the auth interceptor, the new files, and the PermissionResolver field on AuthInterceptor. No schema change, no data migration, no live behavior change to reverse.

[github-actions]

🔐 Codex Security Review

Note: This is an automated security-focused code review generated by Codex.
It should be used as a supplementary check alongside human review.
False positives are possible - use your judgment.

Scope summary

• Reviewed pull request diff only (3f157ca2f68465471f88a1af8397104bae72d239...7a202c74f2fc9f198c8cc7066a75131df2079684, exact PR three-dot diff)
• Model: gpt-5.5

💡 Click "edited" above to see previous reviews for this PR.

---

Review Summary

Overall Risk: MEDIUM

Findings

[MEDIUM] Permission Rechecks Reuse Stale Authorization Snapshot

• Category: Auth
• Location: server/internal/handlers/middleware/permission.go:102
• Description: RequirePermission only reads the EffectivePermissions value cached on the request context during authentication. The new comment says long-running RPCs can re-invoke RequirePermission so revocation propagates within the same streaming session, but re-invocation uses the same cached snapshot and never reloads from the resolver.
• Impact: If a user or API key loses a role/permission while a long-running RPC is active, later side effects in that same RPC can continue under the permissions loaded at request start. This matters for firmware updates, log downloads, and streaming control paths where a request can outlive an operator’s revocation action.
• Recommendation: Either document that permissions are strictly request-start snapshots, or add a fresh-check path for long-running handlers that reloads permissions from PermissionResolver before each significant side effect.

Notes

No SQL injection, command injection, pool hijacking, protobuf wire-format, plugin-boundary, or frontend security issues were evident in the reviewed diff.

---

_{Generated by Codex Security Review |
Triggered by: @mcharles-square |
Review workflow run}

[Copilot]

Pull request overview

Adds the new granular RBAC “effective permissions” snapshot + resolver, wires it into the auth interceptor, and introduces a RequirePermission middleware that will become the new handler gate (without switching any call sites yet).

Changes:

• Introduces authz.EffectivePermissions with narrowing semantics and a DB-backed PermissionResolver.
• Adds handlers/middleware.RequirePermission and context plumbing for per-request effective permissions.
• Wires resolver loading into the auth interceptor and updates server/test wiring to pass the resolver.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
server/internal/testutil/service_provider.go	Adds PermissionResolver to test service provider wiring.
server/internal/testutil/infrastructure_provider.go	Threads the resolver into NewAuthInterceptor in test infra.
server/internal/handlers/middleware/permission.go	New RequirePermission middleware + context stash/accessors and structured deny payload.
server/internal/handlers/middleware/permission_test.go	Unit tests for allow/deny, payload shape, fail-closed behavior, and actor short-circuit.
server/internal/handlers/interceptors/config_test.go	Updates interceptor construction signature in tests.
server/internal/handlers/interceptors/authentication.go	Loads/stashes effective permissions after auth (session + API key).
server/internal/handlers/interceptors/authentication_test.go	Updates interceptor construction to pass resolver in integration tests.
server/internal/handlers/interceptors/authentication_apikey_error_test.go	Updates interceptor construction signature.
server/internal/domain/authz/effective.go	New in-memory effective-permissions decision structure + Has/FlatKeys.
server/internal/domain/authz/effective_test.go	Unit tests for narrowing semantics, unions, and flat projection.
server/internal/domain/authz/resolver.go	New resolver that materializes EffectivePermissions from one SQL query.
server/internal/domain/authz/resolver_test.go	DB-backed integration tests for org/site scope and narrowing behavior.
server/cmd/fleetd/main.go	Constructs and injects the resolver into the auth interceptor at boot.

[mcharles-square]

Codex Security Review (round 1 on #301) — response

Both findings addressed in e7f762a.

HIGH — Zero-permission site assignments fail open to org-scope grants

A site-scoped role with zero permissions produces no permission rows, so the resolver never records bySite[siteID]; Has then falls back to the user's org-scope grant.

You're right — the INNER JOIN dropped empty-role assignments and narrowing collapsed. Fixed by switching ListEffectivePermissionsForUser to LEFT JOIN role_permission and LEFT JOIN permission, with permission_key now sql.NullString. The resolver creates the Assignment (and therefore the bySite[siteID] marker) on first sight of the assignment id, and only appends a permission key when the row carries a non-null one. An assignment with zero permissions still triggers narrowing.

Two regression tests added:

• TestEffective_ZeroPermissionSiteAssignmentStillNarrows — pure unit test against NewEffectivePermissions directly.
• TestResolver_ZeroPermissionSiteAssignmentStillNarrows — DB-backed, creates an empty custom role via UpsertCustomRoleForOrg and confirms an org-scope ADMIN + zero-permission site role denies miner:reboot at the targeted site, but still allows it at sites with no narrower assignment.

MEDIUM — Any non-empty internal actor bypasses all permission checks

Switch on explicit allowed constants (session.ActorScheduler, session.ActorCurtailment) and fail closed for unknown non-empty actors. Add a test proving an unknown actor does not bypass EffectivePermissions.

Done. Replaced the info.Actor != "" short-circuit with an explicit allowlist:

if info.Actor != "" {
    switch info.Actor {
    case session.ActorScheduler, session.ActorCurtailment:
        return info, nil
    default:
        return nil, fleeterror.NewInternalErrorf(
            "authz: unknown internal actor %q; refusing to short-circuit RBAC",
            info.Actor,
        )
    }
}

TestRequirePermission_UnknownActorDoesNotBypass mounts a context with Actor: session.Actor("future-orchestrator-typo") and no EffectivePermissions; the call returns Internal (not ALLOW) — proves the typo path does not silently grant.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e7f762ab8c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ankitgoswami]

looks good