@docknetwork/wallet-sdk-core 1.5.0 → 1.5.8

package/src/biometric-provider.ts

@@ -1,91 +1,173 @@
 import {WalletDocument} from '@docknetwork/wallet-sdk-wasm/src/types';
 import {IWallet} from './types';
-import {createCredentialProvider, CredentialStatus} from './credential-provider';
+import {
+  createCredentialProvider,
+  Credential,
+  CredentialStatus,
+} from './credential-provider';
 import assert from 'assert';
+import {EventEmitter} from 'events';
+import {createDIDProvider} from './did-provider';
 
-export type BiometricsPluginIssuerConfig = {
-  networkId: string;
-  did: string;
-  apiKey: string;
-  apiUrl: string;
-}
-
-export type BiometricsPluginConfigs = {
+export type BiometricsProviderConfigs<E> = {
+  // Generic configs used by the biometric provider
   enrollmentCredentialType: string;
   biometricMatchCredentialType: string;
-  biometricMatchExpirationMinutes: number;
-  issuerConfigs:BiometricsPluginIssuerConfig[];
+  // IDV specific configs, it depends on the IDV provider and its implementation
+  idvConfigs: E;
+};
+
+export interface IDVProcessOptions {
+  onDeepLink?: () => void;
+  onMessage?: () => void;
+  onError?: (error: Error) => void;
+  onCancel?: () => void;
+  onComplete?: (credential: any) => void;
 }
 
-let configs: BiometricsPluginConfigs = null;
+export interface BiometricPlugin {
+  onEnroll(walletDID: string): Promise<WalletDocument>;
+  onMatch(
+    walletDID: string,
+    enrollmentCredential: Credential,
+  ): Promise<WalletDocument>;
+}
 
-export function setBiometricConfigs(_configs: BiometricsPluginConfigs) {
-  configs = _configs;
-};
+let currentConfigs: BiometricsProviderConfigs<unknown> = null;
+
+export function setConfigs(configs: BiometricsProviderConfigs<unknown>) {
+  currentConfigs = configs;
+}
+
+export function isBiometricPluginEnabled() {
+  return !!currentConfigs?.biometricMatchCredentialType;
+}
 
 export function assertConfigs() {
-  assert(!!configs, 'Biometrics plugin not configured');
+  assert(!!currentConfigs, 'Missing biometric provider configs');
 }
 
 export function getBiometricConfigs() {
   assertConfigs();
-  return configs;
+  return currentConfigs;
+}
+
+export function hasProofOfBiometrics(proofRequest) {
+  const fields = proofRequest.input_descriptors
+    ?.map(input => input.constraints?.fields)
+    .flat();
+  const paths = fields.map(field => field.path).flat();
+  return (
+    paths?.includes('$.credentialSubject.biometric.id') &&
+    paths?.includes('$.credentialSubject.biometric.created')
+  );
+}
+
+// map for events
+export const IDV_EVENTS = {
+  onDeepLink: 'onDeepLink',
+  onMessage: 'onMessage',
+  onError: 'onError',
+  onCancel: 'onCancel',
+  onComplete: 'onComplete',
+};
+
+export interface IDVProvider {
+  enroll(
+    walletDID: string,
+    proofRequest: any,
+  ): Promise<{enrollmentCredential: Credential; matchCredential: Credential}>;
+  match(
+    walletDID: string,
+    enrollmentCredential: Credential,
+    proofRequest: any,
+  ): Promise<{
+    matchCredential: Credential;
+  }>;
 }
 
-export function getIssuerConfigsForNetwork(networkId): BiometricsPluginIssuerConfig {
-  return getBiometricConfigs()?.issuerConfigs.find(config => config.networkId === networkId);
+export interface IDVProviderFactory {
+  create(eventEmitter: EventEmitter, wallet: IWallet): IDVProvider;
 }
 
-export function createBiometricBindingProvider({
+export function createBiometricProvider({
   wallet,
-  onEnroll,
-  onMatch,
-  onCheckBiometryRequired,
+  idvProviderFactory,
 }: {
   wallet: IWallet;
-  onEnroll: () => Promise<WalletDocument>;
-  onMatch: (biometricTemplate: WalletDocument) => Promise<WalletDocument>;
-  onCheckBiometryRequired: (request) => boolean;
+  idvProviderFactory: IDVProviderFactory;
 }) {
   const credentialProvider = createCredentialProvider({wallet});
-  return {
-    enrollBiometry: async () => {
-      const enrollmentCredential = await onEnroll();
-      return await credentialProvider.addCredential(enrollmentCredential);
-    },
-    matchBiometry: async () => {
-      const CREDENTIAL_TYPE = configs.enrollmentCredentialType;
-      const enrollmentCredentials = await wallet.getDocumentsByType(
-        CREDENTIAL_TYPE,
+  const didProvider = createDIDProvider({wallet});
+  const eventEmitter = new EventEmitter();
+  const idvProvider = idvProviderFactory.create(eventEmitter, wallet);
+
+
+  async function startIDV(proofRequest: any): Promise<{
+    enrollmentCredential: Credential;
+    matchCredential: Credential;
+  }> {
+    const walletDID = await didProvider.getDefaultDID();
+    let [enrollmentCredential] = await credentialProvider.getCredentials(
+      currentConfigs.enrollmentCredentialType,
+    );
+
+    // Remove any existing match credentials
+    const existingMatchCredentials = await credentialProvider.getCredentials(
+      currentConfigs.biometricMatchCredentialType,
+    );
+    for (const credential of existingMatchCredentials) {
+      await credentialProvider.removeCredential(credential.id);
+    }
+
+    let matchCredential: Credential;
+
+    if (!enrollmentCredential) {
+      // call IDV to start enrollment process and issue the enrollment credential + match credential
+      const credentials = await idvProvider.enroll(walletDID, proofRequest);
+
+      // check if credential is already in the credential store
+      const receivedViaDistribution = await credentialProvider.getById(
+        credentials.matchCredential.id,
       );
 
-      if (!enrollmentCredentials.length) {
-        throw new Error('Enrollment credential not found');
+      if (!receivedViaDistribution) {
+        await credentialProvider.addCredential(
+          credentials.enrollmentCredential,
+        );
+        await credentialProvider.addCredential(credentials.matchCredential);
       }
 
-      const matchConfirmationCredential = await onMatch(
-        enrollmentCredentials[0],
+      matchCredential = credentials.matchCredential;
+      enrollmentCredential = credentials.enrollmentCredential;
+    } else {
+      // call IDV to match the enrollment credential and issue the match credential
+      const credentials = await idvProvider.match(
+        walletDID,
+        enrollmentCredential,
+        proofRequest,
+      );
+
+      // check if credential is already in the credential store
+      const receivedViaDistribution = await credentialProvider.getById(
+        credentials.matchCredential.id,
       );
 
-      if (matchConfirmationCredential) {
-        const biometricMatchCredentials = await wallet.getDocumentsByType(configs.biometricMatchCredentialType);
-        for (let i = 0; i < biometricMatchCredentials.length; i++) {
-          await wallet.removeDocument(biometricMatchCredentials[0].id);
-        }
-
-        await wallet.addDocument(matchConfirmationCredential);
-        // make the biometric credential valid by default
-        await wallet.addDocument({
-          id: `${matchConfirmationCredential.id}#status`,
-          status: CredentialStatus.Verified,
-          type: 'CredentialStatus',
-          createdAt: new Date().toISOString(),
-          updatedAt: new Date().toISOString(),
-        })
+      if (!receivedViaDistribution) {
+        await credentialProvider.addCredential(credentials.matchCredential);
       }
 
-      return matchConfirmationCredential;
-    },
-    checkIsBiometryRequired: onCheckBiometryRequired,
+      matchCredential = credentials.matchCredential;
+    }
+
+    return {
+      enrollmentCredential,
+      matchCredential,
+    };
+  }
+
+  return {
+    startIDV,
+    eventEmitter,
   };
 }

package/src/cloud-wallet.ts

@@ -2,13 +2,311 @@ import {
   DataStore,
   DataStoreEvents,
 } from '@docknetwork/wallet-sdk-data-store/src/types';
-import {logger} from '@docknetwork/wallet-sdk-data-store/src/logger';
-import {edvService} from '@docknetwork/wallet-sdk-wasm/src/services/edv';
-import base64url from 'base64url-universal';
-
-import {utilCryptoService} from '@docknetwork/wallet-sdk-wasm/src/services/util-crypto';
+import { logger } from '@docknetwork/wallet-sdk-data-store/src/logger';
+import { edvService, EDVService } from '@docknetwork/wallet-sdk-wasm/src/services/edv/service';
+import hkdf from 'futoin-hkdf';
+import crypto from '@docknetwork/universal-wallet/crypto';
+import { utilCryptoService } from '@docknetwork/wallet-sdk-wasm/src/services/util-crypto';
 
 export const SYNC_MARKER_TYPE = 'SyncMarkerDocument';
+export const MNEMONIC_WORD_COUNT = 12;
+export const KEY_MAPPING_TYPE = 'KeyMappingDocument';
+export const HKDF_LENGTH = 32;
+export const HKDF_HASH = 'SHA-256';
+const MASTER_KEY_SUFFIX = 'master-key';
+
+/**
+ * Derives a key from biometric data using HKDF
+ * @param biometricData Biometric data from provider
+ * @param identifier User's identifier as salt (email, phone number, etc.)
+ * @returns Derived key
+ */
+export function deriveBiometricKey(
+  biometricData: Buffer,
+  identifier: string,
+): Buffer {
+  const salt = identifier;
+
+  return hkdf(biometricData, HKDF_LENGTH, { salt, hash: HKDF_HASH });
+}
+
+/**
+ * Derives EDV keys from biometric data for the KeyMappingVault
+ * @param biometricData Biometric data from the provider
+ * @param identifier User's identifier as additional entropy (email, phone number, etc.)
+ * @returns Keys for accessing the KeyMappingVault
+ */
+export async function deriveKeyMappingVaultKeys(
+  biometricData: Buffer,
+  identifier: string
+): Promise<{ hmacKey: string; agreementKey: string; verificationKey: string }> {
+  const seedBuffer = deriveBiometricKey(biometricData, identifier);
+
+  return edvService.deriveKeys(new Uint8Array(seedBuffer));
+}
+
+/**
+ * Generates a key for encrypting/decrypting the master key
+ * @param biometricData Biometric data from provider
+ * @param identifier User's identifier as salt (email, phone number, etc.)
+ * @returns Encryption key and IV for AES encryption
+ */
+export async function deriveBiometricEncryptionKey(
+  biometricData: Buffer,
+  identifier: string
+): Promise<{ key: Buffer; iv: Buffer }> {
+  const key = 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 masterKey The CloudWalletVault master key to encrypt
+ * @param encryptionKey Key derived from biometric data
+ * @param iv Initialization vector
+ * @returns Encrypted master key
+ */
+export async function 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 encryptedKey The encrypted master key
+ * @param decryptionKey Key derived from biometric data
+ * @param iv Initialization vector
+ * @returns The decrypted master key
+ */
+export async function 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');
+  }
+}
+
+/**
+ * Initializes the KeyMappingVault using biometric data
+ * @param edvUrl URL for the edv
+ * @param authKey Auth key for the edv
+ * @param biometricData User's biometric data
+ * @param identifier User's identifier (email, phone number, etc.)
+ * @returns Initialized EDV service
+ */
+export async function initializeKeyMappingVault(
+  edvUrl: string,
+  authKey: string,
+  biometricData: Buffer,
+  identifier: string
+): Promise<EDVService> {
+  const {
+    hmacKey,
+    agreementKey,
+    verificationKey
+  } = await deriveKeyMappingVaultKeys(biometricData, identifier);
+
+  const keyMappingEdvService = new EDVService();
+  await keyMappingEdvService.initialize({
+    hmacKey,
+    agreementKey,
+    verificationKey,
+    edvUrl,
+    authKey
+  });
+
+  return keyMappingEdvService;
+}
+
+/**
+ * Enrolls a user by creating necessary vaults and keys
+ * @param edvUrl URL for the edv
+ * @param authKey Auth key for the edv
+ * @param biometricData Biometric data from provider
+ * @param identifier User's identifier (email, phone number, etc.)
+ * @returns The master key and mnemonic for backup
+ */
+export async function enrollUserWithBiometrics(
+  edvUrl: string,
+  authKey: string,
+  biometricData: Buffer,
+  identifier: string
+): Promise<{ masterKey: Uint8Array; mnemonic: string }> {
+  const keyMappingEdv = await initializeKeyMappingVault(
+    edvUrl,
+    authKey,
+    biometricData,
+    identifier
+  );
+  const { mnemonic, masterKey } = await generateCloudWalletMasterKey();
+  const { key: encryptionKey, iv } = await deriveBiometricEncryptionKey(biometricData, identifier);
+  const encryptedMasterKey = await encryptMasterKey(masterKey, encryptionKey, iv);
+
+  const encryptedData = {
+    data: Array.from(encryptedMasterKey),
+    iv: Array.from(iv)
+  };
+
+  const contentId = `${await keyMappingEdv.getController()}#${MASTER_KEY_SUFFIX}`;
+
+  await keyMappingEdv.insert({
+    document: {
+      content: {
+        id: contentId,
+        type: KEY_MAPPING_TYPE,
+        encryptedKey: encryptedData
+      }
+    }
+  });
+
+  return { masterKey, mnemonic };
+}
+
+/**
+ * Gets the master key from the key mapping vault using provided decryption keys
+ * @param keyMappingEdv Initialized key mapping vault service
+ * @param identifier User's identifier (email, phone number, etc.)
+ * @param decryptionKey Key for decrypting the master key
+ * @param iv Initialization vector for decryption
+ * @returns The decrypted master key for CloudWalletVault
+ */
+export async function getKeyMappingMasterKey(
+  keyMappingEdv: EDVService,
+  identifier: string,
+  decryptionKey: Buffer,
+): Promise<Uint8Array> {
+  const result = await keyMappingEdv.find({
+    equals: {
+      'content.id': identifier
+    }
+  });
+
+  if (!result.documents || result.documents.length === 0) {
+    throw new Error('Authentication failed: Invalid identifier');
+  }
+
+  // The KeyMappingVault keys are derived from the biometric data so each
+  // vault should have a unique key for the user
+
+  const keyMappingDoc = result.documents[0];
+  const { data: encryptedKey, iv: storedIv } = keyMappingDoc.content.encryptedKey;
+  const encryptedKeyArray = new Uint8Array(encryptedKey);
+  const ivBuffer = Buffer.from(storedIv);
+
+  try {
+    const masterKey = await decryptMasterKey(encryptedKeyArray, decryptionKey, ivBuffer);
+
+    return masterKey;
+  } catch (error) {
+    throw new Error('Authentication failed: Invalid decryption key');
+  }
+}
+
+/**
+ * Authenticates a user with biometric data and identifier
+ * @param edvUrl URL for the edv
+ * @param authKey Auth key for the edv
+ * @param biometricData Biometric data from the provider
+ * @param identifier User's identifier (email, phone number, etc.)
+ * @returns The decrypted master key for CloudWalletVault
+ */
+export async function authenticateWithBiometrics(
+  edvUrl: string,
+  authKey: string,
+  biometricData: Buffer,
+  identifier: string
+): Promise<Uint8Array> {
+  const keyMappingEdv = await initializeKeyMappingVault(
+    edvUrl,
+    authKey,
+    biometricData,
+    identifier
+  );
+  const { key: decryptionKey } = await deriveBiometricEncryptionKey(biometricData, identifier);
+
+  const contentId = `${await keyMappingEdv.getController()}#${MASTER_KEY_SUFFIX}`;
+
+  return getKeyMappingMasterKey(keyMappingEdv, contentId, decryptionKey);
+}
+
+/**
+ * Initializes the Cloud Wallet using biometric authentication
+ * @param edvUrl Cloud wallet vault URL
+ * @param authKey Cloud wallet auth key
+ * @param biometricData User's biometric data
+ * @param identifier User's identifier (email, phone number, etc.)
+ * @param dataStore Optional data store for the wallet
+ * @returns Initialized cloud wallet
+ */
+export async function initializeCloudWalletWithBiometrics(
+  edvUrl: string,
+  authKey: string,
+  biometricData: Buffer,
+  identifier: string,
+  dataStore?: any
+): Promise<any> {
+  const masterKey = await authenticateWithBiometrics(
+    edvUrl,
+    authKey,
+    biometricData,
+    identifier
+  );
+
+  return initializeCloudWallet({
+    dataStore,
+    edvUrl,
+    authKey,
+    masterKey
+  });
+}
 
 interface QueuedOperation {
   operation: () => Promise<any>;
@@ -21,11 +319,10 @@ interface DocumentQueue {
   isProcessing: boolean;
 }
 
-export async function generateCloudWalletMasterKey(): Promise<{ mnemonic: string; masterKey: string }> {
-  const mnemonic = await utilCryptoService.mnemonicGenerate(12);
+export async function generateCloudWalletMasterKey(): Promise<{ mnemonic: string; masterKey: Uint8Array }> {
+  const mnemonic = await utilCryptoService.mnemonicGenerate(MNEMONIC_WORD_COUNT);
 
-  const seedBytes = await utilCryptoService.mnemonicToMiniSecret(mnemonic);
-  const masterKey = base64url.encode(Buffer.from(seedBytes));
+  const masterKey = await utilCryptoService.mnemonicToMiniSecret(mnemonic);
 
   return {
     mnemonic,
@@ -33,9 +330,8 @@ export async function generateCloudWalletMasterKey(): Promise<{ mnemonic: string
   };
 }
 
-export async function recoverCloudWalletMasterKey(mnemonic: string): Promise<string> {
-  const seedBytes = await utilCryptoService.mnemonicToMiniSecret(mnemonic);
-  const masterKey = base64url.encode(Buffer.from(seedBytes));
+export async function recoverCloudWalletMasterKey(mnemonic: string): Promise<Uint8Array> {
+  const masterKey = await utilCryptoService.mnemonicToMiniSecret(mnemonic);
 
   return masterKey;
 }
@@ -49,7 +345,7 @@ export async function initializeCloudWallet({
   dataStore?: DataStore;
   edvUrl: string;
   authKey: string;
-  masterKey: any;
+  masterKey: Uint8Array;
 }) {
   const {
     hmacKey,
@@ -174,7 +470,7 @@ export async function initializeCloudWallet({
           },
         });
         logger.debug(`Document added to EDV: ${content.id}`);
-      } catch(error) {
+      } catch (error) {
         logger.error(`Unable to add document ${content.id}: ${error.message}`);
       }
     });
@@ -185,7 +481,7 @@ export async function initializeCloudWallet({
       try {
         logger.debug(`Removing document from EDV: ${documentId}`);
         const edvDocument = await findDocumentByContentId(documentId);
-        await edvService.delete({document: edvDocument});
+        await edvService.delete({ document: edvDocument });
         // TODO: Remove this once we figure out why the data store is empty after deleting a document
         await pullDocuments();
         logger.debug(`Document removed from EDV: ${documentId}`);
@@ -259,7 +555,7 @@ export async function initializeCloudWallet({
     const allDocs = await edvService.find({});
 
     for (const doc of allDocs.documents) {
-      await edvService.delete({document: doc});
+      await edvService.delete({ document: doc });
     }
   }
 

package/src/credential-provider.ts

@@ -24,6 +24,7 @@ export interface ICredentialProvider {
   getCredentialStatus(
     credential: Credential,
   ): Promise<{status: string; error?: string}>;
+  removeCredential(credential: Credential): Promise<void>;
 }
 
 export function isBBSPlusCredential(credential) {
@@ -275,6 +276,35 @@ async function syncCredentialStatus({
   return statusDocs;
 }
 
+/**
+ * Removes a credential and its related documents from the wallet
+ * @param param0 
+ * @returns 
+ */
+export async function removeCredential({
+  wallet, 
+  credential,
+}: {
+  wallet: IWallet;
+  credential: Credential | string;
+}): Promise<void> {
+  // Allow passing either a credential object or a credential ID
+  const credentialId = typeof credential === 'string' ? credential : credential.id;
+  
+  assert(!!credentialId, 'credential ID is required');
+  
+  // Remove the main credential document
+  await wallet.removeDocument(credentialId);
+  
+  if (await wallet.getDocumentById(`${credentialId}#witness`)) {
+    await wallet.removeDocument(`${credentialId}#witness`);
+  }
+
+  if (await wallet.getDocumentById(`${credentialId}#status`)) {
+    await wallet.removeDocument(`${credentialId}#status`);
+  }
+}
+
 export function createCredentialProvider({
   wallet,
 }: {
@@ -320,6 +350,7 @@ export function createCredentialProvider({
       return syncCredentialStatus({wallet, ...props});
     },
     addCredential: credential => addCredential({wallet, credential}),
+    removeCredential: credential => removeCredential({wallet, credential}),
     // TODO: move import credential from json or URL to this provider
   };
 }