Skip to content

The open-source app everyone uses to manage agents at work

27.5 KB
Raw Blame
import { vercelConnectHttpError, vercelCredentialFor, vercelConnectResourcesFor } from "../vercel-credentials.js";
import { credentialScope, managedConnectorProfile } from "./client-settings.js";
import { createOAuthClientRegistration } from "./client-registration.js";
import type { ActorInfo } from "../types.js";
import { createOAuthEndpointPolicy } from "./endpoint-policy.js";
import { createOAuthDiscovery } from "./discovery.js";
import { oauthConfig, normalizeOauthScopes, originOf } from "./metadata.js";
import { connectionMethodForConnection } from "../connection-methods.js";
import { GOOGLE_WORKSPACE_DEFAULT_SELECTION, googleWorkspaceSelectedScopes, type GoogleWorkspaceServiceSelection, isGoogleWorkspaceScopeGrant } from "@paperclipai/shared";
import { and, eq, lt } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import { agents, connectionGrants, issueThreadInteractions, toolConnections, toolOauthStates } from "@paperclipai/db";
import type { ConnectionGrantKind, ToolOAuthStartResult } from "@paperclipai/shared";
import { getConnectableAppDefinition } from "@paperclipai/shared";
import { badRequest, conflict, forbidden, unprocessable } from "../../../errors.js";
import { isPaperclipCloudConnectorStrategy, type PaperclipCloudConnector } from "../../paperclip-cloud-connector.js";
import { deriveVercelConnectSubject, vercelConnectCallbackUrl, VercelConnectClientError, type VercelConnectClient } from "../../vercel-connect.js";

import type { ConnectionSetupPolicy } from "../connections/setup-policy.js";
import { assertSupportedConnection } from "../connections/setup-policy.js";

import { actorBinding } from "../actor.js";
import { assertOAuthRedirectConstraints, randomOauthToken, base64UrlSha256 } from "./authorization-constraints.js";
import type { createPersonalConnectionIdentity } from "../connections/personal-identity.js";

type Dependencies = {
  now: () => Date;
  getConnectionRow(idOrUid: string, companyId?: string): Promise<typeof toolConnections.$inferSelect>;
  setupPolicy: ConnectionSetupPolicy;
  fixedPersonalIdentityForReconnect: ReturnType<typeof createPersonalConnectionIdentity>;
  currentCloudConnector: () => PaperclipCloudConnector | null;
  vercelConnect: VercelConnectClient | null;
  ensureOAuthClient: ReturnType<typeof createOAuthClientRegistration>;
  oauthEndpointsForConnection: ReturnType<typeof createOAuthDiscovery>["oauthEndpointsForConnection"];
  assertOAuthEndpointUrl: ReturnType<typeof createOAuthEndpointPolicy>["assertOAuthEndpointUrl"];
};

export function createOAuthAuthorizationStart(db: Db, dependencies: Dependencies) {
  const { now, getConnectionRow, setupPolicy, fixedPersonalIdentityForReconnect, currentCloudConnector, vercelConnect, ensureOAuthClient, oauthEndpointsForConnection, assertOAuthEndpointUrl } = dependencies;
  const { assertConnectorConnectionSetupEnabled, assertExperimentalConnectorSetupEnabled } = setupPolicy;
  async function startOAuth(
    companyId: string,
    connectionId: string,
    input: {
      redirectUri: string;
      actor: ActorInfo;
      subjectUserId?: string;
      subjectAgentId?: string;
      scopes?: string[];
      workspaceServices?: GoogleWorkspaceServiceSelection;
      returnTo?: string;
      issueId?: string;
      interactionId?: string;
    },
  ): Promise<ToolOAuthStartResult> {
    let connection = await getConnectionRow(connectionId, companyId);
    assertSupportedConnection(connection);
    await assertConnectorConnectionSetupEnabled(connection);
    await assertExperimentalConnectorSetupEnabled(connection.config.sourceTemplateKey, connection.status !== "draft");
    if (connection.status === "archived")
      throw conflict("Archived app connections cannot start sign in");
    const sourceTemplateKey =
      typeof connection.config.sourceTemplateKey === "string"
        ? connection.config.sourceTemplateKey
        : null;
    const galleryEntry = sourceTemplateKey
      ? getConnectableAppDefinition(sourceTemplateKey)
      : null;
    assertOAuthRedirectConstraints(galleryEntry, input.redirectUri);
    const galleryMethod = galleryEntry
      ? connectionMethodForConnection(galleryEntry, connection)
      : null;
    const requestedScopes = await (async () => {
      if (input.workspaceServices && sourceTemplateKey !== "google-workspace") throw badRequest("Service selection requires Google Workspace");
      if (sourceTemplateKey === "google-workspace") {
        if (input.workspaceServices && input.scopes) throw badRequest("Choose services or scopes, not both");
        const allowed = normalizeOauthScopes(galleryMethod?.defaults?.scopesHint);
        let scopes = input.scopes ?? (input.workspaceServices ? googleWorkspaceSelectedScopes(input.workspaceServices) : undefined);
        if (!scopes && connection.status !== "draft") {
          // Account-page reconnect has no new service choice. Never replace its
          // subject's saved request with the new-account write defaults.
          const binding = actorBinding(input.actor);
          const subjectUserId = input.subjectUserId ?? (binding.actorType === "user" ? binding.actorId : null);
          const kind = connection.credentialPolicy === "per_user" ? "user"
            : connection.credentialPolicy === "per_agent" ? "agent" : "organization";
          const [grant] = await db.select().from(connectionGrants).where(and(
            eq(connectionGrants.companyId, companyId),
            eq(connectionGrants.connectionId, connection.id),
            eq(connectionGrants.kind, kind),
            kind === "user" ? eq(connectionGrants.subjectUserId, subjectUserId ?? "")
              : kind === "agent" ? eq(connectionGrants.subjectAgentId, input.subjectAgentId ?? "")
                : eq(connectionGrants.isDefault, true),
          )).limit(1);
          const saved = grant?.providerTenant?.oauth;
          scopes = normalizeOauthScopes(saved?.requestedScopes ?? saved?.scopes)
            .filter(scope => allowed.includes(scope));
          if (scopes.length === 0) throw badRequest("Choose your Google Workspace services before reconnecting");
        }
        scopes ??= googleWorkspaceSelectedScopes(GOOGLE_WORKSPACE_DEFAULT_SELECTION);
        if (!isGoogleWorkspaceScopeGrant(scopes) || scopes.some(scope => !allowed.includes(scope))) throw badRequest("Select at least one supported Google service");
        return scopes;
      }
      if (!galleryMethod) return input.scopes ?? null;
      const allowed = normalizeOauthScopes(galleryMethod.defaults?.scopesHint);
      if (!input.scopes) return allowed;
      const requested = normalizeOauthScopes(input.scopes);
      const widened = requested.filter((scope) => !allowed.includes(scope));
      if (widened.length > 0) {
        throw badRequest(
          `Requested OAuth scopes are not allowed for ${galleryEntry?.name ?? "this app"}`,
          {
            code: "oauth_scope_widening_rejected",
            scopes: widened,
          },
        );
      }
      return requested;
    })();
    const starterBinding = actorBinding(input.actor);
    const fixedPersonalIdentity = await fixedPersonalIdentityForReconnect(
      connection,
      input.subjectUserId,
      input.actor,
    );
    const authorizationSubjectUserId =
      fixedPersonalIdentity?.subjectUserId ?? input.subjectUserId;
    const authorizationSubjectAgentId = input.subjectAgentId;
    if (authorizationSubjectAgentId) {
      const [subjectAgent] = await db
        .select({ id: agents.id })
        .from(agents)
        .where(
          and(
            eq(agents.id, authorizationSubjectAgentId),
            eq(agents.companyId, companyId),
          ),
        )
        .limit(1);
      if (!subjectAgent)
        throw badRequest(
          "Dedicated identity requires an agent in this company",
        );
      if (connection.credentialPolicy !== "per_agent") {
        throw badRequest(
          "This connection is not configured for a dedicated agent identity",
        );
      }
    }
    const intentLink = input.interactionId
      ? await db
          .select({
            id: issueThreadInteractions.id,
            issueId: issueThreadInteractions.issueId,
            addresseeUserId: issueThreadInteractions.addresseeUserId,
            kind: issueThreadInteractions.kind,
            status: issueThreadInteractions.status,
          })
          .from(issueThreadInteractions)
          .where(
            and(
              eq(issueThreadInteractions.id, input.interactionId),
              eq(issueThreadInteractions.companyId, companyId),
            ),
          )
          .limit(1)
          .then((rows) => rows[0] ?? null)
      : null;
    if (
      input.interactionId &&
      (!intentLink ||
        intentLink.kind !== "connection_intent" ||
        intentLink.status !== "pending" ||
        starterBinding.actorType !== "user" ||
        starterBinding.actorId !== intentLink.addresseeUserId)
    ) {
      throw forbidden(
        "Only the addressed user can authorize this connection request",
      );
    }
    if (connection.credentialSource === "vercel_connect") {
      if (!vercelConnect)
        throw vercelConnectHttpError(
          new VercelConnectClientError("vercel_connect_unavailable", 503),
        );
      const credential = vercelCredentialFor(connection);
      if (
        connection.authKind !== "oauth" ||
        credential.principalMode !== "user"
      ) {
        throw badRequest(
          "This Vercel connector does not use browser authorization",
        );
      }
      const binding = starterBinding;
      if (!binding.actorType || !binding.actorId) {
        throw forbidden(
          "Vercel Connect authorization requires an authenticated actor",
        );
      }
      const grantKind: ConnectionGrantKind = authorizationSubjectUserId
        ? "user"
        : "organization";
      const derived = deriveVercelConnectSubject({
        credential,
        connectionId: connection.id,
        companyId,
        grantKind,
        subjectUserId: authorizationSubjectUserId,
      });
      const state = randomOauthToken();
      let authorization;
      try {
        authorization = await vercelConnect.startAuthorization(
          {
            connector: credential.connectorUid,
            subject: derived.subject,
            scopes: credential.scopes,
            resources: vercelConnectResourcesFor(connection),
          },
          vercelConnectCallbackUrl(input.redirectUri, state),
        );
      } catch (error) {
        throw vercelConnectHttpError(error);
      }
      const remoteExpiry = authorization.expiresAt
        ? new Date(authorization.expiresAt)
        : null;
      const expiresAt =
        remoteExpiry && Number.isFinite(remoteExpiry.getTime())
          ? new Date(
              Math.min(
                remoteExpiry.getTime(),
                now().getTime() + 10 * 60 * 1000,
              ),
            )
          : new Date(now().getTime() + 10 * 60 * 1000);
      await db
        .delete(toolOauthStates)
        .where(lt(toolOauthStates.expiresAt, now()));
      await db.insert(toolOauthStates).values({
        state,
        companyId,
        connectionId: connection.id,
        // Vercel owns its verifier. This marker only dispatches the consumed
        // one-time state to the Vercel callback completion path.
        codeVerifier: "vercel-connect",
        createdByActorType: binding.actorType,
        createdByActorId: binding.actorId,
        createdBySessionId: binding.sessionId,
        subjectUserId: authorizationSubjectUserId,
        requestedScopes: [...credential.scopes],
        returnTo: input.returnTo,
        issueId: intentLink?.issueId ?? input.issueId,
        interactionId: intentLink?.id,
        expiresAt,
      });
      return {
        connectionId: connection.id,
        provider: `vercel-connect:${credential.service}`,
        authorizationUrl: authorization.url,
        expiresAt: expiresAt.toISOString(),
        issuer: "https://vercel.com/connect",
        resource: galleryMethod?.defaults?.serverUrl ?? null,
        registrationSource: null,
      };
    }
    if (
      galleryMethod &&
      isPaperclipCloudConnectorStrategy(galleryMethod.oauthStrategy)
    ) {
      const connectorProfile = galleryMethod.connectorProfile;
      const managedProfile = managedConnectorProfile(connectorProfile);
      if (!managedProfile)
        throw badRequest("This app has an invalid managed connector profile");
      const providerName = galleryEntry?.name ?? "Google Workspace";
      const cloudConnector = currentCloudConnector();
      if (!cloudConnector) {
        throw unprocessable(
          `${providerName} connections through Paperclip are not available on this instance yet`,
          {
            code: "paperclip_cloud_connector_unavailable",
          },
        );
      }
      const binding = starterBinding;
      if (!binding.actorType || !binding.actorId) {
        throw forbidden(
          `${providerName} sign-in requires an authenticated actor`,
        );
      }
      const subjectUserId = authorizationSubjectAgentId
        ? null
        : (authorizationSubjectUserId ??
          (binding.actorType === "user" ? binding.actorId : null));
      if (!subjectUserId && !authorizationSubjectAgentId) {
        throw forbidden(
          `Agent-started ${providerName} sign-in requires an authorized identity`,
        );
      }
      if (
        !authorizationSubjectAgentId &&
        binding.actorType === "user" &&
        subjectUserId !== binding.actorId
      ) {
        throw forbidden(
          `Board users may only authorize their own ${providerName} identity`,
        );
      }
      await db
        .delete(toolOauthStates)
        .where(lt(toolOauthStates.expiresAt, now()));
      const state = randomOauthToken();
      const returnUri = new URL(input.redirectUri);
      returnUri.pathname = "/api/tools/oauth/cloud-connector/callback";
      returnUri.search = "";
      returnUri.hash = "";
      const session = await cloudConnector.startAuthorization({
        subject: authorizationSubjectAgentId
          ? `agent:${authorizationSubjectAgentId}`
          : subjectUserId!,
        companyId,
        profile: managedProfile.id,
        ...(managedProfile.id === "workspace.all" ? { scopes: requestedScopes! } : {}),
        returnUri: returnUri.toString(),
        returnState: state,
      });
      const remoteExpiry = new Date(session.expiresAt);
      const expiresAt = Number.isFinite(remoteExpiry.getTime())
        ? new Date(
            Math.min(remoteExpiry.getTime(), now().getTime() + 10 * 60 * 1000),
          )
        : new Date(now().getTime() + 10 * 60 * 1000);
      await db.insert(toolOauthStates).values({
        state,
        companyId,
        connectionId: connection.id,
        // Paperclip Cloud owns PKCE for this flow. The local state row remains the
        // single-use browser correlator and never stores broker token material.
        codeVerifier: "paperclip-cloud-connector",
        createdByActorType: binding.actorType,
        createdByActorId: binding.actorId,
        createdBySessionId: binding.sessionId,
        subjectUserId,
        subjectAgentId: authorizationSubjectAgentId,
        requestedScopes: managedProfile.id === "workspace.all" ? requestedScopes! : [...managedProfile.scopes],
        returnTo: input.returnTo,
        issueId: intentLink?.issueId ?? input.issueId,
        interactionId: intentLink?.id,
        expiresAt,
      });
      return {
        connectionId: connection.id,
        provider: managedProfile.provider,
        authorizationUrl: session.authorizationUrl,
        expiresAt: expiresAt.toISOString(),
        ...(session.handoff ? { handoff: session.handoff } : {}),
        issuer:
          managedProfile.provider === "github"
            ? "https://github.com"
            : managedProfile.provider === "asana"
              ? "https://app.asana.com"
              : "https://accounts.google.com",
        resource: galleryMethod.defaults?.serverUrl ?? null,
        registrationSource: null,
      };
    }
    const endpoints = await oauthEndpointsForConnection(
      connection,
      null,
      input.redirectUri,
    );
    if (endpoints.grantType === "client_credentials") {
      throw unprocessable(
        "This app uses shared machine credentials and does not need browser sign in",
      );
    }
    const resolvedClient = await ensureOAuthClient({
      connection,
      endpoints,
      redirectUri: input.redirectUri,
      galleryEntry,
      actor: input.actor,
    });
    connection = resolvedClient.connection;
    const client = resolvedClient.client;
    if (galleryMethod?.oauthClientSecretRequired && !client.clientSecret) {
      throw unprocessable("This app requires an OAuth client secret. Add it in the app setup before signing in.");
    }
    if (!client.clientId)
      throw unprocessable(
        `OAuth client id is not configured for ${endpoints.provider}`,
      );

    const authorizationScopes = normalizeOauthScopes(
      galleryMethod ? (requestedScopes ?? []) : (input.scopes ?? endpoints.scopes),
    );
    if (
      !galleryMethod &&
      endpoints.offlineAccessSupported &&
      (!endpoints.grantTypesSupported?.length ||
        endpoints.grantTypesSupported.includes("refresh_token")) &&
      !authorizationScopes.includes("offline_access")
    ) authorizationScopes.push("offline_access");

    await db
      .delete(toolOauthStates)
      .where(lt(toolOauthStates.expiresAt, new Date()));

    const state = randomOauthToken();
    const codeVerifier = randomOauthToken(48);
    const expiresAt = new Date(Date.now() + 10 * 60 * 1000);
    const binding = starterBinding;
    if (!binding.actorType || !binding.actorId) {
      throw forbidden("OAuth sign-in requires an authenticated board session");
    }
    await db.insert(toolOauthStates).values({
      state,
      companyId,
      connectionId: connection.id,
      codeVerifier,
      createdByActorType: binding.actorType,
      createdByActorId: binding.actorId,
      createdBySessionId: binding.sessionId,
      subjectUserId: authorizationSubjectUserId,
      requestedScopes: authorizationScopes,
      returnTo: input.returnTo,
      issueId: intentLink?.issueId ?? input.issueId,
      interactionId: intentLink?.id,
      expiresAt,
    });

    // Last gate before this URL becomes a top-level browser navigation. Every
    // producer above already validates, so reaching a rejection here means a new
    // path was added without one — fail closed rather than hand the board an
    // unvetted target.
    const authorizationUrl = new URL(
      assertOAuthEndpointUrl("authorization", endpoints.authorizationUrl, {
        // Paperclip's own callback origin: a first-party authorization endpoint is
        // served however this deployment is served, plaintext LAN host included.
        firstPartyOrigin: originOf(input.redirectUri),
      }),
    );
    authorizationUrl.searchParams.set("response_type", "code");
    authorizationUrl.searchParams.set("client_id", client.clientId);
    authorizationUrl.searchParams.set("redirect_uri", input.redirectUri);
    authorizationUrl.searchParams.set("state", state);
    authorizationUrl.searchParams.set(
      "code_challenge",
      base64UrlSha256(codeVerifier),
    );
    authorizationUrl.searchParams.set("code_challenge_method", "S256");
    // RFC 8707: name the MCP server the resulting token is for, so an
    // authorization server that serves several resources can audience-restrict it.
    if (endpoints.resource)
      authorizationUrl.searchParams.set("resource", endpoints.resource);
    // Curated definitions are an allowlist, not a suggestion. Never copy every
    // scope advertised by discovery into a provider consent screen: a curated
    // method either sends its reviewed hint or omits scope entirely. Generic
    // MCP URLs retain discovery-first behavior because Paperclip has no manifest
    // against which it could safely judge the caller's requested scope.
    if (authorizationScopes.length > 0)
      authorizationUrl.searchParams.set("scope", authorizationScopes.join(" "));
    if (galleryMethod && connection.config.sourceTemplateKey === "google-workspace")
      authorizationUrl.searchParams.set("enable_granular_consent", "true");
    const reviewedAuthorizationParams =
      galleryMethod?.defaults?.oauthAuthorizationParams;
    if (reviewedAuthorizationParams?.access_type)
      authorizationUrl.searchParams.set(
        "access_type",
        reviewedAuthorizationParams.access_type,
      );
    if (reviewedAuthorizationParams?.prompt)
      authorizationUrl.searchParams.set(
        "prompt",
        reviewedAuthorizationParams.prompt,
      );
    else if (!galleryMethod && authorizationScopes.includes("offline_access"))
      // OIDC offline access requires consent unless the provider has another
      // established basis for granting it. A generic server has no reviewed override.
      authorizationUrl.searchParams.set("prompt", "consent");

    if (
      authorizationSubjectUserId &&
      input.issueId &&
      binding.actorType === "agent"
    ) {
      const idempotencyKey = `connection-authorization:${connection.id}:${authorizationSubjectUserId}`;
      // Provider label for the card's copy. The gallery definition's name when we
      // have one, else the connection's own name — never a secret name or ref.
      const sourceTemplateKey =
        typeof connection.config.sourceTemplateKey === "string"
          ? connection.config.sourceTemplateKey
          : null;
      const providerName =
        (sourceTemplateKey
          ? getConnectableAppDefinition(sourceTemplateKey)?.name
          : null) ?? connection.name;
      const [requestingAgent] = binding.actorId
        ? await db
            .select({ name: agents.name })
            .from(agents)
            .where(
              and(
                eq(agents.id, binding.actorId),
                eq(agents.companyId, companyId),
              ),
            )
            .limit(1)
        : [undefined];
      const payload = {
        version: 1 as const,
        prompt: `Connect your ${providerName} to continue`,
        acceptLabel: `Connect ${providerName}`,
        rejectLabel: "Not now",
        detailsMarkdown:
          "Authorization is required before this agent can act on your behalf.",
        // Presentation metadata so the card can compose its own copy instead of
        // parsing the title string (PAP-17835 seam #6). The interaction kind and
        // the server-addressed audience are unchanged.
        connectionAuthorization: {
          version: 1 as const,
          providerName,
          connectionName:
            connection.name === providerName ? null : connection.name,
          requestingAgentName: requestingAgent?.name ?? null,
        },
        target: {
          type: "custom" as const,
          key: `connection:${connection.uid}:user:${authorizationSubjectUserId}`,
          revisionId: state,
          label: `Connect ${providerName}`,
          href: authorizationUrl.toString(),
        },
      };
      const [existingInteraction] = await db
        .select()
        .from(issueThreadInteractions)
        .where(
          and(
            eq(issueThreadInteractions.companyId, companyId),
            eq(issueThreadInteractions.issueId, input.issueId),
            eq(issueThreadInteractions.idempotencyKey, idempotencyKey),
          ),
        )
        .limit(1);
      const [interaction] = existingInteraction
        ? await db
            .update(issueThreadInteractions)
            .set({
              status: "pending",
              requestedResolverPolicy: "human_only",
              effectiveResolverPolicy: "human_only",
              resolverPolicyProvenance: "explicit",
              effectiveResolverPolicySource: "requested",
              addresseeUserId: authorizationSubjectUserId,
              payload,
              result: null,
              resolvedAt: null,
              updatedAt: new Date(),
            })
            .where(eq(issueThreadInteractions.id, existingInteraction.id))
            .returning()
        : await db
            .insert(issueThreadInteractions)
            .values({
              companyId,
              issueId: input.issueId,
              kind: "request_confirmation",
              status: "pending",
              continuationPolicy: "none",
              requestedResolverPolicy: "human_only",
              effectiveResolverPolicy: "human_only",
              resolverPolicyProvenance: "explicit",
              effectiveResolverPolicySource: "requested",
              addresseeUserId: authorizationSubjectUserId,
              idempotencyKey,
              sourceRunId:
                binding.actorType === "agent"
                  ? (input.actor.sessionId ?? null)
                  : null,
              title: `Connect your ${providerName} to continue`,
              summary: `${requestingAgent?.name ?? "An agent"} needs your ${providerName} identity for work running as you.`,
              createdByAgentId:
                binding.actorType === "agent" ? binding.actorId : null,
              payload,
            })
            .returning();
      if (interaction) {
        await db
          .update(toolOauthStates)
          .set({ interactionId: interaction.id })
          .where(eq(toolOauthStates.state, state));
      }
    }

    const nextConfig = {
      ...connection.config,
      oauth: {
        ...oauthConfig(connection),
        provider: endpoints.provider,
        authorizationUrl: endpoints.authorizationUrl,
        tokenUrl: endpoints.tokenUrl,
        registrationUrl: endpoints.registrationUrl ?? null,
        metadataUrl: endpoints.metadataUrl ?? null,
        // Curated apps persist only the reviewed scopes attached to this OAuth
        // state. Discovery metadata can advertise a provider's entire scope
        // universe and must never silently become Paperclip's requested set.
        scopes: authorizationScopes,
        offlineAccessSupported: endpoints.offlineAccessSupported,
        grantTypesSupported: endpoints.grantTypesSupported ?? [],
        codeChallengeMethodsSupported:
          endpoints.codeChallengeMethodsSupported ?? [],
        tokenEndpointAuthMethodsSupported:
          endpoints.tokenEndpointAuthMethodsSupported ?? [],
        grantType: "authorization_code",
        clientIdEnv: client.clientIdEnv,
        clientSecretEnv: client.clientSecret ? client.clientSecretEnv : null,
        credentialScope: credentialScope(connection, input.actor),
        // Persist the issuer and resource this authorization run is bound to.
        // `iss` on the callback is validated against `expectedIssuer`, and
        // refresh/reconnect/revoke reuse the same pair rather than re-deriving it.
        issuer: endpoints.issuer ?? oauthConfig(connection).issuer ?? null,
        expectedIssuer: endpoints.issuer ?? null,
        resource:
          endpoints.resource ?? oauthConfig(connection).resource ?? null,
        clientIdMetadataDocumentSupported:
          endpoints.clientIdMetadataDocumentSupported === true,
      },
    };
    await db
      .update(toolConnections)
      .set({
        // A generic URL connection starts life as `authKind: none`. Once it has
        // completed OAuth discovery and client resolution it is an OAuth
        // connection, and refresh, reconnect, revoke and diagnostics must all
        // treat it as one.
        authKind: "oauth",
        config: nextConfig,
        transportConfig: nextConfig,
        updatedAt: new Date(),
      })
      .where(eq(toolConnections.id, connection.id));

    return {
      connectionId: connection.id,
      provider: endpoints.provider,
      authorizationUrl: authorizationUrl.toString(),
      expiresAt: expiresAt.toISOString(),
      issuer: endpoints.issuer ?? null,
      resource: endpoints.resource ?? null,
      registrationSource: resolvedClient.source,
    };
  }
  return startOAuth;
}