ts-prorm-orm 1.1.0 → 1.2.0

package/dist/compliance/rate-limiter.d.ts

@@ -0,0 +1,203 @@
+/**
+ * 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 { ... }
+ */
+import { Prorm } from '../prorm';
+import type { ModelStatic } from '../types';
+export type RateLimitAction = 'block' | 'throttle';
+export interface RateLimitConfig {
+    /** Requests allowed per minute */
+    perMinute: number;
+    /** Requests allowed per hour */
+    perHour: number;
+    /** Requests allowed per day (optional) */
+    perDay?: number;
+}
+export interface RateLimiterOptions {
+    /** Rate limit for authenticated users */
+    user?: RateLimitConfig;
+    /** Rate limit for anonymous users (by IP) */
+    anonymous?: RateLimitConfig;
+    /** Rate limit per IP address */
+    ip?: RateLimitConfig;
+    /** Rate limit per endpoint */
+    endpoint?: RateLimitConfig;
+    /** Rate limit per role */
+    role?: Record<string, RateLimitConfig>;
+    /** Action when limit is exceeded: 'block' (return error) or 'throttle' (add delay) */
+    action?: RateLimitAction;
+    /** Throttle delay in ms when action is 'throttle' */
+    throttleDelay?: number;
+    /** Enable logging of rate limit events */
+    logEvents?: boolean;
+    /** Callback when rate limit is exceeded */
+    onLimitExceeded?: (info: RateLimitInfo) => void;
+    /** Store rate limit data in database (requires table) */
+    storeInDb?: boolean;
+    /** Model name for storing rate limit data */
+    rateLimitModelName?: string;
+}
+export interface RateLimitInfo {
+    identifier: string;
+    identifierType: 'user' | 'ip' | 'endpoint' | 'role';
+    limit: number;
+    current: number;
+    window: 'minute' | 'hour' | 'day';
+    action: RateLimitAction;
+    timestamp: Date;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetIn: number;
+    action?: RateLimitAction;
+    throttleDelay?: number;
+}
+export interface RateLimitStats {
+    totalRequests: number;
+    blockedRequests: number;
+    throttledRequests: number;
+    uniqueUsers: number;
+    uniqueIPs: number;
+    uniqueEndpoints: number;
+    byUser: Record<string, {
+        minute: number;
+        hour: number;
+        day: number;
+    }>;
+    byIP: Record<string, {
+        minute: number;
+        hour: number;
+        day: number;
+    }>;
+    byEndpoint: Record<string, {
+        minute: number;
+        hour: number;
+        day: number;
+    }>;
+}
+export declare class RateLimiter {
+    private prorm;
+    private options;
+    private store;
+    private dbModel;
+    private totalRequests;
+    private blockedRequests;
+    private throttledRequests;
+    constructor(prorm: Prorm, options?: RateLimiterOptions);
+    /**
+     * Factory method to create a RateLimiter instance
+     */
+    static create(prorm: Prorm, options?: RateLimiterOptions): RateLimiter;
+    /**
+     * Initialize database storage (optional)
+     */
+    initDatabase(): Promise<void>;
+    /**
+     * Check if a request is within rate limits
+     */
+    checkLimit(userId: string | null, ip: string, endpoint: string, role?: string): RateLimitResult;
+    /**
+     * 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).
+     */
+    private blockEntry;
+    /**
+     * 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.
+     */
+    private updateEntry;
+    /**
+     * Get rate limit statistics
+     */
+    getStats(): RateLimitStats;
+    /**
+     * Reset all rate limit counters
+     */
+    reset(): void;
+    /**
+     * Reset specific user/IP
+     */
+    resetIdentifier(identifier: string, type: string, endpoint?: string): void;
+    /**
+     * Get current window reset time
+     */
+    getResetTime(): number;
+}
+export interface RateLimitDecoratorOptions {
+    /** Requests allowed per minute */
+    perMinute?: number;
+    /** Requests allowed per hour */
+    perHour?: number;
+    /** Requests allowed per day */
+    perDay?: number;
+    /** Custom endpoint pattern */
+    endpoint?: string;
+    /** Apply to specific roles */
+    roles?: string[];
+}
+/**
+ * Rate limit decorator for models
+ *
+ * Usage:
+ *   @RateLimit({ perMinute: 100, perHour: 1000 })
+ *   class User extends Model { ... }
+ */
+export declare function RateLimit(options: RateLimitDecoratorOptions): <T extends ModelStatic<any>>(target: T) => T;
+/**
+ * Get rate limit options from a model
+ */
+export declare function getRateLimitOptions(model: ModelStatic<any>): RateLimitDecoratorOptions | null;
+/**
+ * Get the global rate limiter instance
+ */
+export declare function getGlobalLimiter(): RateLimiter | null;
+/**
+ * Initialize the global rate limiter
+ */
+export declare function initRateLimiter(prorm: Prorm, options?: RateLimiterOptions): RateLimiter;
+/**
+ * Quick rate limit check using global limiter
+ */
+export declare function checkRateLimit(userId: string | null, ip: string, endpoint: string, role?: string): RateLimitResult;
+/**
+ * Check if rate limiting satisfies a compliance framework
+ */
+export declare function satisfiesCompliance(framework: string): boolean;
+/**
+ * Get recommended rate limits for a framework
+ */
+export declare function getRecommendedLimits(framework: string): RateLimiterOptions;

package/dist/compliance/right-to-erasure.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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'] },
+ *     ],
+ *   });
+ */
+export type ErasureMode = 'delete' | 'anonymize';
+export interface CascadeTarget {
+    /** The associated model to erase from */
+    model: any;
+    /** The foreign key column linking to the erased subject */
+    foreignKey: string;
+    /** PII fields to anonymize (only for mode: 'anonymize') */
+    piiFields?: string[];
+    /** Sub-cascades for this model's own associations */
+    cascade?: CascadeTarget[];
+}
+export interface ErasureOptions {
+    /**
+     * 'delete'    — hard delete rows (force: true bypasses paranoid)
+     * 'anonymize' — null out PII fields, keep the row for referential integrity
+     * Default: 'delete'
+     */
+    mode?: ErasureMode;
+    /**
+     * Fields to anonymize in 'anonymize' mode.
+     * Uses DataClassifier PII fields if not specified.
+     */
+    piiFields?: string[];
+    /**
+     * Replacement value for anonymized string fields.
+     * Default: '[REDACTED]'
+     */
+    redactedValue?: string;
+    /**
+     * Whether to use force: true for deletion (bypasses soft delete).
+     * Default: true
+     */
+    force?: boolean;
+    /**
+     * Cascade erasure to associated models.
+     */
+    cascade?: CascadeTarget[];
+}
+export interface ErasureResult {
+    model: string;
+    mode: ErasureMode;
+    affected: number;
+    cascadeResults?: ErasureResult[];
+    timestamp: Date;
+    requestId: string;
+}
+export declare 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 erase(model: any, query: {
+        where: Record<string, any>;
+    }, options?: ErasureOptions): Promise<ErasureResult>;
+    /**
+     * Check if records exist for a given subject (for verification before erasure).
+     */
+    static exists(model: any, query: {
+        where: Record<string, any>;
+    }): Promise<boolean>;
+}

package/dist/compliance/row-level-security.d.ts

@@ -0,0 +1,152 @@
+/**
+ * RowLevelSecurity
+ *
+ * Applies dynamic scoping to filter all queries by the current user's context
+ * (e.g. tenant_id, organization_id, user_id). Uses AsyncLocalStorage to
+ * store the request context so it's automatically available without passing
+ * it through every function call.
+ *
+ * Covers ~64 compliance frameworks including:
+ *   GDPR, HIPAA, PCI DSS, SOX, NIST SP 800-53, NIS2, DORA, Zero Trust,
+ *   FedRAMP, CJIS, APRA CPS 234, TISAX, and more.
+ *
+ * Usage:
+ *   // At app startup, set up the context storage:
+ *   RowLevelSecurity.init();
+ *
+ *   // In your request middleware, set the current user context:
+ *   RowLevelSecurity.setContext({ tenantId: 'acme-corp', userId: 'user-123', role: 'admin' });
+ *
+ *   // Apply RLS to a model (all queries are automatically filtered):
+ *   RowLevelSecurity.apply(Document, (ctx) => ({
+ *     where: { tenantId: ctx.tenantId }
+ *   }));
+ *
+ *   // Express middleware example:
+ *   app.use((req, res, next) => {
+ *     RowLevelSecurity.setContext({
+ *       tenantId: req.user.tenantId,
+ *       userId: req.user.id,
+ *       role: req.user.role,
+ *     });
+ *     next();
+ *   });
+ */
+export interface SecurityContext {
+    /** The tenant or organization identifier */
+    tenantId?: string;
+    /** The user ID */
+    userId?: string;
+    /** The user's role(s) */
+    role?: string | string[];
+    /** Any additional context keys */
+    [key: string]: any;
+}
+export type ScopeSelector = (ctx: SecurityContext) => {
+    where?: Record<string, any>;
+    include?: any[];
+    attributes?: string[];
+};
+/**
+ * Initialize the RLS subsystem.
+ * Call once at application startup.
+ */
+export declare function initRLS(): void;
+/**
+ * Get the current security context (or undefined if not set).
+ */
+export declare function getContext(): SecurityContext | undefined;
+/**
+ * Run a function within a specific security context.
+ * Use this to simulate a different user for testing.
+ */
+export declare function runInContext<T>(ctx: SecurityContext, fn: () => T): T;
+/**
+ * Set the current security context for the request.
+ * Call this in your authentication middleware.
+ *
+ * @param ctx - The security context for the current request
+ */
+export declare function setContext(ctx: SecurityContext): void;
+/**
+ * Clear the current security context.
+ */
+export declare function clearContext(): void;
+/**
+ * Apply row-level security to a model.
+ * Registers a dynamic scope selector that is applied to ALL queries on that model.
+ *
+ * @param Model - The model to protect
+ * @param selector - A function that returns query modifiers based on the current context
+ */
+export declare function apply(Model: any, selector: ScopeSelector): void;
+/**
+ * Remove RLS protection from a model.
+ */
+export declare function remove(Model: any): void;
+/**
+ * Get the filtered query options for a model given the current context.
+ * Returns empty object if no RLS is configured or no context is set.
+ */
+export declare function getFilteredQuery(Model: any): {
+    where?: Record<string, any>;
+    include?: any[];
+    attributes?: string[];
+};
+/**
+ * Decorator to apply RLS to a model class.
+ *
+ *   @RowLevelSecurity((ctx) => ({ where: { tenantId: ctx.tenantId } }))
+ *   class Document extends Model { ... }
+ */
+export declare function RowLevelSecurity(selector: ScopeSelector): (target: any) => void;
+/**
+ * Middleware to integrate RLS with Express/Connect.
+ * Use after your authentication middleware.
+ *
+ *   app.use(authMiddleware);        // sets req.user
+ *   app.use(rowLevelSecurityMiddleware);
+ */
+export declare function rlsMiddleware(req: any, res: any, next: () => void): void;
+/**
+ * Register beforeFind hooks on all models that have RLS configured.
+ * Call this once after all models are defined.
+ */
+export declare function registerHooks(prorm: any): void;
+export declare const RLS: {
+    init: typeof initRLS;
+    apply: typeof apply;
+    remove: typeof remove;
+    setContext: typeof setContext;
+    getContext: typeof getContext;
+    clearContext: typeof clearContext;
+    runInContext: typeof runInContext;
+    getFilteredQuery: typeof getFilteredQuery;
+    registerHooks: typeof registerHooks;
+    middleware: typeof rlsMiddleware;
+};
+/**
+ * Row-level security class with static methods.
+ * Provides the same functionality as the RLS object but as class methods.
+ *
+ *   RowLevelSecurity.init();
+ *   RowLevelSecurity.apply(Document, ctx => ({ where: { tenantId: ctx.tenantId } }));
+ *   RowLevelSecurity.remove(Document);
+ *   RowLevelSecurity.getFilteredQuery(Document);
+ */
+export declare class RowLevelSecurityAPI {
+    static init(): void;
+    static apply(Model: any, selector: ScopeSelector): void;
+    static remove(Model: any): void;
+    static setContext(ctx: SecurityContext): void;
+    static getContext(): SecurityContext | undefined;
+    static clearContext(): void;
+    static runInContext<T>(ctx: SecurityContext, fn: () => T): T;
+    static getFilteredQuery(Model: any): {
+        where?: Record<string, any>;
+        include?: any[];
+        attributes?: string[];
+    };
+    static registerHooks(prorm: any): void;
+    static middleware(req: any, res: any, next: () => void): void;
+}