# SECURITY.md — Políticas de Seguridad del Ecosistema 4GatosCoin

Este documento define las políticas de seguridad internas del ecosistema 4GatosCoin, incluyendo DevWeb3, los endpoints API, los modelos de datos y el Organismo Global.  
Su objetivo es garantizar integridad, consistencia y protección frente a usos indebidos.

Este proyecto es **privado** y solo accesible para desarrolladores autorizados.

---

# 1. Principios de Seguridad

### **1.1. Server-side first**
Toda operación crítica debe ejecutarse exclusivamente en el servidor:

- registro de gestos  
- asignación de puntos  
- actualización del organismo global  
- generación de semillas  
- escritura de logs  
- validación de rituales  

### **1.2. Validación estricta**
Ningún dato del cliente se considera confiable.

### **1.3. Normalización obligatoria**
Todas las wallets deben normalizarse:

```
wallet.toLowerCase().trim()
```

### **1.4. Minimización de superficie**
Los endpoints solo exponen lo estrictamente necesario.

---

# 2. Seguridad en Endpoints API

Todos los endpoints viven en:

```
app/api/*
```

### **2.1. Validación de entrada**
Cada endpoint debe validar:

- tipos de datos  
- formato de wallet  
- parámetros requeridos  
- límites de longitud  
- tipos de gesto permitidos  

### **2.2. Manejo de errores**
Nunca exponer errores internos:

❌ Incorrecto:
```
return NextResponse.json({ error: err.message });
```

✔ Correcto:
```
return NextResponse.error();
```

### **2.3. Respuestas controladas**
Nunca devolver:

- stack traces  
- datos internos del organismo  
- información sensible  
- colecciones completas sin filtros  

---

# 3. Seguridad en Modelos y Base de Datos

### **3.1. Modelos Mongoose**
Todos los modelos deben incluir:

- validación de esquema  
- timestamps  
- índices cuando sea necesario  
- restricciones de unicidad si aplica  

### **3.2. Operaciones atómicas**
Las actualizaciones del organismo deben ser:

- transaccionales  
- consistentes  
- revertibles  

### **3.3. No exponer IDs internos**
Nunca devolver `_id` si no es necesario.

---

# 4. Seguridad en Gestos

Los gestos son la entrada principal del organismo, por lo que requieren protección especial.

### **4.1. Validación de tipo**
Los tipos válidos viven en:

```
types/Gesture.ts
```

### **4.2. Prevención de spam**
Cada gesto debe pasar por:

- límites diarios  
- límites por wallet  
- validación de repetición  
- control de frecuencia  

### **4.3. Logs obligatorios**
Cada gesto genera un log en:

```
models/Log.ts
```

---

# 5. Seguridad en Puntos

### **5.1. Cálculo server-side**
Nunca calcular puntos en el frontend.

### **5.2. Reglas centralizadas**
Las reglas viven en:

```
app/api/points
```

### **5.3. Prevención de manipulación**
- no aceptar puntos enviados por el cliente  
- no permitir sobrescritura manual  

---

# 6. Seguridad en Organismo Global

El Organismo Global es el núcleo del sistema.

### **6.1. Acceso restringido**
Solo endpoints internos pueden modificarlo.

### **6.2. Validación estricta**
Cada actualización debe:

- validar campos  
- evitar estados inválidos  
- mantener consistencia con otros órganos  

### **6.3. Sincronización**
Cambios en:

- gestos  
- puntos  
- semillas  
- energía  

deben reflejarse correctamente.

---

# 7. Seguridad en DevWeb3

DevWeb3 es un panel interno, pero aun así requiere protección.

### **7.1. No exponer datos sensibles**
- claves  
- tokens  
- secretos  
- configuraciones internas  

### **7.2. No permitir acciones destructivas**
El panel no debe permitir:

- borrar colecciones  
- resetear organismo  
- manipular puntos manualmente  

### **7.3. Sandbox aislado**
El sandbox debe:

- limitar operaciones  
- no permitir escritura directa  
- no exponer endpoints privados  

---

# 8. Seguridad en Autenticación

### **8.1. NextAuth**
El sistema usa autenticación basada en:

- wallets  
- firmas  
- sesiones seguras  

### **8.2. Protección de rutas**
Rutas internas deben requerir sesión válida.

---

# 9. Seguridad en Producción

### **9.1. Variables de entorno**
Nunca subir:

- `.env.local`  
- claves privadas  
- URIs sensibles  

### **9.2. Logs**
Los logs de producción deben:

- anonimizar wallets si es necesario  
- no incluir datos sensibles  

### **9.3. Monitoreo**
El organismo debe monitorear:

- frecuencia de gestos  
- anomalías en puntos  
- actividad sospechosa  

---

# 10. Reporte de Vulnerabilidades

Si encuentras un problema de seguridad:

1. No lo publiques.  
2. Notifica al arquitecto del organismo.  
3. Proporciona pasos para reproducirlo.  
4. Espera confirmación antes de aplicar un fix.  

---

# 11. Licencia

Proyecto interno.  
Acceso restringido.  
No se permite distribución externa.