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 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-testing
# or
npm install @sebastienrousseau/crypto-testing
# or
yarn add @sebastienrousseau/crypto-testing

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 {
  TEST_KEYS,
  TEST_VECTORS,
  mockEncrypt,
  mockDecrypt,
  createTestKeyring,
  expectValidHex,
  expectSignVerifyRoundTrip,
} from "@sebastienrousseau/crypto-testing";

// Use deterministic keys instead of generating new ones every run
const { publicKey, privateKey } = TEST_KEYS.ed25519;

// Mock encrypt/decrypt for fast unit tests
const ct = mockEncrypt(TEST_KEYS.aes256, "secret data");
const pt = mockDecrypt(TEST_KEYS.aes256, ct);

// Validate outputs
expectValidHex(publicKey, 32);

// Full sign/verify round-trip with real crypto-lib
expectSignVerifyRoundTrip("ed25519");

The Crypto Service ecosystem

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

| Package | Role | Description | | :------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------- | :----------------------------------------------------------------------------------------------------------------------------- | | @sebastienrousseau/crypto-api | API Schemas | Shared TypeScript types and utilities for the Crypto Service Suite, defining the canonical API surface. | | @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 and local providers implemented; GCP, Azure and Vault are stubs. | | @sebastienrousseau/crypto-lib | 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 (this package) | 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. |

Overview

crypto-testing is the test utility package for the Crypto Service Suite. It provides pre-generated deterministic keys, instant XOR-based mock functions for expensive crypto operations, one-call fixture generators, and assertion helpers for hex, Base64, key-pair, and round-trip validations. Use it to make your CI/CD pipeline fast and reproducible without sacrificing coverage.

Features

| Category | What you get | | :------------- | :---------------------------------------------------------------------------- | | Keys | Pre-generated Ed25519, X25519, P-256, AES-256, and HMAC key pairs/keys | | Vectors | Known plaintext with expected SHA-256, SHA3-256, and BLAKE3 digests | | Mocks | Instant XOR-based fakes for encrypt, decrypt, sign, verify, password hashing | | Fixtures | One-call generators for keyrings, encrypted messages, signed messages, hashes | | Assertions | Hex, Base64, key-pair, encrypt/decrypt, and sign/verify round-trip helpers |

Deterministic Keys

TEST_KEYS provides well-known key pairs that never change between runs:

| Key | Algorithm | Description | | :-------- | :-------- | :------------------------------- | | ed25519 | Ed25519 | 32-byte signing key pair | | x25519 | X25519 | 32-byte key-exchange pair | | p256 | P-256 | ECDSA signing key pair | | aes256 | AES-256 | 32-byte symmetric encryption key | | hmacKey | HMAC | 32-byte HMAC key |

TEST_VECTORS includes a known plaintext and its expected hashes.

Mock Functions

Replace expensive crypto operations with instant, deterministic fakes:

| Function | Replaces | Speed | | :-------------------- | :----------------------- | :-------- | | mockHashPassword | Argon2id (100+ ms) | < 0.01 ms | | mockGenerateKeyPair | Real key generation | < 0.01 ms | | mockEncrypt | XChaCha20-Poly1305 | < 0.01 ms | | mockDecrypt | XChaCha20-Poly1305 | < 0.01 ms | | mockSign | Ed25519/ECDSA signatures | < 0.01 ms | | mockVerify | Signature verification | < 0.01 ms |

All mock functions use XOR internally -- they are not cryptographically secure but are deterministic and round-trip correctly.

Fixtures

Fixture generators produce complete test data structures in one call:

| Function | Returns | | :----------------------------- | :-------------------------------------------------------------- | | createTestKeyring() | Keyring with signing, exchange, ECDSA, symmetric, and HMAC keys | | createTestEncryptedMessage() | Key + plaintext + mock ciphertext | | createTestSignedMessage() | Key pair + message + mock signature | | createTestPasswordHash() | Hash + salt + params + PHC string |

Assertion Helpers

One-liner assertions that throw descriptive errors on failure:

| Helper | Checks | | :------------------------------ | :------------------------------------- | | expectValidHex(value, len?) | Valid hex string, optional byte length | | expectValidBase64(value) | Valid Base64 string with round-trip | | expectKeyPair(kp) | Non-empty hex keys, pub != priv | | expectEncryptDecryptRoundTrip | Real secretbox encrypt then decrypt | | expectSignVerifyRoundTrip | Real keygen, sign, and verify |

Examples

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

npx ts-node examples/<name>.ts

| Category | Example | Purpose | | :--------- | :-------------------------------------- | :---------------------------------- | | Keys | keys.ts | Using deterministic test keys | | Mocks | mocks.ts | Mocking crypto operations for speed | | Fixtures | fixtures.ts | Using pre-built test fixtures | | Assertions | assertions.ts | Assertion helpers in tests |

Development

pnpm --filter @sebastienrousseau/crypto-testing run build
pnpm --filter @sebastienrousseau/crypto-testing run test
pnpm --filter @sebastienrousseau/crypto-testing run lint
pnpm --filter @sebastienrousseau/crypto-testing 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

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

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.

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