π OpenHands: AI-Driven Development
fix(frontend): preserve returnTo through the onboarding interstitial (#14353)
chuckbutkusd04ddf6f8fbe
diff --git a/enterprise/server/routes/auth.py b/enterprise/server/routes/auth.pyindex dc3347eb1e..11f61e21f2 100644--- a/enterprise/server/routes/auth.py+++ b/enterprise/server/routes/auth.py@@ -5,7 +5,7 @@ import warningsfrom datetime import datetime, timedelta, timezonefrom types import MappingProxyTypefrom typing import Annotated, Optional, cast-from urllib.parse import quote, urlencode+from urllib.parse import parse_qs, quote, urlencode, urlparsefrom uuid import UUID as parse_uuidfrom fastapi import (@@ -586,7 +586,10 @@ async def keycloak_callback(# Only redirect to onboarding if user has a valid offline token,# otherwise they need to complete the Keycloak offline token flow firstif valid_offline_token and await _should_redirect_to_onboarding(user_id, user):- redirect_url = f'{web_url}/onboarding'+ # Preserve the user's originally requested destination as+ # ``?returnTo=...`` so the frontend ``OnboardingForm`` can+ # restore it after the user finishes the form.+ redirect_url = _build_onboarding_redirect(redirect_url, web_url)logger.info('Redirecting returning user to onboarding',extra={'user_id': user_id, 'deployment_mode': DEPLOYMENT_MODE},@@ -690,6 +693,97 @@ async def authenticate(request: Request):return response+def _extract_login_inner_return_to(relative_url: str) -> str | None:+ """Extract the inner ``returnTo`` from a ``/login?returnTo=...`` URL.++ Returns the decoded inner ``returnTo`` value, or ``None`` if+ ``relative_url`` is not a login URL or has no inner ``returnTo``.++ The OAuth flow's ``state`` is set to the full URL of the page that+ triggered the login (see ``generateAuthUrl`` in the frontend).+ For an unauthenticated deep-link visit, that page is itself+ ``/login?returnTo=<actual destination>``, so the OAuth callback's+ ``redirect_url`` ends up *wrapping* the user's true destination+ inside a login URL. Sending the user back through ``/login`` after+ onboarding works in principle (``LoginPage`` re-redirects authed+ users to its own ``returnTo``), but the round-trip adds extra+ state and is brittle when query-string layering goes wrong.++ Unwrapping here keeps the post-onboarding navigation a single+ direct step, e.g. ``/onboarding?returnTo=%2Fsettings%2Fuser``+ rather than the doubly-nested+ ``/onboarding?returnTo=%2Flogin%3FreturnTo%3D%252Fsettings...``.+ """+ parsed = urlparse(relative_url)+ if parsed.path != '/login':+ return None+ inner = parse_qs(parsed.query).get('returnTo')+ if not inner:+ return None+ value = inner[0]+ if not value.startswith('/'):+ return None+ return value+++def _build_onboarding_redirect(original_url: str, web_url: str) -> str:+ """Build the ``/onboarding`` redirect URL preserving ``returnTo``.++ The user's originally requested destination is preserved as a+ ``returnTo`` query parameter on ``/onboarding``.++ Without this, any deep link the user clicked while logged out+ (e.g. ``/conversations/abc?foo=bar``) is silently dropped at the+ onboarding interstitial because the OAuth callback would clobber+ its working ``redirect_url`` with a bare ``f'{web_url}/onboarding'``.+ The frontend ``OnboardingForm`` reads this ``returnTo`` query+ parameter and restores it after the user finishes the form.++ The trivial home-page case (``original_url`` empty, equal to+ ``web_url``, or pointing at ``web_url/``) returns the bare+ ``/onboarding`` URL to keep the URL bar clean β that is already+ the default landing page once onboarding completes.++ The ``returnTo`` value is always a *relative* path (``/foo?bar``)+ rather than an absolute URL: that keeps the URL short, avoids+ leaking the deployment origin into the browser bar a second time,+ and lets the frontend use ``navigate(returnTo)`` directly.++ When ``original_url`` is itself a ``/login?returnTo=...`` URL β+ which is the common case for unauthenticated deep-link visits,+ because the OAuth flow's ``state`` carries the full login page+ URL β the *inner* ``returnTo`` is extracted so the user lands at+ their real destination in a single navigation rather than+ bouncing through ``/login`` after onboarding.+ """+ onboarding_url = f'{web_url}/onboarding'+ if not original_url:+ return onboarding_url++ # Compute the path-and-query portion of the original URL. We try+ # to strip the deployment origin first so we end up with a+ # relative path; if the URL points at a different host we fall+ # back to the URL as-is. The ``OnboardingForm`` component's+ # ``sanitizeReturnTo`` helper rejects absolute/protocol-relative+ # URLs before use, so any unexpected absolute value here is safe.+ relative = original_url+ if web_url and original_url.startswith(web_url):+ relative = original_url[len(web_url) :] or '/'++ # If we ended up with a login-page URL, unwrap its inner+ # ``returnTo`` so post-onboarding navigation goes straight to the+ # user's real destination instead of bouncing through ``/login``.+ inner_return_to = _extract_login_inner_return_to(relative)+ if inner_return_to is not None:+ relative = inner_return_to++ # Skip the trivial home-page case to keep the URL clean.+ if relative in ('', '/'):+ return onboarding_url++ return f'{onboarding_url}?returnTo={quote(relative, safe="")}'++async def _should_redirect_to_onboarding(user_id: str, user: User) -> bool:"""Check if user should be redirected to onboarding after TOS acceptance.Backend always redirects applicable users to /onboarding.@@ -749,7 +843,10 @@ async def _get_post_auth_redirect('Redirecting user to onboarding',extra={'user_id': user_id, 'deployment_mode': DEPLOYMENT_MODE},)- return f'{web_url}/onboarding'+ # Preserve the user's originally requested destination as+ # ``?returnTo=...`` so the frontend ``OnboardingForm`` can+ # restore it after the user finishes the form.+ return _build_onboarding_redirect(default_url, web_url)return default_urldiff --git a/enterprise/tests/unit/server/routes/test_auth_onboarding.py b/enterprise/tests/unit/server/routes/test_auth_onboarding.pyindex d3464bd8dc..6199e195e7 100644--- a/enterprise/tests/unit/server/routes/test_auth_onboarding.py+++ b/enterprise/tests/unit/server/routes/test_auth_onboarding.py@@ -17,6 +17,7 @@ from fastapi.responses import JSONResponsefrom server.auth.saas_user_auth import SaasUserAuthfrom server.routes.auth import (OnboardingSubmission,+ _build_onboarding_redirect,_get_post_auth_redirect,_should_redirect_to_onboarding,complete_onboarding,@@ -237,6 +238,210 @@ class TestGetPostAuthRedirect:assert call_args[0][0] == 'Redirecting user to onboarding'assert call_args[1]['extra']['user_id'] == user_id+ @pytest.mark.asyncio+ async def test_preserves_deep_link_path_as_returnTo(self, mock_user):+ """Regression: deep-link path is preserved as ``returnTo``.++ When an onboarding-needing user originally requested a deep+ link (e.g. ``/conversations/abc``), the backend must redirect+ to ``/onboarding?returnTo=...`` so the frontend+ ``OnboardingForm`` can restore that destination after the+ user finishes the form. Without this, deep links clicked+ while logged out are silently dropped at the onboarding+ interstitial.+ """+ mock_user.onboarding_completed = False+ user_id = str(mock_user.id)++ with (+ patch('server.routes.auth.DEPLOYMENT_MODE', 'cloud'),+ patch(+ 'server.routes.auth.UserStore.get_user_by_id',+ new_callable=AsyncMock,+ return_value=mock_user,+ ),+ ):+ result = await _get_post_auth_redirect(+ user_id,+ 'https://example.com/conversations/abc',+ 'https://example.com',+ )++ assert result == (+ 'https://example.com/onboarding?returnTo=%2Fconversations%2Fabc'+ )++ @pytest.mark.asyncio+ async def test_preserves_query_string_as_returnTo(self, mock_user):+ """Regression: query-string destinations are preserved fully.++ Destinations like ``/conversations/abc?foo=bar`` must be+ preserved in the encoded ``returnTo`` rather than truncated.+ """+ mock_user.onboarding_completed = False+ user_id = str(mock_user.id)++ with (+ patch('server.routes.auth.DEPLOYMENT_MODE', 'cloud'),+ patch(+ 'server.routes.auth.UserStore.get_user_by_id',+ new_callable=AsyncMock,+ return_value=mock_user,+ ),+ ):+ result = await _get_post_auth_redirect(+ user_id,+ 'https://example.com/conversations/abc?foo=bar',+ 'https://example.com',+ )++ assert result == (+ 'https://example.com/onboarding'+ '?returnTo=%2Fconversations%2Fabc%3Ffoo%3Dbar'+ )+++# --- Tests for _build_onboarding_redirect ---+++class TestBuildOnboardingRedirect:+ """Tests for the ``_build_onboarding_redirect`` helper.++ These exercise the unit directly β the integration coverage+ through ``_get_post_auth_redirect`` lives in+ ``TestGetPostAuthRedirect`` above.+ """++ def test_strips_web_url_prefix_to_relative_path(self):+ result = _build_onboarding_redirect(+ 'https://example.com/foo/bar', 'https://example.com'+ )+ assert result == ('https://example.com/onboarding?returnTo=%2Ffoo%2Fbar')++ def test_preserves_query_string_in_returnTo(self):+ result = _build_onboarding_redirect(+ 'https://example.com/foo?bar=baz&qux=1', 'https://example.com'+ )+ assert result == (+ 'https://example.com/onboarding' '?returnTo=%2Ffoo%3Fbar%3Dbaz%26qux%3D1'+ )++ def test_skips_returnTo_for_bare_home_with_trailing_slash(self):+ # ``https://example.com/`` is the home page; appending a+ # ``returnTo=%2F`` would be noise since ``/`` is the default+ # post-onboarding landing page anyway.+ result = _build_onboarding_redirect(+ 'https://example.com/', 'https://example.com'+ )+ assert result == 'https://example.com/onboarding'++ def test_skips_returnTo_for_bare_home_without_trailing_slash(self):+ result = _build_onboarding_redirect(+ 'https://example.com', 'https://example.com'+ )+ assert result == 'https://example.com/onboarding'++ def test_skips_returnTo_when_original_url_is_empty(self):+ result = _build_onboarding_redirect('', 'https://example.com')+ assert result == 'https://example.com/onboarding'++ def test_passes_through_absolute_url_when_origin_does_not_match(self):+ # Defensive: if the original_url doesn't share the deployment+ # origin, the helper preserves it as-is so the frontend can+ # decide whether to navigate within the SPA or do a hard+ # window.location redirect.+ result = _build_onboarding_redirect(+ 'https://other.example.com/foo', 'https://example.com'+ )+ assert result == (+ 'https://example.com/onboarding'+ '?returnTo=https%3A%2F%2Fother.example.com%2Ffoo'+ )++ def test_unwraps_cross_origin_login_returnTo(self):+ """Cross-origin login URLs still have their inner ``returnTo`` extracted.++ ``_extract_login_inner_return_to`` matches on the path only+ (``parsed.path == '/login'``); it does not check the host. A+ login URL at a different origin therefore has its inner+ destination unwrapped to a safe relative path rather than being+ preserved as a cross-origin absolute URL.++ This differs from ``test_passes_through_absolute_url_when_origin_does_not_match``+ (non-login cross-origin path β absolute URL preserved as-is) and+ the behaviour is intentionally *safer*: the attacker-controlled+ origin is discarded and only the relative ``returnTo`` value from+ the query string is used.+ """+ result = _build_onboarding_redirect(+ 'https://other.example.com/login?returnTo=%2Ffoo', 'https://example.com'+ )+ assert result == 'https://example.com/onboarding?returnTo=%2Ffoo'++ def test_unwraps_login_returnTo_to_inner_destination(self):+ """Regression: login-wrapped destinations are unwrapped.++ An unauthenticated deep-link visit creates an OAuth ``state``+ that wraps the user's real destination inside a+ ``/login?returnTo=...`` URL. The onboarding redirect must+ unwrap that so the user lands directly at their destination+ after finishing onboarding instead of bouncing through+ ``/login`` (which adds round-trips and is brittle when+ query-string layering goes wrong).+ """+ result = _build_onboarding_redirect(+ 'https://example.com/login?returnTo=%2Fsettings%2Fuser'+ '&login_method=github',+ 'https://example.com',+ )+ assert result == (+ 'https://example.com/onboarding' '?returnTo=%2Fsettings%2Fuser'+ )++ def test_unwraps_login_returnTo_with_inner_query_string(self):+ """Inner destinations with their own query string survive unwrap.++ Destinations like ``/conversations/abc?foo=bar`` must keep+ their query string when the outer login URL is unwrapped.+ """+ result = _build_onboarding_redirect(+ 'https://example.com/login'+ '?returnTo=%2Fconversations%2Fabc%3Ffoo%3Dbar'+ '&login_method=github',+ 'https://example.com',+ )+ assert result == (+ 'https://example.com/onboarding'+ '?returnTo=%2Fconversations%2Fabc%3Ffoo%3Dbar'+ )++ def test_unwraps_login_returnTo_to_bare_home_skips_returnTo(self):+ """Home-page short-circuit applies after the unwrap step.++ If the unwrapped destination is the bare home page, the+ helper should still emit the clean ``/onboarding`` URL with+ no ``returnTo`` query parameter.+ """+ result = _build_onboarding_redirect(+ 'https://example.com/login?returnTo=%2F&login_method=github',+ 'https://example.com',+ )+ assert result == 'https://example.com/onboarding'++ def test_does_not_unwrap_non_login_path(self):+ """Non-login paths with a ``returnTo`` are preserved verbatim.++ Only ``/login`` URLs get the inner-returnTo unwrap; other+ paths that happen to carry a ``returnTo`` query parameter+ must be preserved as-is.+ """+ result = _build_onboarding_redirect(+ 'https://example.com/foo?returnTo=%2Fbar', 'https://example.com'+ )+ assert result == (+ 'https://example.com/onboarding' '?returnTo=%2Ffoo%3FreturnTo%3D%252Fbar'+ )+# --- Tests for /complete_onboarding endpoint ---diff --git a/frontend/__tests__/components/features/guards/onboarding-guard.test.tsx b/frontend/__tests__/components/features/guards/onboarding-guard.test.tsxnew file mode 100644index 0000000000..40b303258f--- /dev/null+++ b/frontend/__tests__/components/features/guards/onboarding-guard.test.tsx@@ -0,0 +1,151 @@+import { render } from "@testing-library/react";+import { createRoutesStub } from "react-router";+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { beforeEach, describe, expect, it, vi } from "vitest";+import { OnboardingGuard } from "#/components/features/guards/onboarding-guard";++const mockNavigate = vi.fn();++vi.mock("react-router", async (importOriginal) => {+ const original = await importOriginal<typeof import("react-router")>();+ return {+ ...original,+ useNavigate: () => mockNavigate,+ };+});++const mockUseConfig = vi.fn();+const mockUseOnboardingStatus = vi.fn();++vi.mock("#/hooks/query/use-config", () => ({+ useConfig: () => mockUseConfig(),+}));++vi.mock("#/hooks/query/use-onboarding-status", () => ({+ useOnboardingStatus: () => mockUseOnboardingStatus(),+}));++const renderGuardAt = (initialEntry: string) => {+ const queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ });++ const Stub = createRoutesStub([+ {+ path: "*",+ Component: () => (+ <OnboardingGuard>+ <div data-testid="children" />+ </OnboardingGuard>+ ),+ },+ ]);++ return render(+ <QueryClientProvider client={queryClient}>+ <Stub initialEntries={[initialEntry]} />+ </QueryClientProvider>,+ );+};++describe("OnboardingGuard returnTo preservation", () => {+ beforeEach(() => {+ mockNavigate.mockReset();+ mockUseConfig.mockReturnValue({+ data: { feature_flags: { enable_onboarding: true } },+ });+ mockUseOnboardingStatus.mockReturnValue({+ data: { should_complete_onboarding: true },+ isLoading: false,+ });+ });++ it("preserves the originally requested path as a returnTo query parameter", async () => {+ renderGuardAt("/conversations/abc-123");++ await vi.waitFor(() => {+ expect(mockNavigate).toHaveBeenCalledWith(+ `/onboarding?returnTo=${encodeURIComponent("/conversations/abc-123")}`,+ { replace: true },+ );+ });+ });++ it("preserves search params alongside the path in returnTo", async () => {+ renderGuardAt("/conversations/abc?foo=bar&baz=qux");++ await vi.waitFor(() => {+ expect(mockNavigate).toHaveBeenCalledWith(+ `/onboarding?returnTo=${encodeURIComponent("/conversations/abc?foo=bar&baz=qux")}`,+ { replace: true },+ );+ });+ });++ it("does not double-encode pre-encoded characters in search params", async () => {+ // ``search`` from useLocation() is already percent-encoded. Without+ // decoding it first, ``encodeURIComponent`` would re-encode the ``%``+ // as ``%25``, causing double-encoding (e.g. ``%20`` β ``%2520``).+ // With the fix, ``%20`` in the original search is decoded to a space+ // and then re-encoded once, yielding ``%20`` (not ``%2520``) in the+ // ``returnTo`` parameter.+ renderGuardAt("/conversations/abc?tab=user%20profile");++ await vi.waitFor(() => {+ expect(mockNavigate).toHaveBeenCalledWith(+ `/onboarding?returnTo=${encodeURIComponent("/conversations/abc?tab=user profile")}`,+ { replace: true },+ );+ });+ });++ it("does not append a returnTo when the originally requested path is /", async () => {+ renderGuardAt("/");++ await vi.waitFor(() => {+ expect(mockNavigate).toHaveBeenCalledWith("/onboarding", {+ replace: true,+ });+ });+ });++ it("does not redirect when already on /onboarding", async () => {+ renderGuardAt("/onboarding");++ // Allow the effect to settle.+ await new Promise((resolve) => {+ setTimeout(resolve, 0);+ });++ expect(mockNavigate).not.toHaveBeenCalled();+ });++ it("does not redirect when the enable_onboarding feature flag is off", async () => {+ mockUseConfig.mockReturnValue({+ data: { feature_flags: { enable_onboarding: false } },+ });++ renderGuardAt("/conversations/abc");++ await new Promise((resolve) => {+ setTimeout(resolve, 0);+ });++ expect(mockNavigate).not.toHaveBeenCalled();+ });++ it("does not redirect when onboarding is already complete", async () => {+ mockUseOnboardingStatus.mockReturnValue({+ data: { should_complete_onboarding: false },+ isLoading: false,+ });++ renderGuardAt("/conversations/abc");++ await new Promise((resolve) => {+ setTimeout(resolve, 0);+ });++ expect(mockNavigate).not.toHaveBeenCalled();+ });+});diff --git a/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsx b/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsxindex 9e2c380bd7..90ca2d0e5a 100644--- a/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsx+++ b/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsx@@ -5,7 +5,10 @@ import { beforeEach, describe, expect, it, vi } from "vitest";import { QueryClient, QueryClientProvider } from "@tanstack/react-query";import { I18nextProvider } from "react-i18next";import i18n from "i18next";-import OnboardingForm, { clientLoader } from "#/routes/onboarding-form";+import OnboardingForm, {+ clientLoader,+ sanitizeReturnTo,+} from "#/routes/onboarding-form";import AuthService from "#/api/auth-service/auth-service.api";import { onboardingService } from "#/api/onboarding-service/onboarding-service.api";@@ -14,7 +17,9 @@ const mockNavigate = vi.fn();const mockUseMe = vi.fn();// Loader data set in beforeEach for each test suite-let loaderData: { config: { app_mode: string; feature_flags: { deployment_mode: string } } };+let loaderData: {+ config: { app_mode: string; feature_flags: { deployment_mode: string } };+};vi.mock("react-router", async (importOriginal) => {const original = await importOriginal<typeof import("react-router")>();@@ -51,9 +56,7 @@ vi.mock("#/api/option-service/option-service.api", () => ({},}));---const renderOnboardingForm = async () => {+const renderOnboardingForm = async (initialEntry: string = "/") => {const queryClient = new QueryClient({defaultOptions: { queries: { retry: false } },});@@ -69,7 +72,7 @@ const renderOnboardingForm = async () => {const result = render(<I18nextProvider i18n={i18n}><QueryClientProvider client={queryClient}>- <RouterStub initialEntries={["/"]} />+ <RouterStub initialEntries={[initialEntry]} /></QueryClientProvider></I18nextProvider>,);@@ -177,13 +180,15 @@ describe("OnboardingForm - Cloud Mode", () => {await user.click(screen.getByRole("button", { name: /finish/i }));expect(mockMutate).toHaveBeenCalledTimes(1);- expect(mockMutate).toHaveBeenCalledWith({- selections: {- org_size: "org_2_10",- use_case: ["new_features"],- role: "software_engineer",- },- });+ expect(mockMutate).toHaveBeenCalledWith(+ expect.objectContaining({+ selections: {+ org_size: "org_2_10",+ use_case: ["new_features"],+ role: "software_engineer",+ },+ }),+ );});it("should render 5 options on step 1 (org size question)", async () => {@@ -214,13 +219,15 @@ describe("OnboardingForm - Cloud Mode", () => {await user.click(screen.getByRole("button", { name: /finish/i }));// Verify all selections were preserved- expect(mockMutate).toHaveBeenCalledWith({- selections: {- org_size: "solo",- use_case: ["fixing_bugs"],- role: "cto_founder",- },- });+ expect(mockMutate).toHaveBeenCalledWith(+ expect.objectContaining({+ selections: {+ org_size: "solo",+ use_case: ["fixing_bugs"],+ role: "cto_founder",+ },+ }),+ );});it("should allow selecting multiple options on multi-select steps", async () => {@@ -241,13 +248,15 @@ describe("OnboardingForm - Cloud Mode", () => {await user.click(screen.getByTestId("step-option-software_engineer"));await user.click(screen.getByRole("button", { name: /finish/i }));- expect(mockMutate).toHaveBeenCalledWith({- selections: {- org_size: "solo",- use_case: ["new_features", "fixing_bugs", "refactoring"],- role: "software_engineer",- },- });+ expect(mockMutate).toHaveBeenCalledWith(+ expect.objectContaining({+ selections: {+ org_size: "solo",+ use_case: ["new_features", "fixing_bugs", "refactoring"],+ role: "software_engineer",+ },+ }),+ );});it("should allow deselecting options on multi-select steps", async () => {@@ -269,13 +278,15 @@ describe("OnboardingForm - Cloud Mode", () => {await user.click(screen.getByTestId("step-option-software_engineer"));await user.click(screen.getByRole("button", { name: /finish/i }));- expect(mockMutate).toHaveBeenCalledWith({- selections: {- org_size: "solo",- use_case: ["fixing_bugs"],- role: "software_engineer",- },- });+ expect(mockMutate).toHaveBeenCalledWith(+ expect.objectContaining({+ selections: {+ org_size: "solo",+ use_case: ["fixing_bugs"],+ role: "software_engineer",+ },+ }),+ );});it("should show all progress bars filled on the last step", async () => {@@ -397,14 +408,16 @@ describe("OnboardingForm - Self-Hosted Mode", () => {await user.click(screen.getByRole("button", { name: /finish/i }));expect(mockMutate).toHaveBeenCalledTimes(1);- expect(mockMutate).toHaveBeenCalledWith({- selections: {- org_name: "Acme Corp",- org_domain: "acme.com",- org_size: "org_2_10",- use_case: ["new_features"],- },- });+ expect(mockMutate).toHaveBeenCalledWith(+ expect.objectContaining({+ selections: {+ org_name: "Acme Corp",+ org_domain: "acme.com",+ org_size: "org_2_10",+ use_case: ["new_features"],+ },+ }),+ );});it("should show all 3 progress bars filled on the last step", async () => {@@ -446,7 +459,6 @@ describe("OnboardingForm - Self-Hosted Mode", () => {const nextButton = screen.getByRole("button", { name: /next/i });expect(nextButton).not.toBeDisabled();});-});describe("OnboardingForm - redirect when already onboarded", () => {@@ -481,9 +493,98 @@ describe("OnboardingForm - redirect when already onboarded", () => {expect(mockNavigate).toHaveBeenCalledWith("/", { replace: true });});});++ it("should restore the returnTo destination when onboarding is already complete", async () => {+ // Regression: a stale ``/onboarding`` link must still respect+ // a ``returnTo`` query param so post-login deep links survive.+ vi.spyOn(onboardingService, "getStatus").mockResolvedValue({+ should_complete_onboarding: false,+ });++ await renderOnboardingForm(+ `/?returnTo=${encodeURIComponent("/conversations/abc?foo=bar")}`,+ );++ await vi.waitFor(() => {+ expect(mockNavigate).toHaveBeenCalledWith("/conversations/abc?foo=bar", {+ replace: true,+ });+ });+ expect(mockNavigate).not.toHaveBeenCalledWith("/", { replace: true });+ });++ it("should reject absolute URL returnTo and redirect to / when onboarding is already complete", async () => {+ // Security: a hand-crafted ``?returnTo=https://evil.example`` must+ // never turn the component redirect into an open-redirect vector.+ vi.spyOn(onboardingService, "getStatus").mockResolvedValue({+ should_complete_onboarding: false,+ });++ await renderOnboardingForm(+ `/?returnTo=${encodeURIComponent("https://evil.example.com/pwn")}`,+ );++ await vi.waitFor(() => {+ expect(mockNavigate).toHaveBeenCalledWith("/", { replace: true });+ });+ });++ it("should reject protocol-relative returnTo and redirect to / when onboarding is already complete", async () => {+ // Security: protocol-relative URLs (``//evil.example.com``) are+ // also open-redirect vectors and must be rejected.+ vi.spyOn(onboardingService, "getStatus").mockResolvedValue({+ should_complete_onboarding: false,+ });++ await renderOnboardingForm(+ `/?returnTo=${encodeURIComponent("//evil.example.com/pwn")}`,+ );++ await vi.waitFor(() => {+ expect(mockNavigate).toHaveBeenCalledWith("/", { replace: true });+ });+ });++ it("should forward returnTo to submitOnboarding so the post-submit redirect respects it", async () => {+ // Regression: ``OnboardingGuard`` saves the originally requested+ // URL as ``?returnTo=...``. ``OnboardingForm`` must thread that+ // value through the submit mutation so the post-submit fallback+ // (when the server response has no ``redirect_url``) sends the+ // user back to where they started.+ const user = userEvent.setup();+ await renderOnboardingForm(+ `/?returnTo=${encodeURIComponent("/conversations/abc?foo=bar")}`,+ );++ // Step 1 - org size+ await user.click(screen.getByTestId("step-option-solo"));+ await user.click(screen.getByRole("button", { name: /next/i }));++ // Step 2 - use case+ await user.click(screen.getByTestId("step-option-new_features"));+ await user.click(screen.getByRole("button", { name: /next/i }));++ // Step 3 - role+ await user.click(screen.getByTestId("step-option-software_engineer"));+ await user.click(screen.getByRole("button", { name: /finish/i }));++ expect(mockMutate).toHaveBeenCalledWith(+ expect.objectContaining({+ returnTo: "/conversations/abc?foo=bar",+ }),+ );+ });});describe("onboarding-form clientLoader", () => {+ // The loader takes a ``{ request }`` arg from react-router. Most of+ // the existing tests don't care about the URL, so build a default+ // request pointing at bare ``/onboarding`` and let returnTo-aware+ // tests override it.+ const makeArgs = (url = "https://app.example.com/onboarding") => ({+ request: new Request(url),+ });+beforeEach(() => {mockQueryClientGetData.mockReset();mockQueryClientSetData.mockReset();@@ -498,7 +599,7 @@ describe("onboarding-form clientLoader", () => {};mockQueryClientGetData.mockReturnValue(saasConfig);- const result = await clientLoader();+ const result = await clientLoader(makeArgs());expect(result).toBeDefined();expect((result as Response).status).toBe(302);@@ -512,7 +613,7 @@ describe("onboarding-form clientLoader", () => {};mockQueryClientGetData.mockReturnValue(ossConfig);- const result = await clientLoader();+ const result = await clientLoader(makeArgs());expect(result).toBeDefined();expect((result as Response).status).toBe(302);@@ -526,7 +627,7 @@ describe("onboarding-form clientLoader", () => {};mockQueryClientGetData.mockReturnValue(undefinedConfig);- const result = await clientLoader();+ const result = await clientLoader(makeArgs());expect(result).toBeDefined();expect((result as Response).status).toBe(302);@@ -537,7 +638,7 @@ describe("onboarding-form clientLoader", () => {mockQueryClientGetData.mockReturnValue(null);mockGetConfig.mockResolvedValue(null);- const result = await clientLoader();+ const result = await clientLoader(makeArgs());expect(result).toBeDefined();expect((result as Response).status).toBe(302);@@ -551,7 +652,7 @@ describe("onboarding-form clientLoader", () => {};mockQueryClientGetData.mockReturnValue(saasCloudConfig);- const result = await clientLoader();+ const result = await clientLoader(makeArgs());expect(result).toEqual({ config: saasCloudConfig });});@@ -559,16 +660,116 @@ describe("onboarding-form clientLoader", () => {it("should allow access and return config when app_mode is saas with self_hosted deployment and enable_onboarding is true", async () => {const saasSelfHostedConfig = {app_mode: "saas",- feature_flags: { deployment_mode: "self_hosted", enable_onboarding: true },+ feature_flags: {+ deployment_mode: "self_hosted",+ enable_onboarding: true,+ },};mockQueryClientGetData.mockReturnValue(saasSelfHostedConfig);- const result = await clientLoader();+ const result = await clientLoader(makeArgs());expect(result).toEqual({ config: saasSelfHostedConfig });});});+ describe("returnTo handling on redirect", () => {+ // The frontend can disagree with the backend about whether+ // onboarding applies (e.g. the backend gates on+ // ``DEPLOYMENT_MODE='cloud'`` while the frontend gates on+ // ``feature_flags.enable_onboarding``). When the frontend+ // redirects users away from /onboarding because the flag is+ // off, it must still honor the ``?returnTo=`` query parameter+ // so deep links survive the disagreement.+ it("should honor returnTo when enable_onboarding is false", async () => {+ const saasConfig = {+ app_mode: "saas",+ feature_flags: { deployment_mode: "cloud", enable_onboarding: false },+ };+ mockQueryClientGetData.mockReturnValue(saasConfig);++ const result = await clientLoader(+ makeArgs(+ "https://app.example.com/onboarding?returnTo=%2Fsettings%2Fuser",+ ),+ );++ expect((result as Response).status).toBe(302);+ expect((result as Response).headers.get("Location")).toBe(+ "/settings/user",+ );+ });++ it("should honor returnTo with query string when app_mode is oss", async () => {+ const ossConfig = {+ app_mode: "oss",+ feature_flags: { deployment_mode: undefined, enable_onboarding: true },+ };+ mockQueryClientGetData.mockReturnValue(ossConfig);++ const result = await clientLoader(+ makeArgs(+ "https://app.example.com/onboarding" ++ "?returnTo=%2Fconversations%2Fabc%3Ffoo%3Dbar",+ ),+ );++ expect((result as Response).headers.get("Location")).toBe(+ "/conversations/abc?foo=bar",+ );+ });++ it("should reject absolute URL returnTo and fall back to /", async () => {+ // Safety: never let a hand-crafted ``?returnTo=https://evil.example``+ // turn the loader's redirect into an open-redirect vector.+ const ossConfig = {+ app_mode: "oss",+ feature_flags: { deployment_mode: undefined, enable_onboarding: true },+ };+ mockQueryClientGetData.mockReturnValue(ossConfig);++ const result = await clientLoader(+ makeArgs(+ "https://app.example.com/onboarding" ++ "?returnTo=https%3A%2F%2Fevil.example.com%2Fpwn",+ ),+ );++ expect((result as Response).headers.get("Location")).toBe("/");+ });++ it("should reject protocol-relative returnTo and fall back to /", async () => {+ const ossConfig = {+ app_mode: "oss",+ feature_flags: { deployment_mode: undefined, enable_onboarding: true },+ };+ mockQueryClientGetData.mockReturnValue(ossConfig);++ const result = await clientLoader(+ makeArgs(+ "https://app.example.com/onboarding" ++ "?returnTo=%2F%2Fevil.example.com%2Fpwn",+ ),+ );++ expect((result as Response).headers.get("Location")).toBe("/");+ });++ it("should fall back to / when returnTo is missing", async () => {+ const ossConfig = {+ app_mode: "oss",+ feature_flags: { deployment_mode: undefined, enable_onboarding: true },+ };+ mockQueryClientGetData.mockReturnValue(ossConfig);++ const result = await clientLoader(+ makeArgs("https://app.example.com/onboarding"),+ );++ expect((result as Response).headers.get("Location")).toBe("/");+ });+ });+describe("config fetching", () => {it("should use cached config from queryClient when available", async () => {const cachedConfig = {@@ -577,9 +778,11 @@ describe("onboarding-form clientLoader", () => {};mockQueryClientGetData.mockReturnValue(cachedConfig);- await clientLoader();+ await clientLoader(makeArgs());- expect(mockQueryClientGetData).toHaveBeenCalledWith(["web-client-config"]);+ expect(mockQueryClientGetData).toHaveBeenCalledWith([+ "web-client-config",+ ]);expect(mockGetConfig).not.toHaveBeenCalled();});@@ -591,7 +794,7 @@ describe("onboarding-form clientLoader", () => {mockQueryClientGetData.mockReturnValue(null);mockGetConfig.mockResolvedValue(fetchedConfig);- const result = await clientLoader();+ const result = await clientLoader(makeArgs());expect(mockGetConfig).toHaveBeenCalled();expect(mockQueryClientSetData).toHaveBeenCalledWith(@@ -602,3 +805,39 @@ describe("onboarding-form clientLoader", () => {});});});++describe("sanitizeReturnTo", () => {+ it("should return / for null", () => {+ expect(sanitizeReturnTo(null)).toBe("/");+ });++ it("should return / for empty string", () => {+ expect(sanitizeReturnTo("")).toBe("/");+ });++ it("should allow same-origin absolute paths", () => {+ expect(sanitizeReturnTo("/conversations/abc")).toBe("/conversations/abc");+ });++ it("should allow paths with query strings", () => {+ expect(sanitizeReturnTo("/conversations/abc?foo=bar")).toBe(+ "/conversations/abc?foo=bar",+ );+ });++ it("should prepend / to relative paths that lack one", () => {+ expect(sanitizeReturnTo("conversations/abc")).toBe("/conversations/abc");+ });++ it("should reject http:// URLs and fall back to /", () => {+ expect(sanitizeReturnTo("http://evil.example.com/pwn")).toBe("/");+ });++ it("should reject https:// URLs and fall back to /", () => {+ expect(sanitizeReturnTo("https://evil.example.com/pwn")).toBe("/");+ });++ it("should reject protocol-relative URLs and fall back to /", () => {+ expect(sanitizeReturnTo("//evil.example.com/pwn")).toBe("/");+ });+});diff --git a/frontend/src/components/features/guards/onboarding-guard.tsx b/frontend/src/components/features/guards/onboarding-guard.tsxindex 4f00bf8e97..d140c6e015 100644--- a/frontend/src/components/features/guards/onboarding-guard.tsx+++ b/frontend/src/components/features/guards/onboarding-guard.tsx@@ -6,12 +6,19 @@ import { useConfig } from "#/hooks/query/use-config";/*** Forces SaaS users with incomplete onboarding to /onboarding before they can* access any protected route. Mirrors EmailVerificationGuard.+ *+ * The originally requested URL is preserved as a ``returnTo`` query+ * parameter on ``/onboarding`` so it can be restored once the user+ * completes the onboarding flow. Without this, post-login deep links+ * (set up by ``root-layout.tsx`` as ``/login?returnTo=...``) get+ * dropped at the onboarding interstitial and the user always lands+ * back on ``/``.*/export function OnboardingGuard({ children }: { children: React.ReactNode }) {const { data, isLoading } = useOnboardingStatus();const { data: config } = useConfig();const navigate = useNavigate();- const { pathname } = useLocation();+ const { pathname, search } = useLocation();React.useEffect(() => {if (isLoading) return;@@ -21,13 +28,33 @@ export function OnboardingGuard({ children }: { children: React.ReactNode }) {data?.should_complete_onboarding &&pathname !== "/onboarding") {- navigate("/onboarding", { replace: true });+ // Preserve the user's originally requested URL (path + query)+ // so OnboardingForm can restore it after the user finishes.+ // Skip the trivial ``/`` case to keep the URL clean β that is+ // already the default landing page after onboarding.+ let destination = "/onboarding";+ if (pathname !== "/") {+ // Decode ``search`` first so already-encoded characters (e.g.+ // ``%20``) are not double-encoded by ``encodeURIComponent``.+ // The try/catch handles malformed percent-encoding sequences by+ // falling back to the raw ``search`` string.+ let decodedSearch: string;+ try {+ decodedSearch = search ? decodeURIComponent(search) : "";+ } catch {+ decodedSearch = search;+ }+ const returnTo = `${pathname}${decodedSearch}`;+ destination = `/onboarding?returnTo=${encodeURIComponent(returnTo)}`;+ }+ navigate(destination, { replace: true });}}, [config?.feature_flags?.enable_onboarding,data?.should_complete_onboarding,isLoading,pathname,+ search,navigate,]);diff --git a/frontend/src/hooks/mutation/use-submit-onboarding.ts b/frontend/src/hooks/mutation/use-submit-onboarding.tsindex ec7d132ab9..6f31311d30 100644--- a/frontend/src/hooks/mutation/use-submit-onboarding.ts+++ b/frontend/src/hooks/mutation/use-submit-onboarding.ts@@ -6,6 +6,13 @@ import { displayErrorToast } from "#/utils/custom-toast-handlers";type SubmitOnboardingArgs = {selections: Record<string, string | string[]>;+ /**+ * Fallback destination to navigate to when the server response does+ * not include a ``redirect_url``. ``OnboardingForm`` passes the+ * caller's ``returnTo`` here so deep links survive the onboarding+ * interstitial. Defaults to ``/`` when omitted.+ */+ returnTo?: string;};interface OnboardingResponse {@@ -25,11 +32,11 @@ export const useSubmitOnboarding = () => {);return data;},- onSuccess: (data) => {+ onSuccess: (data, { returnTo }) => {queryClient.invalidateQueries({ queryKey: SETTINGS_QUERY_KEYS.all });queryClient.invalidateQueries({ queryKey: ["onboarding-status"] });- const finalRedirectUrl = data.redirect_url || "/";+ const finalRedirectUrl = data.redirect_url || returnTo || "/";// Check if the redirect URL is an external URL (starts with http or https)if (finalRedirectUrl.startsWith("http://") ||diff --git a/frontend/src/routes/onboarding-form.tsx b/frontend/src/routes/onboarding-form.tsxindex eef9bb9b4b..880368b009 100644--- a/frontend/src/routes/onboarding-form.tsx+++ b/frontend/src/routes/onboarding-form.tsx@@ -1,6 +1,11 @@import React from "react";import { useTranslation } from "react-i18next";-import { useNavigate, redirect, useLoaderData } from "react-router";+import {+ useNavigate,+ redirect,+ useLoaderData,+ useSearchParams,+} from "react-router";import StepHeader from "#/components/features/onboarding/step-header";import { StepContent } from "#/components/features/onboarding/step-content";import { BrandButton } from "#/components/features/settings/brand-button";@@ -21,22 +26,68 @@ import {import { queryClient } from "#/query-client-config";import OptionService from "#/api/option-service/option-service.api";-export const clientLoader = async () => {+/**+ * Sanitize a raw ``returnTo`` value, returning a safe same-origin path.+ *+ * Absolute URLs and protocol-relative URLs fall back to ``"/"`` to+ * prevent open-redirect attacks. Relative paths that don't start with+ * ``"/"`` are prepended with one.+ */+export function sanitizeReturnTo(raw: string | null): string {+ if (!raw) return "/";+ // Same-origin paths only β reject protocol-bearing or+ // protocol-relative targets.+ if (+ raw.startsWith("http://") ||+ raw.startsWith("https://") ||+ raw.startsWith("//")+ ) {+ return "/";+ }+ return raw.startsWith("/") ? raw : `/${raw}`;+}++/**+ * Compute a safe redirect target from the URL's ``returnTo`` query+ * parameter, defaulting to ``"/"``.+ *+ * This loader intentionally redirects same-origin only β absolute URLs+ * are dropped to ``"/"`` rather than being followed, since the loader+ * This loader intentionally redirects to same-origin paths only. Absolute+ * URLs are silently dropped to "/" because a loader's `redirect()` performs+ * a client-side navigation β following an external URL would break the SPA.+ * URL here would break the SPA.+ */+function safeReturnToFromRequest(request: Request): string {+ const url = new URL(request.url);+ return sanitizeReturnTo(url.searchParams.get("returnTo"));+}++export const clientLoader = async ({ request }: { request: Request }) => {let config = queryClient.getQueryData<WebClientConfig>(["web-client-config"]);if (!config) {config = await OptionService.getConfig();queryClient.setQueryData<WebClientConfig>(["web-client-config"], config);}+ // The deployment's frontend may have ``enable_onboarding=false`` or+ // a non-SaaS ``app_mode`` even when the backend OAuth callback has+ // just sent the user here (the backend gates on ``DEPLOYMENT_MODE``,+ // not on the frontend feature flag, so the two can disagree). When+ // we redirect away in those cases, honor the user's deep-link+ // ``?returnTo=`` so they don't lose their original destination at+ // the onboarding interstitial.+ const fallback = safeReturnToFromRequest(request);+// Check server feature flag to block accessif (!config?.feature_flags?.enable_onboarding) {- return redirect("/");+ return redirect(fallback);}// Only allow access to onboarding for SaaS mode (cloud or self-hosted)// OSS users should never reach /onboardingif (config?.app_mode !== "saas") {- return redirect("/");+ return redirect(fallback);}return { config };@@ -85,6 +136,12 @@ function OnboardingForm() {const navigate = useNavigate();const loaderData = useLoaderData<typeof clientLoader>();const config = loaderData?.config;+ const [searchParams] = useSearchParams();+ // ``OnboardingGuard`` forwards the user's originally requested URL+ // here so we can restore it after they finish the form. Sanitize to+ // prevent open-redirect attacks β absolute/protocol-relative URLs+ // fall back to ``"/"``.+ const returnTo = sanitizeReturnTo(searchParams.get("returnTo"));const { data: onboardingStatus, isLoading: isOnboardingStatusLoading } =useOnboardingStatus();const { mutate: submitOnboarding } = useSubmitOnboarding();@@ -92,12 +149,17 @@ function OnboardingForm() {React.useEffect(() => {if (isOnboardingStatusLoading) return;if (onboardingStatus?.should_complete_onboarding === false) {- navigate("/", { replace: true });+ // Honor returnTo if the user already completed onboarding so a+ // stale ``/onboarding`` link still respects their deep-link+ // destination. ``returnTo`` is already sanitized above so it is+ // always a safe same-origin path.+ navigate(returnTo, { replace: true });}}, [onboardingStatus?.should_complete_onboarding,isOnboardingStatusLoading,navigate,+ returnTo,]);const onboardingAppMode: OnboardingAppMode = getOnboardingAppMode(@@ -181,7 +243,7 @@ function OnboardingForm() {const handleNext = () => {if (isLastStep) {- submitOnboarding({ selections: answers });+ submitOnboarding({ selections: answers, returnTo });} else {setCurrentStepIndex((prev) => prev + 1);}