From 8212507cd7f4f59977d67d017d3717b5e8646947 Mon Sep 17 00:00:00 2001 From: Richard Esplin Date: Sat, 4 Oct 2025 21:22:17 -0600 Subject: [PATCH 1/4] A few more minor cleanup items in the docs --- docs/getting-started.md | 2 +- docs/other-topics.md | 4 +--- examples/nodejs-example/readme.md | 4 ++-- 3 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index fa595fd6..681e0e49 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,4 +1,4 @@ -# Truvera Wallet SDK +# Getting Started with the Truvera Wallet SDK This guide walks you through the process of setting up the Truvera Wallet SDK, creating a wallet, managing decentralized identifiers (DIDs), adding credentials, and verifying them. diff --git a/docs/other-topics.md b/docs/other-topics.md index 54bcd3b9..956add19 100644 --- a/docs/other-topics.md +++ b/docs/other-topics.md @@ -10,6 +10,4 @@ The WebView is similar to a REST API, and its entry point is in the wallet-sdk-w interacts with `@docknetwork/wallet-sdk-wasm/lib/services/[moduleName]/service.js` -Notice that the `modules` folder is running in the main thread (react native) and will be using the json rpc client (`@docknetwork/wallet-sdk-core/lib/client`) to interact with `@docknetwork/wallet-sdk-core/lib/service` methods - - +Notice that the `modules` folder is running in the main thread (React Native) and will be using the JSON RPC client (`@docknetwork/wallet-sdk-core/lib/client`) to interact with `@docknetwork/wallet-sdk-core/lib/service` methods. diff --git a/examples/nodejs-example/readme.md b/examples/nodejs-example/readme.md index b04f8fb0..22651e47 100644 --- a/examples/nodejs-example/readme.md +++ b/examples/nodejs-example/readme.md @@ -1,5 +1,5 @@ -# Wallet sdk web examples -This is an examples on how to install the Truvera Wallet SDK in a nodejs application. +# Wallet SDK NodeJS Example +This example illustrates how to install the Truvera Wallet SDK in a Node.js application. ## Installation steps From 8c2f634c040f16326f858b1e5596ebfc30f373f3 Mon Sep 17 00:00:00 2001 From: Richard Esplin Date: Sat, 4 Oct 2025 21:47:41 -0600 Subject: [PATCH 2/4] Clarifications to the biometric plugin documentation --- docs/biometric-plugin.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/biometric-plugin.md b/docs/biometric-plugin.md index 06bb4b52..7eaeb407 100644 --- a/docs/biometric-plugin.md +++ b/docs/biometric-plugin.md @@ -2,11 +2,23 @@ ## Purpose -The biometrics plugin provides a way to perform credential verification using the user's biometric data. It is useful to guarantee that only the biometric holder can perform the verification. +The biometrics plugin allows for the collection of the user's biometric data as part of credential verification. This allows the verification process to guarantee that only the physical person who was issued the credential can perform the verification. + +## Overview + +When the wallet detects a request for a biometric check credential, it will trigger the biometric plugin to perform a biometric collection. If the user has not previously enrolled a biometric template, the user can be onboarded with the biometric service which can create an enrollment credential. The enrollment credential can contain the biometric template, or point to a biometric template hosted elsewhere. If the user has previously enrolled, then the biometric collection can be compared with the contents of the enrollment credential. + +The enrollment credential also contains a biometric ID, which is a random string that can be used to identify a successful biometric check for a specific use case. For privacy purposes, the biometric ID should not be derived from the user's actual biometric. If the currently collected sample matches the biometric template, then the biometric ID stored in the enrollment credential can be put into a biometric check credential which can be shared without disclosing the user's biometric. + +During issuance, the issuer can request a recent biometric check credential and embed the biometric ID and biometric issuer DID into the credential that is being issued. + +During verification, the verifier can request a recent biometric check credential alongside the credential with the attributes of interest. If the holder can produce a biometric check credential that contains the same biometric ID as is embedded in the credential of interest and also comes from the same biometric issuer as the credential of interest, then the relying party can be confident that it is the same physical person who was issued the credential. + +You can learn more about [biometric bound credentials in the solutions section of the documentation](https://docs.truvera.io/solutions/biometric-bound-credentials). ## Flow -The biometric plugin flow is the following: +The following diagram details the flow of the biometric plugin: ```mermaid sequenceDiagram @@ -100,7 +112,7 @@ The presence of the following fields should trigger the biometric check: ## How to enable the biometric plugin in the wallet -To enable the biometric plugin in a white-label wallet, you need to edit the following file src/wallet-sdk-configs.ts and add your configuration: +To enable the biometric plugin in a white-label wallet, you need to edit `src/wallet-sdk-configs.ts` and add your configuration: ```typescript import { BiometricsProviderConfigs, IDVProviderFactory, setConfigs } from '@docknetwork/wallet-sdk-core/src/biometric-provider'; @@ -135,7 +147,7 @@ export const idvProviderFactory: IDVProviderFactory = { ``` -The truvera biometric plugin requires the following configs: +The Truvera biometric plugin requires the following configs: * walletApiUrl: The URL of the wallet API that will be used to issue the credentials * ecosystemID: The ecosystem ID of the biometric service From a26931f68c4bd4e82d772f45d297c95312d48657 Mon Sep 17 00:00:00 2001 From: Richard Esplin Date: Sat, 4 Oct 2025 21:56:05 -0600 Subject: [PATCH 3/4] More clarification for ecosystem tools --- docs/ecosystem-tools.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/ecosystem-tools.md b/docs/ecosystem-tools.md index 22d6ae76..8a0bd39a 100644 --- a/docs/ecosystem-tools.md +++ b/docs/ecosystem-tools.md @@ -1,8 +1,11 @@ # Ecosystem Tools -You can find the implementation of ecosystem tools in the following location: +An ecosystem is a trusted set of issuers and verifiers. If a credential is associated with an ecosystem, then the credential details will include the ecosystem logo and a link to the ecosystem web page. This allows credential holders to become familiar with the branding of an ecosystem which they can then use to identify verifiers who will trust the ecosystem credentials and abide by the ecosystem's policies. -File Path: [packages/core/src/ecosystem-tools.ts](https://github.com/docknetwork/wallet-sdk/blob/5dfbcb197b848802478d2f7a697286a8c3c28823/packages/core/src/ecosystem-tools.ts#L4) +The functions of an ecosystem are further described in [the Ecosystem Tools section of the API documentation](https://docs.truvera.io/truvera-api/ecosystem-tools). + +The Truvera Wallet SDK implementation of ecosystem tools is in: +[packages/core/src/ecosystem-tools.ts](https://github.com/docknetwork/wallet-sdk/blob/5dfbcb197b848802478d2f7a697286a8c3c28823/packages/core/src/ecosystem-tools.ts#L4) ## Usage Example @@ -29,7 +32,7 @@ fetchEcosystemDetails(); ## Expected Output -When you run the above code, you should expect an output similar to this: +When you run the above code, you should expect output similar to this: ```json { @@ -46,5 +49,6 @@ This JSON output contains the details of the ecosystems associated with the give ## Integration Tests For more examples and usage, please refer to the integration test at: +https://github.com/docknetwork/wallet-sdk/blob/master/integration-tests/ecosystem-tools.test.ts -Test File Path: https://github.com/docknetwork/wallet-sdk/blob/master/integration-tests/ecosystem-tools.test.ts This test file provides comprehensive examples on how to interact with ecosystem tools effectively. +This test file provides comprehensive examples on how to interact with ecosystem tools effectively. From 900d17a89e0c8d1e8e2a9879bbdf50e77351d096 Mon Sep 17 00:00:00 2001 From: Richard Esplin Date: Sat, 4 Oct 2025 23:39:41 -0600 Subject: [PATCH 4/4] Cloud wallet docs clarifications --- docs/cloud-wallet.md | 47 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 8 deletions(-) diff --git a/docs/cloud-wallet.md b/docs/cloud-wallet.md index f219955f..d7f88d58 100644 --- a/docs/cloud-wallet.md +++ b/docs/cloud-wallet.md @@ -1,12 +1,17 @@ # Cloud Wallet Documentation -The Cloud Wallet feature allows secure storage and synchronization of wallet documents via an [Encrypted Data Vault (EDV)](https://digitalbazaar.github.io/encrypted-data-vaults/). +The Truvera Cloud Wallet provides SaaS hosted secure storage of a user's identity data. The contents of an individual cloud wallet are accessed through a wallet application. The Cloud Wallet APIs support synchronization between the cloud storage and local storage of a wallet application. In addition to standard mobile or web wallet applications, the Cloud Wallet also allows credentials to be used in existing web sites through embedded widgets. The Cloud Wallet is especially useful for non-human identity use cases, such as organizational identity wallets and wallets for AI agents. -**File Path:** `@docknetwork/wallet-sdk-core/src/cloud-wallet` +The implementation is in: +`@docknetwork/wallet-sdk-core/src/cloud-wallet` ## Feature Overview -The Cloud Wallet integrates with an [Encrypted Data Vault (EDV)](https://digitalbazaar.github.io/encrypted-data-vaults/) to securely store, sync, and manage documents. Once initialized, it automatically synchronizes documents between the EDV and the wallet, allowing you to add, update, remove, without dealing with the synchronization logic. +The Truvera Cloud Wallet service hosts individual wallets for each user. The user's wallet stores encrypted documents that usually contain verifiable credentials. The service includes an [Encrypted Data Vault (EDV)](https://digitalbazaar.github.io/encrypted-data-vaults/) to securely store, sync, and manage documents. The Truvera Platform includes an EDV instance that can be used as part of a Truvera solution, but you can also deploy an EDV instance within your infrastructure if you prefer to host the encrypted user data. In most solutions, documents should be encrypted by the wallet application before being stored in the cloud wallet so that it cannot be read by the organization hosting the EDV. + +Once initialized, the Cloud Wallet automatically synchronizes documents between the EDV and the wallet application, allowing you to add, update, and remove credentials without dealing with the synchronization logic. + +Each holder's individual cloud wallet is accessed using a key in the holder's possession. This key can be stored in the local storage of a wallet application, or derived from a biometric of the holder's. A recovery mnemonic can be used to recover a lost master key. ## Usage Example @@ -41,7 +46,7 @@ const dataStore = await createDataStore({ ### Step 2: Generate Wallet Key and Mnemonic -Next, we generate key and mnemonic for interacting with the cloud wallet. Use the same Cloud Wallet key across multiple devices to access the same documents. These keys are used to encrypt, decrypt, and locate documents in the EDV. +Next, we generate a key and mnemonic for interacting with the cloud wallet. Use the same Cloud Wallet key across multiple devices to access the same documents. These keys are used to encrypt, decrypt, and locate documents in the EDV. ```ts import {generateCloudWalletMasterKey} from '@docknetwork/wallet-sdk-core/lib/cloud-wallet'; @@ -51,7 +56,7 @@ const {masterKey, mnemonic} = await generateCloudWalletMasterKey(); The `masterKey` is used to derive encryption keys for the EDV, while the `mnemonic` is used to recover the master key. -**Note:** Encryption keys can be derived from biometric data through a third-party service, offering enhanced security by linking the keys to a user's unique biometric profile +**Note:** Encryption keys can be derived from biometric data through a third-party service, offering enhanced security by linking the keys to a user's unique biometric profile. If the master key is lost, the mnemonic can be used to recover it. Store the mnemonic securely and do not share it with anyone. ```ts @@ -62,7 +67,7 @@ const masterKey = await recoverCloudWalletMasterKey(mnemonic); ### Step 3: Initialize the Cloud Wallet -After setting up the data store and generating key, initialize the Cloud Wallet and connect it to the local data storage. This ensures continuous synchronization between the EDV and the wallet. +After setting up the data store and generating the key, initialize the Cloud Wallet and connect it to the local data storage. This ensures continuous synchronization between the EDV and the wallet. ```ts import {initializeCloudWallet} from '@docknetwork/wallet-sdk-core/lib/cloud-wallet'; @@ -108,7 +113,7 @@ await wallet.addDocument(document); ### Issuing Credentials to Cloud Wallet -You can issue credentials directly to a cloud wallet using the Truvera Workspace/API. The credential will be automatically distributed to the holder's cloud wallet through the DIDComm protocol, eliminating the need for direct API calls or manual credential handling. +You can issue credentials directly to a cloud wallet using the Truvera Workspace or the Truvera API. The credential will be automatically distributed to the holder's cloud wallet through the DIDComm protocol, eliminating the need for direct API calls or manual credential handling. #### Important Requirement @@ -195,9 +200,13 @@ The system uses a two-vault architecture: - KeyMappingVault: Stores encrypted master keys that can only be accessed with proper authentication - CloudWalletVault: The main vault containing wallet documents, secured by the master key +We will provide an example of how this two-vault architecture can be used to allow biometric authentication to the cloud wallet. + +Note that the biometric sample used to authenticate to a cloud wallet could also be provided to a [biometric service](https://github.com/docknetwork/wallet-sdk/blob/master/docs/biometric-plugin.md) in order to issue a new biometric check credential as described in [biometric bound credentials](https://docs.truvera.io/solutions/biometric-bound-credentials). + #### Step 1: Enroll User with Biometric Data -To set up biometric authentication, enroll the user with their biometric data and identifier (typically an email): +To set up biometric authentication, enroll the user with their biometric data and identifier: ```ts import { enrollUserWithBiometrics } from '@docknetwork/wallet-sdk-core/lib/cloud-wallet'; @@ -222,6 +231,8 @@ The enrollment process: 3. Encrypts the master key with the biometric-derived keys 4. Stores the encrypted master key in the KeyMappingVault, indexed by the user's email +In this example, the user email address is provided as a unique identifier to look up the biometric template for highly secure one-to-one biometric matching. The identifier is not shared with issuers or verifiers and any identifier may be used so long as it is convenient for the holder to remember. Phone numbers are another common choice. Biometric solutions that support one-to-n matching might be sufficient for many scenarios and would allow the user to avoid having to remember and provide an identifier. If you use an identifier, remember to verify that the user is actually in control of the identifier or an attacker could register the identifier and prevent the legitimate holder from accessing the service. + #### Step 2: Authenticate with Biometrics Next, when the user wants to access their wallet, they can authenticate with their biometric data: @@ -259,3 +270,23 @@ The authentication process: 3. Derives decryption keys from the provided biometric data 4. Decrypts the master key 5. Uses the master key to access the CloudWalletVault + +### Wallet Recovery + +This architecture allows solution developers to design the recovery mechanism that makes sense for your use case. + +If only a master key is used, then the mnemonic should also be provided to the user so that they can regenerate the master key if necessary. + +Alternatively, one or more recovery keys can be stored in the KeyMappingVault. As they are used, old keys can be removed and new keys can be added. + +If a biometrically derived key can no longer be generated, then a recovery key should be used to enroll a new biometric. Any biometric-bound credentials will need to be reissued with the new biometric. + + +## Organizational Wallets + +Verifiable credentials can help automate many processes that include organization identity, such as credit worthiness or Know-Your-Business (KYB) checks. Organization information that originates with a third party and then must be privately shared with a relying party is well suited to verifiable credentials. + +By storing organizational credentials in a cloud wallet, multiple members of the organization can access the wallet to present the credentials as needed. The multi-key authentication described above allows for integration with a variety of authentication and authorization systems. + +* Keys to the organization's cloud wallet can be stored in a corporate secrets vault or password manager, through which access can be granted to authorized employees. +* Staff can authenticate with the corporate IAM system. If they are authorized to use the cloud wallet, then the key stored in the IAM system can be used for the cloud wallet.