@nihplod/sso-sdk 1.3.1 → 1.4.1

package/dist/next/index.d.ts

@@ -159,7 +159,9 @@ declare function createCallbackRouteHandler(config: CallbackRouteConfig): (reque
  * 在 /api/auth/logout 路由中处理本地登出 + RP-Initiated Logout：
  * 1. 从 cookie 读取 refresh_token 并调用 revocation_endpoint 撤销
  * 2. 清除所有 SSO cookie
- * 3. 可选重定向到 SSO 中心登出页
+ * 3. 按退出范围（defaultScope / 表单 global 字段）决定：
+ *    - "local"（默认）：仅退出本站，重定向回本站首页
+ *    - "global"：重定向到 SSO 中心 end-session，全局退出所有 NIHPLOD 平台
  *
  * 用法 (src/app/api/auth/logout/route.ts):
  * ```ts
@@ -193,7 +195,18 @@ interface LogoutRouteConfig {
     clientSecret?: string;
     /** 登出后跳转回子项目的地址，默认取 redirectUri 的 origin */
     postLogoutRedirectUri?: string;
-    /** 是否重定向到 SSO 中心登出页，默认 true */
+    /**
+     * 默认退出范围（默认 "local"）：
+     * - "local"：仅退出本站（撤销 refresh_token + 清本地 cookie），不跳转 SSO 中心；
+     * - "global"：同时跳转 SSO 中心 end-session 全局退出（RP-Initiated Logout）。
+     * 用户可在 GET 确认页勾选"同时退出所有 NIHPLOD 平台"后通过表单字段
+     * global=1 覆盖默认值；POST 表单携带 global 字段时以表单为准。
+     */
+    defaultScope?: "local" | "global";
+    /**
+     * @deprecated 请改用 defaultScope（true → "global"，false → "local"）。
+     * 仅为兼容保留；与 defaultScope 同时传入时以 defaultScope 为准。
+     */
     redirectToSso?: boolean;
     /** Access Token Cookie 名称 */
     accessTokenCookieName?: string;
@@ -230,6 +243,63 @@ interface LogoutRouteConfig {
 }
 declare function createLogoutRouteHandler(config: LogoutRouteConfig): (request: NextRequest) => Promise<NextResponse<unknown>>;
 
+/** 验证通过的 logout_token 负载（仅暴露子站清会话所需的标识） */
+interface LogoutTokenPayload {
+    sub?: string;
+    sid?: string;
+}
+
+/**
+ * App Router Backchannel Logout 接收端 Route Handler
+ *
+ * 接收 SSO 中心在用户全局登出 / 撤销授权时推送的 logout_token
+ * （OIDC Back-Channel Logout 1.0），验证通过后清除本站 SSO cookie 并
+ * 调用 onLogout 钩子（子站在钩子里清除自己的本地会话，如数据库 session）。
+ *
+ * 前置条件：在 SSO 中心管理后台为本 client 注册 backchannelLogoutUri
+ * 指向本路由的公网地址（必须 HTTPS）。
+ *
+ * 用法 (src/app/api/auth/backchannel-logout/route.ts):
+ * ```ts
+ * import { createBackchannelLogoutRouteHandler } from "@nihplod/sso-sdk/next";
+ *
+ * export const POST = createBackchannelLogoutRouteHandler({
+ *   clientId: "my-app",
+ *   ssoBaseUrl: "https://nihplod.cn",
+ *   onLogout: async ({ sub, sid }) => {
+ *     // 清除子站本地会话（按 sub 或 sid 定位）
+ *   },
+ * });
+ * ```
+ */
+
+interface BackchannelLogoutRouteConfig {
+    /** OAuth Client ID（logout_token 的 aud 必须等于它） */
+    clientId: string;
+    /** SSO 中心地址（Discovery / JWKS 基准） */
+    ssoBaseUrl: string;
+    /**
+     * 登出通知钩子：logout_token 验证通过后调用，
+     * 子站在此处按 sub / sid 清除自己的本地会话（数据库 session 等）。
+     * 抛错时返回 500，让 IdP 重投。
+     */
+    onLogout?: (payload: LogoutTokenPayload, request: NextRequest) => void | Promise<void>;
+    /** Access Token Cookie 名称 */
+    accessTokenCookieName?: string;
+    /** Refresh Token Cookie 名称 */
+    refreshTokenCookieName?: string;
+    /** ID Token Cookie 名称，默认 __Host-nihplod_sso_id */
+    idTokenCookieName?: string;
+    /**
+     * 本地 HTTP 开发模式（默认 false）。关闭 Cookie 的 Secure 属性并去除
+     * __Host-/__Secure- 前缀；必须与 middleware / callback / logout 的配置保持一致。
+     * 生产严禁启用——生产环境（NODE_ENV=production 且 ssoBaseUrl 为 https）下
+     * 该开关会被强制忽略并告警。
+     */
+    insecureLocalDev?: boolean;
+}
+declare function createBackchannelLogoutRouteHandler(config: BackchannelLogoutRouteConfig): (request: NextRequest) => Promise<NextResponse<unknown>>;
+
 /**
  * Next.js 集成默认 Cookie 名称
  *
@@ -271,4 +341,4 @@ declare function getSecureCookieOptions(maxAge?: number, path?: string, secure?:
     maxAge?: number;
 };
 
-export { type CallbackRouteConfig, DEFAULT_ACCESS_TOKEN_COOKIE_NAME, DEFAULT_ID_TOKEN_COOKIE_NAME, DEFAULT_LOGOUT_STATE_COOKIE_NAME, DEFAULT_NONCE_COOKIE_NAME, DEFAULT_REFRESH_TOKEN_COOKIE_NAME, DEFAULT_RETURN_COOKIE_NAME, DEFAULT_STATE_COOKIE_NAME, DEFAULT_VERIFIER_COOKIE_NAME, type LogoutRouteConfig, type SsoMiddlewareConfig, createCallbackRouteHandler, createLogoutRouteHandler, createSsoMiddleware, getHostCookieOptions, getSecureCookieOptions, toInsecureCookieName };
+export { type BackchannelLogoutRouteConfig, type CallbackRouteConfig, DEFAULT_ACCESS_TOKEN_COOKIE_NAME, DEFAULT_ID_TOKEN_COOKIE_NAME, DEFAULT_LOGOUT_STATE_COOKIE_NAME, DEFAULT_NONCE_COOKIE_NAME, DEFAULT_REFRESH_TOKEN_COOKIE_NAME, DEFAULT_RETURN_COOKIE_NAME, DEFAULT_STATE_COOKIE_NAME, DEFAULT_VERIFIER_COOKIE_NAME, type LogoutRouteConfig, type SsoMiddlewareConfig, createBackchannelLogoutRouteHandler, createCallbackRouteHandler, createLogoutRouteHandler, createSsoMiddleware, getHostCookieOptions, getSecureCookieOptions, toInsecureCookieName };

package/dist/next/index.js

@@ -28,6 +28,7 @@ __export(next_exports, {
   DEFAULT_RETURN_COOKIE_NAME: () => DEFAULT_RETURN_COOKIE_NAME,
   DEFAULT_STATE_COOKIE_NAME: () => DEFAULT_STATE_COOKIE_NAME,
   DEFAULT_VERIFIER_COOKIE_NAME: () => DEFAULT_VERIFIER_COOKIE_NAME,
+  createBackchannelLogoutRouteHandler: () => createBackchannelLogoutRouteHandler,
   createCallbackRouteHandler: () => createCallbackRouteHandler,
   createLogoutRouteHandler: () => createLogoutRouteHandler,
   createSsoMiddleware: () => createSsoMiddleware,
@@ -121,6 +122,7 @@ function matchesPath(pathname, paths) {
 var introspectionCache = /* @__PURE__ */ new Map();
 var INTROSPECT_CACHE_TTL_MS = 3e4;
 var INTROSPECT_CACHE_MAX_ENTRIES = 500;
+var INTROSPECT_TIMEOUT_MS = 5e3;
 async function introspectCacheKey(token, clientId) {
   const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(token));
   const hex = Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
@@ -153,7 +155,7 @@ async function introspectAccessToken(token, ssoBaseUrl, clientId, clientSecret)
   const cacheKey = await introspectCacheKey(token, clientId);
   const cached = introspectCacheGet(cacheKey);
   if (cached) {
-    return cached.active;
+    return cached.active ? "active" : "inactive";
   }
   try {
     const body = new URLSearchParams({
@@ -167,21 +169,22 @@ async function introspectAccessToken(token, ssoBaseUrl, clientId, clientSecret)
     const res = await fetch(`${ssoBaseUrl}/api/oauth/introspect`, {
       method: "POST",
       headers: { "Content-Type": "application/x-www-form-urlencoded" },
-      body: body.toString()
+      body: body.toString(),
+      signal: AbortSignal.timeout(INTROSPECT_TIMEOUT_MS)
     });
     if (!res.ok) {
       if (res.status !== 401 && res.status !== 403) {
-        return false;
+        return "unreachable";
       }
       introspectCacheSet(cacheKey, false);
-      return false;
+      return "inactive";
     }
     const data = await res.json();
     const active = data.active === true;
     introspectCacheSet(cacheKey, active);
-    return active;
+    return active ? "active" : "inactive";
   } catch {
-    return false;
+    return "unreachable";
   }
 }
 function createSsoMiddleware(config) {
@@ -231,13 +234,13 @@ function createSsoMiddleware(config) {
     const ssoSession = request.cookies.get(ssoCookieName);
     if (ssoSession?.value) {
       if (validateSsoCookie) {
-        const tokenActive = await introspectAccessToken(
+        const introspectResult = await introspectAccessToken(
           ssoSession.value,
           normalizedServerBase,
           clientId,
           clientSecret
         );
-        if (tokenActive) {
+        if (introspectResult === "active") {
           return import_server.NextResponse.next();
         }
       } else {
@@ -246,13 +249,19 @@ function createSsoMiddleware(config) {
     }
     const accessTokenCookie = request.cookies.get(accessTokenCookieName);
     if (accessTokenCookie?.value) {
-      const tokenActive = await introspectAccessToken(
+      const introspectResult = await introspectAccessToken(
         accessTokenCookie.value,
         normalizedServerBase,
         clientId,
         clientSecret
       );
-      if (tokenActive) {
+      if (introspectResult === "active") {
+        return import_server.NextResponse.next();
+      }
+      if (introspectResult === "unreachable") {
+        console.warn(
+          "[SSO SDK] introspection \u4E0D\u53EF\u8FBE\uFF08\u7F51\u7EDC\u5F02\u5E38/\u8D85\u65F6/5xx\uFF09\uFF0C\u5BF9\u6301\u6709 SSO access token Cookie \u7684\u8BF7\u6C42 fail-open \u653E\u884C\uFF1B\u654F\u611F\u6570\u636E\u7684\u9274\u6743\u7531 Route Handler \u515C\u5E95\u3002"
+        );
         return import_server.NextResponse.next();
       }
     }
@@ -790,6 +799,9 @@ function buildLogoutConfirmHtml() {
 <body style="display:flex;align-items:center;justify-content:center;min-height:100vh;font-family:system-ui,sans-serif;">
   <form method="post" style="text-align:center;">
     <p>\u786E\u5B9A\u8981\u9000\u51FA\u767B\u5F55\u5417\uFF1F</p>
+    <label style="display:flex;align-items:center;justify-content:center;gap:6px;margin:12px 0;font-size:14px;color:#374151;cursor:pointer;">
+      <input type="checkbox" name="global" value="1">\u540C\u65F6\u9000\u51FA\u6240\u6709 NIHPLOD \u5E73\u53F0
+    </label>
     <button type="submit" style="padding:10px 20px;background-color:#ef4444;color:white;border:none;border-radius:8px;cursor:pointer;font-size:14px;">\u9000\u51FA\u767B\u5F55</button>
     <p><a href="/" style="color:#2563eb;text-decoration:underline;">\u53D6\u6D88\u5E76\u8FD4\u56DE\u9996\u9875</a></p>
   </form>
@@ -817,10 +829,18 @@ function createLogoutRouteHandler(config) {
     redirectUri,
     clientSecret,
     postLogoutRedirectUri = new URL(redirectUri).origin + "/",
-    redirectToSso = true,
     callbackPath = "/api/auth/callback",
     insecureLocalDev: insecureLocalDevOpt = false
   } = config;
+  let defaultScope = config.defaultScope ?? "local";
+  if (config.redirectToSso !== void 0) {
+    console.warn(
+      '[SSO SDK] redirectToSso \u5DF2\u5F03\u7528\uFF0C\u8BF7\u6539\u7528 defaultScope\uFF08redirectToSso: true \u2192 defaultScope: "global"\uFF0Cfalse \u2192 "local"\uFF09\u3002\u6CE8\u610F\uFF1A\u9ED8\u8BA4\u9000\u51FA\u8303\u56F4\u5DF2\u53D8\u66F4\u4E3A "local"\uFF08\u4EC5\u9000\u51FA\u672C\u7AD9\uFF0C\u4E0D\u8DF3\u8F6C SSO \u4E2D\u5FC3\uFF09\u3002'
+    );
+    if (config.defaultScope === void 0) {
+      defaultScope = config.redirectToSso ? "global" : "local";
+    }
+  }
   const insecureLocalDev = resolveInsecureLocalDev(insecureLocalDevOpt, ssoBaseUrl);
   const secureCookies = !insecureLocalDev;
   const pickName = (explicit, fallback) => insecureLocalDev ? toInsecureCookieName(explicit ?? fallback) : explicit ?? fallback;
@@ -855,6 +875,12 @@ function createLogoutRouteHandler(config) {
         headers: { "content-type": "text/html; charset=utf-8" }
       });
     }
+    let formGlobal = null;
+    try {
+      formGlobal = new URLSearchParams(await request.text()).get("global");
+    } catch {
+    }
+    const effectiveScope = formGlobal !== null ? formGlobal === "1" || formGlobal === "true" ? "global" : "local" : defaultScope;
     const refreshToken = request.cookies.get(refreshTokenCookieName)?.value;
     const idTokenHint = request.cookies.get(idTokenCookieName)?.value;
     if (refreshToken) {
@@ -889,7 +915,7 @@ function createLogoutRouteHandler(config) {
       res.cookies.set(verifierCookieName, "", getSecureCookieOptions(0, callbackPath, secureCookies));
       return res;
     };
-    if (redirectToSso) {
+    if (effectiveScope === "global") {
       const discovery = await fetchDiscoveryCached(normalizedServerBase);
       const endSessionEndpoint = discovery?.end_session_endpoint || `${normalizedBase}/api/oauth/end-session`;
       const logoutUrl = new URL(endSessionEndpoint);
@@ -912,6 +938,198 @@ function createLogoutRouteHandler(config) {
     );
   };
 }
+
+// src/next/backchannel-logout.ts
+var import_server4 = require("next/server");
+
+// src/core/logout-token.ts
+var BACKCHANNEL_LOGOUT_EVENT = "http://schemas.openid.net/event/backchannel-logout";
+var JTI_CACHE_CAPACITY = 1e3;
+var seenJti = /* @__PURE__ */ new Map();
+function recordJti(jti, expiresAtMs) {
+  const now = Date.now();
+  const existing = seenJti.get(jti);
+  if (existing !== void 0 && existing > now) return false;
+  for (const [key, exp] of seenJti) {
+    if (exp <= now) seenJti.delete(key);
+  }
+  while (seenJti.size >= JTI_CACHE_CAPACITY) {
+    const oldest = seenJti.keys().next().value;
+    if (oldest === void 0) break;
+    seenJti.delete(oldest);
+  }
+  seenJti.set(jti, expiresAtMs);
+  return true;
+}
+async function verifyLogoutToken(logoutToken, ssoBaseUrl, clientId) {
+  const baseUrl = ssoBaseUrl.replace(/\/+$/, "");
+  const header = decodeJwtHeader(logoutToken);
+  if (!header) {
+    throw new SsoError("logout_token_invalid", "Logout Token \u683C\u5F0F\u9519\u8BEF");
+  }
+  if (header.alg !== "RS256") {
+    throw new SsoError(
+      "logout_token_unsupported_alg",
+      `\u4E0D\u652F\u6301\u7684 Logout Token \u7B7E\u540D\u7B97\u6CD5: ${String(header.alg)}`
+    );
+  }
+  const discovery = await fetchDiscoveryDoc(baseUrl);
+  const normalizedIssuer = (discovery?.issuer || baseUrl).replace(/\/+$/, "");
+  const jwks = await fetchJwks(baseUrl);
+  if (!jwks) {
+    throw new SsoError(
+      "logout_token_invalid_signature",
+      "\u65E0\u6CD5\u83B7\u53D6 JWKS \u9A8C\u8BC1 Logout Token \u7B7E\u540D"
+    );
+  }
+  const kid = typeof header.kid === "string" ? header.kid : void 0;
+  const matchCandidates = (set) => set.keys.filter(
+    (k) => k.kty === "RSA" && k.alg === "RS256" && k.use === "sig" && (kid ? k.kid === kid : true)
+  );
+  const verifyAny = async (keys) => {
+    for (const key of keys) {
+      if (await verifyRs256Signature(logoutToken, key)) return true;
+    }
+    return false;
+  };
+  let candidates = matchCandidates(jwks);
+  let validSig = candidates.length > 0 ? await verifyAny(candidates) : false;
+  if (candidates.length === 0 || !validSig) {
+    const freshJwks = await fetchJwks(baseUrl, { forceRefresh: true });
+    if (freshJwks) {
+      candidates = matchCandidates(freshJwks);
+      validSig = candidates.length > 0 ? await verifyAny(candidates) : false;
+    }
+  }
+  if (candidates.length === 0) {
+    throw new SsoError(
+      "logout_token_invalid_signature",
+      "JWKS \u4E2D\u672A\u627E\u5230\u5339\u914D\u7684 RS256 \u516C\u94A5"
+    );
+  }
+  if (!validSig) {
+    throw new SsoError(
+      "logout_token_invalid_signature",
+      "Logout Token \u7B7E\u540D\u9A8C\u8BC1\u5931\u8D25"
+    );
+  }
+  const payload = decodeJwtPayload(logoutToken);
+  if (!payload) {
+    throw new SsoError("logout_token_invalid", "Logout Token payload \u89E3\u6790\u5931\u8D25");
+  }
+  const tokenIssuer = typeof payload.iss === "string" ? payload.iss.replace(/\/+$/, "") : "";
+  if (tokenIssuer !== normalizedIssuer) {
+    throw new SsoError(
+      "logout_token_issuer_mismatch",
+      "Logout Token issuer \u4E0D\u5339\u914D"
+    );
+  }
+  const aud = payload.aud;
+  const audList = Array.isArray(aud) ? aud : typeof aud === "string" ? [aud] : [];
+  if (!audList.includes(clientId)) {
+    throw new SsoError(
+      "logout_token_audience_mismatch",
+      "Logout Token audience \u4E0D\u5339\u914D"
+    );
+  }
+  if (typeof payload.exp !== "number") {
+    throw new SsoError("logout_token_invalid", "Logout Token \u7F3A\u5C11 exp \u58F0\u660E");
+  }
+  if (Date.now() >= payload.exp * 1e3 + 6e4) {
+    throw new SsoError("logout_token_expired", "Logout Token \u5DF2\u8FC7\u671F");
+  }
+  const events = payload.events;
+  if (!events || typeof events !== "object" || !(BACKCHANNEL_LOGOUT_EVENT in events)) {
+    throw new SsoError(
+      "logout_token_invalid",
+      "Logout Token \u7F3A\u5C11 backchannel-logout events \u58F0\u660E"
+    );
+  }
+  const sub = typeof payload.sub === "string" && payload.sub ? payload.sub : void 0;
+  const sid = typeof payload.sid === "string" && payload.sid ? payload.sid : void 0;
+  if (!sub && !sid) {
+    throw new SsoError(
+      "logout_token_invalid",
+      "Logout Token \u5FC5\u987B\u5305\u542B sub \u6216 sid \u81F3\u5C11\u5176\u4E00"
+    );
+  }
+  const jti = typeof payload.jti === "string" ? payload.jti : "";
+  if (!jti) {
+    throw new SsoError("logout_token_invalid", "Logout Token \u7F3A\u5C11 jti \u58F0\u660E");
+  }
+  if (!recordJti(jti, payload.exp * 1e3 + 6e4)) {
+    throw new SsoError("logout_token_replay", "Logout Token jti \u91CD\u653E");
+  }
+  return { sub, sid };
+}
+
+// src/next/backchannel-logout.ts
+function createBackchannelLogoutRouteHandler(config) {
+  const { clientId, ssoBaseUrl, onLogout } = config;
+  const insecureLocalDev = resolveInsecureLocalDev(
+    config.insecureLocalDev ?? false,
+    ssoBaseUrl
+  );
+  const secureCookies = !insecureLocalDev;
+  const pickName = (explicit, fallback) => insecureLocalDev ? toInsecureCookieName(explicit ?? fallback) : explicit ?? fallback;
+  const accessTokenCookieName = pickName(
+    config.accessTokenCookieName,
+    DEFAULT_ACCESS_TOKEN_COOKIE_NAME
+  );
+  const refreshTokenCookieName = pickName(
+    config.refreshTokenCookieName,
+    DEFAULT_REFRESH_TOKEN_COOKIE_NAME
+  );
+  const idTokenCookieName = pickName(
+    config.idTokenCookieName,
+    DEFAULT_ID_TOKEN_COOKIE_NAME
+  );
+  return async function handler(request) {
+    if (request.method !== "POST") {
+      return import_server4.NextResponse.json(
+        { error: "method_not_allowed", error_description: "\u4EC5\u63A5\u53D7 POST \u8BF7\u6C42" },
+        { status: 405 }
+      );
+    }
+    const logoutToken = new URLSearchParams(await request.text()).get(
+      "logout_token"
+    );
+    if (!logoutToken) {
+      return import_server4.NextResponse.json(
+        { error: "invalid_request", error_description: "\u7F3A\u5C11 logout_token" },
+        { status: 400 }
+      );
+    }
+    let payload;
+    try {
+      payload = await verifyLogoutToken(logoutToken, ssoBaseUrl, clientId);
+    } catch (err) {
+      const code = err instanceof SsoError ? err.code : "logout_token_invalid";
+      const description = err instanceof SsoError ? err.description : "Logout Token \u9A8C\u8BC1\u5931\u8D25";
+      return import_server4.NextResponse.json(
+        { error: code, error_description: description },
+        { status: 400 }
+      );
+    }
+    try {
+      await onLogout?.(payload, request);
+    } catch (err) {
+      console.error(
+        "[SSO SDK] backchannel logout onLogout \u94A9\u5B50\u6267\u884C\u5931\u8D25:",
+        err
+      );
+      return import_server4.NextResponse.json(
+        { error: "server_error", error_description: "onLogout \u5904\u7406\u5931\u8D25" },
+        { status: 500 }
+      );
+    }
+    const res = new import_server4.NextResponse(null, { status: 200 });
+    res.cookies.set(accessTokenCookieName, "", getHostCookieOptions(0, secureCookies));
+    res.cookies.set(refreshTokenCookieName, "", getHostCookieOptions(0, secureCookies));
+    res.cookies.set(idTokenCookieName, "", getHostCookieOptions(0, secureCookies));
+    return res;
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_ACCESS_TOKEN_COOKIE_NAME,
@@ -922,6 +1140,7 @@ function createLogoutRouteHandler(config) {
   DEFAULT_RETURN_COOKIE_NAME,
   DEFAULT_STATE_COOKIE_NAME,
   DEFAULT_VERIFIER_COOKIE_NAME,
+  createBackchannelLogoutRouteHandler,
   createCallbackRouteHandler,
   createLogoutRouteHandler,
   createSsoMiddleware,