ts-prorm-orm 1.1.0

package/dist/compliance/data-masker.js

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * DataMasker
+ *
+ * Masks sensitive fields in query output. Supports built-in masking patterns
+ * (PAN, SSN, email, phone) and custom patterns. Works with the permission
+ * system to provide role-aware masking.
+ *
+ * Covers ~14 compliance frameworks including:
+ *   PCI DSS (cardholder data), GLBA (financial), SOX, HIPAA,
+ *   NYDFS 23 NYCRR 500, GDPR Art 25/32, NIST SP 800-122, and more.
+ *
+ * Usage:
+ *   // Register a masking rule:
+ *   DataMasker.maskField(User, 'ssn', { pattern: 'ssn' });
+ *   DataMasker.maskField(Payment, 'cardNumber', { pattern: 'card-last4', showLast: 4 });
+ *   DataMasker.maskField(Customer, 'email', { pattern: 'email' });
+ *
+ *   // Or use the decorator:
+ *   @Mask('ssn', { pattern: 'ssn' })
+ *   class User extends Model { ... }
+ *
+ *   // At query time, mask the output:
+ *   const user = await User.findByPk(1);
+ *   const masked = DataMasker.mask(user, 'admin'); // respects role
+ *
+ *   // Or use the automatic hook:
+ *   DataMasker.applyHooks(User);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataMasker = exports.MaskPatternEnum = void 0;
+exports.maskField = maskField;
+exports.getMaskRules = getMaskRules;
+exports.Mask = Mask;
+exports.maskValue = maskValue;
+exports.mask = mask;
+exports.maskMany = maskMany;
+exports.applyHooks = applyHooks;
+const permissions_1 = require("../decorators/permissions");
+/**
+ * Companion enum for {@link MaskPattern}. Provided for callers who prefer
+ * enum-based ergonomics (autocomplete, refactor-safety) over raw string
+ * literals. The underlying values are identical to the `MaskPattern`
+ * string literals, so either form may be used interchangeably.
+ */
+var MaskPatternEnum;
+(function (MaskPatternEnum) {
+    MaskPatternEnum["SSN"] = "ssn";
+    MaskPatternEnum["CardLast4"] = "card-last4";
+    MaskPatternEnum["CardFirst6"] = "card-first6";
+    MaskPatternEnum["Email"] = "email";
+    MaskPatternEnum["Phone"] = "phone";
+    MaskPatternEnum["Full"] = "full";
+    MaskPatternEnum["None"] = "none";
+    MaskPatternEnum["Custom"] = "custom";
+})(MaskPatternEnum || (exports.MaskPatternEnum = MaskPatternEnum = {}));
+const maskedFields = new Map();
+// ==================== Built-in Maskers ====================
+/** Masks a 9-digit SSN as `***-**-1234`; falls back to a length-preserving mask (last 4 chars shown) for non-standard formats. */
+function maskSSN(value, opts) {
+    if (!value)
+        return '';
+    const digits = value.replace(/\D/g, '');
+    if (digits.length === 9) {
+        return `***-**-${digits.slice(-4)}`;
+    }
+    // Fallback for non-standard format
+    const char = opts.maskChar ?? '*';
+    return char.repeat(value.length - 4) + value.slice(-4);
+}
+/**
+ * Masks a card number, revealing only the last N digits (PCI DSS truncation
+ * pattern). Defaults to 4 digits; pass `opts.showLast` to reveal a different count.
+ */
+function maskCardLast4(value, opts) {
+    if (!value)
+        return '';
+    const clean = value.replace(/\s/g, '');
+    const showLast = opts.showLast ?? 4;
+    const maskChar = opts.maskChar ?? '*';
+    if (clean.length >= showLast) {
+        return maskChar.repeat(clean.length - showLast) + clean.slice(clean.length - showLast);
+    }
+    return maskChar.repeat(value.length);
+}
+/**
+ * Masks a card number, revealing only the first N digits (the BIN/IIN).
+ * Defaults to 6 digits; pass `opts.showFirst` to reveal a different count.
+ */
+function maskCardFirst6(value, opts) {
+    if (!value)
+        return '';
+    const clean = value.replace(/\s/g, '');
+    const showFirst = opts.showFirst ?? 6;
+    const maskChar = opts.maskChar ?? '*';
+    if (clean.length >= showFirst) {
+        return clean.slice(0, showFirst) + maskChar.repeat(clean.length - showFirst);
+    }
+    return maskChar.repeat(value.length);
+}
+/** Masks the local part of an email address, leaving the domain visible. */
+function maskEmail(value) {
+    if (!value || !value.includes('@'))
+        return value;
+    const [local, domain] = value.split('@');
+    // Always use a fixed-width mask ('***') so the masked output never leaks
+    // the original local-part length.
+    const maskedLocal = local.length > 2 ? `${local[0]}***${local.slice(-1)}` : '***';
+    return `${maskedLocal}@${domain}`;
+}
+/** Masks a phone number, showing only the last 4 digits; recognizes 10-digit and 11-digit (+1) US formats. */
+function maskPhone(value) {
+    if (!value)
+        return '';
+    const digits = value.replace(/\D/g, '');
+    if (digits.length === 10) {
+        return `(***) ***-${digits.slice(-4)}`;
+    }
+    if (digits.length === 11 && digits[0] === '1') {
+        return `+1 (***) ***-${digits.slice(-4)}`;
+    }
+    return '*'.repeat(value.length - 4) + value.slice(-4);
+}
+/** Fully masks a value, replacing every character with the mask char. */
+function maskFull(value, opts) {
+    if (!value)
+        return '';
+    return (opts.maskChar ?? '*').repeat(value.length);
+}
+/**
+ * Dispatches to the appropriate masker for `opts.pattern`. Non-string
+ * values are stringified before masking; `null`/`undefined` short-circuit
+ * to `''` and unknown/`none` patterns pass the value through unchanged.
+ */
+function applyMask(value, opts) {
+    if (value == null)
+        return '';
+    if (typeof value !== 'string')
+        value = String(value);
+    const pattern = opts.pattern ?? 'none';
+    const maskChar = opts.maskChar ?? '*';
+    switch (pattern) {
+        case 'ssn':
+            return maskSSN(value, { ...opts, maskChar });
+        case 'card-last4':
+            return maskCardLast4(value, { ...opts, maskChar });
+        case 'card-first6':
+            return maskCardFirst6(value, { ...opts, maskChar });
+        case 'email':
+            return maskEmail(value);
+        case 'phone':
+            return maskPhone(value);
+        case 'full':
+            return maskFull(value, { ...opts, maskChar });
+        case 'none':
+            return value;
+        case 'custom':
+            return opts.customMasker ? opts.customMasker(value) : value;
+        default:
+            return value;
+    }
+}
+// ==================== Registry ====================
+/**
+ * Register a masking rule for a field on a model.
+ */
+function maskField(Model, field, options = {}) {
+    if (!maskedFields.has(Model)) {
+        maskedFields.set(Model, []);
+    }
+    const rules = maskedFields.get(Model);
+    const existing = rules.findIndex((r) => r.field === field);
+    const rule = {
+        field,
+        options: {
+            pattern: options.pattern ?? 'none',
+            customMasker: options.customMasker,
+            showLast: options.showLast ?? 4,
+            showFirst: options.showFirst ?? 0,
+            maskChar: options.maskChar ?? '*',
+        },
+    };
+    if (existing >= 0) {
+        rules[existing] = rule;
+    }
+    else {
+        rules.push(rule);
+    }
+}
+/**
+ * Get all masking rules for a model.
+ */
+function getMaskRules(Model) {
+    return maskedFields.get(Model) ?? [];
+}
+// ==================== Decorator ====================
+/**
+ * Decorator to mark a field for masking.
+ *
+ *   @Mask('ssn', { pattern: 'ssn' })
+ *   class User extends Model { ... }
+ */
+function Mask(field, options = {}) {
+    return function (target) {
+        maskField(target, field, options);
+    };
+}
+// ==================== Masking Logic ====================
+/**
+ * Apply masking to a single value.
+ */
+function maskValue(value, options) {
+    return applyMask(value, {
+        pattern: options.pattern ?? 'none',
+        customMasker: options.customMasker,
+        showLast: options.showLast ?? 4,
+        showFirst: options.showFirst ?? 0,
+        maskChar: options.maskChar ?? '*',
+    });
+}
+/**
+ * Apply masking to a model instance, respecting both permission rules
+ * and masking rules.
+ *
+ * @param instance - The model instance or plain object
+ * @param role     - The current user's role (for permission filtering)
+ * @param Model    - The model class (optional, inferred from instance.constructor)
+ */
+function mask(instance, role, Model) {
+    const modelClass = Model ?? instance.constructor;
+    const rules = getMaskRules(modelClass);
+    // First filter by permissions
+    const permitted = (0, permissions_1.filterByPermissions)(instance, role, modelClass);
+    // Then apply masking
+    const result = {};
+    const data = permitted;
+    for (const [key, value] of Object.entries(data)) {
+        const rule = rules.find((r) => r.field === key);
+        if (rule) {
+            result[key] = applyMask(value, rule.options);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Apply masking to an array of instances.
+ */
+function maskMany(instances, role, Model) {
+    return instances.map((inst) => mask(inst, role, Model));
+}
+// ==================== Hook Wiring ====================
+/**
+ * Wire afterFind hooks onto a model to automatically mask results.
+ *
+ *   DataMasker.applyHooks(User);
+ */
+function applyHooks(Model) {
+    const rules = getMaskRules(Model);
+    if (rules.length === 0)
+        return;
+    const hookName = 'orm:dataMasker';
+    if (typeof Model.addHook === 'function') {
+        Model.addHook('afterFind', hookName, (result) => {
+            const maskOne = (instance) => {
+                if (!instance)
+                    return;
+                const data = instance.toJSON ? instance.toJSON() : instance;
+                for (const rule of rules) {
+                    const value = data[rule.field];
+                    if (value != null) {
+                        const masked = applyMask(value, rule.options);
+                        if (instance.setDataValue) {
+                            instance.setDataValue(rule.field, masked);
+                        }
+                        else {
+                            instance[rule.field] = masked;
+                        }
+                    }
+                }
+            };
+            if (Array.isArray(result)) {
+                result.forEach(maskOne);
+            }
+            else {
+                maskOne(result);
+            }
+        });
+    }
+}
+// ==================== Class Export ====================
+/** Static facade bundling the masking API (mirrors the module-level functions). */
+class DataMasker {
+}
+exports.DataMasker = DataMasker;
+DataMasker.maskField = maskField;
+DataMasker.getRules = getMaskRules;
+DataMasker.mask = mask;
+DataMasker.maskMany = maskMany;
+DataMasker.maskValue = maskValue;
+DataMasker.applyHooks = applyHooks;

package/dist/compliance/data-portability.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * DataPortabilityExporter
+ *
+ * Exports data in machine-readable formats (JSON, CSV, NDJSON) for
+ * GDPR Art 20 / CCPA / CPRA data subject access requests (DSARs).
+ * Respects field-level permissions — strips restricted fields from export.
+ *
+ * Covers ~25 compliance frameworks including:
+ *   GDPR Art 20, CCPA, CPRA, LGPD, APPI, PDPA (Singapore, Philippines),
+ *   PoPI (South Africa), PIPEDA, and other data portability rights.
+ *
+ * Usage:
+ *   // Export all data for a user (JSON):
+ *   const export = await DataPortabilityExporter.export(User, {
+ *     where: { id: userId },
+ *     format: 'json',
+ *   });
+ *
+ *   // Export in CSV format:
+ *   const csv = await DataPortabilityExporter.export(User, {
+ *     where: { id: userId },
+ *     format: 'csv',
+ *     include: [Order, Address],  // also export associated models
+ *   });
+ *
+ *   // Export as NDJSON (newline-delimited JSON, better for large datasets):
+ *   const ndjson = await DataPortabilityExporter.export(User, {
+ *     where: { id: userId },
+ *     format: 'ndjson',
+ *   });
+ *
+ *   // Stream export (for very large datasets):
+ *   await DataPortabilityExporter.exportStream(User, {
+ *     where: { userId },
+ *     format: 'ndjson',
+ *     onChunk: (chunk) => stream.write(chunk),
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataPortabilityExporter = void 0;
+exports.exportData = exportData;
+exports.exportStream = exportStream;
+exports.createDSARResponse = createDSARResponse;
+const permissions_1 = require("../decorators/permissions");
+/**
+ * Get the list of attribute names defined on a model.
+ * Used as the default attribute universe for permission filtering when
+ * no explicit per-field rules have been registered for the model.
+ */
+function getModelAttributeNames(Model) {
+    if (Model?.rawAttributes) {
+        return Object.keys(Model.rawAttributes);
+    }
+    if (typeof Model?.getAttributes === 'function') {
+        return Object.keys(Model.getAttributes());
+    }
+    return [];
+}
+/**
+ * Convert a plain object to CSV row.
+ */
+function toCSVRow(obj, headers) {
+    return headers
+        .map((h) => {
+        const value = obj[h];
+        if (value == null)
+            return '';
+        const str = String(value);
+        // Escape quotes and wrap in quotes if contains comma/quote/newline
+        if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+            return `"${str.replace(/"/g, '""')}"`;
+        }
+        return str;
+    })
+        .join(',');
+}
+/**
+ * Export associated data recursively.
+ */
+async function exportAssociations(instance, include, role) {
+    const result = {};
+    for (const assoc of include) {
+        const model = assoc.model ?? assoc;
+        const as = assoc.as ?? model.name?.toLowerCase() ?? 'association';
+        // Get the associated records
+        const associated = await instance[as]?.();
+        if (!associated)
+            continue;
+        if (Array.isArray(associated)) {
+            // Filter by permissions
+            const filtered = await Promise.all(associated.map(async (item) => {
+                const data = item.toJSON ? item.toJSON() : item;
+                const allowed = (0, permissions_1.getAllowedAttributes)(model, role);
+                const filtered = {};
+                for (const key of allowed) {
+                    filtered[key] = data[key];
+                }
+                return filtered;
+            }));
+            result[as] = filtered;
+        }
+        else {
+            const data = associated.toJSON ? associated.toJSON() : associated;
+            const allowed = (0, permissions_1.getAllowedAttributes)(model, role);
+            const filtered = {};
+            for (const key of allowed) {
+                filtered[key] = data[key];
+            }
+            result[as] = filtered;
+        }
+    }
+    return result;
+}
+/**
+ * Main export function.
+ */
+async function exportData(Model, options) {
+    const { where = {}, include = [], format = 'json', excludeForRole, limit } = options;
+    const role = excludeForRole ?? 'export';
+    const allowedAttrs = (0, permissions_1.getAllowedAttributes)(Model, role, getModelAttributeNames(Model));
+    // Fetch the main records
+    const records = await Model.findAll({
+        where,
+        include,
+        limit,
+        order: options.order,
+    });
+    if (records.length === 0) {
+        return {
+            format,
+            content: format === 'csv' ? '' : '[]',
+            recordCount: 0,
+            exportedAt: new Date(),
+            includedModels: [Model.name, ...include.map((m) => m.model?.name ?? m.name ?? 'assoc')],
+        };
+    }
+    // Process each record
+    const processed = [];
+    for (const record of records) {
+        const base = record.toJSON ? record.toJSON() : record;
+        const filtered = {};
+        // Only include allowed attributes
+        for (const key of allowedAttrs) {
+            if (base[key] !== undefined) {
+                filtered[key] = base[key];
+            }
+        }
+        // Include associations if requested
+        if (include.length > 0) {
+            const assocData = await exportAssociations(record, include, role);
+            Object.assign(filtered, assocData);
+        }
+        processed.push(filtered);
+    }
+    // Format the output
+    let content;
+    if (format === 'json') {
+        content = JSON.stringify(processed, null, 2);
+    }
+    else if (format === 'csv') {
+        const headers = Object.keys(processed[0]);
+        const headerRow = headers.join(',');
+        const dataRows = processed.map((row) => toCSVRow(row, headers));
+        content = [headerRow, ...dataRows].join('\n');
+    }
+    else if (format === 'ndjson') {
+        // NDJSON convention: every record (including the last) is terminated by '\n'.
+        content = processed.map((row) => `${JSON.stringify(row)}\n`).join('');
+    }
+    else {
+        throw new Error(`[DataPortabilityExporter] Unsupported format: ${format}`);
+    }
+    return {
+        format,
+        content,
+        recordCount: processed.length,
+        exportedAt: new Date(),
+        includedModels: [Model.name, ...include.map((m) => m.model?.name ?? m.name ?? 'assoc')],
+    };
+}
+/**
+ * Stream export for large datasets.
+ * Writes directly to a callback to avoid loading everything in memory.
+ */
+async function exportStream(Model, options) {
+    const { where = {}, include = [], format = 'ndjson', onChunk, batchSize = 100 } = options;
+    const role = options.excludeForRole ?? 'export';
+    const allowedAttrs = (0, permissions_1.getAllowedAttributes)(Model, role, getModelAttributeNames(Model));
+    let offset = 0;
+    let recordCount = 0;
+    let batch = [];
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const records = await Model.findAll({
+            where,
+            include,
+            limit: batchSize,
+            offset,
+            order: options.order,
+        });
+        if (records.length === 0)
+            break;
+        for (const record of records) {
+            const base = record.toJSON ? record.toJSON() : record;
+            const filtered = {};
+            for (const key of allowedAttrs) {
+                if (base[key] !== undefined) {
+                    filtered[key] = base[key];
+                }
+            }
+            if (include.length > 0) {
+                const assocData = await exportAssociations(record, include, role);
+                Object.assign(filtered, assocData);
+            }
+            if (format === 'csv') {
+                // CSV streaming is complex — fall back to NDJSON for streaming
+                batch.push(filtered);
+            }
+            else {
+                // NDJSON
+                await onChunk(JSON.stringify(filtered) + '\n');
+            }
+            recordCount++;
+        }
+        offset += batchSize;
+        // For CSV, we need to collect headers first
+        if (format === 'csv' && batch.length > 0) {
+            const headers = Object.keys(batch[0]);
+            const headerRow = headers.join(',');
+            await onChunk(headerRow + '\n');
+            for (const row of batch) {
+                await onChunk(toCSVRow(row, headers) + '\n');
+            }
+            batch = [];
+        }
+    }
+    return { recordCount, exportedAt: new Date() };
+}
+/**
+ * Generate a DSAR response object ready for API return.
+ */
+async function createDSARResponse(subjectId, models, options = {}) {
+    const exports = [];
+    for (const { model, where } of models) {
+        const exp = await exportData(model, {
+            where: { ...where, id: subjectId },
+            format: options.format ?? 'json',
+            include: options.include,
+        });
+        exports.push(exp);
+    }
+    return {
+        subjectId,
+        requestedAt: new Date(),
+        exports,
+    };
+}
+// ==================== Class Export ====================
+class DataPortabilityExporter {
+}
+exports.DataPortabilityExporter = DataPortabilityExporter;
+DataPortabilityExporter.export = exportData;
+DataPortabilityExporter.exportStream = exportStream;
+DataPortabilityExporter.createDSARResponse = createDSARResponse;