Crypto MCP README

Crypto Service

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

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.

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.

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.

Ecosystem comparison

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

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)

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:

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.