fixed-size encryption supporting up to 254 bytes of data

Author: killroy192

README.md

@@ -74,7 +74,8 @@ const account = deriveStealthAccount(privateKey, toHex(random));
 ### Classic Encryption (`/crypt.js`)
 
 #### `encrypt(data: string, publicKey: Hex): Hex`
-ECDH encryption with ephemeral keys and AES-256-GCM.
+ECDH encryption with ephemeral keys and AES-256-GCM. **Max 254 bytes input.**
+- All ciphertexts are fixed-length (255 bytes padded) for perfect length obfuscation.
 
 #### `decrypt(privateKey: Hash, encodedData: Hex): string`
 Decrypt data encrypted with `encrypt()`.
@@ -87,7 +88,8 @@ Generate ML-KEM-768 key pair. Optional seed for deterministic generation.
 - **Key sizes:** 1184 bytes (public), 2400 bytes (secret)
 
 #### `encryptQuantum(data: string, publicKey: Hex): Hex`
-Quantum-resistant encryption using ML-KEM-768 + AES-256-GCM.
+Quantum-resistant encryption using ML-KEM-768 + AES-256-GCM. **Max 254 bytes input.**
+- All ciphertexts are fixed-length (255 bytes padded) for perfect length obfuscation.
 
 #### `decryptQuantum(secretKey: Hex, encodedData: Hex): string`
 Decrypt quantum-encrypted data.
@@ -113,12 +115,14 @@ Multiply private key by scalar (modulo curve order).
 - ✅ Authenticated encryption (AES-256-GCM)
 - ✅ Random IVs per operation
 - ✅ ECDH on secp256k1 curve
+- ✅ Fixed-length ciphertexts (length obfuscation)
 
 ### Quantum Encryption
 - ✅ ML-KEM-768 (NIST FIPS 203)
 - ✅ Post-quantum secure
 - ✅ Hybrid encryption (KEM + AES-GCM)
 - ✅ Non-deterministic by default
+- ✅ Fixed-length ciphertexts (length obfuscation)
 
 ### Best Practices
 - Never share or transmit private keys
@@ -153,7 +157,7 @@ npm run typecheck
 npm run lint
 ```
 
-**Test coverage:** 89+ tests covering encryption, stealth addresses, edge cases, and build validation.
+**Test coverage:** 128 tests covering encryption, stealth addresses, edge cases, and build validation.
 
 ## Dependencies
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroledger/vycrypt",
-  "version": "1.0.0-alpha",
+  "version": "1.0.0-beta.1",
   "description": "Crypto primitives for ZeroLedger Protocol",
   "files": [
     "*.js",

package.json

@@ -61,11 +61,27 @@ function getSharedSecret(privateKey: Hash, publicKey: Hex) {
 }
 
 /**
- * @notice Encrypt a number with the instance's public key
- * @param randomNumber Number as instance of RandomNumber class
- * @returns Hex strings of uncompressed 65 byte public key and 32 byte ciphertext
+ * @notice Encrypt data with ECIES and length obfuscation
+ * @param data String to encrypt
+ * @param counterpartyPubKey Recipient's public key
+ * @returns Hex strings of uncompressed 65 byte public key and ciphertext
+ * @description Adds a 1-byte header + paddingSize (1-254 bytes) before the actual data to obfuscate length
  */
 export const encrypt = (data: string, counterpartyPubKey: Hex) => {
+  const dataBytes = encoder.encode(data);
+
+  if (dataBytes.length >= 255) {
+    throw new Error("Data length must be less than 255");
+  }
+
+  const fakePrefixSize = 255 - dataBytes.length;
+  const fakePrefix = randomBytes(fakePrefixSize);
+  // Create padded data: [prefix_size(1 byte)][fake_prefix(1-254 bytes)][actual_data]
+  const paddedData = new Uint8Array(1 + fakePrefixSize + dataBytes.length);
+  paddedData[0] = fakePrefixSize;
+  paddedData.set(fakePrefix, 1);
+  paddedData.set(dataBytes, 1 + fakePrefixSize);
+
   // Get shared secret to use as encryption key
   const ephemeralPrivateKey = secp256k1Utils.randomPrivateKey();
   const ephemeralPublicKey = Point.fromPrivateKey(ephemeralPrivateKey);
@@ -77,12 +93,18 @@ export const encrypt = (data: string, counterpartyPubKey: Hex) => {
   );
 
   const iv = randomBytes(12);
-  const rawData = encoder.encode(data);
   const aes = gcm(sharedSecret, iv);
-  const ciphertext = aes.encrypt(rawData);
+  const ciphertext = aes.encrypt(paddedData);
   return `${toHex(iv)}${ephemeralPublicKeyHex.slice(2)}${toHex(ciphertext).slice(2)}` as Hex;
 };
 
+/**
+ * @notice Decrypt data encrypted with ECIES
+ * @param privateKey Your private key
+ * @param encodedData Encrypted data from encrypt()
+ * @returns Decrypted string
+ * @description Automatically removes fake prefix padding added during encryption
+ */
 export const decrypt = (privateKey: Hash, encodedData: Hex) => {
   // manually split string by bytes12, bytes64, the rest
   const iv = toBytes(encodedData.slice(0, 26));
@@ -95,6 +117,13 @@ export const decrypt = (privateKey: Hash, encodedData: Hex) => {
   const sharedSecret = getSharedSecret(privateKey, ephemeralPublicKey);
 
   const aes = gcm(sharedSecret, iv);
+  const decryptedBytes = aes.decrypt(ciphertext);
+
+  // Read the fake prefix size from first byte
+  const fakePrefixSize = decryptedBytes[0];
+
+  // Skip header (1 byte) and fake prefix, return actual data
+  const actualData = decryptedBytes.slice(1 + fakePrefixSize);
 
-  return decoder.decode(aes.decrypt(ciphertext));
+  return decoder.decode(actualData);
 };

src/crypt.ts

@@ -67,14 +67,29 @@ export function generateQuantumKeyPair(seed?: string): QuantumKeyPair {
 }
 
 /**
- * @notice Encrypt data using quantum-resistant ML-KEM-768
+ * @notice Encrypt data using quantum-resistant ML-KEM-768 with length obfuscation
  * @param data String to encrypt (supports any UTF-8 data)
  * @param publicKey Recipient's ML-KEM-768 public key (0x-prefixed hex string, 1184 bytes)
  * @returns Hex string of encrypted data
+ * @description Adds a 1-byte header + paddingSize (1-254 bytes) before the actual data to obfuscate length
  */
 export const encryptQuantum = (data: string, publicKey: Hex): Hex => {
   assertValidQuantumPublicKey(publicKey);
 
+  const dataBytes = encoder.encode(data);
+
+  if (dataBytes.length >= 255) {
+    throw new Error("Data length must be less than 255");
+  }
+
+  const fakePrefixSize = 255 - dataBytes.length;
+  const fakePrefix = randomBytes(fakePrefixSize);
+  // Create padded data: [prefix_size(1 byte)][fake_prefix(1-254 bytes)][actual_data]
+  const paddedData = new Uint8Array(1 + fakePrefixSize + dataBytes.length);
+  paddedData[0] = fakePrefixSize;
+  paddedData.set(fakePrefix, 1);
+  paddedData.set(dataBytes, 1 + fakePrefixSize);
+
   // Convert public key from hex to bytes
   const publicKeyBytes = toBytes(publicKey);
 
@@ -87,9 +102,8 @@ export const encryptQuantum = (data: string, publicKey: Hex): Hex => {
 
   // Encrypt data with AES-256-GCM
   const iv = randomBytes(12);
-  const rawData = encoder.encode(data);
   const aes = gcm(aesKey, iv);
-  const ciphertext = aes.encrypt(rawData);
+  const ciphertext = aes.encrypt(paddedData);
 
   // Format: iv(12) + kemCiphertext(1088) + ciphertext(variable)
   return `${toHex(iv)}${toHex(kemCiphertext).slice(2)}${toHex(ciphertext).slice(2)}` as Hex;
@@ -100,6 +114,7 @@ export const encryptQuantum = (data: string, publicKey: Hex): Hex => {
  * @param secretKey Your ML-KEM-768 secret key (0x-prefixed hex string, 2400 bytes)
  * @param encodedData Encrypted data from encryptQuantum()
  * @returns Decrypted string
+ * @description Automatically removes fake prefix padding added during encryption
  */
 export const decryptQuantum = (secretKey: Hex, encodedData: Hex): string => {
   assertValidQuantumSecretKey(secretKey);
@@ -120,6 +135,13 @@ export const decryptQuantum = (secretKey: Hex, encodedData: Hex): string => {
 
   // Decrypt with AES-256-GCM
   const aes = gcm(aesKey, iv);
+  const decryptedBytes = aes.decrypt(ciphertext);
+
+  // Read the fake prefix size from first byte
+  const fakePrefixSize = decryptedBytes[0];
+
+  // Skip header (1 byte) and fake prefix, return actual data
+  const actualData = decryptedBytes.slice(1 + fakePrefixSize);
 
-  return decoder.decode(aes.decrypt(ciphertext));
+  return decoder.decode(actualData);
 };

src/qcrypt.ts

@@ -1,22 +1,27 @@
 import { isHex } from "viem";
 import { privateKeyToAccount, generatePrivateKey } from "viem/accounts";
 import { encrypt, decrypt } from "../src/crypt.ts";
-import * as fs from "fs";
 
 describe("crypt", () => {
   const privKey = generatePrivateKey();
   const account = privateKeyToAccount(privKey);
 
   const hexData = `0xa5eaba8f6b292d059d9e8c3a2f1b16af`;
-  const jsonData = fs.readFileSync("./test/mocks/arbitraryData.json", "utf8");
 
   describe("encrypt", () => {
     it("should encrypt hex string", () => {
       expect(isHex(encrypt(hexData, account.publicKey))).toBeTruthy();
     });
 
-    it("should encrypt json string", () => {
-      expect(isHex(encrypt(jsonData, account.publicKey))).toBeTruthy();
+    it("should encrypt json string (small)", () => {
+      const smallJson = JSON.stringify({
+        name: "Alice",
+        age: 30,
+        active: true,
+      });
+      const encrypted = encrypt(smallJson, account.publicKey);
+      expect(isHex(encrypted)).toBeTruthy();
+      expect(decrypt(privKey, encrypted)).toBe(smallJson);
     });
 
     it("should encrypt empty string", () => {
@@ -25,11 +30,18 @@ describe("crypt", () => {
       expect(decrypt(privKey, encrypted)).toBe("");
     });
 
-    it("should encrypt large data", () => {
-      const largeData = "x".repeat(10000);
-      const encrypted = encrypt(largeData, account.publicKey);
+    it("should encrypt maximum allowed data (254 bytes)", () => {
+      const maxData = "x".repeat(254);
+      const encrypted = encrypt(maxData, account.publicKey);
       expect(isHex(encrypted)).toBeTruthy();
-      expect(decrypt(privKey, encrypted)).toBe(largeData);
+      expect(decrypt(privKey, encrypted)).toBe(maxData);
+    });
+
+    it("should throw error for data >= 255 bytes", () => {
+      const tooLarge = "x".repeat(255);
+      expect(() => encrypt(tooLarge, account.publicKey)).toThrow(
+        "Data length must be less than 255",
+      );
     });
 
     it("should encrypt unicode data", () => {
@@ -70,20 +82,25 @@ describe("crypt", () => {
       expect(decrypt(privKey, encryptedData)).toBe(hexData);
     });
 
-    it("should decrypt json string", () => {
-      const encryptedData = encrypt(jsonData, account.publicKey);
-      expect(decrypt(privKey, encryptedData)).toBe(jsonData);
+    it("should decrypt json string (small)", () => {
+      const smallJson = JSON.stringify({
+        name: "Bob",
+        id: 123,
+        verified: false,
+      });
+      const encryptedData = encrypt(smallJson, account.publicKey);
+      expect(decrypt(privKey, encryptedData)).toBe(smallJson);
     });
 
     it("should decrypt empty string", () => {
       const encryptedData = encrypt("", account.publicKey);
       expect(decrypt(privKey, encryptedData)).toBe("");
     });
 
-    it("should decrypt large data", () => {
-      const largeData = "x".repeat(10000);
-      const encryptedData = encrypt(largeData, account.publicKey);
-      expect(decrypt(privKey, encryptedData)).toBe(largeData);
+    it("should decrypt maximum allowed data (254 bytes)", () => {
+      const maxData = "x".repeat(254);
+      const encryptedData = encrypt(maxData, account.publicKey);
+      expect(decrypt(privKey, encryptedData)).toBe(maxData);
     });
 
     it("should decrypt unicode data", () => {
@@ -147,10 +164,17 @@ describe("crypt", () => {
   });
 
   describe("edge cases", () => {
-    it("should handle very long strings", () => {
-      const longString = "a".repeat(100000);
-      const encrypted = encrypt(longString, account.publicKey);
-      expect(decrypt(privKey, encrypted)).toBe(longString);
+    it("should handle maximum size strings (254 bytes)", () => {
+      const maxString = "a".repeat(254);
+      const encrypted = encrypt(maxString, account.publicKey);
+      expect(decrypt(privKey, encrypted)).toBe(maxString);
+    });
+
+    it("should throw for strings over 254 bytes", () => {
+      const tooLong = "a".repeat(255);
+      expect(() => encrypt(tooLong, account.publicKey)).toThrow(
+        "Data length must be less than 255",
+      );
     });
 
     it("should handle null bytes in data", () => {
@@ -197,4 +221,85 @@ describe("crypt", () => {
       expect(encrypted1).not.toBe(encrypted2);
     });
   });
+
+  describe("length obfuscation", () => {
+    it("should produce same length for all plaintexts (fixed 255 bytes)", () => {
+      const data1 = "short";
+      const data2 = "x".repeat(254);
+      const data3 = "";
+
+      const encrypted1 = encrypt(data1, account.publicKey);
+      const encrypted2 = encrypt(data2, account.publicKey);
+      const encrypted3 = encrypt(data3, account.publicKey);
+
+      // All should be same length (255 bytes padded + overhead)
+      expect(encrypted1.length).toBe(encrypted2.length);
+      expect(encrypted2.length).toBe(encrypted3.length);
+    });
+
+    it("should pad to exactly 255 bytes before encryption", () => {
+      // All encrypted data should be same length regardless of input
+      const data1 = "test";
+      const data2 = "";
+      const data3 = "x".repeat(100);
+
+      const encrypted1 = encrypt(data1, account.publicKey);
+      const encrypted2 = encrypt(data2, account.publicKey);
+      const encrypted3 = encrypt(data3, account.publicKey);
+
+      // All should be exactly the same length
+      expect(encrypted1.length).toBe(encrypted2.length);
+      expect(encrypted2.length).toBe(encrypted3.length);
+    });
+
+    it("should correctly decrypt data with different sizes", () => {
+      const testData = [
+        "",
+        "a",
+        "test data",
+        "x".repeat(50),
+        "x".repeat(100),
+        "x".repeat(254),
+      ];
+
+      for (const data of testData) {
+        const encrypted = encrypt(data, account.publicKey);
+        const decrypted = decrypt(privKey, encrypted);
+        expect(decrypted).toBe(data);
+      }
+    });
+
+    it("should handle maximum padding (254 bytes for empty string)", () => {
+      const data = "";
+      const encrypted = encrypt(data, account.publicKey);
+      const decrypted = decrypt(privKey, encrypted);
+      expect(decrypted).toBe(data);
+
+      // Should be same length as any other encryption
+      const other = encrypt("test", account.publicKey);
+      expect(encrypted.length).toBe(other.length);
+    });
+
+    it("should handle minimum padding (1 byte for 254-byte string)", () => {
+      const data = "x".repeat(254);
+      const encrypted = encrypt(data, account.publicKey);
+      const decrypted = decrypt(privKey, encrypted);
+      expect(decrypted).toBe(data);
+
+      // Should be same length as any other encryption
+      const other = encrypt("test", account.publicKey);
+      expect(encrypted.length).toBe(other.length);
+    });
+
+    it("should throw error for corrupted data", () => {
+      const data = "test data";
+      const encrypted = encrypt(data, account.publicKey);
+
+      // Corrupt the encrypted data
+      const corruptedData = encrypted.slice(0, -10) + "ff".repeat(5);
+
+      // Should fail at AES decryption
+      expect(() => decrypt(privKey, corruptedData as `0x${string}`)).toThrow();
+    });
+  });
 });