Testing Alpha

docs/Helpers/security-logger-helper-guide.md

@@ -0,0 +1,120 @@
+# Koneko Security Logger Helper Guide
+
+> ⚖️ Auditoría de eventos de seguridad en tiempo real y bajo demanda.
+
+El logger `log_security()` forma parte de la infraestructura central de seguridad de Koneko Vuexy Admin y te permite registrar eventos sensibles como accesos, fallos de login, intentos sospechosos, detecciones de VPN, entre otros.
+
+---
+
+## ✨ Ventajas
+
+* No requiere instanciar clases.
+* Autoobtiene `Request`, `IP`, `UserAgent`, `Geolocalización`, etc.
+* Flexible para ejecutarse desde controladores, middleware, jobs o Livewire.
+* Compatible con `SecurityEvent` (modelo auditado).
+* Almacena contexto extendido con `payload`, `is_proxy`, `user_id`, etc.
+
+---
+
+## ✨ Uso básico
+
+```php
+log_security('login_failed');
+```
+
+Esto registra un fallo de login con todos los metadatos de seguridad: IP, ciudad, dispositivo, agente, URL y más.
+
+---
+
+## ⚖️ Sintaxis Completa
+
+```php
+log_security(
+    string $type,                    // Tipo de evento (ej: login_failed, login_success)
+    ?Request $request = null,        // Puede inyectarse manualmente
+    ?int $userId = null,             // Usuario relacionado (opcional)
+    array $payload = [],             // Datos adicionales como intentos, cabeceras, etc.
+    bool $isProxy = false            // ¿Fue detectado uso de proxy/VPN?
+);
+```
+
+Ejemplo completo:
+
+```php
+log_security(
+    'login_failed',
+    request(),
+    $user?->id,
+    ['intentos' => 3, 'via' => 'formulario'],
+    detectaVpnProxy(request()->ip())
+);
+```
+
+---
+
+## 🔍 Eventos soportados por defecto
+
+Puedes definirlos como constantes estáticas en tu código:
+
+```php
+SecurityEvent::EVENT_LOGIN_FAILED
+SecurityEvent::EVENT_LOGIN_SUCCESS
+```
+
+O usar strings arbitrarios con sentido:
+
+```php
+'password_reset_attempt'
+'blocked_login_from_blacklist'
+'csrf_token_fail'
+'geolocation_warning'
+```
+
+---
+
+## ⌚ Modelo generado: `SecurityEvent`
+
+El evento registrado se almacena en la tabla `security_events`, con campos como:
+
+* `ip_address`
+* `user_id`
+* `event_type`
+* `payload`
+* `region`, `city`, `country`
+* `is_proxy`, `device_type`, etc.
+
+---
+
+## 🌐 Geolocalización Automática
+
+Si tienes habilitado el trait `HasGeolocation`, el sistema hace *GeoIP Lookup* por IP:
+
+```php
+use Koneko\VuexyAdmin\Support\Traits\Helpers\HasGeolocation;
+```
+
+---
+
+## 🔐 Buenas prácticas
+
+* Usa tipos semánticos: `login_success`, `vpn_blocked`, `csrf_fail`, etc.
+* Agrega contexto extra en `payload` para debugging posterior.
+* Detecta IPs sospechosas con `isProxy` (ideal para usar junto con sistemas de listas negras).
+
+---
+
+## ✨ Extras
+
+Puedes extender la lógica de logging desde:
+
+```php
+Koneko\VuexyAdmin\Support\Logger\KonekoSecurityLogger
+```
+
+Este servicio puede adaptarse o sustituirse por otro para logs distribuidos o externos (ej: Sentry, Elastic, etc).
+
+---
+
+## ✅ Conclusión
+
+El helper `log_security()` es una herramienta robusta, flexible y elegante para capturar eventos sensibles en tu ERP. Evita trabajar directamente con el modelo, mantén la consistencia de tu registro, y delega la trazabilidad a una capa preparada para el contexto empresarial.