SEVOLA SDK for JavaScript/Node.js

A comprehensive Node.js SDK for format-preserving encryption (FF1) and AES-GCM encryption via HashiCorp Vault or built-in key management. This SDK provides multiple encryption modes including REST, Transit, and Dynamic Transit encryption with support for both single operations and batch processing.

Features

• Format-Preserving Encryption (FF1): Preserves data format while encrypting
• AES-256-CBC Encryption: Standard encryption for transit and rest data
• Multiple Key Types: Support for rest, transit, and dynamictransit encryption modes
• Dynamic Key Management: Automatic key rotation with trace ID tracking
• Batch Processing: Efficient encryption/decryption of multiple data items
• Template Detection: Automatic detection of numeric vs alphanumeric data
• Key Caching: Automatic 5-minute key caching for improved performance
• Automatic Retry: Built-in retry logic for transient network errors (ECONNRESET, etc.)
• TypeScript Support: Full type definitions and IntelliSense support
• Multiple Build Formats: CommonJS, ESM, and UMD support
• ES5 Compatibility: Full support for older browsers and Node.js versions (0.12+)
• Comprehensive Error Handling: Detailed error messages and timeout support

Installation

npm install sevola-sdk-js

ES5 Compatibility

This library is fully compatible with ES5 environments and older browsers. It includes built-in polyfills for:

• Promise: Full Promise implementation for environments without native support
• Object.assign: Object property copying utility
• Array.from: Array creation from array-like objects
• Array.prototype.find: Array search functionality
• String.prototype.startsWith/endsWith/includes: String search methods

The library automatically detects and polyfills missing features, ensuring compatibility with:

• Internet Explorer 9+
• Node.js 0.12+
• Older mobile browsers
• Legacy enterprise environments

Note: For production use in ES5 environments, consider installing core-js as a peer dependency for additional polyfills:

npm install core-js

⚠️ Important Warning: Node.js Environment Only

This library cannot be used in browser environments due to several Node.js-specific dependencies and security requirements:

Why Browser Usage is Not Supported:

1. Node.js Crypto Module: The SDK relies on Node.js built-in crypto module for:

   • AES-256-CBC encryption/decryption
   • PBKDF2 key derivation
   • Random byte generation
   • Hash functions

2. File System Access: Some operations require access to Node.js file system APIs

3. Network Security: The SDK makes HTTP requests to encryption servers, which may have CORS restrictions in browsers

4. Security Considerations: Running encryption libraries in browsers can expose sensitive operations to client-side code

What This Means:

• ✅ Supported: Node.js applications, server-side scripts, CLI tools
• ❌ Not Supported: Web browsers, React Native, Electron renderer process
• ⚠️ Limited Support: Electron main process (if properly configured)

Example of What Won't Work:

// ❌ This will fail in browsers
import { EncryptClient } from 'sevola-sdk-js';
const client = new EncryptClient('api-key'); // Error: crypto module not found

Example of What Will Work:

// ✅ This works in Node.js
import { EncryptClient } from 'sevola-sdk-js';
const client = new EncryptClient('api-key');
const encrypted = await client.encryptData('sensitive data');

Quick Start

Basic Usage

import { EncryptClient } from 'sevola-sdk-js';

// Initialize with API key only
const client = new EncryptClient('your-api-key');

// Or with full configuration
const client = new EncryptClient({
  apiKey: 'your-api-key',
  baseUrl: 'http://localhost:8082', // Optional, defaults to localhost:8082
  timeout: 30000,      // Optional, defaults to 30 seconds
  logger: true,        // Optional, enables debug logging (default: false)
  retryAttempts: 3,    // Optional, number of retries for network errors (default: 3)
  retryDelay: 1000     // Optional, base delay between retries in ms (default: 1000)
});

Format-Preserving Encryption (FF1)

// Single data encryption with automatic template detection
const plaintext = 'Hello123World';
const encrypted = await client.encryptData(plaintext);
console.log('Encrypted:', encrypted); // Returns array with encrypted data and template

// Single data decryption
const decrypted = await client.decryptData(encrypted[0].encrypted);
console.log('Decrypted:', decrypted); // Returns array with decrypted data and template

// Batch encryption with explicit templates
const requests = [
  { template: 'numeric', data: '12345' },
  { template: 'alphanumeric', data: 'ABC123' },
  { template: 'numeric', data: '67890' }
];

const batchEncrypted = await client.encryptDataFF1(requests);
console.log('Batch Encrypted:', batchEncrypted);

// Batch decryption
const batchDecrypted = await client.decryptDataFF1(batchEncrypted);
console.log('Batch Decrypted:', batchDecrypted);

AES Transit Encryption

// Standard transit encryption
const plaintext = 'Sensitive transit data';
const encrypted = await client.encryptTransit(plaintext);
console.log('Transit Encrypted:', encrypted);

// Transit decryption
const decrypted = await client.decryptTransit(encrypted);
console.log('Transit Decrypted:', decrypted);

// Dynamic transit encryption (with automatic key rotation)
const dynamicEncrypted = await client.encryptTransitDynamic(plaintext);
console.log('Dynamic Encrypted:', dynamicEncrypted);

// Dynamic transit decryption (uses embedded trace ID)
const dynamicDecrypted = await client.decryptTransitDynamic(dynamicEncrypted);
console.log('Dynamic Decrypted:', dynamicDecrypted);

// High-Performance Batch Processing
const batchData = ['item1', 'item2', 'item3', ...moreItems];

// Encrypt multiple items in parallel (optimized with caching and concurrency)
const batchEncrypted = await client.encryptTransitBatch(batchData);
console.log('Batch Encrypted:', batchEncrypted.length);

// Decrypt multiple items in parallel
const batchDecrypted = await client.decryptTransitBatch(batchEncrypted);
console.log('Batch Verified:', batchDecrypted[0] === batchData[0]);

API Reference

EncryptClient Class

The main client class for all encryption operations.

Constructor

new EncryptClient(apiKey: string)
new EncryptClient(options: EncryptClientOptions)

Configuration Options

interface EncryptClientOptions {
  apiKey: string;         // Required: Your API key for authentication
  baseUrl?: string;       // Optional: Base URL for the API (default: 'http://localhost:8082')
  timeout?: number;       // Optional: Request timeout in milliseconds (default: 30000)
  logger?: boolean;       // Optional: Enable debug logging (default: false)
  retryAttempts?: number; // Optional: Number of retry attempts for network errors (default: 3)
  retryDelay?: number;    // Optional: Base delay between retries in ms (default: 1000)
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your API key for authentication | | baseUrl | string | 'http://localhost:8082' | Base URL for the encryption API | | timeout | number | 30000 | Request timeout in milliseconds | | logger | boolean | false | Enable debug logging to console | | retryAttempts | number | 3 | Number of retry attempts for transient network errors | | retryDelay | number | 1000 | Base delay between retries in ms (uses exponential backoff) |

Public Methods

Format-Preserving Encryption (FF1)

// Legacy method with automatic template detection
encryptData(plaintext: string): Promise<NewEncryptionResult[]>
decryptData(cipherText: string): Promise<NewDecryptionResult[]>

// Modern batch methods with explicit templates
encryptDataFF1(requests: { template: string; data: string }[]): Promise<{ template: string; encrypted: string }[]>
decryptDataFF1(requests: { template: string; data: string }[]): Promise<{ template: string; decrypted: string }[]>

AES Transit Encryption

// Standard transit encryption
encryptTransit(plaintext: string): Promise<string>
decryptTransit(cipherText: string): Promise<string>

// Modern batch methods with concurrency support (up to 20 batches in parallel)
encryptTransitBatch(plaintexts: string[]): Promise<string[]>
decryptTransitBatch(ciphertexts: string[]): Promise<string[]>

// Dynamic transit encryption with key rotation
encryptTransitDynamic(plaintext: string): Promise<string>
decryptTransitDynamic(cipherText: string): Promise<string>

Cache Management

// Clear all cached encryption keys (force fresh fetch from server)
clearCache(): void

// Get number of cached keys (for debugging/monitoring)
getCacheSize(): number

Data Types

Encryption Results

interface EncryptionResult {
  encrypted: string;
  template: 'numeric' | 'alphanumeric';
}

interface DecryptionResult {
  data: string;
  template: 'numeric' | 'alphanumeric';
}

API Responses

interface ApiResponse {
  status: string;
  message: string;
  data: string;
}

interface DynamicKeyResponse {
  status: string;
  message?: string;
  data: {
    key: string;
    'x-sevola-traceid': string;
  };
}

Key Types and Operations

type KeyType = 'rest' | 'transit' | 'dynamictransit';
type EncryptionOperation = 'enc' | 'dec';

Usage Examples

Credit Card Number Encryption

const client = new EncryptClient('your-api-key');

// Encrypt credit card number (preserves numeric format)
const cardNumber = '4111111111111111';
const encrypted = await client.encryptDataFF1([
  { template: 'numeric', data: cardNumber }
]);

console.log('Original:', cardNumber);
console.log('Encrypted:', encrypted[0].encrypted); // Still numeric format

// Decrypt
const decrypted = await client.decryptDataFF1(encrypted);
console.log('Decrypted:', decrypted[0].decrypted); // Original card number

Email Address Encryption

const client = new EncryptClient('your-api-key');

// Encrypt email address (preserves alphanumeric format)
const email = '[email protected]';
const encrypted = await client.encryptDataFF1([
  { template: 'alphanumeric', data: email }
]);

console.log('Original:', email);
console.log('Encrypted:', encrypted[0].encrypted); // Preserves @ symbol and format

// Decrypt
const decrypted = await client.decryptDataFF1(encrypted);
console.log('Decrypted:', decrypted[0].decrypted); // Original email

Batch Processing Multiple Data Types

const client = new EncryptClient('your-api-key');

const dataToEncrypt = [
  { template: 'numeric', data: '1234567890' },      // Phone number
  { template: 'alphanumeric', data: 'ABC123XYZ' },  // Product code
  { template: 'numeric', data: '9876543210' },      // Another phone number
  { template: 'alphanumeric', data: '[email protected]' } // Email
];

// Encrypt all data in one batch
const encrypted = await client.encryptDataFF1(dataToEncrypt);

// Process encrypted data
encrypted.forEach((item, index) => {
  console.log(`Item ${index + 1}:`, {
    template: item.template,
    encrypted: item.encrypted
  });
});

// Decrypt all data in one batch
const decrypted = await client.decryptDataFF1(encrypted);

Dynamic Key Encryption for High Security

const client = new EncryptClient('your-api-key');

// Encrypt with dynamic key (each encryption uses a new key)
const sensitiveData = 'highly-sensitive-information';
const encrypted = await client.encryptTransitDynamic(sensitiveData);

console.log('Dynamic Encrypted:', encrypted);
// Output includes trace ID: "base64encrypteddatax-sevola-traceid=abc123..."

// Decrypt using the embedded trace ID
const decrypted = await client.decryptTransitDynamic(encrypted);
console.log('Decrypted:', decrypted); // Original sensitive data

Error Handling

const client = new EncryptClient({
  apiKey: 'your-api-key',
  logger: true  // Enable to see retry attempts in console
});

try {
  // Attempt encryption (will auto-retry on network errors)
  const encrypted = await client.encryptData('test data');
  console.log('Success:', encrypted);
} catch (error) {
  if (error.message.includes('timeout')) {
    console.error('Request timed out - check network connection');
  } else if (error.message.includes('Invalid API Key')) {
    console.error('Authentication failed - check API key');
  } else if (error.message.includes('Network error after')) {
    console.error('Network error persisted after all retries');
  } else if (error.message.includes('HTTP 404')) {
    console.error('API endpoint not found - check base URL');
  } else {
    console.error('Encryption failed:', error.message);
  }
}

Template Types

The SDK supports two main template types for format-preserving encryption:

Numeric Template

• Alphabet: 0123456789
• Use Case: Phone numbers, credit card numbers, SSNs, PINs
• Example: "1234567890" → "9876543210" (same format, different values)

Alphanumeric Template

• Alphabet: 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ@
• Use Case: Email addresses, product codes, usernames, alphanumeric IDs
• Example: "[email protected]" → "x7k9#m2n4p8q" (preserves @ symbol)

Performance & Reliability

Batch Processing & Concurrency

The SDK is optimized for high-throughput scenarios using intelligent batching and concurrency control:

• Parallel Execution: encryptTransitBatch and decryptTransitBatch process requests in parallel (up to 20 concurrent batches).
• Derived Key Caching: CPU-intensive PBKDF2 operations are cached, making decryption essentially instantaneous (millisec range) after the first fetch.
• Smart Queueing: Large datasets are automatically split into manageable chunks to prevent API overloading.

Key Caching

The SDK automatically caches encryption keys to reduce API calls and improve performance:

• Keys are cached for 5 minutes by default
• Subsequent encrypt/decrypt operations reuse cached keys
• Use clearCache() to force fetching fresh keys from the server

const client = new EncryptClient('your-api-key');

// Perform multiple operations (key is fetched once, then cached)
await client.encryptData('data1');
await client.encryptData('data2'); // Uses cached key
await client.encryptData('data3'); // Uses cached key

// Force fresh key fetch
client.clearCache();

// Check cache state
console.log('Cached keys:', client.getCacheSize());

Automatic Retry

The SDK automatically retries requests when transient network errors occur:

| Error Code | Description | |------------|-------------| | ECONNRESET | Connection reset by peer | | ECONNREFUSED | Connection refused | | ETIMEDOUT | Connection timed out | | ENOTFOUND | DNS lookup failed | | EAI_AGAIN | DNS temporary failure | | EPIPE | Broken pipe | | EHOSTUNREACH | Host unreachable | | ENETUNREACH | Network unreachable |

Retry behavior uses exponential backoff: 1s → 2s → 3s (with default settings).

// Configure retry behavior
const client = new EncryptClient({
  apiKey: 'your-api-key',
  retryAttempts: 5,    // Try up to 5 times
  retryDelay: 2000,    // Start with 2s delay (then 4s, 6s, 8s, 10s)
  logger: true         // Enable to see retry logs
});

Security Features

Key Management

• Automatic Key Retrieval: Keys are fetched securely from the server
• Key Caching: Keys are cached locally for 5 minutes to improve performance
• Key Rotation: Dynamic transit mode supports automatic key rotation
• Trace ID Tracking: Each dynamic encryption includes a unique trace ID
• Secure Communication: All API calls use HTTPS and proper authentication

Encryption Standards

• FF1 Algorithm: NIST-approved format-preserving encryption
• AES-256-CBC: Industry-standard symmetric encryption
• PBKDF2 Key Derivation: Secure key derivation with salt
• Random IV Generation: Unique initialization vectors for each encryption

Requirements

• Node.js: 14.0.0 or higher
• Runtime Dependencies:
  • node-fetch: ^3.3.2 (HTTP client)
  • ubiq-security: ^2.2.3 (FF1 encryption library)
• Development Dependencies: See package.json for full list

License

MIT © PT Ifabula Digital Kreasi

Support

• Repository: https://gitlab.com/kasfi.tamiya/sevola_sdk_js
• Issues: https://gitlab.com/kasfi.tamiya/sevola_sdk_js/issues
• Author: Kasfi Tamiya ([email protected])
• Company: PT Ifabula Digital Kreasi (https://ifabula.com)