# IWish Auth

> 简体中文统一身份、飞书员工目录、客户项目上下文和跨 App SSO 平台。业务 App 自己管理成员、角色和业务权限。

## 机器可读入口

- [完整 AI 接入上下文](/llms-full.txt)
- [OpenAPI 3.1 契约](/openapi.json)
- [Auth Manifest JSON Schema](/auth-manifest.schema.json)
- [存量账号迁移计划 JSON Schema](/account-migration.schema.json)
- 本地运维入口：doctor:auth-dev（docs/AUTH_DEV_DOCTOR.md）、next:auth、bootstrap:dev-admin、e2e:auth-api
- 本地敏感变量名：SUPABASE_SERVICE_ROLE_KEY、SUPABASE_ACCESS_TOKEN、E2E_INVITE_EMAIL（仅存放于未提交的环境文件）
- Manifest 预检：POST /v1/admin/apps/{appKey}/manifest/validate
- Manifest 同步：POST /v1/admin/apps/{appKey}/manifest/sync（需要 auth.manifest.write）
- 内部员工使用飞书登录；会话通过 identitySource=feishu 和 employee 返回稳定员工上下文
- 飞书目录状态：GET /v1/admin/feishu/status（仅平台管理）
- 客户项目管理：/v1/admin/client-projects；项目团队分工：/v1/admin/client-team-assignments
- 服务端机器身份：Service Account + iwa_ Service Token；Manifest 自动化使用 auth.manifest.write scope
- Webhook：HMAC-SHA256 签名、IWish-Event-Id 幂等、最多 5 次重试和死信
- Webhook 验签：TypeScript verifyIWishWebhook；Python verify_iwish_webhook

## 文档索引

- [快速开始](/): 完成统一登录、上下文与 App 本地授权接入
- [接入流程概览](/docs/integration-flow): 管理员、开发者和业务 App 的完整协作流程
- [Next.js](/docs/nextjs): 使用 App Router 和 TypeScript SDK 接入
- [Express](/docs/express): 使用统一中间件保护 Node.js API
- [FastAPI](/docs/fastapi): 使用 Python SDK 和依赖注入接入
- [跨 App SSO](/docs/sso): 授权码、PKCE、App session 和登出边界
- [飞书身份边界](/docs/feishu-boundary): 内部员工身份、组织同步和业务 App 禁止事项
- [客户项目上下文](/docs/client-assignments): 正确消费 clientAssignments 与业务授权
- [Manifest 2.0](/docs/manifest): 声明 App 元数据和所需统一上下文
- [App 本地权限设计](/docs/permission-naming): 本地成员、角色、权限和数据范围模型
- [SDK API Reference](/docs/sdk-reference): TypeScript 和 Python SDK 0.3 稳定接口
- [Service Token 与 Webhook](/docs/webhooks-service-tokens): 机器身份、签名验签、幂等投递和上下文缓存失效
- [受控身份目录](/docs/identity-directory): 业务 App 通过绑定的 Service Token 查询最小身份信息
- [OAuth Client 生命周期](/docs/oauth-client-lifecycle): 创建、环境隔离、Secret 轮换与停用恢复
- [外部账号与 Portal](/docs/external-accounts): 邀请、密码恢复、账号生命周期和最近访问 App
- [V1 RC 契约与发布](/docs/release-policy): 版本冻结、兼容规则、制品校验和破坏性变更要求
- [新应用接入](/docs/greenfield-integration): 从第一天使用 Auth 身份并建立 App 本地成员与角色
- [存量账号迁移与无感切换](/docs/account-migration): 预绑定原账号并保持角色、业务外键和历史数据不变
- [迁移指南](/docs/migration-guide): 从独立登录与权限体系一刀切迁移
- [迁移 Playbook](/docs/migration-playbook): 按阶段执行、回滚和验收真实 App 迁移
- [接入 Checklist](/docs/integration-checklist): 上线前逐项检查身份、权限与安全边界
- [故障排查](/docs/troubleshooting): 稳定错误码、诊断顺序和常见问题
- [AI Agent 接入指南](/docs/ai-agent): 让 AI 按确定契约完成 App 改造

## 不可突破的边界

- 内部员工使用飞书统一身份；外部账号使用邀请或邮箱密码。
- 业务 App 禁止直接接飞书、Supabase Auth 或 Auth 数据库。
- SSO code exchange 和 client secret 只能存在于业务 App 服务端。
- Service Token 和 Webhook signing secret 只能存在于服务端 Secret 管理，明文只显示一次。
- App Session 0.3 的 authorizationDomain 固定为 application，不包含业务 roles 或 permissions。
- 业务 App 使用 iwish_auth_user_id 建立本地成员，并在每个受保护动作执行本地角色、权限与数据范围检查。
- clientAssignments 只表示客户项目分工，不能替代 App 本地权限或业务数据授权。
- application_owned 表示业务授权完全归业务 App；Auth 不创建、分配或判断其业务角色。
- 不提供 Auth Proxy，不保留长期双登录或第二套内部员工账号。

## Agent 开始命令

先读取 /llms-full.txt、/openapi.json 和 /auth-manifest.schema.json，再盘点目标 App。不要猜测未声明 API。