ts-prorm-orm 1.1.0 → 1.2.0

package/dist/compliance/session-isolation.d.ts

@@ -0,0 +1,286 @@
+/**
+ * SessionIsolation
+ *
+ * Provides multi-tenant data isolation using AsyncLocalStorage for automatic
+ * tenant context propagation. Implements tenant-specific encryption keys,
+ * session management, and tenant-aware audit logging.
+ *
+ * Covers compliance frameworks including:
+ *   ISO 27017, FedRAMP, CPRA, GDPR, HIPAA, SOC 2, NIST SP 800-53, and more.
+ *
+ * Usage:
+ *   // At app startup, initialize session isolation:
+ *   SessionIsolation.init({ sessionTimeout: 30 * 60 * 1000 });
+ *
+ *   // Register tenant encryption keys:
+ *   SessionIsolation.registerTenantKey('tenant-123', 'encryption-key-32-bytes');
+ *
+ *   // In your authentication middleware:
+ *   SessionIsolation.setTenant({
+ *     tenantId: 'tenant-123',
+ *     sessionId: 'session-abc',
+ *     userId: 'user-456',
+ *     roles: ['admin']
+ *   });
+ *
+ *   // Run operations in a specific tenant context:
+ *   const result = SessionIsolation.runInTenant('tenant-123', () => {
+ *     return db.User.findAll();
+ *   });
+ *
+ *   // Use the decorator on models:
+ *   @TenantIsolation({ tenantId: 'tenantId', auditEnabled: true })
+ *   class Document extends Model { ... }
+ */
+export interface TenantContext {
+    /** The tenant identifier */
+    tenantId: string;
+    /** The current session ID */
+    sessionId: string;
+    /** The user ID */
+    userId?: string;
+    /** User roles within this tenant */
+    roles?: string[];
+    /** Session creation timestamp */
+    sessionCreatedAt?: Date;
+    /** Last activity timestamp */
+    lastActivityAt?: Date;
+    /** Custom tenant metadata */
+    metadata?: Record<string, any>;
+}
+export interface TenantKey {
+    /** The tenant ID this key belongs to */
+    tenantId: string;
+    /** The encryption key (32 bytes for AES-256) */
+    key: string;
+    /** Key version/rotation identifier */
+    keyVersion?: string;
+    /** When this key was registered */
+    createdAt: Date;
+    /** When this key expires (for rotation) */
+    expiresAt?: Date;
+}
+export interface SessionInfo {
+    /** Session identifier */
+    sessionId: string;
+    /** Tenant ID */
+    tenantId: string;
+    /** User ID */
+    userId: string;
+    /** When session was created */
+    createdAt: Date;
+    /** When session expires */
+    expiresAt: Date;
+    /** Last activity timestamp */
+    lastActivityAt: Date;
+    /** Whether session is active */
+    isActive: boolean;
+    /** IP address of session creation */
+    ipAddress?: string;
+    /** User agent of session creation */
+    userAgent?: string;
+}
+export interface SessionIsolationOptions {
+    /** Session timeout in milliseconds. Default: 30 minutes */
+    sessionTimeout?: number;
+    /** Maximum number of concurrent sessions per tenant. Default: unlimited */
+    maxSessionsPerTenant?: number;
+    /** Maximum sessions per user. Default: 5 */
+    maxSessionsPerUser?: number;
+    /** Enable automatic session cleanup. Default: true */
+    autoCleanup?: boolean;
+    /** Cleanup interval in milliseconds. Default: 5 minutes */
+    cleanupInterval?: number;
+    /** Enable tenant-aware audit logging. Default: true */
+    auditEnabled?: boolean;
+    /** Custom session storage (for distributed setups) */
+    sessionStore?: SessionStore;
+    /** Custom key storage (for distributed setups) */
+    keyStore?: KeyStore;
+}
+export interface TenantIsolationDecoratorOptions {
+    /** The field name that holds the tenant ID */
+    tenantId: string;
+    /** Enable audit logging for this model */
+    auditEnabled?: boolean;
+    /** Fields to encrypt */
+    encryptFields?: string[];
+    /** Required roles to access */
+    requiredRoles?: string[];
+}
+export interface SessionStore {
+    get(sessionId: string): Promise<SessionInfo | null>;
+    set(sessionId: string, info: SessionInfo): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    getByTenant(tenantId: string): Promise<SessionInfo[]>;
+    getByUser(userId: string): Promise<SessionInfo[]>;
+    cleanup(expiredBefore: Date): Promise<number>;
+}
+export interface KeyStore {
+    get(tenantId: string): Promise<TenantKey | null>;
+    set(tenantId: string, key: TenantKey): Promise<void>;
+    delete(tenantId: string): Promise<void>;
+    getAll(): Promise<TenantKey[]>;
+}
+export declare class SessionIsolation {
+    /**
+     * Initialize session isolation. Call once at application startup.
+     *
+     * @param opts - Configuration options
+     */
+    static init(opts?: SessionIsolationOptions): void;
+    /**
+     * Reset the session isolation system. Useful for testing.
+     */
+    static reset(): void;
+    /**
+     * Set the current tenant context for this request/operation.
+     *
+     * @param ctx - The tenant context
+     */
+    static setTenant(ctx: TenantContext): void;
+    /**
+     * Get the current tenant context.
+     *
+     * @returns The current tenant context, or undefined if not set
+     */
+    static getTenant(): TenantContext | undefined;
+    /**
+     * Clear the current tenant context.
+     */
+    static clearTenant(): void;
+    /**
+     * Run a function within a specific tenant context.
+     *
+     * @param tenantId - The tenant ID to run in
+     * @param fn - The function to execute
+     * @returns The result of the function
+     */
+    static runInTenant<T>(tenantId: string, fn: () => T): T;
+    /**
+     * Register an encryption key for a tenant.
+     *
+     * @param tenantId - The tenant ID
+     * @param key - The encryption key (32 bytes recommended for AES-256)
+     * @param keyVersion - Optional key version for rotation
+     */
+    static registerTenantKey(tenantId: string, key: string, keyVersion?: string): Promise<void>;
+    /**
+     * Get the encryption key for a tenant.
+     *
+     * @param tenantId - The tenant ID
+     * @returns The tenant key, or undefined if not found
+     */
+    static getTenantKey(tenantId: string): Promise<TenantKey | undefined>;
+    /**
+     * Validate a session.
+     *
+     * @param sessionId - The session ID to validate
+     * @returns SessionInfo if valid, null if invalid/expired
+     */
+    static validateSession(sessionId: string): Promise<SessionInfo | null>;
+    /**
+     * Manually expire a session.
+     *
+     * @param sessionId - The session ID to expire
+     */
+    static expireSession(sessionId: string): Promise<void>;
+    /**
+     * Create a new session for a tenant.
+     *
+     * @param tenantId - The tenant ID
+     * @param userId - The user ID
+     * @param options - Additional session options
+     * @returns The created session info
+     */
+    static createSession(tenantId: string, userId: string, options?: {
+        ipAddress?: string;
+        userAgent?: string;
+        customExpiresAt?: Date;
+    }): Promise<SessionInfo>;
+    /**
+     * Get all active sessions for a tenant.
+     *
+     * @param tenantId - The tenant ID
+     * @returns Array of session info
+     */
+    static getTenantSessions(tenantId: string): Promise<SessionInfo[]>;
+    /**
+     * Get all active sessions for a user.
+     *
+     * @param userId - The user ID
+     * @returns Array of session info
+     */
+    static getUserSessions(userId: string): Promise<SessionInfo[]>;
+    /**
+     * Clean up all expired sessions.
+     *
+     * @returns Number of sessions cleaned up
+     */
+    static cleanupExpiredSessions(): Promise<number>;
+    /**
+     * Get the current session timeout value.
+     *
+     * @returns Timeout in milliseconds
+     */
+    static getSessionTimeout(): number;
+    /**
+     * Check if session isolation is initialized.
+     *
+     * @returns True if initialized
+     */
+    static isReady(): boolean;
+}
+/**
+ * Decorator to apply tenant isolation to a model.
+ *
+ *   @TenantIsolation({ tenantId: 'tenantId', auditEnabled: true })
+ *   class Document extends Model {
+ *     tenantId: string;
+ *     title: string;
+ *   }
+ *
+ * @param options - Tenant isolation options
+ */
+export declare function TenantIsolation(options: TenantIsolationDecoratorOptions): (target: any) => void;
+/**
+ * Get tenant isolation options from a decorated model.
+ *
+ * @param model - The model class
+ * @returns The decorator options, or undefined if not decorated
+ */
+export declare function getTenantIsolationOptions(model: any): TenantIsolationDecoratorOptions | undefined;
+/**
+ * Express/Koa middleware to automatically set tenant context from request.
+ *
+ *   app.use(authMiddleware);           // sets req.user
+ *   app.use(sessionIsolationMiddleware);
+ *
+ * @param options - Middleware options
+ */
+export declare function sessionIsolationMiddleware(req: any, res: any, next: () => void): void;
+/**
+ * Get tenant-aware audit metadata for the current context.
+ * Use this to include tenant information in audit logs.
+ *
+ * @returns Audit metadata object
+ */
+export declare function getTenantAuditMetadata(): Record<string, any>;
+export declare const TenantIsolationManager: {
+    init: typeof SessionIsolation.init;
+    reset: typeof SessionIsolation.reset;
+    setTenant: typeof SessionIsolation.setTenant;
+    getTenant: typeof SessionIsolation.getTenant;
+    clearTenant: typeof SessionIsolation.clearTenant;
+    runInTenant: typeof SessionIsolation.runInTenant;
+    registerTenantKey: typeof SessionIsolation.registerTenantKey;
+    getTenantKey: typeof SessionIsolation.getTenantKey;
+    validateSession: typeof SessionIsolation.validateSession;
+    expireSession: typeof SessionIsolation.expireSession;
+    createSession: typeof SessionIsolation.createSession;
+    getTenantSessions: typeof SessionIsolation.getTenantSessions;
+    getUserSessions: typeof SessionIsolation.getUserSessions;
+    cleanupExpiredSessions: typeof SessionIsolation.cleanupExpiredSessions;
+    getSessionTimeout: typeof SessionIsolation.getSessionTimeout;
+    isReady: typeof SessionIsolation.isReady;
+};

package/dist/compliance/tls-enforcer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * TLSEnforcer
+ *
+ * Validates and enforces TLS/SSL on database connections at startup.
+ * Throws a descriptive error if the connection is not encrypted,
+ * preventing insecure deployments from reaching production.
+ *
+ * Covers ~54 compliance frameworks including:
+ *   GDPR Art 32, HIPAA, PCI DSS, NIST SP 800-53, FedRAMP, SOC 2,
+ *   ISO 27001, NYDFS 23 NYCRR 500, HITRUST, NIS2, DORA, and more.
+ *
+ * Usage:
+ *   const prorm = new Prorm({ ... });
+ *   TLSEnforcer.enforce(prorm);                       // strict
+ *   TLSEnforcer.enforce(prorm, { mode: 'warn' });     // log only
+ *   TLSEnforcer.enforce(prorm, { allowLocal: true }); // skip for localhost
+ */
+export type TLSMode = 'strict' | 'warn' | 'off';
+export interface TLSEnforcerOptions {
+    /**
+     * 'strict' (default) — throw if TLS is not configured.
+     * 'warn'             — log a warning but continue.
+     * 'off'              — disable enforcement entirely.
+     */
+    mode?: TLSMode;
+    /**
+     * If true, skip enforcement for localhost / 127.0.0.1 / ::1 connections.
+     * Useful for local development without a dev certificate. Default: false.
+     */
+    allowLocal?: boolean;
+    /** Custom logger. Defaults to console.warn. */
+    logger?: (message: string) => void;
+}
+export declare class TLSEnforcer {
+    /**
+     * Enforce TLS on the given Prorm instance.
+     * Call immediately after constructing the Prorm instance.
+     *
+     * @param prorm - The Prorm instance to inspect
+     * @param options   - Enforcement mode and options
+     */
+    static enforce(prorm: any, options?: TLSEnforcerOptions): void;
+    /**
+     * Return recommended SSL dialectOptions for a given dialect.
+     * Use this as a starting point when configuring your connection.
+     */
+    static recommendedOptions(dialect: 'postgres' | 'mysql' | 'mariadb' | 'mssql', options?: {
+        rejectUnauthorized?: boolean;
+        ca?: string;
+    }): Record<string, any>;
+}

package/dist/compliance/worm-storage.d.ts

@@ -0,0 +1,225 @@
+/**
+ * WORMStorage (Write Once Read Many)
+ *
+ * Immutable archival storage that prevents UPDATE and DELETE operations after commit.
+ * Provides tamper-evident audit trails and retention period enforcement.
+ *
+ * Covers compliance frameworks including:
+ *   SEC 17a-4 (WORM), FINRA, SOX, DORA, MiFID II, GDPR Art 32,
+ *   ALCOA+, 21 CFR Part 11, and financial audit requirements.
+ *
+ * Usage:
+ *   // Enable WORM on a model:
+ *   WORMStorage.enable(FinancialRecord, {
+ *     retentionPeriod: { years: 7 },
+ *     tamperEvident: true,
+ *   });
+ *
+ *   // Archive a record (moves to archived state):
+ *   await WORMStorage.archive(record);
+ *
+ *   // Freeze a record (fully immutable):
+ *   await WORMStorage.freeze(record);
+ *
+ *   // Verify integrity of a record:
+ *   const isValid = await WORMStorage.verifyIntegrity(recordId, 'FinancialRecords');
+ *
+ *   // Get tamper evidence log:
+ *   const log = await WORMStorage.getTamperLog(recordId, 'FinancialRecords');
+ *
+ *   // Enforce retention policy:
+ *   await WORMStorage.enforceRetention(FinancialRecord, prorm);
+ *
+ *   // Using the decorator:
+ *   @WORM({ retentionPeriod: { years: 7 }, tamperEvident: true })
+ *   class FinancialRecord extends Model { ... }
+ */
+import { ModelStatic, Prorm } from '../prorm';
+import { RetentionDuration } from './data-retention';
+/** Archive state machine states */
+export type ArchiveState = 'active' | 'archived' | 'frozen';
+/** WORM configuration options */
+export interface WORMOptions {
+    /** Retention period for the records */
+    retentionPeriod: RetentionDuration;
+    /** Enable tamper-evident audit trail. Default: true */
+    tamperEvident?: boolean;
+    /** Custom table name for WORM metadata. Default: 'WORMMetadata' */
+    tableName?: string;
+    /** State field name. Default: 'wormState' */
+    stateField?: string;
+    /** Timestamp field for archive. Default: 'archivedAt' */
+    timestampField?: string;
+    /** Allow soft deletes instead of hard blocks. Default: false */
+    allowSoftDelete?: boolean;
+    /** Automatically archive after creation. Default: false */
+    autoArchive?: boolean;
+    /** Auto-freeze after retention period. Default: false */
+    autoFreeze?: boolean;
+    /** Integrate with DataRetentionPolicy. Default: true */
+    integrateWithRetention?: boolean;
+}
+/** Tamper log entry for chain verification */
+export interface WORMTamperLog {
+    /** Unique identifier */
+    id: number;
+    /** Record ID this log applies to */
+    recordId: string | number;
+    /** Table name */
+    tableName: string;
+    /** Operation performed */
+    operation: 'create' | 'archive' | 'freeze' | 'unfreeze' | 'tamper_detected';
+    /** Hash of record state at this point */
+    hash: string;
+    /** Previous hash in chain */
+    previousHash: string;
+    /** Timestamp of operation */
+    timestamp: Date;
+    /** User who performed the operation */
+    performedBy?: string | number;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+/** WORM configuration stored in registry */
+interface WORMConfig {
+    model: any;
+    prorm: Prorm;
+    options: Required<WORMOptions>;
+    metadataModel: ModelStatic<any>;
+    tamperLogModel: ModelStatic<any>;
+}
+/**
+ * Decorator to mark a model for WORM storage.
+ *
+ *   @WORM({ retentionPeriod: { years: 7 }, tamperEvident: true })
+ *   class FinancialRecord extends Model { ... }
+ */
+export declare function WORM(options: WORMOptions): (target: Function) => void;
+/**
+ * Get the WORM options for a model.
+ */
+export declare function getWORMOptions(Model: any): WORMOptions | undefined;
+export declare class WORMStorage {
+    /**
+     * Enable WORM storage on a model.
+     * Creates necessary metadata tables and registers hooks.
+     *
+     * @param model     - The model class to protect
+     * @param prorm - The Prorm instance
+     * @param options   - WORM configuration options
+     */
+    static enable(model: any, prorm: Prorm, options: WORMOptions): void;
+    /**
+     * Apply hooks to a model for WORM protection.
+     * Called automatically by enable().
+     *
+     * @param model  - The model class
+     * @param config - The WORM configuration
+     */
+    static applyHooks(model: any, config?: WORMConfig): void;
+    /**
+     * Archive a record (moves to archived state).
+     * Archived records are read-only but can still be queried.
+     *
+     * @param record - The record instance to archive
+     */
+    static archive(record: any): Promise<void>;
+    /**
+     * Freeze a record (fully immutable).
+     * Frozen records cannot be modified or deleted.
+     *
+     * @param record - The record instance to freeze
+     */
+    static freeze(record: any): Promise<void>;
+    /**
+     * Get the tamper evidence log for a record.
+     *
+     * @param recordId  - The record ID
+     * @param tableName - The table name
+     */
+    static getTamperLog(recordId: string | number, tableName: string): Promise<WORMTamperLog[]>;
+    /**
+     * Verify the integrity of a record's tamper chain.
+     *
+     * @param recordId  - The record ID
+     * @param tableName - The table name
+     * @returns True if chain is valid, false if tampering detected
+     */
+    static verifyIntegrity(recordId: string | number, tableName: string): Promise<boolean>;
+    /**
+     * Check if WORM is enabled on a model.
+     *
+     * @param model - The model class
+     */
+    static isWORMEnabled(model: any): boolean;
+    /**
+     * Get the WORM configuration for a model.
+     *
+     * @param model - The model class
+     */
+    static getConfig(model: any): WORMOptions | undefined;
+    /**
+     * Enforce retention policy on a model.
+     * This will delete or anonymize records that have exceeded their retention period.
+     *
+     * @param model     - The model class
+     * @param prorm - The Prorm instance
+     */
+    static enforceRetention(model: any, prorm: any): Promise<{
+        affected: number;
+        mode: string;
+    }>;
+    /**
+     * Get the archive state of a record.
+     *
+     * @param recordId  - The record ID
+     * @param tableName - The table name
+     */
+    static getState(recordId: string | number, tableName: string): Promise<ArchiveState | null>;
+    /**
+     * Disable WORM storage for a model.
+     *
+     * @param model - The model class
+     */
+    static disable(model: any): void;
+    /**
+     * Get the WORM metadata model for a model.
+     *
+     * @param model - The model class
+     */
+    static getMetadataModel(model: any): ModelStatic<any> | undefined;
+    /**
+     * Get the tamper log model for a model.
+     *
+     * @param model - The model class
+     */
+    static getTamperLogModel(model: any): ModelStatic<any> | undefined;
+    /**
+     * List all models with WORM storage enabled.
+     */
+    static listWORMModels(): Array<{
+        modelName: string;
+        options: WORMOptions;
+    }>;
+}
+/**
+ * Apply WORM hooks to a model (exported for convenience).
+ *
+ * @param model - The model class
+ */
+export declare function applyWORMHooks(model: any): void;
+/**
+ * Check if a specific record is frozen.
+ *
+ * @param recordId  - The record ID
+ * @param tableName - The table name
+ */
+export declare function isFrozen(recordId: string | number, tableName: string): Promise<boolean>;
+/**
+ * Check if a specific record is archived.
+ *
+ * @param recordId  - The record ID
+ * @param tableName - The table name
+ */
+export declare function isArchived(recordId: string | number, tableName: string): Promise<boolean>;
+export {};

package/dist/connection-manager.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Connection Manager for managing multiple named database connections
+ * Supports cross-database queries and SQLite ATTACH DATABASE
+ */
+import { Prorm, PrormOptions } from './prorm';
+/**
+ * Named connection options for adding a new database connection
+ */
+export interface NamedConnectionOptions {
+    /** Unique name to identify this connection */
+    name: string;
+    /** Prorm options for the connection */
+    options: PrormOptions;
+}
+/**
+ * Connection Manager class for managing multiple database connections
+ * Allows switching between different databases in the same application
+ */
+export declare class ConnectionManager {
+    private connections;
+    private _defaultConnection;
+    /**
+     * Create a new ConnectionManager instance
+     */
+    constructor();
+    /**
+     * Add a new named database connection
+     * @param name - Unique name to identify this connection
+     * @param options - Prorm options for the connection
+     * @returns The Prorm instance for the new connection
+     * @example
+     * // Add a secondary SQLite database
+     * const manager = new ConnectionManager();
+     * await manager.addConnection('analytics', {
+     *   dialect: 'sqlite',
+     *   storage: './analytics.db'
+     * });
+     */
+    addConnection(name: string, options: PrormOptions): Promise<Prorm>;
+    /**
+     * Get a connection by name
+     * @param name - The connection name
+     * @returns The Prorm instance or undefined if not found
+     * @example
+     * const analyticsDb = manager.getConnection('analytics');
+     */
+    getConnection(name: string): Prorm | undefined;
+    /**
+     * Check if a connection exists
+     * @param name - The connection name to check
+     * @returns True if the connection exists
+     * @example
+     * if (manager.hasConnection('analytics')) {
+     *   // Use analytics connection
+     * }
+     */
+    hasConnection(name: string): boolean;
+    /**
+     * Remove a connection by name
+     * @param name - The connection name to remove
+     * @returns True if the connection was removed
+     * @example
+     * await manager.removeConnection('analytics');
+     */
+    removeConnection(name: string): Promise<boolean>;
+    /**
+     * Get all connection names
+     * @returns Array of connection names
+     * @example
+     * const names = manager.getConnectionNames();
+     * // ['main', 'analytics', 'logs']
+     */
+    getConnectionNames(): string[];
+    /**
+     * Get or set the default connection name
+     */
+    get defaultConnection(): string | null;
+    set defaultConnection(name: string | null);
+    /**
+     * Get all connections
+     * @returns Map of connection names to Prorm instances
+     */
+    get connectionsMap(): Map<string, Prorm>;
+    /**
+     * Attach a SQLite database using ATTACH DATABASE
+     * This allows querying across multiple SQLite files
+     * @param mainConnectionName - The name of the main connection to attach to
+     * @param alias - The alias to use for the attached database
+     * @param path - Path to the SQLite file to attach
+     * @example
+     * // Attach analytics database to main connection
+     * await manager.attachDatabase('main', 'analytics', './analytics.db');
+     * // Now you can query: SELECT * FROM analytics.users
+     */
+    attachDatabase(mainConnectionName: string, alias: string, path: string): Promise<void>;
+    /**
+     * Detach a SQLite database
+     * @param mainConnectionName - The name of the main connection
+     * @param alias - The alias of the database to detach
+     * @example
+     * await manager.detachDatabase('main', 'analytics');
+     */
+    detachDatabase(mainConnectionName: string, alias: string): Promise<void>;
+    /**
+     * Close all connections
+     * @example
+     * await manager.closeAll();
+     */
+    closeAll(): Promise<void>;
+    /**
+     * Execute a raw query on a specific connection
+     * @param connectionName - The name of the connection to use
+     * @param sql - The SQL query to execute
+     * @param options - Optional query options
+     * @returns Query results
+     * @example
+     * const results = await manager.query('main', 'SELECT * FROM users');
+     */
+    query(connectionName: string, sql: string, options?: {
+        raw?: boolean;
+        replacements?: Record<string, any>;
+        bind?: Record<string, any>;
+    }): Promise<any>;
+}
+/**
+ * Create a new ConnectionManager instance
+ * @example
+ * const manager = createConnectionManager();
+ */
+export declare function createConnectionManager(): ConnectionManager;