feat(server): self-explaining 403 for rejected forwarded hosts (#568)

## Summary

Follow-up to the 403 path discussed in #562. When agentsview is reached through SSH port-forwarding, a reverse proxy, or a remote dev environment (exe.dev, Codespaces, Coder, WSL2), the browser sends a `Host` the server does not trust, so `/api/v1/settings` is rejected with a bare `403 Forbidden` — with no server log and no body explaining why. The only escape was already knowing to pass `--public-url`.

This makes the existing behavior self-explaining without loosening it:

- **Server:** on a host-check rejection, `hostCheckMiddleware` writes a breadcrumb to the debug log (rejected `Host`, the allowed set, and a `--public-url` hint) and returns a descriptive `403` body instead of bare "Forbidden". Fails closed exactly as before — the DNS-rebinding guard is unchanged.
- **Frontend:** the settings store surfaces an actionable origin-rejection message on `403` (preferring the server's descriptive body), rather than the generic error. Complements #563, which stopped `403` from showing the misleading auth-token prompt.
- **Docs:** a "Remote / forwarded access" section in the README covering the forwarded-host case and the `--public-url` / `--public-origin` flags.

Verified end-to-end against the compiled binary on a single machine, including a real `socat` port-forward (equivalent to `ssh -L`) that reproduces the bare 403, and confirmation that `--public-url <forwarded-origin>` resolves it while an untrusted Host still gets 403. The breadcrumb lands in `<dataDir>/debug.log` — the same file referenced in #562.

Refs #562

Co-authored-by: Matthew Jacobs <mjacobs@users.noreply.github.com>

Author: mjacobs

README.md

@@ -44,6 +44,29 @@ On first run, agentsview discovers sessions from every supported agent on your
 machine, syncs them into a local SQLite database, and opens a web UI at
 `http://127.0.0.1:8080`.
 
+## Remote / forwarded access
+
+agentsview binds to loopback and validates the request `Host` header to guard
+against DNS-rebinding attacks. When you reach it through SSH port-forwarding, a
+reverse proxy, or a remote dev environment (exe.dev, Codespaces, Coder, WSL2),
+the browser sends a `Host` that the server does not recognize, so API requests
+such as `/api/v1/settings` are rejected with `403 Forbidden`.
+
+To fix this, restart the server with `--public-url` set to the exact origin you
+open in the browser:
+
+```bash
+# Browser opens http://127.0.0.1:18080 via `ssh -L 18080:127.0.0.1:8080 host`
+agentsview serve --public-url http://127.0.0.1:18080
+
+# Browser opens a forwarded hostname
+agentsview serve --public-url https://your-workspace.exe.dev
+```
+
+Use `--public-origin` (repeatable or comma-separated) to trust additional
+browser origins. If you expose the UI beyond loopback, also enable
+`--require-auth`.
+
 ## Docker
 
 The container image defaults to local `agentsview serve`. Set `PG_SERVE=1` to

frontend/src/lib/stores/settings.svelte.ts

@@ -7,6 +7,25 @@ import {
   isRemoteConnection,
 } from "../api/client.js";
 
+/** Build an actionable message for a 403 from the settings API. A
+ *  403 means the server rejected the request origin/Host (not that a
+ *  token is required), which typically happens behind SSH
+ *  port-forwarding, a reverse proxy, or a remote dev environment.
+ *  Newer servers return a descriptive body; for older servers that
+ *  return a bare "Forbidden", supply the actionable hint ourselves. */
+function forbiddenMessage(serverMessage: string): string {
+  const detail = serverMessage.trim();
+  if (detail && detail.toLowerCase() !== "forbidden") {
+    return detail;
+  }
+  return (
+    "Server rejected this origin. If you are reaching agentsview " +
+    "through SSH port-forwarding, a reverse proxy, or a remote dev " +
+    "environment, restart it with --public-url <origin> matching the " +
+    "URL in your browser."
+  );
+}
+
 class SettingsStore {
   agentDirs: Record<string, string[]> = $state({});
   githubConfigured: boolean = $state(false);
@@ -46,6 +65,8 @@ class SettingsStore {
     } catch (e) {
       if (e instanceof ApiError && e.status === 401) {
         this.needsAuth = true;
+      } else if (e instanceof ApiError && e.status === 403) {
+        this.error = forbiddenMessage(e.message);
       } else {
         this.error =
           e instanceof Error ? e.message : "Failed to load settings";

frontend/src/lib/stores/settings.test.ts

@@ -48,14 +48,29 @@ describe("SettingsStore.load auth handling", () => {
     expect(settings.error).toBeNull();
   });
 
-  it("does not prompt for a token on non-auth 403 responses", async () => {
+  it("surfaces an actionable hint on a bare 403", async () => {
     vi.mocked(api.getSettings).mockRejectedValue(
       new ApiError(403, "Forbidden"),
     );
 
     await settings.load();
 
     expect(settings.needsAuth).toBe(false);
-    expect(settings.error).toBe("Forbidden");
+    expect(settings.error).toContain("--public-url");
+  });
+
+  it("preserves a descriptive 403 body from the server", async () => {
+    const detail =
+      'Forbidden: request Host "127.0.0.1:18080" is not in the ' +
+      "allowed set [127.0.0.1:8080 localhost:8080]. restart with " +
+      "--public-url http://127.0.0.1:18080.";
+    vi.mocked(api.getSettings).mockRejectedValue(
+      new ApiError(403, detail),
+    );
+
+    await settings.load();
+
+    expect(settings.needsAuth).toBe(false);
+    expect(settings.error).toBe(detail);
   });
 });

internal/server/server.go

@@ -9,6 +9,7 @@ import (
 	"net"
 	"net/http"
 	"net/url"
+	"sort"
 	"strconv"
 	"strings"
 	gosync "sync"
@@ -617,8 +618,17 @@ func hostCheckMiddleware(
 				hostAllowed = isAllowedBindAllHost(r.Host, port, allowedIPs)
 			}
 			if !hostAllowed {
+				allowed := sortedHosts(allowedHosts)
+				log.Printf(
+					"host check rejected %s %s: Host %q not in allowed "+
+						"set %v; if reaching agentsview through a forwarded "+
+						"port or remote host, restart with --public-url "+
+						"<origin> matching your browser URL",
+					r.Method, r.URL.Path, r.Host, allowed,
+				)
 				http.Error(
-					w, "Forbidden", http.StatusForbidden,
+					w, hostRejectionMessage(r.Host, allowed),
+					http.StatusForbidden,
 				)
 				return
 			}
@@ -627,6 +637,33 @@ func hostCheckMiddleware(
 	})
 }
 
+// sortedHosts returns the allowed Host header values as a sorted
+// slice for deterministic log and error output.
+func sortedHosts(hosts map[string]bool) []string {
+	out := make([]string, 0, len(hosts))
+	for h := range hosts {
+		out = append(out, h)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// hostRejectionMessage builds a self-explaining 403 body for a
+// rejected Host header. It names the offending Host, lists the
+// allowed values, and points at --public-url so users behind SSH
+// port-forwarding, reverse proxies, or remote dev environments
+// (exe.dev, Codespaces, Coder, WSL2) can diagnose without devtools.
+func hostRejectionMessage(host string, allowed []string) string {
+	return fmt.Sprintf(
+		"Forbidden: request Host %q is not in the allowed set %v. "+
+			"If you are reaching agentsview through SSH port-forwarding, "+
+			"a reverse proxy, or a remote dev environment, restart the "+
+			"server with --public-url <origin> matching the URL in your "+
+			"browser (for example --public-url http://%s).",
+		host, allowed, host,
+	)
+}
+
 // httpOrigin formats an HTTP origin string. It uses
 // net.JoinHostPort to handle IPv6 bracket formatting correctly
 // (e.g., [::1]:8080). Browsers omit the port from the Origin

internal/server/server_test.go

@@ -1577,6 +1577,23 @@ func TestHostHeaderRejectsDNSRebinding(t *testing.T) {
 	assertStatus(t, w, http.StatusForbidden)
 }
 
+func TestHostHeaderRejectionBodyIsDescriptive(t *testing.T) {
+	te := setup(t)
+
+	// A forwarded port produces a Host the server does not trust.
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/stats", nil)
+	req.Host = "127.0.0.1:18080"
+	w := httptest.NewRecorder()
+	te.srv.Handler().ServeHTTP(w, req)
+
+	assertStatus(t, w, http.StatusForbidden)
+	body := w.Body.String()
+	// The body must name the rejected Host and point at the fix so a
+	// user can self-diagnose without devtools.
+	assert.Contains(t, body, "127.0.0.1:18080")
+	assert.Contains(t, body, "--public-url")
+}
+
 func TestHostHeaderAllowsLegitimate(t *testing.T) {
 	te := setup(t)