@opengeni/api-router 4.1.0 → 4.1.2-canary.36199476632001

package/src/http/sse.ts

@@ -448,17 +448,28 @@ export async function sseSessionStream(
   stopReconnectObservation = durableFanout.subscribeRecovery(scheduleReconnectReconciliation);
 
   void (async () => {
-    const release = await bus.subscribe(workspaceId, sessionId, (events) => {
-      if (bootstrapping) {
-        for (const event of events) {
-          if (!newestBuffered || event.sequence > newestBuffered.sequence) {
-            newestBuffered = event;
+    const release = await bus.subscribe(
+      workspaceId,
+      sessionId,
+      (events) => {
+        if (bootstrapping) {
+          for (const event of events) {
+            if (!newestBuffered || event.sequence > newestBuffered.sequence) {
+              newestBuffered = event;
+            }
           }
+        } else {
+          delivery?.publish(events);
         }
-      } else {
-        delivery?.publish(events);
-      }
-    });
+      },
+      {
+        // Live fanout stopped while this stream still held it. Heartbeats alone
+        // would keep a silently stale timeline open; fail retryably so the
+        // client reconnects and replays from the durable Postgres cursor.
+        onTerminated: (error) =>
+          fail(retryableSseFailure("session live fanout subscription ended", error)),
+      },
+    );
     if (channel.stopped()) {
       release();
       return;
@@ -632,13 +643,22 @@ export async function sseWorkspaceControlStream(
   delivery = createLatestWinsDelivery(send, fail);
 
   void (async () => {
-    const release = await bus.subscribeWorkspaceControl(workspaceId, (event) => {
-      if (bootstrapping) {
-        if (!newestBuffered || event.sequence > newestBuffered.sequence) newestBuffered = event;
-      } else {
-        delivery?.publish([event]);
-      }
-    });
+    const release = await bus.subscribeWorkspaceControl(
+      workspaceId,
+      (event) => {
+        if (bootstrapping) {
+          if (!newestBuffered || event.sequence > newestBuffered.sequence) newestBuffered = event;
+        } else {
+          delivery?.publish([event]);
+        }
+      },
+      {
+        // Same contract as session SSE: a dead live subscription must reconnect
+        // and replay the durable control cursor, not idle on heartbeats.
+        onTerminated: (error) =>
+          fail(retryableSseFailure("workspace control live subscription ended", error)),
+      },
+    );
     if (channel.stopped()) {
       release();
       return;

package/src/http/user-content.ts

@@ -0,0 +1,158 @@
+/**
+ * Response headers for user-controlled bytes served from the API origin.
+ *
+ * Retained files, screenshots, exports, and live frames carry bytes and, for
+ * uploads, a content type chosen by a user or agent. The API shares its origin
+ * with the web console in the default deployment, so a stored `text/html` file
+ * opened by top-level navigation would otherwise run as that origin.
+ *
+ * Every such response therefore:
+ * - is a sandboxed document with no script, form, popup, plugin, or network
+ *   capability (`sandbox` plus `default-src 'none'`). Raster images and text
+ *   still render when a URL is opened directly;
+ * - cannot be embedded by another site as a no-cors subresource (CORP);
+ * - is never re-sniffed into a different type (`nosniff`).
+ *
+ * Audio and video keep their real origin (`sandbox allow-same-origin`, still
+ * without `allow-scripts`): the browser's synthesized media document re-fetches
+ * its own URL, and from an opaque origin that same-origin-only request would be
+ * refused. With scripts disabled and `nosniff`, such a response can only ever
+ * be a media player, never attacker markup.
+ *
+ * Markup types that a browser would render as an active document (HTML, XML,
+ * SVG, multipart) are additionally served as attachments, so a direct
+ * navigation downloads the bytes instead of showing attacker-authored markup on
+ * the app origin. The console never navigates to these routes: it reads bytes
+ * through the SDK and renders them in app-owned elements, so neither header
+ * changes an in-app preview. Signed object-storage GET URLs for active markup
+ * carry the same attachment as a signed response override
+ * (`userContentSignedGetUrlOptions`), because the storage endpoint is not
+ * always a separate site.
+ */
+const USER_CONTENT_FETCH_DIRECTIVES =
+  "default-src 'none'; img-src 'self' data: blob:; media-src 'self' data: blob:; style-src 'unsafe-inline'";
+
+export const USER_CONTENT_SECURITY_POLICY = `${USER_CONTENT_FETCH_DIRECTIVES}; sandbox`;
+
+/** Media players only; scripts stay disabled (see the module comment). */
+export const USER_MEDIA_CONTENT_SECURITY_POLICY = `${USER_CONTENT_FETCH_DIRECTIVES}; sandbox allow-same-origin`;
+
+export const USER_CONTENT_SECURITY_HEADERS = Object.freeze({
+  "Content-Security-Policy": USER_CONTENT_SECURITY_POLICY,
+  "Cross-Origin-Resource-Policy": "same-origin",
+  "X-Content-Type-Options": "nosniff",
+} as const);
+
+const ACTIVE_DOCUMENT_TYPES = new Set(["text/html", "text/xml", "text/xsl", "application/xml"]);
+
+/** Media type essence (no parameters), lowercased. */
+function mediaTypeEssence(contentType: string): string {
+  return (contentType.split(";", 1)[0] ?? "").trim().toLowerCase();
+}
+
+/**
+ * True when a browser would render this type as an active document (HTML,
+ * XHTML, SVG, any XML dialect, or multipart replacement streams). Anything that
+ * is not a clean `type/subtype` token is treated as active too.
+ */
+export function isActiveUserContentType(contentType: string): boolean {
+  const essence = mediaTypeEssence(contentType);
+  if (!/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/.test(essence)) return true;
+  return (
+    ACTIVE_DOCUMENT_TYPES.has(essence) ||
+    essence.endsWith("+xml") ||
+    essence.startsWith("multipart/")
+  );
+}
+
+const DISPOSITION_FILENAME_MAX_CHARS = 200;
+
+/** RFC 8187 `attr-char` percent-encoding (stricter than `encodeURIComponent`). */
+function encodeExtendedParameterValue(value: string): string {
+  return encodeURIComponent(value).replace(
+    /['()*]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+/**
+ * RFC 6266 filename parameters: an ASCII-only quoted `filename` that cannot
+ * break out of the header, plus an RFC 8187 `filename*` carrying the original
+ * name (for example non-Latin names) whenever the ASCII form had to change it.
+ */
+function dispositionFilenameParameters(filename: string): string {
+  const cleaned = Array.from(
+    filename
+      .replace(/[\u0000-\u001f\u007f/\\]+/g, "_")
+      // Lone surrogates cannot be percent-encoded as UTF-8.
+      .replace(/[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/g, "_")
+      .trim(),
+  )
+    .slice(0, DISPOSITION_FILENAME_MAX_CHARS)
+    .join("");
+  const ascii =
+    cleaned
+      .replace(/[^A-Za-z0-9._ -]+/g, "_")
+      .replace(/\s+/g, " ")
+      .trim()
+      .slice(0, DISPOSITION_FILENAME_MAX_CHARS) || "download";
+  if (!cleaned || ascii === cleaned) return `filename="${ascii}"`;
+  return `filename="${ascii}"; filename*=UTF-8''${encodeExtendedParameterValue(cleaned)}`;
+}
+
+/** `Content-Disposition: attachment` for active markup; inline types are unchanged. */
+export function userContentDispositionHeaders(
+  contentType: string,
+  filename?: string | null,
+): { "Content-Disposition": string } | Record<string, never> {
+  if (!isActiveUserContentType(contentType)) return {};
+  return {
+    "Content-Disposition": filename
+      ? `attachment; ${dispositionFilenameParameters(filename)}`
+      : "attachment",
+  };
+}
+
+/**
+ * Signed object-storage GET options for one stored object: active markup gets
+ * a signed `attachment` response override, so a browser that opens the URL
+ * downloads the bytes instead of rendering them with their stored type. The
+ * storage endpoint is not always a separate site (local development serves it
+ * from loopback, and a preview may route the bucket path on the app origin),
+ * so a signed URL follows the same rule as the API routes. Spread into
+ * `createGetUrl`; inline types add nothing.
+ */
+export function userContentSignedGetUrlOptions(
+  contentType: string,
+  filename?: string | null,
+): { responseContentDisposition: string } | Record<string, never> {
+  const headers = userContentDispositionHeaders(contentType, filename);
+  return "Content-Disposition" in headers
+    ? { responseContentDisposition: headers["Content-Disposition"] }
+    : {};
+}
+
+/** True for audio and video types the browser plays in a synthesized media document. */
+export function isPlayableMediaUserContentType(contentType: string): boolean {
+  const essence = mediaTypeEssence(contentType);
+  return !isActiveUserContentType(essence) && /^(audio|video)\//.test(essence);
+}
+
+/** Sandbox policy for one response; only playable media keeps its origin. */
+export function userContentSecurityPolicy(contentType: string): string {
+  return isPlayableMediaUserContentType(contentType)
+    ? USER_MEDIA_CONTENT_SECURITY_POLICY
+    : USER_CONTENT_SECURITY_POLICY;
+}
+
+/** Full header set for one user-content response with the given content type. */
+export function userContentResponseHeaders(
+  contentType: string,
+  filename?: string | null,
+): Record<string, string> {
+  return {
+    ...USER_CONTENT_SECURITY_HEADERS,
+    "Content-Security-Policy": userContentSecurityPolicy(contentType),
+    ...userContentDispositionHeaders(contentType, filename),
+  };
+}

package/src/http/websocket-upgrade-dispatch.ts

@@ -0,0 +1,29 @@
+import { localBrowserBoundaryResponse, type LocalBrowserBoundary } from "./local-browser-boundary";
+
+export type ApiWebSocketUpgradeRoute<Server> = {
+  handles(request: Request): boolean;
+  upgrade(request: Request, server: Server): Response | undefined;
+};
+
+export type ApiWebSocketUpgradeDispatch =
+  | { handled: false }
+  | { handled: true; response: Response | undefined };
+
+/**
+ * WebSocket upgrades bypass the Hono app, so the local-mode browser boundary
+ * (./local-browser-boundary.ts) is applied here before a transport upgrades.
+ * Returns `{ handled: false }` when no transport claims the request, so the
+ * caller dispatches it to the app, where the boundary runs as middleware.
+ */
+export function dispatchApiWebSocketUpgrade<Server>(
+  request: Request,
+  server: Server,
+  routes: ReadonlyArray<ApiWebSocketUpgradeRoute<Server>>,
+  localBrowserBoundary: LocalBrowserBoundary | null,
+): ApiWebSocketUpgradeDispatch {
+  const route = routes.find((candidate) => candidate.handles(request));
+  if (!route) return { handled: false };
+  const rejection = localBrowserBoundary?.rejection(request);
+  if (rejection) return { handled: true, response: localBrowserBoundaryResponse(rejection) };
+  return { handled: true, response: route.upgrade(request, server) };
+}

package/src/index.ts

@@ -43,7 +43,7 @@ import {
 } from "@temporalio/client";
 import type { ScheduleOptions, ScheduleSpec, ScheduleUpdateOptions } from "@temporalio/client";
 import { createAppComposition, type DocumentIndexClient, type SessionWorkflowClient } from "./app";
-import { observabilityEventLogger } from "./observability";
+import { observabilityEventBusOptions } from "./observability";
 import { startAuthCalloutResponder } from "./sandbox/auth-callout";
 import { startHelloIngestion, startMetricsIngestion } from "./sandbox/metrics-ingestion";
 import { startSlackInteractionPump } from "./integrations/slack-interactions";
@@ -57,6 +57,9 @@ import {
 import type { ApiWebSocketConnection } from "./api-websocket";
 import { InteractionFrameProxyTransport } from "./interaction-frame-proxy";
 import { apiRequestBindingsForTransportPeer } from "./http/request-source";
+import { startApiMetricsListener } from "./http/metrics-listener";
+import { createLocalBrowserBoundary } from "./http/local-browser-boundary";
+import { dispatchApiWebSocketUpgrade } from "./http/websocket-upgrade-dispatch";
 import {
   createStandaloneEditableArtifactApplication,
   type StandaloneEditableArtifactApplication,
@@ -382,7 +385,7 @@ export async function startApi(
           controlPlaneAuth
             ? { user: controlPlaneAuth.user, pass: controlPlaneAuth.password }
             : undefined,
-          { logger: observabilityEventLogger(observability) },
+          observabilityEventBusOptions(observability),
         ),
       {
         ...retryOptions,
@@ -449,17 +452,25 @@ export async function startApi(
   const interactionFrameProxies = new InteractionFrameProxyTransport(
     resolveFirstPartyDelegationSecret(settings),
   );
+  // WebSocket upgrades bypass the Hono app, so the local-mode browser boundary
+  // (http/local-browser-boundary.ts) is applied to them in the dispatcher;
+  // every other request meets it in the Hono middleware.
+  const localBrowserBoundary = createLocalBrowserBoundary(settings, {
+    warn: (message, attributes) => observability.warn(message, attributes),
+  });
+  const webSocketUpgrades = [interactionFrameProxies, artifactWebSockets];
   const server = Bun.serve<ApiWebSocketConnection>({
     hostname: settings.apiHost,
     port: settings.apiPort,
     idleTimeout: 255,
     fetch: (request, bunServer) => {
-      if (interactionFrameProxies.handles(request)) {
-        return interactionFrameProxies.upgrade(request, bunServer);
-      }
-      if (artifactWebSockets.handles(request)) {
-        return artifactWebSockets.upgrade(request, bunServer);
-      }
+      const upgrade = dispatchApiWebSocketUpgrade(
+        request,
+        bunServer,
+        webSocketUpgrades,
+        localBrowserBoundary,
+      );
+      if (upgrade.handled) return upgrade.response;
       return app.fetch(
         request,
         apiRequestBindingsForTransportPeer(bunServer.requestIP(request)?.address),
@@ -474,6 +485,7 @@ export async function startApi(
       close: (socket) => socket.data.transportClosed(),
     },
   });
+  const metricsServer = startApiMetricsListener(settings, observability);
   const stopSlackInteractionPump = settings.slackSigningSecret
     ? startSlackInteractionPump(routeDeps)
     : undefined;
@@ -540,11 +552,13 @@ export async function startApi(
   observability.info("OpenGeni API listening", {
     host: settings.apiHost,
     port: settings.apiPort,
+    ...(metricsServer ? { metricsPort: settings.apiMetricsPort } : {}),
   });
   return {
     server,
     close: async () => {
       server.stop(true);
+      metricsServer?.stop(true);
       stopSlackInteractionPump?.();
       await stopMemorySlackPublicationPump();
       stopMetricsIngestion?.();

package/src/integrations/atlassian.ts

@@ -92,6 +92,7 @@ import {
 } from "../connection-ownership";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
 } from "./oauth-client";
@@ -246,7 +247,7 @@ export async function completeAtlassianOAuthCallback(
       expiresAt: new Date(state.iat * 1000 + oauthStateTtlMs),
       now: new Date(),
     });
-    if (!consumed) throw new AtlassianCallbackError("state_reused");
+    if (!consumed) throw new AtlassianCallbackError("state_replayed");
     if (operation && (input.error || !input.code)) {
       await finishConnectOperation(deps.db, state, {
         ...operation,
@@ -428,12 +429,15 @@ export async function completeAtlassianOAuthCallback(
     };
   } catch (error) {
     if (exactReturnUrl) return { redirectTo: exactReturnUrl, exactReturn: true };
+    // Reading the state is the first step, so no state means the link itself
+    // was unusable: say whether it expired rather than blame configuration.
+    const failure = state ? null : oauthStateFailureReturn(deps.settings, input.state);
     return {
       redirectTo: returnUrl(
         returnBaseUrl,
-        state?.returnPath ?? "/integrations",
+        state?.returnPath ?? failure!.returnPath,
         "error",
-        errorReason(error),
+        failure?.reason ?? errorReason(error),
       ),
     };
   }

package/src/integrations/fiken.ts

@@ -46,8 +46,10 @@ import { readResponseJsonBounded, type FetchLike } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
+  workspaceIntegrationsPath,
 } from "./oauth-client";
 
 const FIKEN_API_BASE = "https://api.fiken.no/api/v2";
@@ -1123,7 +1125,7 @@ export async function startFikenOAuth(
     workspaceId: input.workspaceId,
     subjectId: input.subjectId,
     returnPath: safeReturnPath(
-      input.payload.returnPath ?? `/workspaces/${input.workspaceId}/capabilities`,
+      input.payload.returnPath ?? workspaceIntegrationsPath(input.workspaceId),
     ),
     ...(input.connectAttemptId ? { connectAttemptId: input.connectAttemptId } : {}),
     ...(input.externalContinuation
@@ -1363,12 +1365,16 @@ export async function completeFikenOAuthCallback(
     };
   } catch (error) {
     if (exactReturnUrl) return { redirectTo: exactReturnUrl, exactReturn: true };
+    // Reading the state is the first step, so no state means the link itself
+    // was unusable: say whether it expired instead of suggesting a token.
+    const failure = state ? null : oauthStateFailureReturn(deps.settings, input.state);
     return {
       redirectTo: fikenReturnUrl(
         returnBaseUrl,
-        state?.returnPath ?? "/integrations",
+        state?.returnPath ?? failure!.returnPath,
         "error",
-        error instanceof FikenOAuthCallbackError ? error.reason : "callback_failed",
+        failure?.reason ??
+          (error instanceof FikenOAuthCallbackError ? error.reason : "callback_failed"),
       ),
     };
   }

package/src/integrations/github-app-connect.ts

@@ -27,6 +27,7 @@ import {
   isConsistentGitHubBindingCandidates,
   isConsistentGitHubBindingProof,
 } from "./github-installation-proof";
+import { githubConnectFailureHtml } from "../routes/github-browser-pages";
 
 const stateSchema = z.object({
   kind: z.literal("github_app_connect"),
@@ -418,8 +419,17 @@ export async function completeGitHubAppConnect(
     }
   } catch {
     // Preserve unknown outcomes; never replay provider authorization to recover.
-    if (!destination)
-      return Response.json({ error: "Connection callback is invalid or expired" }, { status: 400 });
+    // This is browser navigation (usually the Connect popup), so explain the
+    // stale or reused link on a page instead of returning a JSON body.
+    if (!destination) {
+      const home =
+        deps.settings.webBaseUrl ??
+        integrationBaseUrl(deps.settings.publicBaseUrl, input.requestUrl);
+      return new Response(githubConnectFailureHtml("expired", `${home.replace(/\/+$/u, "")}/`), {
+        status: 400,
+        headers: { "content-type": "text/html; charset=UTF-8" },
+      });
+    }
   }
   return new Response(null, { status: 302, headers: { Location: destination! } });
 }

package/src/integrations/google-drive.ts

@@ -116,6 +116,7 @@ import {
 } from "../connection-ownership";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
 } from "./oauth-client";
@@ -400,7 +401,7 @@ export async function completeGoogleDriveOAuthCallback(
       now: new Date(),
     });
     if (!consumed) {
-      throw new HTTPException(400, { message: "Google Drive OAuth state has already been used" });
+      throw new GoogleDriveCallbackError("state_replayed");
     }
     if (operation && (input.error || !input.code)) {
       await finishConnectOperation(deps.db, state, {
@@ -629,12 +630,15 @@ export async function completeGoogleDriveOAuthCallback(
     };
   } catch (error) {
     if (exactReturnUrl) return { redirectTo: exactReturnUrl, exactReturn: true };
+    // Reading the state is the first step, so no state means the link itself
+    // was unusable: say whether it expired rather than blame configuration.
+    const failure = state ? null : oauthStateFailureReturn(deps.settings, input.state);
     return {
       redirectTo: googleDriveReturnUrl(
         returnBaseUrl,
-        state?.returnPath ?? "/integrations",
+        state?.returnPath ?? failure!.returnPath,
         "error",
-        googleDriveErrorReason(error),
+        failure?.reason ?? googleDriveErrorReason(error),
       ),
     };
   }

package/src/integrations/oauth-client.ts

@@ -38,7 +38,7 @@ import {
   withDatabaseStatementTimeout,
   type Database,
 } from "@opengeni/db";
-import { createSignedState, readSignedState } from "@opengeni/github";
+import { createSignedState, inspectSignedState, readSignedState } from "@opengeni/github";
 import {
   DestinationPolicyError,
   McpOAuthDiscoveryError,
@@ -86,6 +86,64 @@ import {
 import { canonicalProviderDomain } from "./provider-domain";
 
 export const oauthStateTtlMs = 10 * 60 * 1000;
+
+/**
+ * Workspace-free landing for a callback whose state names no trustworthy
+ * workspace. The web app resolves it to the viewer's current workspace
+ * integrations page and keeps the callback outcome parameters.
+ */
+export const INTEGRATIONS_FALLBACK_PATH = "/integrations";
+
+const WORKSPACE_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+/** The web integrations page for one workspace (the Plugins surface). */
+export function workspaceIntegrationsPath(workspaceId: string): string {
+  return `/workspaces/${encodeURIComponent(workspaceId)}/plugins`;
+}
+
+/**
+ * The integrations page for a workspace id read from untrusted input (a URL
+ * parameter or an unverified-age state), or null unless it is a workspace UUID.
+ * A link target only: it grants nothing.
+ */
+export function workspaceIntegrationsPathForUntrusted(candidate: unknown): string | null {
+  return typeof candidate === "string" && WORKSPACE_ID_PATTERN.test(candidate)
+    ? workspaceIntegrationsPath(candidate)
+    : null;
+}
+
+/**
+ * Where a callback returns, and why, when its own signed state is unusable.
+ *
+ * A correctly signed state still names its workspace, even when it is too old
+ * or its flow rejected it, so the browser returns to that workspace's
+ * integrations page; an aged one is reported as expired. Anything unsigned,
+ * tampered, or signed with another secret returns to
+ * {@link INTEGRATIONS_FALLBACK_PATH}. Display routing only: nothing here
+ * authorizes, resumes, or replays the callback.
+ */
+export function oauthStateFailureReturn(
+  settings: Settings,
+  rawState: string | undefined,
+  nowMs = Date.now(),
+): { returnPath: string; reason: "state_expired" | "state_invalid" } {
+  let payload: ReturnType<typeof inspectSignedState> = null;
+  try {
+    payload = rawState
+      ? inspectSignedState(rawState, requireIntegrationsStateSecret(settings))
+      : null;
+  } catch {
+    payload = null;
+  }
+  return {
+    returnPath:
+      workspaceIntegrationsPathForUntrusted(payload?.workspaceId) ?? INTEGRATIONS_FALLBACK_PATH,
+    reason:
+      payload !== null && nowMs - payload.iat * 1000 > oauthStateTtlMs
+        ? "state_expired"
+        : "state_invalid",
+  };
+}
 export {
   OFFICIAL_GMAIL_MCP_SCOPES,
   OFFICIAL_GMAIL_MCP_URL,
@@ -469,7 +527,9 @@ async function startMcpOAuthWithinDeadline(
   // Catalog defaults are setup preferences; an explicit ownership always wins.
   const requestedOwnership: ConnectionOwnership =
     context.payload.ownership ?? defaultOwnershipFor(profile);
-  const returnPath = safeReturnPath(context.payload.returnPath ?? "/integrations");
+  const returnPath = safeReturnPath(
+    context.payload.returnPath ?? workspaceIntegrationsPath(context.workspaceId),
+  );
   const baseUrl = integrationBaseUrl(settings.publicBaseUrl, context.requestUrl);
   const redirectUri = `${baseUrl}/v1/integrations/oauth/callback`;
   const metadataUrl = `${baseUrl}/v1/integrations/oauth/client-metadata.json`;
@@ -686,6 +746,8 @@ export async function completeMcpOAuthCallback(
   input: {
     code?: string | undefined;
     state?: string | undefined;
+    /** The provider's `error` parameter, for example `access_denied` on Cancel. */
+    error?: string | undefined;
     requestUrl: string;
   },
 ): Promise<OAuthCallbackResult> {
@@ -704,6 +766,7 @@ async function completeMcpOAuthCallbackWithinDeadline(
   input: {
     code?: string | undefined;
     state?: string | undefined;
+    error?: string | undefined;
     requestUrl: string;
   },
   deadline: OAuthCallbackDeadline,
@@ -720,7 +783,7 @@ async function completeMcpOAuthCallbackWithinDeadline(
     );
     logOAuthCallbackFailure(observability, error, state);
     return {
-      redirectTo: callbackReturnPath("/integrations", "error", {
+      redirectTo: callbackReturnPath(INTEGRATIONS_FALLBACK_PATH, "error", {
         stage: error.stage,
         reason: error.reason,
       }),
@@ -776,7 +839,11 @@ async function completeMcpOAuthCallbackWithinDeadline(
         new HTTPException(422, { message: PERSONAL_CONNECTION_PRINCIPAL_MESSAGE }),
       );
     }
-    if (!input.code) {
+    if (input.error || !input.code) {
+      // The provider sends `error` (for example `access_denied` when the user
+      // clicks Cancel) instead of a code. Report that as a refusal, not as an
+      // expired attempt, and never echo the provider's own text.
+      const cancelled = input.error === "access_denied";
       if (connectOperation) {
         await finishConnectOperation(db, state, {
           ...connectOperation,
@@ -785,20 +852,23 @@ async function completeMcpOAuthCallbackWithinDeadline(
           commit: async (_tx, current) => ({
             ...current,
             revision: current.revision + 1,
-            state: "failed",
+            state: cancelled ? "cancelled" : "failed",
             nextAction: { type: "none" },
             error: {
-              code: "missing_code",
+              code: input.error ? "provider_denied" : "missing_code",
               message: "Authorization was not completed. Start a new connection attempt.",
               retryable: false,
             },
           }),
         });
       }
-      return callbackStateResult(state, "error", {
-        stage: "state_verify",
-        reason: "missing_code",
-      });
+      return callbackStateResult(
+        state,
+        "error",
+        input.error
+          ? { stage: "authorize", reason: cancelled ? "access_denied" : "provider_error" }
+          : { stage: "state_verify", reason: "missing_code" },
+      );
     }
     await withOrganizationIntegrationAcquisition(db, state, [integrationKey], async () => {});
     const consumed = await runCallbackDatabaseStage(
@@ -828,6 +898,17 @@ async function completeMcpOAuthCallbackWithinDeadline(
         ? error
         : new OAuthCallbackStageError("state_verify", "state_invalid", error);
     logOAuthCallbackFailure(observability, staged, state);
+    if (!state) {
+      // The state itself could not be resolved, so it carries no return path.
+      // An authentic but aged state still names its workspace and "expired".
+      const failure = oauthStateFailureReturn(settings, input.state);
+      return {
+        redirectTo: callbackReturnPath(failure.returnPath, "error", {
+          stage: staged.stage,
+          reason: staged.reason === "state_invalid" ? failure.reason : staged.reason,
+        }),
+      };
+    }
     return callbackStateResult(state, "error", {
       stage: staged.stage,
       reason: staged.reason,
@@ -1009,7 +1090,13 @@ function callbackStateResult(
 ): OAuthCallbackResult {
   if ((state?.externalContinuation || state?.connectAttemptId) && state.returnUrl)
     return { redirectTo: state.returnUrl, exactReturn: true };
-  return { redirectTo: callbackReturnPath(state?.returnPath ?? "/integrations", status, details) };
+  return {
+    redirectTo: callbackReturnPath(
+      state?.returnPath ?? INTEGRATIONS_FALLBACK_PATH,
+      status,
+      details,
+    ),
+  };
 }
 
 export function integrationBaseUrl(publicBaseUrl: string | undefined, requestUrl: string): string {
@@ -2432,7 +2519,7 @@ function callbackReturnPath(
   // Defense in depth: a `//host` pathname becomes a protocol-relative absolute
   // Location — an open redirect from the unauthenticated callback.
   if (url.pathname.startsWith("//")) {
-    const fallback = new URL("/integrations", "https://opengeni.local");
+    const fallback = new URL(INTEGRATIONS_FALLBACK_PATH, "https://opengeni.local");
     fallback.search = url.search;
     return `${fallback.pathname}${fallback.search}`;
   }