@polpo-ai/connect-server 0.15.144 → 0.16.0

package/dist/service.js

@@ -1,36 +1,104 @@
-import { ConnectError, assertConnectorRedirectAllowed, assertAllowedScopes, assertGrantedScopes, connectorHostnameIsUnsafe, createConnectorRegistry, normalizeScopes, resolveConnectorHttpRequest, } from "@polpo-ai/connect";
+import { ConnectError, connectionRequiresSecret, connectionSetupState, snapshotOAuthReconnect, matchesOAuthReconnect, matchesMcpOAuthSetup, assertConnectorRedirectAllowed, assertAllowedScopes, assertGrantedScopes, connectorHostnameIsUnsafe, createConnectorRegistry, compileConnectorDefinition, describeConnector, normalizeConnectorDefinition, normalizeConnectorAuthPolicy, normalizeScopes, resolveConnectorHttpRequest, } from "@polpo-ai/connect";
 import { ConnectionSelectionError, } from "@polpo-ai/core";
 import { lookup } from "node:dns/promises";
+import { createHash } from "node:crypto";
 import { MemoryTokenRefreshCoordinator, isVersionedConnectionSecretStore, } from "./secrets.js";
-import { createOpaqueToken, createPkcePair, parseScopes, toFormBody } from "./oauth.js";
+import { createOpaqueToken, createPkcePair, parseScopes } from "./oauth.js";
+import { requestOAuthToken } from "./oauth-token-transport.js";
+import { verifyConnectionProbe } from "./verification.js";
+import { assertRefreshAvailable, hasPendingRefresh, refreshConnectionSecret } from "./refresh-lineage.js";
+import { normalizeOAuthTokenScopes, oauthIdentityPolicyFingerprint, resolveOAuthAccountIdentity } from "./oauth-identity.js";
+import { publicNetworkFetch } from "./public-network.js";
+import { resolveMcpOAuthSetupClient, verifyMcpOAuthSetupClient } from "./mcp-setup-clients.js";
+import { observeConnectionSetupSession, cancelConnectionSetupSession } from "./setup-lifecycle.js";
 import { createMcpOAuthProtocol, } from "./mcp-oauth.js";
 export function createConnectService(options) {
     const registry = createConnectorRegistry(options.providers);
-    const fetchImpl = options.fetch ?? fetch;
+    const requireProvider = async (id, authenticationId) => {
+        if (registry.get(id))
+            return registry.require(id, authenticationId);
+        const stored = await options.definitions?.getConnectorDefinition(id);
+        if (!stored || stored.disabledAt)
+            throw new ConnectError("provider_not_found", "Active Connector not found");
+        return compileConnectorDefinition(stored.definition, authenticationId);
+    };
+    const fetchImpl = options.fetch ?? publicNetworkFetch;
     const now = options.now ?? (() => new Date());
     const tokenRefreshSkewMs = options.tokenRefreshSkewMs ?? 60_000;
     const oauthStateTtlMs = options.oauthStateTtlMs ?? 10 * 60_000;
     const setupSessionTtlMs = options.setupSessionTtlMs ?? 10 * 60_000;
     const refreshCoordinator = options.refreshCoordinator ?? new MemoryTokenRefreshCoordinator();
     const resolveHostname = options.resolveHostname ?? (async (hostname) => (await lookup(hostname, { all: true, verbatim: true })).map((entry) => entry.address));
-    const mcpOAuthFetch = async (request, init) => {
+    const mcpOAuthFetch = async (request, init) => withGatewayDeadline(10_000, init?.signal ?? undefined, async (signal) => {
         const url = new URL(request instanceof Request ? request.url : String(request));
         if (url.protocol !== "https:") {
             throw new ConnectError("oauth_discovery_failed", "MCP OAuth network requests must use HTTPS");
         }
         await assertPublicDns(url.hostname, resolveHostname);
-        return fetchImpl(request, { ...init, redirect: "error" });
-    };
+        signal.throwIfAborted();
+        const response = await fetchImpl(request, { ...init, signal, redirect: "error" });
+        const bytes = await readResponseBytes(response, 256 * 1024, signal);
+        return new Response(bytes.byteLength ? Uint8Array.from(bytes) : null, { status: response.status, headers: response.headers });
+    });
     const mcpOAuth = createMcpOAuthProtocol({
         fetch: mcpOAuthFetch,
         registrations: options.mcpOAuthRegistrations,
         now,
     });
     const mcpOAuthCallbackClaimTtlMs = options.mcpOAuthCallbackClaimTtlMs ?? 30_000;
+    const authorizeOAuth = async (operation, protocol, context) => {
+        // Pick fields explicitly: callers also hold secret-bearing states/inputs.
+        await options.authorizeOAuth?.(Object.freeze({ operation, protocol, providerId: context.providerId,
+            authenticationId: context.authenticationId, projectId: context.projectId, orgId: context.orgId,
+            connectionId: context.connectionId }));
+    };
+    const authorizeConnection = async (operation, connection, mcpOAuth = false) => {
+        if (connection.authType === "mcp" && (connection.oauthClientId || connection.oauthClientFingerprint)) {
+            await verifyMcpClient(connection.oauthClientId, connection.oauthClientFingerprint);
+        }
+        if (connection.authType === "oauth2" || (connection.authType === "mcp"
+            && (mcpOAuth || readMcpAuthMode(connection.metadata) === "oauth2"))) {
+            await authorizeOAuth(operation, connection.authType === "oauth2" ? "api" : "mcp", { ...connection, connectionId: connection.id });
+        }
+    };
+    const assertConnectionCurrent = async (connection, scopes, authorize = true) => {
+        const current = await options.store.getConnection(connection.id);
+        if (!current || current.status !== "active" || current.secretRef !== connection.secretRef
+            || current.credentialVersion !== connection.credentialVersion) {
+            throw new ConnectError("connection_revoked", "Connection changed while resolving its credential");
+        }
+        assertGrantedScopes(current.grantedScopes, scopes);
+        if (authorize)
+            await authorizeConnection("credential", current);
+        return current;
+    };
+    const recoverConnectionWrite = async (expected) => {
+        const current = await options.store.getConnection(expected.id).catch(() => null);
+        // Only a positive read of our exact generation/authority proves the write.
+        // A missing row (or failed read) does not prove a timed-out write rolled back.
+        if (current?.status === "active" && snapshotOAuthReconnect(current).authorizationFingerprint
+            === snapshotOAuthReconnect(expected).authorizationFingerprint)
+            return current;
+        return undefined;
+    };
+    const persistNewConnection = async (connection) => {
+        try {
+            return await options.store.upsertConnection(connection);
+        }
+        catch (error) {
+            const committed = await recoverConnectionWrite(connection);
+            if (committed)
+                return committed;
+            // Preserve potentially referenced secrets. Host reconciliation must establish
+            // that an uncertain write has finished before reclaiming an actual orphan.
+            throw error;
+        }
+    };
     const resolveOAuthClient = async (input) => {
         if (options.oauthClients) {
             const client = await options.oauthClients.resolve({
                 providerId: input.provider.id,
+                authenticationId: input.provider.authenticationId,
                 ...(input.projectId ? { projectId: input.projectId } : {}),
                 ...(input.orgId ? { orgId: input.orgId } : {}),
                 mode: input.mode ?? "managed",
@@ -42,6 +110,9 @@ export function createConnectService(options) {
             }
             return client;
         }
+        if (input.mode === "customer") {
+            throw new ConnectError("setup_invalid", "Customer OAuth Client resolution is not configured on this host");
+        }
         if (input.provider.auth.type !== "oauth2" || !input.provider.auth.clientId) {
             throw new ConnectError("invalid_provider", `OAuth provider "${input.provider.id}" is missing an OAuth Client resolver`);
         }
@@ -60,13 +131,20 @@ export function createConnectService(options) {
         }
         assertOAuthClient(input.provider.id, input.redirectUri, input.client);
         const auth = input.provider.auth;
-        const requestedScopes = assertAllowedScopes(input.provider, input.scopes ?? auth.defaultScopes);
+        const requestedScopes = assertAllowedScopes(input.provider, [...(input.scopes ?? auth.defaultScopes ?? []), ...(auth.identity?.requiredScopes ?? [])]);
         const state = createOpaqueToken();
         const pkce = auth.supportsPkce === false ? undefined : createPkcePair();
-        const expiresAt = new Date(now().getTime() + oauthStateTtlMs).toISOString();
+        await authorizeOAuth("authorize", "api", { ...input, providerId: input.provider.id,
+            authenticationId: input.provider.authenticationId, connectionId: input.reconnect?.connectionId });
+        const expiresAt = input.authorizationExpiresAt ?? new Date(now().getTime() + oauthStateTtlMs).toISOString();
+        if (Date.parse(expiresAt) <= now().getTime())
+            throw new ConnectError("setup_expired", "OAuth authorization window has expired");
+        input.onStateWriteAttempt?.();
         await options.store.saveOAuthState({
+            setupSessionRef: input.setupSessionRef,
             state,
             providerId: input.provider.id,
+            authenticationId: input.provider.authenticationId,
             subject: input.subject,
             requestedScopes,
             redirectUri: input.redirectUri,
@@ -79,6 +157,9 @@ export function createConnectService(options) {
             createdAt: now().toISOString(),
             metadata: input.metadata,
             oauthClientId: input.client.id,
+            oauthClientFingerprint: oauthClientFingerprint(input.provider, input.client.clientId),
+            oauthIdentityPolicyFingerprint: oauthIdentityPolicyFingerprint(auth.identity),
+            reconnect: input.reconnect,
             audience: input.audience,
             binding: input.binding,
             returnUrl: input.returnUrl,
@@ -99,26 +180,268 @@ export function createConnectService(options) {
         }
         return { authorizationUrl: url.toString(), state, expiresAt };
     };
-    const oauthAuthForConnection = async (provider, oauthClientId) => {
+    const oauthAuthForConnection = async (provider, oauthClientId, fingerprint) => {
         if (provider.auth.type !== "oauth2") {
             throw new ConnectError("unsupported_auth", `Provider "${provider.id}" does not use OAuth2 auth`);
         }
-        if (!oauthClientId || oauthClientId.startsWith("legacy:"))
+        if (!oauthClientId || oauthClientId.startsWith("legacy:")) {
+            assertOAuthClientFingerprint(provider, provider.auth.clientId, fingerprint);
             return provider.auth;
+        }
         const client = await options.oauthClients?.resolveById(oauthClientId);
-        if (!client || client.providerId !== provider.id) {
+        if (!client || client.id !== oauthClientId || client.providerId !== provider.id) {
             throw new ConnectError("refresh_unavailable", "OAuth Client is unavailable during token refresh");
         }
+        assertOAuthClientFingerprint(provider, client.clientId, fingerprint);
         return {
             ...provider.auth,
             clientId: client.clientId,
             clientSecret: client.clientSecret,
         };
     };
+    const configurationForOAuthState = async (state) => {
+        const provider = await requireProvider(state.providerId, state.authenticationId);
+        if (provider.auth.type !== "oauth2") {
+            throw new ConnectError("unsupported_auth", `Provider "${provider.id}" does not use OAuth2 auth`);
+        }
+        if (state.oauthIdentityPolicyFingerprint !== oauthIdentityPolicyFingerprint(provider.auth.identity)) {
+            throw new ConnectError("setup_invalid", "OAuth identity policy changed; restart authorization");
+        }
+        let oauthAuth = provider.auth;
+        if (state.oauthClientId && !state.oauthClientId.startsWith("legacy:")) {
+            const client = await options.oauthClients?.resolveById(state.oauthClientId);
+            if (!client || client.id !== state.oauthClientId || client.providerId !== provider.id) {
+                throw new ConnectError("setup_invalid", "OAuth Client is unavailable during callback");
+            }
+            assertOAuthClient(provider.id, state.redirectUri, client);
+            assertOAuthClientFingerprint(provider, client.clientId, state.oauthClientFingerprint);
+            oauthAuth = {
+                ...provider.auth,
+                clientId: client.clientId,
+                clientSecret: client.clientSecret,
+            };
+        }
+        else {
+            assertOAuthClientFingerprint(provider, provider.auth.clientId, state.oauthClientFingerprint);
+        }
+        return { provider: { ...provider, auth: provider.auth }, oauthAuth };
+    };
+    const requireMcpSetupHost = () => {
+        if (!options.mcpOAuthClients || !options.setupSessions?.getConnectionSetupSessionByReference
+            || !options.setupSessions.finishConnectionSetupSession || !options.store.failMcpOAuthSetup
+            || !options.store.commitMcpOAuthSetup || !options.store.getOAuthState || !options.store.claimOAuthState
+            || !options.store.releaseOAuthState || !options.links || !isVersionedConnectionSecretStore(options.secrets)) {
+            throw new ConnectError("setup_invalid", "Host does not support atomic embedded MCP OAuth setup");
+        }
+    };
+    const verifyMcpClient = async (id, fingerprint) => {
+        if (!options.mcpOAuthClients || !id || !fingerprint)
+            throw new ConnectError("setup_invalid", "MCP client configuration is unavailable");
+        return verifyMcpOAuthSetupClient(options.mcpOAuthClients, { id, fingerprint });
+    };
+    const setupForMcpState = async (state) => {
+        requireMcpSetupHost();
+        const setup = await options.setupSessions.getConnectionSetupSessionByReference(state.setupSessionRef);
+        if (!setup || !matchesMcpOAuthSetup(state, setup))
+            throw new ConnectError("setup_invalid", "MCP setup authorization changed");
+        const { client } = await verifyMcpClient(state.oauthClientId, state.oauthClientFingerprint);
+        if (state.metadata?.url !== client.resourceUrl || state.metadata?.transport !== client.transport
+            || state.metadata?.oauthClientMode !== client.registration.mode || state.redirectUri !== client.redirectUri) {
+            throw new ConnectError("setup_invalid", "MCP OAuth state does not match its client configuration");
+        }
+        return setup;
+    };
+    const currentMcpMaterial = async (material, id, fingerprint) => {
+        if (!id && !fingerprint)
+            return material;
+        const { client } = await verifyMcpClient(id, fingerprint);
+        return client.registration.mode === "pre_registered" ? { ...material, client: client.registration.client } : material;
+    };
+    const beginMcpOAuth = async (input, setupContext) => {
+        if (!options.store.getOAuthState || !options.store.claimOAuthState || !options.store.releaseOAuthState
+            || !(setupContext ? options.store.commitMcpOAuthSetup : options.store.commitMcpOAuthConnection)
+            || !isVersionedConnectionSecretStore(options.secrets)) {
+            throw new ConnectError("setup_invalid", "Host must support atomic MCP OAuth activation and versioned secrets");
+        }
+        const identity = normalizeCreationIdentity(input);
+        const provider = await requireProvider(input.providerId ?? "mcp_url", input.authenticationId);
+        if (provider.auth.type !== "mcp") {
+            throw new ConnectError("unsupported_auth", `Provider "${provider.id}" does not use MCP auth`);
+        }
+        if (provider.authenticationId && provider.auth.auth !== "oauth2") {
+            throw new ConnectError("unsupported_auth", "Selected MCP authentication does not support OAuth");
+        }
+        await authorizeOAuth("authorize", "mcp", { ...input, providerId: provider.id });
+        const url = normalizeMcpUrl(input.url, false);
+        const transport = input.transport ?? "http";
+        const requestedScopes = assertAllowedScopes(provider, input.scopes ?? provider.auth.defaultScopes);
+        const state = createOpaqueToken();
+        const pendingConnectionId = createId("conn");
+        const temporarySecretRef = createId("connsec");
+        const started = await mcpOAuth.start({
+            url,
+            transport,
+            redirectUri: input.redirectUri,
+            state,
+            scopes: requestedScopes,
+            mode: input.mode,
+            clientName: input.clientName,
+            clientUri: input.clientUri,
+            clientMetadataUrl: input.clientMetadataUrl,
+            preRegisteredClient: input.preRegisteredClient,
+            registrationNamespace: setupContext?.fingerprint,
+        });
+        const createdAt = now();
+        const expiresAt = new Date(setupContext?.authorizationExpiresAt ?? createdAt.getTime() + oauthStateTtlMs);
+        if (!(expiresAt.getTime() > createdAt.getTime()))
+            throw new ConnectError("setup_expired", "Setup authorization expired during discovery");
+        if (setupContext)
+            await verifyMcpClient(setupContext.clientId, setupContext.fingerprint);
+        await authorizeOAuth("authorize", "mcp", { ...input, providerId: provider.id });
+        await options.secrets.setSecret(temporarySecretRef, {
+            kind: "mcp",
+            mcpOAuth: started.material,
+        });
+        try {
+            setupContext?.onStateWriteAttempt();
+            await options.store.saveOAuthState({
+                ...(setupContext ? { setupSessionRef: setupContext.reference, oauthClientId: setupContext.clientId,
+                    oauthClientFingerprint: setupContext.fingerprint, returnUrl: setupContext.returnUrl } : {}),
+                state,
+                providerId: provider.id,
+                authenticationId: provider.authenticationId,
+                flowKind: "mcp",
+                status: "pending",
+                subject: identity.subject,
+                audience: identity.audience,
+                binding: identity.binding,
+                requestedScopes,
+                redirectUri: started.material.redirectUri,
+                projectId: input.projectId,
+                orgId: input.orgId,
+                connectionName: input.name,
+                temporarySecretRef,
+                createdAt: createdAt.toISOString(),
+                expiresAt: expiresAt.toISOString(),
+                metadata: {
+                    ...omitMcpDiscoveryMetadata(input.metadata),
+                    url,
+                    transport,
+                    auth: "oauth2",
+                    oauthClientMode: input.mode,
+                    pendingConnectionId,
+                },
+            });
+        }
+        catch (error) {
+            const committed = await options.store.getOAuthState?.(state).catch(() => null);
+            if (committed?.status !== "pending" || committed.temporarySecretRef !== temporarySecretRef
+                || committed.metadata?.pendingConnectionId !== pendingConnectionId)
+                throw error;
+        }
+        return { authorizationUrl: started.authorizationUrl, state, expiresAt: expiresAt.toISOString() };
+    };
     return {
         listProviders() {
             return registry.list();
         },
+        async listCatalog() {
+            const custom = await options.definitions?.listConnectorDefinitions() ?? [];
+            return [...registry.catalog(), ...custom.filter((record) => !record.disabledAt && !registry.get(record.definition.id))
+                    .map((record) => describeConnector(record.definition))];
+        },
+        async getSetupReadiness(input) {
+            const provider = await requireProvider(input.providerId, input.authenticationId);
+            const catalog = describeConnector(provider);
+            const base = {
+                providerId: provider.id,
+                authenticationId: provider.authenticationId ?? catalog.defaultAuthenticationId,
+                check: "configuration", outcome: "passed", code: "ready", checkedAt: now().toISOString(),
+                configurationVersion: createHash("sha256").update(JSON.stringify(catalog)).digest("hex"),
+            };
+            if (catalog.kind === "credential")
+                return { ...base, outcome: "unsupported", code: "credential_only" };
+            if (provider.auth.type === "mcp") {
+                return { ...base, outcome: "inconclusive", code: "discovery_required", nextStep: "mcp_discovery" };
+            }
+            if (provider.auth.type === "none")
+                return { ...base, nextStep: "create" };
+            if (provider.auth.type === "api_key")
+                return { ...base, code: "credentials_required", nextStep: "credentials" };
+            if (!input.redirectUri)
+                return { ...base, outcome: "failed", code: "callback_required" };
+            try {
+                const client = await resolveOAuthClient({
+                    provider, projectId: input.projectId, orgId: input.orgId,
+                    redirectUri: input.redirectUri, mode: input.oauthClientMode,
+                });
+                return {
+                    ...base, code: "consent_required", nextStep: "oauth_consent",
+                    configurationVersion: createHash("sha256").update(JSON.stringify([
+                        base.configurationVersion, oauthClientFingerprint(provider, client.clientId), input.redirectUri, input.oauthClientMode,
+                    ])).digest("hex"),
+                };
+            }
+            catch (error) {
+                return { ...base, outcome: error instanceof ConnectError ? "failed" : "inconclusive",
+                    code: error instanceof ConnectError ? error.code : "configuration_unavailable" };
+            }
+        },
+        async registerConnectorDefinition(input) {
+            if (!options.definitions)
+                throw new ConnectError("setup_invalid", "Custom Connector storage is not configured on this host");
+            if (!input || typeof input !== "object" || Array.isArray(input))
+                throw new ConnectError("invalid_provider", "Connector definition must be an object");
+            let definition;
+            try {
+                definition = normalizeConnectorDefinition({ ...input, source: "custom" });
+            }
+            catch (error) {
+                if (error instanceof ConnectError)
+                    throw error;
+                throw new ConnectError("invalid_provider", "Connector definition has an invalid HTTP policy or configuration");
+            }
+            if (registry.get(definition.id))
+                throw new ConnectError("invalid_provider", "Connector id is reserved by the host catalog");
+            const record = { definition, createdAt: now().toISOString() };
+            await options.definitions.createConnectorDefinition(record);
+            return record;
+        },
+        async disableConnectorDefinition(id) {
+            if (!options.definitions)
+                throw new ConnectError("setup_invalid", "Custom Connector storage is not configured on this host");
+            if (registry.get(id))
+                throw new ConnectError("invalid_provider", "Host catalog Connectors cannot be disabled through custom registration");
+            return options.definitions.disableConnectorDefinition(id, now().toISOString());
+        },
+        async verifyConnection(input) {
+            const connection = await options.store.getConnection(input.connectionId);
+            if (!connection)
+                throw new ConnectError("connection_not_found", "Connection not found");
+            const provider = await requireProvider(connection.providerId, connection.authenticationId);
+            let result = await verifyConnectionProbe(this, input, connection, provider, {
+                checkedAt: now().toISOString(),
+                configurationVersion: createHash("sha256").update(JSON.stringify([
+                    describeConnector(provider), provider.authenticationId,
+                ])).digest("hex"),
+            }, options.verifyMcp ? (probe) => withGatewayDeadline(30_000, probe.signal, (signal) => options.verifyMcp({ ...probe, signal, beforeDispatch: async () => {
+                    signal.throwIfAborted();
+                    const current = await assertConnectionCurrent(probe.connection, probe.credential.scopes);
+                    await options.beforeDispatch?.(current);
+                    await assertConnectionCurrent(probe.connection, probe.credential.scopes);
+                    signal.throwIfAborted();
+                } })) : undefined);
+            const current = await options.store.getConnection(connection.id);
+            if (!current || current.status !== connection.status || current.secretRef !== connection.secretRef
+                || (current.credentialVersion ?? current.updatedAt) !== result.credentialVersion) {
+                result = { ...result, outcome: "inconclusive", code: "connection_changed", account: undefined, toolCount: undefined };
+            }
+            if (result.outcome === "passed" && result.account) {
+                await options.store.updateConnection(connection.id, { providerAccountId: result.account.id });
+            }
+            await options.verifications?.saveConnectionVerification(result);
+            return result;
+        },
         listConnections(filter) {
             return options.store.listConnections(filter);
         },
@@ -169,11 +492,12 @@ export function createConnectService(options) {
             });
         },
         async createApiKeyConnection(input) {
-            const provider = registry.require(input.providerId);
+            const identity = normalizeCreationIdentity(input);
+            const provider = await requireProvider(input.providerId, input.authenticationId);
             if (provider.auth.type !== "api_key") {
                 throw new ConnectError("unsupported_auth", `Provider "${provider.id}" does not use API-key auth`);
             }
-            const apiKey = input.apiKey.trim();
+            const apiKey = typeof input.apiKey === "string" ? input.apiKey.trim() : "";
             if (!apiKey) {
                 throw new ConnectError("invalid_request", "API key cannot be empty");
             }
@@ -185,15 +509,19 @@ export function createConnectService(options) {
                 apiKey,
                 ...(input.secretMetadata ? { metadata: input.secretMetadata } : {}),
             });
-            return options.store.upsertConnection({
+            return persistNewConnection({
                 id,
                 providerId: provider.id,
+                authenticationId: provider.authenticationId,
                 name: input.name,
                 projectId: input.projectId,
                 orgId: input.orgId,
-                owner: input.subject,
+                owner: identity.subject,
+                audience: identity.audience,
+                binding: identity.binding,
                 authType: "api_key",
                 status: "active",
+                credentialVersion: createId("credver"),
                 grantedScopes,
                 secretRef,
                 createdAt: now().toISOString(),
@@ -201,8 +529,26 @@ export function createConnectService(options) {
                 metadata: input.metadata,
             });
         },
+        async createPublicConnection(input) {
+            const identity = normalizeCreationIdentity(input);
+            const provider = await requireProvider(input.providerId, input.authenticationId);
+            if (provider.auth.type !== "none" || !provider.http) {
+                throw new ConnectError("unsupported_auth", `Provider "${provider.id}" does not support public HTTP access`);
+            }
+            const grantedScopes = assertAllowedScopes(provider, input.scopes ?? provider.auth.defaultScopes);
+            const timestamp = now().toISOString();
+            return options.store.upsertConnection({
+                id: createId("conn"), providerId: provider.id, authenticationId: provider.authenticationId,
+                name: input.name, projectId: input.projectId, orgId: input.orgId, owner: identity.subject,
+                audience: identity.audience, binding: identity.binding,
+                authType: "none", status: "active", grantedScopes,
+                credentialVersion: createId("credver"),
+                createdAt: timestamp, updatedAt: timestamp, metadata: input.metadata,
+            });
+        },
         async createMcpConnection(input) {
-            const provider = registry.require(input.providerId ?? "mcp_url");
+            const identity = normalizeCreationIdentity(input);
+            const provider = await requireProvider(input.providerId ?? "mcp_url", input.authenticationId);
             if (provider.auth.type !== "mcp") {
                 throw new ConnectError("unsupported_auth", `Provider "${provider.id}" does not use MCP auth`);
             }
@@ -210,23 +556,31 @@ export function createConnectService(options) {
             if (transport !== "http" && transport !== "sse") {
                 throw new ConnectError("invalid_request", "MCP transport must be http or sse");
             }
-            const auth = input.auth ?? (provider.auth.auth === "none" ? "none" : "bearer");
-            if (auth !== "none" && auth !== "bearer") {
-                throw new ConnectError("invalid_request", "MCP auth must be none or bearer");
+            const selectedAuth = provider.auth.auth ?? "bearer";
+            const auth = input.auth ?? selectedAuth;
+            if (provider.authenticationId && auth !== selectedAuth) {
+                throw new ConnectError("unsupported_auth", "MCP authentication does not match the selected method");
             }
+            if (auth !== "none" && auth !== "bearer" && auth !== "header") {
+                throw new ConnectError("unsupported_auth", "MCP OAuth must use the OAuth authorization flow");
+            }
+            const headerName = auth === "header" ? normalizeConnectorAuthPolicy({
+                mode: "header", name: provider.auth.headerName ?? (!provider.authenticationId ? input.headerName : undefined),
+            }).name : undefined;
             const url = normalizeMcpUrl(input.url, options.allowInsecureLocalMcpUrls === true);
             const apiKey = (input.bearerToken ?? input.apiKey ?? "").trim();
-            if (auth === "bearer" && !apiKey) {
-                throw new ConnectError("invalid_request", "MCP bearer auth requires a token");
+            if (auth !== "none" && !apiKey) {
+                throw new ConnectError("invalid_request", "MCP authenticated access requires a token");
             }
             const grantedScopes = assertAllowedScopes(provider, input.scopes ?? provider.auth.defaultScopes);
             const id = createId("conn");
-            const secretRef = auth === "bearer" ? createId("connsec") : undefined;
+            const secretRef = auth !== "none" ? createId("connsec") : undefined;
             const metadata = {
-                ...(input.metadata ?? {}),
+                ...omitMcpDiscoveryMetadata(input.metadata),
                 url,
                 transport,
                 auth,
+                headerName,
             };
             if (secretRef) {
                 await options.secrets.setSecret(secretRef, {
@@ -235,15 +589,19 @@ export function createConnectService(options) {
                     metadata: { tokenType: "Bearer" },
                 });
             }
-            return options.store.upsertConnection({
+            return persistNewConnection({
                 id,
                 providerId: provider.id,
+                authenticationId: provider.authenticationId,
                 name: input.name,
                 projectId: input.projectId,
                 orgId: input.orgId,
-                owner: input.subject,
+                owner: identity.subject,
+                audience: identity.audience,
+                binding: identity.binding,
                 authType: "mcp",
                 status: "active",
+                credentialVersion: createId("credver"),
                 grantedScopes,
                 secretRef,
                 createdAt: now().toISOString(),
@@ -255,87 +613,47 @@ export function createConnectService(options) {
             return mcpOAuth.inspect({ url: input.url, transport: input.transport });
         },
         async startMcpOAuth(input) {
-            const provider = registry.require(input.providerId ?? "mcp_url");
-            if (provider.auth.type !== "mcp") {
-                throw new ConnectError("unsupported_auth", `Provider "${provider.id}" does not use MCP auth`);
-            }
-            const url = normalizeMcpUrl(input.url, false);
-            const transport = input.transport ?? "http";
-            const requestedScopes = normalizeScopes(input.scopes ?? provider.auth.defaultScopes ?? []);
-            const state = createOpaqueToken();
-            const pendingConnectionId = createId("conn");
-            const temporarySecretRef = createId("connsec");
-            const started = await mcpOAuth.start({
-                url,
-                transport,
-                redirectUri: input.redirectUri,
-                state,
-                scopes: requestedScopes,
-                mode: input.mode,
-                clientName: input.clientName,
-                clientUri: input.clientUri,
-                clientMetadataUrl: input.clientMetadataUrl,
-                preRegisteredClient: input.preRegisteredClient,
-            });
-            const createdAt = now();
-            const expiresAt = new Date(createdAt.getTime() + oauthStateTtlMs);
-            await options.secrets.setSecret(temporarySecretRef, {
-                kind: "mcp",
-                mcpOAuth: started.material,
-            });
-            try {
-                await options.store.saveOAuthState({
-                    state,
-                    providerId: provider.id,
-                    flowKind: "mcp",
-                    status: "pending",
-                    subject: input.subject,
-                    requestedScopes,
-                    redirectUri: started.material.redirectUri,
-                    projectId: input.projectId,
-                    orgId: input.orgId,
-                    connectionName: input.name,
-                    temporarySecretRef,
-                    createdAt: createdAt.toISOString(),
-                    expiresAt: expiresAt.toISOString(),
-                    metadata: {
-                        ...(input.metadata ?? {}),
-                        url,
-                        transport,
-                        auth: "oauth2",
-                        oauthClientMode: input.mode,
-                        pendingConnectionId,
-                    },
-                });
-            }
-            catch (error) {
-                await options.secrets.deleteSecret(temporarySecretRef).catch(() => undefined);
-                throw error;
-            }
-            return { authorizationUrl: started.authorizationUrl, state, expiresAt: expiresAt.toISOString() };
+            // Private setup context is a separate argument: spreading runtime extras
+            // or metadata into direct-start input cannot establish setup authority.
+            return beginMcpOAuth(input);
         },
         async completeMcpOAuth(input) {
             const store = options.store;
-            if (!store.getOAuthState || !store.claimOAuthState || !store.completeOAuthState || !store.releaseOAuthState) {
+            if (!store.getOAuthState || !store.claimOAuthState || !store.releaseOAuthState
+                || !isVersionedConnectionSecretStore(options.secrets)) {
                 throw new ConnectError("setup_invalid", "Host store does not support retry-safe MCP OAuth callbacks");
             }
             const current = await store.getOAuthState(input.state);
             if (!current || current.flowKind !== "mcp") {
                 throw new ConnectError("oauth_state_not_found", "MCP OAuth state was not found");
             }
+            await authorizeOAuth("callback", "mcp", current);
+            const setup = current.setupSessionRef ? await setupForMcpState(current) : undefined;
+            if (!setup && !store.commitMcpOAuthConnection)
+                throw new ConnectError("setup_invalid", "Host does not support atomic MCP OAuth activation");
             if (current.status === "completed" && current.completedConnectionId) {
                 const completed = await store.getConnection(current.completedConnectionId);
-                if (completed)
+                if (setup) {
+                    const links = await options.links.listConnectionLinks({ connectionId: current.completedConnectionId, projectId: setup.projectId, status: "active" });
+                    if (setup.status !== "completed" || setup.resultingConnectionId !== current.completedConnectionId || !links.length) {
+                        throw new ConnectError("setup_invalid", "Completed MCP setup link is no longer active");
+                    }
+                }
+                if (completed?.status === "active")
                     return completed;
+                throw new ConnectError("connection_revoked", "Completed MCP account is no longer active");
             }
             if (new Date(current.expiresAt).getTime() <= now().getTime()) {
                 throw new ConnectError("oauth_state_expired", "MCP OAuth state has expired");
             }
-            if (input.error) {
-                throw new ConnectError("oauth_error", input.errorDescription ?? input.error);
-            }
-            if (!input.code)
+            if (setup && connectionSetupState(setup) !== "started")
+                throw new ConnectError("setup_invalid", "MCP setup is no longer active");
+            if (!input.error && !input.code)
                 throw new ConnectError("invalid_request", "OAuth callback is missing code");
+            const provider = await requireProvider(current.providerId, current.authenticationId);
+            if (provider.auth.type !== "mcp" || (provider.authenticationId && provider.auth.auth !== "oauth2")) {
+                throw new ConnectError("unsupported_auth", "MCP OAuth authentication is no longer supported");
+            }
             const claimToken = createOpaqueToken();
             const claimed = await store.claimOAuthState(input.state, claimToken, new Date(now().getTime() + mcpOAuthCallbackClaimTtlMs).toISOString(), now().toISOString());
             if (!claimed) {
@@ -345,50 +663,75 @@ export function createConnectService(options) {
                 ? claimed.metadata.pendingConnectionId
                 : undefined;
             try {
-                if (pendingConnectionId) {
-                    const existing = await store.getConnection(pendingConnectionId);
-                    if (existing?.status === "active") {
-                        await store.completeOAuthState(input.state, claimToken, existing.id);
-                        return existing;
+                if (input.error) {
+                    if (claimed.setupSessionRef && !await store.failMcpOAuthSetup({ state: input.state, setupReference: claimed.setupSessionRef,
+                        claimToken, now: now().toISOString() })) {
+                        throw new ConnectError("oauth_callback_in_progress", "MCP OAuth callback no longer owns the setup");
                     }
+                    throw new ConnectError("oauth_error", input.errorDescription ?? input.error);
                 }
                 if (!claimed.temporarySecretRef) {
                     throw new ConnectError("secret_not_found", "MCP OAuth transient secret is missing");
                 }
-                const transient = await options.secrets.getSecret(claimed.temporarySecretRef);
+                const generation = await options.secrets.getVersioned(claimed.temporarySecretRef);
+                const transient = generation?.secret;
                 if (!transient?.mcpOAuth) {
                     throw new ConnectError("secret_not_found", "MCP OAuth transient material is unavailable");
                 }
-                const tokens = await mcpOAuth.complete({
-                    material: transient.mcpOAuth,
+                // The authorization code is one-time. If persistence failed after
+                // exchange, reuse the staged encrypted tokens when retrying the claim.
+                await authorizeOAuth("callback", "mcp", claimed);
+                const currentMaterial = await currentMcpMaterial(transient.mcpOAuth, claimed.oauthClientId, claimed.oauthClientFingerprint);
+                const tokens = transient.mcpOAuth.tokens ?? await mcpOAuth.complete({
+                    material: currentMaterial,
                     code: input.code,
                     requestedScopes: claimed.requestedScopes,
                 });
-                const grantedScopes = normalizeScopes(tokens.scopes ?? claimed.requestedScopes);
+                assertGrantedScopes(tokens.scopes ?? claimed.requestedScopes, claimed.requestedScopes);
+                const grantedScopes = assertAllowedScopes(provider, claimed.requestedScopes);
                 const material = {
-                    ...transient.mcpOAuth,
+                    ...currentMaterial,
                     codeVerifier: undefined,
                     tokens,
                 };
-                await options.secrets.setSecret(claimed.temporarySecretRef, { kind: "mcp", mcpOAuth: material });
+                if (!transient.mcpOAuth.tokens && !await options.secrets.compareAndSet(claimed.temporarySecretRef, generation.version, { kind: "mcp", mcpOAuth: material }))
+                    throw new ConnectError("oauth_callback_in_progress", "MCP OAuth token generation changed; retry callback");
+                // Keep the spent code's result encrypted for retry, but never activate
+                // an account when the host disabled OAuth while exchanging/staging it.
+                await authorizeOAuth("callback", "mcp", claimed);
                 const id = pendingConnectionId ?? createId("conn");
-                const connection = await store.upsertConnection({
+                if (claimed.setupSessionRef)
+                    await setupForMcpState(claimed);
+                const record = {
                     id,
                     providerId: claimed.providerId,
+                    authenticationId: claimed.authenticationId,
                     name: claimed.connectionName,
-                    projectId: claimed.projectId,
+                    projectId: claimed.setupSessionRef ? undefined : claimed.projectId,
+                    oauthClientId: claimed.oauthClientId,
+                    oauthClientFingerprint: claimed.oauthClientFingerprint,
                     orgId: claimed.orgId,
                     owner: claimed.subject,
+                    audience: claimed.audience,
+                    binding: claimed.binding,
                     authType: "mcp",
                     status: "active",
+                    credentialVersion: createId("credver"),
                     grantedScopes,
                     secretRef: claimed.temporarySecretRef,
                     tokenExpiresAt: tokens.expiresAt,
                     createdAt: now().toISOString(),
                     updatedAt: now().toISOString(),
                     metadata: omitInternalMcpStateMetadata(claimed.metadata),
-                });
-                await store.completeOAuthState(input.state, claimToken, connection.id);
+                };
+                const commit = { state: input.state, claimToken, now: now().toISOString(), connection: record };
+                const connection = claimed.setupSessionRef
+                    ? await store.commitMcpOAuthSetup({ ...commit, setupReference: claimed.setupSessionRef,
+                        link: { id: `connlink_${id}`, connectionId: id, projectId: claimed.projectId, status: "active",
+                            createdAt: record.createdAt, updatedAt: record.updatedAt } })
+                    : await store.commitMcpOAuthConnection(commit);
+                if (!connection)
+                    throw new ConnectError("oauth_callback_in_progress", "MCP OAuth claim changed before activation; retry callback");
                 return connection;
             }
             catch (error) {
@@ -398,50 +741,69 @@ export function createConnectService(options) {
             }
         },
         async createSetupSession(input) {
-            if (!options.setupSessions || !options.oauthClients) {
+            if (!options.setupSessions) {
                 throw new ConnectError("setup_invalid", "Connection setup sessions are not configured on this host");
             }
-            const provider = registry.require(requiredText("providerId", input.providerId));
-            if (provider.auth.type !== "oauth2") {
+            const provider = await requireProvider(requiredText("providerId", input.providerId), input.authenticationId);
+            const mcp = provider.auth.type === "mcp";
+            if (provider.auth.type !== "oauth2" && (!mcp || (provider.authenticationId && provider.auth.type === "mcp" && provider.auth.auth !== "oauth2"))) {
                 throw new ConnectError("unsupported_auth", `Provider "${provider.id}" does not use OAuth2 auth`);
             }
             const projectId = requiredText("projectId", input.projectId);
+            if (mcp)
+                requireMcpSetupHost();
+            else if (!options.oauthClients)
+                throw new ConnectError("setup_invalid", "OAuth Clients are not configured");
+            await authorizeOAuth("setup", mcp ? "mcp" : "api", { ...input, projectId });
             if (!["personal", "shared", "end_user"].includes(input.audience)) {
                 throw new ConnectError("setup_invalid", "Connection setup audience is invalid");
             }
+            const identity = normalizeSetupIdentity(input.audience, input.subject, input.binding);
             const returnUrl = normalizeReturnUrl(input.returnUrl, options.allowedReturnUrlOrigins);
-            const scopes = assertAllowedScopes(provider, input.scopes ?? provider.auth.defaultScopes);
-            const client = await resolveOAuthClient({
-                provider,
-                projectId,
-                ...(input.orgId ? { orgId: requiredText("orgId", input.orgId) } : {}),
-                redirectUri: "",
-                mode: input.oauthClientMode,
-            });
-            if (client.redirectUris.length === 0) {
+            const scopes = assertAllowedScopes(provider, [...(input.scopes ?? provider.auth.defaultScopes ?? []), ...(provider.auth.type === "oauth2" ? provider.auth.identity?.requiredScopes ?? [] : [])]);
+            const mcpClient = mcp ? await resolveMcpOAuthSetupClient(options.mcpOAuthClients, {
+                providerId: provider.id, authenticationId: provider.authenticationId, projectId, orgId: input.orgId,
+                configurationId: input.configurationId, mode: input.oauthClientMode,
+            }) : undefined;
+            const client = mcp ? undefined : await resolveOAuthClient({ provider, projectId,
+                ...(input.orgId ? { orgId: requiredText("orgId", input.orgId) } : {}), redirectUri: "", mode: input.oauthClientMode });
+            if (client && client.redirectUris.length === 0)
                 throw new ConnectError("setup_invalid", "OAuth Client has no registered redirect URI");
-            }
             const timestamp = now().toISOString();
             const setup = {
                 id: createId("connsetup"),
                 providerId: provider.id,
-                oauthClientId: client.id,
+                authenticationId: provider.authenticationId,
+                ...(mcp ? { flowKind: "mcp" } : {}),
+                oauthClientId: mcpClient?.reference.id ?? client.id,
+                oauthClientFingerprint: mcpClient?.reference.fingerprint ?? oauthClientFingerprint(provider, client.clientId),
+                oauthIdentityPolicyFingerprint: oauthIdentityPolicyFingerprint(provider.auth.type === "oauth2" ? provider.auth.identity : undefined),
                 projectId,
                 ...(input.orgId ? { orgId: requiredText("orgId", input.orgId) } : {}),
                 audience: input.audience,
-                subject: normalizeConnectionOwner(input.subject),
-                ...(input.binding ? { binding: normalizeConnectionBinding(input.binding) } : {}),
+                ...identity,
                 scopes,
                 returnUrl,
                 expiresAt: new Date(now().getTime() + setupSessionTtlMs).toISOString(),
                 createdAt: timestamp,
                 ...(input.metadata ? { metadata: input.metadata } : {}),
             };
+            await authorizeOAuth("setup", mcp ? "mcp" : "api", setup);
             await options.setupSessions.saveConnectionSetupSession(setup);
             return setup;
         },
+        async getSetupStatus(id) {
+            if (!options.setupSessions)
+                throw new ConnectError("setup_invalid", "Connection setup sessions are not configured on this host");
+            return observeConnectionSetupSession(options.setupSessions, id, now);
+        },
+        async cancelSetupSession(id) {
+            if (!options.setupSessions)
+                throw new ConnectError("setup_invalid", "Connection setup sessions are not configured on this host");
+            return cancelConnectionSetupSession(options.setupSessions, id, now);
+        },
         async startOAuthSetup(input) {
-            if (!options.setupSessions || !options.oauthClients) {
+            if (!options.setupSessions) {
                 throw new ConnectError("setup_invalid", "Connection setup sessions are not configured on this host");
             }
             const setupSessionId = requiredText("setupSessionId", input.setupSessionId);
@@ -449,41 +811,83 @@ export function createConnectService(options) {
             if (!existing) {
                 throw new ConnectError("setup_invalid", "Connection setup session was not found");
             }
-            if (existing.consumedAt) {
+            if (existing.consumedAt || connectionSetupState(existing) !== "pending") {
                 throw new ConnectError("setup_consumed", "Connection setup session has already been used");
             }
             if (new Date(existing.expiresAt).getTime() <= now().getTime()) {
                 throw new ConnectError("setup_expired", "Connection setup session has expired");
             }
-            const setup = await options.setupSessions.consumeConnectionSetupSession(setupSessionId, now().toISOString());
+            if (existing.flowKind === "mcp")
+                requireMcpSetupHost();
+            else if (!options.oauthClients)
+                throw new ConnectError("setup_invalid", "OAuth Clients are not configured");
+            await authorizeOAuth("authorize", existing.flowKind === "mcp" ? "mcp" : "api", existing);
+            const consumedAt = now();
+            const authorizationExpiresAt = new Date(consumedAt.getTime() + oauthStateTtlMs).toISOString();
+            const setup = await options.setupSessions.consumeConnectionSetupSession(setupSessionId, consumedAt.toISOString(), authorizationExpiresAt);
             if (!setup) {
+                if (Date.parse(existing.expiresAt) <= now().getTime())
+                    throw new ConnectError("setup_expired", "Connection setup session has expired");
                 throw new ConnectError("setup_consumed", "Connection setup session has already been used");
             }
-            const provider = registry.require(setup.providerId);
-            const client = await options.oauthClients.resolveById(setup.oauthClientId);
-            if (!client || client.providerId !== provider.id) {
-                throw new ConnectError("setup_invalid", "Connection setup OAuth Client is unavailable");
+            let stateWriteAttempted = false;
+            try {
+                const provider = await requireProvider(setup.providerId, setup.authenticationId);
+                if (setup.flowKind === "mcp") {
+                    if (provider.auth.type !== "mcp")
+                        throw new ConnectError("setup_invalid", "MCP Connector changed");
+                    const { client, reference } = await verifyMcpClient(setup.oauthClientId, setup.oauthClientFingerprint);
+                    const registration = client.registration;
+                    return await beginMcpOAuth({ providerId: setup.providerId, authenticationId: setup.authenticationId,
+                        projectId: setup.projectId, orgId: setup.orgId, audience: setup.audience, subject: setup.subject, binding: setup.binding,
+                        url: client.resourceUrl, transport: client.transport, redirectUri: client.redirectUri, scopes: setup.scopes,
+                        mode: registration.mode, metadata: setup.metadata,
+                        ...(registration.mode === "dynamic" ? { clientName: registration.clientName, clientUri: registration.clientUri }
+                            : registration.mode === "metadata_document" ? { clientMetadataUrl: registration.clientMetadataUrl }
+                                : { preRegisteredClient: registration.client }),
+                    }, { reference: setup.reference ?? setup.id, clientId: reference.id, fingerprint: reference.fingerprint,
+                        returnUrl: setup.returnUrl, authorizationExpiresAt, onStateWriteAttempt: () => { stateWriteAttempted = true; } });
+                }
+                if (setup.oauthIdentityPolicyFingerprint !== oauthIdentityPolicyFingerprint(provider.auth.type === "oauth2" ? provider.auth.identity : undefined)) {
+                    throw new ConnectError("setup_invalid", "OAuth identity policy changed; restart setup");
+                }
+                const client = await options.oauthClients.resolveById(setup.oauthClientId);
+                if (!client || client.providerId !== provider.id) {
+                    throw new ConnectError("setup_invalid", "Connection setup OAuth Client is unavailable");
+                }
+                assertOAuthClientFingerprint(provider, client.clientId, setup.oauthClientFingerprint);
+                const identity = normalizeSetupIdentity(setup.audience, setup.subject, setup.binding);
+                const redirectUri = client.redirectUris[0];
+                return await beginOAuth({
+                    onStateWriteAttempt: () => { stateWriteAttempted = true; },
+                    setupSessionRef: setup.reference ?? setup.id,
+                    authorizationExpiresAt,
+                    provider,
+                    client,
+                    scopes: setup.scopes,
+                    subject: identity.subject,
+                    redirectUri,
+                    projectId: setup.projectId,
+                    orgId: setup.orgId,
+                    metadata: setup.metadata,
+                    audience: setup.audience,
+                    binding: identity.binding,
+                    returnUrl: setup.returnUrl,
+                });
+            }
+            catch (error) {
+                // A lost OAuth-state write acknowledgement is not proof no state exists.
+                if (!stateWriteAttempted)
+                    await options.setupSessions.finishConnectionSetupSession?.(setup.reference ?? setup.id, { status: "error" }, now().toISOString()).catch(() => undefined);
+                throw error;
             }
-            const redirectUri = client.redirectUris[0];
-            return beginOAuth({
-                provider,
-                client,
-                scopes: setup.scopes,
-                subject: setup.subject,
-                redirectUri,
-                projectId: setup.projectId,
-                orgId: setup.orgId,
-                metadata: setup.metadata,
-                audience: setup.audience,
-                binding: setup.binding,
-                returnUrl: setup.returnUrl,
-            });
         },
         async startOAuth(input) {
-            const provider = registry.require(input.providerId);
+            const provider = await requireProvider(input.providerId, input.authenticationId);
             if (provider.auth.type !== "oauth2") {
                 throw new ConnectError("unsupported_auth", `Provider "${provider.id}" does not use OAuth2 auth`);
             }
+            await authorizeOAuth("authorize", "api", input);
             const client = await resolveOAuthClient({
                 provider,
                 projectId: input.projectId,
@@ -491,96 +895,218 @@ export function createConnectService(options) {
                 redirectUri: input.redirectUri,
                 mode: input.oauthClientMode,
             });
-            return beginOAuth({ ...input, provider, client });
+            return beginOAuth({ ...input, provider, client, setupSessionRef: undefined, authorizationExpiresAt: undefined, onStateWriteAttempt: undefined });
+        },
+        async reconnectOAuth(input) {
+            const connection = await options.store.getConnection(input.connectionId);
+            if (!connection)
+                throw new ConnectError("connection_not_found", "Connection not found");
+            if (connection.authType !== "oauth2") {
+                throw new ConnectError("unsupported_auth", "Only OAuth2 Connections can use OAuth reconnect");
+            }
+            if ((input.orgId && connection.orgId && input.orgId !== connection.orgId)
+                || (input.projectId && connection.projectId && input.projectId !== connection.projectId)) {
+                throw new ConnectError("policy_denied", "Connection belongs to a different organization or project");
+            }
+            if (!connection.oauthClientId || connection.oauthClientId.startsWith("legacy:")) {
+                throw new ConnectError("setup_invalid", "The original OAuth Client is not recorded; create a new Connection with an explicit OAuth app");
+            }
+            const provider = await requireProvider(connection.providerId, connection.authenticationId);
+            if (provider.auth.type !== "oauth2" || !provider.auth.identity || !connection.oauthIdentity
+                || connection.oauthIdentity.policyFingerprint !== oauthIdentityPolicyFingerprint(provider.auth.identity)
+                || provider.auth.identity.requiredScopes.some(scope => !connection.grantedScopes.includes(scope))) {
+                throw new ConnectError("setup_invalid", "Same-account reconnect requires a verified account identity; create a new Connection");
+            }
+            if (!options.store.replaceOAuthCredential) {
+                throw new ConnectError("setup_invalid", "This host does not support atomic OAuth reconnect");
+            }
+            if (connection.status !== "active")
+                throw new ConnectError("connection_revoked", "A revoked Connection cannot be reconnected");
+            await authorizeOAuth("authorize", "api", { ...connection, connectionId: connection.id,
+                projectId: input.projectId ?? connection.projectId, orgId: connection.orgId ?? input.orgId });
+            const client = await options.oauthClients?.resolveById(connection.oauthClientId);
+            if (!client || client.id !== connection.oauthClientId || client.providerId !== connection.providerId) {
+                throw new ConnectError("setup_invalid", "The original OAuth Client is unavailable; restore it or create a new Connection");
+            }
+            assertOAuthClientFingerprint(provider, client.clientId, connection.oauthClientFingerprint);
+            return beginOAuth({
+                provider,
+                client,
+                scopes: connection.grantedScopes,
+                subject: connection.owner,
+                redirectUri: input.redirectUri,
+                projectId: input.projectId ?? connection.projectId,
+                orgId: connection.orgId ?? input.orgId,
+                connectionName: connection.name,
+                audience: connection.audience,
+                binding: connection.binding,
+                metadata: { ...connection.metadata, ...input.metadata },
+                reconnect: snapshotOAuthReconnect(connection),
+            });
         },
         async completeOAuth(input) {
             const state = await options.store.consumeOAuthState(input.state);
             if (!state) {
                 throw new ConnectError("oauth_state_not_found", "OAuth state was not found or has already been used");
             }
-            if (new Date(state.expiresAt).getTime() <= now().getTime()) {
-                throw new ConnectError("oauth_state_expired", "OAuth state has expired");
-            }
-            if (input.error) {
-                throw new ConnectError("oauth_error", input.errorDescription ?? input.error, {
-                    details: { error: input.error, errorDescription: input.errorDescription },
-                });
-            }
-            if (!input.code) {
-                throw new ConnectError("invalid_request", "OAuth callback is missing code");
-            }
-            const provider = registry.require(state.providerId);
-            if (provider.auth.type !== "oauth2") {
-                throw new ConnectError("unsupported_auth", `Provider "${provider.id}" does not use OAuth2 auth`);
-            }
-            let oauthAuth = provider.auth;
-            if (state.oauthClientId && !state.oauthClientId.startsWith("legacy:")) {
-                const client = await options.oauthClients?.resolveById(state.oauthClientId);
-                if (!client || client.providerId !== provider.id) {
-                    throw new ConnectError("setup_invalid", "OAuth Client is unavailable during callback");
-                }
-                assertOAuthClient(provider.id, state.redirectUri, client);
-                oauthAuth = {
-                    ...provider.auth,
-                    clientId: client.clientId,
-                    clientSecret: client.clientSecret,
-                };
-            }
-            const tokenSet = await exchangeCode(fetchImpl, oauthAuth, input.code, state.redirectUri, state.codeVerifier);
-            const grantedScopes = assertAllowedScopes(provider, parseScopes(tokenSet.scope, state.requestedScopes));
-            assertGrantedScopes(grantedScopes, state.requestedScopes);
-            const id = createId("conn");
-            const secretRef = createId("connsec");
-            const tokens = normalizeTokenSet(tokenSet, grantedScopes, now());
-            await options.secrets.setSecret(secretRef, { kind: "oauth2", tokens });
-            let connection;
+            let credentialWriteAttempted = false;
             try {
-                connection = await options.store.upsertConnection({
-                    id,
-                    providerId: provider.id,
-                    name: state.connectionName,
-                    projectId: state.audience ? undefined : state.projectId,
-                    orgId: state.orgId,
-                    owner: state.subject,
-                    audience: state.audience,
-                    oauthClientId: state.oauthClientId,
-                    binding: state.binding,
-                    authType: "oauth2",
-                    status: "active",
-                    grantedScopes,
-                    secretRef,
-                    tokenExpiresAt: tokens.expiresAt,
-                    createdAt: now().toISOString(),
-                    updatedAt: now().toISOString(),
-                    metadata: state.metadata,
-                });
-                if (state.audience && state.projectId) {
-                    if (!options.links) {
-                        throw new ConnectError("setup_invalid", "Connection link storage is not configured on this host");
+                if (new Date(state.expiresAt).getTime() <= now().getTime()) {
+                    throw new ConnectError("oauth_state_expired", "OAuth state has expired");
+                }
+                if (input.error) {
+                    throw new ConnectError("oauth_error", input.errorDescription ?? input.error, {
+                        details: { error: input.error, errorDescription: input.errorDescription },
+                    });
+                }
+                if (!input.code) {
+                    throw new ConnectError("invalid_request", "OAuth callback is missing code");
+                }
+                await authorizeOAuth("callback", "api", state);
+                const { provider, oauthAuth } = await configurationForOAuthState(state);
+                const original = state.reconnect ? await options.store.getConnection(state.reconnect.connectionId) : null;
+                if (state.reconnect && (!original || !options.store.replaceOAuthCredential || !matchesOAuthReconnect(original, state.reconnect))) {
+                    throw new ConnectError("policy_denied", "Connection changed while reconnecting");
+                }
+                await authorizeOAuth("callback", "api", state);
+                const tokenSet = await exchangeCode(fetchImpl, resolveHostname, oauthAuth, input.code, state.redirectUri, state.codeVerifier);
+                const tokenScopes = normalizeOAuthTokenScopes(provider.auth, parseScopes(tokenSet.scope, state.requestedScopes));
+                // A provider may include grants from a previous consent on the same OAuth
+                // app. Record actual token scopes without expanding this Connection.
+                assertGrantedScopes(tokenScopes, state.requestedScopes);
+                const grantedScopes = assertAllowedScopes(provider, state.requestedScopes);
+                await authorizeOAuth("callback", "api", state);
+                const oauthIdentity = provider.auth.identity ? await resolveOAuthAccountIdentity({ fetch: fetchImpl, resolveHostname }, provider.auth.identity, tokenSet.access_token, now()) : undefined;
+                if (state.reconnect && (!oauthIdentity || !original?.oauthIdentity
+                    || oauthIdentity.issuer !== original.oauthIdentity.issuer || oauthIdentity.subject !== original.oauthIdentity.subject
+                    || oauthIdentity.policyFingerprint !== original.oauthIdentity.policyFingerprint)) {
+                    throw new ConnectError("policy_denied", "The authorized account differs from the original Connection; connect it separately");
+                }
+                // Recheck changes made while the provider exchange/identity request was in flight.
+                // Durable hosts must additionally pin their OAuth Client row in the atomic commit.
+                await configurationForOAuthState(state);
+                await authorizeOAuth("callback", "api", state);
+                const id = createId("conn");
+                const secretRef = createId("connsec");
+                const tokens = normalizeTokenSet(tokenSet, tokenScopes, now());
+                await options.secrets.setSecret(secretRef, { kind: "oauth2", tokens });
+                let connection;
+                try {
+                    if (state.reconnect) {
+                        const committed = {};
+                        const replacement = {
+                            secretRef, credentialVersion: createId("credver"), tokenExpiresAt: tokens.expiresAt,
+                            grantedScopes, oauthClientFingerprint: state.oauthClientFingerprint, oauthIdentity: oauthIdentity, updatedAt: now().toISOString(),
+                        };
+                        try {
+                            await refreshCoordinator.runExclusive(state.reconnect.connectionId, async () => {
+                                await configurationForOAuthState(state);
+                                await authorizeOAuth("callback", "api", state);
+                                credentialWriteAttempted = true;
+                                committed.connection = await options.store.replaceOAuthCredential(state.reconnect, replacement);
+                                // An explicit CAS miss proves this operation did not store its reference.
+                                if (committed.connection === null)
+                                    credentialWriteAttempted = false;
+                            });
+                        }
+                        catch (error) {
+                            // A coordinator release failure cannot roll back a confirmed commit.
+                            if (!committed.connection && credentialWriteAttempted) {
+                                committed.connection = await recoverConnectionWrite({ ...original, ...replacement });
+                            }
+                            if (!committed.connection)
+                                throw error;
+                        }
+                        const saved = committed.connection;
+                        if (!saved)
+                            throw new ConnectError("policy_denied", "Connection changed while reconnecting");
+                        // A failed old-secret cleanup cannot undo a committed rotation or invite token exchange replay.
+                        if (original?.secretRef)
+                            await options.secrets.deleteSecret(original.secretRef).catch(() => undefined);
+                        return saved;
                     }
-                    await options.links.upsertConnectionLink({
-                        id: createId("connlink"),
-                        connectionId: connection.id,
-                        projectId: state.projectId,
+                    await configurationForOAuthState(state);
+                    await authorizeOAuth("callback", "api", state);
+                    const pendingConnection = {
+                        id,
+                        providerId: provider.id,
+                        authenticationId: provider.authenticationId,
+                        name: state.connectionName,
+                        projectId: state.audience ? undefined : state.projectId,
+                        orgId: state.orgId,
+                        owner: state.subject,
+                        audience: state.audience,
+                        oauthClientId: state.oauthClientId,
+                        oauthClientFingerprint: state.oauthClientFingerprint,
+                        oauthIdentity,
+                        binding: state.binding,
+                        authType: "oauth2",
                         status: "active",
+                        credentialVersion: createId("credver"),
+                        grantedScopes,
+                        secretRef,
+                        tokenExpiresAt: tokens.expiresAt,
                         createdAt: now().toISOString(),
                         updatedAt: now().toISOString(),
-                    });
+                        metadata: state.metadata,
+                    };
+                    const pendingLink = state.audience && state.projectId ? {
+                        id: createId("connlink"), connectionId: id, projectId: state.projectId, status: "active",
+                        createdAt: now().toISOString(), updatedAt: now().toISOString(),
+                    } : undefined;
+                    if (state.setupSessionRef && pendingLink && options.setupSessions?.prepareConnectionSetupCompletion) {
+                        const intent = { connection: snapshotOAuthReconnect(pendingConnection),
+                            link: { id: pendingLink.id, connectionId: id, projectId: pendingLink.projectId } };
+                        const prepare = () => options.setupSessions.prepareConnectionSetupCompletion(state.setupSessionRef, intent);
+                        // A committed intent is idempotent; do not start account persistence
+                        // until its exact private recovery target has been confirmed.
+                        const prepared = await prepare().catch(() => prepare());
+                        if (!prepared)
+                            throw new ConnectError("setup_invalid", "Connection setup completion intent could not be confirmed");
+                    }
+                    credentialWriteAttempted = true;
+                    connection = await persistNewConnection(pendingConnection);
+                    if (pendingLink) {
+                        if (!options.links) {
+                            throw new ConnectError("setup_invalid", "Connection link storage is not configured on this host");
+                        }
+                        await options.links.upsertConnectionLink(pendingLink);
+                    }
+                    if (state.setupSessionRef && options.setupSessions?.finishConnectionSetupSession) {
+                        const receipt = await options.setupSessions.finishConnectionSetupSession(state.setupSessionRef, { status: "completed", connectionId: connection.id }, now().toISOString()).catch(async (error) => {
+                            const recovered = await options.setupSessions?.reconcileConnectionSetupSession?.(state.setupSessionRef).catch(() => null);
+                            if (recovered?.status === "completed" && recovered.resultingConnectionId === connection.id)
+                                return recovered;
+                            throw error;
+                        });
+                        if (!receipt)
+                            throw new ConnectError("setup_invalid", "Connection setup completion receipt could not be confirmed");
+                    }
+                    return connection;
+                }
+                catch (error) {
+                    // Cleanup is safe only before attempting the reference write, or after
+                    // an explicit CAS miss. Never invalidate a committed account because a
+                    // later link/acknowledgement failed; that would also race with reconnect.
+                    if (!credentialWriteAttempted)
+                        await options.secrets.deleteSecret(secretRef).catch(() => undefined);
+                    throw error;
                 }
-                return connection;
             }
             catch (error) {
-                await options.secrets.deleteSecret(secretRef).catch(() => undefined);
-                if (connection) {
-                    await options.store.updateConnection(connection.id, {
-                        status: "error",
-                        secretRef: undefined,
-                        updatedAt: now().toISOString(),
-                    }).catch(() => undefined);
+                if (state.setupSessionRef && !credentialWriteAttempted) {
+                    await options.setupSessions?.finishConnectionSetupSession?.(state.setupSessionRef, { status: "error" }, now().toISOString()).catch(() => undefined);
                 }
                 throw error;
             }
         },
+        async completeOAuthCallback(input) {
+            const state = await options.store.getOAuthState?.(input.state);
+            const connection = state?.flowKind === "mcp"
+                ? await this.completeMcpOAuth(input)
+                : await this.completeOAuth(input);
+            return { connection, ...(state?.returnUrl ? { returnUrl: state.returnUrl } : {}) };
+        },
         async resolveCredential(input) {
             const connection = await options.store.getConnection(input.connectionId);
             if (!connection) {
@@ -589,7 +1115,22 @@ export function createConnectService(options) {
             if (connection.status !== "active") {
                 throw new ConnectError("connection_revoked", `Connection is not active: ${connection.id}`);
             }
-            const scopes = assertGrantedScopes(connection.grantedScopes, input.scopes ?? []);
+            const provider = await requireProvider(connection.providerId, connection.authenticationId);
+            if (connection.oauthIdentity && (provider.auth.type !== "oauth2"
+                || connection.oauthIdentity.policyFingerprint !== oauthIdentityPolicyFingerprint(provider.auth.identity))) {
+                throw new ConnectError("setup_invalid", "OAuth identity policy changed; create a new Connection");
+            }
+            if (provider.auth.type !== connection.authType) {
+                throw new ConnectError("unsupported_auth", "Connection authentication no longer matches its Connector");
+            }
+            if (provider.authenticationId && provider.auth.type === "mcp"
+                && readMcpAuthMode(connection.metadata) !== (provider.auth.auth ?? "bearer")) {
+                throw new ConnectError("unsupported_auth", "Connection MCP authentication no longer matches its Connector");
+            }
+            const action = input.actionId ? provider.actions?.find((candidate) => candidate.id === input.actionId) : undefined;
+            // Hosts may also use actionId as an audit label for a custom tool. Its
+            // operation policy remains enforced by that tool's capability/grant.
+            const scopes = assertGrantedScopes(connection.grantedScopes, [...(input.scopes ?? []), ...(action?.scopes ?? [])]);
             const allowed = await options.policy?.canUseConnection({
                 connection,
                 subject: input.subject,
@@ -599,8 +1140,13 @@ export function createConnectService(options) {
             if (allowed === false) {
                 throw new ConnectError("policy_denied", `Connection use denied by policy: ${connection.id}`);
             }
+            await authorizeConnection("credential", connection);
+            if (connection.authType === "oauth2" && connection.oauthClientFingerprint) {
+                await oauthAuthForConnection(provider, connection.oauthClientId, connection.oauthClientFingerprint);
+            }
             if (!connection.secretRef) {
-                if (connection.authType === "mcp" && readMcpAuthMode(connection.metadata) === "none") {
+                if (!connectionRequiresSecret(connection)) {
+                    await assertConnectionCurrent(connection, scopes);
                     return {
                         kind: "none",
                         scopes,
@@ -615,9 +1161,13 @@ export function createConnectService(options) {
             if (!secret) {
                 throw new ConnectError("secret_not_found", `Connection secret not found: ${connection.secretRef}`);
             }
+            if (secret.kind !== connection.authType) {
+                throw new ConnectError("unsupported_auth", "Connection credential kind does not match its authentication");
+            }
             if (secret.kind === "api_key") {
                 if (!secret.apiKey)
                     throw new ConnectError("token_not_available", "API-key connection secret is empty");
+                await assertConnectionCurrent(connection, scopes);
                 return {
                     kind: "api_key",
                     value: secret.apiKey,
@@ -629,35 +1179,77 @@ export function createConnectService(options) {
             }
             if (secret.kind === "mcp") {
                 if (secret.mcpOAuth?.tokens?.accessToken) {
+                    await authorizeConnection("credential", connection, true);
                     let material = secret.mcpOAuth;
-                    if (input.forceRefresh || shouldRefresh(material.tokens, now(), tokenRefreshSkewMs)) {
-                        material = await refreshCoordinator.runExclusive(connection.id, async () => {
-                            const latest = await options.secrets.getSecret(connection.secretRef);
-                            if (!latest?.mcpOAuth?.tokens?.accessToken) {
-                                throw new ConnectError("token_not_available", "MCP OAuth connection secret is empty");
-                            }
-                            if (!input.forceRefresh && !shouldRefresh(latest.mcpOAuth.tokens, now(), tokenRefreshSkewMs)) {
-                                return latest.mcpOAuth;
-                            }
-                            const tokens = await mcpOAuth.refresh({
-                                material: latest.mcpOAuth,
-                                fallbackScopes: scopes,
-                            });
-                            const refreshed = { ...latest.mcpOAuth, tokens };
-                            await options.secrets.setSecret(connection.secretRef, { kind: "mcp", mcpOAuth: refreshed });
-                            await options.store.updateConnection(connection.id, {
-                                tokenExpiresAt: tokens.expiresAt,
-                                updatedAt: now().toISOString(),
+                    if (input.forceRefresh || hasPendingRefresh(secret) || shouldRefresh(material.tokens, now(), tokenRefreshSkewMs)) {
+                        const initialTokens = material.tokens;
+                        try {
+                            material = await refreshCoordinator.runExclusive(connection.id, async () => {
+                                await assertConnectionCurrent(connection, scopes);
+                                const versionedStore = isVersionedConnectionSecretStore(options.secrets) ? options.secrets : undefined;
+                                const snapshot = await versionedStore?.getVersioned(connection.secretRef);
+                                const latest = snapshot?.secret ?? await options.secrets.getSecret(connection.secretRef);
+                                if (latest?.kind !== "mcp" || !latest.mcpOAuth?.tokens?.accessToken) {
+                                    throw new ConnectError("token_not_available", "MCP OAuth connection secret is empty");
+                                }
+                                assertRefreshAvailable(latest);
+                                const latestTokens = latest.mcpOAuth.tokens;
+                                if (tokensChanged(initialTokens, latestTokens)
+                                    || (!input.forceRefresh && !shouldRefresh(latestTokens, now(), tokenRefreshSkewMs))) {
+                                    return latest.mcpOAuth;
+                                }
+                                await authorizeConnection("refresh", connection, true);
+                                let currentMaterial = latest.mcpOAuth;
+                                const saved = await refreshConnectionSecret({
+                                    store: options.secrets, ref: connection.secretRef, previous: latest, snapshot, now,
+                                    beforeRefresh: async () => {
+                                        await assertConnectionCurrent(connection, scopes);
+                                        await authorizeConnection("refresh", connection, true);
+                                        currentMaterial = await currentMcpMaterial(latest.mcpOAuth, connection.oauthClientId, connection.oauthClientFingerprint);
+                                    },
+                                    refresh: async () => {
+                                        const tokens = await mcpOAuth.refresh({
+                                            material: currentMaterial,
+                                            fallbackScopes: latestTokens.scopes ?? connection.grantedScopes,
+                                        });
+                                        // Versioned stores fence deletion/replacement at commit.
+                                        // Persist known rotated material before any fallible read.
+                                        if (!versionedStore)
+                                            await assertConnectionCurrent(connection, scopes, false);
+                                        return { ...latest, mcpOAuth: { ...latest.mcpOAuth, tokens } };
+                                    },
+                                });
+                                // Preserve rotated refresh tokens durably before denying delivery
+                                // if the host gate changed while the provider request was in flight.
+                                const current = await assertConnectionCurrent(connection, scopes, false);
+                                const refreshed = saved.mcpOAuth;
+                                const tokens = refreshed.tokens;
+                                await options.store.updateConnection(connection.id, {
+                                    tokenExpiresAt: tokens.expiresAt,
+                                    grantedScopes: current.grantedScopes.filter((scope) => tokens.scopes?.includes(scope)),
+                                    updatedAt: now().toISOString(),
+                                });
+                                return refreshed;
                             });
-                            return refreshed;
-                        });
+                        }
+                        catch (error) {
+                            if (error instanceof ConnectError && error.code === "refresh_unavailable") {
+                                await assertConnectionCurrent(connection, scopes, false);
+                            }
+                            if (error instanceof ConnectError)
+                                throw error;
+                            throw new ConnectError("refresh_unavailable", "MCP OAuth token refresh could not be coordinated");
+                        }
                     }
+                    assertGrantedScopes(material.tokens.scopes ?? connection.grantedScopes, scopes);
+                    const current = await assertConnectionCurrent(connection, scopes);
+                    await authorizeConnection("credential", current, true);
                     return {
                         kind: "mcp",
                         accessToken: material.tokens.accessToken,
                         tokenType: material.tokens.tokenType ?? "Bearer",
                         expiresAt: material.tokens.expiresAt,
-                        scopes,
+                        scopes: current.grantedScopes.filter((scope) => (material.tokens.scopes ?? current.grantedScopes).includes(scope)),
                         connectionId: connection.id,
                         providerId: connection.providerId,
                         metadata: connection.metadata,
@@ -665,6 +1257,7 @@ export function createConnectService(options) {
                 }
                 if (!secret.apiKey)
                     throw new ConnectError("token_not_available", "MCP connection secret is empty");
+                await assertConnectionCurrent(connection, scopes);
                 return {
                     kind: "mcp",
                     accessToken: secret.apiKey,
@@ -679,10 +1272,11 @@ export function createConnectService(options) {
                 throw new ConnectError("token_not_available", "Connection does not contain an OAuth access token");
             }
             let tokens = secret.tokens;
-            if (input.forceRefresh || shouldRefresh(tokens, now(), tokenRefreshSkewMs)) {
+            if (input.forceRefresh || hasPendingRefresh(secret) || shouldRefresh(tokens, now(), tokenRefreshSkewMs)) {
                 const initialTokens = tokens;
                 try {
                     tokens = await refreshCoordinator.runExclusive(connection.id, async () => {
+                        await assertConnectionCurrent(connection, scopes);
                         const versionedStore = isVersionedConnectionSecretStore(options.secrets)
                             ? options.secrets
                             : undefined;
@@ -694,56 +1288,61 @@ export function createConnectService(options) {
                         if (latestSecret?.kind !== "oauth2" || !latestSecret.tokens?.accessToken) {
                             throw new ConnectError("token_not_available", "Connection does not contain an OAuth access token");
                         }
+                        assertRefreshAvailable(latestSecret);
                         const latestTokens = latestSecret.tokens;
-                        const refreshedByAnotherCaller = latestTokens.accessToken !== initialTokens.accessToken
-                            || latestTokens.refreshToken !== initialTokens.refreshToken
-                            || latestTokens.expiresAt !== initialTokens.expiresAt;
+                        const refreshedByAnotherCaller = tokensChanged(initialTokens, latestTokens);
                         if (refreshedByAnotherCaller
                             || (!input.forceRefresh && !shouldRefresh(latestTokens, now(), tokenRefreshSkewMs))) {
                             secret = latestSecret;
                             return latestTokens;
                         }
-                        const provider = registry.require(connection.providerId);
-                        const oauthAuth = await oauthAuthForConnection(provider, connection.oauthClientId);
+                        const provider = await requireProvider(connection.providerId, connection.authenticationId);
+                        const oauthAuth = await oauthAuthForConnection(provider, connection.oauthClientId, connection.oauthClientFingerprint);
                         if (!latestTokens.refreshToken) {
                             throw new ConnectError("token_not_available", "OAuth access token is expired and no refresh token is available");
                         }
-                        const refreshed = await refreshToken(fetchImpl, oauthAuth, latestTokens.refreshToken, connection.grantedScopes, now());
-                        const nextSecret = { ...latestSecret, tokens: refreshed };
-                        if (versionedStore && snapshot) {
-                            const written = await versionedStore.compareAndSet(connection.secretRef, snapshot.version, nextSecret);
-                            if (!written) {
-                                const winner = await versionedStore.getVersioned(connection.secretRef);
-                                if (winner?.secret.kind !== "oauth2" || !winner.secret.tokens?.accessToken) {
-                                    throw new ConnectError("refresh_unavailable", "OAuth token refresh lost a write race without a valid winner");
-                                }
-                                secret = winner.secret;
-                                return winner.secret.tokens;
-                            }
-                        }
-                        else {
-                            await options.secrets.setSecret(connection.secretRef, nextSecret);
-                        }
+                        await authorizeConnection("refresh", connection);
+                        const nextSecret = await refreshConnectionSecret({
+                            store: options.secrets, ref: connection.secretRef, previous: latestSecret, snapshot, now,
+                            beforeRefresh: async () => {
+                                await assertConnectionCurrent(connection, scopes);
+                                await authorizeConnection("refresh", connection);
+                            },
+                            refresh: async () => {
+                                const refreshed = await refreshToken(fetchImpl, resolveHostname, oauthAuth, latestTokens.refreshToken, latestTokens.scopes ?? connection.grantedScopes, now());
+                                if (!versionedStore)
+                                    await assertConnectionCurrent(connection, scopes, false);
+                                return { ...latestSecret, tokens: refreshed };
+                            },
+                        });
+                        const refreshed = nextSecret.tokens;
+                        const current = await assertConnectionCurrent(connection, scopes, false);
                         secret = nextSecret;
                         await options.store.updateConnection(connection.id, {
                             tokenExpiresAt: refreshed.expiresAt,
+                            grantedScopes: current.grantedScopes.filter((scope) => refreshed.scopes?.includes(scope)),
                             updatedAt: now().toISOString(),
                         });
                         return refreshed;
                     });
                 }
                 catch (error) {
+                    if (error instanceof ConnectError && error.code === "refresh_unavailable") {
+                        await assertConnectionCurrent(connection, scopes, false);
+                    }
                     if (error instanceof ConnectError)
                         throw error;
                     throw new ConnectError("refresh_unavailable", "OAuth token refresh could not be coordinated");
                 }
             }
+            assertGrantedScopes(tokens.scopes ?? connection.grantedScopes, scopes);
+            const current = await assertConnectionCurrent(connection, scopes);
             return {
                 kind: "oauth2",
                 accessToken: tokens.accessToken,
                 tokenType: tokens.tokenType ?? "Bearer",
                 expiresAt: tokens.expiresAt,
-                scopes: tokens.scopes ?? scopes,
+                scopes: current.grantedScopes.filter((scope) => (tokens.scopes ?? current.grantedScopes).includes(scope)),
                 connectionId: connection.id,
                 providerId: connection.providerId,
                 metadata: connection.metadata,
@@ -789,13 +1388,14 @@ export function createConnectService(options) {
             if (!connection) {
                 throw new ConnectError("connection_not_found", `Connection not found: ${input.connectionId}`);
             }
-            const provider = registry.require(connection.providerId);
+            const provider = await requireProvider(connection.providerId, connection.authenticationId);
             if (!provider.http) {
                 throw new ConnectError("policy_denied", `Provider "${provider.id}" does not expose an HTTP gateway policy`);
             }
+            const httpPolicy = provider.http;
             let resolvedRequest;
             try {
-                resolvedRequest = resolveConnectorHttpRequest(provider.http, input.request);
+                resolvedRequest = resolveConnectorHttpRequest(httpPolicy, input.request);
             }
             catch (error) {
                 if (error instanceof ConnectionSelectionError) {
@@ -806,91 +1406,129 @@ export function createConnectService(options) {
                 }
                 throw error;
             }
-            const credential = await this.resolveCredential(input);
-            const authValue = credential.kind === "api_key"
-                ? credential.value
-                : credential.kind === "oauth2" || credential.kind === "mcp"
-                    ? credential.accessToken
-                    : undefined;
-            const tokenType = credential.kind === "oauth2" || credential.kind === "mcp"
-                ? credential.tokenType ?? "Bearer"
-                : "Bearer";
-            let url = new URL(resolvedRequest.url);
-            const headers = new Headers(resolvedRequest.headers);
-            if (authValue) {
-                if (provider.http.auth.mode === "bearer") {
-                    headers.set("authorization", `${tokenType} ${authValue}`);
-                }
-                else if (provider.http.auth.mode === "header") {
-                    headers.set(provider.http.auth.name, authValue);
-                }
-                else {
-                    url.searchParams.set(provider.http.auth.name, authValue);
-                }
-            }
-            if (resolvedRequest.idempotencyKey) {
-                headers.set("idempotency-key", resolvedRequest.idempotencyKey);
-            }
-            const body = resolvedRequest.body === undefined
-                ? undefined
-                : JSON.stringify(resolvedRequest.body);
-            if (body !== undefined && !headers.has("content-type")) {
-                headers.set("content-type", "application/json");
-            }
-            for (let redirectCount = 0; redirectCount <= 3; redirectCount += 1) {
-                await assertPublicDns(url.hostname, resolveHostname);
-                const response = await fetchWithTimeout(fetchImpl, url, {
-                    method: resolvedRequest.method,
-                    headers,
-                    body,
-                    redirect: "manual",
-                }, resolvedRequest.timeoutMs, input.signal);
-                if (response.status >= 300 && response.status < 400) {
-                    const location = response.headers.get("location");
-                    if (!location) {
-                        throw new ConnectError("http_error", "Provider returned a redirect without a location");
+            return withGatewayDeadline(resolvedRequest.timeoutMs, input.signal, async (signal) => {
+                const credential = await this.resolveCredential(input);
+                const authValue = credential.kind === "api_key"
+                    ? credential.value
+                    : credential.kind === "oauth2" || credential.kind === "mcp"
+                        ? credential.accessToken
+                        : undefined;
+                const tokenType = credential.kind === "oauth2" || credential.kind === "mcp"
+                    ? credential.tokenType ?? "Bearer"
+                    : "Bearer";
+                let url = new URL(resolvedRequest.url);
+                const headers = new Headers(resolvedRequest.headers);
+                if (authValue) {
+                    if (httpPolicy.auth.mode === "bearer") {
+                        headers.set("authorization", `${tokenType} ${authValue}`);
                     }
-                    if (redirectCount === 3) {
-                        throw new ConnectError("http_error", "Provider exceeded the Connector redirect limit");
+                    else if (httpPolicy.auth.mode === "header") {
+                        headers.set(httpPolicy.auth.name, authValue);
                     }
-                    if (resolvedRequest.method !== "GET"
-                        && resolvedRequest.method !== "HEAD"
-                        && response.status !== 307
-                        && response.status !== 308) {
-                        throw new ConnectError("http_error", "Provider attempted an unsafe method-changing redirect");
+                    else if (httpPolicy.auth.mode === "query") {
+                        url.searchParams.set(httpPolicy.auth.name, authValue);
                     }
+                }
+                if (resolvedRequest.idempotencyKey) {
+                    headers.set("idempotency-key", resolvedRequest.idempotencyKey);
+                }
+                const body = resolvedRequest.body === undefined
+                    ? undefined
+                    : JSON.stringify(resolvedRequest.body);
+                if (body !== undefined && !headers.has("content-type")) {
+                    headers.set("content-type", "application/json");
+                }
+                const authorizeSend = async () => {
+                    await assertConnectionCurrent(connection, credential.scopes);
                     try {
-                        url = new URL(assertConnectorRedirectAllowed(provider.http, new URL(location, url).toString()));
+                        await input.authorizeDispatch?.();
                     }
                     catch (error) {
-                        if (error instanceof ConnectionSelectionError) {
-                            throw new ConnectError("http_error", "Provider redirect was denied by policy", {
-                                details: { category: "redirect_denied" },
-                            });
+                        if (error instanceof ConnectError)
+                            throw error;
+                        throw new ConnectError("policy_denied", "Invocation authorization is no longer available", {
+                            status: error instanceof ConnectionSelectionError ? error.status : 503,
+                            ...(error instanceof ConnectionSelectionError ? { details: { code: error.code } } : {}),
+                        });
+                    }
+                };
+                for (let redirectCount = 0; redirectCount <= 3; redirectCount += 1) {
+                    signal.throwIfAborted();
+                    await assertPublicDns(url.hostname, resolveHostname);
+                    signal.throwIfAborted();
+                    await authorizeSend();
+                    signal.throwIfAborted();
+                    if (input.beforeDispatch || options.beforeDispatch) {
+                        if (input.beforeDispatch)
+                            await input.beforeDispatch({ method: resolvedRequest.method });
+                        else
+                            await options.beforeDispatch(connection);
+                        // Waiting on a distributed quota is an authorization boundary too.
+                        // A revoked grant/account must not send previously resolved headers.
+                        await authorizeSend();
+                    }
+                    signal.throwIfAborted();
+                    const response = await fetchImpl(url, {
+                        method: resolvedRequest.method,
+                        headers,
+                        body,
+                        redirect: "manual",
+                        signal,
+                    });
+                    if (response.status >= 300 && response.status < 400) {
+                        void response.body?.cancel().catch(() => undefined);
+                        const location = response.headers.get("location");
+                        if (!location) {
+                            throw new ConnectError("http_error", "Provider returned a redirect without a location");
                         }
-                        throw error;
+                        if (redirectCount === 3) {
+                            throw new ConnectError("http_error", "Provider exceeded the Connector redirect limit");
+                        }
+                        if (resolvedRequest.method !== "GET"
+                            && resolvedRequest.method !== "HEAD"
+                            && response.status !== 307
+                            && response.status !== 308) {
+                            throw new ConnectError("http_error", "Provider attempted an unsafe method-changing redirect");
+                        }
+                        try {
+                            url = new URL(assertConnectorRedirectAllowed(httpPolicy, new URL(location, url).toString()));
+                        }
+                        catch (error) {
+                            if (error instanceof ConnectionSelectionError) {
+                                throw new ConnectError("http_error", "Provider redirect was denied by policy", {
+                                    details: { category: "redirect_denied" },
+                                });
+                            }
+                            throw error;
+                        }
+                        continue;
                     }
-                    continue;
+                    const responseBytes = await readResponseBytes(response, resolvedRequest.maxResponseBytes, signal);
+                    const responseHeaders = sanitizedResponseHeaders(response.headers);
+                    const requestId = response.headers.get("x-request-id")
+                        ?? response.headers.get("request-id")
+                        ?? undefined;
+                    return {
+                        status: response.status,
+                        headers: Object.freeze(responseHeaders),
+                        body: parseResponseBody(responseBytes, response.headers.get("content-type")),
+                        ...(requestId ? { requestId } : {}),
+                    };
                 }
-                const responseBytes = await readResponseBytes(response, resolvedRequest.maxResponseBytes);
-                const responseHeaders = sanitizedResponseHeaders(response.headers);
-                const requestId = response.headers.get("x-request-id")
-                    ?? response.headers.get("request-id")
-                    ?? undefined;
-                return {
-                    status: response.status,
-                    headers: Object.freeze(responseHeaders),
-                    body: parseResponseBody(responseBytes, response.headers.get("content-type")),
-                    ...(requestId ? { requestId } : {}),
-                };
-            }
-            throw new ConnectError("http_error", "Provider request did not produce a response");
+                throw new ConnectError("http_error", "Provider request did not produce a response");
+            });
         },
         async revokeConnection(input) {
             const connection = await options.store.getConnection(input.connectionId);
             if (!connection) {
                 throw new ConnectError("connection_not_found", `Connection not found: ${input.connectionId}`);
             }
+            // Deny new use before touching the vault. Retain the ref until deletion
+            // succeeds so a transient vault failure can be retried safely.
+            await options.store.updateConnection(connection.id, {
+                status: "revoked",
+                updatedAt: now().toISOString(),
+            });
             if (connection.secretRef) {
                 await options.secrets.deleteSecret(connection.secretRef);
             }
@@ -902,6 +1540,25 @@ export function createConnectService(options) {
         },
     };
 }
+function tokensChanged(before, after) {
+    return before.accessToken !== after.accessToken
+        || before.refreshToken !== after.refreshToken
+        || before.expiresAt !== after.expiresAt;
+}
+function oauthClientFingerprint(provider, clientId) {
+    if (provider.auth.type !== "oauth2" || !clientId) {
+        throw new ConnectError("setup_invalid", "OAuth Client registration is unavailable; reconnect the Connection");
+    }
+    return createHash("sha256").update(JSON.stringify([
+        provider.id, provider.authenticationId ?? null, clientId,
+        provider.auth.authorizationUrl, provider.auth.tokenUrl,
+    ])).digest("hex");
+}
+function assertOAuthClientFingerprint(provider, clientId, expected) {
+    if (expected && oauthClientFingerprint(provider, clientId) !== expected) {
+        throw new ConnectError("setup_invalid", "OAuth Client registration changed; reconnect the Connection");
+    }
+}
 function assertOAuthClient(providerId, redirectUri, client) {
     if (!client
         || client.providerId !== providerId
@@ -936,6 +1593,43 @@ function normalizeReturnUrl(value, allowedOrigins) {
     }
     return url.toString();
 }
+function normalizeCreationIdentity(input) {
+    const audience = input.audience === undefined ? "shared" : input.audience;
+    if (!["personal", "shared", "end_user"].includes(audience)) {
+        throw new ConnectError("setup_invalid", "Connection audience is invalid");
+    }
+    // Agent-owned static credentials predate audience selection. Preserve that
+    // explicit shared ownership, without allowing it to satisfy a user audience.
+    if (audience === "shared" && input.subject?.type === "agent") {
+        const subject = { type: "agent", id: requiredText("owner.id", input.subject.id) };
+        return { audience, subject, ...(input.binding === undefined ? {} : { binding: normalizeConnectionBinding(input.binding) }) };
+    }
+    if (input.subject !== undefined || audience !== "shared") {
+        return { audience, ...normalizeSetupIdentity(audience, input.subject, input.binding) };
+    }
+    return { audience, ...(input.binding === undefined ? {} : { binding: normalizeConnectionBinding(input.binding) }) };
+}
+/** Inventory is host-observed evidence, never caller-authored configuration. */
+function omitMcpDiscoveryMetadata(metadata) {
+    const { discoveredTools: _tools, lastDiscoveredAt: _timestamp, ...rest } = metadata ?? {};
+    return rest;
+}
+function normalizeSetupIdentity(audience, owner, suppliedBinding) {
+    const subject = normalizeConnectionOwner(owner);
+    const binding = suppliedBinding === undefined ? undefined : normalizeConnectionBinding(suppliedBinding);
+    const principalType = audience === "end_user" ? "external_user" : audience === "personal" ? "user" : undefined;
+    if (!principalType)
+        return { subject, ...(binding ? { binding } : {}) };
+    if (subject.type !== principalType)
+        throw new ConnectError("setup_invalid", "Connection setup subject does not match its audience");
+    const principal = { type: principalType, id: subject.id,
+        ...(subject.type === "external_user" ? { namespace: subject.namespace } : {}) };
+    if (binding?.principal && (binding.principal.type !== principal.type || binding.principal.id !== principal.id
+        || (binding.principal.namespace !== undefined && binding.principal.namespace !== principal.namespace))) {
+        throw new ConnectError("setup_invalid", "Connection setup binding does not match its subject");
+    }
+    return { subject, binding: { ...binding, principal } };
+}
 function normalizeConnectionOwner(owner) {
     if (!owner || typeof owner !== "object" || Array.isArray(owner)) {
         throw new ConnectError("setup_invalid", "Connection setup owner is invalid");
@@ -968,28 +1662,28 @@ function normalizeConnectionBinding(binding) {
     if (unsupported.length > 0) {
         throw new ConnectError("setup_invalid", "Connection setup binding has unsupported fields");
     }
-    const normalizePart = (name, value, fields) => {
+    const normalizePart = (name, value, fields, optionalFields = []) => {
         if (value === undefined)
             return undefined;
         if (!value || typeof value !== "object" || Array.isArray(value)) {
             throw new ConnectError("setup_invalid", `Connection setup binding ${name} is invalid`);
         }
-        if (Object.keys(value).some((key) => !fields.includes(key))) {
+        if (Object.keys(value).some((key) => !fields.includes(key) && !optionalFields.includes(key))) {
             throw new ConnectError("setup_invalid", `Connection setup binding ${name} has unsupported fields`);
         }
-        return Object.fromEntries(fields.map((field) => [
+        return Object.fromEntries([...fields, ...optionalFields.filter(field => value[field] !== undefined)].map((field) => [
             field,
             requiredText(`binding.${name}.${field}`, value[field]),
         ]));
     };
     return {
-        ...(binding.principal ? {
-            principal: normalizePart("principal", binding.principal, ["type", "id"]),
+        ...(binding.principal !== undefined ? {
+            principal: normalizePart("principal", binding.principal, ["type", "id"], ["namespace"]),
         } : {}),
-        ...(binding.tenant ? {
+        ...(binding.tenant !== undefined ? {
             tenant: normalizePart("tenant", binding.tenant, ["namespace", "id"]),
         } : {}),
-        ...(binding.resource ? {
+        ...(binding.resource !== undefined ? {
             resource: normalizePart("resource", binding.resource, ["namespace", "type", "id"]),
         } : {}),
         ...(binding.scopeEpoch === undefined
@@ -1013,22 +1707,28 @@ async function assertPublicDns(hostname, resolveHostname) {
         });
     }
 }
-async function fetchWithTimeout(fetchImpl, url, init, timeoutMs, signal) {
+async function withGatewayDeadline(timeoutMs, signal, run) {
+    const aborted = () => new ConnectError("http_error", "Provider request was aborted or timed out", {
+        details: { category: "aborted", retryable: true },
+    });
+    if (signal?.aborted)
+        throw aborted();
     const controller = new AbortController();
-    const onAbort = () => controller.abort(signal?.reason);
+    let rejectAbort;
+    const deadline = new Promise((_, reject) => { rejectAbort = reject; });
+    const onAbort = () => { controller.abort(); rejectAbort(aborted()); };
     signal?.addEventListener("abort", onAbort, { once: true });
-    const timeout = setTimeout(() => controller.abort(new Error("connection_gateway_timeout")), timeoutMs);
+    const timeout = setTimeout(onAbort, timeoutMs);
     try {
-        return await fetchImpl(url, { ...init, signal: controller.signal });
+        return await Promise.race([deadline, run(controller.signal)]);
     }
     catch (error) {
-        throw new ConnectError("http_error", controller.signal.aborted
-            ? "Provider request was aborted or timed out"
-            : "Provider request failed", {
-            details: {
-                category: controller.signal.aborted ? "aborted" : "transport_failed",
-                retryable: true,
-            },
+        if (error instanceof ConnectError)
+            throw error;
+        if (controller.signal.aborted)
+            throw aborted();
+        throw new ConnectError("http_error", "Provider request failed", {
+            details: { category: "transport_failed", retryable: true },
         });
     }
     finally {
@@ -1036,9 +1736,10 @@ async function fetchWithTimeout(fetchImpl, url, init, timeoutMs, signal) {
         signal?.removeEventListener("abort", onAbort);
     }
 }
-async function readResponseBytes(response, maximum) {
+async function readResponseBytes(response, maximum, signal) {
     const declared = Number(response.headers.get("content-length"));
     if (Number.isFinite(declared) && declared > maximum) {
+        void response.body?.cancel().catch(() => undefined);
         throw new ConnectError("http_error", "Provider response exceeds the Connector limit", {
             details: { category: "response_too_large" },
         });
@@ -1046,28 +1747,41 @@ async function readResponseBytes(response, maximum) {
     if (!response.body)
         return new Uint8Array();
     const reader = response.body.getReader();
-    const chunks = [];
-    let total = 0;
-    while (true) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        total += value.byteLength;
-        if (total > maximum) {
-            await reader.cancel();
-            throw new ConnectError("http_error", "Provider response exceeds the Connector limit", {
-                details: { category: "response_too_large" },
-            });
+    const cancel = () => { void reader.cancel().catch(() => undefined); };
+    signal.addEventListener("abort", cancel, { once: true });
+    try {
+        if (signal.aborted) {
+            cancel();
+            signal.throwIfAborted();
         }
-        chunks.push(value);
+        const chunks = [];
+        let total = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            signal.throwIfAborted();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maximum) {
+                await reader.cancel();
+                throw new ConnectError("http_error", "Provider response exceeds the Connector limit", {
+                    details: { category: "response_too_large" },
+                });
+            }
+            chunks.push(value);
+        }
+        const result = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return result;
     }
-    const result = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        result.set(chunk, offset);
-        offset += chunk.byteLength;
+    finally {
+        signal.removeEventListener("abort", cancel);
+        reader.releaseLock();
     }
-    return result;
 }
 function parseResponseBody(bytes, contentType) {
     if (bytes.byteLength === 0)
@@ -1105,8 +1819,8 @@ function sanitizedResponseHeaders(headers) {
     }
     return safe;
 }
-async function exchangeCode(fetchImpl, auth, code, redirectUri, codeVerifier) {
-    return requestToken(fetchImpl, auth.tokenUrl, {
+async function exchangeCode(fetchImpl, resolveHostname, auth, code, redirectUri, codeVerifier) {
+    return requestOAuthToken({ fetch: fetchImpl, resolveHostname }, auth.tokenUrl, {
         grant_type: "authorization_code",
         code,
         redirect_uri: redirectUri,
@@ -1116,34 +1830,15 @@ async function exchangeCode(fetchImpl, auth, code, redirectUri, codeVerifier) {
         ...auth.extraTokenParams,
     });
 }
-async function refreshToken(fetchImpl, auth, refreshTokenValue, fallbackScopes, now) {
-    const tokenSet = await requestToken(fetchImpl, auth.tokenUrl, {
+async function refreshToken(fetchImpl, resolveHostname, auth, refreshTokenValue, fallbackScopes, now) {
+    const tokenSet = await requestOAuthToken({ fetch: fetchImpl, resolveHostname }, auth.tokenUrl, {
         grant_type: "refresh_token",
         refresh_token: refreshTokenValue,
         client_id: auth.clientId,
         client_secret: auth.clientSecret,
         ...auth.extraTokenParams,
     });
-    return normalizeTokenSet(tokenSet, parseScopes(tokenSet.scope, fallbackScopes), now, refreshTokenValue);
-}
-async function requestToken(fetchImpl, tokenUrl, body) {
-    const response = await fetchImpl(tokenUrl, {
-        method: "POST",
-        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
-        body: toFormBody(body),
-    });
-    const text = await response.text();
-    const payload = text ? safeJson(text) : {};
-    if (!response.ok) {
-        throw new ConnectError("token_exchange_failed", "OAuth token endpoint returned an error", {
-            status: response.status,
-            details: payload,
-        });
-    }
-    if (!payload || typeof payload !== "object" || typeof payload.access_token !== "string") {
-        throw new ConnectError("token_exchange_failed", "OAuth token endpoint did not return access_token", { details: payload });
-    }
-    return payload;
+    return normalizeTokenSet(tokenSet, normalizeOAuthTokenScopes(auth, parseScopes(tokenSet.scope, fallbackScopes)), now, refreshTokenValue);
 }
 function normalizeTokenSet(payload, scopes, now, fallbackRefreshToken) {
     return {
@@ -1197,7 +1892,7 @@ function readMcpAuthMode(metadata) {
 function omitInternalMcpStateMetadata(metadata) {
     if (!metadata)
         return undefined;
-    const { pendingConnectionId: _pendingConnectionId, ...publicMetadata } = metadata;
+    const { pendingConnectionId: _pendingConnectionId, ...publicMetadata } = omitMcpDiscoveryMetadata(metadata);
     return publicMetadata;
 }
 function readTokenType(secret) {
@@ -1207,12 +1902,4 @@ function readTokenType(secret) {
 function createId(prefix) {
     return `${prefix}_${createOpaqueToken(18)}`;
 }
-function safeJson(text) {
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        throw new ConnectError("token_exchange_failed", "OAuth token endpoint returned invalid JSON", { details: text });
-    }
-}
 //# sourceMappingURL=service.js.map