Skip to main content
Version: 5.0

Vault

Represents a vault for secure value storage

Constructors

constructor

Usage


_10
const vault = new Vault({
_10
key: 'com.company.myvaultapp',
_10
type: 'CustomPasscode',
_10
deviceSecurityType: DeviceSecurityType.None,
_10
lockAfterBackgrounded: 2000,
_10
});

Parameters

NameType
config?IdentityVaultConfig

Returns: Vault

Properties

config

Contains the current config properties of the vault. See the IdentityVaultConfig docs page for more info.

Usage


_10
const newVault = new Vault(vaultConfig);
_10
if(newVault.config.deviceSecurityType === DeviceSecurityType.None) {
_10
...
_10
}

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


_10
const vault = new Vault(existingVaultConfig);
_10
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:

Usage


_10
const vault = new Vault(existingVaultConfig);
_10
const vaultExists = await vault.doesVaultExists()
_10
if (!vaultExists) {
_10
// the vault does not exist...
_10
}

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


_10
const vault = new Vault(existingVaultConfig);
_10
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


_10
const vault = new Vault(existingVaultConfig);
_10
const allKeys = await vault.getKeys();
_10
allKeys.forEach((key) => {
_10
// do something with the key
_10
});

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


_10
const vault = new Vault(existingVaultConfig);
_10
const userFirstName = await vault.getValue<string>("firstname");

Parameters

NameTypeDescription
keystringThe 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


_10
const dataFromElsewhere = await getUserData();
_10
const newVault = new Vault(vaultConfig);
_10
await newVault.importVault(dataFromElsewhere);

Parameters

NameTypeDescription
dataobjectThe entire data object to be imported. The shape of data must be {[key: string]: string}.

Returns: Promise<void>

initialize

Usage


_10
await initialize({
_10
key: 'com.company.myvaultapp',
_10
type: 'CustomPasscode',
_10
deviceSecurityType: DeviceSecurityType.None,
_10
lockAfterBackgrounded: 2000,
_10
});

Parameters

NameTypeDescription
configIdentityVaultConfigThe default configuration that is used when initializing a new vault. If a vault already exists identified by the specified key, then the configuration stored with that vault shall be read and used instead.

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


_10
const vault = new Vault(existingVaultConfig);
_10
const vaultIsEmpty = await vault.isEmpty()
_10
if (vaultIsEmpty) {
_10
// the vault is empty and contains no data...
_10
}

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


_10
const vault = new Vault(existingVaultConfig);
_10
const locked = await vault.isLocked();
_10
if (locked) {
_10
// vault is locked (or does not exist);
_10
}

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


_10
const vault = new Vault(existingVaultConfig);
_10
await vault.lock();

Returns: Promise<void>

onConfigChanged

Triggers when a config change occurs.

Usage


_10
vault.onConfigChanged((config) => {
_10
console.log("updated config: ", config);
_10
});

Parameters

NameTypeDescription
callback(config: IdentityVaultConfig) => voidThe 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


_10
vault.onError((err) => {
_10
console.log('ERROR from callback', JSON.stringify(err));
_10
});

Parameters

NameTypeDescription
callback(err: VaultError) => voidThe 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


_10
vault.onLock((lockEvent) => { displayNotification(`Vault locked. Was from timeout: ${lockEvent.timeout}`); })

Parameters

NameTypeDescription
callback(lockEvent: VaultLockEvent) => voidThe 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


_10
vault.onPasscodeRequested((isPasscodeSetRequest, onComplete) => {
_10
const message = isPasscodeSetRequest
_10
? 'Setup Passcode' // passcode is being set for first time
_10
: 'Enter passcode'; // passcode is being asked for unlock
_10
const passcode = window.prompt(message) || '';
_10
onComplete(passcode);
_10
});

Parameters

NameTypeDescription
callback(isPasscodeSetRequest: boolean, onComplete: (code: string) => void) => voidThe 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


_10
vault.onPasscodeRequested(async (isPasscodeSetRequest) => {
_10
const message = isPasscodeSetRequest
_10
? 'Setup Passcode' // passcode is being set for first time
_10
: 'Enter passcode'; // passcode is being asked for unlock
_10
// async yourGetPasscodeFromUser() returns a string of the users entry or null if canceled.
_10
const passcode = await yourGetPasscodeFromUser(message);
_10
await vault.setCustomPasscode(passcode ?? '');
_10
});

Parameters

NameTypeDescription
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


_10
vault.onUnlock(() => {
_10
console.log("vault is now unlocked");
_10
});

Parameters

NameTypeDescription
callback() => voidThe 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


_10
const vault = new Vault(existingVaultConfig);
_10
await vault.removeValue("address");

Parameters

NameTypeDescription
keystringThe 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


_10
const vault = new Vault(existingVaultConfig);
_10
const code = window.prompt("Enter your passcode.");
_10
if (code) {
_10
await vault.setCustomPasscode(code);
_10
}

Parameters

NameTypeDescription
passcodestringThe 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


_10
const vault = new Vault(existingVaultConfig);
_10
await vault.setValue<string>("theme", theme);

Parameters

NameTypeDescription
keystringThe key for the new value.
valueTThe 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


_10
const vault = new Vault(existingVaultConfig);
_10
await vault.unlock();

Returns: Promise<void>

updateConfig

Updates the configuration of the current vault.

Usage


_10
async function changeVaultType(type: VaultType) {
_10
const vault = new Vault(this.existingVaultConfig);
_10
const newConfig = { ...this.existingVaultConfig, type };
_10
await vault.updateConfig(newConfig);
_10
this.existingVaultConfig = newConfig;
_10
}

Parameters

NameTypeDescription
configIdentityVaultConfigThe new config

Returns: Promise<void>