Multiplayer agent harness for work.
Allow MCP connectors to use per-user credentials (#1189)
Regan Bell31f44cde1fc7
diff --git a/docs/mcp-connectors.md b/docs/mcp-connectors.mdnew file mode 100644index 000000000..54959f144--- /dev/null+++ b/docs/mcp-connectors.md@@ -0,0 +1,57 @@+# MCP connector credentials++Administrators register HTTP MCP servers through `PUT /v1/admin/mcp-servers/:id`.+Registration controls the outbound destination and the tools available to agents.++`credentialScope` selects the identity used for `tools/call`:++- `shared` (the default for existing and new registrations): all callers use the+ configured `auth`, `bearerToken`, or `clientId` and `clientSecret`.+- `per-user`: each call uses the initiating actor's bearer token from the encrypted+ connector keychain, under `credentialHost` in the selected `credentialAccountType`+ slot (`default`, `personal`, or `company`; defaults to `default`). The+ runtime supplies the actor; tool arguments cannot select another user.++For example:++```json+{+ "name": "Customer tools",+ "url": "https://tools.example.com/mcp",+ "auth": "none",+ "credentialScope": "per-user",+ "credentialHost": "accounts.example.com",+ "readOnly": false,+ "enabled": true+}+```++Per-user mode requires persistent keychain encryption (`CONNECTOR_SECRET_KEY`).+Connect the user's account using an existing QM OAuth connector, or have a trusted+integration save its token through the source-authenticated+`POST /v1/connectors/token` endpoint with `host`, `principalId`, `accessToken`, and+optional `expiresAt` (Unix milliseconds). Supported OAuth providers can also store+and refresh a `refreshToken`. This change does not add OAuth provider discovery or+an interactive MCP login flow. An unsupported provider must manage token renewal+in its integration; do not store a refresh token that QM cannot refresh.++Missing, expired, revoked, or unrefreshable user credentials fail the call with a+connection-required message. Per-user MCP calls do not use operator environment+tokens, organization credentials, another user's account, or the shared discovery+credential as fallback. Tokens are resolved again for every call rather than+cached across users. Triggered work uses its existing initiating actor identity.++Tool discovery (`tools/list`, including registration probes) remains connector-wide+and uses the configured `auth`. In per-user mode those credentials are only for+catalog discovery. The server must expose a common, non-sensitive catalog and+check each caller's permissions when executing a tool. A public catalog can use+`auth: "none"`; a private catalog can use a dedicated shared discovery credential.+Do not put user-specific data into names, descriptions, or schemas.++`credentialHost` explicitly authorizes sending that connector's user token to the+registered server. Only register a trusted service permitted to receive those+tokens. Per-user endpoints require HTTPS, except on loopback for local development.+HTTP redirects are rejected for every MCP authentication mode. Updating an endpoint+or credential host is an administrative trust decision. Tool call auditing records+the initiating actor as before; authentication does not expand the audience allowed+to receive the result.diff --git a/src/api/routes/admin/mcp-servers.ts b/src/api/routes/admin/mcp-servers.tsindex 2e8bbf427..a0e76a5aa 100644--- a/src/api/routes/admin/mcp-servers.ts+++ b/src/api/routes/admin/mcp-servers.ts@@ -79,11 +79,45 @@ export async function putMcpServer(ctx: ApiCtx): Promise<void> {return sendJson(ctx.res, 400, { error: "bad_request", message: `auth must be one of ${AUTH_MODES.join(", ")}` });}const existing = await ctx.deps.mcpServers.get(id);+ const credentialScope = b.credentialScope ?? existing?.credentialScope ?? "shared";+ if (credentialScope !== "shared" && credentialScope !== "per-user") {+ return sendJson(ctx.res, 400, { error: "bad_request", message: "credentialScope must be shared or per-user" });+ }+ const credentialHost = b.credentialHost ?? existing?.credentialHost;+ const credentialAccountType = b.credentialAccountType ?? existing?.credentialAccountType ?? "default";+ if (!["default", "personal", "company"].includes(credentialAccountType)) {+ return sendJson(ctx.res, 400, {+ error: "bad_request",+ message: "credentialAccountType must be default, personal, or company",+ });+ }+ if (+ credentialScope === "per-user" &&+ (typeof credentialHost !== "string" ||+ !credentialHost ||+ credentialHost !== credentialHost.trim() ||+ credentialHost.length > 253 ||+ /[\s/\\?#@]/.test(credentialHost))+ ) {+ return sendJson(ctx.res, 400, { error: "bad_request", message: "per-user credentials require a credentialHost" });+ }+ if (+ credentialScope === "per-user" &&+ parsed.protocol !== "https:" &&+ !["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname)+ ) {+ return sendJson(ctx.res, 400, {+ error: "bad_request",+ message: "per-user credentials require HTTPS (except loopback)",+ });+ }const server: McpServer = {id,name: typeof b.name === "string" && b.name.trim() ? b.name.trim().slice(0, 80) : id,url,auth,+ credentialScope,+ ...(credentialScope === "per-user" ? { credentialHost, credentialAccountType } : {}),...(auth === "bearer"? { bearerToken: typeof b.bearerToken === "string" && b.bearerToken ? b.bearerToken : existing?.bearerToken }: {}),diff --git a/src/mcp/mcp-client.ts b/src/mcp/mcp-client.tsindex 85f292b9c..96f178be3 100644--- a/src/mcp/mcp-client.ts+++ b/src/mcp/mcp-client.ts@@ -24,7 +24,7 @@ export type McpFetch = (init: { method: string; headers: Record<string, string>; body: string },) => Promise<McpHttpResponse>;-const realFetch: McpFetch = (url, init) => fetch(url, init);+const realFetch: McpFetch = (url, init) => fetch(url, { ...init, redirect: "error" });function baseUrl(mcpUrl: string): string {return mcpUrl.replace(/\/+$/g, "").replace(/\/mcp$/g, "");diff --git a/src/mcp/mcp-server-store.ts b/src/mcp/mcp-server-store.tsindex 2979ee5fc..ac2dd4de6 100644--- a/src/mcp/mcp-server-store.ts+++ b/src/mcp/mcp-server-store.ts@@ -14,6 +14,9 @@ export interface McpServer {name: string;url: string;auth: McpServerAuthMode;+ credentialScope?: "shared" | "per-user";+ credentialHost?: string;+ credentialAccountType?: "default" | "personal" | "company";bearerToken?: string;clientId?: string;clientSecret?: string;diff --git a/src/mcp/mcp-tool-service.ts b/src/mcp/mcp-tool-service.tsindex ea265a9ed..d76a1a4a1 100644--- a/src/mcp/mcp-tool-service.ts+++ b/src/mcp/mcp-tool-service.ts@@ -6,6 +6,7 @@// namespaced `<serverId>_<toolName>` so two servers can't collide with each// other or with built-in tools.+import type { ConnectorTokenStore } from "../credentials/keychain.ts";import type { AuditLog } from "../audit/audit-log.ts";import { errMessage } from "../util/errors.ts";import { createMcpClient, mcpResultText, type McpAuth, type McpClient, type McpFetch } from "./mcp-client.ts";@@ -47,6 +48,7 @@ function authOf(server: McpServer): McpAuth {export function createMcpToolService(opts: {servers: McpServerStore;audit?: AuditLog;+ userTokens?: Pick<ConnectorTokenStore, "connectorAccessToken">;fetchImpl?: McpFetch;now?: () => number;refreshIntervalMs?: number;@@ -80,6 +82,26 @@ export function createMcpToolService(opts: {return client;}+ async function callerClient(server: McpServer, principalId?: string): Promise<McpClient> {+ if ((server.credentialScope ?? "shared") === "shared") return clientFor(server);+ if (server.credentialScope !== "per-user") throw new Error("invalid MCP credential scope");+ if (!principalId || !server.credentialHost || !opts.userTokens) {+ throw new Error(`MCP server ${server.id} requires a connected user account`);+ }+ const token = await opts.userTokens.connectorAccessToken(+ server.credentialHost,+ principalId,+ server.credentialAccountType,+ );+ if (!token) throw new Error(`Connect your account for MCP server ${server.id} before using this tool`);+ return createMcpClient({+ url: server.url,+ auth: { mode: "bearer", token },+ ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),+ now,+ });+ }+async function refresh(): Promise<void> {const servers = (await opts.servers.list()).filter((s) => s.enabled);const next: McpToolDescriptor[] = [];@@ -123,7 +145,7 @@ export function createMcpToolService(opts: {const server = await opts.servers.get(def.serverId);if (!server || !server.enabled) throw new Error(`MCP server ${def.serverId} is not available`);try {- const result = await clientFor(server).callTool(def.remoteName, args);+ const result = await (await callerClient(server, principalId)).callTool(def.remoteName, args);record("call", `${def.serverId}/${def.remoteName}`, "ok", principalId);const text = mcpResultText(result) || JSON.stringify(result.structuredContent ?? "") || "";return text.length > MAX_RESULT_CHARS ? `${text.slice(0, MAX_RESULT_CHARS)}\n[truncated]` : text;diff --git a/src/wiring.ts b/src/wiring.tsindex 8916aa121..0c42946d0 100644--- a/src/wiring.ts+++ b/src/wiring.ts@@ -752,8 +752,6 @@ export function buildApp(},});const mcpServers = createMcpServerStore(artifactMap<McpServer>("mcp_servers"));- const mcpToolService = createMcpToolService({ servers: mcpServers, audit: auditLog });- const mcpTools = () => mcpToolService.toolDefs();const errors = config.databaseUrl ? createPostgresErrorLog(config.databaseUrl) : createErrorLog();const sandboxOnError = (e: { category: string; code: string; message: string; scopeLabel?: string }) =>errors.record({@@ -1070,6 +1068,12 @@ export function buildApp(// every other personal credential.const userModelCredentials = createUserModelCredentialStore({ keychain: credentialStore });const keychain: Keychain | undefined = keychainKeyMaterial ? credentialStore : undefined;+ const mcpToolService = createMcpToolService({+ servers: mcpServers,+ audit: auditLog,+ ...(keychain ? { userTokens: keychain } : {}),+ });+ const mcpTools = () => mcpToolService.toolDefs();const browserSessionStore: BrowserSessionStore | undefined = keychainKeyMaterial? createBrowserSessionStore({ sessions: artifactMap<StoredBrowserSession>("browser_sessions"), key: credentialKey }): undefined;diff --git a/test/mcp-admin.test.ts b/test/mcp-admin.test.tsnew file mode 100644index 000000000..36c976ebb--- /dev/null+++ b/test/mcp-admin.test.ts@@ -0,0 +1,146 @@+import "./support/auto-fake-sprites.ts";+import { test } from "node:test";+import assert from "node:assert/strict";+import { mkdtemp, rm } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { once } from "node:events";+import { createServer } from "node:http";+import type { AddressInfo } from "node:net";+import { createInsecureTestServer } from "../src/api/server.ts";+import { buildApp } from "../src/wiring.ts";+import { testConfig } from "./support/test-config.ts";+import { createMcpServerStore, type McpServer } from "../src/mcp/mcp-server-store.ts";+import { createMemoryMap } from "../src/persistence/durable-map.ts";++const ADMIN = { "content-type": "application/json", "x-admin-actor": "admin-alice@default-org" };++test("MCP admin validates and preserves credential scope, without returning secrets", async (t) => {+ const dir = await mkdtemp(join(tmpdir(), "mcp-admin-"));+ const built = buildApp(testConfig({ dataDir: dir }));+ const store = createMcpServerStore(createMemoryMap<McpServer>());+ const server = createInsecureTestServer(built.app, {+ admin: built.admin,+ auditLog: built.auditLog,+ mcpServers: store,+ });+ server.listen(0, "127.0.0.1");+ await once(server, "listening");+ t.after(async () => {+ await new Promise<void>((resolve) => server.close(() => resolve()));+ await rm(dir, { recursive: true, force: true });+ });+ const url = `http://127.0.0.1:${(server.address() as AddressInfo).port}/v1/admin/mcp-servers/crm`;+ const put = (body: object, headers = ADMIN) =>+ fetch(url, {+ method: "PUT",+ headers,+ body: JSON.stringify({ url: "https://tools.example.com/mcp", validate: false, ...body }),+ });+ assert.equal((await put({ credentialScope: "other" })).status, 400);+ assert.equal((await put({ credentialScope: "per-user" })).status, 400);+ assert.equal(+ (await put({ credentialScope: "per-user", credentialHost: "accounts.example.com", credentialAccountType: "other" }))+ .status,+ 400,+ );+ for (const credentialHost of ["", " accounts.example.com", "accounts.example.com/path", "host@evil", 1]) {+ assert.equal((await put({ credentialScope: "per-user", credentialHost })).status, 400);+ }+ assert.equal(+ (+ await put({+ credentialScope: "per-user",+ credentialHost: "accounts.example.com",+ url: "http://tools.example.com/mcp",+ })+ ).status,+ 400,+ );+ assert.equal(+ (+ await put(+ { credentialScope: "per-user", credentialHost: "accounts.example.com" },+ { ...ADMIN, "x-admin-actor": "nobody@default-org" },+ )+ ).status,+ 403,+ );+ const saved = await put({+ credentialScope: "per-user",+ credentialHost: "accounts.example.com",+ auth: "bearer",+ bearerToken: "catalog-secret",+ credentialAccountType: "personal",+ });+ assert.equal(saved.status, 200);+ const body = await saved.text();+ assert.doesNotMatch(body, /catalog-secret/);+ assert.equal(JSON.parse(body).server.credentialScope, "per-user");+ assert.equal((await put({ auth: "bearer" })).status, 200);+ assert.equal((await store.get("crm"))?.credentialScope, "per-user");+ assert.equal((await store.get("crm"))?.credentialHost, "accounts.example.com");+ assert.equal((await store.get("crm"))?.credentialAccountType, "personal");+ assert.equal((await store.get("crm"))?.bearerToken, "catalog-secret");+ assert.equal((await put({ credentialScope: "shared" })).status, 200);+ assert.equal((await store.get("crm"))?.credentialScope, "shared");+ assert.equal((await store.get("crm"))?.credentialHost, undefined);+ assert.equal((await store.get("crm"))?.credentialAccountType, undefined);+});++test("production wiring never uses operator fallback tokens for per-user MCP calls", async (t) => {+ const dir = await mkdtemp(join(tmpdir(), "mcp-wiring-"));+ const previous = process.env.VAULT_TOKEN_ACCOUNTS_EXAMPLE_COM;+ process.env.VAULT_TOKEN_ACCOUNTS_EXAMPLE_COM = "operator-token";+ const built = buildApp(testConfig({ dataDir: dir, egressServiceHosts: ["accounts.example.com"] }));+ let calls = 0;+ const remote = createServer(async (req, res) => {+ const chunks: Buffer[] = [];+ for await (const chunk of req) chunks.push(Buffer.from(chunk));+ const rpc = JSON.parse(Buffer.concat(chunks).toString());+ if (rpc.method === "tools/call") calls++;+ res.setHeader("content-type", "application/json");+ res.end(+ JSON.stringify({+ id: rpc.id,+ result:+ rpc.method === "tools/list"+ ? { tools: [{ name: "identity", inputSchema: { type: "object" } }] }+ : { content: [{ type: "text", text: req.headers.authorization }] },+ }),+ );+ });+ remote.listen(0, "127.0.0.1");+ await once(remote, "listening");+ t.after(async () => {+ built.mcpToolService.close();+ await new Promise<void>((resolve) => remote.close(() => resolve()));+ if (previous === undefined) delete process.env.VAULT_TOKEN_ACCOUNTS_EXAMPLE_COM;+ else process.env.VAULT_TOKEN_ACCOUNTS_EXAMPLE_COM = previous;+ await rm(dir, { recursive: true, force: true });+ });+ await built.mcpServers.put({+ id: "crm",+ name: "CRM",+ url: `http://127.0.0.1:${(remote.address() as AddressInfo).port}/mcp`,+ auth: "none",+ credentialScope: "per-user",+ credentialHost: "accounts.example.com",+ readOnly: true,+ enabled: true,+ updatedAt: Date.now(),+ updatedBy: "internal:admin",+ });+ await built.mcpToolService.refresh();+ assert.equal(+ await built.connectorTokens.connectorAccessToken("accounts.example.com", "internal:alice"),+ "operator-token",+ );+ await assert.rejects(built.mcpToolService.call("crm_identity", {}, "internal:alice"), /Connect your account/);+ assert.equal(calls, 0);+ await built.connectorTokens.setConnectorToken("accounts.example.com", "internal:alice", {+ accessToken: "alice-only",+ });+ assert.equal(await built.mcpToolService.call("crm_identity", {}, "internal:alice"), "Bearer alice-only");+ assert.equal(calls, 1);+});diff --git a/test/mcp-connectors.test.ts b/test/mcp-connectors.test.tsindex 2158ed32f..134d37849 100644--- a/test/mcp-connectors.test.ts+++ b/test/mcp-connectors.test.ts@@ -3,6 +3,11 @@ import assert from "node:assert/strict";import { createMcpClient, mcpResultText, type McpFetch } from "../src/mcp/mcp-client.ts";import { createMcpServerStore, isValidMcpServerId, type McpServer } from "../src/mcp/mcp-server-store.ts";import { createMcpToolService } from "../src/mcp/mcp-tool-service.ts";+import { createKeychain, type KeychainCredential } from "../src/credentials/keychain.ts";+import { deriveConnectorKey } from "../src/connectors/connector-client-store.ts";+import { createServer } from "node:http";+import { once } from "node:events";+import type { AddressInfo } from "node:net";import { createMemoryMap } from "../src/persistence/durable-map.ts";function jsonResponse(body: unknown, status = 200, contentType = "application/json") {@@ -124,3 +129,136 @@ test("unknown tool call rejects", async () => {await assert.rejects(() => service.call("nope_tool", {}), /unknown MCP tool/);service.close();});++function tokenStore() {+ return createKeychain({+ creds: createMemoryMap<KeychainCredential>(),+ grants: createMemoryMap(),+ asks: createMemoryMap(),+ key: deriveConnectorKey("mcp-test-encryption-key"),+ });+}++test("per-user calls resolve only the caller's fresh token while discovery uses catalog auth", async (t) => {+ const store = createMcpServerStore(createMemoryMap<McpServer>());+ const users = tokenStore();+ const host = "accounts.example.com";+ await users.setConnectorToken(host, "internal:alice", { accessToken: "alice-token" });+ await users.setConnectorToken(host, "internal:bob", { accessToken: "bob-token" });+ const catalogAuth: string[] = [];+ const callAuth: string[] = [];+ const service = createMcpToolService({+ servers: store,+ userTokens: users,+ fetchImpl: async (_url, init) => {+ const rpc = JSON.parse(init.body);+ if (rpc.method === "tools/list") {+ catalogAuth.push(init.headers.authorization!);+ return jsonResponse({ result: { tools: TOOLS } });+ }+ callAuth.push(init.headers.authorization!);+ return jsonResponse({ result: { content: [{ type: "text", text: rpc.params.arguments.q }] } });+ },+ });+ t.after(() => service.close());+ await store.put(+ server({ auth: "bearer", bearerToken: "catalog-only", credentialScope: "per-user", credentialHost: host }),+ );+ await service.refresh();+ assert.deepEqual(await service.probe((await store.get("crm"))!), ["query", "update"]);+ assert.ok(catalogAuth.length > 0);+ assert.ok(catalogAuth.every((auth) => auth === "Bearer catalog-only"));+ assert.deepEqual(+ await Promise.all([+ service.call("crm_query", { q: "alice" }, "internal:alice"),+ service.call("crm_query", { q: "bob" }, "internal:bob"),+ ]),+ ["alice", "bob"],+ );+ assert.deepEqual(callAuth.sort(), ["Bearer alice-token", "Bearer bob-token"]);+ await users.setConnectorToken(host, "internal:alice", { accessToken: "rotated-alice" });+ await service.call("crm_query", { q: "rotated" }, "internal:alice");+ assert.equal(callAuth.at(-1), "Bearer rotated-alice");+ await users.deleteConnectorToken(host, "internal:alice");+ await assert.rejects(service.call("crm_query", {}, "internal:alice"), /Connect your account/);+ await assert.rejects(service.call("crm_query", {}), /requires a connected user/);+ await assert.rejects(+ service.call("crm_query", { principalId: "internal:bob" }, "internal:mallory"),+ /Connect your account/,+ );+ await users.setConnectorToken(host, "internal:bob", { accessToken: "expired", expiresAt: 1 });+ await assert.rejects(service.call("crm_query", {}, "internal:bob"), /Connect your account/);+ assert.equal(callAuth.length, 3);+});++test("per-user mode fails closed without a keychain and shared mode preserves existing behavior", async (t) => {+ const store = createMcpServerStore(createMemoryMap<McpServer>());+ const { fetch, calls } = fakeServerFetch({ requireBearer: "shared-token" });+ const service = createMcpToolService({ servers: store, fetchImpl: fetch });+ t.after(() => service.close());+ await store.put(+ server({+ auth: "bearer",+ bearerToken: "shared-token",+ credentialScope: "per-user",+ credentialHost: "accounts.example.com",+ }),+ );+ await service.refresh();+ const count = calls.length;+ await assert.rejects(service.call("crm_query", {}, "internal:alice"), /requires a connected user/);+ assert.equal(calls.length, count);+ await store.put(server({ auth: "bearer", bearerToken: "shared-token", credentialScope: "shared" }));+ await service.refresh();+ assert.equal(await service.call("crm_query", {}), "ran query");+});++test("MCP HTTP transport refuses redirects before sending a user token to another endpoint", async (t) => {+ let targetRequests = 0;+ const target = createServer((_req, res) => {+ targetRequests++;+ res.end("{}");+ });+ target.listen(0, "127.0.0.1");+ await once(target, "listening");+ const redirected = createServer((_req, res) => {+ res.writeHead(307, { location: `http://127.0.0.1:${(target.address() as AddressInfo).port}/mcp` });+ res.end();+ });+ redirected.listen(0, "127.0.0.1");+ await once(redirected, "listening");+ t.after(() => {+ target.close();+ redirected.close();+ });+ const client = createMcpClient({+ url: `http://127.0.0.1:${(redirected.address() as AddressInfo).port}`,+ auth: { mode: "bearer", token: "private-user-token" },+ });+ await assert.rejects(client.callTool("query", {}));+ assert.equal(targetRequests, 0);+});++test("per-user connectors select an explicit account slot without falling back to another slot", async (t) => {+ const store = createMcpServerStore(createMemoryMap<McpServer>());+ const users = tokenStore();+ const host = "accounts.example.com";+ await users.setConnectorToken(host, "internal:alice", { accessToken: "default-token" });+ await users.setConnectorToken(host, "internal:alice", { accessToken: "company-token" }, "company");+ const { fetch } = fakeServerFetch({ requireBearer: "company-token" });+ const service = createMcpToolService({ servers: store, userTokens: users, fetchImpl: fetch });+ t.after(() => service.close());+ await store.put(+ server({+ auth: "bearer",+ bearerToken: "company-token",+ credentialScope: "per-user",+ credentialHost: host,+ credentialAccountType: "company",+ }),+ );+ await service.refresh();+ assert.equal(await service.call("crm_query", {}, "internal:alice"), "ran query");+ await users.deleteConnectorToken(host, "internal:alice", "company");+ await assert.rejects(service.call("crm_query", {}, "internal:alice"), /Connect your account/);+});