Vault
Represents a vault for secure value storage
Constructors
constructor
Usage
const vault = new Vault({
key: 'com.company.myvaultapp',
type: 'CustomPasscode',
deviceSecurityType: DeviceSecurityType.None,
lockAfterBackgrounded: 2000,
});
Parameters
Name | Type |
---|---|
config | IdentityVaultConfig |
Returns: Vault
Properties
config
Contains the current config properties of the vault. See the IdentityVaultConfig docs page for more info.
Usage
const newVault = new Vault(vaultConfig);
if(newVault.config.deviceSecurityType === DeviceSecurityType.None) {
...
}
Methods
clear
Clears out the current vault and removes it from the system. Note: The vault does not need to be unlocked in order to clear it. No credentials are checked when clearing the vault.
Usage
const vault = new Vault(existingVaultConfig);
await vault.clear();
Returns: Promise<void>
doesVaultExist
Resolves true if a vault with the same key already exists, and false if not. The vault does not need to be unlocked to check.
Note:
- Using removeValue() to remove all of your vault data will not cause this function to resolve false, however clear() will.
- A vault only exists once it has been interacted with at least once via any of the following instance methods.
Usage
const vault = new Vault(existingVaultConfig);
const vaultExists = await vault.doesVaultExists()
if (!vaultExists) {
// the vault does not exist...
}
Deprecated in favor of using the isEmpty() method.
Returns: Promise<boolean>
exportVault
Exports the data of the current vault in its entirety.
The data is a map with keys that are strings and values that are JSON.
Calling exportVault
will attempt to unlock the vault if it is currently locked.
Usage
const vault = new Vault(existingVaultConfig);
const data = await vault.exportVault();
Returns: Promise<{ [key: string]: string; }>
The resolved object is a map with string keys and string values.
getKeys
Returns an array of keys that are currently in the vault.
Calling getKeys
will attempt to unlock the vault if it is currently locked.
Usage
const vault = new Vault(existingVaultConfig);
const allKeys = await vault.getKeys();
allKeys.forEach((key) => {
// do something with the key
});
Returns: Promise<string[]>
getValue
Gets the value for a given key. Returns null if the key does not exist.
Calling getValue
will attempt to unlock the vault if it is currently locked.
Usage
const vault = new Vault(existingVaultConfig);
const userFirstName = await vault.getValue<string>("firstname");
Parameters
Name | Type | Description |
---|---|---|
key | string | The key to look up the value for |
Returns: Promise<null | T>
importVault
Imports data into the vault, replacing the current contents of the vault.
The data is a map with keys that are strings and values that are JSON.
Calling importVault
will attempt to unlock the vault if it is currently locked.
Usage
const dataFromElsewhere = await getUserData();
const newVault = new Vault(vaultConfig);
await newVault.importVault(dataFromElsewhere);
Parameters
Name | Type | Description |
---|---|---|
data | object | The entire data object to be imported. The shape of data must be {[key: string]: string}. |
Returns: Promise<void>
isEmpty
Resolves true if a vault contains no data, and false if any data exists in the vault. The vault does not need to be unlocked to check.
Note: Vaults created prior to version 5.2.0 will return false until the vault is unlocked for the first time after updating, even if the vault contains no data. After which this method will return the expected value.
Usage
const vault = new Vault(existingVaultConfig);
const vaultIsEmpty = await vault.isEmpty()
if (vaultIsEmpty) {
// the vault is empty and contains no data...
}
Returns: Promise<boolean>
isLocked
Checks if the vault is currently in a locked state, which signifies that the contents
of the secure vault are not currently accessible. isLocked
can also return true if the
vault does not exist.
If a vault has a VaultType
of SecureStorage
or InMemory
this method will return false
as these vault types cannot be locked.
Usage
const vault = new Vault(existingVaultConfig);
const locked = await vault.isLocked();
if (locked) {
// vault is locked (or does not exist);
}
Returns: Promise<boolean>
lock
Locks the vault if it is currently unlocked. Locking the vault with remove all secure data from memory inside of Identity Vault, but not your application.
For Vaults of type SecureStorage
or InMemory
this method will have no effect on the vault.
Usage
const vault = new Vault(existingVaultConfig);
await vault.lock();
Returns: Promise<void>
onConfigChanged
Triggers when a config change occurs.
Usage
vault.onConfigChanged((config) => {
console.log("updated config: ", config);
});
Parameters
Name | Type | Description |
---|---|---|
callback | (config : IdentityVaultConfig) => void | The callback function that will be called when the event triggers. Passes in the current vault config. |
Returns: void
onError
Triggers when an error occurs in the application. Errors that come back as rejected promises also trigger this event.
Usage
vault.onError((err) => {
console.log('ERROR from callback', JSON.stringify(err));
});
Parameters
Name | Type | Description |
---|---|---|
callback | (err : VaultError) => void | The callback function that will be called when the event triggers. Passes in the error object. |
Returns: void
onLock
Triggers when the vault enters a locked state.
Usage
vault.onLock((lockEvent) => { displayNotification(`Vault locked. Was from timeout: ${lockEvent.timeout}`); })
Parameters
Name | Type | Description |
---|---|---|
callback | (lockEvent : VaultLockEvent) => void | The callback function that will be called when the event triggers. Passes in an object with a boolean property of timeout indicating if the lock was due to a background timeout or not. |
Returns: void
onPasscodeRequested
For CustomPasscode vaults, this event triggers when the vault is attempting to unlock and needs the user to provide a passcode.
The callback parameter is a function that has two parameters available to it:
isPasscodeSetRequest
is a boolean value indicating whether the passcode needs to be setup for the first time or not.onComplete
is a function that accepts a string parameter 'code', that when called will set the passcode on the vault and attempt to unlock the vault again calling the same method that originally tried to unlock the vault.
Usage
vault.onPasscodeRequested((isPasscodeSetRequest, onComplete) => {
const message = isPasscodeSetRequest
? 'Setup Passcode' // passcode is being set for first time
: 'Enter passcode'; // passcode is being asked for unlock
const passcode = window.prompt(message) || '';
onComplete(passcode);
});
Parameters
Name | Type | Description |
---|---|---|
callback | (isPasscodeSetRequest : boolean, onComplete : (code : string) => void) => void | The callback function that will be called when the event triggers. Contains a boolean that indicates if the passcode is being setup for the first time for the vault or not, and an onComplete function to be called when a passcode is ready to be set on the vault. |
Returns: void
For CustomPasscode vaults, this event triggers when the vault is attempting to unlock and needs the user to provide a passcode.
The callback parameter is a async function that has one parameter available to it:
isPasscodeSetRequest
is a boolean value indicating whether the passcode needs to be setup for the first time or not.
When the callback function is resolved, an attempt to unlock the vault again calling the same method that originally tried to unlock the vault will be made.
Before the function is resolved, you should prompt the user to supply a passcode, and then supply that value to setCustomPasscode
.
Usage
vault.onPasscodeRequested(async (isPasscodeSetRequest) => {
const message = isPasscodeSetRequest
? 'Setup Passcode' // passcode is being set for first time
: 'Enter passcode'; // passcode is being asked for unlock
// async yourGetPasscodeFromUser() returns a string of the users entry or null if canceled.
const passcode = await yourGetPasscodeFromUser(message);
await vault.setCustomPasscode(passcode ?? '');
});
Parameters
Name | Type | Description |
---|---|---|
callback | (isPasscodeSetRequest : boolean) => Promise<void> | The callback function that will be called when the event triggers. This async function returns a promise with a boolean that indicates if the passcode is being setup for the first time for the vault or not. |
Returns: void
onUnlock
Triggers when the vault enters an unlocked state.
Usage
vault.onUnlock(() => {
console.log("vault is now unlocked");
});
Parameters
Name | Type | Description |
---|---|---|
callback | () => void | The callback function that will be called when the event triggers. |
Returns: void
removeValue
Removes a value from the vault.
Calling removeValue
will attempt to unlock the vault if it is currently locked.
Usage
const vault = new Vault(existingVaultConfig);
await vault.removeValue("address");
Parameters
Name | Type | Description |
---|---|---|
key | string | The key to remove |
Returns: Promise<void>
setCustomPasscode
When the vault type is set to 'CustomPasscode', this method sets the passcode required to secure the vault. If the vault is unlocked this method can be used to change the passcode.
This method is typically called in the onPasscodeRequested
callback.
Usage
const vault = new Vault(existingVaultConfig);
const code = window.prompt("Enter your passcode.");
if (code) {
await vault.setCustomPasscode(code);
}
Parameters
Name | Type | Description |
---|---|---|
passcode | string | The user supplied passcode to secure the vault with. |
Returns: Promise<void>
setValue
Sets the value of an item in the vault.
Calling setValue
will attempt to unlock the vault if it is currently locked.
Usage
const vault = new Vault(existingVaultConfig);
await vault.setValue<string>("theme", theme);
Parameters
Name | Type | Description |
---|---|---|
key | string | The key for the new value. |
value | T | The value to store in the vault. Value can be of any type, as it will be parsed to JSON in the vault. |
Returns: Promise<void>
unlock
Manually unlock the vault. Will trigger any authentication mechanism needed to access the vault (passcode, biometrics, etc..).
For Vaults of type SecureStorage
or InMemory
this method will have no effect on the vault.
Usage
const vault = new Vault(existingVaultConfig);
await vault.unlock();
Returns: Promise<void>
updateConfig
Updates the configuration of the current vault.
Usage
async function changeVaultType(type: VaultType) {
const vault = new Vault(this.existingVaultConfig);
const newConfig = { ...this.existingVaultConfig, type };
await vault.updateConfig(newConfig);
this.existingVaultConfig = newConfig;
}
Parameters
Name | Type | Description |
---|---|---|
config | IdentityVaultConfig | The new config |
Returns: Promise<void>