@nihplod/sso-verify 1.1.0 → 1.1.2

package/README.md

@@ -86,9 +86,9 @@ After successful verification, the token payload is attached to `req.user`.
 
 ## Notes
 
-- The main site currently uses HS256 symmetric signing by default. For external sub-projects, we recommend verifying access tokens via **Introspection**.
-- If your sub-project is an internal service and already shares the RS256 public key with the main site, you can configure `accessTokenPublicKey` or `jwksUri` for local JWT verification.
-- **Never distribute `JWT_ACCESS_SECRET` (the HS256 symmetric key) to external sub-projects.**
+- The main site signs access tokens with **RS256 when `JWT_ACCESS_PRIVATE_KEY` is configured (recommended, enables local verification via JWKS)**, and falls back to HS256 symmetric signing when it is not. For external sub-projects, we recommend verifying access tokens via **Introspection** regardless of the signing algorithm — it always works and reflects revocations in real time.
+- If your sub-project is an internal service and the main site has RS256 enabled, you can configure `accessTokenPublicKey` or `jwksUri` for local JWT verification.
+- **Never distribute `JWT_ACCESS_SECRET` (the HS256 symmetric key) to external sub-projects.** `accessTokenSecret` local verification only applies to internal services that legitimately share the HS256 secret.
 
 ## Advanced Options
 
@@ -97,15 +97,53 @@ After successful verification, the token payload is attached to `req.user`.
 | `introspectCacheTtl` | `30000` | Cache TTL (ms) for `active: true` introspection results |
 | `introspectNegativeCacheTtl` | `5000` | Cache TTL (ms) for `active: false` results; set `0` to disable caching of revoked/invalid tokens |
 | `introspectTimeoutMs` | `10000` | Introspection request timeout (ms); a timeout is treated as verification failure |
+| `introspectRetries` | `1` | Retries for introspection requests on network errors / 5xx (short backoff); 4xx is never retried; set `0` to disable |
+| `clockToleranceSeconds` | `60` | Clock skew tolerance (seconds) applied to all local JWT verification paths (HS256 / RS256 / logout token) |
 | `accessTokenPublicKey` | — | RS256 public key (PEM) for local access token verification |
 | `jwksUri` | — | JWKS endpoint URL; public keys are matched by `kid` |
 | `logoutTokenPublicKey` | — | RS256 public key (PEM) for back-channel `logout_token` verification |
 | `logoutTokenSecret` | — | HS256 secret for local `logout_token` verification |
+| `logoutJtiStore` | — | External store for processed `logout_token` jtis (see "Multi-instance deployments" below) |
+| `strictAudience` | `false` | Reject introspection responses that carry neither `aud` nor `client_id` (fail-closed). **Recommended for production** |
 
 ### Revocation latency trade-off
 
 Introspection results are cached to reduce latency and load on the main site. This means a revoked access token may remain accepted locally until its cache entry expires. `active: true` results are cached for `introspectCacheTtl` (default 30s); `active: false` results use the much shorter `introspectNegativeCacheTtl` (default 5s), so a previously-invalid token that becomes valid (e.g. re-issued) converges quickly, while revocation of an already-cached token takes at most `introspectCacheTtl`. Lower `introspectCacheTtl` for stronger revocation guarantees at the cost of more introspection calls. Use `verifier.invalidateCache(token)` to evict a specific token immediately.
 
+Concurrent `verify()` calls for the same token share a single in-flight introspection request, and failed requests (network errors / 5xx) are retried once by default — see `introspectRetries`.
+
+### Audience (aud) binding for introspection
+
+When verifying via introspection, the response's audience binding is checked against the configured `audience` (which is the sub-project's `client_id`):
+
+- If the response contains `aud` (string or array), it must include the configured `audience`.
+- Otherwise, if the response contains `client_id`, it must equal the configured `audience`.
+- If the endpoint returns neither field, the response is trusted as-is (legacy behavior); the main site's introspection endpoint always returns `client_id`, so tokens issued to other clients are rejected.
+
+> ⚠️ **Production recommendation: enable `strictAudience: true`.** In strict mode a response missing both `aud` and `client_id` is rejected (fail-closed) instead of trusted, eliminating the fail-open path entirely. The main site's introspection endpoint always returns `client_id`, so enabling it does not change behavior against the main site — only turn it off when integrating a third-party introspection endpoint that returns no audience fields.
+
 ### Logout token verification
 
-Back-channel `logout_token`s are signed with a dedicated key pair (`kid: logout-token-rs256-v1`), which is **different** from the access token key — do not use `accessTokenPublicKey` for them. Configure `logoutTokenPublicKey` (PEM) or `jwksUri` (keys matched by `kid`). Verification is dispatched by the JWT header `alg`: an RS256 logout token without any matching public key fails closed (returns `null`) instead of silently falling back to HS256; HS256 is only used when `logoutTokenSecret` (or the legacy `accessTokenSecret` fallback) is explicitly configured. Verified `jti`s are replay-guarded per issuer for 10 minutes.
+Back-channel `logout_token`s are signed with a dedicated key pair (`kid: logout-token-rs256-v1`), which is **different** from the access token key — do not use `accessTokenPublicKey` for them. Configure `logoutTokenPublicKey` (PEM) or `jwksUri` (keys matched by `kid`). Verification is dispatched by the JWT header `alg`: an RS256 logout token without any matching public key fails closed (returns `null`) instead of silently falling back to HS256; HS256 is only used when `logoutTokenSecret` (or the legacy `accessTokenSecret` fallback) is explicitly configured.
+
+Per OIDC Back-Channel Logout 1.0, a `logout_token` must carry an `exp` claim, an `events` claim whose `http://schemas.openid.net/event/backchannel-logout` member is an object (typically `{}`), and at least one of `sub` / `sid` (§2.4); tokens failing any of these checks are rejected. Verified `jti`s are replay-guarded per issuer for 10 minutes.
+
+When the IdP revokes sessions administratively (consent revoke, session termination, user ban/deletion), the `logout_token` also carries a `sid` claim matching the terminated IdP session — RPs that track IdP `sid`s should invalidate the matching local session and may fall back to `sub`-level logout when `sid` is absent (e.g. user-initiated IdP logout without a known session). Failed deliveries are retried by the IdP with exponential backoff (up to 10 attempts), so RPs may receive a delayed `logout_token`; the `jti` replay guard still applies.
+
+### Multi-instance deployments (logout jti replay store)
+
+By default, processed `logout_token` jtis are kept in an in-process LRU cache — it is emptied on restart and **not shared across instances**, so a replayed logout token could be accepted by another instance. When running multiple instances, inject a shared store (e.g. backed by Redis) via `logoutJtiStore`:
+
+```typescript
+const verifier = createTokenVerifier({
+  audience: "your-client-id",
+  logoutTokenPublicKey: process.env.LOGOUT_TOKEN_PUBLIC_KEY,
+  logoutJtiStore: {
+    // Both sync and async implementations are supported.
+    has: (key) => redis.exists(key).then((n) => n > 0),
+    add: (key, ttlSeconds) => redis.set(key, "1", "EX", ttlSeconds),
+  },
+});
+```
+
+`has(key)` reports whether a jti was already processed; `add(key, ttlSeconds)` records it with expiry (the verifier passes 600 seconds, matching the built-in cache).

package/dist/index.d.mts

@@ -7,10 +7,11 @@ import { JWTPayload } from 'jose';
  *
  * 供子项目在后端验证主站签发的 Access Token。
  *
- * 由于主站当前使用 HS256 对称签名，JWKS 端点不公开签名密钥，
- * 因此本工具包默认采用 OAuth 2.0 Token Introspection（RFC 7662）
- * 端点进行验证。对于已知共享密钥的内部服务，也可传入
- * accessTokenSecret 做本地 JWT 验证。
+ * 由于主站 access_token 的签名算法取决于部署配置（配置 JWT_ACCESS_PRIVATE_KEY
+ * 后以 RS256 签名，未配置时回退 HS256 对称签名），JWKS 端点仅在 RS256
+ * 模式下公开公钥，因此本工具包默认采用 OAuth 2.0 Token Introspection
+ * （RFC 7662）端点进行验证。对于已知共享密钥/公钥的内部服务，也可传入
+ * accessTokenSecret（HS256）或 accessTokenPublicKey / jwksUri（RS256）做本地 JWT 验证。
  *
  * 安装：npm install @nihplod/sso-verify
  *
@@ -38,7 +39,7 @@ interface SsoVerifierOptions {
     issuer?: string;
     /**
      * Token Introspection 端点 URL。
-     * 推荐优先使用，适配当前 HS256 对称签名场景。
+     * 推荐优先使用，与主站签名算法（HS256/RS256）无关，且能实时感知撤销。
      */
     introspectionEndpoint?: string;
     /** 子项目的 client_id（用于 introspection） */
@@ -66,8 +67,9 @@ interface SsoVerifierOptions {
     introspectNegativeCacheTtl?: number;
     /**
      * Access Token RS256 公钥（PEM 格式，可选）。
-     * 主站已迁移至 RS256 签名，子项目可传入此公钥进行本地验证，
-     * 避免每次都调用 Introspection 端点。
+     * 主站在配置 JWT_ACCESS_PRIVATE_KEY 后以 RS256 签名 access_token，
+     * 子项目可传入此公钥进行本地验证，避免每次都调用 Introspection 端点。
+     * 若主站未配置 RS256 密钥（回退 HS256 签名），此选项不生效。
      */
     accessTokenPublicKey?: string;
     /**
@@ -91,6 +93,45 @@ interface SsoVerifierOptions {
      * 不会静默回退到 HS256。
      */
     logoutTokenPublicKey?: string;
+    /**
+     * Introspection 请求失败重试次数，默认 1。
+     * 仅对网络错误与 5xx 响应重试（短退避），4xx 不重试。
+     * 设为 0 表示不重试。
+     */
+    introspectRetries?: number;
+    /**
+     * JWT 时钟偏移容忍（秒），默认 60。
+     * 应用于所有本地验签路径（HS256/RS256/logout token），
+     * 用于容忍子项目与主站之间的时钟偏差。
+     */
+    clockToleranceSeconds?: number;
+    /**
+     * Logout Token jti 外部存储（可选）。
+     * 默认使用进程内 LRU 缓存（重启即清空、多实例不共享）；
+     * 多实例部署时应注入共享存储（如 Redis 实现）以防跨实例重放。
+     */
+    logoutJtiStore?: LogoutJtiStore;
+    /**
+     * Introspection audience 严格模式（默认 false，保持向后兼容）。
+     *
+     * 默认模式下，introspection 响应既无 aud 又无 client_id 时保持信任
+     * （兼容不返回归属字段的端点）。设为 true 后：响应缺少归属字段即拒绝
+     * （fail-closed），防止被 confused deputy 攻击利用。
+     *
+     * ⚠️ 生产环境强烈建议开启。主站 introspection 端点始终返回 client_id，
+     * 开启后行为不变；仅在对接不返回归属字段的第三方端点时才需要保持 false。
+     */
+    strictAudience?: boolean;
+}
+/**
+ * Logout Token jti 防重放存储接口（可注入 Redis 等共享存储实现）。
+ * has/add 均支持同步或异步返回。
+ */
+interface LogoutJtiStore {
+    /** 判断 jti 是否已处理过 */
+    has(key: string): boolean | Promise<boolean>;
+    /** 记录已处理的 jti，ttlSeconds 后过期 */
+    add(key: string, ttlSeconds: number): void | Promise<void>;
 }
 interface VerifiedTokenPayload extends JWTPayload {
     sub: string;
@@ -106,7 +147,7 @@ interface VerifiedTokenPayload extends JWTPayload {
  * 主站签发 logout_token 时包含以下字段：
  * - iss: 主站 issuer
  * - aud: 目标 client_id
- * - sub: 用户 ID
+ * - sub: 用户 ID（与 sid 至少其一）
  * - iat: 签发时间
  * - jti: 唯一 ID（防重放，建议接收方缓存已处理的 jti）
  * - events: { "http://schemas.openid.net/event/backchannel-logout": {} }
@@ -118,8 +159,8 @@ interface LogoutTokenPayload {
     iss: string;
     /** 目标 audience */
     aud: string;
-    /** 用户 ID */
-    sub: string;
+    /** 用户 ID（Back-Channel Logout 1.0：sub 与 sid 至少其一） */
+    sub?: string;
     /** 签发时间（UNIX timestamp） */
     iat: number;
     /** JWT ID（唯一标识，防重放） */
@@ -134,6 +175,7 @@ interface LogoutTokenPayload {
 interface IntrospectResponse {
     active: boolean;
     sub?: string;
+    aud?: string | string[];
     client_id?: string;
     scope?: string;
     exp?: number;
@@ -167,7 +209,9 @@ declare function createTokenVerifier(options: SsoVerifierOptions): {
      * 1. type === "logout_token"
      * 2. iss 匹配配置的 issuer
      * 3. aud 包含当前 client_id
-     * 4. events 包含 backchannel-logout 事件
+     * 4. exp 存在（规范要求）
+     * 5. events 包含 backchannel-logout 事件，且事件值为对象
+     * 6. sub 或 sid 至少其一（§2.4，否则无法定位要终止的会话）
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */
@@ -211,7 +255,7 @@ interface SsoMiddlewareResponse {
  * }
  * ```
  */
-declare function ssoMiddleware(options: SsoVerifierOptions): (req: SsoMiddlewareRequest, res: SsoMiddlewareResponse, next: () => void) => Promise<void>;
+declare function ssoMiddleware(options: SsoVerifierOptions): (req: SsoMiddlewareRequest, res: SsoMiddlewareResponse, next: (err?: unknown) => void) => Promise<void>;
 /**
  * 创建 Logout Token 专用验证器
  *
@@ -248,4 +292,4 @@ declare function createLogoutTokenVerifier(options: SsoVerifierOptions): {
     verify(token: string): Promise<LogoutTokenPayload | null>;
 };
 
-export { type LogoutTokenPayload, type SsoMiddlewareRequest, type SsoMiddlewareResponse, type SsoVerifierOptions, type VerifiedTokenPayload, createLogoutTokenVerifier, createTokenVerifier, ssoMiddleware };
+export { type LogoutJtiStore, type LogoutTokenPayload, type SsoMiddlewareRequest, type SsoMiddlewareResponse, type SsoVerifierOptions, type VerifiedTokenPayload, createLogoutTokenVerifier, createTokenVerifier, ssoMiddleware };

package/dist/index.d.ts

@@ -7,10 +7,11 @@ import { JWTPayload } from 'jose';
  *
  * 供子项目在后端验证主站签发的 Access Token。
  *
- * 由于主站当前使用 HS256 对称签名，JWKS 端点不公开签名密钥，
- * 因此本工具包默认采用 OAuth 2.0 Token Introspection（RFC 7662）
- * 端点进行验证。对于已知共享密钥的内部服务，也可传入
- * accessTokenSecret 做本地 JWT 验证。
+ * 由于主站 access_token 的签名算法取决于部署配置（配置 JWT_ACCESS_PRIVATE_KEY
+ * 后以 RS256 签名，未配置时回退 HS256 对称签名），JWKS 端点仅在 RS256
+ * 模式下公开公钥，因此本工具包默认采用 OAuth 2.0 Token Introspection
+ * （RFC 7662）端点进行验证。对于已知共享密钥/公钥的内部服务，也可传入
+ * accessTokenSecret（HS256）或 accessTokenPublicKey / jwksUri（RS256）做本地 JWT 验证。
  *
  * 安装：npm install @nihplod/sso-verify
  *
@@ -38,7 +39,7 @@ interface SsoVerifierOptions {
     issuer?: string;
     /**
      * Token Introspection 端点 URL。
-     * 推荐优先使用，适配当前 HS256 对称签名场景。
+     * 推荐优先使用，与主站签名算法（HS256/RS256）无关，且能实时感知撤销。
      */
     introspectionEndpoint?: string;
     /** 子项目的 client_id（用于 introspection） */
@@ -66,8 +67,9 @@ interface SsoVerifierOptions {
     introspectNegativeCacheTtl?: number;
     /**
      * Access Token RS256 公钥（PEM 格式，可选）。
-     * 主站已迁移至 RS256 签名，子项目可传入此公钥进行本地验证，
-     * 避免每次都调用 Introspection 端点。
+     * 主站在配置 JWT_ACCESS_PRIVATE_KEY 后以 RS256 签名 access_token，
+     * 子项目可传入此公钥进行本地验证，避免每次都调用 Introspection 端点。
+     * 若主站未配置 RS256 密钥（回退 HS256 签名），此选项不生效。
      */
     accessTokenPublicKey?: string;
     /**
@@ -91,6 +93,45 @@ interface SsoVerifierOptions {
      * 不会静默回退到 HS256。
      */
     logoutTokenPublicKey?: string;
+    /**
+     * Introspection 请求失败重试次数，默认 1。
+     * 仅对网络错误与 5xx 响应重试（短退避），4xx 不重试。
+     * 设为 0 表示不重试。
+     */
+    introspectRetries?: number;
+    /**
+     * JWT 时钟偏移容忍（秒），默认 60。
+     * 应用于所有本地验签路径（HS256/RS256/logout token），
+     * 用于容忍子项目与主站之间的时钟偏差。
+     */
+    clockToleranceSeconds?: number;
+    /**
+     * Logout Token jti 外部存储（可选）。
+     * 默认使用进程内 LRU 缓存（重启即清空、多实例不共享）；
+     * 多实例部署时应注入共享存储（如 Redis 实现）以防跨实例重放。
+     */
+    logoutJtiStore?: LogoutJtiStore;
+    /**
+     * Introspection audience 严格模式（默认 false，保持向后兼容）。
+     *
+     * 默认模式下，introspection 响应既无 aud 又无 client_id 时保持信任
+     * （兼容不返回归属字段的端点）。设为 true 后：响应缺少归属字段即拒绝
+     * （fail-closed），防止被 confused deputy 攻击利用。
+     *
+     * ⚠️ 生产环境强烈建议开启。主站 introspection 端点始终返回 client_id，
+     * 开启后行为不变；仅在对接不返回归属字段的第三方端点时才需要保持 false。
+     */
+    strictAudience?: boolean;
+}
+/**
+ * Logout Token jti 防重放存储接口（可注入 Redis 等共享存储实现）。
+ * has/add 均支持同步或异步返回。
+ */
+interface LogoutJtiStore {
+    /** 判断 jti 是否已处理过 */
+    has(key: string): boolean | Promise<boolean>;
+    /** 记录已处理的 jti，ttlSeconds 后过期 */
+    add(key: string, ttlSeconds: number): void | Promise<void>;
 }
 interface VerifiedTokenPayload extends JWTPayload {
     sub: string;
@@ -106,7 +147,7 @@ interface VerifiedTokenPayload extends JWTPayload {
  * 主站签发 logout_token 时包含以下字段：
  * - iss: 主站 issuer
  * - aud: 目标 client_id
- * - sub: 用户 ID
+ * - sub: 用户 ID（与 sid 至少其一）
  * - iat: 签发时间
  * - jti: 唯一 ID（防重放，建议接收方缓存已处理的 jti）
  * - events: { "http://schemas.openid.net/event/backchannel-logout": {} }
@@ -118,8 +159,8 @@ interface LogoutTokenPayload {
     iss: string;
     /** 目标 audience */
     aud: string;
-    /** 用户 ID */
-    sub: string;
+    /** 用户 ID（Back-Channel Logout 1.0：sub 与 sid 至少其一） */
+    sub?: string;
     /** 签发时间（UNIX timestamp） */
     iat: number;
     /** JWT ID（唯一标识，防重放） */
@@ -134,6 +175,7 @@ interface LogoutTokenPayload {
 interface IntrospectResponse {
     active: boolean;
     sub?: string;
+    aud?: string | string[];
     client_id?: string;
     scope?: string;
     exp?: number;
@@ -167,7 +209,9 @@ declare function createTokenVerifier(options: SsoVerifierOptions): {
      * 1. type === "logout_token"
      * 2. iss 匹配配置的 issuer
      * 3. aud 包含当前 client_id
-     * 4. events 包含 backchannel-logout 事件
+     * 4. exp 存在（规范要求）
+     * 5. events 包含 backchannel-logout 事件，且事件值为对象
+     * 6. sub 或 sid 至少其一（§2.4，否则无法定位要终止的会话）
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */
@@ -211,7 +255,7 @@ interface SsoMiddlewareResponse {
  * }
  * ```
  */
-declare function ssoMiddleware(options: SsoVerifierOptions): (req: SsoMiddlewareRequest, res: SsoMiddlewareResponse, next: () => void) => Promise<void>;
+declare function ssoMiddleware(options: SsoVerifierOptions): (req: SsoMiddlewareRequest, res: SsoMiddlewareResponse, next: (err?: unknown) => void) => Promise<void>;
 /**
  * 创建 Logout Token 专用验证器
  *
@@ -248,4 +292,4 @@ declare function createLogoutTokenVerifier(options: SsoVerifierOptions): {
     verify(token: string): Promise<LogoutTokenPayload | null>;
 };
 
-export { type LogoutTokenPayload, type SsoMiddlewareRequest, type SsoMiddlewareResponse, type SsoVerifierOptions, type VerifiedTokenPayload, createLogoutTokenVerifier, createTokenVerifier, ssoMiddleware };
+export { type LogoutJtiStore, type LogoutTokenPayload, type SsoMiddlewareRequest, type SsoMiddlewareResponse, type SsoVerifierOptions, type VerifiedTokenPayload, createLogoutTokenVerifier, createTokenVerifier, ssoMiddleware };

package/dist/index.js

@@ -51,7 +51,11 @@ function createTokenVerifier(options) {
     logoutTokenPublicKey,
     introspectCacheTtl = 30 * 1e3,
     introspectTimeoutMs = 10 * 1e3,
-    introspectNegativeCacheTtl = 5 * 1e3
+    introspectNegativeCacheTtl = 5 * 1e3,
+    introspectRetries = 1,
+    clockToleranceSeconds = 60,
+    logoutJtiStore,
+    strictAudience = false
   } = options;
   const introspectCache = createIntrospectCache(introspectCacheTtl);
   let _jwksKeySet = null;
@@ -99,6 +103,14 @@ function createTokenVerifier(options) {
     }
     return _logoutRs256PublicKey;
   }
+  function matchesAudience(data) {
+    const aud = data.aud;
+    if (typeof aud === "string") return aud === audience;
+    if (Array.isArray(aud)) return aud.includes(audience);
+    if (typeof data.client_id === "string") return data.client_id === audience;
+    return !strictAudience;
+  }
+  const inflightIntrospects = /* @__PURE__ */ new Map();
   async function introspect(token) {
     if (!introspectionEndpoint || !clientId) {
       return null;
@@ -107,41 +119,73 @@ function createTokenVerifier(options) {
     if (cached) {
       return { active: cached.active, ...cached.payload || {} };
     }
-    try {
-      const params = new URLSearchParams({ token, client_id: clientId });
-      if (clientSecret) {
-        params.set("client_secret", clientSecret);
+    const inflight = inflightIntrospects.get(token);
+    if (inflight) {
+      return inflight;
+    }
+    const promise = doIntrospect(token).finally(() => {
+      inflightIntrospects.delete(token);
+    });
+    inflightIntrospects.set(token, promise);
+    return promise;
+  }
+  async function doIntrospect(token) {
+    const params = new URLSearchParams({ token, client_id: clientId });
+    if (clientSecret) {
+      params.set("client_secret", clientSecret);
+    }
+    let data = null;
+    for (let attempt = 0; ; attempt++) {
+      if (attempt > 0) {
+        await new Promise((resolve) => setTimeout(resolve, 200 * attempt));
       }
-      const response = await fetch(introspectionEndpoint, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: params,
-        signal: AbortSignal.timeout(introspectTimeoutMs)
-      });
-      if (!response.ok) return null;
-      const data = await response.json();
-      let payload = null;
-      if (data.active && data.sub) {
-        payload = {
-          sub: data.sub,
-          aud: audience,
-          iss: issuer,
-          client_id: data.client_id,
-          scope: data.scope,
-          exp: data.exp
-        };
+      let response;
+      try {
+        response = await fetch(introspectionEndpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/x-www-form-urlencoded" },
+          body: params,
+          signal: AbortSignal.timeout(introspectTimeoutMs)
+        });
+      } catch {
+        if (attempt < introspectRetries) continue;
+        return null;
+      }
+      if (!response.ok) {
+        if (response.status >= 500 && attempt < introspectRetries) continue;
+        return null;
       }
-      if (data.active) {
-        introspectCache.set(token, { active: true, payload });
-      } else if (introspectNegativeCacheTtl > 0) {
+      data = await response.json();
+      break;
+    }
+    if (!data) return null;
+    if (data.active && !matchesAudience(data)) {
+      if (introspectNegativeCacheTtl > 0) {
         introspectCache.set(token, { active: false, payload: null }, {
           ttl: introspectNegativeCacheTtl
         });
       }
-      return data;
-    } catch {
-      return null;
+      return { active: false };
     }
+    let payload = null;
+    if (data.active && data.sub) {
+      payload = {
+        sub: data.sub,
+        aud: audience,
+        iss: issuer,
+        client_id: data.client_id,
+        scope: data.scope,
+        exp: data.exp
+      };
+    }
+    if (data.active) {
+      introspectCache.set(token, { active: true, payload });
+    } else if (introspectNegativeCacheTtl > 0) {
+      introspectCache.set(token, { active: false, payload: null }, {
+        ttl: introspectNegativeCacheTtl
+      });
+    }
+    return data;
   }
   async function verifyLocally(token) {
     if (!accessTokenSecret) return null;
@@ -150,7 +194,8 @@ function createTokenVerifier(options) {
       const { payload } = await (0, import_jose.jwtVerify)(token, secret, {
         issuer,
         audience,
-        algorithms: ["HS256"]
+        algorithms: ["HS256"],
+        clockTolerance: clockToleranceSeconds
       });
       if (payload.type !== "access_token") {
         return null;
@@ -170,7 +215,8 @@ function createTokenVerifier(options) {
         const { payload } = await (0, import_jose.jwtVerify)(token, directKey, {
           issuer,
           audience,
-          algorithms: ["RS256"]
+          algorithms: ["RS256"],
+          clockTolerance: clockToleranceSeconds
         });
         if (payload.type !== "access_token") return null;
         return payload;
@@ -180,7 +226,8 @@ function createTokenVerifier(options) {
         const { payload } = await (0, import_jose.jwtVerify)(token, jwks, {
           issuer,
           audience,
-          algorithms: ["RS256"]
+          algorithms: ["RS256"],
+          clockTolerance: clockToleranceSeconds
         });
         if (payload.type !== "access_token") return null;
         return payload;
@@ -237,29 +284,49 @@ function createTokenVerifier(options) {
      * 1. type === "logout_token"
      * 2. iss 匹配配置的 issuer
      * 3. aud 包含当前 client_id
-     * 4. events 包含 backchannel-logout 事件
+     * 4. exp 存在（规范要求）
+     * 5. events 包含 backchannel-logout 事件，且事件值为对象
+     * 6. sub 或 sid 至少其一（§2.4，否则无法定位要终止的会话）
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */
     async verifyLogoutToken(token) {
-      const validateLogoutPayload = (payload) => {
+      const validateLogoutPayload = async (payload) => {
         if (payload.type !== "logout_token") {
           return null;
         }
+        if (typeof payload.exp !== "number") {
+          return null;
+        }
         const events = payload.events;
-        if (!events || !events["http://schemas.openid.net/event/backchannel-logout"]) {
+        const logoutEvent = events?.["http://schemas.openid.net/event/backchannel-logout"];
+        if (!logoutEvent || typeof logoutEvent !== "object" || Array.isArray(logoutEvent)) {
           return null;
         }
         const jti = payload.jti;
         if (!jti || typeof jti !== "string") {
           return null;
         }
+        const sub = payload.sub;
+        const sid = payload.sid;
+        const hasSub = typeof sub === "string" && sub.length > 0;
+        const hasSid = typeof sid === "string" && sid.length > 0;
+        if (!hasSub && !hasSid) {
+          return null;
+        }
         const iss = payload.iss || issuer;
         const jtiKey = `${iss}:${jti}`;
-        if (processedLogoutJtis.has(jtiKey)) {
-          return null;
+        if (logoutJtiStore) {
+          if (await logoutJtiStore.has(jtiKey)) {
+            return null;
+          }
+          await logoutJtiStore.add(jtiKey, 10 * 60);
+        } else {
+          if (processedLogoutJtis.has(jtiKey)) {
+            return null;
+          }
+          processedLogoutJtis.set(jtiKey, Date.now());
         }
-        processedLogoutJtis.set(jtiKey, Date.now());
         return payload;
       };
       let alg;
@@ -275,9 +342,10 @@ function createTokenVerifier(options) {
             const { payload } = await (0, import_jose.jwtVerify)(token, directKey, {
               issuer,
               audience,
-              algorithms: ["RS256"]
+              algorithms: ["RS256"],
+              clockTolerance: clockToleranceSeconds
             });
-            return validateLogoutPayload(payload);
+            return await validateLogoutPayload(payload);
           } catch {
             return null;
           }
@@ -288,9 +356,10 @@ function createTokenVerifier(options) {
             const { payload } = await (0, import_jose.jwtVerify)(token, jwks, {
               issuer,
               audience,
-              algorithms: ["RS256"]
+              algorithms: ["RS256"],
+              clockTolerance: clockToleranceSeconds
             });
-            return validateLogoutPayload(payload);
+            return await validateLogoutPayload(payload);
           } catch {
             return null;
           }
@@ -305,9 +374,10 @@ function createTokenVerifier(options) {
           const { payload } = await (0, import_jose.jwtVerify)(token, key, {
             issuer,
             audience,
-            algorithms: ["HS256"]
+            algorithms: ["HS256"],
+            clockTolerance: clockToleranceSeconds
           });
-          return validateLogoutPayload(payload);
+          return await validateLogoutPayload(payload);
         } catch {
           return null;
         }
@@ -324,14 +394,18 @@ function ssoMiddleware(options) {
     if (!token) {
       if (res.status) {
         res.status(401).json({ error: "Unauthorized", message: "\u8BF7\u63D0\u4F9B Bearer token" });
+        return;
       }
+      next(new Error("Unauthorized: \u8BF7\u63D0\u4F9B Bearer token"));
       return;
     }
     const payload = await verifier.verify(token);
     if (!payload) {
       if (res.status) {
         res.status(401).json({ error: "Unauthorized", message: "Token \u65E0\u6548\u6216\u5DF2\u8FC7\u671F" });
+        return;
       }
+      next(new Error("Unauthorized: Token \u65E0\u6548\u6216\u5DF2\u8FC7\u671F"));
       return;
     }
     req.user = payload;

package/dist/index.mjs

@@ -30,7 +30,11 @@ function createTokenVerifier(options) {
     logoutTokenPublicKey,
     introspectCacheTtl = 30 * 1e3,
     introspectTimeoutMs = 10 * 1e3,
-    introspectNegativeCacheTtl = 5 * 1e3
+    introspectNegativeCacheTtl = 5 * 1e3,
+    introspectRetries = 1,
+    clockToleranceSeconds = 60,
+    logoutJtiStore,
+    strictAudience = false
   } = options;
   const introspectCache = createIntrospectCache(introspectCacheTtl);
   let _jwksKeySet = null;
@@ -78,6 +82,14 @@ function createTokenVerifier(options) {
     }
     return _logoutRs256PublicKey;
   }
+  function matchesAudience(data) {
+    const aud = data.aud;
+    if (typeof aud === "string") return aud === audience;
+    if (Array.isArray(aud)) return aud.includes(audience);
+    if (typeof data.client_id === "string") return data.client_id === audience;
+    return !strictAudience;
+  }
+  const inflightIntrospects = /* @__PURE__ */ new Map();
   async function introspect(token) {
     if (!introspectionEndpoint || !clientId) {
       return null;
@@ -86,41 +98,73 @@ function createTokenVerifier(options) {
     if (cached) {
       return { active: cached.active, ...cached.payload || {} };
     }
-    try {
-      const params = new URLSearchParams({ token, client_id: clientId });
-      if (clientSecret) {
-        params.set("client_secret", clientSecret);
+    const inflight = inflightIntrospects.get(token);
+    if (inflight) {
+      return inflight;
+    }
+    const promise = doIntrospect(token).finally(() => {
+      inflightIntrospects.delete(token);
+    });
+    inflightIntrospects.set(token, promise);
+    return promise;
+  }
+  async function doIntrospect(token) {
+    const params = new URLSearchParams({ token, client_id: clientId });
+    if (clientSecret) {
+      params.set("client_secret", clientSecret);
+    }
+    let data = null;
+    for (let attempt = 0; ; attempt++) {
+      if (attempt > 0) {
+        await new Promise((resolve) => setTimeout(resolve, 200 * attempt));
       }
-      const response = await fetch(introspectionEndpoint, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: params,
-        signal: AbortSignal.timeout(introspectTimeoutMs)
-      });
-      if (!response.ok) return null;
-      const data = await response.json();
-      let payload = null;
-      if (data.active && data.sub) {
-        payload = {
-          sub: data.sub,
-          aud: audience,
-          iss: issuer,
-          client_id: data.client_id,
-          scope: data.scope,
-          exp: data.exp
-        };
+      let response;
+      try {
+        response = await fetch(introspectionEndpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/x-www-form-urlencoded" },
+          body: params,
+          signal: AbortSignal.timeout(introspectTimeoutMs)
+        });
+      } catch {
+        if (attempt < introspectRetries) continue;
+        return null;
+      }
+      if (!response.ok) {
+        if (response.status >= 500 && attempt < introspectRetries) continue;
+        return null;
       }
-      if (data.active) {
-        introspectCache.set(token, { active: true, payload });
-      } else if (introspectNegativeCacheTtl > 0) {
+      data = await response.json();
+      break;
+    }
+    if (!data) return null;
+    if (data.active && !matchesAudience(data)) {
+      if (introspectNegativeCacheTtl > 0) {
         introspectCache.set(token, { active: false, payload: null }, {
           ttl: introspectNegativeCacheTtl
         });
       }
-      return data;
-    } catch {
-      return null;
+      return { active: false };
     }
+    let payload = null;
+    if (data.active && data.sub) {
+      payload = {
+        sub: data.sub,
+        aud: audience,
+        iss: issuer,
+        client_id: data.client_id,
+        scope: data.scope,
+        exp: data.exp
+      };
+    }
+    if (data.active) {
+      introspectCache.set(token, { active: true, payload });
+    } else if (introspectNegativeCacheTtl > 0) {
+      introspectCache.set(token, { active: false, payload: null }, {
+        ttl: introspectNegativeCacheTtl
+      });
+    }
+    return data;
   }
   async function verifyLocally(token) {
     if (!accessTokenSecret) return null;
@@ -129,7 +173,8 @@ function createTokenVerifier(options) {
       const { payload } = await jwtVerify(token, secret, {
         issuer,
         audience,
-        algorithms: ["HS256"]
+        algorithms: ["HS256"],
+        clockTolerance: clockToleranceSeconds
       });
       if (payload.type !== "access_token") {
         return null;
@@ -149,7 +194,8 @@ function createTokenVerifier(options) {
         const { payload } = await jwtVerify(token, directKey, {
           issuer,
           audience,
-          algorithms: ["RS256"]
+          algorithms: ["RS256"],
+          clockTolerance: clockToleranceSeconds
         });
         if (payload.type !== "access_token") return null;
         return payload;
@@ -159,7 +205,8 @@ function createTokenVerifier(options) {
         const { payload } = await jwtVerify(token, jwks, {
           issuer,
           audience,
-          algorithms: ["RS256"]
+          algorithms: ["RS256"],
+          clockTolerance: clockToleranceSeconds
         });
         if (payload.type !== "access_token") return null;
         return payload;
@@ -216,29 +263,49 @@ function createTokenVerifier(options) {
      * 1. type === "logout_token"
      * 2. iss 匹配配置的 issuer
      * 3. aud 包含当前 client_id
-     * 4. events 包含 backchannel-logout 事件
+     * 4. exp 存在（规范要求）
+     * 5. events 包含 backchannel-logout 事件，且事件值为对象
+     * 6. sub 或 sid 至少其一（§2.4，否则无法定位要终止的会话）
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */
     async verifyLogoutToken(token) {
-      const validateLogoutPayload = (payload) => {
+      const validateLogoutPayload = async (payload) => {
         if (payload.type !== "logout_token") {
           return null;
         }
+        if (typeof payload.exp !== "number") {
+          return null;
+        }
         const events = payload.events;
-        if (!events || !events["http://schemas.openid.net/event/backchannel-logout"]) {
+        const logoutEvent = events?.["http://schemas.openid.net/event/backchannel-logout"];
+        if (!logoutEvent || typeof logoutEvent !== "object" || Array.isArray(logoutEvent)) {
           return null;
         }
         const jti = payload.jti;
         if (!jti || typeof jti !== "string") {
           return null;
         }
+        const sub = payload.sub;
+        const sid = payload.sid;
+        const hasSub = typeof sub === "string" && sub.length > 0;
+        const hasSid = typeof sid === "string" && sid.length > 0;
+        if (!hasSub && !hasSid) {
+          return null;
+        }
         const iss = payload.iss || issuer;
         const jtiKey = `${iss}:${jti}`;
-        if (processedLogoutJtis.has(jtiKey)) {
-          return null;
+        if (logoutJtiStore) {
+          if (await logoutJtiStore.has(jtiKey)) {
+            return null;
+          }
+          await logoutJtiStore.add(jtiKey, 10 * 60);
+        } else {
+          if (processedLogoutJtis.has(jtiKey)) {
+            return null;
+          }
+          processedLogoutJtis.set(jtiKey, Date.now());
         }
-        processedLogoutJtis.set(jtiKey, Date.now());
         return payload;
       };
       let alg;
@@ -254,9 +321,10 @@ function createTokenVerifier(options) {
             const { payload } = await jwtVerify(token, directKey, {
               issuer,
               audience,
-              algorithms: ["RS256"]
+              algorithms: ["RS256"],
+              clockTolerance: clockToleranceSeconds
             });
-            return validateLogoutPayload(payload);
+            return await validateLogoutPayload(payload);
           } catch {
             return null;
           }
@@ -267,9 +335,10 @@ function createTokenVerifier(options) {
             const { payload } = await jwtVerify(token, jwks, {
               issuer,
               audience,
-              algorithms: ["RS256"]
+              algorithms: ["RS256"],
+              clockTolerance: clockToleranceSeconds
             });
-            return validateLogoutPayload(payload);
+            return await validateLogoutPayload(payload);
           } catch {
             return null;
           }
@@ -284,9 +353,10 @@ function createTokenVerifier(options) {
           const { payload } = await jwtVerify(token, key, {
             issuer,
             audience,
-            algorithms: ["HS256"]
+            algorithms: ["HS256"],
+            clockTolerance: clockToleranceSeconds
           });
-          return validateLogoutPayload(payload);
+          return await validateLogoutPayload(payload);
         } catch {
           return null;
         }
@@ -303,14 +373,18 @@ function ssoMiddleware(options) {
     if (!token) {
       if (res.status) {
         res.status(401).json({ error: "Unauthorized", message: "\u8BF7\u63D0\u4F9B Bearer token" });
+        return;
       }
+      next(new Error("Unauthorized: \u8BF7\u63D0\u4F9B Bearer token"));
       return;
     }
     const payload = await verifier.verify(token);
     if (!payload) {
       if (res.status) {
         res.status(401).json({ error: "Unauthorized", message: "Token \u65E0\u6548\u6216\u5DF2\u8FC7\u671F" });
+        return;
       }
+      next(new Error("Unauthorized: Token \u65E0\u6548\u6216\u5DF2\u8FC7\u671F"));
       return;
     }
     req.user = payload;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nihplod/sso-verify",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "NIHPLOD 一网通 SSO Token 验证工具包 — 供子项目在后端验证主站签发的 Access Token",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -34,9 +34,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/nihplod/nihplod.cn",
+    "url": "https://github.com/Wilboerht/NIHPLOD-Homepage.CN",
     "directory": "packages/sso-verify"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "peerDependencies": {},
   "dependencies": {
     "jose": "^5.0.0",