toc

Node.js SDK

A full reference of our Node.js SDK.

You can use our Node.js SDK to:

  1. Encrypt data at your server
  2. Run your Cages
  3. Encrypt/decrypt data with Relay

Our Node.js SDK encrypts all data fields by default unless you specify what to encrypt.

You can use our Node.js SDK to encrypt data — rather than with Relay — and still send it to a third-party via Relay. Encrypting with our backend SDKs is best for developers who want to avoid the network latency of Relay and/or want to avoid sending plaintext data to Relay to be encrypted.

Encrypting data with our backend SDKs instead of Relay may expose you to greater compliance burden because plaintext data touches your server before it is encrypted. If you want to avoid sending plaintext data to Relay and want to reduce your compliance burden — by never having plaintext data touch your infrastructure — using our frontend SDKs to encrypt in the browser or on the client is best.

You don’t need to change your database configuration. You can store Evervault-encrypted data in your database as you would the plaintext version.

Installation

Our Node.js SDK is distributed via npm, and can be installed using your preferred package manager.

bash
# Install using npm
npm install @evervault/sdk
# Install using Yarn
yarn add @evervault/sdk

Initialization

The Evervault Node.js SDK will automatically pass all outbound network requests through Relay by overriding your default HTTP Agent. To disable this behaviour, set the relay value to false in the options.

javascript
const Evervault = require('@evervault/sdk');
// Initialize the client with your team’s API key
const evervault = new Evervault('<YOUR_API_KEY>', {
relay: true
});
// Encrypt your data
const encrypted = await evervault.encrypt({ name: 'Alice' });
// Process the encrypted data in a Cage
const result = await evervault.run('demo-cage', encrypted);

Reference

The Evervault Node.js SDK exposes three functions:

  • evervault.encrypt()
  • evervault.run()

evervault.encrypt()

evervault.encrypt() encrypts data for use in your Cages and through Relay. To encrypt data at the server, simply pass an object or string into the evervault.encrypt() function. Store the encrypted data in your database as normal.

javascript
async evervault.encrypt(data: Object | String);
ParameterTypeDescription
dataObject or StringData to be encrypted.

evervault.run()

evervault.run() lets you invoke a Cage with a given payload.

javascript
async evervault.run(cageName: String, data: Object[, options: Object]);
ParameterTypeDescription
cageNameStringName of the Cage to be run.
dataObjectPayload for the Cage.
optionsObjectOptions for the cage run.
OptionTypeDefaultDescription
asyncBooleanfalseRun your Cage in async mode. Async Cage runs will be queued for processing.
versionNumberundefinedSpecify the version of your Cage to run. By default, the latest version will be run.