jose
Advanced tools
JSON Web Almost Everything - JWA, JWS, JWE, JWK, JWT, JWKS for Node.js with minimal dependencies
Package description
The 'jose' npm package is a JavaScript library that provides a variety of cryptographic operations based on JSON Web Tokens (JWT), JSON Web Encryption (JWE), JSON Web Signature (JWS), and JSON Web Key (JWK). It is designed to be compliant with the JOSE (JSON Object Signing and Encryption) suite of standards, and it supports various algorithms for encryption, decryption, signing, and verification of tokens.
JWT Signing
This code sample demonstrates how to create and sign a JWT with a specified algorithm and secret.
const { SignJWT } = require('jose');
const jwt = await new SignJWT({ 'urn:example:claim': true })
.setProtectedHeader({ alg: 'HS256' })
.setIssuedAt()
.setIssuer('urn:example:issuer')
.setAudience('urn:example:audience')
.setExpirationTime('2h')
.sign(new TextEncoder().encode('your-256-bit-secret'));
console.log(jwt);JWT Verification
This code sample shows how to verify a JWT using a secret key and retrieve the payload and protected header.
const { jwtVerify } = require('jose');
const { payload, protectedHeader } = await jwtVerify(jwt, new TextEncoder().encode('your-256-bit-secret'));
console.log(payload);
console.log(protectedHeader);JWE Encryption
This code sample illustrates how to encrypt a JWT using RSA-OAEP-256 for key management and A256GCM for content encryption.
const { EncryptJWT } = require('jose');
const jwe = await new EncryptJWT({ 'urn:example:claim': true })
.setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM' })
.setIssuedAt()
.setIssuer('urn:example:issuer')
.setAudience('urn:example:audience')
.setExpirationTime('2h')
.encrypt(publicKey);
console.log(jwe);JWE Decryption
This code sample demonstrates how to decrypt a JWE and obtain the payload and protected header using a private key.
const { jwtDecrypt } = require('jose');
const { payload, protectedHeader } = await jwtDecrypt(jwe, privateKey);
console.log(payload);
console.log(protectedHeader);JWK Key Generation
This code sample shows how to generate a public and private key pair for the RS256 algorithm.
const { generateKeyPair } = require('jose');
const { publicKey, privateKey } = await generateKeyPair('RS256');
console.log(publicKey);
console.log(privateKey);The 'jsonwebtoken' package is similar to 'jose' in that it provides functionality for creating and verifying JWTs. It is widely used and has a simpler API for basic JWT operations, but it does not support JWE or more advanced JOSE features.
The 'node-jose' package is another alternative that implements the JOSE suite of standards. It offers similar functionalities to 'jose' but has a different API design and may have different performance characteristics.
The 'jws' package is focused on JSON Web Signatures (JWS). It is a simpler library that allows signing and verifying messages but does not handle JWTs, JWEs, or JWKs directly.
Changelog
Readme
"JSON Web Almost Everything" - JWA, JWS, JWE, JWT, JWK, JWKS for Node.js with minimal dependencies
The following specifications are implemented by jose
The test suite utilizes examples defined in RFC7520 to confirm its JOSE implementation is correct.
Available JWT validation profiles
id_token) - OpenID Connect Core 1.0at+JWT) - JWT Profile for OAuth 2.0 Access Tokenslogout_token) - OpenID Connect Back-Channel Logout 1.0Legend:
| JWK Key Types | Supported | kty |
|---|---|---|
| RSA | ✓ | RSA |
| Elliptic Curve | ✓ | EC (P-256, secp256k1, P-384, P-521) |
| Octet Key Pair | ✓ | OKP (Ed25519, Ed448, X25519, X448) |
| Octet sequence | ✓ | oct |
| Serialization | JWS Sign | JWS Verify | JWE Encrypt | JWE Decrypt |
|---|---|---|---|---|
| Compact | ✓ | ✓ | ✓ | ✓ |
| General JSON | ✓ | ✓ | ✓ | ✓ |
| Flattened JSON | ✓ | ✓ | ✓ | ✓ |
| JWS Algorithms | Supported | |
|---|---|---|
| RSASSA-PKCS1-v1_5 | ✓ | RS256, RS384, RS512 |
| RSASSA-PSS | ✓ | PS256, PS384, PS512 |
| ECDSA | ✓ | ES256, ES256K, ES384, ES512 |
| Edwards-curve DSA | ✓ | EdDSA |
| HMAC with SHA-2 | ✓ | HS256, HS384, HS512 |
| JWE Key Management Algorithms | Supported | |
|---|---|---|
| AES | ✓ | A128KW, A192KW, A256KW |
| AES GCM | ✓ | A128GCMKW, A192GCMKW, A256GCMKW |
| Direct Key Agreement | ✓ | dir |
| RSAES OAEP | ✓ | RSA-OAEP, RSA-OAEP-256 |
| RSAES-PKCS1-v1_5 | ✓ | RSA1_5 |
| PBES2 | ✓ | PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW |
| ECDH-ES (for all EC keys) | ✓ | ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW |
| ECDH-ES (for OKP X25519) | ✓ via plugin | ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW |
| ECDH-ES (for OKP X448) | ✕ | |
| (X)ChaCha | ✓ via plugin | C20PKW, X20CPKW, ECDH-ES+C20PKW, ECDH-ES+XC20PKW |
| JWE Content Encryption Algorithms | Supported | |
|---|---|---|
| AES GCM | ✓ | A128GCM, A192GCM, A256GCM |
| AES_CBC_HMAC_SHA2 | ✓ | A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 |
| (X)ChaCha | ✓ via plugin | C20P, X20CP |
| JWT profile validation | Supported | profile option value |
|---|---|---|
| ID Token - OpenID Connect Core 1.0 | ✓ | id_token |
| JWT Access Tokens JWT Profile for OAuth 2.0 Access Tokens | ✓ | at+JWT |
| Logout Token - OpenID Connect Back-Channel Logout 1.0 | ✓ | logout_token |
| JARM - JWT Secured Authorization Response Mode for OAuth 2.0 | ◯ |
Notes
x5c is only supported when Node.js >= 12.0.0 runtime is detectedPending Node.js Support 🤞:
Won't implement:
x5c, jwk) to JWK.asKey and validate with that
key, similarly the application can handle fetching and then instantiating the referenced x5u
or jku in its own code. This way you opt-in to these behaviours.Have a question about using jose? - ask.
Found a bug? - report it.
Missing a feature? - If it wasn't already discussed before, ask for it.
Found a vulnerability? - Reach out to us via email first, see security vulnerability disclosure.
If you or your business use jose, please consider becoming a sponsor so I can continue maintaining it and adding new features carefree.
There are two plugin extensions with functionality which is either not available in Node.js crypto
module yet and therefore needs a crypto polyfill (libsodium), or are not IETF WG standards/drafts
"worthy" of landing in the core library.
crypto support)For the best performance Node.js version >=12.0.0 is recommended, but ^10.13.0 lts/dubnium is also supported.
Installing jose
npm install jose
Usage
const jose = require('jose')
const {
JWE, // JSON Web Encryption (JWE)
JWK, // JSON Web Key (JWK)
JWKS, // JSON Web Key Set (JWKS)
JWS, // JSON Web Signature (JWS)
JWT, // JSON Web Token (JWT)
errors // errors utilized by jose
} = jose
Prepare your Keys and KeyStores. See the documentation for more.
const key = jose.JWK.asKey(fs.readFileSync('path/to/key/file'))
const jwk = { kty: 'EC',
kid: 'dl4M_fcI7XoFCsQ22PYrQBkuxZ2pDcbDimcdFmmXM98',
crv: 'P-256',
x: 'v37avifcL-xgh8cy6IFzcINqqmFLc2JF20XUpn4Y2uQ',
y: 'QTwy27XgP7ZMOdGOSopAHB-FU1JMQn3J9GEWGtUXreQ' }
const anotherKey = jose.JWK.asKey(jwk)
const keystore = new jose.JWKS.KeyStore(key, anotherKey)
The JWT module provides IANA registered claim type and format validations on top of JWS as well as convenience options for verifying UNIX timestamps, setting maximum allowed JWT age, verifying audiences, and more.
The JWS module on the other hand handles the other JWS Serialization Syntaxes with all their additional available features and allows signing of any payload, i.e. not just serialized JSON objects.
Sign with a private or symmetric key with plethora of convenience options. See the documentation for more.
jose.JWT.sign(
{ 'urn:example:claim': 'foo' },
privateKey,
{
algorithm: 'PS256',
audience: 'urn:example:client_id',
expiresIn: '1 hour',
header: {
typ: 'JWT'
},
issuer: 'https://op.example.com'
}
)
Verify with a public or symmetric key with plethora of convenience options. See the documentation for more.
jose.JWT.verify(
'eyJ0eXAiOiJKV1QiLCJhbGciOiJQUzI1NiIsImtpZCI6IjRQQXBsVkJIN0toS1ZqN0xob0RFM0VVQnNGc0hvaTRhSmxBZGstM3JuME0ifQ.eyJ1cm46ZXhhbXBsZTpjbGFpbSI6ImZvbyIsImF1ZCI6InVybjpleGFtcGxlOmNsaWVudF9pZCIsImlzcyI6Imh0dHBzOi8vb3AuZXhhbXBsZS5jb20iLCJpYXQiOjE1NTEyOTI2MjksImV4cCI6MTU1MTI5NjIyOX0.nE5fgRL8gvlStf_wB4mJ0TSXVmhJRnUVQuZ0ts6a1nWnnk0Rv69bEJ12BoMdpyPrGa_W6dxU4HFj89F4pQwW0kqBK2-TZ_n9lq-iqupj46w_lpKOfPC3clVc7ZmqYF81bEA-nX93cSKqVV-qPNPEFenb8XHKszYhBFu_uiRg9rXj2qXVU7PXGJAGTzhVgVxB-3XDB1bQ_6KiDCwzVPftrHxEYLydRCaHzggDg6sAFUhQqhPguKuE2gs6jVUh_gIL2RXeoLoinx6gZ72rfovaOmud-yzNIUN8Tvo0pqBmx0s_lEhTlfrQCzN7hZNmV1eG0GDDE-S_CfZhPePnVJZoRA',
publicKey,
{
issuer: 'https://op.example.com',
audience: 'urn:example:client_id',
algorithms: ['PS256']
}
)
ID Token is a JWT, but profiled, there are additional requirements to a JWT to be accepted as an
ID Token and it is pretty easy to omit some, use the profile option of JWT.verify to make sure
what you're accepting is really an ID Token meant to your Client. This will then perform all
doable validations given the input. See the documentation for more.
jose.JWT.verify(
'eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InIxTGtiQm8zOTI1UmIyWkZGckt5VTNNVmV4OVQyODE3S3gwdmJpNmlfS2MifQ.eyJzdWIiOiJmb28iLCJub25jZSI6ImE1MWNjZjA4ZjRiYmIwNmU4ODcxNWRkYzRiYmI0MWQ4IiwiYXVkIjoidXJuOmV4YW1wbGU6Y2xpZW50X2lkIiwiZXhwIjoxNTYzODg4ODMwLCJpYXQiOjE1NjM4ODUyMzAsImlzcyI6Imh0dHBzOi8vb3AuZXhhbXBsZS5jb20ifQ.RKCZczgICF5G9XdNDSwe4dolGauQHptpFKPzahA2wYGG2HKrKhyC8ZzqpeVc8cbntuqFBgABJVv6_9YICRx_dgwPYydTpZfZYjHnxrdWF9QsIPEGs672mrnhqIXUnXoseZ0TF6GOq6P7Qbf6gk1ru7TAbr_ieyJnNWcJhh5iHpz1k3mFz0TyTh7UNXshtQXftPUipqz4OBni5r9UaZXHw8B3QYOnms8__GJ3owOxaqkr1jgRs_EWqMlBNjPaj7ElVaeBWljDKuoK673tH0heSpgzUmUX_W8IDUVqs33uglpZwAQC7cAA5mGEg2odcRpvpP5M-WaP4RE9dl9jzcYmrw',
keystore,
{
profile: 'id_token',
issuer: 'https://op.example.com',
audience: 'urn:example:client_id',
nonce: 'a51ccf08f4bbb06e88715ddc4bbb41d8',
algorithms: ['PS256']
}
)
Note: Depending on the channel you receive an ID Token from the following claims may be required
and must also be checked: at_hash, c_hash or s_hash. Use e.g. oidc-token-hash
to validate those hashes after getting the ID Token payload and signature validated by jose
When accepting a JWT-formatted OAuth 2.0 Access Token there are additional requirements for the JWT
to be accepted as an Access Token according to the specification
and it is pretty easy to omit some. Use the profile option of JWT.verify to make sure
what you're accepting is really a JWT Access Token meant for your Resource Server. This will then
perform all doable validations given the input. See the documentation for more.
jose.JWT.verify(
'eyJhbGciOiJQUzI1NiIsInR5cCI6ImF0K0pXVCIsImtpZCI6InIxTGtiQm8zOTI1UmIyWkZGckt5VTNNVmV4OVQyODE3S3gwdmJpNmlfS2MifQ.eyJzdWIiOiJmb28iLCJjbGllbnRfaWQiOiJ1cm46ZXhhbXBsZTpjbGllbnRfaWQiLCJhdWQiOiJ1cm46ZXhhbXBsZTpyZXNvdXJjZS1zZXJ2ZXIiLCJleHAiOjE1NjM4ODg4MzAsImlzcyI6Imh0dHBzOi8vb3AuZXhhbXBsZS5jb20iLCJzY29wZSI6ImFwaTpyZWFkIn0.UYy8vEGWS0cS24giCYobMMy9-bqI45p807yV1l-2WXX2J4UO-eohV_R58LE2oM88gl414c6XydO6QSYXul5roNPoOs41jpEvreQIP-HmegjbWGutktWJKfvoOblE5FjYwjrwStjLQGUzkq6KWcnDLPGmpFy7n6gZ4LF8YVz4dLEaO335hMNVNrmSPSXYqr7bAWybnLVpLxjDYwNfCO1g0_TlFx8fHh2OftHoOOmJFltFwb8JypkSB-JXVVSEh43IOEjeeMJIG_ylWIOxfLLi5Q7vPWgub83ZTkuGNe4KmlQJKIsH5k0yZSshsLYUOOH0RiXqQ-SA4Ubh3Fowigdu-g',
keystore,
{
profile: 'at+JWT',
issuer: 'https://op.example.com',
audience: 'urn:example:resource-server',
algorithms: ['PS256']
}
)
Logout Token is a JWT, but profiled, there are additional requirements to a JWT to be accepted as an
Logout Token and it is pretty easy to omit some, use the profile option of JWT.verify to make sure
what you're accepting is really an Logout Token meant to your Client. This will then perform all
doable validations given the input. See the documentation for more.
jose.JWT.verify(
'eyJhbGciOiJQUzI1NiJ9.eyJzdWIiOiJmb28iLCJhdWQiOiJ1cm46ZXhhbXBsZTpjbGllbnRfaWQiLCJpYXQiOjE1NjM4ODg4MzAsImp0aSI6ImhqazMyN2RzYSIsImlzcyI6Imh0dHBzOi8vb3AuZXhhbXBsZS5jb20iLCJldmVudHMiOnsiaHR0cDovL3NjaGVtYXMub3BlbmlkLm5ldC9ldmVudC9iYWNrY2hhbm5lbC1sb2dvdXQiOnt9fX0.SBi7uNUvjHL9TFoFzautGgTQ1MjyeGUNYHL7inpgq3XgTv6xc9EAKuPRtpixmhdNhmInGwUvAeqDSJxomwv1KK1cTndrC9zAMZ7h657BGQAwGhu7nTm41fWMpKQdiLa9sqp3yit5_FNBmqUNeOoMPrYT_Vl9ytsoNO89MUQy2aqCd-Z7BrNJZH0QycdW6dmYlrmZL7w3t3TaAXoJDJ4Hgl2Itkkkb6_6gO-VoPIdVD8sDuf1zQzGhIkmcFrk0fXczVYOkeF2hNYBuvsM8LuO-EPA3oyE2In9djai3M7yceTQetRa1vwlqWkg_xmYS59ry-6wT44aN7-Y6p0TdXm-Zg',
keystore,
{
profile: 'logout_token',
issuer: 'https://op.example.com',
audience: 'urn:example:client_id',
algorithms: ['PS256']
}
)
Sign with a private or symmetric key using compact serialization. See the documentation for more.
jose.JWS.sign(
{ sub: 'johndoe' },
privateKey,
{ kid: privateKey.kid }
)
Verify with a public or symmetric key. See the documentation for more.
jose.JWS.verify(
'eyJhbGciOiJFUzI1NiJ9.eyJzdWIiOiJqb2huZG9lIn0.T_SYLQV3A5_kFDDVNuoadoURSEtuSOR-dG2CMmrP-ULK9xbIf2vYeiHOkvTrnqGlWEGBGxYtsP1VkXmNsi1uOw',
publicKey
)
Encrypt using the recipient's public key or a shared symmetrical secret. See the documentation for more.
jose.JWE.encrypt(
'eyJhbGciOiJFUzI1NiJ9.eyJzdWIiOiJqb2huZG9lIn0.T_SYLQV3A5_kFDDVNuoadoURSEtuSOR-dG2CMmrP-ULK9xbIf2vYeiHOkvTrnqGlWEGBGxYtsP1VkXmNsi1uOw',
publicKey,
{ kid: publicKey.kid }
)
Decrypt using the private key or a shared symmetrical secret. See the documentation for more.
jose.JWE.decrypt(
'eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiRUNESC1FUyIsImVwayI6eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6IkVsUGhsN1ljTVZsWkhHM0daSkRoOVJhemNYYlN2VFNheUF6aTBINFFtRUEiLCJ5IjoiM0hDREJTRy12emd6cGtLWmJqMU05UzVuUEJrTDBBdFM4U29ORUxMWE1SayJ9fQ..FhmidRo0twvFA7jcfKFNJw.o112vgiG_qUL1JR5WHpsErcxxgaK_FAa7vCWJ--WulndLpdwdRXHd9k3aL_k8K67xoAThrt10d7dSY2TlPpHdYkw979u0V-C4TNrpzNkv5jpBjU6hHyKpoGZfEsiTD1ivHaFy3ZLCTS69kN_eVKsZGLVf_dkq6Sz6bWE4-ln_fuwukPyMvjTyaTreLjPLBZW.ocKwptCm4Zn437L5hWFnHg',
privateKey
)
Electron >=6.0.0 runtime is supported to the extent of the crypto engine BoringSSL feature parity with standard Node.js OpenSSL. The following is disabled in Electron runtime because of its lack of support.
A128KW, A192KW and A256KW algorithms are not available, this also means that other JWAs
depending on those are not working, those are ECDH-ES+A128KW, ECDH-ES+A192KW,
ECDH-ES+A256KW, PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW)Ed448, X25519 and X448 are not supportedsecp256k1 is not supportedYes. Everything that's either exported in the TypeScript definitions file or documented is subject to Semantic Versioning 2.0.0. The rest is to be considered private API and is subject to change between any versions.
It is only built for >=10.13.0 Node.js environment - including jose in transpiled
browser-environment targeted projects is not supported and may result in unexpected results.
jws, jwa or jsonwebtoken?node-josenode-jose is built to work in any javascript runtime, to be able to do that it packs a lot of
backfill and javascript implementation code in the form of
node-forge, this significantly increases the footprint
of the module with dependencies that either aren't ever used or have native implementation available
in Node.js already, those are often times faster and more reliable.
crypto the direct
dependency count will go down from 1 to 0. 🚀I was using node-jose for
openid-client and
oidc-provider and came to realize its shortcomings
in terms of performance and API (not having well defined errors).
+ this was an amazing opportunity to learn JOSE as a whole
FAQs
JWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes
The npm package jose receives a total of 8,372,294 weekly downloads. As such, jose popularity was classified as popular.
We found that jose demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Learn how Socket's 'Non-Existent Author' alert helps safeguard your dependencies by identifying npm packages published by deleted accounts. This is one of the fastest ways to determine if a package may be abandoned.
Security News
In July, the Python Software Foundation mounted a quick response to address a leaked GitHub token, elected new board members, and added more members to the team supporting PSF and PyPI infrastructure.
Security News
Emerging ransomware groups drive a surge in activity in early 2024, with increasing software supply chain attacks predicted to impact critical industries reliant on third-party software.