@f0rest8/metamorphic-crypto 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @f0rest8/metamorphic-crypto
 
-Zero-knowledge end-to-end encryption with post-quantum hybrid KEM (ML-KEM-768/1024 + X25519).
+Zero-knowledge end-to-end encryption with post-quantum hybrid KEM (ML-KEM-512/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.
 
@@ -103,7 +103,17 @@ import { generateHybridKeyPair1024, sealForUserWithLevel } from "@f0rest8/metamo
 
 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
+// unsealFromUser auto-detects Cat-1 vs Cat-3 vs Cat-5, no level param needed
+```
+
+### Cat-1 (ML-KEM-512, opt-in)
+
+```js
+import { generateHybridKeyPair512, sealForUserWithLevel } from "@f0rest8/metamorphic-crypto";
+
+const pq1 = generateHybridKeyPair512();  // { publicKey, secretKey } (ML-KEM-512)
+const sealed = sealForUserWithLevel(plaintextBase64, x25519.publicKey, pq1.publicKey, "cat1");
+// unsealFromUser auto-detects the level from the version tag, no level param needed
 ```
 
 ### Private key management
@@ -212,10 +222,11 @@ across native Rust, WASM, and the Elixir NIF.
 
 | Level | ML-KEM | NIST Category | Equivalent | Default |
 |-------|--------|---------------|------------|---------|
+| Cat-1 | 512    | 1             | ~AES-128   | No      |
 | 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.
+Decryption always auto-detects the level from the ciphertext version tag. NIST (FIPS 203) standardizes ML-KEM only at categories 1/3/5 — there is no category-2/4 set. The classical half is X25519 (~Cat-1 classical) at every tier; at Cat-3/Cat-5 the post-quantum half dominates and X25519 is the classical floor (standard hybrid-KEM practice).
 
 ## Security properties
 

package/metamorphic_crypto.d.ts

@@ -72,6 +72,11 @@ export function generateHybridKeyPair(): any;
  */
 export function generateHybridKeyPair1024(): any;
 
+/**
+ * Generate a ML-KEM-512 + X25519 keypair (Cat-1). Returns JSON: `{ publicKey, secretKey }`.
+ */
+export function generateHybridKeyPair512(): any;
+
 /**
  * Generate a random 32-byte symmetric key (base64).
  */
@@ -123,7 +128,8 @@ export function sealForUser(plaintext_b64: string, public_key_b64: string, pq_pu
 /**
  * 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).
+ * `level` must be `"cat1"` (ML-KEM-512), `"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;
@@ -192,6 +198,7 @@ export interface InitOutput {
     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 generateHybridKeyPair512: () => number;
     readonly generateHybridKeyPair: () => number;
     readonly generateHybridKeyPair1024: () => number;
     readonly isHybridCiphertext: (a: number, b: number) => number;
@@ -212,10 +219,10 @@ export interface InitOutput {
     readonly deriveSigningPublicKey: (a: number, b: number, c: number) => void;
     readonly sign: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly verify: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly decryptPrivateKeyWithRecovery: (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 encryptSecretboxString: (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 decryptSecretboxToString: (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;

package/metamorphic_crypto.js

@@ -439,6 +439,15 @@ export function generateHybridKeyPair1024() {
     return takeObject(ret);
 }
 
+/**
+ * Generate a ML-KEM-512 + X25519 keypair (Cat-1). Returns JSON: `{ publicKey, secretKey }`.
+ * @returns {any}
+ */
+export function generateHybridKeyPair512() {
+    const ret = wasm.generateHybridKeyPair512();
+    return takeObject(ret);
+}
+
 /**
  * Generate a random 32-byte symmetric key (base64).
  * @returns {string}
@@ -653,7 +662,8 @@ export function sealForUser(plaintext_b64, public_key_b64, pq_public_key_b64) {
 /**
  * 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).
+ * `level` must be `"cat1"` (ML-KEM-512), `"cat3"` (ML-KEM-768, default), or
+ * `"cat5"` (ML-KEM-1024).
  * If `pq_public_key_b64` is absent or empty, falls back to legacy X25519.
  * @param {string} plaintext_b64
  * @param {string} public_key_b64

package/package.json

@@ -1,8 +1,8 @@
 {
   "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.5.0",
+  "description": "Zero-knowledge end-to-end encryption with post-quantum hybrid KEM (ML-KEM-512/768/1024 + X25519)",
+  "version": "0.6.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",