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

Administra el flujo de autenticación mediante Google Identity (OAuth 2.0 popup), gestión de Access Tokens y validación asíncrona de listas blancas (whitelist) en Realtime Database.

Atributos Exportados (export const)

1. userSession

Tipo: Auth (instancia de Firebase Auth)

Propósito: Instancia exportada directa de la sesión de Firebase Auth.

Ejemplo de uso:

import { userSession } from "../../_main/auth.js";

userSession.onAuthStateChanged((user) => {
  if (user) console.log("Usuario autenticado:", user.email);
});

Funciones Exportadas (export function)

1. userSignIn({ callbackOnSuccess, callbackOnFail })

Firma: userSignIn({ callbackOnSuccess: Function, callbackOnFail: Function }): void

Propósito: Abre la ventana emergente de autenticación de Google Identity y verifica la autorización por Whitelist.

ParámetroTipoRequeridoDescripción
optionsObjectSíObjeto de configuración de los callbacks de inicio de sesión.
options.callbackOnSuccessFunctionOpcionalCallback invocado tras iniciar sesión y validar autorización en la whitelist.
options.callbackOnFailFunctionOpcionalCallback invocado si el usuario cancella el popup o no está autorizado.

Ejemplo de uso:

import { userSignIn } from "../../_main/auth.js";

userSignIn({
  callbackOnSuccess: (user) => console.log("Usuario autenticado:", user.email),
  callbackOnFail: (err) => console.error("Error al iniciar sesión:", err)
});

2. userSignOut({ callbackOnSuccess, callbackOnFail })

Firma: userSignOut({ callbackOnSuccess: Function, callbackOnFail: Function }): void

Propósito: Cierra la sesión activa del usuario en Firebase Auth y revoca credenciales locales.

ParámetroTipoRequeridoDescripción
optionsObjectSíObjeto de configuración de los callbacks de cierre de sesión.
options.callbackOnSuccessFunctionOpcionalCallback invocado al cerrar la sesión correctamente.
options.callbackOnFailFunctionOpcionalCallback invocado en caso de error durante el cierre de sesión.

Ejemplo de uso:

import { userSignOut } from "../../_main/auth.js";

userSignOut({
  callbackOnSuccess: () => console.log("Sesión cerrada exitosamente."),
  callbackOnFail: (err) => console.error("Error al cerrar sesión:", err)
});

3. isUserAuthorized(user)

Firma: isUserAuthorized(user: Object|string): Promise<boolean>

Propósito: Consulta la rama /allowed_users/ de Realtime Database para verificar si el usuario se encuentra autorizado.

ParámetroTipoRequeridoDescripción
userObject | StringSíObjeto de usuario retornado por Firebase Auth o string con el uid.

Ejemplo de uso:

import { isUserAuthorized } from "../../_main/auth.js";

const isAllowed = await isUserAuthorized(user.uid);
if (!isAllowed) {
  console.warn("El usuario no pertenece a la whitelist de la aplicación.");
}

4. sanitizeUserKey(email)

Firma: sanitizeUserKey(email: string): string

Propósito: Sanitiza un correo electrónico reemplazando puntos por guiones bajos para usarlo como clave segura en Firebase Realtime Database.

ParámetroTipoRequeridoDescripción
emailStringSíCorreo electrónico a sanitizar.

Ejemplo de uso:

import { sanitizeUserKey } from "../../_main/auth.js";

const dbKey = sanitizeUserKey("usuario.ejemplo@dominio.com");
// Resultado: "usuario_ejemplo@dominio_com"

5. setGoogleAccessToken(token)

Firma: setGoogleAccessToken(token: string): void

Propósito: Almacena localmente un token de acceso OAuth 2.0 de Google.

ParámetroTipoRequeridoDescripción
tokenStringSíAccess Token OAuth 2.0 de Google.

6. getGoogleAccessToken() & ensureGoogleAccessToken()

Firma: ensureGoogleAccessToken(): Promise<string|null>

Propósito: Garantizan un Access Token activo de Google OAuth 2.0 antes de realizar peticiones a servicios REST de Google (ej. Google Drive API v3).

Ejemplo de uso:

import { ensureGoogleAccessToken } from "../../_main/auth.js";

const token = await ensureGoogleAccessToken();
console.log("Token OAuth 2.0 listo para peticiones REST:", token);

Buenas Prácticas