mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
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:
1 parent
6b631dd477
commit
f6c5986b61
29 files changed
+2861
-67
No files matched your search
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -525,6 +525,9 @@ export type {
|
||||
ToolAccessSelector,
|
||||
ConnectToolAppAuthChallenge,
|
||||
ConnectToolAppResult,
|
||||
MachineSignInPublicKey,
|
||||
MachineSignInStatus,
|
||||
MachineSignInSetupResult,
|
||||
ToolAppMetadataPreflightAttempt,
|
||||
ToolAppMetadataPreflightResult,
|
||||
FinishToolAppResult,
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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") });
|
||||
});
|
||||
});
|
||||
@@ -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",
|
||||
|
||||
@@ -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, {
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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"
|
||||
) {
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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 } },
|
||||
};
|
||||
Reference in new issue
Block a user