@opengeni/api-router 0.5.2 → 0.5.4

package/src/integrations/oauth-client.ts

@@ -4,6 +4,7 @@ import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { parseIntegrationsOauthClientsJson, type Settings } from "@opengeni/config";
 import { OAuthStartResponse, type OAuthStartRequest } from "@opengeni/contracts";
 import { requireEnvironmentEncryption } from "@opengeni/core";
+import type { Observability } from "@opengeni/observability";
 import {
   consumeIntegrationOAuthStateNonce,
   createConnection,
@@ -11,7 +12,9 @@ import {
   encryptEnvironmentValue,
   getConnectionMetadata,
   isPrivateAddress,
+  listConnectionsMetadata,
   loadIntegrationOAuthClient,
+  normalizeBearerScheme,
   storeIntegrationOAuthClient,
   updateConnection,
   type Database,
@@ -29,6 +32,7 @@ export const oauthStateTtlMs = 10 * 60 * 1000;
 type OAuthClientDeps = {
   db: Database;
   settings: Settings;
+  observability?: Observability | undefined;
 };
 
 export type OAuthStartContext = {
@@ -63,12 +67,13 @@ type AuthorizationServerMetadata = {
   tokenEndpoint: string;
   registrationEndpoint?: string;
   clientIdMetadataDocumentSupported: boolean;
+  tokenEndpointAuthMethodsSupported: string[];
   codeChallengeMethodsSupported: string[];
   raw: Record<string, unknown>;
 };
 
 type OAuthClientRegistration = {
-  method: "operator" | "cimd" | "dcr";
+  method: "operator" | "manual" | "cimd" | "dcr";
   issuer: string;
   authorizationServer: string;
   clientId: string;
@@ -81,6 +86,7 @@ type OAuthStatePayload = {
   workspaceId: string;
   subjectId: string;
   providerDomain: string;
+  mcpUrl: string;
   resource: string;
   requestedScopes: string[];
   authorizeScopes: string[];
@@ -91,6 +97,7 @@ type OAuthStatePayload = {
   issuer: string;
   clientRegistrationMethod: OAuthClientRegistration["method"];
   tokenEndpointAuthMethod: OAuthClientRegistration["tokenEndpointAuthMethod"];
+  encryptedClientSecret?: string;
   returnPath: string;
   connectionId?: string;
   connectionVersion?: number;
@@ -107,34 +114,66 @@ type TokenResponse = {
   raw: Record<string, unknown>;
 };
 
+type OAuthCallbackStage = "state_verify" | "token_exchange" | "tools_list" | "persist";
+
+class OAuthCallbackStageError extends Error {
+  constructor(
+    readonly stage: OAuthCallbackStage,
+    readonly reason: string,
+    readonly cause: unknown,
+  ) {
+    super(errorMessage(cause));
+    this.name = "OAuthCallbackStageError";
+  }
+}
+
 export async function startMcpOAuth(
   deps: OAuthClientDeps,
   context: OAuthStartContext,
 ): Promise<OAuthStartResponse> {
   const { db, settings } = deps;
-  const resource = canonicalMcpResource(context.payload.mcpUrl ?? context.payload.resource);
-  const providerDomain = canonicalProviderDomain(context.payload.providerDomain ?? new URL(resource).hostname);
+  const mcpUrl = canonicalMcpResource(context.payload.mcpUrl ?? context.payload.resource);
+  const providerDomain = canonicalProviderDomain(
+    context.payload.providerDomain ?? new URL(mcpUrl).hostname,
+  );
   const returnPath = safeReturnPath(context.payload.returnPath ?? "/integrations");
   const baseUrl = integrationBaseUrl(settings.publicBaseUrl, context.requestUrl);
   const redirectUri = `${baseUrl}/v1/integrations/oauth/callback`;
   const metadataUrl = `${baseUrl}/v1/integrations/oauth/client-metadata.json`;
-  const existing = context.payload.connectionId
-    ? await getConnectionMetadata(db, context.workspaceId, context.payload.connectionId, context.subjectId)
-    : null;
+  const existing = await existingOAuthConnectionForStart(db, {
+    workspaceId: context.workspaceId,
+    subjectId: context.subjectId,
+    providerDomain,
+    connectionId: context.payload.connectionId,
+  });
   if (context.payload.connectionId && !existing) {
     throw new HTTPException(404, { message: "connection not found" });
   }
 
-  const discovery = await discoverMcpOAuth(resource, settings);
-  const client = await registerOAuthClient(db, settings, discovery.as, metadataUrl, redirectUri);
+  const discovery = await discoverMcpOAuth(mcpUrl, settings);
+  const resource = discovery.prm.resource ? canonicalOAuthResource(discovery.prm.resource) : mcpUrl;
   const verifier = randomPkceVerifier();
-  const authorizeScopes = chooseAuthorizeScopes(context.payload.requestedScopes, discovery.challenge.scope, discovery.prm.scopesSupported);
+  const authorizeScopes = chooseAuthorizeScopes(
+    context.payload.requestedScopes,
+    discovery.challenge.scope,
+    discovery.prm.scopesSupported,
+  );
+  const client = await registerOAuthClient(
+    db,
+    settings,
+    discovery.as,
+    metadataUrl,
+    redirectUri,
+    authorizeScopes,
+    context.payload.oauthClient,
+  );
   const key = requireEnvironmentEncryption(settings);
   const state = createSignedState(requireIntegrationsStateSecret(settings), {
     accountId: context.accountId,
     workspaceId: context.workspaceId,
     subjectId: context.subjectId,
     providerDomain,
+    mcpUrl,
     resource,
     requestedScopes: uniqueStrings(context.payload.requestedScopes ?? []),
     authorizeScopes,
@@ -145,6 +184,9 @@ export async function startMcpOAuth(
     issuer: client.issuer,
     clientRegistrationMethod: client.method,
     tokenEndpointAuthMethod: client.tokenEndpointAuthMethod,
+    ...(client.method === "manual" && client.clientSecret
+      ? { encryptedClientSecret: encryptEnvironmentValue(key, client.clientSecret) }
+      : {}),
     returnPath,
     ...(existing ? { connectionId: existing.id, connectionVersion: existing.version } : {}),
   });
@@ -168,24 +210,43 @@ export async function completeMcpOAuthCallback(
   deps: OAuthClientDeps,
   input: { code?: string | undefined; state?: string | undefined; requestUrl: string },
 ): Promise<OAuthCallbackResult> {
-  const { db, settings } = deps;
+  const { db, settings, observability } = deps;
+  let state: OAuthStatePayload | null = null;
   if (!input.state) {
-    throw new HTTPException(400, { message: "missing OAuth state" });
-  }
-  const state = readOAuthState(input.state, settings);
-  if (!input.code) {
-    return { redirectTo: callbackReturnPath(state.returnPath, "error", { reason: "missing_code" }) };
-  }
-  const consumed = await consumeIntegrationOAuthStateNonce(db, {
-    accountId: state.accountId,
-    workspaceId: state.workspaceId,
-    subjectId: state.subjectId,
-    nonce: state.nonce,
-    expiresAt: new Date(state.iat * 1000 + oauthStateTtlMs),
-    now: new Date(),
-  });
-  if (!consumed) {
-    throw new HTTPException(400, { message: "OAuth state has already been used" });
+    const error = new OAuthCallbackStageError(
+      "state_verify",
+      "state_invalid",
+      new Error("missing OAuth state"),
+    );
+    logOAuthCallbackFailure(observability, error, state);
+    return { redirectTo: callbackReturnPath("/integrations", "error", { reason: error.reason }) };
+  }
+  try {
+    state = readOAuthState(input.state, settings);
+    if (!input.code) {
+      return {
+        redirectTo: callbackReturnPath(state.returnPath, "error", { reason: "missing_code" }),
+      };
+    }
+    const consumed = await consumeIntegrationOAuthStateNonce(db, {
+      accountId: state.accountId,
+      workspaceId: state.workspaceId,
+      subjectId: state.subjectId,
+      nonce: state.nonce,
+      expiresAt: new Date(state.iat * 1000 + oauthStateTtlMs),
+      now: new Date(),
+    });
+    if (!consumed) {
+      throw new HTTPException(400, { message: "OAuth state has already been used" });
+    }
+  } catch (error) {
+    const staged = new OAuthCallbackStageError("state_verify", "state_invalid", error);
+    logOAuthCallbackFailure(observability, staged, state);
+    return {
+      redirectTo: callbackReturnPath(state?.returnPath ?? "/integrations", "error", {
+        reason: staged.reason,
+      }),
+    };
   }
 
   try {
@@ -194,67 +255,83 @@ export async function completeMcpOAuthCallback(
     const key = requireEnvironmentEncryption(settings);
     const verifier = decryptEnvironmentValue(key, state.encryptedPkceVerifier);
     const client = await clientForState(db, settings, state);
-    const token = await exchangeAuthorizationCode(settings, {
-      code: input.code,
-      verifier,
-      redirectUri,
-      resource: state.resource,
-      tokenEndpoint: state.tokenEndpoint,
-      client,
-    });
-    const tools = await verifyMcpToolsList(settings, state.resource, token);
+    const token = await runCallbackStage("token_exchange", "token_exchange_failed", () =>
+      exchangeAuthorizationCode(settings, {
+        code: input.code!,
+        verifier,
+        redirectUri,
+        resource: state.resource,
+        tokenEndpoint: state.tokenEndpoint,
+        client,
+      }),
+    );
+    const verification = await verifyMcpToolsListNonFatal(observability, settings, state, token);
     const scopes = grantedScopes(token.scopeText, state.authorizeScopes);
     const credential = credentialBundle(token, state, client);
     const metadata = {
       resource: state.resource,
+      mcpUrl: state.mcpUrl,
       authorizationServer: state.authorizationServer,
       authorizationServerIssuer: state.issuer,
       tokenEndpoint: state.tokenEndpoint,
       clientId: client.clientId,
       clientRegistrationMethod: state.clientRegistrationMethod,
-      mcpTools: tools,
+      mcpToolsVerification: verification.metadata,
+      ...(verification.tools ? { mcpTools: verification.tools } : {}),
     };
     const credentialEncrypted = encryptEnvironmentValue(key, JSON.stringify(credential));
-    const connection = state.connectionId
-      ? await updateConnection(db, {
-        workspaceId: state.workspaceId,
-        connectionId: state.connectionId,
-        visibleToSubjectId: state.subjectId,
-        expectedVersion: state.connectionVersion,
-        providerDomain: state.providerDomain,
-        kind: "oauth2",
-        status: "active",
-        credentialEncrypted,
-        grantedScopes: scopes,
-        expiresAt: token.expiresAt,
-        metadata,
-        updatedBySubjectId: state.subjectId,
-      })
-      : await createConnection(db, {
-        accountId: state.accountId,
-        workspaceId: state.workspaceId,
-        subjectId: null,
-        providerDomain: state.providerDomain,
-        kind: "oauth2",
-        credentialEncrypted,
-        grantedScopes: scopes,
-        expiresAt: token.expiresAt,
-        metadata,
-        createdBySubjectId: state.subjectId,
-      });
+    const connection = await runCallbackStage("persist", "persist_failed", () =>
+      state.connectionId
+        ? updateConnection(db, {
+            workspaceId: state.workspaceId,
+            connectionId: state.connectionId,
+            visibleToSubjectId: state.subjectId,
+            expectedVersion: state.connectionVersion,
+            providerDomain: state.providerDomain,
+            kind: "oauth2",
+            status: "active",
+            credentialEncrypted,
+            grantedScopes: scopes,
+            expiresAt: token.expiresAt,
+            metadata,
+            updatedBySubjectId: state.subjectId,
+          })
+        : createConnection(db, {
+            accountId: state.accountId,
+            workspaceId: state.workspaceId,
+            subjectId: null,
+            providerDomain: state.providerDomain,
+            kind: "oauth2",
+            credentialEncrypted,
+            grantedScopes: scopes,
+            expiresAt: token.expiresAt,
+            metadata,
+            createdBySubjectId: state.subjectId,
+          }),
+    );
     if (!connection) {
-      throw new HTTPException(409, { message: "connection changed during OAuth reconnect; start again" });
+      throw new HTTPException(409, {
+        message: "connection changed during OAuth reconnect; start again",
+      });
     }
     // Carry the canonical providerDomain (not just the id) so the SPA can build
     // the enable connectionRef straight from the redirect, without a listConnections
     // round-trip that could fail (transient, or a grant lacking connections:read)
     // and leave the connection created but the capability un-enabled.
-    return { redirectTo: callbackReturnPath(state.returnPath, "success", { connectionId: connection.id, providerDomain: connection.providerDomain }) };
+    return {
+      redirectTo: callbackReturnPath(state.returnPath, "success", {
+        connectionId: connection.id,
+        providerDomain: connection.providerDomain,
+        ...(verification.metadata.status === "failed" ? { verification: "failed" } : {}),
+      }),
+    };
   } catch (error) {
-    if (error instanceof HTTPException && error.status >= 400 && error.status < 500) {
-      throw error;
-    }
-    return { redirectTo: callbackReturnPath(state.returnPath, "error", { reason: "oauth_callback_failed" }) };
+    const staged =
+      error instanceof OAuthCallbackStageError
+        ? error
+        : new OAuthCallbackStageError("persist", "persist_failed", error);
+    logOAuthCallbackFailure(observability, staged, state);
+    return { redirectTo: callbackReturnPath(state.returnPath, "error", { reason: staged.reason }) };
   }
 }
 
@@ -265,30 +342,46 @@ export function integrationBaseUrl(publicBaseUrl: string | undefined, requestUrl
 export function requireIntegrationsStateSecret(settings: Settings): string {
   const secret = settings.integrationsStateSecret?.trim();
   if (!secret) {
-    throw new HTTPException(503, { message: "integrations OAuth requires OPENGENI_INTEGRATIONS_STATE_SECRET" });
+    throw new HTTPException(503, {
+      message: "integrations OAuth requires OPENGENI_INTEGRATIONS_STATE_SECRET",
+    });
   }
   return secret;
 }
 
-async function discoverMcpOAuth(resource: string, settings: Settings): Promise<{
+async function discoverMcpOAuth(
+  resource: string,
+  settings: Settings,
+): Promise<{
   challenge: WwwAuthenticateChallenge;
   prm: ProtectedResourceMetadata;
   as: AuthorizationServerMetadata;
 }> {
   const challenge = await probeMcpChallenge(resource, settings);
-  const prm = await discoverProtectedResourceMetadata(resource, settings, challenge.resourceMetadata);
+  const prm = await discoverProtectedResourceMetadata(
+    resource,
+    settings,
+    challenge.resourceMetadata,
+  );
   const authorizationServer = prm.authorizationServers[0];
   if (!authorizationServer) {
-    throw new HTTPException(422, { message: "MCP protected resource metadata did not advertise an authorization server" });
+    throw new HTTPException(422, {
+      message: "MCP protected resource metadata did not advertise an authorization server",
+    });
   }
   const as = await discoverAuthorizationServerMetadata(authorizationServer, settings);
   if (!as.codeChallengeMethodsSupported.includes("S256")) {
-    throw new HTTPException(422, { message: "authorization server does not support required PKCE S256" });
+    throw new HTTPException(422, {
+      message: "authorization server does not support required PKCE S256",
+    });
   }
   return { challenge, prm, as };
 }
 
-async function probeMcpChallenge(resource: string, settings: Settings): Promise<WwwAuthenticateChallenge> {
+async function probeMcpChallenge(
+  resource: string,
+  settings: Settings,
+): Promise<WwwAuthenticateChallenge> {
   const response = await fetchOAuth(resource, settings, {
     method: "GET",
     headers: { accept: "application/json" },
@@ -332,7 +425,10 @@ async function discoverProtectedResourceMetadata(
   throw new HTTPException(422, { message: "could not discover MCP protected resource metadata" });
 }
 
-async function discoverAuthorizationServerMetadata(authorizationServer: string, settings: Settings): Promise<AuthorizationServerMetadata> {
+async function discoverAuthorizationServerMetadata(
+  authorizationServer: string,
+  settings: Settings,
+): Promise<AuthorizationServerMetadata> {
   const candidates = uniqueStrings([
     authorizationServer,
     ...wellKnownCandidates(authorizationServer, "oauth-authorization-server"),
@@ -359,12 +455,17 @@ async function discoverAuthorizationServerMetadata(authorizationServer: string,
       authorizationEndpoint,
       tokenEndpoint,
       clientIdMetadataDocumentSupported: payload.client_id_metadata_document_supported === true,
+      tokenEndpointAuthMethodsSupported: stringArray(payload.token_endpoint_auth_methods_supported),
       codeChallengeMethodsSupported: stringArray(payload.code_challenge_methods_supported),
       raw: payload,
-      ...(stringValue(payload.registration_endpoint) ? { registrationEndpoint: stringValue(payload.registration_endpoint)! } : {}),
+      ...(stringValue(payload.registration_endpoint)
+        ? { registrationEndpoint: stringValue(payload.registration_endpoint)! }
+        : {}),
     };
   }
-  throw new HTTPException(422, { message: "could not discover OAuth authorization server metadata" });
+  throw new HTTPException(422, {
+    message: "could not discover OAuth authorization server metadata",
+  });
 }
 
 async function registerOAuthClient(
@@ -373,6 +474,8 @@ async function registerOAuthClient(
   as: AuthorizationServerMetadata,
   metadataUrl: string,
   redirectUri: string,
+  scopes: string[],
+  manual: OAuthStartRequest["oauthClient"],
 ): Promise<OAuthClientRegistration> {
   const operator = operatorClientForAs(settings, as);
   if (operator) {
@@ -387,15 +490,41 @@ async function registerOAuthClient(
       tokenEndpointAuthMethod: "none",
     };
   }
+  if (manual) {
+    return {
+      method: "manual",
+      issuer: as.issuer,
+      authorizationServer: as.authorizationServer,
+      clientId: manual.clientId,
+      ...(manual.clientSecret ? { clientSecret: manual.clientSecret } : {}),
+      tokenEndpointAuthMethod: tokenAuthMethod(
+        manual.tokenEndpointAuthMethod,
+        Boolean(manual.clientSecret),
+      ),
+    };
+  }
+  return await getOrCreateDynamicClientRegistration(db, settings, as, redirectUri, scopes);
+}
+
+async function getOrCreateDynamicClientRegistration(
+  db: Database,
+  settings: Settings,
+  as: AuthorizationServerMetadata,
+  redirectUri: string,
+  scopes: string[],
+): Promise<OAuthClientRegistration> {
   const storedClient = await loadIntegrationOAuthClient(db, settings, as.issuer);
-  if (storedClient) {
+  if (storedClient && storedDcrClientSatisfiesPolicy(storedClient, scopes)) {
     return {
       method: "dcr",
       issuer: storedClient.issuer,
       authorizationServer: storedClient.authorizationServer,
       clientId: storedClient.clientId,
       ...(storedClient.clientSecret ? { clientSecret: storedClient.clientSecret } : {}),
-      tokenEndpointAuthMethod: tokenAuthMethod(storedClient.tokenEndpointAuthMethod, Boolean(storedClient.clientSecret)),
+      tokenEndpointAuthMethod: tokenAuthMethod(
+        storedClient.tokenEndpointAuthMethod,
+        Boolean(storedClient.clientSecret),
+      ),
     };
   }
   if (!as.registrationEndpoint) {
@@ -403,29 +532,56 @@ async function registerOAuthClient(
       message: "manual OAuth client credentials are required for this authorization server",
     });
   }
-  const dcr = await dynamicClientRegistration(settings, as, redirectUri);
+  const dcr = await dynamicClientRegistration(settings, as, redirectUri, scopes);
   const key = dcr.clientSecret ? requireEnvironmentEncryption(settings) : null;
-  const storedWinner = await storeIntegrationOAuthClient(db, {
+  const storeInput = {
     issuer: as.issuer,
     authorizationServer: as.authorizationServer,
     clientId: dcr.clientId,
-    clientSecretEncrypted: dcr.clientSecret && key ? encryptEnvironmentValue(key, dcr.clientSecret) : null,
+    clientSecretEncrypted:
+      dcr.clientSecret && key ? encryptEnvironmentValue(key, dcr.clientSecret) : null,
     tokenEndpointAuthMethod: dcr.tokenEndpointAuthMethod,
-    metadata: {
-      registrationEndpoint: as.registrationEndpoint,
-      registeredAt: new Date().toISOString(),
-    },
-  });
+    metadata: registrationMetadata(as, scopes),
+  };
+  const storedWinner = await storeIntegrationOAuthClient(db, storeInput);
   if (storedWinner.clientId !== dcr.clientId) {
     const winner = await loadIntegrationOAuthClient(db, settings, as.issuer);
     if (!winner) {
-      throw new HTTPException(422, { message: "OAuth client registration could not be loaded after a registration race" });
+      throw new HTTPException(422, {
+        message: "OAuth client registration could not be loaded after a registration race",
+      });
     }
     return dcrRegistrationFromStored(winner);
   }
   return dcr;
 }
 
+function storedDcrClientSatisfiesPolicy(
+  stored: { metadata: Record<string, unknown> },
+  scopes: string[],
+): boolean {
+  return registeredScopesMatch(stored.metadata, scopes);
+}
+
+function registeredScopesMatch(metadata: Record<string, unknown>, scopes: string[]): boolean {
+  return stableScopeKey(stringArray(metadata.registeredScopes)) === stableScopeKey(scopes);
+}
+
+function stableScopeKey(scopes: string[]): string {
+  return uniqueStrings(scopes).sort().join(" ");
+}
+
+function registrationMetadata(
+  as: AuthorizationServerMetadata,
+  scopes: string[],
+): Record<string, unknown> {
+  return {
+    registrationEndpoint: as.registrationEndpoint,
+    registeredAt: new Date().toISOString(),
+    registeredScopes: uniqueStrings(scopes),
+  };
+}
+
 function dcrRegistrationFromStored(stored: {
   issuer: string;
   authorizationServer: string;
@@ -439,11 +595,17 @@ function dcrRegistrationFromStored(stored: {
     authorizationServer: stored.authorizationServer,
     clientId: stored.clientId,
     ...(stored.clientSecret ? { clientSecret: stored.clientSecret } : {}),
-    tokenEndpointAuthMethod: tokenAuthMethod(stored.tokenEndpointAuthMethod, Boolean(stored.clientSecret)),
+    tokenEndpointAuthMethod: tokenAuthMethod(
+      stored.tokenEndpointAuthMethod,
+      Boolean(stored.clientSecret),
+    ),
   };
 }
 
-function operatorClientForAs(settings: Settings, as: AuthorizationServerMetadata): OAuthClientRegistration | null {
+function operatorClientForAs(
+  settings: Settings,
+  as: AuthorizationServerMetadata,
+): OAuthClientRegistration | null {
   const entry = operatorClientEntryFor(settings, [as.issuer, as.authorizationServer]);
   if (!entry) {
     return null;
@@ -454,7 +616,10 @@ function operatorClientForAs(settings: Settings, as: AuthorizationServerMetadata
     authorizationServer: as.authorizationServer,
     clientId: entry.clientId,
     ...(entry.clientSecret ? { clientSecret: entry.clientSecret } : {}),
-    tokenEndpointAuthMethod: tokenAuthMethod(entry.tokenEndpointAuthMethod, Boolean(entry.clientSecret)),
+    tokenEndpointAuthMethod: tokenAuthMethod(
+      entry.tokenEndpointAuthMethod,
+      Boolean(entry.clientSecret),
+    ),
   };
 }
 
@@ -463,7 +628,9 @@ function operatorClientEntryFor(
   candidates: string[],
 ): ReturnType<typeof parseIntegrationsOauthClientsJson>[string] | null {
   const configured = parseIntegrationsOauthClientsJson(settings.integrationsOauthClientsJson);
-  const exactKeys = uniqueStrings(candidates.flatMap((candidate) => [candidate, normalizedIssuerKey(candidate)]));
+  const exactKeys = uniqueStrings(
+    candidates.flatMap((candidate) => [candidate, normalizedIssuerKey(candidate)]),
+  );
   for (const key of exactKeys) {
     const entry = configured[key];
     if (entry) {
@@ -487,9 +654,12 @@ async function dynamicClientRegistration(
   settings: Settings,
   as: AuthorizationServerMetadata,
   redirectUri: string,
+  scopes: string[],
 ): Promise<OAuthClientRegistration> {
   if (!as.registrationEndpoint) {
-    throw new HTTPException(422, { message: "authorization server does not support dynamic client registration" });
+    throw new HTTPException(422, {
+      message: "authorization server does not support dynamic client registration",
+    });
   }
   await assertOAuthFetchAllowed(as.registrationEndpoint, settings);
   const response = await fetchOAuth(as.registrationEndpoint, settings, {
@@ -501,15 +671,20 @@ async function dynamicClientRegistration(
       token_endpoint_auth_method: "none",
       grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
+      ...(scopes.length ? { scope: scopes.join(" ") } : {}),
     }),
   });
   if (!response.ok) {
-    throw new HTTPException(422, { message: `dynamic client registration failed with HTTP ${response.status}` });
+    throw new HTTPException(422, {
+      message: `dynamic client registration failed with HTTP ${response.status}`,
+    });
   }
-  const payload = await response.json() as Record<string, unknown>;
+  const payload = (await response.json()) as Record<string, unknown>;
   const clientId = stringValue(payload.client_id);
   if (!clientId) {
-    throw new HTTPException(422, { message: "dynamic client registration response did not include client_id" });
+    throw new HTTPException(422, {
+      message: "dynamic client registration response did not include client_id",
+    });
   }
   const clientSecret = stringValue(payload.client_secret);
   return {
@@ -518,10 +693,37 @@ async function dynamicClientRegistration(
     authorizationServer: as.authorizationServer,
     clientId,
     ...(clientSecret ? { clientSecret } : {}),
-    tokenEndpointAuthMethod: tokenAuthMethod(stringValue(payload.token_endpoint_auth_method), Boolean(clientSecret)),
+    tokenEndpointAuthMethod: tokenAuthMethod(
+      stringValue(payload.token_endpoint_auth_method),
+      Boolean(clientSecret),
+    ),
   };
 }
 
+async function existingOAuthConnectionForStart(
+  db: Database,
+  input: {
+    workspaceId: string;
+    subjectId: string;
+    providerDomain: string;
+    connectionId?: string | undefined;
+  },
+) {
+  if (input.connectionId) {
+    return await getConnectionMetadata(db, input.workspaceId, input.connectionId, input.subjectId);
+  }
+  const visible = await listConnectionsMetadata(db, input.workspaceId, input.subjectId);
+  return (
+    visible.find(
+      (connection) =>
+        connection.subjectId === null &&
+        connection.kind === "oauth2" &&
+        connection.status === "active" &&
+        connection.providerDomain === input.providerDomain,
+    ) ?? null
+  );
+}
+
 function buildAuthorizationUrl(input: {
   endpoint: string;
   clientId: string;
@@ -546,7 +748,10 @@ function buildAuthorizationUrl(input: {
 }
 
 function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
-  const payload = readSignedState(state, requireIntegrationsStateSecret(settings)) as Record<string, unknown> | null;
+  const payload = readSignedState(state, requireIntegrationsStateSecret(settings)) as Record<
+    string,
+    unknown
+  > | null;
   if (!payload) {
     throw new HTTPException(400, { message: "invalid or expired OAuth state" });
   }
@@ -555,21 +760,29 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
   if (iat === undefined || nowSeconds - iat > oauthStateTtlMs / 1000 || nowSeconds < iat) {
     throw new HTTPException(400, { message: "invalid or expired OAuth state" });
   }
+  const resource = requiredString(payload.resource, "state.resource");
   const parsed = {
     accountId: requiredString(payload.accountId, "state.accountId"),
     workspaceId: requiredString(payload.workspaceId, "state.workspaceId"),
     subjectId: requiredString(payload.subjectId, "state.subjectId"),
     providerDomain: requiredString(payload.providerDomain, "state.providerDomain"),
-    resource: requiredString(payload.resource, "state.resource"),
+    mcpUrl: stringValue(payload.mcpUrl) ?? resource,
+    resource,
     requestedScopes: stringArray(payload.requestedScopes),
     authorizeScopes: stringArray(payload.authorizeScopes),
-    encryptedPkceVerifier: requiredString(payload.encryptedPkceVerifier, "state.encryptedPkceVerifier"),
+    encryptedPkceVerifier: requiredString(
+      payload.encryptedPkceVerifier,
+      "state.encryptedPkceVerifier",
+    ),
     clientId: requiredString(payload.clientId, "state.clientId"),
     tokenEndpoint: requiredString(payload.tokenEndpoint, "state.tokenEndpoint"),
     authorizationServer: requiredString(payload.authorizationServer, "state.authorizationServer"),
     issuer: requiredString(payload.issuer, "state.issuer"),
     clientRegistrationMethod: registrationMethod(payload.clientRegistrationMethod),
     tokenEndpointAuthMethod: tokenAuthMethod(stringValue(payload.tokenEndpointAuthMethod), false),
+    ...(stringValue(payload.encryptedClientSecret)
+      ? { encryptedClientSecret: stringValue(payload.encryptedClientSecret)! }
+      : {}),
     returnPath: safeReturnPath(stringValue(payload.returnPath) ?? "/integrations"),
     nonce: requiredString(payload.nonce, "state.nonce"),
     iat,
@@ -583,7 +796,11 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
   };
 }
 
-async function clientForState(db: Database, settings: Settings, state: OAuthStatePayload): Promise<OAuthClientRegistration> {
+async function clientForState(
+  db: Database,
+  settings: Settings,
+  state: OAuthStatePayload,
+): Promise<OAuthClientRegistration> {
   if (state.clientRegistrationMethod === "cimd") {
     return {
       method: "cimd",
@@ -593,6 +810,19 @@ async function clientForState(db: Database, settings: Settings, state: OAuthStat
       tokenEndpointAuthMethod: "none",
     };
   }
+  if (state.clientRegistrationMethod === "manual") {
+    const key = requireEnvironmentEncryption(settings);
+    return {
+      method: "manual",
+      issuer: state.issuer,
+      authorizationServer: state.authorizationServer,
+      clientId: state.clientId,
+      ...(state.encryptedClientSecret
+        ? { clientSecret: decryptEnvironmentValue(key, state.encryptedClientSecret) }
+        : {}),
+      tokenEndpointAuthMethod: state.tokenEndpointAuthMethod,
+    };
+  }
   if (state.clientRegistrationMethod === "dcr") {
     const stored = await loadIntegrationOAuthClient(db, settings, state.issuer);
     if (!stored || stored.clientId !== state.clientId) {
@@ -604,12 +834,17 @@ async function clientForState(db: Database, settings: Settings, state: OAuthStat
       authorizationServer: stored.authorizationServer,
       clientId: stored.clientId,
       ...(stored.clientSecret ? { clientSecret: stored.clientSecret } : {}),
-      tokenEndpointAuthMethod: tokenAuthMethod(stored.tokenEndpointAuthMethod, Boolean(stored.clientSecret)),
+      tokenEndpointAuthMethod: tokenAuthMethod(
+        stored.tokenEndpointAuthMethod,
+        Boolean(stored.clientSecret),
+      ),
     };
   }
   const entry = operatorClientEntryFor(settings, [state.issuer, state.authorizationServer]);
   if (!entry || entry.clientId !== state.clientId) {
-    throw new HTTPException(400, { message: "operator OAuth client credentials are no longer available" });
+    throw new HTTPException(400, {
+      message: "operator OAuth client credentials are no longer available",
+    });
   }
   return {
     method: "operator",
@@ -617,7 +852,10 @@ async function clientForState(db: Database, settings: Settings, state: OAuthStat
     authorizationServer: state.authorizationServer,
     clientId: entry.clientId,
     ...(entry.clientSecret ? { clientSecret: entry.clientSecret } : {}),
-    tokenEndpointAuthMethod: tokenAuthMethod(entry.tokenEndpointAuthMethod, Boolean(entry.clientSecret)),
+    tokenEndpointAuthMethod: tokenAuthMethod(
+      entry.tokenEndpointAuthMethod,
+      Boolean(entry.clientSecret),
+    ),
   };
 }
 
@@ -639,18 +877,35 @@ async function exchangeAuthorizationCode(
   body.set("redirect_uri", input.redirectUri);
   body.set("code_verifier", input.verifier);
   body.set("resource", input.resource);
-  body.set("client_id", input.client.clientId);
-  const headers: Record<string, string> = { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
+  const headers: Record<string, string> = {
+    "content-type": "application/x-www-form-urlencoded",
+    accept: "application/json",
+  };
   if (input.client.clientSecret && input.client.tokenEndpointAuthMethod === "client_secret_post") {
+    body.set("client_id", input.client.clientId);
     body.set("client_secret", input.client.clientSecret);
-  } else if (input.client.clientSecret && input.client.tokenEndpointAuthMethod === "client_secret_basic") {
+  } else if (
+    input.client.clientSecret &&
+    input.client.tokenEndpointAuthMethod === "client_secret_basic"
+  ) {
     headers.authorization = `Basic ${Buffer.from(`${input.client.clientId}:${input.client.clientSecret}`).toString("base64")}`;
+  } else {
+    body.set("client_id", input.client.clientId);
   }
-  const response = await fetchOAuth(input.tokenEndpoint, settings, { method: "POST", headers, body });
+  const response = await fetchOAuth(input.tokenEndpoint, settings, {
+    method: "POST",
+    headers,
+    body,
+  });
   if (!response.ok) {
-    throw new Error(`OAuth token endpoint returned HTTP ${response.status}`);
+    const oauthError = await oauthErrorFromResponse(response);
+    throw new OAuthCallbackStageError(
+      "token_exchange",
+      oauthError ?? "token_exchange_failed",
+      new Error(`OAuth token endpoint returned HTTP ${response.status}`),
+    );
   }
-  const payload = await response.json() as Record<string, unknown>;
+  const payload = (await response.json()) as Record<string, unknown>;
   const accessToken = stringValue(payload.access_token);
   if (!accessToken) {
     throw new Error("OAuth token response did not include access_token");
@@ -660,22 +915,124 @@ async function exchangeAuthorizationCode(
     tokenType: stringValue(payload.token_type) ?? "Bearer",
     expiresAt: expiresAtFromTokenResponse(payload),
     raw: payload,
-    ...(stringValue(payload.refresh_token) ? { refreshToken: stringValue(payload.refresh_token)! } : {}),
+    ...(stringValue(payload.refresh_token)
+      ? { refreshToken: stringValue(payload.refresh_token)! }
+      : {}),
     ...(stringValue(payload.scope) ? { scopeText: stringValue(payload.scope)! } : {}),
   };
 }
 
-async function verifyMcpToolsList(settings: Settings, resource: string, token: TokenResponse): Promise<Array<{ name: string; description?: string }>> {
+async function runCallbackStage<T>(
+  callbackStage: OAuthCallbackStage,
+  fallbackReason: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof OAuthCallbackStageError) {
+      throw error;
+    }
+    throw new OAuthCallbackStageError(callbackStage, fallbackReason, error);
+  }
+}
+
+function logOAuthCallbackFailure(
+  observability: Observability | undefined,
+  error: OAuthCallbackStageError,
+  state: OAuthStatePayload | null,
+): void {
+  observability?.error("MCP OAuth callback failed", {
+    "opengeni.oauth.stage": error.stage,
+    "opengeni.oauth.reason": error.reason,
+    "opengeni.oauth.provider_domain": state?.providerDomain,
+    "opengeni.oauth.resource_host": state ? safeHost(state.resource) : undefined,
+    "opengeni.oauth.authorization_server": state?.authorizationServer,
+    "opengeni.oauth.issuer": state?.issuer,
+    "opengeni.oauth.client_registration_method": state?.clientRegistrationMethod,
+    error: sanitizedError(error.cause),
+  });
+}
+
+function logOAuthVerificationWarning(
+  observability: Observability | undefined,
+  error: OAuthCallbackStageError,
+  state: OAuthStatePayload,
+): void {
+  observability?.warn("MCP OAuth tools/list verification failed after token exchange", {
+    "opengeni.oauth.stage": error.stage,
+    "opengeni.oauth.reason": error.reason,
+    "opengeni.oauth.provider_domain": state.providerDomain,
+    "opengeni.oauth.resource_host": safeHost(state.resource),
+    "opengeni.oauth.mcp_host": safeHost(state.mcpUrl),
+    "opengeni.oauth.authorization_server": state.authorizationServer,
+    "opengeni.oauth.issuer": state.issuer,
+    "opengeni.oauth.client_registration_method": state.clientRegistrationMethod,
+    error: sanitizedError(error.cause),
+  });
+}
+
+function sanitizedError(error: unknown): string {
+  if (error instanceof HTTPException) {
+    return `HTTPException ${error.status}: ${error.message}`;
+  }
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return String(error);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function safeHost(rawUrl: string): string | undefined {
+  try {
+    return new URL(rawUrl).host;
+  } catch {
+    return undefined;
+  }
+}
+
+async function oauthErrorFromResponse(response: Response): Promise<string | null> {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("application/json")) {
+    return null;
+  }
+  const payload = (await response
+    .clone()
+    .json()
+    .catch(() => null)) as Record<string, unknown> | null;
+  const error = stringValue(payload?.error);
+  if (!error || !/^[a-zA-Z0-9_.-]{1,80}$/.test(error)) {
+    return null;
+  }
+  return error;
+}
+
+async function verifyMcpToolsList(
+  settings: Settings,
+  resource: string,
+  token: TokenResponse,
+): Promise<Array<{ name: string; description?: string }>> {
   await assertOAuthFetchAllowed(resource, settings);
-  const client = new Client({ name: "opengeni-integration-verify", version: "0.1.0" }, { capabilities: {} });
+  const client = new Client(
+    { name: "opengeni-integration-verify", version: "0.1.0" },
+    { capabilities: {} },
+  );
   try {
     const transport = new StreamableHTTPClientTransport(new URL(resource), {
       requestInit: {
-        headers: { authorization: `${token.tokenType} ${token.accessToken}` },
+        headers: {
+          authorization: `${normalizeBearerScheme(token.tokenType)} ${token.accessToken}`,
+        },
       },
       fetch: (url, init) => fetchOAuth(url.toString(), settings, init),
     });
-    await client.connect(transport as unknown as Transport, { timeout: 10_000, maxTotalTimeout: 10_000 });
+    await client.connect(transport as unknown as Transport, {
+      timeout: 10_000,
+      maxTotalTimeout: 10_000,
+    });
     const listed = await client.listTools(undefined, { timeout: 10_000, maxTotalTimeout: 10_000 });
     return listed.tools.map((tool) => ({
       name: tool.name,
@@ -686,21 +1043,78 @@ async function verifyMcpToolsList(settings: Settings, resource: string, token: T
   }
 }
 
-function credentialBundle(token: TokenResponse, state: OAuthStatePayload, client: OAuthClientRegistration): Record<string, unknown> {
+async function verifyMcpToolsListNonFatal(
+  observability: Observability | undefined,
+  settings: Settings,
+  state: OAuthStatePayload,
+  token: TokenResponse,
+): Promise<{
+  metadata:
+    | { status: "ok"; checkedAt: string; toolCount: number }
+    | { status: "failed"; checkedAt: string; reason: string };
+  tools?: Array<{ name: string; description?: string }>;
+}> {
+  try {
+    const tools = await runCallbackStage("tools_list", "tools_list_failed", () =>
+      verifyMcpToolsList(settings, state.mcpUrl, token),
+    );
+    return {
+      metadata: {
+        status: "ok",
+        checkedAt: new Date().toISOString(),
+        toolCount: tools.length,
+      },
+      tools,
+    };
+  } catch (error) {
+    const staged =
+      error instanceof OAuthCallbackStageError
+        ? error
+        : new OAuthCallbackStageError("tools_list", "tools_list_failed", error);
+    logOAuthVerificationWarning(observability, staged, state);
+    return {
+      metadata: {
+        status: "failed",
+        checkedAt: new Date().toISOString(),
+        reason: staged.reason,
+      },
+    };
+  }
+}
+
+function credentialBundle(
+  token: TokenResponse,
+  state: OAuthStatePayload,
+  client: OAuthClientRegistration,
+): Record<string, unknown> {
   return {
     access_token: token.accessToken,
     ...(token.refreshToken ? { refresh_token: token.refreshToken } : {}),
     token_type: token.tokenType,
     ...(token.expiresAt ? { expires_at: token.expiresAt.toISOString() } : {}),
     resource: state.resource,
-    ...(token.scopeText ? { scope: token.scopeText } : state.authorizeScopes.length ? { scope: state.authorizeScopes.join(" ") } : {}),
+    mcp_url: state.mcpUrl,
+    ...(token.scopeText
+      ? { scope: token.scopeText }
+      : state.authorizeScopes.length
+        ? { scope: state.authorizeScopes.join(" ") }
+        : {}),
     token_endpoint: state.tokenEndpoint,
     client_id: client.clientId,
-    ...(client.clientSecret ? { client_secret: client.clientSecret, token_endpoint_auth_method: client.tokenEndpointAuthMethod } : {}),
+    ...(client.clientSecret
+      ? {
+          client_secret: client.clientSecret,
+          token_endpoint_auth_method: client.tokenEndpointAuthMethod,
+        }
+      : {}),
   };
 }
 
-function callbackReturnPath(returnPath: string, status: "success" | "error", params: Record<string, string>): string {
+function callbackReturnPath(
+  returnPath: string,
+  status: "success" | "error",
+  params: Record<string, string>,
+): string {
   const url = new URL(returnPath, "https://opengeni.local");
   url.searchParams.set("integration_oauth", status);
   for (const [key, value] of Object.entries(params)) {
@@ -723,6 +1137,27 @@ function canonicalMcpResource(value: string | undefined): string {
   return url.toString();
 }
 
+function canonicalOAuthResource(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new HTTPException(422, {
+      message: "MCP protected resource metadata advertised an invalid resource",
+    });
+  }
+  try {
+    const url = new URL(trimmed);
+    if (url.protocol === "http:" || url.protocol === "https:") {
+      url.hash = "";
+      return url.toString();
+    }
+    return trimmed;
+  } catch {
+    throw new HTTPException(422, {
+      message: "MCP protected resource metadata advertised an invalid resource",
+    });
+  }
+}
+
 function safeReturnPath(value: string): string {
   if (!value.startsWith("/") || value.startsWith("//")) {
     throw new HTTPException(400, { message: "OAuth returnPath must be a relative path" });
@@ -746,7 +1181,12 @@ async function fetchJsonObject(url: string, settings: Settings): Promise<Record<
   return payload as Record<string, unknown>;
 }
 
-async function fetchOAuth(rawUrl: string, settings: Settings, init: RequestInit = {}, hop = 0): Promise<Response> {
+async function fetchOAuth(
+  rawUrl: string,
+  settings: Settings,
+  init: RequestInit = {},
+  hop = 0,
+): Promise<Response> {
   await assertOAuthFetchAllowed(rawUrl, settings);
   const response = await fetch(rawUrl, { ...init, redirect: "manual" });
   if (response.status < 300 || response.status >= 400) {
@@ -773,20 +1213,29 @@ async function assertOAuthFetchAllowed(rawUrl: string, settings: Settings): Prom
   if (!["https:", "http:"].includes(url.protocol)) {
     throw new HTTPException(422, { message: "OAuth discovery only supports http and https URLs" });
   }
-  if (settings.integrationsAllowPrivateNetworkTargets || ["local", "test"].includes(settings.environment)) {
+  if (
+    settings.integrationsAllowPrivateNetworkTargets ||
+    ["local", "test"].includes(settings.environment)
+  ) {
     return;
   }
   if (url.protocol !== "https:") {
-    throw new HTTPException(422, { message: "OAuth discovery targets must use https outside local/test" });
+    throw new HTTPException(422, {
+      message: "OAuth discovery targets must use https outside local/test",
+    });
   }
   const hostname = url.hostname.toLowerCase();
   if (hostname === "localhost" || hostname.endsWith(".localhost")) {
     throw new HTTPException(422, { message: "OAuth discovery may not target localhost" });
   }
   const literal = isIP(hostname);
-  const addresses = literal ? [hostname] : (await lookup(hostname, { all: true })).map((entry) => entry.address);
+  const addresses = literal
+    ? [hostname]
+    : (await lookup(hostname, { all: true })).map((entry) => entry.address);
   if (addresses.some(isPrivateAddress)) {
-    throw new HTTPException(422, { message: "OAuth discovery may not target private network addresses" });
+    throw new HTTPException(422, {
+      message: "OAuth discovery may not target private network addresses",
+    });
   }
 }
 
@@ -804,7 +1253,9 @@ function parseWwwAuthenticate(header: string | null): WwwAuthenticateChallenge {
   let match: RegExpExecArray | null;
   while ((match = re.exec(paramsText)) !== null) {
     const raw = match[2]!;
-    params[match[1]!.toLowerCase()] = raw.startsWith("\"") ? raw.slice(1, -1).replace(/\\"/g, "\"") : raw;
+    params[match[1]!.toLowerCase()] = raw.startsWith('"')
+      ? raw.slice(1, -1).replace(/\\"/g, '"')
+      : raw;
   }
   return {
     ...(params.resource_metadata ? { resourceMetadata: params.resource_metadata } : {}),
@@ -823,7 +1274,11 @@ function wellKnownCandidates(rawUrl: string, name: string): string[] {
   ]);
 }
 
-function chooseAuthorizeScopes(requested: string[] | undefined, challenged: string[] | undefined, supported: string[]): string[] {
+function chooseAuthorizeScopes(
+  requested: string[] | undefined,
+  challenged: string[] | undefined,
+  supported: string[],
+): string[] {
   if (requested?.length) {
     return uniqueStrings(requested);
   }
@@ -840,7 +1295,10 @@ function grantedScopes(scopeText: string | undefined, fallback: string[]): strin
   return fallback;
 }
 
-function tokenAuthMethod(raw: string | undefined, hasSecret: boolean): OAuthClientRegistration["tokenEndpointAuthMethod"] {
+function tokenAuthMethod(
+  raw: string | undefined,
+  hasSecret: boolean,
+): OAuthClientRegistration["tokenEndpointAuthMethod"] {
   if (raw === "client_secret_post" || raw === "client_secret_basic") {
     return raw;
   }
@@ -848,7 +1306,7 @@ function tokenAuthMethod(raw: string | undefined, hasSecret: boolean): OAuthClie
 }
 
 function registrationMethod(value: unknown): OAuthClientRegistration["method"] {
-  if (value === "operator" || value === "cimd" || value === "dcr") {
+  if (value === "operator" || value === "manual" || value === "cimd" || value === "dcr") {
     return value;
   }
   throw new HTTPException(400, { message: "invalid OAuth state" });
@@ -860,7 +1318,8 @@ function expiresAtFromTokenResponse(payload: Record<string, unknown>): Date | nu
     const parsed = new Date(expiresAt);
     return Number.isNaN(parsed.getTime()) ? null : parsed;
   }
-  const expiresIn = typeof payload.expires_in === "number" ? payload.expires_in : Number(payload.expires_in);
+  const expiresIn =
+    typeof payload.expires_in === "number" ? payload.expires_in : Number(payload.expires_in);
   if (Number.isFinite(expiresIn) && expiresIn > 0) {
     return new Date(Date.now() + expiresIn * 1000);
   }
@@ -880,7 +1339,9 @@ function uniqueStrings(values: string[]): string[] {
 }
 
 function stringArray(value: unknown): string[] {
-  return Array.isArray(value) ? uniqueStrings(value.filter((entry): entry is string => typeof entry === "string")) : [];
+  return Array.isArray(value)
+    ? uniqueStrings(value.filter((entry): entry is string => typeof entry === "string"))
+    : [];
 }
 
 function stringValue(value: unknown): string | undefined {