ts-prorm-orm 1.1.0 → 1.2.0

package/dist/compliance/consent-versioning.d.ts

@@ -0,0 +1,169 @@
+/**
+ * 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');
+ */
+export type ConsentType = string;
+export interface ConsentVersion {
+    id: number;
+    userId: string;
+    consentType: string;
+    granted: boolean;
+    version: string;
+    grantedAt: Date;
+    revokedAt: Date | null;
+    expiresAt: Date | null;
+    metadata: Record<string, any> | null;
+    ipAddress: string | null;
+    userAgent: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface ConsentHistoryOptions {
+    /** Sort order for history records */
+    order?: 'ASC' | 'DESC';
+    /** Maximum number of records to return */
+    limit?: number;
+    /** Include only records after this date */
+    since?: Date;
+    /** Include only records before this date */
+    until?: Date;
+}
+export interface RecordConsentOptions {
+    /** IP address of the consenting user */
+    ipAddress?: string;
+    /** User agent string */
+    userAgent?: string;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+    /** Expiration date for time-limited consent */
+    expiresAt?: Date;
+}
+/**
+ * ConsentVersioning class for tracking consent history with version control.
+ * Provides methods for recording, retrieving, and validating consent records.
+ */
+export declare 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 initialize(prorm: any, tableName?: string): Promise<void>;
+    private static requireModel;
+    /**
+     * 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 recordConsent(userId: string, consentType: string, granted: boolean, version: string, options?: RecordConsentOptions): Promise<ConsentVersion>;
+    /**
+     * 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 getConsentHistory(userId: string, consentType: string, options?: ConsentHistoryOptions): Promise<ConsentVersion[]>;
+    /**
+     * 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 getCurrentConsent(userId: string, consentType: string): Promise<ConsentVersion | null>;
+    /**
+     * 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 revokeConsent(userId: string, consentType: string, options?: RecordConsentOptions): Promise<ConsentVersion>;
+    /**
+     * 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 validateConsent(userId: string, consentType: string): Promise<boolean>;
+    /**
+     * 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 getActiveConsents(userId: string): Promise<ConsentVersion[]>;
+    /**
+     * 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 getConsentedUsers(consentType: string): Promise<string[]>;
+    /**
+     * 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 getConsentByVersion(userId: string, consentType: string, version: string): Promise<ConsentVersion | null>;
+    /**
+     * 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 reGrantConsent(userId: string, consentType: string, version: string, options?: RecordConsentOptions): Promise<ConsentVersion>;
+}

package/dist/compliance/cross-border-log.d.ts

@@ -0,0 +1,254 @@
+/**
+ * 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'] },
+ *   });
+ */
+import { ModelStatic, Prorm } from '../prorm';
+/** Transfer status */
+export type TransferStatus = 'pending' | 'completed' | 'blocked' | 'reviewed';
+/** Data type being transferred */
+export type DataTypeCategory = 'PII' | 'PHI' | 'PCI' | 'FINANCIAL' | 'BIOMETRIC' | 'SENSITIVE' | 'GENERAL';
+/** Region code (ISO 3166-1 alpha-2 or custom) */
+export type RegionCode = string;
+/** A transfer record stored in the database */
+export interface TransferRecord {
+    /** Unique identifier */
+    id: number;
+    /** Record ID being transferred */
+    recordId: string | number;
+    /** Table/model name */
+    tableName: string;
+    /** Source region code */
+    sourceRegion: RegionCode;
+    /** Target region code */
+    targetRegion: RegionCode;
+    /** Data category type */
+    dataType: DataTypeCategory;
+    /** Number of records transferred */
+    recordCount: number;
+    /** Transfer status */
+    status: TransferStatus;
+    /** Transfer timestamp */
+    transferredAt: Date;
+    /** Who initiated the transfer */
+    initiatedBy?: string | number;
+    /** Purpose of transfer */
+    purpose?: string;
+    /** Legal basis for transfer */
+    legalBasis?: string;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+    /** Created at timestamp */
+    createdAt: Date;
+    /** Updated at timestamp */
+    updatedAt: Date;
+}
+/** Configuration for a region */
+export interface RegionConfig {
+    /** Whether the region has adequate data protection */
+    adequateProtection: boolean;
+    /** Regulatory frameworks applicable */
+    regulations: string[];
+    /** Additional restrictions */
+    restrictions?: string[];
+    /** Custom requirements */
+    requirements?: Record<string, any>;
+}
+/** Options for CrossBorderLog.enable() */
+export interface TransferOptions {
+    /** Custom table name for transfer logs. Default: 'CrossBorderTransfers' */
+    tableName?: string;
+    /** Function to get current user ID */
+    getUserId?: () => string | number | undefined;
+    /** Function to get IP address */
+    getIpAddress?: () => string | undefined;
+    /** Auto-log all cross-region queries. Default: true */
+    autoLog?: boolean;
+    /** Require approval for specific transfers */
+    requireApproval?: (source: RegionCode, target: RegionCode, dataType: DataTypeCategory) => boolean;
+}
+interface TransferConfig {
+    model: any;
+    prorm: Prorm;
+    options: Required<TransferOptions>;
+    transferModel: ModelStatic<any>;
+}
+export declare 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: any, model: any, options?: TransferOptions): void;
+    /**
+     * 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: any, config?: TransferConfig): void;
+    /**
+     * Configure custom region settings.
+     * Merges with default region configs.
+     *
+     * @param regions - Map of region codes to their configurations
+     */
+    static configureRegions(regions: Record<RegionCode, RegionConfig>): void;
+    /**
+     * Get region configuration.
+     *
+     * @param regionCode - The region code
+     */
+    static getRegionConfig(regionCode: RegionCode): RegionConfig | undefined;
+    /**
+     * 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 logTransfer(sourceRegion: RegionCode, targetRegion: RegionCode, dataType: DataTypeCategory, records: any[], options?: {
+        recordId?: string | number;
+        tableName?: string;
+        initiatedBy?: string | number;
+        purpose?: string;
+        legalBasis?: string;
+        status?: TransferStatus;
+        metadata?: Record<string, any>;
+    }): Promise<TransferRecord>;
+    /**
+     * Get transfer history for a specific record.
+     *
+     * @param model    - The model class
+     * @param recordId - The record ID to get history for
+     */
+    static getTransferHistory(model: any, recordId: string | number): Promise<TransferRecord[]>;
+    /**
+     * Get all transfer records for a model.
+     *
+     * @param model   - The model class
+     * @param options - Filter options (source, target, status, date range)
+     */
+    static getAllTransfers(model: any, options?: {
+        sourceRegion?: RegionCode;
+        targetRegion?: RegionCode;
+        dataType?: DataTypeCategory;
+        status?: TransferStatus;
+        startDate?: Date;
+        endDate?: Date;
+        limit?: number;
+        offset?: number;
+    }): Promise<TransferRecord[]>;
+    /**
+     * 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 checkTransferAllowed(sourceRegion: RegionCode, targetRegion: RegionCode, dataType?: DataTypeCategory): Promise<{
+        allowed: boolean;
+        reason?: string;
+        requiresReview?: boolean;
+        regulations?: string[];
+    }>;
+    /**
+     * Get all regions with their configurations.
+     */
+    static listRegions(): Array<{
+        code: RegionCode;
+        config: RegionConfig;
+    }>;
+    /**
+     * Get transfer model for a model.
+     *
+     * @param model - The model class
+     */
+    static getTransferModel(model: any): ModelStatic<any> | undefined;
+    /**
+     * Disable transfer logging for a model.
+     *
+     * @param model - The model class
+     */
+    static disable(model: any): void;
+    /**
+     * List all models with transfer logging enabled.
+     */
+    static listTrackedModels(): Array<{
+        modelName: string;
+        options: TransferOptions;
+    }>;
+    /**
+     * Check if a model has transfer logging enabled.
+     *
+     * @param model - The model class
+     */
+    static isEnabled(model: any): boolean;
+    /**
+     * Reset all custom region configurations to defaults.
+     */
+    static resetRegions(): void;
+}
+/**
+ * Get all transfers for compliance reporting.
+ *
+ * @param prorm - The Prorm instance
+ * @param options   - Filter options
+ */
+export declare function getComplianceTransfers(prorm: any, options?: {
+    startDate?: Date;
+    endDate?: Date;
+    regions?: RegionCode[];
+    dataTypes?: DataTypeCategory[];
+}): Promise<TransferRecord[]>;
+/**
+ * Generate a compliance report for cross-border transfers.
+ *
+ * @param prorm - The Prorm instance
+ * @param options   - Report options
+ */
+export declare function generateTransferReport(prorm: any, options?: {
+    startDate?: Date;
+    endDate?: Date;
+    groupByRegion?: boolean;
+}): Promise<{
+    summary: {
+        totalTransfers: number;
+        uniqueRegions: number;
+        dataTypes: Record<DataTypeCategory, number>;
+    };
+    byRegion?: Record<string, any>;
+    transfers: TransferRecord[];
+}>;
+export {};

package/dist/compliance/data-classifier.d.ts

@@ -0,0 +1,127 @@
+/**
+ * DataClassifier
+ *
+ * Tags model fields with sensitivity classifications (PII, PHI, PCI, etc.)
+ * to enable other compliance classes to auto-identify sensitive data.
+ * Stores classifications in model metadata for runtime discovery.
+ *
+ * Covers ~25 compliance frameworks including:
+ *   NIST CSF, NIST SP 800-122, FIPS 199, ISO 29101, China Data Security Law,
+ *   PIPL, AI Act EU, GDPR Art 25/30/32, and data classification requirements.
+ *
+ * Usage:
+ *   // Tag fields with sensitivity levels:
+ *   @Classify('PII')
+ *   @FieldClassification('email', 'PII')
+ *   @FieldClassification('ssn', 'PHI')  // PHI = Personal Health Information
+ *   @FieldClassification('creditCard', 'PCI')
+ *   @FieldClassification('salary', 'CONFIDENTIAL')
+ *   class User extends Model { ... }
+ *
+ *   // Query classifications:
+ *   const fields = DataClassifier.getPIIFields(User);
+ *   const classification = DataClassifier.getClassification(User, 'email');
+ *   const all = DataClassifier.getClassifications(User);
+ *
+ *   // Auto-discover fields by name patterns:
+ *   DataClassifier.autoDiscover(User, ['ssn', 'social', 'dob', 'card', 'password']);
+ */
+export type SensitivityLevel = 'PUBLIC' | 'INTERNAL' | 'CONFIDENTIAL' | 'SECRET' | 'TOP_SECRET';
+export type DataCategory = 'PII' | 'PHI' | 'PCI' | 'PCI_PAN' | 'FINANCIAL' | 'HEALTH' | 'BIOMETRIC' | 'CUI' | 'SENSITIVE';
+export interface ClassificationMetadata {
+    /** The classification level */
+    level: SensitivityLevel;
+    /** The data category */
+    category: DataCategory;
+    /** Whether this field is a unique identifier */
+    isIdentifier?: boolean;
+    /** Whether this field can be used in logs/analytics */
+    canLog?: boolean;
+    /** Regulatory references */
+    regulations?: string[];
+    /** Free-form description */
+    description?: string;
+}
+/**
+ * Classify the entire model (applies to all fields, use field-level for specifics).
+ *
+ *   @Classify('CONFIDENTIAL')
+ *   class FinancialRecord extends Model { ... }
+ */
+export declare function Classify(level: SensitivityLevel): (target: Function) => void;
+/**
+ * Classify a specific field.
+ *
+ *   @FieldClassification('email', 'PII')
+ *   @FieldClassification('ssn', 'PHI', { level: 'SECRET', regulations: ['HIPAA'] })
+ *   @FieldClassification('creditCard', 'PCI_PAN', { level: 'TOP_SECRET' })
+ */
+export declare function FieldClassification(field: string, category: DataCategory, options?: Partial<ClassificationMetadata>): (target: Function) => void;
+/**
+ * Get the classification for a specific field.
+ */
+export declare function getClassification(Model: any, field: string): ClassificationMetadata | undefined;
+/**
+ * Get all classifications for a model.
+ */
+export declare function getClassificationsForModel(Model: any): Map<string, ClassificationMetadata>;
+/**
+ * Get all fields with a specific category (e.g., all PII fields).
+ */
+export declare function getFieldsByCategory(Model: any, category: DataCategory): string[];
+/**
+ * Convenience: get all PII (Personally Identifiable Information) fields.
+ */
+export declare function getPIIFields(Model: any): string[];
+/**
+ * Convenience: get all PHI (Protected Health Information) fields.
+ */
+export declare function getPHIFields(Model: any): string[];
+/**
+ * Convenience: get all PCI (Payment Card Industry) fields.
+ */
+export declare function getPCIFields(Model: any): string[];
+/**
+ * Convenience: get all financial data fields.
+ */
+export declare function getFinancialFields(Model: any): string[];
+/**
+ * Get all fields with a specific sensitivity level.
+ */
+export declare function getFieldsByLevel(Model: any, level: SensitivityLevel): string[];
+/**
+ * Get all fields classified as CONFIDENTIAL or higher.
+ */
+export declare function getConfidentialFields(Model: any): string[];
+/**
+ * Check if a field contains sensitive data (PII, PHI, PCI, etc.).
+ */
+export declare function isSensitive(Model: any, field: string): boolean;
+/**
+ * Automatically classify fields based on their names.
+ * Call this after model definition to tag common sensitive fields.
+ *
+ * @param Model - The model to scan
+ * @param patterns - Optional custom patterns (merged with defaults)
+ */
+export declare function autoDiscover(Model: any, additionalPatterns?: Array<RegExp | string>): void;
+/**
+ * Merge classifications from another model (useful for inheritance).
+ */
+export declare function inheritClassifications(child: any, parent: any): void;
+export declare class DataClassifier {
+    static Classify: typeof Classify;
+    static FieldClassification: typeof FieldClassification;
+    static getClassification: typeof getClassification;
+    static getClassifications: typeof getClassificationsForModel;
+    static getFieldsByCategory: typeof getFieldsByCategory;
+    static getPIIFields: typeof getPIIFields;
+    static getPHIFields: typeof getPHIFields;
+    static getPCIFields: typeof getPCIFields;
+    static getFinancialFields: typeof getFinancialFields;
+    static getFieldsByLevel: typeof getFieldsByLevel;
+    static getConfidentialFields: typeof getConfidentialFields;
+    static isSensitive: typeof isSensitive;
+    static autoDiscover: typeof autoDiscover;
+    static inheritClassifications: typeof inheritClassifications;
+}