thakares/nx9-auth
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add architecture documentation and standardize filenames

Browse Source
This commit is contained in:
thakares committed 2026-07-22 20:18:38 +05:30
1 parent 0010f2cfb8
commit 0134ff6a50
1 file changed
+28 -28
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+28 -28
View File
@@ -73,16 +73,16 @@ The server runtime isolates process lifecycle management from business domain lo
- **Shutdown**: Manages prioritized shutdown hooks and completion timeouts. - **Shutdown**: Manages prioritized shutdown hooks and completion timeouts.
```mermaid ```mermaid
stateDiagram-v2 flowchart TD
[*] --> Initializing : Build application runtime Start([Start]) --> Initializing[Initializing]
Initializing --> Starting : Start application Initializing -->|Build application runtime| Starting[Starting]
Starting --> Running : Bind TCP listener and serve Starting -->|Bind listener and serve| Running[Running]
Running --> Draining : Signal received Running -->|Signal received| Draining[Draining]
Draining --> StoppingWorkers : Stop background workers Draining -->|Stop background workers| StoppingWorkers[Stopping Workers]
StoppingWorkers --> ExecutingHooks : Execute shutdown hooks StoppingWorkers -->|Execute shutdown hooks| ExecutingHooks[Executing Hooks]
ExecutingHooks --> ClosingResources : Close database pools ExecutingHooks -->|Close database pools| ClosingResources[Closing Resources]
ClosingResources --> Stopped : Process stopped ClosingResources --> Stopped[Stopped]
Stopped --> [*] Stopped --> EndState([End])
``` ```
--- ---
@@ -100,8 +100,8 @@ flowchart TD
TracingMW --> Sanitizer[Query String Credential Sanitizer] TracingMW --> Sanitizer[Query String Credential Sanitizer]
Sanitizer --> AuthExtractor[Authentication Extractor] Sanitizer --> AuthExtractor[Authentication Extractor]
AuthExtractor --> GuardCheck{Authorized} AuthExtractor --> GuardCheck{Authorized}
GuardCheck -- No --> ErrResp[HTTP 401 or 403 Response] --> Client GuardCheck -->|No| ErrResp[HTTP 401 or 403 Response] --> Client
GuardCheck -- Yes --> Handler[API Route Handler] GuardCheck -->|Yes| Handler[API Route Handler]
Handler --> Service[Domain Service Layer] Handler --> Service[Domain Service Layer]
Service --> RepoTrait[Repository Interface] Service --> RepoTrait[Repository Interface]
RepoTrait --> DBImpl[Database Provider] RepoTrait --> DBImpl[Database Provider]
@@ -166,26 +166,26 @@ NX9-Auth supports dual-mode authentication, accommodating both browser environme
```mermaid ```mermaid
flowchart TD flowchart TD
AuthRequest[Incoming HTTP Request] --> RouteType{Request Path} AuthRequest[Incoming HTTP Request] --> RouteType{Request Path}
RouteType -- Login Route --> LoginHandler[Login Handler] RouteType -->|Login Route| LoginHandler[Login Handler]
LoginHandler --> VerifyPassword[Verify Password via Argon2id] LoginHandler --> VerifyPassword[Verify Password via Argon2id]
VerifyPassword -- Invalid --> TimingMitigation[Execute Dummy Hash Delay] --> Return401[Return HTTP 401] VerifyPassword -->|Invalid| TimingMitigation[Execute Dummy Hash Delay] --> Return401[Return HTTP 401]
VerifyPassword -- Valid --> RevokeSessions[Revoke Active User Sessions] VerifyPassword -->|Valid| RevokeSessions[Revoke Active User Sessions]
RevokeSessions --> GenerateTokens[Generate Opaque Tokens] RevokeSessions --> GenerateTokens[Generate Opaque Tokens]
GenerateTokens --> HashTokens[Compute BLAKE3 Hashes] GenerateTokens --> HashTokens[Compute BLAKE3 Hashes]
HashTokens --> SaveDB[Store Hashes in Database] HashTokens --> SaveDB[Store Hashes in Database]
SaveDB --> IssueAuth[Issue HttpOnly Cookie and Bearer Token] --> AuthSuccess[Authentication Success] SaveDB --> IssueAuth[Issue HttpOnly Cookie and Bearer Token] --> AuthSuccess[Authentication Success]
RouteType -- Protected API Route --> ExtractAuth[Extract Authentication Context] RouteType -->|Protected API Route| ExtractAuth[Extract Authentication Context]
ExtractAuth --> CheckCookie{Cookie Present} ExtractAuth --> CheckCookie{Cookie Present}
CheckCookie -- Yes --> ValidateCookie[BLAKE3 Lookup in Sessions Table] CheckCookie -->|Yes| ValidateCookie[BLAKE3 Lookup in Sessions Table]
ValidateCookie -- Valid --> ExtractUserCookie[Find Active User] --> SessionAuth[Authenticated Session] ValidateCookie -->|Valid| ExtractUserCookie[Find Active User] --> SessionAuth[Authenticated Session]
CheckCookie -- No --> CheckHeader{Authorization Header Present} CheckCookie -->|No| CheckHeader{Authorization Header Present}
CheckHeader -- Yes --> TokenPrefix{Token Prefix} CheckHeader -->|Yes| TokenPrefix{Token Prefix}
TokenPrefix -- PAT Prefix --> ValidatePAT[BLAKE3 Lookup in PAT Table] --> ExtractUserPAT[Find Active User] --> PATAuth[Authenticated Token] TokenPrefix -->|PAT Prefix| ValidatePAT[BLAKE3 Lookup in PAT Table] --> ExtractUserPAT[Find Active User] --> PATAuth[Authenticated Token]
TokenPrefix -- Session Prefix --> ValidateSession[BLAKE3 Lookup in Sessions Table] --> ExtractUserSession[Find Active User] --> SessionAuth TokenPrefix -->|Session Prefix| ValidateSession[BLAKE3 Lookup in Sessions Table] --> ExtractUserSession[Find Active User] --> SessionAuth
CheckHeader -- No --> Return401 CheckHeader -->|No| Return401
ValidateCookie -- Invalid --> CheckHeader ValidateCookie -->|Invalid| CheckHeader
ValidatePAT -- Invalid --> Return401 ValidatePAT -->|Invalid| Return401
ValidateSession -- Invalid --> Return401 ValidateSession -->|Invalid| Return401
``` ```
--- ---
@@ -202,8 +202,8 @@ flowchart LR
Request[API Endpoint Request] --> RequiredPerm[Required Permission Scope] Request[API Endpoint Request] --> RequiredPerm[Required Permission Scope]
RequiredPerm --> AccessEvaluator{Permission Granted} RequiredPerm --> AccessEvaluator{Permission Granted}
GlobalPermissions --> AccessEvaluator GlobalPermissions --> AccessEvaluator
AccessEvaluator -- Yes --> Allow[Execute Handler] AccessEvaluator -->|Yes| Allow[Execute Handler]
AccessEvaluator -- No --> Deny[HTTP 403 Forbidden] AccessEvaluator -->|No| Deny[HTTP 403 Forbidden]
``` ```
--- ---