feat(connections): machine sign-in (MCP OAuth client credentials) for organization connections (#21473)

## 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 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-14 03:10:32 +00:00
1 parent 6b631dd477
commit f6c5986b61
29 files changed
+2861 -67

No files matched your search

+5 -1
View File
@@ -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.
+129
View File
@@ -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.
+7 -2
View File
@@ -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).
+12
View File
@@ -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,
+3
View File
@@ -525,6 +525,9 @@ export type {
ToolAccessSelector,
ConnectToolAppAuthChallenge,
ConnectToolAppResult,
MachineSignInPublicKey,
MachineSignInStatus,
MachineSignInSetupResult,
ToolAppMetadataPreflightAttempt,
ToolAppMetadataPreflightResult,
FinishToolAppResult,
+33
View File
@@ -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<string, unknown>;
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;
+9
View File
@@ -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,
@@ -372,6 +372,45 @@ export const genericMcpOAuthClientSchema = z.object({
export type GenericMcpOAuthClient = z.infer<typeof genericMcpOAuthClientSchema>;
/**
* 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<typeof machineSignInMethodSchema>;
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<typeof createMachineSignInSchema>;
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<typeof testMachineSignInSchema>;
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<typeof rotateMachineSignInSchema>;
/**
* Reject `headers.*` credential paths whose header name Paperclip refuses to
* send, and any value that could split the outbound request. This runs at the
@@ -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<string, unknown>,
claims: JSON.parse(Buffer.from(claims!, "base64url").toString()) as Record<string, unknown>,
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<string, string> = {}) {
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<string, KeyObject>(),
clientSecret: CLIENT_SECRET,
tokenRequests: [] as Array<{ url: string; body: URLSearchParams; authorization: string | null }>,
otherIssuerRequests: 0,
mcpRequests: [] as Array<{ authorization: string | null; body: Record<string, unknown> }>,
acceptedTokens: new Set<string>(),
issued: 0,
tokenDelayMs: 0,
rejectAllTokens: false,
/** Other clients the sign-in service knows (id → secret). */
extraClients: new Map<string, string>(),
/** Clients whose tokens the MCP server refuses. */
mcpDeniedClients: new Set<string>(),
tokenClients: new Map<string, string>(),
/** 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<void>),
};
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<Response> => {
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<string, unknown>;
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<typeof createDb>;
let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | 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<typeof fakeProvider>, 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<typeof fakeProvider>) {
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<string, unknown>).tokenUrl).toBe(TOKEN_URL);
expect((row!.config.oauth as Record<string, unknown>).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<string, unknown>).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<string, unknown>).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") });
});
});
+65
View File
@@ -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",
+105 -1
View File
@@ -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<typeof heartbeatService>;
/** Allowlist (e.g. Google Sheets allowed spreadsheet ids) lives in connection config. */
function asRecord(value: unknown): Record<string, unknown> {
return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
}
/** 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<string, unknown> | 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, {
+7 -3
View File
@@ -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<string, unknown> {
export function mcpClientCapabilities(protocolVersion: string, options: { declareTasks?: boolean; elicitationForm?: boolean; declareClientCredentials?: boolean } = {}): Record<string, unknown> {
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<string, string> | 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<string, string>; 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,
},
};
@@ -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)
+21 -3
View File
@@ -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,
@@ -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<string, string>, 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) ||
@@ -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<typeof secretService>;
store: Pick<OAuthCredentialStore, "createOrRotateOAuthSecret" | "syncCredentialBindings">;
exchangeOAuthToken: ReturnType<typeof createOAuthClientProtocol>["exchangeOAuthToken"];
getConnectionRow(idOrUid: string, companyId?: string): Promise<typeof toolConnections.$inferSelect>;
assertRemoteConnectionEndpointsAllowed(config: Record<string, unknown>): Promise<unknown>;
ensureDefaultOrganizationGrant: ReturnType<typeof createOrganizationGrantStore>;
checkConnectionHealth(connectionId: string, actor?: ActorInfo): Promise<ToolConnectionHealthCheckResult>;
refreshCatalog(connectionId: string, actor?: ActorInfo, options?: { enableAllByDefault?: boolean }): Promise<ToolCatalogRefreshResult>;
/** List the server's tools with exactly these credentials, never the stored ones. */
probeServerWithToken(connection: typeof toolConnections.$inferSelect, authorization: string, actor?: ActorInfo): Promise<unknown>;
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<string, unknown>,
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<Record<string, unknown> | 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<DiscoveredSignInService | null> {
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<string | null> {
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<string[] | null> {
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<DiscoveredSignInService> {
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<ToolCredentialSecretRef> {
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<typeof toolConnections.$inferInsert>,
) {
// 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<MachineSignInSetupResult> {
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<string, unknown> = { 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<ReturnType<typeof generateClientKeyPair>> | 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<ConnectToolAppResult> {
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<MachineSignInSetupResult & { completed: boolean }> {
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<MachineSignInSetupResult> {
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<MachineSignInStatus> {
return machineSignInStatus(await machineSignInConnection(companyId, connectionId));
}
return {
requestClientCredentialsToken,
assertPinnedSignInService,
createMachineSignIn,
testMachineSignIn,
rotateMachineSignIn,
completeMachineSignInRotation,
getMachineSignIn,
};
}
export type ClientCredentialsService = ReturnType<typeof createClientCredentialsService>;
@@ -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<typeof toolConnections.$inferSelect, "config">,
): 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<typeof toolConnections.$inferSelect, "config">): 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<KeyObject> {
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";
}
@@ -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) {
@@ -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<string, unknown> {
if (value && typeof value === "object" && !Array.isArray(value))
return value as Record<string, unknown>;
@@ -27,9 +29,11 @@ type LegacyRefreshDependencies = {
leases: Pick<OAuthRefreshLeases, "acquireOAuthRefreshLease" | "clearOAuthRefreshLease">;
getConnectionRow(idOrUid: string, companyId?: string): Promise<typeof toolConnections.$inferSelect>;
exchangeOAuthToken: ReturnType<typeof createOAuthClientProtocol>["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<string, Promise<unknown>>();
@@ -138,12 +142,15 @@ const oauthRefreshFlights = new Map<string, Promise<unknown>>();
},
);
}
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<string, Promise<unknown>>();
: null;
let token: Awaited<ReturnType<typeof exchangeOAuthToken>>;
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,
@@ -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<string, unknown> {
if (value && typeof value === "object" && !Array.isArray(value))
return value as Record<string, unknown>;
@@ -31,9 +33,11 @@ type GrantRefreshDependencies = {
currentCloudConnector: () => PaperclipCloudConnector | null;
getConnectionRow(idOrUid: string, companyId?: string): Promise<typeof toolConnections.$inferSelect>;
exchangeOAuthToken: ReturnType<typeof createOAuthClientProtocol>["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<string, Promise<unknown>>();
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<ReturnType<typeof exchangeOAuthToken>>;
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"
) {
+2
View File
@@ -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,
@@ -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",
+10
View File
@@ -306,6 +306,16 @@ export const toolsApi = {
},
connectApp: (companyId: string, input: ConnectToolApp) =>
api.post<ConnectToolAppResult>(`/companies/${companyId}/tools/apps/connect`, input),
createMachineSignIn: (companyId: string, input: import("@paperclipai/shared").CreateMachineSignIn) =>
api.post<import("@paperclipai/shared").MachineSignInSetupResult>(`/companies/${companyId}/tools/machine-sign-in`, input),
getMachineSignIn: (connectionId: string) =>
api.get<import("@paperclipai/shared").MachineSignInStatus>(`/tool-connections/${connectionId}/machine-sign-in`),
testMachineSignIn: (connectionId: string, input: import("@paperclipai/shared").TestMachineSignIn) =>
api.post<ConnectToolAppResult>(`/tool-connections/${connectionId}/machine-sign-in/test`, input),
rotateMachineSignIn: (connectionId: string, input: import("@paperclipai/shared").RotateMachineSignIn) =>
api.post<import("@paperclipai/shared").MachineSignInSetupResult & { completed: boolean }>(`/tool-connections/${connectionId}/machine-sign-in/rotate`, input),
completeMachineSignInRotation: (connectionId: string) =>
api.post<import("@paperclipai/shared").MachineSignInSetupResult>(`/tool-connections/${connectionId}/machine-sign-in/rotate/complete`, {}),
startOAuth: (
connectionId: string,
input: {
@@ -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<string, boolean> = {};
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<string, boolean> = {};
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}
/>
)}
@@ -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(
<GenericMcpConnectStep
link="https://mcp.example/mcp" name="" needsKey={false} keyValue="" onKeyChange={() => 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={<p data-testid="access-defaults">Connects for every agent. Change</p>}
/>,
);
});
}
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");
});
});
@@ -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<HTMLDivElement>) => {
// 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<HTMLButtonElement>('[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 (
<div key={option.mode}>
@@ -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 ? <div className="px-4 pb-2 pt-3">{fields}</div> : null}
</div>
);
})}
{machineSignIn ? (
<div>
<RadioCard
selected={machine}
title="Machine sign-in"
description="Your organization’s automation signs in as its own registered client. No person signs in."
tabIndex={machine ? 0 : -1}
disabled={submitting}
className="bg-background"
onClick={() => setMachineSelected(true)}
/>
{machine ? (
<div className="px-4 pb-2 pt-3">
<MachineSignInSetup
companyId={machineSignIn.companyId}
link={link}
name={name}
onBack={onBack}
onConnected={machineSignIn.onConnected}
beforeFooter={defaults}
/>
</div>
) : null}
</div>
) : null}
</div>
</CollapsibleContent>
</Collapsible>
{defaults}
{/* Machine sign-in owns its footer (Test connection, not Check link) and shows the access line above it. */}
{machine ? null : (
<>
{defaults}
<div className="mt-8 flex items-center justify-between">
<Button variant="ghost" onClick={onBack} disabled={submitting}>
Back
</Button>
<Button onClick={onConnect} disabled={submitting || !canSubmit || Boolean(headerError)}>
{submitting && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
{submitting ? "Checking…" : "Check link"}
</Button>
</div>
<div className="mt-8 flex items-center justify-between">
<Button variant="ghost" onClick={onBack} disabled={submitting}>
Back
</Button>
<Button onClick={onConnect} disabled={submitting || !canSubmit || Boolean(headerError)}>
{submitting && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
{submitting ? "Checking…" : "Check link"}
</Button>
</div>
</>
)}
</div>
);
}
@@ -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<HTMLInputElement>(`#${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(<MachineSignInSetup companyId="company-1" link="https://mcp.example/mcp" client={client} onBack={() => 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(<MachineSignInSetup companyId="company-1" link="https://mcp.example/mcp" client={client} initialSetup={draft} onBack={() => 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(<MachineSignInSetup companyId="company-1" link="https://mcp.example/mcp" client={client} initialMethod="client_secret" onBack={() => 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(<MachineSignInSetup companyId="company-1" link="https://mcp.example/mcp" client={client} initialSetup={secretDraft} onBack={() => 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<typeof draft.machineSignIn>((resolve) => { finish = resolve; })),
};
await act(async () => {
root.render(<MachineSignInSetup companyId="company-1" link="https://mcp.example/mcp" client={client} onBack={() => 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();
});
});
@@ -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<MachineSignInSetupResult>;
test(connectionId: string, input: TestMachineSignIn): Promise<ConnectToolAppResult>;
status(connectionId: string): Promise<MachineSignInStatus>;
}
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<MachineSignInSetupResult, "connectionId" | "machineSignIn">;
/**
* 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<MachineSignInMethod>(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<MachineSignInDraft | null>(initialSetup);
const [error, setError] = useState<string | null>(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<MachineSignInDraft | null> {
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 (
<div className="space-y-5" data-testid="machine-sign-in-setup">
<p className="text-xs text-muted-foreground">
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.
</p>
{error ? <InlineBanner tone="warning" title="Machine sign-in didn’t work">{error}</InlineBanner> : null}
{!setup ? (
<div className="space-y-4">
<div
className="flex flex-wrap gap-2"
role="radiogroup"
aria-label="How Paperclip proves who it is"
onKeyDown={(event) => {
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<HTMLButtonElement>('[role="radio"]')[next]?.focus();
}}
>
{METHOD_OPTIONS.map((option) => (
<button
key={option.method}
type="button"
role="radio"
aria-checked={method === option.method}
onClick={() => setMethod(option.method)}
className={cn(
"rounded-md border border-border px-3 py-1.5 text-sm font-medium transition-colors",
method === option.method ? "bg-background text-foreground shadow-sm" : "text-muted-foreground hover:text-foreground",
)}
>
{option.label}
</button>
))}
</div>
<p className="text-xs text-muted-foreground">{METHOD_OPTIONS.find((option) => option.method === method)?.hint}</p>
<Field id="machine-sign-in-service" label="Sign-in service" hint={`Leave blank and Paperclip asks ${host} where to sign in. Otherwise enter the address or token URL from the provider’s docs.`}>
<Input id="machine-sign-in-service" value={signInService} onChange={(event) => setSignInService(event.target.value)} placeholder="Found automatically" autoComplete="off" className="h-11 font-mono" />
</Field>
<Field id="machine-sign-in-client-id" label="Client ID" hint={method === "paperclip_key" ? "You can add this after registering the key." : undefined}>
<Input id="machine-sign-in-client-id" value={clientId} onChange={(event) => setClientId(event.target.value)} autoComplete="off" className="h-11 font-mono" />
</Field>
{method === "client_secret" ? (
<Field id="machine-sign-in-client-secret" label="Client secret">
<Input id="machine-sign-in-client-secret" type="password" value={clientSecret} onChange={(event) => setClientSecret(event.target.value)} autoComplete="off" className="h-11 font-mono" />
</Field>
) : null}
<Field id="machine-sign-in-scopes" label="Scopes" hint="Optional. Separate with spaces, as the provider’s docs list them.">
<Input id="machine-sign-in-scopes" value={scopes} onChange={(event) => setScopes(event.target.value)} placeholder="Optional" autoComplete="off" className="h-11 font-mono" />
</Field>
</div>
) : (
<div className="space-y-4">
{publicKey ? (
<div className="space-y-3">
<p className="text-sm text-foreground">
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.
</p>
<PublicKeyBlock label="Public key (PEM)" value={publicKey.pem} />
<PublicKeyBlock label="Public key (JSON)" value={JSON.stringify(publicKey.jwk, null, 2)} />
</div>
) : null}
<Field id="machine-sign-in-client-id-confirm" label="Client ID" hint="The ID the provider shows for the Paperclip client.">
<Input id="machine-sign-in-client-id-confirm" value={clientId} onChange={(event) => setClientId(event.target.value)} autoComplete="off" className="h-11 font-mono" />
</Field>
{setup.machineSignIn.method === "client_secret" ? (
<Field id="machine-sign-in-client-secret-replace" label="Client secret" hint={setup.machineSignIn.hasClientSecret ? "Saved. Enter a new one only to replace it." : undefined}>
<Input id="machine-sign-in-client-secret-replace" type="password" value={clientSecret} onChange={(event) => setClientSecret(event.target.value)} placeholder={setup.machineSignIn.hasClientSecret ? "••••••••" : ""} autoComplete="off" className="h-11 font-mono" />
</Field>
) : null}
<Field id="machine-sign-in-scopes-confirm" label="Scopes" hint="Optional. Separate with spaces.">
<Input id="machine-sign-in-scopes-confirm" value={scopes} onChange={(event) => setScopes(event.target.value)} autoComplete="off" className="h-11 font-mono" />
</Field>
</div>
)}
{beforeFooter}
<div className="flex items-center justify-between pt-3">
<Button variant="ghost" onClick={onBack} disabled={busy !== null}>Back</Button>
{!setup && method === "paperclip_key" ? (
<Button onClick={() => void createDraft()} disabled={busy !== null || restoring || !canCreate}>
{busy === "creating" && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
{busy === "creating" ? "Creating key…" : "Create key"}
</Button>
) : (
<Button
onClick={async () => {
const target = setup ?? await createDraft();
if (target) await testConnection(target, setup ? clientSecret : "");
}}
disabled={busy !== null || restoring || (setup ? !canTest : !canCreate)}
>
{busy !== null && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
{busy === "testing" ? "Testing…" : busy === "creating" ? "Saving…" : "Test connection"}
</Button>
)}
</div>
</div>
);
}
function Field({ id, label, hint, children }: { id: string; label: string; hint?: string; children: React.ReactNode }) {
return (
<div>
<label className="text-sm font-medium text-foreground" htmlFor={id}>{label}</label>
<div className="mt-2">{children}</div>
{hint ? <p className="mt-2 text-xs text-muted-foreground">{hint}</p> : null}
</div>
);
}
function PublicKeyBlock({ label, value }: { label: string; value: string }) {
const [copied, setCopied] = useState(false);
return (
<div>
<div className="flex items-center justify-between">
<span className="text-sm font-medium text-foreground">{label}</span>
<Button
type="button"
variant="outline"
size="sm"
onClick={async () => {
await copyTextToClipboard(value).then(() => setCopied(true), () => setCopied(false));
}}
>
{copied ? "Copied" : "Copy"}
</Button>
</div>
<Textarea readOnly value={value} aria-label={label} rows={6} className="mt-2 font-mono text-xs" />
</div>
);
}
@@ -0,0 +1,102 @@
import type { Meta, StoryObj } from "@storybook/react-vite";
import type { ConnectToolAppResult, MachineSignInSetupResult } from "@paperclipai/shared";
import { MachineSignInSetup, type MachineSignInClient } from "@/features/connections/MachineSignInSetup";
const LINK = "https://mcp.reports.example/mcp";
const PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoBlCS+lp0dZwCGElkUQw
spwT+Q/xmKEF05Tx3hIq1HvAjZBWP1WGbCvfE47bK0nrnQHOYvLjpjFwtA3H/yOL
WevYMfELbZdAsX0hGZYFuEStMUgOK+40hqkBzmmHDhxILvjk2e0F/V6FcYuKMxt6
o1uDJw9D97Go61SPIyNgX9s702/8UPJ1o+ywqj/q20DATDsbg2tmcd0SJGvg0Yvr
5Vfs3pIbeI/W9oD1uwMp+R39qfPkHtXgdphr0zZUT4nQyYYaRkqU3fEt/95wQl5u
ZEhMyxTlUpuSkNJR7+CQ5fKF1eLoC0cBg2GNs/TYkzorEOfF36KRwThWJDcw1OaZ
CQIDAQAB
-----END PUBLIC KEY-----
`;
const draft: MachineSignInSetupResult = {
connectionId: "connection-1",
connection: {} as MachineSignInSetupResult["connection"],
machineSignIn: {
connectionId: "connection-1",
method: "paperclip_key",
clientId: null,
issuer: "https://auth.reports.example",
tokenUrl: "https://auth.reports.example/oauth/token",
scopes: ["reports.read"],
publicKey: {
keyId: "qlq2dTOYsBTTtWyaR7QZLShkPOW7XPkzHBgki7R28rg",
algorithm: "RS256",
pem: PUBLIC_KEY_PEM,
jwk: { kty: "RSA", e: "AQAB", n: "oBlCS-lp0dZwCGElkUQw…", kid: "qlq2dTOYsBTTtWyaR7QZLShkPOW7XPkzHBgki7R28rg", alg: "RS256", use: "sig" },
createdAt: "2026-11-13T12:00:00.000Z",
},
pendingPublicKey: null,
hasClientSecret: false,
lastTokenAt: null,
},
};
/** In memory: creating returns the draft above; testing fails until a client ID is entered. */
const fakeClient: MachineSignInClient = {
create: async () => draft,
status: async () => draft.machineSignIn,
test: async (_connectionId, input) => {
await new Promise((resolve) => setTimeout(resolve, 400));
if (input.clientId !== "paperclip-automation") {
throw new Error("The provider didn't accept Paperclip's key. Check the client ID and that the public key shown here is registered for it.");
}
return {} as ConnectToolAppResult;
},
};
const meta = {
id: "apps-connections-machine-sign-in",
title: "Apps, channels, and extensions/Connection setup/Apps/Connections/Machine sign-in",
component: MachineSignInSetup,
args: { companyId: "company-1", link: LINK, client: fakeClient, onBack: () => undefined, onConnected: () => undefined },
parameters: {
layout: "padded",
docs: { description: { component: "Machine sign-in (client credentials) for an organization connection, with in-memory provider responses. Use client ID `paperclip-automation` to see a successful test." } },
paperclip: {
"capabilities": [
"connection-setup/credentials",
"connection-setup/failure"
],
"implementation": "production",
"boundary": "fixtures"
},
},
decorators: [(Story) => <div className="mx-auto max-w-xl"><Story /></div>],
} satisfies Meta<typeof MachineSignInSetup>;
export default meta;
type Story = StoryObj<typeof meta>;
/** Default: Paperclip creates a key; the sign-in service is found from the server. */
export const ChooseKey: Story = {};
export const ChooseClientSecret: Story = { args: { initialMethod: "client_secret" } };
/** After "Create key": the public key to register, then the client ID and test. */
export const RegisterPublicKey: Story = { args: { initialSetup: draft } };
export const TestFailed: Story = {
args: {
initialSetup: { ...draft, machineSignIn: { ...draft.machineSignIn, clientId: "wrong-client" } },
initialError: "The provider didn't accept Paperclip's key. Check the client ID and that the public key shown here is registered for it.",
},
};
export const SignInServiceChanged: Story = {
args: {
initialSetup: { ...draft, machineSignIn: { ...draft.machineSignIn, clientId: "paperclip-automation" } },
initialError: "This server now sends sign-in to a different service (login.other.example). Paperclip won't send this connection's credentials there. Set up machine sign-in again to trust the new service.",
},
};
export const NarrowRegisterPublicKey: Story = {
args: { initialSetup: draft },
globals: { viewport: { value: "mobile", isRotated: false } },
};