# 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. --- # 2. Design Philosophy NX9-Auth adheres to seven core design tenets: - **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. --- # 3. Architectural Principles The internal architecture is guided by structural design patterns: - **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. --- # 4. Technology Stack ### 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 The server runtime isolates process lifecycle management from business domain logic. ### 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 : 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 --> [*] ``` --- # 6. Request Lifecycle Every incoming HTTP request traverses a structured, layered processing pipeline. ```mermaid flowchart TD Client[Client Request] --> TCP[TCP Listener] TCP --> Router[Axum HTTP Router] 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 Interface] RepoTrait --> DBImpl[Database Provider] DBImpl --> DB[(Database Engine)] DB --> DBImpl --> RepoTrait --> Service --> Handler Handler --> Response[JSON Response or SPA Assets] --> Client ``` --- # 7. Repository Architecture NX9-Auth decouples persistence logic from domain services using trait abstractions. This ensures API handlers remain agnostic of the underlying storage backend. ### 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) +find_by_username(username) +create(user) +update(user) +delete(id) } class SqliteUserRepository { +find_by_id(id) +create(user) } class PostgresUserRepository { +find_by_id(id) +create(user) } class AuthService { +authenticate(credentials) } UserRepository <|.. SqliteUserRepository UserRepository <|.. PostgresUserRepository AuthService --> UserRepository ``` --- # 8. Authentication 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 HTTP Request] --> RouteType{Request Path} RouteType -- Login Route --> LoginHandler[Login Handler] LoginHandler --> VerifyPassword[Verify Password via Argon2id] 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 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[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 ``` --- # 9. Authorization NX9-Auth implements a hierarchical Role-Based Access Control (RBAC) authorization model. ```mermaid flowchart LR User[User or Service Account] --> UserRoles[Assigned Roles] UserRoles --> RolePermissions[Role Permissions] RolePermissions --> GlobalPermissions[Effective Permission Set] Request[API Endpoint Request] --> RequiredPerm[Required Permission Scope] RequiredPerm --> AccessEvaluator{Permission Granted} GlobalPermissions --> AccessEvaluator AccessEvaluator -- Yes --> Allow[Execute Handler] AccessEvaluator -- No --> Deny[HTTP 403 Forbidden] ``` --- # 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. --- # 11. Multi-tenancy 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 and Service Accounts] TenantA --> GroupsA[Groups] TenantA --> AppsA[Applications] GroupsA --> RolesA[Roles] AppsA --> ResourcesA[Resources and Tokens] TenantB --> UsersB[Users and Service Accounts] TenantB --> GroupsB[Groups] TenantB --> AppsB[Applications] ``` ### 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 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[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 NX9-Auth manages system parameters through a hierarchical configuration system. ### Configuration Precedence Order 1. Command Line Interface (CLI) Arguments 2. Environment Variables 3. Configuration Files (TOML format) 4. Built-in Defaults 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 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[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] ``` ### 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 Layout ```text / ├── 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/ # 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. Future Roadmap Planned future architectural extensions include: - **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.