jose

What is jose?

The 'jose' npm package is a JavaScript library that provides a variety of cryptographic operations based on JSON Web Tokens (JWT), JSON Web Encryption (JWE), JSON Web Signature (JWS), and JSON Web Key (JWK). It is designed to be compliant with the JOSE (JSON Object Signing and Encryption) suite of standards, and it supports various algorithms for encryption, decryption, signing, and verification of tokens.

What are jose's main functionalities?

JWT Signing

This code sample demonstrates how to create and sign a JWT with a specified algorithm and secret.

const { SignJWT } = require('jose');

const jwt = await new SignJWT({ 'urn:example:claim': true })
  .setProtectedHeader({ alg: 'HS256' })
  .setIssuedAt()
  .setIssuer('urn:example:issuer')
  .setAudience('urn:example:audience')
  .setExpirationTime('2h')
  .sign(new TextEncoder().encode('your-256-bit-secret'));

console.log(jwt);

JWT Verification

This code sample shows how to verify a JWT using a secret key and retrieve the payload and protected header.

const { jwtVerify } = require('jose');

const { payload, protectedHeader } = await jwtVerify(jwt, new TextEncoder().encode('your-256-bit-secret'));

console.log(payload);
console.log(protectedHeader);

JWE Encryption

This code sample illustrates how to encrypt a JWT using RSA-OAEP-256 for key management and A256GCM for content encryption.

const { EncryptJWT } = require('jose');

const jwe = await new EncryptJWT({ 'urn:example:claim': true })
  .setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM' })
  .setIssuedAt()
  .setIssuer('urn:example:issuer')
  .setAudience('urn:example:audience')
  .setExpirationTime('2h')
  .encrypt(publicKey);

console.log(jwe);

JWE Decryption

This code sample demonstrates how to decrypt a JWE and obtain the payload and protected header using a private key.

const { jwtDecrypt } = require('jose');

const { payload, protectedHeader } = await jwtDecrypt(jwe, privateKey);

console.log(payload);
console.log(protectedHeader);

JWK Key Generation

This code sample shows how to generate a public and private key pair for the RS256 algorithm.

const { generateKeyPair } = require('jose');

const { publicKey, privateKey } = await generateKeyPair('RS256');

console.log(publicKey);
console.log(privateKey);

Other packages similar to jose

jsonwebtoken

The 'jsonwebtoken' package is similar to 'jose' in that it provides functionality for creating and verifying JWTs. It is widely used and has a simpler API for basic JWT operations, but it does not support JWE or more advanced JOSE features.

node-jose

The 'node-jose' package is another alternative that implements the JOSE suite of standards. It offers similar functionalities to 'jose' but has a different API design and may have different performance characteristics.

jws

The 'jws' package is focused on JSON Web Signatures (JWS). It is a simpler library that allows signing and verifying messages but does not handle JWTs, JWEs, or JWKs directly.

README

jose

JSON Object Signing and Encryption (JOSE) library (symmetric and asymmetric)

API

JWA

The implementation of the JSON Web Algorithms for use with JSON Web Signatures or JSON Web Encryption.

The following cryptographic algorithms are supported for JWS:

"alg" Header Parameter	Digital Signature or MAC Algorithm
HS256	HMAC using SHA-256 hash algorithm
HS384	HMAC using SHA-384 hash algorithm
HS512	HMAC using SHA-512 hash algorithm
RS256	RSASSA-PKCS1-v1_5 using SHA-256 hash algorithm
RS384	RSASSA-PKCS1-v1_5 using SHA-384 hash algorithm
RS512	RSASSA-PKCS1-v1_5 using SHA-512 hash algorithm
ES256	ECDSA using P-256 curve and SHA-256 hash algorithm
ES384	ECDSA using P-384 curve and SHA-384 hash algorithm
ES512	ECDSA using P-521 curve and SHA-512 hash algorithm
none	No integrity protection

Currently no key encryption and content encryption algorithms are supported.

jwa(algorithm)

Creates a new jwa object with sign and verify methods, depending on the specified algorithm. Valid values for algorithm can be found in the above table and are case-sensitive. Passing an invalid algorithm will throw a TypeError.

Example:

var jose = require('jose');
var hs256 = jose.jwa('HS256');

jwa.sign(input, secretOrPrivateKey)

This method is only available to algorithms for digital signatures and MACs.

Sign input with either a secret using a HMAC algorithm or a private key using a digital signature algorithm.

If input is neither a string nor a buffer, it will be stringified using JSON.stringify.

When using a HMAC algorithm secretOrPrivateKey should be either a string or a buffer. When using a digital signature algorithm, the value should be a PEM encoded private key.

Returns the signature in base64url format.

Example:

var jose = require('jose');
var hs256 = jose.jwa('HS256');
var signature = hs256.sign('input', 'secret');
console.log(signature); // Prints 'jYmF0Et6vTLLqjd5o9qgGeDSaaIq7BWvjnKW9wLMaMY'

jwa.verify(input, signature, secretOrPublicKey)

This method is only available to algorithms for digital signatures and MACs.

Verify that signature is a valid signature for input using a secret for HMAC algorithms or a public key for digital signature algorithms.

If input is neither a string nor a buffer, it will be stringified using JSON.stringify.

When using a HMAC algorithm secretOrPublicKey should be either a string or a buffer. Whenn using a digital signature algorithm, the value should be a PEM encoded public key.

Returns a boolean indicating whether or not the signature is valid.

Example:

var jose = require('jose');
var hs256 = jose.jwa('HS256');
var isValid = hs256.verify('input', 'jYmF0Et6vTLLqjd5o9qgGeDSaaIq7BWvjnKW9wLMaMY', 'secret');
console.log(isValid); // Prints 'true'