@jeanharo98/typed-storage 0.1.6 → 0.1.8

package/README.md

@@ -224,7 +224,8 @@ const appStorage = createStorage(schema, options);
 | `version` | `number` | — | Current schema version — required for migrations |
 | `migrations` | `Record<number, (data) => data>` | — | Migration functions per version |
 | `compress` | `boolean` | `false` | Compresses data with LZ-string before storing |
-| `encrypt` | `boolean` | `false` | Shows a security warning — see note below |
+| `encrypt` | `boolean` | `false` | Obfuscates data with XOR + Base64 — see security note below |
+| `secret` | `string` | — | Required when `encrypt: true` — the obfuscation key |
 
 ---
 
@@ -279,27 +280,79 @@ appStorage.theme.remove();     // → 'theme changed to: dark' (initialValue)
 
 ---
 
-## 🔒 A note on encryption
+## 🔒 Encryption (XOR obfuscation)
 
-If you pass `encrypt: true`, typed-storage will display a warning explaining why encrypting values in `localStorage` is not a secure practice — the encryption key must live in the frontend and is accessible to anyone who inspects your code.
+`typed-storage` can obfuscate values using XOR + Base64 before storing them. This is **not real cryptography** — read this section carefully before using it.
 
-For sensitive data such as auth tokens or personal information, use **httpOnly cookies** set by your server:
+```typescript
+const secureStorage = createStorage({
+    token: ''
+}, {
+    encrypt: true,
+    secret: 'your-secret-key',  // required when encrypt is true
+    ttl: 3600000                // recommended — expire alongside your real token
+});
+
+secureStorage.token.set('eyJhbGciOiJIUzI1NiJ9.xxx.yyy');
+// Stored in localStorage as obfuscated text, not the readable JWT
+
+const token = secureStorage.token();
+// Automatically decrypted — returns the real JWT
+```
+
+### ⚠️ What this actually protects against
+
+```
+✅ Hides the value from casual inspection in DevTools/Application/Storage
+✅ Discourages non-technical users from reading or copying the value
+✅ Combined with ttl, expires alongside your backend token
+
+❌ Does NOT protect against a technical attacker
+❌ Does NOT protect against debugger breakpoints — the secret and
+   decrypted value are visible in memory while the app runs
+❌ Is NOT equivalent to real cryptography (AES, etc.)
+```
+
+### Why this limitation exists — and why no frontend library can fix it
+
+The `secret` you pass lives in your JavaScript code, which runs in the user's browser. No matter the algorithm used (XOR, AES, anything), **the key must be present in the frontend to decrypt the value**, which means it's always inspectable:
+
+```
+1. The secret travels safely over HTTPS — that's not the problem
+2. Once it reaches the browser, it must be used by your JS to decrypt
+3. Anyone with DevTools open can set a breakpoint where decryption
+   happens and read the secret and the decrypted value directly
+4. This is true even with industry-standard encryption (Web Crypto AES) —
+   the algorithm's strength doesn't matter if the key is exposed
+```
+
+This is a fundamental limitation of any frontend-only encryption — not a flaw specific to typed-storage's XOR implementation.
+
+### For real security with auth tokens
 
 ```typescript
 // In your backend (Express / NestJS):
 res.cookie('authToken', token, {
-  httpOnly: true,   // not accessible from JavaScript
-  secure: true,     // HTTPS only
-  sameSite: 'strict'
+    httpOnly: true,   // JavaScript cannot read this — ever
+    secure: true,     // HTTPS only
+    sameSite: 'strict'
 });
 ```
 
-typed-storage is designed for:
-- ✅ UI preferences (theme, language, font size)
-- ✅ Navigation state (last visited, sidebar open)
-- ✅ Non-sensitive user settings
-- ❌ Auth tokens → use httpOnly cookies
-- ❌ Passwords or financial data → never in localStorage
+httpOnly cookies are the only approach where the token never becomes accessible to JavaScript running in the browser — because the browser itself enforces the restriction, not your code.
+
+### When `encrypt` is still worth using
+
+```
+✅ You understand it's obfuscation, not security
+✅ You want to deter casual inspection, not block determined attackers
+✅ You're combining it with ttl so values expire predictably
+✅ The data isn't critical enough to justify httpOnly cookie infrastructure
+   (e.g. you're prototyping, or it's a low-stakes internal tool)
+
+❌ Don't rely on this alone for banking, healthcare, or any data where
+   a breach has real consequences — use httpOnly cookies on the backend
+```
 
 ---
 

package/dist/core/create-storage.d.ts

@@ -0,0 +1,2 @@
+import { StorageSchema, StorageResult, StorageSignalOptions } from '../types.js';
+export declare function createStorage<T extends StorageSchema>(schema: T, options?: StorageSignalOptions): StorageResult<T>;

package/dist/core/create-storage.js

@@ -0,0 +1,31 @@
+import { createStorageSignal } from './storage-signal.js';
+import { applyMigrations } from '../features/migrations.js';
+function registerPrefix(prefix, sto) {
+    const registryKey = '__typed-storage__';
+    const existing = sto.getItem(registryKey);
+    const prefixes = existing ? JSON.parse(existing) : [];
+    if (prefix && !prefixes.includes(prefix)) {
+        prefixes.push(prefix);
+        sto.setItem(registryKey, JSON.stringify(prefixes));
+    }
+}
+export function createStorage(schema, options) {
+    if (options?.version && options.migrations) {
+        const sto = options.storage === 'session' ? sessionStorage : localStorage;
+        const prefix = options.prefix ?? '';
+        applyMigrations(prefix, options.version, options.migrations, sto);
+    }
+    const sto = options?.storage === 'session' ? sessionStorage : localStorage;
+    registerPrefix(options?.prefix ?? '', sto);
+    const result = [];
+    let keys = Object.keys(schema);
+    for (let key of keys) {
+        result[key] = createStorageSignal(key, schema[key], options);
+    }
+    result.clear = () => {
+        for (let key of keys) {
+            result[key].reset();
+        }
+    };
+    return result;
+}

package/dist/core/memory-storage.d.ts

@@ -0,0 +1,6 @@
+export declare class MemoryStorage {
+    private data;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}

package/dist/core/memory-storage.js

@@ -0,0 +1,14 @@
+export class MemoryStorage {
+    constructor() {
+        this.data = new Map();
+    }
+    getItem(key) {
+        return this.data.get(key) ?? null;
+    }
+    setItem(key, value) {
+        this.data.set(key, value);
+    }
+    removeItem(key) {
+        this.data.delete(key);
+    }
+}

package/dist/core/storage-signal.d.ts

@@ -0,0 +1,2 @@
+import { StorageSignal, StorageSignalOptions } from "../types.js";
+export declare function createStorageSignal<T>(key: string, initialValue: T, options?: StorageSignalOptions): StorageSignal<T>;

package/dist/core/storage-signal.js

@@ -0,0 +1,129 @@
+import LZString from 'lz-string';
+import { MemoryStorage } from "./memory-storage.js";
+import { xorEncrypt, xorDecrypt } from '../features/xor.js';
+function safeParseJSON(value, fallback) {
+    if (!value)
+        return { value: fallback };
+    try {
+        const parsed = JSON.parse(value);
+        if (parsed && typeof parsed === 'object' && 'value' in parsed) {
+            return parsed;
+        }
+        return { value: JSON.parse(value) };
+    }
+    catch (error) {
+        console.warn(`Error al parsear JSON de localStorage. Usando valor por defecto.`, error);
+        return { value: fallback };
+    }
+}
+function getStorage(type) {
+    try {
+        const sto = type === 'session' ? sessionStorage : localStorage;
+        sto.setItem('__typed_storage_test__', '1');
+        sto.removeItem('__typed_storage_test__');
+        return sto;
+    }
+    catch {
+        console.warn('Storage no disponible, usando memoria como fallback');
+        return new MemoryStorage();
+    }
+}
+export function createStorageSignal(key, initialValue, options) {
+    let sto = getStorage(options?.storage ?? 'local');
+    if (options?.prefix) {
+        key = `${options.prefix}:${key}`;
+    }
+    const rawData = sto.getItem(key);
+    let savedData = options?.compress && rawData
+        ? LZString.decompress(rawData)
+        : rawData;
+    if (options?.encrypt && options?.secret && savedData) {
+        try {
+            savedData = xorDecrypt(savedData, options.secret);
+        }
+        catch {
+            savedData = null;
+        }
+    }
+    let currentValue;
+    const listeners = [];
+    function notify(value) {
+        listeners.forEach(cb => cb(value));
+    }
+    const item = safeParseJSON(savedData, initialValue);
+    if (item.expiresAt === undefined) {
+        currentValue = !savedData ? initialValue : item.value;
+    }
+    else {
+        if (Date.now() <= item.expiresAt) {
+            currentValue = item.value;
+        }
+        else {
+            sto.removeItem(key);
+            currentValue = initialValue;
+        }
+    }
+    const signalBase = function () {
+        return currentValue;
+    };
+    if (options?.sync) {
+        window.addEventListener('storage', (event) => {
+            if (event.key === key) {
+                if (event.newValue === null) {
+                    notify(initialValue);
+                    return currentValue = initialValue;
+                }
+                let rawNewValue = options?.compress
+                    ? LZString.decompress(event.newValue)
+                    : event.newValue;
+                if (options?.encrypt && options?.secret) {
+                    try {
+                        rawNewValue = xorDecrypt(rawNewValue, options.secret);
+                    }
+                    catch {
+                        rawNewValue = '';
+                    }
+                }
+                const item = safeParseJSON(rawNewValue, initialValue);
+                notify(item.value);
+                return currentValue = item.value;
+            }
+        });
+    }
+    signalBase.set = function (newValue) {
+        currentValue = newValue;
+        notify(currentValue);
+        const dataToStore = JSON.stringify({
+            value: newValue,
+            expiresAt: options?.ttl ? Date.now() + options.ttl : undefined
+        });
+        let finalData = options?.compress
+            ? LZString.compress(dataToStore)
+            : dataToStore;
+        if (options?.encrypt && options?.secret) {
+            finalData = xorEncrypt(finalData, options.secret);
+        }
+        sto.setItem(key, finalData);
+    };
+    signalBase.reset = function () {
+        currentValue = initialValue;
+        notify(currentValue);
+        const dataToStore = JSON.stringify(initialValue);
+        const finalData = options?.compress
+            ? LZString.compress(dataToStore)
+            : dataToStore;
+        sto.setItem(key, finalData);
+    };
+    signalBase.has = function () {
+        return !!sto.getItem(key);
+    };
+    signalBase.remove = function () {
+        sto.removeItem(key);
+        currentValue = initialValue;
+        notify(currentValue);
+    };
+    signalBase.onChange = function (callback) {
+        listeners.push(callback);
+    };
+    return signalBase;
+}

package/dist/create-storage.js

@@ -17,24 +17,6 @@ export function createStorage(schema, options) {
     }
     const sto = options?.storage === 'session' ? sessionStorage : localStorage;
     registerPrefix(options?.prefix ?? '', sto);
-    if (options?.encrypt) {
-        console.warn(`
-⚠️  typed-storage: la opción encrypt está activada.
-
-Encriptar valores en localStorage no es seguro — 
-la clave vive en el frontend y cualquier dev puede accederla.
-
-Para datos sensibles usa:
-    ✅ httpOnly cookies (tokens, sesiones)
-    ✅ Variables de entorno en el servidor
-  
-typed-storage es ideal para:
-    ✅ Preferencias de UI (theme, language)
-    ✅ Estado de navegación
-    ❌ Tokens de autenticación
-    ❌ Datos financieros o personales sensibles
-        `);
-    }
     const result = [];
     let keys = Object.keys(schema);
     for (let key of keys) {

package/dist/features/heavy-storage/heavy-storage.d.ts

@@ -0,0 +1,3 @@
+import { HeavySignal, HeavyStorageOptions, HeavyStorageResult, HeavyStorageSchema } from "./heavy-storage.types";
+export declare function createHeavySignal<T>(key: string, initialValue: T, options?: HeavyStorageOptions): HeavySignal<T>;
+export declare function createHeavyStorage<T extends HeavyStorageSchema>(schema: T, options?: HeavyStorageOptions): HeavyStorageResult<T>;

package/dist/features/heavy-storage/heavy-storage.js

@@ -0,0 +1,50 @@
+import { dbDelete, dbGet, dbSet, openDB } from "./indexeddb-driver";
+export function createHeavySignal(key, initialValue, options) {
+    const dbName = options?.dbName ?? 'typed-storage-heavy';
+    const listeners = [];
+    function notify(value) {
+        listeners.forEach(cb => cb(value));
+    }
+    const signal = {};
+    signal.get = async function () {
+        const db = await openDB(dbName);
+        const stored = await dbGet(db, key);
+        if (stored === undefined)
+            return initialValue;
+        if (stored.expiresAt && Date.now() > stored.expiresAt) {
+            await dbDelete(db, key);
+            return initialValue;
+        }
+        return stored.value ?? initialValue;
+    };
+    signal.set = async function (value) {
+        const db = await openDB(dbName);
+        await dbSet(db, key, {
+            value,
+            expiresAt: options?.ttl ? Date.now() + options.ttl : undefined
+        });
+        notify(value);
+    };
+    signal.remove = async function () {
+        const db = await openDB(dbName);
+        await dbDelete(db, key);
+        notify(initialValue);
+    };
+    signal.onChange = function (callback) {
+        listeners.push(callback);
+    };
+    return signal;
+}
+export function createHeavyStorage(schema, options) {
+    const result = {};
+    const keys = Object.keys(schema);
+    for (const key of keys) {
+        result[key] = createHeavySignal(key, schema[key], options);
+    }
+    result.clear = async () => {
+        for (const key of keys) {
+            await result[key].remove();
+        }
+    };
+    return result;
+}

package/dist/features/heavy-storage/heavy-storage.types.d.ts

@@ -0,0 +1,16 @@
+export interface HeavyStorageOptions {
+    dbName?: string;
+    ttl?: number;
+}
+export interface HeavySignal<T> {
+    get(): Promise<T>;
+    set(value: T): Promise<void>;
+    remove(): Promise<void>;
+    onChange(callback: (value: T) => void): void;
+}
+export type HeavyStorageSchema = Record<string, any>;
+export type HeavyStorageResult<T extends HeavyStorageSchema> = {
+    [K in keyof T]: HeavySignal<T[K]>;
+} & {
+    clear(): Promise<void>;
+};

package/dist/features/heavy-storage/heavy-storage.types.js

@@ -0,0 +1 @@
+export {};

package/dist/features/heavy-storage/indexeddb-driver.d.ts

@@ -0,0 +1,4 @@
+export declare function openDB(dbName: string): Promise<IDBDatabase>;
+export declare function dbGet(db: IDBDatabase, key: string): Promise<any>;
+export declare function dbSet(db: IDBDatabase, key: string, value: any): Promise<void>;
+export declare function dbDelete(db: IDBDatabase, key: string): Promise<void>;

package/dist/features/heavy-storage/indexeddb-driver.js

@@ -0,0 +1,40 @@
+export function openDB(dbName) {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(dbName, 1);
+        request.onupgradeneeded = (event) => {
+            const db = event.target.result;
+            if (!db.objectStoreNames.contains('storage')) {
+                db.createObjectStore('storage');
+            }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+export function dbGet(db, key) {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readonly');
+        const store = transaction.objectStore('storage');
+        const request = store.get(key);
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+export function dbSet(db, key, value) {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readwrite');
+        const store = transaction.objectStore('storage');
+        const request = store.put(value, key);
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+    });
+}
+export function dbDelete(db, key) {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readwrite');
+        const store = transaction.objectStore('storage');
+        const request = store.delete(key);
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+    });
+}

package/dist/features/migrations.d.ts

@@ -0,0 +1 @@
+export declare function applyMigrations(prefix: string, currentVersion: number, migrations: Record<number, (data: any) => any>, storage: Storage): void;

package/dist/features/migrations.js

@@ -0,0 +1,34 @@
+export function applyMigrations(prefix, currentVersion, migrations, storage) {
+    const versionKey = `${prefix}__version__`;
+    const savedVersion = storage.getItem(versionKey);
+    if (!savedVersion) {
+        storage.setItem(versionKey, String(currentVersion));
+        return;
+    }
+    let version = parseInt(savedVersion);
+    if (version >= currentVersion)
+        return;
+    const currentData = {};
+    for (let i = 0; i < storage.length; i++) {
+        const key = storage.key(i);
+        if (key && key.startsWith(prefix) && key !== versionKey) {
+            const value = storage.getItem(key);
+            if (value) {
+                const cleanKey = key.replace(`${prefix}:`, '');
+                currentData[cleanKey] = JSON.parse(value);
+            }
+        }
+    }
+    while (version < currentVersion) {
+        const migration = migrations[version];
+        if (migration) {
+            const migrated = migration(currentData);
+            Object.assign(currentData, migrated);
+        }
+        version++;
+    }
+    for (const [key, value] of Object.entries(currentData)) {
+        storage.setItem(`${prefix}:${key}`, JSON.stringify(value));
+    }
+    storage.setItem(versionKey, String(currentVersion));
+}

package/dist/features/xor.d.ts

@@ -0,0 +1,3 @@
+export declare function xorTransform(text: string, secret: string): string;
+export declare function xorEncrypt(text: string, secret: string): string;
+export declare function xorDecrypt(text: string, secret: string): string;

package/dist/features/xor.js

@@ -0,0 +1,14 @@
+export function xorTransform(text, secret) {
+    return text.split('').map((char, i) => {
+        const keyChar = secret[i % secret.length];
+        return String.fromCharCode(char.charCodeAt(0) ^ keyChar.charCodeAt(0));
+    }).join('');
+}
+export function xorEncrypt(text, secret) {
+    const xored = xorTransform(text, secret);
+    return btoa(xored);
+}
+export function xorDecrypt(text, secret) {
+    const xored = atob(text);
+    return xorTransform(xored, secret);
+}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { createStorage } from './create-storage.js';
-export { createHeavyStorage } from './heavy-storage.js';
+export { createStorage } from './core/create-storage.js';
+export { createHeavyStorage } from './features/heavy-storage/heavy-storage.js';
 export type { StorageSignal, StorageSchema, StorageResult, StorageSignalOptions } from './types.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export { createStorage } from './create-storage.js';
-export { createHeavyStorage } from './heavy-storage.js';
+export { createStorage } from './core/create-storage.js';
+export { createHeavyStorage } from './features/heavy-storage/heavy-storage.js';

package/dist/storage-signal.js

@@ -1,5 +1,6 @@
 import LZString from 'lz-string';
 import { MemoryStorage } from "./memory-storage.js";
+import { xorEncrypt, xorDecrypt } from './xor.js';
 function safeParseJSON(value, fallback) {
     if (!value)
         return { value: fallback };
@@ -33,9 +34,17 @@ export function createStorageSignal(key, initialValue, options) {
         key = `${options.prefix}:${key}`;
     }
     const rawData = sto.getItem(key);
-    const savedData = options?.compress && rawData
+    let savedData = options?.compress && rawData
         ? LZString.decompress(rawData)
         : rawData;
+    if (options?.encrypt && options?.secret && savedData) {
+        try {
+            savedData = xorDecrypt(savedData, options.secret);
+        }
+        catch {
+            savedData = null;
+        }
+    }
     let currentValue;
     const listeners = [];
     function notify(value) {
@@ -64,9 +73,17 @@ export function createStorageSignal(key, initialValue, options) {
                     notify(initialValue);
                     return currentValue = initialValue;
                 }
-                const rawNewValue = options?.compress
+                let rawNewValue = options?.compress
                     ? LZString.decompress(event.newValue)
                     : event.newValue;
+                if (options?.encrypt && options?.secret) {
+                    try {
+                        rawNewValue = xorDecrypt(rawNewValue, options.secret);
+                    }
+                    catch {
+                        rawNewValue = '';
+                    }
+                }
                 const item = safeParseJSON(rawNewValue, initialValue);
                 notify(item.value);
                 return currentValue = item.value;
@@ -80,9 +97,12 @@ export function createStorageSignal(key, initialValue, options) {
             value: newValue,
             expiresAt: options?.ttl ? Date.now() + options.ttl : undefined
         });
-        const finalData = options?.compress
+        let finalData = options?.compress
             ? LZString.compress(dataToStore)
             : dataToStore;
+        if (options?.encrypt && options?.secret) {
+            finalData = xorEncrypt(finalData, options.secret);
+        }
         sto.setItem(key, finalData);
     };
     signalBase.reset = function () {

package/dist/types.d.ts

@@ -4,6 +4,7 @@ export interface StorageSignalOptions {
     ttl?: number;
     sync?: boolean;
     encrypt?: boolean;
+    secret?: string;
     version?: number;
     migrations?: Record<number, (data: any) => any>;
     compress?: boolean;

package/dist/xor.d.ts

@@ -0,0 +1,3 @@
+export declare function xorTransform(text: string, secret: string): string;
+export declare function xorEncrypt(text: string, secret: string): string;
+export declare function xorDecrypt(text: string, secret: string): string;

package/dist/xor.js

@@ -0,0 +1,14 @@
+export function xorTransform(text, secret) {
+    return text.split('').map((char, i) => {
+        const keyChar = secret[i % secret.length];
+        return String.fromCharCode(char.charCodeAt(0) ^ keyChar.charCodeAt(0));
+    }).join('');
+}
+export function xorEncrypt(text, secret) {
+    const xored = xorTransform(text, secret);
+    return btoa(xored);
+}
+export function xorDecrypt(text, secret) {
+    const xored = atob(text);
+    return xorTransform(xored, secret);
+}

package/index.html

@@ -5,41 +5,20 @@
 </head>
 <body>
     <script type="module">
-        import { createHeavyStorage } from './dist/index.js';
+        import { createStorage } from './dist/index.js';
 
-        const heavyStorage = createHeavyStorage({
-            documents: [],
-            userPhotos: []
+        const secureStorage = createStorage({
+            token: ''
         }, {
-            dbName: 'test-heavy-storage'
+            prefix: 'secure',
+            encrypt: true,
+            secret: 'mi-clave-secreta',
+            ttl: 3600000
         });
 
-        async function test() {
-            // Set
-            await heavyStorage.documents.set([
-                { id: 1, name: 'Documento 1' },
-                { id: 2, name: 'Documento 2' }
-            ]);
-            console.log('✅ Documentos guardados');
-
-            // Get
-            const docs = await heavyStorage.documents.get();
-            console.log('📄 Documentos leídos:', docs);
-
-            // onChange
-            heavyStorage.documents.onChange((newValue) => {
-                console.log('🔔 documents cambió a:', newValue);
-            });
-
-            await heavyStorage.documents.set([{ id: 3, name: 'Documento nuevo' }]);
-
-            // Remove
-            await heavyStorage.userPhotos.remove();
-            const photos = await heavyStorage.userPhotos.get();
-            console.log('🗑️ userPhotos después de remove:', photos);
-        }
-
-        test();
+        secureStorage.token.set('eyJhbGciOiJIUzI1NiJ9.test.jwt');
+        console.log('Valor leído:', secureStorage.token());
+        console.log('Valor en localStorage (debe estar ofuscado):', localStorage.getItem('secure:token'));
     </script>
 </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeanharo98/typed-storage",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Type-safe localStorage with reactive signals",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/{create-storage.ts → core/create-storage.ts}

@@ -1,11 +1,15 @@
 // Types
-import { StorageSchema, StorageResult, StorageSignalOptions } from './types.js';
+import { 
+    StorageSchema, 
+    StorageResult, 
+    StorageSignalOptions 
+} from '../types.js';
 
 // Storage Signal
 import { createStorageSignal } from './storage-signal.js';
 
 // Migraciones
-import { applyMigrations } from './migrations.js';
+import { applyMigrations } from '../features/migrations.js';
 
 function registerPrefix (
     prefix: string,
@@ -42,25 +46,6 @@ export function createStorage<T extends StorageSchema>(
     const sto = options?.storage === 'session' ? sessionStorage : localStorage;
     registerPrefix(options?.prefix ?? '', sto);
 
-    if ( options?.encrypt ) {
-        console.warn(`
-⚠️  typed-storage: la opción encrypt está activada.
-
-Encriptar valores en localStorage no es seguro — 
-la clave vive en el frontend y cualquier dev puede accederla.
-
-Para datos sensibles usa:
-    ✅ httpOnly cookies (tokens, sesiones)
-    ✅ Variables de entorno en el servidor
-  
-typed-storage es ideal para:
-    ✅ Preferencias de UI (theme, language)
-    ✅ Estado de navegación
-    ❌ Tokens de autenticación
-    ❌ Datos financieros o personales sensibles
-        `);
-    }
-
     const result: any = [];
 
     let keys = Object.keys(schema);

package/src/{storage-signal.test.ts → core/storage-signal.test.ts}

@@ -118,4 +118,44 @@ describe('compress option', () => {
         
         expect(compressedSize).toBeLessThan(uncompressedSize);
     });
+});
+
+describe('encrypt option', () => {
+    beforeEach(() => localStorage.clear());
+
+    it('debe ofuscar el valor guardado en localStorage', () => {
+        const signal = createStorageSignal('token', '', {
+            encrypt: true,
+            secret: 'mi-clave'
+        });
+
+        signal.set('eyJhbGciOiJIUzI1NiJ9.test.jwt');
+
+        const rawStored = localStorage.getItem('token');
+        // El valor crudo NO debe contener el JWT en texto plano
+        expect(rawStored).not.toContain('eyJhbGciOiJIUzI1NiJ9');
+    });
+
+    it('debe desencriptar correctamente al leer', () => {
+        const signal = createStorageSignal('token', '', {
+            encrypt: true,
+            secret: 'mi-clave'
+        });
+
+        const originalValue = 'eyJhbGciOiJIUzI1NiJ9.test.jwt';
+        signal.set(originalValue);
+
+        expect(signal()).toBe(originalValue);
+    });
+
+    it('debe funcionar junto con TTL', () => {
+        const signal = createStorageSignal('token', '', {
+            encrypt: true,
+            secret: 'mi-clave',
+            ttl: 1000
+        });
+
+        signal.set('mi-token');
+        expect(signal()).toBe('mi-token');
+    });
 });

package/src/{storage-signal.ts → core/storage-signal.ts}

@@ -1,11 +1,20 @@
 import LZString from 'lz-string';
 
 // Tipos
-import { StorageSignal, StorageSignalOptions } from "./types.js";
+import { 
+    StorageSignal, 
+    StorageSignalOptions 
+} from "../types.js";
 
 // Memory
 import { MemoryStorage } from "./memory-storage.js";
 
+// Xor
+import { 
+    xorEncrypt, 
+    xorDecrypt 
+} from '../features/xor.js';
+
 // Interface
 interface StoredValue<T> {
     value: T;
@@ -66,9 +75,18 @@ export function createStorageSignal<T>(
     }
 
     const rawData = sto.getItem(key);
-    const savedData = options?.compress && rawData 
+    let savedData = options?.compress && rawData 
                             ? LZString.decompress(rawData) 
                             : rawData;
+
+    // Desencripta si encrypt está activo
+    if ( options?.encrypt && options?.secret && savedData ) {
+        try {
+            savedData = xorDecrypt(savedData, options.secret);
+        } catch {
+            savedData = null; // si falla desencriptar, trata como vacío
+        }
+    }
     let currentValue: T;
 
     const listeners: Array<(value: T) => void> = [];
@@ -106,9 +124,17 @@ export function createStorageSignal<T>(
                 } 
 
                 // Parseamos el nuevo valor
-                const rawNewValue = options?.compress 
+                let rawNewValue = options?.compress 
                                         ? LZString.decompress(event.newValue)
                                         : event.newValue;
+
+                if ( options?.encrypt && options?.secret ) {
+                    try {
+                        rawNewValue = xorDecrypt(rawNewValue, options.secret);
+                    } catch {
+                        rawNewValue = '';
+                    }
+                }
                 const item = safeParseJSON(rawNewValue, initialValue);
 
                 notify(item.value as T);
@@ -126,10 +152,14 @@ export function createStorageSignal<T>(
             expiresAt: options?.ttl ? Date.now() + options.ttl : undefined
         });
 
-        const finalData = options?.compress 
+        let finalData = options?.compress 
                                 ? LZString.compress(dataToStore) 
                                 : dataToStore;
 
+        if ( options?.encrypt && options?.secret ) {
+            finalData = xorEncrypt(finalData, options.secret);
+        }
+
         sto.setItem( key, finalData );
     }
 

package/src/features/heavy-storage/heavy-storage.ts

@@ -0,0 +1,89 @@
+// Indexed
+import { 
+    dbDelete, 
+    dbGet, 
+    dbSet, 
+    openDB 
+} from "./indexeddb-driver";
+
+// Types
+import { 
+    HeavySignal, 
+    HeavyStorageOptions, 
+    HeavyStorageResult, 
+    HeavyStorageSchema 
+} from "./heavy-storage.types";
+
+export function createHeavySignal<T>(
+    key: string,
+    initialValue: T,
+    options?: HeavyStorageOptions
+): HeavySignal<T> {
+    const dbName = options?.dbName ?? 'typed-storage-heavy';
+    const listeners: Array<(value: T) => void> = [];
+
+    function notify ( value: T ): void {
+        listeners.forEach(cb => cb(value));
+    }
+
+    const signal: any = {};
+
+    signal.get = async function(): Promise<T> {
+        const db = await openDB(dbName);
+        const stored = await dbGet(db, key);
+        
+        if (stored === undefined) return initialValue;
+
+        // Verifica TTL si existe
+        if (stored.expiresAt && Date.now() > stored.expiresAt) {
+            await dbDelete(db, key);
+            return initialValue;
+        }
+
+        return stored.value ?? initialValue;
+    };
+
+    signal.set = async function(value: T): Promise<void> {
+        const db = await openDB(dbName);
+        await dbSet(db, key, {
+            value,
+            expiresAt: options?.ttl ? Date.now() + options.ttl : undefined
+        });
+        notify(value);
+    };
+
+    signal.remove = async function(): Promise<void> {
+        const db = await openDB(dbName);
+        await dbDelete(db, key);
+        notify(initialValue);
+    };
+
+    signal.onChange = function ( callback: (value: T) => void ): void {
+        listeners.push(callback);
+    };
+
+    return signal as HeavySignal<T>;
+}
+
+// ===========================================
+// Iteramos el schema completo
+
+export function createHeavyStorage<T extends HeavyStorageSchema>(
+    schema: T,
+    options?: HeavyStorageOptions
+): HeavyStorageResult<T> {
+    const result: any = {};
+
+    const keys = Object.keys(schema);
+    for (const key of keys) {
+        result[key] = createHeavySignal(key, schema[key], options);
+    }
+
+    result.clear = async () => {
+        for (const key of keys) {
+            await result[key].remove();
+        }
+    };
+
+    return result as HeavyStorageResult<T>;
+}

package/src/features/heavy-storage/heavy-storage.types.ts

@@ -0,0 +1,21 @@
+export interface HeavyStorageOptions {
+    dbName?: string;
+    ttl?: number;
+}
+
+export interface HeavySignal<T> {
+    get(): Promise<T>;
+    set(value: T): Promise<void>;
+    remove(): Promise<void>;
+    onChange(callback: (value: T) => void): void;
+}
+
+// ==============================================
+
+export type HeavyStorageSchema = Record<string, any>;
+
+export type HeavyStorageResult<T extends HeavyStorageSchema> = {
+    [K in keyof T]: HeavySignal<T[K]>;
+} & {
+    clear(): Promise<void>;
+};

package/src/features/heavy-storage/indexeddb-driver.ts

@@ -0,0 +1,50 @@
+// Abrir/crear la base de datos
+export function openDB(dbName: string): Promise<IDBDatabase> {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(dbName, 1);
+
+        request.onupgradeneeded = (event) => {
+            const db = (event.target as IDBOpenDBRequest).result;
+            // Crea el "object store" — equivalente a una tabla
+            if (!db.objectStoreNames.contains('storage')) {
+                db.createObjectStore('storage');
+            }
+        };
+
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+
+export function dbGet(db: IDBDatabase, key: string): Promise<any> {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readonly');
+        const store = transaction.objectStore('storage');
+        const request = store.get(key);
+
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+
+export function dbSet(db: IDBDatabase, key: string, value: any): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readwrite');
+        const store = transaction.objectStore('storage');
+        const request = store.put(value, key);
+
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+    });
+}
+
+export function dbDelete(db: IDBDatabase, key: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readwrite');
+        const store = transaction.objectStore('storage');
+        const request = store.delete(key);
+
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+    });
+}

package/src/features/xor.ts

@@ -0,0 +1,18 @@
+export function xorTransform ( text: string, secret: string ): string {
+    return text.split('').map((char, i) => {
+        const keyChar = secret[i % secret.length];
+        return String.fromCharCode(
+            char.charCodeAt(0) ^ keyChar.charCodeAt(0)
+        );
+    }).join('');
+}
+
+export function xorEncrypt ( text: string, secret: string ): string {
+    const xored = xorTransform(text, secret);
+    return btoa(xored);
+}
+
+export function xorDecrypt ( text: string, secret: string ): string {
+    const xored = atob(text);
+    return xorTransform(xored, secret);
+}

package/src/index.ts

@@ -1,5 +1,5 @@
-export { createStorage } from './create-storage.js';
-export { createHeavyStorage } from './heavy-storage.js';
+export { createStorage } from './core/create-storage.js';
+export { createHeavyStorage } from './features/heavy-storage/heavy-storage.js';
 export type { 
     StorageSignal, 
     StorageSchema, 

package/src/types.ts

@@ -5,6 +5,7 @@ export interface StorageSignalOptions {
     ttl?: number;
     sync?: boolean;
     encrypt?: boolean;
+    secret?: string; // Requerido si el encrypt es true
     version?: number;
     migrations?: Record<number, ( data: any ) => any>;
     compress?: boolean;

package/src/heavy-storage.ts

@@ -1,146 +0,0 @@
-// Abrir/crear la base de datos
-function openDB(dbName: string): Promise<IDBDatabase> {
-    return new Promise((resolve, reject) => {
-        const request = indexedDB.open(dbName, 1);
-
-        request.onupgradeneeded = (event) => {
-            const db = (event.target as IDBOpenDBRequest).result;
-            // Crea el "object store" — equivalente a una tabla
-            if (!db.objectStoreNames.contains('storage')) {
-                db.createObjectStore('storage');
-            }
-        };
-
-        request.onsuccess = () => resolve(request.result);
-        request.onerror = () => reject(request.error);
-    });
-}
-
-function dbGet(db: IDBDatabase, key: string): Promise<any> {
-    return new Promise((resolve, reject) => {
-        const transaction = db.transaction('storage', 'readonly');
-        const store = transaction.objectStore('storage');
-        const request = store.get(key);
-
-        request.onsuccess = () => resolve(request.result);
-        request.onerror = () => reject(request.error);
-    });
-}
-
-function dbSet(db: IDBDatabase, key: string, value: any): Promise<void> {
-    return new Promise((resolve, reject) => {
-        const transaction = db.transaction('storage', 'readwrite');
-        const store = transaction.objectStore('storage');
-        const request = store.put(value, key);
-
-        request.onsuccess = () => resolve();
-        request.onerror = () => reject(request.error);
-    });
-}
-
-function dbDelete(db: IDBDatabase, key: string): Promise<void> {
-    return new Promise((resolve, reject) => {
-        const transaction = db.transaction('storage', 'readwrite');
-        const store = transaction.objectStore('storage');
-        const request = store.delete(key);
-
-        request.onsuccess = () => resolve();
-        request.onerror = () => reject(request.error);
-    });
-}
-
-// ===========================================
-
-interface HeavyStorageOptions {
-    dbName?: string;
-    ttl?: number;
-}
-
-interface HeavySignal<T> {
-    get(): Promise<T>;
-    set(value: T): Promise<void>;
-    remove(): Promise<void>;
-    onChange(callback: (value: T) => void): void;
-}
-
-export function createHeavySignal<T>(
-    key: string,
-    initialValue: T,
-    options?: HeavyStorageOptions
-): HeavySignal<T> {
-    const dbName = options?.dbName ?? 'typed-storage-heavy';
-    const listeners: Array<(value: T) => void> = [];
-
-    function notify(value: T): void {
-        listeners.forEach(cb => cb(value));
-    }
-
-    const signal: any = {};
-
-    signal.get = async function(): Promise<T> {
-        const db = await openDB(dbName);
-        const stored = await dbGet(db, key);
-        
-        if (stored === undefined) return initialValue;
-
-        // Verifica TTL si existe
-        if (stored.expiresAt && Date.now() > stored.expiresAt) {
-            await dbDelete(db, key);
-            return initialValue;
-        }
-
-        return stored.value ?? initialValue;
-    };
-
-    signal.set = async function(value: T): Promise<void> {
-        const db = await openDB(dbName);
-        await dbSet(db, key, {
-            value,
-            expiresAt: options?.ttl ? Date.now() + options.ttl : undefined
-        });
-        notify(value);
-    };
-
-    signal.remove = async function(): Promise<void> {
-        const db = await openDB(dbName);
-        await dbDelete(db, key);
-        notify(initialValue);
-    };
-
-    signal.onChange = function(callback: (value: T) => void): void {
-        listeners.push(callback);
-    };
-
-    return signal as HeavySignal<T>;
-}
-
-// ===========================================
-// Iteramos el schema completo
-
-type HeavyStorageSchema = Record<string, any>;
-
-type HeavyStorageResult<T extends HeavyStorageSchema> = {
-    [K in keyof T]: HeavySignal<T[K]>;
-} & {
-    clear(): Promise<void>;
-};
-
-export function createHeavyStorage<T extends HeavyStorageSchema>(
-    schema: T,
-    options?: HeavyStorageOptions
-): HeavyStorageResult<T> {
-    const result: any = {};
-
-    const keys = Object.keys(schema);
-    for (const key of keys) {
-        result[key] = createHeavySignal(key, schema[key], options);
-    }
-
-    result.clear = async () => {
-        for (const key of keys) {
-            await result[key].remove();
-        }
-    };
-
-    return result as HeavyStorageResult<T>;
-}