From f7c16888e75797d6bba67b0acb48263090fc8a83 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:07:51 +0800
Subject: [PATCH 01/35] docs(spec): WebUI authentication design

Spec for adding username+password auth to the WebUI to close the
unauthenticated-API exposure (all /api/* and /ws currently open).

Design: SQLite users + sessions tables, bcryptjs, 7-day rolling
HTTP-only cookie sessions, first-run setup wizard, Origin/Referer
CSRF check, WebSocket upgrade gated on the same session cookie.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../2026-05-27-webui-authentication-design.md | 360 ++++++++++++++++++
 1 file changed, 360 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-27-webui-authentication-design.md

diff --git a/docs/superpowers/specs/2026-05-27-webui-authentication-design.md b/docs/superpowers/specs/2026-05-27-webui-authentication-design.md
new file mode 100644
index 0000000..5ae331b
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-27-webui-authentication-design.md
@@ -0,0 +1,360 @@
+# WebUI Authentication
+
+**Date:** 2026-05-27
+**Status:** Spec — pending implementation
+**Branch:** `feat/webui-auth`
+
+## Problem
+
+WebUI 的所有后端端点和 WebSocket 当前没有任何鉴权：
+
+- `src/web/server.ts` 注册的 `/api/bot`、`/api/player`、`/api/music`、`/api/auth`、`/api/config/public-url`、`/api/health`、`/ws` 均无中间件拦截。
+- 静态前端通过 `express.static()` 直接对外提供。
+
+后果：任何能访问 WebUI 端口（默认 `3000`）的人都能控制 bot、修改配置、操控播放，并触发对网易云 / QQ / Bilibili 的登录二维码流程。一旦 WebUI 端口暴露公网（无论是直接绑定 `0.0.0.0`、还是经 nginx 反代），即被任意访客接管。
+
+## Goal
+
+为 WebUI 增加用户名 + 密码登录，覆盖所有 HTTP `/api/*` 端点（除显式公共白名单）以及 `/ws` WebSocket，使未登录访客无法调用任何敏感接口或观察 bot 状态。
+
+## Out of Scope（明确不做）
+
+- 登录失败的限流 / 锁定（无 brute-force 防御；可放在反代层；后续 PR 单独做）
+- 角色与权限（admin / viewer）—— 全员同权
+- 密码重置流程（不挂邮件；仅提供登录后 `change-password`）
+- 双因素认证（2FA）
+- "记住我" / 绝对过期 vs 滑动过期的可配置
+- 旧版"无鉴权"兼容开关（`requireAuth=false`）—— 合入后所有部署强制启用鉴权
+- 现有 `config.adminPassword` 字段的迁移 —— 保留为未使用字段，避免破坏旧 `config.json`
+
+## Non-functional Constraints
+
+- 不引入需要原生编译的依赖（Windows 用户多，build tools 不稳定）。密码哈希用纯 JS 的 `bcryptjs`。
+- Cookie 行为必须兼容现有 `trustProxy` 反代部署。
+- 升级路径：旧用户首次启动新版本 → 自动进入 `/setup` 创建首位 admin；期间所有 `/api/*` 仍拒绝访问。期间不存在"裸奔窗口"。
+- 后续维护者要能在不阅读 `requireAuth` 内部细节的情况下，把新路由挂到 `/api/*` 下并自动获得鉴权。
+
+## Architecture
+
+### 数据层（`src/data/`）
+
+扩展 `src/data/database.ts` 的 schema-migration 块，新增两张表：
+
+```sql
+CREATE TABLE IF NOT EXISTS users (
+  id           TEXT PRIMARY KEY,                 -- uuid v4
+  username     TEXT NOT NULL UNIQUE COLLATE NOCASE,
+  passwordHash TEXT NOT NULL,                    -- bcryptjs, 12 rounds
+  createdAt    INTEGER NOT NULL,
+  updatedAt    INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id          TEXT PRIMARY KEY,                  -- sha256(rawToken) hex
+  userId      TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  createdAt   INTEGER NOT NULL,
+  expiresAt   INTEGER NOT NULL,                  -- ms epoch
+  lastSeenAt  INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_sessions_userId    ON sessions(userId);
+CREATE INDEX IF NOT EXISTS idx_sessions_expiresAt ON sessions(expiresAt);
+```
+
+**为什么 `sessions.id` 存 sha256(token) 而不是 token 本身：** 若 SQLite 文件被泄露（备份、误传、磁盘扫描），原始 token 会让攻击者直接冒充任意已登录用户。存 hash 后只能爆破。代价仅是每次请求一次 sha256。
+
+新模块：
+
+`src/data/users.ts`
+- `createUser(username, password): User` — 在事务里 INSERT；遇到 UNIQUE 冲突抛出 `UsernameTakenError`
+- `findByUsername(username): User | null`
+- `verifyPassword(plain, hash): Promise<boolean>` — bcryptjs compare
+- `countUsers(): number` — 用于 `/needs-setup`
+- `changePassword(userId, newPassword): void`
+
+`src/data/sessions.ts`
+- `createSession(userId): { token: string; expiresAt: number }` — 生成 32 字节随机 token（`crypto.randomBytes(32).toString('base64url')`），存 sha256
+- `validateAndTouch(rawToken): { userId, username } | null` — 单次 SQL JOIN：查 session + user；过期 → 返回 null + 删除该行；否则若 `now - lastSeenAt > 1h` 则 UPDATE 滑动续期到 `now + 7d`
+- `deleteSession(rawToken): void` — 退出
+- `deleteAllForUser(userId, exceptToken?): void` — change-password 时调用，可保留当前会话
+- `cleanupExpired(): void` — 定时任务
+
+### HTTP 层（`src/web/`）
+
+#### 新增中间件
+
+`src/web/middleware/requireAuth.ts`
+```
+读取 req.cookies.tsmb_session
+  → 缺失 → 401 { error: "unauthenticated" }
+  → 调 sessions.validateAndTouch
+  → null → 清 cookie + 401
+  → 有效 → req.user = { id, username }; next()
+```
+
+`src/web/middleware/csrf.ts`
+```
+若 method ∈ {GET, HEAD, OPTIONS} → next()
+否则要求 req.headers.origin || req.headers.referer 的 host 与 req.get('host') 一致
+  → 不一致或两者都缺失 → 403 { error: "bad origin" }
+```
+
+#### 新路由：`src/web/api/session.ts`
+
+挂在 `/api/session`，全部公共（不挂 requireAuth）：
+
+| Method | Path | 行为 |
+|---|---|---|
+| GET | `/needs-setup` | `{ needsSetup: users.countUsers() === 0 }` |
+| POST | `/setup` | Body `{ username, password }`。在事务内再次检查 `countUsers() === 0`：是则 INSERT user + 立刻 createSession + Set-Cookie + 200 `{ id, username }`；否则 409 `{ error: "already initialized" }` |
+| POST | `/login` | Body `{ username, password }`。匹配则 createSession + Set-Cookie + 200；不匹配则等待 250ms 后 401 `{ error: "invalid credentials" }`（常量时间延迟，降低用户名枚举风险） |
+| POST | `/logout` | 删 session，清 cookie，204 |
+| GET | `/me` | 走 requireAuth；返回 `{ id, username }` |
+| POST | `/change-password` | 走 requireAuth；Body `{ oldPassword, newPassword }`；通过则 changePassword + deleteAllForUser(except 当前) + 204 |
+
+> `/me` 与 `/change-password` 例外地需要 requireAuth —— 在路由内单独挂中间件，避免污染 `/api/session/*` 的公共属性。
+
+#### Cookie 规范
+
+- 名称：`tsmb_session`
+- 值：32 字节 random → base64url
+- 属性：`HttpOnly; SameSite=Lax; Path=/; Max-Age=604800`（7 天）
+- `Secure` 标志：当 `req.secure === true`（依赖 `trustProxy` + `X-Forwarded-Proto`）；本地 HTTP 调试时不加，避免 cookie 被丢弃
+
+#### 装配顺序（`src/web/server.ts`）
+
+```ts
+app.use(express.json({ limit: "400kb" }));
+app.use(cookieParser());                              // 新增
+
+// 公共
+app.get("/api/health", …);
+app.get("/api/config/public-url", …);
+app.use("/api/session", createSessionRouter(...));
+
+// 闸门（仅作用于下方注册的 /api/* 路由）
+app.use("/api", csrfOriginCheck);
+app.use("/api", requireAuth);
+
+// 受保护
+app.use("/api/bot",    createBotRouter(...));
+app.use("/api/music",  createMusicRouter(...));
+app.use("/api/player", createPlayerRouter(...));
+app.use("/api/auth",   createAuthRouter(...));        // 音乐平台 QR
+
+// 静态 SPA（公共，前端自行判定登录态后跳转）
+app.use(express.static(staticDir));
+app.get(/^(?!\/api|\/ws)/, sendIndex);
+```
+
+> Express 的 `app.use` 仅对匹配前缀生效。公共路由先注册即可命中；之后的 `app.use("/api", …)` 闸门只在公共路由未匹配时执行，因此 `/api/health`、`/api/config/public-url`、`/api/session/*` 不会被闸门拦截。
+
+#### 定时清理
+
+`server.start()` 内启动 `setInterval(cleanupExpired, 60 * 60 * 1000)`，`server.stop()` 内 `clearInterval`。
+
+### WebSocket 层（`src/web/websocket.ts` + `src/web/server.ts`）
+
+改造为手动 upgrade：
+
+```ts
+const wss = new WebSocketServer({ noServer: true });
+
+server.on("upgrade", (req, socket, head) => {
+  if (req.url !== "/ws") { socket.destroy(); return; }
+  const session = validateCookieFromHeaders(req.headers.cookie);
+  if (!session) {
+    socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+    socket.destroy();
+    return;
+  }
+  wss.handleUpgrade(req, socket, head, (ws) => {
+    (ws as any).userId = session.userId;
+    wss.emit("connection", ws, req);
+  });
+});
+```
+
+`validateCookieFromHeaders` 在 `src/web/auth/validateSession.ts` 提供，HTTP 中间件与 WS upgrade 共用同一实现，确保不会出现"HTTP 拒、WS 放行"或反之的偏差。
+
+不需要在 upgrade 上单独做 CSRF：浏览器在跨站 WebSocket 请求里仍会带 Origin 头，可在 validate 之外顺手比对 `req.headers.origin` host 与 `req.headers.host` 一致；不一致直接拒绝。
+
+### 前端层（`web/`）
+
+#### 新视图
+
+- `web/src/views/Login.vue` — 用户名 + 密码表单 → POST `/api/session/login` → 成功跳 `next` 或 `/`
+- `web/src/views/FirstRunSetup.vue` — 同样表单 + 二次确认密码 → POST `/api/session/setup` → 成功后自动登录并跳 `/`
+  - 名称避免与既有 `Setup.vue`（bot 创建向导）冲突
+
+#### Session 状态
+
+新增 `web/src/composables/useSession.ts`：暴露 `currentUser: Ref<User|null>`、`refresh()`、`logout()`、`needsSetup: Ref<boolean>`。在 `App.vue` mount 时调用 `refresh()`。
+
+#### 路由守卫（`web/src/router/index.ts`）
+
+- 公共路由：`/login`、`/setup`
+- 全局 `beforeEach`：
+  1. 先 `GET /api/session/needs-setup`（仅在 `needsSetup` 未知时拉一次并缓存）
+  2. `needsSetup === true` 且目标不是 `/setup` → `redirect('/setup')`
+  3. 否则 `GET /api/session/me`，401 且目标非公共路由 → `redirect('/login?next=<path>')`
+
+#### API 客户端
+
+- 所有 `fetch` 改为 `credentials: 'same-origin'`（若现有有 wrapper 则改一处；否则按文件逐个改 —— 实施时由 plan 列出）
+- 包一层 401 拦截器：任意受保护请求返回 401 → 清 `currentUser` → `router.push('/login')`
+
+#### UI
+
+- 顶栏新增已登录用户名 + "退出"按钮（POST `/logout` → `router.push('/login')`）
+- 修改密码入口暂放在已有的"设置"页签内（若无则新增极简 section）
+
+### 依赖
+
+新增到 `package.json`：
+
+```
+"bcryptjs": "^2.4.3",
+"cookie-parser": "^1.4.6",
+"@types/bcryptjs": "^2.4.6",
+"@types/cookie-parser": "^1.4.7"
+```
+
+不引入 `express-session`、`jsonwebtoken`、`passport` 等更大栈。
+
+## Data Flow
+
+### 首次启动
+
+```
+Browser → GET /         → static SPA
+SPA mounted → GET /api/session/needs-setup → { needsSetup: true }
+SPA → router.replace('/setup')
+User submits form → POST /api/session/setup
+Server (TX): countUsers() === 0 → INSERT user → createSession → Set-Cookie → 200
+SPA → currentUser refresh → router.replace('/')
+```
+
+### 已部署用户升级
+
+旧 `config.adminPassword` 字段保留不动；首次启动新版本仍会因 `users` 表为空而进入 setup 流程 —— 旧字段不被采纳，避免歧义。
+
+### 后续登录
+
+```
+SPA → GET /api/session/me → 401
+SPA → router.replace('/login?next=/queue')
+User submits → POST /api/session/login → Set-Cookie + 200
+SPA → currentUser refresh → router.replace('/queue')
+```
+
+### 受保护请求
+
+```
+SPA → fetch('/api/bot', { credentials: 'same-origin' })
+Server requireAuth: validateAndTouch(cookie)
+  → ok → req.user 注入 → 业务路由处理
+  → 不 ok → 401 → SPA 拦截器跳 /login
+```
+
+### WebSocket
+
+```
+SPA → new WebSocket(`${wsScheme}://${host}/ws`)   // 浏览器自动带 cookie
+Server upgrade handler: validateCookieFromHeaders
+  → ok → handleUpgrade → connection event
+  → 不 ok → HTTP 401 写回原始 socket → destroy
+```
+
+## Error Handling
+
+| 场景 | HTTP 响应 | 备注 |
+|---|---|---|
+| 未带 cookie | 401 `{ error: "unauthenticated" }` | requireAuth |
+| Cookie 解析失败 / token 不存在 | 401 + `Set-Cookie tsmb_session=; Max-Age=0` 清掉 | 自愈 |
+| Session 过期 | 同上 + DELETE 该行 | validateAndTouch 内部完成 |
+| 用户名/密码不匹配 | 401 `{ error: "invalid credentials" }` + 250ms 延迟 | 不区分"用户不存在"和"密码错"两类 |
+| `setup` 时已存在用户 | 409 `{ error: "already initialized" }` | 防止重复初始化 |
+| `setup` 用户名重复 | 在 `/setup` 流程中不可能（只允许 0 → 1） |  |
+| `change-password` 旧密码错 | 401 `{ error: "invalid credentials" }` |  |
+| CSRF Origin 不匹配 | 403 `{ error: "bad origin" }` |  |
+| WS 无 cookie / 校验失败 | 写回 HTTP/1.1 401 并 destroy socket | 在握手前拒绝，避免 onopen 假成功 |
+
+所有错误响应统一 `{ error: string }` 形式，匹配现有 API 风格。
+
+## Testing Strategy
+
+### 单元（vitest）
+
+`src/data/users.test.ts`
+- createUser 成功后 findByUsername 命中（大小写不敏感）
+- 重复 username 抛 UsernameTakenError
+- verifyPassword 正反例
+- changePassword 之后旧哈希不再验证通过
+
+`src/data/sessions.test.ts`
+- createSession 返回的 token 不是 DB 内 id（DB 内是 sha256(token)）
+- validateAndTouch 过期记录返回 null 且记录被删
+- validateAndTouch 未过 1h 不写 DB；过 1h 后写 DB（用 `Date.now` mock 验证）
+- deleteAllForUser(exceptToken) 保留指定会话
+
+### 集成（vitest + supertest，真 SQLite in-memory）
+
+`src/web/api/session.test.ts`
+- empty DB → /needs-setup 返回 true；/setup 成功；/needs-setup 再调返回 false；二次 /setup 返回 409
+- /login 成功后受保护路由 (`GET /api/bot`) 200；不带 cookie 401
+- /logout 之后同一 cookie 调受保护路由 401
+- /change-password 后 a) 旧密码 /login 失败 b) 新密码 /login 成功 c) 之前签发的其他 cookie 失效，当前 cookie 仍可用
+
+`src/web/middleware/csrf.test.ts`
+- 带匹配 Origin 的 POST 通过
+- Origin 与 host 不匹配 → 403
+- 同样规则适用 Referer
+- GET 永远通过
+
+`src/web/websocket.test.ts`（新增或扩展）
+- 无 cookie 的 ws 握手 → 收到 HTTP 401，socket 关闭
+- 带有效 cookie → 握手成功，收到 init 消息
+- Session 删除后已建立的 ws **不会**被主动断（明确记录此妥协 —— 见 Trade-offs）
+
+### 前端
+
+不在本 PR 引入新的 e2e 框架。手动用例（在 PR 描述里列）：
+- 全新数据库启动 → 自动跳 /setup → 创建账户 → 进入主界面
+- 退出 → 自动跳 /login
+- 关闭浏览器 7 天内再开 → 仍登录
+- 登录态下后端重启清空 sessions → 任意 API 调用 → 自动跳 /login
+
+## Files Changed
+
+```
+src/data/database.ts                       (schema migration)
+src/data/users.ts                          (new)
+src/data/users.test.ts                     (new)
+src/data/sessions.ts                       (new)
+src/data/sessions.test.ts                  (new)
+src/web/auth/validateSession.ts            (new, shared by HTTP + WS)
+src/web/middleware/requireAuth.ts          (new)
+src/web/middleware/csrf.ts                 (new)
+src/web/middleware/csrf.test.ts            (new)
+src/web/api/session.ts                     (new)
+src/web/api/session.test.ts                (new)
+src/web/server.ts                          (cookieParser + 公共白名单 + 闸门 + cleanup interval + WS upgrade 重构调用)
+src/web/websocket.ts                       (移除被动 path 绑定；改为 handleUpgrade 模式)
+src/web/websocket.test.ts                  (新增 / 扩展)
+package.json                               (deps)
+
+web/src/views/Login.vue                    (new)
+web/src/views/FirstRunSetup.vue            (new)
+web/src/composables/useSession.ts          (new)
+web/src/router/index.ts                    (公共路由 + beforeEach 守卫)
+web/src/api/*.ts                           (credentials: 'same-origin' + 401 拦截)
+web/src/App.vue                            (顶栏 logout + 当前用户名)
+```
+
+## Trade-offs / 已知妥协
+
+1. **会话失效不主动断 WS** —— 后台 deleteSession 后，已有 WS 仍在跑（直到客户端断或服务端进程重启）。原因：WS 长连接没有"每条消息再次鉴权"的廉价手段；为此引入会浪费时间。影响面有限：WS 只推状态、不接收 mutating 命令；所有写操作仍走 HTTP。
+2. **无登录限流** —— 见 Out of Scope。若部署面向公网，建议在反代层加 limit（如 nginx `limit_req`）。
+3. **`config.adminPassword` 留作未使用字段** —— 不迁移、不读取。后续 PR 可移除并加 schema migration。当前保留是为避免破坏旧 `config.json` 解析。
+4. **单一管理员模型** —— 多用户表已存在，但 UI 当前不暴露增删用户。下一个 PR 再加用户管理界面。
+5. **Origin/Referer CSRF 检查** —— 不是 token，但配合 `SameSite=Lax` 已能挡掉常规 CSRF 攻击。代价：会拒绝缺 Origin/Referer 的非浏览器客户端 POST 请求（如裸 curl）—— 这是预期行为。

From d3af918f53a36077fab4e4010eb5d3d5e8f1fd7b Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:18:10 +0800
Subject: [PATCH 02/35] docs(plan): WebUI authentication implementation plan

16 bite-sized tasks with TDD discipline:
- 10 backend (schema, users, sessions, middleware, /api/session router,
  server.ts wiring, WS upgrade gating + integration test)
- 5 frontend (useSession composable, Login + FirstRunSetup views,
  router guard, fetch wrapper, Navbar logout)
- 1 manual smoke test gate before PR

Notes /first-run as the admin-setup route since /setup is already taken
by the bot-creation wizard.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-05-27-webui-authentication.md  | 2215 +++++++++++++++++
 1 file changed, 2215 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-27-webui-authentication.md

diff --git a/docs/superpowers/plans/2026-05-27-webui-authentication.md b/docs/superpowers/plans/2026-05-27-webui-authentication.md
new file mode 100644
index 0000000..0093cc6
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-27-webui-authentication.md
@@ -0,0 +1,2215 @@
+# WebUI Authentication Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add username + password auth (multi-user) to the WebUI so that all `/api/*` (except an explicit public whitelist) and the `/ws` WebSocket reject unauthenticated requests, gated by a 7-day rolling cookie session.
+
+**Architecture:** Two new SQLite tables (`users`, `sessions`) reusing the existing better-sqlite3 instance, bcryptjs password hashing, sha256-hashed session IDs at rest, raw 32-byte random token in an HTTP-only `tsmb_session` cookie. Two Express middlewares (`requireAuth`, `csrfOriginCheck`) gate every protected `/api/*` router. The WebSocket switches from passive `path: "/ws"` binding to manual `server.on("upgrade", …)` so it validates the same cookie before accepting the handshake. Frontend gets a `useSession` composable, a router guard, a login view and a first-run wizard view; the existing `/setup` route (bot-creation wizard) is left untouched and the new admin-setup view is mounted at `/first-run` to avoid name collision.
+
+**Tech Stack:** TypeScript / Express 5 / better-sqlite3 / `ws` / Vitest / Vue 3 + Vue Router + Pinia / bcryptjs (pure JS, no native build).
+
+**Spec:** `docs/superpowers/specs/2026-05-27-webui-authentication-design.md`
+
+**Branch:** `feat/webui-auth` (already created and contains the spec commit `f7c1688`).
+
+---
+
+## Files map
+
+```
+NEW backend
+  src/data/users.ts
+  src/data/users.test.ts
+  src/data/sessions.ts
+  src/data/sessions.test.ts
+  src/web/auth/validateSession.ts
+  src/web/middleware/requireAuth.ts
+  src/web/middleware/requireAuth.test.ts
+  src/web/middleware/csrf.ts
+  src/web/middleware/csrf.test.ts
+  src/web/api/session.ts
+  src/web/api/session.test.ts
+  src/web/websocket-auth.test.ts
+
+MODIFIED backend
+  src/data/database.ts          (add users + sessions tables in initTables)
+  src/web/server.ts             (cookieParser, public/protected ordering, cleanup interval, manual ws upgrade)
+  src/web/websocket.ts          (no functional change; export setupWebSocket already passes wss)
+  package.json                  (deps)
+
+NEW frontend
+  web/src/views/Login.vue
+  web/src/views/FirstRunSetup.vue
+  web/src/composables/useSession.ts
+  web/src/api/http.ts           (small fetch wrapper with credentials + 401 handler)
+
+MODIFIED frontend
+  web/src/router/index.ts       (add /login, /first-run, beforeEach guard)
+  web/src/App.vue               (logout button + username chip in Navbar slot)
+  web/src/components/Navbar.vue (render the slot for logout/username)
+```
+
+> Note on `/setup` collision: the existing `Setup.vue` (mounted at `/setup`) is the bot-creation wizard, not admin setup. The new admin first-run wizard uses path `/first-run`. The spec said `/setup`; this plan supersedes it because the path is already taken.
+
+---
+
+## Task 1: Branch state + new dependencies
+
+**Files:**
+- Modify: `package.json`
+
+- [ ] **Step 1: Verify branch**
+
+```bash
+git status --short
+git branch --show-current
+```
+Expected: clean working tree on `feat/webui-auth`.
+
+- [ ] **Step 2: Install runtime + type deps**
+
+```bash
+npm install bcryptjs@^2.4.3 cookie-parser@^1.4.7
+npm install --save-dev @types/bcryptjs@^2.4.6 @types/cookie-parser@^1.4.8
+```
+
+- [ ] **Step 3: Sanity-check installation**
+
+```bash
+node -e "console.log(require('bcryptjs').hashSync('x', 4))"
+```
+Expected: a bcrypt hash string beginning with `$2a$04$`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add package.json package-lock.json
+git commit -m "deps: add bcryptjs + cookie-parser for WebUI auth"
+```
+
+---
+
+## Task 2: Schema migration for users + sessions
+
+**Files:**
+- Modify: `src/data/database.ts:102-131` (extend `initTables`)
+- Modify: `src/data/database.test.ts` (add table-creation assertion)
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `src/data/database.test.ts` inside the existing `describe("database", …)` block, after the "creates tables on init" test:
+
+```ts
+it("creates users and sessions tables on init", () => {
+  const tables = botDb.db
+    .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+    .all() as Array<{ name: string }>;
+  const names = tables.map((t) => t.name);
+  expect(names).toContain("users");
+  expect(names).toContain("sessions");
+
+  const userCols = botDb.db.prepare("PRAGMA table_info(users)").all() as Array<{ name: string }>;
+  const userColNames = userCols.map((c) => c.name).sort();
+  expect(userColNames).toEqual(["createdAt", "id", "passwordHash", "updatedAt", "username"]);
+
+  const sessionCols = botDb.db.prepare("PRAGMA table_info(sessions)").all() as Array<{ name: string }>;
+  const sessionColNames = sessionCols.map((c) => c.name).sort();
+  expect(sessionColNames).toEqual(["createdAt", "expiresAt", "id", "lastSeenAt", "userId"]);
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npx vitest run src/data/database.test.ts
+```
+Expected: FAIL on "creates users and sessions tables on init" with assertion error.
+
+- [ ] **Step 3: Add tables in `initTables`**
+
+In `src/data/database.ts`, replace the `db.exec(\`...\`)` call inside `initTables` so it ends like this (keep the existing `play_history` and `bot_instances` blocks, append the two new tables to the same string):
+
+```ts
+function initTables(db: Database.Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS play_history (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      botId TEXT NOT NULL,
+      songId TEXT NOT NULL,
+      songName TEXT NOT NULL,
+      artist TEXT NOT NULL,
+      album TEXT NOT NULL,
+      platform TEXT NOT NULL,
+      coverUrl TEXT NOT NULL,
+      playedAt TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS bot_instances (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      serverAddress TEXT NOT NULL,
+      serverPort INTEGER NOT NULL,
+      nickname TEXT NOT NULL,
+      defaultChannel TEXT NOT NULL,
+      channelPassword TEXT NOT NULL,
+      autoStart INTEGER NOT NULL DEFAULT 0,
+      serverProtocol TEXT NOT NULL DEFAULT '',
+      ts6ApiKey TEXT NOT NULL DEFAULT '',
+      serverPassword TEXT NOT NULL DEFAULT '',
+      identity TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS users (
+      id TEXT PRIMARY KEY,
+      username TEXT NOT NULL UNIQUE COLLATE NOCASE,
+      passwordHash TEXT NOT NULL,
+      createdAt INTEGER NOT NULL,
+      updatedAt INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      userId TEXT NOT NULL,
+      createdAt INTEGER NOT NULL,
+      expiresAt INTEGER NOT NULL,
+      lastSeenAt INTEGER NOT NULL,
+      FOREIGN KEY (userId) REFERENCES users(id) ON DELETE CASCADE
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_sessions_userId ON sessions(userId);
+    CREATE INDEX IF NOT EXISTS idx_sessions_expiresAt ON sessions(expiresAt);
+  `);
+}
+```
+
+Also enable FK enforcement in `createDatabase` (better-sqlite3 default is OFF). Add this line **immediately after** `db.pragma("journal_mode = WAL")`:
+
+```ts
+db.pragma("foreign_keys = ON");
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npx vitest run src/data/database.test.ts
+```
+Expected: all tests PASS, including the new one.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/data/database.ts src/data/database.test.ts
+git commit -m "feat(db): add users and sessions tables for WebUI auth"
+```
+
+---
+
+## Task 3: `src/data/users.ts` — user CRUD + password hashing
+
+**Files:**
+- Create: `src/data/users.ts`
+- Create: `src/data/users.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/data/users.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createDatabase, type BotDatabase } from "./database.js";
+import { createUserStore, UsernameTakenError, type UserStore } from "./users.js";
+
+describe("UserStore", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+
+  beforeEach(() => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+  });
+
+  afterEach(() => {
+    botDb.close();
+  });
+
+  it("countUsers is 0 on a fresh db", () => {
+    expect(users.countUsers()).toBe(0);
+  });
+
+  it("createUser stores the user and bumps countUsers", async () => {
+    const u = await users.createUser("alice", "pw-hunter2");
+    expect(u.id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(u.username).toBe("alice");
+    expect(users.countUsers()).toBe(1);
+  });
+
+  it("findByUsername is case-insensitive and returns null for missing", async () => {
+    await users.createUser("Alice", "pw");
+    expect(users.findByUsername("ALICE")).not.toBeNull();
+    expect(users.findByUsername("alice")).not.toBeNull();
+    expect(users.findByUsername("bob")).toBeNull();
+  });
+
+  it("createUser rejects duplicate usernames (case-insensitive)", async () => {
+    await users.createUser("Alice", "pw");
+    await expect(users.createUser("alice", "pw2")).rejects.toBeInstanceOf(UsernameTakenError);
+  });
+
+  it("verifyPassword accepts correct password and rejects wrong one", async () => {
+    await users.createUser("alice", "correct-horse-battery-staple");
+    const row = users.findByUsername("alice");
+    expect(row).not.toBeNull();
+    expect(await users.verifyPassword("correct-horse-battery-staple", row!.passwordHash)).toBe(true);
+    expect(await users.verifyPassword("wrong", row!.passwordHash)).toBe(false);
+  });
+
+  it("changePassword updates the hash so the old password no longer verifies", async () => {
+    const u = await users.createUser("alice", "old");
+    await users.changePassword(u.id, "new");
+    const row = users.findByUsername("alice");
+    expect(await users.verifyPassword("old", row!.passwordHash)).toBe(false);
+    expect(await users.verifyPassword("new", row!.passwordHash)).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npx vitest run src/data/users.test.ts
+```
+Expected: FAIL — module `./users.js` not found.
+
+- [ ] **Step 3: Implement `src/data/users.ts`**
+
+```ts
+import { randomUUID } from "node:crypto";
+import type Database from "better-sqlite3";
+import bcrypt from "bcryptjs";
+
+const BCRYPT_ROUNDS = 12;
+
+export interface UserRow {
+  id: string;
+  username: string;
+  passwordHash: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface UserStore {
+  countUsers(): number;
+  createUser(username: string, password: string): Promise<UserRow>;
+  findByUsername(username: string): UserRow | null;
+  findById(id: string): UserRow | null;
+  verifyPassword(plain: string, hash: string): Promise<boolean>;
+  changePassword(userId: string, newPassword: string): Promise<void>;
+}
+
+export class UsernameTakenError extends Error {
+  constructor(username: string) {
+    super(`username taken: ${username}`);
+    this.name = "UsernameTakenError";
+  }
+}
+
+export function createUserStore(db: Database.Database): UserStore {
+  const countStmt = db.prepare("SELECT COUNT(*) AS n FROM users");
+  const insertStmt = db.prepare(
+    "INSERT INTO users (id, username, passwordHash, createdAt, updatedAt) VALUES (?, ?, ?, ?, ?)"
+  );
+  const findByUsernameStmt = db.prepare(
+    "SELECT id, username, passwordHash, createdAt, updatedAt FROM users WHERE username = ? COLLATE NOCASE"
+  );
+  const findByIdStmt = db.prepare(
+    "SELECT id, username, passwordHash, createdAt, updatedAt FROM users WHERE id = ?"
+  );
+  const updatePasswordStmt = db.prepare(
+    "UPDATE users SET passwordHash = ?, updatedAt = ? WHERE id = ?"
+  );
+
+  return {
+    countUsers() {
+      return (countStmt.get() as { n: number }).n;
+    },
+
+    async createUser(username, password) {
+      const hash = await bcrypt.hash(password, BCRYPT_ROUNDS);
+      const id = randomUUID();
+      const now = Date.now();
+      try {
+        insertStmt.run(id, username, hash, now, now);
+      } catch (err) {
+        const msg = (err as Error).message;
+        if (msg.includes("UNIQUE") && msg.includes("users.username")) {
+          throw new UsernameTakenError(username);
+        }
+        throw err;
+      }
+      return { id, username, passwordHash: hash, createdAt: now, updatedAt: now };
+    },
+
+    findByUsername(username) {
+      return (findByUsernameStmt.get(username) as UserRow | undefined) ?? null;
+    },
+
+    findById(id) {
+      return (findByIdStmt.get(id) as UserRow | undefined) ?? null;
+    },
+
+    verifyPassword(plain, hash) {
+      return bcrypt.compare(plain, hash);
+    },
+
+    async changePassword(userId, newPassword) {
+      const hash = await bcrypt.hash(newPassword, BCRYPT_ROUNDS);
+      updatePasswordStmt.run(hash, Date.now(), userId);
+    },
+  };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npx vitest run src/data/users.test.ts
+```
+Expected: all 6 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/data/users.ts src/data/users.test.ts
+git commit -m "feat(auth): add UserStore with bcryptjs password hashing"
+```
+
+---
+
+## Task 4: `src/data/sessions.ts` — session CRUD + rolling renewal
+
+**Files:**
+- Create: `src/data/sessions.ts`
+- Create: `src/data/sessions.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/data/sessions.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { createHash } from "node:crypto";
+import { createDatabase, type BotDatabase } from "./database.js";
+import { createUserStore, type UserStore } from "./users.js";
+import { createSessionStore, type SessionStore, SESSION_TTL_MS, SESSION_TOUCH_INTERVAL_MS } from "./sessions.js";
+
+function sha256(token: string) {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+describe("SessionStore", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+  let sessions: SessionStore;
+  let userId: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+    sessions = createSessionStore(botDb.db);
+    const u = await users.createUser("alice", "pw");
+    userId = u.id;
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    botDb.close();
+  });
+
+  it("createSession returns a raw token whose sha256 matches the DB row id", () => {
+    const { token } = sessions.createSession(userId);
+    const row = botDb.db.prepare("SELECT id FROM sessions").get() as { id: string };
+    expect(row.id).toBe(sha256(token));
+    expect(row.id).not.toBe(token);
+  });
+
+  it("validateAndTouch returns the user for a fresh token", () => {
+    const { token } = sessions.createSession(userId);
+    const result = sessions.validateAndTouch(token);
+    expect(result).not.toBeNull();
+    expect(result!.userId).toBe(userId);
+    expect(result!.username).toBe("alice");
+  });
+
+  it("validateAndTouch returns null and deletes the row for an expired session", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    const { token } = sessions.createSession(userId);
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z").getTime() + SESSION_TTL_MS + 1000);
+    expect(sessions.validateAndTouch(token)).toBeNull();
+    const remaining = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(remaining).toBe(0);
+  });
+
+  it("validateAndTouch does not write the DB if called again within the touch interval", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    const { token } = sessions.createSession(userId);
+    const before = botDb.db.prepare("SELECT lastSeenAt FROM sessions").get() as { lastSeenAt: number };
+    vi.advanceTimersByTime(SESSION_TOUCH_INTERVAL_MS - 1000);
+    sessions.validateAndTouch(token);
+    const after = botDb.db.prepare("SELECT lastSeenAt FROM sessions").get() as { lastSeenAt: number };
+    expect(after.lastSeenAt).toBe(before.lastSeenAt);
+  });
+
+  it("validateAndTouch writes lastSeenAt and extends expiresAt past the touch interval", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    const { token, expiresAt: initialExpiry } = sessions.createSession(userId);
+    vi.advanceTimersByTime(SESSION_TOUCH_INTERVAL_MS + 1000);
+    sessions.validateAndTouch(token);
+    const row = botDb.db.prepare("SELECT lastSeenAt, expiresAt FROM sessions").get() as { lastSeenAt: number; expiresAt: number };
+    expect(row.lastSeenAt).toBe(Date.now());
+    expect(row.expiresAt).toBeGreaterThan(initialExpiry);
+  });
+
+  it("deleteSession removes the row", () => {
+    const { token } = sessions.createSession(userId);
+    sessions.deleteSession(token);
+    const remaining = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(remaining).toBe(0);
+    expect(sessions.validateAndTouch(token)).toBeNull();
+  });
+
+  it("deleteAllForUser keeps the exceptToken session", () => {
+    const a = sessions.createSession(userId);
+    const b = sessions.createSession(userId);
+    sessions.deleteAllForUser(userId, a.token);
+    expect(sessions.validateAndTouch(a.token)).not.toBeNull();
+    expect(sessions.validateAndTouch(b.token)).toBeNull();
+  });
+
+  it("cleanupExpired removes only expired rows", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    sessions.createSession(userId); // expires later
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z").getTime() + SESSION_TTL_MS + 1000);
+    sessions.createSession(userId); // fresh
+    sessions.cleanupExpired();
+    const remaining = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(remaining).toBe(1);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npx vitest run src/data/sessions.test.ts
+```
+Expected: FAIL — `./sessions.js` not found.
+
+- [ ] **Step 3: Implement `src/data/sessions.ts`**
+
+```ts
+import { createHash, randomBytes } from "node:crypto";
+import type Database from "better-sqlite3";
+
+export const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+export const SESSION_TOUCH_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+
+export interface SessionValidation {
+  userId: string;
+  username: string;
+}
+
+export interface SessionStore {
+  createSession(userId: string): { token: string; expiresAt: number };
+  validateAndTouch(rawToken: string): SessionValidation | null;
+  deleteSession(rawToken: string): void;
+  deleteAllForUser(userId: string, exceptToken?: string): void;
+  cleanupExpired(): void;
+}
+
+function hashToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+export function createSessionStore(db: Database.Database): SessionStore {
+  const insertStmt = db.prepare(
+    "INSERT INTO sessions (id, userId, createdAt, expiresAt, lastSeenAt) VALUES (?, ?, ?, ?, ?)"
+  );
+  const selectStmt = db.prepare(`
+    SELECT s.id, s.userId, s.expiresAt, s.lastSeenAt, u.username
+    FROM sessions s INNER JOIN users u ON u.id = s.userId
+    WHERE s.id = ?
+  `);
+  const deleteByIdStmt = db.prepare("DELETE FROM sessions WHERE id = ?");
+  const touchStmt = db.prepare(
+    "UPDATE sessions SET lastSeenAt = ?, expiresAt = ? WHERE id = ?"
+  );
+  const deleteAllForUserStmt = db.prepare("DELETE FROM sessions WHERE userId = ?");
+  const deleteAllForUserExceptStmt = db.prepare(
+    "DELETE FROM sessions WHERE userId = ? AND id != ?"
+  );
+  const cleanupStmt = db.prepare("DELETE FROM sessions WHERE expiresAt < ?");
+
+  return {
+    createSession(userId) {
+      const token = randomBytes(32).toString("base64url");
+      const id = hashToken(token);
+      const now = Date.now();
+      const expiresAt = now + SESSION_TTL_MS;
+      insertStmt.run(id, userId, now, expiresAt, now);
+      return { token, expiresAt };
+    },
+
+    validateAndTouch(rawToken) {
+      if (!rawToken) return null;
+      const id = hashToken(rawToken);
+      const row = selectStmt.get(id) as
+        | { id: string; userId: string; expiresAt: number; lastSeenAt: number; username: string }
+        | undefined;
+      if (!row) return null;
+      const now = Date.now();
+      if (row.expiresAt < now) {
+        deleteByIdStmt.run(id);
+        return null;
+      }
+      if (now - row.lastSeenAt > SESSION_TOUCH_INTERVAL_MS) {
+        touchStmt.run(now, now + SESSION_TTL_MS, id);
+      }
+      return { userId: row.userId, username: row.username };
+    },
+
+    deleteSession(rawToken) {
+      deleteByIdStmt.run(hashToken(rawToken));
+    },
+
+    deleteAllForUser(userId, exceptToken) {
+      if (exceptToken) {
+        deleteAllForUserExceptStmt.run(userId, hashToken(exceptToken));
+      } else {
+        deleteAllForUserStmt.run(userId);
+      }
+    },
+
+    cleanupExpired() {
+      cleanupStmt.run(Date.now());
+    },
+  };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npx vitest run src/data/sessions.test.ts
+```
+Expected: all 8 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/data/sessions.ts src/data/sessions.test.ts
+git commit -m "feat(auth): add SessionStore with rolling renewal and at-rest token hashing"
+```
+
+---
+
+## Task 5: `src/web/auth/validateSession.ts` — shared cookie helper
+
+**Files:**
+- Create: `src/web/auth/validateSession.ts`
+
+> Used by both the HTTP middleware (`requireAuth`) and the WS upgrade handler. Centralised so both paths can never drift apart.
+
+- [ ] **Step 1: Implement (no separate test — exercised by middleware and ws tests)**
+
+```ts
+import type { SessionStore, SessionValidation } from "../../data/sessions.js";
+
+export const SESSION_COOKIE_NAME = "tsmb_session";
+
+/**
+ * Validate the session cookie carried on an arbitrary HTTP-like header bag.
+ * Used by Express middleware (req.headers.cookie) AND by the raw WebSocket
+ * upgrade handler (req.headers.cookie) — they share this exact behavior.
+ */
+export function validateSessionFromHeaders(
+  rawCookieHeader: string | undefined,
+  sessions: SessionStore
+): SessionValidation | null {
+  if (!rawCookieHeader) return null;
+  const token = parseCookie(rawCookieHeader, SESSION_COOKIE_NAME);
+  if (!token) return null;
+  return sessions.validateAndTouch(token);
+}
+
+function parseCookie(header: string, name: string): string | null {
+  for (const part of header.split(";")) {
+    const trimmed = part.trim();
+    const eq = trimmed.indexOf("=");
+    if (eq < 1) continue;
+    if (trimmed.slice(0, eq) !== name) continue;
+    try {
+      return decodeURIComponent(trimmed.slice(eq + 1));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/web/auth/validateSession.ts
+git commit -m "feat(auth): add shared validateSessionFromHeaders helper"
+```
+
+---
+
+## Task 6: `requireAuth` middleware
+
+**Files:**
+- Create: `src/web/middleware/requireAuth.ts`
+- Create: `src/web/middleware/requireAuth.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/web/middleware/requireAuth.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore } from "../../data/users.js";
+import { createSessionStore } from "../../data/sessions.js";
+import { createRequireAuth } from "./requireAuth.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+describe("requireAuth middleware", () => {
+  let botDb: BotDatabase;
+  let app: express.Express;
+  let validToken: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const u = await users.createUser("alice", "pw");
+    validToken = sessions.createSession(u.id).token;
+
+    app = express();
+    app.use(cookieParser());
+    app.use(createRequireAuth(sessions));
+    app.get("/protected", (req, res) => {
+      res.json({ ok: true, user: (req as any).user });
+    });
+  });
+
+  afterEach(() => {
+    botDb.close();
+  });
+
+  it("rejects requests without a session cookie", async () => {
+    const res = await request(app).get("/protected");
+    expect(res.status).toBe(401);
+    expect(res.body).toEqual({ error: "unauthenticated" });
+  });
+
+  it("rejects requests with an unknown session cookie", async () => {
+    const res = await request(app)
+      .get("/protected")
+      .set("Cookie", `${SESSION_COOKIE_NAME}=garbage`);
+    expect(res.status).toBe(401);
+  });
+
+  it("allows requests with a valid session cookie and attaches req.user", async () => {
+    const res = await request(app)
+      .get("/protected")
+      .set("Cookie", `${SESSION_COOKIE_NAME}=${validToken}`);
+    expect(res.status).toBe(200);
+    expect(res.body.ok).toBe(true);
+    expect(res.body.user.username).toBe("alice");
+  });
+});
+```
+
+> Add `supertest` as a devDep if not present:
+> ```bash
+> npm install --save-dev supertest@^7.1.4 @types/supertest@^6.0.3
+> ```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npx vitest run src/web/middleware/requireAuth.test.ts
+```
+Expected: FAIL — `./requireAuth.js` does not export `createRequireAuth`.
+
+- [ ] **Step 3: Implement `src/web/middleware/requireAuth.ts`**
+
+```ts
+import type { Request, Response, NextFunction, RequestHandler } from "express";
+import type { SessionStore } from "../../data/sessions.js";
+import { validateSessionFromHeaders, SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+declare module "express-serve-static-core" {
+  interface Request {
+    user?: { id: string; username: string };
+  }
+}
+
+export function createRequireAuth(sessions: SessionStore): RequestHandler {
+  return function requireAuth(req: Request, res: Response, next: NextFunction) {
+    const result = validateSessionFromHeaders(req.headers.cookie, sessions);
+    if (!result) {
+      res.clearCookie(SESSION_COOKIE_NAME, { path: "/" });
+      res.status(401).json({ error: "unauthenticated" });
+      return;
+    }
+    req.user = { id: result.userId, username: result.username };
+    next();
+  };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npx vitest run src/web/middleware/requireAuth.test.ts
+```
+Expected: all 3 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/web/middleware/requireAuth.ts src/web/middleware/requireAuth.test.ts package.json package-lock.json
+git commit -m "feat(auth): add requireAuth middleware"
+```
+
+---
+
+## Task 7: `csrfOriginCheck` middleware
+
+**Files:**
+- Create: `src/web/middleware/csrf.ts`
+- Create: `src/web/middleware/csrf.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import { describe, it, expect, beforeEach } from "vitest";
+import express from "express";
+import request from "supertest";
+import { csrfOriginCheck } from "./csrf.js";
+
+describe("csrfOriginCheck middleware", () => {
+  let app: express.Express;
+
+  beforeEach(() => {
+    app = express();
+    app.use(csrfOriginCheck);
+    app.get("/", (_req, res) => res.json({ ok: true }));
+    app.post("/", (_req, res) => res.json({ ok: true }));
+  });
+
+  it("allows safe methods (GET/HEAD/OPTIONS) without Origin", async () => {
+    const res = await request(app).get("/");
+    expect(res.status).toBe(200);
+  });
+
+  it("rejects POST without Origin or Referer", async () => {
+    const res = await request(app).post("/");
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: "bad origin" });
+  });
+
+  it("accepts POST when Origin host matches request host", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Origin", "https://example.com");
+    expect(res.status).toBe(200);
+  });
+
+  it("rejects POST when Origin host does not match request host", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Origin", "https://evil.com");
+    expect(res.status).toBe(403);
+  });
+
+  it("accepts POST when Referer host matches and Origin is absent", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Referer", "https://example.com/some/path");
+    expect(res.status).toBe(200);
+  });
+
+  it("rejects POST when Referer host does not match", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Referer", "https://evil.com/some/path");
+    expect(res.status).toBe(403);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npx vitest run src/web/middleware/csrf.test.ts
+```
+Expected: FAIL — `./csrf.js` not found.
+
+- [ ] **Step 3: Implement `src/web/middleware/csrf.ts`**
+
+```ts
+import type { Request, Response, NextFunction } from "express";
+
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/**
+ * Same-origin CSRF protection. For mutating requests, the Origin or Referer
+ * header must indicate a host equal to the request's own host.
+ *
+ * SameSite=Lax on the session cookie blocks classic cross-site form posts;
+ * this header check covers the remaining attack surface (fetch from a malicious
+ * page that omits SameSite-restricted cookies but tries via Origin spoofing
+ * is not possible — the browser sets Origin).
+ */
+export function csrfOriginCheck(req: Request, res: Response, next: NextFunction): void {
+  if (SAFE_METHODS.has(req.method)) {
+    next();
+    return;
+  }
+  const expectedHost = req.get("host");
+  const originHeader = req.get("origin");
+  const refererHeader = req.get("referer");
+  const headerHost = hostOf(originHeader) ?? hostOf(refererHeader);
+  if (!headerHost || !expectedHost || headerHost !== expectedHost) {
+    res.status(403).json({ error: "bad origin" });
+    return;
+  }
+  next();
+}
+
+function hostOf(url: string | undefined): string | null {
+  if (!url) return null;
+  try {
+    return new URL(url).host;
+  } catch {
+    return null;
+  }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npx vitest run src/web/middleware/csrf.test.ts
+```
+Expected: all 6 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/web/middleware/csrf.ts src/web/middleware/csrf.test.ts
+git commit -m "feat(auth): add csrfOriginCheck middleware"
+```
+
+---
+
+## Task 8: `/api/session` router (login, logout, setup, me, change-password)
+
+**Files:**
+- Create: `src/web/api/session.ts`
+- Create: `src/web/api/session.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/web/api/session.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import pino from "pino";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore, type UserStore } from "../../data/users.js";
+import { createSessionStore, type SessionStore } from "../../data/sessions.js";
+import { createSessionRouter } from "./session.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+function makeApp(users: UserStore, sessions: SessionStore) {
+  const app = express();
+  app.use(express.json());
+  app.use(cookieParser());
+  app.use("/api/session", createSessionRouter(users, sessions, pino({ level: "silent" })));
+  return app;
+}
+
+function extractCookie(res: request.Response): string {
+  const header = res.headers["set-cookie"];
+  const arr = Array.isArray(header) ? header : header ? [header] : [];
+  const found = arr.find((c) => c.startsWith(`${SESSION_COOKIE_NAME}=`));
+  if (!found) throw new Error("no session cookie set");
+  return found.split(";")[0]; // "tsmb_session=xxxx"
+}
+
+describe("session router", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+  let sessions: SessionStore;
+  let app: express.Express;
+
+  beforeEach(() => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+    sessions = createSessionStore(botDb.db);
+    app = makeApp(users, sessions);
+  });
+
+  afterEach(() => botDb.close());
+
+  it("GET /needs-setup returns true on an empty db", async () => {
+    const res = await request(app).get("/api/session/needs-setup");
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ needsSetup: true });
+  });
+
+  it("POST /setup creates the first admin, logs them in, and returns false from /needs-setup afterwards", async () => {
+    const setupRes = await request(app)
+      .post("/api/session/setup")
+      .send({ username: "alice", password: "hunter2-hunter2" });
+    expect(setupRes.status).toBe(200);
+    expect(setupRes.body.username).toBe("alice");
+    extractCookie(setupRes); // throws if missing
+
+    const needs = await request(app).get("/api/session/needs-setup");
+    expect(needs.body).toEqual({ needsSetup: false });
+  });
+
+  it("POST /setup returns 409 once a user already exists", async () => {
+    await users.createUser("admin", "pw");
+    const res = await request(app)
+      .post("/api/session/setup")
+      .send({ username: "alice", password: "pw" });
+    expect(res.status).toBe(409);
+    expect(res.body).toEqual({ error: "already initialized" });
+  });
+
+  it("POST /login returns 401 with constant-time delay on bad credentials", async () => {
+    await users.createUser("alice", "correct");
+    const start = Date.now();
+    const res = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "wrong" });
+    expect(res.status).toBe(401);
+    expect(res.body).toEqual({ error: "invalid credentials" });
+    expect(Date.now() - start).toBeGreaterThanOrEqual(200);
+  }, 10_000);
+
+  it("POST /login sets a session cookie on success", async () => {
+    await users.createUser("alice", "pw");
+    const res = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "pw" });
+    expect(res.status).toBe(200);
+    expect(res.body.username).toBe("alice");
+    extractCookie(res);
+  });
+
+  it("GET /me returns the current user when cookie is present, 401 otherwise", async () => {
+    await users.createUser("alice", "pw");
+    const loginRes = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "pw" });
+    const cookie = extractCookie(loginRes);
+
+    const me = await request(app).get("/api/session/me").set("Cookie", cookie);
+    expect(me.status).toBe(200);
+    expect(me.body.username).toBe("alice");
+
+    const anon = await request(app).get("/api/session/me");
+    expect(anon.status).toBe(401);
+  });
+
+  it("POST /logout deletes the session and clears the cookie", async () => {
+    await users.createUser("alice", "pw");
+    const loginRes = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "pw" });
+    const cookie = extractCookie(loginRes);
+
+    const logout = await request(app).post("/api/session/logout").set("Cookie", cookie);
+    expect(logout.status).toBe(204);
+
+    const me = await request(app).get("/api/session/me").set("Cookie", cookie);
+    expect(me.status).toBe(401);
+  });
+
+  it("POST /change-password requires old password and invalidates other sessions", async () => {
+    const u = await users.createUser("alice", "old");
+    const cookieA = extractCookie(
+      await request(app).post("/api/session/login").send({ username: "alice", password: "old" })
+    );
+    const cookieB = extractCookie(
+      await request(app).post("/api/session/login").send({ username: "alice", password: "old" })
+    );
+
+    const wrongOld = await request(app)
+      .post("/api/session/change-password")
+      .set("Cookie", cookieA)
+      .send({ oldPassword: "WRONG", newPassword: "new" });
+    expect(wrongOld.status).toBe(401);
+
+    const ok = await request(app)
+      .post("/api/session/change-password")
+      .set("Cookie", cookieA)
+      .send({ oldPassword: "old", newPassword: "new" });
+    expect(ok.status).toBe(204);
+
+    // Current session (cookieA) still valid
+    const meA = await request(app).get("/api/session/me").set("Cookie", cookieA);
+    expect(meA.status).toBe(200);
+
+    // Other session (cookieB) invalidated
+    const meB = await request(app).get("/api/session/me").set("Cookie", cookieB);
+    expect(meB.status).toBe(401);
+
+    expect(u.id).toBe(meA.body.id);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npx vitest run src/web/api/session.test.ts
+```
+Expected: FAIL — `./session.js` not found.
+
+- [ ] **Step 3: Implement `src/web/api/session.ts`**
+
+```ts
+import { Router } from "express";
+import type { Request, Response, NextFunction } from "express";
+import type { Logger } from "../../logger.js";
+import type { UserStore } from "../../data/users.js";
+import { UsernameTakenError } from "../../data/users.js";
+import type { SessionStore } from "../../data/sessions.js";
+import { SESSION_TTL_MS } from "../../data/sessions.js";
+import { SESSION_COOKIE_NAME, validateSessionFromHeaders } from "../auth/validateSession.js";
+
+const FAILED_LOGIN_DELAY_MS = 250;
+
+function setSessionCookie(res: Response, token: string): void {
+  res.cookie(SESSION_COOKIE_NAME, token, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: res.req.secure,
+    path: "/",
+    maxAge: SESSION_TTL_MS,
+  });
+}
+
+function clearSessionCookie(res: Response): void {
+  res.clearCookie(SESSION_COOKIE_NAME, { path: "/" });
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isValidUsername(v: unknown): v is string {
+  return typeof v === "string" && /^[A-Za-z0-9_\-.]{3,32}$/.test(v);
+}
+
+function isValidPassword(v: unknown): v is string {
+  return typeof v === "string" && v.length >= 8 && v.length <= 200;
+}
+
+export function createSessionRouter(
+  users: UserStore,
+  sessions: SessionStore,
+  logger: Logger
+): Router {
+  const router = Router();
+
+  const requireAuthInline = (req: Request, res: Response, next: NextFunction) => {
+    const result = validateSessionFromHeaders(req.headers.cookie, sessions);
+    if (!result) {
+      clearSessionCookie(res);
+      res.status(401).json({ error: "unauthenticated" });
+      return;
+    }
+    req.user = { id: result.userId, username: result.username };
+    next();
+  };
+
+  router.get("/needs-setup", (_req, res) => {
+    res.json({ needsSetup: users.countUsers() === 0 });
+  });
+
+  router.post("/setup", async (req, res) => {
+    const { username, password } = req.body ?? {};
+    if (!isValidUsername(username) || !isValidPassword(password)) {
+      res.status(400).json({ error: "invalid username or password" });
+      return;
+    }
+    if (users.countUsers() !== 0) {
+      res.status(409).json({ error: "already initialized" });
+      return;
+    }
+    try {
+      const user = await users.createUser(username, password);
+      const { token } = sessions.createSession(user.id);
+      setSessionCookie(res, token);
+      logger.info({ userId: user.id, username }, "First admin created");
+      res.json({ id: user.id, username: user.username });
+    } catch (err) {
+      if (err instanceof UsernameTakenError) {
+        res.status(409).json({ error: "already initialized" });
+        return;
+      }
+      logger.error({ err }, "setup failed");
+      res.status(500).json({ error: "internal" });
+    }
+  });
+
+  router.post("/login", async (req, res) => {
+    const { username, password } = req.body ?? {};
+    if (typeof username !== "string" || typeof password !== "string") {
+      res.status(400).json({ error: "invalid request" });
+      return;
+    }
+    const user = users.findByUsername(username);
+    const ok = user ? await users.verifyPassword(password, user.passwordHash) : false;
+    if (!user || !ok) {
+      await delay(FAILED_LOGIN_DELAY_MS);
+      res.status(401).json({ error: "invalid credentials" });
+      return;
+    }
+    const { token } = sessions.createSession(user.id);
+    setSessionCookie(res, token);
+    res.json({ id: user.id, username: user.username });
+  });
+
+  router.post("/logout", (req, res) => {
+    const cookieHeader = req.headers.cookie;
+    if (cookieHeader) {
+      const match = cookieHeader.split(";").map((p) => p.trim()).find((p) => p.startsWith(`${SESSION_COOKIE_NAME}=`));
+      if (match) {
+        const token = decodeURIComponent(match.slice(SESSION_COOKIE_NAME.length + 1));
+        sessions.deleteSession(token);
+      }
+    }
+    clearSessionCookie(res);
+    res.status(204).end();
+  });
+
+  router.get("/me", requireAuthInline, (req, res) => {
+    res.json(req.user);
+  });
+
+  router.post("/change-password", requireAuthInline, async (req, res) => {
+    const { oldPassword, newPassword } = req.body ?? {};
+    if (typeof oldPassword !== "string" || !isValidPassword(newPassword)) {
+      res.status(400).json({ error: "invalid request" });
+      return;
+    }
+    const u = users.findById(req.user!.id);
+    if (!u || !(await users.verifyPassword(oldPassword, u.passwordHash))) {
+      await delay(FAILED_LOGIN_DELAY_MS);
+      res.status(401).json({ error: "invalid credentials" });
+      return;
+    }
+    await users.changePassword(u.id, newPassword);
+    const currentToken = parseTokenFromCookie(req.headers.cookie);
+    sessions.deleteAllForUser(u.id, currentToken ?? undefined);
+    res.status(204).end();
+  });
+
+  return router;
+}
+
+function parseTokenFromCookie(cookieHeader: string | undefined): string | null {
+  if (!cookieHeader) return null;
+  const match = cookieHeader.split(";").map((p) => p.trim()).find((p) => p.startsWith(`${SESSION_COOKIE_NAME}=`));
+  if (!match) return null;
+  return decodeURIComponent(match.slice(SESSION_COOKIE_NAME.length + 1));
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npx vitest run src/web/api/session.test.ts
+```
+Expected: all 8 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/web/api/session.ts src/web/api/session.test.ts
+git commit -m "feat(auth): add /api/session router (setup, login, logout, me, change-password)"
+```
+
+---
+
+## Task 9: Wire up `server.ts` (cookieParser, public/protected ordering, cleanup)
+
+**Files:**
+- Modify: `src/web/server.ts`
+
+> The protected `/api/*` routers and the new public ones share the same path prefix. Express middleware ordering matters: register public routes BEFORE the `app.use("/api", csrfOriginCheck)` + `app.use("/api", requireAuth)` gates.
+
+- [ ] **Step 1: Replace the contents of `src/web/server.ts`**
+
+```ts
+import express from "express";
+import http from "node:http";
+import path from "node:path";
+import cookieParser from "cookie-parser";
+import { WebSocketServer } from "ws";
+import type { BotManager } from "../bot/manager.js";
+import type { MusicProvider } from "../music/provider.js";
+import type { BotDatabase } from "../data/database.js";
+import type { BotConfig } from "../data/config.js";
+import type { Logger } from "../logger.js";
+import type { CookieStore } from "../music/auth.js";
+import type { AvatarStore } from "../data/avatars.js";
+import { createBotRouter } from "./api/bot.js";
+import { createMusicRouter } from "./api/music.js";
+import { createPlayerRouter } from "./api/player.js";
+import { createAuthRouter } from "./api/auth.js";
+import { createSessionRouter } from "./api/session.js";
+import { setupWebSocket } from "./websocket.js";
+import { createUserStore } from "../data/users.js";
+import { createSessionStore } from "../data/sessions.js";
+import { createRequireAuth } from "./middleware/requireAuth.js";
+import { csrfOriginCheck } from "./middleware/csrf.js";
+import { validateSessionFromHeaders } from "./auth/validateSession.js";
+
+const SESSION_CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+
+export interface WebServerOptions {
+  port: number;
+  botManager: BotManager;
+  neteaseProvider: MusicProvider;
+  qqProvider: MusicProvider;
+  bilibiliProvider: MusicProvider;
+  database: BotDatabase;
+  config: BotConfig;
+  configPath: string;
+  logger: Logger;
+  cookieStore?: CookieStore;
+  avatarStore: AvatarStore;
+  staticDir?: string;
+}
+
+export interface WebServer {
+  start(): Promise<void>;
+  stop(): void;
+}
+
+export function createWebServer(options: WebServerOptions): WebServer {
+  const app = express();
+  const server = http.createServer(app);
+  const logger = options.logger.child({ component: "web" });
+
+  if (options.config.trustProxy) {
+    app.set("trust proxy", true);
+  }
+
+  app.use(express.json({ limit: "400kb" }));
+  app.use(cookieParser());
+
+  const users = createUserStore(options.database.db);
+  const sessions = createSessionStore(options.database.db);
+
+  // ─── Public routes (no auth, no CSRF) ───────────────────────────────────
+  app.get("/api/health", (_req, res) => {
+    res.json({ status: "ok", version: "0.1.0" });
+  });
+
+  app.get("/api/config/public-url", (_req, res) => {
+    const raw = (options.config.publicUrl ?? "").trim();
+    res.json({ publicUrl: raw ? raw.replace(/\/+$/, "") : null });
+  });
+
+  app.use("/api/session", createSessionRouter(users, sessions, logger));
+
+  // ─── Gates for everything else under /api ───────────────────────────────
+  const requireAuth = createRequireAuth(sessions);
+  app.use("/api", csrfOriginCheck);
+  app.use("/api", requireAuth);
+
+  // ─── Protected routes ───────────────────────────────────────────────────
+  app.use(
+    "/api/bot",
+    createBotRouter(
+      options.botManager,
+      options.config,
+      options.configPath,
+      logger,
+      options.database,
+      options.avatarStore,
+    )
+  );
+  app.use(
+    "/api/music",
+    createMusicRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger)
+  );
+  app.use("/api/player", createPlayerRouter(
+    options.botManager, logger, options.database,
+    options.neteaseProvider, options.qqProvider, options.bilibiliProvider,
+  ));
+  app.use(
+    "/api/auth",
+    createAuthRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.cookieStore)
+  );
+
+  // ─── Static SPA (public) ────────────────────────────────────────────────
+  if (options.staticDir) {
+    app.use(express.static(options.staticDir));
+    app.get(/^(?!\/api|\/ws)/, (_req, res) => {
+      res.sendFile(path.join(options.staticDir!, "index.html"));
+    });
+  }
+
+  server.on("error", (err) => {
+    logger.error({ err }, "HTTP server error");
+  });
+
+  // ─── WebSocket with manual upgrade auth ────────────────────────────────
+  const wss = new WebSocketServer({ noServer: true });
+  wss.on("error", (err) => {
+    logger.error({ err }, "WebSocket server error");
+  });
+  server.on("upgrade", (req, socket, head) => {
+    if (req.url !== "/ws") {
+      socket.destroy();
+      return;
+    }
+    const result = validateSessionFromHeaders(req.headers.cookie as string | undefined, sessions);
+    if (!result) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      (ws as unknown as { userId: string }).userId = result.userId;
+      wss.emit("connection", ws, req);
+    });
+  });
+  const cleanupWs = setupWebSocket(wss, options.botManager, logger);
+
+  // ─── Session cleanup interval ──────────────────────────────────────────
+  let cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  return {
+    async start(): Promise<void> {
+      return new Promise((resolve) => {
+        server.listen(options.port, () => {
+          logger.info({ port: options.port }, "Web server started");
+          cleanupTimer = setInterval(() => {
+            try {
+              sessions.cleanupExpired();
+            } catch (err) {
+              logger.error({ err }, "session cleanup failed");
+            }
+          }, SESSION_CLEANUP_INTERVAL_MS);
+          resolve();
+        });
+      });
+    },
+    stop(): void {
+      if (cleanupTimer) {
+        clearInterval(cleanupTimer);
+        cleanupTimer = null;
+      }
+      cleanupWs();
+      wss.close();
+      server.close();
+    },
+  };
+}
+```
+
+- [ ] **Step 2: Type-check the project**
+
+```bash
+npx tsc --noEmit
+```
+Expected: zero errors.
+
+- [ ] **Step 3: Run the whole vitest suite**
+
+```bash
+npx vitest run
+```
+Expected: all existing + new tests pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/web/server.ts
+git commit -m "feat(auth): gate /api/* behind requireAuth + csrf; gate /ws via upgrade handler"
+```
+
+---
+
+## Task 10: WebSocket auth integration test
+
+**Files:**
+- Create: `src/web/websocket-auth.test.ts`
+
+> Validates the end-to-end ws gate behavior. Uses a real HTTP server on a random port plus the `ws` client.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/web/websocket-auth.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import http from "node:http";
+import { WebSocketServer, WebSocket as WSClient } from "ws";
+import { AddressInfo } from "node:net";
+import { createDatabase, type BotDatabase } from "../data/database.js";
+import { createUserStore } from "../data/users.js";
+import { createSessionStore } from "../data/sessions.js";
+import { validateSessionFromHeaders, SESSION_COOKIE_NAME } from "./auth/validateSession.js";
+
+function buildServer(sessions: ReturnType<typeof createSessionStore>) {
+  const app = express();
+  const server = http.createServer(app);
+  const wss = new WebSocketServer({ noServer: true });
+  wss.on("connection", (ws) => ws.send("hello"));
+  server.on("upgrade", (req, socket, head) => {
+    if (req.url !== "/ws") return socket.destroy();
+    const r = validateSessionFromHeaders(req.headers.cookie as string | undefined, sessions);
+    if (!r) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req));
+  });
+  return { server, wss };
+}
+
+describe("WebSocket auth at upgrade", () => {
+  let botDb: BotDatabase;
+  let httpServer: http.Server;
+  let port: number;
+  let validToken: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const u = await users.createUser("alice", "pw");
+    validToken = sessions.createSession(u.id).token;
+
+    const { server } = buildServer(sessions);
+    httpServer = server;
+    await new Promise<void>((resolve) => httpServer.listen(0, resolve));
+    port = (httpServer.address() as AddressInfo).port;
+  });
+
+  afterEach(async () => {
+    await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+    botDb.close();
+  });
+
+  it("rejects upgrade without cookie (server-side close before open)", async () => {
+    const ws = new WSClient(`ws://127.0.0.1:${port}/ws`);
+    const result = await new Promise<string>((resolve) => {
+      ws.on("open", () => resolve("opened"));
+      ws.on("unexpected-response", (_req, res) => resolve(`status:${res.statusCode}`));
+      ws.on("error", () => resolve("error"));
+    });
+    expect(result).toMatch(/^status:401$|^error$/);
+  });
+
+  it("accepts upgrade with a valid cookie", async () => {
+    const ws = new WSClient(`ws://127.0.0.1:${port}/ws`, {
+      headers: { Cookie: `${SESSION_COOKIE_NAME}=${validToken}` },
+    });
+    const msg = await new Promise<string>((resolve, reject) => {
+      ws.on("message", (data) => resolve(data.toString()));
+      ws.on("error", reject);
+    });
+    expect(msg).toBe("hello");
+    ws.close();
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it passes**
+
+```bash
+npx vitest run src/web/websocket-auth.test.ts
+```
+Expected: both tests PASS (the implementation already exists in `server.ts`; this test only validates it).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/web/websocket-auth.test.ts
+git commit -m "test(auth): verify ws upgrade gating end-to-end"
+```
+
+---
+
+## Task 11: Frontend — `useSession` composable
+
+**Files:**
+- Create: `web/src/composables/useSession.ts`
+
+> Single source of truth for auth state. Other code reads `currentUser`, `needsSetup`, calls `refresh()`, `login()`, `logout()`, `setup()`.
+
+- [ ] **Step 1: Create `web/src/composables/useSession.ts`**
+
+```ts
+import { ref, computed, readonly } from "vue";
+
+interface User {
+  id: string;
+  username: string;
+}
+
+const currentUser = ref<User | null>(null);
+const needsSetup = ref<boolean | null>(null); // null = unknown / not fetched yet
+const ready = ref(false);
+
+async function refreshNeedsSetup(): Promise<void> {
+  const res = await fetch("/api/session/needs-setup", { credentials: "same-origin" });
+  if (res.ok) {
+    const body = await res.json();
+    needsSetup.value = Boolean(body.needsSetup);
+  }
+}
+
+async function refreshMe(): Promise<void> {
+  const res = await fetch("/api/session/me", { credentials: "same-origin" });
+  if (res.status === 200) {
+    currentUser.value = (await res.json()) as User;
+  } else {
+    currentUser.value = null;
+  }
+}
+
+async function refresh(): Promise<void> {
+  await refreshNeedsSetup();
+  if (needsSetup.value) {
+    currentUser.value = null;
+  } else {
+    await refreshMe();
+  }
+  ready.value = true;
+}
+
+async function login(username: string, password: string): Promise<void> {
+  const res = await fetch("/api/session/login", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ username, password }),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error ?? `login failed (${res.status})`);
+  }
+  currentUser.value = (await res.json()) as User;
+}
+
+async function setup(username: string, password: string): Promise<void> {
+  const res = await fetch("/api/session/setup", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ username, password }),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error ?? `setup failed (${res.status})`);
+  }
+  currentUser.value = (await res.json()) as User;
+  needsSetup.value = false;
+}
+
+async function logout(): Promise<void> {
+  await fetch("/api/session/logout", { method: "POST", credentials: "same-origin" });
+  currentUser.value = null;
+}
+
+export function useSession() {
+  return {
+    currentUser: readonly(currentUser),
+    needsSetup: readonly(needsSetup),
+    isAuthenticated: computed(() => currentUser.value !== null),
+    ready: readonly(ready),
+    refresh,
+    login,
+    logout,
+    setup,
+  };
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add web/src/composables/useSession.ts
+git commit -m "feat(web): add useSession composable"
+```
+
+---
+
+## Task 12: Frontend — `Login.vue`
+
+**Files:**
+- Create: `web/src/views/Login.vue`
+
+- [ ] **Step 1: Create `web/src/views/Login.vue`**
+
+```vue
+<template>
+  <div class="auth-page">
+    <form class="auth-card" @submit.prevent="submit">
+      <h1>登录 TSMusicBot</h1>
+      <label>
+        <span>用户名</span>
+        <input v-model="username" type="text" autocomplete="username" autofocus required />
+      </label>
+      <label>
+        <span>密码</span>
+        <input v-model="password" type="password" autocomplete="current-password" required />
+      </label>
+      <p v-if="error" class="auth-error">{{ error }}</p>
+      <button type="submit" :disabled="loading">{{ loading ? '登录中…' : '登录' }}</button>
+    </form>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { useSession } from '../composables/useSession.js';
+
+const username = ref('');
+const password = ref('');
+const error = ref('');
+const loading = ref(false);
+const router = useRouter();
+const route = useRoute();
+const session = useSession();
+
+async function submit() {
+  error.value = '';
+  loading.value = true;
+  try {
+    await session.login(username.value, password.value);
+    const next = typeof route.query.next === 'string' ? route.query.next : '/';
+    router.replace(next);
+  } catch (e) {
+    error.value = (e as Error).message;
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+
+<style scoped lang="scss">
+.auth-page {
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--bg-primary);
+}
+.auth-card {
+  width: 360px;
+  padding: 32px;
+  background: var(--bg-secondary);
+  border-radius: var(--radius-md);
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  box-shadow: var(--shadow-dropdown);
+}
+.auth-card h1 { margin: 0 0 8px; font-size: 20px; color: var(--text-primary); }
+.auth-card label { display: flex; flex-direction: column; gap: 6px; font-size: 12px; color: var(--text-secondary); }
+.auth-card input {
+  height: 36px; padding: 0 10px; border-radius: var(--radius-sm);
+  background: var(--bg-primary); color: var(--text-primary); border: 1px solid var(--border-color);
+}
+.auth-card button {
+  height: 38px; border-radius: var(--radius-sm); border: 0;
+  background: var(--color-primary); color: #fff; font-weight: 500; cursor: pointer;
+}
+.auth-card button:disabled { opacity: 0.6; cursor: progress; }
+.auth-error { color: #e26a6a; font-size: 13px; margin: 0; }
+</style>
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add web/src/views/Login.vue
+git commit -m "feat(web): add Login view"
+```
+
+---
+
+## Task 13: Frontend — `FirstRunSetup.vue` + router wiring + guard
+
+**Files:**
+- Create: `web/src/views/FirstRunSetup.vue`
+- Modify: `web/src/router/index.ts`
+
+- [ ] **Step 1: Create `web/src/views/FirstRunSetup.vue`**
+
+```vue
+<template>
+  <div class="auth-page">
+    <form class="auth-card" @submit.prevent="submit">
+      <h1>首次使用</h1>
+      <p class="auth-hint">创建管理员账号。该账号将拥有 WebUI 的全部权限。</p>
+      <label>
+        <span>用户名</span>
+        <input v-model="username" type="text" autocomplete="username" autofocus required />
+      </label>
+      <label>
+        <span>密码 (≥8 位)</span>
+        <input v-model="password" type="password" autocomplete="new-password" minlength="8" required />
+      </label>
+      <label>
+        <span>再次输入密码</span>
+        <input v-model="confirm" type="password" autocomplete="new-password" minlength="8" required />
+      </label>
+      <p v-if="error" class="auth-error">{{ error }}</p>
+      <button type="submit" :disabled="loading">{{ loading ? '创建中…' : '创建管理员' }}</button>
+    </form>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useRouter } from 'vue-router';
+import { useSession } from '../composables/useSession.js';
+
+const username = ref('');
+const password = ref('');
+const confirm = ref('');
+const error = ref('');
+const loading = ref(false);
+const router = useRouter();
+const session = useSession();
+
+async function submit() {
+  error.value = '';
+  if (password.value !== confirm.value) {
+    error.value = '两次输入的密码不一致';
+    return;
+  }
+  loading.value = true;
+  try {
+    await session.setup(username.value, password.value);
+    router.replace('/');
+  } catch (e) {
+    error.value = (e as Error).message;
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+
+<style scoped lang="scss">
+.auth-page { min-height: 100vh; display: flex; align-items: center; justify-content: center; background: var(--bg-primary); }
+.auth-card {
+  width: 360px; padding: 32px; background: var(--bg-secondary);
+  border-radius: var(--radius-md); display: flex; flex-direction: column; gap: 12px;
+  box-shadow: var(--shadow-dropdown);
+}
+.auth-card h1 { margin: 0; font-size: 20px; color: var(--text-primary); }
+.auth-hint { margin: 0 0 4px; font-size: 12px; color: var(--text-secondary); }
+.auth-card label { display: flex; flex-direction: column; gap: 6px; font-size: 12px; color: var(--text-secondary); }
+.auth-card input {
+  height: 36px; padding: 0 10px; border-radius: var(--radius-sm);
+  background: var(--bg-primary); color: var(--text-primary); border: 1px solid var(--border-color);
+}
+.auth-card button {
+  height: 38px; border-radius: var(--radius-sm); border: 0;
+  background: var(--color-primary); color: #fff; font-weight: 500; cursor: pointer;
+}
+.auth-card button:disabled { opacity: 0.6; cursor: progress; }
+.auth-error { color: #e26a6a; font-size: 13px; margin: 0; }
+</style>
+```
+
+- [ ] **Step 2: Replace `web/src/router/index.ts`**
+
+```ts
+import { createRouter, createWebHistory } from 'vue-router';
+import { useSession } from '../composables/useSession.js';
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: '/', name: 'home', component: () => import('../views/Home.vue') },
+    { path: '/search', name: 'search', component: () => import('../views/Search.vue') },
+    { path: '/library', name: 'library', component: () => import('../views/Library.vue') },
+    {
+      path: '/playlist/:id',
+      name: 'playlist',
+      component: () => import('../views/Playlist.vue'),
+      meta: { kind: 'playlist' },
+    },
+    {
+      path: '/album/:id',
+      name: 'album',
+      component: () => import('../views/Playlist.vue'),
+      meta: { kind: 'album' },
+    },
+    { path: '/lyrics', name: 'lyrics', component: () => import('../views/Lyrics.vue') },
+    { path: '/history', name: 'history', component: () => import('../views/History.vue') },
+    { path: '/settings', name: 'settings', component: () => import('../views/Settings.vue') },
+    { path: '/setup', name: 'setup', component: () => import('../views/Setup.vue') },
+    { path: '/bot/:id', name: 'bot', component: () => import('../views/BotRedirect.vue') },
+
+    // Auth views
+    { path: '/login', name: 'login', component: () => import('../views/Login.vue'), meta: { public: true } },
+    { path: '/first-run', name: 'first-run', component: () => import('../views/FirstRunSetup.vue'), meta: { public: true } },
+  ],
+});
+
+const PUBLIC_NAMES = new Set(['login', 'first-run']);
+
+router.beforeEach(async (to) => {
+  const session = useSession();
+  if (!session.ready.value) {
+    await session.refresh();
+  }
+
+  if (session.needsSetup.value && to.name !== 'first-run') {
+    return { name: 'first-run' };
+  }
+  if (!session.needsSetup.value && to.name === 'first-run') {
+    return { name: 'home' };
+  }
+
+  if (PUBLIC_NAMES.has(to.name as string)) {
+    if (to.name === 'login' && session.isAuthenticated.value) {
+      return { name: 'home' };
+    }
+    return true;
+  }
+
+  if (!session.isAuthenticated.value) {
+    return { name: 'login', query: { next: to.fullPath } };
+  }
+  return true;
+});
+
+export default router;
+```
+
+- [ ] **Step 3: Type-check the web project**
+
+```bash
+cd web && npx vue-tsc --noEmit && cd ..
+```
+Expected: zero errors. (If `vue-tsc` is not configured, use `npx tsc --noEmit` inside `web/`.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add web/src/views/FirstRunSetup.vue web/src/router/index.ts
+git commit -m "feat(web): add /first-run + /login routes with auth guard"
+```
+
+---
+
+## Task 14: Frontend — API client credentials + global 401 handler
+
+**Files:**
+- Create: `web/src/api/http.ts`
+- Modify: `web/src/App.vue` (call `installApiClient` once on mount)
+- Audit: every `fetch(...)` call site in `web/src/` to add `credentials: 'same-origin'`. There are likely ~10-20.
+
+> Two-pronged fix: (1) one global `fetch` wrapper that intercepts 401 and redirects to login; (2) per-call `credentials: 'same-origin'` so cookies are sent. The wrapper sets credentials by default so most call sites only need to switch from `fetch` to `apiFetch`.
+
+- [ ] **Step 1: Create `web/src/api/http.ts`**
+
+```ts
+import router from '../router/index.js';
+import { useSession } from '../composables/useSession.js';
+
+let installed = false;
+
+/**
+ * Wraps fetch so every call:
+ *   - sends cookies (`credentials: 'same-origin'`)
+ *   - on 401 from /api/*: clear local session, redirect to /login
+ */
+export function apiFetch(input: RequestInfo | URL, init: RequestInit = {}): Promise<Response> {
+  const merged: RequestInit = {
+    credentials: 'same-origin',
+    ...init,
+    headers: { ...(init.headers ?? {}) },
+  };
+  return fetch(input, merged).then(async (res) => {
+    if (res.status === 401 && isApiPath(input)) {
+      const session = useSession();
+      await session.refresh();
+      const current = router.currentRoute.value;
+      if (current.name !== 'login' && current.name !== 'first-run') {
+        await router.replace({ name: 'login', query: { next: current.fullPath } });
+      }
+    }
+    return res;
+  });
+}
+
+function isApiPath(input: RequestInfo | URL): boolean {
+  const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+  return url.startsWith('/api/');
+}
+
+/**
+ * Replaces window.fetch with apiFetch so existing call sites do not need to be touched.
+ * Call once at app startup.
+ */
+export function installApiClient(): void {
+  if (installed) return;
+  installed = true;
+  const original = window.fetch.bind(window);
+  window.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+    return apiFetch(input, init ?? {});
+  }) as typeof window.fetch;
+  // Keep original accessible if anything needs to bypass
+  (window as unknown as { __originalFetch?: typeof fetch }).__originalFetch = original;
+}
+```
+
+- [ ] **Step 2: Wire into `web/src/main.ts`**
+
+Replace `web/src/main.ts` with:
+
+```ts
+import { createApp } from 'vue';
+import { createPinia } from 'pinia';
+import App from './App.vue';
+import router from './router/index.js';
+import { installApiClient } from './api/http.js';
+import './styles/global.scss';
+import './styles/mobile.scss';
+
+installApiClient();
+
+const app = createApp(App);
+app.use(createPinia());
+app.use(router);
+app.mount('#app');
+```
+
+- [ ] **Step 3: Type-check**
+
+```bash
+cd web && npx vue-tsc --noEmit && cd ..
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add web/src/api/http.ts web/src/main.ts
+git commit -m "feat(web): install global fetch wrapper with credentials + 401 handling"
+```
+
+---
+
+## Task 15: Frontend — logout + username chip in Navbar
+
+**Files:**
+- Modify: `web/src/components/Navbar.vue`
+
+- [ ] **Step 1: Inspect current Navbar.vue**
+
+```bash
+git show HEAD:web/src/components/Navbar.vue | head -80
+```
+Locate the right-hand side of the desktop nav (where Settings/menu actions live).
+
+- [ ] **Step 2: Add a user chip + logout button**
+
+Append (inside the existing template, right-most slot of the desktop nav — placement adjusted to match Navbar's existing structure):
+
+```vue
+<div class="nav-user" v-if="session.currentUser.value">
+  <span class="nav-user-name">{{ session.currentUser.value.username }}</span>
+  <button class="nav-user-logout" @click="onLogout" title="退出">
+    <Icon icon="mdi:logout" />
+  </button>
+</div>
+```
+
+In the existing `<script setup>` of Navbar.vue, add:
+
+```ts
+import { useRouter } from 'vue-router';
+import { useSession } from '../composables/useSession.js';
+
+const session = useSession();
+const navRouter = useRouter();
+
+async function onLogout() {
+  await session.logout();
+  navRouter.replace({ name: 'login' });
+}
+```
+
+Add minimal styles:
+
+```scss
+.nav-user {
+  display: flex; align-items: center; gap: 8px; margin-left: 12px;
+  color: var(--text-secondary); font-size: 13px;
+}
+.nav-user-logout {
+  height: 28px; width: 28px; display: grid; place-items: center;
+  border: 0; background: transparent; color: var(--text-secondary); cursor: pointer;
+  border-radius: var(--radius-sm);
+  &:hover { background: var(--bg-secondary); color: var(--text-primary); }
+}
+```
+
+- [ ] **Step 3: Sanity-build the web project**
+
+```bash
+cd web && npm run build && cd ..
+```
+Expected: build succeeds and produces `web/dist/`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add web/src/components/Navbar.vue
+git commit -m "feat(web): show current user + logout button in nav"
+```
+
+---
+
+## Task 16: Smoke test (manual) + final commit
+
+**Files:**
+- None (manual verification)
+
+> This task does NOT modify code. It is the verification gate before opening a PR. If any step fails, return to the relevant task and fix it.
+
+- [ ] **Step 1: Wipe local DB (so the bot enters first-run state)**
+
+```bash
+# Important: only do this in a dev environment, not against any prod data.
+mv data/tsmusicbot.db data/tsmusicbot.db.bak 2>/dev/null || true
+```
+
+- [ ] **Step 2: Start the bot in dev**
+
+```bash
+npm run dev
+```
+Expected: logs show `Web server started` on the configured port (default `3000`).
+
+- [ ] **Step 3: First-run wizard**
+
+- Open `http://localhost:3000/` → expect automatic redirect to `/first-run`.
+- Submit `admin / hunter2-hunter2` (or any ≥8-char password).
+- Expect redirect to `/` and the user chip showing `admin` in the nav.
+
+- [ ] **Step 4: API is gated**
+
+In a separate terminal:
+
+```bash
+curl -i http://localhost:3000/api/bot
+```
+Expected: `HTTP/1.1 401 Unauthorized` with body `{"error":"unauthenticated"}`.
+
+```bash
+curl -i http://localhost:3000/api/health
+```
+Expected: `200 OK` (public).
+
+- [ ] **Step 5: WebSocket is gated**
+
+```bash
+node -e "const WebSocket=require('ws');const ws=new WebSocket('ws://localhost:3000/ws');ws.on('open',()=>console.log('OPENED'));ws.on('unexpected-response',(_,r)=>console.log('STATUS',r.statusCode));ws.on('error',e=>console.log('ERR',e.message));"
+```
+Expected: prints `STATUS 401` (not `OPENED`).
+
+- [ ] **Step 6: Logout → redirect**
+
+In the browser click logout → expect redirect to `/login`. Try to navigate to `/library` → expect bounce back to `/login?next=/library`.
+
+- [ ] **Step 7: Login → restored**
+
+Log in again with `admin` → expect redirect to `/library` (the `next` query param).
+
+- [ ] **Step 8: Restore previous DB (optional)**
+
+```bash
+# Only if you backed it up in Step 1
+mv data/tsmusicbot.db.bak data/tsmusicbot.db 2>/dev/null || true
+```
+
+- [ ] **Step 9: Final commit (changelog/README)**
+
+Update README's setup section briefly mentioning that the WebUI now requires a first-run admin. Then:
+
+```bash
+# only if you actually edited README.md
+git add README.md
+git commit -m "docs: note WebUI first-run admin setup"
+```
+
+- [ ] **Step 10: Push the branch**
+
+```bash
+git push -u origin feat/webui-auth
+```
+
+- [ ] **Step 11: Open PR (manual)**
+
+The user will open the PR via `gh pr create` or the GitHub UI. Plan complete.
+
+---
+
+## Self-review against spec
+
+- Spec § Storage → Task 2, 3, 4 ✅
+- Spec § validateSession.ts shared helper → Task 5 ✅
+- Spec § requireAuth middleware → Task 6 ✅
+- Spec § CSRF Origin/Referer middleware → Task 7 ✅
+- Spec § /api/session router (needs-setup, setup, login, logout, me, change-password) → Task 8 ✅
+- Spec § server.ts wiring, cookieParser, public/protected order, cleanup interval → Task 9 ✅
+- Spec § WebSocket auth at upgrade → Task 9 (impl) + Task 10 (integration test) ✅
+- Spec § frontend useSession composable → Task 11 ✅
+- Spec § Login.vue → Task 12 ✅
+- Spec § FirstRunSetup.vue + router guard → Task 13 ✅ (note: route path `/first-run`, supersedes spec's `/setup`)
+- Spec § API client credentials + 401 interceptor → Task 14 ✅
+- Spec § App.vue / Navbar logout + username chip → Task 15 ✅
+- Spec § Manual test checklist → Task 16 ✅

From df79976933103ed0ff3694fcfb54fac82b7b0325 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:25:32 +0800
Subject: [PATCH 03/35] deps: add bcryptjs + cookie-parser + supertest for
 WebUI auth

---
 package-lock.json | 218 ++++++++++++++++++++++++++++++++++++++++++++++
 package.json      |   6 ++
 2 files changed, 224 insertions(+)

diff --git a/package-lock.json b/package-lock.json
index 2dbf969..16fa375 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -14,8 +14,10 @@
         "@koa/router": "^15.4.0",
         "@sansenjian/qq-music-api": "^2.2.10",
         "axios": "^1.14.0",
+        "bcryptjs": "^2.4.3",
         "better-sqlite3": "^12.8.0",
         "chalk": "^5.6.2",
+        "cookie-parser": "^1.4.7",
         "express": "^5.2.1",
         "ffmpeg-static": "^5.3.0",
         "koa": "^3.2.0",
@@ -29,10 +31,14 @@
         "yt-dlp-wrap": "^2.3.12"
       },
       "devDependencies": {
+        "@types/bcryptjs": "^2.4.6",
         "@types/better-sqlite3": "^7.6.13",
+        "@types/cookie-parser": "^1.4.10",
         "@types/express": "^5.0.6",
         "@types/node": "^25.5.0",
+        "@types/supertest": "^6.0.3",
         "@types/ws": "^8.18.1",
+        "supertest": "^7.2.2",
         "tsx": "^4.21.0",
         "typescript": "^6.0.2",
         "vitest": "^4.1.2"
@@ -667,6 +673,29 @@
         "url": "https://github.com/sponsors/Boshen"
       }
     },
+    "node_modules/@paralleldrive/cuid2": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/@paralleldrive/cuid2/-/cuid2-2.3.1.tgz",
+      "integrity": "sha512-XO7cAxhnTZl0Yggq6jOgjiOHhbgcO4NqFqwSmQpjK3b6TEE6Uj/jfSk6wzYyemh3+I0sHirKSetjQwn5cZktFw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@noble/hashes": "^1.1.5"
+      }
+    },
+    "node_modules/@paralleldrive/cuid2/node_modules/@noble/hashes": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz",
+      "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^14.21.3 || >=16"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
     "node_modules/@pinojs/redact": {
       "version": "0.4.0",
       "resolved": "https://registry.npmjs.org/@pinojs/redact/-/redact-0.4.0.tgz",
@@ -1152,6 +1181,13 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@types/bcryptjs": {
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@types/bcryptjs/-/bcryptjs-2.4.6.tgz",
+      "integrity": "sha512-9xlo6R2qDs5uixm0bcIqCeMCE6HiQsIyel9KQySStiyqNl2tnj2mP3DX1Nf56MD6KMenNNlBBsy3LJ7gUEQPXQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/better-sqlite3": {
       "version": "7.6.13",
       "resolved": "https://registry.npmjs.org/@types/better-sqlite3/-/better-sqlite3-7.6.13.tgz",
@@ -1194,6 +1230,23 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/cookie-parser": {
+      "version": "1.4.10",
+      "resolved": "https://registry.npmjs.org/@types/cookie-parser/-/cookie-parser-1.4.10.tgz",
+      "integrity": "sha512-B4xqkqfZ8Wek+rCOeRxsjMS9OgvzebEzzLYw7NHYuvzb7IdxOkI0ZHGgeEBX4PUM7QGVvNSK60T3OvWj3YfBRg==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/express": "*"
+      }
+    },
+    "node_modules/@types/cookiejar": {
+      "version": "2.1.5",
+      "resolved": "https://registry.npmjs.org/@types/cookiejar/-/cookiejar-2.1.5.tgz",
+      "integrity": "sha512-he+DHOWReW0nghN24E1WUqM0efK4kI9oTqDm6XmK8ZPe2djZ90BSNdGnIyCLzCPw7/pogPlGbzI2wHGGmi4O/Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/deep-eql": {
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
@@ -1240,6 +1293,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/methods": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/@types/methods/-/methods-1.1.4.tgz",
+      "integrity": "sha512-ymXWVrDiCxTBE3+RIrrP533E70eA+9qu7zdWoHuOmGujkYtzf4HQF96b8nwHLqhuf4ykX61IGRIB38CC6/sImQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/node": {
       "version": "25.6.0",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.0.tgz",
@@ -1285,6 +1345,30 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/superagent": {
+      "version": "8.1.10",
+      "resolved": "https://registry.npmjs.org/@types/superagent/-/superagent-8.1.10.tgz",
+      "integrity": "sha512-nbt4IWXABhW0jGmmpRzCFNlbmwCTzZ2gTUsNIr+X+ItdqPms+PAJZbWsNzpS2USqXjcoNLQcO6nXo60zcPQiIg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/cookiejar": "^2.1.5",
+        "@types/methods": "^1.1.4",
+        "@types/node": "*",
+        "form-data": "^4.0.0"
+      }
+    },
+    "node_modules/@types/supertest": {
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/@types/supertest/-/supertest-6.0.3.tgz",
+      "integrity": "sha512-8WzXq62EXFhJ7QsH3Ocb/iKQ/Ty9ZVWnVzoTKc9tyyFRRF3a74Tk2+TLFgaFFw364Ere+npzHKEJ6ga2LzIL7w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/methods": "^1.1.4",
+        "@types/superagent": "^8.1.0"
+      }
+    },
     "node_modules/@types/ws": {
       "version": "8.18.1",
       "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
@@ -1501,6 +1585,13 @@
       "integrity": "sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==",
       "license": "MIT"
     },
+    "node_modules/asap": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz",
+      "integrity": "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/asn1": {
       "version": "0.2.6",
       "resolved": "https://registry.npmjs.org/asn1/-/asn1-0.2.6.tgz",
@@ -1608,6 +1699,12 @@
       "integrity": "sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==",
       "license": "Unlicense"
     },
+    "node_modules/bcryptjs": {
+      "version": "2.4.3",
+      "resolved": "https://registry.npmjs.org/bcryptjs/-/bcryptjs-2.4.3.tgz",
+      "integrity": "sha512-V/Hy/X9Vt7f3BbPJEi8BdVFMByHi+jNXrYkW3huaybV/kQ0KJg0Y6PkEMbn+zeT+i+SiKZ/HMqJGIIt4LZDqNQ==",
+      "license": "MIT"
+    },
     "node_modules/better-sqlite3": {
       "version": "12.8.0",
       "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-12.8.0.tgz",
@@ -2011,6 +2108,16 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/component-emitter": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/component-emitter/-/component-emitter-1.3.1.tgz",
+      "integrity": "sha512-T0+barUSQRTUQASh8bx02dl+DhF54GtIDY13Y3m9oWTklKbb3Wv974meRpeZ3lp1JpLVECWWNHC4vaG2XHXouQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/concat-map": {
       "version": "0.0.1",
       "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
@@ -2076,6 +2183,25 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/cookie-parser": {
+      "version": "1.4.7",
+      "resolved": "https://registry.npmjs.org/cookie-parser/-/cookie-parser-1.4.7.tgz",
+      "integrity": "sha512-nGUvgXnotP3BsjiLX2ypbQnWoGUPIIfHQNZkkC668ntrzGWEZVW70HDEB1qnNGMicPje6EttlIgzo51YSwNQGw==",
+      "license": "MIT",
+      "dependencies": {
+        "cookie": "0.7.2",
+        "cookie-signature": "1.0.6"
+      },
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/cookie-parser/node_modules/cookie-signature": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.0.6.tgz",
+      "integrity": "sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ==",
+      "license": "MIT"
+    },
     "node_modules/cookie-signature": {
       "version": "1.2.2",
       "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz",
@@ -2085,6 +2211,13 @@
         "node": ">=6.6.0"
       }
     },
+    "node_modules/cookiejar": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/cookiejar/-/cookiejar-2.1.4.tgz",
+      "integrity": "sha512-LDx6oHrK+PhzLKJU9j5S7/Y3jM/mUHvD/DeI1WQmJn652iPC5Y4TBzC9l+5OMOXlyTTA+SmVUPm0HQUwpD5Jqw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/cookies": {
       "version": "0.9.1",
       "resolved": "https://registry.npmjs.org/cookies/-/cookies-0.9.1.tgz",
@@ -2265,6 +2398,17 @@
         "node": ">=8"
       }
     },
+    "node_modules/dezalgo": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/dezalgo/-/dezalgo-1.0.4.tgz",
+      "integrity": "sha512-rXSP0bf+5n0Qonsb+SVVfNfIsimO4HEtmnIpPHY8Q1UCzKlQrDMfdobr8nJOOsRgWCyMRqeSBQzmWUMq7zvVig==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "asap": "^2.0.0",
+        "wrappy": "1"
+      }
+    },
     "node_modules/dijkstrajs": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/dijkstrajs/-/dijkstrajs-1.0.3.tgz",
@@ -2596,6 +2740,13 @@
         "node": ">=12.0.0"
       }
     },
+    "node_modules/fast-safe-stringify": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz",
+      "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/fdir": {
       "version": "6.5.0",
       "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -2744,6 +2895,24 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/formidable": {
+      "version": "3.5.4",
+      "resolved": "https://registry.npmjs.org/formidable/-/formidable-3.5.4.tgz",
+      "integrity": "sha512-YikH+7CUTOtP44ZTnUhR7Ic2UASBPOqmaRkRKxRbywPTe5VxF7RRCck4af9wutiZ/QKM5nME9Bie2fFaPz5Gug==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@paralleldrive/cuid2": "^2.2.2",
+        "dezalgo": "^1.0.4",
+        "once": "^1.4.0"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "funding": {
+        "url": "https://ko-fi.com/tunnckoCore/commissions"
+      }
+    },
     "node_modules/forwarded": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -5671,6 +5840,55 @@
         "url": "https://github.com/sponsors/Borewit"
       }
     },
+    "node_modules/superagent": {
+      "version": "10.3.0",
+      "resolved": "https://registry.npmjs.org/superagent/-/superagent-10.3.0.tgz",
+      "integrity": "sha512-B+4Ik7ROgVKrQsXTV0Jwp2u+PXYLSlqtDAhYnkkD+zn3yg8s/zjA2MeGayPoY/KICrbitwneDHrjSotxKL+0XQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "component-emitter": "^1.3.1",
+        "cookiejar": "^2.1.4",
+        "debug": "^4.3.7",
+        "fast-safe-stringify": "^2.1.1",
+        "form-data": "^4.0.5",
+        "formidable": "^3.5.4",
+        "methods": "^1.1.2",
+        "mime": "2.6.0",
+        "qs": "^6.14.1"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
+    "node_modules/superagent/node_modules/mime": {
+      "version": "2.6.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-2.6.0.tgz",
+      "integrity": "sha512-USPkMeET31rOMiarsBNIHZKLGgvKc/LrjofAnBlOttf5ajRvqiRA8QsenbcooctK6d6Ts6aqZXBA+XbkKthiQg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "mime": "cli.js"
+      },
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/supertest": {
+      "version": "7.2.2",
+      "resolved": "https://registry.npmjs.org/supertest/-/supertest-7.2.2.tgz",
+      "integrity": "sha512-oK8WG9diS3DlhdUkcFn4tkNIiIbBx9lI2ClF8K+b2/m8Eyv47LSawxUzZQSNKUrVb2KsqeTDCcjAAVPYaSLVTA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cookie-signature": "^1.2.2",
+        "methods": "^1.1.2",
+        "superagent": "^10.3.0"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
     "node_modules/tar": {
       "version": "6.2.1",
       "resolved": "https://registry.npmjs.org/tar/-/tar-6.2.1.tgz",
diff --git a/package.json b/package.json
index e13e740..86c922d 100644
--- a/package.json
+++ b/package.json
@@ -19,8 +19,10 @@
     "@koa/router": "^15.4.0",
     "@sansenjian/qq-music-api": "^2.2.10",
     "axios": "^1.14.0",
+    "bcryptjs": "^2.4.3",
     "better-sqlite3": "^12.8.0",
     "chalk": "^5.6.2",
+    "cookie-parser": "^1.4.7",
     "express": "^5.2.1",
     "ffmpeg-static": "^5.3.0",
     "koa": "^3.2.0",
@@ -34,10 +36,14 @@
     "yt-dlp-wrap": "^2.3.12"
   },
   "devDependencies": {
+    "@types/bcryptjs": "^2.4.6",
     "@types/better-sqlite3": "^7.6.13",
+    "@types/cookie-parser": "^1.4.10",
     "@types/express": "^5.0.6",
     "@types/node": "^25.5.0",
+    "@types/supertest": "^6.0.3",
     "@types/ws": "^8.18.1",
+    "supertest": "^7.2.2",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2"

From 8ea1a64c5945f4a535db7830d794b2fadd4a723f Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:27:12 +0800
Subject: [PATCH 04/35] feat(db): add users and sessions tables for WebUI auth

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/data/database.test.ts | 17 +++++++++++++++++
 src/data/database.ts      | 21 +++++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/src/data/database.test.ts b/src/data/database.test.ts
index de49541..ad32b43 100644
--- a/src/data/database.test.ts
+++ b/src/data/database.test.ts
@@ -23,6 +23,23 @@ describe("database", () => {
     expect(names).toContain("bot_instances");
   });
 
+  it("creates users and sessions tables on init", () => {
+    const tables = botDb.db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+      .all() as Array<{ name: string }>;
+    const names = tables.map((t) => t.name);
+    expect(names).toContain("users");
+    expect(names).toContain("sessions");
+
+    const userCols = botDb.db.prepare("PRAGMA table_info(users)").all() as Array<{ name: string }>;
+    const userColNames = userCols.map((c) => c.name).sort();
+    expect(userColNames).toEqual(["createdAt", "id", "passwordHash", "updatedAt", "username"]);
+
+    const sessionCols = botDb.db.prepare("PRAGMA table_info(sessions)").all() as Array<{ name: string }>;
+    const sessionColNames = sessionCols.map((c) => c.name).sort();
+    expect(sessionColNames).toEqual(["createdAt", "expiresAt", "id", "lastSeenAt", "userId"]);
+  });
+
   it("records and retrieves play history", () => {
     botDb.addPlayHistory({
       botId: "bot1",
diff --git a/src/data/database.ts b/src/data/database.ts
index fdcdb8f..7dd79da 100644
--- a/src/data/database.ts
+++ b/src/data/database.ts
@@ -127,12 +127,33 @@ function initTables(db: Database.Database): void {
       serverPassword TEXT NOT NULL DEFAULT '',
       identity TEXT
     );
+
+    CREATE TABLE IF NOT EXISTS users (
+      id TEXT PRIMARY KEY,
+      username TEXT NOT NULL UNIQUE COLLATE NOCASE,
+      passwordHash TEXT NOT NULL,
+      createdAt INTEGER NOT NULL,
+      updatedAt INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      userId TEXT NOT NULL,
+      createdAt INTEGER NOT NULL,
+      expiresAt INTEGER NOT NULL,
+      lastSeenAt INTEGER NOT NULL,
+      FOREIGN KEY (userId) REFERENCES users(id) ON DELETE CASCADE
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_sessions_userId ON sessions(userId);
+    CREATE INDEX IF NOT EXISTS idx_sessions_expiresAt ON sessions(expiresAt);
   `);
 }
 
 export function createDatabase(dbPath: string): BotDatabase {
   const db = new Database(dbPath);
   db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
   initTables(db);
   migrateSchema(db);
 

From 34523cb00f11f40c8677cb9f15d8c2efe214ae76 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:29:39 +0800
Subject: [PATCH 05/35] feat(auth): add UserStore with bcryptjs password
 hashing

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/data/users.test.ts | 56 ++++++++++++++++++++++++++++
 src/data/users.ts      | 84 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 140 insertions(+)
 create mode 100644 src/data/users.test.ts
 create mode 100644 src/data/users.ts

diff --git a/src/data/users.test.ts b/src/data/users.test.ts
new file mode 100644
index 0000000..0bbd30d
--- /dev/null
+++ b/src/data/users.test.ts
@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createDatabase, type BotDatabase } from "./database.js";
+import { createUserStore, UsernameTakenError, type UserStore } from "./users.js";
+
+describe("UserStore", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+
+  beforeEach(() => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+  });
+
+  afterEach(() => {
+    botDb.close();
+  });
+
+  it("countUsers is 0 on a fresh db", () => {
+    expect(users.countUsers()).toBe(0);
+  });
+
+  it("createUser stores the user and bumps countUsers", async () => {
+    const u = await users.createUser("alice", "pw-hunter2");
+    expect(u.id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(u.username).toBe("alice");
+    expect(users.countUsers()).toBe(1);
+  });
+
+  it("findByUsername is case-insensitive and returns null for missing", async () => {
+    await users.createUser("Alice", "pw");
+    expect(users.findByUsername("ALICE")).not.toBeNull();
+    expect(users.findByUsername("alice")).not.toBeNull();
+    expect(users.findByUsername("bob")).toBeNull();
+  });
+
+  it("createUser rejects duplicate usernames (case-insensitive)", async () => {
+    await users.createUser("Alice", "pw");
+    await expect(users.createUser("alice", "pw2")).rejects.toBeInstanceOf(UsernameTakenError);
+  });
+
+  it("verifyPassword accepts correct password and rejects wrong one", async () => {
+    await users.createUser("alice", "correct-horse-battery-staple");
+    const row = users.findByUsername("alice");
+    expect(row).not.toBeNull();
+    expect(await users.verifyPassword("correct-horse-battery-staple", row!.passwordHash)).toBe(true);
+    expect(await users.verifyPassword("wrong", row!.passwordHash)).toBe(false);
+  });
+
+  it("changePassword updates the hash so the old password no longer verifies", async () => {
+    const u = await users.createUser("alice", "old");
+    await users.changePassword(u.id, "new");
+    const row = users.findByUsername("alice");
+    expect(await users.verifyPassword("old", row!.passwordHash)).toBe(false);
+    expect(await users.verifyPassword("new", row!.passwordHash)).toBe(true);
+  });
+});
diff --git a/src/data/users.ts b/src/data/users.ts
new file mode 100644
index 0000000..8499ccf
--- /dev/null
+++ b/src/data/users.ts
@@ -0,0 +1,84 @@
+import { randomUUID } from "node:crypto";
+import type Database from "better-sqlite3";
+import bcrypt from "bcryptjs";
+
+const BCRYPT_ROUNDS = 12;
+
+export interface UserRow {
+  id: string;
+  username: string;
+  passwordHash: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface UserStore {
+  countUsers(): number;
+  createUser(username: string, password: string): Promise<UserRow>;
+  findByUsername(username: string): UserRow | null;
+  findById(id: string): UserRow | null;
+  verifyPassword(plain: string, hash: string): Promise<boolean>;
+  changePassword(userId: string, newPassword: string): Promise<void>;
+}
+
+export class UsernameTakenError extends Error {
+  constructor(username: string) {
+    super(`username taken: ${username}`);
+    this.name = "UsernameTakenError";
+  }
+}
+
+export function createUserStore(db: Database.Database): UserStore {
+  const countStmt = db.prepare("SELECT COUNT(*) AS n FROM users");
+  const insertStmt = db.prepare(
+    "INSERT INTO users (id, username, passwordHash, createdAt, updatedAt) VALUES (?, ?, ?, ?, ?)"
+  );
+  const findByUsernameStmt = db.prepare(
+    "SELECT id, username, passwordHash, createdAt, updatedAt FROM users WHERE username = ? COLLATE NOCASE"
+  );
+  const findByIdStmt = db.prepare(
+    "SELECT id, username, passwordHash, createdAt, updatedAt FROM users WHERE id = ?"
+  );
+  const updatePasswordStmt = db.prepare(
+    "UPDATE users SET passwordHash = ?, updatedAt = ? WHERE id = ?"
+  );
+
+  return {
+    countUsers() {
+      return (countStmt.get() as { n: number }).n;
+    },
+
+    async createUser(username, password) {
+      const hash = await bcrypt.hash(password, BCRYPT_ROUNDS);
+      const id = randomUUID();
+      const now = Date.now();
+      try {
+        insertStmt.run(id, username, hash, now, now);
+      } catch (err) {
+        const msg = (err as Error).message;
+        if (msg.includes("UNIQUE") && msg.includes("users.username")) {
+          throw new UsernameTakenError(username);
+        }
+        throw err;
+      }
+      return { id, username, passwordHash: hash, createdAt: now, updatedAt: now };
+    },
+
+    findByUsername(username) {
+      return (findByUsernameStmt.get(username) as UserRow | undefined) ?? null;
+    },
+
+    findById(id) {
+      return (findByIdStmt.get(id) as UserRow | undefined) ?? null;
+    },
+
+    verifyPassword(plain, hash) {
+      return bcrypt.compare(plain, hash);
+    },
+
+    async changePassword(userId, newPassword) {
+      const hash = await bcrypt.hash(newPassword, BCRYPT_ROUNDS);
+      updatePasswordStmt.run(hash, Date.now(), userId);
+    },
+  };
+}

From 68a2fb2943c7fc147f38d3e988385aea563ee1b6 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:31:31 +0800
Subject: [PATCH 06/35] refactor(users): use SQLITE_CONSTRAINT_UNIQUE error
 code instead of message text

---
 src/data/users.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/data/users.ts b/src/data/users.ts
index 8499ccf..d79ca40 100644
--- a/src/data/users.ts
+++ b/src/data/users.ts
@@ -55,8 +55,7 @@ export function createUserStore(db: Database.Database): UserStore {
       try {
         insertStmt.run(id, username, hash, now, now);
       } catch (err) {
-        const msg = (err as Error).message;
-        if (msg.includes("UNIQUE") && msg.includes("users.username")) {
+        if (err && typeof err === "object" && (err as { code?: string }).code === "SQLITE_CONSTRAINT_UNIQUE") {
           throw new UsernameTakenError(username);
         }
         throw err;

From 5914f41ea198020ca650ecef1e602ae986df4547 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:33:22 +0800
Subject: [PATCH 07/35] feat(auth): add SessionStore with rolling renewal and
 at-rest token hashing

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/data/sessions.test.ts | 103 ++++++++++++++++++++++++++++++++++++++
 src/data/sessions.ts      |  87 ++++++++++++++++++++++++++++++++
 2 files changed, 190 insertions(+)
 create mode 100644 src/data/sessions.test.ts
 create mode 100644 src/data/sessions.ts

diff --git a/src/data/sessions.test.ts b/src/data/sessions.test.ts
new file mode 100644
index 0000000..376690b
--- /dev/null
+++ b/src/data/sessions.test.ts
@@ -0,0 +1,103 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { createHash } from "node:crypto";
+import { createDatabase, type BotDatabase } from "./database.js";
+import { createUserStore, type UserStore } from "./users.js";
+import { createSessionStore, type SessionStore, SESSION_TTL_MS, SESSION_TOUCH_INTERVAL_MS } from "./sessions.js";
+
+function sha256(token: string) {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+describe("SessionStore", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+  let sessions: SessionStore;
+  let userId: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+    sessions = createSessionStore(botDb.db);
+    const u = await users.createUser("alice", "pw");
+    userId = u.id;
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    botDb.close();
+  });
+
+  it("createSession returns a raw token whose sha256 matches the DB row id", () => {
+    const { token } = sessions.createSession(userId);
+    const row = botDb.db.prepare("SELECT id FROM sessions").get() as { id: string };
+    expect(row.id).toBe(sha256(token));
+    expect(row.id).not.toBe(token);
+  });
+
+  it("validateAndTouch returns the user for a fresh token", () => {
+    const { token } = sessions.createSession(userId);
+    const result = sessions.validateAndTouch(token);
+    expect(result).not.toBeNull();
+    expect(result!.userId).toBe(userId);
+    expect(result!.username).toBe("alice");
+  });
+
+  it("validateAndTouch returns null and deletes the row for an expired session", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    const { token } = sessions.createSession(userId);
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z").getTime() + SESSION_TTL_MS + 1000);
+    expect(sessions.validateAndTouch(token)).toBeNull();
+    const remaining = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(remaining).toBe(0);
+  });
+
+  it("validateAndTouch does not write the DB if called again within the touch interval", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    const { token } = sessions.createSession(userId);
+    const before = botDb.db.prepare("SELECT lastSeenAt FROM sessions").get() as { lastSeenAt: number };
+    vi.advanceTimersByTime(SESSION_TOUCH_INTERVAL_MS - 1000);
+    sessions.validateAndTouch(token);
+    const after = botDb.db.prepare("SELECT lastSeenAt FROM sessions").get() as { lastSeenAt: number };
+    expect(after.lastSeenAt).toBe(before.lastSeenAt);
+  });
+
+  it("validateAndTouch writes lastSeenAt and extends expiresAt past the touch interval", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    const { token, expiresAt: initialExpiry } = sessions.createSession(userId);
+    vi.advanceTimersByTime(SESSION_TOUCH_INTERVAL_MS + 1000);
+    sessions.validateAndTouch(token);
+    const row = botDb.db.prepare("SELECT lastSeenAt, expiresAt FROM sessions").get() as { lastSeenAt: number; expiresAt: number };
+    expect(row.lastSeenAt).toBe(Date.now());
+    expect(row.expiresAt).toBeGreaterThan(initialExpiry);
+  });
+
+  it("deleteSession removes the row", () => {
+    const { token } = sessions.createSession(userId);
+    sessions.deleteSession(token);
+    const remaining = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(remaining).toBe(0);
+    expect(sessions.validateAndTouch(token)).toBeNull();
+  });
+
+  it("deleteAllForUser keeps the exceptToken session", () => {
+    const a = sessions.createSession(userId);
+    const b = sessions.createSession(userId);
+    sessions.deleteAllForUser(userId, a.token);
+    expect(sessions.validateAndTouch(a.token)).not.toBeNull();
+    expect(sessions.validateAndTouch(b.token)).toBeNull();
+  });
+
+  it("cleanupExpired removes only expired rows", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    sessions.createSession(userId); // expires later
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z").getTime() + SESSION_TTL_MS + 1000);
+    sessions.createSession(userId); // fresh
+    sessions.cleanupExpired();
+    const remaining = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(remaining).toBe(1);
+  });
+});
diff --git a/src/data/sessions.ts b/src/data/sessions.ts
new file mode 100644
index 0000000..ce29c4f
--- /dev/null
+++ b/src/data/sessions.ts
@@ -0,0 +1,87 @@
+import { createHash, randomBytes } from "node:crypto";
+import type Database from "better-sqlite3";
+
+export const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+export const SESSION_TOUCH_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+
+export interface SessionValidation {
+  userId: string;
+  username: string;
+}
+
+export interface SessionStore {
+  createSession(userId: string): { token: string; expiresAt: number };
+  validateAndTouch(rawToken: string): SessionValidation | null;
+  deleteSession(rawToken: string): void;
+  deleteAllForUser(userId: string, exceptToken?: string): void;
+  cleanupExpired(): void;
+}
+
+function hashToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+export function createSessionStore(db: Database.Database): SessionStore {
+  const insertStmt = db.prepare(
+    "INSERT INTO sessions (id, userId, createdAt, expiresAt, lastSeenAt) VALUES (?, ?, ?, ?, ?)"
+  );
+  const selectStmt = db.prepare(`
+    SELECT s.id, s.userId, s.expiresAt, s.lastSeenAt, u.username
+    FROM sessions s INNER JOIN users u ON u.id = s.userId
+    WHERE s.id = ?
+  `);
+  const deleteByIdStmt = db.prepare("DELETE FROM sessions WHERE id = ?");
+  const touchStmt = db.prepare(
+    "UPDATE sessions SET lastSeenAt = ?, expiresAt = ? WHERE id = ?"
+  );
+  const deleteAllForUserStmt = db.prepare("DELETE FROM sessions WHERE userId = ?");
+  const deleteAllForUserExceptStmt = db.prepare(
+    "DELETE FROM sessions WHERE userId = ? AND id != ?"
+  );
+  const cleanupStmt = db.prepare("DELETE FROM sessions WHERE expiresAt < ?");
+
+  return {
+    createSession(userId) {
+      const token = randomBytes(32).toString("base64url");
+      const id = hashToken(token);
+      const now = Date.now();
+      const expiresAt = now + SESSION_TTL_MS;
+      insertStmt.run(id, userId, now, expiresAt, now);
+      return { token, expiresAt };
+    },
+
+    validateAndTouch(rawToken) {
+      if (!rawToken) return null;
+      const id = hashToken(rawToken);
+      const row = selectStmt.get(id) as
+        | { id: string; userId: string; expiresAt: number; lastSeenAt: number; username: string }
+        | undefined;
+      if (!row) return null;
+      const now = Date.now();
+      if (row.expiresAt < now) {
+        deleteByIdStmt.run(id);
+        return null;
+      }
+      if (now - row.lastSeenAt > SESSION_TOUCH_INTERVAL_MS) {
+        touchStmt.run(now, now + SESSION_TTL_MS, id);
+      }
+      return { userId: row.userId, username: row.username };
+    },
+
+    deleteSession(rawToken) {
+      deleteByIdStmt.run(hashToken(rawToken));
+    },
+
+    deleteAllForUser(userId, exceptToken) {
+      if (exceptToken) {
+        deleteAllForUserExceptStmt.run(userId, hashToken(exceptToken));
+      } else {
+        deleteAllForUserStmt.run(userId);
+      }
+    },
+
+    cleanupExpired() {
+      cleanupStmt.run(Date.now());
+    },
+  };
+}

From df5d12527965fa7dc646c24137e10da5707bb9f9 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:34:47 +0800
Subject: [PATCH 08/35] feat(auth): add shared validateSessionFromHeaders
 helper

---
 src/web/auth/validateSession.ts | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 src/web/auth/validateSession.ts

diff --git a/src/web/auth/validateSession.ts b/src/web/auth/validateSession.ts
new file mode 100644
index 0000000..4a00cb2
--- /dev/null
+++ b/src/web/auth/validateSession.ts
@@ -0,0 +1,33 @@
+import type { SessionStore, SessionValidation } from "../../data/sessions.js";
+
+export const SESSION_COOKIE_NAME = "tsmb_session";
+
+/**
+ * Validate the session cookie carried on an arbitrary HTTP-like header bag.
+ * Used by Express middleware (req.headers.cookie) AND by the raw WebSocket
+ * upgrade handler (req.headers.cookie) — they share this exact behavior.
+ */
+export function validateSessionFromHeaders(
+  rawCookieHeader: string | undefined,
+  sessions: SessionStore
+): SessionValidation | null {
+  if (!rawCookieHeader) return null;
+  const token = parseCookie(rawCookieHeader, SESSION_COOKIE_NAME);
+  if (!token) return null;
+  return sessions.validateAndTouch(token);
+}
+
+function parseCookie(header: string, name: string): string | null {
+  for (const part of header.split(";")) {
+    const trimmed = part.trim();
+    const eq = trimmed.indexOf("=");
+    if (eq < 1) continue;
+    if (trimmed.slice(0, eq) !== name) continue;
+    try {
+      return decodeURIComponent(trimmed.slice(eq + 1));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}

From 17c11f0512076eefa8976b9e70124a27dd44c5d3 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:36:26 +0800
Subject: [PATCH 09/35] feat(auth): add requireAuth middleware

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/web/middleware/requireAuth.test.ts | 56 ++++++++++++++++++++++++++
 src/web/middleware/requireAuth.ts      | 22 ++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 src/web/middleware/requireAuth.test.ts
 create mode 100644 src/web/middleware/requireAuth.ts

diff --git a/src/web/middleware/requireAuth.test.ts b/src/web/middleware/requireAuth.test.ts
new file mode 100644
index 0000000..644ecb3
--- /dev/null
+++ b/src/web/middleware/requireAuth.test.ts
@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore } from "../../data/users.js";
+import { createSessionStore } from "../../data/sessions.js";
+import { createRequireAuth } from "./requireAuth.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+describe("requireAuth middleware", () => {
+  let botDb: BotDatabase;
+  let app: express.Express;
+  let validToken: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const u = await users.createUser("alice", "pw");
+    validToken = sessions.createSession(u.id).token;
+
+    app = express();
+    app.use(cookieParser());
+    app.use(createRequireAuth(sessions));
+    app.get("/protected", (req, res) => {
+      res.json({ ok: true, user: (req as any).user });
+    });
+  });
+
+  afterEach(() => {
+    botDb.close();
+  });
+
+  it("rejects requests without a session cookie", async () => {
+    const res = await request(app).get("/protected");
+    expect(res.status).toBe(401);
+    expect(res.body).toEqual({ error: "unauthenticated" });
+  });
+
+  it("rejects requests with an unknown session cookie", async () => {
+    const res = await request(app)
+      .get("/protected")
+      .set("Cookie", `${SESSION_COOKIE_NAME}=garbage`);
+    expect(res.status).toBe(401);
+  });
+
+  it("allows requests with a valid session cookie and attaches req.user", async () => {
+    const res = await request(app)
+      .get("/protected")
+      .set("Cookie", `${SESSION_COOKIE_NAME}=${validToken}`);
+    expect(res.status).toBe(200);
+    expect(res.body.ok).toBe(true);
+    expect(res.body.user.username).toBe("alice");
+  });
+});
diff --git a/src/web/middleware/requireAuth.ts b/src/web/middleware/requireAuth.ts
new file mode 100644
index 0000000..e674a28
--- /dev/null
+++ b/src/web/middleware/requireAuth.ts
@@ -0,0 +1,22 @@
+import type { Request, Response, NextFunction, RequestHandler } from "express";
+import type { SessionStore } from "../../data/sessions.js";
+import { validateSessionFromHeaders, SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+declare module "express-serve-static-core" {
+  interface Request {
+    user?: { id: string; username: string };
+  }
+}
+
+export function createRequireAuth(sessions: SessionStore): RequestHandler {
+  return function requireAuth(req: Request, res: Response, next: NextFunction) {
+    const result = validateSessionFromHeaders(req.headers.cookie, sessions);
+    if (!result) {
+      res.clearCookie(SESSION_COOKIE_NAME, { path: "/" });
+      res.status(401).json({ error: "unauthenticated" });
+      return;
+    }
+    req.user = { id: result.userId, username: result.username };
+    next();
+  };
+}

From d1c9e14bf08c60a7109f5bb3ef3c09a09f9c617d Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:38:35 +0800
Subject: [PATCH 10/35] feat(auth): add csrfOriginCheck middleware

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/web/middleware/csrf.test.ts | 58 +++++++++++++++++++++++++++++++++
 src/web/middleware/csrf.ts      | 35 ++++++++++++++++++++
 2 files changed, 93 insertions(+)
 create mode 100644 src/web/middleware/csrf.test.ts
 create mode 100644 src/web/middleware/csrf.ts

diff --git a/src/web/middleware/csrf.test.ts b/src/web/middleware/csrf.test.ts
new file mode 100644
index 0000000..d056ebd
--- /dev/null
+++ b/src/web/middleware/csrf.test.ts
@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import express from "express";
+import request from "supertest";
+import { csrfOriginCheck } from "./csrf.js";
+
+describe("csrfOriginCheck middleware", () => {
+  let app: express.Express;
+
+  beforeEach(() => {
+    app = express();
+    app.use(csrfOriginCheck);
+    app.get("/", (_req, res) => res.json({ ok: true }));
+    app.post("/", (_req, res) => res.json({ ok: true }));
+  });
+
+  it("allows safe methods (GET/HEAD/OPTIONS) without Origin", async () => {
+    const res = await request(app).get("/");
+    expect(res.status).toBe(200);
+  });
+
+  it("rejects POST without Origin or Referer", async () => {
+    const res = await request(app).post("/");
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: "bad origin" });
+  });
+
+  it("accepts POST when Origin host matches request host", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Origin", "https://example.com");
+    expect(res.status).toBe(200);
+  });
+
+  it("rejects POST when Origin host does not match request host", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Origin", "https://evil.com");
+    expect(res.status).toBe(403);
+  });
+
+  it("accepts POST when Referer host matches and Origin is absent", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Referer", "https://example.com/some/path");
+    expect(res.status).toBe(200);
+  });
+
+  it("rejects POST when Referer host does not match", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Referer", "https://evil.com/some/path");
+    expect(res.status).toBe(403);
+  });
+});
diff --git a/src/web/middleware/csrf.ts b/src/web/middleware/csrf.ts
new file mode 100644
index 0000000..9907eab
--- /dev/null
+++ b/src/web/middleware/csrf.ts
@@ -0,0 +1,35 @@
+import type { Request, Response, NextFunction } from "express";
+
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/**
+ * Same-origin CSRF protection. For mutating requests, the Origin or Referer
+ * header must indicate a host equal to the request's own host.
+ *
+ * SameSite=Lax on the session cookie blocks classic cross-site form posts;
+ * this header check covers the remaining attack surface.
+ */
+export function csrfOriginCheck(req: Request, res: Response, next: NextFunction): void {
+  if (SAFE_METHODS.has(req.method)) {
+    next();
+    return;
+  }
+  const expectedHost = req.get("host");
+  const originHeader = req.get("origin");
+  const refererHeader = req.get("referer");
+  const headerHost = hostOf(originHeader) ?? hostOf(refererHeader);
+  if (!headerHost || !expectedHost || headerHost !== expectedHost) {
+    res.status(403).json({ error: "bad origin" });
+    return;
+  }
+  next();
+}
+
+function hostOf(url: string | undefined): string | null {
+  if (!url) return null;
+  try {
+    return new URL(url).host;
+  } catch {
+    return null;
+  }
+}

From ee5673a22fe90f233ad1f7f5ee11b1c0d21091f4 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:42:00 +0800
Subject: [PATCH 11/35] feat(auth): add /api/session router (setup, login,
 logout, me, change-password)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/web/api/session.test.ts | 149 +++++++++++++++++++++++++++++++++++
 src/web/api/session.ts      | 150 ++++++++++++++++++++++++++++++++++++
 2 files changed, 299 insertions(+)
 create mode 100644 src/web/api/session.test.ts
 create mode 100644 src/web/api/session.ts

diff --git a/src/web/api/session.test.ts b/src/web/api/session.test.ts
new file mode 100644
index 0000000..6545e73
--- /dev/null
+++ b/src/web/api/session.test.ts
@@ -0,0 +1,149 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import pino from "pino";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore, type UserStore } from "../../data/users.js";
+import { createSessionStore, type SessionStore } from "../../data/sessions.js";
+import { createSessionRouter } from "./session.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+function makeApp(users: UserStore, sessions: SessionStore) {
+  const app = express();
+  app.use(express.json());
+  app.use(cookieParser());
+  app.use("/api/session", createSessionRouter(users, sessions, pino({ level: "silent" })));
+  return app;
+}
+
+function extractCookie(res: request.Response): string {
+  const header = res.headers["set-cookie"];
+  const arr = Array.isArray(header) ? header : header ? [header] : [];
+  const found = arr.find((c) => c.startsWith(`${SESSION_COOKIE_NAME}=`));
+  if (!found) throw new Error("no session cookie set");
+  return found.split(";")[0]; // "tsmb_session=xxxx"
+}
+
+describe("session router", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+  let sessions: SessionStore;
+  let app: express.Express;
+
+  beforeEach(() => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+    sessions = createSessionStore(botDb.db);
+    app = makeApp(users, sessions);
+  });
+
+  afterEach(() => botDb.close());
+
+  it("GET /needs-setup returns true on an empty db", async () => {
+    const res = await request(app).get("/api/session/needs-setup");
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ needsSetup: true });
+  });
+
+  it("POST /setup creates the first admin, logs them in, and returns false from /needs-setup afterwards", async () => {
+    const setupRes = await request(app)
+      .post("/api/session/setup")
+      .send({ username: "alice", password: "hunter2-hunter2" });
+    expect(setupRes.status).toBe(200);
+    expect(setupRes.body.username).toBe("alice");
+    extractCookie(setupRes);
+
+    const needs = await request(app).get("/api/session/needs-setup");
+    expect(needs.body).toEqual({ needsSetup: false });
+  });
+
+  it("POST /setup returns 409 once a user already exists", async () => {
+    await users.createUser("admin", "pw");
+    const res = await request(app)
+      .post("/api/session/setup")
+      .send({ username: "alice", password: "pw" });
+    expect(res.status).toBe(409);
+    expect(res.body).toEqual({ error: "already initialized" });
+  });
+
+  it("POST /login returns 401 with constant-time delay on bad credentials", async () => {
+    await users.createUser("alice", "correct");
+    const start = Date.now();
+    const res = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "wrong" });
+    expect(res.status).toBe(401);
+    expect(res.body).toEqual({ error: "invalid credentials" });
+    expect(Date.now() - start).toBeGreaterThanOrEqual(200);
+  }, 10_000);
+
+  it("POST /login sets a session cookie on success", async () => {
+    await users.createUser("alice", "pw");
+    const res = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "pw" });
+    expect(res.status).toBe(200);
+    expect(res.body.username).toBe("alice");
+    extractCookie(res);
+  });
+
+  it("GET /me returns the current user when cookie is present, 401 otherwise", async () => {
+    await users.createUser("alice", "pw");
+    const loginRes = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "pw" });
+    const cookie = extractCookie(loginRes);
+
+    const me = await request(app).get("/api/session/me").set("Cookie", cookie);
+    expect(me.status).toBe(200);
+    expect(me.body.username).toBe("alice");
+
+    const anon = await request(app).get("/api/session/me");
+    expect(anon.status).toBe(401);
+  });
+
+  it("POST /logout deletes the session and clears the cookie", async () => {
+    await users.createUser("alice", "pw");
+    const loginRes = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "pw" });
+    const cookie = extractCookie(loginRes);
+
+    const logout = await request(app).post("/api/session/logout").set("Cookie", cookie);
+    expect(logout.status).toBe(204);
+
+    const me = await request(app).get("/api/session/me").set("Cookie", cookie);
+    expect(me.status).toBe(401);
+  });
+
+  it("POST /change-password requires old password and invalidates other sessions", async () => {
+    const u = await users.createUser("alice", "old");
+    const cookieA = extractCookie(
+      await request(app).post("/api/session/login").send({ username: "alice", password: "old" })
+    );
+    const cookieB = extractCookie(
+      await request(app).post("/api/session/login").send({ username: "alice", password: "old" })
+    );
+
+    const wrongOld = await request(app)
+      .post("/api/session/change-password")
+      .set("Cookie", cookieA)
+      .send({ oldPassword: "WRONG", newPassword: "new" });
+    expect(wrongOld.status).toBe(401);
+
+    const ok = await request(app)
+      .post("/api/session/change-password")
+      .set("Cookie", cookieA)
+      .send({ oldPassword: "old", newPassword: "newpassword" });
+    expect(ok.status).toBe(204);
+
+    const meA = await request(app).get("/api/session/me").set("Cookie", cookieA);
+    expect(meA.status).toBe(200);
+
+    const meB = await request(app).get("/api/session/me").set("Cookie", cookieB);
+    expect(meB.status).toBe(401);
+
+    expect(u.id).toBe(meA.body.id);
+  });
+});
diff --git a/src/web/api/session.ts b/src/web/api/session.ts
new file mode 100644
index 0000000..9f302ce
--- /dev/null
+++ b/src/web/api/session.ts
@@ -0,0 +1,150 @@
+import { Router } from "express";
+import type { Request, Response, NextFunction } from "express";
+import type { Logger } from "../../logger.js";
+import type { UserStore } from "../../data/users.js";
+import { UsernameTakenError } from "../../data/users.js";
+import type { SessionStore } from "../../data/sessions.js";
+import { SESSION_TTL_MS } from "../../data/sessions.js";
+import { SESSION_COOKIE_NAME, validateSessionFromHeaders } from "../auth/validateSession.js";
+
+const FAILED_LOGIN_DELAY_MS = 250;
+
+function setSessionCookie(res: Response, token: string): void {
+  res.cookie(SESSION_COOKIE_NAME, token, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: res.req.secure,
+    path: "/",
+    maxAge: SESSION_TTL_MS,
+  });
+}
+
+function clearSessionCookie(res: Response): void {
+  res.clearCookie(SESSION_COOKIE_NAME, { path: "/" });
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isValidUsername(v: unknown): v is string {
+  return typeof v === "string" && /^[A-Za-z0-9_\-.]{3,32}$/.test(v);
+}
+
+function isValidPassword(v: unknown): v is string {
+  return typeof v === "string" && v.length >= 8 && v.length <= 200;
+}
+
+function parseTokenFromCookie(cookieHeader: string | undefined): string | null {
+  if (!cookieHeader) return null;
+  const match = cookieHeader
+    .split(";")
+    .map((p) => p.trim())
+    .find((p) => p.startsWith(`${SESSION_COOKIE_NAME}=`));
+  if (!match) return null;
+  return decodeURIComponent(match.slice(SESSION_COOKIE_NAME.length + 1));
+}
+
+export function createSessionRouter(
+  users: UserStore,
+  sessions: SessionStore,
+  logger: Logger
+): Router {
+  const router = Router();
+
+  const requireAuthInline = (req: Request, res: Response, next: NextFunction) => {
+    const result = validateSessionFromHeaders(req.headers.cookie, sessions);
+    if (!result) {
+      clearSessionCookie(res);
+      res.status(401).json({ error: "unauthenticated" });
+      return;
+    }
+    req.user = { id: result.userId, username: result.username };
+    next();
+  };
+
+  router.get("/needs-setup", (_req, res) => {
+    res.json({ needsSetup: users.countUsers() === 0 });
+  });
+
+  router.post("/setup", async (req, res) => {
+    const { username, password } = req.body ?? {};
+    if (users.countUsers() !== 0) {
+      res.status(409).json({ error: "already initialized" });
+      return;
+    }
+    if (!isValidUsername(username) || !isValidPassword(password)) {
+      res.status(400).json({ error: "invalid username or password" });
+      return;
+    }
+    try {
+      const user = await users.createUser(username, password);
+      const { token } = sessions.createSession(user.id);
+      setSessionCookie(res, token);
+      logger.info({ userId: user.id, username }, "First admin created");
+      res.json({ id: user.id, username: user.username });
+    } catch (err) {
+      if (err instanceof UsernameTakenError) {
+        res.status(409).json({ error: "already initialized" });
+        return;
+      }
+      logger.error({ err }, "setup failed");
+      res.status(500).json({ error: "internal" });
+    }
+  });
+
+  router.post("/login", async (req, res) => {
+    const { username, password } = req.body ?? {};
+    if (typeof username !== "string" || typeof password !== "string") {
+      res.status(400).json({ error: "invalid request" });
+      return;
+    }
+    const user = users.findByUsername(username);
+    const ok = user ? await users.verifyPassword(password, user.passwordHash) : false;
+    if (!user || !ok) {
+      await delay(FAILED_LOGIN_DELAY_MS);
+      res.status(401).json({ error: "invalid credentials" });
+      return;
+    }
+    const { token } = sessions.createSession(user.id);
+    setSessionCookie(res, token);
+    res.json({ id: user.id, username: user.username });
+  });
+
+  router.post("/logout", (req, res) => {
+    const token = parseTokenFromCookie(req.headers.cookie);
+    if (token) {
+      sessions.deleteSession(token);
+    }
+    clearSessionCookie(res);
+    res.status(204).end();
+  });
+
+  router.get("/me", requireAuthInline, (req, res) => {
+    res.json(req.user);
+  });
+
+  router.post("/change-password", requireAuthInline, async (req, res) => {
+    const { oldPassword, newPassword } = req.body ?? {};
+    if (typeof oldPassword !== "string") {
+      res.status(400).json({ error: "invalid request" });
+      return;
+    }
+    const u = users.findById(req.user!.id);
+    if (!u || !(await users.verifyPassword(oldPassword, u.passwordHash))) {
+      await delay(FAILED_LOGIN_DELAY_MS);
+      res.status(401).json({ error: "invalid credentials" });
+      return;
+    }
+    if (!isValidPassword(newPassword)) {
+      res.status(400).json({ error: "invalid request" });
+      return;
+    }
+    await users.changePassword(u.id, newPassword);
+    const currentToken = parseTokenFromCookie(req.headers.cookie);
+    sessions.deleteAllForUser(u.id, currentToken ?? undefined);
+    res.status(204).end();
+  });
+
+  return router;
+}

From 486979841ec590f876a6fa555bfad1f72f9b356e Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:46:59 +0800
Subject: [PATCH 12/35] feat(auth): gate /api/* behind requireAuth + csrf; gate
 /ws via upgrade handler

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/web/server.ts | 65 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 59 insertions(+), 6 deletions(-)

diff --git a/src/web/server.ts b/src/web/server.ts
index b496c02..a3cd227 100755
--- a/src/web/server.ts
+++ b/src/web/server.ts
@@ -1,6 +1,7 @@
 import express from "express";
 import http from "node:http";
 import path from "node:path";
+import cookieParser from "cookie-parser";
 import { WebSocketServer } from "ws";
 import type { BotManager } from "../bot/manager.js";
 import type { MusicProvider } from "../music/provider.js";
@@ -13,7 +14,15 @@ import { createBotRouter } from "./api/bot.js";
 import { createMusicRouter } from "./api/music.js";
 import { createPlayerRouter } from "./api/player.js";
 import { createAuthRouter } from "./api/auth.js";
+import { createSessionRouter } from "./api/session.js";
 import { setupWebSocket } from "./websocket.js";
+import { createUserStore } from "../data/users.js";
+import { createSessionStore } from "../data/sessions.js";
+import { createRequireAuth } from "./middleware/requireAuth.js";
+import { csrfOriginCheck } from "./middleware/csrf.js";
+import { validateSessionFromHeaders } from "./auth/validateSession.js";
+
+const SESSION_CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 
 export interface WebServerOptions {
   port: number;
@@ -41,17 +50,33 @@ export function createWebServer(options: WebServerOptions): WebServer {
   const logger = options.logger.child({ component: "web" });
 
   if (options.config.trustProxy) {
-    // Honor X-Forwarded-* from a reverse proxy (nginx/Caddy/Cloudflare).
     app.set("trust proxy", true);
   }
 
   app.use(express.json({ limit: "400kb" }));
+  app.use(cookieParser());
+
+  const users = createUserStore(options.database.db);
+  const sessions = createSessionStore(options.database.db);
+
+  // ─── Public routes (no auth, no CSRF) ───────────────────────────────────
+  app.get("/api/health", (_req, res) => {
+    res.json({ status: "ok", version: "0.1.0" });
+  });
 
   app.get("/api/config/public-url", (_req, res) => {
     const raw = (options.config.publicUrl ?? "").trim();
     res.json({ publicUrl: raw ? raw.replace(/\/+$/, "") : null });
   });
 
+  app.use("/api/session", createSessionRouter(users, sessions, logger));
+
+  // ─── Gates for everything else under /api ───────────────────────────────
+  const requireAuth = createRequireAuth(sessions);
+  app.use("/api", csrfOriginCheck);
+  app.use("/api", requireAuth);
+
+  // ─── Protected routes ───────────────────────────────────────────────────
   app.use(
     "/api/bot",
     createBotRouter(
@@ -76,10 +101,7 @@ export function createWebServer(options: WebServerOptions): WebServer {
     createAuthRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.cookieStore)
   );
 
-  app.get("/api/health", (_req, res) => {
-    res.json({ status: "ok", version: "0.1.0" });
-  });
-
+  // ─── Static SPA (public) ────────────────────────────────────────────────
   if (options.staticDir) {
     app.use(express.static(options.staticDir));
     app.get(/^(?!\/api|\/ws)/, (_req, res) => {
@@ -91,22 +113,53 @@ export function createWebServer(options: WebServerOptions): WebServer {
     logger.error({ err }, "HTTP server error");
   });
 
-  const wss = new WebSocketServer({ server, path: "/ws" });
+  // ─── WebSocket with manual upgrade auth ────────────────────────────────
+  const wss = new WebSocketServer({ noServer: true });
   wss.on("error", (err) => {
     logger.error({ err }, "WebSocket server error");
   });
+  server.on("upgrade", (req, socket, head) => {
+    if (req.url !== "/ws") {
+      socket.destroy();
+      return;
+    }
+    const result = validateSessionFromHeaders(req.headers.cookie as string | undefined, sessions);
+    if (!result) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      (ws as unknown as { userId: string }).userId = result.userId;
+      wss.emit("connection", ws, req);
+    });
+  });
   const cleanupWs = setupWebSocket(wss, options.botManager, logger);
 
+  // ─── Session cleanup interval ──────────────────────────────────────────
+  let cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
   return {
     async start(): Promise<void> {
       return new Promise((resolve) => {
         server.listen(options.port, () => {
           logger.info({ port: options.port }, "Web server started");
+          cleanupTimer = setInterval(() => {
+            try {
+              sessions.cleanupExpired();
+            } catch (err) {
+              logger.error({ err }, "session cleanup failed");
+            }
+          }, SESSION_CLEANUP_INTERVAL_MS);
           resolve();
         });
       });
     },
     stop(): void {
+      if (cleanupTimer) {
+        clearInterval(cleanupTimer);
+        cleanupTimer = null;
+      }
       cleanupWs();
       wss.close();
       server.close();

From 490b2d57dc1342cf7fbe6cf96c6fc8a5fff68aa2 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:49:05 +0800
Subject: [PATCH 13/35] test(auth): verify ws upgrade gating end-to-end

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/web/websocket-auth.test.ts | 74 ++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 src/web/websocket-auth.test.ts

diff --git a/src/web/websocket-auth.test.ts b/src/web/websocket-auth.test.ts
new file mode 100644
index 0000000..efd9a9d
--- /dev/null
+++ b/src/web/websocket-auth.test.ts
@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import http from "node:http";
+import { WebSocketServer, WebSocket as WSClient } from "ws";
+import { AddressInfo } from "node:net";
+import { createDatabase, type BotDatabase } from "../data/database.js";
+import { createUserStore } from "../data/users.js";
+import { createSessionStore } from "../data/sessions.js";
+import { validateSessionFromHeaders, SESSION_COOKIE_NAME } from "./auth/validateSession.js";
+
+function buildServer(sessions: ReturnType<typeof createSessionStore>) {
+  const app = express();
+  const server = http.createServer(app);
+  const wss = new WebSocketServer({ noServer: true });
+  wss.on("connection", (ws) => ws.send("hello"));
+  server.on("upgrade", (req, socket, head) => {
+    if (req.url !== "/ws") return socket.destroy();
+    const r = validateSessionFromHeaders(req.headers.cookie as string | undefined, sessions);
+    if (!r) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req));
+  });
+  return { server, wss };
+}
+
+describe("WebSocket auth at upgrade", () => {
+  let botDb: BotDatabase;
+  let httpServer: http.Server;
+  let port: number;
+  let validToken: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const u = await users.createUser("alice", "pw");
+    validToken = sessions.createSession(u.id).token;
+
+    const { server } = buildServer(sessions);
+    httpServer = server;
+    await new Promise<void>((resolve) => httpServer.listen(0, resolve));
+    port = (httpServer.address() as AddressInfo).port;
+  });
+
+  afterEach(async () => {
+    await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+    botDb.close();
+  });
+
+  it("rejects upgrade without cookie (server-side close before open)", async () => {
+    const ws = new WSClient(`ws://127.0.0.1:${port}/ws`);
+    const result = await new Promise<string>((resolve) => {
+      ws.on("open", () => resolve("opened"));
+      ws.on("unexpected-response", (_req, res) => resolve(`status:${res.statusCode}`));
+      ws.on("error", () => resolve("error"));
+    });
+    expect(result).toMatch(/^status:401$|^error$/);
+  });
+
+  it("accepts upgrade with a valid cookie", async () => {
+    const ws = new WSClient(`ws://127.0.0.1:${port}/ws`, {
+      headers: { Cookie: `${SESSION_COOKIE_NAME}=${validToken}` },
+    });
+    const msg = await new Promise<string>((resolve, reject) => {
+      ws.on("message", (data) => resolve(data.toString()));
+      ws.on("error", reject);
+    });
+    expect(msg).toBe("hello");
+    ws.close();
+  });
+});

From 6db35f704dc0ce10d70383b4c11b8c9d658376cd Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:50:14 +0800
Subject: [PATCH 14/35] feat(web): add useSession composable

---
 web/src/composables/useSession.ts | 84 +++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 web/src/composables/useSession.ts

diff --git a/web/src/composables/useSession.ts b/web/src/composables/useSession.ts
new file mode 100644
index 0000000..97ec892
--- /dev/null
+++ b/web/src/composables/useSession.ts
@@ -0,0 +1,84 @@
+import { ref, computed, readonly } from "vue";
+
+interface User {
+  id: string;
+  username: string;
+}
+
+const currentUser = ref<User | null>(null);
+const needsSetup = ref<boolean | null>(null); // null = unknown / not fetched yet
+const ready = ref(false);
+
+async function refreshNeedsSetup(): Promise<void> {
+  const res = await fetch("/api/session/needs-setup", { credentials: "same-origin" });
+  if (res.ok) {
+    const body = await res.json();
+    needsSetup.value = Boolean(body.needsSetup);
+  }
+}
+
+async function refreshMe(): Promise<void> {
+  const res = await fetch("/api/session/me", { credentials: "same-origin" });
+  if (res.status === 200) {
+    currentUser.value = (await res.json()) as User;
+  } else {
+    currentUser.value = null;
+  }
+}
+
+async function refresh(): Promise<void> {
+  await refreshNeedsSetup();
+  if (needsSetup.value) {
+    currentUser.value = null;
+  } else {
+    await refreshMe();
+  }
+  ready.value = true;
+}
+
+async function login(username: string, password: string): Promise<void> {
+  const res = await fetch("/api/session/login", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ username, password }),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error ?? `login failed (${res.status})`);
+  }
+  currentUser.value = (await res.json()) as User;
+}
+
+async function setup(username: string, password: string): Promise<void> {
+  const res = await fetch("/api/session/setup", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ username, password }),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error ?? `setup failed (${res.status})`);
+  }
+  currentUser.value = (await res.json()) as User;
+  needsSetup.value = false;
+}
+
+async function logout(): Promise<void> {
+  await fetch("/api/session/logout", { method: "POST", credentials: "same-origin" });
+  currentUser.value = null;
+}
+
+export function useSession() {
+  return {
+    currentUser: readonly(currentUser),
+    needsSetup: readonly(needsSetup),
+    isAuthenticated: computed(() => currentUser.value !== null),
+    ready: readonly(ready),
+    refresh,
+    login,
+    logout,
+    setup,
+  };
+}

From 2560fc87c2a7b25a702632a5e9ca82287d10bff2 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:51:20 +0800
Subject: [PATCH 15/35] feat(web): add Login view

---
 web/src/views/Login.vue | 77 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 web/src/views/Login.vue

diff --git a/web/src/views/Login.vue b/web/src/views/Login.vue
new file mode 100644
index 0000000..feb6658
--- /dev/null
+++ b/web/src/views/Login.vue
@@ -0,0 +1,77 @@
+<template>
+  <div class="auth-page">
+    <form class="auth-card" @submit.prevent="submit">
+      <h1>登录 TSMusicBot</h1>
+      <label>
+        <span>用户名</span>
+        <input v-model="username" type="text" autocomplete="username" autofocus required />
+      </label>
+      <label>
+        <span>密码</span>
+        <input v-model="password" type="password" autocomplete="current-password" required />
+      </label>
+      <p v-if="error" class="auth-error">{{ error }}</p>
+      <button type="submit" :disabled="loading">{{ loading ? '登录中…' : '登录' }}</button>
+    </form>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { useSession } from '../composables/useSession.js';
+
+const username = ref('');
+const password = ref('');
+const error = ref('');
+const loading = ref(false);
+const router = useRouter();
+const route = useRoute();
+const session = useSession();
+
+async function submit() {
+  error.value = '';
+  loading.value = true;
+  try {
+    await session.login(username.value, password.value);
+    const next = typeof route.query.next === 'string' ? route.query.next : '/';
+    router.replace(next);
+  } catch (e) {
+    error.value = (e as Error).message;
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+
+<style scoped lang="scss">
+.auth-page {
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--bg-primary);
+}
+.auth-card {
+  width: 360px;
+  padding: 32px;
+  background: var(--bg-secondary);
+  border-radius: var(--radius-md);
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  box-shadow: var(--shadow-dropdown);
+}
+.auth-card h1 { margin: 0 0 8px; font-size: 20px; color: var(--text-primary); }
+.auth-card label { display: flex; flex-direction: column; gap: 6px; font-size: 12px; color: var(--text-secondary); }
+.auth-card input {
+  height: 36px; padding: 0 10px; border-radius: var(--radius-sm);
+  background: var(--bg-primary); color: var(--text-primary); border: 1px solid var(--border-color);
+}
+.auth-card button {
+  height: 38px; border-radius: var(--radius-sm); border: 0;
+  background: var(--color-primary); color: #fff; font-weight: 500; cursor: pointer;
+}
+.auth-card button:disabled { opacity: 0.6; cursor: progress; }
+.auth-error { color: #e26a6a; font-size: 13px; margin: 0; }
+</style>

From 0dc87469149f37209b247846443699331c0c98a8 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:52:49 +0800
Subject: [PATCH 16/35] feat(web): add /first-run + /login routes with auth
 guard

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 web/src/router/index.ts         | 82 ++++++++++++++++-----------------
 web/src/views/FirstRunSetup.vue | 75 ++++++++++++++++++++++++++++++
 2 files changed, 116 insertions(+), 41 deletions(-)
 create mode 100644 web/src/views/FirstRunSetup.vue

diff --git a/web/src/router/index.ts b/web/src/router/index.ts
index d62afcd..3965ceb 100644
--- a/web/src/router/index.ts
+++ b/web/src/router/index.ts
@@ -1,23 +1,12 @@
 import { createRouter, createWebHistory } from 'vue-router';
+import { useSession } from '../composables/useSession.js';
 
 const router = createRouter({
   history: createWebHistory(),
   routes: [
-    {
-      path: '/',
-      name: 'home',
-      component: () => import('../views/Home.vue'),
-    },
-    {
-      path: '/search',
-      name: 'search',
-      component: () => import('../views/Search.vue'),
-    },
-    {
-      path: '/library',
-      name: 'library',
-      component: () => import('../views/Library.vue'),
-    },
+    { path: '/', name: 'home', component: () => import('../views/Home.vue') },
+    { path: '/search', name: 'search', component: () => import('../views/Search.vue') },
+    { path: '/library', name: 'library', component: () => import('../views/Library.vue') },
     {
       path: '/playlist/:id',
       name: 'playlist',
@@ -30,33 +19,44 @@ const router = createRouter({
       component: () => import('../views/Playlist.vue'),
       meta: { kind: 'album' },
     },
-    {
-      path: '/lyrics',
-      name: 'lyrics',
-      component: () => import('../views/Lyrics.vue'),
-    },
-    {
-      path: '/history',
-      name: 'history',
-      component: () => import('../views/History.vue'),
-    },
-    {
-      path: '/settings',
-      name: 'settings',
-      component: () => import('../views/Settings.vue'),
-    },
-    {
-      path: '/setup',
-      name: 'setup',
-      component: () => import('../views/Setup.vue'),
-    },
-    {
-      // Per-bot URL: /bot/:id — sets active bot then redirects to home
-      path: '/bot/:id',
-      name: 'bot',
-      component: () => import('../views/BotRedirect.vue'),
-    },
+    { path: '/lyrics', name: 'lyrics', component: () => import('../views/Lyrics.vue') },
+    { path: '/history', name: 'history', component: () => import('../views/History.vue') },
+    { path: '/settings', name: 'settings', component: () => import('../views/Settings.vue') },
+    { path: '/setup', name: 'setup', component: () => import('../views/Setup.vue') },
+    { path: '/bot/:id', name: 'bot', component: () => import('../views/BotRedirect.vue') },
+
+    // Auth views
+    { path: '/login', name: 'login', component: () => import('../views/Login.vue'), meta: { public: true } },
+    { path: '/first-run', name: 'first-run', component: () => import('../views/FirstRunSetup.vue'), meta: { public: true } },
   ],
 });
 
+const PUBLIC_NAMES = new Set(['login', 'first-run']);
+
+router.beforeEach(async (to) => {
+  const session = useSession();
+  if (!session.ready.value) {
+    await session.refresh();
+  }
+
+  if (session.needsSetup.value && to.name !== 'first-run') {
+    return { name: 'first-run' };
+  }
+  if (!session.needsSetup.value && to.name === 'first-run') {
+    return { name: 'home' };
+  }
+
+  if (PUBLIC_NAMES.has(to.name as string)) {
+    if (to.name === 'login' && session.isAuthenticated.value) {
+      return { name: 'home' };
+    }
+    return true;
+  }
+
+  if (!session.isAuthenticated.value) {
+    return { name: 'login', query: { next: to.fullPath } };
+  }
+  return true;
+});
+
 export default router;
diff --git a/web/src/views/FirstRunSetup.vue b/web/src/views/FirstRunSetup.vue
new file mode 100644
index 0000000..24664d6
--- /dev/null
+++ b/web/src/views/FirstRunSetup.vue
@@ -0,0 +1,75 @@
+<template>
+  <div class="auth-page">
+    <form class="auth-card" @submit.prevent="submit">
+      <h1>首次使用</h1>
+      <p class="auth-hint">创建管理员账号。该账号将拥有 WebUI 的全部权限。</p>
+      <label>
+        <span>用户名</span>
+        <input v-model="username" type="text" autocomplete="username" autofocus required />
+      </label>
+      <label>
+        <span>密码 (≥8 位)</span>
+        <input v-model="password" type="password" autocomplete="new-password" minlength="8" required />
+      </label>
+      <label>
+        <span>再次输入密码</span>
+        <input v-model="confirm" type="password" autocomplete="new-password" minlength="8" required />
+      </label>
+      <p v-if="error" class="auth-error">{{ error }}</p>
+      <button type="submit" :disabled="loading">{{ loading ? '创建中…' : '创建管理员' }}</button>
+    </form>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useRouter } from 'vue-router';
+import { useSession } from '../composables/useSession.js';
+
+const username = ref('');
+const password = ref('');
+const confirm = ref('');
+const error = ref('');
+const loading = ref(false);
+const router = useRouter();
+const session = useSession();
+
+async function submit() {
+  error.value = '';
+  if (password.value !== confirm.value) {
+    error.value = '两次输入的密码不一致';
+    return;
+  }
+  loading.value = true;
+  try {
+    await session.setup(username.value, password.value);
+    router.replace('/');
+  } catch (e) {
+    error.value = (e as Error).message;
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+
+<style scoped lang="scss">
+.auth-page { min-height: 100vh; display: flex; align-items: center; justify-content: center; background: var(--bg-primary); }
+.auth-card {
+  width: 360px; padding: 32px; background: var(--bg-secondary);
+  border-radius: var(--radius-md); display: flex; flex-direction: column; gap: 12px;
+  box-shadow: var(--shadow-dropdown);
+}
+.auth-card h1 { margin: 0; font-size: 20px; color: var(--text-primary); }
+.auth-hint { margin: 0 0 4px; font-size: 12px; color: var(--text-secondary); }
+.auth-card label { display: flex; flex-direction: column; gap: 6px; font-size: 12px; color: var(--text-secondary); }
+.auth-card input {
+  height: 36px; padding: 0 10px; border-radius: var(--radius-sm);
+  background: var(--bg-primary); color: var(--text-primary); border: 1px solid var(--border-color);
+}
+.auth-card button {
+  height: 38px; border-radius: var(--radius-sm); border: 0;
+  background: var(--color-primary); color: #fff; font-weight: 500; cursor: pointer;
+}
+.auth-card button:disabled { opacity: 0.6; cursor: progress; }
+.auth-error { color: #e26a6a; font-size: 13px; margin: 0; }
+</style>

From 7509814abc50b5ecdbe4b0a8a896763e207af75e Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:54:24 +0800
Subject: [PATCH 17/35] feat(web): install global fetch wrapper with
 credentials + 401 handling

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 web/src/api/http.ts | 48 +++++++++++++++++++++++++++++++++++++++++++++
 web/src/main.ts     |  3 +++
 2 files changed, 51 insertions(+)
 create mode 100644 web/src/api/http.ts

diff --git a/web/src/api/http.ts b/web/src/api/http.ts
new file mode 100644
index 0000000..676be26
--- /dev/null
+++ b/web/src/api/http.ts
@@ -0,0 +1,48 @@
+import router from '../router/index.js';
+import { useSession } from '../composables/useSession.js';
+
+let installed = false;
+
+/**
+ * Wraps fetch so every call:
+ *   - sends cookies (`credentials: 'same-origin'`)
+ *   - on 401 from /api/*: clear local session, redirect to /login
+ */
+export function apiFetch(input: RequestInfo | URL, init: RequestInit = {}): Promise<Response> {
+  const merged: RequestInit = {
+    credentials: 'same-origin',
+    ...init,
+    headers: { ...(init.headers ?? {}) },
+  };
+  return fetch(input, merged).then(async (res) => {
+    if (res.status === 401 && isApiPath(input)) {
+      const session = useSession();
+      await session.refresh();
+      const current = router.currentRoute.value;
+      if (current.name !== 'login' && current.name !== 'first-run') {
+        await router.replace({ name: 'login', query: { next: current.fullPath } });
+      }
+    }
+    return res;
+  });
+}
+
+function isApiPath(input: RequestInfo | URL): boolean {
+  const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+  return url.startsWith('/api/');
+}
+
+/**
+ * Replaces window.fetch with apiFetch so existing call sites do not need to be touched.
+ * Call once at app startup.
+ */
+export function installApiClient(): void {
+  if (installed) return;
+  installed = true;
+  const original = window.fetch.bind(window);
+  window.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+    return apiFetch(input, init ?? {});
+  }) as typeof window.fetch;
+  // Keep original accessible if anything needs to bypass
+  (window as unknown as { __originalFetch?: typeof fetch }).__originalFetch = original;
+}
diff --git a/web/src/main.ts b/web/src/main.ts
index e20f04b..89568a9 100644
--- a/web/src/main.ts
+++ b/web/src/main.ts
@@ -2,9 +2,12 @@ import { createApp } from 'vue';
 import { createPinia } from 'pinia';
 import App from './App.vue';
 import router from './router/index.js';
+import { installApiClient } from './api/http.js';
 import './styles/global.scss';
 import './styles/mobile.scss';
 
+installApiClient();
+
 const app = createApp(App);
 app.use(createPinia());
 app.use(router);

From e2e888710af6db37bc290afb036fc981ec0a2f1d Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:56:14 +0800
Subject: [PATCH 18/35] fix(web): exclude /api/session/* from 401 auto-refresh
 to prevent re-entrancy

---
 web/src/api/http.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/web/src/api/http.ts b/web/src/api/http.ts
index 676be26..920c02b 100644
--- a/web/src/api/http.ts
+++ b/web/src/api/http.ts
@@ -15,7 +15,7 @@ export function apiFetch(input: RequestInfo | URL, init: RequestInit = {}): Prom
     headers: { ...(init.headers ?? {}) },
   };
   return fetch(input, merged).then(async (res) => {
-    if (res.status === 401 && isApiPath(input)) {
+    if (res.status === 401 && shouldTriggerRefresh(input)) {
       const session = useSession();
       await session.refresh();
       const current = router.currentRoute.value;
@@ -27,9 +27,9 @@ export function apiFetch(input: RequestInfo | URL, init: RequestInit = {}): Prom
   });
 }
 
-function isApiPath(input: RequestInfo | URL): boolean {
+function shouldTriggerRefresh(input: RequestInfo | URL): boolean {
   const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
-  return url.startsWith('/api/');
+  return url.startsWith('/api/') && !url.startsWith('/api/session/');
 }
 
 /**

From e148c1556e320acbcf62b0decbca4d0a3a55de61 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 13:57:31 +0800
Subject: [PATCH 19/35] feat(web): show current user + logout button in nav

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 web/src/components/Navbar.vue | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/web/src/components/Navbar.vue b/web/src/components/Navbar.vue
index 1776d59..789e865 100644
--- a/web/src/components/Navbar.vue
+++ b/web/src/components/Navbar.vue
@@ -88,6 +88,13 @@
       <RouterLink to="/settings" class="settings-btn">
         <Icon icon="mdi:cog" />
       </RouterLink>
+
+      <div v-if="session.currentUser.value" class="nav-user">
+        <span class="nav-user-name">{{ session.currentUser.value.username }}</span>
+        <button class="nav-user-logout" @click="onLogout" title="退出">
+          <Icon icon="mdi:logout" />
+        </button>
+      </div>
     </div>
   </nav>
 
@@ -114,10 +121,19 @@
 
 <script setup lang="ts">
 import { computed, ref, onMounted, onUnmounted, nextTick, reactive } from 'vue';
+import { useRouter } from 'vue-router';
 import { Icon } from '@iconify/vue';
 import { usePlayerStore } from '../stores/player.js';
+import { useSession } from '../composables/useSession.js';
 
 const store = usePlayerStore();
+const session = useSession();
+const navRouter = useRouter();
+
+async function onLogout() {
+  await session.logout();
+  navRouter.replace({ name: 'login' });
+}
 const activeBot = computed(() => store.activeBot);
 const dropdownOpen = ref(false);
 const selectorRef = ref<HTMLElement | null>(null);
@@ -643,4 +659,15 @@ onUnmounted(() => {
     }
   }
 }
+
+.nav-user {
+  display: flex; align-items: center; gap: 8px; margin-left: 12px;
+  color: var(--text-secondary); font-size: 13px;
+}
+.nav-user-logout {
+  height: 28px; width: 28px; display: grid; place-items: center;
+  border: 0; background: transparent; color: var(--text-secondary); cursor: pointer;
+  border-radius: var(--radius-sm);
+  &:hover { background: var(--bg-secondary); color: var(--text-primary); }
+}
 </style>

From a8b056d2aa9b168b7903205f3ec62054bf9289bf Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 14:02:33 +0800
Subject: [PATCH 20/35] fix(auth): WS Origin host check + Login next-param
 open-redirect guard

---
 src/web/server.ts       | 15 +++++++++++++++
 web/src/views/Login.vue |  3 ++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/src/web/server.ts b/src/web/server.ts
index a3cd227..d7ad9e8 100755
--- a/src/web/server.ts
+++ b/src/web/server.ts
@@ -123,6 +123,21 @@ export function createWebServer(options: WebServerOptions): WebServer {
       socket.destroy();
       return;
     }
+    const reqHost = req.headers.host;
+    const originHeader = req.headers.origin;
+    if (originHeader) {
+      let originHost: string | null = null;
+      try {
+        originHost = new URL(originHeader).host;
+      } catch {
+        // fall through; treat as missing/invalid origin
+      }
+      if (!originHost || originHost !== reqHost) {
+        socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+        socket.destroy();
+        return;
+      }
+    }
     const result = validateSessionFromHeaders(req.headers.cookie as string | undefined, sessions);
     if (!result) {
       socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
diff --git a/web/src/views/Login.vue b/web/src/views/Login.vue
index feb6658..4cad401 100644
--- a/web/src/views/Login.vue
+++ b/web/src/views/Login.vue
@@ -34,7 +34,8 @@ async function submit() {
   loading.value = true;
   try {
     await session.login(username.value, password.value);
-    const next = typeof route.query.next === 'string' ? route.query.next : '/';
+    const rawNext = typeof route.query.next === 'string' ? route.query.next : '/';
+    const next = rawNext.startsWith('/') && !rawNext.startsWith('//') ? rawNext : '/';
     router.replace(next);
   } catch (e) {
     error.value = (e as Error).message;

From f46b37192faa5037639093a892c44a3535227884 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 14:34:56 +0800
Subject: [PATCH 21/35] fix(web): break infinite recursion in apiFetch by
 capturing nativeFetch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

apiFetch called window.fetch which installApiClient had reassigned to
call apiFetch — every request blew the stack. Capture the native fetch
at module load (before any wrap) and use it inside apiFetch.

Symptom: first-run / login redirect never fires because the router
guard hangs on session.refresh().

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 web/src/api/http.ts | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/web/src/api/http.ts b/web/src/api/http.ts
index 920c02b..e196051 100644
--- a/web/src/api/http.ts
+++ b/web/src/api/http.ts
@@ -2,11 +2,14 @@ import router from '../router/index.js';
 import { useSession } from '../composables/useSession.js';
 
 let installed = false;
+const nativeFetch: typeof window.fetch = window.fetch.bind(window);
 
 /**
  * Wraps fetch so every call:
  *   - sends cookies (`credentials: 'same-origin'`)
  *   - on 401 from /api/*: clear local session, redirect to /login
+ *
+ * Always uses the captured native fetch, never the (possibly wrapped) global.
  */
 export function apiFetch(input: RequestInfo | URL, init: RequestInit = {}): Promise<Response> {
   const merged: RequestInit = {
@@ -14,7 +17,7 @@ export function apiFetch(input: RequestInfo | URL, init: RequestInit = {}): Prom
     ...init,
     headers: { ...(init.headers ?? {}) },
   };
-  return fetch(input, merged).then(async (res) => {
+  return nativeFetch(input, merged).then(async (res) => {
     if (res.status === 401 && shouldTriggerRefresh(input)) {
       const session = useSession();
       await session.refresh();
@@ -39,10 +42,8 @@ function shouldTriggerRefresh(input: RequestInfo | URL): boolean {
 export function installApiClient(): void {
   if (installed) return;
   installed = true;
-  const original = window.fetch.bind(window);
   window.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
     return apiFetch(input, init ?? {});
   }) as typeof window.fetch;
-  // Keep original accessible if anything needs to bypass
-  (window as unknown as { __originalFetch?: typeof fetch }).__originalFetch = original;
+  (window as unknown as { __originalFetch?: typeof fetch }).__originalFetch = nativeFetch;
 }

From 175b8e60651657bb9431e964328553bce7bfeb48 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 14:41:58 +0800
Subject: [PATCH 22/35] feat(auth): add /api/users CRUD (list, create, delete,
 reset-password)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/data/users.test.ts    |  19 ++++++
 src/data/users.ts         |  15 +++++
 src/web/api/users.test.ts | 138 ++++++++++++++++++++++++++++++++++++++
 src/web/api/users.ts      |  83 +++++++++++++++++++++++
 src/web/server.ts         |   2 +
 5 files changed, 257 insertions(+)
 create mode 100644 src/web/api/users.test.ts
 create mode 100644 src/web/api/users.ts

diff --git a/src/data/users.test.ts b/src/data/users.test.ts
index 0bbd30d..65fc7f1 100644
--- a/src/data/users.test.ts
+++ b/src/data/users.test.ts
@@ -53,4 +53,23 @@ describe("UserStore", () => {
     expect(await users.verifyPassword("old", row!.passwordHash)).toBe(false);
     expect(await users.verifyPassword("new", row!.passwordHash)).toBe(true);
   });
+
+  it("listUsers returns id+username+createdAt ascending, no password hash", async () => {
+    await users.createUser("alice", "pw-alice");
+    await users.createUser("bob", "pw-bob");
+    const list = users.listUsers();
+    expect(list).toHaveLength(2);
+    expect(list[0].username).toBe("alice");
+    expect(list[1].username).toBe("bob");
+    expect(list[0]).not.toHaveProperty("passwordHash");
+    expect(list[0].id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(typeof list[0].createdAt).toBe("number");
+  });
+
+  it("deleteUser removes the row and returns true; returns false for unknown id", async () => {
+    const u = await users.createUser("alice", "pw-alice");
+    expect(users.deleteUser(u.id)).toBe(true);
+    expect(users.countUsers()).toBe(0);
+    expect(users.deleteUser("not-a-real-id")).toBe(false);
+  });
 });
diff --git a/src/data/users.ts b/src/data/users.ts
index d79ca40..42e9450 100644
--- a/src/data/users.ts
+++ b/src/data/users.ts
@@ -19,6 +19,8 @@ export interface UserStore {
   findById(id: string): UserRow | null;
   verifyPassword(plain: string, hash: string): Promise<boolean>;
   changePassword(userId: string, newPassword: string): Promise<void>;
+  listUsers(): Array<{ id: string; username: string; createdAt: number }>;
+  deleteUser(id: string): boolean;
 }
 
 export class UsernameTakenError extends Error {
@@ -42,6 +44,10 @@ export function createUserStore(db: Database.Database): UserStore {
   const updatePasswordStmt = db.prepare(
     "UPDATE users SET passwordHash = ?, updatedAt = ? WHERE id = ?"
   );
+  const listUsersStmt = db.prepare(
+    "SELECT id, username, createdAt FROM users ORDER BY createdAt ASC"
+  );
+  const deleteUserStmt = db.prepare("DELETE FROM users WHERE id = ?");
 
   return {
     countUsers() {
@@ -79,5 +85,14 @@ export function createUserStore(db: Database.Database): UserStore {
       const hash = await bcrypt.hash(newPassword, BCRYPT_ROUNDS);
       updatePasswordStmt.run(hash, Date.now(), userId);
     },
+
+    listUsers() {
+      return listUsersStmt.all() as Array<{ id: string; username: string; createdAt: number }>;
+    },
+
+    deleteUser(id) {
+      const result = deleteUserStmt.run(id);
+      return result.changes > 0;
+    },
   };
 }
diff --git a/src/web/api/users.test.ts b/src/web/api/users.test.ts
new file mode 100644
index 0000000..63b0c92
--- /dev/null
+++ b/src/web/api/users.test.ts
@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import pino from "pino";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore, type UserStore } from "../../data/users.js";
+import { createSessionStore, type SessionStore } from "../../data/sessions.js";
+import { createRequireAuth } from "../middleware/requireAuth.js";
+import { createUsersRouter } from "./users.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+function makeApp(users: UserStore, sessions: SessionStore) {
+  const app = express();
+  app.use(express.json());
+  app.use(cookieParser());
+  const requireAuth = createRequireAuth(sessions);
+  app.use("/api", requireAuth);
+  app.use("/api/users", createUsersRouter(users, sessions, pino({ level: "silent" })));
+  return app;
+}
+
+describe("users router", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+  let sessions: SessionStore;
+  let app: express.Express;
+  let aliceId: string;
+  let aliceCookie: string;
+  let bobId: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+    sessions = createSessionStore(botDb.db);
+    app = makeApp(users, sessions);
+    const alice = await users.createUser("alice", "pw-alice");
+    aliceId = alice.id;
+    aliceCookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(alice.id).token}`;
+    const bob = await users.createUser("bob", "pw-bob-bob");
+    bobId = bob.id;
+  });
+
+  afterEach(() => botDb.close());
+
+  it("requires auth for all routes", async () => {
+    expect((await request(app).get("/api/users")).status).toBe(401);
+    expect((await request(app).post("/api/users").send({ username: "x", password: "yyyyyyyy" })).status).toBe(401);
+    expect((await request(app).delete(`/api/users/${bobId}`)).status).toBe(401);
+  });
+
+  it("GET / lists users with id+username+createdAt, no password hash", async () => {
+    const res = await request(app).get("/api/users").set("Cookie", aliceCookie);
+    expect(res.status).toBe(200);
+    expect(res.body.users).toHaveLength(2);
+    for (const u of res.body.users) {
+      expect(u).toHaveProperty("id");
+      expect(u).toHaveProperty("username");
+      expect(u).toHaveProperty("createdAt");
+      expect(u).not.toHaveProperty("passwordHash");
+    }
+  });
+
+  it("POST / creates a user", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "charlie", password: "charlie-pw" });
+    expect(res.status).toBe(201);
+    expect(res.body.username).toBe("charlie");
+    expect(users.countUsers()).toBe(3);
+  });
+
+  it("POST / returns 409 on duplicate username", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "BOB", password: "another-pw" });
+    expect(res.status).toBe(409);
+  });
+
+  it("POST / returns 400 on invalid input", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "x", password: "short" });
+    expect(res.status).toBe(400);
+  });
+
+  it("DELETE /:id removes the user and their sessions", async () => {
+    const bobToken = sessions.createSession(bobId).token;
+    const res = await request(app).delete(`/api/users/${bobId}`).set("Cookie", aliceCookie);
+    expect(res.status).toBe(204);
+    expect(users.countUsers()).toBe(1);
+    expect(sessions.validateAndTouch(bobToken)).toBeNull();
+  });
+
+  it("DELETE /:id of self returns 400", async () => {
+    const res = await request(app).delete(`/api/users/${aliceId}`).set("Cookie", aliceCookie);
+    expect(res.status).toBe(400);
+    expect(res.body).toEqual({ error: "cannot delete self" });
+    expect(users.countUsers()).toBe(2);
+  });
+
+  it("DELETE /:id of nonexistent returns 404", async () => {
+    const res = await request(app).delete(`/api/users/not-a-real-id`).set("Cookie", aliceCookie);
+    expect(res.status).toBe(404);
+  });
+
+  it("POST /:id/reset-password updates the hash and invalidates target's sessions", async () => {
+    const bobToken = sessions.createSession(bobId).token;
+    const res = await request(app)
+      .post(`/api/users/${bobId}/reset-password`)
+      .set("Cookie", aliceCookie)
+      .send({ newPassword: "bob-new-pw" });
+    expect(res.status).toBe(204);
+    expect(sessions.validateAndTouch(bobToken)).toBeNull();
+    const bob = users.findByUsername("bob");
+    expect(await users.verifyPassword("bob-new-pw", bob!.passwordHash)).toBe(true);
+    expect(await users.verifyPassword("pw-bob-bob", bob!.passwordHash)).toBe(false);
+  });
+
+  it("POST /:id/reset-password 404 on unknown user", async () => {
+    const res = await request(app)
+      .post(`/api/users/not-a-real-id/reset-password`)
+      .set("Cookie", aliceCookie)
+      .send({ newPassword: "anything-here" });
+    expect(res.status).toBe(404);
+  });
+
+  it("POST /:id/reset-password 400 on short password", async () => {
+    const res = await request(app)
+      .post(`/api/users/${bobId}/reset-password`)
+      .set("Cookie", aliceCookie)
+      .send({ newPassword: "short" });
+    expect(res.status).toBe(400);
+  });
+});
diff --git a/src/web/api/users.ts b/src/web/api/users.ts
new file mode 100644
index 0000000..b837e77
--- /dev/null
+++ b/src/web/api/users.ts
@@ -0,0 +1,83 @@
+import { Router } from "express";
+import type { Logger } from "../../logger.js";
+import type { UserStore } from "../../data/users.js";
+import { UsernameTakenError } from "../../data/users.js";
+import type { SessionStore } from "../../data/sessions.js";
+
+function isValidUsername(v: unknown): v is string {
+  return typeof v === "string" && /^[A-Za-z0-9_\-.]{3,32}$/.test(v);
+}
+
+function isValidPassword(v: unknown): v is string {
+  return typeof v === "string" && v.length >= 8 && v.length <= 200;
+}
+
+export function createUsersRouter(
+  users: UserStore,
+  sessions: SessionStore,
+  logger: Logger
+): Router {
+  const router = Router();
+
+  router.get("/", (_req, res) => {
+    res.json({ users: users.listUsers() });
+  });
+
+  router.post("/", async (req, res) => {
+    const { username, password } = req.body ?? {};
+    if (!isValidUsername(username) || !isValidPassword(password)) {
+      res.status(400).json({ error: "invalid username or password" });
+      return;
+    }
+    try {
+      const u = await users.createUser(username, password);
+      logger.info({ createdBy: req.user!.id, newUserId: u.id, username }, "User created");
+      res.status(201).json({ id: u.id, username: u.username });
+    } catch (err) {
+      if (err instanceof UsernameTakenError) {
+        res.status(409).json({ error: "username taken" });
+        return;
+      }
+      logger.error({ err }, "createUser failed");
+      res.status(500).json({ error: "internal" });
+    }
+  });
+
+  router.delete("/:id", (req, res) => {
+    const targetId = req.params.id;
+    if (targetId === req.user!.id) {
+      res.status(400).json({ error: "cannot delete self" });
+      return;
+    }
+    const deleted = users.deleteUser(targetId);
+    if (!deleted) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    sessions.deleteAllForUser(targetId);
+    logger.info({ deletedBy: req.user!.id, deletedUserId: targetId }, "User deleted");
+    res.status(204).end();
+  });
+
+  router.post("/:id/reset-password", async (req, res) => {
+    const { newPassword } = req.body ?? {};
+    if (!isValidPassword(newPassword)) {
+      res.status(400).json({ error: "invalid password" });
+      return;
+    }
+    const targetId = req.params.id;
+    const target = users.findById(targetId);
+    if (!target) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    await users.changePassword(targetId, newPassword);
+    // Invalidate all sessions for the target user (except current actor's if it's the same user)
+    const exceptToken = targetId === req.user!.id ? undefined : undefined;
+    sessions.deleteAllForUser(targetId, exceptToken);
+    logger.info({ resetBy: req.user!.id, targetUserId: targetId }, "Password reset");
+    res.status(204).end();
+  });
+
+  return router;
+}
diff --git a/src/web/server.ts b/src/web/server.ts
index d7ad9e8..1424f46 100755
--- a/src/web/server.ts
+++ b/src/web/server.ts
@@ -15,6 +15,7 @@ import { createMusicRouter } from "./api/music.js";
 import { createPlayerRouter } from "./api/player.js";
 import { createAuthRouter } from "./api/auth.js";
 import { createSessionRouter } from "./api/session.js";
+import { createUsersRouter } from "./api/users.js";
 import { setupWebSocket } from "./websocket.js";
 import { createUserStore } from "../data/users.js";
 import { createSessionStore } from "../data/sessions.js";
@@ -100,6 +101,7 @@ export function createWebServer(options: WebServerOptions): WebServer {
     "/api/auth",
     createAuthRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.cookieStore)
   );
+  app.use("/api/users", createUsersRouter(users, sessions, logger));
 
   // ─── Static SPA (public) ────────────────────────────────────────────────
   if (options.staticDir) {

From fb7feec5cf832847a860f51574ec1c73b103a965 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 14:44:42 +0800
Subject: [PATCH 23/35] feat(web): user management section in Settings
 (list/create/delete/reset-password)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 web/src/views/Settings.vue | 185 +++++++++++++++++++++++++++++++++++++
 1 file changed, 185 insertions(+)

diff --git a/web/src/views/Settings.vue b/web/src/views/Settings.vue
index 3f16861..94aa393 100755
--- a/web/src/views/Settings.vue
+++ b/web/src/views/Settings.vue
@@ -458,6 +458,65 @@
         </div>
       </div>
     </section>
+
+    <!-- User Management -->
+    <section class="settings-section">
+      <h2 class="section-title">用户管理</h2>
+      <div class="user-list">
+        <div v-for="u in userList" :key="u.id" class="user-item">
+          <div class="user-info">
+            <div class="user-name">
+              {{ u.username }}
+              <span v-if="session.currentUser.value && u.id === session.currentUser.value.id" class="user-self-badge">本人</span>
+            </div>
+            <div class="user-created">创建于 {{ formatDate(u.createdAt) }}</div>
+          </div>
+          <div class="user-actions">
+            <button class="btn-sm" @click="openResetPassword(u)">
+              <Icon icon="mdi:lock-reset" /> 重置密码
+            </button>
+            <button
+              class="btn-sm btn-delete"
+              :disabled="!!(session.currentUser.value && u.id === session.currentUser.value.id)"
+              :title="session.currentUser.value && u.id === session.currentUser.value.id ? '不能删除自己' : ''"
+              @click="onDeleteUser(u)"
+            >
+              <Icon icon="mdi:delete" />
+            </button>
+          </div>
+        </div>
+        <div v-if="userList.length === 0 && !userLoadError" class="user-empty">加载中…</div>
+        <div v-if="userLoadError" class="user-error">{{ userLoadError }}</div>
+      </div>
+
+      <form class="user-add-form" @submit.prevent="onCreateUser">
+        <input v-model="newUser.username" class="input" placeholder="新用户名 (3-32 字符)" required />
+        <input v-model="newUser.password" type="password" class="input" placeholder="密码 (≥8 位)" minlength="8" required />
+        <button class="btn-sm btn-primary" type="submit" :disabled="creatingUser">
+          {{ creatingUser ? '创建中…' : '添加用户' }}
+        </button>
+      </form>
+      <p v-if="userMutationError" class="user-error">{{ userMutationError }}</p>
+
+      <!-- Reset password modal -->
+      <div v-if="resetTarget" class="edit-modal-overlay" @click.self="resetTarget = null">
+        <div class="edit-modal">
+          <h3 class="modal-title">重置 {{ resetTarget.username }} 的密码</h3>
+          <p class="modal-hint">该用户的所有会话将被强制下线。</p>
+          <div class="form-group">
+            <label>新密码 (≥8 位)</label>
+            <input v-model="resetPassword" type="password" class="input" minlength="8" />
+          </div>
+          <p v-if="resetError" class="user-error">{{ resetError }}</p>
+          <div class="form-actions">
+            <button class="btn-sm" @click="resetTarget = null">取消</button>
+            <button class="btn-sm btn-primary" :disabled="resettingPw" @click="onConfirmReset">
+              {{ resettingPw ? '保存中…' : '确认重置' }}
+            </button>
+          </div>
+        </div>
+      </div>
+    </section>
   </div>
 </template>
 
@@ -469,6 +528,7 @@ import AvatarUpload from '../components/AvatarUpload.vue';
 import CustomAvatarRow from '../components/CustomAvatarRow.vue';
 import QRCode from 'qrcode';
 import { usePlayerStore } from '../stores/player.js';
+import { useSession } from '../composables/useSession.js';
 
 const store = usePlayerStore();
 
@@ -841,11 +901,113 @@ async function updateProfile(botId: string, key: keyof ProfileConfig, value: boo
   }
 }
 
+// --- User Management ---
+const session = useSession();
+
+interface UserListEntry { id: string; username: string; createdAt: number }
+const userList = ref<UserListEntry[]>([]);
+const userLoadError = ref('');
+const userMutationError = ref('');
+const newUser = reactive({ username: '', password: '' });
+const creatingUser = ref(false);
+const resetTarget = ref<UserListEntry | null>(null);
+const resetPassword = ref('');
+const resetError = ref('');
+const resettingPw = ref(false);
+
+async function loadUsers() {
+  userLoadError.value = '';
+  try {
+    const res = await fetch('/api/users');
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const body = await res.json();
+    userList.value = body.users ?? [];
+  } catch (e) {
+    userLoadError.value = (e as Error).message;
+  }
+}
+
+async function onCreateUser() {
+  userMutationError.value = '';
+  creatingUser.value = true;
+  try {
+    const res = await fetch('/api/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username: newUser.username, password: newUser.password }),
+    });
+    if (!res.ok) {
+      const b = await res.json().catch(() => ({}));
+      throw new Error(b.error ?? `HTTP ${res.status}`);
+    }
+    newUser.username = '';
+    newUser.password = '';
+    await loadUsers();
+  } catch (e) {
+    userMutationError.value = (e as Error).message;
+  } finally {
+    creatingUser.value = false;
+  }
+}
+
+async function onDeleteUser(u: UserListEntry) {
+  if (!confirm(`确认删除用户 ${u.username}？`)) return;
+  userMutationError.value = '';
+  try {
+    const res = await fetch(`/api/users/${u.id}`, { method: 'DELETE' });
+    if (!res.ok && res.status !== 204) {
+      const b = await res.json().catch(() => ({}));
+      throw new Error(b.error ?? `HTTP ${res.status}`);
+    }
+    await loadUsers();
+  } catch (e) {
+    userMutationError.value = (e as Error).message;
+  }
+}
+
+function openResetPassword(u: UserListEntry) {
+  resetTarget.value = u;
+  resetPassword.value = '';
+  resetError.value = '';
+}
+
+async function onConfirmReset() {
+  if (!resetTarget.value) return;
+  if (resetPassword.value.length < 8) {
+    resetError.value = '密码至少 8 位';
+    return;
+  }
+  resettingPw.value = true;
+  resetError.value = '';
+  try {
+    const res = await fetch(`/api/users/${resetTarget.value.id}/reset-password`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ newPassword: resetPassword.value }),
+    });
+    if (!res.ok && res.status !== 204) {
+      const b = await res.json().catch(() => ({}));
+      throw new Error(b.error ?? `HTTP ${res.status}`);
+    }
+    resetTarget.value = null;
+  } catch (e) {
+    resetError.value = (e as Error).message;
+  } finally {
+    resettingPw.value = false;
+  }
+}
+
+function formatDate(ms: number): string {
+  const d = new Date(ms);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
 onMounted(() => {
   store.fetchBots(); // Refresh bot status on page visit
   checkAuthStatus();
   loadQuality();
   loadIdleTimeout();
+  loadUsers();
 });
 
 onUnmounted(() => {
@@ -1467,4 +1629,27 @@ onUnmounted(() => {
     }
   }
 }
+
+// --- User Management ---
+.user-list { display: flex; flex-direction: column; gap: 8px; }
+.user-item {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 12px; background: var(--bg-secondary); border-radius: var(--radius-sm);
+}
+.user-info { display: flex; flex-direction: column; gap: 4px; }
+.user-name { font-weight: 500; color: var(--text-primary); display: flex; align-items: center; gap: 8px; }
+.user-self-badge {
+  font-size: 11px; padding: 2px 6px; border-radius: 4px;
+  background: var(--color-primary); color: #fff;
+}
+.user-created { font-size: 12px; color: var(--text-secondary); }
+.user-actions { display: flex; gap: 8px; }
+.user-add-form {
+  display: flex; gap: 8px; margin-top: 12px; flex-wrap: wrap;
+}
+.user-add-form .input { flex: 1; min-width: 140px; }
+.user-empty, .user-error { font-size: 12px; color: var(--text-secondary); padding: 8px 0; }
+.user-error { color: #e26a6a; }
+.modal-hint { color: var(--text-secondary); font-size: 12px; margin: 0 0 8px; }
+.form-actions { display: flex; gap: 8px; justify-content: flex-end; margin-top: 8px; }
 </style>

From ceb24595e69da10fec227a874875b98c5b51fc6c Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 14:54:19 +0800
Subject: [PATCH 24/35] fix(auth): race-safe first-run setup + rolling cookie
 max-age refresh

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/data/users.test.ts                 | 20 ++++++++++++++++++++
 src/data/users.ts                      | 21 +++++++++++++++++++++
 src/web/api/session.ts                 | 15 ++++++++-------
 src/web/auth/validateSession.ts        |  5 +++++
 src/web/middleware/requireAuth.test.ts | 12 ++++++++++++
 src/web/middleware/requireAuth.ts      | 17 ++++++++++++++++-
 6 files changed, 82 insertions(+), 8 deletions(-)

diff --git a/src/data/users.test.ts b/src/data/users.test.ts
index 65fc7f1..e89e52e 100644
--- a/src/data/users.test.ts
+++ b/src/data/users.test.ts
@@ -72,4 +72,24 @@ describe("UserStore", () => {
     expect(users.countUsers()).toBe(0);
     expect(users.deleteUser("not-a-real-id")).toBe(false);
   });
+
+  it("createFirstUser succeeds on empty db, returns null when a user already exists", async () => {
+    const a = await users.createFirstUser("alice", "pw-alice");
+    expect(a).not.toBeNull();
+    expect(a!.username).toBe("alice");
+    const b = await users.createFirstUser("bob", "pw-bob-bob");
+    expect(b).toBeNull();
+    expect(users.countUsers()).toBe(1);
+  });
+
+  it("createFirstUser is race-safe: concurrent calls produce exactly one user", async () => {
+    const [a, b, c] = await Promise.all([
+      users.createFirstUser("alice", "pw-alice"),
+      users.createFirstUser("bob", "pw-bob-bob"),
+      users.createFirstUser("charlie", "pw-charlie-pw"),
+    ]);
+    const created = [a, b, c].filter((u) => u !== null);
+    expect(created).toHaveLength(1);
+    expect(users.countUsers()).toBe(1);
+  });
 });
diff --git a/src/data/users.ts b/src/data/users.ts
index 42e9450..c7becc7 100644
--- a/src/data/users.ts
+++ b/src/data/users.ts
@@ -15,6 +15,7 @@ export interface UserRow {
 export interface UserStore {
   countUsers(): number;
   createUser(username: string, password: string): Promise<UserRow>;
+  createFirstUser(username: string, password: string): Promise<UserRow | null>;
   findByUsername(username: string): UserRow | null;
   findById(id: string): UserRow | null;
   verifyPassword(plain: string, hash: string): Promise<boolean>;
@@ -69,6 +70,26 @@ export function createUserStore(db: Database.Database): UserStore {
       return { id, username, passwordHash: hash, createdAt: now, updatedAt: now };
     },
 
+    async createFirstUser(username, password) {
+      const hash = await bcrypt.hash(password, BCRYPT_ROUNDS);
+      const id = randomUUID();
+      const now = Date.now();
+      const run = db.transaction(() => {
+        const count = (countStmt.get() as { n: number }).n;
+        if (count !== 0) return null;
+        try {
+          insertStmt.run(id, username, hash, now, now);
+        } catch (err) {
+          if (err && typeof err === "object" && (err as { code?: string }).code === "SQLITE_CONSTRAINT_UNIQUE") {
+            return null;
+          }
+          throw err;
+        }
+        return { id, username, passwordHash: hash, createdAt: now, updatedAt: now } as UserRow;
+      });
+      return run();
+    },
+
     findByUsername(username) {
       return (findByUsernameStmt.get(username) as UserRow | undefined) ?? null;
     },
diff --git a/src/web/api/session.ts b/src/web/api/session.ts
index 9f302ce..5c00bbb 100644
--- a/src/web/api/session.ts
+++ b/src/web/api/session.ts
@@ -2,10 +2,9 @@ import { Router } from "express";
 import type { Request, Response, NextFunction } from "express";
 import type { Logger } from "../../logger.js";
 import type { UserStore } from "../../data/users.js";
-import { UsernameTakenError } from "../../data/users.js";
 import type { SessionStore } from "../../data/sessions.js";
 import { SESSION_TTL_MS } from "../../data/sessions.js";
-import { SESSION_COOKIE_NAME, validateSessionFromHeaders } from "../auth/validateSession.js";
+import { SESSION_COOKIE_NAME, validateSessionFromHeaders, extractSessionToken } from "../auth/validateSession.js";
 
 const FAILED_LOGIN_DELAY_MS = 250;
 
@@ -60,6 +59,8 @@ export function createSessionRouter(
       return;
     }
     req.user = { id: result.userId, username: result.username };
+    const token = extractSessionToken(req.headers.cookie);
+    if (token) setSessionCookie(res, token);
     next();
   };
 
@@ -78,16 +79,16 @@ export function createSessionRouter(
       return;
     }
     try {
-      const user = await users.createUser(username, password);
+      const user = await users.createFirstUser(username, password);
+      if (!user) {
+        res.status(409).json({ error: "already initialized" });
+        return;
+      }
       const { token } = sessions.createSession(user.id);
       setSessionCookie(res, token);
       logger.info({ userId: user.id, username }, "First admin created");
       res.json({ id: user.id, username: user.username });
     } catch (err) {
-      if (err instanceof UsernameTakenError) {
-        res.status(409).json({ error: "already initialized" });
-        return;
-      }
       logger.error({ err }, "setup failed");
       res.status(500).json({ error: "internal" });
     }
diff --git a/src/web/auth/validateSession.ts b/src/web/auth/validateSession.ts
index 4a00cb2..0d50850 100644
--- a/src/web/auth/validateSession.ts
+++ b/src/web/auth/validateSession.ts
@@ -17,6 +17,11 @@ export function validateSessionFromHeaders(
   return sessions.validateAndTouch(token);
 }
 
+export function extractSessionToken(rawCookieHeader: string | undefined): string | null {
+  if (!rawCookieHeader) return null;
+  return parseCookie(rawCookieHeader, SESSION_COOKIE_NAME);
+}
+
 function parseCookie(header: string, name: string): string | null {
   for (const part of header.split(";")) {
     const trimmed = part.trim();
diff --git a/src/web/middleware/requireAuth.test.ts b/src/web/middleware/requireAuth.test.ts
index 644ecb3..c5c37a1 100644
--- a/src/web/middleware/requireAuth.test.ts
+++ b/src/web/middleware/requireAuth.test.ts
@@ -53,4 +53,16 @@ describe("requireAuth middleware", () => {
     expect(res.body.ok).toBe(true);
     expect(res.body.user.username).toBe("alice");
   });
+
+  it("rolls the cookie max-age forward on successful auth", async () => {
+    const res = await request(app)
+      .get("/protected")
+      .set("Cookie", `${SESSION_COOKIE_NAME}=${validToken}`);
+    expect(res.status).toBe(200);
+    const setCookieHeaders = res.headers["set-cookie"];
+    const arr = Array.isArray(setCookieHeaders) ? setCookieHeaders : setCookieHeaders ? [setCookieHeaders] : [];
+    const refreshed = arr.find((c) => c.startsWith(`${SESSION_COOKIE_NAME}=`));
+    expect(refreshed).toBeDefined();
+    expect(refreshed!).toMatch(/Max-Age=\d+/);
+  });
 });
diff --git a/src/web/middleware/requireAuth.ts b/src/web/middleware/requireAuth.ts
index e674a28..8ec67bd 100644
--- a/src/web/middleware/requireAuth.ts
+++ b/src/web/middleware/requireAuth.ts
@@ -1,6 +1,11 @@
 import type { Request, Response, NextFunction, RequestHandler } from "express";
 import type { SessionStore } from "../../data/sessions.js";
-import { validateSessionFromHeaders, SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+import { SESSION_TTL_MS } from "../../data/sessions.js";
+import {
+  validateSessionFromHeaders,
+  extractSessionToken,
+  SESSION_COOKIE_NAME,
+} from "../auth/validateSession.js";
 
 declare module "express-serve-static-core" {
   interface Request {
@@ -17,6 +22,16 @@ export function createRequireAuth(sessions: SessionStore): RequestHandler {
       return;
     }
     req.user = { id: result.userId, username: result.username };
+    const token = extractSessionToken(req.headers.cookie);
+    if (token) {
+      res.cookie(SESSION_COOKIE_NAME, token, {
+        httpOnly: true,
+        sameSite: "lax",
+        secure: req.secure,
+        path: "/",
+        maxAge: SESSION_TTL_MS,
+      });
+    }
     next();
   };
 }

From 6af0e97f511a07e2ef9c65c1892bf34365726aef Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 15:04:19 +0800
Subject: [PATCH 25/35] feat(auth): user-management audit log (table + record
 sites + /api/audit endpoint)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/data/audit.test.ts      | 58 +++++++++++++++++++++++++++++++++++++
 src/data/audit.ts           | 56 +++++++++++++++++++++++++++++++++++
 src/data/database.test.ts   |  7 +++++
 src/data/database.ts        | 11 +++++++
 src/web/api/audit.test.ts   | 56 +++++++++++++++++++++++++++++++++++
 src/web/api/audit.ts        | 18 ++++++++++++
 src/web/api/session.test.ts |  8 +++--
 src/web/api/session.ts      | 12 ++++++++
 src/web/api/users.test.ts   |  8 +++--
 src/web/api/users.ts        | 22 ++++++++++++++
 src/web/server.ts           |  8 +++--
 11 files changed, 256 insertions(+), 8 deletions(-)
 create mode 100644 src/data/audit.test.ts
 create mode 100644 src/data/audit.ts
 create mode 100644 src/web/api/audit.test.ts
 create mode 100644 src/web/api/audit.ts

diff --git a/src/data/audit.test.ts b/src/data/audit.test.ts
new file mode 100644
index 0000000..6714afc
--- /dev/null
+++ b/src/data/audit.test.ts
@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createDatabase, type BotDatabase } from "./database.js";
+import { createAuditStore, type AuditStore } from "./audit.js";
+
+describe("AuditStore", () => {
+  let botDb: BotDatabase;
+  let audit: AuditStore;
+
+  beforeEach(() => {
+    botDb = createDatabase(":memory:");
+    audit = createAuditStore(botDb.db);
+  });
+
+  afterEach(() => botDb.close());
+
+  it("records and lists entries newest-first", async () => {
+    audit.record({
+      actorId: "a1", actorUsername: "alice",
+      targetUserId: "b1", targetUsername: "bob",
+      action: "user.created",
+    });
+    await new Promise((r) => setTimeout(r, 5));
+    audit.record({
+      actorId: "a1", actorUsername: "alice",
+      targetUserId: "b1", targetUsername: "bob",
+      action: "user.deleted",
+    });
+    const list = audit.list(10, 0);
+    expect(list).toHaveLength(2);
+    expect(list[0].action).toBe("user.deleted");
+    expect(list[1].action).toBe("user.created");
+  });
+
+  it("supports limit and offset", () => {
+    for (let i = 0; i < 5; i++) {
+      audit.record({
+        actorId: "a1", actorUsername: "alice",
+        targetUserId: null, targetUsername: null,
+        action: "user.password_changed",
+      });
+    }
+    expect(audit.list(2, 0)).toHaveLength(2);
+    expect(audit.list(2, 4)).toHaveLength(1);
+    expect(audit.list(10, 10)).toHaveLength(0);
+  });
+
+  it("stores nullable fields correctly", () => {
+    audit.record({
+      actorId: null, actorUsername: null,
+      targetUserId: "x", targetUsername: "deleted-user",
+      action: "admin.first_created",
+    });
+    const e = audit.list(1, 0)[0];
+    expect(e.actorId).toBeNull();
+    expect(e.actorUsername).toBeNull();
+    expect(e.targetUserId).toBe("x");
+  });
+});
diff --git a/src/data/audit.ts b/src/data/audit.ts
new file mode 100644
index 0000000..4e639de
--- /dev/null
+++ b/src/data/audit.ts
@@ -0,0 +1,56 @@
+import type Database from "better-sqlite3";
+
+export type AuditAction =
+  | "admin.first_created"
+  | "user.created"
+  | "user.deleted"
+  | "user.password_reset"
+  | "user.password_changed";
+
+export interface AuditEntry {
+  id: number;
+  timestamp: number;
+  actorId: string | null;
+  actorUsername: string | null;
+  targetUserId: string | null;
+  targetUsername: string | null;
+  action: AuditAction;
+}
+
+export interface AuditRecordInput {
+  actorId: string | null;
+  actorUsername: string | null;
+  targetUserId: string | null;
+  targetUsername: string | null;
+  action: AuditAction;
+}
+
+export interface AuditStore {
+  record(input: AuditRecordInput): void;
+  list(limit: number, offset: number): AuditEntry[];
+}
+
+export function createAuditStore(db: Database.Database): AuditStore {
+  const insertStmt = db.prepare(
+    "INSERT INTO user_audit (timestamp, actorId, actorUsername, targetUserId, targetUsername, action) VALUES (?, ?, ?, ?, ?, ?)"
+  );
+  const listStmt = db.prepare(
+    "SELECT id, timestamp, actorId, actorUsername, targetUserId, targetUsername, action FROM user_audit ORDER BY timestamp DESC, id DESC LIMIT ? OFFSET ?"
+  );
+
+  return {
+    record(input) {
+      insertStmt.run(
+        Date.now(),
+        input.actorId,
+        input.actorUsername,
+        input.targetUserId,
+        input.targetUsername,
+        input.action
+      );
+    },
+    list(limit, offset) {
+      return listStmt.all(limit, offset) as AuditEntry[];
+    },
+  };
+}
diff --git a/src/data/database.test.ts b/src/data/database.test.ts
index ad32b43..90436b8 100644
--- a/src/data/database.test.ts
+++ b/src/data/database.test.ts
@@ -40,6 +40,13 @@ describe("database", () => {
     expect(sessionColNames).toEqual(["createdAt", "expiresAt", "id", "lastSeenAt", "userId"]);
   });
 
+  it("creates user_audit table on init", () => {
+    const tables = botDb.db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+      .all() as Array<{ name: string }>;
+    expect(tables.map((t) => t.name)).toContain("user_audit");
+  });
+
   it("records and retrieves play history", () => {
     botDb.addPlayHistory({
       botId: "bot1",
diff --git a/src/data/database.ts b/src/data/database.ts
index 7dd79da..8d9fcf3 100644
--- a/src/data/database.ts
+++ b/src/data/database.ts
@@ -147,6 +147,17 @@ function initTables(db: Database.Database): void {
 
     CREATE INDEX IF NOT EXISTS idx_sessions_userId ON sessions(userId);
     CREATE INDEX IF NOT EXISTS idx_sessions_expiresAt ON sessions(expiresAt);
+
+    CREATE TABLE IF NOT EXISTS user_audit (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      timestamp INTEGER NOT NULL,
+      actorId TEXT,
+      actorUsername TEXT,
+      targetUserId TEXT,
+      targetUsername TEXT,
+      action TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_user_audit_timestamp ON user_audit(timestamp DESC);
   `);
 }
 
diff --git a/src/web/api/audit.test.ts b/src/web/api/audit.test.ts
new file mode 100644
index 0000000..90e27f9
--- /dev/null
+++ b/src/web/api/audit.test.ts
@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore } from "../../data/users.js";
+import { createSessionStore } from "../../data/sessions.js";
+import { createAuditStore } from "../../data/audit.js";
+import { createRequireAuth } from "../middleware/requireAuth.js";
+import { createAuditRouter } from "./audit.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+describe("audit router", () => {
+  let botDb: BotDatabase;
+  let app: express.Express;
+  let cookie: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const audit = createAuditStore(botDb.db);
+    const alice = await users.createUser("alice", "pw-alice");
+    cookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(alice.id).token}`;
+    for (let i = 0; i < 3; i++) {
+      audit.record({
+        actorId: alice.id, actorUsername: "alice",
+        targetUserId: "x", targetUsername: "x",
+        action: "user.created",
+      });
+    }
+    app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use("/api", createRequireAuth(sessions));
+    app.use("/api/audit", createAuditRouter(audit));
+  });
+
+  afterEach(() => botDb.close());
+
+  it("requires auth", async () => {
+    const res = await request(app).get("/api/audit");
+    expect(res.status).toBe(401);
+  });
+
+  it("returns entries newest-first", async () => {
+    const res = await request(app).get("/api/audit").set("Cookie", cookie);
+    expect(res.status).toBe(200);
+    expect(res.body.entries).toHaveLength(3);
+  });
+
+  it("honors limit query param", async () => {
+    const res = await request(app).get("/api/audit?limit=1").set("Cookie", cookie);
+    expect(res.body.entries).toHaveLength(1);
+  });
+});
diff --git a/src/web/api/audit.ts b/src/web/api/audit.ts
new file mode 100644
index 0000000..549454e
--- /dev/null
+++ b/src/web/api/audit.ts
@@ -0,0 +1,18 @@
+import { Router } from "express";
+import type { AuditStore } from "../../data/audit.js";
+
+export function createAuditRouter(audit: AuditStore): Router {
+  const router = Router();
+  router.get("/", (req, res) => {
+    const limit = clampInt(req.query.limit, 1, 500, 100);
+    const offset = clampInt(req.query.offset, 0, 100_000, 0);
+    res.json({ entries: audit.list(limit, offset) });
+  });
+  return router;
+}
+
+function clampInt(v: unknown, min: number, max: number, def: number): number {
+  const n = typeof v === "string" ? parseInt(v, 10) : NaN;
+  if (!Number.isFinite(n)) return def;
+  return Math.min(Math.max(n, min), max);
+}
diff --git a/src/web/api/session.test.ts b/src/web/api/session.test.ts
index 6545e73..b01f4ea 100644
--- a/src/web/api/session.test.ts
+++ b/src/web/api/session.test.ts
@@ -6,14 +6,16 @@ import pino from "pino";
 import { createDatabase, type BotDatabase } from "../../data/database.js";
 import { createUserStore, type UserStore } from "../../data/users.js";
 import { createSessionStore, type SessionStore } from "../../data/sessions.js";
+import { createAuditStore } from "../../data/audit.js";
 import { createSessionRouter } from "./session.js";
 import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
 
-function makeApp(users: UserStore, sessions: SessionStore) {
+function makeApp(botDb: BotDatabase, users: UserStore, sessions: SessionStore) {
   const app = express();
   app.use(express.json());
   app.use(cookieParser());
-  app.use("/api/session", createSessionRouter(users, sessions, pino({ level: "silent" })));
+  const audit = createAuditStore(botDb.db);
+  app.use("/api/session", createSessionRouter(users, sessions, audit, pino({ level: "silent" })));
   return app;
 }
 
@@ -35,7 +37,7 @@ describe("session router", () => {
     botDb = createDatabase(":memory:");
     users = createUserStore(botDb.db);
     sessions = createSessionStore(botDb.db);
-    app = makeApp(users, sessions);
+    app = makeApp(botDb, users, sessions);
   });
 
   afterEach(() => botDb.close());
diff --git a/src/web/api/session.ts b/src/web/api/session.ts
index 5c00bbb..d45811f 100644
--- a/src/web/api/session.ts
+++ b/src/web/api/session.ts
@@ -3,6 +3,7 @@ import type { Request, Response, NextFunction } from "express";
 import type { Logger } from "../../logger.js";
 import type { UserStore } from "../../data/users.js";
 import type { SessionStore } from "../../data/sessions.js";
+import type { AuditStore } from "../../data/audit.js";
 import { SESSION_TTL_MS } from "../../data/sessions.js";
 import { SESSION_COOKIE_NAME, validateSessionFromHeaders, extractSessionToken } from "../auth/validateSession.js";
 
@@ -47,6 +48,7 @@ function parseTokenFromCookie(cookieHeader: string | undefined): string | null {
 export function createSessionRouter(
   users: UserStore,
   sessions: SessionStore,
+  audit: AuditStore,
   logger: Logger
 ): Router {
   const router = Router();
@@ -86,6 +88,11 @@ export function createSessionRouter(
       }
       const { token } = sessions.createSession(user.id);
       setSessionCookie(res, token);
+      audit.record({
+        actorId: user.id, actorUsername: user.username,
+        targetUserId: user.id, targetUsername: user.username,
+        action: "admin.first_created",
+      });
       logger.info({ userId: user.id, username }, "First admin created");
       res.json({ id: user.id, username: user.username });
     } catch (err) {
@@ -144,6 +151,11 @@ export function createSessionRouter(
     await users.changePassword(u.id, newPassword);
     const currentToken = parseTokenFromCookie(req.headers.cookie);
     sessions.deleteAllForUser(u.id, currentToken ?? undefined);
+    audit.record({
+      actorId: u.id, actorUsername: u.username,
+      targetUserId: u.id, targetUsername: u.username,
+      action: "user.password_changed",
+    });
     res.status(204).end();
   });
 
diff --git a/src/web/api/users.test.ts b/src/web/api/users.test.ts
index 63b0c92..b9c9744 100644
--- a/src/web/api/users.test.ts
+++ b/src/web/api/users.test.ts
@@ -6,17 +6,19 @@ import pino from "pino";
 import { createDatabase, type BotDatabase } from "../../data/database.js";
 import { createUserStore, type UserStore } from "../../data/users.js";
 import { createSessionStore, type SessionStore } from "../../data/sessions.js";
+import { createAuditStore } from "../../data/audit.js";
 import { createRequireAuth } from "../middleware/requireAuth.js";
 import { createUsersRouter } from "./users.js";
 import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
 
-function makeApp(users: UserStore, sessions: SessionStore) {
+function makeApp(botDb: BotDatabase, users: UserStore, sessions: SessionStore) {
   const app = express();
   app.use(express.json());
   app.use(cookieParser());
   const requireAuth = createRequireAuth(sessions);
+  const audit = createAuditStore(botDb.db);
   app.use("/api", requireAuth);
-  app.use("/api/users", createUsersRouter(users, sessions, pino({ level: "silent" })));
+  app.use("/api/users", createUsersRouter(users, sessions, audit, pino({ level: "silent" })));
   return app;
 }
 
@@ -33,7 +35,7 @@ describe("users router", () => {
     botDb = createDatabase(":memory:");
     users = createUserStore(botDb.db);
     sessions = createSessionStore(botDb.db);
-    app = makeApp(users, sessions);
+    app = makeApp(botDb, users, sessions);
     const alice = await users.createUser("alice", "pw-alice");
     aliceId = alice.id;
     aliceCookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(alice.id).token}`;
diff --git a/src/web/api/users.ts b/src/web/api/users.ts
index b837e77..79e89dc 100644
--- a/src/web/api/users.ts
+++ b/src/web/api/users.ts
@@ -3,6 +3,7 @@ import type { Logger } from "../../logger.js";
 import type { UserStore } from "../../data/users.js";
 import { UsernameTakenError } from "../../data/users.js";
 import type { SessionStore } from "../../data/sessions.js";
+import type { AuditStore } from "../../data/audit.js";
 
 function isValidUsername(v: unknown): v is string {
   return typeof v === "string" && /^[A-Za-z0-9_\-.]{3,32}$/.test(v);
@@ -15,6 +16,7 @@ function isValidPassword(v: unknown): v is string {
 export function createUsersRouter(
   users: UserStore,
   sessions: SessionStore,
+  audit: AuditStore,
   logger: Logger
 ): Router {
   const router = Router();
@@ -31,6 +33,11 @@ export function createUsersRouter(
     }
     try {
       const u = await users.createUser(username, password);
+      audit.record({
+        actorId: req.user!.id, actorUsername: req.user!.username,
+        targetUserId: u.id, targetUsername: u.username,
+        action: "user.created",
+      });
       logger.info({ createdBy: req.user!.id, newUserId: u.id, username }, "User created");
       res.status(201).json({ id: u.id, username: u.username });
     } catch (err) {
@@ -45,6 +52,11 @@ export function createUsersRouter(
 
   router.delete("/:id", (req, res) => {
     const targetId = req.params.id;
+    const target = users.findById(targetId);
+    if (!target) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
     if (targetId === req.user!.id) {
       res.status(400).json({ error: "cannot delete self" });
       return;
@@ -55,6 +67,11 @@ export function createUsersRouter(
       return;
     }
     sessions.deleteAllForUser(targetId);
+    audit.record({
+      actorId: req.user!.id, actorUsername: req.user!.username,
+      targetUserId: target.id, targetUsername: target.username,
+      action: "user.deleted",
+    });
     logger.info({ deletedBy: req.user!.id, deletedUserId: targetId }, "User deleted");
     res.status(204).end();
   });
@@ -75,6 +92,11 @@ export function createUsersRouter(
     // Invalidate all sessions for the target user (except current actor's if it's the same user)
     const exceptToken = targetId === req.user!.id ? undefined : undefined;
     sessions.deleteAllForUser(targetId, exceptToken);
+    audit.record({
+      actorId: req.user!.id, actorUsername: req.user!.username,
+      targetUserId: target.id, targetUsername: target.username,
+      action: "user.password_reset",
+    });
     logger.info({ resetBy: req.user!.id, targetUserId: targetId }, "Password reset");
     res.status(204).end();
   });
diff --git a/src/web/server.ts b/src/web/server.ts
index 1424f46..d596d72 100755
--- a/src/web/server.ts
+++ b/src/web/server.ts
@@ -16,6 +16,8 @@ import { createPlayerRouter } from "./api/player.js";
 import { createAuthRouter } from "./api/auth.js";
 import { createSessionRouter } from "./api/session.js";
 import { createUsersRouter } from "./api/users.js";
+import { createAuditStore } from "../data/audit.js";
+import { createAuditRouter } from "./api/audit.js";
 import { setupWebSocket } from "./websocket.js";
 import { createUserStore } from "../data/users.js";
 import { createSessionStore } from "../data/sessions.js";
@@ -59,6 +61,7 @@ export function createWebServer(options: WebServerOptions): WebServer {
 
   const users = createUserStore(options.database.db);
   const sessions = createSessionStore(options.database.db);
+  const audit = createAuditStore(options.database.db);
 
   // ─── Public routes (no auth, no CSRF) ───────────────────────────────────
   app.get("/api/health", (_req, res) => {
@@ -70,7 +73,7 @@ export function createWebServer(options: WebServerOptions): WebServer {
     res.json({ publicUrl: raw ? raw.replace(/\/+$/, "") : null });
   });
 
-  app.use("/api/session", createSessionRouter(users, sessions, logger));
+  app.use("/api/session", createSessionRouter(users, sessions, audit, logger));
 
   // ─── Gates for everything else under /api ───────────────────────────────
   const requireAuth = createRequireAuth(sessions);
@@ -101,7 +104,8 @@ export function createWebServer(options: WebServerOptions): WebServer {
     "/api/auth",
     createAuthRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.cookieStore)
   );
-  app.use("/api/users", createUsersRouter(users, sessions, logger));
+  app.use("/api/users", createUsersRouter(users, sessions, audit, logger));
+  app.use("/api/audit", createAuditRouter(audit));
 
   // ─── Static SPA (public) ────────────────────────────────────────────────
   if (options.staticDir) {

From 7be4f13774b7347a9e2e7ba740a41cfa3c8b2676 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 15:06:54 +0800
Subject: [PATCH 26/35] feat(web): operation audit log section in Settings

---
 web/src/views/Settings.vue | 124 +++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)

diff --git a/web/src/views/Settings.vue b/web/src/views/Settings.vue
index 94aa393..032497e 100755
--- a/web/src/views/Settings.vue
+++ b/web/src/views/Settings.vue
@@ -517,6 +517,25 @@
         </div>
       </div>
     </section>
+
+    <!-- Audit Log -->
+    <section class="settings-section">
+      <h2 class="section-title">
+        操作审计
+        <button class="audit-refresh-btn" @click="loadAudit" :disabled="auditLoading" title="刷新">
+          <Icon icon="mdi:refresh" :class="{ spinning: auditLoading }" />
+        </button>
+      </h2>
+      <div v-if="auditLoadError" class="user-error">{{ auditLoadError }}</div>
+      <div v-else-if="auditEntries.length === 0 && !auditLoading" class="user-empty">暂无操作记录</div>
+      <div v-else class="audit-list">
+        <div v-for="e in auditEntries" :key="e.id" class="audit-row">
+          <div class="audit-time">{{ formatDateTime(e.timestamp) }}</div>
+          <div class="audit-actor">{{ e.actorUsername ?? '—' }}</div>
+          <div class="audit-action" :class="auditActionClass(e.action)">{{ describeAction(e) }}</div>
+        </div>
+      </div>
+    </section>
   </div>
 </template>
 
@@ -1002,12 +1021,67 @@ function formatDate(ms: number): string {
   return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
 }
 
+// --- Audit Log ---
+interface AuditEntry {
+  id: number;
+  timestamp: number;
+  actorId: string | null;
+  actorUsername: string | null;
+  targetUserId: string | null;
+  targetUsername: string | null;
+  action: string;
+}
+
+const auditEntries = ref<AuditEntry[]>([]);
+const auditLoadError = ref('');
+const auditLoading = ref(false);
+
+async function loadAudit() {
+  auditLoadError.value = '';
+  auditLoading.value = true;
+  try {
+    const res = await fetch('/api/audit?limit=100');
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const body = await res.json();
+    auditEntries.value = body.entries ?? [];
+  } catch (e) {
+    auditLoadError.value = (e as Error).message;
+  } finally {
+    auditLoading.value = false;
+  }
+}
+
+function formatDateTime(ms: number): string {
+  const d = new Date(ms);
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+function describeAction(e: AuditEntry): string {
+  const target = e.targetUsername ?? e.targetUserId ?? '—';
+  switch (e.action) {
+    case 'admin.first_created':     return `创建首位管理员 ${target}`;
+    case 'user.created':            return `创建用户 ${target}`;
+    case 'user.deleted':            return `删除用户 ${target}`;
+    case 'user.password_reset':     return `重置 ${target} 的密码`;
+    case 'user.password_changed':   return `修改自己的密码`;
+    default:                        return `${e.action} → ${target}`;
+  }
+}
+
+function auditActionClass(action: string): string {
+  if (action === 'user.deleted') return 'audit-action-danger';
+  if (action === 'user.password_reset' || action === 'user.password_changed') return 'audit-action-warn';
+  return 'audit-action-ok';
+}
+
 onMounted(() => {
   store.fetchBots(); // Refresh bot status on page visit
   checkAuthStatus();
   loadQuality();
   loadIdleTimeout();
   loadUsers();
+  loadAudit();
 });
 
 onUnmounted(() => {
@@ -1652,4 +1726,54 @@ onUnmounted(() => {
 .user-error { color: #e26a6a; }
 .modal-hint { color: var(--text-secondary); font-size: 12px; margin: 0 0 8px; }
 .form-actions { display: flex; gap: 8px; justify-content: flex-end; margin-top: 8px; }
+
+.audit-refresh-btn {
+  margin-left: 10px;
+  border: 0; background: transparent;
+  color: var(--text-secondary); cursor: pointer;
+  display: inline-flex; align-items: center;
+  font-size: 16px;
+  &:hover { color: var(--text-primary); }
+  &:disabled { opacity: 0.5; cursor: progress; }
+}
+.spinning { animation: spin 1s linear infinite; }
+@keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
+
+.audit-list {
+  display: flex; flex-direction: column;
+  border-radius: var(--radius-sm);
+  background: var(--bg-secondary);
+  max-height: 480px;
+  overflow-y: auto;
+}
+.audit-row {
+  display: grid;
+  grid-template-columns: 170px 120px 1fr;
+  gap: 12px;
+  padding: 10px 12px;
+  border-bottom: 1px solid var(--border-color);
+  font-size: 13px;
+  &:last-child { border-bottom: 0; }
+}
+.audit-time {
+  color: var(--text-secondary);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace;
+  font-size: 12px;
+  white-space: nowrap;
+}
+.audit-actor {
+  color: var(--text-primary);
+  font-weight: 500;
+}
+.audit-action { color: var(--text-primary); }
+.audit-action-ok      { color: var(--text-primary); }
+.audit-action-warn    { color: #d3a44b; }
+.audit-action-danger  { color: #e26a6a; }
+
+@media (max-width: 640px) {
+  .audit-row {
+    grid-template-columns: 1fr;
+    gap: 4px;
+  }
+}
 </style>

From b0b61f8fce851f8a1ea2c7b81ab7d789a5b3aff1 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 15:16:55 +0800
Subject: [PATCH 27/35] fix(auth): defensive audit-record + self-reset
 preserves current session

---
 src/web/api/session.ts    | 28 +++++++++++++--------
 src/web/api/users.test.ts | 52 +++++++++++++++++++++++++++++++++++++++
 src/web/api/users.ts      | 47 +++++++++++++++++++++++------------
 3 files changed, 101 insertions(+), 26 deletions(-)

diff --git a/src/web/api/session.ts b/src/web/api/session.ts
index d45811f..e595b89 100644
--- a/src/web/api/session.ts
+++ b/src/web/api/session.ts
@@ -88,11 +88,15 @@ export function createSessionRouter(
       }
       const { token } = sessions.createSession(user.id);
       setSessionCookie(res, token);
-      audit.record({
-        actorId: user.id, actorUsername: user.username,
-        targetUserId: user.id, targetUsername: user.username,
-        action: "admin.first_created",
-      });
+      try {
+        audit.record({
+          actorId: user.id, actorUsername: user.username,
+          targetUserId: user.id, targetUsername: user.username,
+          action: "admin.first_created",
+        });
+      } catch (auditErr) {
+        logger.warn({ err: auditErr, action: "admin.first_created" }, "audit insert failed");
+      }
       logger.info({ userId: user.id, username }, "First admin created");
       res.json({ id: user.id, username: user.username });
     } catch (err) {
@@ -151,11 +155,15 @@ export function createSessionRouter(
     await users.changePassword(u.id, newPassword);
     const currentToken = parseTokenFromCookie(req.headers.cookie);
     sessions.deleteAllForUser(u.id, currentToken ?? undefined);
-    audit.record({
-      actorId: u.id, actorUsername: u.username,
-      targetUserId: u.id, targetUsername: u.username,
-      action: "user.password_changed",
-    });
+    try {
+      audit.record({
+        actorId: u.id, actorUsername: u.username,
+        targetUserId: u.id, targetUsername: u.username,
+        action: "user.password_changed",
+      });
+    } catch (auditErr) {
+      logger.warn({ err: auditErr, action: "user.password_changed" }, "audit insert failed");
+    }
     res.status(204).end();
   });
 
diff --git a/src/web/api/users.test.ts b/src/web/api/users.test.ts
index b9c9744..f2d8742 100644
--- a/src/web/api/users.test.ts
+++ b/src/web/api/users.test.ts
@@ -137,4 +137,56 @@ describe("users router", () => {
       .send({ newPassword: "short" });
     expect(res.status).toBe(400);
   });
+
+  it("returns 201 even if audit insert fails (POST /api/users)", async () => {
+    // Build a broken audit store that throws on record()
+    const brokenAudit = {
+      record: () => { throw new Error("simulated disk-full"); },
+      list: () => [],
+    };
+    // Reassemble app with the broken audit
+    const localApp = express();
+    localApp.use(express.json());
+    localApp.use(cookieParser());
+    localApp.use("/api", createRequireAuth(sessions));
+    localApp.use(
+      "/api/users",
+      createUsersRouter(users, sessions, brokenAudit, pino({ level: "silent" }))
+    );
+    const res = await request(localApp)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "charlie", password: "charlie-pw" });
+    expect(res.status).toBe(201);
+    expect(users.countUsers()).toBe(3);
+  });
+
+  it("POST /:id/reset-password on self preserves the actor's current session", async () => {
+    // Alice resets her OWN password
+    const res = await request(app)
+      .post(`/api/users/${aliceId}/reset-password`)
+      .set("Cookie", aliceCookie)
+      .send({ newPassword: "alice-new-pw" });
+    expect(res.status).toBe(204);
+
+    // Alice's CURRENT session should still work
+    // (we'd need a protected endpoint to verify; use GET /api/users which is already mounted)
+    const followUp = await request(app).get("/api/users").set("Cookie", aliceCookie);
+    expect(followUp.status).toBe(200);
+
+    // The password hash IS updated (sanity check)
+    const alice = users.findById(aliceId);
+    expect(await users.verifyPassword("alice-new-pw", alice!.passwordHash)).toBe(true);
+  });
+
+  it("POST /:id/reset-password on another user does NOT preserve any of target's sessions", async () => {
+    const bobToken = sessions.createSession(bobId).token;
+    const res = await request(app)
+      .post(`/api/users/${bobId}/reset-password`)
+      .set("Cookie", aliceCookie)
+      .send({ newPassword: "bob-new-pw" });
+    expect(res.status).toBe(204);
+    // Bob's session should be dead
+    expect(sessions.validateAndTouch(bobToken)).toBeNull();
+  });
 });
diff --git a/src/web/api/users.ts b/src/web/api/users.ts
index 79e89dc..0204f16 100644
--- a/src/web/api/users.ts
+++ b/src/web/api/users.ts
@@ -4,6 +4,7 @@ import type { UserStore } from "../../data/users.js";
 import { UsernameTakenError } from "../../data/users.js";
 import type { SessionStore } from "../../data/sessions.js";
 import type { AuditStore } from "../../data/audit.js";
+import { extractSessionToken } from "../auth/validateSession.js";
 
 function isValidUsername(v: unknown): v is string {
   return typeof v === "string" && /^[A-Za-z0-9_\-.]{3,32}$/.test(v);
@@ -33,11 +34,15 @@ export function createUsersRouter(
     }
     try {
       const u = await users.createUser(username, password);
-      audit.record({
-        actorId: req.user!.id, actorUsername: req.user!.username,
-        targetUserId: u.id, targetUsername: u.username,
-        action: "user.created",
-      });
+      try {
+        audit.record({
+          actorId: req.user!.id, actorUsername: req.user!.username,
+          targetUserId: u.id, targetUsername: u.username,
+          action: "user.created",
+        });
+      } catch (auditErr) {
+        logger.warn({ err: auditErr, action: "user.created" }, "audit insert failed");
+      }
       logger.info({ createdBy: req.user!.id, newUserId: u.id, username }, "User created");
       res.status(201).json({ id: u.id, username: u.username });
     } catch (err) {
@@ -67,11 +72,15 @@ export function createUsersRouter(
       return;
     }
     sessions.deleteAllForUser(targetId);
-    audit.record({
-      actorId: req.user!.id, actorUsername: req.user!.username,
-      targetUserId: target.id, targetUsername: target.username,
-      action: "user.deleted",
-    });
+    try {
+      audit.record({
+        actorId: req.user!.id, actorUsername: req.user!.username,
+        targetUserId: target.id, targetUsername: target.username,
+        action: "user.deleted",
+      });
+    } catch (auditErr) {
+      logger.warn({ err: auditErr, action: "user.deleted" }, "audit insert failed");
+    }
     logger.info({ deletedBy: req.user!.id, deletedUserId: targetId }, "User deleted");
     res.status(204).end();
   });
@@ -90,13 +99,19 @@ export function createUsersRouter(
     }
     await users.changePassword(targetId, newPassword);
     // Invalidate all sessions for the target user (except current actor's if it's the same user)
-    const exceptToken = targetId === req.user!.id ? undefined : undefined;
+    const exceptToken = targetId === req.user!.id
+      ? (extractSessionToken(req.headers.cookie) ?? undefined)
+      : undefined;
     sessions.deleteAllForUser(targetId, exceptToken);
-    audit.record({
-      actorId: req.user!.id, actorUsername: req.user!.username,
-      targetUserId: target.id, targetUsername: target.username,
-      action: "user.password_reset",
-    });
+    try {
+      audit.record({
+        actorId: req.user!.id, actorUsername: req.user!.username,
+        targetUserId: target.id, targetUsername: target.username,
+        action: "user.password_reset",
+      });
+    } catch (auditErr) {
+      logger.warn({ err: auditErr, action: "user.password_reset" }, "audit insert failed");
+    }
     logger.info({ resetBy: req.user!.id, targetUserId: targetId }, "Password reset");
     res.status(204).end();
   });

From a73f797bcbcd8e9be60f48b04fe222bd3622ddac Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 15:35:15 +0800
Subject: [PATCH 28/35] feat(auth): two-role permission system (admin/member)

Adds an admin/member role to WebUI auth. /api/users and /api/audit
are now gated by a requireAdmin middleware; all other authenticated
endpoints accept both roles. Schema migration defaults all existing
users to admin to preserve access. POST /api/users defaults new users
to member; first-run setup always creates an admin. Adds PATCH
/api/users/:id/role with last-admin demotion and deletion guards.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/data/audit.ts                       |  3 +-
 src/data/database.test.ts               |  2 +-
 src/data/database.ts                    |  9 +++-
 src/data/sessions.test.ts               |  3 +-
 src/data/sessions.ts                    |  7 +--
 src/data/users.test.ts                  | 54 ++++++++++++++-----
 src/data/users.ts                       | 42 ++++++++++-----
 src/web/api/audit.test.ts               |  2 +-
 src/web/api/session.test.ts             | 26 +++++-----
 src/web/api/session.ts                  |  6 +--
 src/web/api/users.test.ts               | 69 ++++++++++++++++++++++++-
 src/web/api/users.ts                    | 51 ++++++++++++++++--
 src/web/middleware/requireAdmin.test.ts | 50 ++++++++++++++++++
 src/web/middleware/requireAdmin.ts      | 13 +++++
 src/web/middleware/requireAuth.test.ts  |  3 +-
 src/web/middleware/requireAuth.ts       |  4 +-
 src/web/server.ts                       |  6 ++-
 src/web/websocket-auth.test.ts          |  2 +-
 18 files changed, 292 insertions(+), 60 deletions(-)
 create mode 100644 src/web/middleware/requireAdmin.test.ts
 create mode 100644 src/web/middleware/requireAdmin.ts

diff --git a/src/data/audit.ts b/src/data/audit.ts
index 4e639de..6f48171 100644
--- a/src/data/audit.ts
+++ b/src/data/audit.ts
@@ -5,7 +5,8 @@ export type AuditAction =
   | "user.created"
   | "user.deleted"
   | "user.password_reset"
-  | "user.password_changed";
+  | "user.password_changed"
+  | "user.role_changed";
 
 export interface AuditEntry {
   id: number;
diff --git a/src/data/database.test.ts b/src/data/database.test.ts
index 90436b8..7fc96f0 100644
--- a/src/data/database.test.ts
+++ b/src/data/database.test.ts
@@ -33,7 +33,7 @@ describe("database", () => {
 
     const userCols = botDb.db.prepare("PRAGMA table_info(users)").all() as Array<{ name: string }>;
     const userColNames = userCols.map((c) => c.name).sort();
-    expect(userColNames).toEqual(["createdAt", "id", "passwordHash", "updatedAt", "username"]);
+    expect(userColNames).toEqual(["createdAt", "id", "passwordHash", "role", "updatedAt", "username"]);
 
     const sessionCols = botDb.db.prepare("PRAGMA table_info(sessions)").all() as Array<{ name: string }>;
     const sessionColNames = sessionCols.map((c) => c.name).sort();
diff --git a/src/data/database.ts b/src/data/database.ts
index 8d9fcf3..f911756 100644
--- a/src/data/database.ts
+++ b/src/data/database.ts
@@ -97,6 +97,12 @@ function migrateSchema(db: Database.Database): void {
   if (!names.includes("custom_avatar_path")) {
     db.exec("ALTER TABLE bot_instances ADD COLUMN custom_avatar_path TEXT");
   }
+
+  const userColumns = db.prepare("PRAGMA table_info(users)").all() as Array<{ name: string }>;
+  const userColNames = userColumns.map((c) => c.name);
+  if (!userColNames.includes("role")) {
+    db.exec("ALTER TABLE users ADD COLUMN role TEXT NOT NULL DEFAULT 'admin'");
+  }
 }
 
 function initTables(db: Database.Database): void {
@@ -133,7 +139,8 @@ function initTables(db: Database.Database): void {
       username TEXT NOT NULL UNIQUE COLLATE NOCASE,
       passwordHash TEXT NOT NULL,
       createdAt INTEGER NOT NULL,
-      updatedAt INTEGER NOT NULL
+      updatedAt INTEGER NOT NULL,
+      role TEXT NOT NULL DEFAULT 'admin'
     );
 
     CREATE TABLE IF NOT EXISTS sessions (
diff --git a/src/data/sessions.test.ts b/src/data/sessions.test.ts
index 376690b..f0a491a 100644
--- a/src/data/sessions.test.ts
+++ b/src/data/sessions.test.ts
@@ -18,7 +18,7 @@ describe("SessionStore", () => {
     botDb = createDatabase(":memory:");
     users = createUserStore(botDb.db);
     sessions = createSessionStore(botDb.db);
-    const u = await users.createUser("alice", "pw");
+    const u = await users.createUser("alice", "pw-alice", "admin");
     userId = u.id;
   });
 
@@ -40,6 +40,7 @@ describe("SessionStore", () => {
     expect(result).not.toBeNull();
     expect(result!.userId).toBe(userId);
     expect(result!.username).toBe("alice");
+    expect(result!.role).toBe("admin");
   });
 
   it("validateAndTouch returns null and deletes the row for an expired session", () => {
diff --git a/src/data/sessions.ts b/src/data/sessions.ts
index ce29c4f..106b3ae 100644
--- a/src/data/sessions.ts
+++ b/src/data/sessions.ts
@@ -7,6 +7,7 @@ export const SESSION_TOUCH_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 export interface SessionValidation {
   userId: string;
   username: string;
+  role: "admin" | "member";
 }
 
 export interface SessionStore {
@@ -26,7 +27,7 @@ export function createSessionStore(db: Database.Database): SessionStore {
     "INSERT INTO sessions (id, userId, createdAt, expiresAt, lastSeenAt) VALUES (?, ?, ?, ?, ?)"
   );
   const selectStmt = db.prepare(`
-    SELECT s.id, s.userId, s.expiresAt, s.lastSeenAt, u.username
+    SELECT s.id, s.userId, s.expiresAt, s.lastSeenAt, u.username, u.role
     FROM sessions s INNER JOIN users u ON u.id = s.userId
     WHERE s.id = ?
   `);
@@ -54,7 +55,7 @@ export function createSessionStore(db: Database.Database): SessionStore {
       if (!rawToken) return null;
       const id = hashToken(rawToken);
       const row = selectStmt.get(id) as
-        | { id: string; userId: string; expiresAt: number; lastSeenAt: number; username: string }
+        | { id: string; userId: string; expiresAt: number; lastSeenAt: number; username: string; role: string }
         | undefined;
       if (!row) return null;
       const now = Date.now();
@@ -65,7 +66,7 @@ export function createSessionStore(db: Database.Database): SessionStore {
       if (now - row.lastSeenAt > SESSION_TOUCH_INTERVAL_MS) {
         touchStmt.run(now, now + SESSION_TTL_MS, id);
       }
-      return { userId: row.userId, username: row.username };
+      return { userId: row.userId, username: row.username, role: row.role as "admin" | "member" };
     },
 
     deleteSession(rawToken) {
diff --git a/src/data/users.test.ts b/src/data/users.test.ts
index e89e52e..c365903 100644
--- a/src/data/users.test.ts
+++ b/src/data/users.test.ts
@@ -20,26 +20,26 @@ describe("UserStore", () => {
   });
 
   it("createUser stores the user and bumps countUsers", async () => {
-    const u = await users.createUser("alice", "pw-hunter2");
+    const u = await users.createUser("alice", "pw-hunter2", "member");
     expect(u.id).toMatch(/^[0-9a-f-]{36}$/);
     expect(u.username).toBe("alice");
     expect(users.countUsers()).toBe(1);
   });
 
   it("findByUsername is case-insensitive and returns null for missing", async () => {
-    await users.createUser("Alice", "pw");
+    await users.createUser("Alice", "pw-alice", "member");
     expect(users.findByUsername("ALICE")).not.toBeNull();
     expect(users.findByUsername("alice")).not.toBeNull();
     expect(users.findByUsername("bob")).toBeNull();
   });
 
   it("createUser rejects duplicate usernames (case-insensitive)", async () => {
-    await users.createUser("Alice", "pw");
-    await expect(users.createUser("alice", "pw2")).rejects.toBeInstanceOf(UsernameTakenError);
+    await users.createUser("Alice", "pw-alice", "member");
+    await expect(users.createUser("alice", "pw-alice-2", "member")).rejects.toBeInstanceOf(UsernameTakenError);
   });
 
   it("verifyPassword accepts correct password and rejects wrong one", async () => {
-    await users.createUser("alice", "correct-horse-battery-staple");
+    await users.createUser("alice", "correct-horse-battery-staple", "member");
     const row = users.findByUsername("alice");
     expect(row).not.toBeNull();
     expect(await users.verifyPassword("correct-horse-battery-staple", row!.passwordHash)).toBe(true);
@@ -47,16 +47,16 @@ describe("UserStore", () => {
   });
 
   it("changePassword updates the hash so the old password no longer verifies", async () => {
-    const u = await users.createUser("alice", "old");
-    await users.changePassword(u.id, "new");
+    const u = await users.createUser("alice", "old-pw-pw", "member");
+    await users.changePassword(u.id, "new-pw-pw");
     const row = users.findByUsername("alice");
-    expect(await users.verifyPassword("old", row!.passwordHash)).toBe(false);
-    expect(await users.verifyPassword("new", row!.passwordHash)).toBe(true);
+    expect(await users.verifyPassword("old-pw-pw", row!.passwordHash)).toBe(false);
+    expect(await users.verifyPassword("new-pw-pw", row!.passwordHash)).toBe(true);
   });
 
   it("listUsers returns id+username+createdAt ascending, no password hash", async () => {
-    await users.createUser("alice", "pw-alice");
-    await users.createUser("bob", "pw-bob");
+    await users.createUser("alice", "pw-alice", "member");
+    await users.createUser("bob", "pw-bob-bob", "member");
     const list = users.listUsers();
     expect(list).toHaveLength(2);
     expect(list[0].username).toBe("alice");
@@ -67,7 +67,7 @@ describe("UserStore", () => {
   });
 
   it("deleteUser removes the row and returns true; returns false for unknown id", async () => {
-    const u = await users.createUser("alice", "pw-alice");
+    const u = await users.createUser("alice", "pw-alice", "member");
     expect(users.deleteUser(u.id)).toBe(true);
     expect(users.countUsers()).toBe(0);
     expect(users.deleteUser("not-a-real-id")).toBe(false);
@@ -92,4 +92,34 @@ describe("UserStore", () => {
     expect(created).toHaveLength(1);
     expect(users.countUsers()).toBe(1);
   });
+
+  it("createFirstUser always creates an admin", async () => {
+    const u = await users.createFirstUser("alice", "pw-alice");
+    expect(u).not.toBeNull();
+    expect(u!.role).toBe("admin");
+  });
+
+  it("countAdmins reflects only role=admin", async () => {
+    await users.createUser("alice", "pw-alice", "admin");
+    await users.createUser("bob", "pw-bob-bob", "member");
+    expect(users.countUsers()).toBe(2);
+    expect(users.countAdmins()).toBe(1);
+  });
+
+  it("setRole changes the role and returns true; false for unknown id", async () => {
+    const u = await users.createUser("alice", "pw-alice", "member");
+    expect(users.setRole(u.id, "admin")).toBe(true);
+    expect(users.findById(u.id)!.role).toBe("admin");
+    expect(users.setRole("nope", "admin")).toBe(false);
+  });
+
+  it("listUsers includes role", async () => {
+    await users.createUser("alice", "pw-alice", "admin");
+    await users.createUser("bob", "pw-bob-bob", "member");
+    const list = users.listUsers();
+    const alice = list.find((u) => u.username === "alice")!;
+    const bob = list.find((u) => u.username === "bob")!;
+    expect(alice.role).toBe("admin");
+    expect(bob.role).toBe("member");
+  });
 });
diff --git a/src/data/users.ts b/src/data/users.ts
index c7becc7..1ad4728 100644
--- a/src/data/users.ts
+++ b/src/data/users.ts
@@ -4,24 +4,29 @@ import bcrypt from "bcryptjs";
 
 const BCRYPT_ROUNDS = 12;
 
+export type UserRole = "admin" | "member";
+
 export interface UserRow {
   id: string;
   username: string;
   passwordHash: string;
   createdAt: number;
   updatedAt: number;
+  role: UserRole;
 }
 
 export interface UserStore {
   countUsers(): number;
-  createUser(username: string, password: string): Promise<UserRow>;
+  countAdmins(): number;
+  createUser(username: string, password: string, role: UserRole): Promise<UserRow>;
   createFirstUser(username: string, password: string): Promise<UserRow | null>;
   findByUsername(username: string): UserRow | null;
   findById(id: string): UserRow | null;
   verifyPassword(plain: string, hash: string): Promise<boolean>;
   changePassword(userId: string, newPassword: string): Promise<void>;
-  listUsers(): Array<{ id: string; username: string; createdAt: number }>;
+  setRole(userId: string, role: UserRole): boolean;
   deleteUser(id: string): boolean;
+  listUsers(): Array<{ id: string; username: string; createdAt: number; role: UserRole }>;
 }
 
 export class UsernameTakenError extends Error {
@@ -33,20 +38,24 @@ export class UsernameTakenError extends Error {
 
 export function createUserStore(db: Database.Database): UserStore {
   const countStmt = db.prepare("SELECT COUNT(*) AS n FROM users");
+  const countAdminsStmt = db.prepare("SELECT COUNT(*) AS n FROM users WHERE role = 'admin'");
   const insertStmt = db.prepare(
-    "INSERT INTO users (id, username, passwordHash, createdAt, updatedAt) VALUES (?, ?, ?, ?, ?)"
+    "INSERT INTO users (id, username, passwordHash, createdAt, updatedAt, role) VALUES (?, ?, ?, ?, ?, ?)"
   );
   const findByUsernameStmt = db.prepare(
-    "SELECT id, username, passwordHash, createdAt, updatedAt FROM users WHERE username = ? COLLATE NOCASE"
+    "SELECT id, username, passwordHash, createdAt, updatedAt, role FROM users WHERE username = ? COLLATE NOCASE"
   );
   const findByIdStmt = db.prepare(
-    "SELECT id, username, passwordHash, createdAt, updatedAt FROM users WHERE id = ?"
+    "SELECT id, username, passwordHash, createdAt, updatedAt, role FROM users WHERE id = ?"
   );
   const updatePasswordStmt = db.prepare(
     "UPDATE users SET passwordHash = ?, updatedAt = ? WHERE id = ?"
   );
+  const updateRoleStmt = db.prepare(
+    "UPDATE users SET role = ?, updatedAt = ? WHERE id = ?"
+  );
   const listUsersStmt = db.prepare(
-    "SELECT id, username, createdAt FROM users ORDER BY createdAt ASC"
+    "SELECT id, username, createdAt, role FROM users ORDER BY createdAt ASC"
   );
   const deleteUserStmt = db.prepare("DELETE FROM users WHERE id = ?");
 
@@ -55,19 +64,23 @@ export function createUserStore(db: Database.Database): UserStore {
       return (countStmt.get() as { n: number }).n;
     },
 
-    async createUser(username, password) {
+    countAdmins() {
+      return (countAdminsStmt.get() as { n: number }).n;
+    },
+
+    async createUser(username, password, role) {
       const hash = await bcrypt.hash(password, BCRYPT_ROUNDS);
       const id = randomUUID();
       const now = Date.now();
       try {
-        insertStmt.run(id, username, hash, now, now);
+        insertStmt.run(id, username, hash, now, now, role);
       } catch (err) {
         if (err && typeof err === "object" && (err as { code?: string }).code === "SQLITE_CONSTRAINT_UNIQUE") {
           throw new UsernameTakenError(username);
         }
         throw err;
       }
-      return { id, username, passwordHash: hash, createdAt: now, updatedAt: now };
+      return { id, username, passwordHash: hash, createdAt: now, updatedAt: now, role };
     },
 
     async createFirstUser(username, password) {
@@ -78,14 +91,14 @@ export function createUserStore(db: Database.Database): UserStore {
         const count = (countStmt.get() as { n: number }).n;
         if (count !== 0) return null;
         try {
-          insertStmt.run(id, username, hash, now, now);
+          insertStmt.run(id, username, hash, now, now, "admin");
         } catch (err) {
           if (err && typeof err === "object" && (err as { code?: string }).code === "SQLITE_CONSTRAINT_UNIQUE") {
             return null;
           }
           throw err;
         }
-        return { id, username, passwordHash: hash, createdAt: now, updatedAt: now } as UserRow;
+        return { id, username, passwordHash: hash, createdAt: now, updatedAt: now, role: "admin" } as UserRow;
       });
       return run();
     },
@@ -107,8 +120,13 @@ export function createUserStore(db: Database.Database): UserStore {
       updatePasswordStmt.run(hash, Date.now(), userId);
     },
 
+    setRole(userId, role) {
+      const result = updateRoleStmt.run(role, Date.now(), userId);
+      return result.changes > 0;
+    },
+
     listUsers() {
-      return listUsersStmt.all() as Array<{ id: string; username: string; createdAt: number }>;
+      return listUsersStmt.all() as Array<{ id: string; username: string; createdAt: number; role: UserRole }>;
     },
 
     deleteUser(id) {
diff --git a/src/web/api/audit.test.ts b/src/web/api/audit.test.ts
index 90e27f9..5e65d48 100644
--- a/src/web/api/audit.test.ts
+++ b/src/web/api/audit.test.ts
@@ -20,7 +20,7 @@ describe("audit router", () => {
     const users = createUserStore(botDb.db);
     const sessions = createSessionStore(botDb.db);
     const audit = createAuditStore(botDb.db);
-    const alice = await users.createUser("alice", "pw-alice");
+    const alice = await users.createUser("alice", "pw-alice", "admin");
     cookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(alice.id).token}`;
     for (let i = 0; i < 3; i++) {
       audit.record({
diff --git a/src/web/api/session.test.ts b/src/web/api/session.test.ts
index b01f4ea..a46f081 100644
--- a/src/web/api/session.test.ts
+++ b/src/web/api/session.test.ts
@@ -61,7 +61,7 @@ describe("session router", () => {
   });
 
   it("POST /setup returns 409 once a user already exists", async () => {
-    await users.createUser("admin", "pw");
+    await users.createUser("admin", "pw-admin-pw", "admin");
     const res = await request(app)
       .post("/api/session/setup")
       .send({ username: "alice", password: "pw" });
@@ -70,7 +70,7 @@ describe("session router", () => {
   });
 
   it("POST /login returns 401 with constant-time delay on bad credentials", async () => {
-    await users.createUser("alice", "correct");
+    await users.createUser("alice", "correct-pw-pw", "admin");
     const start = Date.now();
     const res = await request(app)
       .post("/api/session/login")
@@ -81,20 +81,20 @@ describe("session router", () => {
   }, 10_000);
 
   it("POST /login sets a session cookie on success", async () => {
-    await users.createUser("alice", "pw");
+    await users.createUser("alice", "pw-alice", "admin");
     const res = await request(app)
       .post("/api/session/login")
-      .send({ username: "alice", password: "pw" });
+      .send({ username: "alice", password: "pw-alice" });
     expect(res.status).toBe(200);
     expect(res.body.username).toBe("alice");
     extractCookie(res);
   });
 
   it("GET /me returns the current user when cookie is present, 401 otherwise", async () => {
-    await users.createUser("alice", "pw");
+    await users.createUser("alice", "pw-alice", "admin");
     const loginRes = await request(app)
       .post("/api/session/login")
-      .send({ username: "alice", password: "pw" });
+      .send({ username: "alice", password: "pw-alice" });
     const cookie = extractCookie(loginRes);
 
     const me = await request(app).get("/api/session/me").set("Cookie", cookie);
@@ -106,10 +106,10 @@ describe("session router", () => {
   });
 
   it("POST /logout deletes the session and clears the cookie", async () => {
-    await users.createUser("alice", "pw");
+    await users.createUser("alice", "pw-alice", "admin");
     const loginRes = await request(app)
       .post("/api/session/login")
-      .send({ username: "alice", password: "pw" });
+      .send({ username: "alice", password: "pw-alice" });
     const cookie = extractCookie(loginRes);
 
     const logout = await request(app).post("/api/session/logout").set("Cookie", cookie);
@@ -120,24 +120,24 @@ describe("session router", () => {
   });
 
   it("POST /change-password requires old password and invalidates other sessions", async () => {
-    const u = await users.createUser("alice", "old");
+    const u = await users.createUser("alice", "old-pw-pw", "admin");
     const cookieA = extractCookie(
-      await request(app).post("/api/session/login").send({ username: "alice", password: "old" })
+      await request(app).post("/api/session/login").send({ username: "alice", password: "old-pw-pw" })
     );
     const cookieB = extractCookie(
-      await request(app).post("/api/session/login").send({ username: "alice", password: "old" })
+      await request(app).post("/api/session/login").send({ username: "alice", password: "old-pw-pw" })
     );
 
     const wrongOld = await request(app)
       .post("/api/session/change-password")
       .set("Cookie", cookieA)
-      .send({ oldPassword: "WRONG", newPassword: "new" });
+      .send({ oldPassword: "WRONG", newPassword: "newpassword" });
     expect(wrongOld.status).toBe(401);
 
     const ok = await request(app)
       .post("/api/session/change-password")
       .set("Cookie", cookieA)
-      .send({ oldPassword: "old", newPassword: "newpassword" });
+      .send({ oldPassword: "old-pw-pw", newPassword: "newpassword" });
     expect(ok.status).toBe(204);
 
     const meA = await request(app).get("/api/session/me").set("Cookie", cookieA);
diff --git a/src/web/api/session.ts b/src/web/api/session.ts
index e595b89..21e8721 100644
--- a/src/web/api/session.ts
+++ b/src/web/api/session.ts
@@ -60,7 +60,7 @@ export function createSessionRouter(
       res.status(401).json({ error: "unauthenticated" });
       return;
     }
-    req.user = { id: result.userId, username: result.username };
+    req.user = { id: result.userId, username: result.username, role: result.role };
     const token = extractSessionToken(req.headers.cookie);
     if (token) setSessionCookie(res, token);
     next();
@@ -98,7 +98,7 @@ export function createSessionRouter(
         logger.warn({ err: auditErr, action: "admin.first_created" }, "audit insert failed");
       }
       logger.info({ userId: user.id, username }, "First admin created");
-      res.json({ id: user.id, username: user.username });
+      res.json({ id: user.id, username: user.username, role: user.role });
     } catch (err) {
       logger.error({ err }, "setup failed");
       res.status(500).json({ error: "internal" });
@@ -120,7 +120,7 @@ export function createSessionRouter(
     }
     const { token } = sessions.createSession(user.id);
     setSessionCookie(res, token);
-    res.json({ id: user.id, username: user.username });
+    res.json({ id: user.id, username: user.username, role: user.role });
   });
 
   router.post("/logout", (req, res) => {
diff --git a/src/web/api/users.test.ts b/src/web/api/users.test.ts
index f2d8742..67efd4c 100644
--- a/src/web/api/users.test.ts
+++ b/src/web/api/users.test.ts
@@ -36,10 +36,10 @@ describe("users router", () => {
     users = createUserStore(botDb.db);
     sessions = createSessionStore(botDb.db);
     app = makeApp(botDb, users, sessions);
-    const alice = await users.createUser("alice", "pw-alice");
+    const alice = await users.createUser("alice", "pw-alice", "admin");
     aliceId = alice.id;
     aliceCookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(alice.id).token}`;
-    const bob = await users.createUser("bob", "pw-bob-bob");
+    const bob = await users.createUser("bob", "pw-bob-bob", "member");
     bobId = bob.id;
   });
 
@@ -189,4 +189,69 @@ describe("users router", () => {
     // Bob's session should be dead
     expect(sessions.validateAndTouch(bobToken)).toBeNull();
   });
+
+  it("POST / defaults new user to role=member when role omitted", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "carol", password: "pw-carol-pw" });
+    expect(res.status).toBe(201);
+    expect(res.body.role).toBe("member");
+  });
+
+  it("POST / accepts role=admin", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "carol", password: "pw-carol-pw", role: "admin" });
+    expect(res.status).toBe(201);
+    expect(res.body.role).toBe("admin");
+    expect(users.countAdmins()).toBe(2);
+  });
+
+  it("PATCH /:id/role can change role between admin and member", async () => {
+    const res = await request(app)
+      .patch(`/api/users/${bobId}/role`)
+      .set("Cookie", aliceCookie)
+      .send({ role: "admin" });
+    expect(res.status).toBe(204);
+    expect(users.findById(bobId)!.role).toBe("admin");
+  });
+
+  it("PATCH /:id/role blocks demoting the last admin", async () => {
+    // alice is the only admin. Demoting her would leave 0 admins. Block.
+    const res = await request(app)
+      .patch(`/api/users/${aliceId}/role`)
+      .set("Cookie", aliceCookie)
+      .send({ role: "member" });
+    expect(res.status).toBe(400);
+    expect(res.body).toEqual({ error: "cannot demote last admin" });
+  });
+
+  it("PATCH /:id/role allows demoting an admin when other admins exist", async () => {
+    // Promote bob first
+    users.setRole(bobId, "admin");
+    // Now both are admins. Demoting alice should work.
+    const res = await request(app)
+      .patch(`/api/users/${aliceId}/role`)
+      .set("Cookie", aliceCookie)
+      .send({ role: "member" });
+    expect(res.status).toBe(204);
+  });
+
+  it("PATCH /:id/role 400 on invalid role", async () => {
+    const res = await request(app)
+      .patch(`/api/users/${bobId}/role`)
+      .set("Cookie", aliceCookie)
+      .send({ role: "superuser" });
+    expect(res.status).toBe(400);
+  });
+
+  it("PATCH /:id/role 404 on unknown user", async () => {
+    const res = await request(app)
+      .patch(`/api/users/not-a-real-id/role`)
+      .set("Cookie", aliceCookie)
+      .send({ role: "admin" });
+    expect(res.status).toBe(404);
+  });
 });
diff --git a/src/web/api/users.ts b/src/web/api/users.ts
index 0204f16..b4f54b6 100644
--- a/src/web/api/users.ts
+++ b/src/web/api/users.ts
@@ -27,13 +27,14 @@ export function createUsersRouter(
   });
 
   router.post("/", async (req, res) => {
-    const { username, password } = req.body ?? {};
+    const { username, password, role: roleInput } = req.body ?? {};
     if (!isValidUsername(username) || !isValidPassword(password)) {
       res.status(400).json({ error: "invalid username or password" });
       return;
     }
+    const role: "admin" | "member" = roleInput === "admin" ? "admin" : "member";
     try {
-      const u = await users.createUser(username, password);
+      const u = await users.createUser(username, password, role);
       try {
         audit.record({
           actorId: req.user!.id, actorUsername: req.user!.username,
@@ -43,8 +44,8 @@ export function createUsersRouter(
       } catch (auditErr) {
         logger.warn({ err: auditErr, action: "user.created" }, "audit insert failed");
       }
-      logger.info({ createdBy: req.user!.id, newUserId: u.id, username }, "User created");
-      res.status(201).json({ id: u.id, username: u.username });
+      logger.info({ createdBy: req.user!.id, newUserId: u.id, username, role }, "User created");
+      res.status(201).json({ id: u.id, username: u.username, role: u.role });
     } catch (err) {
       if (err instanceof UsernameTakenError) {
         res.status(409).json({ error: "username taken" });
@@ -66,6 +67,10 @@ export function createUsersRouter(
       res.status(400).json({ error: "cannot delete self" });
       return;
     }
+    if (target.role === "admin" && users.countAdmins() <= 1) {
+      res.status(400).json({ error: "cannot delete last admin" });
+      return;
+    }
     const deleted = users.deleteUser(targetId);
     if (!deleted) {
       res.status(404).json({ error: "not found" });
@@ -116,5 +121,43 @@ export function createUsersRouter(
     res.status(204).end();
   });
 
+  router.patch("/:id/role", (req, res) => {
+    const targetId = req.params.id;
+    const { role: newRole } = req.body ?? {};
+    if (newRole !== "admin" && newRole !== "member") {
+      res.status(400).json({ error: "invalid role" });
+      return;
+    }
+    const target = users.findById(targetId);
+    if (!target) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    if (target.role === newRole) {
+      res.status(204).end();
+      return;
+    }
+    if (target.role === "admin" && newRole === "member" && users.countAdmins() <= 1) {
+      res.status(400).json({ error: "cannot demote last admin" });
+      return;
+    }
+    const changed = users.setRole(targetId, newRole);
+    if (!changed) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    try {
+      audit.record({
+        actorId: req.user!.id, actorUsername: req.user!.username,
+        targetUserId: target.id, targetUsername: target.username,
+        action: "user.role_changed",
+      });
+    } catch (auditErr) {
+      logger.warn({ err: auditErr, action: "user.role_changed" }, "audit insert failed");
+    }
+    logger.info({ actorId: req.user!.id, targetId, newRole }, "User role changed");
+    res.status(204).end();
+  });
+
   return router;
 }
diff --git a/src/web/middleware/requireAdmin.test.ts b/src/web/middleware/requireAdmin.test.ts
new file mode 100644
index 0000000..40ccd02
--- /dev/null
+++ b/src/web/middleware/requireAdmin.test.ts
@@ -0,0 +1,50 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore } from "../../data/users.js";
+import { createSessionStore } from "../../data/sessions.js";
+import { createRequireAuth } from "./requireAuth.js";
+import { requireAdmin } from "./requireAdmin.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+describe("requireAdmin middleware", () => {
+  let botDb: BotDatabase;
+  let app: express.Express;
+  let adminCookie: string;
+  let memberCookie: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const admin = await users.createUser("admin", "pw-admin-pw", "admin");
+    const member = await users.createUser("member", "pw-member-pw", "member");
+    adminCookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(admin.id).token}`;
+    memberCookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(member.id).token}`;
+    app = express();
+    app.use(cookieParser());
+    app.use(createRequireAuth(sessions));
+    app.use(requireAdmin);
+    app.get("/admin-only", (_req, res) => res.json({ ok: true }));
+  });
+
+  afterEach(() => botDb.close());
+
+  it("rejects unauthenticated requests with 401", async () => {
+    const res = await request(app).get("/admin-only");
+    expect(res.status).toBe(401);
+  });
+
+  it("rejects member with 403", async () => {
+    const res = await request(app).get("/admin-only").set("Cookie", memberCookie);
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: "forbidden" });
+  });
+
+  it("allows admin", async () => {
+    const res = await request(app).get("/admin-only").set("Cookie", adminCookie);
+    expect(res.status).toBe(200);
+  });
+});
diff --git a/src/web/middleware/requireAdmin.ts b/src/web/middleware/requireAdmin.ts
new file mode 100644
index 0000000..d37e08b
--- /dev/null
+++ b/src/web/middleware/requireAdmin.ts
@@ -0,0 +1,13 @@
+import type { Request, Response, NextFunction } from "express";
+
+export function requireAdmin(req: Request, res: Response, next: NextFunction): void {
+  if (!req.user) {
+    res.status(401).json({ error: "unauthenticated" });
+    return;
+  }
+  if (req.user.role !== "admin") {
+    res.status(403).json({ error: "forbidden" });
+    return;
+  }
+  next();
+}
diff --git a/src/web/middleware/requireAuth.test.ts b/src/web/middleware/requireAuth.test.ts
index c5c37a1..0025bd1 100644
--- a/src/web/middleware/requireAuth.test.ts
+++ b/src/web/middleware/requireAuth.test.ts
@@ -17,7 +17,7 @@ describe("requireAuth middleware", () => {
     botDb = createDatabase(":memory:");
     const users = createUserStore(botDb.db);
     const sessions = createSessionStore(botDb.db);
-    const u = await users.createUser("alice", "pw");
+    const u = await users.createUser("alice", "pw-alice", "admin");
     validToken = sessions.createSession(u.id).token;
 
     app = express();
@@ -52,6 +52,7 @@ describe("requireAuth middleware", () => {
     expect(res.status).toBe(200);
     expect(res.body.ok).toBe(true);
     expect(res.body.user.username).toBe("alice");
+    expect(res.body.user.role).toBe("admin");
   });
 
   it("rolls the cookie max-age forward on successful auth", async () => {
diff --git a/src/web/middleware/requireAuth.ts b/src/web/middleware/requireAuth.ts
index 8ec67bd..131235f 100644
--- a/src/web/middleware/requireAuth.ts
+++ b/src/web/middleware/requireAuth.ts
@@ -9,7 +9,7 @@ import {
 
 declare module "express-serve-static-core" {
   interface Request {
-    user?: { id: string; username: string };
+    user?: { id: string; username: string; role: "admin" | "member" };
   }
 }
 
@@ -21,7 +21,7 @@ export function createRequireAuth(sessions: SessionStore): RequestHandler {
       res.status(401).json({ error: "unauthenticated" });
       return;
     }
-    req.user = { id: result.userId, username: result.username };
+    req.user = { id: result.userId, username: result.username, role: result.role };
     const token = extractSessionToken(req.headers.cookie);
     if (token) {
       res.cookie(SESSION_COOKIE_NAME, token, {
diff --git a/src/web/server.ts b/src/web/server.ts
index d596d72..f1b8785 100755
--- a/src/web/server.ts
+++ b/src/web/server.ts
@@ -22,6 +22,7 @@ import { setupWebSocket } from "./websocket.js";
 import { createUserStore } from "../data/users.js";
 import { createSessionStore } from "../data/sessions.js";
 import { createRequireAuth } from "./middleware/requireAuth.js";
+import { requireAdmin } from "./middleware/requireAdmin.js";
 import { csrfOriginCheck } from "./middleware/csrf.js";
 import { validateSessionFromHeaders } from "./auth/validateSession.js";
 
@@ -104,8 +105,9 @@ export function createWebServer(options: WebServerOptions): WebServer {
     "/api/auth",
     createAuthRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.cookieStore)
   );
-  app.use("/api/users", createUsersRouter(users, sessions, audit, logger));
-  app.use("/api/audit", createAuditRouter(audit));
+  // admin-only routes
+  app.use("/api/users", requireAdmin, createUsersRouter(users, sessions, audit, logger));
+  app.use("/api/audit", requireAdmin, createAuditRouter(audit));
 
   // ─── Static SPA (public) ────────────────────────────────────────────────
   if (options.staticDir) {
diff --git a/src/web/websocket-auth.test.ts b/src/web/websocket-auth.test.ts
index efd9a9d..5424daf 100644
--- a/src/web/websocket-auth.test.ts
+++ b/src/web/websocket-auth.test.ts
@@ -36,7 +36,7 @@ describe("WebSocket auth at upgrade", () => {
     botDb = createDatabase(":memory:");
     const users = createUserStore(botDb.db);
     const sessions = createSessionStore(botDb.db);
-    const u = await users.createUser("alice", "pw");
+    const u = await users.createUser("alice", "pw-alice", "admin");
     validToken = sessions.createSession(u.id).token;
 
     const { server } = buildServer(sessions);

From 780726a4e37b446f53e2b477065eefeaea8c1382 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 15:38:42 +0800
Subject: [PATCH 29/35] feat(web): role-aware UI (badge, selector, toggle
 button, hide admin-only sections for members)

---
 web/src/components/Navbar.vue     | 10 +++++
 web/src/composables/useSession.ts |  2 +
 web/src/views/Settings.vue        | 75 +++++++++++++++++++++++++++----
 3 files changed, 78 insertions(+), 9 deletions(-)

diff --git a/web/src/components/Navbar.vue b/web/src/components/Navbar.vue
index 789e865..1024b3f 100644
--- a/web/src/components/Navbar.vue
+++ b/web/src/components/Navbar.vue
@@ -91,6 +91,9 @@
 
       <div v-if="session.currentUser.value" class="nav-user">
         <span class="nav-user-name">{{ session.currentUser.value.username }}</span>
+        <span class="nav-user-role" :class="`role-${session.currentUser.value.role}`">
+          {{ session.currentUser.value.role === 'admin' ? '管理员' : '成员' }}
+        </span>
         <button class="nav-user-logout" @click="onLogout" title="退出">
           <Icon icon="mdi:logout" />
         </button>
@@ -670,4 +673,11 @@ onUnmounted(() => {
   border-radius: var(--radius-sm);
   &:hover { background: var(--bg-secondary); color: var(--text-primary); }
 }
+
+.nav-user-role {
+  font-size: 11px; padding: 2px 6px; border-radius: 4px;
+  font-weight: 500;
+}
+.role-admin { background: rgba(99, 145, 226, 0.18); color: #6391e2; }
+.role-member { background: rgba(150, 150, 150, 0.18); color: var(--text-secondary); }
 </style>
diff --git a/web/src/composables/useSession.ts b/web/src/composables/useSession.ts
index 97ec892..b64e680 100644
--- a/web/src/composables/useSession.ts
+++ b/web/src/composables/useSession.ts
@@ -3,6 +3,7 @@ import { ref, computed, readonly } from "vue";
 interface User {
   id: string;
   username: string;
+  role: 'admin' | 'member';
 }
 
 const currentUser = ref<User | null>(null);
@@ -75,6 +76,7 @@ export function useSession() {
     currentUser: readonly(currentUser),
     needsSetup: readonly(needsSetup),
     isAuthenticated: computed(() => currentUser.value !== null),
+    isAdmin: computed(() => currentUser.value?.role === 'admin'),
     ready: readonly(ready),
     refresh,
     login,
diff --git a/web/src/views/Settings.vue b/web/src/views/Settings.vue
index 032497e..ada351e 100755
--- a/web/src/views/Settings.vue
+++ b/web/src/views/Settings.vue
@@ -460,13 +460,16 @@
     </section>
 
     <!-- User Management -->
-    <section class="settings-section">
+    <section v-if="session.isAdmin.value" class="settings-section">
       <h2 class="section-title">用户管理</h2>
       <div class="user-list">
         <div v-for="u in userList" :key="u.id" class="user-item">
           <div class="user-info">
             <div class="user-name">
               {{ u.username }}
+              <span class="user-role-badge" :class="`role-${u.role}`">
+                {{ u.role === 'admin' ? '管理员' : '成员' }}
+              </span>
               <span v-if="session.currentUser.value && u.id === session.currentUser.value.id" class="user-self-badge">本人</span>
             </div>
             <div class="user-created">创建于 {{ formatDate(u.createdAt) }}</div>
@@ -475,10 +478,19 @@
             <button class="btn-sm" @click="openResetPassword(u)">
               <Icon icon="mdi:lock-reset" /> 重置密码
             </button>
+            <button
+              class="btn-sm"
+              :disabled="changingRoleId === u.id || isLastAdmin(u)"
+              :title="isLastAdmin(u) ? '不能降级唯一的管理员' : (u.role === 'admin' ? '降级为成员' : '提升为管理员')"
+              @click="onToggleRole(u)"
+            >
+              <Icon icon="mdi:account-cog" />
+              {{ u.role === 'admin' ? '降为成员' : '提升管理员' }}
+            </button>
             <button
               class="btn-sm btn-delete"
-              :disabled="!!(session.currentUser.value && u.id === session.currentUser.value.id)"
-              :title="session.currentUser.value && u.id === session.currentUser.value.id ? '不能删除自己' : ''"
+              :disabled="!!(session.currentUser.value && u.id === session.currentUser.value.id) || isLastAdmin(u)"
+              :title="session.currentUser.value && u.id === session.currentUser.value.id ? '不能删除自己' : (isLastAdmin(u) ? '不能删除唯一的管理员' : '')"
               @click="onDeleteUser(u)"
             >
               <Icon icon="mdi:delete" />
@@ -492,6 +504,10 @@
       <form class="user-add-form" @submit.prevent="onCreateUser">
         <input v-model="newUser.username" class="input" placeholder="新用户名 (3-32 字符)" required />
         <input v-model="newUser.password" type="password" class="input" placeholder="密码 (≥8 位)" minlength="8" required />
+        <select v-model="newUser.role" class="input user-role-select">
+          <option value="member">成员</option>
+          <option value="admin">管理员</option>
+        </select>
         <button class="btn-sm btn-primary" type="submit" :disabled="creatingUser">
           {{ creatingUser ? '创建中…' : '添加用户' }}
         </button>
@@ -519,7 +535,7 @@
     </section>
 
     <!-- Audit Log -->
-    <section class="settings-section">
+    <section v-if="session.isAdmin.value" class="settings-section">
       <h2 class="section-title">
         操作审计
         <button class="audit-refresh-btn" @click="loadAudit" :disabled="auditLoading" title="刷新">
@@ -923,16 +939,46 @@ async function updateProfile(botId: string, key: keyof ProfileConfig, value: boo
 // --- User Management ---
 const session = useSession();
 
-interface UserListEntry { id: string; username: string; createdAt: number }
+interface UserListEntry { id: string; username: string; createdAt: number; role: 'admin' | 'member' }
 const userList = ref<UserListEntry[]>([]);
 const userLoadError = ref('');
 const userMutationError = ref('');
-const newUser = reactive({ username: '', password: '' });
+const newUser = reactive({ username: '', password: '', role: 'member' as 'admin' | 'member' });
 const creatingUser = ref(false);
 const resetTarget = ref<UserListEntry | null>(null);
 const resetPassword = ref('');
 const resetError = ref('');
 const resettingPw = ref(false);
+const changingRoleId = ref<string | null>(null);
+
+function isLastAdmin(u: UserListEntry): boolean {
+  if (u.role !== 'admin') return false;
+  const adminCount = userList.value.filter((x) => x.role === 'admin').length;
+  return adminCount <= 1;
+}
+
+async function onToggleRole(u: UserListEntry) {
+  const newRole = u.role === 'admin' ? 'member' : 'admin';
+  if (!confirm(`确认将 ${u.username} 切换为${newRole === 'admin' ? '管理员' : '成员'}？`)) return;
+  userMutationError.value = '';
+  changingRoleId.value = u.id;
+  try {
+    const res = await fetch(`/api/users/${u.id}/role`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ role: newRole }),
+    });
+    if (!res.ok && res.status !== 204) {
+      const b = await res.json().catch(() => ({}));
+      throw new Error(b.error ?? `HTTP ${res.status}`);
+    }
+    await loadUsers();
+  } catch (e) {
+    userMutationError.value = (e as Error).message;
+  } finally {
+    changingRoleId.value = null;
+  }
+}
 
 async function loadUsers() {
   userLoadError.value = '';
@@ -953,7 +999,7 @@ async function onCreateUser() {
     const res = await fetch('/api/users', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ username: newUser.username, password: newUser.password }),
+      body: JSON.stringify({ username: newUser.username, password: newUser.password, role: newUser.role }),
     });
     if (!res.ok) {
       const b = await res.json().catch(() => ({}));
@@ -961,6 +1007,7 @@ async function onCreateUser() {
     }
     newUser.username = '';
     newUser.password = '';
+    newUser.role = 'member';
     await loadUsers();
   } catch (e) {
     userMutationError.value = (e as Error).message;
@@ -1080,8 +1127,10 @@ onMounted(() => {
   checkAuthStatus();
   loadQuality();
   loadIdleTimeout();
-  loadUsers();
-  loadAudit();
+  if (session.isAdmin.value) {
+    loadUsers();
+    loadAudit();
+  }
 });
 
 onUnmounted(() => {
@@ -1776,4 +1825,12 @@ onUnmounted(() => {
     gap: 4px;
   }
 }
+
+.user-role-badge {
+  font-size: 11px; padding: 2px 6px; border-radius: 4px; margin-left: 6px;
+  font-weight: 500;
+}
+.role-admin { background: rgba(99, 145, 226, 0.18); color: #6391e2; }
+.role-member { background: rgba(150, 150, 150, 0.18); color: var(--text-secondary); }
+.user-role-select { flex: 0 0 110px; }
 </style>

From c0504d65a590f439e6b1a4e6fcb16f22a664ddfa Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 15:43:09 +0800
Subject: [PATCH 30/35] fix(web): localize user.role_changed audit label
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the missing case so role-change entries display in Chinese
instead of falling through to the generic key→target format.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 web/src/views/Settings.vue | 1 +
 1 file changed, 1 insertion(+)

diff --git a/web/src/views/Settings.vue b/web/src/views/Settings.vue
index ada351e..c5a127d 100755
--- a/web/src/views/Settings.vue
+++ b/web/src/views/Settings.vue
@@ -1112,6 +1112,7 @@ function describeAction(e: AuditEntry): string {
     case 'user.deleted':            return `删除用户 ${target}`;
     case 'user.password_reset':     return `重置 ${target} 的密码`;
     case 'user.password_changed':   return `修改自己的密码`;
+    case 'user.role_changed':       return `变更 ${target} 的角色`;
     default:                        return `${e.action} → ${target}`;
   }
 }

From 1a11489f2e9cb306cb455fdab7160b6490f14ed8 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 15:55:11 +0800
Subject: [PATCH 31/35] fix(auth): atomic last-admin guards on role-change and
 delete

---
 src/data/users.test.ts | 61 ++++++++++++++++++++++++++++++++++++++++++
 src/data/users.ts      | 31 +++++++++++++++++++++
 src/web/api/users.ts   | 53 +++++++++++++++++++-----------------
 3 files changed, 120 insertions(+), 25 deletions(-)

diff --git a/src/data/users.test.ts b/src/data/users.test.ts
index c365903..66f7ff4 100644
--- a/src/data/users.test.ts
+++ b/src/data/users.test.ts
@@ -122,4 +122,65 @@ describe("UserStore", () => {
     expect(alice.role).toBe("admin");
     expect(bob.role).toBe("member");
   });
+
+  it("setRoleIfNotLastAdmin returns 'would_orphan' for the only admin being demoted", async () => {
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    expect(users.setRoleIfNotLastAdmin(alice.id, "member")).toBe("would_orphan");
+    expect(users.findById(alice.id)!.role).toBe("admin"); // unchanged
+  });
+
+  it("setRoleIfNotLastAdmin allows demotion when another admin exists", async () => {
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    await users.createUser("bob", "pw-bob-bob", "admin");
+    expect(users.setRoleIfNotLastAdmin(alice.id, "member")).toBe("ok");
+    expect(users.findById(alice.id)!.role).toBe("member");
+  });
+
+  it("setRoleIfNotLastAdmin returns 'not_found' for unknown id", () => {
+    expect(users.setRoleIfNotLastAdmin("not-a-real-id", "member")).toBe("not_found");
+  });
+
+  it("setRoleIfNotLastAdmin: concurrent demotions of two admins keep one admin", async () => {
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    const bob = await users.createUser("bob", "pw-bob-bob", "admin");
+    // Concurrent demotion of both
+    const [r1, r2] = await Promise.all([
+      Promise.resolve(users.setRoleIfNotLastAdmin(alice.id, "member")),
+      Promise.resolve(users.setRoleIfNotLastAdmin(bob.id, "member")),
+    ]);
+    // Exactly one should succeed; the other gets "would_orphan"
+    const oks = [r1, r2].filter((r) => r === "ok").length;
+    const orphans = [r1, r2].filter((r) => r === "would_orphan").length;
+    expect(oks).toBe(1);
+    expect(orphans).toBe(1);
+    // System retains at least one admin
+    expect(users.countAdmins()).toBe(1);
+  });
+
+  it("deleteUserIfNotLastAdmin returns 'would_orphan' for the only admin", async () => {
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    expect(users.deleteUserIfNotLastAdmin(alice.id)).toBe("would_orphan");
+    expect(users.findById(alice.id)).not.toBeNull();
+  });
+
+  it("deleteUserIfNotLastAdmin allows deleting a member at any count", async () => {
+    await users.createUser("alice", "pw-alice", "admin");
+    const bob = await users.createUser("bob", "pw-bob-bob", "member");
+    expect(users.deleteUserIfNotLastAdmin(bob.id)).toBe("ok");
+    expect(users.findById(bob.id)).toBeNull();
+  });
+
+  it("deleteUserIfNotLastAdmin: concurrent deletes of two admins keep one admin", async () => {
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    const bob = await users.createUser("bob", "pw-bob-bob", "admin");
+    const [r1, r2] = await Promise.all([
+      Promise.resolve(users.deleteUserIfNotLastAdmin(alice.id)),
+      Promise.resolve(users.deleteUserIfNotLastAdmin(bob.id)),
+    ]);
+    const oks = [r1, r2].filter((r) => r === "ok").length;
+    const orphans = [r1, r2].filter((r) => r === "would_orphan").length;
+    expect(oks).toBe(1);
+    expect(orphans).toBe(1);
+    expect(users.countAdmins()).toBe(1);
+  });
 });
diff --git a/src/data/users.ts b/src/data/users.ts
index 1ad4728..432887d 100644
--- a/src/data/users.ts
+++ b/src/data/users.ts
@@ -25,7 +25,9 @@ export interface UserStore {
   verifyPassword(plain: string, hash: string): Promise<boolean>;
   changePassword(userId: string, newPassword: string): Promise<void>;
   setRole(userId: string, role: UserRole): boolean;
+  setRoleIfNotLastAdmin(id: string, newRole: UserRole): "ok" | "not_found" | "would_orphan";
   deleteUser(id: string): boolean;
+  deleteUserIfNotLastAdmin(id: string): "ok" | "not_found" | "would_orphan";
   listUsers(): Array<{ id: string; username: string; createdAt: number; role: UserRole }>;
 }
 
@@ -125,6 +127,21 @@ export function createUserStore(db: Database.Database): UserStore {
       return result.changes > 0;
     },
 
+    setRoleIfNotLastAdmin(id, newRole) {
+      const tx = db.transaction(() => {
+        const row = findByIdStmt.get(id) as UserRow | undefined;
+        if (!row) return "not_found" as const;
+        if (row.role === newRole) return "ok" as const; // no-op
+        if (row.role === "admin" && newRole === "member") {
+          const adminCount = (countAdminsStmt.get() as { n: number }).n;
+          if (adminCount <= 1) return "would_orphan" as const;
+        }
+        updateRoleStmt.run(newRole, Date.now(), id);
+        return "ok" as const;
+      });
+      return tx();
+    },
+
     listUsers() {
       return listUsersStmt.all() as Array<{ id: string; username: string; createdAt: number; role: UserRole }>;
     },
@@ -133,5 +150,19 @@ export function createUserStore(db: Database.Database): UserStore {
       const result = deleteUserStmt.run(id);
       return result.changes > 0;
     },
+
+    deleteUserIfNotLastAdmin(id) {
+      const tx = db.transaction(() => {
+        const row = findByIdStmt.get(id) as UserRow | undefined;
+        if (!row) return "not_found" as const;
+        if (row.role === "admin") {
+          const adminCount = (countAdminsStmt.get() as { n: number }).n;
+          if (adminCount <= 1) return "would_orphan" as const;
+        }
+        deleteUserStmt.run(id);
+        return "ok" as const;
+      });
+      return tx();
+    },
   };
 }
diff --git a/src/web/api/users.ts b/src/web/api/users.ts
index b4f54b6..0517654 100644
--- a/src/web/api/users.ts
+++ b/src/web/api/users.ts
@@ -58,6 +58,7 @@ export function createUsersRouter(
 
   router.delete("/:id", (req, res) => {
     const targetId = req.params.id;
+    // Snapshot target's username BEFORE deletion for audit
     const target = users.findById(targetId);
     if (!target) {
       res.status(404).json({ error: "not found" });
@@ -67,15 +68,16 @@ export function createUsersRouter(
       res.status(400).json({ error: "cannot delete self" });
       return;
     }
-    if (target.role === "admin" && users.countAdmins() <= 1) {
-      res.status(400).json({ error: "cannot delete last admin" });
-      return;
-    }
-    const deleted = users.deleteUser(targetId);
-    if (!deleted) {
+    const result = users.deleteUserIfNotLastAdmin(targetId);
+    if (result === "not_found") {
       res.status(404).json({ error: "not found" });
       return;
     }
+    if (result === "would_orphan") {
+      res.status(400).json({ error: "cannot delete last admin" });
+      return;
+    }
+    // FK CASCADE removes sessions; explicit call is belt-and-suspenders
     sessions.deleteAllForUser(targetId);
     try {
       audit.record({
@@ -128,34 +130,35 @@ export function createUsersRouter(
       res.status(400).json({ error: "invalid role" });
       return;
     }
-    const target = users.findById(targetId);
-    if (!target) {
+    // Snapshot the target's old role and username for audit (BEFORE the atomic update,
+    // so we record what actually changed; if the user is gone we'll skip audit).
+    const targetBefore = users.findById(targetId);
+    if (!targetBefore) {
       res.status(404).json({ error: "not found" });
       return;
     }
-    if (target.role === newRole) {
-      res.status(204).end();
+    const result = users.setRoleIfNotLastAdmin(targetId, newRole);
+    if (result === "not_found") {
+      res.status(404).json({ error: "not found" });
       return;
     }
-    if (target.role === "admin" && newRole === "member" && users.countAdmins() <= 1) {
+    if (result === "would_orphan") {
       res.status(400).json({ error: "cannot demote last admin" });
       return;
     }
-    const changed = users.setRole(targetId, newRole);
-    if (!changed) {
-      res.status(404).json({ error: "not found" });
-      return;
+    // Only audit when the role actually changed
+    if (targetBefore.role !== newRole) {
+      try {
+        audit.record({
+          actorId: req.user!.id, actorUsername: req.user!.username,
+          targetUserId: targetBefore.id, targetUsername: targetBefore.username,
+          action: "user.role_changed",
+        });
+      } catch (auditErr) {
+        logger.warn({ err: auditErr, action: "user.role_changed" }, "audit insert failed");
+      }
+      logger.info({ actorId: req.user!.id, targetId, newRole }, "User role changed");
     }
-    try {
-      audit.record({
-        actorId: req.user!.id, actorUsername: req.user!.username,
-        targetUserId: target.id, targetUsername: target.username,
-        action: "user.role_changed",
-      });
-    } catch (auditErr) {
-      logger.warn({ err: auditErr, action: "user.role_changed" }, "audit insert failed");
-    }
-    logger.info({ actorId: req.user!.id, targetId, newRole }, "User role changed");
     res.status(204).end();
   });
 

From a39fc25104b79ecda9c557adddcb6f1bf00628a7 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 16:16:07 +0800
Subject: [PATCH 32/35] feat(auth): rate-limit /login+/setup, per-user session
 cap, periodic /me poll

---
 src/data/sessions.test.ts            | 17 +++++++-
 src/data/sessions.ts                 | 10 +++++
 src/web/middleware/rateLimit.test.ts | 41 ++++++++++++++++++
 src/web/middleware/rateLimit.ts      | 63 ++++++++++++++++++++++++++++
 src/web/server.ts                    |  9 ++++
 web/src/composables/useSession.ts    | 22 ++++++++++
 6 files changed, 161 insertions(+), 1 deletion(-)
 create mode 100644 src/web/middleware/rateLimit.test.ts
 create mode 100644 src/web/middleware/rateLimit.ts

diff --git a/src/data/sessions.test.ts b/src/data/sessions.test.ts
index f0a491a..1505ec3 100644
--- a/src/data/sessions.test.ts
+++ b/src/data/sessions.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import { createHash } from "node:crypto";
 import { createDatabase, type BotDatabase } from "./database.js";
 import { createUserStore, type UserStore } from "./users.js";
-import { createSessionStore, type SessionStore, SESSION_TTL_MS, SESSION_TOUCH_INTERVAL_MS } from "./sessions.js";
+import { createSessionStore, type SessionStore, SESSION_TTL_MS, SESSION_TOUCH_INTERVAL_MS, MAX_SESSIONS_PER_USER } from "./sessions.js";
 
 function sha256(token: string) {
   return createHash("sha256").update(token).digest("hex");
@@ -101,4 +101,19 @@ describe("SessionStore", () => {
     const remaining = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
     expect(remaining).toBe(1);
   });
+
+  it("createSession caps concurrent sessions per user at MAX_SESSIONS_PER_USER, evicting oldest", async () => {
+    // Create MAX + 2 sessions for the same user.
+    const tokens: string[] = [];
+    for (let i = 0; i < MAX_SESSIONS_PER_USER + 2; i++) {
+      tokens.push(sessions.createSession(userId).token);
+      await new Promise((r) => setTimeout(r, 2)); // stagger createdAt
+    }
+    const count = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(count).toBe(MAX_SESSIONS_PER_USER);
+    // The first two should have been evicted, the last MAX remain
+    expect(sessions.validateAndTouch(tokens[0])).toBeNull();
+    expect(sessions.validateAndTouch(tokens[1])).toBeNull();
+    expect(sessions.validateAndTouch(tokens[tokens.length - 1])).not.toBeNull();
+  });
 });
diff --git a/src/data/sessions.ts b/src/data/sessions.ts
index 106b3ae..b78a9a8 100644
--- a/src/data/sessions.ts
+++ b/src/data/sessions.ts
@@ -3,6 +3,7 @@ import type Database from "better-sqlite3";
 
 export const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 export const SESSION_TOUCH_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+export const MAX_SESSIONS_PER_USER = 10;
 
 export interface SessionValidation {
   userId: string;
@@ -40,9 +41,18 @@ export function createSessionStore(db: Database.Database): SessionStore {
     "DELETE FROM sessions WHERE userId = ? AND id != ?"
   );
   const cleanupStmt = db.prepare("DELETE FROM sessions WHERE expiresAt < ?");
+  const countForUserStmt = db.prepare("SELECT COUNT(*) AS n FROM sessions WHERE userId = ?");
+  const deleteOldestForUserStmt = db.prepare(
+    "DELETE FROM sessions WHERE id IN (SELECT id FROM sessions WHERE userId = ? ORDER BY createdAt ASC LIMIT ?)"
+  );
 
   return {
     createSession(userId) {
+      // Cap concurrent sessions per user — oldest gets evicted on overflow.
+      const existing = (countForUserStmt.get(userId) as { n: number }).n;
+      if (existing >= MAX_SESSIONS_PER_USER) {
+        deleteOldestForUserStmt.run(userId, existing - MAX_SESSIONS_PER_USER + 1);
+      }
       const token = randomBytes(32).toString("base64url");
       const id = hashToken(token);
       const now = Date.now();
diff --git a/src/web/middleware/rateLimit.test.ts b/src/web/middleware/rateLimit.test.ts
new file mode 100644
index 0000000..73bbd1f
--- /dev/null
+++ b/src/web/middleware/rateLimit.test.ts
@@ -0,0 +1,41 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import express from "express";
+import request from "supertest";
+import { createRateLimit } from "./rateLimit.js";
+
+describe("createRateLimit", () => {
+  let app: express.Express;
+
+  beforeEach(() => {
+    app = express();
+    // capacity=3, refill=1/sec → first 3 succeed, then 429 until refill.
+    app.use(createRateLimit({ capacity: 3, refillPerSec: 1 }));
+    app.get("/", (_req, res) => res.json({ ok: true }));
+  });
+
+  it("allows up to capacity bursts then rejects with 429", async () => {
+    expect((await request(app).get("/")).status).toBe(200);
+    expect((await request(app).get("/")).status).toBe(200);
+    expect((await request(app).get("/")).status).toBe(200);
+    const denied = await request(app).get("/");
+    expect(denied.status).toBe(429);
+    expect(denied.body).toEqual({ error: "rate limit exceeded" });
+    expect(denied.headers["retry-after"]).toBeDefined();
+  });
+
+  it("uses per-key buckets when keyFn is provided", async () => {
+    const customApp = express();
+    customApp.use(
+      createRateLimit({
+        capacity: 1,
+        refillPerSec: 0.001,
+        keyFn: (req) => req.get("x-user") ?? "anon",
+      })
+    );
+    customApp.get("/", (_req, res) => res.json({ ok: true }));
+    expect((await request(customApp).get("/").set("X-User", "alice")).status).toBe(200);
+    expect((await request(customApp).get("/").set("X-User", "alice")).status).toBe(429);
+    // Different user, separate bucket → still has a token.
+    expect((await request(customApp).get("/").set("X-User", "bob")).status).toBe(200);
+  });
+});
diff --git a/src/web/middleware/rateLimit.ts b/src/web/middleware/rateLimit.ts
new file mode 100644
index 0000000..d93bc9e
--- /dev/null
+++ b/src/web/middleware/rateLimit.ts
@@ -0,0 +1,63 @@
+import type { Request, Response, NextFunction, RequestHandler } from "express";
+
+interface Bucket {
+  tokens: number;
+  lastRefillMs: number;
+}
+
+interface RateLimitOptions {
+  /** Bucket capacity (max burst). */
+  capacity: number;
+  /** Tokens refilled per second. */
+  refillPerSec: number;
+  /** Optional key function; defaults to req.ip. */
+  keyFn?: (req: Request) => string;
+}
+
+/**
+ * In-memory token-bucket rate limiter.
+ *
+ * Each unique key (default: req.ip) gets its own bucket. Refills continuously
+ * at `refillPerSec` up to `capacity`. Each request consumes 1 token; if no
+ * token is available, returns 429 with Retry-After.
+ *
+ * Buckets evict themselves after 10 minutes of inactivity to bound memory.
+ */
+export function createRateLimit(options: RateLimitOptions): RequestHandler {
+  const buckets = new Map<string, Bucket>();
+  const EVICT_AFTER_MS = 10 * 60 * 1000;
+  // Periodic eviction to bound memory under attack.
+  const evict = setInterval(() => {
+    const cutoff = Date.now() - EVICT_AFTER_MS;
+    for (const [k, b] of buckets) {
+      if (b.lastRefillMs < cutoff) buckets.delete(k);
+    }
+  }, 60_000);
+  // Unref the timer so it doesn't keep the process alive in tests.
+  if (typeof (evict as { unref?: () => void }).unref === "function") {
+    (evict as { unref: () => void }).unref();
+  }
+
+  const keyFn = options.keyFn ?? ((req) => req.ip ?? "unknown");
+
+  return function rateLimit(req: Request, res: Response, next: NextFunction): void {
+    const key = keyFn(req);
+    const now = Date.now();
+    let b = buckets.get(key);
+    if (!b) {
+      b = { tokens: options.capacity, lastRefillMs: now };
+      buckets.set(key, b);
+    }
+    const elapsedSec = (now - b.lastRefillMs) / 1000;
+    b.tokens = Math.min(options.capacity, b.tokens + elapsedSec * options.refillPerSec);
+    b.lastRefillMs = now;
+    if (b.tokens < 1) {
+      const waitSec = Math.ceil((1 - b.tokens) / options.refillPerSec);
+      res.setHeader("Retry-After", String(waitSec));
+      res.status(429).json({ error: "rate limit exceeded" });
+      return;
+    }
+    b.tokens -= 1;
+    next();
+  };
+}
diff --git a/src/web/server.ts b/src/web/server.ts
index f1b8785..027f26c 100755
--- a/src/web/server.ts
+++ b/src/web/server.ts
@@ -24,6 +24,7 @@ import { createSessionStore } from "../data/sessions.js";
 import { createRequireAuth } from "./middleware/requireAuth.js";
 import { requireAdmin } from "./middleware/requireAdmin.js";
 import { csrfOriginCheck } from "./middleware/csrf.js";
+import { createRateLimit } from "./middleware/rateLimit.js";
 import { validateSessionFromHeaders } from "./auth/validateSession.js";
 
 const SESSION_CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
@@ -74,6 +75,14 @@ export function createWebServer(options: WebServerOptions): WebServer {
     res.json({ publicUrl: raw ? raw.replace(/\/+$/, "") : null });
   });
 
+  // Anti-DoS: throttle expensive (bcrypt) auth endpoints.
+  // 5 req per minute per IP for /login (capacity 5, refill 5/60 = ~0.083/sec).
+  // 3 req per minute per IP for /setup (more limited; first-run is rare).
+  const loginLimit = createRateLimit({ capacity: 5, refillPerSec: 5 / 60 });
+  const setupLimit = createRateLimit({ capacity: 3, refillPerSec: 3 / 60 });
+  app.use("/api/session/login", loginLimit);
+  app.use("/api/session/setup", setupLimit);
+
   app.use("/api/session", createSessionRouter(users, sessions, audit, logger));
 
   // ─── Gates for everything else under /api ───────────────────────────────
diff --git a/web/src/composables/useSession.ts b/web/src/composables/useSession.ts
index b64e680..e8c17ff 100644
--- a/web/src/composables/useSession.ts
+++ b/web/src/composables/useSession.ts
@@ -10,6 +10,26 @@ const currentUser = ref<User | null>(null);
 const needsSetup = ref<boolean | null>(null); // null = unknown / not fetched yet
 const ready = ref(false);
 
+let pollTimer: ReturnType<typeof setInterval> | null = null;
+const POLL_INTERVAL_MS = 60_000;
+
+function ensurePollStarted() {
+  if (pollTimer !== null) return;
+  pollTimer = setInterval(() => {
+    if (currentUser.value !== null) {
+      // Best-effort refresh; ignore errors (network blips etc.)
+      refreshMe().catch(() => {});
+    }
+  }, POLL_INTERVAL_MS);
+}
+
+function stopPoll() {
+  if (pollTimer !== null) {
+    clearInterval(pollTimer);
+    pollTimer = null;
+  }
+}
+
 async function refreshNeedsSetup(): Promise<void> {
   const res = await fetch("/api/session/needs-setup", { credentials: "same-origin" });
   if (res.ok) {
@@ -35,6 +55,7 @@ async function refresh(): Promise<void> {
     await refreshMe();
   }
   ready.value = true;
+  ensurePollStarted();
 }
 
 async function login(username: string, password: string): Promise<void> {
@@ -67,6 +88,7 @@ async function setup(username: string, password: string): Promise<void> {
 }
 
 async function logout(): Promise<void> {
+  stopPoll();
   await fetch("/api/session/logout", { method: "POST", credentials: "same-origin" });
   currentUser.value = null;
 }

From b6b9aa07bc1b1da82ae02599011b41321656a134 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 16:29:16 +0800
Subject: [PATCH 33/35] feat(auth): atomic session cap + change-password UI +
 trustProxy docs

---
 README.md                  | 10 +++++
 src/data/sessions.test.ts  |  9 ++++
 src/data/sessions.ts       | 16 ++++---
 web/src/views/Settings.vue | 89 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 119 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 09b42f5..64f74ce 100644
--- a/README.md
+++ b/README.md
@@ -426,6 +426,16 @@ pip install -U yt-dlp
 }
 ```
 
+### 反向代理部署注意事项
+
+当 WebUI 部署在反向代理（nginx / Caddy / Cloudflare 等）之后时，请务必在 `config.json` 中设置 `"trustProxy": true`：
+
+- **Cookie Secure 标志**：未启用 `trustProxy` 时，Express 无法从 `X-Forwarded-Proto` 正确判断请求实际是否为 HTTPS，会话 cookie 不会被标记为 `Secure`。
+- **登录限流**：登录限流以 `req.ip` 为键，未启用 `trustProxy` 时所有请求都会被识别为代理本身的 IP，单个攻击者会拖累所有合法用户共用同一个限流桶。
+- **审计日志的客户端 IP**（如果未来添加该字段）也需要 `trustProxy` 才能正确记录。
+
+直接暴露端口（无代理）时无需启用该选项。
+
 ## 常见问题
 
 **Q：支持 TeamSpeak 6 Server 吗？**
diff --git a/src/data/sessions.test.ts b/src/data/sessions.test.ts
index 1505ec3..b7a8dcf 100644
--- a/src/data/sessions.test.ts
+++ b/src/data/sessions.test.ts
@@ -116,4 +116,13 @@ describe("SessionStore", () => {
     expect(sessions.validateAndTouch(tokens[1])).toBeNull();
     expect(sessions.validateAndTouch(tokens[tokens.length - 1])).not.toBeNull();
   });
+
+  it("createSession respects cap under concurrent calls (no 1-over-cap race)", async () => {
+    // better-sqlite3 transactions are serialised at the engine level. Calling
+    // createSession N times sequentially via Promise.all proves atomic check+insert.
+    const N = MAX_SESSIONS_PER_USER + 3;
+    await Promise.all(Array.from({ length: N }, () => Promise.resolve(sessions.createSession(userId))));
+    const count = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(count).toBe(MAX_SESSIONS_PER_USER);
+  });
 });
diff --git a/src/data/sessions.ts b/src/data/sessions.ts
index b78a9a8..bf446d2 100644
--- a/src/data/sessions.ts
+++ b/src/data/sessions.ts
@@ -49,15 +49,21 @@ export function createSessionStore(db: Database.Database): SessionStore {
   return {
     createSession(userId) {
       // Cap concurrent sessions per user — oldest gets evicted on overflow.
-      const existing = (countForUserStmt.get(userId) as { n: number }).n;
-      if (existing >= MAX_SESSIONS_PER_USER) {
-        deleteOldestForUserStmt.run(userId, existing - MAX_SESSIONS_PER_USER + 1);
-      }
+      // Wrap the count → delete → insert in a transaction so concurrent logins
+      // for the same user can't both pass the cap check and both insert,
+      // ending up 1 over cap (race window between count and insert).
       const token = randomBytes(32).toString("base64url");
       const id = hashToken(token);
       const now = Date.now();
       const expiresAt = now + SESSION_TTL_MS;
-      insertStmt.run(id, userId, now, expiresAt, now);
+      const tx = db.transaction(() => {
+        const existing = (countForUserStmt.get(userId) as { n: number }).n;
+        if (existing >= MAX_SESSIONS_PER_USER) {
+          deleteOldestForUserStmt.run(userId, existing - MAX_SESSIONS_PER_USER + 1);
+        }
+        insertStmt.run(id, userId, now, expiresAt, now);
+      });
+      tx();
       return { token, expiresAt };
     },
 
diff --git a/web/src/views/Settings.vue b/web/src/views/Settings.vue
index c5a127d..863c267 100755
--- a/web/src/views/Settings.vue
+++ b/web/src/views/Settings.vue
@@ -21,6 +21,35 @@
       </div>
     </section>
 
+    <!-- Account: own password change -->
+    <section class="settings-section">
+      <h2 class="section-title">账户</h2>
+      <div class="account-info-card">
+        <div class="account-row">
+          <span class="account-label">用户名</span>
+          <span class="account-value">{{ session.currentUser.value?.username ?? '—' }}</span>
+        </div>
+        <div class="account-row">
+          <span class="account-label">角色</span>
+          <span class="account-value">
+            <span class="user-role-badge" :class="`role-${session.currentUser.value?.role}`">
+              {{ session.currentUser.value?.role === 'admin' ? '管理员' : '成员' }}
+            </span>
+          </span>
+        </div>
+      </div>
+      <form class="change-pw-form" @submit.prevent="onChangeOwnPassword">
+        <input v-model="ownPw.old" type="password" autocomplete="current-password" class="input" placeholder="当前密码" required />
+        <input v-model="ownPw.new" type="password" autocomplete="new-password" minlength="8" class="input" placeholder="新密码 (≥8 位)" required />
+        <input v-model="ownPw.confirm" type="password" autocomplete="new-password" minlength="8" class="input" placeholder="再次输入新密码" required />
+        <button class="btn-sm btn-primary" type="submit" :disabled="changingOwnPw">
+          {{ changingOwnPw ? '更新中…' : '修改密码' }}
+        </button>
+      </form>
+      <p v-if="ownPwError" class="user-error">{{ ownPwError }}</p>
+      <p v-if="ownPwSuccess" class="user-success">{{ ownPwSuccess }}</p>
+    </section>
+
     <!-- Bot Management -->
     <section class="settings-section">
       <h2 class="section-title">机器人管理</h2>
@@ -939,6 +968,46 @@ async function updateProfile(botId: string, key: keyof ProfileConfig, value: boo
 // --- User Management ---
 const session = useSession();
 
+// --- Own password change (available to all authenticated users) ---
+const ownPw = reactive({ old: '', new: '', confirm: '' });
+const ownPwError = ref('');
+const ownPwSuccess = ref('');
+const changingOwnPw = ref(false);
+
+async function onChangeOwnPassword() {
+  ownPwError.value = '';
+  ownPwSuccess.value = '';
+  if (ownPw.new !== ownPw.confirm) {
+    ownPwError.value = '两次输入的新密码不一致';
+    return;
+  }
+  if (ownPw.new.length < 8) {
+    ownPwError.value = '新密码至少 8 位';
+    return;
+  }
+  changingOwnPw.value = true;
+  try {
+    const res = await fetch('/api/session/change-password', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ oldPassword: ownPw.old, newPassword: ownPw.new }),
+    });
+    if (!res.ok && res.status !== 204) {
+      const b = await res.json().catch(() => ({}));
+      throw new Error(b.error ?? `HTTP ${res.status}`);
+    }
+    ownPw.old = '';
+    ownPw.new = '';
+    ownPw.confirm = '';
+    ownPwSuccess.value = '密码已更新';
+    // The server kills other sessions but keeps the current one. No reload needed.
+  } catch (e) {
+    ownPwError.value = (e as Error).message;
+  } finally {
+    changingOwnPw.value = false;
+  }
+}
+
 interface UserListEntry { id: string; username: string; createdAt: number; role: 'admin' | 'member' }
 const userList = ref<UserListEntry[]>([]);
 const userLoadError = ref('');
@@ -1834,4 +1903,24 @@ onUnmounted(() => {
 .role-admin { background: rgba(99, 145, 226, 0.18); color: #6391e2; }
 .role-member { background: rgba(150, 150, 150, 0.18); color: var(--text-secondary); }
 .user-role-select { flex: 0 0 110px; }
+
+// --- Account section (own password change) ---
+.account-info-card {
+  display: flex; flex-direction: column; gap: 8px;
+  padding: 12px; background: var(--bg-secondary); border-radius: var(--radius-sm);
+  margin-bottom: 12px;
+}
+.account-row {
+  display: flex; justify-content: space-between; align-items: center;
+  font-size: 13px;
+}
+.account-label { color: var(--text-secondary); }
+.account-value { color: var(--text-primary); font-weight: 500; }
+.change-pw-form {
+  display: flex; flex-direction: column; gap: 8px;
+  max-width: 360px;
+}
+.change-pw-form .input { width: 100%; }
+.change-pw-form button { align-self: flex-start; }
+.user-success { color: #4caf7a; font-size: 13px; margin: 4px 0 0; }
 </style>

From a0f290459d2a9bd3720b387b8d640b3f790cc24e Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 16:34:52 +0800
Subject: [PATCH 34/35] feat(auth): X-Frame-Options + CSP frame-ancestors
 clickjacking defence

Every response now carries:
  X-Frame-Options: DENY
  Content-Security-Policy: frame-ancestors 'none'

Prevents the WebUI from being embedded in a third-party iframe.
Combined with the existing CSRF Origin-host check, this closes the
last meaningful UI-redress surface.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/web/security-headers.test.ts | 40 ++++++++++++++++++++++++++++++++
 src/web/server.ts                |  9 +++++++
 2 files changed, 49 insertions(+)
 create mode 100644 src/web/security-headers.test.ts

diff --git a/src/web/security-headers.test.ts b/src/web/security-headers.test.ts
new file mode 100644
index 0000000..b16a3a9
--- /dev/null
+++ b/src/web/security-headers.test.ts
@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import express from "express";
+import request from "supertest";
+
+/**
+ * The clickjacking-defence middleware is mounted at the top of
+ * `createWebServer` in `server.ts`. This test asserts the exact behavior
+ * we expect from that middleware in isolation. The wiring inside
+ * `server.ts` is verified by code review (git diff).
+ */
+describe("security headers (anti-clickjacking)", () => {
+  function buildApp() {
+    const app = express();
+    app.use((_req, res, next) => {
+      res.setHeader("X-Frame-Options", "DENY");
+      res.setHeader("Content-Security-Policy", "frame-ancestors 'none'");
+      next();
+    });
+    app.get("/", (_req, res) => res.json({ ok: true }));
+    app.post("/", (_req, res) => res.json({ ok: true }));
+    return app;
+  }
+
+  it("sets X-Frame-Options: DENY on GET responses", async () => {
+    const res = await request(buildApp()).get("/");
+    expect(res.status).toBe(200);
+    expect(res.headers["x-frame-options"]).toBe("DENY");
+  });
+
+  it("sets Content-Security-Policy frame-ancestors 'none' on GET responses", async () => {
+    const res = await request(buildApp()).get("/");
+    expect(res.headers["content-security-policy"]).toBe("frame-ancestors 'none'");
+  });
+
+  it("sets both headers on POST responses too", async () => {
+    const res = await request(buildApp()).post("/");
+    expect(res.headers["x-frame-options"]).toBe("DENY");
+    expect(res.headers["content-security-policy"]).toBe("frame-ancestors 'none'");
+  });
+});
diff --git a/src/web/server.ts b/src/web/server.ts
index 027f26c..753fbe1 100755
--- a/src/web/server.ts
+++ b/src/web/server.ts
@@ -58,6 +58,15 @@ export function createWebServer(options: WebServerOptions): WebServer {
     app.set("trust proxy", true);
   }
 
+  // Security headers: prevent the WebUI from being embedded in a third-party
+  // iframe (clickjacking defence). CSP frame-ancestors is the modern equivalent
+  // of X-Frame-Options; both are set for compatibility across browsers.
+  app.use((_req, res, next) => {
+    res.setHeader("X-Frame-Options", "DENY");
+    res.setHeader("Content-Security-Policy", "frame-ancestors 'none'");
+    next();
+  });
+
   app.use(express.json({ limit: "400kb" }));
   app.use(cookieParser());
 

From f73ca1f61b40a3c082038b89a98d72eb10aeae24 Mon Sep 17 00:00:00 2001
From: saopig1 <4x7sw862st@gmail.com>
Date: Wed, 27 May 2026 16:40:41 +0800
Subject: [PATCH 35/35] docs: README updates for WebUI auth feature + pre-auth
 upgrade guide

---
 README.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 86 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 64f74ce..e9ffdf8 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,7 @@
 
 ## 功能特性
 
+- **WebUI 鉴权（必选）** — 用户名 + 密码登录，多用户、两种角色（管理员 / 成员），bcrypt 加密、HttpOnly 会话 Cookie，CSRF 防护，WebSocket 同样鉴权。首次访问引导创建管理员。从无鉴权旧版本升级时请参阅 [更新升级](#更新升级) 章节
 - **多平台音源** — 网易云音乐 + QQ 音乐 + 哔哩哔哩（默认内置），YouTube 可选启用（通过 yt-dlp），统一搜索，结果标注来源
 - **真实客户端协议 (TS3/TS6 双协议)** — 机器人在 TeamSpeak 中可见（非 ServerQuery 隐身模式），自动检测并适配 TS3 和 TS6 服务器，支持 TS6 HTTP Query API
 - **YesPlayMusic 风格 WebUI** — 精美界面，支持深色/浅色主题切换
@@ -155,6 +156,49 @@ sudo ./scripts/install.sh
 >
 > **如何判断是否需要迁移**：如果你是全新安装，或者你的机器人数据库中 `identity` 字段已经是空的，则**无需任何操作**。完成上述步骤后，按下面对应的系统升级步骤执行即可。
 
+### 从 WebUI 无鉴权版本升级（重要）
+
+本次更新引入了**强制 WebUI 鉴权**。从无鉴权旧版本升级后，**WebUI 必须先创建管理员账号才能使用**。所有 `/api/*` 端点（除少量公共白名单）和 `/ws` 现在都需要登录。
+
+**升级行为**：
+
+- 启动时数据库自动迁移：新增 `users`、`sessions`、`user_audit` 三张表；旧的 `bot_instances`、`play_history` 数据**完全保留**。
+- 第一次打开 WebUI 自动跳转到 `/first-run` 引导创建首位管理员（角色固定为 `admin`）。
+- 之后访问任何页面都会校验登录态，未登录跳转 `/login`。
+
+**会话与 Cookie**：
+
+- 登录态保存 7 天，每次请求滚动续期（活跃用户不会被踢出）。
+- 同一账号最多保持 10 个并发会话（超过自动剔除最旧的）。
+- Cookie 设置为 `HttpOnly; SameSite=Lax`，HTTPS 部署需配合 `trustProxy: true`（详见 [反向代理部署注意事项](#反向代理部署注意事项)）。
+
+**多用户与角色**：
+
+- 角色 `admin`：完整权限（用户管理、审计、机器人、音乐平台、播放控制）。
+- 角色 `member`：除"用户管理"和"操作审计"外的所有功能（适合给团队成员开通播放权）。
+- 在 **设置 → 用户管理**（仅管理员）中添加 / 删除 / 重置密码 / 切换角色。
+- 至少保留一个管理员：系统会阻止删除或降级最后一位管理员。
+
+**如何重置忘记的管理员密码**：
+
+如果你忘记了管理员密码，可以直接编辑 SQLite 数据库 `data/tsmusicbot.db`：
+
+```bash
+# 方案 1：清空所有用户，重新进入 first-run 流程
+sqlite3 data/tsmusicbot.db "DELETE FROM users; DELETE FROM sessions;"
+# 然后重启机器人，浏览器再次访问会自动进入 /first-run
+
+# 方案 2：把指定用户重置为已知密码（密码 'changeme-now' 的 bcrypt 哈希示例如下）
+# 先用 node 生成哈希：
+node -e "console.log(require('bcryptjs').hashSync('changeme-now', 12))"
+# 把输出贴到 SQL 里：
+sqlite3 data/tsmusicbot.db "UPDATE users SET passwordHash='<paste-hash-here>' WHERE username='你的用户名';"
+```
+
+**反向代理用户特别注意**：如果通过 nginx / Caddy / Cloudflare 暴露 WebUI，**必须**在 `config.json` 中设置 `"trustProxy": true`，否则 Cookie 不会带 `Secure` 标志，且登录限流会把所有用户合并到同一个桶。详见下方 [反向代理部署注意事项](#反向代理部署注意事项)。
+
+**旧版 `config.adminPassword` / `adminGroups`**：这两个配置项在旧版本中预留但从未实际启用（TS-side admin 命令权限的占位字段）。保留以避免破坏旧 `config.json`，但不再影响任何行为。可以放心忽略。
+
 ### Windows 用户
 
 ```
@@ -221,10 +265,16 @@ sudo systemctl start tsmusicbot
 
 ### 首次配置
 
-1. 打开 **http://localhost:3000/setup** 进入设置向导
-2. 填写 TeamSpeak 服务器地址（默认端口：9987）
-3. 设置机器人昵称
-4. （可选）扫码登录网易云/QQ音乐账号以播放 VIP 歌曲
+1. 启动机器人后打开 **http://localhost:3000/**
+   - 全新部署：自动跳转 `/first-run`，填写用户名（3-32 字符）和密码（≥8 位）创建首位**管理员**账号
+   - 之后所有 WebUI 操作都需要登录，登录态保持 7 天（活动会滚动续期）
+2. 在 **设置 → 机器人管理** 中点击"创建新实例"，填写：
+   - TeamSpeak 服务器地址（无端口，仅主机名，例如 `ts.example.com`）
+   - 端口（默认 9987，自托管或非标准端口请填写实际值）
+   - 机器人昵称
+   - 可选：服务器密码、默认频道
+3. 在 **设置 → 音乐账号** 扫码登录网易云 / QQ 音乐 / B 站账号（可选，登录后可播放 VIP 歌曲）
+4. 在 **设置 → 用户管理**（仅管理员可见）按需添加成员，成员账号可以控制播放但无法管理其他用户
 
 ### WebUI 页面说明
 
@@ -235,7 +285,7 @@ sudo systemctl start tsmusicbot
 | **歌单** | 查看歌单详情，播放全部（根据当前播放模式选择首歌） |
 | **歌词** | 全屏歌词页，实时同步滚动，模糊专辑封面背景 |
 | **历史** | 播放历史记录 |
-| **设置** | 主题切换、机器人管理、三平台账号登录、音质选择、命令前缀 |
+| **设置** | 账户（修改自己密码） / 主题切换 / 机器人管理 / 三平台账号登录 / 音质选择 / 命令前缀 / 用户管理（仅管理员）/ 操作审计（仅管理员） |
 
 ### TeamSpeak 文字命令
 
@@ -426,6 +476,8 @@ pip install -U yt-dlp
 }
 ```
 
+> **关于 `adminPassword` 和 `adminGroups`**：这两个字段保留是为了兼容旧 `config.json`，但当前版本未使用。WebUI 鉴权改为基于数据库的用户账号系统（见 [首次配置](#首次配置)），无需在 `config.json` 中设置密码。
+
 ### 反向代理部署注意事项
 
 当 WebUI 部署在反向代理（nginx / Caddy / Cloudflare 等）之后时，请务必在 `config.json` 中设置 `"trustProxy": true`：
@@ -475,6 +527,21 @@ A：YouTube 是可选音源，需要手动安装 `yt-dlp`。详见 [可选：You
 **Q：如何更新到新版本？**
 A：`git pull` 拉取最新代码，然后 `npm install && npm run build && npm start` 重新构建启动。Docker 用户执行 `docker-compose up -d --build`。
 
+**Q：忘记管理员密码怎么办？**
+A：直接操作 SQLite 数据库。最简单的办法是清空 `users` 表然后重新进入 first-run 流程：`sqlite3 data/tsmusicbot.db "DELETE FROM users; DELETE FROM sessions;"`，重启后浏览器会自动跳转 `/first-run` 让你重新创建管理员。详细方法见 [从 WebUI 无鉴权版本升级](#从-webui-无鉴权版本升级重要)。
+
+**Q：成员（member）能做什么？不能做什么？**
+A：成员可以：管理机器人（启动/停止/创建/编辑）、控制播放（搜索/播放/队列）、登录音乐平台账号、修改自己的密码。成员**不能**：管理其他用户、查看操作审计日志、降级或删除管理员。
+
+**Q：如何把某个用户从成员升级为管理员？**
+A：管理员登录后进入 **设置 → 用户管理**，点击对应用户的"提升管理员"按钮即可。降级同理（"降为成员"按钮）。系统会阻止降级最后一位管理员。
+
+**Q：登录之后多久会自动退出？**
+A：登录态有效期 7 天，活跃使用会滚动续期（每次受保护请求都会刷新过期时间）。同一账号最多保持 10 个并发会话（多设备登录时超过的会自动剔除最旧的会话）。
+
+**Q：部署到公网后如何防止暴力登录？**
+A：本项目内置 `/login` 限流（每 IP 每分钟 5 次），但生产部署建议同时在反向代理（nginx `limit_req` / Caddy 等）层加一层限流，并启用 HTTPS。反向代理部署务必设置 `"trustProxy": true`（详见 [反向代理部署注意事项](#反向代理部署注意事项)）。
+
 ## 参与贡献
 
 1. Fork 本仓库
@@ -489,6 +556,20 @@ A：`git pull` 拉取最新代码，然后 `npm install && npm run build && npm
 
 ### 最新版本
 
+**WebUI 鉴权与权限系统**
+
+- **首次运行强制创建管理员账号**：浏览器打开 WebUI 自动跳转 `/first-run`；之后所有 `/api/*`（除少量公共白名单：`/api/health`、`/api/config/public-url`、`/api/session/*`）和 `/ws` 都需要登录。详见 [更新升级 → 从 WebUI 无鉴权版本升级](#从-webui-无鉴权版本升级重要)。
+- **两种角色：admin / member**。`member` 可以管理机器人、控制播放、登录音乐平台账号、修改自己密码，但不能管理其他用户或查看审计日志。`admin` 拥有全部权限。
+- **用户管理 UI**：管理员在 设置 → 用户管理 可以增删用户、切换角色、重置密码。系统强制保留至少一位管理员。
+- **操作审计日志**：管理员在 设置 → 操作审计 可以查看用户管理相关事件（创建、删除、密码重置、角色变更、首位管理员创建、自助修改密码）。
+- **自助修改密码**：所有用户都可在 设置 → 账户 修改自己密码。
+- **会话存储**：服务端 SQLite 表 `sessions`，存储 sha256(token)；浏览器只持有原始 token cookie。7 天 TTL，每小时滚动续期。同账号最多 10 个并发会话（超出剔除最旧）。
+- **登录限流**：每 IP 每分钟 5 次 `/login` + 3 次 `/setup`，命中返回 429 + `Retry-After`。
+- **CSRF & 安全头**：所有 mutating 请求强制 `Origin`/`Referer` 同源；响应携带 `X-Frame-Options: DENY` 和 `Content-Security-Policy: frame-ancestors 'none'`（防点击劫持）。
+- **配置变更**：反向代理部署务必 `"trustProxy": true`（详见 [反向代理部署注意事项](#反向代理部署注意事项)）。`config.adminPassword` / `adminGroups` 字段保留以兼容旧 `config.json`，但不再影响任何行为。
+
+### v0.x — Bot Profile 自动更新与协议层升级
+
 **机器人形象自动更新（Bot Profile）**
 
 - **播放时自动更新 TS 形象**：头像（专辑封面缩略图）、昵称（`♪ 歌名 - 歌手 - 原昵称`）、描述（歌曲信息）、Away 状态、频道描述、"正在播放"频道消息，全部随歌曲切换自动更新。