Skip to content
master
Go to file
Code

README.md

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

Examples

A continuously growing list of examples is available in the tracker.

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.

How is it different from jws, jwa or jsonwebtoken?

  • 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

"Module '"crypto"' has no exported member '...'"

Update @types/node as your project's development dependency

npm uninstall @types/node
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

You can’t perform that action at this time.