Cloud wallet
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.
The implementation is in: @docknetwork/wallet-sdk-core/src/cloud-wallet
Feature Overview
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) 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
The example below demonstrates how to initialize and use the Cloud Wallet for managing documents.
Step 1: Initialize the Data Store
First, you need to create local data storage to connect to the credential wallet.
For Mobile and Node.js
import {createDataStore} from '@docknetwork/wallet-sdk-data-store-typeorm/lib';
const dataStore = await createDataStore({
databasePath: 'dock-wallet',
dbType: 'sqlite',
defaultNetwork: 'testnet',
});
For Browser
import {createDataStore} from '@docknetwork/wallet-sdk-data-store-web/lib';
const dataStore = await createDataStore({
databasePath: 'dock-wallet',
defaultNetwork: 'testnet',
});
Step 2: Generate Wallet Key and Mnemonic
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.
import {generateCloudWalletMasterKey} from '@docknetwork/wallet-sdk-core/lib/cloud-wallet';
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.
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.
import {recoverCloudWalletMasterKey} from '@docknetwork/wallet-sdk-core/lib/cloud-wallet';
const masterKey = await recoverCloudWalletMasterKey(mnemonic);
Step 3: Initialize the cloud storage
After setting up the data store and generating keys, initialize the cloud storage and connect it to the local data storage. This ensures continuous synchronization between the EDV and the wallet.
import {initializeCloudWallet} from '@docknetwork/wallet-sdk-core/lib/cloud-wallet';
const {pullDocuments} = await initializeCloudWallet({
dataStore,
edvUrl: EDV_URL,
authKey: EDV_AUTH_KEY,
masterKey,
});
// Pull documents from the EDV and sync with the wallet
await pullDocuments();
The pullDocuments
function synchronizes the EDV and the wallet by comparing documents and updating the data store accordingly. Documents can be credentials or messages.
Step 4: Create a New Wallet
Now, create a credential wallet inside of the data storage. This will allow you to add, update, and remove documents.
import {createWallet} from '@docknetwork/wallet-sdk-core/lib/wallet';
const wallet = await createWallet({
dataStore,
});
Step 5: Add a Document to the Wallet
You can add a document to the wallet using the following code:
const document = {
id: 'document-id',
type: 'document-type',
someData: 'any-data-you-want',
};
await wallet.addDocument(document);
Issuing Credentials to Cloud Wallet
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
For the DIDComm automatic distribution to work properly, the subject ID of the credential must be set to the holder's DID when issuing the credential. This enables the system to route the credential to the correct wallet.
Receiving Credentials in Cloud Wallet
After a credential has been issued to a holder's DID, the cloud wallet only needs to fetch and process DIDComm messages to receive it:
import {createDIDProvider} from '@docknetwork/wallet-sdk-core/lib/did-provider';
import {createMessageProvider} from '@docknetwork/wallet-sdk-core/lib/message-provider';
const didProvider = createDIDProvider({ wallet });
const messageProvider = createMessageProvider({
wallet,
didProvider,
});
// This will process the messages for all the DIDs in the wallet
await messageProvider.fetchMessages();
await messageProvider.processDIDCommMessages();
Full Example
import {createDataStore} from '@docknetwork/wallet-sdk-data-store-web/lib';
import {initializeCloudWallet} from '@docknetwork/wallet-sdk-core/lib/cloud-wallet';
import {createWallet} from '@docknetwork/wallet-sdk-core/lib/wallet';
async function example() {
const dataStore = await createDataStore({
databasePath: 'dock-wallet',
defaultNetwork: 'testnet',
});
const {pullDocuments} = await initializeCloudWallet({
dataStore,
edvUrl: EDV_URL,
authKey: EDV_AUTH_KEY,
masterKey,
});
// Pull documents from the EDV and sync with the wallet
await pullDocuments();
const wallet = await createWallet({
dataStore,
});
const document = {
id: 'document-id',
type: 'document-type',
someData: 'any-data-you-want',
};
await wallet.addDocument(document);
}
example();
Multi-Key Authentication
The Cloud Wallet supports multiple authentication methods to unlock the same wallet, providing both security and convenience.
Available Authentication Methods
Mnemonic-based authentication: The traditional recovery phrase approach
Biometric authentication: Using fingerprints, facial recognition, or other biometric data
Future extensions: Can be extended to support passkeys and other authentication methods
How Multi-Key Authentication Works
The Cloud Wallet uses a key mapping system that allows a secondary key (e.g. derived from biometrics) to unlock the same master key that was originally derived from a mnemonic phrase.
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 in order to issue a new biometric check credential as described in biometric bound credentials.
Step 1: Enroll User with Biometric Data
To set up biometric authentication, enroll the user with their biometric data and identifier:
import { enrollUserWithBiometrics } from '@docknetwork/wallet-sdk-core/lib/cloud-wallet';
// Biometric data would come from platform-specific biometric APIs
const biometricData = await getPlatformBiometricData();
const userEmail = '[email protected]';
// Enroll user and get master key + recovery mnemonic
const { masterKey, mnemonic } = await enrollUserWithBiometrics(
EDV_URL,
EDV_AUTH_KEY,
biometricData,
userEmail
);
// IMPORTANT: Store the mnemonic securely for recovery purposes
The enrollment process:
Creates a unique master key and mnemonic
Generates encryption keys from the biometric data
Encrypts the master key with the biometric-derived keys
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:
import {
authenticateWithBiometrics,
initializeCloudWalletWithBiometrics
} from '@docknetwork/wallet-sdk-core/lib/cloud-wallet';
// Get current biometric data from platform APIs
const biometricData = await getPlatformBiometricData();
const userEmail = '[email protected]';
// Method 1: Get the master key directly
const masterKey = await authenticateWithBiometrics(
EDV_URL,
EDV_AUTH_KEY,
biometricData,
userEmail
);
// Method 2: Initialize cloud wallet in one step
const cloudWallet = await initializeCloudWalletWithBiometrics(
EDV_URL,
EDV_AUTH_KEY,
biometricData,
userEmail,
dataStore
);
The authentication process:
Uses biometric data and email to access the KeyMappingVault
Finds the encrypted master key associated with the user's email
Derives decryption keys from the provided biometric data
Decrypts the master key
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.
Last updated
Was this helpful?