Unify scoped credential bindings

Move OpenAPI, GraphQL, and MCP credential ownership onto shared scoped credential bindings with explicit write targets.

Add one-shot cloud/local migrations for the cutover, require explicit OAuth token scope, update source/auth UI flows to choose credential target scope, and tighten scoped usage/policy behavior with regression coverage.

Author: RhysSullivan

apps/cloud/drizzle/0009_scoped_credentials_cutover.sql

@@ -64,6 +64,13 @@
       "when": 1778004191000,
       "tag": "0008_normalize_plugin_secret_refs",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1778128200000,
+      "tag": "0009_scoped_credentials_cutover",
+      "breakpoints": true
     }
   ]
 }

apps/cloud/drizzle/meta/0009_snapshot.json

@@ -8,6 +8,8 @@
 
 import { PGlite } from "@electric-sql/pglite";
 import { PGLiteSocketServer } from "@electric-sql/pglite-socket";
+import { execSync } from "node:child_process";
+import { setTimeout as sleep } from "node:timers/promises";
 import { drizzle } from "drizzle-orm/pglite";
 import { migrate } from "drizzle-orm/pglite/migrator";
 import { resolve, dirname } from "node:path";
@@ -18,6 +20,36 @@ const PORT = 5433;
 const DB_PATH = resolve(__dirname, "../.dev-db");
 const MIGRATIONS_FOLDER = resolve(__dirname, "../drizzle");
 
+// Reap any orphan dev-db from a previous `bun dev` that didn't shut down
+// cleanly — otherwise the new instance can't bind to PORT and the app ends
+// up talking to a stale PGlite with the wrong schema.
+function reapStaleDevDb() {
+  const out = execSync(`lsof -ti tcp:${PORT} -sTCP:LISTEN 2>/dev/null || true`, {
+    encoding: "utf8",
+  });
+  const pids = out.trim().split("\n").filter(Boolean);
+  if (pids.length === 0) return false;
+
+  for (const pid of pids) {
+    const cmd = execSync(`ps -p ${pid} -o args= 2>/dev/null || true`, {
+      encoding: "utf8",
+    }).trim();
+    if (!cmd.includes("dev-db.ts")) {
+      console.error(`[dev-db] Port ${PORT} is held by an unexpected process (pid ${pid}): ${cmd}`);
+      console.error(`[dev-db] Refusing to kill it. Free the port and retry.`);
+      process.exit(1);
+    }
+    console.log(`[dev-db] Reaping stale dev-db (pid ${pid})`);
+    execSync(`kill -KILL ${pid}`);
+  }
+  return true;
+}
+
+if (reapStaleDevDb()) {
+  // Give the kernel a beat to release the socket before we try to bind.
+  await sleep(200);
+}
+
 console.log(`[dev-db] Starting PGlite at ${DB_PATH}`);
 const db = await PGlite.create(DB_PATH);
 

apps/cloud/drizzle/meta/_journal.json

@@ -794,7 +794,7 @@ layer(TestEnv, { timeout: 60_000 })("cloud MCP over real HTTP (miniflare)", (it)
         // `HttpApiGroup` name ("approve") becomes part of the sandbox path,
         // so the invocation reads `tools.approveapi.approve.approveThing`.
         const code = [
-          `await tools.openapi.addSource({ spec: ${JSON.stringify(specJson)}, namespace: "approveapi" });`,
+          `await tools.openapi.addSource({ scope: ${JSON.stringify(orgId)}, spec: ${JSON.stringify(specJson)}, namespace: "approveapi" });`,
           `return await tools.approveapi.approve.approveThing({});`,
         ].join("\n");
         const result = yield* Effect.promise(() =>

apps/cloud/scripts/dev-db.ts

@@ -9,6 +9,8 @@ import {
   primaryKey,
 } from "drizzle-orm/pg-core";
 
+export { blobTable as blob } from "@executor-js/storage-postgres";
+
 export const source = pgTable(
   "source",
   {
@@ -134,6 +136,35 @@ export const oauth2_session = pgTable(
   ],
 );
 
+export const credential_binding = pgTable(
+  "credential_binding",
+  {
+    id: text("id").notNull(),
+    scope_id: text("scope_id").notNull(),
+    plugin_id: text("plugin_id").notNull(),
+    source_id: text("source_id").notNull(),
+    source_scope_id: text("source_scope_id").notNull(),
+    slot_key: text("slot_key").notNull(),
+    kind: text("kind").notNull(),
+    text_value: text("text_value"),
+    secret_id: text("secret_id"),
+    connection_id: text("connection_id"),
+    created_at: timestamp("created_at").notNull(),
+    updated_at: timestamp("updated_at").notNull(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.scope_id, table.id] }),
+    index("credential_binding_scope_id_idx").on(table.scope_id),
+    index("credential_binding_plugin_id_idx").on(table.plugin_id),
+    index("credential_binding_source_id_idx").on(table.source_id),
+    index("credential_binding_source_scope_id_idx").on(table.source_scope_id),
+    index("credential_binding_slot_key_idx").on(table.slot_key),
+    index("credential_binding_kind_idx").on(table.kind),
+    index("credential_binding_secret_id_idx").on(table.secret_id),
+    index("credential_binding_connection_id_idx").on(table.connection_id),
+  ],
+);
+
 export const tool_policy = pgTable(
   "tool_policy",
   {
@@ -160,7 +191,6 @@ export const openapi_source = pgTable(
     spec: text("spec").notNull(),
     source_url: text("source_url"),
     base_url: text("base_url"),
-    headers: jsonb("headers"),
     oauth2: jsonb("oauth2"),
   },
   (table) => [
@@ -184,28 +214,22 @@ export const openapi_operation = pgTable(
   ],
 );
 
-export const openapi_source_binding = pgTable(
-  "openapi_source_binding",
+export const openapi_source_header = pgTable(
+  "openapi_source_header",
   {
-    id: text("id").primaryKey(),
+    id: text("id").notNull(),
+    scope_id: text("scope_id").notNull(),
     source_id: text("source_id").notNull(),
-    source_scope_id: text("source_scope_id").notNull(),
-    target_scope_id: text("target_scope_id").notNull(),
-    slot: text("slot").notNull(),
-    kind: text("kind", { enum: ["secret", "connection", "text"] }).notNull(),
-    secret_id: text("secret_id"),
-    connection_id: text("connection_id"),
+    name: text("name").notNull(),
+    kind: text("kind", { enum: ["text", "binding"] }).notNull(),
     text_value: text("text_value"),
-    created_at: timestamp("created_at").notNull(),
-    updated_at: timestamp("updated_at").notNull(),
+    slot_key: text("slot_key"),
+    prefix: text("prefix"),
   },
   (table) => [
-    index("openapi_source_binding_source_id_idx").on(table.source_id),
-    index("openapi_source_binding_source_scope_id_idx").on(table.source_scope_id),
-    index("openapi_source_binding_target_scope_id_idx").on(table.target_scope_id),
-    index("openapi_source_binding_slot_idx").on(table.slot),
-    index("openapi_source_binding_secret_id_idx").on(table.secret_id),
-    index("openapi_source_binding_connection_id_idx").on(table.connection_id),
+    primaryKey({ columns: [table.scope_id, table.id] }),
+    index("openapi_source_header_scope_id_idx").on(table.scope_id),
+    index("openapi_source_header_source_id_idx").on(table.source_id),
   ],
 );
 
@@ -216,16 +240,15 @@ export const openapi_source_query_param = pgTable(
     scope_id: text("scope_id").notNull(),
     source_id: text("source_id").notNull(),
     name: text("name").notNull(),
-    kind: text("kind", { enum: ["text", "secret"] }).notNull(),
+    kind: text("kind", { enum: ["text", "binding"] }).notNull(),
     text_value: text("text_value"),
-    secret_id: text("secret_id"),
-    secret_prefix: text("secret_prefix"),
+    slot_key: text("slot_key"),
+    prefix: text("prefix"),
   },
   (table) => [
     primaryKey({ columns: [table.scope_id, table.id] }),
     index("openapi_source_query_param_scope_id_idx").on(table.scope_id),
     index("openapi_source_query_param_source_id_idx").on(table.source_id),
-    index("openapi_source_query_param_secret_id_idx").on(table.secret_id),
   ],
 );
 
@@ -236,16 +259,15 @@ export const openapi_source_spec_fetch_header = pgTable(
     scope_id: text("scope_id").notNull(),
     source_id: text("source_id").notNull(),
     name: text("name").notNull(),
-    kind: text("kind", { enum: ["text", "secret"] }).notNull(),
+    kind: text("kind", { enum: ["text", "binding"] }).notNull(),
     text_value: text("text_value"),
-    secret_id: text("secret_id"),
-    secret_prefix: text("secret_prefix"),
+    slot_key: text("slot_key"),
+    prefix: text("prefix"),
   },
   (table) => [
     primaryKey({ columns: [table.scope_id, table.id] }),
     index("openapi_source_spec_fetch_header_scope_id_idx").on(table.scope_id),
     index("openapi_source_spec_fetch_header_source_id_idx").on(table.source_id),
-    index("openapi_source_spec_fetch_header_secret_id_idx").on(table.secret_id),
   ],
 );
 
@@ -256,16 +278,15 @@ export const openapi_source_spec_fetch_query_param = pgTable(
     scope_id: text("scope_id").notNull(),
     source_id: text("source_id").notNull(),
     name: text("name").notNull(),
-    kind: text("kind", { enum: ["text", "secret"] }).notNull(),
+    kind: text("kind", { enum: ["text", "binding"] }).notNull(),
     text_value: text("text_value"),
-    secret_id: text("secret_id"),
-    secret_prefix: text("secret_prefix"),
+    slot_key: text("slot_key"),
+    prefix: text("prefix"),
   },
   (table) => [
     primaryKey({ columns: [table.scope_id, table.id] }),
     index("openapi_source_spec_fetch_query_param_scope_id_idx").on(table.scope_id),
     index("openapi_source_spec_fetch_query_param_source_id_idx").on(table.source_id),
-    index("openapi_source_spec_fetch_query_param_secret_id_idx").on(table.secret_id),
   ],
 );
 
@@ -280,20 +301,16 @@ export const mcp_source = pgTable(
       .default("none")
       .notNull(),
     auth_header_name: text("auth_header_name"),
-    auth_secret_id: text("auth_secret_id"),
-    auth_secret_prefix: text("auth_secret_prefix"),
-    auth_connection_id: text("auth_connection_id"),
-    auth_client_id_secret_id: text("auth_client_id_secret_id"),
-    auth_client_secret_secret_id: text("auth_client_secret_secret_id"),
+    auth_header_slot: text("auth_header_slot"),
+    auth_header_prefix: text("auth_header_prefix"),
+    auth_connection_slot: text("auth_connection_slot"),
+    auth_client_id_slot: text("auth_client_id_slot"),
+    auth_client_secret_slot: text("auth_client_secret_slot"),
     created_at: timestamp("created_at").notNull(),
   },
   (table) => [
     primaryKey({ columns: [table.scope_id, table.id] }),
     index("mcp_source_scope_id_idx").on(table.scope_id),
-    index("mcp_source_auth_secret_id_idx").on(table.auth_secret_id),
-    index("mcp_source_auth_connection_id_idx").on(table.auth_connection_id),
-    index("mcp_source_auth_client_id_secret_id_idx").on(table.auth_client_id_secret_id),
-    index("mcp_source_auth_client_secret_secret_id_idx").on(table.auth_client_secret_secret_id),
   ],
 );
 
@@ -304,16 +321,15 @@ export const mcp_source_header = pgTable(
     scope_id: text("scope_id").notNull(),
     source_id: text("source_id").notNull(),
     name: text("name").notNull(),
-    kind: text("kind", { enum: ["text", "secret"] }).notNull(),
+    kind: text("kind", { enum: ["text", "binding"] }).notNull(),
     text_value: text("text_value"),
-    secret_id: text("secret_id"),
-    secret_prefix: text("secret_prefix"),
+    slot_key: text("slot_key"),
+    prefix: text("prefix"),
   },
   (table) => [
     primaryKey({ columns: [table.scope_id, table.id] }),
     index("mcp_source_header_scope_id_idx").on(table.scope_id),
     index("mcp_source_header_source_id_idx").on(table.source_id),
-    index("mcp_source_header_secret_id_idx").on(table.secret_id),
   ],
 );
 
@@ -324,16 +340,15 @@ export const mcp_source_query_param = pgTable(
     scope_id: text("scope_id").notNull(),
     source_id: text("source_id").notNull(),
     name: text("name").notNull(),
-    kind: text("kind", { enum: ["text", "secret"] }).notNull(),
+    kind: text("kind", { enum: ["text", "binding"] }).notNull(),
     text_value: text("text_value"),
-    secret_id: text("secret_id"),
-    secret_prefix: text("secret_prefix"),
+    slot_key: text("slot_key"),
+    prefix: text("prefix"),
   },
   (table) => [
     primaryKey({ columns: [table.scope_id, table.id] }),
     index("mcp_source_query_param_scope_id_idx").on(table.scope_id),
     index("mcp_source_query_param_source_id_idx").on(table.source_id),
-    index("mcp_source_query_param_secret_id_idx").on(table.secret_id),
   ],
 );
 
@@ -363,12 +378,11 @@ export const graphql_source = pgTable(
     auth_kind: text("auth_kind", { enum: ["none", "oauth2"] })
       .default("none")
       .notNull(),
-    auth_connection_id: text("auth_connection_id"),
+    auth_connection_slot: text("auth_connection_slot"),
   },
   (table) => [
     primaryKey({ columns: [table.scope_id, table.id] }),
     index("graphql_source_scope_id_idx").on(table.scope_id),
-    index("graphql_source_auth_connection_id_idx").on(table.auth_connection_id),
   ],
 );
 
@@ -379,16 +393,15 @@ export const graphql_source_header = pgTable(
     scope_id: text("scope_id").notNull(),
     source_id: text("source_id").notNull(),
     name: text("name").notNull(),
-    kind: text("kind", { enum: ["text", "secret"] }).notNull(),
+    kind: text("kind", { enum: ["text", "binding"] }).notNull(),
     text_value: text("text_value"),
-    secret_id: text("secret_id"),
-    secret_prefix: text("secret_prefix"),
+    slot_key: text("slot_key"),
+    prefix: text("prefix"),
   },
   (table) => [
     primaryKey({ columns: [table.scope_id, table.id] }),
     index("graphql_source_header_scope_id_idx").on(table.scope_id),
     index("graphql_source_header_source_id_idx").on(table.source_id),
-    index("graphql_source_header_secret_id_idx").on(table.secret_id),
   ],
 );
 
@@ -399,16 +412,15 @@ export const graphql_source_query_param = pgTable(
     scope_id: text("scope_id").notNull(),
     source_id: text("source_id").notNull(),
     name: text("name").notNull(),
-    kind: text("kind", { enum: ["text", "secret"] }).notNull(),
+    kind: text("kind", { enum: ["text", "binding"] }).notNull(),
     text_value: text("text_value"),
-    secret_id: text("secret_id"),
-    secret_prefix: text("secret_prefix"),
+    slot_key: text("slot_key"),
+    prefix: text("prefix"),
   },
   (table) => [
     primaryKey({ columns: [table.scope_id, table.id] }),
     index("graphql_source_query_param_scope_id_idx").on(table.scope_id),
     index("graphql_source_query_param_source_id_idx").on(table.source_id),
-    index("graphql_source_query_param_secret_id_idx").on(table.secret_id),
   ],
 );
 
@@ -441,13 +453,3 @@ export const workos_vault_metadata = pgTable(
     index("workos_vault_metadata_scope_id_idx").on(table.scope_id),
   ],
 );
-
-export const blob = pgTable(
-  "blob",
-  {
-    namespace: text("namespace").notNull(),
-    key: text("key").notNull(),
-    value: text("value").notNull(),
-  },
-  (table) => [primaryKey({ columns: [table.namespace, table.key] })],
-);

apps/cloud/src/mcp-miniflare.e2e.node.test.ts

@@ -43,10 +43,10 @@ const orgPlugins = (): CloudPlugins =>
 // distinct scope row; future workspace scopes can slot in between without
 // conflicting with a hypothetical global user scope.
 //
-// OAuth tokens land at `ctx.scopes[0]` (the user-org scope) by default, so
-// a member's access/refresh tokens can't leak to other members via
-// `secrets.list`, while source rows and org-wide credentials live on the
-// outer scope.
+// OAuth token writes require an explicit `tokenScope`. User sign-in UI passes
+// the user-org scope so a member's access/refresh tokens cannot leak to other
+// members via `secrets.list`, while source rows and org-wide credentials live
+// on the outer scope.
 // ---------------------------------------------------------------------------
 
 export const createScopedExecutor = (

apps/cloud/src/services/executor-schema.ts

@@ -280,6 +280,7 @@ describe("mcp oauth end-to-end (node pool, real OAuth + MCP server)", () => {
               endpoint: `${fake.url}/mcp`,
               redirectUrl,
               connectionId,
+              tokenScope: String(userScope),
               strategy: { kind: "dynamic-dcr" },
               pluginId: "mcp",
             },
@@ -328,6 +329,7 @@ describe("mcp oauth end-to-end (node pool, real OAuth + MCP server)", () => {
               endpoint,
               redirectUrl,
               connectionId,
+              tokenScope: String(scopeA),
               strategy: { kind: "dynamic-dcr" },
               pluginId: "mcp",
             },
@@ -351,6 +353,7 @@ describe("mcp oauth end-to-end (node pool, real OAuth + MCP server)", () => {
               endpoint,
               redirectUrl,
               connectionId,
+              tokenScope: String(scopeB),
               strategy: { kind: "dynamic-dcr" },
               pluginId: "mcp",
             },