⚠️ Advertencia sobre Modificaciones del Core: Si bien BaP Framework permite modificar cualquier archivo en src/_main/, ten en cuenta que al actualizar a una nueva versión de BaP en el futuro, cualquier cambio manual en los archivos del núcleo se sobrescribirá y perderá. Se sugiere contactar al referente o mantenedor del framework para sugerir mejoras o cambios antes de alterar el motor localmente.

Módulo storage.js

Capa de persistencia con cifrado criptográfico local **AES-GCM de 256 bits** y derivación **PBKDF2** (100,000 iteraciones y salt) enlazados al `uid` del usuario, e integración remota con Realtime Database.

Atributos Exportados (export const)

1. dbRoutes

Tipo: Object

Propósito: Objeto expuesto con funciones que retornan las rutas de la base de datos inyectadas desde `bap.config.json` en tiempo de compilación.

Ejemplo de uso:

import { dbRoutes } from "../../_main/storage.js";

// Obtener la ruta de la colección de usuarios autorizados
const path = dbRoutes.allowedUsers();
console.log("Ruta en Realtime Database:", path);

Funciones Exportadas (export function / export const)

1. secureEncryptData(data, password)

Firma: secureEncryptData(data: Object|string, password: string): Promise<string>

Propósito: Cifra datos usando AES-GCM (256-bit) y derivación PBKDF2 mediante la Web Crypto API nativa.

ParámetroTipoRequeridoDescripción
dataObject | StringSíDatos en texto plano u objeto JSON a cifrar.
passwordStringSíClave secreta o uid del usuario para derivar la clave de cifrado PBKDF2.

Ejemplo de uso:

import { secureEncryptData } from "../../_main/storage.js";

const cipherText = await secureEncryptData({ role: "admin" }, user.uid);
console.log("Payload cifrado AES-GCM:", cipherText);

2. secureDecryptData(encryptedData, password)

Firma: secureDecryptData(encryptedData: string, password: string): Promise<Object|string|null>

Propósito: Descifra bloques de texto cifrados utilizando la contraseña o clave secreta enlazada al `uid` del usuario.

ParámetroTipoRequeridoDescripción
encryptedDataStringSíCadena cifrada codificada en Base64.
passwordStringSíClave secreta o uid para descifrado.

Ejemplo de uso:

import { secureDecryptData } from "../../_main/storage.js";

const plainData = await secureDecryptData(cipherText, user.uid);
console.log("Datos descifrados:", plainData);

3. setToStorageAsync({ storageType, item, value, secretKey })

Firma: setToStorageAsync(options: Object): Promise<boolean>

Propósito: Cifra y guarda un elemento en `localStorage` o `sessionStorage` de forma asíncrona.

ParámetroTipoRequeridoDescripción
options.storageTypeStringSíFuente (CONSTANT.STORAGE.SOURCE.LOCAL o SESSION).
options.itemStringSíClave del elemento en el almacenamiento.
options.valueAnySíValor a almacenar.
options.secretKeyStringOpcionalClave para cifrado criptográfico AES-GCM.

Ejemplo de uso:

import { setToStorageAsync, CONSTANT } from "../../_main/storage.js";

await setToStorageAsync({
  storageType: CONSTANT.STORAGE.SOURCE.LOCAL,
  item: "config_data",
  value: { theme: "dark" },
  secretKey: user.uid
});

4. getFromStorageAsync({ storageType, item, secretKey, sanitize })

Firma: getFromStorageAsync(options: Object): Promise<any>

Propósito: Lee y descifra asíncronamente un elemento guardado localmente.

ParámetroTipoRequeridoDescripción
options.storageTypeStringSíFuente de almacenamiento.
options.itemStringSíClave del elemento a consultar.
options.secretKeyStringOpcionalClave para descifrar el elemento.
options.sanitizeBooleanOpcionalSi es true, sanitiza el resultado contra XSS.

Ejemplo de uso:

import { getFromStorageAsync, CONSTANT } from "../../_main/storage.js";

const config = await getFromStorageAsync({
  storageType: CONSTANT.STORAGE.SOURCE.LOCAL,
  item: "config_data",
  secretKey: user.uid
});

5. updateStorageAsync({ storageType, item, value, secretKey })

Firma: updateStorageAsync(options: Object): Promise<boolean>

Propósito: Actualiza asíncronamente un elemento almacenado cifrado en el almacenamiento local.

ParámetroTipoRequeridoDescripción
options.storageTypeStringSíFuente de almacenamiento.
options.itemStringSíClave del elemento.
options.valueAnySíNuevo valor a almacenar.
options.secretKeyStringOpcionalClave de cifrado.

Ejemplo de uso:

import { updateStorageAsync, CONSTANT } from "../../_main/storage.js";

await updateStorageAsync({
  storageType: CONSTANT.STORAGE.SOURCE.LOCAL,
  item: "config_data",
  value: { theme: "light", updated: true },
  secretKey: user.uid
});

6. Métodos legacy por Callbacks: getFromStorage, setToStorage, updateStorage, removeFromStorage

Propósito: Métodos síncronos/por callbacks para consulta, guardado, actualización y eliminación de elementos en almacenamiento local o Realtime Database.

ParámetroTipoRequeridoDescripción
options.storageTypeStringSíFuente (LOCAL, SESSION o DB).
options.itemStringSíClave o ruta del elemento.
options.callbackOnSuccessFunctionOpcionalCallback ejecutado en éxito.
options.callBackOnFailFunctionOpcionalCallback ejecutado si ocurre un error.

Ejemplo de uso:

import { removeFromStorage, CONSTANT } from "../../_main/storage.js";

removeFromStorage({
  storageType: CONSTANT.STORAGE.SOURCE.LOCAL,
  item: "draft_cache",
  callbackOnSuccess: () => console.log("Caché eliminada.")
});

Buenas Prácticas