The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
refactor(tools): isolate OAuth protocol boundaries (#17147)
Dotta4413bb262fbe
diff --git a/doc/plans/2026-10-21-tool-access-boundaries.md b/doc/plans/2026-10-21-tool-access-boundaries.mdindex 1c9aa0c2ee..0d36bc30c6 100644--- a/doc/plans/2026-10-21-tool-access-boundaries.md+++ b/doc/plans/2026-10-21-tool-access-boundaries.md@@ -61,3 +61,50 @@ coverage pass before and after; the combined post-move run passes 506 tests.Server TypeScript checking passes. The first typecheck exposed that the publicToolConnection DTO allows absent config; the module now declares the requiredvalidated settings shape directly instead of adding internal fallback checks.++## Third extraction++OAuth protocol handling now has explicit owners for endpoint policy, metadata+interpretation and discovery, client registration/token exchange, provider error+normalization, and the public client metadata document. Each owner accepts+settings or named request capabilities. None imports the database or the parent+service. Connection URL normalization stays with connection-method settings.++Registration returns validated client material before the coordinator stores it.+Token exchange returns normalized token fields without the unused raw provider+payload. The coordinator retains registration single-flight state, refresh+leases, current membership and grant checks, secret writes, audit records,+transaction ownership, and callback state validation. Endpoint policy reads the+existing live private-endpoint setting through a callback. It does not snapshot+options or create another cache.++Thirty-seven moved function bodies match after syntax normalization. Registration+request/validation and persistence statements match their original halves.+Preflight takes explicit defaults and a clock callback. Remaining coordinator+function bodies match except for these deliberate delegation points.++The original service becomes 19,293 lines / 749,158 bytes, a reduction of 2,232+lines across the stack. The seven OAuth modules total 1,697 lines; the largest+has 582 lines. Connection-methods grows to 368 lines with URL normalization.++A new route integration fixture uses a real local HTTP OAuth/MCP server and a+disposable PostgreSQL database. It covers public and Basic-authenticated clients,+discovery, registration, PKCE token exchange, callback completion, secret storage,+catalog review, and connection activation. Both cases passed before and after+the move. The combined post-move protocol/service run passed 508 tests.+The first fixture run asserted a nonexistent catalog enabled field; the assertion+now checks persisted active status and reviewer identity. An initial typecheck+exposed optional method defaults across the extraction boundary; the coordinator+passes the already-validated defaults explicitly. No runtime fallback was added.+Repository-wide typechecking and module-boundary checks pass. The PR records+the full test and build results for the batch handoff.++## Next ownership cuts++The service still coordinates grant lifecycle, profile resolution, token+brokering, and app setup. Profile resolution/review is the next candidate because+it can own scoped queries and projection without importing OAuth protocol code.+Token brokering follows after its authorization, issuance audit, and locking+contract is mapped. The large setup and callback functions should shrink through+those ownership cuts rather than by distributing their local variables into a+shared service context.diff --git a/server/src/__tests__/tool-access-oauth-protocol.integration.test.ts b/server/src/__tests__/tool-access-oauth-protocol.integration.test.tsnew file mode 100644index 0000000000..d6658e70be--- /dev/null+++ b/server/src/__tests__/tool-access-oauth-protocol.integration.test.ts@@ -0,0 +1,147 @@+import { randomUUID } from "node:crypto";+import { mkdtemp, rm } from "node:fs/promises";+import { createServer } from "node:http";+import type { AddressInfo } from "node:net";+import { tmpdir } from "node:os";+import { join } from "node:path";+import express from "express";+import request from "supertest";+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";+import { companies, companyMemberships, createDb, toolCatalogEntries, toolConnections, toolOauthStates } from "@paperclipai/db";+import { eq } from "drizzle-orm";+import { toolAccessRoutes } from "../routes/tool-access.js";+import { errorHandler } from "../middleware/index.js";+import { startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";++describe("tool OAuth over local HTTP", () => {+ let fixture: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;+ let db: ReturnType<typeof createDb>;+ let keyDir: string;++ beforeAll(async () => {+ keyDir = await mkdtemp(join(tmpdir(), "tool-oauth-protocol-"));+ vi.stubEnv("PAPERCLIP_SECRETS_MASTER_KEY_FILE", join(keyDir, "key"));+ vi.stubEnv("PAPERCLIP_PUBLIC_URL", "http://127.0.0.1:3100");+ vi.stubEnv("PAPERCLIP_TOOL_OAUTH_CLIENT_ID", "");+ vi.stubEnv("PAPERCLIP_TOOL_OAUTH_CLIENT_SECRET", "");+ fixture = await startEmbeddedPostgresTestDatabase("tool-oauth-protocol-");+ db = createDb(fixture.connectionString);+ });++ afterAll(async () => {+ await fixture?.cleanup();+ vi.unstubAllEnvs();+ if (keyDir) await rm(keyDir, { recursive: true, force: true });+ });++ it.each(["none", "client_secret_basic"] as const)("registers, exchanges, and activates a %s client through the routes", async (authMethod) => {+ const userId = `oauth-user-${randomUUID()}`;+ const [company] = await db.insert(companies).values({+ name: "OAuth protocol fixture", issuePrefix: `O${randomUUID().slice(0, 5)}`,+ }).returning();+ await db.insert(companyMemberships).values({+ companyId: company.id, principalType: "user", principalId: userId,+ status: "active", membershipRole: "admin",+ });+ const calls: Array<{ path: string; authorization?: string; body: string }> = [];+ let origin: string;+ const provider = createServer(async (req, res) => {+ let body = "";+ for await (const chunk of req) body += chunk;+ const path = new URL(req.url!, origin).pathname;+ calls.push({ path, authorization: req.headers.authorization, body });+ const json = (value: unknown, status = 200) => {+ res.writeHead(status, { "content-type": "application/json" });+ res.end(JSON.stringify(value));+ };+ if (path.startsWith("/.well-known/oauth-protected-resource")) {+ return json({ resource: `${origin}/mcp`, authorization_servers: [origin] });+ }+ if (path === "/.well-known/oauth-authorization-server") {+ return json({+ issuer: origin, authorization_endpoint: `${origin}/authorize`,+ token_endpoint: `${origin}/token`, registration_endpoint: `${origin}/register`,+ code_challenge_methods_supported: ["S256"],+ token_endpoint_auth_methods_supported: [authMethod],+ scopes_supported: ["tools.read", "offline_access"],+ grant_types_supported: ["authorization_code", "refresh_token"],+ });+ }+ if (path === "/register") {+ return json({ ...JSON.parse(body), client_id: "fixture-client",+ ...(authMethod === "client_secret_basic" ? { client_secret: "fixture-secret" } : {}),+ });+ }+ if (path === "/token") {+ return json({ access_token: "fixture-access", refresh_token: "fixture-refresh",+ expires_in: 3600, token_type: "Bearer", scope: "tools.read offline_access" });+ }+ if (path === "/mcp") {+ if (req.headers.authorization !== "Bearer fixture-access") {+ res.setHeader("www-authenticate", `Bearer resource_metadata="${origin}/.well-known/oauth-protected-resource/mcp"`);+ return json({}, 401);+ }+ const rpc = JSON.parse(body);+ if (rpc.method === "notifications/initialized") {+ res.writeHead(202).end();+ return;+ }+ return json({ jsonrpc: "2.0", id: rpc.id, result: rpc.method === "initialize"+ ? { protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "fixture", version: "1" } }+ : { tools: [{ name: "read_fixture", description: "Read fixture state", inputSchema: { type: "object", properties: {} }, annotations: { readOnlyHint: true } }] },+ });+ }+ json({}, 404);+ });+ await new Promise<void>((resolve) => provider.listen(0, "127.0.0.1", resolve));+ origin = `http://127.0.0.1:${(provider.address() as AddressInfo).port}`;+ try {+ const app = express();+ app.use(express.json());+ app.use((req, _res, next) => {+ req.actor = { type: "board", userId, source: "local_implicit", isInstanceAdmin: true };+ next();+ });+ app.use("/api", toolAccessRoutes(db, { deploymentMode: "local_trusted", deploymentExposure: "private", paperclipCloudConnector: null }));+ app.use(errorHandler);++ const connected = await request(app).post(`/api/companies/${company.id}/tools/apps/connect`)+ .send({ link: `${origin}/mcp`, name: "Local OAuth" }).expect(201);+ const authorization = new URL(connected.body.auth.startUrl);+ expect(authorization.origin).toBe(origin);+ expect(authorization.searchParams.get("client_id")).toBe("fixture-client");+ expect(authorization.searchParams.get("code_challenge_method")).toBe("S256");+ expect(authorization.searchParams.get("resource")).toBe(`${origin}/mcp`);+ const state = authorization.searchParams.get("state")!;+ const [pending] = await db.select().from(toolOauthStates).where(eq(toolOauthStates.state, state));+ expect(pending.companyId).toBe(company.id);++ const completed = await request(app).get("/api/tools/oauth/callback")+ .query({ state, code: "fixture-code", iss: origin }).expect(200);+ expect(completed.body.catalog).toEqual([expect.objectContaining({ toolName: "read_fixture", riskLevel: "read" })]);+ await request(app).post(`/api/companies/${company.id}/tools/apps/${connected.body.connectionId}/finish`)+ .send({ enabledCatalogEntryIds: completed.body.catalog.map((entry: { id: string }) => entry.id), askFirstCatalogEntryIds: [], access: "all_agents" }).expect(200);++ const [connection] = await db.select().from(toolConnections).where(eq(toolConnections.id, connected.body.connectionId));+ expect(connection).toMatchObject({ companyId: company.id, status: "active", enabled: true, ownership: "dcr" });+ expect(connection.config.oauth).toMatchObject({ clientId: "fixture-client", clientTokenEndpointAuthMethod: authMethod, clientIssuer: origin });+ expect(JSON.stringify(connection.config)).not.toMatch(/fixture-(access|refresh|secret)/);+ expect(connection.credentialSecretRefs.map((ref) => ref.configPath)).toEqual(expect.arrayContaining(["oauth.access_token", "oauth.refresh_token"]));+ expect(await db.select().from(toolCatalogEntries).where(eq(toolCatalogEntries.connectionId, connection.id)))+ .toEqual([expect.objectContaining({ toolName: "read_fixture", status: "active", reviewedByUserId: userId })]);+ const tokenCall = calls.find((call) => call.path === "/token")!;+ const tokenBody = new URLSearchParams(tokenCall.body);+ expect(tokenBody.get("code")).toBe("fixture-code");+ expect(tokenBody.get("code_verifier")).toBe(pending.codeVerifier);+ expect(tokenBody.get("resource")).toBe(`${origin}/mcp`);+ expect(tokenCall.authorization).toBe(authMethod === "client_secret_basic"+ ? `Basic ${Buffer.from("fixture-client:fixture-secret").toString("base64")}` : undefined);+ expect(tokenBody.has("client_secret")).toBe(false);+ expect(calls.some((call) => call.path === "/mcp" && call.authorization === "Bearer fixture-access")).toBe(true);+ expect(calls.filter((call) => call.path === "/register")).toHaveLength(1);+ } finally {+ provider.closeAllConnections();+ await new Promise<void>((resolve, reject) => provider.close((error) => error ? reject(error) : resolve()));+ }+ });+});diff --git a/server/src/services/tool-access.ts b/server/src/services/tool-access.tsindex 3fdbc226e3..ed24bf0268 100644--- a/server/src/services/tool-access.ts+++ b/server/src/services/tool-access.ts@@ -1,4 +1,13 @@+import { createOAuthEndpointPolicy } from "./tool-access/oauth/endpoint-policy.js";+import { createOAuthDiscovery } from "./tool-access/oauth/discovery.js";+import { createOAuthClientProtocol, storedOAuthTokenEndpointAuthMethod } from "./tool-access/oauth/client.js";+import { normalizeOAuthProviderError, oauthProviderErrorMessage } from "./tool-access/oauth/provider-errors.js";+import { oauthConfig, normalizeOauthScopes, resolveGrantedOauthScopes, sameOAuthIssuer, originOf, isSmokeLabOAuthFixture } from "./tool-access/oauth/metadata.js";+import { resolveOAuthClientIdMetadataDocumentUrl } from "./tool-access/oauth/client-metadata.js";+import type { OAuthProviderEndpoints, OAuthClientRegistrationSource } from "./tool-access/oauth/types.js";+export { OAUTH_CLIENT_ID_METADATA_DOCUMENT_PATH, resolveOAuthClientIdMetadataDocumentUrl, oauthClientIdMetadataDocument } from "./tool-access/oauth/client-metadata.js";import {+ remoteEndpoint,connectionMethodFor,connectionMethodForConnection,credentialFieldsFor,@@ -217,12 +226,6 @@ import {mcpRemoteHeaderNameFromConfigPath,mcpRemoteHeaderRejectionMessage,} from "@paperclipai/shared";-import {- checkOAuthEndpointUrl,- oauthEndpointUrlRejectionMessage,- type OAuthEndpointKind,- type OAuthEndpointUrlRejection,-} from "@paperclipai/shared";import {badRequest,conflict,@@ -323,348 +326,10 @@ type ActorInfo = {const ACTIVE_BROKER_RUN_STATUSES = new Set(["running"]);const REMOTE_HTTP_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);const MAX_REMOTE_HTTP_REDIRECTS = 5;-const MAX_OAUTH_DCR_CLIENT_ID_LENGTH = 4_096;-const MAX_OAUTH_DCR_CLIENT_SECRET_LENGTH = 16_384;const OAUTH_REFRESH_LEASE_MS = 120_000;const OAUTH_REFRESH_LEASE_WAIT_MS = 30_000;const OAUTH_REFRESH_LEASE_POLL_MS = 25;-/**- * Upstream OAuth error redaction (PAP-17108).- *- * A generic remote MCP connection points at an arbitrary authorization server,- * so everything that server says about a failure is attacker-chosen: `error`,- * `error_description`, `error_uri`, and the response body. Paperclip surfaces- * connection failures to the operator through API responses, board UI copy,- * audit rows and logs, so reflecting any of that text would let a hostile- * provider plant secrets, ANSI escapes, or instructions ("paste your recovery- * key here") into Paperclip's own voice.- *- * The rule is therefore: the operator only ever reads text Paperclip authored.- * The provider's `error` code survives — as a *label* in structured `details`,- * never in a message — and only when it is one of the codes the RFCs define,- * because a label is still untrusted input. Everything else is dropped, and an- * unrecognized code collapses to `unrecognized` rather than being echoed.- *- * `error_description` and the response body are never read at all: no call site- * below parses them, which is what keeps a future edit from quietly- * reintroducing the reflection.- */-const OAUTH_PROVIDER_ERROR_CODES = new Set([- // RFC 6749 §4.1.2.1 — authorization endpoint (the callback-denial path).- "access_denied",- "invalid_request",- "invalid_scope",- "server_error",- "temporarily_unavailable",- "unauthorized_client",- "unsupported_response_type",- // RFC 6749 §5.2 — token endpoint (authorization-code and refresh exchanges).- "invalid_client",- "invalid_grant",- "unsupported_grant_type",- // RFC 7591 §3.2.2 — dynamic client registration.- "invalid_client_metadata",- "invalid_redirect_uri",- "invalid_software_statement",- "unapproved_software_statement",- // OpenID Connect Core §3.1.2.6 — interactive re-authentication prompts.- "account_selection_required",- "consent_required",- "interaction_required",- "login_required",-]);--/** What an `error` that is absent, malformed, or off the allowlist becomes. */-const UNRECOGNIZED_OAUTH_PROVIDER_ERROR = "unrecognized";-const MAX_OAUTH_PROVIDER_ERROR_LENGTH = 64;-const OAUTH_PROVIDER_ERROR_PATTERN = /^[a-z0-9_-]+$/;--/**- * Stable, Paperclip-authored operator copy for each allowlisted provider error.- * Deliberately keyed on the code alone: the calling context is already carried- * by the Paperclip `code` in `details`, so one table serves the callback,- * token-exchange and registration paths without any of them composing a message- * out of provider text.- */-const OAUTH_PROVIDER_ERROR_MESSAGES: Record<string, string> = {- access_denied: "The authorization server denied the request.",- account_selection_required:- "The authorization server needs an account to be selected. Try connecting again.",- consent_required:- "The authorization server needs consent to be granted. Try connecting again.",- interaction_required:- "The authorization server needs to be signed in to interactively. Try connecting again.",- invalid_client: "The authorization server rejected Paperclip's OAuth client.",- invalid_client_metadata:- "The authorization server rejected Paperclip's client registration details.",- invalid_grant:- "The authorization server rejected the authorization code or refresh token.",- invalid_redirect_uri:- "The authorization server rejected Paperclip's callback URL.",- invalid_request:- "The authorization server rejected the request as malformed.",- invalid_scope: "The authorization server rejected the requested permissions.",- invalid_software_statement:- "The authorization server rejected Paperclip's client registration details.",- login_required:- "The authorization server needs to be signed in to. Try connecting again.",- server_error:- "The authorization server reported an internal error. Try again shortly.",- temporarily_unavailable:- "The authorization server is temporarily unavailable. Try again shortly.",- unapproved_software_statement:- "The authorization server rejected Paperclip's client registration details.",- unauthorized_client:- "The authorization server refused to authorize Paperclip's OAuth client.",- unsupported_grant_type:- "The authorization server does not support the grant Paperclip uses.",- unsupported_response_type:- "The authorization server does not support the sign-in flow Paperclip uses.",-};--/**- * Reduce a provider-supplied `error` to a bounded, allowlisted label safe to- * keep in structured `details`. Returns `null` only when the provider sent no- * `error` at all, so the caller can tell "silent failure" from "said something- * Paperclip does not recognize".- */-function normalizeOAuthProviderError(value: unknown): string | null {- if (typeof value !== "string" || value.length === 0) return null;- // Bound length and character class before the allowlist even though- // membership implies both: these limits are what keeps the label safe if the- // allowlist above ever grows a pattern-matched entry.- if (value.length > MAX_OAUTH_PROVIDER_ERROR_LENGTH)- return UNRECOGNIZED_OAUTH_PROVIDER_ERROR;- if (!OAUTH_PROVIDER_ERROR_PATTERN.test(value))- return UNRECOGNIZED_OAUTH_PROVIDER_ERROR;- return OAUTH_PROVIDER_ERROR_CODES.has(value)- ? value- : UNRECOGNIZED_OAUTH_PROVIDER_ERROR;-}--/** Paperclip's own message for a provider failure, never the provider's. */-function oauthProviderErrorMessage(- providerError: string | null,- fallback: string,-): string {- if (!providerError) return fallback;- return OAUTH_PROVIDER_ERROR_MESSAGES[providerError] ?? fallback;-}--/**- * Where this deployment publishes its Client ID Metadata Document. The document's- * own URL is the `client_id` Paperclip presents, so this path is a stable part of- * the deployment's public contract with every authorization server that has seen- * it — changing it invalidates existing CIMD registrations.- */-export const OAUTH_CLIENT_ID_METADATA_DOCUMENT_PATH =- "/api/tools/oauth/client-metadata";--/**- * Resolve the URL Paperclip would use as a CIMD client id, but only when its- * hostname is not known to resolve into a private network.- *- * An authorization server fetches this URL from outside Paperclip's network and- * will normally apply an SSRF guard. Tailscale/MagicDNS names are HTTPS but- * resolve into 100.64.0.0/10, so presenting one as a client id can only produce- * an `invalid_client` response. A local DNS failure remains inconclusive because- * split-horizon public DNS may still let the authorization server resolve it.- */-export async function resolveOAuthClientIdMetadataDocumentUrl(- redirectUri: string,- lookup?: RemoteHttpEndpointLookup,-): Promise<string | null> {- try {- const parsed = new URL(redirectUri);- if (parsed.protocol !== "https:") return null;- const hostname = parsed.hostname.replace(/^\[|\]$/g, "").toLowerCase();- const isLoopback =- hostname === "localhost" ||- hostname.endsWith(".localhost") ||- hostname === "::1" ||- /^127(?:\.\d{1,3}){3}$/.test(hostname);- if (isLoopback) return null;- const metadataUrl = new URL(- OAUTH_CLIENT_ID_METADATA_DOCUMENT_PATH,- parsed.origin,- ).toString();- try {- await assertPublicRemoteHttpEndpoint(- new URL(metadataUrl),- { allowPrivateNetwork: false, lookup },- (message, code) => Object.assign(new Error(message), { code }),- );- } catch (error) {- if (- error instanceof Error &&- "code" in error &&- error.code === "remote_http_private_endpoint"- ) {- return null;- }- }- return metadataUrl;- } catch {- return null;- }-}--/**- * Paperclip's client metadata for CIMD (RFC 7591 metadata, served rather than- * registered). Only the callback for this deployment appears in it, so an- * authorization server that fetches it can see exactly one legal redirect target.- */-export function oauthClientIdMetadataDocument(input: {- clientId: string;- redirectUri: string;-}): Record<string, unknown> {- return {- client_id: input.clientId,- client_name: `Paperclip (${new URL(input.redirectUri).host})`,- client_uri: new URL("/", input.clientId).toString(),- redirect_uris: [input.redirectUri],- grant_types: ["authorization_code", "refresh_token"],- response_types: ["code"],- token_endpoint_auth_method: "none",- application_type: "web",- };-}--type OAuthProviderEndpoints = {- provider: string;- scopes: string[];- /** Refresh permission belongs to authorization-server metadata, not MCP tool scopes. */- offlineAccessSupported?: boolean;- authorizationUrl: string;- tokenUrl: string;- registrationUrl?: string | null;- codeChallengeMethodsSupported?: string[];- tokenEndpointAuthMethodsSupported?: string[];- grantTypesSupported?: string[];- grantType?: "authorization_code" | "client_credentials";- metadataUrl?: string | null;- /**- * Canonical authorization-server issuer, when discovery found one. Registered- * client material is bound to it, `iss` on the callback is validated against- * it, and reconnect/refresh reuse it instead of re-deriving a provider key.- */- issuer?: string | null;- /**- * RFC 8707 resource indicator: the MCP endpoint the token is for. Sent on both- * authorization and token requests so the authorization server can audience-- * restrict the access token to this server rather than to everything Paperclip- * has ever connected.- */- resource?: string | null;- /** The authorization server advertised support for Client ID Metadata Documents. */- clientIdMetadataDocumentSupported?: boolean;-};--/**- * Where an OAuth client came from, in the preference order the current MCP- * client-registration guidance recommends (PAP-17087).- */-type OAuthClientRegistrationSource =- "preconfigured" | "cimd" | "dcr" | "manual";--/**- * RFC 8414 §3.1 requires the well-known path to be *inserted between* the- * issuer host and its path component, but a large amount of deployed software- * only serves the naive suffix form. OpenID Connect Discovery 1.0 in turn- * specifies the suffix form. Try all of them for an issuer that has a path, and- * the plain origin form when it doesn't.- */-function wellKnownMetadataUrls(issuer: string): string[] {- let parsed: URL;- try {- parsed = new URL(issuer);- } catch {- return [];- }- const suffixes = ["oauth-authorization-server", "openid-configuration"];- const path = parsed.pathname.replace(/\/+$/, "");- const urls: string[] = [];- for (const suffix of suffixes) {- if (path) {- // RFC 8414: https://host/.well-known/<suffix><path>- urls.push(- new URL(`/.well-known/${suffix}${path}`, parsed.origin).toString(),- );- // OIDC Discovery / widely deployed: https://host<path>/.well-known/<suffix>- urls.push(- new URL(`${path}/.well-known/${suffix}`, parsed.origin).toString(),- );- }- urls.push(new URL(`/.well-known/${suffix}`, parsed.origin).toString());- }- return [...new Set(urls)];-}--/**- * Protected-resource metadata lives at `/.well-known/oauth-protected-resource`- * with the resource's path appended (RFC 9728 §3.1). Probe the path-aware form- * first so a multi-tenant host that serves several MCP servers resolves to the- * right one, then fall back to the origin form.- */-function protectedResourceMetadataUrls(endpoint: URL): string[] {- const path = endpoint.pathname.replace(/\/+$/, "");- const urls: string[] = [];- if (path)- urls.push(- new URL(- `/.well-known/oauth-protected-resource${path}`,- endpoint.origin,- ).toString(),- );- urls.push(- new URL(- "/.well-known/oauth-protected-resource",- endpoint.origin,- ).toString(),- );- return [...new Set(urls)];-}--/**- * Canonical RFC 8707 resource indicator for an MCP endpoint: origin + path, with- * query, fragment and any trailing slash removed. Vendor query parameters belong- * to the connection config, not to the token audience.- */-function canonicalResourceIndicator(endpoint: string): string | null {- try {- const parsed = new URL(endpoint);- const path = parsed.pathname.replace(/\/+$/, "");- return `${parsed.origin}${path}`;- } catch {- return null;- }-}--/**- * Two issuers are the same authorization server only when scheme, host, port and- * path match exactly (a trailing slash is not significant). Used for `iss`- * validation on the callback and for detecting that a stored registration is- * bound to a different server than the one we just discovered.- */-function sameOAuthIssuer(- a: string | null | undefined,- b: string | null | undefined,-): boolean {- if (!a || !b) return false;- try {- const left = new URL(a);- const right = new URL(b);- return (- left.protocol === right.protocol &&- left.host === right.host &&- left.pathname.replace(/\/+$/, "") === right.pathname.replace(/\/+$/, "")- );- } catch {- return false;- }-}-const oauthRegistrationFlights = new Map<string, Promise<unknown>>();async function singleFlight<T>(@@ -2284,22 +1949,11 @@ function managedConnectorProfile(value: string | undefined): {return null;}--/*** Did this error come from the OAuth endpoint gate (PAP-17099)? Such a refusal* is Paperclip's own decision about an unsafe address, so it must keep its code* and its 422 instead of being folded into a generic upstream failure.*/-function originOf(value: string | null | undefined): string | null {- if (!value) return null;- try {- return new URL(value).origin;- } catch {- return null;- }-}-function isOAuthEndpointRejection(error: unknown): boolean {if (!(error instanceof HttpError)) return false;const code = asRecord(error.details).code;@@ -2441,14 +2095,6 @@ function sanitizeHttpFailure(error: unknown): {};}-function remoteEndpoint(config: Record<string, unknown>): string {- const value = config.url ?? config.endpoint ?? config.remoteUrl;- const parsed = parseRemoteHttpEndpoint(value, (message, code) =>- badRequest(message, { code }),- );- return parsed.toString();-}-function vercelConnectResourcesFor(connection: typeof toolConnections.$inferSelect,): string[] {@@ -2547,6 +2193,13 @@ export function toolAccessService(options: ToolAccessServiceOptions = {},) {const secrets = secretService(db);+ const { assertOAuthEndpointUrl, safeOAuthEndpointUrl } = createOAuthEndpointPolicy(allowPrivateRemoteEndpoints);+ const { oauthEndpointsForConnection, discoverOAuthEndpoints, preflightConnectionMetadata } = createOAuthDiscovery({+ fetchRemoteHttpUrl, assertRemoteEndpointAllowed, assertOAuthEndpointUrl, safeOAuthEndpointUrl,+ });+ const { requestOAuthClientRegistration, exchangeOAuthToken } = createOAuthClientProtocol({+ fetchRemoteHttpUrl, assertOAuthEndpointUrl,+ });const composioSyncJobs = new Map<string, Promise<void>>();const composioSyncTtlMs = 5 * 60_000;const composioSyncLeaseMs = 4 * 60_000;@@ -2962,110 +2615,6 @@ export function toolAccessService(return endpoint;}- /**- * OAuth endpoint scheme/transport gate (PAP-17099).- *- * Every OAuth endpoint Paperclip acts on is attacker-influenced: discovered- * metadata, a `WWW-Authenticate` hint, a pasted config, or a gallery default.- * The authorization endpoint is the sharpest one because it is handed to the- * operator's browser as a top-level navigation, so `javascript:`/`data:` there- * would run in the board's origin. `checkOAuthEndpointUrl` is the single place- * that decides; loopback `http:` is accepted only under the same- * local-development policy that governs private remote endpoints, and- * Paperclip's own origin is exempt from the transport rule because a- * first-party endpoint (the smoke-lab fixture) is served exactly as the board- * itself is.- */- function oauthEndpointRejected(- kind: OAuthEndpointKind,- reason: OAuthEndpointUrlRejection,- ): HttpError {- return new HttpError(422, oauthEndpointUrlRejectionMessage(kind, reason), {- code: `oauth_${kind}_endpoint_rejected`,- reason,- });- }-- /**- * Origins that are Paperclip itself: this deployment's configured public URL,- * plus the callback origin of the request in hand when there is one. Only the- * plaintext-transport rule is relaxed for these.- */- function firstPartyOrigins(candidate?: string | null): string[] {- const configured =- process.env.PAPERCLIP_PUBLIC_URL?.trim() ||- process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL?.trim() ||- process.env.BETTER_AUTH_URL?.trim() ||- process.env.BETTER_AUTH_BASE_URL?.trim() ||- null;- return [originOf(candidate), originOf(configured)].filter(- (origin): origin is string => Boolean(origin),- );- }-- /**- * Origins for which the plaintext-transport rule is relaxed when checking- * `value`. Adds the smoke-lab fixture's own origin, because that provider is- * mounted on this deployment's own routes — `assertNotSmokeLabOAuthEndpoints`- * is what stops any other connection from claiming those paths — and a smoke- * run may be driven against a deployment served over plaintext HTTP.- */- function insecureTransportExemptions(- value: unknown,- candidate?: string | null,- ): string[] {- const origins = firstPartyOrigins(candidate);- if (typeof value === "string" && isSmokeLabOAuthUrl(value)) {- const origin = originOf(value);- if (origin) origins.push(origin);- }- return origins;- }-- /** Throws unless `value` is an endpoint Paperclip may use (and navigate to). */- function assertOAuthEndpointUrl(- kind: OAuthEndpointKind,- value: unknown,- options: { firstPartyOrigin?: string | null } = {},- ): string {- const check = checkOAuthEndpointUrl(value, {- allowInsecureLoopback: allowPrivateRemoteEndpoints(),- allowInsecureOrigins: insecureTransportExemptions(- value,- options.firstPartyOrigin,- ),- });- if (!check.ok) throw oauthEndpointRejected(kind, check.reason);- return check.url;- }-- /**- * Discovery variant: an unusable endpoint is dropped rather than thrown, so a- * second advertised authorization server (or a later metadata candidate) still- * gets a chance. Rejections are recorded in `rejections`; discovery raises the- * first one only if it ends up with nothing safe to use, so the operator sees- * *why* instead of a bare "does not advertise OAuth sign in".- */- function safeOAuthEndpointUrl(- kind: OAuthEndpointKind,- value: unknown,- rejections: HttpError[],- firstPartyOrigin?: string | null,- ): string | null {- if (value === null || value === undefined || value === "") return null;- const check = checkOAuthEndpointUrl(value, {- allowInsecureLoopback: allowPrivateRemoteEndpoints(),- allowInsecureOrigins: insecureTransportExemptions(- value,- firstPartyOrigin,- ),- });- if (check.ok) return check.url;- if (check.reason !== "missing")- rejections.push(oauthEndpointRejected(kind, check.reason));- return null;- }-function trustedRuntimeHost() {return (options.trustedLocalStdioRuntimeHost ??@@ -8329,41 +7878,6 @@ export function toolAccessService(};}- function isSmokeLabOAuthFixture(- connection: typeof toolConnections.$inferSelect,- ) {- const config = asRecord(connection.config);- const oauth = oauthConfig(connection);- return (- config.smokeLabFixture === "oauth-http" && oauth.smokeLabFixture === true- );- }-- function smokeLabOAuthEndpoints(- connection: typeof toolConnections.$inferSelect,- redirectUri?: string,- ): OAuthProviderEndpoints | null {- if (!isSmokeLabOAuthFixture(connection) || !redirectUri) return null;- let origin: string;- try {- origin = new URL(redirectUri).origin;- } catch {- return null;- }- const oauthBasePath = `/api/companies/${encodeURIComponent(connection.companyId)}/smoke-lab/oauth`;- return {- provider: "smoke_lab",- scopes: normalizeOauthScopes(oauthConfig(connection).scopes),- authorizationUrl: new URL(- `${oauthBasePath}/authorize`,- origin,- ).toString(),- tokenUrl: new URL(`${oauthBasePath}/token`, origin).toString(),- metadataUrl: null,- grantType: "authorization_code",- };- }-function configuredOAuthClientForConnection(connection: typeof toolConnections.$inferSelect,provider: string,@@ -8485,20 +7999,6 @@ export function toolAccessService(return randomBytes(bytes).toString("base64url");}- function oauthConfig(connection: typeof toolConnections.$inferSelect) {- const oauth = asRecord(connection.config).oauth- ? asRecord(asRecord(connection.config).oauth)- : {};- const {- access_token: _accessToken,- refresh_token: _refreshToken,- accessToken: _camelAccessToken,- refreshToken: _camelRefreshToken,- ...metadata- } = oauth;- return metadata;- }-function connectionSetupUrl(connection: typeof toolConnections.$inferSelect) {return `/apps/${connection.id}/permissions`;}@@ -8542,164 +8042,6 @@ export function toolAccessService(};}- function normalizeOauthScopes(value: unknown): string[] {- if (Array.isArray(value))- return value.filter(- (item): item is string =>- typeof item === "string" && item.trim().length > 0,- );- if (typeof value === "string")- return value- .split(/\s+/)- .map((item) => item.trim())- .filter(Boolean);- return [];- }-- /**- * Decide what a token grant actually carries, keeping the provider's assertion separate from- * our own request.- *- * RFC 6749 §5.1 permits a provider to omit `scope` only when the grant is identical to the- * request, so reading the request as the grant is the specified fallback. A provider that- * over-grants *and* omits `scope` breaks that contract, and recording the request unmarked- * turns what we asked for into a confident-looking record of what we got. `scopeSource` keeps- * the two readable apart so nothing downstream can mistake an inference for an assertion.- *- * `unrequestedScopes` is only meaningful when we asked for something specific; with no- * requested scopes there is no baseline to compare against, so it stays empty rather than- * flagging every scope on connections that keep their scopes in provider-side app config.- *- * `previous` is the provenance already recorded for this grant. A refresh response that omits- * `scope` asserts nothing at all — least of all that a permission was taken away — so the- * earlier record is carried forward verbatim instead of being overwritten with a clean-looking- * inference. Only a fresh provider assertion replaces a recorded over-grant.- */- function resolveGrantedOauthScopes(input: {- tokenScope: unknown;- requestedScopes: unknown;- previous?: {- scopes?: unknown;- scopeSource?: unknown;- unrequestedScopes?: unknown;- };- }): {- scopes: string[];- scopeSource: "provider" | "requested_fallback";- unrequestedScopes: string[];- } {- const requested = normalizeOauthScopes(input.requestedScopes);- const asserted =- input.tokenScope === undefined || input.tokenScope === null- ? []- : normalizeOauthScopes(input.tokenScope);- if (asserted.length === 0) {- const previousScopes = normalizeOauthScopes(input.previous?.scopes);- const previousUnrequested = normalizeOauthScopes(- input.previous?.unrequestedScopes,- );- if (previousScopes.length > 0) {- return {- scopes: previousScopes,- scopeSource:- input.previous?.scopeSource === "provider"- ? "provider"- : "requested_fallback",- unrequestedScopes: previousUnrequested,- };- }- return {- scopes: requested,- scopeSource: "requested_fallback",- unrequestedScopes: previousUnrequested,- };- }- return {- scopes: asserted,- scopeSource: "provider",- unrequestedScopes:- requested.length === 0- ? []- : asserted.filter((scope) => !requested.includes(scope)),- };- }-- function isSmokeLabOAuthUrl(value: string | null | undefined) {- if (!value) return false;- try {- return /\/smoke-lab\/oauth(?:\/|$)/.test(new URL(value).pathname);- } catch {- return false;- }- }-- function assertNotSmokeLabOAuthEndpoints(- connection: typeof toolConnections.$inferSelect,- endpoints: OAuthProviderEndpoints,- ) {- const blockedUrl = [- endpoints.authorizationUrl,- endpoints.tokenUrl,- endpoints.metadataUrl,- ].find(isSmokeLabOAuthUrl);- if (blockedUrl && !isSmokeLabOAuthFixture(connection)) {- throw unprocessable(- "Smoke Lab OAuth provider cannot be used for tool app sign-in",- );- }- }-- function oauthProviderForConnection(- connection: typeof toolConnections.$inferSelect,- metadataUrl?: string | null,- ): string {- const oauth = oauthConfig(connection);- if (typeof oauth.provider === "string" && oauth.provider.trim())- return oauth.provider.trim();- const sourceTemplateKey =- typeof connection.config.sourceTemplateKey === "string"- ? connection.config.sourceTemplateKey.trim()- : "";- if (sourceTemplateKey) return sourceTemplateKey;- const url = metadataUrl ?? remoteEndpoint(connection.config);- try {- return (- new URL(url).hostname- .replace(/[^a-z0-9]+/gi, "_")- .replace(/^_+|_+$/g, "")- .toLowerCase() || "generic"- );- } catch {- return "generic";- }- }-- function parseWwwAuthenticateParams(value: string): Record<string, string> {- const params: Record<string, string> = {};- const input = value.replace(/^\s*Bearer\s+/i, "");- const re = /([a-zA-Z_][a-zA-Z0-9_-]*)=(?:"([^"]*)"|([^,\s]+))/g;- let match: RegExpExecArray | null;- while ((match = re.exec(input))) {- params[match[1]!.toLowerCase()] = match[2] ?? match[3] ?? "";- }- return params;- }-- function challengeOAuthHints(wwwAuthenticate: string) {- const params = parseWwwAuthenticateParams(wwwAuthenticate);- return {- metadataUrl:- params.resource_metadata ??- params.resource_metadata_url ??- params.metadata_url ??- null,- authorizationUrl:- params.authorization_uri ?? params.authorization_url ?? null,- tokenUrl: params.token_uri ?? params.token_url ?? null,- scope: params.scope ?? null,- };- }-function oauthSecretRef(connection: typeof toolConnections.$inferSelect,configPath:@@ -8721,465 +8063,6 @@ export function toolAccessService(return Number.isFinite(ms) ? ms : null;}- async function fetchJsonRecord(- url: string,- ): Promise<Record<string, unknown> | null> {- try {- const response = await fetchRemoteHttpUrl(url);- if (!response.ok) return null;- return asRecord((await response.json()) as unknown) ?? null;- } catch {- return null;- }- }-- /**- * Candidate authorization-server metadata URLs advertised by protected-resource- * metadata, paired with the issuer that advertised them so the caller can bind- * the resulting client material to a canonical issuer.- */- function authServerMetadataUrls(- metadata: Record<string, unknown>,- ): Array<{ issuer: string; metadataUrl: string }> {- const candidates: Array<{ issuer: string; metadataUrl: string }> = [];- const issuers: string[] = [];- if (Array.isArray(metadata.authorization_servers)) {- for (const server of metadata.authorization_servers) {- if (typeof server === "string" && server.trim())- issuers.push(server.trim());- }- }- if (typeof metadata.issuer === "string" && metadata.issuer.trim())- issuers.push(metadata.issuer.trim());- for (const issuer of [...new Set(issuers)]) {- for (const metadataUrl of wellKnownMetadataUrls(issuer)) {- candidates.push({ issuer, metadataUrl });- }- }- const seen = new Set<string>();- return candidates.filter((candidate) => {- if (seen.has(candidate.metadataUrl)) return false;- seen.add(candidate.metadataUrl);- return true;- });- }-- async function endpointsFromMetadataUrl(- connection: typeof toolConnections.$inferSelect,- metadataUrl: string,- rejections: HttpError[] = [],- firstPartyOrigin?: string | null,- ): Promise<OAuthProviderEndpoints | null> {- const metadata = await fetchJsonRecord(metadataUrl);- if (!metadata) return null;- // Every endpoint below is a string the remote server chose, so none of them- // is adopted before `safeOAuthEndpointUrl` has vetted its scheme and host.- let authorizationUrl = safeOAuthEndpointUrl(- "authorization",- metadata.authorization_endpoint,- rejections,- firstPartyOrigin,- );- let tokenUrl = safeOAuthEndpointUrl(- "token",- metadata.token_endpoint,- rejections,- firstPartyOrigin,- );- let registrationUrl = safeOAuthEndpointUrl(- "registration",- metadata.registration_endpoint,- rejections,- firstPartyOrigin,- );- let scopes = normalizeOauthScopes(metadata.scopes_supported);- let offlineAccessSupported = Boolean(- authorizationUrl && scopes.includes("offline_access"),- );- let codeChallengeMethodsSupported = normalizeOauthScopes(- metadata.code_challenge_methods_supported,- );- let tokenEndpointAuthMethodsSupported = normalizeOauthScopes(- metadata.token_endpoint_auth_methods_supported,- );- let grantTypesSupported = normalizeOauthScopes(- metadata.grant_types_supported,- );- let clientIdMetadataDocumentSupported =- metadata.client_id_metadata_document_supported === true;- // A document that carries the authorization endpoint itself *is* the- // authorization-server metadata, so its own `issuer` is the canonical one.- // Otherwise this was protected-resource metadata and the issuer comes from- // whichever advertised authorization server answered.- let issuer =- authorizationUrl &&- typeof metadata.issuer === "string" &&- metadata.issuer.trim()- ? metadata.issuer.trim()- : null;- const resource =- typeof metadata.resource === "string" && metadata.resource.trim()- ? metadata.resource.trim()- : null;- for (const candidate of authServerMetadataUrls(metadata)) {- const authMetadata = await fetchJsonRecord(candidate.metadataUrl);- if (!authMetadata) continue;- const candidateAuthorizationUrl = safeOAuthEndpointUrl(- "authorization",- authMetadata.authorization_endpoint,- rejections,- firstPartyOrigin,- );- const candidateTokenUrl = safeOAuthEndpointUrl(- "token",- authMetadata.token_endpoint,- rejections,- firstPartyOrigin,- );- if (!candidateAuthorizationUrl && !candidateTokenUrl) continue;- // RFC 8414 §3.3: the metadata document's `issuer` must match the issuer we- // used to build the discovery URL, or the document is not authoritative.- const advertisedIssuer =- typeof authMetadata.issuer === "string" && authMetadata.issuer.trim()- ? authMetadata.issuer.trim()- : null;- if (- advertisedIssuer &&- !sameOAuthIssuer(advertisedIssuer, candidate.issuer)- )- continue;- // A document can carry its own endpoints and also list other servers.- // Adopt capabilities only from metadata bound to the selected endpoints- // and issuer; otherwise offline access could break an unrelated sign-in.- if (- (authorizationUrl && candidateAuthorizationUrl !== authorizationUrl) ||- (tokenUrl && candidateTokenUrl !== tokenUrl) ||- (issuer && !sameOAuthIssuer(issuer, advertisedIssuer ?? candidate.issuer))- )- continue;- authorizationUrl = authorizationUrl ?? candidateAuthorizationUrl;- tokenUrl = tokenUrl ?? candidateTokenUrl;- registrationUrl =- registrationUrl ??- safeOAuthEndpointUrl(- "registration",- authMetadata.registration_endpoint,- rejections,- firstPartyOrigin,- );- issuer = issuer ?? advertisedIssuer ?? candidate.issuer;- offlineAccessSupported = offlineAccessSupported ||- normalizeOauthScopes(authMetadata.scopes_supported).includes("offline_access");- if (scopes.length === 0)- scopes = normalizeOauthScopes(authMetadata.scopes_supported);- if (codeChallengeMethodsSupported.length === 0) {- codeChallengeMethodsSupported = normalizeOauthScopes(- authMetadata.code_challenge_methods_supported,- );- }- if (tokenEndpointAuthMethodsSupported.length === 0) {- tokenEndpointAuthMethodsSupported = normalizeOauthScopes(- authMetadata.token_endpoint_auth_methods_supported,- );- }- if (grantTypesSupported.length === 0) {- grantTypesSupported = normalizeOauthScopes(- authMetadata.grant_types_supported,- );- }- if (!clientIdMetadataDocumentSupported) {- clientIdMetadataDocumentSupported =- authMetadata.client_id_metadata_document_supported === true;- }- if (authorizationUrl && tokenUrl) break;- }- if (!authorizationUrl || !tokenUrl) return null;- return {- provider: oauthProviderForConnection(connection, metadataUrl),- scopes,- offlineAccessSupported,- authorizationUrl,- tokenUrl,- registrationUrl,- codeChallengeMethodsSupported,- tokenEndpointAuthMethodsSupported,- grantTypesSupported,- metadataUrl,- issuer,- resource,- clientIdMetadataDocumentSupported,- };- }-- async function discoverOAuthEndpoints(- connection: typeof toolConnections.$inferSelect,- challenge?: string | null,- firstPartyOrigin?: string | null,- ): Promise<OAuthProviderEndpoints | null> {- const oauth = oauthConfig(connection);- const hints = challenge ? challengeOAuthHints(challenge) : null;- // A configured endpoint was pasted by an operator or persisted from an- // earlier discovery, and a hint came straight out of the endpoint's- // `WWW-Authenticate` header. Neither is more trusted than metadata, so both- // go through the same gate; an unusable one is dropped so full metadata- // discovery still runs below.- const rejections: HttpError[] = [];- const configuredAuthorizationUrl = safeOAuthEndpointUrl(- "authorization",- typeof oauth.authorizationUrl === "string"- ? oauth.authorizationUrl- : (hints?.authorizationUrl ?? null),- rejections,- firstPartyOrigin,- );- const configuredTokenUrl = safeOAuthEndpointUrl(- "token",- typeof oauth.tokenUrl === "string"- ? oauth.tokenUrl- : (hints?.tokenUrl ?? null),- rejections,- firstPartyOrigin,- );- const provider = oauthProviderForConnection(- connection,- typeof oauth.metadataUrl === "string"- ? oauth.metadataUrl- : hints?.metadataUrl,- );- const scopes =- normalizeOauthScopes(oauth.scopes).length > 0- ? normalizeOauthScopes(oauth.scopes)- : normalizeOauthScopes(oauth.scope).length > 0- ? normalizeOauthScopes(oauth.scope)- : normalizeOauthScopes(hints?.scope);- const grantType =- oauth.grantType === "client_credentials" ||- oauth.clientCredentials === true- ? ("client_credentials" as const)- : ("authorization_code" as const);- // The resource indicator is the MCP endpoint itself, independent of which- // authorization server ends up serving it.- const configuredResource =- typeof oauth.resource === "string" && oauth.resource.trim()- ? oauth.resource.trim()- : canonicalResourceIndicator(remoteEndpoint(connection.config));- if (configuredAuthorizationUrl && configuredTokenUrl) {- // Pre-existing generic connections cached endpoints before refresh-scope- // support was recorded. Recover that capability from their bound metadata- // without adopting a different issuer or changing their requested tool scopes.- let refreshMetadata: OAuthProviderEndpoints | null = null;- if (- !connection.config.sourceTemplateKey &&- typeof oauth.offlineAccessSupported !== "boolean" &&- typeof oauth.metadataUrl === "string"- ) {- const discovered = await endpointsFromMetadataUrl(- connection, oauth.metadataUrl, rejections, firstPartyOrigin,- );- if (- discovered?.authorizationUrl === configuredAuthorizationUrl &&- discovered.tokenUrl === configuredTokenUrl &&- (typeof oauth.issuer !== "string" ||- (discovered.issuer && sameOAuthIssuer(discovered.issuer, oauth.issuer)))- ) refreshMetadata = discovered;- }- return {- provider,- scopes,- offlineAccessSupported: typeof oauth.offlineAccessSupported === "boolean"- ? oauth.offlineAccessSupported- : refreshMetadata?.offlineAccessSupported,- authorizationUrl: configuredAuthorizationUrl,- tokenUrl: configuredTokenUrl,- registrationUrl: safeOAuthEndpointUrl(- "registration",- oauth.registrationUrl,- rejections,- firstPartyOrigin,- ),- codeChallengeMethodsSupported: normalizeOauthScopes(- oauth.codeChallengeMethodsSupported,- ),- tokenEndpointAuthMethodsSupported: normalizeOauthScopes(- oauth.tokenEndpointAuthMethodsSupported,- ),- grantTypesSupported: Array.isArray(oauth.grantTypesSupported)- ? normalizeOauthScopes(oauth.grantTypesSupported)- : refreshMetadata?.grantTypesSupported,- grantType,- metadataUrl:- typeof oauth.metadataUrl === "string"- ? oauth.metadataUrl- : (hints?.metadataUrl ?? null),- issuer:- typeof oauth.issuer === "string" && oauth.issuer.trim()- ? oauth.issuer.trim()- : null,- resource: configuredResource,- clientIdMetadataDocumentSupported:- oauth.clientIdMetadataDocumentSupported === true,- };- }-- const metadataCandidates = [- typeof oauth.metadataUrl === "string" ? oauth.metadataUrl : null,- hints?.metadataUrl ?? null,- ].filter((value): value is string => Boolean(value));- if (metadataCandidates.length === 0) {- const endpoint = new URL(- await assertRemoteEndpointAllowed(connection.config),- );- metadataCandidates.push(...protectedResourceMetadataUrls(endpoint));- // The MCP server may double as its own authorization server, in which case- // it serves authorization-server metadata directly at (or under) its path.- metadataCandidates.push(...wellKnownMetadataUrls(endpoint.toString()));- }- for (const metadataUrl of [...new Set(metadataCandidates)]) {- const endpoints = await endpointsFromMetadataUrl(- connection,- metadataUrl,- rejections,- firstPartyOrigin,- );- if (endpoints) {- return {- ...endpoints,- scopes: scopes.length > 0 ? scopes : endpoints.scopes,- grantType,- resource: endpoints.resource ?? configuredResource,- };- }- }- // Nothing usable was found *and* something was refused on the way: report the- // refusal rather than the generic "does not advertise OAuth sign in", so the- // operator learns the server offered an unsafe address.- if (rejections.length > 0) throw rejections[0];- return null;- }-- async function oauthProviderEndpoints(- app: AppDefinition,- methodKey?: string | null,- ): Promise<OAuthProviderEndpoints> {- const method = connectionMethodFor(app, methodKey);- if (method.auth !== "oauth")- throw unprocessable("This app does not support sign in");- let authorizationUrl = method.defaults?.authorizationEndpoint ?? null;- let tokenUrl = method.defaults?.tokenEndpoint ?? null;- const metadataUrl = method.defaults?.metadataUrl ?? null;- if ((!authorizationUrl || !tokenUrl) && metadataUrl) {- const response = await fetchRemoteHttpUrl(metadataUrl);- if (!response.ok)- throw new HttpError(- 502,- "OAuth provider metadata could not be loaded",- { code: "oauth_metadata_failed" },- );- const metadata = asRecord((await response.json()) as unknown);- authorizationUrl =- authorizationUrl ??- (typeof metadata.authorization_endpoint === "string"- ? metadata.authorization_endpoint- : null);- tokenUrl =- tokenUrl ??- (typeof metadata.token_endpoint === "string"- ? metadata.token_endpoint- : null);- }- if (!authorizationUrl || !tokenUrl) {- throw unprocessable(- "OAuth provider endpoints are not configured for this app",- );- }- // A gallery default is Paperclip's own data, but it is still a URL that ends- // up as a browser navigation, and the metadata branch above reads the same- // untrusted document a generic connection does. Both go through the gate.- return {- provider: app.slug,- scopes: method.defaults?.scopesHint ?? [],- authorizationUrl: assertOAuthEndpointUrl(- "authorization",- authorizationUrl,- ),- tokenUrl: assertOAuthEndpointUrl("token", tokenUrl),- grantType: "authorization_code",- metadataUrl,- };- }-- async function oauthEndpointsForConnection(- connection: typeof toolConnections.$inferSelect,- challenge?: string | null,- redirectUri?: string,- ): Promise<OAuthProviderEndpoints> {- const smokeLabEndpoints = smokeLabOAuthEndpoints(connection, redirectUri);- const sourceTemplateKey =- typeof connection.config.sourceTemplateKey === "string"- ? connection.config.sourceTemplateKey- : null;- const galleryEntry = sourceTemplateKey- ? getConnectableAppDefinition(sourceTemplateKey)- : null;- const galleryMethod = galleryEntry- ? connectionMethodForConnection(galleryEntry, connection)- : null;- // Pinned endpoints describe the provider's console-registered OAuth app.- // A method that also offers dynamic registration registers against the MCP- // server's own authorization server (Linear: mcp.linear.app, not- // linear.app), which only discovery finds. So the pins stand in for- // discovery only when no registration is possible or the connection- // already carries an operator-entered client.- const storedOAuth = oauthConfig(connection);- const usesOperatorClient =- storedOAuth.clientRegistrationSource === "manual" &&- connection.ownership !== "dcr" &&- typeof storedOAuth.clientId === "string" &&- storedOAuth.clientId.trim().length > 0;- // A reviewed protected-resource document is authoritative for this method.- // Some hosts still serve metadata for a retired MCP server at the root.- // Resolve it before cached endpoints, including on existing draft reconnects.- if (!smokeLabEndpoints && galleryMethod?.defaults?.discoveryUrl) {- const endpoints = await endpointsFromMetadataUrl(- connection, galleryMethod.defaults.discoveryUrl, [], originOf(redirectUri),- );- if (!endpoints) throw unprocessable("OAuth provider metadata could not be loaded");- assertNotSmokeLabOAuthEndpoints(connection, endpoints);- return endpoints;- }- const hasCompleteGalleryEndpointHints = Boolean(- galleryMethod?.defaults?.authorizationEndpoint &&- galleryMethod.defaults.tokenEndpoint &&- (!galleryMethod.ownershipModes.includes("dcr") || usesOperatorClient),- );- // The smoke-lab fixture's endpoints are first-party and complete, so- // discovery is not just unnecessary there, it must not run: an unreachable- // fixture endpoint would fail the whole callback.- const firstPartyOrigin = originOf(redirectUri);- const discovered =- !smokeLabEndpoints &&- connection.transport === "mcp_remote" &&- !hasCompleteGalleryEndpointHints- ? await discoverOAuthEndpoints(connection, challenge, firstPartyOrigin)- : null;- const endpoints =- smokeLabEndpoints ??- discovered ??- (galleryEntry && galleryMethod?.auth === "oauth"- ? await oauthProviderEndpoints(galleryEntry, galleryMethod.key)- : await discoverOAuthEndpoints(- connection,- challenge,- firstPartyOrigin,- ));- if (!endpoints)- throw unprocessable(- "This app connection does not advertise OAuth sign in",- );- assertNotSmokeLabOAuthEndpoints(connection, endpoints);- return endpoints;- }-async function oauthGalleryEntryForConnection(connection: typeof toolConnections.$inferSelect,) {@@ -9300,299 +8183,16 @@ export function toolAccessService();}- function invalidOAuthDcrResponse(field: string, reason: string): HttpError {- return new HttpError(- 502,- "OAuth provider returned incompatible dynamic client metadata",- {- code: "oauth_dcr_response_invalid",- field,- reason,- },- );- }-- function parseOAuthDcrString(- record: Record<string, unknown>,- field: "client_id" | "client_secret",- input: { required: boolean; maxLength: number },- ): string | null {- const value = record[field];- if (value === undefined || value === null) {- if (input.required) throw invalidOAuthDcrResponse(field, "missing");- return null;- }- if (- typeof value !== "string" ||- value.length === 0 ||- value.length > input.maxLength- ) {- throw invalidOAuthDcrResponse(field, "invalid_string");- }- if (field === "client_id" && value.trim() !== value) {- throw invalidOAuthDcrResponse(field, "invalid_string");- }- return value;- }-- function assertOAuthDcrArray(- record: Record<string, unknown>,- field: "redirect_uris" | "grant_types" | "response_types",- expected: string[],- options: { allowAdditional?: boolean; allowOmitted?: boolean } = {},- ) {- if (record[field] === undefined) {- if (options.allowOmitted) return;- throw invalidOAuthDcrResponse(field, "missing");- }- const value = record[field];- if (- !Array.isArray(value) ||- value.length < expected.length ||- value.length > 32 ||- value.some(- (entry) =>- typeof entry !== "string" ||- entry.length === 0 ||- entry.length > 2_048,- )- ) {- throw invalidOAuthDcrResponse(field, "invalid_array");- }- const actual = new Set(value);- if (- expected.some((entry) => !actual.has(entry)) ||- (!options.allowAdditional && actual.size !== expected.length)- ) {- throw invalidOAuthDcrResponse(field, "registered_value_mismatch");- }- }-- function parseOAuthDcrTimestamp(- record: Record<string, unknown>,- field: string,- ): number | null {- const value = record[field];- if (value === undefined || value === null) return null;- if (- typeof value !== "number" ||- !Number.isSafeInteger(value) ||- value < 0- ) {- throw invalidOAuthDcrResponse(field, "invalid_timestamp");- }- return value;- }-- type OAuthTokenEndpointAuthMethod =- "none" | "client_secret_basic" | "client_secret_post";-- function selectOAuthDcrTokenEndpointAuthMethod(- supported: string[] | undefined,- ): OAuthTokenEndpointAuthMethod {- if (!supported?.length || supported.includes("none")) return "none";- // When a confidential client is required, preserve the provider's advertised- // ordering. Miro advertises both methods but only completes its MCP exchange- // for the first one (`client_secret_post`), while Supabase and Hugging Face- // advertise `client_secret_basic` first. Treating Basic as a global preference- // creates a valid-looking registration that fails only after user consent.- for (const method of supported) {- if (method === "client_secret_basic" || method === "client_secret_post")- return method;- }- throw unprocessable(- "OAuth provider does not support a compatible dynamic client authentication method",- {- code: "oauth_dcr_client_auth_unsupported",- supportedMethods: supported,- },- );- }-- function storedOAuthTokenEndpointAuthMethod(- oauth: Record<string, unknown>,- clientSecret: string | null | undefined,- ): OAuthTokenEndpointAuthMethod {- const method = oauth.clientTokenEndpointAuthMethod;- if (- method === "none" ||- method === "client_secret_basic" ||- method === "client_secret_post"- ) {- return method;- }- const advertised = Array.isArray(oauth.tokenEndpointAuthMethodsSupported)- ? oauth.tokenEndpointAuthMethodsSupported.filter(- (value): value is string => typeof value === "string",- )- : [];- // Manual OAuth clients do not carry a DCR-selected method. Follow the- // authorization server's advertised preference when it offers a- // confidential-client method; Xero, for example, documents Basic auth and- // rejects an otherwise valid code when the secret is posted in the body.- if (clientSecret && advertised.includes("client_secret_basic"))- return "client_secret_basic";- if (clientSecret && advertised.includes("client_secret_post"))- return "client_secret_post";- // Existing manually configured and preconfigured clients predate the- // persisted method field and already use client_secret_post successfully.- return clientSecret ? "client_secret_post" : "none";- }-async function registerOAuthClient(input: {connection: typeof toolConnections.$inferSelect;endpoints: OAuthProviderEndpoints;redirectUri: string;actor?: ActorInfo;}) {- if (!input.endpoints.registrationUrl) {- throw unprocessable(- "OAuth provider does not advertise dynamic client registration",- {- code: "oauth_dcr_not_supported",- },- );- }- if (- input.endpoints.codeChallengeMethodsSupported?.length &&- !input.endpoints.codeChallengeMethodsSupported.includes("S256")- ) {- throw unprocessable(- "OAuth provider does not support the required PKCE S256 method",- {- code: "oauth_pkce_s256_required",- },- );- }- const tokenEndpointAuthMethod = selectOAuthDcrTokenEndpointAuthMethod(- input.endpoints.tokenEndpointAuthMethodsSupported,- );-- const host = new URL(input.redirectUri).host;- const clientNameHost = host- .replace(/[^A-Za-z0-9-]/g, "-")- .replace(/-+/g, "-")- .replace(/^-|-$/g, "");- const requestedMetadata = {- // Some DCR servers restrict client_name to alphanumeric characters,- // hyphens and spaces. Keep the deployment host recognizable without- // sending punctuation such as dots, colons or parentheses.- client_name: `Paperclip ${clientNameHost}`,- redirect_uris: [input.redirectUri],- grant_types: [- "authorization_code",- ...(!input.endpoints.grantTypesSupported?.length ||- input.endpoints.grantTypesSupported.includes("refresh_token")- ? ["refresh_token"]- : []),- ],- response_types: ["code"],- token_endpoint_auth_method: tokenEndpointAuthMethod,- // RFC 7591: Paperclip's callback is a server-side HTTPS endpoint, so this- // is a `web` client, not a `native` one. Some authorization servers reject- // an https redirect URI when the default (`web`) is left implicit, and- // others apply native-client redirect rules without it.- application_type: "web",- };- const response = await fetchRemoteHttpUrl(- assertOAuthEndpointUrl("registration", input.endpoints.registrationUrl),- {- method: "POST",- headers: { "content-type": "application/json" },- body: JSON.stringify(requestedMetadata),- },- );- const record = asRecord(- (await response.json().catch(() => ({}))) as unknown,- );- if (!response.ok) {- const providerError = normalizeOAuthProviderError(record.error);- throw new HttpError(- 502,- oauthProviderErrorMessage(- providerError,- "OAuth dynamic client registration failed",- ),- {- code: "oauth_dynamic_client_registration_failed",- providerError,- status: response.status,- },- );- }- const clientId = parseOAuthDcrString(record, "client_id", {- required: true,- maxLength: MAX_OAUTH_DCR_CLIENT_ID_LENGTH,- })!;- const clientSecret = parseOAuthDcrString(record, "client_secret", {- required: tokenEndpointAuthMethod !== "none",- maxLength: MAX_OAUTH_DCR_CLIENT_SECRET_LENGTH,- });- // Some authorization servers add provider-owned metadata to the registered- // client. Paperclip still uses only the exact redirect, grant and response- // types it requested, so accept bounded supersets while requiring every- // requested value to remain present. Hugging Face, for example, adds the- // device-code grant to an otherwise valid authorization-code registration.- assertOAuthDcrArray(- record,- "redirect_uris",- requestedMetadata.redirect_uris,- { allowAdditional: true },- );- // RFC 7591 registration responses do not consistently echo every accepted- // request field. Supabase, for example, returns only the client material and- // redirect URIs. Redirect binding remains mandatory; omitted grant/response- // metadata inherits the values Paperclip requested. Additional provider-owned- // values do not widen Paperclip's behavior because they are never persisted as- // a flow choice or sent in authorization/token requests.- assertOAuthDcrArray(record, "grant_types", requestedMetadata.grant_types, {- allowAdditional: true,- allowOmitted: true,+ const { clientId, clientSecret, tokenEndpointAuthMethod, clientIdIssuedAt, clientSecretExpiresAt } = await requestOAuthClientRegistration({+ endpoints: input.endpoints,+ redirectUri: input.redirectUri,});- assertOAuthDcrArray(- record,- "response_types",- requestedMetadata.response_types,- {- allowAdditional: true,- allowOmitted: true,- },- );- if (- record.token_endpoint_auth_method !== undefined &&- record.token_endpoint_auth_method !==- requestedMetadata.token_endpoint_auth_method- ) {- throw invalidOAuthDcrResponse(- "token_endpoint_auth_method",- "registered_value_mismatch",- );- }- const clientIdIssuedAt = parseOAuthDcrTimestamp(- record,- "client_id_issued_at",- );- const returnedClientSecretExpiresAt = parseOAuthDcrTimestamp(- record,- "client_secret_expires_at",- );- // A few public-client registrars (including Mixpanel) return the RFC 7591- // `0` sentinel even though they issued no secret. It carries no credential- // lifetime in that case, so normalize it away. A positive expiry without a- // secret is still contradictory and remains a hard failure.- if (- returnedClientSecretExpiresAt !== null &&- returnedClientSecretExpiresAt > 0 &&- clientSecret === null- ) {- throw invalidOAuthDcrResponse(- "client_secret_expires_at",- "client_secret_missing",- );- }- const clientSecretExpiresAt = clientSecret- ? returnedClientSecretExpiresAt- : null;const existingClientSecretRef = oauthSecretRef(input.connection,"oauth.client_secret",@@ -10107,141 +8707,6 @@ export function toolAccessService(});}- async function exchangeOAuthToken(input: {- tokenUrl: string;- clientId: string;- clientSecret?: string | null;- tokenEndpointAuthMethod?: OAuthTokenEndpointAuthMethod;- grantType?: "authorization_code" | "refresh_token" | "client_credentials";- scopes?: string[];- redirectUri?: string | null;- codeVerifier?: string | null;- code?: string | null;- refreshToken?: string | null;- /** RFC 8707 resource indicator: the MCP server this token is for. */- resource?: string | null;- }) {- const body = new URLSearchParams();- if (input.grantType === "client_credentials") {- body.set("grant_type", "client_credentials");- if (input.scopes && input.scopes.length > 0)- body.set("scope", input.scopes.join(" "));- } else if (input.refreshToken) {- body.set("grant_type", "refresh_token");- body.set("refresh_token", input.refreshToken);- } else {- body.set("grant_type", "authorization_code");- body.set("code", input.code ?? "");- 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")- body.set("client_id", input.clientId);- if (tokenEndpointAuthMethod === "client_secret_post") {- if (!input.clientSecret) {- throw unprocessable(- "OAuth client secret is missing for client_secret_post authentication",- {- code: "oauth_client_secret_missing",- },- );- }- body.set("client_secret", input.clientSecret);- }- // RFC 8707: repeat the resource indicator on the token request so the- // authorization server audience-restricts the access token (and any refresh- // exchange) to this MCP server.- if (input.resource) body.set("resource", input.resource);-- // The token URL can come from a connection row written before the endpoint- // gate existed, so a client secret / authorization code never leaves- // Paperclip without re-checking the transport it would leave over.- const tokenUrl = assertOAuthEndpointUrl("token", input.tokenUrl, {- // Paperclip's own callback origin, so a first-party token endpoint keeps- // working on a deployment that is itself served over plaintext HTTP.- firstPartyOrigin: originOf(input.redirectUri),- });- const headers: Record<string, string> = {- "content-type": "application/x-www-form-urlencoded",- // Some providers otherwise return a legacy form-encoded token response.- accept: "application/json",- };- if (tokenEndpointAuthMethod === "client_secret_basic") {- if (!input.clientSecret) {- throw unprocessable(- "OAuth client secret is missing for client_secret_basic authentication",- {- code: "oauth_client_secret_missing",- },- );- }- const formEncode = (value: string) =>- new URLSearchParams({ value }).toString().slice("value=".length);- headers.Authorization = `Basic ${Buffer.from(- `${formEncode(input.clientId)}:${formEncode(input.clientSecret)}`,- "utf8",- ).toString("base64")}`;- }- const response = await fetchRemoteHttpUrl(tokenUrl, {- method: "POST",- headers,- body,- });- const payload = (await response.json().catch(() => ({}))) as unknown;- const record = asRecord(payload);- if (!response.ok || record.ok === false) {- const providerError = normalizeOAuthProviderError(record.error);- const message = oauthProviderErrorMessage(- providerError,- "OAuth token exchange failed",- );- if (- input.grantType === "refresh_token" &&- providerError === "invalid_grant"- ) {- throw new HttpError(- 422,- "OAuth authorization has expired. Reconnect this app to continue.",- {- code: "oauth_reauthorization_required",- providerError,- status: response.status,- },- );- }- throw new HttpError(502, message, {- code: "oauth_token_exchange_failed",- providerError,- status: response.status,- });- }- const accessToken =- typeof record.access_token === "string" ? record.access_token : null;- if (!accessToken)- throw new HttpError(- 502,- "OAuth provider did not return an access token",- { code: "oauth_access_token_missing" },- );- const expiresIn =- typeof record.expires_in === "number"- ? record.expires_in- : Number(record.expires_in);- return {- accessToken,- refreshToken:- typeof record.refresh_token === "string" ? record.refresh_token : null,- expiresIn: Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : null,- scope: typeof record.scope === "string" ? record.scope : null,- tokenType:- typeof record.token_type === "string" ? record.token_type : "Bearer",- raw: record,- };- }-function withoutOAuthRefreshLease(oauth: Record<string, unknown>) {const { refreshLease: _refreshLease, ...rest } = oauth;return rest;@@ -16810,96 +15275,7 @@ export function toolAccessService(const serverUrl = await assertRemoteHttpUrlAllowed(method.defaults.serverUrl,);- const attempts: ToolAppMetadataPreflightResult["attempts"] = [];- const endpointResponse = await fetchRemoteHttpUrl(serverUrl, {- method: "GET",- headers: { Accept: "application/json, text/event-stream" },- });- attempts.push({- kind: "endpoint",- url: serverUrl,- status: endpointResponse.status,- ok: endpointResponse.ok,- contentType: endpointResponse.headers.get("content-type"),- });-- if (method.auth !== "oauth") {- return {- galleryKey: app.slug,- methodKey: method.key,- serverUrl,- endpointReachable: endpointResponse.status < 500,- oauth: null,- attempts,- checkedAt: (options.now?.() ?? new Date()).toISOString(),- };- }-- const endpoint = new URL(serverUrl);- const metadataQueue = [- method.defaults.discoveryUrl ?? null,- method.defaults.metadataUrl ?? null,- ...protectedResourceMetadataUrls(endpoint),- ...wellKnownMetadataUrls(endpoint.toString()),- ].filter((url): url is string => Boolean(url));- const visited = new Set<string>();- let metadataFound = false;- let registrationAdvertised = false;- let clientIdMetadataDocumentSupported = false;-- while (metadataQueue.length > 0 && visited.size < 16) {- const metadataUrl = metadataQueue.shift()!;- if (visited.has(metadataUrl)) continue;- visited.add(metadataUrl);- const response = await fetchRemoteHttpUrl(metadataUrl, {- method: "GET",- headers: { Accept: "application/json" },- });- attempts.push({- kind: "oauth_metadata",- url: metadataUrl,- status: response.status,- ok: response.ok,- contentType: response.headers.get("content-type"),- });- if (!response.ok) continue;- let metadata: Record<string, unknown>;- try {- metadata = asRecord((await response.json()) as unknown);- } catch {- continue;- }- const looksLikeOAuthMetadata = Boolean(- metadata.authorization_endpoint ||- metadata.token_endpoint ||- metadata.authorization_servers ||- metadata.resource,- );- if (!looksLikeOAuthMetadata) continue;- metadataFound = true;- registrationAdvertised ||=- typeof metadata.registration_endpoint === "string";- clientIdMetadataDocumentSupported ||=- metadata.client_id_metadata_document_supported === true;- for (const candidate of authServerMetadataUrls(metadata)) {- if (!visited.has(candidate.metadataUrl))- metadataQueue.push(candidate.metadataUrl);- }- }-- return {- galleryKey: app.slug,- methodKey: method.key,- serverUrl,- endpointReachable: endpointResponse.status < 500,- oauth: {- metadataFound,- registrationAdvertised,- clientIdMetadataDocumentSupported,- },- attempts,- checkedAt: (options.now?.() ?? new Date()).toISOString(),- };+ return preflightConnectionMetadata(app, method, method.defaults, serverUrl, () => options.now?.() ?? new Date());}async function resolveEffectiveProfiles<TEntry extends ProfileCatalogEntry, TAllowedTool>(diff --git a/server/src/services/tool-access/connection-methods.ts b/server/src/services/tool-access/connection-methods.tsindex 31d6e538fb..4ddd35ca07 100644--- a/server/src/services/tool-access/connection-methods.ts+++ b/server/src/services/tool-access/connection-methods.ts@@ -1,3 +1,4 @@+import { parseRemoteHttpEndpoint } from "../remote-http-endpoint-guard.js";import type { AppDefinition, ConnectionMethodDef, ToolConnectionTransport } from "@paperclipai/shared";import {credentialConfigPath,@@ -357,3 +358,11 @@ export function projectedConnectionToolInputSchema(inputSchema,);}++export function remoteEndpoint(config: Record<string, unknown>): string {+ const value = config.url ?? config.endpoint ?? config.remoteUrl;+ const parsed = parseRemoteHttpEndpoint(value, (message, code) =>+ badRequest(message, { code }),+ );+ return parsed.toString();+}diff --git a/server/src/services/tool-access/oauth/client-metadata.ts b/server/src/services/tool-access/oauth/client-metadata.tsnew file mode 100644index 0000000000..2aeecad72f--- /dev/null+++ b/server/src/services/tool-access/oauth/client-metadata.ts@@ -0,0 +1,80 @@+import { assertPublicRemoteHttpEndpoint, type RemoteHttpEndpointLookup } from "../../remote-http-endpoint-guard.js";++/**+ * Where this deployment publishes its Client ID Metadata Document. The document's+ * own URL is the `client_id` Paperclip presents, so this path is a stable part of+ * the deployment's public contract with every authorization server that has seen+ * it — changing it invalidates existing CIMD registrations.+ */+export const OAUTH_CLIENT_ID_METADATA_DOCUMENT_PATH =+ "/api/tools/oauth/client-metadata";++/**+ * Resolve the URL Paperclip would use as a CIMD client id, but only when its+ * hostname is not known to resolve into a private network.+ *+ * An authorization server fetches this URL from outside Paperclip's network and+ * will normally apply an SSRF guard. Tailscale/MagicDNS names are HTTPS but+ * resolve into 100.64.0.0/10, so presenting one as a client id can only produce+ * an `invalid_client` response. A local DNS failure remains inconclusive because+ * split-horizon public DNS may still let the authorization server resolve it.+ */+export async function resolveOAuthClientIdMetadataDocumentUrl(+ redirectUri: string,+ lookup?: RemoteHttpEndpointLookup,+): Promise<string | null> {+ try {+ const parsed = new URL(redirectUri);+ if (parsed.protocol !== "https:") return null;+ const hostname = parsed.hostname.replace(/^\[|\]$/g, "").toLowerCase();+ const isLoopback =+ hostname === "localhost" ||+ hostname.endsWith(".localhost") ||+ hostname === "::1" ||+ /^127(?:\.\d{1,3}){3}$/.test(hostname);+ if (isLoopback) return null;+ const metadataUrl = new URL(+ OAUTH_CLIENT_ID_METADATA_DOCUMENT_PATH,+ parsed.origin,+ ).toString();+ try {+ await assertPublicRemoteHttpEndpoint(+ new URL(metadataUrl),+ { allowPrivateNetwork: false, lookup },+ (message, code) => Object.assign(new Error(message), { code }),+ );+ } catch (error) {+ if (+ error instanceof Error &&+ "code" in error &&+ error.code === "remote_http_private_endpoint"+ ) {+ return null;+ }+ }+ return metadataUrl;+ } catch {+ return null;+ }+}++/**+ * Paperclip's client metadata for CIMD (RFC 7591 metadata, served rather than+ * registered). Only the callback for this deployment appears in it, so an+ * authorization server that fetches it can see exactly one legal redirect target.+ */+export function oauthClientIdMetadataDocument(input: {+ clientId: string;+ redirectUri: string;+}): Record<string, unknown> {+ return {+ client_id: input.clientId,+ client_name: `Paperclip (${new URL(input.redirectUri).host})`,+ client_uri: new URL("/", input.clientId).toString(),+ redirect_uris: [input.redirectUri],+ grant_types: ["authorization_code", "refresh_token"],+ response_types: ["code"],+ token_endpoint_auth_method: "none",+ application_type: "web",+ };+}diff --git a/server/src/services/tool-access/oauth/client.ts b/server/src/services/tool-access/oauth/client.tsnew file mode 100644index 0000000000..5c5dee5bbd--- /dev/null+++ b/server/src/services/tool-access/oauth/client.ts@@ -0,0 +1,434 @@+import { HttpError, unprocessable } from "../../../errors.js";+import { asRecord, originOf } from "./metadata.js";+import { normalizeOAuthProviderError, oauthProviderErrorMessage } from "./provider-errors.js";+import type { OAuthProviderEndpoints, OAuthTokenEndpointAuthMethod, OAuthTransport } from "./types.js";++const MAX_OAUTH_DCR_CLIENT_ID_LENGTH = 4_096;++const MAX_OAUTH_DCR_CLIENT_SECRET_LENGTH = 16_384;++function invalidOAuthDcrResponse(field: string, reason: string): HttpError {+ return new HttpError(+ 502,+ "OAuth provider returned incompatible dynamic client metadata",+ {+ code: "oauth_dcr_response_invalid",+ field,+ reason,+ },+ );+}++function parseOAuthDcrString(+ record: Record<string, unknown>,+ field: "client_id" | "client_secret",+ input: { required: boolean; maxLength: number },+): string | null {+ const value = record[field];+ if (value === undefined || value === null) {+ if (input.required) throw invalidOAuthDcrResponse(field, "missing");+ return null;+ }+ if (+ typeof value !== "string" ||+ value.length === 0 ||+ value.length > input.maxLength+ ) {+ throw invalidOAuthDcrResponse(field, "invalid_string");+ }+ if (field === "client_id" && value.trim() !== value) {+ throw invalidOAuthDcrResponse(field, "invalid_string");+ }+ return value;+}++function assertOAuthDcrArray(+ record: Record<string, unknown>,+ field: "redirect_uris" | "grant_types" | "response_types",+ expected: string[],+ options: { allowAdditional?: boolean; allowOmitted?: boolean } = {},+) {+ if (record[field] === undefined) {+ if (options.allowOmitted) return;+ throw invalidOAuthDcrResponse(field, "missing");+ }+ const value = record[field];+ if (+ !Array.isArray(value) ||+ value.length < expected.length ||+ value.length > 32 ||+ value.some(+ (entry) =>+ typeof entry !== "string" ||+ entry.length === 0 ||+ entry.length > 2_048,+ )+ ) {+ throw invalidOAuthDcrResponse(field, "invalid_array");+ }+ const actual = new Set(value);+ if (+ expected.some((entry) => !actual.has(entry)) ||+ (!options.allowAdditional && actual.size !== expected.length)+ ) {+ throw invalidOAuthDcrResponse(field, "registered_value_mismatch");+ }+}++function parseOAuthDcrTimestamp(+ record: Record<string, unknown>,+ field: string,+): number | null {+ const value = record[field];+ if (value === undefined || value === null) return null;+ if (+ typeof value !== "number" ||+ !Number.isSafeInteger(value) ||+ value < 0+ ) {+ throw invalidOAuthDcrResponse(field, "invalid_timestamp");+ }+ return value;+}++function selectOAuthDcrTokenEndpointAuthMethod(+ supported: string[] | undefined,+): OAuthTokenEndpointAuthMethod {+ if (!supported?.length || supported.includes("none")) return "none";+ // When a confidential client is required, preserve the provider's advertised+ // ordering. Miro advertises both methods but only completes its MCP exchange+ // for the first one (`client_secret_post`), while Supabase and Hugging Face+ // advertise `client_secret_basic` first. Treating Basic as a global preference+ // creates a valid-looking registration that fails only after user consent.+ for (const method of supported) {+ if (method === "client_secret_basic" || method === "client_secret_post")+ return method;+ }+ throw unprocessable(+ "OAuth provider does not support a compatible dynamic client authentication method",+ {+ code: "oauth_dcr_client_auth_unsupported",+ supportedMethods: supported,+ },+ );+}++export function storedOAuthTokenEndpointAuthMethod(+ oauth: Record<string, unknown>,+ clientSecret: string | null | undefined,+): OAuthTokenEndpointAuthMethod {+ const method = oauth.clientTokenEndpointAuthMethod;+ if (+ method === "none" ||+ method === "client_secret_basic" ||+ method === "client_secret_post"+ ) {+ return method;+ }+ const advertised = Array.isArray(oauth.tokenEndpointAuthMethodsSupported)+ ? oauth.tokenEndpointAuthMethodsSupported.filter(+ (value): value is string => typeof value === "string",+ )+ : [];+ // Manual OAuth clients do not carry a DCR-selected method. Follow the+ // authorization server's advertised preference when it offers a+ // confidential-client method; Xero, for example, documents Basic auth and+ // rejects an otherwise valid code when the secret is posted in the body.+ if (clientSecret && advertised.includes("client_secret_basic"))+ return "client_secret_basic";+ if (clientSecret && advertised.includes("client_secret_post"))+ return "client_secret_post";+ // Existing manually configured and preconfigured clients predate the+ // persisted method field and already use client_secret_post successfully.+ return clientSecret ? "client_secret_post" : "none";+}++export function createOAuthClientProtocol({ fetchRemoteHttpUrl, assertOAuthEndpointUrl }: OAuthTransport) {+ async function requestOAuthClientRegistration(input: { endpoints: OAuthProviderEndpoints; redirectUri: string }) {+ if (!input.endpoints.registrationUrl) {+ throw unprocessable(+ "OAuth provider does not advertise dynamic client registration",+ {+ code: "oauth_dcr_not_supported",+ },+ );+ }+ if (+ input.endpoints.codeChallengeMethodsSupported?.length &&+ !input.endpoints.codeChallengeMethodsSupported.includes("S256")+ ) {+ throw unprocessable(+ "OAuth provider does not support the required PKCE S256 method",+ {+ code: "oauth_pkce_s256_required",+ },+ );+ }+ const tokenEndpointAuthMethod = selectOAuthDcrTokenEndpointAuthMethod(+ input.endpoints.tokenEndpointAuthMethodsSupported,+ );++ const host = new URL(input.redirectUri).host;+ const clientNameHost = host+ .replace(/[^A-Za-z0-9-]/g, "-")+ .replace(/-+/g, "-")+ .replace(/^-|-$/g, "");+ const requestedMetadata = {+ // Some DCR servers restrict client_name to alphanumeric characters,+ // hyphens and spaces. Keep the deployment host recognizable without+ // sending punctuation such as dots, colons or parentheses.+ client_name: `Paperclip ${clientNameHost}`,+ redirect_uris: [input.redirectUri],+ grant_types: [+ "authorization_code",+ ...(!input.endpoints.grantTypesSupported?.length ||+ input.endpoints.grantTypesSupported.includes("refresh_token")+ ? ["refresh_token"]+ : []),+ ],+ response_types: ["code"],+ token_endpoint_auth_method: tokenEndpointAuthMethod,+ // RFC 7591: Paperclip's callback is a server-side HTTPS endpoint, so this+ // is a `web` client, not a `native` one. Some authorization servers reject+ // an https redirect URI when the default (`web`) is left implicit, and+ // others apply native-client redirect rules without it.+ application_type: "web",+ };+ const response = await fetchRemoteHttpUrl(+ assertOAuthEndpointUrl("registration", input.endpoints.registrationUrl),+ {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify(requestedMetadata),+ },+ );+ const record = asRecord(+ (await response.json().catch(() => ({}))) as unknown,+ );+ if (!response.ok) {+ const providerError = normalizeOAuthProviderError(record.error);+ throw new HttpError(+ 502,+ oauthProviderErrorMessage(+ providerError,+ "OAuth dynamic client registration failed",+ ),+ {+ code: "oauth_dynamic_client_registration_failed",+ providerError,+ status: response.status,+ },+ );+ }+ const clientId = parseOAuthDcrString(record, "client_id", {+ required: true,+ maxLength: MAX_OAUTH_DCR_CLIENT_ID_LENGTH,+ })!;+ const clientSecret = parseOAuthDcrString(record, "client_secret", {+ required: tokenEndpointAuthMethod !== "none",+ maxLength: MAX_OAUTH_DCR_CLIENT_SECRET_LENGTH,+ });+ // Some authorization servers add provider-owned metadata to the registered+ // client. Paperclip still uses only the exact redirect, grant and response+ // types it requested, so accept bounded supersets while requiring every+ // requested value to remain present. Hugging Face, for example, adds the+ // device-code grant to an otherwise valid authorization-code registration.+ assertOAuthDcrArray(+ record,+ "redirect_uris",+ requestedMetadata.redirect_uris,+ { allowAdditional: true },+ );+ // RFC 7591 registration responses do not consistently echo every accepted+ // request field. Supabase, for example, returns only the client material and+ // redirect URIs. Redirect binding remains mandatory; omitted grant/response+ // metadata inherits the values Paperclip requested. Additional provider-owned+ // values do not widen Paperclip's behavior because they are never persisted as+ // a flow choice or sent in authorization/token requests.+ assertOAuthDcrArray(record, "grant_types", requestedMetadata.grant_types, {+ allowAdditional: true,+ allowOmitted: true,+ });+ assertOAuthDcrArray(+ record,+ "response_types",+ requestedMetadata.response_types,+ {+ allowAdditional: true,+ allowOmitted: true,+ },+ );+ if (+ record.token_endpoint_auth_method !== undefined &&+ record.token_endpoint_auth_method !==+ requestedMetadata.token_endpoint_auth_method+ ) {+ throw invalidOAuthDcrResponse(+ "token_endpoint_auth_method",+ "registered_value_mismatch",+ );+ }+ const clientIdIssuedAt = parseOAuthDcrTimestamp(+ record,+ "client_id_issued_at",+ );+ const returnedClientSecretExpiresAt = parseOAuthDcrTimestamp(+ record,+ "client_secret_expires_at",+ );+ // A few public-client registrars (including Mixpanel) return the RFC 7591+ // `0` sentinel even though they issued no secret. It carries no credential+ // lifetime in that case, so normalize it away. A positive expiry without a+ // secret is still contradictory and remains a hard failure.+ if (+ returnedClientSecretExpiresAt !== null &&+ returnedClientSecretExpiresAt > 0 &&+ clientSecret === null+ ) {+ throw invalidOAuthDcrResponse(+ "client_secret_expires_at",+ "client_secret_missing",+ );+ }+ const clientSecretExpiresAt = clientSecret+ ? returnedClientSecretExpiresAt+ : null;+ return { clientId, clientSecret, tokenEndpointAuthMethod, clientIdIssuedAt, clientSecretExpiresAt };+ }++ async function exchangeOAuthToken(input: {+ tokenUrl: string;+ clientId: string;+ clientSecret?: string | null;+ tokenEndpointAuthMethod?: OAuthTokenEndpointAuthMethod;+ grantType?: "authorization_code" | "refresh_token" | "client_credentials";+ scopes?: string[];+ redirectUri?: string | null;+ codeVerifier?: string | null;+ code?: string | null;+ refreshToken?: string | null;+ /** RFC 8707 resource indicator: the MCP server this token is for. */+ resource?: string | null;+ }) {+ const body = new URLSearchParams();+ if (input.grantType === "client_credentials") {+ body.set("grant_type", "client_credentials");+ if (input.scopes && input.scopes.length > 0)+ body.set("scope", input.scopes.join(" "));+ } else if (input.refreshToken) {+ body.set("grant_type", "refresh_token");+ body.set("refresh_token", input.refreshToken);+ } else {+ body.set("grant_type", "authorization_code");+ body.set("code", input.code ?? "");+ 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")+ body.set("client_id", input.clientId);+ if (tokenEndpointAuthMethod === "client_secret_post") {+ if (!input.clientSecret) {+ throw unprocessable(+ "OAuth client secret is missing for client_secret_post authentication",+ {+ code: "oauth_client_secret_missing",+ },+ );+ }+ body.set("client_secret", input.clientSecret);+ }+ // RFC 8707: repeat the resource indicator on the token request so the+ // authorization server audience-restricts the access token (and any refresh+ // exchange) to this MCP server.+ if (input.resource) body.set("resource", input.resource);++ // The token URL can come from a connection row written before the endpoint+ // gate existed, so a client secret / authorization code never leaves+ // Paperclip without re-checking the transport it would leave over.+ const tokenUrl = assertOAuthEndpointUrl("token", input.tokenUrl, {+ // Paperclip's own callback origin, so a first-party token endpoint keeps+ // working on a deployment that is itself served over plaintext HTTP.+ firstPartyOrigin: originOf(input.redirectUri),+ });+ const headers: Record<string, string> = {+ "content-type": "application/x-www-form-urlencoded",+ // Some providers otherwise return a legacy form-encoded token response.+ accept: "application/json",+ };+ if (tokenEndpointAuthMethod === "client_secret_basic") {+ if (!input.clientSecret) {+ throw unprocessable(+ "OAuth client secret is missing for client_secret_basic authentication",+ {+ code: "oauth_client_secret_missing",+ },+ );+ }+ const formEncode = (value: string) =>+ new URLSearchParams({ value }).toString().slice("value=".length);+ headers.Authorization = `Basic ${Buffer.from(+ `${formEncode(input.clientId)}:${formEncode(input.clientSecret)}`,+ "utf8",+ ).toString("base64")}`;+ }+ const response = await fetchRemoteHttpUrl(tokenUrl, {+ method: "POST",+ headers,+ body,+ });+ const payload = (await response.json().catch(() => ({}))) as unknown;+ const record = asRecord(payload);+ if (!response.ok || record.ok === false) {+ const providerError = normalizeOAuthProviderError(record.error);+ const message = oauthProviderErrorMessage(+ providerError,+ "OAuth token exchange failed",+ );+ if (+ input.grantType === "refresh_token" &&+ providerError === "invalid_grant"+ ) {+ throw new HttpError(+ 422,+ "OAuth authorization has expired. Reconnect this app to continue.",+ {+ code: "oauth_reauthorization_required",+ providerError,+ status: response.status,+ },+ );+ }+ throw new HttpError(502, message, {+ code: "oauth_token_exchange_failed",+ providerError,+ status: response.status,+ });+ }+ const accessToken =+ typeof record.access_token === "string" ? record.access_token : null;+ if (!accessToken)+ throw new HttpError(+ 502,+ "OAuth provider did not return an access token",+ { code: "oauth_access_token_missing" },+ );+ const expiresIn =+ typeof record.expires_in === "number"+ ? record.expires_in+ : Number(record.expires_in);+ return {+ accessToken,+ refreshToken:+ typeof record.refresh_token === "string" ? record.refresh_token : null,+ expiresIn: Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : null,+ scope: typeof record.scope === "string" ? record.scope : null,+ tokenType:+ typeof record.token_type === "string" ? record.token_type : "Bearer",+ };+ }++ return { requestOAuthClientRegistration, exchangeOAuthToken };+}diff --git a/server/src/services/tool-access/oauth/discovery.ts b/server/src/services/tool-access/oauth/discovery.tsnew file mode 100644index 0000000000..a9847979ed--- /dev/null+++ b/server/src/services/tool-access/oauth/discovery.ts@@ -0,0 +1,582 @@+import { getConnectableAppDefinition, type AppDefinition, type ConnectionMethodDef, type ToolAppMetadataPreflightResult } from "@paperclipai/shared";+import { HttpError, unprocessable } from "../../../errors.js";+import { connectionMethodFor, connectionMethodForConnection, remoteEndpoint } from "../connection-methods.js";+import type { OAuthConnectionSettings, OAuthProviderEndpoints, OAuthTransport } from "./types.js";+import type { createOAuthEndpointPolicy } from "./endpoint-policy.js";+import { asRecord, oauthConfig, normalizeOauthScopes, isSmokeLabOAuthFixture, isSmokeLabOAuthUrl, originOf, oauthProviderForConnection, challengeOAuthHints, canonicalResourceIndicator, sameOAuthIssuer, protectedResourceMetadataUrls, wellKnownMetadataUrls, authServerMetadataUrls } from "./metadata.js";++type DiscoveryDependencies = OAuthTransport & Pick<ReturnType<typeof createOAuthEndpointPolicy>, "safeOAuthEndpointUrl"> & {+ assertRemoteEndpointAllowed: (config: Record<string, unknown>) => Promise<string>;+};++export function createOAuthDiscovery({ fetchRemoteHttpUrl, assertRemoteEndpointAllowed, assertOAuthEndpointUrl, safeOAuthEndpointUrl }: DiscoveryDependencies) {+ function smokeLabOAuthEndpoints(+ connection: OAuthConnectionSettings,+ redirectUri?: string,+ ): OAuthProviderEndpoints | null {+ if (!isSmokeLabOAuthFixture(connection) || !redirectUri) return null;+ let origin: string;+ try {+ origin = new URL(redirectUri).origin;+ } catch {+ return null;+ }+ const oauthBasePath = `/api/companies/${encodeURIComponent(connection.companyId)}/smoke-lab/oauth`;+ return {+ provider: "smoke_lab",+ scopes: normalizeOauthScopes(oauthConfig(connection).scopes),+ authorizationUrl: new URL(+ `${oauthBasePath}/authorize`,+ origin,+ ).toString(),+ tokenUrl: new URL(`${oauthBasePath}/token`, origin).toString(),+ metadataUrl: null,+ grantType: "authorization_code",+ };+ }++ function assertNotSmokeLabOAuthEndpoints(+ connection: OAuthConnectionSettings,+ endpoints: OAuthProviderEndpoints,+ ) {+ const blockedUrl = [+ endpoints.authorizationUrl,+ endpoints.tokenUrl,+ endpoints.metadataUrl,+ ].find(isSmokeLabOAuthUrl);+ if (blockedUrl && !isSmokeLabOAuthFixture(connection)) {+ throw unprocessable(+ "Smoke Lab OAuth provider cannot be used for tool app sign-in",+ );+ }+ }++ async function fetchJsonRecord(+ url: string,+ ): Promise<Record<string, unknown> | null> {+ try {+ const response = await fetchRemoteHttpUrl(url);+ if (!response.ok) return null;+ return asRecord((await response.json()) as unknown) ?? null;+ } catch {+ return null;+ }+ }++ async function endpointsFromMetadataUrl(+ connection: OAuthConnectionSettings,+ metadataUrl: string,+ rejections: HttpError[] = [],+ firstPartyOrigin?: string | null,+ ): Promise<OAuthProviderEndpoints | null> {+ const metadata = await fetchJsonRecord(metadataUrl);+ if (!metadata) return null;+ // Every endpoint below is a string the remote server chose, so none of them+ // is adopted before `safeOAuthEndpointUrl` has vetted its scheme and host.+ let authorizationUrl = safeOAuthEndpointUrl(+ "authorization",+ metadata.authorization_endpoint,+ rejections,+ firstPartyOrigin,+ );+ let tokenUrl = safeOAuthEndpointUrl(+ "token",+ metadata.token_endpoint,+ rejections,+ firstPartyOrigin,+ );+ let registrationUrl = safeOAuthEndpointUrl(+ "registration",+ metadata.registration_endpoint,+ rejections,+ firstPartyOrigin,+ );+ let scopes = normalizeOauthScopes(metadata.scopes_supported);+ let offlineAccessSupported = Boolean(+ authorizationUrl && scopes.includes("offline_access"),+ );+ let codeChallengeMethodsSupported = normalizeOauthScopes(+ metadata.code_challenge_methods_supported,+ );+ let tokenEndpointAuthMethodsSupported = normalizeOauthScopes(+ metadata.token_endpoint_auth_methods_supported,+ );+ let grantTypesSupported = normalizeOauthScopes(+ metadata.grant_types_supported,+ );+ let clientIdMetadataDocumentSupported =+ metadata.client_id_metadata_document_supported === true;+ // A document that carries the authorization endpoint itself *is* the+ // authorization-server metadata, so its own `issuer` is the canonical one.+ // Otherwise this was protected-resource metadata and the issuer comes from+ // whichever advertised authorization server answered.+ let issuer =+ authorizationUrl &&+ typeof metadata.issuer === "string" &&+ metadata.issuer.trim()+ ? metadata.issuer.trim()+ : null;+ const resource =+ typeof metadata.resource === "string" && metadata.resource.trim()+ ? metadata.resource.trim()+ : null;+ for (const candidate of authServerMetadataUrls(metadata)) {+ const authMetadata = await fetchJsonRecord(candidate.metadataUrl);+ if (!authMetadata) continue;+ const candidateAuthorizationUrl = safeOAuthEndpointUrl(+ "authorization",+ authMetadata.authorization_endpoint,+ rejections,+ firstPartyOrigin,+ );+ const candidateTokenUrl = safeOAuthEndpointUrl(+ "token",+ authMetadata.token_endpoint,+ rejections,+ firstPartyOrigin,+ );+ if (!candidateAuthorizationUrl && !candidateTokenUrl) continue;+ // RFC 8414 §3.3: the metadata document's `issuer` must match the issuer we+ // used to build the discovery URL, or the document is not authoritative.+ const advertisedIssuer =+ typeof authMetadata.issuer === "string" && authMetadata.issuer.trim()+ ? authMetadata.issuer.trim()+ : null;+ if (+ advertisedIssuer &&+ !sameOAuthIssuer(advertisedIssuer, candidate.issuer)+ )+ continue;+ // A document can carry its own endpoints and also list other servers.+ // Adopt capabilities only from metadata bound to the selected endpoints+ // and issuer; otherwise offline access could break an unrelated sign-in.+ if (+ (authorizationUrl && candidateAuthorizationUrl !== authorizationUrl) ||+ (tokenUrl && candidateTokenUrl !== tokenUrl) ||+ (issuer && !sameOAuthIssuer(issuer, advertisedIssuer ?? candidate.issuer))+ )+ continue;+ authorizationUrl = authorizationUrl ?? candidateAuthorizationUrl;+ tokenUrl = tokenUrl ?? candidateTokenUrl;+ registrationUrl =+ registrationUrl ??+ safeOAuthEndpointUrl(+ "registration",+ authMetadata.registration_endpoint,+ rejections,+ firstPartyOrigin,+ );+ issuer = issuer ?? advertisedIssuer ?? candidate.issuer;+ offlineAccessSupported = offlineAccessSupported ||+ normalizeOauthScopes(authMetadata.scopes_supported).includes("offline_access");+ if (scopes.length === 0)+ scopes = normalizeOauthScopes(authMetadata.scopes_supported);+ if (codeChallengeMethodsSupported.length === 0) {+ codeChallengeMethodsSupported = normalizeOauthScopes(+ authMetadata.code_challenge_methods_supported,+ );+ }+ if (tokenEndpointAuthMethodsSupported.length === 0) {+ tokenEndpointAuthMethodsSupported = normalizeOauthScopes(+ authMetadata.token_endpoint_auth_methods_supported,+ );+ }+ if (grantTypesSupported.length === 0) {+ grantTypesSupported = normalizeOauthScopes(+ authMetadata.grant_types_supported,+ );+ }+ if (!clientIdMetadataDocumentSupported) {+ clientIdMetadataDocumentSupported =+ authMetadata.client_id_metadata_document_supported === true;+ }+ if (authorizationUrl && tokenUrl) break;+ }+ if (!authorizationUrl || !tokenUrl) return null;+ return {+ provider: oauthProviderForConnection(connection, metadataUrl),+ scopes,+ offlineAccessSupported,+ authorizationUrl,+ tokenUrl,+ registrationUrl,+ codeChallengeMethodsSupported,+ tokenEndpointAuthMethodsSupported,+ grantTypesSupported,+ metadataUrl,+ issuer,+ resource,+ clientIdMetadataDocumentSupported,+ };+ }++ async function discoverOAuthEndpoints(+ connection: OAuthConnectionSettings,+ challenge?: string | null,+ firstPartyOrigin?: string | null,+ ): Promise<OAuthProviderEndpoints | null> {+ const oauth = oauthConfig(connection);+ const hints = challenge ? challengeOAuthHints(challenge) : null;+ // A configured endpoint was pasted by an operator or persisted from an+ // earlier discovery, and a hint came straight out of the endpoint's+ // `WWW-Authenticate` header. Neither is more trusted than metadata, so both+ // go through the same gate; an unusable one is dropped so full metadata+ // discovery still runs below.+ const rejections: HttpError[] = [];+ const configuredAuthorizationUrl = safeOAuthEndpointUrl(+ "authorization",+ typeof oauth.authorizationUrl === "string"+ ? oauth.authorizationUrl+ : (hints?.authorizationUrl ?? null),+ rejections,+ firstPartyOrigin,+ );+ const configuredTokenUrl = safeOAuthEndpointUrl(+ "token",+ typeof oauth.tokenUrl === "string"+ ? oauth.tokenUrl+ : (hints?.tokenUrl ?? null),+ rejections,+ firstPartyOrigin,+ );+ const provider = oauthProviderForConnection(+ connection,+ typeof oauth.metadataUrl === "string"+ ? oauth.metadataUrl+ : hints?.metadataUrl,+ );+ const scopes =+ normalizeOauthScopes(oauth.scopes).length > 0+ ? normalizeOauthScopes(oauth.scopes)+ : normalizeOauthScopes(oauth.scope).length > 0+ ? normalizeOauthScopes(oauth.scope)+ : normalizeOauthScopes(hints?.scope);+ const grantType =+ oauth.grantType === "client_credentials" ||+ oauth.clientCredentials === true+ ? ("client_credentials" as const)+ : ("authorization_code" as const);+ // The resource indicator is the MCP endpoint itself, independent of which+ // authorization server ends up serving it.+ const configuredResource =+ typeof oauth.resource === "string" && oauth.resource.trim()+ ? oauth.resource.trim()+ : canonicalResourceIndicator(remoteEndpoint(connection.config));+ if (configuredAuthorizationUrl && configuredTokenUrl) {+ // Pre-existing generic connections cached endpoints before refresh-scope+ // support was recorded. Recover that capability from their bound metadata+ // without adopting a different issuer or changing their requested tool scopes.+ let refreshMetadata: OAuthProviderEndpoints | null = null;+ if (+ !connection.config.sourceTemplateKey &&+ typeof oauth.offlineAccessSupported !== "boolean" &&+ typeof oauth.metadataUrl === "string"+ ) {+ const discovered = await endpointsFromMetadataUrl(+ connection, oauth.metadataUrl, rejections, firstPartyOrigin,+ );+ if (+ discovered?.authorizationUrl === configuredAuthorizationUrl &&+ discovered.tokenUrl === configuredTokenUrl &&+ (typeof oauth.issuer !== "string" ||+ (discovered.issuer && sameOAuthIssuer(discovered.issuer, oauth.issuer)))+ ) refreshMetadata = discovered;+ }+ return {+ provider,+ scopes,+ offlineAccessSupported: typeof oauth.offlineAccessSupported === "boolean"+ ? oauth.offlineAccessSupported+ : refreshMetadata?.offlineAccessSupported,+ authorizationUrl: configuredAuthorizationUrl,+ tokenUrl: configuredTokenUrl,+ registrationUrl: safeOAuthEndpointUrl(+ "registration",+ oauth.registrationUrl,+ rejections,+ firstPartyOrigin,+ ),+ codeChallengeMethodsSupported: normalizeOauthScopes(+ oauth.codeChallengeMethodsSupported,+ ),+ tokenEndpointAuthMethodsSupported: normalizeOauthScopes(+ oauth.tokenEndpointAuthMethodsSupported,+ ),+ grantTypesSupported: Array.isArray(oauth.grantTypesSupported)+ ? normalizeOauthScopes(oauth.grantTypesSupported)+ : refreshMetadata?.grantTypesSupported,+ grantType,+ metadataUrl:+ typeof oauth.metadataUrl === "string"+ ? oauth.metadataUrl+ : (hints?.metadataUrl ?? null),+ issuer:+ typeof oauth.issuer === "string" && oauth.issuer.trim()+ ? oauth.issuer.trim()+ : null,+ resource: configuredResource,+ clientIdMetadataDocumentSupported:+ oauth.clientIdMetadataDocumentSupported === true,+ };+ }++ const metadataCandidates = [+ typeof oauth.metadataUrl === "string" ? oauth.metadataUrl : null,+ hints?.metadataUrl ?? null,+ ].filter((value): value is string => Boolean(value));+ if (metadataCandidates.length === 0) {+ const endpoint = new URL(+ await assertRemoteEndpointAllowed(connection.config),+ );+ metadataCandidates.push(...protectedResourceMetadataUrls(endpoint));+ // The MCP server may double as its own authorization server, in which case+ // it serves authorization-server metadata directly at (or under) its path.+ metadataCandidates.push(...wellKnownMetadataUrls(endpoint.toString()));+ }+ for (const metadataUrl of [...new Set(metadataCandidates)]) {+ const endpoints = await endpointsFromMetadataUrl(+ connection,+ metadataUrl,+ rejections,+ firstPartyOrigin,+ );+ if (endpoints) {+ return {+ ...endpoints,+ scopes: scopes.length > 0 ? scopes : endpoints.scopes,+ grantType,+ resource: endpoints.resource ?? configuredResource,+ };+ }+ }+ // Nothing usable was found *and* something was refused on the way: report the+ // refusal rather than the generic "does not advertise OAuth sign in", so the+ // operator learns the server offered an unsafe address.+ if (rejections.length > 0) throw rejections[0];+ return null;+ }++ async function oauthProviderEndpoints(+ app: AppDefinition,+ methodKey?: string | null,+ ): Promise<OAuthProviderEndpoints> {+ const method = connectionMethodFor(app, methodKey);+ if (method.auth !== "oauth")+ throw unprocessable("This app does not support sign in");+ let authorizationUrl = method.defaults?.authorizationEndpoint ?? null;+ let tokenUrl = method.defaults?.tokenEndpoint ?? null;+ const metadataUrl = method.defaults?.metadataUrl ?? null;+ if ((!authorizationUrl || !tokenUrl) && metadataUrl) {+ const response = await fetchRemoteHttpUrl(metadataUrl);+ if (!response.ok)+ throw new HttpError(+ 502,+ "OAuth provider metadata could not be loaded",+ { code: "oauth_metadata_failed" },+ );+ const metadata = asRecord((await response.json()) as unknown);+ authorizationUrl =+ authorizationUrl ??+ (typeof metadata.authorization_endpoint === "string"+ ? metadata.authorization_endpoint+ : null);+ tokenUrl =+ tokenUrl ??+ (typeof metadata.token_endpoint === "string"+ ? metadata.token_endpoint+ : null);+ }+ if (!authorizationUrl || !tokenUrl) {+ throw unprocessable(+ "OAuth provider endpoints are not configured for this app",+ );+ }+ // A gallery default is Paperclip's own data, but it is still a URL that ends+ // up as a browser navigation, and the metadata branch above reads the same+ // untrusted document a generic connection does. Both go through the gate.+ return {+ provider: app.slug,+ scopes: method.defaults?.scopesHint ?? [],+ authorizationUrl: assertOAuthEndpointUrl(+ "authorization",+ authorizationUrl,+ ),+ tokenUrl: assertOAuthEndpointUrl("token", tokenUrl),+ grantType: "authorization_code",+ metadataUrl,+ };+ }++ async function oauthEndpointsForConnection(+ connection: OAuthConnectionSettings,+ challenge?: string | null,+ redirectUri?: string,+ ): Promise<OAuthProviderEndpoints> {+ const smokeLabEndpoints = smokeLabOAuthEndpoints(connection, redirectUri);+ const sourceTemplateKey =+ typeof connection.config.sourceTemplateKey === "string"+ ? connection.config.sourceTemplateKey+ : null;+ const galleryEntry = sourceTemplateKey+ ? getConnectableAppDefinition(sourceTemplateKey)+ : null;+ const galleryMethod = galleryEntry+ ? connectionMethodForConnection(galleryEntry, connection)+ : null;+ // Pinned endpoints describe the provider's console-registered OAuth app.+ // A method that also offers dynamic registration registers against the MCP+ // server's own authorization server (Linear: mcp.linear.app, not+ // linear.app), which only discovery finds. So the pins stand in for+ // discovery only when no registration is possible or the connection+ // already carries an operator-entered client.+ const storedOAuth = oauthConfig(connection);+ const usesOperatorClient =+ storedOAuth.clientRegistrationSource === "manual" &&+ connection.ownership !== "dcr" &&+ typeof storedOAuth.clientId === "string" &&+ storedOAuth.clientId.trim().length > 0;+ // A reviewed protected-resource document is authoritative for this method.+ // Some hosts still serve metadata for a retired MCP server at the root.+ // Resolve it before cached endpoints, including on existing draft reconnects.+ if (!smokeLabEndpoints && galleryMethod?.defaults?.discoveryUrl) {+ const endpoints = await endpointsFromMetadataUrl(+ connection, galleryMethod.defaults.discoveryUrl, [], originOf(redirectUri),+ );+ if (!endpoints) throw unprocessable("OAuth provider metadata could not be loaded");+ assertNotSmokeLabOAuthEndpoints(connection, endpoints);+ return endpoints;+ }+ const hasCompleteGalleryEndpointHints = Boolean(+ galleryMethod?.defaults?.authorizationEndpoint &&+ galleryMethod.defaults.tokenEndpoint &&+ (!galleryMethod.ownershipModes.includes("dcr") || usesOperatorClient),+ );+ // The smoke-lab fixture's endpoints are first-party and complete, so+ // discovery is not just unnecessary there, it must not run: an unreachable+ // fixture endpoint would fail the whole callback.+ const firstPartyOrigin = originOf(redirectUri);+ const discovered =+ !smokeLabEndpoints &&+ connection.transport === "mcp_remote" &&+ !hasCompleteGalleryEndpointHints+ ? await discoverOAuthEndpoints(connection, challenge, firstPartyOrigin)+ : null;+ const endpoints =+ smokeLabEndpoints ??+ discovered ??+ (galleryEntry && galleryMethod?.auth === "oauth"+ ? await oauthProviderEndpoints(galleryEntry, galleryMethod.key)+ : await discoverOAuthEndpoints(+ connection,+ challenge,+ firstPartyOrigin,+ ));+ if (!endpoints)+ throw unprocessable(+ "This app connection does not advertise OAuth sign in",+ );+ assertNotSmokeLabOAuthEndpoints(connection, endpoints);+ return endpoints;+ }++ async function preflightConnectionMetadata(+ app: Pick<AppDefinition, "slug">,+ method: Pick<ConnectionMethodDef, "auth" | "key">,+ defaults: NonNullable<ConnectionMethodDef["defaults"]>,+ serverUrl: string,+ now: () => Date,+ ): Promise<ToolAppMetadataPreflightResult> {+ const attempts: ToolAppMetadataPreflightResult["attempts"] = [];+ const endpointResponse = await fetchRemoteHttpUrl(serverUrl, {+ method: "GET",+ headers: { Accept: "application/json, text/event-stream" },+ });+ attempts.push({+ kind: "endpoint",+ url: serverUrl,+ status: endpointResponse.status,+ ok: endpointResponse.ok,+ contentType: endpointResponse.headers.get("content-type"),+ });++ if (method.auth !== "oauth") {+ return {+ galleryKey: app.slug,+ methodKey: method.key,+ serverUrl,+ endpointReachable: endpointResponse.status < 500,+ oauth: null,+ attempts,+ checkedAt: now().toISOString(),+ };+ }++ const endpoint = new URL(serverUrl);+ const metadataQueue = [+ defaults.discoveryUrl ?? null,+ defaults.metadataUrl ?? null,+ ...protectedResourceMetadataUrls(endpoint),+ ...wellKnownMetadataUrls(endpoint.toString()),+ ].filter((url): url is string => Boolean(url));+ const visited = new Set<string>();+ let metadataFound = false;+ let registrationAdvertised = false;+ let clientIdMetadataDocumentSupported = false;++ while (metadataQueue.length > 0 && visited.size < 16) {+ const metadataUrl = metadataQueue.shift()!;+ if (visited.has(metadataUrl)) continue;+ visited.add(metadataUrl);+ const response = await fetchRemoteHttpUrl(metadataUrl, {+ method: "GET",+ headers: { Accept: "application/json" },+ });+ attempts.push({+ kind: "oauth_metadata",+ url: metadataUrl,+ status: response.status,+ ok: response.ok,+ contentType: response.headers.get("content-type"),+ });+ if (!response.ok) continue;+ let metadata: Record<string, unknown>;+ try {+ metadata = asRecord((await response.json()) as unknown);+ } catch {+ continue;+ }+ const looksLikeOAuthMetadata = Boolean(+ metadata.authorization_endpoint ||+ metadata.token_endpoint ||+ metadata.authorization_servers ||+ metadata.resource,+ );+ if (!looksLikeOAuthMetadata) continue;+ metadataFound = true;+ registrationAdvertised ||=+ typeof metadata.registration_endpoint === "string";+ clientIdMetadataDocumentSupported ||=+ metadata.client_id_metadata_document_supported === true;+ for (const candidate of authServerMetadataUrls(metadata)) {+ if (!visited.has(candidate.metadataUrl))+ metadataQueue.push(candidate.metadataUrl);+ }+ }++ return {+ galleryKey: app.slug,+ methodKey: method.key,+ serverUrl,+ endpointReachable: endpointResponse.status < 500,+ oauth: {+ metadataFound,+ registrationAdvertised,+ clientIdMetadataDocumentSupported,+ },+ attempts,+ checkedAt: now().toISOString(),+ };+ }++ return { oauthEndpointsForConnection, discoverOAuthEndpoints, preflightConnectionMetadata };+}diff --git a/server/src/services/tool-access/oauth/endpoint-policy.ts b/server/src/services/tool-access/oauth/endpoint-policy.tsnew file mode 100644index 0000000000..95fb52099c--- /dev/null+++ b/server/src/services/tool-access/oauth/endpoint-policy.ts@@ -0,0 +1,111 @@+import { checkOAuthEndpointUrl, oauthEndpointUrlRejectionMessage, type OAuthEndpointKind, type OAuthEndpointUrlRejection } from "@paperclipai/shared";+import { HttpError } from "../../../errors.js";+import { originOf, isSmokeLabOAuthUrl } from "./metadata.js";++export function createOAuthEndpointPolicy(allowPrivateRemoteEndpoints: () => boolean) {+ /**+ * OAuth endpoint scheme/transport gate (PAP-17099).+ *+ * Every OAuth endpoint Paperclip acts on is attacker-influenced: discovered+ * metadata, a `WWW-Authenticate` hint, a pasted config, or a gallery default.+ * The authorization endpoint is the sharpest one because it is handed to the+ * operator's browser as a top-level navigation, so `javascript:`/`data:` there+ * would run in the board's origin. `checkOAuthEndpointUrl` is the single place+ * that decides; loopback `http:` is accepted only under the same+ * local-development policy that governs private remote endpoints, and+ * Paperclip's own origin is exempt from the transport rule because a+ * first-party endpoint (the smoke-lab fixture) is served exactly as the board+ * itself is.+ */+ function oauthEndpointRejected(+ kind: OAuthEndpointKind,+ reason: OAuthEndpointUrlRejection,+ ): HttpError {+ return new HttpError(422, oauthEndpointUrlRejectionMessage(kind, reason), {+ code: `oauth_${kind}_endpoint_rejected`,+ reason,+ });+ }++ /**+ * Origins that are Paperclip itself: this deployment's configured public URL,+ * plus the callback origin of the request in hand when there is one. Only the+ * plaintext-transport rule is relaxed for these.+ */+ function firstPartyOrigins(candidate?: string | null): string[] {+ const configured =+ process.env.PAPERCLIP_PUBLIC_URL?.trim() ||+ process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL?.trim() ||+ process.env.BETTER_AUTH_URL?.trim() ||+ process.env.BETTER_AUTH_BASE_URL?.trim() ||+ null;+ return [originOf(candidate), originOf(configured)].filter(+ (origin): origin is string => Boolean(origin),+ );+ }++ /**+ * Origins for which the plaintext-transport rule is relaxed when checking+ * `value`. Adds the smoke-lab fixture's own origin, because that provider is+ * mounted on this deployment's own routes — `assertNotSmokeLabOAuthEndpoints`+ * is what stops any other connection from claiming those paths — and a smoke+ * run may be driven against a deployment served over plaintext HTTP.+ */+ function insecureTransportExemptions(+ value: unknown,+ candidate?: string | null,+ ): string[] {+ const origins = firstPartyOrigins(candidate);+ if (typeof value === "string" && isSmokeLabOAuthUrl(value)) {+ const origin = originOf(value);+ if (origin) origins.push(origin);+ }+ return origins;+ }++ /** Throws unless `value` is an endpoint Paperclip may use (and navigate to). */+ function assertOAuthEndpointUrl(+ kind: OAuthEndpointKind,+ value: unknown,+ options: { firstPartyOrigin?: string | null } = {},+ ): string {+ const check = checkOAuthEndpointUrl(value, {+ allowInsecureLoopback: allowPrivateRemoteEndpoints(),+ allowInsecureOrigins: insecureTransportExemptions(+ value,+ options.firstPartyOrigin,+ ),+ });+ if (!check.ok) throw oauthEndpointRejected(kind, check.reason);+ return check.url;+ }++ /**+ * Discovery variant: an unusable endpoint is dropped rather than thrown, so a+ * second advertised authorization server (or a later metadata candidate) still+ * gets a chance. Rejections are recorded in `rejections`; discovery raises the+ * first one only if it ends up with nothing safe to use, so the operator sees+ * *why* instead of a bare "does not advertise OAuth sign in".+ */+ function safeOAuthEndpointUrl(+ kind: OAuthEndpointKind,+ value: unknown,+ rejections: HttpError[],+ firstPartyOrigin?: string | null,+ ): string | null {+ if (value === null || value === undefined || value === "") return null;+ const check = checkOAuthEndpointUrl(value, {+ allowInsecureLoopback: allowPrivateRemoteEndpoints(),+ allowInsecureOrigins: insecureTransportExemptions(+ value,+ firstPartyOrigin,+ ),+ });+ if (check.ok) return check.url;+ if (check.reason !== "missing")+ rejections.push(oauthEndpointRejected(kind, check.reason));+ return null;+ }++ return { assertOAuthEndpointUrl, safeOAuthEndpointUrl };+}diff --git a/server/src/services/tool-access/oauth/metadata.ts b/server/src/services/tool-access/oauth/metadata.tsnew file mode 100644index 0000000000..c112f78eca--- /dev/null+++ b/server/src/services/tool-access/oauth/metadata.ts@@ -0,0 +1,311 @@+import type { OAuthConnectionSettings } from "./types.js";+import { remoteEndpoint } from "../connection-methods.js";++export function asRecord(value: unknown): Record<string, unknown> {+ if (value && typeof value === "object" && !Array.isArray(value))+ return value as Record<string, unknown>;+ return {};+}++/**+ * RFC 8414 §3.1 requires the well-known path to be *inserted between* the+ * issuer host and its path component, but a large amount of deployed software+ * only serves the naive suffix form. OpenID Connect Discovery 1.0 in turn+ * specifies the suffix form. Try all of them for an issuer that has a path, and+ * the plain origin form when it doesn't.+ */+export function wellKnownMetadataUrls(issuer: string): string[] {+ let parsed: URL;+ try {+ parsed = new URL(issuer);+ } catch {+ return [];+ }+ const suffixes = ["oauth-authorization-server", "openid-configuration"];+ const path = parsed.pathname.replace(/\/+$/, "");+ const urls: string[] = [];+ for (const suffix of suffixes) {+ if (path) {+ // RFC 8414: https://host/.well-known/<suffix><path>+ urls.push(+ new URL(`/.well-known/${suffix}${path}`, parsed.origin).toString(),+ );+ // OIDC Discovery / widely deployed: https://host<path>/.well-known/<suffix>+ urls.push(+ new URL(`${path}/.well-known/${suffix}`, parsed.origin).toString(),+ );+ }+ urls.push(new URL(`/.well-known/${suffix}`, parsed.origin).toString());+ }+ return [...new Set(urls)];+}++/**+ * Protected-resource metadata lives at `/.well-known/oauth-protected-resource`+ * with the resource's path appended (RFC 9728 §3.1). Probe the path-aware form+ * first so a multi-tenant host that serves several MCP servers resolves to the+ * right one, then fall back to the origin form.+ */+export function protectedResourceMetadataUrls(endpoint: URL): string[] {+ const path = endpoint.pathname.replace(/\/+$/, "");+ const urls: string[] = [];+ if (path)+ urls.push(+ new URL(+ `/.well-known/oauth-protected-resource${path}`,+ endpoint.origin,+ ).toString(),+ );+ urls.push(+ new URL(+ "/.well-known/oauth-protected-resource",+ endpoint.origin,+ ).toString(),+ );+ return [...new Set(urls)];+}++/**+ * Canonical RFC 8707 resource indicator for an MCP endpoint: origin + path, with+ * query, fragment and any trailing slash removed. Vendor query parameters belong+ * to the connection config, not to the token audience.+ */+export function canonicalResourceIndicator(endpoint: string): string | null {+ try {+ const parsed = new URL(endpoint);+ const path = parsed.pathname.replace(/\/+$/, "");+ return `${parsed.origin}${path}`;+ } catch {+ return null;+ }+}++/**+ * Two issuers are the same authorization server only when scheme, host, port and+ * path match exactly (a trailing slash is not significant). Used for `iss`+ * validation on the callback and for detecting that a stored registration is+ * bound to a different server than the one we just discovered.+ */+export function sameOAuthIssuer(+ a: string | null | undefined,+ b: string | null | undefined,+): boolean {+ if (!a || !b) return false;+ try {+ const left = new URL(a);+ const right = new URL(b);+ return (+ left.protocol === right.protocol &&+ left.host === right.host &&+ left.pathname.replace(/\/+$/, "") === right.pathname.replace(/\/+$/, "")+ );+ } catch {+ return false;+ }+}++export function originOf(value: string | null | undefined): string | null {+ if (!value) return null;+ try {+ return new URL(value).origin;+ } catch {+ return null;+ }+}++export function oauthConfig(connection: Pick<OAuthConnectionSettings, "config">) {+ const oauth = asRecord(connection.config).oauth+ ? asRecord(asRecord(connection.config).oauth)+ : {};+ const {+ access_token: _accessToken,+ refresh_token: _refreshToken,+ accessToken: _camelAccessToken,+ refreshToken: _camelRefreshToken,+ ...metadata+ } = oauth;+ return metadata;+}++export function normalizeOauthScopes(value: unknown): string[] {+ if (Array.isArray(value))+ return value.filter(+ (item): item is string =>+ typeof item === "string" && item.trim().length > 0,+ );+ if (typeof value === "string")+ return value+ .split(/\s+/)+ .map((item) => item.trim())+ .filter(Boolean);+ return [];+}++/**+ * Decide what a token grant actually carries, keeping the provider's assertion separate from+ * our own request.+ *+ * RFC 6749 §5.1 permits a provider to omit `scope` only when the grant is identical to the+ * request, so reading the request as the grant is the specified fallback. A provider that+ * over-grants *and* omits `scope` breaks that contract, and recording the request unmarked+ * turns what we asked for into a confident-looking record of what we got. `scopeSource` keeps+ * the two readable apart so nothing downstream can mistake an inference for an assertion.+ *+ * `unrequestedScopes` is only meaningful when we asked for something specific; with no+ * requested scopes there is no baseline to compare against, so it stays empty rather than+ * flagging every scope on connections that keep their scopes in provider-side app config.+ *+ * `previous` is the provenance already recorded for this grant. A refresh response that omits+ * `scope` asserts nothing at all — least of all that a permission was taken away — so the+ * earlier record is carried forward verbatim instead of being overwritten with a clean-looking+ * inference. Only a fresh provider assertion replaces a recorded over-grant.+ */+export function resolveGrantedOauthScopes(input: {+ tokenScope: unknown;+ requestedScopes: unknown;+ previous?: {+ scopes?: unknown;+ scopeSource?: unknown;+ unrequestedScopes?: unknown;+ };+}): {+ scopes: string[];+ scopeSource: "provider" | "requested_fallback";+ unrequestedScopes: string[];+} {+ const requested = normalizeOauthScopes(input.requestedScopes);+ const asserted =+ input.tokenScope === undefined || input.tokenScope === null+ ? []+ : normalizeOauthScopes(input.tokenScope);+ if (asserted.length === 0) {+ const previousScopes = normalizeOauthScopes(input.previous?.scopes);+ const previousUnrequested = normalizeOauthScopes(+ input.previous?.unrequestedScopes,+ );+ if (previousScopes.length > 0) {+ return {+ scopes: previousScopes,+ scopeSource:+ input.previous?.scopeSource === "provider"+ ? "provider"+ : "requested_fallback",+ unrequestedScopes: previousUnrequested,+ };+ }+ return {+ scopes: requested,+ scopeSource: "requested_fallback",+ unrequestedScopes: previousUnrequested,+ };+ }+ return {+ scopes: asserted,+ scopeSource: "provider",+ unrequestedScopes:+ requested.length === 0+ ? []+ : asserted.filter((scope) => !requested.includes(scope)),+ };+}++export function isSmokeLabOAuthFixture(+ connection: Pick<OAuthConnectionSettings, "config">,+) {+ const config = asRecord(connection.config);+ const oauth = oauthConfig(connection);+ return (+ config.smokeLabFixture === "oauth-http" && oauth.smokeLabFixture === true+ );+}++export function isSmokeLabOAuthUrl(value: string | null | undefined) {+ if (!value) return false;+ try {+ return /\/smoke-lab\/oauth(?:\/|$)/.test(new URL(value).pathname);+ } catch {+ return false;+ }+}++export function oauthProviderForConnection(+ connection: Pick<OAuthConnectionSettings, "config">,+ metadataUrl?: string | null,+): string {+ const oauth = oauthConfig(connection);+ if (typeof oauth.provider === "string" && oauth.provider.trim())+ return oauth.provider.trim();+ const sourceTemplateKey =+ typeof connection.config.sourceTemplateKey === "string"+ ? connection.config.sourceTemplateKey.trim()+ : "";+ if (sourceTemplateKey) return sourceTemplateKey;+ const url = metadataUrl ?? remoteEndpoint(connection.config);+ try {+ return (+ new URL(url).hostname+ .replace(/[^a-z0-9]+/gi, "_")+ .replace(/^_+|_+$/g, "")+ .toLowerCase() || "generic"+ );+ } catch {+ return "generic";+ }+}++export function parseWwwAuthenticateParams(value: string): Record<string, string> {+ const params: Record<string, string> = {};+ const input = value.replace(/^\s*Bearer\s+/i, "");+ const re = /([a-zA-Z_][a-zA-Z0-9_-]*)=(?:"([^"]*)"|([^,\s]+))/g;+ let match: RegExpExecArray | null;+ while ((match = re.exec(input))) {+ params[match[1]!.toLowerCase()] = match[2] ?? match[3] ?? "";+ }+ return params;+}++export function challengeOAuthHints(wwwAuthenticate: string) {+ const params = parseWwwAuthenticateParams(wwwAuthenticate);+ return {+ metadataUrl:+ params.resource_metadata ??+ params.resource_metadata_url ??+ params.metadata_url ??+ null,+ authorizationUrl:+ params.authorization_uri ?? params.authorization_url ?? null,+ tokenUrl: params.token_uri ?? params.token_url ?? null,+ scope: params.scope ?? null,+ };+}++/**+ * Candidate authorization-server metadata URLs advertised by protected-resource+ * metadata, paired with the issuer that advertised them so the caller can bind+ * the resulting client material to a canonical issuer.+ */+export function authServerMetadataUrls(+ metadata: Record<string, unknown>,+): Array<{ issuer: string; metadataUrl: string }> {+ const candidates: Array<{ issuer: string; metadataUrl: string }> = [];+ const issuers: string[] = [];+ if (Array.isArray(metadata.authorization_servers)) {+ for (const server of metadata.authorization_servers) {+ if (typeof server === "string" && server.trim())+ issuers.push(server.trim());+ }+ }+ if (typeof metadata.issuer === "string" && metadata.issuer.trim())+ issuers.push(metadata.issuer.trim());+ for (const issuer of [...new Set(issuers)]) {+ for (const metadataUrl of wellKnownMetadataUrls(issuer)) {+ candidates.push({ issuer, metadataUrl });+ }+ }+ const seen = new Set<string>();+ return candidates.filter((candidate) => {+ if (seen.has(candidate.metadataUrl)) return false;+ seen.add(candidate.metadataUrl);+ return true;+ });+}diff --git a/server/src/services/tool-access/oauth/provider-errors.ts b/server/src/services/tool-access/oauth/provider-errors.tsnew file mode 100644index 0000000000..fdeb822059--- /dev/null+++ b/server/src/services/tool-access/oauth/provider-errors.ts@@ -0,0 +1,126 @@+++/**+ * Upstream OAuth error redaction (PAP-17108).+ *+ * A generic remote MCP connection points at an arbitrary authorization server,+ * so everything that server says about a failure is attacker-chosen: `error`,+ * `error_description`, `error_uri`, and the response body. Paperclip surfaces+ * connection failures to the operator through API responses, board UI copy,+ * audit rows and logs, so reflecting any of that text would let a hostile+ * provider plant secrets, ANSI escapes, or instructions ("paste your recovery+ * key here") into Paperclip's own voice.+ *+ * The rule is therefore: the operator only ever reads text Paperclip authored.+ * The provider's `error` code survives — as a *label* in structured `details`,+ * never in a message — and only when it is one of the codes the RFCs define,+ * because a label is still untrusted input. Everything else is dropped, and an+ * unrecognized code collapses to `unrecognized` rather than being echoed.+ *+ * `error_description` and the response body are never read at all: no call site+ * below parses them, which is what keeps a future edit from quietly+ * reintroducing the reflection.+ */+const OAUTH_PROVIDER_ERROR_CODES = new Set([+ // RFC 6749 §4.1.2.1 — authorization endpoint (the callback-denial path).+ "access_denied",+ "invalid_request",+ "invalid_scope",+ "server_error",+ "temporarily_unavailable",+ "unauthorized_client",+ "unsupported_response_type",+ // RFC 6749 §5.2 — token endpoint (authorization-code and refresh exchanges).+ "invalid_client",+ "invalid_grant",+ "unsupported_grant_type",+ // RFC 7591 §3.2.2 — dynamic client registration.+ "invalid_client_metadata",+ "invalid_redirect_uri",+ "invalid_software_statement",+ "unapproved_software_statement",+ // OpenID Connect Core §3.1.2.6 — interactive re-authentication prompts.+ "account_selection_required",+ "consent_required",+ "interaction_required",+ "login_required",+]);++/** What an `error` that is absent, malformed, or off the allowlist becomes. */+const UNRECOGNIZED_OAUTH_PROVIDER_ERROR = "unrecognized";++const MAX_OAUTH_PROVIDER_ERROR_LENGTH = 64;++const OAUTH_PROVIDER_ERROR_PATTERN = /^[a-z0-9_-]+$/;++/**+ * Stable, Paperclip-authored operator copy for each allowlisted provider error.+ * Deliberately keyed on the code alone: the calling context is already carried+ * by the Paperclip `code` in `details`, so one table serves the callback,+ * token-exchange and registration paths without any of them composing a message+ * out of provider text.+ */+const OAUTH_PROVIDER_ERROR_MESSAGES: Record<string, string> = {+ access_denied: "The authorization server denied the request.",+ account_selection_required:+ "The authorization server needs an account to be selected. Try connecting again.",+ consent_required:+ "The authorization server needs consent to be granted. Try connecting again.",+ interaction_required:+ "The authorization server needs to be signed in to interactively. Try connecting again.",+ invalid_client: "The authorization server rejected Paperclip's OAuth client.",+ invalid_client_metadata:+ "The authorization server rejected Paperclip's client registration details.",+ invalid_grant:+ "The authorization server rejected the authorization code or refresh token.",+ invalid_redirect_uri:+ "The authorization server rejected Paperclip's callback URL.",+ invalid_request:+ "The authorization server rejected the request as malformed.",+ invalid_scope: "The authorization server rejected the requested permissions.",+ invalid_software_statement:+ "The authorization server rejected Paperclip's client registration details.",+ login_required:+ "The authorization server needs to be signed in to. Try connecting again.",+ server_error:+ "The authorization server reported an internal error. Try again shortly.",+ temporarily_unavailable:+ "The authorization server is temporarily unavailable. Try again shortly.",+ unapproved_software_statement:+ "The authorization server rejected Paperclip's client registration details.",+ unauthorized_client:+ "The authorization server refused to authorize Paperclip's OAuth client.",+ unsupported_grant_type:+ "The authorization server does not support the grant Paperclip uses.",+ unsupported_response_type:+ "The authorization server does not support the sign-in flow Paperclip uses.",+};++/**+ * Reduce a provider-supplied `error` to a bounded, allowlisted label safe to+ * keep in structured `details`. Returns `null` only when the provider sent no+ * `error` at all, so the caller can tell "silent failure" from "said something+ * Paperclip does not recognize".+ */+export function normalizeOAuthProviderError(value: unknown): string | null {+ if (typeof value !== "string" || value.length === 0) return null;+ // Bound length and character class before the allowlist even though+ // membership implies both: these limits are what keeps the label safe if the+ // allowlist above ever grows a pattern-matched entry.+ if (value.length > MAX_OAUTH_PROVIDER_ERROR_LENGTH)+ return UNRECOGNIZED_OAUTH_PROVIDER_ERROR;+ if (!OAUTH_PROVIDER_ERROR_PATTERN.test(value))+ return UNRECOGNIZED_OAUTH_PROVIDER_ERROR;+ return OAUTH_PROVIDER_ERROR_CODES.has(value)+ ? value+ : UNRECOGNIZED_OAUTH_PROVIDER_ERROR;+}++/** Paperclip's own message for a provider failure, never the provider's. */+export function oauthProviderErrorMessage(+ providerError: string | null,+ fallback: string,+): string {+ if (!providerError) return fallback;+ return OAUTH_PROVIDER_ERROR_MESSAGES[providerError] ?? fallback;+}diff --git a/server/src/services/tool-access/oauth/types.ts b/server/src/services/tool-access/oauth/types.tsnew file mode 100644index 0000000000..c9782e0716--- /dev/null+++ b/server/src/services/tool-access/oauth/types.ts@@ -0,0 +1,53 @@+import type { ToolConnectionOwnership, ToolConnectionTransport, OAuthEndpointKind } from "@paperclipai/shared";++export type OAuthProviderEndpoints = {+ provider: string;+ scopes: string[];+ /** Refresh permission belongs to authorization-server metadata, not MCP tool scopes. */+ offlineAccessSupported?: boolean;+ authorizationUrl: string;+ tokenUrl: string;+ registrationUrl?: string | null;+ codeChallengeMethodsSupported?: string[];+ tokenEndpointAuthMethodsSupported?: string[];+ grantTypesSupported?: string[];+ grantType?: "authorization_code" | "client_credentials";+ metadataUrl?: string | null;+ /**+ * Canonical authorization-server issuer, when discovery found one. Registered+ * client material is bound to it, `iss` on the callback is validated against+ * it, and reconnect/refresh reuse it instead of re-deriving a provider key.+ */+ issuer?: string | null;+ /**+ * RFC 8707 resource indicator: the MCP endpoint the token is for. Sent on both+ * authorization and token requests so the authorization server can audience-+ * restrict the access token to this server rather than to everything Paperclip+ * has ever connected.+ */+ resource?: string | null;+ /** The authorization server advertised support for Client ID Metadata Documents. */+ clientIdMetadataDocumentSupported?: boolean;+};++/**+ * Where an OAuth client came from, in the preference order the current MCP+ * client-registration guidance recommends (PAP-17087).+ */+export type OAuthClientRegistrationSource =+ "preconfigured" | "cimd" | "dcr" | "manual";++export type OAuthTokenEndpointAuthMethod =+ "none" | "client_secret_basic" | "client_secret_post";++export type OAuthConnectionSettings = {+ config: Record<string, unknown>;+ companyId: string;+ transport: ToolConnectionTransport;+ ownership: ToolConnectionOwnership;+};++export type OAuthTransport = {+ fetchRemoteHttpUrl: (value: string, init?: RequestInit) => Promise<Response>;+ assertOAuthEndpointUrl: (kind: OAuthEndpointKind, value: unknown, options?: { firstPartyOrigin?: string | null }) => string;+};