@nihplod/sso-sdk 1.5.0 → 1.6.0

package/dist/next/index.d.mts

@@ -36,7 +36,12 @@ interface SsoMiddlewareConfig {
     redirectUri: string;
     /** 请求的 scope（空格分隔），默认 "openid profile" */
     scopes?: string;
-    /** 公开路由前缀（不需要认证） */
+    /**
+     * 公开路由前缀（不需要认证）。
+     *
+     * 注意：/api/ 下的路径永不按静态资源扩展名（.js/.css/...）放行；
+     * 如需公开某个 API 路径，必须在此显式列出。
+     */
     publicPaths?: string[];
     /** 回调路径（不触发重定向），默认 "/api/auth/callback" */
     callbackPath?: string;
@@ -298,6 +303,28 @@ interface LogoutTokenPayload {
     sub?: string;
     sid?: string;
 }
+/**
+ * jti 防重放存储接口（可注入）。
+ *
+ * 默认实现是进程内 Map（per-instance）：多实例 / Serverless 部署下各实例
+ * 互不可见，重放检查形同虚设，必须注入共享存储（如 Redis）。
+ * key 为 `${issuer}:${jti}`，ttlSeconds 为建议过期时间（logout_token exp + 60s 宽限）。
+ */
+interface LogoutJtiStore {
+    has(key: string): Promise<boolean> | boolean;
+    add(key: string, ttlSeconds: number): Promise<void> | void;
+    /**
+     * 原子 check-and-set（如 Redis `SET key 1 NX EX ttl`）：返回 false 表示
+     * key 已存在（判重放）。提供时优先使用；缺失时回退 has+add
+     * （非原子，仅单实例部署可接受：并发窗口内同一 jti 可能双双通过）。
+     */
+    addIfAbsent?(key: string, ttlSeconds: number): Promise<boolean> | boolean;
+    /**
+     * 释放已记录的 key。onLogout 钩子失败后需要允许 IdP 用同一 logout_token
+     * 重投，SDK 会调用此方法；未实现时 IdP 重投将被重放检查以 400 拒绝。
+     */
+    remove?(key: string): Promise<void> | void;
+}
 
 /**
  * App Router Backchannel Logout 接收端 Route Handler
@@ -340,6 +367,15 @@ interface BackchannelLogoutRouteConfig {
     refreshTokenCookieName?: string;
     /** ID Token Cookie 名称，默认 __Host-nihplod_sso_id */
     idTokenCookieName?: string;
+    /**
+     * jti 防重放存储（可选）。
+     *
+     * 默认实现是进程内 Map（per-instance）：多实例 / Serverless 部署下各实例
+     * 互不可见，重放保护形同虚设（IdP 重投/攻击者重放到另一实例会被当作首次）。
+     * 这类部署 MUST 注入共享存储（如 Redis：addIfAbsent = `SET key 1 NX EX ttl`，
+     * remove = `DEL key`——onLogout 失败时用于释放 jti 允许 IdP 重投）。
+     */
+    jtiStore?: LogoutJtiStore;
     /**
      * 本地 HTTP 开发模式（默认 false）。关闭 Cookie 的 Secure 属性并去除
      * __Host-/__Secure- 前缀；必须与 middleware / callback / logout 的配置保持一致。
@@ -391,4 +427,4 @@ declare function getSecureCookieOptions(maxAge?: number, path?: string, secure?:
     maxAge?: number;
 };
 
-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 };
+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 LogoutJtiStore, type LogoutRouteConfig, type SsoMiddlewareConfig, createBackchannelLogoutRouteHandler, createCallbackRouteHandler, createLogoutRouteHandler, createSsoMiddleware, getHostCookieOptions, getSecureCookieOptions, toInsecureCookieName };

package/dist/next/index.d.ts

@@ -36,7 +36,12 @@ interface SsoMiddlewareConfig {
     redirectUri: string;
     /** 请求的 scope（空格分隔），默认 "openid profile" */
     scopes?: string;
-    /** 公开路由前缀（不需要认证） */
+    /**
+     * 公开路由前缀（不需要认证）。
+     *
+     * 注意：/api/ 下的路径永不按静态资源扩展名（.js/.css/...）放行；
+     * 如需公开某个 API 路径，必须在此显式列出。
+     */
     publicPaths?: string[];
     /** 回调路径（不触发重定向），默认 "/api/auth/callback" */
     callbackPath?: string;
@@ -298,6 +303,28 @@ interface LogoutTokenPayload {
     sub?: string;
     sid?: string;
 }
+/**
+ * jti 防重放存储接口（可注入）。
+ *
+ * 默认实现是进程内 Map（per-instance）：多实例 / Serverless 部署下各实例
+ * 互不可见，重放检查形同虚设，必须注入共享存储（如 Redis）。
+ * key 为 `${issuer}:${jti}`，ttlSeconds 为建议过期时间（logout_token exp + 60s 宽限）。
+ */
+interface LogoutJtiStore {
+    has(key: string): Promise<boolean> | boolean;
+    add(key: string, ttlSeconds: number): Promise<void> | void;
+    /**
+     * 原子 check-and-set（如 Redis `SET key 1 NX EX ttl`）：返回 false 表示
+     * key 已存在（判重放）。提供时优先使用；缺失时回退 has+add
+     * （非原子，仅单实例部署可接受：并发窗口内同一 jti 可能双双通过）。
+     */
+    addIfAbsent?(key: string, ttlSeconds: number): Promise<boolean> | boolean;
+    /**
+     * 释放已记录的 key。onLogout 钩子失败后需要允许 IdP 用同一 logout_token
+     * 重投，SDK 会调用此方法；未实现时 IdP 重投将被重放检查以 400 拒绝。
+     */
+    remove?(key: string): Promise<void> | void;
+}
 
 /**
  * App Router Backchannel Logout 接收端 Route Handler
@@ -340,6 +367,15 @@ interface BackchannelLogoutRouteConfig {
     refreshTokenCookieName?: string;
     /** ID Token Cookie 名称，默认 __Host-nihplod_sso_id */
     idTokenCookieName?: string;
+    /**
+     * jti 防重放存储（可选）。
+     *
+     * 默认实现是进程内 Map（per-instance）：多实例 / Serverless 部署下各实例
+     * 互不可见，重放保护形同虚设（IdP 重投/攻击者重放到另一实例会被当作首次）。
+     * 这类部署 MUST 注入共享存储（如 Redis：addIfAbsent = `SET key 1 NX EX ttl`，
+     * remove = `DEL key`——onLogout 失败时用于释放 jti 允许 IdP 重投）。
+     */
+    jtiStore?: LogoutJtiStore;
     /**
      * 本地 HTTP 开发模式（默认 false）。关闭 Cookie 的 Secure 属性并去除
      * __Host-/__Secure- 前缀；必须与 middleware / callback / logout 的配置保持一致。
@@ -391,4 +427,4 @@ declare function getSecureCookieOptions(maxAge?: number, path?: string, secure?:
     maxAge?: number;
 };
 
-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 };
+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 LogoutJtiStore, type LogoutRouteConfig, type SsoMiddlewareConfig, createBackchannelLogoutRouteHandler, createCallbackRouteHandler, createLogoutRouteHandler, createSsoMiddleware, getHostCookieOptions, getSecureCookieOptions, toInsecureCookieName };

package/dist/next/index.js

@@ -114,15 +114,18 @@ async function computeCodeChallenge(verifier) {
 function matchesPath(pathname, paths) {
   return paths.some((path) => {
     if (pathname === path) return true;
-    if (path.endsWith("/:path*") && pathname.startsWith(path.replace("/:path*", ""))) return true;
-    if (pathname.startsWith(path + "/")) return true;
-    return false;
+    if (path.endsWith("/:path*")) {
+      const base = path.slice(0, -"/:path*".length);
+      return pathname === base || pathname.startsWith(base + "/");
+    }
+    return pathname.startsWith(path + "/");
   });
 }
 var introspectionCache = /* @__PURE__ */ new Map();
 var INTROSPECT_CACHE_TTL_MS = 3e4;
 var INTROSPECT_CACHE_MAX_ENTRIES = 500;
 var INTROSPECT_TIMEOUT_MS = 5e3;
+var warnedIntrospectClientAuthFailure = false;
 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("");
@@ -176,8 +179,13 @@ async function introspectAccessToken(token, ssoBaseUrl, clientId, clientSecret)
       if (res.status !== 401 && res.status !== 403) {
         return "unreachable";
       }
-      introspectCacheSet(cacheKey, false);
-      return "inactive";
+      if (!warnedIntrospectClientAuthFailure) {
+        warnedIntrospectClientAuthFailure = true;
+        console.warn(
+          `[SSO SDK] introspection \u5BA2\u6237\u7AEF\u8BA4\u8BC1\u5931\u8D25\uFF08HTTP ${res.status}\uFF09\uFF1A\u8BF7\u68C0\u67E5 clientId/clientSecret \u4E0E\u4E3B\u7AD9\u6CE8\u518C\u4FE1\u606F\u662F\u5426\u4E00\u81F4\u3002\u8BE5\u6545\u969C\u4E0D\u4F1A\u88AB\u7F13\u5B58\u4E3A token \u5931\u6548\uFF0C\u4E5F\u4E0D\u4F1A\u89E6\u53D1\u9759\u9ED8\u91CD\u767B\u5F55\u5FAA\u73AF\u3002`
+        );
+      }
+      return "unreachable";
     }
     const data = await res.json();
     const active = data.active === true;
@@ -220,7 +228,7 @@ function createSsoMiddleware(config) {
   }
   return async function ssoMiddleware(request) {
     const { pathname } = request.nextUrl;
-    if (pathname.startsWith("/_next/") || pathname.startsWith("/favicon.ico") || pathname.match(/\.(ico|png|jpg|jpeg|svg|css|js|woff2?)$/)) {
+    if (!pathname.startsWith("/api/") && (pathname.startsWith("/_next/") || pathname.startsWith("/favicon.ico") || pathname.match(/\.(ico|png|jpg|jpeg|svg|css|js|woff2?)$/))) {
       return import_server.NextResponse.next();
     }
     if (pathname === callbackPath) {
@@ -539,7 +547,10 @@ async function validateIdToken(idToken, accessToken, expectedIssuer, expectedCli
   if (Date.now() >= payload.exp * 1e3 + 6e4) {
     throw new SsoError("id_token_expired", "ID Token \u5DF2\u8FC7\u671F");
   }
-  if (typeof payload.iat === "number" && payload.iat * 1e3 > Date.now() + 6e4) {
+  if (typeof payload.iat !== "number") {
+    throw new SsoError("id_token_invalid", "ID Token \u7F3A\u5C11 iat \u58F0\u660E");
+  }
+  if (payload.iat * 1e3 > Date.now() + 6e4) {
     throw new SsoError("id_token_invalid", "ID Token iat \u5728\u672A\u6765\uFF0C\u7591\u4F3C\u4F2A\u9020\u6216\u65F6\u949F\u5F02\u5E38");
   }
   if (typeof payload.sub !== "string" || !payload.sub) {
@@ -556,10 +567,27 @@ async function validateIdToken(idToken, accessToken, expectedIssuer, expectedCli
     if (!tokenNonce || !timingSafeEqualString(expectedNonce, tokenNonce)) {
       throw new SsoError("id_token_nonce_mismatch", "ID Token nonce \u4E0D\u5339\u914D");
     }
+  } else if (typeof payload.nonce === "string" && payload.nonce) {
+    throw new SsoError(
+      "id_token_nonce_mismatch",
+      "ID Token \u643A\u5E26 nonce \u4F46\u672C\u5730\u65E0\u671F\u671B\u503C\uFF08\u53EF\u80FD\u975E\u672C\u6B21\u767B\u5F55\u4F1A\u8BDD\u7B7E\u53D1\uFF09"
+    );
   }
   return { sub: payload.sub };
 }
 
+// src/core/http.ts
+var REQUEST_TIMEOUT_MS = 1e4;
+async function fetchWithTimeout(input, init = {}, timeoutMs = REQUEST_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(input, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/next/callback.ts
 function escapeHtml(value) {
   return value.replace(/[&<>"']/g, (ch) => {
@@ -784,11 +812,15 @@ function createCallbackRouteHandler(config) {
         await new Promise((r) => setTimeout(r, 1e3 * Math.pow(2, attempt - 1)));
       }
       try {
-        res = await fetch(tokenEndpoint, {
-          method: "POST",
-          headers: { "Content-Type": "application/x-www-form-urlencoded" },
-          body: body.toString()
-        });
+        res = await fetchWithTimeout(
+          tokenEndpoint,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString()
+          },
+          1e4
+        );
         lastError = null;
         break;
       } catch (err) {
@@ -1022,7 +1054,7 @@ function createLogoutRouteHandler(config) {
     const returnedState = request.nextUrl.searchParams.get("state");
     if (returnedState) {
       const savedState = request.cookies.get(logoutStateCookieName)?.value;
-      if (!savedState || savedState !== returnedState) {
+      if (!savedState || !timingSafeEqualString(savedState, returnedState)) {
         return import_server3.NextResponse.json(
           { error: "invalid_request", error_description: "Logout state \u4E0D\u5339\u914D" },
           { status: 400 }
@@ -1138,8 +1170,19 @@ var import_server4 = require("next/server");
 var BACKCHANNEL_LOGOUT_EVENT = "http://schemas.openid.net/event/backchannel-logout";
 var JTI_CACHE_CAPACITY = 1e3;
 var seenJti = /* @__PURE__ */ new Map();
-function releaseLogoutTokenJti(jti) {
-  seenJti.delete(jti);
+async function releaseLogoutTokenJti(replayKey, options = {}) {
+  const store = options.jtiStore;
+  if (store?.remove) {
+    await store.remove(replayKey);
+    return;
+  }
+  if (store) {
+    console.warn(
+      "[SSO SDK] \u81EA\u5B9A\u4E49 jtiStore \u672A\u5B9E\u73B0 remove()\uFF1AonLogout \u5931\u8D25\u540E\u65E0\u6CD5\u91CA\u653E jti\uFF0CIdP \u7528\u540C\u4E00 logout_token \u91CD\u6295\u5C06\u88AB\u91CD\u653E\u68C0\u67E5\u62D2\u7EDD\uFF08logout_token_replay\uFF09"
+    );
+    return;
+  }
+  seenJti.delete(replayKey);
 }
 function recordJti(jti, expiresAtMs) {
   const now = Date.now();
@@ -1156,7 +1199,7 @@ function recordJti(jti, expiresAtMs) {
   seenJti.set(jti, expiresAtMs);
   return true;
 }
-async function verifyLogoutTokenDetailed(logoutToken, ssoBaseUrl, clientId) {
+async function verifyLogoutTokenDetailed(logoutToken, ssoBaseUrl, clientId, options = {}) {
   const baseUrl = ssoBaseUrl.replace(/\/+$/, "");
   const header = decodeJwtHeader(logoutToken);
   if (!header) {
@@ -1265,10 +1308,27 @@ async function verifyLogoutTokenDetailed(logoutToken, ssoBaseUrl, clientId) {
   if (!jti) {
     throw new SsoError("logout_token_invalid", "Logout Token \u7F3A\u5C11 jti \u58F0\u660E");
   }
-  if (!recordJti(jti, payload.exp * 1e3 + 6e4)) {
+  const replayKey = `${normalizedIssuer}:${jti}`;
+  const replayTtlSeconds = Math.max(
+    1,
+    Math.ceil((payload.exp * 1e3 + 6e4 - Date.now()) / 1e3)
+  );
+  const jtiStore = options.jtiStore;
+  if (jtiStore) {
+    if (jtiStore.addIfAbsent) {
+      if (!await jtiStore.addIfAbsent(replayKey, replayTtlSeconds)) {
+        throw new SsoError("logout_token_replay", "Logout Token jti \u91CD\u653E");
+      }
+    } else {
+      if (await jtiStore.has(replayKey)) {
+        throw new SsoError("logout_token_replay", "Logout Token jti \u91CD\u653E");
+      }
+      await jtiStore.add(replayKey, replayTtlSeconds);
+    }
+  } else if (!recordJti(replayKey, payload.exp * 1e3 + 6e4)) {
     throw new SsoError("logout_token_replay", "Logout Token jti \u91CD\u653E");
   }
-  return { payload: { sub, sid }, jti };
+  return { payload: { sub, sid }, jti, replayKey };
 }
 
 // src/next/backchannel-logout.ts
@@ -1310,7 +1370,9 @@ function createBackchannelLogoutRouteHandler(config) {
     }
     let verified;
     try {
-      verified = await verifyLogoutTokenDetailed(logoutToken, ssoBaseUrl, clientId);
+      verified = await verifyLogoutTokenDetailed(logoutToken, ssoBaseUrl, clientId, {
+        jtiStore: config.jtiStore
+      });
     } 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";
@@ -1322,7 +1384,7 @@ function createBackchannelLogoutRouteHandler(config) {
     try {
       await onLogout?.(verified.payload, request);
     } catch (err) {
-      releaseLogoutTokenJti(verified.jti);
+      await releaseLogoutTokenJti(verified.replayKey, { jtiStore: config.jtiStore });
       console.error(
         "[SSO SDK] backchannel logout onLogout \u94A9\u5B50\u6267\u884C\u5931\u8D25:",
         err