# IWish Auth

> 简体中文统一认证、权限、飞书员工身份和客户项目上下文平台。业务 App 只接 IWish Auth。

## 机器可读入口

- [完整 AI 接入上下文](/llms-full.txt)
- [OpenAPI 3.1 契约](/openapi.json)
- [Auth Manifest JSON Schema](/auth-manifest.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；权限检查 scope 为 auth.permission.check
- 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 规范](/docs/manifest): 声明 App、权限和角色的稳定契约
- [权限命名规范](/docs/permission-naming): 统一权限 key、粒度和兼容策略
- [SDK API Reference](/docs/sdk-reference): TypeScript 和 Python SDK 的稳定接口
- [Service Token 与 Webhook](/docs/webhooks-service-tokens): 机器身份、签名验签、幂等投递和缓存失效
- [迁移指南](/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 permission，再执行业务数据授权。
- clientAssignments 只表示客户项目分工，不能替代 permission 或业务数据授权。
- 不提供 Auth Proxy，不保留长期双登录或第二套内部员工账号。

## Agent 开始命令

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