π OpenHands: AI-Driven Development
fix: enforce onboarding completion on every navigation (#14142)
Hiep Leb41dd2ba8b1a
diff --git a/enterprise/server/routes/auth.py b/enterprise/server/routes/auth.pyindex 4d7e2dbc1b..a71b6cd10b 100644--- a/enterprise/server/routes/auth.py+++ b/enterprise/server/routes/auth.py@@ -703,6 +703,41 @@ async def accept_tos(request: Request):return response+@api_router.get('/onboarding_status')+async def onboarding_status(request: Request):+ """Return whether the current user must still complete onboarding.++ Kept as a dedicated endpoint instead of riding on ``GET /api/v1/settings``+ (the natural home for fields like ``email_verified``) because the settings+ response is heavyweight: ``SaasSettingsStore.load`` joins User, Org, and+ OrgMember rows and deep-merges the org-level and member-level+ ``agent_settings`` before returning. Onboarding gating runs on every+ protected-route navigation, so we need a lightweight read of a single+ boolean rather than paying for the full settings aggregation.+ """+ user_auth = cast(SaasUserAuth, await get_user_auth(request))+ user_id = await user_auth.get_user_id()++ if not user_id:+ return JSONResponse(+ status_code=status.HTTP_401_UNAUTHORIZED,+ content={'error': 'User is not authenticated'},+ )++ user = await UserStore.get_user_by_id(user_id)+ if not user:+ return JSONResponse(+ status_code=status.HTTP_404_NOT_FOUND,+ content={'error': 'User not found'},+ )++ should_complete = await _should_redirect_to_onboarding(user_id, user)+ return JSONResponse(+ status_code=status.HTTP_200_OK,+ content={'should_complete_onboarding': should_complete},+ )++@api_router.post('/complete_onboarding')async def complete_onboarding(request: Request):"""Mark onboarding as completed for the current user."""diff --git a/enterprise/tests/unit/server/routes/test_auth_onboarding.py b/enterprise/tests/unit/server/routes/test_auth_onboarding.pyindex 76e29a9d0c..28d77f94d3 100644--- a/enterprise/tests/unit/server/routes/test_auth_onboarding.py+++ b/enterprise/tests/unit/server/routes/test_auth_onboarding.py@@ -4,8 +4,10 @@ Tests for:- _should_redirect_to_onboarding() function- _get_post_auth_redirect() function- /complete_onboarding endpoint+- /onboarding_status endpoint"""+import jsonimport uuidfrom unittest.mock import AsyncMock, MagicMock, patch@@ -17,6 +19,7 @@ from server.routes.auth import (_get_post_auth_redirect,_should_redirect_to_onboarding,complete_onboarding,+ onboarding_status,)from storage.user import User@@ -328,3 +331,78 @@ class TestCompleteOnboardingEndpoint:await complete_onboarding(mock_request)mock_mark_completed.assert_called_once_with(user_id)+++class TestOnboardingStatusEndpoint:+ """Tests for the /onboarding_status API endpoint."""++ @pytest.mark.asyncio+ async def test_returns_401_when_not_authenticated(self, mock_request):+ """Unauthenticated requests return 401."""+ mock_user_auth = MagicMock(spec=SaasUserAuth)+ mock_user_auth.get_user_id = AsyncMock(return_value=None)++ with patch(+ 'server.routes.auth.get_user_auth',+ new_callable=AsyncMock,+ return_value=mock_user_auth,+ ):+ result = await onboarding_status(mock_request)++ assert isinstance(result, JSONResponse)+ assert result.status_code == status.HTTP_401_UNAUTHORIZED++ @pytest.mark.asyncio+ async def test_returns_true_for_new_cloud_user(self, mock_request, mock_user):+ """A cloud user whose onboarding is incomplete should be told to complete it."""+ user_id = str(uuid.uuid4())+ mock_user.onboarding_completed = False+ mock_user_auth = MagicMock(spec=SaasUserAuth)+ mock_user_auth.get_user_id = AsyncMock(return_value=user_id)++ with (+ patch(+ 'server.routes.auth.get_user_auth',+ new_callable=AsyncMock,+ return_value=mock_user_auth,+ ),+ patch(+ 'server.routes.auth.UserStore.get_user_by_id',+ new_callable=AsyncMock,+ return_value=mock_user,+ ),+ patch('server.routes.auth.DEPLOYMENT_MODE', 'cloud'),+ ):+ result = await onboarding_status(mock_request)++ assert isinstance(result, JSONResponse)+ assert result.status_code == status.HTTP_200_OK+ body = json.loads(result.body)+ assert body == {'should_complete_onboarding': True}++ @pytest.mark.asyncio+ async def test_returns_false_for_completed_user(self, mock_request, mock_user):+ """A user who already completed onboarding should not be told to complete it."""+ user_id = str(uuid.uuid4())+ mock_user.onboarding_completed = True+ mock_user_auth = MagicMock(spec=SaasUserAuth)+ mock_user_auth.get_user_id = AsyncMock(return_value=user_id)++ with (+ patch(+ 'server.routes.auth.get_user_auth',+ new_callable=AsyncMock,+ return_value=mock_user_auth,+ ),+ patch(+ 'server.routes.auth.UserStore.get_user_by_id',+ new_callable=AsyncMock,+ return_value=mock_user,+ ),+ ):+ result = await onboarding_status(mock_request)++ assert isinstance(result, JSONResponse)+ assert result.status_code == status.HTTP_200_OK+ body = json.loads(result.body)+ assert body == {'should_complete_onboarding': False}diff --git a/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsx b/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsxindex e024bcef84..529de4f97d 100644--- a/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsx+++ b/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsx@@ -6,6 +6,8 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";import { I18nextProvider } from "react-i18next";import i18n from "i18next";import OnboardingForm, { clientLoader } from "#/routes/onboarding-form";+import AuthService from "#/api/auth-service/auth-service.api";+import { onboardingService } from "#/api/onboarding-service/onboarding-service.api";const mockMutate = vi.fn();const mockNavigate = vi.fn();@@ -555,6 +557,40 @@ describe("OnboardingForm - Self-Hosted Mode", () => {});});+describe("OnboardingForm - redirect when already onboarded", () => {+ beforeEach(() => {+ mockMutate.mockClear();+ mockNavigate.mockClear();+ mockUseMe.mockReturnValue({ data: { role: "member" } });+ loaderData = {+ config: {+ app_mode: "saas",+ feature_flags: { deployment_mode: "cloud" },+ },+ };+ mockGetConfig.mockResolvedValue({+ app_mode: "saas",+ feature_flags: { deployment_mode: "cloud" },+ });+ vi.spyOn(AuthService, "authenticate").mockResolvedValue(true);+ });++ it("should navigate to / when the backend reports onboarding is already complete", async () => {+ // Arrange+ vi.spyOn(onboardingService, "getStatus").mockResolvedValue({+ should_complete_onboarding: false,+ });++ // Act+ await renderOnboardingForm();++ // Assert+ await vi.waitFor(() => {+ expect(mockNavigate).toHaveBeenCalledWith("/", { replace: true });+ });+ });+});+describe("onboarding-form clientLoader", () => {beforeEach(() => {mockQueryClientGetData.mockReset();diff --git a/frontend/__tests__/hooks/use-is-on-intermediate-page.test.ts b/frontend/__tests__/hooks/use-is-on-intermediate-page.test.tsindex 2c9ecdca18..888b82bbe3 100644--- a/frontend/__tests__/hooks/use-is-on-intermediate-page.test.ts+++ b/frontend/__tests__/hooks/use-is-on-intermediate-page.test.ts@@ -27,12 +27,6 @@ describe("useIsOnIntermediatePage", () => {expect(result.current).toBe(true);});- it("should return true when on /onboarding page", () => {- useLocationMock.mockReturnValue({ pathname: "/onboarding" });- const { result } = renderHook(() => useIsOnIntermediatePage());- expect(result.current).toBe(true);- });-it("should return true when on /information-request page", () => {useLocationMock.mockReturnValue({ pathname: "/information-request" });const { result } = renderHook(() => useIsOnIntermediatePage());@@ -52,6 +46,12 @@ describe("useIsOnIntermediatePage", () => {const { result } = renderHook(() => useIsOnIntermediatePage());expect(result.current).toBe(false);});++ it("should return false when on /onboarding page so settings/auth queries can fire", () => {+ useLocationMock.mockReturnValue({ pathname: "/onboarding" });+ const { result } = renderHook(() => useIsOnIntermediatePage());+ expect(result.current).toBe(false);+ });});describe("handles edge cases", () => {diff --git a/frontend/__tests__/routes/root-layout.test.tsx b/frontend/__tests__/routes/root-layout.test.tsxindex ba7327d0c4..9f7ada1b3f 100644--- a/frontend/__tests__/routes/root-layout.test.tsx+++ b/frontend/__tests__/routes/root-layout.test.tsx@@ -6,6 +6,7 @@ import MainApp from "#/routes/root-layout";import OptionService from "#/api/option-service/option-service.api";import AuthService from "#/api/auth-service/auth-service.api";import SettingsService from "#/api/settings-service/settings-service.api";+import { onboardingService } from "#/api/onboarding-service/onboarding-service.api";import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";vi.mock("#/hooks/use-github-auth-url", () => ({@@ -111,6 +112,23 @@ const RouterStubWithLogin = createRoutesStub([},]);+const RouterStubWithOnboarding = createRoutesStub([+ {+ Component: MainApp,+ path: "/",+ children: [+ {+ Component: () => <div data-testid="outlet-content" />,+ path: "/",+ },+ ],+ },+ {+ Component: () => <div data-testid="onboarding-page" />,+ path: "/onboarding",+ },+]);+const RouterStubWithDeviceVerify = createRoutesStub([{Component: MainApp,@@ -193,6 +211,10 @@ describe("MainApp", () => {MOCK_DEFAULT_USER_SETTINGS,);+ vi.spyOn(onboardingService, "getStatus").mockResolvedValue({+ should_complete_onboarding: false,+ });+vi.stubGlobal("localStorage", {getItem: vi.fn(() => null),setItem: vi.fn(),@@ -553,4 +575,25 @@ describe("MainApp", () => {);});});++ describe("Onboarding redirect", () => {+ it("should redirect authenticated SaaS users with incomplete onboarding to /onboarding", async () => {+ // Arrange: backend reports onboarding still required.+ vi.spyOn(onboardingService, "getStatus").mockResolvedValue({+ should_complete_onboarding: true,+ });++ // Act: render the home page.+ renderWithLoginStub(RouterStubWithOnboarding, ["/"]);++ // Assert: user lands on /onboarding instead of the home outlet.+ await waitFor(+ () => {+ expect(screen.getByTestId("onboarding-page")).toBeInTheDocument();+ },+ { timeout: 2000 },+ );+ expect(screen.queryByTestId("outlet-content")).not.toBeInTheDocument();+ });+ });});diff --git a/frontend/src/api/onboarding-service/onboarding-service.api.ts b/frontend/src/api/onboarding-service/onboarding-service.api.tsnew file mode 100644index 0000000000..b708139a75--- /dev/null+++ b/frontend/src/api/onboarding-service/onboarding-service.api.ts@@ -0,0 +1,14 @@+import { openHands } from "../open-hands-axios";++export type OnboardingStatusResponse = {+ should_complete_onboarding: boolean;+};++export const onboardingService = {+ getStatus: async (): Promise<OnboardingStatusResponse> => {+ const { data } = await openHands.get<OnboardingStatusResponse>(+ "/api/onboarding_status",+ );+ return data;+ },+};diff --git a/frontend/src/components/features/guards/onboarding-guard.tsx b/frontend/src/components/features/guards/onboarding-guard.tsxnew file mode 100644index 0000000000..a74a963072--- /dev/null+++ b/frontend/src/components/features/guards/onboarding-guard.tsx@@ -0,0 +1,22 @@+import React from "react";+import { useLocation, useNavigate } from "react-router";+import { useOnboardingStatus } from "#/hooks/query/use-onboarding-status";++/**+ * Forces SaaS users with incomplete onboarding to /onboarding before they can+ * access any protected route. Mirrors EmailVerificationGuard.+ */+export function OnboardingGuard({ children }: { children: React.ReactNode }) {+ const { data, isLoading } = useOnboardingStatus();+ const navigate = useNavigate();+ const { pathname } = useLocation();++ React.useEffect(() => {+ if (isLoading) return;+ if (data?.should_complete_onboarding && pathname !== "/onboarding") {+ navigate("/onboarding", { replace: true });+ }+ }, [data?.should_complete_onboarding, isLoading, pathname, navigate]);++ return children;+}diff --git a/frontend/src/hooks/mutation/use-submit-onboarding.ts b/frontend/src/hooks/mutation/use-submit-onboarding.tsindex de922a88e9..87f21ac2e1 100644--- a/frontend/src/hooks/mutation/use-submit-onboarding.ts+++ b/frontend/src/hooks/mutation/use-submit-onboarding.ts@@ -19,6 +19,7 @@ export const useSubmitOnboarding = () => {},onSuccess: () => {queryClient.invalidateQueries({ queryKey: ["settings"] });+ queryClient.invalidateQueries({ queryKey: ["onboarding-status"] });const finalRedirectUrl = "/";// Check if the redirect URL is an external URL (starts with http or https)diff --git a/frontend/src/hooks/query/use-onboarding-status.ts b/frontend/src/hooks/query/use-onboarding-status.tsnew file mode 100644index 0000000000..8c30b8dbcd--- /dev/null+++ b/frontend/src/hooks/query/use-onboarding-status.ts@@ -0,0 +1,21 @@+import { useQuery } from "@tanstack/react-query";+import { onboardingService } from "#/api/onboarding-service/onboarding-service.api";+import { useConfig } from "./use-config";+import { useIsAuthed } from "./use-is-authed";++export const useOnboardingStatus = () => {+ const { data: config } = useConfig();+ const { data: isAuthed } = useIsAuthed();++ return useQuery({+ queryKey: ["onboarding-status"],+ queryFn: onboardingService.getStatus,+ enabled: config?.app_mode === "saas" && !!isAuthed,+ staleTime: 1000 * 60 * 5,+ gcTime: 1000 * 60 * 15,+ retry: false,+ meta: {+ disableToast: true,+ },+ });+};diff --git a/frontend/src/hooks/use-is-on-intermediate-page.ts b/frontend/src/hooks/use-is-on-intermediate-page.tsindex dbe6ed6025..2bcd898c4c 100644--- a/frontend/src/hooks/use-is-on-intermediate-page.ts+++ b/frontend/src/hooks/use-is-on-intermediate-page.ts@@ -1,10 +1,6 @@import { useLocation } from "react-router";-const INTERMEDIATE_PAGE_PATHS = [- "/accept-tos",- "/onboarding",- "/information-request",-];+const INTERMEDIATE_PAGE_PATHS = ["/accept-tos", "/information-request"];/*** Checks if the current page is an intermediate page.diff --git a/frontend/src/routes/onboarding-form.tsx b/frontend/src/routes/onboarding-form.tsxindex 9799253056..c7c3dd9e7e 100644--- a/frontend/src/routes/onboarding-form.tsx+++ b/frontend/src/routes/onboarding-form.tsx@@ -7,6 +7,7 @@ import { BrandButton } from "#/components/features/settings/brand-button";import { I18nKey } from "#/i18n/declaration";import OpenHandsLogoWhite from "#/assets/branding/openhands-logo-white.svg?react";import { useSubmitOnboarding } from "#/hooks/mutation/use-submit-onboarding";+import { useOnboardingStatus } from "#/hooks/query/use-onboarding-status";import { useTracking } from "#/hooks/use-tracking";import { cn } from "#/utils/utils";import { useMe } from "#/hooks/query/use-me";@@ -82,9 +83,22 @@ function OnboardingForm() {const loaderData = useLoaderData<typeof clientLoader>();const config = loaderData?.config;const { data: me } = useMe();+ const { data: onboardingStatus, isLoading: isOnboardingStatusLoading } =+ useOnboardingStatus();const { mutate: submitOnboarding } = useSubmitOnboarding();const { trackOnboardingCompleted } = useTracking();+ React.useEffect(() => {+ if (isOnboardingStatusLoading) return;+ if (onboardingStatus?.should_complete_onboarding === false) {+ navigate("/", { replace: true });+ }+ }, [+ onboardingStatus?.should_complete_onboarding,+ isOnboardingStatusLoading,+ navigate,+ ]);+const onboardingAppMode: OnboardingAppMode = getOnboardingAppMode(config?.feature_flags?.deployment_mode,);diff --git a/frontend/src/routes/root-layout.tsx b/frontend/src/routes/root-layout.tsxindex 636ae85c11..87b8c11769 100644--- a/frontend/src/routes/root-layout.tsx+++ b/frontend/src/routes/root-layout.tsx@@ -26,6 +26,7 @@ import { useSyncPostHogConsent } from "#/hooks/use-sync-posthog-consent";import { useAutoSelectOrganization } from "#/hooks/use-auto-select-organization";import { LOCAL_STORAGE_KEYS } from "#/utils/local-storage";import { EmailVerificationGuard } from "#/components/features/guards/email-verification-guard";+import { OnboardingGuard } from "#/components/features/guards/onboarding-guard";import { AlertBanner } from "#/components/features/alerts/alert-banner";import { cn } from "#/utils/utils";import { LoadingSpinner } from "#/components/shared/loading-spinner";@@ -278,9 +279,11 @@ export default function MainApp() {id="root-outlet"className="flex-1 relative overflow-auto custom-scrollbar">- <EmailVerificationGuard>- <Outlet />- </EmailVerificationGuard>+ <OnboardingGuard>+ <EmailVerificationGuard>+ <Outlet />+ </EmailVerificationGuard>+ </OnboardingGuard></div></div>