@bantis/local-cipher 1.0.1 → 2.0.0

package/README.md

@@ -1,27 +1,26 @@
-# @bantis/local-cipher
+# @bantis/local-cipher v2.0.0
 
 [![npm version](https://img.shields.io/npm/v/@bantis/local-cipher.svg)](https://www.npmjs.com/package/@bantis/local-cipher)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub](https://img.shields.io/badge/GitHub-master--tech--team-blue)](https://github.com/master-tech-team/-bantis-local-cipher)
 
-Librería de cifrado local AES-256-GCM para proteger datos sensibles en localStorage. Compatible con **Angular**, **React** y **JavaScript vanilla**.
+Librería enterprise de cifrado local AES-256-GCM con **configuración personalizable**, **eventos**, **compresión**, **expiración**, **namespaces** y **rotación de claves**. Compatible con **Angular**, **React** y **JavaScript vanilla**.
 
-## 🔐 Características
+## ✨ Novedades v2.0.0
 
-- ✅ **Cifrado AES-256-GCM** - Estándar de cifrado avanzado con autenticación
-- ✅ **Derivación de claves PBKDF2** - 100,000 iteraciones con SHA-256
-- ✅ **Browser Fingerprinting** - Claves únicas por navegador
-- ✅ **Ofuscación de nombres** - Los nombres de las claves también se encriptan
-- ✅ **TypeScript** - Tipado completo
-- ✅ **Framework Agnostic** - Funciona con cualquier proyecto JavaScript
-- ✅ **Integraciones específicas** - Hooks de React y servicio de Angular
-- ✅ **Migración automática** - Convierte datos existentes a formato encriptado
-- ✅ **Fallback transparente** - Funciona en navegadores sin Web Crypto API
+- 🎛️ **Configuración Personalizable** - Ajusta iteraciones, longitud de clave, salt e IV
+- 🎯 **Sistema de Eventos** - Escucha eventos de cifrado, expiración, errores, etc.
+- 🗜️ **Compresión Automática** - Gzip para valores > 1KB (configurable)
+- ⏰ **Expiración/TTL** - Establece tiempo de vida con auto-limpieza
+- 🔐 **Validación de Integridad** - Checksums SHA-256 automáticos
+- 📦 **Namespaces** - Organiza datos en espacios aislados
+- 🔄 **Rotación de Claves** - Re-encripta datos con nuevas claves
+- 📊 **Modo Debug** - Logging configurable con niveles
 
 ## 📦 Instalación
 
 ```bash
-npm install @mtt/local-cipher
+npm install @bantis/local-cipher
 ```
 
 ## 🚀 Uso Rápido
@@ -29,28 +28,71 @@ npm install @mtt/local-cipher
 ### JavaScript Vanilla
 
 ```javascript
-import { secureStorage } from '@mtt/local-cipher';
+import { SecureStorage } from '@bantis/local-cipher';
+
+const storage = SecureStorage.getInstance();
 
 // Guardar datos encriptados
-await secureStorage.setItem('accessToken', 'mi-token-secreto');
+await storage.setItem('accessToken', 'mi-token-secreto');
 
 // Leer datos desencriptados
-const token = await secureStorage.getItem('accessToken');
+const token = await storage.getItem('accessToken');
+
+// Con expiración (1 hora)
+await storage.setItemWithExpiry('session', sessionData, { expiresIn: 3600000 });
 
 // Eliminar datos
-await secureStorage.removeItem('accessToken');
+await storage.removeItem('accessToken');
+```
+
+### Con Configuración Personalizada
 
-// Limpiar todo
-secureStorage.clear();
+```javascript
+const storage = SecureStorage.getInstance({
+  encryption: {
+    iterations: 150000,      // PBKDF2 iterations (default: 100000)
+    keyLength: 256,          // 128, 192, or 256 bits
+    saltLength: 16,          // Salt size in bytes
+    ivLength: 12,            // IV size in bytes
+    appIdentifier: 'my-app'  // Custom app identifier
+  },
+  storage: {
+    compression: true,              // Enable compression
+    compressionThreshold: 1024,     // Compress if > 1KB
+    autoCleanup: true,              // Auto-clean expired items
+    cleanupInterval: 60000          // Cleanup every 60s
+  },
+  debug: {
+    enabled: true,           // Enable debug logging
+    logLevel: 'verbose',     // silent, error, warn, info, debug, verbose
+    prefix: 'MyApp'          // Log prefix
+  }
+});
 ```
 
 ### React
 
 ```jsx
-import { useSecureStorage } from '@mtt/local-cipher';
+import { useSecureStorage, useSecureStorageWithExpiry, useSecureStorageEvents } from '@bantis/local-cipher';
 
 function App() {
+  // Hook básico
   const [token, setToken, loading] = useSecureStorage('accessToken', '');
+  
+  // Hook con expiración
+  const [session, setSession] = useSecureStorageWithExpiry(
+    'session', 
+    null, 
+    { expiresIn: 3600000 }
+  );
+  
+  // Escuchar eventos
+  useSecureStorageEvents('expired', (data) => {
+    console.log('Item expired:', data.key);
+  });
+  
+  // Usar namespace
+  const userStorage = useNamespace('user');
 
   if (loading) return <div>Cargando...</div>;
 
@@ -68,169 +110,261 @@ function App() {
 ### Angular
 
 ```typescript
-import { SecureStorageService } from '@mtt/local-cipher';
+import { SecureStorageService } from '@bantis/local-cipher';
 
 @Component({
   selector: 'app-root',
-  template: `<div>{{ token$ | async }}</div>`
+  template: `
+    <div>{{ token$ | async }}</div>
+    <button (click)="saveToken()">Guardar</button>
+  `
 })
-export class AppComponent {
-  token$ = this.secureStorage.getItem('accessToken');
-
-  constructor(private secureStorage: SecureStorageService) {}
+export class AppComponent implements OnInit {
+  token$ = this.storage.getItem('accessToken');
+
+  constructor(private storage: SecureStorageService) {}
+  
+  ngOnInit() {
+    // Escuchar eventos
+    this.storage.events$.subscribe(event => {
+      console.log('Storage event:', event);
+    });
+    
+    // Eventos específicos
+    this.storage.onEvent$('expired').subscribe(event => {
+      console.log('Item expired:', event.key);
+    });
+  }
 
-  saveToken(token: string) {
-    this.secureStorage.setItem('accessToken', token).subscribe();
+  saveToken() {
+    this.storage.setItemWithExpiry('token', 'value', { expiresIn: 3600000 })
+      .subscribe();
+  }
+  
+  saveObject() {
+    this.storage.setObjectWithExpiry('user', { id: 1 }, { expiresIn: 7200000 })
+      .subscribe();
   }
 }
 ```
 
-## 📚 Documentación Completa
+## 📚 API Completa
 
-### API Principal
+### SecureStorage
 
-#### `SecureStorage`
+#### Métodos Básicos
 
-**`setItem(key: string, value: string): Promise<void>`**
-Guarda un valor encriptado en localStorage.
+```typescript
+setItem(key: string, value: string): Promise<void>
+getItem(key: string): Promise<string | null>
+removeItem(key: string): Promise<void>
+hasItem(key: string): Promise<boolean>
+clear(): void
+```
+
+#### Expiración
 
-**`getItem(key: string): Promise<string | null>`**
-Recupera y desencripta un valor de localStorage.
+```typescript
+setItemWithExpiry(key: string, value: string, options: ExpiryOptions): Promise<void>
+cleanExpired(): Promise<number>
 
-**`removeItem(key: string): Promise<void>`**
-Elimina un valor de localStorage.
+// Opciones
+interface ExpiryOptions {
+  expiresIn?: number;    // Milisegundos desde ahora
+  expiresAt?: Date;      // Fecha absoluta
+}
+```
 
-**`hasItem(key: string): Promise<boolean>`**
-Verifica si existe una clave.
+#### Eventos
 
-**`clear(): void`**
-Limpia todos los datos encriptados.
+```typescript
+on(event: StorageEventType, listener: EventListener): void
+once(event: StorageEventType, listener: EventListener): void
+off(event: StorageEventType, listener: EventListener): void
+removeAllListeners(event?: StorageEventType): void
+
+// Tipos de eventos
+type StorageEventType = 
+  | 'encrypted' | 'decrypted' | 'deleted' | 'cleared' 
+  | 'expired' | 'error' | 'keyRotated' | 'compressed' | 'decompressed';
+```
 
-**`migrateExistingData(keys: string[]): Promise<void>`**
-Migra datos existentes no encriptados a formato encriptado.
+#### Namespaces
 
-### React Hooks
+```typescript
+namespace(name: string): NamespacedStorage
 
-#### `useSecureStorage<T>(key: string, initialValue: T)`
-Hook principal para usar SecureStorage de forma reactiva.
+// Ejemplo
+const userStorage = storage.namespace('user');
+const sessionStorage = storage.namespace('session');
 
-```jsx
-const [user, setUser, loading, error] = useSecureStorage('user', null);
+await userStorage.setItem('profile', data);
+await userStorage.clearNamespace(); // Solo limpia este namespace
 ```
 
-**Retorna:** `[value, setValue, loading, error]`
-
-#### `useSecureStorageItem(key: string)`
-Verifica si existe una clave.
+#### Integridad
 
-```jsx
-const [hasToken, loading, error] = useSecureStorageItem('accessToken');
+```typescript
+verifyIntegrity(key: string): Promise<boolean>
+getIntegrityInfo(key: string): Promise<IntegrityInfo>
+
+interface IntegrityInfo {
+  valid: boolean;
+  lastModified: number;
+  checksum: string;
+  version: number;
+}
 ```
 
-**Retorna:** `[exists, loading, error]`
-
-#### `useSecureStorageDebug()`
-Obtiene información de debug del sistema.
+#### Rotación de Claves
 
-```jsx
-const debugInfo = useSecureStorageDebug();
-console.log(`Claves encriptadas: ${debugInfo.encryptedKeys.length}`);
+```typescript
+rotateKeys(): Promise<void>
+exportEncryptedData(): Promise<EncryptedBackup>
+importEncryptedData(backup: EncryptedBackup): Promise<void>
+
+// Ejemplo
+const backup = await storage.exportEncryptedData();
+await storage.rotateKeys();
+// Si algo sale mal:
+await storage.importEncryptedData(backup);
 ```
 
-### Angular Service
-
-#### `SecureStorageService`
+#### Debug
 
 ```typescript
-// Inyectar el servicio
-constructor(private secureStorage: SecureStorageService) {}
+getDebugInfo(): {
+  cryptoSupported: boolean;
+  encryptedKeys: string[];
+  unencryptedKeys: string[];
+  totalKeys: number;
+  config: SecureStorageConfig;
+}
+```
 
-// Guardar
-this.secureStorage.setItem('key', 'value').subscribe();
+## 🎯 Casos de Uso
 
-// Leer
-this.secureStorage.getItem('key').subscribe(value => console.log(value));
+### 1. Session Management con Expiración
 
-// Guardar objetos JSON
-this.secureStorage.setObject('user', { id: 1, name: 'Juan' }).subscribe();
+```javascript
+// Guardar sesión que expira en 30 minutos
+await storage.setItemWithExpiry('session', sessionData, { 
+  expiresIn: 30 * 60 * 1000 
+});
+
+// Auto-limpieza cada minuto
+const storage = SecureStorage.getInstance({
+  storage: { autoCleanup: true, cleanupInterval: 60000 }
+});
+```
 
-// Leer objetos JSON
-this.secureStorage.getObject<User>('user').subscribe(user => console.log(user));
+### 2. Organización con Namespaces
 
-// Obtener debug info como Observable
-this.secureStorage.getDebugInfo$().subscribe(info => console.log(info));
-```
+```javascript
+const userStorage = storage.namespace('user');
+const appStorage = storage.namespace('app');
+const tempStorage = storage.namespace('temp');
+
+await userStorage.setItem('profile', userData);
+await appStorage.setItem('settings', appSettings);
+await tempStorage.setItem('cache', cacheData);
 
-## 🔄 Migración de Datos Existentes
+// Limpiar solo datos temporales
+await tempStorage.clearNamespace();
+```
 
-Si ya tienes datos en localStorage sin encriptar, puedes migrarlos fácilmente:
+### 3. Monitoreo con Eventos
 
 ```javascript
-import { secureStorage } from '@mtt/local-cipher';
-
-// Migrar claves específicas
-await secureStorage.migrateExistingData([
-  'accessToken',
-  'refreshToken',
-  'user',
-  'sessionId'
-]);
+storage.on('encrypted', ({ key, metadata }) => {
+  console.log(`✅ Encrypted: ${key}`, metadata);
+});
+
+storage.on('expired', ({ key }) => {
+  console.warn(`⏰ Expired: ${key}`);
+  // Refrescar datos o redirigir a login
+});
+
+storage.on('error', ({ key, error }) => {
+  console.error(`❌ Error on ${key}:`, error);
+  // Enviar a sistema de logging
+});
 ```
 
-**Recomendación:** Ejecuta esto al iniciar tu aplicación para migrar automáticamente.
+### 4. Rotación de Claves Programada
 
-## 🛡️ Seguridad
+```javascript
+// Rotar claves cada 30 días
+setInterval(async () => {
+  console.log('Rotating encryption keys...');
+  const backup = await storage.exportEncryptedData();
+  
+  try {
+    await storage.rotateKeys();
+    console.log('Keys rotated successfully');
+  } catch (error) {
+    console.error('Rotation failed, restoring backup');
+    await storage.importEncryptedData(backup);
+  }
+}, 30 * 24 * 60 * 60 * 1000);
+```
 
-### ¿Qué protege?
+## 🔄 Migración desde v1
 
-✅ **XSS (Cross-Site Scripting)** - Los datos están encriptados incluso si un script malicioso accede a localStorage  
-✅ **Lectura de archivos locales** - Malware que lee archivos del navegador no puede descifrar los datos  
-✅ **Ofuscación** - Los nombres de las claves también están encriptados  
+### Cambios Principales
 
-### ¿Qué NO protege?
+**v1:**
+```javascript
+const storage = SecureStorage.getInstance();
+```
 
-❌ **Ataques del lado del servidor** - La encriptación es solo del lado del cliente  
-❌ **Man-in-the-Middle** - Usa HTTPS para proteger datos en tránsito  
-❌ **Acceso físico durante sesión activa** - Si el navegador está abierto, la clave está en memoria  
+**v2 (compatible):**
+```javascript
+// Funciona igual que v1
+const storage = SecureStorage.getInstance();
 
-### Cómo Funciona
+// O con configuración
+const storage = SecureStorage.getInstance({
+  encryption: { iterations: 150000 }
+});
+```
 
-1. **Fingerprinting del navegador** - Se genera una huella digital única combinando características del navegador
-2. **Derivación de clave** - Se usa PBKDF2 con 100,000 iteraciones para derivar una clave AES-256
-3. **Cifrado AES-GCM** - Cada valor se encripta con un IV aleatorio único
-4. **Almacenamiento** - Se guarda `IV + datos encriptados` en Base64
+### Migración Automática
 
-**Ejemplo de localStorage:**
+Los datos de v1 se migran automáticamente al leerlos. No requiere acción del usuario.
 
-```
-Antes:
-  accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-  user: '{"id":1,"name":"Juan"}'
+```javascript
+// v1 data format: plain encrypted string
+// v2 data format: JSON with metadata
 
-Después:
-  __enc_a7f5d8e2c1b4: "Qm9keUVuY3J5cHRlZERhdGE..."
-  __enc_9c3e7b1a5f8d: "QW5vdGhlckVuY3J5cHRlZA..."
-  __app_salt: "cmFuZG9tU2FsdEhlcmU="
+// Al hacer getItem(), v1 data se detecta y migra automáticamente
+const value = await storage.getItem('oldKey'); // ✅ Migrado a v2
 ```
 
-## 🧪 Utilidades de Debug
+## 🛡️ Seguridad
 
-```javascript
-import { debugEncryptionState, testEncryption, forceMigration } from '@mtt/local-cipher';
+### Protección
 
-// Ver estado del sistema
-await debugEncryptionState();
+✅ **XSS** - Datos encriptados incluso si script malicioso accede a localStorage  
+✅ **Lectura local** - Malware no puede descifrar sin la clave del navegador  
+✅ **Ofuscación** - Nombres de claves encriptados  
+✅ **Integridad** - Checksums SHA-256 detectan manipulación  
 
-// Probar encriptación
-await testEncryption();
+### Limitaciones
 
-// Forzar migración
-await forceMigration(['accessToken', 'refreshToken']);
-```
+❌ **Servidor** - Encriptación solo cliente  
+❌ **MITM** - Usa HTTPS  
+❌ **Sesión activa** - Clave en memoria durante uso  
 
-## 🌐 Compatibilidad
+### Arquitectura
+
+1. **Fingerprinting** - Huella única del navegador
+2. **PBKDF2** - 100,000+ iteraciones para derivar clave
+3. **AES-256-GCM** - Cifrado con autenticación
+4. **SHA-256** - Checksums de integridad
+5. **Gzip** - Compresión opcional
 
-Requiere navegadores con soporte para **Web Crypto API**:
+## 🌐 Compatibilidad
 
 - ✅ Chrome 37+
 - ✅ Firefox 34+
@@ -238,16 +372,18 @@ Requiere navegadores con soporte para **Web Crypto API**:
 - ✅ Edge 12+
 - ✅ Opera 24+
 
-**Nota:** En navegadores sin soporte, la librería hace fallback automático a localStorage normal.
+**Fallback:** En navegadores sin Web Crypto API, usa localStorage normal.
 
 ## 📄 Licencia
 
 MIT © MTT
 
-## 🤝 Contribuir
+## 🔗 Enlaces
 
-Las contribuciones son bienvenidas. Por favor abre un issue o pull request en GitHub.
+- [GitHub](https://github.com/master-tech-team/-bantis-local-cipher)
+- [npm](https://www.npmjs.com/package/@bantis/local-cipher)
+- [Changelog](./CHANGELOG.md)
 
-## 📞 Soporte
+## 🤝 Contribuir
 
-Si encuentras algún problema o tienes preguntas, abre un issue en GitHub.
+Las contribuciones son bienvenidas. Abre un issue o pull request en GitHub.