51 lines
3.2 KiB
Markdown
51 lines
3.2 KiB
Markdown
# 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. |