feat(web): login/logout flow with session-aware UI (ATB-30) (#40)

* feat(web): implement login/logout flow with session-aware UI (ATB-30)

- Add session helper (lib/session.ts): getSession() fetches auth state
from AppView's /api/auth/session by forwarding the browser's Cookie
header server-to-server
- Add auth proxy (routes/auth.ts): proxies all /api/auth/* GET requests
to AppView (forwarding cookies + Set-Cookie headers), plus POST /logout
that revokes tokens and clears the session cookie
- Update BaseLayout to accept optional auth prop: renders "Log in" link
when unauthenticated, or handle + POST logout form when authenticated
- Implement full login page: handle input, AT Proto explanation, error
display from query param, redirects to / when already authenticated
- Convert all routes to factory functions createXRoutes(appviewUrl) so
session can be injected for auth-aware header rendering on every page
- Add auth-gated prompts: board page shows "Log in to start a topic",
topic page shows "Log in to reply" when unauthenticated
- Update fetchApi to accept cookieHeader option for forwarding cookies
in server-to-server API calls
- Add 30 new tests: session helper, auth proxy, login page, auth-aware
BaseLayout nav, updated route stubs with fetch mocking

* fix stuff

* fix(web): address ATB-30 PR review — error handling, logging, factory pattern

Critical fixes:
- auth proxy GET now catches AppView unreachable: login/callback redirect to
/login?error=..., session path returns 503 JSON
- logout bare catch replaced: logs network errors, re-throws programming errors,
checks logoutRes.ok and logs non-ok AppView responses
- decodeURIComponent in login.tsx wrapped in try-catch to avoid URIError crash
on malformed percent-encoding (e.g. %ZZ in query params)

Important fixes:
- getSession logs console.error for network/unexpected errors and for non-ok
non-401 AppView responses (operators can now distinguish AppView downtime from
normal expired sessions)
- createLoginRoutes and createAuthRoutes now accept appviewUrl param — consistent
factory DI pattern used by all other routes; routes/index.ts updated
- fetchApi wraps fetch() in try-catch and throws descriptive network error

Test coverage:
- Authenticated UI branch tests added for boards, topics, new-topic, home header
- auth.test.ts: AppView unreachable redirects/503, logout non-ok logging
- session.test.ts: non-ok non-401 logging, network error logging, 401 no-log
- api.test.ts: cookieHeader forwarding, network error message

* fix(web): address ATB-30 re-review — dead exports, TypeError guard, new tests

- Remove dead `export const` aliases (homeRoutes, boardsRoutes, topicsRoutes,
newTopicRoutes) — index.ts correctly uses factory functions + loadConfig;
the module-level aliases duplicated config logic and could mislead
- Add TypeError to logout re-throw guard per CLAUDE.md: programming TypeErrors
(e.g. fetch(undefined), bad URL) now propagate instead of being silently
logged as "network errors"; existing network failure tests use new Error(),
not TypeError, so graceful logout on ECONNREFUSED is unaffected
- Add test: ReferenceError from fetch() propagates out of logout handler —
Hono returns 500, cookie is not cleared
- Add test: GET /login?error=%ZZ returns 200 with %ZZ in error banner instead
of 500; verifies the decodeURIComponent try-catch fallback works
- Add JSDoc to fetchApi documenting the two error shapes callers must classify
(network error → 503, API error → map HTTP status)

* remove proxied auth routes

* we still need the auth routes, but just the logout

.env.example

···
 FORUM_PASSWORD=your-forum-password
 
 # OAuth Configuration
-OAUTH_PUBLIC_URL=http://localhost:3000
-# The public URL where your AppView is accessible (used for client_id and redirect_uri)
+OAUTH_PUBLIC_URL=http://localhost:8080
+# The public URL where the forum is accessible (used as OAuth client_id and redirect_uri base).
+# AT Protocol fetches {OAUTH_PUBLIC_URL}/.well-known/oauth-client-metadata — nginx routes
+# this to AppView, so OAUTH_PUBLIC_URL must be the nginx address (not AppView directly).
+# For local dev with devenv: http://localhost:8080  (devenv nginx runs on port 8080)
 # For production: https://your-forum-domain.com
-# For local dev with ngrok: https://abc123.ngrok.io
 
 SESSION_SECRET=CHANGE_ME_SEE_COMMENT_BELOW
 # Used for signing session tokens (prevent tampering)

apps/web/src/layouts/__tests__/base.test.tsx

···
 import { describe, it, expect } from "vitest";
 import { Hono } from "hono";
 import { BaseLayout } from "../base.js";
+import type { WebSession } from "../../lib/session.js";
 
 const app = new Hono().get("/", (c) =>
   c.html(<BaseLayout title="Test Page">Page content</BaseLayout>)
···
     const html = await res.text();
     expect(html).toContain('href="/"');
     expect(html).toContain('class="site-header__title"');
+  });
+
+  describe("auth-aware navigation", () => {
+    it("shows Log in link when auth is not provided (default unauthenticated)", async () => {
+      const unauthApp = new Hono().get("/", (c) =>
+        c.html(<BaseLayout>content</BaseLayout>)
+      );
+      const res = await unauthApp.request("/");
+      const html = await res.text();
+      expect(html).toContain('href="/login"');
+      expect(html).toContain("Log in");
+    });
+
+    it("shows Log in link when auth is explicitly unauthenticated", async () => {
+      const auth: WebSession = { authenticated: false };
+      const unauthApp = new Hono().get("/", (c) =>
+        c.html(<BaseLayout auth={auth}>content</BaseLayout>)
+      );
+      const res = await unauthApp.request("/");
+      const html = await res.text();
+      expect(html).toContain('href="/login"');
+      expect(html).toContain("Log in");
+      expect(html).not.toContain("Log out");
+    });
+
+    it("shows handle and Log out button when authenticated", async () => {
+      const auth: WebSession = {
+        authenticated: true,
+        did: "did:plc:abc123",
+        handle: "alice.bsky.social",
+      };
+      const authApp = new Hono().get("/", (c) =>
+        c.html(<BaseLayout auth={auth}>content</BaseLayout>)
+      );
+      const res = await authApp.request("/");
+      const html = await res.text();
+      expect(html).toContain("alice.bsky.social");
+      expect(html).toContain("Log out");
+      expect(html).not.toContain('href="/login"');
+    });
+
+    it("renders logout as a form POST (not a link)", async () => {
+      const auth: WebSession = {
+        authenticated: true,
+        did: "did:plc:abc123",
+        handle: "alice.bsky.social",
+      };
+      const authApp = new Hono().get("/", (c) =>
+        c.html(<BaseLayout auth={auth}>content</BaseLayout>)
+      );
+      const res = await authApp.request("/");
+      const html = await res.text();
+      // Logout must be a form POST for CSRF protection, not a plain link
+      expect(html).toContain('action="/logout"');
+      expect(html).toContain('method="post"');
+      expect(html).toContain("Log out");
+    });
   });
 });

apps/web/src/layouts/base.tsx

···
 import type { FC, PropsWithChildren } from "hono/jsx";
 import { tokensToCss } from "../lib/theme.js";
 import { neobrutalLight } from "../styles/presets/neobrutal-light.js";
+import type { WebSession } from "../lib/session.js";
 
 const ROOT_CSS = `:root { ${tokensToCss(neobrutalLight)} }`;
 
-export const BaseLayout: FC<PropsWithChildren<{ title?: string }>> = (props) => {
+export const BaseLayout: FC<
+  PropsWithChildren<{ title?: string; auth?: WebSession }>
+> = (props) => {
+  const { auth } = props;
   return (
     <html lang="en">
       <head>
···
               atBB Forum
             </a>
             <nav class="site-header__nav">
-              {/* login/logout — auth ticket */}
+              {auth?.authenticated ? (
+                <>
+                  <span class="site-header__handle">{auth.handle}</span>
+                  <form
+                    action="/logout"
+                    method="post"
+                    class="site-header__logout-form"
+                  >
+                    <button type="submit" class="site-header__logout-btn">
+                      Log out
+                    </button>
+                  </form>
+                </>
+              ) : (
+                <a href="/login" class="site-header__login-link">
+                  Log in
+                </a>
+              )}
             </nav>
           </div>
         </header>

apps/web/src/lib/__tests__/api.test.ts

···
       "AppView API error: 404 Not Found"
     );
   });
+
+  it("forwards cookieHeader as Cookie header when provided", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({}),
+    });
+
+    const fetchApi = await loadFetchApi();
+    await fetchApi("/boards", { cookieHeader: "atbb_session=mytoken" });
+
+    const [, init] = mockFetch.mock.calls[0] as [string, RequestInit];
+    expect((init.headers as Record<string, string>)["Cookie"]).toBe(
+      "atbb_session=mytoken"
+    );
+  });
+
+  it("does not set Cookie header when cookieHeader is not provided", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({}),
+    });
+
+    const fetchApi = await loadFetchApi();
+    await fetchApi("/boards");
+
+    const [, init] = mockFetch.mock.calls[0] as [string, RequestInit];
+    expect((init.headers as Record<string, string>)["Cookie"]).toBeUndefined();
+  });
+
+  it("throws a network error with descriptive message when AppView is unreachable", async () => {
+    mockFetch.mockRejectedValueOnce(new Error("fetch failed: ECONNREFUSED"));
+
+    const fetchApi = await loadFetchApi();
+    await expect(fetchApi("/boards")).rejects.toThrow(
+      "AppView network error: fetch failed: ECONNREFUSED"
+    );
+  });
 });

apps/web/src/lib/__tests__/session.test.ts

···
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { getSession } from "../session.js";
+
+const mockFetch = vi.fn();
+
+describe("getSession", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    mockFetch.mockReset();
+  });
+
+  it("returns unauthenticated when no cookie header provided", async () => {
+    const result = await getSession("http://localhost:3000");
+    expect(result).toEqual({ authenticated: false });
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("returns unauthenticated when cookie header has no atbb_session", async () => {
+    const result = await getSession(
+      "http://localhost:3000",
+      "other_cookie=value"
+    );
+    expect(result).toEqual({ authenticated: false });
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("calls AppView /api/auth/session with forwarded cookie header", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          authenticated: true,
+          did: "did:plc:abc123",
+          handle: "alice.bsky.social",
+        }),
+    });
+
+    await getSession(
+      "http://localhost:3000",
+      "atbb_session=some-token; other=value"
+    );
+
+    expect(mockFetch).toHaveBeenCalledOnce();
+    const [url, init] = mockFetch.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("http://localhost:3000/api/auth/session");
+    expect((init.headers as Record<string, string>)["Cookie"]).toBe(
+      "atbb_session=some-token; other=value"
+    );
+  });
+
+  it("returns authenticated session with did and handle on success", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          authenticated: true,
+          did: "did:plc:abc123",
+          handle: "alice.bsky.social",
+        }),
+    });
+
+    const result = await getSession(
+      "http://localhost:3000",
+      "atbb_session=token"
+    );
+
+    expect(result).toEqual({
+      authenticated: true,
+      did: "did:plc:abc123",
+      handle: "alice.bsky.social",
+    });
+  });
+
+  it("returns unauthenticated when AppView returns 401 (expired session)", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 401,
+    });
+
+    const result = await getSession(
+      "http://localhost:3000",
+      "atbb_session=expired"
+    );
+
+    expect(result).toEqual({ authenticated: false });
+  });
+
+  it("logs console.error when AppView returns unexpected non-ok status (not 401)", async () => {
+    const consoleSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+    });
+
+    const result = await getSession(
+      "http://localhost:3000",
+      "atbb_session=token"
+    );
+
+    expect(result).toEqual({ authenticated: false });
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("unexpected non-ok status"),
+      expect.objectContaining({ status: 500 })
+    );
+
+    consoleSpy.mockRestore();
+  });
+
+  it("does not log console.error for 401 (normal expired session)", async () => {
+    const consoleSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 401,
+    });
+
+    await getSession("http://localhost:3000", "atbb_session=expired");
+
+    expect(consoleSpy).not.toHaveBeenCalled();
+
+    consoleSpy.mockRestore();
+  });
+
+  it("returns unauthenticated when AppView response is malformed", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          authenticated: true,
+          // missing did and handle fields
+        }),
+    });
+
+    const result = await getSession(
+      "http://localhost:3000",
+      "atbb_session=token"
+    );
+
+    expect(result).toEqual({ authenticated: false });
+  });
+
+  it("returns unauthenticated and logs when AppView is unreachable (network error)", async () => {
+    const consoleSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    mockFetch.mockRejectedValueOnce(new Error("fetch failed: ECONNREFUSED"));
+
+    const result = await getSession(
+      "http://localhost:3000",
+      "atbb_session=token"
+    );
+
+    expect(result).toEqual({ authenticated: false });
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("network or unexpected error"),
+      expect.objectContaining({ error: expect.stringContaining("ECONNREFUSED") })
+    );
+
+    consoleSpy.mockRestore();
+  });
+
+  it("returns unauthenticated when AppView returns authenticated:false", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 401,
+      json: () => Promise.resolve({ authenticated: false }),
+    });
+
+    const result = await getSession(
+      "http://localhost:3000",
+      "atbb_session=token"
+    );
+
+    expect(result).toEqual({ authenticated: false });
+  });
+});

apps/web/src/lib/api.ts

···
 
 const config = loadConfig();
 
-export async function fetchApi<T>(path: string): Promise<T> {
+/**
+ * Fetches from the AppView API and returns parsed JSON.
+ *
+ * Throws two distinct error shapes that callers must classify:
+ * - `"AppView network error: ..."` — AppView is unreachable; callers should
+ *   return 503 so the user knows to retry.
+ * - `"AppView API error: N ..."` — AppView returned a non-ok HTTP status;
+ *   callers should map to an appropriate response (404, 400, 500, etc.).
+ */
+export async function fetchApi<T>(
+  path: string,
+  options?: { cookieHeader?: string }
+): Promise<T> {
   const url = `${config.appviewUrl}/api${path}`;
-  const res = await fetch(url);
+  const headers: Record<string, string> = {};
+  if (options?.cookieHeader) {
+    headers["Cookie"] = options.cookieHeader;
+  }
+  let res: Response;
+  try {
+    res = await fetch(url, { headers });
+  } catch (error) {
+    throw new Error(
+      `AppView network error: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
   if (!res.ok) {
     throw new Error(`AppView API error: ${res.status} ${res.statusText}`);
   }

apps/web/src/lib/session.ts

···
+export type WebSession =
+  | { authenticated: false }
+  | { authenticated: true; did: string; handle: string };
+
+/**
+ * Fetches the current session from AppView by forwarding the browser's
+ * atbb_session cookie in a server-to-server call.
+ *
+ * Returns unauthenticated if no cookie is present, AppView is unreachable,
+ * or the session is invalid.
+ */
+export async function getSession(
+  appviewUrl: string,
+  cookieHeader?: string
+): Promise<WebSession> {
+  if (!cookieHeader || !cookieHeader.includes("atbb_session=")) {
+    return { authenticated: false };
+  }
+
+  try {
+    const res = await fetch(`${appviewUrl}/api/auth/session`, {
+      headers: { Cookie: cookieHeader },
+    });
+
+    if (!res.ok) {
+      if (res.status !== 401) {
+        console.error("getSession: unexpected non-ok status from AppView", {
+          operation: "GET /api/auth/session",
+          status: res.status,
+        });
+      }
+      return { authenticated: false };
+    }
+
+    const data = (await res.json()) as Record<string, unknown>;
+
+    if (
+      data.authenticated === true &&
+      typeof data.did === "string" &&
+      typeof data.handle === "string"
+    ) {
+      return { authenticated: true, did: data.did, handle: data.handle };
+    }
+
+    return { authenticated: false };
+  } catch (error) {
+    console.error(
+      "getSession: network or unexpected error — treating as unauthenticated",
+      {
+        operation: "GET /api/auth/session",
+        error: error instanceof Error ? error.message : String(error),
+      }
+    );
+    // AppView unavailable or network error — treat as unauthenticated
+    return { authenticated: false };
+  }
+}

apps/web/src/routes/__tests__/auth.test.ts

···
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+const mockFetch = vi.fn();
+
+describe("createAuthRoutes", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    vi.stubEnv("APPVIEW_URL", "http://localhost:3000");
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+    mockFetch.mockReset();
+  });
+
+  async function loadAuthRoutes() {
+    const mod = await import("../auth.js");
+    return mod.createAuthRoutes("http://localhost:3000");
+  }
+
+  describe("POST /logout", () => {
+    it("calls AppView logout, clears cookie, and redirects to /", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+      });
+
+      const authRoutes = await loadAuthRoutes();
+      const res = await authRoutes.request("/logout", {
+        method: "POST",
+        headers: { cookie: "atbb_session=user-token" },
+      });
+
+      expect(res.status).toBe(303);
+      expect(res.headers.get("location")).toBe("/");
+
+      // Verify AppView logout was called with the forwarded cookie
+      expect(mockFetch).toHaveBeenCalledOnce();
+      const [url, init] = mockFetch.mock.calls[0] as [string, RequestInit];
+      expect(url).toBe("http://localhost:3000/api/auth/logout");
+      // Full Cookie header forwarded verbatim
+      expect((init.headers as Record<string, string>)["Cookie"]).toBe(
+        "atbb_session=user-token"
+      );
+    });
+
+    it("clears atbb_session cookie via Set-Cookie header", async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true, status: 200 });
+
+      const authRoutes = await loadAuthRoutes();
+      const res = await authRoutes.request("/logout", { method: "POST" });
+
+      const setCookie = res.headers.get("set-cookie");
+      expect(setCookie).toContain("atbb_session=");
+      expect(setCookie).toContain("Max-Age=0");
+    });
+
+    it("still clears cookie and redirects even if AppView logout fails", async () => {
+      mockFetch.mockRejectedValueOnce(new Error("fetch failed: ECONNREFUSED"));
+
+      const authRoutes = await loadAuthRoutes();
+      const res = await authRoutes.request("/logout", { method: "POST" });
+
+      // Should still redirect home (graceful degradation)
+      expect(res.status).toBe(303);
+      expect(res.headers.get("location")).toBe("/");
+      const setCookie = res.headers.get("set-cookie");
+      expect(setCookie).toContain("Max-Age=0");
+    });
+
+    it("logs console.error when AppView logout returns non-ok status", async () => {
+      mockFetch.mockResolvedValueOnce({ ok: false, status: 500 });
+      const consoleSpy = vi
+        .spyOn(console, "error")
+        .mockImplementation(() => {});
+
+      const authRoutes = await loadAuthRoutes();
+      const res = await authRoutes.request("/logout", { method: "POST" });
+
+      // Still redirects home despite non-ok response
+      expect(res.status).toBe(303);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("non-ok status"),
+        expect.objectContaining({ status: 500 })
+      );
+
+      consoleSpy.mockRestore();
+    });
+
+    it("re-throws programming errors (ReferenceError) without clearing the cookie", async () => {
+      mockFetch.mockRejectedValueOnce(new ReferenceError("fetch is not defined"));
+
+      const authRoutes = await loadAuthRoutes();
+      const res = await authRoutes.request("/logout", { method: "POST" });
+
+      // Programming error escapes the catch block — Hono's default handler returns 500
+      // rather than the expected 303 redirect, and the cookie is never cleared
+      expect(res.status).toBe(500);
+      expect(res.headers.get("set-cookie")).toBeNull();
+    });
+
+    it("logs console.error when AppView logout throws a network error", async () => {
+      mockFetch.mockRejectedValueOnce(new Error("fetch failed: ECONNREFUSED"));
+      const consoleSpy = vi
+        .spyOn(console, "error")
+        .mockImplementation(() => {});
+
+      const authRoutes = await loadAuthRoutes();
+      const res = await authRoutes.request("/logout", { method: "POST" });
+
+      expect(res.status).toBe(303);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to call AppView logout"),
+        expect.objectContaining({ error: expect.stringContaining("ECONNREFUSED") })
+      );
+
+      consoleSpy.mockRestore();
+    });
+  });
+});

apps/web/src/routes/__tests__/login.test.tsx

···
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+const mockFetch = vi.fn();
+
+describe("loginRoutes", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    vi.stubEnv("APPVIEW_URL", "http://localhost:3000");
+    vi.resetModules();
+
+    // Default: user is not authenticated
+    mockFetch.mockResolvedValue({ ok: false, status: 401 });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+    mockFetch.mockReset();
+  });
+
+  async function loadLoginRoutes() {
+    const mod = await import("../login.js");
+    return mod.createLoginRoutes("http://localhost:3000");
+  }
+
+  it("renders handle input form for unauthenticated users", async () => {
+    const routes = await loadLoginRoutes();
+    const res = await routes.request("/login");
+
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain('name="handle"');
+    expect(html).toContain('type="text"');
+    expect(html).toContain('placeholder="alice.bsky.social"');
+  });
+
+  it("renders login submit button", async () => {
+    const routes = await loadLoginRoutes();
+    const res = await routes.request("/login");
+
+    const html = await res.text();
+    expect(html).toContain("Log in with AT Proto");
+    expect(html).toContain('type="submit"');
+  });
+
+  it("form action points to /api/auth/login (the auth proxy)", async () => {
+    const routes = await loadLoginRoutes();
+    const res = await routes.request("/login");
+
+    const html = await res.text();
+    expect(html).toContain('action="/api/auth/login"');
+    expect(html).toContain('method="get"');
+  });
+
+  it("renders AT Proto explanation text", async () => {
+    const routes = await loadLoginRoutes();
+    const res = await routes.request("/login");
+
+    const html = await res.text();
+    // Should explain what AT Proto login means
+    expect(html).toContain("AT Protocol");
+  });
+
+  it("displays decoded error message from query param", async () => {
+    const routes = await loadLoginRoutes();
+    const res = await routes.request(
+      "/login?error=Invalid%20handle%20or%20unable%20to%20find%20your%20PDS."
+    );
+
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain("Invalid handle or unable to find your PDS.");
+  });
+
+  it("shows Log in link in header when unauthenticated", async () => {
+    const routes = await loadLoginRoutes();
+    const res = await routes.request("/login");
+
+    const html = await res.text();
+    expect(html).toContain('href="/login"');
+    expect(html).toContain("Log in");
+    expect(html).not.toContain("Log out");
+  });
+
+  it("redirects to / when already authenticated", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          authenticated: true,
+          did: "did:plc:xyz",
+          handle: "bob.bsky.social",
+        }),
+    });
+
+    const routes = await loadLoginRoutes();
+    const res = await routes.request("/login", {
+      headers: { cookie: "atbb_session=valid-token" },
+    });
+
+    expect(res.status).toBe(302);
+    expect(res.headers.get("location")).toBe("/");
+  });
+
+  it("displays raw error string when error param has malformed percent-encoding", async () => {
+    const routes = await loadLoginRoutes();
+    // %ZZ is invalid percent-encoding — decodeURIComponent would throw URIError
+    const res = await routes.request("/login?error=%ZZ");
+
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    // Falls back to raw string instead of crashing with 500
+    expect(html).toContain("%ZZ");
+    expect(html).toContain("login-form__error");
+  });
+
+  it("renders no error banner when no error query param present", async () => {
+    const routes = await loadLoginRoutes();
+    const res = await routes.request("/login");
+
+    const html = await res.text();
+    expect(html).not.toContain("login-form__error");
+  });
+});

apps/web/src/routes/__tests__/stubs.test.tsx

···
-import { describe, it, expect } from "vitest";
-import { homeRoutes } from "../home.js";
-import { boardsRoutes } from "../boards.js";
-import { topicsRoutes } from "../topics.js";
-import { loginRoutes } from "../login.js";
-import { newTopicRoutes } from "../new-topic.js";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+const mockFetch = vi.fn();
 
+/**
+ * Route stub tests — verify each page route renders without error.
+ *
+ * Since routes now call getSession() (which calls AppView's /api/auth/session),
+ * we mock fetch to return unauthenticated. This keeps tests fast and isolated
+ * from external dependencies.
+ */
 describe("Route stubs", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    vi.stubEnv("APPVIEW_URL", "http://localhost:3000");
+    vi.resetModules();
+
+    // Default: AppView session returns unauthenticated
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 401,
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+    mockFetch.mockReset();
+  });
+
+  const authenticatedSession = {
+    ok: true,
+    json: () =>
+      Promise.resolve({
+        authenticated: true,
+        did: "did:plc:abc",
+        handle: "alice.bsky.social",
+      }),
+  };
+
   it("GET / returns 200 with home title", async () => {
-    const res = await homeRoutes.request("/");
+    const { createHomeRoutes } = await import("../home.js");
+    const routes = createHomeRoutes("http://localhost:3000");
+    const res = await routes.request("/");
     expect(res.status).toBe(200);
     const html = await res.text();
     expect(html).toContain("Home — atBB Forum");
   });
 
+  it("GET / shows handle in header when authenticated", async () => {
+    mockFetch.mockResolvedValueOnce(authenticatedSession);
+    const { createHomeRoutes } = await import("../home.js");
+    const routes = createHomeRoutes("http://localhost:3000");
+    const res = await routes.request("/", {
+      headers: { cookie: "atbb_session=token" },
+    });
+    const html = await res.text();
+    expect(html).toContain("alice.bsky.social");
+    expect(html).toContain("Log out");
+    expect(html).not.toContain('href="/login"');
+  });
+
   it("GET /boards/:id returns 200 with board title", async () => {
-    const res = await boardsRoutes.request("/boards/123");
+    const { createBoardsRoutes } = await import("../boards.js");
+    const routes = createBoardsRoutes("http://localhost:3000");
+    const res = await routes.request("/boards/123");
     expect(res.status).toBe(200);
     const html = await res.text();
     expect(html).toContain("Board — atBB Forum");
   });
 
+  it("GET /boards/:id shows 'Log in to start a topic' when unauthenticated", async () => {
+    const { createBoardsRoutes } = await import("../boards.js");
+    const routes = createBoardsRoutes("http://localhost:3000");
+    const res = await routes.request("/boards/123");
+    const html = await res.text();
+    expect(html).toContain("Log in");
+    expect(html).toContain("to start a topic");
+    expect(html).not.toContain("Start a new topic");
+  });
+
+  it("GET /boards/:id shows 'Start a new topic' link when authenticated", async () => {
+    mockFetch.mockResolvedValueOnce(authenticatedSession);
+    const { createBoardsRoutes } = await import("../boards.js");
+    const routes = createBoardsRoutes("http://localhost:3000");
+    const res = await routes.request("/boards/123", {
+      headers: { cookie: "atbb_session=token" },
+    });
+    const html = await res.text();
+    expect(html).toContain("Start a new topic");
+    expect(html).not.toContain("Log in");
+  });
+
   it("GET /topics/:id returns 200 with topic title", async () => {
-    const res = await topicsRoutes.request("/topics/123");
+    const { createTopicsRoutes } = await import("../topics.js");
+    const routes = createTopicsRoutes("http://localhost:3000");
+    const res = await routes.request("/topics/123");
     expect(res.status).toBe(200);
     const html = await res.text();
     expect(html).toContain("Topic — atBB Forum");
   });
 
-  it("GET /login returns 200 with login title", async () => {
-    const res = await loginRoutes.request("/login");
+  it("GET /topics/:id shows 'Log in to reply' when unauthenticated", async () => {
+    const { createTopicsRoutes } = await import("../topics.js");
+    const routes = createTopicsRoutes("http://localhost:3000");
+    const res = await routes.request("/topics/123");
+    const html = await res.text();
+    expect(html).toContain("Log in");
+    expect(html).toContain("to reply");
+    expect(html).not.toContain("Reply form");
+  });
+
+  it("GET /topics/:id shows reply form placeholder when authenticated", async () => {
+    mockFetch.mockResolvedValueOnce(authenticatedSession);
+    const { createTopicsRoutes } = await import("../topics.js");
+    const routes = createTopicsRoutes("http://localhost:3000");
+    const res = await routes.request("/topics/123", {
+      headers: { cookie: "atbb_session=token" },
+    });
+    const html = await res.text();
+    expect(html).toContain("Reply form will appear here");
+    expect(html).not.toContain("Log in");
+  });
+
+  it("GET /login returns 200 with sign in title", async () => {
+    const { createLoginRoutes } = await import("../login.js");
+    const routes = createLoginRoutes("http://localhost:3000");
+    const res = await routes.request("/login");
     expect(res.status).toBe(200);
     const html = await res.text();
-    expect(html).toContain("Login — atBB Forum");
+    expect(html).toContain("Sign in — atBB Forum");
+  });
+
+  it("GET /login redirects to / when user is already authenticated", async () => {
+    mockFetch.mockResolvedValueOnce(authenticatedSession);
+    const { createLoginRoutes } = await import("../login.js");
+    const routes = createLoginRoutes("http://localhost:3000");
+    const res = await routes.request("/login", {
+      headers: { cookie: "atbb_session=token" },
+    });
+    expect(res.status).toBe(302);
+    expect(res.headers.get("location")).toBe("/");
   });
 
   it("GET /new-topic returns 200 with new topic title", async () => {
-    const res = await newTopicRoutes.request("/new-topic");
+    const { createNewTopicRoutes } = await import("../new-topic.js");
+    const routes = createNewTopicRoutes("http://localhost:3000");
+    const res = await routes.request("/new-topic");
     expect(res.status).toBe(200);
     const html = await res.text();
     expect(html).toContain("New Topic — atBB Forum");
+  });
+
+  it("GET /new-topic shows 'Log in to create a topic' when unauthenticated", async () => {
+    const { createNewTopicRoutes } = await import("../new-topic.js");
+    const routes = createNewTopicRoutes("http://localhost:3000");
+    const res = await routes.request("/new-topic");
+    const html = await res.text();
+    expect(html).toContain("Log in");
+    expect(html).toContain("to create a topic");
+    expect(html).not.toContain("Compose form");
+  });
+
+  it("GET /new-topic shows compose form placeholder when authenticated", async () => {
+    mockFetch.mockResolvedValueOnce(authenticatedSession);
+    const { createNewTopicRoutes } = await import("../new-topic.js");
+    const routes = createNewTopicRoutes("http://localhost:3000");
+    const res = await routes.request("/new-topic", {
+      headers: { cookie: "atbb_session=token" },
+    });
+    const html = await res.text();
+    expect(html).toContain("Compose form will appear here");
+    expect(html).not.toContain("Log in");
   });
 });

apps/web/src/routes/auth.ts

···
+import { Hono } from "hono";
+
+/**
+ * POST /logout → calls AppView logout, clears cookie, redirects to /
+ */
+export function createAuthRoutes(appviewUrl: string) {
+  return new Hono()
+    /**
+     * POST /logout — logout should be a POST (not a link) to prevent CSRF.
+     *
+     * Calls AppView's logout endpoint to revoke tokens and clean up the
+     * server-side session, then clears the cookie on the web UI's domain and
+     * redirects to the homepage.
+     */
+    .post("/logout", async (c) => {
+      const cookieHeader = c.req.header("cookie") ?? "";
+
+      try {
+        const logoutRes = await fetch(`${appviewUrl}/api/auth/logout`, {
+          headers: { Cookie: cookieHeader },
+        });
+
+        if (!logoutRes.ok) {
+          console.error("Auth proxy: AppView logout returned non-ok status", {
+            operation: "POST /logout",
+            status: logoutRes.status,
+          });
+        }
+      } catch (error) {
+        if (
+          error instanceof TypeError ||
+          error instanceof ReferenceError ||
+          error instanceof SyntaxError
+        ) {
+          throw error; // Re-throw programming errors — don't hide code bugs
+        }
+        console.error("Auth proxy: Failed to call AppView logout", {
+          operation: "POST /logout",
+          error: error instanceof Error ? error.message : String(error),
+        });
+        // Continue — still clear local cookie
+      }
+
+      const headers = new Headers();
+      headers.set(
+        "set-cookie",
+        "atbb_session=; Path=/; HttpOnly; Max-Age=0; SameSite=Lax"
+      );
+      headers.set("location", "/");
+
+      return new Response(null, { status: 303, headers });
+    });
+}

apps/web/src/routes/boards.tsx

···
 import { Hono } from "hono";
 import { BaseLayout } from "../layouts/base.js";
 import { PageHeader, EmptyState } from "../components/index.js";
+import { getSession } from "../lib/session.js";
 
-export const boardsRoutes = new Hono().get("/boards/:id", (c) =>
-  c.html(
-    <BaseLayout title="Board — atBB Forum">
-      <PageHeader title="Board" description="Topics will appear here." />
-      <EmptyState message="No topics yet." />
-    </BaseLayout>
-  )
-);
+export function createBoardsRoutes(appviewUrl: string) {
+  return new Hono().get("/boards/:id", async (c) => {
+    const auth = await getSession(appviewUrl, c.req.header("cookie"));
+    return c.html(
+      <BaseLayout title="Board — atBB Forum" auth={auth}>
+        <PageHeader title="Board" description="Topics will appear here." />
+        {auth.authenticated ? (
+          <p>
+            <a href="/new-topic">Start a new topic</a>
+          </p>
+        ) : (
+          <p>
+            <a href="/login">Log in</a> to start a topic.
+          </p>
+        )}
+        <EmptyState message="No topics yet." />
+      </BaseLayout>
+    );
+  });
+}

apps/web/src/routes/home.tsx

···
 import { Hono } from "hono";
 import { BaseLayout } from "../layouts/base.js";
 import { PageHeader, EmptyState } from "../components/index.js";
+import { getSession } from "../lib/session.js";
 
-export const homeRoutes = new Hono().get("/", (c) =>
-  c.html(
-    <BaseLayout title="Home — atBB Forum">
-      <PageHeader
-        title="Welcome to atBB"
-        description="A BB-style forum on the ATmosphere."
-      />
-      <EmptyState message="No boards yet." />
-    </BaseLayout>
-  )
-);
+export function createHomeRoutes(appviewUrl: string) {
+  return new Hono().get("/", async (c) => {
+    const auth = await getSession(appviewUrl, c.req.header("cookie"));
+    return c.html(
+      <BaseLayout title="Home — atBB Forum" auth={auth}>
+        <PageHeader
+          title="Welcome to atBB"
+          description="A BB-style forum on the ATmosphere."
+        />
+        <EmptyState message="No boards yet." />
+      </BaseLayout>
+    );
+  });
+}

apps/web/src/routes/index.ts

···
 import { Hono } from "hono";
-import { homeRoutes } from "./home.js";
-import { boardsRoutes } from "./boards.js";
-import { topicsRoutes } from "./topics.js";
-import { loginRoutes } from "./login.js";
-import { newTopicRoutes } from "./new-topic.js";
+import { loadConfig } from "../lib/config.js";
+import { createHomeRoutes } from "./home.js";
+import { createBoardsRoutes } from "./boards.js";
+import { createTopicsRoutes } from "./topics.js";
+import { createLoginRoutes } from "./login.js";
+import { createNewTopicRoutes } from "./new-topic.js";
+import { createAuthRoutes } from "./auth.js";
+
+const config = loadConfig();
 
 export const webRoutes = new Hono()
-  .route("/", homeRoutes)
-  .route("/", boardsRoutes)
-  .route("/", topicsRoutes)
-  .route("/", loginRoutes)
-  .route("/", newTopicRoutes);
+  .route("/", createHomeRoutes(config.appviewUrl))
+  .route("/", createBoardsRoutes(config.appviewUrl))
+  .route("/", createTopicsRoutes(config.appviewUrl))
+  .route("/", createLoginRoutes(config.appviewUrl))
+  .route("/", createNewTopicRoutes(config.appviewUrl))
+  .route("/", createAuthRoutes(config.appviewUrl));

apps/web/src/routes/login.tsx

···
 import { Hono } from "hono";
 import { BaseLayout } from "../layouts/base.js";
 import { PageHeader } from "../components/index.js";
+import { getSession } from "../lib/session.js";
 
-export const loginRoutes = new Hono().get("/login", (c) =>
-  c.html(
-    <BaseLayout title="Login — atBB Forum">
-      <PageHeader
-        title="Sign in"
-        description="Sign in with your AT Protocol account."
-      />
-    </BaseLayout>
-  )
-);
+export function createLoginRoutes(appviewUrl: string) {
+  return new Hono().get("/login", async (c) => {
+    const auth = await getSession(appviewUrl, c.req.header("cookie"));
+
+    // If already logged in, redirect to homepage
+    if (auth.authenticated) {
+      return c.redirect("/");
+    }
+
+    const rawError = c.req.query("error");
+    // decodeURIComponent throws URIError on malformed percent-encoding (e.g. %ZZ)
+    const error = rawError
+      ? (() => {
+          try {
+            return decodeURIComponent(rawError);
+          } catch {
+            return rawError;
+          }
+        })()
+      : undefined;
+
+    return c.html(
+      <BaseLayout title="Sign in — atBB Forum" auth={auth}>
+        <PageHeader
+          title="Sign in"
+          description="Sign in with your AT Protocol account."
+        />
+        <div class="login-form">
+          {error && (
+            <div class="login-form__error" role="alert">
+              {error}
+            </div>
+          )}
+          <form
+            action="/api/auth/login"
+            method="get"
+            class="login-form__form"
+          >
+            <label for="login-handle" class="login-form__label">
+              AT Protocol handle
+            </label>
+            <input
+              type="text"
+              id="login-handle"
+              name="handle"
+              placeholder="alice.bsky.social"
+              class="login-form__input"
+              required
+              autocomplete="username"
+              autofocus
+            />
+            <p class="login-form__hint">
+              Use any AT Protocol handle (e.g. <code>alice.bsky.social</code>{" "}
+              or a custom domain). You own your posts — they live on your PDS.
+            </p>
+            <button type="submit" class="login-form__submit">
+              Log in with AT Proto
+            </button>
+          </form>
+        </div>
+      </BaseLayout>
+    );
+  });
+}

apps/web/src/routes/new-topic.tsx

···
 import { Hono } from "hono";
 import { BaseLayout } from "../layouts/base.js";
 import { PageHeader } from "../components/index.js";
+import { getSession } from "../lib/session.js";
 
-export const newTopicRoutes = new Hono().get("/new-topic", (c) =>
-  c.html(
-    <BaseLayout title="New Topic — atBB Forum">
-      <PageHeader title="New Topic" description="Compose a new topic." />
-    </BaseLayout>
-  )
-);
+export function createNewTopicRoutes(appviewUrl: string) {
+  return new Hono().get("/new-topic", async (c) => {
+    const auth = await getSession(appviewUrl, c.req.header("cookie"));
+    return c.html(
+      <BaseLayout title="New Topic — atBB Forum" auth={auth}>
+        <PageHeader title="New Topic" description="Compose a new topic." />
+        {auth.authenticated ? (
+          <p>Compose form will appear here.</p>
+        ) : (
+          <p>
+            <a href="/login">Log in</a> to create a topic.
+          </p>
+        )}
+      </BaseLayout>
+    );
+  });
+}

apps/web/src/routes/topics.tsx

···
 import { Hono } from "hono";
 import { BaseLayout } from "../layouts/base.js";
 import { PageHeader, EmptyState } from "../components/index.js";
+import { getSession } from "../lib/session.js";
 
-export const topicsRoutes = new Hono().get("/topics/:id", (c) =>
-  c.html(
-    <BaseLayout title="Topic — atBB Forum">
-      <PageHeader title="Topic" />
-      <EmptyState message="No replies yet." />
-    </BaseLayout>
-  )
-);
+export function createTopicsRoutes(appviewUrl: string) {
+  return new Hono().get("/topics/:id", async (c) => {
+    const auth = await getSession(appviewUrl, c.req.header("cookie"));
+    return c.html(
+      <BaseLayout title="Topic — atBB Forum" auth={auth}>
+        <PageHeader title="Topic" />
+        {auth.authenticated ? (
+          <p>Reply form will appear here.</p>
+        ) : (
+          <p>
+            <a href="/login">Log in</a> to reply.
+          </p>
+        )}
+        <EmptyState message="No replies yet." />
+      </BaseLayout>
+    );
+  });
+}

devenv.nix

···
 
   packages = [
     pkgs.turbo
+    pkgs.nginx
   ];
 
   services.postgres = {
···
     '';
   };
 
-  processes = {
-    appview.exec = "pnpm --filter @atbb/appview dev";
-    web.exec = "pnpm --filter @atbb/web dev";
-  };
+  processes =
+    let
+      # Inline nginx config using Nix store paths so it works in the Nix
+      # environment (no /etc/nginx/mime.types). Mirrors production nginx.conf
+      # but listens on port 8080 (no root required) and uses a tmp working dir.
+      nginxConf = pkgs.writeText "atbb-nginx-dev.conf" ''
+        pid /tmp/atbb-nginx-dev.pid;
+        error_log /dev/stderr;
+
+        events {
+          worker_connections 1024;
+        }
+
+        http {
+          include ${pkgs.nginx}/conf/mime.types;
+          default_type application/octet-stream;
+
+          access_log /dev/stdout;
+
+          client_max_body_size 10M;
+          proxy_connect_timeout 60s;
+          proxy_send_timeout 60s;
+          proxy_read_timeout 60s;
+
+          server {
+            listen 8080;
+
+            # OAuth client metadata → appview
+            # AT Protocol fetches {client_id}/.well-known/oauth-client-metadata
+            # to validate the OAuth client. OAUTH_PUBLIC_URL should be set to
+            # http://localhost:8080 so this route serves the correct document.
+            location /.well-known/ {
+              proxy_pass http://localhost:3000;
+              proxy_set_header Host $host;
+              proxy_set_header X-Real-IP $remote_addr;
+              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+              proxy_set_header X-Forwarded-Proto $scheme;
+            }
+
+            # API routes → appview
+            location /api/ {
+              proxy_pass http://localhost:3000;
+              proxy_set_header Host $host;
+              proxy_set_header X-Real-IP $remote_addr;
+              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+              proxy_set_header X-Forwarded-Proto $scheme;
+            }
+
+            # Web UI → web
+            location / {
+              proxy_pass http://localhost:3001;
+              proxy_set_header Host $host;
+              proxy_set_header X-Real-IP $remote_addr;
+              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+              proxy_set_header X-Forwarded-Proto $scheme;
+            }
+          }
+        }
+      '';
+    in
+    {
+      appview.exec = "pnpm --filter @atbb/appview dev";
+      web.exec = "pnpm --filter @atbb/web dev";
+      nginx.exec = "${pkgs.nginx}/bin/nginx -c ${nginxConf} -p /tmp/atbb-nginx-dev -g 'daemon off;'";
+    };
 }

nginx.conf

···
     server {
         listen 80;
 
+        # OAuth client metadata → appview
+        # AT Protocol fetches {client_id}/.well-known/oauth-client-metadata to
+        # validate the OAuth client. AppView serves this document, so all
+        # /.well-known/* requests must reach AppView, not the web UI.
+        location /.well-known/ {
+            proxy_pass http://localhost:3000;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
         # API routes → appview
         location /api/ {
             proxy_pass http://localhost:3000;