# ADR-008：本地 API 用户认证

## 状态
已接受

## 决策

- SQLite 的 `users` 表保存唯一用户名、PBKDF2-SHA256（600,000 次迭代、随机 salt）密码哈希、启用状态和管理员标志；不保存明文密码。
- 不提供公开注册接口。`./scripts/init_db.sh` 执行迁移并在缺失时创建默认管理员 `gly / maxta2026`；重复运行不会覆盖已有密码。首次登录必须重置公开的初始密码。
- `POST /api/v1/auth/login` 成功后签发 HMAC-SHA256 access token 和随机 refresh token；数据库只保存 refresh token 的 SHA-256 摘要。默认 access token 有效 1 小时，refresh token 有效 8 小时。
- 认证中间件只放行 `/api/v1/health`、登录与刷新接口；其余 `/api/v1/*` 请求必须携带有效 access token，并在 SQLite 中再次确认用户和会话仍有效。
- `POST /api/v1/auth/refresh` 必须携带 `Idempotency-Key`，每次成功都轮换 refresh token。同一旧 token 与同一幂等键返回字节级相同的响应；旧 token 换键重放则撤销整个 token family。数据库原子消费旧 token，唯一约束防止并发产生多个后继。
- access token 剩余时间不超过 `AUTH_TOKEN_REFRESH_WINDOW_SECONDS`（默认 30 分钟）时才允许续约；过早请求返回 `409 REFRESH_NOT_DUE` 及 `refresh_after`，且不消费 refresh token。每次成功续约都从当前时间重新计算 access 与 refresh 过期时间，不设固定登录总时长上限。
- 已登录用户可通过 `GET /api/v1/auth/me` 读取本人资料和管理员标志。
- 管理员可创建、列出、启停和删除用户；普通用户没有这些权限，且管理员不能禁用或删除自己的当前账号。
- 用户可通过 `PATCH /api/v1/auth/password` 提交当前密码和至少 8 位的新密码修改本人密码；管理员可通过 `PATCH /api/v1/auth/users/{id}/password` 无需旧密码地重置他人密码。两条路径都更新密码哈希并递增令牌版本，该用户此前签发的全部令牌立即失效。
- provider 配置读取与模型调用要求登录；创建、更新和删除连接配置还要求管理员权限。
- 登出撤销当前 access token 及其 refresh token family；不存储原始令牌。
- 认证失败返回统一的 401 `UNAUTHORIZED` 与 `WWW-Authenticate: Bearer`；日志记录失败原因、请求 ID 和成功用户 ID，但绝不记录密码或令牌。

## 结果与边界

禁用用户、密码重置、登出或检测刷新令牌重放会在下一次请求立刻失效。当前不提供会话列表或远程逐设备下线；有该产品需求时再增加管理接口。