diff --git a/doc/connections/AWS.md b/doc/connections/AWS.md index 40adf2285d3..42a6b5951bb 100644 --- a/doc/connections/AWS.md +++ b/doc/connections/AWS.md @@ -87,31 +87,52 @@ sequenceDiagram ## Administrator setup -The role method uses three steps, because the role must trust a connection -that already exists: +The role method takes two steps, because the role must trust a connection that +already exists. The setup screen walks through them: 1. Turn on **AWS connector** in Instance Settings, Experimental. -2. **Save a draft.** Call `connectGalleryApp` with `saveDraft: true`, the role - ARN to be created, the endpoint region and the access level. Paperclip - creates the connection without contacting AWS. It also publishes the - company's issuer, so AWS can validate it in the next step. -3. In the AWS account: - - Register the issuer `https:///oidc/companies/` as an - IAM OIDC identity provider with audience `sts.amazonaws.com`. - - Create the role. Its trust policy allows - `sts:AssumeRoleWithWebIdentity` only when `:sub` equals - `connection:` and `:aud` equals `sts.amazonaws.com`. - - Attach `AWSMCPSignInOAuthAccessPolicy` and the permissions agents need. -4. **Resume** with `resumeConnectionId`. Paperclip mints a token, lists the - tools, and the connection becomes active. +2. In Connectors, open AWS. Choose the endpoint region and the access level, + then click **Connect**. There is no role ARN to enter yet: the role does not + exist until the next step creates it. +3. Paperclip saves a draft without contacting AWS and publishes the company's + issuer. The role is named after the connection (`paperclip-`), + and CloudFormation fills in the account, so nothing is typed by hand. The + screen shows one thing by default: + - **Set it up with your agent** copies a prompt for an agent (Claude Code, + Codex) on a computer signed in to the AWS account. The agent checks which + account the CLI uses, checks for an existing identity provider, deploys + the template with `aws cloudformation deploy` and reports the stack's + `RoleArn` output. For full access it asks which policy to attach. The + prompt holds no secret. + - Paste that role ARN into the field below the prompt. + + **Or do it by hand** shows the same setup without an agent: + - **With CloudFormation.** Download the template, create a stack from it in + the AWS account, set `CreateIdentityProvider` to `false` if the account + already has an identity provider for this issuer, choose `AccessPolicyArn` + for full access, and acknowledge that the stack creates IAM resources + (`CAPABILITY_NAMED_IAM`). Copy `RoleArn` from the stack's outputs. + - **In the IAM console or AWS CLI.** Add an OpenID Connect provider with the + shown provider URL and audience, then create the role with the shown trust + policy (replace `ACCOUNT_ID`), which trusts only `connection:`. Attach + `AWSMCPSignInOAuthAccessPolicy` and the agents' permissions. The CLI + commands read the account ID themselves and print the role ARN. + + If the instance's address changed after the draft was saved, the screen + shows no steps and asks you to go back and click **Connect** again, which + saves the draft with the current address. +4. Click **Test connection**. Paperclip saves the role ARN, mints a token, lists the tools and + finishes setup. If AWS refuses, the screen shows why, in place. + +The screen reads `GET /api/tool-connections/{connectionId}/aws-setup`, which +returns the issuer, audience, subject, trust policy and template, and never a +secret. AWS hosts quick-create links only for templates stored in Amazon S3, so +Paperclip offers a download instead of a hosted template. For the access-key method, create a dedicated IAM user with `AWSMCPSignInOAuthAccessPolicy`, `sts:GetFederationToken` and the agents' permissions. Then connect with the key. Setup lists the tools immediately. -A guided setup screen and a CloudFormation template are planned next. Until -then, the generic setup form and these steps apply. - **Verify:** the connection lists 8 tools. A test call of `aws___run_script` that runs `ListBuckets` succeeds. With read-only access, a `CreateBucket` call is refused by AWS with "no session policy allows". diff --git a/doc/plans/2026-11-17-aws-connector-and-minted-credentials.md b/doc/plans/2026-11-17-aws-connector-and-minted-credentials.md index 959e7525ae7..933d52cf874 100644 --- a/doc/plans/2026-11-17-aws-connector-and-minted-credentials.md +++ b/doc/plans/2026-11-17-aws-connector-and-minted-credentials.md @@ -256,7 +256,7 @@ test it. Verify it when the personal-grant method is built. | 0 | **Done 2026-11-18. Results are in "Spike findings".** Verified: AWS accepts a JWT from a tunnelled Paperclip issuer; connection isolation; the token exchange; tool listing; reads and writes through `aws___run_script`; read-only session policies through `AssumeRoleWithWebIdentity` and `GetFederationToken`; the region is passed per call; timings. Resolved: the server offers no `aws___call_aws`. **Not tested, deferred:** DCR OAuth sign-in as a person, and `AssumeRole` from an access key. | Findings recorded in this doc | | 1 | **Built.** Methods can declare `credentialMinter`. The gateway and health checks mint the `Authorization` header at call time and share one in-memory cache per connection and grant. A 401 mints again without replaying the call. AWS errors map to plain health reasons. See `doc/connections/AWS.md`. | Red/green unit and integration tests; a real-AWS run of the integrated path | | 1b | **Built** (paperclipai/paperclip#22083). Per-company workload-identity issuer (`/oidc/companies/`): signing key stored in the database, encrypted with the vault master key; discovery and JWKS routes, key rotation, JWT signing for a connection. | Red/green tests; AWS accepted its tokens in the spike and in the integrated run | -| 2 | **Partly built.** Done: the AWS minter (role and access key), the app definition behind `enableAwsConnector`, reviewed tools, artwork, and `doc/connections/AWS.md`. Setup uses save-as-draft, then resume, because the role must trust an existing connection. Saving the draft publishes the issuer. **Next:** a guided setup screen showing the issuer and subject, and the CloudFormation template. | Real-AWS run: both methods listed 8 tools; a read succeeded and AWS refused a write | +| 2 | **Built.** The AWS minter (role and access key), the app definition behind `enableAwsConnector`, reviewed tools, artwork, and `doc/connections/AWS.md` (paperclipai/paperclip#22195). A guided setup screen: save a draft, show the issuer, subject and trust policy, offer a per-connection CloudFormation template (validated by AWS), then test the same draft. | Real-AWS run: both methods listed 8 tools; a read succeeded and AWS refused a write. Browser check of the setup screen | | 3 | Paperclip Cloud staging verification. | An AWS task completed on a staging stack | | Later | Option D (sandbox credentials for Terraform/CDK). Further minters as connectors need them, such as GCP service-account impersonation or Azure client credentials. Each needs its own check of what the provider supports. | Separate plans | diff --git a/docs/api/tool-connections.md b/docs/api/tool-connections.md index c45df84c029..9e7b7d43a00 100644 --- a/docs/api/tool-connections.md +++ b/docs/api/tool-connections.md @@ -1,6 +1,6 @@ --- title: Tool Connections -summary: Remove a connection or one of its grants, and read what happened at the provider +summary: Remove a connection or one of its grants, read what happened at the provider, and read what to set up in AWS for an AWS role connection --- Removing a connection or a grant always completes in Paperclip. The response says what happened at the provider when Paperclip can ask the provider to end access. @@ -48,3 +48,52 @@ For a Google connection that Paperclip Cloud manages, the connection response ha `outcomes` has one code for each refresh token Paperclip sent, in order. The codes are for diagnosis, not for display. A failure to end access at Google does not undo the local removal. On both routes the local removal completes first, then Paperclip asks Paperclip Cloud to end access at Google, and it never retries in the request. Revoking an organization grant whose token the connection itself still uses does not end access at Google and has no `providerAccess`; removing the connection does. The activity entry for the removal records the same `providerAccess`, and the connection's audit history gets a `connection.google_access_removal` event with it. + +## AWS Role Setup + +``` +GET /api/tool-connections/{connectionId}/aws-setup +GET /api/tool-connections/{connectionId}/aws-setup?accessLevel=full +``` + +Returns what to create in AWS for an AWS role connection (`connectionMethodKey` `aws-role`): an IAM OpenID Connect identity provider for the company's issuer and a role that trusts only this connection. The setup screen reads it after saving the connection as a draft, and again on reconnect. It never contains a secret. + +The caller needs `connections:configure` for the connection. + +`accessLevel` is optional (`read_only` or `full`). It sets up for an access level that is not saved yet, such as one changed while reconnecting. Without it, the saved access level is used. For `read_only` the template's `AccessPolicyArn` defaults to `ReadOnlyAccess`; for `full` it has no default. + +When this instance can serve the role method, the `200` response is: + +```json +{ + "available": true, + "issuer": "https://paperclip.example.com/oidc/companies/", + "audience": "sts.amazonaws.com", + "subject": "connection:", + "providerHost": "paperclip.example.com/oidc/companies/", + "roleName": "paperclip-", + "savedRoleArn": null, + "accessLevel": "read_only", + "trustPolicy": { "Version": "2012-10-17", "Statement": ["..."] }, + "cloudFormationTemplate": "{ ... }", + "cloudFormationConsoleUrl": "https://console.aws.amazon.com/cloudformation/home#/stacks/create", + "issuerPublished": true +} +``` + +- `roleName` is the role the template and the agent prompt create. It is named after the connection, and CloudFormation fills in the account, so the template needs no edits. +- `savedRoleArn` is the role ARN saved on a finished connection when it is this connection's own role (`roleName`), or `null`. Drafts never keep a role ARN, and a role with any other name is not offered, because the setup steps tell an AWS administrator to update this role. +- `trustPolicy` is for setting up by hand. `ACCOUNT_ID` in it stands for the customer's AWS account ID. +- `issuerPublished` is `true` when the company's signing key is published, so AWS can validate the issuer. + +Otherwise the `200` response is `{ "available": false, "reason": "" }`: + +| `reason` | Meaning | +| --- | --- | +| `no_public_url` | The instance has no public address, so AWS cannot reach its issuer. | +| `not_https` | The instance is not served over HTTPS, which AWS requires. | +| `has_port` | The instance address includes a port, which AWS does not allow. | +| `loopback` | The instance runs on this computer only. | +| `address_changed` | The instance address changed after this draft was saved. Saving the draft again uses the current address. A finished connection is set up for the current address instead, since reconnecting records it. | + +Errors: `404` when the connection does not exist or is not accessible, and `422` with code `aws_role_setup_unavailable` when the connection does not use an AWS role. diff --git a/packages/shared/src/app-definitions.test.ts b/packages/shared/src/app-definitions.test.ts index c66ab693bd4..ff3bdaec084 100644 --- a/packages/shared/src/app-definitions.test.ts +++ b/packages/shared/src/app-definitions.test.ts @@ -1521,7 +1521,6 @@ describe("AppDefinition catalog", () => { "aws:aws-access-key:endpointRegion", "aws:aws-role:accessLevel", "aws:aws-role:endpointRegion", - "aws:aws-role:roleArn", "clickhouse:mcp-oauth:serviceId", "honcho:mcp-api-key:workspaceId", "make:mcp-api-token:zone", diff --git a/packages/shared/src/app-definitions/aws.json b/packages/shared/src/app-definitions/aws.json index 34f4845777a..f6413552f37 100644 --- a/packages/shared/src/app-definitions/aws.json +++ b/packages/shared/src/app-definitions/aws.json @@ -49,13 +49,14 @@ "key": "roleArn", "label": "Role ARN", "type": "text", - "required": true, - "placeholder": "arn:aws:iam::123456789012:role/paperclip-agents", - "helperMd": "The role must trust this company's Paperclip identity provider for this connection only. Its permissions decide what agents can do.", + "required": false, + "helperMd": "Set on the AWS setup step after the role exists. The role must trust this company's Paperclip identity provider for this connection only.", "validation": { - "pattern": "^arn:aws[a-z-]*:iam::[0-9]{12}:role/[A-Za-z0-9+=,.@_/-]{1,512}$", + "pattern": "^arn:aws[a-z-]*:iam::[0-9]{12}:role/(?:[A-Za-z0-9+=,.@_-]+/)*[A-Za-z0-9+=,.@_-]{1,64}$", "maxLength": 600 - } + }, + "hidden": true, + "defaultValue": "" }, { "key": "endpointRegion", @@ -173,7 +174,7 @@ "placeholder": "arn:aws:iam::123456789012:role/paperclip-agents", "helperMd": "Paperclip switches into this role before each session when set.", "validation": { - "pattern": "^arn:aws[a-z-]*:iam::[0-9]{12}:role/[A-Za-z0-9+=,.@_/-]{1,512}$", + "pattern": "^arn:aws[a-z-]*:iam::[0-9]{12}:role/(?:[A-Za-z0-9+=,.@_-]+/)*[A-Za-z0-9+=,.@_-]{1,64}$", "maxLength": 600 } }, diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts index 342d2c78c30..5aef054bdb1 100644 --- a/packages/shared/src/index.ts +++ b/packages/shared/src/index.ts @@ -1560,6 +1560,7 @@ export type { ConnectToolAppResult, MachineSignInPublicKey, MachineSignInStatus, + AwsConnectionSetup, MachineSignInSetupResult, ToolAppMetadataPreflightAttempt, ToolAppMetadataPreflightResult, diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts index 4a489d81995..27184a4cd8e 100644 --- a/packages/shared/src/types/index.ts +++ b/packages/shared/src/types/index.ts @@ -527,6 +527,7 @@ export type { ConnectToolAppResult, MachineSignInPublicKey, MachineSignInStatus, + AwsConnectionSetup, MachineSignInSetupResult, ToolAppMetadataPreflightAttempt, ToolAppMetadataPreflightResult, diff --git a/packages/shared/src/types/tool-access.ts b/packages/shared/src/types/tool-access.ts index 2cc8b33a474..6006d7fbd9b 100644 --- a/packages/shared/src/types/tool-access.ts +++ b/packages/shared/src/types/tool-access.ts @@ -1292,6 +1292,29 @@ export interface MachineSignInPublicKey { } /** Machine sign-in settings for one organization connection. Never includes secret or private key values. */ +/** What to configure in AWS for an AWS role connection (`GET /tool-connections/:id/aws-setup`). */ +export type AwsConnectionSetup = + /** address_changed: the instance's address differs from the one this connection was saved with. */ + | { available: false; reason: "no_public_url" | "not_https" | "has_port" | "loopback" | "address_changed" } + | { + available: true; + issuer: string; + audience: string; + subject: string; + providerHost: string; + /** The role the template and agent prompt create; named after the connection. */ + roleName: string; + /** The role ARN saved on the connection, once the customer pasted it back. */ + savedRoleArn: string | null; + /** The connection's access level; the template defaults to ReadOnlyAccess only when it is read_only. */ + accessLevel: "read_only" | "full"; + trustPolicy: Record; + cloudFormationTemplate: string; + cloudFormationConsoleUrl: string; + /** True when the company's issuer has a published key, so AWS can validate it. */ + issuerPublished: boolean; + }; + export interface MachineSignInStatus { connectionId: string; method: "paperclip_key" | "client_secret"; diff --git a/packages/shared/src/validators/tool-access.ts b/packages/shared/src/validators/tool-access.ts index e894bc2a274..0336b4b582f 100644 --- a/packages/shared/src/validators/tool-access.ts +++ b/packages/shared/src/validators/tool-access.ts @@ -1,5 +1,6 @@ import { connectionAgentInstructionsSchema } from "../connection-instructions.js"; import { isRemoteMcpConnectorMethod } from "../remote-mcp-connectors.js"; +import { APP_DEFINITIONS } from "../app-definitions.generated.js"; import { z } from "zod"; import { CONNECTION_TOKEN_ISSUANCE_PATHS, @@ -108,6 +109,13 @@ const safeKeyPattern = /^[a-z0-9][a-z0-9._:-]*$/i; const sensitiveConfigKeyPattern = /^(access[-_]?key([-_]?id)?|api[-_]?key|authorization|bearer|client[-_]?secret|credential|credentials|jwt|password|passwd|private[-_]?key|refresh[-_]?token|secret|secret[-_]?access[-_]?key|secret[-_]?key|session[-_]?token|token)$/i; +/** Minted-credential methods (AWS role) save a draft first: the provider must trust a connection that already exists. */ +function methodMintsCredentials(galleryKey: unknown, methodKey: unknown): boolean { + if (typeof galleryKey !== "string" || typeof methodKey !== "string") return false; + return Boolean(APP_DEFINITIONS.find((app) => app.slug === galleryKey)?.methods + .find((method) => method.key === methodKey)?.credentialMinter); +} + function rejectSensitiveConfigKeys(value: unknown, ctx: z.RefinementCtx, path: Array = []) { if (!value || typeof value !== "object") return; if (Array.isArray(value)) { @@ -500,8 +508,9 @@ export const connectToolAppSchema = z.object({ if ((value.grantKind === "agent") !== Boolean(value.subjectAgentId)) { ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["subjectAgentId"], message: "subjectAgentId is required exactly for an agent grant" }); } - if (value.saveDraft && !isRemoteMcpConnectorMethod(value.galleryKey, value.connectionMethodKey)) { - ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["saveDraft"], message: "Draft saving requires a remote MCP connector" }); + if (value.saveDraft && !isRemoteMcpConnectorMethod(value.galleryKey, value.connectionMethodKey) + && !methodMintsCredentials(value.galleryKey, value.connectionMethodKey)) { + ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["saveDraft"], message: "Draft saving requires a remote MCP connector or a method with minted credentials" }); } if (value.authMode && value.galleryKey && !isRemoteMcpConnectorMethod(value.galleryKey, value.connectionMethodKey)) { ctx.addIssue({ diff --git a/scripts/app-definition-overrides/aws.json b/scripts/app-definition-overrides/aws.json index 0b108bf7e0c..e6b8490797e 100644 --- a/scripts/app-definition-overrides/aws.json +++ b/scripts/app-definition-overrides/aws.json @@ -49,13 +49,14 @@ "key": "roleArn", "label": "Role ARN", "type": "text", - "required": true, - "placeholder": "arn:aws:iam::123456789012:role/paperclip-agents", - "helperMd": "The role must trust this company's Paperclip identity provider for this connection only. Its permissions decide what agents can do.", + "required": false, + "helperMd": "Set on the AWS setup step after the role exists. The role must trust this company's Paperclip identity provider for this connection only.", "validation": { - "pattern": "^arn:aws[a-z-]*:iam::[0-9]{12}:role/[A-Za-z0-9+=,.@_/-]{1,512}$", + "pattern": "^arn:aws[a-z-]*:iam::[0-9]{12}:role/(?:[A-Za-z0-9+=,.@_-]+/)*[A-Za-z0-9+=,.@_-]{1,64}$", "maxLength": 600 - } + }, + "hidden": true, + "defaultValue": "" }, { "key": "endpointRegion", @@ -172,7 +173,7 @@ "placeholder": "arn:aws:iam::123456789012:role/paperclip-agents", "helperMd": "Paperclip switches into this role before each session when set.", "validation": { - "pattern": "^arn:aws[a-z-]*:iam::[0-9]{12}:role/[A-Za-z0-9+=,.@_/-]{1,512}$", + "pattern": "^arn:aws[a-z-]*:iam::[0-9]{12}:role/(?:[A-Za-z0-9+=,.@_-]+/)*[A-Za-z0-9+=,.@_-]{1,64}$", "maxLength": 600 } }, diff --git a/server/src/__tests__/aws-mcp-connector.test.ts b/server/src/__tests__/aws-mcp-connector.test.ts index 13769874d7d..a7c565ba848 100644 --- a/server/src/__tests__/aws-mcp-connector.test.ts +++ b/server/src/__tests__/aws-mcp-connector.test.ts @@ -12,12 +12,20 @@ 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"; +import express from "express"; +import request from "supertest"; +import { toolAccessRoutes } from "../routes/tool-access.js"; +import { errorHandler } from "../middleware/error-handler.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 } }); +function asConfig(config: unknown): { methodConfig: Record } { + return config as { methodConfig: Record }; +} + describe("AWS connector with minted credentials", () => { let fixture: Awaited>; let db: ReturnType; @@ -76,6 +84,80 @@ describe("AWS connector with minted credentials", () => { return { aws, requests, rejected, service: toolAccessService(db, common), gateway: createToolGatewayService(db, { ...common, toolActionSigningSecret: "fixture-signing-key" }) }; } + it("saves a role draft through the API and returns what to configure in AWS", async () => { + await instanceSettingsService(db).updateExperimental({ enableAwsConnector: true }); + const { org } = await company(); + const app = express(); + app.use(express.json()); + app.use((req, _res, next) => { req.actor = { type: "board", userId: actor.actorId, source: "local_implicit", isInstanceAdmin: true } as Express.Request["actor"]; next(); }); + app.use("/api", toolAccessRoutes(db, { paperclipCloudConnector: null })); + app.use(errorHandler); + // The role does not exist yet, so the draft is saved without a role ARN. + const draft = await request(app).post(`/api/companies/${org.id}/tools/apps/connect`).send({ + galleryKey: "aws", connectionMethodKey: "aws-role", saveDraft: true, + configValues: { roleArn: "", endpointRegion: "us-east-1", accessLevel: "read_only" }, + }); + expect(draft.status, JSON.stringify(draft.body)).toBeLessThan(300); + const connectionId = draft.body.connectionId as string; + // The setup screen reopens a resumed draft by these stored keys. + const [stored] = await db.select().from(toolConnections).where(eq(toolConnections.id, connectionId)); + expect(stored).toMatchObject({ status: "draft", config: { sourceTemplateKey: "aws", connectionMethodKey: "aws-role" } }); + const setup = await request(app).get(`/api/tool-connections/${connectionId}/aws-setup`).expect(200); + const issuer = `https://acme.paperclip.app/oidc/companies/${org.id}`; + expect(setup.body).toMatchObject({ + available: true, issuer, audience: "sts.amazonaws.com", subject: `connection:${connectionId}`, + roleName: `paperclip-${connectionId}`, savedRoleArn: null, issuerPublished: true, + }); + const host = issuer.replace("https://", ""); + const template = JSON.parse(setup.body.cloudFormationTemplate); + const role = template.Resources.PaperclipRole.Properties; + expect(role).toMatchObject({ RoleName: `paperclip-${connectionId}` }); + expect(role.AssumeRolePolicyDocument.Statement[0].Condition.StringEquals).toEqual({ + [`${host}:aud`]: "sts.amazonaws.com", [`${host}:sub`]: `connection:${connectionId}`, + }); + expect(template.Resources.PaperclipIdentityProvider.Properties.Url).toBe(issuer); + expect(setup.body.trustPolicy.Statement[0].Principal.Federated).toBe(`arn:aws:iam::ACCOUNT_ID:oidc-provider/${host}`); + expect(JSON.stringify(setup.body)).not.toMatch(/secret|private/i); + // A reconnect may change the access level before it is saved; the guide follows the level being set up. + const full = await request(app).get(`/api/tool-connections/${connectionId}/aws-setup?accessLevel=full`).expect(200); + expect(full.body.accessLevel).toBe("full"); + expect(JSON.parse(full.body.cloudFormationTemplate).Parameters.AccessPolicyArn.Default).toBeUndefined(); + + // After the address changes, setup for the old address could never pass, so it asks for a new save, + // and saving the draft again records the current address. + vi.stubEnv("PAPERCLIP_PUBLIC_URL", "https://renamed.paperclip.app"); + try { + await request(app).get(`/api/tool-connections/${connectionId}/aws-setup`).expect(200, { available: false, reason: "address_changed" }); + await request(app).post(`/api/companies/${org.id}/tools/apps/connect`).send({ + galleryKey: "aws", connectionMethodKey: "aws-role", saveDraft: true, resumeConnectionId: connectionId, + configValues: { endpointRegion: "us-east-1", accessLevel: "read_only" }, + }).expect((res) => expect(res.status, JSON.stringify(res.body)).toBeLessThan(300)); + const resaved = await request(app).get(`/api/tool-connections/${connectionId}/aws-setup`).expect(200); + expect(resaved.body).toMatchObject({ available: true, issuer: `https://renamed.paperclip.app/oidc/companies/${org.id}` }); + } finally { + vi.stubEnv("PAPERCLIP_PUBLIC_URL", "https://acme.paperclip.app"); + } + + // A draft never keeps a role ARN AWS has not accepted: the setup steps would tell an AWS + // administrator to update that role, so any role named in a draft would be at risk. + const unchecked = await request(app).post(`/api/companies/${org.id}/tools/apps/connect`).send({ + galleryKey: "aws", connectionMethodKey: "aws-role", saveDraft: true, + configValues: { roleArn: "arn:aws:iam::123456789012:role/OrganizationAccountAccessRole", endpointRegion: "us-east-1", accessLevel: "read_only" }, + }); + expect(unchecked.status, JSON.stringify(unchecked.body)).toBeLessThan(300); + const [uncheckedRow] = await db.select().from(toolConnections).where(eq(toolConnections.id, unchecked.body.connectionId)); + expect(JSON.stringify(uncheckedRow!.config)).not.toContain("OrganizationAccountAccessRole"); + const uncheckedSetup = await request(app).get(`/api/tool-connections/${unchecked.body.connectionId}/aws-setup`).expect(200); + expect(uncheckedSetup.body.savedRoleArn).toBeNull(); + + const keyDraft = await request(app).post(`/api/companies/${org.id}/tools/apps/connect`).send({ + galleryKey: "aws", connectionMethodKey: "aws-access-key", saveDraft: true, + configValues: { endpointRegion: "us-east-1", accessLevel: "read_only" }, + credentialValues: { "credentials.accessKeyId": ACCESS_KEY_ID, "credentials.secretAccessKey": SECRET_ACCESS_KEY }, + }); + await request(app).get(`/api/tool-connections/${keyDraft.body.connectionId}/aws-setup`).expect(422); + }); + it("stays unavailable until the experimental setting is on", async () => { const { org } = await company(); const { service } = harness(); @@ -206,7 +288,10 @@ describe("AWS connector with minted credentials", () => { }; // 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); + // The role is created after the draft (it is named after it), so the draft has no role ARN yet. + const draft = await service.connectGalleryApp(org.id, { + ...roleInput, configValues: { endpointRegion: "us-east-1", accessLevel: "full" }, saveDraft: true, + }, actor); expect(draft.catalog).toEqual([]); expect(aws.assumeRoleWithWebIdentity).not.toHaveBeenCalled(); expect(await workloadIdentityService(db).publicKeySet(org.id)).not.toBeNull(); @@ -239,6 +324,20 @@ describe("AWS connector with minted credentials", () => { 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"); + // Reconnect opens the AWS step for a finished connection, set up for the current address. + await service.finishGalleryAppConnection(org.id, connected.connectionId, { + enabledCatalogEntryIds: connected.catalog.map((entry) => entry.id), askFirstCatalogEntryIds: [], access: "all_agents", + }, actor); + // Setup steps tell an administrator to update the saved role, so only the role named after this + // connection is offered: a role with any other name (in any account) could be an unrelated one. + expect(await service.getAwsSetup(org.id, connected.connectionId)).toMatchObject({ + available: true, issuer: `https://renamed.paperclip.app/oidc/companies/${org.id}`, savedRoleArn: null, + }); + const ownRole = `arn:aws:iam::123456789012:role/paperclip-${connected.connectionId}`; + const [current] = await db.select().from(toolConnections).where(eq(toolConnections.id, connected.connectionId)); + await db.update(toolConnections).set({ config: { ...current!.config, methodConfig: { ...asConfig(current!.config).methodConfig, roleArn: ownRole } } }) + .where(eq(toolConnections.id, connected.connectionId)); + expect(await service.getAwsSetup(org.id, connected.connectionId)).toMatchObject({ savedRoleArn: ownRole }); // 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); diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.ts index adb9810f31e..46a904aba4e 100644 --- a/server/src/routes/openapi.ts +++ b/server/src/routes/openapi.ts @@ -12747,6 +12747,17 @@ registerCurrentRoute({ responses: { 200: r.ok(), ...MACHINE_SIGN_IN_ERRORS }, }); +registerCurrentRoute({ + "x-paperclip-transport": "rest", + "x-paperclip-connection-management": "connections:configure", + method: "get", + path: "/api/tool-connections/{connectionId}/aws-setup", + tags: ["tool-access"], + summary: "Read what to configure in AWS for an AWS role connection", + description: "Returns the issuer, audience, connection subject, trust policy and a CloudFormation template for this connection. No secret values. Optional query `accessLevel` (`read_only` or `full`) sets up for an access level not saved yet. 422 when the connection does not use an AWS role.", + responses: { 200: r.ok(), ...MACHINE_SIGN_IN_ERRORS }, +}); + registerCurrentRoute({ "x-paperclip-transport": "rest", "x-paperclip-connection-management": "connections:configure", diff --git a/server/src/routes/tool-access.ts b/server/src/routes/tool-access.ts index a52fd32f7bb..2d8c9226772 100644 --- a/server/src/routes/tool-access.ts +++ b/server/src/routes/tool-access.ts @@ -1121,6 +1121,15 @@ function connectorEnrollmentPrincipal(req: Request): string { res.json(await svc.getMachineSignIn(existing.companyId, existing.id)); }); + router.get("/tool-connections/:connectionId/aws-setup", managementGuard("connections:configure", "GET /tool-connections/:connectionId/aws-setup"), async (req, res) => { + const existing = await getAccessibleResource(req, res, svc.getConnection(req.params.connectionId as string), "Tool connection not found"); + if (!existing) return; + await assertToolConnectionConfigureAccess(req, existing); + // The access level being set up (it may not be saved yet, as when reconnecting) decides the template's default policy. + const accessLevel = req.query.accessLevel === "full" || req.query.accessLevel === "read_only" ? req.query.accessLevel : undefined; + res.json(await svc.getAwsSetup(existing.companyId, existing.id, { accessLevel })); + }); + router.post("/tool-connections/:connectionId/machine-sign-in/test", managementGuard("connections:configure", "POST /tool-connections/:connectionId/machine-sign-in/test"), validate(testMachineSignInSchema), async (req, res) => { const existing = await getAccessibleResource(req, res, svc.getConnection(req.params.connectionId as string), "Tool connection not found"); if (!existing) return; diff --git a/server/src/services/connectors/aws/mcp-credentials.ts b/server/src/services/connectors/aws/mcp-credentials.ts index 1954e1a2ef4..bb4955c2acc 100644 --- a/server/src/services/connectors/aws/mcp-credentials.ts +++ b/server/src/services/connectors/aws/mcp-credentials.ts @@ -38,7 +38,11 @@ const SESSION_SECONDS = 3600; 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}$/; +/** + * An IAM role ARN: partition, account, optional path segments, and a role name of + * at most 64 characters. The app definition's field pattern mirrors this rule. + */ +export const AWS_ROLE_ARN_PATTERN = /^arn:(aws[a-z-]*):iam::([0-9]{12}):role\/((?:[A-Za-z0-9+=,.@_-]+\/)*)([A-Za-z0-9+=,.@_-]{1,64})$/; export type AwsMcpAccessLevel = "read_only" | "full"; @@ -117,7 +121,7 @@ export function awsMcpSettings(connection: ConnectionLike & { config: Record) { + return JSON.parse(setup.cloudFormationTemplate); +} + +describe("awsRoleSetup", () => { + it("builds a role that trusts only this connection, with the sign-in policy and a one-hour session", () => { + const setup = awsRoleSetup({ issuer: ISSUER, connectionId: "conn-1", accessLevel: "read_only" }); + expect(setup).toMatchObject({ roleName: "paperclip-conn-1", subject: "connection:conn-1", providerHost: HOST }); + const t = template(setup); + const role = t.Resources.PaperclipRole.Properties; + expect(role).toMatchObject({ RoleName: "paperclip-conn-1", MaxSessionDuration: 3600 }); + expect(role.Path).toBeUndefined(); + expect(role.ManagedPolicyArns).toEqual([ + { Ref: "AccessPolicyArn" }, + { "Fn::Sub": "arn:${AWS::Partition}:iam::aws:policy/AWSMCPSignInOAuthAccessPolicy" }, + ]); + const statement = role.AssumeRolePolicyDocument.Statement[0]; + expect(statement.Action).toBe("sts:AssumeRoleWithWebIdentity"); + expect(statement.Condition.StringEquals).toEqual({ [`${HOST}:aud`]: "sts.amazonaws.com", [`${HOST}:sub`]: "connection:conn-1" }); + // Both identity-provider branches: the one this stack creates, or an existing one in the account. + expect(statement.Principal.Federated["Fn::If"]).toEqual([ + "CreateProvider", + { "Fn::GetAtt": ["PaperclipIdentityProvider", "Arn"] }, + { "Fn::Sub": `arn:\${AWS::Partition}:iam::\${AWS::AccountId}:oidc-provider/${HOST}` }, + ]); + expect(t.Resources.PaperclipIdentityProvider).toMatchObject({ Condition: "CreateProvider", Properties: { Url: ISSUER, ClientIdList: ["sts.amazonaws.com"] } }); + // A stack update that stops creating the provider, or a stack deletion, must not remove a provider other roles trust. + expect(t.Resources.PaperclipIdentityProvider).toMatchObject({ DeletionPolicy: "Retain", UpdateReplacePolicy: "Retain" }); + expect(t.Conditions.CreateProvider).toEqual({ "Fn::Equals": [{ Ref: "CreateIdentityProvider" }, "true"] }); + expect(t.Parameters.AccessPolicyArn.Default).toBe("arn:aws:iam::aws:policy/ReadOnlyAccess"); + expect(setup.trustPolicy).toMatchObject({ Statement: [{ Principal: { Federated: `arn:aws:iam::ACCOUNT_ID:oidc-provider/${HOST}` } }] }); + }); + + it("asks for the access policy instead of defaulting to read only when the connection has full access", () => { + const t = template(awsRoleSetup({ issuer: ISSUER, connectionId: "c", accessLevel: "full" })); + expect(t.Parameters.AccessPolicyArn.Default).toBeUndefined(); + expect(t.Parameters.AccessPolicyArn.AllowedPattern).toBeTruthy(); + }); + + it("names the role after the connection, within IAM's 64 characters", () => { + const id = "26e99114-bde0-428a-944b-eee3c44366de"; + expect(awsConnectionRoleName(id)).toBe(`paperclip-${id}`); + expect(awsConnectionRoleName("x".repeat(80))).toHaveLength(64); + expect(awsConnectionRoleName("a/b c")).toBe("paperclip-a-b-c"); + }); +}); + +describe("role ARN rule", () => { + it("is the same in the app definition (what the form accepts) and on the server", () => { + const aws = APP_DEFINITIONS.find((app) => app.slug === "aws")!; + const patterns = aws.methods.flatMap((method) => [...(method.tenantFields ?? []), ...(method.extensionFields ?? [])]) + .filter((field) => field.key === "roleArn") + .map((field) => new RegExp(field.validation!.pattern!)); + expect(patterns.length).toBeGreaterThan(0); + const accepted = [ + "arn:aws:iam::123456789012:role/paperclip-agents", + "arn:aws:iam::123456789012:role/team/sub/paperclip-ops", + `arn:aws:iam::123456789012:role/${"x".repeat(64)}`, + "arn:aws-us-gov:iam::123456789012:role/ops", + ]; + const rejected = [ + `arn:aws:iam::123456789012:role/${"x".repeat(65)}`, + "arn:aws:iam::123456789012:role/team/", + "arn:azure:iam::123456789012:role/ops", + "arn:aws:iam::12345:role/ops", + "arn:aws:iam::123456789012:user/ops", + ]; + for (const arn of [...accepted, ...rejected]) { + const expected = accepted.includes(arn); + expect(AWS_ROLE_ARN_PATTERN.test(arn), arn).toBe(expected); + for (const pattern of patterns) expect(pattern.test(arn), `${pattern} ${arn}`).toBe(expected); + } + }); +}); diff --git a/server/src/services/connectors/aws/setup.ts b/server/src/services/connectors/aws/setup.ts new file mode 100644 index 00000000000..0168b6f701e --- /dev/null +++ b/server/src/services/connectors/aws/setup.ts @@ -0,0 +1,146 @@ +import { AWS_MCP_STS_AUDIENCE } from "./mcp-credentials.js"; +import { workloadIdentitySubject } from "../../workload-identity.js"; + +/** + * What a customer configures in AWS for an AWS role connection: an IAM OIDC + * identity provider for the company's issuer, and a role that trusts exactly + * this connection. Everything is generated for one connection (the role is named + * after it, and CloudFormation fills in the account), so nothing is entered by hand + * until the customer pastes back the role ARN AWS created. + */ + +const SIGN_IN_POLICY = "AWSMCPSignInOAuthAccessPolicy"; + +/** The IAM role name for a connection: unique per connection, within IAM's 64 characters. */ +export function awsConnectionRoleName(connectionId: string): string { + return `paperclip-${connectionId}`.replace(/[^A-Za-z0-9+=,.@_-]/g, "-").slice(0, 64); +} + +export interface AwsRoleSetupInput { + issuer: string; + connectionId: string; + /** Read-only connections default the template to ReadOnlyAccess; full access asks for the policy. */ + accessLevel: "read_only" | "full"; +} + +export interface AwsRoleSetup { + issuer: string; + audience: string; + subject: string; + /** The issuer without its scheme: IAM's provider URL and the prefix of the trust condition keys. */ + providerHost: string; + /** The role the template and the agent prompt create. */ + roleName: string; + accessLevel: "read_only" | "full"; + /** For setting up by hand; `ACCOUNT_ID` stands for the customer's AWS account ID. */ + trustPolicy: Record; + /** A CloudFormation template (JSON) that creates the identity provider (optional) and the role. */ + cloudFormationTemplate: string; + cloudFormationConsoleUrl: string; +} + +export function awsRoleSetup(input: AwsRoleSetupInput): AwsRoleSetup { + const roleName = awsConnectionRoleName(input.connectionId); + const providerHost = input.issuer.replace(/^https:\/\//, ""); + // The same subject the signer puts in the token, so the trust policy always matches it. + const subject = workloadIdentitySubject(input.connectionId); + const condition = { + StringEquals: { + [`${providerHost}:aud`]: AWS_MCP_STS_AUDIENCE, + [`${providerHost}:sub`]: subject, + }, + }; + const providerArn = `arn:aws:iam::ACCOUNT_ID:oidc-provider/${providerHost}`; + const trustPolicy = { + Version: "2012-10-17", + Statement: [{ + Effect: "Allow", + Principal: { Federated: providerArn }, + Action: "sts:AssumeRoleWithWebIdentity", + Condition: condition, + }], + }; + const template = { + AWSTemplateFormatVersion: "2010-09-09", + Description: `Paperclip AWS connection: an IAM role that trusts only ${subject} from ${input.issuer}.`, + Parameters: { + CreateIdentityProvider: { + Type: "String", + AllowedValues: ["true", "false"], + Default: "true", + Description: "Choose false if this account already has an IAM identity provider for this Paperclip issuer.", + }, + AccessPolicyArn: input.accessLevel === "read_only" + ? { + Type: "String", + Default: "arn:aws:iam::aws:policy/ReadOnlyAccess", + Description: "The managed policy that decides what agents can do. This connection is read only, so ReadOnlyAccess fits.", + } + : { + Type: "String", + AllowedPattern: "^arn:aws[a-z-]*:iam::(aws|[0-9]{12}):policy/.+$", + ConstraintDescription: "Enter the ARN of a managed policy.", + Description: "Required. The managed policy that decides what agents can change in this account.", + }, + }, + Conditions: { + CreateProvider: { "Fn::Equals": [{ Ref: "CreateIdentityProvider" }, "true"] }, + }, + Resources: { + PaperclipIdentityProvider: { + Type: "AWS::IAM::OIDCProvider", + Condition: "CreateProvider", + // Other connections from this company's issuer may trust the same provider, so updating + // or deleting this stack must never remove it. + DeletionPolicy: "Retain", + UpdateReplacePolicy: "Retain", + Properties: { + Url: input.issuer, + ClientIdList: [AWS_MCP_STS_AUDIENCE], + }, + }, + PaperclipRole: { + Type: "AWS::IAM::Role", + Properties: { + RoleName: roleName, + MaxSessionDuration: 3600, + AssumeRolePolicyDocument: { + Version: "2012-10-17", + Statement: [{ + Effect: "Allow", + Principal: { + Federated: { + "Fn::If": [ + "CreateProvider", + { "Fn::GetAtt": ["PaperclipIdentityProvider", "Arn"] }, + { "Fn::Sub": `arn:\${AWS::Partition}:iam::\${AWS::AccountId}:oidc-provider/${providerHost}` }, + ], + }, + }, + Action: "sts:AssumeRoleWithWebIdentity", + Condition: condition, + }], + }, + ManagedPolicyArns: [ + { Ref: "AccessPolicyArn" }, + { "Fn::Sub": `arn:\${AWS::Partition}:iam::aws:policy/${SIGN_IN_POLICY}` }, + ], + }, + }, + }, + Outputs: { + RoleArn: { Description: "Paste this into Paperclip to finish the connection.", Value: { "Fn::GetAtt": ["PaperclipRole", "Arn"] } }, + }, + }; + return { + issuer: input.issuer, + audience: AWS_MCP_STS_AUDIENCE, + subject, + providerHost, + roleName, + accessLevel: input.accessLevel, + trustPolicy, + cloudFormationTemplate: `${JSON.stringify(template, null, 2)}\n`, + cloudFormationConsoleUrl: "https://console.aws.amazon.com/cloudformation/home#/stacks/create", + }; +} diff --git a/server/src/services/tool-access.ts b/server/src/services/tool-access.ts index ec23ea31a03..702156151e1 100644 --- a/server/src/services/tool-access.ts +++ b/server/src/services/tool-access.ts @@ -1,5 +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 { AWS_MCP_ISSUER_CONFIG_KEY, AWS_ROLE_ARN_PATTERN, awsMcpMethodUsesIssuer, isAwsMcpConnection, type AwsMcpClients } from "./connectors/aws/mcp-credentials.js"; +import { awsRoleSetup } from "./connectors/aws/setup.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"; @@ -97,7 +98,7 @@ import { defaultConnectionAgentInstructions, paperclipPeerAgentInstructions, pap import { isBrowserUseConnection } from "./browser-use-client.js"; import { COGNEE_STDIO_TEMPLATE } from "./cognee-connection.js"; -import { isRemoteMcpConnectorMethod } from "@paperclipai/shared"; +import { isRemoteMcpConnectorMethod, type AwsConnectionSetup } from "@paperclipai/shared"; import { githubBotRequest } from "./chat-github-client.js"; import { syncConnectionCredentialBindings } from "./connection-credential-bindings.js"; @@ -2256,9 +2257,9 @@ 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" + // gets a clear message instead of a role refusal. Testing a draft keeps the issuer recorded at the + // draft step; saving the draft again, any other setup, or a reconnect records the current address. + const recordedAwsIssuer = !input.reconnectConnectionId && !input.saveDraft && retainedConnection?.status === "draft" ? asRecord(retainedConnection.config)[AWS_MCP_ISSUER_CONFIG_KEY] : undefined; const awsIssuerOrigin = workloadIdentityIssuerOrigin(); @@ -2271,7 +2272,11 @@ export function toolAccessService( ...(awsRoleIssuer ? { [AWS_MCP_ISSUER_CONFIG_KEY]: awsRoleIssuer } : {}), sourceTemplateKey: galleryEntry.slug, connectionMethodKey: method?.key, - methodConfig: normalizedMethodConfig?.values ?? {}, + methodConfig: input.saveDraft && awsMcpMethodUsesIssuer(galleryEntry.slug, method?.key) + // A role ARN is only kept once AWS accepted it in a test, so an unchecked ARN never reaches + // the setup steps (which tell an AWS administrator to update that role). + ? Object.fromEntries(Object.entries(normalizedMethodConfig?.values ?? {}).filter(([key]) => key !== "roleArn")) + : normalizedMethodConfig?.values ?? {}, ...(galleryEntry.slug === "google-workspace" && retainedConnection?.status === "draft" ? { workspaceSetup: retainedConnection.config.workspaceSetup } : {}), @@ -4000,6 +4005,45 @@ export function toolAccessService( return preflightConnectionMetadata(app, method, method.defaults, serverUrl, () => options.now?.() ?? new Date()); } + /** The values and template a customer needs to create an AWS role for this connection. */ + async function getAwsSetup( + companyId: string, connectionId: string, options: { accessLevel?: "read_only" | "full" } = {}, + ): Promise { + const [row] = await db.select().from(toolConnections) + .where(and(eq(toolConnections.id, connectionId), eq(toolConnections.companyId, companyId))); + if (!row) throw notFound("Tool connection not found"); + if (!isAwsMcpConnection(row) || row.config.connectionMethodKey !== "aws-role") { + throw unprocessable("This connection does not use an AWS role.", { code: "aws_role_setup_unavailable" }); + } + // Without a usable public address Paperclip cannot sign, so a recorded issuer would only look usable. + const origin = workloadIdentityIssuerOrigin(); + if (!origin.available) return { available: false, reason: origin.reason }; + const issuer = workloadIdentityIssuer(origin.origin, companyId); + // Paperclip signs only as its current address, so a draft set up for an older one could never pass + // the test: it is saved again first. Reconnecting a connection records the current address, so it + // gets setup for that address. + const recorded = row.config[AWS_MCP_ISSUER_CONFIG_KEY]; + if (row.status === "draft" && typeof recorded === "string" && recorded !== issuer) { + return { available: false, reason: "address_changed" }; + } + const methodConfig = asRecord(row.config.methodConfig); + const setup = awsRoleSetup({ + issuer, connectionId: row.id, + accessLevel: options.accessLevel ?? (methodConfig.accessLevel === "full" ? "full" : "read_only"), + }); + return { + available: true, + ...setup, + // The setup steps tell an AWS administrator to update this role, so only the role made for this + // connection (named after it, so no other role shares the name) on a finished connection is + // offered. A draft's unchecked value, or any other role, could point that update at an unrelated role. + savedRoleArn: row.status !== "draft" && typeof methodConfig.roleArn === "string" + && methodConfig.roleArn.split(":role/")[1] === setup.roleName && AWS_ROLE_ARN_PATTERN.test(methodConfig.roleArn) + ? methodConfig.roleArn : null, + issuerPublished: Boolean(await workloadIdentityService(db).publicKeySet(companyId)), + }; + } + return { /** Identity-only verification: no bot installation/repository access required. */ verifyPersonalGitHubIdentity: async (companyId: string, connectionId: string, userId: string) => { @@ -4108,6 +4152,7 @@ export function toolAccessService( rotateMachineSignIn: clientCredentials.rotateMachineSignIn, completeMachineSignInRotation: clientCredentials.completeMachineSignInRotation, getMachineSignIn: clientCredentials.getMachineSignIn, + getAwsSetup, reconnectGalleryApp: withPluginApps(reconnectGalleryApp), diff --git a/tests/runner-e2e/source-sdk-public-inputs.json b/tests/runner-e2e/source-sdk-public-inputs.json index 70e2986aa27..ba5e145aece 100644 --- a/tests/runner-e2e/source-sdk-public-inputs.json +++ b/tests/runner-e2e/source-sdk-public-inputs.json @@ -74,7 +74,7 @@ "packages/shared/src/app-definitions-url.test.ts": "56792d6745a5bc7eafc36e7403f4c9bbd671ae99", "packages/shared/src/app-definitions.generated.ts": "b162e9621fab029951d77a6b4605ab7893904a3a", "packages/shared/src/app-definitions.ingestion-report.json": "a7b60c7c16a484a411989315e9f08d48258fa647", - "packages/shared/src/app-definitions.test.ts": "c66ab693bd49ddcc8acc2c2c5049c3dacd034d36", + "packages/shared/src/app-definitions.test.ts": "ff3bdaec0840b1aff109ce0928aa3eacb4d27032", "packages/shared/src/app-definitions.ts": "f8c9c3aa66ea3bbe38c3a2eff7abca9a25911c83", "packages/shared/src/app-definitions/1password.json": "c11a4777de2c78805b2d391da5eb075a9511e0f8", "packages/shared/src/app-definitions/agentmail.json": "edd0799b1980d0f5f43b89c8f7a1173dc623f7fa", @@ -83,7 +83,7 @@ "packages/shared/src/app-definitions/api-key-generic.json": "09e6d4295513ac9f1002eaf37c34e7c2d00a3c05", "packages/shared/src/app-definitions/arcade.json": "c8379450055d4ea226d229b1cbf99c7ed2e52beb", "packages/shared/src/app-definitions/asana.json": "4cc2859043a30037fd5cdc3ebd0909938b9344a8", - "packages/shared/src/app-definitions/aws.json": "34f4845777ae61baa7fffa2e8590f4c91a72f128", + "packages/shared/src/app-definitions/aws.json": "f6413552f37f06e3b003486324c7d892d8f3e5f3", "packages/shared/src/app-definitions/bedrock.json": "962d8a722ac6e2e4db00abc34f71947a3fdb733a", "packages/shared/src/app-definitions/beehiiv.json": "47aec8fdfbf5aed0919b6ac9bddb435de4988db3", "packages/shared/src/app-definitions/bitly.json": "81f4937e92f2971f2011acb50929adf5287315e4", @@ -272,7 +272,7 @@ "packages/shared/src/home-paths.ts": "fa4f1c440653b76b3dbb7a51026d557287deb45d", "packages/shared/src/humanize-connection.test.ts": "ba9e90a44c63452b0bf9f733adb90241921e8eca", "packages/shared/src/humanize-connection.ts": "fbd414476a0ef7106a7c80d8572208781b091699", - "packages/shared/src/index.ts": "342d2c78c309f3cd61d109489351cef5928b7721", + "packages/shared/src/index.ts": "5aef054bdb11de0e9e42a2d54bdf05b3f3bd4288", "packages/shared/src/issue-activity-identity.test.ts": "3dc294640f54c2be67943e3e0149cf4eff2c95ca", "packages/shared/src/issue-activity-identity.ts": "1b0f07ec3fe0506aaaf80a4fa9893f3baf8f0075", "packages/shared/src/issue-attribution.test.ts": "84563685e7f3c48029243cf1cc24a3a09ee3cde9", @@ -429,7 +429,7 @@ "packages/shared/src/types/inbox-agent-policy.ts": "cb9d41d9681e80b834889268ad96015a39df92f6", "packages/shared/src/types/inbox-dismissal.ts": "58fb7013847396ac9971eb5799dd0bf0486e0371", "packages/shared/src/types/inbox-mine.ts": "1d302b531d34842189704abd2f75f8743d09490d", - "packages/shared/src/types/index.ts": "4a489d81995adbb8e485cf7283e23fca4b8f3ff3", + "packages/shared/src/types/index.ts": "27184a4cd8e340ac4cea30e8a16efeb125cdf1e5", "packages/shared/src/types/instance.ts": "77b0052be0f64a5531c5ebf0fd078c9854084479", "packages/shared/src/types/issue-tree-control.ts": "75489fffd491b8350b05caf57d7796419797d9df", "packages/shared/src/types/issue.ts": "2ef360b54e5e44a1c516935ab93e9029526abb40", @@ -453,7 +453,7 @@ "packages/shared/src/types/tailscale.ts": "d02a917945d7779009a2dea4c4b535e9478e0680", "packages/shared/src/types/task-workspace.ts": "a23afa13d2cb58dc2eb72692ed28c16ed6fb84fb", "packages/shared/src/types/teams-catalog.ts": "632fe75f8e5a4cfc455843c2a1a2daff28a022be", - "packages/shared/src/types/tool-access.ts": "2cc8b33a4744342ee94a5d6c8ad4289afb0455bf", + "packages/shared/src/types/tool-access.ts": "6006d7fbd9b70f69a2e4d734a384638dbdf053df", "packages/shared/src/types/user-profile.ts": "1ac26e033a79fab21dc267fd983959814c8b680f", "packages/shared/src/types/voice-sessions.ts": "95e3b62cdd51f62290e68536728ddd7297bc0459", "packages/shared/src/types/work-product.ts": "26f9129f606a207ce7a218ccef40f96747283086", @@ -544,7 +544,7 @@ "packages/shared/src/validators/teams-catalog.ts": "7bddf40c091a52aaa54e79de784bea5ae496f9aa", "packages/shared/src/validators/text.ts": "74c430fe17cdcfd4b56dd08a4c57cd3d567670a8", "packages/shared/src/validators/tool-access.test.ts": "b5838320115946a936b256919a5bd3a2294c6070", - "packages/shared/src/validators/tool-access.ts": "e894bc2a2746f8f117e7f645568ad0fb6d5e35fc", + "packages/shared/src/validators/tool-access.ts": "0336b4b582f351c6beec350fc167fa829c44bb28", "packages/shared/src/validators/trust-policy.test.ts": "1fc4818984eb0e14f034d56ad147600224496d4e", "packages/shared/src/validators/trust-policy.ts": "f16b002db940b06bd882d51df8b5712c576e1d7b", "packages/shared/src/validators/voice-sessions.ts": "018a71f9ac544645041ac3cc9919e59c95fbe998", diff --git a/ui/src/api/tools.ts b/ui/src/api/tools.ts index 309315506b3..38ec7939404 100644 --- a/ui/src/api/tools.ts +++ b/ui/src/api/tools.ts @@ -320,6 +320,10 @@ export const toolsApi = { api.post(`/companies/${companyId}/tools/apps/connect`, input), createMachineSignIn: (companyId: string, input: import("@paperclipai/shared").CreateMachineSignIn) => api.post(`/companies/${companyId}/tools/machine-sign-in`, input), + getAwsSetup: (connectionId: string, accessLevel?: "read_only" | "full") => + api.get( + `/tool-connections/${connectionId}/aws-setup${accessLevel ? `?accessLevel=${accessLevel}` : ""}`, + ), getMachineSignIn: (connectionId: string) => api.get(`/tool-connections/${connectionId}/machine-sign-in`), testMachineSignIn: (connectionId: string, input: import("@paperclipai/shared").TestMachineSignIn) => diff --git a/ui/src/features/connections/AwsRoleSetup.test.tsx b/ui/src/features/connections/AwsRoleSetup.test.tsx new file mode 100644 index 00000000000..b36cb1f7c41 --- /dev/null +++ b/ui/src/features/connections/AwsRoleSetup.test.tsx @@ -0,0 +1,182 @@ +// @vitest-environment jsdom +import { act } from "react"; +import { createRoot, type Root } from "react-dom/client"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import type { AwsConnectionSetup } from "@paperclipai/shared"; +import { AwsRoleSetup, awsAgentSetupPrompt, awsCliCommands, awsSetupErrorMessage, type AwsRoleSetupClient } from "./AwsRoleSetup"; +import { ApiError } from "@/api/client"; + +vi.mock("@/api/tools", () => ({ toolsApi: {} })); + +const READY: AwsConnectionSetup = { + available: true, + issuer: "https://acme.paperclip.app/oidc/companies/company-1", + audience: "sts.amazonaws.com", + subject: "connection:conn-1", + providerHost: "acme.paperclip.app/oidc/companies/company-1", + roleName: "paperclip-conn-1", + savedRoleArn: null, + accessLevel: "read_only", + trustPolicy: { Version: "2012-10-17", Statement: [{ Effect: "Allow", Principal: { Federated: "arn:aws:iam::ACCOUNT_ID:oidc-provider/acme.paperclip.app/oidc/companies/company-1" } }] }, + cloudFormationTemplate: "{\"Resources\":{}}\n", + cloudFormationConsoleUrl: "https://console.aws.amazon.com/cloudformation/home#/stacks/create", + issuerPublished: true, +}; +const ROLE_ARN = "arn:aws:iam::123456789012:role/paperclip-conn-1"; +type Ready = Extract; + +function setInput(input: HTMLInputElement, value: string) { + Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!.call(input, value); + input.dispatchEvent(new Event("input", { bubbles: true })); +} + +describe("AwsRoleSetup", () => { + let container: HTMLDivElement; + let root: Root; + beforeEach(() => { + (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + container = document.createElement("div"); + document.body.appendChild(container); + root = createRoot(container); + }); + afterEach(async () => { + await act(async () => root.unmount()); + container.remove(); + vi.restoreAllMocks(); + }); + + async function render(setup: AwsConnectionSetup, props: Partial[0]> = {}) { + const client: AwsRoleSetupClient = { setup: vi.fn(async () => setup) }; + const onTest = vi.fn(); + await act(async () => { + root.render(); + }); + await act(async () => { await Promise.resolve(); }); + return { client, onTest }; + } + const button = (text: string) => [...container.querySelectorAll("button")].find((b) => b.textContent?.trim() === text); + + it("shows only the agent setup by default, then tests with the pasted role ARN", async () => { + const { client, onTest } = await render(READY); + expect(client.setup).toHaveBeenCalledWith("conn-1", undefined); + expect(container.querySelector('button[aria-label="Set it up with your agent"]')).not.toBeNull(); + expect(container.textContent).toContain("Or do it by hand"); + expect(container.textContent).not.toContain("Download template"); + const test = () => button("Test connection")!; + expect(test().disabled).toBe(true); + const input = container.querySelector("#aws-role-arn")!; + await act(async () => { setInput(input, "not-an-arn"); }); + expect(container.textContent).toContain("Use the full role ARN"); + expect(test().disabled).toBe(true); + await act(async () => { setInput(input, ` ${ROLE_ARN} `); }); + expect(test().disabled).toBe(false); + await act(async () => { test().click(); }); + expect(onTest).toHaveBeenCalledWith(ROLE_ARN); + }); + + it("fills in a role ARN saved earlier", async () => { + await render({ ...READY, savedRoleArn: ROLE_ARN } as AwsConnectionSetup); + expect(container.querySelector("#aws-role-arn")!.value).toBe(ROLE_ARN); + expect(button("Test connection")?.disabled).toBe(false); + }); + + it("shows CloudFormation and IAM steps by hand, with CLI commands that read the account", async () => { + await render(READY); + await act(async () => { button("Or do it by hand")?.click(); }); + expect(container.textContent).toContain("With CloudFormation"); + expect(container.textContent).toContain("copy RoleArn from its Outputs tab"); + expect(container.textContent).toContain("replacing ACCOUNT_ID with your AWS account ID"); + const cli = container.querySelector('textarea[aria-label="AWS CLI commands"]')!.value; + expect(cli).toContain("ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)"); + expect(cli).toContain("arn:aws:iam::${ACCOUNT_ID}:oidc-provider/"); + expect(cli).toContain("--role-name paperclip-conn-1"); + expect(cli).toContain("arn:aws:iam::aws:policy/ReadOnlyAccess"); + expect(cli).toContain("aws iam get-role --role-name paperclip-conn-1 --query Role.Arn --output text"); + }); + + it("gives the user's agent a prompt that deploys this connection's template and reports the role ARN", () => { + const prompt = awsAgentSetupPrompt(READY as Ready); + expect(prompt).toContain("aws sts get-caller-identity"); + expect(prompt).toContain("--stack-name paperclip-conn-1 "); + expect(prompt).toContain("CAPABILITY_NAMED_IAM"); + expect(prompt).toContain("RoleArn output"); + expect(prompt).toContain("connection:conn-1"); + expect(prompt).toContain((READY as Ready).cloudFormationTemplate.trimEnd()); + expect(prompt).not.toContain("AccessPolicyArn="); + const full = awsAgentSetupPrompt({ ...READY, accessLevel: "full" } as Ready); + expect(full).toContain("ask me which managed policy"); + expect(full).toContain("AccessPolicyArn="); + }); + + it("updates the connection's role on reconnect, checks its account, with CLI commands that paste as is", async () => { + const setup = { ...READY, savedRoleArn: ROLE_ARN, accessLevel: "full" } as Ready; + await render(setup); + expect(container.textContent).toContain("It updates the existing role"); + await act(async () => { button("Or do it by hand")?.click(); }); + expect(container.textContent).toContain("Update the role"); + const roleRow = [...container.querySelectorAll("div")].find((d) => d.firstElementChild?.textContent === "Role name"); + expect(roleRow?.querySelector("code")?.textContent).toBe("paperclip-conn-1"); + const cli = awsCliCommands(setup); + expect(cli).toContain("if aws iam get-role --role-name paperclip-conn-1"); + expect(cli).toContain("aws iam update-assume-role-policy --role-name paperclip-conn-1"); + expect(cli).toContain("|| aws iam create-open-id-connect-provider"); + expect(cli).toContain("REPLACE_WITH_POLICY_ARN"); + expect(cli).not.toMatch(/<[^<>\n]*>/); + const prompt = awsAgentSetupPrompt(setup); + expect(prompt).toContain(`Update the AWS IAM role ${ROLE_ARN}`); + // The agent stops when the CLI is signed in to another account than the role's. + expect(prompt).toContain("The role is in account 123456789012: if the CLI uses a different account"); + expect(prompt).toContain("creates the stack, or updates it if it already exists"); + expect(prompt).toContain("If the stack paperclip-conn-1 already exists and its value is true"); + expect(prompt).toContain("keep true so the stack keeps owning its provider. Otherwise run `aws iam list-open-id-connect-providers`"); + }); + + it("asks for the access policy when the connection has full access", async () => { + await render({ ...READY, accessLevel: "full" } as AwsConnectionSetup); + await act(async () => { button("Or do it by hand")?.click(); }); + expect(container.textContent).toContain("Set AccessPolicyArn to the managed policy agents should have"); + expect(container.textContent).not.toContain("so it needs no edits"); + }); + + it("downloads the template generated for this connection", async () => { + await render(READY); + await act(async () => { button("Or do it by hand")?.click(); }); + const createObjectURL = vi.fn(() => "blob:template"); + const revokeObjectURL = vi.fn(); + Object.assign(URL, { createObjectURL, revokeObjectURL }); + let downloaded = ""; + vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(function (this: HTMLAnchorElement) { downloaded = this.download; }); + await act(async () => { [...container.querySelectorAll("button")].find((b) => b.textContent?.includes("Download template"))?.click(); }); + expect(downloaded).toBe("paperclip-aws-paperclip-conn-1.json"); + expect(createObjectURL).toHaveBeenCalledOnce(); + expect(revokeObjectURL).toHaveBeenCalledWith("blob:template"); + }); + + it("points to the access-key method when AWS cannot reach this instance", async () => { + await render({ available: false, reason: "loopback" }); + expect(container.textContent).toContain("Use an access key instead"); + expect(container.textContent).toContain("runs on this computer only"); + expect(button("Test connection")?.disabled).toBe(true); + }); + + it("shows the server's AWS message even when setup reports it with a gateway status", () => { + const message = "AWS refused this connection's role. Check that the role exists and trusts this connection."; + const awsError = new ApiError(message, 502, { error: message, code: "aws_role_access_denied", details: { code: "aws_role_access_denied" } }); + expect(awsSetupErrorMessage(awsError)).toBe(message); + const other = new ApiError("Bad Gateway", 502, { error: "upstream", details: { code: "mcp_remote_fetch_failed" } }); + expect(awsSetupErrorMessage(other)).not.toContain("upstream"); + }); + + it("explains a failed test in place", async () => { + await render(READY, { error: "AWS refused this connection's role. Check that the role exists and trusts this connection." }); + expect(container.textContent).toContain("AWS didn’t accept the connection yet"); + expect(container.textContent).toContain("AWS refused this connection's role"); + }); + + it("asks to save the connection again instead of showing steps for an old address", async () => { + await render({ available: false, reason: "address_changed" }); + expect(container.textContent).toContain("Save the connection again"); + expect(container.textContent).not.toContain("Create it with CloudFormation"); + expect(button("Test connection")?.disabled).toBe(true); + }); +}); diff --git a/ui/src/features/connections/AwsRoleSetup.tsx b/ui/src/features/connections/AwsRoleSetup.tsx new file mode 100644 index 00000000000..1b8615f5f13 --- /dev/null +++ b/ui/src/features/connections/AwsRoleSetup.tsx @@ -0,0 +1,371 @@ +import { useEffect, useState } from "react"; +import { ArrowUpRight, ChevronRight, Download, Loader2 } from "lucide-react"; +import { getAppStoreDefinition, type AwsConnectionSetup } from "@paperclipai/shared"; +import { ApiError } from "@/api/client"; +import { toolsApi } from "@/api/tools"; +import { describeError } from "@/api/errors"; +import { AgentSetupPrompt } from "@/components/AgentSetupPrompt"; +import { InlineBanner } from "@/components/InlineBanner"; +import { Button } from "@/components/ui/button"; +import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible"; +import { Input } from "@/components/ui/input"; +import { Textarea } from "@/components/ui/textarea"; +import { copyTextToClipboard } from "@/lib/clipboard"; + +/** The call this step makes. Stories and tests pass in-memory fakes. */ +export interface AwsRoleSetupClient { + setup(connectionId: string, accessLevel?: "read_only" | "full"): Promise; +} + +export const awsRoleSetupApiClient: AwsRoleSetupClient = { + setup: (connectionId, accessLevel) => toolsApi.getAwsSetup(connectionId, accessLevel), +}; + +const UNAVAILABLE_REASON: Record["reason"], string> = { + no_public_url: "This Paperclip instance has no public address, so AWS cannot reach it.", + not_https: "This Paperclip instance is not served over HTTPS, which AWS requires.", + has_port: "This Paperclip instance's address includes a port, which AWS does not allow.", + loopback: "This Paperclip instance runs on this computer only, so AWS cannot reach it.", + address_changed: "This Paperclip instance’s address changed after this connection was saved, so AWS would be set up for the old address.", +}; + +/** + * A failed AWS test, in words that say what to fix. The server's AWS messages are + * already plain language and never contain AWS's own text, so they are shown as + * is; setup reports them with a gateway status that generic copy would replace. + */ +export function awsSetupErrorMessage(error: unknown): string { + if (error instanceof ApiError && error.body && typeof error.body === "object") { + const body = error.body as { error?: unknown; details?: { code?: unknown } }; + const code = typeof body.details?.code === "string" ? body.details.code : error.code; + if (typeof code === "string" && code.startsWith("aws_") && typeof body.error === "string") return body.error; + } + return describeError(error).body; +} + +export interface AwsRoleSetupProps { + connectionId: string; + /** The access level the test will submit, when it may differ from the saved one (reconnect). */ + accessLevel?: "read_only" | "full"; + client?: AwsRoleSetupClient; + /** The last test's failure, shown in place. */ + error?: string | null; + testing?: boolean; + onBack: () => void; + /** Tests the connection with the role ARN the customer pasted back. */ + onTest: (roleArn: string) => void; + /** Shown above the footer, such as who gets access to the connection. */ + beforeFooter?: React.ReactNode; +} + +/** + * The app definition's role ARN rule (a server test keeps it equal to the server's), so this + * check matches what the server accepts. Without a definition the server alone decides. + */ +const ROLE_ARN_PATTERN = new RegExp( + getAppStoreDefinition("aws")?.methods.find((method) => method.key === "aws-role") + ?.tenantFields?.find((field) => field.key === "roleArn")?.validation?.pattern ?? "^arn:", +); + +/** + * The middle of AWS role setup: the connection is saved as a draft, so AWS can + * now trust exactly this connection. By default the customer hands a prompt to + * their own agent, which creates the role, then pastes back the role ARN; the + * CloudFormation and by-hand steps are there for anyone who prefers them. + */ +export function AwsRoleSetup({ + connectionId, + accessLevel, + client = awsRoleSetupApiClient, + error = null, + testing = false, + onBack, + onTest, + beforeFooter, +}: AwsRoleSetupProps) { + const [setup, setSetup] = useState(null); + const [loadError, setLoadError] = useState(null); + const [roleArn, setRoleArn] = useState(""); + + useEffect(() => { + let cancelled = false; + setSetup(null); + setLoadError(null); + client.setup(connectionId, accessLevel).then( + (value) => { + if (cancelled) return; + setSetup(value); + if (value.available && value.savedRoleArn) setRoleArn((current) => current || value.savedRoleArn!); + }, + (caught) => { if (!cancelled) setLoadError(describeError(caught).body); }, + ); + return () => { cancelled = true; }; + }, [client, connectionId, accessLevel]); + + const ready = setup?.available === true ? setup : null; + const trimmedArn = roleArn.trim(); + const arnInvalid = trimmedArn.length > 0 && !ROLE_ARN_PATTERN.test(trimmedArn); + + return ( +
+

+ Paperclip saved this connection. Now create a role in your AWS account that trusts this connection only. + Paperclip stores no AWS keys: it proves who it is each time it needs access. +

+ + {error ? {error} : null} + {loadError ? {loadError} : null} + {setup?.available === false ? ( + setup.reason === "address_changed" ? ( + + {UNAVAILABLE_REASON[setup.reason]} Go back and click Connect to use the current address. + + ) : ( + + {UNAVAILABLE_REASON[setup.reason]} Go back and choose Access key. + + ) + ) : null} + + {!setup && !loadError ? ( +

+ Preparing the AWS setup… +

+ ) : null} + + {ready ? ( + <> +
    +
  1. + Give this prompt to an agent on a computer signed in to your AWS account.{" "} + {ready.savedRoleArn + ? "It updates the existing role with the AWS CLI and tells you the role ARN." + : "It creates the role with the AWS CLI and tells you the role ARN."} +
    + +
    +
  2. +
  3. + + setRoleArn(event.target.value)} + placeholder={`arn:aws:iam:::role/${ready.roleName}`} + aria-invalid={arnInvalid || undefined} + className="font-mono text-base md:text-xs" + autoComplete="off" + spellCheck={false} + /> + {arnInvalid ? ( +

    Use the full role ARN, like arn:aws:iam::123456789012:role/{ready.roleName}.

    + ) : null} +
  4. +
+ + + + + Or do it by hand + + +
+

With CloudFormation

+
    +
  1. + Download the template.{" "} + {ready.accessLevel === "read_only" + ? "It is made for this connection, so it needs no edits." + : "It is made for this connection; it only needs the access policy you choose in step 3."} +
    + +
    +
  2. +
  3. + + Open CloudFormation + {" "} + in the AWS account agents should use, create a stack, choose Upload a template file, and select the downloaded file. +
  4. +
  5. + {ready.accessLevel === "read_only" + ? "Keep the defaults: AccessPolicyArn is ReadOnlyAccess, matching this read-only connection." + : "Set AccessPolicyArn to the managed policy agents should have. This connection has full access, so there is no default."}{" "} + If this AWS account already has an identity provider for this Paperclip address, set + CreateIdentityProvider to false. On the last page, tick the box that acknowledges the stack creates IAM + resources. +
  6. +
  7. + When the stack finishes, copy RoleArn from its Outputs tab into the field above. If this role came from + this template before, update that stack ({ready.roleName}) + with the new template instead of creating another. +
  8. +
+
+ +
+

In the IAM console or AWS CLI

+
    +
  1. Add an OpenID Connect identity provider with the provider URL and audience below, unless the account already has one for it.
  2. +
  3. + {ready.savedRoleArn ? "Update the role " : "Create the role "} + {ready.savedRoleArn ?? ready.roleName}{" "} + {ready.savedRoleArn ? "so its trust policy is the one below" : "with the trust policy below"}, replacing + ACCOUNT_ID with your AWS account ID. The CLI commands do either. +
  4. +
  5. Attach AWSMCPSignInOAuthAccessPolicy and the permissions agents should have, then paste the role ARN above.
  6. +
+ + + + + + +
+
+
+ + ) : null} + + {beforeFooter} + +
+ + +
+
+ ); +} + +/** + * The by-hand setup for the AWS CLI. It reads the account ID, reuses an existing identity + * provider, and updates the role when it already exists (as on reconnect), so it can be pasted as is. + */ +export function awsCliCommands(setup: Extract): string { + const { roleName } = setup; + const policy = JSON.stringify(setup.trustPolicy, null, 2).replaceAll("ACCOUNT_ID", "${ACCOUNT_ID}"); + const accessPolicy = setup.accessLevel === "read_only" ? "arn:aws:iam::aws:policy/ReadOnlyAccess" : "REPLACE_WITH_POLICY_ARN"; + return [ + ...(setup.accessLevel === "read_only" ? [] : ["# Replace REPLACE_WITH_POLICY_ARN below with the managed policy agents should have."]), + "ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)", + `aws iam get-open-id-connect-provider --open-id-connect-provider-arn "arn:aws:iam::\${ACCOUNT_ID}:oidc-provider/${setup.providerHost}" >/dev/null 2>&1 \\`, + ` || aws iam create-open-id-connect-provider --url ${setup.issuer} --client-id-list ${setup.audience}`, + "cat > paperclip-trust-policy.json </dev/null 2>&1; then`, + ` aws iam update-assume-role-policy --role-name ${roleName} --policy-document file://paperclip-trust-policy.json`, + "else", + ` aws iam create-role --role-name ${roleName} --max-session-duration 3600 --assume-role-policy-document file://paperclip-trust-policy.json`, + "fi", + `aws iam attach-role-policy --role-name ${roleName} --policy-arn arn:aws:iam::aws:policy/AWSMCPSignInOAuthAccessPolicy`, + `aws iam attach-role-policy --role-name ${roleName} --policy-arn ${accessPolicy}`, + `aws iam get-role --role-name ${roleName} --query Role.Arn --output text`, + ].join("\n"); +} + +/** + * A prompt for the user's own agent (on a machine already signed in to AWS) to + * deploy this connection's template and report the role ARN. It holds no + * secrets: AWS trusts the connection's signed identity, so it is safe to paste anywhere. + */ +export function awsAgentSetupPrompt(setup: Extract): string { + // One stack per connection, like the role, so two connections never share (and replace) a stack. + const stack = setup.roleName; + const policyStep = setup.accessLevel === "read_only" + ? "The connection is read only, so keep the template's default AccessPolicyArn (ReadOnlyAccess)." + : "The connection has full access, so ask me which managed policy agents should have, then pass it as AccessPolicyArn. Do not pick one yourself."; + return [ + setup.savedRoleArn + ? `Update the AWS IAM role ${setup.savedRoleArn} so Paperclip can connect to my AWS account again. Use the AWS CLI on this computer.` + : "Set up an AWS IAM role so Paperclip can connect to my AWS account. Use the AWS CLI on this computer.", + "", + "Steps:", + setup.savedRoleArn + ? `1. Run \`aws sts get-caller-identity\` and tell me which account and identity it shows. The role is in account ${setup.savedRoleArn.split(":")[4]}: if the CLI uses a different account, or is not signed in, stop and ask me which profile to use.` + : "1. Run `aws sts get-caller-identity` and tell me which account and identity it shows. If the CLI is not signed in, or I may want a different account, stop and ask me which profile to use.", + `2. Choose CreateIdentityProvider. If the stack ${stack} already exists and its value is true (see \`aws cloudformation describe-stacks --stack-name ${stack}\`), keep true so the stack keeps owning its provider. Otherwise run \`aws iam list-open-id-connect-providers\`: if one already ends with ${setup.providerHost}, pass false; otherwise pass true.`, + `3. ${policyStep}`, + "4. Save the CloudFormation template below to a file and deploy it. This creates the stack, or updates it if it already exists:", + ` aws cloudformation deploy --stack-name ${stack} --template-file --capabilities CAPABILITY_NAMED_IAM --parameter-overrides CreateIdentityProvider=${setup.accessLevel === "full" ? " AccessPolicyArn=" : ""}`, + ` If it fails because the role ${setup.roleName} already exists outside this stack, do not delete it. Instead update its trust policy with \`aws iam update-assume-role-policy\` to the trust policy in the template (with this account's ID and the identity provider's ARN), make sure AWSMCPSignInOAuthAccessPolicy and the access policy are attached, and use that role's ARN in step 5.`, + `5. Give me the role's ARN (the stack's RoleArn output, or \`aws iam get-role --role-name ${setup.roleName} --query Role.Arn --output text\`), so I can paste it into Paperclip and press Test connection.`, + "", + "The role trusts only this one Paperclip connection, and no AWS keys are created or shared:", + `- Identity provider: ${setup.issuer} (audience ${setup.audience})`, + `- Connection subject: ${setup.subject}`, + `- Role name: ${setup.roleName}`, + "", + "CloudFormation template:", + setup.cloudFormationTemplate.trimEnd(), + ].join("\n"); +} + +function downloadTemplate(setup: Extract) { + const blob = new Blob([setup.cloudFormationTemplate], { type: "application/json" }); + const url = URL.createObjectURL(blob); + const link = document.createElement("a"); + link.href = url; + link.download = `paperclip-aws-${setup.roleName}.json`; + document.body.appendChild(link); + link.click(); + link.remove(); + URL.revokeObjectURL(url); +} + +function CopyButton({ value, label }: { value: string; label: string }) { + const [copied, setCopied] = useState(false); + return ( + + ); +} + +function CopyRow({ label, value }: { label: string; value: string }) { + return ( +
+ {label} +
+ {value} + +
+
+ ); +} + +function CopyBlock({ label, value }: { label: string; value: string }) { + return ( +
+
+ {label} + +
+