jsonwebtoken (Node.js)

Факты и проверки, на которых они основаны

Ничего из приведённого ниже не скопировано из документации. 20 октября 2026 г. проверка content/libraries/verify/jsonwebtoken/run.sh запустила jsonwebtoken (Node.js) 9.0.3 в среде Node.js 24.22.0 в образе контейнера node:24.22.0-bookworm-slim; содержимое страницы должно совпадать с выводом проверки, а у каждого факта приведены соответствующие строки вывода.

• Алгоритмы 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 байта в формате raw r‖s, как требует RFC 7518; библиотека преобразует их из DER, который выдаёт node:crypto.

  Что записала проверка

  fact jws-ecdsa-encoding = raw

• Подпись в DER внутри JWS

  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, а проверка токена RS256 ключом EC завершилась ошибкой 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

  Токен HS256, ключом HMAC для которого служит текст PEM открытого ключа, отклонён как без списка алгоритмов (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

  При подписи ES256 ключом P-384 выбрасывается "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

  По умолчанию расхождение часов не допускается: токен, срок действия которого истёк 3 секунды назад, отклонён. Чтобы учесть расхождение, задайте 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);