@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/csharp/seguridad.md

@@ -0,0 +1,258 @@
+# Regla: Seguridad — C# / .NET
+
+ASP.NET Core tiene un buen punto de partida en seguridad, pero muchas de sus
+protecciones deben habilitarse explícitamente. Esta regla cubre las configuraciones
+obligatorias para que el punto de partida seguro sea la norma, no la excepción.
+
+---
+
+## OWASP Top 10 para .NET
+
+Antes de cerrar cualquier ticket que toque autenticación, autorización o datos,
+verificar que no se introduce ninguna vulnerabilidad del OWASP Top 10:
+
+- **Inyección (A03)**: EF Core usa parámetros por defecto — nunca interpolar variables
+  en `FromSqlRaw()` ni `ExecuteSqlRaw()`.
+- **Control de acceso roto (A01)**: `[Authorize]` en todos los controllers y endpoints
+  por defecto; `[AllowAnonymous]` explícito solo en los que lo requieren.
+- **Fallos criptográficos (A02)**: HTTPS obligatorio, datos sensibles cifrados en reposo
+  con `IDataProtectionProvider`, no con implementaciones propias.
+- **Componentes vulnerables (A06)**: `dotnet list package --vulnerable` en CI.
+- **Fallos de logging y monitoreo (A09)**: No loggear datos sensibles (passwords, tokens, PII).
+
+---
+
+## Entity Framework Core: queries parametrizadas por defecto
+
+EF Core parametriza automáticamente. Los errores ocurren cuando se sale de ese camino:
+
+```csharp
+// MAL — interpolación directa en SQL crudo, susceptible a inyección
+var email = userInput; // potencialmente malicioso
+var facturas = await _db.Facturas
+    .FromSqlRaw($"SELECT * FROM facturas WHERE email = '{email}'")
+    .ToListAsync();
+
+// MAL — aunque se use parámetro, la interpolación de C# no es SQL parameter
+var facturas = await _db.Database
+    .ExecuteSqlRawAsync($"DELETE FROM facturas WHERE id = {id}");
+
+// BIEN — FromSqlInterpolated usa parámetros seguros automáticamente
+var facturas = await _db.Facturas
+    .FromSqlInterpolated($"SELECT * FROM facturas WHERE email = {email}")
+    .ToListAsync();
+
+// BIEN — parámetro explícito con FromSqlRaw
+var facturas = await _db.Facturas
+    .FromSqlRaw("SELECT * FROM facturas WHERE email = {0}", email)
+    .ToListAsync();
+
+// MEJOR — LINQ con EF Core (parámetros automáticos siempre)
+var facturas = await _db.Facturas
+    .Where(f => f.ClienteEmail == email)
+    .ToListAsync();
+```
+
+- Regla simple: si hay interpolación de strings en SQL → es un bug de seguridad.
+- `FromSqlInterpolated` es la excepción segura cuando se necesita SQL crudo.
+
+---
+
+## ASP.NET Core: [Authorize] por defecto
+
+```csharp
+// Program.cs — política de autorización por defecto
+builder.Services.AddAuthorization(opts =>
+{
+    // Todo endpoint requiere autenticación por defecto
+    opts.FallbackPolicy = new AuthorizationPolicyBuilder()
+        .RequireAuthenticatedUser()
+        .Build();
+});
+
+// Los endpoints públicos deben marcarse EXPLÍCITAMENTE
+[AllowAnonymous]
+app.MapGet("/health", () => Results.Ok("healthy"));
+
+// Los endpoints con roles específicos
+[Authorize(Roles = "Admin,Facturador")]
+app.MapPost("/facturas", async (IMediator mediator) => { ... });
+```
+
+- El modelo por defecto es: todo requiere autenticación, lo público se declara explícitamente.
+- NUNCA depender de que los endpoints "no están en producción" para no protegerlos.
+- `[Authorize(Policy = "nombre")]` para autorización basada en policies (más flexible que roles).
+
+---
+
+## Anti-forgery tokens en formularios
+
+```csharp
+// En páginas Razor o controladores MVC
+// Program.cs — habilitado por defecto en Razor Pages
+builder.Services.AddRazorPages();
+// o con configuración explícita
+builder.Services.AddControllersWithViews(opts =>
+{
+    opts.Filters.Add(new AutoValidateAntiforgeryTokenAttribute());
+});
+```
+
+```html
+<!-- En el formulario Razor -->
+<form method="post">
+    @Html.AntiForgeryToken()
+    <!-- campos del formulario -->
+</form>
+```
+
+- APIs que usan JWT en el header `Authorization` son inmunes a CSRF por diseño —
+  documentar explícitamente en el controller que no se necesita CSRF protection y por qué:
+  ```csharp
+  [ApiController] // implica [ValidateAntiForgeryToken] deshabilitado para JSON APIs con JWT
+  [Route("api/[controller]")]
+  // CSRF no aplica: esta API usa JWT en Authorization header, no cookies
+  public class FacturasController : ControllerBase { ... }
+  ```
+
+---
+
+## User secrets para desarrollo local
+
+```bash
+# Inicializar user secrets en el proyecto
+dotnet user-secrets init
+
+# Agregar secreto para desarrollo
+dotnet user-secrets set "ConnectionStrings:Default" "Server=localhost;Database=dev;..."
+dotnet user-secrets set "Jwt:SecretKey" "clave-solo-para-desarrollo"
+```
+
+- User secrets nunca se versionan en git — se almacenan en `%APPDATA%/Microsoft/UserSecrets/`.
+- Solo para ambiente de desarrollo. En staging y producción: Azure Key Vault o AWS Secrets Manager.
+- El archivo `appsettings.Development.json` NUNCA contiene secretos reales — solo configuración
+  no sensible de desarrollo.
+
+---
+
+## Azure Key Vault / AWS Secrets Manager en producción
+
+```csharp
+// Program.cs — integración con Azure Key Vault
+if (builder.Environment.IsProduction())
+{
+    var keyVaultUri = new Uri(builder.Configuration["KeyVaultUri"]!);
+    builder.Configuration.AddAzureKeyVault(
+        keyVaultUri,
+        new DefaultAzureCredential()); // usa Managed Identity en Azure
+}
+```
+
+- `DefaultAzureCredential` usa Managed Identity automáticamente en Azure — sin API keys.
+- Las variables de entorno y configuración de producción NUNCA se almacenan en el repositorio.
+- Los secretos de Key Vault se cargan en el `IConfiguration` estándar — el código no cambia.
+
+---
+
+## No usar BinaryFormatter
+
+`BinaryFormatter` fue deprecado y tiene vulnerabilidades conocidas de ejecución
+remota de código (RCE) via deserialización maliciosa.
+
+```csharp
+// PROHIBIDO — BinaryFormatter puede ejecutar código arbitrario
+var formatter = new BinaryFormatter();
+objeto = (MiTipo)formatter.Deserialize(stream); // CVE-2022-34716 y otros
+
+// BIEN — alternativas seguras
+// Para datos internos estructurados:
+var json = JsonSerializer.Serialize(objeto);
+var restaurado = JsonSerializer.Deserialize<MiTipo>(json);
+
+// Para datos binarios de alto rendimiento:
+// MessagePack, protobuf-net (con tipos explícitos registrados)
+```
+
+- El compilador emite SYSLIB0011 cuando se usa `BinaryFormatter` — tratar como error.
+- Si se necesita serialización binaria: usar `System.Text.Json`, `MessagePack` o `ProtoBuf`.
+
+---
+
+## Content Security Policy headers
+
+```csharp
+// Program.cs — agregar headers de seguridad en todas las respuestas
+app.Use(async (context, next) =>
+{
+    context.Response.Headers.Append("X-Content-Type-Options", "nosniff");
+    context.Response.Headers.Append("X-Frame-Options", "DENY");
+    context.Response.Headers.Append("X-XSS-Protection", "1; mode=block");
+    context.Response.Headers.Append(
+        "Content-Security-Policy",
+        "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'");
+    context.Response.Headers.Append(
+        "Strict-Transport-Security",
+        "max-age=31536000; includeSubDomains");
+    await next();
+});
+```
+
+- Usar el paquete `NWebsec.AspNetCore.Middleware` para configuración más completa de CSP.
+- Ajustar la CSP según los recursos externos que la aplicación necesita cargar.
+- Probar la CSP con https://csp-evaluator.withgoogle.com/.
+
+---
+
+## Rate limiting con el middleware nativo de .NET 7+
+
+```csharp
+// Program.cs
+builder.Services.AddRateLimiter(opts =>
+{
+    // Límite global por IP
+    opts.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(
+        context => RateLimitPartition.GetFixedWindowLimiter(
+            context.Connection.RemoteIpAddress?.ToString() ?? "unknown",
+            _ => new FixedWindowRateLimiterOptions
+            {
+                PermitLimit = 100,
+                Window = TimeSpan.FromMinutes(1)
+            }));
+
+    // Límite estricto para endpoints de autenticación
+    opts.AddPolicy("autenticacion", context =>
+        RateLimitPartition.GetFixedWindowLimiter(
+            context.Connection.RemoteIpAddress?.ToString() ?? "unknown",
+            _ => new FixedWindowRateLimiterOptions
+            {
+                PermitLimit = 5,
+                Window = TimeSpan.FromMinutes(1)
+            }));
+
+    opts.OnRejected = async (context, ct) =>
+    {
+        context.HttpContext.Response.StatusCode = 429;
+        await context.HttpContext.Response.WriteAsync(
+            "Demasiadas solicitudes. Intenta de nuevo en un minuto.", ct);
+    };
+});
+
+app.UseRateLimiter();
+```
+
+- .NET 7+ tiene rate limiting nativo — no requiere paquetes externos para casos comunes.
+- Aplicar políticas más estrictas en endpoints de autenticación (`/login`, `/register`).
+
+---
+
+## Checklist de seguridad antes de hacer merge
+
+- [ ] Sin interpolación de strings en `FromSqlRaw` o `ExecuteSqlRaw`
+- [ ] Todos los endpoints protegidos con `[Authorize]` o `[AllowAnonymous]` explícito
+- [ ] Sin secretos en `appsettings*.json`, `user-secrets` solo en desarrollo
+- [ ] Azure Key Vault o equivalente configurado para producción
+- [ ] `BinaryFormatter` no utilizado en ningún lugar del código nuevo
+- [ ] Headers de seguridad configurados (`X-Content-Type-Options`, `X-Frame-Options`, CSP)
+- [ ] Rate limiting en endpoints de autenticación
+- [ ] `dotnet list package --vulnerable` pasa sin vulnerabilidades HIGH o CRITICAL
+- [ ] Logs sin datos sensibles (passwords, tokens, datos personales)

package/reglas/lenguajes/csharp/testing.md

@@ -0,0 +1,176 @@
+# Regla: Pruebas — C# / .NET
+
+Las pruebas en .NET tienen un ecosistema maduro. Estas reglas establecen el
+stack estándar del proyecto y cómo usarlo para tests deterministas, legibles
+y mantenibles.
+
+---
+
+## xUnit como framework principal
+
+- xUnit es el framework estándar. No usar NUnit ni MSTest en proyectos nuevos.
+- Estructura:
+  ```
+  tests/
+  ├── MiProyecto.UnitTests/
+  └── MiProyecto.IntegrationTests/
+  ```
+- Un proyecto de tests por capa — no mezclar unitarios e integración.
+
+---
+
+## NSubstitute para mocks
+
+NSubstitute para todos los mocks. No Moq (historial de cambios de licencia):
+
+```csharp
+// Crear y configurar mock
+var repo = Substitute.For<IFacturaRepository>();
+repo.ObtenerPorIdAsync(Arg.Any<Guid>(), Arg.Any<CancellationToken>())
+    .Returns(new Factura(/* ... */));
+
+// Verificar que fue llamado exactamente una vez
+await repo.Received(1).AgregarAsync(
+    Arg.Is<Factura>(f => f.Total == 1500m),
+    Arg.Any<CancellationToken>());
+
+// Simular error
+repo.ObtenerPorIdAsync(Arg.Any<Guid>(), Arg.Any<CancellationToken>())
+    .ThrowsAsync(new TimeoutException());
+```
+
+- Mockear solo interfaces y clases abstractas — no clases concretas del dominio.
+- NUNCA mockear la clase bajo prueba — señal de acoplamiento excesivo.
+
+---
+
+## FluentAssertions para assertions legibles
+
+```csharp
+// MAL — difícil de leer en mensajes de fallo
+Assert.Equal(1500m, factura.Total);
+Assert.NotNull(factura.Cliente);
+
+// BIEN — mensajes de error descriptivos automáticos
+factura.Total.Should().Be(1500m);
+factura.Cliente.Should().NotBeNull();
+facturas.Should().HaveCount(3)
+    .And.ContainSingle(f => f.Estatus == EstadoFactura.Pagada);
+
+// Para objetos complejos — ignora campos no relevantes
+resultado.Should().BeEquivalentTo(esperado,
+    opts => opts.Excluding(f => f.FechaCreacion));
+```
+
+---
+
+## TestContainers para integración
+
+```csharp
+public class DatabaseFixture : IAsyncLifetime
+{
+    private readonly PostgreSqlContainer _postgres = new PostgreSqlBuilder()
+        .WithDatabase("testdb").WithUsername("test").WithPassword("test")
+        .Build();
+
+    public string ConnectionString => _postgres.GetConnectionString();
+    public async Task InitializeAsync() => await _postgres.StartAsync();
+    public async Task DisposeAsync() => await _postgres.DisposeAsync();
+}
+
+[Collection("Database")]
+public class FacturaRepositoryTests : IClassFixture<DatabaseFixture>
+{
+    public FacturaRepositoryTests(DatabaseFixture db) { /* usar db.ConnectionString */ }
+
+    [Fact]
+    public async Task Should_PersistFactura_When_Added() { ... }
+}
+```
+
+- TestContainers para tests de repositorio contra PostgreSQL real.
+- `IClassFixture<T>` para compartir el contenedor entre tests del mismo archivo.
+
+---
+
+## WebApplicationFactory para tests de API
+
+```csharp
+public class FacturasApiTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client;
+
+    public FacturasApiTests(WebApplicationFactory<Program> factory)
+    {
+        _client = factory.WithWebHostBuilder(builder =>
+            builder.ConfigureServices(services =>
+            {
+                services.RemoveAll<AppDbContext>();
+                services.AddDbContext<AppDbContext>(opts =>
+                    opts.UseInMemoryDatabase("TestDb"));
+            }))
+            .CreateClient();
+    }
+
+    [Fact]
+    public async Task Should_Return200_When_FacturaExists()
+    {
+        var response = await _client.GetAsync($"/facturas/{Guid.NewGuid()}");
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+    }
+}
+```
+
+- Reemplazar dependencias de infraestructura (BD, servicios externos) con dobles.
+- BD in-memory para tests de API (velocidad), TestContainers para tests de repositorio (fidelidad).
+
+---
+
+## Cobertura mínima 80% con coverlet
+
+```bash
+dotnet test --collect:"XPlat Code Coverage"
+reportgenerator -reports:"**/coverage.cobertura.xml" -targetdir:./coverage-report
+```
+
+- CI falla si cobertura cae por debajo del 80% en proyectos de lógica de negocio.
+- Proyectos de infraestructura y configuración: umbral mínimo del 60%.
+
+---
+
+## Patrón Arrange-Act-Assert
+
+```csharp
+[Fact]
+public async Task Should_ReturnError_When_ClienteNoExiste()
+{
+    // Arrange
+    _clienteRepo.ExisteAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
+        .Returns(false);
+
+    // Act
+    var resultado = await _handler.Handle(
+        new CrearFacturaCommand("test@test.com", 1500m),
+        CancellationToken.None);
+
+    // Assert
+    resultado.IsFailed.Should().BeTrue();
+    resultado.Errors.Should().ContainSingle(e => e.Message.Contains("Cliente"));
+}
+```
+
+- Nombre del test: `Should_[resultado]_When_[condicion]`.
+- Tests parametrizados con `[Theory]` + `[InlineData]` — no duplicar el cuerpo del test.
+
+---
+
+## Checklist de pruebas antes de hacer merge
+
+- [ ] xUnit + NSubstitute + FluentAssertions en todos los tests nuevos
+- [ ] Tests nuevos para todo código nuevo de negocio
+- [ ] Test de regresión escrito antes del fix para todo bug
+- [ ] Cobertura >= 80% verificada con coverlet en CI
+- [ ] Sin `Thread.Sleep` en tests — usar `TimeProvider` mockeado
+- [ ] Tests de integración con TestContainers o WebApplicationFactory
+- [ ] Patrón Arrange-Act-Assert con separación visual clara
+- [ ] Naming: `Should_[resultado]_When_[condicion]`

package/reglas/lenguajes/go/estilo-codigo.md

@@ -0,0 +1,195 @@
+# Regla: Estilo de Código Go
+
+Go tiene una sola forma correcta de formatear código: `gofmt`. Esta regla
+complementa el estilo mecánico con las convenciones idiomáticas de Go que
+no puede verificar una herramienta automática. Seguirlas hace que el código
+sea reconocible para cualquier desarrollador Go, no solo para el equipo.
+
+---
+
+## gofmt es la ley — sin alternativa ni discusión
+
+```bash
+# Obligatorio antes de cada commit
+gofmt -w .
+
+# O con goimports (superset de gofmt que también ordena imports)
+goimports -w .
+```
+
+Un PR que no pasa `gofmt -l .` (que lista archivos mal formateados) no pasa CI.
+No se debate el formato — gofmt es la autoridad. Si el equipo no está de acuerdo
+con alguna decisión de gofmt, el equipo está equivocado.
+
+---
+
+## goimports para organización de imports
+
+`goimports` aplica gofmt y además organiza imports en grupos separados por línea en blanco:
+
+```go
+import (
+    // Paquetes de la standard library
+    "context"
+    "fmt"
+    "time"
+
+    // Dependencias externas
+    "github.com/google/uuid"
+    "go.uber.org/zap"
+
+    // Paquetes internos del proyecto
+    "github.com/miempresa/miapp/internal/domain"
+    "github.com/miempresa/miapp/internal/repository"
+)
+```
+
+---
+
+## Nombres: cortos en scope corto, descriptivos en exportados
+
+Effective Go es la referencia. Las convenciones de naming en Go son distintas a otros lenguajes.
+
+```go
+// BIEN — nombres cortos para variables de scope corto (loops, funciones pequeñas)
+for i, v := range facturas {
+    total += v.Total
+}
+
+if err := repo.Guardar(ctx, factura); err != nil {
+    return fmt.Errorf("guardar factura: %w", err)
+}
+
+// BIEN — nombres descriptivos para exportados y variables de scope amplio
+type FacturaRepository interface {
+    BuscarPorID(ctx context.Context, id uuid.UUID) (*Factura, error)
+    ListarPorCliente(ctx context.Context, clienteID uuid.UUID) ([]*Factura, error)
+}
+
+// MAL — nombre largo para variable de loop (innecesariamente verbose)
+for indiceDeIteracion, facturaActual := range facturas { ... }
+
+// MAL — nombre críptico para exportado
+func Proc(c context.Context, f *Fct) (*Res, error) { ... }
+```
+
+Reglas específicas:
+- Acrónimos exportados en MAYÚSCULAS: `URL`, `HTTP`, `ID`, no `Url`, `Http`, `Id`.
+- Interfaces de un solo método: nombre del método + `-er`: `Reader`, `Writer`, `Stringer`.
+- No repetir el nombre del paquete: `factura.Factura` → `factura.Nueva()` retorna `*Factura`.
+
+---
+
+## "Accept interfaces, return structs"
+
+Las funciones aceptan interfaces (para desacoplamiento y testabilidad) y retornan
+tipos concretos (para claridad del llamador).
+
+```go
+// MAL — retorna interface: el llamador no sabe qué métodos tiene disponibles
+func NuevoServicio(repo FacturaRepository) FacturaServiceInterface { ... }
+
+// BIEN — retorna struct: el llamador sabe exactamente qué recibe
+func NuevoServicio(repo FacturaRepository) *FacturaService { ... }
+
+// BIEN — acepta interface: se puede inyectar cualquier implementación
+type FacturaService struct {
+    repo FacturaRepository  // interface, no *FacturaRepositoryPostgres
+}
+```
+
+---
+
+## Errores se manejan SIEMPRE — nunca `_ = f()`
+
+En Go, ignorar un error es una decisión explícita que requiere justificación.
+`_ = f()` sin comentario es código incorrecto.
+
+```go
+// MAL — error ignorado silenciosamente
+archivo, _ := os.Open(ruta)
+defer archivo.Close()
+
+// MAL — error ignorado con blank identifier sin justificación
+_ = repositorio.Guardar(ctx, factura)
+
+// BIEN — error manejado
+archivo, err := os.Open(ruta)
+if err != nil {
+    return fmt.Errorf("abrir archivo %s: %w", ruta, err)
+}
+defer archivo.Close()
+
+// BIEN — si realmente se ignora, documentar POR QUÉ
+_ = cache.Invalidar(key)  // Error no crítico: la caché se reconstruye automáticamente
+```
+
+---
+
+## Múltiples return values: (resultado, error)
+
+El patrón estándar de Go para operaciones que pueden fallar. Nunca usar
+excepciones ni panics para flujo de control normal.
+
+```go
+// Siempre: (valor, error) — el error va último
+func BuscarFactura(ctx context.Context, id uuid.UUID) (*Factura, error) {
+    factura, err := repo.FindByID(ctx, id)
+    if err != nil {
+        return nil, fmt.Errorf("buscar factura %s: %w", id, err)
+    }
+    if factura == nil {
+        return nil, ErrFacturaNoEncontrada
+    }
+    return factura, nil
+}
+
+// Consumo idiomático
+factura, err := BuscarFactura(ctx, id)
+if err != nil {
+    // manejar error
+}
+// usar factura — garantizado no-nil aquí
+```
+
+---
+
+## Comentarios en funciones exportadas obligatorios
+
+Toda función, tipo o constante exportada DEBE tener comentario en formato godoc.
+El comentario empieza con el nombre del símbolo.
+
+```go
+// MAL — sin comentario
+func (s *FacturaService) Crear(ctx context.Context, req CrearRequest) (*Factura, error) { ... }
+
+// MAL — comentario que no sigue convención godoc
+// Esta función crea una factura
+func (s *FacturaService) Crear(...) { ... }
+
+// BIEN — empieza con el nombre del símbolo
+// Crear genera una nueva factura a partir de la solicitud dada.
+// Retorna ErrClienteInactivo si el cliente no está activo en el momento de la creación.
+func (s *FacturaService) Crear(ctx context.Context, req CrearRequest) (*Factura, error) { ... }
+```
+
+---
+
+## Límites de tamaño
+
+- Máximo **50 líneas** por función (sin contar comentarios y líneas en blanco).
+- Archivos grandes son señal de baja cohesión. Si un archivo supera 300 líneas,
+  evaluar si el paquete tiene una sola responsabilidad.
+- Paquetes con muchos archivos de <50 líneas son paquetes superficiales — considerar consolidar.
+
+---
+
+## Checklist de estilo Go antes de abrir PR
+
+- [ ] `gofmt -l .` retorna vacío (ningún archivo mal formateado)
+- [ ] `goimports -l .` retorna vacío (imports organizados)
+- [ ] Funciones y tipos exportados tienen comentarios godoc
+- [ ] Sin `_ = f()` sin justificación en comentario
+- [ ] Acrónimos exportados en MAYÚSCULAS (URL, ID, HTTP)
+- [ ] Funciones <= 50 líneas
+- [ ] Interfaces aceptadas como parámetros, structs retornados