mm_njwt 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,152 @@
+# mm_njwt
+
+mm_njwt 是一个基于 Node.js `crypto` 模块实现的 JWT（JSON Web Token）加解密库，用于在通信中生成、签名、解析和验证 JWT。它支持 HMAC、RSA、ECDSA 等多种签名算法及 `none` 无签名模式，提供链式设置 Claims 的 `Jwt` 构建器与可配置密钥解析器的 `Verifier` 验证器，适合用于接口鉴权、令牌签发与校验等场景。
+
+## 项目信息
+
+- **当前版本**: 1.0.1
+- **更新日期**: 2026-10-04
+- **Gitee地址**: https://gitee.com/qiuwenwu91/mm_njwt
+- **依赖**:
+  - ecdsa-sig-formatter ^1.0.11（ECDSA 签名 DER/JOSE 格式转换）
+  - secure-random ^1.1.2（生成随机签名密钥）
+  - uuid ^11.1.0（生成默认 jti 声明）
+
+## 特点
+
+- 支持 HS256/384/512、RS256/384/512、ES256/384/512 及 `none` 共 10 种签名算法。
+- 链式 API 设置标准 Claims（`jti`、`sub`、`iss`、`iat`、`exp`、`nbf`）及自定义 Claims、自定义 Header 字段。
+- 创建 Token 时默认自动填充 `jti`（UUID v4）、`iat`（当前秒级时间戳），`create()` 默认 1 小时过期。
+- 验证时自动校验签名算法一致性、过期时间（exp）、生效时间（nbf）与签名正确性。
+- 支持通过 `setKeyResolver` / `withKeyResolver` 按 Header 中的 `kid` 动态解析验签密钥。
+- 核心类与原型已 `Object.freeze` 冻结，防止运行时被篡改（对应 njwt 已知漏洞 SNYK-JS-NJWT-6861582）。
+
+## 安装
+
+```bash
+npm install mm_njwt
+```
+
+## 基本使用
+
+```javascript
+const nJwt = require('mm_njwt');
+
+// 1. 创建并签名 Token（默认 HS256，自动设置 1 小时过期）
+const claims = {
+  iss: 'http://myapp.com/',   // 签发者
+  sub: 'users/user1234',      // 用户标识
+  scope: 'self, admins'
+};
+const jwt = nJwt.create(claims, 'my-secret-key');
+const token = jwt.compact();  // 得到 xxx.yyy.zzz 形式的 JWT 字符串
+
+// 2. 验证 Token
+nJwt.verify(token, 'my-secret-key', (err, verifiedJwt) => {
+  if (err) {
+    console.error('验证失败:', err.userMessage || err.message);
+  } else {
+    console.log('验证通过:', verifiedJwt.body);
+  }
+});
+```
+
+## API 说明
+
+### 顶层函数
+
+| 方法 | 签名 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| create | `create(claims, secret, [alg])` | `Jwt` 实例 | 快速创建 Token。`claims` 为声明对象；`secret` 为签名密钥（`alg` 为 `'none'` 时可省略）；`alg` 默认 `'HS256'`。自动设置 1 小时过期。若传入单个字符串参数，则视为密钥并创建空 Claims 的 Token |
+| verify | `verify(jwtTokenString, [signingKey], [algOverride], [callback])` | 无回调时返回 `Jwt`，失败抛异常 | 便捷验证函数。内部创建 `Verifier`：传 2 参时按默认 HS256 验证；传 3 参时可覆盖签名算法；仅 1 参时按 `none` 验证 |
+| createVerifier | `createVerifier()` | `Verifier` 实例 | 创建一个验证器实例 |
+| base64urlEncode | `base64urlEncode(data)` | `String` | 将字符串（或数字）编码为 base64url 格式 |
+| base64urlUnescape | `base64urlUnescape(str)` | `String` | 将 base64url 字符串还原为标准 base64（补齐 `=` 并替换 `-`、`_`） |
+
+### Jwt 类
+
+构造函数：`new nJwt.Jwt(claims, [enforceDefaultFields])`。`claims` 为声明对象；`enforceDefaultFields` 默认为 `true`，会自动补全 `typ=JWT`、`alg=none`、`jti`、`iat`，传 `false` 则不补全。实例属性 `header`（JwtHeader）与 `body`（JwtBody）可直接读取。
+
+| 方法 | 签名 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| setClaim | `setClaim(claim, value)` | `this` | 设置任意自定义 Claim |
+| setHeader | `setHeader(param, value)` | `this` | 设置 Header 自定义字段（如 `kid`） |
+| setJti | `setJti(jti)` | `this` | 设置 Token 唯一标识 `jti` |
+| setSubject | `setSubject(sub)` | `this` | 设置主题 `sub` |
+| setIssuer | `setIssuer(iss)` | `this` | 设置签发者 `iss` |
+| setIssuedAt | `setIssuedAt(iat)` | `this` | 设置签发时间（秒级时间戳） |
+| setExpiration | `setExpiration(exp)` | `this` | 设置过期时间，接受 `Date` 或可被 `new Date()` 解析的值；传假值则删除 `exp` |
+| setNotBefore | `setNotBefore(nbf)` | `this` | 设置生效时间，用法同 `setExpiration`；传假值则删除 `nbf` |
+| setSigningKey | `setSigningKey(key)` | `this` | 设置签名密钥 |
+| setSigningAlgorithm | `setSigningAlgorithm(alg)` | `this` | 设置签名算法，不支持的算法抛 `JwtError` |
+| compact | `compact()` | `String` | 生成并返回完整 JWT 字符串。算法非 `none` 且未设置密钥时抛异常 |
+| toString | `toString()` | `String` | 等价于 `compact()` |
+| isExpired | `isExpired()` | `Boolean` | 是否已过期（依据 `exp`） |
+| isNotBefore | `isNotBefore()` | `Boolean` | 是否尚未生效（依据 `nbf`） |
+| sign | `sign(payload, algorithm, cryptoInput)` | `String` | 底层签名方法：对 `payload` 用 `algorithm` 和密钥 `cryptoInput` 签名，ECDSA 结果自动转为 JOSE 格式 |
+| isSupportedAlg | `isSupportedAlg(alg)` | `Boolean` | 判断算法是否受支持 |
+
+### Verifier 类
+
+构造函数：`new nJwt.Verifier()`（或 `nJwt.createVerifier()`）。默认算法 `HS256`，默认密钥解析器返回自身 `signingKey`。
+
+| 方法 | 签名 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| setSigningAlgorithm | `setSigningAlgorithm(alg)` | `this` | 指定期望的签名算法，与 Token Header 中 `alg` 不一致时验证失败 |
+| setSigningKey | `setSigningKey(keyStr)` | `this` | 设置验签密钥 |
+| setKeyResolver | `setKeyResolver(resolver)` | `undefined` | 设置密钥解析器，签名为 `resolver(kid, cb)`，通过 `cb(err, key)` 返回密钥 |
+| withKeyResolver | `withKeyResolver(resolver)` | `this` | 链式设置密钥解析器 |
+| verify | `verify(jwtString, [callback])` | 无回调时返回 `Jwt` | 验证 JWT 字符串：依次校验算法一致性、`exp`、`nbf`、签名。失败时通过回调返回 `JwtParseError`（含 `userMessage`、`jwtString`、`parsedHeader`、`parsedBody`），无回调则抛异常；成功后回调 `(null, jwt)` |
+
+### JwtBody / JwtHeader
+
+| 类 | 构造 | 方法 | 说明 |
+| --- | --- | --- | --- |
+| JwtBody | `new nJwt.JwtBody(claims)` | `toJSON()` 返回普通对象；`compact()` 返回 base64url 编码的 JSON 字符串 | JWT 载荷部分 |
+| JwtHeader | `new nJwt.JwtHeader(header, [enforceDefaultFields])` | `compact()` 返回 base64url 编码的 JSON 字符串 | JWT 头部部分，保留字段为 `typ`、`alg` |
+
+## 使用示例
+
+### 场景一：完整控制 Claims 与 Header
+
+```javascript
+const nJwt = require('mm_njwt');
+
+const jwt = new nJwt.Jwt({ uid: 1001 });
+jwt.setIssuer('http://myapp.com/')
+   .setSubject('users/1001')
+   .setExpiration(new Date(Date.now() + 2 * 3600 * 1000)) // 2 小时后过期
+   .setHeader('kid', 'key-2026')
+   .setSigningAlgorithm('HS512')
+   .setSigningKey('strong-secret');
+
+const token = jwt.compact();
+```
+
+### 场景二：按 kid 动态解析密钥验证
+
+```javascript
+const nJwt = require('mm_njwt');
+
+const verifier = nJwt.createVerifier().withKeyResolver((kid, cb) => {
+  // 根据 header 中的 kid 查找对应密钥
+  const key = kid === 'key-2026' ? 'strong-secret' : null;
+  cb(key ? null : new Error('key not found'), key);
+});
+verifier.setSigningAlgorithm('HS512');
+
+verifier.verify(token, (err, jwt) => {
+  if (!err) console.log(jwt.body); // { uid: 1001, iss: ..., exp: ... }
+});
+```
+
+### 场景三：使用随机密钥（配合 secure-random）
+
+```javascript
+const nJwt = require('mm_njwt');
+const secureRandom = require('secure-random');
+
+const signingKey = secureRandom(256, { type: 'Buffer' }); // 256 字节随机密钥
+const jwt = nJwt.create({ iss: 'http://myapp.com/', sub: 'users/user1234' }, signingKey);
+console.log(jwt.compact());
+```

package/example/index.js

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * mm_njwt JWT 签发与校验模块示例
+ * 演示：创建 JWT、签发 token，并校验签名的有效性。
+ * 运行：node example/index.js
+ */
+
+const nJwt = require('../index.js');
+
+// 签名密钥（演示用）
+const SECRET = 'my-256-bit-secret-key-0123456789abcdef';
+
+/**
+ * 主函数
+ * @returns {void} 无返回值
+ */
+function main() {
+  // 1. 创建 JWT 并签发
+  const jwt = nJwt.create(
+    { iss: 'http://myapp.com/', sub: 'users/user1234', scope: 'self, admins' },
+    SECRET
+  );
+  const token = jwt.compact();
+  console.log('签发的 JWT:', token);
+  console.log('载荷:', JSON.stringify(jwt.body.toJSON()));
+
+  // 2. 校验 JWT
+  nJwt.verify(token, SECRET, 'HS256', (err, verified) => {
+    if (err) {
+      console.error('校验失败:', err.message);
+      process.exit(1);
+    }
+    console.log('校验通过，载荷:', JSON.stringify(verified.body.toJSON()));
+  });
+}
+
+main();

package/package.json

@@ -1,33 +1,38 @@
-{
-	"name": "mm_njwt",
-	"version": "1.0.1",
-	"description": "用于加解密通讯",
-	"main": "index.js",
-	"scripts": {
-		"test": "node test.js"
-	},
-    "repository": {
-        "type": "git",
-        "url": "git+https://gitee.com/qiuwenwu91/mm_njwt.git"
-    },
-    "keywords": [
-        "wechat",
-        "public",
-        "bot",
-        "robot",
-        "encode",
-        "decode",
-        "njwt"
-    ],
-	"author": "qww",
-	"license": "ISC",
-    "bugs": {
-        "url": "https://gitee.com/qiuwenwu91/mm_njwt/issues"
-    },
-    "homepage": "https://gitee.com/qiuwenwu91/mm_njwt#readme",
-	"dependencies": {
-		"ecdsa-sig-formatter": "^1.0.11",
-		"secure-random": "^1.1.2",
-		"uuid": "^11.1.0"
-	}
-}
+{
+    "name": "mm_njwt",
+    "version": "1.0.2",
+    "description": "用于加解密通讯",
+    "main": "index.js",
+    "scripts": {
+        "test": "node test.js"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://gitee.com/qiuwenwu91/mm_njwt.git"
+    },
+    "keywords": [
+        "mm_mod",
+        "mm_infra",
+        "mm_signature",
+        "wechat",
+        "public",
+        "bot",
+        "robot",
+        "encode",
+        "decode",
+        "njwt"
+    ],
+    "layer": "crosscut",
+    "group": "signature",
+    "author": "qww",
+    "license": "ISC",
+    "bugs": {
+        "url": "https://gitee.com/qiuwenwu91/mm_njwt/issues"
+    },
+    "homepage": "https://gitee.com/qiuwenwu91/mm_njwt#readme",
+    "dependencies": {
+        "ecdsa-sig-formatter": "^1.0.11",
+        "secure-random": "^1.1.2",
+        "uuid": "^11.1.0"
+    }
+}

package/test.js

@@ -1,13 +1,13 @@
-var nJwt = require('./index.js');
-var secureRandom = require('secure-random');
-
-var signingKey = secureRandom(256, {type: 'Buffer'}); // Create a highly random byte array of 256 bytes
-
-var claims = {
-  iss: "http://myapp.com/",  // The URL of your service
-  sub: "users/user1234",    // The UID of the user in your system
-  scope: "self, admins"
-}
-
+var nJwt = require('./index.js');
+var secureRandom = require('secure-random');
+
+var signingKey = secureRandom(256, {type: 'Buffer'}); // Create a highly random byte array of 256 bytes
+
+var claims = {
+  iss: "http://myapp.com/",  // The URL of your service
+  sub: "users/user1234",    // The UID of the user in your system
+  scope: "self, admins"
+}
+
 var jwt = nJwt.create(claims,signingKey);
 console.log(jwt);