SDK API Reference

SDK 是 IWish Auth HTTP/SSO 协议的稳定封装。业务 App 应优先使用 Adapter；只有非框架服务或后台任务才直接使用 Client。

当前 JavaScript SDK 固定版本为 0.2.0，从文档站 /packages/iwish-auth-sdk-0.2.0.tgz 安装；制品元数据和 SHA256 见 /packages/index.json。

1. TypeScript Client

import { IWishAuthClient } from "@iwish/auth-sdk";

new IWishAuthClient(options)

Client 方法

• getCurrentUser()：使用统一登录 token 读取 /v1/me。
• exchangeAuthorizationCode(request)：服务端交换一次性 SSO code。
• getAppSession({ forceRefresh? })：解析 opaque App session。
• checkPermission(permission, options?)：当前 App 命名空间内本地判断。
• checkPermissionsBatch(permissions, options?)：一次 session 解析批量判断。
• getClientAssignments(options?)：返回当前有效项目分工。
• revokeAppSession()：撤销当前 App session。
• clearSessionCache()：清理 Client 短缓存。
• withToken(token)：保留配置并创建带 token 的 Client。

getBoundClients() 是兼容别名，已 deprecated；新代码使用 getClientAssignments()。

2. Next.js Adapter

import { createIWishAuth } from "@iwish/auth-sdk/next";

返回方法：

• beginLogin(request, { organizationId?, returnTo? })
• handleCallback(request)
• logout(request, { redirectTo? })
• getSession(request, forceRefresh?)
• requireAuth(request)
• requireOrganization(request)
• requireAppAccess(request)
• requirePermission(request, permission)
• getClientAssignments(request)

3. Express Adapter

import { createIWishExpressAuth } from "@iwish/auth-sdk/express";

返回 Express-like middleware factory：requireAuth()、requireAppAccess()、requireOrganization()、requirePermission(permission)。requireAuth 成功后把 { context, token } 写入 request.iwishAuth。

4. TypeScript 错误

• IWishAuthError(status, code, details?)
• IWishAuthUnauthorizedError：固定 HTTP 401。
• IWishAuthForbiddenError：固定 HTTP 403。

业务日志只记录 status、code 和自身 request id，不记录 token 或 details 中可能存在的敏感值。

5. Python Client

from iwish_auth import IWishAuthClient

主要方法与 TypeScript 一致，使用 snake_case：

• get_current_user()
• exchange_authorization_code(...)
• get_app_session(force_refresh=False)
• check_permission(permission, force_refresh=False)
• check_permissions_batch(permissions, force_refresh=False)
• get_client_assignments(force_refresh=False)
• revoke_app_session()
• clear_session_cache()
• with_token(token)
• aclose()

推荐使用 async with IWishAuthClient(...) as client 管理 httpx.AsyncClient 生命周期。

6. FastAPI Adapter

IWishFastAPIAuthOptions 配置 API、Portal、App、client 和 callback。IWishFastAPIAuth 提供 login、callback、logout、get_session、require_auth、require_app_access、require_organization、get_client_assignments 和 require_permission。

7. 上下文稳定字段

App session 的稳定顶层字段为：

session
user
employee
clientAssignments
organization
app
roles
permissions

8. Service Token 与 Webhook

• TypeScript checkUserPermission(request)：使用服务端 iwa_ Token 调用远程权限检查。
• Python check_user_permission(...)：使用服务端 Token 调用远程权限检查。
• TypeScript verifyIWishWebhook(...)：校验时间戳、HMAC-SHA256 签名、事件 ID 和 Envelope。
• Python verify_iwish_webhook(...)：与 TypeScript 验签规则一致。

完整协议见 Service Token 与 Webhook。

新字段可能向后兼容地增加。业务 App 不得对未知字段报错，也不得假设可空字段始终存在。