🔐 EncoraDB

EncoraDB is a universal database encryption layer for Node.js and TypeScript. It automatically secures sensitive data (PII) in your database while maintaining ORM-agnostic flexibility and SOC2-compliant audit logging.

Status: Production Ready (Phase 3 Completed) 🚀

---

🌟 Key Features

• 🔐 Zero-Effort Encryption: Automatically encrypts sensitive columns (email, ssn, password) on write and decrypts on read.
• 🗝️ Secure Key Management: Uses AES-256-GCM with HKDF key derivation. Supports static master keys or KMS Envelope Encryption.
• 🧩 Plug-and-Play Adapters: Integrations for Slonik (more coming: Prisma, Knex).
• 🛡️ SOC2 Compliance: Built-in audit logging for all crypto operations.
• ⚡ Performance: Optimized for minimal overhead.
• 📦 Monorepo Architecture: Modular packages for Core, Adapters, and CLI.

---

📦 Architecture & Packages

EncoraDB is managed as a monorepo using pnpm workspaces.

Package	Description	Version	Links
@encoradb/core	The encryption engine, key management, and audit logging system.	0.1.1	README
@encoradb/adapters	Database/ORM interceptors (e.g., Slonik).	0.1.1	README
@encoradb/cli	CLI tools for scanning schemas, key rotation, and validation.	0.1.1	README

---

🚀 Quick Start for Users

1️⃣ Install

pnpm add @encoradb/core @encoradb/adapters

2️⃣ Initialize (Slonik Example)

import { createPool, sql } from "slonik";
import { EncoraDB } from "@encoradb/core";
import { createEncoraInterceptor } from "@encoradb/adapters";

// 1. Configure EncoraDB
const encora = new EncoraDB({
  masterKey: process.env.ENCORA_MASTER_KEY, // 32-byte hex string
  mode: "local",
  encryptColumns: {
    users: ["email", "ssn"],
  },
});

// 2. Attach to Database Driver
const pool = await createPool("postgres://localhost/mydb", {
  interceptors: [createEncoraInterceptor(encora)],
});

// 3. Use your database as normal!
// Reads are decrypted automatically
// Note: Use 'email as users__email' if implicit table context is missing
const user = await pool.one(sql.type(User)`
  SELECT id, email as users__email FROM users WHERE id = 1
`);
console.log(user.users__email); // "alice@example.com" (Decrypted)

---

💻 Contribution Guide

We welcome contributions! Whether you're fixing a bug, improving documentation, or adding a new adapter, here's how to get started.

Prerequisites

• Node.js: v20 or higher
• pnpm: v9 or higher (npm install -g pnpm)
• Docker (Optional, for running local DBs if needed)

🛠️ Local Development Setup

1. Clone the repository

   git clone https://github.com/shurajcodx/encoradb.git
   cd encoradb

2. Install dependencies We use pnpm workspaces.

   pnpm install

3. Build all packages This compiles TypeScript for all packages in the correct order.

   pnpm build

4. Watch mode (Development) To watch for changes and recompile automatically:

   pnpm dev

🧪 Testing

We use Vitest for testing.

# Run all tests
pnpm test

# Run tests for a specific package
pnpm --filter @encoradb/core test

� Testing CLI locally

To test the CLI package without publishing:

# 1. From root, build everything
pnpm build

# 2. Go to CLI package and link
cd packages/cli
pnpm link --global

# 3. Use it!
encoradb --help

---

🗺️ Roadmap

• Phase 1: Core SDK (Encryption Engine, HKDF, SOC2 Audit Logging)
• Phase 2: Adapters (Slonik Interceptor, Automatic Decryption)
• Phase 3: CLI (Scan, Key Rotation via Re-encryption)
• Phase 4: Advanced Features (KMS Integration, Deterministic Encryption)
• Phase 5: Ecosystem (Prisma Middleware, TypeORM Subscriber)

---

📂 Project Structure

encoradb/
├── packages/
│   ├── core/       # Encryption logic & Interfaces
│   ├── adapters/   # Slonik, Prisma, Knex integrations
│   └── cli/        # Command-line utilities
├── example/        # Usage demonstrations
├── docs/           # Documentation
└── pnpm-workspace.yaml

📚 Documentation

• 📐 Architecture & Project Spec
• 📅 Roadmap
• 🔒 Security
• ✍️ Contributing
• 🤝 Code of Conduct

📄 License

MIT © 2025 EncoraDB Team