Changes backend in preparation for frontend work

2026-06-19 12:15:08 +02:00
parent b5357f213a
commit 23e2150140
22 changed files with 631 additions and 92 deletions
@@ -0,0 +1,62 @@
+# Logical Components — Unit 0: Backend Prerequisites
+
+The following logical components and configuration structures are defined to support the NFR implementation.
+
+## 1. Middleware Ordering (Pipeline Design)
+The order of middleware registration is critical for security and performance. The pipeline is configured in `Program.cs`.
+
+```mermaid
+graph TD
+    Start((Start)) --> Exc[GlobalExceptionHandler]
+    Exc --> RL[Rate Limiter]
+    RL --> CORS[CORS Middleware]
+    CORS --> Auth[Authentication]
+    Auth --> Map[Endpoint Mapping]
+    Map --> End((End))
+    
+    classDef infra fill:#cbd5e0,stroke:#1a202c,stroke-width:2px,color:#1a202c;
+    classDef security fill:#feb2b2,stroke:#742a2a,stroke-width:2px,color:#742a2a;
+    classDef core fill:#9ae6b4,stroke:#22543d,stroke-width:2px,color:#22543d;
+    class Start,End,Map infra;
+    class Exc,RL,CORS,Auth security;
+```
+
+Text alternative: Sequence of middleware in the ASP.NET Core pipeline (colored nodes indicate role).
+
+## 2. Configuration Structure (appsettings.json)
+Following the `dotnet-appsettings` skill pattern, the configuration for NFRs is centralized.
+
+### CORS Configuration
+```json
+"Cors": {
+  "AllowedOrigins": [
+    "https://localhost:5173"
+  ]
+}
+```
+
+### Rate Limiting Configuration
+```json
+"RateLimiting": {
+  "Login": {
+    "PermitLimit": 5,
+    "WindowSeconds": 60
+  },
+  "Refresh": {
+    "PermitLimit": 20,
+    "WindowSeconds": 60
+  }
+}
+```
+
+## 3. Extension Methods
+To keep `Program.cs` clean, logical components are encapsulated in `ServiceCollectionExtensions.cs`.
+
+| Component | Responsibility |
+|-----------|----------------|
+| `AddCmsCors()` | Configures the CORS policy based on settings. |
+| `AddCmsRateLimiting()` | Defines the Fixed and Sliding window policies for auth. |
+| `AddCmsExceptionHandling()` | Registers the `GlobalExceptionHandler` and ProblemDetails. |
+
+## 4. ProblemDetails Integration
+The `GlobalExceptionHandler` will be modified to fully replace the custom `ApiErrorResponse` with standard `ProblemDetails` as the return type. No backward compatibility for the old error format is required.
@@ -0,0 +1,71 @@
+# 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).