BaP Docs - Core Engine

Guía de Integración del Core (Engine Core Setup)

Aprende a integrar, configurar y utilizar los módulos del núcleo de BaP Framework en tu aplicación web.

⚠️ 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.

📋 Pre requisitos de Entorno

Antes de comenzar a utilizar los módulos del núcleo, asegúrate de contar con la siguiente configuración inicial:

Archivo bap.config.json configurado en la raíz del proyecto con la versión y rutas de la aplicación.
Variables de entorno definidas en el archivo .env para la compilación automatizada mediante Gulp.
Servicios de Firebase habilitados en la consola de Google (para proyectos con backend activo).

1. Inicializar la Aplicación y Servicios Globales

Los módulos constants.js y firebaseInit.js actúan como el punto de entrada lógico. Resuelven dinámicamente las URLs base y proveen un gateway único e inmutable para los SDKs de Google Firebase.

JavaScript — src/index.js (Inicialización de constantes y Firebase)

import { CONSTANT, ENV_URL } from "./_main/constants.js";
import { bapApp, bapAuth, bapDB } from "./_main/firebaseInit.js";

console.log(`BaP Framework ${CONSTANT.APP_VERSION} corriendo en $https://bap-framework.gonzaloarenasf.cl`);

2. Configurar Autenticación con Google Identity y Whitelist

El módulo auth.js administra el flujo de inicio/cierre de sesión mediante una ventana emergente de Google Identity, obtiene los tokens de acceso OAuth 2.0 y valida los permisos de usuario contra la rama /allowed_users/ de Realtime Database.

JavaScript — Control de sesión y Whitelist (auth.js)

import { logIn, logOut, isUserAuthorized, ensureGoogleAccessToken } from "./_main/auth.js";

// Iniciar sesión con Google Identity
logIn(
  async (user) => {
    const isAuthorized = await isUserAuthorized(user.uid);
    if (isAuthorized) {
      console.log("Usuario autorizado por Whitelist:", user.email);
    }
  },
  (error) => console.error("Error al iniciar sesión:", error)
);

🔒 Regla de Bypass Local (Bypass de Seguridad): Si CONSTANT.FIREBASE_AVAILABLE es false en tu archivo de entorno local .env, el enrutador omitirá todas las validaciones de listas blancas e inicio de sesión para agilizar el desarrollo de vistas locales.

3. Configurar Enrutamiento SPA y Rutas Protegidas

Los módulos routerPaths.js y router.js gestionan la navegación de la Single Page Application (SPA) sin recargar la página, mitigando ataques de inyección XSS al crear componentes programáticamente.

JavaScript — Navegación SPA (router.js & routerPaths.js)

import { initRouter, navigateTo } from "./_main/router.js";

// Inicializar el enrutador al cargar el DOM
document.addEventListener("DOMContentLoaded", () => {
  initRouter();
});

// Navegación programática segura
navigateTo("/pages/core/");

4. Persistencia Cifrada (AES-GCM 256-bit) y Base de Datos

El módulo storage.js provee una capa de persistencia ultrasegura. Cifra datos confidenciales en localStorage o sessionStorage usando **AES-GCM de 256 bits** y **PBKDF2** (100,000 iteraciones y salt) aislados por el uid del usuario, sincronizándolos opcionalmente con Realtime Database.

JavaScript — Persistencia cifrada AES-GCM (storage.js)

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

// Guardar y cifrar datos confidenciales en localStorage
await setToStorageAsync({
  storageType: CONSTANT.STORAGE.SOURCE.LOCAL,
  item: "user_secret_data",
  value: { role: "admin", token: "secret_123" },
  secretKey: user.uid // Aislamiento criptográfico por usuario
});

// Descifrar datos
const data = await getFromStorageAsync({
  storageType: CONSTANT.STORAGE.SOURCE.LOCAL,
  item: "user_secret_data",
  secretKey: user.uid
});

5. Internacionalización (i18n) y Sanitización Anti-XSS

El módulo i18n.js recorre el DOM de forma segura usando un TreeWalker nativo para sustituir marcadores de traducción sin destruir escuchadores de eventos. Incluye sanitizeHTML() impulsado por DOMPurify.

JavaScript — Traducción y Filtro Anti-XSS (i18n.js)

import { applyI18n, sanitizeHTML } from "./_main/i18n.js";

// Aplicar internacionalización en tiempo de ejecución
applyI18n(() => {
  console.log("i18n aplicado correctamente al DOM.");
});

// Sanitizar código HTML dinámico proveniente de fuentes externas
const safeHTML = sanitizeHTML("<img src=x onerror=alert(1)><strong>Texto seguro</strong>");

6. Telemetría, Drive, Markdown y Utilidades Transversales

Los módulos auxiliares analytics.js, util.js, googleDrive.js y markdown.js complementan la experiencia de desarrollo con métricas de uso, identificadores criptográficos (crypto.randomUUID), sincronización en la nube y renderizado de documentos.

JavaScript — Servicios adicionales y utilidades

import { generateUUID, bapNotify } from "./_main/util.js";
import { parseMarkdown } from "./_main/markdown.js";
import { uploadFile } from "./_main/googleDrive.js";

// 1. UUID criptográficamente fuerte
const uniqueId = generateUUID();

// 2. Disparar notificación Toast
bapNotify("ALERT", "SUCCESS", "Operación exitosa", "El archivo fue procesado.");

// 3. Renderizar Markdown a HTML
const htmlOutput = parseMarkdown("# Reporte de Estado\n- Todo funcionando.");

📖 Referencia Completa de Módulos de la API Core

Índice rápido de consulta técnica para los 11 módulos del núcleo:

Módulo	Propósito	Funciones Exportadas	Integraciones / Sinergias
`constants.js`	Fuente única de verdad. Resuelve ENV_URL dinámicamente según el origin para prevenir colisión de puertos.	`CONSTANT, ENV_URL, CDN_URL, IS_PROD`	Gulp (inyección %%BAP_*%%), Web Components y vistas.
`firebaseInit.js`	Gateway único para la inicialización perezosa de servicios de Firebase.	`bapApp, bapAuth, bapDB, bapAnalytics, logAnalyticEvent()`	auth.js, storage.js, analytics.js.
`auth.js`	Autenticación Google Identity, tokens OAuth 2.0 y validación de Whitelist.	`logIn(), logOut(), isUserAuthorized(), ensureGoogleAccessToken()`	router.js (route guards), googleDrive.js (OAuth Bearer token).
`routerPaths.js`	Catálogo declarativo y estricto de todas las rutas válidas y sus permisos.	`routerPaths, getRouteInfo()`	router.js, bap-header (construcción de menús).
`router.js`	Motor de enrutamiento SPA que navega sin recarga de página y mitiga XSS.	`initRouter(), navigateTo(), getCurrentRoute(), getQueryParams()`	auth.js, analytics.js, elementos con data-link.
`storage.js`	Persistencia local y remota cifrada con AES-GCM (256-bit) y derivación PBKDF2.	`secureEncryptData(), secureDecryptData(), getFromStorageAsync(), setToStorageAsync()`	auth.js, Firebase Realtime Database, componentes de vista.
`i18n.js`	Motor de internacionalización (TreeWalker) y sanitizador HTML (DOMPurify).	`applyI18n(), getI18nContent(), sanitizeHTML(), replaceTokensInDOM()`	Web Components (bap-header, bap-dialog, etc.), markdown.js.
`analytics.js`	Centralización y taxonomía unificada de eventos de telemetría.	`analytic.logEvent.*`	router.js (pageviews), componentes UI.
`util.js`	Caja de herramientas: UUIDs criptográficos (crypto.randomUUID) y notificaciones Toast.	`generateUUID(), bapNotify(), isMobile(), isCSSIncluded(), loadScript()`	customComponentsRegistration.js, storage.js, auth.js.
`googleDrive.js`	Servicio desacoplado para la API REST v3 de Google Drive.	`searchFolder(), createFolder(), uploadFile(), getFile(), listFilesInFolder()`	auth.js (ensureGoogleAccessToken), herramientas de reporte.
`markdown.js`	Parser local y ligero de Markdown a HTML sanitizado.	`parseMarkdown(), renderMarkdownToContainer()`	bap-dialog, simulador de migración, documentos de vistas.
`ai.js`	Motor genérico de cliente para la API de Google Gemini (Soporte exclusivo actual).	`generateContent(), generateContentWithRetryAndFallback()`	bap.config.json (configuración de IA), constants.js (CONSTANT.AI).

Seguridad: Reglas recomendadas para Realtime Database

La validación de whitelist y los guards de ruta se ejecutan en el cliente, por lo que son una capa de UX y no constituyen la frontera de seguridad real. La autorización efectiva depende de las Reglas de Seguridad de Firebase que configures en tu propio proyecto. BaP nunca despliega ni sobrescribe las reglas de tu proyecto.

⚠️ Plantilla recomendativa (no se despliega automáticamente): Es una base deny-by-default de referencia. Adáptala a tu modelo de datos y publícala tú mismo en la consola de Firebase. La seguridad de tus datos depende de estas reglas, no de la validación client-side.

{
  "rules": {
    ".read": false,
    ".write": false,
    "allowed_users": {
      "$userKey": {
        ".read": "auth != null",
        ".write": false
      }
    }
  }
}

🎯 Alcance: prototipos y MVP BaP Framework está diseñado para prototipos y MVP, no como una solución de seguridad definitiva. El bypass afecta la navegación de vistas, no el acceso a datos (protegido por las Reglas de Seguridad). Quien lo lleve a producción asume el riesgo y es responsable de endurecer su propia infraestructura (Firebase Auth, App Check y Reglas de Seguridad).

🤖 Auditoría de Seguridad Asistida con IA (bap-security-auditor)

La habilidad ejecutable .agents/skills/bap-security-auditor/ evalúa automáticamente el proyecto contra el modelo de seguridad de SECURITY.md, verificando la exclusión de credenciales `.env`, la regla de build VUL-04, la protección de AppCheck/reCAPTCHA y ejecutando la suite de tests.

Prompts de Ejemplo: "Audita la seguridad del sitio web antes de publicar" o "Revisa si mi proyecto cumple las normas de SECURITY.md"