feat: dashboard login gate for public deployments (#148)

* feat: dashboard login gate for public deployments (#141)

Cookie-based session auth when proxy_api_key is set and request is non-localhost.
API routes (/v1/*) unaffected, Electron (localhost) auto-bypassed.

- In-memory session store with TTL from session.ttl_minutes config
- Dashboard auth middleware with path-based allowlist
- Login/logout/status endpoints with per-IP brute-force protection
- HTTPS auto-detection: Secure flag on cookie when X-Forwarded-Proto: https
- Remote session cannot clear proxy_api_key (prevents disabling login gate)
- Frontend LoginGate component with i18n (en/zh), conditional logout button

* fix: dashboard login security hardening

- Timing-safe password comparison (crypto.timingSafeEqual)
- Rate limiter cleanup of expired entries to prevent memory leak
- Extract shared parseSessionCookie to src/utils/parse-cookie.ts
- Remove silent password.trim() that could cause subtle mismatches
- Logout button visible on mobile (icon-only on small screens)
- Fix fragile cleanup timer test (use vi.setSystemTime consistently)

---------

Co-authored-by: icebear0828 <icebear0828@users.noreply.github.com>

CHANGELOG.md

@@ -14,6 +14,14 @@
 
 ### Added
 
+- Dashboard 登录门（#141）：当 `proxy_api_key` 已配置且请求来自非 localhost 时，需输入密码才能访问控制台
+  - Cookie-based session，TTL 由 `session.ttl_minutes` 控制（默认 60 分钟）
+  - `POST /auth/dashboard-login`、`POST /auth/dashboard-logout`、`GET /auth/dashboard-status` 端点
+  - API 路由（`/v1/*`）不受影响，Electron（localhost）自动跳过
+  - 简单防暴力：同 IP 5 次/60s 限制
+  - HTTPS 自动检测：反代 `X-Forwarded-Proto: https` 时 cookie 加 `Secure` flag
+  - 远程 session 禁止清空 `proxy_api_key`（防止误操作导致登录门失效）
+  - Header 显示条件性退出按钮
 - 账号封禁检测：上游返回非 Cloudflare 的 403 时自动标记为 `banned` 状态
   - Dashboard 卡片/表格显示玫红色 `Banned`/`已封禁` 状态徽章
   - 状态筛选下拉新增 `Banned` 选项

shared/hooks/use-dashboard-auth.ts

@@ -0,0 +1,60 @@
+import { useState, useEffect, useCallback } from "preact/hooks";
+
+export type DashboardAuthStatus = "loading" | "login" | "authenticated";
+
+export function useDashboardAuth() {
+  const [status, setStatus] = useState<DashboardAuthStatus>("loading");
+  const [error, setError] = useState<string | null>(null);
+  const [isRemoteSession, setIsRemoteSession] = useState(false);
+
+  const checkStatus = useCallback(async () => {
+    try {
+      const res = await fetch("/auth/dashboard-status");
+      const data: { required: boolean; authenticated: boolean } = await res.json();
+      if (!data.required || data.authenticated) {
+        setStatus("authenticated");
+        setIsRemoteSession(data.required && data.authenticated);
+      } else {
+        setStatus("login");
+      }
+    } catch {
+      // If status endpoint fails, assume no gate (backwards compat)
+      setStatus("authenticated");
+    }
+  }, []);
+
+  useEffect(() => {
+    checkStatus();
+  }, [checkStatus]);
+
+  const login = useCallback(async (password: string) => {
+    setError(null);
+    try {
+      const res = await fetch("/auth/dashboard-login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ password }),
+      });
+      if (res.ok) {
+        setStatus("authenticated");
+        setIsRemoteSession(true);
+      } else {
+        const data = await res.json();
+        setError(data.error || "Login failed");
+      }
+    } catch {
+      setError("Network error");
+    }
+  }, []);
+
+  const logout = useCallback(async () => {
+    try {
+      await fetch("/auth/dashboard-logout", { method: "POST" });
+    } finally {
+      setStatus("login");
+      setIsRemoteSession(false);
+    }
+  }, []);
+
+  return { status, error, login, logout, isRemoteSession };
+}

shared/i18n/translations.ts

@@ -220,6 +220,13 @@ export const translations = {
     last24h: "Last 24h",
     last3d: "Last 3d",
     last7d: "Last 7d",
+    dashboardLogin: "Dashboard Login",
+    dashboardPassword: "Password",
+    dashboardLoginBtn: "Log In",
+    dashboardLoginError: "Invalid password",
+    dashboardLoginRequired: "Enter the proxy API key to access the dashboard.",
+    dashboardLogout: "Logout",
+    dashboardTooManyAttempts: "Too many attempts. Try again later.",
   },
   zh: {
     serverOnline: "\u670d\u52a1\u8fd0\u884c\u4e2d",
@@ -445,6 +452,13 @@ export const translations = {
     last24h: "最近 24h",
     last3d: "最近 3 天",
     last7d: "最近 7 天",
+    dashboardLogin: "控制台登录",
+    dashboardPassword: "密码",
+    dashboardLoginBtn: "登录",
+    dashboardLoginError: "密码错误",
+    dashboardLoginRequired: "请输入代理 API 密钥以访问控制台。",
+    dashboardLogout: "退出登录",
+    dashboardTooManyAttempts: "尝试次数过多，请稍后再试。",
   },
 } as const;
 

src/auth/__tests__/dashboard-session.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+vi.mock("../../config.js", () => ({
+  getConfig: vi.fn(() => ({
+    session: { ttl_minutes: 1, cleanup_interval_minutes: 1 },
+  })),
+}));
+
+import {
+  createSession,
+  validateSession,
+  deleteSession,
+  getSessionCount,
+  startSessionCleanup,
+  stopSessionCleanup,
+  _resetForTest,
+} from "../dashboard-session.js";
+
+beforeEach(() => {
+  _resetForTest();
+});
+
+afterEach(() => {
+  stopSessionCleanup();
+  _resetForTest();
+});
+
+describe("dashboard-session", () => {
+  it("createSession returns a session with id", () => {
+    const session = createSession();
+    expect(session.id).toBeTruthy();
+    expect(typeof session.id).toBe("string");
+    expect(session.expiresAt).toBeGreaterThan(Date.now());
+  });
+
+  it("validateSession returns true for valid session", () => {
+    const session = createSession();
+    expect(validateSession(session.id)).toBe(true);
+  });
+
+  it("validateSession returns false for nonexistent session", () => {
+    expect(validateSession("nonexistent")).toBe(false);
+  });
+
+  it("validateSession returns false for expired session", () => {
+    const session = createSession();
+    // Manually expire it
+    vi.spyOn(Date, "now").mockReturnValue(session.expiresAt + 1);
+    expect(validateSession(session.id)).toBe(false);
+    vi.restoreAllMocks();
+  });
+
+  it("deleteSession invalidates the session", () => {
+    const session = createSession();
+    expect(validateSession(session.id)).toBe(true);
+    deleteSession(session.id);
+    expect(validateSession(session.id)).toBe(false);
+  });
+
+  it("getSessionCount tracks correctly", () => {
+    expect(getSessionCount()).toBe(0);
+    createSession();
+    createSession();
+    expect(getSessionCount()).toBe(2);
+  });
+
+  it("cleanup removes expired sessions", () => {
+    vi.useFakeTimers();
+    const baseTime = Date.now();
+
+    const s1 = createSession();
+    const s2 = createSession();
+    expect(getSessionCount()).toBe(2);
+
+    // Expire both sessions (ttl_minutes=1 → 60_000ms)
+    vi.setSystemTime(baseTime + 60_001);
+
+    // Start cleanup and advance to trigger interval (cleanup_interval_minutes=1 → 60_000ms)
+    startSessionCleanup();
+    vi.advanceTimersByTime(60_001);
+
+    expect(validateSession(s1.id)).toBe(false);
+    expect(validateSession(s2.id)).toBe(false);
+
+    vi.useRealTimers();
+  });
+});

src/auth/dashboard-session.ts

@@ -0,0 +1,81 @@
+/**
+ * Dashboard Session Store — in-memory session management for web dashboard login gate.
+ *
+ * Sessions are cookie-based and protect the dashboard when proxy_api_key is set
+ * and requests come from non-localhost origins. TTL is configured via session.ttl_minutes.
+ *
+ * Sessions are NOT persisted — server restart requires re-login, which is acceptable.
+ */
+
+import { randomUUID } from "crypto";
+import { getConfig } from "../config.js";
+
+export interface DashboardSession {
+  id: string;
+  createdAt: number;
+  expiresAt: number;
+}
+
+const sessions = new Map<string, DashboardSession>();
+let cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+export function createSession(): DashboardSession {
+  const config = getConfig();
+  const ttlMs = config.session.ttl_minutes * 60_000;
+  const now = Date.now();
+  const session: DashboardSession = {
+    id: randomUUID(),
+    createdAt: now,
+    expiresAt: now + ttlMs,
+  };
+  sessions.set(session.id, session);
+  return session;
+}
+
+export function validateSession(id: string): boolean {
+  const session = sessions.get(id);
+  if (!session) return false;
+  if (Date.now() > session.expiresAt) {
+    sessions.delete(id);
+    return false;
+  }
+  return true;
+}
+
+export function deleteSession(id: string): void {
+  sessions.delete(id);
+}
+
+export function getSessionCount(): number {
+  return sessions.size;
+}
+
+function cleanupExpired(): void {
+  const now = Date.now();
+  for (const [id, session] of sessions) {
+    if (now > session.expiresAt) {
+      sessions.delete(id);
+    }
+  }
+}
+
+export function startSessionCleanup(): void {
+  if (cleanupTimer) return;
+  const config = getConfig();
+  const intervalMs = config.session.cleanup_interval_minutes * 60_000;
+  cleanupTimer = setInterval(cleanupExpired, intervalMs);
+  if (cleanupTimer.unref) cleanupTimer.unref();
+}
+
+export function stopSessionCleanup(): void {
+  if (cleanupTimer) {
+    clearInterval(cleanupTimer);
+    cleanupTimer = null;
+  }
+}
+
+/** Reset all sessions — for tests only. */
+export function _resetForTest(): void {
+  sessions.clear();
+  stopSessionCleanup();
+}

src/index.ts

@@ -7,6 +7,7 @@ import { RefreshScheduler } from "./auth/refresh-scheduler.js";
 import { requestId } from "./middleware/request-id.js";
 import { logger } from "./middleware/logger.js";
 import { errorHandler } from "./middleware/error-handler.js";
+import { dashboardAuth } from "./middleware/dashboard-auth.js";
 import { createAuthRoutes } from "./routes/auth.js";
 import { createAccountRoutes } from "./routes/accounts.js";
 import { createChatRoutes } from "./routes/chat.js";
@@ -26,6 +27,8 @@ import { loadStaticModels } from "./models/model-store.js";
 import { startModelRefresh, stopModelRefresh } from "./models/model-fetcher.js";
 import { startQuotaRefresh, stopQuotaRefresh } from "./auth/usage-refresher.js";
 import { UsageStatsStore } from "./auth/usage-stats.js";
+import { startSessionCleanup, stopSessionCleanup } from "./auth/dashboard-session.js";
+import { createDashboardAuthRoutes } from "./routes/dashboard-login.js";
 
 export interface ServerHandle {
   close: () => Promise<void>;
@@ -69,6 +72,7 @@ export async function startServer(options?: StartOptions): Promise<ServerHandle>
   app.use("*", requestId);
   app.use("*", logger);
   app.use("*", errorHandler);
+  app.use("*", dashboardAuth);
 
   // Mount routes
   const authRoutes = createAuthRoutes(accountPool, refreshScheduler);
@@ -81,6 +85,7 @@ export async function startServer(options?: StartOptions): Promise<ServerHandle>
   const usageStats = new UsageStatsStore();
   const webRoutes = createWebRoutes(accountPool, usageStats);
 
+  app.route("/", createDashboardAuthRoutes());
   app.route("/", authRoutes);
   app.route("/", accountRoutes);
   app.route("/", chatRoutes);
@@ -119,6 +124,9 @@ export async function startServer(options?: StartOptions): Promise<ServerHandle>
   }
   console.log();
 
+  // Start dashboard session cleanup
+  startSessionCleanup();
+
   // Start background update checkers
   // (Electron has its own native auto-updater — skip proxy update checker)
   startUpdateChecker();
@@ -152,6 +160,7 @@ export async function startServer(options?: StartOptions): Promise<ServerHandle>
         stopProxyUpdateChecker();
         stopModelRefresh();
         stopQuotaRefresh();
+        stopSessionCleanup();
         refreshScheduler.destroy();
         proxyPool.destroy();
         cookieJar.destroy();

src/middleware/__tests__/dashboard-auth.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Hono } from "hono";
+
+const mockConfig = {
+  server: { proxy_api_key: "test-key" as string | null },
+  session: { ttl_minutes: 60, cleanup_interval_minutes: 5 },
+};
+
+vi.mock("../../config.js", () => ({
+  getConfig: vi.fn(() => mockConfig),
+}));
+
+const mockGetConnInfo = vi.fn(() => ({ remote: { address: "192.168.1.100" } }));
+vi.mock("@hono/node-server/conninfo", () => ({
+  getConnInfo: (...args: unknown[]) => mockGetConnInfo(...args),
+}));
+
+vi.mock("../../auth/dashboard-session.js", async () => {
+  const validSessions = new Set<string>();
+  return {
+    validateSession: vi.fn((id: string) => validSessions.has(id)),
+    _addTestSession: (id: string) => validSessions.add(id),
+    _clearTestSessions: () => validSessions.clear(),
+  };
+});
+
+import { dashboardAuth } from "../dashboard-auth.js";
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports
+const sessionMod = await import("../../auth/dashboard-session.js") as {
+  validateSession: ReturnType<typeof vi.fn>;
+  _addTestSession: (id: string) => void;
+  _clearTestSessions: () => void;
+};
+
+function createApp(): Hono {
+  const app = new Hono();
+  app.use("*", dashboardAuth);
+  // Catch-all handler to confirm middleware passed through
+  app.all("*", (c) => c.json({ ok: true }));
+  return app;
+}
+
+describe("dashboard-auth middleware", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockConfig.server.proxy_api_key = "test-key";
+    mockGetConnInfo.mockReturnValue({ remote: { address: "192.168.1.100" } });
+    sessionMod._clearTestSessions();
+  });
+
+  it("passes through when proxy_api_key is not set", async () => {
+    mockConfig.server.proxy_api_key = null;
+    const app = createApp();
+    const res = await app.request("/auth/accounts");
+    expect(res.status).toBe(200);
+  });
+
+  it("passes through for localhost requests", async () => {
+    mockGetConnInfo.mockReturnValue({ remote: { address: "127.0.0.1" } });
+    const app = createApp();
+    const res = await app.request("/auth/accounts");
+    expect(res.status).toBe(200);
+  });
+
+  it("passes through for ::1 localhost", async () => {
+    mockGetConnInfo.mockReturnValue({ remote: { address: "::1" } });
+    const app = createApp();
+    const res = await app.request("/admin/rotation-settings");
+    expect(res.status).toBe(200);
+  });
+
+  it("passes through for GET / (HTML shell)", async () => {
+    const app = createApp();
+    const res = await app.request("/");
+    expect(res.status).toBe(200);
+  });
+
+  it("passes through for GET /desktop", async () => {
+    const app = createApp();
+    const res = await app.request("/desktop");
+    expect(res.status).toBe(200);
+  });
+
+  it("passes through for /assets/* (static files)", async () => {
+    const app = createApp();
+    const res = await app.request("/assets/index-abc123.js");
+    expect(res.status).toBe(200);
+  });
+
+  it("passes through for /health", async () => {
+    const app = createApp();
+    const res = await app.request("/health");
+    expect(res.status).toBe(200);
+  });
+
+  it("passes through for /v1/* API routes", async () => {
+    const app = createApp();
+    const res = await app.request("/v1/chat/completions");
+    expect(res.status).toBe(200);
+  });
+
+  it("passes through for /v1beta/* API routes", async () => {
+    const app = createApp();
+    const res = await app.request("/v1beta/models");
+    expect(res.status).toBe(200);
+  });
+
+  it("passes through for dashboard auth endpoints", async () => {
+    const app = createApp();
+    for (const path of ["/auth/dashboard-login", "/auth/dashboard-logout", "/auth/dashboard-status"]) {
+      const res = await app.request(path);
+      expect(res.status).toBe(200);
+    }
+  });
+
+  it("returns 401 for /auth/accounts without session", async () => {
+    const app = createApp();
+    const res = await app.request("/auth/accounts");
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body.error).toBeTruthy();
+  });
+
+  it("returns 401 for /admin/* without session", async () => {
+    const app = createApp();
+    const res = await app.request("/admin/rotation-settings");
+    expect(res.status).toBe(401);
+  });
+
+  it("returns 401 for /auth/status without session", async () => {
+    const app = createApp();
+    const res = await app.request("/auth/status");
+    expect(res.status).toBe(401);
+  });
+
+  it("passes through with valid session cookie", async () => {
+    sessionMod._addTestSession("valid-session-id");
+    const app = createApp();
+    const res = await app.request("/auth/accounts", {
+      headers: { Cookie: "_codex_session=valid-session-id" },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  it("returns 401 with invalid session cookie", async () => {
+    const app = createApp();
+    const res = await app.request("/auth/accounts", {
+      headers: { Cookie: "_codex_session=invalid-id" },
+    });
+    expect(res.status).toBe(401);
+  });
+});

src/middleware/dashboard-auth.ts

@@ -0,0 +1,50 @@
+/**
+ * Dashboard Auth Middleware — cookie-based login gate for the web dashboard.
+ *
+ * When proxy_api_key is configured and the request originates from a non-localhost
+ * address, require a valid _codex_session cookie. Protects dashboard data endpoints
+ * while allowing: static assets, health, API routes, login endpoints, and HTML shell.
+ */
+
+import type { Context, Next } from "hono";
+import { getConnInfo } from "@hono/node-server/conninfo";
+import { getConfig } from "../config.js";
+import { isLocalhostRequest } from "../utils/is-localhost.js";
+import { validateSession } from "../auth/dashboard-session.js";
+import { parseSessionCookie } from "../utils/parse-cookie.js";
+
+/** Paths that are always allowed through without dashboard session. */
+const ALLOWED_PREFIXES = ["/assets/", "/v1/", "/v1beta/"];
+const ALLOWED_EXACT = new Set([
+  "/health",
+  "/auth/dashboard-login",
+  "/auth/dashboard-logout",
+  "/auth/dashboard-status",
+]);
+/** GET-only paths allowed (HTML shell must load to render login form). */
+const ALLOWED_GET_EXACT = new Set(["/", "/desktop"]);
+
+export async function dashboardAuth(c: Context, next: Next): Promise<Response | void> {
+  const config = getConfig();
+
+  // No key configured → no gate
+  if (!config.server.proxy_api_key) return next();
+
+  // Localhost → bypass (Electron + local dev)
+  const remoteAddr = getConnInfo(c).remote.address ?? "";
+  if (isLocalhostRequest(remoteAddr)) return next();
+
+  // Always-allowed paths
+  const path = c.req.path;
+  if (ALLOWED_EXACT.has(path)) return next();
+  if (ALLOWED_PREFIXES.some((p) => path.startsWith(p))) return next();
+  if (c.req.method === "GET" && ALLOWED_GET_EXACT.has(path)) return next();
+
+  // Check session cookie
+  const sessionId = parseSessionCookie(c.req.header("cookie"));
+  if (sessionId && validateSession(sessionId)) return next();
+
+  // Not authenticated — reject
+  c.status(401);
+  return c.json({ error: "Dashboard login required" });
+}

src/routes/__tests__/dashboard-login.test.ts

@@ -0,0 +1,303 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Hono } from "hono";
+
+const mockConfig = {
+  server: { proxy_api_key: "secret-key" as string | null },
+  session: { ttl_minutes: 60, cleanup_interval_minutes: 5 },
+  auth: { rotation_strategy: "least_used" as string },
+  quota: {
+    refresh_interval_minutes: 5,
+    warning_thresholds: { primary: [80, 90], secondary: [80, 90] },
+    skip_exhausted: true,
+  },
+};
+
+vi.mock("../../config.js", () => ({
+  getConfig: vi.fn(() => mockConfig),
+  reloadAllConfigs: vi.fn(),
+  ROTATION_STRATEGIES: ["least_used", "round_robin", "sticky"],
+}));
+
+const mockGetConnInfo = vi.fn(() => ({ remote: { address: "192.168.1.100" } }));
+vi.mock("@hono/node-server/conninfo", () => ({
+  getConnInfo: (...args: unknown[]) => mockGetConnInfo(...args),
+}));
+
+vi.mock("../../auth/dashboard-session.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../auth/dashboard-session.js")>();
+  return actual;
+});
+
+vi.mock("../../paths.js", () => ({
+  getConfigDir: vi.fn(() => "/tmp/test-config"),
+  getPublicDir: vi.fn(() => "/tmp/test-public"),
+  getDesktopPublicDir: vi.fn(() => "/tmp/test-desktop"),
+  getDataDir: vi.fn(() => "/tmp/test-data"),
+  getBinDir: vi.fn(() => "/tmp/test-bin"),
+  isEmbedded: vi.fn(() => false),
+}));
+
+vi.mock("../../utils/yaml-mutate.js", () => ({
+  mutateYaml: vi.fn(),
+}));
+
+vi.mock("../../tls/transport.js", () => ({
+  getTransport: vi.fn(),
+  getTransportInfo: vi.fn(() => ({})),
+}));
+
+vi.mock("../../tls/curl-binary.js", () => ({
+  getCurlDiagnostics: vi.fn(() => ({})),
+}));
+
+vi.mock("../../fingerprint/manager.js", () => ({
+  buildHeaders: vi.fn(() => ({})),
+}));
+
+vi.mock("../../update-checker.js", () => ({
+  getUpdateState: vi.fn(() => ({})),
+  checkForUpdate: vi.fn(),
+  isUpdateInProgress: vi.fn(() => false),
+}));
+
+vi.mock("../../self-update.js", () => ({
+  getProxyInfo: vi.fn(() => ({})),
+  canSelfUpdate: vi.fn(() => false),
+  checkProxySelfUpdate: vi.fn(),
+  applyProxySelfUpdate: vi.fn(),
+  isProxyUpdateInProgress: vi.fn(() => false),
+  getCachedProxyUpdateResult: vi.fn(() => null),
+  getDeployMode: vi.fn(() => "git"),
+}));
+
+vi.mock("@hono/node-server/serve-static", () => ({
+  serveStatic: vi.fn(() => vi.fn()),
+}));
+
+import {
+  createDashboardAuthRoutes,
+  _resetRateLimitForTest,
+} from "../dashboard-login.js";
+import { createSettingsRoutes } from "../admin/settings.js";
+import { _resetForTest } from "../../auth/dashboard-session.js";
+
+function createApp(): Hono {
+  const app = new Hono();
+  app.route("/", createDashboardAuthRoutes());
+  app.route("/", createSettingsRoutes());
+  return app;
+}
+
+describe("dashboard auth endpoints", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockConfig.server.proxy_api_key = "secret-key";
+    mockGetConnInfo.mockReturnValue({ remote: { address: "192.168.1.100" } });
+    _resetForTest();
+    _resetRateLimitForTest();
+  });
+
+  describe("POST /auth/dashboard-login", () => {
+    it("returns 200 and sets cookie with correct password", async () => {
+      const app = createApp();
+      const res = await app.request("/auth/dashboard-login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ password: "secret-key" }),
+      });
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      expect(body.success).toBe(true);
+
+      const cookie = res.headers.get("set-cookie");
+      expect(cookie).toContain("_codex_session=");
+      expect(cookie).toContain("HttpOnly");
+      expect(cookie).toContain("SameSite=Strict");
+      expect(cookie).toContain("Path=/");
+      expect(cookie).toContain("Max-Age=");
+    });
+
+    it("returns 401 with wrong password", async () => {
+      const app = createApp();
+      const res = await app.request("/auth/dashboard-login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ password: "wrong" }),
+      });
+      expect(res.status).toBe(401);
+      const body = await res.json();
+      expect(body.error).toBeTruthy();
+    });
+
+    it("returns 400 with missing body", async () => {
+      const app = createApp();
+      const res = await app.request("/auth/dashboard-login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({}),
+      });
+      expect(res.status).toBe(400);
+    });
+
+    it("sets Secure flag when behind HTTPS reverse proxy", async () => {
+      const app = createApp();
+      const res = await app.request("/auth/dashboard-login", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Forwarded-Proto": "https",
+        },
+        body: JSON.stringify({ password: "secret-key" }),
+      });
+      expect(res.status).toBe(200);
+      const cookie = res.headers.get("set-cookie");
+      expect(cookie).toContain("Secure");
+    });
+
+    it("omits Secure flag for HTTP", async () => {
+      const app = createApp();
+      const res = await app.request("/auth/dashboard-login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ password: "secret-key" }),
+      });
+      expect(res.status).toBe(200);
+      const cookie = res.headers.get("set-cookie");
+      expect(cookie).not.toContain("Secure");
+    });
+
+    it("returns 429 after 5 failed attempts", async () => {
+      const app = createApp();
+      for (let i = 0; i < 5; i++) {
+        await app.request("/auth/dashboard-login", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ password: "wrong" }),
+        });
+      }
+      const res = await app.request("/auth/dashboard-login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ password: "wrong" }),
+      });
+      expect(res.status).toBe(429);
+    });
+  });
+
+  describe("POST /auth/dashboard-logout", () => {
+    it("clears session and cookie", async () => {
+      const app = createApp();
+      // Login first
+      const loginRes = await app.request("/auth/dashboard-login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ password: "secret-key" }),
+      });
+      const cookie = loginRes.headers.get("set-cookie")!;
+      const sessionId = cookie.match(/_codex_session=([^;]+)/)![1];
+
+      // Logout
+      const logoutRes = await app.request("/auth/dashboard-logout", {
+        method: "POST",
+        headers: { Cookie: `_codex_session=${sessionId}` },
+      });
+      expect(logoutRes.status).toBe(200);
+      const body = await logoutRes.json();
+      expect(body.success).toBe(true);
+
+      const clearCookie = logoutRes.headers.get("set-cookie");
+      expect(clearCookie).toContain("Max-Age=0");
+    });
+  });
+
+  describe("GET /auth/dashboard-status", () => {
+    it("returns required=false when no key configured", async () => {
+      mockConfig.server.proxy_api_key = null;
+      const app = createApp();
+      const res = await app.request("/auth/dashboard-status");
+      const body = await res.json();
+      expect(body.required).toBe(false);
+      expect(body.authenticated).toBe(true);
+    });
+
+    it("returns required=false for localhost", async () => {
+      mockGetConnInfo.mockReturnValue({ remote: { address: "127.0.0.1" } });
+      const app = createApp();
+      const res = await app.request("/auth/dashboard-status");
+      const body = await res.json();
+      expect(body.required).toBe(false);
+      expect(body.authenticated).toBe(true);
+    });
+
+    it("returns required=true, authenticated=false for remote without session", async () => {
+      const app = createApp();
+      const res = await app.request("/auth/dashboard-status");
+      const body = await res.json();
+      expect(body.required).toBe(true);
+      expect(body.authenticated).toBe(false);
+    });
+
+    it("returns required=true, authenticated=true for remote with valid session", async () => {
+      const app = createApp();
+      // Login first
+      const loginRes = await app.request("/auth/dashboard-login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ password: "secret-key" }),
+      });
+      const cookie = loginRes.headers.get("set-cookie")!;
+      const sessionId = cookie.match(/_codex_session=([^;]+)/)![1];
+
+      const statusRes = await app.request("/auth/dashboard-status", {
+        headers: { Cookie: `_codex_session=${sessionId}` },
+      });
+      const body = await statusRes.json();
+      expect(body.required).toBe(true);
+      expect(body.authenticated).toBe(true);
+    });
+  });
+
+  describe("POST /admin/settings — remote clear protection", () => {
+    it("blocks remote session from clearing proxy_api_key", async () => {
+      const app = createApp();
+      const res = await app.request("/admin/settings", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: "Bearer secret-key",
+        },
+        body: JSON.stringify({ proxy_api_key: null }),
+      });
+      expect(res.status).toBe(403);
+      const body = await res.json();
+      expect(body.error).toContain("Cannot clear");
+    });
+
+    it("allows localhost to clear proxy_api_key", async () => {
+      mockGetConnInfo.mockReturnValue({ remote: { address: "127.0.0.1" } });
+      const app = createApp();
+      const res = await app.request("/admin/settings", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: "Bearer secret-key",
+        },
+        body: JSON.stringify({ proxy_api_key: null }),
+      });
+      expect(res.status).toBe(200);
+    });
+
+    it("allows remote session to change (not clear) proxy_api_key", async () => {
+      const app = createApp();
+      const res = await app.request("/admin/settings", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: "Bearer secret-key",
+        },
+        body: JSON.stringify({ proxy_api_key: "new-key" }),
+      });
+      expect(res.status).toBe(200);
+    });
+  });
+});

src/routes/admin/health.ts

@@ -7,6 +7,7 @@ import { getConfig, getFingerprint } from "../../config.js";
 import { getConfigDir, getDataDir, getBinDir, isEmbedded } from "../../paths.js";
 import { getTransportInfo } from "../../tls/transport.js";
 import { getCurlDiagnostics } from "../../tls/curl-binary.js";
+import { isLocalhostRequest } from "../../utils/is-localhost.js";
 
 export function createHealthRoutes(accountPool: AccountPool): Hono {
   const app = new Hono();
@@ -25,7 +26,7 @@ export function createHealthRoutes(accountPool: AccountPool): Hono {
   app.get("/debug/fingerprint", (c) => {
     const isProduction = process.env.NODE_ENV === "production";
     const remoteAddr = getConnInfo(c).remote.address ?? "";
-    const isLocalhost = remoteAddr === "" || remoteAddr === "127.0.0.1" || remoteAddr === "::1" || remoteAddr === "::ffff:127.0.0.1";
+    const isLocalhost = isLocalhostRequest(remoteAddr);
     if (isProduction && !isLocalhost) {
       c.status(404);
       return c.json({ error: { message: "Not found", type: "invalid_request_error" } });
@@ -86,7 +87,7 @@ export function createHealthRoutes(accountPool: AccountPool): Hono {
 
   app.get("/debug/diagnostics", (c) => {
     const remoteAddr = getConnInfo(c).remote.address ?? "";
-    const isLocalhost = remoteAddr === "" || remoteAddr === "127.0.0.1" || remoteAddr === "::1" || remoteAddr === "::ffff:127.0.0.1";
+    const isLocalhost = isLocalhostRequest(remoteAddr);
     if (process.env.NODE_ENV === "production" && !isLocalhost) {
       c.status(404);
       return c.json({ error: { message: "Not found", type: "invalid_request_error" } });

src/routes/admin/settings.ts

@@ -1,8 +1,10 @@
 import { Hono } from "hono";
 import { resolve } from "path";
+import { getConnInfo } from "@hono/node-server/conninfo";
 import { getConfig, reloadAllConfigs, ROTATION_STRATEGIES } from "../../config.js";
 import { getConfigDir } from "../../paths.js";
 import { mutateYaml } from "../../utils/yaml-mutate.js";
+import { isLocalhostRequest } from "../../utils/is-localhost.js";
 
 export function createSettingsRoutes(): Hono {
   const app = new Hono();
@@ -73,6 +75,15 @@ export function createSettingsRoutes(): Hono {
     const body = await c.req.json() as { proxy_api_key?: string | null };
     const newKey = body.proxy_api_key === undefined ? currentKey : (body.proxy_api_key || null);
 
+    // Prevent remote sessions from clearing the key (would disable login gate)
+    if (currentKey && !newKey) {
+      const remoteAddr = getConnInfo(c).remote.address ?? "";
+      if (!isLocalhostRequest(remoteAddr)) {
+        c.status(403);
+        return c.json({ error: "Cannot clear API key from remote session — this would disable the login gate" });
+      }
+    }
+
     const configPath = resolve(getConfigDir(), "default.yaml");
     mutateYaml(configPath, (data) => {
       const server = data.server as Record<string, unknown>;

src/routes/dashboard-login.ts

@@ -0,0 +1,144 @@
+/**
+ * Dashboard Login Routes — cookie-based authentication for the web dashboard.
+ *
+ * Provides login/logout/status endpoints that work with the dashboard-auth middleware.
+ * Uses the existing proxy_api_key as the dashboard password.
+ */
+
+import { timingSafeEqual } from "crypto";
+import { Hono } from "hono";
+import type { Context } from "hono";
+import { getConnInfo } from "@hono/node-server/conninfo";
+import { getConfig } from "../config.js";
+import { isLocalhostRequest } from "../utils/is-localhost.js";
+import { parseSessionCookie } from "../utils/parse-cookie.js";
+import {
+  createSession,
+  validateSession,
+  deleteSession,
+} from "../auth/dashboard-session.js";
+
+/** Per-IP brute-force tracking: IP → { count, resetAt } */
+const failedAttempts = new Map<string, { count: number; resetAt: number }>();
+const MAX_ATTEMPTS = 5;
+const WINDOW_MS = 60_000;
+
+function checkRateLimit(ip: string): boolean {
+  const now = Date.now();
+  const entry = failedAttempts.get(ip);
+  if (!entry || now > entry.resetAt) {
+    if (entry) failedAttempts.delete(ip); // cleanup expired
+    return true;
+  }
+  return entry.count < MAX_ATTEMPTS;
+}
+
+function recordFailure(ip: string): void {
+  const now = Date.now();
+  const entry = failedAttempts.get(ip);
+  if (!entry || now > entry.resetAt) {
+    failedAttempts.set(ip, { count: 1, resetAt: now + WINDOW_MS });
+  } else {
+    entry.count++;
+  }
+}
+
+/** Detect HTTPS from X-Forwarded-Proto (reverse proxy) or protocol. */
+function isHttps(c: Context): boolean {
+  const proto = c.req.header("x-forwarded-proto");
+  if (proto) return proto.toLowerCase() === "https";
+  const url = new URL(c.req.url);
+  return url.protocol === "https:";
+}
+
+function buildCookieString(name: string, value: string, maxAge: number, secure: boolean): string {
+  let cookie = `${name}=${value}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${maxAge}`;
+  if (secure) cookie += "; Secure";
+  return cookie;
+}
+
+/** Reset rate-limit state — for tests only. */
+export function _resetRateLimitForTest(): void {
+  failedAttempts.clear();
+}
+
+export function createDashboardAuthRoutes(): Hono {
+  const app = new Hono();
+
+  // POST /auth/dashboard-login — validate proxy_api_key and set session cookie
+  app.post("/auth/dashboard-login", async (c) => {
+    const config = getConfig();
+    const remoteAddr = getConnInfo(c).remote.address ?? "unknown";
+
+    // Rate limit check
+    if (!checkRateLimit(remoteAddr)) {
+      c.status(429);
+      return c.json({ error: "Too many login attempts. Try again later." });
+    }
+
+    let body: { password?: string };
+    try {
+      body = await c.req.json();
+    } catch {
+      c.status(400);
+      return c.json({ error: "Invalid JSON body" });
+    }
+
+    const password = body.password;
+    if (!password || typeof password !== "string") {
+      c.status(400);
+      return c.json({ error: "Password is required" });
+    }
+
+    const key = config.server.proxy_api_key ?? "";
+    const a = Buffer.from(password);
+    const b = Buffer.from(key);
+    const match = a.length === b.length && timingSafeEqual(a, b);
+    if (!match) {
+      recordFailure(remoteAddr);
+      c.status(401);
+      return c.json({ error: "Invalid password" });
+    }
+
+    const session = createSession();
+    const maxAge = config.session.ttl_minutes * 60;
+    const secure = isHttps(c);
+    c.header("Set-Cookie", buildCookieString("_codex_session", session.id, maxAge, secure));
+    return c.json({ success: true });
+  });
+
+  // POST /auth/dashboard-logout — clear session and cookie
+  app.post("/auth/dashboard-logout", (c) => {
+    const sessionId = parseSessionCookie(c.req.header("cookie"));
+    if (sessionId) {
+      deleteSession(sessionId);
+    }
+    const secure = isHttps(c);
+    c.header("Set-Cookie", buildCookieString("_codex_session", "", 0, secure));
+    return c.json({ success: true });
+  });
+
+  // GET /auth/dashboard-status — check if login is required and current auth state
+  app.get("/auth/dashboard-status", (c) => {
+    const config = getConfig();
+
+    // No key → no gate required
+    if (!config.server.proxy_api_key) {
+      return c.json({ required: false, authenticated: true });
+    }
+
+    // Localhost → no gate required
+    const remoteAddr = getConnInfo(c).remote.address ?? "";
+    if (isLocalhostRequest(remoteAddr)) {
+      return c.json({ required: false, authenticated: true });
+    }
+
+    // Check session
+    const sessionId = parseSessionCookie(c.req.header("cookie"));
+    const authenticated = !!sessionId && validateSession(sessionId);
+
+    return c.json({ required: true, authenticated });
+  });
+
+  return app;
+}

src/utils/__tests__/is-localhost.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest";
+import { isLocalhostRequest } from "../is-localhost.js";
+
+describe("isLocalhostRequest", () => {
+  it.each([
+    ["", true],
+    ["127.0.0.1", true],
+    ["::1", true],
+    ["::ffff:127.0.0.1", true],
+  ])("returns true for %s", (addr, expected) => {
+    expect(isLocalhostRequest(addr)).toBe(expected);
+  });
+
+  it.each([
+    ["192.168.1.1", false],
+    ["10.0.0.5", false],
+    ["172.16.0.1", false],
+    ["8.8.8.8", false],
+    ["::ffff:192.168.1.1", false],
+    ["2001:db8::1", false],
+  ])("returns false for %s", (addr, expected) => {
+    expect(isLocalhostRequest(addr)).toBe(expected);
+  });
+});

src/utils/is-localhost.ts

@@ -0,0 +1,6 @@
+const LOCALHOST_ADDRS = new Set(["", "127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+
+/** Returns true if the remote address represents a localhost connection. */
+export function isLocalhostRequest(remoteAddr: string): boolean {
+  return LOCALHOST_ADDRS.has(remoteAddr);
+}

src/utils/parse-cookie.ts

@@ -0,0 +1,8 @@
+const COOKIE_REGEX = /(?:^|;\s*)_codex_session=([^;]*)/;
+
+/** Extract the _codex_session cookie value from a Cookie header. */
+export function parseSessionCookie(cookieHeader: string | undefined): string | undefined {
+  if (!cookieHeader) return undefined;
+  const match = COOKIE_REGEX.exec(cookieHeader);
+  return match ? match[1] : undefined;
+}

web/src/App.tsx

@@ -1,4 +1,6 @@
-import { useState, useEffect, useRef } from "preact/hooks";
+import { useState, useEffect, useRef, useContext } from "preact/hooks";
+import { createContext } from "preact";
+import type { ComponentChildren } from "preact";
 import { I18nProvider } from "../../shared/i18n/context";
 import { ThemeProvider } from "../../shared/theme/context";
 import { Header } from "./components/Header";
@@ -22,6 +24,11 @@ import { useProxies } from "../../shared/hooks/use-proxies";
 import { useStatus } from "../../shared/hooks/use-status";
 import { useUpdateStatus } from "../../shared/hooks/use-update-status";
 import { useI18n } from "../../shared/i18n/context";
+import { useDashboardAuth } from "../../shared/hooks/use-dashboard-auth";
+
+/** Context for dashboard session state (logout button, remote session indicator). */
+const DashboardAuthCtx = createContext<{ onLogout?: () => void }>({});
+function useDashboardAuthCtx() { return useContext(DashboardAuthCtx); }
 
 function useUpdateMessage() {
   const { t } = useI18n();
@@ -75,6 +82,7 @@ function Dashboard() {
   const proxies = useProxies();
   const status = useStatus(accounts.list.length);
   const update = useUpdateMessage();
+  const { onLogout } = useDashboardAuthCtx();
   const [showModal, setShowModal] = useState(false);
   const prevUpdateAvailable = useRef(false);
 
@@ -104,6 +112,7 @@ function Dashboard() {
         version={update.status?.proxy.version ?? null}
         commit={update.status?.proxy.commit ?? null}
         hasUpdate={update.hasUpdate}
+        onLogout={onLogout}
       />
       <main class="flex-grow px-4 md:px-8 lg:px-40 py-8 flex justify-center">
         <div class="flex flex-col w-full max-w-[960px] gap-6">
@@ -195,13 +204,79 @@ function PageRouter({ hash }: { hash: string }) {
   }
 }
 
+function LoginGate({ children }: { children: ComponentChildren }) {
+  const { t } = useI18n();
+  const auth = useDashboardAuth();
+  const [password, setPassword] = useState("");
+
+  if (auth.status === "loading") {
+    return (
+      <div class="min-h-screen flex items-center justify-center bg-slate-50 dark:bg-bg-dark">
+        <div class="animate-pulse text-slate-400 dark:text-text-dim text-sm">Loading...</div>
+      </div>
+    );
+  }
+
+  if (auth.status === "login") {
+    const handleSubmit = (e: Event) => {
+      e.preventDefault();
+      if (password.trim()) auth.login(password.trim());
+    };
+
+    return (
+      <div class="min-h-screen flex items-center justify-center bg-slate-50 dark:bg-bg-dark px-4">
+        <div class="w-full max-w-sm bg-white dark:bg-card-dark border border-gray-200 dark:border-border-dark rounded-2xl shadow-lg p-8">
+          <div class="flex flex-col items-center gap-2 mb-6">
+            <div class="flex items-center justify-center size-12 rounded-full bg-primary/10 text-primary border border-primary/20">
+              <svg class="size-6" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M16.5 10.5V6.75a4.5 4.5 0 10-9 0v3.75m-.75 11.25h10.5a2.25 2.25 0 002.25-2.25v-6.75a2.25 2.25 0 00-2.25-2.25H6.75a2.25 2.25 0 00-2.25 2.25v6.75a2.25 2.25 0 002.25 2.25z" />
+              </svg>
+            </div>
+            <h1 class="text-lg font-bold text-slate-800 dark:text-text-main">{t("dashboardLogin")}</h1>
+            <p class="text-xs text-slate-500 dark:text-text-dim text-center">{t("dashboardLoginRequired")}</p>
+          </div>
+          <form onSubmit={handleSubmit} class="flex flex-col gap-4">
+            <div>
+              <label class="block text-xs font-medium text-slate-600 dark:text-text-dim mb-1.5">{t("dashboardPassword")}</label>
+              <input
+                type="password"
+                value={password}
+                onInput={(e) => setPassword((e.target as HTMLInputElement).value)}
+                class="w-full px-3 py-2 rounded-lg border border-gray-200 dark:border-border-dark bg-slate-50 dark:bg-bg-dark text-sm text-slate-800 dark:text-text-main focus:outline-none focus:ring-2 focus:ring-primary/40 focus:border-primary transition-colors"
+                placeholder="proxy_api_key"
+                autofocus
+              />
+            </div>
+            {auth.error && (
+              <p class="text-xs text-red-500 font-medium">
+                {auth.error.includes("Too many") ? t("dashboardTooManyAttempts") : t("dashboardLoginError")}
+              </p>
+            )}
+            <button
+              type="submit"
+              class="w-full py-2.5 bg-primary hover:bg-primary-hover text-white text-sm font-semibold rounded-lg transition-colors shadow-sm active:scale-[0.98]"
+            >
+              {t("dashboardLoginBtn")}
+            </button>
+          </form>
+        </div>
+      </div>
+    );
+  }
+
+  const ctxValue = auth.isRemoteSession ? { onLogout: auth.logout } : {};
+  return <DashboardAuthCtx.Provider value={ctxValue}>{children}</DashboardAuthCtx.Provider>;
+}
+
 export function App() {
   const hash = useHash();
 
   return (
     <I18nProvider>
       <ThemeProvider>
-        <PageRouter hash={hash} />
+        <LoginGate>
+          <PageRouter hash={hash} />
+        </LoginGate>
       </ThemeProvider>
     </I18nProvider>
   );

web/src/components/Header.tsx

@@ -39,9 +39,10 @@ interface HeaderProps {
   commit?: string | null;
   isProxySettings?: boolean;
   hasUpdate?: boolean;
+  onLogout?: () => void;
 }
 
-export function Header({ onAddAccount, onCheckUpdate, onOpenUpdateModal, checking, updateStatusMsg, updateStatusColor, version, commit, isProxySettings, hasUpdate }: HeaderProps) {
+export function Header({ onAddAccount, onCheckUpdate, onOpenUpdateModal, checking, updateStatusMsg, updateStatusColor, version, commit, isProxySettings, hasUpdate, onLogout }: HeaderProps) {
   const { lang, toggleLang, t } = useI18n();
   const { isDark, toggle: toggleTheme } = useTheme();
 
@@ -113,6 +114,18 @@ export function Header({ onAddAccount, onCheckUpdate, onOpenUpdateModal, checkin
                 {updateStatusMsg}
               </button>
             )}
+            {/* Logout (remote sessions only) */}
+            {onLogout && (
+              <button
+                onClick={onLogout}
+                class="flex items-center gap-1.5 px-3 py-1.5 rounded-full border border-gray-200 dark:border-border-dark text-slate-600 dark:text-text-dim hover:bg-slate-50 dark:hover:bg-border-dark transition-colors"
+              >
+                <svg class="size-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                  <path stroke-linecap="round" stroke-linejoin="round" d="M15.75 9V5.25A2.25 2.25 0 0013.5 3h-6a2.25 2.25 0 00-2.25 2.25v13.5A2.25 2.25 0 007.5 21h6a2.25 2.25 0 002.25-2.25V15m3 0l3-3m0 0l-3-3m3 3H9" />
+                </svg>
+                <span class="hidden sm:inline"><StableText tKey="dashboardLogout" class="text-xs font-semibold">{t("dashboardLogout")}</StableText></span>
+              </button>
+            )}
             {/* Language Toggle */}
             <button
               onClick={toggleLang}