This is a TypeScript client to connect to a Piiano Vault. It provides an easy-to-use API for accessing the various resources exposed by the Vault REST API.
Note:
This package is compatible with Vault version 1.12.4. For a Vault client compatible with other versions of Vault, check other versions of this package.
To install the package using npm
:
npm install @piiano/vault-client
To install the package using yarn
:
yarn add @piiano/vault-client
To use the VaultClient
class, first import it into your project:
const { VaultClient } = require('@piiano/vault-client');
Or if you are using TypeScript:
import { VaultClient } from '@piiano/vault-client';
Then create a new instance of the client:
const client = new VaultClient({
vaultURL: 'https://vault.example.com:8123',
apiKey: 'vaultApiKey',
});
ℹ️ Note that the VaultClient
options have default values for the vaultURL
and apiKey
properties.
These match the defaults of a local Vault installation in development mode.
const defaultOptions = {
vaultURL: "http://localhost:8123",
apiKey: "pvaultauth",
}
To get the version of the running Vault:
const version = await this.vaultClient.system.getVaultVersion();
console.log(version);
Expected output:
{
vault_id: '165147695309533184',
vault_version: '1.2.2.4420853466-g3a086a1',
db_schema_version: 20230314205727
}
To build and test the project:
yarn
yarn build
yarn test
The VaultClient
class includes members for the following specific API categories:
const vaultClient = new VaultClient();
vaultClient.collections // client for working with collections
vaultClient.collectionProperties // client for working with collection properties
vaultClient.objects // client for working with objects
vaultClient.crypto // client for working with crypto operations
vaultClient.tokens // client for working with tokens
vaultClient.system // client for working with system operations
vaultClient.iam // client for working with IAM
vaultClient.configVars // client for working with config vars
vaultClient.dataTypes // client for working with data types
vaultClient.bundles // client for working with bundles
These correspond to the various resources exposed by the Piiano Vault REST API. Each member provides methods for interacting with the corresponding resource.
This Piiano Vault resource enables you to create, retrieve, update, and delete the collections that hold sensitive data.
VaultClient.collections.listCollections()
VaultClient.collections.addCollection()
VaultClient.collections.getCollection()
VaultClient.collections.updateCollection()
VaultClient.collections.deleteCollection()
description: This Piiano Vault resource enables you to create, retrieve, list, update, and delete the collection properties that define the stored data values.
VaultClient.collectionProperties.listCollectionProperties()
VaultClient.collectionProperties.addCollectionProperty()
VaultClient.collectionProperties.getCollectionProperty()
VaultClient.collectionProperties.updateCollectionProperty()
VaultClient.collectionProperties.deleteCollectionProperty()
This beta Piiano Vault resource enables you to create, retrieve, list, update, and delete bundles that export functions used by custom data types.
VaultClient.bundles.listBundles()
VaultClient.bundles.addBundle()
VaultClient.bundles.getBundle()
VaultClient.bundles.updateBundle()
VaultClient.bundles.deleteBundle()
This beta Piiano Vault resource enables you to create, retrieve, list, and delete data types that can be used as property types.
VaultClient.dataTypes.listDataTypes()
VaultClient.dataTypes.addDataType()
VaultClient.dataTypes.getDataType()
VaultClient.dataTypes.deleteDataType()
This Piiano Vault resource enables you to create, retrieve, search, update, and delete collection objects and their data.
VaultClient.objects.listObjects()
VaultClient.objects.addObject()
VaultClient.objects.getObjectById()
VaultClient.objects.updateObjectById()
VaultClient.objects.deleteObjectById()
VaultClient.objects.addObjects()
VaultClient.objects.updateObjects()
VaultClient.objects.deleteObjects()
VaultClient.objects.searchObjects()
This beta Piiano Vault resource enables you to encrypt, decrypt, and update encrypted blobs.
VaultClient.crypto.encrypt()
VaultClient.crypto.updateEncrypted()
VaultClient.crypto.decrypt()
VaultClient.crypto.hashObjects()
This Piiano Vault resource enables you to tokenize, detokenize, update, rotate, search, and delete tokens.
VaultClient.tokens.tokenize()
VaultClient.tokens.detokenize()
VaultClient.tokens.deleteTokens()
VaultClient.tokens.updateTokens()
VaultClient.tokens.rotateTokens()
VaultClient.tokens.searchTokens()
This Piiano Vault resource enables you to set and retrieve the IAM configuration and regenerate user API keys.
VaultClient.iam.getIamConf()
VaultClient.iam.setIamConf()
VaultClient.iam.regenerateUserApiKey()
This Piiano Vault resource enables you to set and retrieve the dynamic configuration variables that control the behavior of your Vault.
VaultClient.configVars.clearAllConfVars()
VaultClient.configVars.getConfVar()
VaultClient.configVars.setConfVar()
This Piiano Vault resource enables you to retrieve details about the status of system components and the Vault version.
VaultClient.system.dataHealth()
VaultClient.system.controlHealth()
VaultClient.system.getClusterInfo()
VaultClient.system.garbageCollection()
VaultClient.system.triggerError()
VaultClient.system.getConfiguration()
VaultClient.system.getLicense()
VaultClient.system.getVaultVersion()
VaultClient.system.rotateKeys()
VaultClient.system.getKms()
You can add additional headers for any request by passing the additionalHeaders
option in the request object of any method.
This can be useful for adding custom headers like X-Pvault-Request-ID
for tracing requests or the X-Pvault-Delegation
header.
For example:
vaultClient.objects.addObject({
collection: 'customers',
reason: 'AppFunctionality',
requestBody: {
name: 'John Doe',
email: 'johndoe@example.com',
},
additionalHeaders: {
'X-Pvault-Request-ID': '1234567890', // Will be added to the request headers
},
});
This package is licensed under the MIT License. See the LICENSE file for more information.