fix(auth): authorize API keys solely by their own allowlist (no owner-role widening)

[viktormarinho]

Summary

Fixes a broken-access-control / privilege-escalation bug (High): an API key whose owner is an org admin/owner silently inherited full org access — the admin/owner role bypass fired before the key's permissions allowlist was ever checked. A "read-only" key minted by an admin could call any tool (API_KEY_CREATE, ORGANIZATION_*, secrets, member mgmt). Found by an agent run and verified in prod (a read-only key minted a new admin-capable key via API_KEY_CREATE).

The model

An API key is authorized solely by its own permissions allowlist. The owner's role never widens it, and there is no membership floor — a key is a capability, not a member. A full-access key carries an explicit wildcard ({ "*": ["*"] } / { self: ["*"] }); a key with no allowlist grants nothing. There is no implicit "default permission" fallback — "a key without a scope" no longer exists.

AccessControl.checkResource dispatches to one of two self-contained codepaths by principal type — so each is simple to reason about in isolation:

• API key → checkApiKeyAccess: the key's allowlist is the entire decision (checkApiKeyPermission). No role, no admin/owner bypass, no basic-usage, no Better Auth.
• member (session / MCP OAuth / mesh JWT) → checkMemberAccess: the existing membership-floor + admin/owner bypass + Better Auth path, unchanged.

The flag lives on boundAuth.isApiKeyPrincipal, so REST (/api/:org/tools/:name) and MCP (/mcp) share one signal; createBoundAuthClient.hasPermission mirrors the same split.

Other changes

• Remove defaultPermissions from the Better Auth apiKey plugin; API_KEY_CREATE now requires permissions.
• Internal minters that relied on the default now pass an explicit scope: per-run agent MCP key (dispatch-run.ts) + dev-link (dev-link-session.ts) act as the user → { "*": ["*"] }; org-fs mount (provisioning.ts) → { self: ["*"] } (which covers its ORG_FS_READ/WRITE checks directly). The <org>_self connection key was already { self: ["*"] }, so self/loopback (Studio Pack, automations) is unaffected.

Because a key is now exactly its allowlist (not allowlist ∪ basic-usage), internal keys carry a wildcard and are unaffected; user-scoped keys are tightened to precisely what they were scoped to. Browser sessions, MCP OAuth, and mesh JWTs are unchanged.

Prod migration

Internal keys are short-TTL (per-run / org-fs) or 30-day (dev-link) → re-mint with explicit scope, no backfill. Existing user keys keep their stored permissions and are enforced against exactly that.

Tests

• apps/mesh/src/auth/api-key-permissions.test.ts — checkApiKeyPermission.
• apps/mesh/src/core/access-control.test.ts + context-factory.bound-auth.test.ts — API-key principal does NOT bypass admin and does NOT get the basic-usage floor; member principal still does; wildcard = full; no-allowlist = deny.
• packages/e2e/tests/apikey-scope-enforcement.spec.ts — black-box HTTP: scoped key → 403 on MONITORING_STATS, API_KEY_CREATE, and a basic-usage tool outside its allowlist; wildcard key keeps access; create without permissions → 400.

tsc + oxlint clean. Unit tests (auth + core) green except the pre-existing DB-gated context-factory.integration.test.ts. Playwright e2e validated by CI.

Related / follow-up

• Complementary: fix(security): prevent privilege escalation via API key permission grants #4119 (creation-time: non-admins can't grant wildcard) — disjoint files, trial-merges clean. The two compose (creation-time + runtime).
• Operational: two keys exposed in the originating thread should be revoked (tracked out-of-band).

🤖 Generated with Claude Code