@bantis/local-cipher 1.0.1 → 2.0.1

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,253 +1,314 @@
 # @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 de cifrado local AES-256-GCM para proteger datos sensibles en localStorage. Compatible con **Angular**, **React** y **JavaScript vanilla**.
+**Client-side encryption for localStorage using AES-256-GCM**
 
-## 🔐 Características
+Protect sensitive data in browser storage from XSS attacks, local file access, and casual inspection. Drop-in replacement for localStorage with automatic encryption/decryption.
 
-- ✅ **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
+## 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 @mtt/local-cipher
+npm install @bantis/local-cipher
 ```
 
-## 🚀 Uso Rápido
+```typescript
+import { SecureStorage } from '@bantis/local-cipher';
 
-### JavaScript Vanilla
+const storage = SecureStorage.getInstance();
 
-```javascript
-import { secureStorage } from '@mtt/local-cipher';
+// Store encrypted
+await storage.setItem('token', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
 
-// Guardar datos encriptados
-await secureStorage.setItem('accessToken', 'mi-token-secreto');
+// Retrieve decrypted
+const token = await storage.getItem('token');
 
-// Leer datos desencriptados
-const token = await secureStorage.getItem('accessToken');
+// Works like localStorage
+await storage.removeItem('token');
+storage.clear();
+```
 
-// Eliminar datos
-await secureStorage.removeItem('accessToken');
+**Before:**
+```
+localStorage: { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
+```
 
-// Limpiar todo
-secureStorage.clear();
+**After:**
+```
+localStorage: { "__enc_a7f5d8e2": "Qm9keUVuY3J5cHRlZERhdGE..." }
 ```
 
-### React
+## Features
 
-```jsx
-import { useSecureStorage } from '@mtt/local-cipher';
+- ✅ **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
 
-function App() {
-  const [token, setToken, loading] = useSecureStorage('accessToken', '');
-
-  if (loading) return <div>Cargando...</div>;
-
-  return (
-    <div>
-      <p>Token: {token}</p>
-      <button onClick={() => setToken('nuevo-token')}>
-        Actualizar Token
-      </button>
-    </div>
-  );
-}
-```
+## Use Cases
 
-### Angular
+### 1. Protect Authentication Tokens
 
 ```typescript
-import { SecureStorageService } from '@mtt/local-cipher';
+// 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';
+});
+```
 
-@Component({
-  selector: 'app-root',
-  template: `<div>{{ token$ | async }}</div>`
-})
-export class AppComponent {
-  token$ = this.secureStorage.getItem('accessToken');
+### 2. Secure User Preferences
 
-  constructor(private secureStorage: SecureStorageService) {}
+```typescript
+const userStorage = storage.namespace('user');
+await userStorage.setItem('theme', 'dark');
+await userStorage.setItem('language', 'en');
 
-  saveToken(token: string) {
-    this.secureStorage.setItem('accessToken', token).subscribe();
-  }
-}
+// Isolated from other namespaces
+const appStorage = storage.namespace('app');
 ```
 
-## 📚 Documentación Completa
+### 3. Cache Sensitive API Responses
 
-### API Principal
+```typescript
+// Store with compression for large data
+const storage = SecureStorage.getInstance({
+  storage: { compression: true, compressionThreshold: 512 }
+});
 
-#### `SecureStorage`
+await storage.setItem('userData', JSON.stringify(largeObject));
+```
 
-**`setItem(key: string, value: string): Promise<void>`**
-Guarda un valor encriptado en localStorage.
+## React Integration
 
-**`getItem(key: string): Promise<string | null>`**
-Recupera y desencripta un valor de localStorage.
+```tsx
+import { useSecureStorage, useSecureStorageEvents } from '@bantis/local-cipher';
 
-**`removeItem(key: string): Promise<void>`**
-Elimina un valor de localStorage.
+function App() {
+  const [token, setToken, loading] = useSecureStorage('token', '');
+  
+  useSecureStorageEvents('expired', () => {
+    // Handle expiration
+  });
+
+  if (loading) return <div>Loading...</div>;
+  
+  return <div>Token: {token}</div>;
+}
+```
 
-**`hasItem(key: string): Promise<boolean>`**
-Verifica si existe una clave.
+## Angular Integration
 
-**`clear(): void`**
-Limpia todos los datos encriptados.
+```typescript
+import { SecureStorageService } from '@bantis/local-cipher';
 
-**`migrateExistingData(keys: string[]): Promise<void>`**
-Migra datos existentes no encriptados a formato encriptado.
+@Component({...})
+export class AppComponent {
+  token$ = this.storage.getItem('token');
 
-### React Hooks
+  constructor(private storage: SecureStorageService) {
+    this.storage.events$.subscribe(event => {
+      console.log('Storage event:', event);
+    });
+  }
+}
+```
 
-#### `useSecureStorage<T>(key: string, initialValue: T)`
-Hook principal para usar SecureStorage de forma reactiva.
+## Configuration
 
-```jsx
-const [user, setUser, loading, error] = useSecureStorage('user', null);
+```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
+  }
+});
 ```
 
-**Retorna:** `[value, setValue, loading, error]`
+## Security
 
-#### `useSecureStorageItem(key: string)`
-Verifica si existe una clave.
+### What This Protects Against
 
-```jsx
-const [hasToken, loading, error] = useSecureStorageItem('accessToken');
-```
+✅ **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  
 
-**Retorna:** `[exists, loading, error]`
+### What This Does NOT Protect Against
 
-#### `useSecureStorageDebug()`
-Obtiene información de debug del sistema.
+❌ **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  
 
-```jsx
-const debugInfo = useSecureStorageDebug();
-console.log(`Claves encriptadas: ${debugInfo.encryptedKeys.length}`);
-```
+### Best Practices
 
-### Angular Service
+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
 
-#### `SecureStorageService`
+## Browser Support
 
-```typescript
-// Inyectar el servicio
-constructor(private secureStorage: SecureStorageService) {}
+Requires [Web Crypto API](https://caniuse.com/cryptography):
 
-// Guardar
-this.secureStorage.setItem('key', 'value').subscribe();
+- Chrome 37+
+- Firefox 34+
+- Safari 11+
+- Edge 12+
+- Opera 24+
 
-// Leer
-this.secureStorage.getItem('key').subscribe(value => console.log(value));
+**Fallback:** Gracefully degrades to unencrypted localStorage in unsupported browsers.
 
-// Guardar objetos JSON
-this.secureStorage.setObject('user', { id: 1, name: 'Juan' }).subscribe();
+## API Reference
 
-// Leer objetos JSON
-this.secureStorage.getObject<User>('user').subscribe(user => console.log(user));
+### Core Methods
 
-// Obtener debug info como Observable
-this.secureStorage.getDebugInfo$().subscribe(info => console.log(info));
+```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
 ```
 
-## 🔄 Migración de Datos Existentes
+### Expiration
+
+```typescript
+setItemWithExpiry(key: string, value: string, options: {
+  expiresIn?: number;    // milliseconds from now
+  expiresAt?: Date;      // absolute date
+}): Promise<void>
+
+cleanExpired(): Promise<number>  // Returns count of deleted items
+```
 
-Si ya tienes datos en localStorage sin encriptar, puedes migrarlos fácilmente:
+### Events
 
-```javascript
-import { secureStorage } from '@mtt/local-cipher';
+```typescript
+on(event: StorageEventType, listener: EventListener): void
+off(event: StorageEventType, listener: EventListener): void
+once(event: StorageEventType, listener: EventListener): void
 
-// Migrar claves específicas
-await secureStorage.migrateExistingData([
-  'accessToken',
-  'refreshToken',
-  'user',
-  'sessionId'
-]);
+// Event types: 'encrypted', 'decrypted', 'deleted', 'cleared', 
+//              'expired', 'error', 'keyRotated', 'compressed'
 ```
 
-**Recomendación:** Ejecuta esto al iniciar tu aplicación para migrar automáticamente.
+### Namespaces
 
-## 🛡️ Seguridad
+```typescript
+namespace(name: string): NamespacedStorage
 
-### ¿Qué protege?
+const userStorage = storage.namespace('user');
+await userStorage.setItem('profile', data);
+await userStorage.clearNamespace();
+```
 
-✅ **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  
+### Key Rotation
 
-### ¿Qué NO protege?
+```typescript
+rotateKeys(): Promise<void>
+exportEncryptedData(): Promise<EncryptedBackup>
+importEncryptedData(backup: EncryptedBackup): Promise<void>
+```
 
-❌ **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  
+## FAQ
 
-### Cómo Funciona
+**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.
 
-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
+**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.
 
-**Ejemplo de localStorage:**
+**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.
 
-```
-Antes:
-  accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-  user: '{"id":1,"name":"Juan"}'
+**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.
 
-Después:
-  __enc_a7f5d8e2c1b4: "Qm9keUVuY3J5cHRlZERhdGE..."
-  __enc_9c3e7b1a5f8d: "QW5vdGhlckVuY3J5cHRlZA..."
-  __app_salt: "cmFuZG9tU2FsdEhlcmU="
-```
+**Q: How is this different from sessionStorage?**  
+A: sessionStorage is cleared on tab close. This provides persistent, encrypted storage across sessions.
 
-## 🧪 Utilidades de Debug
+**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
-import { debugEncryptionState, testEncryption, forceMigration } from '@mtt/local-cipher';
+**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.
 
-// Ver estado del sistema
-await debugEncryptionState();
+## Migration from v1
 
-// Probar encriptación
-await testEncryption();
+v1 data is automatically migrated to v2 format on first read. No action required.
 
-// Forzar migración
-await forceMigration(['accessToken', 'refreshToken']);
+```typescript
+// v1 and v2 are API-compatible
+const storage = SecureStorage.getInstance();  // Works with both
 ```
 
-## 🌐 Compatibilidad
+## Examples
 
-Requiere navegadores con soporte para **Web Crypto API**:
+See [/examples](./examples) directory for:
+- Basic usage
+- React integration
+- Angular integration
+- Advanced features (TTL, events, namespaces)
 
-- ✅ Chrome 37+
-- ✅ Firefox 34+
-- ✅ Safari 11+
-- ✅ Edge 12+
-- ✅ Opera 24+
+## Contributing
 
-**Nota:** En navegadores sin soporte, la librería hace fallback automático a localStorage normal.
+Contributions welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) first.
 
-## 📄 Licencia
+## Security Issues
 
-MIT © MTT
+Report security vulnerabilities to [security@example.com](mailto:security@example.com). See [SECURITY.md](./SECURITY.md) for details.
 
-## 🤝 Contribuir
+## License
 
-Las contribuciones son bienvenidas. Por favor abre un issue o pull request en GitHub.
+MIT © MTT - See [LICENSE](./LICENSE) for details.
 
-## 📞 Soporte
+## Links
 
-Si encuentras algún problema o tienes preguntas, abre un issue en GitHub.
+- [npm package](https://www.npmjs.com/package/@bantis/local-cipher)
+- [GitHub repository](https://github.com/master-tech-team/-bantis-local-cipher)
+- [Changelog](./CHANGELOG.md)
+- [Security Policy](./SECURITY.md)