fix: validate DoltHub token at connect time and show expiry reason on reconnect

Three improvements for users with invalid/expired DoltHub API keys:

1. Proactive validation: handleConnect and handleJoin now probe DoltHub
   with the API key before creating a session. Bad keys are rejected
   immediately with a clear message about tokens vs credentials.

2. Auth-aware error handling: handleBrowse and handleDetail now detect
   "invalid authorization" errors and return 401 instead of serving
   stale data or a generic "upstream unavailable" 503. This triggers
   the frontend re-auth redirect.

3. Expiry UX: the frontend now passes reason=expired when redirecting
   to /connect on 401, and the connect page shows a styled error banner
   explaining the token expired and linking to DoltHub token settings.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: julianknutsen

internal/api/handlers.go

@@ -52,6 +52,11 @@ func (s *Server) handleBrowse(w http.ResponseWriter, r *http.Request) {
 		return json.Marshal(toBrowseResponse(result))
 	})
 	if err != nil {
+		// Auth errors should not serve stale data — the user needs to reconnect.
+		if isUpstreamAuthError(err) {
+			writeError(w, http.StatusUnauthorized, "DoltHub credentials expired — please reconnect.")
+			return
+		}
 		// Try to serve stale cache data with a warning instead of a hard error.
 		stale := s.browseCache.GetStale(key)
 		if stale != nil {
@@ -104,6 +109,11 @@ func (s *Server) handleDetail(w http.ResponseWriter, r *http.Request) {
 			writeError(w, http.StatusNotFound, err.Error())
 			return
 		}
+		// Auth errors should not serve stale data — the user needs to reconnect.
+		if isUpstreamAuthError(err) {
+			writeError(w, http.StatusUnauthorized, "DoltHub credentials expired — please reconnect.")
+			return
+		}
 		// Try stale cache before returning a hard error.
 		if stale := s.detailCache.GetStale(key); stale != nil {
 			slog.Warn("serving stale detail data due to upstream error", "error", err)
@@ -227,12 +237,17 @@ func (s *Server) invalidateAllCaches() {
 	s.detailCache.Invalidate()
 }
 
+// isUpstreamAuthError returns true if the error is a DoltHub authentication
+// failure (expired or invalid API key).
+func isUpstreamAuthError(err error) bool {
+	return strings.Contains(err.Error(), "invalid authorization")
+}
+
 // writeUpstreamError classifies DoltHub errors and writes an appropriate response:
 //   - "invalid authorization" → 401 (triggers frontend re-auth)
 //   - other upstream errors → 503 with sanitized message + Sentry capture
 func writeUpstreamError(w http.ResponseWriter, err error, label string) {
-	msg := err.Error()
-	if strings.Contains(msg, "invalid authorization") {
+	if isUpstreamAuthError(err) {
 		writeError(w, http.StatusUnauthorized, "DoltHub credentials expired — please reconnect.")
 		return
 	}

internal/hosted/main_test.go

@@ -0,0 +1,13 @@
+package hosted
+
+import (
+	"os"
+	"testing"
+)
+
+func TestMain(m *testing.M) {
+	// Disable the real DoltHub probe during tests — test Nango servers
+	// return fake API keys that would fail validation.
+	ProbeDoltHubToken = func(string) error { return nil }
+	os.Exit(m.Run())
+}

internal/hosted/server.go

@@ -2,9 +2,12 @@ package hosted
 
 import (
 	"encoding/json"
+	"fmt"
+	"io"
 	"io/fs"
 	"log/slog"
 	"net/http"
+	"strings"
 	"time"
 
 	"github.com/gastownhall/wasteland/internal/api"
@@ -106,6 +109,15 @@ func (s *Server) handleConnect(w http.ResponseWriter, r *http.Request) {
 	if err != nil || meta == nil {
 		meta = &UserMetadata{RigHandle: req.RigHandle}
 	}
+
+	// Verify the DoltHub API key works before proceeding.
+	if err := ProbeDoltHubToken(apiKey); err != nil {
+		writeJSON(w, http.StatusBadRequest, map[string]string{
+			"error": "DoltHub API key is invalid — please reconnect your DoltHub account. Verify you created an API token (not a credential) in DoltHub.",
+		})
+		return
+	}
+
 	meta.RigHandle = req.RigHandle
 	meta.UpsertWasteland(WastelandConfig{
 		Upstream: req.Upstream,
@@ -309,6 +321,14 @@ func (s *Server) handleJoin(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// Verify the DoltHub API key still works before joining.
+	if err := ProbeDoltHubToken(apiKey); err != nil {
+		writeJSON(w, http.StatusBadRequest, map[string]string{
+			"error": "DoltHub API key is invalid — please reconnect your DoltHub account. Verify you created an API token (not a credential) in DoltHub.",
+		})
+		return
+	}
+
 	meta.UpsertWasteland(WastelandConfig{
 		Upstream: req.Upstream,
 		ForkOrg:  req.ForkOrg,
@@ -465,6 +485,36 @@ func healthHandler() http.HandlerFunc {
 	}
 }
 
+// ProbeDoltHubToken verifies a DoltHub API key by running a lightweight query.
+// Returns nil if the key is valid (or empty), error if DoltHub rejects it.
+// Var so tests can override.
+var ProbeDoltHubToken = func(apiKey string) error {
+	if apiKey == "" {
+		return nil
+	}
+	req, err := http.NewRequest("GET",
+		"https://www.dolthub.com/api/v1alpha1/hop/wl-commons/main?q=SELECT%201", nil)
+	if err != nil {
+		return nil // don't block connect for request construction errors
+	}
+	req.Header.Set("authorization", "token "+apiKey)
+
+	client := &http.Client{Timeout: 5 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil // network error — don't block connect for transient issues
+	}
+	defer resp.Body.Close() //nolint:errcheck // best-effort close
+
+	if resp.StatusCode == http.StatusBadRequest {
+		body, _ := io.ReadAll(resp.Body)
+		if strings.Contains(string(body), "invalid authorization") {
+			return fmt.Errorf("DoltHub rejected the API key")
+		}
+	}
+	return nil
+}
+
 // writeJSON writes a JSON response (duplicated here to avoid circular import
 // with the api package, which provides the canonical version).
 func writeJSON(w http.ResponseWriter, status int, v any) {

web/src/api/client.ts

@@ -111,7 +111,8 @@ async function request<T>(path: string, init?: RequestInit): Promise<T> {
   if (resp.status === 401 || resp.status === 412) {
     if (typeof window !== "undefined" && !window.location.pathname.startsWith("/connect")) {
       const returnTo = window.location.pathname + window.location.search;
-      window.location.href = `/connect?return_to=${encodeURIComponent(returnTo)}`;
+      const reason = resp.status === 401 ? "&reason=expired" : "";
+      window.location.href = `/connect?return_to=${encodeURIComponent(returnTo)}${reason}`;
       // Return a never-resolving promise to prevent callers from processing stale data.
       return new Promise<T>(() => {});
     }

web/src/components/ConnectPage.module.css

@@ -60,6 +60,17 @@
   line-height: 1.5;
 }
 
+.errorHint {
+  color: var(--red);
+  font-size: var(--text-sm);
+  margin-bottom: var(--space-3);
+  line-height: 1.5;
+  padding: 10px 14px;
+  background: color-mix(in srgb, var(--red) 8%, transparent);
+  border: 1px solid color-mix(in srgb, var(--red) 25%, transparent);
+  border-radius: var(--radius-sm);
+}
+
 .actions {
   display: flex;
   gap: var(--space-2);

web/src/components/ConnectPage.tsx

@@ -14,6 +14,7 @@ export function ConnectPage() {
 
   const rawReturnTo = searchParams.get("return_to");
   const returnTo = rawReturnTo && /^\/[^/]/.test(rawReturnTo) ? rawReturnTo : null;
+  const reason = searchParams.get("reason");
   const [view, setView] = useState<"connect" | "join">("connect");
   const [loading, setLoading] = useState(true);
   const [submitting, setSubmitting] = useState(false);
@@ -129,7 +130,22 @@ export function ConnectPage() {
 
   return (
     <div className={styles.page}>
-      {returnTo && <p className={styles.hint}>Sign in to continue.</p>}
+      {reason === "expired" && (
+        <p className={styles.errorHint}>
+          Your DoltHub API token has expired or is invalid. Please reconnect. Make sure you create an API{" "}
+          <strong>token</strong> (not a credential) at{" "}
+          <a
+            href="https://www.dolthub.com/settings/tokens"
+            target="_blank"
+            rel="noopener noreferrer"
+            className={styles.link}
+          >
+            dolthub.com/settings/tokens
+          </a>
+          .
+        </p>
+      )}
+      {returnTo && !reason && <p className={styles.hint}>Sign in to continue.</p>}
       <h2 className={styles.heading}>{view === "join" ? "Join a Wasteland" : "Connect to Wasteland"}</h2>
 
       {view === "join" && (