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).

- Remove the "default permissions" concept entirely. `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 come from basic-usage). So "a key without a scope" no longer
  exists.
- `createBoundAuthClient`: an API-key principal (apiKeyId present) is checked via
  `checkApiKeyPermission(permissions, …)` BEFORE the admin/owner role bypass, and
  exposes `isApiKeyPrincipal` on `BoundAuthClient`.
- `AccessControl.checkResource` gates its admin/owner bypass on
  `!boundAuth?.isApiKeyPrincipal`, so REST (`/api/:org/tools`) and MCP (`/mcp`)
  both enforce from one signal.

Browser sessions, MCP OAuth, and mesh JWTs keep the role-based path unchanged.

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",

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

@@ -199,8 +199,17 @@ export class AccessControl {
       return true;
     }
 
-    // Admin and owner roles bypass all checks (they have full access)
-    if (this.role === "admin" || this.role === "owner") {
+    // Admin and owner roles bypass all checks (they have full access) — EXCEPT
+    // for an API-key principal, which is authorized SOLELY by the key's stored
+    // allowlist and must never inherit the owner's role. Otherwise a "read-only"
+    // key minted by an admin could mint admin keys. An API-key principal falls
+    // through to `boundAuth.hasPermission`, which enforces the allowlist. The
+    // flag lives on `boundAuth` so every construction site (REST + MCP) reads
+    // one source; it is unset for sessions / MCP OAuth / mesh JWTs.
+    if (
+      !this.boundAuth?.isApiKeyPrincipal &&
+      (this.role === "admin" || this.role === "owner")
+    ) {
       return true;
     }
 

apps/mesh/src/core/context-factory.bound-auth.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Unit tests for the API-key authorization wired into `createBoundAuthClient`.
+ * These exercise only the in-memory decision branches (API-key allowlist / role
+ * bypass), none of which call Better Auth — so a minimal stubbed `auth` is enough.
+ */
+import { describe, expect, it } from "bun:test";
+import { createBoundAuthClient } from "./context-factory";
+import type { BetterAuthInstance } from "./studio-context";
+
+const stubAuth = { api: {} } as unknown as BetterAuthInstance;
+
+describe("createBoundAuthClient — API-key authorization", () => {
+  it("authorizes an API key SOLELY by its allowlist, ignoring the owner role", async () => {
+    const client = createBoundAuthClient({
+      auth: stubAuth,
+      headers: new Headers(),
+      role: "admin", // owner is an admin — must NOT widen the key
+      permissions: { self: ["ORGANIZATION_GET"] },
+      apiKeyId: "key_1",
+    });
+
+    expect(client.isApiKeyPrincipal).toBe(true);
+    expect(await client.hasPermission({ self: ["ORGANIZATION_GET"] })).toBe(
+      true,
+    );
+    // The exact escalation the report found — denied even for an admin owner.
+    expect(await client.hasPermission({ self: ["API_KEY_CREATE"] })).toBe(
+      false,
+    );
+  });
+
+  it("treats a wildcard key as full access (explicit full key)", async () => {
+    const client = createBoundAuthClient({
+      auth: stubAuth,
+      headers: new Headers(),
+      role: "user",
+      permissions: { "*": ["*"] },
+      apiKeyId: "key_2",
+    });
+
+    expect(client.isApiKeyPrincipal).toBe(true);
+    expect(await client.hasPermission({ self: ["API_KEY_CREATE"] })).toBe(true);
+    expect(await client.hasPermission({ vir_x: ["SEND_MESSAGE"] })).toBe(true);
+  });
+
+  it("denies an API key with no allowlist (fail-closed)", async () => {
+    const client = createBoundAuthClient({
+      auth: stubAuth,
+      headers: new Headers(),
+      role: "owner",
+      permissions: undefined,
+      apiKeyId: "key_3",
+    });
+
+    expect(client.isApiKeyPrincipal).toBe(true);
+    expect(await client.hasPermission({ self: ["ORGANIZATION_GET"] })).toBe(
+      false,
+    );
+  });
+
+  it("keeps the admin/owner role bypass for a non-API-key principal", async () => {
+    const client = createBoundAuthClient({
+      auth: stubAuth,
+      headers: new Headers(),
+      role: "admin",
+      permissions: { self: ["ORGANIZATION_GET"] }, // e.g. a mesh JWT payload
+      // no apiKeyId — not an API key principal
+    });
+
+    expect(client.isApiKeyPrincipal).toBe(false);
+    expect(await client.hasPermission({ self: ["API_KEY_CREATE"] })).toBe(true);
+  });
+});