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.
  • setValue()
  • removeValue()
  • importVault()
  • exportVault()
  • unlock()
  • updateConfig()

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>