# 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.

```mermaid
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.

```mermaid
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).