refactor(sandbox): extract validateSandboxReconnectRequest + fix preview build

Two changes bundled:

1) SRP per review feedback (sweetmantech) — extract the auth +
   sessionId-from-query + session lookup + ownership check pre-flight
   from `getSandboxReconnectHandler` into its own
   `validateSandboxReconnectRequest.ts`. Mirrors the
   `validateCreateSandboxBody` pattern: returns either a 4xx
   NextResponse describing the first failure, or `{ row, auth }` for
   the handler to consume.

2) Type fix for `next build` — `connectSandbox(row.sandbox_state as
   SandboxState)` failed to compile against `Json` (union includes
   primitives + arrays); cast through `unknown` first. The
   `hasRuntimeSandboxState` gate above ensures the runtime shape is
   safe at the call site, so the double cast is justified — comment
   added explaining why.

The vitest pass alone wasn't enough to catch the type error — `next
build` runs a separate `tsc` step that the test runner skips. Caught
by the Vercel preview build failing on the previous commit.

TDD red -> green:
- 5 unit tests for the new validator covering auth fail (passes
  through), missing sessionId (400), session not found (404),
  ownership mismatch (403), and happy-path return shape ({row, auth})
- Existing handler tests pass unchanged — the module-level mocks for
  validateAuthContext / selectSessions still intercept the calls now
  that they're behind the new validator
- Suite: 2529 -> 2534, pnpm lint:check clean

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sweetmantech

lib/sandbox/__tests__/validateSandboxReconnectRequest.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { NextRequest, NextResponse } from "next/server";
+
+import { validateSandboxReconnectRequest } from "@/lib/sandbox/validateSandboxReconnectRequest";
+import { validateAuthContext } from "@/lib/auth/validateAuthContext";
+import { selectSessions } from "@/lib/supabase/sessions/selectSessions";
+
+vi.mock("@/lib/networking/getCorsHeaders", () => ({
+  getCorsHeaders: () => ({ "Access-Control-Allow-Origin": "*" }),
+}));
+vi.mock("@/lib/auth/validateAuthContext", () => ({
+  validateAuthContext: vi.fn(),
+}));
+vi.mock("@/lib/supabase/sessions/selectSessions", () => ({
+  selectSessions: vi.fn(),
+}));
+
+const ACCOUNT_ID = "acc-1";
+const baseRow = { id: "sess-1", account_id: ACCOUNT_ID } as never;
+
+function makeReq(query = "?sessionId=sess-1"): NextRequest {
+  return new NextRequest(`http://localhost/api/sandbox/reconnect${query}`, { method: "GET" });
+}
+
+describe("validateSandboxReconnectRequest", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(validateAuthContext).mockResolvedValue({
+      accountId: ACCOUNT_ID,
+      orgId: null,
+      authToken: "k",
+    });
+  });
+
+  it("returns the auth response unchanged when auth fails", async () => {
+    const fail = NextResponse.json({ status: "error", error: "Unauthorized" }, { status: 401 });
+    vi.mocked(validateAuthContext).mockResolvedValueOnce(fail);
+
+    const result = await validateSandboxReconnectRequest(makeReq());
+
+    expect(result).toBe(fail);
+  });
+
+  it("returns 400 when sessionId is missing from the query", async () => {
+    const result = await validateSandboxReconnectRequest(makeReq(""));
+
+    expect(result).toBeInstanceOf(NextResponse);
+    expect((result as NextResponse).status).toBe(400);
+  });
+
+  it("returns 404 when no session exists with the given id", async () => {
+    vi.mocked(selectSessions).mockResolvedValue([]);
+
+    const result = await validateSandboxReconnectRequest(makeReq());
+
+    expect(result).toBeInstanceOf(NextResponse);
+    expect((result as NextResponse).status).toBe(404);
+  });
+
+  it("returns 403 when the session is not owned by the authenticated account", async () => {
+    vi.mocked(selectSessions).mockResolvedValue([
+      { ...baseRow, account_id: "someone-else" } as never,
+    ]);
+
+    const result = await validateSandboxReconnectRequest(makeReq());
+
+    expect(result).toBeInstanceOf(NextResponse);
+    expect((result as NextResponse).status).toBe(403);
+  });
+
+  it("returns the validated row + auth on the happy path", async () => {
+    vi.mocked(selectSessions).mockResolvedValue([baseRow]);
+
+    const result = await validateSandboxReconnectRequest(makeReq());
+
+    expect(result).not.toBeInstanceOf(NextResponse);
+    if (result instanceof NextResponse) return;
+    expect(result.row.id).toBe("sess-1");
+    expect(result.auth.accountId).toBe(ACCOUNT_ID);
+  });
+});

lib/sandbox/getSandboxReconnectHandler.ts

@@ -1,11 +1,10 @@
 import { NextRequest, NextResponse } from "next/server";
 import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
-import { validateAuthContext } from "@/lib/auth/validateAuthContext";
 import { buildLifecycle } from "@/lib/sandbox/buildLifecycle";
 import { connectSandbox } from "@/lib/sandbox/factory";
 import { hasRuntimeSandboxState } from "@/lib/sandbox/hasRuntimeSandboxState";
 import { noSandboxResponse } from "@/lib/sandbox/noSandboxResponse";
-import { selectSessions } from "@/lib/supabase/sessions/selectSessions";
+import { validateSandboxReconnectRequest } from "@/lib/sandbox/validateSandboxReconnectRequest";
 import { updateSession } from "@/lib/supabase/sessions/updateSession";
 import type { SandboxState } from "@/lib/sandbox/factory";
 
@@ -31,42 +30,21 @@ interface ReconnectBody {
  * `GET /api/sandbox/status` agree with the probe.
  */
 export async function getSandboxReconnectHandler(request: NextRequest): Promise<NextResponse> {
-  const auth = await validateAuthContext(request);
-  if (auth instanceof NextResponse) {
-    return auth;
-  }
-
-  const sessionId = request.nextUrl.searchParams.get("sessionId");
-  if (!sessionId) {
-    return NextResponse.json(
-      { status: "error", error: "Missing sessionId" },
-      { status: 400, headers: getCorsHeaders() },
-    );
-  }
-
-  const rows = await selectSessions({ id: sessionId });
-  const row = rows[0];
-
-  if (!row) {
-    return NextResponse.json(
-      { status: "error", error: "Session not found" },
-      { status: 404, headers: getCorsHeaders() },
-    );
-  }
-
-  if (row.account_id !== auth.accountId) {
-    return NextResponse.json(
-      { status: "error", error: "Forbidden" },
-      { status: 403, headers: getCorsHeaders() },
-    );
+  const validated = await validateSandboxReconnectRequest(request);
+  if (validated instanceof NextResponse) {
+    return validated;
   }
+  const { row } = validated;
 
   if (!hasRuntimeSandboxState(row.sandbox_state)) {
     return noSandboxResponse(row);
   }
 
   try {
-    const sandbox = await connectSandbox(row.sandbox_state as SandboxState);
+    // Safe cast: hasRuntimeSandboxState above narrowed sandbox_state to an
+    // object with a non-empty `sandboxName` — but the Json type is wider, so
+    // TS needs the unknown bridge to accept the conversion.
+    const sandbox = await connectSandbox(row.sandbox_state as unknown as SandboxState);
     await sandbox.exec("pwd", sandbox.workingDirectory, PROBE_TIMEOUT_MS);
 
     const body: ReconnectBody = {
@@ -78,9 +56,9 @@ export async function getSandboxReconnectHandler(request: NextRequest): Promise<
     return NextResponse.json(body, { status: 200, headers: getCorsHeaders() });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    console.warn(`[getSandboxReconnectHandler] probe failed for ${sessionId}: ${message}`);
+    console.warn(`[getSandboxReconnectHandler] probe failed for ${row.id}: ${message}`);
 
-    await updateSession(sessionId, {
+    await updateSession(row.id, {
       sandbox_state: null,
       lifecycle_state: "hibernated",
       sandbox_expires_at: null,

lib/sandbox/validateSandboxReconnectRequest.ts

@@ -0,0 +1,60 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { validateAuthContext } from "@/lib/auth/validateAuthContext";
+import type { AuthContext } from "@/lib/auth/validateAuthContext";
+import { selectSessions } from "@/lib/supabase/sessions/selectSessions";
+import type { Tables } from "@/types/database.types";
+
+export interface ValidatedSandboxReconnectRequest {
+  row: Tables<"sessions">;
+  auth: AuthContext;
+}
+
+/**
+ * Validates a `GET /api/sandbox/reconnect` request end-to-end:
+ *   1. Authenticates the caller via Privy Bearer / x-api-key
+ *   2. Requires a `sessionId` query parameter
+ *   3. Looks up the session row
+ *   4. Enforces ownership (the authed account must match `account_id`)
+ *
+ * Returns either a 4xx NextResponse describing the first failure, or
+ * the validated `{ row, auth }` ready for the handler to consume.
+ *
+ * @param request - The incoming GET request.
+ * @returns A NextResponse on validation failure, or the validated row + auth.
+ */
+export async function validateSandboxReconnectRequest(
+  request: NextRequest,
+): Promise<NextResponse | ValidatedSandboxReconnectRequest> {
+  const auth = await validateAuthContext(request);
+  if (auth instanceof NextResponse) {
+    return auth;
+  }
+
+  const sessionId = request.nextUrl.searchParams.get("sessionId");
+  if (!sessionId) {
+    return NextResponse.json(
+      { status: "error", error: "Missing sessionId" },
+      { status: 400, headers: getCorsHeaders() },
+    );
+  }
+
+  const rows = await selectSessions({ id: sessionId });
+  const row = rows[0];
+
+  if (!row) {
+    return NextResponse.json(
+      { status: "error", error: "Session not found" },
+      { status: 404, headers: getCorsHeaders() },
+    );
+  }
+
+  if (row.account_id !== auth.accountId) {
+    return NextResponse.json(
+      { status: "error", error: "Forbidden" },
+      { status: 403, headers: getCorsHeaders() },
+    );
+  }
+
+  return { row, auth };
+}