teamspeak-music-bot/docs/superpowers/specs/2026-05-27-webui-authentication-design.md

# 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）—— 这是预期行为。