Crypto Lib
    Preparing search index...

    Crypto Lib

    crypto-lib logo

    @sebastienrousseau/crypto-lib

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

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


    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

    Package reference

    Operational


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

    Back to Top


    • 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)

    Back to Top


    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);

    Back to Top


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

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

    Back to Top


    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.

    Back to Top

    Module Adds
    modern/hash SHA-2, SHA-3, BLAKE2b, BLAKE3
    modern/aead XChaCha20-Poly1305 encrypt/decrypt
    modern/aes AES-GCM, AES-GCM-SIV (128/256)
    modern/signing Ed25519 key generation, sign, verify
    modern/curves P-256, P-384, Ed448, X448, Schnorr (BIP-340)
    modern/mac HMAC (SHA-2, SHA-3), KMAC-128/256
    modern/kdf scrypt, HKDF-SHA256, PBKDF2-SHA256
    modern/password Argon2id/i/d hash, verify, PHC format
    modern/pq-kem ML-KEM-512/768/1024, hybrid KEMs
    modern/pq-sign ML-DSA-44/65/87, hybrid signatures
    modern/pq-hash-sign SLH-DSA (FIPS 205)
    high-level/secretbox Symmetric seal/open
    high-level/sealedbox Anonymous public-key encryption
    high-level/password-encrypt Password-based encryption
    high-level/key-wrap AES-KW, AES-KWP, X25519-AES-KW
    high-level/multi-recipient Multi-recipient encryption
    keys/keygen Unified key generation (12 algorithms)
    keys/serialize Hex, Base64, PEM, JWK, thumbprints
    keys/keyring In-memory keyring with rotation and JWKS
    streaming/stream-hash Incremental hashing for large inputs
    streaming/stream-aead Streaming AEAD encryption
    protocols/pqxdh Post-Quantum Extended Triple DH
    protocols/ratchet Double Ratchet (Signal-style)
    protocols/pake OPAQUE-3DH PAKE (RFC 9807)
    protocols/threshold Shamir SSS + Feldman VSS
    registry Algorithm metadata, deprecation, recommendations
    crypto Unified API namespace
    utils timingSafeEqual, SecureBuffer

    Back to Top

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

    const r = hash({ algorithm: "sha3-256", data: "hello" });
    console.log(r.digest); // hex string
    Signing
    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);
    Symmetric Encryption
    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 });
    Post-Quantum KEM
    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
    Password Hashing
    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 });
    Keyring
    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();

    Back to Top

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

    npx ts-node examples/<name>.ts
    
    Category Example Purpose
    Hashing hash.ts SHA-256, SHA-3, BLAKE3
    Encryption encrypt.ts XChaCha20-Poly1305 encrypt/decrypt
    Signing sign.ts Ed25519 sign and verify
    Key Generation keygen.ts Generate key pairs for various algorithms
    Passwords password.ts Argon2id hash and verify
    Secretbox secretbox.ts Symmetric authenticated encryption
    Sealed Box sealedbox.ts Anonymous public-key encryption
    Keyring keyring.ts Create, rotate, and export keys
    Threshold threshold.ts Shamir secret sharing split/combine
    PQ KEM pqkem.ts ML-KEM-768 key encapsulation
    PQ Sign pqsign.ts ML-DSA-65 sign and verify
    HMAC hmac.ts HMAC-SHA256 compute and verify
    KDF kdf.ts Key derivation with scrypt and HKDF
    Streaming stream.ts Incremental hashing with createHasher
    Curves curves.ts P-256, P-384, Ed448, Schnorr
    Serialization serialize.ts PEM encode/decode, JWK conversion
    Hybrid KEM hybrid.ts Hybrid post-quantum key exchange
    Registry registry.ts Query algorithm registry
    Unified API unified.ts Unified crypto API overview
    Ratchet ratchet.ts Double Ratchet protocol demo

    Back to Top

    Back to Top


    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.

    Back to Top


    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.

    Back to Top


    Back to Top


    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.

    Back to Top


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

    Copyright (c) 2022-2026 Sebastien Rousseau and The Crypto Service Suite contributors.

    Back to Top