@sebastienrousseau/crypto-lib 0.0.2 → 0.0.8

package/README.md

@@ -1,214 +1,363 @@
-# Crypto Lib
-
-![Banner representing Crypto Lib](https://raw.githubusercontent.com/sebastienrousseau/crypto-service/master/assets/crypto-lib-logo.svg)
-
-[![Maintained with Lerna](https://img.shields.io/badge/maintained%20with-lerna-blue?style=for-the-badge)](https://lerna.js.org/)
-[![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge&logo=)](https://opensource.org/licenses/MIT)
-![Made with Love](https://raw.githubusercontent.com/sebastienrousseau/crypto-service/master/assets/made-with-love.svg)
-
-***
-
-## Welcome to Crypto Lib
-
-Crypto Lib is a powerful intuitive cryptographic JavaScript library that
-encapsulates common algorithms, functions and provides an interface for
-low-level cryptographic operations.
-
-The cryptographic operations include:
-
-- Digital Signing,
-- Encryption and Decryption,
-- Key Generation,
-- Key Management,
-- Pseudorandom Number Generation,
-- Signature Verification.
-
-This library is based on [OpenPGP.js][1] - a JavaScript implementation of the
-OpenPGP protocol. It implements [RFC4880][2] and parts of [RFC4880bis][3].
-
-Development of this library is hosted by [GitHub][4] at the [following page][5].
-Source code is available to everyone under the standard [MIT license][6].
-
-## Getting Started
-
-Crypto Lib is a [Node.js][7] module available through the
-[npm registry][8]. Before installing, [download and install Node.js][7].
-Node.js 12.20.0 or higher is required.
-
-Installation is done using either [`npm`][8], [`yarn`][9] or [`pnpm`][10]
-package managers to use Crypto Lib with Node.js or the Command Line Interface:
-
-- `npm i @sebastienrousseau/crypto-lib`
-- `yarn add @sebastienrousseau/crypto-lib`
-- `pnpm add @sebastienrousseau/crypto-lib`
-
-## What's included
-
-Within the download you'll find all the crypto lib source files grouped into
-the *dist* folder.
-
-You'll see something like this:
-
-```shell
-.
-├── bin
-│   ├── crypto-lib.d.ts
-│   ├── crypto-lib.d.ts.map
-│   ├── crypto-lib.js
-│   └── crypto-lib.js.map
-├── index.d.ts
-├── index.d.ts.map
-├── index.js
-├── index.js.map
-└── lib
-    ├── decrypt.d.ts
-    ├── decrypt.d.ts.map
-    ├── decrypt.js
-    ├── decrypt.js.map
-    ├── encrypt.d.ts
-    ├── encrypt.d.ts.map
-    ├── encrypt.js
-    ├── encrypt.js.map
-    ├── generate.d.ts
-    ├── generate.d.ts.map
-    ├── generate.js
-    ├── generate.js.map
-    ├── revoke-key.d.ts
-    ├── revoke-key.d.ts.map
-    ├── revoke-key.js
-    └── revoke-key.js.map
-
-2 directories, 24 files
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sebastienrousseau/crypto-service/main/assets/crypto-lib-logo.svg" alt="crypto-lib logo" width="360" />
+</p>
+
+<h1 align="center">@sebastienrousseau/crypto-lib</h1>
+
+<p align="center">
+  A modern cryptographic library for TypeScript, with post-quantum support, zero unsafe dependencies, and 100% test coverage.
+</p>
+
+<p align="center">
+  <a href="https://github.com/sebastienrousseau/crypto-service/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/crypto-service/ci.yml?branch=main&style=for-the-badge&logo=github" alt="Build" /></a>
+  <a href="https://coveralls.io/github/sebastienrousseau/crypto-service?branch=main"><img src="https://img.shields.io/coveralls/github/sebastienrousseau/crypto-service?branch=main&style=for-the-badge" alt="Coverage" /></a>
+  <a href="https://www.npmjs.com/package/@sebastienrousseau/crypto-lib"><img src="https://img.shields.io/npm/v/@sebastienrousseau/crypto-lib.svg?style=for-the-badge&color=f14041&logo=npm" alt="Registry" /></a>
+  <a href="https://sebastienrousseau.github.io/crypto-service/"><img src="https://img.shields.io/badge/docs-TypeDoc-blue.svg?style=for-the-badge&labelColor=555555&logo=typescript" alt="Docs" /></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/crypto-service" title="ossf-scorecard"><img src="https://img.shields.io/badge/OpenSSF-Scorecard-blue?style=for-the-badge&logo=openssf" alt="OpenSSF Scorecard" /></a>
+  <a href="https://github.com/sebastienrousseau/crypto-service/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg?style=for-the-badge" alt="License: Apache-2.0 OR MIT" /></a>
+  <a href="https://github.com/sebastienrousseau/crypto-service/blob/main/docs/POLICIES.md"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-93450a.svg?style=for-the-badge&logo=node.js" alt="Node.js 22 or newer" /></a>
+</p>
+
+---
+
+## Contents
+
+**Getting started**
+
+- [Install](#install) — installation via pnpm, npm, or yarn
+- [Requirements](#requirements) — runtime floor and environment prerequisites
+- [Quick Start](#quick-start) — minimal working usage sample
+
+**The Crypto Service ecosystem**
+
+- [The Crypto Service ecosystem](#the-crypto-service-ecosystem) — full 14-package suite overview
+
+**Package reference**
+
+- [Reference & Usage](#overview) — features, configuration, and capabilities
+- [Examples](#examples) — runnable sample code
+
+**Operational**
+
+- [Development](#development) — build, lint, format, and test targets
+- [Security](#security) — vulnerability disclosure and cryptographic invariants
+- [Documentation](#documentation) — TypeDoc API docs and ecosystem guides
+- [Stability guarantees](#stability-guarantees) — SemVer axis and release policy
+- [License](#license)
+
+---
+
+## Install
+
+```bash
+pnpm add @sebastienrousseau/crypto-lib
+# or
+npm install @sebastienrousseau/crypto-lib
+# or
+yarn add @sebastienrousseau/crypto-lib
 ```
 
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## 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)
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
 ## Quick Start
 
-### Generating a new RSA key pair
+```ts
+import { crypto } from "@sebastienrousseau/crypto-lib";
+
+// Generate a random 256-bit key
+const key = crypto.randomKey();
+
+// Encrypt (XChaCha20-Poly1305 via secretbox)
+const ciphertext = crypto.encrypt(key, "classified payload");
+
+// Decrypt
+const plaintext = crypto.decrypt(key, ciphertext);
+console.log(Buffer.from(plaintext).toString("utf8"));
+// => "classified payload"
+
+// Hash
+const digest = crypto.hash("sha3-256", "hello world");
+
+// Sign and verify (Ed25519)
+const kp = crypto.generateKeyPair("ed25519");
+const sig = crypto.sign("ed25519", kp.privateKey, "message");
+const ok = crypto.verify("ed25519", kp.publicKey, "message", sig);
+```
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## The Crypto Service ecosystem
+
+Crypto Service provides a complete cryptography stack across 14 specialized packages:
+
+| Package                                                               | Role             | Description                                                                                                                            |
+| :-------------------------------------------------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
+| [`@sebastienrousseau/crypto-api`](../crypto-api)                      | API Schemas      | Shared TypeScript types and utilities for the Crypto Service Suite, defining the canonical API surface.                                |
+| [`@sebastienrousseau/crypto-cli`](../crypto-cli)                      | Terminal CLI     | An interactive command-line interface for cryptographic operations, supporting both legacy OpenPGP and modern post-quantum algorithms. |
+| [`@sebastienrousseau/crypto-edge`](../crypto-edge)                    | Edge Runtime     | Edge-runtime cryptographic operations using the Web Crypto API, optimized for Cloudflare Workers, Vercel Edge, and Deno.               |
+| [`@sebastienrousseau/crypto-kms`](../crypto-kms)                      | Cloud KMS        | Unified Key Management Service interface for AWS KMS, GCP Cloud KMS, Azure Key Vault, and HashiCorp Vault.                             |
+| **[`@sebastienrousseau/crypto-lib`](../crypto-lib)** _(this package)_ | **Core Library** | **A modern cryptographic library for TypeScript, with post-quantum support, zero unsafe dependencies, and 100% test coverage.**        |
+| [`@sebastienrousseau/crypto-middleware`](../crypto-middleware)        | Middleware       | Framework-agnostic cryptographic middleware for Express, Fastify, and Koa applications.                                                |
+| [`@sebastienrousseau/crypto-prisma`](../crypto-prisma)                | ORM Adapter      | Transparent field-level encryption extension for Prisma Client, using XChaCha20-Poly1305.                                              |
+| [`@sebastienrousseau/crypto-react`](../crypto-react)                  | React Hooks      | React hooks and context provider for client-side cryptographic operations with zero boilerplate.                                       |
+| [`@sebastienrousseau/crypto-sdk`](../crypto-sdk)                      | Client SDK       | A zero-dependency, typed HTTP client for the Crypto Service REST API, with full post-quantum support.                                  |
+| [`@sebastienrousseau/crypto-server`](../crypto-server)                | HTTP API         | A hardened Fastify REST API for cryptographic operations, with rate limiting, OpenAPI schemas, and post-quantum endpoints.             |
+| [`@sebastienrousseau/crypto-testing`](../crypto-testing)              | Test Support     | Deterministic keys, fast mocks, and test fixtures for crypto-lib                                                                       |
+| [`@sebastienrousseau/crypto-typeorm`](../crypto-typeorm)              | ORM Adapter      | TypeORM column-level encryption with a single decorator, powered by crypto-lib.                                                        |
+| [`@sebastienrousseau/crypto-vue`](../crypto-vue)                      | Vue Composables  | Vue 3 composables for client-side cryptography                                                                                         |
+| [`@sebastienrousseau/crypto-wasm`](../crypto-wasm)                    | Acceleration     | WebAssembly performance accelerator for crypto-lib                                                                                     |
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Overview
+
+crypto-lib is the core cryptographic engine of the Crypto Service
+Suite. It provides a unified TypeScript API over the
+`@noble/hashes`, `@noble/curves`, `@noble/ciphers`, and
+`@noble/post-quantum` libraries -- pure TypeScript, zero native
+add-ons, no C bindings. The first three have had independent audits;
+`@noble/post-quantum` has not. Post-quantum primitives (ML-KEM, ML-DSA,
+SLH-DSA) are first-class citizens, not add-ons, and hybrid
+constructions combine classical and PQ algorithms so security holds
+even if one family breaks.
+
+Two API layers serve different needs: a unified `crypto.*` namespace
+for common tasks, and granular per-module imports for full control
+and tree-shaking. Both layers use the same underlying noble
+primitives; the unified API is a thin dispatcher that adds no
+overhead.
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+## Features
+
+| Module                        | Adds                                             |
+| :---------------------------- | :----------------------------------------------- |
+| `modern/hash`                 | SHA-2, SHA-3, BLAKE2b, BLAKE3                    |
+| `modern/aead`                 | XChaCha20-Poly1305 encrypt/decrypt               |
+| `modern/aes`                  | AES-GCM, AES-GCM-SIV (128/256)                   |
+| `modern/signing`              | Ed25519 key generation, sign, verify             |
+| `modern/curves`               | P-256, P-384, Ed448, X448, Schnorr (BIP-340)     |
+| `modern/mac`                  | HMAC (SHA-2, SHA-3), KMAC-128/256                |
+| `modern/kdf`                  | scrypt, HKDF-SHA256, PBKDF2-SHA256               |
+| `modern/password`             | Argon2id/i/d hash, verify, PHC format            |
+| `modern/pq-kem`               | ML-KEM-512/768/1024, hybrid KEMs                 |
+| `modern/pq-sign`              | ML-DSA-44/65/87, hybrid signatures               |
+| `modern/pq-hash-sign`         | SLH-DSA (FIPS 205)                               |
+| `high-level/secretbox`        | Symmetric seal/open                              |
+| `high-level/sealedbox`        | Anonymous public-key encryption                  |
+| `high-level/password-encrypt` | Password-based encryption                        |
+| `high-level/key-wrap`         | AES-KW, AES-KWP, X25519-AES-KW                   |
+| `high-level/multi-recipient`  | Multi-recipient encryption                       |
+| `keys/keygen`                 | Unified key generation (12 algorithms)           |
+| `keys/serialize`              | Hex, Base64, PEM, JWK, thumbprints               |
+| `keys/keyring`                | In-memory keyring with rotation and JWKS         |
+| `streaming/stream-hash`       | Incremental hashing for large inputs             |
+| `streaming/stream-aead`       | Streaming AEAD encryption                        |
+| `protocols/pqxdh`             | Post-Quantum Extended Triple DH                  |
+| `protocols/ratchet`           | Double Ratchet (Signal-style)                    |
+| `protocols/pake`              | OPAQUE-3DH PAKE (RFC 9807)                       |
+| `protocols/threshold`         | Shamir SSS + Feldman VSS                         |
+| `registry`                    | Algorithm metadata, deprecation, recommendations |
+| `crypto`                      | Unified API namespace                            |
+| `utils`                       | `timingSafeEqual`, `SecureBuffer`                |
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+## Library Usage
+
+<details>
+<summary><b>Hashing</b></summary>
+
+```ts
+import { hash } from "@sebastienrousseau/crypto-lib";
+
+const r = hash({ algorithm: "sha3-256", data: "hello" });
+console.log(r.digest); // hex string
+```
+
+</details>
+
+<details>
+<summary><b>Signing</b></summary>
+
+```ts
+import { crypto } from "@sebastienrousseau/crypto-lib";
+
+const kp = crypto.generateKeyPair("ed25519");
+const sig = crypto.sign("ed25519", kp.privateKey, "payload");
+const ok = crypto.verify("ed25519", kp.publicKey, "payload", sig);
+```
 
-[RSA][11] is a public-key algorithm for encrypting and signing messages. To
-generate a Rivest-Shamir-Adelman (RSA) public key pair:
+</details>
 
-- Open Terminal for Mac or Command Prompt for Windows,
+<details>
+<summary><b>Symmetric Encryption</b></summary>
 
-- Enter the following example command that will start the generation process in
-the `dist/` directory.
+```ts
+import { aeadEncrypt, aeadDecrypt } from "@sebastienrousseau/crypto-lib";
 
-```js
-yarn start \
-  --name "Jane Doe" \
-  --email "jane@doe.com" \
-  --passphrase "123456789abcdef" \
-  --type "rsa" \
-  --curve "" \
-  --bits 2048 \
-  --expiration 0 \
-  --format armored \
-  --sign true
+const key = "a".repeat(64); // 32-byte hex key
+const { ciphertext } = aeadEncrypt({ key, plaintext: "secret" });
+const plain = aeadDecrypt({ key, ciphertext });
 ```
 
-This starts generating a 2048-bit RSA key pair, encrypts them with the password
-provided and writes them to a file in the [key](src/key/) directory with a pgp
-extension.
-
-***
-
-### Generating a new Elliptic-curve cryptography (ECC) key pair
-
-[Elliptic-curve cryptography (ECC)][12] is an alternative technique to RSA. It
-generates security between key pairs for public key encryption by using the
-mathematics of elliptic curves. Elliptic curve cryptography provides stronger
-security per bits of key, which allows for much faster operations.
-
-Currently the following curves are supported:
-
-| Curve           | Encryption | Signature | NodeCrypto | WebCrypto |
-|:---------------:|:----------:|:---------:|:----------:|:---------:|
-| curve25519      | ECDH       | N/A       | No         | No        |
-| ed25519         | N/A        | EdDSA     | No         | No        |
-| p256            | ECDH       | ECDSA     | Yes        | Yes       |
-| p384            | ECDH       | ECDSA     | Yes        | Yes       |
-| p521            | ECDH       | ECDSA     | Yes        | Yes       |
-| brainpoolP256r1 | ECDH       | ECDSA     | Yes        | No        |
-| brainpoolP384r1 | ECDH       | ECDSA     | Yes        | No        |
-| brainpoolP512r1 | ECDH       | ECDSA     | Yes        | No        |
-| secp256k1       | ECDH       | ECDSA     | Yes        | No        |
-
-To generate an Elliptic Curve Cryptography (ECC) key pair:
-
-- Open Terminal for Mac or Command Prompt for Windows,
-- Enter the following example command that will start the generation process in
-the `dist/` directory.
-
-```js
-yarn start \
-  --name "Jane Doe" \
-  --email "jane@doe.com" \
-  --passphrase "123456789abcdef" \
-  --type "ecc" \
-  --curve curve25519 \
-  --bits null \
-  --expiration 0 \
-  --format armored \
-  --sign true
+</details>
+
+<details>
+<summary><b>Post-Quantum KEM</b></summary>
+
+```ts
+import {
+  mlKemKeygen,
+  mlKemEncapsulate,
+  mlKemDecapsulate,
+} from "@sebastienrousseau/crypto-lib";
+
+const kp = mlKemKeygen(768);
+const { ciphertext, sharedSecret: ss1 } = mlKemEncapsulate(768, kp.publicKey);
+const { sharedSecret: ss2 } = mlKemDecapsulate(768, kp.secretKey, ciphertext);
+// ss1 === ss2
 ```
 
-This starts generating an Elliptic Curve Cryptography (ECC) key pair, encrypts
-them with the password provided and writes them to a file in the [key](src/key/)
-directory with a pgp extension.
+</details>
 
-***
+<details>
+<summary><b>Password Hashing</b></summary>
 
-### Encrypting and Signing Data
+```ts
+import { hashPassword, verifyPasswordPhc } from "@sebastienrousseau/crypto-lib";
 
-Encryption is the transformation of data into a form in which it cannot be made
-sense of without the use of some key. Such transformed data is referred to as
-`ciphertext`.
+const result = hashPassword({ password: "hunter2" });
+console.log(result.phc); // $argon2id$v=19$m=65536,t=3,p=4$...
+const { valid } = verifyPasswordPhc({ password: "hunter2", phc: result.phc });
+```
 
-Crypto Lib makes it easy and painless to encrypt and sign data.
+</details>
 
-To encrypt a message:
+<details>
+<summary><b>Keyring</b></summary>
 
-- Open Terminal for Mac or Command Prompt for Windows,
-- Run the yarn start
-- Enter the following example command that will start the encryption process in
-the `dist/` directory.
+```ts
+import { Keyring } from "@sebastienrousseau/crypto-lib";
 
-```js
-node dist/lib/encrypt.js \
-  --passphrase '123456789abcdef' \
-  --message 'Hello Crypto Service APIs!'
+const ring = new Keyring();
+const key = ring.add("ed25519", { use: "sig" });
+const rotated = ring.rotate(key.kid);
+const jwks = ring.toJwks();
 ```
 
-***
+</details>
 
-### Decrypting and Verifying Signatures
+<p align="right"><a href="#contents">Back to Top</a></p>
 
-Decryption restores encrypted data to to its original (cleartext or plaintext)
-form. Decrypting data and verifying signatures is being done similarly in Crypto
-Lib.
+## Examples
 
-To decrypt a message:
+All examples are self-contained TypeScript files in the `examples/`
+directory. Run any example with:
 
-- Open Terminal for Mac or Command Prompt for Windows,
-- Enter the following example command that will start the decryption process in
-the `dist/` directory.
+```bash
+npx ts-node examples/<name>.ts
+```
 
-```js
-node dist/lib/decrypt.js \
-  --passphrase '123456789abcdef' \
-  --message 'LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tCgp3Y0ZNQXpMNWFTdVU0RWM4QVEvL1RlZzN6bzFiMSszNW9lN3l6NDFpRS9LVlNZYUJYSEFESTNpbVJodlQKeXlRczdFc29iYTdoUUx4dFZESjEyc3ZNU25YUWk2Y1FVNXd4cGo1L3VENUFOT2ZuN0hVSkYrSExINlRNCjNBWktZNUFLRk40VUZBK0hQRy9GSHlaNVhxVzRLd0hpL3ZjVWxSejRreWJDc2VxYmZoY01hU0NJdHRKbwpmWkNOcTFZNEhiR1hBV1BQWXExV0tRZnl0RnRyWWlQODU3VE5hc21XNTJKUjVMQUZ5OFdzdnZNTmM3Z3AKQ0RFcUIyVWQwRmJSNEZOU2tvTXFhN3FScXFqS1V2ei9odU9ieVVsOW94RVpGVGNac1hwSVQ1QkE5WUtECmpvY1pVSE1hTjZkbnFJTk8rcWVBZWM4R1FjbEUxVVk0RWhNcEhjUktkZEJaY2pjaE0xbW9oaEMxb0Q4aQpUTVBlRU5XcDg0SGh3cVp1UjRNNmxUQjBqSUhZbytuMXpMbm0vRUFtcDdoc3VvSEFYY3pqSFhVYVE3M2IKOEZ5UWlENW1IMU1wWHRoWjVheXNRTklmRkY5TUdOQ1paWXExNitHSFQvbmJCTDNyUmU2dENCUUFRTnVaCksydnNQeThGZlJyYmVBR0llZHllOFZIUGJFYXNsNWF4TVBwc08yaUtjV3dNN1QvZjVaeG5FRUxWem5UeApHQnA5MHFKMUFUNGtVWVNOejYvZC9aT2JUVVV3WWdkKzdUNDdxQ3VTMjYxVlJpL0Jiblh1Z2pLRk90VlEKMEhpU1VKbTlCbGhFR2s3OWg3RGJuZmx0ZFc4dFRCNE9CdXJxUHRVaHRLS2hHL3JhYUY3YlFrVVowUktNCmQ0SllOM0sySmhBL2ovaHIySEE4ZUpWZ0NNVm9McXJyZW8xazNHbGxIWkxTd2RBQmJtaXpZL1JZd2JDUQpUeG91TW5KNjhvZmVtSHNrSW1MdGx2OUtBOElQVEY4UXp3enZRcmpNRGRtclg2V09QTGtKQ3JiV1JKbHcKV25NWlBkVGpzSzdicnVNOTByZXhLeFowSGZVL050V3BvZ251L3dOYVBHZ1NRbEZhdHZhclJFQlNEaExaCndNYVE2ZWkycUJLbXdDTGVERURlaU1BSWlSQVBad1d2R1Y2RlFWNW14V2xGdm9SaGRDeTc2TW5kWXNNTQoza1Nwb1doMVBYUWpWYWZLV2lhZHJJS2FOSllDZkY2bzE5Ty9NdlZITGFFV0tnM0lzRGtvMGdtQWZ5VE8KTngzb2dYdTV0VFpvelRyUzRUMUpsMUR3bnRZbGlrMWhINkNYK0ZGLzIzVzlHaHdTdlcreVgzZFlTeHZjCjFuMlBjVDY5QzdDTmZtcWpOT293d20wcjl6M0lWYlZ2dGk4ZFduVzNEZDVGS256d2VaUDhaZ2hudUl4SQptUzdrY0ZWTVd4d3p6SmptQjg3UGZPbmZtZ2k2b0NxbFRzMXJDRldTQVZqM3hzenFFRGRnT1B1QXcvdzQKWmZOSS9sSVhHdU1DakpKQlYzNTZCN2ExNkZacXVqK2ZtOUQwS1BYbGpjSEcydHFRTjVDbHVTUnhUZlBiCm42U3ZOZ2tkVTNGM3pYS3NxRW9iRzdzakg5WjZWZlJIZjlRcmN2ZXZHdWFIb2ZZQkROVzZmT3ZNODBURQpHNjkzS3BRdytEaDVnMzBzamhXbDRuMS9aZUROR0RYZ0dERGRUMU9WQXRrVTBTcm1vY0ZSM1hCUHprYnQKRmw3YlVkVG1oVFlHVys2VmRIUG9mOFZ0b1FrWVJma2YxK1hFaC9kNUFvTzdSSVZRQ29qb3pqTmhoVy9qCjg4VW56d0VqZ3VoK0VMbVFRS1ViUi9ydjg2djcyM0VtVkVSd3hvQTIvalZCbGVaaHpFOHdrY01HODM3VApLVlo3N0VHblRPcTBjbUkrang2Ri9SenRjbDRBUHN6eEJkUkVSM25HR3dqbGVIdjdpMndhQTYzbWNJLzcKM0I0dWZyVGczbHNMWDVlWVFDUnJrdXdwOVZKNzNlWmJiOTlLOU51ZDhNVGczNnE0cFhtNWRBd3ZLZzEwCm96c0t2MHVxa0tDclF1TFBWU1JtZkE9PQo9Yll1VQotLS0tLUVORCBQR1AgTUVTU0FHRS0tLS0tCg=='
+| Category       | Example                               | Purpose                                   |
+| :------------- | :------------------------------------ | :---------------------------------------- |
+| Hashing        | [hash.ts](examples/hash.ts)           | SHA-256, SHA-3, BLAKE3                    |
+| Encryption     | [encrypt.ts](examples/encrypt.ts)     | XChaCha20-Poly1305 encrypt/decrypt        |
+| Signing        | [sign.ts](examples/sign.ts)           | Ed25519 sign and verify                   |
+| Key Generation | [keygen.ts](examples/keygen.ts)       | Generate key pairs for various algorithms |
+| Passwords      | [password.ts](examples/password.ts)   | Argon2id hash and verify                  |
+| Secretbox      | [secretbox.ts](examples/secretbox.ts) | Symmetric authenticated encryption        |
+| Sealed Box     | [sealedbox.ts](examples/sealedbox.ts) | Anonymous public-key encryption           |
+| Keyring        | [keyring.ts](examples/keyring.ts)     | Create, rotate, and export keys           |
+| Threshold      | [threshold.ts](examples/threshold.ts) | Shamir secret sharing split/combine       |
+| PQ KEM         | [pqkem.ts](examples/pqkem.ts)         | ML-KEM-768 key encapsulation              |
+| PQ Sign        | [pqsign.ts](examples/pqsign.ts)       | ML-DSA-65 sign and verify                 |
+| HMAC           | [hmac.ts](examples/hmac.ts)           | HMAC-SHA256 compute and verify            |
+| KDF            | [kdf.ts](examples/kdf.ts)             | Key derivation with scrypt and HKDF       |
+| Streaming      | [stream.ts](examples/stream.ts)       | Incremental hashing with createHasher     |
+| Curves         | [curves.ts](examples/curves.ts)       | P-256, P-384, Ed448, Schnorr              |
+| Serialization  | [serialize.ts](examples/serialize.ts) | PEM encode/decode, JWK conversion         |
+| Hybrid KEM     | [hybrid.ts](examples/hybrid.ts)       | Hybrid post-quantum key exchange          |
+| Registry       | [registry.ts](examples/registry.ts)   | Query algorithm registry                  |
+| Unified API    | [unified.ts](examples/unified.ts)     | Unified crypto API overview               |
+| Ratchet        | [ratchet.ts](examples/ratchet.ts)     | Double Ratchet protocol demo              |
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Development
+
+```bash
+pnpm --filter @sebastienrousseau/crypto-lib run build
+pnpm --filter @sebastienrousseau/crypto-lib run test
+pnpm --filter @sebastienrousseau/crypto-lib run lint
+pnpm --filter @sebastienrousseau/crypto-lib run format
 ```
 
-[1]: https://openpgpjs.org/
-[2]: https://tools.ietf.org/html/rfc4880
-[3]: https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-10
-[4]: https://github.com
-[5]: https://github.com/sebastienrousseau/crypto-service
-[6]: https://github.com/sebastienrousseau/crypto-service/blob/main/LICENSE
-[7]: https://nodejs.org/en/
-[8]: https://www.npmjs.com/
-[9]: https://yarnpkg.com/getting-started
-[10]: https://pnpm.io/motivation
-[11]: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
-[12]: https://en.wikipedia.org/wiki/Elliptic-curve_cryptography
+All 18 packages in the Crypto Service workspace maintain a **100% coverage floor** across statements, branches, functions, and lines.
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Security
+
+Report vulnerabilities privately via [GitHub Security Advisories](https://github.com/sebastienrousseau/crypto-service/security/advisories) or according to [`SECURITY.md`](../../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`](../../SECURITY.md).
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## Documentation
+
+- [Full Suite Documentation](https://sebastienrousseau.github.io/crypto-service/)
+- [API Reference (TypeDoc)](https://sebastienrousseau.github.io/crypto-service/)
+- [Developer Guide](../../DEVELOPMENT.md)
+- [Security Policy](../../SECURITY.md)
+- [Architecture & Design](../../ARCHITECTURE.md)
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## 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](../../docs/POLICIES.md).
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+---
+
+## License
+
+Dual-licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) or [MIT](https://opensource.org/licenses/MIT), at your option.
+
+Copyright (c) 2022-2026 Sebastien Rousseau and The Crypto Service Suite contributors.
+
+<p align="right"><a href="#contents">Back to Top</a></p>

package/dist/accel/index.d.ts

@@ -0,0 +1,11 @@
+export { isWebCryptoAvailable, webCryptoAesGcmEncrypt, webCryptoAesGcmDecrypt, webCryptoHash, } from "./webcrypto-bridge";
+export type { WebCryptoHashAlgorithm, WebCryptoAesGcmEncryptOptions, WebCryptoAesGcmEncryptResult, WebCryptoAesGcmDecryptOptions, WebCryptoAesGcmDecryptResult, WebCryptoHashOptions, WebCryptoHashResult, } from "./webcrypto-bridge";
+export { WorkerPool } from "./worker-pool";
+export type { WorkerPoolOptions, WorkerTask } from "./worker-pool";
+export { detectWasmBackend, wasmHash, wasmAeadEncrypt, wasmAeadDecrypt, _resetWasmDetection, } from "./wasm-bridge";
+export type { WasmBackend, WasmHashAlgorithm, WasmHashOptions, WasmHashResult, WasmAeadEncryptOptions, WasmAeadEncryptResult, WasmAeadDecryptResult, } from "./wasm-bridge";
+export { hasNativePqc, resetNativePqcCache, _forceNativePqcDetected, pqcBackend, bridgedMlKemKeygen, bridgedMlKemEncapsulate, bridgedMlKemDecapsulate, } from "./native-pqc-bridge";
+export type { PqcBackend, NativeMlKemLevel, BridgedMlKemKeygenResult, BridgedMlKemEncapsulateResult, } from "./native-pqc-bridge";
+export { detectModernWebCrypto, _resetModernWebCryptoDetection, modernChaCha20Encrypt, modernChaCha20Decrypt, modernSha3Hash, } from "./webcrypto-modern";
+export type { WebCryptoModernSupport, ModernSha3Algorithm, ModernChaCha20EncryptOptions, ModernAeadResult, ModernChaCha20DecryptOptions, ModernChaCha20DecryptResult, ModernSha3HashOptions, ModernSha3HashResult, } from "./webcrypto-modern";
+//# sourceMappingURL=index.d.ts.map

package/dist/accel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/accel/index.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,sBAAsB,EACtB,6BAA6B,EAC7B,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEnE,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,eAAe,EACf,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,EACV,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAC9B,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,sBAAsB,EACtB,mBAAmB,EACnB,4BAA4B,EAC5B,gBAAgB,EAChB,4BAA4B,EAC5B,2BAA2B,EAC3B,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC"}

package/dist/accel/index.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modernSha3Hash = exports.modernChaCha20Decrypt = exports.modernChaCha20Encrypt = exports._resetModernWebCryptoDetection = exports.detectModernWebCrypto = exports.bridgedMlKemDecapsulate = exports.bridgedMlKemEncapsulate = exports.bridgedMlKemKeygen = exports.pqcBackend = exports._forceNativePqcDetected = exports.resetNativePqcCache = exports.hasNativePqc = exports._resetWasmDetection = exports.wasmAeadDecrypt = exports.wasmAeadEncrypt = exports.wasmHash = exports.detectWasmBackend = exports.WorkerPool = exports.webCryptoHash = exports.webCryptoAesGcmDecrypt = exports.webCryptoAesGcmEncrypt = exports.isWebCryptoAvailable = void 0;
+var webcrypto_bridge_1 = require("./webcrypto-bridge");
+Object.defineProperty(exports, "isWebCryptoAvailable", { enumerable: true, get: function () { return webcrypto_bridge_1.isWebCryptoAvailable; } });
+Object.defineProperty(exports, "webCryptoAesGcmEncrypt", { enumerable: true, get: function () { return webcrypto_bridge_1.webCryptoAesGcmEncrypt; } });
+Object.defineProperty(exports, "webCryptoAesGcmDecrypt", { enumerable: true, get: function () { return webcrypto_bridge_1.webCryptoAesGcmDecrypt; } });
+Object.defineProperty(exports, "webCryptoHash", { enumerable: true, get: function () { return webcrypto_bridge_1.webCryptoHash; } });
+var worker_pool_1 = require("./worker-pool");
+Object.defineProperty(exports, "WorkerPool", { enumerable: true, get: function () { return worker_pool_1.WorkerPool; } });
+var wasm_bridge_1 = require("./wasm-bridge");
+Object.defineProperty(exports, "detectWasmBackend", { enumerable: true, get: function () { return wasm_bridge_1.detectWasmBackend; } });
+Object.defineProperty(exports, "wasmHash", { enumerable: true, get: function () { return wasm_bridge_1.wasmHash; } });
+Object.defineProperty(exports, "wasmAeadEncrypt", { enumerable: true, get: function () { return wasm_bridge_1.wasmAeadEncrypt; } });
+Object.defineProperty(exports, "wasmAeadDecrypt", { enumerable: true, get: function () { return wasm_bridge_1.wasmAeadDecrypt; } });
+Object.defineProperty(exports, "_resetWasmDetection", { enumerable: true, get: function () { return wasm_bridge_1._resetWasmDetection; } });
+var native_pqc_bridge_1 = require("./native-pqc-bridge");
+Object.defineProperty(exports, "hasNativePqc", { enumerable: true, get: function () { return native_pqc_bridge_1.hasNativePqc; } });
+Object.defineProperty(exports, "resetNativePqcCache", { enumerable: true, get: function () { return native_pqc_bridge_1.resetNativePqcCache; } });
+Object.defineProperty(exports, "_forceNativePqcDetected", { enumerable: true, get: function () { return native_pqc_bridge_1._forceNativePqcDetected; } });
+Object.defineProperty(exports, "pqcBackend", { enumerable: true, get: function () { return native_pqc_bridge_1.pqcBackend; } });
+Object.defineProperty(exports, "bridgedMlKemKeygen", { enumerable: true, get: function () { return native_pqc_bridge_1.bridgedMlKemKeygen; } });
+Object.defineProperty(exports, "bridgedMlKemEncapsulate", { enumerable: true, get: function () { return native_pqc_bridge_1.bridgedMlKemEncapsulate; } });
+Object.defineProperty(exports, "bridgedMlKemDecapsulate", { enumerable: true, get: function () { return native_pqc_bridge_1.bridgedMlKemDecapsulate; } });
+var webcrypto_modern_1 = require("./webcrypto-modern");
+Object.defineProperty(exports, "detectModernWebCrypto", { enumerable: true, get: function () { return webcrypto_modern_1.detectModernWebCrypto; } });
+Object.defineProperty(exports, "_resetModernWebCryptoDetection", { enumerable: true, get: function () { return webcrypto_modern_1._resetModernWebCryptoDetection; } });
+Object.defineProperty(exports, "modernChaCha20Encrypt", { enumerable: true, get: function () { return webcrypto_modern_1.modernChaCha20Encrypt; } });
+Object.defineProperty(exports, "modernChaCha20Decrypt", { enumerable: true, get: function () { return webcrypto_modern_1.modernChaCha20Decrypt; } });
+Object.defineProperty(exports, "modernSha3Hash", { enumerable: true, get: function () { return webcrypto_modern_1.modernSha3Hash; } });
+//# sourceMappingURL=index.js.map

package/dist/accel/native-pqc-bridge.d.ts

@@ -0,0 +1,18 @@
+export declare function hasNativePqc(): boolean;
+export declare function resetNativePqcCache(): void;
+export declare function _forceNativePqcDetected(value: boolean): void;
+export type PqcBackend = "native" | "noble";
+export declare function pqcBackend(): PqcBackend;
+export type NativeMlKemLevel = 512 | 768 | 1024;
+export interface BridgedMlKemKeygenResult {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+export interface BridgedMlKemEncapsulateResult {
+    cipherText: Uint8Array;
+    sharedSecret: Uint8Array;
+}
+export declare function bridgedMlKemKeygen(level: NativeMlKemLevel): BridgedMlKemKeygenResult;
+export declare function bridgedMlKemEncapsulate(level: NativeMlKemLevel, publicKey: Uint8Array): BridgedMlKemEncapsulateResult;
+export declare function bridgedMlKemDecapsulate(level: NativeMlKemLevel, cipherText: Uint8Array, secretKey: Uint8Array): Uint8Array;
+//# sourceMappingURL=native-pqc-bridge.d.ts.map

package/dist/accel/native-pqc-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-pqc-bridge.d.ts","sourceRoot":"","sources":["../../src/accel/native-pqc-bridge.ts"],"names":[],"mappings":"AA+CA,wBAAgB,YAAY,IAAI,OAAO,CActC;AAUD,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAUD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE5D;AAGD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;AAU5C,wBAAgB,UAAU,IAAI,UAAU,CAEvC;AAKD,MAAM,MAAM,gBAAgB,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC;AAGhD,MAAM,WAAW,wBAAwB;IAEvC,SAAS,EAAE,UAAU,CAAC;IAEtB,SAAS,EAAE,UAAU,CAAC;CACvB;AAGD,MAAM,WAAW,6BAA6B;IAE5C,UAAU,EAAE,UAAU,CAAC;IAEvB,YAAY,EAAE,UAAU,CAAC;CAC1B;AA0CD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,gBAAgB,GACtB,wBAAwB,CAI1B;AAmBD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,UAAU,GACpB,6BAA6B,CAI/B;AAoBD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,gBAAgB,EACvB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,UAAU,GACpB,UAAU,CAIZ"}