DSP Web SDK

The DSP Web SDK enables integration with the Virtru Data Security Platform (DSP). It provides tools for encrypting and decrypting TDF (Trusted Data Format) content, as well as managing Attribute-Based Access Control (ABAC) operations.

Overview

The DSP Web SDK is designed to help developers secure sensitive data in web applications by leveraging the Trusted Data Format (TDF) and Attribute-Based Access Control (ABAC). Key features include:

• Easy encryption and decryption of data using TDF.
• Fine-grained access control with ABAC policies.
• Seamless integration with DSP services for key management and policy enforcement.
• Support for modern web frameworks and environments.

Table of Contents

• DSP Web SDK
  • Overview
  • Table of Contents
  • Installation
  • Usage
  • Testing
    • Linting

Installation

Install the SDK using your preferred package manager. This will add the SDK as a dependency to your project, making its APIs available for import.

Note: The package name is subject to change before public release.

# Using npm
npm install @virtru/dsp-sdk

Usage

The following example demonstrates how to authenticate with DSP, initialize the platform client, and perform common operations such as tagging and fetching configuration.

import { DSP, type Interceptor } from '@virtru/dsp-sdk';

const authInterceptor: Interceptor = (next) => async (req) => {
  req.header.set('Authorization', 'Bearer access-token');
  return next(req);
};

const dsp = new DSP({
  platformUrl: '/api',
  interceptors: [authInterceptor],
});

// Tag PDP
const taggingResponse = await dsp.services.v2.taggingPDPService.tag({});

// List policy attributes
const attributesResponse = await dsp.services.v1.attributes.listAttributes({});


// Encrypts string into a NanoTDF
const tdf = await dsp.createNanoTDF({
  source: {
    type: "buffer",
    location: new TextEncoder().encode("hello world"),
  },
});

const encrypted = await new Response(tdf).arrayBuffer();

// Decrypts the NanoTDF back to plaintext
const stream = await dsp.read({
  source: {
    type: "buffer",
    location: encrypted,
  },
});

const decrypted = await new Response(stream).text();
console.log(decrypted); // "hello world"

FIPS Mode

Use the Go FIPS WASM provider. It initializes and validates its runtime before DSP is constructed, and routes the provider's cryptographic operations through the WASM boundary:

import { AuthProviders, DSP } from '@virtru/dsp-sdk';
import { createFipsWasmCryptoService } from '@virtru/dsp-sdk/fips-wasm';

const cryptoService = await createFipsWasmCryptoService();

// Create the auth provider with the same FIPS CryptoService used by DSP.
const authProvider = await AuthProviders.clientSecretAuthProvider(
  {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    oidcOrigin: 'https://oidc-endpoint',
    exchange: 'client',
  },
  cryptoService
);

const dsp = new DSP({
  authProvider, // Backward-compatible. Prefer interceptors for new integrations.
  platformUrl: 'https://dsp-platform-url',
  cryptoService,
});

Install the optional peer dependency alongside the SDK:

npm install @virtru-private/fips-web-crypto

To provide asset-hosting options such as wasmBaseUrl, create the provider explicitly and pass it as cryptoService to DSP.

The Go FIPS WASM provider supports RSA-OAEP plus P-256, P-384, and P-521 ECDH/ECDSA operations. createFipsWasmCryptoService() selects RSA-OAEP SHA-1 for the KAS key-wrap path, matching what KAS and @opentdf/sdk's own WebCryptoService do; the SHA-256 default of @virtru-private/fips-web-crypto fails every KAS unwrap.

Migrating from the legacy FIPS provider

The legacy FIPS 140-2 BoringSSL WASM integration has been removed. useFips, FipsCryptoService, and the @virtru/dsp-sdk/fips entrypoint are no longer available. Initialize createFipsWasmCryptoService() before constructing DSP, then supply the returned cryptoService to both the auth provider and DSP as shown above.

Refer to the API documentation for a complete list of available methods and configuration options.

Testing

This section is intended for repository maintainers and contributors.

The unit suite runs in Vitest jsdom mode. The optional browser integration suite uses Playwright and is skipped unless its DSP credentials are supplied.

To run the unit suite:

pnpm test:unit

To run the browser integration suite against a DSP environment, provide DSP_PLATFORM_URL, CLIENT_ID, CLIENT_SECRET, and OIDC_ENDPOINT, then run:

pnpm test:integration

The suite initializes the Go FIPS WASM provider in Chromium and verifies FIPS-to-FIPS and FIPS-to-WebCrypto TDF compatibility.

Linting

• ESLint is used for linting. To check for linting errors:

  pnpm lint

• To automatically fix linting errors:

  pnpm lint:fix

Code Generation (For Maintainers)

This section is for maintainers who need to regenerate TypeScript code from protobuf definitions.

Purpose

The SDK includes TypeScript code that is generated from protobuf definitions in the data-security-platform repository. This generated code lives in src/gen/ and is checked into version control. The code generation process is manual to ensure CI builds succeed without requiring access to the DSP repository.

Prerequisites

• Node.js (version 22 or higher)
• buf CLI installed (https://buf.build/docs/installation)
• Access to the data-security-platform repository

Setup

1. Clone the data-security-platform repository as a sibling to this monorepo:

cd ../../  # Navigate to parent directory containing js-lib-monorepo
git clone [email protected]:virtru-corp/data-security-platform.git

Your directory structure should look like:

virtru-corp/
├── js-lib-monorepo/
│   └── libraries/
│       └── dsp-sdk/
└── data-security-platform/
    └── ext/

Running Code Generation

From the dsp-sdk directory, run:

buf generate ../../../data-security-platform/ext \
  --path ../../../data-security-platform/ext/virtru/policy/certificates \
  --path ../../../data-security-platform/ext/virtru/policy/objects.proto \
  --path ../../../data-security-platform/ext/virtru/common

This will regenerate the TypeScript files in src/gen/.

Clone and Generate

From the dsp-sdk directory, run:

pnpm run update-protos

This will clone to DSP repo for you, and generate protos, copy them over and update the license within them.

When to Regenerate

You only need to regenerate the code when:

• Proto definitions in the data-security-platform repository change
• New proto files are added that the SDK needs to consume
• Proto dependencies are updated

After regenerating, commit the updated files in src/gen/ to version control.