# NX9-Auth System Architecture Specification --- ## 1. System Overview & Executive Summary **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. 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. --- ## 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 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. - **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 | 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. | --- ## 5. Runtime Architecture ### 5.1 Runtime Core Components 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 ```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 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 Every incoming HTTP request traverses a strict layered middleware pipeline: ```mermaid flowchart TD Client([Client Request]) --> TCP[Tokio TcpListener] 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] Handler --> Service[Domain Service Layer] Service --> RepoTrait[Repository Trait Interface] RepoTrait --> DBImpl[SQLite / PostgreSQL Driver] DBImpl --> DB[(Database Engine)] DB --> DBImpl --> RepoTrait --> Service --> Handler Handler --> Response[JSON Response / SPA Assets] --> Client ``` --- ## 7. Repository & Database Architecture ### 7.1 Repository Abstraction Layer 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. ```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 } 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 NX9-Auth supports dual-mode authentication, accommodating both web browser clients (via HttpOnly cookies) and API consumers / SPA applications (via Bearer tokens). ```mermaid flowchart TD AuthRequest([Incoming Credentials / Request]) --> RouteType{Request Path?} RouteType -- POST /api/v1/auth/login --> 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] 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?} 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 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) NX9-Auth implements a hierarchical Role-Based Access Control (RBAC) model: ```mermaid flowchart LR User[User / 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?} GlobalPermissions --> AccessEvaluator AccessEvaluator -- Yes --> Allow[HTTP 200 / 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 Architecture 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: ```mermaid flowchart TD System[NX9-Auth System] --> TenantA[Tenant A] System --> TenantB[Tenant B] TenantA --> UsersA[Users & Service Accounts] TenantA --> GroupsA[Groups] TenantA --> AppsA[Applications] GroupsA --> RolesA[Roles] AppsA --> ResourcesA[API Resources & Tokens] TenantB --> UsersB[Users & 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. --- ## 12. Frontend Architecture (WebAssembly SPA) The administration interface is implemented as a pure WebAssembly Single Page Application (SPA) using Dioxus 0.6: ```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] ``` --- ## 13. Configuration System NX9-Auth loads configuration using a multi-tiered fallback hierarchy: ``` 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 ``` ### 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. --- ## 14. Deployment Architecture NX9-Auth is deployed as a single, self-contained Linux executable: ```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)] ``` ### 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 ``` --- ## 15. Repository Directory 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 │ ├── 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 ``` --- ## 16. Architectural Roadmap & Future Capabilities The following capabilities represent planned architectural extensions: - **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. - **High-Availability Clustering**: Distributed session cache synchronization across multi-region server nodes.