@f0rest8/metamorphic-crypto 0.3.3 → 0.3.4

package/README.md

@@ -1,113 +1,166 @@
-# metamorphic-crypto
+# @f0rest8/metamorphic-crypto
 
-Zero-knowledge end-to-end encryption library with post-quantum hybrid KEM.
+Zero-knowledge end-to-end encryption with post-quantum hybrid KEM (ML-KEM-768/1024 + X25519).
 
 Built for [Metamorphic](https://metamorphic.app) and [Mosslet](https://mosslet.com) — privacy-first apps by [Moss Piglet Corporation](https://mosspiglet.dev) where all user data is encrypted client-side and the server only stores opaque ciphertext.
 
-## What this provides
+This package is a WebAssembly build of the [metamorphic-crypto](https://github.com/moss-piglet/metamorphic-crypto) Rust crate.
 
-- **Secretbox** (XSalsa20-Poly1305) — symmetric authenticated encryption
-- **Sealed box** (X25519) — anonymous public-key encryption (libsodium-compatible)
-- **Hybrid PQ KEM** (ML-KEM-768 + X25519) — NIST Cat-3 post-quantum key encapsulation (default)
-- **Hybrid PQ KEM** (ML-KEM-1024 + X25519) — NIST Cat-5 post-quantum key encapsulation (opt-in)
-- **Argon2id KDF** — password-based key derivation (libsodium INTERACTIVE parameters)
-- **WASM bindings** — browser-ready via `wasm-pack`
-- **Recovery keys** — human-readable base32 encoding for key backup
+## Install
 
-## Security levels
+```bash
+npm install @f0rest8/metamorphic-crypto
+```
 
-| Level | ML-KEM | NIST Category | Equivalent | Version Tag | Default |
-|-------|--------|---------------|------------|-------------|---------|
-| Cat-3 | 768    | 3             | ~AES-192   | `0x02`      | Yes     |
-| Cat-5 | 1024   | 5             | ~AES-256   | `0x03`      | No      |
+## Quick start
 
-Both levels use the same combiner construction and X25519 classical fallback. `hybrid_open` auto-detects the level from the version tag byte — old and new ciphertext coexist seamlessly.
+```js
+import init, {
+  generateKey,
+  encryptSecretboxString,
+  decryptSecretboxToString,
+} from "@f0rest8/metamorphic-crypto";
+
+// Initialize the WASM module (required once before calling any function)
+await init();
+
+// All functions are synchronous after init() and throw on error
+const key = generateKey();
+const ciphertext = encryptSecretboxString("sensitive data", key);
+const plaintext = decryptSecretboxToString(ciphertext, key);
+// plaintext === "sensitive data"
+```
 
-## Security properties
+## API overview
 
-- `#![forbid(unsafe_code)]` — no unsafe anywhere in the crate
-- All secret key material zeroized after use
-- Constant-time MAC comparison via RustCrypto
-- OS CSPRNG via `getrandom` (no userspace PRNG)
-- Hybrid construction: both ML-KEM AND X25519 must be broken to compromise a sealed key
+All values are base64-encoded strings unless noted otherwise.
 
-## Hybrid KEM construction
+### Key derivation (Argon2id)
 
-The hybrid combiner matches the format used by [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum)'s `ml_kem768_x25519`:
+```js
+import { deriveSessionKey, generateSalt, parseSaltFromKeyHash } from "@f0rest8/metamorphic-crypto";
 
+const salt = generateSalt();                          // random 16-byte salt (base64)
+const sessionKey = deriveSessionKey(password, salt);   // 32-byte derived key (base64)
+const salt2 = parseSaltFromKeyHash("base64salt$argon2id..."); // extract salt from stored hash
 ```
-Seed expansion:  SHAKE256(seed_32) → 96 bytes [ML-KEM seed (64) || X25519 sk (32)]
-Combiner:        SHA3-256(ss_mlkem || ss_x25519 || ct_x25519 || pk_x25519 || label)
+
+### Symmetric encryption (XSalsa20-Poly1305)
+
+```js
+import {
+  generateKey,
+  encryptSecretboxString, decryptSecretboxToString,
+  encryptSecretbox, decryptSecretbox,
+} from "@f0rest8/metamorphic-crypto";
+
+const key = generateKey();
+
+// String plaintext
+const ct = encryptSecretboxString("hello", key);
+const pt = decryptSecretboxToString(ct, key); // "hello"
+
+// Binary plaintext (base64 in, base64 out)
+const ctBin = encryptSecretbox(plaintextBase64, key);
+const ptBin = decryptSecretbox(ctBin, key); // base64
 ```
 
-### Cat-3 (ML-KEM-768, default)
+### Public-key encryption (X25519 sealed box)
+
+```js
+import { generateKeyPair, boxSeal, boxSealOpen } from "@f0rest8/metamorphic-crypto";
+
+const kp = generateKeyPair(); // { publicKey, privateKey }
+const sealed = boxSeal(plaintextBase64, kp.publicKey);
+const opened = boxSealOpen(sealed, kp.publicKey, kp.privateKey); // base64
 ```
-Public key:   ML-KEM-768 ek (1184 B) || X25519 pk (32 B) = 1216 bytes
-Ciphertext:   0x02 || ML-KEM-768 ct (1088 B) || X25519 eph pk (32 B) || nonce (24 B) || secretbox ct
+
+### Hybrid PQ seal/unseal (ML-KEM + X25519)
+
+The recommended API for encrypting data to a user. Uses post-quantum hybrid encryption when a PQ public key is available, falls back to legacy X25519 sealed box otherwise. Decryption auto-detects the format.
+
+```js
+import {
+  generateKeyPair, generateHybridKeyPair,
+  sealForUser, unsealFromUser,
+} from "@f0rest8/metamorphic-crypto";
+
+// Generate keys
+const x25519 = generateKeyPair();          // { publicKey, privateKey }
+const pq = generateHybridKeyPair();         // { publicKey, secretKey } (ML-KEM-768)
+
+// Seal (encrypt) — pass both public keys
+const sealed = sealForUser(plaintextBase64, x25519.publicKey, pq.publicKey);
+
+// Unseal (decrypt) — pass both secret keys, auto-detects format
+const opened = unsealFromUser(sealed, x25519.publicKey, x25519.privateKey, pq.secretKey);
 ```
 
 ### Cat-5 (ML-KEM-1024, opt-in)
-```
-Public key:   ML-KEM-1024 ek (1568 B) || X25519 pk (32 B) = 1600 bytes
-Ciphertext:   0x03 || ML-KEM-1024 ct (1568 B) || X25519 eph pk (32 B) || nonce (24 B) || secretbox ct
-```
 
-## Targets
-
-| Target | Build | Use case |
-|--------|-------|----------|
-| Native | `cargo build` | Tests, CLI tools, Elixir NIF (`metamorphic_crypto` Hex package) |
-| WASM | `wasm-pack build --target web` | Browser (Phoenix LiveView, any SPA) |
-| iOS | UniFFI (planned) | Native Swift apps |
-| Android | UniFFI (planned) | Native Kotlin apps |
-
-## Usage
-
-```rust
-use metamorphic_crypto::{generate_key, encrypt_secretbox_string, decrypt_secretbox_to_string};
-use metamorphic_crypto::{generate_hybrid_keypair, hybrid_seal, hybrid_open};
-use metamorphic_crypto::{generate_hybrid_keypair_1024, hybrid_seal_1024};
-
-// Symmetric encryption
-let key = generate_key();
-let ciphertext = encrypt_secretbox_string("sensitive data", &key).unwrap();
-let plaintext = decrypt_secretbox_to_string(&ciphertext, &key).unwrap();
-assert_eq!(plaintext, "sensitive data");
-
-// Hybrid PQ seal (Cat-3, default)
-let kp = generate_hybrid_keypair();
-let sealed = hybrid_seal(b"context_key_bytes", &kp.public_key).unwrap();
-let opened = hybrid_open(&sealed, &kp.secret_key).unwrap();
-
-// Hybrid PQ seal (Cat-5)
-let kp5 = generate_hybrid_keypair_1024();
-let sealed5 = hybrid_seal_1024(b"context_key_bytes", &kp5.public_key).unwrap();
-let opened5 = hybrid_open(&sealed5, &kp5.secret_key).unwrap(); // auto-detects level
+```js
+import { generateHybridKeyPair1024, sealForUserWithLevel } from "@f0rest8/metamorphic-crypto";
+
+const pq5 = generateHybridKeyPair1024();  // { publicKey, secretKey } (ML-KEM-1024)
+const sealed = sealForUserWithLevel(plaintextBase64, x25519.publicKey, pq5.publicKey, "cat5");
+// unsealFromUser auto-detects Cat-3 vs Cat-5, no level param needed
 ```
 
-## WASM (browser)
+### Private key management
 
-```bash
-wasm-pack build --target web --release
+```js
+import { encryptPrivateKey, decryptPrivateKey } from "@f0rest8/metamorphic-crypto";
+
+const encrypted = encryptPrivateKey(privateKeyBase64, sessionKeyBase64);
+const decrypted = decryptPrivateKey(encrypted, sessionKeyBase64);
 ```
 
+### Recovery keys
+
 ```js
-import init, { deriveSessionKey, encryptSecretboxString } from './pkg/metamorphic_crypto.js';
+import {
+  generateRecoveryKey, recoveryKeyToSecret,
+  encryptPrivateKeyForRecovery, decryptPrivateKeyWithRecovery,
+} from "@f0rest8/metamorphic-crypto";
+
+const rk = generateRecoveryKey(); // { recoveryKey, recoverySecretBase64 }
+// recoveryKey is a human-readable string like "ABCD-EFGH-..." for the user to write down
 
-await init('/path/to/metamorphic_crypto_bg.wasm');
+const backup = encryptPrivateKeyForRecovery(privateKeyBase64, rk.recoverySecretBase64);
+const restored = decryptPrivateKeyWithRecovery(backup, rk.recoverySecretBase64);
 
-const key = deriveSessionKey(password, saltBase64);
-const ciphertext = encryptSecretboxString("hello", key);
+// Or recover from the human-readable key:
+const secret = recoveryKeyToSecret("ABCD-EFGH-...");
+const restored2 = decryptPrivateKeyWithRecovery(backup, secret);
 ```
 
-## Tests
+## Security levels
+
+| Level | ML-KEM | NIST Category | Equivalent | Default |
+|-------|--------|---------------|------------|---------|
+| Cat-3 | 768    | 3             | ~AES-192   | Yes     |
+| Cat-5 | 1024   | 5             | ~AES-256   | No      |
+
+Decryption always auto-detects the level from the ciphertext version tag.
+
+## Security properties
+
+- `#![forbid(unsafe_code)]` — no unsafe anywhere in the Rust source
+- All secret key material zeroized after use
+- Constant-time MAC comparison via RustCrypto
+- OS CSPRNG via `getrandom` (no userspace PRNG)
+- Hybrid construction: both ML-KEM AND X25519 must be broken to compromise a sealed key
+
+## Integrity verification
+
+Every release includes SHA-512 checksums and [cosign](https://docs.sigstore.dev/cosign/overview/) signatures for supply chain verification:
 
 ```bash
-cargo test          # unit + integration + cross-level compatibility
-cargo clippy        # zero warnings
-cargo fmt --check   # formatted
+cosign verify-blob \
+  --bundle metamorphic_crypto_bg.wasm.cosign.bundle \
+  metamorphic_crypto_bg.wasm
 ```
 
 ## License
 
-Dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your option.
+Dual-licensed under [MIT](https://github.com/moss-piglet/metamorphic-crypto/blob/main/LICENSE-MIT) or [Apache-2.0](https://github.com/moss-piglet/metamorphic-crypto/blob/main/LICENSE-APACHE) at your option.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@f0rest8/metamorphic-crypto",
   "type": "module",
   "description": "Zero-knowledge end-to-end encryption with post-quantum hybrid KEM (ML-KEM-768/1024 + X25519)",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",