Skip to content

πŸ™Œ 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.py
index 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.py
index 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 json
import uuid
from 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.tsx
index 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.ts
index 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.tsx
index 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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.tsx
index 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.tsx
index 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>