@sebastienrousseau/crypto-lib

v0.0.37

Published

4 hours ago

Post-quantum cryptography library for TypeScript and Node.js: ML-KEM, ML-DSA, SLH-DSA, HPKE, AES-GCM, XChaCha20-Poly1305, Ed25519, X25519, SHA-3, BLAKE3, Argon2id and OpenPGP.

Getting started

Install — installation via pnpm, npm, or yarn
Requirements — runtime floor and environment prerequisites
Quick Start — minimal working usage sample

The Crypto Service ecosystem

The Crypto Service ecosystem — full 18-package suite overview

Package reference

Reference & Usage — features, configuration, and capabilities
Examples — runnable sample code

Operational

Development — build, lint, format, and test targets
Security — vulnerability disclosure and cryptographic invariants
Documentation — TypeDoc API docs and ecosystem guides
Stability guarantees — SemVer axis and release policy
License

Install

pnpm add @sebastienrousseau/crypto-lib
# or
npm install @sebastienrousseau/crypto-lib
# or
yarn add @sebastienrousseau/crypto-lib

Requirements

Node.js: ^22.0.0 or >=24.0.0 (active and maintenance LTS releases)
Package Manager: pnpm >=9 (recommended) or npm >=10
TypeScript: >=5.0 (when compiling with TypeScript)

Quick Start

import { crypto } from "@sebastienrousseau/crypto-lib";

// Generate a random 256-bit key
const key = crypto.randomKey();

// Encrypt (XChaCha20-Poly1305 via secretbox)
const ciphertext = crypto.encrypt(key, "classified payload");

// Decrypt
const plaintext = crypto.decrypt(key, ciphertext);
console.log(Buffer.from(plaintext).toString("utf8"));
// => "classified payload"

// Hash
const digest = crypto.hash("sha3-256", "hello world");

// Sign and verify (Ed25519)
const kp = crypto.generateKeyPair("ed25519");
const sig = crypto.sign("ed25519", kp.privateKey, "message");
const ok = crypto.verify("ed25519", kp.publicKey, "message", sig);

The Crypto Service ecosystem

Crypto Service provides a complete cryptography stack across 14 specialized packages:

| Package | Role | Description | :---------------------------------------------------------------------------------------------------------------------------------------- | :--------------- | :------------------------------- | @sebastienrousseau/crypto-api | @sebastienrousseau/crypto-benchmarks | @sebastienrousseau/crypto-cbom | @sebastienrousseau/crypto-cli | @sebastienrousseau/crypto-edge | @sebastienrousseau/crypto-kms | @sebastienrousseau/crypto-lib@sebastienrousseau/crypto-lsp| @sebastienrousseau/crypto-mcp | @sebastienrousseau/crypto-middleware | @sebastienrousseau/crypto-prisma | @sebastienrousseau/crypto-react | @sebastienrousseau/crypto-sdk | @sebastienrousseau/crypto-server | @sebastienrousseau/crypto-testing | @sebastienrousseau/crypto-typeorm | @sebastienrousseau/crypto-vue | @sebastienrousseau/crypto-wasm | ---------------------------------------------------------------------------------------------- | | API docs | Postman collection types and a Postman-to-Markdown converter; the server's API contract is its OpenAPI document. | | Benchmarks | Benchmarks comparing classical and post-quantum cryptography: ops/sec, latency and throughput. | | CBOM | Cryptographic Bill of Materials generator and auditor (CycloneDX 1.6, SPDX 3.0). | | Terminal CLI | Command-line interface: hashing, key generation, encryption, signing, HPKE, Argon2id and CBOM scans, with an interactive menu. | | Edge Runtime | Edge-runtime cryptographic operations using the Web Crypto API, optimized for Cloudflare Workers, Vercel Edge, and Deno. | | Cloud KMS | Unified KMS interface: AWS KMS, Google Cloud KMS, Vault Transit and local providers; Azure is a stub. | e> (this package) | Core Library | Core library: post-quantum ML-KEM, ML-DSA and SLH-DSA, plus classical, modern and OpenPGP cryptography for TypeScript. | | IDE Analysis | Language server that flags weak and quantum-vulnerable cryptography in the editor, with quick fixes. | | AI Agents | Model Context Protocol server exposing cryptography tools to AI assistants and agents. | | Middleware | Cryptographic middleware for Express and Fastify: decrypt requests, encrypt responses, verify HMAC signatures and JWTs. | | ORM Adapter | Transparent field-level encryption extension for Prisma Client, using XChaCha20-Poly1305. | | React Hooks | React hooks and context provider for client-side cryptographic operations with zero boilerplate. | | Client SDK | A zero-dependency, typed HTTP client for the Crypto Service REST API, with full post-quantum support. | | HTTP API | A hardened Fastify REST API for cryptographic operations, with rate limiting, OpenAPI schemas, and post-quantum endpoints. | | Test Support | Deterministic keys, fast mocks, and test fixtures for crypto-lib | | ORM Adapter | TypeORM column-level encryption with a single decorator, powered by crypto-lib. | | Vue Composables | Vue 3 composables for client-side cryptography | | Acceleration | Placeholder for a WebAssembly accelerator; no WebAssembly module ships yet. |

`Overview`

crypto-lib is the core cryptographic engine of the Crypto Service Suite. It provides a unified TypeScript API over the @noble/hashes, @noble/curves, @noble/ciphers, and @noble/post-quantum libraries -- pure TypeScript, zero native add-ons, no C bindings. The first three have had independent audits; @noble/post-quantum has not. Post-quantum primitives (ML-KEM, ML-DSA, SLH-DSA) are first-class citizens, not add-ons, and hybrid constructions combine classical and PQ algorithms so security holds even if one family breaks.

On Node.js 24.7 and later, ML-KEM, ML-DSA and SLH-DSA run in the runtime's own OpenSSL 3.5 instead: measured on an Apple A18 Pro with Node.js 24.21, ML-KEM-768 encapsulation is about 7 times faster, ML-DSA-65 signing about 20 times and SLH-DSA-SHA2-128f signing about 6 times. Keys, ciphertexts and signatures are the same raw bytes as noble's, so data made on one runtime works on another, and noble still runs in browsers, edge runtimes and older Node.js. nativeAlgorithms() in @sebastienrousseau/crypto-lib/accel lists what runs natively.

In a browser, import from the ./modern, ./high-level, ./keys, ./streaming, ./protocols and ./tokens subpaths: they use no Node.js API (each is bundled for the browser and run in Chrome in testing). The main entry also loads the OpenPGP API and the file keystore, and ./accel the worker pool, which need Node.js.

Two API layers serve different needs: a unified crypto.* namespace for common tasks, and granular per-module imports for full control and tree-shaking. Both layers use the same underlying noble primitives; the unified API is a thin dispatcher that adds no overhead.

`Features`

`Library Usage`

import { hash } from "@sebastienrousseau/crypto-lib";

const r = hash({ algorithm: "sha3-256", data: "hello" });
console.log(r.digest); // hex string

import { crypto } from "@sebastienrousseau/crypto-lib";

const kp = crypto.generateKeyPair("ed25519");
const sig = crypto.sign("ed25519", kp.privateKey, "payload");
const ok = crypto.verify("ed25519", kp.publicKey, "payload", sig);

import { aeadEncrypt, aeadDecrypt } from "@sebastienrousseau/crypto-lib";

const key = "a".repeat(64); // 32-byte hex key
const { ciphertext } = aeadEncrypt({ key, plaintext: "secret" });
const plain = aeadDecrypt({ key, ciphertext });

import {
  mlKemKeygen,
  mlKemEncapsulate,
  mlKemDecapsulate,
} from "@sebastienrousseau/crypto-lib";

const kp = mlKemKeygen(768);
const { ciphertext, sharedSecret: ss1 } = mlKemEncapsulate(768, kp.publicKey);
const { sharedSecret: ss2 } = mlKemDecapsulate(768, kp.secretKey, ciphertext);
// ss1 === ss2

import { hashPassword, verifyPasswordPhc } from "@sebastienrousseau/crypto-lib";

const result = hashPassword({ password: "hunter2" });
console.log(result.phc); // $argon2id$v=19$m=65536,t=3,p=4$...
const { valid } = verifyPasswordPhc({ password: "hunter2", phc: result.phc });

import { Keyring } from "@sebastienrousseau/crypto-lib";

const ring = new Keyring();
const key = ring.add("ed25519", { use: "sig" });
const rotated = ring.rotate(key.kid);
const jwks = ring.toJwks();

`Examples`

All examples are self-contained TypeScript files in the examples/ directory. Run any example with:

npx ts-node examples/<name>.ts

`Development`

pnpm --filter @sebastienrousseau/crypto-lib run build
pnpm --filter @sebastienrousseau/crypto-lib run test
pnpm --filter @sebastienrousseau/crypto-lib run lint
pnpm --filter @sebastienrousseau/crypto-lib run format

All 18 packages in the Crypto Service workspace maintain a 100% coverage floor across statements, branches, functions, and lines.

`Security`

Report vulnerabilities privately via GitHub Security Advisories or according to SECURITY.md. Never report security issues publicly.

Cryptographic operations use the @noble/* libraries, Node.js crypto and OpenPGP.js. @noble/post-quantum has not been independently audited and does not guarantee constant-time execution, and no module in this suite is FIPS 140-3 validated. Key zeroization is limited: JavaScript strings and garbage-collected buffers cannot be reliably wiped. See SECURITY.md.

`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 18 packages in the workspace move in lockstep. Public API signatures, cipher output formats, and serialization schemas are strictly versioned. Breaking changes to serialized formats or algorithm defaults are considered major breaking changes. Minimum toolchain upgrades (e.g. Node.js LTS floor) are governed by POLICIES.md.

`License`

Dual-licensed under Apache 2.0 or MIT, at your option.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Contents

Install

Requirements

Quick Start

The Crypto Service ecosystem

Overview

Features

Library Usage

Examples

Development

Security

Documentation

Stability guarantees

License