@bantis/local-cipher 2.0.1 → 2.2.0

package/dist/index.d.ts

@@ -1,704 +1,20 @@
-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 HASH_ALGORITHM;
-    private static readonly SALT_STORAGE_KEY;
-    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
-     */
-    private generateBaseKey;
-    /**
-     * Hashea un string usando SHA-256
-     * @param str - String a hashear
-     * @returns Hash hexadecimal
-     */
-    private hashString;
-    /**
-     * Deriva una clave criptográfica usando PBKDF2
-     * @param password - Password base (fingerprint)
-     * @param salt - Salt aleatorio
-     * @returns CryptoKey para AES-GCM
-     */
-    private deriveKey;
-    /**
-     * Inicializa el sistema de encriptación generando un nuevo salt
-     */
-    initialize(): Promise<void>;
-    /**
-     * Inicializa desde un salt almacenado previamente
-     */
-    initializeFromStored(): Promise<void>;
-    /**
-     * Encripta un texto plano usando AES-256-GCM
-     * @param plaintext - Texto a encriptar
-     * @returns Texto encriptado en Base64 (IV + datos encriptados)
-     */
-    encrypt(plaintext: string): Promise<string>;
-    /**
-     * Desencripta un texto encriptado
-     * @param ciphertext - Texto encriptado en Base64
-     * @returns Texto plano
-     */
-    decrypt(ciphertext: string): Promise<string>;
-    /**
-     * Encripta el nombre de una clave para ofuscar nombres en localStorage
-     * @param keyName - Nombre original de la clave
-     * @returns Nombre encriptado con prefijo __enc_
-     */
-    encryptKey(keyName: string): Promise<string>;
-    /**
-     * Limpia todos los datos encriptados del localStorage
-     */
-    clearEncryptedData(): void;
-    /**
-     * Verifica si el navegador soporta Web Crypto API
-     */
-    static isSupported(): boolean;
-    private arrayBufferToBase64;
-    private base64ToArrayBuffer;
-    private arrayBufferToHex;
-}
-
-/**
- * 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(config?: SecureStorageConfig): SecureStorage;
-    /**
-     * Setup automatic cleanup of expired items
-     */
-    private setupAutoCleanup;
-    /**
-     * Guarda un valor encriptado en localStorage
-     */
-    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
-     */
-    getItem(key: string): Promise<string | null>;
-    /**
-     * Elimina un valor de localStorage
-     */
-    removeItem(key: string): Promise<void>;
-    /**
-     * Verifica si existe un valor para la clave dada
-     */
-    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
-     */
-    migrateExistingData(keys: string[]): Promise<void>;
-    /**
-     * Obtiene información de debug sobre el estado del almacenamiento
-     */
-    getDebugInfo(): {
-        cryptoSupported: boolean;
-        encryptedKeys: string[];
-        unencryptedKeys: string[];
-        totalKeys: number;
-        config: Required<SecureStorageConfig>;
-    };
-    /**
-     * Calcula el checksum SHA-256 de un valor
-     */
-    private calculateChecksum;
-    /**
-     * Cleanup on destroy
-     */
-    destroy(): void;
-}
-
-/**
- * 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, 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, 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(storage?: SecureStorage): any;
-/**
- * Exportar la instancia de SecureStorage para uso directo
- */
-declare const secureStorage$1: SecureStorage;
-
-/**
- * Servicio de Angular para SecureStorage v2
- * Proporciona una API reactiva usando RxJS Observables
- *
- * @example
- * constructor(private secureStorage: SecureStorageService) {}
- *
- * // Guardar
- * this.secureStorage.setItem('token', 'abc123').subscribe();
- *
- * // 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$;
-    private eventsSubject$;
-    /**
-     * Observable de eventos de storage
-     */
-    events$: any;
-    constructor(config?: SecureStorageConfig);
-    /**
-     * Guarda un valor encriptado
-     * @param key - Clave
-     * @param value - Valor a guardar
-     * @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
-     * @returns Observable con el valor o null
-     */
-    getItem(key: string): Observable<string | null>;
-    /**
-     * Elimina un valor
-     * @param key - Clave a eliminar
-     * @returns Observable que completa cuando se elimina
-     */
-    removeItem(key: string): Observable<void>;
-    /**
-     * Verifica si existe una clave
-     * @param key - Clave a verificar
-     * @returns Observable con true/false
-     */
-    hasItem(key: string): Observable<boolean>;
-    /**
-     * 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
-     * @returns Observable que completa cuando termina la migración
-     */
-    migrateExistingData(keys: string[]): Observable<void>;
-    /**
-     * Obtiene información de debug como Observable
-     * @returns Observable con información de debug que se actualiza automáticamente
-     */
-    getDebugInfo$(): Observable<any>;
-    /**
-     * Obtiene información de debug de forma síncrona
-     */
-    private getDebugInfo;
-    /**
-     * Helper para guardar objetos JSON
-     * @param key - Clave
-     * @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>;
-}
-
-/**
- * @bantis/local-cipher v2.0.0
- * Librería de cifrado local AES-256-GCM para Angular, React y JavaScript
+ * @bantis/local-cipher - Core Module
+ * Framework-agnostic client-side encryption for browser storage
  *
- * @author MTT
+ * @version 2.1.0
  * @license MIT
  */
-
-declare const secureStorage: SecureStorage;
-declare const VERSION = "2.0.0";
-
-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 };
+export { EncryptionHelper } from './core/EncryptionHelper';
+export { SecureStorage } from './core/SecureStorage';
+export { EventEmitter } from './core/EventEmitter';
+export { KeyRotation } from './core/KeyRotation';
+export { NamespacedStorage } from './core/NamespacedStorage';
+export type { EncryptionConfig, StorageConfig, DebugConfig, SecureStorageConfig, StoredValue, ExpiryOptions, EncryptedBackup, IntegrityInfo, StorageEventType, StorageEventData, EventListener, LogLevel, } from './types';
+export { DEFAULT_CONFIG, LIBRARY_VERSION, STORAGE_VERSION } from './types';
+export { Logger } from './utils/logger';
+export { compress, decompress, shouldCompress, isCompressionSupported } from './utils/compression';
+export { debugEncryptionState, forceMigration } from './utils/debug';
+import { SecureStorage } from './core/SecureStorage';
+export declare const secureStorage: SecureStorage;
+export declare const VERSION = "2.1.0";