ts-prorm-orm 1.1.0

package/dist/compliance/privacy-impact-assessment.js

@@ -0,0 +1,364 @@
+"use strict";
+/**
+ * PrivacyImpactAssessment
+ *
+ * A ready-made model and service for conducting Privacy Impact Assessments (PIA)
+ * and Data Protection Impact Assessments (DPIA) for high-risk data processing.
+ *
+ * Covers compliance frameworks including:
+ *   GDPR Art. 35 (DPIA), ISO 27701, UK GDPR, CCPA, PIPEDA,
+ *   LGPD (Brazil), APPI (Japan), PDPA (Thailand, Singapore), and more.
+ *
+ * Usage:
+ *   // Initialize once (creates the pia_assessments table):
+ *   await PrivacyImpactAssessment.initialize(prorm);
+ *
+ *   // Create a new PIA:
+ *   const assessment = await PrivacyImpactAssessment.createAssessment(
+ *     'User Analytics Processing',
+ *     ['email', 'ip_address', 'behavioral_data'],
+ *     'analyze_user_behavior_for_product_improvement'
+ *   );
+ *
+ *   // Record identified risks:
+ *   await PrivacyImpactAssessment.recordRisk(
+ *     assessment.id,
+ *     'Potential data breach exposing user profiles',
+ *     'high',
+ *   *   'Implement AES-256 encryption at rest and TLS 1.3 in transit'
+ *   );
+ *
+ *   // Approve the assessment:
+ *   await PrivacyImpactAssessment.approveAssessment(assessment.id, 'DPO John Smith');
+ *
+ *   // Link to a model:
+ *   await PrivacyImpactAssessment.linkToModel(assessment.id, UserAnalytics);
+ *
+ *   // Get assessment details:
+ *   const details = await PrivacyImpactAssessment.getAssessment(assessment.id);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrivacyImpactAssessment = void 0;
+const data_types_1 = require("../models/data-types");
+const operators_1 = require("../models/operators");
+let PIAModel = null;
+let RiskModel = null;
+class PrivacyImpactAssessment {
+    /**
+     * Initialize the PrivacyImpactAssessment model and sync the tables.
+     * Call once at application startup.
+     *
+     * @param prorm - The Prorm instance
+     * @param tableName - Override the default table name 'pia_assessments'
+     */
+    static async initialize(prorm, tableName = 'pia_assessments') {
+        PIAModel = prorm.define('PIAContainer', {
+            id: {
+                type: data_types_1.DataTypes.INTEGER(),
+                primaryKey: true,
+                autoIncrement: true,
+            },
+            name: {
+                type: data_types_1.DataTypes.STRING(255),
+                allowNull: false,
+                comment: 'Name/title of the privacy impact assessment',
+            },
+            dataTypes: {
+                type: data_types_1.DataTypes.JSON(),
+                allowNull: false,
+                comment: 'List of data types being processed',
+            },
+            processingPurpose: {
+                type: data_types_1.DataTypes.TEXT(),
+                allowNull: false,
+                comment: 'Purpose of the data processing',
+            },
+            status: {
+                type: data_types_1.DataTypes.ENUM('draft', 'in_review', 'approved', 'rejected', 'archived'),
+                allowNull: false,
+                defaultValue: 'draft',
+                comment: 'Current status of the assessment',
+            },
+            approvedBy: {
+                type: data_types_1.DataTypes.STRING(255),
+                allowNull: true,
+                comment: 'Name/ID of the approver (DPO, compliance officer)',
+            },
+            approvedAt: {
+                type: data_types_1.DataTypes.DATE(),
+                allowNull: true,
+                comment: 'Timestamp when the assessment was approved',
+            },
+            linkedModels: {
+                type: data_types_1.DataTypes.JSON(),
+                allowNull: true,
+                comment: 'List of model names linked to this assessment',
+            },
+            metadata: {
+                type: data_types_1.DataTypes.JSON(),
+                allowNull: true,
+                comment: 'Additional structured metadata',
+            },
+        }, {
+            tableName,
+            timestamps: true,
+            underscored: true,
+            indexes: [
+                { fields: ['status'] },
+                { fields: ['name'] },
+            ],
+        });
+        RiskModel = prorm.define('PIARisk', {
+            id: {
+                type: data_types_1.DataTypes.INTEGER(),
+                primaryKey: true,
+                autoIncrement: true,
+            },
+            assessmentId: {
+                type: data_types_1.DataTypes.INTEGER(),
+                allowNull: false,
+                references: {
+                    model: tableName,
+                    key: 'id',
+                },
+                comment: 'Foreign key to the parent PIA assessment',
+            },
+            risk: {
+                type: data_types_1.DataTypes.TEXT(),
+                allowNull: false,
+                comment: 'Description of the identified risk',
+            },
+            severity: {
+                type: data_types_1.DataTypes.ENUM('low', 'medium', 'high', 'critical'),
+                allowNull: false,
+                comment: 'Severity level of the risk',
+            },
+            mitigation: {
+                type: data_types_1.DataTypes.TEXT(),
+                allowNull: true,
+                comment: 'Mitigation measures for the risk',
+            },
+        }, {
+            tableName: `${tableName}_risks`,
+            timestamps: true,
+            underscored: true,
+            indexes: [
+                { fields: ['assessment_id'] },
+                { fields: ['severity'] },
+            ],
+        });
+        await PIAModel.sync({ alter: false });
+        await RiskModel.sync({ alter: false });
+    }
+    static requireModels() {
+        if (!PIAModel || !RiskModel) {
+            throw new Error('[PrivacyImpactAssessment] Not initialized. Call PrivacyImpactAssessment.initialize(prorm) first.');
+        }
+        return { pia: PIAModel, risk: RiskModel };
+    }
+    /**
+     * Create a new Privacy Impact Assessment.
+     *
+     * @param name - Name/title of the assessment
+     * @param dataTypes - List of data types being processed
+     * @param processingPurpose - Purpose of the processing operation
+     * @returns The created PIA record
+     */
+    static async createAssessment(name, dataTypes, processingPurpose) {
+        const { pia } = PrivacyImpactAssessment.requireModels();
+        return pia.create({
+            name,
+            dataTypes,
+            processingPurpose,
+            status: 'draft',
+        });
+    }
+    /**
+     * Record a risk associated with a PIA assessment.
+     *
+     * @param assessmentId - The ID of the assessment to add the risk to
+     * @param risk - Description of the identified risk
+     * @param severity - Severity level of the risk
+     * @param mitigation - Mitigation measures for the risk
+     * @returns The created risk record
+     */
+    static async recordRisk(assessmentId, risk, severity, mitigation) {
+        const { risk: RiskModelClass } = PrivacyImpactAssessment.requireModels();
+        return RiskModelClass.create({
+            assessmentId,
+            risk,
+            severity,
+            mitigation,
+        });
+    }
+    /**
+     * Approve a Privacy Impact Assessment.
+     * Sets status to 'approved' and records approver information.
+     *
+     * @param assessmentId - The ID of the assessment to approve
+     * @param approver - Name/ID of the approver (e.g., DPO name)
+     * @returns The updated PIA record
+     */
+    static async approveAssessment(assessmentId, approver) {
+        const { pia } = PrivacyImpactAssessment.requireModels();
+        const assessment = await pia.findByPk(assessmentId);
+        if (!assessment) {
+            throw new Error(`[PrivacyImpactAssessment] Assessment not found: ${assessmentId}`);
+        }
+        await assessment.update({
+            status: 'approved',
+            approvedBy: approver,
+            approvedAt: new Date(),
+        });
+        return assessment;
+    }
+    /**
+     * Get a Privacy Impact Assessment by ID.
+     * Includes associated risks.
+     *
+     * @param assessmentId - The ID of the assessment to retrieve
+     * @returns The PIA record with associated risks
+     */
+    static async getAssessment(assessmentId) {
+        const { pia, risk } = PrivacyImpactAssessment.requireModels();
+        return pia.findByPk(assessmentId, {
+            include: [
+                {
+                    model: risk,
+                    as: 'risks',
+                },
+            ],
+        });
+    }
+    /**
+     * Link a model to a PIA assessment.
+     * Useful for tracking which models are covered by the assessment.
+     *
+     * @param assessmentId - The ID of the assessment
+     * @param model - The model class to link (can be a Prorm model or string name)
+     * @returns The updated PIA record
+     */
+    static async linkToModel(assessmentId, model) {
+        const { pia } = PrivacyImpactAssessment.requireModels();
+        const assessment = await pia.findByPk(assessmentId);
+        if (!assessment) {
+            throw new Error(`[PrivacyImpactAssessment] Assessment not found: ${assessmentId}`);
+        }
+        const modelName = typeof model === 'string' ? model : (model.tableName ?? model.name ?? 'Unknown');
+        const currentLinkedModels = assessment.linkedModels ?? [];
+        if (!currentLinkedModels.includes(modelName)) {
+            await assessment.update({
+                linkedModels: [...currentLinkedModels, modelName],
+            });
+        }
+        return assessment;
+    }
+    /**
+     * Get all assessments with a specific status.
+     *
+     * @param status - The status to filter by
+     * @returns Array of PIA records matching the status
+     */
+    static async getByStatus(status) {
+        const { pia } = PrivacyImpactAssessment.requireModels();
+        return pia.findAll({
+            where: { status },
+            order: [['createdAt', 'DESC']],
+        });
+    }
+    /**
+     * Reject a Privacy Impact Assessment.
+     *
+     * @param assessmentId - The ID of the assessment to reject
+     * @param reason - Reason for rejection
+     * @returns The updated PIA record
+     */
+    static async rejectAssessment(assessmentId, reason) {
+        const { pia } = PrivacyImpactAssessment.requireModels();
+        const assessment = await pia.findByPk(assessmentId);
+        if (!assessment) {
+            throw new Error(`[PrivacyImpactAssessment] Assessment not found: ${assessmentId}`);
+        }
+        await assessment.update({
+            status: 'rejected',
+            metadata: {
+                ...(assessment.metadata ?? {}),
+                rejectionReason: reason,
+            },
+        });
+        return assessment;
+    }
+    /**
+     * Submit an assessment for review.
+     * Changes status from 'draft' to 'in_review'.
+     *
+     * @param assessmentId - The ID of the assessment to submit
+     * @returns The updated PIA record
+     */
+    static async submitForReview(assessmentId) {
+        const { pia } = PrivacyImpactAssessment.requireModels();
+        const assessment = await pia.findByPk(assessmentId);
+        if (!assessment) {
+            throw new Error(`[PrivacyImpactAssessment] Assessment not found: ${assessmentId}`);
+        }
+        if (assessment.status !== 'draft') {
+            throw new Error(`[PrivacyImpactAssessment] Only draft assessments can be submitted for review. Current status: ${assessment.status}`);
+        }
+        await assessment.update({
+            status: 'in_review',
+        });
+        return assessment;
+    }
+    /**
+     * Get all risks for an assessment grouped by severity.
+     *
+     * @param assessmentId - The ID of the assessment
+     * @returns Object with risks grouped by severity level
+     */
+    static async getRisksBySeverity(assessmentId) {
+        const { risk } = PrivacyImpactAssessment.requireModels();
+        const risks = await risk.findAll({
+            where: { assessmentId },
+            order: [['severity', 'DESC']],
+        });
+        return {
+            critical: risks.filter((r) => r.severity === 'critical'),
+            high: risks.filter((r) => r.severity === 'high'),
+            medium: risks.filter((r) => r.severity === 'medium'),
+            low: risks.filter((r) => r.severity === 'low'),
+        };
+    }
+    /**
+     * Check if an assessment has any high or critical risks without mitigations.
+     *
+     * @param assessmentId - The ID of the assessment
+     * @returns True if there are unresolved high-risk items
+     */
+    static async hasUnresolvedHighRisks(assessmentId) {
+        const { risk } = PrivacyImpactAssessment.requireModels();
+        const count = await risk.count({
+            where: {
+                [operators_1.Op.and]: [
+                    { assessmentId, severity: { [operators_1.Op.in]: ['high', 'critical'] } },
+                    { [operators_1.Op.or]: [{ mitigation: { [operators_1.Op.isNull]: true } }, { mitigation: '' }] },
+                ],
+            },
+        });
+        return count > 0;
+    }
+    /**
+     * List all models linked to a PIA assessment.
+     *
+     * @param assessmentId - The ID of the assessment
+     * @returns Array of linked model names
+     */
+    static async getLinkedModels(assessmentId) {
+        const { pia } = PrivacyImpactAssessment.requireModels();
+        const assessment = await pia.findByPk(assessmentId);
+        if (!assessment) {
+            throw new Error(`[PrivacyImpactAssessment] Assessment not found: ${assessmentId}`);
+        }
+        return assessment.linkedModels ?? [];
+    }
+}
+exports.PrivacyImpactAssessment = PrivacyImpactAssessment;

package/dist/compliance/pseudonymization.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * PseudonymizationService
+ *
+ * Replaces identifiers with non-reversible tokens for analytics, logging,
+ * and cross-system sharing while preserving referential integrity.
+ * Supports deterministic tokenization (same input → same token) using HMAC-SHA256.
+ *
+ * Covers ~34 compliance frameworks including:
+ *   GDPR Art 25 (Privacy by Design), ISO 27701, ISO 29151, HIPAA Safe Harbor,
+ *   PIPL (China), KVKK (Turkey), NIST SP 800-122, and more.
+ *
+ * Usage:
+ *   // Configure once at startup:
+ *   await PseudonymizationService.configure({
+ *     secretKey: process.env.PSEUDO_SECRET_KEY,
+ *     store: 'database', // or 'memory'
+ *   });
+ *
+ *   // Tokenize a value:
+ *   const token = await PseudonymizationService.tokenize('user-123');
+ *   // token: 'a1b2c3d4e5f6...' (deterministic, same input = same output)
+ *
+ *   // Detokenize (reverse):
+ *   const original = await PseudonymizationService.detokenize(token);
+ *   // original: 'user-123'
+ *
+ *   // Or use the decorator on a model field:
+ *   @Pseudonymize('nationalId')
+ *   class Patient extends Model { ... }
+ *
+ *   // Apply hooks to auto-tokenize on write:
+ *   PseudonymizationService.applyHooks(Patient, 'nationalId');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PseudonymizationService = void 0;
+exports.configure = configure;
+exports.tokenize = tokenize;
+exports.detokenize = detokenize;
+exports.exists = exists;
+exports.removeToken = removeToken;
+exports.removeOriginal = removeOriginal;
+exports.getPseudonymizedFields = getPseudonymizedFields;
+exports.Pseudonymize = Pseudonymize;
+exports.applyHooks = applyHooks;
+const crypto_1 = require("crypto");
+// In-memory storage for tokens
+const tokenStore = new Map();
+const reverseStore = new Map();
+let config = null;
+let tokenModel = null;
+/**
+ * Configure the pseudonymization service.
+ *
+ * @param cfg - Configuration options
+ */
+async function configure(cfg) {
+    if (!cfg.secretKey || cfg.secretKey.length < 32) {
+        throw new Error('[PseudonymizationService] secretKey must be at least 32 characters. ' +
+            'Use a strong, randomly generated key and store it securely.');
+    }
+    config = {
+        store: cfg.store ?? 'memory',
+        algorithm: cfg.algorithm ?? 'sha256',
+        ...cfg,
+    };
+    if (cfg.store === 'database' && cfg.model) {
+        tokenModel = cfg.model;
+        await tokenModel.sync?.({ alter: true });
+    }
+}
+function getConfig() {
+    if (!config) {
+        throw new Error('[PseudonymizationService] Not configured. Call await PseudonymizationService.configure({ secretKey }) first.');
+    }
+    return config;
+}
+/**
+ * Generate a deterministic HMAC token from a value.
+ */
+function generateToken(value) {
+    const cfg = getConfig();
+    const hmac = (0, crypto_1.createHmac)(cfg.algorithm, cfg.secretKey);
+    hmac.update(value);
+    return hmac.digest('hex');
+}
+/**
+ * Tokenize a value (replace with a pseudonym/token).
+ * Returns the same token for the same input (deterministic).
+ */
+async function tokenize(value) {
+    if (!value)
+        return '';
+    const cfg = getConfig();
+    // Check if we already have a token for this value
+    if (cfg.store === 'memory') {
+        const existing = reverseStore.get(value);
+        if (existing)
+            return existing;
+    }
+    else if (cfg.store === 'database' && tokenModel) {
+        const record = await tokenModel.findOne({ where: { original: value } });
+        if (record)
+            return record.token;
+    }
+    // Generate new token
+    const token = generateToken(value);
+    // Store the mapping
+    if (cfg.store === 'memory') {
+        tokenStore.set(token, { token, original: value, createdAt: new Date() });
+        reverseStore.set(value, token);
+    }
+    else if (cfg.store === 'database' && tokenModel) {
+        await tokenModel.findOrCreate({
+            where: { token },
+            defaults: { token, original: value, createdAt: new Date() },
+        });
+    }
+    return token;
+}
+/**
+ * Detokenize (reverse) a token to get the original value.
+ */
+async function detokenize(token) {
+    if (!token)
+        return null;
+    const cfg = getConfig();
+    if (cfg.store === 'memory') {
+        const record = tokenStore.get(token);
+        return record?.original ?? null;
+    }
+    else if (cfg.store === 'database' && tokenModel) {
+        const record = await tokenModel.findOne({ where: { token } });
+        return record?.original ?? null;
+    }
+    return null;
+}
+/**
+ * Check if a token exists.
+ */
+async function exists(token) {
+    if (!token)
+        return false;
+    const cfg = getConfig();
+    if (cfg.store === 'memory') {
+        return tokenStore.has(token);
+    }
+    else if (cfg.store === 'database' && tokenModel) {
+        const count = await tokenModel.count({ where: { token } });
+        return count > 0;
+    }
+    return false;
+}
+/**
+ * Delete a token (irreversible — useful for right to erasure).
+ */
+async function removeToken(token) {
+    if (!token)
+        return false;
+    const cfg = getConfig();
+    if (cfg.store === 'memory') {
+        const record = tokenStore.get(token);
+        if (record) {
+            reverseStore.delete(record.original);
+            tokenStore.delete(token);
+            return true;
+        }
+    }
+    else if (cfg.store === 'database' && tokenModel) {
+        const record = await tokenModel.findOne({ where: { token } });
+        if (record) {
+            await record.destroy();
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Delete tokens for a specific original value.
+ */
+async function removeOriginal(original) {
+    if (!original)
+        return false;
+    const cfg = getConfig();
+    if (cfg.store === 'memory') {
+        const token = reverseStore.get(original);
+        if (token) {
+            tokenStore.delete(token);
+            reverseStore.delete(original);
+            return true;
+        }
+    }
+    else if (cfg.store === 'database' && tokenModel) {
+        const record = await tokenModel.findOne({ where: { original } });
+        if (record) {
+            await record.destroy();
+            return true;
+        }
+    }
+    return false;
+}
+// ==================== Decorator ====================
+const PSEUDO_FIELDS_KEY = '__orm_pseudo_fields__';
+function getPseudonymizedFields(target) {
+    return target[PSEUDO_FIELDS_KEY] ?? [];
+}
+/**
+ * Mark a field for automatic pseudonymization.
+ *
+ *   @Pseudonymize('nationalId')
+ *   class Patient extends Model { ... }
+ */
+function Pseudonymize(field) {
+    return function (target) {
+        if (!target[PSEUDO_FIELDS_KEY]) {
+            target[PSEUDO_FIELDS_KEY] = [];
+        }
+        target[PSEUDO_FIELDS_KEY].push(field);
+    };
+}
+// ==================== Hook Wiring ====================
+/**
+ * Wire hooks onto a model to auto-tokenize the specified field on write
+ * and auto-detokenize on read.
+ *
+ * @param Model  - The model class
+ * @param field  - The field to pseudonymize
+ */
+function applyHooks(Model, field) {
+    const hookName = 'orm:pseudonymize';
+    if (typeof Model.addHook === 'function') {
+        // Tokenize before create/update
+        Model.addHook('beforeCreate', hookName, async (instance) => {
+            const value = instance.getDataValue ? instance.getDataValue(field) : instance[field];
+            if (value && typeof value === 'string' && !value.startsWith('pseudo:')) {
+                const token = await tokenize(value);
+                if (instance.setDataValue) {
+                    instance.setDataValue(field, token);
+                }
+                else {
+                    instance[field] = token;
+                }
+            }
+        });
+        Model.addHook('beforeUpdate', hookName, async (instance) => {
+            const value = instance.getDataValue ? instance.getDataValue(field) : instance[field];
+            if (instance.changed(field) && value && typeof value === 'string' && !value.startsWith('pseudo:')) {
+                const token = await tokenize(value);
+                if (instance.setDataValue) {
+                    instance.setDataValue(field, token);
+                }
+                else {
+                    instance[field] = token;
+                }
+            }
+        });
+    }
+}
+// ==================== Class Export ====================
+class PseudonymizationService {
+}
+exports.PseudonymizationService = PseudonymizationService;
+PseudonymizationService.configure = configure;
+PseudonymizationService.tokenize = tokenize;
+PseudonymizationService.detokenize = detokenize;
+PseudonymizationService.exists = exists;
+PseudonymizationService.removeToken = removeToken;
+PseudonymizationService.removeOriginal = removeOriginal;
+PseudonymizationService.applyHooks = applyHooks;