jws

jws is a Node.js implementation of the JSON Web Signatures (JWS) specification, implementing the full draft-ietf-jose-json-web-signature spec except X.509 certificate chain signing/verifying. Originally authored by Brian Brennan and now maintained under the Auth0 organization, it underpins widely-used higher-level libraries such as jsonwebtoken.

It exposes both synchronous (jws.sign, jws.verify, jws.decode) and streaming (jws.createSign, jws.createVerify) APIs, and supports the full range of HMAC, RSA, RSA-PSS, and ECDSA signing algorithms (HS256 through ES512), making it a low-level building block for token-based authentication systems.

What You Get

• Synchronous jws.sign() / jws.verify() / jws.decode() functions for one-shot JWS operations
• Streaming SignStream / VerifyStream classes for signing or verifying payloads and keys as chunked data arrives
• Support for all standard JWS algorithms: HS256/384/512, RS256/384/512, PS256/384/512, ES256/384/512, and none
• An exported jws.ALGORITHMS array for programmatic validation of supported algorithm names

Common Use Cases

• Serving as the low-level signing/verification engine underneath higher-level JWT libraries like jsonwebtoken
• Signing and verifying arbitrary payloads (not just JWT claims) using standard JOSE algorithms
• Streaming signature generation/verification for large payloads or keys sourced from readable streams
• Implementing custom token formats that need raw JWS compact serialization without full JWT semantics

Under The Hood

Architecture: The package is intentionally minimal — index.js is a 22-line facade that re-exports SignStream/VerifyStream from lib/sign-stream.js and lib/verify-stream.js, and wraps them into synchronous sign/verify/decode helpers. lib/data-stream.js provides a shared buffering base for both stream classes, and lib/tostring.js normalizes Buffer/string inputs. Actual cryptographic signing/verification is delegated to the jwa package (a separate low-level JWA algorithm implementation), keeping jws focused purely on JWS compact-serialization framing (header.payload.signature) and stream plumbing. Tech Stack: Only two runtime dependencies — jwa for algorithm implementations and safe-buffer for consistent Buffer handling across Node versions — keeping the attack surface and dependency tree small, which matters for a security-sensitive primitive. Tooling includes tape for tests, husky for git hooks, and semantic-release/conventional-changelog for automated releases. Code Quality: The test/jws.test.js suite (backed by a test/data.txt fixture) exercises the sign/verify/decode round-trip and streaming APIs; the library is a widely-depended-upon transitive dependency (67M+ weekly downloads) which has driven battle-testing over its decade-plus history, though the low-level surface area is deliberately small, limiting the room for hidden bugs. API Design: The API cleanly separates a simple synchronous path from an advanced streaming path, and the explicit jws.ALGORITHMS list gives calling code (like jsonwebtoken) a way to validate algorithm names before use — a small but meaningful safety affordance in JWT/JWS libraries where algorithm confusion attacks are a known risk class.