npm package: @giaquinta/behavioral-sdk
Description: Behavioral Biometrics SDK for capture and verification of user patterns (Taps and Scrolls)
Latest version: 1.0.0

# 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)](./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:**
    ```bash
    pnpm install
    ```
2.  **Iniciar la aplicación:**
    ```bash
    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:**
    ```bash
    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:**
        ```bash
        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:**
        ```bash
        python -m pytest tests/integration
        ```

*   **Ejecutar Todos los Tests del Backend:**
    ```bash
    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

```ts
import { BehavioralSDK } from "@behavior/sdk";

BehavioralSDK.init({
  apiUrl: "https://api.behavior.local",
  appId: "restaurant_app",
});
```