@docknetwork/wallet-sdk-core 1.5.14 → 1.7.6

package/src/cloud-wallet.ts

@@ -1,18 +1,20 @@
+/**
+ * @module cloud-wallet
+ * @description Cloud wallet functionality for the Truvera Wallet SDK.
+ * This module provides the main cloud wallet creation and management functions.
+ */
+
 import {
   DataStore,
   DataStoreEvents,
 } from '@docknetwork/wallet-sdk-data-store/src/types';
 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 { edvService } from '@docknetwork/wallet-sdk-wasm/src/services/edv';
 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';
 
 /**
@@ -25,9 +27,7 @@ export function deriveBiometricKey(
   biometricData: Buffer,
   identifier: string,
 ): Buffer {
-  const salt = identifier;
-
-  return hkdf(biometricData, HKDF_LENGTH, { salt, hash: HKDF_HASH });
+  return edvService.deriveBiometricKey(biometricData, identifier);
 }
 
 /**
@@ -55,15 +55,7 @@ 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
-  };
+  return edvService.deriveBiometricEncryptionKey(biometricData, identifier);
 }
 
 /**
@@ -78,24 +70,7 @@ export async function encryptMasterKey(
   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);
+  return edvService.encryptMasterKey(masterKey, encryptionKey, iv);
 }
 
 /**
@@ -110,28 +85,7 @@ export async function decryptMasterKey(
   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');
-  }
+  return edvService.decryptMasterKey(encryptedKey, decryptionKey, iv);
 }
 
 /**
@@ -147,14 +101,14 @@ export async function initializeKeyMappingVault(
   authKey: string,
   biometricData: Buffer,
   identifier: string
-): Promise<EDVService> {
+): Promise<typeof edvService> {
   const {
     hmacKey,
     agreementKey,
     verificationKey
   } = await deriveKeyMappingVaultKeys(biometricData, identifier);
 
-  const keyMappingEdvService = new EDVService();
+  const keyMappingEdvService = edvService;
   await keyMappingEdvService.initialize({
     hmacKey,
     agreementKey,
@@ -219,7 +173,7 @@ export async function enrollUserWithBiometrics(
  * @returns The decrypted master key for CloudWalletVault
  */
 export async function getKeyMappingMasterKey(
-  keyMappingEdv: EDVService,
+  keyMappingEdv: typeof edvService,
   identifier: string,
   decryptionKey: Buffer,
 ): Promise<Uint8Array> {
@@ -227,6 +181,13 @@ export async function getKeyMappingMasterKey(
     equals: {
       'content.id': identifier
     }
+  }).catch(error => {
+    if (error.message && error.message.includes('does not exist')) {
+      logger.error('KeyMappingVault does not exist, skipping find');
+      return { documents: [] };
+    }
+
+    throw error;
   });
 
   if (!result.documents || result.documents.length === 0) {

package/src/credential-provider.test.ts

@@ -227,7 +227,7 @@ describe('CredentialProvider', () => {
         });
 
       await provider.syncCredentialStatus({forceFetch: true});
-      
+
       // Clear mocks
       jest.clearAllMocks();
 
@@ -255,6 +255,196 @@ describe('CredentialProvider', () => {
       expect(credentialServiceRPC.verifyCredential).toHaveBeenCalledTimes(2);
     });
 
+    it('should always refetch credentials with Invalid status even when cached', async () => {
+      // First, create credentials with Invalid status
+      jest
+        .spyOn(credentialServiceRPC, 'verifyCredential')
+        .mockImplementation(async () => {
+          return {
+            verified: false,
+            error: 'Credential validation failed',
+          };
+        });
+
+      await provider.syncCredentialStatus({forceFetch: true});
+
+      // Verify initial calls
+      expect(credentialServiceRPC.verifyCredential).toHaveBeenCalledTimes(2);
+
+      // Check that status is set to Invalid
+      const initialStatusDoc = await wallet.getDocumentById(
+        `${customerCredential.id}#status`,
+      );
+      expect(initialStatusDoc.status).toBe(CredentialStatus.Invalid);
+
+      // Clear mocks to track only subsequent calls
+      jest.clearAllMocks();
+
+      // Now mock successful verification
+      jest
+        .spyOn(credentialServiceRPC, 'verifyCredential')
+        .mockImplementation(async () => {
+          return {
+            verified: true,
+          };
+        });
+
+      // Call syncCredentialStatus again WITHOUT forceFetch
+      // Invalid status should trigger refetch even without forceFetch
+      const statusDocs = await provider.syncCredentialStatus({});
+
+      // Verify that verifyCredential was called again despite no forceFetch
+      expect(credentialServiceRPC.verifyCredential).toHaveBeenCalledTimes(2);
+
+      // Check that status is now updated to Verified
+      expect(statusDocs.length).toBe(2);
+      for (const statusDoc of statusDocs) {
+        expect(statusDoc.status).toBe(CredentialStatus.Verified);
+      }
+    });
+
+    it('should always refetch credentials with Pending status even when cached', async () => {
+      // First, manually create a Pending status document
+      const pendingStatusDoc = {
+        type: 'CredentialStatus',
+        id: `${customerCredential.id}#status`,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        status: CredentialStatus.Pending,
+        error: null,
+        warning: null,
+      };
+      await wallet.updateDocument(pendingStatusDoc);
+
+      // Mock successful verification
+      jest
+        .spyOn(credentialServiceRPC, 'verifyCredential')
+        .mockImplementation(async () => {
+          return {
+            verified: true,
+          };
+        });
+
+      // Call syncCredentialStatus without forceFetch
+      // Pending status should trigger refetch
+      const statusDocs = await provider.syncCredentialStatus({
+        credentialIds: [customerCredential.id],
+      });
+
+      // Verify that verifyCredential was called for the Pending credential
+      expect(credentialServiceRPC.verifyCredential).toHaveBeenCalledTimes(1);
+
+      // Check that status is now updated to Verified
+      expect(statusDocs.length).toBe(1);
+      expect(statusDocs[0].status).toBe(CredentialStatus.Verified);
+    });
+
+    it('should cache Revoked status and not refetch within 24 hours', async () => {
+      // First, create credentials with Revoked status
+      jest
+        .spyOn(credentialServiceRPC, 'verifyCredential')
+        .mockImplementation(async () => {
+          return {
+            verified: false,
+            error: 'Revocation check failed',
+          };
+        });
+
+      await provider.syncCredentialStatus({forceFetch: true});
+
+      // Verify initial calls
+      expect(credentialServiceRPC.verifyCredential).toHaveBeenCalledTimes(2);
+
+      // Check that status is set to Revoked
+      const revokedStatusDoc = await wallet.getDocumentById(
+        `${customerCredential.id}#status`,
+      );
+      expect(revokedStatusDoc.status).toBe(CredentialStatus.Revoked);
+
+      // Clear mocks to track only subsequent calls
+      jest.clearAllMocks();
+
+      // Call syncCredentialStatus again WITHOUT forceFetch
+      // Revoked status should NOT trigger refetch within 24 hours
+      const statusDocs = await provider.syncCredentialStatus({});
+
+      // Verify that verifyCredential was NOT called (cached)
+      expect(credentialServiceRPC.verifyCredential).toHaveBeenCalledTimes(0);
+
+      // Check that status remains Revoked
+      expect(statusDocs.length).toBe(2);
+      for (const statusDoc of statusDocs) {
+        expect(statusDoc.status).toBe(CredentialStatus.Revoked);
+      }
+    });
+
+    it('should cache Verified status and not refetch within 24 hours', async () => {
+      // First, create credentials with Verified status
+      jest
+        .spyOn(credentialServiceRPC, 'verifyCredential')
+        .mockImplementation(async () => {
+          return {
+            verified: true,
+          };
+        });
+
+      await provider.syncCredentialStatus({forceFetch: true});
+
+      // Verify initial calls
+      expect(credentialServiceRPC.verifyCredential).toHaveBeenCalledTimes(2);
+
+      // Check that status is set to Verified
+      const verifiedStatusDoc = await wallet.getDocumentById(
+        `${customerCredential.id}#status`,
+      );
+      expect(verifiedStatusDoc.status).toBe(CredentialStatus.Verified);
+
+      // Clear mocks to track only subsequent calls
+      jest.clearAllMocks();
+
+      // Call syncCredentialStatus again WITHOUT forceFetch
+      // Verified status should NOT trigger refetch within 24 hours
+      const statusDocs = await provider.syncCredentialStatus({});
+
+      // Verify that verifyCredential was NOT called (cached)
+      expect(credentialServiceRPC.verifyCredential).toHaveBeenCalledTimes(0);
+
+      // Check that status remains Verified
+      expect(statusDocs.length).toBe(2);
+      for (const statusDoc of statusDocs) {
+        expect(statusDoc.status).toBe(CredentialStatus.Verified);
+      }
+    });
+
+    it('should refetch credentials without status document', async () => {
+      // Remove any existing status documents
+      await wallet.removeDocument(`${customerCredential.id}#status`).catch(() => {});
+      await wallet.removeDocument(`${biometricsBBSRevocation.id}#status`).catch(() => {});
+
+      // Mock successful verification
+      jest
+        .spyOn(credentialServiceRPC, 'verifyCredential')
+        .mockImplementation(async () => {
+          return {
+            verified: true,
+          };
+        });
+
+      // Call syncCredentialStatus
+      // Missing status docs should trigger fetch
+      const statusDocs = await provider.syncCredentialStatus({});
+
+      // Verify that verifyCredential was called for both credentials
+      expect(credentialServiceRPC.verifyCredential).toHaveBeenCalledTimes(2);
+
+      // Check that status documents were created
+      expect(statusDocs.length).toBe(2);
+      for (const statusDoc of statusDocs) {
+        expect(statusDoc.status).toBe(CredentialStatus.Verified);
+        expect(statusDoc.type).toBe('CredentialStatus');
+      }
+    });
+
     afterEach(() => {
       (credentialServiceRPC.verifyCredential as any).mockReset();
     });

package/src/credential-provider.ts

@@ -1,5 +1,12 @@
+/**
+ * @module credential-provider
+ * @description Verifiable credential management functionality for the Truvera Wallet SDK.
+ * This module provides functions for importing, verifying, storing, and managing verifiable credentials.
+ */
+
 import {credentialServiceRPC} from '@docknetwork/wallet-sdk-wasm/src/services/credential';
-import {IWallet} from './types';
+import {IWallet, ICredentialProvider} from './types';
+export type {ICredentialProvider};
 import assert from 'assert';
 import {blockchainService} from '@docknetwork/wallet-sdk-wasm/src/services/blockchain';
 import {acquireOpenIDCredentialFromURI} from './credentials/oidvc';
@@ -7,29 +14,10 @@ import {IDIDProvider} from './did-provider';
 
 export type Credential = any;
 
-export interface ICredentialProvider {
-  getCredentials(type?: string): Credential[];
-  getById(id: string): Credential;
-  getMembershipWitness(credential: any): Promise<any>;
-  isBBSPlusCredential(credential: any): boolean;
-  isValid(credential: any, forceFetch?: boolean): Promise<{
-    status: string;
-    error?: string;
-    warning?: string;
-  }>;
-  addCredential(credential: any): Promise<Credential>;
-  importCredentialFromURI(
-    params: importCredentialFromUriParams,
-  ): Promise<Credential>;
-  syncCredentialStatus(
-    params: SyncCredentialStatusParams,
-  ): Promise<CredentialStatusDocument[]>;
-  getCredentialStatus(
-    credential: Credential,
-  ): Promise<{status: string; error?: string}>;
-  removeCredential(credential: Credential): Promise<void>;
-}
-
+/**
+ * Internal function to check if a credential uses BBS+ signature
+ * @private
+ */
 export function isBBSPlusCredential(credential) {
   return (
     (typeof credential?.proof?.type === 'string' &&
@@ -47,6 +35,10 @@ type importCredentialFromUriParams = {
   getAuthCode?: (authorizationURL: string) => Promise<string>;
 };
 
+/**
+ * Internal function to import credential from URI
+ * @private
+ */
 export async function importCredentialFromURI({
   uri,
   wallet,
@@ -68,6 +60,10 @@ export async function importCredentialFromURI({
   await addCredential({wallet, credential});
 }
 
+/**
+ * Internal function to check if credential is expired
+ * @private
+ */
 export function isCredentialExpired(credential) {
   return (
     !!credential.expirationDate &&
@@ -78,7 +74,7 @@ export function isCredentialExpired(credential) {
 /**
  * Uses Dock SDK to verify a credential
  * @param credential
- * @returns
+ * @returns {Promise<Object>} Verification result with status and optional error/warning messages
  */
 export async function isValid({
   credential,
@@ -172,7 +168,26 @@ export async function isValid({
 
 export const ACUMM_WITNESS_PROP_KEY = '$$accum__witness$$';
 
+/**
+ * Internal function to add credential to wallet
+ * @private
+ */
 export async function addCredential({wallet, credential}) {
+  // Check if the credential is an SD-JWT (string format)
+  if (typeof credential === 'string') {
+    try {
+      const isSDJWT = await credentialServiceRPC.isSDJWTCredential({credential});
+
+      if (isSDJWT) {
+        // Convert SD-JWT to W3C format (includes _sd_jwt metadata for unwrapping)
+        credential = await credentialServiceRPC.credentialToW3C({credential});
+      }
+    } catch (error) {
+      console.error('Error checking/converting SD-JWT credential:', error);
+      throw new Error('Failed to process SD-JWT credential: ' + error.message);
+    }
+  }
+
   const acummWitness = credential[ACUMM_WITNESS_PROP_KEY];
 
   if (acummWitness) {
@@ -195,6 +210,10 @@ export async function addCredential({wallet, credential}) {
   return response;
 }
 
+/**
+ * Internal function to get membership witness for credential
+ * @private
+ */
 async function getMembershipWitness({credentialId, wallet}) {
   const document = await wallet.getDocumentById(`${credentialId}#witness`);
   return document?.value;
@@ -230,6 +249,10 @@ type CredentialStatusDocument = {
  * @param param0
  * @returns CredentialStatusDocument[]
  */
+/**
+ * Internal function to sync credential status from blockchain
+ * @private
+ */
 async function syncCredentialStatus({
   wallet,
   credentialIds,
@@ -268,7 +291,9 @@ async function syncCredentialStatus({
 
     statusDocs.push(statusDoc);
 
-    if (!statusDoc.status || statusDoc.status === CredentialStatus.Pending) {
+    // Revoked and Expired statuses should be cached
+    // The user can fore refresh that from the credentials screen
+    if (!statusDoc.status || statusDoc.status === CredentialStatus.Invalid || statusDoc.status === CredentialStatus.Pending) {
       shouldFetch = true;
     }
 
@@ -312,7 +337,11 @@ async function syncCredentialStatus({
 /**
  * Removes a credential and its related documents from the wallet
  * @param param0 
- * @returns 
+ * @returns {Promise<void>}
+ */
+/**
+ * Internal function to remove credential and related documents
+ * @private
  */
 export async function removeCredential({
   wallet, 
@@ -338,6 +367,35 @@ export async function removeCredential({
   }
 }
 
+/**
+ * Creates a credential provider instance bound to a wallet
+ * @param {Object} params - Provider configuration
+ * @param {IWallet} params.wallet - The wallet instance to use for credential storage
+ * @returns {ICredentialProvider} A credential provider instance with all verifiable credential management methods
+ * @see {@link ICredentialProvider} - The interface defining all available credential provider methods
+ * @example
+ * import { createCredentialProvider } from '@docknetwork/wallet-sdk-core';
+ *
+ * const credentialProvider = createCredentialProvider({wallet});
+ *
+ * // Add a credential
+ * const addedCredential = await credentialProvider.addCredential(myCredential);
+ *
+ * // Validate a credential
+ * const result = await credentialProvider.isValid(credential);
+ * if (result.status === 'verified') {
+ *   console.log('Credential is valid');
+ * }
+ *
+ * // Get all credentials
+ * const allCredentials = credentialProvider.getCredentials();
+ *
+ * // Import from URI
+ * await credentialProvider.importCredentialFromURI({
+ *   uri: 'https://example.com/credential-offer',
+ *   didProvider
+ * });
+ */
 export function createCredentialProvider({
   wallet,
 }: {
@@ -348,21 +406,103 @@ export function createCredentialProvider({
   }
 
   return {
+    /**
+     * Imports a credential from a URI (supports OpenID credential offers)
+     * @memberof ICredentialProvider
+     * @param {Object} params - Import parameters
+     * @param {string} params.uri - The URI containing the credential offer
+     * @param {any} params.didProvider - DID provider instance for key management
+     * @param {Function} [params.getAuthCode] - Optional callback to handle authorization
+     * @returns {Promise<any>} The imported credential
+     * @throws {Error} If import fails
+     * @example
+     * const credential = await credentialProvider.importCredentialFromURI({
+     *   uri: 'https://issuer.example.com/credential-offer',
+     *   didProvider,
+     *   getAuthCode: async (url) => getUserAuthCode(url)
+     * });
+     */
     importCredentialFromURI: async (params: importCredentialFromUriParams) =>
       importCredentialFromURI({
         ...params,
         wallet,
       }),
+    /**
+     * Retrieves credentials from the wallet, optionally filtered by type
+     * @memberof ICredentialProvider
+     * @param {string} [type='VerifiableCredential'] - The credential type to filter by
+     * @returns {any[]} Array of credentials matching the specified type
+     * @example
+     * const allCredentials = credentialProvider.getCredentials();
+     * const certificates = credentialProvider.getCredentials('Certificate');
+     */
     getCredentials,
+    /**
+     * Gets the membership witness for a credential (used for BBS+ credentials)
+     * @memberof ICredentialProvider
+     * @param {string} credentialId - The credential ID to get the witness for
+     * @returns {Promise<any>} The membership witness data
+     * @example
+     * const witness = await credentialProvider.getMembershipWitness('credential-123');
+     */
     getMembershipWitness: async (credentialId: string) =>
       getMembershipWitness({credentialId, wallet}),
+    /**
+     * Retrieves a credential by its ID
+     * @memberof ICredentialProvider
+     * @param {string} id - The unique identifier of the credential
+     * @returns {any} The credential document
+     * @throws {Error} If credential is not found
+     * @example
+     * const credential = await credentialProvider.getById('credential-123');
+     */
     getById: (id: string) => wallet.getDocumentById(id),
+    /**
+     * Checks if a credential uses BBS+ signature
+     * @memberof ICredentialProvider
+     * @param {any} credential - The credential to check
+     * @returns {boolean} True if the credential uses BBS+ signature
+     * @example
+     * const isBBS = credentialProvider.isBBSPlusCredential(credential);
+     * if (isBBS) {
+     *   console.log('This credential uses BBS+ signatures');
+     * }
+     */
     isBBSPlusCredential,
+    /**
+     * Validates a credential by verifying its cryptographic proof and status
+     * @memberof ICredentialProvider
+     * @param {any} credential - The credential to validate
+     * @param {boolean} [forceFetch=false] - Whether to force refresh the credential status
+     * @returns {Promise<Object>} Validation result
+     * @returns {string} returns.status - Validation status (verified, revoked, expired, invalid, pending)
+     * @returns {string} [returns.error] - Error message if validation failed
+     * @returns {string} [returns.warning] - Warning message if any
+     * @throws {Error} If validation fails
+     * @example
+     * const result = await credentialProvider.isValid(credential);
+     * if (result.status === 'verified') {
+     *   console.log('Credential is valid');
+     * } else if (result.status === 'revoked') {
+     *   console.log('Credential has been revoked');
+     * }
+     */
     isValid: async credential =>
       isValid({
         credential,
         wallet,
       }) as any,
+    /**
+     * Gets the current status of a credential (cached, fast operation)
+     * @memberof ICredentialProvider
+     * @param {any} credential - The credential to check
+     * @returns {Promise<Object>} Current credential status
+     * @returns {string} returns.status - Current status of the credential
+     * @returns {string} [returns.error] - Error message if any
+     * @example
+     * const status = await credentialProvider.getCredentialStatus(credential);
+     * console.log(`Credential status: ${status.status}`);
+     */
     getCredentialStatus: async (credential: Credential) => {
       assert(!!credential, 'credential is required');
 
@@ -379,10 +519,51 @@ export function createCredentialProvider({
         error: statusDoc?.error,
       };
     },
+    /**
+     * Synchronizes credential status from the blockchain
+     * @memberof ICredentialProvider
+     * @param {Object} params - Sync parameters
+     * @param {string[]} [params.credentialIds] - Optional list of credential IDs to sync
+     * @param {boolean} [params.forceFetch=false] - Whether to force refresh from blockchain
+     * @returns {Promise<any[]>} Array of credential status documents
+     * @example
+     * // Sync all credentials
+     * await credentialProvider.syncCredentialStatus({});
+     *
+     * // Sync specific credentials
+     * await credentialProvider.syncCredentialStatus({
+     *   credentialIds: ['cred-1', 'cred-2'],
+     *   forceFetch: true
+     * });
+     */
     syncCredentialStatus: async (props: SyncCredentialStatusParams) => {
       return syncCredentialStatus({wallet, ...props});
     },
+    /**
+     * Adds a credential to the wallet
+     * @memberof ICredentialProvider
+     * @param {any} credential - The credential to add
+     * @returns {Promise<any>} The added credential document
+     * @example
+     * const addedCredential = await credentialProvider.addCredential({
+     *   '@context': ['https://www.w3.org/2018/credentials/v1'],
+     *   type: ['VerifiableCredential'],
+     *   issuer: 'did:dock:issuer123',
+     *   credentialSubject: { name: 'Alice' }
+     * });
+     */
     addCredential: credential => addCredential({wallet, credential}),
+    /**
+     * Removes a credential and all its related documents from the wallet
+     * @memberof ICredentialProvider
+     * @param {any} credential - The credential to remove
+     * @returns {Promise<void>}
+     * @throws {Error} If credential is not found
+     * @example
+     * await credentialProvider.removeCredential(credential);
+     * // Or by ID
+     * await credentialProvider.removeCredential('credential-123');
+     */
     removeCredential: credential => removeCredential({wallet, credential}),
     // TODO: move import credential from json or URL to this provider
   };