Universal "JSON Web Almost Everything" - JWA, JWS, JWE, JWT, JWK with no dependencies using native crypto runtimes
The following specifications are implemented by jose
The test suite utilizes examples defined in RFC7520 to confirm its JOSE implementation is correct.
If you or your business use jose
, please consider becoming a sponsor so I can continue maintaining it and adding new features carefree.
npm install [email protected]
A continuously growing list of examples is available in the tracker.
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:
Platform | supported versions | caveats |
---|---|---|
Node.js | LTS ^12.19.0 || ^14.15.0 | |
Electron |
process.version must matchthe 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
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
Version | Bug Fixes 🐞 | New Features ⭐ |
---|---|---|
3.x.x | ✅ | ✅ |
2.x.x | ✅ until 2022-04-30 | ❌ |
Yes. All module's public API is subject to Semantic Versioning 2.0.0.
jws
, jwa
or jsonwebtoken
?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.
node-forge
fallbacks when crypto runtime is unavailableUint8Array
is a valid input, so is Buffer
since buffers are instances of Uint8Array.Uint8Array
is returned and you want a Buffer
instead, use Buffer.from(uint8array)
.Yes the bundle size is on the larger side, that is because each module is actually published multiple times so that it can remain truly without dependencies and be universal / isomorphic.
Nevertheless, since each module can be required independently and is fully tree-shakeable, the install size should not be a cause for concern.
Install @types/node as your project's development dependency
npm install --save-dev @types/node
Install @types/node as your project's development dependency
npm install --save-dev @types/node
Update @types/node as your project's development dependency
npm uninstall @types/node
npm install --save-dev @types/node
There's no "jose" root module. Each module is to be individually imported as explained in each individual module's documentation.
Use a supported Node.js runtime and make sure whatever tools you may use for transpiling the code also support the Subpath exports ("exports") feature.
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