@nihplod/sso-verify 1.1.1 → 1.1.3

package/README.md

@@ -104,6 +104,7 @@ After successful verification, the token payload is attached to `req.user`.
 | `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
 
@@ -119,11 +120,13 @@ When verifying via introspection, the response's audience binding is checked aga
 - 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.
 
-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.
+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.
 

package/dist/index.d.mts

@@ -111,6 +111,17 @@ interface SsoVerifierOptions {
      * 多实例部署时应注入共享存储（如 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 等共享存储实现）。
@@ -136,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": {} }
@@ -148,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（唯一标识，防重放） */
@@ -200,6 +211,7 @@ declare function createTokenVerifier(options: SsoVerifierOptions): {
      * 3. aud 包含当前 client_id
      * 4. exp 存在（规范要求）
      * 5. events 包含 backchannel-logout 事件，且事件值为对象
+     * 6. sub 或 sid 至少其一（§2.4，否则无法定位要终止的会话）
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */

package/dist/index.d.ts

@@ -111,6 +111,17 @@ interface SsoVerifierOptions {
      * 多实例部署时应注入共享存储（如 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 等共享存储实现）。
@@ -136,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": {} }
@@ -148,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（唯一标识，防重放） */
@@ -200,6 +211,7 @@ declare function createTokenVerifier(options: SsoVerifierOptions): {
      * 3. aud 包含当前 client_id
      * 4. exp 存在（规范要求）
      * 5. events 包含 backchannel-logout 事件，且事件值为对象
+     * 6. sub 或 sid 至少其一（§2.4，否则无法定位要终止的会话）
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */

package/dist/index.js

@@ -54,7 +54,8 @@ function createTokenVerifier(options) {
     introspectNegativeCacheTtl = 5 * 1e3,
     introspectRetries = 1,
     clockToleranceSeconds = 60,
-    logoutJtiStore
+    logoutJtiStore,
+    strictAudience = false
   } = options;
   const introspectCache = createIntrospectCache(introspectCacheTtl);
   let _jwksKeySet = null;
@@ -107,7 +108,7 @@ function createTokenVerifier(options) {
     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;
+    return !strictAudience;
   }
   const inflightIntrospects = /* @__PURE__ */ new Map();
   async function introspect(token) {
@@ -186,6 +187,13 @@ function createTokenVerifier(options) {
     }
     return data;
   }
+  function normalizeLocalPayload(payload) {
+    const p = payload;
+    if (!p.sub && typeof p.id === "string" && p.id) {
+      p.sub = p.id;
+    }
+    return p.sub ? p : null;
+  }
   async function verifyLocally(token) {
     if (!accessTokenSecret) return null;
     try {
@@ -199,7 +207,7 @@ function createTokenVerifier(options) {
       if (payload.type !== "access_token") {
         return null;
       }
-      return payload;
+      return normalizeLocalPayload(payload);
     } catch {
       return null;
     }
@@ -218,7 +226,7 @@ function createTokenVerifier(options) {
           clockTolerance: clockToleranceSeconds
         });
         if (payload.type !== "access_token") return null;
-        return payload;
+        return normalizeLocalPayload(payload);
       }
       const jwks = getJwksKeySet();
       if (jwks) {
@@ -229,7 +237,7 @@ function createTokenVerifier(options) {
           clockTolerance: clockToleranceSeconds
         });
         if (payload.type !== "access_token") return null;
-        return payload;
+        return normalizeLocalPayload(payload);
       }
       return null;
     } catch {
@@ -285,6 +293,7 @@ function createTokenVerifier(options) {
      * 3. aud 包含当前 client_id
      * 4. exp 存在（规范要求）
      * 5. events 包含 backchannel-logout 事件，且事件值为对象
+     * 6. sub 或 sid 至少其一（§2.4，否则无法定位要终止的会话）
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */
@@ -305,6 +314,13 @@ function createTokenVerifier(options) {
         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 (logoutJtiStore) {

package/dist/index.mjs

@@ -33,7 +33,8 @@ function createTokenVerifier(options) {
     introspectNegativeCacheTtl = 5 * 1e3,
     introspectRetries = 1,
     clockToleranceSeconds = 60,
-    logoutJtiStore
+    logoutJtiStore,
+    strictAudience = false
   } = options;
   const introspectCache = createIntrospectCache(introspectCacheTtl);
   let _jwksKeySet = null;
@@ -86,7 +87,7 @@ function createTokenVerifier(options) {
     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;
+    return !strictAudience;
   }
   const inflightIntrospects = /* @__PURE__ */ new Map();
   async function introspect(token) {
@@ -165,6 +166,13 @@ function createTokenVerifier(options) {
     }
     return data;
   }
+  function normalizeLocalPayload(payload) {
+    const p = payload;
+    if (!p.sub && typeof p.id === "string" && p.id) {
+      p.sub = p.id;
+    }
+    return p.sub ? p : null;
+  }
   async function verifyLocally(token) {
     if (!accessTokenSecret) return null;
     try {
@@ -178,7 +186,7 @@ function createTokenVerifier(options) {
       if (payload.type !== "access_token") {
         return null;
       }
-      return payload;
+      return normalizeLocalPayload(payload);
     } catch {
       return null;
     }
@@ -197,7 +205,7 @@ function createTokenVerifier(options) {
           clockTolerance: clockToleranceSeconds
         });
         if (payload.type !== "access_token") return null;
-        return payload;
+        return normalizeLocalPayload(payload);
       }
       const jwks = getJwksKeySet();
       if (jwks) {
@@ -208,7 +216,7 @@ function createTokenVerifier(options) {
           clockTolerance: clockToleranceSeconds
         });
         if (payload.type !== "access_token") return null;
-        return payload;
+        return normalizeLocalPayload(payload);
       }
       return null;
     } catch {
@@ -264,6 +272,7 @@ function createTokenVerifier(options) {
      * 3. aud 包含当前 client_id
      * 4. exp 存在（规范要求）
      * 5. events 包含 backchannel-logout 事件，且事件值为对象
+     * 6. sub 或 sid 至少其一（§2.4，否则无法定位要终止的会话）
      *
      * @returns LogoutTokenPayload 或 null（验证失败）
      */
@@ -284,6 +293,13 @@ function createTokenVerifier(options) {
         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 (logoutJtiStore) {

package/package.json

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