@nihplod/sso-verify 1.0.3 → 1.1.1

package/README.md

@@ -86,6 +86,61 @@ 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
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `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) |
+
+### 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.
+
+### 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.
+
+Per OIDC Back-Channel Logout 1.0, a `logout_token` must carry an `exp` claim and an `events` claim whose `http://schemas.openid.net/event/backchannel-logout` member is an object (typically `{}`); tokens failing either check 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） */
@@ -53,10 +54,22 @@ interface SsoVerifierOptions {
     accessTokenSecret?: string;
     /** Introspection 结果缓存 TTL（毫秒），默认 30 秒 */
     introspectCacheTtl?: number;
+    /**
+     * Introspection 请求超时时间（毫秒），默认 10 秒。
+     * 超时按验证失败处理（返回 null）。
+     */
+    introspectTimeoutMs?: number;
+    /**
+     * Introspection 返回 active:false（已撤销/无效）结果的缓存 TTL（毫秒），默认 5 秒。
+     * 明显短于 active:true 的 TTL，以降低 token 撤销后的生效延迟。
+     * 设为 0 表示不缓存 active:false 结果。
+     */
+    introspectNegativeCacheTtl?: number;
     /**
      * Access Token RS256 公钥（PEM 格式，可选）。
-     * 主站已迁移至 RS256 签名，子项目可传入此公钥进行本地验证，
-     * 避免每次都调用 Introspection 端点。
+     * 主站在配置 JWT_ACCESS_PRIVATE_KEY 后以 RS256 签名 access_token，
+     * 子项目可传入此公钥进行本地验证，避免每次都调用 Introspection 端点。
+     * 若主站未配置 RS256 密钥（回退 HS256 签名），此选项不生效。
      */
     accessTokenPublicKey?: string;
     /**
@@ -71,6 +84,43 @@ interface SsoVerifierOptions {
      * 若未提供，将回退使用 accessTokenSecret 进行验证。
      */
     logoutTokenSecret?: string;
+    /**
+     * Logout Token RS256 公钥（PEM 格式，可选）。
+     * 主站 logout_token 使用独立密钥对（kid: logout-token-rs256-v1）签名，
+     * 与 access token 密钥不同，因此不能使用 accessTokenPublicKey 验证。
+     * 若未提供但配置了 jwksUri，将通过 JWKS 按 kid 匹配获取对应公钥。
+     * RS256 签名的 logout_token 在无任何可用公钥时验证失败（返回 null），
+     * 不会静默回退到 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;
+}
+/**
+ * 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;
@@ -114,6 +164,7 @@ interface LogoutTokenPayload {
 interface IntrospectResponse {
     active: boolean;
     sub?: string;
+    aud?: string | string[];
     client_id?: string;
     scope?: string;
     exp?: number;
@@ -147,12 +198,27 @@ 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 事件，且事件值为对象
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */
     verifyLogoutToken(token: string): Promise<LogoutTokenPayload | null>;
 };
+/** 框架无关的最小中间件请求类型（兼容 Express/Connect 风格） */
+interface SsoMiddlewareRequest {
+    headers?: Record<string, string | undefined>;
+    /** 验证通过后由中间件挂载的用户信息 */
+    user?: VerifiedTokenPayload;
+    [key: string]: unknown;
+}
+/** 框架无关的最小中间件响应类型 */
+interface SsoMiddlewareResponse {
+    status?: (code: number) => {
+        json: (body: unknown) => unknown;
+    };
+    [key: string]: unknown;
+}
 /**
  * Express/Next.js 兼容中间件
  *
@@ -177,7 +243,7 @@ declare function createTokenVerifier(options: SsoVerifierOptions): {
  * }
  * ```
  */
-declare function ssoMiddleware(options: SsoVerifierOptions): (req: any, res: any, next: () => void) => Promise<void>;
+declare function ssoMiddleware(options: SsoVerifierOptions): (req: SsoMiddlewareRequest, res: SsoMiddlewareResponse, next: (err?: unknown) => void) => Promise<void>;
 /**
  * 创建 Logout Token 专用验证器
  *
@@ -214,4 +280,4 @@ declare function createLogoutTokenVerifier(options: SsoVerifierOptions): {
     verify(token: string): Promise<LogoutTokenPayload | null>;
 };
 
-export { type LogoutTokenPayload, 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） */
@@ -53,10 +54,22 @@ interface SsoVerifierOptions {
     accessTokenSecret?: string;
     /** Introspection 结果缓存 TTL（毫秒），默认 30 秒 */
     introspectCacheTtl?: number;
+    /**
+     * Introspection 请求超时时间（毫秒），默认 10 秒。
+     * 超时按验证失败处理（返回 null）。
+     */
+    introspectTimeoutMs?: number;
+    /**
+     * Introspection 返回 active:false（已撤销/无效）结果的缓存 TTL（毫秒），默认 5 秒。
+     * 明显短于 active:true 的 TTL，以降低 token 撤销后的生效延迟。
+     * 设为 0 表示不缓存 active:false 结果。
+     */
+    introspectNegativeCacheTtl?: number;
     /**
      * Access Token RS256 公钥（PEM 格式，可选）。
-     * 主站已迁移至 RS256 签名，子项目可传入此公钥进行本地验证，
-     * 避免每次都调用 Introspection 端点。
+     * 主站在配置 JWT_ACCESS_PRIVATE_KEY 后以 RS256 签名 access_token，
+     * 子项目可传入此公钥进行本地验证，避免每次都调用 Introspection 端点。
+     * 若主站未配置 RS256 密钥（回退 HS256 签名），此选项不生效。
      */
     accessTokenPublicKey?: string;
     /**
@@ -71,6 +84,43 @@ interface SsoVerifierOptions {
      * 若未提供，将回退使用 accessTokenSecret 进行验证。
      */
     logoutTokenSecret?: string;
+    /**
+     * Logout Token RS256 公钥（PEM 格式，可选）。
+     * 主站 logout_token 使用独立密钥对（kid: logout-token-rs256-v1）签名，
+     * 与 access token 密钥不同，因此不能使用 accessTokenPublicKey 验证。
+     * 若未提供但配置了 jwksUri，将通过 JWKS 按 kid 匹配获取对应公钥。
+     * RS256 签名的 logout_token 在无任何可用公钥时验证失败（返回 null），
+     * 不会静默回退到 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;
+}
+/**
+ * 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;
@@ -114,6 +164,7 @@ interface LogoutTokenPayload {
 interface IntrospectResponse {
     active: boolean;
     sub?: string;
+    aud?: string | string[];
     client_id?: string;
     scope?: string;
     exp?: number;
@@ -147,12 +198,27 @@ 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 事件，且事件值为对象
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */
     verifyLogoutToken(token: string): Promise<LogoutTokenPayload | null>;
 };
+/** 框架无关的最小中间件请求类型（兼容 Express/Connect 风格） */
+interface SsoMiddlewareRequest {
+    headers?: Record<string, string | undefined>;
+    /** 验证通过后由中间件挂载的用户信息 */
+    user?: VerifiedTokenPayload;
+    [key: string]: unknown;
+}
+/** 框架无关的最小中间件响应类型 */
+interface SsoMiddlewareResponse {
+    status?: (code: number) => {
+        json: (body: unknown) => unknown;
+    };
+    [key: string]: unknown;
+}
 /**
  * Express/Next.js 兼容中间件
  *
@@ -177,7 +243,7 @@ declare function createTokenVerifier(options: SsoVerifierOptions): {
  * }
  * ```
  */
-declare function ssoMiddleware(options: SsoVerifierOptions): (req: any, res: any, next: () => void) => Promise<void>;
+declare function ssoMiddleware(options: SsoVerifierOptions): (req: SsoMiddlewareRequest, res: SsoMiddlewareResponse, next: (err?: unknown) => void) => Promise<void>;
 /**
  * 创建 Logout Token 专用验证器
  *
@@ -214,4 +280,4 @@ declare function createLogoutTokenVerifier(options: SsoVerifierOptions): {
     verify(token: string): Promise<LogoutTokenPayload | null>;
 };
 
-export { type LogoutTokenPayload, 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

@@ -48,7 +48,13 @@ function createTokenVerifier(options) {
     accessTokenPublicKey,
     jwksUri,
     logoutTokenSecret,
-    introspectCacheTtl = 30 * 1e3
+    logoutTokenPublicKey,
+    introspectCacheTtl = 30 * 1e3,
+    introspectTimeoutMs = 10 * 1e3,
+    introspectNegativeCacheTtl = 5 * 1e3,
+    introspectRetries = 1,
+    clockToleranceSeconds = 60,
+    logoutJtiStore
   } = options;
   const introspectCache = createIntrospectCache(introspectCacheTtl);
   let _jwksKeySet = null;
@@ -79,6 +85,31 @@ function createTokenVerifier(options) {
     }
     return _rs256PublicKey;
   }
+  let _logoutRs256PublicKey = null;
+  let _logoutRs256KeyInitialized = false;
+  async function getLogoutRS256PublicKey() {
+    if (!_logoutRs256KeyInitialized) {
+      _logoutRs256KeyInitialized = true;
+      if (!logoutTokenPublicKey) {
+        _logoutRs256PublicKey = null;
+      } else {
+        try {
+          _logoutRs256PublicKey = await (0, import_jose.importSPKI)(logoutTokenPublicKey, "RS256");
+        } catch {
+          _logoutRs256PublicKey = null;
+        }
+      }
+    }
+    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 true;
+  }
+  const inflightIntrospects = /* @__PURE__ */ new Map();
   async function introspect(token) {
     if (!introspectionEndpoint || !clientId) {
       return null;
@@ -87,34 +118,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
-      });
-      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;
       }
-      introspectCache.set(token, { active: data.active, payload });
-      return data;
-    } catch {
-      return null;
+      if (!response.ok) {
+        if (response.status >= 500 && attempt < introspectRetries) continue;
+        return null;
+      }
+      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 { 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;
@@ -122,7 +192,9 @@ function createTokenVerifier(options) {
       const secret = new TextEncoder().encode(accessTokenSecret);
       const { payload } = await (0, import_jose.jwtVerify)(token, secret, {
         issuer,
-        audience
+        audience,
+        algorithms: ["HS256"],
+        clockTolerance: clockToleranceSeconds
       });
       if (payload.type !== "access_token") {
         return null;
@@ -142,7 +214,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;
@@ -152,7 +225,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;
@@ -181,9 +255,9 @@ function createTokenVerifier(options) {
       const rs256Result = await verifyWithRS256(token);
       if (rs256Result) return rs256Result;
       const result = await introspect(token);
-      if (!result?.active) return null;
+      if (!result?.active || !result.sub) return null;
       return {
-        sub: result.sub || "",
+        sub: result.sub,
         aud: audience,
         iss: issuer,
         client_id: result.client_id,
@@ -209,39 +283,97 @@ function createTokenVerifier(options) {
      * 1. type === "logout_token"
      * 2. iss 匹配配置的 issuer
      * 3. aud 包含当前 client_id
-     * 4. events 包含 backchannel-logout 事件
+     * 4. exp 存在（规范要求）
+     * 5. events 包含 backchannel-logout 事件，且事件值为对象
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */
     async verifyLogoutToken(token) {
-      const secret = logoutTokenSecret || accessTokenSecret;
-      if (!secret) return null;
-      try {
-        const key = new TextEncoder().encode(secret);
-        const { payload } = await (0, import_jose.jwtVerify)(token, key, {
-          issuer,
-          audience,
-          algorithms: ["HS256"]
-        });
+      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;
         }
-        if (processedLogoutJtis.has(jti)) {
-          return null;
+        const iss = payload.iss || issuer;
+        const jtiKey = `${iss}:${jti}`;
+        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(jti, Date.now());
         return payload;
+      };
+      let alg;
+      try {
+        alg = (0, import_jose.decodeProtectedHeader)(token).alg;
       } catch {
         return null;
       }
+      if (alg === "RS256") {
+        const directKey = await getLogoutRS256PublicKey();
+        if (directKey) {
+          try {
+            const { payload } = await (0, import_jose.jwtVerify)(token, directKey, {
+              issuer,
+              audience,
+              algorithms: ["RS256"],
+              clockTolerance: clockToleranceSeconds
+            });
+            return await validateLogoutPayload(payload);
+          } catch {
+            return null;
+          }
+        }
+        const jwks = getJwksKeySet();
+        if (jwks) {
+          try {
+            const { payload } = await (0, import_jose.jwtVerify)(token, jwks, {
+              issuer,
+              audience,
+              algorithms: ["RS256"],
+              clockTolerance: clockToleranceSeconds
+            });
+            return await validateLogoutPayload(payload);
+          } catch {
+            return null;
+          }
+        }
+        return null;
+      }
+      if (alg === "HS256") {
+        const secret = logoutTokenSecret || accessTokenSecret;
+        if (!secret) return null;
+        try {
+          const key = new TextEncoder().encode(secret);
+          const { payload } = await (0, import_jose.jwtVerify)(token, key, {
+            issuer,
+            audience,
+            algorithms: ["HS256"],
+            clockTolerance: clockToleranceSeconds
+          });
+          return await validateLogoutPayload(payload);
+        } catch {
+          return null;
+        }
+      }
+      return null;
     }
   };
 }
@@ -253,14 +385,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

@@ -1,5 +1,10 @@
 // src/index.ts
-import { jwtVerify, importSPKI, createRemoteJWKSet } from "jose";
+import {
+  jwtVerify,
+  importSPKI,
+  createRemoteJWKSet,
+  decodeProtectedHeader
+} from "jose";
 import { LRUCache } from "lru-cache";
 function createIntrospectCache(ttlMs) {
   return new LRUCache({
@@ -22,7 +27,13 @@ function createTokenVerifier(options) {
     accessTokenPublicKey,
     jwksUri,
     logoutTokenSecret,
-    introspectCacheTtl = 30 * 1e3
+    logoutTokenPublicKey,
+    introspectCacheTtl = 30 * 1e3,
+    introspectTimeoutMs = 10 * 1e3,
+    introspectNegativeCacheTtl = 5 * 1e3,
+    introspectRetries = 1,
+    clockToleranceSeconds = 60,
+    logoutJtiStore
   } = options;
   const introspectCache = createIntrospectCache(introspectCacheTtl);
   let _jwksKeySet = null;
@@ -53,6 +64,31 @@ function createTokenVerifier(options) {
     }
     return _rs256PublicKey;
   }
+  let _logoutRs256PublicKey = null;
+  let _logoutRs256KeyInitialized = false;
+  async function getLogoutRS256PublicKey() {
+    if (!_logoutRs256KeyInitialized) {
+      _logoutRs256KeyInitialized = true;
+      if (!logoutTokenPublicKey) {
+        _logoutRs256PublicKey = null;
+      } else {
+        try {
+          _logoutRs256PublicKey = await importSPKI(logoutTokenPublicKey, "RS256");
+        } catch {
+          _logoutRs256PublicKey = null;
+        }
+      }
+    }
+    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 true;
+  }
+  const inflightIntrospects = /* @__PURE__ */ new Map();
   async function introspect(token) {
     if (!introspectionEndpoint || !clientId) {
       return null;
@@ -61,34 +97,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
-      });
-      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;
       }
-      introspectCache.set(token, { active: data.active, payload });
-      return data;
-    } catch {
-      return null;
+      if (!response.ok) {
+        if (response.status >= 500 && attempt < introspectRetries) continue;
+        return null;
+      }
+      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 { 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;
@@ -96,7 +171,9 @@ function createTokenVerifier(options) {
       const secret = new TextEncoder().encode(accessTokenSecret);
       const { payload } = await jwtVerify(token, secret, {
         issuer,
-        audience
+        audience,
+        algorithms: ["HS256"],
+        clockTolerance: clockToleranceSeconds
       });
       if (payload.type !== "access_token") {
         return null;
@@ -116,7 +193,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;
@@ -126,7 +204,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;
@@ -155,9 +234,9 @@ function createTokenVerifier(options) {
       const rs256Result = await verifyWithRS256(token);
       if (rs256Result) return rs256Result;
       const result = await introspect(token);
-      if (!result?.active) return null;
+      if (!result?.active || !result.sub) return null;
       return {
-        sub: result.sub || "",
+        sub: result.sub,
         aud: audience,
         iss: issuer,
         client_id: result.client_id,
@@ -183,39 +262,97 @@ function createTokenVerifier(options) {
      * 1. type === "logout_token"
      * 2. iss 匹配配置的 issuer
      * 3. aud 包含当前 client_id
-     * 4. events 包含 backchannel-logout 事件
+     * 4. exp 存在（规范要求）
+     * 5. events 包含 backchannel-logout 事件，且事件值为对象
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */
     async verifyLogoutToken(token) {
-      const secret = logoutTokenSecret || accessTokenSecret;
-      if (!secret) return null;
-      try {
-        const key = new TextEncoder().encode(secret);
-        const { payload } = await jwtVerify(token, key, {
-          issuer,
-          audience,
-          algorithms: ["HS256"]
-        });
+      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;
         }
-        if (processedLogoutJtis.has(jti)) {
-          return null;
+        const iss = payload.iss || issuer;
+        const jtiKey = `${iss}:${jti}`;
+        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(jti, Date.now());
         return payload;
+      };
+      let alg;
+      try {
+        alg = decodeProtectedHeader(token).alg;
       } catch {
         return null;
       }
+      if (alg === "RS256") {
+        const directKey = await getLogoutRS256PublicKey();
+        if (directKey) {
+          try {
+            const { payload } = await jwtVerify(token, directKey, {
+              issuer,
+              audience,
+              algorithms: ["RS256"],
+              clockTolerance: clockToleranceSeconds
+            });
+            return await validateLogoutPayload(payload);
+          } catch {
+            return null;
+          }
+        }
+        const jwks = getJwksKeySet();
+        if (jwks) {
+          try {
+            const { payload } = await jwtVerify(token, jwks, {
+              issuer,
+              audience,
+              algorithms: ["RS256"],
+              clockTolerance: clockToleranceSeconds
+            });
+            return await validateLogoutPayload(payload);
+          } catch {
+            return null;
+          }
+        }
+        return null;
+      }
+      if (alg === "HS256") {
+        const secret = logoutTokenSecret || accessTokenSecret;
+        if (!secret) return null;
+        try {
+          const key = new TextEncoder().encode(secret);
+          const { payload } = await jwtVerify(token, key, {
+            issuer,
+            audience,
+            algorithms: ["HS256"],
+            clockTolerance: clockToleranceSeconds
+          });
+          return await validateLogoutPayload(payload);
+        } catch {
+          return null;
+        }
+      }
+      return null;
     }
   };
 }
@@ -227,14 +364,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.0.3",
+  "version": "1.1.1",
   "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",