update

README.md

@@ -13,4 +13,481 @@ pinned: false
 
 DECI is a high-performance, privacy-first backend API designed to detect advanced AI bots, cognitive mimicry attacks, and credential stuffing in real time.
 
+> **PoH Engine · Sprint 1 MVP · Vertex Coders LLC**
+
+![Version](https://img.shields.io/badge/version-0.1.0--sprint1-red)
+![Status](https://img.shields.io/badge/status-MVP%20%2F%20Research-yellow)
+![Stack](https://img.shields.io/badge/stack-FastAPI%20%2B%20Qdrant%20%2B%20Python-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+---
+
+## ¿Qué es DECI?
+
+DECI es un motor experimental de **autenticación cognitiva continua**. En vez de preguntar *"¿qué sabes?"* (contraseña) o *"¿qué tienes?"* (token), DECI pregunta *"¿cómo piensas mientras escribes?"*
+
+Analiza señales de comportamiento en tiempo real — latencia entre teclas, patrones de corrección, micro-pausas — y genera un **Trust Score (0.0 → 1.0)** que indica si quien está escribiendo es un humano real o un bot automatizado.
+
+```
+Score >= 0.65  →  HUMAN      ✓
+Score  0.40-0.65  →  SUSPECT  ⚠
+Score <  0.40  →  BOT        ✗
+```
+
+> **Nota importante:** Este es un MVP de investigación (Sprint 1). Los números de precisión no están validados con datos reales todavía. Ver sección [Estado actual del proyecto](#estado-actual-del-proyecto).
+
+---
+
+## Screenshots
+
+| Dashboard | Session Analyzer |
+|-----------|-----------------|
+| ![Dashboard](docs/screenshots/dashboard.png) | ![Analyzer](docs/screenshots/analyzer.png) |
+
+| Red Team Lab | Signal Analysis |
+|-------------|-----------------|
+| ![Attacks](docs/screenshots/attacks.png) | ![Signals](docs/screenshots/signals.png) |
+
+---
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    DECI Architecture                    │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  Browser/Client                                         │
+│  ┌──────────────────────┐                               │
+│  │  deci-dashboard.html │  ← Dashboard HTML (single     │
+│  │  (Keystroke capture) │    file, sin dependencias)    │
+│  └──────────┬───────────┘                               │
+│             │ POST /session/analyze                     │
+│             │ POST /attack/simulate/ghosting            │
+│             ▼                                           │
+│  ┌──────────────────────┐                               │
+│  │  FastAPI (Python)    │  ← PoH Engine, port 8000     │
+│  │  app/main.py         │                               │
+│  │  app/core/engine.py  │  ← Scoring logic              │
+│  └──────────┬───────────┘                               │
+│             │                                           │
+│             ▼                                           │
+│  ┌──────────────────────┐                               │
+│  │  Qdrant              │  ← Cognitive DNA Vault        │
+│  │  (Vector DB)         │    port 6333                  │
+│  └──────────────────────┘                               │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Estructura del proyecto
+
+```
+deci-prototype/
+├── docker-compose.yml          # Levanta FastAPI + Qdrant
+├── Dockerfile                  # Container de la API
+├── .env                        # Variables de entorno
+├── requirements.txt            # Dependencias Python
+│
+├── app/
+│   ├── main.py                 # Punto de entrada FastAPI
+│   ├── core/
+│   │   ├── engine.py           # PoH Engine — corazón del sistema
+│   │   ├── config.py           # Configuración global
+│   │   └── security.py        # JWT + Shadow Mode
+│   ├── api/
+│   │   ├── endpoints/
+│   │   │   ├── session.py      # POST /session/analyze
+│   │   │   └── attack.py       # POST /attack/simulate/ghosting
+│   │   └── schemas/
+│   │       └── telemetry.py    # Modelos Pydantic — el Contrato
+│   ├── database/
+│   │   └── qdrant_vault.py     # Cognitive DNA Vault
+│   └── tests/
+│       └── deepseek_lab/       # Red Team attack suite
+│           ├── mimicry_attack_v2.py
+│           ├── ghosting_attack.py
+│           ├── forced_errors.py
+│           ├── entropy_scanner.py
+│           ├── benchmark.py
+│           └── results/
+│
+├── scripts/
+│   └── setup_db.py             # Inicializa colección Qdrant
+│
+└── deci-dashboard.html         # Dashboard completo (single file)
+```
+
+---
+
+## Instalación y arranque rápido
+
+### Requisitos previos
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/) instalado y corriendo
+- Python 3.11+ (solo para el red team lab)
+- Un browser moderno (Chrome, Firefox, Edge)
+
+### Paso 1 — Clonar el repo
+
+```bash
+git clone https://github.com/tu-usuario/deci-prototype.git
+cd deci-prototype
+```
+
+### Paso 2 — Configurar variables de entorno
+
+```bash
+cp .env.example .env
+# El .env por defecto funciona para desarrollo local
+# Cambia SECRET_KEY en producción
+```
+
+### Paso 3 — Levantar el backend
+
+```bash
+docker-compose up
+```
+
+Deberías ver algo así:
+
+```
+deci_vault  | Qdrant HTTP listening on 6333
+deci_core   | INFO: Uvicorn running on http://0.0.0.0:8000
+deci_core   | [DECI] Cognitive Vault ready — collection: cognitive_dna
+```
+
+### Paso 4 — Abrir el dashboard
+
+Tienes dos opciones:
+
+**Opción A — Directo en el browser (más simple):**
+```bash
+# Windows
+start deci-dashboard.html
+
+# Mac
+open deci-dashboard.html
+
+# Linux
+xdg-open deci-dashboard.html
+```
+
+**Opción B — Con servidor local (recomendado, evita CORS):**
+```bash
+# Si tienes Python
+python -m http.server 5500
+# Abrir: http://localhost:5500/deci-dashboard.html
+
+# Si tienes Node
+npx serve .
+# Abrir: http://localhost:3000/deci-dashboard.html
+```
+
+### Paso 5 — Verificar que todo funciona
+
+El topbar del dashboard debe mostrar `● OPERATIONAL` en verde.
+
+Si muestra `● API OFFLINE`, verifica que `docker-compose up` esté corriendo.
+
+---
+
+## Guía de uso del Dashboard
+
+### Tab 1 — Dashboard
+
+Vista general en tiempo real. Muestra:
+
+- **Métricas** — conteo de sesiones Human / Suspect / Bot / Calibrating
+- **Score distribution** — histograma de scores de las últimas sesiones
+- **Attack detections** — chart de ataques detectados vs bypassed (datos del Sprint 1)
+- **Live session feed** — feed en tiempo real de sesiones entrantes
+
+Las sesiones del feed en modo demo son simuladas. Cuando conectas el Session Analyzer, las sesiones reales aparecen aquí.
+
+### Tab 2 — Session Analyzer
+
+**El corazón del sistema.** Aquí puedes probar DECI con tu propia escritura.
+
+**Cómo usarlo:**
+
+1. Click en **Start** — el textarea se activa
+2. **Escribe cualquier cosa** — un párrafo, texto libre, lo que sea. Mínimo 10 keystrokes, ideal 80+
+3. Click en **Analyze** — el payload se envía al engine
+4. El resultado aparece a la derecha con:
+   - **Verdict** (HUMAN / SUSPECT / BOT)
+   - **Score** (0.0 → 1.0)
+   - **Confidence** — qué tan seguro está el engine
+   - **Signal breakdown** — por qué tomó esa decisión
+
+**Importante:** Con menos de 50 keystrokes el IKL Entropy es inestable. Para resultados confiables escribe al menos 2-3 oraciones completas.
+
+**¿Qué mide mientras escribes?**
+
+| Señal | Peso | Lo que detecta |
+|-------|------|----------------|
+| IKL Entropy | 30% | Variabilidad en el tiempo entre teclas. Los humanos tienen distribución lognormal. Los bots tienen distribución normal o constante. |
+| Corrections | 25% | Patrones de backspace. Los humanos cometen errores en ráfagas orgánicas. Los bots no cometen errores o los distribuyen uniformemente. |
+| Pauses | 15% | Micro-pausas (>800ms). Los humanos pausan antes de palabras difíciles. Los bots generan de forma lineal. |
+| Speed | 15% | Velocidad en CPM. Rango humano: 150-600 CPM. |
+| Fatigue | 15% | ¿Se simplifica el vocabulario con el tiempo? Los humanos se cansan. Los bots no. |
+
+### Tab 3 — Red Team Lab
+
+**El laboratorio de DeepSeek.** Simula ataques contra el engine para probar su robustez.
+
+#### Ghosting Attack
+
+Simula un bot que intenta imitar latencia humana. Cuatro niveles de sofisticación:
+
+| Nivel | Técnica | Score esperado | ¿Pasa? |
+|-------|---------|----------------|--------|
+| L1 — Constant | Delay fijo de 100ms | ~0.08 | ❌ BOT |
+| L2 — Gaussian | Noise gaussiano | ~0.22 | ❌ BOT |
+| L3 — Bimodal | Clusters rápido+lento | ~0.44 | ❌ SUSPECT |
+| L4 — Lognormal | Distribución biológica + bursts + fatiga | ~0.60 | ⚠ SUSPECT |
+
+**Cómo correrlo:**
+1. Seleccionar el nivel en el dropdown
+2. Opcionalmente cambiar el texto objetivo
+3. Click **Run Attack** — el payload se envía al endpoint real de Gemini
+4. El resultado aparece en el Attack Log
+
+**Full Suite** corre los 4 niveles en secuencia automáticamente.
+
+#### Forced Errors
+
+Testea si el engine detecta la ausencia de correcciones orgánicas:
+
+- **Variant A** — Cero correcciones (clásico tell de LLM) → detectado
+- **Variant C** — Fake burst (ataque sofisticado) → SUSPECT
+- **Variant E** — Bursts posicionados óptimamente → SUSPECT
+
+#### Replay Attack
+
+Visualiza el scatter de cosine similarity. El threshold de detección es 0.92 — sesiones con similarity mayor son flaggeadas como replay.
+
+### Tab 4 — Signal Analysis
+
+Análisis técnico de las señales:
+
+- **Signal weights** — donut chart con el peso de cada señal en el score final
+- **Human vs Bot radar** — comparación de perfil cognitivo humano real vs bot L4
+- **DeepSeek V1 vs V2** — evolución del ataque a través de versiones
+- **Signal definitions** — definición técnica de cada señal
+
+---
+
+## Red Team Lab — Correr los ataques desde Python
+
+Además del dashboard, puedes correr los ataques directamente desde Python:
+
+```bash
+# Instalar dependencias
+pip install -r requirements.txt
+
+# Asegúrate de que docker-compose up está corriendo
+# Luego:
+
+# Ataque simple
+python app/tests/deepseek_lab/mimicry_attack_v2.py --version v2 --target gemini
+
+# Con texto largo (más confiable)
+python app/tests/deepseek_lab/mimicry_attack_v2.py \
+  --version v2 \
+  --target gemini \
+  --text "Intento de acceso no autorizado al nucleo VIC de Vertex Coders usando patron cognitivo avanzado de nivel cuatro"
+
+# Benchmark completo V1 vs V2
+python app/tests/deepseek_lab/mimicry_attack_v2.py --benchmark --runs 10
+
+# Suite completa de DeepSeek
+python app/tests/deepseek_lab/benchmark_v2.py --verbose --iterations 20
+```
+
+Los resultados se guardan en `app/tests/deepseek_lab/results/`.
+
+---
+
+## API Endpoints
+
+Con el backend corriendo, la documentación interactiva está en:
+**http://localhost:8000/docs**
+
+### Endpoints principales
+
+#### `POST /session/analyze`
+
+Analiza una sesión de telemetría y devuelve un PoH verdict.
+
+
+
+```json
+// Request
+### POST /session/analyze
+Analiza la telemetría conductual. **Importante:** Requiere mínimo 15 eventos para un veredicto confiable.
+
+// Request (Esquema TelemetryPayload)
+{
+  "session_id": "SESS-001",
+  "events": [
+    { "key": "v", "timestamp": 1000.0 },
+    { "key": "e", "timestamp": 1150.0 }
+  ],
+  "metadata": {
+    "total_chars": 20,
+    "total_corrections": 0
+  }
+}
+
+// Response
+{
+  "verdict": "HUMAN",
+  "score": 0.8561,
+  "confidence": 0.90,
+  "signal_scores": {
+    "entropy": 0.85,
+    "cv": 0.15,
+    "corrections": 0.05
+  }
+}
+
+
+```
+
+#### `POST /attack/simulate/ghosting`
+
+Endpoint del red team. Simula un ataque de ghosting y devuelve el verdict del engine.
+
+```json
+// Request
+{
+  "session_id": "atk-001",
+  "events": [
+    { "key": "A", "timestamp": 1700000000100 },
+    { "key": "c", "timestamp": 1700000000200 }
+  ]
+}
+
+// Response
+{
+  "session_id": "atk-001",
+  "entropy_score": 0.43,
+  "score": 0.51,
+  "verdict": "SUSPECT",
+  "signal_breakdown": { ... }
+}
+```
+
+#### `GET /health`
+
+```json
+{ "api": "ok", "vault": "ok", "shadow_mode": true }
+```
+
+#### `DELETE /session/{user_id}/dna`
+
+Elimina todo el Cognitive DNA de un usuario. Cumplimiento GDPR Art. 17.
+
+---
+
+## Variables de entorno (.env)
+
+```bash
+# API
+APP_ENV=development          # development | production
+SECRET_KEY=change_me_please  # JWT secret — cambia esto en producción
+
+# Qdrant
+QDRANT_HOST=qdrant           # nombre del servicio en docker-compose
+QDRANT_PORT=6333
+QDRANT_COLLECTION=cognitive_dna
+
+# PoH Engine thresholds
+POH_HUMAN_THRESHOLD=0.65     # score >= este valor → HUMAN
+POH_SUSPECT_THRESHOLD=0.40   # score entre 0.40-0.65 → SUSPECT
+POH_ENTROPY_MIN=1.8          # entropía mínima para clasificar como humano
+POH_CALIBRATION_SESSIONS=3   # sesiones requeridas antes de activar validación completa
+
+# Shadow Mode — en true, el engine observa pero NO bloquea
+SHADOW_MODE=true
+```
+
+---
+
+## Estado actual del proyecto
+
+### ✅ Completado (Sprint 1)
+
+- PoH Engine funcional con 5 señales cognitivas
+- Cognitive DNA Vault (Qdrant) con GDPR erasure
+- API FastAPI completa con documentación automática
+- Red Team framework (DeepSeek attack suite)
+- Dashboard HTML completo con 4 módulos
+- Shadow Mode para calibración sin bloqueo
+- Cold start detection (período de calibración)
+- Docker Compose con Qdrant + FastAPI
+
+### ⚠️ Limitaciones conocidas (Sprint 1)
+
+- **No validado con datos reales** — los thresholds (0.65, 0.40) fueron elegidos por lógica, no por datos estadísticos de usuarios reales
+- **IKL Entropy inestable con < 50 keystrokes** — textos cortos dan entropy cercana a 0
+- **Sin ZK-Proofs** — la capa de privacidad avanzada está planificada para Sprint 2
+- **Sin P2P Mesh** — los nodos validadores están planificados para Sprint 2
+- **Sin WebSocket** — el dashboard usa polling/simulación, no conexión en vivo
+
+### 🔜 Sprint 2 (planificado)
+
+- ZK-Proof layer para privacidad absoluta
+- LibP2P validation mesh
+- Adaptive PoH challenges (se adaptan cuando un ataque los rompe)
+- WebSocket para feed en tiempo real
+- Validación con dataset de 50+ usuarios reales
+
+---
+
+## Equipo
+
+| Rol | Responsabilidad |
+|-----|-----------------|
+| **Denis Sanchez Leyva** (CEO, Vertex Coders) | Producto, arquitectura general, FastAPI, dashboard |
+| **Claude** (Anthropic) | PoH Engine design, privacy layer, API architecture |
+| **Gemini** (Google) | Infrastructure, Qdrant integration, node mesh design |
+| **DeepSeek** | Offensive security, attack suite, cognitive mimicry testing |
+
+---
+
+## Contribuir
+
+Este proyecto está en fase de investigación activa. Si quieres contribuir:
+
+1. Fork el repo
+2. Crea un branch: `git checkout -b feature/nombre-del-feature`
+3. Commit tus cambios: `git commit -m 'feat: descripción'`
+4. Push: `git push origin feature/nombre-del-feature`
+5. Abre un Pull Request
+
+**Áreas donde más se necesita ayuda:**
+- Recolección de datos reales para validar thresholds
+- Mejoras al PoH Engine (nuevas señales cognitivas)
+- Ataques nuevos para el red team lab
+- Tests unitarios
+
+---
+
+## Licencia
+
+MIT License — ver [LICENSE](LICENSE) para detalles.
+
+---
+
+## Disclaimer
+
+DECI es un proyecto de investigación en desarrollo activo. **No usar en producción** sin validación previa con datos reales de tu caso de uso específico. Los números de precisión en el artículo de lanzamiento son estimados teóricos, no métricas validadas.
+
+
+---
+
 Developed by **Vertex Coders LLC**. *Offensive by design. Defensive by nature.* 🛡️🔥