@hexclave/react 1.0.49 → 1.0.52

package/src/components-page/sign-out.tsx

@@ -6,9 +6,26 @@
 //===========================================
 
 import { cacheFunction } from "@hexclave/shared/dist/utils/caches";
+import { captureError } from "@hexclave/shared/dist/utils/errors";
 import { use } from "@hexclave/shared/dist/utils/react";
-import { CurrentUser, useUser } from "..";
+import { CurrentUser, useStackApp, useUser } from "..";
 import { PredefinedMessageCard } from "../components/message-cards/predefined-message-card";
+import { StackClientApp, hexclaveAppInternalsSymbol } from "../lib/hexclave-app";
+
+// The sign-out page's `after_auth_return_to` comes straight from the query string, so it is
+// attacker-craftable (open-redirect shaped). Only follow it if it passes the same trust validation
+// as every other SDK redirect; otherwise ignore it and fall back to the default after-sign-out
+// destination.
+const cacheGetTrustedRedirectUrl = cacheFunction(async (app: StackClientApp<true, string>, redirectUrl: string | undefined): Promise<string | undefined> => {
+  if (redirectUrl == null) {
+    return undefined;
+  }
+  if (await app[hexclaveAppInternalsSymbol].isTrustedRedirectUrl(redirectUrl)) {
+    return redirectUrl;
+  }
+  captureError("sign-out-untrusted-redirect-url", new Error(`Ignoring untrusted after_auth_return_to query parameter on the sign-out page: ${redirectUrl}`));
+  return undefined;
+});
 
 const cacheSignOut = cacheFunction(async (user: CurrentUser, redirectUrl: string | undefined) => {
   return await user.signOut({ redirectUrl });
@@ -24,13 +41,15 @@ const cacheRedirectIfAlreadySignedOut = cacheFunction(async (redirectUrl: string
 });
 
 export function SignOut(props: { fullPage?: boolean, searchParams?: Record<string, string> }) {
+  const app = useStackApp();
   const user = useUser({ or: "return-null" });
   const redirectUrl = props.searchParams?.after_auth_return_to;
+  const trustedRedirectUrl = use(cacheGetTrustedRedirectUrl(app, redirectUrl));
 
   if (user) {
-    use(cacheSignOut(user, redirectUrl));
+    use(cacheSignOut(user, trustedRedirectUrl));
   } else {
-    use(cacheRedirectIfAlreadySignedOut(redirectUrl));
+    use(cacheRedirectIfAlreadySignedOut(trustedRedirectUrl));
   }
 
   return <PredefinedMessageCard type='signedOut' fullPage={props.fullPage} />;

package/src/dev-tool/dev-tool-core.ts

@@ -8,7 +8,6 @@ import { DEV_TOOL_ROOT_ID } from "@hexclave/shared/dist/utils/dev-tool";
 import { runAsynchronously, runAsynchronouslyWithAlert } from "@hexclave/shared/dist/utils/promises";
 import { isLocalhost } from "@hexclave/shared/dist/utils/urls";
 import type { StackClientApp } from "../lib/hexclave-app";
-import { envVars } from "../generated/env";
 import { getGlobalUiInstance, h, hasAppendChild, setGlobalUiInstance, setHtml, type UiGlobalInstance } from "../in-page-ui/dom";
 import { getBaseUrl } from "../lib/hexclave-app/apps/implementations/common";
 import type { HandlerUrlOptions, HandlerUrls, HandlerUrlTarget } from "../lib/hexclave-app/common";
@@ -63,6 +62,11 @@ const MAX_LOG_ENTRIES = 500;
 const CONSOLE_LOG_BATCH_SIZE = 100;
 const DRAG_THRESHOLD = 5;
 const DOCS_URL = 'https://docs.hexclave.com';
+// The local development-environment dashboard always listens on this loopback
+// port (see the CLI's DEFAULT_DASHBOARD_PORT). The dev tool runs inside the
+// customer's own app, so it can't read the CLI's env vars — the port is fixed.
+const LOCAL_DASHBOARD_ORIGIN = 'http://localhost:26700';
+const HOSTED_DASHBOARD_URL = 'https://app.hexclave.com';
 
 const TABS: { id: TabId; label: string; icon: string }[] = [
   { id: 'overview', label: 'Overview', icon: '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="7" height="7"/><rect x="14" y="3" width="7" height="7"/><rect x="14" y="14" width="7" height="7"/><rect x="3" y="14" width="7" height="7"/></svg>' },
@@ -193,42 +197,60 @@ function resolveApiBaseUrl(app: StackClientApp<true>): string {
   return getBaseUrl(opts.baseUrl);
 }
 
-function shouldShowDashboardTab(app: StackClientApp<true>): boolean {
-  return envVars.HEXCLAVE_IS_LOCAL_EMULATOR === "true" && isLocalhost(resolveApiBaseUrl(app));
+function localDashboardProjectUrl(app: StackClientApp<true>): string {
+  return `${LOCAL_DASHBOARD_ORIGIN}/projects/${encodeURIComponent(app.projectId)}`;
 }
 
-function getTabsForApp(app: StackClientApp<true>): { id: TabId; label: string; icon: string }[] {
-  if (shouldShowDashboardTab(app)) {
-    return TABS;
-  }
-  return TABS.filter((tab) => tab.id !== 'dashboard');
+function parseProjectAvailabilityResponse(body: unknown): boolean {
+  if (typeof body !== 'object' || body === null) return false;
+  return 'project_available' in body && body.project_available === true;
+}
+
+// How long to wait for the availability probe before giving up. A refused
+// connection rejects almost immediately, but a host that accepts the socket yet
+// never responds would otherwise leave the tab stuck on "Checking…" forever.
+const LOCAL_DASHBOARD_PROBE_TIMEOUT_MS = 3000;
+
+// Whether the current page can even talk to the HTTP-only local dashboard.
+// LOCAL_DASHBOARD_ORIGIN is `http://localhost:26700`, so the page itself must be
+// an http: localhost origin: an https: page (e.g. an HTTPS dev server) would
+// have both the probe fetch and the iframe embed blocked as mixed content, so
+// we treat that as "not available" and fall back to the hosted dashboard.
+function canReachLocalDashboard(): boolean {
+  return isLocalhost(window.location.href) && window.location.protocol === 'http:';
 }
 
-function deriveDashboardBaseUrl(apiBaseUrl: string): string {
+// Decides whether the Dashboard tab can embed the locally-running
+// development-environment dashboard. Rather than inferring from build-time env
+// vars (which don't reflect whether the dev environment is actually up right
+// now), we ask the running development environment directly:
+//   1. We must be viewing the app from an http: localhost origin — the HTTP-only
+//      dashboard on :26700 is only reachable from, and only relevant to, a local
+//      browser (and an https: page can't reach it without mixed-content errors).
+//   2. The development environment must be running AND already own this exact
+//      project (see the project-availability route it answers).
+// Any failure — dev environment not running (connection refused), probe timeout,
+// project unknown, or a malformed response — resolves to `false`, which shows
+// the hosted-dashboard hint instead.
+async function isLocalDashboardProjectAvailable(app: StackClientApp<true>): Promise<boolean> {
+  if (!canReachLocalDashboard()) return false;
+  const url = `${LOCAL_DASHBOARD_ORIGIN}/api/development-environment/project-availability?project_id=${encodeURIComponent(app.projectId)}`;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), LOCAL_DASHBOARD_PROBE_TIMEOUT_MS);
   try {
-    const url = new URL(apiBaseUrl);
-    if (url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]') {
-      const port = url.port;
-      if (port && port.endsWith('02')) {
-        url.port = port.slice(0, -2) + '01';
-      }
-      return url.origin;
-    }
-    if (url.hostname.startsWith('api.')) {
-      url.hostname = 'app.' + url.hostname.slice(4);
-      return url.origin;
-    }
-    return url.origin;
+    const response = await fetch(url, { method: 'GET', signal: controller.signal });
+    if (!response.ok) return false;
+    return parseProjectAvailabilityResponse(await response.json());
   } catch {
-    return 'https://app.hexclave.com';
+    // Reachability probe: when the local development environment isn't running,
+    // the fetch rejects (connection refused); when it hangs, the AbortController
+    // aborts it. Either way that simply means "not available".
+    return false;
+  } finally {
+    clearTimeout(timeout);
   }
 }
 
-function resolveDashboardUrl(app: StackClientApp<true>): string {
-  const base = deriveDashboardBaseUrl(resolveApiBaseUrl(app));
-  return `${base}/projects/${encodeURIComponent(app.projectId)}`;
-}
-
 function formatTimestamp(ts: number): string {
   return new Date(ts).toLocaleTimeString([], {
     hour: '2-digit',
@@ -563,8 +585,8 @@ function createTabBar(
 // Iframe helper
 // ---------------------------------------------------------------------------
 
-function createIframeTab(src: string, title: string, loadingMsg = 'Loading\u2026', errorMsg = 'Unable to load content', errorDetail?: string, openExternallyLabel?: string): HTMLElement {
-  const container = h('div', { className: 'sdt-iframe-container' });
+function populateIframeTab(container: HTMLElement, src: string, title: string, loadingMsg = 'Loading\u2026', errorMsg = 'Unable to load content', errorDetail?: string, openExternallyLabel?: string): void {
+  container.innerHTML = '';
   if (openExternallyLabel != null) {
     container.appendChild(h('div', { className: 'sdt-iframe-toolbar' },
       h('a', { href: src, target: '_blank', rel: 'noopener noreferrer', className: 'sdt-iframe-open-link' }, openExternallyLabel),
@@ -594,7 +616,7 @@ function createIframeTab(src: string, title: string, loadingMsg = 'Loading\u2026
     }
     const retryBtn = h('button', { className: 'sdt-iframe-error-btn' }, 'Retry');
     retryBtn.addEventListener('click', () => {
-      container.replaceWith(createIframeTab(src, title, loadingMsg, errorMsg, errorDetail, openExternallyLabel));
+      populateIframeTab(container, src, title, loadingMsg, errorMsg, errorDetail, openExternallyLabel);
     });
     errDiv.appendChild(retryBtn);
     const link = h('a', { href: src, target: '_blank', rel: 'noopener noreferrer', style: { color: 'var(--sdt-accent)', fontSize: '12px', textDecoration: 'none' } }, 'Open in new tab');
@@ -603,7 +625,6 @@ function createIframeTab(src: string, title: string, loadingMsg = 'Loading\u2026
   });
 
   container.appendChild(iframe);
-  return container;
 }
 
 // ===========================================================================================
@@ -1681,8 +1702,52 @@ function createAITab(app: StackClientApp<true>): HTMLElement {
 // ---------------------------------------------------------------------------
 
 function createDashboardTab(app: StackClientApp<true>): HTMLElement {
-  const dashboardUrl = resolveDashboardUrl(app);
-  return createIframeTab(dashboardUrl, 'Hexclave Dashboard', 'Loading dashboard\u2026', 'Unable to load dashboard', 'The dashboard may require authentication or block framing', 'Open in New Tab');
+  const container = h('div', { className: 'sdt-iframe-container' });
+
+  function showChecking() {
+    container.innerHTML = '';
+    container.appendChild(h('div', { className: 'sdt-iframe-loading' }, 'Checking development environment\u2026'));
+  }
+
+  function showUnavailable() {
+    container.innerHTML = '';
+    const message = h('div', { className: 'sdt-dashboard-unavailable' });
+    const text = h('div', { className: 'sdt-dashboard-unavailable-text' });
+    text.appendChild(document.createTextNode('Navigate to '));
+    text.appendChild(h('a', {
+      className: 'sdt-dashboard-unavailable-link',
+      href: HOSTED_DASHBOARD_URL,
+      target: '_blank',
+      rel: 'noopener noreferrer',
+    }, HOSTED_DASHBOARD_URL));
+    text.appendChild(document.createTextNode(" to view this project's dashboard"));
+    message.appendChild(text);
+    container.appendChild(message);
+  }
+
+  async function check() {
+    showChecking();
+    const available = await isLocalDashboardProjectAvailable(app);
+    // The dev tool may have been torn down while we were probing; only mutate
+    // the DOM if this container is still mounted.
+    if (!container.isConnected) return;
+    if (available) {
+      populateIframeTab(
+        container,
+        localDashboardProjectUrl(app),
+        'Hexclave Dashboard',
+        'Loading dashboard\u2026',
+        'Unable to load dashboard',
+        'The dashboard may require authentication or block framing',
+        'Open in New Tab',
+      );
+    } else {
+      showUnavailable();
+    }
+  }
+
+  runAsynchronously(check);
+  return container;
 }
 
 // ---------------------------------------------------------------------------
@@ -2112,7 +2177,7 @@ function createPanel(
     panel.style.height = state.get().panelHeight + 'px';
   }
 
-  const tabs = getTabsForApp(app);
+  const tabs = TABS;
   const storedActiveTab = state.get().activeTab;
   const activeTab = tabs.some((tab) => tab.id === storedActiveTab) ? storedActiveTab : DEFAULT_STATE.activeTab;
 

package/src/dev-tool/dev-tool-styles.ts

@@ -328,6 +328,14 @@ export const devToolCSS = getInPageUiBaseCSS('.hexclave-devtool') + `
     z-index: 1;
   }
 
+  /* Iframe panes lay their content out as a flex column so the embedded
+     dashboard (or the fallback message) fills the pane height. Uses two
+     classes to win over the plain .sdt-tab-pane-active { display: block }. */
+  .hexclave-devtool .sdt-tab-pane-iframe.sdt-tab-pane-active {
+    display: flex;
+    flex-direction: column;
+  }
+
   /* ===== Overview tab — single column ===== */
 
   .hexclave-devtool .sdt-ov {
@@ -1235,6 +1243,33 @@ export const devToolCSS = getInPageUiBaseCSS('.hexclave-devtool') + `
     background: var(--sdt-accent-hover);
   }
 
+  .hexclave-devtool .sdt-dashboard-unavailable {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 12px;
+    padding: 24px;
+    text-align: center;
+    color: var(--sdt-text-secondary);
+    font-size: 14px;
+  }
+
+  .hexclave-devtool .sdt-dashboard-unavailable-text {
+    max-width: 420px;
+    line-height: 1.5;
+  }
+
+  .hexclave-devtool .sdt-dashboard-unavailable-link {
+    color: var(--sdt-accent);
+    text-decoration: none;
+  }
+
+  .hexclave-devtool .sdt-dashboard-unavailable-link:hover {
+    text-decoration: underline;
+  }
+
   /* Shared content fade animation */
   .hexclave-devtool .sdt-tab-content-fade {
     animation: sdt-tab-fade-in 0.15s ease-out;

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

@@ -648,6 +648,133 @@ describe("StackClientApp cross-domain auth", () => {
     expect(redirectedUrl).toBe("/settings?tab=profile");
   });
 
+  it("restores a dropped after_auth_return_to from the sessionStorage mirror when redirecting after sign-in", async () => {
+    const previousWindow = globalThis.window;
+    const previousDocument = globalThis.document;
+    const hadPreviousWindow = Reflect.has(globalThis, "window");
+    const sessionStorageMap = new Map<string, string>();
+    const windowMock = {
+      location: {
+        href: "https://demo.example.test/handler/sign-in?after_auth_return_to=%2Fmusic%3Ftrack%3D1",
+      },
+      sessionStorage: {
+        getItem: (key: string) => sessionStorageMap.get(key) ?? null,
+        setItem: (key: string, value: string) => {
+          sessionStorageMap.set(key, value);
+        },
+        removeItem: (key: string) => {
+          sessionStorageMap.delete(key);
+        },
+      },
+    };
+    Reflect.set(globalThis, "window", windowMock);
+    globalThis.document = createMockDocument();
+
+    try {
+      // The constructor mirrors the redirect-back state from the arrival URL into sessionStorage.
+      const clientApp = new StackClientApp({
+        baseUrl: "http://localhost:12345",
+        projectId: "00000000-0000-4000-8000-000000000011",
+        publishableClientKey: "stack-pk-test",
+        tokenStore: "memory",
+        redirectMethod: "window",
+        noAutomaticPrefetch: true,
+      });
+
+      // Intermediate hops (MFA, magic link, OAuth round-trips, ...) dropped the query params.
+      windowMock.location.href = "https://demo.example.test/handler/mfa";
+
+      const redirectUrl = await clientApp[hexclaveAppInternalsSymbol].getRedirectToHandlerUrl("afterSignIn");
+      expect(redirectUrl).toBe("/music?track=1");
+
+      // noRedirectBack opts out of the mirror just like it opts out of the query param.
+      const noRedirectBackUrl = await clientApp[hexclaveAppInternalsSymbol].getRedirectToHandlerUrl("afterSignIn", { noRedirectBack: true });
+      expect(new URL(noRedirectBackUrl, "https://demo.example.test").pathname).toBe("/");
+    } finally {
+      globalThis.document = previousDocument;
+      if (hadPreviousWindow) {
+        Reflect.set(globalThis, "window", previousWindow);
+      } else {
+        Reflect.deleteProperty(globalThis, "window");
+      }
+    }
+  });
+
+  it("restores dropped cross-domain handoff state from the sessionStorage mirror when redirecting after sign-in", async () => {
+    const projectId = "00000000-0000-4000-8000-000000000012";
+    const previousWindow = globalThis.window;
+    const hadPreviousWindow = Reflect.has(globalThis, "window");
+    const sessionStorageMap = new Map<string, string>();
+
+    const handoffState = "mirror-handoff-state";
+    const handoffCodeChallenge = "abcdefghijklmnopqrstuvwxyzABCDEFG_0123456789-._~";
+    const handoffAfterCallbackRedirect = "https://demo.example.test/dashboard";
+    const redirectBackUrl = new URL("https://demo.example.test/handler/oauth-callback");
+    redirectBackUrl.searchParams.set("hexclave_cross_domain_auth", "1");
+    redirectBackUrl.searchParams.set("hexclave_cross_domain_state", handoffState);
+    redirectBackUrl.searchParams.set("hexclave_cross_domain_code_challenge", handoffCodeChallenge);
+    redirectBackUrl.searchParams.set("hexclave_cross_domain_after_callback_redirect_url", handoffAfterCallbackRedirect);
+
+    const arrivalUrl = new URL(`https://${projectId}.built-with-stack-auth.com/handler/sign-in`);
+    arrivalUrl.searchParams.set("after_auth_return_to", redirectBackUrl.toString());
+    arrivalUrl.searchParams.set("hexclave_cross_domain_state", handoffState);
+    arrivalUrl.searchParams.set("hexclave_cross_domain_code_challenge", handoffCodeChallenge);
+    arrivalUrl.searchParams.set("hexclave_cross_domain_after_callback_redirect_url", handoffAfterCallbackRedirect);
+
+    const previousDocument = globalThis.document;
+    const windowMock = {
+      location: {
+        href: arrivalUrl.toString(),
+      },
+      sessionStorage: {
+        getItem: (key: string) => sessionStorageMap.get(key) ?? null,
+        setItem: (key: string, value: string) => {
+          sessionStorageMap.set(key, value);
+        },
+        removeItem: (key: string) => {
+          sessionStorageMap.delete(key);
+        },
+      },
+    };
+    Reflect.set(globalThis, "window", windowMock);
+    globalThis.document = createMockDocument();
+
+    try {
+      const clientApp = new StackClientApp({
+        baseUrl: "http://localhost:12345",
+        projectId,
+        publishableClientKey: "stack-pk-test",
+        tokenStore: "memory",
+        redirectMethod: "window",
+        noAutomaticPrefetch: true,
+      });
+      const crossDomainAuthorizeRedirect = "https://demo.example.test/handler/oauth-callback?code=minted-code&state=mirror-handoff-state";
+      const createCrossDomainAuthRedirectUrlSpy = vi
+        .spyOn(clientApp as any, "_createCrossDomainAuthRedirectUrl")
+        .mockResolvedValue(crossDomainAuthorizeRedirect);
+
+      // All redirect-back query params were dropped before the after-sign-in redirect.
+      windowMock.location.href = `https://${projectId}.built-with-stack-auth.com/handler/sign-in`;
+
+      const redirectUrl = await clientApp[hexclaveAppInternalsSymbol].getRedirectToHandlerUrl("afterSignIn");
+
+      expect(createCrossDomainAuthRedirectUrlSpy).toHaveBeenCalledWith(expect.objectContaining({
+        redirectUri: redirectBackUrl.toString(),
+        state: handoffState,
+        codeChallenge: handoffCodeChallenge,
+        afterCallbackRedirectUrl: handoffAfterCallbackRedirect,
+      }));
+      expect(redirectUrl).toBe(crossDomainAuthorizeRedirect);
+    } finally {
+      globalThis.document = previousDocument;
+      if (hadPreviousWindow) {
+        Reflect.set(globalThis, "window", previousWindow);
+      } else {
+        Reflect.deleteProperty(globalThis, "window");
+      }
+    }
+  });
+
   it("ignores stale session callbacks after a newer refresh token owns the token store", async () => {
     const clientApp = new StackClientApp({
       baseUrl: "http://localhost:12345",

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

@@ -58,6 +58,8 @@ 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 { recordRedirectAndThrowIfLoopDetected } from "./redirect-loop-breaker";
 import { ActiveSession, Auth, BaseUser, CurrentUser, InternalUserExtra, OAuthProvider, ProjectCurrentUser, SyncedPartialUser, TokenPartialUser, UserExtra, UserUpdateOptions, userUpdateOptionsToCrud, withUserDestructureGuard } from "../../users";
 import { StackClientApp, StackClientAppConstructorOptions, StackClientAppJson } from "../interfaces/client-app";
 import { _HexclaveAdminAppImplIncomplete } from "./admin-app-impl";
@@ -723,6 +725,11 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       this._trackPendingAuthResolution(async () => {
         await this._maybeHandleNestedCrossDomainAuth(urlAtConstructionTime);
       });
+
+      // Mirror any redirect-back state from the page URL into sessionStorage, so the return trip
+      // survives later hops that drop the query params (OAuth provider round-trips, MFA, magic
+      // links, ...). See redirect-back-state.ts for details.
+      saveRedirectBackStateFromUrl({ url: urlAtConstructionTime, projectId: this.projectId });
     }
 
     if (isBrowserLike() && resolvedOptions.devTool !== false) {
@@ -2894,6 +2901,17 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
   }
 
   protected async _redirectTo(options: { url: URL | string, replace?: boolean }) {
+    if (this._redirectMethod !== "none" && isBrowserLike()) {
+      const currentUrl = new URL(window.location.href);
+      const targetUrl = new URL(options.url, currentUrl);
+      // Circuit breaker: if this exact redirect keeps repeating, throw so the initiating page
+      // renders its error state instead of bouncing the user between pages forever.
+      recordRedirectAndThrowIfLoopDetected({ currentUrl, targetUrl });
+      // Client-side navigations don't re-run the app constructor, so mirror redirect-back state
+      // on every SDK-driven hop too (see redirect-back-state.ts).
+      saveRedirectBackStateFromUrl({ url: targetUrl, projectId: this.projectId });
+    }
+
     if (this._redirectMethod === "none") {
       return;
     } else if (typeof this._redirectMethod === "object" && this._redirectMethod.navigate) {
@@ -2953,9 +2971,21 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       throw new Error(`No URL for handler name ${handlerName}`);
     }
 
-    const currentUrl = isReactServer || typeof window === "undefined"
+    let currentUrl = isReactServer || typeof window === "undefined"
       ? null
       : new URL(window.location.href);
+    if (
+      currentUrl != null
+      && options?.noRedirectBack !== true
+      && (handlerName === "afterSignIn" || handlerName === "afterSignUp")
+    ) {
+      // 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.
+      currentUrl = augmentUrlWithPersistedRedirectBackState({ currentUrl, projectId: this.projectId });
+    }
     const plan = await planRedirectToHandler({
       handlerName,
       rawHandlerUrl,
@@ -4057,6 +4087,9 @@ export class _HexclaveClientAppImplIncomplete<HasTokenStore extends boolean, Pro
       awaitPendingAuthResolutions: async () => {
         await this._awaitPendingAuthResolutions();
       },
+      isTrustedRedirectUrl: async (url: string) => {
+        return await this._isTrusted(url);
+      },
     };
   };
 

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

@@ -12,6 +12,7 @@ import { ReactPromise, runAsynchronously } from "@hexclave/shared/dist/utils/pro
 import { suspendIfSsr, 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";
@@ -44,7 +45,23 @@ const showMissingConfigAlertInBrowser = (message: string) => {
 };
 
 const throwMissingProjectIdError = (): never => {
-  const message = "Welcome to Hexclave! It seems that you haven't provided a project ID. Please create a project on the Hexclave dashboard at https://app.hexclave.com and put it in the HEXCLAVE_PROJECT_ID environment variable.";
+  const message = deindent`
+    Welcome to Hexclave!
+    
+    It seems that you haven't provided a project ID.
+
+    ${envVars.NODE_ENV?.includes("dev") ? deindent`
+      You are running this app in development mode. Make sure that your start command is wrapped in a call to the Hexclave CLI: \`npx @hexclave/cli dev --config-file <file> -- <command>\`
+
+      Alternatively, you can also connect to a Cloud project's environment variables instead by creating a project on the Hexclave dashboard at https://app.hexclave.com and put its information in the HEXCLAVE_PROJECT_ID environment variable.
+    ` : envVars.NODE_ENV?.includes("prod") ? deindent`
+      It seems you are running a project in production. Please create a project on the Hexclave dashboard at https://app.hexclave.com and put it in the HEXCLAVE_PROJECT_ID environment variable.
+    ` : deindent`
+      - If you are running a development project and would like to connect the local Hexclave dashboard, wrap your start command in: \`npx @hexclave/cli dev --config-file <file> -- <command>\`
+
+      - If you are running a project in production and would like to connect to Hexclave Cloud, create a project on the Hexclave dashboard at https://app.hexclave.com and put its information in the HEXCLAVE_PROJECT_ID environment variable.
+    `}
+  `;
   showMissingConfigAlertInBrowser(message);
   return throwErr(new Error(message));
 };