@ursalock/crypto 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,285 @@
+import { CipherJWK } from '@z-base/cryptosuite';
+export { CipherJWK } from '@z-base/cryptosuite';
+
+/**
+ * Interfaces for crypto operations (Dependency Inversion Principle)
+ * Allows testing and alternative implementations
+ */
+/** Encrypted data structure */
+interface IEncryptedPayload {
+    /** Initialization vector */
+    iv: Uint8Array;
+    /** Ciphertext with auth tag */
+    ciphertext: Uint8Array;
+    /** Combined iv + ciphertext for storage */
+    combined: Uint8Array;
+}
+/** Crypto provider interface for encryption/decryption */
+interface ICryptoProvider {
+    /**
+     * Encrypt data with AES-GCM
+     * @param plaintext Data to encrypt
+     * @param key 256-bit encryption key
+     * @param iv Optional IV (generated if not provided)
+     */
+    encrypt(plaintext: Uint8Array, key: Uint8Array, iv?: Uint8Array): Promise<IEncryptedPayload>;
+    /**
+     * Decrypt data with AES-GCM
+     * @param encrypted Encrypted payload or combined bytes
+     * @param key 256-bit encryption key
+     */
+    decrypt(encrypted: Uint8Array | IEncryptedPayload, key: Uint8Array): Promise<Uint8Array>;
+}
+/** Key derivation provider interface */
+interface IKeyDerivationProvider {
+    /**
+     * Derive encryption key from password
+     * @param password Password bytes
+     * @param salt Salt (generated if not provided)
+     * @param options Derivation options
+     */
+    deriveKey(password: Uint8Array, salt?: Uint8Array, options?: {
+        iterations?: number;
+        memorySize?: number;
+        parallelism?: number;
+    }): Promise<{
+        key: Uint8Array;
+        salt: Uint8Array;
+    }>;
+}
+/** Random number generator interface */
+interface IRandomProvider {
+    /**
+     * Generate cryptographically secure random bytes
+     * @param length Number of bytes to generate
+     */
+    randomBytes(length: number): Uint8Array;
+}
+
+/**
+ * Web Crypto API implementation (Concrete provider)
+ * Implements ICryptoProvider using browser's native crypto
+ */
+
+/**
+ * Web Crypto API provider for AES-256-GCM
+ */
+declare class WebCryptoProvider implements ICryptoProvider {
+    encrypt(plaintext: Uint8Array, key: Uint8Array, iv?: Uint8Array): Promise<IEncryptedPayload>;
+    decrypt(encrypted: Uint8Array | IEncryptedPayload, key: Uint8Array): Promise<Uint8Array>;
+}
+
+/**
+ * Key derivation using Argon2id
+ *
+ * Parameters based on OWASP 2026 recommendations:
+ * - Memory: 64 MiB
+ * - Iterations: 3
+ * - Parallelism: 4
+ */
+interface DeriveKeyOptions {
+    /** Password or recovery key bytes */
+    password: Uint8Array;
+    /** Salt (32 bytes recommended, auto-generated if not provided) */
+    salt?: Uint8Array;
+    /** Memory cost in KiB (default: 65536 = 64 MiB) */
+    memoryCost?: number;
+    /** Time cost / iterations (default: 3) */
+    timeCost?: number;
+    /** Parallelism (default: 4) */
+    parallelism?: number;
+    /** Output key length in bytes (default: 32 for AES-256) */
+    keyLength?: number;
+}
+interface DerivedKey {
+    /** The derived key bytes */
+    key: Uint8Array;
+    /** The salt used (save this for re-derivation) */
+    salt: Uint8Array;
+}
+/**
+ * Derive an encryption key from a password/recovery key using Argon2id
+ *
+ * @example
+ * ```ts
+ * const { key, salt } = await deriveKey({
+ *   password: recoveryKeyBytes,
+ * })
+ * // Save salt alongside encrypted data
+ * // Use key for AES-256-GCM encryption
+ * ```
+ */
+declare function deriveKey(options: DeriveKeyOptions): Promise<DerivedKey>;
+
+/**
+ * AES-256-GCM encryption/decryption using Web Crypto API
+ *
+ * - 256-bit key
+ * - 96-bit (12 byte) IV (NIST recommended for GCM)
+ * - 128-bit auth tag (included in ciphertext by Web Crypto)
+ *
+ * Refactored to follow Dependency Inversion Principle:
+ * - Uses ICryptoProvider interface
+ * - Default implementation uses WebCryptoProvider
+ * - Can inject alternative implementations for testing
+ */
+
+/** Encrypted payload structure (backward compatibility) */
+interface EncryptedPayload extends IEncryptedPayload {
+}
+/**
+ * Set custom crypto provider (for testing or alternative implementations)
+ * @param provider Custom crypto provider
+ */
+declare function setCryptoProvider(provider: ICryptoProvider): void;
+/**
+ * Get current crypto provider
+ */
+declare function getCryptoProvider(): ICryptoProvider;
+/**
+ * Encrypt data using AES-256-GCM
+ *
+ * @param plaintext - Data to encrypt
+ * @param key - 256-bit encryption key
+ * @param provider - Optional crypto provider (uses default if not provided)
+ * @returns Encrypted payload with IV
+ *
+ * @example
+ * ```ts
+ * const data = new TextEncoder().encode(JSON.stringify(state))
+ * const encrypted = await encrypt(data, key)
+ * // Store encrypted.combined (iv + ciphertext)
+ * ```
+ */
+declare function encrypt(plaintext: Uint8Array, key: Uint8Array, provider?: ICryptoProvider): Promise<EncryptedPayload>;
+/**
+ * Decrypt data using AES-256-GCM
+ *
+ * @param encrypted - Combined IV + ciphertext, or separate components
+ * @param key - 256-bit encryption key
+ * @param provider - Optional crypto provider (uses default if not provided)
+ * @returns Decrypted plaintext
+ *
+ * @example
+ * ```ts
+ * const plaintext = await decrypt(encrypted.combined, key)
+ * const state = JSON.parse(new TextDecoder().decode(plaintext))
+ * ```
+ */
+declare function decrypt(encrypted: Uint8Array | EncryptedPayload, key: Uint8Array, provider?: ICryptoProvider): Promise<Uint8Array>;
+/**
+ * Encrypt a string (convenience wrapper)
+ */
+declare function encryptString(plaintext: string, key: Uint8Array, provider?: ICryptoProvider): Promise<EncryptedPayload>;
+/**
+ * Decrypt to a string (convenience wrapper)
+ */
+declare function decryptString(encrypted: Uint8Array | EncryptedPayload, key: Uint8Array, provider?: ICryptoProvider): Promise<string>;
+
+/**
+ * Recovery key generation and validation
+ *
+ * Recovery key format:
+ * - 256 bits of entropy (32 bytes)
+ * - Encoded as base32 (RFC 4648, no padding)
+ * - Split into groups of 4 chars with dashes for readability
+ * - Total: 52 characters + 12 dashes = 64 characters
+ *
+ * Example: ABCD-EFGH-IJKL-MNOP-QRST-UVWX-YZ23-4567-ABCD-EFGH-IJKL-MNOP-Q
+ */
+/** Recovery key with metadata */
+interface RecoveryKey {
+    /** Human-readable recovery key with dashes */
+    formatted: string;
+    /** Raw recovery key without dashes */
+    raw: string;
+    /** Original bytes (32 bytes = 256 bits) */
+    bytes: Uint8Array;
+}
+/**
+ * Generate a new recovery key
+ *
+ * @returns Recovery key in multiple formats
+ *
+ * @example
+ * ```ts
+ * const recovery = generateRecoveryKey()
+ * console.log(recovery.formatted)
+ * // "ABCD-EFGH-IJKL-MNOP-QRST-UVWX-YZ23-4567-ABCD-EFGH-IJKL-MNOP-Q"
+ * ```
+ */
+declare function generateRecoveryKey(): RecoveryKey;
+/**
+ * Validate a recovery key format
+ *
+ * @param key - Recovery key (with or without dashes)
+ * @returns True if valid format
+ */
+declare function validateRecoveryKey(key: string): boolean;
+/**
+ * Convert recovery key string to bytes
+ *
+ * @param key - Recovery key (with or without dashes)
+ * @returns 32 bytes
+ */
+declare function recoveryKeyToBytes(key: string): Uint8Array;
+/**
+ * Convert bytes to recovery key string
+ *
+ * @param bytes - 32 bytes
+ * @returns Raw base32 string (no dashes)
+ */
+declare function bytesToRecoveryKey(bytes: Uint8Array): string;
+
+/**
+ * Crypto utilities
+ */
+/**
+ * Generate cryptographically secure random bytes
+ */
+declare function randomBytes(length: number): Uint8Array;
+/**
+ * Constant-time comparison to prevent timing attacks
+ */
+declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
+
+/**
+ * JWK-based encryption using @z-base/cryptosuite
+ * For use with ZKCredentials PRF-derived keys
+ */
+
+/** Encrypted payload with IV and ciphertext */
+interface JwkEncryptedPayload {
+    /** Initialization vector (12 bytes for AES-GCM) */
+    iv: Uint8Array;
+    /** Encrypted data */
+    ciphertext: Uint8Array;
+    /** Combined iv + ciphertext for easy storage */
+    combined: Uint8Array;
+}
+/**
+ * Encrypt data using AES-256-GCM with a CipherJWK
+ *
+ * @param plaintext - Data to encrypt
+ * @param cipherJwk - JWK key from ZKCredentials
+ * @returns Encrypted payload with IV
+ */
+declare function encryptWithJwk(plaintext: Uint8Array, cipherJwk: CipherJWK): Promise<JwkEncryptedPayload>;
+/**
+ * Decrypt data using AES-256-GCM with a CipherJWK
+ *
+ * @param encrypted - Combined IV + ciphertext, or separate components
+ * @param cipherJwk - JWK key from ZKCredentials
+ * @returns Decrypted plaintext
+ */
+declare function decryptWithJwk(encrypted: Uint8Array | JwkEncryptedPayload, cipherJwk: CipherJWK): Promise<Uint8Array>;
+/**
+ * Encrypt a string using CipherJWK
+ */
+declare function encryptStringWithJwk(plaintext: string, cipherJwk: CipherJWK): Promise<JwkEncryptedPayload>;
+/**
+ * Decrypt to a string using CipherJWK
+ */
+declare function decryptStringWithJwk(encrypted: Uint8Array | JwkEncryptedPayload, cipherJwk: CipherJWK): Promise<string>;
+
+export { type DeriveKeyOptions, type EncryptedPayload, type ICryptoProvider, type IEncryptedPayload, type IKeyDerivationProvider, type IRandomProvider, type JwkEncryptedPayload, type RecoveryKey, WebCryptoProvider, bytesToRecoveryKey, constantTimeEqual, decrypt, decryptString, decryptStringWithJwk, decryptWithJwk, deriveKey, encrypt, encryptString, encryptStringWithJwk, encryptWithJwk, generateRecoveryKey, getCryptoProvider, randomBytes, recoveryKeyToBytes, setCryptoProvider, validateRecoveryKey };

package/dist/index.js

@@ -0,0 +1,271 @@
+// src/utils.ts
+function randomBytes(length) {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a[i] ^ b[i];
+  }
+  return result === 0;
+}
+function concatBytes(...arrays) {
+  const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const arr of arrays) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}
+
+// src/providers/web-crypto.ts
+var IV_LENGTH = 12;
+var WebCryptoProvider = class {
+  async encrypt(plaintext, key, iv) {
+    if (key.length !== 32) {
+      throw new Error(`Invalid key length: expected 32 bytes, got ${key.length}`);
+    }
+    const actualIv = iv ?? randomBytes(IV_LENGTH);
+    const cryptoKey = await crypto.subtle.importKey(
+      "raw",
+      key.buffer,
+      { name: "AES-GCM" },
+      false,
+      ["encrypt"]
+    );
+    const ciphertext = new Uint8Array(
+      await crypto.subtle.encrypt(
+        { name: "AES-GCM", iv: actualIv },
+        cryptoKey,
+        plaintext.buffer
+      )
+    );
+    const combined = concatBytes(actualIv, ciphertext);
+    return { iv: actualIv, ciphertext, combined };
+  }
+  async decrypt(encrypted, key) {
+    if (key.length !== 32) {
+      throw new Error(`Invalid key length: expected 32 bytes, got ${key.length}`);
+    }
+    let iv;
+    let ciphertext;
+    if (encrypted instanceof Uint8Array) {
+      if (encrypted.length < IV_LENGTH + 16) {
+        throw new Error("Invalid encrypted data: too short");
+      }
+      iv = encrypted.slice(0, IV_LENGTH);
+      ciphertext = encrypted.slice(IV_LENGTH);
+    } else {
+      iv = encrypted.iv;
+      ciphertext = encrypted.ciphertext;
+    }
+    const cryptoKey = await crypto.subtle.importKey(
+      "raw",
+      key.buffer,
+      { name: "AES-GCM" },
+      false,
+      ["decrypt"]
+    );
+    try {
+      const plaintext = await crypto.subtle.decrypt(
+        { name: "AES-GCM", iv },
+        cryptoKey,
+        ciphertext.buffer
+      );
+      return new Uint8Array(plaintext);
+    } catch (error) {
+      throw new Error("Decryption failed: invalid key or corrupted data");
+    }
+  }
+};
+
+// src/derive.ts
+import { argon2id } from "hash-wasm";
+async function deriveKey(options) {
+  const {
+    password,
+    salt = randomBytes(32),
+    memoryCost = 65536,
+    // 64 MiB
+    timeCost = 3,
+    parallelism = 4,
+    keyLength = 32
+  } = options;
+  const hash = await argon2id({
+    password,
+    salt,
+    memorySize: memoryCost,
+    iterations: timeCost,
+    parallelism,
+    hashLength: keyLength,
+    outputType: "binary"
+  });
+  return {
+    key: new Uint8Array(hash),
+    salt
+  };
+}
+
+// src/aes.ts
+var defaultProvider = new WebCryptoProvider();
+function setCryptoProvider(provider) {
+  defaultProvider = provider;
+}
+function getCryptoProvider() {
+  return defaultProvider;
+}
+async function encrypt(plaintext, key, provider = defaultProvider) {
+  return provider.encrypt(plaintext, key);
+}
+async function decrypt(encrypted, key, provider = defaultProvider) {
+  return provider.decrypt(encrypted, key);
+}
+async function encryptString(plaintext, key, provider) {
+  const data = new TextEncoder().encode(plaintext);
+  return encrypt(data, key, provider);
+}
+async function decryptString(encrypted, key, provider) {
+  const plaintext = await decrypt(encrypted, key, provider);
+  return new TextDecoder().decode(plaintext);
+}
+
+// src/recovery.ts
+var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+function generateRecoveryKey() {
+  const bytes = randomBytes(32);
+  const raw = bytesToRecoveryKey(bytes);
+  const formatted = formatRecoveryKey(raw);
+  return { formatted, raw, bytes };
+}
+function validateRecoveryKey(key) {
+  const clean = key.replace(/[-\s]/g, "").toUpperCase();
+  if (clean.length !== 52) return false;
+  for (const char of clean) {
+    if (!BASE32_ALPHABET.includes(char)) return false;
+  }
+  return true;
+}
+function recoveryKeyToBytes(key) {
+  const clean = key.replace(/[-\s]/g, "").toUpperCase();
+  if (!validateRecoveryKey(clean)) {
+    throw new Error("Invalid recovery key format");
+  }
+  return base32Decode(clean);
+}
+function bytesToRecoveryKey(bytes) {
+  if (bytes.length !== 32) {
+    throw new Error(`Invalid bytes length: expected 32, got ${bytes.length}`);
+  }
+  return base32Encode(bytes);
+}
+function formatRecoveryKey(raw) {
+  const chunks = [];
+  for (let i = 0; i < raw.length; i += 4) {
+    chunks.push(raw.slice(i, i + 4));
+  }
+  return chunks.join("-");
+}
+function base32Encode(bytes) {
+  let result = "";
+  let bits = 0;
+  let value = 0;
+  for (const byte of bytes) {
+    value = value << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      result += BASE32_ALPHABET[value >> bits & 31];
+    }
+  }
+  if (bits > 0) {
+    result += BASE32_ALPHABET[value << 5 - bits & 31];
+  }
+  return result;
+}
+function base32Decode(str) {
+  const output = [];
+  let bits = 0;
+  let value = 0;
+  for (const char of str) {
+    const index = BASE32_ALPHABET.indexOf(char);
+    if (index === -1) {
+      throw new Error(`Invalid base32 character: ${char}`);
+    }
+    value = value << 5 | index;
+    bits += 5;
+    while (bits >= 8) {
+      bits -= 8;
+      output.push(value >> bits & 255);
+    }
+  }
+  return new Uint8Array(output);
+}
+
+// src/jwk.ts
+import { CipherCluster } from "@z-base/cryptosuite";
+async function encryptWithJwk(plaintext, cipherJwk) {
+  const result = await CipherCluster.encrypt(cipherJwk, plaintext);
+  const iv = result.iv;
+  const ciphertext = new Uint8Array(result.ciphertext);
+  const combined = new Uint8Array(iv.length + ciphertext.length);
+  combined.set(iv, 0);
+  combined.set(ciphertext, iv.length);
+  return { iv, ciphertext, combined };
+}
+async function decryptWithJwk(encrypted, cipherJwk) {
+  let iv;
+  let ciphertext;
+  if (encrypted instanceof Uint8Array) {
+    if (encrypted.length < 12 + 16) {
+      throw new Error("Invalid encrypted data: too short");
+    }
+    iv = encrypted.slice(0, 12);
+    ciphertext = encrypted.slice(12);
+  } else {
+    iv = encrypted.iv;
+    ciphertext = encrypted.ciphertext;
+  }
+  try {
+    const ciphertextBuffer = new ArrayBuffer(ciphertext.length);
+    new Uint8Array(ciphertextBuffer).set(ciphertext);
+    return await CipherCluster.decrypt(cipherJwk, {
+      iv,
+      ciphertext: ciphertextBuffer
+    });
+  } catch {
+    throw new Error("Decryption failed: invalid key or corrupted data");
+  }
+}
+async function encryptStringWithJwk(plaintext, cipherJwk) {
+  const data = new TextEncoder().encode(plaintext);
+  return encryptWithJwk(data, cipherJwk);
+}
+async function decryptStringWithJwk(encrypted, cipherJwk) {
+  const plaintext = await decryptWithJwk(encrypted, cipherJwk);
+  return new TextDecoder().decode(plaintext);
+}
+export {
+  WebCryptoProvider,
+  bytesToRecoveryKey,
+  constantTimeEqual,
+  decrypt,
+  decryptString,
+  decryptStringWithJwk,
+  decryptWithJwk,
+  deriveKey,
+  encrypt,
+  encryptString,
+  encryptStringWithJwk,
+  encryptWithJwk,
+  generateRecoveryKey,
+  getCryptoProvider,
+  randomBytes,
+  recoveryKeyToBytes,
+  setCryptoProvider,
+  validateRecoveryKey
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@ursalock/crypto",
+  "version": "0.2.1",
+  "description": "E2EE crypto primitives for ursalock",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@z-base/cryptosuite": "^1.0.1",
+    "hash-wasm": "^4.11.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "keywords": [
+    "encryption",
+    "e2ee",
+    "aes-256-gcm",
+    "argon2id",
+    "crypto",
+    "zero-knowledge",
+    "jwk"
+  ],
+  "license": "MIT",
+  "author": "Nicolas de Luz <ndlz@pm.me>",
+  "homepage": "https://github.com/nicodlz/ursalock#readme",
+  "bugs": {
+    "url": "https://github.com/nicodlz/ursalock/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicodlz/ursalock.git",
+    "directory": "packages/crypto"
+  }
+}