@opengeni/api-router 0.5.3 → 0.5.5

package/src/integrations/oauth-client.ts

@@ -12,7 +12,9 @@ import {
   encryptEnvironmentValue,
   getConnectionMetadata,
   isPrivateAddress,
+  listConnectionsMetadata,
   loadIntegrationOAuthClient,
+  normalizeBearerScheme,
   storeIntegrationOAuthClient,
   updateConnection,
   type Database,
@@ -65,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;
@@ -94,6 +97,7 @@ type OAuthStatePayload = {
   issuer: string;
   clientRegistrationMethod: OAuthClientRegistration["method"];
   tokenEndpointAuthMethod: OAuthClientRegistration["tokenEndpointAuthMethod"];
+  encryptedClientSecret?: string;
   returnPath: string;
   connectionId?: string;
   connectionVersion?: number;
@@ -129,23 +133,40 @@ export async function startMcpOAuth(
 ): Promise<OAuthStartResponse> {
   const { db, settings } = deps;
   const mcpUrl = canonicalMcpResource(context.payload.mcpUrl ?? context.payload.resource);
-  const providerDomain = canonicalProviderDomain(context.payload.providerDomain ?? new URL(mcpUrl).hostname);
+  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(mcpUrl, settings);
   const resource = discovery.prm.resource ? canonicalOAuthResource(discovery.prm.resource) : mcpUrl;
-  const client = await registerOAuthClient(db, settings, discovery.as, metadataUrl, redirectUri);
   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,
@@ -163,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 } : {}),
   });
@@ -189,14 +213,20 @@ export async function completeMcpOAuthCallback(
   const { db, settings, observability } = deps;
   let state: OAuthStatePayload | null = null;
   if (!input.state) {
-    const error = new OAuthCallbackStageError("state_verify", "state_invalid", new Error("missing OAuth state"));
+    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" }) };
+      return {
+        redirectTo: callbackReturnPath(state.returnPath, "error", { reason: "missing_code" }),
+      };
     }
     const consumed = await consumeIntegrationOAuthStateNonce(db, {
       accountId: state.accountId,
@@ -212,7 +242,11 @@ export async function completeMcpOAuthCallback(
   } 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 }) };
+    return {
+      redirectTo: callbackReturnPath(state?.returnPath ?? "/integrations", "error", {
+        reason: staged.reason,
+      }),
+    };
   }
 
   try {
@@ -221,14 +255,16 @@ export async function completeMcpOAuthCallback(
     const key = requireEnvironmentEncryption(settings);
     const verifier = decryptEnvironmentValue(key, state.encryptedPkceVerifier);
     const client = await clientForState(db, settings, state);
-    const token = await stage("token_exchange", "token_exchange_failed", () => exchangeAuthorizationCode(settings, {
-      code: input.code!,
-      verifier,
-      redirectUri,
-      resource: state.resource,
-      tokenEndpoint: state.tokenEndpoint,
-      client,
-    }));
+    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);
@@ -244,35 +280,39 @@ export async function completeMcpOAuthCallback(
       ...(verification.tools ? { mcpTools: verification.tools } : {}),
     };
     const credentialEncrypted = encryptEnvironmentValue(key, JSON.stringify(credential));
-    const connection = await stage("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,
-      }));
+    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
@@ -286,9 +326,10 @@ export async function completeMcpOAuthCallback(
       }),
     };
   } catch (error) {
-    const staged = error instanceof OAuthCallbackStageError
-      ? error
-      : new OAuthCallbackStageError("persist", "persist_failed", error);
+    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 }) };
   }
@@ -301,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" },
@@ -368,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"),
@@ -395,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(
@@ -409,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) {
@@ -423,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) {
@@ -439,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;
@@ -475,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;
@@ -490,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),
+    ),
   };
 }
 
@@ -499,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) {
@@ -523,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, {
@@ -537,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 {
@@ -554,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;
@@ -582,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" });
   }
@@ -601,13 +770,19 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
     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,
@@ -621,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",
@@ -631,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) {
@@ -642,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",
@@ -655,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),
+    ),
   };
 }
 
@@ -677,19 +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) {
     const oauthError = await oauthErrorFromResponse(response);
-    throw new OAuthCallbackStageError("token_exchange", oauthError ?? "token_exchange_failed", new Error(`OAuth token endpoint returned HTTP ${response.status}`));
+    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");
@@ -699,13 +915,15 @@ 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 stage<T>(
-  stage: OAuthCallbackStage,
+async function runCallbackStage<T>(
+  callbackStage: OAuthCallbackStage,
   fallbackReason: string,
   fn: () => Promise<T>,
 ): Promise<T> {
@@ -715,7 +933,7 @@ async function stage<T>(
     if (error instanceof OAuthCallbackStageError) {
       throw error;
     }
-    throw new OAuthCallbackStageError(stage, fallbackReason, error);
+    throw new OAuthCallbackStageError(callbackStage, fallbackReason, error);
   }
 }
 
@@ -781,7 +999,10 @@ async function oauthErrorFromResponse(response: Response): Promise<string | null
   if (!contentType.toLowerCase().includes("application/json")) {
     return null;
   }
-  const payload = await response.clone().json().catch(() => null) as Record<string, unknown> | 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;
@@ -789,17 +1010,29 @@ async function oauthErrorFromResponse(response: Response): Promise<string | null
   return error;
 }
 
-async function verifyMcpToolsList(settings: Settings, resource: string, token: TokenResponse): Promise<Array<{ name: string; description?: string }>> {
+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,
@@ -822,7 +1055,9 @@ async function verifyMcpToolsListNonFatal(
   tools?: Array<{ name: string; description?: string }>;
 }> {
   try {
-    const tools = await stage("tools_list", "tools_list_failed", () => verifyMcpToolsList(settings, state.mcpUrl, token));
+    const tools = await runCallbackStage("tools_list", "tools_list_failed", () =>
+      verifyMcpToolsList(settings, state.mcpUrl, token),
+    );
     return {
       metadata: {
         status: "ok",
@@ -832,9 +1067,10 @@ async function verifyMcpToolsListNonFatal(
       tools,
     };
   } catch (error) {
-    const staged = error instanceof OAuthCallbackStageError
-      ? error
-      : new OAuthCallbackStageError("tools_list", "tools_list_failed", error);
+    const staged =
+      error instanceof OAuthCallbackStageError
+        ? error
+        : new OAuthCallbackStageError("tools_list", "tools_list_failed", error);
     logOAuthVerificationWarning(observability, staged, state);
     return {
       metadata: {
@@ -846,7 +1082,11 @@ async function verifyMcpToolsListNonFatal(
   }
 }
 
-function credentialBundle(token: TokenResponse, state: OAuthStatePayload, client: OAuthClientRegistration): Record<string, unknown> {
+function credentialBundle(
+  token: TokenResponse,
+  state: OAuthStatePayload,
+  client: OAuthClientRegistration,
+): Record<string, unknown> {
   return {
     access_token: token.accessToken,
     ...(token.refreshToken ? { refresh_token: token.refreshToken } : {}),
@@ -854,14 +1094,27 @@ function credentialBundle(token: TokenResponse, state: OAuthStatePayload, client
     ...(token.expiresAt ? { expires_at: token.expiresAt.toISOString() } : {}),
     resource: state.resource,
     mcp_url: state.mcpUrl,
-    ...(token.scopeText ? { scope: token.scopeText } : state.authorizeScopes.length ? { scope: state.authorizeScopes.join(" ") } : {}),
+    ...(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)) {
@@ -887,7 +1140,9 @@ function canonicalMcpResource(value: string | undefined): string {
 function canonicalOAuthResource(value: string): string {
   const trimmed = value.trim();
   if (!trimmed) {
-    throw new HTTPException(422, { message: "MCP protected resource metadata advertised an invalid resource" });
+    throw new HTTPException(422, {
+      message: "MCP protected resource metadata advertised an invalid resource",
+    });
   }
   try {
     const url = new URL(trimmed);
@@ -897,7 +1152,9 @@ function canonicalOAuthResource(value: string): string {
     }
     return trimmed;
   } catch {
-    throw new HTTPException(422, { message: "MCP protected resource metadata advertised an invalid resource" });
+    throw new HTTPException(422, {
+      message: "MCP protected resource metadata advertised an invalid resource",
+    });
   }
 }
 
@@ -924,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) {
@@ -951,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",
+    });
   }
 }
 
@@ -982,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 } : {}),
@@ -1001,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);
   }
@@ -1018,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;
   }
@@ -1026,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" });
@@ -1038,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);
   }
@@ -1058,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 {