ts-prorm-orm 1.1.0 → 1.2.0

package/dist/compliance/backup-verification.d.ts

@@ -0,0 +1,279 @@
+/**
+ * BackupVerification
+ *
+ * Automated backup integrity verification and test restore capabilities.
+ * Supports scheduled verification for compliance with DORA, NERC CIP,
+ * NIST CSF, and other regulatory frameworks requiring backup validation.
+ *
+ * Usage:
+ *   // Configure backup sources
+ *   BackupVerification.configure({
+ *     primary: { type: 's3', bucket: 'backups', path: 'primary/' },
+ *     secondary: { type: 'filesystem', path: '/backup/secondary' },
+ *   });
+ *
+ *   // Verify a backup
+ *   const result = await BackupVerification.verifyBackup('backup-2024-01-15');
+ *
+ *   // Test restore to staging
+ *   const restoreResult = await BackupVerification.testRestore('backup-2024-01-15');
+ *
+ *   // Schedule periodic verification
+ *   BackupVerification.scheduleVerification('backup-2024-01-15', {
+ *     frequency: 'weekly',
+ *     dayOfWeek: 'sunday',
+ *     time: '02:00',
+ *   });
+ *
+ *   // Get verification history
+ *   const history = await BackupVerification.getVerificationHistory('backup-2024-01-15');
+ */
+import { Prorm } from '../prorm';
+export interface BackupSource {
+    /** Storage type */
+    type: 's3' | 'filesystem' | 'azure' | 'gcp' | 'nfs';
+    /** Storage location - bucket name or path */
+    bucket?: string;
+    /** Path prefix or directory path */
+    path: string;
+    /** Optional credentials */
+    credentials?: {
+        accessKeyId?: string;
+        secretAccessKey?: string;
+        region?: string;
+    };
+    /** Encryption settings */
+    encryption?: {
+        enabled: boolean;
+        algorithm?: 'AES-256' | 'AES-256-GCM';
+        keyId?: string;
+    };
+    /**
+     * Optional callback that computes the real checksum (e.g. sha256 hex
+     * digest) of the backup content for `backupId`. Required for non-
+     * filesystem source types (s3/azure/gcp/nfs) if you want real checksum
+     * verification, since this library does not bundle any cloud SDKs.
+     * Without it, checksum verification for those types is inconclusive
+     * (reported as a 'warning', never fabricated as a pass).
+     */
+    computeChecksum?: (backupId: string) => Promise<string>;
+    /**
+     * Optional callback that returns true if the backup content for
+     * `backupId` actually exists and is readable/non-corrupted at the
+     * source. Required for non-filesystem source types to get a real
+     * integrity check; otherwise integrity verification is inconclusive.
+     */
+    checkReadable?: (backupId: string) => Promise<boolean>;
+}
+export interface BackupConfig {
+    /** Primary backup source */
+    primary: BackupSource;
+    /** Secondary/backup backup source (for redundancy check) */
+    secondary?: BackupSource;
+    /** Staging environment for test restores */
+    staging?: {
+        database: string;
+        host: string;
+        port?: number;
+        username: string;
+        password: string;
+    };
+    /** Verification settings */
+    verification?: {
+        /** Verify checksum integrity (default: true) */
+        verifyChecksum?: boolean;
+        /** Verify encryption (default: true) */
+        verifyEncryption?: boolean;
+        /** Verify backup is not corrupted (default: true) */
+        verifyIntegrity?: boolean;
+        /** Minimum backup age to verify (default: 0) */
+        minAgeHours?: number;
+    };
+    /** Notification settings */
+    notifications?: {
+        onSuccess?: boolean;
+        onFailure?: boolean;
+        emailRecipients?: string[];
+        webhookUrl?: string;
+    };
+}
+export interface BackupMetadata {
+    backupId: string;
+    source: string;
+    timestamp: Date;
+    size: number;
+    checksum?: string;
+    encrypted: boolean;
+    compression?: string;
+    retentionDays?: number;
+    /**
+     * Optional snapshot of database state captured at backup time (e.g. via
+     * BackupVerification.captureSnapshot()). Used by testRestore() to
+     * compare row counts against current live state, since this library
+     * cannot perform a true restore-and-diff without a real backup/restore
+     * engine or a second staging database connection.
+     */
+    snapshot?: {
+        rowCounts: Record<string, number>;
+        capturedAt: Date;
+    };
+}
+export interface VerificationResult {
+    /** Unique verification ID */
+    verificationId: string;
+    /** The backup ID being verified */
+    backupId: string;
+    /** Verification status */
+    status: 'passed' | 'failed' | 'warning';
+    /** Timestamp of verification */
+    timestamp: Date;
+    /** Checksum verification result */
+    checksumValid?: boolean;
+    /** Encryption verification result */
+    encryptionValid?: boolean;
+    /** Integrity check result */
+    integrityValid?: boolean;
+    /** Test restore result */
+    restoreResult?: {
+        success: boolean;
+        rowsRestored?: number;
+        duration?: number;
+        errorMessage?: string;
+        /**
+         * Clarifying note about what this restore check does/does not
+         * guarantee (e.g. "reachability-only, no snapshot to compare"). May be
+         * present alongside success: true.
+         */
+        note?: string;
+    };
+    /** Detailed messages */
+    messages: string[];
+    /** Compliance frameworks this verification satisfies */
+    complianceFrameworks: string[];
+    /** Duration of verification in milliseconds */
+    durationMs: number;
+}
+export interface VerificationSchedule {
+    /** Frequency of verification */
+    frequency: 'daily' | 'weekly' | 'monthly';
+    /** Day of week for weekly (0=sunday, 6=saturday) */
+    dayOfWeek?: number;
+    /** Day of month for monthly (1-31) */
+    dayOfMonth?: number;
+    /** Time in HH:MM format (24-hour) */
+    time: string;
+    /** Next scheduled run */
+    nextRun?: Date;
+    /** Whether the schedule is active */
+    active: boolean;
+}
+export interface VerificationHistoryEntry {
+    verificationId: string;
+    backupId: string;
+    status: 'passed' | 'failed' | 'warning';
+    timestamp: Date;
+    durationMs: number;
+    checksumValid?: boolean;
+    integrityValid?: boolean;
+    restoreSuccess?: boolean;
+}
+export declare class BackupVerification {
+    /**
+     * Configure backup sources and verification settings.
+     *
+     * @param config - Backup configuration including primary/secondary sources,
+     *                 staging environment, and verification options
+     */
+    static configure(config: BackupConfig): void;
+    /**
+     * Register a backup in the system for tracking.
+     *
+     * @param metadata - Backup metadata including ID, source, timestamp, etc.
+     * @param source - Source identifier ('primary' or 'secondary')
+     */
+    static registerBackup(metadata: BackupMetadata, source?: string): void;
+    /**
+     * Capture a real row-count snapshot of a live database, intended to be
+     * taken at (or immediately before/after) backup time and stored on
+     * `BackupMetadata.snapshot`. This is the "strongest achievable"
+     * verification baseline this library can produce without a real
+     * restore/import engine: it lets testRestore() report what the backup
+     * *should* contain, even though it cannot prove the backup file itself
+     * restores to that state.
+     *
+     * @param prorm - A connected Prorm instance to query
+     * @param tables    - Table names to count rows for
+     * @returns A snapshot with real row counts per table
+     */
+    static captureSnapshot(prorm: Prorm, tables: string[]): Promise<NonNullable<BackupMetadata['snapshot']>>;
+    /**
+     * Verify the integrity of a backup without performing a full restore.
+     *
+     * @param backupId - The backup ID to verify
+     * @returns Verification result with status and details
+     */
+    static verifyBackup(backupId: string): Promise<VerificationResult>;
+    /**
+     * Test restore a backup to a staging environment.
+     * This performs an actual restore to verify backup is valid.
+     *
+     * @param backupId - The backup ID to test restore
+     * @returns Verification result including restore details
+     */
+    static testRestore(backupId: string): Promise<VerificationResult>;
+    /**
+     * Schedule periodic verification for a backup.
+     *
+     * @param backupId - The backup ID to schedule verification for
+     * @param schedule - Verification schedule configuration
+     */
+    static scheduleVerification(backupId: string, schedule: VerificationSchedule): void;
+    /**
+     * Remove a scheduled verification.
+     *
+     * @param backupId - The backup ID to remove schedule for
+     */
+    static removeScheduledVerification(backupId: string): boolean;
+    /**
+     * Get all scheduled verifications.
+     *
+     * @returns Array of scheduled verification entries
+     */
+    static getScheduledVerifications(): Array<{
+        backupId: string;
+        schedule: VerificationSchedule;
+        nextRun: Date;
+    }>;
+    /**
+     * Get verification history for a backup.
+     *
+     * @param backupId - The backup ID to get history for
+     * @returns Array of verification history entries
+     */
+    static getVerificationHistory(backupId: string): VerificationHistoryEntry[];
+    /**
+     * Get all backups registered in the system.
+     *
+     * @returns Array of backup entries
+     */
+    static listBackups(): Array<{
+        backupId: string;
+        metadata: BackupMetadata;
+        source: string;
+    }>;
+    /**
+     * Get the current configuration.
+     *
+     * @returns Current backup configuration
+     */
+    static getConfiguration(): {
+        sources: Map<string, BackupSource>;
+        staging: BackupConfig['staging'] | undefined;
+        verification: BackupConfig['verification'] | undefined;
+        notifications: BackupConfig['notifications'] | undefined;
+    };
+    /**
+     * Clear all configuration (useful for testing).
+     */
+    static clear(): void;
+}

package/dist/compliance/breach-detector.d.ts

@@ -0,0 +1,197 @@
+/**
+ * BreachDetector
+ *
+ * A comprehensive breach detection and monitoring system for identifying
+ * unusual access patterns, mass exports, failed authentication attempts,
+ * and suspicious query patterns.
+ *
+ * Required for compliance with:
+ *   - NIST CSF (PR.AC-1, PR.AC-2, PR.DS-5)
+ *   - CIS Controls (CIS 3.4, 8.2, 8.5)
+ *   - MITRE ATT&CK (TA0001, TA0009, TA0010)
+ *
+ * Usage:
+ *   // Initialize breach detection
+ *   const detector = BreachDetector.create(prorm, {
+ *     alertCallback: (alert) => securityTeam.notify(alert),
+ *     massExportThreshold: 1000,
+ *     rateLimitWindow: 60000,
+ *     rateLimitMax: 100,
+ *   });
+ *
+ *   // Start monitoring
+ *   await detector.start();
+ *
+ *   // Query alerts and stats
+ *   const alerts = detector.getAlerts();
+ *   const stats = detector.getStats();
+ */
+import { Prorm } from '../prorm';
+/** Alert severity levels */
+export type BreachSeverity = 'low' | 'medium' | 'high' | 'critical';
+/** Categories of breaches detected */
+export type BreachCategory = 'mass_export' | 'failed_auth' | 'unusual_access_time' | 'rate_limit_exceeded' | 'suspicious_query_pattern' | 'bulk_download';
+/** A breach alert */
+export interface BreachAlert {
+    id: string;
+    timestamp: Date;
+    severity: BreachSeverity;
+    category: BreachCategory;
+    message: string;
+    details: Record<string, unknown>;
+    userId?: string;
+    ipAddress?: string;
+    query?: string;
+}
+/** Configuration options for BreachDetector */
+export interface BreachDetectorOptions {
+    /** Callback for real-time alerts to security team */
+    alertCallback?: (alert: BreachAlert) => void;
+    /** Maximum records that can be exported in a single query before alerting */
+    massExportThreshold?: number;
+    /** Time window for rate limiting in milliseconds */
+    rateLimitWindow?: number;
+    /** Maximum queries allowed per rate limit window */
+    rateLimitMax?: number;
+    /** Number of failed auth attempts before alerting */
+    failedAuthThreshold?: number;
+    /** Time window for failed auth tracking in milliseconds */
+    failedAuthWindow?: number;
+    /** Enable detection of unusual access times */
+    detectUnusualAccessTime?: boolean;
+    /** Allowed hours (24h format) for normal access */
+    allowedHours?: number[];
+    /** Enable suspicious query pattern detection */
+    detectSuspiciousPatterns?: boolean;
+    /** Maximum alerts to keep in memory */
+    maxAlerts?: number;
+    /** Minimum severity to trigger alert callback */
+    minAlertSeverity?: BreachSeverity;
+    /** Custom suspicious query patterns (regex) */
+    customPatterns?: RegExp[];
+    /** Track queries by user ID */
+    trackByUser?: boolean;
+    /** Track queries by IP address */
+    trackByIP?: boolean;
+}
+export declare class BreachDetector {
+    private prorm;
+    private options;
+    private alerts;
+    private isRunning;
+    private originalQuery;
+    private queryTimestamps;
+    private failedAuthAttempts;
+    private accessPatterns;
+    private startTime;
+    private stats;
+    private constructor();
+    /**
+     * Create a new BreachDetector instance
+     */
+    static create(prorm: Prorm, options?: BreachDetectorOptions): BreachDetector;
+    /**
+     * Start monitoring queries for breaches
+     */
+    start(): Promise<void>;
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+    /**
+     * Setup hooks for bulk operation monitoring
+     */
+    private setupBulkOperationHooks;
+    /**
+     * Analyze a query for breach patterns
+     */
+    private analyzeQuery;
+    /**
+     * Analyze errors for security events
+     */
+    private analyzeError;
+    /**
+     * Check for bulk operations
+     */
+    private checkBulkOperation;
+    /**
+     * Check rate limiting
+     */
+    private checkRateLimit;
+    /**
+     * Check for unusual access time
+     */
+    private checkUnusualAccessTime;
+    /**
+     * Check for suspicious query patterns
+     */
+    private checkSuspiciousPatterns;
+    /**
+     * Track failed authentication attempts
+     */
+    private trackFailedAuth;
+    /**
+     * Get identifier key for rate limiting
+     */
+    private getIdentifierKey;
+    /**
+     * Add an alert
+     */
+    private addAlert;
+    /**
+     * Check if alert severity meets callback threshold
+     */
+    private shouldTriggerCallback;
+    /**
+     * Get all breach alerts
+     */
+    getAlerts(options?: {
+        severity?: BreachSeverity;
+        category?: BreachCategory;
+        limit?: number;
+    }): BreachAlert[];
+    /**
+     * Get detection statistics
+     */
+    getStats(): {
+        uptime: number;
+        totalQueries: number;
+        totalAlerts: number;
+        massExportAlerts: number;
+        failedAuthAlerts: number;
+        rateLimitAlerts: number;
+        unusualTimeAlerts: number;
+        suspiciousPatternAlerts: number;
+        bulkDownloadAlerts: number;
+        alertsBySeverity: Record<BreachSeverity, number>;
+        alertsByCategory: Record<BreachCategory, number>;
+    };
+    /**
+     * Clear all alerts
+     */
+    clearAlerts(): void;
+    /**
+     * Check if monitoring is active
+     */
+    isActive(): boolean;
+    /**
+     * Manually trigger an alert (for custom checks)
+     */
+    alert(options: Omit<BreachAlert, 'id' | 'timestamp'>): void;
+    /**
+     * Record a query execution (for external tracking)
+     */
+    recordQuery(userId?: string, ipAddress?: string, recordsAffected?: number): void;
+    /**
+     * Record authentication failure
+     */
+    recordAuthFailure(userId?: string, ipAddress?: string): void;
+}
+/**
+ * Get the global BreachDetector instance
+ */
+export declare function getGlobalBreachDetector(): BreachDetector | null;
+/**
+ * Initialize the global BreachDetector instance
+ */
+export declare function initBreachDetector(prorm: Prorm, options?: BreachDetectorOptions): BreachDetector;

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

@@ -0,0 +1,107 @@
+/**
+ * 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');
+ */
+export type LegalBasis = 'consent' | 'contract' | 'legal_obligation' | 'vital_interests' | 'public_task' | 'legitimate_interests';
+/**
+ * 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.
+ */
+export declare enum LegalBasisEnum {
+    Consent = "consent",
+    Contract = "contract",
+    LegalObligation = "legal_obligation",
+    VitalInterests = "vital_interests",
+    PublicTask = "public_task",
+    LegitimateInterests = "legitimate_interests"
+}
+export interface ConsentGrantOptions {
+    /** Unique identifier of the data subject */
+    subjectId: string;
+    /** Purpose of the processing (e.g. 'marketing_emails', 'analytics') */
+    purpose: string;
+    /** GDPR/equivalent legal basis for processing */
+    legalBasis?: LegalBasis | LegalBasisEnum;
+    /** Version of the privacy notice / consent form shown */
+    version?: string;
+    /** IP address of the consenting user */
+    ipAddress?: string;
+    /** Additional metadata (e.g. consent UI element ID, A/B test variant) */
+    metadata?: Record<string, any>;
+}
+export interface ConsentWithdrawOptions {
+    /** Reason for withdrawal, if provided by the user */
+    reason?: string;
+}
+export declare 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 initialize(prorm: any, tableName?: string): Promise<void>;
+    private static requireModel;
+    /**
+     * 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 grant(options: ConsentGrantOptions): Promise<any>;
+    /**
+     * 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 withdraw(subjectId: string, purpose: string, options?: ConsentWithdrawOptions): Promise<boolean>;
+    /**
+     * Check whether an active (non-withdrawn) consent exists.
+     */
+    static isActive(subjectId: string, purpose: string): Promise<boolean>;
+    /**
+     * Get the full consent history for a subject (all purposes).
+     */
+    static getHistory(subjectId: string): Promise<any[]>;
+    /**
+     * Get active consents for a subject grouped by purpose.
+     */
+    static getActiveConsents(subjectId: string): Promise<any[]>;
+    /**
+     * List all subjects who have active consent for a specific purpose.
+     * Useful for marketing campaign validation.
+     */
+    static getConsented(purpose: string): Promise<string[]>;
+}