@authing/jose NPM

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

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
JWS Unencoded Payload Option - RFC7797
CFRG Elliptic Curve ECDH and Signatures - RFC8037
secp256k1 EC Key curve support - JOSE Registrations for WebAuthn Algorithms

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

ESM module (import):

npm install jose-node-esm-runtime

CJS module (require):

npm install jose-node-cjs-runtime

npm install jose-browser-runtime

Documentation

JSON Web Tokens (JWT)
- Signing
- Verification & Claims Set Validation
- Encrypted JSON Web Tokens
  - Encryption
  - Decryption & Claims Set Validation
JSON Web Encryption (JWE)
- Encryption - Compact, Flattened
- Decryption - Compact, Flattened, General
JSON Web Signature (JWS)
- Signing - Compact, Flattened, General
- Verification - Compact, Flattened, General
JSON Web Key (JWK)
JSON Web Key Set (JWKS)
- Verify using a remote JWKSet
Key Pair or Secret Generation (Generate KeyLike)
- Asymmetric Key Pair Generation
- Symmetric Secret Generation
Utilities
- Decoding Token's Protected Header
Unsecured JWT
JOSE Errors

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	^12.0.0	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 curve
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	Security Fixes 🔑	Other Bug Fixes 🐞	New Features ⭐
3.x.x	✅	✅	✅
2.x.x	✅	✅ until 2022-04-30	❌
1.x.x	✅	❌	❌

What is new in v3.x?

Revised API
No dependencies
Browser support (using Web Cryptography API)
Promise-based API

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 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.

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