@f0rest8/metamorphic-crypto 0.3.2

package/README.md

@@ -0,0 +1,113 @@
+# metamorphic-crypto
+
+Zero-knowledge end-to-end encryption library with post-quantum hybrid KEM.
+
+Built for [Metamorphic](https://metamorphic.app) and [Mosslet](https://mosslet.app) — 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
+
+- **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
+
+## Security levels
+
+| 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      |
+
+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.
+
+## Security properties
+
+- `#![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
+
+## Hybrid KEM construction
+
+The hybrid combiner matches the format used by [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum)'s `ml_kem768_x25519`:
+
+```
+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)
+```
+
+### Cat-3 (ML-KEM-768, default)
+```
+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
+```
+
+### 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
+```
+
+## WASM (browser)
+
+```bash
+wasm-pack build --target web --release
+```
+
+```js
+import init, { deriveSessionKey, encryptSecretboxString } from './pkg/metamorphic_crypto.js';
+
+await init('/path/to/metamorphic_crypto_bg.wasm');
+
+const key = deriveSessionKey(password, saltBase64);
+const ciphertext = encryptSecretboxString("hello", key);
+```
+
+## Tests
+
+```bash
+cargo test          # unit + integration + cross-level compatibility
+cargo clippy        # zero warnings
+cargo fmt --check   # formatted
+```
+
+## License
+
+Dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your option.

package/metamorphic_crypto.d.ts

@@ -0,0 +1,178 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Seal plaintext (base64) to a recipient's public key. Returns base64 ciphertext.
+ */
+export function boxSeal(plaintext_b64: string, public_key_b64: string): string;
+
+/**
+ * Open a sealed box. Returns base64-encoded plaintext.
+ */
+export function boxSealOpen(ciphertext_b64: string, public_key_b64: string, private_key_b64: string): string;
+
+/**
+ * Decrypt an encrypted private key with a session key. Returns base64 private key.
+ */
+export function decryptPrivateKey(ciphertext_b64: string, session_key_b64: string): string;
+
+/**
+ * Decrypt private key from recovery backup. Returns base64 private key.
+ */
+export function decryptPrivateKeyWithRecovery(ciphertext_b64: string, recovery_secret_b64: string): string;
+
+/**
+ * Decrypt base64 ciphertext, returning plaintext as base64.
+ */
+export function decryptSecretbox(ciphertext_b64: string, key_b64: string): string;
+
+/**
+ * Decrypt base64 ciphertext to a UTF-8 string.
+ */
+export function decryptSecretboxToString(ciphertext_b64: string, key_b64: string): string;
+
+/**
+ * Derive a 32-byte session key from password + base64-encoded salt.
+ * Returns base64-encoded key.
+ */
+export function deriveSessionKey(password: string, salt_b64: string): string;
+
+/**
+ * Encrypt a base64 private key with a session key. Returns base64 ciphertext.
+ */
+export function encryptPrivateKey(private_key_b64: string, session_key_b64: string): string;
+
+/**
+ * Encrypt private key for recovery backup. Returns base64 ciphertext.
+ */
+export function encryptPrivateKeyForRecovery(private_key_b64: string, recovery_secret_b64: string): string;
+
+/**
+ * Encrypt raw bytes (as base64) with a base64 key. Returns base64 ciphertext.
+ */
+export function encryptSecretbox(plaintext_b64: string, key_b64: string): string;
+
+/**
+ * Encrypt a UTF-8 string with a base64 key. Returns base64 ciphertext.
+ */
+export function encryptSecretboxString(plaintext: string, key_b64: string): string;
+
+/**
+ * Generate a ML-KEM-768 keypair. Returns JSON: `{ publicKey, secretKey }`.
+ */
+export function generateHybridKeyPair(): any;
+
+/**
+ * Generate a ML-KEM-1024 + X25519 keypair (Cat-5). Returns JSON: `{ publicKey, secretKey }`.
+ */
+export function generateHybridKeyPair1024(): any;
+
+/**
+ * Generate a random 32-byte symmetric key (base64).
+ */
+export function generateKey(): string;
+
+/**
+ * Generate a random X25519 keypair. Returns JSON: `{ publicKey, privateKey }`.
+ */
+export function generateKeyPair(): any;
+
+/**
+ * Generate a recovery key. Returns JSON: `{ recoveryKey, recoverySecretBase64 }`.
+ */
+export function generateRecoveryKey(): any;
+
+/**
+ * Generate a random 16-byte salt (base64).
+ */
+export function generateSalt(): string;
+
+/**
+ * Check if a base64 ciphertext is hybrid (v2/v3) format.
+ */
+export function isHybridCiphertext(ciphertext_b64: string): boolean;
+
+/**
+ * Parse the salt (base64) from a key_hash string (`salt$argon2id`).
+ */
+export function parseSaltFromKeyHash(key_hash: string): string;
+
+/**
+ * Derive the 32-byte secret (base64) from a human-readable recovery key.
+ */
+export function recoveryKeyToSecret(recovery_key: string): string;
+
+/**
+ * Seal plaintext bytes (base64) to a user's key(s). Uses hybrid PQ if pq_pk is provided.
+ */
+export function sealForUser(plaintext_b64: string, public_key_b64: string, pq_public_key_b64?: string | null): string;
+
+/**
+ * Seal plaintext bytes (base64) to a user's key(s) at a specific security level.
+ *
+ * `level` must be `"cat3"` (ML-KEM-768, default) or `"cat5"` (ML-KEM-1024).
+ * If `pq_public_key_b64` is absent or empty, falls back to legacy X25519.
+ */
+export function sealForUserWithLevel(plaintext_b64: string, public_key_b64: string, pq_public_key_b64: string | null | undefined, level: string): string;
+
+/**
+ * Unseal ciphertext using the user's keys. Auto-detects format.
+ * Returns base64-encoded plaintext.
+ */
+export function unsealFromUser(ciphertext_b64: string, public_key_b64: string, private_key_b64: string, pq_secret_key_b64?: string | null): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly deriveSessionKey: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly encryptSecretbox: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly decryptSecretbox: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly boxSeal: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly boxSealOpen: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly sealForUser: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly unsealFromUser: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly sealForUserWithLevel: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly generateHybridKeyPair: () => number;
+    readonly generateHybridKeyPair1024: () => number;
+    readonly isHybridCiphertext: (a: number, b: number) => number;
+    readonly generateKey: (a: number) => void;
+    readonly generateKeyPair: () => number;
+    readonly generateSalt: (a: number) => void;
+    readonly encryptPrivateKey: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly decryptPrivateKey: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly generateRecoveryKey: (a: number) => void;
+    readonly recoveryKeyToSecret: (a: number, b: number, c: number) => void;
+    readonly parseSaltFromKeyHash: (a: number, b: number, c: number) => void;
+    readonly encryptSecretboxString: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly decryptSecretboxToString: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly encryptPrivateKeyForRecovery: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly decryptPrivateKeyWithRecovery: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;