@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/dotnet/security/references/REFERENCE.md

@@ -0,0 +1,295 @@
+# .NET Security Reference
+
+Authentication, authorization, and security headers configuration.
+
+## References
+
+- [**JWT Authentication**](jwt-authentication.md) - Token generation and validation.
+- [**Identity Configuration**](identity-configuration.md) - Password rules, lockout settings.
+- [**Security Headers**](security-headers.md) - CSP, HSTS, X-Frame-Options.
+
+## JWT Token Generation
+
+```csharp
+public class TokenService(IOptions<JwtSettings> options)
+{
+    private readonly JwtSettings _settings = options.Value;
+
+    public string GenerateToken(User user)
+    {
+        var claims = new[]
+        {
+            new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()),
+            new Claim(ClaimTypes.Email, user.Email),
+            new Claim(ClaimTypes.Role, user.Role),
+            new Claim("tenant_id", user.TenantId.ToString())
+        };
+
+        var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_settings.Key));
+        var credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
+
+        var token = new JwtSecurityToken(
+            issuer: _settings.Issuer,
+            audience: _settings.Audience,
+            claims: claims,
+            expires: DateTime.UtcNow.AddHours(_settings.ExpiryHours),
+            signingCredentials: credentials);
+
+        return new JwtSecurityTokenHandler().WriteToken(token);
+    }
+
+    public ClaimsPrincipal? ValidateToken(string token)
+    {
+        var handler = new JwtSecurityTokenHandler();
+        try
+        {
+            return handler.ValidateToken(token, new TokenValidationParameters
+            {
+                ValidateIssuer = true,
+                ValidateAudience = true,
+                ValidateLifetime = true,
+                ValidateIssuerSigningKey = true,
+                ValidIssuer = _settings.Issuer,
+                ValidAudience = _settings.Audience,
+                IssuerSigningKey = new SymmetricSecurityKey(
+                    Encoding.UTF8.GetBytes(_settings.Key)),
+                ClockSkew = TimeSpan.Zero
+            }, out _);
+        }
+        catch
+        {
+            return null;
+        }
+    }
+}
+```
+
+## ASP.NET Identity Configuration
+
+```csharp
+// Program.cs
+builder.Services.AddIdentity<ApplicationUser, IdentityRole>(options =>
+{
+    // Password requirements
+    options.Password.RequiredLength = 12;
+    options.Password.RequireDigit = true;
+    options.Password.RequireLowercase = true;
+    options.Password.RequireUppercase = true;
+    options.Password.RequireNonAlphanumeric = true;
+    options.Password.RequiredUniqueChars = 4;
+
+    // Lockout settings
+    options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(15);
+    options.Lockout.MaxFailedAccessAttempts = 5;
+    options.Lockout.AllowedForNewUsers = true;
+
+    // User settings
+    options.User.RequireUniqueEmail = true;
+    options.SignIn.RequireConfirmedEmail = true;
+})
+.AddEntityFrameworkStores<AppDbContext>()
+.AddDefaultTokenProviders();
+
+// Password hasher upgrade (Argon2id recommended for new apps)
+builder.Services.Configure<PasswordHasherOptions>(options =>
+{
+    options.IterationCount = 310000; // OWASP recommendation
+});
+```
+
+## Security Headers Middleware
+
+```csharp
+// Using a middleware class
+public class SecurityHeadersMiddleware(RequestDelegate next)
+{
+    public async Task InvokeAsync(HttpContext context)
+    {
+        // Prevent clickjacking
+        context.Response.Headers.Append("X-Frame-Options", "DENY");
+
+        // Prevent MIME sniffing
+        context.Response.Headers.Append("X-Content-Type-Options", "nosniff");
+
+        // XSS protection (legacy, CSP is better)
+        context.Response.Headers.Append("X-XSS-Protection", "1; mode=block");
+
+        // Referrer policy
+        context.Response.Headers.Append("Referrer-Policy", "strict-origin-when-cross-origin");
+
+        // Content Security Policy
+        context.Response.Headers.Append("Content-Security-Policy",
+            "default-src 'self'; " +
+            "script-src 'self' 'unsafe-inline'; " +
+            "style-src 'self' 'unsafe-inline'; " +
+            "img-src 'self' data: https:; " +
+            "font-src 'self'; " +
+            "frame-ancestors 'none';");
+
+        // Permissions Policy
+        context.Response.Headers.Append("Permissions-Policy",
+            "geolocation=(), microphone=(), camera=()");
+
+        await next(context);
+    }
+}
+
+// Usage in Program.cs
+app.UseMiddleware<SecurityHeadersMiddleware>();
+app.UseHsts(); // Strict-Transport-Security
+```
+
+## CORS Configuration
+
+```csharp
+// Development (allow specific origins)
+builder.Services.AddCors(options =>
+{
+    options.AddPolicy("Development", policy =>
+    {
+        policy.WithOrigins("http://localhost:3000", "http://localhost:5173")
+              .AllowAnyHeader()
+              .AllowAnyMethod()
+              .AllowCredentials();
+    });
+
+    options.AddPolicy("Production", policy =>
+    {
+        policy.WithOrigins(
+                builder.Configuration.GetSection("Cors:AllowedOrigins").Get<string[]>()!)
+              .WithHeaders("Authorization", "Content-Type", "X-Requested-With")
+              .WithMethods("GET", "POST", "PUT", "DELETE")
+              .AllowCredentials()
+              .SetPreflightMaxAge(TimeSpan.FromMinutes(10));
+    });
+});
+
+// Usage
+app.UseCors(builder.Environment.IsDevelopment() ? "Development" : "Production");
+```
+
+## Resource-Based Authorization
+
+```csharp
+// Requirement
+public class ResourceOwnerRequirement : IAuthorizationRequirement { }
+
+// Handler
+public class ResourceOwnerHandler : AuthorizationHandler<ResourceOwnerRequirement, Order>
+{
+    protected override Task HandleRequirementAsync(
+        AuthorizationHandlerContext context,
+        ResourceOwnerRequirement requirement,
+        Order resource)
+    {
+        var userId = context.User.FindFirstValue(ClaimTypes.NameIdentifier);
+
+        if (resource.UserId.ToString() == userId ||
+            context.User.IsInRole("Admin"))
+        {
+            context.Succeed(requirement);
+        }
+
+        return Task.CompletedTask;
+    }
+}
+
+// Registration
+builder.Services.AddScoped<IAuthorizationHandler, ResourceOwnerHandler>();
+
+// Usage in controller
+public async Task<IActionResult> UpdateOrder(int id, UpdateOrderDto dto)
+{
+    var order = await _orderService.GetByIdAsync(id);
+    if (order is null) return NotFound();
+
+    var authResult = await _authService.AuthorizeAsync(
+        User, order, new ResourceOwnerRequirement());
+
+    if (!authResult.Succeeded) return Forbid();
+
+    await _orderService.UpdateAsync(order, dto);
+    return NoContent();
+}
+```
+
+## Rate Limiting (.NET 7+)
+
+```csharp
+builder.Services.AddRateLimiter(options =>
+{
+    // Fixed window: 100 requests per minute
+    options.AddFixedWindowLimiter("fixed", cfg =>
+    {
+        cfg.Window = TimeSpan.FromMinutes(1);
+        cfg.PermitLimit = 100;
+        cfg.QueueLimit = 10;
+        cfg.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
+    });
+
+    // Sliding window: smoother rate limiting
+    options.AddSlidingWindowLimiter("sliding", cfg =>
+    {
+        cfg.Window = TimeSpan.FromMinutes(1);
+        cfg.PermitLimit = 100;
+        cfg.SegmentsPerWindow = 6; // 10-second segments
+    });
+
+    // Token bucket: burst allowance
+    options.AddTokenBucketLimiter("token", cfg =>
+    {
+        cfg.TokenLimit = 100;
+        cfg.ReplenishmentPeriod = TimeSpan.FromSeconds(10);
+        cfg.TokensPerPeriod = 20;
+    });
+
+    // Per-user limiting
+    options.AddPolicy("per-user", context =>
+        RateLimitPartition.GetFixedWindowLimiter(
+            context.User.Identity?.Name ?? context.Connection.RemoteIpAddress?.ToString() ?? "anonymous",
+            _ => new FixedWindowRateLimiterOptions
+            {
+                Window = TimeSpan.FromMinutes(1),
+                PermitLimit = 50
+            }));
+
+    options.OnRejected = async (context, token) =>
+    {
+        context.HttpContext.Response.StatusCode = StatusCodes.Status429TooManyRequests;
+        await context.HttpContext.Response.WriteAsJsonAsync(new
+        {
+            error = "Too many requests. Please try again later."
+        }, token);
+    };
+});
+
+// Usage
+app.UseRateLimiter();
+
+app.MapGet("/api/data", () => "Hello")
+   .RequireRateLimiting("fixed");
+```
+
+## Secrets Management
+
+```csharp
+// Development: User Secrets
+// dotnet user-secrets init
+// dotnet user-secrets set "Database:Password" "secret123"
+
+// Production: Azure Key Vault
+builder.Configuration.AddAzureKeyVault(
+    new Uri($"https://{builder.Configuration["KeyVault:Name"]}.vault.azure.net/"),
+    new DefaultAzureCredential());
+
+// Environment variables (Docker/K8s)
+builder.Configuration.AddEnvironmentVariables(prefix: "APP_");
+
+// Never do this:
+// ❌ var password = "hardcoded_password";
+// ❌ var connString = "Server=...;Password=secret;";
+
+// Always do this:
+// ✅ var password = builder.Configuration["Database:Password"];
+// ✅ var connString = builder.Configuration.GetConnectionString("Default");
+```

package/rules/dotnet/tooling/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: .NET Tooling
+description: Essential tooling for .NET development and CI/CD.
+metadata:
+  labels: [dotnet, tooling, testing, build, nuget]
+  triggers:
+    files: ['**/*.csproj', '**/*.sln', '.editorconfig', 'Directory.Build.props']
+    keywords: [PackageReference, dotnet, test, build, publish]
+---
+
+# .NET Tooling
+
+## **Priority: P1 (OPERATIONAL)**
+
+Essential tooling for .NET development, testing, and CI/CD.
+
+## Implementation Guidelines
+
+- **Project Files**: SDK-style `.csproj`. Use `Directory.Build.props` for shared settings.
+- **Central Package Management**: `Directory.Packages.props` for version consistency.
+- **Testing**: xUnit or NUnit. FluentAssertions for readable assertions. Moq for mocking.
+- **Code Analysis**: Enable built-in analyzers. Consider StyleCop, SonarQube.
+- **Build**: `dotnet build`, `dotnet publish`. Use Release config for production.
+- **EditorConfig**: Consistent code style across team.
+- **CI/CD**: GitHub Actions, Azure DevOps, or GitLab CI.
+
+## Anti-Patterns
+
+- **No `packages.config`**: Migrate to `PackageReference`.
+- **No skipping tests in CI**: Tests must pass before merge.
+- **No ignoring warnings**: Fix or suppress with documented justification.
+- **No floating versions**: Pin versions (`8.0.0`, not `8.*`).
+
+## Code
+
+```xml
+<!-- Directory.Build.props (shared across all projects) -->
+<Project>
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <AnalysisLevel>latest-recommended</AnalysisLevel>
+  </PropertyGroup>
+</Project>
+
+<!-- Directory.Packages.props (Central Package Management) -->
+<Project>
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="8.0.0" />
+    <PackageVersion Include="FluentValidation" Version="11.9.0" />
+    <PackageVersion Include="xunit" Version="2.6.6" />
+  </ItemGroup>
+</Project>
+```
+
+```csharp
+// xUnit test with FluentAssertions
+public class UserServiceTests
+{
+    [Fact]
+    public async Task GetUser_WithValidId_ReturnsUser()
+    {
+        // Arrange
+        var mockRepo = new Mock<IUserRepository>();
+        mockRepo.Setup(r => r.GetByIdAsync(1, default))
+            .ReturnsAsync(new User { Id = 1, Name = "Test" });
+        var sut = new UserService(mockRepo.Object);
+
+        // Act
+        var result = await sut.GetUserAsync(1);
+
+        // Assert
+        result.Should().NotBeNull();
+        result!.Name.Should().Be("Test");
+        mockRepo.Verify(r => r.GetByIdAsync(1, default), Times.Once);
+    }
+}
+```
+
+## Reference & Examples
+
+For CI/CD configuration and Docker setup:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+language | best-practices | security

package/rules/dotnet/tooling/references/REFERENCE.md

@@ -0,0 +1,300 @@
+# .NET Tooling Reference
+
+Testing, CI/CD, and build configuration patterns.
+
+## References
+
+- [**Testing Setup**](testing-setup.md) - xUnit, NUnit, integration tests.
+- [**CI/CD**](ci-cd.md) - GitHub Actions, Azure DevOps pipelines.
+- [**Docker**](docker.md) - Multi-stage builds for .NET.
+
+## Project File (.csproj) Reference
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+
+    <!-- Code analysis -->
+    <AnalysisLevel>latest-recommended</AnalysisLevel>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+
+    <!-- Assembly info -->
+    <Version>1.0.0</Version>
+    <Authors>Your Name</Authors>
+
+    <!-- Build optimization -->
+    <PublishTrimmed>true</PublishTrimmed>
+    <PublishSingleFile>true</PublishSingleFile>
+    <SelfContained>true</SelfContained>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Package references (versions from Directory.Packages.props) -->
+    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" />
+    <PackageReference Include="Serilog.AspNetCore" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <!-- Project references -->
+    <ProjectReference Include="..\Domain\Domain.csproj" />
+    <ProjectReference Include="..\Infrastructure\Infrastructure.csproj" />
+  </ItemGroup>
+</Project>
+```
+
+## GitHub Actions CI/CD
+
+```yaml
+# .github/workflows/ci.yml
+name: CI/CD
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+env:
+  DOTNET_VERSION: '8.0.x'
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: ${{ env.DOTNET_VERSION }}
+
+      - name: Restore dependencies
+        run: dotnet restore
+
+      - name: Build
+        run: dotnet build --no-restore --configuration Release
+
+      - name: Test
+        run: dotnet test --no-build --configuration Release --collect:"XPlat Code Coverage" --results-directory ./coverage
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          directory: ./coverage
+          fail_ci_if_error: true
+
+  publish:
+    needs: build-and-test
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: ${{ env.DOTNET_VERSION }}
+
+      - name: Publish
+        run: dotnet publish src/WebApi/WebApi.csproj -c Release -o ./publish
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ghcr.io/${{ github.repository }}:latest
+```
+
+## Docker Multi-Stage Build
+
+```dockerfile
+# Dockerfile
+FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
+WORKDIR /src
+
+# Copy csproj files and restore
+COPY ["src/WebApi/WebApi.csproj", "src/WebApi/"]
+COPY ["src/Domain/Domain.csproj", "src/Domain/"]
+COPY ["src/Infrastructure/Infrastructure.csproj", "src/Infrastructure/"]
+COPY ["Directory.Build.props", "./"]
+COPY ["Directory.Packages.props", "./"]
+RUN dotnet restore "src/WebApi/WebApi.csproj"
+
+# Copy everything and build
+COPY . .
+RUN dotnet publish "src/WebApi/WebApi.csproj" -c Release -o /app/publish --no-restore
+
+# Runtime image
+FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
+WORKDIR /app
+
+# Create non-root user
+RUN adduser --disabled-password --gecos "" appuser
+USER appuser
+
+COPY --from=build /app/publish .
+
+ENV ASPNETCORE_URLS=http://+:8080
+EXPOSE 8080
+
+ENTRYPOINT ["dotnet", "WebApi.dll"]
+```
+
+## Integration Testing with WebApplicationFactory
+
+```csharp
+// CustomWebApplicationFactory.cs
+public class CustomWebApplicationFactory<TProgram> : WebApplicationFactory<TProgram>
+    where TProgram : class
+{
+    protected override void ConfigureWebHost(IWebHostBuilder builder)
+    {
+        builder.ConfigureServices(services =>
+        {
+            // Replace real database with in-memory
+            var descriptor = services.SingleOrDefault(
+                d => d.ServiceType == typeof(DbContextOptions<AppDbContext>));
+
+            if (descriptor != null)
+                services.Remove(descriptor);
+
+            services.AddDbContext<AppDbContext>(options =>
+                options.UseInMemoryDatabase("TestDb"));
+
+            // Replace external services with fakes
+            services.AddScoped<IEmailService, FakeEmailService>();
+        });
+
+        builder.UseEnvironment("Testing");
+    }
+}
+
+// Integration tests
+public class UsersApiTests : IClassFixture<CustomWebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client;
+    private readonly CustomWebApplicationFactory<Program> _factory;
+
+    public UsersApiTests(CustomWebApplicationFactory<Program> factory)
+    {
+        _factory = factory;
+        _client = factory.CreateClient();
+    }
+
+    [Fact]
+    public async Task GetUsers_ReturnsSuccessAndUsers()
+    {
+        // Arrange - seed data
+        using var scope = _factory.Services.CreateScope();
+        var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
+        db.Users.Add(new User { Name = "Test User", Email = "test@example.com" });
+        await db.SaveChangesAsync();
+
+        // Act
+        var response = await _client.GetAsync("/api/users");
+
+        // Assert
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        var users = await response.Content.ReadFromJsonAsync<List<UserDto>>();
+        users.Should().ContainSingle(u => u.Email == "test@example.com");
+    }
+
+    [Fact]
+    public async Task CreateUser_WithValidData_ReturnsCreated()
+    {
+        // Arrange
+        var newUser = new CreateUserDto { Name = "New User", Email = "new@example.com" };
+
+        // Act
+        var response = await _client.PostAsJsonAsync("/api/users", newUser);
+
+        // Assert
+        response.StatusCode.Should().Be(HttpStatusCode.Created);
+        response.Headers.Location.Should().NotBeNull();
+    }
+}
+```
+
+## EditorConfig
+
+```ini
+# .editorconfig
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.cs]
+# Naming conventions
+dotnet_naming_rule.private_fields_should_be_camel_case.severity = error
+dotnet_naming_rule.private_fields_should_be_camel_case.symbols = private_fields
+dotnet_naming_rule.private_fields_should_be_camel_case.style = camel_case_underscore
+
+dotnet_naming_symbols.private_fields.applicable_kinds = field
+dotnet_naming_symbols.private_fields.applicable_accessibilities = private
+
+dotnet_naming_style.camel_case_underscore.required_prefix = _
+dotnet_naming_style.camel_case_underscore.capitalization = camel_case
+
+# Code style
+csharp_style_var_for_built_in_types = false:suggestion
+csharp_style_var_when_type_is_apparent = true:suggestion
+csharp_style_expression_bodied_methods = when_on_single_line:suggestion
+csharp_prefer_braces = true:warning
+
+# Formatting
+csharp_new_line_before_open_brace = all
+csharp_new_line_before_else = true
+csharp_new_line_before_catch = true
+csharp_new_line_before_finally = true
+
+[*.{json,yml,yaml}]
+indent_size = 2
+```
+
+## Benchmark.NET Setup
+
+```csharp
+// Install: dotnet add package BenchmarkDotNet
+
+[MemoryDiagnoser]
+[SimpleJob(RuntimeMoniker.Net80)]
+public class StringConcatBenchmarks
+{
+    private readonly string[] _strings = Enumerable.Range(0, 100)
+        .Select(i => $"String{i}").ToArray();
+
+    [Benchmark(Baseline = true)]
+    public string ConcatWithPlus()
+    {
+        string result = "";
+        foreach (var s in _strings)
+            result += s;
+        return result;
+    }
+
+    [Benchmark]
+    public string ConcatWithStringBuilder()
+    {
+        var sb = new StringBuilder();
+        foreach (var s in _strings)
+            sb.Append(s);
+        return sb.ToString();
+    }
+
+    [Benchmark]
+    public string ConcatWithJoin() => string.Join("", _strings);
+}
+
+// Run: dotnet run -c Release
+```