dcpe-js

DCPE-JS

Distance Comparison Preserving Encryption (DCPE) for JavaScript. A framework that enables secure, end-to-end encryption of vector embeddings while preserving the ability to perform similarity search on the encrypted data.

Features

• Zero-Trust Security: Client-side encryption and decryption via client-managed keys (BYOK)
• Searchable Encryption: Perform similarity search on encrypted vectors
• Metadata Filtering: Support for encrypted metadata fields with deterministic encryption
• Vector Database Agnostic: Works with any vector database through adapter interface
• Next.js Compatible: Designed for seamless integration with Next.js applications

Installation

# Using npm
npm install dcpe-js

# Using yarn
yarn add dcpe-js

# Using pnpm
pnpm add dcpe-js

Quick Start

import { DCPE } from 'dcpe-js';

// Create a DCPE instance
const dcpe = new DCPE();

// Generate encryption keys
const keys = await dcpe.generateKeys();
dcpe.setKeys(keys);

// Encrypt a vector embedding
const vector = [0.1, 0.2, 0.3, 0.4];
const encryptedVector = dcpe.encryptVector(vector);

// Encrypt document text
const text = "This is a secret document.";
const encryptedText = dcpe.encryptText(text);

// Encrypt metadata for filtering
const category = "finance";
const encryptedCategory = dcpe.encryptMetadata(category);

// Store in your vector database
// { vector: encryptedVector, metadata: { text: encryptedText, category: encryptedCategory } }

// Later, decrypt the results
const decryptedText = dcpe.decryptText(encryptedText);
const decryptedCategory = dcpe.decryptMetadata(encryptedCategory);

Working with Vector Databases

DCPE-JS can work with any vector database through its adapter interface:

import { DCPE, BaseAdapter } from 'dcpe-js';

// Create a custom adapter for your vector database
class MyDatabaseAdapter extends BaseAdapter {
  constructor(config) {
    super(config);
    // Initialize your database client
  }

  async connect() {
    // Connect to your database
    return true;
  }

  async insert(vectors) {
    // Insert vectors into your database
    return ["id1", "id2"]; // Return inserted IDs
  }

  async search(queryVector, options) {
    // Search for similar vectors
    return [{ id: "id1", score: 0.95 }];
  }

  async disconnect() {
    // Clean up resources
  }
}

// Use your adapter
const adapter = new MyDatabaseAdapter({
  host: "https://your-db-host.com",
  apiKey: "your-api-key"
});

await adapter.connect();

Next.js Integration

DCPE-JS is designed to work seamlessly with Next.js applications:

// In your Next.js client component
'use client';
import { useState } from 'react';
import { DCPE } from 'dcpe-js';

export default function EncryptionComponent() {
  const [result, setResult] = useState('');
  
  const encryptData = async () => {
    // Create DCPE instance
    const dcpe = new DCPE();
    
    // Generate or load keys
    const keys = await dcpe.generateKeys();
    dcpe.setKeys(keys);
    
    // Encrypt data
    const vector = [0.1, 0.2, 0.3, 0.4];
    const encrypted = dcpe.encryptVector(vector);
    
    setResult(`Encrypted: ${JSON.stringify(encrypted)}`);
  };
  
  return (
    <div>
      <button onClick={encryptData}>Encrypt Data</button>
      <pre>{result}</pre>
    </div>
  );
}

Advanced Configuration

DCPE-JS offers various configuration options:

const dcpe = new DCPE({
  // Key provider configuration
  keyProvider: 'local', // 'local' is the default
  keyProviderConfig: {
    // Provider-specific options
  },
  
  // Vector configuration
  vectorConfig: {
    approximationFactor: 0.95 // Trade-off between security and performance
  }
});

API Documentation

For detailed API documentation, see the API Reference.

Examples

• Basic Vector Encryption
• Text and Metadata Encryption
• Next.js Integration
• Custom Database Adapter

Advanced Usage

For more advanced usage scenarios, please refer to:

• Getting Started Guide
• Advanced Configuration
• Custom Adapter Implementation

Acknowledgments

This project is inspired by IronCore Labs' Cloaked AI library, which provides searchable encryption for vector embeddings. The original implementation can be found here.

License

This project is licensed under the MIT License - see the LICENSE file for details.