@vollcrypt/messages-wasm 0.2.0

package/README.md

@@ -0,0 +1,57 @@
+# @vollcrypt/wasm
+
+**Cross-platform, quantum-resistant cryptography engine - WebAssembly Binding**
+
+[![npm](https://img.shields.io/npm/v/@vollcrypt/wasm.svg)](https://www.npmjs.com/package/@vollcrypt/wasm)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://github.com/BeratVural/vollcrypt/blob/main/LICENSE)
+
+This package provides the **WebAssembly (WASM) bindings** for the Vollcrypt cryptography engine. It is compiled directly from Rust using `wasm-pack`, bringing robust, post-quantum cryptography straight to the user's browser or frontend application (React, Next.js, Vue, etc.) without relying on slow JavaScript cryptography implementations.
+
+## Features
+
+- **Universal:** Runs in any modern browser without native binary dependencies.
+- **Quantum-Resistant:** Implements the NIST FIPS 203 (ML-KEM-768) standard combined with X25519 for hybrid key exchange.
+- **Client-Side E2EE:** Perfect for End-to-End Encryption where keys never leave the user's device.
+- **Secure Defaults:** Provides AES-256-GCM, Ed25519, HKDF-SHA256, and post-compromise security ratchets out of the box.
+
+## Installation
+
+```bash
+npm install @vollcrypt/wasm
+```
+
+*Note: Since this is a WebAssembly module, you may need to configure your bundler (Webpack, Vite, Rollup) to handle `.wasm` files depending on your frontend setup.*
+
+## Quick Start
+
+```javascript
+import * as vollcrypt from '@vollcrypt/wasm';
+
+// Generate an Ed25519 Identity Keypair
+const identity = vollcrypt.generate_ed25519_keypair();
+console.log("Public Key:", Buffer.from(identity.public_key).toString('hex'));
+
+// Sign and Verify
+const message = new TextEncoder().encode("Hello from Vollcrypt WASM!");
+const signature = vollcrypt.sign_message(identity.private_key, message);
+const isValid = vollcrypt.verify_signature(identity.public_key, message, signature);
+
+console.log("Signature Valid:", isValid); // true
+
+// Hybrid Key Exchange (X25519)
+const alice = vollcrypt.generate_x25519_keypair();
+const bob = vollcrypt.generate_x25519_keypair();
+const sharedSecret = vollcrypt.ecdh_shared_secret(alice.private_key, bob.public_key);
+
+console.log("Shared Secret Derived successfully.");
+```
+
+## Documentation
+
+For full API documentation, architecture details, and the high-performance Native Node.js equivalent, please refer to the [Vollcrypt Main Repository](https://github.com/BeratVural/vollcrypt).
+
+## License
+
+This project is licensed under the **GNU General Public License v3.0**. 
+
+For commercial use without the GPL copyleft requirement, please contact Berat Vural at [berat.vural.tr@gmail.com](mailto:berat.vural.tr@gmail.com).

package/fast.d.ts

@@ -0,0 +1,102 @@
+export { default } from "./pkg/wasm"
+export * from "./pkg/wasm"
+
+export declare function encryptAesGcmWeb(
+  key: CryptoKey | Uint8Array,
+  plaintext: Uint8Array,
+  aad?: Uint8Array | null
+): Promise<Uint8Array>
+
+export declare function decryptAesGcmWeb(
+  key: CryptoKey | Uint8Array,
+  ciphertext: Uint8Array,
+  aad?: Uint8Array | null
+): Promise<Uint8Array>
+
+export declare function encryptAesGcmAuto(
+  key: CryptoKey | Uint8Array,
+  plaintext: Uint8Array,
+  aad?: Uint8Array | null
+): Promise<Uint8Array>
+
+export declare function decryptAesGcmAuto(
+  key: CryptoKey | Uint8Array,
+  ciphertext: Uint8Array,
+  aad?: Uint8Array | null
+): Promise<Uint8Array>
+
+export declare function encryptAesGcmPaddedWeb(
+  key: CryptoKey | Uint8Array,
+  plaintext: Uint8Array,
+  aad?: Uint8Array | null
+): Promise<Uint8Array>
+
+export declare function decryptAesGcmPaddedWeb(
+  key: CryptoKey | Uint8Array,
+  ciphertext: Uint8Array,
+  aad?: Uint8Array | null
+): Promise<Uint8Array>
+
+export declare function encryptAesGcmPaddedAuto(
+  key: CryptoKey | Uint8Array,
+  plaintext: Uint8Array,
+  aad?: Uint8Array | null
+): Promise<Uint8Array>
+
+export declare function decryptAesGcmPaddedAuto(
+  key: CryptoKey | Uint8Array,
+  ciphertext: Uint8Array,
+  aad?: Uint8Array | null
+): Promise<Uint8Array>
+
+export declare function encryptAesGcmChunkedWeb(
+  key: CryptoKey | Uint8Array,
+  plaintext: Uint8Array,
+  aad: Uint8Array | null | undefined,
+  chunkSize: number
+): Promise<Uint8Array>
+
+export declare function decryptAesGcmChunkedWeb(
+  key: CryptoKey | Uint8Array,
+  ciphertext: Uint8Array,
+  aad: Uint8Array | null | undefined
+): Promise<Uint8Array>
+
+export declare function encryptAesGcmChunkedPaddedWeb(
+  key: CryptoKey | Uint8Array,
+  plaintext: Uint8Array,
+  aad: Uint8Array | null | undefined,
+  chunkSize: number
+): Promise<Uint8Array>
+
+export declare function decryptAesGcmChunkedPaddedWeb(
+  key: CryptoKey | Uint8Array,
+  ciphertext: Uint8Array,
+  aad: Uint8Array | null | undefined
+): Promise<Uint8Array>
+
+export declare function encryptAesGcmChunkedAuto(
+  key: CryptoKey | Uint8Array,
+  plaintext: Uint8Array,
+  aad: Uint8Array | null | undefined,
+  chunkSize: number
+): Promise<Uint8Array>
+
+export declare function decryptAesGcmChunkedAuto(
+  key: CryptoKey | Uint8Array,
+  ciphertext: Uint8Array,
+  aad: Uint8Array | null | undefined
+): Promise<Uint8Array>
+
+export declare function encryptAesGcmChunkedPaddedAuto(
+  key: CryptoKey | Uint8Array,
+  plaintext: Uint8Array,
+  aad: Uint8Array | null | undefined,
+  chunkSize: number
+): Promise<Uint8Array>
+
+export declare function decryptAesGcmChunkedPaddedAuto(
+  key: CryptoKey | Uint8Array,
+  ciphertext: Uint8Array,
+  aad: Uint8Array | null | undefined
+): Promise<Uint8Array>

package/fast.js

@@ -0,0 +1,301 @@
+import init, * as wasm from "./pkg/wasm.js"
+
+function getSubtle() {
+  const cryptoObj = globalThis?.crypto
+  return cryptoObj && cryptoObj.subtle ? cryptoObj.subtle : null
+}
+
+function normalizeU8(data) {
+  if (data == null) return null
+  return data instanceof Uint8Array ? data : new Uint8Array(data)
+}
+
+async function importAesKey(key, usages) {
+  if (typeof CryptoKey !== "undefined" && key instanceof CryptoKey) {
+    return key
+  }
+  const subtle = getSubtle()
+  if (!subtle) {
+    throw new Error("WebCrypto not available")
+  }
+  const raw = normalizeU8(key)
+  if (!raw) {
+    throw new Error("Invalid key")
+  }
+  return await subtle.importKey("raw", raw, { name: "AES-GCM" }, false, usages)
+}
+
+export async function encryptAesGcmWeb(key, plaintext, aad) {
+  const subtle = getSubtle()
+  if (!subtle) {
+    throw new Error("WebCrypto not available")
+  }
+  const pt = normalizeU8(plaintext)
+  if (!pt) {
+    throw new Error("Invalid plaintext")
+  }
+  const aadU8 = normalizeU8(aad)
+  const cryptoKey = await importAesKey(key, ["encrypt"])
+  const iv = new Uint8Array(12)
+  globalThis.crypto.getRandomValues(iv)
+  const algo = { name: "AES-GCM", iv }
+  if (aadU8 && aadU8.length > 0) {
+    algo.additionalData = aadU8
+  }
+  const ct = await subtle.encrypt(algo, cryptoKey, pt)
+  const out = new Uint8Array(iv.length + ct.byteLength)
+  out.set(iv, 0)
+  out.set(new Uint8Array(ct), iv.length)
+  return out
+}
+
+export async function decryptAesGcmWeb(key, ciphertext, aad) {
+  const subtle = getSubtle()
+  if (!subtle) {
+    throw new Error("WebCrypto not available")
+  }
+  const ct = normalizeU8(ciphertext)
+  if (!ct || ct.length < 12) {
+    throw new Error("Ciphertext too short")
+  }
+  const aadU8 = normalizeU8(aad)
+  const cryptoKey = await importAesKey(key, ["decrypt"])
+  const iv = ct.slice(0, 12)
+  const data = ct.slice(12)
+  const algo = { name: "AES-GCM", iv }
+  if (aadU8 && aadU8.length > 0) {
+    algo.additionalData = aadU8
+  }
+  const pt = await subtle.decrypt(algo, cryptoKey, data)
+  return new Uint8Array(pt)
+}
+
+export async function encryptAesGcmAuto(key, plaintext, aad) {
+  const subtle = getSubtle()
+  if (subtle) {
+    return await encryptAesGcmWeb(key, plaintext, aad)
+  }
+  return wasm.encryptAesGcm(key, plaintext, aad ?? null)
+}
+
+export async function decryptAesGcmAuto(key, ciphertext, aad) {
+  const subtle = getSubtle()
+  if (subtle) {
+    return await decryptAesGcmWeb(key, ciphertext, aad)
+  }
+  return wasm.decryptAesGcm(key, ciphertext, aad ?? null)
+}
+
+function calculatePaddingLen(contentLen) {
+  const sizes = [64, 128, 256, 512, 1024, 2048]
+  const minPadding = 2
+  const target = sizes.find((s) => s >= contentLen + minPadding) ?? (() => {
+    const remainder = (contentLen + minPadding) % 1024
+    return remainder === 0 ? contentLen + minPadding : contentLen + minPadding + (1024 - remainder)
+  })()
+  return target - contentLen
+}
+
+function padWithLen(content) {
+  const pt = normalizeU8(content)
+  if (!pt) {
+    throw new Error("Invalid plaintext")
+  }
+  if (pt.length > 0xffffffff) {
+    throw new Error("Message too large to pad")
+  }
+  const lenPrefix = new Uint8Array(4)
+  new DataView(lenPrefix.buffer).setUint32(0, pt.length, false)
+  const baseLen = 4 + pt.length
+  const padLen = calculatePaddingLen(baseLen)
+  const padding = new Uint8Array(padLen)
+  if (padLen > 0) {
+    globalThis.crypto.getRandomValues(padding)
+  }
+  const out = new Uint8Array(baseLen + padLen)
+  out.set(lenPrefix, 0)
+  out.set(pt, 4)
+  out.set(padding, 4 + pt.length)
+  return out
+}
+
+function unpadWithLen(padded) {
+  const buf = normalizeU8(padded)
+  if (!buf || buf.length < 4) {
+    throw new Error("Padded message too short")
+  }
+  const len = new DataView(buf.buffer, buf.byteOffset, buf.byteLength).getUint32(0, false)
+  if (len > buf.length - 4) {
+    throw new Error("Invalid padded message length")
+  }
+  return buf.subarray(4, 4 + len)
+}
+
+export async function encryptAesGcmPaddedWeb(key, plaintext, aad) {
+  const padded = padWithLen(plaintext)
+  return await encryptAesGcmWeb(key, padded, aad)
+}
+
+export async function decryptAesGcmPaddedWeb(key, ciphertext, aad) {
+  const padded = await decryptAesGcmWeb(key, ciphertext, aad)
+  return unpadWithLen(padded)
+}
+
+export async function encryptAesGcmPaddedAuto(key, plaintext, aad) {
+  const subtle = getSubtle()
+  if (subtle) {
+    return await encryptAesGcmPaddedWeb(key, plaintext, aad)
+  }
+  return wasm.encryptAesGcmPadded(key, plaintext, aad ?? null)
+}
+
+export async function decryptAesGcmPaddedAuto(key, ciphertext, aad) {
+  const subtle = getSubtle()
+  if (subtle) {
+    return await decryptAesGcmPaddedWeb(key, ciphertext, aad)
+  }
+  return wasm.decryptAesGcmPadded(key, ciphertext, aad ?? null)
+}
+
+function buildChunkAad(baseAad, chunkIndex) {
+  const aadPrefix = baseAad ? normalizeU8(baseAad) : null
+  const indexBuf = new Uint8Array(4)
+  const view = new DataView(indexBuf.buffer)
+  view.setUint32(0, chunkIndex, false)
+  if (!aadPrefix || aadPrefix.length === 0) {
+    return indexBuf
+  }
+  const out = new Uint8Array(aadPrefix.length + 4)
+  out.set(aadPrefix, 0)
+  out.set(indexBuf, aadPrefix.length)
+  return out
+}
+
+export async function encryptAesGcmChunkedWeb(key, plaintext, aad, chunkSize) {
+  if (!chunkSize || chunkSize <= 0) {
+    throw new Error("Invalid chunk size")
+  }
+  const pt = normalizeU8(plaintext)
+  if (!pt) {
+    throw new Error("Invalid plaintext")
+  }
+  const totalLen = pt.length
+  const chunkCount = totalLen === 0 ? 1 : Math.ceil(totalLen / chunkSize)
+  if (chunkCount > 0xffffffff) {
+    throw new Error("Chunk count exceeds supported maximum")
+  }
+  const parts = []
+  const header = new Uint8Array(4)
+  new DataView(header.buffer).setUint32(0, chunkCount, false)
+  parts.push(header)
+  for (let i = 0; i < chunkCount; i += 1) {
+    const start = i * chunkSize
+    const end = totalLen === 0 ? 0 : Math.min(start + chunkSize, totalLen)
+    const chunk = pt.subarray(start, end)
+    const aadChunk = buildChunkAad(aad, i)
+    const enc = await encryptAesGcmWeb(key, chunk, aadChunk)
+    const h = new Uint8Array(8)
+    const v = new DataView(h.buffer)
+    v.setUint32(0, i, false)
+    v.setUint32(4, enc.length, false)
+    parts.push(h, enc)
+    if (totalLen === 0) break
+  }
+  const total = parts.reduce((sum, p) => sum + p.length, 0)
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const p of parts) {
+    out.set(p, offset)
+    offset += p.length
+  }
+  return out
+}
+
+export async function encryptAesGcmChunkedPaddedWeb(key, plaintext, aad, chunkSize) {
+  const padded = padWithLen(plaintext)
+  return await encryptAesGcmChunkedWeb(key, padded, aad, chunkSize)
+}
+
+export async function decryptAesGcmChunkedWeb(key, ciphertext, aad) {
+  const ct = normalizeU8(ciphertext)
+  if (!ct || ct.length < 4) {
+    throw new Error("Encrypted data too short")
+  }
+  const view = new DataView(ct.buffer, ct.byteOffset, ct.byteLength)
+  const chunkCount = view.getUint32(0, false)
+  if (chunkCount === 0) {
+    throw new Error("Invalid chunk count")
+  }
+  let offset = 4
+  const parts = []
+  for (let expected = 0; expected < chunkCount; expected += 1) {
+    if (offset + 8 > ct.length) {
+      throw new Error("Encrypted data truncated")
+    }
+    const chunkIndex = view.getUint32(offset, false)
+    const chunkLen = view.getUint32(offset + 4, false)
+    offset += 8
+    if (chunkIndex !== expected) {
+      throw new Error("Chunk index mismatch")
+    }
+    if (chunkLen === 0 || offset + chunkLen > ct.length) {
+      throw new Error("Invalid chunk length")
+    }
+    const chunk = ct.subarray(offset, offset + chunkLen)
+    const aadChunk = buildChunkAad(aad, chunkIndex)
+    const dec = await decryptAesGcmWeb(key, chunk, aadChunk)
+    parts.push(dec)
+    offset += chunkLen
+  }
+  if (offset !== ct.length) {
+    throw new Error("Trailing data after chunks")
+  }
+  const total = parts.reduce((sum, p) => sum + p.length, 0)
+  const out = new Uint8Array(total)
+  let outOffset = 0
+  for (const p of parts) {
+    out.set(p, outOffset)
+    outOffset += p.length
+  }
+  return out
+}
+
+export async function decryptAesGcmChunkedPaddedWeb(key, ciphertext, aad) {
+  const padded = await decryptAesGcmChunkedWeb(key, ciphertext, aad)
+  return unpadWithLen(padded)
+}
+
+export async function encryptAesGcmChunkedAuto(key, plaintext, aad, chunkSize) {
+  const subtle = getSubtle()
+  if (subtle) {
+    return await encryptAesGcmChunkedWeb(key, plaintext, aad, chunkSize)
+  }
+  return wasm.encryptAesGcmChunked(key, plaintext, aad ?? null, chunkSize)
+}
+
+export async function encryptAesGcmChunkedPaddedAuto(key, plaintext, aad, chunkSize) {
+  const subtle = getSubtle()
+  if (subtle) {
+    return await encryptAesGcmChunkedPaddedWeb(key, plaintext, aad, chunkSize)
+  }
+  return wasm.encryptAesGcmChunkedPadded(key, plaintext, aad ?? null, chunkSize)
+}
+
+export async function decryptAesGcmChunkedAuto(key, ciphertext, aad) {
+  const subtle = getSubtle()
+  if (subtle) {
+    return await decryptAesGcmChunkedWeb(key, ciphertext, aad)
+  }
+  return wasm.decryptAesGcmChunked(key, ciphertext, aad ?? null)
+}
+
+export async function decryptAesGcmChunkedPaddedAuto(key, ciphertext, aad) {
+  const subtle = getSubtle()
+  if (subtle) {
+    return await decryptAesGcmChunkedPaddedWeb(key, ciphertext, aad)
+  }
+  return wasm.decryptAesGcmChunkedPadded(key, ciphertext, aad ?? null)
+}
+
+export { init }
+export * from "./pkg/wasm.js"

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vollcrypt/messages-wasm",
+  "version": "0.2.0",
+  "description": "Cross-platform, quantum-resistant cryptography engine - WebAssembly binding",
+  "type": "module",
+  "main": "pkg/wasm.js",
+  "types": "pkg/wasm.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BeratVural/vollcrypt.git",
+    "directory": "wasm"
+  },
+  "homepage": "https://github.com/BeratVural/vollcrypt#readme",
+  "bugs": {
+    "url": "https://github.com/BeratVural/vollcrypt/issues"
+  },
+  "files": [
+    "pkg/",
+    "fast.js",
+    "fast.d.ts"
+  ],
+  "keywords": [
+    "vollcrypt",
+    "cryptography",
+    "encryption",
+    "wasm",
+    "webassembly",
+    "aes-gcm",
+    "ed25519",
+    "x25519",
+    "ml-kem",
+    "post-quantum",
+    "pqc",
+    "e2ee"
+  ],
+  "author": "Berat Vural <berat.vural.tr@gmail.com>",
+  "license": "GPL-3.0-only"
+}