jsonwebtoken (Node.js)

事实及其依据的检查

以下内容均非抄自文档。检查脚本 content/libraries/verify/jsonwebtoken/run.sh 于2026年10月20日在容器镜像 node:24.22.0-bookworm-slim 中运行了 jsonwebtoken (Node.js) 9.0.3（运行时为 Node.js 24.22.0）；本页内容必须与它的输出一致，每条事实都列出了对应的输出行。

• JWS 算法

  HS256HS384HS512RS256RS384RS512PS256PS384PS512ES256ES384ES512

  在检查中，HS256/384/512、RS256/384/512、PS256/384/512 和 ES256/384/512 的签名与验证均成功。EdDSA、Ed25519、Ed448、ES256K 和 ML-DSA 在签名时被拒绝。

  检查记录

  fact jws-algorithms = HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512
  evidence jws-algorithms: ES256K: sign throws Error: "algorithm" must be a valid string enum value
  evidence jws-algorithms: EdDSA: sign throws Error: "algorithm" must be a valid string enum value
  evidence jws-algorithms: Ed25519: sign throws Error: "algorithm" must be a valid string enum value
  evidence jws-algorithms: Ed448: sign throws Error: "algorithm" must be a valid string enum value
  evidence jws-algorithms: ML-DSA-44: sign throws Error: "algorithm" must be a valid string enum value

• ES256 签名编码

  raw

  令牌中的 ES256 签名是 64 字节的原始 r‖s，符合 RFC 7518 的要求；该库会把 node:crypto 生成的 DER 转换成这种格式。

  检查记录

  fact jws-ecdsa-encoding = raw

• JWS 中的 DER 签名

  rejected

  ES256 签名被重新编码为 DER 的令牌会报错 "ES256" signatures must be "64" bytes, saw "72"（这个数字是 DER 数据块的长度）。

  检查记录

  fact jws-der-signature = rejected
  evidence jws-der-signature: TypeError: "ES256" signatures must be "64" bytes, saw "72"

• 算法允许列表

  from-key

  不传 algorithms 时，验证只允许与密钥相符的算法：HS256 令牌用共享密钥验证通过，ES256 令牌用 EC 公钥验证通过，而用 EC 密钥验证 RS256 令牌时报错 invalid algorithm。

  检查记录

  fact jwt-algorithm-allowlist = from-key
  evidence jwt-algorithm-allowlist: RS256 token against an EC key: JsonWebTokenError: invalid algorithm

• 未签名的令牌（alg none）

  opt-in

  只要提供了密钥，未签名的令牌就会被拒绝，报错 jwt signature is required；只有当 algorithms 包含 none 且密钥参数为空时，它才能验证通过。

  检查记录

  fact jwt-alg-none = opt-in
  evidence jwt-alg-none: with a key: JsonWebTokenError: jwt signature is required
  evidence jwt-alg-none: algorithms ["none"] and no key: verified

• 把公钥用作 HMAC 密钥

  rejected

  以公钥 PEM 文本为 HMAC 密钥的 HS256 令牌，无论不提供算法列表（invalid algorithm），还是设置 algorithms: ["HS256"]（secretOrPublicKey must be a symmetric key when using HS256），都会被拒绝。

  检查记录

  fact jwt-hmac-public-key = rejected
  evidence jwt-hmac-public-key: no list: JsonWebTokenError: invalid algorithm
  evidence jwt-hmac-public-key: algorithms ["HS256"]: JsonWebTokenError: secretOrPublicKey must be a symmetric key when using HS256

• 按 alg 检查曲线

  enforced

  用 P-384 密钥签名 ES256 时抛出 "alg" parameter "ES256" requires curve "prime256v1".——ES256、ES384 和 ES512 分别绑定 P-256、P-384 和 P-521。

  检查记录

  fact jwt-ecdsa-curve-check = enforced
  evidence jwt-ecdsa-curve-check: Error: "alg" parameter "ES256" requires curve "prime256v1".

• 默认时钟偏差

  0s

  默认没有容差：三秒前过期的令牌被拒绝。以秒为单位设置 clockTolerance，即可容许时钟漂移。

  检查记录

  fact jwt-clock-skew = 0s

• 是否要求过期时间声明

  no

  不含 exp 声明的令牌验证通过；只有当该声明存在或设置了 maxAge 时，才会检查过期时间。

  检查记录

  fact jwt-exp-required = no

用法

import { generateKeyPairSync } from "node:crypto";
import jwt from "jsonwebtoken";

const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });

const token = jwt.sign({ sub: "user-42" }, privateKey, {
  algorithm: "ES256",
  expiresIn: "10m",
  issuer: "https://auth.example.com",
  audience: "api",
});

// Pin the algorithm, issuer and audience instead of trusting the token header.
const claims = jwt.verify(token, publicKey, {
  algorithms: ["ES256"],
  issuer: "https://auth.example.com",
  audience: "api",
});

console.log("sub:", claims.sub);