3.0 KiB
认证与安全
初始化与管理员
新数据库不预建 Codex 账号；管理员初始化后通过 CPA authIndex 添加绑定。只有 settings.initialized 存在才视为完成安装。POST /api/v1/setup 在事务中创建唯一 admin(id=1)、通用设置和安装标记；用户名至少 3 位、密码至少 10 位。首次初始化没有额外安装令牌，因此初始化完成前不得把实例直接暴露到不可信网络。
管理员密码使用 argon2id（3 次、64 MiB、2 lanes、32 字节结果和随机 salt）保存。当前没有改密或找回接口；不要通过新增旁路直接写入明文或弱摘要。
Session 与请求来源
登录成功生成 32 字节随机 token，客户端得到七天 HttpOnly、SameSite=Strict cookie，SQLite 只保存 SHA-256 摘要。每次受保护请求回查未过期 session。登出删除当前摘要并清 cookie。
所有非 GET/HEAD 受保护请求还必须携带 X-Requested-With: codex-helper。这是当前同源部署下的额外 CSRF 门禁，不替代 session 校验，也不意味着可以放宽 CSP 或 cookie 策略。Secure 当前为 false，以支持 README 中直接 HTTP 部署；公网必须由 HTTPS 反向代理保护，调整此兼容行为时同步评估代理终止 TLS 的方式。
登录失败限流仅存在于单进程内，以 RemoteAddr 为 key，每 15 分钟最多 10 次。修改反向代理或客户端 IP 处理时，不能未经可信代理白名单就相信任意转发头。
密钥与外部凭据
security.OpenVault 首次启动创建权限 0600 的 /data/secret.key。SMTP 密码和 Telegram Bot Token 使用该 32 字节密钥经 AES-GCM 加密，密文写入 SQLite；GET 和保存响应不得返回秘密明文，空密码/Token 表示保留旧值。
Codex OAuth 凭据由外部 CLIProxyAPI 保存和刷新，不进入 Codex Helper。每条本地账号记录只保存非秘密的 CPA authIndex；CLIPROXY_API_MANAGEMENT_KEY 只从服务端环境变量读取，不写入 SQLite、日志、前端状态或响应。secret.key、数据库、部署 .env、CPA management key 和 CPA 凭据目录都属于敏感运行信息，不得提交 Git、加入镜像层或复制到前端。
HTTP 边界
初始化完成后，标记为公开的账号列表和 Dashboard 以匿名只读方式开放，供公开总览加载；未标记账号对匿名请求不可见。匿名响应不返回邮箱、CPA authIndex、Codex 认证方式、账号配置校验字段或内部错误。新增或修改 CPA 绑定、同步、删除、公开状态修改、提醒和所有设置接口仍必须经过 require 的 session 与来源校验。
JSON 解码限制为 1 MiB 并拒绝未知字段。统一安全头包括限制性 CSP、nosniff、禁止 iframe 和 same-origin referrer。前端路由、按钮禁用和邮箱掩码均不是服务端授权边界；所有新敏感端点必须在后端经过 require，改变 API 方法时还要核对来源头逻辑。公开账号响应必须清空 authIndex，避免把 CPA 内部凭据标识暴露给匿名访问者。