added more docs

docs/AUTHENTICATION.md

@@ -0,0 +1,51 @@
+# Authentication Architecture
+
+MiauInv implements a stateless JSON Web Token (JWT) architecture combined with a persistent database-backed Refresh Token mechanism to provide high security alongside seamless session retention.
+
+## Token Lifetime and Properties
+
+| Token Type | Transport Vector | Storage Location | Lifetime | Purpose |
+| --- | --- | --- | --- | --- |
+| **Access Token** | HTTP-Only Cookie & Auth Header | Memory / Browser Cookies | 15 Minutes | Signed payload validating current session identity for immediate API interaction. |
+| **Refresh Token** | Secure Cookie & JSON Payload | LocalStorage / Secure Cookies | 7 Days | Long-lived high-entropy string used to request a new token pair when the Access Token expires. |
+
+---
+
+## Token Rotation and Flow
+
+The application coordinates token validation through cooperative interactions between Go authentication middlewares and the frontend runtime environment.
+
+### 1. Normal Authenticated Requests
+During standard interaction loops, the Go server intercepts requests via auth middleware. It checks the incoming context for validity in the following order:
+1. `Authorization: Bearer <token>` request header.
+2. `access_token` cookie values.
+
+If a valid, unexpired Access Token is recovered, the middleware parses the claims (ID, username, role) and injects them into the request context before execution routes fire.
+
+### 2. Token Refresh Flow
+When an Access Token expires mid-session, the following workflow occurs automatically:
+1. The backend rejects an API call or routing intent with an HTTP state indicating token expiration.
+2. The frontend execution scope identifies the expiration status and reads the `refresh_token` from storage assets.
+3. The client submits a POST request containing the token payload to `/api/refresh`.
+4. The backend verifies the signature, looks up the hash inside the `refresh_tokens` table, and verifies that `revoked == 0` and `expires_at > now`.
+5. If the validation succeeds, a brand-new Access Token and a rotated Refresh Token pair are generated, saved to secure cookies/storage, and the user session continues without explicit re-authentication.
+
+---
+
+## Security Mitigations
+
+### Loop Protection
+To prevent broken, expired, or malformed credentials from triggering infinite network refresh loops (which degrade browser performance and strain backend lookup performance), the frontend utilizes an explicit safety lock.
+
+
+```
+
+Token Expired -> Check 'is_refreshing' flag -> True -> Clear Auth & Force Login
+-> False -> Set flag 'true' -> Send Request
+
+```
+
+Before issuing an evaluation request to `/api/refresh`, the application checks a temporary session variable (`is_refreshing` within `sessionStorage`). If the flag is already set to `true`, the loop protection triggers a hard clearance routine via `clearAllAuth()`, drops all token storage records, and routes the user back to the primary login view safely.
+
+### Database Revocation
+Refresh sessions can be killed immediately from the server side. When a user requests `/api/logout`, the backend switches the corresponding row state within the `refresh_tokens` database container to `revoked = 1`. Any subsequent rotation requests relying on that token family are automatically dropped, protecting against stolen credential replay attacks.