@sebastienrousseau/crypto-lib

A modern cryptographic library for TypeScript, with post-quantum support, zero unsafe dependencies, and 100% test coverage.

Contents

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 14-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
Copy

Back to Top

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)

Back to Top

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

Back to Top

The Crypto Service ecosystem

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

Back to Top

Overview

crypto-lib is the core cryptographic engine of the Crypto Service Suite. It provides a unified TypeScript API over the audited @noble/hashes, @noble/curves, @noble/ciphers, and @noble/post-quantum libraries -- pure TypeScript, zero native add-ons, no C bindings. 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.

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

Back to Top

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

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

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

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

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
Copy

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

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

Back to Top

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

npx ts-node examples/<name>.ts
Copy

Back to Top

Back to Top

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
Copy

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

Back to Top

Security

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

All cryptographic operations leverage audited primitives, enforce constant-time execution where applicable, and zero sensitive key material upon disposal.

Back to Top

Documentation

• Full Suite Documentation
• API Reference (TypeDoc)
• Developer Guide
• Security Policy
• Architecture & Design

Back to Top

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 14 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

License

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