@ursalock/crypto 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -18,11 +18,15 @@ interface IEncryptedPayload {
 interface ICryptoProvider {
     /**
      * Encrypt data with AES-GCM
+     *
+     * The IV is always generated internally using a CSPRNG.
+     * Callers must NOT supply their own IV — reusing an IV with the same
+     * key under AES-GCM is catastrophic (NIST SP 800-38D §8.3).
+     *
      * @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>;
+    encrypt(plaintext: Uint8Array, key: Uint8Array): Promise<IEncryptedPayload>;
     /**
      * Decrypt data with AES-GCM
      * @param encrypted Encrypted payload or combined bytes
@@ -47,14 +51,6 @@ interface IKeyDerivationProvider {
         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)
@@ -65,26 +61,34 @@ interface IRandomProvider {
  * Web Crypto API provider for AES-256-GCM
  */
 declare class WebCryptoProvider implements ICryptoProvider {
-    encrypt(plaintext: Uint8Array, key: Uint8Array, iv?: Uint8Array): Promise<IEncryptedPayload>;
+    encrypt(plaintext: Uint8Array, key: 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
+ * Current parameters based on OWASP 2026 high-security recommendations:
+ * - Memory: 128 MiB (OWASP "higher memory" profile)
+ * - Iterations: 4
  * - Parallelism: 4
+ *
+ * Legacy parameters (64 MiB / 3 iterations) are preserved for backward
+ * compatibility — existing vaults encrypted with the old defaults can
+ * still be decrypted by passing LEGACY_ARGON2_PARAMS explicitly.
+ *
+ * References:
+ * - OWASP Password Storage Cheat Sheet (2026 revision)
+ * - RFC 9106 §4 (Argon2 recommended parameters)
  */
 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) */
+    /** Memory cost in KiB (default: 131072 = 128 MiB) */
     memoryCost?: number;
-    /** Time cost / iterations (default: 3) */
+    /** Time cost / iterations (default: 4) */
     timeCost?: number;
     /** Parallelism (default: 4) */
     parallelism?: number;
@@ -108,8 +112,44 @@ interface DerivedKey {
  * // Save salt alongside encrypted data
  * // Use key for AES-256-GCM encryption
  * ```
+ *
+ * @example Decrypt data encrypted with older parameters
+ * ```ts
+ * const { key } = await deriveKey({
+ *   password: recoveryKeyBytes,
+ *   salt: storedSalt,
+ *   ...LEGACY_ARGON2_PARAMS,
+ * })
+ * ```
  */
 declare function deriveKey(options: DeriveKeyOptions): Promise<DerivedKey>;
+/**
+ * Default parameters for key derivation
+ *
+ * OWASP 2026 high-security recommendation:
+ * - 128 MiB memory, 4 iterations, parallelism 4
+ * - Provides ≈ 2× the work factor of the previous defaults
+ */
+declare const DEFAULT_ARGON2_PARAMS: {
+    readonly memoryCost: 131072;
+    readonly timeCost: 4;
+    readonly parallelism: 4;
+    readonly keyLength: 32;
+    readonly saltLength: 32;
+};
+/**
+ * Legacy Argon2id parameters (pre-2026)
+ *
+ * Use these when decrypting data that was encrypted with older defaults.
+ * New encryptions should always use DEFAULT_ARGON2_PARAMS.
+ */
+declare const LEGACY_ARGON2_PARAMS: {
+    readonly memoryCost: 65536;
+    readonly timeCost: 3;
+    readonly parallelism: 4;
+    readonly keyLength: 32;
+    readonly saltLength: 32;
+};
 
 /**
  * AES-256-GCM encryption/decryption using Web Crypto API
@@ -125,8 +165,7 @@ declare function deriveKey(options: DeriveKeyOptions): Promise<DerivedKey>;
  */
 
 /** Encrypted payload structure (backward compatibility) */
-interface EncryptedPayload extends IEncryptedPayload {
-}
+type EncryptedPayload = IEncryptedPayload;
 /**
  * Set custom crypto provider (for testing or alternative implementations)
  * @param provider Custom crypto provider
@@ -230,6 +269,13 @@ declare function recoveryKeyToBytes(key: string): Uint8Array;
  * @returns Raw base32 string (no dashes)
  */
 declare function bytesToRecoveryKey(bytes: Uint8Array): string;
+/**
+ * Format recovery key with dashes for readability
+ *
+ * @param raw - Raw base32 string
+ * @returns Formatted string with dashes every 4 characters
+ */
+declare function formatRecoveryKey(raw: string): string;
 
 /**
  * Crypto utilities
@@ -243,6 +289,39 @@ declare function randomBytes(length: number): Uint8Array;
  */
 declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
 
+/**
+ * HMAC-SHA256 using Web Crypto API
+ *
+ * Provides integrity verification for ciphertext in transit/storage.
+ * Uses HMAC-SHA256 as recommended by NIST SP 800-107 Rev. 1 §5.3
+ * and RFC 2104.
+ *
+ * Design rationale:
+ * - Separate HMAC key from encryption key (key separation principle)
+ * - Verify HMAC *before* attempting decryption (Encrypt-then-MAC)
+ * - Constant-time comparison via Web Crypto verify to prevent timing attacks
+ */
+/**
+ * Compute HMAC-SHA256 over arbitrary data
+ *
+ * @param data - Data to authenticate
+ * @param key  - HMAC key (any length; 32 bytes recommended)
+ * @returns Hex-encoded HMAC string (64 characters)
+ */
+declare function computeHmac(data: Uint8Array, key: Uint8Array): Promise<string>;
+/**
+ * Verify an HMAC-SHA256 tag
+ *
+ * Uses Web Crypto's verify() which performs constant-time comparison
+ * internally, preventing timing side-channel attacks.
+ *
+ * @param data         - Data that was authenticated
+ * @param key          - HMAC key (same key used for computeHmac)
+ * @param expectedHmac - Hex-encoded HMAC to verify against
+ * @returns True if HMAC is valid
+ */
+declare function verifyHmac(data: Uint8Array, key: Uint8Array, expectedHmac: string): Promise<boolean>;
+
 /**
  * JWK-based encryption using @z-base/cryptosuite
  * For use with ZKCredentials PRF-derived keys
@@ -282,4 +361,4 @@ declare function encryptStringWithJwk(plaintext: string, cipherJwk: 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 };
+export { DEFAULT_ARGON2_PARAMS, type DeriveKeyOptions, type DerivedKey, type EncryptedPayload, type ICryptoProvider, type IEncryptedPayload, type IKeyDerivationProvider, type JwkEncryptedPayload, LEGACY_ARGON2_PARAMS, type RecoveryKey, WebCryptoProvider, bytesToRecoveryKey, computeHmac, constantTimeEqual, decrypt, decryptString, decryptStringWithJwk, decryptWithJwk, deriveKey, encrypt, encryptString, encryptStringWithJwk, encryptWithJwk, formatRecoveryKey, generateRecoveryKey, getCryptoProvider, randomBytes, recoveryKeyToBytes, setCryptoProvider, validateRecoveryKey, verifyHmac };

package/dist/index.js

@@ -26,14 +26,14 @@ function concatBytes(...arrays) {
 // src/providers/web-crypto.ts
 var IV_LENGTH = 12;
 var WebCryptoProvider = class {
-  async encrypt(plaintext, key, iv) {
+  async encrypt(plaintext, key) {
     if (key.length !== 32) {
       throw new Error(`Invalid key length: expected 32 bytes, got ${key.length}`);
     }
-    const actualIv = iv ?? randomBytes(IV_LENGTH);
+    const actualIv = randomBytes(IV_LENGTH);
     const cryptoKey = await crypto.subtle.importKey(
       "raw",
-      key.buffer,
+      key.buffer.slice(key.byteOffset, key.byteOffset + key.byteLength),
       { name: "AES-GCM" },
       false,
       ["encrypt"]
@@ -42,7 +42,7 @@ var WebCryptoProvider = class {
       await crypto.subtle.encrypt(
         { name: "AES-GCM", iv: actualIv },
         cryptoKey,
-        plaintext.buffer
+        plaintext.buffer.slice(plaintext.byteOffset, plaintext.byteOffset + plaintext.byteLength)
       )
     );
     const combined = concatBytes(actualIv, ciphertext);
@@ -66,7 +66,7 @@ var WebCryptoProvider = class {
     }
     const cryptoKey = await crypto.subtle.importKey(
       "raw",
-      key.buffer,
+      key.buffer.slice(key.byteOffset, key.byteOffset + key.byteLength),
       { name: "AES-GCM" },
       false,
       ["decrypt"]
@@ -75,7 +75,7 @@ var WebCryptoProvider = class {
       const plaintext = await crypto.subtle.decrypt(
         { name: "AES-GCM", iv },
         cryptoKey,
-        ciphertext.buffer
+        ciphertext.buffer.slice(ciphertext.byteOffset, ciphertext.byteOffset + ciphertext.byteLength)
       );
       return new Uint8Array(plaintext);
     } catch (error) {
@@ -90,9 +90,9 @@ async function deriveKey(options) {
   const {
     password,
     salt = randomBytes(32),
-    memoryCost = 65536,
-    // 64 MiB
-    timeCost = 3,
+    memoryCost = 131072,
+    // 128 MiB — OWASP 2026 high-security recommendation
+    timeCost = 4,
     parallelism = 4,
     keyLength = 32
   } = options;
@@ -110,6 +110,22 @@ async function deriveKey(options) {
     salt
   };
 }
+var DEFAULT_ARGON2_PARAMS = {
+  memoryCost: 131072,
+  // 128 MiB
+  timeCost: 4,
+  parallelism: 4,
+  keyLength: 32,
+  saltLength: 32
+};
+var LEGACY_ARGON2_PARAMS = {
+  memoryCost: 65536,
+  // 64 MiB
+  timeCost: 3,
+  parallelism: 4,
+  keyLength: 32,
+  saltLength: 32
+};
 
 // src/aes.ts
 var defaultProvider = new WebCryptoProvider();
@@ -145,10 +161,13 @@ function generateRecoveryKey() {
 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;
+  let valid = true;
+  for (let i = 0; i < clean.length; i++) {
+    if (!BASE32_ALPHABET.includes(clean[i])) {
+      valid = false;
+    }
   }
-  return true;
+  return valid;
 }
 function recoveryKeyToBytes(key) {
   const clean = key.replace(/[-\s]/g, "").toUpperCase();
@@ -206,6 +225,52 @@ function base32Decode(str) {
   return new Uint8Array(output);
 }
 
+// src/hmac.ts
+async function computeHmac(data, key) {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = new Uint8Array(
+    await crypto.subtle.sign("HMAC", cryptoKey, data)
+  );
+  return bytesToHex(signature);
+}
+async function verifyHmac(data, key, expectedHmac) {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"]
+  );
+  const expectedBytes = hexToBytes(expectedHmac);
+  return crypto.subtle.verify(
+    "HMAC",
+    cryptoKey,
+    expectedBytes,
+    data
+  );
+}
+function bytesToHex(bytes) {
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+function hexToBytes(hex) {
+  const len = hex.length >>> 1;
+  const bytes = new Uint8Array(len);
+  for (let i = 0; i < len; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
 // src/jwk.ts
 import { CipherCluster } from "@z-base/cryptosuite";
 async function encryptWithJwk(plaintext, cipherJwk) {
@@ -250,8 +315,11 @@ async function decryptStringWithJwk(encrypted, cipherJwk) {
   return new TextDecoder().decode(plaintext);
 }
 export {
+  DEFAULT_ARGON2_PARAMS,
+  LEGACY_ARGON2_PARAMS,
   WebCryptoProvider,
   bytesToRecoveryKey,
+  computeHmac,
   constantTimeEqual,
   decrypt,
   decryptString,
@@ -262,10 +330,12 @@ export {
   encryptString,
   encryptStringWithJwk,
   encryptWithJwk,
+  formatRecoveryKey,
   generateRecoveryKey,
   getCryptoProvider,
   randomBytes,
   recoveryKeyToBytes,
   setCryptoProvider,
-  validateRecoveryKey
+  validateRecoveryKey,
+  verifyHmac
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ursalock/crypto",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "E2EE crypto primitives for ursalock",
   "type": "module",
   "main": "./dist/index.js",