mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 02:43:25 +01:00
feat(connections): AWS connector with credentials minted per connection (#22195)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents use outside services through connections, and the control plane holds each connection's credentials > - Companies want agents to "do things on AWS" with exactly the permissions they choose, without Paperclip storing long-lived AWS keys or rebuilding the AWS API > - AWS hosts an MCP server that runs any AWS API call in its own sandbox, and it accepts a one-hour bearer token that can be minted from IAM credentials > - This pull request adds an AWS connection that mints that token for each connection at call time. The role method proves the connection with the company's workload identity issuer (#22083), so no AWS key is stored > - The benefit is that each AWS connection carries its own role and permissions, AWS enforces them, and agents never see any AWS credential ## Linked Issues or Issue Description Refs #22083 (workload identity issuer) and #22191 (spike findings). **Subsystem affected** Connections (tool access), tool gateway, shared app definitions, instance settings. **Problem or motivation** Paperclip has no way to connect AWS. AWS's hosted MCP server needs a bearer token from AWS Sign-in, minted from IAM credentials. No existing credential path mints a header at call time from a role or key. **Proposed solution** Methods can declare `credentialMinter: "aws_mcp"`. The gateway and connection health checks mint the `Authorization` header at call time, and they share one in-memory cache per connection and grant (about 55 minutes). There are two methods: - Role (`AssumeRoleWithWebIdentity` with a Paperclip-signed connection token). - Access key (the key directly, `GetFederationToken`, or `AssumeRole`). Read-only connections add `ReadOnlyAccess` and `AWSMCPSignInOAuthAccessPolicy` as session policies, so AWS refuses changes. The feature is behind the `enableAwsConnector` experimental setting. **Alternatives considered** - Run AWS's `mcp-proxy-for-aws` process on the control plane. Rejected: it adds a Python runtime and processes, and gives nothing the token exchange does not. - Put credentials in the agent sandbox and use the AWS CLI. Deferred: there is no per-call governance, and every sandbox would need the CLI. - Add a new `credentialSource`. Rejected: it needs a migration, and the `vercel_connect` database rules do not fit stored access keys. ## What Changed - `packages/shared`: - `credentialMinter` on connection methods. The validator requires `mcp_remote` and `api_key`, and does not allow `keyPlacement` or another credential source. - The `aws` app definition (two methods, reviewed tools, `mcpSessionRequired`, experimental key). - The `enableAwsConnector` setting in the catalog, types and validators. - `aws` added to the connectable apps. - `server/src/services/connectors/aws/mcp-credentials.ts`: - Settings parsing and checks. The URL must be AWS's endpoint for the saved region, and the role ARN must be valid. - The minter: role or key session, read-only session policies, Sign-in exchange, cache keyed on settings, key references and status, in-flight de-duplication, eviction. - A plain-language error mapping that never shows AWS's own text, because that text can contain account IDs and ARNs. - Gateway (`resolveCredentialHeadersUnrecorded`), credential access (`resolveCredentialHeaders`), catalog discovery and health-failure mapping: - The AWS branch. - After a 401, the gateway evicts the token and mints again, then requires an explicit retry (no replay). Discovery lists again. - Setup: - Minted methods may save a draft without contacting the provider. The role must trust a connection that already exists. - Saving an AWS role draft publishes the company's issuer, so AWS can validate it when the customer registers it. - `workload-identity.ts`: a draft connection can get a token, so setup can test it. Disabled, archived or switched-off connections still get none. - `server/package.json`: `@aws-sdk/client-sts` and `@aws-sdk/client-signin`. The lockfile is left to the refresh workflow. - Artwork: AWS light and dark marks from LobeHub's MIT icon set (already licensed in the repo). The manifest entry passes the brand checks. - `scripts/ingest-app-definitions.mjs`: minted methods are exempt from the `keyPlacement` requirement. The override source is `scripts/app-definition-overrides/aws.json`. Permission reviews are added. - UI: the experimental settings toggle, in alphabetical position. - Docs: `doc/connections/AWS.md`, the connections index, the issuer API doc (draft rule), and the plan's phase table. ## Verification - `server/src/services/connectors/aws/mcp-credentials.test.ts` (7 tests) covers these items: - Both methods and the read-only policies. - Caching, revision, forced refresh, expiry and eviction. - Concurrent de-duplication. - The error mapping, with no AWS text leaking. - Settings validation, including the URL and region check and the rule that an unknown access level means read only. - `server/src/__tests__/aws-mcp-connector.test.ts` (3 tests, real setup, catalog and gateway code with a fake AWS and a session-requiring fake MCP server) covers these items: - The setting gates setup. - The access key is never sent as a header or stored in config. - A cached token is reused. - After a 401, a fresh token is minted and the call is not replayed. - Role draft-then-resume publishes the issuer. - The signed token has the right `iss`, `sub` and `aud`. - An AWS refusal shows a plain health message without the account ID. - Red/green: - Removing the gateway hook fails the access-key test. - Turning off `mcpSessionRequired` fails both integration tests. - Removing draft support for minted methods fails both integration tests. - Restoring each change passes again. - Nearby suites: `tool-gateway-service`, `tool-access-service`, `remote-mcp-connectors`, `instance-settings-service`, `workload-identity`, plus the new files. 775 of 775 pass. - Shared `app-definitions.test.ts` passes (42), including new `credentialMinter` schema tests. UI `InstanceExperimentalSettings` (63) and the brand asset tests pass. `check-app-brand-assets` validates 112 identities. - Typecheck is clean for `packages/shared`, `server` and `ui`. The only UI errors are in Storybook's generated catalog files, which this worktree has not built. - **Real AWS** (Paperclip dev account, integrated code path, issuer behind a temporary public tunnel): - Access key, read only: 8 tools listed. `run_script` `ListBuckets` succeeded in 8.9 s on a cold sandbox. AWS refused `CreateBucket` ("no session policy allows"). - Role: the draft was saved without contacting AWS, and the issuer was published. After an IAM provider and a role trusting only that connection were created, resuming setup listed 8 tools. `ListBuckets` succeeded in 12.8 s. The role's own permissions refused `CreateBucket`. - This run found two bugs the fakes did not: AWS needs MCP sessions for calls, and the role method needs draft-first setup with the issuer published. Both are fixed and both now have tests. - All IAM users, keys, roles, providers and buckets were deleted, and a listing confirmed it. - Not run: Paperclip Cloud staging (the setting is off by default), and `AssumeRole` from an access key with a role ARN against real AWS (unit tests only). ## Risks - The feature is off by default, behind `enableAwsConnector`. No migration. - New dependencies `@aws-sdk/client-sts` and `@aws-sdk/client-signin` are in the existing `@aws-sdk` family (the server already uses `client-s3`). - Minted tokens are held only in process memory. A restart mints again. A cached token can outlive a deactivated key by up to an hour, unless AWS returns 401, which evicts it. - `aws___run_script` is classified as a write, so the normal approval and ask-first policy applies. Read-only connections rely on AWS session policies. - The guided setup screen and the CloudFormation template are not in this PR. Setup uses the generic form and the documented draft and resume steps. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, AWS SDK for JavaScript against the Paperclip dev AWS account, a Cloudflare quick tunnel, an exploration subagent). ## 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> Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
36 files changed
+1899
-37
No files matched your search
@@ -0,0 +1,251 @@
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { mkdtemp, rm } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
|
||||
import { eq } from "drizzle-orm";
|
||||
import { agents, companies, companyMemberships, connectionGrants, createDb, toolConnections } from "@paperclipai/db";
|
||||
import { startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
|
||||
import { toolAccessService } from "../services/tool-access.js";
|
||||
import { createToolGatewayService } from "../services/tool-gateway.js";
|
||||
import { instanceSettingsService } from "../services/instance-settings.js";
|
||||
import { AWS_MCP_READ_ONLY_SESSION_POLICIES, type AwsMcpClients } from "../services/connectors/aws/mcp-credentials.js";
|
||||
import { resetWorkloadIdentityKeyCacheForTests, workloadIdentityService } from "../services/workload-identity.js";
|
||||
import { forgetMcpHttpSessions } from "../services/mcp-http.js";
|
||||
|
||||
const actor = { actorType: "user" as const, actorId: "aws-test-user", actorSource: "local_implicit" as const };
|
||||
const ACCESS_KEY_ID = "AKIAEXAMPLE1234567";
|
||||
const SECRET_ACCESS_KEY = "fixture-secret-access-key";
|
||||
const awsTool = (name: string, readOnlyHint: boolean) => ({ name, description: name, inputSchema: { type: "object", properties: {} }, annotations: { readOnlyHint } });
|
||||
|
||||
describe("AWS connector with minted credentials", () => {
|
||||
let fixture: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
|
||||
let db: ReturnType<typeof createDb>;
|
||||
let keyDir: string;
|
||||
|
||||
beforeAll(async () => {
|
||||
keyDir = await mkdtemp(join(tmpdir(), "aws-mcp-connector-"));
|
||||
vi.stubEnv("PAPERCLIP_SECRETS_MASTER_KEY_FILE", join(keyDir, "key"));
|
||||
vi.stubEnv("PAPERCLIP_PUBLIC_URL", "https://acme.paperclip.app");
|
||||
fixture = await startEmbeddedPostgresTestDatabase("aws-mcp-connector-");
|
||||
db = createDb(fixture.connectionString);
|
||||
resetWorkloadIdentityKeyCacheForTests();
|
||||
}, 120_000);
|
||||
afterAll(async () => {
|
||||
await fixture?.cleanup();
|
||||
vi.unstubAllEnvs();
|
||||
if (keyDir) await rm(keyDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
async function company() {
|
||||
const [row] = await db.insert(companies).values({ name: `AWS ${randomUUID()}`, issuePrefix: `A${randomUUID().slice(0, 5)}` }).returning();
|
||||
await db.insert(companyMemberships).values({ companyId: row!.id, principalType: "user", principalId: actor.actorId, status: "active", membershipRole: "admin" });
|
||||
const [agent] = await db.insert(agents).values({ companyId: row!.id, name: "Ops agent", role: "engineer", adapterType: "process", adapterConfig: {}, runtimeConfig: {} }).returning();
|
||||
return { org: row!, agent: agent! };
|
||||
}
|
||||
|
||||
function harness() {
|
||||
let tokens = 0;
|
||||
const session = (label: string) => ({ accessKeyId: `ASIA${label}`, secretAccessKey: "s", sessionToken: "t", expiration: new Date(Date.now() + 3_600_000) });
|
||||
const aws = {
|
||||
assumeRoleWithWebIdentity: vi.fn(async (_input: Parameters<AwsMcpClients["assumeRoleWithWebIdentity"]>[0]) => session("WEB")),
|
||||
assumeRole: vi.fn(async () => session("ROLE")),
|
||||
getFederationToken: vi.fn(async () => session("FED")),
|
||||
createMcpToken: vi.fn(async () => ({ token: `mcp-${++tokens}`, expiresInSeconds: 3599 })),
|
||||
} satisfies AwsMcpClients;
|
||||
const requests: { url: string; method: string; headers: Headers }[] = [];
|
||||
const rejected = new Set<string>();
|
||||
const send = async (url: string, init: RequestInit) => {
|
||||
const body = JSON.parse(String(init.body));
|
||||
const headers = new Headers(init.headers);
|
||||
requests.push({ url, method: body.method, headers });
|
||||
const authorization = headers.get("authorization") ?? "";
|
||||
if (!authorization.startsWith("Bearer mcp-") || rejected.has(authorization)) {
|
||||
return new Response(JSON.stringify({ error: "invalid_token" }), { status: 401 });
|
||||
}
|
||||
if (body.method === "initialize") return Response.json({ id: body.id, jsonrpc: "2.0", result: { protocolVersion: "2025-06-18", capabilities: {} } }, { headers: { "Mcp-Session-Id": `s-${authorization}` } });
|
||||
if (body.method === "notifications/initialized") return new Response(null, { status: 202 });
|
||||
// Like AWS's server: tool calls only work inside an initialized MCP session.
|
||||
if (body.method === "tools/call" && !headers.get("mcp-session-id")) {
|
||||
return Response.json({ id: body.id, jsonrpc: "2.0", error: { code: -32600, message: "Session ID is required for this operation." } });
|
||||
}
|
||||
if (body.method === "tools/list") return Response.json({ id: body.id, jsonrpc: "2.0", result: { tools: [awsTool("aws___run_script", false), awsTool("aws___list_regions", true)] } });
|
||||
return Response.json({ id: body.id, jsonrpc: "2.0", result: { content: [{ type: "text", text: "regions" }] } });
|
||||
};
|
||||
const common = { deploymentMode: "local_trusted" as const, deploymentExposure: "private" as const, remoteHttpEndpointLookup: async () => [{ address: "8.8.8.8", family: 4 as const }], remoteHttpRequest: send, awsMcpClients: aws };
|
||||
return { aws, requests, rejected, service: toolAccessService(db, common), gateway: createToolGatewayService(db, { ...common, toolActionSigningSecret: "fixture-signing-key" }) };
|
||||
}
|
||||
|
||||
it("stays unavailable until the experimental setting is on", async () => {
|
||||
const { org } = await company();
|
||||
const { service } = harness();
|
||||
await instanceSettingsService(db).updateExperimental({ enableAwsConnector: false });
|
||||
await expect(service.connectGalleryApp(org.id, {
|
||||
galleryKey: "aws", connectionMethodKey: "aws-access-key",
|
||||
configValues: { endpointRegion: "us-east-1", accessLevel: "read_only" },
|
||||
credentialValues: { "credentials.accessKeyId": ACCESS_KEY_ID, "credentials.secretAccessKey": SECRET_ACCESS_KEY },
|
||||
}, actor)).rejects.toThrow();
|
||||
});
|
||||
|
||||
it("access key: lists and calls tools with a minted token, never sending the stored key", async () => {
|
||||
await instanceSettingsService(db).updateExperimental({ enableAwsConnector: true });
|
||||
const { org, agent } = await company();
|
||||
const { service, gateway, aws, requests, rejected } = harness();
|
||||
const connected = await service.connectGalleryApp(org.id, {
|
||||
galleryKey: "aws", connectionMethodKey: "aws-access-key",
|
||||
configValues: { endpointRegion: "eu-west-1", accessLevel: "read_only" },
|
||||
credentialValues: { "credentials.accessKeyId": ACCESS_KEY_ID, "credentials.secretAccessKey": SECRET_ACCESS_KEY },
|
||||
}, actor);
|
||||
expect(connected.catalog.map((entry) => entry.toolName).sort()).toEqual(["aws___list_regions", "aws___run_script"]);
|
||||
expect(requests[0]!.url).toBe("https://aws-mcp.eu-west-1.api.aws/mcp");
|
||||
expect(aws.getFederationToken).toHaveBeenCalledWith(expect.objectContaining({
|
||||
region: "eu-west-1", credentials: { accessKeyId: ACCESS_KEY_ID, secretAccessKey: SECRET_ACCESS_KEY },
|
||||
policyArns: AWS_MCP_READ_ONLY_SESSION_POLICIES,
|
||||
}));
|
||||
for (const request of requests) {
|
||||
const sent = JSON.stringify([...request.headers.entries()]);
|
||||
expect(sent).not.toContain(ACCESS_KEY_ID);
|
||||
expect(sent).not.toContain(SECRET_ACCESS_KEY);
|
||||
}
|
||||
const [row] = await db.select().from(toolConnections).where(eq(toolConnections.id, connected.connectionId));
|
||||
expect(JSON.stringify(row!.config)).not.toContain(SECRET_ACCESS_KEY);
|
||||
expect(row!.credentialRefs.filter((ref) => ref.placement === "header")).toEqual([]);
|
||||
|
||||
await service.finishGalleryAppConnection(org.id, connected.connectionId, {
|
||||
enabledCatalogEntryIds: connected.catalog.map((entry) => entry.id), askFirstCatalogEntryIds: [], access: "all_agents",
|
||||
}, actor);
|
||||
const call = () => gateway.executeTestCall({ companyId: org.id, connectionId: connected.connectionId, agentId: agent.id, userId: actor.actorId, toolName: "aws___list_regions", parameters: {} });
|
||||
const mintsAfterSetup = aws.createMcpToken.mock.calls.length;
|
||||
expect(await call()).toMatchObject({ decision: "allowed", result: { data: { isError: false } } });
|
||||
// The first agent call reuses the token minted while setup listed the tools.
|
||||
expect(aws.createMcpToken.mock.calls.length).toBe(mintsAfterSetup);
|
||||
const mintsBefore = aws.createMcpToken.mock.calls.length;
|
||||
expect(await call()).toMatchObject({ decision: "allowed" });
|
||||
expect(aws.createMcpToken.mock.calls.length).toBe(mintsBefore);
|
||||
|
||||
// AWS refuses the cached token: Paperclip mints a fresh one, never replays the call, and the retry works.
|
||||
const lastAuthorization = requests.at(-1)!.headers.get("authorization")!;
|
||||
rejected.add(lastAuthorization);
|
||||
const toolCalls = () => requests.filter((request) => request.method === "tools/call").length;
|
||||
const callsBefore = toolCalls();
|
||||
expect(await call()).toMatchObject({ error: { reasonCode: "credentials_refreshed_retry_required", message: expect.stringContaining("AWS refused the saved credentials") } });
|
||||
expect(toolCalls()).toBe(callsBefore + 1);
|
||||
expect(aws.createMcpToken.mock.calls.length).toBe(mintsBefore + 1);
|
||||
expect(await call()).toMatchObject({ decision: "allowed", result: { data: { isError: false } } });
|
||||
expect(requests.at(-1)!.headers.get("authorization")).not.toBe(lastAuthorization);
|
||||
});
|
||||
|
||||
it("a shared connection never reads a personal grant's keys", async () => {
|
||||
await instanceSettingsService(db).updateExperimental({ enableAwsConnector: true });
|
||||
const { org } = await company();
|
||||
const { service, aws } = harness();
|
||||
const connected = await service.connectGalleryApp(org.id, {
|
||||
galleryKey: "aws", connectionMethodKey: "aws-access-key",
|
||||
configValues: { endpointRegion: "us-east-1", accessLevel: "full" },
|
||||
credentialValues: { "credentials.accessKeyId": ACCESS_KEY_ID, "credentials.secretAccessKey": SECRET_ACCESS_KEY },
|
||||
}, actor);
|
||||
const [organization] = await db.select().from(connectionGrants).where(eq(connectionGrants.connectionId, connected.connectionId));
|
||||
// A leftover personal grant for the same person, with refs that are not the organization's keys.
|
||||
await db.insert(connectionGrants).values({
|
||||
companyId: org.id, connectionId: connected.connectionId, kind: "user", subjectUserId: actor.actorId, status: "active",
|
||||
credentialSecretRefs: [{ secretId: randomUUID(), versionSelector: "latest", configPath: "credentials.accessKeyId" }],
|
||||
});
|
||||
await service.checkHealth(connected.connectionId, actor);
|
||||
expect(aws.createMcpToken).toHaveBeenLastCalledWith(expect.objectContaining({
|
||||
credentials: { accessKeyId: ACCESS_KEY_ID, secretAccessKey: SECRET_ACCESS_KEY },
|
||||
}));
|
||||
expect(organization!.kind).toBe("organization");
|
||||
});
|
||||
|
||||
it("access key: a personal connection reads its owner's keys", async () => {
|
||||
await instanceSettingsService(db).updateExperimental({ enableAwsConnector: true });
|
||||
const { org } = await company();
|
||||
const { service, aws } = harness();
|
||||
const connected = await service.connectGalleryApp(org.id, {
|
||||
galleryKey: "aws", connectionMethodKey: "aws-access-key", grantKind: "user",
|
||||
configValues: { endpointRegion: "us-east-1", accessLevel: "full" },
|
||||
credentialValues: { "credentials.accessKeyId": ACCESS_KEY_ID, "credentials.secretAccessKey": SECRET_ACCESS_KEY },
|
||||
}, actor);
|
||||
expect(connected.catalog).toHaveLength(2);
|
||||
expect(aws.createMcpToken).toHaveBeenCalledWith(expect.objectContaining({
|
||||
credentials: { accessKeyId: ACCESS_KEY_ID, secretAccessKey: SECRET_ACCESS_KEY },
|
||||
}));
|
||||
});
|
||||
|
||||
it("mints a fresh token when AWS refuses the cached one while opening an MCP session", async () => {
|
||||
await instanceSettingsService(db).updateExperimental({ enableAwsConnector: true });
|
||||
const { org, agent } = await company();
|
||||
const { service, gateway, aws, requests, rejected } = harness();
|
||||
const connected = await service.connectGalleryApp(org.id, {
|
||||
galleryKey: "aws", connectionMethodKey: "aws-access-key",
|
||||
configValues: { endpointRegion: "us-east-1", accessLevel: "full" },
|
||||
credentialValues: { "credentials.accessKeyId": ACCESS_KEY_ID, "credentials.secretAccessKey": SECRET_ACCESS_KEY },
|
||||
}, actor);
|
||||
await service.finishGalleryAppConnection(org.id, connected.connectionId, {
|
||||
enabledCatalogEntryIds: connected.catalog.map((entry) => entry.id), askFirstCatalogEntryIds: [], access: "all_agents",
|
||||
}, actor);
|
||||
const call = () => gateway.executeTestCall({ companyId: org.id, connectionId: connected.connectionId, agentId: agent.id, userId: actor.actorId, toolName: "aws___list_regions", parameters: {} });
|
||||
expect(await call()).toMatchObject({ decision: "allowed" });
|
||||
// AWS stops accepting the cached token, and the MCP session is gone, so the next call starts by opening a session.
|
||||
for (const request of requests) rejected.add(request.headers.get("authorization") ?? "");
|
||||
forgetMcpHttpSessions(connected.connectionId);
|
||||
const mintsBefore = aws.createMcpToken.mock.calls.length;
|
||||
const initializesBefore = requests.filter((request) => request.method === "initialize").length;
|
||||
expect(await call()).toMatchObject({ decision: "allowed", result: { data: { isError: false } } });
|
||||
expect(aws.createMcpToken.mock.calls.length).toBe(mintsBefore + 1);
|
||||
expect(requests.filter((request) => request.method === "initialize").length).toBe(initializesBefore + 2);
|
||||
});
|
||||
|
||||
it("role: proves the connection with a Paperclip-signed token and reports AWS refusals plainly", async () => {
|
||||
await instanceSettingsService(db).updateExperimental({ enableAwsConnector: true });
|
||||
const { org } = await company();
|
||||
const { service, aws, requests, rejected } = harness();
|
||||
const roleInput = {
|
||||
galleryKey: "aws", connectionMethodKey: "aws-role",
|
||||
configValues: { roleArn: "arn:aws:iam::123456789012:role/paperclip-agents", endpointRegion: "us-east-1", accessLevel: "full" },
|
||||
};
|
||||
// The role must trust a connection that already exists, so setup saves a draft first without contacting AWS,
|
||||
// and publishes the company's issuer so AWS can validate it when the customer registers it.
|
||||
const draft = await service.connectGalleryApp(org.id, { ...roleInput, saveDraft: true }, actor);
|
||||
expect(draft.catalog).toEqual([]);
|
||||
expect(aws.assumeRoleWithWebIdentity).not.toHaveBeenCalled();
|
||||
expect(await workloadIdentityService(db).publicKeySet(org.id)).not.toBeNull();
|
||||
const connected = await service.connectGalleryApp(org.id, { ...roleInput, resumeConnectionId: draft.connectionId }, actor);
|
||||
expect(connected.connectionId).toBe(draft.connectionId);
|
||||
expect(connected.catalog).toHaveLength(2);
|
||||
const [recorded] = await db.select().from(toolConnections).where(eq(toolConnections.id, connected.connectionId));
|
||||
expect(recorded!.config.workloadIdentityIssuer).toBe(`https://acme.paperclip.app/oidc/companies/${org.id}`);
|
||||
const call = aws.assumeRoleWithWebIdentity.mock.calls[0]![0];
|
||||
expect(call).toMatchObject({ region: "us-east-1", roleArn: "arn:aws:iam::123456789012:role/paperclip-agents", policyArns: undefined });
|
||||
const claims = JSON.parse(Buffer.from(call.webIdentityToken.split(".")[1]!, "base64url").toString("utf8"));
|
||||
expect(claims).toMatchObject({
|
||||
iss: `https://acme.paperclip.app/oidc/companies/${org.id}`,
|
||||
sub: `connection:${connected.connectionId}`,
|
||||
aud: "sts.amazonaws.com",
|
||||
});
|
||||
|
||||
// AWS stops accepting the cached token and the role no longer trusts this connection.
|
||||
for (const request of requests) rejected.add(request.headers.get("authorization") ?? "");
|
||||
aws.assumeRoleWithWebIdentity.mockRejectedValueOnce(Object.assign(new Error("arn:aws:iam::123456789012:role/x is not authorized"), { name: "AccessDenied", $metadata: { httpStatusCode: 403 } }));
|
||||
const health = await service.checkHealth(connected.connectionId, actor).catch((error: unknown) => error);
|
||||
const [row] = await db.select().from(toolConnections).where(eq(toolConnections.id, connected.connectionId));
|
||||
expect(row!.healthMessage ?? JSON.stringify(health)).toContain("AWS refused this connection's role");
|
||||
expect(row!.healthMessage ?? "").not.toContain("123456789012");
|
||||
|
||||
// The instance's address changes: Paperclip stops with a clear message instead of a role refusal from AWS.
|
||||
vi.stubEnv("PAPERCLIP_PUBLIC_URL", "https://renamed.paperclip.app");
|
||||
try {
|
||||
for (const request of requests) rejected.add(request.headers.get("authorization") ?? "");
|
||||
await service.checkHealth(connected.connectionId, actor).catch(() => undefined);
|
||||
const [moved] = await db.select().from(toolConnections).where(eq(toolConnections.id, connected.connectionId));
|
||||
expect(moved!.healthMessage).toContain("address changed");
|
||||
// After the administrator registers the new address in AWS, reconnecting records it and works again.
|
||||
const reconnected = await service.connectGalleryApp(org.id, { ...roleInput, reconnectConnectionId: connected.connectionId }, actor);
|
||||
expect(reconnected.catalog).toHaveLength(2);
|
||||
const [restored] = await db.select().from(toolConnections).where(eq(toolConnections.id, connected.connectionId));
|
||||
expect(restored!.config.workloadIdentityIssuer).toBe(`https://renamed.paperclip.app/oidc/companies/${org.id}`);
|
||||
} finally {
|
||||
vi.stubEnv("PAPERCLIP_PUBLIC_URL", "https://acme.paperclip.app");
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -140,6 +140,7 @@ describe("instance settings service", () => {
|
||||
enableMemoryConnectors: false,
|
||||
enablePaperclipNotebook: false,
|
||||
enableGoogleWorkspaceConnector: false,
|
||||
enableAwsConnector: false,
|
||||
enableConferenceRoomChat: false,
|
||||
enableClassicTaskInterface: false,
|
||||
enableLegacyComposerSubmit: false,
|
||||
|
||||
@@ -74,7 +74,7 @@ describe("company workload identity issuer", () => {
|
||||
return id;
|
||||
}
|
||||
|
||||
async function connection(companyId: string, state: { status?: "draft" | "active" | "disabled"; enabled?: boolean } = {}) {
|
||||
async function connection(companyId: string, state: { status?: "draft" | "active" | "disabled" | "archived"; enabled?: boolean } = {}) {
|
||||
const [application] = await db.insert(toolApplications).values({
|
||||
companyId, applicationKey: `aws-${randomUUID()}`, name: `AWS ${randomUUID().slice(0, 8)}`, type: "mcp_http", status: "active",
|
||||
}).returning();
|
||||
@@ -273,13 +273,16 @@ describe("company workload identity issuer", () => {
|
||||
))).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("stops issuing tokens for a disabled, draft or switched-off connection", async () => {
|
||||
it("stops issuing tokens for a disabled, archived or switched-off connection, but lets setup test a draft", async () => {
|
||||
const companyId = await company();
|
||||
for (const state of [{ status: "disabled" as const }, { status: "draft" as const }, { enabled: false }]) {
|
||||
for (const state of [{ status: "disabled" as const }, { status: "archived" as const }, { enabled: false }]) {
|
||||
const connectionId = await connection(companyId, state);
|
||||
await expect(service().signConnectionToken({ companyId, connectionId, audience: "sts.amazonaws.com" }))
|
||||
.rejects.toMatchObject({ status: 422, details: { code: "workload_identity_connection_inactive" } });
|
||||
}
|
||||
const draft = await connection(companyId, { status: "draft", enabled: false });
|
||||
expect((await service().signConnectionToken({ companyId, connectionId: draft, audience: "sts.amazonaws.com" })).subject)
|
||||
.toBe(`connection:${draft}`);
|
||||
});
|
||||
|
||||
it("writes a rotation's activity entry only when the key change commits", async () => {
|
||||
|
||||
@@ -20,6 +20,7 @@ const CLOUD_STAGING_EXPERIMENTAL_KEYS: ReadonlySet<string> = new Set([
|
||||
"enableFirstTaskPlanProposal",
|
||||
"enableGitHubReviewBots",
|
||||
"enableGoogleWorkspaceConnector",
|
||||
"enableAwsConnector",
|
||||
"enableGoalsSidebarLink",
|
||||
"enableGrokBot",
|
||||
"enableIsolatedWorkspaces",
|
||||
|
||||
@@ -0,0 +1,198 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
AWS_MCP_READ_ONLY_SESSION_POLICIES,
|
||||
AwsMcpCredentialError,
|
||||
awsMcpSettings,
|
||||
awsSessionName,
|
||||
classifyAwsMcpError,
|
||||
createAwsMcpCredentialMinter,
|
||||
isAwsMcpConnection,
|
||||
type AwsMcpClients,
|
||||
type AwsMcpMintInput,
|
||||
type AwsMcpSettings,
|
||||
} from "./mcp-credentials.js";
|
||||
|
||||
function fakeAws(overrides: Partial<AwsMcpClients> = {}) {
|
||||
let tokens = 0;
|
||||
const session = (label: string) => ({ accessKeyId: `ASIA${label}`, secretAccessKey: "secret", sessionToken: "session", expiration: new Date(Date.now() + 3600_000) });
|
||||
const clients = {
|
||||
assumeRoleWithWebIdentity: vi.fn(async () => session("WEB")),
|
||||
assumeRole: vi.fn(async () => session("ROLE")),
|
||||
getFederationToken: vi.fn(async () => session("FED")),
|
||||
createMcpToken: vi.fn(async () => ({ token: `mcp-token-${++tokens}`, expiresInSeconds: 3599 })),
|
||||
...overrides,
|
||||
} satisfies AwsMcpClients;
|
||||
return clients;
|
||||
}
|
||||
|
||||
const roleSettings: AwsMcpSettings = { method: "aws-role", roleArn: "arn:aws:iam::123456789012:role/agents", endpointRegion: "us-east-1", accessLevel: "read_only" };
|
||||
const keySettings: AwsMcpSettings = { method: "aws-access-key", roleArn: null, endpointRegion: "eu-west-1", accessLevel: "read_only" };
|
||||
|
||||
function input(settings: AwsMcpSettings, extra: Partial<AwsMcpMintInput> = {}): AwsMcpMintInput {
|
||||
return {
|
||||
companyId: "company-1", connectionId: "connection-1", connectionName: "AWS Prod", grantId: "grant-1",
|
||||
revision: "r1", settings,
|
||||
readSecret: async (path) => (path === "credentials.accessKeyId" ? "AKIAEXAMPLE" : "stored-secret"),
|
||||
...extra,
|
||||
};
|
||||
}
|
||||
|
||||
describe("AWS MCP credential minter", () => {
|
||||
it("passes the issuer recorded at setup to the signer", async () => {
|
||||
const sign = vi.fn(async () => ({ token: "jwt" }));
|
||||
const minter = createAwsMcpCredentialMinter({ clients: fakeAws(), signConnectionToken: sign });
|
||||
await minter.authorizationHeader(input(roleSettings, { expectedIssuer: "https://a.example/oidc/companies/c" }));
|
||||
expect(sign).toHaveBeenCalledWith(expect.objectContaining({ expectedIssuer: "https://a.example/oidc/companies/c" }));
|
||||
});
|
||||
|
||||
it("role method: signs a connection token for STS and limits read-only sessions", async () => {
|
||||
const clients = fakeAws();
|
||||
const sign = vi.fn(async () => ({ token: "paperclip-jwt" }));
|
||||
const minter = createAwsMcpCredentialMinter({ clients, signConnectionToken: sign });
|
||||
expect(await minter.authorizationHeader(input(roleSettings))).toEqual({ Authorization: "Bearer mcp-token-1" });
|
||||
expect(sign).toHaveBeenCalledWith({ companyId: "company-1", connectionId: "connection-1", audience: "sts.amazonaws.com", expectedIssuer: undefined });
|
||||
expect(clients.assumeRoleWithWebIdentity).toHaveBeenCalledWith({
|
||||
region: "us-east-1", roleArn: roleSettings.roleArn, sessionName: "paperclip-aws-prod",
|
||||
webIdentityToken: "paperclip-jwt", policyArns: AWS_MCP_READ_ONLY_SESSION_POLICIES, signal: expect.any(AbortSignal),
|
||||
});
|
||||
expect(clients.createMcpToken).toHaveBeenCalledWith({ region: "us-east-1", credentials: expect.objectContaining({ accessKeyId: "ASIAWEB" }), signal: expect.any(AbortSignal) });
|
||||
|
||||
await minter.authorizationHeader(input({ ...roleSettings, accessLevel: "full" }, { connectionId: "connection-2" }));
|
||||
expect(clients.assumeRoleWithWebIdentity).toHaveBeenLastCalledWith(expect.objectContaining({ policyArns: undefined }));
|
||||
});
|
||||
|
||||
it("access-key method: federation token for read only, the key itself for full, AssumeRole with a role", async () => {
|
||||
const clients = fakeAws();
|
||||
const sign = vi.fn();
|
||||
const minter = createAwsMcpCredentialMinter({ clients, signConnectionToken: sign });
|
||||
await minter.authorizationHeader(input(keySettings));
|
||||
expect(clients.getFederationToken).toHaveBeenCalledWith({
|
||||
region: "eu-west-1", credentials: { accessKeyId: "AKIAEXAMPLE", secretAccessKey: "stored-secret" },
|
||||
name: "paperclip-aws-prod", policyArns: AWS_MCP_READ_ONLY_SESSION_POLICIES, signal: expect.any(AbortSignal),
|
||||
});
|
||||
expect(clients.createMcpToken).toHaveBeenLastCalledWith({ region: "eu-west-1", credentials: expect.objectContaining({ accessKeyId: "ASIAFED" }), signal: expect.any(AbortSignal) });
|
||||
|
||||
await minter.authorizationHeader(input({ ...keySettings, accessLevel: "full" }, { connectionId: "c-full" }));
|
||||
expect(clients.createMcpToken).toHaveBeenLastCalledWith({ region: "eu-west-1", credentials: { accessKeyId: "AKIAEXAMPLE", secretAccessKey: "stored-secret" }, signal: expect.any(AbortSignal) });
|
||||
|
||||
await minter.authorizationHeader(input({ ...keySettings, roleArn: "arn:aws:iam::123456789012:role/x" }, { connectionId: "c-role" }));
|
||||
expect(clients.assumeRole).toHaveBeenCalledWith(expect.objectContaining({
|
||||
roleArn: "arn:aws:iam::123456789012:role/x", policyArns: AWS_MCP_READ_ONLY_SESSION_POLICIES,
|
||||
}));
|
||||
expect(sign).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("caches per connection and grant, and mints again on edit, forced refresh, expiry or eviction", async () => {
|
||||
let clock = Date.now();
|
||||
const clients = fakeAws();
|
||||
const minter = createAwsMcpCredentialMinter({ clients, signConnectionToken: async () => ({ token: "jwt" }), now: () => clock });
|
||||
const header = () => minter.authorizationHeader(input(roleSettings)).then((h) => h.Authorization);
|
||||
expect(await header()).toBe("Bearer mcp-token-1");
|
||||
expect(await header()).toBe("Bearer mcp-token-1");
|
||||
expect(clients.createMcpToken).toHaveBeenCalledTimes(1);
|
||||
|
||||
expect((await minter.authorizationHeader(input(roleSettings, { revision: "r2" }))).Authorization).toBe("Bearer mcp-token-2");
|
||||
expect((await minter.authorizationHeader(input(roleSettings, { revision: "r2", forceRefresh: true }))).Authorization).toBe("Bearer mcp-token-3");
|
||||
|
||||
clock += 56 * 60 * 1000; // past the 55-minute refresh point
|
||||
expect((await minter.authorizationHeader(input(roleSettings, { revision: "r2" }))).Authorization).toBe("Bearer mcp-token-4");
|
||||
|
||||
minter.evict("company-1", "connection-1");
|
||||
expect((await minter.authorizationHeader(input(roleSettings, { revision: "r2" }))).Authorization).toBe("Bearer mcp-token-5");
|
||||
expect((await minter.authorizationHeader(input(roleSettings, { grantId: "grant-2", revision: "r2" }))).Authorization).toBe("Bearer mcp-token-6");
|
||||
});
|
||||
|
||||
it("keeps only live tokens: an expired token is pruned when the next one is stored", async () => {
|
||||
let clock = Date.now();
|
||||
const minter = createAwsMcpCredentialMinter({ clients: fakeAws(), signConnectionToken: async () => ({ token: "jwt" }), now: () => clock });
|
||||
await minter.authorizationHeader(input(roleSettings, { connectionId: "old" }));
|
||||
expect(minter.cachedTokenCount()).toBe(1);
|
||||
clock += 56 * 60 * 1000;
|
||||
await minter.authorizationHeader(input(roleSettings, { connectionId: "new" }));
|
||||
expect(minter.cachedTokenCount()).toBe(1);
|
||||
});
|
||||
|
||||
it("shares one mint between concurrent callers", async () => {
|
||||
let release!: () => void;
|
||||
const gate = new Promise<void>((resolve) => { release = resolve; });
|
||||
const clients = fakeAws({ createMcpToken: vi.fn(async () => { await gate; return { token: "only", expiresInSeconds: 3599 }; }) });
|
||||
const minter = createAwsMcpCredentialMinter({ clients, signConnectionToken: async () => ({ token: "jwt" }) });
|
||||
const calls = Array.from({ length: 5 }, () => minter.authorizationHeader(input(roleSettings)));
|
||||
release();
|
||||
expect(new Set((await Promise.all(calls)).map((h) => h.Authorization))).toEqual(new Set(["Bearer only"]));
|
||||
expect(clients.createMcpToken).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("stops waiting for a stalled AWS request, aborts it, and lets the next call try again", async () => {
|
||||
let aborted = false;
|
||||
let stall = true;
|
||||
const clients = fakeAws({
|
||||
assumeRoleWithWebIdentity: vi.fn((input: { signal?: AbortSignal }) => {
|
||||
if (!stall) return Promise.resolve({ accessKeyId: "ASIAOK", secretAccessKey: "s", sessionToken: "t" });
|
||||
return new Promise<never>(() => { input.signal?.addEventListener("abort", () => { aborted = true; }); });
|
||||
}),
|
||||
});
|
||||
const minter = createAwsMcpCredentialMinter({ clients, signConnectionToken: async () => ({ token: "jwt" }), stepTimeoutMs: 50 });
|
||||
const callers = [minter.authorizationHeader(input(roleSettings)), minter.authorizationHeader(input(roleSettings))];
|
||||
for (const caller of callers) await expect(caller).rejects.toMatchObject({ code: "aws_unavailable", status: 503, health: "degraded" });
|
||||
expect(aborted).toBe(true);
|
||||
stall = false;
|
||||
expect(await minter.authorizationHeader(input(roleSettings))).toEqual({ Authorization: "Bearer mcp-token-1" });
|
||||
});
|
||||
|
||||
it("maps AWS failures to stable codes and messages without AWS's own text", async () => {
|
||||
const awsError = (name: string, httpStatusCode: number) =>
|
||||
Object.assign(new Error(`AWS says arn:aws:iam::123456789012:role/secret-name ${name}`), { name, $metadata: { httpStatusCode } });
|
||||
const denied = createAwsMcpCredentialMinter({
|
||||
clients: fakeAws({ assumeRoleWithWebIdentity: vi.fn(async () => { throw awsError("AccessDenied", 403); }) }),
|
||||
signConnectionToken: async () => ({ token: "jwt" }),
|
||||
});
|
||||
const error = await denied.authorizationHeader(input(roleSettings)).catch((e) => e);
|
||||
expect(error).toMatchObject({ code: "aws_role_access_denied", status: 403, health: "error", awsErrorName: "AccessDenied" });
|
||||
expect(error.message).not.toContain("123456789012");
|
||||
|
||||
expect(classifyAwsMcpError("signin", awsError("UnauthorizedException", 401))).toMatchObject({ code: "aws_mcp_signin_denied", status: 403 });
|
||||
expect(classifyAwsMcpError("access_key", awsError("InvalidClientTokenId", 403))).toMatchObject({ code: "aws_access_key_invalid" });
|
||||
expect(classifyAwsMcpError("federation", awsError("AccessDenied", 403)).message).toContain("sts:GetFederationToken");
|
||||
expect(classifyAwsMcpError("role", awsError("ServiceUnavailable", 503))).toMatchObject({ code: "aws_unavailable", status: 503, health: "degraded" });
|
||||
expect(classifyAwsMcpError("role", awsError("Throttling", 400))).toMatchObject({ code: "aws_unavailable" });
|
||||
expect(classifyAwsMcpError("identity", Object.assign(new Error("x"), { details: { code: "workload_identity_unavailable" } })))
|
||||
.toMatchObject({ code: "aws_identity_unavailable", status: 422 });
|
||||
expect(classifyAwsMcpError("identity", Object.assign(new Error("x"), { details: { code: "workload_identity_issuer_changed" } })))
|
||||
.toMatchObject({ code: "aws_issuer_changed", status: 409, message: expect.stringContaining("address changed") });
|
||||
|
||||
const failing = createAwsMcpCredentialMinter({
|
||||
clients: fakeAws({ createMcpToken: vi.fn(async () => { throw awsError("UnauthorizedException", 401); }) }),
|
||||
signConnectionToken: async () => ({ token: "jwt" }),
|
||||
});
|
||||
await expect(failing.authorizationHeader(input(roleSettings))).rejects.toBeInstanceOf(AwsMcpCredentialError);
|
||||
// A failed mint is not cached: the next call tries AWS again.
|
||||
await expect(failing.authorizationHeader(input(roleSettings))).rejects.toMatchObject({ code: "aws_mcp_signin_denied" });
|
||||
});
|
||||
|
||||
it("accepts only AWS's endpoint for the saved region and valid role ARNs", () => {
|
||||
const connection = (config: Record<string, unknown>) => ({ id: "c", transport: "mcp_remote", config: {
|
||||
sourceTemplateKey: "aws", connectionMethodKey: "aws-role", url: "https://aws-mcp.us-east-1.api.aws/mcp",
|
||||
methodConfig: { roleArn: "arn:aws:iam::123456789012:role/agents", endpointRegion: "us-east-1", accessLevel: "full" }, ...config,
|
||||
} });
|
||||
expect(isAwsMcpConnection(connection({}))).toBe(true);
|
||||
expect(isAwsMcpConnection(connection({ connectionMethodKey: "other" }))).toBe(false);
|
||||
// Detection follows the method's credentialMinter declaration, not a hard-coded list.
|
||||
expect(isAwsMcpConnection(connection({ sourceTemplateKey: "pagerduty", connectionMethodKey: "mcp-api-key-us" }))).toBe(false);
|
||||
expect(isAwsMcpConnection({ ...connection({}), transport: "local_stdio" })).toBe(false);
|
||||
expect(awsMcpSettings(connection({}))).toEqual({ method: "aws-role", roleArn: "arn:aws:iam::123456789012:role/agents", endpointRegion: "us-east-1", accessLevel: "full" });
|
||||
expect(() => awsMcpSettings(connection({ url: "https://evil.example.com/mcp" }))).toThrow(AwsMcpCredentialError);
|
||||
expect(() => awsMcpSettings(connection({ url: "https://aws-mcp.eu-west-1.api.aws/mcp" }))).toThrow(AwsMcpCredentialError);
|
||||
expect(() => awsMcpSettings(connection({ methodConfig: { roleArn: "not-an-arn", endpointRegion: "us-east-1" } }))).toThrow(AwsMcpCredentialError);
|
||||
expect(() => awsMcpSettings(connection({ methodConfig: { endpointRegion: "us-east-1" } }))).toThrow(AwsMcpCredentialError);
|
||||
// An unknown access level is treated as read only, never as full.
|
||||
expect(awsMcpSettings(connection({ methodConfig: { roleArn: "arn:aws:iam::123456789012:role/agents", endpointRegion: "us-east-1", accessLevel: "admin" } })).accessLevel).toBe("read_only");
|
||||
});
|
||||
|
||||
it("builds session names STS accepts", () => {
|
||||
expect(awsSessionName("AWS Prod (us)")).toBe("paperclip-aws-prod-us");
|
||||
expect(awsSessionName("!!!")).toBe("paperclip-connection");
|
||||
expect(awsSessionName("x".repeat(200))).toHaveLength(64);
|
||||
expect(awsSessionName("x".repeat(200), 32)).toHaveLength(32);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,489 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import {
|
||||
AssumeRoleCommand,
|
||||
AssumeRoleWithWebIdentityCommand,
|
||||
GetFederationTokenCommand,
|
||||
STSClient,
|
||||
} from "@aws-sdk/client-sts";
|
||||
import { CreateOAuth2TokenWithIAMCommand, SigninClient } from "@aws-sdk/client-signin";
|
||||
import { getConnectableAppDefinition } from "@paperclipai/shared";
|
||||
|
||||
/**
|
||||
* Credentials for AWS's hosted MCP server, minted on the control plane for each
|
||||
* connection. A connection proves who it is with a Paperclip-signed OIDC token
|
||||
* (role method) or its own stored access key, gets short-lived AWS credentials,
|
||||
* and exchanges them for a one-hour MCP bearer token. Agents never see any of it.
|
||||
*/
|
||||
|
||||
export const AWS_MCP_SOURCE_TEMPLATE_KEY = "aws";
|
||||
/** The `credentialMinter` value AWS methods declare in their app definition. */
|
||||
export const AWS_MCP_CREDENTIAL_MINTER = "aws_mcp";
|
||||
export const AWS_MCP_METHOD_KEYS = ["aws-role", "aws-access-key"] as const;
|
||||
export type AwsMcpMethodKey = (typeof AWS_MCP_METHOD_KEYS)[number];
|
||||
export const AWS_MCP_ENDPOINT_REGIONS = [
|
||||
"us-east-1", "us-west-2", "eu-west-1", "eu-west-2", "eu-central-1",
|
||||
"ap-southeast-1", "ap-southeast-2", "ap-northeast-1",
|
||||
] as const;
|
||||
export const AWS_MCP_STS_AUDIENCE = "sts.amazonaws.com";
|
||||
export const AWS_MCP_TOKEN_RESOURCE = "aws-mcp.amazonaws.com";
|
||||
/** Read-only sessions also need the sign-in policy, or AWS refuses the token exchange. */
|
||||
export const AWS_MCP_READ_ONLY_SESSION_POLICIES = [
|
||||
"arn:aws:iam::aws:policy/ReadOnlyAccess",
|
||||
"arn:aws:iam::aws:policy/AWSMCPSignInOAuthAccessPolicy",
|
||||
] as const;
|
||||
export const AWS_MCP_ACCESS_KEY_ID_PATH = "credentials.accessKeyId";
|
||||
export const AWS_MCP_SECRET_ACCESS_KEY_PATH = "credentials.secretAccessKey";
|
||||
const SESSION_SECONDS = 3600;
|
||||
/** Each AWS request in a mint must finish within this, so a stalled AWS never holds a tool call. */
|
||||
const DEFAULT_STEP_TIMEOUT_MS = 10_000;
|
||||
/** Mint again this long before the token expires, so an in-flight call never carries an expiring token. */
|
||||
const REFRESH_MARGIN_MS = 5 * 60 * 1000;
|
||||
const ROLE_ARN_PATTERN = /^arn:aws[a-z-]*:iam::[0-9]{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
|
||||
|
||||
export type AwsMcpAccessLevel = "read_only" | "full";
|
||||
|
||||
export interface AwsMcpSettings {
|
||||
method: AwsMcpMethodKey;
|
||||
roleArn: string | null;
|
||||
endpointRegion: (typeof AWS_MCP_ENDPOINT_REGIONS)[number];
|
||||
accessLevel: AwsMcpAccessLevel;
|
||||
}
|
||||
|
||||
export interface AwsSessionCredentials {
|
||||
accessKeyId: string;
|
||||
secretAccessKey: string;
|
||||
sessionToken?: string;
|
||||
expiration?: Date;
|
||||
}
|
||||
|
||||
export type AwsMcpCredentialErrorCode =
|
||||
| "aws_mcp_settings_invalid"
|
||||
| "aws_identity_unavailable"
|
||||
| "aws_issuer_changed"
|
||||
| "aws_role_access_denied"
|
||||
| "aws_access_key_invalid"
|
||||
| "aws_mcp_signin_denied"
|
||||
| "aws_unavailable";
|
||||
|
||||
/** A failure with a plain-language message. AWS's own message is never shown, since it can carry account IDs and ARNs. */
|
||||
export class AwsMcpCredentialError extends Error {
|
||||
constructor(
|
||||
readonly code: AwsMcpCredentialErrorCode,
|
||||
readonly status: number,
|
||||
message: string,
|
||||
readonly health: "degraded" | "error",
|
||||
readonly awsErrorName?: string,
|
||||
) {
|
||||
super(message);
|
||||
this.name = "AwsMcpCredentialError";
|
||||
}
|
||||
}
|
||||
|
||||
interface ConnectionLike {
|
||||
id: string;
|
||||
transport: string;
|
||||
config: Record<string, unknown>;
|
||||
}
|
||||
|
||||
function asRecord(value: unknown): Record<string, unknown> {
|
||||
return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
|
||||
}
|
||||
|
||||
/** The credential minter the connection's method declares in its app definition, if any. */
|
||||
export function connectionCredentialMinter(connection: ConnectionLike): string | null {
|
||||
if (connection.transport !== "mcp_remote") return null;
|
||||
const slug = connection.config.sourceTemplateKey;
|
||||
const methodKey = connection.config.connectionMethodKey;
|
||||
if (typeof slug !== "string" || typeof methodKey !== "string") return null;
|
||||
const method = getConnectableAppDefinition(slug)?.methods.find((candidate) => candidate.key === methodKey);
|
||||
return method?.credentialMinter ?? null;
|
||||
}
|
||||
|
||||
/** The method's declaration decides: a connection whose method mints AWS MCP credentials. */
|
||||
export function isAwsMcpConnection(connection: ConnectionLike): boolean {
|
||||
return connectionCredentialMinter(connection) === AWS_MCP_CREDENTIAL_MINTER;
|
||||
}
|
||||
|
||||
/** Saved settings, rechecked at call time: the URL must be AWS's endpoint for the saved region. */
|
||||
export function awsMcpSettings(connection: ConnectionLike & { config: Record<string, unknown> }): AwsMcpSettings {
|
||||
const invalid = () => new AwsMcpCredentialError(
|
||||
"aws_mcp_settings_invalid", 422,
|
||||
"This AWS connection's settings are incomplete. Reconnect AWS.", "error",
|
||||
);
|
||||
const method = connection.config.connectionMethodKey;
|
||||
if (!(AWS_MCP_METHOD_KEYS as readonly unknown[]).includes(method)) throw invalid();
|
||||
const values = asRecord(connection.config.methodConfig);
|
||||
const endpointRegion = values.endpointRegion;
|
||||
if (!(AWS_MCP_ENDPOINT_REGIONS as readonly unknown[]).includes(endpointRegion)) throw invalid();
|
||||
if (connection.config.url !== `https://aws-mcp.${endpointRegion}.api.aws/mcp`) throw invalid();
|
||||
const roleArn = typeof values.roleArn === "string" && values.roleArn.trim() ? values.roleArn.trim() : null;
|
||||
if (roleArn !== null && !ROLE_ARN_PATTERN.test(roleArn)) throw invalid();
|
||||
if (method === "aws-role" && !roleArn) throw invalid();
|
||||
const accessLevel = values.accessLevel === "full" ? "full" : "read_only";
|
||||
return {
|
||||
method: method as AwsMcpMethodKey,
|
||||
roleArn,
|
||||
endpointRegion: endpointRegion as AwsMcpSettings["endpointRegion"],
|
||||
accessLevel,
|
||||
};
|
||||
}
|
||||
|
||||
/** `paperclip-<name>` in the characters STS allows, so CloudTrail shows which connection acted. */
|
||||
export function awsSessionName(connectionName: string, maxLength = 64): string {
|
||||
const cleaned = connectionName.toLowerCase().replace(/[^a-z0-9+=,.@-]+/g, "-").replace(/^-+|-+$/g, "");
|
||||
return `paperclip-${cleaned || "connection"}`.slice(0, maxLength);
|
||||
}
|
||||
|
||||
/** The four AWS calls the minter makes. Tests replace them with a fake AWS. */
|
||||
export interface AwsMcpClients {
|
||||
assumeRoleWithWebIdentity(input: {
|
||||
region: string; roleArn: string; sessionName: string; webIdentityToken: string; policyArns?: readonly string[]; signal?: AbortSignal;
|
||||
}): Promise<AwsSessionCredentials>;
|
||||
assumeRole(input: {
|
||||
region: string; credentials: AwsSessionCredentials; roleArn: string; sessionName: string; policyArns?: readonly string[]; signal?: AbortSignal;
|
||||
}): Promise<AwsSessionCredentials>;
|
||||
getFederationToken(input: {
|
||||
region: string; credentials: AwsSessionCredentials; name: string; policyArns: readonly string[]; signal?: AbortSignal;
|
||||
}): Promise<AwsSessionCredentials>;
|
||||
createMcpToken(input: { region: string; credentials: AwsSessionCredentials; signal?: AbortSignal }): Promise<{ token: string; expiresInSeconds: number }>;
|
||||
}
|
||||
|
||||
function stsCredentials(value: { AccessKeyId?: string; SecretAccessKey?: string; SessionToken?: string; Expiration?: Date } | undefined): AwsSessionCredentials {
|
||||
if (!value?.AccessKeyId || !value.SecretAccessKey) throw new Error("AWS returned no credentials");
|
||||
return {
|
||||
accessKeyId: value.AccessKeyId,
|
||||
secretAccessKey: value.SecretAccessKey,
|
||||
sessionToken: value.SessionToken,
|
||||
expiration: value.Expiration,
|
||||
};
|
||||
}
|
||||
|
||||
const policyArnList = (arns?: readonly string[]) => arns?.length ? { PolicyArns: arns.map((arn) => ({ arn })) } : {};
|
||||
|
||||
export const sdkAwsMcpClients: AwsMcpClients = {
|
||||
async assumeRoleWithWebIdentity(input) {
|
||||
// No caller credentials: the signed web identity token is the proof.
|
||||
const sts = new STSClient({ region: input.region, credentials: { accessKeyId: "none", secretAccessKey: "none" } });
|
||||
const out = await sts.send(new AssumeRoleWithWebIdentityCommand({
|
||||
RoleArn: input.roleArn, RoleSessionName: input.sessionName, WebIdentityToken: input.webIdentityToken,
|
||||
DurationSeconds: SESSION_SECONDS, ...policyArnList(input.policyArns),
|
||||
}), { abortSignal: input.signal });
|
||||
return stsCredentials(out.Credentials);
|
||||
},
|
||||
async assumeRole(input) {
|
||||
const sts = new STSClient({ region: input.region, credentials: input.credentials });
|
||||
const out = await sts.send(new AssumeRoleCommand({
|
||||
RoleArn: input.roleArn, RoleSessionName: input.sessionName,
|
||||
DurationSeconds: SESSION_SECONDS, ...policyArnList(input.policyArns),
|
||||
}), { abortSignal: input.signal });
|
||||
return stsCredentials(out.Credentials);
|
||||
},
|
||||
async getFederationToken(input) {
|
||||
const sts = new STSClient({ region: input.region, credentials: input.credentials });
|
||||
const out = await sts.send(new GetFederationTokenCommand({
|
||||
Name: input.name, DurationSeconds: SESSION_SECONDS, ...policyArnList(input.policyArns),
|
||||
}), { abortSignal: input.signal });
|
||||
return stsCredentials(out.Credentials);
|
||||
},
|
||||
async createMcpToken(input) {
|
||||
const signin = new SigninClient({ region: input.region, credentials: input.credentials });
|
||||
const out = await signin.send(new CreateOAuth2TokenWithIAMCommand({
|
||||
grantType: "client_credentials", resource: AWS_MCP_TOKEN_RESOURCE,
|
||||
} as ConstructorParameters<typeof CreateOAuth2TokenWithIAMCommand>[0]), { abortSignal: input.signal });
|
||||
const token = (out as { accessToken?: string }).accessToken;
|
||||
const expiresInSeconds = (out as { expiresIn?: number }).expiresIn ?? SESSION_SECONDS;
|
||||
if (!token) throw new Error("AWS returned no MCP token");
|
||||
return { token, expiresInSeconds };
|
||||
},
|
||||
};
|
||||
|
||||
type Step = "identity" | "role" | "access_key" | "federation" | "signin";
|
||||
|
||||
function awsErrorName(error: unknown): string | undefined {
|
||||
const record = asRecord(error);
|
||||
return typeof record.name === "string" ? record.name : undefined;
|
||||
}
|
||||
|
||||
function awsHttpStatus(error: unknown): number | undefined {
|
||||
const status = asRecord(asRecord(error).$metadata).httpStatusCode;
|
||||
return typeof status === "number" ? status : undefined;
|
||||
}
|
||||
|
||||
/** Maps an AWS failure to a stable code and a message that names the fix, never AWS's raw text. */
|
||||
export function classifyAwsMcpError(step: Step, error: unknown): AwsMcpCredentialError {
|
||||
if (error instanceof AwsMcpCredentialError) return error;
|
||||
const name = awsErrorName(error);
|
||||
const status = awsHttpStatus(error);
|
||||
const details = asRecord(asRecord(error).details);
|
||||
if (step === "identity") {
|
||||
if (details.code === "workload_identity_issuer_changed") {
|
||||
return new AwsMcpCredentialError(
|
||||
"aws_issuer_changed", 409,
|
||||
"This Paperclip instance's address changed since AWS was connected. Register the new identity provider address in AWS, then reconnect AWS.",
|
||||
"error",
|
||||
);
|
||||
}
|
||||
if (details.code === "workload_identity_unavailable") {
|
||||
return new AwsMcpCredentialError(
|
||||
"aws_identity_unavailable", 422,
|
||||
"The AWS role method needs this Paperclip instance to have a stable public HTTPS address. Use an access key instead.",
|
||||
"error",
|
||||
);
|
||||
}
|
||||
return new AwsMcpCredentialError("aws_unavailable", 503, "Paperclip could not prepare this AWS connection's identity. Try again.", "degraded");
|
||||
}
|
||||
const transient = !status || status >= 500 || status === 429
|
||||
|| ["ThrottlingException", "Throttling", "TimeoutError", "RequestTimeout", "IDPCommunicationError"].includes(name ?? "");
|
||||
if (transient) {
|
||||
return new AwsMcpCredentialError("aws_unavailable", 503, "AWS did not respond. Try again shortly.", "degraded", name);
|
||||
}
|
||||
if (step === "signin") {
|
||||
return new AwsMcpCredentialError(
|
||||
"aws_mcp_signin_denied", 403,
|
||||
"AWS refused the MCP sign-in. Attach the AWSMCPSignInOAuthAccessPolicy managed policy to this connection's role or user.",
|
||||
"error", name,
|
||||
);
|
||||
}
|
||||
if (step === "role") {
|
||||
return new AwsMcpCredentialError(
|
||||
"aws_role_access_denied", 403,
|
||||
"AWS refused this connection's role. Check that the role exists and trusts this connection.",
|
||||
"error", name,
|
||||
);
|
||||
}
|
||||
return new AwsMcpCredentialError(
|
||||
"aws_access_key_invalid", 403,
|
||||
step === "federation"
|
||||
? "AWS refused a read-only session for this access key. Allow sts:GetFederationToken for this IAM user."
|
||||
: "AWS did not accept this connection's access key. Check that the key is active, or reconnect AWS with a new key.",
|
||||
"error", name,
|
||||
);
|
||||
}
|
||||
|
||||
export interface AwsMcpMintInput {
|
||||
companyId: string;
|
||||
connectionId: string;
|
||||
connectionName: string;
|
||||
/** Changes whenever the connection or its grant is edited, so any edit makes a fresh token. */
|
||||
revision: string;
|
||||
grantId: string;
|
||||
/** The issuer recorded at setup; signing stops with a clear message if the instance address changed. */
|
||||
expectedIssuer?: string | null;
|
||||
settings: AwsMcpSettings;
|
||||
/** Reads a stored credential field by config path (access-key method only). */
|
||||
readSecret(configPath: string): Promise<string>;
|
||||
forceRefresh?: boolean;
|
||||
}
|
||||
|
||||
export interface AwsMcpCredentialMinterOptions {
|
||||
clients?: AwsMcpClients;
|
||||
/** Signs a connection identity token (the workload identity issuer). */
|
||||
signConnectionToken(input: { companyId: string; connectionId: string; audience: string; expectedIssuer?: string | null }): Promise<{ token: string }>;
|
||||
now?: () => number;
|
||||
/** Deadline for each AWS request (default 10 s). */
|
||||
stepTimeoutMs?: number;
|
||||
}
|
||||
|
||||
interface CacheEntry { fingerprint: string; header: string; refreshAt: number }
|
||||
|
||||
export function createAwsMcpCredentialMinter(options: AwsMcpCredentialMinterOptions) {
|
||||
const clients = options.clients ?? sdkAwsMcpClients;
|
||||
const now = options.now ?? (() => Date.now());
|
||||
const stepTimeoutMs = options.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
|
||||
const cache = new Map<string, CacheEntry>();
|
||||
const inFlight = new Map<string, Promise<string>>();
|
||||
|
||||
async function step<T>(name: Step, run: (signal: AbortSignal) => Promise<T>): Promise<T> {
|
||||
const controller = new AbortController();
|
||||
let timer: ReturnType<typeof setTimeout> | undefined;
|
||||
const deadline = new Promise<never>((_, reject) => {
|
||||
timer = setTimeout(() => {
|
||||
controller.abort();
|
||||
reject(Object.assign(new Error("AWS request timed out"), { name: "TimeoutError" }));
|
||||
}, stepTimeoutMs);
|
||||
timer.unref?.();
|
||||
});
|
||||
try {
|
||||
return await Promise.race([run(controller.signal), deadline]);
|
||||
} catch (error) {
|
||||
throw classifyAwsMcpError(name, error);
|
||||
} finally {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
}
|
||||
|
||||
async function sessionCredentials(input: AwsMcpMintInput): Promise<AwsSessionCredentials> {
|
||||
const { settings } = input;
|
||||
const region = settings.endpointRegion;
|
||||
const sessionName = awsSessionName(input.connectionName);
|
||||
const readOnlyPolicies = settings.accessLevel === "read_only" ? AWS_MCP_READ_ONLY_SESSION_POLICIES : undefined;
|
||||
if (settings.method === "aws-role") {
|
||||
const { token } = await step("identity", () => options.signConnectionToken({
|
||||
companyId: input.companyId, connectionId: input.connectionId, audience: AWS_MCP_STS_AUDIENCE,
|
||||
expectedIssuer: input.expectedIssuer,
|
||||
}));
|
||||
return step("role", (signal) => clients.assumeRoleWithWebIdentity({
|
||||
region, roleArn: settings.roleArn!, sessionName, webIdentityToken: token, policyArns: readOnlyPolicies, signal,
|
||||
}));
|
||||
}
|
||||
const base: AwsSessionCredentials = {
|
||||
accessKeyId: await input.readSecret(AWS_MCP_ACCESS_KEY_ID_PATH),
|
||||
secretAccessKey: await input.readSecret(AWS_MCP_SECRET_ACCESS_KEY_PATH),
|
||||
};
|
||||
if (settings.roleArn) {
|
||||
return step("role", (signal) => clients.assumeRole({
|
||||
region, credentials: base, roleArn: settings.roleArn!, sessionName, policyArns: readOnlyPolicies, signal,
|
||||
}));
|
||||
}
|
||||
if (readOnlyPolicies) {
|
||||
// Federation token names allow at most 32 characters.
|
||||
return step("federation", (signal) => clients.getFederationToken({
|
||||
region, credentials: base, name: awsSessionName(input.connectionName, 32), policyArns: readOnlyPolicies, signal,
|
||||
}));
|
||||
}
|
||||
return base;
|
||||
}
|
||||
|
||||
async function mintHeader(input: AwsMcpMintInput, fingerprint: string, key: string): Promise<string> {
|
||||
const credentials = await sessionCredentials(input);
|
||||
const { token, expiresInSeconds } = await step("signin", (signal) => clients.createMcpToken({
|
||||
region: input.settings.endpointRegion, credentials, signal,
|
||||
}));
|
||||
const expiresAt = Math.min(
|
||||
now() + expiresInSeconds * 1000,
|
||||
credentials.expiration ? credentials.expiration.getTime() : Number.POSITIVE_INFINITY,
|
||||
);
|
||||
const header = `Bearer ${token}`;
|
||||
// Drop tokens past their refresh point, so the cache only ever holds live tokens (removed connections included).
|
||||
for (const [cachedKey, entry] of cache) if (entry.refreshAt <= now()) cache.delete(cachedKey);
|
||||
cache.set(key, { fingerprint, header, refreshAt: expiresAt - REFRESH_MARGIN_MS });
|
||||
return header;
|
||||
}
|
||||
|
||||
return {
|
||||
/** The Authorization header for one connection and grant, cached until about 55 minutes in. */
|
||||
async authorizationHeader(input: AwsMcpMintInput): Promise<Record<string, string>> {
|
||||
const key = `${input.companyId}:${input.connectionId}:${input.grantId}`;
|
||||
const fingerprint = createHash("sha256")
|
||||
.update(JSON.stringify([input.revision, input.settings]))
|
||||
.digest("base64url");
|
||||
const cached = cache.get(key);
|
||||
if (!input.forceRefresh && cached && cached.fingerprint === fingerprint && cached.refreshAt > now()) {
|
||||
return { Authorization: cached.header };
|
||||
}
|
||||
if (input.forceRefresh || (cached && cached.fingerprint !== fingerprint)) cache.delete(key);
|
||||
const flightKey = `${key}:${fingerprint}`;
|
||||
let flight = inFlight.get(flightKey);
|
||||
if (!flight) {
|
||||
flight = mintHeader(input, fingerprint, key).finally(() => inFlight.delete(flightKey));
|
||||
inFlight.set(flightKey, flight);
|
||||
}
|
||||
return { Authorization: await flight };
|
||||
},
|
||||
/** How many tokens are cached (observability and tests). */
|
||||
cachedTokenCount(): number {
|
||||
return cache.size;
|
||||
},
|
||||
/** Drops every cached token for a connection, for example after AWS answers 401. */
|
||||
evict(companyId: string, connectionId: string) {
|
||||
const prefix = `${companyId}:${connectionId}:`;
|
||||
for (const key of cache.keys()) if (key.startsWith(prefix)) cache.delete(key);
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export type AwsMcpCredentialMinter = ReturnType<typeof createAwsMcpCredentialMinter>;
|
||||
|
||||
const sharedMinters = new WeakMap<object, AwsMcpCredentialMinter>();
|
||||
|
||||
/**
|
||||
* One minter per database, shared by the gateway and connection health checks so
|
||||
* a token minted for discovery is reused by the next call, and an eviction after a
|
||||
* 401 applies everywhere.
|
||||
*/
|
||||
export function sharedAwsMcpCredentialMinter(
|
||||
db: object,
|
||||
signConnectionToken: AwsMcpCredentialMinterOptions["signConnectionToken"],
|
||||
clients?: AwsMcpClients,
|
||||
): AwsMcpCredentialMinter {
|
||||
// Test fakes get one shared minter per fake, like production gets one per database.
|
||||
const owner = clients ?? db;
|
||||
let minter = sharedMinters.get(owner);
|
||||
if (!minter) {
|
||||
minter = createAwsMcpCredentialMinter({ signConnectionToken, clients });
|
||||
sharedMinters.set(owner, minter);
|
||||
}
|
||||
return minter;
|
||||
}
|
||||
|
||||
interface RevisionSource {
|
||||
status: string;
|
||||
enabled: boolean;
|
||||
credentialSecretRefs: Array<{ secretId: string; versionSelector?: unknown; configPath: string }>;
|
||||
}
|
||||
|
||||
/**
|
||||
* What a cached token depends on besides the saved settings: which stored key it
|
||||
* came from and whether the grant is live. Health and last-used
|
||||
* stamps change on every call, so update times are deliberately not part of it.
|
||||
*/
|
||||
export function awsMcpCredentialRevision(
|
||||
connection: RevisionSource,
|
||||
grant?: { id: string; status: string; credentialSecretRefs: RevisionSource["credentialSecretRefs"] } | null,
|
||||
): string {
|
||||
const refs = (grant?.credentialSecretRefs ?? connection.credentialSecretRefs)
|
||||
.map((ref) => `${ref.configPath}=${ref.secretId}@${String(ref.versionSelector ?? "latest")}`)
|
||||
.sort();
|
||||
// Connection status is deliberately absent: finishing setup must not discard the token setup minted,
|
||||
// and the gateway refuses a disabled connection before it asks for credentials.
|
||||
return JSON.stringify([grant?.id ?? null, grant?.status ?? null, refs]);
|
||||
}
|
||||
|
||||
/** The role method proves itself with the company's issuer, which must be published before the customer registers it in AWS. */
|
||||
export function awsMcpMethodUsesIssuer(appSlug: string | null | undefined, methodKey: string | null | undefined): boolean {
|
||||
return appSlug === AWS_MCP_SOURCE_TEMPLATE_KEY && methodKey === "aws-role";
|
||||
}
|
||||
|
||||
|
||||
/** Where setup records the issuer a role connection's AWS trust was created for. */
|
||||
export const AWS_MCP_ISSUER_CONFIG_KEY = "workloadIdentityIssuer";
|
||||
|
||||
type SecretRefLike = RevisionSource["credentialSecretRefs"][number];
|
||||
|
||||
/**
|
||||
* The shared minting pipeline for the gateway and connection health checks: builds
|
||||
* the minter input from the connection and grant and reads stored keys through the
|
||||
* caller's resolver. Failures are AwsMcpCredentialError; errors from `readRef`
|
||||
* (the caller's own secret resolution) pass through unchanged.
|
||||
*/
|
||||
export async function resolveAwsMcpAuthorization<Ref extends SecretRefLike>(input: {
|
||||
minter: AwsMcpCredentialMinter;
|
||||
connection: ConnectionLike & { companyId: string; name: string; status: string; enabled: boolean; credentialSecretRefs: Ref[] };
|
||||
grant: { id: string; status: string; credentialSecretRefs: Ref[] } | null;
|
||||
forceRefresh?: boolean;
|
||||
readRef(ref: Ref): Promise<string>;
|
||||
}): Promise<Record<string, string>> {
|
||||
const { connection, grant } = input;
|
||||
const refs = grant?.credentialSecretRefs ?? connection.credentialSecretRefs;
|
||||
const recordedIssuer = connection.config[AWS_MCP_ISSUER_CONFIG_KEY];
|
||||
return input.minter.authorizationHeader({
|
||||
companyId: connection.companyId,
|
||||
connectionId: connection.id,
|
||||
connectionName: connection.name,
|
||||
grantId: grant?.id ?? "shared",
|
||||
revision: awsMcpCredentialRevision(connection, grant),
|
||||
settings: awsMcpSettings(connection),
|
||||
expectedIssuer: typeof recordedIssuer === "string" ? recordedIssuer : null,
|
||||
forceRefresh: input.forceRefresh,
|
||||
readSecret: async (configPath) => {
|
||||
const ref = refs.find((candidate) => candidate.configPath === configPath);
|
||||
if (!ref) {
|
||||
throw new AwsMcpCredentialError(
|
||||
"aws_access_key_invalid", 422,
|
||||
"This AWS connection has no saved access key. Reconnect AWS.", "error",
|
||||
);
|
||||
}
|
||||
return input.readRef(ref);
|
||||
},
|
||||
});
|
||||
}
|
||||
@@ -268,6 +268,7 @@ export function normalizeExperimentalSettings(raw: unknown): InstanceExperimenta
|
||||
enableMemoryConnectors: parsed.data.enableMemoryConnectors ?? false,
|
||||
enablePaperclipNotebook: parsed.data.enablePaperclipNotebook ?? false,
|
||||
enableGoogleWorkspaceConnector: parsed.data.enableGoogleWorkspaceConnector ?? false,
|
||||
enableAwsConnector: parsed.data.enableAwsConnector ?? false,
|
||||
enableCases: parsed.data.enableCases ?? false,
|
||||
enableAgentChat: true,
|
||||
enableCombinedInboxTasks: parsed.data.enableCombinedInboxTasks ?? false,
|
||||
@@ -329,6 +330,7 @@ export function normalizeExperimentalSettings(raw: unknown): InstanceExperimenta
|
||||
enableMemoryConnectors: false,
|
||||
enablePaperclipNotebook: false,
|
||||
enableGoogleWorkspaceConnector: false,
|
||||
enableAwsConnector: false,
|
||||
enableCases: false,
|
||||
enableAgentChat: true,
|
||||
enableCombinedInboxTasks: false,
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
import { notifyGitHubCredentialChange } from "./github-connection-notifications.js";
|
||||
import { AWS_MCP_ISSUER_CONFIG_KEY, awsMcpMethodUsesIssuer, type AwsMcpClients } from "./connectors/aws/mcp-credentials.js";
|
||||
import { workloadIdentityIssuer, workloadIdentityIssuerOrigin, workloadIdentityService } from "./workload-identity.js";
|
||||
import { RepositoryCatalogUnavailableError, findRepositoryCatalogUnavailableError } from "./repository-catalog-unavailable-error.js";
|
||||
import { notifyVoiceChange } from "./voice/voice-recovery-notifications.js";
|
||||
import { notifyToolConnectionHealth, writeToolConnectionHealthChange } from "./tool-connection-health-notifications.js";
|
||||
@@ -173,6 +175,8 @@ type ToolAccessServiceOptions = {
|
||||
paperclipCloudConnector?: PaperclipCloudConnector | null;
|
||||
/** Test seam for Vercel Connect without live vendor traffic. */
|
||||
vercelConnectClient?: VercelConnectClient | null;
|
||||
/** Test seam for the AWS calls behind minted AWS MCP credentials. */
|
||||
awsMcpClients?: AwsMcpClients;
|
||||
};
|
||||
|
||||
const GOOGLE_SHEETS_SPREADSHEET_SCHEMA = {
|
||||
@@ -837,7 +841,7 @@ export function toolAccessService(
|
||||
const { refreshManagedGitHubGrantAccess, syncGitHubGrantBindings, sweepGitHubConnectionContinuity, nextGitHubConnectionContinuityAt, githubConnectionContinuitySchedule } = createGitHubGrantContinuity(db, { now, currentCloudConnector, refreshOAuthGrantCredentials, resolveOAuthGrantSecret });
|
||||
const vercelCredentials = createVercelCredentialService(db, now, vercelConnect);
|
||||
const { resolveVercelCredentialHeaders, vercelGrantForConnection } = vercelCredentials;
|
||||
const credentialAccess = createConnectionCredentialAccess(db, { secrets, audit, vercel: vercelCredentials, resolveOAuthGrantSecret, maybeRefreshOAuthCredentials, refreshOAuthGrantCredentials });
|
||||
const credentialAccess = createConnectionCredentialAccess(db, { secrets, audit, vercel: vercelCredentials, resolveOAuthGrantSecret, maybeRefreshOAuthCredentials, refreshOAuthGrantCredentials, awsMcpClients: options.awsMcpClients });
|
||||
const { vaultGrantForConnection, resolveCredentialHeaders, resolvedRemoteEndpoint } = credentialAccess;
|
||||
const setupPolicy = createConnectionSetupPolicy(db);
|
||||
const { assertConnectorConnectionSetupEnabled, assertExperimentalConnectorSetupEnabled } = setupPolicy;
|
||||
@@ -2251,9 +2255,20 @@ export function toolAccessService(
|
||||
"",
|
||||
}
|
||||
: { templateId: method?.defaults?.templateKey };
|
||||
// The issuer an AWS role is asked to trust, recorded so a later change of this instance's address
|
||||
// gets a clear message instead of a role refusal. A draft being resumed keeps the issuer recorded at
|
||||
// the draft step; any other setup or reconnect records the current address (the one now in AWS).
|
||||
const recordedAwsIssuer = !input.reconnectConnectionId && retainedConnection?.status === "draft"
|
||||
? asRecord(retainedConnection.config)[AWS_MCP_ISSUER_CONFIG_KEY]
|
||||
: undefined;
|
||||
const awsIssuerOrigin = workloadIdentityIssuerOrigin();
|
||||
const awsRoleIssuer = !awsMcpMethodUsesIssuer(galleryEntry?.slug, method?.key) ? null
|
||||
: typeof recordedAwsIssuer === "string" ? recordedAwsIssuer
|
||||
: awsIssuerOrigin.available ? workloadIdentityIssuer(awsIssuerOrigin.origin, companyId) : null;
|
||||
let config: Record<string, unknown> = galleryEntry
|
||||
? {
|
||||
...baseConfig,
|
||||
...(awsRoleIssuer ? { [AWS_MCP_ISSUER_CONFIG_KEY]: awsRoleIssuer } : {}),
|
||||
sourceTemplateKey: galleryEntry.slug,
|
||||
connectionMethodKey: method?.key,
|
||||
methodConfig: normalizedMethodConfig?.values ?? {},
|
||||
@@ -2921,7 +2936,13 @@ export function toolAccessService(
|
||||
);
|
||||
await ensureRuntimeSlot(connectionRow);
|
||||
|
||||
if (input.saveDraft && remoteMcpConnector) {
|
||||
// Minted-credential methods (AWS role) need the connection to exist before the
|
||||
// provider can trust it, so they may also save a draft without contacting it.
|
||||
// AWS validates the issuer's discovery document when the customer registers it, so publish the key now.
|
||||
if (input.saveDraft && awsMcpMethodUsesIssuer(galleryEntry?.slug, method?.key)) {
|
||||
await workloadIdentityService(db).ensureActiveKey(companyId);
|
||||
}
|
||||
if (input.saveDraft && (remoteMcpConnector || method?.credentialMinter)) {
|
||||
return { connectionId: connectionRow.id, application: toApplication(applicationRow), connection: toConnection(connectionRow),
|
||||
catalog: [], actions: { readOnly: [], canMakeChanges: [] }, suggestedDefaults: { access: "all_agents", askFirstRiskLevels: [] } };
|
||||
}
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { assertSupportedConnection } from "../connections/setup-policy.js";
|
||||
import { isAwsMcpConnection } from "../../connectors/aws/mcp-credentials.js";
|
||||
import { usesClientCredentials } from "../oauth/client-credentials.js";
|
||||
import { vercelCredentialFor, vercelConnectResourcesFor } from "../vercel-credentials.js";
|
||||
import { connectionSetupUrl, connectionReconnectUrl } from "../identifiers.js";
|
||||
@@ -345,6 +346,14 @@ export function createToolCatalogDiscovery(db: Db, { now, audit, secrets, creden
|
||||
await response.body?.cancel().catch(() => undefined);
|
||||
throw unprocessable(INSUFFICIENT_CONNECTION_SCOPE_MESSAGE, { code: "oauth_insufficient_scope", connectionId: connection.id });
|
||||
}
|
||||
if (response.status === 401 && isAwsMcpConnection(connection)) {
|
||||
// A refused AWS token: mint a fresh one and list again (listing has no side effects).
|
||||
headers = {
|
||||
...projectedConnectionHeaders(connection),
|
||||
...(await resolveCredentialHeaders(connection, actor, { forceRefresh: true })),
|
||||
};
|
||||
response = await relistAfterCredentialRefresh();
|
||||
}
|
||||
if (
|
||||
response.status === 401 &&
|
||||
connection.credentialSource === "vercel_connect"
|
||||
|
||||
@@ -106,6 +106,10 @@ export function sanitizeHttpFailure(error: unknown): {
|
||||
code: "oauth_reauthorization_required",
|
||||
};
|
||||
}
|
||||
if (typeof code === "string" && code.startsWith("aws_") && code !== "aws_unavailable") {
|
||||
return { status: "error", message: error.message, code };
|
||||
}
|
||||
if (code === "aws_unavailable") return { status: "degraded", message: error.message, code };
|
||||
if (typeof code === "string" && code.startsWith("vercel_connect_")) {
|
||||
return {
|
||||
status:
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
import { connectionActorUserId } from "./actor.js";
|
||||
import { AwsMcpCredentialError, isAwsMcpConnection, resolveAwsMcpAuthorization, sharedAwsMcpCredentialMinter, type AwsMcpClients } from "../connectors/aws/mcp-credentials.js";
|
||||
import { workloadIdentityService } from "../workload-identity.js";
|
||||
import type { ActorInfo } from "./types.js";
|
||||
import { oauthConfig } from "./oauth/metadata.js";
|
||||
import { remoteEndpoint } from "./connection-methods.js";
|
||||
@@ -26,6 +28,8 @@ function asRecord(value: unknown): Record<string, unknown> {
|
||||
|
||||
type CredentialAccessDependencies = {
|
||||
secrets: ReturnType<typeof secretService>;
|
||||
/** Test seam for the AWS calls behind minted AWS MCP credentials. */
|
||||
awsMcpClients?: AwsMcpClients;
|
||||
audit: ToolAccessAudit;
|
||||
vercel: VercelCredentialService;
|
||||
resolveOAuthGrantSecret: OAuthCredentialStore["resolveOAuthGrantSecret"];
|
||||
@@ -33,7 +37,10 @@ type CredentialAccessDependencies = {
|
||||
refreshOAuthGrantCredentials: ReturnType<typeof createOAuthGrantRefresh>;
|
||||
};
|
||||
|
||||
export function createConnectionCredentialAccess(db: Db, { secrets, audit, vercel, resolveOAuthGrantSecret, maybeRefreshOAuthCredentials, refreshOAuthGrantCredentials }: CredentialAccessDependencies) {
|
||||
export function createConnectionCredentialAccess(db: Db, { secrets, audit, vercel, resolveOAuthGrantSecret, maybeRefreshOAuthCredentials, refreshOAuthGrantCredentials, awsMcpClients }: CredentialAccessDependencies) {
|
||||
const signAwsConnectionToken = (input: { companyId: string; connectionId: string; audience: string }) =>
|
||||
workloadIdentityService(db).signConnectionToken(input);
|
||||
const awsMcpMinter = sharedAwsMcpCredentialMinter(db, signAwsConnectionToken, awsMcpClients);
|
||||
const { resolveVercelCredentialHeaders, vercelGrantForConnection } = vercel;
|
||||
async function vaultGrantForConnection(
|
||||
connection: typeof toolConnections.$inferSelect,
|
||||
@@ -137,6 +144,40 @@ export function createConnectionCredentialAccess(db: Db, { secrets, audit, verce
|
||||
return null;
|
||||
}
|
||||
|
||||
/** Minted at call time for AWS's hosted MCP server; shares the gateway's token cache. */
|
||||
async function resolveAwsMcpHeaders(
|
||||
connection: typeof toolConnections.$inferSelect,
|
||||
actor: ActorInfo | undefined,
|
||||
options: { forceRefresh?: boolean },
|
||||
): Promise<Record<string, string>> {
|
||||
// The same grant the gateway uses, so both share one cached token and a shared connection never reads
|
||||
// a personal key: a shared connection uses only its active default organization grant.
|
||||
const grant = connection.credentialPolicy === "shared"
|
||||
? (await db.select().from(connectionGrants).where(and(
|
||||
eq(connectionGrants.companyId, connection.companyId),
|
||||
eq(connectionGrants.connectionId, connection.id),
|
||||
eq(connectionGrants.kind, "organization"),
|
||||
eq(connectionGrants.isDefault, true),
|
||||
eq(connectionGrants.status, "active"),
|
||||
)).limit(1))[0] ?? null
|
||||
: await vaultGrantForConnection(connection, actor);
|
||||
try {
|
||||
return await resolveAwsMcpAuthorization({
|
||||
minter: awsMcpMinter, connection, grant, forceRefresh: options.forceRefresh,
|
||||
// A grant's keys may be user-owned (personal connections); read them the way other grant credentials are read.
|
||||
readRef: async (ref) => grant
|
||||
? (await resolveOAuthGrantSecret(connection, grant, ref, actor, undefined)).value
|
||||
: secrets.resolveSecretValue(connection.companyId, ref.secretId, ref.versionSelector ?? "latest"),
|
||||
});
|
||||
} catch (error) {
|
||||
if (!(error instanceof AwsMcpCredentialError)) throw error;
|
||||
throw new HttpError(error.status, error.message, {
|
||||
code: error.code, connectionId: connection.id,
|
||||
...(error.awsErrorName ? { awsError: error.awsErrorName } : {}),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
async function resolveCredentialHeaders(
|
||||
connection: typeof toolConnections.$inferSelect,
|
||||
actor?: ActorInfo,
|
||||
@@ -146,6 +187,7 @@ export function createConnectionCredentialAccess(db: Db, { secrets, audit, verce
|
||||
const grant = await vercelGrantForConnection(connection, actor);
|
||||
return resolveVercelCredentialHeaders(connection, grant, options);
|
||||
}
|
||||
if (isAwsMcpConnection(connection)) return resolveAwsMcpHeaders(connection, actor, options);
|
||||
let grant: typeof connectionGrants.$inferSelect | null = null;
|
||||
try {
|
||||
if (
|
||||
|
||||
@@ -1,4 +1,12 @@
|
||||
import { assertAgentToolAssignmentInteractions } from "./connection-management.js";
|
||||
import {
|
||||
AwsMcpCredentialError,
|
||||
isAwsMcpConnection,
|
||||
resolveAwsMcpAuthorization,
|
||||
sharedAwsMcpCredentialMinter,
|
||||
type AwsMcpClients,
|
||||
} from "./connectors/aws/mcp-credentials.js";
|
||||
import { workloadIdentityService } from "./workload-identity.js";
|
||||
import { isNewHumanIntentAfterToolRejection } from "./tool-action-replay-intent.js";
|
||||
import { approvalSnapshotsMatch, approvalTargetChangeMessage, oauthApprovalConfig,
|
||||
approvalGrantTenantIdentity, externalCredentialApprovalIdentity } from "./tool-approval-target.js";
|
||||
@@ -619,6 +627,7 @@ const REMOTE_TOOL_CALL_WORKFLOW_REASON_CODES = new Set([
|
||||
"provider_retry_requested",
|
||||
"oauth_insufficient_scope",
|
||||
"oauth_refreshed_retry_required",
|
||||
"credentials_refreshed_retry_required",
|
||||
"provider_task_pending",
|
||||
"provider_task_cancelled",
|
||||
"provider_task_expired",
|
||||
@@ -1400,6 +1409,8 @@ export function createToolGatewayService(
|
||||
}) => Promise<typeof connectionGrants.$inferSelect>;
|
||||
/** Test seam for resolving Vercel Connect credentials. */
|
||||
vercelConnectClient?: VercelConnectClient | null;
|
||||
/** Test seam for the AWS calls behind minted AWS MCP credentials. */
|
||||
awsMcpClients?: AwsMcpClients;
|
||||
/** Test seam for reproducing the managed-argument drift expiry race. */
|
||||
beforeManagedArgumentDriftExpiry?: () => Promise<void>;
|
||||
/** Test seam for pausing a legacy approved request before its execution claim. */
|
||||
@@ -1655,6 +1666,9 @@ export function createToolGatewayService(
|
||||
options.vercelConnectClient === undefined
|
||||
? createVercelConnectClient()
|
||||
: options.vercelConnectClient;
|
||||
const signAwsConnectionToken = (input: { companyId: string; connectionId: string; audience: string }) =>
|
||||
workloadIdentityService(db).signConnectionToken(input);
|
||||
const awsMcpMinter = sharedAwsMcpCredentialMinter(db, signAwsConnectionToken, options.awsMcpClients);
|
||||
const protocolLimits = mcpGatewayProtocolLimits(
|
||||
options.mcpGatewayProtocolLimits,
|
||||
);
|
||||
@@ -4703,6 +4717,9 @@ export function createToolGatewayService(
|
||||
});
|
||||
}
|
||||
}
|
||||
if (isAwsMcpConnection(connection)) {
|
||||
return resolveAwsMcpHeaders(session, connection, grant, resolveOptions);
|
||||
}
|
||||
const oauth = asRecord(asRecord(connection.config)?.oauth);
|
||||
if (
|
||||
isPaperclipCloudConnectorStrategy(oauth?.strategy) &&
|
||||
@@ -4817,6 +4834,35 @@ export function createToolGatewayService(
|
||||
return headers;
|
||||
}
|
||||
|
||||
/** AWS's Authorization header is minted per connection at call time and never stored. */
|
||||
async function resolveAwsMcpHeaders(
|
||||
session: ToolGatewaySession,
|
||||
connection: typeof toolConnections.$inferSelect,
|
||||
grant: typeof connectionGrants.$inferSelect,
|
||||
resolveOptions: { forceRefresh?: boolean },
|
||||
): Promise<Record<string, string>> {
|
||||
try {
|
||||
return await resolveAwsMcpAuthorization({
|
||||
minter: awsMcpMinter, connection, grant, forceRefresh: resolveOptions.forceRefresh,
|
||||
readRef: (ref) => resolveGrantSecretValue(session, connection, grant, ref),
|
||||
});
|
||||
} catch (error) {
|
||||
if (error instanceof ToolGatewayHttpError) {
|
||||
await markRemoteConnectionHealth(connection, "missing_secret", "A configured credential secret could not be resolved.");
|
||||
throw error;
|
||||
}
|
||||
const known = error instanceof AwsMcpCredentialError
|
||||
? error
|
||||
: new AwsMcpCredentialError("aws_unavailable", 503, "AWS credentials could not be prepared. Try again.", "degraded");
|
||||
await markRemoteConnectionHealth(connection, known.health, known.message);
|
||||
throw new ToolGatewayHttpError(known.status, known.message, known.code, {
|
||||
connectionId: connection.id,
|
||||
grantId: grant.id,
|
||||
...(known.awsErrorName ? { awsError: known.awsErrorName } : {}),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
function credentialVersionRefHash(value: Record<string, unknown>): string {
|
||||
return stableHash(value);
|
||||
}
|
||||
@@ -8094,6 +8140,15 @@ export function createToolGatewayService(
|
||||
responseTimeoutMs: ms,
|
||||
});
|
||||
};
|
||||
// AWS refused the minted token: drop it everywhere and rebuild this call's headers with a fresh one.
|
||||
const remintAwsCredentials = async () => {
|
||||
awsMcpMinter.evict(connection.companyId, connection.id);
|
||||
resolvedCredentials = await resolveCredentialHeaders(session, connection, grant, { forceRefresh: true });
|
||||
credentialHeaders = { ...projectedConnectionHeaders(connection), ...resolvedCredentials };
|
||||
builtHeaders = buildRemoteHeaders({ session, connection, credentialHeaders, callerHeaders });
|
||||
headers = builtHeaders.headers;
|
||||
headerSummary = builtHeaders.summary;
|
||||
};
|
||||
const requireExplicitRetryAfterOAuthRefresh = async (refreshedResponse: Response): Promise<never> => {
|
||||
// The provider rejected this dispatch, but automatic replay is unsafe:
|
||||
// a server can apply a request before returning 401. A caller retry
|
||||
@@ -8108,10 +8163,14 @@ export function createToolGatewayService(
|
||||
refreshedResponse.headers.get("x-request-id") ??
|
||||
refreshedResponse.headers.get("traceparent"),
|
||||
};
|
||||
// AWS credentials are minted, not OAuth tokens: say what actually happened.
|
||||
const minted = isAwsMcpConnection(connection);
|
||||
throw new ToolGatewayHttpError(
|
||||
409,
|
||||
"The provider rejected the saved OAuth token, which has now been refreshed. Retry the action explicitly; the original call was not replayed.",
|
||||
"oauth_refreshed_retry_required",
|
||||
minted
|
||||
? "AWS refused the saved credentials, and Paperclip has made new ones. Retry the action explicitly; the original call was not replayed."
|
||||
: "The provider rejected the saved OAuth token, which has now been refreshed. Retry the action explicitly; the original call was not replayed.",
|
||||
minted ? "credentials_refreshed_retry_required" : "oauth_refreshed_retry_required",
|
||||
{ connectionId: connection.id, catalogEntryId: entry.id, execution },
|
||||
);
|
||||
};
|
||||
@@ -8200,7 +8259,7 @@ export function createToolGatewayService(
|
||||
// declares form questions; it is kept apart from sessions that only
|
||||
// read (resources, prompts, listing), which declare none.
|
||||
const scope = `${connection.id}:grant:${grant.id}:actor:${session.agentId}:elicit-form:${endpoint}`;
|
||||
requestHeaders = await getMcpHttpSession({
|
||||
const openSession = () => getMcpHttpSession({
|
||||
scope,
|
||||
send: sendForNegotiation,
|
||||
headers,
|
||||
@@ -8208,6 +8267,15 @@ export function createToolGatewayService(
|
||||
eraKey,
|
||||
elicitationForm: true,
|
||||
});
|
||||
try {
|
||||
requestHeaders = await openSession();
|
||||
} catch (error) {
|
||||
if (!(error instanceof McpHttpInitializationError && error.status === 401 && isAwsMcpConnection(connection))) throw error;
|
||||
// AWS refused the cached token while opening the session. No tool ran,
|
||||
// so mint a fresh token and open the session once more.
|
||||
await remintAwsCredentials();
|
||||
requestHeaders = await openSession();
|
||||
}
|
||||
const sessionId = new Headers(requestHeaders).get("mcp-session-id");
|
||||
if (sessionId) mcpSession = { scope, headers, sessionId };
|
||||
const negotiated = mcpProtocolVersionOf(requestHeaders);
|
||||
@@ -8467,6 +8535,11 @@ export function createToolGatewayService(
|
||||
headerSummary = builtHeaders.summary;
|
||||
await requireExplicitRetryAfterOAuthRefresh(response);
|
||||
}
|
||||
if (response.status === 401 && isAwsMcpConnection(connection)) {
|
||||
// The cached AWS token was refused: mint a fresh one, never replay the call.
|
||||
await remintAwsCredentials();
|
||||
await requireExplicitRetryAfterOAuthRefresh(response);
|
||||
}
|
||||
if (
|
||||
response.status === 401 &&
|
||||
connection.credentialSource === "vercel_connect"
|
||||
|
||||
@@ -272,7 +272,9 @@ export function workloadIdentityService(db: Db, options: { now?: () => Date } =
|
||||
));
|
||||
if (!connection) throw notFound("Connection not found");
|
||||
// Disabling a connection must stop new cloud credentials at once.
|
||||
if (!connection.enabled || connection.status !== "active") {
|
||||
// A draft is being set up and tested; a disabled, archived or switched-off connection gets nothing.
|
||||
const usable = connection.status === "draft" || (connection.status === "active" && connection.enabled);
|
||||
if (!usable) {
|
||||
throw unprocessable("This connection is not active.", { code: "workload_identity_connection_inactive" });
|
||||
}
|
||||
|
||||
|
||||
Reference in new issue
Block a user