jwt-ts — API
| Экспорт | Контракт |
|---|---|
sign(payload, key, options?) | Promise со строкой JWT |
verify(token, keyOrResolver, options?) | Promise с payload после проверок |
decode(token, { complete? }) | Payload либо объект header/payload/signature без проверки |
JWTService, jwtService | Класс и экземпляр с теми же методами |
SignOptions: alg по умолчанию HS256; typ и kid необязательны; iat по умолчанию включён; числовой exp — секунды от текущего времени. Переданный payload.exp сохраняется, если options.exp не является числом.
VerifyOptions: algorithms, issuer, subject, audience, jti, typ, ignoreExpiration, clockTolerance. Issuer/subject допускают строку или массив ожидаемых строк; audience — строку либо массив, для которого достаточно пересечения с aud. ClockTolerance задаётся в секундах и влияет на exp/nbf/iat. IgnoreExpiration отключает только проверку exp.
Exp и nbf не обязательны. Если присутствуют, проверяются условия now - tolerance < exp и now + tolerance >= nbf. Iat не должен быть позже now + tolerance. Iss/sub должны быть строками; если содержат двоеточие, дополнительно проверяется разбор URL. Aud допускает строку или массив строк.
getSigner(alg) и JWAFactory.getSigner(alg) возвращают sign/verify для Buffer. Экспорт jwa представляет фабрику. Алгоритмы: HS256/384/512, RS256/384/512, PS256/384/512, ES256/ES256K/ES384/ES512, EdDSA, none.
Поддержка в фабрике не является политикой безопасности приложения. Минимальная длина HMAC-ключа не обеспечивается отдельной проверкой этой реализации; выбирайте случайный ключ достаточной длины и фиксированный разрешённый алгоритм. None не подписывает сообщение.
signCompact(payload, signer) принимает object/string/Buffer; signer содержит key, protectedHeader и необязательный header. Для проверки используйте verifyCompact(token, keyOrLookup, { expectedAlg, expectedTyp, detachedPayload }). Возвращается header/payload.
signGeneral(payload, signers, { detached? }) возвращает payload/signatures. verifyGeneral(object, keyOrLookup, { expectedTyp, detachedPayload }) возвращает payload/verified. Отдельной опции expectedAlg у general verifier нет; resolver должен применять политику алгоритмов, а приложение — требовать непустой набор подписей. Ветка none не вызывает resolver, поэтому её необходимо запретить при предварительной проверке всех заголовков.
При b64:false требуется crit:[‘b64’]; compact verifier требует отдельный detachedPayload. Произвольная строка без JSON в обычном compact payload приводит к ошибке JSON-разбора после проверки подписи.
| Вызов | Назначение |
|---|---|
encryptCompact(plaintext, recipient, header?, enc?) | Строка с пятью сегментами |
decryptCompact(token, keyOrLookup) | JSON, Buffer либо строка при cty JWT |
encryptGeneral(plaintext, recipients, protectedHeader?, unprotectedHeader?, enc?) | JSON-структура для нескольких получателей |
decryptGeneral(object, keyOrLookup) | Расшифрованный JSON или Buffer |
JWEService, jweService | Класс и экземпляр с теми же операциями |
Recipient содержит alg/key, а в general-форме также header. Реализованы ветви dir, RSA-OAEP, RSA-OAEP-256, RSA1_5, A128KW, A256KW, ECDH-ES и ECDH-ES+A128KW/A256KW. Наличие ветви не означает, что все варианты принимаются каждой средой Node/OpenSSL или совместимы с любым внешним JOSE-пакетом.
Enc: A128GCM (ключ 16 байт), A256GCM (32), A128CBC-HS256 (32), A256CBC-HS512 (64). Значение по умолчанию — A256GCM. HeaderInput объединяется поверх служебного заголовка: не передавайте туда непроверенные alg/enc, которые расходятся с выбранными параметрами шифрования.
JWK и JWKS
Заголовок раздела «JWK и JWKS»JWKManager/jwkManager и одноимённые функции: jwkToKeyObject, keyObjectToJwk, jwkToPEM, pemToJwk, jwkThumbprint. Преобразование JWK в KeyObject выбирает приватный ключ при наличии d; иначе создаёт публичный. PemToJwk использует createPublicKey, поэтому не является экспортом приватного PEM в приватный JWK.
Thumbprint поддерживает RSA, EC, OKP и по умолчанию SHA-256. Симметричный oct-ключ этим методом не поддерживается.
getJwkByKid(jwks, kid?, alg?) и resolveJwkFromHeader(jwks, header) принимают { keys: [...] } либо массив JWK. Без kid/alg возвращается первый ключ. При фильтрации alg ключ без собственного alg тоже считается кандидатом. Результат может быть undefined. Уникальность, use/key_ops, доверие к издателю и ротация остаются на стороне приложения.
Заголовки
Заголовок раздела «Заголовки»HeaderValidator.validate(header, options) проверяет набор параметров, crit и typ/cty в указанном context. Самостоятельная функция validateJoseHeaders не экспортируется корнем пакета. Unknown-параметры по умолчанию игнорируются; значение reject включается явно либо внутри отдельных операций. Типы TypeScript не заменяют runtime-проверку входящего JSON.