Finishes functional design for unit 0 (back-end changes before front-end work)

2026-06-18 21:40:45 +02:00
parent 9e49489f7e
commit 53a307cdbd
14 changed files with 1065 additions and 4 deletions
@@ -0,0 +1,86 @@
+# Functional Design Plan — Unit 0: Backend Prerequisites
+
+## Unit Context
+- **Unit**: Unit 0 — Backend Prerequisites
+- **Type**: .NET backend changes
+- **Stories**: US-02 (partial — cookie support), US-06 (partial), US-07 (partial)
+- **Deliverables**:
+  - CORS policy via `appsettings.json`
+  - `AuthController` updated for httpOnly cookie (login/refresh/revoke)
+  - `RefreshTokenRequest.cs` removed
+  - `TokenResponse` updated with `Name` property
+  - `appsettings.json` + `appsettings.Development.json` updated
+
+## Plan Checklist
+- [x] Unit context analyzed
+- [x] Questions generated
+- [x] Questions answered
+- [x] business-logic-model.md generated
+- [x] business-rules.md generated
+- [x] domain-entities.md generated
+
+---
+
+## Clarification Questions
+
+Please answer the following questions by filling in the letter choice after the `[Answer]:` tag.
+
+---
+
+### Question 1: Cookie SameSite policy
+The refresh token cookie will use `SameSite=Strict`. Is this correct, or should it be `SameSite=Lax`?
+
+- `SameSite=Strict` — the cookie is only sent when the request originates from the exact same site (most secure; may cause issues if the login page is linked from an external source)
+- `SameSite=Lax` — the cookie is sent on top-level navigations (e.g. clicking a link) but not on cross-site sub-requests (good balance of security and usability)
+
+A) SameSite=Strict (as currently designed)
+B) SameSite=Lax (slightly more permissive, still secure)
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+---
+
+### Question 2: Cookie Secure flag in development
+In local development (HTTP, not HTTPS), the `Secure` flag on the cookie will cause the browser to reject the cookie. How should this be handled?
+
+A) Use `Secure = true` always — developer must use HTTPS locally (e.g. via `dotnet dev-certs`)
+B) Set `Secure` based on environment: `true` in Production, `false` in Development
+C) Set `Secure = request.IsHttps` — automatically adapts to the current request protocol
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: B
+
+---
+
+### Question 3: TokenResponse — Name field source
+The `TokenResponse` needs a `Name` field for the user's display name. `ApplicationUser` has `UserName` (from IdentityUser) but no dedicated display name field. What should `Name` return?
+
+A) `user.UserName` — the username is used as the display name
+B) `user.Email` — the email is used as the display name
+C) `user.UserName ?? user.Email` — use UserName if set, fall back to Email
+X) Other — add a dedicated `DisplayName` property to `ApplicationUser` (describe below)
+
+[Answer]: C
+
+---
+
+### Question 4: Revoke endpoint — authentication requirement
+The current `Revoke` endpoint requires a valid Bearer token (`[Authorize]`). With the cookie-based flow, should this still require authentication?
+
+A) Yes — keep `[Authorize]` requirement (user must have a valid access token to revoke; most secure)
+B) No — remove `[Authorize]` (allows revoking even after access token expires; better UX for logout after expiry)
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A, but make the UX still seemless and make it refresh in the background while logging out. Maybe adding a text along the line of "Securely logging out..." gives some more time.
+
+---
+
+### Question 5: CORS — allowed HTTP methods
+Which HTTP methods should the CORS policy allow?
+
+A) Only the methods used by the API: GET, POST, PUT, DELETE, OPTIONS
+B) All methods: `AllowAnyMethod()` (simpler, allows future endpoints without CORS changes)
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
@@ -0,0 +1,50 @@
+# NFR Requirements Plan — Unit 0: Backend Prerequisites
+
+## Context
+Unit 0 modifies existing .NET 10 backend endpoints. Most NFRs are inherited from the existing system. Only security-specific NFRs for the cookie/CORS changes require clarification.
+
+## Plan Checklist
+- [x] Functional design artifacts analyzed
+- [x] Questions generated
+- [x] Questions answered
+- [x] nfr-requirements.md generated
+- [x] tech-stack-decisions.md generated
+
+---
+
+## Clarification Questions
+
+---
+
+### Question 1: Refresh token lifetime
+What should the refresh token lifetime be?
+
+A) 7 days (current default — check actual `RefreshToken` expiry in the codebase)
+B) 30 days
+C) 90 days
+X) Other (specify in days after [Answer]: tag)
+
+[Answer]: A
+
+---
+
+### Question 2: Rate limiting on auth endpoints
+Should rate limiting be applied to the auth endpoints (login, refresh) to prevent brute-force attacks?
+
+A) Yes — add rate limiting now as part of Unit 0 (e.g. via ASP.NET Core built-in rate limiter)
+B) No — rate limiting is out of scope for this unit; document as future work
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+---
+
+### Question 3: Error response format on auth failures
+What should the error response body look like when auth fails (wrong password, invalid token, missing cookie)?
+
+A) RFC 9457 ProblemDetails (standard ASP.NET format: `type`, `title`, `status`, `detail`)
+B) Simple JSON `{ "message": "..." }` (consistent with current API error format)
+C) Use the existing GlobalExceptionHandler format from `SlpModularCms.Api/Infrastructure/`
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A