@opengeni/api-router 0.30.1 → 1.0.0

package/src/integrations/oauth-client.ts

@@ -1,60 +1,154 @@
+import { safeReturnPath } from "./oauth-return-path";
+import { assertOrganizationIntegrationAllowed, stableJson } from "@opengeni/contracts";
+import {
+  withOrganizationIntegrationAcquisition,
+  withOrganizationIntegrationPolicyFence,
+} from "@opengeni/db/organization-integration-policy";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { parseIntegrationsOauthClientsJson, type Settings } from "@opengeni/config";
 import {
-  OPENGENI_PERSONAL_SLACK_MCP_URL,
   OAuthStartResponse,
   selectCanonicalPersonalSlackConnection,
   type ConnectionOwnership,
   type OAuthStartRequest,
 } from "@opengeni/contracts";
-import { hasPermission, requireEnvironmentEncryption } from "@opengeni/core";
+import { requireEnvironmentEncryption, integrationKeyForConnectProvider } from "@opengeni/core";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import type { Observability } from "@opengeni/observability";
 import {
   consumeIntegrationOAuthStateNonce,
+  claimConnectOperation,
+  finishConnectOperation,
+  getConnectAttempt,
   createConnection,
   decryptEnvironmentValue,
   encryptEnvironmentValue,
   getConnectionMetadata,
-  getWorkspaceGrant,
+  getGlobalCatalogOAuthProfile,
   listConnectionsMetadata,
   loadIntegrationOAuthClient,
+  loadIntegrationOAuthPendingState,
   normalizeBearerScheme,
   replaceIntegrationOAuthClientIfCurrent,
   storeIntegrationOAuthClient,
+  storeIntegrationOAuthPendingState,
   updateConnection,
   withDatabaseStatementTimeout,
   type Database,
 } from "@opengeni/db";
-import { createSignedState, readSignedState } from "@opengeni/github";
+import { createSignedState, inspectSignedState, readSignedState } from "@opengeni/github";
 import {
   DestinationPolicyError,
+  McpOAuthDiscoveryError,
   OAUTH_MAX_RESPONSE_BYTES,
   RequestDeadlineError,
   isLocalTestEnvironment,
+  parseMcpOAuthChallenge,
   pinnedFetch,
   readResponseJsonBounded,
+  resolveMcpOAuthDiscovery,
   validateHttpUrl,
+  type McpAuthorizationServerMetadata,
+  type McpOAuthChallenge,
+  type McpOAuthDiscoveryMode,
+  type McpOAuthMetadataFetchResult,
+  type McpProtectedResourceMetadata,
 } from "@opengeni/network";
 import { Buffer } from "node:buffer";
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { HTTPException } from "hono/http-exception";
+import {
+  assertConnectionOwnershipAllowedForPrincipal,
+  personalOwnerStateAccepted,
+  personalOwnerVerifiedInState,
+  PERSONAL_CONNECTION_PRINCIPAL_MESSAGE,
+  PERSONAL_OWNER_VERIFIED_STATE_CLAIM,
+} from "../connection-ownership";
 import { ApiHttpError } from "../http/api-error";
+import { requireConnectOwnerAuthority } from "./connect-authority";
+import {
+  DEFAULT_OAUTH_PROFILE,
+  OFFICIAL_GMAIL_MCP_URL,
+  DEPLOYMENT_MANAGED_CLIENTS,
+  builtInOAuthProfileByKey,
+  assertAuthorizationServerNotReserved,
+  assertAuthorizationServerPins,
+  builtInOAuthProfileFor,
+  catalogMcpUrlKey,
+  defaultOwnershipFor,
+  deploymentManagedClientFor,
+  oauthProfileFromCatalog,
+  type OAuthProviderProfile,
+  type PinnableAuthorizationServer,
+} from "./oauth-profiles";
 import { canonicalProviderDomain } from "./provider-domain";
 
 export const oauthStateTtlMs = 10 * 60 * 1000;
-export const OFFICIAL_SLACK_MCP_URL = OPENGENI_PERSONAL_SLACK_MCP_URL;
-export const OFFICIAL_GMAIL_MCP_URL = "https://gmailmcp.googleapis.com/mcp/v1";
-export const OFFICIAL_GMAIL_MCP_SCOPES = [
-  "https://www.googleapis.com/auth/gmail.readonly",
-  "https://www.googleapis.com/auth/gmail.compose",
-  "https://www.googleapis.com/auth/gmail.modify",
-] as const;
-const SLACK_OAUTH_ORIGIN = "https://slack.com";
-const SLACK_MCP_ORIGIN = "https://mcp.slack.com";
-const GOOGLE_OAUTH_ISSUER_ORIGIN = "https://accounts.google.com";
-const GOOGLE_TOKEN_ORIGIN = "https://oauth2.googleapis.com";
+
+/**
+ * Workspace-free landing for a callback whose state names no trustworthy
+ * workspace. The web app resolves it to the viewer's current workspace
+ * integrations page and keeps the callback outcome parameters.
+ */
+export const INTEGRATIONS_FALLBACK_PATH = "/integrations";
+
+const WORKSPACE_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+/** The web integrations page for one workspace (the Plugins surface). */
+export function workspaceIntegrationsPath(workspaceId: string): string {
+  return `/workspaces/${encodeURIComponent(workspaceId)}/plugins`;
+}
+
+/**
+ * The integrations page for a workspace id read from untrusted input (a URL
+ * parameter or an unverified-age state), or null unless it is a workspace UUID.
+ * A link target only: it grants nothing.
+ */
+export function workspaceIntegrationsPathForUntrusted(candidate: unknown): string | null {
+  return typeof candidate === "string" && WORKSPACE_ID_PATTERN.test(candidate)
+    ? workspaceIntegrationsPath(candidate)
+    : null;
+}
+
+/**
+ * Where a callback returns, and why, when its own signed state is unusable.
+ *
+ * A correctly signed state still names its workspace, even when it is too old
+ * or its flow rejected it, so the browser returns to that workspace's
+ * integrations page; an aged one is reported as expired. Anything unsigned,
+ * tampered, or signed with another secret returns to
+ * {@link INTEGRATIONS_FALLBACK_PATH}. Display routing only: nothing here
+ * authorizes, resumes, or replays the callback.
+ */
+export function oauthStateFailureReturn(
+  settings: Settings,
+  rawState: string | undefined,
+  nowMs = Date.now(),
+): { returnPath: string; reason: "state_expired" | "state_invalid" } {
+  let payload: ReturnType<typeof inspectSignedState> = null;
+  try {
+    payload = rawState
+      ? inspectSignedState(rawState, requireIntegrationsStateSecret(settings))
+      : null;
+  } catch {
+    payload = null;
+  }
+  return {
+    returnPath:
+      workspaceIntegrationsPathForUntrusted(payload?.workspaceId) ?? INTEGRATIONS_FALLBACK_PATH,
+    reason:
+      payload !== null && nowMs - payload.iat * 1000 > oauthStateTtlMs
+        ? "state_expired"
+        : "state_invalid",
+  };
+}
+export {
+  OFFICIAL_GMAIL_MCP_SCOPES,
+  OFFICIAL_GMAIL_MCP_URL,
+  OFFICIAL_SLACK_MCP_URL,
+} from "./oauth-profiles";
 export { OAUTH_MAX_RESPONSE_BYTES } from "@opengeni/network";
 
 type OAuthClientDeps = {
@@ -66,41 +160,32 @@ type OAuthClientDeps = {
 };
 
 export type OAuthStartContext = {
+  /** Server-selected dedicated adapter identity; never copied from request metadata. */
+  integrationKey?: "gmail" | "slack-personal";
+  connectAttemptId?: string;
+  externalContinuation?: ExternalActorContinuation;
   accountId: string;
   workspaceId: string;
   subjectId: string;
+  /**
+   * False for every principal that cannot own a personal Connection (API keys,
+   * the configured key, services, agent attempts). Resolved by the route from
+   * the live authenticated principal, never inferred here.
+   */
+  personalOwnershipAllowed: boolean;
   requestUrl: string;
   payload: OAuthStartRequest;
 };
 
 export type OAuthCallbackResult = {
   redirectTo: string;
+  exactReturn?: boolean;
 };
 
-type WwwAuthenticateChallenge = {
-  resourceMetadata?: string;
-  scope?: string[];
-  error?: string;
-};
-
-type ProtectedResourceMetadata = {
-  resource?: string;
-  authorizationServers: string[];
-  scopesSupported: string[];
-  raw: Record<string, unknown>;
-};
-
-type AuthorizationServerMetadata = {
-  issuer: string;
-  authorizationServer: string;
-  authorizationEndpoint: string;
-  tokenEndpoint: string;
-  registrationEndpoint?: string;
-  clientIdMetadataDocumentSupported: boolean;
-  tokenEndpointAuthMethodsSupported: string[];
-  codeChallengeMethodsSupported: string[];
-  raw: Record<string, unknown>;
-};
+type WwwAuthenticateChallenge = McpOAuthChallenge;
+type ProtectedResourceMetadata = McpProtectedResourceMetadata;
+type AuthorizationServerMetadata = McpAuthorizationServerMetadata;
+type OAuthDiscoveryMode = McpOAuthDiscoveryMode | "provider_oauth_metadata";
 
 type OAuthClientRegistration = {
   method: "operator" | "manual" | "cimd" | "dcr";
@@ -112,10 +197,16 @@ type OAuthClientRegistration = {
 };
 
 type OAuthStatePayload = {
+  integrationKey?: "gmail" | "slack-personal";
+  connectAttemptId?: string;
+  externalContinuation?: ExternalActorContinuation;
+  returnUrl?: string;
   accountId: string;
   workspaceId: string;
   subjectId: string;
   ownership: ConnectionOwnership;
+  /** Signed proof that a live managed human authorized personal ownership. */
+  personalOwnerVerified: boolean;
   providerDomain: string;
   mcpUrl: string;
   resource: string;
@@ -126,6 +217,10 @@ type OAuthStatePayload = {
   tokenEndpoint: string;
   authorizationServer: string;
   issuer: string;
+  discoveryMode: OAuthDiscoveryMode;
+  discoveryMetadataSha256?: string;
+  protectedResourceMetadataUrl?: string;
+  authorizationServerMetadataUrl?: string;
   clientRegistrationMethod: OAuthClientRegistration["method"];
   tokenEndpointAuthMethod: OAuthClientRegistration["tokenEndpointAuthMethod"];
   resourceParameterSupported: boolean;
@@ -162,7 +257,8 @@ export type OAuthStartStage =
   | "mcp_challenge"
   | "protected_resource_metadata"
   | "authorization_server_metadata"
-  | "client_registration";
+  | "client_registration"
+  | "state_persist";
 
 class OAuthStartStageError extends Error {
   constructor(
@@ -175,6 +271,13 @@ class OAuthStartStageError extends Error {
   }
 }
 
+class OAuthMetadataUpstreamError extends Error {
+  constructor(readonly upstreamStatus: number) {
+    super(`OAuth metadata endpoint returned HTTP ${upstreamStatus}`);
+    this.name = "OAuthMetadataUpstreamError";
+  }
+}
+
 class OAuthStartDeadline {
   readonly signal: AbortSignal;
   private readonly controller = new AbortController();
@@ -279,10 +382,90 @@ class OAuthCallbackDeadline {
   }
 }
 
+/** Policy is the outermost lock. Receipt replay still runs normal authorization,
+ * but the DB calls authorizeAcquisition only for uncommitted progress. Provider
+ * requests must happen after this transaction, never inside either wrapper. */
+export async function claimOAuthAcquisition(
+  db: Database,
+  scope: Parameters<typeof claimConnectOperation>[1],
+  input: Parameters<typeof claimConnectOperation>[2],
+  integrationKey: string | null,
+  acquiring = true,
+) {
+  if (!acquiring) return claimConnectOperation(db, scope, input);
+  return withOrganizationIntegrationPolicyFence(db, scope, (tx, policy) =>
+    claimConnectOperation(tx, scope, {
+      ...input,
+      authorizeAcquisition: async (locked, attempt) => {
+        assertOrganizationIntegrationAllowed(policy, integrationKey);
+        await input.authorizeAcquisition?.(locked, attempt);
+      },
+    }),
+  );
+}
+
+type IntegrationSourceSelection = Record<string, unknown> & {
+  id: string;
+  syncEnabled: boolean;
+  readPolicy: "allow" | "ask" | "block";
+};
+
+/** Compare server-bound selections, not provider classification. Removing a
+ * source, disabling sync, or narrowing its read permission acquires no authority.
+ * Generation/timestamp bookkeeping does not turn an unchanged save into setup. */
+export function integrationSourceSelectionRequiresAcquisition(
+  previous: readonly IntegrationSourceSelection[],
+  requested: readonly IntegrationSourceSelection[],
+): boolean {
+  const rank = { block: 0, ask: 1, allow: 2 };
+  const config = (source: IntegrationSourceSelection) => {
+    const {
+      selectedAt: _selectedAt,
+      configGeneration: _generation,
+      syncEnabled: _enabled,
+      readPolicy: _readPolicy,
+      ...binding
+    } = source;
+    return stableJson(binding);
+  };
+  return requested.some((source) => {
+    const existing = previous.find((candidate) => candidate.id === source.id);
+    return (
+      !existing ||
+      (!existing.syncEnabled && source.syncEnabled) ||
+      rank[source.readPolicy] > rank[existing.readPolicy] ||
+      config(existing) !== config(source)
+    );
+  });
+}
+
+export async function finishOAuthAcquisition(
+  db: Database,
+  scope: Parameters<typeof finishConnectOperation>[1],
+  input: Parameters<typeof finishConnectOperation>[2],
+  integrationKey: string | null,
+) {
+  return withOrganizationIntegrationPolicyFence(db, scope, (tx, policy) =>
+    finishConnectOperation(tx, scope, {
+      ...input,
+      authorizeAcquisition: async (locked, attempt) => {
+        assertOrganizationIntegrationAllowed(policy, integrationKey);
+        await input.authorizeAcquisition?.(locked, attempt);
+      },
+    }),
+  );
+}
+
 export async function startMcpOAuth(
   deps: OAuthClientDeps,
   context: OAuthStartContext,
 ): Promise<OAuthStartResponse> {
+  await withOrganizationIntegrationAcquisition(
+    deps.db,
+    context,
+    [context.integrationKey ?? "custom:mcp"],
+    async () => {},
+  );
   const deadline = new OAuthStartDeadline(deps.oauthStartDeadlineMs ?? OAUTH_START_DEADLINE_MS);
   try {
     return await startMcpOAuthWithinDeadline(deps, context, deadline);
@@ -304,17 +487,51 @@ async function startMcpOAuthWithinDeadline(
   deadline: OAuthStartDeadline,
 ): Promise<OAuthStartResponse> {
   const { db, settings } = deps;
+  const externalContinuation = context.externalContinuation
+    ? ExternalActorContinuation.parse(context.externalContinuation)
+    : undefined;
+  const returnUrl =
+    context.payload.returnUrl !== undefined
+      ? exactExternalReturnUrl(context.payload.returnUrl)
+      : undefined;
+  if (
+    (externalContinuation && !returnUrl) ||
+    (returnUrl && !externalContinuation && !context.connectAttemptId)
+  )
+    throw new HTTPException(422, {
+      message: "external MCP OAuth requires verified actor authority and a host returnUrl",
+    });
+  if (
+    externalContinuation &&
+    (externalContinuation.actor.accountId !== context.accountId ||
+      externalContinuation.actor.effectiveSubjectId !== context.subjectId)
+  )
+    throw new HTTPException(403, { message: "external OAuth actor mismatch" });
   const mcpUrl = canonicalMcpResource(context.payload.mcpUrl ?? context.payload.resource);
-  const officialGmailResource = mcpUrl === OFFICIAL_GMAIL_MCP_URL;
-  const officialSlackResource = mcpUrl === OFFICIAL_SLACK_MCP_URL;
-  const providerDomain = officialSlackResource
-    ? "slack.com"
-    : canonicalProviderDomain(context.payload.providerDomain ?? new URL(mcpUrl).hostname);
-  const hostedSlackMcp = officialSlackResource || providerDomain === "slack.com";
-  assertHostedSlackMcpOAuthStart(settings, context.payload, mcpUrl, hostedSlackMcp);
-  const requestedOwnership: ConnectionOwnership = context.payload.ownership ?? "workspace";
-  assertOfficialGmailPersonalOwnership(mcpUrl, requestedOwnership);
-  const returnPath = safeReturnPath(context.payload.returnPath ?? "/integrations");
+  const urlProfile = builtInOAuthProfileFor({ mcpUrl });
+  const providerDomain =
+    urlProfile?.canonicalProviderDomain ??
+    canonicalProviderDomain(context.payload.providerDomain ?? new URL(mcpUrl).hostname);
+  const builtInProfile = urlProfile ?? builtInOAuthProfileFor({ mcpUrl, providerDomain });
+  const profile =
+    builtInProfile ??
+    (await deadline.run("connection_lookup", async () => {
+      const raw = await getGlobalCatalogOAuthProfile(
+        db,
+        context.workspaceId,
+        catalogMcpUrlKey(mcpUrl),
+      );
+      return raw === null ? null : oauthProfileFromCatalog(mcpUrl, raw);
+    })) ??
+    DEFAULT_OAUTH_PROFILE;
+  assertOAuthStartProfile(settings, context.payload, mcpUrl, profile);
+  // Catalog defaults are setup preferences; an explicit ownership always wins.
+  const requestedOwnership: ConnectionOwnership =
+    context.payload.ownership ?? defaultOwnershipFor(profile);
+  assertProfileOwnership(profile, requestedOwnership);
+  const returnPath = safeReturnPath(
+    context.payload.returnPath ?? workspaceIntegrationsPath(context.workspaceId),
+  );
   const baseUrl = integrationBaseUrl(settings.publicBaseUrl, context.requestUrl);
   const redirectUri = `${baseUrl}/v1/integrations/oauth/callback`;
   const metadataUrl = `${baseUrl}/v1/integrations/oauth/client-metadata.json`;
@@ -324,8 +541,8 @@ async function startMcpOAuthWithinDeadline(
       subjectId: context.subjectId,
       providerDomain,
       mcpUrl,
-      hostedSlackMcp,
-      exactMcpBinding: hostedSlackMcp || officialGmailResource,
+      connectionSelection: profile.connectionSelection,
+      exactMcpBinding: profile.exactMcpBinding,
       connectionId: context.payload.connectionId,
       requestedOwnership: context.payload.ownership,
       newConnectionOwnership: requestedOwnership,
@@ -337,30 +554,29 @@ async function startMcpOAuthWithinDeadline(
   const ownership = existing
     ? ownershipForConnection(existing.subjectId, context.subjectId)
     : requestedOwnership;
-
-  const discovery = await discoverMcpOAuth(mcpUrl, settings, deadline);
-  if (hostedSlackMcp && !isLocalTestEnvironment(settings.environment)) {
-    assertSlackAuthorizationServer(discovery.as);
-  }
-  const googleAuthorizationServer = hasGoogleAuthorizationServerIdentity(discovery.as);
-  if (officialGmailResource || googleAuthorizationServer) {
-    if (!officialGmailResource || providerDomain !== "gmailmcp.googleapis.com") {
-      throw new HTTPException(422, {
-        message: `Google OAuth is allowed only for ${OFFICIAL_GMAIL_MCP_URL}`,
-      });
-    }
-    assertGoogleAuthorizationServer(discovery.as);
-  }
-  const resourceParameterSupported = !officialGmailResource;
-  const resource = discovery.prm.resource ? canonicalOAuthResource(discovery.prm.resource) : mcpUrl;
+  assertProfileOwnership(profile, ownership);
+  // Only a managed human can own a personal Connection: personal-authority
+  // execution resolves through a delegation snapshot frozen on a human's causal
+  // turn, and migration 0256 can mint the `user` authority scope only for a
+  // subject that holds an active organization membership. An explicit personal
+  // choice is never silently downgraded to workspace ownership.
+  assertConnectionOwnershipAllowedForPrincipal(ownership, context.personalOwnershipAllowed);
+
+  const discovery = profile.providerOAuthDiscovery
+    ? await discoverProviderOAuth(mcpUrl, settings, deadline, profile)
+    : await discoverMcpOAuth(mcpUrl, settings, deadline);
+  assertDiscoveredAuthorizationServer(settings, discovery.as, profile, providerDomain);
+  const resourceParameterSupported =
+    discovery.mode === "rfc9728_protected_resource" && profile.sendResourceParameter;
+  const resource = discovery.resource;
   const verifier = randomPkceVerifier();
-  // The Gmail PRM advertises broader grants, including full-mail access. The
-  // reviewed connector never lets a caller widen the capability contract.
-  const authorizeScopes = chooseMcpAuthorizeScopes({
-    mcpUrl,
+  // A profile's exact scope override wins outright: the reviewed connector
+  // never lets a caller widen the capability contract.
+  const authorizeScopes = chooseProfileAuthorizeScopes(profile, {
     requested: context.payload.requestedScopes,
     challenged: discovery.challenge.scope,
     supported: discovery.prm.scopesSupported,
+    authorizationServerScopesSupported: stringArray(discovery.as.raw.scopes_supported),
   });
   const client = await deadline.run("client_registration", (signal) =>
     registerOAuthClient(
@@ -371,20 +587,50 @@ async function startMcpOAuthWithinDeadline(
       redirectUri,
       authorizeScopes,
       context.payload.oauthClient,
+      profile,
       signal,
+      context,
     ),
   );
+  if (
+    profile.confidentialClientRequired &&
+    (!isConfidentialOAuthClient(client) ||
+      !discovery.as.tokenEndpointAuthMethodsSupported.includes(client.tokenEndpointAuthMethod))
+  ) {
+    throw new OAuthStartStageError(
+      "client_registration",
+      "configuration_missing",
+      new HTTPException(503, {
+        message:
+          "Gmail OAuth requires a registered Google Web application client with a secret and supported token authentication",
+      }),
+    );
+  }
   const key = requireEnvironmentEncryption(settings);
-  const state = createSignedState(requireIntegrationsStateSecret(settings), {
+  const fullState = createSignedState(requireIntegrationsStateSecret(settings), {
+    ...(context.integrationKey ? { integrationKey: context.integrationKey } : {}),
+    ...(context.connectAttemptId ? { connectAttemptId: context.connectAttemptId } : {}),
     accountId: context.accountId,
     workspaceId: context.workspaceId,
     subjectId: context.subjectId,
     ownership,
+    // Signed record that a live principal was checked; the callback has no
+    // principal of its own and enforces exactly this decision.
+    [PERSONAL_OWNER_VERIFIED_STATE_CLAIM]: context.personalOwnershipAllowed,
+    ...(externalContinuation
+      ? {
+          encryptedExternalContinuation: encryptEnvironmentValue(
+            requireEnvironmentEncryption(settings),
+            JSON.stringify(externalContinuation),
+          ),
+        }
+      : {}),
+    ...(returnUrl ? { returnUrl } : {}),
     providerDomain,
     mcpUrl,
     resource,
-    requestedScopes: officialGmailResource
-      ? [...OFFICIAL_GMAIL_MCP_SCOPES]
+    requestedScopes: profile.requestedScopes
+      ? [...profile.requestedScopes]
       : uniqueStrings(context.payload.requestedScopes ?? []),
     authorizeScopes,
     encryptedPkceVerifier: encryptEnvironmentValue(key, verifier),
@@ -392,6 +638,14 @@ async function startMcpOAuthWithinDeadline(
     tokenEndpoint: discovery.as.tokenEndpoint,
     authorizationServer: client.authorizationServer,
     issuer: client.issuer,
+    discoveryMode: discovery.mode,
+    discoveryMetadataSha256: discovery.provenance.metadataSha256,
+    ...(discovery.provenance.protectedResourceMetadataUrl
+      ? {
+          protectedResourceMetadataUrl: discovery.provenance.protectedResourceMetadataUrl,
+        }
+      : {}),
+    authorizationServerMetadataUrl: discovery.provenance.authorizationServerMetadataUrl,
     clientRegistrationMethod: client.method,
     tokenEndpointAuthMethod: client.tokenEndpointAuthMethod,
     resourceParameterSupported,
@@ -403,6 +657,29 @@ async function startMcpOAuthWithinDeadline(
     returnPath,
     ...(existing ? { connectionId: existing.id, connectionVersion: existing.version } : {}),
   });
+  const expiresAt = new Date(Date.now() + oauthStateTtlMs);
+  let state = fullState;
+  if (settings.integrationsOauthShortStateEnabled) {
+    const stateId = randomUUID();
+    state = createSignedState(requireIntegrationsStateSecret(settings), {
+      kind: "mcp_oauth_reference",
+      id: stateId,
+      accountId: context.accountId,
+      workspaceId: context.workspaceId,
+    });
+    if (state.length > 512) {
+      throw new Error("MCP OAuth reference state exceeded its provider-safe length");
+    }
+    await deadline.run("state_persist", async () =>
+      storeIntegrationOAuthPendingState(db, {
+        id: stateId,
+        accountId: context.accountId,
+        workspaceId: context.workspaceId,
+        stateEncrypted: encryptEnvironmentValue(key, fullState),
+        expiresAt,
+      }),
+    );
+  }
   const authorizationUrl = buildAuthorizationUrl({
     endpoint: discovery.as.authorizationEndpoint,
     settings,
@@ -413,31 +690,84 @@ async function startMcpOAuthWithinDeadline(
     verifier,
     scopes: authorizeScopes,
     resourceParameterSupported,
+    ...(profile.extraAuthorizeParams ? { extraParams: profile.extraAuthorizeParams } : {}),
   });
   return OAuthStartResponse.parse({
     state,
     authorizationUrl,
-    expiresAt: new Date(Date.now() + oauthStateTtlMs).toISOString(),
+    expiresAt: expiresAt.toISOString(),
   });
 }
 
-export function assertOfficialGmailPersonalOwnership(
+export function isHostedSlackMcpTarget(providerDomain: string, mcpUrl: string): boolean {
+  return builtInOAuthProfileFor({ mcpUrl, providerDomain })?.key === "hosted-slack-mcp";
+}
+
+/** Start-time payload fences declared by the resolved profile. */
+function assertOAuthStartProfile(
+  settings: Settings,
+  payload: OAuthStartRequest,
   mcpUrl: string,
-  ownership: ConnectionOwnership,
+  profile: OAuthProviderProfile,
 ): void {
-  if (mcpUrl === OFFICIAL_GMAIL_MCP_URL && ownership !== "personal") {
-    throw new HTTPException(422, {
-      message:
-        "Gmail connections are personal only; each workspace member must connect their own mailbox",
-    });
+  if (profile.rejectCallerOAuthClient && payload.oauthClient) {
+    throw new HTTPException(422, { message: profile.rejectCallerOAuthClient.message });
+  }
+  if (
+    profile.requireProviderDomain &&
+    payload.providerDomain &&
+    canonicalProviderDomain(payload.providerDomain) !== profile.requireProviderDomain.domain
+  ) {
+    throw new HTTPException(422, { message: profile.requireProviderDomain.message });
+  }
+  if (
+    profile.requireExactMcpUrl &&
+    !isLocalTestEnvironment(settings.environment) &&
+    mcpUrl !== profile.requireExactMcpUrl.url
+  ) {
+    throw new HTTPException(422, { message: profile.requireExactMcpUrl.message });
+  }
+  if (
+    profile.requireDeploymentClient &&
+    !deploymentManagedClientFor(settings, profile.requireDeploymentClient.key)
+  ) {
+    throw new HTTPException(503, { message: profile.requireDeploymentClient.message });
   }
 }
 
+/**
+ * Post-discovery fences, in an order that preserves the historical error
+ * surface: the profile's provider identity, then its authorization-server
+ * origin pins, then the reserved-server guard for everything else.
+ */
+function assertDiscoveredAuthorizationServer(
+  settings: Settings,
+  as: PinnableAuthorizationServer,
+  profile: OAuthProviderProfile,
+  providerDomain: string,
+): void {
+  if (
+    profile.postDiscoveryProviderDomain &&
+    providerDomain !== profile.postDiscoveryProviderDomain.domain
+  ) {
+    throw new HTTPException(422, { message: profile.postDiscoveryProviderDomain.message });
+  }
+  if (
+    profile.authorizationServer &&
+    !(profile.authorizationServer.skipInLocalTest && isLocalTestEnvironment(settings.environment))
+  ) {
+    assertAuthorizationServerPins(as, profile.authorizationServer);
+  }
+  assertAuthorizationServerNotReserved(as, profile);
+}
+
 export async function completeMcpOAuthCallback(
   deps: OAuthClientDeps,
   input: {
     code?: string | undefined;
     state?: string | undefined;
+    /** The provider's `error` parameter, for example `access_denied` on Cancel. */
+    error?: string | undefined;
     requestUrl: string;
   },
 ): Promise<OAuthCallbackResult> {
@@ -456,12 +786,15 @@ async function completeMcpOAuthCallbackWithinDeadline(
   input: {
     code?: string | undefined;
     state?: string | undefined;
+    error?: string | undefined;
     requestUrl: string;
   },
   deadline: OAuthCallbackDeadline,
 ): Promise<OAuthCallbackResult> {
   const { db, settings, observability } = deps;
   let state: OAuthStatePayload | null = null;
+  let integrationKey: string | null = "custom:mcp";
+  let connectOperation: { attemptId: string; operationId: string; inputDigest: string } | undefined;
   if (!input.state) {
     const error = new OAuthCallbackStageError(
       "state_verify",
@@ -470,25 +803,94 @@ async function completeMcpOAuthCallbackWithinDeadline(
     );
     logOAuthCallbackFailure(observability, error, state);
     return {
-      redirectTo: callbackReturnPath("/integrations", "error", {
+      redirectTo: callbackReturnPath(INTEGRATIONS_FALLBACK_PATH, "error", {
         stage: error.stage,
         reason: error.reason,
       }),
     };
   }
   try {
-    state = readOAuthState(input.state, settings);
-    // Fence state minted by an older deployment too: a rolling update must not
-    // let a still-valid workspace-owned Gmail callback persist shared authority.
-    assertOfficialGmailPersonalOwnership(state.mcpUrl, state.ownership);
-    if (!input.code) {
-      return {
-        redirectTo: callbackReturnPath(state.returnPath, "error", {
-          stage: "state_verify",
-          reason: "missing_code",
-        }),
+    state = await resolveMcpOAuthState(db, settings, input.state, deadline);
+    integrationKey = state.integrationKey ?? "custom:mcp";
+    if (state.connectAttemptId) {
+      const stored = await getConnectAttempt(db, state, state.connectAttemptId);
+      // Native Gmail setup uses its own provider id, but shares this callback.
+      // Bind that id to the exact reviewed Gmail destination before
+      // claiming an operation (including receipt replay), not to arbitrary MCP.
+      const gmailAttemptMatches =
+        stored.attempt.providerId === "gmail" &&
+        state.mcpUrl === OFFICIAL_GMAIL_MCP_URL &&
+        state.providerDomain === "gmailmcp.googleapis.com" &&
+        builtInOAuthProfileFor(state)?.key === "official-gmail" &&
+        personalOwnerStateAccepted(state);
+      if (
+        (!["mcp-oauth", "slack-personal"].includes(stored.attempt.providerId) &&
+          !gmailAttemptMatches) ||
+        stored.attempt.ownership !== state.ownership ||
+        stored.returnUrl !== state.returnUrl
+      )
+        throw new HTTPException(403, { message: "OAuth attempt mismatch" });
+      connectOperation = {
+        attemptId: state.connectAttemptId,
+        operationId: `oauth:${state.nonce}`,
+        inputDigest: createHash("sha256").update(input.state).digest("hex"),
       };
+      integrationKey = integrationKeyForConnectProvider(stored.attempt.providerId);
+      const claim = await claimOAuthAcquisition(
+        db,
+        state,
+        {
+          ...connectOperation,
+          expectedRevision: stored.attempt.revision,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        },
+        integrationKey,
+        Boolean(input.code),
+      );
+      if (claim.status === "replayed") return { redirectTo: stored.returnUrl, exactReturn: true };
     }
+    // The callback enforces the signed start-time principal decision.
+    // Workspace ownership requires no personal-owner claim.
+    if (!personalOwnerStateAccepted(state)) {
+      throw new OAuthCallbackStageError(
+        "state_verify",
+        "state_invalid",
+        new HTTPException(422, { message: PERSONAL_CONNECTION_PRINCIPAL_MESSAGE }),
+      );
+    }
+    if (input.error || !input.code) {
+      // The provider sends `error` (for example `access_denied` when the user
+      // clicks Cancel) instead of a code. Report that as a refusal, not as an
+      // expired attempt, and never echo the provider's own text.
+      const cancelled = input.error === "access_denied";
+      if (connectOperation) {
+        await finishConnectOperation(db, state, {
+          ...connectOperation,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+          commit: async (_tx, current) => ({
+            ...current,
+            revision: current.revision + 1,
+            state: cancelled ? "cancelled" : "failed",
+            nextAction: { type: "none" },
+            error: {
+              code: input.error ? "provider_denied" : "missing_code",
+              message: "Authorization was not completed. Start a new connection attempt.",
+              retryable: false,
+            },
+          }),
+        });
+      }
+      return callbackStateResult(
+        state,
+        "error",
+        input.error
+          ? { stage: "authorize", reason: cancelled ? "access_denied" : "provider_error" }
+          : { stage: "state_verify", reason: "missing_code" },
+      );
+    }
+    await withOrganizationIntegrationAcquisition(db, state, [integrationKey], async () => {});
     const consumed = await runCallbackDatabaseStage(
       deadline,
       "state_verify",
@@ -516,12 +918,21 @@ async function completeMcpOAuthCallbackWithinDeadline(
         ? error
         : new OAuthCallbackStageError("state_verify", "state_invalid", error);
     logOAuthCallbackFailure(observability, staged, state);
-    return {
-      redirectTo: callbackReturnPath(state?.returnPath ?? "/integrations", "error", {
-        stage: staged.stage,
-        reason: staged.reason,
-      }),
-    };
+    if (!state) {
+      // The state itself could not be resolved, so it carries no return path.
+      // An authentic but aged state still names its workspace and "expired".
+      const failure = oauthStateFailureReturn(settings, input.state);
+      return {
+        redirectTo: callbackReturnPath(failure.returnPath, "error", {
+          stage: staged.stage,
+          reason: staged.reason === "state_invalid" ? failure.reason : staged.reason,
+        }),
+      };
+    }
+    return callbackStateResult(state, "error", {
+      stage: staged.stage,
+      reason: staged.reason,
+    });
   }
 
   const ownerSubjectId = state.ownership === "personal" ? state.subjectId : null;
@@ -533,6 +944,16 @@ async function completeMcpOAuthCallbackWithinDeadline(
     const client = await runCallbackDatabaseStage(deadline, "client_lookup", db, (scopedDb) =>
       clientForState(scopedDb, settings, state),
     );
+    if (
+      builtInOAuthProfileFor(state)?.confidentialClientRequired &&
+      !isConfidentialOAuthClient(client)
+    ) {
+      throw new OAuthCallbackStageError(
+        "client_lookup",
+        "invalid_client",
+        new Error("Gmail OAuth client is unavailable"),
+      );
+    }
     const token = await deadline.run("token_exchange", (signal) =>
       exchangeAuthorizationCode(settings, {
         code: input.code!,
@@ -545,6 +966,27 @@ async function completeMcpOAuthCallbackWithinDeadline(
         signal,
       }),
     );
+    const profile = builtInOAuthProfileFor(state);
+    if (profile?.freshRefreshTokenRequired && !token.refreshToken) {
+      // Never splice a previous account's refresh token into a new grant.
+      // Google can omit refresh_token even after another consent prompt.
+      throw new OAuthCallbackStageError(
+        "token_exchange",
+        "offline_access_unavailable",
+        new Error("Google did not grant offline access. Start a new Gmail connection attempt."),
+      );
+    }
+    const scopes = grantedScopes(token.scopeText, state.authorizeScopes, profile);
+    if (
+      profile?.fullRequestedScopesRequired &&
+      profile.requestedScopes?.some((scope) => !scopes.includes(scope))
+    ) {
+      throw new OAuthCallbackStageError(
+        "token_exchange",
+        "insufficient_scope",
+        new Error("Google did not grant the reviewed Gmail permissions."),
+      );
+    }
     const verification = await verifyMcpToolsListNonFatal(
       observability,
       settings,
@@ -552,7 +994,6 @@ async function completeMcpOAuthCallbackWithinDeadline(
       token,
       deadline,
     );
-    const scopes = grantedScopes(token.scopeText, state.authorizeScopes);
     const credential = credentialBundle(token, state, client);
     const metadata = {
       resource: state.resource,
@@ -562,11 +1003,24 @@ async function completeMcpOAuthCallbackWithinDeadline(
       tokenEndpoint: state.tokenEndpoint,
       clientId: client.clientId,
       clientRegistrationMethod: state.clientRegistrationMethod,
+      oauthDiscovery: {
+        mode: state.discoveryMode,
+        resource: state.resource,
+        issuer: state.issuer,
+        ...(state.discoveryMetadataSha256 ? { metadataSha256: state.discoveryMetadataSha256 } : {}),
+        ...(state.protectedResourceMetadataUrl
+          ? { protectedResourceMetadataUrl: state.protectedResourceMetadataUrl }
+          : {}),
+        ...(state.authorizationServerMetadataUrl
+          ? { authorizationServerMetadataUrl: state.authorizationServerMetadataUrl }
+          : {}),
+      },
       mcpToolsVerification: verification.metadata,
+      ...(verification.providerIdentity ?? {}),
       ...(verification.tools ? { mcpTools: verification.tools } : {}),
     };
     const credentialEncrypted = encryptEnvironmentValue(key, JSON.stringify(credential));
-    const connection = await runCallbackDatabaseStage(deadline, "persist", db, async (scopedDb) => {
+    const persist = async (scopedDb: Database) => {
       await requireOAuthCallbackGrant(scopedDb, state!);
       return state!.connectionId
         ? await updateConnection(scopedDb, {
@@ -577,7 +1031,7 @@ async function completeMcpOAuthCallbackWithinDeadline(
             subjectId: ownerSubjectId,
             providerDomain: state.providerDomain,
             kind: "oauth2",
-            status: "active",
+            status: verification.connectionStatus ?? "active",
             credentialEncrypted,
             grantedScopes: scopes,
             expiresAt: token.expiresAt,
@@ -590,13 +1044,55 @@ async function completeMcpOAuthCallbackWithinDeadline(
             subjectId: ownerSubjectId,
             providerDomain: state.providerDomain,
             kind: "oauth2",
+            status: verification.connectionStatus ?? "active",
             credentialEncrypted,
             grantedScopes: scopes,
             expiresAt: token.expiresAt,
             metadata,
             createdBySubjectId: state.subjectId,
           });
-    });
+    };
+    if (connectOperation) {
+      await runCallbackDatabaseStage(deadline, "persist", db, (scopedDb) =>
+        finishOAuthAcquisition(
+          scopedDb,
+          state!,
+          {
+            ...connectOperation!,
+            authorize: (tx, _attempt, origin) =>
+              requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+            commit: async (tx, current) => {
+              const connection = await persist(tx);
+              if (!connection)
+                throw new HTTPException(409, {
+                  message: "connection changed during OAuth reconnect",
+                });
+              return {
+                ...current,
+                revision: current.revision + 1,
+                state: "complete",
+                completionRequirement: "connection",
+                credentialsCommitted: true,
+                nextAction: { type: "none" },
+                account: {
+                  id: connection.id,
+                  version: connection.version,
+                  providerId: current.providerId,
+                  label: state!.providerDomain,
+                  ownership: current.ownership,
+                  status: connection.status === "needs_reauth" ? "auth_needed" : "connected",
+                },
+              };
+            },
+          },
+          integrationKey,
+        ),
+      );
+      return { redirectTo: state.returnUrl!, exactReturn: true };
+    }
+    const connection = await runCallbackDatabaseStage(deadline, "persist", db, (scopedDb) =>
+      withOrganizationIntegrationAcquisition(scopedDb, state!, [integrationKey], persist),
+    );
     if (!connection) {
       throw new HTTPException(409, {
         message: "connection changed during OAuth reconnect; start again",
@@ -606,29 +1102,90 @@ async function completeMcpOAuthCallbackWithinDeadline(
     // the enable connectionRef straight from the redirect, without a listConnections
     // round-trip that could fail (transient, or a grant lacking connections:read)
     // and leave the connection created but the capability un-enabled.
-    return {
-      redirectTo: callbackReturnPath(state.returnPath, "success", {
-        connectionId: connection.id,
-        providerDomain: connection.providerDomain,
-        ownership: state.ownership,
-        ...(verification.metadata.status === "failed" ? { verification: "failed" } : {}),
-      }),
-    };
+    return callbackStateResult(state, "success", {
+      connectionId: connection.id,
+      providerDomain: connection.providerDomain,
+      ownership: state.ownership,
+      ...(verification.metadata.status === "failed" ? { verification: "failed" } : {}),
+    });
   } catch (error) {
     const staged =
       error instanceof OAuthCallbackStageError
         ? error
         : new OAuthCallbackStageError("persist", "persist_failed", error);
     logOAuthCallbackFailure(observability, staged, state);
-    return {
-      redirectTo: callbackReturnPath(state.returnPath, "error", {
-        stage: staged.stage,
-        reason: staged.reason,
-      }),
-    };
+    if (connectOperation && builtInOAuthProfileFor(state)?.key === "official-gmail") {
+      // The external return URL stays exact. Its caller reads the durable
+      // attempt result, which must not remain in flight after a rejected grant.
+      try {
+        await withDatabaseStatementTimeout(db, OAUTH_CALLBACK_DB_STATEMENT_TIMEOUT_MS, (tx) =>
+          finishConnectOperation(tx, state!, {
+            ...connectOperation!,
+            authorize: (locked, _attempt, origin) =>
+              requireConnectOwnerAuthority(locked, state!, "connections:write", origin),
+            commit: async (_locked, current) => ({
+              ...current,
+              revision: current.revision + 1,
+              state: "failed",
+              nextAction: { type: "none" },
+              error: {
+                code: staged.reason,
+                message:
+                  staged.reason === "offline_access_unavailable"
+                    ? "Google did not grant offline access. Your previous connection is unchanged. Start a new Gmail connection attempt."
+                    : staged.reason === "insufficient_scope"
+                      ? "Google did not grant all required Gmail permissions. Your previous connection is unchanged. Start a new connection attempt and approve the requested permissions."
+                      : "Gmail authorization could not be verified. Your previous connection is unchanged. Start a new connection attempt.",
+                retryable: true,
+              },
+            }),
+          }),
+        );
+      } catch (settlementError) {
+        logOAuthCallbackFailure(
+          observability,
+          new OAuthCallbackStageError("persist", "persist_failed", settlementError),
+          state,
+        );
+      }
+    }
+    return callbackStateResult(state, "error", {
+      stage: staged.stage,
+      reason: staged.reason,
+    });
   }
 }
 
+function exactExternalReturnUrl(raw: string): string {
+  if (!raw || raw.length > 4096 || /[\u0000-\u0020\u007f]/.test(raw))
+    throw new HTTPException(422, { message: "invalid external OAuth returnUrl" });
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new HTTPException(422, { message: "invalid external OAuth returnUrl" });
+  }
+  if (!["https:", "http:"].includes(url.protocol) || url.username || url.password)
+    throw new HTTPException(422, { message: "invalid external OAuth returnUrl" });
+  return raw;
+}
+
+function callbackStateResult(
+  state: OAuthStatePayload | null,
+  status: Parameters<typeof callbackReturnPath>[1],
+  details: Parameters<typeof callbackReturnPath>[2],
+): OAuthCallbackResult {
+  if ((state?.externalContinuation || state?.connectAttemptId) && state.returnUrl)
+    return { redirectTo: state.returnUrl, exactReturn: true };
+  return {
+    redirectTo: callbackReturnPath(
+      state?.returnPath ?? INTEGRATIONS_FALLBACK_PATH,
+      status,
+      details,
+    ),
+  };
+}
+
 export function integrationBaseUrl(publicBaseUrl: string | undefined, requestUrl: string): string {
   return (publicBaseUrl ?? new URL(requestUrl).origin).replace(/\/+$/, "");
 }
@@ -644,113 +1201,283 @@ export function requireIntegrationsStateSecret(settings: Settings): string {
 }
 
 async function requireOAuthCallbackGrant(db: Database, state: OAuthStatePayload): Promise<void> {
-  const grant = await getWorkspaceGrant(db, state.subjectId, state.workspaceId);
-  if (
-    !grant ||
-    grant.accountId !== state.accountId ||
-    !hasPermission(grant.permissions, "connections:write")
-  ) {
-    throw new HTTPException(403, {
-      message: "OAuth subject no longer has permission to write this workspace connection",
-    });
-  }
+  await requireConnectOwnerAuthority(db, state);
 }
 
-function assertHostedSlackMcpOAuthStart(
-  settings: Settings,
-  payload: OAuthStartRequest,
-  mcpUrl: string,
-  hostedSlackMcp: boolean,
-): void {
-  if (!hostedSlackMcp) return;
-  if (payload.oauthClient) {
-    throw new HTTPException(422, {
-      message: "Slack OAuth client credentials are deployment-managed",
-    });
-  }
-  if (payload.providerDomain && canonicalProviderDomain(payload.providerDomain) !== "slack.com") {
-    throw new HTTPException(422, {
-      message: "Slack provider identity does not match slack.com",
-    });
-  }
-  if (!isLocalTestEnvironment(settings.environment) && mcpUrl !== OFFICIAL_SLACK_MCP_URL) {
-    throw new HTTPException(422, {
-      message: `Slack MCP OAuth must use ${OFFICIAL_SLACK_MCP_URL}`,
-    });
-  }
-  if (!settings.slackClientId?.trim() || !settings.slackClientSecret?.trim()) {
-    throw new HTTPException(503, {
-      message: "Slack MCP OAuth requires OPENGENI_SLACK_CLIENT_ID and OPENGENI_SLACK_CLIENT_SECRET",
-    });
+/** The hosted-Slack profile's origin pins, kept exported for its tests. */
+export function assertSlackAuthorizationServer(as: AuthorizationServerMetadata): void {
+  const pins = builtInOAuthProfileByKey("hosted-slack-mcp").authorizationServer;
+  if (pins) {
+    assertAuthorizationServerPins(as, pins);
   }
 }
 
-export function assertSlackAuthorizationServer(as: AuthorizationServerMetadata): void {
-  const issuerOrigins = [as.issuer, as.authorizationServer].map((value) => new URL(value).origin);
-  const endpointOrigins = [as.authorizationEndpoint, as.tokenEndpoint].map(
-    (value) => new URL(value).origin,
-  );
-  if (
-    issuerOrigins.some((origin) => origin !== SLACK_OAUTH_ORIGIN && origin !== SLACK_MCP_ORIGIN) ||
-    endpointOrigins.some((origin) => origin !== SLACK_OAUTH_ORIGIN)
-  ) {
-    throw new HTTPException(422, {
-      message: "Slack MCP authorization metadata did not remain bound to slack.com",
-    });
+/** The official-Gmail profile's origin pins, kept exported for its tests. */
+export function assertGoogleAuthorizationServer(as: AuthorizationServerMetadata): void {
+  const pins = builtInOAuthProfileByKey("official-gmail").authorizationServer;
+  if (pins) {
+    assertAuthorizationServerPins(as, pins);
   }
 }
 
-function hasGoogleAuthorizationServerIdentity(as: AuthorizationServerMetadata): boolean {
-  return [as.issuer, as.authorizationServer].some(
-    (value) => new URL(value).origin === GOOGLE_OAUTH_ISSUER_ORIGIN,
-  );
+/** Inspect without credentials, registration, or running tools. */
+export async function inspectMcpAuthentication(
+  resource: string,
+  settings: Settings,
+): Promise<{
+  kind: "oauth2" | "none" | "unknown";
+  message?: string;
+}> {
+  const deadline = new OAuthStartDeadline(12_000);
+  try {
+    const response = await deadline.run("mcp_challenge", (signal) =>
+      fetchOAuth(resource, settings, {
+        method: "POST",
+        headers: {
+          accept: "application/json, text/event-stream",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: "auth-discovery",
+          method: "initialize",
+          params: {
+            protocolVersion: "2025-03-26",
+            capabilities: {},
+            clientInfo: { name: "OpenGeni", version: "1.0" },
+          },
+        }),
+        signal,
+      }),
+    );
+    const challenge = parseMcpOAuthChallenge(response.headers.get("www-authenticate"));
+    let initialized = false;
+    if (response.ok) {
+      initialized = await deadline.run("mcp_challenge", async () => {
+        const reader = response.body?.getReader();
+        if (!reader) return false;
+        const decoder = new TextDecoder();
+        let text = "";
+        let bytes = 0;
+        const sse = response.headers.get("content-type")?.includes("text/event-stream");
+        try {
+          while (true) {
+            const chunk = await reader.read();
+            if (chunk.done) return false;
+            bytes += chunk.value.byteLength;
+            if (bytes > 262144) return false;
+            text += decoder.decode(chunk.value, { stream: true });
+            const messages = sse
+              ? text
+                  .split(/\r?\n/)
+                  .filter((line) => line.startsWith("data:"))
+                  .map((line) => line.slice(5).trim())
+              : [text];
+            for (const message of messages) {
+              try {
+                const value = JSON.parse(message);
+                if (
+                  value.id === "auth-discovery" &&
+                  typeof value.result?.protocolVersion === "string" &&
+                  value.result?.serverInfo &&
+                  value.result?.capabilities
+                )
+                  return true;
+              } catch {
+                /* Wait for a complete JSON message. */
+              }
+            }
+          }
+        } finally {
+          await reader.cancel().catch(() => undefined);
+        }
+      });
+    } else {
+      await cancelResponseBody(response);
+    }
+    let metadataRead = false;
+    let metadataAbsent = true;
+    try {
+      await resolveMcpOAuthDiscovery({
+        resourceUrl: resource,
+        challenge,
+        fetchMetadata: async ({ kind, url }) => {
+          try {
+            const result = await deadline.run(
+              kind === "protected_resource"
+                ? "protected_resource_metadata"
+                : "authorization_server_metadata",
+              (signal) => fetchOAuthMetadata(url, settings, signal),
+            );
+            metadataRead = true;
+            if (result.status !== "absent") metadataAbsent = false;
+            return result;
+          } catch (error) {
+            metadataAbsent = false;
+            throw error;
+          }
+        },
+        validateEndpoint: (url, label) => oauthEndpointUrl(url, settings, label),
+        canonicalizeResource: canonicalOAuthResource,
+      });
+      return { kind: "oauth2" };
+    } catch (failure) {
+      // Public initialization does not exclude optional or tool-level OAuth.
+      // Only explicit absence of metadata permits the unauthenticated path.
+      if (
+        initialized &&
+        !challenge.scheme &&
+        !challenge.resourceMetadata &&
+        metadataRead &&
+        metadataAbsent
+      )
+        return { kind: "none" };
+      return {
+        kind: "unknown",
+        message: mcpAuthInspectionFailureMessage(failure),
+      };
+    }
+  } catch (failure) {
+    return {
+      kind: "unknown",
+      message: mcpAuthInspectionFailureMessage(failure),
+    };
+  } finally {
+    deadline.dispose();
+  }
 }
 
-export function assertGoogleAuthorizationServer(as: AuthorizationServerMetadata): void {
-  const issuerOrigins = [as.issuer, as.authorizationServer].map((value) => new URL(value).origin);
-  const authorizationOrigin = new URL(as.authorizationEndpoint).origin;
-  const tokenOrigin = new URL(as.tokenEndpoint).origin;
-  if (
-    issuerOrigins.some((origin) => origin !== GOOGLE_OAUTH_ISSUER_ORIGIN) ||
-    authorizationOrigin !== GOOGLE_OAUTH_ISSUER_ORIGIN ||
-    tokenOrigin !== GOOGLE_TOKEN_ORIGIN
-  ) {
-    throw new HTTPException(422, {
-      message: "Gmail MCP authorization metadata did not remain bound to Google",
-    });
+function mcpAuthInspectionFailureMessage(failure: unknown): string {
+  if (failure instanceof OAuthStartStageError) {
+    if (failure.reason === "timeout") {
+      return "Checking how to sign in timed out. Try again.";
+    }
+    if (failure.cause instanceof OAuthMetadataUpstreamError) {
+      return `The provider returned HTTP ${failure.cause.upstreamStatus} while checking how to sign in. Retry or check the provider's setup instructions.`;
+    }
   }
+  return "Could not determine how to sign in. Retry or check the provider's setup instructions.";
 }
 
 async function discoverMcpOAuth(
   resource: string,
   settings: Settings,
   deadline: OAuthStartDeadline,
+  knownChallenge?: WwwAuthenticateChallenge,
 ): Promise<{
   challenge: WwwAuthenticateChallenge;
   prm: ProtectedResourceMetadata;
   as: AuthorizationServerMetadata;
+  mode: McpOAuthDiscoveryMode;
+  resource: string;
+  provenance: {
+    protectedResourceMetadataUrl: string | null;
+    authorizationServerMetadataUrl: string;
+    metadataSha256: string;
+  };
 }> {
-  const challenge = await deadline.run("mcp_challenge", (signal) =>
-    probeMcpChallenge(resource, settings, signal),
-  );
-  const prm = await deadline.run("protected_resource_metadata", (signal) =>
-    discoverProtectedResourceMetadata(resource, settings, challenge.resourceMetadata, signal),
-  );
-  const authorizationServer = prm.authorizationServers[0];
-  if (!authorizationServer) {
-    throw new HTTPException(422, {
-      message: "MCP protected resource metadata did not advertise an authorization server",
+  const challenge =
+    knownChallenge ??
+    (await deadline.run("mcp_challenge", (signal) =>
+      probeMcpChallenge(resource, settings, signal),
+    ));
+  try {
+    const discovery = await resolveMcpOAuthDiscovery({
+      resourceUrl: resource,
+      challenge,
+      fetchMetadata: ({ kind, url }) =>
+        deadline.run(
+          kind === "protected_resource"
+            ? "protected_resource_metadata"
+            : "authorization_server_metadata",
+          (signal) => fetchOAuthMetadata(url, settings, signal),
+        ),
+      validateEndpoint: (rawUrl, label) => oauthEndpointUrl(rawUrl, settings, label),
+      canonicalizeResource: canonicalOAuthResource,
     });
+    return {
+      challenge: discovery.challenge,
+      prm: discovery.protectedResourceMetadata,
+      as: discovery.authorizationServerMetadata,
+      mode: discovery.mode,
+      resource: discovery.resource,
+      provenance: discovery.provenance,
+    };
+  } catch (error) {
+    if (error instanceof OAuthStartStageError) throw error;
+    if (error instanceof McpOAuthDiscoveryError) {
+      throw new OAuthStartStageError(
+        error.stage,
+        error.classification,
+        new HTTPException(422, { message: error.message }),
+      );
+    }
+    throw error;
   }
-  const as = await deadline.run("authorization_server_metadata", (signal) =>
-    discoverAuthorizationServerMetadata(authorizationServer, settings, signal),
+}
+
+/** Exact built-in API bridge discovery never contacts its historical MCP identity. */
+async function discoverProviderOAuth(
+  resource: string,
+  settings: Settings,
+  deadline: OAuthStartDeadline,
+  profile: OAuthProviderProfile,
+) {
+  const pinned = profile.providerOAuthDiscovery;
+  if (!pinned || resource !== profile.requireExactMcpUrl?.url)
+    throw new HTTPException(422, { message: "invalid provider OAuth resource" });
+  const fetched = await deadline.run("authorization_server_metadata", (signal) =>
+    fetchOAuthMetadata(pinned.metadataUrl, settings, signal),
   );
-  if (!as.codeChallengeMethodsSupported.includes("S256")) {
-    throw new HTTPException(422, {
-      message: "authorization server does not support required PKCE S256",
-    });
-  }
-  return { challenge, prm, as };
+  if (fetched.status !== "present")
+    throw new HTTPException(422, { message: "provider OAuth metadata is unavailable" });
+  const raw = fetched.document;
+  const issuer = normalizedIssuerKey(
+    oauthEndpointUrl(requiredString(raw.issuer, "OAuth issuer"), settings, "OAuth issuer"),
+  );
+  if (issuer !== pinned.issuer)
+    throw new HTTPException(422, { message: "provider OAuth issuer did not match its profile" });
+  const as: AuthorizationServerMetadata = {
+    issuer,
+    authorizationServer: pinned.issuer,
+    authorizationEndpoint: oauthEndpointUrl(
+      requiredString(raw.authorization_endpoint, "OAuth authorization endpoint"),
+      settings,
+      "OAuth authorization endpoint",
+    ),
+    tokenEndpoint: oauthEndpointUrl(
+      requiredString(raw.token_endpoint, "OAuth token endpoint"),
+      settings,
+      "OAuth token endpoint",
+    ),
+    clientIdMetadataDocumentSupported: false,
+    tokenEndpointAuthMethodsSupported: stringArray(raw.token_endpoint_auth_methods_supported),
+    codeChallengeMethodsSupported: stringArray(raw.code_challenge_methods_supported),
+    raw,
+    metadataUrl: fetched.url,
+  };
+  if (!as.codeChallengeMethodsSupported.includes("S256"))
+    throw new HTTPException(422, { message: "provider OAuth requires PKCE S256" });
+  return {
+    challenge: { scheme: null, scope: [] } as WwwAuthenticateChallenge,
+    prm: {
+      resource,
+      authorizationServers: [pinned.issuer],
+      scopesSupported: [...(profile.requestedScopes ?? [])],
+      raw: {},
+      metadataUrl: "",
+    } as ProtectedResourceMetadata,
+    as,
+    mode: "provider_oauth_metadata" as const,
+    resource,
+    provenance: {
+      protectedResourceMetadataUrl: null,
+      authorizationServerMetadataUrl: fetched.url,
+      metadataSha256: createHash("sha256")
+        .update(stableJson({ profile: profile.key, resource, metadataUrl: fetched.url, raw }))
+        .digest("hex"),
+    },
+  };
 }
 
 async function probeMcpChallenge(
@@ -765,115 +1492,45 @@ async function probeMcpChallenge(
   });
   try {
     if (response.status !== 401) {
-      return {};
+      return { scheme: null, scope: [] };
     }
-    return parseWwwAuthenticate(response.headers.get("www-authenticate"));
+    return parseMcpOAuthChallenge(response.headers.get("www-authenticate"));
   } finally {
     await cancelResponseBody(response);
   }
 }
 
-async function discoverProtectedResourceMetadata(
-  resource: string,
-  settings: Settings,
-  advertisedUrl?: string,
-  signal?: AbortSignal,
-): Promise<ProtectedResourceMetadata> {
-  const candidates = uniqueStrings([
-    ...(advertisedUrl ? [advertisedUrl] : []),
-    ...wellKnownCandidates(resource, "oauth-protected-resource"),
-  ]);
-  for (const candidate of candidates) {
-    const payload = await fetchJsonObject(candidate, settings, signal).catch((error) => {
-      if (error instanceof HTTPException) {
-        throw error;
-      }
-      return null;
-    });
-    if (!payload) {
-      continue;
-    }
-    const authorizationServers = stringArray(payload.authorization_servers);
-    if (authorizationServers.length === 0) {
-      continue;
-    }
-    return {
-      authorizationServers,
-      scopesSupported: stringArray(payload.scopes_supported),
-      raw: payload,
-      ...(stringValue(payload.resource) ? { resource: stringValue(payload.resource)! } : {}),
-    };
-  }
-  throw new HTTPException(422, {
-    message: "could not discover MCP protected resource metadata",
-  });
-}
-
-async function discoverAuthorizationServerMetadata(
-  authorizationServer: string,
+async function fetchOAuthMetadata(
+  url: string,
   settings: Settings,
   signal: AbortSignal,
-): Promise<AuthorizationServerMetadata> {
-  const safeAuthorizationServer = oauthEndpointUrl(
-    authorizationServer,
-    settings,
-    "OAuth authorization server",
-  ).replace(/\/+$/, "");
-  const candidates = uniqueStrings([
-    // Prefer the RFC metadata locations before probing the issuer itself. Some
-    // providers (including Linear) redirect their issuer root to a human docs
-    // page; following that redirect can leave discovery waiting on an unrelated
-    // streaming response even though the well-known metadata is immediately
-    // available.
-    ...wellKnownCandidates(safeAuthorizationServer, "oauth-authorization-server"),
-    ...wellKnownCandidates(safeAuthorizationServer, "openid-configuration"),
-    safeAuthorizationServer,
-  ]);
-  for (const candidate of candidates) {
-    const payload = await fetchJsonObject(candidate, settings, signal).catch((error) => {
-      if (error instanceof HTTPException) {
-        throw error;
-      }
-      return null;
-    });
-    if (!payload) {
-      continue;
-    }
-    const authorizationEndpoint = stringValue(payload.authorization_endpoint);
-    const tokenEndpoint = stringValue(payload.token_endpoint);
-    if (!authorizationEndpoint || !tokenEndpoint) {
-      continue;
-    }
-    const safeAuthorizationEndpoint = oauthEndpointUrl(
-      authorizationEndpoint,
-      settings,
-      "OAuth authorization endpoint",
-    );
-    const safeTokenEndpoint = oauthEndpointUrl(tokenEndpoint, settings, "OAuth token endpoint");
-    const registrationEndpoint = stringValue(payload.registration_endpoint);
-    const issuer = oauthEndpointUrl(
-      stringValue(payload.issuer) ?? safeAuthorizationServer,
-      settings,
-      "OAuth issuer",
-    );
-    const safeRegistrationEndpoint = registrationEndpoint
-      ? oauthEndpointUrl(registrationEndpoint, settings, "OAuth registration endpoint")
-      : undefined;
-    return {
-      issuer,
-      authorizationServer: safeAuthorizationServer,
-      authorizationEndpoint: safeAuthorizationEndpoint,
-      tokenEndpoint: safeTokenEndpoint,
-      clientIdMetadataDocumentSupported: payload.client_id_metadata_document_supported === true,
-      tokenEndpointAuthMethodsSupported: stringArray(payload.token_endpoint_auth_methods_supported),
-      codeChallengeMethodsSupported: stringArray(payload.code_challenge_methods_supported),
-      raw: payload,
-      ...(safeRegistrationEndpoint ? { registrationEndpoint: safeRegistrationEndpoint } : {}),
-    };
-  }
-  throw new HTTPException(422, {
-    message: "could not discover OAuth authorization server metadata",
+): Promise<McpOAuthMetadataFetchResult> {
+  const response = await fetchOAuth(url, settings, {
+    headers: { accept: "application/json" },
+    signal,
   });
+  if (response.status === 404 || response.status === 410) {
+    await cancelResponseBody(response);
+    return { status: "absent", url, httpStatus: response.status };
+  }
+  if (!response.ok) {
+    await cancelResponseBody(response);
+    throw new OAuthMetadataUpstreamError(response.status);
+  }
+  const payload = await readResponseJsonBounded<unknown>(
+    response,
+    OAUTH_MAX_RESPONSE_BYTES,
+    "OAuth metadata response",
+    { signal },
+  );
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("OAuth metadata response was not a JSON object");
+  }
+  return {
+    status: "present",
+    url,
+    document: payload as Record<string, unknown>,
+  };
 }
 
 async function registerOAuthClient(
@@ -884,16 +1541,16 @@ async function registerOAuthClient(
   redirectUri: string,
   scopes: string[],
   manual: OAuthStartRequest["oauthClient"],
+  profile: OAuthProviderProfile,
   signal: AbortSignal,
+  acquisition: Pick<OAuthStartContext, "accountId" | "workspaceId" | "integrationKey">,
 ): Promise<OAuthClientRegistration> {
   const operator = operatorClientForAs(settings, as);
   if (operator) {
     return operator;
   }
-  // Linear currently advertises CIMD but rejects its client metadata URL at
-  // the authorization endpoint. Its documented interactive setup uses DCR,
-  // so prefer the simultaneously advertised registration endpoint.
-  if (prefersDynamicClientRegistration(as)) {
+  const selfRegistration = preferredOAuthSelfRegistration(as, profile.clientSource);
+  if (selfRegistration === "dcr") {
     return await getOrCreateDynamicClientRegistration(
       db,
       settings,
@@ -901,9 +1558,10 @@ async function registerOAuthClient(
       redirectUri,
       scopes,
       signal,
+      acquisition,
     );
   }
-  if (as.clientIdMetadataDocumentSupported) {
+  if (selfRegistration === "cimd") {
     return {
       method: "cimd",
       issuer: as.issuer,
@@ -925,13 +1583,33 @@ async function registerOAuthClient(
       ),
     };
   }
-  return await getOrCreateDynamicClientRegistration(db, settings, as, redirectUri, scopes, signal);
+  return await getOrCreateDynamicClientRegistration(
+    db,
+    settings,
+    as,
+    redirectUri,
+    scopes,
+    signal,
+    acquisition,
+  );
 }
 
-function prefersDynamicClientRegistration(as: AuthorizationServerMetadata): boolean {
-  return Boolean(
-    as.registrationEndpoint && normalizedIssuerKey(as.issuer) === "https://mcp.linear.app",
-  );
+export function preferredOAuthSelfRegistration(
+  as: Pick<
+    AuthorizationServerMetadata,
+    "clientIdMetadataDocumentSupported" | "registrationEndpoint"
+  >,
+  clientSource: OAuthProviderProfile["clientSource"],
+): "cimd" | "dcr" | null {
+  if (clientSource === "dcr") return "dcr";
+  if (clientSource === "cimd" && as.clientIdMetadataDocumentSupported) return "cimd";
+  // DCR produces an authorization-server-issued client id and is therefore the
+  // interoperable default whenever the server advertises both registration
+  // mechanisms. A reviewed provider profile may explicitly force CIMD for a
+  // server whose registration endpoint is unsuitable.
+  if (clientSource !== "cimd" && as.registrationEndpoint) return "dcr";
+  if (as.clientIdMetadataDocumentSupported) return "cimd";
+  return null;
 }
 
 async function getOrCreateDynamicClientRegistration(
@@ -941,6 +1619,7 @@ async function getOrCreateDynamicClientRegistration(
   redirectUri: string,
   scopes: string[],
   signal: AbortSignal,
+  acquisition: Pick<OAuthStartContext, "accountId" | "workspaceId" | "integrationKey">,
 ): Promise<OAuthClientRegistration> {
   const storedClient = await loadIntegrationOAuthClient(db, settings, as.issuer);
   if (storedClient && storedDcrClientSatisfiesPolicy(storedClient, as, redirectUri, scopes)) {
@@ -961,6 +1640,12 @@ async function getOrCreateDynamicClientRegistration(
       message: "manual OAuth client credentials are required for this authorization server",
     });
   }
+  await withOrganizationIntegrationAcquisition(
+    db,
+    acquisition,
+    [acquisition.integrationKey ?? "custom:mcp"],
+    async () => {},
+  );
   const dcr = await dynamicClientRegistration(settings, as, redirectUri, scopes, signal);
   const key = dcr.clientSecret ? requireEnvironmentEncryption(settings) : null;
   const storeInput = {
@@ -972,34 +1657,43 @@ async function getOrCreateDynamicClientRegistration(
     tokenEndpointAuthMethod: dcr.tokenEndpointAuthMethod,
     metadata: registrationMetadata(as, redirectUri, scopes),
   };
-  if (storedClient) {
-    const replaced = await replaceIntegrationOAuthClientIfCurrent(db, {
-      ...storeInput,
-      expectedClientId: storedClient.clientId,
-    });
-    if (replaced?.clientId === dcr.clientId) {
-      return dcr;
-    }
-    return await loadCompatibleDcrWinner(db, settings, as, redirectUri, scopes);
-  }
-  const storedWinner = await storeIntegrationOAuthClient(db, storeInput);
-  if (storedWinner.clientId === dcr.clientId) {
-    return dcr;
-  }
-  const winner = await loadIntegrationOAuthClient(db, settings, as.issuer);
-  if (winner && storedDcrClientSatisfiesPolicy(winner, as, redirectUri, scopes)) {
-    return dcrRegistrationFromStored(winner);
-  }
-  if (winner) {
-    const replaced = await replaceIntegrationOAuthClientIfCurrent(db, {
-      ...storeInput,
-      expectedClientId: winner.clientId,
-    });
-    if (replaced?.clientId === dcr.clientId) {
-      return dcr;
-    }
-  }
-  return await loadCompatibleDcrWinner(db, settings, as, redirectUri, scopes);
+  // Registration has already happened outside this transaction. Fence only the
+  // durable client credential; a restriction racing DCR must not persist it.
+  return withOrganizationIntegrationAcquisition(
+    db,
+    acquisition,
+    [acquisition.integrationKey ?? "custom:mcp"],
+    async (tx) => {
+      if (storedClient) {
+        const replaced = await replaceIntegrationOAuthClientIfCurrent(tx, {
+          ...storeInput,
+          expectedClientId: storedClient.clientId,
+        });
+        if (replaced?.clientId === dcr.clientId) {
+          return dcr;
+        }
+        return await loadCompatibleDcrWinner(tx, settings, as, redirectUri, scopes);
+      }
+      const storedWinner = await storeIntegrationOAuthClient(tx, storeInput);
+      if (storedWinner.clientId === dcr.clientId) {
+        return dcr;
+      }
+      const winner = await loadIntegrationOAuthClient(tx, settings, as.issuer);
+      if (winner && storedDcrClientSatisfiesPolicy(winner, as, redirectUri, scopes)) {
+        return dcrRegistrationFromStored(winner);
+      }
+      if (winner) {
+        const replaced = await replaceIntegrationOAuthClientIfCurrent(tx, {
+          ...storeInput,
+          expectedClientId: winner.clientId,
+        });
+        if (replaced?.clientId === dcr.clientId) {
+          return dcr;
+        }
+      }
+      return await loadCompatibleDcrWinner(tx, settings, as, redirectUri, scopes);
+    },
+  );
 }
 
 function storedDcrClientSatisfiesPolicy(
@@ -1106,23 +1800,21 @@ function operatorClientEntryFor(
   candidates: string[],
 ): ReturnType<typeof parseIntegrationsOauthClientsJson>[string] | null {
   const normalizedCandidates = new Set(candidates.map(normalizedIssuerKey));
-  if (
-    candidates.some((candidate) => {
-      try {
-        const origin = new URL(candidate).origin;
-        return origin === SLACK_OAUTH_ORIGIN || origin === SLACK_MCP_ORIGIN;
-      } catch {
-        return false;
-      }
-    }) &&
-    settings.slackClientId?.trim() &&
-    settings.slackClientSecret?.trim()
-  ) {
-    return {
-      clientId: settings.slackClientId.trim(),
-      clientSecret: settings.slackClientSecret.trim(),
-      tokenEndpointAuthMethod: "client_secret_post",
-    };
+  const candidateOrigins = candidates.flatMap((candidate) => {
+    try {
+      return [new URL(candidate).origin];
+    } catch {
+      return [];
+    }
+  });
+  for (const entry of DEPLOYMENT_MANAGED_CLIENTS) {
+    if (!candidateOrigins.some((origin) => entry.issuerOrigins.includes(origin))) {
+      continue;
+    }
+    const resolved = entry.resolve(settings);
+    if (resolved) {
+      return resolved;
+    }
   }
   const configured = parseIntegrationsOauthClientsJson(settings.integrationsOauthClientsJson);
   const exactKeys = uniqueStrings(
@@ -1142,6 +1834,33 @@ function operatorClientEntryFor(
   return null;
 }
 
+/** Secret-free readiness for the exact registered client used by Gmail setup. */
+export function gmailOAuthClientConfigured(settings: Settings): boolean {
+  const entry = operatorClientEntryFor(settings, ["https://accounts.google.com"]);
+  return Boolean(
+    entry &&
+    isConfidentialOAuthClient({
+      ...entry,
+      tokenEndpointAuthMethod: tokenAuthMethod(
+        entry.tokenEndpointAuthMethod,
+        Boolean(entry.clientSecret),
+      ),
+    }),
+  );
+}
+
+function isConfidentialOAuthClient(client: {
+  clientId: string;
+  clientSecret?: string | undefined;
+  tokenEndpointAuthMethod: string;
+}): boolean {
+  return Boolean(
+    client.clientId.trim() &&
+    client.clientSecret?.trim() &&
+    ["client_secret_post", "client_secret_basic"].includes(client.tokenEndpointAuthMethod),
+  );
+}
+
 function normalizedIssuerKey(value: string): string {
   return value.replace(/\/+$/, "");
 }
@@ -1210,7 +1929,7 @@ async function existingOAuthConnectionForStart(
     subjectId: string;
     providerDomain: string;
     mcpUrl: string;
-    hostedSlackMcp: boolean;
+    connectionSelection: OAuthProviderProfile["connectionSelection"];
     exactMcpBinding: boolean;
     connectionId?: string | undefined;
     requestedOwnership?: ConnectionOwnership | undefined;
@@ -1247,7 +1966,7 @@ async function existingOAuthConnectionForStart(
       connection.providerDomain === input.providerDomain &&
       (!input.exactMcpBinding || connection.metadata.mcpUrl === input.mcpUrl),
   );
-  if (input.hostedSlackMcp && input.newConnectionOwnership === "personal") {
+  if (input.connectionSelection === "canonical_personal") {
     return selectCanonicalPersonalSlackConnection(matching);
   }
   return matching.find((connection) => connection.status === "active") ?? null;
@@ -1272,6 +1991,8 @@ export function buildAuthorizationUrl(input: {
   verifier: string;
   scopes: string[];
   resourceParameterSupported: boolean;
+  /** Profile-declared extra authorize parameters, applied last. */
+  extraParams?: Readonly<Record<string, string>> | undefined;
 }): string {
   const endpoint = oauthEndpointUrl(input.endpoint, input.settings, "OAuth authorization endpoint");
   const url = new URL(endpoint);
@@ -1280,23 +2001,63 @@ export function buildAuthorizationUrl(input: {
   url.searchParams.set("redirect_uri", input.redirectUri);
   url.searchParams.set("state", input.state);
   if (input.resourceParameterSupported) {
+    // Suppressing RFC 8707 is a profile fact (Google's endpoints reject the
+    // parameter); any provider-specific replacement parameters, such as
+    // Google's offline-consent options, are that profile's
+    // `extraAuthorizeParams` rather than behavior implied by the suppression.
     url.searchParams.set("resource", input.resource);
-  } else {
-    // Google's OAuth endpoints do not implement RFC 8707's `resource`
-    // parameter. Explicit offline consent is required to obtain the refresh
-    // token used by the durable connection broker.
-    url.searchParams.set("access_type", "offline");
-    url.searchParams.set("include_granted_scopes", "true");
-    url.searchParams.set("prompt", "consent");
   }
   url.searchParams.set("code_challenge_method", "S256");
   url.searchParams.set("code_challenge", pkceChallenge(input.verifier));
   if (input.scopes.length > 0) {
     url.searchParams.set("scope", input.scopes.join(" "));
   }
+  for (const [name, value] of Object.entries(input.extraParams ?? {})) {
+    // Defense in depth behind the schema/curation validation: an extra
+    // parameter can never displace a security parameter the client already
+    // set (state, PKCE, scope, resource, redirect_uri, ...).
+    if (!url.searchParams.has(name)) {
+      url.searchParams.set(name, value);
+    }
+  }
   return url.toString();
 }
 
+async function resolveMcpOAuthState(
+  db: Database,
+  settings: Settings,
+  state: string,
+  deadline: OAuthCallbackDeadline,
+): Promise<OAuthStatePayload> {
+  const reference = readSignedState(state, requireIntegrationsStateSecret(settings)) as Record<
+    string,
+    unknown
+  > | null;
+  if (reference?.kind !== "mcp_oauth_reference") {
+    // In-flight grants from the previous release remain valid for their
+    // normal ten-minute lifetime during a rolling deployment.
+    return readOAuthState(state, settings);
+  }
+  const accountId = requiredString(reference.accountId, "state.accountId");
+  const workspaceId = requiredString(reference.workspaceId, "state.workspaceId");
+  const id = requiredString(reference.id, "state.id");
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id)) {
+    throw new HTTPException(400, { message: "invalid OAuth state reference" });
+  }
+  const encrypted = await runCallbackDatabaseStage(deadline, "state_verify", db, (scopedDb) =>
+    loadIntegrationOAuthPendingState(scopedDb, { accountId, workspaceId, id }),
+  );
+  if (!encrypted) {
+    throw new HTTPException(400, { message: "invalid or expired OAuth state" });
+  }
+  const fullState = decryptEnvironmentValue(requireEnvironmentEncryption(settings), encrypted);
+  const resolved = readOAuthState(fullState, settings);
+  if (resolved.accountId !== accountId || resolved.workspaceId !== workspaceId) {
+    throw new HTTPException(400, { message: "OAuth state reference mismatch" });
+  }
+  return resolved;
+}
+
 function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
   const payload = readSignedState(state, requireIntegrationsStateSecret(settings)) as Record<
     string,
@@ -1305,19 +2066,76 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
   if (!payload) {
     throw new HTTPException(400, { message: "invalid or expired OAuth state" });
   }
+  if (
+    payload.integrationKey !== undefined &&
+    payload.integrationKey !== "gmail" &&
+    payload.integrationKey !== "slack-personal"
+  ) {
+    throw new HTTPException(400, { message: "invalid OAuth integration identity" });
+  }
   const nowSeconds = Math.floor(Date.now() / 1000);
   const iat = numberValue(payload.iat);
   if (iat === undefined || nowSeconds - iat > oauthStateTtlMs / 1000 || nowSeconds < iat) {
     throw new HTTPException(400, { message: "invalid or expired OAuth state" });
   }
   const resource = requiredString(payload.resource, "state.resource");
+  const encodedDiscoveryMode = stringValue(payload.discoveryMode);
+  const discoveryMode = discoveryModeValue(encodedDiscoveryMode);
+  const discoveryMetadataSha256 = stringValue(payload.discoveryMetadataSha256);
+  if (
+    encodedDiscoveryMode &&
+    (!discoveryMetadataSha256 || !/^[0-9a-f]{64}$/.test(discoveryMetadataSha256))
+  ) {
+    throw new HTTPException(400, { message: "invalid OAuth discovery state" });
+  }
+  const protectedResourceMetadataUrl = stringValue(payload.protectedResourceMetadataUrl);
+  const authorizationServerMetadataUrl = stringValue(payload.authorizationServerMetadataUrl);
+  if (
+    encodedDiscoveryMode &&
+    (!authorizationServerMetadataUrl ||
+      (discoveryMode === "rfc9728_protected_resource" && !protectedResourceMetadataUrl) ||
+      (discoveryMode !== "rfc9728_protected_resource" && protectedResourceMetadataUrl))
+  ) {
+    throw new HTTPException(400, { message: "invalid OAuth discovery provenance state" });
+  }
+  const resourceParameterSupported = payload.resourceParameterSupported !== false;
+  if (discoveryMode === "legacy_2025_03_26_metadata" && resourceParameterSupported) {
+    throw new HTTPException(400, { message: "invalid legacy OAuth resource parameter state" });
+  }
+  const ownership = connectionOwnership(payload.ownership);
+  if (!ownership) {
+    throw new HTTPException(400, {
+      message: "missing or invalid OAuth ownership; restart connection setup",
+    });
+  }
   const parsed = {
     accountId: requiredString(payload.accountId, "state.accountId"),
     workspaceId: requiredString(payload.workspaceId, "state.workspaceId"),
     subjectId: requiredString(payload.subjectId, "state.subjectId"),
-    // OAuth states minted before ownership was explicit were always personal.
-    // Preserve that meaning for in-flight reconnects during a rolling deploy.
-    ownership: connectionOwnership(payload.ownership) ?? "personal",
+    ...(stringValue(payload.encryptedExternalContinuation)
+      ? {
+          externalContinuation: ExternalActorContinuation.parse(
+            JSON.parse(
+              decryptEnvironmentValue(
+                requireEnvironmentEncryption(settings),
+                requiredString(payload.encryptedExternalContinuation, "state.externalContinuation"),
+              ),
+            ),
+          ),
+        }
+      : {}),
+    ...(payload.returnUrl !== undefined
+      ? { returnUrl: exactExternalReturnUrl(requiredString(payload.returnUrl, "state.returnUrl")) }
+      : {}),
+    ...(stringValue(payload.connectAttemptId)
+      ? { connectAttemptId: requiredString(payload.connectAttemptId, "state.connectAttemptId") }
+      : {}),
+    ownership,
+    // Absent on a legacy state, which therefore cannot land a personal owner.
+    personalOwnerVerified: personalOwnerVerifiedInState(payload),
+    ...(payload.integrationKey
+      ? { integrationKey: payload.integrationKey as "gmail" | "slack-personal" }
+      : {}),
     providerDomain: requiredString(payload.providerDomain, "state.providerDomain"),
     mcpUrl: stringValue(payload.mcpUrl) ?? resource,
     resource,
@@ -1343,11 +2161,31 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
       settings,
       "OAuth issuer",
     ),
+    discoveryMode,
+    ...(discoveryMetadataSha256 ? { discoveryMetadataSha256 } : {}),
+    ...(protectedResourceMetadataUrl
+      ? {
+          protectedResourceMetadataUrl: oauthEndpointUrl(
+            protectedResourceMetadataUrl,
+            settings,
+            "OAuth protected resource metadata",
+          ),
+        }
+      : {}),
+    ...(authorizationServerMetadataUrl
+      ? {
+          authorizationServerMetadataUrl: oauthEndpointUrl(
+            authorizationServerMetadataUrl,
+            settings,
+            "OAuth authorization server metadata",
+          ),
+        }
+      : {}),
     clientRegistrationMethod: registrationMethod(payload.clientRegistrationMethod),
     tokenEndpointAuthMethod: tokenAuthMethod(stringValue(payload.tokenEndpointAuthMethod), false),
     // States minted before provider-specific compatibility was introduced used
     // the RFC 8707 resource parameter.
-    resourceParameterSupported: payload.resourceParameterSupported !== false,
+    resourceParameterSupported,
     ...(stringValue(payload.encryptedClientSecret)
       ? { encryptedClientSecret: stringValue(payload.encryptedClientSecret)! }
       : {}),
@@ -1357,16 +2195,72 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
   };
   const connectionId = stringValue(payload.connectionId);
   const connectionVersion = numberValue(payload.connectionVersion);
+  assertProfileOwnership(builtInOAuthProfileFor(parsed), parsed.ownership);
   if (Boolean(connectionId) !== Boolean(connectionVersion)) {
     throw new HTTPException(400, { message: "invalid OAuth reconnect state" });
   }
+  if (
+    parsed.discoveryMode === "legacy_2025_03_26_metadata" &&
+    (normalizedIssuerKey(parsed.authorizationServer) !== normalizedIssuerKey(parsed.issuer) ||
+      new URL(parsed.resource).origin !== new URL(parsed.issuer).origin)
+  ) {
+    throw new HTTPException(400, { message: "invalid OAuth discovery binding state" });
+  }
+  if (parsed.discoveryMode === "provider_oauth_metadata") {
+    const profile = builtInOAuthProfileFor(parsed);
+    const discovery = profile?.providerOAuthDiscovery;
+    if (
+      !discovery ||
+      parsed.mcpUrl !== profile?.requireExactMcpUrl?.url ||
+      parsed.resource !== parsed.mcpUrl ||
+      parsed.providerDomain !== profile?.postDiscoveryProviderDomain?.domain ||
+      normalizedIssuerKey(parsed.issuer) !== discovery.issuer ||
+      parsed.authorizationServer !== discovery.issuer ||
+      parsed.authorizationServerMetadataUrl !== discovery.metadataUrl ||
+      parsed.resourceParameterSupported
+    ) {
+      throw new HTTPException(400, { message: "invalid provider OAuth discovery binding state" });
+    }
+    assertDiscoveredAuthorizationServer(
+      settings,
+      { ...parsed, authorizationEndpoint: discovery.issuer },
+      profile!,
+      parsed.providerDomain,
+    );
+  }
   return {
     ...parsed,
+    ...(parsed.discoveryMode === "provider_oauth_metadata"
+      ? { issuer: normalizedIssuerKey(parsed.issuer) }
+      : {}),
     ...(connectionId ? { connectionId } : {}),
     ...(connectionVersion !== undefined ? { connectionVersion } : {}),
   };
 }
 
+function discoveryModeValue(value: string | undefined): OAuthDiscoveryMode {
+  if (!value) {
+    // Every state minted before discovery modes existed used RFC 9728 PRM.
+    return "rfc9728_protected_resource";
+  }
+  if (
+    value === "rfc9728_protected_resource" ||
+    value === "legacy_2025_03_26_metadata" ||
+    value === "provider_oauth_metadata"
+  ) {
+    return value;
+  }
+  throw new HTTPException(400, { message: "invalid OAuth discovery mode state" });
+}
+
+function assertProfileOwnership(
+  profile: OAuthProviderProfile | null,
+  ownership: ConnectionOwnership,
+): void {
+  if (profile?.requiredOwnership && ownership !== profile.requiredOwnership.ownership)
+    throw new HTTPException(422, { message: profile.requiredOwnership.message });
+}
+
 function connectionOwnership(value: unknown): ConnectionOwnership | undefined {
   return value === "workspace" || value === "personal" ? value : undefined;
 }
@@ -1562,6 +2456,9 @@ function logOAuthStartFailure(
 function oauthStartFailureReason(error: unknown): string {
   if (error instanceof RequestDeadlineError) return "timeout";
   if (error instanceof DestinationPolicyError) return error.reason;
+  if (error instanceof OAuthMetadataUpstreamError) {
+    return `upstream_http_${error.upstreamStatus}`;
+  }
   if (error instanceof HTTPException) return `http_${error.status}`;
   if (error instanceof SyntaxError) return "invalid_response";
   return "request_failed";
@@ -1605,15 +2502,29 @@ function isDatabaseStatementTimeout(error: unknown): boolean {
 
 function oauthStartApiError(error: OAuthStartStageError): ApiHttpError {
   const timeout = error.reason === "timeout";
-  const status = timeout ? 408 : error.cause instanceof HTTPException ? error.cause.status : 422;
+  const metadataUpstream = error.cause instanceof OAuthMetadataUpstreamError ? error.cause : null;
+  const status = timeout
+    ? 408
+    : metadataUpstream
+      ? 502
+      : error.cause instanceof HTTPException
+        ? error.cause.status
+        : 422;
   return new ApiHttpError(status, {
     code: timeout || status >= 500 ? "upstream_unavailable" : "validation_failed",
-    retryable: timeout || status === 429 || status >= 500,
+    retryable:
+      timeout ||
+      status === 429 ||
+      (metadataUpstream
+        ? metadataUpstream.upstreamStatus === 429 || metadataUpstream.upstreamStatus >= 500
+        : status >= 500),
     message: timeout
       ? oauthStartTimeoutMessage(error.stage)
-      : error.cause instanceof HTTPException
-        ? error.cause.message
-        : `Connection setup failed during ${oauthStartStageLabel(error.stage)}.`,
+      : metadataUpstream
+        ? `OAuth provider returned HTTP ${metadataUpstream.upstreamStatus} during ${oauthStartStageLabel(error.stage)}.`
+        : error.cause instanceof HTTPException
+          ? error.cause.message
+          : `Connection setup failed during ${oauthStartStageLabel(error.stage)}.`,
     details: {
       oauthStage: error.stage,
       oauthReason: error.reason,
@@ -1637,6 +2548,8 @@ function oauthStartStageLabel(stage: OAuthStartStage): string {
       return "authorization-server discovery";
     case "client_registration":
       return "OAuth client registration";
+    case "state_persist":
+      return "OAuth state persistence";
   }
 }
 
@@ -1762,11 +2675,44 @@ async function verifyMcpToolsListNonFatal(
     | { status: "ok"; checkedAt: string; toolCount: number }
     | { status: "failed"; checkedAt: string; reason: string };
   tools?: Array<{ name: string; description?: string }>;
+  providerIdentity?: Record<string, string>;
+  connectionStatus?: "needs_reauth";
 }> {
+  let grantRejected = false;
   try {
-    const tools = await deadline.run("tools_list", (signal) =>
-      verifyMcpToolsList(settings, state.mcpUrl, token, signal),
-    );
+    const profile = builtInOAuthProfileFor(state);
+    const local = profile?.localToolVerification;
+    let providerIdentity: Record<string, string> | undefined;
+    const tools = await deadline.run("tools_list", async (signal) => {
+      if (!local || state.mcpUrl !== profile?.requireExactMcpUrl?.url) {
+        return verifyMcpToolsList(settings, state.mcpUrl, token, signal);
+      }
+      const response = await fetchOAuth(local.url, settings, {
+        method: local.method ?? "POST",
+        signal,
+        headers: {
+          authorization: `${normalizeBearerScheme(token.tokenType)} ${token.accessToken}`,
+        },
+      });
+      if (!response.ok) {
+        await cancelResponseBody(response);
+        throw new Error("Connector token verification failed");
+      }
+      const payload = await readResponseJsonBounded<Record<string, unknown>>(
+        response,
+        OAUTH_MAX_RESPONSE_BYTES,
+        "Connector token verification",
+        { signal },
+      );
+      grantRejected = local.isRejectedGrant?.(payload) ?? false;
+      providerIdentity = local.validateIdentity(payload);
+      const verifiedTools = local.toolsForScopes(
+        grantedScopes(token.scopeText, state.authorizeScopes, profile),
+      );
+      if (local.required && verifiedTools.length === 0)
+        throw new Error("Connector verification did not report an authorized tool scope");
+      return verifiedTools;
+    });
     return {
       metadata: {
         status: "ok",
@@ -1774,6 +2720,7 @@ async function verifyMcpToolsListNonFatal(
         toolCount: tools.length,
       },
       tools,
+      ...(providerIdentity ? { providerIdentity } : {}),
     };
   } catch (error) {
     const staged =
@@ -1783,6 +2730,7 @@ async function verifyMcpToolsListNonFatal(
     if (staged.reason === "timeout" && deadline.signal.aborted) {
       throw staged;
     }
+    if (builtInOAuthProfileFor(state)?.localToolVerification?.required) throw staged;
     logOAuthVerificationWarning(observability, staged, state);
     return {
       metadata: {
@@ -1790,6 +2738,7 @@ async function verifyMcpToolsListNonFatal(
         checkedAt: new Date().toISOString(),
         reason: staged.reason,
       },
+      ...(grantRejected ? { connectionStatus: "needs_reauth" as const } : {}),
     };
   }
 }
@@ -1836,7 +2785,7 @@ function callbackReturnPath(
   // Defense in depth: a `//host` pathname becomes a protocol-relative absolute
   // Location — an open redirect from the unauthenticated callback.
   if (url.pathname.startsWith("//")) {
-    const fallback = new URL("/integrations", "https://opengeni.local");
+    const fallback = new URL(INTEGRATIONS_FALLBACK_PATH, "https://opengeni.local");
     fallback.search = url.search;
     return `${fallback.pathname}${fallback.search}`;
   }
@@ -1892,48 +2841,6 @@ function oauthEndpointUrl(rawUrl: string, settings: Settings, label: string): st
   }
 }
 
-function safeReturnPath(value: string): string {
-  if (!value.startsWith("/") || value.startsWith("//")) {
-    throw new HTTPException(400, {
-      message: "OAuth returnPath must be a relative path",
-    });
-  }
-  const parsed = new URL(value, "https://opengeni.local");
-  // `..` segments can normalize back into a `//host` prefix, which browsers
-  // resolve as a protocol-relative absolute URL. Reject the NORMALIZED path.
-  if (parsed.origin !== "https://opengeni.local" || parsed.pathname.startsWith("//")) {
-    throw new HTTPException(400, {
-      message: "OAuth returnPath must be a relative path",
-    });
-  }
-  return `${parsed.pathname}${parsed.search}${parsed.hash}`;
-}
-
-async function fetchJsonObject(
-  url: string,
-  settings: Settings,
-  signal?: AbortSignal,
-): Promise<Record<string, unknown>> {
-  const response = await fetchOAuth(url, settings, {
-    headers: { accept: "application/json" },
-    ...(signal ? { signal } : {}),
-  });
-  if (!response.ok) {
-    await cancelResponseBody(response);
-    throw new Error(`HTTP ${response.status}`);
-  }
-  const payload = await readResponseJsonBounded<unknown>(
-    response,
-    OAUTH_MAX_RESPONSE_BYTES,
-    "OAuth metadata response",
-    { ...(signal ? { signal } : {}) },
-  );
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
-    throw new Error("metadata response was not a JSON object");
-  }
-  return payload as Record<string, unknown>;
-}
-
 async function fetchOAuth(
   rawUrl: string,
   settings: Settings,
@@ -2006,41 +2913,6 @@ async function cancelResponseBody(response: Response): Promise<void> {
   await response.body?.cancel().catch(() => undefined);
 }
 
-function parseWwwAuthenticate(header: string | null): WwwAuthenticateChallenge {
-  if (!header) {
-    return {};
-  }
-  const bearerIndex = header.toLowerCase().indexOf("bearer");
-  if (bearerIndex < 0) {
-    return {};
-  }
-  const paramsText = header.slice(bearerIndex + "bearer".length);
-  const params: Record<string, string> = {};
-  const re = /([a-zA-Z_][a-zA-Z0-9_-]*)\s*=\s*("(?:[^"\\]|\\.)*"|[^,\s]+)/g;
-  let match: RegExpExecArray | null;
-  while ((match = re.exec(paramsText)) !== null) {
-    const raw = match[2]!;
-    params[match[1]!.toLowerCase()] = raw.startsWith('"')
-      ? raw.slice(1, -1).replace(/\\"/g, '"')
-      : raw;
-  }
-  return {
-    ...(params.resource_metadata ? { resourceMetadata: params.resource_metadata } : {}),
-    ...(params.scope ? { scope: params.scope.split(/\s+/).filter(Boolean) } : {}),
-    ...(params.error ? { error: params.error } : {}),
-  };
-}
-
-function wellKnownCandidates(rawUrl: string, name: string): string[] {
-  const url = new URL(rawUrl);
-  const path = url.pathname.replace(/^\/+|\/+$/g, "");
-  return uniqueStrings([
-    `${url.origin}/.well-known/${name}${path ? `/${path}` : ""}`,
-    `${url.origin}${path ? `/${path}` : ""}/.well-known/${name}`,
-    `${url.origin}/.well-known/${name}`,
-  ]);
-}
-
 function chooseAuthorizeScopes(
   requested: string[] | undefined,
   challenged: string[] | undefined,
@@ -2060,13 +2932,38 @@ export function chooseMcpAuthorizeScopes(input: {
   requested: string[] | undefined;
   challenged: string[] | undefined;
   supported: string[];
+  authorizationServerScopesSupported?: string[];
 }): string[] {
-  return input.mcpUrl === OFFICIAL_GMAIL_MCP_URL
-    ? [...OFFICIAL_GMAIL_MCP_SCOPES]
-    : chooseAuthorizeScopes(input.requested, input.challenged, input.supported);
+  const profile = builtInOAuthProfileFor({ mcpUrl: input.mcpUrl }) ?? DEFAULT_OAUTH_PROFILE;
+  return chooseProfileAuthorizeScopes(profile, input);
 }
 
-function grantedScopes(scopeText: string | undefined, fallback: string[]): string[] {
+function chooseProfileAuthorizeScopes(
+  profile: OAuthProviderProfile,
+  input: {
+    requested: string[] | undefined;
+    challenged: string[] | undefined;
+    supported: string[];
+    authorizationServerScopesSupported?: string[];
+  },
+): string[] {
+  // Reviewed profiles keep their exact scope contract. A generic long-running
+  // connector also needs the AS-advertised refresh grant: the MCP resource's
+  // challenge often advertises only its resource permission (e.g. mcp:use).
+  if (profile.requestedScopes) return [...profile.requestedScopes];
+  const scopes = chooseAuthorizeScopes(input.requested, input.challenged, input.supported);
+  return input.authorizationServerScopesSupported?.includes("offline_access")
+    ? uniqueStrings([...scopes, "offline_access"])
+    : scopes;
+}
+
+function grantedScopes(
+  scopeText: string | undefined,
+  fallback: string[],
+  profile?: OAuthProviderProfile | null,
+): string[] {
+  if (profile?.reportedScopesRequired && !scopeText) return [];
+  if (profile?.normalizeGrantedScopes) return profile.normalizeGrantedScopes(scopeText ?? fallback);
   if (scopeText) {
     return uniqueStrings(scopeText.split(/\s+/).filter(Boolean));
   }