ts-prorm-orm 1.1.0

package/dist/compliance/rate-limiter.js

@@ -0,0 +1,580 @@
+"use strict";
+/**
+ * API Rate Limiter
+ *
+ * A comprehensive rate limiting system that:
+ * - Limits queries per user/role to prevent enumeration attacks
+ * - Per-IP rate limiting
+ * - Per-endpoint rate limiting
+ * - Configurable thresholds with block/throttle actions
+ * - OWASP Top 10, NIS2, DORA compliance
+ *
+ * Usage:
+ *   // Initialize rate limiter
+ *   const limiter = RateLimiter.create(prorm, {
+ *     user: { perMinute: 100, perHour: 1000 },
+ *     ip: { perMinute: 50, perHour: 500 },
+ *     endpoint: { perMinute: 200, perHour: 2000 },
+ *     onLimitExceeded: (info) => console.log('Rate limited:', info),
+ *   });
+ *
+ *   // Check if request is allowed
+ *   const result = limiter.checkLimit(userId, ip, endpoint);
+ *   if (!result.allowed) {
+ *     return res.status(429).json({ error: 'Rate limit exceeded' });
+ *   }
+ *
+ *   // Get statistics
+ *   const stats = limiter.getStats();
+ *
+ *   // Reset counters
+ *   limiter.reset();
+ *
+ * Decorator usage:
+ *   @RateLimit({ perMinute: 100, perHour: 1000 })
+ *   class User extends Model { ... }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+exports.RateLimit = RateLimit;
+exports.getRateLimitOptions = getRateLimitOptions;
+exports.getGlobalLimiter = getGlobalLimiter;
+exports.initRateLimiter = initRateLimiter;
+exports.checkRateLimit = checkRateLimit;
+exports.satisfiesCompliance = satisfiesCompliance;
+exports.getRecommendedLimits = getRecommendedLimits;
+// In-memory storage (default)
+class RateLimitStore {
+    constructor() {
+        this.entries = new Map();
+    }
+    getKey(identifier, identifierType, endpoint) {
+        return `${identifierType}:${identifier}${endpoint ? `:${endpoint}` : ''}`;
+    }
+    get(identifier, identifierType, endpoint) {
+        return this.entries.get(this.getKey(identifier, identifierType, endpoint));
+    }
+    set(entry) {
+        const key = this.getKey(entry.identifier, entry.identifierType, entry.endpoint);
+        this.entries.set(key, entry);
+    }
+    delete(key) {
+        this.entries.delete(key);
+    }
+    clear() {
+        this.entries.clear();
+    }
+    getAll() {
+        return Array.from(this.entries.values());
+    }
+    getSize() {
+        return this.entries.size;
+    }
+}
+// ==================== Rate Limiter Class ====================
+class RateLimiter {
+    constructor(prorm, options = {}) {
+        this.dbModel = null;
+        this.totalRequests = 0;
+        this.blockedRequests = 0;
+        this.throttledRequests = 0;
+        this.prorm = prorm;
+        this.store = new RateLimitStore();
+        this.options = {
+            user: options.user ?? { perMinute: 100, perHour: 1000, perDay: 10000 },
+            anonymous: options.anonymous ?? { perMinute: 20, perHour: 200, perDay: 1000 },
+            ip: options.ip ?? { perMinute: 50, perHour: 500, perDay: 5000 },
+            endpoint: options.endpoint ?? { perMinute: 200, perHour: 2000, perDay: 20000 },
+            role: options.role ?? {},
+            action: options.action ?? 'block',
+            throttleDelay: options.throttleDelay ?? 1000,
+            logEvents: options.logEvents ?? true,
+            onLimitExceeded: options.onLimitExceeded ?? (() => { }),
+            storeInDb: options.storeInDb ?? false,
+            rateLimitModelName: options.rateLimitModelName ?? 'RateLimitEntry',
+        };
+    }
+    /**
+     * Factory method to create a RateLimiter instance
+     */
+    static create(prorm, options = {}) {
+        return new RateLimiter(prorm, options);
+    }
+    /**
+     * Initialize database storage (optional)
+     */
+    async initDatabase() {
+        if (!this.options.storeInDb)
+            return;
+        const modelName = this.options.rateLimitModelName;
+        // Check if model already exists
+        const existingModel = this.prorm.models[modelName];
+        if (existingModel) {
+            this.dbModel = existingModel;
+            return;
+        }
+        // Create the model
+        this.dbModel = this.prorm.define(modelName, {
+            id: {
+                type: this.prorm.Prorm.INTEGER,
+                primaryKey: true,
+                autoIncrement: true,
+            },
+            identifier: {
+                type: this.prorm.Prorm.STRING,
+                allowNull: false,
+            },
+            identifierType: {
+                type: this.prorm.Prorm.STRING,
+                allowNull: false,
+            },
+            endpoint: {
+                type: this.prorm.Prorm.STRING,
+                allowNull: true,
+            },
+            countMinute: {
+                type: this.prorm.Prorm.INTEGER,
+                defaultValue: 0,
+            },
+            countHour: {
+                type: this.prorm.Prorm.INTEGER,
+                defaultValue: 0,
+            },
+            countDay: {
+                type: this.prorm.Prorm.INTEGER,
+                defaultValue: 0,
+            },
+            windowStartMinute: {
+                type: this.prorm.Prorm.BIGINT,
+                defaultValue: 0,
+            },
+            windowStartHour: {
+                type: this.prorm.Prorm.BIGINT,
+                defaultValue: 0,
+            },
+            windowStartDay: {
+                type: this.prorm.Prorm.BIGINT,
+                defaultValue: 0,
+            },
+            blocked: {
+                type: this.prorm.Prorm.BOOLEAN,
+                defaultValue: false,
+            },
+            blockUntil: {
+                type: this.prorm.Prorm.DATE,
+                allowNull: true,
+            },
+        });
+        await this.dbModel.sync({ alter: true });
+    }
+    /**
+     * Check if a request is within rate limits
+     */
+    checkLimit(userId, ip, endpoint, role) {
+        this.totalRequests++;
+        const now = Date.now();
+        const currentMinute = Math.floor(now / 60000);
+        const currentHour = Math.floor(now / 3600000);
+        const currentDay = Math.floor(now / 86400000);
+        // Determine which limits apply
+        const limits = [];
+        // User limit
+        if (userId) {
+            limits.push({ type: 'user', config: this.options.user, identifier: userId });
+        }
+        else {
+            // Anonymous user limit
+            limits.push({ type: 'user', config: this.options.anonymous, identifier: `anon:${ip}` });
+        }
+        // Role limit
+        if (role && this.options.role[role]) {
+            limits.push({ type: 'role', config: this.options.role[role], identifier: `role:${role}` });
+        }
+        // IP limit
+        limits.push({ type: 'ip', config: this.options.ip, identifier: ip });
+        // Endpoint limit
+        limits.push({ type: 'endpoint', config: this.options.endpoint, identifier: endpoint });
+        // Check all limits
+        let overallAllowed = true;
+        let minRemaining = Infinity;
+        let minResetIn = Infinity;
+        for (const limit of limits) {
+            const entry = this.store.get(limit.identifier, limit.type, endpoint);
+            let countMinute = 0;
+            let countHour = 0;
+            let countDay = 0;
+            if (entry) {
+                // Check if we need to reset windows
+                if (entry.windowStartMinute !== currentMinute) {
+                    entry.countMinute = 0;
+                    entry.windowStartMinute = currentMinute;
+                }
+                if (entry.windowStartHour !== currentHour) {
+                    entry.countHour = 0;
+                    entry.windowStartHour = currentHour;
+                }
+                if (entry.windowStartDay !== currentDay) {
+                    entry.countDay = 0;
+                    entry.windowStartDay = currentDay;
+                }
+                // Check if blocked
+                if (entry.blocked && entry.blockUntil && entry.blockUntil.getTime() > now) {
+                    overallAllowed = false;
+                    minRemaining = 0;
+                    minResetIn = Math.min(minResetIn, entry.blockUntil.getTime() - now);
+                    this.blockedRequests++;
+                    this.options.onLimitExceeded({
+                        identifier: limit.identifier,
+                        identifierType: limit.type,
+                        limit: limit.config.perMinute,
+                        current: entry.countMinute + 1,
+                        window: 'minute',
+                        action: this.options.action,
+                        timestamp: new Date(),
+                    });
+                    continue;
+                }
+                countMinute = entry.countMinute;
+                countHour = entry.countHour;
+                countDay = entry.countDay;
+            }
+            // Check per-minute, per-hour, and per-day limits. Each window is
+            // tracked and enforced independently (a request can be within the
+            // per-minute budget but still exceed the per-hour or per-day
+            // budget), matching what RateLimitConfig documents but the original
+            // implementation never actually enforced for hour/day.
+            const windows = [
+                { window: 'minute', limitVal: limit.config.perMinute, current: countMinute, resetIn: 60000 - (now % 60000) },
+                { window: 'hour', limitVal: limit.config.perHour, current: countHour, resetIn: 3600000 - (now % 3600000) },
+                { window: 'day', limitVal: limit.config.perDay, current: countDay, resetIn: 86400000 - (now % 86400000) },
+            ];
+            const breached = windows.find((w) => w.limitVal !== undefined && w.current + 1 > w.limitVal);
+            if (breached) {
+                if (this.options.action === 'block') {
+                    overallAllowed = false;
+                    minRemaining = 0;
+                    minResetIn = Math.min(minResetIn, breached.resetIn);
+                    // Block the identifier until the breached window resets
+                    this.blockEntry(limit.identifier, limit.type, endpoint, now, breached.resetIn);
+                    this.options.onLimitExceeded({
+                        identifier: limit.identifier,
+                        identifierType: limit.type,
+                        limit: breached.limitVal,
+                        current: breached.current + 1,
+                        window: breached.window,
+                        action: 'block',
+                        timestamp: new Date(),
+                    });
+                    this.blockedRequests++;
+                }
+                else {
+                    // Throttle
+                    minRemaining = 0;
+                    minResetIn = Math.min(minResetIn, breached.resetIn);
+                    this.throttledRequests++;
+                    this.options.onLimitExceeded({
+                        identifier: limit.identifier,
+                        identifierType: limit.type,
+                        limit: breached.limitVal,
+                        current: breached.current + 1,
+                        window: breached.window,
+                        action: 'throttle',
+                        timestamp: new Date(),
+                    });
+                }
+            }
+            else {
+                for (const w of windows) {
+                    if (w.limitVal !== undefined) {
+                        minRemaining = Math.min(minRemaining, w.limitVal - w.current);
+                    }
+                }
+            }
+            // Update entry - increments minute/hour/day counters independently
+            this.updateEntry(limit.identifier, limit.type, endpoint, now);
+        }
+        return {
+            allowed: overallAllowed,
+            remaining: minRemaining === Infinity ? Math.min(this.options.user.perMinute, this.options.ip.perMinute, this.options.endpoint.perMinute) : minRemaining,
+            resetIn: minResetIn === Infinity ? 60000 - (now % 60000) : minResetIn,
+            action: overallAllowed ? undefined : this.options.action,
+            throttleDelay: this.options.action === 'throttle' && !overallAllowed ? this.options.throttleDelay : undefined,
+        };
+    }
+    /**
+     * Block an identifier until `now + blockDurationMs` (defaults to the
+     * standard 1 minute block window when no specific breached window was
+     * given, e.g. for callers outside checkLimit).
+     */
+    blockEntry(identifier, type, endpoint, now, blockDurationMs = 60000) {
+        let entry = this.store.get(identifier, type, endpoint);
+        if (!entry) {
+            entry = {
+                identifier,
+                identifierType: type,
+                endpoint,
+                countMinute: 0,
+                countHour: 0,
+                countDay: 0,
+                windowStartMinute: Math.floor(now / 60000),
+                windowStartHour: Math.floor(now / 3600000),
+                windowStartDay: Math.floor(now / 86400000),
+                lastRequest: new Date(),
+                blocked: false,
+            };
+        }
+        entry.blocked = true;
+        const newBlockUntil = now + Math.max(blockDurationMs, 0);
+        // Never shorten an existing block (e.g. a daily breach shouldn't be
+        // clobbered by a shorter minute-level block computed afterwards).
+        const existingUntil = entry.blockUntil?.getTime() ?? 0;
+        entry.blockUntil = new Date(Math.max(newBlockUntil, existingUntil));
+        this.store.set(entry);
+        if (this.options.logEvents) {
+            console.log(`[RateLimiter] Blocked: ${identifier} (${type}) until ${entry.blockUntil}`);
+        }
+    }
+    /**
+     * Update or create an entry, independently incrementing the minute,
+     * hour, and day counters for the current request. Each window is reset
+     * to 0 when its bucket boundary rolls over.
+     */
+    updateEntry(identifier, type, endpoint, now) {
+        const currentMinute = Math.floor(now / 60000);
+        const currentHour = Math.floor(now / 3600000);
+        const currentDay = Math.floor(now / 86400000);
+        let entry = this.store.get(identifier, type, endpoint);
+        if (!entry) {
+            entry = {
+                identifier,
+                identifierType: type,
+                endpoint,
+                countMinute: 0,
+                countHour: 0,
+                countDay: 0,
+                windowStartMinute: currentMinute,
+                windowStartHour: currentHour,
+                windowStartDay: currentDay,
+                lastRequest: new Date(),
+                blocked: false,
+            };
+        }
+        // Reset counters whose window has rolled over
+        if (entry.windowStartMinute !== currentMinute) {
+            entry.countMinute = 0;
+            entry.windowStartMinute = currentMinute;
+        }
+        if (entry.windowStartHour !== currentHour) {
+            entry.countHour = 0;
+            entry.windowStartHour = currentHour;
+        }
+        if (entry.windowStartDay !== currentDay) {
+            entry.countDay = 0;
+            entry.windowStartDay = currentDay;
+        }
+        // Each window tracks its own independent count of requests seen within
+        // it, rather than all three being forced to the same value.
+        entry.countMinute += 1;
+        entry.countHour += 1;
+        entry.countDay += 1;
+        entry.lastRequest = new Date();
+        // Unblock if needed
+        if (entry.blocked && (!entry.blockUntil || entry.blockUntil.getTime() <= now)) {
+            entry.blocked = false;
+            entry.blockUntil = undefined;
+        }
+        this.store.set(entry);
+    }
+    /**
+     * Get rate limit statistics
+     */
+    getStats() {
+        const entries = this.store.getAll();
+        const byUser = {};
+        const byIP = {};
+        const byEndpoint = {};
+        const uniqueUsers = new Set();
+        const uniqueIPs = new Set();
+        const uniqueEndpoints = new Set();
+        for (const entry of entries) {
+            if (entry.identifierType === 'user') {
+                byUser[entry.identifier] = {
+                    minute: entry.countMinute,
+                    hour: entry.countHour,
+                    day: entry.countDay,
+                };
+                uniqueUsers.add(entry.identifier);
+            }
+            else if (entry.identifierType === 'ip') {
+                byIP[entry.identifier] = {
+                    minute: entry.countMinute,
+                    hour: entry.countHour,
+                    day: entry.countDay,
+                };
+                uniqueIPs.add(entry.identifier);
+            }
+            else if (entry.identifierType === 'endpoint') {
+                byEndpoint[entry.identifier] = {
+                    minute: entry.countMinute,
+                    hour: entry.countHour,
+                    day: entry.countDay,
+                };
+                uniqueEndpoints.add(entry.identifier);
+            }
+        }
+        return {
+            totalRequests: this.totalRequests,
+            blockedRequests: this.blockedRequests,
+            throttledRequests: this.throttledRequests,
+            uniqueUsers: uniqueUsers.size,
+            uniqueIPs: uniqueIPs.size,
+            uniqueEndpoints: uniqueEndpoints.size,
+            byUser,
+            byIP,
+            byEndpoint,
+        };
+    }
+    /**
+     * Reset all rate limit counters
+     */
+    reset() {
+        this.store.clear();
+        this.totalRequests = 0;
+        this.blockedRequests = 0;
+        this.throttledRequests = 0;
+        if (this.options.logEvents) {
+            console.log('[RateLimiter] Counters reset');
+        }
+    }
+    /**
+     * Reset specific user/IP
+     */
+    resetIdentifier(identifier, type, endpoint) {
+        const key = `${type}:${identifier}${endpoint ? `:${endpoint}` : ''}`;
+        this.store.delete(key);
+        if (this.options.logEvents) {
+            console.log(`[RateLimiter] Reset: ${key}`);
+        }
+    }
+    /**
+     * Get current window reset time
+     */
+    getResetTime() {
+        const now = Date.now();
+        return 60000 - (now % 60000); // Reset in X seconds
+    }
+}
+exports.RateLimiter = RateLimiter;
+/**
+ * Rate limit decorator for models
+ *
+ * Usage:
+ *   @RateLimit({ perMinute: 100, perHour: 1000 })
+ *   class User extends Model { ... }
+ */
+function RateLimit(options) {
+    return function (target) {
+        // Store rate limit metadata on the model
+        target.rateLimitOptions = {
+            perMinute: options.perMinute ?? 100,
+            perHour: options.perHour ?? 1000,
+            perDay: options.perDay ?? 10000,
+            endpoint: options.endpoint,
+            roles: options.roles,
+        };
+        return target;
+    };
+}
+/**
+ * Get rate limit options from a model
+ */
+function getRateLimitOptions(model) {
+    return model.rateLimitOptions ?? null;
+}
+// ==================== Utility Functions ====================
+let globalLimiter = null;
+/**
+ * Get the global rate limiter instance
+ */
+function getGlobalLimiter() {
+    return globalLimiter;
+}
+/**
+ * Initialize the global rate limiter
+ */
+function initRateLimiter(prorm, options) {
+    globalLimiter = new RateLimiter(prorm, options);
+    return globalLimiter;
+}
+/**
+ * Quick rate limit check using global limiter
+ */
+function checkRateLimit(userId, ip, endpoint, role) {
+    if (!globalLimiter) {
+        return { allowed: true, remaining: 100, resetIn: 60000 };
+    }
+    return globalLimiter.checkLimit(userId, ip, endpoint, role);
+}
+// ==================== Compliance Helpers ====================
+/**
+ * Check if rate limiting satisfies a compliance framework
+ */
+function satisfiesCompliance(framework) {
+    const frameworks = [
+        'OWASP_Top_10',
+        'NIST_800_53',
+        'NIST_CSF',
+        'ISO_27001',
+        'SOC_2',
+        'DORA',
+        'NIS2',
+        'PCI_DSS',
+    ];
+    return frameworks.includes(framework);
+}
+/**
+ * Get recommended rate limits for a framework
+ */
+function getRecommendedLimits(framework) {
+    switch (framework) {
+        case 'OWASP_Top_10':
+            // Prevent enumeration attacks
+            return {
+                user: { perMinute: 100, perHour: 1000 },
+                ip: { perMinute: 50, perHour: 500 },
+                endpoint: { perMinute: 200, perHour: 2000 },
+                action: 'block',
+            };
+        case 'DORA':
+            // Digital Operational Resilience Act
+            return {
+                user: { perMinute: 200, perHour: 2000, perDay: 10000 },
+                ip: { perMinute: 100, perHour: 1000, perDay: 5000 },
+                endpoint: { perMinute: 300, perHour: 3000, perDay: 30000 },
+                action: 'throttle',
+                throttleDelay: 500,
+            };
+        case 'NIS2':
+            // Network and Information Security Directive
+            return {
+                user: { perMinute: 150, perHour: 1500, perDay: 10000 },
+                ip: { perMinute: 75, perHour: 750, perDay: 5000 },
+                endpoint: { perMinute: 250, perHour: 2500, perDay: 25000 },
+                action: 'block',
+                logEvents: true,
+            };
+        case 'PCI_DSS':
+            return {
+                user: { perMinute: 50, perHour: 500, perDay: 2000 },
+                ip: { perMinute: 25, perHour: 250, perDay: 1000 },
+                endpoint: { perMinute: 100, perHour: 1000, perDay: 10000 },
+                action: 'block',
+            };
+        default:
+            return {
+                user: { perMinute: 100, perHour: 1000 },
+                ip: { perMinute: 50, perHour: 500 },
+                endpoint: { perMinute: 200, perHour: 2000 },
+            };
+    }
+}

package/dist/compliance/right-to-erasure.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * RightToErasure
+ *
+ * Handles Data Subject Access Requests (DSARs) for the right to be forgotten.
+ * Supports hard deletion or field-level anonymization (GDPR-preferred),
+ * and cascades through associated models.
+ *
+ * Covers ~57 compliance frameworks including:
+ *   GDPR Art 17, CCPA, CPRA, LGPD, APPI, PIPA (South Korea),
+ *   PDPA (Thailand, Singapore, Philippines, Malaysia), PoPI, DPDP India,
+ *   and all US state privacy laws with deletion rights.
+ *
+ * Usage:
+ *   // Hard delete all records for a user:
+ *   const result = await RightToErasure.erase(User, { where: { id: userId } });
+ *
+ *   // Anonymize instead of delete (preserves referential integrity):
+ *   const result = await RightToErasure.erase(User, { where: { id: userId } }, {
+ *     mode: 'anonymize',
+ *     piiFields: ['email', 'name', 'phoneNumber', 'address'],
+ *   });
+ *
+ *   // Cascade to associated models:
+ *   const result = await RightToErasure.erase(User, { where: { id: userId } }, {
+ *     mode: 'anonymize',
+ *     cascade: [
+ *       { model: Order, foreignKey: 'userId', piiFields: ['shippingAddress'] },
+ *       { model: Payment, foreignKey: 'userId', piiFields: ['cardLastFour'] },
+ *     ],
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RightToErasure = void 0;
+function generateRequestId() {
+    return `dsar-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+async function anonymizeRecords(records, piiFields, redactedValue) {
+    let count = 0;
+    for (const record of records) {
+        const patch = {};
+        for (const field of piiFields) {
+            patch[field] = redactedValue;
+        }
+        if (Object.keys(patch).length > 0) {
+            await record.update(patch);
+            count++;
+        }
+    }
+    return count;
+}
+async function processErasure(model, where, options, requestId) {
+    const modelName = model.name ?? model.tableName ?? 'Unknown';
+    let affected = 0;
+    if (options.mode === 'delete') {
+        affected = (await model.destroy({ where, force: options.force })) ?? 0;
+    }
+    else {
+        const records = await model.findAll({ where });
+        const pii = options.piiFields.length > 0 ? options.piiFields : Object.keys(records[0]?.dataValues ?? {}).filter((k) => k !== 'id' && k !== 'createdAt' && k !== 'updatedAt');
+        affected = await anonymizeRecords(records, pii, options.redactedValue);
+    }
+    const cascadeResults = [];
+    for (const target of options.cascade) {
+        // Find the primary key values of the erased subject to cascade
+        const subjectIds = await model.findAll({ where, attributes: ['id'] });
+        const ids = subjectIds.map((r) => r.id ?? r.dataValues?.id);
+        if (ids.length === 0)
+            continue;
+        const cascadeWhere = { [target.foreignKey]: ids };
+        const cascadeResult = await processErasure(target.model, cascadeWhere, {
+            mode: options.mode,
+            piiFields: target.piiFields ?? [],
+            redactedValue: options.redactedValue,
+            force: options.force,
+            cascade: target.cascade ?? [],
+        }, requestId);
+        cascadeResults.push(cascadeResult);
+    }
+    return {
+        model: modelName,
+        mode: options.mode,
+        affected,
+        cascadeResults: cascadeResults.length > 0 ? cascadeResults : undefined,
+        timestamp: new Date(),
+        requestId,
+    };
+}
+class RightToErasure {
+    /**
+     * Erase personal data for one or more data subjects.
+     *
+     * @param model   - The primary model to erase from
+     * @param query   - Where clause identifying the data subject(s)
+     * @param options - Erasure mode, fields, and cascade configuration
+     * @returns An ErasureResult with a unique request ID for DSAR audit purposes
+     */
+    static async erase(model, query, options = {}) {
+        const resolved = {
+            mode: options.mode ?? 'delete',
+            piiFields: options.piiFields ?? [],
+            redactedValue: options.redactedValue ?? '[REDACTED]',
+            force: options.force !== false,
+            cascade: options.cascade ?? [],
+        };
+        const requestId = generateRequestId();
+        return processErasure(model, query.where, resolved, requestId);
+    }
+    /**
+     * Check if records exist for a given subject (for verification before erasure).
+     */
+    static async exists(model, query) {
+        const count = await model.count({ where: query.where });
+        return count > 0;
+    }
+}
+exports.RightToErasure = RightToErasure;