Behavioral Biometrics System - Full Stack

Este proyecto implementa un sistema integral para capturar, analizar y persistir biometría conductual del usuario. Comprende un SDK Frontend para la captura de datos en diversas plataformas y un Servicio Backend para el procesamiento, perfilado y almacenamiento de estos datos, diseñado para identificar patrones de usuario y detectar anomalías.

📚 Documentación

Para una guía detallada sobre cómo integrar este sistema en tus aplicaciones, consulta nuestra:

👉 Guía de Integración (docs/integration.md)

Esta guía incluye ejemplos para Web (React), Mobile (React Native, Flutter) y detalles técnicos de la API del Backend.

🏗️ Arquitectura

Todo el sistema se adhiere a la Clean Architecture, Domain-Driven Design (DDD) y los principios SOLID. Esto asegura una clara separación de responsabilidades, alta mantenibilidad y testabilidad.

Arquitectura del SDK Frontend (TypeScript/React)

El SDK frontend está diseñado para la captura de eventos conductuales del usuario en aplicaciones web/móviles. Se caracteriza por ser:

• Reutilizable e independiente del dominio.
• Fácil de integrar en cualquier aplicación web, WebView o aplicación móvil nativa.
• Respetuoso de la privacidad del usuario, capturando únicamente métricas temporales y dinámicas.

Actualmente, el SDK Frontend incluye:

• Módulo de Captura de Taps (TapCapture.ts): Una clase TypeScript pura, agnóstica de frameworks, que captura datos detallados de taps (duración, posición inicial y final).
• Módulo de Perfilado y Verificación (TapProfileBuilder.ts): Un módulo TypeScript puro que, a partir de los datos de taps, construye un perfil estadístico (media y desviación estándar para duración y distancia de movimiento) y verifica nuevos taps contra este perfil.
• Aplicación Piloto (DataCollector.tsx): Un componente React que sirve como interfaz de demostración para las funcionalidades de captura, perfilado y verificación de taps. Soporta múltiples usuarios y visualiza las métricas y resultados en tiempo real.

Arquitectura del Servicio Backend (Python/SQLAlchemy/PostgreSQL)

El servicio backend está estructurado en capas distintas para gestionar los perfiles conductuales:

• Capa de Dominio (src/domain):

  • Modelos: Clases dataclass de Python (ej., MetricStats, TapProfile, ScrollProfile, BehavioralProfile). Estas definen las entidades y objetos de valor del negocio principal, completamente independientes de cualquier base de datos o framework. Contienen las reglas de negocio fundamentales y las estructuras de datos para los perfiles conductuales.
  • Principios: Adhiere a SRP (responsabilidad única para la estructura de datos y reglas de negocio), OCP (abierto a la extensión con nuevas métricas, cerrado a la modificación de la lógica central) y DIP (abstracción sobre los detalles de implementación).

• Capa de Aplicación (src/application):

  • Interfaces de Repositorio (IBehavioralProfileRepository): Clases abstractas que definen el contrato para interactuar con la persistencia de perfiles conductuales (ej., get_by_user_id, save, update). Esta es una abstracción clave para DIP e ISP.
  • Casos de Uso (ProfileManagementUseCase): Reglas de negocio específicas de la aplicación que orquestan los modelos de dominio e interactúan con la interfaz del repositorio. Estos representan las acciones específicas que la aplicación puede realizar (ej., create_or_update_user_profile).
  • Principios: Adhiere a SRP (cada caso de uso tiene una responsabilidad), OCP (nuevas características pueden extender casos de uso existentes o añadir nuevos sin modificar la lógica central) y DIP (depende de abstracciones de repositorio).

• Capa de Infraestructura (src/infrastructure):

  • Configuración de Base de Datos (database.py): Configura SQLAlchemy, define los modelos ORM (UserORM, TapProfileORM, ScrollProfileORM) que se mapean directamente a tablas de PostgreSQL, y proporciona utilidades de base de datos (init_db, get_db, create_tables).
  • Implementaciones de Repositorio (sqlalchemy_repository.py): Implementaciones concretas de IBehavioralProfileRepository utilizando SQLAlchemy. Estas clases manejan la conversión entre modelos de dominio y modelos ORM, y realizan las operaciones reales de la base de datos.
  • Principios: Adhiere a DIP (implementa la interfaz abstracta del repositorio definida en la capa de aplicación), SRP (la lógica de persistencia está encapsulada aquí).

💾 Estrategia de Base de Datos (PostgreSQL)

El servicio backend está diseñado para utilizar una Base de Datos Relacional, siendo PostgreSQL la opción recomendada para entornos de producción y pre-producción debido a su robustez, características de integridad de datos y amplias herramientas.

• Desarrollo y Pruebas: Para el desarrollo local y las pruebas automatizadas, se utiliza una base de datos SQLite en memoria. Esto proporciona un entorno rápido y aislado para ejecutar pruebas sin necesidad de una instancia de PostgreSQL en ejecución.
  • Cómo funciona: El módulo src/infrastructure/database.py permite configurar la URL de la base de datos. Los tests utilizan sqlite:///:memory: para crear una base de datos temporal y aislada para cada ejecución de prueba.
• Pre-producción y Producción: Para despliegues de pre-producción y producción, se espera que la DATABASE_URL se proporcione a través de una variable de entorno. Esta variable apuntará a tu instancia de PostgreSQL (ej., postgresql://usuario:contraseña@host:puerto/nombre_db).
  • Creación de Esquema: La función create_tables() (de src/infrastructure/database.py) debe ejecutarse una vez durante el inicio de la aplicación o el despliegue para asegurar que las tablas necesarias (users, tap_profiles, scroll_profiles) estén presentes en la base de datos PostgreSQL.

Estructura de la Tabla:

• users: Almacena la identificación básica del usuario.
  • id (VARCHAR, PRIMARY KEY)
  • created_at (TIMESTAMP)
  • updated_at (TIMESTAMP)
• tap_profiles: Almacena perfiles conductuales específicos para interacciones de taps.
  • user_id (VARCHAR, PRIMARY KEY, FOREIGN KEY to users.id)
  • duration_mean (REAL)
  • duration_std_dev (REAL)
  • movement_distance_mean (REAL)
  • movement_distance_std_dev (REAL)
  • sample_size (INTEGER)
  • created_at (TIMESTAMP)
  • updated_at (TIMESTAMP)
• scroll_profiles: Almacena perfiles conductuales específicos para interacciones de navegación (scroll).
  • user_id (VARCHAR, PRIMARY KEY, FOREIGN KEY to users.id)
  • distance_mean (REAL)
  • distance_std_dev (REAL)
  • velocity_mean (REAL)
  • velocity_std_dev (REAL)
  • duration_mean (REAL)
  • duration_std_dev (REAL)
  • sample_size (INTEGER)
  • created_at (TIMESTAMP)
  • updated_at (TIMESTAMP)

🚀 Cómo Ejecutar la Aplicación Piloto (Frontend)

El proyecto incluye una aplicación piloto interactiva (DataCollector.tsx) para demostrar la captura, perfilado y verificación de taps en tiempo real.

1. Instalar dependencias:

   pnpm install

2. Iniciar la aplicación:

   pnpm run dev

   Abre la URL proporcionada en tu terminal (usualmente http://localhost:5173) en tu navegador.

Uso de la Aplicación Piloto

La interfaz de usuario te permitirá:

• Definir un Usuario: Introduce un User ID en el campo de texto superior.
• Enrolamiento de Perfil: Realiza la cantidad de taps configurada (por defecto 10) en el área gris central. La aplicación recolectará datos de duración y distancia de movimiento de cada tap.
• Creación Automática de Perfil: Una vez alcanzados los taps de enrolamiento, el perfil biométrico del usuario se creará y se mostrará automáticamente en el cuadro "Profile for [User ID]".
• Verificación en Tiempo Real: Después de crear el perfil, cada tap adicional se comparará con este. El log de "Captured Taps" indicará si el tap fue [Verified ✓] o [Rejected ✗].
• Gestión Multi-Perfil: Cambia el User ID para crear y gestionar perfiles biométricos para diferentes usuarios.
• Borrar Datos: El botón "Clear Data" reinicia la captura y borra el perfil del usuario activo.

🔐 Seguridad y Resiliencia de Datos

El sistema incorpora protecciones avanzadas contra ataques comunes en biometría conductual:

• Protección contra Envenenamiento de Datos (Data Poisoning):
  • Filtrado de Outliers: Tanto en el enrolamiento como en las actualizaciones dinámicas, se filtran puntos de datos anómalos (Z-score > 1.5) para evitar que un atacante desvíe gradualmente el perfil del usuario.
  • Control de Deriva (Drift Control): Una vez que el perfil es maduro (n > 10), el sistema limita el cambio máximo de la media por actualización (3% en el frontend, 5% en el backend). Esto bloquea ataques que intentan "empujar" lentamente el perfil hacia un comportamiento malicioso.
  • API Shielding (Rate Limiting): Se ha implementado un sistema de limitación de peticiones en el backend (Flask-Limiter). Esto bloquea ataques de fuerza bruta, adivinación de IDs y ráfagas de ruido, limitando las actualizaciones a 5 por minuto y las consultas a 10 por minuto por dirección IP.
  • Estadística Robusta: El cálculo de la desviación estándar incluye una fase de pre-filtrado de valores extremos para asegurar una línea base confiable.
  • Validación en Backend: El servidor valida la integridad de cada perfil (tamaño de muestra mínimo, varianza razonable y valores positivos) antes de persistirlos.
• Detección de Ofuscación de Identidad (Mimicry/Bots):
  • Umbral de Mimicry: El sistema detecta interacciones "demasiado perfectas" (Z-score < 0.05). Una consistencia robótica es a menudo señal de scripts automatizados o intentos de imitación artificial, y es rechazada por el motor de verificación.
  • Límites de Varianza: Se imponen límites mínimos y máximos a la desviación estándar para evitar perfiles excesivamente sensibles o peligrosamente permisivos.

🧠 Señales Conductuales Multiplataforma Capturadas

El SDK captura señales conductuales universales, independientemente de la plataforma (Web, iOS, Android, React Native o Flutter).

(Sección idéntica a la anterior sobre las señales capturadas, ya que sigue siendo relevante para la descripción general del proyecto.)

🔐 Privacidad

(Sección idéntica a la anterior sobre privacidad.)

🏗 Plataformas Soportadas

(Sección idéntica a la anterior sobre plataformas soportadas.)

🧪 Testing

El proyecto emplea una estrategia de pruebas robusta que cubre tanto los componentes de frontend como los de backend.

Pruebas Frontend (TypeScript/Vitest)

• Cómo ejecutar:

  pnpm test

• Cobertura: Incluye tests unitarios para las clases de captura (TapCapture, ScrollCapture) y los módulos de perfilado/verificación (TapProfileBuilder, ScrollProfileBuilder), asegurando la integridad de las métricas táctiles y de navegación.

Pruebas Backend (Python/Pytest)

El backend utiliza pytest para su suite de pruebas, dividida en:

• Tests Unitarios (tests/unit/domain y tests/unit/application):

  • Propósito: Verificar la funcionalidad de unidades individuales (modelos de dominio, casos de uso) de forma aislada.
  • Cobertura: Asegura que la lógica del dominio es sólida y que la lógica de la aplicación orquesta correctamente las interacciones del dominio sin dependencias externas.
  • Ejecución: Mocks de componentes externos (como el repositorio) para asegurar que los tests sean rápidos y enfocados.
  • Cómo ejecutar:

    python -m pytest tests/unit

• Tests de Integración (tests/integration/infrastructure):

  • Propósito: Verificar la interacción entre diferentes capas, especialmente la implementación del repositorio de SQLAlchemy con una base de datos real.
  • Cobertura: Asegura el mapeo correcto entre los modelos de dominio y ORM, y las operaciones adecuadas de la base de datos (guardar, recuperar, actualizar).
  • Ejecución: Utiliza una base de datos SQLite en memoria para la velocidad y el aislamiento durante la ejecución de los tests. Esto significa que no necesitas una instancia de PostgreSQL en ejecución para ejecutar los tests de integración.
  • Cómo ejecutar:

    python -m pytest tests/integration

• Ejecutar Todos los Tests del Backend:

  python -m pytest

🚀 Despliegue del Servicio Backend

(Esta sección se completará más adelante con instrucciones detalladas de despliegue para entornos de pre-producción y producción. Incluirá la configuración de PostgreSQL, variables de entorno y posiblemente Dockerización o scripts de despliegue.)

🔌 Integración del SDK Frontend

import { BehavioralSDK } from "@behavior/sdk";

BehavioralSDK.init({
  apiUrl: "https://api.behavior.local",
  appId: "restaurant_app",
});