outlet-orm 5.5.3 → 6.5.0

package/README.md

@@ -86,8 +86,9 @@ my-project/
 ├── database/
 │   ├── config.js                 # Config migrations (outlet-init)
 │   ├── migrations/               # Migration files
-│   └── seeds/                    # Test/demo data
-│       └── UserSeeder.js
+│   ├── seeds/                    # Test/demo data
+│   │   └── UserSeeder.js
+│   └── backups/                  # 🗄️ Backup files (full / partial / journal)
 │
 ├── public/                       # ✅ Public static files
 │   ├── images/
@@ -195,6 +196,7 @@ async store(req, res) {
 - **Ergonomic aliases**: `columns([...])`, `ordrer()` (typo alias for `orderBy`)
 - **Raw queries**: `executeRawQuery()` and `execute()` (native driver results)
 - **Complete Migrations** (create/alter/drop, index, foreign keys, batch tracking)
+- **Database Backup** (v6.0.0): full/partial/journal backups, recurring scheduler, AES-256-GCM encryption, TCP daemon + remote client, automatic restore
 - **Handy CLI tools**: `outlet-init`, `outlet-migrate`, `outlet-convert`
 - **`.env` configuration** (loaded automatically)
 - **Multi-database**: MySQL, PostgreSQL, and SQLite

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outlet-orm",
-  "version": "5.5.3",
+  "version": "6.5.0",
   "description": "A Laravel Eloquent-inspired ORM for Node.js with support for MySQL, PostgreSQL, and SQLite",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/Backup/BackupEncryption.js

@@ -0,0 +1,153 @@
+/**
+ * BackupEncryption
+ *
+ * AES-256-GCM encryption/decryption for backup files.
+ * Uses only Node.js built-in `crypto` – zero external dependencies.
+ *
+ * Grain de sable (salt) concept:
+ *   A random alphanumeric salt of 4–6 characters is generated for every
+ *   encryption operation.  The salt is stored in plain text inside the
+ *   encrypted file header so that decryption can always reconstruct the
+ *   exact key that was used without storing the salt separately.
+ *
+ * Encrypted file format (UTF-8 text):
+ *   Line 1 : OUTLET_ENC_V1          – magic / version marker
+ *   Line 2 : <salt>                 – 4–6 alphanumeric chars (grain de sable)
+ *   Line 3 : <iv_hex>               – 24-char hex (12-byte IV for GCM)
+ *   Line 4 : <authTag_hex>          – 32-char hex (16-byte GCM auth tag)
+ *   Line 5 : <ciphertext_base64>    – base64-encoded encrypted content
+ *
+ * Key derivation: scryptSync(password, salt, 32)
+ *   N=16384, r=8, p=1 (scrypt defaults – safe for interactive use)
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+const MAGIC = 'OUTLET_ENC_V1';
+const IV_LENGTH = 12;          // bytes – GCM recommended
+const SALT_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Generate a random alphanumeric salt (grain de sable).
+ * @param {number} length  4 to 6 (inclusive)
+ * @returns {string}
+ */
+function generateSalt(length = 6) {
+  if (length < 4 || length > 6) {
+    throw new RangeError(`BackupEncryption: saltLength must be between 4 and 6 (got ${length})`);
+  }
+  const bytes = crypto.randomBytes(length);
+  return Array.from(bytes)
+    .map((b) => SALT_CHARS[b % SALT_CHARS.length])
+    .join('');
+}
+
+/**
+ * Derive a 256-bit key from a password and a salt using scrypt.
+ * @param {string} password
+ * @param {string} salt
+ * @returns {Buffer}
+ */
+function deriveKey(password, salt) {
+  return crypto.scryptSync(password, salt, 32, { N: 16384, r: 8, p: 1 });
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Encrypt a string payload (backup content).
+ *
+ * @param {string} plaintext      The content to encrypt (SQL / JSON string)
+ * @param {string} password       User-supplied encryption password
+ * @param {number} [saltLength=6] Grain de sable length (4–6 characters)
+ * @returns {{ encryptedContent: string, salt: string }}
+ *   `encryptedContent` is the full file payload ready to write to disk.
+ *   `salt` is exposed so callers can log / audit the grain de sable used.
+ */
+function encrypt(plaintext, password, saltLength = 6) {
+  if (!password || typeof password !== 'string') {
+    throw new TypeError('BackupEncryption.encrypt: password must be a non-empty string');
+  }
+
+  const salt = generateSalt(saltLength);
+  const key  = deriveKey(password, salt);
+  const iv   = crypto.randomBytes(IV_LENGTH);
+
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, 'utf8'),
+    cipher.final()
+  ]);
+  const authTag = cipher.getAuthTag();
+
+  const encryptedContent = [
+    MAGIC,
+    salt,
+    iv.toString('hex'),
+    authTag.toString('hex'),
+    encrypted.toString('base64')
+  ].join('\n');
+
+  return { encryptedContent, salt };
+}
+
+/**
+ * Decrypt a previously encrypted backup payload.
+ *
+ * @param {string} encryptedContent  The raw file content (as written by encrypt())
+ * @param {string} password          The same password used during encryption
+ * @returns {string}  The original plaintext
+ * @throws  If the format is invalid, the password is wrong, or the auth tag fails
+ */
+function decrypt(encryptedContent, password) {
+  if (!password || typeof password !== 'string') {
+    throw new TypeError('BackupEncryption.decrypt: password must be a non-empty string');
+  }
+
+  const lines = encryptedContent.split('\n');
+
+  if (lines.length < 5 || lines[0] !== MAGIC) {
+    throw new Error('BackupEncryption.decrypt: invalid or unrecognised encrypted backup format');
+  }
+
+  const [, salt, ivHex, tagHex, ciphertextB64] = lines;
+
+  // Validate salt length (defensive)
+  if (salt.length < 4 || salt.length > 6) {
+    throw new Error(`BackupEncryption.decrypt: unexpected salt length (${salt.length})`);
+  }
+
+  const key        = deriveKey(password, salt);
+  const iv         = Buffer.from(ivHex, 'hex');
+  const authTag    = Buffer.from(tagHex, 'hex');
+  const ciphertext = Buffer.from(ciphertextB64, 'base64');
+
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(authTag);
+
+  try {
+    const decrypted = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final()
+    ]);
+    return decrypted.toString('utf8');
+  } catch (_) {
+    throw new Error('BackupEncryption.decrypt: authentication failed – wrong password or corrupted data');
+  }
+}
+
+/**
+ * Return true if the content looks like an outlet-orm encrypted backup.
+ * @param {string} content
+ * @returns {boolean}
+ */
+function isEncrypted(content) {
+  return typeof content === 'string' && content.startsWith(MAGIC + '\n');
+}
+
+module.exports = { encrypt, decrypt, isEncrypted, generateSalt };

package/src/Backup/BackupManager.js

@@ -0,0 +1,422 @@
+/**
+ * BackupManager
+ *
+ * Provides programmatic backup capabilities for outlet-orm:
+ *   - full     : complete schema + data dump
+ *   - partial  : selected tables only
+ *   - journal  : transaction log replay (INSERT / UPDATE / DELETE captured via query log)
+ *
+ * Supports MySQL, PostgreSQL, and SQLite drivers.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const fsPromises = require('fs').promises;
+const path = require('path');
+const DatabaseConnection = require('../DatabaseConnection');
+const { encrypt, decrypt, isEncrypted } = require('./BackupEncryption');
+
+// DML keywords captured for transaction-log backups
+const DML_REGEX = /^\s*(INSERT|UPDATE|DELETE|REPLACE)\s+/i;
+
+/**
+ * Escape a SQL identifier (table / column name).
+ * @param {string} name
+ * @param {string} driver  'mysql' | 'postgres' | 'sqlite'
+ * @returns {string}
+ */
+function quoteIdentifier(name, driver) {
+  if (driver === 'mysql') return `\`${name.replace(/`/g, '``')}\``;
+  return `"${name.replace(/"/g, '""')}"`;   // postgres / sqlite
+}
+
+/**
+ * Quote a scalar value for use in a SQL dump statement.
+ * @param {*} val
+ * @returns {string}
+ */
+function quoteValue(val) {
+  if (val === null || val === undefined) return 'NULL';
+  if (typeof val === 'number' || typeof val === 'boolean') return String(val);
+  // Escape single quotes
+  return `'${String(val).replace(/'/g, "''")}'`;
+}
+
+/**
+ * Generate a human-readable timestamp suitable for filenames.
+ * @returns {string}  e.g. "20260226_143022"
+ */
+function timestamp() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+class BackupManager {
+  /**
+   * @param {DatabaseConnection} connection
+   * @param {object}  [options]
+   * @param {string}  [options.backupPath='./database/backups']  Directory for backup files
+   * @param {boolean} [options.encrypt=false]      Encrypt backup files with AES-256-GCM
+   * @param {string}  [options.encryptionPassword] Password used for encryption / decryption
+   * @param {number}  [options.saltLength=6]       Grain de sable length – 4, 5 or 6 characters
+   */
+  constructor(connection, options = {}) {
+    if (!(connection instanceof DatabaseConnection)) {
+      throw new TypeError('BackupManager requires a DatabaseConnection instance');
+    }
+    this.connection = connection;
+    this.backupPath = path.resolve(
+      process.cwd(),
+      options.backupPath || './database/backups'
+    );
+
+    // Encryption settings
+    this._encryptEnabled  = Boolean(options.encrypt);
+    this._encryptPassword = options.encryptionPassword || null;
+    this._saltLength      = options.saltLength != null ? options.saltLength : 6;
+
+    if (this._encryptEnabled && !this._encryptPassword) {
+      throw new Error('BackupManager: encryptionPassword is required when encrypt=true');
+    }
+    if (this._saltLength < 4 || this._saltLength > 6) {
+      throw new RangeError(`BackupManager: saltLength must be between 4 and 6 (got ${this._saltLength})`);
+    }
+
+    this._ensureBackupDir();
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Public API
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Full backup – dumps schema (CREATE TABLE) + data (INSERT) for every user table.
+   *
+   * @param {object}  [options]
+   * @param {string}  [options.filename]   Override the generated filename
+   * @param {string}  [options.format='sql']  'sql' | 'json'
+   * @returns {Promise<string>}  Absolute path of the written backup file
+   */
+  async full(options = {}) {
+    const tables = await this._listTables();
+    return this._dumpTables(tables, 'full', options);
+  }
+
+  /**
+   * Partial backup – dumps schema + data for the specified tables only.
+   *
+   * @param {string[]} tables  Table names to include
+   * @param {object}   [options]
+   * @param {string}   [options.filename]
+   * @param {string}   [options.format='sql']  'sql' | 'json'
+   * @returns {Promise<string>}  Absolute path of the written backup file
+   */
+  async partial(tables, options = {}) {
+    if (!Array.isArray(tables) || tables.length === 0) {
+      throw new Error('BackupManager.partial() requires a non-empty array of table names');
+    }
+    return this._dumpTables(tables, 'partial', options);
+  }
+
+  /**
+   * Transaction-log backup – captures DML statements (INSERT / UPDATE / DELETE)
+   * from the DatabaseConnection query log and writes them as a replayable SQL script.
+   *
+   * ⚠️  Requires query logging to be enabled BEFORE the operations you want to record:
+   *     DatabaseConnection.enableQueryLog()
+   *
+   * @param {object}  [options]
+   * @param {string}  [options.filename]
+   * @param {boolean} [options.flush=false]  Clear the query log after writing the journal
+   * @returns {Promise<string>}  Absolute path of the written journal file
+   */
+  async journal(options = {}) {
+    const log = DatabaseConnection.getQueryLog();
+    // Filter to DML statements only
+    const dmlEntries = log.filter((entry) => DML_REGEX.test(entry.sql));
+
+    const driver = this.connection.driver;
+    const filename = options.filename || `journal_${timestamp()}.sql`;
+    const filePath = path.join(this.backupPath, filename);
+
+    const header = this._sqlHeader('transaction-log journal');
+    const lines = [header];
+
+    for (const entry of dmlEntries) {
+      const ts = entry.timestamp ? entry.timestamp.toISOString() : '';
+      lines.push(`-- ${ts}  (${entry.duration}ms)`);
+      // Re-inject bound parameters into the SQL for a replayable statement
+      const replayable = this._injectParams(entry.sql, entry.params, driver);
+      lines.push(replayable + ';');
+    }
+
+    lines.push(`-- end of journal (${dmlEntries.length} statement(s))`);
+
+    // Apply encryption-aware filename
+    const resolvedPath = (this._encryptEnabled && !filePath.endsWith('.enc'))
+      ? filePath + '.enc'
+      : filePath;
+
+    await this._writeContent(resolvedPath, lines.join('\n'));
+
+    if (options.flush) {
+      DatabaseConnection.flushQueryLog();
+    }
+
+    console.log(`✓ Transaction-log backup written: ${resolvedPath} (${dmlEntries.length} statement(s))`);
+    return resolvedPath;
+  }
+
+  /**
+   * Restore a previously created SQL backup file.
+   * The file is executed statement-by-statement inside a transaction.
+   *
+   * @param {string} filePath  Absolute or relative path to the .sql backup file
+   * @returns {Promise<{ statements: number }>}
+   */
+  async restore(filePath, options = {}) {
+    const absolute = path.resolve(process.cwd(), filePath);
+    let content = await fsPromises.readFile(absolute, 'utf8');
+
+    // Decrypt if necessary
+    if (isEncrypted(content)) {
+      const password = options.encryptionPassword || this._encryptPassword;
+      if (!password) {
+        throw new Error('BackupManager.restore: file is encrypted – provide encryptionPassword');
+      }
+      content = decrypt(content, password);
+    }
+
+    // Split on semicolon, ignore comment-only or empty chunks
+    const statements = content
+      .split(';')
+      .map((s) => s.trim())
+      .filter((s) => s && !s.startsWith('--'));
+
+    let count = 0;
+    await this.connection.transaction(async () => {
+      for (const sql of statements) {
+        await this.connection.execute(sql);
+        count++;
+      }
+    });
+
+    console.log(`✓ Restore complete: ${count} statement(s) executed from ${absolute}`);
+    return { statements: count };
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Private helpers
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Dump a list of tables in the chosen format.
+   * @private
+   */
+  async _dumpTables(tables, label, options) {
+    const format = (options.format || 'sql').toLowerCase();
+    const ext = format === 'json' ? 'json' : 'sql';
+    const baseExt = this._encryptEnabled ? `${ext}.enc` : ext;
+    const filename = options.filename
+      ? (this._encryptEnabled && !options.filename.endsWith('.enc') ? options.filename + '.enc' : options.filename)
+      : `${label}_${timestamp()}.${baseExt}`;
+    const filePath = path.join(this.backupPath, filename);
+
+    if (format === 'json') {
+      await this._dumpJSON(tables, filePath);
+    } else {
+      await this._dumpSQL(tables, filePath, label);
+    }
+
+    console.log(`✓ ${label.charAt(0).toUpperCase() + label.slice(1)} backup written: ${filePath}`);
+    return filePath;
+  }
+
+  /**
+   * Write a SQL dump (CREATE TABLE + INSERT INTO).
+   * @private
+   */
+  async _dumpSQL(tables, filePath, label) {
+    const driver = this.connection.driver;
+    const lines = [this._sqlHeader(label)];
+
+    for (const table of tables) {
+      lines.push(`\n-- Table: ${table}`);
+      lines.push(`-- -----------------------------------------------------------`);
+
+      // Schema
+      const createSql = await this._getCreateTable(table);
+      if (createSql) {
+        lines.push(createSql + ';');
+      }
+
+      // Data
+      const rows = await this.connection.executeRawQuery(`SELECT * FROM ${quoteIdentifier(table, driver)}`);
+      if (rows.length > 0) {
+        const columns = Object.keys(rows[0]).map((c) => quoteIdentifier(c, driver)).join(', ');
+        for (const row of rows) {
+          const values = Object.values(row).map(quoteValue).join(', ');
+          lines.push(`INSERT INTO ${quoteIdentifier(table, driver)} (${columns}) VALUES (${values});`);
+        }
+      }
+    }
+
+    lines.push('\n-- End of backup');
+    await this._writeContent(filePath, lines.join('\n'));
+  }
+
+  /**
+   * Write a JSON dump { table: rows[] }.
+   * @private
+   */
+  async _dumpJSON(tables, filePath) {
+    const driver = this.connection.driver;
+    const dump = { generatedAt: new Date().toISOString(), tables: {} };
+
+    for (const table of tables) {
+      const rows = await this.connection.executeRawQuery(`SELECT * FROM ${quoteIdentifier(table, driver)}`);
+      dump.tables[table] = rows;
+    }
+
+    await this._writeContent(filePath, JSON.stringify(dump, null, 2));
+  }
+
+  /**
+   * List all user tables from the connected database.
+   * @private
+   * @returns {Promise<string[]>}
+   */
+  async _listTables() {
+    const driver = this.connection.driver;
+    let rows;
+
+    switch (driver) {
+    case 'mysql':
+      rows = await this.connection.executeRawQuery(
+        'SELECT table_name AS name FROM information_schema.tables WHERE table_schema = DATABASE() AND table_type = \'BASE TABLE\' ORDER BY table_name'
+      );
+      return rows.map((r) => r.name || r.TABLE_NAME);
+
+    case 'postgres':
+    case 'postgresql':
+      rows = await this.connection.executeRawQuery(
+        "SELECT tablename AS name FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename"
+      );
+      return rows.map((r) => r.name);
+
+    case 'sqlite':
+      rows = await this.connection.executeRawQuery(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+      );
+      return rows.map((r) => r.name);
+
+    default:
+      throw new Error(`BackupManager: unsupported driver "${driver}"`);
+    }
+  }
+
+  /**
+   * Retrieve the CREATE TABLE statement for a given table.
+   * Returns null if not available for the current driver.
+   * @private
+   * @returns {Promise<string|null>}
+   */
+  async _getCreateTable(table) {
+    const driver = this.connection.driver;
+
+    try {
+      switch (driver) {
+      case 'mysql': {
+        const rows = await this.connection.executeRawQuery(`SHOW CREATE TABLE ${quoteIdentifier(table, driver)}`);
+        return rows[0]?.['Create Table'] || null;
+      }
+      case 'sqlite': {
+        const rows = await this.connection.executeRawQuery(
+          'SELECT sql FROM sqlite_master WHERE type=\'table\' AND name=?',
+          [table]
+        );
+        return rows[0]?.sql || null;
+      }
+      case 'postgres':
+      case 'postgresql':
+        // PostgreSQL does not expose a single-row SHOW CREATE TABLE.
+        // Returning null; the INSERT statements are still written.
+        return null;
+      default:
+        return null;
+      }
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /**
+   * Rebuild a replayable SQL statement by injecting bound parameters.
+   * This is intentionally simple – values are quoted but not re-parameterized,
+   * so the result is a human-readable / replayable script rather than a prepared
+   * statement.
+   * @private
+   */
+  _injectParams(sql, params, driver) {
+    if (!params || params.length === 0) return sql;
+
+    // Replace ? placeholders (MySQL/SQLite) or $1..$N placeholders (PostgreSQL)
+    if (driver === 'postgres' || driver === 'postgresql') {
+      let out = sql;
+      for (let i = 0; i < params.length; i++) {
+        out = out.replace(`$${i + 1}`, quoteValue(params[i]));
+      }
+      return out;
+    }
+
+    // MySQL / SQLite – replace each ? in order
+    let idx = 0;
+    return sql.replace(/\?/g, () => quoteValue(params[idx++]));
+  }
+
+  /**
+   * Build a standard SQL header comment block.
+   * @private
+   */
+  _sqlHeader(type) {
+    return [
+      `-- outlet-orm backup`,
+      `-- type      : ${type}`,
+      `-- driver    : ${this.connection.driver}`,
+      `-- database  : ${this.connection.config?.database || '(unknown)'}`,
+      `-- generated : ${new Date().toISOString()}`,
+      `-- ---------------------------------------------------------------`,
+    ].join('\n');
+  }
+
+  /**
+   * Write content to disk, encrypting first when encryption is enabled.
+   * @private
+   * @param {string} filePath
+   * @param {string} content
+   */
+  async _writeContent(filePath, content) {
+    if (this._encryptEnabled) {
+      const { encryptedContent, salt } = encrypt(content, this._encryptPassword, this._saltLength);
+      await fsPromises.writeFile(filePath, encryptedContent, 'utf8');
+      // Log the grain de sable (salt) for audit purposes without exposing the password
+      console.log(`  🔒 Encrypted (grain de sable: "${salt}", AES-256-GCM, scrypt key derivation)`);
+    } else {
+      await fsPromises.writeFile(filePath, content, 'utf8');
+    }
+  }
+
+  /**
+   * Ensure the backup directory exists.
+   * @private
+   */
+  _ensureBackupDir() {
+    if (!fs.existsSync(this.backupPath)) {
+      fs.mkdirSync(this.backupPath, { recursive: true });
+    }
+  }
+}
+
+module.exports = BackupManager;