@encoradb/core

The core encryption engine for EncoraDB. This package handles AES-256-GCM field encryption, HKDF key derivation, HMAC blind indexing for searchable queries, and SOC2 audit logging.

📦 Installation

pnpm add @encoradb/core
# or
npm install @encoradb/core

🚀 Basic Usage (Local Mode)

In Local Mode, you provide a 32-byte master key (64 hex characters) directly or via environment variable (process.env.ENCORA_MASTER_KEY).

1. Generate a Master Key

Generate a secure 32-byte hex key using openssl:

openssl rand -hex 32
# Example output: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

2. Initialize EncoraDB

import { EncoraDB } from "@encoradb/core";

const encora = new EncoraDB({
  masterKey: process.env.ENCORA_MASTER_KEY, // 64 hex characters
  mode: "local",
  encryptColumns: {
    users: ["email", "ssn"],
    orders: ["credit_card"],
  },
  searchableColumns: {
    users: ["email"], // Automatically generates email_bindex HMAC search token
  },
});

// Encrypt a row
const encryptedRow = await encora.encrypt("users", {
  id: 1,
  name: "Alice",
  email: "[email protected]", // Encrypted to enc:gcm:...
});

// Decrypt a row
const decryptedRow = await encora.decryptRow("users", encryptedRow);
console.log(decryptedRow.email); // "[email protected]"

🔍 Searchable Encryption (HMAC Blind Indexing)

Standard AES-256-GCM ciphertexts change on every write. EncoraDB uses HMAC Blind Indexing to enable exact-match lookups (WHERE email = ?) without exposing plaintext to the database:

// Generate deterministic HMAC search token for exact match queries
const searchToken = encora.generateBlindIndex("users", "email", "[email protected]");
// Output: "bindex:sha256:e3b0c44298fc1c149afbf4c89..."

// Query database using searchToken:
// SELECT * FROM users WHERE email_bindex = searchToken

⚙️ Configuration

The EncoraDB constructor accepts an EncryptionConfig object:

| Property | Type | Description | | :--- | :--- | :--- | | mode | 'local' \| 'kms' | Required. Defines the encryption strategy. | | masterKey | string | Required for local mode (if ENCORA_MASTER_KEY env is not set). A 64-character hex string. | | encryptColumns | Record<string, string[]> | Map of table_name ➔ [column_names] to encrypt. | | searchableColumns | Record<string, string[]> | Optional map of table_name ➔ [column_names] for blind index generation. | | kms | KmsConfig | Required for kms mode. KMS provider configuration object. | | auditLogger | IAuditLogger | Optional. Defaults to ConsoleAuditLogger. |

🛡️ Audit Logging (SOC2)

EncoraDB includes built-in audit logging for all encryption and decryption operations.

// Default output:
// [EncoraAudit] 2026... | DECRYPT | users.email | SUCCESS |

🔧 Core API Reference

encrypt(table: string, row: object)

Encrypts sensitive columns. Auto-generates <col>_bindex if column is in searchableColumns.

decryptRow(table: string, row: object)

Decrypts sensitive columns for a given table.

autoDecryptRow(row: object, tableHint?: string)

Seamlessly decrypts row without requiring manual table aliases.

generateBlindIndex(table: string, column: string, value: string)

Computes deterministic HMAC search token for exact match queries.

📄 License

MIT