feat(permissions): enforce the built-in user role (remove its bypass)

[viktormarinho]

Summary

Capstone of the capability-RBAC work. Until now the built-in user role bypassed all permission checks server-side, so UI capability gating only truly bit custom roles — a user had full org access via the API.

This flips the runtime bypass to ADMIN_ROLES (owner/admin) only. A user is now enforced like any member: it gets basic-usage (granted out-of-band in AccessControl) plus its explicit Better Auth / connection grants, and nothing else.

Prerequisite (#3654, merged) rounded out basic-usage to cover every normal-member flow first, so members keep working after the flip.

The change

One functional line — createBoundAuthClient.hasPermission in context-factory.ts:

-      // Built-in roles bypass all permission checks
-      if (role && BUILTIN_ROLES.includes(role as ...)) return true;
+      // Only owner/admin bypass all permission checks (full org access).
+      if (role && ADMIN_ROLES.includes(role as ...)) return true;

Plus comment fixes at the three sites that previously implied built-in == bypass (roles.ts, context-factory.ts, auth/index.ts).

Why this is safe

• The other bypass site already excluded user. AccessControl.checkResource (access-control.ts) only ever bypassed admin/owner; its unit tests already model user as enforced. This aligns the second site (createBoundAuthClient) with the first.
• fetchRolePermissions still treats user as built-in (no organizationRole row) → returns undefined → its Better Auth role grant is consulted.
• The Better Auth user role is self: ["*"], and authorize() matches actions literally. That's the documented reason owner/admin must enumerate the full tool list (creatorSelf). So ["*"] authorizes no specific tool → gated tools are denied; only basic-usage (granted separately) remains.
• The UI was already restricted. The MY_CAPABILITIES endpoint already reports all-false capabilities for a user (my-capabilities.spec.ts asserts values.every(v => v === false)), and settings-capability-gating.spec.ts already drives a user as a restricted member. This change makes the server match what the UI already shows.

Testing

• bun run check ✅ · bun run lint ✅ (0/0) · bun run knip ✅ · bun run fmt ✅
• bun test on access-control / mesh-context / define-tool ✅ (53 pass) — these already encode user as enforced.
• Existing e2e specs (my-capabilities, settings-capability-gating, create-scoped-role) already cover the restricted-user behavior end-to-end; they require Postgres+NATS infra to run locally.

No new unit test added: the flip lives in createBoundAuthClient, which depends on the real Better Auth hasPermission (integration territory, already covered by the e2e specs); a mock-only unit test would be brittle per TESTING.md.

Rollout note

This is a real privilege reduction for the user role. Verify in staging that normal members can still chat, view agents/connections, use the home/shell, file picker, and credits banner (all covered by basic-usage) before promoting.

🤖 Generated with Claude Code

---

Summary by cubic

Enforces permission checks for the built-in "user" role and grants agents:manage and connections:manage via USER_ROLE_TOOLS, so members can manage agents and connections but not other gated areas. Only "owner" and "admin" keep the bypass; this closes wildcard leaks and aligns server rules with UI gating.

• Bug Fixes

  • Limit runtime bypass to ADMIN_ROLES (owner/admin); enforce user.
  • Define user with self: [...USER_ROLE_TOOLS] (no "*") and spread memberAc org statements to block native org management.
  • Extend e2e to assert: user gets basic-usage, can’t view monitoring or org-admin endpoints; restricted custom roles can’t manage agents/connections.

• New Features

  • Add USER_ROLE_TOOLS (from USER_ROLE_CAPABILITY_IDS) as the source of truth for gated tools granted to user; both enforcement and MY_CAPABILITIES resolve from it.
  • Set USER_ROLE_CAPABILITY_IDS = ["agents:manage", "connections:manage"]: members can create/manage agents and connections; other gated capabilities remain denied and UI shows Create Agent and Custom Connection.

^{Written for commit 7b23f7c. Summary will update on new commits.}

[github-actions]

🧪 Benchmark

Should we run the Virtual MCP strategy benchmark for this PR?

React with 👍 to run the benchmark.

Reaction	Action
👍	Run quick benchmark (10 & 128 tools)

Benchmark will run on the next push after you react.

[github-actions]

Release Options

Suggested: Minor (2.387.0) — based on feat: prefix

React with an emoji to override the release type:

Reaction	Type	Next Version
👍	Prerelease	2.386.1-alpha.1
🎉	Patch	2.386.1
❤️	Minor	2.387.0
🚀	Major	3.0.0

Current version: 2.386.0

Note: If multiple reactions exist, the smallest bump wins. If no reactions, the suggested bump is used (default: patch).

[cubic-dev-ai]

1 issue found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/src/core/context-factory.ts">

<violation number="1" location="apps/mesh/src/core/context-factory.ts:271">
P1: `user` is still effectively granted wildcard `self` access via the explicit wildcard fallback, so the intended privilege reduction is not fully enforced.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: user is still effectively granted wildcard self access via the explicit wildcard fallback, so the intended privilege reduction is not fully enforced.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/core/context-factory.ts, line 271:

<comment>`user` is still effectively granted wildcard `self` access via the explicit wildcard fallback, so the intended privilege reduction is not fully enforced.</comment>

<file context>
@@ -264,11 +264,11 @@ export function createBoundAuthClient(ctx: AuthContext): BoundAuthClient {
+      // built-in `user` role is enforced like any member: it gets basic-usage
+      // (granted out-of-band in AccessControl) plus its explicit Better Auth /
+      // connection grants, and nothing else. See ADMIN_ROLES in auth/roles.ts.
+      if (role && ADMIN_ROLES.includes(role as (typeof ADMIN_ROLES)[number])) {
         return true;
       }
</file context>