@hexclave/next 1.0.75 → 1.0.76

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

@@ -4,11 +4,16 @@
 //===========================================
 import { describe, expect, it, vi } from "vitest";
 import { AccessToken } from "@hexclave/shared/dist/sessions";
+import { HexclaveSetupError } from "@hexclave/shared/dist/utils/errors";
 import { Store } from "@hexclave/shared/dist/utils/stores";
 import { hexclaveAppInternalsSymbol } from "../../common";
 import { StackClientApp } from "../interfaces/client-app";
 import { planRedirectToHandler } from "./redirect-page-urls";
 
+// Every app in this file is constructed with `devTool: false`. The tests install a mock window and document, which makes
+// the SDK believe it is in a browser, and mounting the dev tool kicks off a background `getProject()` against a backend
+// that does not exist here. That fetch never settles, and because it runs inside the global store lock, it blocks every
+// later `withWriteLock` caller (`_signOut`, most visibly) for the rest of the test file.
 function createAccessTokenString(refreshTokenId: string): string {
   const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString("base64url");
   const nowSeconds = Math.floor(Date.now() / 1000);
@@ -54,6 +59,28 @@ function createMockDocument(): Document {
   } as any;
 }
 
+/**
+ * Installs a stand-in for `window` with only the parts the code under test touches. `globalThis.window` is typed as a
+ * full `Window`, which a hand-written stub can never be, so the assignment goes through `Reflect.set` — the stub's own
+ * shape stays checked, unlike with a cast on the object literal.
+ */
+function setMockWindow(mockWindow: {
+  location: { href: string, replace?: (url: string) => void },
+}): void {
+  Reflect.set(globalThis, "window", mockWindow);
+}
+
+/**
+ * Calls one of the app's `protected` methods, which are part of the flows under test but not of the public SDK surface.
+ */
+function callProtectedMethod(app: StackClientApp<true>, methodName: string, ...args: unknown[]): Promise<unknown> {
+  const method = Reflect.get(app, methodName);
+  if (typeof method !== "function") {
+    throw new Error(`Expected StackClientApp to have a ${methodName} method in tests.`);
+  }
+  return method.apply(app, args);
+}
+
 describe("StackClientApp cross-domain auth", () => {
   it("keeps noRedirectBack same-domain redirects free of redirect-back state", async () => {
     const redirectPlan = await planRedirectToHandler({
@@ -145,6 +172,7 @@ describe("StackClientApp cross-domain auth", () => {
           signIn: "/handler/sign-in",
         },
         noAutomaticPrefetch: true,
+        devTool: false,
       });
 
       const redirectUrl = await clientApp[hexclaveAppInternalsSymbol].getRedirectToHandlerUrl("signIn");
@@ -173,6 +201,7 @@ describe("StackClientApp cross-domain auth", () => {
       },
       redirectMethod: "none",
       noAutomaticPrefetch: true,
+      devTool: false,
     });
 
     const clientInterface = Reflect.get(clientApp, "_interface");
@@ -253,6 +282,7 @@ describe("StackClientApp cross-domain auth", () => {
         default: { type: "hosted" },
       },
       noAutomaticPrefetch: true,
+      devTool: false,
     });
     const outerState = "outer-cross-domain-state";
     const outerCodeChallenge = "abcdefghijklmnopqrstuvwxyzABCDEFG_0123456789-._~";
@@ -314,6 +344,7 @@ describe("StackClientApp cross-domain auth", () => {
         default: { type: "hosted" },
       },
       noAutomaticPrefetch: true,
+      devTool: false,
     });
     const tokenStore = Reflect.get(clientApp, "_memoryTokenStore");
     if (!(tokenStore instanceof Store)) {
@@ -392,6 +423,7 @@ describe("StackClientApp cross-domain auth", () => {
       tokenStore: "cookie",
       redirectMethod: "none",
       noAutomaticPrefetch: true,
+      devTool: false,
     });
     const clientInterface = Reflect.get(clientApp, "_interface");
     const originalFetchNewAccessToken = Reflect.get(clientInterface, "fetchNewAccessToken");
@@ -466,6 +498,7 @@ describe("StackClientApp cross-domain auth", () => {
       tokenStore: "memory",
       redirectMethod: "window",
       noAutomaticPrefetch: true,
+      devTool: false,
     });
 
     globalThis.document = createMockDocument();
@@ -499,6 +532,122 @@ describe("StackClientApp cross-domain auth", () => {
     }
   });
 
+  it("reports malformed nested cross-domain auth URLs as setup errors", async () => {
+    const projectId = "00000000-0000-4000-8000-000000000012";
+    const previousWindow = globalThis.window;
+    const previousDocument = globalThis.document;
+    globalThis.document = createMockDocument();
+
+    // A URL the flow cannot even parse is as fatal as an untrusted one, so it has to reach the developer the same way
+    // instead of escaping as a bare TypeError from `new URL()`, which the overlay only shows during development.
+    // The two branches of the handler want opposite session states: on the provider side (a.com) a query-derived failure
+    // only becomes a setup error when the handoff belongs to the current session, while the requesting side (b.com) only
+    // bounces when the current session is *not* the one that was asked for.
+    const malformedCases = [
+      {
+        description: "redirect URI",
+        currentRefreshTokenId: "source-refresh-token-id",
+        params: { redirect_uri: "not-a-url", state: "nested-state", code_challenge: "nested-code-challenge" },
+      },
+      {
+        description: "after-callback redirect URL",
+        currentRefreshTokenId: "source-refresh-token-id",
+        params: {
+          redirect_uri: "https://source.example.test/handler/account-settings",
+          state: "nested-state",
+          code_challenge: "nested-code-challenge",
+          after_callback_redirect_url: "http://[",
+        },
+      },
+      {
+        description: "callback URL",
+        currentRefreshTokenId: null,
+        params: { stack_nested_cross_domain_auth_callback_url: "http://[" },
+      },
+    ];
+
+    try {
+      for (const malformedCase of malformedCases) {
+        const currentUrl = new URL("https://target.example.test/nested-provider");
+        currentUrl.searchParams.set("stack_nested_cross_domain_auth_refresh_token_id", "source-refresh-token-id");
+        for (const [key, value] of Object.entries(malformedCase.params)) {
+          currentUrl.searchParams.set(key, value);
+        }
+        // Each app is constructed with the mock window uninstalled: the constructor's automatic side effects expect a
+        // real window, and a construction-time nested-auth URL would also schedule a second, unawaited run of the
+        // handler that keeps failing in the background and leaks into whichever test runs next.
+        globalThis.window = previousWindow;
+        const clientApp = new StackClientApp({
+          baseUrl: "http://localhost:12345",
+          projectId,
+          publishableClientKey: "stack-pk-test",
+          tokenStore: "memory",
+          redirectMethod: "window",
+          noAutomaticPrefetch: true,
+          devTool: false,
+        });
+        setMockWindow({ location: { href: currentUrl.toString() } });
+        Reflect.set(clientApp, "_fetchCurrentRefreshTokenIdIfSignedIn", async () => malformedCase.currentRefreshTokenId);
+        Reflect.set(clientApp, "_isTrusted", async () => true);
+
+        const nestedAuthPromise = callProtectedMethod(clientApp, "_maybeHandleNestedCrossDomainAuth");
+        await expect(nestedAuthPromise).rejects.toThrowError(new RegExp(`${malformedCase.description} .* is not a valid absolute URL`));
+        await expect(nestedAuthPromise).rejects.toSatisfy((error: unknown) => HexclaveSetupError.isSetupError(error));
+      }
+    } finally {
+      globalThis.window = previousWindow;
+      globalThis.document = previousDocument;
+    }
+  });
+
+  it("keeps nested cross-domain auth failures off the page for a handoff that does not own the session", async () => {
+    const projectId = "00000000-0000-4000-8000-000000000013";
+    const previousWindow = globalThis.window;
+    const previousDocument = globalThis.document;
+    globalThis.document = createMockDocument();
+
+    // Setup errors are shown in production, so a link anybody can craft must not be able to put a card on a healthy
+    // app's page: with a refresh-token ID that is not the current session's, every failure below stays an ordinary error
+    // that only captureError sees, even though the same URL from the right session would render a card.
+    const craftedRedirectUris = [
+      "https://evil.example.test/handler/account-settings", // untrusted
+      "not-a-url", // malformed
+    ];
+
+    try {
+      for (const craftedRedirectUri of craftedRedirectUris) {
+        const currentUrl = new URL("https://target.example.test/nested-provider");
+        currentUrl.searchParams.set("stack_nested_cross_domain_auth_refresh_token_id", "attacker-chosen-refresh-token-id");
+        currentUrl.searchParams.set("redirect_uri", craftedRedirectUri);
+        currentUrl.searchParams.set("state", "nested-state");
+        currentUrl.searchParams.set("code_challenge", "nested-code-challenge");
+
+        globalThis.window = previousWindow;
+        const clientApp = new StackClientApp({
+          baseUrl: "http://localhost:12345",
+          projectId,
+          publishableClientKey: "stack-pk-test",
+          tokenStore: "memory",
+          redirectMethod: "window",
+          noAutomaticPrefetch: true,
+          devTool: false,
+        });
+        setMockWindow({ location: { href: currentUrl.toString() } });
+        Reflect.set(clientApp, "_fetchCurrentRefreshTokenIdIfSignedIn", async () => "this-apps-refresh-token-id");
+        Reflect.set(clientApp, "_isTrusted", async () => false);
+
+        const nestedAuthPromise = callProtectedMethod(clientApp, "_maybeHandleNestedCrossDomainAuth");
+        await expect(nestedAuthPromise).rejects.toThrowError(/does not match the requested refresh token ID/);
+        await expect(nestedAuthPromise).rejects.toSatisfy(
+          (error: unknown) => !HexclaveSetupError.isSetupError(error),
+        );
+      }
+    } finally {
+      globalThis.window = previousWindow;
+      globalThis.document = previousDocument;
+    }
+  });
+
   it("passes the construction-time URL to the nested cross-domain auth handler", async () => {
     const projectId = "00000000-0000-4000-8000-000000000009";
     const previousWindow = globalThis.window;
@@ -529,6 +678,7 @@ describe("StackClientApp cross-domain auth", () => {
         tokenStore: "memory",
         redirectMethod: "window",
         noAutomaticPrefetch: true,
+        devTool: false,
       });
 
       // Simulate consumeOAuthCallbackQueryParams stripping code+state before microtasks run.
@@ -597,6 +747,7 @@ describe("StackClientApp cross-domain auth", () => {
           default: { type: "hosted" },
         },
         noAutomaticPrefetch: true,
+        devTool: false,
       });
 
       await new Promise((resolve) => setTimeout(resolve, 0));
@@ -629,6 +780,7 @@ describe("StackClientApp cross-domain auth", () => {
         signOut: { type: "hosted" },
       },
       noAutomaticPrefetch: true,
+      devTool: false,
     });
     const signOutSpy = vi.spyOn(clientApp, "signOut").mockRejectedValue(new Error("INTENTIONAL_TEST_ABORT"));
 
@@ -651,6 +803,7 @@ describe("StackClientApp cross-domain auth", () => {
         default: { type: "hosted" },
       },
       noAutomaticPrefetch: true,
+      devTool: false,
     });
 
     expect(() => clientApp.urls.signIn).toThrowError(/app\.urls\.signIn cannot be used when this app is configured to use hosted components.*Use app\.redirectToSignIn\(\) instead/s);
@@ -669,6 +822,7 @@ describe("StackClientApp cross-domain auth", () => {
         handler: "/custom-handler",
       },
       noAutomaticPrefetch: true,
+      devTool: false,
     });
 
     expect(clientApp.urls.signIn).toBe("/custom-handler/sign-in");
@@ -685,6 +839,7 @@ describe("StackClientApp cross-domain auth", () => {
         default: { type: "hosted" },
       },
       noAutomaticPrefetch: true,
+      devTool: false,
     });
     const currentHref = "https://demo.stack-auth.com/settings?tab=profile";
 
@@ -754,6 +909,7 @@ describe("StackClientApp cross-domain auth", () => {
         tokenStore: "memory",
         redirectMethod: "window",
         noAutomaticPrefetch: true,
+        devTool: false,
       });
 
       // Intermediate hops (MFA, magic link, OAuth round-trips, ...) dropped the query params.
@@ -822,6 +978,7 @@ describe("StackClientApp cross-domain auth", () => {
         tokenStore: "memory",
         redirectMethod: "window",
         noAutomaticPrefetch: true,
+        devTool: false,
       });
       const crossDomainAuthorizeRedirect = "https://demo.example.test/handler/oauth-callback?code=minted-code&state=mirror-handoff-state";
       const createCrossDomainAuthRedirectUrlSpy = vi
@@ -858,6 +1015,7 @@ describe("StackClientApp cross-domain auth", () => {
       tokenStore: "memory",
       redirectMethod: "none",
       noAutomaticPrefetch: true,
+      devTool: false,
     });
     const oldAccessToken = createAccessTokenString("old-refresh-token-id");
     const refreshedOldAccessToken = createAccessTokenString("refreshed-old-refresh-token-id");

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

@@ -25,7 +25,7 @@ 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";
@@ -76,6 +76,7 @@ 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 +99,67 @@ 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,
+}): 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,
+    },
+  });
+}
+
+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,
+    },
+  });
+}
+
 function getRedirectHelperInstruction(handlerName: string): string {
   if (handlerName === "handler") {
     return "Use a page-specific redirect helper such as app.redirectToSignIn() instead.";
@@ -788,6 +850,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 +1079,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 +1150,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);
@@ -3016,7 +3116,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.`);
+      throw createUntrustedUrlError({
+        message: `Redirect URL ${url} is not trusted; should be relative.`,
+        url,
+        projectId: this.projectId,
+      });
     }
     return await this._redirectTo({ url, ...options });
   }
@@ -3097,7 +3201,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.`);
+      throw createUntrustedUrlError({
+        message: `Redirect URL ${redirectUrl} is not trusted; should be relative.`,
+        url: redirectUrl,
+        projectId: this.projectId,
+      });
     }
     return redirectUrl;
   }

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");
     },