@nihplod/sso-verify 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# @nihplod/sso-verify
+
+NIHPLOD 一网通 SSO Token 验证工具包 — 供子项目在后端验证主站签发的 Access Token。
+
+## 安装
+
+```bash
+npm install @nihplod/sso-verify
+```
+
+## 使用方式
+
+### 方式一：Introspection 验证（推荐）
+
+适用于所有子项目，无需接触签名密钥。
+
+```typescript
+import { createTokenVerifier } from "@nihplod/sso-verify";
+
+const verifier = createTokenVerifier({
+  introspectionEndpoint: "https://nihplod.cn/api/oauth/introspect",
+  clientId: "your-client-id",
+  clientSecret: "your-client-secret",
+  audience: "your-client-id",
+  issuer: "https://nihplod.cn",
+});
+
+const payload = await verifier.verify(token);
+if (payload) {
+  console.log(payload.sub); // 用户 ID
+}
+```
+
+### 方式二：本地 JWT 验证（仅内部 Confidential Client）
+
+仅当子项目与主站共享 `JWT_ACCESS_SECRET` 时使用。
+
+```typescript
+import { createTokenVerifier } from "@nihplod/sso-verify";
+
+const verifier = createTokenVerifier({
+  accessTokenSecret: process.env.JWT_ACCESS_SECRET,
+  audience: "your-client-id",
+  issuer: "https://nihplod.cn",
+});
+
+const payload = await verifier.verify(token);
+```
+
+## Express / Connect 中间件
+
+```typescript
+import { ssoMiddleware } from "@nihplod/sso-verify";
+
+app.use(
+  "/api/protected",
+  ssoMiddleware({
+    introspectionEndpoint: "https://nihplod.cn/api/oauth/introspect",
+    clientId: "your-client-id",
+    clientSecret: "your-client-secret",
+    audience: "your-client-id",
+  })
+);
+```
+
+验证成功后，`req.user` 会挂载 token payload。
+
+## 注意事项
+
+- 当前主站默认使用 HS256 对称签名。对于外部子项目，推荐优先使用 **Introspection 模式** 验证 access_token。
+- 若你的子项目是内部服务且已与主站共享 RS256 公钥，可配置 `accessTokenPublicKey` 或 `jwksUri` 做本地 JWT 验证。
+- **不要将 `JWT_ACCESS_SECRET`（HS256 对称密钥）分发给外部子项目。**

package/dist/index.d.mts

@@ -0,0 +1,217 @@
+import { JWTPayload } from 'jose';
+
+/**
+ * @nihplod/sso-verify
+ *
+ * NIHPLOD 一网通 SSO Token 验证工具包
+ *
+ * 供子项目在后端验证主站签发的 Access Token。
+ *
+ * 由于主站当前使用 HS256 对称签名，JWKS 端点不公开签名密钥，
+ * 因此本工具包默认采用 OAuth 2.0 Token Introspection（RFC 7662）
+ * 端点进行验证。对于已知共享密钥的内部服务，也可传入
+ * accessTokenSecret 做本地 JWT 验证。
+ *
+ * 安装：npm install @nihplod/sso-verify
+ *
+ * 使用：
+ * ```typescript
+ * import { createTokenVerifier } from "@nihplod/sso-verify";
+ * const verifier = createTokenVerifier({
+ *   introspectionEndpoint: "https://nihplod.cn/api/oauth/introspect",
+ *   clientId: "advisor",
+ *   clientSecret: "YOUR_CLIENT_SECRET",
+ *   audience: "advisor",
+ * });
+ *
+ * const payload = await verifier.verify(token);
+ * if (payload) {
+ *   console.log(payload.sub); // 用户 ID
+ * }
+ * ```
+ */
+
+interface SsoVerifierOptions {
+    /** 期望的 audience（对应子项目的 client_id） */
+    audience: string;
+    /** 期望的 issuer（主站 URL），默认 "https://nihplod.cn" */
+    issuer?: string;
+    /**
+     * Token Introspection 端点 URL。
+     * 推荐优先使用，适配当前 HS256 对称签名场景。
+     */
+    introspectionEndpoint?: string;
+    /** 子项目的 client_id（用于 introspection） */
+    clientId?: string;
+    /** 子项目的 client_secret（用于 introspection） */
+    clientSecret?: string;
+    /**
+     * 共享的 Access Token Secret（可选）。
+     * 仅在子项目与主站共享 JWT_ACCESS_SECRET 时使用本地验证。
+     * 注意：当前 JWKS 端点不公开对称密钥，因此不能通过 JWKS 获取此值。
+     */
+    accessTokenSecret?: string;
+    /** Introspection 结果缓存 TTL（毫秒），默认 30 秒 */
+    introspectCacheTtl?: number;
+    /**
+     * Access Token RS256 公钥（PEM 格式，可选）。
+     * 主站已迁移至 RS256 签名，子项目可传入此公钥进行本地验证，
+     * 避免每次都调用 Introspection 端点。
+     */
+    accessTokenPublicKey?: string;
+    /**
+     * JWKS 端点 URL（可选）。
+     * 子项目可传入此 URL 以动态获取 RS256 公钥进行本地验证。
+     * 当 accessTokenPublicKey 未配置时，将通过此端点获取匹配 kid 的公钥。
+     */
+    jwksUri?: string;
+    /**
+     * Logout Token Secret（可选）。
+     * 用于本地验证主站签发的 logout_token（HS256 签名）。
+     * 若未提供，将回退使用 accessTokenSecret 进行验证。
+     */
+    logoutTokenSecret?: string;
+}
+interface VerifiedTokenPayload extends JWTPayload {
+    sub: string;
+    aud: string;
+    iss: string;
+    client_id?: string;
+    scope?: string;
+    phone?: string;
+}
+/**
+ * Logout Token Payload（RFC 7519 + OIDC Back-Channel Logout 1.0）
+ *
+ * 主站签发 logout_token 时包含以下字段：
+ * - iss: 主站 issuer
+ * - aud: 目标 client_id
+ * - sub: 用户 ID
+ * - iat: 签发时间
+ * - jti: 唯一 ID（防重放，建议接收方缓存已处理的 jti）
+ * - events: { "http://schemas.openid.net/event/backchannel-logout": {} }
+ */
+interface LogoutTokenPayload {
+    /** JWT type，logout_token 固定值为 "logout_token" */
+    type: "logout_token";
+    /** 签发者 */
+    iss: string;
+    /** 目标 audience */
+    aud: string;
+    /** 用户 ID */
+    sub: string;
+    /** 签发时间（UNIX timestamp） */
+    iat: number;
+    /** JWT ID（唯一标识，防重放） */
+    jti: string;
+    /** Backchannel logout 事件声明 */
+    events: {
+        "http://schemas.openid.net/event/backchannel-logout": Record<string, never>;
+    };
+    /** sid (Session ID)，可选 */
+    sid?: string;
+}
+interface IntrospectResponse {
+    active: boolean;
+    sub?: string;
+    client_id?: string;
+    scope?: string;
+    exp?: number;
+    [key: string]: unknown;
+}
+declare function createTokenVerifier(options: SsoVerifierOptions): {
+    /**
+     * 验证 Access Token
+     *
+     * 验证顺序：
+     * 1. 若配置了 accessTokenSecret，先尝试 HS256 本地验证
+     * 2. 若配置了 accessTokenPublicKey 或 jwksUri，尝试 RS256 本地验证
+     * 3. 若上述均失败/未配置，调用 Introspection 端点
+     *
+     * @returns token payload 或者 null（验证失败）
+     */
+    verify(token: string): Promise<VerifiedTokenPayload | null>;
+    /**
+     * 直接调用 Introspection 端点
+     */
+    introspect: (token: string) => Promise<IntrospectResponse | null>;
+    /**
+     * 清除指定 token 的 Introspection 缓存
+     */
+    invalidateCache(token: string): void;
+    /**
+     * 验证 Logout Token（Back-Channel Logout）
+     *
+     * 用于子项目接收主站 backchannel logout 通知时验证 logout_token。
+     * 验证要求（OIDC Back-Channel Logout 1.0）：
+     * 1. type === "logout_token"
+     * 2. iss 匹配配置的 issuer
+     * 3. aud 包含当前 client_id
+     * 4. events 包含 backchannel-logout 事件
+     *
+     * @returns LogoutTokenPayload 或 null（验证失败）
+     */
+    verifyLogoutToken(token: string): Promise<LogoutTokenPayload | null>;
+};
+/**
+ * Express/Next.js 兼容中间件
+ *
+ * 使用示例（Express）:
+ * ```typescript
+ * app.use(ssoMiddleware({
+ *   introspectionEndpoint: "https://nihplod.cn/api/oauth/introspect",
+ *   clientId: "advisor",
+ *   clientSecret: "SECRET",
+ *   audience: "advisor",
+ * }));
+ * ```
+ *
+ * 使用示例（Next.js Route Handler）:
+ * ```typescript
+ * const verifier = createTokenVerifier({ ... });
+ * export async function GET(request: NextRequest) {
+ *   const token = request.headers.get("authorization")?.replace("Bearer ", "");
+ *   const payload = token ? await verifier.verify(token) : null;
+ *   if (!payload) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ *   // ...
+ * }
+ * ```
+ */
+declare function ssoMiddleware(options: SsoVerifierOptions): (req: any, res: any, next: () => void) => Promise<void>;
+/**
+ * 创建 Logout Token 专用验证器
+ *
+ * 适用于仅需处理 backchannel logout 的子项目。
+ * 内部调用 createTokenVerifier 并暴露 verifyLogoutToken 方法。
+ *
+ * 使用示例：
+ * ```typescript
+ * import { createLogoutTokenVerifier } from "@nihplod/sso-verify";
+ *
+ * const logoutVerifier = createLogoutTokenVerifier({
+ *   audience: "advisor",
+ *   issuer: "https://nihplod.cn",
+ *   logoutTokenSecret: process.env.LOGOUT_TOKEN_SECRET,
+ * });
+ *
+ * // 在 backchannel logout 端点中：
+ * app.post("/api/auth/backchannel-logout", async (req, res) => {
+ *   const token = req.body.logout_token;
+ *   const payload = await logoutVerifier.verify(token);
+ *   if (payload) {
+ *     await clearUserSession(payload.sub);
+ *     res.status(200).end();
+ *   } else {
+ *     res.status(400).end();
+ *   }
+ * });
+ * ```
+ */
+declare function createLogoutTokenVerifier(options: SsoVerifierOptions): {
+    /**
+     * 验证 logout_token
+     */
+    verify(token: string): Promise<LogoutTokenPayload | null>;
+};
+
+export { type LogoutTokenPayload, type SsoVerifierOptions, type VerifiedTokenPayload, createLogoutTokenVerifier, createTokenVerifier, ssoMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,217 @@
+import { JWTPayload } from 'jose';
+
+/**
+ * @nihplod/sso-verify
+ *
+ * NIHPLOD 一网通 SSO Token 验证工具包
+ *
+ * 供子项目在后端验证主站签发的 Access Token。
+ *
+ * 由于主站当前使用 HS256 对称签名，JWKS 端点不公开签名密钥，
+ * 因此本工具包默认采用 OAuth 2.0 Token Introspection（RFC 7662）
+ * 端点进行验证。对于已知共享密钥的内部服务，也可传入
+ * accessTokenSecret 做本地 JWT 验证。
+ *
+ * 安装：npm install @nihplod/sso-verify
+ *
+ * 使用：
+ * ```typescript
+ * import { createTokenVerifier } from "@nihplod/sso-verify";
+ * const verifier = createTokenVerifier({
+ *   introspectionEndpoint: "https://nihplod.cn/api/oauth/introspect",
+ *   clientId: "advisor",
+ *   clientSecret: "YOUR_CLIENT_SECRET",
+ *   audience: "advisor",
+ * });
+ *
+ * const payload = await verifier.verify(token);
+ * if (payload) {
+ *   console.log(payload.sub); // 用户 ID
+ * }
+ * ```
+ */
+
+interface SsoVerifierOptions {
+    /** 期望的 audience（对应子项目的 client_id） */
+    audience: string;
+    /** 期望的 issuer（主站 URL），默认 "https://nihplod.cn" */
+    issuer?: string;
+    /**
+     * Token Introspection 端点 URL。
+     * 推荐优先使用，适配当前 HS256 对称签名场景。
+     */
+    introspectionEndpoint?: string;
+    /** 子项目的 client_id（用于 introspection） */
+    clientId?: string;
+    /** 子项目的 client_secret（用于 introspection） */
+    clientSecret?: string;
+    /**
+     * 共享的 Access Token Secret（可选）。
+     * 仅在子项目与主站共享 JWT_ACCESS_SECRET 时使用本地验证。
+     * 注意：当前 JWKS 端点不公开对称密钥，因此不能通过 JWKS 获取此值。
+     */
+    accessTokenSecret?: string;
+    /** Introspection 结果缓存 TTL（毫秒），默认 30 秒 */
+    introspectCacheTtl?: number;
+    /**
+     * Access Token RS256 公钥（PEM 格式，可选）。
+     * 主站已迁移至 RS256 签名，子项目可传入此公钥进行本地验证，
+     * 避免每次都调用 Introspection 端点。
+     */
+    accessTokenPublicKey?: string;
+    /**
+     * JWKS 端点 URL（可选）。
+     * 子项目可传入此 URL 以动态获取 RS256 公钥进行本地验证。
+     * 当 accessTokenPublicKey 未配置时，将通过此端点获取匹配 kid 的公钥。
+     */
+    jwksUri?: string;
+    /**
+     * Logout Token Secret（可选）。
+     * 用于本地验证主站签发的 logout_token（HS256 签名）。
+     * 若未提供，将回退使用 accessTokenSecret 进行验证。
+     */
+    logoutTokenSecret?: string;
+}
+interface VerifiedTokenPayload extends JWTPayload {
+    sub: string;
+    aud: string;
+    iss: string;
+    client_id?: string;
+    scope?: string;
+    phone?: string;
+}
+/**
+ * Logout Token Payload（RFC 7519 + OIDC Back-Channel Logout 1.0）
+ *
+ * 主站签发 logout_token 时包含以下字段：
+ * - iss: 主站 issuer
+ * - aud: 目标 client_id
+ * - sub: 用户 ID
+ * - iat: 签发时间
+ * - jti: 唯一 ID（防重放，建议接收方缓存已处理的 jti）
+ * - events: { "http://schemas.openid.net/event/backchannel-logout": {} }
+ */
+interface LogoutTokenPayload {
+    /** JWT type，logout_token 固定值为 "logout_token" */
+    type: "logout_token";
+    /** 签发者 */
+    iss: string;
+    /** 目标 audience */
+    aud: string;
+    /** 用户 ID */
+    sub: string;
+    /** 签发时间（UNIX timestamp） */
+    iat: number;
+    /** JWT ID（唯一标识，防重放） */
+    jti: string;
+    /** Backchannel logout 事件声明 */
+    events: {
+        "http://schemas.openid.net/event/backchannel-logout": Record<string, never>;
+    };
+    /** sid (Session ID)，可选 */
+    sid?: string;
+}
+interface IntrospectResponse {
+    active: boolean;
+    sub?: string;
+    client_id?: string;
+    scope?: string;
+    exp?: number;
+    [key: string]: unknown;
+}
+declare function createTokenVerifier(options: SsoVerifierOptions): {
+    /**
+     * 验证 Access Token
+     *
+     * 验证顺序：
+     * 1. 若配置了 accessTokenSecret，先尝试 HS256 本地验证
+     * 2. 若配置了 accessTokenPublicKey 或 jwksUri，尝试 RS256 本地验证
+     * 3. 若上述均失败/未配置，调用 Introspection 端点
+     *
+     * @returns token payload 或者 null（验证失败）
+     */
+    verify(token: string): Promise<VerifiedTokenPayload | null>;
+    /**
+     * 直接调用 Introspection 端点
+     */
+    introspect: (token: string) => Promise<IntrospectResponse | null>;
+    /**
+     * 清除指定 token 的 Introspection 缓存
+     */
+    invalidateCache(token: string): void;
+    /**
+     * 验证 Logout Token（Back-Channel Logout）
+     *
+     * 用于子项目接收主站 backchannel logout 通知时验证 logout_token。
+     * 验证要求（OIDC Back-Channel Logout 1.0）：
+     * 1. type === "logout_token"
+     * 2. iss 匹配配置的 issuer
+     * 3. aud 包含当前 client_id
+     * 4. events 包含 backchannel-logout 事件
+     *
+     * @returns LogoutTokenPayload 或 null（验证失败）
+     */
+    verifyLogoutToken(token: string): Promise<LogoutTokenPayload | null>;
+};
+/**
+ * Express/Next.js 兼容中间件
+ *
+ * 使用示例（Express）:
+ * ```typescript
+ * app.use(ssoMiddleware({
+ *   introspectionEndpoint: "https://nihplod.cn/api/oauth/introspect",
+ *   clientId: "advisor",
+ *   clientSecret: "SECRET",
+ *   audience: "advisor",
+ * }));
+ * ```
+ *
+ * 使用示例（Next.js Route Handler）:
+ * ```typescript
+ * const verifier = createTokenVerifier({ ... });
+ * export async function GET(request: NextRequest) {
+ *   const token = request.headers.get("authorization")?.replace("Bearer ", "");
+ *   const payload = token ? await verifier.verify(token) : null;
+ *   if (!payload) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ *   // ...
+ * }
+ * ```
+ */
+declare function ssoMiddleware(options: SsoVerifierOptions): (req: any, res: any, next: () => void) => Promise<void>;
+/**
+ * 创建 Logout Token 专用验证器
+ *
+ * 适用于仅需处理 backchannel logout 的子项目。
+ * 内部调用 createTokenVerifier 并暴露 verifyLogoutToken 方法。
+ *
+ * 使用示例：
+ * ```typescript
+ * import { createLogoutTokenVerifier } from "@nihplod/sso-verify";
+ *
+ * const logoutVerifier = createLogoutTokenVerifier({
+ *   audience: "advisor",
+ *   issuer: "https://nihplod.cn",
+ *   logoutTokenSecret: process.env.LOGOUT_TOKEN_SECRET,
+ * });
+ *
+ * // 在 backchannel logout 端点中：
+ * app.post("/api/auth/backchannel-logout", async (req, res) => {
+ *   const token = req.body.logout_token;
+ *   const payload = await logoutVerifier.verify(token);
+ *   if (payload) {
+ *     await clearUserSession(payload.sub);
+ *     res.status(200).end();
+ *   } else {
+ *     res.status(400).end();
+ *   }
+ * });
+ * ```
+ */
+declare function createLogoutTokenVerifier(options: SsoVerifierOptions): {
+    /**
+     * 验证 logout_token
+     */
+    verify(token: string): Promise<LogoutTokenPayload | null>;
+};
+
+export { type LogoutTokenPayload, type SsoVerifierOptions, type VerifiedTokenPayload, createLogoutTokenVerifier, createTokenVerifier, ssoMiddleware };

package/dist/index.js

@@ -0,0 +1,286 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createLogoutTokenVerifier: () => createLogoutTokenVerifier,
+  createTokenVerifier: () => createTokenVerifier,
+  ssoMiddleware: () => ssoMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+var import_jose = require("jose");
+var import_lru_cache = require("lru-cache");
+function createIntrospectCache(ttlMs) {
+  return new import_lru_cache.LRUCache({
+    max: 1e4,
+    ttl: ttlMs
+  });
+}
+var processedLogoutJtis = new import_lru_cache.LRUCache({
+  max: 1e4,
+  ttl: 10 * 60 * 1e3
+});
+function createTokenVerifier(options) {
+  const {
+    audience,
+    issuer = "https://nihplod.cn",
+    introspectionEndpoint,
+    clientId,
+    clientSecret,
+    accessTokenSecret,
+    accessTokenPublicKey,
+    jwksUri,
+    logoutTokenSecret,
+    introspectCacheTtl = 30 * 1e3
+  } = options;
+  const introspectCache = createIntrospectCache(introspectCacheTtl);
+  let _jwksKeySet = null;
+  function getJwksKeySet() {
+    if (!jwksUri) return null;
+    if (!_jwksKeySet) {
+      _jwksKeySet = (0, import_jose.createRemoteJWKSet)(new URL(jwksUri), {
+        cacheMaxAge: 60 * 60 * 1e3
+        // 1 小时缓存
+      });
+    }
+    return _jwksKeySet;
+  }
+  let _rs256PublicKey = null;
+  let _rs256KeyInitialized = false;
+  async function getRS256PublicKey() {
+    if (!_rs256KeyInitialized) {
+      _rs256KeyInitialized = true;
+      if (!accessTokenPublicKey) {
+        _rs256PublicKey = null;
+      } else {
+        try {
+          _rs256PublicKey = await (0, import_jose.importSPKI)(accessTokenPublicKey, "RS256");
+        } catch {
+          _rs256PublicKey = null;
+        }
+      }
+    }
+    return _rs256PublicKey;
+  }
+  async function introspect(token) {
+    if (!introspectionEndpoint || !clientId || !clientSecret) {
+      return null;
+    }
+    const cached = introspectCache.get(token);
+    if (cached) {
+      return { active: cached.active, ...cached.payload || {} };
+    }
+    try {
+      const response = await fetch(introspectionEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          token,
+          client_id: clientId,
+          client_secret: clientSecret
+        })
+      });
+      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
+        };
+      }
+      introspectCache.set(token, { active: data.active, payload });
+      return data;
+    } catch {
+      return null;
+    }
+  }
+  async function verifyLocally(token) {
+    if (!accessTokenSecret) return null;
+    try {
+      const secret = new TextEncoder().encode(accessTokenSecret);
+      const { payload } = await (0, import_jose.jwtVerify)(token, secret, {
+        issuer,
+        audience
+      });
+      if (payload.type !== "access_token") {
+        return null;
+      }
+      return payload;
+    } catch {
+      return null;
+    }
+  }
+  async function verifyWithRS256(token) {
+    const hasPublicKey = Boolean(accessTokenPublicKey);
+    const hasJwks = Boolean(jwksUri);
+    if (!hasPublicKey && !hasJwks) return null;
+    try {
+      const directKey = await getRS256PublicKey();
+      if (directKey) {
+        const { payload } = await (0, import_jose.jwtVerify)(token, directKey, {
+          issuer,
+          audience,
+          algorithms: ["RS256"]
+        });
+        if (payload.type !== "access_token") return null;
+        return payload;
+      }
+      const jwks = getJwksKeySet();
+      if (jwks) {
+        const { payload } = await (0, import_jose.jwtVerify)(token, jwks, {
+          issuer,
+          audience,
+          algorithms: ["RS256"]
+        });
+        if (payload.type !== "access_token") return null;
+        return payload;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  return {
+    /**
+     * 验证 Access Token
+     *
+     * 验证顺序：
+     * 1. 若配置了 accessTokenSecret，先尝试 HS256 本地验证
+     * 2. 若配置了 accessTokenPublicKey 或 jwksUri，尝试 RS256 本地验证
+     * 3. 若上述均失败/未配置，调用 Introspection 端点
+     *
+     * @returns token payload 或者 null（验证失败）
+     */
+    async verify(token) {
+      if (accessTokenSecret) {
+        const local = await verifyLocally(token);
+        if (local) return local;
+      }
+      const rs256Result = await verifyWithRS256(token);
+      if (rs256Result) return rs256Result;
+      const result = await introspect(token);
+      if (!result?.active) return null;
+      return {
+        sub: result.sub || "",
+        aud: audience,
+        iss: issuer,
+        client_id: result.client_id,
+        scope: result.scope,
+        exp: result.exp
+      };
+    },
+    /**
+     * 直接调用 Introspection 端点
+     */
+    introspect,
+    /**
+     * 清除指定 token 的 Introspection 缓存
+     */
+    invalidateCache(token) {
+      introspectCache.delete(token);
+    },
+    /**
+     * 验证 Logout Token（Back-Channel Logout）
+     *
+     * 用于子项目接收主站 backchannel logout 通知时验证 logout_token。
+     * 验证要求（OIDC Back-Channel Logout 1.0）：
+     * 1. type === "logout_token"
+     * 2. iss 匹配配置的 issuer
+     * 3. aud 包含当前 client_id
+     * 4. 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"]
+        });
+        if (payload.type !== "logout_token") {
+          return null;
+        }
+        const events = payload.events;
+        if (!events || !events["http://schemas.openid.net/event/backchannel-logout"]) {
+          return null;
+        }
+        const jti = payload.jti;
+        if (!jti || typeof jti !== "string") {
+          return null;
+        }
+        if (processedLogoutJtis.has(jti)) {
+          return null;
+        }
+        processedLogoutJtis.set(jti, Date.now());
+        return payload;
+      } catch {
+        return null;
+      }
+    }
+  };
+}
+function ssoMiddleware(options) {
+  const verifier = createTokenVerifier(options);
+  return async (req, res, next) => {
+    const authHeader = req.headers?.authorization || req.headers?.Authorization || "";
+    const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
+    if (!token) {
+      if (res.status) {
+        res.status(401).json({ error: "Unauthorized", message: "\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;
+    }
+    req.user = payload;
+    next();
+  };
+}
+function createLogoutTokenVerifier(options) {
+  const verifier = createTokenVerifier(options);
+  return {
+    /**
+     * 验证 logout_token
+     */
+    async verify(token) {
+      return verifier.verifyLogoutToken(token);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createLogoutTokenVerifier,
+  createTokenVerifier,
+  ssoMiddleware
+});

package/dist/index.mjs

@@ -0,0 +1,259 @@
+// src/index.ts
+import { jwtVerify, importSPKI, createRemoteJWKSet } from "jose";
+import { LRUCache } from "lru-cache";
+function createIntrospectCache(ttlMs) {
+  return new LRUCache({
+    max: 1e4,
+    ttl: ttlMs
+  });
+}
+var processedLogoutJtis = new LRUCache({
+  max: 1e4,
+  ttl: 10 * 60 * 1e3
+});
+function createTokenVerifier(options) {
+  const {
+    audience,
+    issuer = "https://nihplod.cn",
+    introspectionEndpoint,
+    clientId,
+    clientSecret,
+    accessTokenSecret,
+    accessTokenPublicKey,
+    jwksUri,
+    logoutTokenSecret,
+    introspectCacheTtl = 30 * 1e3
+  } = options;
+  const introspectCache = createIntrospectCache(introspectCacheTtl);
+  let _jwksKeySet = null;
+  function getJwksKeySet() {
+    if (!jwksUri) return null;
+    if (!_jwksKeySet) {
+      _jwksKeySet = createRemoteJWKSet(new URL(jwksUri), {
+        cacheMaxAge: 60 * 60 * 1e3
+        // 1 小时缓存
+      });
+    }
+    return _jwksKeySet;
+  }
+  let _rs256PublicKey = null;
+  let _rs256KeyInitialized = false;
+  async function getRS256PublicKey() {
+    if (!_rs256KeyInitialized) {
+      _rs256KeyInitialized = true;
+      if (!accessTokenPublicKey) {
+        _rs256PublicKey = null;
+      } else {
+        try {
+          _rs256PublicKey = await importSPKI(accessTokenPublicKey, "RS256");
+        } catch {
+          _rs256PublicKey = null;
+        }
+      }
+    }
+    return _rs256PublicKey;
+  }
+  async function introspect(token) {
+    if (!introspectionEndpoint || !clientId || !clientSecret) {
+      return null;
+    }
+    const cached = introspectCache.get(token);
+    if (cached) {
+      return { active: cached.active, ...cached.payload || {} };
+    }
+    try {
+      const response = await fetch(introspectionEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          token,
+          client_id: clientId,
+          client_secret: clientSecret
+        })
+      });
+      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
+        };
+      }
+      introspectCache.set(token, { active: data.active, payload });
+      return data;
+    } catch {
+      return null;
+    }
+  }
+  async function verifyLocally(token) {
+    if (!accessTokenSecret) return null;
+    try {
+      const secret = new TextEncoder().encode(accessTokenSecret);
+      const { payload } = await jwtVerify(token, secret, {
+        issuer,
+        audience
+      });
+      if (payload.type !== "access_token") {
+        return null;
+      }
+      return payload;
+    } catch {
+      return null;
+    }
+  }
+  async function verifyWithRS256(token) {
+    const hasPublicKey = Boolean(accessTokenPublicKey);
+    const hasJwks = Boolean(jwksUri);
+    if (!hasPublicKey && !hasJwks) return null;
+    try {
+      const directKey = await getRS256PublicKey();
+      if (directKey) {
+        const { payload } = await jwtVerify(token, directKey, {
+          issuer,
+          audience,
+          algorithms: ["RS256"]
+        });
+        if (payload.type !== "access_token") return null;
+        return payload;
+      }
+      const jwks = getJwksKeySet();
+      if (jwks) {
+        const { payload } = await jwtVerify(token, jwks, {
+          issuer,
+          audience,
+          algorithms: ["RS256"]
+        });
+        if (payload.type !== "access_token") return null;
+        return payload;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  return {
+    /**
+     * 验证 Access Token
+     *
+     * 验证顺序：
+     * 1. 若配置了 accessTokenSecret，先尝试 HS256 本地验证
+     * 2. 若配置了 accessTokenPublicKey 或 jwksUri，尝试 RS256 本地验证
+     * 3. 若上述均失败/未配置，调用 Introspection 端点
+     *
+     * @returns token payload 或者 null（验证失败）
+     */
+    async verify(token) {
+      if (accessTokenSecret) {
+        const local = await verifyLocally(token);
+        if (local) return local;
+      }
+      const rs256Result = await verifyWithRS256(token);
+      if (rs256Result) return rs256Result;
+      const result = await introspect(token);
+      if (!result?.active) return null;
+      return {
+        sub: result.sub || "",
+        aud: audience,
+        iss: issuer,
+        client_id: result.client_id,
+        scope: result.scope,
+        exp: result.exp
+      };
+    },
+    /**
+     * 直接调用 Introspection 端点
+     */
+    introspect,
+    /**
+     * 清除指定 token 的 Introspection 缓存
+     */
+    invalidateCache(token) {
+      introspectCache.delete(token);
+    },
+    /**
+     * 验证 Logout Token（Back-Channel Logout）
+     *
+     * 用于子项目接收主站 backchannel logout 通知时验证 logout_token。
+     * 验证要求（OIDC Back-Channel Logout 1.0）：
+     * 1. type === "logout_token"
+     * 2. iss 匹配配置的 issuer
+     * 3. aud 包含当前 client_id
+     * 4. 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"]
+        });
+        if (payload.type !== "logout_token") {
+          return null;
+        }
+        const events = payload.events;
+        if (!events || !events["http://schemas.openid.net/event/backchannel-logout"]) {
+          return null;
+        }
+        const jti = payload.jti;
+        if (!jti || typeof jti !== "string") {
+          return null;
+        }
+        if (processedLogoutJtis.has(jti)) {
+          return null;
+        }
+        processedLogoutJtis.set(jti, Date.now());
+        return payload;
+      } catch {
+        return null;
+      }
+    }
+  };
+}
+function ssoMiddleware(options) {
+  const verifier = createTokenVerifier(options);
+  return async (req, res, next) => {
+    const authHeader = req.headers?.authorization || req.headers?.Authorization || "";
+    const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
+    if (!token) {
+      if (res.status) {
+        res.status(401).json({ error: "Unauthorized", message: "\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;
+    }
+    req.user = payload;
+    next();
+  };
+}
+function createLogoutTokenVerifier(options) {
+  const verifier = createTokenVerifier(options);
+  return {
+    /**
+     * 验证 logout_token
+     */
+    async verify(token) {
+      return verifier.verifyLogoutToken(token);
+    }
+  };
+}
+export {
+  createLogoutTokenVerifier,
+  createTokenVerifier,
+  ssoMiddleware
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nihplod/sso-verify",
+  "version": "1.0.0",
+  "description": "NIHPLOD 一网通 SSO Token 验证工具包 — 供子项目在后端验证主站签发的 Access Token",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sso",
+    "oauth2",
+    "jwt",
+    "jwks",
+    "token-verification",
+    "nihplod"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nihplod/nihplod.cn",
+    "directory": "packages/sso-verify"
+  },
+  "peerDependencies": {},
+  "dependencies": {
+    "jose": "^5.0.0",
+    "lru-cache": "^11.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}