@atlashub/smartstack-cli 2.0.0 → 2.2.0

package/templates/skills/review-code/references/owasp-api-top10.md

@@ -0,0 +1,243 @@
+<overview>
+OWASP API Security Top 10 checklist adapted for SmartStack (.NET/ASP.NET Core). This is DIFFERENT from the OWASP Top 10 (web application vulnerabilities) -- this list targets API-specific threats.
+
+Use this reference when reviewing API controllers, especially those exposed to external clients or public-facing APIs.
+</overview>
+
+<api1_bola>
+## API1 - Broken Object Level Authorization (BOLA/IDOR)
+
+**Risk:** Users access other users' resources by manipulating object IDs in requests.
+
+**SmartStack check:**
+- [ ] All queries filter by `TenantId` (EF Core global filters active)
+- [ ] `[RequirePermission]` on every endpoint
+- [ ] No raw `Guid` from URL used directly without ownership verification
+
+```csharp
+// BAD: IDOR vulnerability - any authenticated user can access any order
+[HttpGet("{id}")]
+public async Task<ActionResult<OrderDto>> Get(Guid id)
+{
+    var order = await _context.Orders.FindAsync(id);
+    return Ok(order);
+}
+
+// GOOD: Tenant filter via EF Core global filter + explicit check
+[HttpGet("{id}")]
+[RequirePermission(Permissions.Business.Orders.Read)]
+public async Task<ActionResult<OrderDto>> Get(Guid id)
+{
+    var order = await _context.Orders
+        .FirstOrDefaultAsync(o => o.Id == id); // Global filter ensures TenantId match
+    if (order is null) return NotFound();
+    return Ok(order.ToDto());
+}
+```
+
+**Detection pattern:**
+```bash
+grep -rE "FindAsync\(id\)|Find\(id\)" --include="*.cs" | grep -v "TenantId"
+```
+</api1_bola>
+
+<api2_broken_auth>
+## API2 - Broken Authentication
+
+**Risk:** Weak authentication mechanisms allow attackers to impersonate users.
+
+**SmartStack check:**
+- [ ] `[Authorize]` on all controllers (except explicit `[AllowAnonymous]`)
+- [ ] JWT tokens validated with issuer, audience, and expiration
+- [ ] Refresh token rotation implemented
+- [ ] Failed login attempts tracked and rate-limited
+
+**Detection pattern:**
+```bash
+grep -rL "\[Authorize\]" --include="*Controller.cs" | grep -v "AuthController"
+```
+</api2_broken_auth>
+
+<api3_broken_property_auth>
+## API3 - Broken Object Property Level Authorization
+
+**Risk:** Users modify properties they shouldn't have access to (mass assignment).
+
+**SmartStack check:**
+- [ ] DTOs separate from entities (no direct entity binding)
+- [ ] `CreateDto` and `UpdateDto` contain only writable fields
+- [ ] Sensitive properties (TenantId, CreatedById, Role) NOT in DTOs
+- [ ] No `[FromBody] Entity` binding (always use DTOs)
+
+```csharp
+// BAD: Mass assignment - user can set their own Role
+[HttpPut("{id}")]
+public async Task<ActionResult> Update(Guid id, [FromBody] User user) { ... }
+
+// GOOD: DTO limits writable fields
+[HttpPut("{id}")]
+[RequirePermission(Permissions.Business.Users.Update)]
+public async Task<ActionResult> Update(Guid id, [FromBody] UpdateUserDto dto) { ... }
+
+public record UpdateUserDto(string Name, string Email); // No Role, no TenantId
+```
+</api3_broken_property_auth>
+
+<api4_unrestricted_consumption>
+## API4 - Unrestricted Resource Consumption
+
+**Risk:** No rate limiting allows API abuse, DDoS, or resource exhaustion.
+
+**SmartStack check:**
+- [ ] Rate limiting middleware configured (`Microsoft.AspNetCore.RateLimiting`)
+- [ ] Pagination enforced on list endpoints (max page size)
+- [ ] File upload size limits set
+- [ ] Query complexity limits (no unbounded `Include()`)
+
+```csharp
+// BAD: No pagination limit - can request entire database
+[HttpGet]
+public async Task<ActionResult<List<OrderDto>>> GetAll([FromQuery] int pageSize = 1000000) { ... }
+
+// GOOD: Enforced max page size
+[HttpGet]
+public async Task<ActionResult<PagedResult<OrderDto>>> GetAll(
+    [FromQuery] int page = 1,
+    [FromQuery] int pageSize = 20)
+{
+    pageSize = Math.Min(pageSize, 100); // Hard cap
+    ...
+}
+```
+</api4_unrestricted_consumption>
+
+<api5_broken_function_auth>
+## API5 - Broken Function Level Authorization
+
+**Risk:** Regular users access admin-level API functions.
+
+**SmartStack check:**
+- [ ] Admin endpoints use `platform.administration.*` permissions
+- [ ] Area-based routing enforced (Admin, Support, Business, User)
+- [ ] System account protection (UserType.System, UserType.LocalAdmin)
+- [ ] No permission bypass via direct URL manipulation
+
+```csharp
+// BAD: Missing permission - any authenticated user can delete
+[HttpDelete("{id}")]
+[Authorize]
+public async Task<ActionResult> Delete(Guid id) { ... }
+
+// GOOD: Explicit permission check
+[HttpDelete("{id}")]
+[RequirePermission(Permissions.Platform.Administration.Users.Delete)]
+public async Task<ActionResult> Delete(Guid id) { ... }
+```
+</api5_broken_function_auth>
+
+<api6_business_flow>
+## API6 - Unrestricted Access to Sensitive Business Flows
+
+**Risk:** Automated abuse of business processes (mass account creation, coupon abuse).
+
+**SmartStack check:**
+- [ ] Rate limiting on sensitive endpoints (registration, password reset)
+- [ ] CAPTCHA or bot detection on public-facing forms
+- [ ] Business flow monitoring and alerting
+- [ ] Idempotency keys for payment/creation operations
+</api6_business_flow>
+
+<api7_ssrf>
+## API7 - Server-Side Request Forgery (SSRF)
+
+**Risk:** Attacker makes the server send requests to internal resources.
+
+**SmartStack check:**
+- [ ] No user-supplied URLs passed to `HttpClient` without validation
+- [ ] Webhook URLs validated against allowlist
+- [ ] Internal network ranges blocked (127.0.0.1, 10.x, 192.168.x)
+
+```csharp
+// BAD: SSRF - user controls the URL
+[HttpPost("fetch")]
+public async Task<ActionResult> Fetch([FromBody] string url)
+{
+    var response = await _httpClient.GetAsync(url);
+    return Ok(await response.Content.ReadAsStringAsync());
+}
+
+// GOOD: Validate against allowlist
+[HttpPost("webhook")]
+public async Task<ActionResult> ConfigureWebhook([FromBody] WebhookDto dto)
+{
+    if (!_webhookValidator.IsAllowedDomain(dto.Url))
+        return BadRequest("URL domain not allowed");
+    ...
+}
+```
+</api7_ssrf>
+
+<api8_misconfiguration>
+## API8 - Security Misconfiguration
+
+**Risk:** Default configs, verbose errors, missing security headers expose attack surface.
+
+**SmartStack check:**
+- [ ] Security headers configured (see security-checklist.md A02)
+- [ ] Error responses don't expose stack traces in production
+- [ ] CORS restricted to known origins (no `AllowAnyOrigin` in production)
+- [ ] Swagger/OpenAPI disabled in production
+- [ ] Debug mode off in production (`ASPNETCORE_ENVIRONMENT=Production`)
+
+**Detection pattern:**
+```bash
+grep -rE "AllowAnyOrigin|EnableDetailedErrors|DeveloperExceptionPage" --include="*.cs"
+```
+</api8_misconfiguration>
+
+<api9_inventory>
+## API9 - Improper Inventory Management
+
+**Risk:** Old or undocumented API endpoints remain exposed without security.
+
+**SmartStack check:**
+- [ ] All controllers have `[NavRoute]` attribute (discoverable)
+- [ ] Deprecated endpoints marked with `[Obsolete]`
+- [ ] `[ProducesResponseType]` on every endpoint (API documentation)
+- [ ] No orphan controllers without matching permissions
+</api9_inventory>
+
+<api10_unsafe_consumption>
+## API10 - Unsafe Consumption of APIs
+
+**Risk:** Application blindly trusts data from third-party APIs.
+
+**SmartStack check:**
+- [ ] External API responses validated/deserialized with typed DTOs
+- [ ] Timeout and retry policies on `HttpClient` (Polly)
+- [ ] Circuit breaker pattern for unreliable external services
+- [ ] External data sanitized before storage
+</api10_unsafe_consumption>
+
+<severity_mapping>
+## Mapping to SmartStack SEC-xxx Categories
+
+| OWASP API | SmartStack Check | Severity |
+|-----------|-----------------|----------|
+| API1 BOLA | SEC-001: Missing tenant filter | blocking |
+| API2 Auth | SEC-002: Missing [Authorize] | blocking |
+| API3 Property Auth | SEC-003: Entity binding (mass assignment) | critical |
+| API4 Resource | SEC-004: No pagination limit | warning |
+| API5 Function Auth | SEC-005: Missing [RequirePermission] | blocking |
+| API6 Business Flow | SEC-006: No rate limit on sensitive ops | warning |
+| API7 SSRF | SEC-007: Unvalidated URL in HttpClient | blocking |
+| API8 Misconfig | SEC-008: CORS/Debug/Headers | critical |
+| API9 Inventory | SEC-009: Undocumented endpoint | info |
+| API10 Unsafe API | SEC-010: Unvalidated external data | warning |
+</severity_mapping>
+
+<sources>
+- [OWASP API Security Top 10 (2023)](https://owasp.org/API-Security/editions/2023/en/0x11-t10/)
+- [OWASP API Security Project](https://owasp.org/www-project-api-security/)
+- SmartStack RBAC and Multi-tenant documentation
+</sources>

package/templates/skills/review-code/references/security-checklist.md

@@ -17,8 +17,35 @@ Configuration hardening:
 
 - [ ] No default credentials
 - [ ] Debug mode disabled in production
-- [ ] Secure headers present (CSP, X-Frame-Options, HSTS)
+- [ ] Secure headers present (see below)
 - [ ] Error messages don't expose internals
+
+**Security headers configuration (ASP.NET Core):**
+```csharp
+// Program.cs
+app.UseHsts(); // HTTP Strict Transport Security (production only)
+
+app.Use(async (context, next) =>
+{
+    var headers = context.Response.Headers;
+    headers["X-Content-Type-Options"] = "nosniff";
+    headers["X-Frame-Options"] = "DENY";
+    headers["Referrer-Policy"] = "strict-origin-when-cross-origin";
+    headers["Permissions-Policy"] = "camera=(), microphone=(), geolocation=()";
+    headers["Content-Security-Policy"] = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'";
+    await next();
+});
+```
+
+**Expected headers in responses:**
+| Header | Value | Purpose |
+|--------|-------|---------|
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` | Force HTTPS |
+| `X-Content-Type-Options` | `nosniff` | Prevent MIME sniffing |
+| `X-Frame-Options` | `DENY` | Prevent clickjacking |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` | Limit referrer info |
+| `Permissions-Policy` | `camera=(), microphone=()` | Restrict browser features |
+| `Content-Security-Policy` | `default-src 'self'` | Prevent XSS via inline scripts |
 </a02_security_misconfiguration>
 
 <a04_cryptographic_failures>
@@ -71,6 +98,64 @@ Access control requirements:
 ✓ No vertical escalation (user → admin functions)
 </authorization>
 
+<rate_limiting>
+## Rate Limiting & Throttling
+
+**ASP.NET Core built-in middleware** (`Microsoft.AspNetCore.RateLimiting`):
+
+```csharp
+// Program.cs
+builder.Services.AddRateLimiter(options =>
+{
+    // Global fixed window: 100 requests per minute
+    options.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(context =>
+        RateLimitPartition.GetFixedWindowLimiter(
+            partitionKey: context.User?.FindFirst("tenant_id")?.Value ?? context.Connection.RemoteIpAddress?.ToString() ?? "anonymous",
+            factory: _ => new FixedWindowRateLimiterOptions
+            {
+                PermitLimit = 100,
+                Window = TimeSpan.FromMinutes(1),
+                QueueLimit = 0
+            }));
+
+    // Named policy for sensitive endpoints
+    options.AddFixedWindowLimiter("auth", opt =>
+    {
+        opt.PermitLimit = 5;
+        opt.Window = TimeSpan.FromMinutes(15);
+        opt.QueueLimit = 0;
+    });
+
+    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
+});
+
+app.UseRateLimiter();
+```
+
+**Controller usage:**
+```csharp
+[EnableRateLimiting("auth")]
+[HttpPost("login")]
+[AllowAnonymous]
+public async Task<ActionResult> Login([FromBody] LoginDto dto) { ... }
+```
+
+**Available strategies:**
+| Strategy | Use case |
+|----------|----------|
+| Fixed Window | General API protection |
+| Sliding Window | Smoother rate distribution |
+| Token Bucket | Burst-tolerant endpoints |
+| Concurrency | Limit parallel requests (file upload, reports) |
+
+**Checklist:**
+- [ ] Global rate limiter configured
+- [ ] Partition by tenant (multi-tenant) or IP (anonymous)
+- [ ] Stricter limits on auth endpoints (login, register, password reset)
+- [ ] `429 Too Many Requests` returned with `Retry-After` header
+- [ ] Rate limit headers present (`X-RateLimit-Limit`, `X-RateLimit-Remaining`)
+</rate_limiting>
+
 <search_patterns>
 Grep patterns for vulnerability detection:
 

package/templates/skills/review-code/references/smartstack-conventions.md

@@ -105,6 +105,172 @@ public class Permission : SystemEntity
 </system_entity>
 </entities>
 
+<value_objects>
+## Value Objects (DDD Pattern)
+
+Value Objects are immutable types defined by their attributes rather than identity. Use them to replace primitive types that carry domain meaning and validation.
+
+**When to use a Value Object:**
+| Instead of | Use | Why |
+|------------|-----|-----|
+| `string Email` | `Email` record | Self-validating, prevents invalid state |
+| `decimal Amount` + `string Currency` | `Money` record | Always consistent pair |
+| `string Street` + `string City` + ... | `Address` record | Cohesive group |
+| `DateTime Start` + `DateTime End` | `DateRange` record | Enforces Start < End invariant |
+
+**Structure (C# record):**
+```csharp
+// Domain/ValueObjects/Email.cs
+public sealed record Email
+{
+    public string Value { get; }
+
+    public Email(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            throw new DomainException("Email is required");
+        if (!value.Contains('@'))
+            throw new DomainException("Invalid email format");
+
+        Value = value.Trim().ToLowerInvariant();
+    }
+
+    public static implicit operator string(Email email) => email.Value;
+    public override string ToString() => Value;
+}
+```
+
+**EF Core mapping:**
+```csharp
+// Option 1: Owned type (separate columns)
+builder.OwnsOne(e => e.Email, email =>
+{
+    email.Property(v => v.Value).HasColumnName("Email").HasMaxLength(256);
+});
+
+// Option 2: Value conversion (single column)
+builder.Property(e => e.Email)
+    .HasConversion(
+        v => v.Value,
+        v => new Email(v))
+    .HasMaxLength(256);
+```
+
+**Entity vs Value Object:**
+| Criteria | Entity | Value Object |
+|----------|--------|-------------|
+| Identity | Has `Id` (Guid) | No identity |
+| Equality | By Id | By all properties |
+| Mutability | Mutable (behavior methods) | Immutable (records) |
+| Lifecycle | Independent | Owned by entity |
+| Example | `User`, `Order` | `Email`, `Money`, `Address` |
+
+**Code review detection:** If an entity has `string Email`, `string Phone`, `decimal Amount` + `string Currency` as separate primitives, suggest replacing with Value Objects.
+</value_objects>
+
+<domain_events>
+## Domain Events
+
+Domain Events capture something that happened in the domain. They enable decoupled communication between aggregates and complement the existing Workflow trigger system.
+
+**Relationship with Workflow Triggers:**
+| Mechanism | Scope | Use case |
+|-----------|-------|----------|
+| Domain Events (MediatR) | In-process, synchronous | Cache invalidation, audit logging, read-model updates |
+| Workflow Triggers (`TriggerAsync`) | Cross-process, async | Emails, webhooks, multi-step business processes |
+| **Combined** | Domain Event handler calls `TriggerAsync()` | Best of both worlds |
+
+**Structure:**
+```csharp
+// Domain/Events/OrderCreatedEvent.cs
+public sealed record OrderCreatedEvent(
+    Guid OrderId,
+    Guid TenantId,
+    Guid CreatedById,
+    DateTime OccurredAt) : IDomainEvent;
+
+// Domain/Common/IDomainEvent.cs
+public interface IDomainEvent : INotification { }  // MediatR marker
+```
+
+**Publishing from entities:**
+```csharp
+public class Order : BaseEntity, ITenantEntity
+{
+    private readonly List<IDomainEvent> _domainEvents = new();
+    public IReadOnlyList<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();
+
+    public static Order Create(Guid tenantId, string description, Guid createdById)
+    {
+        var order = new Order
+        {
+            Id = Guid.NewGuid(),
+            TenantId = tenantId,
+            Description = description
+        };
+
+        order._domainEvents.Add(new OrderCreatedEvent(
+            order.Id, tenantId, createdById, DateTime.UtcNow));
+
+        return order;
+    }
+
+    public void ClearDomainEvents() => _domainEvents.Clear();
+}
+```
+
+**Handling events:**
+```csharp
+// Application/EventHandlers/OrderCreatedEventHandler.cs
+public class OrderCreatedEventHandler : INotificationHandler<OrderCreatedEvent>
+{
+    private readonly IWorkflowService _workflowService;
+    private readonly ILogger<OrderCreatedEventHandler> _logger;
+
+    public async Task Handle(OrderCreatedEvent notification, CancellationToken ct)
+    {
+        _logger.LogInformation("Order {OrderId} created", notification.OrderId);
+
+        // Bridge to Workflow triggers for cross-process actions
+        await _workflowService.TriggerAsync("order.created",
+            new Dictionary<string, object>
+            {
+                ["orderId"] = notification.OrderId,
+                ["tenantId"] = notification.TenantId
+            }, ct: ct);
+    }
+}
+```
+
+**Dispatching (in DbContext):**
+```csharp
+// Infrastructure/Persistence/ApplicationDbContext.cs
+public override async Task<int> SaveChangesAsync(CancellationToken ct = default)
+{
+    var entities = ChangeTracker.Entries<BaseEntity>()
+        .Where(e => e.Entity.DomainEvents.Any())
+        .ToList();
+
+    var events = entities.SelectMany(e => e.Entity.DomainEvents).ToList();
+
+    var result = await base.SaveChangesAsync(ct);
+
+    foreach (var @event in events)
+        await _mediator.Publish(@event, ct);
+
+    foreach (var entity in entities)
+        entity.Entity.ClearDomainEvents();
+
+    return result;
+}
+```
+
+**When to add Domain Events (code review check):**
+- Entity has side effects in `Create()` or behavior methods → Domain Event candidate
+- Service calls `TriggerAsync()` right after `SaveChangesAsync()` → Should be Domain Event
+- Multiple services react to the same entity change → Domain Event decouples them
+</domain_events>
+
 <tables>
 ## Table Naming Conventions
 

package/templates/skills/workflow/SKILL.md

@@ -156,6 +156,33 @@ workflowsApi.execute(workflowId, variables)
 □ Tests: trigger, emails, variables
 ```
 
+## RELATION WITH DOMAIN EVENTS
+
+Workflow triggers (`TriggerAsync`) are the **primary mechanism** for cross-process automation (emails, webhooks, multi-step flows).
+
+**Domain Events** (MediatR `INotificationHandler<T>`) are a complementary pattern for **in-process** side effects (audit logging, cache invalidation, read-model updates).
+
+**Recommended pattern:** Domain Event handler bridges to Workflow triggers:
+```csharp
+// OrderCreatedEventHandler calls TriggerAsync for cross-process actions
+public async Task Handle(OrderCreatedEvent notification, CancellationToken ct)
+{
+    await _workflowService.TriggerAsync("order.created",
+        new Dictionary<string, object>{ ["orderId"] = notification.OrderId }, ct: ct);
+}
+```
+
+**When to use which:**
+| Scenario | Mechanism |
+|----------|-----------|
+| Send email after entity creation | Workflow Trigger |
+| Invalidate cache after entity update | Domain Event |
+| Log audit trail | Domain Event |
+| Multi-step business process with delays | Workflow Trigger |
+| Notify multiple services of same change | Domain Event → Workflow Trigger |
+
+See `review-code/references/smartstack-conventions.md` (Domain Events section) for the full implementation pattern.
+
 ## ABSOLUTE RULES
 
 | DO | DON'T |