@hexclave/next 1.0.72 → 1.0.74

package/src/lib/hexclave-app/apps/implementations/client-app-impl.automatic-side-effects.test.ts

@@ -0,0 +1,126 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { describe, expect, it } from "vitest";
+import { hexclaveAppInternalsSymbol } from "../../common";
+import { HexclaveClientApp, HexclaveClientAppConstructorOptions, HexclaveClientAppJson } from "../interfaces/client-app";
+
+const baseOptions = {
+  baseUrl: "http://localhost:12345",
+  projectId: "00000000-0000-4000-8000-000000000000",
+  publishableClientKey: "stack-pk-test",
+  tokenStore: "memory",
+  redirectMethod: "none",
+} satisfies HexclaveClientAppConstructorOptions<true, string>;
+
+describe("HexclaveClientApp automatic side effects", () => {
+  it("does not inspect browser state when disabled", () => {
+    const previousWindow = Reflect.get(globalThis, "window");
+    const previousDocument = Reflect.get(globalThis, "document");
+    const hadPreviousWindow = Reflect.has(globalThis, "window");
+    const hadPreviousDocument = Reflect.has(globalThis, "document");
+    const browserGlobal = {};
+    Object.defineProperty(browserGlobal, "location", {
+      get() {
+        throw new Error("Construction must not inspect the current URL when automatic side effects are disabled");
+      },
+    });
+
+    Reflect.set(globalThis, "window", browserGlobal);
+    Object.defineProperty(globalThis, "document", {
+      configurable: true,
+      get() {
+        throw new Error("Construction must not access the document when automatic side effects are disabled");
+      },
+    });
+
+    try {
+      expect(() => new HexclaveClientApp({
+        ...baseOptions,
+        automaticSideEffects: false,
+      })).not.toThrow();
+    } finally {
+      if (hadPreviousWindow) {
+        Reflect.set(globalThis, "window", previousWindow);
+      } else {
+        Reflect.deleteProperty(globalThis, "window");
+      }
+      if (hadPreviousDocument) {
+        Object.defineProperty(globalThis, "document", {
+          configurable: true,
+          value: previousDocument,
+          writable: true,
+        });
+      } else {
+        Reflect.deleteProperty(globalThis, "document");
+      }
+    }
+  });
+
+  it("does not initialize automatic side effects when disabled", () => {
+    const methodName = "_initializeAutomaticSideEffects";
+    const originalInitializer = Reflect.get(HexclaveClientApp.prototype, methodName);
+    let initializationCalls = 0;
+    Reflect.set(HexclaveClientApp.prototype, methodName, () => {
+      initializationCalls += 1;
+    });
+
+    try {
+      new HexclaveClientApp({
+        ...baseOptions,
+        automaticSideEffects: false,
+      });
+
+      expect(initializationCalls).toBe(0);
+    } finally {
+      Reflect.set(HexclaveClientApp.prototype, methodName, originalInitializer);
+    }
+  });
+
+  it.each([undefined, true])("retains automatic initialization when automaticSideEffects is %s", (automaticSideEffects) => {
+    const methodName = "_initializeAutomaticSideEffects";
+    const originalInitializer = Reflect.get(HexclaveClientApp.prototype, methodName);
+    let initializationCalls = 0;
+    Reflect.set(HexclaveClientApp.prototype, methodName, () => {
+      initializationCalls += 1;
+    });
+
+    try {
+      new HexclaveClientApp({
+        ...baseOptions,
+        automaticSideEffects,
+      });
+
+      expect(initializationCalls).toBe(1);
+    } finally {
+      Reflect.set(HexclaveClientApp.prototype, methodName, originalInitializer);
+    }
+  });
+
+  it("preserves the option through serialization", () => {
+    const app = new HexclaveClientApp({
+      ...baseOptions,
+      automaticSideEffects: false,
+    });
+
+    expect(app[hexclaveAppInternalsSymbol].toClientJson().automaticSideEffects).toBe(false);
+  });
+
+  it("preserves stable identity when deserializing with automatic side effects disabled", () => {
+    const json: HexclaveClientAppJson<false, string> = {
+      baseUrl: baseOptions.baseUrl,
+      projectId: baseOptions.projectId,
+      publishableClientKey: baseOptions.publishableClientKey,
+      tokenStore: null,
+      redirectMethod: baseOptions.redirectMethod,
+      automaticSideEffects: false,
+      uniqueIdentifier: "00000000-0000-4000-8000-000000000001",
+    };
+
+    const first = HexclaveClientApp[hexclaveAppInternalsSymbol].fromClientJson(json);
+    const second = HexclaveClientApp[hexclaveAppInternalsSymbol].fromClientJson(json);
+
+    expect(second).toBe(first);
+  });
+});

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

@@ -7,6 +7,7 @@ import { AccessToken } from "@hexclave/shared/dist/sessions";
 import { Store } from "@hexclave/shared/dist/utils/stores";
 import { hexclaveAppInternalsSymbol } from "../../common";
 import { StackClientApp } from "../interfaces/client-app";
+import { planRedirectToHandler } from "./redirect-page-urls";
 
 function createAccessTokenString(refreshTokenId: string): string {
   const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString("base64url");
@@ -54,6 +55,76 @@ function createMockDocument(): Document {
 }
 
 describe("StackClientApp cross-domain auth", () => {
+  it("keeps noRedirectBack same-domain redirects free of redirect-back state", async () => {
+    const redirectPlan = await planRedirectToHandler({
+      handlerName: "signIn",
+      rawHandlerUrl: "/handler/sign-in",
+      noRedirectBack: true,
+      currentUrl: new URL("https://app.example.test/settings?tab=profile"),
+      localOAuthCallbackUrl: "/handler/oauth-callback",
+      rawHomeUrl: "/home",
+      getCrossDomainHandoffParams: async () => {
+        throw new Error("Same-domain redirects must not create cross-domain handoff parameters.");
+      },
+    });
+
+    expect(redirectPlan).toEqual({
+      type: "redirect",
+      url: "/handler/sign-in",
+    });
+  });
+
+  it("returns noRedirectBack cross-domain auth to the source app home", async () => {
+    const handoffState = "no-redirect-back-state";
+    const handoffCodeChallenge = "abcdefghijklmnopqrstuvwxyzABCDEFG_0123456789-._~";
+    const currentUrl = new URL("https://app.example.test/settings?tab=profile");
+    currentUrl.searchParams.set("hexclave_cross_domain_state", handoffState);
+    currentUrl.searchParams.set("hexclave_cross_domain_code_challenge", handoffCodeChallenge);
+    currentUrl.searchParams.set(
+      "hexclave_cross_domain_after_callback_redirect_url",
+      "https://app.example.test/settings?tab=profile",
+    );
+
+    const redirectPlan = await planRedirectToHandler({
+      handlerName: "signIn",
+      rawHandlerUrl: "https://auth.example.test/handler/sign-in",
+      noRedirectBack: true,
+      currentUrl,
+      localOAuthCallbackUrl: "/handler/oauth-callback",
+      rawHomeUrl: "/home",
+      getCrossDomainHandoffParams: async () => {
+        throw new Error("Existing cross-domain handoff parameters must be reused.");
+      },
+    });
+
+    expect(redirectPlan.type).toBe("redirect");
+    if (redirectPlan.type !== "redirect") {
+      throw new Error("Expected noRedirectBack sign-in to produce a redirect URL.");
+    }
+
+    const hostedUrl = new URL(redirectPlan.url);
+    expect(hostedUrl.origin).toBe("https://auth.example.test");
+    expect(hostedUrl.pathname).toBe("/handler/sign-in");
+    expect(hostedUrl.searchParams.get("hexclave_cross_domain_after_callback_redirect_url")).toBe(
+      "https://app.example.test/home",
+    );
+
+    const rawSourceCallbackUrl = hostedUrl.searchParams.get("after_auth_return_to");
+    if (rawSourceCallbackUrl == null) {
+      throw new Error("Expected cross-domain noRedirectBack to include its internal source callback URL.");
+    }
+    const sourceCallbackUrl = new URL(rawSourceCallbackUrl);
+    expect(sourceCallbackUrl.origin).toBe("https://app.example.test");
+    expect(sourceCallbackUrl.pathname).toBe("/handler/oauth-callback");
+    expect(sourceCallbackUrl.searchParams.get("hexclave_cross_domain_auth")).toBe("1");
+    expect(sourceCallbackUrl.searchParams.get("hexclave_cross_domain_state")).toBe(handoffState);
+    expect(sourceCallbackUrl.searchParams.get("hexclave_cross_domain_code_challenge")).toBe(handoffCodeChallenge);
+    expect(sourceCallbackUrl.searchParams.get("hexclave_cross_domain_after_callback_redirect_url")).toBe(
+      "https://app.example.test/home",
+    );
+    expect(sourceCallbackUrl.toString()).not.toContain("/settings");
+  });
+
   it("exposes redirect-back-aware handler URLs for devtool previews", async () => {
     const previousWindow = Reflect.get(globalThis, "window");
     const hadPreviousWindow = Reflect.has(globalThis, "window");
@@ -486,6 +557,8 @@ describe("StackClientApp cross-domain auth", () => {
     callbackUrl.searchParams.set("details", JSON.stringify({
       message: "Your sign up was rejected by an administrator's sign-up rule.",
     }));
+    callbackUrl.searchParams.set("after_auth_return_to", "/dashboard");
+    callbackUrl.searchParams.set("after_callback_redirect_url", "https://customer.example.test/settings?tab=connected-accounts");
     let currentHref = callbackUrl.toString();
     let redirectedUrl = "";
     const redirectSpy = vi.spyOn(StackClientApp.prototype as any, "_redirectTo").mockImplementation(async (...args: unknown[]) => {
@@ -539,6 +612,8 @@ describe("StackClientApp cross-domain auth", () => {
     expect(errorUrl.pathname).toBe("/handler/error");
     expect(errorUrl.searchParams.get("errorCode")).toBe("SIGN_UP_REJECTED");
     expect(errorUrl.searchParams.get("message")).toBe("Your sign up was rejected by an administrator's sign-up rule.");
+    expect(errorUrl.searchParams.get("after_auth_return_to")).toBe("/dashboard");
+    expect(errorUrl.searchParams.get("after_callback_redirect_url")).toBe("https://customer.example.test/settings?tab=connected-accounts");
     expect(new URL(currentHref).searchParams.has("errorCode")).toBe(false);
   });
 

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

@@ -59,7 +59,7 @@ import { TeamPermission } from "../../permissions";
 import { AdminOwnedProject, AdminProjectUpdateOptions, Project, adminProjectCreateOptionsToCrud } from "../../projects";
 import { EditableTeamMemberProfile, ReceivedTeamInvitation, SentTeamInvitation, Team, TeamCreateOptions, TeamUpdateOptions, TeamUser, teamCreateOptionsToCrud, teamUpdateOptionsToCrud } from "../../teams";
 import { buildCliAuthConfirmUrl, getHostedHandlerUrl, isHostedHandlerUrlForProject, resolveHandlerUrls } from "../../url-targets";
-import { augmentUrlWithPersistedRedirectBackState, saveRedirectBackStateFromUrl } from "./redirect-back-state";
+import { augmentUrlWithPersistedRedirectBackState, getRawAfterAuthReturnTo, saveRedirectBackStateFromUrl } from "./redirect-back-state";
 import { recordRedirectAndThrowIfLoopDetected } from "./redirect-loop-breaker";
 import { scopePasskeyAuthenticationToHostname, scopePasskeyRegistrationToHostname } from "../../passkey-rp-id";
 import { ActiveSession, Auth, BaseUser, CurrentUser, InternalUserExtra, OAuthProvider, ProjectCurrentUser, SyncedPartialUser, TokenPartialUser, UserExtra, UserUpdateOptions, userUpdateOptionsToCrud, withUserDestructureGuard } from "../../users";
@@ -86,6 +86,7 @@ isReactServer = sc.isReactServer;
 const NextNavigation = scrambleDuringCompileTime(NextNavigationUnscrambled);
 
 const prefetchedCrossDomainHandoffTtlMs = 55 * 60 * 1000;
+const oauthAfterCallbackRedirectUrlQueryParam = "after_callback_redirect_url";
 
 const nestedCrossDomainAuthQueryParams = {
   refreshTokenId: "stack_nested_cross_domain_auth_refresh_token_id",
@@ -94,7 +95,7 @@ const nestedCrossDomainAuthQueryParams = {
   state: "state",
   codeChallenge: "code_challenge",
   codeChallengeMethod: "code_challenge_method",
-  afterCallbackRedirectUrl: "after_callback_redirect_url",
+  afterCallbackRedirectUrl: oauthAfterCallbackRedirectUrlQueryParam,
 } as const;
 
 function getRedirectHelperInstruction(handlerName: string): string {
@@ -670,18 +671,32 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
     this._redirectMethod = resolvedOptions.redirectMethod || "nextjs"; // THIS_LINE_PLATFORM next
     this._urlOptions = resolvedOptions.urls ?? {};
     this._oauthScopesOnSignIn = resolvedOptions.oauthScopesOnSignIn ?? {};
+    this._analyticsOptions = resolvedOptions.analytics;
+
+    if (extraOptions?.uniqueIdentifier !== undefined) {
+      this._uniqueIdentifier = extraOptions.uniqueIdentifier;
+    }
+
+    // Custom dashboards can disable automatic initialization so URL parameters, browser storage, analytics, and
+    // development overlays cannot affect the containing page. Explicit SDK calls remain functional and retain their
+    // documented side effects.
+    if (resolvedOptions.automaticSideEffects === false) {
+      return;
+    }
+
+    this._initializeAutomaticSideEffects(resolvedOptions);
+  }
+
+  private _initializeAutomaticSideEffects(resolvedOptions: HexclaveClientAppImplConstructorOptionsResolved<HasTokenStore, ProjectId>) {
     if (isBrowserLike() && (resolvedOptions.tokenStore === "cookie" || resolvedOptions.tokenStore === "nextjs-cookie")) {
       runAsynchronously(this._trustedParentDomainCache.getOrWait([window.location.hostname], "write-only"));
       this._ensureCrossSubdomainCookieExists();
     }
 
-    if (extraOptions && extraOptions.uniqueIdentifier) {
-      this._uniqueIdentifier = extraOptions.uniqueIdentifier;
+    if (this._uniqueIdentifier !== undefined) {
       this._initUniqueIdentifier();
     }
 
-    this._analyticsOptions = resolvedOptions.analytics;
-
     const getAnalyticsSession = async (): Promise<InternalSession> => {
       this._ensurePersistentTokenStore();
       const partialUser = await this.getPartialUser({ from: 'token', or: 'anonymous-if-exists' });
@@ -887,9 +902,31 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
 
   protected async _redirectToOAuthCallbackError(error: KnownError): Promise<void> {
     const errorUrl = new URL(this._getUrls().error, window.location.href);
+    const callbackUrl = augmentUrlWithPersistedRedirectBackState({
+      currentUrl: new URL(window.location.href),
+      projectId: this.projectId,
+    });
     errorUrl.searchParams.set("errorCode", error.errorCode);
     errorUrl.searchParams.set("message", error.message);
     errorUrl.searchParams.set("details", JSON.stringify(error.details ?? {}));
+    for (const paramName of [
+      "after_auth_return_to",
+      crossDomainAuthQueryParams.state,
+      crossDomainAuthQueryParams.codeChallenge,
+      crossDomainAuthQueryParams.afterCallbackRedirectUrl,
+    ]) {
+      const value = callbackUrl.searchParams.get(paramName);
+      if (value != null) {
+        errorUrl.searchParams.set(paramName, value);
+      }
+    }
+    const afterCallbackRedirectUrl = callbackUrl.searchParams.get(oauthAfterCallbackRedirectUrlQueryParam);
+    if (afterCallbackRedirectUrl != null) {
+      // Account-link callbacks need to finish consuming the OAuth response before returning to
+      // their invoking page. Carry the already server-validated continuation through the
+      // configured error handler, which validates it again before navigation.
+      errorUrl.searchParams.set(oauthAfterCallbackRedirectUrlQueryParam, afterCallbackRedirectUrl);
+    }
     await this._redirectIfTrusted(errorUrl.toString(), { replace: true });
   }
 
@@ -2673,6 +2710,7 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
         tokenStore: null,
         projectOwnerSession: session,
         noAutomaticPrefetch: true,
+        automaticSideEffects: false,
       }));
     }
     return this._ownedAdminApps.get([session, forProjectId])!;
@@ -3014,16 +3052,18 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
     let currentUrl = isReactServer || typeof window === "undefined"
       ? null
       : new URL(window.location.href);
-    if (
-      currentUrl != null
-      && options?.noRedirectBack !== true
-      && (handlerName === "afterSignIn" || handlerName === "afterSignUp")
-    ) {
+    const shouldRestorePersistedRedirectBackState = (
+      (options?.noRedirectBack !== true && (handlerName === "afterSignIn" || handlerName === "afterSignUp"))
+      || handlerName === "forgotPassword"
+      || handlerName === "passwordReset"
+      || (handlerName === "signIn" && options?.noRedirectBack === true)
+    );
+    if (currentUrl != null && shouldRestorePersistedRedirectBackState) {
       // If intermediate hops dropped the redirect-back query params, restore them from the
-      // sessionStorage mirror so the user still returns to where they came from instead of
-      // stranding on the default post-auth page (on hosted components, that would be the hosted
-      // welcome page). The restored URL goes through the same _isTrusted / cross-domain-authorize
-      // validation below as one read from query params.
+      // sessionStorage mirror. Password-flow continuation pages only carry this inherited state;
+      // redirect planning never turns forgot/reset pages themselves into return targets. The
+      // restored URL still goes through the same _isTrusted / cross-domain-authorize validation
+      // below as one read from query params.
       currentUrl = augmentUrlWithPersistedRedirectBackState({ currentUrl, projectId: this.projectId });
     }
     const plan = await planRedirectToHandler({
@@ -3032,6 +3072,7 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       noRedirectBack: options?.noRedirectBack === true,
       currentUrl,
       localOAuthCallbackUrl: this._getLocalOAuthCallbackHandlerUrl(),
+      rawHomeUrl: rawUrls.home,
       getCrossDomainHandoffParams: async (href) => await this._getCrossDomainHandoffParamsForRedirect(href),
     });
 
@@ -4048,13 +4089,19 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
         }
 
         const { analytics, ...restJson } = omit(json, ["uniqueIdentifier"]);
-        return new _HexclaveClientAppImplIncomplete<HasTokenStore, ProjectId>({
+        const app = new _HexclaveClientAppImplIncomplete<HasTokenStore, ProjectId>({
           ...restJson as any,
           analytics: analyticsOptionsFromJson(analytics),
         }, {
           uniqueIdentifier: json.uniqueIdentifier,
           checkString: providedCheckString,
         });
+        // Inert construction does not register itself, so register only after it has completed to preserve stable
+        // identity across repeated client-side deserialization.
+        if (json.automaticSideEffects === false) {
+          app._initUniqueIdentifier();
+        }
+        return app;
       }
     };
   }
@@ -4081,6 +4128,7 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
           redirectMethod: this._redirectMethod,
           extraRequestHeaders: this._options.extraRequestHeaders,
           devTool: this._options.devTool,
+          automaticSideEffects: this._options.automaticSideEffects,
           analytics: analyticsOptionsToJson(this._analyticsOptions),
         };
       },
@@ -4117,6 +4165,15 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       redirectToHandler: async (handlerName: keyof HandlerUrls, options?: RedirectToOptions) => {
         await this._redirectToHandler(handlerName, options);
       },
+      getRawAfterAuthReturnTo: () => {
+        if (isReactServer || typeof window === "undefined") {
+          return null;
+        }
+        return getRawAfterAuthReturnTo({
+          currentUrl: new URL(window.location.href),
+          projectId: this.projectId,
+        });
+      },
       refreshOwnedProjects: async () => {
         await this._refreshOwnedProjects(await this._getSession());
       },

package/src/lib/hexclave-app/apps/implementations/redirect-back-state.test.ts

@@ -3,7 +3,7 @@
 // THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
 //===========================================
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { augmentUrlWithPersistedRedirectBackState, readRedirectBackState, saveRedirectBackStateFromUrl } from "./redirect-back-state";
+import { augmentUrlWithPersistedRedirectBackState, getRawAfterAuthReturnTo, readRedirectBackState, saveRedirectBackStateFromUrl } from "./redirect-back-state";
 
 function createMockSessionStorage() {
   const map = new Map<string, string>();
@@ -114,6 +114,34 @@ describe("redirect-back state mirror", () => {
     expect(unchanged.toString()).toBe(explicitUrl.toString());
   });
 
+  it("reads the explicit return target before persisted state", () => {
+    saveRedirectBackStateFromUrl({
+      url: new URL("https://hosted.example.test/handler/sign-in?after_auth_return_to=/persisted"),
+      projectId,
+    });
+
+    expect(getRawAfterAuthReturnTo({
+      currentUrl: new URL("https://hosted.example.test/handler/mfa?after_auth_return_to=/explicit"),
+      projectId,
+    })).toBe("/explicit");
+    expect(getRawAfterAuthReturnTo({
+      currentUrl: new URL("https://hosted.example.test/handler/mfa"),
+      projectId,
+    })).toBe("/persisted");
+  });
+
+  it("treats an explicitly empty return target as missing instead of reviving persisted state", () => {
+    saveRedirectBackStateFromUrl({
+      url: new URL("https://hosted.example.test/handler/sign-in?after_auth_return_to=/persisted"),
+      projectId,
+    });
+
+    expect(getRawAfterAuthReturnTo({
+      currentUrl: new URL("https://hosted.example.test/handler/mfa?after_auth_return_to=%20%20"),
+      projectId,
+    })).toBeNull();
+  });
+
   it("leaves the URL unchanged when there is no mirrored state", () => {
     const url = new URL("https://hosted.example.test/handler/sign-in");
     const augmented = augmentUrlWithPersistedRedirectBackState({ currentUrl: url, projectId });

package/src/lib/hexclave-app/apps/implementations/redirect-back-state.ts

@@ -111,6 +111,23 @@ export function readRedirectBackState(options: { projectId: string }): Persisted
   return parsed;
 }
 
+/**
+ * Returns the raw return target carried by the current auth flow. The value is intentionally not
+ * described as trusted: callers must still pass it through the normal redirect validation before
+ * navigating to it.
+ *
+ * An explicit query parameter wins even when it is empty. This prevents a malformed URL from
+ * silently reviving an older flow from sessionStorage.
+ */
+export function getRawAfterAuthReturnTo(options: { currentUrl: URL, projectId: string }): string | null {
+  const explicitReturnTo = options.currentUrl.searchParams.get("after_auth_return_to");
+  if (explicitReturnTo != null) {
+    return explicitReturnTo.trim().length > 0 ? explicitReturnTo : null;
+  }
+  const persistedReturnTo = readRedirectBackState({ projectId: options.projectId })?.afterAuthReturnTo;
+  return persistedReturnTo != null && persistedReturnTo.trim().length > 0 ? persistedReturnTo : null;
+}
+
 /**
  * Returns a copy of `currentUrl` with any redirect-back query params that were dropped along the
  * way restored from the sessionStorage mirror. If `currentUrl` already carries

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

@@ -0,0 +1,119 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { describe, expect, it } from "vitest";
+import { crossDomainAuthQueryParams, planRedirectToHandler } from "./redirect-page-urls";
+
+const localOAuthCallbackUrl = "https://hosted.example.test/handler/oauth-callback";
+
+async function plan(options: {
+  handlerName: "signIn" | "forgotPassword" | "passwordReset" | "afterSignIn" | "afterSignUp",
+  rawHandlerUrl: string,
+  currentUrl: URL,
+  noRedirectBack?: boolean,
+}) {
+  return await planRedirectToHandler({
+    ...options,
+    noRedirectBack: options.noRedirectBack === true,
+    localOAuthCallbackUrl,
+    getCrossDomainHandoffParams: async () => {
+      throw new Error("Continuation-only redirects must not mint a new cross-domain handoff");
+    },
+  });
+}
+
+function expectRedirectUrl(planResult: Awaited<ReturnType<typeof plan>>, baseUrl: URL): URL {
+  if (planResult.type !== "redirect") {
+    throw new Error("Expected a direct redirect plan");
+  }
+  return new URL(planResult.url, baseUrl);
+}
+
+function expectContinuation(url: URL, expectedReturnTo: string): void {
+  expect(url.searchParams.get("after_auth_return_to")).toBe(expectedReturnTo);
+  expect(url.searchParams.get(crossDomainAuthQueryParams.state)).toBe("outer-state");
+  expect(url.searchParams.get(crossDomainAuthQueryParams.codeChallenge)).toBe("outer-challenge");
+  expect(url.searchParams.get(crossDomainAuthQueryParams.afterCallbackRedirectUrl)).toBe("https://customer.example.test/dashboard");
+}
+
+describe("password-flow redirect continuation", () => {
+  it("carries the complete customer return state through forgot-password and a reset-email new tab", async () => {
+    const customerReturnTo = "https://customer.example.test/handler/oauth-callback?hexclave_cross_domain_auth=1";
+    const signInUrl = new URL("https://hosted.example.test/handler/sign-in");
+    signInUrl.searchParams.set("after_auth_return_to", customerReturnTo);
+    signInUrl.searchParams.set(crossDomainAuthQueryParams.state, "outer-state");
+    signInUrl.searchParams.set(crossDomainAuthQueryParams.codeChallenge, "outer-challenge");
+    signInUrl.searchParams.set(crossDomainAuthQueryParams.afterCallbackRedirectUrl, "https://customer.example.test/dashboard");
+
+    const forgotPlan = await plan({
+      handlerName: "forgotPassword",
+      rawHandlerUrl: "/handler/forgot-password",
+      currentUrl: signInUrl,
+    });
+    const forgotUrl = expectRedirectUrl(forgotPlan, signInUrl);
+    expectContinuation(forgotUrl, customerReturnTo);
+
+    const callbackPlan = await plan({
+      handlerName: "passwordReset",
+      rawHandlerUrl: "/handler/password-reset",
+      currentUrl: forgotUrl,
+    });
+    const resetEmailCallbackUrl = expectRedirectUrl(callbackPlan, forgotUrl);
+    expectContinuation(resetEmailCallbackUrl, customerReturnTo);
+
+    // Model opening the callback in a new tab: only URL state is available.
+    resetEmailCallbackUrl.searchParams.set("code", "reset-code");
+    const signInPlan = await plan({
+      handlerName: "signIn",
+      rawHandlerUrl: "/handler/sign-in",
+      currentUrl: resetEmailCallbackUrl,
+      noRedirectBack: true,
+    });
+    const finalSignInUrl = expectRedirectUrl(signInPlan, resetEmailCallbackUrl);
+    expectContinuation(finalSignInUrl, customerReturnTo);
+    expect(finalSignInUrl.searchParams.has("code")).toBe(false);
+  });
+
+  it.each([
+    ["forgotPassword", "/handler/forgot-password"],
+    ["passwordReset", "/handler/password-reset"],
+  ] as const)("never synthesizes the current %s page as a return target", async (handlerName, rawHandlerUrl) => {
+    const currentUrl = new URL(`https://hosted.example.test${rawHandlerUrl}?code=reset-code`);
+    const result = expectRedirectUrl(await plan({
+      handlerName,
+      rawHandlerUrl,
+      currentUrl,
+    }), currentUrl);
+
+    expect(result.searchParams.has("after_auth_return_to")).toBe(false);
+    expect(result.searchParams.has("code")).toBe(false);
+  });
+
+  it("makes sign-in noRedirectBack suppress capture while preserving only inherited state", async () => {
+    const resetUrlWithoutContinuation = new URL("https://hosted.example.test/handler/password-reset?code=reset-code");
+    const result = expectRedirectUrl(await plan({
+      handlerName: "signIn",
+      rawHandlerUrl: "/handler/sign-in",
+      currentUrl: resetUrlWithoutContinuation,
+      noRedirectBack: true,
+    }), resetUrlWithoutContinuation);
+
+    expect(result.toString()).toBe("https://hosted.example.test/handler/sign-in");
+  });
+
+  it.each(["afterSignIn", "afterSignUp"] as const)(
+    "keeps existing %s noRedirectBack semantics",
+    async (handlerName) => {
+      const currentUrl = new URL("https://hosted.example.test/handler/sign-in?after_auth_return_to=%2Fcustomer");
+      const result = expectRedirectUrl(await plan({
+        handlerName,
+        rawHandlerUrl: "/default-after-auth",
+        currentUrl,
+        noRedirectBack: true,
+      }), currentUrl);
+
+      expect(result.toString()).toBe("https://hosted.example.test/default-after-auth");
+    },
+  );
+});