slp-modular-cms/aidlc-docs/features/cms-frontend/construction/unit-0/nfr-design/nfr-design-patterns.md

NFR Design Patterns — Unit 0: Backend Prerequisites

Non-functional requirements are addressed using the following design patterns and implementation strategies.

Resilience & Protection Patterns

1. Global Rate Limiting Pipeline

To protect the authentication endpoints from brute-force and DoS attacks, a global rate limiting pipeline is implemented using the built-in ASP.NET Core Microsoft.AspNetCore.RateLimiting middleware.

• Fixed Window Pattern (Login):
  • Scoped to POST /api/v1/auth/login.
  • Limit: 5 requests per 1 minute.
  • Partitioned by Client IP Address.
• Sliding Window Pattern (Refresh):
  • Scoped to POST /api/v1/auth/refresh.
  • Limit: 20 requests per 1 minute.
  • Partitioned by Client IP Address.

graph TD
    Client[Client Request] --> RL[Rate Limiter Middleware]
    RL -- Limit Exceeded --> 429[429 Too Many Requests]
    RL -- Within Limit --> Pipeline[Authentication Pipeline]
    
    classDef client fill:#fef3c7,stroke:#92400e,stroke-width:2px,color:#92400e;
    classDef security fill:#feb2b2,stroke:#742a2a,stroke-width:2px,color:#742a2a;
    classDef success fill:#c6f6d5,stroke:#22543d,stroke-width:2px,color:#22543d;
    class Client client;
    class RL,429 security;
    class Pipeline success;

Text alternative: Flow showing Rate Limiter Middleware intercepting requests and either returning 429 or passing to the pipeline (colored nodes indicate role).

Security Patterns

2. Cross-Origin Resource Sharing (CORS) Policy

CORS is configured via a strongly-typed ServiceCollectionExtensions method to ensure consistent application of security rules.

• Pattern: Explicit Origin Allowlist.
• Logic: Origin is validated against Cors:AllowedOrigins in appsettings.json.
• Requirement: AllowCredentials() is mandatory to support the httpOnly Refresh Token cookie cross-origin.

3. Secure Cookie Pattern (Refresh Token)

The Refresh Token is stored using a multi-layered security approach:

• HttpOnly: Prevents access via JavaScript (XSS protection).
• Secure: Ensures the cookie is only transmitted over HTTPS (In production).
• SameSite=Strict: Prevents the browser from sending the cookie with cross-site requests (CSRF protection).
• Scoped Path: Path is restricted to /api/v1/auth to minimize exposure.

Performance & Reliability Patterns

4. Standardized RFC 9457 Error Handling

Existing GlobalExceptionHandler is extended to return ProblemDetails conform RFC 9457. This ensures client-side libraries can predictably parse error responses.

• Mapping: Specific exceptions (e.g. UnauthorizedAccessException, RateLimitRejectedException) are mapped to their corresponding HTTP status codes.
• Safety: Stack traces are only included in Development environment.

sequenceDiagram
    participant C as Client #fef3c7
    participant M as Middleware/Controller #c6f6d5
    participant H as GlobalExceptionHandler #feb2b2
    
    C->>M: Request
    M-->>M: Error Occurs
    M->>H: Catch Exception
    H->>C: ProblemDetails (JSON)

Text alternative: Sequence diagram showing how exceptions are caught by the GlobalExceptionHandler and returned as ProblemDetails to the client (colored participants indicate role).