@zero-server/orm 0.9.1 → 0.9.2

package/lib/orm/audit.js

@@ -0,0 +1,649 @@
+/**
+ * @module orm/audit
+ * @description Automatic audit logging for the ORM.
+ *              Tracks who changed what and when, with diff-based change logs.
+ *              Supports storing audit trails in the same database or a separate one
+ *              and provides querying capabilities for the audit trail.
+ *
+ * @example
+ *   const { AuditLog } = require('@zero-server/sdk');
+ *
+ *   const audit = new AuditLog(db, {
+ *       actorField: 'userId',       // field on req/context identifying the actor
+ *       include: [User, Post],      // models to audit
+ *   });
+ *
+ *   // Automatically tracks creates, updates, and deletes
+ *   await User.create({ name: 'Alice' }); // audit entry logged
+ *
+ *   // Query audit trail
+ *   const trail = await audit.trail({ table: 'users', recordId: 1 });
+ */
+
+const log = require('../debug')('zero:orm:audit');
+
+// -- AuditLog class ------------------------------------------
+
+/**
+ * Automatic change tracking for ORM models.
+ * Records who changed what and when, with diff-based change logs.
+ */
+class AuditLog
+{
+    /**
+     * @constructor
+     * @param {import('./index').Database} db - Database instance for storing audit entries.
+     * @param {object} options - Audit configuration.
+     * @param {string} [options.table='_audit_log']     - Table name for audit entries.
+     * @param {Array<typeof import('./model')>} [options.include]  - Models to audit (all registered if omitted).
+     * @param {Array<typeof import('./model')>} [options.exclude]  - Models to exclude from auditing.
+     * @param {string[]} [options.excludeFields]        - Fields to never log (e.g. passwords).
+     * @param {string} [options.actorField]             - Context property for the actor identifier.
+     * @param {import('./index').Database} [options.storage] - Separate database for audit storage.
+     * @param {boolean} [options.timestamps=true]       - Include timestamps in audit entries.
+     * @param {boolean} [options.diffs=true]            - Store field-level diffs for updates.
+     *
+     * @example
+     *   const audit = new AuditLog(db, {
+     *       table: '_audit_log',
+     *       include: [User, Post],
+     *       excludeFields: ['password', 'token'],
+     *       diffs: true,
+     *   });
+     */
+    constructor(db, options = {})
+    {
+        if (!db) throw new Error('AuditLog requires a Database instance');
+
+        /** @type {import('./index').Database} */
+        this.db = db;
+
+        /** @type {string} */
+        this.tableName = options.table || '_audit_log';
+
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(this.tableName))
+        {
+            throw new Error(`Invalid audit table name: "${this.tableName}"`);
+        }
+
+        /** @type {Set<typeof import('./model')>|null} */
+        this._include = options.include ? new Set(options.include) : null;
+
+        /** @type {Set<typeof import('./model')>} */
+        this._exclude = new Set(options.exclude || []);
+
+        /** @type {Set<string>} */
+        this._excludeFields = new Set(options.excludeFields || []);
+
+        /** @type {string|null} */
+        this._actorField = options.actorField || null;
+
+        /** @type {import('./index').Database} */
+        this._storage = options.storage || db;
+
+        /** @type {boolean} */
+        this._timestamps = options.timestamps !== false;
+
+        /** @type {boolean} */
+        this._diffs = options.diffs !== false;
+
+        /** @type {string|null} Current actor for audit entries. */
+        this._currentActor = null;
+
+        /** @type {boolean} */
+        this._initialized = false;
+
+        /** @type {Set<typeof import('./model')>} Models currently being audited. */
+        this._auditedModels = new Set();
+
+        log('AuditLog created', { table: this.tableName });
+    }
+
+    // -- Setup -------------------------------------------
+
+    /**
+     * Initialize the audit log table and attach hooks to models.
+     * Must be called after models are registered and synced.
+     *
+     * @returns {Promise<AuditLog>} this (for chaining)
+     *
+     * @example
+     *   await audit.install();
+     */
+    async install()
+    {
+        // Create the audit log table
+        const adapter = this._storage.adapter;
+
+        if (typeof adapter.execute === 'function')
+        {
+            // SQL adapter
+            const sql =
+                `CREATE TABLE IF NOT EXISTS "${this.tableName}" (` +
+                `"id" INTEGER PRIMARY KEY ${adapter.constructor.name === 'PostgresAdapter' ? 'GENERATED ALWAYS AS IDENTITY' : 'AUTOINCREMENT'},` +
+                `"action" TEXT NOT NULL,` +
+                `"table_name" TEXT NOT NULL,` +
+                `"record_id" TEXT,` +
+                `"actor" TEXT,` +
+                `"old_values" TEXT,` +
+                `"new_values" TEXT,` +
+                `"diff" TEXT,` +
+                `"timestamp" TEXT NOT NULL DEFAULT (datetime('now'))` +
+                `)`;
+            await adapter.execute({ raw: sql });
+        }
+        else
+        {
+            // Memory/JSON adapter — ensure table structure
+            if (typeof adapter.createTable === 'function')
+            {
+                const schema = {
+                    id:         { type: 'integer', primaryKey: true, autoIncrement: true },
+                    action:     { type: 'string', required: true },
+                    table_name: { type: 'string', required: true },
+                    record_id:  { type: 'string' },
+                    actor:      { type: 'string' },
+                    old_values: { type: 'text' },
+                    new_values: { type: 'text' },
+                    diff:       { type: 'text' },
+                    timestamp:  { type: 'string' },
+                };
+                await adapter.createTable(this.tableName, schema);
+            }
+        }
+
+        // Attach hooks to models
+        const models = this._include
+            ? [...this._include]
+            : [...this.db._models.values()];
+
+        for (const ModelClass of models)
+        {
+            if (this._exclude.has(ModelClass)) continue;
+            this._attachHooks(ModelClass);
+        }
+
+        this._initialized = true;
+        log('AuditLog installed', { models: this._auditedModels.size });
+        return this;
+    }
+
+    // -- Actor Management --------------------------------
+
+    /**
+     * Set the current actor (user) performing operations.
+     *
+     * @param {string} actor - Actor identifier (user ID, email, etc.).
+     * @returns {AuditLog} this (for chaining)
+     *
+     * @example
+     *   audit.setActor('user-123');
+     */
+    setActor(actor)
+    {
+        this._currentActor = actor != null ? String(actor) : null;
+        return this;
+    }
+
+    /**
+     * Get the current actor.
+     *
+     * @returns {string|null} Current actor identifier.
+     */
+    getActor()
+    {
+        return this._currentActor;
+    }
+
+    /**
+     * Execute a function within a specific actor context.
+     *
+     * @param {string}   actor - Actor identifier.
+     * @param {Function} fn    - Async callback.
+     * @returns {Promise<*>} Result of fn().
+     *
+     * @example
+     *   await audit.withActor('admin', async () => {
+     *       await User.create({ name: 'New User' });
+     *   });
+     */
+    async withActor(actor, fn)
+    {
+        const prev = this._currentActor;
+        this.setActor(actor);
+        try
+        {
+            return await fn();
+        }
+        finally
+        {
+            this._currentActor = prev;
+        }
+    }
+
+    // -- Hook Attachment ---------------------------------
+
+    /**
+     * @private
+     * Attach lifecycle hooks to a model for audit logging.
+     */
+    _attachHooks(ModelClass)
+    {
+        if (this._auditedModels.has(ModelClass)) return;
+        this._auditedModels.add(ModelClass);
+
+        const audit = this;
+        const table = ModelClass.table || ModelClass.name;
+
+        // Use model events if available
+        if (typeof ModelClass.on === 'function')
+        {
+            ModelClass.on('created', (instance) =>
+            {
+                audit._logEntry('create', table, instance).catch(() => {});
+            });
+
+            ModelClass.on('updated', (instance) =>
+            {
+                audit._logEntry('update', table, instance).catch(() => {});
+            });
+
+            ModelClass.on('deleted', (instance) =>
+            {
+                audit._logEntry('delete', table, instance).catch(() => {});
+            });
+        }
+        else
+        {
+            // Fallback: patch static methods
+            const origCreate = ModelClass.create.bind(ModelClass);
+            ModelClass.create = async function (data)
+            {
+                const result = await origCreate(data);
+                await audit._logEntry('create', table, result);
+                return result;
+            };
+        }
+
+        log('hooks attached', table);
+    }
+
+    // -- Entry Logging -----------------------------------
+
+    /**
+     * @private
+     * Log a single audit entry.
+     */
+    async _logEntry(action, tableName, instance)
+    {
+        try
+        {
+            const pk = this._extractPK(instance);
+            const filtered = this._filterFields(instance);
+
+            const entry = {
+                action,
+                table_name: tableName,
+                record_id:  pk != null ? String(pk) : null,
+                actor:      this._currentActor,
+                timestamp:  new Date().toISOString(),
+            };
+
+            if (action === 'create')
+            {
+                entry.old_values = null;
+                entry.new_values = JSON.stringify(filtered);
+                entry.diff = null;
+            }
+            else if (action === 'update')
+            {
+                const original = instance._original || {};
+                const oldFiltered = this._filterFields(original);
+                entry.old_values = JSON.stringify(oldFiltered);
+                entry.new_values = JSON.stringify(filtered);
+
+                if (this._diffs)
+                {
+                    entry.diff = JSON.stringify(this._computeDiff(oldFiltered, filtered));
+                }
+            }
+            else if (action === 'delete')
+            {
+                entry.old_values = JSON.stringify(filtered);
+                entry.new_values = null;
+                entry.diff = null;
+            }
+
+            await this._writeEntry(entry);
+        }
+        catch (err)
+        {
+            log('audit entry failed', err.message);
+        }
+    }
+
+    /**
+     * @private
+     * Write an audit entry to storage.
+     */
+    async _writeEntry(entry)
+    {
+        const adapter = this._storage.adapter;
+
+        if (typeof adapter.execute === 'function')
+        {
+            // SQL adapter
+            await adapter.execute({
+                action: 'insert',
+                table: this.tableName,
+                data: entry,
+            });
+        }
+        else if (typeof adapter.insert === 'function')
+        {
+            await adapter.insert(this.tableName, entry);
+        }
+    }
+
+    /**
+     * @private
+     * Extract primary key value from an instance.
+     */
+    _extractPK(instance)
+    {
+        if (!instance) return null;
+
+        // Handle plain objects and model instances
+        const data = typeof instance.toJSON === 'function' ? instance.toJSON() : instance;
+        return data.id || data._id || null;
+    }
+
+    /**
+     * @private
+     * Filter out excluded fields from data.
+     */
+    _filterFields(data)
+    {
+        if (!data || typeof data !== 'object') return {};
+
+        const source = typeof data.toJSON === 'function' ? data.toJSON() : { ...data };
+        const result = {};
+
+        for (const [key, value] of Object.entries(source))
+        {
+            if (key.startsWith('_')) continue;
+            if (this._excludeFields.has(key)) continue;
+            result[key] = value;
+        }
+
+        return result;
+    }
+
+    // -- Diff Computation --------------------------------
+
+    /**
+     * Compute a diff between old and new values.
+     * Returns an array of `{ field, from, to }` objects.
+     *
+     * @param {object} oldValues - Previous data.
+     * @param {object} newValues - Current data.
+     * @returns {Array<{field: string, from: *, to: *}>}
+     *
+     * @example
+     *   const diff = audit.diff({ name: 'Alice' }, { name: 'Bob' });
+     *   // [{ field: 'name', from: 'Alice', to: 'Bob' }]
+     */
+    diff(oldValues, newValues)
+    {
+        return this._computeDiff(oldValues, newValues);
+    }
+
+    /**
+     * @private
+     */
+    _computeDiff(oldValues, newValues)
+    {
+        const changes = [];
+        const allKeys = new Set([
+            ...Object.keys(oldValues || {}),
+            ...Object.keys(newValues || {}),
+        ]);
+
+        for (const key of allKeys)
+        {
+            const oldVal = oldValues ? oldValues[key] : undefined;
+            const newVal = newValues ? newValues[key] : undefined;
+
+            // Deep equality via JSON comparison for objects/arrays
+            const oldStr = JSON.stringify(oldVal);
+            const newStr = JSON.stringify(newVal);
+
+            if (oldStr !== newStr)
+            {
+                changes.push({ field: key, from: oldVal, to: newVal });
+            }
+        }
+
+        return changes;
+    }
+
+    // -- Querying Audit Trail ----------------------------
+
+    /**
+     * Query the audit trail.
+     *
+     * @param {object}  [options] - Filter options.
+     * @param {string}  [options.table]    - Filter by table name.
+     * @param {string}  [options.action]   - Filter by action (create, update, delete).
+     * @param {string}  [options.recordId] - Filter by record ID.
+     * @param {string}  [options.actor]    - Filter by actor.
+     * @param {string}  [options.since]    - ISO timestamp lower bound.
+     * @param {string}  [options.until]    - ISO timestamp upper bound.
+     * @param {number}  [options.limit=100] - Maximum entries.
+     * @param {number}  [options.offset=0]  - Skip entries.
+     * @param {string}  [options.order='desc'] - Sort order by timestamp.
+     * @returns {Promise<Array>} Audit entries.
+     *
+     * @example
+     *   const entries = await audit.trail({ table: 'users', recordId: '1' });
+     *   const updates = await audit.trail({ action: 'update', limit: 50 });
+     */
+    async trail(options = {})
+    {
+        const { table, action, recordId, actor, since, until, limit = 100, offset = 0, order = 'desc' } = options;
+        const adapter = this._storage.adapter;
+
+        const where = [];
+        if (table)    where.push({ field: 'table_name', op: '=', value: table });
+        if (action)   where.push({ field: 'action', op: '=', value: action });
+        if (recordId) where.push({ field: 'record_id', op: '=', value: String(recordId) });
+        if (actor)    where.push({ field: 'actor', op: '=', value: actor });
+        if (since)    where.push({ field: 'timestamp', op: '>=', value: since });
+        if (until)    where.push({ field: 'timestamp', op: '<=', value: until });
+
+        const descriptor = {
+            action: 'find',
+            table: this.tableName,
+            where,
+            orderBy: [{ field: 'timestamp', direction: order }],
+            limit,
+            offset,
+        };
+
+        let rows;
+        if (typeof adapter.execute === 'function')
+        {
+            rows = await adapter.execute(descriptor);
+        }
+        else if (typeof adapter.find === 'function')
+        {
+            rows = await adapter.find(this.tableName, descriptor);
+        }
+        else
+        {
+            rows = [];
+        }
+
+        // Parse JSON fields
+        return (rows || []).map(row => ({
+            ...row,
+            old_values: row.old_values ? JSON.parse(row.old_values) : null,
+            new_values: row.new_values ? JSON.parse(row.new_values) : null,
+            diff: row.diff ? JSON.parse(row.diff) : null,
+        }));
+    }
+
+    /**
+     * Get the audit history for a specific record.
+     *
+     * @param {string}        table    - Table name.
+     * @param {string|number} recordId - Record ID.
+     * @param {object}        [options] - Additional filter options.
+     * @returns {Promise<Array>} Audit entries for the record.
+     *
+     * @example
+     *   const history = await audit.history('users', 1);
+     */
+    async history(table, recordId, options = {})
+    {
+        return this.trail({ ...options, table, recordId: String(recordId) });
+    }
+
+    /**
+     * Get audit entries grouped by actor.
+     *
+     * @param {object} [options] - Filter options.
+     * @returns {Promise<Map<string, Array>>} Map of actor → entries.
+     */
+    async byActor(options = {})
+    {
+        const entries = await this.trail({ ...options, limit: options.limit || 1000 });
+        const grouped = new Map();
+
+        for (const entry of entries)
+        {
+            const actor = entry.actor || '__unknown__';
+            if (!grouped.has(actor)) grouped.set(actor, []);
+            grouped.get(actor).push(entry);
+        }
+
+        return grouped;
+    }
+
+    /**
+     * Count audit entries matching the given filters.
+     *
+     * @param {object} [options] - Same filter options as trail().
+     * @returns {Promise<number>}
+     *
+     * @example
+     *   const count = await audit.count({ table: 'users', action: 'update' });
+     */
+    async count(options = {})
+    {
+        const { table, action, recordId, actor, since, until } = options;
+        const adapter = this._storage.adapter;
+
+        const where = [];
+        if (table)    where.push({ field: 'table_name', op: '=', value: table });
+        if (action)   where.push({ field: 'action', op: '=', value: action });
+        if (recordId) where.push({ field: 'record_id', op: '=', value: String(recordId) });
+        if (actor)    where.push({ field: 'actor', op: '=', value: actor });
+        if (since)    where.push({ field: 'timestamp', op: '>=', value: since });
+        if (until)    where.push({ field: 'timestamp', op: '<=', value: until });
+
+        if (typeof adapter.execute === 'function')
+        {
+            const result = await adapter.execute({
+                action: 'count',
+                table: this.tableName,
+                where,
+            });
+            return typeof result === 'number' ? result : (result && result[0] ? result[0].count || 0 : 0);
+        }
+
+        // Fallback: fetch all and count
+        const entries = await this.trail(options);
+        return entries.length;
+    }
+
+    /**
+     * Purge old audit entries.
+     *
+     * @param {object} options - Purge options.
+     * @param {string} [options.before]    - ISO timestamp; delete entries older than this.
+     * @param {string} [options.table]     - Only purge entries for this table.
+     * @param {number} [options.keepLast]  - Keep at least this many entries per record.
+     * @returns {Promise<number>} Number of entries purged.
+     *
+     * @example
+     *   const purged = await audit.purge({ before: '2025-01-01T00:00:00Z' });
+     */
+    async purge(options = {})
+    {
+        const { before, table } = options;
+        const adapter = this._storage.adapter;
+
+        const where = [];
+        if (before) where.push({ field: 'timestamp', op: '<', value: before });
+        if (table)  where.push({ field: 'table_name', op: '=', value: table });
+
+        if (where.length === 0)
+        {
+            throw new Error('purge() requires at least one filter (before or table)');
+        }
+
+        if (typeof adapter.execute === 'function')
+        {
+            const result = await adapter.execute({
+                action: 'delete',
+                table: this.tableName,
+                where,
+            });
+            const count = typeof result === 'number' ? result : (result && result.changes ? result.changes : 0);
+            log('purged entries', count);
+            return count;
+        }
+
+        return 0;
+    }
+
+    /**
+     * Returns an HTTP middleware that sets the actor from the request.
+     *
+     * @param {object}   [options] - Options.
+     * @param {Function} [options.extract] - Custom `(req) => actorId` function.
+     * @param {string}   [options.header='x-user-id'] - Header to read actor from.
+     * @returns {Function} Middleware `(req, res, next) => {}`.
+     *
+     * @example
+     *   app.use(audit.middleware({ extract: (req) => req.user?.id }));
+     */
+    middleware(options = {})
+    {
+        const { extract, header = 'x-user-id' } = options;
+        const auditLog = this;
+
+        return function auditMiddleware(req, res, next)
+        {
+            let actor;
+            if (typeof extract === 'function')
+            {
+                actor = extract(req);
+            }
+            else if (header && req.headers)
+            {
+                actor = req.headers[header.toLowerCase()];
+            }
+
+            if (actor)
+            {
+                auditLog.setActor(String(actor));
+            }
+
+            next();
+        };
+    }
+}
+
+module.exports = { AuditLog };