SlideStage Pro 的认证与邀请模型

SlideStage Pro 使用关闭注册模型。用户不能随意注册，必须通过管理员创建的邀请码进入系统。

这个设计让 Pro 可以安全地部署在小团队、内网或私有 VPS 上，而不需要先实现完整的组织、多租户和公开注册体系。

核心角色

Pro v0 只需要两个角色：

• admin：管理用户邀请、查看所有 deck、执行平台管理操作。
• 普通用户：上传和管理自己有权限访问的 deck。

角色存储在用户记录上。Better Auth 负责身份和 session，Pro 在它之上增加角色和邀请规则。

登录

登录使用 Better Auth 的邮箱密码接口：

POST /api/auth/sign-in/email

成功后，浏览器持有 HttpOnly session cookie。前端通过 session 查询判断当前用户状态。

注册为什么需要邀请

Pro 是自托管系统。默认部署通常暴露在团队域名、内网或公网 VPS 上。如果允许开放注册，任何访问到页面的人都可能创建账号。

因此注册必须带 inviteToken。

注册请求缺少 token 或 token 无效时，服务端返回：

{
  "error": {
    "code": "INVITE_REQUIRED",
    "message": "Invite token is required"
  }
}

邀请生命周期

1. 管理员创建邀请。
2. 系统生成一次性 token。
3. 管理员把注册链接发给新用户。
4. 用户注册时提交 token。
5. 服务端在创建用户前验证 token。
6. 用户创建成功后，服务端标记邀请已使用，并给用户分配角色。

邀请应只能使用一次。已经使用、过期或被删除的邀请不能再次注册。

Bootstrap 管理员

首次启动时，如果数据库中还没有用户，Pro 会读取 bootstrap 环境变量创建第一个管理员。

常用变量：

• BOOTSTRAP_ADMIN_EMAIL
• BOOTSTRAP_ADMIN_PASSWORD
• BOOTSTRAP_ADMIN_NAME

如果系统没有任何用户，又缺少 bootstrap 配置，API 应拒绝继续服务。这样可以避免部署出一个没有管理员、但可能开放注册的站点。

Session 与 Cookie

生产环境中，session cookie 应满足：

• HttpOnly。
• SameSite=Lax。
• HTTPS 下 Secure。
• BETTER_AUTH_URL 与用户实际访问地址一致。

如果登录后马上变回未登录，优先检查 BETTER_AUTH_URL、反向代理协议头和公开访问域名是否一致。

前端如何使用

前端不直接读取 cookie。它通过 Better Auth client 或 session API 获取当前用户。

常见 UI 分支：

• 无 session：显示登录页。
• 有 session：进入 deck 列表。
• user.role === "admin"：显示邀请管理入口。

不要在前端只靠隐藏按钮保护管理员能力。服务端接口必须再次检查 admin 权限。

设计边界

Pro v0 暂不处理：

• OAuth 登录。
• Passkey / WebAuthn。
• 双因素认证。
• 多租户组织。
• 公开注册。
• 邮箱找回密码。

这些能力可以后续添加，但不应改变当前原则：注册入口必须默认关闭，管理员邀请是团队准入边界。