README.md

---

title: Deci Core Api
emoji: 🛡️
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---


# DECI — Decentralized Cognitive Identity Core

> **PoH (Proof of Humanity) Engine · Production API · Vertex Coders LLC**

![Version](https://img.shields.io/badge/version-0.1.0--production-green)
![Infrastructure](https://img.shields.io/badge/host-Hugging%20Face%20Spaces-orange)
![Security](https://img.shields.io/badge/defense-Rate%20Limited%20%2B%20Polyglot-blue)
![License](https://img.shields.io/badge/license-MIT-green)

---

## 👁️ ¿Qué es DECI Core?

DECI es un motor de **autenticación cognitiva continua** expuesto como una API REST invisible para entornos Zero-Trust. En lugar de mitigar el fraude mediante desafíos estáticos e intrusivos (como los CAPTCHAs tradicionales que las IAs resuelven fácilmente), DECI analiza el **ADN conductual** del usuario mientras interactúa de forma nativa con los campos de entrada de datos.

El sistema procesa señales biométricas sub-segundo como la latencia entre pulsaciones (IKL), micro-pausas estructurales y coeficientes de variación de ritmo para calcular un **Trust Score (0.0 → 1.0)** en tiempo real.


```



Score >= 0.65  →  HUMAN      ✓  (Acceso transparente)

Score  0.40-0.65  →  SUSPECT  ⚠  (Desafío adaptativo / Step-up 2FA)

Score <  0.40  →  BOT        ✗  (Bloqueo inmediato de sesión / API Reject)



```

---

## 🧠 Modelado Matemático de Defensa

El motor no se limita a promediar velocidades en caracteres por minuto; evalúa la irregularidad orgánica del operador mediante dos pilares estadísticos correlacionados:

### 1. Entropía de Shannon ($H$)
La incertidumbre o aleatoriedad del ritmo de tipeo se cuantifica dinámicamente. Un operador humano posee una alta entropía intrínseca debido a variables micro-biológicas y cognitivas:

$$H(X) = -\sum_{i=1}^{n} P(x_i) \log_2 P(x_i)$$

Donde $P(x_i)$ es la probabilidad de ocurrencia de un intervalo de tiempo específico entre teclas. Los scripts automatizados exhiben un colapso inmediato de entropía ($H \to 0$).



### 2. Coeficiente de Variación ($CV$) vs. Distribución de Cauchy

Los scripts de ataque avanzados (como los evaluados en la suite de DeepSeek Lab) inyectan latencia artificial usando distribuciones de **Cauchy** para imitar pausas humanas mediante colas pesadas (*heavy tails*). DECI neutraliza este comportamiento evaluando el Coeficiente de Variación:



$$CV = \frac{\sigma}{\mu}$$



Donde $\sigma$ es la desviación estándar y $\mu$ es la media de los intervalos de tiempo entre teclas (IKL). Mientras que un humano mantiene un $CV > 0.15$ debido a las transiciones complejas entre caracteres, las ejecuciones sintéticas se delatan por mantener una regularidad matemática artificial ($CV < 0.05$).



---



## ┌── Arquitectura de Infraestructura Cloud ($0.00 Cost)



El backend se encuentra dockerizado y desplegado en un entorno aislado de **Hugging Face Spaces**, garantizando alta disponibilidad sin costes operativos de infraestructura.





```



┌─────────────────────────────────────────────────────────────┐

│                   DECI Cloud Architecture                   │

├─────────────────────────────────────────────────────────────┤

│                                                             │

│  Client App / SDK Invisible                                 │

│  ┌───────────────────────┐                                  │

│  │     deci-telemetry.js │ ← Captura sub-segundo en background│

│  └───────────┬───────────┘                                  │

│              │ Secure HTTPS POST                            │

│              ▼                                              │

│  ┌───────────────────────────────────────────────────────┐  │

│  │ Hugging Face Spaces (Isolated Contenedor Docker)     │  │

│  │ ┌───────────────────┐                                 │  │

│  │ │ FastAPI (Python)  │ ← Rate-Limited via SlowAPI       │  │

│  │ └─────────┬─────────┘   Max 5 req/min por IP activa   │  │

│  │           │                                           │  │

│  │           ▼ Internal Vector Search                    │  │

│  │ ┌───────────────────┐                                 │  │

│  │ │ Qdrant Embedded   │ ← Vault de ADN Cognitivo        │  │

│  │ └───────────────────┘                                 │  │

│  └───────────────────────────────────────────────────────┘  │

│                                                             │

└─────────────────────────────────────────────────────────────┘



```



---



## 🛠️ Estructura del Core del Servidor





```



deci-prototype/

├── Dockerfile                  # Configuración de producción No-Root (Puerto 7860)

├── README.md                   # Manifiesto de metadatos e ingeniería del Space

├── requirements.txt            # Dependencias estrictas del runtime de Python

│

└── app/

├── main.py                 # Inicialización de FastAPI + SlowAPI Rate Limiting

├── core/

│   ├── engine.py           # Algoritmia de Scoring de Entropía y CV

│   ├── config.py           # Parámetros del sistema y thresholds

│   └── security.py         # Cifrado de firmas cognitivas y Shadow Mode

└── api/

└── endpoints/

├── session.py      # Producción: POST /session/analyze

└── attack.py       # Red Team: POST /attack/simulate/ghosting



```



---



## 🔬 Bitácora del Stress Test (Resultados Reales de Producción)



Durante la fase de validación y control desde la estación de trabajo `HP-Omen`, el núcleo operativo en la nube fue sometido a ataques dirigidos de inyección conductual con latencia artificial errática, arrojando las siguientes métricas definitivas:



### Test 001 — Calibración de Simulación de Ataque (Intensidad 0.5)

* **Comando Ejecutado:**

```bash



curl -X POST https://denisijcu-deci-core-api.hf.space/attack/simulate/ghosting \

     -H "Content-Type: application/json" \

     -d '{

          "session_id": "cloud-test-vertex-001",
          "events": [

            {"key": "v", "timestamp": 1000.0}, {"key": "e", "timestamp": 1200.0},

            {"key": "r", "timestamp": 1450.0}, {"key": "t", "timestamp": 1700.0},

            {"key": "e", "timestamp": 1950.0}, {"key": "x", "timestamp": 2200.0},

            {"key": "c", "timestamp": 2450.0}, {"key": "o", "timestamp": 2700.0},

            {"key": "d", "timestamp": 2950.0}, {"key": "e", "timestamp": 3200.0},

            {"key": "r", "timestamp": 3450.0}, {"key": "s", "timestamp": 3700.0},

            {"key": "s", "timestamp": 3950.0}, {"key": "e", "timestamp": 4200.0},

            {"key": "c", "timestamp": 4450.0}, {"key": "u", "timestamp": 4700.0},

            {"key": "r", "timestamp": 4950.0}, {"key": "i", "timestamp": 5200.0},

            {"key": "t", "timestamp": 5450.0}, {"key": "y", "timestamp": 5700.0}

          ],

          "metadata": {"intensity": 0.5, "algorithm": "cauchy"}

         }'


```



* **Payload de Respuesta Exitoso (HTTP 200):**



```json

{

  "session_id": "cloud-test-vertex-001",

  "entropy_score": 0.3747,

  "score": 0.35,

  "verdict": "BOT",

  "signal_breakdown": {

    "entropy": 0.3747,

    "cv": 0.0451,

    "mean_ikl_ms": 247.37,

    "corr_rate": 0.0,

    "burst_ratio": 0.0,

    "s_entropy": 0.5,

    "s_cv": 0.05,

    "s_mean": 1.0,

    "s_corrections": 0.05

  }

}



```

> 📊 **Análisis del Test:** A pesar de que el bot intentó mimetizarse usando una cadencia lenta de ~247ms, el motor detectó la extrema regularidad lineal de la firma biométrica arrojando un $CV = 0.0451$ (muy por debajo del límite humano), lo que desplomó el score global a **0.35**, asignando un veredicto inmediato de **BOT**.

---

## 🚀 API Endpoints de Producción

### `POST /session/analyze`

Analiza los vectores de telemetría conductual enviados de forma transparente por el SDK del cliente.

* **Rate Limit:** 5 peticiones por minuto por IP (Mitigación nativa de abuso).

### `POST /attack/simulate/ghosting`

Endpoint de simulación ofensiva. Inyecta ruido matemático sintético en el motor para validar la resiliencia de las señales.

* **Rate Limit:** 3 peticiones por minuto por IP.

### `GET /health`

Mapeo rápido de disponibilidad de la API y estado de la bóveda cognitiva.

* **Comando:** `curl -X GET https://denisijcu-deci-core-api.hf.space/health`
* **Respuesta:** `{"api":"ok","vault":"ok","shadow_mode":true}`

---

## 🛡️ Capa de Hardening y Protección del Servidor

1. **Aislamiento Operativo:** El `Dockerfile` descarta privilegios de administrador mediante directivas `USER 1000`, neutralizando ataques de ejecución remota de comandos o escape de contenedor.
2. **Control de Inundación de Recursos:** Implementación de `slowapi` en la capa de endpoints que responde con estados **HTTP 429 Too Many Requests** ante ráfagas DDoS coordinadas sin depender de bases de datos externas de almacenamiento en caché.
3. **Filtro Políglota Pasivo:** Middleware HTTP interceptor que escanea el contenido de los hilos POST bloqueando patrones maliciosos, credenciales ofuscadas en formato hexadecimal o fugas de buffers antes de ceder el control al motor.

---

## 👥 Equipo y Contribuciones

* **Denis Sanchez Leyva** (CEO, Vertex Coders LLC) — Arquitectura General, Hardening de Servidores e Infraestructura de Producción API.
* **Gemini** — Ingeniería Cloud, Control de Saturación y Despliegue de Nodos en Contenedor.
* **Claude** — Diseño de Estructura de Telemetría Cognitiva del Sprint 1.
* **DeepSeek Lab** — Framework de Ataque Conductual Ofensivo y Pruebas de Estrés Biométrico.

---

**Vertex Coders LLC — Miami, Florida** *Ofensivo por diseño. Defensivo por naturaleza.* 🛡️🔥