Vault

The Vault Aptitude provides the ability to read and write strings in either macOS' Keychain or Window's Credential Manager, depending on the system.

The vault Aptitude is not intended for storing large amounts of data.

API

remove

Removes the entry from the vault with the specified key.

import { vault } from '@oliveai/ldk';

const key = 'myKey';

vault.remove(key).then(() => {
    console.log(`Removed ${key} from the vault`);
});

exists

Returns true if an entry with the specified key is in the vault.

import { vault } from '@oliveai/ldk';

const key = 'myKey';

vault.exists(key).then((inVault) => {
    console.log(`${key} ${!inVault ? 'does not exist' : 'exists'} in the vault.`);
});

read

Returns the value stored in the vault with the specified key.

import { vault } from '@oliveai/ldk';

const key = 'myKey';

vault.read(key).then((value) => {
    console.log(`${key} maps to ${value}`);
});

write

Adds the given value to the vault with the specified key.

import { vault } from '@oliveai/ldk';

const key = 'myKey';
const value = 'some value to write';

vault.write(key, value).then(() => {
    console.log(`Wrote ${value} to ${key}`);
});

Example

Let's suppose we have a Loop that needs to access network resources that are locked behind a security token. We'll create a Loop that retrieves and stores this token to be used elsewhere within the Loop.

import { network, user, vault } from '@oliveai/ldk';

const tokenKey = 'myloop_token';
const expirationKey = 'myloop_expiration';
const oneDayMs = 24 * 60 * 60 * 1000;

const tokenUrl = 'http://127.0.0.1:8080/token';
const apiUrl = 'http://127.0.0.1:8080/myTestApi';

async function refreshToken() {
    // We'll use the jwt provided by the user aptitude to act as our authorization
    // to hit the token endpoint
    const jwt = await user.jwt();
    const response = await network.httpRequest({
        url: tokenUrl,
        method: 'GET',
        headers: {
            Authorization: `Bearer ${jwt}`,
        },
    });

    if (response.statusCode != 200) {
        return;
    }

    const token = await network.decode(response.body);
    const expirationTime = Date.now() + oneDayMs;
  
    // Once we've retrieved the new token, we can store it securely in the vault
    await vault.write(tokenKey, token);
    await vault.write(expirationKey, expirationTime);
}

// This will be the main entrypoint into our example
async function main() {
    let exists = await vault.exists(expirationKey);
  
    if (exists) {
        // If the key exists in vault, we need to make sure it hasn't expired
        let expirationTimeStr = await vault.read(expirationKey);
        let expirationTime = parseInt(expirationTimeStr);
        if (expirationTime < Date.now()) {
            await refreshToken();
        }
    } else {
        await refreshToken();
    }

    // Check to make sure the user token exists before retrieving it
    // Something could have gone wrong with refreshToken();
    const userTokenExists = await vault.exists(tokenKey);
    if (!userTokenExists) {
        return;
    }

    // Read the key and make an API request to get our data
    const userToken = await vault.read(tokenKey);
    const someData = await network.httpRequest({
        url: apiUrl,
        method: 'GET',
        headers: {
            Authorization: `Bearer ${userToken}`,
        },
    });

    // Do something with someData
}

main();

Permissions

To use the Vault Aptitude, simply set the following permissions in your package.json under the ldk object.

Please see our Permissions page for more information.

...
"ldk": {
  "permissions": {
    "vault": {},
    ...
  }
},
...