@opengeni/api-router 3.0.1 → 3.0.2-canary.38894290271001

package/src/integrations/oauth-client.ts

@@ -1,15 +1,24 @@
 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 {
+  findIntegrationsOauthClient,
+  parseIntegrationsOauthClientsJson,
+  type Settings,
+} from "@opengeni/config";
 import {
   OAuthStartResponse,
   selectCanonicalPersonalSlackConnection,
   type ConnectionOwnership,
   type OAuthStartRequest,
 } from "@opengeni/contracts";
-import { requireEnvironmentEncryption } from "@opengeni/core";
+import { requireEnvironmentEncryption, integrationKeyForConnectProvider } from "@opengeni/core";
 import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import type { Observability } from "@opengeni/observability";
 import {
@@ -24,14 +33,16 @@ import {
   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,
@@ -50,8 +61,9 @@ import {
   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 { observeOAuthStart } from "../integration-connect-metrics";
 import {
   assertConnectionOwnershipAllowedForPrincipal,
   personalOwnerStateAccepted,
@@ -63,11 +75,11 @@ 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,
-  assertOwnershipAllowed,
   builtInOAuthProfileFor,
   catalogMcpUrlKey,
   defaultOwnershipFor,
@@ -79,6 +91,64 @@ import {
 import { canonicalProviderDomain } from "./provider-domain";
 
 export const oauthStateTtlMs = 10 * 60 * 1000;
+
+/**
+ * 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,
@@ -95,6 +165,8 @@ 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;
@@ -118,6 +190,7 @@ export type OAuthCallbackResult = {
 type WwwAuthenticateChallenge = McpOAuthChallenge;
 type ProtectedResourceMetadata = McpProtectedResourceMetadata;
 type AuthorizationServerMetadata = McpAuthorizationServerMetadata;
+type OAuthDiscoveryMode = McpOAuthDiscoveryMode | "provider_oauth_metadata";
 
 type OAuthClientRegistration = {
   method: "operator" | "manual" | "cimd" | "dcr";
@@ -129,6 +202,7 @@ type OAuthClientRegistration = {
 };
 
 type OAuthStatePayload = {
+  integrationKey?: "gmail" | "slack-personal";
   connectAttemptId?: string;
   externalContinuation?: ExternalActorContinuation;
   returnUrl?: string;
@@ -148,7 +222,7 @@ type OAuthStatePayload = {
   tokenEndpoint: string;
   authorizationServer: string;
   issuer: string;
-  discoveryMode: McpOAuthDiscoveryMode;
+  discoveryMode: OAuthDiscoveryMode;
   discoveryMetadataSha256?: string;
   protectedResourceMetadataUrl?: string;
   authorizationServerMetadataUrl?: string;
@@ -188,7 +262,8 @@ export type OAuthStartStage =
   | "mcp_challenge"
   | "protected_resource_metadata"
   | "authorization_server_metadata"
-  | "client_registration";
+  | "client_registration"
+  | "state_persist";
 
 class OAuthStartStageError extends Error {
   constructor(
@@ -312,19 +387,107 @@ 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);
+    const started = await startMcpOAuthWithinDeadline(deps, context, deadline);
+    observeOAuthStart(deps.observability, { flow: "mcp_oauth", outcome: "success" });
+    return started;
   } catch (error) {
     const staged =
       error instanceof OAuthStartStageError
         ? error
         : new OAuthStartStageError("connection_lookup", oauthStartFailureReason(error), error);
     logOAuthStartFailure(deps.observability, staged);
+    observeOAuthStart(deps.observability, {
+      flow: "mcp_oauth",
+      outcome: "failure",
+      stage: staged.stage,
+      reason: staged.reason,
+    });
     throw oauthStartApiError(staged);
   } finally {
     deadline.dispose();
@@ -375,13 +538,13 @@ async function startMcpOAuthWithinDeadline(
     })) ??
     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.
+  // Catalog defaults are setup preferences; an explicit ownership always wins.
   const requestedOwnership: ConnectionOwnership =
     context.payload.ownership ?? defaultOwnershipFor(profile);
-  assertOwnershipAllowed(profile, requestedOwnership);
-  const returnPath = safeReturnPath(context.payload.returnPath ?? "/integrations");
+  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`;
@@ -394,6 +557,7 @@ async function startMcpOAuthWithinDeadline(
       connectionSelection: profile.connectionSelection,
       exactMcpBinding: profile.exactMcpBinding,
       connectionId: context.payload.connectionId,
+      newAccount: context.payload.newAccount === true,
       requestedOwnership: context.payload.ownership,
       newConnectionOwnership: requestedOwnership,
     }),
@@ -404,18 +568,17 @@ 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);
+  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. 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.
+  // subject that holds an active organization membership. An explicit personal
+  // choice is never silently downgraded to workspace ownership.
   assertConnectionOwnershipAllowedForPrincipal(ownership, context.personalOwnershipAllowed);
 
-  const discovery = await discoverMcpOAuth(mcpUrl, settings, deadline);
+  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;
@@ -427,6 +590,7 @@ async function startMcpOAuthWithinDeadline(
     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(
@@ -439,10 +603,26 @@ async function startMcpOAuthWithinDeadline(
       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,
@@ -491,6 +671,28 @@ async function startMcpOAuthWithinDeadline(
     returnPath,
     ...(existing ? { connectionId: existing.id, connectionVersion: existing.version } : {}),
   });
+  const expiresAt = new Date(Date.now() + oauthStateTtlMs);
+  // Providers cap `state` length (Stripe at 1024 characters), so only a short
+  // signed reference leaves; the full context waits encrypted at rest.
+  const stateId = randomUUID();
+  const 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,
@@ -506,36 +708,10 @@ async function startMcpOAuthWithinDeadline(
   return OAuthStartResponse.parse({
     state,
     authorizationUrl,
-    expiresAt: new Date(Date.now() + oauthStateTtlMs).toISOString(),
+    expiresAt: expiresAt.toISOString(),
   });
 }
 
-/** Ownership fence for the official Gmail profile, keyed by exact MCP URL. */
-export function assertOfficialGmailPersonalOwnership(
-  mcpUrl: string,
-  ownership: ConnectionOwnership,
-): void {
-  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";
 }
@@ -603,6 +779,8 @@ export async function completeMcpOAuthCallback(
   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> {
@@ -621,12 +799,14 @@ 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(
@@ -636,18 +816,29 @@ 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);
+    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) ||
+        (!["mcp-oauth", "slack-personal"].includes(stored.attempt.providerId) &&
+          !gmailAttemptMatches) ||
         stored.attempt.ownership !== state.ownership ||
         stored.returnUrl !== state.returnUrl
       )
@@ -657,29 +848,23 @@ async function completeMcpOAuthCallbackWithinDeadline(
         operationId: `oauth:${state.nonce}`,
         inputDigest: createHash("sha256").update(input.state).digest("hex"),
       };
-      const claim = await claimConnectOperation(db, state, {
-        ...connectOperation,
-        expectedRevision: stored.attempt.revision,
-        authorize: (tx, _attempt, origin) =>
-          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
-      });
+      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 };
     }
-    // Fence state minted by an older deployment too: a rolling update must not
-    // 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.
+    // The callback enforces the signed start-time principal decision.
+    // Workspace ownership requires no personal-owner claim.
     if (!personalOwnerStateAccepted(state)) {
       throw new OAuthCallbackStageError(
         "state_verify",
@@ -687,7 +872,11 @@ async function completeMcpOAuthCallbackWithinDeadline(
         new HTTPException(422, { message: PERSONAL_CONNECTION_PRINCIPAL_MESSAGE }),
       );
     }
-    if (!input.code) {
+    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,
@@ -696,39 +885,31 @@ async function completeMcpOAuthCallbackWithinDeadline(
           commit: async (_tx, current) => ({
             ...current,
             revision: current.revision + 1,
-            state: "failed",
+            state: cancelled ? "cancelled" : "failed",
             nextAction: { type: "none" },
             error: {
-              code: "missing_code",
+              code: input.error ? "provider_denied" : "missing_code",
               message: "Authorization was not completed. Start a new connection attempt.",
               retryable: false,
             },
           }),
         });
       }
-      return callbackStateResult(state, "error", {
-        stage: "state_verify",
-        reason: "missing_code",
-      });
+      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",
       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,
@@ -750,6 +931,17 @@ async function completeMcpOAuthCallbackWithinDeadline(
         ? error
         : new OAuthCallbackStageError("state_verify", "state_invalid", error);
     logOAuthCallbackFailure(observability, staged, state);
+    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,
@@ -765,6 +957,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!,
@@ -777,6 +979,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,
@@ -784,7 +1007,6 @@ async function completeMcpOAuthCallbackWithinDeadline(
       token,
       deadline,
     );
-    const scopes = grantedScopes(token.scopeText, state.authorizeScopes);
     const credential = credentialBundle(token, state, client);
     const metadata = {
       resource: state.resource,
@@ -807,6 +1029,7 @@ async function completeMcpOAuthCallbackWithinDeadline(
           : {}),
       },
       mcpToolsVerification: verification.metadata,
+      ...(verification.providerIdentity ?? {}),
       ...(verification.tools ? { mcpTools: verification.tools } : {}),
     };
     const credentialEncrypted = encryptEnvironmentValue(key, JSON.stringify(credential));
@@ -821,7 +1044,7 @@ async function completeMcpOAuthCallbackWithinDeadline(
             subjectId: ownerSubjectId,
             providerDomain: state.providerDomain,
             kind: "oauth2",
-            status: "active",
+            status: verification.connectionStatus ?? "active",
             credentialEncrypted,
             grantedScopes: scopes,
             expiresAt: token.expiresAt,
@@ -834,6 +1057,7 @@ async function completeMcpOAuthCallbackWithinDeadline(
             subjectId: ownerSubjectId,
             providerDomain: state.providerDomain,
             kind: "oauth2",
+            status: verification.connectionStatus ?? "active",
             credentialEncrypted,
             grantedScopes: scopes,
             expiresAt: token.expiresAt,
@@ -843,38 +1067,45 @@ async function completeMcpOAuthCallbackWithinDeadline(
     };
     if (connectOperation) {
       await runCallbackDatabaseStage(deadline, "persist", db, (scopedDb) =>
-        finishConnectOperation(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: "connected",
-              },
-            };
+        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, persist);
+    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",
@@ -896,6 +1127,41 @@ async function completeMcpOAuthCallbackWithinDeadline(
         ? error
         : new OAuthCallbackStageError("persist", "persist_failed", error);
     logOAuthCallbackFailure(observability, staged, state);
+    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,
@@ -924,7 +1190,13 @@ function callbackStateResult(
 ): OAuthCallbackResult {
   if ((state?.externalContinuation || state?.connectAttemptId) && state.returnUrl)
     return { redirectTo: state.returnUrl, exactReturn: true };
-  return { redirectTo: callbackReturnPath(state?.returnPath ?? "/integrations", status, details) };
+  return {
+    redirectTo: callbackReturnPath(
+      state?.returnPath ?? INTEGRATIONS_FALLBACK_PATH,
+      status,
+      details,
+    ),
+  };
 }
 
 export function integrationBaseUrl(publicBaseUrl: string | undefined, requestUrl: string): string {
@@ -985,7 +1257,7 @@ export async function inspectMcpAuthentication(
           params: {
             protocolVersion: "2025-03-26",
             capabilities: {},
-            clientInfo: { name: "OpenGeni", version: "1.0" },
+            clientInfo: { name: "Opengeni", version: "1.0" },
           },
         }),
         signal,
@@ -1042,10 +1314,13 @@ export async function inspectMcpAuthentication(
       await resolveMcpOAuthDiscovery({
         resourceUrl: resource,
         challenge,
-        fetchMetadata: async ({ url }) => {
+        fetchMetadata: async ({ kind, url }) => {
           try {
-            const result = await deadline.run("protected_resource_metadata", (signal) =>
-              fetchOAuthMetadata(url, settings, signal),
+            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;
@@ -1059,7 +1334,7 @@ export async function inspectMcpAuthentication(
         canonicalizeResource: canonicalOAuthResource,
       });
       return { kind: "oauth2" };
-    } catch {
+    } catch (failure) {
       // Public initialization does not exclude optional or tool-level OAuth.
       // Only explicit absence of metadata permits the unauthenticated path.
       if (
@@ -1072,20 +1347,31 @@ export async function inspectMcpAuthentication(
         return { kind: "none" };
       return {
         kind: "unknown",
-        message:
-          "This server's sign-in requirements could not be determined. Check its setup instructions.",
+        message: mcpAuthInspectionFailureMessage(failure),
       };
     }
-  } catch {
+  } catch (failure) {
     return {
       kind: "unknown",
-      message: "Could not check this server. Retry or consult its setup instructions.",
+      message: mcpAuthInspectionFailureMessage(failure),
     };
   } finally {
     deadline.dispose();
   }
 }
 
+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,
@@ -1143,6 +1429,70 @@ async function discoverMcpOAuth(
   }
 }
 
+/** 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 (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(
   resource: string,
   settings: Settings,
@@ -1206,6 +1556,7 @@ async function registerOAuthClient(
   manual: OAuthStartRequest["oauthClient"],
   profile: OAuthProviderProfile,
   signal: AbortSignal,
+  acquisition: Pick<OAuthStartContext, "accountId" | "workspaceId" | "integrationKey">,
 ): Promise<OAuthClientRegistration> {
   const operator = operatorClientForAs(settings, as);
   if (operator) {
@@ -1220,6 +1571,7 @@ async function registerOAuthClient(
       redirectUri,
       scopes,
       signal,
+      acquisition,
     );
   }
   if (selfRegistration === "cimd") {
@@ -1244,7 +1596,15 @@ async function registerOAuthClient(
       ),
     };
   }
-  return await getOrCreateDynamicClientRegistration(db, settings, as, redirectUri, scopes, signal);
+  return await getOrCreateDynamicClientRegistration(
+    db,
+    settings,
+    as,
+    redirectUri,
+    scopes,
+    signal,
+    acquisition,
+  );
 }
 
 export function preferredOAuthSelfRegistration(
@@ -1272,6 +1632,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)) {
@@ -1292,6 +1653,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 = {
@@ -1303,34 +1670,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(
@@ -1436,7 +1812,6 @@ function operatorClientEntryFor(
   settings: Settings,
   candidates: string[],
 ): ReturnType<typeof parseIntegrationsOauthClientsJson>[string] | null {
-  const normalizedCandidates = new Set(candidates.map(normalizedIssuerKey));
   const candidateOrigins = candidates.flatMap((candidate) => {
     try {
       return [new URL(candidate).origin];
@@ -1453,22 +1828,37 @@ function operatorClientEntryFor(
       return resolved;
     }
   }
-  const configured = parseIntegrationsOauthClientsJson(settings.integrationsOauthClientsJson);
-  const exactKeys = uniqueStrings(
-    candidates.flatMap((candidate) => [candidate, normalizedIssuerKey(candidate)]),
+  return findIntegrationsOauthClient(
+    parseIntegrationsOauthClientsJson(settings.integrationsOauthClientsJson),
+    candidates,
+  );
+}
+
+/** 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),
   );
-  for (const key of exactKeys) {
-    const entry = configured[key];
-    if (entry) {
-      return entry;
-    }
-  }
-  for (const [key, entry] of Object.entries(configured)) {
-    if (normalizedCandidates.has(normalizedIssuerKey(key))) {
-      return entry;
-    }
-  }
-  return null;
 }
 
 function normalizedIssuerKey(value: string): string {
@@ -1491,7 +1881,7 @@ async function dynamicClientRegistration(
     method: "POST",
     headers: { "content-type": "application/json", accept: "application/json" },
     body: JSON.stringify({
-      client_name: "OpenGeni",
+      client_name: "Opengeni",
       redirect_uris: [redirectUri],
       token_endpoint_auth_method: "none",
       grant_types: ["authorization_code", "refresh_token"],
@@ -1542,10 +1932,21 @@ async function existingOAuthConnectionForStart(
     connectionSelection: OAuthProviderProfile["connectionSelection"];
     exactMcpBinding: boolean;
     connectionId?: string | undefined;
+    newAccount?: boolean;
     requestedOwnership?: ConnectionOwnership | undefined;
     newConnectionOwnership: ConnectionOwnership;
   },
 ) {
+  if (input.newAccount) {
+    // A further account always mints its own row; it never refreshes (and so
+    // never replaces) an account the caller already holds for this provider.
+    if (input.connectionSelection === "canonical_personal") {
+      throw new HTTPException(409, {
+        message: "this connector supports one account per person; reconnect it instead",
+      });
+    }
+    return null;
+  }
   if (input.connectionId) {
     const connection = await getConnectionMetadata(
       db,
@@ -1633,6 +2034,41 @@ export function buildAuthorizationUrl(input: {
   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,
@@ -1641,6 +2077,13 @@ 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) {
@@ -1662,7 +2105,7 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
     encodedDiscoveryMode &&
     (!authorizationServerMetadataUrl ||
       (discoveryMode === "rfc9728_protected_resource" && !protectedResourceMetadataUrl) ||
-      (discoveryMode === "legacy_2025_03_26_metadata" && protectedResourceMetadataUrl))
+      (discoveryMode !== "rfc9728_protected_resource" && protectedResourceMetadataUrl))
   ) {
     throw new HTTPException(400, { message: "invalid OAuth discovery provenance state" });
   }
@@ -1670,6 +2113,12 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
   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"),
@@ -1692,11 +2141,12 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
     ...(stringValue(payload.connectAttemptId)
       ? { connectAttemptId: requiredString(payload.connectAttemptId, "state.connectAttemptId") }
       : {}),
-    // 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",
+    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,
@@ -1756,6 +2206,7 @@ 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" });
   }
@@ -1766,24 +2217,61 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
   ) {
     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): McpOAuthDiscoveryMode {
+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") {
+  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;
 }
@@ -2071,6 +2559,8 @@ function oauthStartStageLabel(stage: OAuthStartStage): string {
       return "authorization-server discovery";
     case "client_registration":
       return "OAuth client registration";
+    case "state_persist":
+      return "OAuth state persistence";
   }
 }
 
@@ -2196,11 +2686,45 @@ 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),
+        settings,
+      );
+      if (local.required && verifiedTools.length === 0)
+        throw new Error("Connector verification did not report an authorized tool scope");
+      return verifiedTools;
+    });
     return {
       metadata: {
         status: "ok",
@@ -2208,6 +2732,7 @@ async function verifyMcpToolsListNonFatal(
         toolCount: tools.length,
       },
       tools,
+      ...(providerIdentity ? { providerIdentity } : {}),
     };
   } catch (error) {
     const staged =
@@ -2217,6 +2742,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: {
@@ -2224,6 +2750,7 @@ async function verifyMcpToolsListNonFatal(
         checkedAt: new Date().toISOString(),
         reason: staged.reason,
       },
+      ...(grantRejected ? { connectionStatus: "needs_reauth" as const } : {}),
     };
   }
 }
@@ -2270,7 +2797,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}`;
   }
@@ -2417,6 +2944,7 @@ export function chooseMcpAuthorizeScopes(input: {
   requested: string[] | undefined;
   challenged: string[] | undefined;
   supported: string[];
+  authorizationServerScopesSupported?: string[];
 }): string[] {
   const profile = builtInOAuthProfileFor({ mcpUrl: input.mcpUrl }) ?? DEFAULT_OAUTH_PROFILE;
   return chooseProfileAuthorizeScopes(profile, input);
@@ -2428,14 +2956,26 @@ function chooseProfileAuthorizeScopes(
     requested: string[] | undefined;
     challenged: string[] | undefined;
     supported: string[];
+    authorizationServerScopesSupported?: string[];
   },
 ): string[] {
-  return profile.requestedScopes
-    ? [...profile.requestedScopes]
-    : chooseAuthorizeScopes(input.requested, input.challenged, input.supported);
-}
-
-function grantedScopes(scopeText: string | undefined, fallback: 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));
   }