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

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

_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:

• 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

_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

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

_10

const dataFromElsewhere = await getUserData();

_10

const newVault = new Vault(vaultConfig);

_10

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>

initialize

Usage

_10

await initialize({

_10

key: 'com.company.myvaultapp',

_10

type: 'CustomPasscode',

_10

deviceSecurityType: DeviceSecurityType.None,

_10

lockAfterBackgrounded: 2000,

_10

});

Parameters

Name	Type	Description
config	IdentityVaultConfig	The 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

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

_10

vault.onError((err) => {

_10

console.log('ERROR from callback', JSON.stringify(err));

_10

});

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

_10

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

_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

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

_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

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

_10

vault.onUnlock(() => {

_10

console.log("vault is now unlocked");

_10

});

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

_10

const vault = new Vault(existingVaultConfig);

_10

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

_10

const vault = new Vault(existingVaultConfig);

_10

const code = window.prompt("Enter your passcode.");

_10

if (code) {

_10

await vault.setCustomPasscode(code);

_10

}

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

_10

const vault = new Vault(existingVaultConfig);

_10

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

_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

Name	Type	Description
config	IdentityVaultConfig	The new config

Returns: Promise<void>