@sebastienrousseau/crypto-lib 0.0.3 → 0.0.8

package/README.md

@@ -1,373 +1,363 @@
-# ⚙️ Crypto Lib
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
 
-![Banner representing Crypto Lib](https://raw.githubusercontent.com/sebastienrousseau/crypto-service/master/assets/crypto-lib-logo.svg)
-
-[![NPM Version](https://img.shields.io/npm/v/solid-js.svg?style=for-the-badge)](https://www.npmjs.com/package/@sebastienrousseau/crypto-lib)
-[![Coverage Status](https://img.shields.io/coveralls/github/sebastienrousseau/crypto-service/solid.svg?branch=main&style=for-the-badge\&color=blueviolet)](https://coveralls.io/github/sebastienrousseau/crypto-service?branch=main)
-[![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)
-
-**[Website](https://cryptolib.io) • [Documentation](https://cryptolib.io/docs/) 
-• [Submit an Issue](https://github.com/sebastienrousseau/crypto-service/issues) 
-• [Contributing Guidelines](https://github.com/sebastienrousseau/crypto-service/blob/master/.github/CONTRIBUTING.md)**
-
-***
-
-## 👋 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.
-
-![divider][divider]
-
-## ✨ Key Features
-
-The cryptographic operations include:
-
-- Authentication via Digital Signature,
-- Confidentiality via Encryption and Decryption,
-- Compression,
-- 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].
-
-![divider][divider]
-
-## ⏩ Getting Started
-
-👉 Note: » 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.
-
-This allows you to always be on the latest version when we release new builds
-with automatic upgrades.
-
-![divider][divider]
-
-## 🔧 Installation
-
-1️⃣ Install the Crypto Library via  [`npm`][8], [`yarn`][9] or [`pnpm`][10]
-package managers:
-
-- `npm i @sebastienrousseau/crypto-lib`
-- `yarn add @sebastienrousseau/crypto-lib`
-- `pnpm add @sebastienrousseau/crypto-lib`
-
-For users who are unable to install the Crypto Lib, released builds can be 
-manually downloaded from this repository's
-[Releases page](https://github.com/sebastienrousseau/crypto-service/releases/).
-
-### 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
-.
-├── COPYRIGHT
-├── Makefile
-├── Report.txt
-├── bin
-│   ├── crypto-lib.d.ts
-│   ├── crypto-lib.d.ts.map
-│   ├── crypto-lib.js
-│   ├── crypto-lib.js.map
-│   ├── cryptolib.d.ts
-│   ├── cryptolib.d.ts.map
-│   ├── cryptolib.js
-│   └── cryptolib.js.map
-├── config
-│   ├── config.d.ts
-│   ├── config.d.ts.map
-│   ├── config.js
-│   └── config.js.map
-├── enums.d.ts
-├── enums.d.ts.map
-├── enums.js
-├── enums.js.map
-├── index.d.ts
-├── index.d.ts.map
-├── index.js
-├── index.js.map
-├── key
-│   ├── key.d.ts
-│   ├── key.d.ts.map
-│   ├── key.js
-│   └── key.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
-│   ├── generateSessionKey.d.ts
-│   ├── generateSessionKey.d.ts.map
-│   ├── generateSessionKey.js
-│   ├── generateSessionKey.js.map
-│   ├── index.d.ts
-│   ├── index.d.ts.map
-│   ├── index.js
-│   ├── index.js.map
-│   ├── reformat.d.ts
-│   ├── reformat.d.ts.map
-│   ├── reformat.js
-│   ├── reformat.js.map
-│   ├── revoke.d.ts
-│   ├── revoke.d.ts.map
-│   ├── revoke.js
-│   ├── revoke.js.map
-│   ├── session.d.ts
-│   ├── session.d.ts.map
-│   ├── session.js
-│   ├── session.js.map
-│   ├── sign.d.ts
-│   ├── sign.d.ts.map
-│   ├── sign.js
-│   ├── sign.js.map
-│   ├── verify.d.ts
-│   ├── verify.d.ts.map
-│   ├── verify.js
-│   └── verify.js.map
-├── package.json
-└── types
-    ├── types.d.ts
-    ├── types.d.ts.map
-    ├── types.js
-    └── types.js.map
-
-5 directories, 72 files
+<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**
 
-2️⃣ Set up your app
+- [The Crypto Service ecosystem](#the-crypto-service-ecosystem) — full 14-package suite overview
 
-You can get started with a simple app by running the following in your terminal:
+**Package reference**
 
-```shell
-> mkdir my-app
-> cd my-app
-> yarn add @sebastienrousseau/crypto-lib -D # or yarn or pnpm
-> yarn start \
---name "Jane Doe" \
---email "jane@doe.com" \
---passphrase "123456789abcdef" \
---type "rsa" \
---curve "" \
---bits 2048 \
---expiration 0 \
---format armored \
+- [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
 ```
 
-3️⃣ Try it out and let us know what you think!
+<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)
 
-![divider][divider]
+<p align="right"><a href="#contents">Back to Top</a></p>
 
-## ❯ Crypto Lib commands
+---
 
-The Crypto Lib accepts multiple types of options. Options are a list of flags
-and other parameters that can control the behavior of the Crypto Lib as a whole.
+## Quick Start
 
-Below is the full list of supported options for the Crypto Lib.
+```ts
+import { crypto } from "@sebastienrousseau/crypto-lib";
 
-### Generating a new RSA key pair
+// Generate a random 256-bit key
+const key = crypto.randomKey();
 
-[RSA][11] is a public-key algorithm for encrypting and signing messages. To
-generate a Rivest-Shamir-Adelman (RSA) public key pair:
+// Encrypt (XChaCha20-Poly1305 via secretbox)
+const ciphertext = crypto.encrypt(key, "classified payload");
 
--   Open Terminal for Mac or Command Prompt for Windows,
+// Decrypt
+const plaintext = crypto.decrypt(key, ciphertext);
+console.log(Buffer.from(plaintext).toString("utf8"));
+// => "classified payload"
 
--   Enter the following example command that will start the generation process
-in the `dist/` directory.
+// Hash
+const digest = crypto.hash("sha3-256", "hello world");
 
-```js
-yarn start \
-  --name "Jane Doe" \
-  --email "jane@doe.com" \
-  --passphrase "123456789abcdef" \
-  --type "rsa" \
-  --curve "" \
-  --bits 2048 \
-  --expiration 0 \
-  --format armored \
-  --sign true
+// 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);
 ```
 
-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
+<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
 ```
 
-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>Signing</b></summary>
 
-### Encrypting and Signing Data
+```ts
+import { crypto } 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 kp = crypto.generateKeyPair("ed25519");
+const sig = crypto.sign("ed25519", kp.privateKey, "payload");
+const ok = crypto.verify("ed25519", kp.publicKey, "payload", sig);
+```
+
+</details>
 
-Crypto Lib makes it easy and painless to encrypt and sign data.
+<details>
+<summary><b>Symmetric Encryption</b></summary>
 
-To encrypt a message:
+```ts
+import { aeadEncrypt, aeadDecrypt } from "@sebastienrousseau/crypto-lib";
+
+const key = "a".repeat(64); // 32-byte hex key
+const { ciphertext } = aeadEncrypt({ key, plaintext: "secret" });
+const plain = aeadDecrypt({ key, ciphertext });
+```
 
-- Open Terminal for Mac or Command Prompt for Windows,
+</details>
 
-- Run the yarn start
+<details>
+<summary><b>Post-Quantum KEM</b></summary>
 
-- Enter the following example command that will start the encryption process
-in the `dist/` directory.
+```ts
+import {
+  mlKemKeygen,
+  mlKemEncapsulate,
+  mlKemDecapsulate,
+} from "@sebastienrousseau/crypto-lib";
 
-```js
-node dist/lib/encrypt.js \
-  --passphrase '123456789abcdef' \
-  --message 'Hello Crypto Service Suite APIs!'
+const kp = mlKemKeygen(768);
+const { ciphertext, sharedSecret: ss1 } = mlKemEncapsulate(768, kp.publicKey);
+const { sharedSecret: ss2 } = mlKemDecapsulate(768, kp.secretKey, ciphertext);
+// ss1 === ss2
 ```
 
-***
+</details>
+
+<details>
+<summary><b>Password Hashing</b></summary>
+
+```ts
+import { hashPassword, verifyPasswordPhc } from "@sebastienrousseau/crypto-lib";
+
+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 });
+```
 
-### Decrypting and Verifying Signatures
+</details>
 
-Decryption restores encrypted data to to its original (cleartext or plaintext)
-form. Decrypting data and verifying signatures is being done similarly in Crypto
-Lib.
+<details>
+<summary><b>Keyring</b></summary>
 
-To decrypt a message:
+```ts
+import { Keyring } from "@sebastienrousseau/crypto-lib";
 
--   Open Terminal for Mac or Command Prompt for Windows,
--   Enter the following example command that will start the decryption process
-in the `dist/` directory.
+const ring = new Keyring();
+const key = ring.add("ed25519", { use: "sig" });
+const rotated = ring.rotate(key.kid);
+const jwks = ring.toJwks();
+```
+
+</details>
+
+<p align="right"><a href="#contents">Back to Top</a></p>
+
+## Examples
+
+All examples are self-contained TypeScript files in the `examples/`
+directory. Run any example with:
+
+```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
 ```
 
-![divider][divider]
+All 18 packages in the Crypto Service workspace maintain a **100% coverage floor** across statements, branches, functions, and lines.
 
-## 🚥 Semantic Versioning Policy
+<p align="right"><a href="#contents">Back to Top</a></p>
 
-For transparency into our release cycle and in striving to maintain backward
-compatibility, `crypto-lib` follows [semantic versioning](http://semver.org/)
-and [ESLint's Semantic Versioning Policy](https://github.com/eslint/eslint#semantic-versioning-policy).
+---
 
-![divider][divider]
+## Security
 
-## ✅ Changelog
+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.
 
-- [GitHub Releases](https://github.com/sebastienrousseau/crypto-service/releases)
+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).
 
-![divider][divider]
+<p align="right"><a href="#contents">Back to Top</a></p>
 
-## ❤️ Contributing
+---
 
-Thank you for using Crypto Lib! If you like the library, it would be great if
-you can give it a star ⭐ on [GitHub][5].
+## Documentation
 
-There are also many ways in which you can participate in this project, for
-example:
+- [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)
 
-* [Submit bugs and feature requests](https://github.com/sebastienrousseau/crypto-service/issues/new), and help us verify as they are checked in,
-* Review [source code changes](https://github.com/sebastienrousseau/crypto-service/pulls), and help us improve our code quality,
-* Review the [documentation](https://github.com/sebastienrousseau/crypto-service/docs) and make pull requests for anything from typos to additional and new content.
+<p align="right"><a href="#contents">Back to Top</a></p>
 
-![divider][divider]
+---
 
-## 🥂 License
+## Stability guarantees
 
-Copyright (c) Sebastien Rousseau. All rights reserved.
+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.
 
-Licensed under the [MIT](LICENSE) license.
+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).
 
-![divider][divider]
+<p align="right"><a href="#contents">Back to Top</a></p>
 
-## 🏢 Acknowledgements
+---
 
-[Crypto Service Suite](https://crypto-service.co) is beautifully crafted by these
-people and a bunch of awesome [contributors](https://github.com/sebastienrousseau/crypto-service/graphs/contributors).
+## License
 
-| Contributors |
-|---------|
-|[![Sebastien Rousseau](https://avatars0.githubusercontent.com/u/1394998?s=117)](https://sebastienrousseau.co.uk)|
-|[Sebastien Rousseau](https://github.com/sebastienrousseau)|
+Dual-licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) or [MIT](https://opensource.org/licenses/MIT), at your option.
 
-[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
-[divider]: https://raw.githubusercontent.com/sebastienrousseau/crypto-service/master/assets/divider.svg
-[getting started]: https://raw.githubusercontent.com/sebastienrousseau/crypto-service/master/assets/button-primary.svg 
-[download]: https://raw.githubusercontent.com/sebastienrousseau/crypto-service/master/assets/button-secondary.svg 
+Copyright (c) 2022-2026 Sebastien Rousseau and The Crypto Service Suite contributors.
 
+<p align="right"><a href="#contents">Back to Top</a></p>