From 0010f2cfb820a82dbf275d89b230e6955a0e70cd Mon Sep 17 00:00:00 2001 From: Sunil Thakare Date: Wed, 22 Jul 2026 20:15:22 +0530 Subject: [PATCH] docs: add architecture documentation and standardize filenames --- docs/ARCHITECTURE.md | 501 +++++++++++++++++-------------------------- 1 file changed, 202 insertions(+), 299 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 680af64..74c237d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,444 +1,347 @@ -# NX9-Auth System Architecture Specification +# 1. System Overview + +NX9-Auth is a self-hosted Identity and Access Management (IAM) server written in pure Rust. It provides centralized authentication, fine-grained Role-Based Access Control (RBAC), multi-tenancy, service account management, personal access tokens (PATs), and append-only audit logging. + +The system is architected as a stateless HTTP server paired with a zero-JavaScript-framework WebAssembly (WASM) administration user interface. Executing natively on Linux operating systems without external memory caches, JavaScript runtimes, or third-party web frameworks, NX9-Auth achieves low memory consumption, high throughput, zero garbage collection pauses, and operational simplicity. + +Supported deployment models include single-binary installations, systemd-managed services, containerized workloads, and reverse-proxy setups using embedded SQLite or external PostgreSQL database engines. --- -## 1. System Overview & Executive Summary +# 2. Design Philosophy -**NX9-Auth** is a lightweight, high-performance, self-hosted Identity and Access Management (IAM) platform written entirely in pure Rust. It provides centralized authentication, fine-grained Role-Based Access Control (RBAC), multi-tenancy, service account management, personal access tokens (PATs), and append-only audit logging. +NX9-Auth adheres to seven core design tenets: -The system is architected as a modular, stateless HTTP server paired with a zero-JavaScript-framework WebAssembly (WASM) administration user interface. By executing natively on Linux systems without requiring external memory caches (e.g., Redis), JavaScript runtime environments (e.g., Node.js), or third-party web frameworks, NX9-Auth achieves minimal memory consumption, high throughput, zero garbage collection pauses, and operational simplicity. +- **Linux-First**: Native optimization for Linux operating systems, systemd process supervision, standard UNIX signal handling, and POSIX filesystem standards. +- **Privacy-First**: Zero external telemetry, phone-home calls, or third-party tracking. All identity records remain strictly under local operator control. +- **Self-Hosted**: Distributed as 100% Free and Open Source Software (FOSS) dual-licensed under Apache 2.0 and MIT. +- **Rust-Native**: End-to-end type safety, compile-time memory safety, and thread concurrency guarantees across both server and WebAssembly client binaries. +- **Security by Default**: OWASP-aligned response headers, memory-hard Argon2id key derivation, BLAKE3 token hashing at rest, non-enumerating error responses, and strict Content Security Policies. +- **Zero Node.js Runtime**: No JavaScript runtime dependencies, npm build chains, or external frontend node packages. The administrative interface is compiled from Rust directly to WebAssembly. +- **Operational Simplicity**: Single-binary deployment capability with embedded or external SQL databases. Zero mandatory external cache or message broker sidecars. --- -## 2. Design Philosophy - -NX9-Auth adheres strictly to eight core design tenets: - -1. **Linux-First**: Native optimization for Linux environments, systemd process supervision, standard UNIX signals, and POSIX filesystem standards. -2. **Privacy-First**: No external telemetry, phone-home mechanisms, or third-party tracking. All identity records remain strictly under local operator control. -3. **Self-Hosted & FOSS**: Distributed as 100% Free and Open Source Software (FOSS) dual-licensed under Apache 2.0 and MIT. -4. **Rust-Native Integrity**: End-to-end type safety, compile-time memory safety, and thread concurrency guarantees across both server and WebAssembly client binaries. -5. **Zero Node.js Runtime**: No JavaScript runtime dependencies, npm build chains, or node_modules overhead. The frontend is compiled from Rust directly to WebAssembly. -6. **Minimal Dependencies**: Strict audit of external crates to maintain a minimal attack surface, fast compile times, and long-term maintenance stability. -7. **Operational Simplicity**: Single-binary deployment capability with embedded or external SQL databases. Zero mandatory external cache or message broker sidecars. -8. **Security by Default**: OWASP-aligned response headers, memory-hard Argon2id key derivation, BLAKE3 token hashing at rest, non-enumerating error responses, and strict Content Security Policies (CSP). - ---- - -## 3. Architectural Principles +# 3. Architectural Principles The internal architecture is guided by structural design patterns: -- **Layer Separation**: Downward-only dependency flow (`CLI` $\rightarrow$ `Runtime` $\rightarrow$ `Application` $\rightarrow$ `HTTP Router` $\rightarrow$ `Services` $\rightarrow$ `Repositories` $\rightarrow$ `Database`). -- **Dependency Inversion**: Service and handler layers depend on trait abstractions (`UserRepository`, `SessionRepository`) rather than concrete database drivers. -- **Repository Pattern**: Pluggable storage providers (SQLite, PostgreSQL) implementing unified async trait interfaces. -- **Configuration over Hardcoding**: Fail-fast configuration loading supporting configuration files, environment variable overrides, and CLI flags. -- **Stateless HTTP API**: Authentication state is encapsulated in cryptographically hashed session cookies or Bearer tokens, eliminating sticky-session server dependencies. +- **Layer Separation**: Downward-only dependency flow from entry points to persistence drivers. +- **Repository Pattern**: Pluggable storage providers implementing unified async trait interfaces. +- **Dependency Inversion**: Service and handler layers depend on trait abstractions rather than concrete database drivers. +- **Stateless APIs**: Authentication state is encapsulated in cryptographically hashed session cookies or Bearer tokens, eliminating sticky-session server dependencies. +- **Explicit Errors**: Strongly typed error enumerations mapping internal failures to standard HTTP status codes without leaking sensitive stack traces. - **Fail-Fast Startup**: Early validation of configuration paths, database connectivity, and encryption parameters before opening listening sockets. - **Graceful Shutdown**: Signal-driven, multi-stage shutdown sequence ensuring background worker completion, audit log flushing, and pool draining. -- **Explicit Error Handling**: Strongly typed error enumerations (`AppError`) mapping internal failures to standard HTTP status codes without leaking sensitive stack traces. --- -## 4. Technology Stack +# 4. Technology Stack -| Component Layer | Technology Choice | Key Function & Architectural Role | -| :--- | :--- | :--- | -| **Language Ecosystem** | Rust | Core system implementation across server and WebAssembly client. | -| **Async Execution** | Tokio | Multi-threaded asynchronous I/O, timer management, and task scheduling. | -| **HTTP Routing** | Axum & Tower | Type-safe REST API routing, request extraction, and middleware pipelines. | -| **Database Abstraction** | SQLx | Asynchronous, compile-time verified database access for SQLite and PostgreSQL. | -| **Password Cryptography** | Argon2id | Memory-hard key derivation function for secure password verification. | -| **Token Hashing** | BLAKE3 | Fast cryptographic hashing for storing session tokens and PATs at rest. | -| **Rate Limiting** | DashMap | Lock-free, high-concurrency in-memory hash map for tracking IP failure counters. | -| **Frontend Framework** | Dioxus (WASM) | Declarative, signal-driven WebAssembly UI with virtual DOM reconciliation. | -| **WASM HTTP Client** | Reqwest (WASM) | WebAssembly HTTP fetch client configured for credentialed API interaction. | +### Backend +- **Core Language**: Rust (2024 Edition) +- **Async Runtime**: Tokio +- **HTTP Routing**: Axum and Tower +- **Database Engine**: SQLx (supporting SQLite and PostgreSQL) + +### Frontend +- **UI Framework**: Dioxus (WebAssembly compilation target) +- **WASM Interop**: wasm-bindgen +- **HTTP Client**: Reqwest (configured for credentialed WebAssembly fetch operations) +- **Browser Storage**: gloo-storage + +### Cryptography & Security +- **Password Hashing**: Argon2id +- **Token Hashing**: BLAKE3 +- **Rate Limiting**: DashMap (lock-free in-memory tracking) --- -## 5. Runtime Architecture +# 5. Runtime Architecture -### 5.1 Runtime Core Components +The server runtime isolates process lifecycle management from business domain logic. -The server runtime (`src/runtime/`) isolates process lifecycle management from business domain logic: - -- **Application**: The core container holding state, connection pools, state trackers, and worker managers. -- **ApplicationBuilder**: Assembles configuration, initializes database providers, applies database migrations, and binds the router. -- **AtomicRuntimeState**: Lock-free atomic state machine enforcing valid lifecycle transitions. -- **SignalManager**: Asynchronous signal listener intercepting `SIGINT` and `SIGTERM`. -- **ShutdownCoordinator**: Manages prioritized shutdown hooks and completion timeouts. -- **WorkerManager**: Supervises background asynchronous tasks (e.g., expired session pruning, audit log flushing). -- **HookRegistry**: Maintains prioritized cleanup routines executed during graceful shutdown. -- **RuntimeMetrics**: Tracks runtime uptime, active connections, and worker states. - -### 5.2 Deterministic Lifecycle State Machine +### Components +- **Application**: Core container holding global state, connection pools, state trackers, and worker managers. +- **Builder**: Assembles configuration, initializes database providers, applies database migrations, and binds the router. +- **Lifecycle**: Manages application state transitions from initialization to termination. +- **State**: Lock-free atomic state machine enforcing valid lifecycle transitions. +- **Workers**: Supervises background asynchronous tasks such as expired session pruning and audit log flushing. +- **Signals**: Asynchronous signal listener intercepting SIGINT and SIGTERM. +- **Hooks**: Maintains prioritized cleanup routines executed during graceful shutdown. +- **Metrics**: Tracks runtime uptime, active connections, and worker states. +- **Shutdown**: Manages prioritized shutdown hooks and completion timeouts. ```mermaid stateDiagram-v2 - [*] --> Initializing : ApplicationBuilder::build() - Initializing --> Starting : Application::start() - Starting --> Running : TcpListener Bound & axum::serve Awaited - Running --> Draining : SIGINT / SIGTERM Received - Draining --> StoppingWorkers : Background Workers Signaled - StoppingWorkers --> ExecutingHooks : Prioritized Shutdown Hooks Executed - ExecutingHooks --> ClosingResources : Database Connection Pools Drained - ClosingResources --> Stopped : Process Terminates Cleanly + [*] --> Initializing : Build application runtime + Initializing --> Starting : Start application + Starting --> Running : Bind TCP listener and serve + Running --> Draining : Signal received + Draining --> StoppingWorkers : Stop background workers + StoppingWorkers --> ExecutingHooks : Execute shutdown hooks + ExecutingHooks --> ClosingResources : Close database pools + ClosingResources --> Stopped : Process stopped Stopped --> [*] ``` -### 5.3 Prioritized Shutdown Sequence - -When a termination signal is received, the runtime executes hooks sequentially by tier: - -1. **ShutdownPriority::First**: Closes HTTP ingress listener and stops receiving new connections. -2. **ShutdownPriority::Normal**: Cancels active background worker loops and awaits inflight jobs. -3. **ShutdownPriority::Last**: Flushes pending audit trails and closes database pool connections. - --- -## 6. Request Lifecycle & Pipeline Architecture +# 6. Request Lifecycle -Every incoming HTTP request traverses a strict layered middleware pipeline: +Every incoming HTTP request traverses a structured, layered processing pipeline. ```mermaid flowchart TD - Client([Client Request]) --> TCP[Tokio TcpListener] + Client[Client Request] --> TCP[TCP Listener] TCP --> Router[Axum HTTP Router] - - subgraph MiddlewarePipeline [" Middleware Pipeline "] - Router --> SecHeaders[Security Headers Middleware\nCSP, Cache-Control, HSTS] - SecHeaders --> TracingMW[Tracing & Request ID Generation] - TracingMW --> Sanitizer[SPA Query String Credential Sanitizer] - end - - Sanitizer --> AuthExtractor[AuthUser Extractor\nCookie vs. Bearer Token] - AuthExtractor --> GuardCheck{Endpoint Allowed?} - - GuardCheck -- Unauthorized --> ErrResp[HTTP 401 / 403 JSON Response] --> Client - GuardCheck -- Authorized --> Handler[API Route Handler] - + Router --> SecHeaders[Security Headers Middleware] + SecHeaders --> TracingMW[Tracing and Request ID] + TracingMW --> Sanitizer[Query String Credential Sanitizer] + Sanitizer --> AuthExtractor[Authentication Extractor] + AuthExtractor --> GuardCheck{Authorized} + GuardCheck -- No --> ErrResp[HTTP 401 or 403 Response] --> Client + GuardCheck -- Yes --> Handler[API Route Handler] Handler --> Service[Domain Service Layer] - Service --> RepoTrait[Repository Trait Interface] - RepoTrait --> DBImpl[SQLite / PostgreSQL Driver] + Service --> RepoTrait[Repository Interface] + RepoTrait --> DBImpl[Database Provider] DBImpl --> DB[(Database Engine)] - DB --> DBImpl --> RepoTrait --> Service --> Handler - Handler --> Response[JSON Response / SPA Assets] --> Client + Handler --> Response[JSON Response or SPA Assets] --> Client ``` --- -## 7. Repository & Database Architecture +# 7. Repository Architecture -### 7.1 Repository Abstraction Layer +NX9-Auth decouples persistence logic from domain services using trait abstractions. This ensures API handlers remain agnostic of the underlying storage backend. -NX9-Auth decouples persistence logic from domain services using Rust traits (`async_trait`). This guarantees that API handlers remain agnostic of the underlying database engine. +### Layer Hierarchy +1. **Traits**: Define high-level database access contracts. +2. **SQLite Implementation**: Embedded storage driver using Write-Ahead Logging for high concurrency. +3. **PostgreSQL Implementation**: Enterprise storage driver for external multi-node deployments. +4. **Service Layer**: Coordinates business logic, transactions, and audit trail records across repositories. ```mermaid classDiagram class UserRepository { - <> - +find_by_id(id) Option~User~ - +find_by_username(name) Option~User~ - +create(user) User - +update(user) User - +delete(id) bool + +find_by_id(id) + +find_by_username(username) + +create(user) + +update(user) + +delete(id) } - class SqliteUserRepository { - -SqlitePool pool +find_by_id(id) +create(user) } - class PostgresUserRepository { - -PgPool pool +find_by_id(id) +create(user) } - class AuthService { - -DynUserRepository user_repo - -DynSessionRepository session_repo +authenticate(credentials) } - UserRepository <|.. SqliteUserRepository UserRepository <|.. PostgresUserRepository AuthService --> UserRepository ``` -### 7.2 Database Engines & Schema Migrations - -- **SQLite**: Default embedded database provider using WAL (Write-Ahead Logging) mode and busy timeout management for high concurrency. -- **PostgreSQL**: Production multi-node provider for enterprise environments. -- **Migration System**: Managed via SQLx embedded migrations executed automatically during startup, guaranteeing schema consistency across upgrades. - --- -## 8. Authentication Architecture +# 8. Authentication -NX9-Auth supports dual-mode authentication, accommodating both web browser clients (via HttpOnly cookies) and API consumers / SPA applications (via Bearer tokens). +NX9-Auth supports dual-mode authentication, accommodating both browser environments and automated API clients. + +### Authentication Credentials and Identifiers +- **Login Handler**: Accepts JSON credential payloads and validates passwords using Argon2id. +- **Password Verification**: Memory-hard verification with constant-time dummy delays on invalid usernames to neutralize timing side-channels. +- **Sessions**: Short-lived opaque session tokens issued upon login and stored as BLAKE3 hashes at rest. +- **Refresh Tokens**: Opaque refresh tokens used to obtain new session tokens without re-entering credentials. +- **Personal Access Tokens (PAT)**: Long-lived tokens generated for automated API integrations. +- **Service Accounts**: Non-human identities bound to specific tenants and permission scopes. +- **Cookies**: HttpOnly, SameSite-protected cookies holding session identifiers for browser clients. +- **Bearer Tokens**: Authorization header tokens for API consumers and WebAssembly applications. ```mermaid flowchart TD - AuthRequest([Incoming Credentials / Request]) --> RouteType{Request Path?} - - RouteType -- POST /api/v1/auth/login --> LoginHandler[Login Handler] + AuthRequest[Incoming HTTP Request] --> RouteType{Request Path} + RouteType -- Login Route --> LoginHandler[Login Handler] LoginHandler --> VerifyPassword[Verify Password via Argon2id] - VerifyPassword -- Invalid --> TimingMitigation[Execute Dummy Argon2id Delay] --> Return401[Return HTTP 401 Unauthorized] - VerifyPassword -- Valid --> RevokeSessions[Session Fixation Mitigation:\nRevoke Prior Sessions & Tokens] - - RevokeSessions --> GenerateTokens[Generate Opaque Tokens:\nst_... and rt_...] - GenerateTokens --> HashTokens[Compute BLAKE3 Hashes for Storage] + VerifyPassword -- Invalid --> TimingMitigation[Execute Dummy Hash Delay] --> Return401[Return HTTP 401] + VerifyPassword -- Valid --> RevokeSessions[Revoke Active User Sessions] + RevokeSessions --> GenerateTokens[Generate Opaque Tokens] + GenerateTokens --> HashTokens[Compute BLAKE3 Hashes] HashTokens --> SaveDB[Store Hashes in Database] - SaveDB --> IssueAuth[Issue HttpOnly Cookie + Return Access Token JSON] --> AuthSuccess([Authenticated]) - - RouteType -- Protected API Route --> ExtractAuth[Extract AuthUser] - ExtractAuth --> CheckCookie{Cookie nx9_session\nPresent?} + SaveDB --> IssueAuth[Issue HttpOnly Cookie and Bearer Token] --> AuthSuccess[Authentication Success] + RouteType -- Protected API Route --> ExtractAuth[Extract Authentication Context] + ExtractAuth --> CheckCookie{Cookie Present} CheckCookie -- Yes --> ValidateCookie[BLAKE3 Lookup in Sessions Table] - ValidateCookie -- Valid --> ExtractUserCookie[Find Active User] --> SessionAuth([AuthMethod::Session]) - - CheckCookie -- No --> CheckHeader{Authorization: Bearer\nHeader Present?} - CheckHeader -- Yes --> TokenPrefix{Token Prefix?} - TokenPrefix -- pat_... --> ValidatePAT[BLAKE3 Lookup in PAT Table] --> ExtractUserPAT[Find Active User] --> PATAuth([AuthMethod::Token]) - TokenPrefix -- st_... --> ValidateSession[BLAKE3 Lookup in Sessions Table] --> ExtractUserSession[Find Active User] --> SessionAuth - + ValidateCookie -- Valid --> ExtractUserCookie[Find Active User] --> SessionAuth[Authenticated Session] + CheckCookie -- No --> CheckHeader{Authorization Header Present} + CheckHeader -- Yes --> TokenPrefix{Token Prefix} + 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 CheckHeader -- No --> Return401 ValidateCookie -- Invalid --> CheckHeader ValidatePAT -- Invalid --> Return401 ValidateSession -- Invalid --> Return401 ``` -### 8.1 Key Authentication Mechanisms -- **Session Tokens (`st_...`)**: Short-lived opaque session tokens returned on login and stored in HttpOnly cookies or client memory. -- **Refresh Tokens (`rt_...`)**: Opaque tokens used to issue new session tokens without re-entering primary credentials. -- **Personal Access Tokens (`pat_...`)**: Long-lived API tokens generated by users for automated integrations, hashed at rest using BLAKE3. -- **Service Accounts**: Non-human identities bound to specific tenants and limited permission scopes for automated workloads. - --- -## 9. Authorization Model (RBAC) +# 9. Authorization -NX9-Auth implements a hierarchical Role-Based Access Control (RBAC) model: +NX9-Auth implements a hierarchical Role-Based Access Control (RBAC) authorization model. ```mermaid flowchart LR - User[User / Service Account] --> UserRoles[Assigned Roles] + User[User or Service Account] --> UserRoles[Assigned Roles] UserRoles --> RolePermissions[Role Permissions] RolePermissions --> GlobalPermissions[Effective Permission Set] - - Request[API Request Endpoint] --> RequiredPerm[Required Permission Scope] - RequiredPerm --> AccessEvaluator{Permission In Set?} + Request[API Endpoint Request] --> RequiredPerm[Required Permission Scope] + RequiredPerm --> AccessEvaluator{Permission Granted} GlobalPermissions --> AccessEvaluator - - AccessEvaluator -- Yes --> Allow[HTTP 200 / Execute Handler] + AccessEvaluator -- Yes --> Allow[Execute Handler] AccessEvaluator -- No --> Deny[HTTP 403 Forbidden] ``` -### Authorization Rules -- **Super Admin (`*`)**: Universal access across all tenants and administrative APIs. -- **Tenant Admin**: Administrative authority scoped strictly to resources owned by their tenant. -- **Viewer / Standard User**: Read-only access or limited domain operation privileges. -- **Permission Evaluation**: Resolved during the handler phase after successful `AuthUser` extraction. +--- + +# 10. Security + +NX9-Auth enforces a defense-in-depth security posture across all subsystems: + +- **Argon2id Key Derivation**: Memory-hard password hashing parameters (m=19456 KiB, t=2, p=1). +- **BLAKE3 Cryptographic Hashing**: High-speed cryptographic hashing for storing session tokens, refresh tokens, and personal access tokens at rest. +- **Secure Cookie Attributes**: HttpOnly, SameSite=Lax, and Secure flag enforcement in production environments. +- **Content Security Policy (CSP)**: Strict header policy prohibiting inline script execution while allowing WebAssembly evaluation. +- **HTTP Strict Transport Security (HSTS)**: Transport security header enforcement when running under secure configurations. +- **Audit Logging**: Append-only, tamper-evident audit trail capturing actor, target, severity, IP address, and user agent. +- **Rate Limiting**: Lock-free in-memory IP tracking with automatic lockout penalties upon consecutive failure thresholds. +- **Credential Sanitization**: Fallback routes intercept and strip query strings containing credentials, returning HTTP 303 redirects to clean paths. --- -## 10. Security Architecture +# 11. Multi-tenancy -NX9-Auth enforces a defense-in-depth security posture: - -``` -┌────────────────────────────────────────────────────────────────────────┐ -│ HTTP Response Layer │ -│ Strict CSP (script-src 'self' 'wasm-unsafe-eval') | Cache-Control │ -│ HSTS | X-Frame-Options: DENY | Referrer-Policy: no-referrer │ -└────────────────────────────────────────────────────────────────────────┘ - │ -┌────────────────────────────────────────────────────────────────────────┐ -│ Transport & Sanitization │ -│ GET Query Credential Interceptor (HTTP 303 Redirect Sanitizer) │ -│ In-Memory Rate Limiting (DashMap Exponential IP Lockout) │ -└────────────────────────────────────────────────────────────────────────┘ - │ -┌────────────────────────────────────────────────────────────────────────┐ -│ Cryptographic Storage Layer │ -│ Argon2id (m=19456 KiB, t=2, p=1) Password Key Derivation │ -│ BLAKE3 Opaque Token Hashing at Rest (Sessions, Refresh, PATs) │ -└────────────────────────────────────────────────────────────────────────┘ - │ -┌────────────────────────────────────────────────────────────────────────┐ -│ Audit & Observability │ -│ Append-Only Tamper-Evident Audit Logging (actor, target, severity) │ -└────────────────────────────────────────────────────────────────────────┘ -``` - -- **Non-Enumerating Authentication Errors**: Password failures and non-existent usernames return identical HTTP 401 error payloads and invoke Argon2id execution paths to neutralize timing side-channels. -- **Query Parameter Credential Protection**: Server-side fallback handlers strip any query strings containing sensitive credentials (`username=`, `password=`) and issue immediate HTTP 303 redirects to clean paths. - ---- - -## 11. Multi-Tenancy & Resource Hierarchy - -Resources are hierarchically structured to ensure data isolation: +Resources are hierarchically isolated to enforce strict multi-tenant data boundaries. ```mermaid flowchart TD System[NX9-Auth System] --> TenantA[Tenant A] System --> TenantB[Tenant B] - - TenantA --> UsersA[Users & Service Accounts] + TenantA --> UsersA[Users and Service Accounts] TenantA --> GroupsA[Groups] TenantA --> AppsA[Applications] - GroupsA --> RolesA[Roles] - AppsA --> ResourcesA[API Resources & Tokens] - - TenantB --> UsersB[Users & Service Accounts] + AppsA --> ResourcesA[Resources and Tokens] + TenantB --> UsersB[Users and Service Accounts] TenantB --> GroupsB[Groups] TenantB --> AppsB[Applications] ``` -### Data Isolation Guarantees -- Every database query for tenant-scoped entities contains explicit `WHERE tenant_id = ?` filters. -- Service accounts and applications are strictly bound to their parent tenant ID and cannot cross boundaries. +### Data Isolation Rules +- Database queries for tenant-scoped entities enforce explicit tenant filters. +- Service accounts and applications are strictly bound to their parent tenant identifier. --- -## 12. Frontend Architecture (WebAssembly SPA) +# 12. Frontend -The administration interface is implemented as a pure WebAssembly Single Page Application (SPA) using Dioxus 0.6: +The administrative user interface is implemented as a WebAssembly Single Page Application (SPA) built with Dioxus. ```mermaid flowchart TD - Browser[Web Browser] --> IndexHTML[index.html] - IndexHTML --> BootJS[assets/boot.js] - BootJS --> WASMModule[nx9_auth_ui_bg.wasm] - - subgraph DioxusWASM [" Dioxus WebAssembly Engine "] - VDOM[Virtual DOM Engine] - SignalState[Signal State Management] - Router[Dioxus Router] - end - - WASMModule --> DioxusWASM - - subgraph EventSystem [" Dual Event Interception Protocol "] - FormSubmit[Form onsubmit Listener] --> PreventDefault[evt.prevent_default()] - ButtonClick[Button onclick Listener] --> PreventDefault - PreventDefault --> WASMFetch[WASM Reqwest fetch()] - end - - DioxusWASM --> EventSystem - WASMFetch -- "Content-Type: application/json\nfetch_credentials_include()" --> BackendAPI[NX9-Auth Axum REST API] + Browser[Web Browser] --> IndexHTML[Index HTML] + IndexHTML --> BootJS[Boot Script] + BootJS --> WASMModule[WASM Module] + WASMModule --> VDOM[Virtual DOM Engine] + VDOM --> SignalState[Signal State] + SignalState --> Router[Dioxus Router] + Router --> EventSystem[Dual Event Interceptors] + EventSystem --> FormSubmit[Form Submit Listener] + EventSystem --> ButtonClick[Button Click Listener] + FormSubmit --> PreventDefault[Prevent Default Event] + ButtonClick --> PreventDefault + PreventDefault --> WASMFetch[Reqwest WASM Fetch] + WASMFetch --> BackendAPI[Axum REST API] ``` --- -## 13. Configuration System +# 13. Configuration -NX9-Auth loads configuration using a multi-tiered fallback hierarchy: +NX9-Auth manages system parameters through a hierarchical configuration system. -``` -1. Explicit CLI Flags (--config /path/to/config.toml) - │ - ▼ -2. Environment Variables (NX9_SERVER__PORT, NX9_DATABASE__URL) - │ - ▼ -3. Local Configuration Files (./config.toml, /etc/nx9-auth/config.toml) - │ - ▼ -4. Compiled Default Fallbacks -``` +### Configuration Precedence Order +1. Command Line Interface (CLI) Arguments +2. Environment Variables +3. Configuration Files (TOML format) +4. Built-in Defaults -### Validation & Startup Safeguards -- Configuration loading performs instant fail-fast validation. If database URIs are malformed or TLS configurations are invalid, process execution halts immediately with explicit error logging before binding network ports. +Startup execution validates configuration parameters immediately. If configuration paths, database URIs, or security options fail validation, process startup halts with explicit error messages before network ports are bound. --- -## 14. Deployment Architecture +# 14. Deployment -NX9-Auth is deployed as a single, self-contained Linux executable: +NX9-Auth is deployed as a single self-contained executable on Linux systems, supervised by systemd and situated behind a reverse proxy. ```mermaid flowchart LR - Internet([Internet / Clients]) --> ReverseProxy[Reverse Proxy\nNginx / Caddy / Traefik\n(TLS Termination)] - ReverseProxy -- HTTP / Unix Socket --> AppService[NX9-Auth Binary\nSystemd Supervised Service] - AppService <--> SQLite[SQLite Database File\n(WAL Mode)] - AppService <--> Postgres[(PostgreSQL Server)] + Internet[Client Traffic] --> ReverseProxy[Reverse Proxy Caddy or Nginx] + ReverseProxy --> AppService[NX9-Auth Process Systemd Supervised] + AppService --> SQLite[SQLite Database Engine] + AppService --> Postgres[PostgreSQL Database Engine] ``` -### Systemd Process Supervision Example (`nx9-auth.service`) -```ini -[Unit] -Description=NX9-Auth Identity & Access Management Server -After=network.target - -[Service] -Type=simple -User=nx9-auth -Group=nx9-auth -ExecStart=/usr/local/bin/nx9-auth serve --config /etc/nx9-auth/config.toml -Restart=on-failure -RestartSec=5s -LimitNOFILE=65536 -CapabilityBoundingSet= -NoNewPrivileges=true -ProtectSystem=strict -ProtectHome=true -ReadWritePaths=/var/lib/nx9-auth - -[Install] -WantedBy=multi-user.target -``` +### Process Supervision Overview +Systemd handles process lifetime, automatic restarts, resource limits, and security sandboxing (such as restricting filesystem access and disabling privilege escalation). Standard deployment files reside in `deploy/systemd/nx9-auth.service`. --- -## 15. Repository Directory Layout +# 15. Repository Layout ```text / -├── Cargo.toml # Primary Cargo workspace manifest -├── Cargo.lock # Dependency lockfile -├── build.rs # Build script for static asset embedding -├── README.md # Project documentation overview -├── LICENSE # Dual license declaration (MIT OR Apache-2.0) -├── LICENSE-MIT # MIT License terms -├── LICENSE-APACHE # Apache 2.0 License terms -├── src/ # Core backend source directory -│ ├── main.rs # Binary entry point and CLI subcommand dispatcher +├── Cargo.toml # Primary Cargo workspace configuration +├── Cargo.lock # Dependency version lockfile +├── build.rs # Static asset embedding build script +├── README.md # Project landing documentation +├── LICENSE # Dual license declaration +├── LICENSE-MIT # MIT License text +├── LICENSE-APACHE # Apache 2.0 License text +├── src/ # Core backend source files +│ ├── main.rs # Entry point and subcommand router │ ├── lib.rs # Library root exporting domain modules -│ ├── api/ # Axum REST API handlers and routing table -│ ├── audit/ # Audit trail logging service and DTOs -│ ├── cli/ # Clap CLI subcommand implementations -│ ├── config/ # Configuration file parsing and environment loaders -│ ├── db/ # SQLx database abstraction layers and migrations -│ ├── error/ # Strongly typed application error enumerations -│ ├── identity/ # User, role, group, and tenant management services -│ ├── middleware/ # Security headers, authentication, and logging middlewares -│ ├── runtime/ # Application lifecycle, state machine, and signal hooks -│ └── security/ # Argon2id, BLAKE3, and rate-limiting modules -├── ui/ # WebAssembly Frontend crate (Dioxus 0.6) -│ ├── Cargo.toml # UI package crate manifest -│ ├── index.html # SPA entry point template -│ ├── assets/ # Static styling and JavaScript boot loader -│ └── src/ # Dioxus components, routes, and services -├── tests/ # Integration and end-to-end security test suites -├── scripts/ # Maintenance, build, and release helper scripts -├── deploy/ # Containerization, systemd, and reverse-proxy templates -└── docs/ # Architecture guides, ADRs, and technical specifications +│ ├── api/ # REST API handlers and endpoint routes +│ ├── audit/ # Audit trail service and data structures +│ ├── cli/ # CLI command parsing logic +│ ├── config/ # Configuration file parsing and environment logic +│ ├── db/ # SQLx abstractions and migration files +│ ├── error/ # Application error types +│ ├── identity/ # User, role, group, and tenant domain services +│ ├── middleware/ # Security header and authentication middlewares +│ ├── runtime/ # Lifecycle, state machine, and signal handlers +│ └── security/ # Password hashing, token hashing, and rate limiting +├── ui/ # WebAssembly frontend crate (Dioxus) +├── tests/ # Integration and security test suites +├── scripts/ # Maintenance and build helper scripts +├── deploy/ # Systemd service files and deployment templates +└── docs/ # Architecture documents and technical specifications ``` --- -## 16. Architectural Roadmap & Future Capabilities +# 16. Future Roadmap -The following capabilities represent planned architectural extensions: +Planned future architectural extensions include: -- **OpenID Connect (OIDC) & OAuth2 Provider**: Expanding identity capabilities to act as a full OIDC Authorization Server and Identity Provider (IdP). -- **WebAuthn / FIDO2 Passkeys**: Native passwordless authentication support using browser WebAuthn APIs. -- **Multi-Factor Authentication (MFA)**: Time-based One-Time Password (TOTP) integration using standard RFC 6238 algorithms. -- **SCIM 2.0 & Directory Sync**: System for Cross-domain Identity Management (SCIM) for automated user provisioning. -- **Observability Exports**: OpenTelemetry metrics and tracing exporters for Prometheus and Grafana monitoring stacks. +- **OpenID Connect (OIDC) & OAuth2 Server**: Native implementation enabling NX9-Auth to function as a full OIDC Authorization Server. +- **SAML 2.0 Support**: Enterprise federation support for identity provider integrations. +- **SCIM 2.0 Provisioning**: System for Cross-domain Identity Management interface for automated user synchronization. +- **Directory Integration**: LDAP and Active Directory authentication capability. +- **Multi-Factor Authentication (MFA)**: TOTP (RFC 6238) and WebAuthn / FIDO2 passkey support. - **High-Availability Clustering**: Distributed session cache synchronization across multi-region server nodes. +- **Observability Exporters**: Native OpenTelemetry metrics and tracing integration for Prometheus and Grafana monitoring stacks.