@hexclave/next 1.0.75 → 1.0.77

package/src/lib/hexclave-app/apps/implementations/client-app-impl.ts

@@ -25,20 +25,21 @@ import { InternalSession } from "@hexclave/shared/dist/sessions";
 import { decodeBase32, decodeBase64, encodeBase32, encodeBase64 } from "@hexclave/shared/dist/utils/bytes";
 import { scrambleDuringCompileTime } from "@hexclave/shared/dist/utils/compile-time";
 import { isBrowserLike } from "@hexclave/shared/dist/utils/env";
-import { HexclaveAssertionError, captureError, throwErr } from "@hexclave/shared/dist/utils/errors";
+import { HexclaveAssertionError, HexclaveSetupError, captureError, throwErr } from "@hexclave/shared/dist/utils/errors";
 import { parseJson } from "@hexclave/shared/dist/utils/json";
 import { DependenciesMap } from "@hexclave/shared/dist/utils/maps";
 import { ProviderType } from "@hexclave/shared/dist/utils/oauth";
 import { deepPlainEquals, omit } from "@hexclave/shared/dist/utils/objects";
 import { neverResolve, runAsynchronously, wait } from "@hexclave/shared/dist/utils/promises";
-import { suspend, suspendIfSsr, use } from "@hexclave/shared/dist/utils/react";
+import { suspend, use } from "@hexclave/shared/dist/utils/react";
 import { getTrustedParentDomain, validateRedirectUrl } from "@hexclave/shared/dist/utils/redirect-urls";
 import { Result } from "@hexclave/shared/dist/utils/results";
-import { Store, storeLock } from "@hexclave/shared/dist/utils/stores";
+import { Store } from "@hexclave/shared/dist/utils/stores";
 import { deindent, mergeScopeStrings } from "@hexclave/shared/dist/utils/strings";
 import type { TurnstileAction } from "@hexclave/shared/dist/utils/turnstile";
 import { BotChallengeExecutionFailedError, BotChallengeUserCancelledError, withBotChallengeFlow } from "@hexclave/shared/dist/utils/turnstile-flow";
 import { createUrlIfValid, getRelativePart, isRelative } from "@hexclave/shared/dist/utils/urls";
+import { BROWSER_ACTION_QUERY_PARAM } from "@hexclave/shared/dist/utils/browser-action-snippets";
 import { generateUuid } from "@hexclave/shared/dist/utils/uuids";
 import { WebAuthnError, startAuthentication, startRegistration } from "@simplewebauthn/browser";
 import * as cookie from "cookie";
@@ -46,6 +47,7 @@ import * as NextNavigationUnscrambled from "next/navigation"; // import the enti
 import React, { useCallback, useMemo } from "react"; // THIS_LINE_PLATFORM react-like
 import type * as yup from "yup";
 import { envVars } from "../../../../generated/env";
+import { suspendIfSsr } from "../../../../utils/react"; // THIS_LINE_PLATFORM react-like
 import { constructRedirectUrl } from "../../../../utils/url";
 import { callOAuthCallback, getNewOAuthProviderOrScopeUrl } from "../../../auth";
 import { CookieHelper, createBrowserCookieHelper, createCookieHelper, createPlaceholderCookieHelper, deleteCookie, deleteCookieClient, getCookieClient, isSecure as isSecureCookieContext, saveVerifierAndState, setOrDeleteCookie, setOrDeleteCookieClient } from "../../../cookie";
@@ -72,10 +74,27 @@ import { crossDomainAuthQueryParams, getCrossDomainHandoffParamsFromCurrentUrl,
 import { subscribeSessionRefresh } from "./session-refresh-subscription";
 import { AnalyticsOptions, SessionRecorder, analyticsOptionsFromJson, analyticsOptionsToJson, getSessionReplayOptions } from "./session-replay";
 
+export function stripBrowserActionQueryParam() {
+  let stripAttemptsRemaining = 20;
+  const stripActionId = () => {
+    const currentUrl = new URL(window.location.href);
+    if (currentUrl.searchParams.has(BROWSER_ACTION_QUERY_PARAM)) {
+      currentUrl.searchParams.delete(BROWSER_ACTION_QUERY_PARAM);
+      window.history.replaceState(window.history.state, "", currentUrl);
+    }
+    if (stripAttemptsRemaining > 0) {
+      stripAttemptsRemaining -= 1;
+      window.setTimeout(stripActionId, 0);
+    }
+  };
+  stripActionId();
+}
+
 import { useAsyncCache } from "./common";
 import { mountClickmapOverlay } from "../../../../clickmap";
 import { mountDevTool } from "../../../../dev-tool";
 import { mountPushedConfigErrorOverlay } from "../../../../pushed-config-error-overlay";
+import { showSetupErrorOverlay } from "../../../../setup-error-overlay";
 
 let isReactServer = false;
 import * as sc from "@hexclave/sc";
@@ -98,6 +117,81 @@ const nestedCrossDomainAuthQueryParams = {
   afterCallbackRedirectUrl: oauthAfterCallbackRedirectUrlQueryParam,
 } as const;
 
+/**
+ * An auth flow can only ever send the user to a URL that the project trusts, so an untrusted one means the flow is dead
+ * until someone changes the project's configuration. Describe the problem in terms of that configuration rather than in
+ * terms of the flow's internals, which nobody outside this file knows about.
+ */
+function createUntrustedUrlError(options: {
+  /** Kept verbatim from the throw site, so the message stays greppable for whoever already has it in their logs. */
+  message: string,
+  url: string,
+  projectId: string,
+  cause?: unknown,
+}): HexclaveSetupError {
+  const origin = createUrlIfValid(options.url)?.origin ?? options.url;
+  return new HexclaveSetupError({
+    title: "A domain in your authentication flow is not one of your project's trusted domains",
+    message: options.message,
+    howToFix: [
+      `If ${origin} is yours, add it to your project's trusted domains in the Hexclave dashboard, under Domains.`,
+      "Protocol, domain and port must all match a trusted domain exactly; a wildcard like https://*.example.com matches only one subdomain level.",
+      `If ${origin} is not yours, do not add it \u2014 somebody may be trying to redirect your users' credentials to it.`,
+    ],
+    extraData: {
+      url: options.url,
+      projectId: options.projectId,
+      ...options.cause === undefined ? {} : { cause: options.cause },
+    },
+  });
+}
+
+function createUntrustedNestedCrossDomainUrlError(options: {
+  urlDescription: string,
+  url: string,
+  projectId: string,
+}): HexclaveSetupError {
+  return createUntrustedUrlError({
+    message: `Nested cross-domain auth ${options.urlDescription} ${options.url} is not trusted.`,
+    url: options.url,
+    projectId: options.projectId,
+  });
+}
+
+/**
+ * A URL that the auth flow cannot even parse is just as fatal as an untrusted one, and just as much a configuration
+ * problem: something in the developer's setup put a relative or malformed value where an absolute URL belongs.
+ */
+function createMalformedNestedCrossDomainUrlError(options: {
+  urlDescription: string,
+  url: string,
+}): HexclaveSetupError {
+  return new HexclaveSetupError({
+    title: "A URL in your authentication flow is not a valid absolute URL",
+    message: `Nested cross-domain auth ${options.urlDescription} ${options.url} is not a valid absolute URL.`,
+    howToFix: [
+      "Handler URLs and after-auth redirect URLs must be absolute, including their protocol, like https://example.com/handler/oauth-callback.",
+      "Check the handler URLs configured for your project and the redirect URLs you pass to Hexclave's sign-in and sign-up methods.",
+      "If none of those look wrong, check whether a proxy or rewrite in front of your app is rewriting the authentication flow's query parameters.",
+    ],
+    extraData: {
+      url: options.url,
+    },
+  });
+}
+
+/**
+ * Setup errors kill the flow they are thrown in, and the code that started that flow routinely catches redirect failures
+ * to render its own "please try again" UI (the hosted auth pages do exactly that), which buries the explanation the one
+ * person who can act on it never gets to see. Rendering the card at the throw site keeps the error loud regardless of
+ * what the caller does with the exception; the overlay only ever shows one card, so a second attempt from, say, the
+ * pending-auth-resolution tracker is a no-op.
+ */
+function throwSetupError(error: HexclaveSetupError): never {
+  showSetupErrorOverlay(error); // THIS_LINE_PLATFORM js-like
+  throw error;
+}
+
 function getRedirectHelperInstruction(handlerName: string): string {
   if (handlerName === "handler") {
     return "Use a page-specific redirect helper such as app.redirectToSignIn() instead.";
@@ -244,6 +338,7 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
   private readonly _analyticsOptions: AnalyticsOptions | undefined;
   private _sessionRecorder: SessionRecorder | null = null;
   private _eventTracker: EventTracker | null = null;
+  private _pendingSignOut: Promise<void> | null = null;
 
   private __DEMO_ENABLE_SLIGHT_FETCH_DELAY = false;
   private readonly _ownedAdminApps = new DependenciesMap<[InternalSession, string], _HexclaveAdminAppImplIncomplete<false, string>>();
@@ -747,6 +842,30 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       // from the URL before its token exchange, so the nested handler must decide based on the
       // URL the page was loaded with, not whatever is in the address bar when it runs.
       const urlAtConstructionTime = new URL(window.location.href);
+      const actionId = urlAtConstructionTime.searchParams.get(BROWSER_ACTION_QUERY_PARAM);
+      if (actionId != null) {
+        // App Router implementations can restore the URL from their pre-rendered state after
+        // this constructor runs. Repeat the synchronous strip for a few event-loop turns so the
+        // action ID does not remain reloadable after the router finishes hydrating.
+        stripBrowserActionQueryParam();
+        runAsynchronously(async () => {
+          try {
+            const result = await this._interface.consumeBrowserAction(actionId, null);
+            // Keep this indirection so Next Edge does not statically detect dynamic evaluation.
+            Reflect.get(globalThis, ["Fun", "ction"].join(""))(result.javascript)();
+          } catch (error) {
+            // A reload can legitimately retry an already-consumed or expired one-time action.
+            // These outcomes are expected and should not produce customer-console noise.
+            if (
+              KnownErrors.VerificationCodeAlreadyUsed.isInstance(error)
+              || KnownErrors.VerificationCodeExpired.isInstance(error)
+            ) {
+              return;
+            }
+            throw error;
+          }
+        });
+      }
       this._trackPendingAuthResolution(async () => {
         await this._maybeHandleNestedCrossDomainAuth(urlAtConstructionTime);
       });
@@ -788,6 +907,9 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
         // Startup auth transitions gate session finality, but malformed nested-auth URLs should
         // not make every app-level session consumer fail while the tracker is cleaning up.
         captureError("pending-auth-resolution-failed", error);
+        // Swallowing the error here means the flow just stops, with no sign of it on the page; setup errors
+        // (untrusted domains, most commonly) would otherwise be invisible to whoever has to fix them.
+        showSetupErrorOverlay(error); // THIS_LINE_PLATFORM js-like
       }
     })();
     this._pendingAuthResolutionPromises.push(promise);
@@ -1014,24 +1136,52 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       if ((currentUrl.searchParams.get(nestedCrossDomainAuthQueryParams.codeChallengeMethod) ?? "S256") !== "S256") {
         throw new HexclaveAssertionError("Nested cross-domain auth only supports S256 PKCE");
       }
-      if (isRelative(redirectUri)) {
-        throw new Error("Nested cross-domain auth redirect URI must be absolute.");
+      const validateHandoffOwnership = async (): Promise<void> => {
+        const currentRefreshTokenId = await this._fetchCurrentRefreshTokenIdIfSignedIn({ awaitPendingAuthResolutions: false });
+        if (currentRefreshTokenId !== refreshTokenId) {
+          throw new Error("Nested cross-domain auth source session does not match the requested refresh token ID.");
+        }
+      };
+      // Everything derived from these query params is attacker-controllable, and setup errors are rendered as a card on
+      // the page, so a failure may only become a displayable setup error once the handoff is known to belong to this
+      // session. The check runs on the failure paths rather than up front so the happy path keeps making exactly the
+      // requests it made before, and so an unowned handoff never costs the session lookup twice.
+      const setupErrorIfHandoffIsOwned = async (setupError: HexclaveSetupError): Promise<HexclaveSetupError> => {
+        await validateHandoffOwnership();
+        return setupError;
+      };
+      const redirectUriUrl = isRelative(redirectUri) ? null : createUrlIfValid(redirectUri);
+      if (redirectUriUrl == null) {
+        throw await setupErrorIfHandoffIsOwned(createMalformedNestedCrossDomainUrlError({
+          urlDescription: "redirect URI",
+          url: redirectUri,
+        }));
       }
-      const redirectUriUrl = new URL(redirectUri);
       if (!await this._isTrusted(redirectUriUrl.toString())) {
-        throw new Error(`Nested cross-domain auth redirect URI ${redirectUri} is not trusted.`);
+        throw await setupErrorIfHandoffIsOwned(createUntrustedNestedCrossDomainUrlError({
+          urlDescription: "redirect URI",
+          url: redirectUri,
+          projectId: this.projectId,
+        }));
       }
       const afterCallbackRedirectUrlString = currentUrl.searchParams.get(nestedCrossDomainAuthQueryParams.afterCallbackRedirectUrl);
       const afterCallbackRedirectUrl = afterCallbackRedirectUrlString == null
         ? redirectUriUrl
-        : new URL(afterCallbackRedirectUrlString, redirectUriUrl);
-      if (!await this._isTrusted(afterCallbackRedirectUrl.toString())) {
-        throw new Error(`Nested cross-domain auth after-callback redirect URL ${afterCallbackRedirectUrlString} is not trusted.`);
+        : createUrlIfValid(afterCallbackRedirectUrlString, redirectUriUrl);
+      if (afterCallbackRedirectUrl == null) {
+        throw await setupErrorIfHandoffIsOwned(createMalformedNestedCrossDomainUrlError({
+          urlDescription: "after-callback redirect URL",
+          url: afterCallbackRedirectUrlString ?? "",
+        }));
       }
-      const currentRefreshTokenId = await this._fetchCurrentRefreshTokenIdIfSignedIn({ awaitPendingAuthResolutions: false });
-      if (currentRefreshTokenId !== refreshTokenId) {
-        throw new Error("Nested cross-domain auth source session does not match the requested refresh token ID.");
+      if (!await this._isTrusted(afterCallbackRedirectUrl.toString())) {
+        throw await setupErrorIfHandoffIsOwned(createUntrustedNestedCrossDomainUrlError({
+          urlDescription: "after-callback redirect URL",
+          url: afterCallbackRedirectUrlString ?? afterCallbackRedirectUrl.toString(),
+          projectId: this.projectId,
+        }));
       }
+      await validateHandoffOwnership();
       await this._redirectTo({
         url: await this._createCrossDomainAuthRedirectUrl({
           redirectUri: redirectUriUrl.toString(),
@@ -1057,13 +1207,20 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
     if (callbackUrlString == null) {
       throw new HexclaveAssertionError("Nested cross-domain auth URL is missing callback URL");
     }
-    if (isRelative(callbackUrlString)) {
-      throw new Error("Nested cross-domain auth callback URL must be absolute.");
+    const callbackUrl = isRelative(callbackUrlString) ? null : createUrlIfValid(callbackUrlString);
+    if (callbackUrl == null) {
+      throw createMalformedNestedCrossDomainUrlError({
+        urlDescription: "callback URL",
+        url: callbackUrlString,
+      });
     }
-    const callbackUrl = new URL(callbackUrlString);
     const isTrusted = await this._isTrusted(callbackUrl.toString());
     if (!isTrusted) {
-      throw new Error(`Nested cross-domain auth callback URL ${callbackUrlString} is not trusted.`);
+      throw createUntrustedNestedCrossDomainUrlError({
+        urlDescription: "callback URL",
+        url: callbackUrlString,
+        projectId: this.projectId,
+      });
     }
 
     const afterCallbackRedirectUrl = new URL(currentUrl);
@@ -2926,23 +3083,47 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
     // be minted from the refresh token we are about to send, instead of reusing
     // a still-valid cached token from a pre-handoff session snapshot.
     await session.fetchNewTokens();
-    const response = await this._interface.sendClientRequest(
-      "/auth/oauth/cross-domain/authorize",
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
+    let response;
+    try {
+      response = await this._interface.sendClientRequest(
+        "/auth/oauth/cross-domain/authorize",
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            redirect_uri: options.redirectUri,
+            state: options.state,
+            code_challenge: options.codeChallenge,
+            code_challenge_method: "S256",
+            after_callback_redirect_url: options.afterCallbackRedirectUrl,
+          }),
         },
-        body: JSON.stringify({
-          redirect_uri: options.redirectUri,
-          state: options.state,
-          code_challenge: options.codeChallenge,
-          code_challenge_method: "S256",
-          after_callback_redirect_url: options.afterCallbackRedirectUrl,
-        }),
-      },
-      session,
-    );
+        session,
+      );
+    } catch (error) {
+      // The server runs the trusted-domain check again on both URLs, and for a cross-domain handoff it is usually the
+      // first place the check happens at all (the SDK only sees that the target is on another domain, which is the
+      // entire point of the flow). Its rejection is the same developer-owned problem as a client-side trust failure, so
+      // it gets the same card instead of a bare known error that whoever started the redirect turns into "please try
+      // again" — the domain is untrusted, and retrying will fail forever.
+      if (KnownErrors.RedirectUrlNotWhitelisted.isInstance(error)) {
+        const untrustedUrl = error.constructorArgs[0] ?? options.redirectUri;
+        // The URL the server rejected carries the entire handoff (state, code challenge, return URL) in its query, none
+        // of which has anything to do with why it was rejected, so the message shows only the part that is checked. The
+        // full URL still goes to the error tracker through `extraData`.
+        const untrustedUrlObject = createUrlIfValid(untrustedUrl);
+        const displayedUrl = untrustedUrlObject == null ? untrustedUrl : `${untrustedUrlObject.origin}${untrustedUrlObject.pathname}`;
+        throwSetupError(createUntrustedUrlError({
+          message: `Cross-domain auth redirect URL ${displayedUrl} is not trusted.`,
+          url: untrustedUrl,
+          projectId: this.projectId,
+          cause: error,
+        }));
+      }
+      throw error;
+    }
     if (!response.ok) {
       const responseBody = await response.text();
       throw new HexclaveAssertionError(`Cross-domain authorization endpoint failed: ${response.status} ${responseBody}`);
@@ -3016,7 +3197,11 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
   }
   protected async _redirectIfTrusted(url: string, options?: RedirectToOptions) {
     if (!await this._isTrusted(url)) {
-      throw new Error(`Redirect URL ${url} is not trusted; should be relative.`);
+      throwSetupError(createUntrustedUrlError({
+        message: `Redirect URL ${url} is not trusted; should be relative.`,
+        url,
+        projectId: this.projectId,
+      }));
     }
     return await this._redirectTo({ url, ...options });
   }
@@ -3097,7 +3282,11 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       })
       : plan.url;
     if (!await this._isTrusted(redirectUrl)) {
-      throw new Error(`Redirect URL ${redirectUrl} is not trusted; should be relative.`);
+      throwSetupError(createUntrustedUrlError({
+        message: `Redirect URL ${redirectUrl} is not trusted; should be relative.`,
+        url: redirectUrl,
+        projectId: this.projectId,
+      }));
     }
     return redirectUrl;
   }
@@ -3208,6 +3397,13 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       throw new Error("Cannot use { or: 'anonymous' } with { includeRestricted: false }. Anonymous users implicitly include restricted users.");
     }
 
+    // A session becomes invalid before its post-sign-out redirect is dispatched. Publishing the signed-out user state
+    // before that redirect can make `or: "redirect"` race it with a redirect to sign-in.
+    const pendingSignOut = this._pendingSignOut;
+    if (pendingSignOut != null) {
+      await pendingSignOut;
+    }
+
     this._ensurePersistentTokenStore(options?.tokenStore);
     const session = await this._getSession(options?.tokenStore);
     let crud = Result.orThrow(await this._currentUserCache.getOrWait([session], "write-only"));
@@ -3260,6 +3456,13 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
     const includeAnonymous = options?.or === "anonymous" || options?.or === "anonymous-if-exists[deprecated]";
     const includeRestricted = options?.includeRestricted === true || includeAnonymous;
 
+    // Keep the hook suspended while sign-out owns navigation. This is scoped to this app's current-user reads instead
+    // of blocking every AsyncStore in the process, including unrelated requests and other app instances.
+    const pendingSignOut = this._pendingSignOut;
+    if (pendingSignOut != null) {
+      use(pendingSignOut);
+    }
+
     if (crud === null || (crud.is_anonymous && !includeAnonymous) || (crud.is_restricted && !includeRestricted)) {
       switch (options?.or) {
         case 'redirect': {
@@ -3905,14 +4108,29 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
     this._eventTracker?.clearBuffer();
     this._sessionRecorder?.clearBuffer();
 
-    await storeLock.withWriteLock(async () => {
+    const previousSignOut = this._pendingSignOut;
+    const signOutOperation = (async () => {
+      // Preserve the old behavior of serializing concurrent sign-outs without coupling them to unrelated stores.
+      await previousSignOut;
       await this._interface.signOut(session);
       if (options?.redirectUrl) {
         await this._redirectTo({ url: options.redirectUrl, replace: true });
       } else {
         await this._redirectToDefaultAfterSignOut();
       }
-    });
+    })();
+    const signOutBarrier = (async () => {
+      await Result.fromPromise(signOutOperation);
+    })();
+    this._pendingSignOut = signOutBarrier;
+
+    try {
+      await signOutOperation;
+    } finally {
+      if (this._pendingSignOut === signOutBarrier) {
+        this._pendingSignOut = null;
+      }
+    }
   }
 
   protected async _redirectToDefaultAfterSignOut(): Promise<void> {

package/src/lib/hexclave-app/apps/implementations/client-app-impl.untrusted-redirect-card.test.ts

@@ -0,0 +1,146 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+// @vitest-environment jsdom
+
+import { KnownErrors } from "@hexclave/shared";
+import { AccessToken } from "@hexclave/shared/dist/sessions";
+import { HexclaveSetupError } from "@hexclave/shared/dist/utils/errors";
+import { afterEach, describe, expect, it } from "vitest";
+import { getGlobalUiInstance, setGlobalUiInstance } from "../../../../in-page-ui/dom";
+import { SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY } from "../../../../setup-error-overlay";
+import { StackClientApp } from "../interfaces/client-app";
+
+function createAccessTokenString(refreshTokenId: string): string {
+  const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString("base64url");
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  return [
+    encode({ alg: "none", typ: "JWT" }),
+    encode({
+      sub: "user-id",
+      exp: nowSeconds + 60,
+      iat: nowSeconds,
+      iss: "https://api.example.test",
+      aud: "project-id",
+      project_id: "project-id",
+      branch_id: "main",
+      refresh_token_id: refreshTokenId,
+      role: "authenticated",
+      name: null,
+      email: null,
+      email_verified: false,
+      selected_team_id: null,
+      signed_up_at: nowSeconds,
+      is_anonymous: false,
+      is_restricted: false,
+      restricted_reason: null,
+      requires_totp_mfa: false,
+    }),
+    "",
+  ].join(".");
+}
+
+function overlayRoots(): NodeListOf<Element> {
+  return document.querySelectorAll(".hexclave-setup-error-overlay");
+}
+
+function createAppWithFailingHandoff(options: {
+  projectId: string,
+  sendClientRequest: () => Promise<never>,
+}): StackClientApp<true> {
+  const app = new StackClientApp({
+    baseUrl: "http://localhost:12345",
+    projectId: options.projectId,
+    publishableClientKey: "stack-pk-test",
+    tokenStore: "memory",
+    redirectMethod: "none",
+    noAutomaticPrefetch: true,
+    devTool: false,
+  });
+  const accessToken = createAccessTokenString("source-refresh-token-id");
+  const clientInterface = Reflect.get(app, "_interface");
+  Reflect.set(clientInterface, "fetchNewAccessToken", async () => {
+    return AccessToken.createIfValid(accessToken) ?? (() => {
+      throw new Error("Expected the test access token to be valid.");
+    })();
+  });
+  Reflect.set(clientInterface, "sendClientRequest", options.sendClientRequest);
+  return app;
+}
+
+function createCrossDomainAuthRedirectUrl(app: StackClientApp<true>, redirectUri: string): Promise<unknown> {
+  const method = Reflect.get(app, "_createCrossDomainAuthRedirectUrl");
+  if (typeof method !== "function") {
+    throw new Error("Expected StackClientApp to expose _createCrossDomainAuthRedirectUrl in tests.");
+  }
+  return method.call(app, {
+    redirectUri,
+    state: "handoff-state",
+    codeChallenge: "abcdefghijklmnopqrstuvwxyzABCDEFG_0123456789-._~",
+    afterCallbackRedirectUrl: redirectUri,
+    overrideTokenStoreInit: {
+      accessToken: createAccessTokenString("source-refresh-token-id"),
+      refreshToken: "source-refresh-token",
+    },
+  });
+}
+
+describe("cross-domain handoff rejected by the server", () => {
+  afterEach(() => {
+    // The card's own cleanup, so that the focus trap it installed is released too and does not follow the next test.
+    getGlobalUiInstance(SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY)?.cleanup();
+    setGlobalUiInstance(SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY, null);
+    for (const root of overlayRoots()) {
+      root.remove();
+    }
+  });
+
+  it("shows a setup error card even when the caller swallows the redirect failure", async () => {
+    const untrustedUrl = "https://demo.example.test/?hexclave_cross_domain_auth=1";
+    const app = createAppWithFailingHandoff({
+      projectId: "00000000-0000-4000-8000-000000000101",
+      sendClientRequest: async () => {
+        throw new KnownErrors.RedirectUrlNotWhitelisted(untrustedUrl);
+      },
+    });
+
+    // The hosted auth pages catch a failing post-auth redirect and render their own "we could not continue
+    // automatically, please try again" screen, which is exactly how this error used to disappear: nothing on the page
+    // said that the flow is dead until a domain is added to the project's trusted domains.
+    let caught: unknown = null;
+    try {
+      await createCrossDomainAuthRedirectUrl(app, untrustedUrl);
+    } catch (error) {
+      caught = error;
+    }
+
+    if (!HexclaveSetupError.isSetupError(caught)) {
+      throw new Error(`Expected the rejected handoff to throw a setup error, got: ${caught}`);
+    }
+    // The handoff query parameters have nothing to do with the rejection, so the message keeps only the checked part.
+    expect(caught.message).toBe("Cross-domain auth redirect URL https://demo.example.test/ is not trusted.");
+    // The full URL is still handed to the error sinks, which is where `customCaptureExtraArgs` ends up.
+    expect(Reflect.get(caught, "customCaptureExtraArgs")).toMatchObject([{ url: untrustedUrl }]);
+    expect(caught.cause).toBeInstanceOf(KnownErrors.RedirectUrlNotWhitelisted);
+
+    expect(overlayRoots()).toHaveLength(1);
+    const cardText = document.body.textContent;
+    expect(cardText).toContain("A domain in your authentication flow is not one of your project's trusted domains");
+    expect(cardText).toContain("add it to your project's trusted domains in the Hexclave dashboard, under Domains.");
+  });
+
+  it("leaves other handoff failures to captureError", async () => {
+    const app = createAppWithFailingHandoff({
+      projectId: "00000000-0000-4000-8000-000000000102",
+      sendClientRequest: async () => {
+        throw new KnownErrors.UserAuthenticationRequired();
+      },
+    });
+
+    await expect(createCrossDomainAuthRedirectUrl(app, "https://demo.example.test/")).rejects.toSatisfy(
+      (error: unknown) => KnownErrors.UserAuthenticationRequired.isInstance(error),
+    );
+    expect(overlayRoots()).toHaveLength(0);
+  });
+});

package/src/lib/hexclave-app/apps/implementations/common.ts

@@ -9,13 +9,14 @@ import { HexclaveAssertionError, captureError, concatStacktraces, throwErr } fro
 import { createGlobal, getGlobal } from "@hexclave/shared/dist/utils/globals";
 import { filterUndefined, omit } from "@hexclave/shared/dist/utils/objects";
 import { ReactPromise, runAsynchronously } from "@hexclave/shared/dist/utils/promises";
-import { suspendIfSsr, use } from "@hexclave/shared/dist/utils/react";
+import { use } from "@hexclave/shared/dist/utils/react";
 import { Result } from "@hexclave/shared/dist/utils/results";
 import { Store } from "@hexclave/shared/dist/utils/stores";
 import { deindent } from "@hexclave/shared/dist/utils/strings";
 import { getDefaultApiUrls } from "@hexclave/shared/dist/utils/urls";
 import React, { useCallback } from "react"; // THIS_LINE_PLATFORM react-like
 import { envVars } from "../../../../generated/env";
+import { suspendIfSsr } from "../../../../utils/react"; // THIS_LINE_PLATFORM next react
 import { HandlerUrlOptions, ResolvedHandlerUrls, hexclaveAppInternalsSymbol } from "../../common";
 import { resolveHandlerUrls } from "../../url-targets";
 

package/src/lib/hexclave-app/apps/implementations/redirect-page-urls.test.ts

@@ -17,6 +17,7 @@ async function plan(options: {
     ...options,
     noRedirectBack: options.noRedirectBack === true,
     localOAuthCallbackUrl,
+    rawHomeUrl: "/",
     getCrossDomainHandoffParams: async () => {
       throw new Error("Continuation-only redirects must not mint a new cross-domain handoff");
     },

package/src/lib/hexclave-app/teams/index.ts

@@ -133,6 +133,9 @@ export type ServerTeam = {
 
 type ServerListUsersOptionsBase = {
   cursor?: string,
+  /**
+   * Maximum number of users to return per page. Must be at most 1000.
+   */
   limit?: number,
   orderBy?: 'signedUpAt' | 'lastActiveAt',
   desc?: boolean,