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

* fix(auth): authorize API keys solely by their own allowlist

A key's owner role no longer widens it: an API key is authorized strictly by its
stored `permissions`. A key an admin scopes to e.g. ORGANIZATION_GET cannot call
any other tool — the privilege escalation reported by an agent run (a read-only
key was minting admin keys via API_KEY_CREATE).

- `AccessControl.checkResource` now dispatches to one of two self-contained
  codepaths by principal type: an **API-key** principal is decided SOLELY by the
  key's allowlist (`checkApiKeyAccess` → `checkApiKeyPermission`) — no role, no
  admin/owner bypass, no basic-usage membership floor, no Better Auth; a
  **member** principal (session / MCP OAuth / mesh JWT) keeps the existing
  membership-floor + role-bypass + Better Auth path (`checkMemberAccess`). The
  flag lives on `boundAuth.isApiKeyPrincipal`, so REST and MCP share one signal.
- `createBoundAuthClient.hasPermission` mirrors the split (API key →
  `checkApiKeyPermission` before any role logic).
- Remove the "default permissions" concept. `API_KEY_CREATE` now requires
  `permissions`, and the three internal minters that relied on the default pass
  an explicit scope: the per-run agent MCP key and the dev-link key act as the
  user (`{ "*": ["*"] }`), the org-fs mount uses `{ self: ["*"] }` (its file ops
  are covered by that scope). "A key without a scope" no longer exists.

A key is therefore exactly its allowlist — not allowlist ∪ basic-usage. Internal
keys carry a wildcard so they are unaffected; user-scoped keys are tightened to
precisely what they were scoped to. Browser sessions, MCP OAuth, and mesh JWTs
are unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(e2e): an API key is capped at its allowlist regardless of owner role

Black-box HTTP regression: an admin-owned key scoped to AUTOMATION_LIST is denied
MONITORING_STATS, API_KEY_CREATE, and a basic-usage tool outside its allowlist
(403) — a key is a capability, not a member. A wildcard key keeps full access;
API_KEY_CREATE without `permissions` is rejected (400).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: viktormarinho

apps/mesh/src/api/routes/decopilot/dispatch-run.ts

@@ -397,6 +397,12 @@ async function mintMcpEndpoint(
 }> {
   const apiKey = await ctx.boundAuth.apiKey.create({
     name: apiKeyName,
+    // The per-run key is the agent's own callback credential — it proxies to
+    // `/mcp/virtual-mcp/<agentId>` (a `vir_*` resource) and acts on behalf of
+    // the user for the duration of the run, so it needs full access. With no
+    // implicit default (auth/index.ts), the scope must be explicit; wildcard
+    // matches the prior behavior (full access via the admin bypass).
+    permissions: { "*": ["*"] },
     expiresIn: MCP_KEY_TTL_SECONDS,
     metadata: {
       organization: {

apps/mesh/src/auth/api-key-permissions.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "bun:test";
+import { checkApiKeyPermission } from "./api-key-permissions";
+
+describe("checkApiKeyPermission", () => {
+  it("grants when the exact (resource, tool) is in the allowlist", () => {
+    expect(
+      checkApiKeyPermission(
+        { self: ["ORGANIZATION_GET"] },
+        { self: ["ORGANIZATION_GET"] },
+      ),
+    ).toBe(true);
+  });
+
+  it("denies a tool outside the allowlist (the escalation we block)", () => {
+    expect(
+      checkApiKeyPermission(
+        { self: ["ORGANIZATION_GET"] },
+        { self: ["API_KEY_CREATE"] },
+      ),
+    ).toBe(false);
+  });
+
+  it("denies when the resource is not granted at all", () => {
+    expect(
+      checkApiKeyPermission(
+        { self: ["ORGANIZATION_GET"] },
+        { conn_123: ["SEND_MESSAGE"] },
+      ),
+    ).toBe(false);
+  });
+
+  it("grants every tool for a resource with a wildcard", () => {
+    expect(checkApiKeyPermission({ self: ["*"] }, { self: ["ANYTHING"] })).toBe(
+      true,
+    );
+  });
+
+  it("honors a wildcard `*` resource granting all tools (full key)", () => {
+    expect(
+      checkApiKeyPermission({ "*": ["*"] }, { conn_9: ["SEND_MESSAGE"] }),
+    ).toBe(true);
+    expect(checkApiKeyPermission({ "*": ["*"] }, { self: ["ANYTHING"] })).toBe(
+      true,
+    );
+  });
+
+  it("denies everything for an empty / absent allowlist (fail-closed)", () => {
+    expect(checkApiKeyPermission({}, { self: ["ORGANIZATION_GET"] })).toBe(
+      false,
+    );
+  });
+
+  it("requires ALL requested tools to be covered", () => {
+    expect(
+      checkApiKeyPermission(
+        { self: ["ORGANIZATION_GET"] },
+        { self: ["ORGANIZATION_GET", "API_KEY_CREATE"] },
+      ),
+    ).toBe(false);
+  });
+});

apps/mesh/src/auth/api-key-permissions.ts

@@ -0,0 +1,58 @@
+/**
+ * API-key authorization.
+ *
+ * An API key is authorized SOLELY by its own stored `permissions` allowlist
+ * ({ resource: [tools] }) — the owner's org role never widens it. A full-access
+ * key carries an explicit wildcard (`{ "*": ["*"] }` or `{ self: ["*"] }`); a
+ * key with no allowlist grants nothing (fail-closed). There is intentionally no
+ * "default permission" fallback: every key is created with an explicit scope
+ * (see API_KEY_CREATE and the internal minters), so "a key without a scope"
+ * does not exist.
+ */
+
+import type { Permission } from "../storage/types";
+
+/**
+ * Does an API key's stored allowlist grant the requested permission?
+ *
+ * Both are `{ resource: [tools] }` maps. Every (resource, tool) in `requested`
+ * must be covered by `granted` — directly, by a per-resource `"*"`, or by a
+ * wildcard `"*"` resource (itself optionally `"*"` for all tools). Returns false
+ * on the first uncovered entry (fail-closed); an empty/absent allowlist grants
+ * nothing.
+ */
+export function checkApiKeyPermission(
+  granted: Permission,
+  requested: Permission,
+): boolean {
+  for (const [resource, tools] of Object.entries(requested)) {
+    const grantedTools = granted[resource];
+
+    if (!grantedTools || grantedTools.length === 0) {
+      // No grant for this resource — fall back to a wildcard `"*"` resource.
+      const wildcardTools = granted["*"];
+      if (!wildcardTools || wildcardTools.length === 0) {
+        return false;
+      }
+      if (wildcardTools.includes("*")) {
+        continue; // wildcard resource grants every tool
+      }
+      const wildcardSet = new Set(wildcardTools);
+      for (const tool of tools) {
+        if (!wildcardSet.has(tool)) return false;
+      }
+      continue;
+    }
+
+    if (grantedTools.includes("*")) {
+      continue; // wildcard grants all tools for this resource
+    }
+
+    const grantedSet = new Set(grantedTools);
+    for (const tool of tools) {
+      if (!grantedSet.has(tool)) return false;
+    }
+  }
+
+  return true;
+}

apps/mesh/src/auth/dev-link-session.ts

@@ -115,6 +115,9 @@ export async function bootstrapDevLinkSession(
       body: {
         name: "dev-link (auto-minted by bun run dev)",
         userId: user.id,
+        // Dev loopback acting as the user — full access. With no implicit
+        // default (auth/index.ts), the scope must be explicit.
+        permissions: { "*": ["*"] },
         // 30 days — re-minted on file deletion, far longer than any
         // single dev session.
         expiresIn: 60 * 60 * 24 * 30,

apps/mesh/src/auth/index.ts

@@ -311,20 +311,10 @@ const plugins = [
       }
       return null;
     },
-    permissions: {
-      defaultPermissions: {
-        self: [
-          "ORGANIZATION_LIST",
-          "ORGANIZATION_GET", // Organization read access
-          "ORGANIZATION_MEMBER_LIST", // Member read access
-          "COLLECTION_CONNECTIONS_LIST",
-          "COLLECTION_CONNECTIONS_GET", // Connection read access
-          "API_KEY_CREATE", // API key creation
-          "API_KEY_LIST", // API key listing (metadata only)
-          // Note: API_KEY_UPDATE and API_KEY_DELETE are not default - users must explicitly request
-        ],
-      },
-    },
+    // No `defaultPermissions`: every key is created with an explicit scope (the
+    // API_KEY_CREATE tool requires `permissions`, and the internal minters pass
+    // their own). A key is authorized solely by its allowlist — see
+    // auth/api-key-permissions.ts. A key with no allowlist grants nothing.
     rateLimit: {
       enabled: false,
     },

apps/mesh/src/core/access-control.test.ts

@@ -143,6 +143,51 @@ describe("AccessControl", () => {
       expect(ac.granted()).toBe(true);
     });
 
+    it("does NOT bypass the admin role for an API-key principal", async () => {
+      // A key scoped to ORGANIZATION_GET is authorized solely by that allowlist —
+      // the owner's admin/owner role must not widen it. The flag lives on
+      // boundAuth, which enforces the key's permissions.
+      const keyBoundAuth = {
+        ...createMockBoundAuth({ self: ["ORGANIZATION_GET"] }),
+        isApiKeyPrincipal: true,
+      } as BoundAuthClient;
+
+      const allowed = new AccessControl(
+        "user_1",
+        "ORGANIZATION_GET",
+        keyBoundAuth,
+        "admin", // owner is an admin — must NOT grant beyond the allowlist
+      );
+      await allowed.check();
+      expect(allowed.granted()).toBe(true);
+
+      const denied = new AccessControl(
+        "user_1",
+        "API_KEY_CREATE", // out of scope — the exact escalation we are blocking
+        keyBoundAuth,
+        "admin",
+      );
+      await expect(denied.check()).rejects.toThrow(ForbiddenError);
+      expect(denied.granted()).toBe(false);
+    });
+
+    it("still bypasses the admin role for a non-API-key principal (session)", async () => {
+      // isApiKeyPrincipal unset (browser session / MCP OAuth) → admin bypass.
+      const boundAuth = {
+        ...createMockBoundAuth({ self: ["ORGANIZATION_GET"] }),
+        isApiKeyPrincipal: false,
+      } as BoundAuthClient;
+
+      const ac = new AccessControl(
+        "user_1",
+        "API_KEY_CREATE",
+        boundAuth,
+        "owner",
+      );
+      await ac.check();
+      expect(ac.granted()).toBe(true);
+    });
+
     it("should check connection-specific permissions", async () => {
       const ac = new AccessControl(
         "user_1",
@@ -229,6 +274,21 @@ describe("AccessControl", () => {
       await expect(ac.check()).rejects.toThrow(ForbiddenError);
       expect(ac.granted()).toBe(false);
     });
+
+    it("does NOT grant basic-usage to an API-key principal (allowlist only)", async () => {
+      // An API key is a capability, not a member — it takes the api-key codepath
+      // and is decided solely by its allowlist, so a basic-usage tool NOT in the
+      // key's scope is denied even though the owner is an admin.
+      const keyBoundAuth = {
+        ...createMockBoundAuth({}), // key grants nothing
+        isApiKeyPrincipal: true,
+      } as BoundAuthClient;
+
+      const ac = new AccessControl("user_1", tool, keyBoundAuth, "admin");
+
+      await expect(ac.check()).rejects.toThrow(ForbiddenError);
+      expect(ac.granted()).toBe(false);
+    });
   });
 
   describe("granted", () => {

apps/mesh/src/core/access-control.ts

@@ -181,51 +181,58 @@ export class AccessControl {
       return false;
     }
 
-    // Basic-usage tools are granted to every authenticated org MEMBER at
-    // runtime, regardless of their role. Resolving them here — instead of
-    // baking them into each role's stored permission — means the set evolves
-    // with a one-line edit to BASIC_USAGE_TOOLS, with no role-backfill
-    // migration.
-    //
-    // Both signals are required and checked explicitly:
-    //   - `userId`: a verified authenticated principal. `boundAuth` is NOT a
-    //     proxy for auth — it's constructed for every request, including
-    //     anonymous ones, so it must never gate this grant.
-    //   - `role`: derived from the caller's membership row in the target org
-    //     (context-factory / resolveOrgFromPath); set only for members. The old
-    //     bake-in model denied non-members implicitly (no role → no stored
-    //     permission), so we keep that boundary explicit here.
+    // Two kinds of principal, each with its OWN self-contained rule:
+    //   - API key   → the key's stored allowlist is the whole decision. It is a
+    //     capability, not a member: no role, no basic-usage, no Better Auth.
+    //   - everyone else (session / MCP OAuth / mesh JWT) → membership floor +
+    //     admin/owner bypass + Better Auth grants.
+    return this.boundAuth?.isApiKeyPrincipal
+      ? this.checkApiKeyAccess(resource)
+      : this.checkMemberAccess(resource);
+  }
+
+  /**
+   * API-key authorization: the key's stored allowlist is the entire decision.
+   * Never inherits the owner's role, basic-usage floor, or any Better Auth
+   * grant — so a "read-only" key minted by an admin can't act beyond its scope.
+   * See auth/api-key-permissions.ts (`checkApiKeyPermission`).
+   */
+  private async checkApiKeyAccess(resource: string): Promise<boolean> {
+    // `isApiKeyPrincipal` is only set on a real bound client, so this is
+    // defensive; the dispatcher already routed non-bound principals away.
+    if (!this.boundAuth) return false;
+    return this.boundAuth.hasPermission({ [this.connectionId]: [resource] });
+  }
+
+  /**
+   * Member authorization (session / MCP OAuth / mesh JWT).
+   *
+   * Basic-usage tools are granted to every authenticated org MEMBER regardless
+   * of role — resolved here, not baked into each role, so the set evolves with
+   * a one-line edit to BASIC_USAGE_TOOLS. Both signals are required: `userId`
+   * (a verified principal — `boundAuth` exists for every request, even
+   * anonymous, so it must not gate this) and `role` (set only for members).
+   * Admin/owner bypass everything; everyone else falls through to the stored /
+   * Better Auth grant.
+   */
+  private async checkMemberAccess(resource: string): Promise<boolean> {
     if (this.userId && this.role && BASIC_USAGE_TOOLS.has(resource)) {
       return true;
     }
-
-    // Admin and owner roles bypass all checks (they have full access)
     if (this.role === "admin" || this.role === "owner") {
       return true;
     }
-
-    // No bound auth client = deny (should not happen in normal flow)
     if (!this.boundAuth) {
       return false;
     }
-
-    // Build permission check - use connectionId as the resource key
-    const permissionToCheck: Record<string, string[]> = {};
-    if (this.connectionId) {
-      permissionToCheck[this.connectionId] = [resource];
-    }
-
-    // Delegate to the bound auth client. When an organizationId is set
-    // (path-resolved org), pass it through so Better Auth uses it instead of
-    // the session's active org. Pass `this.role` too: it is the member's role
-    // for THIS org (constructor + resolveOrgFromPath keep role and
-    // organizationId in lock-step), so boundAuth can resolve built-in roles
-    // in-memory without a Better Auth round-trip. admin/owner already returned
-    // above, so this only accelerates the `user` role; custom roles fall back.
-    return this.boundAuth.hasPermission(permissionToCheck, {
-      organizationId: this.organizationId,
-      role: this.role,
-    });
+    // Pass `this.role` so boundAuth can resolve built-in roles in-memory (no
+    // Better Auth round-trip); admin/owner already returned above, so this only
+    // accelerates the `user` role. `organizationId` (path-resolved org) makes
+    // Better Auth check the right org instead of the session's active one.
+    return this.boundAuth.hasPermission(
+      { [this.connectionId]: [resource] },
+      { organizationId: this.organizationId, role: this.role },
+    );
   }
 
   /**