jose (panva)

事实及其依据的检查

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

• JWS 算法

  HS256HS384HS512RS256RS384RS512PS256PS384PS512ES256ES384ES512EdDSAEd25519ML-DSA-44ML-DSA-65ML-DSA-87

  在检查中，256/384/512 位的 HS、RS、PS 和 ES，EdDSA 和 Ed25519，以及 ML-DSA-44/65/87（在 Node.js 24.22 上）的签名与验证均成功；ES256K 和 Ed448 报错 ERR_JOSE_NOT_SUPPORTED。

  检查记录

  fact jws-algorithms = HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, EdDSA, Ed25519, ML-DSA-44, ML-DSA-65, ML-DSA-87
  evidence jws-algorithms: ES256K: ERR_JOSE_NOT_SUPPORTED: Invalid or unsupported "alg" (Algorithm) value
  evidence jws-algorithms: Ed448: ERR_JOSE_NOT_SUPPORTED: Invalid or unsupported "alg" (Algorithm) value

• ES256 签名编码

  raw

  紧凑格式令牌中的 ES256 签名是 64 字节的原始 r‖s，即 RFC 7518 要求的格式。

  检查记录

  fact jws-ecdsa-encoding = raw

• JWS 中的 DER 签名

  rejected

  ES256 签名被重新编码为 DER 的令牌会报错 ERR_JWS_SIGNATURE_VERIFICATION_FAILED，与伪造签名的错误相同。

  检查记录

  fact jws-der-signature = rejected
  evidence jws-der-signature: ERR_JWS_SIGNATURE_VERIFICATION_FAILED: signature verification failed

• 算法允许列表

  from-key

  不传 algorithms 时，密钥能执行的任何算法都被允许；用 EC 密钥验证 RS256 令牌，报错 CryptoKey does not support this operation, its algorithm.name must be RSASSA-PKCS1-v1_5。

  检查记录

  fact jwt-algorithm-allowlist = from-key
  evidence jwt-algorithm-allowlist: RS256 token against an EC key: TypeError: CryptoKey does not support this operation, its algorithm.name must be RSASSA-PKCS1-v1_5

• 未签名的令牌（alg none）

  rejected

  即使 algorithms 中列出了 none，jwtVerify() 也会拒绝 alg: none；未受保护的令牌只能用 UnsecuredJWT.decode() 解码。

  检查记录

  fact jwt-alg-none = rejected
  evidence jwt-alg-none: jwtVerify: ERR_JOSE_NOT_SUPPORTED: alg none is not supported either by JOSE or your javascript runtime
  evidence jwt-alg-none: jwtVerify with algorithms ["none"]: ERR_JOSE_NOT_SUPPORTED: alg none is not supported either by JOSE or your javascript runtime
  evidence jwt-alg-none: UnsecuredJWT.decode: returned sub fact-check

• 把公钥用作 HMAC 密钥

  rejected

  以公钥 PEM 文本为密钥的 HS256 令牌，用该公钥验证时报错 CryptoKey instances must be of type "secret" for the HS256 algorithm，无论是否提供算法列表。

  检查记录

  fact jwt-hmac-public-key = rejected
  evidence jwt-hmac-public-key: no list: TypeError: CryptoKey instances must be of type "secret" for the HS256 algorithm
  evidence jwt-hmac-public-key: algorithms ["HS256"]: TypeError: CryptoKey instances must be of type "secret" for the HS256 algorithm

• 按 alg 检查曲线

  enforced

  用 P-384 密钥签名 ES256 时报错 its algorithm.namedCurve must be P-256。

  检查记录

  fact jwt-ecdsa-curve-check = enforced
  evidence jwt-ecdsa-curve-check: TypeError: CryptoKey does not support this operation, its algorithm.namedCurve must be P-256

• 默认时钟偏差

  0s

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

  检查记录

  fact jwt-clock-skew = 0s

• 是否要求过期时间声明

  no

  不含 exp 的令牌验证通过；添加 requiredClaims: ["exp"] 可将其设为必需。

  检查记录

  fact jwt-exp-required = no

• 公钥格式

  spki-pemx509jwk

  importSPKI（PEM 字符串）、importX509（PEM 证书）和 importJWK 均可正常使用；传给 importSPKI 的 DER 字节被拒绝。Node.js 的 KeyObject 实例也能被直接接受。

  检查记录

  fact public-key-formats = spki-pem, x509, jwk
  evidence public-key-formats: spki-der: TypeError: "spki" must be SPKI formatted string
  evidence public-key-formats: KeyObject from node:crypto accepted as a key: true

• 私钥格式

  pkcs8-pemjwk

  importPKCS8 接收 PKCS#8 PEM 字符串，importJWK 接收带 d 的 JWK；SEC1 EC PRIVATE KEY PEM 被拒绝，报错 "pkcs8" must be PKCS#8 formatted string。

  检查记录

  fact private-key-formats = pkcs8-pem, jwk
  evidence private-key-formats: sec1-pem: TypeError: "pkcs8" must be PKCS#8 formatted string

用法

import * as jose from "jose";

const { privateKey, publicKey } = await jose.generateKeyPair("ES256");
const jwk = { ...(await jose.exportJWK(publicKey)), kid: "2026-10", alg: "ES256" };

const token = await new jose.SignJWT({ sub: "user-42" })
  .setProtectedHeader({ alg: "ES256", kid: jwk.kid })
  .setIssuer("https://auth.example.com")
  .setAudience("api")
  .setExpirationTime("10m")
  .sign(privateKey);

// The key set picks the key by kid; createRemoteJWKSet(new URL(...)) does the same over HTTPS.
const keys = jose.createLocalJWKSet({ keys: [jwk] });
const { payload } = await jose.jwtVerify(token, keys, {
  algorithms: ["ES256"],
  issuer: "https://auth.example.com",
  audience: "api",
  requiredClaims: ["exp"],
});

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