@bantis/local-cipher 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MTT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# @bantis/local-cipher
+
+[![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/-mtt-local-cipher)
+
+Librería de cifrado local AES-256-GCM para proteger datos sensibles en localStorage. Compatible con **Angular**, **React** y **JavaScript vanilla**.
+
+## 🔐 Características
+
+- ✅ **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
+
+## 📦 Instalación
+
+```bash
+npm install @mtt/local-cipher
+```
+
+## 🚀 Uso Rápido
+
+### JavaScript Vanilla
+
+```javascript
+import { secureStorage } from '@mtt/local-cipher';
+
+// Guardar datos encriptados
+await secureStorage.setItem('accessToken', 'mi-token-secreto');
+
+// Leer datos desencriptados
+const token = await secureStorage.getItem('accessToken');
+
+// Eliminar datos
+await secureStorage.removeItem('accessToken');
+
+// Limpiar todo
+secureStorage.clear();
+```
+
+### React
+
+```jsx
+import { useSecureStorage } from '@mtt/local-cipher';
+
+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>
+  );
+}
+```
+
+### Angular
+
+```typescript
+import { SecureStorageService } from '@mtt/local-cipher';
+
+@Component({
+  selector: 'app-root',
+  template: `<div>{{ token$ | async }}</div>`
+})
+export class AppComponent {
+  token$ = this.secureStorage.getItem('accessToken');
+
+  constructor(private secureStorage: SecureStorageService) {}
+
+  saveToken(token: string) {
+    this.secureStorage.setItem('accessToken', token).subscribe();
+  }
+}
+```
+
+## 📚 Documentación Completa
+
+### API Principal
+
+#### `SecureStorage`
+
+**`setItem(key: string, value: string): Promise<void>`**
+Guarda un valor encriptado en localStorage.
+
+**`getItem(key: string): Promise<string | null>`**
+Recupera y desencripta un valor de localStorage.
+
+**`removeItem(key: string): Promise<void>`**
+Elimina un valor de localStorage.
+
+**`hasItem(key: string): Promise<boolean>`**
+Verifica si existe una clave.
+
+**`clear(): void`**
+Limpia todos los datos encriptados.
+
+**`migrateExistingData(keys: string[]): Promise<void>`**
+Migra datos existentes no encriptados a formato encriptado.
+
+### React Hooks
+
+#### `useSecureStorage<T>(key: string, initialValue: T)`
+Hook principal para usar SecureStorage de forma reactiva.
+
+```jsx
+const [user, setUser, loading, error] = useSecureStorage('user', null);
+```
+
+**Retorna:** `[value, setValue, loading, error]`
+
+#### `useSecureStorageItem(key: string)`
+Verifica si existe una clave.
+
+```jsx
+const [hasToken, loading, error] = useSecureStorageItem('accessToken');
+```
+
+**Retorna:** `[exists, loading, error]`
+
+#### `useSecureStorageDebug()`
+Obtiene información de debug del sistema.
+
+```jsx
+const debugInfo = useSecureStorageDebug();
+console.log(`Claves encriptadas: ${debugInfo.encryptedKeys.length}`);
+```
+
+### Angular Service
+
+#### `SecureStorageService`
+
+```typescript
+// Inyectar el servicio
+constructor(private secureStorage: SecureStorageService) {}
+
+// Guardar
+this.secureStorage.setItem('key', 'value').subscribe();
+
+// Leer
+this.secureStorage.getItem('key').subscribe(value => console.log(value));
+
+// Guardar objetos JSON
+this.secureStorage.setObject('user', { id: 1, name: 'Juan' }).subscribe();
+
+// Leer objetos JSON
+this.secureStorage.getObject<User>('user').subscribe(user => console.log(user));
+
+// Obtener debug info como Observable
+this.secureStorage.getDebugInfo$().subscribe(info => console.log(info));
+```
+
+## 🔄 Migración de Datos Existentes
+
+Si ya tienes datos en localStorage sin encriptar, puedes migrarlos fácilmente:
+
+```javascript
+import { secureStorage } from '@mtt/local-cipher';
+
+// Migrar claves específicas
+await secureStorage.migrateExistingData([
+  'accessToken',
+  'refreshToken',
+  'user',
+  'sessionId'
+]);
+```
+
+**Recomendación:** Ejecuta esto al iniciar tu aplicación para migrar automáticamente.
+
+## 🛡️ Seguridad
+
+### ¿Qué protege?
+
+✅ **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  
+
+### ¿Qué NO protege?
+
+❌ **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  
+
+### Cómo Funciona
+
+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
+
+**Ejemplo de localStorage:**
+
+```
+Antes:
+  accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  user: '{"id":1,"name":"Juan"}'
+
+Después:
+  __enc_a7f5d8e2c1b4: "Qm9keUVuY3J5cHRlZERhdGE..."
+  __enc_9c3e7b1a5f8d: "QW5vdGhlckVuY3J5cHRlZA..."
+  __app_salt: "cmFuZG9tU2FsdEhlcmU="
+```
+
+## 🧪 Utilidades de Debug
+
+```javascript
+import { debugEncryptionState, testEncryption, forceMigration } from '@mtt/local-cipher';
+
+// Ver estado del sistema
+await debugEncryptionState();
+
+// Probar encriptación
+await testEncryption();
+
+// Forzar migración
+await forceMigration(['accessToken', 'refreshToken']);
+```
+
+## 🌐 Compatibilidad
+
+Requiere navegadores con soporte para **Web Crypto API**:
+
+- ✅ Chrome 37+
+- ✅ Firefox 34+
+- ✅ Safari 11+
+- ✅ Edge 12+
+- ✅ Opera 24+
+
+**Nota:** En navegadores sin soporte, la librería hace fallback automático a localStorage normal.
+
+## 📄 Licencia
+
+MIT © MTT
+
+## 🤝 Contribuir
+
+Las contribuciones son bienvenidas. Por favor abre un issue o pull request en GitHub.
+
+## 📞 Soporte
+
+Si encuentras algún problema o tienes preguntas, abre un issue en GitHub.

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+import { Observable } from 'rxjs';
+
+/**
+ * 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 key;
+    private baseKey;
+    private baseKeyPromise;
+    /**
+     * 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;
+}
+
+/**
+ * SecureStorage - API de alto nivel que imita localStorage con cifrado automático
+ * Implementa el patrón Singleton
+ */
+declare class SecureStorage {
+    private static instance;
+    private encryptionHelper;
+    private constructor();
+    /**
+     * Obtiene la instancia singleton de SecureStorage
+     */
+    static getInstance(): SecureStorage;
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * Migra datos existentes no encriptados a formato encriptado
+     * @param keys - Array de claves a migrar
+     */
+    migrateExistingData(keys: string[]): Promise<void>;
+    /**
+     * Obtiene información de debug sobre el estado del almacenamiento
+     */
+    getDebugInfo(): {
+        cryptoSupported: boolean;
+        encryptedKeys: string[];
+        unencryptedKeys: string[];
+        totalKeys: number;
+    };
+}
+
+declare const secureStorage$1: SecureStorage;
+/**
+ * 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
+ * @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];
+/**
+ * Hook para verificar si una clave existe en SecureStorage
+ *
+ * @param key - Clave a verificar
+ * @returns [exists, loading, error]
+ *
+ * @example
+ * const [hasToken, loading] = useSecureStorageItem('accessToken');
+ */
+declare function useSecureStorageItem(key: string): [boolean, boolean, Error | null];
+/**
+ * Hook para obtener información de debug del almacenamiento
+ *
+ * @returns Información de debug
+ *
+ * @example
+ * const debugInfo = useSecureStorageDebug();
+ * console.log(`Claves encriptadas: ${debugInfo.encryptedKeys.length}`);
+ */
+declare function useSecureStorageDebug(): any;
+
+/**
+ * Servicio de Angular para SecureStorage
+ * 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));
+ */
+declare class SecureStorageService {
+    private storage;
+    private debugInfo$;
+    constructor();
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * 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<{
+        cryptoSupported: boolean;
+        encryptedKeys: string[];
+        unencryptedKeys: string[];
+        totalKeys: number;
+    }>;
+    /**
+     * 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 recuperar objetos JSON
+     * @param key - Clave
+     * @returns Observable con el objeto parseado o null
+     */
+    getObject<T>(key: string): Observable<T | null>;
+}
+
+/**
+ * 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
+ * Librería de cifrado local AES-256-GCM para Angular, React y JavaScript
+ *
+ * @author MTT
+ * @license MIT
+ */
+
+declare const secureStorage: SecureStorage;
+declare const VERSION = "1.0.0";
+
+export { EncryptionHelper, SecureStorage, SecureStorageService, VERSION, debugEncryptionState, forceMigration, secureStorage$1 as reactSecureStorage, secureStorage, useSecureStorage, useSecureStorageDebug, useSecureStorageItem };