What is jose?
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.
What are jose's main functionalities?
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);
Other packages similar to jose
jsonwebtoken
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.
node-jose
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.
jws
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.
jose
Universal "JSON Web Almost Everything" - JWA, JWS, JWE, JWT, JWK with no dependencies using native crypto runtimes
Implemented specs & features
The following specifications are implemented by jose
The test suite utilizes examples defined in RFC7520 to confirm its JOSE
implementation is correct.
Support
If you or your business use jose
, please consider becoming a sponsor so I can continue maintaining it and adding new features carefree.
Install
npm install jose@3
Documentation
- JSON Web Tokens (JWT)
- JSON Web Encryption (JWE)
- JSON Web Signature (JWS)
- JSON Web Key (JWK)
- JSON Web Key Set (JWKS)
- Key Pair or Secret Generation
- Unsecured JWT
- JOSE Errors
JOSE Support Matrix
JWK Key Types | Supported | kty value | |
---|
RSA | ✓ | RSA | |
Elliptic Curve | ✓ | EC | supported curves: P-256, secp256k1, P-384, P-521 |
Octet Key Pair | ✓ | OKP | supported subtypes: Ed25519, Ed448, X25519, X448 |
Octet sequence | ✓ | oct | |
Serialization | JWS Sign | JWS Verify | JWE Encrypt | JWE Decrypt |
---|
Compact | ✓ | ✓ | ✓ | ✓ |
General JSON | ✕ | ✕ | ✕ | ✕ |
Flattened JSON | ✓ | ✓ | ✓ | ✓ |
JWT Sign | JWT Verify | JWT Encrypt | JWT Decrypt |
---|
✓ | ✓ | ✓ | ✓ |
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 |
Unsecured JWS | ✓ | none |
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, RSA-OAEP-384, RSA-OAEP-512 |
RSAES-PKCS1-v1_5 | ✓ | RSA1_5 |
PBES2 | ✓ | PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW |
ECDH-ES | ✓ | ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW |
JWE Content Encryption Algorithms | Supported | |
---|
AES GCM | ✓ | A128GCM, A192GCM, A256GCM |
AES CBC w/ HMAC | ✓ | A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 |
Legend:
- ✓ Implemented
- ✕ Not Considered
Runtime Support Matrix
Platform | supported versions | caveats |
---|
Node.js | LTS ^12.19.0 || ^14.15.0 | |
Electron | process.version must match the Node.js supported versions. So 12+ | see [1] |
Deno | ✕ | needs Web Cryptography API integration first |
React Native | ✕ | has no available and usable crypto runtime |
IE | ✕ | implements old version of the Web Cryptography API specification |
Browsers | see caniuse.com | |
--- | | |
Edge | 79+ | see [2], [4] |
Firefox | 57+ | see [2] |
Chrome | 63+ | see [2], [4] |
Safari | 11+ | see [2], [3] |
Opera | 50+ | see [2], [4] |
iOS Safari | 12+ | see [2], [3] |
1 Due to its use of BoringSSL the following is not supported in Electron
- A128KW, A192KW, A256KW, and all composite algorithms utilizing those
- secp256k1 EC curves
- Ed448, X25519, and X448 OKP Sub Types
2 RSA1_5, OKP JWK Key Type, and secp256k1 EC curve is not supported in Web Cryptography API.
3 P-521 EC curve is not supported in Safari
4 192 bit AES keys are not supported in Chromium
FAQ
Supported Versions
Version | Bug Fixes 🐞 | New Features ⭐ |
---|
3.x.x | ✅ | ✅ |
2.x.x | ✅ until 2022-04-30 | ❌ |
What is new in v3.x?
- Revised API
- No dependencies
- Browser support (using Web Cryptography API)
- Promise-based API
- experimental (non-blocking 🎉) Node.js libuv thread pool based runtime
v2.x docs?
Here.
Semver?
Yes. All module's public API is subject to Semantic Versioning 2.0.0.
- it supports browser runtime
- it supports encrypted JWTs (i.e. in JWE format)
- supports secp256k1, Ed25519, Ed448, X25519, and X448
- it supports JWK Key Format for all four key types (oct, RSA, EC and OKP)
- it is exclusively using native platform Key object representations (CryptoKey and KeyObject)
- there is JSON Web Encryption support
- it supports the flattened JWS / JWE Serialization Syntaxes
- it supports the "crit" member validations to make sure extensions are handled correctly
How is it different from node-jose
?
node-jose
is also built to work in any javascript runtime, to be able to do that it packs a lot of
polyfills and javascript implementation code in the form of
node-forge
, this significantly increases the footprint
of the modules with dependencies that either aren't ever used or have native implementation available
in the runtime already, those are often times faster and more reliable.
- it has smaller module footprints as it does not bundle unnecessary polyfills
- it does not bundle
node-forge
fallbacks when crypto runtime is unavailable - supports secp256k1, Ed25519, Ed448, X25519, and X448
Uint8Array?!
- Whenever
Uint8Array
is a valid input, so is Buffer
since buffers are instances of Uint8Array. - Whenever
Uint8Array
is returned and you want a Buffer
instead, use Buffer.from(uint8array)
.
Bundle Size, Package Size, Tree Shaking
Yes the bundle size is on the larger side, that is because each module is actually published
5 times so that it can remain truly without dependencies and be universal / isomorphic.
The source TS files are also published with inline docs so that your IDE's Intelligent code
completion works and has the exact same documentation as published.
Nevertheless, since each module can be required independently and is fully tree-shakeable, the
install size should not be a cause for concern.
Most types are "any"
Install @types/node as your project's development dependency
npm install --save-dev @types/node
"Cannot find module '...' or its corresponding type declarations."
Install @types/node as your project's development dependency
npm install --save-dev @types/node
Why? Just. Why?
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