DocsGuidesReference
Dashboard

Guides

Node.js SDK

You can use our Node.js SDK to:

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

Encrypting/Decrypting data with our backend SDKs instead of Inbound Relay may expose you to greater compliance burden because your server handles plaintext data.

Instead you can:

  • Use an Inbound Relay to encrypt data before it reaches your server.
  • Use an Outbound Relay to decrypt data before it reaches a third-party service.
  • Use our client-side SDKs to encrypt data before sending it to your server.

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 ID and our App's API key. If you don't have an API key yet, you can get one by creating an App in the Evervault Dashboard.

1
const Evervault = require('@evervault/sdk');
2
const evervault = new Evervault('<APP_ID>', '<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
console.log(encrypted);
3
// ev:Tk9D:4GgTSQGlroU4369e:A6UCVzVYTdonIw6IXwTLedr9e...

Configure Outbound Relay

Outbound Relay can be configured to proxy all traffic to a domain or specific requests. For all traffic to be proxied use the enableOutboundRelay function. evervault.enableOutboundRelay().

1
  // Send all requests with encrypted data to a third-party API
2
  await evervault.enableOutboundRelay()
3
  const response = await axios.post('https://example.com', encrypted)

To send an individual request via Outbound Relay, use evervault.createRelayHttpsAgent(). This will return a HTTPSProxyAgent that can be passed into supporting HTTP clients.

1
  // Send a singular request with encrypted data to a third-party API
2
  const httpsAgent = evervault.createRelayHttpsAgent();
3
  const payload = {"sensitiveField": "sensitive value"};
4
  const response = await axios.post('https://example.com', payload, {
5
    httpsAgent,
6
    headers: {
7
      'Content-Type': 'application/json'
8
    }
9
  });

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 and App ID), run it in your own environment and run the encryption for yourself.

1
const Evervault = require('@evervault/sdk');
2
const evervault = new Evervault('<APP_ID>', '<API_KEY>');
3
4
const encrypted = await evervault.encrypt("Hello, world!");
5
6
// Decrypt the encrypted data
7
const decrypted = await evervault.decrypt(encrypted);
8
9
// Send the encrypted data to a third-party API
10
await evervault.enableOutboundRelay()
11
const response = await axios.post('https://example.com', encrypted)
12
13
// Enable the Cages beta client
14
await evervaultClient.enableCagesBeta({ 'my-cage': { pcr8: '...' } });
15
16
// This connection will be attested by the Cages beta client
17
const response = await axios.post(
18
  'https://my-cage.my-app.cages.evervault.com',
19
  encrypted
20
);

Reference

new Evervault(appId, apiKey)

The SDK constructor accepts three parameters:

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

Your Evervault App's ID.

apiKeyRequiredString

Your Evervault App's API Key.

evervault.encrypt(data)

evervault.encrypt() encrypts data using Evervault Encryption.

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

The encrypted data can be stored in your database or file storage as normal. Evervault Strings can be used across all of our products. Evervault File Encryption is currently in Beta, and files can only be decrypted with Outbound Relay.

1
const Evervault = require('@evervault/sdk');
2
const evervault = new Evervault("<APP_ID>", "<API_KEY>");
3
4
// encrypt a string
5
const encrypted = await evervault.encrypt("Hello, world!");
6
7
// encrypt a file
8
const fileContents = fs.readFileSync('<input-file>');
9
const encryptedFile = await evervault.encrypt(fileContents);
10
fs.writeFileSync('<output-file>', encryptedFile);
Parameters
dataRequiredString | Object | Buffer

The data you want to encrypt.

evervault.decrypt(data)

evervault.decrypt() decrypts data previously encrypted with the encrypt() function or through Relay.

An API key with the decrypt permission must be used to perform this operation.

1
const Evervault = require('@evervault/sdk');
2
const evervault = new Evervault("<APP_ID>", "<API_KEY>");
3
4
const encrypted = await evervault.encrypt("Hello, world!");
5
const decrypted = await evervault.decrypt(encrypted);
6
console.log(decrypted)
7
// Hello, world!
Parameters
encryptedRequiredString | Object | Buffer

The data you want to decrypt.

Decrypting data with our backend SDKs is not available if you are part of the PCI or HIPAA compliance use cases

Instead you can:

evervault.createClientSideDecryptToken(payload, expiry)

Client Side Decrypt Tokens are versatile and short-lived tokens that frontend applications can utilise to decrypt data previously encrypted through Evervault. Client Side Decrypt Tokens are restricted to specific payloads.

By default, a Client Side Decrypt Token will live for 5 minutes into the future. The maximum time to live of the token is 10 minutes into the future.

1
const encryptedData = await evervault.encrypt("foo");
2
const now = new Date();
3
const timeInFiveMinutes = now.setMinutes(now.getMinutes() + 5);
4
5
const token = await evervault.createClientSideDecryptToken(encryptedData, timeInFiveMinutes);
Parameters
payloadRequiredString | Object | Buffer

The payload containing encrypted data that the token will be used to decrypt.

expiryDate

The time the token will expire. Defaults to 5 minutes in the future.

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("<APP_ID>", "<API_KEY>");
3
4
const result = await evervault.functions.run("hello-function", {
5
  "name": "Claude Shannon",
6
  "ssn": "ev:encrypted_string"
7
}, {
8
  async: false,
9
  version: undefined
10
});
Parameters
functionNameRequiredString

The name of the function your want to run.

dataRequiredObject

The data you want to send to the function.

options

Additional options.

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("<APP_ID>", "<API_KEY>");
3
4
const runToken = await evervault.createRunToken("hello-function", {
5
  "name": "Claude Shannon",
6
  "ssn": "ev:encrypted_string"
7
});
Parameters
functionNameRequiredString

The name of the function your want to run.

dataObject

The data you want to send to the function. If not provided, a run token will be created, and the payload will not be validated when the function is executed.

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"}'

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.

evervault.createRelayHttpsAgent()

The HTTPSProxyAgent allows for more granular control over what requests gets sent through Relay. This can be passed to any client that supports the Node.js Agent as a parameter.

1
evervault.createRelayHttpsAgent()

using HTTPSProxyAgent with Axios

Axios is configured in the following example to send a request through Relay.

1
const axios = require('axios');
2
3
const httpsAgent = evervault.createRelayHttpsAgent();
4
const payload = {"sensitiveField": "sensitive value"};
5
const response = await axios.post('https://example.com', payload, {
6
  httpsAgent,
7
  headers: {
8
    'Content-Type': 'application/json'
9
  }
10
});

evervault.enableCagesBeta(cageAttestationData)

Configures your application to attest all TLS connections to Evervault Cages. See Cages's TLS Attestation to learn more.

1
await evervault.enableCagesBeta()
Parameters
cageAttestationData

A mapping of Cage names to their PCRs. This is optional. When included, the connection will only be attested when the PCRs match exactly. The provided data can be either a single Object, or an Array of Objects to allow roll-over between different sets of PCRs. If not provided, the attestation doc and its signature will be validated but the PCRs will be ignored.