# 安全模型

本服务同时处理 Bilibili 登录 Cookie、TOTP Secret、一次性恢复码、管理员邀请码和 OBS
token。以下规则是实现约束，而不是可选部署建议。

## 租户隔离

- HTTP handler 只从服务端会话解析 `owner_id`，不接受客户端声明的 owner。
- 组件查询始终限定 `owner_user_id`；组件表不保存直播源外键。
- 直播间、直播源和 CookieCloud 凭据分别以账户 ID 建立唯一约束与 RLS 边界。
- 数据库使用 owner 复合外键、RLS 和 `FORCE ROW LEVEL SECURITY`。
- tenant 查询必须在事务中执行 `SET LOCAL app.user_id`，不能使用会泄漏到连接池的 session-level
  `SET`。
- 实时广播按 `component_id` 建立独立 channel，不提供全局订阅。
- 路由器按事件的可信 `owner_id` 扇出，并在投影发布前再次验证 owner、账户 source 和 component ID。

## Secret 生命周期

| Secret               | 浏览器可见性        | 数据库存储              | 轮换/消费        |
| -------------------- | ------------------- | ----------------------- | ---------------- |
| TOTP Secret          | 注册时显示一次      | XChaCha20-Poly1305 密文 | 账户绑定         |
| 恢复码               | 注册完成时显示一次  | SHA-256 摘要            | 单次消费         |
| 登录 session         | HttpOnly Cookie     | SHA-256 摘要            | 到期、登出或撤销 |
| CookieCloud Key/密码 | 用户提交时          | XChaCha20-Poly1305 密文 | 覆盖更新         |
| 邀请码               | 创建时显示一次      | SHA-256 摘要和前缀      | 单次消费或撤销   |
| OBS token            | 创建/轮换时显示一次 | SHA-256 摘要            | 组件级轮换       |

`security.data_encryption_key`
是恢复密文所必需的主密钥。它必须独立备份，但不能提交到 Git 或写入镜像。

## Passwordless 认证

- 第一个系统管理员只能通过数据库为空时的 bootstrap 流程创建。
- bootstrap proof 不成为账户密码，也不能用于日常登录。
- TOTP 接受有限时钟偏移，并持久化最近使用的 time step，阻止同一码重放。
- 登录与匿名注册同时按账户维度和网络维度限流，错误消息不暴露用户名是否存在。
- 注册先写入短期 pending enrollment；只有正确 TOTP 确认后才原子创建账户并消费邀请码。

## CookieCloud 与 SSRF

- 部署者通过 `cookiecloud_allowed_hosts` 指定精确的基础地址白名单。
- URL 会规范化，并拒绝 embedded credentials、query 和 fragment。
- Key 编码成单一路径段，不能注入额外路径。
- HTTP 客户端禁止重定向，防止允许的地址跳转到内网目标。
- 浏览器只看到 host 和 `keyConfigured`/`passwordConfigured`，不会读回凭据。
- `libilibili::Credentials` 的 `Debug` 已脱敏，但应用仍不得记录 Cookie、原始认证响应或弹幕 token。

## HTTP、WebSocket 与 OBS

- 公开部署必须在受信任反代终止 HTTPS，并保持 `secure_cookies = true`。
- 生产 session 使用 `__Host-` Cookie、HttpOnly、Secure 与 SameSite 策略。
- 写 API 执行 same-origin 检查并限制 body 大小。
- 所有 `/api/*` 响应使用 `Cache-Control: no-store`。
- OBS token 放在 URL fragment，并作为 WebSocket 第一帧发送。
- token 只具有 `events:subscribe` scope，且只能订阅其绑定的组件。
- WebSocket 首帧、frame size、认证时间和全局连接数均有上限。

## PWA 边界

- manifest、Service Worker 和 start URL 都限定在 `/control/`。
- `/obs/*` 不在 Service Worker scope 内。
- worker 只缓存静态应用壳层、图标和构建资源；不缓存 API、WebSocket 或直播事件。
- 离线 mutation 直接失败，不使用 Background Sync。
- 新 worker 仅在用户确认后激活。
- TOTP、恢复码、邀请码、新 OBS 地址或未保存设置可见时，更新会被阻止。

## 上线检查表

- [ ] 使用独立随机 `data_encryption_key`，并在安全位置备份。
- [ ] `config.toml` 权限为 `0600`，且已被 Git 和 Docker build context 排除。
- [ ] PostgreSQL runtime role 可以执行迁移，但 PUBLIC 无权执行 SECURITY DEFINER helper。
- [ ] `secure_cookies = true`，Nginx 正确传递 `X-Forwarded-Proto https`。
- [ ] 应用仅监听 loopback，9719 未直接暴露公网。
- [ ] CookieCloud 白名单只包含管理员批准的实例。
- [ ] 日志中没有 Cookie、TOTP、token、邀请码或上游认证响应。
- [ ] 轮换 OBS token 后，旧浏览器源立即断开且无法重连。