@opengeni/api-router 0.22.2 → 0.26.1

package/src/integrations/oauth-client.ts

@@ -45,8 +45,16 @@ import { canonicalProviderDomain } from "./provider-domain";
 
 export const oauthStateTtlMs = 10 * 60 * 1000;
 export const OFFICIAL_SLACK_MCP_URL = OPENGENI_PERSONAL_SLACK_MCP_URL;
+export const OFFICIAL_GMAIL_MCP_URL = "https://gmailmcp.googleapis.com/mcp/v1";
+export const OFFICIAL_GMAIL_MCP_SCOPES = [
+  "https://www.googleapis.com/auth/gmail.readonly",
+  "https://www.googleapis.com/auth/gmail.compose",
+  "https://www.googleapis.com/auth/gmail.modify",
+] as const;
 const SLACK_OAUTH_ORIGIN = "https://slack.com";
 const SLACK_MCP_ORIGIN = "https://mcp.slack.com";
+const GOOGLE_OAUTH_ISSUER_ORIGIN = "https://accounts.google.com";
+const GOOGLE_TOKEN_ORIGIN = "https://oauth2.googleapis.com";
 export { OAUTH_MAX_RESPONSE_BYTES } from "@opengeni/network";
 
 type OAuthClientDeps = {
@@ -120,6 +128,7 @@ type OAuthStatePayload = {
   issuer: string;
   clientRegistrationMethod: OAuthClientRegistration["method"];
   tokenEndpointAuthMethod: OAuthClientRegistration["tokenEndpointAuthMethod"];
+  resourceParameterSupported: boolean;
   encryptedClientSecret?: string;
   returnPath: string;
   connectionId?: string;
@@ -282,8 +291,7 @@ export async function startMcpOAuth(
       error instanceof OAuthStartStageError
         ? error
         : new OAuthStartStageError("connection_lookup", oauthStartFailureReason(error), error);
-    const providerDomain = safeRequestedProviderDomain(context.payload);
-    logOAuthStartFailure(deps.observability, staged, providerDomain);
+    logOAuthStartFailure(deps.observability, staged);
     throw oauthStartApiError(staged);
   } finally {
     deadline.dispose();
@@ -297,21 +305,15 @@ async function startMcpOAuthWithinDeadline(
 ): Promise<OAuthStartResponse> {
   const { db, settings } = deps;
   const mcpUrl = canonicalMcpResource(context.payload.mcpUrl ?? context.payload.resource);
+  const officialGmailResource = mcpUrl === OFFICIAL_GMAIL_MCP_URL;
   const officialSlackResource = mcpUrl === OFFICIAL_SLACK_MCP_URL;
   const providerDomain = officialSlackResource
     ? "slack.com"
     : canonicalProviderDomain(context.payload.providerDomain ?? new URL(mcpUrl).hostname);
-  const personalSlack = officialSlackResource || providerDomain === "slack.com";
-  assertPersonalSlackOAuthStart(settings, context.payload, mcpUrl, personalSlack);
-  if (personalSlack && context.payload.ownership === "workspace") {
-    throw new HTTPException(422, {
-      message:
-        "Slack's hosted MCP connection is personal; use the OpenGeni Slack bot installation for workspace access",
-    });
-  }
-  const requestedOwnership: ConnectionOwnership = personalSlack
-    ? "personal"
-    : (context.payload.ownership ?? "workspace");
+  const hostedSlackMcp = officialSlackResource || providerDomain === "slack.com";
+  assertHostedSlackMcpOAuthStart(settings, context.payload, mcpUrl, hostedSlackMcp);
+  const requestedOwnership: ConnectionOwnership = context.payload.ownership ?? "workspace";
+  assertOfficialGmailPersonalOwnership(mcpUrl, requestedOwnership);
   const returnPath = safeReturnPath(context.payload.returnPath ?? "/integrations");
   const baseUrl = integrationBaseUrl(settings.publicBaseUrl, context.requestUrl);
   const redirectUri = `${baseUrl}/v1/integrations/oauth/callback`;
@@ -322,7 +324,8 @@ async function startMcpOAuthWithinDeadline(
       subjectId: context.subjectId,
       providerDomain,
       mcpUrl,
-      personalSlack,
+      hostedSlackMcp,
+      exactMcpBinding: hostedSlackMcp || officialGmailResource,
       connectionId: context.payload.connectionId,
       requestedOwnership: context.payload.ownership,
       newConnectionOwnership: requestedOwnership,
@@ -336,16 +339,29 @@ async function startMcpOAuthWithinDeadline(
     : requestedOwnership;
 
   const discovery = await discoverMcpOAuth(mcpUrl, settings, deadline);
-  if (personalSlack && !isLocalTestEnvironment(settings.environment)) {
+  if (hostedSlackMcp && !isLocalTestEnvironment(settings.environment)) {
     assertSlackAuthorizationServer(discovery.as);
   }
+  const googleAuthorizationServer = hasGoogleAuthorizationServerIdentity(discovery.as);
+  if (officialGmailResource || googleAuthorizationServer) {
+    if (!officialGmailResource || providerDomain !== "gmailmcp.googleapis.com") {
+      throw new HTTPException(422, {
+        message: `Google OAuth is allowed only for ${OFFICIAL_GMAIL_MCP_URL}`,
+      });
+    }
+    assertGoogleAuthorizationServer(discovery.as);
+  }
+  const resourceParameterSupported = !officialGmailResource;
   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,
-  );
+  // The Gmail PRM advertises broader grants, including full-mail access. The
+  // reviewed connector never lets a caller widen the capability contract.
+  const authorizeScopes = chooseMcpAuthorizeScopes({
+    mcpUrl,
+    requested: context.payload.requestedScopes,
+    challenged: discovery.challenge.scope,
+    supported: discovery.prm.scopesSupported,
+  });
   const client = await deadline.run("client_registration", (signal) =>
     registerOAuthClient(
       db,
@@ -367,7 +383,9 @@ async function startMcpOAuthWithinDeadline(
     providerDomain,
     mcpUrl,
     resource,
-    requestedScopes: uniqueStrings(context.payload.requestedScopes ?? []),
+    requestedScopes: officialGmailResource
+      ? [...OFFICIAL_GMAIL_MCP_SCOPES]
+      : uniqueStrings(context.payload.requestedScopes ?? []),
     authorizeScopes,
     encryptedPkceVerifier: encryptEnvironmentValue(key, verifier),
     clientId: client.clientId,
@@ -376,6 +394,7 @@ async function startMcpOAuthWithinDeadline(
     issuer: client.issuer,
     clientRegistrationMethod: client.method,
     tokenEndpointAuthMethod: client.tokenEndpointAuthMethod,
+    resourceParameterSupported,
     ...(client.method === "manual" && client.clientSecret
       ? {
           encryptedClientSecret: encryptEnvironmentValue(key, client.clientSecret),
@@ -393,6 +412,7 @@ async function startMcpOAuthWithinDeadline(
     resource,
     verifier,
     scopes: authorizeScopes,
+    resourceParameterSupported,
   });
   return OAuthStartResponse.parse({
     state,
@@ -401,6 +421,18 @@ async function startMcpOAuthWithinDeadline(
   });
 }
 
+export function assertOfficialGmailPersonalOwnership(
+  mcpUrl: string,
+  ownership: ConnectionOwnership,
+): void {
+  if (mcpUrl === OFFICIAL_GMAIL_MCP_URL && ownership !== "personal") {
+    throw new HTTPException(422, {
+      message:
+        "Gmail connections are personal only; each workspace member must connect their own mailbox",
+    });
+  }
+}
+
 export async function completeMcpOAuthCallback(
   deps: OAuthClientDeps,
   input: {
@@ -446,6 +478,9 @@ async function completeMcpOAuthCallbackWithinDeadline(
   }
   try {
     state = readOAuthState(input.state, settings);
+    // Fence state minted by an older deployment too: a rolling update must not
+    // let a still-valid workspace-owned Gmail callback persist shared authority.
+    assertOfficialGmailPersonalOwnership(state.mcpUrl, state.ownership);
     if (!input.code) {
       return {
         redirectTo: callbackReturnPath(state.returnPath, "error", {
@@ -506,6 +541,7 @@ async function completeMcpOAuthCallbackWithinDeadline(
         resource: state.resource,
         tokenEndpoint: state.tokenEndpoint,
         client,
+        resourceParameterSupported: state.resourceParameterSupported,
         signal,
       }),
     );
@@ -620,13 +656,13 @@ async function requireOAuthCallbackGrant(db: Database, state: OAuthStatePayload)
   }
 }
 
-function assertPersonalSlackOAuthStart(
+function assertHostedSlackMcpOAuthStart(
   settings: Settings,
   payload: OAuthStartRequest,
   mcpUrl: string,
-  personalSlack: boolean,
+  hostedSlackMcp: boolean,
 ): void {
-  if (!personalSlack) return;
+  if (!hostedSlackMcp) return;
   if (payload.oauthClient) {
     throw new HTTPException(422, {
       message: "Slack OAuth client credentials are deployment-managed",
@@ -639,13 +675,12 @@ function assertPersonalSlackOAuthStart(
   }
   if (!isLocalTestEnvironment(settings.environment) && mcpUrl !== OFFICIAL_SLACK_MCP_URL) {
     throw new HTTPException(422, {
-      message: `personal Slack OAuth must use ${OFFICIAL_SLACK_MCP_URL}`,
+      message: `Slack MCP OAuth must use ${OFFICIAL_SLACK_MCP_URL}`,
     });
   }
   if (!settings.slackClientId?.trim() || !settings.slackClientSecret?.trim()) {
     throw new HTTPException(503, {
-      message:
-        "personal Slack OAuth requires OPENGENI_SLACK_CLIENT_ID and OPENGENI_SLACK_CLIENT_SECRET",
+      message: "Slack MCP OAuth requires OPENGENI_SLACK_CLIENT_ID and OPENGENI_SLACK_CLIENT_SECRET",
     });
   }
 }
@@ -665,6 +700,27 @@ export function assertSlackAuthorizationServer(as: AuthorizationServerMetadata):
   }
 }
 
+function hasGoogleAuthorizationServerIdentity(as: AuthorizationServerMetadata): boolean {
+  return [as.issuer, as.authorizationServer].some(
+    (value) => new URL(value).origin === GOOGLE_OAUTH_ISSUER_ORIGIN,
+  );
+}
+
+export function assertGoogleAuthorizationServer(as: AuthorizationServerMetadata): void {
+  const issuerOrigins = [as.issuer, as.authorizationServer].map((value) => new URL(value).origin);
+  const authorizationOrigin = new URL(as.authorizationEndpoint).origin;
+  const tokenOrigin = new URL(as.tokenEndpoint).origin;
+  if (
+    issuerOrigins.some((origin) => origin !== GOOGLE_OAUTH_ISSUER_ORIGIN) ||
+    authorizationOrigin !== GOOGLE_OAUTH_ISSUER_ORIGIN ||
+    tokenOrigin !== GOOGLE_TOKEN_ORIGIN
+  ) {
+    throw new HTTPException(422, {
+      message: "Gmail MCP authorization metadata did not remain bound to Google",
+    });
+  }
+}
+
 async function discoverMcpOAuth(
   resource: string,
   settings: Settings,
@@ -1154,7 +1210,8 @@ async function existingOAuthConnectionForStart(
     subjectId: string;
     providerDomain: string;
     mcpUrl: string;
-    personalSlack: boolean;
+    hostedSlackMcp: boolean;
+    exactMcpBinding: boolean;
     connectionId?: string | undefined;
     requestedOwnership?: ConnectionOwnership | undefined;
     newConnectionOwnership: ConnectionOwnership;
@@ -1177,7 +1234,7 @@ async function existingOAuthConnectionForStart(
       });
     }
     return connection.providerDomain === input.providerDomain &&
-      (!input.personalSlack || connection.metadata.mcpUrl === input.mcpUrl)
+      (!input.exactMcpBinding || connection.metadata.mcpUrl === input.mcpUrl)
       ? connection
       : null;
   }
@@ -1188,9 +1245,9 @@ async function existingOAuthConnectionForStart(
       connection.subjectId === ownerSubjectId &&
       connection.kind === "oauth2" &&
       connection.providerDomain === input.providerDomain &&
-      (!input.personalSlack || connection.metadata.mcpUrl === input.mcpUrl),
+      (!input.exactMcpBinding || connection.metadata.mcpUrl === input.mcpUrl),
   );
-  if (input.personalSlack) {
+  if (input.hostedSlackMcp && input.newConnectionOwnership === "personal") {
     return selectCanonicalPersonalSlackConnection(matching);
   }
   return matching.find((connection) => connection.status === "active") ?? null;
@@ -1205,7 +1262,7 @@ function ownershipForConnection(
   throw new HTTPException(404, { message: "connection not found" });
 }
 
-function buildAuthorizationUrl(input: {
+export function buildAuthorizationUrl(input: {
   endpoint: string;
   settings: Settings;
   clientId: string;
@@ -1214,6 +1271,7 @@ function buildAuthorizationUrl(input: {
   resource: string;
   verifier: string;
   scopes: string[];
+  resourceParameterSupported: boolean;
 }): string {
   const endpoint = oauthEndpointUrl(input.endpoint, input.settings, "OAuth authorization endpoint");
   const url = new URL(endpoint);
@@ -1221,7 +1279,16 @@ function buildAuthorizationUrl(input: {
   url.searchParams.set("client_id", input.clientId);
   url.searchParams.set("redirect_uri", input.redirectUri);
   url.searchParams.set("state", input.state);
-  url.searchParams.set("resource", input.resource);
+  if (input.resourceParameterSupported) {
+    url.searchParams.set("resource", input.resource);
+  } else {
+    // Google's OAuth endpoints do not implement RFC 8707's `resource`
+    // parameter. Explicit offline consent is required to obtain the refresh
+    // token used by the durable connection broker.
+    url.searchParams.set("access_type", "offline");
+    url.searchParams.set("include_granted_scopes", "true");
+    url.searchParams.set("prompt", "consent");
+  }
   url.searchParams.set("code_challenge_method", "S256");
   url.searchParams.set("code_challenge", pkceChallenge(input.verifier));
   if (input.scopes.length > 0) {
@@ -1278,6 +1345,9 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
     ),
     clientRegistrationMethod: registrationMethod(payload.clientRegistrationMethod),
     tokenEndpointAuthMethod: tokenAuthMethod(stringValue(payload.tokenEndpointAuthMethod), false),
+    // States minted before provider-specific compatibility was introduced used
+    // the RFC 8707 resource parameter.
+    resourceParameterSupported: payload.resourceParameterSupported !== false,
     ...(stringValue(payload.encryptedClientSecret)
       ? { encryptedClientSecret: stringValue(payload.encryptedClientSecret)! }
       : {}),
@@ -1380,6 +1450,7 @@ async function exchangeAuthorizationCode(
     verifier: string;
     redirectUri: string;
     resource: string;
+    resourceParameterSupported: boolean;
     tokenEndpoint: string;
     client: OAuthClientRegistration;
     signal: AbortSignal;
@@ -1390,7 +1461,9 @@ async function exchangeAuthorizationCode(
   body.set("code", input.code);
   body.set("redirect_uri", input.redirectUri);
   body.set("code_verifier", input.verifier);
-  body.set("resource", input.resource);
+  if (input.resourceParameterSupported) {
+    body.set("resource", input.resource);
+  }
   const headers: Record<string, string> = {
     "content-type": "application/x-www-form-urlencoded",
     accept: "application/json",
@@ -1474,31 +1547,16 @@ function throwIfCallbackAborted(signal: AbortSignal, stage: OAuthCallbackStage):
 function logOAuthCallbackFailure(
   observability: Observability | undefined,
   error: OAuthCallbackStageError,
-  state: OAuthStatePayload | null,
+  _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),
-  });
+  observability?.error("MCP OAuth callback failed", oauthPublicErrorFields(error.cause));
 }
 
 function logOAuthStartFailure(
   observability: Observability | undefined,
   error: OAuthStartStageError,
-  providerDomain: string | undefined,
 ): void {
-  observability?.warn("MCP OAuth setup failed", {
-    "opengeni.oauth.stage": error.stage,
-    "opengeni.oauth.reason": error.reason,
-    "opengeni.oauth.provider_domain": providerDomain,
-    error: sanitizedError(error.cause),
-  });
+  observability?.warn("MCP OAuth setup failed", oauthPublicErrorFields(error.cause));
 }
 
 function oauthStartFailureReason(error: unknown): string {
@@ -1528,7 +1586,11 @@ function oauthCallbackFailureReason(stage: OAuthCallbackStage, error: unknown):
 function isDatabaseStatementTimeout(error: unknown): boolean {
   let current = error;
   for (let depth = 0; depth < 4 && current && typeof current === "object"; depth += 1) {
-    const candidate = current as { code?: unknown; message?: unknown; cause?: unknown };
+    const candidate = current as {
+      code?: unknown;
+      message?: unknown;
+      cause?: unknown;
+    };
     if (
       candidate.code === "57014" ||
       (typeof candidate.message === "string" &&
@@ -1581,51 +1643,47 @@ function oauthStartStageLabel(stage: OAuthStartStage): string {
 function logOAuthVerificationWarning(
   observability: Observability | undefined,
   error: OAuthCallbackStageError,
-  state: OAuthStatePayload,
+  _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);
+  observability?.warn(
+    "MCP OAuth tools/list verification failed after token exchange",
+    oauthPublicErrorFields(error.cause),
+  );
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
+export type OAuthPublicErrorFields = {
+  errorClass: "OAuthOperationError";
+  errorCode: "oauth_operation_failed";
+  status?: number;
+  origin: "oauth";
+};
 
-function safeHost(rawUrl: string): string | undefined {
+/** Allowlisted projection for public telemetry; canonical OAuth errors stay exact. */
+export function oauthPublicErrorFields(error: unknown): OAuthPublicErrorFields {
+  const fields: OAuthPublicErrorFields = {
+    errorClass: "OAuthOperationError",
+    errorCode: "oauth_operation_failed",
+    origin: "oauth",
+  };
   try {
-    return new URL(rawUrl).host;
+    const rawStatus =
+      error instanceof HTTPException
+        ? error.status
+        : error && typeof error === "object"
+          ? ((error as { status?: unknown; statusCode?: unknown }).status ??
+            (error as { statusCode?: unknown }).statusCode)
+          : undefined;
+    const status = Number(rawStatus);
+    if (Number.isInteger(status) && status >= 100 && status <= 599) fields.status = status;
   } catch {
-    return undefined;
+    // Public telemetry is best-effort. A hostile getter/proxy must never
+    // replace the exact OAuth failure with a projection failure.
   }
+  return fields;
 }
 
-function safeRequestedProviderDomain(payload: OAuthStartRequest): string | undefined {
-  try {
-    const resource = payload.mcpUrl ?? payload.resource;
-    if (!resource) return undefined;
-    return canonicalProviderDomain(payload.providerDomain ?? new URL(resource).hostname);
-  } catch {
-    return undefined;
-  }
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
 }
 
 async function oauthErrorFromResponse(
@@ -1747,6 +1805,7 @@ function credentialBundle(
     token_type: token.tokenType,
     ...(token.expiresAt ? { expires_at: token.expiresAt.toISOString() } : {}),
     resource: state.resource,
+    resource_parameter_supported: state.resourceParameterSupported,
     mcp_url: state.mcpUrl,
     ...(token.scopeText
       ? { scope: token.scopeText }
@@ -1996,6 +2055,17 @@ function chooseAuthorizeScopes(
   return uniqueStrings(supported);
 }
 
+export function chooseMcpAuthorizeScopes(input: {
+  mcpUrl: string;
+  requested: string[] | undefined;
+  challenged: string[] | undefined;
+  supported: string[];
+}): string[] {
+  return input.mcpUrl === OFFICIAL_GMAIL_MCP_URL
+    ? [...OFFICIAL_GMAIL_MCP_SCOPES]
+    : chooseAuthorizeScopes(input.requested, input.challenged, input.supported);
+}
+
 function grantedScopes(scopeText: string | undefined, fallback: string[]): string[] {
   if (scopeText) {
     return uniqueStrings(scopeText.split(/\s+/).filter(Boolean));