Public API

JWK

const JWK: {
  createKeyStore(): KeyStore;
  asKeyStore(input: string | object): Promise<KeyStore>;
  asKey(input: string | object | KeyLike, form?: string): Promise<Key>;
};

JWK manages cryptographic key material. Use createKeyStore() to start an empty store, asKeyStore() to import a JWK-set (JSON or string), and asKey() to import a single JWK. All key operations return Promises.

JWE

const JWE: {
  createEncrypt(options: object | Key, recipients?: Key | Key[]): Encryptor;
  createDecrypt(keyOrStore: Key | KeyStore, options?: object): Decryptor;
};

JWE handles JSON Web Encryption. Pass a key (or options + key) to createEncrypt() and call .update(plaintext).final() to produce a compact or JSON-serialized JWE. Use createDecrypt() with a key or keystore to unwrap and decrypt incoming tokens.

JWS

const JWS: {
  createSign(options: object | Key, recipients?: Key | Key[]): Signer;
  createVerify(keyOrStore?: Key | KeyStore, options?: object): Verifier;
};

JWS handles JSON Web Signatures. createSign() produces a signer; chain .update(payload).final() to get a compact or JSON JWS. createVerify() (also exported as canYouSee) accepts a key or keystore and returns a verifier whose .verify(token) resolves with { payload, header, key }.

parse

const parse: {
  compact(input: string): Promise<object>;
  json(input: string | object): Promise<object>;
};

parse deserializes raw JWS/JWE tokens without performing cryptographic operations, giving access to headers and structure before committing to a key lookup strategy.

Working examples

Scenario - Generate a key and sign a JWT payload

Create an RSA key, sign a JSON payload as a compact JWS, then verify it against the same key.

import jose = require('./jose/index.js');

async function signAndVerify() {
  const keystore = jose.JWK.createKeyStore();
  const key = await keystore.generate('RSA', 2048, { alg: 'RS256', use: 'sig' });

  const signer = jose.JWS.createSign({ format: 'compact', alg: 'RS256' }, key);
  const token: string = await signer
    .update(JSON.stringify({ sub: 'user-42', iat: Math.floor(Date.now() / 1000) }))
    .final();

  console.log('JWS compact token:', token);

  const verifier = jose.JWS.createVerify(keystore);
  const result = await verifier.verify(token);
  console.log('Verified payload:', result.payload.toString('utf8'));
}

signAndVerify().catch(console.error);

Scenario - Encrypt and decrypt a message with AES-GCM

Generate an AES key and produce a compact JWE, then decrypt it.

import jose = require('./jose/index.js');

async function encryptDecrypt() {
  const keystore = jose.JWK.createKeyStore();
  const key = await keystore.generate('oct', 256, { alg: 'A256GCM', use: 'enc' });

  const encryptor = jose.JWE.createEncrypt({ format: 'compact', contentAlg: 'A256GCM' }, key);
  const ciphertext: string = await encryptor
    .update('Hello, JOSE!')
    .final();

  console.log('JWE compact:', ciphertext);

  const decryptor = jose.JWE.createDecrypt(keystore);
  const result = await decryptor.decrypt(ciphertext);
  console.log('Plaintext:', result.plaintext.toString('utf8'));
}

encryptDecrypt().catch(console.error);

Scenario - Import an existing JWK-set and verify an inbound token

Load externally provided JWKS (e.g., from an identity provider) and verify a token signed by one of its keys.

import jose = require('./jose/index.js');

async function verifyWithRemoteJWKS(jwksJson: object, compactToken: string) {
  const keystore = await jose.JWK.asKeyStore(jwksJson);

  const verifier = jose.JWS.createVerify(keystore);
  try {
    const result = await verifier.verify(compactToken);
    const claims = JSON.parse(result.payload.toString('utf8'));
    console.log('Claims:', claims);
    return claims;
  } catch (err) {
    console.error('Verification failed:', err.message);
    throw err;
  }
}

Scenario - Compute a digest using JWA primitives

Use the low-level JWA namespace to hash data without constructing a full JWS.

import jose = require('./jose/index.js');

async function hashData() {
  const data = Buffer.from('sensitive content');
  const digest = await jose.JWA.digest('SHA-256', data);
  console.log('SHA-256 hex:', digest.toString('hex'));
}

hashData().catch(console.error);

File walkthrough

• index.js - Polyfills Promise/Buffer/process, then assembles and exports the full public surface: JWA, JWE, JWK, JWS, util, parse, and canYouSee (alias for JWS.createVerify).
• algorithms/ - Each file implements one algorithm family (e.g., aes-gcm.js, rsaes.js). index.js aggregates them into four dispatch tables: encrypt/decrypt/sign/verify/digest/derive.
• deps/forge.js - Thin wrapper that imports and re-exports node-forge, providing the underlying AES and bignum primitives.
• deps/ciphermodes/gcm/ - Pure-JS AES-GCM cipher mode built on the forge AES primitive; exposes createCipher and createDecipher.
• deps/ecc/ - Elliptic curve arithmetic (math.js), named curve parameters (curves.js), and a high-level EC key operations entry point (index.js).
• jwe/ - encrypt.js and decrypt.js implement JWE creation and processing; helpers.js and defaults.js centralise shared logic and algorithm defaults.
• jwk/ - keystore.js manages key collections; basekey.js, eckey.js, octkey.js, rsakey.js implement per-key-type logic; helpers.js and constants.js provide shared utilities.
• jws/ - sign.js and verify.js implement JWS creation and verification; helpers.js and defaults.js provide shared header/algorithm handling.
• parse/ - compact.js and json.js parse the two JWS/JWE serialization formats without decrypting or verifying.
• util/ - base64url.js (encode/decode), databuffer.js (binary buffer wrapper), utf8.js, merge.js (deep object merge), algconfig.js (per-algorithm configuration helpers).

Common pitfalls and fixes

• Promise not defined in older Node.js: The library self-polyfills via es6-promise, but ensure es6-promise is installed; otherwise the polyfill require will throw at startup.
• Buffer not available in browser bundles: Webpack 5+ no longer polyfills Buffer by default. Add resolve.fallback: { buffer: require.resolve('buffer/') } and new webpack.ProvidePlugin({ Buffer: ['buffer', 'Buffer'] }) to your Webpack config.
• ESM/CJS interop: node-jose source is CommonJS only. In an ESM project use import { createRequire } from 'module'; const require = createRequire(import.meta.url); before requiring ./jose/index.js.
• Key use / alg mismatch: Passing a key with use: 'sig' to createEncrypt silently fails or throws. Always match use (sig vs enc) and alg to the operation.
• long package peer requirement: The GCM implementation imports long directly. Ensure long version ^4.0.0 is installed; version 5+ is ESM-only and will break require('long') in CJS context.
• Compact vs JSON format default: createEncrypt/createSign default to JSON serialization. Pass { format: 'compact' } as the first options argument to get the xxx.yyy.zzz dot-delimited string expected by most JWT consumers.

Vibe-coding prompt template

I have dropped the node-jose library source into `src/jose/` in my project.
There is a USAGE.md in the same directory with the full integration guide.
The upstream package is `user@example.com`.

Please integrate this source into my project step by step:

1. Read USAGE.md and the file walkthrough to understand the module layout.
2. Install all required runtime dependencies listed in the "Required dependencies" section.
3. Create a wrapper module at `src/crypto/jose.ts` that imports from `src/jose/index.js`
   and re-exports typed helpers for: generating a keystore, signing a payload as a compact
   JWS, verifying a compact JWS, encrypting a Buffer as a compact JWE, and decrypting it.
4. Wire up tsconfig paths so `jose/*` resolves to `src/jose/*`.
5. Add ESM/CJS interop if my project uses `"type": "module"`.
6. Write a test file `src/crypto/jose.test.ts` covering: key generation, sign+verify
   round-trip, and encrypt+decrypt round-trip using real exports from `src/jose/index.js`.
7. Flag any pitfalls from USAGE.md that apply to my specific setup.

Only use APIs visible in USAGE.md. Do not invent method names.

License and credit

The upstream source is released under the BSD license (see source/LICENSE if present, or the repository at https://github.com/cisco/node-jose). Original authors: Cisco Systems, Inc. Upstream npm package: user@example.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Automation, Utilities & Developer Tools

Free