@encoradb/core

The core encryption engine for EncoraDB. This package handles the heavy lifting of encryption, decryption, key derivation, and audit logging. It is designed to be used either directly or via the @encoradb/adapters package.

📦 Installation

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

🚀 Basic Usage

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

const encora = new EncoraDB({
  masterKey: "YOUR_32_BYTE_HEX_MASTER_KEY",
  mode: "local",
  encryptColumns: {
    users: ["email", "password"],
    orders: ["credit_card"],
  },
});

// Encrypt a row (only configured columns are encrypted)
const encryptedUser = await encora.encrypt("users", {
  name: "Alice",
  email: "[email protected]",
});
// Result: { name: 'Alice', email: 'enc:gcm:...' }

// Decrypt a row
const decryptedUser = await encora.decryptRow("users", encryptedUser);
// Result: { name: 'Alice', email: '[email protected]' }

⚙️ Configuration

The EncoraDB constructor accepts an EncryptionConfig object:

| Property | Type | Description | | :--- | :--- | :--- | | masterKey | string | A 32-byte hex string used to derive per-column keys. Required for local mode. | | mode | 'local' \| 'kms' | Required. local uses the master key directly. kms uses Envelope Encryption (coming soon). | | encryptColumns | Record<string, string[]> | A map of table_name -> [column_names]. Defines which fields are encrypted. | | auditLogger | IAuditLogger | Optional custom logger for SOC2 compliance. Defaults to ConsoleAuditLogger. |

🛡️ Audit Logging (SOC2)

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

// Default Logger outputs to console
// [EncoraAudit] 2025... | DECRYPT | users.email | SUCCESS | undefined

You can provide a custom logger to send logs to CloudWatch, Datadog, etc.:

const myLogger = {
  log: async (event) => {
    // push to monitoring system
    console.log("AUDIT:", event.action, event.column);
  }
};

const encora = new EncoraDB({ ..., auditLogger: myLogger });

🔧 API Reference

encrypt(table: string, row: object)

Encrypts the configured sensitive columns within the given row object. Returns a new object with encrypted values.

decryptRow(table: string, row: object)

Decrypts the configured sensitive columns within the given row object.

decryptJoinedRows(rows: object[], mapping: Record<string, string[]>)

Helper for decrypting results from SQL JOINS where columns are aliased (e.g., users__email).

• mapping: { users: ['email'] } tells the engine to look for users__email and decrypt it using the users.email key.

📄 License

MIT