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:
authored and GitHub committed 2026-11-18 12:48:49 -06:00
1 parent 8285a81280
commit 651749bdb4
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 () => {
+1
View File
@@ -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);
},
});
}
+2
View File
@@ -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,
+23 -2
View File
@@ -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 (
+76 -3
View File
@@ -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"
+3 -1
View File
@@ -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" });
}