@nihplod/sso-verify 1.0.3 → 1.1.0

package/README.md

@@ -89,3 +89,23 @@ After successful verification, the token payload is attached to `req.user`.
 - 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.**
+
+## 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 |
+| `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 |
+
+### 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.
+
+### 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.

package/dist/index.d.mts

@@ -53,6 +53,17 @@ 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 签名，子项目可传入此公钥进行本地验证，
@@ -71,6 +82,15 @@ 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;
 }
 interface VerifiedTokenPayload extends JWTPayload {
     sub: string;
@@ -153,6 +173,20 @@ declare function createTokenVerifier(options: SsoVerifierOptions): {
      */
     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 +211,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: () => void) => Promise<void>;
 /**
  * 创建 Logout Token 专用验证器
  *
@@ -214,4 +248,4 @@ declare function createLogoutTokenVerifier(options: SsoVerifierOptions): {
     verify(token: string): Promise<LogoutTokenPayload | null>;
 };
 
-export { type LogoutTokenPayload, type SsoVerifierOptions, type VerifiedTokenPayload, createLogoutTokenVerifier, createTokenVerifier, ssoMiddleware };
+export { type LogoutTokenPayload, type SsoMiddlewareRequest, type SsoMiddlewareResponse, type SsoVerifierOptions, type VerifiedTokenPayload, createLogoutTokenVerifier, createTokenVerifier, ssoMiddleware };

package/dist/index.d.ts

@@ -53,6 +53,17 @@ 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 签名，子项目可传入此公钥进行本地验证，
@@ -71,6 +82,15 @@ 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;
 }
 interface VerifiedTokenPayload extends JWTPayload {
     sub: string;
@@ -153,6 +173,20 @@ declare function createTokenVerifier(options: SsoVerifierOptions): {
      */
     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 +211,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: () => void) => Promise<void>;
 /**
  * 创建 Logout Token 专用验证器
  *
@@ -214,4 +248,4 @@ declare function createLogoutTokenVerifier(options: SsoVerifierOptions): {
     verify(token: string): Promise<LogoutTokenPayload | null>;
 };
 
-export { type LogoutTokenPayload, type SsoVerifierOptions, type VerifiedTokenPayload, createLogoutTokenVerifier, createTokenVerifier, ssoMiddleware };
+export { type LogoutTokenPayload, type SsoMiddlewareRequest, type SsoMiddlewareResponse, type SsoVerifierOptions, type VerifiedTokenPayload, createLogoutTokenVerifier, createTokenVerifier, ssoMiddleware };

package/dist/index.js

@@ -48,7 +48,10 @@ function createTokenVerifier(options) {
     accessTokenPublicKey,
     jwksUri,
     logoutTokenSecret,
-    introspectCacheTtl = 30 * 1e3
+    logoutTokenPublicKey,
+    introspectCacheTtl = 30 * 1e3,
+    introspectTimeoutMs = 10 * 1e3,
+    introspectNegativeCacheTtl = 5 * 1e3
   } = options;
   const introspectCache = createIntrospectCache(introspectCacheTtl);
   let _jwksKeySet = null;
@@ -79,6 +82,23 @@ 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;
+  }
   async function introspect(token) {
     if (!introspectionEndpoint || !clientId) {
       return null;
@@ -95,7 +115,8 @@ function createTokenVerifier(options) {
       const response = await fetch(introspectionEndpoint, {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: params
+        body: params,
+        signal: AbortSignal.timeout(introspectTimeoutMs)
       });
       if (!response.ok) return null;
       const data = await response.json();
@@ -110,7 +131,13 @@ function createTokenVerifier(options) {
           exp: data.exp
         };
       }
-      introspectCache.set(token, { active: data.active, payload });
+      if (data.active) {
+        introspectCache.set(token, { active: true, payload });
+      } else if (introspectNegativeCacheTtl > 0) {
+        introspectCache.set(token, { active: false, payload: null }, {
+          ttl: introspectNegativeCacheTtl
+        });
+      }
       return data;
     } catch {
       return null;
@@ -122,7 +149,8 @@ function createTokenVerifier(options) {
       const secret = new TextEncoder().encode(accessTokenSecret);
       const { payload } = await (0, import_jose.jwtVerify)(token, secret, {
         issuer,
-        audience
+        audience,
+        algorithms: ["HS256"]
       });
       if (payload.type !== "access_token") {
         return null;
@@ -181,9 +209,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,
@@ -214,15 +242,7 @@ function createTokenVerifier(options) {
      * @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 = (payload) => {
         if (payload.type !== "logout_token") {
           return null;
         }
@@ -234,14 +254,65 @@ function createTokenVerifier(options) {
         if (!jti || typeof jti !== "string") {
           return null;
         }
-        if (processedLogoutJtis.has(jti)) {
+        const iss = payload.iss || issuer;
+        const jtiKey = `${iss}:${jti}`;
+        if (processedLogoutJtis.has(jtiKey)) {
           return null;
         }
-        processedLogoutJtis.set(jti, Date.now());
+        processedLogoutJtis.set(jtiKey, 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"]
+            });
+            return validateLogoutPayload(payload);
+          } catch {
+            return null;
+          }
+        }
+        const jwks = getJwksKeySet();
+        if (jwks) {
+          try {
+            const { payload } = await (0, import_jose.jwtVerify)(token, jwks, {
+              issuer,
+              audience,
+              algorithms: ["RS256"]
+            });
+            return 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"]
+          });
+          return validateLogoutPayload(payload);
+        } catch {
+          return null;
+        }
+      }
+      return null;
     }
   };
 }

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,10 @@ function createTokenVerifier(options) {
     accessTokenPublicKey,
     jwksUri,
     logoutTokenSecret,
-    introspectCacheTtl = 30 * 1e3
+    logoutTokenPublicKey,
+    introspectCacheTtl = 30 * 1e3,
+    introspectTimeoutMs = 10 * 1e3,
+    introspectNegativeCacheTtl = 5 * 1e3
   } = options;
   const introspectCache = createIntrospectCache(introspectCacheTtl);
   let _jwksKeySet = null;
@@ -53,6 +61,23 @@ 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;
+  }
   async function introspect(token) {
     if (!introspectionEndpoint || !clientId) {
       return null;
@@ -69,7 +94,8 @@ function createTokenVerifier(options) {
       const response = await fetch(introspectionEndpoint, {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: params
+        body: params,
+        signal: AbortSignal.timeout(introspectTimeoutMs)
       });
       if (!response.ok) return null;
       const data = await response.json();
@@ -84,7 +110,13 @@ function createTokenVerifier(options) {
           exp: data.exp
         };
       }
-      introspectCache.set(token, { active: data.active, payload });
+      if (data.active) {
+        introspectCache.set(token, { active: true, payload });
+      } else if (introspectNegativeCacheTtl > 0) {
+        introspectCache.set(token, { active: false, payload: null }, {
+          ttl: introspectNegativeCacheTtl
+        });
+      }
       return data;
     } catch {
       return null;
@@ -96,7 +128,8 @@ function createTokenVerifier(options) {
       const secret = new TextEncoder().encode(accessTokenSecret);
       const { payload } = await jwtVerify(token, secret, {
         issuer,
-        audience
+        audience,
+        algorithms: ["HS256"]
       });
       if (payload.type !== "access_token") {
         return null;
@@ -155,9 +188,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,
@@ -188,15 +221,7 @@ function createTokenVerifier(options) {
      * @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 = (payload) => {
         if (payload.type !== "logout_token") {
           return null;
         }
@@ -208,14 +233,65 @@ function createTokenVerifier(options) {
         if (!jti || typeof jti !== "string") {
           return null;
         }
-        if (processedLogoutJtis.has(jti)) {
+        const iss = payload.iss || issuer;
+        const jtiKey = `${iss}:${jti}`;
+        if (processedLogoutJtis.has(jtiKey)) {
           return null;
         }
-        processedLogoutJtis.set(jti, Date.now());
+        processedLogoutJtis.set(jtiKey, 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"]
+            });
+            return validateLogoutPayload(payload);
+          } catch {
+            return null;
+          }
+        }
+        const jwks = getJwksKeySet();
+        if (jwks) {
+          try {
+            const { payload } = await jwtVerify(token, jwks, {
+              issuer,
+              audience,
+              algorithms: ["RS256"]
+            });
+            return 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"]
+          });
+          return validateLogoutPayload(payload);
+        } catch {
+          return null;
+        }
+      }
+      return null;
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nihplod/sso-verify",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "NIHPLOD 一网通 SSO Token 验证工具包 — 供子项目在后端验证主站签发的 Access Token",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",