@nihplod/sso-verify 1.0.0 → 1.0.3

package/README.md

@@ -1,18 +1,20 @@
 # @nihplod/sso-verify
 
-NIHPLOD 一网通 SSO Token 验证工具包 — 供子项目在后端验证主站签发的 Access Token。
+NIHPLOD SSO token verification toolkit — for sub-projects to validate access tokens issued by the main site backend.
 
-## 安装
+## Install
 
 ```bash
 npm install @nihplod/sso-verify
 ```
 
-## 使用方式
+## Usage
 
-### 方式一：Introspection 验证（推荐）
+### Method 1: Introspection (Recommended)
 
-适用于所有子项目，无需接触签名密钥。
+Suitable for all sub-projects; no signing keys required.
+
+#### Confidential Client (server-side or BFF)
 
 ```typescript
 import { createTokenVerifier } from "@nihplod/sso-verify";
@@ -27,13 +29,30 @@ const verifier = createTokenVerifier({
 
 const payload = await verifier.verify(token);
 if (payload) {
-  console.log(payload.sub); // 用户 ID
+  console.log(payload.sub); // User ID
 }
 ```
 
-### 方式二：本地 JWT 验证（仅内部 Confidential Client）
+#### Public Client (SPA / mobile / desktop)
+
+Public Clients have no `client_secret`. The introspection endpoint still accepts verification with `client_id` only.
+
+```typescript
+import { createTokenVerifier } from "@nihplod/sso-verify";
+
+const verifier = createTokenVerifier({
+  introspectionEndpoint: "https://nihplod.cn/api/oauth/introspect",
+  clientId: "your-public-client-id",
+  audience: "your-public-client-id",
+  issuer: "https://nihplod.cn",
+});
+
+const payload = await verifier.verify(token);
+```
+
+### Method 2: Local JWT Verification (Internal Confidential Clients Only)
 
-仅当子项目与主站共享 `JWT_ACCESS_SECRET` 时使用。
+Only use this when the sub-project shares `JWT_ACCESS_SECRET` with the main site.
 
 ```typescript
 import { createTokenVerifier } from "@nihplod/sso-verify";
@@ -47,7 +66,7 @@ const verifier = createTokenVerifier({
 const payload = await verifier.verify(token);
 ```
 
-## Express / Connect 中间件
+## Express / Connect Middleware
 
 ```typescript
 import { ssoMiddleware } from "@nihplod/sso-verify";
@@ -63,10 +82,10 @@ app.use(
 );
 ```
 
-验证成功后，`req.user` 会挂载 token payload。
+After successful verification, the token payload is attached to `req.user`.
 
-## 注意事项
+## Notes
 
-- 当前主站默认使用 HS256 对称签名。对于外部子项目，推荐优先使用 **Introspection 模式** 验证 access_token。
-- 若你的子项目是内部服务且已与主站共享 RS256 公钥，可配置 `accessTokenPublicKey` 或 `jwksUri` 做本地 JWT 验证。
-- **不要将 `JWT_ACCESS_SECRET`（HS256 对称密钥）分发给外部子项目。**
+- 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.**

package/dist/index.js

@@ -80,7 +80,7 @@ function createTokenVerifier(options) {
     return _rs256PublicKey;
   }
   async function introspect(token) {
-    if (!introspectionEndpoint || !clientId || !clientSecret) {
+    if (!introspectionEndpoint || !clientId) {
       return null;
     }
     const cached = introspectCache.get(token);
@@ -88,14 +88,14 @@ function createTokenVerifier(options) {
       return { active: cached.active, ...cached.payload || {} };
     }
     try {
+      const params = new URLSearchParams({ token, client_id: clientId });
+      if (clientSecret) {
+        params.set("client_secret", clientSecret);
+      }
       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
-        })
+        body: params
       });
       if (!response.ok) return null;
       const data = await response.json();

package/dist/index.mjs

@@ -54,7 +54,7 @@ function createTokenVerifier(options) {
     return _rs256PublicKey;
   }
   async function introspect(token) {
-    if (!introspectionEndpoint || !clientId || !clientSecret) {
+    if (!introspectionEndpoint || !clientId) {
       return null;
     }
     const cached = introspectCache.get(token);
@@ -62,14 +62,14 @@ function createTokenVerifier(options) {
       return { active: cached.active, ...cached.payload || {} };
     }
     try {
+      const params = new URLSearchParams({ token, client_id: clientId });
+      if (clientSecret) {
+        params.set("client_secret", clientSecret);
+      }
       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
-        })
+        body: params
       });
       if (!response.ok) return null;
       const data = await response.json();

package/package.json

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