Build with the Virtru Developer Hub

It's Your Data. Protect It. Control It. Everywhere.

Try the Demo          Learn More     

Getting Started: JS - Node

The Virtru JavaScript SDK allows you to protect your application's content in both browser and server-side contexts. In this guide, we'll walk through a sample webapp that demonstrates using the SDK with headless nodejs.

For more detailed information, please see the comprehensive SDK documentation.

Step 1: Install the Virtru SDK from npm

npm install virtru-sdk
# Optionally verify installation:
node -e "console.log(require('virtru-sdk').Version)" 

Step 2: Save the Sample App as a JS File

Copy the following JS snippet into your favorite editor and save as .js (e.g., sample.js).

const Virtru = require('virtru-sdk');

async function run(){
  const email = process.argv[2];
  const appId = process.argv[3];
  const client = new Virtru.Client({email, appId});
  const encryptParams = new Virtru.EncryptParamsBuilder()
    .withStringSource('Hello, world!')
    .withDisplayFilename('hello.txt')
    .build();
  ct = await client.encrypt(encryptParams);
  await ct.toFile('hello.html');
}
run().then(() => console.log('Created my first encrypted file!'));

Step 3: Generate an AppId from Virtru

Go to the Virtru dashboard to generate an appId, the credential which Virtru will use to authenticate your app. Enable "Developer Mode" and copy the generated appId to a safe location. This appId can be revoked at any time by disabling "Developer Mode" in the dashboard.

The following is an example of storing your appId on local disk using best practices after hitting the Copy button.

APPID=$(pbpaste)
mkdir ~/.virtru
echo $APPID > ~/.virtru/appId 
chmod 400 ~/.virtru/appId

Step 4: Run the Sample App

Run the sample using node and the email/appId pair from the previous step.

A TDF-encrypted file named hello.html will be downloaded automatically after running through the authentication wizard. Open this file anytime and anywhere to securely authenticate, decrypt, and read your content!

node sample.js your@email.com $(cat ~/.virtru/appId)

Let's Break it Down

Let's take a deeper look at how the Virtru SDK is integrated into this application.

  const encryptParams = new Virtru.EncryptParamsBuilder()
    .withStringSource('Hello, world!')
    .withDisplayFilename('hello.txt')
    .build();
  ct = await client.encrypt(encryptParams);

Encryption is a core operation of the SDK, so we'll look at this section first. Here we specify the content to encrypt using withStringSource(), and then we execute the encrypt() using the SDK client.

We also set the filename to display in Secure Reader using withDisplayFilename(). This optional configuration is solely to give Secure Reader a readable name to display and ensure the decrypted content is rendered in-browser as plaintext (using .txt).

await ct.toFile('hello.html');

In this line we take the returned ciphertext, in TDFCiphertextStream form, and write it out to a local file using the toFile() helper function.

Note that the local filename is independent of the display filename from the previous step. For novice users we recommend an .html suffix so the file can easily opened using the browser.

  const email = process.argv[2];
  const appId = process.argv[3];
  const client = new Virtru.Client({email, appId});

In this section we initialize the SDK client, using the email and appId generated in Step 3. The client instance will continue to use this credential pair to authenticate all of its operations.

const Virtru = require('virtru-sdk');

async function run(){
  // ...
}
run().then(() => console.log('created my first encrypted file!'));

Finally, this section contains the boilerplate for including the SDK package and running it in an async context. See the following section for an example of using the SDK in a standard (i.e., non-async) context.

Stream-Based Interface

The core encrypt() and decrypt() operations are built around the standard node Stream library and return Readable streams instrumented with helper functions like toFile(). These streams can be used with standard node stream processing techniques, such as writing to a file with fs.createWriteStream().

For example, the sample.js above could alternatively be written as the following:

const Virtru = require('virtru-sdk');
const fs = require('fs');

const email = process.argv[2];
const appId = process.argv[3];
const client = new Virtru.Client({email, appId});
const encryptParams = new Virtru.EncryptParamsBuilder()
  .withStringSource('Hello, world!')
  .withDisplayFilename('hello.txt')
  .build();
client.encrypt(encryptParams).then(ct =>
 ct.pipe(fs.createWriteStream('hello.html')));

Getting Started: JS - Node


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.