PQ-JOSE — Post-Quantum JOSE Library

Part of the PQ-JWT ecosystem. Built on @pq-jwt/core for post-quantum signing; adds JWE, JWK, and JWKS (jose-compatible API).

A complete post-quantum JOSE library for JavaScript/Node.js — JWT, JWS, JWE, JWK, and JWKS. Cryptography uses NIST FIPS 203 (ML-KEM), FIPS 204 (ML-DSA), and FIPS 205 (SLH-DSA) via audited @noble/post-quantum.

Part of the PQ-JWT ecosystem

@pq-jose/jose is the full JOSE layer of the Post-Quantum JWT (PQ-JWT) project — post-quantum JOSE with a jose-compatible API.

| Package | Role | | --- | --- | | pq-jwt.github.io | Project website and documentation | | @pq-jwt/core | Low-level sign / verify / key primitives (used under the hood) | | @pq-jose/jose (this package) | High-level JOSE API — JWS, JWE, JWK, JWKS |

Signing and verification are delegated to @pq-jwt/core; JWE (ML-KEM + AES-GCM) and JWK/JWKS helpers are implemented in this package via @noble/post-quantum and Node crypto.

API inspired by the jose package; not affiliated with or endorsed by its author. Not a drop-in replacement — post-quantum algorithms only.

Author

Sachin Ruhil · github.com/ruhil6789

Features

• jose-compatible API — SignJWT, EncryptJWT, jwtVerify, jwtDecrypt, JWKS helpers
• Signing — ML-DSA-44/65/87, SLH-DSA-SHA2-128s
• Encryption — ML-KEM-512/768/1024 + AES-256-GCM (compact 5-part JWE)
• JWK / JWKS — AKP key format, thumbprints, local and remote JWKS verifiers
• TypeScript — full src/index.d.ts included
• Zero native deps — pure JS via @noble/post-quantum

Requirements

• Node.js 20.0.0 or higher

Installation

npm install @pq-jose/jose

Quick Start

Sign & verify (JWS)

import { SignJWT, jwtVerify, generateKeyPair } from '@pq-jose/jose';

const { publicKey, secretKey } = generateKeyPair('ML-DSA-65');

const token = new SignJWT({ sub: 'user-1' })
  .setExpirationTime('1h')
  .setIssuer('auth.example.com')
  .sign(secretKey);

const { payload } = jwtVerify(token, publicKey, { issuer: 'auth.example.com' });

Encrypt & decrypt (JWE)

import { EncryptJWT, jwtDecrypt, generateKeyPair } from '@pq-jose/jose';

const { publicKey, secretKey } = generateKeyPair('ML-KEM-768');

const token = new EncryptJWT({ secret: 'classified' })
  .setAlgorithm('ML-KEM-768')
  .setExpirationTime('15m')
  .encrypt(publicKey);

const { payload } = jwtDecrypt(token, secretKey);

See examples/ for runnable scripts.

Scripts

npm test              # unit tests
npm run test:ecosystem  # pack + JS/TS consumer checks

License

MIT — see LICENSE