ts-prorm-orm 1.1.0

package/dist/compliance/consent-record.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * ConsentRecord
+ *
+ * A ready-made model and service for storing, managing, and querying
+ * data subject consent — including purpose, legal basis, version, and withdrawal.
+ *
+ * Covers ~62 compliance frameworks including:
+ *   GDPR Art 6/7, CCPA, CPRA, LGPD, APPI, ePrivacy Directive, CASL,
+ *   PDPA (Thailand, Singapore, Philippines, Malaysia, Indonesia, Vietnam),
+ *   DPDP India, PIPA South Korea, PIPL, KVKK, PoPI, and more.
+ *
+ * Usage:
+ *   // Initialize once (creates the consent_records table):
+ *   await ConsentRecord.initialize(prorm);
+ *
+ *   // Record consent:
+ *   await ConsentRecord.grant({
+ *     subjectId: 'user-123',
+ *     purpose: 'marketing_emails',
+ *     legalBasis: 'consent',
+ *     version: '2.1',
+ *     ipAddress: req.ip,
+ *   });
+ *
+ *   // Check active consent:
+ *   const active = await ConsentRecord.isActive('user-123', 'marketing_emails');
+ *
+ *   // Withdraw consent (GDPR Art 7(3)):
+ *   await ConsentRecord.withdraw('user-123', 'marketing_emails');
+ *
+ *   // Get full consent history for a subject:
+ *   const history = await ConsentRecord.getHistory('user-123');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsentRecord = exports.LegalBasisEnum = void 0;
+const data_types_1 = require("../models/data-types");
+/**
+ * Companion enum for {@link LegalBasis}. Provided for callers who prefer
+ * enum-based ergonomics (autocomplete, refactor-safety) over raw string
+ * literals. The underlying values are identical to the `LegalBasis`
+ * string literals, so either form may be used interchangeably.
+ */
+var LegalBasisEnum;
+(function (LegalBasisEnum) {
+    LegalBasisEnum["Consent"] = "consent";
+    LegalBasisEnum["Contract"] = "contract";
+    LegalBasisEnum["LegalObligation"] = "legal_obligation";
+    LegalBasisEnum["VitalInterests"] = "vital_interests";
+    LegalBasisEnum["PublicTask"] = "public_task";
+    LegalBasisEnum["LegitimateInterests"] = "legitimate_interests";
+})(LegalBasisEnum || (exports.LegalBasisEnum = LegalBasisEnum = {}));
+let ConsentModel = null;
+class ConsentRecord {
+    /**
+     * Initialize the ConsentRecord model and sync the table.
+     * Call once at application startup.
+     *
+     * @param prorm - The Prorm instance
+     * @param tableName - Override the default table name 'consent_records'
+     */
+    static async initialize(prorm, tableName = 'consent_records') {
+        ConsentModel = prorm.define('ConsentRecord', {
+            id: {
+                type: data_types_1.DataTypes.INTEGER(),
+                primaryKey: true,
+                autoIncrement: true,
+            },
+            subjectId: {
+                type: data_types_1.DataTypes.STRING(255),
+                allowNull: false,
+                comment: 'Unique identifier of the data subject (user ID, email, etc.)',
+            },
+            purpose: {
+                type: data_types_1.DataTypes.STRING(255),
+                allowNull: false,
+                comment: 'Processing purpose (e.g. marketing_emails, analytics)',
+            },
+            legalBasis: {
+                type: data_types_1.DataTypes.STRING(64),
+                allowNull: true,
+                comment: 'GDPR Article 6 legal basis for processing',
+            },
+            consentedAt: {
+                type: data_types_1.DataTypes.DATE(),
+                allowNull: true,
+                comment: 'Timestamp when consent was granted',
+            },
+            withdrawnAt: {
+                type: data_types_1.DataTypes.DATE(),
+                allowNull: true,
+                comment: 'Timestamp when consent was withdrawn',
+            },
+            version: {
+                type: data_types_1.DataTypes.STRING(64),
+                allowNull: true,
+                comment: 'Privacy notice / consent form version',
+            },
+            ipAddress: {
+                type: data_types_1.DataTypes.STRING(45),
+                allowNull: true,
+                comment: 'IP address of the consenting user',
+            },
+            metadata: {
+                type: data_types_1.DataTypes.JSON(),
+                allowNull: true,
+                comment: 'Additional structured metadata',
+            },
+        }, {
+            tableName,
+            timestamps: true,
+            underscored: true,
+            indexes: [
+                { fields: ['subject_id', 'purpose'] },
+                { fields: ['subject_id'] },
+            ],
+        });
+        await ConsentModel.sync({ alter: false });
+    }
+    static requireModel() {
+        if (!ConsentModel) {
+            throw new Error('[ConsentRecord] Not initialized. Call ConsentRecord.initialize(prorm) first.');
+        }
+        return ConsentModel;
+    }
+    /**
+     * Record a new consent grant.
+     * If an active consent already exists for the same subject + purpose,
+     * a new record is created (audit trail is preserved).
+     */
+    static async grant(options) {
+        const model = ConsentRecord.requireModel();
+        return model.create({
+            subjectId: options.subjectId,
+            purpose: options.purpose,
+            legalBasis: options.legalBasis ?? 'consent',
+            version: options.version ?? null,
+            ipAddress: options.ipAddress ?? null,
+            metadata: options.metadata ?? null,
+            consentedAt: new Date(),
+            withdrawnAt: null,
+        });
+    }
+    /**
+     * Withdraw consent for a subject + purpose.
+     * Sets withdrawnAt on the most recent active consent record.
+     *
+     * @returns true if a consent record was found and updated, false if none existed.
+     */
+    static async withdraw(subjectId, purpose, options = {}) {
+        const model = ConsentRecord.requireModel();
+        const record = await model.findOne({
+            where: {
+                subjectId,
+                purpose,
+                withdrawnAt: { $isNull: true },
+                consentedAt: { $isNotNull: true },
+            },
+            order: [['consentedAt', 'DESC']],
+        });
+        if (!record)
+            return false;
+        await record.update({
+            withdrawnAt: new Date(),
+            metadata: {
+                ...(record.metadata ?? {}),
+                withdrawalReason: options.reason ?? null,
+            },
+        });
+        return true;
+    }
+    /**
+     * Check whether an active (non-withdrawn) consent exists.
+     */
+    static async isActive(subjectId, purpose) {
+        const model = ConsentRecord.requireModel();
+        const count = await model.count({
+            where: {
+                subjectId,
+                purpose,
+                consentedAt: { $isNotNull: true },
+                withdrawnAt: { $isNull: true },
+            },
+        });
+        return count > 0;
+    }
+    /**
+     * Get the full consent history for a subject (all purposes).
+     */
+    static async getHistory(subjectId) {
+        const model = ConsentRecord.requireModel();
+        return model.findAll({
+            where: { subjectId },
+            order: [['consentedAt', 'DESC']],
+        });
+    }
+    /**
+     * Get active consents for a subject grouped by purpose.
+     */
+    static async getActiveConsents(subjectId) {
+        const model = ConsentRecord.requireModel();
+        return model.findAll({
+            where: {
+                subjectId,
+                consentedAt: { $isNotNull: true },
+                withdrawnAt: { $isNull: true },
+            },
+        });
+    }
+    /**
+     * List all subjects who have active consent for a specific purpose.
+     * Useful for marketing campaign validation.
+     */
+    static async getConsented(purpose) {
+        const model = ConsentRecord.requireModel();
+        const records = await model.findAll({
+            where: {
+                purpose,
+                consentedAt: { $isNotNull: true },
+                withdrawnAt: { $isNull: true },
+            },
+            attributes: ['subjectId'],
+        });
+        return records.map((r) => r.subjectId);
+    }
+}
+exports.ConsentRecord = ConsentRecord;

package/dist/compliance/consent-versioning.js

@@ -0,0 +1,331 @@
+"use strict";
+/**
+ * ConsentVersioning
+ *
+ * Tracks consent history with timestamps for legal audit compliance.
+ * Provides version control for consent records with full history tracking.
+ *
+ * Supports compliance frameworks:
+ *   GDPR (Art 6, 7, 9), CCPA/CPRA, LGPD (Brazil), PDPA (Thailand),
+ *   PDPA (Singapore, Philippines, Malaysia, Indonesia, Vietnam),
+ *   PIPL (China), PIPA (South Korea), and 60+ others.
+ *
+ * Usage:
+ *   // Initialize (creates consent_versions table):
+ *   await ConsentVersioning.initialize(prorm);
+ *
+ *   // Record consent with version tracking:
+ *   await ConsentVersioning.recordConsent(
+ *     'user-123',
+ *     'marketing_emails',
+ *     true,
+ *     '2.1'
+ *   );
+ *
+ *   // Get full history for audit:
+ *   const history = await ConsentVersioning.getConsentHistory('user-123', 'marketing_emails');
+ *
+ *   // Get current consent state:
+ *   const current = await ConsentVersioning.getCurrentConsent('user-123', 'marketing_emails');
+ *
+ *   // Revoke consent:
+ *   await ConsentVersioning.revokeConsent('user-123', 'marketing_emails');
+ *
+ *   // Validate consent is still valid:
+ *   const isValid = await ConsentVersioning.validateConsent('user-123', 'marketing_emails');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsentVersioning = void 0;
+const data_types_1 = require("../models/data-types");
+const operators_1 = require("../models/operators");
+let ConsentVersionModel = null;
+/**
+ * ConsentVersioning class for tracking consent history with version control.
+ * Provides methods for recording, retrieving, and validating consent records.
+ */
+class ConsentVersioning {
+    /**
+     * Initialize the ConsentVersioning model and sync the table.
+     * Call once at application startup.
+     *
+     * @param prorm - The Prorm instance
+     * @param tableName - Override the default table name 'consent_versions'
+     */
+    static async initialize(prorm, tableName = 'consent_versions') {
+        ConsentVersionModel = prorm.define('ConsentVersion', {
+            id: {
+                type: data_types_1.DataTypes.INTEGER(),
+                primaryKey: true,
+                autoIncrement: true,
+            },
+            userId: {
+                type: data_types_1.DataTypes.STRING(255),
+                allowNull: false,
+                comment: 'Unique identifier of the data subject',
+            },
+            consentType: {
+                type: data_types_1.DataTypes.STRING(255),
+                allowNull: false,
+                comment: 'Type of consent (e.g. marketing_emails, analytics, cookies)',
+            },
+            granted: {
+                type: data_types_1.DataTypes.BOOLEAN(),
+                allowNull: false,
+                comment: 'Whether consent was granted (true) or revoked (false)',
+            },
+            version: {
+                type: data_types_1.DataTypes.STRING(64),
+                allowNull: false,
+                comment: 'Privacy notice / consent form version at time of recording',
+            },
+            grantedAt: {
+                type: data_types_1.DataTypes.DATE(),
+                allowNull: false,
+                comment: 'Timestamp when consent was granted',
+            },
+            revokedAt: {
+                type: data_types_1.DataTypes.DATE(),
+                allowNull: true,
+                comment: 'Timestamp when consent was revoked',
+            },
+            expiresAt: {
+                type: data_types_1.DataTypes.DATE(),
+                allowNull: true,
+                comment: 'Timestamp when consent expires (for time-limited consent)',
+            },
+            metadata: {
+                type: data_types_1.DataTypes.JSON(),
+                allowNull: true,
+                comment: 'Additional structured metadata',
+            },
+            ipAddress: {
+                type: data_types_1.DataTypes.STRING(45),
+                allowNull: true,
+                comment: 'IP address of the consenting user',
+            },
+            userAgent: {
+                type: data_types_1.DataTypes.STRING(512),
+                allowNull: true,
+                comment: 'User agent string of the consenting user',
+            },
+        }, {
+            tableName,
+            timestamps: true,
+            underscored: true,
+            indexes: [
+                { fields: ['user_id', 'consent_type', 'granted_at'] },
+                { fields: ['user_id', 'consent_type'] },
+                { fields: ['consent_type', 'granted'] },
+                { fields: ['expires_at'] },
+            ],
+        });
+        await ConsentVersionModel.sync({ alter: false });
+    }
+    static requireModel() {
+        if (!ConsentVersionModel) {
+            throw new Error('[ConsentVersioning] Not initialized. Call ConsentVersioning.initialize(prorm) first.');
+        }
+        return ConsentVersionModel;
+    }
+    /**
+     * Record a new consent event with version tracking.
+     * Creates a new version record for each consent change.
+     *
+     * @param userId - Unique identifier of the data subject
+     * @param consentType - Type of consent (e.g. 'marketing_emails')
+     * @param granted - Whether consent is granted (true) or revoked (false)
+     * @param version - Privacy notice version at time of recording
+     * @param options - Additional options
+     * @returns The created consent version record
+     */
+    static async recordConsent(userId, consentType, granted, version, options = {}) {
+        const model = ConsentVersioning.requireModel();
+        // If granting consent, first revoke any existing active consent
+        if (granted) {
+            const activeRecord = await model.findOne({
+                where: {
+                    userId,
+                    consentType,
+                    granted: true,
+                    revokedAt: null,
+                },
+                order: [['grantedAt', 'DESC']],
+            });
+            if (activeRecord) {
+                await activeRecord.update({
+                    revokedAt: new Date(),
+                });
+            }
+        }
+        const record = await model.create({
+            userId,
+            consentType,
+            granted,
+            version,
+            grantedAt: new Date(),
+            revokedAt: granted ? null : new Date(),
+            expiresAt: options.expiresAt ?? null,
+            metadata: options.metadata ?? null,
+            ipAddress: options.ipAddress ?? null,
+            userAgent: options.userAgent ?? null,
+        });
+        return record;
+    }
+    /**
+     * Get the full consent history for a user and consent type.
+     * Returns all version records in chronological order.
+     *
+     * @param userId - Unique identifier of the data subject
+     * @param consentType - Type of consent to query
+     * @param options - History options (order, limit, date filters)
+     * @returns Array of consent version records
+     */
+    static async getConsentHistory(userId, consentType, options = {}) {
+        const model = ConsentVersioning.requireModel();
+        const where = {
+            userId,
+            consentType,
+        };
+        if (options.since) {
+            where.grantedAt = { [operators_1.Op.gte]: options.since };
+        }
+        if (options.until) {
+            where.grantedAt = {
+                ...(where.grantedAt ?? {}),
+                [operators_1.Op.lte]: options.until,
+            };
+        }
+        return model.findAll({
+            where,
+            order: [['grantedAt', options.order ?? 'DESC']],
+            limit: options.limit ?? undefined,
+        });
+    }
+    /**
+     * Get the current consent state for a user and consent type.
+     * Returns the most recent consent record (granted or revoked).
+     *
+     * @param userId - Unique identifier of the data subject
+     * @param consentType - Type of consent to query
+     * @returns The current consent version record or null if none exists
+     */
+    static async getCurrentConsent(userId, consentType) {
+        const model = ConsentVersioning.requireModel();
+        return model.findOne({
+            where: {
+                userId,
+                consentType,
+            },
+            order: [['grantedAt', 'DESC']],
+        });
+    }
+    /**
+     * Revoke consent for a user and consent type.
+     * Creates a new version record with granted = false.
+     *
+     * @param userId - Unique identifier of the data subject
+     * @param consentType - Type of consent to revoke
+     * @param options - Additional options (metadata, ipAddress, etc.)
+     * @returns The created revocation record
+     */
+    static async revokeConsent(userId, consentType, options = {}) {
+        return ConsentVersioning.recordConsent(userId, consentType, false, options.metadata?.version ?? 'unknown', options);
+    }
+    /**
+     * Validate whether consent is currently valid (granted and not expired).
+     *
+     * @param userId - Unique identifier of the data subject
+     * @param consentType - Type of consent to validate
+     * @returns true if consent is currently valid, false otherwise
+     */
+    static async validateConsent(userId, consentType) {
+        const current = await ConsentVersioning.getCurrentConsent(userId, consentType);
+        if (!current) {
+            return false;
+        }
+        // Check if consent is granted
+        if (!current.granted) {
+            return false;
+        }
+        // Check if consent has been revoked
+        if (current.revokedAt) {
+            return false;
+        }
+        // Check if consent has expired
+        if (current.expiresAt && new Date() > current.expiresAt) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Get all active (granted and not expired) consents for a user.
+     *
+     * @param userId - Unique identifier of the data subject
+     * @returns Array of active consent version records
+     */
+    static async getActiveConsents(userId) {
+        const model = ConsentVersioning.requireModel();
+        const now = new Date();
+        return model.findAll({
+            where: {
+                [operators_1.Op.and]: [
+                    { userId, granted: true, revokedAt: { [operators_1.Op.isNull]: true } },
+                    { [operators_1.Op.or]: [{ expiresAt: { [operators_1.Op.isNull]: true } }, { expiresAt: { [operators_1.Op.gte]: now } }] },
+                ],
+            },
+        });
+    }
+    /**
+     * Get all users who have granted consent for a specific consent type.
+     * Useful for compliance audits and marketing campaigns.
+     *
+     * @param consentType - Type of consent to query
+     * @returns Array of user IDs with active consent
+     */
+    static async getConsentedUsers(consentType) {
+        const model = ConsentVersioning.requireModel();
+        const now = new Date();
+        const records = await model.findAll({
+            where: {
+                [operators_1.Op.and]: [
+                    { consentType, granted: true, revokedAt: { [operators_1.Op.isNull]: true } },
+                    { [operators_1.Op.or]: [{ expiresAt: { [operators_1.Op.isNull]: true } }, { expiresAt: { [operators_1.Op.gte]: now } }] },
+                ],
+            },
+            attributes: ['userId'],
+        });
+        return Array.from(new Set(records.map((r) => r.userId)));
+    }
+    /**
+     * Get consent by specific version.
+     *
+     * @param userId - Unique identifier of the data subject
+     * @param consentType - Type of consent to query
+     * @param version - Specific version to retrieve
+     * @returns The consent version record or null if not found
+     */
+    static async getConsentByVersion(userId, consentType, version) {
+        const model = ConsentVersioning.requireModel();
+        return model.findOne({
+            where: {
+                userId,
+                consentType,
+                version,
+            },
+            order: [['grantedAt', 'DESC']],
+        });
+    }
+    /**
+     * Re-grant consent (creates new version after revocation).
+     *
+     * @param userId - Unique identifier of the data subject
+     * @param consentType - Type of consent to re-grant
+     * @param version - Current privacy notice version
+     * @param options - Additional options
+     * @returns The created consent record
+     */
+    static async reGrantConsent(userId, consentType, version, options = {}) {
+        return ConsentVersioning.recordConsent(userId, consentType, true, version, options);
+    }
+}
+exports.ConsentVersioning = ConsentVersioning;