jose

joseis JavaScript module for JSON Object Signing and Encryption, providing support for JSON Web Tokens (JWT), JSON Web Signature (JWS), JSON Web Encryption (JWE), JSON Web Key (JWK), JSON Web Key Set (JWKS), and more. The module is designed to work across various Web-interoperable runtimes including Node.js, browsers, Cloudflare Workers, Deno, Bun, and others.

Sponsor

If you want to quickly add JWT authentication to JavaScript apps, feel free to check out Auth0's JavaScript SDK and free plan.Create an Auth0 account; it's free!

💗 Help the project

Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project bybecoming a sponsor.

Dependencies: 0

josehas no dependencies and it exports tree-shakeable ESM. CJS is also supported.

Documentation

joseis distributed vianpmjs,deno.land/x,cdnjs,jsdelivr,andgithub.

exampleESM import

import*asjosefrom'jose'

exampleCJS require

constjose=require('jose')

JSON Web Tokens (JWT)

Thejosemodule supports JSON Web Tokens (JWT) and provides functionality for signing and verifying tokens, as well as their JWT Claims Set validation.

• JWT Claims Set Validation & Signature Verificationusing thejwtVerifyfunction
  • Using a remote JSON Web Key Set (JWKS)
  • Using a local JSON Web Key Set (JWKS)
• Signingusing theSignJWTclass
• Utility functions
  • Decoding Token's Protected Header
  • Decoding JWT Claims Setprior to its validation

Encrypted JSON Web Tokens

Thejosemodule supports encrypted JSON Web Tokens and provides functionality for encrypting and decrypting tokens, as well as their JWT Claims Set validation.

• Decryption & JWT Claims Set Validationusing thejwtDecryptfunction
• Encryptionusing theEncryptJWTclass
• Utility functions
  • Decoding Token's Protected Header

Key Utilities

Thejosemodule supports importing, exporting, and generating keys and secrets in various formats, including PEM formats like SPKI, X.509 certificate, and PKCS #8, as well as JSON Web Key (JWK).

• Key Import Functions
  • JWK Import
  • Public Key Import (SPKI)
  • Public Key Import (X.509 Certificate)
  • Private Key Import (PKCS #8)
• Key and Secret Generation Functions
  • Asymmetric Key Pair Generation
  • Symmetric Secret Generation
• Key Export Functions
  • JWK Export
  • Private Key Export
  • Public Key Export

JSON Web Signature (JWS)

Thejosemodule supports signing and verification of JWS messages with arbitrary payloads in Compact, Flattened JSON, and General JSON serialization syntaxes.

• Signing -Compact,Flattened JSON,General JSON
• Verification -Compact,Flattened JSON,General JSON
  • Using a remote JSON Web Key Set (JWKS)
  • Using a local JSON Web Key Set (JWKS)
• Utility functions
  • Decoding Token's Protected Header

JSON Web Encryption (JWE)

Thejosemodule supports encryption and decryption of JWE messages with arbitrary plaintext in Compact, Flattened JSON, and General JSON serialization syntaxes.

• Encryption -Compact,Flattened JSON,General JSON
• Decryption -Compact,Flattened JSON,General JSON
• Utility functions
  • Decoding Token's Protected Header

Other

The following are additional features and utilities provided by thejosemodule:

• Calculating JWK Thumbprint
• Calculating JWK Thumbprint URI
• Verification using a JWK Embedded in a JWS Header
• Unsecured JWT
• JOSE Errors

Supported Runtimes

Thejosemodule is compatible with JavaScript runtimes that support the utilized Web API globals and standard built-in objects or are Node.js.

The following runtimes are supported(this is not an exhaustive list):

• Bun
• Browsers
• Cloudflare Workers
• Deno
• Electron
• Node.js
• Vercel's Edge Runtime

Please note that certain algorithms may not be available depending on the runtime used. You can find a list of available algorithms for each runtime in the specific issue links provided above.

Supported Versions

Version	Security Fixes 🔑	Other Bug Fixes 🐞	New Features ⭐
v5.x	✅	✅	✅
v4.x	✅	❌	❌
v2.x	✅	❌	❌

Specifications

Details

• JSON Web Signature (JWS) -RFC7515
• JSON Web Encryption (JWE) -RFC7516
• JSON Web Key (JWK) -RFC7517
• JSON Web Algorithms (JWA) -RFC7518
• JSON Web Token (JWT) -RFC7519
• JSON Web Key Thumbprint -RFC7638
• JSON Web Key Thumbprint URI -RFC9278
• JWS Unencoded Payload Option -RFC7797
• CFRG Elliptic Curve ECDH and Signatures -RFC8037
• secp256k1 EC Key curve support -RFC8812

The algorithm implementations injosehave been tested using test vectors from their respective specifications as well asRFC7520.