@vollcrypt/db-guard 0.1.0

package/README.md

@@ -0,0 +1,271 @@
+# db-guard
+
+Application-level, field-level encryption integrations for ORMs (Prisma, Mongoose, Drizzle, TypeORM, Diesel, SeaORM) powered by FIPS-compliant cryptography.
+
+`db-guard` secures sensitive database columns (SSN, credit card numbers, addresses, personal data) by encrypting them before they hit the database. It prevents data leakage from compromised database dumps, unauthorized database connections, or compromised database administrators (DBAs).
+
+---
+
+## Key Features
+
+- **Multi-ORM Support**: Integrations for Node.js (Prisma, Mongoose, Drizzle, TypeORM) and Rust (Diesel, SeaORM).
+- **Dynamic Multi-Tenant Routing**: Dynamically resolves distinct KMS keys or database configurations per request context using AsyncLocalStorage.
+- **Secure Key Cache**: Protects memory from dumps using an ephemeral master key generated randomly at boot. Plaint-text DEKs are wrapped with AES-256-KW and cached with automated TTL eviction and zeroization.
+- **Schema Evolution & Crypto-Agility**: Features backward-compatible prefixes for smooth algorithm transitions without database downtime.
+- **M-of-N Break-Glass Protocol**: Emergency KMS bypass via threshold Ed25519 signature verification.
+- **Compliance Scorecard CLI**: Built-in CLI scans configuration and outputs compliance scorecards for GDPR Article 32, KVKK Article 12, and PCI-DSS v4.0.
+- **Supply Chain Security (SLSA Level 4)**: Build pipeline automatically compiles CycloneDX SBOM and SLSA Level 4 Provenance files, cryptographically signed with Ed25519.
+- **FIPS 140-3 & Post-Quantum Hybrid Transition**: Conforms to FIPS 140-3 logical and physical boundaries with NIST FIPS 203 (ML-KEM) lattice-based algorithms registered for hybrid key exchange.
+- **Hardened Blind Indexing**: Allows exact-match querying on encrypted columns via HKDF-SHA256 shadow columns, avoiding frequency analysis vulnerabilities.
+- **RAM Security**: Aggressive memory zeroization (null-byte writing) for keys and plaintext buffers in memory.
+- **Batch Migration CLI**: Built-in CLI tool to perform chunked shadow database migrations in the background.
+
+---
+
+## Installation
+
+For Node.js (Prisma, Mongoose, Drizzle, TypeORM):
+```bash
+npm install @vollcrypt/db-guard
+```
+
+For Rust (Diesel, SeaORM):
+```toml
+# Cargo.toml
+[dependencies]
+vollcrypt-db-guard = { path = "db-guard/rust", features = ["sqlite", "sea-orm"] }
+```
+
+---
+
+## Configuration & Usage
+
+### 1. Prisma ORM (TypeScript)
+
+Register `prismaDbGuard` extension on your client:
+
+```typescript
+import { PrismaClient } from '@prisma/client';
+import { prismaDbGuard } from '@vollcrypt/db-guard';
+
+const key = Buffer.from('your-secure-32-byte-encryption-key-here');
+
+const basePrisma = new PrismaClient();
+export const prisma = basePrisma.$extends(
+  prismaDbGuard({
+    key,
+    models: {
+      User: ['credit_card', 'ssn'],
+    },
+  })
+);
+```
+
+### 2. Mongoose (TypeScript)
+
+Register `mongooseDbGuard` as a schema plugin:
+
+```typescript
+import { Schema, model } from 'mongoose';
+import { mongooseDbGuard } from '@vollcrypt/db-guard';
+
+const key = Buffer.from('your-secure-32-byte-encryption-key-here');
+
+const UserSchema = new Schema({
+  name: String,
+  credit_card: String,
+});
+
+UserSchema.plugin(mongooseDbGuard, {
+  key,
+  fields: ['credit_card'],
+});
+
+export const User = model('User', UserSchema);
+```
+
+### 3. Drizzle ORM (TypeScript)
+
+Use the `createDrizzleGuard` factory to declare encrypted text columns:
+
+```typescript
+import { pgTable, serial } from 'drizzle-orm/pg-core';
+import { createDrizzleGuard } from '@vollcrypt/db-guard';
+
+const guard = createDrizzleGuard({
+  key: Buffer.from('your-secure-32-byte-encryption-key-here'),
+});
+
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  creditCard: guard.pgText('credit_card'), // Automatically encrypted/decrypted
+});
+```
+
+### 4. TypeORM (TypeScript)
+
+Define your entity subscribers using `createTypeOrmSubscriber`:
+
+```typescript
+import { DataSource } from 'typeorm';
+import { createTypeOrmSubscriber } from '@vollcrypt/db-guard';
+
+const key = Buffer.from('your-secure-32-byte-encryption-key-here');
+
+const VollcryptSubscriber = createTypeOrmSubscriber({
+  key,
+  entities: {
+    User: ['credit_card', 'ssn'],
+  },
+});
+
+export const AppDataSource = new DataSource({
+  subscribers: [VollcryptSubscriber],
+});
+```
+
+### 5. Diesel (Rust)
+
+Use `EncryptedString` in your schema and models:
+
+```rust
+use diesel::prelude::*;
+use vollcrypt_db_guard::diesel_impl::EncryptedString;
+
+#[derive(Queryable, Selectable, Insertable)]
+#[diesel(table_name = users)]
+pub struct User {
+    pub id: i32,
+    pub name: String,
+    pub credit_card: EncryptedString,
+}
+```
+
+### 6. SeaORM (Rust)
+
+Use the SeaORM-compatible `EncryptedString` type wrapper:
+
+```rust
+use sea_orm::entity::prelude::*;
+use vollcrypt_db_guard::seaorm_impl::EncryptedString;
+
+#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
+#[sea_orm(table_name = "users")]
+pub struct Model {
+    #[sea_orm(primary_key)]
+    pub id: i32,
+    pub name: String,
+    pub credit_card: EncryptedString,
+}
+```
+
+Initialize your keys at application boot for Rust:
+```rust
+use vollcrypt_db_guard::{set_key, set_active_version};
+
+fn main() {
+    let key = [0u8; 32]; // Secure 32-byte key
+    set_key("1", &key);
+    set_active_version("1").unwrap();
+}
+```
+
+---
+
+## Cloud & On-Premises KMS Providers
+
+`db-guard` supports multiple key management systems (KMS) and hardware security modules (HSM) to resolve keys dynamically for envelope encryption.
+
+### 1. Node.js KMS Providers
+
+We provide several KmsProvider implementations:
+
+- **AwsKmsProvider**: Resolves keys using AWS KMS.
+- **GcpKmsProvider**: Resolves keys using Google Cloud KMS.
+- **VaultKmsProvider**: Resolves keys using HashiCorp Vault.
+- **Pkcs11KmsProvider**: Interacts with physical or virtual HSMs (YubiHSM2, Thales, Nitrokey, SoftHSM2, etc.) using the standard PKCS#11 protocol.
+
+#### Node.js PKCS#11 Configuration Example:
+```typescript
+import { Pkcs11KmsProvider } from '@vollcrypt/db-guard';
+
+const kmsProvider = new Pkcs11KmsProvider({
+  libraryPath: '/usr/local/lib/softhsm/libsofthsm2.so', // Path to vendor PKCS#11 library
+  pin: '123456',                                      // Slot/Token PIN
+  slotId: 0,                                          // Target Slot Index (optional, default: 0)
+  keyId: '000102',                                    // Hex-encoded CKA_ID of the AES-256 key in HSM
+});
+
+// Decrypt wrapped key (DEK) inside HSM
+const decryptedKey = await kmsProvider.decrypt(wrappedKeyBuffer);
+```
+
+### 2. Rust PKCS#11 Support
+
+To use PKCS#11 in Rust, enable the `pkcs11` feature:
+```toml
+# Cargo.toml
+[dependencies]
+vollcrypt-db-guard = { path = "db-guard/rust", features = ["sqlite", "pkcs11"] }
+```
+
+You can then decrypt wrapped keys directly inside your HSM:
+```rust
+use vollcrypt_db_guard::pkcs11_impl::decrypt_with_hsm;
+
+let decrypted = decrypt_with_hsm(
+    "/usr/local/lib/softhsm/libsofthsm2.so", // Path to PKCS#11 module
+    "123456",                               // PIN
+    Some(0),                                // Slot ID
+    "010203",                               // Hex CKA_ID
+    &wrapped_data,                          // Ciphertext containing wrapped DEK
+).unwrap();
+```
+
+---
+
+## CLI Commands
+
+The package includes a dual-purpose CLI tool for database migrations and compliance auditing.
+
+### 1. Database Migrations (`migrate`)
+Encrypts existing plaintext records in a live database using batch processing:
+
+```bash
+# Run PostgreSQL migration
+npx vollcrypt-db-guard migrate \
+  --db-type postgres \
+  --db-url "postgres://user:pass@localhost:5432/db" \
+  --table users \
+  --column credit_card \
+  --key "your_32_byte_hex_key_here" \
+  --chunk-size 100 \
+  --id-col id
+
+# Run MongoDB migration
+npx vollcrypt-db-guard migrate \
+  --db-type mongodb \
+  --db-url "mongodb://localhost:27017/db" \
+  --table users \
+  --column credit_card \
+  --key "your_32_byte_hex_key_here" \
+  --chunk-size 100 \
+  --id-col _id
+```
+
+### 2. Compliance Scorecard Generator (`compliance`)
+Scans cryptographic configurations and generates an auditor-ready HTML compliance report:
+
+```bash
+npx vollcrypt-db-guard compliance \
+  --config compliance-config.json \
+  --output compliance-report.html
+```
+
+---
+
+## Supply Chain & Compliance Verification
+
+Refer to the following standalone validation documentation for formal verification processes:
+- **Supply Chain Artifacts**: Signed CycloneDX SBOM and SLSA Level 4 Provenance are located in `dist/sbom.json` and `dist/provenance.json` post-build.
+- **FIPS 140-3 Boundaries**: Detailed logical boundaries, Approved algorithm registries, and post-quantum hybrid structures are defined in [FIPS_VALIDATION.md](file:///c:/Users/iTopya/Desktop/Project/vollcrypt/db-guard/FIPS_VALIDATION.md).

package/compliance-config.json

@@ -0,0 +1,39 @@
+{
+  "kms": {
+    "provider": "aws",
+    "wrappedKey": "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f",
+    "wrappedKek": "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f",
+    "activeKeyVersion": "1"
+  },
+  "models": {
+    "User": ["email", "credit_card"]
+  },
+  "blindIndexes": {
+    "rootSalt": "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f",
+    "models": {
+      "User": ["email"]
+    }
+  },
+  "cryptoRbac": {
+    "roles": {
+      "ADMIN": {
+        "decrypt": ["User.email", "User.credit_card"]
+      },
+      "SUPPORT": {
+        "decrypt": [],
+        "mask": {
+          "User.credit_card": "credit_card"
+        }
+      }
+    }
+  },
+  "rateLimiter": {
+    "maxDecryptionsPerSecond": 100,
+    "mode": "fail_closed",
+    "maxPageSize": 100,
+    "onPageSizeExceeded": "error"
+  },
+  "breakGlassThreshold": 2,
+  "breakGlassPublicKeys": ["2be3f91a7b204d104b60d3ce756b7555f7c7c437f1470b826d03c877b9349dd8", "1234f91a7b204d104b60d3ce756b7555f7c7c437f1470b826d03c877b9349dd8"],
+  "postQuantumEnabled": true
+}

package/dist/blind-index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Computes a hardened, frequency-resistant blind index for a database field.
+ *
+ * Uses HKDF-SHA256 to derive a unique column key from the root salt,
+ * preventing cross-column frequency analysis. Zeroizes intermediate keys immediately.
+ */
+export declare function computeBlindIndex(value: any, rootSalt: Buffer, columnName: string): string;

package/dist/blind-index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeBlindIndex = computeBlindIndex;
+const security_1 = require("./security");
+/**
+ * Computes a hardened, frequency-resistant blind index for a database field.
+ *
+ * Uses HKDF-SHA256 to derive a unique column key from the root salt,
+ * preventing cross-column frequency analysis. Zeroizes intermediate keys immediately.
+ */
+function computeBlindIndex(value, rootSalt, columnName) {
+    if (value === null || value === undefined)
+        return value;
+    const plaintext = typeof value === 'string' ? value : JSON.stringify(value);
+    const columnNameBuf = Buffer.from(columnName, 'utf8');
+    // 1. Derive column-specific key using HKDF-SHA256
+    const derivedColumnKey = (0, security_1.deriveHkdf)(rootSalt, null, columnNameBuf, 32);
+    // 2. Compute the final blind index using the derived column key
+    const plaintextBuf = Buffer.from(plaintext, 'utf8');
+    const blindIndex = (0, security_1.deriveHkdf)(derivedColumnKey, null, plaintextBuf, 32);
+    // 3. RAM Security: Zeroize the derived key immediately (Anti-Core Dump)
+    derivedColumnKey.fill(0);
+    return blindIndex.toString('hex');
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const prisma_1 = require("./prisma");
+function printProgressBar(current, total) {
+    const percentage = Math.min(100, Math.floor((current / total) * 100));
+    const barLength = 40;
+    const completedLength = Math.floor((percentage / 100) * barLength);
+    const remainingLength = barLength - completedLength;
+    const progressBar = '='.repeat(completedLength) + '>'.repeat(completedLength > 0 && remainingLength > 0 ? 1 : 0) + ' '.repeat(Math.max(0, remainingLength - (completedLength > 0 && remainingLength > 0 ? 1 : 0)));
+    process.stdout.write(`\rProgress: [${progressBar}] ${percentage}% (${current}/${total} records)`);
+}
+async function run() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || (args[0] !== 'migrate' && args[0] !== 'compliance')) {
+        console.error("Usage: vollcrypt-db-guard <command> [options]");
+        console.error("\nCommands:");
+        console.error("  migrate       Run shadow database migrations");
+        console.error("  compliance    Scan database configurations and generate a compliance HTML scorecard");
+        console.error("\nMigrate Options:");
+        console.error("  --db-type <postgres|mongodb>  Database type");
+        console.error("  --db-url <url>                Database connection URL");
+        console.error("  --table <table-name>          Table/collection name to migrate");
+        console.error("  --column <column-name>        Column/field name to encrypt");
+        console.error("  --key <32-byte-hex-key>       Encryption key (hex-encoded)");
+        console.error("  --active-version <version>    Encryption key version (default: 1)");
+        console.error("  --chunk-size <size>           Batch processing chunk size (default: 100)");
+        console.error("  --id-col <id-col-name>        Primary key column (default: 'id' / '_id')");
+        console.error("\nCompliance Options:");
+        console.error("  --config <path-to-json-file>  Path to configuration file");
+        console.error("  --output <output-html-path>   Path to write HTML compliance report (default: compliance-report.html)");
+        process.exit(1);
+    }
+    if (args[0] === 'compliance') {
+        const options = {};
+        for (let i = 1; i < args.length; i += 2) {
+            if (args[i] && args[i + 1]) {
+                const key = args[i].replace(/^--/, '');
+                const val = args[i + 1];
+                options[key] = val;
+            }
+        }
+        const configPath = options['config'];
+        const outputPath = options['output'] || 'compliance-report.html';
+        if (!configPath) {
+            console.error("Error: --config <path-to-json-file> is required for compliance scan.");
+            process.exit(1);
+        }
+        const fs = require('fs');
+        const path = require('path');
+        try {
+            const fullPath = path.resolve(configPath);
+            if (!fs.existsSync(fullPath)) {
+                console.error(`Error: Configuration file not found at ${fullPath}`);
+                process.exit(1);
+            }
+            const raw = fs.readFileSync(fullPath, 'utf8');
+            const config = JSON.parse(raw);
+            const { generateComplianceHtmlReport } = require('./compliance');
+            const html = generateComplianceHtmlReport(config);
+            const outFullPath = path.resolve(outputPath);
+            fs.writeFileSync(outFullPath, html, 'utf8');
+            console.log(`Compliance report generated successfully at ${outFullPath}`);
+        }
+        catch (err) {
+            console.error(`Error generating compliance report: ${err.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // Parse arguments
+    const options = {};
+    for (let i = 1; i < args.length; i += 2) {
+        if (args[i] && args[i + 1]) {
+            const key = args[i].replace(/^--/, '');
+            const val = args[i + 1];
+            options[key] = val;
+        }
+    }
+    const dbType = options['db-type'];
+    const dbUrl = options['db-url'];
+    const table = options['table'] || options['collection'];
+    const column = options['column'];
+    const keyHex = options['key'];
+    const activeVersion = options['active-version'] || '1';
+    const chunkSize = parseInt(options['chunk-size'] || '100', 10);
+    const idCol = options['id-col'] || (dbType === 'mongodb' ? '_id' : 'id');
+    if (!dbType || !dbUrl || !table || !column || !keyHex) {
+        console.error("Error: Missing required arguments. --db-type, --db-url, --table, --column, and --key are required.");
+        process.exit(1);
+    }
+    if (keyHex.length !== 64) {
+        console.error("Error: Key must be a 32-byte hex-encoded string (64 characters).");
+        process.exit(1);
+    }
+    const encryptionKey = Buffer.from(keyHex, 'hex');
+    console.log(`Starting shadow migration on: table/collection: "${table}", column: "${column}"`);
+    console.log(`Active key version: "${activeVersion}", Batch size: ${chunkSize}`);
+    if (dbType === 'postgres') {
+        await migratePostgres(dbUrl, table, column, idCol, encryptionKey, activeVersion, chunkSize);
+    }
+    else if (dbType === 'mongodb') {
+        await migrateMongo(dbUrl, table, column, idCol, encryptionKey, activeVersion, chunkSize);
+    }
+    else {
+        console.error(`Error: Unsupported db-type "${dbType}". Supported: postgres, mongodb.`);
+        process.exit(1);
+    }
+}
+async function migratePostgres(url, table, column, idCol, key, version, chunkSize) {
+    let Client;
+    try {
+        Client = require('pg').Client;
+    }
+    catch (err) {
+        console.error("Error: The 'pg' package is not installed. Please install 'pg' to run migrations on PostgreSQL.");
+        process.exit(1);
+    }
+    const client = new Client({ connectionString: url });
+    await client.connect();
+    try {
+        // 1. Count unencrypted rows (value doesn't start with VOLLVALT:)
+        const countRes = await client.query(`SELECT COUNT(*) FROM "${table}" WHERE "${column}" IS NOT NULL AND "${column}" NOT LIKE 'VOLLVALT:%'`);
+        const total = parseInt(countRes.rows[0].count, 10);
+        if (total === 0) {
+            console.log("No unencrypted records found. Migration complete!");
+            return;
+        }
+        console.log(`Found ${total} unencrypted records. Processing...`);
+        let processed = 0;
+        printProgressBar(processed, total);
+        while (true) {
+            // 2. Fetch a batch of unencrypted rows
+            const batchRes = await client.query(`SELECT "${idCol}", "${column}" FROM "${table}" WHERE "${column}" IS NOT NULL AND "${column}" NOT LIKE 'VOLLVALT:%' LIMIT $1`, [chunkSize]);
+            if (batchRes.rows.length === 0) {
+                break;
+            }
+            // 3. Encrypt and update each row
+            for (const row of batchRes.rows) {
+                const rawVal = row[column];
+                const encryptedVal = (0, prisma_1.encryptValue)(rawVal, key, version);
+                await client.query(`UPDATE "${table}" SET "${column}" = $1 WHERE "${idCol}" = $2`, [encryptedVal, row[idCol]]);
+                processed++;
+                printProgressBar(processed, total);
+            }
+        }
+        console.log(`\nSuccessfully migrated ${processed} records!`);
+    }
+    catch (err) {
+        console.error(`\nMigration failed: ${err.message}`);
+    }
+    finally {
+        await client.end();
+    }
+}
+async function migrateMongo(url, collectionName, field, idCol, key, version, chunkSize) {
+    let MongoClient;
+    try {
+        MongoClient = require('mongodb').MongoClient;
+    }
+    catch (err) {
+        console.error("Error: The 'mongodb' package is not installed. Please install 'mongodb' to run migrations on MongoDB.");
+        process.exit(1);
+    }
+    const client = new MongoClient(url);
+    await client.connect();
+    try {
+        const db = client.db();
+        const collection = db.collection(collectionName);
+        // Filter to find docs where field exists, is not null, and doesn't start with VOLLVALT:
+        const filter = {
+            [field]: {
+                $exists: true,
+                $ne: null,
+                $not: /^VOLLVALT:/
+            }
+        };
+        const total = await collection.countDocuments(filter);
+        if (total === 0) {
+            console.log("No unencrypted records found. Migration complete!");
+            return;
+        }
+        console.log(`Found ${total} unencrypted records. Processing...`);
+        let processed = 0;
+        printProgressBar(processed, total);
+        while (true) {
+            const batch = await collection.find(filter).limit(chunkSize).toArray();
+            if (batch.length === 0) {
+                break;
+            }
+            for (const doc of batch) {
+                const rawVal = doc[field];
+                const encryptedVal = (0, prisma_1.encryptValue)(rawVal, key, version);
+                await collection.updateOne({ [idCol]: doc[idCol] }, { $set: { [field]: encryptedVal } });
+                processed++;
+                printProgressBar(processed, total);
+            }
+        }
+        console.log(`\nSuccessfully migrated ${processed} records!`);
+    }
+    catch (err) {
+        console.error(`\nMigration failed: ${err.message}`);
+    }
+    finally {
+        await client.close();
+    }
+}
+run().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});