jose

"JSON Web Almost Everything" - JWA, JWS, JWE, JWT, JWK, JWKS for Node.js, B...

Authentication / Authorization
panva/josejose

README

jose


"JSON Web Almost Everything" - JWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes.


Implemented specs & features


The following specifications are implemented by jose

- JSON Web Signature (JWS) - [RFC7515][spec-jws]
- JSON Web Encryption (JWE) - [RFC7516][spec-jwe]
- JSON Web Key (JWK) - [RFC7517][spec-jwk]
- JSON Web Algorithms (JWA) - [RFC7518][spec-jwa]
- JSON Web Token (JWT) - [RFC7519][spec-jwt]
- JSON Web Key Thumbprint - [RFC7638][spec-thumbprint]
- JSON Web Key Thumbprint URI - [RFC9278][spec-thumbprint-uri]
- JWS Unencoded Payload Option - [RFC7797][spec-b64]
- CFRG Elliptic Curve ECDH and Signatures - [RFC8037][spec-okp]
- secp256k1 EC Key curve support - [JOSE Registrations for WebAuthn Algorithms][spec-secp256k1]

The test suite utilizes examples defined in [RFC7520][spec-cookbook] to confirm its JOSE
implementation is correct.

💗 Help the project


Dependencies: 0


Documentation


example ESM import
  1. ``` js
  2. import * as jose from 'jose'
  3. ```

example CJS require
  1. ``` js
  2. const jose = require('jose')
  3. ```

example Deno import
  1. ``` js
  2. import * as jose from 'https://deno.land/x/jose@v4.11.1/index.ts'
  3. ```

- JSON Web Tokens (JWT)
  - Signing
  - Verification & JWT Claims Set Validation
  - Encrypted JSON Web Tokens
    - Encryption
    - Decryption & JWT Claims Set Validation
- Key Import
  - JWK Import
  - Public Key Import (SPKI)
  - Public Key Import (X.509 Certificate)
  - Private Key Import (PKCS #8)
- JSON Web Encryption (JWE)
  - Encryption - Compact, Flattened, General
  - Decryption - Compact, Flattened, General
- JSON Web Signature (JWS)
  - Signing - Compact, Flattened, General
  - Verification - Compact, Flattened, General
- JSON Web Key (JWK)
  - Calculating JWK Thumbprint
  - Calculating JWK Thumbprint URI
  - Verification using a JWK Embedded in a JWS Header
- JSON Web Key Set (JWKS)
  - Verify using a local JWKSet
  - Verify using a remote JWKSet
- Key Pair or Secret Generation
  - Asymmetric Key Pair Generation
  - Symmetric Secret Generation
- Key Export
  - JWK Export
  - Private Key Export
  - Public Key Export
- Utilities
  - Decoding Token's Protected Header
  - Decoding JWT Claims Set
- Unsecured JWT
- JOSE Errors

Supported Runtimes


The supported JavaScript runtimes include ones that support the utilized Web API globals and standard built-in objects or are Node.js

These are _(this is not an exhaustive list)_:
- Bun
- Browsers
- Cloudflare Workers
- Deno
- Electron
- Node.js
- Vercel's Edge Runtime

FAQ


Supported Versions


VersionSecurityOtherNew
--------------------------------
[v4.x](https://github.com/panva/jose/tree/v4.x)✅✅✅
[v3.x](https://github.com/panva/jose/tree/v3.x),✅❌❌

Uint8Array?!


- Whenever Uint8Array is a valid input, so is [Buffer](https://nodejs.org/api/buffer.html#buffer_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.

[spec-b64]: https://www.rfc-editor.org/rfc/rfc7797
[spec-cookbook]: https://www.rfc-editor.org/rfc/rfc7520
[spec-jwa]: https://www.rfc-editor.org/rfc/rfc7518
[spec-jwe]: https://www.rfc-editor.org/rfc/rfc7516
[spec-jwk]: https://www.rfc-editor.org/rfc/rfc7517
[spec-jws]: https://www.rfc-editor.org/rfc/rfc7515
[spec-jwt]: https://www.rfc-editor.org/rfc/rfc7519
[spec-okp]: https://www.rfc-editor.org/rfc/rfc8037
[spec-secp256k1]: https://www.rfc-editor.org/rfc/rfc8812
[spec-thumbprint]: https://www.rfc-editor.org/rfc/rfc7638
[spec-thumbprint-uri]: https://www.rfc-editor.org/rfc/rfc9278