Skip to content

About

Post-quantum cryptography toolkit for TypeScript and Node.js: ML-KEM (FIPS 203), ML-DSA (FIPS 204), SLH-DSA (FIPS 205) and HPKE, plus AES-GCM, XChaCha20-Poly1305, Ed25519 and Argon2id. 18 packages: library, CLI, Fastify REST server, SDK, KMS, Prisma and TypeORM field encryption, React and Vue hooks, and a CBOM generator.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

9 stars

Watchers

1 watching

Forks

Latest commit

 

History

1,109 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Crypto Service logo

Crypto Service

A comprehensive TypeScript cryptography toolkit: 50+ algorithms, post-quantum ready, full-stack integration.

Build Coverage Registry Docs OpenSSF Scorecard OpenSSF Best Practices License: Apache-2.0 OR MIT Node.js 22 or newer

crypto-cli 0.0.39 printing its version, hashing a file with BLAKE3, signing and verifying it with ML-DSA-65, and round-tripping it through XChaCha20-Poly1305


Contents

Getting started

The Crypto Service ecosystem

Library reference

Operational


Install

As a Node.js / TypeScript library

pnpm add @sebastienrousseau/crypto-lib

Crypto Service is distributed as a family of scoped npm packages. Install only what you need, or clone the entire monorepo for full-stack development.

Method Command / Steps
pnpm (recommended) pnpm add @sebastienrousseau/crypto-lib
npm npm install @sebastienrousseau/crypto-lib
yarn yarn add @sebastienrousseau/crypto-lib
From source git clone https://github.com/sebastienrousseau/crypto-service.git && cd crypto-service && pnpm install && pnpm -r run build
Docker docker run -p 3000:3000 ghcr.io/sebastienrousseau/crypto-service:latest

Docker container images are published to GHCR. Standalone distro packages and Repology tracking will be established once packaged by distributions.

Individual packages

From 0.0.8, every tagged release publishes all 18 packages to npm and to GitHub Packages from CI. From 0.0.9, the npm versions are published through trusted publishing only after a maintainer approves the release, and each carries a provenance attestation (0.0.8 was published without one):

pnpm add @sebastienrousseau/crypto-lib
pnpm add @sebastienrousseau/crypto-server
pnpm add -g @sebastienrousseau/crypto-cli

All 18 packages share one version: this tree is 0.0.39. Releases before 0.0.8 reached npm only partially (crypto-lib 0.0.3, crypto-server 0.0.2, crypto-cli 0.0.1); do not use those versions.


Requirements

Node.js >= 22.0.0 (CI tests Node.js 22 and 24 on Ubuntu and macOS). Package manager: pnpm 11.9.0 (pinned in packageManager; needs Node.js >= 22.13 for development). TypeScript: ~5.9.3 for development. Docker images require Docker 20.10+ or a compatible OCI runtime. See toolchain policy.


Quick Start

import { randomBytes } from "node:crypto";
import {
  aesGcmEncrypt,
  aesGcmDecrypt,
  hash,
  mlKemKeygen,
  mlKemEncapsulate,
  mlKemDecapsulate,
  slhDsaKeygen,
  slhDsaSign,
  slhDsaVerify,
} from "@sebastienrousseau/crypto-lib";

// 1. Authenticated encryption with AES-256-GCM (32-byte key)
const key = randomBytes(32);
const { ciphertext } = aesGcmEncrypt({ key, plaintext: "Sensitive payload" });
const plaintext = new TextDecoder().decode(aesGcmDecrypt({ key, ciphertext }));

// 2. Hashing with SHA-256 (hex digest)
const { digest } = hash({ algorithm: "sha256", data: "Integrity check" });

// 3. ML-KEM-768 key encapsulation (FIPS 203 algorithm)
const kem = mlKemKeygen(768);
const sent = mlKemEncapsulate(768, kem.publicKey);
const received = mlKemDecapsulate(768, kem.secretKey, sent.ciphertext);
// received.sharedSecret === sent.sharedSecret

// 4. SLH-DSA signatures (FIPS 205 algorithm)
const signer = slhDsaKeygen("sha2-128s");
const { signature } = slhDsaSign("sha2-128s", signer.secretKey, "Message");
const { valid } = slhDsaVerify(
  "sha2-128s",
  signer.publicKey,
  "Message",
  signature,
);

The post-quantum algorithms come from @noble/post-quantum, which has not been independently audited and does not guarantee constant-time execution. No module in this suite is FIPS 140-3 validated.

The CLI runs one operation per subcommand, or opens an interactive menu when started with no arguments in a terminal:

crypto-cli hash -a blake3 note.txt
crypto-cli keygen -a ml-dsa-65 --json > signer.json
crypto-cli sign --key-file signer.json note.txt > note.sig
crypto-cli verify --key-file signer.json --signature-file note.sig note.txt

The Crypto Service ecosystem

All 18 packages follow a coordinated versioning policy with automated CI enforcement and lockstep releases.

Note

Registry availability: from 0.0.8 every package is published to npm and GitHub Packages on each tagged release. Earlier npm versions of @sebastienrousseau/crypto-service, crypto-lib, crypto-server and crypto-cli predate this repository's fixes; use 0.0.8 or later.

Component Purpose Use case Registry Availability
@sebastienrousseau/crypto-lib Core crypto library: classical, modern and post-quantum algorithms Standalone library for Node.js, browsers, and Edge npm (0.0.8+)
@sebastienrousseau/crypto-server Fastify REST API service Cryptography-as-a-service microservice npm (0.0.8+)
@sebastienrousseau/crypto-cli Interactive terminal CLI DevOps automation, local keygen, and file encryption npm (0.0.8+)
@sebastienrousseau/crypto-sdk Typed TypeScript SDK client for the REST API Client applications consuming the REST service npm (0.0.8+)
@sebastienrousseau/crypto-api Postman collection types and a Postman-to-Markdown converter API documentation tooling npm (0.0.8+)
@sebastienrousseau/crypto-middleware Express and Fastify request encryption/decryption middleware Automated payload encryption in HTTP pipelines npm (0.0.8+)
@sebastienrousseau/crypto-react React hooks (useEncryption, useKeypair, etc.) Web application client-side cryptography npm (0.0.8+)
@sebastienrousseau/crypto-vue Vue 3 composables for reactive cryptography Vue/Nuxt client-side encryption and hashing npm (0.0.8+)
@sebastienrousseau/crypto-edge Cloudflare Workers, Vercel Edge, and Deno runtime adapters Serverless and edge cryptographic processing npm (0.0.8+)
@sebastienrousseau/crypto-kms KMS interface: AWS, Google Cloud, Vault Transit and local providers; Azure is a stub Envelope encryption and key rotation npm (0.0.8+)
@sebastienrousseau/crypto-prisma Prisma client extension for transparent field encryption Field-level encryption before data reaches the DB npm (0.0.8+)
@sebastienrousseau/crypto-typeorm TypeORM column transformer for encrypted persistence Transparent database column encryption npm (0.0.8+)
@sebastienrousseau/crypto-wasm Placeholder: contains no WebAssembly code yet None yet; operations run in JavaScript npm (0.0.8+)
@sebastienrousseau/crypto-testing Cryptographic test utilities, known-answer tests, and mocks Testing downstream applications using crypto-service npm (0.0.8+)
@sebastienrousseau/crypto-mcp Model Context Protocol server exposing crypto tools & prompts AI agent integration (Claude, Cursor, Antigravity) npm (0.0.8+)
@sebastienrousseau/crypto-lsp Language Server Protocol server for crypto diagnostics & migration IDE real-time analysis, PEM linting, quick fixes npm (0.0.8+)
@sebastienrousseau/crypto-cbom Cryptographic Bill of Materials generator (CycloneDX 1.6 / SPDX 3.0) Cryptographic inventory tracking npm (0.0.8+)
@sebastienrousseau/crypto-benchmarks Comparative benchmarking suite (classical vs post-quantum) Performance regression testing and throughput checks npm (0.0.8+)

Capabilities at a glance

All algorithms run in software. No module in this suite is FIPS 140-3 validated; the FIPS numbers below name the algorithm standards implemented.

Area Capability Implementation
Symmetric AEAD AES-128/256-GCM, AES-128/256-GCM-SIV, XChaCha20-Poly1305 @noble/ciphers
Signatures Ed25519, Ed448, ECDSA P-256/P-384, Schnorr (BIP-340) @noble/curves
Key Exchange & KEM X25519, X448, ECDH P-256/P-384, ML-KEM-512/768/1024 (FIPS 203), hybrid KEMs @noble/curves, @noble/post-quantum
Post-Quantum Signatures ML-DSA-44/65/87 (FIPS 204), SLH-DSA SHA-2/SHAKE (FIPS 205), FN-DSA-512/1024 @noble/post-quantum
Hybrid Encryption HPKE (RFC 9180) @noble/*
Hash Functions SHA-256/384/512, SHA3-256/512, BLAKE2b, BLAKE3 @noble/hashes
Key Derivation (KDF) HKDF-SHA256, PBKDF2-SHA256, scrypt, Argon2id/i/d @noble/hashes
Message Authentication HMAC (SHA-2, SHA-3), KMAC-128/256 @noble/hashes
OpenPGP Key generation, encryption, signing, revocation (RSA and ECC keys) OpenPGP.js
Protocols & Tokens PQXDH, double ratchet, PAKE, Shamir threshold sharing, PASETO v4 crypto-lib (built on @noble/*)
Observability (server) OpenTelemetry tracing and metrics, Prometheus-format metrics endpoint, JSON logs crypto-server

Ecosystem comparison

This matrix compares Crypto Service's unified TypeScript architecture against alternative solutions.

Project Algorithm Coverage Post-Quantum (FIPS 203/204/205) Full-Stack Integrations (ORM/React/Vue/CLI)
Crypto Service 50+ algorithms Yes (ML-KEM, ML-DSA, SLH-DSA) Yes (Prisma, TypeORM, React, Vue, CLI)
Web Crypto API Standard web set only No native PQ support No (low-level browser/runtime only)
Node.js crypto Classical OpenSSL set Experimental / OpenSSL-dependent No (standard library only)
libsodium High-level modern suite No (pre-quantum focus) Partial community bindings

See docs/COMPARISON.md for the evidence and complete matrix.


Benchmarks

No benchmark numbers are published yet. Earlier figures in this section did not come from committed benchmark code and were removed. Run node benchmarks/crypto-bench.ts after pnpm -r run build to measure on your own hardware; CI runs the same script on pull requests to main. See docs/BENCHMARKS.md.


Features

Unified Cryptographic API

  • Consistent interface for all algorithms: encryption, hashing, signing, key generation, and key derivation.
  • Built-in type definitions, strict input validation, and automatic serialization/deserialization.
  • Support for classical algorithms (AES, RSA, ECC, HMAC) and modern primitives (ChaCha20-Poly1305, Ed25519, X25519).

Post-Quantum Cryptography (FIPS 203, 204, 205)

  • ML-KEM (FIPS 203): Module-Lattice-Based Key-Encapsulation Mechanism across security categories (512, 768, 1024).
  • ML-DSA (FIPS 204): Module-Lattice-Based Digital Signature Algorithm across parameter sets (44, 65, 87).
  • SLH-DSA (FIPS 205): Stateless Hash-Based Digital Signature Algorithm supporting SHA-2 and SHAKE parameter sets.

Full-Stack Architecture

  • Microservice Ready: Preconfigured Fastify server (@sebastienrousseau/crypto-server) with OpenAPI/Swagger schemas.
  • Client SDK: Typed SDK (@sebastienrousseau/crypto-sdk) for the REST API.
  • Command-Line Interface: Interactive terminal CLI (@sebastienrousseau/crypto-cli).
  • UI Framework Hooks: React hooks (@sebastienrousseau/crypto-react) and Vue 3 composables (@sebastienrousseau/crypto-vue).
  • Database Field Encryption: Transparent field-level encryption extensions for Prisma (@sebastienrousseau/crypto-prisma) and TypeORM (@sebastienrousseau/crypto-typeorm).

Configuration

Command-Line Interface (crypto-cli)

Command What it does
hash [file] Hash a file or stdin (SHA-2, SHA-3, BLAKE2b, BLAKE3)
keygen -a <algorithm> Generate an Ed25519, X25519, Ed448, X448, P-256/384, ML-KEM or ML-DSA key pair
encrypt / decrypt [file] XChaCha20-Poly1305 sealed box with a 32-byte key file
sign / verify [file] Sign and verify with a key pair from keygen --json
password hash / password verify Argon2id password hashing (PHC string)
hpke keygen / seal / open HPKE (RFC 9180), including the X25519 + ML-KEM-768 hybrid
stream, opaque, kms, cbom Streaming AEAD, OPAQUE (RFC 9807), KMS operations, CBOM scan/audit

Every command takes --help, and most take --json for one line of machine-readable output. decrypt and verify exit 1 on a wrong key, a modified input or an invalid signature. Run crypto-cli with no arguments in a terminal for the interactive menu.

Server Configuration (crypto-server)

The REST API server is configured via environment variables:

Variable Description Default
PORT HTTP server port 3000
HOST Bind host address localhost
LOG_LEVEL Logger level (error, warn, info, debug) info
OTEL_EXPORTER_OTLP_ENDPOINT OpenTelemetry OTLP collector endpoint None (export disabled)
CRYPTO_API_KEY Static API key for service-to-service requests None
JWT_SECRET HMAC secret for HS256 JWT validation None
JWT_MAX_AGE Maximum JWT lifetime in seconds 3600
JWT_ISSUER Required JWT iss claim None (not checked)
JWT_AUDIENCE Required JWT aud value None (not checked)
ALLOW_ANONYMOUS 1 allows unauthenticated requests Off
CRYPTO_KEY_DIR Keystore for the v1 PGP routes Bundled test keys
CRYPTO_KEY_OUT_DIR Where generated keys are persisted None (memory only)

With neither CRYPTO_API_KEY nor JWT_SECRET set, every request except /health, /live, /ready, /metrics, /docs and the OPAQUE login steps (/v2/opaque/login/init and /login/finish, metered per client address) gets 401. OPAQUE registration needs credentials: a caller registers its own subject, and crypto:admin can provision any identifier. In production (NODE_ENV=production) the server refuses to start without a credential unless ALLOW_ANONYMOUS=1 is set (for example behind an authenticating gateway), rejects a JWT_SECRET shorter than 32 bytes or set without JWT_ISSUER and JWT_AUDIENCE, and refuses the bundled test keys unless CRYPTO_KEY_DIR is set.

The full list, including CORS, rate limiting, trusted proxies, key encryption at rest and the KMS providers, is in the crypto-server README.


Examples

Runnable example code and integration patterns are located in examples/:

Middleware Integration (Express / Fastify)

import Fastify from "fastify";
import { cryptoPlugin } from "@sebastienrousseau/crypto-middleware";

const app = Fastify();
await app.register(cryptoPlugin, {
  key: process.env.PAYLOAD_KEY, // 64 hex characters (256-bit key)
  routes: ["/api/**"],
  operations: ["decrypt-request", "encrypt-response"],
});

Prisma Transparent Field Encryption

import { PrismaClient } from "@prisma/client";
import { createFieldEncryptionExtension } from "@sebastienrousseau/crypto-prisma";

const prisma = new PrismaClient().$extends(
  createFieldEncryptionExtension({
    key: process.env.ENCRYPTION_KEY!, // 64 hex characters (256-bit key)
    encryptedFields: [{ model: "User", fields: ["ssn", "dateOfBirth"] }],
  }),
);

When not to use Crypto Service

  • You need a FIPS 140-3 validated module: nothing in this suite is validated. The FIPS 203/204/205 algorithms come from @noble/post-quantum, which is not a validated module.
  • You need an HSM or PKCS#11: there is no PKCS#11 binding. The crypto-kms Pkcs11HsmProvider is an in-memory software simulation for tests; the Azure KMS provider is a stub.
  • You need audited or guaranteed constant-time post-quantum code: @noble/post-quantum has not been independently audited and does not guarantee constant-time execution.
  • Embedded bare-metal microcontrollers: devices without a Node.js or browser JavaScript runtime.

Development

pnpm install
pnpm -r run build
pnpm -r run lint
pnpm -r run format
pnpm -r run test
pnpm -r run docs

make check runs the local gate: build, lint, format, the complexity gate, tests, TypeDoc, manifest checks and a pack smoke test. The complexity gate holds every function to cyclomatic ≤ 10, cognitive ≤ 15, Halstead difficulty ≤ 30 and ≤ 60 lines (≤ 500 lines per file). Every function meets them, so complexity-baseline.json is empty and any new offender fails the gate. CI enforces 100% line and function coverage in every package, and 100% branch coverage in every package except crypto-lib (99.5%). Pull requests must pass the complete CI matrix before merge. See DEVELOPMENT.md for local gate reproduction and CONTRIBUTING.md for commit and PR guidelines.


Security

Report vulnerabilities privately according to SECURITY.md. Never file public issues for security vulnerabilities.

Cryptographic operations use @noble/hashes, @noble/curves, @noble/ciphers, @noble/post-quantum, Node.js crypto and OpenPGP.js. @noble/post-quantum has not been independently audited and does not guarantee constant-time execution. No module in this suite is FIPS 140-3 validated. Key zeroization is limited: JavaScript strings and garbage-collected buffers cannot be reliably wiped. Not every secret comparison is constant-time (see SECURITY.md). CI runs pnpm audit, CodeQL analysis and SBOM generation.


Documentation


Stability guarantees

Versions advance strictly one step at a time on the 0.0.x line (v0.0.1 → v0.0.2 → v0.0.3 ... → v0.0.999 → v0.1.0). Work for every release iteration begins on a dedicated feat/v<version> branch.

All packages in the suite move in lockstep. Public API signatures, cipher output formats, and serialization schemas are strictly versioned. Breaking changes to serialized ciphertext formats, key formats, or algorithm defaults still ship as the next 0.0.x version: the CHANGELOG marks each one (breaking) and MIGRATION.md says how to upgrade. Minimum toolchain upgrades (e.g. Node.js LTS floor) are governed by POLICIES.md and announced in advance.


License

Dual-licensed under Apache-2.0 OR MIT, at your option. See LICENSE. Dependencies retain their own licenses.

About

Post-quantum cryptography toolkit for TypeScript and Node.js: ML-KEM (FIPS 203), ML-DSA (FIPS 204), SLH-DSA (FIPS 205) and HPKE, plus AES-GCM, XChaCha20-Poly1305, Ed25519 and Argon2id. 18 packages: library, CLI, Fastify REST server, SDK, KMS, Prisma and TypeORM field encryption, React and Vue hooks, and a CBOM generator.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

9 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages