EncoraDB is designed to be a secure, transparent encryption layer for your database. This document outlines our cryptographic standards, threat model, and best practices for secure usage.

We rely on standard, well-tested algorithms provided by the Node.js crypto module (via OpenSSL). We do not roll our own crypto.

• Cipher: AES-256-GCM (Galois/Counter Mode)
• Key Size: 256-bit (32 bytes)
• IV Size: 96-bit (12 bytes), randomly generated for every single write.
• Auth Tag: 128-bit (16 bytes), appended to ciphertext to ensure integrity.

We do not use the Master Key directly to encrypt data. Instead, we derive a unique sub-key for every table column using HKDF-SHA256.

• Master Key: 32-byte secret (User provided)
• Info/Context: EncoraDB v1
• Salt: table_name:column_name (e.g., users:email)

This ensures that even if a key for one column is theoretically analyzed or compromised, keys for other columns remain secure.

Encrypted data is stored as a base64-encoded string with a prefix for identification:

enc:gcm:<iv_base64>:<auth_tag_base64>:<ciphertext_base64>

Your Master Key is the root of trust. If lost, data is irretrievable. If stolen, data is compromised.

NEVER commit your Master Key to version control.

// ❌ WRONG
const encora = new EncoraDB({ masterKey: "8f4b..." });

// ✅ CORRECT: Load from Environment
const encora = new EncoraDB({ masterKey: process.env.ENCORA_MASTER_KEY });

For production environments, we strongly recommend using our envelope encryption mode with a Key Management Service (AWS KMS, etc.). This ensures the Master Key is never resident in your application configuration in plaintext, but is instead decrypted on-the-fly or used to unwrap Data Encryption Keys.

Rotate your keys periodically or immediately after a suspected breach. Use the CLI command:

encoradb rotate-keys --old-key <old> --new-key <new>

Note: We recommend backing up your database before performing rotation.

• Database Dump / Theft: An attacker managing to pg_dump or reading the raw database files will only see encrypted ciphertext for sensitive columns.
• SQL Injection: Even if an attacker can SELECT *, they receive encrypted strings (unless the application decrypts it for them).
• Accidental Logging: If raw database rows are logged by DB tools, sensitive fields remain encrypted.

• Application Compromise: If an attacker gains RCE (Remote Code Execution) on your Node.js server, they have access to the memory and the Environment Variables (likely including the Master Key).
• End-Device Compromise: If a user's laptop is stolen while logged in, the application has already decrypted the data for them.

EncoraDB includes built-in hooks for Audit Logging. Every encryption and decryption attempt (successful or failed) is logged.

To satisfy SOC2 / HIPAA requirements:

1. Configure a custom auditLogger in EncoraDB.
2. Pipe these logs to an immutable store (e.g., CloudWatch, Datadog logs, or Splunk).

const encora = new EncoraDB({
  // ...
  auditLogger: {
    log: async (event) => {
      // Send to centralized logging
      await splunk.send(event);
    }
  }
})

Events Logged:

• ENCRYPT / DECRYPT action
• Table and Column name
• Success / Failure status
• Timestamp
• Note: We strongly advise AGAINST logging the actual Data Payload.

If you have found a security vulnerability in EncoraDB, please do not open a public issue.

Contact us directly at: security@encoradb.com (or specific contact method)

We will assess the issue and provide a fix as soon as possible.