Example Implementations

Every business has different compliance requirements for how Protected Health Information (PHI) and Personally Identifiable Information (PII) must be handled.

Volidator supports four distinct architectural modes. Below are complete, copy-pasteable examples for the Node.js SDK demonstrating exactly how to configure the client and trigger an audit log for each scenario.

Use Case: You are logging raw infrastructure events or system actions where no human identifiers (like emails or SSNs) are involved.

How it works: You log the raw payload. Because AES-GCM encryption is applied globally by the SDK to every payload, no special configuration is needed to secure this data. It is End-to-End Encrypted (E2EE) on your server before reaching Volidator.

import { VolidatorClient } from '@volidator/node';

// 1. Initialize standard client
const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
});

// 2. Log the event
await volidator.log({
  actor: 'system_cron_job',
  action: 'database.backup.completed',
  target: 'db_cluster_us_east',
  metadata: {
    durationMs: 4500,
    bytesTransferred: 1024000
  }
});

Use Case: You want to log PII (like emails or names), but you want the convenience of having Volidator store it.

How it works: You use the exact same code as Mode 1!

Why? Because Volidator uses a Zero-Knowledge Architecture, the SDK doesn’t need to know which fields are PII. The entire payload (including the email and phone number) is encrypted with AES-256-GCM locally. Volidator stores the ciphertext but mathematically cannot read the PII.

import { VolidatorClient } from '@volidator/node';

// 1. Initialize standard client
const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
});

// 2. Log the event with PII
// The email and phone number are encrypted before leaving your server.
await volidator.log({
  actor: '[email protected]',
  action: 'billing.payment.processed',
  target: 'inv_891011',
  metadata: {
    stripeCustomerId: 'cus_123',
    customerPhone: '+1-555-0100'
  }
});

Use Case: Strict compliance (e.g., HIPAA) dictates that PII/PHI must absolutely never leave your database, even in encrypted form. However, your dashboard still needs to display human-readable names to authorized admins.

How it works: You log a Database Reference ID (like a UUID) instead of the PII. When the dashboard renders, it asks your host application to securely resolve that ID back into a name on-the-fly.

import { VolidatorClient } from '@volidator/node';

// 1. Initialize client with Reference Keys
// This tells the SDK: "Do not store the actor or target directly.
// Expect the dashboard to resolve these IDs on the frontend via JIT Hydration."
const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
  referenceKeys: ['actor', 'target']
});

// 2. Log the Reference IDs, NOT the PII
// 'usr_999' is an opaque ID stored in your local DB
await volidator.log({
  actor: 'usr_999',
  action: 'patient.record.view',
  target: 'med_rec_404',
  metadata: {
    department: 'oncology'
  }
});

// Note: The embed dashboard will see [REF:usr_999] and trigger a
// postMessage handshake to your app to request the name "Jane Doe".

Use Case: You are logging events where PII is present, but you want to permanently destroy the PII before the log is saved. You don’t care about mapping it back to a human-readable name in the dashboard.

How it works: The SDK intercepts the payload, permanently replaces the PII with a [REDACTED] placeholder, and then encrypts it.

import { VolidatorClient } from '@volidator/node';

// 1. Initialize client with Redact Keys
const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
  // Tell the SDK: "Aggressively strip these fields and permanently
  // replace them with [REDACTED] before you encrypt the payload."
  redactKeys: ['actor', 'metadata.ssn', 'metadata.patientName']
});

// 2. Log the event normally
await volidator.log({
  actor: '[email protected]',
  action: 'account.delete',
  metadata: {
    reason: 'Requested via support',
    ssn: '000-00-0000',
    patientName: 'Jane Smith'
  }
});

// The encrypted payload stored in Volidator will look like this:
// {
//   actor: "[REDACTED:actor]",
//   action: "account.delete",
//   metadata: {
//     reason: "Requested via support",
//     ssn: "[REDACTED:ssn]",
//     patientName: "[REDACTED:patientName]"
//   }
// }
//
// Note: The blind index is still generated from "[email protected]",
// so you can still mathematically search for logs by Jane Smith,
// but the email itself is permanently destroyed.