@docknetwork/wallet-sdk-wasm 1.5.14 → 1.7.6

package/src/services/edv/index.test.js

@@ -47,5 +47,234 @@ describe('EDVService', () => {
         expect(JSON.stringify(agreementKey)).toBe(derivedTestAgreementKey);
       });
     });
+
+    describe('deriveBiometricKey', () => {
+      it('should derive a key from biometric data', () => {
+        const biometricData = Buffer.from('mock-biometric-data');
+        const identifier = 'user@example.com';
+
+        const key = service.deriveBiometricKey(biometricData, identifier);
+
+        expect(key).toBeDefined();
+        expect(Buffer.isBuffer(key)).toBe(true);
+        expect(key.length).toBe(32); // HKDF_LENGTH
+      });
+
+      it('should produce consistent keys for same inputs', () => {
+        const biometricData = Buffer.from('mock-biometric-data');
+        const identifier = 'user@example.com';
+
+        const key1 = service.deriveBiometricKey(biometricData, identifier);
+        const key2 = service.deriveBiometricKey(biometricData, identifier);
+
+        expect(key1.equals(key2)).toBe(true);
+      });
+
+      it('should produce different keys for different identifiers', () => {
+        const biometricData = Buffer.from('mock-biometric-data');
+        const identifier1 = 'user1@example.com';
+        const identifier2 = 'user2@example.com';
+
+        const key1 = service.deriveBiometricKey(biometricData, identifier1);
+        const key2 = service.deriveBiometricKey(biometricData, identifier2);
+
+        expect(key1.equals(key2)).toBe(false);
+      });
+
+      it('should produce different keys for different biometric data', () => {
+        const biometricData1 = Buffer.from('mock-biometric-data-1');
+        const biometricData2 = Buffer.from('mock-biometric-data-2');
+        const identifier = 'user@example.com';
+
+        const key1 = service.deriveBiometricKey(biometricData1, identifier);
+        const key2 = service.deriveBiometricKey(biometricData2, identifier);
+
+        expect(key1.equals(key2)).toBe(false);
+      });
+    });
+
+    describe('deriveBiometricEncryptionKey', () => {
+      it('should derive encryption key and IV', async () => {
+        const biometricData = Buffer.from('mock-biometric-data');
+        const identifier = 'user@example.com';
+
+        const result = await service.deriveBiometricEncryptionKey(
+          biometricData,
+          identifier,
+        );
+
+        expect(result).toBeDefined();
+        expect(result.key).toBeDefined();
+        expect(result.iv).toBeDefined();
+        expect(Buffer.isBuffer(result.key)).toBe(true);
+        expect(Buffer.isBuffer(result.iv)).toBe(true);
+        expect(result.key.length).toBe(32); // HKDF_LENGTH
+        expect(result.iv.length).toBe(16); // AES-GCM IV length
+      });
+
+      it('should produce consistent keys but different IVs for same inputs', async () => {
+        const biometricData = Buffer.from('mock-biometric-data');
+        const identifier = 'user@example.com';
+
+        const result1 = await service.deriveBiometricEncryptionKey(
+          biometricData,
+          identifier,
+        );
+        const result2 = await service.deriveBiometricEncryptionKey(
+          biometricData,
+          identifier,
+        );
+
+        expect(result1.key.equals(result2.key)).toBe(true);
+        // IVs should be different (random)
+        expect(result1.iv.equals(result2.iv)).toBe(false);
+      });
+    });
+
+    describe('encryptMasterKey and decryptMasterKey', () => {
+      it('should encrypt and decrypt master key successfully', async () => {
+        const masterKey = new Uint8Array(32).fill(42);
+        const encryptionKey = Buffer.from(new Uint8Array(32).fill(1));
+        const iv = Buffer.from(new Uint8Array(16).fill(2));
+
+        const encrypted = await service.encryptMasterKey(
+          masterKey,
+          encryptionKey,
+          iv,
+        );
+        expect(encrypted).toBeDefined();
+        expect(encrypted instanceof Uint8Array).toBe(true);
+        expect(encrypted.length).toBeGreaterThan(0);
+
+        const decrypted = await service.decryptMasterKey(
+          encrypted,
+          encryptionKey,
+          iv,
+        );
+        expect(decrypted).toBeDefined();
+        expect(decrypted instanceof Uint8Array).toBe(true);
+        expect(new Uint8Array(decrypted)).toEqual(masterKey);
+      });
+
+      it('should fail to decrypt with wrong key', async () => {
+        const masterKey = new Uint8Array(32).fill(42);
+        const encryptionKey = Buffer.from(new Uint8Array(32).fill(1));
+        const wrongKey = Buffer.from(new Uint8Array(32).fill(99));
+        const iv = Buffer.from(new Uint8Array(16).fill(2));
+
+        const encrypted = await service.encryptMasterKey(
+          masterKey,
+          encryptionKey,
+          iv,
+        );
+
+        await expect(
+          service.decryptMasterKey(encrypted, wrongKey, iv),
+        ).rejects.toThrow('Decryption failed: Invalid key or corrupted data');
+      });
+
+      it('should fail to decrypt with wrong IV', async () => {
+        const masterKey = new Uint8Array(32).fill(42);
+        const encryptionKey = Buffer.from(new Uint8Array(32).fill(1));
+        const iv = Buffer.from(new Uint8Array(16).fill(2));
+        const wrongIv = Buffer.from(new Uint8Array(16).fill(99));
+
+        const encrypted = await service.encryptMasterKey(
+          masterKey,
+          encryptionKey,
+          iv,
+        );
+
+        await expect(
+          service.decryptMasterKey(encrypted, encryptionKey, wrongIv),
+        ).rejects.toThrow('Decryption failed: Invalid key or corrupted data');
+      });
+
+      it('should produce different ciphertext for same plaintext with different IVs', async () => {
+        const masterKey = new Uint8Array(32).fill(42);
+        const encryptionKey = Buffer.from(new Uint8Array(32).fill(1));
+        const iv1 = Buffer.from(new Uint8Array(16).fill(2));
+        const iv2 = Buffer.from(new Uint8Array(16).fill(3));
+
+        const encrypted1 = await service.encryptMasterKey(
+          masterKey,
+          encryptionKey,
+          iv1,
+        );
+        const encrypted2 = await service.encryptMasterKey(
+          masterKey,
+          encryptionKey,
+          iv2,
+        );
+
+        expect(encrypted1).not.toEqual(encrypted2);
+      });
+
+      it('should handle empty master key', async () => {
+        const masterKey = new Uint8Array(0);
+        const encryptionKey = Buffer.from(new Uint8Array(32).fill(1));
+        const iv = Buffer.from(new Uint8Array(16).fill(2));
+
+        const encrypted = await service.encryptMasterKey(
+          masterKey,
+          encryptionKey,
+          iv,
+        );
+        const decrypted = await service.decryptMasterKey(
+          encrypted,
+          encryptionKey,
+          iv,
+        );
+
+        expect(new Uint8Array(decrypted)).toEqual(masterKey);
+      });
+    });
+
+    describe('integration: biometric encryption workflow', () => {
+      it('should complete full encryption workflow', async () => {
+        const biometricData = Buffer.from('mock-biometric-data');
+        const identifier = 'user@example.com';
+        const masterKey = new Uint8Array(32).fill(123);
+
+        // Derive encryption key and IV from biometric data
+        const {key, iv} = await service.deriveBiometricEncryptionKey(
+          biometricData,
+          identifier,
+        );
+
+        // Encrypt master key
+        const encrypted = await service.encryptMasterKey(masterKey, key, iv);
+
+        // Decrypt master key
+        const decrypted = await service.decryptMasterKey(encrypted, key, iv);
+
+        // Verify decrypted matches original
+        expect(new Uint8Array(decrypted)).toEqual(masterKey);
+      });
+
+      it('should fail workflow with different biometric data', async () => {
+        const biometricData1 = Buffer.from('mock-biometric-data-1');
+        const biometricData2 = Buffer.from('mock-biometric-data-2');
+        const identifier = 'user@example.com';
+        const masterKey = new Uint8Array(32).fill(123);
+
+        // Encrypt with first biometric data
+        const {key: key1, iv} = await service.deriveBiometricEncryptionKey(
+          biometricData1,
+          identifier,
+        );
+        const encrypted = await service.encryptMasterKey(masterKey, key1, iv);
+
+        // Try to decrypt with second biometric data (should fail)
+        const {key: key2} = await service.deriveBiometricEncryptionKey(
+          biometricData2,
+          identifier,
+        );
+
+        await expect(
+          service.decryptMasterKey(encrypted, key2, iv),
+        ).rejects.toThrow('Decryption failed: Invalid key or corrupted data');
+      });
+    });
   });
 });

package/src/services/edv/service-rpc.js

@@ -38,4 +38,27 @@ export class EDVServiceRpc extends RpcService {
   delete(params: any) {
     return this.call('delete', params);
   }
+
+  deriveBiometricKey(biometricData: Buffer, identifier: string) {
+    return this.call('deriveBiometricKey', {biometricData, identifier});
+  }
+
+  deriveBiometricEncryptionKey(biometricData: Buffer, identifier: string) {
+    return this.call('deriveBiometricEncryptionKey', {
+      biometricData,
+      identifier,
+    });
+  }
+
+  encryptMasterKey(masterKey: Uint8Array, encryptionKey: Buffer, iv: Buffer) {
+    return this.call('encryptMasterKey', {masterKey, encryptionKey, iv});
+  }
+
+  decryptMasterKey(
+    encryptedKey: Uint8Array,
+    decryptionKey: Buffer,
+    iv: Buffer,
+  ) {
+    return this.call('decryptMasterKey', {encryptedKey, decryptionKey, iv});
+  }
 }

package/src/services/edv/service.ts

@@ -1,4 +1,12 @@
 // @ts-nocheck
+
+/**
+ * @module edv-service
+ * @description Encrypted Data Vault (EDV) service for the Wallet SDK.
+ * This module provides secure, encrypted storage functionality using EDV protocol,
+ * enabling privacy-preserving data storage with client-side encryption.
+ */
+
 import {InitializeEDVParams, serviceName} from './configs';
 import EDVHTTPStorageInterface from '@docknetwork/universal-wallet/storage/edv-http-storage';
 import HMAC from './hmac';
@@ -9,9 +17,17 @@ import {getKeypairFromDoc} from '@docknetwork/universal-wallet/methods/keypairs'
 import {logger} from '@docknetwork/wallet-sdk-data-store/src/logger';
 import {didService} from '@docknetwork/wallet-sdk-wasm/src/services/dids/service';
 import {Ed25519Keypair} from '@docknetwork/credential-sdk/keypairs';
+import hkdf from 'futoin-hkdf';
+import crypto from '@docknetwork/universal-wallet/crypto';
+
+export const HKDF_LENGTH = 32;
+export const HKDF_HASH = 'SHA-256';
 
 /**
- * EDVService
+ * Service class for managing Encrypted Data Vaults
+ * @class
+ * @description Provides methods for creating, managing, and interacting with
+ * encrypted data vaults for secure storage of sensitive wallet data
  */
 export class EDVService {
   storageInterface: EDVHTTPStorageInterface;
@@ -28,12 +44,39 @@ export class EDVService {
     EDVService.prototype.update,
     EDVService.prototype.insert,
     EDVService.prototype.delete,
+    EDVService.prototype.deriveBiometricKey,
+    EDVService.prototype.deriveBiometricEncryptionKey,
+    EDVService.prototype.encryptMasterKey,
+    EDVService.prototype.decryptMasterKey,
   ];
 
+  /**
+   * Creates a new EDVService instance
+   * @constructor
+   */
   constructor() {
     this.name = serviceName;
   }
 
+  /**
+   * Initializes the EDV service with encryption keys and connection parameters
+   * @param {InitializeEDVParams} params - Initialization parameters
+   * @param {Object} params.hmacKey - HMAC key for document indexing
+   * @param {Object} params.agreementKey - Key agreement key for encryption
+   * @param {Object} params.verificationKey - Verification key for authentication
+   * @param {string} params.edvUrl - URL of the EDV server
+   * @param {string} params.authKey - Authentication key for the EDV server
+   * @returns {Promise<void>}
+   * @throws {Error} If unable to create or connect to EDV
+   * @example
+   * await edvService.initialize({
+   *   hmacKey: hmacKeyData,
+   *   agreementKey: agreementKeyData,
+   *   verificationKey: verificationKeyData,
+   *   edvUrl: 'https://edv.example.com',
+   *   authKey: 'auth-token-123'
+   * });
+   */
   async initialize({
     hmacKey,
     agreementKey,
@@ -95,6 +138,21 @@ export class EDVService {
     });
   }
 
+  /**
+   * Generates new cryptographic keys for EDV operations
+   * @returns {Promise<Object>} Generated keys
+   * @returns {Object} returns.verificationKey - Ed25519 verification key for authentication
+   * @returns {Object} returns.agreementKey - X25519 key agreement key for encryption
+   * @returns {Object} returns.hmacKey - HMAC key for indexing
+   * @example
+   * const keys = await edvService.generateKeys();
+   * // Use keys for EDV initialization
+   * await edvService.initialize({
+   *   ...keys,
+   *   edvUrl: 'https://edv.example.com',
+   *   authKey: 'auth-token'
+   * });
+   */
   async generateKeys() {
     const keyPair = await didService.generateKeyDoc({});
 
@@ -111,6 +169,17 @@ export class EDVService {
     return {verificationKey, agreementKey, hmacKey};
   }
 
+  /**
+   * Derives cryptographic keys from a master key
+   * @param {Uint8Array} masterKey - Master key for derivation
+   * @returns {Promise<Object>} Derived keys
+   * @returns {Object} returns.verificationKey - Derived Ed25519 verification key
+   * @returns {Object} returns.agreementKey - Derived X25519 key agreement key
+   * @returns {Object} returns.hmacKey - Derived HMAC key
+   * @example
+   * const masterKey = new Uint8Array(32); // Your master key
+   * const keys = await edvService.deriveKeys(masterKey);
+   */
   async deriveKeys(masterKey: Uint8Array) {
     const {keyPair: pair} = new Ed25519Keypair(masterKey, 'seed');
 
@@ -126,18 +195,66 @@ export class EDVService {
     return { verificationKey, agreementKey, hmacKey };
   }
 
+  /**
+   * Gets the controller identifier for the current EDV
+   * @returns {Promise<string>} The controller DID or identifier
+   * @example
+   * const controller = await edvService.getController();
+   * console.log('EDV Controller:', controller);
+   */
   async getController() {
     return this.controller;
   }
 
+  /**
+   * Finds documents in the EDV based on query parameters
+   * @param {Object} params - Query parameters
+   * @param {Object} [params.equals] - Equality-based query conditions
+   * @param {boolean} [params.has] - Existence-based query conditions
+   * @param {number} [params.limit] - Maximum number of results
+   * @returns {Promise<Array>} Array of matching documents
+   * @example
+   * const documents = await edvService.find({
+   *   equals: { 'content.type': 'VerifiableCredential' },
+   *   limit: 10
+   * });
+   */
   find(params: any) {
     return this.storageInterface.find(params);
   }
 
+  /**
+   * Updates a document in the EDV
+   * @param {Object} params - Update parameters
+   * @param {string} params.id - Document ID to update
+   * @param {Object} params.content - New document content
+   * @returns {Promise<Object>} Updated document
+   * @example
+   * const updated = await edvService.update({
+   *   id: 'doc-123',
+   *   content: { ...existingContent, updated: true }
+   * });
+   */
   update(params: any) {
     return this.storageInterface.update(params);
   }
 
+  /**
+   * Inserts a new document into the EDV
+   * @param {Object} params - Insert parameters
+   * @param {string} params.id - Document ID
+   * @param {Object} params.content - Document content to store
+   * @returns {Promise<Object>} The inserted document
+   * @throws {Error} If insertion fails
+   * @example
+   * const document = await edvService.insert({
+   *   id: 'doc-456',
+   *   content: {
+   *     type: 'VerifiableCredential',
+   *     data: credentialData
+   *   }
+   * });
+   */
   insert(params: any) {
     this.insertQueue = this.insertQueue.then(() => {
       return this.storageInterface.insert(params).catch(error => {
@@ -148,9 +265,163 @@ export class EDVService {
     return this.insertQueue;
   }
 
+  /**
+   * Deletes a document from the EDV
+   * @param {Object} params - Deletion parameters
+   * @param {string} params.id - Document ID to delete
+   * @returns {Promise<boolean>} True if deletion successful
+   * @example
+   * const deleted = await edvService.delete({
+   *   id: 'doc-123'
+   * });
+   */
   delete(params: any) {
     return this.storageInterface.delete(params);
   }
+
+  /**
+   * Derives a key from biometric data using HKDF
+   * @param {Buffer} biometricData - Biometric data from provider
+   * @param {string} identifier - User's identifier as salt (email, phone number, etc.)
+   * @returns {Buffer} Derived key
+   * @example
+   * const key = edvService.deriveBiometricKey(biometricData, 'user@example.com');
+   */
+  deriveBiometricKey(biometricData: Buffer, identifier: string): Buffer {
+    const salt = identifier;
+    return hkdf(biometricData, HKDF_LENGTH, { salt, hash: HKDF_HASH });
+  }
+
+  /**
+   * Generates a key for encrypting/decrypting the master key
+   * @param {Buffer} biometricData - Biometric data from provider
+   * @param {string} identifier - User's identifier as salt (email, phone number, etc.)
+   * @returns {Promise<Object>} Encryption key and IV for AES encryption
+   * @returns {Buffer} returns.key - Encryption key
+   * @returns {Buffer} returns.iv - Initialization vector
+   * @example
+   * const { key, iv } = await edvService.deriveBiometricEncryptionKey(biometricData, 'user@example.com');
+   */
+  async deriveBiometricEncryptionKey(
+    biometricData: Buffer,
+    identifier: string
+  ): Promise<{ key: Buffer; iv: Buffer }> {
+    const key = this.deriveBiometricKey(biometricData, identifier);
+    const randomBytes = crypto.getRandomValues(new Uint8Array(16));
+    const iv = Buffer.from(randomBytes);
+
+    return {
+      key,
+      iv
+    };
+  }
+
+  /**
+   * Encrypts the master key using a key derived from biometric data
+   * @param {Uint8Array} masterKey - The CloudWalletVault master key to encrypt
+   * @param {Buffer} encryptionKey - Key derived from biometric data
+   * @param {Buffer} iv - Initialization vector
+   * @returns {Promise<Uint8Array>} Encrypted master key
+   * @example
+   * const encrypted = await edvService.encryptMasterKey(masterKey, encryptionKey, iv);
+   */
+  async encryptMasterKey(
+    masterKey: Uint8Array,
+    encryptionKey: Buffer,
+    iv: Buffer
+  ): Promise<Uint8Array> {
+    const keyData = new Uint8Array(encryptionKey);
+    const ivData = new Uint8Array(iv);
+
+    const key = await crypto.subtle.importKey(
+      'raw',
+      keyData,
+      { name: 'AES-GCM' },
+      false,
+      ['encrypt']
+    );
+
+    const encryptedBuffer = await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv: ivData },
+      key,
+      masterKey
+    );
+
+    return new Uint8Array(encryptedBuffer);
+  }
+
+  /**
+   * Decrypts the master key using biometric-derived key
+   * @param {Uint8Array} encryptedKey - The encrypted master key
+   * @param {Buffer} decryptionKey - Key derived from biometric data
+   * @param {Buffer} iv - Initialization vector
+   * @returns {Promise<Uint8Array>} The decrypted master key
+   * @throws {Error} If decryption fails
+   * @example
+   * const masterKey = await edvService.decryptMasterKey(encryptedKey, decryptionKey, iv);
+   */
+  async decryptMasterKey(
+    encryptedKey: Uint8Array,
+    decryptionKey: Buffer,
+    iv: Buffer
+  ): Promise<Uint8Array> {
+    try {
+      const keyData = new Uint8Array(decryptionKey);
+      const ivData = new Uint8Array(iv);
+
+      const key = await crypto.subtle.importKey(
+        'raw',
+        keyData,
+        { name: 'AES-GCM' },
+        false,
+        ['decrypt']
+      );
+
+      const decryptedBuffer = await crypto.subtle.decrypt(
+        { name: 'AES-GCM', iv: ivData },
+        key,
+        encryptedKey
+      );
+
+      return new Uint8Array(decryptedBuffer);
+    } catch (error) {
+      throw new Error('Decryption failed: Invalid key or corrupted data');
+    }
+  }
 }
 
+/**
+ * Singleton instance of the EDV service
+ * @type {EDVService}
+ * @example
+ * import { edvService } from '@docknetwork/wallet-sdk-wasm/services/edv';
+ *
+ * // Generate keys and initialize
+ * const keys = await edvService.generateKeys();
+ * await edvService.initialize({
+ *   ...keys,
+ *   edvUrl: 'https://edv.example.com',
+ *   authKey: 'auth-token'
+ * });
+ *
+ * // Store encrypted data
+ * await edvService.insert({
+ *   id: 'credential-1',
+ *   content: {
+ *     type: 'VerifiableCredential',
+ *     data: credentialData
+ *   }
+ * });
+ *
+ * // Query encrypted data
+ * const credentials = await edvService.find({
+ *   equals: { 'content.type': 'VerifiableCredential' }
+ * });
+ *
+ * // Update encrypted data
+ * await edvService.update({
+ *   id: 'credential-1',
+ *   content: updatedData
+ * });
+ */
 export const edvService: EDVService = new EDVService();

package/src/services/pex/config.ts

@@ -7,6 +7,10 @@ export const validation = {
     assert(params.credentials, 'credentials is required');
     assert(params.presentationDefinition, 'presentationDefinition is required');
   },
+  evaluateCredentials: (params: EvaluateCredentialsParams) => {
+    assert(params.credentials, 'credentials is required');
+    assert(params.presentationDefinition, 'presentationDefinition is required');
+  },
   evaluatePresentation: (params: EvaluatePresentationParams) => {
     assert(params.presentation, 'presentation is required');
     assert(params.presentationDefinition, 'presentationDefinition is required');

package/src/services/pex/service-rpc.js

@@ -24,4 +24,8 @@ export class PEXServiceRPC extends RpcService {
   async presentationFrom(params: CreatePresentationParams) {
     return this.call('presentationFrom', params);
   }
+
+  async isCredentialSelectionValid(params: EvaluateCredentialsParams) {
+    return this.call('isCredentialSelectionValid', params);
+  }
 }

package/src/services/pex/service.ts

@@ -78,6 +78,7 @@ class PEXService {
     PEXService.prototype.filterCredentials,
     PEXService.prototype.evaluatePresentation,
     PEXService.prototype.presentationFrom,
+    PEXService.prototype.isCredentialSelectionValid,
   ];
 
   filterCredentials(params: FilterCredentialsParams) {
@@ -92,6 +93,18 @@ class PEXService {
     return result;
   }
 
+  isCredentialSelectionValid(params: EvaluateCredentialsParams) {
+    validation.evaluateCredentials(params);
+    const {credentials, presentationDefinition, holderDIDs} = params;
+    const result = pex.selectFrom(
+      removeOptionalAttribute(presentationDefinition),
+      credentials,
+      holderDIDs,
+    );
+
+    return result.errors.length === 0;
+  }
+
   evaluatePresentation(params: EvaluatePresentationParams) {
     validation.evaluatePresentation(params);
     const {presentation, presentationDefinition} = params;