@f0rest8/metamorphic-crypto 0.3.7 → 0.4.0

package/README.md

@@ -134,6 +134,48 @@ const secret = recoveryKeyToSecret("ABCD-EFGH-...");
 const restored2 = decryptPrivateKeyWithRecovery(backup, secret);
 ```
 
+### Hashing (SHA-3 / SHA-2)
+
+Public, one-shot digest functions — intended for **public** data only, such as
+key fingerprints, safety numbers, and key-transparency-log entries. Each takes
+**base64-encoded input** and returns the digest as **base64**. Decode with
+`atob`, or re-encode to hex, if you need a hex fingerprint.
+
+`sha3_512` is the recommended default (highest assurance, NIST Cat-5). The
+others let you match an existing format.
+
+```js
+import { sha3_512, sha3_256, sha256, sha512 } from "@f0rest8/metamorphic-crypto";
+
+const dataBase64 = btoa("public key bytes");
+const digestBase64 = sha3_512(dataBase64); // 64-byte digest, base64
+
+// Need hex? decode the base64 digest:
+const hex = [...atob(digestBase64)].map(c => c.charCodeAt(0).toString(16).padStart(2, "0")).join("");
+```
+
+**Domain separation (recommended for fingerprints / transparency logs).** Use
+`sha3_512WithContext` to bind a digest to a versioned context label, so the same
+bytes hashed for different purposes can never collide or be reinterpreted across
+contexts. It is exactly as strong as `sha3_512`:
+
+```js
+import { sha3_512WithContext } from "@f0rest8/metamorphic-crypto";
+
+const dataBase64 = btoa("public key bytes");
+const fingerprint = sha3_512WithContext("mosslet/key-fingerprint/v1", dataBase64);
+```
+
+Stable wire format (reproduce exactly to match native/Elixir):
+`SHA3-512( u64_be(len(context_utf8)) || context_utf8 || data )`.
+
+> **Do not hash secrets with these.** A bare hash makes no guarantees about its
+> inputs, and the hashing path intentionally adds no zeroize/constant-time
+> ceremony — wiping a transient copy of already-public data adds cost without
+> protection. To process secret material (passwords, private keys), use the
+> right construction instead: this package's Argon2id `deriveSessionKey` for
+> password-based derivation, or a dedicated KDF/MAC.
+
 ## Security levels
 
 | Level | ML-KEM | NIST Category | Equivalent | Default |

package/metamorphic_crypto.d.ts

@@ -115,6 +115,39 @@ export function sealForUser(plaintext_b64: string, public_key_b64: string, pq_pu
  */
 export function sealForUserWithLevel(plaintext_b64: string, public_key_b64: string, pq_public_key_b64: string | null | undefined, level: string): string;
 
+/**
+ * SHA-256 (SHA-2) digest of base64-encoded `data`. Returns the 32-byte digest as base64.
+ */
+export function sha256(data_b64: string): string;
+
+/**
+ * SHA3-256 digest of base64-encoded `data`. Returns the 32-byte digest as base64.
+ */
+export function sha3_256(data_b64: string): string;
+
+/**
+ * SHA3-512 digest of base64-encoded `data`. Returns the 64-byte digest as base64.
+ *
+ * This is the recommended default hash (NIST Cat-5).
+ */
+export function sha3_512(data_b64: string): string;
+
+/**
+ * Domain-separated SHA3-512: binds the digest to a UTF-8 `context` label.
+ *
+ * `data` is base64; returns the 64-byte digest as base64. Prefer this over
+ * `sha3_512` for fingerprints / safety numbers / key-transparency entries.
+ *
+ * Wire format (reproduce exactly for parity with native/Elixir):
+ * `SHA3-512( u64_be(len(context_utf8)) || context_utf8 || data )`.
+ */
+export function sha3_512WithContext(context: string, data_b64: string): string;
+
+/**
+ * SHA-512 (SHA-2) digest of base64-encoded `data`. Returns the 64-byte digest as base64.
+ */
+export function sha512(data_b64: string): string;
+
 /**
  * Unseal ciphertext using the user's keys. Auto-detects format.
  * Returns base64-encoded plaintext.
@@ -144,10 +177,15 @@ export interface InitOutput {
     readonly generateRecoveryKey: (a: number) => void;
     readonly recoveryKeyToSecret: (a: number, b: number, c: number) => void;
     readonly parseSaltFromKeyHash: (a: number, b: number, c: number) => void;
-    readonly decryptSecretboxToString: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly sha3_512: (a: number, b: number, c: number) => void;
+    readonly sha3_512WithContext: (a: number, b: number, c: number, d: number, e: number) => void;
+    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 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 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 __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

@@ -636,6 +636,177 @@ export function sealForUserWithLevel(plaintext_b64, public_key_b64, pq_public_ke
     }
 }
 
+/**
+ * SHA-256 (SHA-2) digest of base64-encoded `data`. Returns the 32-byte digest as base64.
+ * @param {string} data_b64
+ * @returns {string}
+ */
+export function sha256(data_b64) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(data_b64, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.sha256(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);
+    }
+}
+
+/**
+ * SHA3-256 digest of base64-encoded `data`. Returns the 32-byte digest as base64.
+ * @param {string} data_b64
+ * @returns {string}
+ */
+export function sha3_256(data_b64) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(data_b64, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.sha3_256(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);
+    }
+}
+
+/**
+ * SHA3-512 digest of base64-encoded `data`. Returns the 64-byte digest as base64.
+ *
+ * This is the recommended default hash (NIST Cat-5).
+ * @param {string} data_b64
+ * @returns {string}
+ */
+export function sha3_512(data_b64) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(data_b64, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.sha3_512(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);
+    }
+}
+
+/**
+ * Domain-separated SHA3-512: binds the digest to a UTF-8 `context` label.
+ *
+ * `data` is base64; returns the 64-byte digest as base64. Prefer this over
+ * `sha3_512` for fingerprints / safety numbers / key-transparency entries.
+ *
+ * Wire format (reproduce exactly for parity with native/Elixir):
+ * `SHA3-512( u64_be(len(context_utf8)) || context_utf8 || data )`.
+ * @param {string} context
+ * @param {string} data_b64
+ * @returns {string}
+ */
+export function sha3_512WithContext(context, data_b64) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(context, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(data_b64, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.sha3_512WithContext(retptr, ptr0, len0, ptr1, len1);
+        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 ptr3 = r0;
+        var len3 = r1;
+        if (r3) {
+            ptr3 = 0; len3 = 0;
+            throw takeObject(r2);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred4_0, deferred4_1, 1);
+    }
+}
+
+/**
+ * SHA-512 (SHA-2) digest of base64-encoded `data`. Returns the 64-byte digest as base64.
+ * @param {string} data_b64
+ * @returns {string}
+ */
+export function sha512(data_b64) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(data_b64, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.sha512(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);
+    }
+}
+
 /**
  * Unseal ciphertext using the user's keys. Auto-detects format.
  * Returns base64-encoded plaintext.

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