@rudderhq/server 0.6.1 → 0.6.2-canary.0

package/dist/services/mcp/oauth.js

@@ -1,27 +1,26 @@
 import { auth, OAuthError, OAuthErrorCode, } from "@modelcontextprotocol/client";
-import { activityLog, instanceUserRoles, mcpConnections, mcpOAuthGrants, mcpOAuthSessions, organizationMemberships, organizationSecrets, organizationSecretVersions, } from "@rudderhq/db";
+import { activityLog, agentCustomIntegrationBindings, instanceUserRoles, mcpConnections, mcpOAuthGrants, mcpOAuthSessions, organizationMemberships, organizationSecrets, organizationSecretVersions, } from "@rudderhq/db";
 import { MCP_OAUTH_SESSION_TTL_MS, mcpOAuthCallbackSchema, mcpScopeSelectionSchema, } from "@rudderhq/shared";
 import { and, asc, eq, gt, inArray, isNull, lte, sql, } from "drizzle-orm";
 import { createHash, randomBytes, randomUUID, } from "node:crypto";
 import { HttpError, notFound, unprocessable } from "../../errors.js";
 import { getSecretProvider } from "../../secrets/provider-registry.js";
 import { lockManagedMcpOAuthAuthorizer } from "./authorizer-lock.js";
-import { createManagedMcpClient, resolveMcpHttpCredentials, } from "./managed-client.js";
+import { accessToken, defaultDiscoverProviderScope, defaultValidateProviderTools, MAX_SCOPE_OPTIONS, oauthActivityValues, oauthRevocationEndpoint, parseOAuthMaterial, safeScopeOption, tokenExpiry, tokenScopes } from "./oauth-helpers.js";
 import { PersistentMcpOAuthClientProvider, resolveMcpOAuthRedirectUri, } from "./oauth-provider.js";
 import { createSecureMcpFetch } from "./pinned-fetch.js";
 import { MCP_CURATED_OAUTH_ORIGINS, MCP_PROVIDER_REGISTRY, resolveCuratedMcpEndpoint, } from "./provider-registry.js";
 import { resolveMcpHttpTarget } from "./security-policy.js";
+export { parseProviderWorkspaceScope } from "./oauth-helpers.js";
 function createOAuthAuthorizationSnapshot(connection) {
     if (connection.provider === "custom") {
         throw unprocessable("Managed MCP OAuth only supports curated providers");
     }
-    const serverUrl = connection.provider === "supabase"
-        ? MCP_PROVIDER_REGISTRY.supabase.endpoint
-        : resolveCuratedMcpEndpoint({
-            provider: connection.provider,
-            accessMode: connection.accessMode,
-            externalScope: connection.externalScope,
-        }).href;
+    const serverUrl = resolveCuratedMcpEndpoint({
+        provider: connection.provider,
+        accessMode: connection.accessMode,
+        externalScope: connection.externalScope,
+    }).href;
     return {
         serverUrl,
         ...(connection.provider === "linear" && connection.accessMode === "read_only"
@@ -30,6 +29,13 @@ function createOAuthAuthorizationSnapshot(connection) {
         accessMode: connection.accessMode,
     };
 }
+function isSupabaseAccountUpgradeCandidate(connection) {
+    return connection.provider === "supabase"
+        && connection.scopeMode === "account"
+        && connection.externalScope === null
+        && connection.canonicalState === "superseded"
+        && connection.supersededByConnectionId !== null;
+}
 function readOAuthAuthorizationSnapshot(statusMetadata, connection) {
     const value = statusMetadata.authorization;
     if (isRecord(value)
@@ -118,237 +124,6 @@ function publicConnection(row) {
         updatedAt: row.updatedAt,
     };
 }
-function oauthActivityValues(input) {
-    return {
-        orgId: input.orgId,
-        actorType: input.actorUserId ? "user" : "system",
-        actorId: input.actorUserId ?? "system",
-        action: input.action,
-        entityType: "mcp_connection",
-        entityId: input.connectionId,
-        details: input.details,
-    };
-}
-function tokenExpiry(tokens, now = new Date()) {
-    if (typeof tokens?.expires_in !== "number" || !Number.isFinite(tokens.expires_in))
-        return null;
-    return new Date(now.getTime() + Math.max(0, tokens.expires_in) * 1_000);
-}
-function tokenScopes(tokens) {
-    return typeof tokens?.scope === "string"
-        ? Array.from(new Set(tokens.scope.split(/\s+/u).filter(Boolean)))
-        : [];
-}
-function accessToken(material) {
-    const value = material.tokens?.access_token;
-    if (!value)
-        throw unprocessable("Managed MCP OAuth credentials are unavailable");
-    return value;
-}
-function oauthRevocationEndpoint(material) {
-    const metadata = material?.discoveryState?.authorizationServerMetadata;
-    return isRecord(metadata) && typeof metadata.revocation_endpoint === "string"
-        ? metadata.revocation_endpoint
-        : null;
-}
-const SAFE_SCOPE_METADATA_KEYS = new Set([
-    "region",
-    "scopeKind",
-    "status",
-    "workspaceName",
-    "workspace_name",
-    "organizationName",
-    "organization_name",
-]);
-const MAX_SCOPE_OPTIONS = 500;
-const MAX_SCOPE_METADATA_BYTES = 4_096;
-function safeScopeMetadata(value) {
-    const output = {};
-    for (const [key, raw] of Object.entries(value)) {
-        if (!SAFE_SCOPE_METADATA_KEYS.has(key))
-            continue;
-        const safeValue = typeof raw === "string"
-            ? raw.slice(0, 512)
-            : typeof raw === "number" && Number.isFinite(raw)
-                ? raw
-                : typeof raw === "boolean"
-                    ? raw
-                    : undefined;
-        if (safeValue === undefined)
-            continue;
-        const candidate = { ...output, [key]: safeValue };
-        if (Buffer.byteLength(JSON.stringify(candidate), "utf8") > MAX_SCOPE_METADATA_BYTES) {
-            continue;
-        }
-        output[key] = safeValue;
-    }
-    return output;
-}
-function safeScopeOption(value) {
-    return {
-        id: value.id.trim().slice(0, 512),
-        displayName: value.displayName.trim().slice(0, 240),
-        metadata: isRecord(value.metadata) ? safeScopeMetadata(value.metadata) : {},
-    };
-}
-function sanitizeScopeOptions(values) {
-    const output = [];
-    const seen = new Set();
-    for (const value of values) {
-        const safe = safeScopeOption(value);
-        if (!safe.id || !safe.displayName || seen.has(safe.id))
-            continue;
-        seen.add(safe.id);
-        output.push(safe);
-        if (output.length === MAX_SCOPE_OPTIONS)
-            break;
-    }
-    return output;
-}
-function parseToolJson(result) {
-    for (const content of result.content ?? []) {
-        if (content.type !== "text")
-            continue;
-        try {
-            return JSON.parse(content.text);
-        }
-        catch {
-            // Ignore non-JSON provider prose; onboarding never persists it.
-        }
-    }
-    return undefined;
-}
-function asProviderScope(value, keys) {
-    if (!isRecord(value))
-        return null;
-    const id = keys.id.map((key) => value[key])
-        .find((item) => typeof item === "string" && item.length > 0);
-    if (!id)
-        return null;
-    const displayName = keys.name.map((key) => value[key])
-        .find((item) => typeof item === "string" && item.length > 0) ?? id;
-    const metadata = Object.fromEntries(["region", "status", "workspaceName", "workspace_name", "organizationName"]
-        .flatMap((key) => value[key] === undefined ? [] : [[key, value[key]]]));
-    return safeScopeOption({ id, displayName, metadata });
-}
-function providerScopeContainer(provider, value) {
-    const definition = MCP_PROVIDER_REGISTRY[provider].scopeIdentity;
-    const candidates = [
-        ...definition.containers.map((key) => value[key]),
-    ];
-    const user = value.user;
-    if (provider === "linear" && isRecord(user)) {
-        candidates.push(...definition.containers.map((key) => user[key]));
-    }
-    const bot = value.bot;
-    if (provider === "notion" && isRecord(bot)) {
-        candidates.push(...definition.containers.map((key) => bot[key]));
-    }
-    const self = value.self;
-    if (provider === "notion" && isRecord(self)) {
-        candidates.push(...definition.containers.map((key) => self[key]));
-    }
-    return candidates.find(isRecord) ?? null;
-}
-/**
- * Official identity tools return an actor plus an explicit workspace or
- * organization. The actor id is never a valid Rudder connection scope.
- */
-export function parseProviderWorkspaceScope(provider, value) {
-    if (!isRecord(value))
-        return null;
-    const container = providerScopeContainer(provider, value);
-    if (container) {
-        return asProviderScope(container, {
-            id: ["workspace_id", "workspaceId", "organization_id", "organizationId", "id"],
-            name: [
-                "workspace_name",
-                "workspaceName",
-                "organization_name",
-                "organizationName",
-                "name",
-            ],
-        });
-    }
-    if (provider === "linear"
-        && typeof value.id === "string"
-        && value.id.length > 0
-        && Array.isArray(value.teams)
-        && value.teams.some((team) => isRecord(team) && typeof team.id === "string")) {
-        const authorizationName = typeof value.name === "string" && value.name.length > 0
-            ? `${value.name}'s Linear authorization`
-            : "Linear authorization";
-        const opaqueSubjectId = createHash("sha256")
-            .update(`linear-authorization-subject:${value.id}`)
-            .digest("hex")
-            .slice(0, 24);
-        return safeScopeOption({
-            id: `linear-authorization-subject-${opaqueSubjectId}`,
-            displayName: authorizationName,
-            metadata: {
-                scopeKind: "authorization_subject",
-            },
-        });
-    }
-    const nested = provider === "notion" && isRecord(value.bot) ? value.bot : value;
-    return asProviderScope(nested, {
-        id: ["workspace_id", "workspaceId", "organization_id", "organizationId"],
-        name: [
-            "workspace_name",
-            "workspaceName",
-            "organization_name",
-            "organizationName",
-        ],
-    });
-}
-async function defaultDiscoverProviderScope(input) {
-    const curatedOrigin = new URL(MCP_PROVIDER_REGISTRY[input.provider].endpoint).origin;
-    const client = await createManagedMcpClient({
-        transport: "streamable_http",
-        url: input.endpoint,
-        credentials: resolveMcpHttpCredentials({ bearerToken: accessToken(input.material) }),
-        network: {
-            allowedOrigins: input.allowlists.httpOrigins,
-            curatedOrigin,
-            lookup: input.dnsLookup,
-        },
-        startupTimeoutMs: input.connection.startupTimeoutMs,
-        toolTimeoutMs: input.connection.toolTimeoutMs,
-    });
-    try {
-        if (input.provider === "supabase") {
-            const parsed = parseToolJson(await client.callTool("list_projects", {}));
-            const rawProjects = Array.isArray(parsed)
-                ? parsed
-                : isRecord(parsed) && Array.isArray(parsed.projects)
-                    ? parsed.projects
-                    : [];
-            const options = rawProjects
-                .map((project) => asProviderScope(project, {
-                id: ["ref", "id", "project_ref"],
-                name: ["name", "display_name", "ref", "id"],
-            }))
-                .filter((option) => Boolean(option));
-            return { options };
-        }
-        const identity = MCP_PROVIDER_REGISTRY[input.provider].scopeIdentity;
-        if (!identity)
-            throw new Error("Provider did not define workspace identity discovery");
-        const tools = await client.discoverTools();
-        const identityTool = identity.toolNames.find((name) => (tools.some((tool) => tool.name === name)));
-        if (!identityTool) {
-            throw new Error("Provider did not expose a safe workspace identity tool");
-        }
-        const parsed = parseToolJson(await client.callTool(identityTool, identity.arguments));
-        const selected = parseProviderWorkspaceScope(input.provider, parsed);
-        if (!selected)
-            throw new Error("Provider workspace identity was invalid");
-        return { options: [], selected };
-    }
-    finally {
-        await client.close();
-    }
-}
 async function prepareOAuthSecret(connectionName, kind, material) {
     const id = randomUUID();
     const prepared = await getSecretProvider("local_encrypted").createVersion({
@@ -383,17 +158,6 @@ async function insertOAuthSecret(tx, input) {
         createdByUserId: input.actorUserId ?? null,
     });
 }
-function parseOAuthMaterial(value) {
-    try {
-        const parsed = JSON.parse(value);
-        if (!isRecord(parsed))
-            throw new Error("invalid");
-        return parsed;
-    }
-    catch {
-        throw unprocessable("Managed MCP OAuth credentials are unavailable");
-    }
-}
 export function managedMcpOAuthService(db, options) {
     const grantRefreshSingleFlights = new Map();
     const runAuth = options.oauthAuth ?? auth;
@@ -471,8 +235,8 @@ export function managedMcpOAuthService(db, options) {
             .for("share")
             .then((rows) => rows[0] ?? null));
     }
-    async function requireUsableGrant(orgId, connectionId) {
-        const outcome = await db.transaction(async (tx) => {
+    async function requireUsableGrant(orgId, connectionId, executor) {
+        const validate = async (tx) => {
             const connection = await tx.select().from(mcpConnections)
                 .where(and(eq(mcpConnections.orgId, orgId), eq(mcpConnections.id, connectionId)))
                 .for("update")
@@ -493,7 +257,10 @@ export function managedMcpOAuthService(db, options) {
                 return { kind: "invalid_authorizer" };
             }
             return { kind: "usable", grant };
-        });
+        };
+        const outcome = executor
+            ? await validate(executor)
+            : await db.transaction(validate);
         if (outcome.kind === "invalid_authorizer") {
             throw unprocessable("Managed MCP OAuth authorization must be reconnected by an owner");
         }
@@ -557,6 +324,25 @@ export function managedMcpOAuthService(db, options) {
             dnsLookup: options.dnsLookup,
         });
     }
+    async function validateProviderTools(input) {
+        if (options.validateProviderTools) {
+            await options.validateProviderTools({
+                provider: input.connection.provider,
+                connection: input.connection,
+                material: input.material,
+                endpoint: input.endpoint,
+            });
+            return;
+        }
+        await defaultValidateProviderTools({
+            provider: input.connection.provider,
+            connection: input.connection,
+            material: input.material,
+            endpoint: input.endpoint,
+            allowlists: options.allowlists,
+            dnsLookup: options.dnsLookup,
+        });
+    }
     async function bestEffortRevokeMaterial(material, timeoutMs) {
         const revocationEndpoint = oauthRevocationEndpoint(material);
         const tokens = material?.tokens;
@@ -668,14 +454,24 @@ export function managedMcpOAuthService(db, options) {
         }
         return cleaned;
     }
-    async function start(orgId, connectionId, actor) {
+    async function start(orgId, connectionId, actor, request = {}) {
         await cleanupExpiredSessions(orgId);
         const connection = await findConnection(orgId, connectionId);
         assertCurated(connection);
+        if (connection.canonicalState !== "canonical"
+            && !isSupabaseAccountUpgradeCandidate(connection)) {
+            throw unprocessable("Superseded MCP connections cannot start authorization");
+        }
         if (options.deploymentMode === "authenticated"
             && !actor.userId) {
             throw unprocessable("Managed MCP OAuth requires an authenticated authorizing user");
         }
+        if (request.requestedAccessMode
+            && (!["supabase", "linear"].includes(connection.provider)
+                || connection.status !== "active"
+                || !connection.enabled)) {
+            throw unprocessable("Managed MCP access changes require an active Supabase or Linear connection");
+        }
         let redirectUri;
         try {
             redirectUri = resolveMcpOAuthRedirectUri({
@@ -697,7 +493,12 @@ export function managedMcpOAuthService(db, options) {
                 material = structuredClone(next);
             },
         });
-        const authorization = createOAuthAuthorizationSnapshot(connection);
+        const authorization = createOAuthAuthorizationSnapshot({
+            ...connection,
+            ...(request.requestedAccessMode
+                ? { accessMode: request.requestedAccessMode }
+                : {}),
+        });
         const result = await runAuth(provider, {
             serverUrl: authorization.serverUrl,
             scope: authorization.scope,
@@ -726,27 +527,30 @@ export function managedMcpOAuthService(db, options) {
             if (!locked)
                 throw notFound("MCP connection not found");
             assertCurated(locked);
+            if (isSupabaseAccountUpgradeCandidate(locked)) {
+                const legacy = await tx.select().from(mcpConnections)
+                    .where(and(eq(mcpConnections.orgId, orgId), eq(mcpConnections.id, locked.supersededByConnectionId), eq(mcpConnections.provider, "supabase"), eq(mcpConnections.scopeMode, "legacy_project"), eq(mcpConnections.canonicalState, "canonical")))
+                    .for("share")
+                    .then((rows) => rows[0] ?? null);
+                if (!legacy) {
+                    throw unprocessable("Supabase account upgrade is no longer available");
+                }
+            }
             if (locked.lifecycleRevision !== connection.lifecycleRevision) {
                 throw unprocessable("Managed MCP OAuth connection changed; start authorization again");
             }
+            if (request.requestedAccessMode
+                && locked.accessMode !== connection.accessMode) {
+                throw unprocessable("Managed MCP access changed; start authorization again");
+            }
             const priorGrant = await tx.select().from(mcpOAuthGrants)
                 .where(and(eq(mcpOAuthGrants.orgId, orgId), eq(mcpOAuthGrants.connectionId, connectionId)))
                 .for("update")
                 .then((rows) => rows[0] ?? null);
-            if (priorGrant?.status === "active") {
-                await tx.update(mcpOAuthGrants).set({
-                    status: "needs_reauth",
-                    statusMetadata: { reason: "authorization_restarted" },
-                    credentialSecretId: null,
-                    refreshLeaseNonce: null,
-                    refreshLeaseExpiresAt: null,
-                    updatedAt: now,
-                }).where(eq(mcpOAuthGrants.id, priorGrant.id));
-                if (priorGrant.credentialSecretId) {
-                    await tx.delete(organizationSecrets)
-                        .where(eq(organizationSecrets.id, priorGrant.credentialSecretId));
-                }
-            }
+            const isCredentialReplacement = priorGrant?.status === "active"
+                && Boolean(priorGrant.credentialSecretId)
+                && locked.status === "active"
+                && locked.enabled;
             const replacedSessions = await tx.select({
                 id: mcpOAuthSessions.id,
                 credentialSecretId: mcpOAuthSessions.credentialSecretId,
@@ -779,11 +583,17 @@ export function managedMcpOAuthService(db, options) {
                 credentialSecretId: sessionSecret.id,
                 redirectUri,
                 status: "authorizing",
-                statusMetadata: { authorization },
+                statusMetadata: {
+                    authorization,
+                    reauthorization: isCredentialReplacement,
+                    ...(request.requestedAccessMode
+                        ? { pendingAccessMode: request.requestedAccessMode }
+                        : {}),
+                },
                 expiresAt,
             });
             await tx.update(mcpConnections).set({
-                status: "authorizing",
+                status: isCredentialReplacement ? "active" : "authorizing",
                 enabled: true,
                 disabledAt: null,
                 revokedAt: null,
@@ -822,7 +632,8 @@ export function managedMcpOAuthService(db, options) {
             if (!connection)
                 return null;
             assertCurated(connection);
-            if (connection.status !== "authorizing")
+            if (connection.canonicalState !== "canonical"
+                && !isSupabaseAccountUpgradeCandidate(connection))
                 return null;
             const lockedSession = await tx.select().from(mcpOAuthSessions)
                 .where(and(eq(mcpOAuthSessions.id, session.id), eq(mcpOAuthSessions.stateHash, stateHash)))
@@ -831,6 +642,11 @@ export function managedMcpOAuthService(db, options) {
             if (!lockedSession || lockedSession.status !== "authorizing" || lockedSession.consumedAt) {
                 return null;
             }
+            const isCredentialReplacement = lockedSession.statusMetadata.reauthorization === true;
+            if (connection.status !== "authorizing"
+                && !(isCredentialReplacement && connection.status === "active" && connection.enabled)) {
+                return null;
+            }
             if (lockedSession.expiresAt <= now) {
                 await tx.update(mcpOAuthSessions).set({
                     consumedAt: now,
@@ -892,12 +708,29 @@ export function managedMcpOAuthService(db, options) {
                     .where(and(eq(mcpConnections.orgId, callbackContext.session.orgId), eq(mcpConnections.id, callbackContext.connection.id)))
                     .for("update")
                     .then((rows) => rows[0] ?? null);
+                const isCredentialReplacement = callbackContext.session.statusMetadata.reauthorization === true
+                    && locked?.status === "active"
+                    && locked.enabled;
                 if (!locked
-                    || locked.status !== "authorizing"
+                    || (locked.status !== "authorizing"
+                        && !isCredentialReplacement)
                     || locked.lifecycleRevision !== callbackContext.connectionLifecycleRevision) {
                     return;
                 }
                 const now = new Date();
+                if (isCredentialReplacement) {
+                    await tx.insert(activityLog).values(oauthActivityValues({
+                        orgId: callbackContext.session.orgId,
+                        connectionId: locked.id,
+                        action: inputFailure.action,
+                        actorUserId: callbackContext.session.authorizingUserId,
+                        details: {
+                            reason: inputFailure.reason,
+                            existingGrantPreserved: true,
+                        },
+                    }));
+                    return;
+                }
                 await tx.update(mcpConnections).set({
                     status: inputFailure.status,
                     ...(inputFailure.status === "needs_reauth"
@@ -932,8 +765,10 @@ export function managedMcpOAuthService(db, options) {
             throw unprocessable("Managed MCP OAuth authorization was not completed");
         }
         const authorization = readOAuthAuthorizationSnapshot(consumed.session.statusMetadata, consumed.connection);
-        if (consumed.connection.provider === "linear"
-            && authorization.accessMode !== consumed.connection.accessMode) {
+        const stagedAccessMode = consumed.session.statusMetadata.reauthorization === true
+            && consumed.session.statusMetadata.pendingAccessMode === authorization.accessMode;
+        if (authorization.accessMode !== consumed.connection.accessMode
+            && !stagedAccessMode) {
             await finishFailure({
                 status: "needs_reauth",
                 action: "mcp_oauth.authorization_failed",
@@ -981,11 +816,13 @@ export function managedMcpOAuthService(db, options) {
             if (authResult !== "AUTHORIZED" || !grantMaterial.tokens?.access_token) {
                 throw unprocessable("Managed MCP OAuth token exchange failed");
             }
-            scope = await discoverScope({
-                connection: consumed.connection,
-                material: grantMaterial,
-                endpoint: authorization.serverUrl,
-            });
+            scope = consumed.connection.provider === "supabase"
+                ? { options: [] }
+                : await discoverScope({
+                    connection: consumed.connection,
+                    material: grantMaterial,
+                    endpoint: authorization.serverUrl,
+                });
         }
         catch (error) {
             await finishUnpersistedGrantFailure({
@@ -999,23 +836,31 @@ export function managedMcpOAuthService(db, options) {
                 throw error;
             throw unprocessable("Managed MCP OAuth authorization could not be completed");
         }
-        const safeOptions = sanitizeScopeOptions(scope.options);
         const selected = scope.selected ? safeScopeOption(scope.selected) : undefined;
-        if (consumed.connection.provider === "supabase" && safeOptions.length === 0) {
+        if (consumed.connection.provider !== "supabase" && !selected) {
             await finishUnpersistedGrantFailure({
                 status: "error",
                 action: "mcp_oauth.authorization_failed",
-                reason: "no_selectable_projects",
+                reason: "workspace_identity_unavailable",
             });
-            throw unprocessable("Supabase OAuth did not return any selectable projects");
+            throw unprocessable("Managed MCP OAuth did not identify a provider workspace");
         }
-        if (consumed.connection.provider !== "supabase" && !selected) {
+        try {
+            await validateProviderTools({
+                connection: consumed.connection,
+                material: grantMaterial,
+                endpoint: authorization.serverUrl,
+            });
+        }
+        catch (error) {
             await finishUnpersistedGrantFailure({
-                status: "error",
+                status: isInvalidGrantOAuthError(error) ? "needs_reauth" : "error",
                 action: "mcp_oauth.authorization_failed",
-                reason: "workspace_identity_unavailable",
+                reason: "tool_discovery_failed",
             });
-            throw unprocessable("Managed MCP OAuth did not identify a provider workspace");
+            if (error instanceof HttpError)
+                throw error;
+            throw unprocessable("Managed MCP OAuth tool discovery could not be completed");
         }
         const outcome = await (async () => {
             try {
@@ -1028,10 +873,23 @@ export function managedMcpOAuthService(db, options) {
                         .for("update")
                         .then((rows) => rows[0] ?? null);
                     if (!connection
-                        || connection.status !== "authorizing"
+                        || (connection.status !== "authorizing"
+                            && !(consumed.session.statusMetadata.reauthorization === true
+                                && connection.status === "active"
+                                && connection.enabled))
                         || connection.lifecycleRevision !== consumed.connectionLifecycleRevision) {
                         return null;
                     }
+                    const legacyUpgradeConnection = isSupabaseAccountUpgradeCandidate(connection)
+                        ? await tx.select().from(mcpConnections)
+                            .where(and(eq(mcpConnections.orgId, connection.orgId), eq(mcpConnections.id, connection.supersededByConnectionId), eq(mcpConnections.provider, "supabase"), eq(mcpConnections.scopeMode, "legacy_project"), eq(mcpConnections.canonicalState, "canonical")))
+                            .for("update")
+                            .then((rows) => rows[0] ?? null)
+                        : null;
+                    if (isSupabaseAccountUpgradeCandidate(connection)
+                        && !legacyUpgradeConnection) {
+                        return null;
+                    }
                     const stillAuthorized = options.deploymentMode === "local_trusted"
                         && !consumed.session.authorizingUserId
                         ? true
@@ -1046,19 +904,27 @@ export function managedMcpOAuthService(db, options) {
                                 .for("share")
                                 .then((rows) => rows[0] ?? null));
                     if (!stillAuthorized) {
-                        await tx.update(mcpConnections).set({
-                            status: "needs_reauth",
-                            enabled: false,
-                            disabledAt: now,
-                            lifecycleRevision: connection.lifecycleRevision + 1,
-                            updatedAt: now,
-                        }).where(eq(mcpConnections.id, connection.id));
+                        const existingGrantPreserved = consumed.session.statusMetadata.reauthorization === true
+                            && connection.status === "active"
+                            && connection.enabled;
+                        if (!existingGrantPreserved) {
+                            await tx.update(mcpConnections).set({
+                                status: "needs_reauth",
+                                enabled: false,
+                                disabledAt: now,
+                                lifecycleRevision: connection.lifecycleRevision + 1,
+                                updatedAt: now,
+                            }).where(eq(mcpConnections.id, connection.id));
+                        }
                         await tx.insert(activityLog).values(oauthActivityValues({
                             orgId: consumed.session.orgId,
                             connectionId: connection.id,
                             action: "mcp_oauth.authorization_rejected",
                             actorUserId: consumed.session.authorizingUserId,
-                            details: { reason: "authorizer_no_longer_authorized" },
+                            details: {
+                                reason: "authorizer_no_longer_authorized",
+                                existingGrantPreserved,
+                            },
                         }));
                         return { kind: "reauth" };
                     }
@@ -1080,9 +946,6 @@ export function managedMcpOAuthService(db, options) {
                         status: "active",
                         statusMetadata: {
                             authorization,
-                            ...(connection.provider === "supabase"
-                                ? { scopeOptions: safeOptions }
-                                : {}),
                         },
                         expiresAt: tokenExpiry(grantMaterial.tokens, now),
                         lastRefreshedAt: now,
@@ -1106,16 +969,62 @@ export function managedMcpOAuthService(db, options) {
                         await tx.delete(organizationSecrets)
                             .where(eq(organizationSecrets.id, existingGrant.credentialSecretId));
                     }
-                    const status = connection.provider === "supabase" ? "selecting_scope" : "active";
+                    const status = "active";
+                    if (legacyUpgradeConnection) {
+                        const legacyGrant = await tx.select().from(mcpOAuthGrants)
+                            .where(and(eq(mcpOAuthGrants.orgId, connection.orgId), eq(mcpOAuthGrants.connectionId, legacyUpgradeConnection.id)))
+                            .for("update")
+                            .then((rows) => rows[0] ?? null);
+                        await tx.update(mcpConnections).set({
+                            canonicalState: "superseded",
+                            supersededByConnectionId: connection.id,
+                            status: "revoked",
+                            enabled: false,
+                            revokedAt: now,
+                            lifecycleRevision: legacyUpgradeConnection.lifecycleRevision + 1,
+                            revision: legacyUpgradeConnection.revision + 1,
+                            updatedAt: now,
+                        }).where(eq(mcpConnections.id, legacyUpgradeConnection.id));
+                        await tx.update(agentCustomIntegrationBindings).set({
+                            accessMode: "none",
+                            policyRevision: sql `${agentCustomIntegrationBindings.policyRevision} + 1`,
+                            updatedAt: now,
+                        }).where(and(eq(agentCustomIntegrationBindings.orgId, connection.orgId), eq(agentCustomIntegrationBindings.connectionId, legacyUpgradeConnection.id)));
+                        if (legacyGrant) {
+                            await tx.update(mcpOAuthGrants).set({
+                                status: "revoked",
+                                credentialSecretId: null,
+                                revokedAt: now,
+                                updatedAt: now,
+                            }).where(eq(mcpOAuthGrants.id, legacyGrant.id));
+                            if (legacyGrant.credentialSecretId) {
+                                await tx.delete(organizationSecrets)
+                                    .where(eq(organizationSecrets.id, legacyGrant.credentialSecretId));
+                            }
+                        }
+                    }
                     await tx.update(mcpConnections).set({
                         status,
-                        externalScope: selected?.id ?? null,
-                        safeConfig: connection.provider === "supabase"
-                            ? {}
-                            : connection.safeConfig,
+                        accessMode: stagedAccessMode
+                            ? authorization.accessMode
+                            : connection.accessMode,
+                        externalScope: connection.provider === "supabase"
+                            ? legacyUpgradeConnection || connection.scopeMode === "account"
+                                ? null
+                                : connection.externalScope
+                            : selected?.id ?? null,
+                        scopeMode: legacyUpgradeConnection ? "account" : connection.scopeMode,
+                        safeConfig: legacyUpgradeConnection ? {} : connection.safeConfig,
+                        canonicalState: legacyUpgradeConnection
+                            ? "canonical"
+                            : connection.canonicalState,
+                        supersededByConnectionId: legacyUpgradeConnection
+                            ? null
+                            : connection.supersededByConnectionId,
                         enabled: true,
                         activatedAt: status === "active" ? connection.activatedAt ?? now : null,
                         lifecycleRevision: connection.lifecycleRevision + 1,
+                        revision: connection.revision + 1,
                         updatedAt: now,
                     }).where(eq(mcpConnections.id, connection.id));
                     await tx.insert(activityLog).values(oauthActivityValues({
@@ -1158,7 +1067,11 @@ export function managedMcpOAuthService(db, options) {
             throw unprocessable("Managed MCP OAuth must be reauthorized by an owner");
         }
         if (outcome.status === "active" && options.refreshConnectionTools) {
-            await options.refreshConnectionTools(outcome.orgId, outcome.connectionId, { userId: outcome.authorizingUserId, agentId: null });
+            // The replacement grant was already validated before the atomic swap.
+            // A transient second discovery must not turn a successfully swapped
+            // connection into an outage. Keep the last known-safe catalog and let a
+            // later refresh reconcile it.
+            await options.refreshConnectionTools(outcome.orgId, outcome.connectionId, { userId: outcome.authorizingUserId, agentId: null }).catch(() => undefined);
         }
         return { connectionId: outcome.connectionId, status: outcome.status };
     }