diff --git a/doc/connections/CONNECTOR-PLAYBOOK.md b/doc/connections/CONNECTOR-PLAYBOOK.md index cabbcdad193..853a75c89fe 100644 --- a/doc/connections/CONNECTOR-PLAYBOOK.md +++ b/doc/connections/CONNECTOR-PLAYBOOK.md @@ -186,7 +186,13 @@ catalog and health work may use a single active grant for that connection and company. An agent caller must use its own grant. Missing, revoked, or ambiguous agent authorizations fail before provider requests; they never fall back to a personal, organization, or connection-owned credential. Renaming or pausing the -connection must preserve the grant and its secret bindings. A later successful +connection must preserve the grant and its secret bindings. OAuth methods +create the agent grant in the callback. Methods without sign-in (`none` or +`api_key`) create it when connect names `subjectAgentId`, with the API key on +that grant; one connection serves exactly one agent, so connecting it for a +second agent is a conflict. Finish never creates agent grants: the grant still +gives no tools until finish or the installs API adds that agent's install. +A later successful catalog refresh clears an earlier connection-health error without new consent. An agent caller denied for lacking its own grant must not change shared health or the catalog, including when that agent has permission to manage the connection. @@ -1683,7 +1689,7 @@ Suggested PR verification block: | `oauthStrategy` | Managed broker strategy. New definitions use `paperclip_cloud_connector`; `paperclip_id_connector` is recognized only to require migration when an old grant expires. The protocols and provider clients are not interchangeable. Only valid for OAuth. | | `connectorProfile` | Managed connector capability/scope profile, required with `oauthStrategy`. | | `capabilityProfile` | User-facing read/write/mode grouping used for method selection. | -| `grantKinds` | Restricts identity to `organization` and/or `user`; omit for flexible methods. | +| `grantKinds` | Restricts identity to `organization`, `user` and/or `agent`; omit for flexible methods. An `agent` method connects for exactly one chosen agent. | | `whenToUse` | One sentence distinguishing this method from alternatives. | | `defaults.serverUrl` | Exact fixed endpoint. For discovery-capable OAuth, omit fixed auth endpoints. | | `defaults.serverUrlTemplate` | HTTPS endpoint with placeholders supplied by declared tenant/extension fields. Mutually exclusive with `serverUrl`. | diff --git a/server/src/__tests__/plugin-connector-agent-grant.test.ts b/server/src/__tests__/plugin-connector-agent-grant.test.ts new file mode 100644 index 00000000000..9f2c32e054a --- /dev/null +++ b/server/src/__tests__/plugin-connector-agent-grant.test.ts @@ -0,0 +1,301 @@ +/** + * A plugin connector method that declares agent grants and has no sign-in step + * (`auth: "none"` or `"api_key"`) must work like any per-agent connector when + * an operator connects it through the real routes: + * - connect for one agent creates that agent's grant (with the API key for + * `api_key`) but exposes no tools; + * - finish with that agent creates the install, and only that agent's + * gateway discovery lists the tools; + * - organization-grant methods keep their default organization grant; + * - a Paperclip Runner session (the run-scoped assigned-tool gateway) lists + * installed plugin-transport tools, like it does for MCP connections. + */ +import { randomUUID } from "node:crypto"; +import { mkdtemp, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { and, eq } from "drizzle-orm"; +import express from "express"; +import request from "supertest"; +import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"; +import { + agents, companies, companyMemberships, connectionGrants, createDb, heartbeatRuns, issues, plugins, toolConnectionInstalls, toolConnections, +} from "@paperclipai/db"; +import { pluginAppSlug, pluginManifestV1Schema, type PaperclipPluginManifestV1 } from "@paperclipai/shared"; +import { toolAccessRoutes } from "../routes/tool-access.js"; +import { errorHandler } from "../middleware/index.js"; +import { createToolGatewayService } from "../services/tool-gateway.js"; +import { buildPaperclipRuntimeMcpServers } from "../services/heartbeat.js"; +import { createAssignedMcpTools } from "../services/native-runtime/assigned-mcp-tools.js"; +import { resolveNativeRuntimeMcpSnapshot } from "../services/native-runtime/runtime-context.js"; +import { setPluginConnectorWorkers } from "../services/plugin-connector-runtime.js"; +import type { PluginWorkerManager } from "../services/plugin-worker-manager.js"; +import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js"; + +const PLUGIN_KEY = "example.agent-grants"; +const NO_SIGN_IN = pluginAppSlug(PLUGIN_KEY, "open"); +const API_KEY = pluginAppSlug(PLUGIN_KEY, "keyed"); +const SHARED = pluginAppSlug(PLUGIN_KEY, "shared"); +const staticTools = { + kind: "static" as const, + list: [ + { name: "lookup", description: "Look up a record.", risk: "read" as const, parametersSchema: { type: "object" } }, + { name: "update_record", description: "Update a record.", risk: "write" as const, parametersSchema: { type: "object" } }, + ], +}; +const app = (slug: string, name: string, method: Record) => ({ + schemaVersion: 1, slug, name, description: `${name} records`, categories: ["developer"], + branding: { logoUrl: "/brands/apps/api-key-generic.svg" }, urlPatterns: [], + methods: [{ transport: "plugin", ownershipModes: ["customer"], whenToUse: "Use it.", guidanceMd: "Connect it.", + riskTier: "S1", tools: staticTools, ...method }], +}); +const manifest = pluginManifestV1Schema.parse({ + id: PLUGIN_KEY, apiVersion: 1, version: "1.0.0", displayName: "Agent grants", description: "Per-agent connectors", + author: "Tests", categories: ["connector"], capabilities: ["connectors.provide"], entrypoints: { worker: "worker.js" }, + apps: [ + app("open", "Open records", { key: "none", auth: "none", grantKinds: ["agent"] }), + app("keyed", "Keyed records", { + key: "api-key", auth: "api_key", grantKinds: ["agent"], + credentialFields: [{ key: "apiKey", label: "API key", type: "password", required: true, placeholder: "key", secret: true }], + }), + app("shared", "Shared records", { key: "none", auth: "none" }), + ], +}) as PaperclipPluginManifestV1; + +const support = await getEmbeddedPostgresTestSupport(); +(support.supported ? describe : describe.skip)("plugin connector with agent grants and no sign-in", () => { + let db: ReturnType; + let temp: Awaited>; + let keyDir: string; + const workerCalls: Array<{ method: string; params: any }> = []; + + beforeAll(async () => { + keyDir = await mkdtemp(join(tmpdir(), "plugin-agent-grant-secrets-")); + vi.stubEnv("PAPERCLIP_SECRETS_MASTER_KEY_FILE", join(keyDir, "key")); + vi.stubEnv("PAPERCLIP_API_URL", "http://127.0.0.1:3100"); + temp = await startEmbeddedPostgresTestDatabase("paperclip-plugin-agent-grant-"); + db = createDb(temp.connectionString); + await db.insert(plugins).values({ pluginKey: PLUGIN_KEY, packageName: `@test/${PLUGIN_KEY}`, version: "1.0.0", manifestJson: manifest, status: "ready" }); + setPluginConnectorWorkers({ + isRunning: () => true, + getWorker: () => ({ status: "running" }), + call: vi.fn(async (_id: string, method: string, params: any) => { + workerCalls.push({ method, params: structuredClone(params) }); + if (method === "executeTool") return { content: `ran ${params.toolName}` }; + throw new Error(`unexpected ${method}`); + }), + } as unknown as PluginWorkerManager); + }, 60_000); + afterAll(async () => { + setPluginConnectorWorkers(null); + await temp?.cleanup(); + vi.unstubAllEnvs(); + if (keyDir) await rm(keyDir, { recursive: true, force: true }); + }); + + async function setup() { + const [company] = await db.insert(companies).values({ name: "Agent grants", issuePrefix: `AG${randomUUID().slice(0, 6).toUpperCase()}` }).returning(); + await db.insert(companyMemberships).values({ companyId: company!.id, principalType: "user", principalId: "board-user", status: "active", membershipRole: "admin" }); + const [agentA, agentB] = await db.insert(agents).values([ + { companyId: company!.id, name: "Owner", role: "engineer", adapterType: "process" }, + { companyId: company!.id, name: "Other", role: "engineer", adapterType: "process" }, + ]).returning(); + const routes = express(); + routes.use(express.json()); + routes.use((req, _res, next) => { + req.actor = { type: "board", userId: "board-user", userName: "Board User", userEmail: null, isInstanceAdmin: true, source: "local_implicit" }; + next(); + }); + routes.use("/api", toolAccessRoutes(db, {})); + routes.use(errorHandler); + const gateway = createToolGatewayService(db, { toolActionSigningSecret: "plugin-agent-grant-signing" }); + const session = async (agentId: string) => { + const [issue] = await db.insert(issues).values({ companyId: company!.id, title: "Use records", assigneeAgentId: agentId }).returning(); + const [run] = await db.insert(heartbeatRuns).values({ companyId: company!.id, agentId, issueId: issue!.id, scopeKind: "issue", + invocationSource: "on_demand", status: "running", responsibleUserId: "board-user", contextSnapshot: { issueId: issue!.id } }).returning(); + runIds.set(agentId, run!.id); + return (await gateway.createSession({ companyId: company!.id, agentId, runId: run!.id, issueId: issue!.id })).token; + }; + const runIds = new Map(); + const tools = async (token: string) => + (await gateway.listToolsForSession(token)).filter((tool) => tool.providerType === "paperclip_plugin_connection"); + const tokenA = await session(agentA!.id); + const tokenB = await session(agentB!.id); + /** The tools a Paperclip Runner run sees: the run-scoped assigned-tool gateway built at run start. */ + const runnerTools = async (agent: typeof agentA) => { + const runId = runIds.get(agent!.id)!; + const snapshot = await resolveNativeRuntimeMcpSnapshot({ db, agent: agent!, runId }); + const servers = await buildPaperclipRuntimeMcpServers({ db, agent: agent!, runId, expectedAssignmentDigest: snapshot.digest }); + if (servers.length === 0) return { definitions: [] as Array<{ name: string }>, search: async () => [] as string[] }; + const assigned = await createAssignedMcpTools({ gateway, companyId: company!.id, + gatewayPublicId: servers[0]!.url.split("/").at(-1)!, bearerToken: servers[0]!.token }); + return { + definitions: assigned.definitions(), + search: async (query: string) => ((await assigned.execute({ tool: "paperclip_search_assigned_tools", arguments: { query } })) as { tools: Array<{ name: string }> }) + .tools.map((tool) => tool.name), + }; + }; + return { company: company!, agentA: agentA!, agentB: agentB!, routes, gateway, tools, runnerTools, tokenA, tokenB }; + } + + async function connectAndFinish(f: Awaited>, body: Record, access: unknown) { + const connected = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`).send(body); + expect(connected.status, JSON.stringify(connected.body)).toBe(201); + // Rule 2: a configured connection alone gives no agent any tool. + expect(await f.tools(f.tokenA)).toEqual([]); + expect(await f.tools(f.tokenB)).toEqual([]); + const connectionId = connected.body.connectionId as string; + const catalogIds = (connected.body.catalog as Array<{ id: string }>).map((entry) => entry.id); + expect(catalogIds).toHaveLength(2); + const finished = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/${connectionId}/finish`) + .send({ enabledCatalogEntryIds: catalogIds, askFirstCatalogEntryIds: [], access }); + expect(finished.status, JSON.stringify(finished.body)).toBe(200); + expect(finished.body.connection).toMatchObject({ status: "active", enabled: true }); + const grants = await db.select().from(connectionGrants).where(eq(connectionGrants.connectionId, connectionId)); + const installs = await db.select().from(toolConnectionInstalls).where(eq(toolConnectionInstalls.connectionId, connectionId)); + return { connectionId, connectBody: connected.body, grants, installs }; + } + + it("gives only the chosen agent the tools of a no-sign-in method", async () => { + const f = await setup(); + const result = await connectAndFinish(f, { galleryKey: NO_SIGN_IN, connectionMethodKey: "none", grantKind: "agent", subjectAgentId: f.agentA.id }, + { agentIds: [f.agentA.id] }); + expect(result.connectBody.connection).toMatchObject({ credentialPolicy: "per_agent" }); + expect(result.grants.map((grant) => ({ kind: grant.kind, subjectAgentId: grant.subjectAgentId, status: grant.status }))) + .toEqual([{ kind: "agent", subjectAgentId: f.agentA.id, status: "active" }]); + expect(result.installs.map((install) => [install.targetType, install.targetId])).toEqual([["agent", f.agentA.id]]); + expect((await f.tools(f.tokenA)).map((tool) => tool.upstreamToolName).sort()).toEqual(["lookup", "update_record"]); + expect(await f.tools(f.tokenB)).toEqual([]); + }); + + it("stores the API key on the chosen agent's grant and serves the tools only to that agent", async () => { + const f = await setup(); + const result = await connectAndFinish(f, { galleryKey: API_KEY, connectionMethodKey: "api-key", grantKind: "agent", subjectAgentId: f.agentA.id, + credentialValues: { "credentials.apiKey": "agent-key-1" } }, { agentIds: [f.agentA.id] }); + expect(result.grants).toHaveLength(1); + expect(result.grants[0]).toMatchObject({ kind: "agent", subjectAgentId: f.agentA.id, status: "active" }); + expect(result.grants[0]!.credentialSecretRefs.map((ref) => ref.configPath)).toEqual(["credentials.apiKey"]); + // The key belongs to the agent's grant, never to a shared connection credential. + expect(result.connectBody.connection.credentialSecretRefs ?? []).toEqual([]); + const toolsA = await f.tools(f.tokenA); + expect(toolsA.map((tool) => tool.upstreamToolName).sort()).toEqual(["lookup", "update_record"]); + expect(await f.tools(f.tokenB)).toEqual([]); + + const lookup = toolsA.find((tool) => tool.upstreamToolName === "lookup")!; + await f.gateway.executeTool({ sessionToken: f.tokenA, tool: lookup.name, parameters: {}, idempotencyKey: randomUUID() }); + expect(workerCalls.filter((call) => call.method === "executeTool").at(-1)!.params.runContext).toMatchObject({ + agentId: f.agentA.id, + connection: { id: result.connectionId, grantId: result.grants[0]!.id, credential: { kind: "api_key", value: "agent-key-1" } }, + }); + }); + + it("refuses a second agent's identity on the same connection and an agent grant without an agent", async () => { + const f = await setup(); + const missing = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none", grantKind: "agent" }); + expect(missing.status).toBe(400); + const connected = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none", grantKind: "agent", subjectAgentId: f.agentA.id }); + expect(connected.status).toBe(201); + const resumed = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none", resumeConnectionId: connected.body.connectionId, grantKind: "agent", subjectAgentId: f.agentB.id }); + expect(resumed.status).toBe(409); + const grants = await db.select().from(connectionGrants).where(and( + eq(connectionGrants.connectionId, connected.body.connectionId), eq(connectionGrants.kind, "agent"))); + expect(grants.map((grant) => grant.subjectAgentId)).toEqual([f.agentA.id]); + }); + + it("resumes an API-key draft for the same agent without asking for the key again", async () => { + const f = await setup(); + const connected = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: API_KEY, connectionMethodKey: "api-key", grantKind: "agent", subjectAgentId: f.agentA.id, + credentialValues: { "credentials.apiKey": "agent-key-2" } }); + expect(connected.status).toBe(201); + const resumed = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: API_KEY, connectionMethodKey: "api-key", resumeConnectionId: connected.body.connectionId }); + expect(resumed.status, JSON.stringify(resumed.body)).toBe(201); + const grants = await db.select().from(connectionGrants).where(eq(connectionGrants.connectionId, connected.body.connectionId)); + expect(grants).toHaveLength(1); + expect(grants[0]).toMatchObject({ kind: "agent", subjectAgentId: f.agentA.id, status: "active" }); + expect(grants[0]!.credentialSecretRefs.map((ref) => ref.configPath)).toEqual(["credentials.apiKey"]); + }); + + it("lets only one of two concurrent resumes claim a grant-less agent draft", async () => { + const f = await setup(); + const connected = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none", grantKind: "agent", subjectAgentId: f.agentA.id }); + expect(connected.status).toBe(201); + const connectionId = connected.body.connectionId as string; + // A draft saved before connect created agent grants has none. + await db.delete(connectionGrants).where(eq(connectionGrants.connectionId, connectionId)); + const resume = (agentId: string) => request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none", resumeConnectionId: connectionId, grantKind: "agent", subjectAgentId: agentId }); + const results = await Promise.all([resume(f.agentA.id), resume(f.agentB.id)]); + expect(results.filter((result) => result.status === 201)).toHaveLength(1); + const active = await db.select().from(connectionGrants).where(and( + eq(connectionGrants.connectionId, connectionId), eq(connectionGrants.status, "active"))); + expect(active).toHaveLength(1); + }); + + it("replaces a dedicated agent's API key on that agent's grant", async () => { + const f = await setup(); + const result = await connectAndFinish(f, { galleryKey: API_KEY, connectionMethodKey: "api-key", grantKind: "agent", subjectAgentId: f.agentA.id, + credentialValues: { "credentials.apiKey": "agent-key-old" } }, { agentIds: [f.agentA.id] }); + const replaced = await request(f.routes).post(`/api/tool-connections/${result.connectionId}/reconnect`) + .send({ credentialValues: { "credentials.apiKey": "agent-key-new" } }); + expect(replaced.status, JSON.stringify(replaced.body)).toBe(200); + const [connection] = await db.select().from(toolConnections).where(eq(toolConnections.id, result.connectionId)); + expect(connection!.credentialSecretRefs).toEqual([]); + const lookup = (await f.tools(f.tokenA)).find((tool) => tool.upstreamToolName === "lookup")!; + await f.gateway.executeTool({ sessionToken: f.tokenA, tool: lookup.name, parameters: {}, idempotencyKey: randomUUID() }); + expect(workerCalls.filter((call) => call.method === "executeTool").at(-1)!.params.runContext.connection.credential) + .toMatchObject({ value: "agent-key-new" }); + }); + + it("does not revive a removed agent identity for a connect that names no agent", async () => { + const f = await setup(); + const result = await connectAndFinish(f, { galleryKey: NO_SIGN_IN, connectionMethodKey: "none", grantKind: "agent", subjectAgentId: f.agentA.id }, + { agentIds: [f.agentA.id] }); + const removed = await request(f.routes).delete(`/api/tool-connections/${result.connectionId}`); + expect(removed.status, JSON.stringify(removed.body)).toBe(200); + const again = await request(f.routes).post(`/api/companies/${f.company.id}/tools/apps/connect`) + .send({ galleryKey: NO_SIGN_IN, connectionMethodKey: "none" }); + expect(again.status).toBe(400); + const active = await db.select().from(connectionGrants).where(and( + eq(connectionGrants.connectionId, result.connectionId), eq(connectionGrants.status, "active"))); + expect(active).toEqual([]); + expect(await f.tools(f.tokenA)).toEqual([]); + }); + + it("keeps the default organization grant for a method without agent grants", async () => { + const f = await setup(); + const result = await connectAndFinish(f, { galleryKey: SHARED, connectionMethodKey: "none" }, "all_agents"); + expect(result.connectBody.connection).toMatchObject({ credentialPolicy: "shared" }); + expect(result.grants.map((grant) => ({ kind: grant.kind, isDefault: grant.isDefault, status: grant.status }))) + .toEqual([{ kind: "organization", isDefault: true, status: "active" }]); + expect((await f.tools(f.tokenA)).map((tool) => tool.upstreamToolName).sort()).toEqual(["lookup", "update_record"]); + expect((await f.tools(f.tokenB)).map((tool) => tool.upstreamToolName).sort()).toEqual(["lookup", "update_record"]); + }); + + it("lists installed plugin-transport tools in a Paperclip Runner session", async () => { + const f = await setup(); + expect((await f.runnerTools(f.agentA)).definitions).toEqual([]); + await connectAndFinish(f, { galleryKey: SHARED, connectionMethodKey: "none" }, { agentIds: [f.agentA.id] }); + const runnerA = await f.runnerTools(f.agentA); + expect(runnerA.definitions).toHaveLength(2); + // Search by the tool's manifest name finds the gateway tool. + expect(await runnerA.search("update_record")).toHaveLength(1); + expect((await f.runnerTools(f.agentB)).definitions).toEqual([]); + }); + + it("keeps plugin-transport tools in a Paperclip Runner session after a stale health error", async () => { + const f = await setup(); + const { connectionId } = await connectAndFinish(f, { galleryKey: SHARED, connectionMethodKey: "none" }, { agentIds: [f.agentA.id] }); + // A health check that ran while the worker was down saved an error; the + // worker is running again, so each call can succeed. + await db.update(toolConnections).set({ healthStatus: "error", healthMessage: "Plugin worker unavailable" }) + .where(eq(toolConnections.id, connectionId)); + expect(await f.tools(f.tokenA)).toHaveLength(2); + expect((await f.runnerTools(f.agentA)).definitions).toHaveLength(2); + }); +}); diff --git a/server/src/services/heartbeat/run-preparation.ts b/server/src/services/heartbeat/run-preparation.ts index 796237196c7..768e4912eb1 100644 --- a/server/src/services/heartbeat/run-preparation.ts +++ b/server/src/services/heartbeat/run-preparation.ts @@ -967,7 +967,7 @@ export async function buildPaperclipRuntimeMcpServers(input: { .filter( (connection) => (connection.transport === "mcp_remote" || - connection.transport === "local_stdio" || isBrowserUseConnection(connection) || restConnectorFor(connection)) && + connection.transport === "local_stdio" || connection.transport === "plugin" || isBrowserUseConnection(connection) || restConnectorFor(connection)) && !allInstalledConnectionIds.has(connection.id), ) .map(({ id, name }) => ({ id, name })) @@ -991,9 +991,15 @@ export async function buildPaperclipRuntimeMcpServers(input: { (connection.config?.sourceTemplateKey === "github" || connection.transportConfig?.sourceTemplateKey === "github")) || connection.credentialPolicy === "per_user" || + // A plugin connection's health mostly reflects its worker, which the + // host restarts; calls fail retryably while it is down. Match the + // gateway, which keeps these tools discoverable. + connection.transport === "plugin" || !isToolConnectionAttentionHealth(connection.healthStatus)) && + // Keep this transport list equal to the native runtime assignment + // digest in native-runtime/runtime-context.ts. (connection.transport === "mcp_remote" || - connection.transport === "local_stdio" || isBrowserUseConnection(connection) || restConnectorFor(connection) || githubBotConnectionIds.has(connection.id) || spekoConnectionIds.has(connection.id)), + connection.transport === "local_stdio" || connection.transport === "plugin" || isBrowserUseConnection(connection) || restConnectorFor(connection) || githubBotConnectionIds.has(connection.id) || spekoConnectionIds.has(connection.id)), ); const assignedConnectionIds = new Set( assignedConnections.map((connection) => connection.id), diff --git a/server/src/services/native-runtime/runtime-context.ts b/server/src/services/native-runtime/runtime-context.ts index 74b22dac3b2..044130f2c96 100644 --- a/server/src/services/native-runtime/runtime-context.ts +++ b/server/src/services/native-runtime/runtime-context.ts @@ -377,8 +377,10 @@ export async function resolveNativeRuntimeMcpSnapshot(input: { db: Db; agent: Pi && connection.enabled && (Boolean(runIdentity?.activeIdentityContextId) && (connection.config?.sourceTemplateKey === "github" || connection.transportConfig?.sourceTemplateKey === "github") || connection.credentialPolicy === "per_user" + || connection.transport === "plugin" || !isToolConnectionAttentionHealth(connection.healthStatus)) - && (["mcp_remote", "local_stdio"].includes(connection.transport) || isBrowserUseConnection(connection) || restConnectorFor(connection) || githubBotConnectionIds.has(connection.id) || spekoConnectionIds.has(connection.id)) + // Keep this transport list equal to buildPaperclipRuntimeMcpServers. + && (["mcp_remote", "local_stdio", "plugin"].includes(connection.transport) || isBrowserUseConnection(connection) || restConnectorFor(connection) || githubBotConnectionIds.has(connection.id) || spekoConnectionIds.has(connection.id)) ).map((connection) => connection.id)); const assignment = { version: 1, diff --git a/server/src/services/tool-access.ts b/server/src/services/tool-access.ts index f08fa43240a..d4b5bbb56d0 100644 --- a/server/src/services/tool-access.ts +++ b/server/src/services/tool-access.ts @@ -29,6 +29,7 @@ import { toApplication } from "./tool-access/applications/projection.js"; import { groupedActions } from "./tool-access/catalog/action-summary.js"; import { createConnectionSetupPolicy, assertSupportedConnection } from "./tool-access/connections/setup-policy.js"; import { createOrganizationGrantStore } from "./tool-access/connections/organization-grant.js"; +import { createAgentGrantStore } from "./tool-access/connections/agent-grant.js"; import { createPersonalConnectionIdentity } from "./tool-access/connections/personal-identity.js"; import { createOAuthStateStore } from "./tool-access/oauth/state.js"; import { createOAuthCatalogCompletion } from "./tool-access/oauth/catalog-completion.js"; @@ -750,6 +751,7 @@ export function toolAccessService( const { resolveInstalledConnectionsForAgent, listConnectionInstalls } = connectionInstalls; const audit = createToolAccessAudit(db); const ensureDefaultOrganizationGrant = createOrganizationGrantStore(db); + const agentGrants = createAgentGrantStore(db); const { mintConnectionTokenForAgent, loadBrokerRunContext } = createConnectionTokenBroker(db, { now, secrets, policySvc, audit, getConnectionRow, ensureDefaultOrganizationGrant }); const profileService = createToolProfileService(db, now); const profileDetails = profileService.getProfile; @@ -2075,8 +2077,28 @@ export function toolAccessService( `${galleryEntry?.name ?? "This app"} supports only ${method.grantKinds.join(" or ")} credentials`, ); } - const dedicatedAgentId = + // OAuth names the agent in its state and the callback writes that agent's + // grant. A curated method without sign-in (`none` or `api_key`) has no + // callback, so connect itself must create the agent's grant. + const createsAgentGrantAtConnect = Boolean( + requestedGrantKind === "agent" && galleryEntry && method && method.auth !== "oauth" && !remoteMcpConnector, + ); + let dedicatedAgentId = requestedGrantKind === "agent" ? (input.subjectAgentId ?? null) : null; + if (createsAgentGrantAtConnect && !dedicatedAgentId) { + // Continuing the same identity (resume or reconnect) without naming the + // agent keeps its one active agent. A fresh connect that only recovered + // an archived row is a new identity decision and must name the agent. + const retainedAgentGrant = retainsIdentity && retainedConnection + ? await agentGrants.activeAgentGrant(companyId, retainedConnection.id) + : null; + dedicatedAgentId = retainedAgentGrant?.subjectAgentId ?? null; + if (!dedicatedAgentId) { + throw badRequest("Choose the agent that uses this connection", { + code: "connection_subject_agent_required", + }); + } + } if (dedicatedAgentId) { const [subjectAgent] = await db .select({ id: agents.id }) @@ -2087,7 +2109,7 @@ export function toolAccessService( .limit(1); if (!subjectAgent) throw badRequest( - "Dedicated GitHub identity requires an agent in this company", + "A dedicated agent identity requires an agent in this company", ); } const credentialSource: ToolConnectionCredentialSource = @@ -2393,8 +2415,22 @@ export function toolAccessService( retainedMethodKey === method?.key && (!remoteMcpConnector || (baseConfig.url === retainedConfig.url && genericAuthKind === retainedConnection.authKind)), ); + // A dedicated agent's API key lives on its grant, not on the connection. + const [retainedAgentGrant] = canRetainCredentialMaterial && createsAgentGrantAtConnect && retainedConnection && dedicatedAgentId + ? await db + .select({ credentialSecretRefs: connectionGrants.credentialSecretRefs }) + .from(connectionGrants) + .where(and( + eq(connectionGrants.companyId, companyId), + eq(connectionGrants.connectionId, retainedConnection.id), + eq(connectionGrants.kind, "agent"), + eq(connectionGrants.subjectAgentId, dedicatedAgentId), + )) + .limit(1) + : []; const retainedCredentialSecretRefs = canRetainCredentialMaterial ? (retainedPersonalIdentity?.grant?.credentialSecretRefs ?? + retainedAgentGrant?.credentialSecretRefs ?? retainedConnection?.credentialSecretRefs ?? []) : []; @@ -2803,6 +2839,19 @@ export function toolAccessService( } else if (dedicatedAgentId) { // Managed OAuth creates the credential-bearing grant in the callback. // Keep the connection free of organization secrets from the outset. + // Without sign-in, the agent's grant is written here, carrying the + // API key when the method has one. The grant alone gives no tools: + // the agent still needs an install of the active connection. + if (createsAgentGrantAtConnect) { + const mutation = await agentGrants.upsertConnectAgentGrant({ + companyId, + connectionId: connectionRow.id, + subjectAgentId: dedicatedAgentId, + credentialSecretRefs, + actor, + }); + if (revivedConnectionPrevious) revivedGrantMutation = mutation; + } } else { const organizationGrant = await ensureDefaultOrganizationGrant( connectionRow, @@ -3783,8 +3832,20 @@ export function toolAccessService( undefined, actor, ); + // A dedicated agent's key lives on its grant, which is what the gateway + // reads for a per-agent connection. Rotate it there. + const agentGrant = connection.credentialPolicy === "per_agent" + ? await agentGrants.activeAgentGrant(companyId, connection.id) + : null; + if (connection.credentialPolicy === "per_agent" && !agentGrant) { + throw conflict("This connection has no agent to update. Connect it again and choose its agent.", { + code: "connection_subject_agent_required", + }); + } + const grantIdentity = Boolean(personalIdentity || agentGrant); const credentialSecretRefs = [ ...(personalIdentity?.grant?.credentialSecretRefs ?? + agentGrant?.credentialSecretRefs ?? connection.credentialSecretRefs), ]; const credentialRefs: McpConnectionCredentialRef[] = [ @@ -3866,13 +3927,19 @@ export function toolAccessService( }); } } + if (agentGrant) { + await tx + .update(connectionGrants) + .set({ credentialSecretRefs, updatedAt }) + .where(eq(connectionGrants.id, agentGrant.id)); + } const [nextConnection] = await tx .update(toolConnections) .set({ credentialRefs, - // Personal reconnect rotates the existing user's grant. The + // Personal and agent reconnects rotate that identity's grant. The // connection-level organization slot stays exactly as it was. - credentialSecretRefs: personalIdentity + credentialSecretRefs: grantIdentity ? connection.credentialSecretRefs : credentialSecretRefs, lastError: null, @@ -3881,7 +3948,7 @@ export function toolAccessService( .where(eq(toolConnections.id, connection.id)) .returning(); await syncConnectionCredentialBindings(tx, nextConnection, - personalIdentity ? credentialSecretRefs : []); + grantIdentity ? credentialSecretRefs : []); return nextConnection; }); const health = await checkConnectionHealth(updated.id, actor); diff --git a/server/src/services/tool-access/connections/agent-grant.ts b/server/src/services/tool-access/connections/agent-grant.ts new file mode 100644 index 00000000000..67e6262a824 --- /dev/null +++ b/server/src/services/tool-access/connections/agent-grant.ts @@ -0,0 +1,112 @@ +import { and, eq } from "drizzle-orm"; +import type { Db } from "@paperclipai/db"; +import { connectionGrants, toolAccessAuditEvents, toolConnections } from "@paperclipai/db"; +import type { CreateToolConnection } from "@paperclipai/shared"; +import { conflict } from "../../../errors.js"; +import { connectionActorUserId } from "../actor.js"; +import type { ActorInfo } from "../types.js"; + +type ConnectionGrant = typeof connectionGrants.$inferSelect; + +/** + * Dedicated-agent identities. A per-agent connection serves exactly one + * agent: its credential lives on that agent's grant, never on the connection. + * OAuth methods write the grant in their callback; methods without sign-in + * write it here when connect names the agent. + */ +export function createAgentGrantStore(db: Db) { + /** Upsert the one active agent grant; a grant for another agent is a conflict. */ + async function upsertConnectAgentGrant(input: { + companyId: string; + connectionId: string; + subjectAgentId: string; + credentialSecretRefs: CreateToolConnection["credentialSecretRefs"]; + actor?: ActorInfo; + }): Promise<{ previous: ConnectionGrant | null; current: ConnectionGrant }> { + return db.transaction(async (tx) => { + // Lock the connection first: with no grant rows yet, locking grants + // alone would let two concurrent connects each add a different agent. + await tx + .select({ id: toolConnections.id }) + .from(toolConnections) + .where(and(eq(toolConnections.id, input.connectionId), eq(toolConnections.companyId, input.companyId))) + .for("update"); + const grants = await tx + .select() + .from(connectionGrants) + .where(and( + eq(connectionGrants.companyId, input.companyId), + eq(connectionGrants.connectionId, input.connectionId), + eq(connectionGrants.kind, "agent"), + )) + .for("update"); + if (grants.some((grant) => grant.status === "active" && grant.subjectAgentId !== input.subjectAgentId)) { + throw conflict( + "This connection already belongs to another agent. Add a separate connection for this agent.", + { code: "connection_agent_identity_in_use" }, + ); + } + const previous = grants.find((grant) => grant.subjectAgentId === input.subjectAgentId) ?? null; + const [current] = previous + ? await tx + .update(connectionGrants) + .set({ + credentialSecretRefs: input.credentialSecretRefs, + status: "active", + revokedAt: null, + revokedByAgentId: null, + revokedByUserId: null, + updatedAt: new Date(), + }) + .where(eq(connectionGrants.id, previous.id)) + .returning() + : await tx + .insert(connectionGrants) + .values({ + companyId: input.companyId, + connectionId: input.connectionId, + kind: "agent", + subjectAgentId: input.subjectAgentId, + credentialSecretRefs: input.credentialSecretRefs, + status: "active", + isDefault: false, + createdByAgentId: input.actor?.actorType === "agent" ? (input.actor.actorId ?? null) : null, + createdByUserId: connectionActorUserId(input.actor), + }) + .returning(); + if (!current) throw new Error("Failed to save the agent connection grant"); + await tx.insert(toolAccessAuditEvents).values({ + companyId: input.companyId, + connectionId: input.connectionId, + actorType: input.actor?.actorType ?? "system", + actorId: input.actor?.actorId ?? null, + action: previous ? "connection_grant.updated" : "connection_grant.created", + outcome: "success", + reasonCode: previous ? "agent_identity_reconnected" : "agent_identity_created", + details: { + kind: "agent", + subjectAgentId: input.subjectAgentId, + credentialSecretRefCount: input.credentialSecretRefs.length, + }, + }); + return { previous, current }; + }); + } + + /** The connection's single active agent grant, or null when there is none or more than one. */ + async function activeAgentGrant(companyId: string, connectionId: string): Promise { + const grants = await db + .select() + .from(connectionGrants) + .where(and( + eq(connectionGrants.companyId, companyId), + eq(connectionGrants.connectionId, connectionId), + eq(connectionGrants.kind, "agent"), + eq(connectionGrants.status, "active"), + )) + .limit(2); + return grants.length === 1 ? grants[0]! : null; + } + + return { upsertConnectAgentGrant, activeAgentGrant }; +} diff --git a/ui/src/features/connections/ConnectionSetupFlow.tsx b/ui/src/features/connections/ConnectionSetupFlow.tsx index 0df8d032037..3df55a4998c 100644 --- a/ui/src/features/connections/ConnectionSetupFlow.tsx +++ b/ui/src/features/connections/ConnectionSetupFlow.tsx @@ -379,7 +379,8 @@ function defaultGrantKindFor(method: ConnectionMethodDef | null, preferPersonal } function defaultInstallChoiceFor(method: ConnectionMethodDef | null, requestedAgentId?: string): "specific" | "all" { - return requestedAgentId || method?.ai?.provider === "github" ? "specific" : "all"; + // A dedicated agent identity belongs to exactly one chosen agent. + return requestedAgentId || method?.ai?.provider === "github" || defaultGrantKindFor(method) === "agent" ? "specific" : "all"; } function configuredAgentIdentity(connection: ToolConnection): string | undefined { @@ -1467,6 +1468,11 @@ function StandardConnectionSetupFlow({ }; const effectiveGrantKind = fixedGrantKind ?? grantKind; + // A dedicated agent identity is never "all agents": keep the picker on so + // the connect request can name its one agent. + useEffect(() => { + if (effectiveGrantKind === "agent" && installChoice !== "specific") setInstallChoice("specific"); + }, [effectiveGrantKind, installChoice]); // A connected result (from the link probe or machine sign-in) goes straight to // review with every discovered action enabled by default. function acceptConnectedResult(result: ConnectToolAppResult) { @@ -1959,7 +1965,7 @@ function StandardConnectionSetupFlow({ // The Access step asks one question about agent reach, so profile access // and installs are committed to the same target set instead of drifting // apart behind two separate wizard screens. - const selection: AppAccessSelection = installChoice === "all" + const selection: AppAccessSelection = installChoice === "all" && effectiveGrantKind !== "agent" ? "all_agents" : { agentIds: Array.from(installAgentIds) }; const finished = await toolsApi.finishApp(selectedCompanyId!, connected.connectionId, { @@ -2223,13 +2229,17 @@ function StandardConnectionSetupFlow({ : "api_key"; // PAP-659 C0: the resolved default is stated, not asked. `Change` opens the // same controls the deleted Access step owned, inline and never blocking. + // Reconnecting a signed-in account keeps its agent; any other dedicated + // agent identity must name exactly one agent before it can connect. + const preservesAgentAccess = Boolean((automaticOAuthEntry && (resumableOAuthConnection || reconnectConnection)) || reconnectConnection?.connectionPurpose === "ai"); + const dedicatedAgentMissing = effectiveGrantKind === "agent" && !requestedAgentId && !preservesAgentAccess && installAgentIds.size !== 1; const renderConnectionDefaults = step === "key" ? ( (extra?: ReactNode, forceOpen?: boolean) => ( <> {entry && instructionTemplate && instructionValue &&
setInstructionDraft({ slug: entry.slug, value })} disabled={connectMutation.isPending || oauthStartMutation.isPending} />
} @@ -2698,7 +2708,7 @@ function StandardConnectionSetupFlow({ ) : step === "key" && entry && credentialStep !== undefined ? credentialStep : step === "key" && entry ? ( agent.id === lockedAgentId)?.name ?? "the requesting agent" : null; - const identityHeading = githubIdentity ? "Connect GitHub as" : "Which humans can use this credential?"; + const identityHeading = githubIdentity + ? "Connect GitHub as" + : allowedGrantKinds.length === 1 && allowedGrantKinds[0] === "agent" + ? "Who this connection acts as" + : "Which humans can use this credential?"; const agentAccessHeading = grantKind === "agent" - ? "Which agent owns this GitHub account?" + ? githubIdentity ? "Which agent owns this GitHub account?" : "Which agent uses this connection?" : githubIdentity && grantKind === "user" ? "Which agents may use your GitHub when you’re responsible?" : githubIdentity @@ -4292,7 +4307,7 @@ export function AccessStepContent({ ]} /> )} - {!preserveAgentAccess && !lockedAgentId && installChoice === "specific" ? ( + {!preserveAgentAccess && !lockedAgentId && (installChoice === "specific" || grantKind === "agent") ? (
{ - const identity = input.authKind === "none" + const identity = input.authKind === "none" && input.grantKind !== "agent" ? "No identity required" : input.grantKind === "user" ? "Your identity" diff --git a/ui/src/pages/apps/AppsConnect.test.tsx b/ui/src/pages/apps/AppsConnect.test.tsx index 47038ea83c8..d0800e4c4ff 100644 --- a/ui/src/pages/apps/AppsConnect.test.tsx +++ b/ui/src/pages/apps/AppsConnect.test.tsx @@ -487,6 +487,48 @@ describe("AppsConnect — Connect with a link (M4 frame)", () => { } }); + it.each([ + { auth: "none" as const, credentialValues: {} }, + { auth: "api_key" as const, credentialValues: { "credentials.apiKey": "records-key" } }, + ])("asks which one agent uses a plugin connector with agent grants ($auth)", async ({ auth, credentialValues }) => { + const app = pluginAppDefinition("example.records", { + schemaVersion: 1, slug: "records", name: "Records", description: "Look up records", categories: ["data"], + branding: { logoUrl: "/brands/apps/api-key-generic.svg" }, urlPatterns: [], + methods: [{ key: "agent", label: "Agent", transport: "plugin", auth, grantKinds: ["agent"], ownershipModes: ["customer"], + whenToUse: "One agent uses it.", guidanceMd: "Pick the agent.", riskTier: "S1", + ...(auth === "api_key" + ? { credentialFields: [{ key: "apiKey", label: "API key", type: "password" as const, required: true, placeholder: "key", secret: true }] } + : {}), + tools: { kind: "static", list: [{ name: "lookup", risk: "read", parametersSchema: { type: "object" } }] } }], + }); + setPluginAppDefinitions([app]); + try { + listGalleryMock.mockResolvedValue({ apps: [app] }); + await render(undefined, false, ); + // The stated default must not promise every agent, and the picker is + // already open because the connection needs its one agent. + expect(container.textContent).not.toContain("available to all agents"); + expect(container.textContent).toContain("Which agent uses this connection?"); + expect(container.textContent).not.toContain("GitHub"); + expect(container.textContent).not.toContain("No identity required"); + expect(buttonByText("Connect")?.disabled).toBe(true); + const key = container.querySelector('input[type="password"]'); + if (auth === "api_key") await act(async () => setInputValue(key!, "records-key")); + await act(async () => buttonByText("Select agents")!.click()); + await flushReact(); + await act(async () => document.body.querySelector('[aria-label="Allow Ada"]')!.click()); + await flushReact(); + expect(container.textContent).toContain("available only to the chosen agent"); + await act(async () => buttonByText("Connect")?.click()); + await flushReact(); + expect(connectAppMock).toHaveBeenCalledWith("company-1", expect.objectContaining({ galleryKey: app.slug, + connectionMethodKey: "agent", grantKind: "agent", subjectAgentId: "agent-1", + ...(auth === "api_key" ? { credentialValues } : {}) })); + } finally { + setPluginAppDefinitions([]); + } + }); + it("opens the saved AI sign-in and reuses a completed account", async () => { mockSearch.value = "aiLogin=saved-login"; const setup = vi.spyOn(aiConnectionsApi, "loginSetup").mockResolvedValue({