From 21c68ec86e7d92d842a4669d444f90a0fdb8a5d1 Mon Sep 17 00:00:00 2001 From: Will Gordon Date: Fri, 31 Jul 2026 12:04:21 -0400 Subject: [PATCH] feat(cursor): surfaces a dismissible cursor-agent nudge Adds GET /api/providers/cursor/agent-availability, a credential-free LOCAL_ONLY route returning only { cursorAgentAvailable: boolean }, backed by a 5-minute cached wrapper around the renewal orchestrator's existing availability check. Surfaces a dismissible dashboard banner on the Cursor provider page suggesting cursor-agent installation when it isn't detected, following the existing dismissible-banner convention. Also fixes a pre-existing bracket character in a routeGuard.ts comment that was silently truncating check-openapi-security-tiers.mjs's view of LOCAL_ONLY_API_PREFIXES. --- docs/openapi.yaml | 10 + .../[id]/ProviderDetailPageClient.tsx | 2 + .../[id]/components/CursorAgentNudge.tsx | 102 ++++++++++ .../__tests__/CursorAgentNudge.test.tsx | 178 ++++++++++++++++++ .../cursor/agent-availability/route.ts | 31 +++ src/i18n/messages/en.json | 3 + src/lib/cursor/renewal.ts | 28 +++ src/server/authz/routeGuard.ts | 3 +- src/shared/constants/spawnCapablePrefixes.ts | 1 + ...t-availability-route-authenticated.test.ts | 61 ++++++ .../cursor-agent-availability-route.test.ts | 116 ++++++++++++ tests/unit/cursor-renewal.test.ts | 58 ++++++ ...te-guard-cursor-agent-availability.test.ts | 49 +++++ 13 files changed, 641 insertions(+), 1 deletion(-) create mode 100644 src/app/(dashboard)/dashboard/providers/[id]/components/CursorAgentNudge.tsx create mode 100644 src/app/(dashboard)/dashboard/providers/[id]/components/__tests__/CursorAgentNudge.test.tsx create mode 100644 src/app/api/providers/cursor/agent-availability/route.ts create mode 100644 tests/unit/cursor-agent-availability-route-authenticated.test.ts create mode 100644 tests/unit/cursor-agent-availability-route.test.ts create mode 100644 tests/unit/route-guard-cursor-agent-availability.test.ts diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 9dfe25f56e..e33c140dc0 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -1744,6 +1744,16 @@ paths: "200": description: Provider model list + /api/providers/cursor/agent-availability: + get: + tags: [Providers] + summary: Check cursor-agent availability + description: "Credential-free, informational check for whether cursor-agent is installed and authenticated on this host — backs the dashboard's dismissible install-nudge banner. Returns only cursorAgentAvailable (boolean); never tokens or machineId." + x-loopback-only: true + responses: + "200": + description: Availability result + /api/providers/test-batch: post: tags: [Providers] diff --git a/src/app/(dashboard)/dashboard/providers/[id]/ProviderDetailPageClient.tsx b/src/app/(dashboard)/dashboard/providers/[id]/ProviderDetailPageClient.tsx index 95842ad47c..f99309bf07 100644 --- a/src/app/(dashboard)/dashboard/providers/[id]/ProviderDetailPageClient.tsx +++ b/src/app/(dashboard)/dashboard/providers/[id]/ProviderDetailPageClient.tsx @@ -49,6 +49,7 @@ import CoolingConnectionsPanel from "./components/CoolingConnectionsPanel"; import ConnectionsHeaderToolbar from "./components/ConnectionsHeaderToolbar"; import ProviderAccountRoutingCard from "../../settings/components/ProviderAccountRoutingCard"; import ZedImportCard from "./components/ZedImportCard"; +import CursorAgentNudge from "./components/CursorAgentNudge"; import ProviderPageHeader from "./components/ProviderPageHeader"; import CompatibleNodeCard from "./components/CompatibleNodeCard"; import ProviderModalsPanel from "./components/ProviderModalsPanel"; @@ -462,6 +463,7 @@ export default function ProviderDetailPageClient() { {providerId === "zed" && ( )} + {providerId === "cursor" && } {isCompatible && providerNode && ( void) { + window.addEventListener(DISMISS_EVENT, callback); + return () => window.removeEventListener(DISMISS_EVENT, callback); +} + +// SSR has no localStorage, so the server always renders the banner visible; +// useSyncExternalStore reconciles that against the real client-side value +// right after hydration, with no hydration mismatch and no setState-in-effect. +function getServerSnapshot() { + return true; +} + +/** + * Dismissible dashboard banner suggesting `cursor-agent` installation when + * it's not detected on the host — without it, Cursor connections need + * periodic manual reconnection roughly every 24 hours instead of automatic + * background renewal. Fetches the credential-free, LOCAL_ONLY + * `/api/providers/cursor/agent-availability` endpoint — NOT + * `/api/oauth/cursor/auto-import`, which returns a live token/machineId and + * has no legitimate use here. One global dismissible notice (persisted under + * a single fixed key) since this is a host-level, not per-connection, fact. + */ +export default function CursorAgentNudge() { + const t = useTranslations("providers"); + const visible = useSyncExternalStore(subscribe, isNotDismissed, getServerSnapshot); + const [available, setAvailable] = useState(null); + + useEffect(() => { + let cancelled = false; + fetch("/api/providers/cursor/agent-availability") + .then((res) => (res.ok ? res.json() : null)) + .then((data) => { + if (!cancelled && data && typeof data.cursorAgentAvailable === "boolean") { + setAvailable(data.cursorAgentAvailable); + } + }) + .catch(() => { + // Unreachable (e.g. a non-loopback dashboard session gets 403 + // LOCAL_ONLY here) — stay in the "unknown" state rather than nagging + // a session that simply can't reach the check. + }); + return () => { + cancelled = true; + }; + }, []); + + if (!visible || available !== false) return null; + + const dismiss = () => { + try { + localStorage.setItem(DISMISS_STORAGE_KEY, "true"); + } catch { + // ignore — worst case the banner reappears next visit + } + window.dispatchEvent(new Event(DISMISS_EVENT)); + }; + + return ( +
+ info +
+

+ {t("cursorAgentNudgeTitle") || "Enable automatic Cursor session renewal"} +

+

+ {t("cursorAgentNudgeBody") || + "Install cursor-agent for automatic session renewal — without it, Cursor connections need periodic manual reconnection roughly every 24 hours."} +

+
+ +
+ ); +} diff --git a/src/app/(dashboard)/dashboard/providers/[id]/components/__tests__/CursorAgentNudge.test.tsx b/src/app/(dashboard)/dashboard/providers/[id]/components/__tests__/CursorAgentNudge.test.tsx new file mode 100644 index 0000000000..acf3685116 --- /dev/null +++ b/src/app/(dashboard)/dashboard/providers/[id]/components/__tests__/CursorAgentNudge.test.tsx @@ -0,0 +1,178 @@ +// @vitest-environment jsdom +/** + * CursorAgentNudge (Cursor renewal plan, Task 5) — dismissible dashboard + * banner suggesting `cursor-agent` installation when it's unavailable. + * Mirrors tests/unit/ui/kimiSponsorBanner.test.tsx's technique for the same + * useSyncExternalStore + localStorage dismissal pattern (KimiSponsorBanner.tsx + * is the precedent this component follows), and this directory's own + * __tests__/phase1d.test.tsx for the createRoot/act mounting convention. + */ +import React from "react"; +import { act } from "react"; +import { createRoot, hydrateRoot } from "react-dom/client"; +import { renderToString } from "react-dom/server"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import CursorAgentNudge from "../CursorAgentNudge"; + +const STORAGE_KEY = "omniroute.cursorAgentNudgeDismissed"; + +vi.mock("next-intl", () => ({ useTranslations: () => (k: string) => k })); + +function mockFetch(cursorAgentAvailable: boolean | null) { + return vi.fn(async (url: string) => { + if (cursorAgentAvailable === null) { + return { ok: false, json: async () => ({}) } as Response; + } + return { ok: true, json: async () => ({ cursorAgentAvailable }) } as Response; + }); +} + +async function flushEffects() { + await act(async () => { + await new Promise((resolve) => setTimeout(resolve, 0)); + }); +} + +function renderNudge(): HTMLDivElement { + const container = document.createElement("div"); + document.body.appendChild(container); + const root = createRoot(container); + act(() => { + root.render(); + }); + return container; +} + +describe("CursorAgentNudge", () => { + beforeEach(() => { + ( + globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean } + ).IS_REACT_ACT_ENVIRONMENT = true; + localStorage.removeItem(STORAGE_KEY); + }); + + afterEach(() => { + document.body.innerHTML = ""; + localStorage.removeItem(STORAGE_KEY); + vi.unstubAllGlobals(); + }); + + it("renders when cursorAgentAvailable is false", async () => { + vi.stubGlobal("fetch", mockFetch(false)); + const container = renderNudge(); + await flushEffects(); + + expect(container.querySelector("[role='complementary']")).not.toBeNull(); + }); + + it("does not render when cursorAgentAvailable is true", async () => { + vi.stubGlobal("fetch", mockFetch(true)); + const container = renderNudge(); + await flushEffects(); + + expect(container.querySelector("[role='complementary']")).toBeNull(); + }); + + it("does not render while the availability check is still pending or unreachable", async () => { + vi.stubGlobal("fetch", mockFetch(null)); // res.ok === false -> stays in the "unknown" state + const container = renderNudge(); + await flushEffects(); + + expect(container.querySelector("[role='complementary']")).toBeNull(); + }); + + it("fetches /api/providers/cursor/agent-availability, NOT /api/oauth/cursor/auto-import", async () => { + const fetchMock = mockFetch(false); + vi.stubGlobal("fetch", fetchMock); + renderNudge(); + await flushEffects(); + + expect(fetchMock).toHaveBeenCalledWith("/api/providers/cursor/agent-availability"); + for (const call of fetchMock.mock.calls) { + expect(String(call[0])).not.toContain("/api/oauth/cursor/auto-import"); + } + }); + + it("dismiss button hides the banner and persists the dismissal to localStorage", async () => { + vi.stubGlobal("fetch", mockFetch(false)); + const container = renderNudge(); + await flushEffects(); + expect(container.querySelector("[role='complementary']")).not.toBeNull(); + + const dismissButton = container.querySelector("button"); + expect(dismissButton).not.toBeNull(); + act(() => { + dismissButton?.dispatchEvent(new MouseEvent("click", { bubbles: true })); + }); + + expect(container.querySelector("[role='complementary']")).toBeNull(); + expect(localStorage.getItem(STORAGE_KEY)).toBe("true"); + }); + + it("stays hidden across a fresh render once dismissed (localStorage persistence — no reappear)", async () => { + localStorage.setItem(STORAGE_KEY, "true"); + vi.stubGlobal("fetch", mockFetch(false)); // still "unavailable" — dismissal alone must suppress it + const container = renderNudge(); + await flushEffects(); + + expect(container.querySelector("[role='complementary']")).toBeNull(); + }); + + it("stays hidden after an actual unmount+remount of the same dismissed state", async () => { + vi.stubGlobal("fetch", mockFetch(false)); + const first = document.createElement("div"); + document.body.appendChild(first); + const firstRoot = createRoot(first); + act(() => { + firstRoot.render(); + }); + await act(async () => { + await new Promise((resolve) => setTimeout(resolve, 0)); + }); + const dismissButton = first.querySelector("button"); + act(() => { + dismissButton?.dispatchEvent(new MouseEvent("click", { bubbles: true })); + }); + act(() => { + firstRoot.unmount(); + }); + first.remove(); + + const second = renderNudge(); + await flushEffects(); + expect(second.querySelector("[role='complementary']")).toBeNull(); + }); + + it("hydrates without a mismatch warning (SSR always renders nothing before the fetch resolves)", async () => { + vi.stubGlobal("fetch", mockFetch(false)); + + const serverHtml = renderToString(); + // The component renders null on the server (available starts at null, + // getServerSnapshot() returns true but `available !== false` short-circuits + // the render to null regardless) — this proves that invariant holds. + expect(serverHtml).toBe(""); + + const container = document.createElement("div"); + container.innerHTML = serverHtml; + document.body.appendChild(container); + + const errors: unknown[][] = []; + const originalConsoleError = console.error; + console.error = (...args: unknown[]) => { + errors.push(args); + }; + + try { + act(() => { + hydrateRoot(container, ); + }); + } finally { + console.error = originalConsoleError; + } + + const hydrationWarnings = errors.filter((args) => + args.some((a) => typeof a === "string" && /hydrat/i.test(a)) + ); + expect(hydrationWarnings).toEqual([]); + }); +}); diff --git a/src/app/api/providers/cursor/agent-availability/route.ts b/src/app/api/providers/cursor/agent-availability/route.ts new file mode 100644 index 0000000000..bac93446f1 --- /dev/null +++ b/src/app/api/providers/cursor/agent-availability/route.ts @@ -0,0 +1,31 @@ +import { NextResponse } from "next/server"; +import { getCachedCursorAgentAvailability } from "@/lib/cursor/renewal"; + +/** + * GET /api/providers/cursor/agent-availability + * Credential-free, informational check for whether `cursor-agent` is + * installed and authenticated on this host — backs the dashboard's + * dismissible install-nudge banner. Returns ONLY `{ cursorAgentAvailable }`; + * never tokens/machineId. This is a SEPARATE route from + * `/api/oauth/cursor/auto-import` (which legitimately returns + * `accessToken`/`machineId` for its own credential-import purpose) — + * reusing that route here would hand a live local Cursor OAuth token to a + * frequently-mounted, purely informational UI component with no legitimate + * use for it. + * + * No in-route auth guard: unlike `/api/oauth/cursor/auto-import` (which is + * PUBLIC-classified and never reaches the LOCAL_ONLY gate), this route lives + * under `/api/providers/` — MANAGEMENT-classified — and is itself + * LOCAL_ONLY (see `LOCAL_ONLY_API_PREFIXES` in + * `src/server/authz/routeGuard.ts`), so `managementPolicy` already enforces + * auth + loopback before this handler runs, matching the sibling + * `/api/providers/[id]/refresh` and `/api/providers/[id]/login` routes + * (neither perform their own in-route auth check either). + * + * 🔒 LOCAL_ONLY — spawns `cursor-agent status --format json` via + * `checkCursorAgentAvailability()` (Hard Rules #15 + #17). + */ +export async function GET() { + const { available } = await getCachedCursorAgentAvailability(); + return NextResponse.json({ cursorAgentAvailable: available }); +} diff --git a/src/i18n/messages/en.json b/src/i18n/messages/en.json index 62d6c4719b..0fd7adab01 100644 --- a/src/i18n/messages/en.json +++ b/src/i18n/messages/en.json @@ -5637,6 +5637,9 @@ "zedPasteApiKey": "Paste API key…", "zedSaving": "Saving…", "zedImportAction": "Import", + "cursorAgentNudgeTitle": "Enable automatic Cursor session renewal", + "cursorAgentNudgeBody": "Install cursor-agent for automatic session renewal — without it, Cursor connections need periodic manual reconnection roughly every 24 hours.", + "cursorAgentNudgeDismiss": "Dismiss", "zedManualImportFailed": "Manual import failed", "zedManualImportSuccess": "Imported {provider} token from Zed", "grokImportTitle": "Import Grok Build Auth", diff --git a/src/lib/cursor/renewal.ts b/src/lib/cursor/renewal.ts index e7736edf71..5338cf7938 100644 --- a/src/lib/cursor/renewal.ts +++ b/src/lib/cursor/renewal.ts @@ -103,6 +103,34 @@ export async function checkCursorAgentAvailability(): Promise<{ } } +const CURSOR_AGENT_AVAILABILITY_CACHE_TTL_MS = 5 * 60 * 1000; + +let cachedAvailability: { + result: { available: boolean; binaryPath: string | null }; + expiresAt: number; +} | null = null; + +/** + * Cached wrapper around checkCursorAgentAvailability(), for INFORMATIONAL/UI + * callers only (5-minute TTL) — e.g. the dashboard's install-nudge banner, + * which may mount/refetch frequently. Task 3's sweep and Task 4's manual + * refresh route continue calling the UNCACHED checkCursorAgentAvailability() + * directly: a "refresh now" click must always see a fresh status, never a + * stale cached answer. + */ +export async function getCachedCursorAgentAvailability(): Promise<{ + available: boolean; + binaryPath: string | null; +}> { + const now = Date.now(); + if (cachedAvailability && cachedAvailability.expiresAt > now) { + return cachedAvailability.result; + } + const result = await checkCursorAgentAvailability(); + cachedAvailability = { result, expiresAt: now + CURSOR_AGENT_AVAILABILITY_CACHE_TTL_MS }; + return result; +} + export type CursorRenewalResult = | { status: "renewed"; diff --git a/src/server/authz/routeGuard.ts b/src/server/authz/routeGuard.ts index f4381b24f7..f1e04efa64 100644 --- a/src/server/authz/routeGuard.ts +++ b/src/server/authz/routeGuard.ts @@ -53,11 +53,12 @@ export const LOCAL_ONLY_API_PREFIXES: ReadonlyArray = [ "/api/local/", // T-12: 1-click local service launchers (Redis today; spawns podman/docker) — loopback-enforced by isLocalRequestAllowed() in src/lib/security/localEndpoints.ts (Hard Rules #15 + #17) "/api/headroom/start", // Headroom token-saver proxy lifecycle: spawns headroom-ai python CLI (Hard Rules #15 + #17) "/api/headroom/stop", // Headroom token-saver proxy lifecycle: sends SIGTERM/SIGKILL to managed PID (Hard Rules #15 + #17) - "/api/oauth/cursor/auto-import", // spawns `execFile("which", ["cursor"])` to verify a local Cursor install before importing creds — RCE-via-tunnel surface (Hard Rules #15 + #17, found by 6A.8 route-guard gate). Specific path only: the rest of /api/oauth/ (browser redirect/callback flows) must stay remote-reachable. + "/api/oauth/cursor/auto-import", // spawns `execFile("which", "cursor")` to verify a local Cursor install before importing creds — RCE-via-tunnel surface (Hard Rules #15 + #17, found by 6A.8 route-guard gate). Specific path only: the rest of /api/oauth/ (browser redirect/callback flows) must stay remote-reachable. "/api/skills/collect/", // Skill Collector CLI detection: GET .../detect probes getCliRuntimeStatus() per CLI_TOOL_IDS entry, which spawns a child process to check each tool — RCE-via-tunnel surface (Hard Rules #15 + #17, PR #6294 review). "/api/discovery/", // Discovery tool (opt-in provider scanner): the scan route makes outbound probes to provider endpoints (SSRF-adjacent) and the whole surface is an admin research tool — strict-loopback only, no manage-scope bypass (NOT in LOCAL_ONLY_MANAGE_SCOPE_BYPASS_PREFIXES). See _tasks/features-v3.8.42/gaps/DISCOVERY_TOOL_DESIGN.md. VNC_ROUTE_PREFIX, // #7892: /api/vnc-session/* spawns Docker containers via child_process.spawn (src/lib/vncSession/service.ts) — RCE-via-tunnel surface (Hard Rules #15 + #17), same CVE class (GHSA-fhh6-4qxv-rpqj). "/api/acp/agents", // ACP custom-agent registry: POST registers a client-chosen `binary`; GET / POST {action:"refresh"} runs detectInstalledAgents() -> execFileSync(probe.command, probe.args, { shell }) transitively (src/lib/acp/registry.ts) — RCE-via-tunnel surface (Hard Rules #15 + #17, #7948) + "/api/providers/cursor/agent-availability", // credential-free dashboard-nudge check: spawns `cursor-agent status --format json` via checkCursorAgentAvailability()/getCachedCursorAgentAvailability() (src/lib/cursor/renewal.ts) — RCE-via-tunnel surface (Hard Rules #15 + #17). Narrow-scoped like /login and /refresh-cursor, not the whole /api/providers/ tree. Placed under /api/providers/ rather than /api/oauth/ because /api/oauth/ is PUBLIC-classified and never reaches this LOCAL_ONLY gate. ]; /** diff --git a/src/shared/constants/spawnCapablePrefixes.ts b/src/shared/constants/spawnCapablePrefixes.ts index 5357cef34c..e1e285ea0e 100644 --- a/src/shared/constants/spawnCapablePrefixes.ts +++ b/src/shared/constants/spawnCapablePrefixes.ts @@ -50,6 +50,7 @@ export const SPAWN_CAPABLE_PREFIXES: ReadonlyArray = [ export const SPAWN_CAPABLE_PATTERNS: ReadonlyArray = [ /^\/api\/providers\/[^/]+\/login\/?$/, // pre-existing gap: in LOCAL_ONLY_API_PATTERNS today but never in a spawn-capable deny-list /^\/api\/providers\/[^/]+\/refresh-cursor\/?$/, // spawns cursor-agent via renewal.ts (Hard Rules #15 + #17) + /^\/api\/providers\/cursor\/agent-availability\/?$/, // static path (no dynamic segment), but kept in this array alongside its /api/providers/ siblings rather than the flat SPAWN_CAPABLE_PREFIXES array — spawns cursor-agent status via checkCursorAgentAvailability()/getCachedCursorAgentAvailability() (Hard Rules #15 + #17) ]; /** diff --git a/tests/unit/cursor-agent-availability-route-authenticated.test.ts b/tests/unit/cursor-agent-availability-route-authenticated.test.ts new file mode 100644 index 0000000000..1959910495 --- /dev/null +++ b/tests/unit/cursor-agent-availability-route-authenticated.test.ts @@ -0,0 +1,61 @@ +/** + * GET /api/providers/cursor/agent-availability — "authenticated -> true" case. + * Split from tests/unit/cursor-agent-availability-route.test.ts (its own + * process, so its own fresh getCachedCursorAgentAvailability() module cache — + * see that file's header comment for why the true/false cases can't share a + * process). + */ +import test from "node:test"; +import assert from "node:assert/strict"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; + +process.env.NODE_ENV = "test"; +const TEST_DATA_DIR = fs.mkdtempSync( + path.join(os.tmpdir(), "omniroute-agent-availability-route-auth-") +); +process.env.DATA_DIR = TEST_DATA_DIR; + +const core = await import("../../src/lib/db/core.ts"); +const { GET } = await import("../../src/app/api/providers/cursor/agent-availability/route.ts"); + +test.after(() => { + core.resetDbInstance(); + fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true }); +}); + +const FAKE_CURSOR_AGENT_SCRIPT = `#!/usr/bin/env node +const args = process.argv.slice(2); +if (args[0] === "status") { + process.stdout.write(JSON.stringify({ status: "authenticated", isAuthenticated: true })); +} +`; + +const originalHome = process.env.HOME; +const originalUserProfile = process.env.USERPROFILE; +const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-agent-availability-home-auth-")); +process.env.HOME = tmpHome; +process.env.USERPROFILE = tmpHome; +const binaryPath = path.join(tmpHome, ".local", "bin", "cursor-agent"); +fs.mkdirSync(path.dirname(binaryPath), { recursive: true }); +fs.writeFileSync(binaryPath, FAKE_CURSOR_AGENT_SCRIPT, { mode: 0o755 }); +fs.chmodSync(binaryPath, 0o755); + +test.after(() => { + process.env.HOME = originalHome; + if (originalUserProfile !== undefined) process.env.USERPROFILE = originalUserProfile; + else delete process.env.USERPROFILE; + fs.rmSync(tmpHome, { recursive: true, force: true }); +}); + +test("returns {cursorAgentAvailable: true} and ONLY that field when cursor-agent is authenticated", async () => { + const res = await GET(); + const body = (await res.json()) as Record; + + assert.equal(res.status, 200); + assert.deepEqual(Object.keys(body), ["cursorAgentAvailable"]); + assert.equal(body.cursorAgentAvailable, true); + assert.equal(body.accessToken, undefined); + assert.equal(body.machineId, undefined); +}); diff --git a/tests/unit/cursor-agent-availability-route.test.ts b/tests/unit/cursor-agent-availability-route.test.ts new file mode 100644 index 0000000000..c395a228d9 --- /dev/null +++ b/tests/unit/cursor-agent-availability-route.test.ts @@ -0,0 +1,116 @@ +/** + * GET /api/providers/cursor/agent-availability (Cursor renewal plan, Task 5). + * + * Real fake-cursor-agent-binary + HOME-override technique (see + * tests/unit/cursor-renewal.test.ts) to drive getCachedCursorAgentAvailability() + * for real — no mocking, same rationale as every other Cursor test file in + * this plan (no DI seam, no mock.module() support in this harness). + * + * getCachedCursorAgentAvailability() has a module-level 5-minute TTL cache + * with no exported reset hook, so this file only exercises ONE truth value + * through the live route (the "unauthenticated" default state a fresh test + * fixture naturally has) — a second call within the same process would + * silently replay the FIRST call's cached result regardless of a changed + * fixture, which would look like a passing assertion for the wrong reason. + * The "authenticated -> true" mapping is verified in a separate file + * (tests/unit/cursor-agent-availability-route-authenticated.test.ts, its own + * process, so its own fresh cache) — the TTL cache's own behavior (reuse + * within the window, fresh spawn after expiry) is covered directly in + * tests/unit/cursor-renewal.test.ts. + * + * DATA_DIR is overridden to a temp dir BEFORE any import below, since loading + * src/server/authz/policies/management.ts transitively touches the real DB + * singleton at import time. + */ +import test from "node:test"; +import assert from "node:assert/strict"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; + +process.env.NODE_ENV = "test"; +const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-agent-availability-route-")); +process.env.DATA_DIR = TEST_DATA_DIR; + +const core = await import("../../src/lib/db/core.ts"); +const { GET } = await import("../../src/app/api/providers/cursor/agent-availability/route.ts"); +const { managementPolicy } = await import("../../src/server/authz/policies/management.ts"); + +const FAKE_CURSOR_AGENT_SCRIPT = `#!/usr/bin/env node +const args = process.argv.slice(2); +if (args[0] === "status") { + const mode = process.env.FAKE_CURSOR_AGENT_STATUS_MODE || "unauthenticated"; + if (mode === "authenticated") { + process.stdout.write(JSON.stringify({ status: "authenticated", isAuthenticated: true })); + } else { + process.stdout.write(JSON.stringify({ status: "unauthenticated", isAuthenticated: false })); + } +} +`; + +test.after(() => { + core.resetDbInstance(); + fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true }); +}); + +function writeFakeCursorAgentBinary(destPath: string): void { + fs.mkdirSync(path.dirname(destPath), { recursive: true }); + fs.writeFileSync(destPath, FAKE_CURSOR_AGENT_SCRIPT, { mode: 0o755 }); + fs.chmodSync(destPath, 0o755); +} + +const originalHome = process.env.HOME; +const originalUserProfile = process.env.USERPROFILE; +const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-agent-availability-home-")); +process.env.HOME = tmpHome; +process.env.USERPROFILE = tmpHome; +process.env.FAKE_CURSOR_AGENT_STATUS_MODE = "unauthenticated"; +writeFakeCursorAgentBinary(path.join(tmpHome, ".local", "bin", "cursor-agent")); + +test.after(() => { + process.env.HOME = originalHome; + if (originalUserProfile !== undefined) process.env.USERPROFILE = originalUserProfile; + else delete process.env.USERPROFILE; + delete process.env.FAKE_CURSOR_AGENT_STATUS_MODE; + fs.rmSync(tmpHome, { recursive: true, force: true }); +}); + +test("returns {cursorAgentAvailable: false} and ONLY that field when cursor-agent is unauthenticated", async () => { + const res = await GET(); + const body = (await res.json()) as Record; + + assert.equal(res.status, 200); + assert.deepEqual(Object.keys(body), ["cursorAgentAvailable"]); + assert.equal(body.cursorAgentAvailable, false); + assert.equal(body.accessToken, undefined); + assert.equal(body.machineId, undefined); +}); + +// Loopback enforcement happens unconditionally before any auth check (Hard +// Rules #15 + #17): a non-loopback caller with NO credentials at all must +// still be rejected by the managementPolicy pipeline itself — never by an +// in-route check (this route intentionally has none; see route.ts's own +// comment on why). +test("a non-loopback, unauthenticated request is rejected by managementPolicy (403 LOCAL_ONLY), not by the route", async () => { + const requestPath = "/api/providers/cursor/agent-availability"; + const outcome = await managementPolicy.evaluate({ + request: { + method: "GET", + headers: new Headers(), + url: `https://dashboard.example${requestPath}`, + nextUrl: { pathname: requestPath }, + }, + classification: { + routeClass: "MANAGEMENT", + normalizedPath: requestPath, + reason: "management_api", + }, + requestId: "req_cursor_agent_availability_test", + } as unknown as Parameters[0]); + + assert.equal(outcome.allow, false); + if (!outcome.allow) { + assert.equal(outcome.status, 403); + assert.equal(outcome.code, "LOCAL_ONLY"); + } +}); diff --git a/tests/unit/cursor-renewal.test.ts b/tests/unit/cursor-renewal.test.ts index dd54633ec9..0d206826c1 100644 --- a/tests/unit/cursor-renewal.test.ts +++ b/tests/unit/cursor-renewal.test.ts @@ -29,6 +29,7 @@ import path from "node:path"; import { runCursorAgentNudge, checkCursorAgentAvailability, + getCachedCursorAgentAvailability, renewCursorConnection, buildCursorRenewedUpdate, runCursorRenewalExclusive, @@ -262,6 +263,63 @@ describe("checkCursorAgentAvailability", () => { }); }); +describe("getCachedCursorAgentAvailability (Task 5 Step 1 — 5-minute TTL wrapper for UI callers)", () => { + const ORIGINAL_HOME = process.env.HOME; + const ORIGINAL_USERPROFILE = process.env.USERPROFILE; + const CACHE_TTL_MS = 5 * 60 * 1000; // mirrors CURSOR_AGENT_AVAILABILITY_CACHE_TTL_MS in renewal.ts + let tmpHome: string; + let logPath: string; + + beforeEach(() => { + tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-cursor-avail-cache-")); + process.env.HOME = tmpHome; + process.env.USERPROFILE = tmpHome; + writeFakeCursorAgentBinary(path.join(tmpHome, ".local", "bin", "cursor-agent")); + logPath = path.join(tmpHome, "log.jsonl"); + process.env.FAKE_CURSOR_AGENT_LOG = logPath; + process.env.FAKE_CURSOR_AGENT_STATUS_MODE = "authenticated"; + }); + + afterEach(() => { + process.env.HOME = ORIGINAL_HOME; + if (ORIGINAL_USERPROFILE !== undefined) process.env.USERPROFILE = ORIGINAL_USERPROFILE; + else delete process.env.USERPROFILE; + clearFakeCursorAgentEnv(); + fs.rmSync(tmpHome, { recursive: true, force: true }); + }); + + // A single test, one continuous mocked timeline: getCachedCursorAgentAvailability()'s + // module-level cache has no exported reset hook and persists for the life of the + // process, so two separate `it()` blocks each assuming a "fresh" cache would be + // order-dependent (a later test could silently inherit an earlier test's still-valid + // cache entry, since node:test's per-test mock-timer teardown restores the REAL clock + // between tests, not the fake one — the leftover `expiresAt` would still be far in + // that real future). Keeping both assertions on one uninterrupted fake clock avoids that. + it("reuses the cached result within the TTL window, then spawns exactly once more after it expires", async (t) => { + t.mock.timers.enable({ apis: ["Date"] }); + + const first = await getCachedCursorAgentAvailability(); + assert.equal(readLoggedInvocations(logPath).length, 1, "the first call must spawn"); + + t.mock.timers.tick(CACHE_TTL_MS - 1000); // still inside the window + const second = await getCachedCursorAgentAvailability(); + assert.deepEqual(first, second); + assert.equal( + readLoggedInvocations(logPath).length, + 1, + "still within the TTL — no second spawn" + ); + + t.mock.timers.tick(2000); // now past the TTL (cumulative: TTL + 1000ms) + await getCachedCursorAgentAvailability(); + assert.equal( + readLoggedInvocations(logPath).length, + 2, + "expiry must trigger exactly one fresh spawn" + ); + }); +}); + describe("renewCursorConnection", () => { const ORIGINAL_HOME = process.env.HOME; const ORIGINAL_USERPROFILE = process.env.USERPROFILE; diff --git a/tests/unit/route-guard-cursor-agent-availability.test.ts b/tests/unit/route-guard-cursor-agent-availability.test.ts new file mode 100644 index 0000000000..bec0dc0fe2 --- /dev/null +++ b/tests/unit/route-guard-cursor-agent-availability.test.ts @@ -0,0 +1,49 @@ +/** + * Security regression (Cursor renewal plan, Task 5): GET + * /api/providers/cursor/agent-availability is a credential-free check for the + * dashboard's install-nudge banner, but it still spawns `cursor-agent status + * --format json` (via checkCursorAgentAvailability()/ + * getCachedCursorAgentAvailability()) — so it MUST be LOCAL_ONLY, same as + * every other spawn-capable route (Hard Rules #15 + #17). + * + * Unlike Task 4's refresh-cursor route, this one is a STATIC path (no dynamic + * `[id]` segment), so it's classified via the flat LOCAL_ONLY_API_PREFIXES + * list, not a regex in LOCAL_ONLY_API_PATTERNS. It was originally scoped + * under `/api/oauth/cursor/agent-availability` during planning, then + * relocated under `/api/providers/` because `/api/oauth/` is PUBLIC-classified + * (see classify.ts) and never reaches the LOCAL_ONLY gate at all — see + * docs/security/ROUTE_GUARD_TIERS.md. The classifyRoute assertion below pins + * that decision as a regression guard against ever moving this back. + */ +import test from "node:test"; +import assert from "node:assert/strict"; +import { isLocalOnlyPath } from "../../src/server/authz/routeGuard.ts"; +import { classifyRoute } from "../../src/server/authz/classify.ts"; + +test("/api/providers/cursor/agent-availability is LOCAL_ONLY (spawns cursor-agent status)", () => { + assert.equal(isLocalOnlyPath("/api/providers/cursor/agent-availability"), true); +}); + +test("/api/providers/cursor/agent-availability with a trailing slash is LOCAL_ONLY", () => { + assert.equal(isLocalOnlyPath("/api/providers/cursor/agent-availability/"), true); +}); + +test("classifyRoute resolves this path to MANAGEMENT, never PUBLIC (regression guard against moving it under /api/oauth/)", () => { + const classification = classifyRoute("/api/providers/cursor/agent-availability", "GET"); + assert.equal(classification.routeClass, "MANAGEMENT"); +}); + +test("does not over-match unrelated /api/providers paths", () => { + // LOCAL_ONLY_API_PREFIXES entries are matched via plain startsWith (see + // isLocalOnlyPath) — like every other exact-path-style sibling entry in + // that array (e.g. /api/system/version, /api/oauth/cursor/auto-import, + // /api/acp/agents), this is a bare path with no trailing slash, so it is + // NOT segment-boundary-anchored the way the regex-based /login and + // /refresh-cursor entries in LOCAL_ONLY_API_PATTERNS are (see + // tests/unit/route-guard-cursor-refresh.test.ts). Only paths that don't + // share the prefix at all are meaningful negative cases here. + assert.equal(isLocalOnlyPath("/api/providers"), false); + assert.equal(isLocalOnlyPath("/api/providers/"), false); + assert.equal(isLocalOnlyPath("/api/providers/cursor"), false); + assert.equal(isLocalOnlyPath("/api/providers/abc123/refresh"), false); +});