@f0rest8/metamorphic-crypto 0.4.0 → 0.5.0

package/README.md

@@ -176,6 +176,38 @@ Stable wire format (reproduce exactly to match native/Elixir):
 > right construction instead: this package's Argon2id `deriveSessionKey` for
 > password-based derivation, or a dedicated KDF/MAC.
 
+### Hybrid PQ signatures (ML-DSA + Ed25519)
+
+Composite digital signatures: every message is signed by **both** ML-DSA
+(FIPS 204) and Ed25519 (RFC 8032), and `verify` returns `true` only if **both**
+component signatures are valid (strict AND). Keys and signatures are base64; the
+message is **base64** and `context` is a UTF-8 string.
+
+```js
+import { generateSigningKeyPair, sign, verify, deriveSigningPublicKey } from "@f0rest8/metamorphic-crypto";
+
+const kp = generateSigningKeyPair("cat3"); // { publicKey, secretKey } — Cat-3 default
+const msg = btoa("transparency log entry");
+const sig = sign(msg, "metamorphic/sign/v1", kp.secretKey);
+const ok = verify(msg, "metamorphic/sign/v1", sig, kp.publicKey); // true
+
+// Re-derive the public key from a backed-up secret key:
+const pk = deriveSigningPublicKey(kp.secretKey); // === kp.publicKey
+```
+
+Levels are `"cat2"` (ML-DSA-44), `"cat3"` (ML-DSA-65, default), and `"cat5"`
+(ML-DSA-87); `verify` auto-detects the level from the signature. ML-DSA uses the
+hedged/randomized FIPS 204 mode, so signature **bytes are non-reproducible**,
+but key derivation and the domain-separation framing
+(`u64_be(len(context)) || context || message`) are deterministic and identical
+across native Rust, WASM, and the Elixir NIF.
+
+> **Audit posture.** `ed25519-dalek` (2.x) is mature and widely deployed.
+> `ml-dsa` (0.1.x, RustCrypto FIPS 204) is new and **not yet independently
+> audited** — it is included as defense-in-depth on top of Ed25519, so the
+> composite remains at least as strong as Ed25519 even if a flaw is found in the
+> young post-quantum implementation. Pinned and tracked for the FIPS-mode roadmap.
+
 ## Security levels
 
 | Level | ML-KEM | NIST Category | Equivalent | Default |

package/metamorphic_crypto.d.ts

@@ -37,6 +37,11 @@ export function decryptSecretboxToString(ciphertext_b64: string, key_b64: string
  */
 export function deriveSessionKey(password: string, salt_b64: string): string;
 
+/**
+ * Re-derive the base64 public key from a base64 hybrid secret key.
+ */
+export function deriveSigningPublicKey(secret_key_b64: string): string;
+
 /**
  * Encrypt a base64 private key with a session key. Returns base64 ciphertext.
  */
@@ -87,6 +92,14 @@ export function generateRecoveryKey(): any;
  */
 export function generateSalt(): string;
 
+/**
+ * Generate a hybrid signing keypair. Returns JSON: `{ publicKey, secretKey }`.
+ *
+ * `level` is `"cat2"` (ML-DSA-44), `"cat3"` (ML-DSA-65, default), or `"cat5"`
+ * (ML-DSA-87). Empty/null defaults to Cat-3.
+ */
+export function generateSigningKeyPair(level: string): any;
+
 /**
  * Check if a base64 ciphertext is hybrid (v2/v3) format.
  */
@@ -148,12 +161,25 @@ export function sha3_512WithContext(context: string, data_b64: string): string;
  */
 export function sha512(data_b64: string): string;
 
+/**
+ * Sign base64 `message` under `context` with a base64 hybrid `secret_key`.
+ * Returns the composite signature as base64.
+ */
+export function sign(message_b64: string, context: string, secret_key_b64: 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;
 
+/**
+ * Verify a base64 composite `signature` over base64 `message`/`context`
+ * against a base64 `public_key`. Returns `true` only if **both** the Ed25519
+ * and ML-DSA components verify (strict AND).
+ */
+export function verify(message_b64: string, context: string, signature_b64: string, public_key_b64: string): boolean;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
@@ -182,10 +208,14 @@ export interface InitOutput {
     readonly sha3_256: (a: number, b: number, c: number) => void;
     readonly sha256: (a: number, b: number, c: number) => void;
     readonly sha512: (a: number, b: number, c: number) => void;
+    readonly generateSigningKeyPair: (a: number, b: number, c: number) => void;
+    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 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 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 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

@@ -249,6 +249,38 @@ export function deriveSessionKey(password, salt_b64) {
     }
 }
 
+/**
+ * Re-derive the base64 public key from a base64 hybrid secret key.
+ * @param {string} secret_key_b64
+ * @returns {string}
+ */
+export function deriveSigningPublicKey(secret_key_b64) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(secret_key_b64, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.deriveSigningPublicKey(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr2 = r0;
+        var len2 = r1;
+        if (r3) {
+            ptr2 = 0; len2 = 0;
+            throw takeObject(r2);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * Encrypt a base64 private key with a session key. Returns base64 ciphertext.
  * @param {string} private_key_b64
@@ -478,6 +510,32 @@ export function generateSalt() {
     }
 }
 
+/**
+ * Generate a hybrid signing keypair. Returns JSON: `{ publicKey, secretKey }`.
+ *
+ * `level` is `"cat2"` (ML-DSA-44), `"cat3"` (ML-DSA-65, default), or `"cat5"`
+ * (ML-DSA-87). Empty/null defaults to Cat-3.
+ * @param {string} level
+ * @returns {any}
+ */
+export function generateSigningKeyPair(level) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(level, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.generateSigningKeyPair(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
 /**
  * Check if a base64 ciphertext is hybrid (v2/v3) format.
  * @param {string} ciphertext_b64
@@ -807,6 +865,45 @@ export function sha512(data_b64) {
     }
 }
 
+/**
+ * Sign base64 `message` under `context` with a base64 hybrid `secret_key`.
+ * Returns the composite signature as base64.
+ * @param {string} message_b64
+ * @param {string} context
+ * @param {string} secret_key_b64
+ * @returns {string}
+ */
+export function sign(message_b64, context, secret_key_b64) {
+    let deferred5_0;
+    let deferred5_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(message_b64, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(context, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(secret_key_b64, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len2 = WASM_VECTOR_LEN;
+        wasm.sign(retptr, ptr0, len0, ptr1, len1, ptr2, len2);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr4 = r0;
+        var len4 = r1;
+        if (r3) {
+            ptr4 = 0; len4 = 0;
+            throw takeObject(r2);
+        }
+        deferred5_0 = ptr4;
+        deferred5_1 = len4;
+        return getStringFromWasm0(ptr4, len4);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred5_0, deferred5_1, 1);
+    }
+}
+
 /**
  * Unseal ciphertext using the user's keys. Auto-detects format.
  * Returns base64-encoded plaintext.
@@ -848,6 +945,40 @@ export function unsealFromUser(ciphertext_b64, public_key_b64, private_key_b64,
         wasm.__wbindgen_export4(deferred6_0, deferred6_1, 1);
     }
 }
+
+/**
+ * Verify a base64 composite `signature` over base64 `message`/`context`
+ * against a base64 `public_key`. Returns `true` only if **both** the Ed25519
+ * and ML-DSA components verify (strict AND).
+ * @param {string} message_b64
+ * @param {string} context
+ * @param {string} signature_b64
+ * @param {string} public_key_b64
+ * @returns {boolean}
+ */
+export function verify(message_b64, context, signature_b64, public_key_b64) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(message_b64, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(context, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(signature_b64, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len2 = WASM_VECTOR_LEN;
+        const ptr3 = passStringToWasm0(public_key_b64, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len3 = WASM_VECTOR_LEN;
+        wasm.verify(retptr, ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return r0 !== 0;
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,

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.4.0",
+  "version": "0.5.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",