@bantis/local-cipher 2.0.0 → 2.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 MTT
+Copyright (c) 2026 MTT (Master Tech Team)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,29 +1,130 @@
-# @bantis/local-cipher v2.0.0
+# @bantis/local-cipher
 
 [![npm version](https://img.shields.io/npm/v/@bantis/local-cipher.svg)](https://www.npmjs.com/package/@bantis/local-cipher)
+[![npm downloads](https://img.shields.io/npm/dm/@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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
 
-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**.
+**Client-side encryption for localStorage using AES-256-GCM**
 
-## ✨ Novedades v2.0.0
+Protect sensitive data in browser storage from XSS attacks, local file access, and casual inspection. Drop-in replacement for localStorage with automatic encryption/decryption.
 
-- 🎛️ **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
+## Problem
 
-## 📦 Instalación
+localStorage stores data in **plain text**. Anyone with access to DevTools, browser files, or malicious scripts can read:
+- Authentication tokens
+- User credentials
+- API keys
+- Personal information
+
+## Solution
+
+Transparent AES-256-GCM encryption with browser fingerprinting. Data is encrypted before storage and decrypted on retrieval. Keys are derived from browser characteristics, making data unreadable outside the original browser context.
+
+## Quick Start
 
 ```bash
 npm install @bantis/local-cipher
 ```
 
-## 🚀 Uso Rápido
+```typescript
+import { SecureStorage } from '@bantis/local-cipher';
+
+const storage = SecureStorage.getInstance();
+
+// Store encrypted
+await storage.setItem('token', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
+
+// Retrieve decrypted
+const token = await storage.getItem('token');
+
+// Works like localStorage
+await storage.removeItem('token');
+storage.clear();
+```
+
+**Before:**
+```
+localStorage: { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
+```
+
+**After:**
+```
+localStorage: { "__enc_a7f5d8e2": "Qm9keUVuY3J5cHRlZERhdGE..." }
+```
+
+## Features
+
+- ✅ **AES-256-GCM** encryption with authentication
+- ✅ **PBKDF2** key derivation (100k+ iterations)
+- ✅ **Browser fingerprinting** for unique keys per device
+- ✅ **Key obfuscation** - even key names are encrypted
+- ✅ **TTL/Expiration** - auto-delete expired data
+- ✅ **Event system** - monitor storage operations
+- ✅ **Compression** - automatic gzip for large values
+- ✅ **Namespaces** - organize data in isolated spaces
+- ✅ **Integrity checks** - SHA-256 checksums
+- ✅ **TypeScript** - full type definitions
+- ✅ **Framework support** - React hooks, Angular service
+
+## Use Cases
+
+### 1. Protect Authentication Tokens
+
+```typescript
+// Store JWT with 1-hour expiration
+await storage.setItemWithExpiry('accessToken', jwt, { 
+  expiresIn: 3600000 
+});
+
+// Auto-cleanup expired tokens
+storage.on('expired', ({ key }) => {
+  console.log(`Token ${key} expired, redirecting to login`);
+  window.location.href = '/login';
+});
+```
+
+### 2. Secure User Preferences
+
+```typescript
+const userStorage = storage.namespace('user');
+await userStorage.setItem('theme', 'dark');
+await userStorage.setItem('language', 'en');
+
+// Isolated from other namespaces
+const appStorage = storage.namespace('app');
+```
+
+### 3. Cache Sensitive API Responses
+
+```typescript
+// Store with compression for large data
+const storage = SecureStorage.getInstance({
+  storage: { compression: true, compressionThreshold: 512 }
+});
+
+await storage.setItem('userData', JSON.stringify(largeObject));
+```
+
+## React Integration
+
+```tsx
+import { useSecureStorage, useSecureStorageEvents } from '@bantis/local-cipher';
+
+function App() {
+  const [token, setToken, loading] = useSecureStorage('token', '');
+  
+  useSecureStorageEvents('expired', () => {
+    // Handle expiration
+  });
+
+  if (loading) return <div>Loading...</div>;
+  
+  return <div>Token: {token}</div>;
+}
+```
+
+## 🚀 Quick Start
 
 ### JavaScript Vanilla
 
@@ -32,75 +133,44 @@ import { SecureStorage } from '@bantis/local-cipher';
 
 const storage = SecureStorage.getInstance();
 
-// Guardar datos encriptados
+// Store encrypted
 await storage.setItem('accessToken', 'mi-token-secreto');
 
-// Leer datos desencriptados
+// Retrieve decrypted
 const token = await storage.getItem('accessToken');
 
-// Con expiración (1 hora)
+// With expiration (1 hour)
 await storage.setItemWithExpiry('session', sessionData, { expiresIn: 3600000 });
 
-// Eliminar datos
+// Remove
 await storage.removeItem('accessToken');
 ```
 
-### Con Configuración Personalizada
+**Before:**
+```
+localStorage: { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
+```
 
-```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
-  }
-});
+**After:**
+```
+localStorage: { "__enc_a7f5d8e2": "Qm9keUVuY3J5cHRlZERhdGE..." }
 ```
 
 ### React
 
 ```jsx
-import { useSecureStorage, useSecureStorageWithExpiry, useSecureStorageEvents } from '@bantis/local-cipher';
+import { useSecureStorage } from '@bantis/local-cipher/react';
 
 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>;
+  if (loading) return <div>Loading...</div>;
 
   return (
     <div>
       <p>Token: {token}</p>
       <button onClick={() => setToken('nuevo-token')}>
-        Actualizar Token
+        Update Token
       </button>
     </div>
   );
@@ -110,49 +180,103 @@ function App() {
 ### Angular
 
 ```typescript
-import { SecureStorageService } from '@bantis/local-cipher';
+import { SecureStorageService } from '@bantis/local-cipher/angular';
 
 @Component({
   selector: 'app-root',
-  template: `
-    <div>{{ token$ | async }}</div>
-    <button (click)="saveToken()">Guardar</button>
-  `
+  template: `<div>{{ token$ | async }}</div>`
 })
-export class AppComponent implements OnInit {
+export class AppComponent {
   token$ = this.storage.getItem('accessToken');
 
   constructor(private storage: SecureStorageService) {}
-  
-  ngOnInit() {
-    // Escuchar eventos
+
+  saveToken(token: string) {
+    this.storage.setItem('accessToken', token).subscribe();
+  }
+}
+```
+## Angular Integration
+
+```typescript
+import { SecureStorageService } from '@bantis/local-cipher';
+
+@Component({...})
+export class AppComponent {
+  token$ = this.storage.getItem('token');
+
+  constructor(private storage: SecureStorageService) {
     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() {
-    this.storage.setItemWithExpiry('token', 'value', { expiresIn: 3600000 })
-      .subscribe();
-  }
-  
-  saveObject() {
-    this.storage.setObjectWithExpiry('user', { id: 1 }, { expiresIn: 7200000 })
-      .subscribe();
+## Configuration
+
+```typescript
+const storage = SecureStorage.getInstance({
+  encryption: {
+    iterations: 150000,      // PBKDF2 iterations
+    keyLength: 256,          // 128, 192, or 256 bits
+    saltLength: 16,          // Salt size in bytes
+    ivLength: 12,            // IV size in bytes
+  },
+  storage: {
+    compression: true,       // Enable gzip compression
+    compressionThreshold: 1024,  // Compress if > 1KB
+    autoCleanup: true,       // Auto-delete expired items
+    cleanupInterval: 60000   // Cleanup every 60s
+  },
+  debug: {
+    enabled: false,          // Enable debug logging
+    logLevel: 'info'         // silent, error, warn, info, debug, verbose
   }
-}
+});
 ```
 
-## 📚 API Completa
+## Security
+
+### What This Protects Against
+
+✅ **XSS attacks** - Encrypted data is useless without the browser-specific key  
+✅ **Local file access** - Malware reading browser files gets encrypted data  
+✅ **Casual inspection** - DevTools shows encrypted values  
+✅ **Data tampering** - Integrity checks detect modifications  
+
+### What This Does NOT Protect Against
+
+❌ **Server-side attacks** - Encryption is client-side only  
+❌ **Man-in-the-Middle** - Use HTTPS for data in transit  
+❌ **Memory dumps** - Keys exist in memory during runtime  
+❌ **Compromised browser** - If the browser is compromised, all bets are off  
+❌ **Physical access during active session** - Data is decrypted when accessed  
+
+### Best Practices
+
+1. **Use HTTPS** - Always transmit data over secure connections
+2. **Short TTLs** - Set expiration on sensitive data
+3. **Clear on logout** - Call `storage.clear()` when user logs out
+4. **Monitor events** - Track suspicious activity via event listeners
+5. **Rotate keys** - Periodically call `storage.rotateKeys()`
+6. **Don't store passwords** - Never store plaintext passwords, even encrypted
+
+## Browser Support
 
-### SecureStorage
+Requires [Web Crypto API](https://caniuse.com/cryptography):
 
-#### Métodos Básicos
+- Chrome 37+
+- Firefox 34+
+- Safari 11+
+- Edge 12+
+- Opera 24+
+
+**Fallback:** Gracefully degrades to unencrypted localStorage in unsupported browsers.
+
+## API Reference
+
+### Core Methods
 
 ```typescript
 setItem(key: string, value: string): Promise<void>
@@ -162,228 +286,124 @@ hasItem(key: string): Promise<boolean>
 clear(): void
 ```
 
-#### Expiración
+### Expiration
 
 ```typescript
-setItemWithExpiry(key: string, value: string, options: ExpiryOptions): Promise<void>
-cleanExpired(): Promise<number>
+setItemWithExpiry(key: string, value: string, options: {
+  expiresIn?: number;    // milliseconds from now
+  expiresAt?: Date;      // absolute date
+}): Promise<void>
 
-// Opciones
-interface ExpiryOptions {
-  expiresIn?: number;    // Milisegundos desde ahora
-  expiresAt?: Date;      // Fecha absoluta
-}
+cleanExpired(): Promise<number>  // Returns count of deleted items
 ```
 
-#### Eventos
+### Events
 
 ```typescript
 on(event: StorageEventType, listener: EventListener): void
-once(event: StorageEventType, listener: EventListener): void
 off(event: StorageEventType, listener: EventListener): void
-removeAllListeners(event?: StorageEventType): void
+once(event: StorageEventType, listener: EventListener): void
 
-// Tipos de eventos
-type StorageEventType = 
-  | 'encrypted' | 'decrypted' | 'deleted' | 'cleared' 
-  | 'expired' | 'error' | 'keyRotated' | 'compressed' | 'decompressed';
+// Event types: 'encrypted', 'decrypted', 'deleted', 'cleared', 
+//              'expired', 'error', 'keyRotated', 'compressed'
 ```
 
-#### Namespaces
+### Namespaces
 
 ```typescript
 namespace(name: string): NamespacedStorage
 
-// Ejemplo
 const userStorage = storage.namespace('user');
-const sessionStorage = storage.namespace('session');
-
 await userStorage.setItem('profile', data);
-await userStorage.clearNamespace(); // Solo limpia este namespace
+await userStorage.clearNamespace();
 ```
 
-#### Integridad
-
-```typescript
-verifyIntegrity(key: string): Promise<boolean>
-getIntegrityInfo(key: string): Promise<IntegrityInfo>
-
-interface IntegrityInfo {
-  valid: boolean;
-  lastModified: number;
-  checksum: string;
-  version: number;
-}
-```
-
-#### Rotación de Claves
+### Key Rotation
 
 ```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);
 ```
 
-#### Debug
+## FAQ
 
-```typescript
-getDebugInfo(): {
-  cryptoSupported: boolean;
-  encryptedKeys: string[];
-  unencryptedKeys: string[];
-  totalKeys: number;
-  config: SecureStorageConfig;
-}
-```
+**Q: Is this secure enough for passwords?**  
+A: No. Never store passwords in localStorage, even encrypted. Use secure, httpOnly cookies or sessionStorage with server-side session management.
 
-## 🎯 Casos de Uso
+**Q: Can data be decrypted on another device?**  
+A: No. Keys are derived from browser fingerprinting. Data encrypted on Chrome/Windows cannot be decrypted on Firefox/Mac.
 
-### 1. Session Management con Expiración
+**Q: What happens if Web Crypto API is unavailable?**  
+A: The library falls back to unencrypted localStorage with a console warning. Check `EncryptionHelper.isSupported()` to detect support.
 
-```javascript
-// Guardar sesión que expira en 30 minutos
-await storage.setItemWithExpiry('session', sessionData, { 
-  expiresIn: 30 * 60 * 1000 
-});
+**Q: Does this protect against XSS?**  
+A: Partially. It makes stolen data harder to use, but XSS can still intercept data when it's decrypted in memory. Use CSP headers and sanitize inputs.
 
-// Auto-limpieza cada minuto
-const storage = SecureStorage.getInstance({
-  storage: { autoCleanup: true, cleanupInterval: 60000 }
-});
-```
+**Q: How is this different from sessionStorage?**  
+A: sessionStorage is cleared on tab close. This provides persistent, encrypted storage across sessions.
 
-### 2. Organización con Namespaces
+**Q: Can I use this in Node.js?**  
+A: No. This library requires browser APIs (Web Crypto, localStorage). For Node.js, use native `crypto` module.
 
-```javascript
-const userStorage = storage.namespace('user');
-const appStorage = storage.namespace('app');
-const tempStorage = storage.namespace('temp');
+**Q: What's the performance impact?**  
+A: Encryption adds ~2-5ms per operation. Compression adds ~5-10ms for large values. Negligible for most use cases.
 
-await userStorage.setItem('profile', userData);
-await appStorage.setItem('settings', appSettings);
-await tempStorage.setItem('cache', cacheData);
+## Migration from v1
 
-// Limpiar solo datos temporales
-await tempStorage.clearNamespace();
+v1 data is automatically migrated to v2 format on first read. No action required.
+
+```typescript
+// v1 and v2 are API-compatible
+const storage = SecureStorage.getInstance();  // Works with both
 ```
 
-### 3. Monitoreo con Eventos
+## Migration from v2.0.x to v2.1.0
 
-```javascript
-storage.on('encrypted', ({ key, metadata }) => {
-  console.log(`✅ Encrypted: ${key}`, metadata);
-});
+> [!WARNING]
+> **Breaking Change:** Framework-specific imports required
 
-storage.on('expired', ({ key }) => {
-  console.warn(`⏰ Expired: ${key}`);
-  // Refrescar datos o redirigir a login
-});
+### For React Users
 
-storage.on('error', ({ key, error }) => {
-  console.error(`❌ Error on ${key}:`, error);
-  // Enviar a sistema de logging
-});
+**Before (v2.0.x):**
+```typescript
+import { useSecureStorage } from '@bantis/local-cipher';
 ```
 
-### 4. Rotación de Claves Programada
-
-```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);
+**After (v2.1.0):**
+```typescript
+import { useSecureStorage } from '@bantis/local-cipher/react';
 ```
 
-## 🔄 Migración desde v1
-
-### Cambios Principales
+### For Angular Users
 
-**v1:**
-```javascript
-const storage = SecureStorage.getInstance();
+**Before (v2.0.x):**
+```typescript
+import { SecureStorageService } from '@bantis/local-cipher';
 ```
 
-**v2 (compatible):**
-```javascript
-// Funciona igual que v1
-const storage = SecureStorage.getInstance();
-
-// O con configuración
-const storage = SecureStorage.getInstance({
-  encryption: { iterations: 150000 }
-});
+**After (v2.1.0):**
+```typescript
+import { SecureStorageService } from '@bantis/local-cipher/angular';
 ```
 
-### Migración Automática
-
-Los datos de v1 se migran automáticamente al leerlos. No requiere acción del usuario.
+### For Core/Vanilla JS Users
 
-```javascript
-// v1 data format: plain encrypted string
-// v2 data format: JSON with metadata
-
-// Al hacer getItem(), v1 data se detecta y migra automáticamente
-const value = await storage.getItem('oldKey'); // ✅ Migrado a v2
+**No changes required:**
+```typescript
+import { SecureStorage } from '@bantis/local-cipher';  // Still works
 ```
 
-## 🛡️ Seguridad
-
-### Protección
-
-✅ **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  
-
-### Limitaciones
-
-❌ **Servidor** - Encriptación solo cliente  
-❌ **MITM** - Usa HTTPS  
-❌ **Sesión activa** - Clave en memoria durante uso  
-
-### 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
-
-## 🌐 Compatibilidad
-
-- ✅ Chrome 37+
-- ✅ Firefox 34+
-- ✅ Safari 11+
-- ✅ Edge 12+
-- ✅ Opera 24+
-
-**Fallback:** En navegadores sin Web Crypto API, usa localStorage normal.
-
-## 📄 Licencia
-
-MIT © MTT
-
-## 🔗 Enlaces
+### Why This Change?
 
-- [GitHub](https://github.com/master-tech-team/-bantis-local-cipher)
-- [npm](https://www.npmjs.com/package/@bantis/local-cipher)
-- [Changelog](./CHANGELOG.md)
+v2.0.x bundled all framework code together, causing dependency conflicts:
+- React projects needed Angular dependencies (`@angular/core`, `rxjs`)
+- Vanilla JS projects loaded unused React/Angular code
+- 40% larger bundle size for non-framework users
 
-## 🤝 Contribuir
+v2.1.0 separates frameworks into independent bundles:
+- ✅ Core: 42KB (no framework dependencies)
+- ✅ React: 49KB (core + hooks)
+- ✅ Angular: 55KB (core + service)
 
-Las contribuciones son bienvenidas. Abre un issue o pull request en GitHub.
+## FAQ