@ursalock/crypto 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -322,6 +322,59 @@ declare function computeHmac(data: Uint8Array, key: Uint8Array): Promise<string>
  */
 declare function verifyHmac(data: Uint8Array, key: Uint8Array, expectedHmac: string): Promise<boolean>;
 
+/**
+ * HKDF-SHA256 key derivation (RFC 5869)
+ *
+ * Uses Web Crypto's native HKDF implementation for deriving sub-keys
+ * from a master key. This is used to generate vault-specific keys for
+ * encryption, HMAC, and indexing from a single master key.
+ *
+ * Design rationale:
+ * - Key separation: Each purpose gets its own derived key
+ * - Context binding: Vault UID prevents key reuse across vaults
+ * - Versioned info strings: "ursalock:v1:..." allows future changes
+ * - Domain separation: Different info → different keys (collision-free)
+ */
+/** Vault-specific derived keys */
+interface VaultKeys {
+    /** AES-256-GCM encryption key for vault documents */
+    encryptionKey: Uint8Array;
+    /** HMAC-SHA256 key for integrity verification */
+    hmacKey: Uint8Array;
+    /** Key for encrypted search indexes (future use) */
+    indexKey: Uint8Array;
+}
+/**
+ * Derive a sub-key using HKDF-SHA256 (RFC 5869)
+ *
+ * Uses Web Crypto's native HKDF implementation.
+ *
+ * @param ikm - Input keying material (master key)
+ * @param info - Context string (e.g., "ursalock:vault:abc123:encrypt") or raw bytes
+ * @param salt - Optional salt (default: empty buffer)
+ * @param length - Output key length in bytes (default: 32 for AES-256)
+ * @returns Derived key material
+ */
+declare function hkdf(ikm: Uint8Array, info: string | Uint8Array, salt?: Uint8Array, length?: number): Promise<Uint8Array>;
+/**
+ * Derive a complete set of vault keys from a master key
+ *
+ * Uses HKDF with vault-specific context strings to derive:
+ * - encryptionKey: for AES-256-GCM document encryption
+ * - hmacKey: for integrity verification (Encrypt-then-MAC)
+ * - indexKey: for encrypted search indexes (future)
+ *
+ * Context format: "ursalock:v1:<purpose>:<vaultUid>"
+ * - Versioned to allow future changes
+ * - Vault UID prevents key reuse across vaults
+ * - Purpose string provides domain separation
+ *
+ * @param masterKey - Master key (from Argon2id or ZKC PRF)
+ * @param vaultUid - Vault unique identifier (used as context)
+ * @returns Set of derived vault keys
+ */
+declare function deriveVaultKeys(masterKey: Uint8Array, vaultUid: string): Promise<VaultKeys>;
+
 /**
  * JWK-based encryption using @z-base/cryptosuite
  * For use with ZKCredentials PRF-derived keys
@@ -361,4 +414,4 @@ declare function encryptStringWithJwk(plaintext: string, cipherJwk: CipherJWK):
  */
 declare function decryptStringWithJwk(encrypted: Uint8Array | JwkEncryptedPayload, cipherJwk: CipherJWK): Promise<string>;
 
-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 };
+export { DEFAULT_ARGON2_PARAMS, type DeriveKeyOptions, type DerivedKey, type EncryptedPayload, type ICryptoProvider, type IEncryptedPayload, type IKeyDerivationProvider, type JwkEncryptedPayload, LEGACY_ARGON2_PARAMS, type RecoveryKey, type VaultKeys, WebCryptoProvider, bytesToRecoveryKey, computeHmac, constantTimeEqual, decrypt, decryptString, decryptStringWithJwk, decryptWithJwk, deriveKey, deriveVaultKeys, encrypt, encryptString, encryptStringWithJwk, encryptWithJwk, formatRecoveryKey, generateRecoveryKey, getCryptoProvider, hkdf, randomBytes, recoveryKeyToBytes, setCryptoProvider, validateRecoveryKey, verifyHmac };

package/dist/index.js

@@ -271,6 +271,39 @@ function hexToBytes(hex) {
   return bytes;
 }
 
+// src/hkdf.ts
+async function hkdf(ikm, info, salt, length = 32) {
+  const infoBytes = typeof info === "string" ? new TextEncoder().encode(info) : info;
+  const actualSalt = salt ?? new Uint8Array(0);
+  const baseKey = await crypto.subtle.importKey(
+    "raw",
+    ikm.buffer.slice(ikm.byteOffset, ikm.byteOffset + ikm.byteLength),
+    { name: "HKDF" },
+    false,
+    ["deriveBits"]
+  );
+  const derivedBits = await crypto.subtle.deriveBits(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: actualSalt.buffer.slice(actualSalt.byteOffset, actualSalt.byteOffset + actualSalt.byteLength),
+      info: infoBytes.buffer.slice(infoBytes.byteOffset, infoBytes.byteOffset + infoBytes.byteLength)
+    },
+    baseKey,
+    length * 8
+    // Convert bytes to bits
+  );
+  return new Uint8Array(derivedBits);
+}
+async function deriveVaultKeys(masterKey, vaultUid) {
+  const [encryptionKey, hmacKey, indexKey] = await Promise.all([
+    hkdf(masterKey, `ursalock:v1:encrypt:${vaultUid}`),
+    hkdf(masterKey, `ursalock:v1:hmac:${vaultUid}`),
+    hkdf(masterKey, `ursalock:v1:index:${vaultUid}`)
+  ]);
+  return { encryptionKey, hmacKey, indexKey };
+}
+
 // src/jwk.ts
 import { CipherCluster } from "@z-base/cryptosuite";
 async function encryptWithJwk(plaintext, cipherJwk) {
@@ -326,6 +359,7 @@ export {
   decryptStringWithJwk,
   decryptWithJwk,
   deriveKey,
+  deriveVaultKeys,
   encrypt,
   encryptString,
   encryptStringWithJwk,
@@ -333,6 +367,7 @@ export {
   formatRecoveryKey,
   generateRecoveryKey,
   getCryptoProvider,
+  hkdf,
   randomBytes,
   recoveryKeyToBytes,
   setCryptoProvider,

package/package.json

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