Class: Vault

Represents a vault for secure value storage

Implements

• VaultInterface

Constructors

constructor

• new Vault(config?): Vault

Parameters

Name	Type
config?	IdentityVaultConfig

Returns

Vault

Usage

_10

const vault = new Vault();

_10

_10

Call initialize after create a vault instead of passing in the configuration in the constructor.

Properties

config

• config: undefined | IdentityVaultConfig

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

Usage

_10

const newVault = new Vault();

_10

await newVault.initialize(vaultConfig);

_10

if(newVault.config.deviceSecurityType === DeviceSecurityType.None) {

_10

...

_10

}

Implementation of

VaultInterface.config

Methods

clear

▸ clear(): Promise<void>

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.

Returns

Promise<void>

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

await vault.clear();

Implementation of

VaultInterface.clear

---

doesVaultExist

▸ doesVaultExist(): Promise<boolean>

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()

Returns

Promise<boolean>

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

const vaultExists = await vault.doesVaultExists()

_10

if (!vaultExists) {

_10

// the vault does not exist...

_10

}

Deprecated

Deprecated in favor of using the isEmpty() method.

Implementation of

VaultInterface.doesVaultExist

---

exportVault

▸ exportVault(): Promise<{ [key: string]: string; }>

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.

Returns

Promise<{ [key: string]: string; }>

The resolved object is a map with string keys and string values.

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

const data = await vault.exportVault();

Implementation of

VaultInterface.exportVault

---

getKeys

▸ getKeys(): Promise<string[]>

Returns an array of keys that are currently in the vault. Calling getKeys will attempt to unlock the vault if it is currently locked.

Returns

Promise<string[]>

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

const allKeys = await vault.getKeys();

_10

allKeys.forEach((key) => {

_10

// do something with the key

_10

});

Implementation of

VaultInterface.getKeys

---

getValue

▸ getValue<T>(key): Promise<null | T>

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.

Type parameters

Name	Type
T	any

Parameters

Name	Type	Description
key	string	The key to look up the value for

Returns

Promise<null | T>

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

const userFirstName = await vault.getValue<string>("firstname");

Implementation of

VaultInterface.getValue

---

importVault

▸ importVault(data): Promise<void>

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.

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>

Usage

_10

const dataFromElsewhere = await getUserData();

_10

const newVault = new Vault();

_10

await newVault.initialize(vaultConfig);

_10

await newVault.importVault(dataFromElsewhere);

Implementation of

VaultInterface.importVault

---

initialize

▸ initialize(config): Promise<void>

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>

Usage

_10

await vault.initialize({

_10

key: 'com.company.myvaultapp',

_10

type: 'CustomPasscode',

_10

deviceSecurityType: DeviceSecurityType.None,

_10

lockAfterBackgrounded: 2000,

_10

});

---

isEmpty

▸ isEmpty(): Promise<boolean>

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.

Returns

Promise<boolean>

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

const vaultIsEmpty = await vault.isEmpty()

_10

if (vaultIsEmpty) {

_10

// the vault is empty and contains no data...

_10

}

Implementation of

VaultInterface.isEmpty

---

isLocked

▸ isLocked(): Promise<boolean>

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.

Returns

Promise<boolean>

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

const locked = await vault.isLocked();

_10

if (locked) {

_10

// vault is locked (or does not exist);

_10

}

Implementation of

VaultInterface.isLocked

---

lock

▸ lock(): Promise<void>

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.

Returns

Promise<void>

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

await vault.lock();

Implementation of

VaultInterface.lock

---

onConfigChanged

▸ onConfigChanged(callback): void

Triggers when a config change occurs.

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

Usage

_10

vault.onConfigChanged((config) => {

_10

console.log("updated config: ", config);

_10

});

Implementation of

VaultInterface.onConfigChanged

---

onError

▸ onError(callback): void

Triggers when an error occurs in the application. Errors that come back as rejected promises also trigger this event.

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

Usage

_10

vault.onError((err) => {

_10

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

_10

});

Implementation of

VaultInterface.onError

---

onLock

▸ onLock(callback): void

Triggers when the vault enters a locked state.

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

Usage

_10

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

Implementation of

VaultInterface.onLock

---

onPasscodeRequested

▸ onPasscodeRequested(callback): 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 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.

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

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

});

Implementation of

VaultInterface.onPasscodeRequested

▸ onPasscodeRequested(callback): 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.

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

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

});

Implementation of

VaultInterface.onPasscodeRequested

---

onUnlock

▸ onUnlock(callback): void

Triggers when the vault enters an unlocked state.

Parameters

Name	Type	Description
callback	() => void	The callback function that will be called when the event triggers.

Returns

void

Usage

_10

vault.onUnlock(() => {

_10

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

_10

});

Implementation of

VaultInterface.onUnlock

---

removeValue

▸ removeValue(key): Promise<void>

Removes a value from the vault. Calling removeValue will attempt to unlock the vault if it is currently locked.

Parameters

Name	Type	Description
key	string	The key to remove

Returns

Promise<void>

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

await vault.removeValue("address");

Implementation of

VaultInterface.removeValue

---

setCustomPasscode

▸ setCustomPasscode(passcode): Promise<void>

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.

Parameters

Name	Type	Description
passcode	string	The user supplied passcode to secure the vault with.

Returns

Promise<void>

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

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

_10

if (code) {

_10

await vault.setCustomPasscode(code);

_10

}

Implementation of

VaultInterface.setCustomPasscode

---

setValue

▸ setValue<T>(key, value): Promise<void>

Sets the value of an item in the vault. Calling setValue will attempt to unlock the vault if it is currently locked.

Type parameters

Name	Type
T	any

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>

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

await vault.setValue<string>("theme", theme);

Implementation of

VaultInterface.setValue

---

unlock

▸ unlock(): Promise<void>

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.

Returns

Promise<void>

Usage

_10

const vault = new Vault();

_10

await vault.initialize(existingVaultConfig);

_10

await vault.unlock();

Implementation of

VaultInterface.unlock

---

updateConfig

▸ updateConfig(config): Promise<void>

Updates the configuration of the current vault.

Parameters

Name	Type	Description
config	IdentityVaultConfig	The new config

Returns

Promise<void>

Usage

_10

async function changeVaultType(type: VaultType) {

_10

const vault = new Vault();

_10

await vault.initialize(this.existingVaultConfig);

_10

const newConfig = { ...this.existingVaultConfig, type };

_10

await vault.updateConfig(newConfig);

_10

this.existingVaultConfig = newConfig;

_10

}

Implementation of

VaultInterface.updateConfig