mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 02:43:25 +01:00
fix(connectors): activate plugin connectors with agent grants and no sign-in (#22201)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Plugins can now add connector types (#22004) and serve their tools with the `plugin` transport (#22019) > - A plugin connector method can declare `grantKinds: ["agent"]` with `auth: "none"` or `"api_key"` > - Such a connector cannot reach its agent: the connect form cannot name the agent, connect creates no agent grant, and Paperclip Runner runs never list plugin-transport tools > - The product rule is that a plugin connector behaves exactly like any existing connector > - This pull request fixes the connect form, creates the agent grant at connect, and lets runner runs list plugin-transport tools > - The benefit is that an operator can activate a per-agent plugin connector, and only the chosen agent gets its tools ## Linked Issues or Issue Description Refs #22004 Refs #22019 **Subsystem affected** Connectors (connect wizard, tool access service), Paperclip Runner assigned-tool gateway. **Problem or motivation** A plugin connector with agent grants and no sign-in cannot be activated: 1. Connect form: it says "No sign-in needed, available to all agents". "Change" shows "No identity required" and "Which agent owns this GitHub account?", with no agent picker. Connect sends `grantKind: "agent"` without `subjectAgentId`, and the server rejects it with a validation error. The "Finish setup" resume form has the same problem. 2. Grant: connect with `subjectAgentId` saves a `per_agent` connection with zero grants. Finish adds the agent install, but there is still no grant. Only the OAuth callback writes agent grants, and these methods have no OAuth step. For `api_key` methods connect fails, because the health check finds no agent grant, and the key has nowhere to go. 3. Runner: a Paperclip Runner run builds its assigned-tool gateway from an allowlist of transports (`mcp_remote`, `local_stdio`, REST, Browser Use, GitHub bot, voice). `plugin` is not in it, so the run sees no plugin-transport tools, even when the install, profile and grant allow them. **Proposed solution** Create the agent grant at connect for curated methods without sign-in. Add `plugin` to the runner assignment and its digest. Show a one-agent picker with connector-neutral copy. **Expected behavior** Connecting alone grants no tools. Finish with agent A gives only agent A the tools, in gateway discovery and in a runner run. The connection has exactly one active agent grant, for A. ## What Changed - `server/src/services/tool-access.ts`: `connectGalleryApp` writes an active agent grant for `subjectAgentId` when a curated method with `auth` `none` or `api_key` uses `grantKind: "agent"`. The API key goes on that grant, not on the connection. A resume without `subjectAgentId` keeps the agent of the existing grant and keeps its saved key. A second agent on the same connection is a 409 conflict. The grant write is audited and joins the existing revive rollback. - Finish does not create agent grants. Finish carries no credential, and it can list many agents while a per-agent connection has one identity. A credential-less grant would also claim a connected OAuth identity that does not exist. The grant comes from connect (or the OAuth callback). Finish creates only the install. - `server/src/services/heartbeat/run-preparation.ts` and `native-runtime/runtime-context.ts`: include the `plugin` transport in the runner assignment and in its digest (the two lists must match). - `ui/src/features/connections/ConnectionSetupFlow.tsx`: for an agent grant, show the agent picker (exactly one agent), keep the install choice on "specific", open the "Change" panel and disable Connect until one agent is chosen, and send `subjectAgentId`. Copy is neutral ("Which agent uses this connection?"); the GitHub copy stays for GitHub. The summary no longer says "available to all agents" for an agent grant. Finish sends the chosen agent, never `all_agents`, for an agent grant. - `doc/connections/CONNECTOR-PLAYBOOK.md`: document agent grants for methods without sign-in. ## Verification Each new test failed before its fix and passes after it: - `server/src/__tests__/plugin-connector-agent-grant.test.ts` (embedded Postgres, real routes and gateway): - `auth: "none"` + agent grants: after connect, no agent has tools; after finish with agent A, A's discovery lists the tools and B's lists none; exactly one active agent grant, for A. (Red: zero grants.) - `auth: "api_key"` + agent grants: same, the key is on A's grant, and a tool call receives it. (Red: connect returned 422.) - A second agent on the same connection is a 409. (Red: 201.) - Resume of an API-key draft without the key keeps the key on the grant. - Paperclip Runner session: `buildPaperclipRuntimeMcpServers` + `createAssignedMcpTools` list the installed plugin tools for A, and search by the manifest tool name (`update_record`) finds the gateway tool. B gets none. (Red: no tools.) - Regression: an organization-grant method keeps one default organization grant, and both agents get the tools with `all_agents`. - `ui/src/pages/apps/AppsConnect.test.tsx`: for `none` and `api_key` agent-grant plugin methods, the form shows the picker, has no GitHub or "available to all agents" copy, blocks Connect until an agent is chosen, and sends `subjectAgentId`. (Red: "available to all agents" shown.) - Regression suites: `plugin-connectors-plugin-transport`, `plugin-connectors-circleback-parity`, `heartbeat-runtime-mcp-servers`, `run-preparation`, `tool-access-service`, `tool-access-oauth-protocol.integration`, `generic-mcp-connection` (OAuth, GitHub per-agent and organization flows) pass. UI: `src/features/connections`, `src/pages/apps`, `App.deep-link-routing` pass (66 files, 1103 tests). - `tsc --noEmit` passes for `server` and `ui` source. `pnpm check:module-boundaries` passes. ## Risks - Low. The grant change applies only to curated methods with agent grants and no OAuth. Organization, personal and OAuth flows keep their code paths. - The runner change makes plugin-transport tools visible to runner runs. Access still needs an install, a profile and a grant, and every call is re-authorized by the gateway. - Connections created before this fix have no agent grant. Connecting again (or "Finish setup") with the agent creates it. - No migration. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file edits, test runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
a7ea2a799a
commit
adb2bcf896
8 files changed
+573
-20
No files matched your search
@@ -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<string, unknown>) => ({
|
||||
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<typeof createDb>;
|
||||
let temp: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
|
||||
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<string, string>();
|
||||
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<ReturnType<typeof setup>>, body: Record<string, unknown>, 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);
|
||||
});
|
||||
});
|
||||
@@ -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),
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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<ConnectionGrant | null> {
|
||||
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 };
|
||||
}
|
||||
Reference in new issue
Block a user