@sebastienrousseau/crypto-wasm

v0.0.32

Published

5 days ago

WebAssembly performance accelerator for crypto-lib — near-native speed for heavy cryptographic operations.

0High
0Medium
0Low

sebastienrousseau

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

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 {
  WasmAccelerator,
  isWasmSupported,
} from "@sebastienrousseau/crypto-wasm";

const accel = new WasmAccelerator();
await accel.init();

// Hash data -- uses WASM when available, JS fallback otherwise
const digest = await accel.hash("sha256", new TextEncoder().encode("hello"));
console.log(Buffer.from(digest).toString("hex"));

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-cli | Terminal CLI | An interactive command-line interface for cryptographic operations, supporting both legacy OpenPGP and modern post-quantum algorithms. | | @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 Key Management Service interface for AWS KMS, GCP Cloud KMS, Azure Key Vault, and HashiCorp Vault. | | @sebastienrousseau/crypto-lib | Core Library | A modern cryptographic library for TypeScript, with post-quantum support, zero unsafe dependencies, and 100% test coverage. | | @sebastienrousseau/crypto-middleware | Middleware | Framework-agnostic cryptographic middleware for Express, Fastify, and Koa applications. | | @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 (this package) | Acceleration | WebAssembly performance accelerator for crypto-lib |

Overview

crypto-wasm is an optional performance accelerator for the Crypto Service Suite. When installed alongside crypto-lib, heavy cryptographic operations are automatically routed through a WebAssembly module compiled from Rust, delivering near-native speed for hashing, AES-GCM encryption, Argon2 password hashing, and Ed25519/X25519 operations. If the WASM module is unavailable, every operation transparently falls back to the equivalent pure-JavaScript implementation.

How It Works

Auto-Detection

When crypto-lib detects @sebastienrousseau/crypto-wasm as an installed dependency, it automatically routes heavy cryptographic operations through the WASM module. No configuration is needed.

crypto-lib  -->  crypto-wasm installed?
                   |               |
                  YES              NO
                   |               |
              WASM path       JS fallback
              (near-native)   (pure JS)

Transparent Fallback

If the WASM module is not compiled or not available in the current runtime, every operation falls back to the equivalent pure-JavaScript implementation. Your application code does not need to handle either case differently.

Runtime Detection

import { detectCapabilities } from "@sebastienrousseau/crypto-wasm";

const caps = detectCapabilities();
// { wasmSupported: true, streamingSupported: true, simdSupported: true }

Supported Operations

Building from Source

The WASM module is compiled from Rust. A Rust toolchain with wasm32-unknown-unknown target is required.

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add the WASM target
rustup target add wasm32-unknown-unknown

# Install wasm-pack
cargo install wasm-pack

# Build the WASM module
pnpm run build:wasm

The compiled .wasm file is placed in wasm/crypto_accel.wasm.

Benchmarks

Run the built-in benchmark to compare JS and WASM performance:

import { WasmAccelerator } from "@sebastienrousseau/crypto-wasm";

const accel = new WasmAccelerator();
await accel.init();

const result = await accel.benchmark("hash-sha256", 10000);
console.log(`JS:      ${result.jsTimeMs.toFixed(2)} ms`);
console.log(`WASM:    ${result.wasmTimeMs.toFixed(2)} ms`);
console.log(`Speedup: ${result.speedup.toFixed(2)}x`);

Expected speedups (once Rust WASM module is compiled):

| Operation | Expected Speedup | | :-------------------- | :--------------- | | SHA-256 (large input) | 2-5x | | AES-GCM | 3-8x | | Argon2 | 5-15x | | Ed25519 Sign | 2-4x | | Ed25519 Verify | 2-4x | | X25519 | 2-4x |

Examples

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

npx ts-node examples/<name>.ts

Development

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

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.