π OpenHands: AI-Driven Development
fix: validate api key before advancing backend connection step (#16840)
Jatin Jain1697faa31337
diff --git a/__tests__/components/backends/add-backend-modal.test.tsx b/__tests__/components/backends/add-backend-modal.test.tsxindex f8d1ebe6a6..ad56c83882 100644--- a/__tests__/components/backends/add-backend-modal.test.tsx+++ b/__tests__/components/backends/add-backend-modal.test.tsx@@ -14,6 +14,7 @@ import { AddBackendModal } from "#/components/features/backends/add-backend-modaimport * as telemetry from "#/services/telemetry";const getServerInfoMock = vi.hoisted(() => vi.fn());+const getSettingsMock = vi.hoisted(() => vi.fn().mockResolvedValue({}));const deviceFlowMocks = vi.hoisted(() => ({startDeviceFlow: vi.fn(),@@ -38,6 +39,11 @@ vi.mock("@openhands/typescript-client/clients", () => ({getServerInfo: getServerInfoMock,};}),+ SettingsClient: vi.fn(function SettingsClientMock() {+ return {+ getSettings: getSettingsMock,+ };+ }),}));let captureMock: MockInstance<typeof telemetry.trackEvent>;@@ -89,7 +95,7 @@ beforeEach(() => {interval: 5,});deviceFlowMocks.pollForToken.mockReset();- deviceFlowMocks.pollForToken.mockImplementation(() => new Promise(() => {}));+ deviceFlowMocks.pollForToken.mockImplementation(() => new Promise(() => { }));__resetActiveStoreForTests();});diff --git a/__tests__/components/backends/backend-form-modal.test.tsx b/__tests__/components/backends/backend-form-modal.test.tsxindex 494d51c831..04c7cd0a39 100644--- a/__tests__/components/backends/backend-form-modal.test.tsx+++ b/__tests__/components/backends/backend-form-modal.test.tsx@@ -16,6 +16,7 @@ import {import { BackendFormModal } from "#/components/features/backends/backend-form-modal";const getServerInfoMock = vi.hoisted(() => vi.fn());+const getSettingsMock = vi.hoisted(() => vi.fn().mockResolvedValue({}));vi.mock("@openhands/typescript-client/clients", () => ({ServerClient: vi.fn(function ServerClientMock() {@@ -23,6 +24,11 @@ vi.mock("@openhands/typescript-client/clients", () => ({getServerInfo: getServerInfoMock,};}),+ SettingsClient: vi.fn(function SettingsClientMock() {+ return {+ getSettings: getSettingsMock,+ };+ }),}));function renderWithProviders(diff --git a/__tests__/components/onboarding/onboarding-modal.test.tsx b/__tests__/components/onboarding/onboarding-modal.test.tsxindex b369919e64..be09c02be6 100644--- a/__tests__/components/onboarding/onboarding-modal.test.tsx+++ b/__tests__/components/onboarding/onboarding-modal.test.tsx@@ -23,6 +23,7 @@ import * as telemetry from "#/services/telemetry";const llmSettingsScreenMock = vi.hoisted(() => vi.fn());const getServerInfoMock = vi.hoisted(() => vi.fn());+const getSettingsMock = vi.hoisted(() => vi.fn().mockResolvedValue({}));let captureMock: MockInstance<typeof telemetry.trackEvent>;// Both the backend status badge in the embedded edit form and the@@ -38,7 +39,7 @@ vi.mock("@openhands/typescript-client/clients", () => ({// `LlmSettingsScreen` is stubbed, so provide the minimal client it needs.SettingsClient: vi.fn(function SettingsClientMock() {return {- getSettings: vi.fn().mockResolvedValue({}),+ getSettings: vi.fn(() => getSettingsMock()),};}),}));@@ -618,6 +619,47 @@ describe("OnboardingModal", () => {expect(screen.queryByText("BACKEND$LOGIN_OR")).toBeNull();});+ it("shows a connection error when the backend API key is invalid", async () => {+ window.localStorage.clear();+ vi.stubEnv("VITE_BACKEND_BASE_URL", "");+ vi.stubEnv("VITE_SESSION_API_KEY", "");+ delete (window as unknown as Record<string, unknown>)+ .__AGENT_CANVAS_SESSION_API_KEY__;+ __resetActiveStoreForTests();++ // Mock SettingsClient to throw a 401 error+ const authError = new Error("Unauthorized");+ authError.name = "HttpError";+ (authError as any).status = 401;+ getSettingsMock.mockRejectedValueOnce(authError);+ // getServerInfoMock implicitly resolves, but shouldn't be reached if test is correct++ renderModal();+ const user = userEvent.setup();++ await user.clear(screen.getByTestId("onboarding-backend-host"));+ await user.type(+ screen.getByTestId("onboarding-backend-host"),+ "https://127.0.0.1:8000",+ );+ await user.clear(screen.getByTestId("onboarding-backend-api-key"));+ await user.type(+ screen.getByTestId("onboarding-backend-api-key"),+ "invalid-session-key",+ );+ await user.click(screen.getByTestId("onboarding-backend-next"));++ expect(+ await screen.findByTestId("onboarding-backend-error"),+ ).toHaveTextContent("BACKEND$CONNECTION_TEST_FAILED");+ expect(screen.getByTestId("onboarding-backend-error")).toHaveTextContent(+ "Invalid API key", // This comes from INVALID_BACKEND_API_KEY_ERROR+ );++ // Should not advance to the next step+ expect(screen.queryByText("BACKEND$LOGIN_OR")).toBeNull();+ });+it("shows a connection error when saving an unreachable backend", async () => {window.localStorage.clear();vi.stubEnv("VITE_BACKEND_BASE_URL", "");@@ -977,7 +1019,7 @@ describe("OnboardingModal", () => {);expect(helloInput.compareDocumentPosition(recommendations) &- Node.DOCUMENT_POSITION_FOLLOWING,+ Node.DOCUMENT_POSITION_FOLLOWING,).toBeTruthy();expect(within(recommendations).getByTestId(diff --git a/src/api/agent-server-compatibility.ts b/src/api/agent-server-compatibility.tsindex efd7897e97..a2834b6423 100644--- a/src/api/agent-server-compatibility.ts+++ b/src/api/agent-server-compatibility.ts@@ -10,6 +10,7 @@ import {getEffectiveLocalBackend,isNoBackend,} from "#/api/backend-registry/active-store";+import type { Backend } from "#/api/backend-registry/types";import defaults from "../../config/defaults.json";const AGENT_SERVER_INFO_TIMEOUT_MS = 5000;@@ -22,6 +23,14 @@ export const AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE =export const AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE ="AGENT_SERVER_UNKNOWN_VERSION";+/**+ * Sentinel string thrown (as an Error message) when a local backend+ * rejects the configured session API key with HTTP 401.+ * Shared between the backend health probe ({@link validateLocalBackend})+ * and any consumer that needs to detect this specific failure.+ */+export const INVALID_BACKEND_API_KEY_ERROR = "Invalid API key";+export interface AgentServerInfo extends BaseServerInfo {sdk_version?: string;usable_tools?: string[] | null;@@ -317,6 +326,41 @@ export function assertAgentServerVersionIsSupported(}}+/**+ * Validates a local agent-server backend with a two-step probe:+ * 1. GET /api/settings β authenticates the configured session API key;+ * a 401 throws an Error with message {@link INVALID_BACKEND_API_KEY_ERROR}.+ * 2. GET /server_info β asserts the server meets the minimum version floor.+ *+ * Returns the display version string reported by the server, or `null` when+ * the server does not report a parseable version. Throws on any failure.+ *+ * Used by both the backend health poller and the backend-form connection test+ * so that auth-check semantics (status codes, error messages) stay in one place.+ */+export async function validateLocalBackend(+ backend: Pick<Backend, "host" | "apiKey">,+ timeout: number,+): Promise<string | null> {+ const clientOptions = getAgentServerClientOptions({+ host: backend.host,+ sessionApiKey: backend.apiKey || null,+ timeout,+ });++ try {+ await new SettingsClient(clientOptions).getSettings();+ const serverInfo = await new ServerClient(clientOptions).getServerInfo();+ assertAgentServerVersionIsSupported(serverInfo);+ return getDisplayAgentServerVersion(serverInfo);+ } catch (error) {+ if (isSdkHttpStatusError(error, 401)) {+ throw new Error(INVALID_BACKEND_API_KEY_ERROR);+ }+ throw error;+ }+}+export async function loadAgentServerInfo() {// The probe is a *local* agent-server concern β it verifies the runtime// hosting the GUI is reachable. It must NEVER run against the activediff --git a/src/components/features/backends/backend-form-modal.tsx b/src/components/features/backends/backend-form-modal.tsxindex 652db065e8..a302aa5629 100644--- a/src/components/features/backends/backend-form-modal.tsx+++ b/src/components/features/backends/backend-form-modal.tsx@@ -22,8 +22,8 @@ import { getAgentServerClientOptions } from "#/api/agent-server-client-options";import { getLockedCloudHost } from "#/api/agent-server-config";import { isOpenHandsCloudHost } from "#/api/device-flow-client";import {- assertAgentServerVersionIsSupported,getDisplayAgentServerVersion,+ validateLocalBackend,} from "#/api/agent-server-compatibility";import ChevronDownSmallIcon from "#/icons/chevron-down-small.svg?react";import { I18nKey } from "#/i18n/declaration";@@ -182,16 +182,8 @@ async function testBackendConnection(): Promise<BackendConnectionTestMetadata> {// Cloud backends authenticate via OAuth; preflight GET is not applicable.if (backend.kind !== "local") return { agentServerVersion: null };-- const serverInfo = await new ServerClient(- getAgentServerClientOptions({- host: backend.host,- sessionApiKey: backend.apiKey || null,- timeout: 5000,- }),- ).getServerInfo();- assertAgentServerVersionIsSupported(serverInfo);- return { agentServerVersion: getDisplayAgentServerVersion(serverInfo) };+ const agentServerVersion = await validateLocalBackend(backend, 5000);+ return { agentServerVersion };}/**diff --git a/src/hooks/query/use-backends-health.ts b/src/hooks/query/use-backends-health.tsindex 7526fcfdcb..d495830b19 100644--- a/src/hooks/query/use-backends-health.ts+++ b/src/hooks/query/use-backends-health.ts@@ -2,20 +2,15 @@ import React from "react";import axios from "axios";import { useQueries } from "@tanstack/react-query";import { HttpError } from "@openhands/typescript-client";-import {- ServerClient,- SettingsClient,-} from "@openhands/typescript-client/clients";import {getCloudOrganizations,getCurrentCloudApiKey,} from "#/api/cloud/organization-service.api";import {- assertAgentServerVersionIsSupported,- isSdkHttpStatusError,+ validateLocalBackend,+ INVALID_BACKEND_API_KEY_ERROR,} from "#/api/agent-server-compatibility";import type { Backend } from "#/api/backend-registry/types";-import { getAgentServerClientOptions } from "#/api/agent-server-client-options";import {isCorsOrNetworkError,isCorsOrNetworkErrorMessage,@@ -33,7 +28,7 @@ import { MAX_CONSECUTIVE_FAILURES } from "#/api/backend-registry/health-storage"// traffic for the browser's per-origin HTTP/1.1 connection pool.const REFRESH_INTERVAL_MS = 30000;const PROBE_TIMEOUT_MS = 4000;-export const INVALID_BACKEND_API_KEY_ERROR = "Invalid API key";+export { INVALID_BACKEND_API_KEY_ERROR } from "#/api/agent-server-compatibility";export const MISSING_BACKEND_API_KEY_ERROR = "API key required";export const CLOUD_BACKEND_API_KEY_OR_NETWORK_ERROR ="Cloud API key or network issue";@@ -114,22 +109,7 @@ async function probeBackend(backend: Backend): Promise<true> {return true;}- try {- const clientOptions = getAgentServerClientOptions({- host: backend.host,- sessionApiKey: backend.apiKey || null,- timeout: PROBE_TIMEOUT_MS,- });-- await new SettingsClient(clientOptions).getSettings();- const serverInfo = await new ServerClient(clientOptions).getServerInfo();- assertAgentServerVersionIsSupported(serverInfo);- } catch (error) {- if (isSdkHttpStatusError(error, 401)) {- throw new Error(INVALID_BACKEND_API_KEY_ERROR);- }- throw error;- }+ await validateLocalBackend(backend, PROBE_TIMEOUT_MS);return true;}