@hexclave/js 1.0.73 → 1.0.74

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

@@ -57,7 +57,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";
@@ -77,6 +77,7 @@ import { mountPushedConfigErrorOverlay } from "../../../../pushed-config-error-o
 let isReactServer = false;
 
 const prefetchedCrossDomainHandoffTtlMs = 55 * 60 * 1000;
+const oauthAfterCallbackRedirectUrlQueryParam = "after_callback_redirect_url";
 
 const nestedCrossDomainAuthQueryParams = {
   refreshTokenId: "stack_nested_cross_domain_auth_refresh_token_id",
@@ -85,7 +86,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 {
@@ -641,18 +642,32 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
     this._redirectMethod = resolvedOptions.redirectMethod || (isBrowserLike() ? "window" : "none");
     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' });
@@ -848,9 +863,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 });
   }
 
@@ -2420,6 +2457,7 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
         tokenStore: null,
         projectOwnerSession: session,
         noAutomaticPrefetch: true,
+        automaticSideEffects: false,
       }));
     }
     return this._ownedAdminApps.get([session, forProjectId])!;
@@ -2747,16 +2785,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({
@@ -2765,6 +2805,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),
     });
 
@@ -3661,13 +3702,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;
       }
     };
   }
@@ -3694,6 +3741,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),
         };
       },
@@ -3730,6 +3778,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");
+    },
+  );
+});

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

@@ -42,7 +42,8 @@ export function getCrossDomainHandoffParamsFromCurrentUrl(currentUrl: URL): Cros
 }
 
 type RedirectBackAwareHandlerName = "signIn" | "signUp" | "onboarding" | "signOut";
-type HandlerRedirectPolicy = "none" | "redirect-back-aware" | "after-auth-return";
+type ContinuationAwareHandlerName = "forgotPassword" | "passwordReset";
+type HandlerRedirectPolicy = "none" | "redirect-back-aware" | "continuation-aware" | "after-auth-return";
 
 type CrossDomainHandoffParamsMaybeMissing = {
   state: string | null,
@@ -57,6 +58,10 @@ function isRedirectBackAwareHandlerName(handlerName: keyof HandlerUrls): handler
     || handlerName === "signOut";
 }
 
+function isContinuationAwareHandlerName(handlerName: keyof HandlerUrls): handlerName is ContinuationAwareHandlerName {
+  return handlerName === "forgotPassword" || handlerName === "passwordReset";
+}
+
 function hasCrossDomainHandoffParams(url: URL): boolean {
   return (
     hasCrossDomainParam(url.searchParams, "state")
@@ -98,14 +103,19 @@ function buildRedirectBackAwareHandlerUrl(options: {
   currentUrl: URL,
   crossDomainHandoffParams: CrossDomainHandoffParams | null,
   localOAuthCallbackUrl: string,
+  noRedirectBack: boolean,
+  afterCallbackRedirectUrlOverride: string | null,
 }): string {
   const nextUrl = new URL(options.rawHandlerUrl, options.currentUrl);
   // Preserve after_auth_return_to verbatim (not a rebranded param).
   const currentAfterAuthReturnTo = options.currentUrl.searchParams.get("after_auth_return_to");
-  if (currentAfterAuthReturnTo != null && !nextUrl.searchParams.has("after_auth_return_to")) {
+  if (!options.noRedirectBack && currentAfterAuthReturnTo != null && !nextUrl.searchParams.has("after_auth_return_to")) {
     nextUrl.searchParams.set("after_auth_return_to", currentAfterAuthReturnTo);
   }
   for (const preservedParam of ["state", "codeChallenge", "afterCallbackRedirectUrl"] as const) {
+    if (options.noRedirectBack && preservedParam === "afterCallbackRedirectUrl") {
+      continue;
+    }
     const currentValue = getCrossDomainParam(options.currentUrl.searchParams, preservedParam);
     if (currentValue != null && !hasCrossDomainParam(nextUrl.searchParams, preservedParam)) {
       setCrossDomainParam(nextUrl.searchParams, preservedParam, currentValue);
@@ -127,31 +137,58 @@ function buildRedirectBackAwareHandlerUrl(options: {
   if (isCrossDomainHandlerRedirect) {
     if (!hasCrossDomainHandoffParams(nextUrl)) {
       const inheritedAfterAuthReturnTo = options.currentUrl.searchParams.get("after_auth_return_to");
-      const afterCallbackRedirectUrl = inheritedAfterAuthReturnTo
-        ? new URL(inheritedAfterAuthReturnTo, options.currentUrl).toString()
-        : options.currentUrl.toString();
+      const afterCallbackRedirectUrl = options.afterCallbackRedirectUrlOverride ?? (
+        inheritedAfterAuthReturnTo
+          ? new URL(inheritedAfterAuthReturnTo, options.currentUrl).toString()
+          : options.currentUrl.toString()
+      );
+      const handoffParams = options.crossDomainHandoffParams
+        ?? getCrossDomainHandoffParamsFromCurrentUrl(options.currentUrl);
       const callbackUrl = buildCrossDomainAuthCallbackUrl({
         currentUrl: options.currentUrl,
         localOAuthCallbackUrl: options.localOAuthCallbackUrl,
-        state: options.crossDomainHandoffParams?.state,
-        codeChallenge: options.crossDomainHandoffParams?.codeChallenge,
+        state: handoffParams?.state,
+        codeChallenge: handoffParams?.codeChallenge,
         afterCallbackRedirectUrl,
       });
 
       nextUrl.searchParams.set("after_auth_return_to", callbackUrl.toString());
       setCrossDomainParam(nextUrl.searchParams, "afterCallbackRedirectUrl", afterCallbackRedirectUrl);
-      if (options.crossDomainHandoffParams != null) {
-        setCrossDomainParam(nextUrl.searchParams, "state", options.crossDomainHandoffParams.state);
-        setCrossDomainParam(nextUrl.searchParams, "codeChallenge", options.crossDomainHandoffParams.codeChallenge);
+      if (handoffParams != null) {
+        setCrossDomainParam(nextUrl.searchParams, "state", handoffParams.state);
+        setCrossDomainParam(nextUrl.searchParams, "codeChallenge", handoffParams.codeChallenge);
       }
     }
-  } else if (options.currentUrl.protocol === nextUrl.protocol && options.currentUrl.host === nextUrl.host && !nextUrl.searchParams.has("after_auth_return_to")) {
+  } else if (!options.noRedirectBack && options.currentUrl.protocol === nextUrl.protocol && options.currentUrl.host === nextUrl.host && !nextUrl.searchParams.has("after_auth_return_to")) {
     nextUrl.searchParams.set("after_auth_return_to", getRelativePart(options.currentUrl));
   }
 
   return nextUrl.origin === options.currentUrl.origin ? getRelativePart(nextUrl) : nextUrl.toString();
 }
 
+/**
+ * Carries an auth flow's existing return state without ever making the current page the return
+ * target. This distinction is important for password flows: forgot-password and password-reset
+ * are continuation pages, not destinations customers should return to after signing in.
+ */
+function buildContinuationAwareHandlerUrl(options: {
+  rawHandlerUrl: string,
+  currentUrl: URL,
+}): string {
+  const nextUrl = new URL(options.rawHandlerUrl, options.currentUrl);
+  const inheritedAfterAuthReturnTo = options.currentUrl.searchParams.get("after_auth_return_to");
+  if (inheritedAfterAuthReturnTo != null && !nextUrl.searchParams.has("after_auth_return_to")) {
+    nextUrl.searchParams.set("after_auth_return_to", inheritedAfterAuthReturnTo);
+  }
+  for (const preservedParam of ["state", "codeChallenge", "afterCallbackRedirectUrl"] as const) {
+    const currentValue = getCrossDomainParam(options.currentUrl.searchParams, preservedParam);
+    if (currentValue != null && !hasCrossDomainParam(nextUrl.searchParams, preservedParam)) {
+      setCrossDomainParam(nextUrl.searchParams, preservedParam, currentValue);
+    }
+  }
+  return nextUrl.origin === options.currentUrl.origin ? getRelativePart(nextUrl) : nextUrl.toString();
+}
+
 function getHandlerRedirectPolicy(handlerName: keyof HandlerUrls): HandlerRedirectPolicy {
   if (handlerName === "afterSignIn" || handlerName === "afterSignUp") {
     return "after-auth-return";
@@ -159,6 +196,9 @@ function getHandlerRedirectPolicy(handlerName: keyof HandlerUrls): HandlerRedire
   if (isRedirectBackAwareHandlerName(handlerName)) {
     return "redirect-back-aware";
   }
+  if (isContinuationAwareHandlerName(handlerName)) {
+    return "continuation-aware";
+  }
   return "none";
 }
 
@@ -179,6 +219,8 @@ async function resolveRedirectBackAwareHandlerUrlForRedirect(options: {
   currentUrl: URL,
   localOAuthCallbackUrl: string,
   getCrossDomainHandoffParams: (currentUrl: URL) => Promise<CrossDomainHandoffParams>,
+  noRedirectBack: boolean,
+  afterCallbackRedirectUrlOverride: string | null,
 }): Promise<string> {
   const initial = buildRedirectBackAwareHandlerUrl({
     handlerName: options.handlerName,
@@ -186,6 +228,8 @@ async function resolveRedirectBackAwareHandlerUrlForRedirect(options: {
     currentUrl: options.currentUrl,
     crossDomainHandoffParams: null,
     localOAuthCallbackUrl: options.localOAuthCallbackUrl,
+    noRedirectBack: options.noRedirectBack,
+    afterCallbackRedirectUrlOverride: options.afterCallbackRedirectUrlOverride,
   });
   if (options.handlerName === "signOut") {
     return initial;
@@ -204,6 +248,8 @@ async function resolveRedirectBackAwareHandlerUrlForRedirect(options: {
     currentUrl: options.currentUrl,
     crossDomainHandoffParams,
     localOAuthCallbackUrl: options.localOAuthCallbackUrl,
+    noRedirectBack: options.noRedirectBack,
+    afterCallbackRedirectUrlOverride: options.afterCallbackRedirectUrlOverride,
   });
 }
 
@@ -213,18 +259,56 @@ export async function planRedirectToHandler(options: {
   noRedirectBack: boolean,
   currentUrl: URL | null,
   localOAuthCallbackUrl: string,
+  rawHomeUrl: string,
   getCrossDomainHandoffParams: (currentUrl: URL) => Promise<CrossDomainHandoffParams>,
 }): Promise<RedirectToHandlerPlan> {
-  if (options.noRedirectBack || options.currentUrl == null) {
+  if (options.currentUrl == null) {
     return { type: "redirect", url: options.rawHandlerUrl };
   }
 
   const policy = getHandlerRedirectPolicy(options.handlerName);
+  if (options.noRedirectBack) {
+    // Sign-in uses noRedirectBack from password-reset pages to avoid capturing the reset page.
+    // Same-domain sign-in must still carry an already-inherited continuation. Cross-domain
+    // sign-in falls through to the redirect-back-aware planner below because it needs to return
+    // through the source app's callback before continuing to home.
+    if (options.handlerName === "signIn") {
+      const signInTarget = new URL(options.rawHandlerUrl, options.currentUrl);
+      if (signInTarget.origin === options.currentUrl.origin) {
+        return {
+          type: "redirect",
+          url: buildContinuationAwareHandlerUrl({
+            rawHandlerUrl: options.rawHandlerUrl,
+            currentUrl: options.currentUrl,
+          }),
+        };
+      }
+    } else {
+      // Other handlers retain the historical noRedirectBack behavior, including
+      // afterSignIn/afterSignUp ignoring all return state.
+      return {
+        type: "redirect",
+        url: options.rawHandlerUrl,
+      };
+    }
+  }
   if (policy === "none") {
     return { type: "redirect", url: options.rawHandlerUrl };
   }
+  if (policy === "continuation-aware") {
+    return {
+      type: "redirect",
+      url: buildContinuationAwareHandlerUrl({
+        rawHandlerUrl: options.rawHandlerUrl,
+        currentUrl: options.currentUrl,
+      }),
+    };
+  }
 
   if (policy === "after-auth-return") {
+    if (options.noRedirectBack) {
+      return { type: "redirect", url: options.rawHandlerUrl };
+    }
     const redirectBackUrl = options.currentUrl.searchParams.get("after_auth_return_to");
     if (redirectBackUrl == null) {
       return { type: "redirect", url: options.rawHandlerUrl };
@@ -267,6 +351,12 @@ export async function planRedirectToHandler(options: {
     });
   }
 
+  // noRedirectBack suppresses the initiating deep link, not the return journey. Cross-domain auth
+  // still needs to return through the source app's callback, but its final destination is home.
+  const afterCallbackRedirectUrlOverride = options.noRedirectBack
+    ? new URL(options.rawHomeUrl, options.currentUrl).toString()
+    : null;
+
   return {
     type: "redirect",
     url: await resolveRedirectBackAwareHandlerUrlForRedirect({
@@ -275,6 +365,8 @@ export async function planRedirectToHandler(options: {
       currentUrl: options.currentUrl,
       localOAuthCallbackUrl: options.localOAuthCallbackUrl,
       getCrossDomainHandoffParams: options.getCrossDomainHandoffParams,
+      noRedirectBack: options.noRedirectBack,
+      afterCallbackRedirectUrlOverride,
     }),
   };
 }

package/src/lib/hexclave-app/apps/interfaces/client-app.ts

@@ -3,10 +3,10 @@
 // THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
 //===========================================
 import { KnownErrors } from "@hexclave/shared";
+import type { RequestListener } from "@hexclave/shared/dist/interface/client-interface";
 import { CurrentUserCrud } from "@hexclave/shared/dist/interface/crud/current-user";
 import { Result } from "@hexclave/shared/dist/utils/results";
-import { AsyncStoreProperty, AuthLike, GetCurrentPartialUserOptions, GetCurrentUserOptions, HandlerUrlOptions, HandlerUrls, OAuthScopesOnSignIn, RedirectMethod, RedirectToOptions, ResolvedHandlerUrls, hexclaveAppInternalsSymbol, TokenStoreInit } from "../../common";
-import type { RequestListener } from "@hexclave/shared/dist/interface/client-interface";
+import { AsyncStoreProperty, AuthLike, GetCurrentPartialUserOptions, GetCurrentUserOptions, HandlerUrlOptions, HandlerUrls, hexclaveAppInternalsSymbol, OAuthScopesOnSignIn, RedirectMethod, RedirectToOptions, ResolvedHandlerUrls, TokenStoreInit } from "../../common";
 import { CustomerInvoicesList, CustomerInvoicesRequestOptions, CustomerProductsList, CustomerProductsRequestOptions, Item } from "../../customers";
 import { Project } from "../../projects";
 import { ProjectCurrentUser, SyncedPartialUser, TokenPartialUser } from "../../users";
@@ -41,6 +41,14 @@ export type StackClientAppConstructorOptions<HasTokenStore extends boolean, Proj
    */
   noAutomaticPrefetch?: boolean,
 
+  /**
+   * Whether the constructor starts browser integrations and other automatic side effects. Defaults to `true`.
+   *
+   * Set this to `false` when the app is instantiated inside a custom dashboard. Explicit method calls remain
+   * available and can still perform their documented side effects.
+   */
+  automaticSideEffects?: boolean,
+
   /**
    * Options for analytics and session recording. Replays are enabled by default;
    * set `{ replays: { enabled: false } }` to opt out.
@@ -128,6 +136,8 @@ export type StackClientApp<HasTokenStore extends boolean = boolean, ProjectId ex
       redirectToUrl(url: string | URL, options?: { replace?: boolean }): Promise<void>,
       getRedirectToHandlerUrl(handlerName: keyof HandlerUrls, options?: RedirectToOptions): Promise<string>,
       redirectToHandler(handlerName: keyof HandlerUrls, options?: RedirectToOptions): Promise<void>,
+      /** Raw flow metadata only. Never navigate to this value without normal redirect validation. */
+      getRawAfterAuthReturnTo(): string | null,
       signInWithTokens(tokens: { accessToken: string, refreshToken: string }): Promise<void>,
       awaitPendingAuthResolutions(): Promise<void>,
       isTrustedRedirectUrl(url: string): Promise<boolean>,