@opengeni/api-router 0.30.3 → 2.2.0-canary.0

package/src/integrations/oauth-client.ts

@@ -3,7 +3,6 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 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,
@@ -17,6 +16,7 @@ import {
   decryptEnvironmentValue,
   encryptEnvironmentValue,
   getConnectionMetadata,
+  getGlobalCatalogOAuthProfile,
   getWorkspaceGrant,
   listConnectionsMetadata,
   loadIntegrationOAuthClient,
@@ -40,21 +40,37 @@ import {
 import { Buffer } from "node:buffer";
 import { createHash, randomBytes } 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 {
+  DEFAULT_OAUTH_PROFILE,
+  DEPLOYMENT_MANAGED_CLIENTS,
+  builtInOAuthProfileByKey,
+  assertAuthorizationServerNotReserved,
+  assertAuthorizationServerPins,
+  assertOwnershipAllowed,
+  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";
+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 = {
@@ -69,6 +85,12 @@ export type OAuthStartContext = {
   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;
 };
@@ -116,6 +138,8 @@ type OAuthStatePayload = {
   workspaceId: string;
   subjectId: string;
   ownership: ConnectionOwnership;
+  /** Signed proof that a live managed human authorized personal ownership. */
+  personalOwnerVerified: boolean;
   providerDomain: string;
   mcpUrl: string;
   resource: string;
@@ -305,15 +329,29 @@ async function startMcpOAuthWithinDeadline(
 ): Promise<OAuthStartResponse> {
   const { db, settings } = deps;
   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 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);
+  // Personal-only resources default an omitted ownership to personal, matching
+  // the fence that existed before #1240; an explicit non-personal value is the
+  // only thing rejected. Everything else defaults to workspace as before.
+  const requestedOwnership: ConnectionOwnership =
+    context.payload.ownership ?? defaultOwnershipFor(profile);
+  assertOwnershipAllowed(profile, requestedOwnership);
   const returnPath = safeReturnPath(context.payload.returnPath ?? "/integrations");
   const baseUrl = integrationBaseUrl(settings.publicBaseUrl, context.requestUrl);
   const redirectUri = `${baseUrl}/v1/integrations/oauth/callback`;
@@ -324,8 +362,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,27 +375,25 @@ async function startMcpOAuthWithinDeadline(
   const ownership = existing
     ? ownershipForConnection(existing.subjectId, context.subjectId)
     : requestedOwnership;
+  // A reconnect of a legacy row must not renew an ownership the profile no
+  // longer allows (e.g. shared authority over one human's hosted-Slack grant).
+  assertOwnershipAllowed(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. For a personal-only
+  // profile (Gmail, hosted Slack MCP) this refuses the whole flow rather than
+  // silently downgrading to the workspace ownership those profiles forbid.
+  assertConnectionOwnershipAllowedForPrincipal(ownership, context.personalOwnershipAllowed);
 
   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;
+  assertDiscoveredAuthorizationServer(settings, discovery.as, profile, providerDomain);
+  const resourceParameterSupported = profile.sendResourceParameter;
   const resource = discovery.prm.resource ? canonicalOAuthResource(discovery.prm.resource) : mcpUrl;
   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,
@@ -371,6 +407,7 @@ async function startMcpOAuthWithinDeadline(
       redirectUri,
       authorizeScopes,
       context.payload.oauthClient,
+      profile,
       signal,
     ),
   );
@@ -380,11 +417,14 @@ async function startMcpOAuthWithinDeadline(
     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,
     providerDomain,
     mcpUrl,
     resource,
-    requestedScopes: officialGmailResource
-      ? [...OFFICIAL_GMAIL_MCP_SCOPES]
+    requestedScopes: profile.requestedScopes
+      ? [...profile.requestedScopes]
       : uniqueStrings(context.payload.requestedScopes ?? []),
     authorizeScopes,
     encryptedPkceVerifier: encryptEnvironmentValue(key, verifier),
@@ -413,6 +453,7 @@ async function startMcpOAuthWithinDeadline(
     verifier,
     scopes: authorizeScopes,
     resourceParameterSupported,
+    ...(profile.extraAuthorizeParams ? { extraParams: profile.extraAuthorizeParams } : {}),
   });
   return OAuthStartResponse.parse({
     state,
@@ -421,18 +462,94 @@ async function startMcpOAuthWithinDeadline(
   });
 }
 
+/** Ownership fence for the official Gmail profile, keyed by exact MCP URL. */
 export function assertOfficialGmailPersonalOwnership(
   mcpUrl: string,
   ownership: ConnectionOwnership,
 ): 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",
-    });
+  const profile = builtInOAuthProfileFor({ mcpUrl });
+  if (profile?.key === "official-gmail") {
+    assertOwnershipAllowed(profile, ownership);
+  }
+}
+
+/**
+ * Slack's hosted MCP issues user tokens only. Sharing one human's grant as
+ * workspace authority made every shared agent act as a named employee; the
+ * OpenGeni workspace bot owns shared Slack access instead (bot-token search
+ * covers public channels, files, and users).
+ */
+export function assertHostedSlackMcpPersonalOwnership(
+  hostedSlackMcp: boolean,
+  ownership: ConnectionOwnership,
+): void {
+  if (hostedSlackMcp) {
+    assertOwnershipAllowed(builtInOAuthProfileByKey("hosted-slack-mcp"), ownership);
+  }
+}
+
+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,
+  profile: OAuthProviderProfile,
+): void {
+  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: {
@@ -479,8 +596,27 @@ async function completeMcpOAuthCallbackWithinDeadline(
   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);
+    // let a still-valid callback persist an ownership the target's profile no
+    // longer allows (workspace-owned Gmail or hosted Slack, for example).
+    const builtInCallbackProfile = builtInOAuthProfileFor({
+      mcpUrl: state.mcpUrl,
+      providerDomain: state.providerDomain,
+    });
+    if (builtInCallbackProfile) {
+      assertOwnershipAllowed(builtInCallbackProfile, state.ownership);
+    }
+    // Only a managed human may own a personal Connection. This callback has no
+    // live principal, so it enforces the signed start-time decision; a state
+    // minted before that fence existed carries no claim and is refused, which
+    // closes the in-flight window across a rolling deploy. The legacy
+    // `?? "personal"` decode above therefore cannot land a machine-owned row.
+    if (!personalOwnerStateAccepted(state)) {
+      throw new OAuthCallbackStageError(
+        "state_verify",
+        "state_invalid",
+        new HTTPException(422, { message: PERSONAL_CONNECTION_PRINCIPAL_MESSAGE }),
+      );
+    }
     if (!input.code) {
       return {
         redirectTo: callbackReturnPath(state.returnPath, "error", {
@@ -495,6 +631,18 @@ async function completeMcpOAuthCallbackWithinDeadline(
       db,
       async (scopedDb) => {
         await requireOAuthCallbackGrant(scopedDb, state!);
+        if (!builtInCallbackProfile) {
+          // Catalog-declared ownership fences get the same rolling-update
+          // treatment as the built-in ones.
+          const raw = await getGlobalCatalogOAuthProfile(
+            scopedDb,
+            state!.workspaceId,
+            catalogMcpUrlKey(state!.mcpUrl),
+          );
+          if (raw !== null) {
+            assertOwnershipAllowed(oauthProfileFromCatalog(state!.mcpUrl, raw), state!.ownership);
+          }
+        }
         return await consumeIntegrationOAuthStateNonce(scopedDb, {
           accountId: state!.accountId,
           workspaceId: state!.workspaceId,
@@ -656,68 +804,19 @@ async function requireOAuthCallbackGrant(db: Database, state: OAuthStatePayload)
   }
 }
 
-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 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",
-    });
+  const pins = builtInOAuthProfileByKey("hosted-slack-mcp").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,
-  );
-}
-
+/** The official-Gmail profile's origin pins, kept exported for its tests. */
 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",
-    });
+  const pins = builtInOAuthProfileByKey("official-gmail").authorizationServer;
+  if (pins) {
+    assertAuthorizationServerPins(as, pins);
   }
 }
 
@@ -884,16 +983,15 @@ async function registerOAuthClient(
   redirectUri: string,
   scopes: string[],
   manual: OAuthStartRequest["oauthClient"],
+  profile: OAuthProviderProfile,
   signal: AbortSignal,
 ): 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,
@@ -903,7 +1001,7 @@ async function registerOAuthClient(
       signal,
     );
   }
-  if (as.clientIdMetadataDocumentSupported) {
+  if (selfRegistration === "cimd") {
     return {
       method: "cimd",
       issuer: as.issuer,
@@ -928,10 +1026,22 @@ async function registerOAuthClient(
   return await getOrCreateDynamicClientRegistration(db, settings, as, redirectUri, scopes, signal);
 }
 
-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(
@@ -1106,23 +1216,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(
@@ -1210,7 +1318,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 +1355,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 +1380,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,20 +1390,25 @@ 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();
 }
 
@@ -1318,6 +1433,8 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
     // 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",
+    // Absent on a legacy state, which therefore cannot land a personal owner.
+    personalOwnerVerified: personalOwnerVerifiedInState(payload),
     providerDomain: requiredString(payload.providerDomain, "state.providerDomain"),
     mcpUrl: stringValue(payload.mcpUrl) ?? resource,
     resource,
@@ -2061,8 +2178,20 @@ export function chooseMcpAuthorizeScopes(input: {
   challenged: string[] | undefined;
   supported: string[];
 }): string[] {
-  return input.mcpUrl === OFFICIAL_GMAIL_MCP_URL
-    ? [...OFFICIAL_GMAIL_MCP_SCOPES]
+  const profile = builtInOAuthProfileFor({ mcpUrl: input.mcpUrl }) ?? DEFAULT_OAUTH_PROFILE;
+  return chooseProfileAuthorizeScopes(profile, input);
+}
+
+function chooseProfileAuthorizeScopes(
+  profile: OAuthProviderProfile,
+  input: {
+    requested: string[] | undefined;
+    challenged: string[] | undefined;
+    supported: string[];
+  },
+): string[] {
+  return profile.requestedScopes
+    ? [...profile.requestedScopes]
     : chooseAuthorizeScopes(input.requested, input.challenged, input.supported);
 }