Express 接入

Express Adapter 负责解析 IWish Auth App Session 和恢复统一身份。业务 App 必须在其后连接自己的成员与授权 middleware。

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

const iwishAuth = createIWishExpressAuth({
  apiUrl: process.env.IWISH_AUTH_API_URL!,
  appKey: "reporting",
  cookieName: "iwish_reporting_session"
});

app.get(
  "/api/reports",
  iwishAuth.requireAuth(),
  iwishAuth.requireAppAccess(),
  requireLocalMember(),
  requireLocalPermission("report.read"),
  async (request, response) => {
    const session = request.iwishAuth!.context;
    response.json(await loadReports({
      iwishAuthUserId: session.user.id,
      clientAssignments: session.clientAssignments
    }));
  }
);

requireAuth() 从 Bearer token 或 HttpOnly Cookie 读取 opaque token并调用 /v1/sso/session。requireAppAccess() 确认 sessionVersion=0.3、authorizationDomain=application、session 的 appKey 与当前服务配置一致，并拒绝已失效的统一身份。requireLocalMember 和 requireLocalPermission 是业务 App 自己实现的 middleware，不属于 IWish Auth SDK。

建议在 Request 类型中扩展两组字段：request.iwishAuth 保存统一身份和上下文；request.appMember 保存本地成员、角色和计算后的数据范围。不要把二者合成一个不透明布尔值，否则无法正确处理员工离职、本地角色撤销和项目分工变化。

旧版 iwishAuth.requirePermission() 只返回 410 application_owned_authorization，用于暴露未完成迁移的代码路径。不得捕获该错误后放行，也不得降级到 x-role、邮箱或前端声明角色。

错误策略：401 可引导登录；Auth 403 表示统一身份或 App 生命周期无效；本地成员不存在、停用、无角色或权限不足返回业务 App 自己的 403；Auth 网络异常与解析异常默认拒绝并记录 request ID。对高风险写操作，每次请求都重新执行本地授权和数据范围检查。