SDK 0.3 参考

SDK 0.3 负责登录、授权码交换、App Session 解析、身份与公共上下文读取、登出和 Webhook 验签。它不判断业务 App 的本地角色或权限。

TypeScript Client

exchangeAuthorizationCode(request)：服务端使用 Client Secret 与 PKCE verifier 交换一次性 code。
getAppSession({ forceRefresh? })：解析 opaque App Session 0.3。
getIdentity()：读取稳定 IWish Auth 用户身份。
getEmployeeContext()：读取飞书员工、部门、岗位、上级和在职状态。
getClientAssignments()：读取当前有效客户项目职责。
revokeAppSession()：撤销当前 App session。

checkPermission、checkPermissionsBatch 和 checkUserPermission 已退出公开业务授权契约，调用会返回 410 application_owned_authorization。新代码不得依赖这些方法。

Next.js Adapter

createIWishAuth(options) 提供 beginLogin、handleCallback、logout、getSession、requireAuth、requireAppAccess、requireOrganization 和 getClientAssignments。受保护路由先调用 requireAppAccess，再使用 session.user.id 查询 App 本地成员并执行本地授权。

const session = await auth.requireAppAccess(request);
const member = await members.requireActive(session.user.id);
await permissions.require(member.id, "report.read");

旧 requirePermission 仅保留为明确失败的迁移护栏，不是可用授权 API。

Express Adapter

createIWishExpressAuth(options) 提供 requireAuth()、requireAppAccess() 和 requireOrganization() middleware。成功后把 { context, token } 写入 request.iwishAuth。随后调用业务 App 自己的成员与权限 middleware。不要从浏览器 Header 接收角色。

Python 与 FastAPI

Python Client 提供 exchange_authorization_code、get_app_session、get_identity、get_employee_context、get_client_assignments 和 revoke_app_session。FastAPI Adapter 提供 login、callback、logout、get_session、require_auth、require_app_access、require_organization 和 get_client_assignments。

check_permission、check_permissions_batch、check_user_permission 和 require_permission 同样只返回 410 迁移错误。

App Session 0.3

稳定字段为：sessionVersion="0.3"、authorizationDomain="application"、session、user、employee、clientAssignments、organization 和 app。app.authorizationMode 为 application_owned。响应中不存在业务 roles、permissions 或 matchedRoles；SDK 发现旧结构或跨 App session 时必须 fail closed。

错误处理

401 表示没有有效统一身份，通常跳转登录；403 表示 Auth 层用户、员工、组织、App 或 OAuth Client 不可用，不应循环登录；410 application_owned_authorization 表示仍在调用已退出的中央业务权限 API；429 应按 Retry-After 重试；5xx 应记录 request ID 并默认拒绝。业务 App 本地成员或权限不足统一由 App 返回自己的 403 错误码。

Webhook 使用 verifyIWishWebhook 或 verify_iwish_webhook 校验时间戳、HMAC-SHA256 签名和事件 ID。所有 Client Secret、Service Token 和 Webhook Secret 仅放在服务端 Secret 管理中。