Skip to main content
Version: 5.0

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#

NameType
configIdentityVaultConfig

Returns: Vault

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.

Usage#

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

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#

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#

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

Parameters#

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

Returns: Promise<void>

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.

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.

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#

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#

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

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#

vault.onLock(() => { displayNotification("Vault locked."); })

Parameters#

NameTypeDescription
callback() => voidThe callback function that will be called when the event triggers.

Returns: void

onPasscodeRequested#

For CustomPasscode vaults, this event triggers when the vault is attempting to unlock and the passcode has not been set yet. The callback function will pass in a Promise that, when resolved, with attempt to unlock the vault again calling the same method that originally tried to unlock the vault. Before the promise 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 const passcode = window.prompt(message) || '';  vault.setCustomPasscode(passcode);  return Promise.resolve();});

Parameters#

NameTypeDescription
callback(isPasscodeSetRequest: boolean) => Promise<void>The callback function that will be called when the event triggers. The 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#

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#

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

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#

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

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#

NameTypeDescription
configIdentityVaultConfigThe new config

Returns: Promise<void>