@bantis/local-cipher 1.0.1 → 2.0.0

package/dist/index.d.ts

@@ -1,21 +1,178 @@
 import { Observable } from 'rxjs';
 
+/**
+ * Configuration types for @bantis/local-cipher
+ */
+/**
+ * Encryption configuration options
+ */
+interface EncryptionConfig {
+    /** Number of PBKDF2 iterations (default: 100000) */
+    iterations?: number;
+    /** Salt length in bytes (default: 16) */
+    saltLength?: number;
+    /** IV length in bytes (default: 12) */
+    ivLength?: number;
+    /** Custom app identifier for fingerprinting (default: 'bantis-local-cipher-v2') */
+    appIdentifier?: string;
+    /** AES key length in bits (default: 256) */
+    keyLength?: 128 | 192 | 256;
+}
+/**
+ * Storage configuration options
+ */
+interface StorageConfig {
+    /** Enable data compression (default: true for values > 1KB) */
+    compression?: boolean;
+    /** Compression threshold in bytes (default: 1024) */
+    compressionThreshold?: number;
+    /** Enable automatic cleanup of expired items (default: true) */
+    autoCleanup?: boolean;
+    /** Auto cleanup interval in ms (default: 60000 - 1 minute) */
+    cleanupInterval?: number;
+}
+/**
+ * Debug configuration options
+ */
+interface DebugConfig {
+    /** Enable debug mode (default: false) */
+    enabled?: boolean;
+    /** Log level (default: 'info') */
+    logLevel?: LogLevel;
+    /** Custom log prefix (default: 'SecureStorage') */
+    prefix?: string;
+}
+/**
+ * Log levels
+ */
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
+/**
+ * Complete configuration for SecureStorage
+ */
+interface SecureStorageConfig {
+    /** Encryption configuration */
+    encryption?: EncryptionConfig;
+    /** Storage configuration */
+    storage?: StorageConfig;
+    /** Debug configuration */
+    debug?: DebugConfig;
+}
+/**
+ * Stored value with metadata
+ */
+interface StoredValue {
+    /** Encrypted value */
+    value: string;
+    /** Expiration timestamp (ms since epoch) */
+    expiresAt?: number;
+    /** Creation timestamp (ms since epoch) */
+    createdAt: number;
+    /** Last modified timestamp (ms since epoch) */
+    modifiedAt: number;
+    /** Data version for migration */
+    version: number;
+    /** Whether value is compressed */
+    compressed?: boolean;
+    /** SHA-256 checksum for integrity */
+    checksum?: string;
+}
+/**
+ * Options for setItemWithExpiry
+ */
+interface ExpiryOptions {
+    /** Expiration time in milliseconds from now */
+    expiresIn?: number;
+    /** Absolute expiration date */
+    expiresAt?: Date;
+}
+/**
+ * Encrypted backup structure
+ */
+interface EncryptedBackup {
+    /** Backup version */
+    version: string;
+    /** Backup timestamp */
+    timestamp: number;
+    /** Encrypted data */
+    data: Record<string, string>;
+    /** Backup metadata */
+    metadata: {
+        /** Key version used for encryption */
+        keyVersion: number;
+        /** Encryption algorithm */
+        algorithm: string;
+        /** Number of items */
+        itemCount: number;
+    };
+}
+/**
+ * Integrity information
+ */
+interface IntegrityInfo {
+    /** Whether data is valid */
+    valid: boolean;
+    /** Last modified timestamp */
+    lastModified: number;
+    /** SHA-256 checksum */
+    checksum: string;
+    /** Data version */
+    version: number;
+}
+/**
+ * Storage event types
+ */
+type StorageEventType = 'encrypted' | 'decrypted' | 'deleted' | 'cleared' | 'expired' | 'error' | 'keyRotated' | 'compressed' | 'decompressed';
+/**
+ * Storage event data
+ */
+interface StorageEventData {
+    /** Event type */
+    type: StorageEventType;
+    /** Key involved (if applicable) */
+    key?: string;
+    /** Event timestamp */
+    timestamp: number;
+    /** Additional metadata */
+    metadata?: any;
+    /** Error (if type is 'error') */
+    error?: Error;
+}
+/**
+ * Event listener function
+ */
+type EventListener = (data: StorageEventData) => void;
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: Required<SecureStorageConfig>;
+/**
+ * Current library version
+ */
+declare const LIBRARY_VERSION = "2.0.0";
+/**
+ * Storage data version
+ */
+declare const STORAGE_VERSION = 2;
+
 /**
  * EncryptionHelper - Clase responsable de todas las operaciones criptográficas
  * Implementa AES-256-GCM con derivación de claves PBKDF2 y fingerprinting del navegador
  */
 declare class EncryptionHelper {
     private static readonly ALGORITHM;
-    private static readonly KEY_LENGTH;
-    private static readonly IV_LENGTH;
-    private static readonly SALT_LENGTH;
-    private static readonly ITERATIONS;
     private static readonly HASH_ALGORITHM;
     private static readonly SALT_STORAGE_KEY;
-    private static readonly APP_IDENTIFIER;
+    private static readonly KEY_VERSION_KEY;
+    private readonly config;
     private key;
     private baseKey;
     private baseKeyPromise;
+    private keyVersion;
+    constructor(config?: EncryptionConfig);
+    /**
+     * Get current key version
+     */
+    getKeyVersion(): number;
     /**
      * Genera un fingerprint único del navegador
      * Combina múltiples características del navegador para crear una huella digital
@@ -74,47 +231,136 @@ declare class EncryptionHelper {
 }
 
 /**
- * SecureStorage - API de alto nivel que imita localStorage con cifrado automático
- * Implementa el patrón Singleton
+ * Namespaced storage for organizing data
+ */
+declare class NamespacedStorage {
+    private prefix;
+    private storage;
+    constructor(storage: any, namespace: string);
+    /**
+     * Set item in this namespace
+     */
+    setItem(key: string, value: string): Promise<void>;
+    /**
+     * Set item with expiry in this namespace
+     */
+    setItemWithExpiry(key: string, value: string, options: {
+        expiresIn?: number;
+        expiresAt?: Date;
+    }): Promise<void>;
+    /**
+     * Get item from this namespace
+     */
+    getItem(key: string): Promise<string | null>;
+    /**
+     * Remove item from this namespace
+     */
+    removeItem(key: string): Promise<void>;
+    /**
+     * Check if item exists in this namespace
+     */
+    hasItem(key: string): Promise<boolean>;
+    /**
+     * Clear all items in this namespace
+     */
+    clearNamespace(): Promise<void>;
+    /**
+     * Get all keys in this namespace
+     */
+    keys(): Promise<string[]>;
+}
+
+/**
+ * SecureStorage v2 - API de alto nivel que imita localStorage con cifrado automático
+ * Incluye: configuración personalizable, eventos, compresión, expiración, namespaces, rotación de claves
  */
 declare class SecureStorage {
     private static instance;
     private encryptionHelper;
+    private eventEmitter;
+    private keyRotation;
+    private logger;
+    private config;
+    private cleanupInterval;
     private constructor();
     /**
      * Obtiene la instancia singleton de SecureStorage
      */
-    static getInstance(): SecureStorage;
+    static getInstance(config?: SecureStorageConfig): SecureStorage;
+    /**
+     * Setup automatic cleanup of expired items
+     */
+    private setupAutoCleanup;
     /**
      * Guarda un valor encriptado en localStorage
-     * @param key - Clave para almacenar
-     * @param value - Valor a encriptar y almacenar
      */
     setItem(key: string, value: string): Promise<void>;
+    /**
+     * Guarda un valor con tiempo de expiración
+     */
+    setItemWithExpiry(key: string, value: string, options: ExpiryOptions): Promise<void>;
     /**
      * Recupera y desencripta un valor de localStorage
-     * @param key - Clave a buscar
-     * @returns Valor desencriptado o null si no existe
      */
     getItem(key: string): Promise<string | null>;
     /**
      * Elimina un valor de localStorage
-     * @param key - Clave a eliminar
      */
     removeItem(key: string): Promise<void>;
     /**
      * Verifica si existe un valor para la clave dada
-     * @param key - Clave a verificar
-     * @returns true si existe, false si no
      */
     hasItem(key: string): Promise<boolean>;
     /**
      * Limpia todos los datos encriptados
      */
     clear(): void;
+    /**
+     * Limpia todos los items expirados
+     */
+    cleanExpired(): Promise<number>;
+    /**
+     * Verifica la integridad de un valor almacenado
+     */
+    verifyIntegrity(key: string): Promise<boolean>;
+    /**
+     * Obtiene información de integridad de un valor
+     */
+    getIntegrityInfo(key: string): Promise<IntegrityInfo | null>;
+    /**
+     * Crea un namespace para organizar datos
+     */
+    namespace(name: string): NamespacedStorage;
+    /**
+     * Rota todas las claves de encriptación
+     */
+    rotateKeys(): Promise<void>;
+    /**
+     * Exporta todos los datos encriptados como backup
+     */
+    exportEncryptedData(): Promise<EncryptedBackup>;
+    /**
+     * Importa datos desde un backup
+     */
+    importEncryptedData(backup: any): Promise<void>;
+    /**
+     * Registra un listener de eventos
+     */
+    on(event: StorageEventType, listener: EventListener): void;
+    /**
+     * Registra un listener de un solo uso
+     */
+    once(event: StorageEventType, listener: EventListener): void;
+    /**
+     * Elimina un listener de eventos
+     */
+    off(event: StorageEventType, listener: EventListener): void;
+    /**
+     * Elimina todos los listeners de un evento
+     */
+    removeAllListeners(event?: StorageEventType): void;
     /**
      * Migra datos existentes no encriptados a formato encriptado
-     * @param keys - Array de claves a migrar
      */
     migrateExistingData(keys: string[]): Promise<void>;
     /**
@@ -125,45 +371,171 @@ declare class SecureStorage {
         encryptedKeys: string[];
         unencryptedKeys: string[];
         totalKeys: number;
+        config: Required<SecureStorageConfig>;
     };
+    /**
+     * Calcula el checksum SHA-256 de un valor
+     */
+    private calculateChecksum;
+    /**
+     * Cleanup on destroy
+     */
+    destroy(): void;
 }
 
-declare const secureStorage$1: SecureStorage;
+/**
+ * Simple event emitter for storage events
+ */
+declare class EventEmitter {
+    private listeners;
+    private onceListeners;
+    /**
+     * Register an event listener
+     */
+    on(event: StorageEventType, listener: EventListener): void;
+    /**
+     * Register a one-time event listener
+     */
+    once(event: StorageEventType, listener: EventListener): void;
+    /**
+     * Remove an event listener
+     */
+    off(event: StorageEventType, listener: EventListener): void;
+    /**
+     * Remove all listeners for an event
+     */
+    removeAllListeners(event?: StorageEventType): void;
+    /**
+     * Emit an event
+     */
+    emit(event: StorageEventType, data: Omit<StorageEventData, 'type' | 'timestamp'>): void;
+    /**
+     * Get listener count for an event
+     */
+    listenerCount(event: StorageEventType): number;
+    /**
+     * Get all event types with listeners
+     */
+    eventNames(): StorageEventType[];
+}
+
+/**
+ * Logger utility for debug mode
+ */
+declare class Logger {
+    private enabled;
+    private logLevel;
+    private prefix;
+    private static readonly LOG_LEVELS;
+    constructor(config?: DebugConfig);
+    private shouldLog;
+    private formatMessage;
+    error(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    debug(message: string, ...args: any[]): void;
+    verbose(message: string, ...args: any[]): void;
+    time(label: string): void;
+    timeEnd(label: string): void;
+    group(label: string): void;
+    groupEnd(): void;
+}
+
+/**
+ * Key rotation utilities
+ */
+declare class KeyRotation {
+    private encryptionHelper;
+    private logger;
+    constructor(encryptionHelper: EncryptionHelper, logger?: Logger);
+    /**
+     * Rotate all encryption keys
+     * Re-encrypts all data with a new salt
+     */
+    rotateKeys(): Promise<void>;
+    /**
+     * Export all encrypted data as backup
+     */
+    exportEncryptedData(): Promise<EncryptedBackup>;
+    /**
+     * Import encrypted data from backup
+     */
+    importEncryptedData(backup: EncryptedBackup): Promise<void>;
+}
+
+/**
+ * Compression utilities using CompressionStream API
+ */
+/**
+ * Check if compression is supported
+ */
+declare function isCompressionSupported(): boolean;
+/**
+ * Compress a string using gzip
+ */
+declare function compress(data: string): Promise<Uint8Array>;
+/**
+ * Decompress gzip data to string
+ */
+declare function decompress(data: Uint8Array): Promise<string>;
+/**
+ * Check if data should be compressed based on size
+ */
+declare function shouldCompress(data: string, threshold?: number): boolean;
+
+/**
+ * Función de debug para verificar el estado del sistema de encriptación
+ * Muestra información detallada en la consola
+ */
+declare function debugEncryptionState(): Promise<void>;
+/**
+ * Fuerza la migración de claves comunes a formato encriptado
+ * Útil para desarrollo y testing
+ */
+declare function forceMigration(customKeys?: string[]): Promise<void>;
+
 /**
  * Hook de React para usar SecureStorage de forma reactiva
  * Similar a useState pero con persistencia encriptada
  *
  * @param key - Clave para almacenar en localStorage
  * @param initialValue - Valor inicial si no existe en storage
+ * @param storage - Instancia personalizada de SecureStorage (opcional)
  * @returns [value, setValue, loading, error]
  *
  * @example
  * const [token, setToken, loading] = useSecureStorage('accessToken', '');
  */
-declare function useSecureStorage<T = string>(key: string, initialValue: T): [T, (value: T) => Promise<void>, boolean, Error | null];
+declare function useSecureStorage<T = string>(key: string, initialValue: T, storage?: SecureStorage): [T, (value: T) => Promise<void>, boolean, Error | null];
 /**
  * Hook para verificar si una clave existe en SecureStorage
  *
  * @param key - Clave a verificar
+ * @param storage - Instancia personalizada de SecureStorage (opcional)
  * @returns [exists, loading, error]
  *
  * @example
  * const [hasToken, loading] = useSecureStorageItem('accessToken');
  */
-declare function useSecureStorageItem(key: string): [boolean, boolean, Error | null];
+declare function useSecureStorageItem(key: string, storage?: SecureStorage): [boolean, boolean, Error | null];
 /**
  * Hook para obtener información de debug del almacenamiento
  *
+ * @param storage - Instancia personalizada de SecureStorage (opcional)
  * @returns Información de debug
  *
  * @example
  * const debugInfo = useSecureStorageDebug();
  * console.log(`Claves encriptadas: ${debugInfo.encryptedKeys.length}`);
  */
-declare function useSecureStorageDebug(): any;
+declare function useSecureStorageDebug(storage?: SecureStorage): any;
+/**
+ * Exportar la instancia de SecureStorage para uso directo
+ */
+declare const secureStorage$1: SecureStorage;
 
 /**
- * Servicio de Angular para SecureStorage
+ * Servicio de Angular para SecureStorage v2
  * Proporciona una API reactiva usando RxJS Observables
  *
  * @example
@@ -174,11 +546,19 @@ declare function useSecureStorageDebug(): any;
  *
  * // Leer
  * this.secureStorage.getItem('token').subscribe(token => console.log(token));
+ *
+ * // Escuchar eventos
+ * this.secureStorage.events$.subscribe(event => console.log(event));
  */
 declare class SecureStorageService {
     private storage;
     private debugInfo$;
-    constructor();
+    private eventsSubject$;
+    /**
+     * Observable de eventos de storage
+     */
+    events$: any;
+    constructor(config?: SecureStorageConfig);
     /**
      * Guarda un valor encriptado
      * @param key - Clave
@@ -186,6 +566,14 @@ declare class SecureStorageService {
      * @returns Observable que completa cuando se guarda
      */
     setItem(key: string, value: string): Observable<void>;
+    /**
+     * Guarda un valor con expiración
+     * @param key - Clave
+     * @param value - Valor a guardar
+     * @param options - Opciones de expiración
+     * @returns Observable que completa cuando se guarda
+     */
+    setItemWithExpiry(key: string, value: string, options: ExpiryOptions): Observable<void>;
     /**
      * Recupera un valor desencriptado
      * @param key - Clave
@@ -208,6 +596,45 @@ declare class SecureStorageService {
      * Limpia todos los datos encriptados
      */
     clear(): void;
+    /**
+     * Limpia todos los items expirados
+     * @returns Observable con el número de items eliminados
+     */
+    cleanExpired(): Observable<number>;
+    /**
+     * Verifica la integridad de un valor
+     * @param key - Clave a verificar
+     * @returns Observable con true si es válido
+     */
+    verifyIntegrity(key: string): Observable<boolean>;
+    /**
+     * Obtiene información de integridad de un valor
+     * @param key - Clave
+     * @returns Observable con información de integridad
+     */
+    getIntegrityInfo(key: string): Observable<any>;
+    /**
+     * Crea un namespace para organizar datos
+     * @param name - Nombre del namespace
+     * @returns Instancia de NamespacedStorage
+     */
+    namespace(name: string): NamespacedStorage;
+    /**
+     * Rota todas las claves de encriptación
+     * @returns Observable que completa cuando termina la rotación
+     */
+    rotateKeys(): Observable<void>;
+    /**
+     * Exporta todos los datos como backup
+     * @returns Observable con el backup
+     */
+    exportEncryptedData(): Observable<EncryptedBackup>;
+    /**
+     * Importa datos desde un backup
+     * @param backup - Backup a importar
+     * @returns Observable que completa cuando termina la importación
+     */
+    importEncryptedData(backup: EncryptedBackup): Observable<void>;
     /**
      * Migra datos existentes a formato encriptado
      * @param keys - Array de claves a migrar
@@ -218,12 +645,7 @@ declare class SecureStorageService {
      * Obtiene información de debug como Observable
      * @returns Observable con información de debug que se actualiza automáticamente
      */
-    getDebugInfo$(): Observable<{
-        cryptoSupported: boolean;
-        encryptedKeys: string[];
-        unencryptedKeys: string[];
-        totalKeys: number;
-    }>;
+    getDebugInfo$(): Observable<any>;
     /**
      * Obtiene información de debug de forma síncrona
      */
@@ -234,27 +656,41 @@ declare class SecureStorageService {
      * @param value - Objeto a guardar
      */
     setObject<T>(key: string, value: T): Observable<void>;
+    /**
+     * Helper para guardar objetos JSON con expiración
+     * @param key - Clave
+     * @param value - Objeto a guardar
+     * @param options - Opciones de expiración
+     */
+    setObjectWithExpiry<T>(key: string, value: T, options: ExpiryOptions): Observable<void>;
     /**
      * Helper para recuperar objetos JSON
      * @param key - Clave
      * @returns Observable con el objeto parseado o null
      */
     getObject<T>(key: string): Observable<T | null>;
+    /**
+     * Registra un listener para un tipo de evento específico
+     * @param event - Tipo de evento
+     * @param handler - Función manejadora
+     */
+    on(event: any, handler: (data: StorageEventData) => void): void;
+    /**
+     * Elimina un listener de evento
+     * @param event - Tipo de evento
+     * @param handler - Función manejadora
+     */
+    off(event: any, handler: (data: StorageEventData) => void): void;
+    /**
+     * Observable filtrado por tipo de evento
+     * @param eventType - Tipo de evento a filtrar
+     * @returns Observable con eventos del tipo especificado
+     */
+    onEvent$(eventType: string): Observable<StorageEventData>;
 }
 
 /**
- * Función de debug para verificar el estado del sistema de encriptación
- * Muestra información detallada en la consola
- */
-declare function debugEncryptionState(): Promise<void>;
-/**
- * Fuerza la migración de claves comunes a formato encriptado
- * Útil para desarrollo y testing
- */
-declare function forceMigration(customKeys?: string[]): Promise<void>;
-
-/**
- * @mtt/local-cipher
+ * @bantis/local-cipher v2.0.0
  * Librería de cifrado local AES-256-GCM para Angular, React y JavaScript
  *
  * @author MTT
@@ -262,6 +698,7 @@ declare function forceMigration(customKeys?: string[]): Promise<void>;
  */
 
 declare const secureStorage: SecureStorage;
-declare const VERSION = "1.0.0";
+declare const VERSION = "2.0.0";
 
-export { EncryptionHelper, SecureStorage, SecureStorageService, VERSION, debugEncryptionState, forceMigration, secureStorage$1 as reactSecureStorage, secureStorage, useSecureStorage, useSecureStorageDebug, useSecureStorageItem };
+export { DEFAULT_CONFIG, EncryptionHelper, EventEmitter, KeyRotation, LIBRARY_VERSION, Logger, NamespacedStorage, STORAGE_VERSION, SecureStorage, SecureStorageService, VERSION, compress, debugEncryptionState, decompress, forceMigration, isCompressionSupported, secureStorage$1 as reactSecureStorage, secureStorage, shouldCompress, useSecureStorage, useSecureStorageDebug, useSecureStorageItem };
+export type { DebugConfig, EncryptedBackup, EncryptionConfig, EventListener, ExpiryOptions, IntegrityInfo, LogLevel, SecureStorageConfig, StorageConfig, StorageEventData, StorageEventType, StoredValue };