piper-utils 1.1.66 → 1.1.68

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "piper-utils",
-    "version": "1.1.66",
+    "version": "1.1.68",
     "description": "Utility library for Piper",
     "main": "bin/main.js",
     "scripts": {

package/src/audit/audit.js

@@ -0,0 +1,436 @@
+import _ from 'lodash';
+import Promise from 'bluebird';
+import { getCurrentUser } from '../requestResponse/requestResponse.js';
+import { accessRightsUtils, getCompanySettings } from '../database/dbUtils/queryStringUtils/accessRightsUtils.js';
+
+/**
+ * @file Audit logging for Sequelize models. Each parent model gets a sibling
+ * `<ModelName>Audit` table that records every field-level change made through
+ * Sequelize hooks (afterCreate / afterUpsert / afterUpdate / afterDestroy).
+ *
+ * Typical wiring in a domain service:
+ *
+ * 1. At model `dbSetup` (one-time, at boot):
+ *    `await attachAudit(MyModel);`
+ *
+ * 2. At the top of each route handler that mutates the model:
+ *    `bindAuditRequest(event, businessId, [MyModel]);`
+ *
+ * 3. To list audit history for a record:
+ *    `const filter = getAuditFilter(MyModel, id, { event, offset, limit });`
+ *    `const audits = await findAll(getAuditModel(MyModel), filter);`
+ *
+ * Audit is **off by default** for any model whose request hasn't been bound —
+ * so cron lambdas, untouched endpoints, and unit tests will not write audit
+ * rows unless they explicitly opt in. The on/off switch comes from the
+ * `custom:SET.auditEnabled` JWT claim resolved by {@link getCompanySettings}.
+ *
+ * The user identity stamped on each row is read from the JWT via
+ * {@link getCurrentUser}; `changedByUser` stores `claims.email`. There is
+ * intentionally no foreign key back to a User table — domain services must
+ * not read across other services' databases.
+ */
+
+/**
+ * Registry of `<ModelName>Audit` Sequelize models, keyed by parent model name.
+ * Populated by {@link attachAudit}. Exported for tests; do not mutate from app code.
+ *
+ * @type {Object<string, import('sequelize').ModelStatic<any>>}
+ */
+export const auditModels = {};
+
+/**
+ * Per-model per-request audit context, keyed by parent model name. Populated by
+ * {@link bindAuditRequest} or {@link bindAuditRequestForUser}. A model with no
+ * entry here (or with `auditEnabled === false`) will not write any audit rows.
+ * Exported for tests; do not mutate from app code.
+ *
+ * @type {Object<string, { user: { username: string, id?: number }, businessId: string|number, auditEnabled: boolean }>}
+ */
+export const modelOptions = {};
+
+const SENSITIVE_FIELDS_PATTERN = /"(token|password|secret|key|credential|auth|securityCode|cvv|pin|ssn)":\s*"[^"]*"/gi;
+
+function getAuditSchema(model) {
+    const DataTypes = model.sequelize.Sequelize;
+    return {
+        field: { type: DataTypes.STRING, allowNull: false },
+        type: DataTypes.STRING,
+        valueOld: DataTypes.STRING,
+        valueNew: DataTypes.STRING,
+        changedByUser: { type: DataTypes.STRING, allowNull: false },
+        businessId: { type: DataTypes.STRING, allowNull: false }
+    };
+}
+
+/**
+ * Internal hook factory. Returns the async function that Sequelize invokes on
+ * each create/upsert/update/destroy. Reads its per-request state from
+ * {@link modelOptions}; emits zero rows when audit is disabled for the model.
+ *
+ * Sensitive fields inside JSON values (token, password, secret, key,
+ * credential, auth, securityCode, cvv, pin, ssn) are masked as
+ * `***************` before being persisted. String values longer than 255
+ * characters are truncated.
+ *
+ * Exported only so tests can drive the hook directly. Application code should
+ * never call this — use {@link attachAudit}.
+ *
+ * @param {string} modelName name of the parent Sequelize model
+ * @returns {(modelInfo: any, options: { type?: string, transaction?: import('sequelize').Transaction }) => Promise<void>}
+ *   the hook function Sequelize will call on each lifecycle event
+ */
+function auditMe(modelName) {
+    return async (modelInfo, options) => {
+        if (_.isArray(modelInfo)) {
+            modelInfo = modelInfo[0];
+        }
+
+        const opts = modelOptions[modelName];
+        if (!opts || !opts.auditEnabled) {
+            return;
+        }
+
+        const auditModel = auditModels[modelName];
+
+        const writeAuditRow = async (field, type, valueOld, valueNew) => {
+            const data = {
+                field,
+                type,
+                valueOld: String(valueOld).substring(0, 255),
+                valueNew: String(valueNew).substring(0, 255),
+                businessId: opts.businessId,
+                changedByUser: opts.user.username
+            };
+            data[modelName + 'Id'] = modelInfo.dataValues.id;
+
+            const newOptions = {};
+            if (options.transaction) {
+                newOptions.transaction = options.transaction;
+            }
+            return auditModel.create(data, newOptions);
+        };
+
+        const checkAudit = async (field, type = 'INITIAL', valueOld, valueNew) => {
+            if (_.isEqual(valueOld, valueNew)) {
+                return;
+            }
+            if (_.isString(valueOld) && _.isString(valueNew)) {
+                type = 'INSERT';
+            }
+
+            if (_.isArray(valueOld) || _.isArray(valueNew)) {
+                let oldString = JSON.stringify(valueOld || []);
+                let newString = JSON.stringify(valueNew || []);
+                oldString = oldString.replace(SENSITIVE_FIELDS_PATTERN, '"$1":"***************"').substring(0, 255);
+                newString = newString.replace(SENSITIVE_FIELDS_PATTERN, '"$1":"***************"').substring(0, 255);
+                return writeAuditRow(field, 'UPDATE', oldString, newString);
+            }
+
+            if (_.isObject(valueOld) || _.isObject(valueNew)) {
+                _.forEach(valueOld, (valueSub, keySub) => {
+                    checkAudit(field + ' ' + keySub, 'DELETED', valueSub || '', (valueNew || {})[keySub] || '');
+                });
+                _.forEach(valueNew, (valueSub, keySub) => {
+                    checkAudit(field + ' ' + keySub, 'INSERT', (valueOld || {})[keySub] || '', valueSub || '');
+                });
+                return;
+            }
+
+            return writeAuditRow(field, type, valueOld, valueNew);
+        };
+
+        return Promise.map([...modelInfo._changed], async (field) => {
+            const valueOld = modelInfo._previousDataValues[field] || '';
+            const valueNew = modelInfo.dataValues[field] || '';
+            await checkAudit(field, options.type, valueOld, valueNew);
+        });
+    };
+}
+
+/**
+ * Define a sibling `<ModelName>Audit` table for the given Sequelize model and
+ * wire the four lifecycle hooks (`afterCreate`, `afterUpsert`, `afterUpdate`,
+ * `afterDestroy`) that record changes into it.
+ *
+ * Call this **once per model at boot time** from inside the model's
+ * `dbSetup()` function. It is idempotent — calling it again for a model that
+ * already has an audit table attached is a no-op.
+ *
+ * The audit table has no foreign key into any user table; the username of the
+ * person who made the change is stamped onto each row from the JWT (set by
+ * {@link bindAuditRequest}). This keeps the audit util portable across domain
+ * services that own different user models.
+ *
+ * @example
+ * // src/customer/customer.js
+ * Customer.dbSetup = async function () {
+ *     await attachAudit(Customer);
+ * };
+ *
+ * @param {import('sequelize').ModelStatic<any>} model the Sequelize model to audit
+ * @returns {Promise<void>} resolves when the audit table's `sync()` completes
+ * @see {@link bindAuditRequest} - per-request setup that turns audit on
+ * @see {@link getAuditModel} - retrieve the audit model from the parent
+ * @see {@link getAuditFilter} - build a filter for an audit history query
+ */
+export async function attachAudit(model) {
+    if (auditModels[model.name]) {
+        return;
+    }
+
+    const auditModel = model.sequelize.define(model.name + 'Audit', getAuditSchema(model), {
+        updatedAt: false,
+        freezeTableName: true
+    });
+    auditModel.belongsTo(model, {
+        foreignKey: { allowNull: true },
+        onDelete: 'SET NULL'
+    });
+    auditModels[model.name] = auditModel;
+
+    model.addHook('afterCreate', auditMe(model.name));
+    model.addHook('afterUpsert', auditMe(model.name));
+    model.addHook('afterUpdate', auditMe(model.name));
+    model.addHook('afterDestroy', auditMe(model.name));
+
+    return auditModel.sync();
+}
+
+/**
+ * Bind per-request audit context for one or more models. Call this **once at
+ * the top of each route handler** that mutates an audited model.
+ *
+ * Resolves the acting user from the JWT claims on the event
+ * (via {@link getCurrentUser}) and reads the company `auditEnabled` flag from
+ * the `custom:SET` claim (via {@link getCompanySettings}). If the company has
+ * `auditEnabled: false` then no rows will be written for the bound models on
+ * this request.
+ *
+ * Audit is **off by default** for any model that has not been bound this
+ * request — a route that omits this call writes no audit rows.
+ *
+ * @example
+ * // src/customer/customerRoutes.js
+ * export async function updateCustomer(event) {
+ *     checkModule('customer', event);
+ *     const businessId = checkWriteAccess(event);
+ *     bindAuditRequest(event, businessId, [Customer]);
+ *     // ...mutate Customer here; rows are written automatically by hooks
+ * }
+ *
+ * @example
+ * // Bind several models in one call when a handler touches more than one
+ * bindAuditRequest(event, businessId, [Order, Payment, Receivable]);
+ *
+ * @param {import('aws-lambda').APIGatewayProxyEvent} event API Gateway event
+ *   with `requestContext.authorizer.claims` (must include `email` and
+ *   optionally `custom:UID`, `custom:SET`)
+ * @param {string|number} businessId business id this request acts on; stamped
+ *   onto every audit row written for the bound models
+ * @param {Array<import('sequelize').ModelStatic<any>>} models Sequelize models
+ *   to enable audit on for the duration of this request
+ * @returns {void}
+ * @see {@link bindAuditRequestForUser} - the equivalent for non-JWT contexts
+ *   (webhooks, integration crons, Cognito triggers)
+ * @see {@link attachAudit} - one-time setup that creates the audit table
+ */
+export function bindAuditRequest(event, businessId, models) {
+    const user = getCurrentUser(event);
+    const auditEnabled = !!(getCompanySettings(event) || {}).auditEnabled;
+    _.forEach(models, (model) => {
+        // Lazily ensure the audit table model + hooks are wired in this Lambda
+        // process. `attachAudit` is idempotent — first call registers, subsequent
+        // calls are no-ops. The returned sync() promise is intentionally not
+        // awaited; the table is expected to already exist from the migration
+        // Lambda, and the synchronous registration is what the request needs.
+        const attachPromise = attachAudit(model);
+        if (attachPromise && typeof attachPromise.catch === 'function') {
+            attachPromise.catch((err) => console.error('attachAudit sync failed for', model.name, err));
+        }
+        modelOptions[model.name] = { user, businessId, auditEnabled };
+    });
+}
+
+/**
+ * Bind per-request audit context for **system-driven flows** that do not carry
+ * an API Gateway JWT — for example, payment-gateway webhooks, integration
+ * crons (QuickBooks/Inbox/etc.), Cognito triggers, or batch jobs.
+ *
+ * Use {@link bindAuditRequest} instead whenever you have a JWT-authenticated
+ * API event; that path automatically resolves the user and the company's
+ * `auditEnabled` flag from claims.
+ *
+ * @example
+ * // payment webhook from the gateway — no JWT, but we still want audit
+ * import { systemUser } from '../user/user.js';
+ *
+ * export async function webhook(event) {
+ *     const businessId = event.queryStringParameters.businessId;
+ *     bindAuditRequestForUser(systemUser, businessId, [Order, Payment]);
+ *     // ...mutate Order/Payment; audit rows are written by hooks
+ * }
+ *
+ * @example
+ * // turn audit OFF explicitly for a system flow that should not be audited
+ * bindAuditRequestForUser(systemUser, businessId, [Order], { auditEnabled: false });
+ *
+ * @param {{ username: string, id?: number }} user identity stamped onto each
+ *   audit row's `changedByUser` field. Conventionally the `systemUser`
+ *   constant exported from your service's user model
+ * @param {string|number} businessId business id this flow is acting on
+ * @param {Array<import('sequelize').ModelStatic<any>>} models Sequelize models
+ *   to enable audit on
+ * @param {{ auditEnabled?: boolean }} [opts] when `auditEnabled` is `false`,
+ *   binds context but suppresses writes; defaults to `true`
+ * @returns {void}
+ * @see {@link bindAuditRequest} - the JWT-driven equivalent for API handlers
+ */
+export function bindAuditRequestForUser(user, businessId, models, opts = {}) {
+    const auditEnabled = opts.auditEnabled !== false;
+    _.forEach(models, (model) => {
+        // See bindAuditRequest for why this is here.
+        const attachPromise = attachAudit(model);
+        if (attachPromise && typeof attachPromise.catch === 'function') {
+            attachPromise.catch((err) => console.error('attachAudit sync failed for', model.name, err));
+        }
+        modelOptions[model.name] = { user, businessId, auditEnabled };
+    });
+}
+
+/**
+ * Get the `<ModelName>Audit` Sequelize model that {@link attachAudit} created
+ * for a parent model. Returns `undefined` if audit was never attached.
+ *
+ * @example
+ * const audits = await findAll(getAuditModel(Customer), filter);
+ *
+ * @param {import('sequelize').ModelStatic<any>} model parent Sequelize model
+ * @returns {import('sequelize').ModelStatic<any> | undefined} the audit model,
+ *   or `undefined` if {@link attachAudit} has not been called for this model
+ * @see {@link getAuditFilter} - companion filter builder for history queries
+ */
+export function getAuditModel(model) {
+    return auditModels[model.name];
+}
+
+/**
+ * Build a Sequelize `findAll`-style filter for an audit-history query, scoped
+ * to the businesses the caller is allowed to read (resolved from
+ * {@link accessRightsUtils}).
+ *
+ * The returned filter joins the parent model so callers can render `oldValue`
+ * → `newValue` rows in the UI alongside the parent record.
+ *
+ * @example
+ * // GET /customer/{id}/audit
+ * export async function getCustomerAudit(event) {
+ *     bindAuditRequest(event, userDefaultBid(event), [Customer]);
+ *     const filter = getAuditFilter(Customer, event.pathParameters.id, {
+ *         event,
+ *         offset: 0,
+ *         limit: 10
+ *     });
+ *     const audits = await findAll(getAuditModel(Customer), filter);
+ *     return success(audits);
+ * }
+ *
+ * @param {import('sequelize').ModelStatic<any>} modelToFilter the parent model
+ *   whose history is being fetched
+ * @param {string|number} id parent record id
+ * @param {{ event: import('aws-lambda').APIGatewayProxyEvent, offset?: number, limit?: number }} options
+ *   `event` is required (drives business-id scoping); `offset` and `limit`
+ *   are pagination passthroughs
+ * @returns {{ where: Object, include: Array<{ model: Object }>, order: Array, offset?: number, limit?: number }}
+ *   a Sequelize `findAll`-compatible filter
+ * @see {@link getAuditModel} - call to get the audit model to query against
+ */
+export function getAuditFilter(modelToFilter, id, options) {
+    const businessIds = accessRightsUtils(options.event);
+    const filter = {
+        where: {
+            businessId: businessIds
+        },
+        include: [{
+            model: modelToFilter
+        }],
+        order: [
+            ['createdAt', 'DESC']
+        ]
+    };
+    filter.where[modelToFilter.name + 'Id'] = id;
+
+    return { ...filter, ...options };
+}
+
+/**
+ * Decrement an integer field on a Sequelize instance and write a matching
+ * audit row in the same call. Useful for inventory adjustments and other
+ * counter-style fields where Sequelize's plain `model.decrement()` would
+ * bypass the `afterUpdate` hook.
+ *
+ * The acting user and businessId come from whatever
+ * {@link bindAuditRequest} / {@link bindAuditRequestForUser} was called for
+ * this request. If audit is disabled for the model, the decrement still
+ * happens but no audit row is written.
+ *
+ * @example
+ * // release inventory on order release
+ * await decrementWithAudit('inventory', inventoryEntry, 'quantity', {
+ *     by: item.quantity,
+ *     transaction: t
+ * });
+ *
+ * @param {string} modelName name of the parent model (e.g. `'inventory'`)
+ * @param {import('sequelize').Model} model the Sequelize instance to mutate
+ * @param {string} field the integer/decimal field to decrement
+ * @param {{ by?: number, transaction?: import('sequelize').Transaction }} args
+ *   passed straight through to Sequelize's `decrement()`; transaction is also
+ *   propagated to the audit write
+ * @returns {Promise<import('sequelize').Model>} the updated instance (with
+ *   `_changed` set on it so internal hooks can observe the change)
+ * @see {@link incrementWithAudit} - the +1 counterpart
+ */
+export async function decrementWithAudit(modelName, model, field, args) {
+    const r = await model.decrement(field, args);
+    r._changed = [field];
+    const options = {};
+    if (args.transaction) {
+        options.transaction = args.transaction;
+    }
+    await auditMe(modelName)(r, options);
+    return r;
+}
+
+/**
+ * Increment an integer field on a Sequelize instance and write a matching
+ * audit row in the same call. The mirror of {@link decrementWithAudit}.
+ *
+ * @example
+ * // restock from a receivable
+ * await incrementWithAudit('inventory', inventoryEntry, 'quantity', {
+ *     by: item.quantity,
+ *     transaction: t
+ * });
+ *
+ * @param {string} modelName name of the parent model (e.g. `'inventory'`)
+ * @param {import('sequelize').Model} model the Sequelize instance to mutate
+ * @param {string} field the integer/decimal field to increment
+ * @param {{ by?: number, transaction?: import('sequelize').Transaction }} args
+ *   passed straight through to Sequelize's `increment()`; transaction is also
+ *   propagated to the audit write
+ * @returns {Promise<import('sequelize').Model>} the updated instance
+ * @see {@link decrementWithAudit} - the -1 counterpart
+ */
+export async function incrementWithAudit(modelName, model, field, args) {
+    const r = await model.increment(field, args);
+    r._changed = [field];
+    const options = {};
+    if (args.transaction) {
+        options.transaction = args.transaction;
+    }
+    await auditMe(modelName)(r, options);
+    return r;
+}
+
+export { auditMe };