baozaotumao2025
2.6 KiB
2.6 KiB
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，但绝不记录密码或令牌。
结果与边界
禁用用户、密码重置、登出或检测刷新令牌重放会在下一次请求立刻失效。当前不提供会话列表或远程逐设备下线；有该产品需求时再增加管理接口。