ts-prorm-orm 1.1.0

package/dist/compliance/cross-border-log.js

@@ -0,0 +1,530 @@
+"use strict";
+/**
+ * CrossBorderLog
+ *
+ * Logs when data crosses geo boundaries, tracking data transfers between
+ * regions/countries. Required for GDPR, PIPL, and DPDPA India compliance.
+ *
+ * Covers ~30 compliance frameworks including:
+ *   GDPR Art 44-49, PIPL, DPDPA India, CCPA, LGPD Brazil, POPIA South Africa,
+ *   PDPA Thailand, APPI Japan, and cross-border transfer requirements.
+ *
+ * Usage:
+ *   // Initialize tracking on a model:
+ *   CrossBorderLog.enable(prorm, User);
+ *
+ *   // Log a cross-border transfer:
+ *   await CrossBorderLog.logTransfer('EU', 'US', 'PII', userRecords);
+ *
+ *   // Get transfer history for a record:
+ *   const history = await CrossBorderLog.getTransferHistory(User, userId);
+ *
+ *   // Check if transfer is allowed:
+ *   const allowed = await CrossBorderLog.checkTransferAllowed('CN', 'US');
+ *
+ *   // Configure regions for compliance:
+ *   CrossBorderLog.configureRegions({
+ *     'EU': { adequateProtection: true, regulations: ['GDPR'] },
+ *     'US': { adequateProtection: false, regulations: ['CCPA'] },
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrossBorderLog = void 0;
+exports.getComplianceTransfers = getComplianceTransfers;
+exports.generateTransferReport = generateTransferReport;
+const data_types_1 = require("../models/data-types");
+// ==================== Symbol Keys ====================
+const TRANSFER_OPTIONS_KEY = '__orm_transfer_options__';
+const transferRegistry = new Map();
+// Default region configurations (can be customized)
+const defaultRegions = {
+    // European Union (adequate protection under GDPR)
+    'EU': { adequateProtection: true, regulations: ['GDPR'] },
+    'EEA': { adequateProtection: true, regulations: ['GDPR'] },
+    'UK': { adequateProtection: true, regulations: ['GDPR', 'UK GDPR'] },
+    // Countries with adequate protection decisions
+    'CA': { adequateProtection: true, regulations: ['PIPEDA'] },
+    'JP': { adequateProtection: true, regulations: ['APPI'] },
+    'KR': { adequateProtection: true, regulations: ['PIPA'] },
+    'GB': { adequateProtection: true, regulations: ['GDPR', 'UK GDPR'] },
+    'AR': { adequateProtection: true, regulations: ['PDPA'] },
+    'UY': { adequateProtection: true, regulations: ['LGPD'] },
+    // Countries WITHOUT adequate protection (need SCCs or other mechanisms)
+    'US': { adequateProtection: false, regulations: ['CCPA'], restrictions: ['requires_scc'] },
+    'CN': { adequateProtection: false, regulations: ['PIPL'], restrictions: ['requires_assessment'] },
+    'IN': { adequateProtection: false, regulations: ['DPDPA'], restrictions: ['requires_notice'] },
+    'BR': { adequateProtection: false, regulations: ['LGPD'], restrictions: ['requires_consent'] },
+    'TH': { adequateProtection: false, regulations: ['PDPA'], restrictions: ['requires_consent'] },
+    'SG': { adequateProtection: false, regulations: ['PDPA'], restrictions: ['requires_assessment'] },
+    'AU': { adequateProtection: false, regulations: ['Privacy Act'], restrictions: ['requires_notice'] },
+    'NZ': { adequateProtection: false, regulations: ['Privacy Act'], restrictions: ['requires_notice'] },
+};
+// Custom region configurations (set by user)
+const customRegions = new Map();
+// Master region config (combines defaults and custom)
+const regionConfigs = new Map(Object.entries(defaultRegions));
+// ==================== Model Creation ====================
+function createTransferModel(prorm, tableName) {
+    const TransferModel = prorm.define('CrossBorderTransfer', {
+        id: {
+            type: data_types_1.DataTypes.INTEGER(),
+            primaryKey: true,
+            autoIncrement: true,
+        },
+        recordId: {
+            type: data_types_1.DataTypes.STRING(),
+            allowNull: false,
+        },
+        tableName: {
+            type: data_types_1.DataTypes.STRING(),
+            allowNull: false,
+        },
+        sourceRegion: {
+            type: data_types_1.DataTypes.STRING(),
+            allowNull: false,
+        },
+        targetRegion: {
+            type: data_types_1.DataTypes.STRING(),
+            allowNull: false,
+        },
+        dataType: {
+            type: data_types_1.DataTypes.ENUM('PII', 'PHI', 'PCI', 'FINANCIAL', 'BIOMETRIC', 'SENSITIVE', 'GENERAL'),
+            allowNull: false,
+        },
+        recordCount: {
+            type: data_types_1.DataTypes.INTEGER(),
+            allowNull: false,
+            defaultValue: 1,
+        },
+        status: {
+            type: data_types_1.DataTypes.ENUM('pending', 'completed', 'blocked', 'reviewed'),
+            allowNull: false,
+            defaultValue: 'completed',
+        },
+        transferredAt: {
+            type: data_types_1.DataTypes.DATE(),
+            allowNull: false,
+            defaultValue: data_types_1.DataTypes.NOW,
+        },
+        initiatedBy: {
+            type: data_types_1.DataTypes.STRING(),
+            allowNull: true,
+        },
+        purpose: {
+            type: data_types_1.DataTypes.STRING(),
+            allowNull: true,
+        },
+        legalBasis: {
+            type: data_types_1.DataTypes.STRING(),
+            allowNull: true,
+        },
+        metadata: {
+            type: data_types_1.DataTypes.JSON(),
+            allowNull: true,
+        },
+    }, {
+        tableName,
+        timestamps: true,
+        indexes: [
+            { fields: ['recordId', 'tableName'] },
+            { fields: ['sourceRegion', 'targetRegion'] },
+            { fields: ['dataType'] },
+            { fields: ['status'] },
+            { fields: ['transferredAt'] },
+        ],
+    });
+    return TransferModel;
+}
+// ==================== CrossBorderLog Class ====================
+class CrossBorderLog {
+    /**
+     * Enable cross-border transfer logging on a model.
+     * Creates necessary tables and registers hooks.
+     *
+     * @param prorm - The Prorm instance
+     * @param model     - The model class to track
+     * @param options   - Optional configuration
+     */
+    static enable(prorm, model, options = {}) {
+        const tableName = options.tableName ?? 'CrossBorderTransfers';
+        const transferModel = createTransferModel(prorm, tableName);
+        const config = {
+            model,
+            prorm,
+            options: {
+                tableName,
+                getUserId: options.getUserId ?? (() => undefined),
+                getIpAddress: options.getIpAddress ?? (() => undefined),
+                autoLog: options.autoLog ?? true,
+                requireApproval: options.requireApproval ?? (() => true),
+            },
+            transferModel,
+        };
+        transferRegistry.set(model, config);
+        // Apply hooks if autoLog is enabled
+        if (config.options.autoLog) {
+            this.applyHooks(model, config);
+        }
+    }
+    /**
+     * Apply hooks to a model for automatic transfer logging.
+     * Called automatically by enable() when autoLog is true.
+     *
+     * @param model  - The model class
+     * @param config - The transfer configuration
+     */
+    static applyHooks(model, config) {
+        const cfg = config ?? transferRegistry.get(model);
+        if (!cfg) {
+            throw new Error(`[CrossBorderLog] No transfer configuration found for model "${model.name ?? model}". ` +
+                `Call CrossBorderLog.enable(prorm, Model) first.`);
+        }
+        const { transferModel, options } = cfg;
+        const hookName = 'orm:crossBorderLog';
+        // beforeCreate hook - could auto-log creation if needed
+        model.addHook('beforeCreate', hookName, async function (record) {
+            // Store metadata for potential transfer logging
+            record.__transferMetadata = {
+                createdAt: new Date(),
+                initiatedBy: options.getUserId(),
+            };
+        });
+    }
+    /**
+     * Configure custom region settings.
+     * Merges with default region configs.
+     *
+     * @param regions - Map of region codes to their configurations
+     */
+    static configureRegions(regions) {
+        for (const [code, config] of Object.entries(regions)) {
+            regionConfigs.set(code.toUpperCase(), config);
+            customRegions.set(code.toUpperCase(), config);
+        }
+    }
+    /**
+     * Get region configuration.
+     *
+     * @param regionCode - The region code
+     */
+    static getRegionConfig(regionCode) {
+        return regionConfigs.get(regionCode.toUpperCase());
+    }
+    /**
+     * Log a cross-border data transfer.
+     *
+     * @param sourceRegion - Source region code (e.g., 'EU', 'US')
+     * @param targetRegion - Target region code
+     * @param dataType     - Category of data being transferred
+     * @param records      - Record IDs or array of record data
+     * @param options      - Additional transfer details
+     */
+    static async logTransfer(sourceRegion, targetRegion, dataType, records, options) {
+        // Find a registered model or use default
+        let config;
+        for (const [, cfg] of transferRegistry) {
+            if (options?.tableName && (cfg.model.tableName ?? cfg.model.name) === options.tableName) {
+                config = cfg;
+                break;
+            }
+            config = cfg;
+        }
+        if (!config) {
+            throw new Error(`[CrossBorderLog] No model registered. Call CrossBorderLog.enable(prorm, Model) first.`);
+        }
+        const { transferModel } = config;
+        const recordCount = Array.isArray(records) ? records.length : 1;
+        const recordId = options?.recordId ?? (Array.isArray(records) && records[0]?.id) ?? 'unknown';
+        const transfer = await transferModel.create({
+            recordId: String(recordId),
+            tableName: options?.tableName ?? config.model.tableName ?? config.model.name,
+            sourceRegion: sourceRegion.toUpperCase(),
+            targetRegion: targetRegion.toUpperCase(),
+            dataType,
+            recordCount,
+            status: options?.status ?? 'completed',
+            transferredAt: new Date(),
+            initiatedBy: options?.initiatedBy ?? config.options.getUserId(),
+            purpose: options?.purpose,
+            legalBasis: options?.legalBasis,
+            metadata: options?.metadata,
+        });
+        return transfer.toJSON();
+    }
+    /**
+     * Get transfer history for a specific record.
+     *
+     * @param model    - The model class
+     * @param recordId - The record ID to get history for
+     */
+    static async getTransferHistory(model, recordId) {
+        const config = transferRegistry.get(model);
+        if (!config) {
+            throw new Error(`[CrossBorderLog] No transfer configuration found for model "${model.name ?? model}". ` +
+                `Call CrossBorderLog.enable(prorm, Model) first.`);
+        }
+        const { transferModel } = config;
+        const transfers = await transferModel.findAll({
+            where: { recordId: String(recordId) },
+            order: [['transferredAt', 'DESC']],
+        });
+        return transfers.map((t) => t.toJSON());
+    }
+    /**
+     * Get all transfer records for a model.
+     *
+     * @param model   - The model class
+     * @param options - Filter options (source, target, status, date range)
+     */
+    static async getAllTransfers(model, options) {
+        const config = transferRegistry.get(model);
+        if (!config) {
+            throw new Error(`[CrossBorderLog] No transfer configuration found for model "${model.name ?? model}". ` +
+                `Call CrossBorderLog.enable(prorm, Model) first.`);
+        }
+        const { transferModel } = config;
+        const where = {};
+        if (options?.sourceRegion) {
+            where.sourceRegion = options.sourceRegion.toUpperCase();
+        }
+        if (options?.targetRegion) {
+            where.targetRegion = options.targetRegion.toUpperCase();
+        }
+        if (options?.dataType) {
+            where.dataType = options.dataType;
+        }
+        if (options?.status) {
+            where.status = options.status;
+        }
+        if (options?.startDate || options?.endDate) {
+            where.transferredAt = {};
+            if (options?.startDate) {
+                where.transferredAt['$gte'] = options.startDate;
+            }
+            if (options?.endDate) {
+                where.transferredAt['$lte'] = options.endDate;
+            }
+        }
+        const transfers = await transferModel.findAll({
+            where,
+            order: [['transferredAt', 'DESC']],
+            limit: options?.limit ?? 100,
+            offset: options?.offset ?? 0,
+        });
+        return transfers.map((t) => t.toJSON());
+    }
+    /**
+     * Check if a cross-border transfer is allowed.
+     * Evaluates based on source/target region configurations.
+     *
+     * @param sourceRegion - Source region code
+     * @param targetRegion - Target region code
+     * @param dataType     - Optional data type for additional checks
+     */
+    static async checkTransferAllowed(sourceRegion, targetRegion, dataType) {
+        const source = regionConfigs.get(sourceRegion.toUpperCase());
+        const target = regionConfigs.get(targetRegion.toUpperCase());
+        // Both regions must be known
+        if (!source && sourceRegion.toUpperCase() !== 'UNKNOWN') {
+            return {
+                allowed: false,
+                reason: `Unknown source region: ${sourceRegion}`,
+                requiresReview: true,
+            };
+        }
+        if (!target && targetRegion.toUpperCase() !== 'UNKNOWN') {
+            return {
+                allowed: false,
+                reason: `Unknown target region: ${targetRegion}`,
+                requiresReview: true,
+            };
+        }
+        // Unknown regions always require review
+        if (sourceRegion.toUpperCase() === 'UNKNOWN' || targetRegion.toUpperCase() === 'UNKNOWN') {
+            return {
+                allowed: true, // Allow but flag for review
+                reason: 'One or both regions are unknown - manual review recommended',
+                requiresReview: true,
+            };
+        }
+        // Check if target has adequate protection
+        if (!target?.adequateProtection) {
+            // Check for specific restrictions based on data type
+            if (dataType === 'PII' || dataType === 'PHI') {
+                const regulations = [...(source?.regulations ?? []), ...(target?.regulations ?? [])];
+                return {
+                    allowed: false,
+                    reason: `Transfer to ${targetRegion} requires additional safeguards (SCCs, BCRs, or adequacy decision)`,
+                    requiresReview: true,
+                    regulations,
+                };
+            }
+            return {
+                allowed: true,
+                reason: `Transfer to ${targetRegion} - target does not have adequate protection determination`,
+                requiresReview: true,
+                regulations: target?.regulations,
+            };
+        }
+        // Target has adequate protection
+        const regulations = [...(source?.regulations ?? []), ...(target?.regulations ?? [])];
+        return {
+            allowed: true,
+            reason: `Transfer to ${targetRegion} - adequate protection in place`,
+            requiresReview: false,
+            regulations,
+        };
+    }
+    /**
+     * Get all regions with their configurations.
+     */
+    static listRegions() {
+        return Array.from(regionConfigs.entries()).map(([code, config]) => ({
+            code,
+            config,
+        }));
+    }
+    /**
+     * Get transfer model for a model.
+     *
+     * @param model - The model class
+     */
+    static getTransferModel(model) {
+        return transferRegistry.get(model)?.transferModel;
+    }
+    /**
+     * Disable transfer logging for a model.
+     *
+     * @param model - The model class
+     */
+    static disable(model) {
+        const config = transferRegistry.get(model);
+        if (config) {
+            // Remove hooks
+            const hookName = 'orm:crossBorderLog';
+            if (typeof config.model.removeHook === 'function') {
+                config.model.removeHook(hookName);
+            }
+            transferRegistry.delete(model);
+        }
+    }
+    /**
+     * List all models with transfer logging enabled.
+     */
+    static listTrackedModels() {
+        return Array.from(transferRegistry.entries()).map(([model, config]) => ({
+            modelName: model.name ?? String(model),
+            options: config.options,
+        }));
+    }
+    /**
+     * Check if a model has transfer logging enabled.
+     *
+     * @param model - The model class
+     */
+    static isEnabled(model) {
+        return transferRegistry.has(model);
+    }
+    /**
+     * Reset all custom region configurations to defaults.
+     */
+    static resetRegions() {
+        customRegions.clear();
+        regionConfigs.clear();
+        for (const [code, config] of Object.entries(defaultRegions)) {
+            regionConfigs.set(code, config);
+        }
+    }
+}
+exports.CrossBorderLog = CrossBorderLog;
+// ==================== Utility Functions ====================
+/**
+ * Get all transfers for compliance reporting.
+ *
+ * @param prorm - The Prorm instance
+ * @param options   - Filter options
+ */
+async function getComplianceTransfers(prorm, options) {
+    const { CrossBorderTransfer } = prorm.models;
+    if (!CrossBorderTransfer) {
+        throw new Error('[CrossBorderLog] Transfer model not found. Initialize with CrossBorderLog.enable() first.');
+    }
+    const where = {};
+    if (options?.startDate || options?.endDate) {
+        where.transferredAt = {};
+        if (options?.startDate) {
+            where.transferredAt['$gte'] = options.startDate;
+        }
+        if (options?.endDate) {
+            where.transferredAt['$lte'] = options.endDate;
+        }
+    }
+    if (options?.regions && options.regions.length > 0) {
+        const upperRegions = options.regions.map((r) => r.toUpperCase());
+        where['$or'] = [
+            { sourceRegion: { $in: upperRegions } },
+            { targetRegion: { $in: upperRegions } },
+        ];
+    }
+    if (options?.dataTypes && options.dataTypes.length > 0) {
+        where.dataType = { $in: options.dataTypes };
+    }
+    const transfers = await CrossBorderTransfer.findAll({
+        where,
+        order: [['transferredAt', 'DESC']],
+    });
+    return transfers.map((t) => t.toJSON());
+}
+/**
+ * Generate a compliance report for cross-border transfers.
+ *
+ * @param prorm - The Prorm instance
+ * @param options   - Report options
+ */
+async function generateTransferReport(prorm, options) {
+    const transfers = await getComplianceTransfers(prorm, {
+        startDate: options?.startDate,
+        endDate: options?.endDate,
+    });
+    const uniqueRegions = new Set();
+    const dataTypes = {
+        PII: 0,
+        PHI: 0,
+        PCI: 0,
+        FINANCIAL: 0,
+        BIOMETRIC: 0,
+        SENSITIVE: 0,
+        GENERAL: 0,
+    };
+    for (const transfer of transfers) {
+        uniqueRegions.add(transfer.sourceRegion);
+        uniqueRegions.add(transfer.targetRegion);
+        dataTypes[transfer.dataType] = (dataTypes[transfer.dataType] ?? 0) + 1;
+    }
+    const report = {
+        summary: {
+            totalTransfers: transfers.length,
+            uniqueRegions: uniqueRegions.size,
+            dataTypes,
+        },
+        transfers,
+    };
+    if (options?.groupByRegion) {
+        const byRegion = {};
+        for (const transfer of transfers) {
+            const key = `${transfer.sourceRegion}_to_${transfer.targetRegion}`;
+            if (!byRegion[key]) {
+                byRegion[key] = {
+                    sourceRegion: transfer.sourceRegion,
+                    targetRegion: transfer.targetRegion,
+                    count: 0,
+                    dataTypes: { ...dataTypes },
+                };
+            }
+            byRegion[key].count++;
+            byRegion[key].dataTypes[transfer.dataType]++;
+        }
+        report.byRegion = byRegion;
+    }
+    return report;
+}