Crypto Service Suite

---

Contents

Getting started

• Install — pnpm, npm, yarn, source, and Docker
• Requirements — toolchain floor, platforms
• Quick Start — core encryption, hashing, and CLI usage

The Crypto Service ecosystem

• The Crypto Service ecosystem — 18 specialized packages across library, server, SDK, CLI, AI tooling, and framework adapters

Library reference

• Capabilities at a glance — the current surface by theme
• Ecosystem comparison — short matrix; full table at docs/COMPARISON.md
• Benchmarks — headline numbers; full table at docs/BENCHMARKS.md
• Features — module-level capability list
• Configuration — core options and environment variables
• Examples — runnable example index

Operational

• When not to use Crypto Service — limitations and operational boundaries
• Development — pnpm tasks, coverage, gates, and CI
• Security — guarantees and compliance
• Documentation — all reference docs
• Stability guarantees — SemVer axis, output stability, minimum toolchain discipline
• License

---

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

---

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

• User manual & guides
• API reference (TypeDoc)
• Developer guide
• Architecture
• Choosing an algorithm
• Ecosystem comparison
• Benchmarks
• Migration guide
• Security policy
• Support guide
• Changelog

---

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.