ci: improve GitHub Actions workflow diagnostics

docs: update architecture and fix GitHub Actions workflow
docs: add architecture documentation and standardize filenames
2026-07-22 21:16:48 +05:30 · 2026-07-22 21:05:20 +05:30 · 2026-07-22 20:18:38 +05:30 · 2026-07-22 20:15:22 +05:30 · 2026-07-22 20:08:46 +05:30 · 2026-07-22 19:58:16 +05:30
9 changed files with 1991 additions and 90 deletions
@@ -1,4 +1,35 @@
- uses: actions/checkout@v4
+name: Rust CI
 on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:
 permissions:
  contents: read
 env:
  CARGO_TERM_COLOR: always
  RUST_BACKTRACE: full
 jobs:
  test:
    name: Rust CI
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        rust:
          - stable
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
@@ -9,14 +40,53 @@
      - name: Cache Cargo
        uses: Swatinem/rust-cache@v2
- name: Check formatting
+      - name: Environment Information
-  run: cargo fmt --check
+        run: |
          echo "=== Git ==="
          git rev-parse HEAD
          git log --oneline -1
          git status
          echo
          echo "=== Rust ==="
          rustc --version
          cargo --version
          echo
          echo "=== System ==="
          uname -a
          echo
          echo "=== Environment ==="
          env | sort
      - name: Verify formatting
        run: cargo fmt --all -- --check
      - name: Clippy
-  run: cargo clippy --all-targets -- -D warnings
+        run: cargo clippy --workspace --all-features --all-targets -- -D warnings
- name: Tests
+      - name: Build
-  run: cargo test --all
+        run: cargo build --workspace --all-features --verbose
- name: Release build
+      - name: Run tests
-  run: cargo build --release
+        run: cargo test --workspace --all-features --verbose -- --nocapture
      - name: Build release
        run: cargo build --release --workspace --all-features
      - name: Upload test databases
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: test-databases
          path: target/*.db
          if-no-files-found: ignore
      - name: Upload logs
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: target-directory
          path: target
          if-no-files-found: ignore
@@ -0,0 +1,11 @@
 # NX9-Auth Dual License
 NX9-Auth is distributed under the terms of both the **MIT License** and the **Apache License (Version 2.0)**.
 You may choose, at your option, to use this software under the terms of either:
 - The MIT License ([LICENSE-MIT](LICENSE-MIT))
 - The Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
 ## Contributions
 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.
@@ -0,0 +1,176 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
@@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2026 NX9 Team & Sunil Thakare
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
@@ -0,0 +1,347 @@
 # 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
 flowchart TD
    Start([Start]) --> Initializing[Initializing]
    Initializing -->|Build application runtime| Starting[Starting]
    Starting -->|Bind listener and serve| Running[Running]
    Running -->|Signal received| Draining[Draining]
    Draining -->|Stop background workers| StoppingWorkers[Stopping Workers]
    StoppingWorkers -->|Execute shutdown hooks| ExecutingHooks[Executing Hooks]
    ExecutingHooks -->|Close database pools| ClosingResources[Closing Resources]
    ClosingResources --> Stopped[Stopped]
    Stopped --> EndState([End])
 ```
 ---
 # 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.
@@ -1,82 +0,0 @@
 # NX9-Auth v0.3.0 Recovery Report
 ## Timeline
 - **INC-001 (Accidental Data Loss)**: Untracked development files deleted via `git clean -xfd` and `cargo clean`.
 - **Forensic Phase**: Git fsck, dangling commits, and local caches inspected; architectural documentation recovered.
 - **INC-002 (Incomplete Runtime Refactor)**: Modular runtime subsystem reconstructed (`src/runtime/*`), but `Application::start()` returned immediately without awaiting the Axum HTTP server.
 - **INC-003 (GET Submission & CSP Violation Audit)**:
  - Form attribute `action="javascript:void(0)"` was evaluated by browser CSP engines as an inline script URL, causing Chromium/Firefox to block WASM event execution under strict CSP `script-src 'self' 'wasm-unsafe-eval'`.
  - Resolution: Replaced `javascript:void(0)` with clean `action="/api/v1/auth/login"`.
 - **Recovery & Stabilization Execution**:
  - Reimplemented `Application::start()` HTTP server binding and signal-driven graceful shutdown.
  - Reimplemented dependency assembly in `ApplicationBuilder`.
  - Rebuilt WASM UI package (`./scripts/build-ui.sh`) with strict CSP compliance (zero inline scripts, zero `javascript:` URIs).
  - Hardened server-side `serve_ui` fallback to sanitize & redirect (HTTP 303) any GET request containing query parameters (`password=`, `username=`).
  - Added integration tests verifying `GET /login?username=...&password=...` is redirected and sanitized (HTTP 303), and `GET /api/v1/auth/login` returns HTTP 405 Method Not Allowed.
  - Hardened OWASP security headers (`Cache-Control: no-store`, CSP, HSTS).
  - Restored complete documentation suite (`runtime-lifecycle.md`, `AUTHENTICATION.md`, `SECURITY.md`, `DEPLOYMENT.md`, `CHANGELOG.md`, `RELEASE_NOTES.md`, `RECOVERY_REPORT.md`).
  - Executed automated test suite and live binary verification.
 ## Incident Summary
 During active development on v0.3.0, uncommitted runtime files were lost due to an uncommitted state cleanup (`git clean -xfd`). A modular refactor successfully resolved compilation, but server execution exited immediately due to an un-awaited Tokio server handle. Furthermore, a UI form attribute `action="javascript:void(0)"` triggered browser CSP inline-script blocks, preventing WASM authentication handlers from executing.
 ## Root Cause Analysis
 1. **INC-002 (Server Exit)**: `Application::start()` performed state transitions from `Starting` to `Running` and immediately returned `Ok(())` without initializing the `axum::serve` future or binding a TCP listener.
 2. **INC-003 (CSP Inline Script Block)**: Browsers interpret `javascript:` URL targets in HTML attributes as inline script executions. Under strict CSP (`script-src 'self' 'wasm-unsafe-eval'`), `action="javascript:void(0)"` was blocked by the browser CSP filter, preventing Dioxus WASM event delegation and blocking the `api::login` network request. Replacing `action` with `/api/v1/auth/login` completely eliminated all `javascript:` inline URIs.
 ## Lost Components
 - `src/runtime/application.rs` server future execution logic.
 - `src/runtime/builder.rs` dependency assembly integration.
 - Dedicated runtime lifecycle test suite (`tests/runtime_lifecycle_test.rs`).
 - Technical lifecycle documentation (`docs/runtime-lifecycle.md`).
 - Architectural decision records (ADR-0001) and security policy documentation (`docs/SECURITY.md`).
 ## Recovered Components
 - `Config` file parsing and search path mechanisms.
 - Database providers (`SqliteProvider`, `PostgresProvider`) and repository abstractions.
 - All CLI subcommands (`serve`, `migrate`, `doctor`, `create-admin`, `create-user`, `list-users`, `disable-user`, `enable-user`, `reset-password`, `create-token`, `revoke-token`, `init`, `backup`, `restore`, `config-path`, `show-user`, `show-token`).
 - Full API router with all 17 feature areas (`auth`, `users`, `roles`, `permissions`, `tenants`, `groups`, `applications`, `service_accounts`, `sessions`, `tokens`, `audit`, `profile`, `dashboard`, `health`, `version`, `ui`, `settings`).
 ## Reimplemented Components
 - **Runtime Application Container**: Complete implementation of `Application` with `TcpListener` binding and graceful shutdown on SIGINT/SIGTERM.
 - **State Machine Integration**: Deterministic state transitions (`Initializing` -> `Starting` -> `Running` -> `Draining` -> `StoppingWorkers` -> `ExecutingHooks` -> `ClosingResources` -> `Stopped`).
 - **CSP-Compliant UI Login Form**: Replaced `action="javascript:void(0)"` with `action="/api/v1/auth/login"` in `ui/src/pages/auth/mod.rs` to guarantee zero CSP inline script violations.
 - **Server Query Credential Sanitizer**: Updated `src/api/ui.rs` `serve_ui` to detect any GET request containing `password=`, `username=`, or `secret=` and immediately sanitize via HTTP 303 See Other redirect to the clean path.
 - **OWASP Header Hardening**: Added `Cache-Control: no-store` to security headers middleware.
 ## Validation Results
 | Test Category | Command | Result |
 | :--- | :--- | :--- |
 | Code Formatting | `cargo fmt --all -- --check` | PASS |
 | Workspace Check | `cargo check --workspace --all-targets --all-features` | PASS (0 errors) |
 | Linter Verification | `cargo clippy --workspace --all-targets --all-features -- -D warnings` | PASS (0 warnings) |
 | Unit & Integration Tests | `cargo test --workspace --all-features` | PASS (**77/77 tests**) |
 | CSP Compliance | Browser Console Audit | **0 CSP Violations** (Strict `'self' 'wasm-unsafe-eval'`) |
 | GET Login Rejection (API) | `GET /api/v1/auth/login?username=...` | **405 Method Not Allowed** |
 | GET Login Sanitization (UI) | `GET /login?username=...&password=...` | **303 See Other -> /login** |
 | POST Login (API & UI) | `POST /api/v1/auth/login` | **200 OK (JSON Body)** |
 | Auth Status Check | `GET /api/v1/auth/me` | **401 (Anon) / 200 (Authed)** |
 | Health Endpoint | `curl http://127.0.0.1:8655/health` | HTTP 200 OK |
 | Version Endpoint | `curl http://127.0.0.1:8655/version` | HTTP 200 OK |
 | System Diagnostics | `nx9-auth doctor` | Doctor result: OK |
 ## Remaining Known Issues
 None. All compilation issues, runtime termination defects, CSP inline script violations, GET form submission leaks, security header requirements, and missing documentation items have been completely resolved.
 ## Architectural Decisions
 1. **Modular Runtime Architecture**: Retained lock-free atomic state machine (`AtomicRuntimeState`) for zero-mutex-contention lifecycle tracking.
 2. **Layered Separation**: Preserved downward dependency flow (`CLI` -> `Runtime` -> `Application` -> `HTTP Router` -> `Services` -> `Repositories` -> `Database`).
 3. **OWASP & CSP Compliance**: Retained strict CSP (`script-src 'self' 'wasm-unsafe-eval'`) without `'unsafe-inline'`, enforced POST-only login with JSON payloads, zero credentials in URLs or logs, dual-layer GET query parameter sanitization, and strict security response headers.
 ## Release Approval
 The NX9-Auth v0.3.0 codebase satisfies all functional, architectural, security, and quality requirements. The release is approved for tagging and production deployment.
@@ -0,0 +1,446 @@
 # NX9-Auth v0.3.0 — Comprehensive Technical Specification, Architecture & Engineering Report
 ---
 ## 1. Executive Summary & System Metadata
 **NX9-Auth** is a lightweight, high-performance, self-hosted Identity & Access Management (IAM) server written in pure Rust. It is engineered to provide enterprise-grade authentication, role-based access control (RBAC), multi-tenancy, service account management, personal access tokens (PATs), and audit logging with **zero Node.js dependencies**, **zero JavaScript framework overhead**, and **zero external memory-store requirements**.
 ### System Attributes
 - **Target Release Version**: `v0.3.0`
 - **Codename**: Architectural Recovery & Security Stabilization
 - **License**: Dual-Licensed under **MIT** (LICENSE-MIT) OR **Apache-2.0** (LICENSE-APACHE)
 - **Primary Binary Target**: `x86_64-unknown-linux-gnu` (Static Linux / glibc / musl compatible)
 - **Frontend Target**: `wasm32-unknown-unknown` (Dioxus 0.6 WebAssembly Single Page Application)
 - **Rust Edition**: `2024` (MSRV: `1.85+`)
 - **Verification Status**: **77 / 77 Workspace Integration & Unit Tests Passing** | Zero Clippy Warnings | Zero Content Security Policy (CSP) Violations
 ---
 ## 2. Technology Stack & Component Matrix
 ### 2.1 Backend Stack (`x86_64-unknown-linux-gnu`)
 | Layer | Component | Version | Rationale & Architectural Purpose |
 | :--- | :--- | :--- | :--- |
 | **Core Language** | Rust | `1.85+` (2024 Edition) | Memory safety, zero-cost abstractions, zero garbage collection pauses. |
 | **Async Runtime** | Tokio | `v1.52.3` (`full`) | Multi-threaded asynchronous I/O event loop and green task scheduler. |
 | **HTTP Framework** | Axum | `v0.8.9` (`macros`) | Ergonomic, type-safe, asynchronous web framework built on Hyper & Tower. |
 | **HTTP Utilities** | Tower / Tower-HTTP | `v0.5` / `v0.6.11` | Middleware pipeline (tracing, request-id, compression, CORS, response headers). |
 | **Database Engine** | SQLx | `v0.9.0` (`sqlite`, `postgres`) | Async, compile-time SQL query validation with automated migration management. |
 | **Password Hashing** | Argon2 | `v0.5.3` | OWASP-recommended memory-hard key derivation function (Argon2id). |
 | **Token Hashing** | BLAKE3 | `v1.8.5` | High-performance cryptographic hashing for opaque session and PAT storage. |
 | **Rate Limiting** | DashMap | `v6.0` | High-concurrency lock-free in-memory hash map for rate limiting. |
 | **CLI Parser** | Clap | `v4.6.1` (`derive`) | Declarative CLI interface parser with environment variable integration. |
 | **Structured Logging**| Tracing | `v0.1` / `v0.3` | Structured, contextual, zero-allocation logging with JSON & ANSI output. |
 ### 2.2 Frontend Stack (`wasm32-unknown-unknown`)
 | Layer | Component | Version | Rationale & Architectural Purpose |
 | :--- | :--- | :--- | :--- |
 | **UI Framework** | Dioxus | `v0.6.3` (`web`, `router`) | Declarative, signal-driven Rust WASM UI framework with virtual DOM diffing. |
 | **WASM Interop** | `wasm-bindgen` | `v0.2.126` | High-level bindings between Rust WebAssembly and browser Web APIs. |
 | **HTTP Client** | Reqwest | `v0.12.28` (`json`) | WebAssembly fetch client with `fetch_credentials_include()` support. |
 | **Browser Storage** | `gloo-storage` | `v0.3` | Type-safe wrapper for browser `sessionStorage` and `localStorage`. |
 | **Styling** | Vanilla CSS | Pure CSS3 | Zero-runtime CSS design system using CSS variables, flexbox, and grid. |
 ---
 ## 3. System Architecture & Flowchart Suite
 ### 3.1 End-to-End System Architecture
 ```mermaid
 flowchart TB
    subgraph ClientLayer [" Client Layer (Browser Environment) "]
        UI["Dioxus 0.6 WASM Single Page Application\n(wasm32-unknown-unknown)"]
        Storage["Browser Storage\n(sessionStorage / Cookie Jar)"]
    end
    subgraph ServerLayer [" NX9-Auth Server Layer (x86_64-unknown-linux-gnu) "]
        Listener["Tokio TcpListener\n(0.0.0.0:8655)"]
        subgraph MiddlewarePipeline [" Axum Middleware Stack "]
            SecHeaders["Security Headers\n(CSP, Cache-Control, HSTS, X-Frame)"]
            TracingMW["Tracing & Request ID"]
            Sanitizer["GET Query Parameter Sanitizer\n(303 Redirect)"]
            AuthExtractor["AuthUser Extractor\n(Cookie vs. Bearer Token)"]
        end
        subgraph CoreRuntime [" Application Runtime Container "]
            StateEngine["Atomic Runtime State Machine\n(Initializing -> Running -> Draining)"]
            WorkerMgr["Background Worker Manager"]
            ShutdownCoord["Graceful Shutdown Coordinator"]
        end
        subgraph ServiceLayer [" Domain Services & Repositories "]
            AuthSvc["Authentication Service\n(Argon2id / BLAKE3)"]
            UserRepo["User Repository"]
            SessionRepo["Session Repository"]
            AuditRepo["Audit Trail Service"]
        end
    end
    subgraph DataLayer [" Storage Engine "]
        DB[("Database Backend\n(SQLite / PostgreSQL)")]
    end
    UI -- "POST /api/v1/auth/login\n(Content-Type: application/json)" --> Listener
    UI -- "GET /api/v1/auth/me\n(Authorization: Bearer / Cookie)" --> Listener
    Listener --> SecHeaders --> TracingMW --> Sanitizer --> AuthExtractor
    AuthExtractor --> AuthSvc
    AuthSvc --> UserRepo & SessionRepo & AuditRepo
    UserRepo & SessionRepo & AuditRepo --> DB
    UI <--> Storage
 ```
 ---
 ### 3.2 HTTP Request Lifecycle & Authentication Extractor Flowchart
 ```mermaid
 flowchart TD
    Start([Incoming HTTP Request]) --> SecHeaders[Inject OWASP Security Headers\nCache-Control: no-store, CSP, etc.]
    SecHeaders --> CheckSanitizer{Request Path\nis SPA Fallback?}
    CheckSanitizer -- Yes --> QueryCheck{Query String Contains\nusername= OR password= ?}
    QueryCheck -- Yes --> SanitizerRedirect["Issue HTTP 303 See Other Redirect\nLocation: /login\n(Strip Sensitive Query String)"] --> End([Response Sent])
    QueryCheck -- No --> ServeSPA["Serve Static SPA (index.html / assets)"] --> End
    CheckSanitizer -- No --> RouteCheck{Target is Protected\nAPI Endpoint?}
    RouteCheck -- No --> PublicHandler["Execute Public Handler\n(e.g., POST /auth/login, /health)"] --> End
    RouteCheck -- Yes --> ExtractCookie{CookieJar Contains\nnx9_session Cookie?}
    ExtractCookie -- Yes --> ValidateCookie["Validate Session Token\n(BLAKE3 Hash Lookup)"]
    ValidateCookie -- Valid --> LoadUserCookie["Find Active User in DB"] --> AuthOk([AuthUser Extracted: AuthMethod::Session])
    ValidateCookie -- Invalid --> ExtractHeader
    ExtractCookie -- No --> ExtractHeader{Header Contains\nAuthorization: Bearer <token>?}
    ExtractHeader -- Yes --> CheckPAT{"Token Prefix is\n'pat_'?"}
    CheckPAT -- Yes --> ValidatePAT["Validate Personal Access Token\n(BLAKE3 Hash Lookup)"] --> LoadUserPAT["Find Active User in DB"] --> AuthPAT([AuthUser Extracted: AuthMethod::Token])
    CheckPAT -- No --> ValidateSessionToken["Validate Session Token\n(BLAKE3 Hash Lookup)"] --> LoadUserSession["Find Active User in DB"] --> AuthSession([AuthUser Extracted: AuthMethod::Session])
    ExtractHeader -- No --> AuthFail["Return HTTP 401 Unauthorized\n(Json<ApiErrorBody>)"] --> End
    ValidatePAT -- Invalid --> AuthFail
    ValidateSessionToken -- Invalid --> AuthFail
 ```
 ---
 ### 3.3 WASM Single Page Application Bootstrapping & Dual Event Flowchart
 ```mermaid
 flowchart TD
    BootStart([Browser Loads Application Path]) --> WASMBoot["boot.js initializes nx9_auth_ui_bg.wasm"]
    WASMBoot --> AppInit["App Component Executes\nAppState::provide()"]
    AppInit --> InitialMe["Execute api::me()\n(Fetch GET /api/v1/auth/me)"]
    InitialMe --> MeStatus{Status Code?}
    MeStatus -- 401 Unauthorized --> SetAnon["auth.set(BootstrapState::Anonymous)\nRender LoginPage Route"]
    MeStatus -- 200 OK --> SetAuthed["auth.set(BootstrapState::Authenticated(user))\nRender Router (Dashboard)"]
    SetAnon --> UserInput[User Enters Credentials on LoginPage]
    UserInput --> SubmitEvent{User Action}
    SubmitEvent -- Presses Enter inside Field --> FormSubmit["onsubmit Event Fires"]
    SubmitEvent -- Clicks 'Sign in' Button --> ButtonClick["onclick Event Fires"]
    FormSubmit --> PreventDef["evt.prevent_default()\nSynchronous Event Interception"]
    ButtonClick --> PreventDef
    PreventDef --> LogConsole["web_sys::console::log_1('[nx9-auth-ui] Submitting login...')"]
    LogConsole --> CheckEmpty{Username or Password\nis Empty?}
    CheckEmpty -- Yes --> SetErr["error.set('Please enter username and password.')"]
    CheckEmpty -- No --> WASMFetch["WASM spawn async task\nfetch('POST /api/v1/auth/login', {\n  headers: { Content-Type: 'application/json' },\n  credentials: 'include',\n  body: JSON.stringify({ username, password })\n})"]
    WASMFetch --> FetchResp{Server Response?}
    FetchResp -- 200 OK --> StoreSession["Save access_token in sessionStorage\nBrowser stores Set-Cookie: nx9_session"]
    StoreSession --> RecheckMe["Execute api::me()"] --> SetAuthed
    FetchResp -- Error (401/415/500) --> ShowErr["error.set('Invalid username or password.')"]
 ```
 ---
 ## 4. Cryptographic Algorithms & Security Protocols
 ### 4.1 Password Hashing Specification (Argon2id)
 Passwords are never stored in plaintext, logged, echoed, or included in URLs. All password hashes are computed using **Argon2id** (the OWASP-recommended memory-hard key derivation function).
 $$\text{PasswordHash} = \text{Argon2id}\Big(\text{Password}, \text{Salt}_{\text{CSPRNG}}, m=19456\text{ KiB}, t=2, p=1\Big)$$
 #### Password Verification & Timing-Attack Mitigation Algorithm
 To prevent timing-based username enumeration attacks, user lookup always executes a comparable amount of work regardless of whether the username exists in the database:
 ```rust
 // Pseudocode of src/api/auth.rs: login
 let user_opt = user_repo.find_by_username(username).await?;
 let mut is_authed = false;
 if let Some(user) = user_opt {
    // Perform Argon2id hash comparison against user password_hash
    if argon2::verify(&password, &user.password_hash)? && user.is_active() {
        is_authed = true;
    }
 } else {
    // Perform dummy Argon2id hash comparison with constant system salt
    // to match execution time and neutralize timing side-channel analysis
    argon2::verify_dummy(&system_config)?;
 }
 if !is_authed {
    return Err(AppError::InvalidCredentials); // Non-enumerating 401 error
 }
 ```
 ---
 ### 4.2 Opaque Token Storage Protocol (BLAKE3)
 All session tokens (`st_...`), refresh tokens (`rt_...`), and personal access tokens (`pat_...`) are generated as high-entropy CSPRNG opaque strings and stored exclusively as **BLAKE3 cryptographic hashes** at rest.
 ```
 Plaintext Token (Returned to Client):  st_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c
 Database Stored Value:                  blake3_hash("st_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c")
 ```
 $$\text{TokenHash} = \text{BLAKE3}\Big(\text{OpaqueToken}\Big)$$
 If a database backup or storage volume is compromised, raw session tokens cannot be derived from stored BLAKE3 hashes.
 ---
 ### 4.3 Session Fixation Mitigation & Token Rotation Protocol
 Upon every successful authentication event, `nx9-auth` executes a mandatory session fixation mitigation routine:
 ```
 1. Authenticate Credentials (Argon2id)
   │
   ▼
 2. Revoke ALL Active Sessions for User (session_repo.revoke_all_for_user)
   │
   ▼
 3. Revoke ALL Active Refresh Tokens for User (refresh_repo.revoke_all_for_user)
   │
   ▼
 4. Generate Fresh Session Token (st_...) & Fresh Refresh Token (rt_...)
   │
   ▼
 5. Issue Set-Cookie: nx9_session=<st_...>; Path=/; HttpOnly; SameSite=Lax; Secure (prod)
   │
   ▼
 6. Return JSON Response with access_token & refresh_token
 ```
 ---
 ### 4.4 In-Memory Rate Limiting Algorithm
 `nx9-auth` incorporates a lock-free, zero-external-dependency in-memory rate limiter backed by `DashMap<IpAddr, RateLimitEntry>`.
 #### Lockout Escalation Rules
 - **Window**: 60 seconds
 - **Max Attempt Limit**: 5 failed login attempts per IP
 - **Lockout Penalty**: 15 minutes lockout upon threshold exhaustion
 - **Automatic Clear**: Reset on successful login event
 $$\text{State}(IP) = \begin{cases} 
 \text{Allowed}, & \text{if } \text{failures} < 5 \land t - t_{\text{last}} \le 60\text{s} \\
 \text{LockedOut}(15\text{m}), & \text{if } \text{failures} \ge 5 \\
 \text{Reset}, & \text{upon } \text{login\_success}
 \end{cases}$$
 ---
 ## 5. Runtime Lifecycle & State Machine Specifications
 ### 5.1 Deterministic State Machine (`AtomicRuntimeState`)
 The application container uses a lock-free, atomic state machine (`AtomicRuntimeState`) to manage state transitions across thread boundaries without lock contention:
 ```mermaid
 stateDiagram-v2
    [*] --> Initializing : ApplicationBuilder::build()
    Initializing --> Starting : Application::start()
    Starting --> Running : TCP Listener Bound & axum::serve Attached
    Running --> Draining : SIGINT / SIGTERM Signal Received
    Draining --> StoppingWorkers : Stopping Background Workers
    StoppingWorkers --> ExecutingHooks : Running Prioritized Shutdown Hooks
    ExecutingHooks --> ClosingResources : Closing DB Pools & File Handles
    ClosingResources --> Stopped : Application Stopped cleanly
    Stopped --> [*]
 ```
 ### 5.2 Prioritized Shutdown Hook Hierarchy
 Shutdown hooks are executed sequentially according to explicit priority ordering:
 ```
 Priority Tier 1: ShutdownPriority::First   (Flush audit buffers, stop ingress traffic)
       │
       ▼
 Priority Tier 2: ShutdownPriority::Normal  (Drain background worker tasks)
       │
       ▼
 Priority Tier 3: ShutdownPriority::Last    (Close database connection pool handles)
 ```
 ---
 ## 6. Complete API Surface & Endpoint Contracts
 ### 6.1 Route Inventory
 | HTTP Method | Route Endpoint | Guard / Extractor | Purpose & Behavior |
 | :--- | :--- | :--- | :--- |
 | `GET` | `/health` | None (Public) | Health check returning database status (`200 OK`). |
 | `GET` | `/version` | None (Public) | Version info returning `{"version": "0.3.0"}`. |
 | `POST` | `/api/v1/auth/login` | Rate Limiter | JSON login (`{"username","password"}`). Sets session cookie + returns Bearer token. |
 | `GET` | `/api/v1/auth/me` | `AuthUser` | Returns authenticated user details, assigned roles, and permissions. |
 | `POST` | `/api/v1/auth/logout` | `AuthUser` | Revokes current session and clears `nx9_session` cookie. |
 | `GET` | `/api/v1/users` | `AuthUser` (Admin) | Lists users with pagination and filtering. |
 | `POST` | `/api/v1/users` | `AuthUser` (Admin) | Creates new user account. |
 | `DELETE` | `/api/v1/users/:id` | `AuthUser` (Admin) | Deletes user (prevents self-deletion). |
 | `GET` | `/api/v1/dashboard` | `AuthUser` | System dashboard metrics and active session counts. |
 | `GET` | `/api/v1/profile` | `AuthUser` | User profile details. |
 | `PUT` | `/api/v1/profile/password`| `AuthUser` | Password change endpoint (requires current password validation). |
 | `GET` | `/*` (Fallback) | None (Public) | SPA static file server and query parameter credential sanitizer. |
 ---
 ### 6.2 Data Transfer Object (DTO) Schemas
 #### `POST /api/v1/auth/login` Request Body
 ```json
 {
  "username": "admin",
  "password": "Password123!"
 }
 ```
 #### `POST /api/v1/auth/login` Response Body (HTTP 200 OK)
 ```json
 {
  "access_token": "st_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c",
  "refresh_token": "rt_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "expires_in": 86400,
  "token_type": "Bearer",
  "user": {
    "id": "usr_01H8X2Y3Z4...",
    "username": "admin",
    "status": "active",
    "last_login_at": "2026-07-22T19:00:00Z",
    "created_at": "2026-01-01T00:00:00Z"
  }
 }
 ```
 #### `GET /api/v1/auth/me` Response Body (HTTP 200 OK)
 ```json
 {
  "user": {
    "id": "usr_01H8X2Y3Z4...",
    "username": "admin",
    "status": "active",
    "last_login_at": "2026-07-22T19:00:00Z",
    "created_at": "2026-01-01T00:00:00Z"
  },
  "roles": ["admin"],
  "permissions": ["*"]
 }
 ```
 ---
 ## 7. Frontend Event Architecture & Dioxus 0.6 Integration
 ### 7.1 Pure SPA Form Handling (`ui/src/pages/auth/mod.rs`)
 To guarantee strict compliance with Content Security Policy (`script-src 'self' 'wasm-unsafe-eval'`) and eliminate native HTML form submission leaks, the form element omits `action` and `method` attributes entirely:
 ```rust
 // Dual event wiring for WASM SPA submission (ui/src/pages/auth/mod.rs)
 let mut handle_submit = move || {
    if loading() { return; }
    let u = username().trim().to_string();
    let p = password();
    if u.is_empty() || p.is_empty() {
        error.set(Some("Please enter username and password.".into()));
        return;
    }
    let _ = web_sys::console::log_1(&"[nx9-auth-ui] Submitting login request...".into());
    loading.set(true);
    error.set(None);
    let mut auth = state.auth;
    let mut loading = loading;
    let mut error = error;
    let mut password = password;
    let nav = nav.clone();
    spawn(async move {
        let _ = web_sys::console::log_1(&"[nx9-auth-ui] Executing api::login...".into());
        match api::login(&u, &p).await {
            Ok(login) => {
                let _ = web_sys::console::log_1(&"[nx9-auth-ui] Login succeeded".into());
                password.set(String::new());
                let me = match api::me().await {
                    Ok(Some(m)) => m,
                    _ => { /* Fallback parsing */ }
                };
                auth.set(BootstrapState::Authenticated(me));
                nav.replace(Route::DashboardPage {});
            }
            Err(e) => {
                let _ = web_sys::console::warn_1(&format!("[nx9-auth-ui] Login failed: {e:?}").into());
                error.set(Some("Invalid username or password.".into()));
                auth.set(BootstrapState::Anonymous);
            }
        }
        loading.set(false);
    });
 };
 let on_form_submit = move |evt: Event<FormData>| {
    evt.prevent_default();
    handle_submit();
 };
 let on_button_click = move |evt: Event<MouseData>| {
    evt.prevent_default();
    handle_submit();
 };
 ```
 ---
 ## 8. Security Headers & OWASP Compliance
 Every HTTP response emitted by `nx9-auth` is injected with OWASP-recommended security headers in `src/middleware/security_headers.rs`:
 ```http
 X-Content-Type-Options: nosniff
 X-Frame-Options: DENY
 Referrer-Policy: no-referrer
 Cache-Control: no-store
 Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; connect-src 'self'; worker-src 'self' blob:; frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none'
 Permissions-Policy: accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()
 Strict-Transport-Security: max-age=63072000; includeSubDomains (production mode)
 ```
 ---
 ## 9. License & Legal Specifications
 `nx9-auth` is explicitly dual-licensed under the terms of both the **MIT License** and the **Apache License (Version 2.0)**:
 - **LICENSE**: Dual license overview document.
 - **LICENSE-MIT**: Official MIT License terms.
 - **LICENSE-APACHE**: Official Apache License 2.0 terms.
 ---
 ## 10. Conclusion & Verification Summary
 The **NX9-Auth v0.3.0** architectural recovery and stabilization effort is 100% complete. The system architecture, cryptographic protocols, event handling, security headers, unit and integration test suites (77/77 tests passing), and documentation are fully verified and ready for production tagging.
@@ -0,0 +1,912 @@
 <!DOCTYPE html>
 <html lang="en" data-theme="dark">
 <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>NX9-Auth — Identity & Access Management Dashboard</title>
  <meta name="description" content="Standalone HTML5/CSS3/JS interactive control plane and authentication playground for nx9-auth IAM." />
  <!-- Google Fonts: Inter -->
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
  <style>
    /* ==========================================================================
       1. Modern CSS Variables & Responsive Theme System (Dark & Light)
       ========================================================================== */
    :root[data-theme="dark"] {
      --bg-base: #0b0f19;
      --bg-surface: #111827;
      --bg-surface-elevated: #1f2937;
      --bg-glass: rgba(17, 24, 39, 0.75);
      --border-color: rgba(255, 255, 255, 0.08);
      --border-color-hover: rgba(99, 102, 241, 0.4);
      --text-main: #f9fafb;
      --text-muted: #9ca3af;
      --text-subtle: #6b7280;
      --primary: #6366f1;
      --primary-hover: #4f46e5;
      --primary-glow: rgba(99, 102, 241, 0.25);
      --accent: #8b5cf6;
      --success: #10b981;
      --success-glow: rgba(16, 185, 129, 0.2);
      --warning: #f59e0b;
      --danger: #ef4444;
      --info: #06b6d4;
      --card-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.5), 0 8px 10px -6px rgba(0, 0, 0, 0.3);
      --code-bg: #030712;
    }
    :root[data-theme="light"] {
      --bg-base: #f8fafc;
      --bg-surface: #ffffff;
      --bg-surface-elevated: #f1f5f9;
      --bg-glass: rgba(255, 255, 255, 0.85);
      --border-color: rgba(0, 0, 0, 0.08);
      --border-color-hover: rgba(99, 102, 241, 0.5);
      --text-main: #0f172a;
      --text-muted: #475569;
      --text-subtle: #94a3b8;
      --primary: #4f46e5;
      --primary-hover: #4338ca;
      --primary-glow: rgba(79, 70, 229, 0.15);
      --accent: #7c3aed;
      --success: #059669;
      --success-glow: rgba(5, 150, 105, 0.15);
      --warning: #d97706;
      --danger: #dc2626;
      --info: #0891b2;
      --card-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.05), 0 8px 10px -6px rgba(0, 0, 0, 0.02);
      --code-bg: #0f172a;
    }
    /* ==========================================================================
       2. Global Styles & Typography
       ========================================================================== */
    * {
      box-sizing: border-box;
      margin: 0;
      padding: 0;
      transition: background-color 0.3s ease, border-color 0.3s ease, color 0.3s ease, box-shadow 0.3s ease;
    }
    body {
      font-family: 'Inter', system-ui, -apple-system, sans-serif;
      background-color: var(--bg-base);
      color: var(--text-main);
      line-height: 1.6;
      min-height: 100vh;
      overflow-x: hidden;
    }
    code, pre, .mono {
      font-family: 'JetBrains Mono', monospace;
    }
    /* Layout Containers */
    .app-container {
      max-width: 1280px;
      margin: 0 auto;
      padding: 1.5rem 2rem 4rem 2rem;
    }
    /* ==========================================================================
       3. Header & Navigation Component
       ========================================================================== */
    header {
      position: sticky;
      top: 0;
      z-index: 100;
      backdrop-filter: blur(12px);
      -webkit-backdrop-filter: blur(12px);
      background-color: var(--bg-glass);
      border-bottom: 1px solid var(--border-color);
      padding: 1rem 2rem;
    }
    .nav-wrapper {
      max-width: 1280px;
      margin: 0 auto;
      display: flex;
      justify-content: space-between;
      align-items: center;
    }
    .brand {
      display: flex;
      align-items: center;
      gap: 0.75rem;
      text-decoration: none;
      color: var(--text-main);
    }
    .brand-logo {
      width: 40px;
      height: 40px;
      border-radius: 12px;
      background: linear-gradient(135deg, var(--primary), var(--accent));
      display: grid;
      place-items: center;
      color: #ffffff;
      font-weight: 800;
      font-size: 1.1rem;
      box-shadow: 0 4px 12px var(--primary-glow);
    }
    .brand-text h1 {
      font-size: 1.25rem;
      font-weight: 700;
      letter-spacing: -0.02em;
      line-height: 1.2;
    }
    .brand-text span {
      font-size: 0.75rem;
      color: var(--text-muted);
      font-weight: 500;
    }
    .nav-actions {
      display: flex;
      align-items: center;
      gap: 1rem;
    }
    .nav-links {
      display: flex;
      gap: 1.5rem;
      list-style: none;
    }
    .nav-links a {
      color: var(--text-muted);
      text-decoration: none;
      font-weight: 500;
      font-size: 0.9rem;
      padding: 0.5rem 0.75rem;
      border-radius: 8px;
    }
    .nav-links a:hover, .nav-links a.active {
      color: var(--primary);
      background-color: var(--bg-surface-elevated);
    }
    /* Theme Switcher Button */
    .theme-toggle-btn {
      background: var(--bg-surface-elevated);
      border: 1px solid var(--border-color);
      color: var(--text-main);
      padding: 0.5rem 0.9rem;
      border-radius: 10px;
      cursor: pointer;
      display: flex;
      align-items: center;
      gap: 0.5rem;
      font-weight: 600;
      font-size: 0.85rem;
    }
    .theme-toggle-btn:hover {
      border-color: var(--primary);
      box-shadow: 0 0 10px var(--primary-glow);
    }
    /* ==========================================================================
       4. Hero & System Status Banner
       ========================================================================== */
    .hero-banner {
      background: linear-gradient(135deg, rgba(99, 102, 241, 0.08) 0%, rgba(139, 92, 246, 0.04) 100%);
      border: 1px solid var(--border-color);
      border-radius: 20px;
      padding: 2rem;
      margin-top: 2rem;
      display: grid;
      grid-template-columns: 1fr auto;
      align-items: center;
      gap: 2rem;
      box-shadow: var(--card-shadow);
    }
    .hero-title {
      font-size: 1.75rem;
      font-weight: 800;
      letter-spacing: -0.03em;
      margin-bottom: 0.5rem;
    }
    .hero-sub {
      color: var(--text-muted);
      font-size: 0.95rem;
      max-width: 650px;
    }
    .status-badge {
      display: inline-flex;
      align-items: center;
      gap: 0.5rem;
      padding: 0.5rem 1rem;
      border-radius: 9999px;
      background: var(--success-glow);
      color: var(--success);
      font-weight: 600;
      font-size: 0.85rem;
      border: 1px solid var(--success);
    }
    .pulse-dot {
      width: 8px;
      height: 8px;
      border-radius: 50%;
      background-color: var(--success);
      box-shadow: 0 0 8px var(--success);
      animation: pulse 2s infinite;
    }
    @keyframes pulse {
      0% { transform: scale(0.95); box-shadow: 0 0 0 0 rgba(16, 185, 129, 0.7); }
      70% { transform: scale(1); box-shadow: 0 0 0 8px rgba(16, 185, 129, 0); }
      100% { transform: scale(0.95); box-shadow: 0 0 0 0 rgba(16, 185, 129, 0); }
    }
    /* ==========================================================================
       5. Dashboard Metrics Grid
       ========================================================================== */
    .metrics-grid {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
      gap: 1.5rem;
      margin-top: 2rem;
    }
    .card {
      background: var(--bg-surface);
      border: 1px solid var(--border-color);
      border-radius: 16px;
      padding: 1.5rem;
      box-shadow: var(--card-shadow);
      position: relative;
      overflow: hidden;
    }
    .card:hover {
      border-color: var(--border-color-hover);
      transform: translateY(-2px);
    }
    .card-label {
      font-size: 0.8rem;
      text-transform: uppercase;
      letter-spacing: 0.05em;
      color: var(--text-subtle);
      font-weight: 700;
    }
    .card-val {
      font-size: 1.8rem;
      font-weight: 800;
      margin: 0.5rem 0;
      letter-spacing: -0.02em;
    }
    .card-footer {
      font-size: 0.85rem;
      color: var(--text-muted);
      display: flex;
      align-items: center;
      gap: 0.35rem;
    }
    /* ==========================================================================
       6. Interactive Authentication Playground Section
       ========================================================================== */
    .section-title {
      font-size: 1.35rem;
      font-weight: 700;
      margin: 3rem 0 1.25rem 0;
      display: flex;
      align-items: center;
      gap: 0.75rem;
    }
    .playground-layout {
      display: grid;
      grid-template-columns: 1fr 1fr;
      gap: 1.5rem;
    }
    @media (max-width: 900px) {
      .playground-layout {
        grid-template-columns: 1fr;
      }
      .hero-banner {
        grid-template-columns: 1fr;
      }
    }
    .form-group {
      margin-bottom: 1.25rem;
    }
    .form-label {
      display: block;
      font-size: 0.85rem;
      font-weight: 600;
      margin-bottom: 0.4rem;
      color: var(--text-muted);
    }
    .form-control {
      width: 100%;
      padding: 0.75rem 1rem;
      background: var(--bg-surface-elevated);
      border: 1px solid var(--border-color);
      border-radius: 10px;
      color: var(--text-main);
      font-size: 0.95rem;
      outline: none;
    }
    .form-control:focus {
      border-color: var(--primary);
      box-shadow: 0 0 0 3px var(--primary-glow);
    }
    .btn {
      padding: 0.75rem 1.5rem;
      border-radius: 10px;
      font-weight: 600;
      font-size: 0.9rem;
      cursor: pointer;
      border: none;
      display: inline-flex;
      align-items: center;
      justify-content: center;
      gap: 0.5rem;
    }
    .btn-primary {
      background: linear-gradient(135deg, var(--primary), var(--accent));
      color: #ffffff;
      box-shadow: 0 4px 12px var(--primary-glow);
    }
    .btn-primary:hover {
      opacity: 0.95;
      transform: translateY(-1px);
    }
    .btn-secondary {
      background: var(--bg-surface-elevated);
      color: var(--text-main);
      border: 1px solid var(--border-color);
    }
    .btn-secondary:hover {
      border-color: var(--primary);
    }
    /* Response Inspector Box */
    .inspector-box {
      background: var(--code-bg);
      border: 1px solid var(--border-color);
      border-radius: 12px;
      padding: 1.25rem;
      color: #e2e8f0;
      font-size: 0.85rem;
      min-height: 280px;
      display: flex;
      flex-direction: column;
    }
    .inspector-header {
      display: flex;
      justify-content: space-between;
      align-items: center;
      padding-bottom: 0.75rem;
      margin-bottom: 0.75rem;
      border-bottom: 1px solid rgba(255, 255, 255, 0.1);
    }
    .badge-status {
      padding: 0.25rem 0.6rem;
      border-radius: 6px;
      font-size: 0.75rem;
      font-weight: 700;
    }
    .badge-200 { background: rgba(16, 185, 129, 0.2); color: #34d399; }
    .badge-401 { background: rgba(239, 68, 68, 0.2); color: #f87171; }
    .badge-303 { background: rgba(245, 158, 11, 0.2); color: #fbbf24; }
    .json-code {
      white-space: pre-wrap;
      word-break: break-all;
      color: #38bdf8;
      overflow-y: auto;
      flex-grow: 1;
    }
    /* ==========================================================================
       7. Security & Compliance Scoreboard
       ========================================================================== */
    .security-grid {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
      gap: 1.25rem;
      margin-top: 1rem;
    }
    .sec-item {
      display: flex;
      align-items: flex-start;
      gap: 1rem;
      padding: 1.25rem;
      background: var(--bg-surface);
      border: 1px solid var(--border-color);
      border-radius: 14px;
    }
    .sec-icon {
      width: 42px;
      height: 42px;
      border-radius: 10px;
      display: grid;
      place-items: center;
      font-size: 1.25rem;
      background: var(--primary-glow);
      color: var(--primary);
    }
    .sec-detail h4 {
      font-size: 0.95rem;
      font-weight: 700;
      margin-bottom: 0.25rem;
    }
    .sec-detail p {
      font-size: 0.825rem;
      color: var(--text-muted);
    }
    /* ==========================================================================
       8. API Surface Reference Table
       ========================================================================== */
    .table-wrapper {
      background: var(--bg-surface);
      border: 1px solid var(--border-color);
      border-radius: 16px;
      overflow: hidden;
      margin-top: 1rem;
      box-shadow: var(--card-shadow);
    }
    table {
      width: 100%;
      border-collapse: collapse;
      text-align: left;
      font-size: 0.9rem;
    }
    th {
      background: var(--bg-surface-elevated);
      padding: 1rem 1.25rem;
      font-weight: 700;
      color: var(--text-muted);
      border-bottom: 1px solid var(--border-color);
      font-size: 0.8rem;
      text-transform: uppercase;
      letter-spacing: 0.05em;
    }
    td {
      padding: 1rem 1.25rem;
      border-bottom: 1px solid var(--border-color);
      color: var(--text-main);
    }
    tr:last-child td {
      border-bottom: none;
    }
    .method-badge {
      padding: 0.25rem 0.5rem;
      border-radius: 6px;
      font-weight: 700;
      font-size: 0.75rem;
      font-family: 'JetBrains Mono', monospace;
    }
    .method-get { background: rgba(6, 182, 212, 0.15); color: var(--info); }
    .method-post { background: rgba(16, 185, 129, 0.15); color: var(--success); }
    .method-put { background: rgba(245, 158, 11, 0.15); color: var(--warning); }
    .method-delete { background: rgba(239, 68, 68, 0.15); color: var(--danger); }
    /* Footer */
    footer {
      margin-top: 4rem;
      padding-top: 2rem;
      border-top: 1px solid var(--border-color);
      text-align: center;
      color: var(--text-subtle);
      font-size: 0.85rem;
    }
  </style>
 </head>
 <body>
  <!-- Sticky Header Navigation -->
  <header>
    <div class="nav-wrapper">
      <a href="#" class="brand">
        <div class="brand-logo">N9</div>
        <div class="brand-text">
          <h1>nx9-auth</h1>
          <span>Identity & Access Management</span>
        </div>
      </a>
      <div class="nav-actions">
        <ul class="nav-links">
          <li><a href="#status" class="active">Overview</a></li>
          <li><a href="#playground">Auth Simulator</a></li>
          <li><a href="#security">Security</a></li>
          <li><a href="#api">API Reference</a></li>
        </ul>
        <button id="themeToggle" class="theme-toggle-btn" aria-label="Toggle Theme">
          <span id="themeIcon">🌙</span>
          <span id="themeLabel">Dark Mode</span>
        </button>
      </div>
    </div>
  </header>
  <div class="app-container">
    <!-- Hero & Status Banner -->
    <section id="status" class="hero-banner">
      <div>
        <div class="status-badge">
          <div class="pulse-dot"></div>
          <span>System Health: Operational</span>
        </div>
        <h2 class="hero-title" style="margin-top: 0.75rem;">Identity & Access Control Center</h2>
        <p class="hero-sub">
          High-performance, zero-Node.js Rust IAM server featuring Argon2id password hashing, BLAKE3 token hashing, and strict OWASP security controls.
        </p>
      </div>
      <div>
        <button class="btn btn-primary" onclick="simulateLoginSuccess()">
          ⚡ Test Admin Session
        </button>
      </div>
    </section>
    <!-- Metrics Cards Grid -->
    <section class="metrics-grid">
      <div class="card">
        <div class="card-label">Active Engine</div>
        <div class="card-val" style="color: var(--primary);">Axum / Tokio</div>
        <div class="card-footer"><span>⚡</span> Pure Rust Non-Blocking I/O</div>
      </div>
      <div class="card">
        <div class="card-label">Password Protection</div>
        <div class="card-val" style="color: var(--accent);">Argon2id</div>
        <div class="card-footer"><span>🛡️</span> Memory-Hard Key Derivation</div>
      </div>
      <div class="card">
        <div class="card-label">Token Hashing</div>
        <div class="card-val" style="color: var(--success);">BLAKE3</div>
        <div class="card-footer"><span>🔒</span> Hashed Opaque Storage at Rest</div>
      </div>
      <div class="card">
        <div class="card-label">UI Architecture</div>
        <div class="card-val" style="color: var(--info);">Dioxus WASM</div>
        <div class="card-footer"><span>🌐</span> Zero JS Runtime Overhead</div>
      </div>
    </section>
    <!-- Interactive Authentication Playground -->
    <section id="playground">
      <h3 class="section-title">
        <span>🧪</span> Authentication Simulator & Protocol Inspector
      </h3>
      <div class="playground-layout">
        <!-- Form Controls -->
        <div class="card">
          <h4 style="font-size: 1.1rem; font-weight: 700; margin-bottom: 1rem;">Simulate API Request</h4>
          <div class="form-group">
            <label class="form-label" for="simEndpoint">Select Auth Endpoint & Protocol</label>
            <select id="simEndpoint" class="form-control" onchange="updatePayloadTemplate()">
              <option value="post_login">POST /api/v1/auth/login (JSON Body)</option>
              <option value="get_me">GET /api/v1/auth/me (Cookie & Bearer Header)</option>
              <option value="get_leak">GET /login?username=admin&password=sec (Sanitizer 303 Check)</option>
            </select>
          </div>
          <div class="form-group">
            <label class="form-label" for="simUsername">Username</label>
            <input type="text" id="simUsername" class="form-control" value="admin" />
          </div>
          <div class="form-group">
            <label class="form-label" for="simPassword">Password</label>
            <input type="password" id="simPassword" class="form-control" value="Password123!" />
          </div>
          <div style="display: flex; gap: 0.75rem; margin-top: 1.5rem;">
            <button class="btn btn-primary" onclick="runSimulatedRequest()">
              🚀 Send Request
            </button>
            <button class="btn btn-secondary" onclick="resetSimulator()">
              Reset
            </button>
          </div>
        </div>
        <!-- Live Response Inspector -->
        <div class="inspector-box">
          <div class="inspector-header">
            <span style="font-weight: 700; font-size: 0.85rem; color: #94a3b8;">RESPONSE INSPECTOR</span>
            <span id="inspectBadge" class="badge-status badge-200">HTTP 200 OK</span>
          </div>
          <div style="font-size: 0.8rem; color: #64748b; margin-bottom: 0.5rem;" id="inspectHeaders">
            Content-Type: application/json | Cache-Control: no-store
          </div>
          <pre id="inspectCode" class="json-code">{
  "status": "ready",
  "message": "Click 'Send Request' to execute simulated request."
 }</pre>
        </div>
      </div>
    </section>
    <!-- Security & Hardening Scoreboard -->
    <section id="security">
      <h3 class="section-title">
        <span>🛡️</span> Security & Compliance Architecture
      </h3>
      <div class="security-grid">
        <div class="sec-item">
          <div class="sec-icon">🔑</div>
          <div class="sec-detail">
            <h4>Timing-Attack Mitigation</h4>
            <p>Non-enumerating authentication failures with constant-time dummy Argon2id execution delays for unknown users.</p>
          </div>
        </div>
        <div class="sec-item">
          <div class="sec-icon">🌐</div>
          <div class="sec-detail">
            <h4>Strict Content Security Policy</h4>
            <p>Hardened CSP (<code>script-src 'self' 'wasm-unsafe-eval'</code>) with zero inline script execution and zero <code>javascript:</code> URIs.</p>
          </div>
        </div>
        <div class="sec-item">
          <div class="sec-icon">🍪</div>
          <div class="sec-detail">
            <h4>HttpOnly Cookie Protection</h4>
            <p>Dual-mode cookie authentication featuring <code>HttpOnly</code>, <code>SameSite=Lax</code>, and automatic <code>Cache-Control: no-store</code>.</p>
          </div>
        </div>
        <div class="sec-item">
          <div class="sec-icon">⚡</div>
          <div class="sec-detail">
            <h4>In-Memory IP Rate Limiter</h4>
            <p>Lock-free exponential backoff lockout penalties managed via concurrent <code>DashMap</code> tracking.</p>
          </div>
        </div>
      </div>
    </section>
    <!-- API Surface Reference -->
    <section id="api">
      <h3 class="section-title">
        <span>📚</span> Core REST API Surface Reference
      </h3>
      <div class="table-wrapper">
        <table>
          <thead>
            <tr>
              <th>Method</th>
              <th>Endpoint Path</th>
              <th>Guard / Authentication</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><span class="method-badge method-get">GET</span></td>
              <td><code>/health</code></td>
              <td>Public</td>
              <td>System and database health diagnostic check.</td>
            </tr>
            <tr>
              <td><span class="method-badge method-get">GET</span></td>
              <td><code>/version</code></td>
              <td>Public</td>
              <td>Returns binary version and build target information.</td>
            </tr>
            <tr>
              <td><span class="method-badge method-post">POST</span></td>
              <td><code>/api/v1/auth/login</code></td>
              <td>Rate Limiter</td>
              <td>JSON login. Issues session cookies & Bearer access tokens.</td>
            </tr>
            <tr>
              <td><span class="method-badge method-get">GET</span></td>
              <td><code>/api/v1/auth/me</code></td>
              <td>AuthUser (Cookie/Bearer)</td>
              <td>Resolves current identity, assigned roles, and permission scopes.</td>
            </tr>
            <tr>
              <td><span class="method-badge method-post">POST</span></td>
              <td><code>/api/v1/auth/logout</code></td>
              <td>AuthUser</td>
              <td>Revokes active session and invalidates HttpOnly cookies.</td>
            </tr>
            <tr>
              <td><span class="method-badge method-get">GET</span></td>
              <td><code>/api/v1/users</code></td>
              <td>AuthUser (Admin)</td>
              <td>Paginated search and listing of registered platform users.</td>
            </tr>
          </tbody>
        </table>
      </div>
    </section>
    <!-- Footer -->
    <footer>
      <p>NX9-Auth IAM — Dual-Licensed under Apache 2.0 & MIT — Built with Pure Rust & WebAssembly</p>
    </footer>
  </div>
  <!-- Interactive JavaScript Application Logic -->
  <script>
    /* ==========================================================================
       Theme Toggle System (Dark / Light with Local Storage Persistence)
       ========================================================================== */
    const themeToggleBtn = document.getElementById('themeToggle');
    const themeIcon = document.getElementById('themeIcon');
    const themeLabel = document.getElementById('themeLabel');
    const htmlElement = document.documentElement;
    function setTheme(theme) {
      htmlElement.setAttribute('data-theme', theme);
      localStorage.setItem('nx9_theme', theme);
      if (theme === 'dark') {
        themeIcon.textContent = '🌙';
        themeLabel.textContent = 'Dark Mode';
      } else {
        themeIcon.textContent = '☀️';
        themeLabel.textContent = 'Light Mode';
      }
    }
    // Initialize Theme Preferences
    const savedTheme = localStorage.getItem('nx9_theme') || 
      (window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark');
    setTheme(savedTheme);
    themeToggleBtn.addEventListener('click', () => {
      const currentTheme = htmlElement.getAttribute('data-theme');
      setTheme(currentTheme === 'dark' ? 'light' : 'dark');
    });
    /* ==========================================================================
       Interactive Simulator & Inspector Logic
       ========================================================================== */
    const simEndpoint = document.getElementById('simEndpoint');
    const simUsername = document.getElementById('simUsername');
    const simPassword = document.getElementById('simPassword');
    const inspectBadge = document.getElementById('inspectBadge');
    const inspectHeaders = document.getElementById('inspectHeaders');
    const inspectCode = document.getElementById('inspectCode');
    function updatePayloadTemplate() {
      const mode = simEndpoint.value;
      if (mode === 'get_me') {
        inspectBadge.className = 'badge-status badge-200';
        inspectBadge.textContent = 'HTTP 200 OK';
        inspectHeaders.textContent = 'Authorization: Bearer st_7f8a9b... | Cookie: nx9_session=st_7f8a9b...';
        inspectCode.textContent = JSON.stringify({
          user: { id: "usr_01H8X2Y3Z4", username: simUsername.value || "admin", status: "active" },
          roles: ["admin"],
          permissions: ["*"]
        }, null, 2);
      } else if (mode === 'get_leak') {
        inspectBadge.className = 'badge-status badge-303';
        inspectBadge.textContent = 'HTTP 303 See Other';
        inspectHeaders.textContent = 'Location: /login | Cache-Control: no-store (Sanitizer Activated)';
        inspectCode.textContent = JSON.stringify({
          action: "Sanitizer Redirect",
          cause: "Credentials detected in GET query parameters",
          sanitized_location: "/login"
        }, null, 2);
      } else {
        inspectBadge.className = 'badge-status badge-200';
        inspectBadge.textContent = 'HTTP 200 OK';
        inspectHeaders.textContent = 'Content-Type: application/json | Cache-Control: no-store';
        inspectCode.textContent = JSON.stringify({
          status: "ready",
          endpoint: "POST /api/v1/auth/login"
        }, null, 2);
      }
    }
    function runSimulatedRequest() {
      const mode = simEndpoint.value;
      const u = simUsername.value.trim();
      const p = simPassword.value;
      if (!u || !p) {
        inspectBadge.className = 'badge-status badge-401';
        inspectBadge.textContent = 'HTTP 401 Unauthorized';
        inspectHeaders.textContent = 'Content-Type: application/json';
        inspectCode.textContent = JSON.stringify({
          error: "Invalid username or password.",
          code: 401
        }, null, 2);
        return;
      }
      if (mode === 'post_login') {
        inspectBadge.className = 'badge-status badge-200';
        inspectBadge.textContent = 'HTTP 200 OK';
        inspectHeaders.textContent = 'Set-Cookie: nx9_session=st_8a9f...; HttpOnly; SameSite=Lax | Content-Type: application/json';
        inspectCode.textContent = JSON.stringify({
          access_token: "st_8a9f0c1d2e3f4a5b6c7d8e9f0a1b2c3d",
          refresh_token: "rt_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
          expires_in: 86400,
          token_type: "Bearer",
          user: { id: "usr_01H8X2Y3Z4", username: u, status: "active" }
        }, null, 2);
      } else if (mode === 'get_me') {
        inspectBadge.className = 'badge-status badge-200';
        inspectBadge.textContent = 'HTTP 200 OK';
        inspectHeaders.textContent = 'Authorization: Bearer st_8a9f... | Content-Type: application/json';
        inspectCode.textContent = JSON.stringify({
          user: { id: "usr_01H8X2Y3Z4", username: u, status: "active" },
          roles: ["admin"],
          permissions: ["*"]
        }, null, 2);
      } else if (mode === 'get_leak') {
        inspectBadge.className = 'badge-status badge-303';
        inspectBadge.textContent = 'HTTP 303 See Other';
        inspectHeaders.textContent = 'Location: /login | Cache-Control: no-store (Sanitizer Interception)';
        inspectCode.textContent = JSON.stringify({
          notice: "Query string credentials intercepted by serve_ui fallback",
          redirect_to: "/login",
          headers: "Cache-Control: no-store"
        }, null, 2);
      }
    }
    function simulateLoginSuccess() {
      simEndpoint.value = 'post_login';
      simUsername.value = 'admin';
      simPassword.value = 'Password123!';
      runSimulatedRequest();
    }
    function resetSimulator() {
      simEndpoint.value = 'post_login';
      simUsername.value = 'admin';
      simPassword.value = 'Password123!';
      updatePayloadTemplate();
    }
  </script>
 </body>
 </html>
Author	SHA1	Message	Date
thakares	b6798e7a7c	ci: improve GitHub Actions workflow diagnostics	2026-07-22 21:16:48 +05:30
thakares	36903d2125	docs: update architecture and fix GitHub Actions workflow	2026-07-22 21:05:20 +05:30
thakares	0134ff6a50	docs: add architecture documentation and standardize filenames	2026-07-22 20:18:38 +05:30
thakares	0010f2cfb8	docs: add architecture documentation and standardize filenames	2026-07-22 20:15:22 +05:30
thakares	5c1340c9cb	docs: add architecture documentation and standardize filenames	2026-07-22 20:08:46 +05:30
thakares	af68b43ae0	Missing: License files, updated	2026-07-22 19:58:16 +05:30
thakares	112ce77891	docs: remove internal recovery report	2026-07-22 19:52:07 +05:30