jose

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

weekly downloads38.3M

versionv6.1.3

licenseMIT

categoryauth

akpbrowserbuncloudflarecompactdecodedecryptdenodetachedececdsaed25519eddsaedgeelectronembeddedencryptflattenedgeneraljosejson web tokenjsonwebtokenjwajwejwkjwksjwsjwt-decodejwtml-dsanetlifynextnextjsoctokppayloadpempkcs8rsasignsignaturespkivalidatevercelverifywebcryptoworkerdworkersx509

Overview

jose is a comprehensive implementation of the JSON Object Signing and Encryption (JOSE) standards for JavaScript. It provides complete support for JWT (JSON Web Tokens), JWS (JSON Web Signature), JWE (JSON Web Encryption), JWK (JSON Web Keys), and JWKS (JSON Web Key Sets) across all modern JavaScript runtimes including Node.js, browsers, Cloudflare Workers, Deno, Bun, and other Web Crypto API-compatible environments.

With over 38 million weekly downloads, jose has become the de facto standard for secure token operations in JavaScript. Unlike older libraries that rely on external dependencies or Node.js-specific crypto APIs, jose leverages the native Web Cryptography API available in all modern runtimes. This approach eliminates dependency vulnerabilities, reduces bundle size, and ensures consistent behavior across platforms. The library is fully Promise-based and supports all standard algorithms including RSA, ECDSA, EdDSA, and HMAC.

The package is actively maintained by Panva and handles the full spectrum of JOSE operations: signing and verifying tokens, encrypting and decrypting payloads, generating and importing cryptographic keys, and managing key sets. It supports advanced features like detached payloads (RFC 7797), JWE compression, and custom header processing. The library is particularly popular in authentication systems, API security implementations, and microservices architectures where secure token exchange is critical.

jose is designed for production environments where security and reliability are paramount. It's extensively cross-tested against other JOSE implementations like Nimbus-JOSE-JWT and JWCrypto to ensure interoperability. The zero-dependency architecture means fewer security audit requirements and simpler supply chain management, making it ideal for enterprise applications and security-conscious teams.

Quick Start

typescript

import { SignJWT, jwtVerify, generateKeyPair } from 'jose';

// Generate an ES256 key pair for signing
const { publicKey, privateKey } = await generateKeyPair('ES256');

// Create a JWT with custom claims
const jwt = await new SignJWT({
  userId: '12345',
  role: 'admin',
  'urn:example:claim': true
})
  .setProtectedHeader({ alg: 'ES256' })
  .setIssuer('https://api.example.com')
  .setAudience('https://app.example.com')
  .setIssuedAt()
  .setExpirationTime('2h')
  .sign(privateKey);

console.log('Generated JWT:', jwt);

// Verify and decode the JWT
const { payload, protectedHeader } = await jwtVerify(jwt, publicKey, {
  issuer: 'https://api.example.com',
  audience: 'https://app.example.com'
});

console.log('Verified payload:', payload);
console.log('Algorithm used:', protectedHeader.alg);
console.log('Token expires at:', new Date(payload.exp * 1000));

// Example with HMAC (shared secret)
import { importJWK } from 'jose';

const secret = await importJWK({
  kty: 'oct',
  k: 'your-base64url-encoded-secret-key',
  alg: 'HS256'
});

const hmacJwt = await new SignJWT({ data: 'sensitive' })
  .setProtectedHeader({ alg: 'HS256' })
  .setExpirationTime('1h')
  .sign(secret);

const verified = await jwtVerify(hmacJwt, secret);
console.log('HMAC verified:', verified.payload);

Use Cases

API Authentication: Generate and verify JWTs for securing REST and GraphQL APIs. Create access and refresh tokens with custom claims, expiration times, and issuer validation. The library handles token lifecycle management including signature verification and claim validation out of the box.

OAuth 2.0 and OpenID Connect: Implement OAuth flows and OIDC authentication in both client and server applications. Verify ID tokens from identity providers, validate token signatures using JWKS endpoints, and handle encrypted tokens for sensitive data transmission.

Microservices Security: Enable secure service-to-service communication using signed or encrypted JWTs. Services can verify tokens without network calls by using shared public keys or JWKS, reducing latency and eliminating single points of failure in distributed systems.

Edge Computing: Deploy authentication logic to edge runtimes like Cloudflare Workers, Vercel Edge Functions, or Netlify Edge where traditional Node.js crypto APIs aren't available. The Web Crypto API support ensures consistent behavior across these constrained environments.

Sensitive Data Encryption: Use JWE to encrypt sensitive payloads before transmission or storage. Common in healthcare applications (protecting PHI), financial services (securing transaction data), and any scenario requiring end-to-end encryption with structured, verifiable metadata in headers.

Pros & Cons

Pros

+Zero external dependencies eliminates supply chain vulnerabilities and simplifies security audits
+Native Web Crypto API support ensures compatibility across Node.js, browsers, Deno, Bun, and edge runtimes without polyfills
+Complete JOSE standard implementation including JWE encryption, JWKS management, and advanced features like detached payloads
+Actively maintained with frequent security updates and strong interoperability testing against other JOSE implementations
+Small bundle size with tree-shakeable exports and runtime-specific builds for optimal performance

Cons

−Async-only API requires Promise handling for all operations, which can be verbose for simple synchronous use cases
−Steeper learning curve than JWT-only libraries due to comprehensive feature set and JOSE standard complexity
−No built-in token storage or session management—handles cryptographic operations only, requiring additional infrastructure for complete auth systems

Alternatives

jsonwebtokenv9.0.3

JSON Web Token implementation (symmetric and asymmetric)

authjwt

31.4M / week

Comparisons

jsonwebtoken vs jose

auth

Install

bash

npm install jose

bash

pnpm add jose

bash

bun add jose

Overview

Quick Start

typescript

import { SignJWT, jwtVerify, generateKeyPair } from 'jose';

// Generate an ES256 key pair for signing
const { publicKey, privateKey } = await generateKeyPair('ES256');

// Create a JWT with custom claims
const jwt = await new SignJWT({
  userId: '12345',
  role: 'admin',
  'urn:example:claim': true
})
  .setProtectedHeader({ alg: 'ES256' })
  .setIssuer('https://api.example.com')
  .setAudience('https://app.example.com')
  .setIssuedAt()
  .setExpirationTime('2h')
  .sign(privateKey);

console.log('Generated JWT:', jwt);

// Verify and decode the JWT
const { payload, protectedHeader } = await jwtVerify(jwt, publicKey, {
  issuer: 'https://api.example.com',
  audience: 'https://app.example.com'
});

console.log('Verified payload:', payload);
console.log('Algorithm used:', protectedHeader.alg);
console.log('Token expires at:', new Date(payload.exp * 1000));

// Example with HMAC (shared secret)
import { importJWK } from 'jose';

const secret = await importJWK({
  kty: 'oct',
  k: 'your-base64url-encoded-secret-key',
  alg: 'HS256'
});

const hmacJwt = await new SignJWT({ data: 'sensitive' })
  .setProtectedHeader({ alg: 'HS256' })
  .setExpirationTime('1h')
  .sign(secret);

const verified = await jwtVerify(hmacJwt, secret);
console.log('HMAC verified:', verified.payload);

Use Cases

Pros & Cons

Pros

+Zero external dependencies eliminates supply chain vulnerabilities and simplifies security audits
+Native Web Crypto API support ensures compatibility across Node.js, browsers, Deno, Bun, and edge runtimes without polyfills
+Complete JOSE standard implementation including JWE encryption, JWKS management, and advanced features like detached payloads
+Actively maintained with frequent security updates and strong interoperability testing against other JOSE implementations
+Small bundle size with tree-shakeable exports and runtime-specific builds for optimal performance

Cons

−Async-only API requires Promise handling for all operations, which can be verbose for simple synchronous use cases
−Steeper learning curve than JWT-only libraries due to comprehensive feature set and JOSE standard complexity
−No built-in token storage or session management—handles cryptographic operations only, requiring additional infrastructure for complete auth systems