Release 1.0.0

The first stable release of fips-crypto — a high-performance post-quantum cryptography library for JavaScript and TypeScript, powered by Rust and WebAssembly. Implements all three NIST post-quantum standards: ML-KEM (FIPS 203), ML-DSA (FIPS 204), and SLH-DSA (FIPS 205). This release marks a public API commitment under semantic versioning.

This package implements the algorithm specifications in FIPS 203, FIPS 204, and FIPS 205. It is not a FIPS 140-2 or FIPS 140-3 validated cryptographic module.

What's New

• Runtime WASM integrity check: SHA-256 hash of the WASM binary is embedded in the Node.js loader at build time and verified before WebAssembly.Module instantiation, blocking tampered binaries from executing
• OIDC trusted publishing: Publish workflow migrated from long-lived NPM_TOKEN to GitHub OIDC, eliminating stored secrets
• Minimal API surface: Removed unused error codes (DECAPSULATION_FAILED, VERIFICATION_FAILED, NOT_IMPLEMENTED) for a clean 1.0.0 contract
• Quantum-safe wallet example: New examples/quantum-safe-wallet.mjs demonstrating ML-DSA signature replacement with address-to-key binding validation
• Socket.dev warning mitigated: WASM binary verified against embedded hash before instantiation, resolving filesystem-access flag

Fixed

• picomatch dev dependency updated to fix high-severity ReDoS vulnerability (CVE in transitive dep; not in published package)

Breaking Changes

• Error codes DECAPSULATION_FAILED, VERIFICATION_FAILED, and NOT_IMPLEMENTED have been removed from ErrorCodes. These were never thrown by any function — any code referencing them was already dead. TypeScript consumers will get a compile-time error if they reference the removed codes.

Full Changelog: v0.7.0...v1.0.0

Release 0.7.0

Added

• Published benchmark results in README (ops/sec for ML-KEM, ML-DSA, SLH-DSA)
• examples/ folder with 4 ready-to-run scripts: key encapsulation, digital signatures, hash-based signatures, CommonJS usage
• Node ESM distribution (dist/node-esm/) for correct WASM loading under Node.js without a bundler
• Packed-artifact smoke tests for Node ESM, CJS, and the integrity verifier CLI

Changed

• README rewritten for developer onboarding: value proposition, "Try it now" code, benchmark tables, choosing parameter sets guide, and star CTA
• Browser runtime status narrowed from "Supported" to "Compatible" (not yet CI-validated)
• fips-crypto/auto documented as working with both ESM import and CommonJS require()
• Upgraded vitest from v1 to v4 and removed vite-plugin-wasm dependency
• Dropped Node.js 18 from CI matrix (EOL April 2025; vitest v4 requires Node 20+)
• engines.node bumped to >=20.0.0
• SLH-DSA internals refactored from per-variant arrow functions to string-based WASM binding lookup, eliminating 36 closure functions and improving coverage instrumentation
• patch-wasm.cjs now patches all JS files in both pkg/ and pkg-node/, with detailed comments explaining the Socket.dev eval-risk mitigation

Fixed

• Socket.dev eval-risk false positive in pkg-node/fips_crypto_wasm.js (previously only pkg/fips_crypto_wasm_bg.js was patched)
• ESM smoke test now uses dist/node-esm/ instead of dist/esm/ (bundler target), fixing WASM load failure on Node.js in CI
• Coverage thresholds now pass under vitest v4's stricter function instrumentation

Release 0.6.0

Added

SLH-DSA (FIPS 205) - full implementation

• All 12 parameter sets: SHA2/SHAKE x 128/192/256 x fast/small
• Rust implementation (~6,000 lines): ADRS, tweakable hash (SHA-256/SHA-512/SHAKE-256), WOTS+, XMSS, FORS, hypertree, keygen/sign/verify
• 36 WASM bindings (12 parameter sets x 3 operations) via macro
• TypeScript wrappers with seed/key/signature/context validation
• Auto-init support (fips-crypto/auto)
• SLH-DSA compliance tests: 108 tests across all 6 fast variants, verified against an independent FIPS 205 implementation with 6 message scenarios each
• SLH-DSA benchmarks for fast variants

Security hardening

• ML-KEM encapsulation shared secret now uses ZeroizeOnDrop
• ML-DSA keygen intermediate buffers (xi, rho', K) explicitly zeroized before return
• ML-DSA signing intermediate buffers (k_bytes, rnd, rho'') explicitly zeroized before return
• docs/SECURITY-MODEL.md: checksum-vs-provenance threat boundary documentation
• SECURITY.md: npm provenance verification instructions (npm audit signatures)

Documentation and trust

• FIPS 205 badge in README
• "Why fips-crypto?" comparison table updated with SLH-DSA coverage
• Runtime compatibility table (Node.js, browsers, Bun, Deno)
• Auto-init promoted as the default README quick start
• Package description updated to include FIPS 205
• Restored slh-dsa, fips-205, and sphincs keywords in package.json
• Publish workflow annotated for future OIDC trusted publishing migration

Changed

• Package description now includes FIPS 205 (SLH-DSA)
• README quick start now leads with the auto-init entrypoint
• README, SECURITY, and contributor docs were updated to reflect the actual publish shape and verification flow
• README now documents SLH-DSA usage, validation scope, and the FIPS 140 disclaimer more clearly
• Package metadata now uses more precise security wording and broader npm discovery keywords
• SLH-DSA address structure fixed to match the NIST reference implementation byte layout
• SHA2 T_l uses SHA-256 for single-block F, SHA-512 for multi-block H/T_l, per FIPS 205 Section 10
• SHA2 PRF uses SHA-256 for all security levels, per FIPS 205 Section 10

Fixed

• Repaired published CommonJS loading by routing CJS wrappers to the Node-oriented WASM package
• Rebuilt dist/pkg and dist/pkg-node from fresh inputs so stale WASM artifacts no longer leak into the packed package
• Published the integrity verifier with the npm artifact and exposed it as fips-crypto-verify-integrity
• Added packed-artifact smoke coverage for local validation, CI, and the publish workflow
• Made the packed-artifact smoke script work on Windows instead of assuming POSIX npm process lookup
• Explicitly zeroized additional ML-KEM seed, derivation, and rejection buffers in the Rust core
• SLH-DSA ADRS byte layout corrected to match NIST reference offsets
• SLH-DSA set_type no longer zeroes subsequent fields
• WOTS+ checksum decomposition digit extraction order corrected to MSB-first
• SHA2 T_l no longer uses MGF1 for multi-block inputs
• SHA2 PRF changed from HMAC to SHA-256 with padding
• Corrected m for SLH-DSA-SHA2/SHAKE-128s, 192s, and 192f

Release 0.5.0

Added

ML-DSA (FIPS 204) — full implementation

• ML-DSA-44, ML-DSA-65, ML-DSA-87: key generation, signing, and verification
• Context parameter support (max 255 bytes per FIPS 204)
• Seed-based deterministic key generation (32-byte seeds)
• Rust implementation: NTT (q=8380417), polynomial arithmetic, ExpandA/ExpandS/ExpandMask/SampleInBall, FIPS 204 Algorithms 1-3
• 9 WASM bindings replacing ML-DSA stubs
• ML-DSA compliance tests using pre-generated vectors from an independent FIPS 204 implementation

Supply chain integrity

• SHA-256 checksums generated for all WASM/JS binaries at build time (checksums.sha256)
• npm run verify:integrity to verify package integrity after install
• npm publish workflow with Sigstore provenance (.github/workflows/publish.yml)

Performance benchmarks

• ML-KEM benchmark suite: keygen, encapsulate, decapsulate for all 3 variants
• ML-DSA benchmark suite: keygen, sign, verify for all 3 variants
• Performance results published in README
• Benchmark step added to CI with artifact upload

Auto-init entry point

• import from 'fips-crypto/auto' — no init() call needed, WASM loads lazily on first use
• New ./auto export in package.json

Documentation

• SECURITY.md: vulnerability reporting policy, response timelines, scope
• CONTRIBUTING.md: development setup, PR requirements, project structure
• CHANGELOG.md: backfilled history from 0.1.0 to present
• docs/SECURITY-MODEL.md: threat model, constant-time analysis, zeroization boundaries, RNG, honest limitations
• FIPS 140 vs FIPS 203/204 compliance disclaimer in README
• "Why fips-crypto?" comparison table in README
• Framework integration patterns (Express, Next.js) for init()
• Subpackage import documentation for tree-shaking
• FIPS 204 badge

Testing

• Property-based tests with fast-check for ML-KEM
• Concurrent initialization safety for init() / initMlKem() / initMlDsa()
• Safeguard tests: cross-algorithm isolation, boundary values, API contract regression
• Script tests: checksum generation/verification, WASM patch, tamper detection
• Auto-init entry point tests
• 567 total tests (up from 324 in 0.4.0), 100% statement/function/line coverage

Changed

• Package description updated to accurately reflect implemented algorithms (removed premature FIPS 205 claim)
• Coverage thresholds raised to 99/99/97/99 (statements/functions/branches/lines)
• Build scripts use shx for cross-platform compatibility (Windows/macOS/Linux)
• README restructured for npm conversion: value proposition first, benchmark data, comparison table
• JSDoc @example tags added to all 6 algorithm exports

Fixed

• ML-DSA-65 signature size corrected from 3293 to 3309 bytes per FIPS 204
• Seed length validation added to ML-KEM keygen (64 bytes) and encapsulate (32 bytes)
• Post-build patch for Socket.dev false-positive eval detection in wasm-bindgen output

Release 0.4.0

Security

• Seed length validation — keygen() now rejects seeds that are not exactly 64 bytes, and encapsulate() rejects seeds that are not exactly 32 bytes, throwing INVALID_SEED_LENGTH. Previously, invalid seed lengths were passed through to WASM unchecked.
• Socket.dev eval mitigation — Post-build patch rewrites wasm-bindgen's debugString output to avoid a false-positive dynamic code execution flag.

Improvements

• Concurrent initialization safety — init() / initMlKem() now shares a single promise when called concurrently, preventing duplicate WASM loading. Failed attempts reset properly so retries work.
• Cross-platform build scripts — Added shx for cross-platform cp/rm in npm scripts. Builds now work on Windows (cmd.exe), macOS, and Linux.
• Windows build documentation — Added Windows-specific instructions for Rust installation and nvm-windows to "Building from Source".

CI/CD

• Cross-platform CI matrix — Tests now run on Ubuntu, macOS, and Windows with Node.js 18, 20, and 22.
• Vitest crypto polyfill — Added vitest.setup.ts to ensure globalThis.crypto is available in v8 coverage workers on all platforms.

Testing

• Property-based tests — Added randomized tests with fast-check verifying roundtrip correctness, determinism, and seed rejection for arbitrary inputs.
• WASM init failure tests — New test file covering the WASM load error path via mocked imports.
• Coverage raised to 100/100/98.75/100 (statements/functions/branches/lines). Thresholds updated from 80% to 99/99/98/99%.
• 381 tests (up from 324 in v0.3.0).

Tooling

• ESLint configuration — Added .eslintrc.json with @typescript-eslint parser and plugin.
• Rust edition 2024 — Updated from 2021.

Release 0.3.0

What's New

License Change

• Changed from GPL-3.0 to MIT License for broader adoption and compatibility

CI & Code Quality

• Added GitHub Actions CI with parallel Rust and JavaScript test jobs
• Integrated Codecov for automated code coverage tracking
• Achieved 99.6% code coverage (100% function coverage)

Documentation

• Added FIPS 203 algorithm references (Algorithms 7–18) throughout the Rust source code
• Cleaned up README: removed outdated project structure, added CI/coverage/FIPS badges
• Changed "Author" to "Major Contributors" for future collaboration

Tests

• Added 27 new Rust tests: NTT linearity, basemul commutativity, Barrett reduction edge cases, keygen structure validation,
  constant-time operation verification, and more
• Added 18 new JS input validation tests covering all three parameter sets
• Added FIPS 203 KAT vector compliance tests verified against an independent implementation
• Added stress tests: repeated encapsulation uniqueness, implicit rejection, seed edge cases

Packaging Fix

• Fixed npm package to correctly include WASM binaries (dist/pkg/)
• Previous versions (0.1.0–0.2.1) were missing the WASM module and non-functional

Upgrading

npm install fips-crypto@0.3.0

No API changes from v0.2.x. Drop-in upgrade.

Full Changelog

https://github.com/fzheng/fips-crypto/compare/v0.2.2...v0.3.0

Release 0.2.2

Post-quantum cryptography library for JavaScript/TypeScript implementing NIST FIPS 203 (ML-KEM).

Built with Rust and WebAssembly for high performance in both Node.js and browser environments.

Highlights

• ML-KEM-512, ML-KEM-768, ML-KEM-1024 — all three FIPS 203 parameter sets, fully functional
• Rust + WebAssembly core for near-native performance
• 374 tests (68 Rust + 306 JavaScript) including FIPS 203 KAT vector compliance verification
• Implicit rejection (CCA security) and constant-time operations for side-channel resistance
• Deterministic key generation with optional seed for reproducible testing

Quick Start

npm install fips-crypto

import { init, ml_kem768 } from 'fips-crypto';

await init();

const { publicKey, secretKey } = await ml_kem768.keygen();
const { ciphertext, sharedSecret } = await ml_kem768.encapsulate(publicKey);
const recovered = await ml_kem768.decapsulate(secretKey, ciphertext);
// sharedSecret and recovered are identical 32-byte keys

Algorithm Parameters (FIPS 203)

┌───────────────┬──────────┬────────────┬────────────┬────────────┬───────────────┐
│ Parameter Set │ Security │ Public Key │ Secret Key │ Ciphertext │ Shared Secret │
├───────────────┼──────────┼────────────┼────────────┼────────────┼───────────────┤
│ ML-KEM-512    │ Cat. 1   │ 800 B      │ 1,632 B    │ 768 B      │ 32 B          │
├───────────────┼──────────┼────────────┼────────────┼────────────┼───────────────┤
│ ML-KEM-768    │ Cat. 3   │ 1,184 B    │ 2,400 B    │ 1,088 B    │ 32 B          │
├───────────────┼──────────┼────────────┼────────────┼────────────┼───────────────┤
│ ML-KEM-1024   │ Cat. 5   │ 1,568 B    │ 3,168 B    │ 1,568 B    │ 32 B          │
└───────────────┴──────────┴────────────┴────────────┴────────────┴───────────────┘

What's Inside

- Rust implementation of NTT, polynomial arithmetic, SHA-3/SHAKE, and the full ML-KEM key encapsulation mechanism
- TypeScript/JavaScript API with ESM and CommonJS support
- FIPS 203 algorithm references (Algorithms 7-18) documented in source code
- Known Answer Test vectors verified against an independent FIPS 203 implementation

Requirements

- Node.js 18+ with --experimental-wasm-modules flag
- Or any bundler (Vite, Webpack, etc.) for browser/bundled Node.js usage

License

GPL-3.0