@docknetwork/wallet-sdk-web 0.0.5 → 0.0.8

package/README.md

@@ -18,6 +18,14 @@ or via CDN:
 
 The SDK can be used via a global variable (Script Tag) or imported as an ES Module (Bundlers).
 
+> [!IMPORTANT]
+> This SDK is designed for **browser-side use only**.
+
+1.  **Client-Side Only**: Your wallet keys (mnemonic/master key) decrypt your data locally in the browser. **Never** send these keys to a server or store them where they can be accessed by third parties.
+2.  **No Server-Side Operations**: Do not use this SDK to initialize wallets or process keys on a backend server. Server-side handling of user keys creates significant security risks and breaks the non-custodial model.
+3.  **End-to-End Encryption**: User data stored in the Cloud Wallet (EDV) is fully encrypted. The decryption key exists *only* in the user's browser session.
+4.  **Authentication vs Encryption**: The `edvAuthKey` is strictly for authenticating the client with the storage server. It does **not** grant access to the encrypted data content; only the user's keys can do that. You can request an `edvAuthKey` by contacting Truvera support at [docs.truvera.io/support](https://docs.truvera.io/support).
+
 ### 1. Script Tag (Global)
 
 When loaded via `<script>`, the SDK exposes a global variable `TruveraWebWallet`.
@@ -44,6 +52,8 @@ async function main() {
 }
 ```
 
+
+
 ### Key Generation (Optional)
 
 If you don't have a mnemonic, you can generate a new master key/mnemonic pair using the SDK:

package/dist/wallet-sdk-web.esm.js

@@ -560555,140 +560555,386 @@ function createVerificationController(_ref) {
   };
 }
 
+/**
+ * @fileoverview Dock Wallet SDK for Web
+ *
+ * This module provides a simplified interface for initializing and working with
+ * the Dock Wallet SDK in web environments. It includes functions for managing
+ * DIDs, credentials, presentations, and cloud wallet synchronization.
+ *
+ * @module @docknetwork/wallet-sdk-web
+ */
+
+
+/**
+ * Initializes the Dock Wallet SDK with the provided configuration.
+ *
+ * This function sets up all necessary wallet providers and establishes a connection
+ * to the cloud wallet for synchronization. It requires either a master key or mnemonic
+ * for wallet recovery, but not both.
+ *
+ * @async
+ * @param {Object} config - Configuration object for wallet initialization
+ * @param {string} config.edvUrl - The Encrypted Data Vault (EDV) URL for cloud storage
+ * @param {string} config.edvAuthKey - Authentication key for accessing the EDV
+ * @param {string} [config.masterKey] - Master key for wallet access (required if mnemonic is not provided)
+ * @param {string} [config.mnemonic] - BIP39 mnemonic for wallet recovery (required if masterKey is not provided)
+ * @param {string} config.networkId - Network identifier ('testnet' or 'mainnet')
+ * @param {string} [config.databasePath='truvera-web-wallet'] - Optional path for the local database
+ *
+ * @returns {Promise<Object>} Initialized wallet object with the following properties:
+ * @returns {Object} returns.wallet - Core wallet instance
+ * @returns {Object} returns.messageProvider - Provider for handling wallet messages
+ * @returns {Object} returns.cloudWallet - Cloud wallet instance for synchronization
+ * @returns {Object} returns.didProvider - Provider for DID operations
+ * @returns {Object} returns.credentialProvider - Provider for credential operations
+ * @returns {Function} returns.getCredentials - Function to retrieve all credentials
+ * @returns {Function} returns.addCredential - Function to import a credential from an offer URI
+ * @returns {Function} returns.getDID - Function to get the default DID
+ * @returns {Function} returns.submitPresentation - Function to create and submit a presentation
+ *
+ * @throws {Error} When neither masterKey nor mnemonic is provided
+ * @throws {Error} When both masterKey and mnemonic are provided
+ * @throws {Error} When edvUrl is not provided
+ * @throws {Error} When edvAuthKey is not provided
+ * @throws {Error} When networkId is not provided
+ * @throws {Error} When networkId is not 'testnet' or 'mainnet'
+ * @throws {Error} When wallet initialization fails
+ * @throws {Error} When cloud wallet initialization fails
+ *
+ * @example
+ * // Initialize with mnemonic
+ * const wallet = await initialize({
+ *   edvUrl: 'https://edv.example.com',
+ *   edvAuthKey: 'your-auth-key',
+ *   mnemonic: 'your twelve word mnemonic phrase here...',
+ *   networkId: 'testnet'
+ * });
+ *
+ * @example
+ * // Initialize with master key
+ * const wallet = await initialize({
+ *   edvUrl: 'https://edv.example.com',
+ *   edvAuthKey: 'your-auth-key',
+ *   masterKey: 'your-master-key',
+ *   networkId: 'mainnet',
+ *   databasePath: 'custom-wallet-db'
+ * });
+ */
 async function initialize(_ref) {
   let {
     edvUrl,
     edvAuthKey,
-    networkId,
     masterKey,
-    mnemonic
+    mnemonic,
+    networkId,
+    databasePath
   } = _ref;
+  // Validate required parameters
   if (!masterKey && !mnemonic) {
-    throw new Error('Master key or mnemonic is required');
+    throw new Error('Initialization failed: Either masterKey or mnemonic must be provided for wallet access');
   }
   if (masterKey && mnemonic) {
-    throw new Error('Master key and mnemonic cannot be used together');
+    throw new Error('Initialization failed: Cannot provide both masterKey and mnemonic. Please use only one authentication method');
   }
   if (!edvUrl) {
-    throw new Error('EDV URL is required');
+    throw new Error('Initialization failed: edvUrl is required. Please provide a valid Encrypted Data Vault URL');
+  }
+  if (typeof edvUrl !== 'string' || !edvUrl.trim()) {
+    throw new Error('Initialization failed: edvUrl must be a non-empty string');
   }
   if (!edvAuthKey) {
-    throw new Error('EDV Auth Key is required');
+    throw new Error('Initialization failed: edvAuthKey is required for EDV authentication');
+  }
+  if (typeof edvAuthKey !== 'string' || !edvAuthKey.trim()) {
+    throw new Error('Initialization failed: edvAuthKey must be a non-empty string');
   }
   if (!networkId) {
-    throw new Error('Network ID is required');
+    throw new Error('Initialization failed: networkId is required. Must be either "testnet" or "mainnet"');
   }
-  const dataStore = await createDataStore({
-    databasePath: 'dock-wallet',
-    defaultNetwork: networkId || 'testnet'
-  });
-  console.log('Data store created');
-  const wallet = await createWallet({
-    dataStore
-  });
-  console.log('Wallet created');
-  const didProvider = createDIDProvider({
-    wallet
-  });
-  console.log('DID provider created');
-  const credentialProvider = await createCredentialProvider({
-    wallet
-  });
-  console.log('Credential provider created');
-  createMessageProvider({
-    wallet,
-    didProvider
-  });
-  console.log('Message provider created');
+  if (networkId !== 'testnet' && networkId !== 'mainnet') {
+    throw new Error("Initialization failed: Invalid networkId \"".concat(networkId, "\". Must be either \"testnet\" or \"mainnet\""));
+  }
+
+  // Initialize data store
+  let dataStore;
+  try {
+    dataStore = await createDataStore({
+      databasePath: databasePath || 'truvera-web-wallet',
+      defaultNetwork: networkId
+    });
+  } catch (error) {
+    throw new Error("Failed to create data store: ".concat(error.message));
+  }
+
+  // Initialize wallet
+  let wallet;
+  try {
+    wallet = await createWallet({
+      dataStore
+    });
+  } catch (error) {
+    throw new Error("Failed to create wallet: ".concat(error.message));
+  }
+
+  // Initialize providers
+  let didProvider, credentialProvider, messageProvider;
+  try {
+    didProvider = createDIDProvider({
+      wallet
+    });
+    credentialProvider = await createCredentialProvider({
+      wallet
+    });
+    messageProvider = createMessageProvider({
+      wallet,
+      didProvider
+    });
+  } catch (error) {
+    throw new Error("Failed to initialize wallet providers: ".concat(error.message));
+  }
+
+  // Recover or set master key
   if (mnemonic) {
-    masterKey = await recoverCloudWalletMasterKey(mnemonic);
-  } else if (masterKey) {
-    masterKey = masterKey;
-  } else {
-    throw new Error('Master key or mnemonic is required');
+    try {
+      masterKey = await recoverCloudWalletMasterKey(mnemonic);
+    } catch (error) {
+      throw new Error("Failed to recover master key from mnemonic: ".concat(error.message));
+    }
   }
-  const cloudWallet = await initializeCloudWallet({
-    dataStore: dataStore,
-    edvUrl: edvUrl,
-    masterKey: masterKey,
-    authKey: edvAuthKey
-  });
-  console.log('Cloud wallet created');
-  console.log(credentialProvider);
+
+  // Initialize cloud wallet
+  let cloudWallet;
   try {
-    const documents = await cloudWallet.pullDocuments();
-  } catch (err) {
-    console.error('Error pulling documents', err);
+    cloudWallet = await initializeCloudWallet({
+      dataStore: dataStore,
+      edvUrl: edvUrl,
+      masterKey: masterKey,
+      authKey: edvAuthKey
+    });
+  } catch (error) {
+    throw new Error("Failed to initialize cloud wallet: ".concat(error.message));
+  }
+
+  // Pull documents from cloud (non-critical operation)
+  try {
+    await cloudWallet.pullDocuments();
+  } catch (error) {
+    console.warn('Warning: Failed to pull documents from cloud wallet. You may need to sync manually.', error.message);
   }
   return {
-    // Simplified API for common use cases
     wallet,
+    messageProvider,
+    cloudWallet,
+    didProvider,
+    credentialProvider,
     /**
-     * Get the list of credentials
-     * @returns 
+     * Retrieves all credentials stored in the wallet.
+     *
+     * @async
+     * @returns {Promise<Array>} Array of credential objects
+     * @throws {Error} When credential retrieval fails
+     *
+     * @example
+     * const credentials = await wallet.getCredentials();
+     * console.log(`Found ${credentials.length} credentials`);
      */
     getCredentials: async () => {
-      return await credentialProvider.getCredentials();
+      try {
+        return await credentialProvider.getCredentials();
+      } catch (error) {
+        throw new Error("Failed to retrieve credentials: ".concat(error.message));
+      }
     },
     /**
-     * Import credential using an offer URI
-     * @param {*} uri 
-     * @returns 
+     * Imports a credential using an OpenID4VC (OID4VCI) offer URI.
+     *
+     * @async
+     * @param {string} uri - The credential offer URI (e.g., openid-credential-offer://...)
+     * @returns {Promise<Object>} The imported credential object
+     * @throws {Error} When the URI is invalid or credential import fails
+     *
+     * @example
+     * const credential = await wallet.addCredential('openid-credential-offer://...');
+     * console.log('Credential imported:', credential.id);
      */
     addCredential: async uri => {
-      return await credentialProvider.importCredentialFromURI({
-        uri,
-        didProvider
-      });
+      if (!uri || typeof uri !== 'string') {
+        throw new Error('Invalid credential offer URI: URI must be a non-empty string');
+      }
+      try {
+        return await credentialProvider.importCredentialFromURI({
+          uri,
+          didProvider
+        });
+      } catch (error) {
+        throw new Error("Failed to import credential from URI: ".concat(error.message));
+      }
     },
     /**
-     * Get default DID
-     * @returns 
+     * Retrieves the default DID (Decentralized Identifier) for the wallet.
+     *
+     * @async
+     * @returns {Promise<string>} The default DID string
+     * @throws {Error} When DID retrieval fails or no DID exists
+     *
+     * @example
+     * const did = await wallet.getDID();
+     * console.log('Default DID:', did);
      */
     getDID: async () => {
-      return await didProvider.getDefaultDID();
+      try {
+        return await didProvider.getDefaultDID();
+      } catch (error) {
+        throw new Error("Failed to retrieve default DID: ".concat(error.message));
+      }
     },
     /**
-     * Submit a presentation for the given credentials and proof request URL
-     * @param {*} param0 
-     * @param {Object} param0.credentials - Map of credential id with attributesToReveal object
-     * @param {string} param0.proofRequestUrl - Proof request URL should be a valid URL to a proof request template
-     * 
+     * Creates and submits a verifiable presentation for the given credentials and proof request.
+     *
+     * This function processes a proof request from a verifier, selects the specified credentials,
+     * creates a presentation with the requested attributes, and submits it to the verifier.
+     *
+     * @async
+     * @param {Object} config - Configuration object for presentation submission
+     * @param {Array<Object>} config.credentials - Array of credential objects to include in the presentation
+     * @param {string} config.credentials[].id - The credential ID
+     * @param {Object} config.credentials[].attributesToReveal - Map of attribute names to reveal
+     * @param {Array<string>} config.credentials[].attributesToReveal - Array of attribute names to reveal from this credential
+     * @param {string} config.proofRequestUrl - URL to the proof request template from the verifier
+     *
+     * @returns {Promise<Object>} The submission response from the verifier
+     * @throws {Error} When credentials array is empty or invalid
+     * @throws {Error} When proofRequestUrl is invalid
+     * @throws {Error} When verification controller fails to start
+     * @throws {Error} When presentation creation fails
+     * @throws {Error} When presentation submission fails
+     *
      * @example
-     * const presentation = await cloudWallet.createPresentation({
-     *   credentials: {
-     *     'credentialId': { attributesToReveal: ['attribute1', 'attribute2'] },
-     *   },
-     *   proofRequestUrl: 'https://example.com/proof-request',
+     * // Submit a presentation with selective disclosure
+     * const result = await wallet.submitPresentation({
+     *   credentials: [
+     *     {
+     *       id: 'credential-123',
+     *       attributesToReveal: ['name', 'dateOfBirth']
+     *     },
+     *     {
+     *       id: 'credential-456',
+     *       attributesToReveal: ['email']
+     *     }
+     *   ],
+     *   proofRequestUrl: 'https://verifier.example.com/proof-request/abc123'
      * });
-     * @returns 
      */
     submitPresentation: async _ref2 => {
       let {
-        // Map of credential id with attributesToReveal object
         credentials,
-        // Proof request URL should be a valid URL to a proof request template
         proofRequestUrl
       } = _ref2;
-      const verificationController = createVerificationController({
-        wallet,
-        credentialProvider,
-        didProvider
-      });
-      await verificationController.start({
-        template: proofRequestUrl
-      });
+      // Validate inputs
+      if (!credentials || !Array.isArray(credentials) || credentials.length === 0) {
+        throw new Error('Invalid credentials: Must provide a non-empty array of credentials');
+      }
+      if (!proofRequestUrl || typeof proofRequestUrl !== 'string') {
+        throw new Error('Invalid proofRequestUrl: Must be a valid URL string');
+      }
+
+      // Validate each credential
       for (const credential of credentials) {
-        verificationController.selectedCredentials.set(credential.id, {
-          credential: credential,
-          attributesToReveal: credentials[credential.id].attributesToReveal
+        if (!credential.id) {
+          throw new Error('Invalid credential: Each credential must have an id property');
+        }
+        if (!credential.attributesToReveal) {
+          throw new Error("Invalid credential ".concat(credential.id, ": Missing attributesToReveal property"));
+        }
+      }
+      let verificationController;
+      try {
+        verificationController = createVerificationController({
+          wallet,
+          credentialProvider,
+          didProvider
         });
+      } catch (error) {
+        throw new Error("Failed to create verification controller: ".concat(error.message));
+      }
+      try {
+        await verificationController.start({
+          template: proofRequestUrl
+        });
+      } catch (error) {
+        throw new Error("Failed to start verification with proof request: ".concat(error.message));
+      }
+
+      // Select credentials and attributes to reveal
+      try {
+        for (const credential of credentials) {
+          verificationController.selectedCredentials.set(credential.id, {
+            credential: credential,
+            attributesToReveal: credential.attributesToReveal
+          });
+        }
+      } catch (error) {
+        throw new Error("Failed to select credentials: ".concat(error.message));
+      }
+      let presentation;
+      try {
+        presentation = await verificationController.createPresentation();
+      } catch (error) {
+        throw new Error("Failed to create presentation: ".concat(error.message));
+      }
+      try {
+        return await verificationController.submitPresentation(presentation);
+      } catch (error) {
+        throw new Error("Failed to submit presentation: ".concat(error.message));
       }
-      const presentation = await verificationController.createPresentation();
-      return await verificationController.submitPresentation(presentation);
     }
   };
 }
+
+/**
+ * Dock Wallet SDK - Web Module
+ *
+ * Provides a comprehensive SDK for building decentralized identity wallets in web applications.
+ * Includes high-level initialization functions and low-level building blocks for custom implementations.
+ *
+ * @namespace DockWalletSDK
+ *
+ * @property {Function} initialize - High-level function to initialize a complete wallet with all providers
+ * @property {Function} createDataStore - Create a data store for wallet data persistence
+ * @property {Function} createWallet - Create a core wallet instance
+ * @property {Function} createCredentialProvider - Create a provider for credential management
+ * @property {Function} createDIDProvider - Create a provider for DID operations
+ * @property {Function} createMessageProvider - Create a provider for wallet messaging
+ * @property {Function} initializeCloudWallet - Initialize cloud wallet synchronization
+ * @property {Function} generateCloudWalletMasterKey - Generate a new master key for cloud wallet
+ * @property {Function} recoverCloudWalletMasterKey - Recover master key from a BIP39 mnemonic
+ * @property {Function} createVerificationController - Create a controller for verification presentations
+ *
+ * @example
+ * // Quick start - use the high-level initialize function
+ * import WalletSDK from '@docknetwork/wallet-sdk-web';
+ *
+ * const wallet = await WalletSDK.initialize({
+ *   edvUrl: 'https://edv.dock.io',
+ *   edvAuthKey: 'your-auth-key',
+ *   mnemonic: 'your mnemonic phrase...',
+ *   networkId: 'testnet'
+ * });
+ *
+ * @example
+ * // Advanced usage - build custom wallet with individual components
+ * import WalletSDK from '@docknetwork/wallet-sdk-web';
+ *
+ * const dataStore = await WalletSDK.createDataStore({
+ *   databasePath: 'my-wallet',
+ *   defaultNetwork: 'mainnet'
+ * });
+ *
+ * const wallet = await WalletSDK.createWallet({ dataStore });
+ * const didProvider = WalletSDK.createDIDProvider({ wallet });
+ * // ... configure additional providers as needed
+ */
 var index = {
   initialize,
   createDataStore,