From f6c5986b6112951369fd9e3d688bac4b50abf2f7 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 13 Nov 2026 21:10:32 -0600 Subject: [PATCH] feat(connections): machine sign-in (MCP OAuth client credentials) for organization connections (#21473) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents use apps through connections to remote MCP servers > - Today an organization connection must sign in as a person (browser sign-in) or use a static key > - Service accounts and CI-style integrations have no person who can sign in > - The MCP OAuth Client Credentials extension (2026-07-28) defines machine-to-machine sign-in for this case > - This pull request adds "Machine sign-in" for organization connections, with a Paperclip-held signing key (recommended) or a client secret > - The benefit is that organizations can connect automation-owned MCP servers safely, with credentials only in the vault and bound to one sign-in service ## Linked Issues or Issue Description **Subsystem affected** Connections: remote MCP OAuth (server `tool-access/oauth`, tool gateway token refresh) and the custom MCP server setup flow in the UI. **Problem or motivation** Organization-owned automation (service accounts, CI integrations) cannot connect an MCP server that requires OAuth, because no person can complete a browser sign-in. The MCP OAuth Client Credentials extension (`io.modelcontextprotocol/oauth-client-credentials`) solves this with `grant_type=client_credentials` and RFC 7523 signed client assertions. **Proposed solution** Add machine sign-in for organization connections only. Paperclip creates a keypair per connection, keeps the private key in the company vault, and shows the public key (PEM and JWK) for the admin to register. A client secret is also supported. The sign-in service (issuer and token endpoint) is pinned at setup. Tokens use the existing organization grant refresh path, so caching, concurrent dedupe and 401 re-request reuse the existing lease and single flight. **Alternatives considered** Reuse the deployment-wide `PAPERCLIP_TOOL_OAUTH_*` client env path that already sent `client_credentials`. Rejected: it is not per connection, it keeps secrets in env, and it has no issuer pin. Route machine sign-in through `connectGalleryApp`. Rejected: its rollback deletes the draft on a failed test, which would lose a key the admin already registered. **Roadmap alignment** Phase 1 of the enterprise MCP plan (no enterprise single sign-on needed). OIDC login and enterprise-managed authorization (ID-JAG) are later phases. ## What Changed - `oauth/client-credentials.ts`: keypair generation (RS256, or ES256 when the service requires it), RFC 7638 key IDs, and RFC 7523 assertions (`iss` = `sub` = client ID, `aud` = token endpoint, 60 s `exp`, unique `jti`) with Node `crypto` only. - `oauth/client.ts`: the token exchange accepts a signed assertion and then sends only `client_assertion_type` and `client_assertion` (no `client_id` or secret), as the extension specifies. - `oauth/client-credentials-service.ts`: discovery of the sign-in service (protected-resource metadata, then RFC 8414/OIDC metadata with issuer check, or a token URL entered directly), issuer pinning, vault-only key and secret handling, draft creation, test-and-activate, and no-downtime rotation (test the new secret first; stage a new key and switch only after the provider accepts it). - `oauth/grant-refresh.ts` and `oauth/connection-refresh.ts`: machine sign-in requests a new access token with the connection's own credentials instead of needing a refresh token. It never falls back to deployment-wide OAuth clients. - `catalog/discovery.ts`: a rejected token on a machine sign-in connection never re-runs discovery or rewrites the pinned endpoints. - `mcp-http.ts` and the tool gateway: declare `io.modelcontextprotocol/oauth-client-credentials` in client capabilities only for connections that use it. - Routes (with OpenAPI and activity logging): `POST /companies/{companyId}/tools/machine-sign-in`, `GET|POST /tool-connections/{id}/machine-sign-in[/test|/rotate|/rotate/complete]`. Removal activity now records `machineSignIn: true`. The runner API treats these routes as sensitive. - Shared validators and types for machine sign-in. - UI: "Machine sign-in" under Advanced authentication in the custom MCP server flow (organization connections only), `MachineSignInSetup` (choose Paperclip key or client secret, register the public key, test), and Storybook stories for each setup state. - Docs: `doc/connections/MCP-CLIENT-CREDENTIALS.md`, linked from `doc/connections/README.md` and `GENERIC-REMOTE-MCP.md`. ## Verification - `server/src/__tests__/tool-access-client-credentials.test.ts`: 16/16 pass. It uses a fake sign-in service that verifies real signatures against registered keys, and a fake MCP server. It covers RS256 and ES256 assertion claims and signatures, assertion-only client authentication, the secret flow (`client_secret_basic`), discovery and direct token URL, issuer pinning (refuses a different sign-in service and sends it nothing), the pinned endpoint surviving a hostile challenge, the token cache (0 token requests while live), concurrent dedupe (5 callers on 2 service instances produce 1 token request), 401 re-request, key and secret rotation, a refused personal connection, secret redaction in responses, rows and activity, and vault cleanup on removal. - Red/green: with the grant-refresh machine sign-in branch and the discovery pin guard disabled, 5 runtime tests fail (pin, cache/dedupe, 401 re-request, both rotations). Restored: 16/16 pass. The other tests cover new routes and services that do not exist on `master`. - `ui/src/features/connections/MachineSignInSetup.test.tsx`: 3/3. `ConnectionSetupFlow.architecture` and `.oauth` tests: 19/19. - `openapi-routes.test.ts`: 51/51. `runner-api.test.ts`: 2153/2153. `mcp-http.test.ts`: 9/9. Existing `tool-access-service.test.ts` refresh and legacy client-credentials tests: 54/54 (filtered). - Server package `tsc --noEmit`: clean. UI `tsc`: clean except the pre-existing generated Storybook catalog imports. - Not run locally (machine under heavy load): full suites, repo-wide typecheck, browser check of the live app. CI covers breadth. ## Risks - No migration. New config lives in `config.oauth` (`grantType: "client_credentials"` plus `clientAuth`). Older env-configured client-credentials connections have no `clientAuth` and keep their original path. - The capability declaration adds one extension key only for machine sign-in connections. Other requests are unchanged. - Rotation has no settings-page control yet; it is available through the API. This is a follow-up. - Low risk to agent boot and time to first token: a live token is read exactly like a browser sign-in token. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with tool use (shell, file edits, test runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] 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 --- doc/connections/GENERIC-REMOTE-MCP.md | 6 +- doc/connections/MCP-CLIENT-CREDENTIALS.md | 129 +++ doc/connections/README.md | 9 +- packages/shared/src/index.ts | 12 + packages/shared/src/types/index.ts | 3 + packages/shared/src/types/tool-access.ts | 33 + packages/shared/src/validators/index.ts | 9 + packages/shared/src/validators/tool-access.ts | 39 + .../tool-access-client-credentials.test.ts | 682 ++++++++++++++++ server/src/routes/openapi.ts | 65 ++ server/src/routes/tool-access.ts | 106 ++- server/src/services/mcp-http.ts | 10 +- .../runner-api-sensitive-response.ts | 2 +- server/src/services/tool-access.ts | 24 +- .../services/tool-access/catalog/discovery.ts | 19 +- .../oauth/client-credentials-service.ts | 753 ++++++++++++++++++ .../tool-access/oauth/client-credentials.ts | 188 +++++ .../src/services/tool-access/oauth/client.ts | 19 +- .../tool-access/oauth/connection-refresh.ts | 17 +- .../tool-access/oauth/grant-refresh.ts | 42 +- server/src/services/tool-gateway.ts | 2 + .../runner-e2e/source-sdk-public-inputs.json | 10 +- ui/src/api/tools.ts | 10 + .../connections/ConnectionSetupFlow.tsx | 24 +- .../GenericMcpConnectStep.machine.test.tsx | 69 ++ .../connections/GenericMcpConnectStep.tsx | 83 +- .../connections/MachineSignInSetup.test.tsx | 137 ++++ .../connections/MachineSignInSetup.tsx | 324 ++++++++ .../machine-sign-in.stories.tsx | 102 +++ 29 files changed, 2861 insertions(+), 67 deletions(-) create mode 100644 doc/connections/MCP-CLIENT-CREDENTIALS.md create mode 100644 server/src/__tests__/tool-access-client-credentials.test.ts create mode 100644 server/src/services/tool-access/oauth/client-credentials-service.ts create mode 100644 server/src/services/tool-access/oauth/client-credentials.ts create mode 100644 ui/src/features/connections/GenericMcpConnectStep.machine.test.tsx create mode 100644 ui/src/features/connections/MachineSignInSetup.test.tsx create mode 100644 ui/src/features/connections/MachineSignInSetup.tsx create mode 100644 ui/storybook/stories/connection-setup/machine-sign-in.stories.tsx diff --git a/doc/connections/GENERIC-REMOTE-MCP.md b/doc/connections/GENERIC-REMOTE-MCP.md index 026eab63090..91a4ee3fd90 100644 --- a/doc/connections/GENERIC-REMOTE-MCP.md +++ b/doc/connections/GENERIC-REMOTE-MCP.md @@ -91,7 +91,7 @@ this as a setup error and keeps the connection available for retry. See The connect screen states the sign-in choice in one line, **Paperclip asks the server how to sign in.**, with a **Change** link, the same shape as the access -line below it. **Change** lists five options, each with its fields directly +line below it. **Change** lists five options (six for organization connections), each with its fields directly beneath it when selected: - **Let Paperclip check** — the default; Paperclip probes and walks you through it. @@ -101,6 +101,10 @@ beneath it when selected: Paperclip first. - **Custom headers** — for servers that name their own headers. - **No sign-in needed** — the server is open to anyone with the address. +- **Machine sign-in** — organization connections only. Paperclip signs in as a + client you registered with the provider, using a Paperclip key or a client + secret, with no person involved. It runs its own setup and test in place of + **Check link**. See [Machine sign-in](./MCP-CLIENT-CREDENTIALS.md). **Done** collapses the list back to a one-line summary of the choice. It stays open while the chosen option still needs a value. diff --git a/doc/connections/MCP-CLIENT-CREDENTIALS.md b/doc/connections/MCP-CLIENT-CREDENTIALS.md new file mode 100644 index 00000000000..8fcfada8748 --- /dev/null +++ b/doc/connections/MCP-CLIENT-CREDENTIALS.md @@ -0,0 +1,129 @@ +# Machine sign-in (MCP OAuth client credentials) + +Machine sign-in connects an **organization-owned** remote MCP server where no +person signs in: service accounts, CI-style integrations, internal automation. +Paperclip signs in as a client the provider registered for it, using the +[MCP OAuth Client Credentials extension](https://modelcontextprotocol.io/extensions/auth/oauth-client-credentials) +(`io.modelcontextprotocol/oauth-client-credentials`, revision 2026-07-28), +which builds on [RFC 6749 §4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) +and [RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523). + +It works the same on Paperclip Cloud and self-hosted instances. + +## Setting it up + +**Apps → Connect an app → Connect your own MCP server**, paste the address, +press **Change** beside the sign-in line and choose **Machine sign-in**. The option +appears only when the connection is shared with the organization; personal +connections sign in as the person. + +1. **Sign-in service.** Leave it blank and Paperclip asks the server where it + signs in (its protected-resource metadata, then that service's metadata). + Otherwise enter the sign-in service's address, or its token URL when the + provider publishes no metadata. +2. **How Paperclip proves who it is.** + - **Paperclip key (recommended).** Press **Create key**. Paperclip creates a + signing key, keeps the private half in the company vault, and shows the + public key as PEM and as JSON. Register it with the provider for the + Paperclip client. The public key isn't secret. + - **Client secret.** For providers that only issue secrets. The secret goes + straight into the vault and is never shown again. +3. **Client ID and scopes.** Enter the client ID the provider shows for the + Paperclip client, and any scopes its docs list (space separated). +4. **Test connection.** Paperclip asks the sign-in service for a token, then + lists the server's tools with it. Success turns the connection on and goes to + the normal review step. A failed test keeps the draft and its key, so you + can fix the provider side and test again. + +Errors say what to change: an unaccepted key or secret, refused scopes, a +provider that doesn't accept keys (choose Client secret) or secrets (choose +Paperclip key), or a sign-in service Paperclip couldn't find. + +## How tokens are requested + +- `grant_type=client_credentials`, with `scope` and the RFC 8707 `resource` + (the MCP server address) on every request. +- **Paperclip key:** `private_key_jwt`. Each request carries a fresh assertion + signed with RS256 (or ES256 when the service accepts only that): + `iss` = `sub` = client ID, `aud` = the token endpoint, `exp` 60 seconds after + `iat`, a unique `jti`, and `kid` = the key's RFC 7638 thumbprint. Per the + extension, no `client_id` or secret is sent alongside it. +- **Client secret:** `client_secret_basic`, or `client_secret_post` when that + is all the service advertises. +- Requests that carry a 2026-07-28 client capability object declare + `io.modelcontextprotocol/oauth-client-credentials` for these connections only. + +Tokens live in the vault on the connection's organization grant, like any +other OAuth token, and are reused until a minute before they expire. There is +no refresh token: Paperclip asks for a new access token. The existing grant +refresh lease and in-process single flight mean concurrent agents, across +server processes, share one token request. A `401` from the server requests a +new token once; a second `401` reports the problem without touching the +pinned settings. Agent boot and time to first token do not change: a live +token is read the same way as for browser sign-in connections. + +## The sign-in service is pinned + +The connection records the sign-in service's issuer and token endpoint at +setup. Credentials and assertions go only to that token endpoint, never to a +deployment-wide OAuth client and never to a different service the server later +advertises: + +- Test and rotation check the server's protected-resource metadata; if it now + lists other sign-in services and not the pinned one, Paperclip refuses and + asks you to set up machine sign-in again. +- A rejected token at runtime never re-runs discovery or rewrites the + connection's endpoints. + +When you enter a token URL directly there is no issuer to compare; the token +URL itself is the pin. + +## Rotation without downtime + +- **New client secret:** enter it; Paperclip tests it against the sign-in + service first and only then replaces the stored secret (a new version of the + same vault entry). A wrong secret changes nothing. +- **New key:** start a key rotation; Paperclip creates a replacement key and + shows its public key while the current key keeps working. Register the new + public key with the provider, then complete the rotation: Paperclip tests the + new key and only then switches to it and deletes the old one. + +API: `POST /api/tool-connections/{id}/machine-sign-in/rotate` with +`{ "method": "client_secret", "clientSecret": "…" }` or +`{ "method": "paperclip_key" }`, then +`POST /api/tool-connections/{id}/machine-sign-in/rotate/complete` for a key. + +## Security + +- Private keys and client secrets exist only in the company vault + (`oauth.client_private_key`, `oauth.client_private_key_next`, + `oauth.client_secret`). Config, API responses, activity and logs carry only + the public key, key ID, issuer, method and scope count. +- Company scoped. Only connection managers can set it up, and only for + organization connections; the service refuses personal connections. +- Activity: `tool_connection.machine_sign_in_created`, `…_verified`, + `…_rotation_started`, `…_rotated`, and removal as `tool_connection.archived` + with `machineSignIn: true`. Removal destroys the vault entries the connection + owned. + +## API + +| Route | Use | +| --- | --- | +| `POST /api/companies/{companyId}/tools/machine-sign-in` | Create the draft (finds and pins the sign-in service, creates the key or stores the secret). | +| `GET /api/tool-connections/{id}/machine-sign-in` | Settings and public keys. | +| `POST /api/tool-connections/{id}/machine-sign-in/test` | Test with an optional client ID, scopes or secret; turns the connection on. | +| `POST /api/tool-connections/{id}/machine-sign-in/rotate` | Rotate the secret, or stage a new key. | +| `POST /api/tool-connections/{id}/machine-sign-in/rotate/complete` | Switch to the staged key. | + +Code: `server/src/services/tool-access/oauth/client-credentials.ts` (keys and +assertions), `client-credentials-service.ts` (setup, pinning, token requests), +the machine sign-in branch in `grant-refresh.ts`, and +`ui/src/features/connections/MachineSignInSetup.tsx`. Tests: +`server/src/__tests__/tool-access-client-credentials.test.ts`. + +## Not yet covered + +- A settings-page control for rotation (rotation is API-only today). +- Enterprise single sign-on and enterprise-managed authorization (ID-JAG) are + later phases. diff --git a/doc/connections/README.md b/doc/connections/README.md index 31fb2959d61..d66cb81371d 100644 --- a/doc/connections/README.md +++ b/doc/connections/README.md @@ -20,9 +20,14 @@ MCP protocol versions (2026-07-28 stateless MCP and older handshake servers): MCP extensions: [MCP Apps](./MCP-APPS.md) (interactive views in the task chat), [MCP Skills](./MCP-SKILLS.md) (skills that connected apps publish, reviewed by the board and delivered to agents), [MCP Tasks](./MCP-TASKS.md) (long -provider calls that survive timeouts, restarts, and deploys), and +provider calls that survive timeouts, restarts, and deploys), [MCP elicitation](./MCP-ELICITATION.md) (an app's question to the person, -answered in the task chat). +answered in the task chat), and [Machine sign-in](./MCP-CLIENT-CREDENTIALS.md) +(OAuth client credentials for organization connections where no person signs +in). + +[Machine sign-in](./MCP-CLIENT-CREDENTIALS.md) (OAuth client credentials for +organization connections where no person signs in). Long-term memory: [Experimental memory connectors](./MEMORY.md). diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts index 7128882e69b..efab7ad18d8 100644 --- a/packages/shared/src/index.ts +++ b/packages/shared/src/index.ts @@ -1458,6 +1458,9 @@ export type { RejectSecretProposalInput, ConnectToolAppAuthChallenge, ConnectToolAppResult, + MachineSignInPublicKey, + MachineSignInStatus, + MachineSignInSetupResult, ToolAppMetadataPreflightAttempt, ToolAppMetadataPreflightResult, ToolOAuthClientRegistrationSource, @@ -2302,6 +2305,15 @@ export { genericMcpOAuthClientSchema, type GenericMcpAuthMode, type GenericMcpOAuthClient, + MACHINE_SIGN_IN_METHODS, + machineSignInMethodSchema, + createMachineSignInSchema, + testMachineSignInSchema, + rotateMachineSignInSchema, + type MachineSignInMethod, + type CreateMachineSignIn, + type TestMachineSignIn, + type RotateMachineSignIn, reconnectToolAppSchema, createToolApplicationSchema, finishToolAppSchema, diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts index f63f67250d6..8abf1f4ed91 100644 --- a/packages/shared/src/types/index.ts +++ b/packages/shared/src/types/index.ts @@ -525,6 +525,9 @@ export type { ToolAccessSelector, ConnectToolAppAuthChallenge, ConnectToolAppResult, + MachineSignInPublicKey, + MachineSignInStatus, + MachineSignInSetupResult, ToolAppMetadataPreflightAttempt, ToolAppMetadataPreflightResult, FinishToolAppResult, diff --git a/packages/shared/src/types/tool-access.ts b/packages/shared/src/types/tool-access.ts index 4c05d176f9b..1d2c29fb7c0 100644 --- a/packages/shared/src/types/tool-access.ts +++ b/packages/shared/src/types/tool-access.ts @@ -1221,6 +1221,39 @@ export interface ConnectToolAppAuthChallenge { manualClientRequired?: boolean; } +/** Public half of a key Paperclip holds for machine sign-in. Safe to show and share. */ +export interface MachineSignInPublicKey { + keyId: string; + algorithm: "RS256" | "ES256"; + /** PEM (SPKI) for providers that take a certificate-style key. */ + pem: string; + /** JWK for providers that take a JSON key. */ + jwk: Record; + createdAt: string; +} + +/** Machine sign-in settings for one organization connection. Never includes secret or private key values. */ +export interface MachineSignInStatus { + connectionId: string; + method: "paperclip_key" | "client_secret"; + clientId: string | null; + /** The sign-in service this connection's credentials are bound to. */ + issuer: string | null; + tokenUrl: string; + scopes: string[]; + publicKey: MachineSignInPublicKey | null; + /** A replacement key waiting to be registered with the provider. */ + pendingPublicKey: MachineSignInPublicKey | null; + hasClientSecret: boolean; + lastTokenAt: string | null; +} + +export interface MachineSignInSetupResult { + connectionId: string; + connection: ToolConnection; + machineSignIn: MachineSignInStatus; +} + export interface ConnectToolAppResult { connectionId: string; application: ToolApplication; diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.ts index a62024f564b..b0bc5449eb5 100644 --- a/packages/shared/src/validators/index.ts +++ b/packages/shared/src/validators/index.ts @@ -919,6 +919,15 @@ export { genericMcpOAuthClientSchema, type GenericMcpAuthMode, type GenericMcpOAuthClient, + MACHINE_SIGN_IN_METHODS, + machineSignInMethodSchema, + createMachineSignInSchema, + testMachineSignInSchema, + rotateMachineSignInSchema, + type MachineSignInMethod, + type CreateMachineSignIn, + type TestMachineSignIn, + type RotateMachineSignIn, reconnectToolAppSchema, finishToolAppSchema, finalizeOAuthAccessSchema, diff --git a/packages/shared/src/validators/tool-access.ts b/packages/shared/src/validators/tool-access.ts index cd28549a930..f6ada4ebdc2 100644 --- a/packages/shared/src/validators/tool-access.ts +++ b/packages/shared/src/validators/tool-access.ts @@ -372,6 +372,45 @@ export const genericMcpOAuthClientSchema = z.object({ export type GenericMcpOAuthClient = z.infer; +/** + * Machine sign-in (MCP OAuth client credentials) for organization-owned + * connections. "paperclip_key" means Paperclip holds a signing key and the admin + * registers its public half with the provider; "client_secret" stores a secret + * the provider issued. Secret values are write-only. + */ +export const MACHINE_SIGN_IN_METHODS = ["paperclip_key", "client_secret"] as const; +export const machineSignInMethodSchema = z.enum(MACHINE_SIGN_IN_METHODS); +export type MachineSignInMethod = z.infer; + +const machineSignInScopesSchema = z.string().trim().max(2048) + .refine((value) => !/[\u0000-\u001f"\\]/.test(value), "Scopes can only contain letters, numbers and punctuation, separated by spaces."); + +export const createMachineSignInSchema = z.object({ + link: z.string().trim().url("Enter the server's full address, starting with https://").max(4096), + name: z.string().trim().min(1).max(160).optional(), + /** The sign-in service's address, or its token URL. Omitted means "find it from the server". */ + authorizationServer: z.string().trim().url("Enter the sign-in service's full address, starting with https://").max(4096).optional(), + method: machineSignInMethodSchema, + clientId: z.string().trim().min(1).max(4096).optional(), + clientSecret: z.string().min(1).max(16384).optional(), + scopes: machineSignInScopesSchema.optional(), + applicationId: z.string().uuid().optional(), +}).strict(); +export type CreateMachineSignIn = z.infer; + +export const testMachineSignInSchema = z.object({ + clientId: z.string().trim().min(1).max(4096).optional(), + clientSecret: z.string().min(1).max(16384).optional(), + scopes: machineSignInScopesSchema.optional(), +}).strict(); +export type TestMachineSignIn = z.infer; + +export const rotateMachineSignInSchema = z.discriminatedUnion("method", [ + z.object({ method: z.literal("paperclip_key") }).strict(), + z.object({ method: z.literal("client_secret"), clientSecret: z.string().min(1).max(16384) }).strict(), +]); +export type RotateMachineSignIn = z.infer; + /** * Reject `headers.*` credential paths whose header name Paperclip refuses to * send, and any value that could split the outbound request. This runs at the diff --git a/server/src/__tests__/tool-access-client-credentials.test.ts b/server/src/__tests__/tool-access-client-credentials.test.ts new file mode 100644 index 00000000000..c39fb3d0b42 --- /dev/null +++ b/server/src/__tests__/tool-access-client-credentials.test.ts @@ -0,0 +1,682 @@ +import { createPublicKey, randomUUID, verify, type KeyObject } from "node:crypto"; +import express from "express"; +import request from "supertest"; +import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest"; +import { + activityLog, + applyPendingMigrations, + authUsers, + companies, + companySecretBindings, + companySecrets, + connectionGrants, + createDb, + secretAccessEvents, + toolAccessAuditEvents, + toolApplications, + toolCatalogEntries, + toolConnections, +} from "@paperclipai/db"; +import { and, eq } from "drizzle-orm"; +import { toolAccessService } from "../services/tool-access.js"; +import { secretService } from "../services/secrets.js"; +import { toolAccessRoutes } from "../routes/tool-access.js"; +import { errorHandler } from "../middleware/index.js"; +import { createOAuthClientProtocol } from "../services/tool-access/oauth/client.js"; +import { + CLIENT_ASSERTION_LIFETIME_SECONDS, + generateClientKeyPair, + signClientAssertion, +} from "../services/tool-access/oauth/client-credentials.js"; +import { MCP_OAUTH_CLIENT_CREDENTIALS_EXTENSION_ID, mcpClientCapabilities } from "../services/mcp-http.js"; +import { resolveExternalTestDatabaseUrl } from "./helpers/external-test-database.js"; +import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js"; + +const ISSUER = "https://auth.example.test"; +const TOKEN_URL = `${ISSUER}/oauth/token`; +const OTHER_ISSUER = "https://other-auth.example.test"; +const MCP_URL = "https://mcp.example.test/mcp"; +const CLIENT_ID = "paperclip-automation"; +const CLIENT_SECRET = "s3cret-value-never-shown"; + +function decodeJwt(token: string) { + const [header, claims, signature] = token.split("."); + return { + header: JSON.parse(Buffer.from(header!, "base64url").toString()) as Record, + claims: JSON.parse(Buffer.from(claims!, "base64url").toString()) as Record, + signingInput: `${header}.${claims}`, + signature: Buffer.from(signature!, "base64url"), + }; +} + +function verifyJwt(token: string, key: KeyObject): boolean { + const { header, signingInput, signature } = decodeJwt(token); + return verify( + "sha256", + Buffer.from(signingInput), + header.alg === "ES256" ? { key, dsaEncoding: "ieee-p1363" } : key, + signature, + ); +} + +function json(payload: unknown, status = 200, headers: Record = {}) { + return new Response(JSON.stringify(payload), { status, headers: { "content-type": "application/json", ...headers } }); +} + +/** + * A fake sign-in service and MCP server behind the outbound HTTP transport. + * The sign-in service verifies real signatures against keys an "admin" + * registered, exactly as a provider would. + */ +function fakeProvider() { + const state = { + advertisedIssuers: [ISSUER], + registeredKeys: new Map(), + clientSecret: CLIENT_SECRET, + tokenRequests: [] as Array<{ url: string; body: URLSearchParams; authorization: string | null }>, + otherIssuerRequests: 0, + mcpRequests: [] as Array<{ authorization: string | null; body: Record }>, + acceptedTokens: new Set(), + issued: 0, + tokenDelayMs: 0, + rejectAllTokens: false, + /** Other clients the sign-in service knows (id → secret). */ + extraClients: new Map(), + /** Clients whose tokens the MCP server refuses. */ + mcpDeniedClients: new Set(), + tokenClients: new Map(), + /** Serve protected-resource metadata only at the address the challenge names. */ + metadataOnlyAtHint: false, + /** Runs once when the server first receives a signed-in request (to stage races). */ + onAuthorizedMcpRequest: null as null | (() => Promise), + }; + const metadata = (issuer: string) => ({ + issuer, + token_endpoint: `${issuer}/oauth/token`, + grant_types_supported: ["client_credentials"], + token_endpoint_auth_methods_supported: ["private_key_jwt", "client_secret_basic", "client_secret_post"], + token_endpoint_auth_signing_alg_values_supported: ["RS256", "ES256"], + }); + const handle = async (input: string | URL | Request, init?: RequestInit): Promise => { + const url = String(input instanceof Request ? input.url : input); + const headers = new Headers(init?.headers); + if (url.startsWith(OTHER_ISSUER)) { + state.otherIssuerRequests += 1; + if (url.includes("/.well-known/")) return json(metadata(OTHER_ISSUER)); + return json({ access_token: "stolen", expires_in: 3600 }); + } + if (url === `${new URL(MCP_URL).origin}/meta/custom-resource` && state.metadataOnlyAtHint) { + return json({ resource: MCP_URL, authorization_servers: state.advertisedIssuers }); + } + if (url === `${new URL(MCP_URL).origin}/.well-known/oauth-protected-resource/mcp` + || url === `${new URL(MCP_URL).origin}/.well-known/oauth-protected-resource`) { + if (state.metadataOnlyAtHint) return new Response("not found", { status: 404 }); + return json({ resource: MCP_URL, authorization_servers: state.advertisedIssuers }); + } + if (url === `${ISSUER}/.well-known/oauth-authorization-server`) return json(metadata(ISSUER)); + if (url.startsWith(ISSUER) && url.includes("/.well-known/")) return new Response("not found", { status: 404 }); + if (url === TOKEN_URL) { + const body = new URLSearchParams(String(init?.body)); + state.tokenRequests.push({ url, body, authorization: headers.get("authorization") }); + if (state.tokenDelayMs) await new Promise((resolve) => setTimeout(resolve, state.tokenDelayMs)); + if (body.get("grant_type") !== "client_credentials") return json({ error: "unsupported_grant_type" }, 400); + const assertion = body.get("client_assertion"); + let authenticated = false; + let clientId = CLIENT_ID; + if (assertion) { + const { header, claims } = decodeJwt(assertion); + const key = state.registeredKeys.get(String(header.kid)); + authenticated = Boolean(key && verifyJwt(assertion, key) + && claims.iss === CLIENT_ID && claims.sub === CLIENT_ID && claims.aud === TOKEN_URL + && typeof claims.exp === "number" && claims.exp * 1000 > Date.now()); + } else { + const basic = headers.get("authorization"); + const expected = `Basic ${Buffer.from(`${CLIENT_ID}:${state.clientSecret}`).toString("base64")}`; + authenticated = basic === expected; + for (const [id, secret] of state.extraClients) { + if (basic === `Basic ${Buffer.from(`${id}:${secret}`).toString("base64")}`) { + authenticated = true; + clientId = id; + } + } + } + if (!authenticated) return json({ error: "invalid_client" }, 401); + state.issued += 1; + const token = `machine-token-${state.issued}`; + state.acceptedTokens.add(token); + state.tokenClients.set(token, clientId); + return json({ access_token: token, token_type: "Bearer", expires_in: 3600, scope: body.get("scope") ?? undefined }); + } + if (url === MCP_URL) { + const body = JSON.parse(String(init?.body ?? "{}")) as Record; + const authorization = headers.get("authorization"); + state.mcpRequests.push({ authorization, body }); + const bearer = authorization?.replace(/^Bearer /, "") ?? ""; + if (state.rejectAllTokens || !state.acceptedTokens.has(bearer) || state.mcpDeniedClients.has(state.tokenClients.get(bearer) ?? "")) { + return new Response("", { + status: 401, + headers: { "www-authenticate": `Bearer resource_metadata="${new URL(MCP_URL).origin}${state.metadataOnlyAtHint ? "/meta/custom-resource" : "/.well-known/oauth-protected-resource/mcp"}"` }, + }); + } + if (state.onAuthorizedMcpRequest) { + const hook = state.onAuthorizedMcpRequest; + state.onAuthorizedMcpRequest = null; + await hook(); + } + if (body.method === "server/discover") { + return json({ jsonrpc: "2.0", id: body.id, result: { supportedVersions: ["2026-07-28"], capabilities: {} } }); + } + if (body.method === "tools/list") { + return json({ jsonrpc: "2.0", id: body.id, result: { tools: [ + { name: "list_reports", description: "List reports", inputSchema: { type: "object", properties: {} }, annotations: { readOnlyHint: true } }, + ] } }); + } + return json({ jsonrpc: "2.0", id: body.id, result: {} }); + } + throw new Error(`unexpected request ${url}`); + }; + return { state, handle }; +} + +describe("client credentials protocol", () => { + it("creates keys without blocking other work on the server", async () => { + let otherWorkRan = false; + const generating = generateClientKeyPair("RS256"); + setImmediate(() => { otherWorkRan = true; }); + await generating; + expect(otherWorkRan).toBe(true); + }); + + it("signs an RS256 assertion with iss = sub = client ID, the token endpoint as audience, a short expiry and a unique jti", async () => { + const { privateKeyPem, publicKey } = await generateClientKeyPair("RS256"); + const now = new Date("2026-11-13T12:00:00Z"); + const first = signClientAssertion({ privateKeyPem, algorithm: "RS256", keyId: publicKey.keyId, clientId: CLIENT_ID, audience: TOKEN_URL, now }); + const second = signClientAssertion({ privateKeyPem, algorithm: "RS256", keyId: publicKey.keyId, clientId: CLIENT_ID, audience: TOKEN_URL, now }); + const decoded = decodeJwt(first); + expect(decoded.header).toEqual({ alg: "RS256", typ: "JWT", kid: publicKey.keyId }); + expect(decoded.claims).toMatchObject({ iss: CLIENT_ID, sub: CLIENT_ID, aud: TOKEN_URL, iat: now.getTime() / 1000 }); + expect(Number(decoded.claims.exp) - Number(decoded.claims.iat)).toBe(CLIENT_ASSERTION_LIFETIME_SECONDS); + expect(CLIENT_ASSERTION_LIFETIME_SECONDS).toBeLessThanOrEqual(60); + expect(decoded.claims.jti).not.toEqual(decodeJwt(second).claims.jti); + expect(verifyJwt(first, createPublicKey(publicKey.publicKeyPem))).toBe(true); + // The JWK the admin registers verifies the same signature. + expect(verifyJwt(first, createPublicKey({ key: publicKey.publicJwk, format: "jwk" }))).toBe(true); + expect(publicKey.publicJwk).toMatchObject({ kid: publicKey.keyId, alg: "RS256", use: "sig", kty: "RSA" }); + expect(JSON.stringify(publicKey)).not.toContain("PRIVATE KEY"); + expect(publicKey.publicJwk).not.toHaveProperty("d"); + }); + + it("signs ES256 assertions in JOSE (raw r||s) form", async () => { + const { privateKeyPem, publicKey } = await generateClientKeyPair("ES256"); + const token = signClientAssertion({ privateKeyPem, algorithm: "ES256", keyId: publicKey.keyId, clientId: CLIENT_ID, audience: TOKEN_URL }); + expect(decodeJwt(token).signature).toHaveLength(64); + expect(verifyJwt(token, createPublicKey(publicKey.publicKeyPem))).toBe(true); + }); + + it("sends only the signed assertion as client authentication", async () => { + const sent: Array<{ body: URLSearchParams; headers: Headers }> = []; + const { exchangeOAuthToken } = createOAuthClientProtocol({ + assertOAuthEndpointUrl: (_kind, value) => String(value), + fetchRemoteHttpUrl: async (_url, init) => { + sent.push({ body: new URLSearchParams(String(init?.body)), headers: new Headers(init?.headers) }); + return json({ access_token: "t", expires_in: 60 }); + }, + }); + await exchangeOAuthToken({ + tokenUrl: TOKEN_URL, clientId: CLIENT_ID, grantType: "client_credentials", scopes: ["reports.read"], + clientAssertion: "a.b.c", resource: MCP_URL, + }); + const { body, headers } = sent[0]!; + expect(body.get("grant_type")).toBe("client_credentials"); + expect(body.get("client_assertion_type")).toBe("urn:ietf:params:oauth:client-assertion-type:jwt-bearer"); + expect(body.get("client_assertion")).toBe("a.b.c"); + expect(body.get("scope")).toBe("reports.read"); + expect(body.get("resource")).toBe(MCP_URL); + expect(body.has("client_id")).toBe(false); + expect(body.has("client_secret")).toBe(false); + expect(headers.get("authorization")).toBeNull(); + }); + + it("declares the extension only when a connection uses machine sign-in", () => { + expect(JSON.stringify(mcpClientCapabilities("2026-07-28"))).not.toContain(MCP_OAUTH_CLIENT_CREDENTIALS_EXTENSION_ID); + expect(mcpClientCapabilities("2026-07-28", { declareClientCredentials: true })).toMatchObject({ + extensions: { [MCP_OAUTH_CLIENT_CREDENTIALS_EXTENSION_ID]: {} }, + }); + }); +}); + +const externalDatabaseUrl = resolveExternalTestDatabaseUrl("PAPERCLIP_TOOL_ACCESS_TEST_DATABASE_URL"); +const embeddedPostgresSupport = externalDatabaseUrl ? { supported: true } : await getEmbeddedPostgresTestSupport(); +const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip; + +describeEmbeddedPostgres("machine sign-in connections", () => { + let db!: ReturnType; + let tempDb: Awaited> | null = null; + const transport = { + remoteHttpEndpointLookup: async () => [{ address: "8.8.8.8", family: 4 as const }], + remoteHttpRequest: async (url: string, init: RequestInit) => fetch(url, init), + }; + const service = () => toolAccessService(db, transport); + const actor = { actorType: "user" as const, actorId: "board-user" }; + + beforeAll(async () => { + if (externalDatabaseUrl) { + await applyPendingMigrations(externalDatabaseUrl); + db = createDb(externalDatabaseUrl, { maxConnections: 6 }); + return; + } + tempDb = await startEmbeddedPostgresTestDatabase("paperclip-client-credentials-"); + db = createDb(tempDb.connectionString, { maxConnections: 6 }); + }, 120_000); + + afterEach(async () => { + vi.restoreAllMocks(); + await db.delete(secretAccessEvents); + await db.delete(companySecretBindings); + await db.delete(activityLog); + await db.delete(toolAccessAuditEvents); + await db.delete(toolCatalogEntries); + await db.delete(connectionGrants); + await db.delete(toolConnections); + await db.delete(companySecrets); + await db.delete(toolApplications); + await db.delete(companies); + await db.delete(authUsers); + }); + + afterAll(async () => { + await db?.$client.end({ timeout: 1 }); + await tempDb?.cleanup(); + }); + + async function createCompany() { + const [company] = await db.insert(companies).values({ + name: `Machine sign-in ${randomUUID()}`, + issuePrefix: `MS${randomUUID().slice(0, 6).toUpperCase()}`, + }).returning(); + return company!; + } + + function useProvider() { + const provider = fakeProvider(); + vi.spyOn(globalThis, "fetch").mockImplementation(provider.handle); + return provider; + } + + function registerKey(provider: ReturnType, key: { keyId: string; pem: string }) { + provider.state.registeredKeys.set(key.keyId, createPublicKey(key.pem)); + } + + async function organizationGrant(connectionId: string) { + const [grant] = await db.select().from(connectionGrants) + .where(and(eq(connectionGrants.connectionId, connectionId), eq(connectionGrants.kind, "organization"))); + return grant!; + } + + async function setupKeyConnection(companyId: string, provider: ReturnType) { + const svc = service(); + const created = await svc.createMachineSignIn(companyId, { link: MCP_URL, method: "paperclip_key", scopes: "reports.read" }, actor); + registerKey(provider, created.machineSignIn.publicKey!); + const result = await svc.testMachineSignIn(companyId, created.connectionId, { clientId: CLIENT_ID }, actor); + return { svc, created, result }; + } + + it("sets up a Paperclip key connection: finds the sign-in service, shows the public key, signs in and lists tools", async () => { + const company = await createCompany(); + const provider = useProvider(); + const svc = service(); + const created = await svc.createMachineSignIn(company.id, { link: MCP_URL, method: "paperclip_key", scopes: "reports.read" }, actor); + expect(created.machineSignIn).toMatchObject({ method: "paperclip_key", issuer: ISSUER, tokenUrl: TOKEN_URL, clientId: null, scopes: ["reports.read"] }); + expect(created.machineSignIn.publicKey?.pem).toContain("BEGIN PUBLIC KEY"); + expect(created.connection.status).toBe("draft"); + // The private key is in the vault, nowhere else. + const serialized = JSON.stringify(created); + expect(serialized).not.toContain("PRIVATE KEY"); + const [row] = await db.select().from(toolConnections).where(eq(toolConnections.id, created.connectionId)); + expect(JSON.stringify(row!.config)).not.toContain("PRIVATE KEY"); + expect(row!.credentialSecretRefs.map((ref) => ref.configPath)).toEqual(["oauth.client_private_key"]); + + // Testing before the key is registered fails clearly and keeps the draft and its key. + await expect(svc.testMachineSignIn(company.id, created.connectionId, { clientId: CLIENT_ID }, actor)) + .rejects.toMatchObject({ status: 422, details: expect.objectContaining({ code: "client_credentials_rejected" }) }); + expect((await svc.getMachineSignIn(company.id, created.connectionId)).publicKey?.keyId).toBe(created.machineSignIn.publicKey!.keyId); + + registerKey(provider, created.machineSignIn.publicKey!); + const result = await svc.testMachineSignIn(company.id, created.connectionId, { clientId: CLIENT_ID }, actor); + expect(result.connection.status).toBe("active"); + expect(result.catalog.map((entry) => entry.name)).toContain("list_reports"); + + const accepted = provider.state.tokenRequests.at(-1)!; + expect(accepted.body.get("scope")).toBe("reports.read"); + expect(accepted.body.get("resource")).toBe(MCP_URL); + const { header, claims } = decodeJwt(accepted.body.get("client_assertion")!); + expect(header.kid).toBe(created.machineSignIn.publicKey!.keyId); + expect(claims).toMatchObject({ iss: CLIENT_ID, sub: CLIENT_ID, aud: TOKEN_URL }); + const authorized = provider.state.mcpRequests.filter((call) => call.authorization === "Bearer machine-token-1"); + expect(authorized.length).toBeGreaterThan(0); + const listCall = provider.state.mcpRequests.find((call) => call.body.method === "tools/list" && call.authorization); + expect(JSON.stringify(listCall?.body)).toContain(MCP_OAUTH_CLIENT_CREDENTIALS_EXTENSION_ID); + const grant = await organizationGrant(created.connectionId); + expect(grant.status).toBe("active"); + expect(grant.credentialSecretRefs.map((ref) => ref.configPath)).toContain("oauth.access_token"); + }); + + it("uses a client secret with client_secret_basic and never returns the secret", async () => { + const company = await createCompany(); + const provider = useProvider(); + const svc = service(); + const created = await svc.createMachineSignIn(company.id, { + link: MCP_URL, method: "client_secret", authorizationServer: ISSUER, clientId: CLIENT_ID, clientSecret: CLIENT_SECRET, + }, actor); + expect(created.machineSignIn).toMatchObject({ method: "client_secret", hasClientSecret: true, publicKey: null }); + const result = await svc.testMachineSignIn(company.id, created.connectionId, {}, actor); + expect(result.connection.status).toBe("active"); + const tokenRequest = provider.state.tokenRequests.at(-1)!; + expect(tokenRequest.authorization).toBe(`Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")}`); + expect(tokenRequest.body.has("client_secret")).toBe(false); + for (const value of [created, result, await svc.getMachineSignIn(company.id, created.connectionId)]) { + expect(JSON.stringify(value)).not.toContain(CLIENT_SECRET); + } + const [row] = await db.select().from(toolConnections).where(eq(toolConnections.id, created.connectionId)); + expect(JSON.stringify(row)).not.toContain(CLIENT_SECRET); + }); + + it("follows the server's challenge to metadata published outside the well-known addresses", async () => { + const company = await createCompany(); + const provider = useProvider(); + provider.state.metadataOnlyAtHint = true; + const created = await service().createMachineSignIn(company.id, { link: MCP_URL, method: "paperclip_key" }, actor); + expect(created.machineSignIn).toMatchObject({ issuer: ISSUER, tokenUrl: TOKEN_URL }); + }); + + it("accepts a token URL directly when the provider publishes no sign-in metadata", async () => { + const company = await createCompany(); + useProvider(); + const created = await service().createMachineSignIn(company.id, { + link: MCP_URL, method: "client_secret", authorizationServer: TOKEN_URL, clientId: CLIENT_ID, clientSecret: CLIENT_SECRET, + }, actor); + expect(created.machineSignIn).toMatchObject({ issuer: null, tokenUrl: TOKEN_URL }); + }); + + it("refuses to follow the server to a different sign-in service and never sends credentials there", async () => { + const company = await createCompany(); + const provider = useProvider(); + const svc = service(); + const created = await svc.createMachineSignIn(company.id, { link: MCP_URL, method: "paperclip_key" }, actor); + registerKey(provider, created.machineSignIn.publicKey!); + provider.state.advertisedIssuers = [OTHER_ISSUER]; + const tokenRequestsBefore = provider.state.tokenRequests.length; + await expect(svc.testMachineSignIn(company.id, created.connectionId, { clientId: CLIENT_ID }, actor)) + .rejects.toMatchObject({ status: 422, details: expect.objectContaining({ code: "client_credentials_issuer_changed" }) }); + expect(provider.state.tokenRequests.length).toBe(tokenRequestsBefore); + expect(provider.state.otherIssuerRequests).toBe(0); + expect((await svc.getMachineSignIn(company.id, created.connectionId)).tokenUrl).toBe(TOKEN_URL); + }); + + it("keeps the pinned token endpoint when an active server's challenge points elsewhere", async () => { + const company = await createCompany(); + const provider = useProvider(); + const { svc, created } = await setupKeyConnection(company.id, provider); + provider.state.advertisedIssuers = [OTHER_ISSUER]; + provider.state.rejectAllTokens = true; + await expect(svc.checkHealth(created.connectionId, actor)).rejects.toMatchObject({ + message: expect.stringContaining("didn't accept this connection's machine sign-in"), + }); + const [row] = await db.select().from(toolConnections).where(eq(toolConnections.id, created.connectionId)); + expect((row!.config.oauth as Record).tokenUrl).toBe(TOKEN_URL); + expect((row!.config.oauth as Record).issuer).toBe(ISSUER); + expect(provider.state.otherIssuerRequests).toBe(0); + }); + + it("reuses a cached token and shares one token request across concurrent callers", async () => { + const company = await createCompany(); + const provider = useProvider(); + const { created } = await setupKeyConnection(company.id, provider); + const grant = await organizationGrant(created.connectionId); + const issuedAfterSetup = provider.state.issued; + + // A live token is reused: no token request at all. + const first = service(); + await first.refreshOAuthGrantCredentials({ companyId: company.id, connectionId: created.connectionId, grantId: grant.id, actor }); + expect(provider.state.issued).toBe(issuedAfterSetup); + + // Shortly before expiry, many agents on two server processes ask at once. + await db.update(connectionGrants).set({ + providerTenant: { ...(grant.providerTenant ?? {}), oauth: { ...((grant.providerTenant ?? {}).oauth as object ?? {}), accessTokenExpiresAt: new Date(Date.now() + 10_000).toISOString() } }, + }).where(eq(connectionGrants.id, grant.id)); + provider.state.tokenDelayMs = 150; + const second = service(); + const input = { companyId: company.id, connectionId: created.connectionId, grantId: grant.id, actor }; + await Promise.all([ + first.refreshOAuthGrantCredentials(input), first.refreshOAuthGrantCredentials(input), first.refreshOAuthGrantCredentials(input), + second.refreshOAuthGrantCredentials(input), second.refreshOAuthGrantCredentials(input), + ]); + expect(provider.state.issued).toBe(issuedAfterSetup + 1); + const refreshed = await organizationGrant(created.connectionId); + const expiresAt = Date.parse(String((refreshed.providerTenant?.oauth as Record).accessTokenExpiresAt)); + expect(expiresAt).toBeGreaterThan(Date.now() + 3_000_000); + }); + + it("requests a new token when the server rejects the current one", async () => { + const company = await createCompany(); + const provider = useProvider(); + const { svc, created } = await setupKeyConnection(company.id, provider); + const issuedAfterSetup = provider.state.issued; + provider.state.acceptedTokens.clear(); + const health = await svc.checkHealth(created.connectionId, actor); + expect(health.connection.healthStatus).toBe("ok"); + expect(provider.state.issued).toBe(issuedAfterSetup + 1); + expect(provider.state.mcpRequests.at(-1)?.authorization).toBe(`Bearer machine-token-${issuedAfterSetup + 1}`); + }); + + it("rotates the key without downtime: the old key works until the new one is registered and confirmed", async () => { + const company = await createCompany(); + const provider = useProvider(); + const { svc, created } = await setupKeyConnection(company.id, provider); + const oldKeyId = created.machineSignIn.publicKey!.keyId; + const started = await svc.rotateMachineSignIn(company.id, created.connectionId, { method: "paperclip_key" }, actor); + expect(started.completed).toBe(false); + const pending = started.machineSignIn.pendingPublicKey!; + expect(pending.keyId).not.toBe(oldKeyId); + expect(started.machineSignIn.publicKey?.keyId).toBe(oldKeyId); + + // Tokens keep coming from the current key while the new one is pending. + const grant = await organizationGrant(created.connectionId); + await svc.refreshOAuthGrantCredentials({ companyId: company.id, connectionId: created.connectionId, grantId: grant.id, forceRefresh: true, actor }); + expect(decodeJwt(provider.state.tokenRequests.at(-1)!.body.get("client_assertion")!).header.kid).toBe(oldKeyId); + + // Completing before the provider knows the new key fails and changes nothing. + await expect(svc.completeMachineSignInRotation(company.id, created.connectionId, actor)) + .rejects.toMatchObject({ details: expect.objectContaining({ code: "client_credentials_rejected" }) }); + expect((await svc.getMachineSignIn(company.id, created.connectionId)).publicKey?.keyId).toBe(oldKeyId); + + registerKey(provider, pending); + const completed = await svc.completeMachineSignInRotation(company.id, created.connectionId, actor); + expect(completed.machineSignIn.publicKey?.keyId).toBe(pending.keyId); + expect(completed.machineSignIn.pendingPublicKey).toBeNull(); + provider.state.registeredKeys.delete(oldKeyId); + await svc.refreshOAuthGrantCredentials({ companyId: company.id, connectionId: created.connectionId, grantId: grant.id, forceRefresh: true, actor }); + expect(decodeJwt(provider.state.tokenRequests.at(-1)!.body.get("client_assertion")!).header.kid).toBe(pending.keyId); + const [row] = await db.select().from(toolConnections).where(eq(toolConnections.id, created.connectionId)); + expect(row!.credentialSecretRefs.map((ref) => ref.configPath)).not.toContain("oauth.client_private_key_next"); + }); + + it("signs with a key ID that matches the key a refresh actually reads", async () => { + const company = await createCompany(); + const provider = useProvider(); + const { svc, created } = await setupKeyConnection(company.id, provider); + // A rotation lands between a refresh loading the settings and reading the + // vault: the vault holds the new key while config still names the old one. + const [row] = await db.select().from(toolConnections).where(eq(toolConnections.id, created.connectionId)); + const keyRef = row!.credentialSecretRefs.find((ref) => ref.configPath === "oauth.client_private_key")!; + const next = await generateClientKeyPair("RS256"); + registerKey(provider, { keyId: next.publicKey.keyId, pem: next.publicKey.publicKeyPem }); + await secretService(db).rotate(keyRef.secretId, { value: next.privateKeyPem }); + const grant = await organizationGrant(created.connectionId); + const before = provider.state.issued; + await svc.refreshOAuthGrantCredentials({ companyId: company.id, connectionId: created.connectionId, grantId: grant.id, forceRefresh: true, actor }); + expect(provider.state.issued).toBe(before + 1); + expect(decodeJwt(provider.state.tokenRequests.at(-1)!.body.get("client_assertion")!).header.kid).toBe(next.publicKey.keyId); + }); + + it("never promotes a staged key that changed after it was registered", async () => { + const company = await createCompany(); + const provider = useProvider(); + const { svc, created } = await setupKeyConnection(company.id, provider); + const started = await svc.rotateMachineSignIn(company.id, created.connectionId, { method: "paperclip_key" }, actor); + registerKey(provider, started.machineSignIn.pendingPublicKey!); + // Another rotation overwrites the staged private key in the vault. + const [row] = await db.select().from(toolConnections).where(eq(toolConnections.id, created.connectionId)); + const staged = row!.credentialSecretRefs.find((ref) => ref.configPath === "oauth.client_private_key_next")!; + const other = await generateClientKeyPair("RS256"); + registerKey(provider, { keyId: other.publicKey.keyId, pem: other.publicKey.publicKeyPem }); + await secretService(db).rotate(staged.secretId, { value: other.privateKeyPem }); + await expect(svc.completeMachineSignInRotation(company.id, created.connectionId, actor)) + .rejects.toMatchObject({ status: 409, details: expect.objectContaining({ code: "client_credentials_rotation_changed" }) }); + const status = await svc.getMachineSignIn(company.id, created.connectionId); + expect(status.publicKey?.keyId).toBe(created.machineSignIn.publicKey!.keyId); + // The current key still signs in. + const grant = await organizationGrant(created.connectionId); + await svc.refreshOAuthGrantCredentials({ companyId: company.id, connectionId: created.connectionId, grantId: grant.id, forceRefresh: true, actor }); + expect(decodeJwt(provider.state.tokenRequests.at(-1)!.body.get("client_assertion")!).header.kid).toBe(created.machineSignIn.publicKey!.keyId); + }); + + it("keeps working credentials when a retest's client can't use the server", async () => { + const company = await createCompany(); + const provider = useProvider(); + const svc = service(); + const created = await svc.createMachineSignIn(company.id, { + link: MCP_URL, method: "client_secret", clientId: CLIENT_ID, clientSecret: CLIENT_SECRET, + }, actor); + await svc.testMachineSignIn(company.id, created.connectionId, {}, actor); + provider.state.extraClients.set("other-client", "other-secret"); + provider.state.mcpDeniedClients.add("other-client"); + await expect(svc.testMachineSignIn(company.id, created.connectionId, { clientId: "other-client", clientSecret: "other-secret" }, actor)) + .rejects.toMatchObject({ details: expect.objectContaining({ code: "client_credentials_rejected" }) }); + const status = await svc.getMachineSignIn(company.id, created.connectionId); + expect(status.clientId).toBe(CLIENT_ID); + // The working connection still serves tools with the original client. + const health = await svc.checkHealth(created.connectionId, actor); + expect(health.connection.healthStatus).toBe("ok"); + expect(provider.state.tokenClients.get(provider.state.mcpRequests.at(-1)!.authorization!.replace("Bearer ", ""))).toBe(CLIENT_ID); + + // A retest that passes gives the organization grant the new token's expiry. + const grant = await organizationGrant(created.connectionId); + await db.update(connectionGrants).set({ + providerTenant: { ...(grant.providerTenant ?? {}), oauth: { ...((grant.providerTenant ?? {}).oauth as object ?? {}), accessTokenExpiresAt: "2000-01-01T00:00:00.000Z" } }, + }).where(eq(connectionGrants.id, grant.id)); + await svc.testMachineSignIn(company.id, created.connectionId, {}, actor); + const retested = await organizationGrant(created.connectionId); + expect(Date.parse(String((retested.providerTenant?.oauth as Record).accessTokenExpiresAt))).toBeGreaterThan(Date.now() + 3_000_000); + }); + + it("never reactivates a removed connection", async () => { + const company = await createCompany(); + const provider = useProvider(); + const { svc, created } = await setupKeyConnection(company.id, provider); + await svc.archiveConnection(created.connectionId, company.id, actor); + await expect(svc.testMachineSignIn(company.id, created.connectionId, { clientSecret: CLIENT_SECRET }, actor)) + .rejects.toMatchObject({ details: expect.objectContaining({ code: "client_credentials_connection_removed" }) }); + const [row] = await db.select().from(toolConnections).where(eq(toolConnections.id, created.connectionId)); + expect(row!.status).toBe("archived"); + }); + + it("does not undo a rotation that lands while a test is running", async () => { + const company = await createCompany(); + const provider = useProvider(); + const { svc, created } = await setupKeyConnection(company.id, provider); + provider.state.clientSecret = "switched-secret"; + // While the test talks to the server, an admin switches to a client secret. + provider.state.onAuthorizedMcpRequest = async () => { + await svc.rotateMachineSignIn(company.id, created.connectionId, { method: "client_secret", clientSecret: "switched-secret" }, actor); + }; + await expect(svc.testMachineSignIn(company.id, created.connectionId, {}, actor)) + .rejects.toMatchObject({ status: 409, details: expect.objectContaining({ code: "client_credentials_changed" }) }); + const status = await svc.getMachineSignIn(company.id, created.connectionId); + expect(status.method).toBe("client_secret"); + const [row] = await db.select().from(toolConnections).where(eq(toolConnections.id, created.connectionId)); + expect(row!.credentialSecretRefs.map((ref) => ref.configPath)).not.toContain("oauth.client_private_key"); + // The next token request uses the secret, not the deleted key. + const grant = await organizationGrant(created.connectionId); + await svc.refreshOAuthGrantCredentials({ companyId: company.id, connectionId: created.connectionId, grantId: grant.id, forceRefresh: true, actor }); + expect(provider.state.tokenRequests.at(-1)!.authorization).toBe(`Basic ${Buffer.from(`${CLIENT_ID}:switched-secret`).toString("base64")}`); + }); + + it("tries a new client secret before replacing the old one", async () => { + const company = await createCompany(); + const provider = useProvider(); + const svc = service(); + const created = await svc.createMachineSignIn(company.id, { + link: MCP_URL, method: "client_secret", clientId: CLIENT_ID, clientSecret: CLIENT_SECRET, + }, actor); + await svc.testMachineSignIn(company.id, created.connectionId, {}, actor); + await expect(svc.rotateMachineSignIn(company.id, created.connectionId, { method: "client_secret", clientSecret: "wrong-new-secret" }, actor)) + .rejects.toMatchObject({ details: expect.objectContaining({ code: "client_credentials_rejected" }) }); + const grant = await organizationGrant(created.connectionId); + // The old secret still works. + await svc.refreshOAuthGrantCredentials({ companyId: company.id, connectionId: created.connectionId, grantId: grant.id, forceRefresh: true, actor }); + provider.state.clientSecret = "rotated-secret"; + const rotated = await svc.rotateMachineSignIn(company.id, created.connectionId, { method: "client_secret", clientSecret: "rotated-secret" }, actor); + expect(rotated.completed).toBe(true); + await svc.refreshOAuthGrantCredentials({ companyId: company.id, connectionId: created.connectionId, grantId: grant.id, forceRefresh: true, actor }); + expect(provider.state.tokenRequests.at(-1)!.authorization).toBe(`Basic ${Buffer.from(`${CLIENT_ID}:rotated-secret`).toString("base64")}`); + }); + + it("refuses machine sign-in on a personal connection", async () => { + const company = await createCompany(); + useProvider(); + const svc = service(); + const created = await svc.createMachineSignIn(company.id, { link: MCP_URL, method: "client_secret", clientId: CLIENT_ID, clientSecret: CLIENT_SECRET }, actor); + await db.update(toolConnections).set({ credentialPolicy: "per_user" }).where(eq(toolConnections.id, created.connectionId)); + await expect(svc.testMachineSignIn(company.id, created.connectionId, {}, actor)) + .rejects.toMatchObject({ status: 422, details: expect.objectContaining({ code: "client_credentials_personal_refused" }) }); + }); + + it("logs setup, verification, rotation and removal without any secret material", async () => { + const company = await createCompany(); + const provider = useProvider(); + const app = express(); + app.use(express.json()); + app.use((req, _res, next) => { + req.actor = { type: "board", userId: "board-user", userName: "Board User", userEmail: null, isInstanceAdmin: true, source: "local_implicit" }; + next(); + }); + app.use("/api", toolAccessRoutes(db, transport)); + app.use(errorHandler); + + const created = await request(app).post(`/api/companies/${company.id}/tools/machine-sign-in`) + .send({ link: MCP_URL, method: "paperclip_key", clientId: CLIENT_ID }); + expect(created.status).toBe(201); + registerKey(provider, created.body.machineSignIn.publicKey); + const connectionId = created.body.connectionId as string; + expect((await request(app).post(`/api/tool-connections/${connectionId}/machine-sign-in/test`).send({})).status).toBe(200); + expect((await request(app).post(`/api/tool-connections/${connectionId}/machine-sign-in/rotate`).send({ method: "client_secret", clientSecret: CLIENT_SECRET })).status).toBe(200); + expect((await request(app).get(`/api/tool-connections/${connectionId}/machine-sign-in`)).body).toMatchObject({ method: "client_secret", hasClientSecret: true }); + expect((await request(app).delete(`/api/tool-connections/${connectionId}`)).status).toBe(200); + + const rows = await db.select().from(activityLog).where(eq(activityLog.entityId, connectionId)); + expect(rows.map((row) => row.action)).toEqual(expect.arrayContaining([ + "tool_connection.machine_sign_in_created", + "tool_connection.machine_sign_in_verified", + "tool_connection.machine_sign_in_rotated", + "tool_connection.archived", + ])); + expect(rows.find((row) => row.action === "tool_connection.archived")?.details).toMatchObject({ machineSignIn: true }); + const logged = JSON.stringify(rows); + expect(logged).not.toContain(CLIENT_SECRET); + expect(logged).not.toContain("PRIVATE KEY"); + expect(logged).not.toContain("machine-token-"); + // Removal destroys the vault entries the connection owned. + const remaining = await db.select({ id: companySecrets.id, status: companySecrets.status }).from(companySecrets) + .where(eq(companySecrets.companyId, company.id)); + expect(remaining.filter((secret) => secret.status === "active")).toEqual([]); + }); + + it("refuses a validation error in plain words", async () => { + const company = await createCompany(); + useProvider(); + await expect(service().createMachineSignIn(company.id, { + link: "https://mcp.example.test/mcp?api_key=abc", method: "client_secret", + }, actor)).rejects.toMatchObject({ status: 400, message: expect.stringContaining("Remove the key from the server address") }); + }); +}); diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.ts index b54469d607c..754c7ab8649 100644 --- a/server/src/routes/openapi.ts +++ b/server/src/routes/openapi.ts @@ -291,6 +291,9 @@ import { workspaceFileResourceQuerySchema, // Tool access connectToolAppSchema, + createMachineSignInSchema, + testMachineSignInSchema, + rotateMachineSignInSchema, configureRailwaySshSchema, createToolApplicationSchema, updateToolApplicationSchema, @@ -12545,6 +12548,68 @@ registerCurrentRoute({ summary: "Archive a tool connection", }); +const MACHINE_SIGN_IN_ERRORS = { + 400: r.badRequest, + 401: r.unauthorized, + 403: r.forbidden, + 404: r.notFound, + 422: r.unprocessable, +}; + +registerCurrentRoute({ + "x-paperclip-transport": "rest", + "x-paperclip-connection-management": "connections:configure", + method: "post", + path: "/api/companies/{companyId}/tools/machine-sign-in", + tags: ["tool-access"], + summary: "Start machine sign-in (OAuth client credentials) for an organization connection", + description: "Creates a draft organization connection to a remote MCP server that signs in as a registered client, with no person involved. With method paperclip_key, Paperclip creates a signing key, keeps the private half in the company vault, and returns the public key to register with the provider. Secrets are write-only.", + body: createMachineSignInSchema, + responses: { 201: r.ok(), ...MACHINE_SIGN_IN_ERRORS }, +}); + +registerCurrentRoute({ + "x-paperclip-transport": "rest", + "x-paperclip-connection-management": "connections:configure", + method: "get", + path: "/api/tool-connections/{connectionId}/machine-sign-in", + tags: ["tool-access"], + summary: "Read a connection's machine sign-in settings (no secret values)", + responses: { 200: r.ok(), ...MACHINE_SIGN_IN_ERRORS }, +}); + +registerCurrentRoute({ + "x-paperclip-transport": "rest", + "x-paperclip-connection-management": "connections:configure", + method: "post", + path: "/api/tool-connections/{connectionId}/machine-sign-in/test", + tags: ["tool-access"], + summary: "Test machine sign-in against the provider and server, then turn the connection on", + body: testMachineSignInSchema, + responses: { 200: r.ok(), ...MACHINE_SIGN_IN_ERRORS }, +}); + +registerCurrentRoute({ + "x-paperclip-transport": "rest", + "x-paperclip-connection-management": "connections:configure", + method: "post", + path: "/api/tool-connections/{connectionId}/machine-sign-in/rotate", + tags: ["tool-access"], + summary: "Replace the machine sign-in key or client secret without downtime", + body: rotateMachineSignInSchema, + responses: { 200: r.ok(), ...MACHINE_SIGN_IN_ERRORS }, +}); + +registerCurrentRoute({ + "x-paperclip-transport": "rest", + "x-paperclip-connection-management": "connections:configure", + method: "post", + path: "/api/tool-connections/{connectionId}/machine-sign-in/rotate/complete", + tags: ["tool-access"], + summary: "Switch to the new machine sign-in key once the provider accepts it", + 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 8faa88e2409..146d1f61b4a 100644 --- a/server/src/routes/tool-access.ts +++ b/server/src/routes/tool-access.ts @@ -23,6 +23,10 @@ import { type ToolConnection, type ToolConnectionCreateCapabilities, connectToolAppSchema, + createMachineSignInSchema, + testMachineSignInSchema, + rotateMachineSignInSchema, + type MachineSignInStatus, configureRailwaySshSchema, createConnectionGrantDelegationSchema, createToolStdioCommandTemplateSchema, @@ -105,6 +109,21 @@ const ORGANIZATION_GRANT_DENIAL_REASON = type Heartbeat = ReturnType; /** Allowlist (e.g. Google Sheets allowed spreadsheet ids) lives in connection config. */ +function asRecord(value: unknown): Record { + return value && typeof value === "object" && !Array.isArray(value) ? value as Record : {}; +} + +/** Activity for machine sign-in carries identifiers only: never a secret, key or token. */ +function machineSignInActivityDetails(status: MachineSignInStatus) { + return { + method: status.method, + issuer: status.issuer, + keyId: status.publicKey?.keyId ?? null, + pendingKeyId: status.pendingPublicKey?.keyId ?? null, + scopeCount: status.scopes.length, + }; +} + function allowlistIds(config: Record | null | undefined): string[] { const raw = config?.allowedSpreadsheetIds; if (!Array.isArray(raw)) return []; @@ -1005,6 +1024,87 @@ function connectorEnrollmentPrincipal(req: Request): string { } }); + // Machine sign-in (MCP OAuth client credentials): organization connections + // that authenticate as a registered client, with no person signing in. + router.post("/companies/:companyId/tools/machine-sign-in", managementGuard("connections:configure", "POST /companies/:companyId/tools/machine-sign-in"), validate(createMachineSignInSchema), async (req, res) => { + const companyId = req.params.companyId as string; + assertToolAppMutationAccess(req, companyId); + if (!await isToolConnectionManagerQuiet(req, companyId)) throw forbidden(ORGANIZATION_GRANT_DENIAL_REASON); + try { + const result = await svc.createMachineSignIn(companyId, req.body, connectionRequestActor(req)); + await logActivity(db, { + companyId, + ...connectionRequestActor(req), + action: "tool_connection.machine_sign_in_created", + entityType: "tool_connection", + entityId: result.connectionId, + details: machineSignInActivityDetails(result.machineSignIn), + }); + res.status(201).json(result); + } catch (error) { + svc.ensureNoDuplicateNameError(error); + } + }); + + router.get("/tool-connections/:connectionId/machine-sign-in", managementGuard("connections:configure", "GET /tool-connections/:connectionId/machine-sign-in"), 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); + res.json(await svc.getMachineSignIn(existing.companyId, existing.id)); + }); + + 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; + await assertToolConnectionConfigureAccess(req, existing); + const result = await svc.testMachineSignIn(existing.companyId, existing.id, req.body, connectionRequestActor(req)); + await logActivity(db, { + companyId: existing.companyId, + ...connectionRequestActor(req), + action: "tool_connection.machine_sign_in_verified", + entityType: "tool_connection", + entityId: existing.id, + details: { + ...machineSignInActivityDetails(await svc.getMachineSignIn(existing.companyId, existing.id)), + clientSecretReplaced: Boolean(req.body.clientSecret), + catalogEntryCount: result.catalog.length, + }, + }); + res.json(result); + }); + + router.post("/tool-connections/:connectionId/machine-sign-in/rotate", managementGuard("connections:configure", "POST /tool-connections/:connectionId/machine-sign-in/rotate"), validate(rotateMachineSignInSchema), 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); + const result = await svc.rotateMachineSignIn(existing.companyId, existing.id, req.body, connectionRequestActor(req)); + await logActivity(db, { + companyId: existing.companyId, + ...connectionRequestActor(req), + action: result.completed ? "tool_connection.machine_sign_in_rotated" : "tool_connection.machine_sign_in_rotation_started", + entityType: "tool_connection", + entityId: existing.id, + details: machineSignInActivityDetails(result.machineSignIn), + }); + res.json(result); + }); + + router.post("/tool-connections/:connectionId/machine-sign-in/rotate/complete", managementGuard("connections:configure", "POST /tool-connections/:connectionId/machine-sign-in/rotate/complete"), 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); + const result = await svc.completeMachineSignInRotation(existing.companyId, existing.id, connectionRequestActor(req)); + await logActivity(db, { + companyId: existing.companyId, + ...connectionRequestActor(req), + action: "tool_connection.machine_sign_in_rotated", + entityType: "tool_connection", + entityId: existing.id, + details: machineSignInActivityDetails(result.machineSignIn), + }); + res.json(result); + }); + router.post( "/companies/:companyId/tools/connections/:connectionId/start-authorization", managementGuard("connections:configure", "POST /companies/:companyId/tools/connections/:connectionId/start-authorization", { personal: true }), validate(startConnectionAuthorizationSchema), @@ -2286,7 +2386,11 @@ function connectorEnrollmentPrincipal(req: Request): string { action: "tool_connection.archived", entityType: "tool_connection", entityId: connection.id, - details: { transport: connection.transport, ...removal }, + details: { + transport: connection.transport, + ...(asRecord(asRecord(existing.config).oauth).grantType === "client_credentials" ? { machineSignIn: true } : {}), + ...removal, + }, }); if (applicationBefore.status !== "archived" && applicationAfter.status === "archived") { await logActivity(db, { diff --git a/server/src/services/mcp-http.ts b/server/src/services/mcp-http.ts index ef7f590d4ce..0a0b1dadbf2 100644 --- a/server/src/services/mcp-http.ts +++ b/server/src/services/mcp-http.ts @@ -36,6 +36,9 @@ const MODERN_ERROR_CODES = new Set([MCP_ERROR_HEADER_MISMATCH, MCP_ERROR_MISSING export const MCP_TASKS_EXTENSION_ID = "io.modelcontextprotocol/tasks"; const MCP_TASK_METHODS = new Set(["tasks/get", "tasks/update", "tasks/cancel"]); +/** MCP OAuth Client Credentials extension; declared only by connections that use machine sign-in. */ +export const MCP_OAUTH_CLIENT_CREDENTIALS_EXTENSION_ID = "io.modelcontextprotocol/oauth-client-credentials"; + const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion"; const META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities"; const META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo"; @@ -54,7 +57,7 @@ export function isModernMcpProtocolVersion(version: unknown): version is string * they may then return URL input requests, which Paperclip shows as a link. * Legacy sessions keep the handshake capabilities they have always received. */ -export function mcpClientCapabilities(protocolVersion: string, options: { declareTasks?: boolean; elicitationForm?: boolean } = {}): Record { +export function mcpClientCapabilities(protocolVersion: string, options: { declareTasks?: boolean; elicitationForm?: boolean; declareClientCredentials?: boolean } = {}): Record { const version: string = protocolVersion; // The skills and tasks extensions are defined against stateless MCP only. // Tasks are declared only where Paperclip can wait on one: a provider tool @@ -66,6 +69,7 @@ export function mcpClientCapabilities(protocolVersion: string, options: { declar return { elicitation: options.elicitationForm ? { form: {}, url: {} } : { url: {} }, extensions: { ...MCP_APPS_CLIENT_CAPABILITY, ...MCP_SKILLS_CLIENT_CAPABILITY, ...(options.declareTasks ? { [MCP_TASKS_EXTENSION_ID]: {} } : {}), + ...(options.declareClientCredentials ? { [MCP_OAUTH_CLIENT_CREDENTIALS_EXTENSION_ID]: {} } : {}), } }; } // 2025-06-18 knows only form questions (`{}`); 2025-11-25 added URL mode. @@ -209,7 +213,7 @@ export type McpJsonRpcRequest = { id?: string | number; method: string; params?: export function mcpHttpRequestInit( headers: Record | undefined, message: McpJsonRpcRequest, - options: { toolInputSchema?: unknown; declareTasks?: boolean; elicitationForm?: boolean; progressToken?: string } = {}, + options: { toolInputSchema?: unknown; declareTasks?: boolean; elicitationForm?: boolean; declareClientCredentials?: boolean; progressToken?: string } = {}, ): { method: "POST"; headers: Record; body: string } { const requestHeaders = mcpHttpRequestHeaders(headers); const protocolVersion = mcpProtocolVersionOf(headers); @@ -222,7 +226,7 @@ export function mcpHttpRequestInit( _meta: { ...record(params._meta), [META_PROTOCOL_VERSION]: protocolVersion, - [META_CLIENT_CAPABILITIES]: mcpClientCapabilities(protocolVersion, { declareTasks: options.declareTasks, elicitationForm: options.elicitationForm }), + [META_CLIENT_CAPABILITIES]: mcpClientCapabilities(protocolVersion, { declareTasks: options.declareTasks, elicitationForm: options.elicitationForm, declareClientCredentials: options.declareClientCredentials }), [META_CLIENT_INFO]: MCP_CLIENT_INFO, }, }; diff --git a/server/src/services/native-runtime/runner-api-sensitive-response.ts b/server/src/services/native-runtime/runner-api-sensitive-response.ts index 97410b665cf..c84d81421c9 100644 --- a/server/src/services/native-runtime/runner-api-sensitive-response.ts +++ b/server/src/services/native-runtime/runner-api-sensitive-response.ts @@ -1,6 +1,6 @@ export function runnerApiSensitiveResponse(method: string, path: string): boolean { if (method === "POST" && /^\/api\/chat-endpoints\/\{[^}]+\}\/setup$/.test(path)) return true; - if (/(\/apps\/connect$|\/email\/connections$|setup-secret|\/github\/(setup|identity\/start)|\/slack\/resume|start-authorization|finalize-oauth-access|\/oauth\/|\/registration|\/managed\/authorize|\/install$|\/login|\/setup-token-login-sessions|\/local\/(attempts|check)(\/|$)|\/test-calls(\/|$))/.test(path)) return true; + if (/(\/apps\/connect$|\/email\/connections$|setup-secret|\/github\/(setup|identity\/start)|\/slack\/resume|start-authorization|finalize-oauth-access|\/machine-sign-in|\/oauth\/|\/registration|\/managed\/authorize|\/install$|\/login|\/setup-token-login-sessions|\/local\/(attempts|check)(\/|$)|\/test-calls(\/|$))/.test(path)) return true; if (/\/secrets\/\{[^}]+\}\/value$/.test(path)) return true; return /^\/api\/tool-gateway\/sessions(?:\/|$)/.test(path) || /^\/api\/companies\/\{[^}]+\}\/exports?(?:\/|$)/.test(path) diff --git a/server/src/services/tool-access.ts b/server/src/services/tool-access.ts index 7bccdf12de7..f11b63d9c2b 100644 --- a/server/src/services/tool-access.ts +++ b/server/src/services/tool-access.ts @@ -45,6 +45,7 @@ import { managedConnectorProfile } from "./tool-access/oauth/client-settings.js" import { createOAuthClientRegistration } from "./tool-access/oauth/client-registration.js"; import { createOAuthRefreshLeases } from "./tool-access/oauth/refresh-leases.js"; import { createLegacyOAuthRefresh } from "./tool-access/oauth/connection-refresh.js"; +import { createClientCredentialsService } from "./tool-access/oauth/client-credentials-service.js"; import { createOAuthGrantRefresh } from "./tool-access/oauth/grant-refresh.js"; import { createGitHubGrantContinuity } from "./tool-access/github-grant-continuity.js"; import { createToolRuntimeHealth } from "./tool-access/runtime/health.js"; @@ -67,7 +68,7 @@ import { createOAuthClientProtocol } from "./tool-access/oauth/client.js"; import type { OAuthClientRegistrationSource } from "./tool-access/oauth/types.js"; export { OAUTH_CLIENT_ID_METADATA_DOCUMENT_PATH, resolveOAuthClientIdMetadataDocumentUrl, oauthClientIdMetadataDocument } from "./tool-access/oauth/client-metadata.js"; -import { connectionMethodFor, connectionMethodForConnection, credentialFieldsFor, normalizeConnectionMethodConfig, projectedConnectionToolInputSchema } from "./tool-access/connection-methods.js"; +import { connectionMethodFor, connectionMethodForConnection, credentialFieldsFor, normalizeConnectionMethodConfig, projectedConnectionHeaders, projectedConnectionToolInputSchema } from "./tool-access/connection-methods.js"; export { normalizeConnectionMethodConfig, projectedConnectionHeaders, @@ -788,8 +789,19 @@ export function toolAccessService( const { syncCredentialBindings, annotateSavedOAuthClientSecret, oauthClientForConnection, createOrRotateOAuthSecret, getOAuthGrantRow, resolveOAuthGrantSecret } = credentialStore; const ensureOAuthClient = createOAuthClientRegistration(db, { now, options, store: credentialStore, getConnectionRow, requestOAuthClientRegistration }); const refreshLeases = createOAuthRefreshLeases(db, now, getConnectionRow, getOAuthGrantRow); - const maybeRefreshOAuthCredentials = createLegacyOAuthRefresh(db, { now, secrets, store: credentialStore, leases: refreshLeases, getConnectionRow, exchangeOAuthToken }); - const refreshOAuthGrantCredentials = createOAuthGrantRefresh(db, { now, store: credentialStore, leases: refreshLeases, currentCloudConnector, getConnectionRow, exchangeOAuthToken }); + // Later dependencies are reached through closures: they are only called at request time. + const clientCredentials = createClientCredentialsService(db, { + now, secrets, store: credentialStore, exchangeOAuthToken, getConnectionRow, fetchRemoteHttpUrl, assertOAuthEndpointUrl, + assertRemoteConnectionEndpointsAllowed, ensureDefaultOrganizationGrant, nextAvailableConnectionName, + checkConnectionHealth: (connectionId, actor) => checkConnectionHealth(connectionId, actor), + refreshCatalog: (connectionId, actor, refreshOptions) => refreshCatalog(connectionId, actor, refreshOptions), + probeServerWithToken: (connection, authorization, actor) => catalogDiscovery.remoteTools( + connection, { ...projectedConnectionHeaders(connection), Authorization: authorization }, actor, undefined, [], { live: true }, + ), + }); + const { requestClientCredentialsToken } = clientCredentials; + const maybeRefreshOAuthCredentials = createLegacyOAuthRefresh(db, { now, secrets, store: credentialStore, leases: refreshLeases, getConnectionRow, exchangeOAuthToken, requestClientCredentialsToken }); + const refreshOAuthGrantCredentials = createOAuthGrantRefresh(db, { now, store: credentialStore, leases: refreshLeases, currentCloudConnector, getConnectionRow, exchangeOAuthToken, requestClientCredentialsToken }); const { refreshManagedGitHubGrantAccess, syncGitHubGrantBindings, sweepGitHubConnectionContinuity, nextGitHubConnectionContinuityAt, githubConnectionContinuitySchedule } = createGitHubGrantContinuity(db, { now, currentCloudConnector, refreshOAuthGrantCredentials, resolveOAuthGrantSecret }); const vercelCredentials = createVercelCredentialService(db, now, vercelConnect); const { resolveVercelCredentialHeaders, vercelGrantForConnection } = vercelCredentials; @@ -3895,6 +3907,12 @@ export function toolAccessService( finishGalleryAppConnection, + createMachineSignIn: clientCredentials.createMachineSignIn, + testMachineSignIn: clientCredentials.testMachineSignIn, + rotateMachineSignIn: clientCredentials.rotateMachineSignIn, + completeMachineSignInRotation: clientCredentials.completeMachineSignInRotation, + getMachineSignIn: clientCredentials.getMachineSignIn, + reconnectGalleryApp, storeConnectorOAuthSecret: createOrRotateOAuthSecret, diff --git a/server/src/services/tool-access/catalog/discovery.ts b/server/src/services/tool-access/catalog/discovery.ts index b7e21d06eb0..70c5145e0e7 100644 --- a/server/src/services/tool-access/catalog/discovery.ts +++ b/server/src/services/tool-access/catalog/discovery.ts @@ -1,4 +1,5 @@ import { assertSupportedConnection } from "../connections/setup-policy.js"; +import { usesClientCredentials } from "../oauth/client-credentials.js"; import { vercelCredentialFor, vercelConnectResourcesFor } from "../vercel-credentials.js"; import { connectionSetupUrl, connectionReconnectUrl } from "../identifiers.js"; import type { ActorInfo } from "../types.js"; @@ -168,7 +169,9 @@ export function createToolCatalogDiscovery(db: Db, { now, audit, secrets, creden const sendRemote = (init: RequestInit) => withMcpConnectionFailure(() => requestRemoteHttpEndpoint(new URL(endpoint), init)); const sendToolsList = (requestHeaders: Record, cursor?: string) => { sessionHeaders = requestHeaders; - return sendRemote(mcpHttpRequestInit(requestHeaders, { id: listRequestId, method: "tools/list", params: cursor ? { cursor } : {} })); + return sendRemote(mcpHttpRequestInit(requestHeaders, { id: listRequestId, method: "tools/list", params: cursor ? { cursor } : {} }, { + declareClientCredentials: usesClientCredentials(connection), + })); }; const connectionConfig = asRecord(connection.config); const sourceTemplateKey = typeof connectionConfig?.sourceTemplateKey === "string" @@ -333,7 +336,10 @@ export function createToolCatalogDiscovery(db: Db, { now, audit, secrets, creden if ( response.status === 401 && connection.authKind === "oauth" && - connection.credentialSource === "paperclip_vault" + connection.credentialSource === "paperclip_vault" && + // A machine sign-in probe with candidate credentials must fail on its own + // answer, not succeed by falling back to the stored ones. + !(credentialHeaders && usesClientCredentials(connection)) ) { headers = { ...projectedConnectionHeaders(connection), @@ -386,6 +392,15 @@ export function createToolCatalogDiscovery(db: Db, { now, audit, secrets, creden connection.credentialSecretRefs.length === 0 && Object.keys(headers).length === 0 && !urlCarriesCredential(sentUrl); + if (response.status === 401 && usesClientCredentials(connection)) { + // Machine sign-in is pinned to the sign-in service recorded at setup. + // Never adopt whatever the server's challenge now advertises. + await response.body?.cancel().catch(() => undefined); + throw unprocessable( + "The server didn't accept this connection's machine sign-in. Test machine sign-in again from the connection's settings.", + { code: "client_credentials_rejected", status: response.status, setupUrl: connectionSetupUrl(connection) }, + ); + } if ( response.status === 401 && (/bearer|oauth|authorization/i.test(authenticate) || diff --git a/server/src/services/tool-access/oauth/client-credentials-service.ts b/server/src/services/tool-access/oauth/client-credentials-service.ts new file mode 100644 index 00000000000..3ef09066467 --- /dev/null +++ b/server/src/services/tool-access/oauth/client-credentials-service.ts @@ -0,0 +1,753 @@ +import { randomUUID } from "node:crypto"; +import { and, eq, ne, sql } from "drizzle-orm"; +import type { Db } from "@paperclipai/db"; +import { connectionGrants, toolApplications, toolConnections } from "@paperclipai/db"; +import type { + ConnectToolAppResult, + ToolCatalogRefreshResult, + ToolConnectionHealthCheckResult, + CreateMachineSignIn, + MachineSignInPublicKey, + MachineSignInSetupResult, + MachineSignInStatus, + RotateMachineSignIn, + TestMachineSignIn, + ToolCredentialSecretRef, +} from "@paperclipai/shared"; +import { badRequest, conflict, HttpError, unprocessable } from "../../../errors.js"; +import { writeConnectionCredential } from "../../connection-credentials.js"; +import { emitConnectionCreated, emitConnectionUpdated } from "../../connector-telemetry.js"; +import { notifyToolConnectionHealth } from "../../tool-connection-health-notifications.js"; +import type { secretService } from "../../secrets.js"; +import { splitRemoteUrlCredential } from "../../remote-url-credentials.js"; +import { connectionActorUserId } from "../actor.js"; +import { toApplication } from "../applications/projection.js"; +import { groupedActions } from "../catalog/action-summary.js"; +import type { createOrganizationGrantStore } from "../connections/organization-grant.js"; +import { toConnection } from "../connections/projection.js"; +import { connectionUid } from "../identifiers.js"; +import type { ActorInfo } from "../types.js"; +import type { createOAuthClientProtocol } from "./client.js"; +import { + CLIENT_PRIVATE_KEY_NEXT_PATH, + CLIENT_PRIVATE_KEY_PATH, + CLIENT_SECRET_PATH, + chooseAssertionAlgorithm, + chooseSecretAuthMethod, + clientCredentialsSettings, + generateClientKeyPair, + publicKeyForPrivateKey, + signClientAssertion, + type ClientCredentialsAuthMethod, + type ClientCredentialsSettings, + type ClientPublicKey, +} from "./client-credentials.js"; +import { actorForSecret, type OAuthCredentialStore } from "./credential-store.js"; +import { + asRecord, + canonicalResourceIndicator, + challengeOAuthHints, + normalizeOauthScopes, + oauthConfig, + protectedResourceMetadataUrls, + sameOAuthIssuer, + wellKnownMetadataUrls, +} from "./metadata.js"; +import { normalizeOAuthProviderError } from "./provider-errors.js"; +import type { OAuthTransport } from "./types.js"; + +type Dependencies = OAuthTransport & { + now: () => Date; + secrets: ReturnType; + store: Pick; + exchangeOAuthToken: ReturnType["exchangeOAuthToken"]; + getConnectionRow(idOrUid: string, companyId?: string): Promise; + assertRemoteConnectionEndpointsAllowed(config: Record): Promise; + ensureDefaultOrganizationGrant: ReturnType; + checkConnectionHealth(connectionId: string, actor?: ActorInfo): Promise; + refreshCatalog(connectionId: string, actor?: ActorInfo, options?: { enableAllByDefault?: boolean }): Promise; + /** List the server's tools with exactly these credentials, never the stored ones. */ + probeServerWithToken(connection: typeof toolConnections.$inferSelect, authorization: string, actor?: ActorInfo): Promise; + nextAvailableConnectionName(requestedName: string, existingNames: readonly string[]): string; +}; + +type DiscoveredSignInService = { + issuer: string | null; + tokenUrl: string; + authMethods: string[]; + signingAlgorithms: string[]; +}; + +type TokenOverrides = { + clientId?: string | null; + clientSecret?: string | null; + scopes?: string[]; + /** Sign with the staged replacement key instead of the current one. */ + usePendingKey?: boolean; + /** Sign with exactly this key (already read from the vault), so the key tested is the key promoted. */ + signingKey?: { privateKeyPem: string; publicKey: ClientPublicKey }; + authMethod?: ClientCredentialsAuthMethod; +}; + +const PERSONAL_REFUSAL = + "Machine sign-in is only for connections your organization shares. Personal connections sign in as you."; + +function issuerChangedError(advertised: string[]) { + const hosts = advertised.map((value) => { + try { return new URL(value).host; } catch { return value; } + }); + return unprocessable( + `This server now sends sign-in to a different service${hosts.length ? ` (${hosts.join(", ")})` : ""}. Paperclip won't send this connection's credentials there. Set up machine sign-in again to trust the new service.`, + { code: "client_credentials_issuer_changed" }, + ); +} + +function machineSignInChangedError() { + return conflict("This connection's machine sign-in changed or was removed while this was running. Reload it and try again.", { + code: "client_credentials_changed", + }); +} + +function rotationChangedError() { + return conflict("The new key changed while the rotation was finishing. Register the key shown now, then try again.", { + code: "client_credentials_rotation_changed", + }); +} + +function toPublicKey(key: ClientPublicKey | null): MachineSignInPublicKey | null { + if (!key) return null; + return { + keyId: key.keyId, + algorithm: key.algorithm, + pem: key.publicKeyPem, + jwk: key.publicJwk as Record, + createdAt: key.createdAt, + }; +} + +export function machineSignInStatus(connection: typeof toolConnections.$inferSelect): MachineSignInStatus { + const settings = clientCredentialsSettings(connection); + if (!settings) throw unprocessable("This connection doesn't use machine sign-in", { code: "client_credentials_not_configured" }); + const oauth = oauthConfig(connection); + return { + connectionId: connection.id, + method: settings.authMethod === "private_key_jwt" ? "paperclip_key" : "client_secret", + clientId: settings.clientId, + issuer: settings.issuer, + tokenUrl: settings.tokenUrl, + scopes: settings.scopes, + publicKey: toPublicKey(settings.key), + pendingPublicKey: toPublicKey(settings.pendingKey), + hasClientSecret: connection.credentialSecretRefs.some((ref) => ref.configPath === CLIENT_SECRET_PATH), + lastTokenAt: typeof oauth.refreshedAt === "string" ? oauth.refreshedAt + : typeof oauth.connectedAt === "string" ? oauth.connectedAt : null, + }; +} + +function scopesFrom(value: string | undefined): string[] | undefined { + return value === undefined ? undefined : normalizeOauthScopes(value.split(/\s+/)); +} + +export function requireClientCredentials( + request: ClientCredentialsService["requestClientCredentialsToken"] | undefined, +): ClientCredentialsService["requestClientCredentialsToken"] { + if (!request) throw new Error("Machine sign-in token requests are not configured for this service"); + return request; +} + +export function createClientCredentialsService(db: Db, deps: Dependencies) { + const { now, secrets, store, exchangeOAuthToken, getConnectionRow, fetchRemoteHttpUrl, assertOAuthEndpointUrl } = deps; + + async function fetchJson(url: string): Promise | null> { + try { + const response = await fetchRemoteHttpUrl(assertOAuthEndpointUrl("metadata", url), { headers: { accept: "application/json" } }); + if (!response.ok) { + await response.body?.cancel().catch(() => undefined); + return null; + } + const parsed = asRecord(await response.json().catch(() => null)); + return Object.keys(parsed).length ? parsed : null; + } catch { + return null; + } + } + + /** RFC 8414 / OIDC metadata for one issuer, accepted only when it names that same issuer. */ + async function signInServiceMetadata(issuer: string): Promise { + for (const url of wellKnownMetadataUrls(issuer)) { + const metadata = await fetchJson(url); + if (!metadata || typeof metadata.token_endpoint !== "string") continue; + if (typeof metadata.issuer !== "string" || !sameOAuthIssuer(metadata.issuer, issuer)) continue; + const grants = normalizeOauthScopes(metadata.grant_types_supported); + if (grants.length > 0 && !grants.includes("client_credentials")) { + throw unprocessable("This sign-in service doesn't offer machine sign-in. Check the provider's docs for a service account option.", { + code: "client_credentials_unsupported", + }); + } + return { + issuer: metadata.issuer.trim(), + tokenUrl: assertOAuthEndpointUrl("token", metadata.token_endpoint), + authMethods: normalizeOauthScopes(metadata.token_endpoint_auth_methods_supported), + signingAlgorithms: normalizeOauthScopes(metadata.token_endpoint_auth_signing_alg_values_supported), + }; + } + return null; + } + + /** The `resource_metadata` address from the server's answer to an unauthenticated request, if any. */ + async function challengedMetadataUrl(serverUrl: string): Promise { + try { + const response = await fetchRemoteHttpUrl(serverUrl, { + method: "POST", + headers: { "content-type": "application/json", accept: "application/json, text/event-stream" }, + body: JSON.stringify({ jsonrpc: "2.0", id: "paperclip-sign-in-probe", method: "server/discover", params: {} }), + }); + await response.body?.cancel().catch(() => undefined); + if (response.status !== 401) return null; + return challengeOAuthHints(response.headers.get("www-authenticate") ?? "").metadataUrl; + } catch { + return null; + } + } + + /** The sign-in services an MCP server's protected-resource metadata lists, or null when it publishes none. */ + async function advertisedSignInServices(serverUrl: string): Promise { + let endpoint: URL; + try { endpoint = new URL(serverUrl); } catch { return null; } + // The server's own challenge may name where its metadata lives; follow + // that (through the same URL checks) before the well-known locations. + const hinted = await challengedMetadataUrl(serverUrl); + for (const url of [...new Set([...(hinted ? [hinted] : []), ...protectedResourceMetadataUrls(endpoint)])]) { + const metadata = await fetchJson(url); + if (!metadata) continue; + const servers = Array.isArray(metadata.authorization_servers) + ? metadata.authorization_servers.filter((value): value is string => typeof value === "string" && value.trim().length > 0) + : []; + if (servers.length > 0) return servers.map((value) => value.trim()); + } + return null; + } + + async function discoverSignInService(serverUrl: string, authorizationServer?: string): Promise { + if (authorizationServer) { + const asIssuer = await signInServiceMetadata(authorizationServer); + if (asIssuer) return asIssuer; + // No metadata at that address: the admin gave the token URL itself. + return { issuer: null, tokenUrl: assertOAuthEndpointUrl("token", authorizationServer), authMethods: [], signingAlgorithms: [] }; + } + for (const issuer of (await advertisedSignInServices(serverUrl)) ?? []) { + const found = await signInServiceMetadata(issuer); + if (found) return found; + } + // A server may be its own sign-in service. + const self = await signInServiceMetadata(new URL(serverUrl).origin); + if (self) return self; + throw unprocessable( + "Paperclip couldn't find this server's sign-in service. Enter the sign-in service address or token URL from the provider's docs.", + { code: "client_credentials_server_not_found" }, + ); + } + + /** + * The issuer pin. A connection's credentials are bound to the sign-in service + * recorded at setup. If the MCP server now advertises other services and not + * that one, refuse rather than follow it. + */ + async function assertPinnedSignInService(connection: typeof toolConnections.$inferSelect, settings: ClientCredentialsSettings) { + if (!settings.issuer) return; + const serverUrl = typeof connection.config.url === "string" ? connection.config.url : null; + if (!serverUrl) return; + const advertised = await advertisedSignInServices(serverUrl); + if (advertised && !advertised.some((issuer) => sameOAuthIssuer(issuer, settings.issuer))) { + throw issuerChangedError(advertised); + } + } + + async function vaultValue(connection: typeof toolConnections.$inferSelect, configPath: string, actor?: ActorInfo) { + const ref = connection.credentialSecretRefs.find((candidate) => candidate.configPath === configPath); + if (!ref) return null; + return secrets.resolveSecretValue(connection.companyId, ref.secretId, ref.versionSelector ?? "latest", { + consumerType: "tool_connection", + consumerId: connection.id, + configPath, + actorType: actor?.actorType ?? "system", + actorId: actor?.actorId ?? null, + }); + } + + /** + * One token request with `grant_type=client_credentials`, authenticated the + * way this connection was set up. Credentials go only to the pinned token + * endpoint; there is no fallback to deployment-wide OAuth clients. + */ + async function requestClientCredentialsToken( + connection: typeof toolConnections.$inferSelect, + actor?: ActorInfo, + overrides: TokenOverrides = {}, + ) { + const settings = clientCredentialsSettings(connection); + if (!settings) throw unprocessable("This connection doesn't use machine sign-in", { code: "client_credentials_not_configured" }); + const clientId = overrides.clientId ?? settings.clientId; + if (!clientId) { + throw unprocessable("Enter the client ID the provider gave you for Paperclip.", { code: "client_credentials_client_id_missing" }); + } + const authMethod = overrides.authMethod ?? settings.authMethod; + const scopes = overrides.scopes ?? settings.scopes; + let clientAssertion: string | null = null; + let clientSecret: string | null = null; + if (authMethod === "private_key_jwt") { + const key = overrides.signingKey?.publicKey ?? (overrides.usePendingKey ? settings.pendingKey : settings.key); + const privateKeyPem = overrides.signingKey?.privateKeyPem + ?? await vaultValue(connection, overrides.usePendingKey ? CLIENT_PRIVATE_KEY_NEXT_PATH : CLIENT_PRIVATE_KEY_PATH, actor); + if (!key || !privateKeyPem) { + throw unprocessable("This connection's Paperclip key is missing. Set up machine sign-in again.", { code: "client_credentials_key_missing" }); + } + // The key ID comes from the private key actually read, never from config + // alone: a refresh that overlaps a rotation may read the new key while + // holding the old settings, and its signature and kid must still agree. + const signing = publicKeyForPrivateKey(privateKeyPem, key.algorithm, new Date(key.createdAt)); + clientAssertion = signClientAssertion({ + privateKeyPem, + algorithm: key.algorithm, + keyId: signing.keyId, + clientId, + audience: settings.tokenUrl, + now: now(), + }); + } else { + clientSecret = overrides.clientSecret ?? await vaultValue(connection, CLIENT_SECRET_PATH, actor); + if (!clientSecret) { + throw unprocessable("Enter the client secret the provider gave you for Paperclip.", { code: "client_credentials_secret_missing" }); + } + } + try { + return await exchangeOAuthToken({ + tokenUrl: settings.tokenUrl, + clientId, + clientSecret, + tokenEndpointAuthMethod: authMethod === "private_key_jwt" ? "none" : authMethod, + clientAssertion, + grantType: "client_credentials", + scopes, + resource: settings.resource, + }); + } catch (error) { + if (!(error instanceof HttpError)) throw error; + const providerError = normalizeOAuthProviderError(asRecord(error.details).providerError); + if (providerError === "invalid_client" || providerError === "unauthorized_client") { + throw unprocessable( + authMethod === "private_key_jwt" + ? "The provider didn't accept Paperclip's key. Check the client ID and that the public key shown here is registered for it." + : "The provider didn't accept the client ID and secret. Check both and try again.", + { code: "client_credentials_rejected", providerError }, + ); + } + if (providerError === "invalid_scope") { + throw unprocessable("The provider refused the requested scopes. Check the scopes in the provider's docs.", { + code: "client_credentials_scope_rejected", + providerError, + }); + } + throw error; + } + } + + function assertOrganizationConnection(connection: typeof toolConnections.$inferSelect) { + if (connection.credentialPolicy !== "shared") throw unprocessable(PERSONAL_REFUSAL, { code: "client_credentials_personal_refused" }); + } + + async function machineSignInConnection(companyId: string, connectionId: string) { + const connection = await getConnectionRow(connectionId, companyId); + if (connection.status === "archived") { + throw unprocessable("This connection was removed. Set up machine sign-in again to reconnect.", { + code: "client_credentials_connection_removed", + }); + } + assertOrganizationConnection(connection); + if (!clientCredentialsSettings(connection)) { + throw unprocessable("This connection doesn't use machine sign-in", { code: "client_credentials_not_configured" }); + } + return connection; + } + + async function writeVaultCredential( + connection: { companyId: string; name: string }, + configPath: string, + label: string, + value: string, + actor: ActorInfo | undefined, + existingRef?: ToolCredentialSecretRef, + ): Promise { + const { secret } = await db.transaction((tx) => writeConnectionCredential(tx, { + companyId: connection.companyId, + connectionName: connection.name, + configPath, + label, + value, + existingRef, + actor: actorForSecret(actor), + })); + return { secretId: secret.id, versionSelector: "latest", configPath, required: false, label }; + } + + async function saveConnection( + previous: typeof toolConnections.$inferSelect, + patch: Partial, + ) { + // Commit only if nothing that decides how this connection signs in changed + // since it was read (a rotation or another test), and it was not removed. + const clientAuth = asRecord(oauthConfig(previous).clientAuth); + const [updated] = await db.update(toolConnections) + .set({ ...patch, ...(patch.config ? { transportConfig: patch.config } : {}), updatedAt: now() }) + .where(and( + eq(toolConnections.id, previous.id), + eq(toolConnections.companyId, previous.companyId), + ne(toolConnections.status, "archived"), + sql`coalesce(${toolConnections.config} -> 'oauth' -> 'clientAuth', '{}'::jsonb) = ${JSON.stringify(clientAuth)}::jsonb`, + sql`${toolConnections.credentialSecretRefs} = ${JSON.stringify(previous.credentialSecretRefs)}::jsonb`, + )) + .returning(); + if (!updated) throw machineSignInChangedError(); + await store.syncCredentialBindings(updated); + if (updated.status === "active") await deps.ensureDefaultOrganizationGrant(updated); + emitConnectionUpdated(updated, previous, "gallery"); + return updated; + } + + async function createMachineSignIn(companyId: string, input: CreateMachineSignIn, actor?: ActorInfo): Promise { + await actor?.managementContext?.reauthorize(); + const split = splitRemoteUrlCredential(input.link); + if (split?.secretUrl) { + throw badRequest("Remove the key from the server address. Machine sign-in sends credentials only to the sign-in service."); + } + const serverUrl = split?.publicUrl ?? input.link; + const config: Record = { url: serverUrl, quarantineNewEntries: false, unverifiedServer: true }; + await deps.assertRemoteConnectionEndpointsAllowed(config); + const service = await discoverSignInService(serverUrl, input.authorizationServer); + const createdAt = now(); + let authMethod: ClientCredentialsAuthMethod; + let generated: Awaited> | null = null; + if (input.method === "paperclip_key") { + if (service.authMethods.length > 0 && !service.authMethods.includes("private_key_jwt")) { + throw unprocessable("This provider doesn't accept Paperclip keys. Choose Client secret instead.", { + code: "client_credentials_key_unsupported", + }); + } + authMethod = "private_key_jwt"; + generated = await generateClientKeyPair(chooseAssertionAlgorithm(service.signingAlgorithms), createdAt); + } else { + if (service.authMethods.length > 0 && !service.authMethods.some((method) => method === "client_secret_basic" || method === "client_secret_post")) { + throw unprocessable("This provider doesn't accept client secrets. Choose Paperclip key instead.", { + code: "client_credentials_secret_unsupported", + }); + } + authMethod = chooseSecretAuthMethod(service.authMethods); + } + config.oauth = { + provider: "client_credentials", + grantType: "client_credentials", + tokenUrl: service.tokenUrl, + issuer: service.issuer, + resource: canonicalResourceIndicator(serverUrl), + scopes: scopesFrom(input.scopes) ?? [], + clientId: input.clientId ?? null, + tokenEndpointAuthMethodsSupported: service.authMethods, + clientAuth: { method: authMethod, ...(generated ? { key: generated.publicKey } : {}), configuredAt: createdAt.toISOString() }, + }; + + const [applicationNames, connectionNames] = await Promise.all([ + db.select({ name: toolApplications.name }).from(toolApplications).where(eq(toolApplications.companyId, companyId)), + db.select({ name: toolConnections.name }).from(toolConnections).where(eq(toolConnections.companyId, companyId)), + ]); + const requestedName = input.name ?? new URL(serverUrl).host.replace(/^www\./, ""); + const name = deps.nextAvailableConnectionName(requestedName, [...applicationNames, ...connectionNames].map((row) => row.name)); + + const credentialSecretRefs: ToolCredentialSecretRef[] = []; + try { + if (generated) { + credentialSecretRefs.push(await writeVaultCredential({ companyId, name }, CLIENT_PRIVATE_KEY_PATH, "Machine sign-in key", generated.privateKeyPem, actor)); + } else if (input.clientSecret) { + credentialSecretRefs.push(await writeVaultCredential({ companyId, name }, CLIENT_SECRET_PATH, "Machine sign-in client secret", input.clientSecret, actor)); + } + const connection = await db.transaction(async (tx) => { + let application: typeof toolApplications.$inferSelect | undefined; + if (input.applicationId) { + [application] = await tx.select().from(toolApplications) + .where(and(eq(toolApplications.id, input.applicationId), eq(toolApplications.companyId, companyId))); + if (!application) throw badRequest("The app for this connection was not found"); + } else { + [application] = await tx.insert(toolApplications).values({ + companyId, + applicationKey: `app-gallery:link:${randomUUID()}`, + name, + description: `Connected app at ${serverUrl}`, + type: "mcp_http", + status: "draft", + metadata: { source: "link" }, + }).returning(); + } + const connectionId = randomUUID(); + const [row] = await tx.insert(toolConnections).values({ + id: connectionId, + companyId, + applicationId: application!.id, + name, + uid: connectionUid(application!.applicationKey ?? application!.name, name, connectionId), + connectionKind: "managed", + ownership: "customer", + authKind: "oauth", + credentialSource: "paperclip_vault", + transport: "mcp_remote", + status: "draft", + enabled: false, + config, + transportConfig: config, + credentialRefs: [], + credentialSecretRefs, + credentialPolicy: "shared", + createdByAgentId: actor?.actorType === "agent" ? (actor.actorId ?? null) : null, + createdByUserId: connectionActorUserId(actor), + }).returning(); + return row!; + }); + await store.syncCredentialBindings(connection); + emitConnectionCreated(connection, "gallery"); + return { connectionId: connection.id, connection: toConnection(connection), machineSignIn: machineSignInStatus(connection) }; + } catch (error) { + // Nothing references these yet; never leave an orphaned key or secret behind. + for (const ref of credentialSecretRefs) await secrets.remove(ref.secretId).catch(() => undefined); + throw error; + } + } + + /** + * Test the settings against the real sign-in service and server, then turn + * the connection on. A failed test leaves the draft (and its key) in place so + * the admin can fix the provider side and try again. + */ + async function testMachineSignIn( + companyId: string, + connectionId: string, + input: TestMachineSignIn, + actor?: ActorInfo, + ): Promise { + await actor?.managementContext?.reauthorize(); + let connection = await machineSignInConnection(companyId, connectionId); + const settings = clientCredentialsSettings(connection)!; + await assertPinnedSignInService(connection, settings); + const scopes = scopesFrom(input.scopes); + const token = await requestClientCredentialsToken(connection, actor, { + clientId: input.clientId, + clientSecret: input.clientSecret, + scopes, + }); + // Prove the server accepts the new client before anything is saved: a client + // the sign-in service accepts may still lack access to this server, and a + // failed retest must leave a working connection's credentials untouched. + await deps.probeServerWithToken(connection, `Bearer ${token.accessToken}`, actor); + // The settings worked: keep them. + const credentialSecretRefs = [...connection.credentialSecretRefs]; + if (input.clientSecret) { + const existing = credentialSecretRefs.find((ref) => ref.configPath === CLIENT_SECRET_PATH); + const ref = await writeVaultCredential(connection, CLIENT_SECRET_PATH, "Machine sign-in client secret", input.clientSecret, actor, existing); + if (!existing) credentialSecretRefs.push(ref); + } + const accessRef = await store.createOrRotateOAuthSecret({ + companyId, + connection, + configPath: "oauth.access_token", + label: "OAuth access token", + value: token.accessToken, + actor, + }); + const at = now(); + const expiresAt = token.expiresIn ? new Date(at.getTime() + token.expiresIn * 1000).toISOString() : null; + const oauth = oauthConfig(connection); + const nextConfig = { + ...connection.config, + oauth: { + ...oauth, + clientId: input.clientId ?? settings.clientId, + scopes: scopes ?? settings.scopes, + expiresAt, + scope: token.scope, + tokenType: token.tokenType, + connectedAt: oauth.connectedAt ?? at.toISOString(), + refreshedAt: at.toISOString(), + }, + }; + connection = await saveConnection(connection, { + config: nextConfig, + credentialSecretRefs: [...credentialSecretRefs.filter((ref) => ref.configPath !== "oauth.access_token"), accessRef], + credentialRefs: [ + ...connection.credentialRefs.filter((ref) => ref.name !== "oauth.access_token"), + { name: "oauth.access_token", secretId: accessRef.secretId, version: "latest", placement: "header", key: "Authorization", prefix: "Bearer " }, + ], + }); + // The organization grant is what tool calls run on; give it the token now, + // with this token's expiry (the grant's own expiry wins over the connection's). + await deps.ensureDefaultOrganizationGrant(connection); + await db.update(connectionGrants).set({ + providerTenant: sql`jsonb_set(coalesce(${connectionGrants.providerTenant}, '{}'::jsonb), '{oauth}', (coalesce(${connectionGrants.providerTenant}->'oauth', '{}'::jsonb) || ${JSON.stringify({ accessTokenExpiresAt: expiresAt, tokenType: token.tokenType, refreshedAt: at.toISOString() })}::jsonb) - 'refreshLease')`, + updatedAt: now(), + }).where(and( + eq(connectionGrants.companyId, companyId), + eq(connectionGrants.connectionId, connection.id), + eq(connectionGrants.kind, "organization"), + eq(connectionGrants.isDefault, true), + )); + await deps.checkConnectionHealth(connection.id, actor); + const before = connection; + connection = await db.transaction(async (tx) => { + await notifyToolConnectionHealth(tx, before); + const [active] = await tx.update(toolConnections) + .set({ status: "active", enabled: true, updatedAt: now() }) + .where(and(eq(toolConnections.id, before.id), eq(toolConnections.companyId, companyId), ne(toolConnections.status, "archived"))) + .returning(); + // Removed while the test ran: never bring it back. + if (!active) throw machineSignInChangedError(); + await tx.update(toolApplications) + .set({ status: "active", updatedAt: now() }) + .where(and(eq(toolApplications.id, before.applicationId), eq(toolApplications.companyId, companyId))); + return active!; + }); + emitConnectionUpdated(connection, before, "gallery"); + const refresh = await deps.refreshCatalog(connection.id, actor, { enableAllByDefault: false }); + const [application] = await db.select().from(toolApplications).where(eq(toolApplications.id, connection.applicationId)); + return { + connectionId: refresh.connection.id, + application: toApplication(application!), + connection: refresh.connection, + catalog: refresh.catalog, + actions: groupedActions(refresh.catalog), + suggestedDefaults: { access: "all_agents", askFirstRiskLevels: [] }, + auth: null, + }; + } + + /** + * Replace the key or secret without downtime. A new secret is tried before it + * replaces the old one. A new key is staged: the current key keeps working + * until the admin registers the new public key and completes the rotation. + */ + async function rotateMachineSignIn( + companyId: string, + connectionId: string, + input: RotateMachineSignIn, + actor?: ActorInfo, + ): Promise { + await actor?.managementContext?.reauthorize(); + const connection = await machineSignInConnection(companyId, connectionId); + const settings = clientCredentialsSettings(connection)!; + const oauth = oauthConfig(connection); + const clientAuth = asRecord(oauth.clientAuth); + if (input.method === "client_secret") { + const authMethod = settings.authMethod === "private_key_jwt" + ? chooseSecretAuthMethod(normalizeOauthScopes(oauth.tokenEndpointAuthMethodsSupported)) + : settings.authMethod; + await assertPinnedSignInService(connection, settings); + await requestClientCredentialsToken(connection, actor, { clientSecret: input.clientSecret, authMethod }); + const existing = connection.credentialSecretRefs.find((ref) => ref.configPath === CLIENT_SECRET_PATH); + const ref = await writeVaultCredential(connection, CLIENT_SECRET_PATH, "Machine sign-in client secret", input.clientSecret, actor, existing); + const retired = connection.credentialSecretRefs.filter((candidate) => + candidate.configPath === CLIENT_PRIVATE_KEY_PATH || candidate.configPath === CLIENT_PRIVATE_KEY_NEXT_PATH); + const updated = await saveConnection(connection, { + config: { ...connection.config, oauth: { ...oauth, clientAuth: { method: authMethod, configuredAt: now().toISOString() } } }, + credentialSecretRefs: [ + ...connection.credentialSecretRefs.filter((candidate) => candidate.configPath !== CLIENT_SECRET_PATH && !retired.includes(candidate)), + ref, + ], + }); + for (const old of retired) await secrets.remove(old.secretId).catch(() => undefined); + return { connectionId, connection: toConnection(updated), machineSignIn: machineSignInStatus(updated), completed: true }; + } + const generated = await generateClientKeyPair(settings.key?.algorithm ?? "RS256", now()); + const existing = connection.credentialSecretRefs.find((ref) => ref.configPath === CLIENT_PRIVATE_KEY_NEXT_PATH); + const ref = await writeVaultCredential(connection, CLIENT_PRIVATE_KEY_NEXT_PATH, "Machine sign-in replacement key", generated.privateKeyPem, actor, existing); + const updated = await saveConnection(connection, { + config: { ...connection.config, oauth: { ...oauth, clientAuth: { ...clientAuth, pendingKey: generated.publicKey } } }, + credentialSecretRefs: [...connection.credentialSecretRefs.filter((candidate) => candidate.configPath !== CLIENT_PRIVATE_KEY_NEXT_PATH), ref], + }); + return { connectionId, connection: toConnection(updated), machineSignIn: machineSignInStatus(updated), completed: false }; + } + + /** Switch to the staged key once the provider accepts it. */ + async function completeMachineSignInRotation( + companyId: string, + connectionId: string, + actor?: ActorInfo, + ): Promise { + await actor?.managementContext?.reauthorize(); + const connection = await machineSignInConnection(companyId, connectionId); + const settings = clientCredentialsSettings(connection)!; + if (!settings.pendingKey) throw unprocessable("There's no new key waiting. Start a key rotation first.", { code: "client_credentials_no_pending_key" }); + await assertPinnedSignInService(connection, settings); + // Read the staged key once and derive its public half from that exact value: + // the key that passes the test is the key that gets promoted, even if + // another rotation replaces the staged key meanwhile. + const pendingValue = await vaultValue(connection, CLIENT_PRIVATE_KEY_NEXT_PATH, actor); + if (!pendingValue) throw unprocessable("The new key is missing. Start the rotation again.", { code: "client_credentials_key_missing" }); + const promoted = publicKeyForPrivateKey(pendingValue, settings.pendingKey.algorithm, new Date(settings.pendingKey.createdAt)); + if (promoted.keyId !== settings.pendingKey.keyId) throw rotationChangedError(); + await requestClientCredentialsToken(connection, actor, { + authMethod: "private_key_jwt", + signingKey: { privateKeyPem: pendingValue, publicKey: promoted }, + }); + const pendingRef = connection.credentialSecretRefs.find((ref) => ref.configPath === CLIENT_PRIVATE_KEY_NEXT_PATH); + // One locked step: the row still stages this key, then the vault and config change together. + const updated = await db.transaction(async (tx) => { + const [locked] = await tx.select().from(toolConnections) + .where(and(eq(toolConnections.id, connection.id), eq(toolConnections.companyId, companyId))) + .for("update"); + const lockedSettings = locked ? clientCredentialsSettings(locked) : null; + if (!locked || lockedSettings?.pendingKey?.keyId !== promoted.keyId) throw rotationChangedError(); + const current = locked.credentialSecretRefs.find((ref) => ref.configPath === CLIENT_PRIVATE_KEY_PATH); + const { secret } = await writeConnectionCredential(tx, { + companyId, connectionName: locked.name, configPath: CLIENT_PRIVATE_KEY_PATH, label: "Machine sign-in key", + value: pendingValue, existingRef: current, actor: actorForSecret(actor), + }); + const keyRef: ToolCredentialSecretRef = { + secretId: secret.id, versionSelector: "latest", configPath: CLIENT_PRIVATE_KEY_PATH, required: false, label: "Machine sign-in key", + }; + const lockedOauth = oauthConfig(locked); + const nextConfig = { + ...locked.config, + oauth: { ...lockedOauth, clientAuth: { method: "private_key_jwt", key: promoted, configuredAt: now().toISOString() } }, + }; + const [row] = await tx.update(toolConnections).set({ + config: nextConfig, + transportConfig: nextConfig, + credentialSecretRefs: [ + ...locked.credentialSecretRefs.filter((ref) => + ref.configPath !== CLIENT_PRIVATE_KEY_PATH && ref.configPath !== CLIENT_PRIVATE_KEY_NEXT_PATH && ref.configPath !== CLIENT_SECRET_PATH), + keyRef, + ], + updatedAt: now(), + }).where(eq(toolConnections.id, locked.id)).returning(); + return row!; + }); + await store.syncCredentialBindings(updated); + if (updated.status === "active") await deps.ensureDefaultOrganizationGrant(updated); + emitConnectionUpdated(updated, connection, "gallery"); + const retired = connection.credentialSecretRefs.filter((ref) => + (ref === pendingRef) || (ref.configPath === CLIENT_SECRET_PATH)); + for (const old of retired) await secrets.remove(old.secretId).catch(() => undefined); + return { connectionId, connection: toConnection(updated), machineSignIn: machineSignInStatus(updated) }; + } + + async function getMachineSignIn(companyId: string, connectionId: string): Promise { + return machineSignInStatus(await machineSignInConnection(companyId, connectionId)); + } + + return { + requestClientCredentialsToken, + assertPinnedSignInService, + createMachineSignIn, + testMachineSignIn, + rotateMachineSignIn, + completeMachineSignInRotation, + getMachineSignIn, + }; +} + +export type ClientCredentialsService = ReturnType; diff --git a/server/src/services/tool-access/oauth/client-credentials.ts b/server/src/services/tool-access/oauth/client-credentials.ts new file mode 100644 index 00000000000..802238d5bcd --- /dev/null +++ b/server/src/services/tool-access/oauth/client-credentials.ts @@ -0,0 +1,188 @@ +import { createHash, createPublicKey, generateKeyPair, randomUUID, sign, type JsonWebKey, type KeyObject } from "node:crypto"; +import type { toolConnections } from "@paperclipai/db"; +import { asRecord, normalizeOauthScopes, oauthConfig } from "./metadata.js"; + +/** + * MCP OAuth Client Credentials extension (2026-07-28): machine-to-machine sign-in + * for organization-owned connections. No person signs in; Paperclip presents a + * client it was registered as, either with a signed assertion (RFC 7523, + * `private_key_jwt`, recommended) or a client secret. + * + * This module is the protocol half: key material, assertions, and how the + * connection records its pinned authorization server. Secret values never live + * here; they are read from the company vault by the caller just before a token + * request and never stored in config. + */ +export const CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"; + +/** Vault paths. The private key and client secret are only ever sent to the pinned token endpoint. */ +export const CLIENT_PRIVATE_KEY_PATH = "oauth.client_private_key"; +export const CLIENT_PRIVATE_KEY_NEXT_PATH = "oauth.client_private_key_next"; +export const CLIENT_SECRET_PATH = "oauth.client_secret"; + +export type ClientCredentialsAuthMethod = "private_key_jwt" | "client_secret_basic" | "client_secret_post"; +export type ClientAssertionAlgorithm = "RS256" | "ES256"; + +/** Public half of a Paperclip-held key, safe to show and to store in config. */ +export type ClientPublicKey = { + keyId: string; + algorithm: ClientAssertionAlgorithm; + publicKeyPem: string; + publicJwk: JsonWebKey; + createdAt: string; +}; + +export type ClientCredentialsSettings = { + clientId: string | null; + tokenUrl: string; + /** Pinned authorization-server issuer. Null when the admin entered a token URL directly. */ + issuer: string | null; + scopes: string[]; + resource: string | null; + authMethod: ClientCredentialsAuthMethod; + key: ClientPublicKey | null; + pendingKey: ClientPublicKey | null; +}; + +function isAuthMethod(value: unknown): value is ClientCredentialsAuthMethod { + return value === "private_key_jwt" || value === "client_secret_basic" || value === "client_secret_post"; +} + +function publicKeyFrom(value: unknown): ClientPublicKey | null { + const record = asRecord(value); + if (typeof record.keyId !== "string" || typeof record.publicKeyPem !== "string") return null; + if (record.algorithm !== "RS256" && record.algorithm !== "ES256") return null; + return { + keyId: record.keyId, + algorithm: record.algorithm, + publicKeyPem: record.publicKeyPem, + publicJwk: asRecord(record.publicJwk) as JsonWebKey, + createdAt: typeof record.createdAt === "string" ? record.createdAt : new Date(0).toISOString(), + }; +} + +/** + * The machine sign-in settings a connection was set up with, or null when the + * connection does not use them. Older env-configured client-credentials rows + * (no `clientAuth`) keep their original path. + */ +export function clientCredentialsSettings( + connection: Pick, +): ClientCredentialsSettings | null { + const oauth = oauthConfig(connection); + if (oauth.grantType !== "client_credentials") return null; + const clientAuth = asRecord(oauth.clientAuth); + if (!isAuthMethod(clientAuth.method) || typeof oauth.tokenUrl !== "string") return null; + return { + clientId: typeof oauth.clientId === "string" && oauth.clientId.trim() ? oauth.clientId.trim() : null, + tokenUrl: oauth.tokenUrl, + issuer: typeof oauth.issuer === "string" && oauth.issuer.trim() ? oauth.issuer.trim() : null, + scopes: normalizeOauthScopes(oauth.scopes), + resource: typeof oauth.resource === "string" && oauth.resource ? oauth.resource : null, + authMethod: clientAuth.method, + key: publicKeyFrom(clientAuth.key), + pendingKey: publicKeyFrom(clientAuth.pendingKey), + }; +} + +export function usesClientCredentials(connection: Pick): boolean { + return clientCredentialsSettings(connection) !== null; +} + +/** Prefer RS256 (the most widely accepted); use ES256 only when the server asks for it. */ +export function chooseAssertionAlgorithm(supported: string[] | undefined): ClientAssertionAlgorithm { + if (!supported?.length || supported.includes("RS256")) return "RS256"; + if (supported.includes("ES256")) return "ES256"; + return "RS256"; +} + +function base64Url(value: Buffer | string): string { + return Buffer.from(value).toString("base64url"); +} + +/** RFC 7638 JWK thumbprint, used as the key ID so it is stable and verifiable. */ +export function jwkThumbprint(jwk: JsonWebKey): string { + const canonical = jwk.kty === "EC" + ? { crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y } + : { e: jwk.e, kty: jwk.kty, n: jwk.n }; + return base64Url(createHash("sha256").update(JSON.stringify(canonical)).digest()); +} + +export function publicKeyForPrivateKey(privateKeyPem: string, algorithm: ClientAssertionAlgorithm, createdAt: Date): ClientPublicKey { + const publicKey = createPublicKey(privateKeyPem); + const exported = publicKey.export({ format: "jwk" }); + const keyId = jwkThumbprint(exported); + return { + keyId, + algorithm, + publicKeyPem: publicKey.export({ format: "pem", type: "spki" }).toString(), + publicJwk: { ...exported, kid: keyId, alg: algorithm, use: "sig" }, + createdAt: createdAt.toISOString(), + }; +} + +function generatePrivateKey(algorithm: ClientAssertionAlgorithm): Promise { + return new Promise((resolve, reject) => { + const done = (error: Error | null, _publicKey: KeyObject, privateKey: KeyObject) => + error ? reject(error) : resolve(privateKey); + if (algorithm === "ES256") generateKeyPair("ec", { namedCurve: "P-256" }, done); + else generateKeyPair("rsa", { modulusLength: 2048 }, done); + }); +} + +/** + * A fresh signing key. The private half goes straight to the vault; only the + * public half is kept in config. Generated off the event loop: RSA key + * generation takes long enough to stall unrelated requests if done inline. + */ +export async function generateClientKeyPair(algorithm: ClientAssertionAlgorithm, now = new Date()): Promise<{ + privateKeyPem: string; + publicKey: ClientPublicKey; +}> { + const privateKey = await generatePrivateKey(algorithm); + const privateKeyPem = privateKey.export({ format: "pem", type: "pkcs8" }).toString(); + return { privateKeyPem, publicKey: publicKeyForPrivateKey(privateKeyPem, algorithm, now) }; +} + +/** Assertions are single-use and short-lived: a captured one is useless a minute later. */ +export const CLIENT_ASSERTION_LIFETIME_SECONDS = 60; + +/** + * RFC 7523 §3 client assertion: `iss` = `sub` = client ID, `aud` = the token + * endpoint it is presented to, a short `exp`, and a unique `jti`. + */ +export function signClientAssertion(input: { + privateKeyPem: string; + algorithm: ClientAssertionAlgorithm; + keyId: string; + clientId: string; + audience: string; + now?: Date; +}): string { + const issuedAt = Math.floor((input.now ?? new Date()).getTime() / 1000); + const header = { alg: input.algorithm, typ: "JWT", kid: input.keyId }; + const claims = { + iss: input.clientId, + sub: input.clientId, + aud: input.audience, + iat: issuedAt, + exp: issuedAt + CLIENT_ASSERTION_LIFETIME_SECONDS, + jti: randomUUID(), + }; + const signingInput = `${base64Url(JSON.stringify(header))}.${base64Url(JSON.stringify(claims))}`; + const signature = sign( + "sha256", + Buffer.from(signingInput), + input.algorithm === "ES256" + ? { key: input.privateKeyPem, dsaEncoding: "ieee-p1363" } + : input.privateKeyPem, + ); + return `${signingInput}.${base64Url(signature)}`; +} + +/** Secret authentication method the server accepts, preferring Basic as the spec requires servers to support it. */ +export function chooseSecretAuthMethod(supported: string[] | undefined): "client_secret_basic" | "client_secret_post" { + if (!supported?.length || supported.includes("client_secret_basic")) return "client_secret_basic"; + if (supported.includes("client_secret_post")) return "client_secret_post"; + return "client_secret_basic"; +} diff --git a/server/src/services/tool-access/oauth/client.ts b/server/src/services/tool-access/oauth/client.ts index 71d1eadea52..d5a1d898e9b 100644 --- a/server/src/services/tool-access/oauth/client.ts +++ b/server/src/services/tool-access/oauth/client.ts @@ -3,6 +3,7 @@ import { asRecord, originOf } from "./metadata.js"; import { normalizeOAuthProviderError, oauthProviderErrorMessage } from "./provider-errors.js"; import type { OAuthProviderEndpoints, OAuthTokenEndpointAuthMethod, OAuthTransport } from "./types.js"; import { oauthApplicationType } from "./client-metadata.js"; +import { CLIENT_ASSERTION_TYPE } from "./client-credentials.js"; const MAX_OAUTH_DCR_CLIENT_ID_LENGTH = 4_096; @@ -309,6 +310,12 @@ export function createOAuthClientProtocol({ fetchRemoteHttpUrl, assertOAuthEndpo refreshToken?: string | null; /** RFC 8707 resource indicator: the MCP server this token is for. */ resource?: string | null; + /** + * RFC 7523 signed client assertion (`private_key_jwt`). When present it is + * the only client authentication sent: the client is identified by the + * assertion's `sub`, so no client_id or secret goes in the request. + */ + clientAssertion?: string | null; }) { const body = new URLSearchParams(); if (input.grantType === "client_credentials") { @@ -324,10 +331,14 @@ export function createOAuthClientProtocol({ fetchRemoteHttpUrl, assertOAuthEndpo body.set("redirect_uri", input.redirectUri ?? ""); body.set("code_verifier", input.codeVerifier ?? ""); } - const tokenEndpointAuthMethod = - input.tokenEndpointAuthMethod ?? - (input.clientSecret ? "client_secret_post" : "none"); - if (tokenEndpointAuthMethod !== "client_secret_basic") + const tokenEndpointAuthMethod = input.clientAssertion + ? "private_key_jwt" + : input.tokenEndpointAuthMethod ?? + (input.clientSecret ? "client_secret_post" : "none"); + if (input.clientAssertion) { + body.set("client_assertion_type", CLIENT_ASSERTION_TYPE); + body.set("client_assertion", input.clientAssertion); + } else if (tokenEndpointAuthMethod !== "client_secret_basic") body.set("client_id", input.clientId); if (tokenEndpointAuthMethod === "client_secret_post") { if (!input.clientSecret) { diff --git a/server/src/services/tool-access/oauth/connection-refresh.ts b/server/src/services/tool-access/oauth/connection-refresh.ts index 4cdf1e8a8e5..c67de010179 100644 --- a/server/src/services/tool-access/oauth/connection-refresh.ts +++ b/server/src/services/tool-access/oauth/connection-refresh.ts @@ -14,6 +14,8 @@ import { withoutOAuthRefreshLease, type OAuthRefreshLeases } from "./refresh-lea import { oauthExpiresAtMs, oauthSecretRef } from "./client-settings.js"; import { connectionSetupUrl, connectionReconnectUrl } from "../identifiers.js"; import { singleFlight } from "../single-flight.js"; +import { usesClientCredentials } from "./client-credentials.js"; +import { requireClientCredentials, type ClientCredentialsService } from "./client-credentials-service.js"; function asRecord(value: unknown): Record { if (value && typeof value === "object" && !Array.isArray(value)) return value as Record; @@ -27,9 +29,11 @@ type LegacyRefreshDependencies = { leases: Pick; getConnectionRow(idOrUid: string, companyId?: string): Promise; exchangeOAuthToken: ReturnType["exchangeOAuthToken"]; + /** Absent only in narrow test harnesses that never use machine sign-in. */ + requestClientCredentialsToken?: ClientCredentialsService["requestClientCredentialsToken"]; }; -export function createLegacyOAuthRefresh(db: Db, { now, secrets, store, leases, getConnectionRow, exchangeOAuthToken }: LegacyRefreshDependencies) { +export function createLegacyOAuthRefresh(db: Db, { now, secrets, store, leases, getConnectionRow, exchangeOAuthToken, requestClientCredentialsToken }: LegacyRefreshDependencies) { // These maps remove duplicate work inside one service instance. OAuth also // uses the database refresh lease below as its cross-process boundary. const oauthRefreshFlights = new Map>(); @@ -138,12 +142,15 @@ const oauthRefreshFlights = new Map>(); }, ); } - const client = await oauthClientForConnection( + // Machine sign-in uses only the connection's own vault credentials and its + // pinned token endpoint, never a deployment-wide client. + const machineSignIn = usesClientCredentials(connection); + const client = machineSignIn ? null : await oauthClientForConnection( connection, oauth.provider, actor, ); - if (!client.clientId) + if (client && !client.clientId) throw unprocessable( `OAuth client id is not configured for ${oauth.provider}`, ); @@ -180,9 +187,9 @@ const oauthRefreshFlights = new Map>(); : null; let token: Awaited>; try { - token = await exchangeOAuthToken({ + token = machineSignIn || !client ? await requireClientCredentials(requestClientCredentialsToken)(connection, actor) : await exchangeOAuthToken({ tokenUrl: oauth.tokenUrl, - clientId: client.clientId, + clientId: client.clientId!, clientSecret: client.clientSecret, tokenEndpointAuthMethod: storedOAuthTokenEndpointAuthMethod( oauth, diff --git a/server/src/services/tool-access/oauth/grant-refresh.ts b/server/src/services/tool-access/oauth/grant-refresh.ts index 87b2dfc5618..e3ee3c79d95 100644 --- a/server/src/services/tool-access/oauth/grant-refresh.ts +++ b/server/src/services/tool-access/oauth/grant-refresh.ts @@ -18,6 +18,8 @@ import { withoutOAuthRefreshLease, type OAuthRefreshLeases } from "./refresh-lea import { managedConnectorProfile, oauthGrantConfig, oauthGrantExpiresAtMs } from "./client-settings.js"; import { connectionSetupUrl, connectionReconnectUrl } from "../identifiers.js"; import { singleFlight } from "../single-flight.js"; +import { usesClientCredentials } from "./client-credentials.js"; +import { requireClientCredentials, type ClientCredentialsService } from "./client-credentials-service.js"; function asRecord(value: unknown): Record { if (value && typeof value === "object" && !Array.isArray(value)) return value as Record; @@ -31,9 +33,11 @@ type GrantRefreshDependencies = { currentCloudConnector: () => PaperclipCloudConnector | null; getConnectionRow(idOrUid: string, companyId?: string): Promise; exchangeOAuthToken: ReturnType["exchangeOAuthToken"]; + /** Absent only in narrow test harnesses that never use machine sign-in. */ + requestClientCredentialsToken?: ClientCredentialsService["requestClientCredentialsToken"]; }; -export function createOAuthGrantRefresh(db: Db, { now, store, leases, currentCloudConnector, getConnectionRow, exchangeOAuthToken }: GrantRefreshDependencies) { +export function createOAuthGrantRefresh(db: Db, { now, store, leases, currentCloudConnector, getConnectionRow, exchangeOAuthToken, requestClientCredentialsToken }: GrantRefreshDependencies) { const oauthGrantRefreshFlights = new Map>(); const { getOAuthGrantRow, resolveOAuthGrantSecret, createOrRotateOAuthSecret, oauthClientForConnection, syncCredentialBindings } = store; const { acquireOAuthGrantRefreshLease, clearOAuthGrantRefreshLease } = leases; @@ -272,10 +276,13 @@ export function createOAuthGrantRefresh(db: Db, { now, store, leases, currentClo if (!lease.leaseId) return lease.grant; try { const grant = lease.grant; - const refreshRef = grant.credentialSecretRefs.find( + // Machine sign-in has no refresh token: it simply asks for a new access + // token with the connection's own client credentials. + const machineSignIn = usesClientCredentials(connection); + const refreshRef = machineSignIn ? undefined : grant.credentialSecretRefs.find( (ref) => ref.configPath === "oauth.refresh_token", ); - if (!refreshRef) { + if (!machineSignIn && !refreshRef) { throw unprocessable( "OAuth credentials have expired and no refresh token is available", { @@ -285,29 +292,32 @@ export function createOAuthGrantRefresh(db: Db, { now, store, leases, currentClo }, ); } - const refreshSecret = await resolveOAuthGrantSecret( + const refreshSecret = refreshRef ? await resolveOAuthGrantSecret( connection, grant, refreshRef, input.actor, input, - ); + ) : null; const credentialActor: ActorInfo | undefined = grant.kind === "user" && grant.subjectUserId ? { actorType: "user", actorId: grant.subjectUserId } : input.actor; - const client = await oauthClientForConnection( - connection, - oauthProvider, - credentialActor, - ); - if (!client.clientId) - throw unprocessable( - `OAuth client id is not configured for ${oauthProvider}`, - ); const grantOauth = oauthGrantConfig(grant); let token: Awaited>; try { + if (machineSignIn) { + token = await requireClientCredentials(requestClientCredentialsToken)(connection, input.actor); + } else { + const client = await oauthClientForConnection( + connection, + oauthProvider, + credentialActor, + ); + if (!client.clientId) + throw unprocessable( + `OAuth client id is not configured for ${oauthProvider}`, + ); token = await exchangeOAuthToken({ tokenUrl: oauthTokenUrl, clientId: client.clientId, @@ -323,14 +333,16 @@ export function createOAuthGrantRefresh(db: Db, { now, store, leases, currentClo : normalizeOauthScopes(oauth.scopes).length > 0 ? normalizeOauthScopes(oauth.scopes) : normalizeOauthScopes(oauth.scope), - refreshToken: refreshSecret.value, + refreshToken: refreshSecret!.value, resource: typeof oauth.resource === "string" && oauth.resource ? oauth.resource : null, }); + } } catch (error) { if ( + refreshRef && refreshSecret && error instanceof HttpError && asRecord(error.details).code === "oauth_reauthorization_required" ) { diff --git a/server/src/services/tool-gateway.ts b/server/src/services/tool-gateway.ts index 7bd6d594bcd..9a2adc2011b 100644 --- a/server/src/services/tool-gateway.ts +++ b/server/src/services/tool-gateway.ts @@ -30,6 +30,7 @@ import { isInsufficientConnectionScope, INSUFFICIENT_CONNECTION_SCOPE_MESSAGE } import { githubAccessDeniedInstructions, githubAccessError } from "./tool-access/github-access-errors.js"; import { githubDefaultOwnerApplies, githubDefaultOwnerArguments } from "./tool-access/github-default-owner.js"; import { toolSourceTemplateKeySql } from "./tool-access/source-template-key.js"; +import { usesClientCredentials } from "./tool-access/oauth/client-credentials.js"; import { boundedMcpToolName } from "./mcp-tool-names.js"; import { browserUseService } from "./browser-use.js"; import { isBrowserUseConnection } from "./browser-use-client.js"; @@ -8037,6 +8038,7 @@ export function createToolGatewayService( progressToken: progressReporter?.token, // A person can answer the app's form questions in the task chat. elicitationForm: Boolean(elicitationCall), + declareClientCredentials: usesClientCredentials(connection), }), redirect: "manual", signal: controller.signal, diff --git a/tests/runner-e2e/source-sdk-public-inputs.json b/tests/runner-e2e/source-sdk-public-inputs.json index 3be3def9c97..46250ab43be 100644 --- a/tests/runner-e2e/source-sdk-public-inputs.json +++ b/tests/runner-e2e/source-sdk-public-inputs.json @@ -268,7 +268,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": "7128882e69b34ebeeefbab5b1ef5f0252c13d4b4", + "packages/shared/src/index.ts": "efab7ad18d89a60ddd3f961e35060b68424ef40b", "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", @@ -408,7 +408,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": "f63f67250d6d5a0b737478c634244ae3aba0328a", + "packages/shared/src/types/index.ts": "8abf1f4ed91e67f8e620a1a0b127799c793554ff", "packages/shared/src/types/instance.ts": "ddabd7cc0d885b5fdf45b33a7937b7b704f8fb7d", "packages/shared/src/types/issue-tree-control.ts": "75489fffd491b8350b05caf57d7796419797d9df", "packages/shared/src/types/issue.ts": "1a59939658d0b28807b8018bacf83a3ded4fef74", @@ -431,7 +431,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": "4c05d176f9bb1d30593fd904c7c4fc3e91b431ca", + "packages/shared/src/types/tool-access.ts": "1d2c29fb7c0c22ae30b53ff18fe44545c18b4835", "packages/shared/src/types/user-profile.ts": "1ac26e033a79fab21dc267fd983959814c8b680f", "packages/shared/src/types/voice-sessions.ts": "95e3b62cdd51f62290e68536728ddd7297bc0459", "packages/shared/src/types/work-product.ts": "26f9129f606a207ce7a218ccef40f96747283086", @@ -485,7 +485,7 @@ "packages/shared/src/validators/folder.ts": "b486444ab09ec3d5a9afec7dbd2e71c1bc2beb67", "packages/shared/src/validators/goal.ts": "602724134915e1e83c50115abba36b288c0abd3d", "packages/shared/src/validators/inbox-agent-policy.ts": "29cef157f4d9b564fd813868038aa8c813df4a7b", - "packages/shared/src/validators/index.ts": "a62024f564b768d87e9b8a2869c0b8b9ce92dc09", + "packages/shared/src/validators/index.ts": "b0bc5449eb5c21fc89064d9d5243223ab33cf5e0", "packages/shared/src/validators/instance.test.ts": "3faa9593a9a05f74429d9b1d2251906a03e9a903", "packages/shared/src/validators/instance.ts": "d801db219659707f0c9a8c1fbad06e862be4892d", "packages/shared/src/validators/issue-chat-bootstrap.test.ts": "e1ebb9aa94da22c825bc3ddd32ce2cfc98bfe645", @@ -520,7 +520,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": "cd28549a930e0b222904bb1121db17659bf12b05", + "packages/shared/src/validators/tool-access.ts": "f6ada4ebdc2d318c0bd50a82dac0692082e03468", "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 9334522137c..2903ec92f1a 100644 --- a/ui/src/api/tools.ts +++ b/ui/src/api/tools.ts @@ -306,6 +306,16 @@ export const toolsApi = { }, connectApp: (companyId: string, input: ConnectToolApp) => 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), + getMachineSignIn: (connectionId: string) => + api.get(`/tool-connections/${connectionId}/machine-sign-in`), + testMachineSignIn: (connectionId: string, input: import("@paperclipai/shared").TestMachineSignIn) => + api.post(`/tool-connections/${connectionId}/machine-sign-in/test`, input), + rotateMachineSignIn: (connectionId: string, input: import("@paperclipai/shared").RotateMachineSignIn) => + api.post(`/tool-connections/${connectionId}/machine-sign-in/rotate`, input), + completeMachineSignInRotation: (connectionId: string) => + api.post(`/tool-connections/${connectionId}/machine-sign-in/rotate/complete`, {}), startOAuth: ( connectionId: string, input: { diff --git a/ui/src/features/connections/ConnectionSetupFlow.tsx b/ui/src/features/connections/ConnectionSetupFlow.tsx index e3ba1e0123d..aa311babc4b 100644 --- a/ui/src/features/connections/ConnectionSetupFlow.tsx +++ b/ui/src/features/connections/ConnectionSetupFlow.tsx @@ -1465,6 +1465,19 @@ function StandardConnectionSetupFlow({ }; const effectiveGrantKind = fixedGrantKind ?? grantKind; + // A connected result (from the link probe or machine sign-in) goes straight to + // review with every discovered action enabled by default. + function acceptConnectedResult(result: ConnectToolAppResult) { + setLinkGuidance(null); + setConnectResult(result); + const defaults: Record = {}; + for (const a of result.actions.readOnly) defaults[a.catalogEntryId] = true; + for (const a of result.actions.canMakeChanges) defaults[a.catalogEntryId] = true; + setEnabled(defaults); + finishMutation.mutate({ result, enabled: defaults }); + } + const acceptMachineSignInResult = acceptConnectedResult; + const connectMutation = useMutation({ mutationFn: async (entryOverride?: AppDefinition) => { if (requiredAgentId && !resumeConnectionId && !reconnectConnectionId @@ -1590,13 +1603,7 @@ function StandardConnectionSetupFlow({ } oauthPopupRef.current?.close(); oauthPopupRef.current = null; - setLinkGuidance(null); - setConnectResult(result); - const defaults: Record = {}; - for (const a of result.actions.readOnly) defaults[a.catalogEntryId] = true; - for (const a of result.actions.canMakeChanges) defaults[a.catalogEntryId] = true; - setEnabled(defaults); - finishMutation.mutate({ result, enabled: defaults }); + acceptConnectedResult(result); }, onError: (error) => { oauthPopupRef.current?.close(); @@ -2826,6 +2833,9 @@ function StandardConnectionSetupFlow({ setLinkGuidance(null); connectApp(); }} + machineSignIn={effectiveGrantKind === "organization" && selectedCompanyId && !reconnectConnectionId + ? { companyId: selectedCompanyId, onConnected: acceptMachineSignInResult } + : null} /> )} diff --git a/ui/src/features/connections/GenericMcpConnectStep.machine.test.tsx b/ui/src/features/connections/GenericMcpConnectStep.machine.test.tsx new file mode 100644 index 00000000000..3304705a9fd --- /dev/null +++ b/ui/src/features/connections/GenericMcpConnectStep.machine.test.tsx @@ -0,0 +1,69 @@ +// @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 { newCustomHeaderRow } from "@/pages/apps/generic-mcp-connect"; +import { GenericMcpConnectStep } from "./GenericMcpConnectStep"; + +vi.mock("@/api/tools", () => ({ toolsApi: {} })); +vi.mock("@/pages/apps/AppLogo", () => ({ AppLogo: () => null })); + +describe("Machine sign-in in the custom server step", () => { + let root: Root; + let container: HTMLDivElement; + + beforeEach(() => { + container = document.createElement("div"); + document.body.append(container); + root = createRoot(container); + }); + afterEach(() => { + act(() => root.unmount()); + container.remove(); + }); + + async function render(machineSignIn: { companyId: string; onConnected: () => void } | null) { + await act(async () => { + root.render( + undefined} + authMode="auto" onAuthModeChange={() => undefined} headers={[newCustomHeaderRow()]} onHeadersChange={() => undefined} + oauthClientId="" onOAuthClientIdChange={() => undefined} oauthClientSecret="" onOAuthClientSecretChange={() => undefined} + advancedOpen onAdvancedOpenChange={() => undefined} guidance={null} submitting={false} + onBack={() => undefined} onConnect={() => undefined} machineSignIn={machineSignIn} + defaults={

Connects for every agent. Change

} + />, + ); + }); + } + const buttons = () => [...container.querySelectorAll("button")].map((button) => button.textContent ?? ""); + + it("is offered for organization connections and replaces Check link with its own setup", async () => { + await render({ companyId: "company-1", onConnected: () => undefined }); + const option = [...container.querySelectorAll('[role="radio"]')].find((item) => item.textContent?.includes("Machine sign-in")); + expect(option).toBeDefined(); + expect(buttons()).toContain("Check link"); + await act(async () => { (option as HTMLElement).click(); }); + expect(container.querySelector('[data-testid="machine-sign-in-setup"]')).not.toBeNull(); + expect(buttons()).not.toContain("Check link"); + expect(buttons()).toContain("Create key"); + // Who gets access stays visible and changeable while machine setup is open. + expect(container.querySelector('[data-testid="access-defaults"]')).not.toBeNull(); + }); + + it("keeps machine sign-in open when arrow keys move its own method choice", async () => { + await render({ companyId: "company-1", onConnected: () => undefined }); + const option = [...container.querySelectorAll('[role="radio"]')].find((item) => item.textContent?.includes("Machine sign-in")); + await act(async () => { (option as HTMLElement).click(); }); + const inner = [...container.querySelectorAll('[role="radio"]')].find((item) => item.textContent === "Paperclip key (recommended)") as HTMLElement; + await act(async () => { inner.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true })); }); + expect(container.querySelector('[data-testid="machine-sign-in-setup"]')).not.toBeNull(); + const secret = [...container.querySelectorAll('[role="radio"]')].find((item) => item.textContent === "Client secret"); + expect(secret?.getAttribute("aria-checked")).toBe("true"); + }); + + it("is not offered for personal connections", async () => { + await render(null); + expect(container.textContent).not.toContain("Machine sign-in"); + }); +}); diff --git a/ui/src/features/connections/GenericMcpConnectStep.tsx b/ui/src/features/connections/GenericMcpConnectStep.tsx index 40e4b14759a..34dc87c8c9d 100644 --- a/ui/src/features/connections/GenericMcpConnectStep.tsx +++ b/ui/src/features/connections/GenericMcpConnectStep.tsx @@ -1,6 +1,6 @@ import { useState, type KeyboardEvent, type ReactNode } from "react"; import { Loader2, Plus, X } from "lucide-react"; -import type { AppDefinition } from "@paperclipai/shared"; +import type { AppDefinition, ConnectToolAppResult } from "@paperclipai/shared"; import { InlineBanner } from "@/components/InlineBanner"; import { Button } from "@/components/ui/button"; import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible"; @@ -8,6 +8,7 @@ import { Input } from "@/components/ui/input"; import { RadioCard } from "@/components/ui/radio-card"; import { redactUrlSecrets } from "@/lib/redact-url-secrets"; import { AppLogo } from "@/pages/apps/AppLogo"; +import { MachineSignInSetup } from "./MachineSignInSetup"; import { canSubmitGenericConnect, customHeaderError, @@ -112,6 +113,7 @@ export function GenericMcpConnectStep({ defaults, onBack, onConnect, + machineSignIn, }: { link: string; name: string; @@ -138,8 +140,13 @@ export function GenericMcpConnectStep({ defaults?: ReactNode; onBack: () => void; onConnect: () => void; + /** Offered only for organization connections: personal connections sign in as the person. */ + machineSignIn?: { companyId: string; onConnected: (result: ConnectToolAppResult) => void } | null; }) { const [clientFieldsOpen, setClientFieldsOpen] = useState(false); + // Machine sign-in runs its own setup and test, so it is a choice beside the modes, not one of them. + const [machineSelected, setMachineSelected] = useState(false); + const machine = Boolean(machineSelected && machineSignIn); const headerError = authMode === "custom_headers" ? customHeaderError(headers) : null; const canSubmit = canSubmitGenericConnect({ link, @@ -156,7 +163,7 @@ export function GenericMcpConnectStep({ // Stay open while the chosen option still needs something typed into it, so // a disabled primary action always has its reason on screen. const choiceNeedsInput = (authMode === "bearer" || authMode === "custom_headers") && !canSubmit; - const expanded = advancedOpen || choiceNeedsInput; + const expanded = advancedOpen || choiceNeedsInput || machine; const showClientFields = clientFieldsOpen || oauthClientId.trim().length > 0 || oauthClientSecret.trim().length > 0 @@ -169,6 +176,8 @@ export function GenericMcpConnectStep({ const moveSelection = (event: KeyboardEvent) => { // Arrow keys inside an option's own fields belong to that field. if ((event.target as HTMLElement).getAttribute("role") !== "radio") return; + // Only this group's own options: a nested choice (machine sign-in's) handles its own keys. + if ((event.target as HTMLElement).closest('[role="radiogroup"]') !== event.currentTarget) return; const step = event.key === "ArrowDown" || event.key === "ArrowRight" ? 1 : event.key === "ArrowUp" || event.key === "ArrowLeft" @@ -176,9 +185,14 @@ export function GenericMcpConnectStep({ : 0; if (step === 0) return; event.preventDefault(); - const index = AUTH_OPTIONS.findIndex((option) => option.mode === authMode); - const next = (index + step + AUTH_OPTIONS.length) % AUTH_OPTIONS.length; - onAuthModeChange(AUTH_OPTIONS[next]!.mode); + const count = AUTH_OPTIONS.length + (machineSignIn ? 1 : 0); + const index = machine ? AUTH_OPTIONS.length : AUTH_OPTIONS.findIndex((option) => option.mode === authMode); + const next = (index + step + count) % count; + if (next === AUTH_OPTIONS.length) setMachineSelected(true); + else { + setMachineSelected(false); + onAuthModeChange(AUTH_OPTIONS[next]!.mode); + } event.currentTarget.querySelectorAll('[role="radio"]')[next]?.focus(); }; @@ -353,7 +367,7 @@ export function GenericMcpConnectStep({ type="button" variant="link" className="h-auto p-0 text-xs font-semibold underline underline-offset-2" - disabled={submitting || choiceNeedsInput} + disabled={submitting || choiceNeedsInput || machine} data-testid="generic-mcp-sign-in-toggle" > {expanded ? "Done" : "Change"} @@ -368,7 +382,7 @@ export function GenericMcpConnectStep({ onKeyDown={moveSelection} > {AUTH_OPTIONS.map((option) => { - const selected = option.mode === authMode; + const selected = !machine && option.mode === authMode; const fields = selected ? optionFields(option.mode) : null; return (
@@ -379,27 +393,60 @@ export function GenericMcpConnectStep({ tabIndex={selected ? 0 : -1} disabled={submitting} className="bg-background" - onClick={() => onAuthModeChange(option.mode)} + onClick={() => { + setMachineSelected(false); + onAuthModeChange(option.mode); + }} /> {fields ?
{fields}
: null}
); })} + {machineSignIn ? ( +
+ setMachineSelected(true)} + /> + {machine ? ( +
+ +
+ ) : null} +
+ ) : null} - {defaults} + {/* Machine sign-in owns its footer (Test connection, not Check link) and shows the access line above it. */} + {machine ? null : ( + <> + {defaults} -
- - -
+
+ + +
+ + )} ); } diff --git a/ui/src/features/connections/MachineSignInSetup.test.tsx b/ui/src/features/connections/MachineSignInSetup.test.tsx new file mode 100644 index 00000000000..3dd8b219370 --- /dev/null +++ b/ui/src/features/connections/MachineSignInSetup.test.tsx @@ -0,0 +1,137 @@ +// @vitest-environment jsdom +import { act } from "react"; +import { createRoot, type Root } from "react-dom/client"; +import type { ConnectToolAppResult, MachineSignInSetupResult } from "@paperclipai/shared"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { MachineSignInSetup, type MachineSignInClient } from "./MachineSignInSetup"; + +vi.mock("@/api/tools", () => ({ toolsApi: {} })); + +const draft = { + connectionId: "connection-1", + connection: {}, + machineSignIn: { + connectionId: "connection-1", method: "paperclip_key", clientId: null, issuer: "https://auth.example", tokenUrl: "https://auth.example/token", + scopes: [], hasClientSecret: false, lastTokenAt: null, pendingPublicKey: null, + publicKey: { keyId: "kid-1", algorithm: "RS256", pem: "-----BEGIN PUBLIC KEY-----\nabc\n-----END PUBLIC KEY-----\n", jwk: { kty: "RSA", kid: "kid-1" }, createdAt: "2026-11-13T00:00:00Z" }, + }, +} as unknown as MachineSignInSetupResult; + +describe("Machine sign-in setup", () => { + let root: Root; + let container: HTMLDivElement; + const flush = async () => { await act(async () => { await new Promise((resolve) => setTimeout(resolve, 0)); }); }; + const button = (name: string) => [...container.querySelectorAll("button")].find((item) => item.textContent === name); + const click = async (name: string) => { await act(async () => { button(name)!.click(); }); await flush(); }; + const type = async (id: string, value: string) => { + const input = container.querySelector(`#${id}`)!; + await act(async () => { + Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!.call(input, value); + input.dispatchEvent(new Event("input", { bubbles: true })); + }); + }; + + beforeEach(() => { + container = document.createElement("div"); + document.body.append(container); + root = createRoot(container); + }); + afterEach(() => { + act(() => root.unmount()); + container.remove(); + }); + + it("creates a key, shows the public key to register, then tests with the client ID", async () => { + const client: MachineSignInClient = { + create: vi.fn(async () => draft), + test: vi.fn(async () => ({ connectionId: "connection-1" }) as ConnectToolAppResult), + status: vi.fn(), + }; + const onConnected = vi.fn(); + await act(async () => { + root.render( undefined} onConnected={onConnected} />); + }); + expect(container.textContent).toContain("Paperclip key (recommended)"); + await click("Create key"); + expect(client.create).toHaveBeenCalledWith("company-1", { link: "https://mcp.example/mcp", method: "paperclip_key" }); + expect(container.textContent).toContain("Register this public key"); + expect(container.querySelector("textarea")?.value).toContain("BEGIN PUBLIC KEY"); + expect(button("Test connection")?.disabled).toBe(true); + await type("machine-sign-in-client-id-confirm", "paperclip-automation"); + await click("Test connection"); + expect(client.test).toHaveBeenCalledWith("connection-1", { clientId: "paperclip-automation", scopes: "" }); + expect(onConnected).toHaveBeenCalled(); + }); + + it("keeps the draft and shows the provider's answer when the test fails", async () => { + const client: MachineSignInClient = { + create: vi.fn(async () => draft), + test: vi.fn(async () => { throw new Error("The provider didn't accept Paperclip's key."); }), + status: vi.fn(), + }; + await act(async () => { + root.render( undefined} onConnected={() => undefined} />); + }); + await type("machine-sign-in-client-id-confirm", "wrong"); + await click("Test connection"); + expect(container.textContent).toContain("Machine sign-in didn’t work"); + expect(container.textContent).toContain("The provider didn't accept Paperclip's key."); + expect(container.textContent).toContain("Register this public key"); + }); + + it("asks for the client ID and secret together for a client secret", async () => { + const client: MachineSignInClient = { + create: vi.fn(async () => ({ ...draft, machineSignIn: { ...draft.machineSignIn, method: "client_secret" as const, publicKey: null } })), + test: vi.fn(async () => ({}) as ConnectToolAppResult), + status: vi.fn(), + }; + await act(async () => { + root.render( undefined} onConnected={() => undefined} />); + }); + expect(button("Test connection")?.disabled).toBe(true); + await type("machine-sign-in-client-id", "id-1"); + await type("machine-sign-in-client-secret", "secret-1"); + await click("Test connection"); + expect(client.create).toHaveBeenCalledWith("company-1", expect.objectContaining({ method: "client_secret", clientId: "id-1", clientSecret: "secret-1" })); + expect(client.test).toHaveBeenCalledWith("connection-1", { clientId: "id-1", scopes: "" }); + }); + + it("lets a wrong secret be replaced after a failed test", async () => { + const secretDraft = { ...draft, machineSignIn: { ...draft.machineSignIn, method: "client_secret" as const, publicKey: null, clientId: "id-1", hasClientSecret: true, scopes: ["a.read"] } }; + const client: MachineSignInClient = { + create: vi.fn(), + test: vi.fn(async () => { throw new Error("The provider didn't accept the client ID and secret."); }), + status: vi.fn(), + }; + await act(async () => { + root.render( undefined} onConnected={() => undefined} />); + }); + await click("Test connection"); + expect(container.querySelector("#machine-sign-in-client-secret-replace")).not.toBeNull(); + await type("machine-sign-in-client-secret-replace", "fixed-secret"); + await type("machine-sign-in-scopes-confirm", ""); + await click("Test connection"); + expect(client.test).toHaveBeenLastCalledWith("connection-1", { clientId: "id-1", scopes: "", clientSecret: "fixed-secret" }); + }); + + it("resumes the key draft this tab started instead of creating another", async () => { + sessionStorage.setItem("paperclip.machine-sign-in-draft:company-1:https://mcp.example/mcp", "connection-1"); + let finish!: (value: typeof draft.machineSignIn) => void; + const client: MachineSignInClient = { + create: vi.fn(), + test: vi.fn(), + status: vi.fn(() => new Promise((resolve) => { finish = resolve; })), + }; + await act(async () => { + root.render( undefined} onConnected={() => undefined} />); + }); + // No second draft can be started while the saved one loads. + expect(button("Create key")?.disabled).toBe(true); + await act(async () => { finish(draft.machineSignIn); }); + await flush(); + expect(client.status).toHaveBeenCalledWith("connection-1"); + expect(container.textContent).toContain("Register this public key"); + expect(client.create).not.toHaveBeenCalled(); + sessionStorage.clear(); + }); +}); diff --git a/ui/src/features/connections/MachineSignInSetup.tsx b/ui/src/features/connections/MachineSignInSetup.tsx new file mode 100644 index 00000000000..98f29980b62 --- /dev/null +++ b/ui/src/features/connections/MachineSignInSetup.tsx @@ -0,0 +1,324 @@ +import { useEffect, useState } from "react"; +import { Loader2 } from "lucide-react"; +import type { + ConnectToolAppResult, + CreateMachineSignIn, + MachineSignInMethod, + MachineSignInSetupResult, + MachineSignInStatus, + TestMachineSignIn, +} from "@paperclipai/shared"; +import { toolsApi } from "@/api/tools"; +import { describeError } from "@/api/errors"; +import { InlineBanner } from "@/components/InlineBanner"; +import { Button } from "@/components/ui/button"; +import { Input } from "@/components/ui/input"; +import { Textarea } from "@/components/ui/textarea"; +import { cn } from "@/lib/utils"; +import { copyTextToClipboard } from "@/lib/clipboard"; + +/** The calls this setup makes. Stories pass in-memory fakes. */ +export interface MachineSignInClient { + create(companyId: string, input: CreateMachineSignIn): Promise; + test(connectionId: string, input: TestMachineSignIn): Promise; + status(connectionId: string): Promise; +} + +export const machineSignInApiClient: MachineSignInClient = { + create: (companyId, input) => toolsApi.createMachineSignIn(companyId, input), + test: (connectionId, input) => toolsApi.testMachineSignIn(connectionId, input), + status: (connectionId) => toolsApi.getMachineSignIn(connectionId), +}; + +type MachineSignInDraft = Pick; + +/** + * The draft this browser tab started for a server, so switching options or + * reloading resumes it (and its key) instead of creating another. + */ +function draftStorageKey(companyId: string, link: string) { + return `paperclip.machine-sign-in-draft:${companyId}:${link}`; +} +function readDraftId(key: string): string | null { + try { return sessionStorage.getItem(key); } catch { return null; } +} +function writeDraftId(key: string, connectionId: string | null) { + try { + if (connectionId) sessionStorage.setItem(key, connectionId); + else sessionStorage.removeItem(key); + } catch { /* storage unavailable: the draft is still listed in Apps */ } +} + +const METHOD_OPTIONS: Array<{ method: MachineSignInMethod; label: string; hint: string }> = [ + { + method: "paperclip_key", + label: "Paperclip key (recommended)", + hint: "Paperclip creates a key and keeps its private half. You register the public key with the provider; nothing secret is copied.", + }, + { + method: "client_secret", + label: "Client secret", + hint: "For providers that only issue a secret. Paperclip stores it securely and never shows it again.", + }, +]; + +export interface MachineSignInSetupProps { + companyId: string; + link: string; + name?: string; + client?: MachineSignInClient; + /** Resume at "register the key" with a key Paperclip already created. */ + initialSetup?: MachineSignInSetupResult | null; + initialMethod?: MachineSignInMethod; + initialError?: string | null; + onBack: () => void; + onConnected: (result: ConnectToolAppResult) => void; + /** Shown above the footer, such as who gets access to the connection. */ + beforeFooter?: React.ReactNode; +} + +/** + * Machine sign-in for an organization connection: the server's provider issues + * Paperclip a client of its own, so no person signs in. With a Paperclip key the + * admin registers the public key we show; with a client secret they paste it. + * Either way the last step is a real test against the provider and the server. + */ +export function MachineSignInSetup({ + companyId, + link, + name, + client = machineSignInApiClient, + initialSetup = null, + initialMethod = "paperclip_key", + initialError = null, + onBack, + onConnected, + beforeFooter, +}: MachineSignInSetupProps) { + const [method, setMethod] = useState(initialSetup?.machineSignIn.method ?? initialMethod); + const [signInService, setSignInService] = useState(""); + const [clientId, setClientId] = useState(initialSetup?.machineSignIn.clientId ?? ""); + const [clientSecret, setClientSecret] = useState(""); + const [scopes, setScopes] = useState(initialSetup?.machineSignIn.scopes.join(" ") ?? ""); + const [setup, setSetup] = useState(initialSetup); + const [error, setError] = useState(initialError); + const [busy, setBusy] = useState<"creating" | "testing" | null>(null); + const storageKey = draftStorageKey(companyId, link); + // While a saved draft loads, creating another would race it; wait for it. + const [restoring, setRestoring] = useState(() => !initialSetup && Boolean(readDraftId(storageKey))); + + useEffect(() => { + if (initialSetup) return; + const draftId = readDraftId(storageKey); + if (!draftId) return; + let cancelled = false; + setRestoring(true); + client.status(draftId).then((status) => { + if (cancelled) return; + setSetup({ connectionId: draftId, machineSignIn: status }); + setMethod(status.method); + setClientId((current) => current || (status.clientId ?? "")); + setScopes((current) => current || status.scopes.join(" ")); + }, () => writeDraftId(storageKey, null)).finally(() => { + if (!cancelled) setRestoring(false); + }); + return () => { cancelled = true; }; + }, [client, initialSetup, storageKey]); + + const trimmedScopes = scopes.trim(); + const canCreate = method === "paperclip_key" || (clientId.trim().length > 0 && clientSecret.length > 0); + const canTest = clientId.trim().length > 0; + + async function createDraft(): Promise { + setBusy("creating"); + setError(null); + try { + const created = await client.create(companyId, { + link, + ...(name?.trim() ? { name: name.trim() } : {}), + ...(signInService.trim() ? { authorizationServer: signInService.trim() } : {}), + method, + ...(clientId.trim() ? { clientId: clientId.trim() } : {}), + ...(method === "client_secret" && clientSecret ? { clientSecret } : {}), + ...(trimmedScopes ? { scopes: trimmedScopes } : {}), + }); + setSetup(created); + writeDraftId(storageKey, created.connectionId); + // The secret is saved with the draft; a later test only sends a replacement. + setClientSecret(""); + return created; + } catch (caught) { + setError(describeError(caught).body); + return null; + } finally { + setBusy(null); + } + } + + /** `replacementSecret` is sent only when the admin typed a new one after the draft was saved. */ + async function testConnection(target: MachineSignInDraft, replacementSecret: string) { + setBusy("testing"); + setError(null); + try { + const result = await client.test(target.connectionId, { + clientId: clientId.trim(), + // Always sent, so clearing the field clears the saved scopes. + scopes: trimmedScopes, + ...(target.machineSignIn.method === "client_secret" && replacementSecret ? { clientSecret: replacementSecret } : {}), + }); + writeDraftId(storageKey, null); + onConnected(result); + } catch (caught) { + setError(describeError(caught).body); + } finally { + setBusy(null); + } + } + + const host = (() => { + try { return new URL(link).host; } catch { return link; } + })(); + const publicKey = setup?.machineSignIn.publicKey ?? null; + + return ( +
+

+ For automation your organization owns. Agents use this connection as the provider client you set up for + Paperclip, not as any person. Only shared connections can use machine sign-in. +

+ + {error ? {error} : null} + + {!setup ? ( +
+
{ + const step = event.key === "ArrowRight" || event.key === "ArrowDown" ? 1 + : event.key === "ArrowLeft" || event.key === "ArrowUp" ? -1 : 0; + if (step === 0) return; + event.preventDefault(); + event.stopPropagation(); + const index = METHOD_OPTIONS.findIndex((option) => option.method === method); + const next = (index + step + METHOD_OPTIONS.length) % METHOD_OPTIONS.length; + setMethod(METHOD_OPTIONS[next]!.method); + event.currentTarget.querySelectorAll('[role="radio"]')[next]?.focus(); + }} + > + {METHOD_OPTIONS.map((option) => ( + + ))} +
+

{METHOD_OPTIONS.find((option) => option.method === method)?.hint}

+ + setSignInService(event.target.value)} placeholder="Found automatically" autoComplete="off" className="h-11 font-mono" /> + + + setClientId(event.target.value)} autoComplete="off" className="h-11 font-mono" /> + + {method === "client_secret" ? ( + + setClientSecret(event.target.value)} autoComplete="off" className="h-11 font-mono" /> + + ) : null} + + setScopes(event.target.value)} placeholder="Optional" autoComplete="off" className="h-11 font-mono" /> + +
+ ) : ( +
+ {publicKey ? ( +
+

+ Register this public key with the provider for the Paperclip client. It isn’t secret, so you can paste it + into the provider’s console or send it to whoever manages it. +

+ + +
+ ) : null} + + setClientId(event.target.value)} autoComplete="off" className="h-11 font-mono" /> + + {setup.machineSignIn.method === "client_secret" ? ( + + setClientSecret(event.target.value)} placeholder={setup.machineSignIn.hasClientSecret ? "••••••••" : ""} autoComplete="off" className="h-11 font-mono" /> + + ) : null} + + setScopes(event.target.value)} autoComplete="off" className="h-11 font-mono" /> + +
+ )} + + {beforeFooter} + +
+ + {!setup && method === "paperclip_key" ? ( + + ) : ( + + )} +
+
+ ); +} + +function Field({ id, label, hint, children }: { id: string; label: string; hint?: string; children: React.ReactNode }) { + return ( +
+ +
{children}
+ {hint ?

{hint}

: null} +
+ ); +} + +function PublicKeyBlock({ label, value }: { label: string; value: string }) { + const [copied, setCopied] = useState(false); + return ( +
+
+ {label} + +
+