@opengeni/api-router 0.5.1 → 0.5.3

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   createApp
-} from "./chunk-DQ5TIRDZ.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.1",
+  "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": {
@@ -47,16 +47,16 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opengeni/agent-proto": "^0.2.1",
     "@opengeni/codex": "^0.2.1",
-    "@opengeni/config": "^0.3.0",
+    "@opengeni/config": "^0.4.0",
     "@opengeni/contracts": "^0.9.0",
-    "@opengeni/core": "^0.4.4",
-    "@opengeni/db": "^0.6.0",
-    "@opengeni/documents": "^0.2.7",
-    "@opengeni/events": "^0.2.7",
-    "@opengeni/github": "^0.2.7",
-    "@opengeni/observability": "^0.2.1",
-    "@opengeni/runtime": "^0.5.0",
-    "@opengeni/storage": "^0.2.7",
+    "@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.3.0",
+    "@opengeni/runtime": "^0.6.1",
+    "@opengeni/storage": "^0.2.8",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",

package/src/app.ts

@@ -21,6 +21,7 @@ import { buildOpenGeniMcpServer } from "./mcp/server";
 import { isToolspaceGrant, prepareToolspaceMcpSurface } from "./mcp/toolspace";
 import { requireAccessKey } from "./http/auth";
 import { registerCapabilityRoutes } from "./routes/capabilities";
+import { registerCatalogAssetRoutes } from "./routes/catalog-assets";
 import { registerCodexRoutes } from "./routes/codex";
 import { registerConnectionRoutes } from "./routes/connections";
 import { registerDocumentRoutes } from "./routes/documents";
@@ -246,6 +247,7 @@ export function createApp(deps: AppDependencies): Hono {
   registerSocialRoutes(app, routeDeps);
   registerConnectionRoutes(app, routeDeps);
   registerCapabilityRoutes(app, routeDeps);
+  registerCatalogAssetRoutes(app, routeDeps);
   registerEnrollmentRoutes(app, routeDeps);
   registerMachineRoutes(app, routeDeps);
   registerEnvironmentRoutes(app, routeDeps);
@@ -426,6 +428,7 @@ const routeLabelPatterns: Array<{ pattern: RegExp; label: string }> = [
   { pattern: /^\/v1\/workspaces\/[^/]+\/connections$/, label: "/v1/workspaces/:workspaceId/connections" },
   { pattern: /^\/v1\/workspaces\/[^/]+\/connections\/oauth\/start$/, label: "/v1/workspaces/:workspaceId/connections/oauth/start" },
   { pattern: /^\/v1\/workspaces\/[^/]+\/connections\/[^/]+$/, label: "/v1/workspaces/:workspaceId/connections/:connectionId" },
+  { pattern: /^\/v1\/catalog-assets\/.+$/, label: "/v1/catalog-assets/*" },
   { pattern: /^\/v1\/integrations\/oauth\/callback$/, label: "/v1/integrations/oauth/callback" },
   { pattern: /^\/v1\/integrations\/oauth\/client-metadata\.json$/, label: "/v1/integrations/oauth/client-metadata.json" },
   { pattern: /^\/v1\/enrollments\/device\/start$/, label: "/v1/enrollments/device/start" },

package/src/http/auth.ts

@@ -52,6 +52,12 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   ) {
     return true;
   }
+  // Catalog logos are rendered via bare <img> tags, which carry no credentials;
+  // the images are public vendor logos, digest-keyed by content, and the route
+  // itself enforces the catalog-assets/ prefix lock and extension whitelist.
+  if (path.startsWith("/v1/catalog-assets/")) {
+    return true;
+  }
   // Browser entry for MCP-issued GitHub install links: opened in a browser
   // that holds no API credentials, like the callbacks above. The route itself
   // verifies the signed workspace-bound state before doing anything.

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,
@@ -22,12 +23,14 @@ import { createHash, randomBytes } from "node:crypto";
 import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
 import { HTTPException } from "hono/http-exception";
+import { canonicalProviderDomain } from "./provider-domain";
 
 export const oauthStateTtlMs = 10 * 60 * 1000;
 
 type OAuthClientDeps = {
   db: Database;
   settings: Settings;
+  observability?: Observability | undefined;
 };
 
 export type OAuthStartContext = {
@@ -80,6 +83,7 @@ type OAuthStatePayload = {
   workspaceId: string;
   subjectId: string;
   providerDomain: string;
+  mcpUrl: string;
   resource: string;
   requestedScopes: string[];
   authorizeScopes: string[];
@@ -106,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`;
@@ -124,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);
@@ -134,6 +152,7 @@ export async function startMcpOAuth(
     workspaceId: context.workspaceId,
     subjectId: context.subjectId,
     providerDomain,
+    mcpUrl,
     resource,
     requestedScopes: uniqueStrings(context.payload.requestedScopes ?? []),
     authorizeScopes,
@@ -167,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 {
@@ -193,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,
@@ -229,7 +259,7 @@ export async function completeMcpOAuthCallback(
         metadata,
         updatedBySubjectId: state.subjectId,
       })
-      : await createConnection(db, {
+      : createConnection(db, {
         accountId: state.accountId,
         workspaceId: state.workspaceId,
         subjectId: null,
@@ -240,16 +270,27 @@ 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" });
     }
-    return { redirectTo: callbackReturnPath(state.returnPath, "success", { connectionId: connection.id }) };
+    // 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,
+        ...(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 }) };
   }
 }
 
@@ -550,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"),
@@ -643,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);
@@ -660,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: {} });
@@ -681,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,
@@ -688,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,
@@ -718,8 +884,21 @@ function canonicalMcpResource(value: string | undefined): string {
   return url.toString();
 }
 
-function canonicalProviderDomain(value: string): string {
-  return value.trim().toLowerCase().replace(/^www\./, "");
+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 {

package/src/integrations/provider-domain.ts

@@ -0,0 +1,15 @@
+import { HTTPException } from "hono/http-exception";
+
+/**
+ * Canonical form of a connection's providerDomain: trimmed, lowercased, no
+ * leading "www.". Rejects a value that canonicalizes to empty (whitespace-only,
+ * or a bare "www.") — `min(1)` validation passes such input, but an empty stored
+ * domain silently breaks the enable-time connectionRef domain match.
+ */
+export function canonicalProviderDomain(value: string): string {
+  const canonical = value.trim().toLowerCase().replace(/^www\./, "");
+  if (!canonical) {
+    throw new HTTPException(400, { message: "providerDomain must not be empty" });
+  }
+  return canonical;
+}

package/src/routes/catalog-assets.ts

@@ -0,0 +1,105 @@
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import type { ApiRouteDeps } from "@opengeni/core";
+
+const CATALOG_ASSET_PREFIX = "catalog-assets/";
+const MAX_KEY_LENGTH = 512;
+const PRINTABLE_ASCII = /^[\x20-\x7e]+$/;
+
+const CONTENT_TYPE_BY_EXTENSION: Record<string, string> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  svg: "image/svg+xml",
+  webp: "image/webp",
+  gif: "image/gif",
+  ico: "image/x-icon",
+};
+
+export function registerCatalogAssetRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const { settings, objectStorage } = deps;
+
+  app.get("/v1/catalog-assets/*", async (c) => {
+    if (!settings.integrationsEnabled) {
+      throw new HTTPException(404, { message: "integrations are not enabled for this deployment" });
+    }
+    if (!objectStorage) {
+      throw new HTTPException(404, { message: "asset not found" });
+    }
+    const key = catalogAssetKeyFromPath(new URL(c.req.url).pathname);
+    if (!key) {
+      throw new HTTPException(404, { message: "asset not found" });
+    }
+    const contentType = contentTypeForKey(key);
+    if (!contentType) {
+      throw new HTTPException(404, { message: "asset not found" });
+    }
+    const object = await objectStorage.getObjectBytes(key);
+    if (!object) {
+      throw new HTTPException(404, { message: "asset not found" });
+    }
+    const etag = etagForKey(key);
+    const headers = {
+      "Cache-Control": "public, max-age=31536000, immutable",
+      ETag: etag,
+      "X-Content-Type-Options": "nosniff",
+      "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+    };
+    if (ifNoneMatchSatisfied(c.req.header("if-none-match"), etag)) {
+      return c.body(null, 304, headers);
+    }
+    // Copy narrows the AWS/GCS/Azure SDKs' ArrayBufferLike-backed Uint8Array to the
+    // ArrayBuffer-backed one Hono's body() type expects.
+    return c.body(new Uint8Array(object.bytes), 200, { ...headers, "Content-Type": contentType });
+  });
+}
+
+/** Decoded, validated storage key from a `/v1/catalog-assets/...` request path, or null if malformed/unsafe. */
+export function catalogAssetKeyFromPath(pathname: string): string | null {
+  const prefix = "/v1/";
+  if (!pathname.startsWith(prefix)) {
+    return null;
+  }
+  let key: string;
+  try {
+    key = decodeURIComponent(pathname.slice(prefix.length));
+  } catch {
+    return null;
+  }
+  if (
+    key.length === 0 ||
+    key.length > MAX_KEY_LENGTH ||
+    !key.startsWith(CATALOG_ASSET_PREFIX) ||
+    key.includes("..") ||
+    key.includes("\\") ||
+    key.includes("//") ||
+    !PRINTABLE_ASCII.test(key)
+  ) {
+    return null;
+  }
+  return key;
+}
+
+function contentTypeForKey(key: string): string | null {
+  const match = /\.([a-zA-Z0-9]+)$/.exec(key);
+  const ext = match?.[1]?.toLowerCase();
+  return ext ? CONTENT_TYPE_BY_EXTENSION[ext] ?? null : null;
+}
+
+/** Digest-keyed filenames (`{domain}/{digest24}.{ext}`) make the basename itself a stable ETag. */
+function etagForKey(key: string): string {
+  const filename = key.slice(key.lastIndexOf("/") + 1);
+  const dot = filename.lastIndexOf(".");
+  const digest = dot === -1 ? filename : filename.slice(0, dot);
+  return `"${digest}"`;
+}
+
+function ifNoneMatchSatisfied(header: string | undefined, etag: string): boolean {
+  if (!header) {
+    return false;
+  }
+  if (header.trim() === "*") {
+    return true;
+  }
+  return header.split(",").map((value) => value.trim()).includes(etag);
+}

package/src/routes/connections.ts

@@ -24,9 +24,10 @@ import {
   integrationBaseUrl,
   startMcpOAuth,
 } from "../integrations/oauth-client";
+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) {
@@ -52,7 +53,7 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
       accountId: grant.accountId,
       workspaceId,
       subjectId,
-      providerDomain: payload.providerDomain,
+      providerDomain: canonicalProviderDomain(payload.providerDomain),
       kind: payload.kind,
       credentialEncrypted: encryptCredentialBundle(key, payload.credential),
       grantedScopes: payload.grantedScopes,
@@ -96,7 +97,7 @@ export function registerConnectionRoutes(app: Hono, deps: ApiRouteDeps): void {
       connectionId: c.req.param("connectionId"),
       visibleToSubjectId: grant.subjectId,
       updatedBySubjectId: grant.subjectId,
-      ...(payload.providerDomain !== undefined ? { providerDomain: payload.providerDomain } : {}),
+      ...(payload.providerDomain !== undefined ? { providerDomain: canonicalProviderDomain(payload.providerDomain) } : {}),
       ...(subjectId !== undefined ? { subjectId } : {}),
       ...(payload.kind !== undefined ? { kind: payload.kind } : {}),
       ...(payload.status !== undefined ? { status: payload.status } : {}),
@@ -130,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,
@@ -142,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,