From 6cc6c36a69c4751137ba7fd9ecea4b06124afad0 Mon Sep 17 00:00:00 2001
From: Andrew <43323844+snowdamiz@users.noreply.github.com>
Date: Thu, 26 Mar 2026 18:17:12 -0400
Subject: [PATCH] =?UTF-8?q?fix(web):=20auth=20token=20gate=20=E2=80=94=20s?=
 =?UTF-8?q?ynthetic=20401=20on=20missing=20token,=20unauthenticated=20boot?=
 =?UTF-8?q?=20state,=20and=20recovery=20screen=20(#2740)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When `gsd --web` is opened without the #token= hash fragment (manual URL
entry, bookmark, new tab), `authenticatedFetch` previously fell through to
a naked `fetch()` that always returned 401, flooding the console with
cascading errors and leaving the UI in a broken state with no recovery path.

Three changes:

1. `web/lib/auth.ts` — `authFetch()` now returns a synthetic 401 Response
   when `getAuthToken()` returns null instead of delegating to bare fetch.
   This makes missing-token failures consistent and immediately catchable
   by all callers without a network round-trip.

2. `web/lib/gsd-workspace-store.tsx` — Added `"unauthenticated"` to
   `WorkspaceStatus`. `refreshBoot()` now detects a 401 response from
   /api/boot and patches `bootStatus` to `"unauthenticated"` instead of
   throwing a generic error. This is a distinct state — not an error worth
   retrying, but a configuration problem the user must resolve.

3. `web/components/gsd/app-shell.tsx` — Added an early-return guard that
   renders a minimal "Authentication Required" screen when
   `bootStatus === "unauthenticated"`. The screen explains the problem and
   tells users to copy the full terminal URL (including `#token=…`) or
   restart with `gsd --web`.

Fixes #2731
---
 web/components/gsd/app-shell.tsx | 35 ++++++++++++++++++++++++++++++++
 web/lib/auth.ts                  | 12 ++++++++++-
 web/lib/gsd-workspace-store.tsx  |  9 +++++++-
 3 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/web/components/gsd/app-shell.tsx b/web/components/gsd/app-shell.tsx
index 3b0da7b49..88442c53b 100644
--- a/web/components/gsd/app-shell.tsx
+++ b/web/components/gsd/app-shell.tsx
@@ -235,6 +235,41 @@ function WorkspaceChrome() {
     detection.kind !== "active-gsd" &&
     detection.kind !== "empty-gsd"
 
+  // --- Unauthenticated gate ---
+  // Render a clear recovery screen before any workspace chrome is mounted so
+  // users who open a manually-typed URL (no #token= fragment) get actionable
+  // guidance instead of a cascade of 401 errors.
+  if (workspace.bootStatus === "unauthenticated") {
+    return (
+      <div className="flex h-dvh flex-col items-center justify-center gap-6 bg-background p-8 text-center">
+        <Image
+          src="/logo-black.svg"
+          alt="GSD"
+          width={57}
+          height={16}
+          className="shrink-0 h-4 w-auto dark:hidden"
+        />
+        <Image
+          src="/logo-white.svg"
+          alt="GSD"
+          width={57}
+          height={16}
+          className="shrink-0 h-4 w-auto hidden dark:block"
+        />
+        <div className="flex flex-col items-center gap-2">
+          <h1 className="text-lg font-semibold text-foreground">Authentication Required</h1>
+          <p className="max-w-sm text-sm text-muted-foreground">
+            This workspace requires an auth token. Copy the full URL from your terminal
+            (including the{" "}
+            <code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">#token=…</code>{" "}
+            part) or restart with{" "}
+            <code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">gsd --web</code>.
+          </p>
+        </div>
+      </div>
+    )
+  }
+
   return (
     <div className="relative flex h-screen flex-col overflow-hidden bg-background text-foreground">
       <header className="flex h-12 flex-shrink-0 items-center justify-between border-b border-border bg-card px-2 md:px-4">
diff --git a/web/lib/auth.ts b/web/lib/auth.ts
index 47ac0515f..780df8be1 100644
--- a/web/lib/auth.ts
+++ b/web/lib/auth.ts
@@ -81,10 +81,20 @@ export function authHeaders(extra?: Record<string, string>): Record<string, stri
 
 /**
  * Wrapper around `fetch()` that automatically injects the auth token.
+ *
+ * When no token is available (missing `#token=` fragment and no sessionStorage
+ * entry), returns a synthetic 401 Response instead of making an unauthenticated
+ * request that will fail server-side anyway. This lets callers handle the
+ * missing-token case uniformly rather than silently cascading 401s.
  */
 export async function authFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
   const token = getAuthToken()
-  if (!token) return fetch(input, init)
+  if (!token) {
+    return new Response(JSON.stringify({ error: "No auth token available" }), {
+      status: 401,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
 
   const headers = new Headers(init?.headers)
   if (!headers.has("Authorization")) {
diff --git a/web/lib/gsd-workspace-store.tsx b/web/lib/gsd-workspace-store.tsx
index 335085c47..567910ed9 100644
--- a/web/lib/gsd-workspace-store.tsx
+++ b/web/lib/gsd-workspace-store.tsx
@@ -66,7 +66,7 @@ import type {
 } from "./session-browser-contract"
 import { authFetch, appendAuthParam } from "./auth"
 
-export type WorkspaceStatus = "idle" | "loading" | "ready" | "error"
+export type WorkspaceStatus = "idle" | "loading" | "ready" | "error" | "unauthenticated"
 export type WorkspaceConnectionState =
   | "idle"
   | "connecting"
@@ -4135,6 +4135,13 @@ export class GSDWorkspaceStore {
         })
 
         if (!response.ok) {
+          if (response.status === 401) {
+            this.patchState({
+              bootStatus: "unauthenticated",
+              connectionState: "error",
+            })
+            return
+          }
           throw new Error(`Boot request failed with ${response.status}`)
         }