a2host/AGENTS.md

183 lines
8.2 KiB
Markdown

# AGENTS.md — Protocolo Operativo y Arquitectura de a2host
Guía para agentes de IA que trabajan en este repositorio. El documento rector de requerimientos del sistema se encuentra en [`a2host.md`](a2host.md). Consultarlo ante cualquier duda sobre el alcance funcional.
---
## Snapshot del Proyecto & Restricciones de Hardware
- **Propósito:** Panel web ligero para gestionar dinámicamente subdominios de `elingejose.com` en Apache2 sobre un VPS Ubuntu.
- **Límite Crítico de Memoria:** El VPS tiene solo **1 GB de RAM**. El panel corre bajo PM2 con tope estricto de memoria (`max_memory_restart: '120M'`) en el puerto `3005`.
- **Prohibición de Procesos Pesados:** Prohibido usar Docker, Nginx, frameworks SSR pesados (Next.js/Nuxt) o compiladores en caliente (`ts-node`) en producción. Frontend servido estáticamente (HTML/CSS/JS o Tailwind CDN sin build pesado).
- **Servidor Web:** Apache2 nativo (`/etc/apache2/sites-available/` y `/etc/apache2/sites-enabled/`). Módulos activos requeridos: `proxy`, `proxy_http`, `rewrite`, `headers`.
- **DNS:** Ya existe wildcard `*.elingejose.com` apuntando a la IP del VPS (`201.32.134.58`). El backend gestiona únicamente el filesystem local y la configuración de Apache2.
- **Usuarios del Sistema:** Proceso Node/PM2 corre bajo usuario `ggc` (con `sudo` sin contraseña en `/etc/sudoers.d/ggc`). Apache2 corre bajo `www-data:www-data`.
---
## Divergencia Crítica: Entorno Local vs VPS
- ⚠️ **La máquina de desarrollo local (laptop) NO tiene instalado Apache2.**
- Si el código invoca `sudo a2ensite` o `sudo apache2ctl` directamente sin abstracción, los tests y la ejecución local fallarán de inmediato.
- **Arquitectura de Drivers Requerida:** Todo acceso a Apache y sistema de archivos debe encapsularse en un servicio (ej. `ApacheService` / `SystemManager`) que admita modo simulado (`MOCK_APACHE=true` o cuando no exista binario `apache2ctl`).
- En modo mock:
- Rutas redirigidas a `./.tmp/apache2/sites-available/` y `./.tmp/apache2/sites-enabled/`.
- Raíz web redirigida a `./.tmp/www/`.
- Comandos `a2ensite`, `a2dissite`, `apache2ctl` y `systemctl reload` simulados mediante manipulación de symlinks y validación sintáctica básica en memoria/disco.
---
## Comandos Clave
| Tarea | Comando |
| --- | --- |
| Instalar dependencias | `npm install` |
| Dev server local (modo mock) | `MOCK_APACHE=true npm run dev` (o `npm start`) |
| Correr suite de tests | `npm test` (pruebas con runner nativo `node --test` o Vitest/Jest ligero) |
| Test unitario individual | `npm test -- --grep "SubdomainValidation"` (o equivalente del runner) |
| Lint / Validación estática | `npm run lint` |
| Arranque en producción (VPS) | `pm2 start ecosystem.config.js --env production` |
| Guardar estado PM2 | `pm2 save` |
| Monitorizar recursos en VPS | `pm2 monit` o `pm2 logs a2host` |
Flujo habitual de verificación antes de finalizar cambios: `npm test` → `npm run lint` (debe pasar al 100% sin requerir `sudo` ni binarios de Apache en local).
---
## Reglas de Arquitectura y Modos de Subdominio
### 1. Validación Estricta de Entrada (Anti-Inyección)
- **Regex de subdominio:** Exclusivamente `^[a-z0-9-]+$` (máximo 63 caracteres). Prohibido aceptar caracteres especiales, barras o espacios para evitar command injection y path traversal.
- **Ejecución de procesos:** Usar siempre `child_process.execFile` o `child_process.spawn` con arrays de argumentos (`['a2ensite', `${subdomain}.conf`]`). **PROHIBIDO** concatenar cadenas con `child_process.exec()`.
### 2. Modo A — Proyecto Web Estático / PHP (Carpeta)
- **Directorio:** `/var/www/<subdominio>`
- **Archivo inicial:** Generar `/var/www/<subdominio>/index.html` de bienvenida si no existe.
- **Permisos requeridos (Mandatorio SGID `2`):**
- `sudo chown -R ggc:www-data /var/www/<subdominio>`
- `sudo chmod -R 2775 /var/www/<subdominio>`
*(El bit `2775` asegura que nuevos ficheros creados por `ggc` vía Git/SFTP hereden el grupo `www-data` para que Apache pueda leerlos sin usar sudo).*
- **VirtualHost canónico (`/etc/apache2/sites-available/<subdominio>.conf`):**
- `<VirtualHost *:80>`
- `ServerName <subdominio>.elingejose.com`
- `DocumentRoot /var/www/<subdominio>`
- `<Directory /var/www/<subdominio>>`: `Options -Indexes +FollowSymLinks`, `AllowOverride All`, `Require all granted`.
### 3. Modo B — Proxy Inverso por Puerto (Node.js, Python, etc.)
- **Rango de puerto válido:** `1024 - 65535`.
- **Puertos Reservados (Bloqueo Estricto):** `[22, 80, 443, 3000, 3005, 3306, 5101, 5432]` (incluye Gitea en 3000 y el propio panel en 3005). Tampoco puede reutilizar un puerto ya asignado en otro VirtualHost activo.
- **VirtualHost canónico (`/etc/apache2/sites-available/<subdominio>.conf`):**
- `<VirtualHost *:80>`
- `ServerName <subdominio>.elingejose.com`
- `ProxyPreserveHost On`
- `AllowEncodedSlashes NoDecode`
- `ProxyPass / http://127.0.0.1:<puerto>/ nocanon`
- `ProxyPassReverse / http://127.0.0.1:<puerto>/`
*(Nota: Usar siempre `127.0.0.1`, nunca `localhost`, para evitar retrasos de resolución IPv6).*
### 4. Protocolo de Validación y Rollback Atómico
Al crear o modificar cualquier subdominio:
1. Escribir `/etc/apache2/sites-available/<subdominio>.conf`.
2. Habilitar sitio: `sudo a2ensite <subdominio>.conf`.
3. Validar sintaxis global: `sudo apache2ctl configtest`.
4. **Si `configtest` falla:**
- Ejecutar rollback inmediato: `sudo a2dissite <subdominio>.conf` y eliminar el archivo `.conf`.
- Si fue Modo A recién creado, limpiar `/var/www/<subdominio>`.
- **NUNCA ejecutar `reload` si la sintaxis no es correcta.**
- Devolver HTTP 422 con el error exacto retornado por Apache.
5. **Si `configtest` devuelve `Syntax OK`:**
- Ejecutar `sudo systemctl reload apache2`.
- Devolver HTTP 201 / respuesta exitosa.
### 5. Sitios Protegidos e Inmutabilidad
- **Sitios protegidos:** `000-default.conf`, `default-ssl.conf`, `git.conf` (definidos en `PROTECTED_SITES`).
- La API debe rechazar con `403 Forbidden` cualquier intento de desactivar, editar o eliminar estos archivos.
### 6. Eliminación Segura
- Deshabilitar (`sudo a2dissite <subdominio>.conf`), borrar `.conf` y recargar Apache (`sudo systemctl reload apache2`).
- El borrado físico de `/var/www/<subdominio>` solo se ejecuta si el usuario marca explícitamente un checkbox (`deleteFiles: true`). Si es `false`, la carpeta física se preserva intacta.
---
## Configuración y Variables de Entorno (`.env`)
Variables obligatorias a documentar en `.env.example`:
```ini
# Red y Proceso
PORT=3005
NODE_ENV=development
BASE_DOMAIN=elingejose.com
# Rutas del Sistema
WEB_ROOT=/var/www
APACHE_SITES_AVAILABLE=/etc/apache2/sites-available
APACHE_SITES_ENABLED=/etc/apache2/sites-enabled
SYSTEM_USER=ggc
# Autenticación Básica del Panel
ADMIN_USER=admin
ADMIN_PASS=cambiar_password_segura
SESSION_SECRET=minimo_32_caracteres_aleatorios_para_cookies_o_jwt
# Restricciones
PROTECTED_SITES=000-default.conf,default-ssl.conf,git.conf
RESERVED_PORTS=22,80,443,3000,3005,3306,5101,5432
# Modo de Operación
MOCK_APACHE=false
```
---
## Configuración PM2 (`ecosystem.config.js`)
```javascript
module.exports = {
apps: [{
name: 'a2host',
script: './src/index.js',
instances: 1,
autorestart: true,
watch: false,
max_memory_restart: '120M',
env_production: {
NODE_ENV: 'production',
PORT: 3005,
MOCK_APACHE: 'false'
}
}]
};
```
---
## VirtualHost del Panel (`panel.elingejose.com`)
Plantilla de Apache para exponer la aplicación:
```apache
<VirtualHost *:80>
ServerName panel.elingejose.com
ProxyPreserveHost On
AllowEncodedSlashes NoDecode
ProxyPass / http://127.0.0.1:3005/ nocanon
ProxyPassReverse / http://127.0.0.1:3005/
ErrorLog ${APACHE_LOG_DIR}/panel_error.log
CustomLog ${APACHE_LOG_DIR}/panel_access.log combined
</VirtualHost>
```
---
## Recursos y Skills en el Repositorio
- Skills especializadas disponibles en `.agents/skills/`:
- `scrum-multi-agent-orchestration`: Orquestación y contratos entre agentes.
- `security-audit` / `web-security-testing`: Auditoría de inyecciones y validaciones.
- `modern-ui-design-system` / `responsive-mobile-first`: Pautas visuales y accesibilidad.
- No modificar directamente carpetas bajo `.agents/skills/` salvo instrucción explícita del usuario.