@docknetwork/wallet-sdk-core 1.5.11 → 1.7.0

package/src/credential-provider.test.ts

@@ -227,7 +227,7 @@ describe('CredentialProvider', () => {
         });
 
       await provider.syncCredentialStatus({forceFetch: true});
-      
+
       // Clear mocks
       jest.clearAllMocks();
 
@@ -255,8 +255,227 @@ 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();
     });
   });
+
+  describe('isValid', () => {
+    it('should return pending status when SDK is not initialized and no cached status exists', async () => {
+      await provider.addCredential({
+        ...customerCredential,
+      });
+
+      jest
+        .spyOn(credentialServiceRPC, 'verifyCredential')
+        .mockImplementation(async () => {
+          return {
+            verified: false,
+            error: {
+              errors: [
+                {
+                  message: 'SDK is not initialized'
+                }
+              ]
+            }
+          };
+        });
+
+      const result = await provider.isValid({credential: customerCredential});
+      
+      expect(result.status).toBe(CredentialStatus.Pending);
+      expect(result.error).toContain('SDK is not initialized. Please ensure the blockchain is connected.');
+      expect(credentialServiceRPC.verifyCredential).toHaveBeenCalledTimes(1);
+    });
+  });
 });

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,26 +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<boolean>;
-  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' &&
@@ -44,6 +35,10 @@ type importCredentialFromUriParams = {
   getAuthCode?: (authorizationURL: string) => Promise<string>;
 };
 
+/**
+ * Internal function to import credential from URI
+ * @private
+ */
 export async function importCredentialFromURI({
   uri,
   wallet,
@@ -65,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 &&
@@ -75,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,
@@ -83,7 +82,11 @@ export async function isValid({
 }: {
   credential: Credential;
   wallet: IWallet;
-}) {
+}): Promise<{
+  status: string;
+  error?: string;
+  warning?: string;
+}> {
   assert(!!credential, 'credential is required');
 
   try {
@@ -109,6 +112,15 @@ export async function isValid({
 
     const {verified, error} = verificationResult;
 
+    if (error) {
+      const sdkNotInitialized = error?.errors?.find(err => err?.message === 'SDK is not initialized');
+      if (sdkNotInitialized) {
+        throw new Error(
+          'SDK is not initialized. Please ensure the blockchain is connected.',
+        );
+      }
+    }
+
     if (!verified) {
       if (
         typeof error === 'string' &&
@@ -156,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) {
@@ -179,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;
@@ -214,6 +249,10 @@ type CredentialStatusDocument = {
  * @param param0
  * @returns CredentialStatusDocument[]
  */
+/**
+ * Internal function to sync credential status from blockchain
+ * @private
+ */
 async function syncCredentialStatus({
   wallet,
   credentialIds,
@@ -252,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;
     }
 
@@ -296,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, 
@@ -322,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,
 }: {
@@ -332,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');
 
@@ -363,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
   };

package/src/credentials/oidvc.test.ts

@@ -6,7 +6,7 @@ import {
 } from './oidvc';
 import {credentialServiceRPC} from '@docknetwork/wallet-sdk-wasm/src/services/credential';
 import {MetadataClient} from '@sphereon/oid4vci-client';
-import jwtDecode from 'jwt-decode';
+import {jwtDecode} from 'jwt-decode';
 import axios from 'axios';
 
 jest.mock('@docknetwork/wallet-sdk-wasm/src/services/credential');

package/src/credentials/oidvc.ts

@@ -2,7 +2,7 @@ import {IWallet} from '../types';
 import {IDIDProvider} from '../did-provider';
 import {credentialServiceRPC} from '@docknetwork/wallet-sdk-wasm/src/services/credential';
 import {MetadataClient} from '@sphereon/oid4vci-client';
-import jwtDecode from 'jwt-decode';
+import {jwtDecode} from 'jwt-decode';
 import axios from 'axios';
 import {pexService} from '@docknetwork/wallet-sdk-wasm/src/services/pex';
 import {WellKnownEndpoints} from '@sphereon/oid4vci-common';