Files

FrankZamora 0f6387ab46 refactor: reorganizar openspec y planificacion con spec recaptcha

- 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>

2026-01-08 15:30:45 -06:00

3.9 KiB

Raw Blame History

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

Newsletter Footer (Public/Footer/Infrastructure/Api/WordPress/NewsletterAjaxHandler.php)
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

reCAPTCHA v3 integrado en ambos formularios
Score threshold configurable desde admin
Logging de intentos bloqueados
Sin impacto visible en UX del usuario
Fallback funcional si API falla

Última actualización

2025-01-08

3.9 KiB Raw Blame History