"JSON Web Almost Everything" - JWA, JWS, JWE, JWT, JWK, JWKS for Node.js with minimal dependencies
Implemented specs & features
The following specifications are implemented by @panva/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 Signatures (EdDSA) - RFC8037
- secp256k1 curve EC Key support - JOSE Registrations for WebAuthn Algorithms
The test suite utilizes examples defined in RFC7520 to confirm its JOSE implementation is correct.
Available JWT validation profiles
- Generic JWT
- ID Token (id_token) - OpenID Connect Core 1.0
Detailed feature matrix (Click to expand)
- ✓ Implemented
- ✕ Missing node crypto support / won't implement
- ◯ TBD
|JWK Key Types||Supported|
|Octet Key Pair||✓||OKP|
|Serialization||JWS Sign||JWS Verify||JWE Encrypt||JWE Decrypt|
|RSASSA-PKCS1-v1_5||✓||RS256, RS384, RS512|
|RSASSA-PSS||✓||PS256, PS384, PS512|
|ECDSA||✓||ES256, ES256K, ES384, ES512|
|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|
|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_HMAC_SHA2||✓||A128CBC-HS256, A192CBC-HS384, A256CBC-HS512|
|JWT profile validation||Supported||profile option value|
|ID Token - OpenID Connect Core 1.0||✓||
|JWT Access Tokens JWT Profile for OAuth 2.0 Access Tokens||◯|
|Logout Token - OpenID Connect Back-Channel Logout 1.0||◯|
|JARM - JWT Secured Authorization Response Mode for OAuth 2.0||◯|
- RSA-OAEP-256 JWE algorithm is only supported when Node.js >= 12.9.0 runtime is detected
- Importing X.509 certificates and handling
x5cis only supported when Node.js >= 12.0.0 runtime is detected
- OKP keys are only supported when Node.js >= 12.0.0 runtime is detected
- See #electron-support for electron exceptions
Pending Node.js Support 🤞:
- ECDH-ES with X25519 and X448 - see nodejs/node#26626
- ✕ JWS embedded key / referenced verification
- one can decode the header and pass the (
JWK.asKeyand validate with that key, similarly the application can handle fetching and then instantiating the referenced
jkuin its own code. This way you opt-in to these behaviours.
- one can decode the header and pass the (
- ✕ JWS detached content
- one can remove/attach the payload after/before the respective operation
- ✕ "none" alg support
- no crypto, no use
Have a question about using @panva/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 want to quickly add secure token-based authentication to Node.js projects, feel free to check Auth0’s free plan at auth0.com/overview.
If you or your business use @panva/jose, please consider becoming a sponsor so I can continue maintaining it and adding new features carefree.
- @panva/jose API Documentation
For the best performance Node.js version >=12.0.0 is recommended, but ^10.13.0 lts/dubnium is also supported.
npm install @panva/jose
const jose =constJWE // 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 @panva/jose} = jose
Keys and KeyStores
Prepare your Keys and KeyStores. See the documentation for more.
const key = joseJWKconst jwk = kty: 'EC'kid: 'dl4M_fcI7XoFCsQ22PYrQBkuxZ2pDcbDimcdFmmXM98'crv: 'P-256'x: 'v37avifcL-xgh8cy6IFzcINqqmFLc2JF20XUpn4Y2uQ'y: 'QTwy27XgP7ZMOdGOSopAHB-FU1JMQn3J9GEWGtUXreQ'const anotherKey = joseJWKconst keystore = key key2
JWT vs JWS
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.
Verify with a public or symmetric key with plethora of convenience options. See the documentation for more.
ID Token Verifying
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.
Note: Depending on the channel you receive an ID Token from the following claims may be required
and must also be checked:
s_hash. Use e.g.
to validate those hashes after getting the ID Token payload and signature validated by @panva/jose.
Sign with a private or symmetric key using compact serialization. See the documentation for more.
Verify with a public or symmetric key. See the documentation for more.
Encrypt using the recipient's public key or a shared symmetrical secret. See the documentation for more.
Decrypt using the private key or a shared symmetrical secret. See the documentation for more.
Note: the secp256k1 JOSE parameters registration and the RFC is still in a draft state. If the WG draft changes its mind about the parameter names again the new values will be propagated as a MINOR library version.
When you require
@panva/jose you can work with
secp256k1 EC keys right away, the EC JWK
used is as per the specification
const jose =let key = joseJWKkey = joseJWKkeycrv === 'secp256k1'
For legacy reasons the unregistered EC JWK
P-256K is also supported but you must
@panva/jose like so to use it:
const jose =let key = joseJWKkey = joseJWKkeycrv === 'P-256K'
Electron v6.x 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.
A256KWalgorithms are not available, this also means that other JWAs depending on those are not working, those are
- OKP curves
X448are not supported
- EC curve
secp256k1is not supported
Yes. 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.
How do I use it outside of Node.js
It is only built for ^10.13.0 || >=12.0.0 Node.js environment - including @panva/jose in transpiled browser-environment targeted projects is not supported and may result in unexpected results.
How is it different from
- it supports JWK Key Format for all four key types (oct, RSA, EC and OKP)
- it is providing Key and KeyStore abstractions
- there is JSON Web Encryption support
- it supports all JWS / JWE Serialization Syntaxes
- it supports the "crit" member validations to make sure extensions are handled correctly
- it is not only validating the signatures, it is making sure the JWE/JWS is syntactically correct, e.g. not having duplicated header parameters between protected/unprotected or per-recipient headers
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.
What is the ultimate goal?
- No dependencies, the moment JWK formatted keys are supported by node's
cryptothe direct dependency count will go down from 1 to 0. 🚀
- Just the API one needs, having used other jose modules for 3+ years I only include what's useful
Why? Just, why?
+ this was an amazing opportunity to learn JOSE as a whole