Reference

Node.js SDK

You can use our Node.js SDK to:

  • Encrypt data server-side
  • Invoke Functions
  • Decrypt data through Outbound Relay

Encrypting data with our backend SDKs instead of Inbound Relay may expose you to greater compliance burden because plaintext data touches your server before it is encrypted.

Instead you can:


Quickstart

Install SDK

First, let's install the Evervault SDK using your package manager of choice.

lovelace:~$
# Using npm
npm install @evervault/sdk
# Using yarn
yarn add @evervault/sdk

Initialize SDK

Now, let's initialize the SDK using our App's API key. If you don't have one yet, you can get one by creating an App in the Evervault Dashboard.

1
const Evervault = require('@evervault/sdk');
2
3
const evervault = new Evervault('<API_KEY>');

Encrypt a string

Now that the SDK is initialized, we can encrypt a string.

1
const encrypted = await evervault.encrypt("Hello, world!");
2
3
// encrypted: ev_encrypted_string
4
// todo: annotate ev_encrypted_string

Full example

Pulling all of this together leaves us with the following working example. You can copy and paste the code below (using a sandbox API key), run it in your own environment and run the encryption and decryption for yourself.

1
const Evervault = require('@evervault/sdk');
2
const evervault = new Evervault('<API_KEY>');
3
4
const encrypted = await evervault.encrypt("Hello, world!");
5
6
// Send the decrypted data to a third-party API
7
await evervault.enableOutboundRelay()
8
const response = await axios.post('https://example.com', encrypted)
9
10
const decrypted = await evervault.decrypt(encrypted);
11
// decrypted: "Hello, world!"

Reference

new Evervault(apiKey)

The SDK constructor accepts two parameters:

  1. Your App's API key
  2. Optional configuration parameters
1
const Evervault = require('@evervault/sdk');
2
3
const evervault = new Evervault("<API_KEY>");
Parameters
apiKeyRequiredString

Your Evervault app API Key.


evervault.encrypt(data)

evervault.encrypt() encrypts data using Evervault Encryption. Evervault Strings can be used across all of our products.

To encrypt data using the Node.js SDK, simply pass a String or an Object into the evervault.encrypt() function.

The encrypted data can be stored in your database as normal and can be used with any of Evervault’s other services.

1
const Evervault = require('@evervault/sdk');
2
const evervault = new Evervault("<API_KEY>");
3
4
const encrypted = await evervault.encrypt("Hello, world!");
Parameters
dataRequiredString

The data you want to encrypt.


evervault.run(functionName, data, options)

evervault.run() lets you invoke an Evervault Function with a given payload

1
const Evervault = require('@evervault/sdk');
2
const evervault = new Evervault("<API_KEY>");
3
4
const result = await evervault.functions.run(
5
"hello-function",
6
{
7
"name": "Claude Shannon",
8
"ssn": "ev:encrypted_string"
9
},
10
{
11
async: false,
12
version: undefined
13
}
14
);
Parameters
functionNameRequiredString

The name of the function your want to run.

dataRequiredObject

The data you want to send to the function.

options

Additional options.

options.asyncBoolean. Default: false

Run your Function in async mode. Asynchronous Function runs will be queued for processing and return a 200 OK response saying your run has been queued.

options.versionNumber. Default: undefined

Specify the version of your Function to run. By default, the latest version will be run.

Response

Function runs will return a JSON object containing a Function Run ID and the result from your Function in the following format:

1
{
2
"result": {
3
"message": "Hello from a Function! It seems you have 14 letters in your name",
4
"name": "ev:RFVC:TTLHY04oVJlBuvPx:A7MeNriTKFES0Djl9uKaPvHCAn9PjSfOHu7tswXFCHF9:jwYKE13o3iQlr6Dn/DRk80XpNOGb:$"
5
},
6
"runId": "09413338da56",
7
"appUuid": "app_dfda72e016b1"
8
}

evervault.createRunToken(data, options)

evervault.createRunToken() creates a single use, time bound token (5 minutes) for invoking an Evervault Function with a given payload.

Run Tokens can be used to invoke an Evervault Function client-side without providing a sensitive API Key.

1
const Evervault = require('@evervault/sdk');
2
const evervault = new Evervault("<API_KEY>");
3
4
const runToken = await evervault.createRunToken(
5
"hello-function",
6
{
7
"name": "Claude Shannon",
8
"ssn": "ev:encrypted_string"
9
}
10
);
Parameters
functionNameRequiredString

The name of the function your want to run.

dataRequiredObject

The data you want to send to the function.

Response

When you create a Run Token, the SDK will return a JSON object containing your token.

1
{
2
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsInZlciI6IjAuMCJ9.eyJhcHBVdWlkIjoiYXBwX2RmZGE3MmUwMTZiMCIsImZ1bmN0aW9uTmFtZSI6ImhlbGxvLWNhZ2UtdGFsbC13YWxscy10cmF2ZWwiLCJydW5JZCI6IjRiMjhmMzNlLWU3NjYtNDI2OC1iNmY2LTUyYzZkM2VmMGQzYyIsImV4cCI6MTY2Nzg3Njc2Nn0.gCiFw7UJ8gjZfeXNEaqX4H1Y9HBX9avjioZ4yDU8PTtmGT4QTzVOhnDV46v_yyXLxpO1BgzoBRpYbLciiW1_QXSLmx6cCuJy4vHUZwssHT13vB7AXIl_88Ab5R7w9vpOQIDoCjhPVWJsolwUiiGh_5yE4wGv6WPTIfSv249_hpJLMz3AAffXUckiLPxFporY73KXtTANQH_zniivB91KdBnyGhle7gTs1EXWLqpdMIrqOz9cmoXU31DGd-AgeMzM082s_XtdCFq7FNLLtg6Nx8Mx8Bjl0cKV41R-jbTpHSXxutLX-PSDmWn5wSqDhlQoEWdTLsoS6xp7qhZ2urYyYg"
3
}

Run Tokens can then be used to authenticate Function runs from the client-side.

lovelace:~$
curl -X POST https://run.evervault.com/hello-function \
-H 'Authorization: Bearer eyJ..Tg' \
-H 'Content-Type: application/json' \
--data '{"name": "Claude Shannon", "ssn": "ev:encrypted_string"}'

The payload used to invoke your Function must be identical to the payload used to create the Run Token.


evervault.enableOutboundRelay(options)

Configures your application to proxy HTTP requests using Outbound Relay based on the configuration created in the Evervault dashboard. See Outbound Relay to learn more.

1
await evervault.enableOutboundRelay()
Parameters
options.decryptionDomainsString[]

Requests sent to any of the domains listed will be proxied through Outbound Relay. This will override the configuration created in the Evervault dashboard.

options.debugRequestsBoolean

Output request domains and whether they were sent through Outbound Relay.