Files
PaperClipAI/server/src/services/tool-access/credential-access.ts
T
651749bdb4 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>
2026-11-18 12:48:49 -06:00

372 lines
15 KiB
TypeScript

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";
import { and, eq } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import { connectionGrants, toolConnections } from "@paperclipai/db";
import { badRequest, HttpError, unprocessable } from "../../errors.js";
import { parseRemoteHttpEndpoint } from "../remote-http-endpoint-guard.js";
import { REMOTE_URL_SECRET_CONFIG_PATH, remoteUrlCredentialMatchesPublicUrl } from "../remote-url-credentials.js";
import { secretService } from "../secrets.js";
import { connectionCredentialConfigPath as credentialRefConfigPath, connectionGrantCredentialRef } from "../connection-credentials.js";
import type { ToolAccessAudit } from "./audit.js";
import type { VercelCredentialService } from "./vercel-credentials.js";
import type { OAuthCredentialStore } from "./oauth/credential-store.js";
import type { createLegacyOAuthRefresh } from "./oauth/connection-refresh.js";
import type { createOAuthGrantRefresh } from "./oauth/grant-refresh.js";
import { credentialScope } from "./oauth/client-settings.js";
import { connectionSetupUrl, connectionReconnectUrl } from "./identifiers.js";
function asRecord(value: unknown): Record<string, unknown> {
if (value && typeof value === "object" && !Array.isArray(value))
return value as Record<string, unknown>;
return {};
}
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"];
maybeRefreshOAuthCredentials: ReturnType<typeof createLegacyOAuthRefresh>;
refreshOAuthGrantCredentials: ReturnType<typeof createOAuthGrantRefresh>;
};
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,
actor?: ActorInfo,
): Promise<typeof connectionGrants.$inferSelect | null> {
if (connection.credentialPolicy === "per_agent") {
const agentId = actor?.actorType === "agent" ? actor.actorId : null;
if (actor?.actorType === "agent" && !agentId) {
throw unprocessable("This connection needs the agent's authorization", {
code: "agent_authorization_required",
});
}
// Discovery has no run identity in background/operator work. Use only
// an unambiguous active agent grant; an agent caller must use its own.
const grants = await db.select().from(connectionGrants).where(and(
eq(connectionGrants.companyId, connection.companyId),
eq(connectionGrants.connectionId, connection.id),
eq(connectionGrants.kind, "agent"),
eq(connectionGrants.status, "active"),
...(agentId ? [eq(connectionGrants.subjectAgentId, agentId)] : []),
)).limit(2);
if (grants.length !== 1) {
throw unprocessable(grants.length > 1
? "This connection has multiple agent accounts. Use a separate connection for each agent."
: "This connection needs the agent's authorization", {
code: grants.length > 1 ? "agent_authorization_ambiguous" : "agent_authorization_required",
setupUrl: connectionSetupUrl(connection),
reconnectUrl: connectionReconnectUrl(connection),
});
}
return grants[0]!;
}
const actorUserId =
connectionActorUserId(actor);
if (actorUserId) {
const [personal] = await db
.select()
.from(connectionGrants)
.where(
and(
eq(connectionGrants.companyId, connection.companyId),
eq(connectionGrants.connectionId, connection.id),
eq(connectionGrants.kind, "user"),
eq(connectionGrants.subjectUserId, actorUserId),
),
)
.limit(1);
if (personal) {
if (personal.status !== "active") {
throw unprocessable("OAuth authorization must be reconnected", {
code: "oauth_reauthorization_required",
setupUrl: connectionSetupUrl(connection),
reconnectUrl: connectionReconnectUrl(connection),
});
}
return personal;
}
}
if (!actorUserId && connection.credentialPolicy === "per_user") {
// A personal-only connection is intentionally fixed to one identity.
// Background health/catalog checks have no acting user, but may safely
// exercise that sole owner-bound grant without turning it into a shared
// credential or making it available to a different caller.
const personalGrants = await db
.select()
.from(connectionGrants)
.where(
and(
eq(connectionGrants.companyId, connection.companyId),
eq(connectionGrants.connectionId, connection.id),
eq(connectionGrants.kind, "user"),
eq(connectionGrants.status, "active"),
),
)
.limit(2);
if (personalGrants.length === 1) return personalGrants[0]!;
}
if (connection.credentialPolicy === "per_user") {
throw unprocessable(
"This connection needs the current user's authorization",
{
code: "user_authorization_required",
setupUrl: connectionSetupUrl(connection),
reconnectUrl: connectionReconnectUrl(connection),
},
);
}
const [organization] = 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),
),
)
.limit(1);
if (organization?.status === "active") return organization;
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,
options: { forceRefresh?: boolean } = {},
): Promise<Record<string, string>> {
if (connection.credentialSource === "vercel_connect") {
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 (
connection.authKind === "oauth" ||
connection.credentialPolicy !== "shared"
) {
grant = await vaultGrantForConnection(connection, actor);
}
if (connection.authKind === "oauth" && grant) {
grant = await refreshOAuthGrantCredentials({
companyId: connection.companyId,
connectionId: connection.id,
grantId: grant.id,
forceRefresh: options.forceRefresh,
actor,
});
} else {
connection = await maybeRefreshOAuthCredentials(connection, actor);
}
} catch (error) {
const scope = credentialScope(connection);
await audit({
companyId: connection.companyId,
connectionId: connection.id,
action: "tool_connection.credential_resolution",
outcome: "failure",
reasonCode:
error instanceof HttpError
? String(asRecord(error.details).code ?? "oauth_refresh_failed")
: "oauth_refresh_failed",
details: {
credentialCount: connection.credentialRefs.length,
credentialSecretRefCount: connection.credentialSecretRefs.length,
credentialScopeType: scope.type,
credentialScopeHash: scope.hash,
setupUrl: connectionSetupUrl(connection),
reconnectUrl: connectionReconnectUrl(connection),
},
});
throw error;
}
const headers: Record<string, string> = {};
const scope = credentialScope(connection);
for (const ref of connection.credentialRefs) {
if (ref.placement !== "header") continue;
let value: string;
const configPath = credentialRefConfigPath(ref);
try {
const grantRef = grant ? connectionGrantCredentialRef(grant, ref) : undefined;
if (grant && !grantRef) throw unprocessable("Your credential is missing. Reconnect this connection.", {
code: "grant_credential_invalid", connectionId: connection.id, grantId: grant.id, credential: configPath,
});
value =
grantRef && grant
? (
await resolveOAuthGrantSecret(
connection,
grant,
grantRef,
actor,
undefined,
)
).value
: await secrets.resolveSecretValue(
connection.companyId,
ref.secretId,
ref.version ?? "latest",
{
consumerType: "tool_connection",
consumerId: connection.id,
configPath,
actorType: "system",
},
);
} catch (error) {
await audit({
companyId: connection.companyId,
connectionId: connection.id,
action: "tool_connection.credential_resolution",
outcome: "failure",
reasonCode:
error instanceof HttpError
? String(
asRecord(error.details).code ?? "secret_resolution_failed",
)
: "secret_resolution_failed",
details: {
credentialCount: connection.credentialRefs.length,
credentialScopeType: scope.type,
credentialScopeHash: scope.hash,
},
});
throw error;
}
if (ref.placement === "header") {
headers[ref.key] = `${ref.prefix ?? ""}${value}`;
}
}
const oauthAccessRef = grant?.credentialSecretRefs.find(
(ref) => ref.configPath === "oauth.access_token",
);
if (oauthAccessRef && headers.Authorization === undefined) {
headers.Authorization = `Bearer ${
(
await resolveOAuthGrantSecret(
connection,
grant!,
oauthAccessRef,
actor,
undefined,
)
).value
}`;
}
if (
connection.credentialRefs.length > 0 ||
connection.credentialSecretRefs.length > 0 ||
Object.keys(oauthConfig(connection)).length > 0
) {
await audit({
companyId: connection.companyId,
connectionId: connection.id,
action: "tool_connection.credential_resolution",
outcome: "success",
details: {
credentialCount: connection.credentialRefs.length,
credentialSecretRefCount: connection.credentialSecretRefs.length,
credentialScopeType: scope.type,
credentialScopeHash: scope.hash,
},
});
}
return headers;
}
async function resolvedRemoteEndpoint(
connection: typeof toolConnections.$inferSelect,
actor?: ActorInfo,
): Promise<string> {
const publicEndpoint = remoteEndpoint(connection.config);
const ref = connection.credentialRefs.find(
(candidate) => candidate.placement === "url",
);
if (!ref) return publicEndpoint;
let value: string;
try {
const grant = await vaultGrantForConnection(connection, actor);
const grantRef = grant ? connectionGrantCredentialRef(grant, ref) : undefined;
if (grant && !grantRef) throw unprocessable("Your MCP URL credential is missing. Reconnect this connection.", {
code: "grant_credential_invalid", connectionId: connection.id, grantId: grant.id,
});
value = grant && grantRef
? (await resolveOAuthGrantSecret(connection, grant, grantRef, actor, undefined)).value
: await secrets.resolveSecretValue(connection.companyId, ref.secretId, ref.version ?? "latest", {
consumerType: "tool_connection", consumerId: connection.id,
configPath: REMOTE_URL_SECRET_CONFIG_PATH,
actorType: actor?.actorType ?? "system", actorId: actor?.actorId ?? null,
});
} catch (error) {
if (error instanceof HttpError) throw error;
throw unprocessable("Your MCP URL credential could not be resolved. Reconnect this connection.", {
code: "mcp_remote_missing_secret", connectionId: connection.id, credential: REMOTE_URL_SECRET_CONFIG_PATH,
});
}
if (!remoteUrlCredentialMatchesPublicUrl(publicEndpoint, value)) {
throw unprocessable(
"The stored MCP URL credential no longer matches this connection.",
{
code: "mcp_remote_url_credential_mismatch",
connectionId: connection.id,
},
);
}
return parseRemoteHttpEndpoint(value, (message, code) =>
badRequest(message, { code }),
).toString();
}
return { vaultGrantForConnection, resolveCredentialHeaders, resolvedRemoteEndpoint };
}
export type ConnectionCredentialAccess = ReturnType<typeof createConnectionCredentialAccess>;