0f6387ab46
- renombrar openspec/ a _openspec/ (carpeta auxiliar) - mover specs de features a changes/ - crear specs base: arquitectura-limpia, estandares-codigo, nomenclatura - migrar _planificacion/ con design-system y roi-theme-template - agregar especificacion recaptcha anti-spam (proposal, tasks, spec) - corregir rutas y referencias en todas las specs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
112 lines
3.9 KiB
Markdown
112 lines
3.9 KiB
Markdown
# Proposal: reCAPTCHA v3 Anti-Spam Protection
|
|
|
|
## Problema
|
|
|
|
Los formularios del sitio (Newsletter Footer y Contact Form) carecen de protección CAPTCHA, haciéndolos vulnerables a spam automatizado. Actualmente solo cuentan con:
|
|
- Nonce de WordPress
|
|
- Rate limiting básico
|
|
- Sanitización de inputs
|
|
- Validación de email
|
|
|
|
## Solución Propuesta
|
|
|
|
Implementar **Google reCAPTCHA v3** como capa adicional de protección anti-spam.
|
|
|
|
### Por qué reCAPTCHA v3
|
|
|
|
| Característica | reCAPTCHA v2 | reCAPTCHA v3 |
|
|
|----------------|--------------|--------------|
|
|
| UX | Requiere interacción (checkbox/imágenes) | Invisible, sin fricción |
|
|
| Detección | Binaria (humano/bot) | Score 0.0-1.0 |
|
|
| Flexibilidad | Fija | Configurable por score |
|
|
| Impacto en conversión | Negativo | Mínimo |
|
|
|
|
### Credenciales
|
|
|
|
```
|
|
Site Key: 6LevZUQsAAAAAB6wcQ4iE6ckaTwgVR_ScBL3vqSj
|
|
```
|
|
|
|
> **Nota**: El Secret Key debe almacenarse en wp-config.php o como opción encriptada en BD, NUNCA en código fuente.
|
|
|
|
## Arquitectura Propuesta
|
|
|
|
```
|
|
Shared/
|
|
├── Domain/
|
|
│ └── Contracts/
|
|
│ └── RecaptchaValidatorInterface.php
|
|
├── Application/
|
|
│ └── Services/
|
|
│ └── RecaptchaValidationService.php
|
|
└── Infrastructure/
|
|
└── Services/
|
|
└── GoogleRecaptchaValidator.php
|
|
```
|
|
|
|
### Flujo de Validación
|
|
|
|
```
|
|
1. Frontend: Usuario envía formulario
|
|
2. Frontend: reCAPTCHA genera token automáticamente
|
|
3. Backend: AjaxHandler recibe token con datos del form
|
|
4. Backend: RecaptchaValidationService valida token con API de Google
|
|
5. Backend: Si score < threshold → rechazar como spam
|
|
6. Backend: Si score >= threshold → procesar formulario normalmente
|
|
```
|
|
|
|
## Formularios Afectados
|
|
|
|
1. **Newsletter Footer** (`Public/Footer/Infrastructure/Api/WordPress/NewsletterAjaxHandler.php`)
|
|
2. **Contact Form** (`Public/ContactForm/Infrastructure/Api/WordPress/ContactFormAjaxHandler.php`)
|
|
|
|
## Configuración Administrable
|
|
|
|
| Campo | Tipo | Default | Descripción |
|
|
|-------|------|---------|-------------|
|
|
| is_enabled | boolean | true | Habilitar/deshabilitar reCAPTCHA |
|
|
| site_key | text | - | Clave pública de reCAPTCHA |
|
|
| secret_key | text | - | Clave secreta (encriptada) |
|
|
| score_threshold | select | 0.5 | Umbral mínimo (0.3, 0.5, 0.7, 0.9) |
|
|
| action_newsletter | text | newsletter_submit | Acción para newsletter |
|
|
| action_contact | text | contact_submit | Acción para contacto |
|
|
|
|
## Impacto
|
|
|
|
### Archivos a Crear
|
|
- `Shared/Domain/Contracts/RecaptchaValidatorInterface.php`
|
|
- `Shared/Domain/Entities/RecaptchaResult.php`
|
|
- `Shared/Application/Services/RecaptchaValidationService.php`
|
|
- `Shared/Infrastructure/Services/GoogleRecaptchaValidator.php`
|
|
- `Schemas/recaptcha-settings.json`
|
|
- `Admin/RecaptchaSettings/Infrastructure/Ui/RecaptchaSettingsFormBuilder.php`
|
|
- `Admin/RecaptchaSettings/Infrastructure/FieldMapping/RecaptchaSettingsFieldMapper.php`
|
|
|
|
### Archivos a Modificar
|
|
- `Public/Footer/Infrastructure/Api/WordPress/NewsletterAjaxHandler.php`
|
|
- `Public/ContactForm/Infrastructure/Api/WordPress/ContactFormAjaxHandler.php`
|
|
- `Public/Footer/Infrastructure/Ui/FooterRenderer.php` (agregar script reCAPTCHA)
|
|
- `Public/ContactForm/Infrastructure/Ui/ContactFormRenderer.php` (agregar script reCAPTCHA)
|
|
- `functions.php` (registrar servicios en contenedor DI)
|
|
- `Admin/Infrastructure/Ui/AdminDashboardRenderer.php` (registrar tab de reCAPTCHA)
|
|
|
|
## Riesgos y Mitigaciones
|
|
|
|
| Riesgo | Probabilidad | Mitigación |
|
|
|--------|--------------|------------|
|
|
| API Google no disponible | Baja | Fallback: permitir envío (fail-open) |
|
|
| Falsos positivos | Media | Score threshold configurable |
|
|
| Latencia adicional | Baja | Validación asíncrona, timeout corto |
|
|
|
|
## Criterios de Aceptación
|
|
|
|
1. reCAPTCHA v3 integrado en ambos formularios
|
|
2. Score threshold configurable desde admin
|
|
3. Logging de intentos bloqueados
|
|
4. Sin impacto visible en UX del usuario
|
|
5. Fallback funcional si API falla
|
|
|
|
## Última actualización
|
|
|
|
2025-01-08
|