jose

jose is a JavaScript library for JSON Object Signing and Encryption (JOSE) — the umbrella of specs behind JSON Web Tokens (JWT), JSON Web Signatures (JWS), JSON Web Encryption (JWE), and JSON Web Keys (JWK/JWKS). It implements the full RFC 751x family plus newer additions like ML-DSA for JOSE, all on top of the standard Web Crypto API rather than a bespoke crypto implementation.

The library ships as a single ESM package with zero runtime dependencies and is built to run identically across Node.js, browsers, Deno, Bun, Cloudflare Workers, and Electron. It exposes both a low-level, spec-faithful API (Compact/Flattened/General JWS and JWE) and higher-level convenience classes like SignJWT and EncryptJWT for the common JWT case, along with remote and local JWKS helpers for key rotation.

What You Get

• Full JWS support (Compact, Flattened, General serialization) for signing and verifying arbitrary payloads
• Full JWE support (Compact, Flattened, General serialization) for encrypting and decrypting arbitrary payloads
• SignJWT and EncryptJWT fluent builder classes plus jwtVerify/jwtDecrypt for the common JWT workflow
• Local and remote JWKS helpers (createLocalJWKSet, createRemoteJWKSet) with built-in caching for key rotation
• Key import/export/generation utilities for PEM (SPKI, PKCS#8, X.509), JWK, and raw secrets

Common Use Cases

• Issuing and verifying signed JWTs for API authentication and session tokens
• Encrypting sensitive claims in JWE-based tokens instead of relying on TLS alone
• Verifying tokens against a provider’s remote JWKS endpoint (OAuth/OIDC identity providers)
• Running crypto-heavy auth logic inside edge runtimes like Cloudflare Workers where Node’s crypto module isn’t available

Under The Hood

Architecture

jose is organized around the JOSE spec family, with parallel module trees for JWS (src/jws/{compact,flattened,general}), JWE (src/jwe/{compact,flattened,general}), JWK (src/jwk/{embedded,thumbprint}), JWKS (src/jwks/{local,remote}), and a higher-level JWT layer (src/jwt/{sign,verify,encrypt,decrypt,unsecured}) that composes the JWS/JWE primitives with claims-set validation (src/lib/jwt_claims_set.ts). All cryptographic operations funnel through a shared internal lib/ layer (crypto_key.ts, key_management.ts, signing.ts, content_encryption.ts, ecdhes.ts, aeskw.ts, rsaes.ts, pbes2kw.ts) that normalizes keys and dispatches to the Web Crypto API’s SubtleCrypto interface rather than any bespoke crypto code, which is what lets the same source run unmodified in Node, browsers, Deno, Bun, and Workers. The public surface in src/index.ts re-exports every operation individually, and the package.json exports map exposes dozens of matching subpaths (jose/jwt/sign, jose/jwks/remote, etc.) so each algorithm/format only pulls in the code it needs.

Tech Stack

Written in strict TypeScript with zero runtime dependencies (an empty “dependencies” field in package.json backs the README’s explicit “Dependencies: 0” claim). The build pipeline uses tsc for type declarations and esbuild for bundled/minified/UMD builds, with a separate build:deno target that transforms the same source into Deno-compatible imports. Package output is ESM-only (type: module) targeting es2022. Devtooling includes ava for unit tests, Playwright for browser tests, and typedoc (with typedoc-plugin-markdown) to generate the docs/ reference straight from JSDoc.

Code Quality

The repo separates unit tests (test/, using ava, 36 files spanning jws/jwe/jwk/jwks/jwt/util) from cross-runtime conformance tests (tap/, with dedicated scripts to run the suite under Node, Bun, Deno, Electron, Workerd, and real browsers via Playwright) — a notably rigorous setup for a library that has to behave identically across five-plus runtimes. Source files are small and single-purpose (e.g. src/jwt/sign.ts at 198 lines, src/lib/crypto_key.ts at 140 lines), each carrying extensive JSDoc with runnable examples that also feed the generated docs.

API Design The library pairs a low-level, spec-literal API (CompactSign, FlattenedEncrypt, GeneralVerify, etc., mirroring the JWS/JWE serialization names from the RFCs) with high-level convenience classes (SignJWT, EncryptJWT) that use a fluent, chainable builder pattern (.setIssuer().setAudience().setExpirationTime().sign(key)) for the common JWT case — letting newcomers use the friendly builder while power users can drop to the primitives. Naming is consistent across the JWS/JWE/JWK/JWT modules, and every exported function/class has a corresponding docs/ page and JSDoc example, keeping the boilerplate needed to get started low despite the library’s broad spec coverage.