@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/php/hooks.md

@@ -0,0 +1,165 @@
+# Regla: Hooks de Pre-commit y CI — PHP / Laravel
+
+Los hooks automatizan la detección de errores antes de que lleguen al repositorio.
+Esta regla define qué verificaciones correr en qué momento y qué debe bloquear
+el commit o el merge.
+
+---
+
+## PHP-CS-Fixer / Pint — verificación de formato
+
+Ejecutar antes de cada commit como verificación sin modificar:
+
+```bash
+# Laravel Pint
+./vendor/bin/pint --test
+
+# PHP-CS-Fixer
+./vendor/bin/php-cs-fixer fix --dry-run --diff
+```
+
+- Si produce diferencias: **bloquear el commit**.
+- El desarrollador aplica el fix y vuelve a commitear:
+  ```bash
+  ./vendor/bin/pint     # aplica correcciones
+  git add -u && git commit
+  ```
+- CI también lo ejecuta como verificación. No se auto-corrige en CI.
+
+---
+
+## PHPStan — análisis estático antes de merge
+
+```bash
+./vendor/bin/phpstan analyse --level=6 app/ --error-format=github
+```
+
+- Ejecutar en CI en cada push a una rama con PR abierto.
+- Bloquear el merge si hay errores de nivel 6 o superior.
+- Los warnings se tratan como errores: `--no-progress --error-format=github`.
+- El flag `--error-format=github` genera anotaciones en la UI de GitHub Actions.
+
+---
+
+## Detección de debug output en código no-test
+
+Detectar `var_dump`, `dd`, `dump`, `print_r`, `var_export` fuera de `tests/`:
+
+```bash
+# En hook pre-commit o CI
+git diff --cached --name-only | grep '\.php$' | xargs grep -n \
+  '\bvar_dump\b\|\bdd\b\|\bdump\b\|\bprint_r\b\|\bvar_export\b' \
+  2>/dev/null | grep -v '^tests/' | grep -v '^vendor/'
+```
+
+Si encuentra coincidencias en código fuera de `tests/`: **bloquear el commit**.
+Los desarrolladores deben eliminar el debug output antes de commitear.
+
+---
+
+## Detección de env() fuera de config/
+
+En Laravel, llamar `env()` directamente en código de aplicación (fuera de `config/`)
+rompe el caché de configuración (`php artisan config:cache`):
+
+```bash
+# Detectar env() fuera de config/
+grep -rn "env(" app/ bootstrap/ routes/ 2>/dev/null \
+  | grep -v "config(" \
+  | grep -v "^.*#"
+```
+
+- Si encuentra `env()` en `app/` o `routes/`: **bloquear el merge** con mensaje:
+  "Usar `config('seccion.clave')` en lugar de `env()` fuera de `config/`."
+
+---
+
+## composer audit — vulnerabilidades en dependencias
+
+```bash
+composer audit --no-dev --format=json
+```
+
+- Ejecutar en CI en cada push.
+- Bloquear el merge si reporta vulnerabilidades de severidad **HIGH** o **CRITICAL**.
+- Vulnerabilidades **MEDIUM** generan warning pero no bloquean (registrar en JIRA).
+- Ejecutar también semanalmente de forma programada para detectar CVEs nuevos
+  en dependencias que no cambiaron recientemente.
+
+---
+
+## Verificación de rutas con artisan
+
+En CI, después de cada cambio en `routes/`:
+
+```bash
+php artisan route:list --json > /dev/null
+```
+
+- Si falla: hay una ruta con controller o middleware inexistente. **Bloquear el merge**.
+- Verificación adicional que el middleware de autenticación está presente en rutas de API:
+
+```bash
+php artisan route:list --path=api --columns=method,uri,middleware \
+  | grep -v "api/auth" \
+  | grep -v "sanctum\|auth"
+```
+
+Cualquier ruta de API sin middleware de autenticación es una alerta que debe
+revisarse manualmente antes de aprobar el PR.
+
+---
+
+## Script de pre-commit completo (referencia)
+
+Guardar como `.git/hooks/pre-commit` o con `husky`/`captain-hook`:
+
+```bash
+#!/usr/bin/env bash
+set -e
+
+echo "==> Verificando formato (Pint)..."
+./vendor/bin/pint --test || {
+  echo "ERROR: Hay errores de formato. Ejecuta ./vendor/bin/pint para corregir."
+  exit 1
+}
+
+echo "==> Detectando debug output..."
+ARCHIVOS_PHP=$(git diff --cached --name-only | grep '\.php$' | grep -v '^tests/' || true)
+if [ -n "$ARCHIVOS_PHP" ]; then
+  if echo "$ARCHIVOS_PHP" | xargs grep -ln '\bvar_dump\b\|\bdd(\b\|\bdump(\b' 2>/dev/null; then
+    echo "ERROR: Eliminar var_dump/dd/dump antes de commitear."
+    exit 1
+  fi
+fi
+
+echo "==> Verificando env() fuera de config/..."
+if grep -rn "env(" app/ routes/ 2>/dev/null | grep -qv "config("; then
+  echo "ADVERTENCIA: Se encontró env() fuera de config/. Verificar manualmente."
+fi
+
+echo "==> Pre-commit: OK"
+```
+
+---
+
+## Resumen de qué bloquea qué
+
+| Verificación | Pre-commit | CI / PR | Severidad |
+|-------------|-----------|---------|-----------|
+| Formato (Pint) | Bloquea | Bloquea | Error |
+| PHPStan nivel 6 | No | Bloquea merge | Error |
+| var_dump / dd / dump | Bloquea | Bloquea | Error |
+| `env()` fuera de config/ | Advertencia | Bloquea merge | Error |
+| `composer audit` HIGH/CRITICAL | No | Bloquea merge | Error |
+| Rutas inválidas | No | Bloquea merge | Error |
+
+---
+
+## Checklist de hooks antes de activar en un proyecto nuevo
+
+- [ ] `pint.json` o `.php-cs-fixer.php` versionado en el repositorio
+- [ ] `phpstan.neon` con nivel 6 versionado
+- [ ] Hook pre-commit instalado (`./vendor/bin/captain-hook install` o `husky`)
+- [ ] Pipeline de CI tiene los pasos: pint, phpstan, audit, route:list
+- [ ] El equipo conoce cómo ejecutar cada verificación localmente

package/reglas/lenguajes/php/patrones.md

@@ -0,0 +1,233 @@
+# Regla: Patrones de Arquitectura — PHP / Laravel
+
+Aplica a todo código PHP en proyectos Laravel. Estos patrones separan las
+responsabilidades entre capas, facilitan el testing y reducen el acoplamiento.
+Un controller gordo que contiene lógica de negocio y queries es deuda técnica
+inmediata — esta regla establece cómo evitarla.
+
+---
+
+## Service Container y Dependency Injection
+
+- Registrar toda clase de negocio en el Service Container de Laravel.
+- Inyectar dependencias por constructor, nunca instanciarlas dentro de la clase.
+- Bind interfaces a implementaciones concretas en `AppServiceProvider`:
+
+```php
+// AppServiceProvider::register()
+$this->app->bind(FacturaRepositoryInterface::class, EloquentFacturaRepository::class);
+```
+
+- En producción, usar `$this->app->singleton()` para servicios sin estado.
+
+---
+
+## Facades: con criterio
+
+- Las Facades de Laravel son cómodas pero dificultan el testing cuando se usan
+  en lógica de negocio profunda.
+- Facades **aceptables** en controllers y middleware (capa de entrada):
+  `Auth::user()`, `Cache::get()`, `Log::error()`.
+- Facades **prohibidas** en Services, Repositories y Jobs: inyectar la interfaz
+  correspondiente para que sea mockeable en tests.
+
+```php
+// MAL — Facade en service, imposible de testear sin mock estático
+class FacturaService
+{
+    public function emitir(int $facturaId): void
+    {
+        $factura = Factura::find($facturaId); // Facade implícita de Eloquent
+        Mail::send(...);                       // Facade de Mail no inyectada
+    }
+}
+
+// BIEN — dependencias inyectadas
+class FacturaService
+{
+    public function __construct(
+        private readonly FacturaRepositoryInterface $facturas,
+        private readonly MailerInterface $mailer,
+    ) {}
+
+    public function emitir(int $facturaId): void
+    {
+        $factura = $this->facturas->findOrFail($facturaId);
+        $this->mailer->enviarFactura($factura);
+    }
+}
+```
+
+---
+
+## Repository Pattern sobre Eloquent directo en controllers
+
+- Los controllers no deben contener queries Eloquent.
+- Definir una interfaz del repositorio y una implementación Eloquent:
+
+```php
+// Interfaz
+interface FacturaRepositoryInterface
+{
+    public function findOrFail(int $id): Factura;
+    /** @return Collection<int, Factura> */
+    public function listarPorEmpresa(int $empresaId, EstatusFactura $estatus): Collection;
+}
+
+// Implementación
+class EloquentFacturaRepository implements FacturaRepositoryInterface
+{
+    public function findOrFail(int $id): Factura
+    {
+        return Factura::with(['items', 'cliente'])->findOrFail($id);
+    }
+
+    public function listarPorEmpresa(int $empresaId, EstatusFactura $estatus): Collection
+    {
+        return Factura::where('empresa_id', $empresaId)
+            ->where('estatus', $estatus)
+            ->with('cliente')
+            ->orderByDesc('fecha_emision')
+            ->get();
+    }
+}
+```
+
+---
+
+## Form Requests para validación
+
+- Toda validación de entrada HTTP va en una clase `FormRequest`, nunca en el controller.
+- Las reglas de autorización también van en el `FormRequest`:
+
+```php
+class EmitirFacturaRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()->can('emitir-facturas');
+    }
+
+    public function rules(): array
+    {
+        return [
+            'cliente_id'  => ['required', 'integer', 'exists:clientes,id'],
+            'items'       => ['required', 'array', 'min:1'],
+            'items.*.sku' => ['required', 'string', 'max:50'],
+            'items.*.qty' => ['required', 'integer', 'min:1'],
+        ];
+    }
+}
+```
+
+---
+
+## Events y Listeners para desacoplamiento
+
+- Acciones con efectos secundarios múltiples (enviar email, actualizar reporte,
+  notificar terceros) se publican como eventos, no se llaman directamente:
+
+```php
+// En el service — solo dispara el evento
+event(new FacturaEmitida($factura));
+
+// Listeners separados, registrados en EventServiceProvider
+FacturaEmitida::class => [
+    EnviarEmailFacturaListener::class,
+    GenerarPdfFacturaListener::class,
+    NotificarSatListener::class,
+],
+```
+
+---
+
+## Jobs y Queues para procesamiento asíncrono
+
+- Todo proceso que tarde más de 500ms o que pueda fallar y reintentarse va en un Job:
+
+```php
+class GenerarReporteFacturacionJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries = 3;
+    public int $backoff = 60; // segundos entre reintentos
+
+    public function __construct(private readonly int $empresaId) {}
+
+    public function handle(ReporteService $reportes): void
+    {
+        $reportes->generarFacturacionMensual($this->empresaId);
+    }
+}
+
+// Despachar desde el controller
+GenerarReporteFacturacionJob::dispatch($empresaId)->onQueue('reportes');
+```
+
+---
+
+## Policies para autorización
+
+- Las reglas de quién puede hacer qué sobre un modelo van en una Policy, no en el controller:
+
+```php
+class FacturaPolicy
+{
+    public function cancelar(User $user, Factura $factura): bool
+    {
+        return $user->empresa_id === $factura->empresa_id
+            && $user->hasRole('admin')
+            && ! $factura->estatus->esTerminal();
+    }
+}
+
+// En el controller
+$this->authorize('cancelar', $factura);
+```
+
+---
+
+## API Resources para transformación de respuestas
+
+- NUNCA devolver modelos Eloquent directamente en respuestas JSON.
+  Un `->toArray()` de Eloquent expone todos los campos incluyendo timestamps internos.
+- Usar `JsonResource` para controlar exactamente qué se expone:
+
+```php
+class FacturaResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id'            => $this->id,
+            'folio'         => $this->folio,
+            'total'         => $this->total,
+            'estatus'       => $this->estatus,
+            'fecha_emision' => $this->fecha_emision->toISOString(),
+            'cliente'       => new ClienteResource($this->whenLoaded('cliente')),
+            'items'         => FacturaItemResource::collection($this->whenLoaded('items')),
+        ];
+    }
+}
+```
+
+---
+
+## Middleware para cross-cutting concerns
+
+- Lógica que aplica a múltiples rutas (autenticación, rate limiting, logging de auditoría,
+  verificación de suscripción) va en middleware, no en cada controller.
+- Nunca duplicar lógica de middleware dentro de métodos de controller.
+
+---
+
+## Checklist de patrones antes de merge
+
+- [ ] Ningun controller contiene queries Eloquent directas
+- [ ] Toda validación HTTP en FormRequest, no en controller
+- [ ] Efectos secundarios múltiples publicados como eventos
+- [ ] Procesos lentos o con reintentos en Jobs con `ShouldQueue`
+- [ ] Reglas de autorización en Policies, no en controllers ni services
+- [ ] Respuestas JSON devueltas con JsonResource, no con `->toArray()`
+- [ ] Interfaces definidas para repositorios y servicios externos

package/reglas/lenguajes/php/seguridad.md

@@ -0,0 +1,186 @@
+# Regla: Seguridad — PHP / Laravel
+
+PHP es históricamente el lenguaje con más vectores de ataque web documentados.
+Laravel mitiga la mayoría de ellos por defecto, pero solo si se usan sus
+mecanismos correctamente. Esta regla es OBLIGATORIA sin excepciones.
+
+---
+
+## SQL Injection: Eloquent y Query Builder siempre
+
+- NUNCA construir queries con interpolación de strings o concatenación:
+
+```php
+// MAL — vulnerable a SQL injection
+$facturas = DB::select("SELECT * FROM facturas WHERE empresa_id = $empresaId");
+
+// MAL — DB::raw sin binding
+$facturas = Factura::whereRaw("empresa_id = $empresaId")->get();
+
+// BIEN — Eloquent con binding automático
+$facturas = Factura::where('empresa_id', $empresaId)->get();
+
+// BIEN — DB::raw con bindings separados cuando es necesario
+$facturas = Factura::whereRaw('empresa_id = ? AND total > ?', [$empresaId, $minimo])->get();
+```
+
+- Cada aparición de `DB::statement(` o `DB::unprepared(` requiere revisión de seguridad
+  explícita con comentario documentando por qué es seguro.
+
+---
+
+## XSS: Blade escapa por defecto
+
+- `{{ $variable }}` en Blade escapa HTML automáticamente. Usar siempre.
+- `{!! $variable !!}` NO escapa. Prohibido salvo en casos específicos documentados:
+
+```blade
+{{-- MAL — XSS si $contenido viene del usuario --}}
+{!! $contenido !!}
+
+{{-- BIEN — escapado por defecto --}}
+{{ $contenido }}
+
+{{-- BIEN — HTML permitido solo de fuente confiable (CMS interno, no usuario) --}}
+{{-- NOTA: $plantilla proviene de CMS interno administrado por el equipo, no de input de usuario --}}
+{!! $plantilla->html_cuerpo !!}
+```
+
+- Si se necesita renderizar HTML de usuario (editor WYSIWYG), sanitizar con
+  `HTMLPurifier` o `League\HTMLToMarkdown` antes de almacenar, nunca al mostrar.
+
+---
+
+## CSRF: middleware activo en todas las rutas web
+
+- El middleware `VerifyCsrfToken` debe estar activo en el grupo `web`.
+- No agregar rutas a `$except` en `VerifyCsrfToken` sin documentar explícitamente por qué.
+- Las rutas de API que usan tokens de portador (Bearer) son inmunes a CSRF por diseño.
+  Documentar esto en el controller si se desactiva el middleware para esa ruta.
+
+---
+
+## Mass Assignment: $fillable en todos los modelos
+
+- Todo modelo Eloquent DEBE declarar `$fillable` o `$guarded`.
+- Preferir `$fillable` (lista de permitidos) sobre `$guarded` (lista de bloqueados).
+- NUNCA `protected $guarded = []` — permite asignación masiva sin restricción:
+
+```php
+// MAL — permite asignar cualquier campo incluyendo is_admin, empresa_id
+class Usuario extends Model
+{
+    protected $guarded = [];
+}
+
+// BIEN — solo los campos que el usuario puede enviar
+class Usuario extends Model
+{
+    protected $fillable = [
+        'nombre',
+        'email',
+        'password',
+    ];
+    // empresa_id, is_admin, etc. solo se asignan explícitamente en el service
+}
+```
+
+---
+
+## Autenticación: Laravel Sanctum o Passport
+
+- NUNCA implementar autenticación custom con hashing manual y generación de tokens.
+- APIs de primera parte (SPA, mobile): **Laravel Sanctum**.
+- OAuth2 para terceros: **Laravel Passport**.
+- Configuración mínima de Sanctum para seguridad:
+
+```php
+// config/sanctum.php
+'expiration' => 60 * 24,          // tokens expiran en 24 horas
+'token_prefix' => env('APP_ENV'), // prefijo diferente por ambiente
+```
+
+- Los tokens de refresh van en cookies `httpOnly`, nunca en `localStorage`.
+
+---
+
+## Secretos en .env, nunca en config/
+
+- Las credenciales se leen desde variables de entorno, nunca hardcodeadas:
+
+```php
+// MAL — credencial en código
+class StripeService
+{
+    private string $apiKey = 'sk_live_abc123...';
+}
+
+// MAL — en archivo de config versionado
+// config/servicios.php
+return ['stripe' => ['key' => 'sk_live_abc123...']];
+
+// BIEN — desde variable de entorno
+return ['stripe' => ['key' => env('STRIPE_SECRET_KEY')]];
+```
+
+- Ejecutar `php artisan config:cache` antes de deploy para que `.env` no sea
+  necesario en producción (las variables se inyectan por el sistema de deployment).
+
+---
+
+## PHPStan/Psalm en CI
+
+- Nivel mínimo de análisis estático: **nivel 6** (PHPStan) o **nivel 3** (Psalm).
+- Configurar en `phpstan.neon`:
+  ```yaml
+  parameters:
+    level: 6
+    paths:
+      - app
+    excludePaths:
+      - app/Http/Middleware/TrustProxies.php
+  ```
+- CI falla si PHPStan reporta errores. Los errores ignorados se documentan
+  con `// @phpstan-ignore-next-line` y comentario explicativo.
+
+---
+
+## Rate limiting en rutas de autenticación
+
+```php
+// routes/api.php
+Route::middleware('throttle:5,1')->group(function () {
+    Route::post('/login', [AuthController::class, 'login']);
+    Route::post('/registro', [AuthController::class, 'registrar']);
+    Route::post('/contrasena/recuperar', [AuthController::class, 'recuperarContrasena']);
+});
+```
+
+- Máximo 5 intentos por minuto por IP en rutas de autenticación.
+- Bloqueo temporal de 15 minutos al superar el límite.
+
+---
+
+## Headers de seguridad
+
+- Agregar middleware con headers de seguridad en el grupo `web` y `api`:
+
+```php
+// Middleware SecurityHeaders::handle()
+$response->headers->set('X-Frame-Options', 'DENY');
+$response->headers->set('X-Content-Type-Options', 'nosniff');
+$response->headers->set('Referrer-Policy', 'strict-origin-when-cross-origin');
+$response->headers->set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+```
+
+---
+
+## Checklist de seguridad antes de merge
+
+- [ ] Sin interpolación de strings en queries SQL
+- [ ] Sin `{!! !!}` en Blade sin comentario que justifique la fuente confiable
+- [ ] `$fillable` declarado en todos los modelos nuevos
+- [ ] Sin credenciales hardcodeadas (verificar con `git grep -rn "sk_live\|password.*=.*'[^']"`)
+- [ ] Rutas de auth con `throttle` configurado
+- [ ] PHPStan nivel 6 pasa sin errores en `app/`
+- [ ] `composer audit` sin vulnerabilidades HIGH o CRITICAL