接入验收清单

接入档案

• 已明确选择 greenfield 或 legacy-migration，没有混用两套流程。
• greenfield 没有伪造迁移数据；legacy-migration 没有通过首次登录创建空账号。

App 与 Manifest

• appKey 唯一、稳定、全小写。
• Manifest 使用 Schema 2.0、authorizationMode=application_owned。
• Manifest 只包含元数据和需要的 requiredContext，没有业务 roles、permissions 或 Secret。
• dev、staging、prod 使用独立 OAuth Client、callback 和 Secret。
• 组织级 App 已开通，应用地址与回调地址均为预期 HTTPS 地址。

登录与 Session

• login 使用随机 state 和 PKCE S256，callback 在服务端交换 code。
• Client Secret 与 opaque App Session 从不进入浏览器 JavaScript、日志或仓库。
• Session Cookie 为 HttpOnly、SameSite=Lax，HTTPS 环境为 Secure。
• 每个受保护请求调用 requireAppAccess，并校验当前 appKey。
• App Session 为 0.3，authorizationDomain=application，不依赖业务 roles/permissions 字段。
• 单 App 登出、全局登出、过期、撤销和跨 App session 均正确失败。

本地授权

• 使用 session.user.id 建立唯一 iwish_auth_user_id 本地成员关联，不按邮箱即时猜测。
• 业务 App 自己保存成员、角色、permission、数据范围和变更审计。
• 无本地成员、成员停用、无角色或权限不足均 fail closed 并返回 403。
• 每个高风险服务端动作重新执行本地 permission 与资源数据范围检查。
• 前端隐藏按钮不能替代服务端授权。
• 已移除 Auth requirePermission、远程业务权限检查和中央业务角色分配依赖。

Greenfield 新应用

以下项目只适用于 greenfield：

• 使用新数据库，不存在需要保留的生产账号、身份外键或旧 Session。
• App 管理员通过 App 服务端和最小权限 Service Token 查询 Auth 受控身份目录。
• 管理员选择身份并在一个事务中创建本地成员、角色分配和 append-only 审计。
• 管理员不手工复制或粘贴 Auth User ID。
• 第一次登录不会自动授予 admin、viewer 或其他默认角色。
• 不自动创建没有明确角色和审计的空成员。
• 首个 App 管理员通过受控 bootstrap 或部署审批创建，不采用首个登录者自动升级。
• 没有生成 auth-migration-plan.json、mapping ledger 或伪造历史迁移数据。

Legacy 存量账号迁移

以下项目只适用于 legacy-migration：

• 已生成并通过 CLI 校验 auth-migration-plan.json，实例文件不包含逐用户 PII。
• 原本地用户主键保持不变，所有项目负责人、创建人、审批人和审计外键保持不变。
• iwish_auth_user_id 可空但非空值唯一；不建立跨数据库外键。
• 逐用户 mapping ledger 位于 App 私有数据库或加密离线工件。
• 只允许飞书员工 ID、已验证企业邮箱、已验证外部邮箱和人工复核四种匹配方式。
• 运行期邮箱自动关联、姓名/手机号匹配和未映射用户空账号创建均已禁用。
• production cutover_ready 时 conflicts=0 且 pending=0。
• 旧密码不导入 Auth；旧密码 hash 只保留到观察期结束或在切换时清除。
• 旧登录、密码重置和旧 Session 接受路径在切换时同时关闭。
• 机器任务和共享账号已迁移到 Service Account 或明确拆分。

员工与客户项目

• 内部员工通过飞书登录，外部账号通过邀请或邮箱密码登录。
• employee 为空时业务 App 能正确处理；外部账号不被伪装为员工。
• clientAssignments 只用于项目上下文，不替代 App 本地 permission。
• assignment 存在但本地权限不足仍返回 403。
• assignment 为空时不会自动扩大到全部项目，也不会误判为未登录。
• 飞书员工离职、冻结或 Auth 用户停用后，即使本地角色仍存在也不能访问。

禁止旁路

• 业务 App 没有直接接飞书、Supabase Auth 或 Auth 数据库。
• 不信任 x-user-id、x-role、邮箱或前端提交的数据范围。
• 没有 Auth Proxy、长期双登录、第二套内部员工密码或共享 OAuth Client。
• 网络错误、契约不匹配和未知状态全部默认拒绝。

真实验收

• 使用真实 staging 飞书员工、外部邮箱账号和专用离职测试账号。
• App 管理员在业务 App 内创建成员并分配本地 viewer/member/manager/admin。
• greenfield 通过受控身份目录开通成员；legacy-migration 通过预绑定命中原成员。
• 本地角色修改立即改变业务权限，而 Auth 客户项目分工保持不变。
• Auth 客户项目分工修改会更新上下文，但不会自动扩大本地角色。
• callback 错误、code 重放、跨 Client、跨 App、伪造 Header 和 Secret 泄漏检查通过。