A robust JavaScript/TypeScript SDK for the Cipherion Encryption API
Secure • Scalable • Enterprise-Ready
Basic and deep object encryption/decryption with enterprise-grade security
Built-in logging, error handling, and retry mechanisms for production use
Batch processing with queue and background worker support for large datasets
Full TypeScript support with comprehensive type definitions
Structured logging for audit and compliance requirements
Optimized for large-scale data processing with memory management
npm i @cipherion/client
or
yarn add @cipherion/clientCreate a .env file in your project root:
CIPHERION_BASE_URL = https://api.cipherion.cloud/api/v1/crypto
CIPHERION_PROJECT_ID = proj_your_project_id
CIPHERION_API_KEY = your_api_key_here
CIPHERION_PASSPHRASE = your_secure_passphrase_hereinterface CipherionConfig {
baseUrl: string; // API base URL
projectId: string; // Your project ID from dashboard
apiKey: string; // Your API key from dashboard
passphrase: string; // Your encryption passphrase (min 12 chars)
timeout?: number; // Request timeout (default: 30000ms)
retries?: number; // Retry attempts (default: 3)
logLevel?: 'error' | 'warn' | 'info' | 'debug';
enableLogging?: boolean; // Enable logging (default: true)
}
const { CipherionClient } = require('cipherion-client');
// Initialize client
const client = new CipherionClient();
async function example() {
try {
// Basic string encryption
const encrypted = await client.encrypt("Hello, World!");
console.log('Encrypted:', encrypted);
// Basic string decryption
const decrypted = await client.decrypt(encrypted);
console.log('Decrypted:', decrypted);
// Deep object encryption
const userData = {
name: "John Doe",
email: "john@example.com",
ssn: "123-45-6789"
};
const deepEncrypted = await client.deepEncrypt(userData);
const deepDecrypted = await client.deepDecrypt(deepEncrypted.encrypted);
console.log('Original:', userData);
console.log('Decrypted:', deepDecrypted.data);
} catch (error) {
console.error('Error:', error.message);
}
}
example();import { CipherionClient, CipherionConfig } from 'cipherion-client';
interface UserData {
id: number;
name: string;
email: string;
}
const config: CipherionConfig = {
baseUrl: process.env.CIPHERION_BASE_URL!,
projectId: process.env.CIPHERION_PROJECT_ID!,
apiKey: process.env.CIPHERION_API_KEY!,
logLevel: 'info'
};
const client = new CipherionClient(config);
const userData: UserData = {
id: 1,
name: "Jane Smith",
email: "jane@example.com"
};
const result = await client.deepEncrypt(userData);
import { CipherionClient } from '@cipherion/client';
// Initialize client (reads from environment variables)
const cipherion = new CipherionClient();
// Or with custom configuration
const cipherionCustom = new CipherionClient({
baseUrl: process.env.CIPHERION_BASE_URL,
projectId: process.env.CIPHERION_PROJECT_ID,
apiKey: process.env.CIPHERION_API_KEY,
passphrase: process.env.CIPHERION_PASSPHRASE,
timeout: 30000,
logLevel: 'info'
});
// Basic encryption
const encrypted = await cipherion.encrypt('sensitive data');
// Basic decryption
const decrypted = await cipherion.decrypt(encrypted);
#### encrypt(data: string): Promise<string>
// Encrypts a string using basic encryption
const encrypted = await cipherion.encrypt('Hello, World!');
// Returns: encrypted string
#### decrypt(encryptedData: string): Promise<string>
// Decrypts a string that was encrypted using encrypt()
const decrypted = await cipherion.decrypt(encryptedData);
// Returns: 'Hello, World!'#### deepEncrypt(data: any): Promise<DeepEncryptResponse['data']>
// Encrypts complex data structures while preserving their structure
const userData = {
name: 'John Doe',
email: 'john@example.com',
address: { street: '123 Main St', city: 'New York' },
creditCards: ['4111111111111111', '5500000000000004']
};
const encrypted = await cipherion.deepEncrypt(userData);
// Returns: encrypted structure with meta data
#### deepDecrypt(encryptedData: any): Promise<DeepDecryptResponse['data']>
const decrypted = await cipherion.deepDecrypt(encrypted.encrypted);
// Returns: original data structure with meta data| Method | Description | Returns |
|---|---|---|
| encrypt(data) | Encrypts a string | Promise<string> |
| decrypt(encryptedData) | Decrypts a string | Promise<string> |
| deepEncrypt(data) | Encrypts complex objects | Promise<DeepEncryptResponse> |
| deepDecrypt(encryptedData) | Decrypts complex objects | Promise<DeepDecryptResponse> |
| Method | Description | Use Case |
|---|---|---|
| migrateEncrypt(dataArray, options?) | Batch encrypt array of objects | Large dataset encryption |
| migrateDecrypt(encryptedArray, options?) | Batch decrypt array of objects | Large dataset decryption |
getConfig(): Omit<CipherionConfig, 'apiKey' | 'passphrase'>
Returns current configuration without sensitive data.
typescript
const config = cipherion.getConfig();
console.log(config.projectId); // Safe to log
updateConfig(newConfig: Partial<CipherionConfig>): void
Updates client configuration.
typescript
cipherion.updateConfig({
timeout: 60000,
logLevel: 'debug'
});
Perfect for enterprise scenarios requiring large-scale data processing:
migrateEncrypt(dataArray: any[], options?: MigrationOptions): Promise<MigrationResult>
Batch encrypts an array of data items with progress tracking. Useful for migrating existing databases.
typescript
const users = [
{ name: 'User 1', email: 'user1@example.com' },
{ name: 'User 2', email: 'user2@example.com' },
// ... more users
];
const result = await cipherion.migrateEncrypt(users, {
batchSize: 10,
delayBetweenBatches: 1000,
maxRetries: 3,
onProgress: (progress) => {
console.log(`Progress: ${progress.percentage}%`);
},
onError: (error, item) => {
console.error('Failed to encrypt:', item, error);
}
});
// Returns:
{
successful: [ /* encrypted items */ ],
failed: [ /* failed items with errors */ ],
summary: {
total: 100,
processed: 100,
successful: 98,
failed: 2,
percentage: 100
}
}
migrateDecrypt(encryptedArray: any[], options?: MigrationOptions): Promise<MigrationResult>
Batch decrypts an array of encrypted data items.
typescript
const result = await cipherion.migrateDecrypt(encryptedUsers, {
batchSize: 10,
onProgress: (progress) => {
console.log(`Decrypted: ${progress.successful} of ${progress.total}`);
}
});
// src/config/cipherion.ts
import { CipherionClient } from '@cipherion/client';
import dotenv from 'dotenv';
dotenv.config();
export const cipherion = new CipherionClient({
baseUrl: process.env.CIPHERION_BASE_URL!,
projectId: process.env.CIPHERION_PROJECT_ID!,
apiKey: process.env.CIPHERION_API_KEY!,
passphrase: process.env.CIPHERION_PASSPHRASE!,
});
// src/app.ts
import express from 'express';
import { cipherion } from './config/cipherion';
const app = express();
app.use(express.json());
// Encrypt user data endpoint
app.post('/api/users', async (req, res) => {
try {
const { name, email, ssn, creditCard } = req.body;
const encrypted = await cipherion.deepEncrypt({
name,
email,
ssn,
creditCard
});
res.json({
success: true,
data: encrypted.encrypted,
meta: encrypted.meta
});
} catch (error) {
res.status(500).json({
success: false,
error: error.message
});
}
});
// Decrypt user data endpoint
app.get('/api/users/:id', async (req, res) => {
try {
const encryptedData = await getUserFromDB(req.params.id);
const decrypted = await cipherion.deepDecrypt(encryptedData);
res.json({
success: true,
data: decrypted.data
});
} catch (error) {
res.status(500).json({
success: false,
error: error.message
});
}
});
// Middleware for encrypting response data
const encryptMiddleware = async (req, res, next) => {
const originalJson = res.json.bind(res);
res.json = async function(data) {
if (data.sensitive) {
const encrypted = await cipherion.deepEncrypt(data.sensitive);
data.sensitive = encrypted.encrypted;
}
originalJson(data);
};
next();
};
app.use(encryptMiddleware);
app.listen(3000, () => {
console.log('Server running on port 3000');
});
// src/cipherion/cipherion.module.ts
import { Module, Global } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { CipherionService } from './cipherion.service';
@Global()
@Module({
imports: [ConfigModule],
providers: [CipherionService],
exports: [CipherionService],
})
export class CipherionModule {}
// src/cipherion/cipherion.service.ts
import { Injectable, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { CipherionClient } from '@cipherion/client';
@Injectable()
export class CipherionService implements OnModuleInit {
private client: CipherionClient;
constructor(private configService: ConfigService) {}
onModuleInit() {
this.client = new CipherionClient({
baseUrl: this.configService.get('CIPHERION_BASE_URL'),
projectId: this.configService.get('CIPHERION_PROJECT_ID'),
apiKey: this.configService.get('CIPHERION_API_KEY'),
passphrase: this.configService.get('CIPHERION_PASSPHRASE'),
});
}
async encrypt(data: string): Promise<string> {
return this.client.encrypt(data);
}
async decrypt(encryptedData: string): Promise<string> {
return this.client.decrypt(encryptedData);
}
async deepEncrypt(data: any) {
return this.client.deepEncrypt(data);
}
async deepDecrypt(encryptedData: any) {
return this.client.deepDecrypt(encryptedData);
}
async migrateEncrypt(dataArray: any[], options?: any) {
return this.client.migrateEncrypt(dataArray, options);
}
async migrateDecrypt(encryptedArray: any[], options?: any) {
return this.client.migrateDecrypt(encryptedArray, options);
}
}
// src/users/users.controller.ts
import { Controller, Post, Get, Body, Param } from '@nestjs/common';
import { CipherionService } from '../cipherion/cipherion.service';
@Controller('users')
export class UsersController {
constructor(private readonly cipherionService: CipherionService) {}
@Post()
async createUser( @Body() userData: any) {
try {
const encrypted = await this.cipherionService.deepEncrypt({
name: userData.name,
email: userData.email,
ssn: userData.ssn,
creditCard: userData.creditCard,
});
// Save to database
// await this.usersService.create(encrypted.encrypted);
return {
success: true,
data: encrypted.encrypted,
meta: encrypted.meta,
};
} catch (error) {
return {
success: false,
error: error.message,
};
}
}
@Get(':id')
async getUser( @Param('id') id: string) {
try {
// Retrieve from database
// const encryptedData = await this.usersService.findOne(id);
const decrypted = await this.cipherionService.deepDecrypt( encryptedData);
return {
success: true,
data: decrypted.data,
};
} catch (error) {
return {
success: false,
error: error.message,
};
}
}
}
// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { CipherionModule } from './cipherion/cipherion.module';
import { UsersModule } from './users/users.module';
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
}),
CipherionModule,
UsersModule,
],
})
export class AppModule {}// migrate-to-encryption.ts
import { CipherionClient } from '@cipherion/client';
import { connectToDatabase, User } from './database';
async function migrateUsers() {
const cipherion = new CipherionClient();
const db = await connectToDatabase();
// Fetch all users from database
const users = await db.collection('users').find().toArray();
console.log(`Starting migration for ${users.length} users...`);
const result = await cipherion.migrateEncrypt(users, {
batchSize: 50,
delayBetweenBatches: 2000,
maxRetries: 3,
onProgress: (progress) => {
console.log(`Progress: ${progress.percentage}% (${progress.successful} successful, ${progress.failed} failed)`);
},
onError: (error, item) => {
console.error(`Failed to encrypt user ${item._id}:`, error.message);
},
});
// Update database with encrypted data
for (const encryptedUser of result.successful) {
await db.collection('users').updateOne({_id: encryptedUser.encrypted._id }}, {{"$set": {{data: encryptedUser.encrypted }});
}
console.log('\\nMigration Summary:');
console.log(`Total: ${result.summary.total}`);
console.log(`Successful: ${result.summary.successful}`);
console.log(`Failed: ${result.summary.failed}`);
// Handle failed items
if (result.failed.length > 0) {
console.log('\\nFailed items:', result.failed);
}
}
migrateUsers().catch(console.error);// src/errors/CipherionError.ts
class CipherionError extends Error {
statusCode: number;
details?: string;
originalError?: Error;
}
// Error Handling Examples
import { CipherionError } from '@cipherion/client';
try {
const encrypted = await cipherion.encrypt(data);
} catch (error) {
if (error instanceof CipherionError) {
console.error('Cipherion Error:', {
message: error.message,
statusCode: error.statusCode,
details: error.details
});
// Handle specific errors
switch (error.statusCode) {
case 400:
// Invalid request (e.g., missing passphrase)
break;
case 401:
// Unauthorized (invalid API key)
break;
case 429:
// Rate limit exceeded
break;
case 500:
// Server error
break;
}
}
}
// Express Error Handling Middleware
app.use((error, req, res, next) => {
if (error instanceof CipherionError) {
return res.status(error.statusCode).json({
success: false,
error: error.message,
details: error.details
});
}
res.status(500).json({
success: false,
error: 'Internal server error'
});
});
// NestJS Exception Filter
import { ExceptionFilter, Catch, ArgumentsHost, HttpStatus } from '@nestjs/common';
import { CipherionError } from '@cipherion/client';
@Catch(CipherionError)
export class CipherionExceptionFilter implements ExceptionFilter {
catch(exception: CipherionError, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse();
response.status(exception.statusCode || HttpStatus.INTERNAL_SERVER_ERROR).json({
success: false,
statusCode: exception.statusCode,
message: exception.message,
details: exception.details,
});
}
}
// Apply globally
app.useGlobalFilters(new CipherionExceptionFilter());
import Queue from 'bull';
import CipherionClient from '@cipherion/client';
const encryptionQueue = new Queue('encryption', {
redis: { host: 'localhost', port: 6379 }
});
// Add jobs to queue
async function queueEncryptionJobs(users) {
for (const user of users) {
await encryptionQueue.add('encrypt-user', { user });
}
}
// Process jobs
encryptionQueue.process('encrypt-user', async (job) => {
const cipherion = new CipherionClient();
const { user } = job.data;
try {
const encrypted = await cipherion.deepEncrypt(user);
await updateDatabase(user.id, encrypted.encrypted);
return { success: true };
} catch (error) {
throw error; // Will be retried by Bull
}
});
// Monitor progress
encryptionQueue.on('completed', (job) => {
console.log(`User ${job.data.user.id} encrypted successfully`);
});
encryptionQueue.on('failed', (job, err) => {
console.error(`Failed to encrypt user ${job.data.user.id}:`, err);
});The SDK automatically logs operations to cipherion-logs/ directory:
error.log - Error-level logs onlycombined.log - All logsconst cipherion = new CipherionClient({
logLevel: 'debug', // 'error' | 'warn' | 'info' | 'debug'
enableLogging: true
});