@opengeni/api-router 0.5.2 → 0.5.3

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   createApp
-} from "./chunk-YY6OAEL6.js";
+} from "./chunk-3HIA43CC.js";
 
 // src/index.ts
 import { dbSearchPath, getSettings, resolveNatsCalloutConfig, resolveNatsControlPlaneAuth, retryStartupDependency, startupRetryOptions } from "@opengeni/config";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -49,13 +49,13 @@
     "@opengeni/codex": "^0.2.1",
     "@opengeni/config": "^0.4.0",
     "@opengeni/contracts": "^0.9.0",
-    "@opengeni/core": "^0.4.5",
+    "@opengeni/core": "^0.4.6",
     "@opengeni/db": "^0.6.1",
     "@opengeni/documents": "^0.2.8",
     "@opengeni/events": "^0.2.8",
     "@opengeni/github": "^0.2.8",
-    "@opengeni/observability": "^0.2.1",
-    "@opengeni/runtime": "^0.6.0",
+    "@opengeni/observability": "^0.3.0",
+    "@opengeni/runtime": "^0.6.1",
     "@opengeni/storage": "^0.2.8",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",

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,
@@ -29,6 +30,7 @@ export const oauthStateTtlMs = 10 * 60 * 1000;
 type OAuthClientDeps = {
   db: Database;
   settings: Settings;
+  observability?: Observability | undefined;
 };
 
 export type OAuthStartContext = {
@@ -81,6 +83,7 @@ type OAuthStatePayload = {
   workspaceId: string;
   subjectId: string;
   providerDomain: string;
+  mcpUrl: string;
   resource: string;
   requestedScopes: string[];
   authorizeScopes: string[];
@@ -107,13 +110,26 @@ 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`;
@@ -125,7 +141,8 @@ export async function startMcpOAuth(
     throw new HTTPException(404, { message: "connection not found" });
   }
 
-  const discovery = await discoverMcpOAuth(resource, settings);
+  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);
@@ -135,6 +152,7 @@ export async function startMcpOAuth(
     workspaceId: context.workspaceId,
     subjectId: context.subjectId,
     providerDomain,
+    mcpUrl,
     resource,
     requestedScopes: uniqueStrings(context.payload.requestedScopes ?? []),
     authorizeScopes,
@@ -168,24 +186,33 @@ 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,29 +221,31 @@ 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,
+    const token = await stage("token_exchange", "token_exchange_failed", () => exchangeAuthorizationCode(settings, {
+      code: input.code!,
       verifier,
       redirectUri,
       resource: state.resource,
       tokenEndpoint: state.tokenEndpoint,
       client,
-    });
-    const tools = await verifyMcpToolsList(settings, state.resource, token);
+    }));
+    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, {
+    const connection = await stage("persist", "persist_failed", () => state.connectionId
+      ? updateConnection(db, {
         workspaceId: state.workspaceId,
         connectionId: state.connectionId,
         visibleToSubjectId: state.subjectId,
@@ -230,7 +259,7 @@ export async function completeMcpOAuthCallback(
         metadata,
         updatedBySubjectId: state.subjectId,
       })
-      : await createConnection(db, {
+      : createConnection(db, {
         accountId: state.accountId,
         workspaceId: state.workspaceId,
         subjectId: null,
@@ -241,7 +270,7 @@ export async function completeMcpOAuthCallback(
         expiresAt: token.expiresAt,
         metadata,
         createdBySubjectId: state.subjectId,
-      });
+      }));
     if (!connection) {
       throw new HTTPException(409, { message: "connection changed during OAuth reconnect; start again" });
     }
@@ -249,12 +278,19 @@ export async function completeMcpOAuthCallback(
     // 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 }) };
   }
 }
 
@@ -555,12 +591,14 @@ 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"),
@@ -648,7 +686,8 @@ async function exchangeAuthorizationCode(
   }
   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 accessToken = stringValue(payload.access_token);
@@ -665,6 +704,91 @@ async function exchangeAuthorizationCode(
   };
 }
 
+async function stage<T>(
+  stage: OAuthCallbackStage,
+  fallbackReason: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof OAuthCallbackStageError) {
+      throw error;
+    }
+    throw new OAuthCallbackStageError(stage, 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: {} });
@@ -686,6 +810,42 @@ async function verifyMcpToolsList(settings: Settings, resource: string, token: T
   }
 }
 
+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 stage("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,
@@ -693,6 +853,7 @@ function credentialBundle(token: TokenResponse, state: OAuthStatePayload, client
     token_type: token.tokenType,
     ...(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_endpoint: state.tokenEndpoint,
     client_id: client.clientId,
@@ -723,6 +884,23 @@ 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" });

package/src/routes/connections.ts

@@ -27,7 +27,7 @@ import {
 import { canonicalProviderDomain } from "../integrations/provider-domain";
 
 export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
-  const { db, settings } = deps;
+  const { db, settings, observability } = deps;
 
   function assertIntegrationsEnabled(): void {
     if (!settings.integrationsEnabled) {
@@ -131,7 +131,7 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
       throw new HTTPException(400, { message: parsed.error.issues[0]?.message ?? "invalid OAuth start request" });
     }
     const payload = parsed.data;
-    const result = await startMcpOAuth({ db, settings }, {
+    const result = await startMcpOAuth({ db, settings, observability }, {
       accountId: grant.accountId,
       workspaceId,
       subjectId: grant.subjectId,
@@ -143,7 +143,7 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.get("/v1/integrations/oauth/callback", async (c) => {
     assertIntegrationsEnabled();
-    const result = await completeMcpOAuthCallback({ db, settings }, {
+    const result = await completeMcpOAuthCallback({ db, settings, observability }, {
       code: c.req.query("code"),
       state: c.req.query("state"),
       requestUrl: c.req.url,