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
216 changed files with 22065 additions and 1631 deletions
@@ -1,41 +1,92 @@
-name: Rust
+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
          - beta
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Rust
-        uses: dtolnay/rust-toolchain@master
+        uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: ${{ matrix.rust }}
          components: rustfmt, clippy
      - 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
@@ -1,39 +1,47 @@
 /target
 *.db
 *.db-wal
 *.db-shm
 .env
 config.toml
 ```gitignore
 # Rust
-/target
+/target/
-# SQLite
+# UI build output
-*.db
+/ui/dist/
 *.db-wal
 *.db-shm
-# Coverage
+# Release artifacts
-coverage/
+/dist/
 tarpaulin-report.html
-# IDE
+# Runtime database
-.vscode/
+auth.db
-.idea/
+auth.db-shm
 auth.db-wal
-# OS
+# Local configuration
 .DS_Store
 Thumbs.db
 # Local configs
 config.toml
 .env
-# Temporary backups
+# Scratch
 backups/
 scratch/
 # Temporary
 tree.txt
 *.tmp
 *.bak
 *.orig
 *.swp
 *.swo
 *~
 # Logs
 *.log
-```
+
-.idea/
+# Coverage
 *.profraw
 *.profdata
 # macOS
 .DS_Store
 # Windows
 Thumbs.db
 # Python
 __pycache__/
 # Node
 node_modules/auth.db
@@ -0,0 +1,23 @@
 # Changelog
 All notable changes to `nx9-auth` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [0.3.0] - 2026-07-22
 ### Added
 - **Unified Modular Runtime Lifecycle**: Fully implemented runtime subsystem (`Application`, `ApplicationBuilder`, `AtomicRuntimeState`, `SignalManager`, `ShutdownCoordinator`, `WorkerManager`, `HookRegistry`, `RuntimeMetrics`).
 - **Axum HTTP Server Graceful Shutdown**: Integrated HTTP listener lifecycle with Tokio signal handling (`SIGINT` and `SIGTERM`).
 - **Prioritized Shutdown Hooks**: Extensible shutdown hook execution (`First`, `Normal`, `Last`) with isolated failure handling.
 - **Lock-Free State Machine**: Deterministic, lock-free lifecycle state transitions (`Initializing` -> `Starting` -> `Running` -> `Draining` -> `StoppingWorkers` -> `ExecutingHooks` -> `ClosingResources` -> `Stopped`).
 - **Comprehensive Integration Tests**: Runtime lifecycle test suite verifying dependency assembly, hook order execution, and worker management.
 ### Changed
 - Refactored `run_server` entrypoint in `main.rs` to construct and await the `Application` runtime lifecycle cleanly.
 - Updated database connection pool closing to execute during the `ClosingResources` lifecycle phase.
 ### Fixed
 - Fixed runtime completeness regression where `Application::start()` returned immediately instead of serving HTTP requests.
 - Resolved database provider initialization lifecycle synchronization between CLI subcommands and server mode.
@@ -84,9 +84,9 @@ dependencies = [
 [[package]]
 name = "anyhow"
-version = "1.0.102"
+version = "1.0.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
 [[package]]
 name = "argon2"
@@ -108,9 +108,9 @@ checksum = "76a2e8124351fda1ef8aaaa3bbd7ebbcb486bbcd4225aca0aa0d84bb2db8fecb"
 [[package]]
 name = "arrayvec"
-version = "0.7.7"
+version = "0.7.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f02882884d3e1bc524fb12c79f107f6ad0e1cfd498c536ffb494301740995dfe"
+checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56"
 [[package]]
 name = "async-compression"
@@ -124,6 +124,17 @@ dependencies = [
 "tokio",
 ]
 [[package]]
 name = "async-trait"
 version = "0.1.91"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ae36dc4177970ef04fde5178d3e2429882def40e57a451f919c098f72baa6cec"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn 3.0.3",
 ]
 [[package]]
 name = "atoi"
 version = "2.0.0"
@@ -228,7 +239,7 @@ checksum = "7aa268c23bfbbd2c4363b9cd302a4f504fb2a9dfe7e3451d66f35dd392e20aca"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 ]
 [[package]]
@@ -245,9 +256,9 @@ checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 [[package]]
 name = "bitflags"
-version = "2.13.0"
+version = "2.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
 dependencies = [
 "serde_core",
 ]
@@ -307,15 +318,15 @@ checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 [[package]]
 name = "bytes"
-version = "1.12.0"
+version = "1.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ae3f5d315924270530207e2a68396c3cc547f6dca3fbdca317cfb1a51edb593"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 [[package]]
 name = "cc"
-version = "1.2.65"
+version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e228eec9be7c17ccb640b59b36a5cd805ea2a564a4c5e162c2f659fea30d3b96"
+checksum = "c89588d05638b5b4594a3348a2d6c20277e43a7f5c5202b05cc56888475a47b8"
 dependencies = [
 "find-msvc-tools",
 "shlex",
@@ -329,9 +340,9 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 [[package]]
 name = "chacha20"
-version = "0.10.0"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6f8d983286843e49675a4b7a2d174efe136dc93a18d69130dd18198a6c167601"
+checksum = "d524456ba66e72eb8b115ff89e01e497f8e6d11d78b70b1aa13c0fbd97540a81"
 dependencies = [
 "cfg-if",
 "cpufeatures 0.3.0",
@@ -354,9 +365,9 @@ dependencies = [
 [[package]]
 name = "clap"
-version = "4.6.1"
+version = "4.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
+checksum = "d91e0c145792ef73a6ad36d27c75ac09f1832222a3c209689d90f534685ee5b7"
 dependencies = [
 "clap_builder",
 "clap_derive",
@@ -364,9 +375,9 @@ dependencies = [
 [[package]]
 name = "clap_builder"
-version = "4.6.0"
+version = "4.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
+checksum = "f09628afdcc538b57f3c6341e9c8e9970f18e4a481690a64974d7023bd33548b"
 dependencies = [
 "anstream",
 "anstyle",
@@ -376,14 +387,14 @@ dependencies = [
 [[package]]
 name = "clap_derive"
-version = "4.6.1"
+version = "4.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
 dependencies = [
 "heck",
 "proc-macro2",
 "quote",
- "syn",
+ "syn 3.0.3",
 ]
 [[package]]
@@ -497,18 +508,18 @@ dependencies = [
 [[package]]
 name = "crossbeam-queue"
-version = "0.3.12"
+version = "0.3.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0f58bbc28f91df819d0aa2a2c00cd19754769c2fad90579b3592b1c9ba7a3115"
+checksum = "803d13fb3b09d88be9f4dbc29062c66b19bf7170867ceb746d2a8689bf6c7a26"
 dependencies = [
 "crossbeam-utils",
 ]
 [[package]]
 name = "crossbeam-utils"
-version = "0.8.21"
+version = "0.8.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
 [[package]]
 name = "crypto-common"
@@ -557,9 +568,6 @@ name = "deranged"
 version = "0.5.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
 dependencies = [
 "powerfmt",
 ]
 [[package]]
 name = "digest"
@@ -591,7 +599,7 @@ checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 ]
 [[package]]
@@ -690,9 +698,9 @@ dependencies = [
 [[package]]
 name = "futures-channel"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d"
+checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae"
 dependencies = [
 "futures-core",
 "futures-sink",
@@ -700,15 +708,15 @@ dependencies = [
 [[package]]
 name = "futures-core"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
+checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
 [[package]]
 name = "futures-executor"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "baf29c38818342a3b26b5b923639e7b1f4a61fc5e76102d4b1981c6dc7a7579d"
+checksum = "6754879cc9f2c66f88c6e5c35344bb0bdb0708b0352b1201815667c7eabc7458"
 dependencies = [
 "futures-core",
 "futures-task",
@@ -728,27 +736,27 @@ dependencies = [
 [[package]]
 name = "futures-io"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718"
+checksum = "4577ecaa3c4f96589d473f679a71b596316f6641bc350038b962a5daf0085d7a"
 [[package]]
 name = "futures-sink"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c39754e157331b013978ec91992bde1ac089843443c49cbc7f46150b0fad0893"
+checksum = "e34418ac499d6305c2fb5ad0ed2f6ac998c5f8ca209b4510f7f94242c647e307"
 [[package]]
 name = "futures-task"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
+checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109"
 [[package]]
 name = "futures-util"
-version = "0.3.32"
+version = "0.3.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
+checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
 dependencies = [
 "futures-core",
 "futures-io",
@@ -876,9 +884,9 @@ dependencies = [
 [[package]]
 name = "http-body"
-version = "1.0.1"
+version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184"
+checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"
 dependencies = [
 "bytes",
 "http",
@@ -886,9 +894,9 @@ dependencies = [
 [[package]]
 name = "http-body-util"
-version = "0.1.3"
+version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b021d93e26becf5dc7e1b75b1bed1fd93124b374ceb73f43d4d4eafec896a64a"
+checksum = "e9f41fd6a08e4d4ec69df65976da761afd5ad5e58a9d4acb46bd1c953a9e3ff2"
 dependencies = [
 "bytes",
 "futures-core",
@@ -911,18 +919,18 @@ checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 [[package]]
 name = "hybrid-array"
-version = "0.4.12"
+version = "0.4.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9155a582abd142abc056962c29e3ce5ff2ad5469f4246b537ed42c5deba857da"
+checksum = "818356c5132c1fede50f837ca96afbe78ff42413047f4abb886217845e1b6c8c"
 dependencies = [
 "typenum",
 ]
 [[package]]
 name = "hyper"
-version = "1.10.1"
+version = "1.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "55281c53a1894c864990125767da440a4e630446785086f52523b20033b74498"
+checksum = "d22053281f852e11534f5198498373cbb59295120a20771d90f7ed1897490a72"
 dependencies = [
 "atomic-waker",
 "bytes",
@@ -1103,9 +1111,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 [[package]]
 name = "js-sys"
-version = "0.3.102"
+version = "0.3.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "03d04c30968dffe80775bd4d7fb676131cd04a1fb46d2686dbffbaec2d9dfd31"
+checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
 dependencies = [
 "cfg-if",
 "futures-util",
@@ -1120,9 +1128,9 @@ checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
 [[package]]
 name = "libc"
-version = "0.2.186"
+version = "0.2.189"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 [[package]]
 name = "libsqlite3-sys"
@@ -1183,9 +1191,9 @@ dependencies = [
 [[package]]
 name = "memchr"
-version = "2.8.2"
+version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 [[package]]
 name = "mime"
@@ -1205,9 +1213,9 @@ dependencies = [
 [[package]]
 name = "mio"
-version = "1.2.1"
+version = "1.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "02bd0af71c67b473010cbbc60715ee815645a4dc942899111f494b4b737d6fda"
+checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427"
 dependencies = [
 "libc",
 "wasi",
@@ -1225,9 +1233,9 @@ dependencies = [
 [[package]]
 name = "num-conv"
-version = "0.1.0"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "51d515d32fb182ee37cda2ccdcb92950d6a3c2893aa280e540671c2cd0f3b1d9"
+checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
 [[package]]
 name = "num-traits"
@@ -1240,10 +1248,11 @@ dependencies = [
 [[package]]
 name = "nx9-auth"
-version = "0.1.0"
+version = "0.3.0"
 dependencies = [
 "anyhow",
 "argon2",
 "async-trait",
 "axum",
 "axum-extra",
 "blake3",
@@ -1252,13 +1261,14 @@ dependencies = [
 "dashmap",
 "hex",
 "http-body-util",
- "rand 0.8.6",
+ "rand 0.8.7",
 "serde",
 "serde_json",
 "sqlx",
 "thiserror",
 "time",
 "tokio",
 "tokio-util",
 "toml",
 "tower",
 "tower-http",
@@ -1363,18 +1373,18 @@ dependencies = [
 [[package]]
 name = "proc-macro2"
-version = "1.0.106"
+version = "1.0.107"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
 dependencies = [
 "unicode-ident",
 ]
 [[package]]
 name = "quote"
-version = "1.0.45"
+version = "1.0.47"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
 dependencies = [
 "proc-macro2",
 ]
@@ -1387,9 +1397,9 @@ checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
 [[package]]
 name = "rand"
-version = "0.8.6"
+version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5ca0ecfa931c29007047d1bc58e623ab12e5590e8c7cc53200d5202b69266d8a"
+checksum = "22f6172bdec972074665ed81ed53b71da00bfc44b65a753cfde883ec4c702a1a"
 dependencies = [
 "libc",
 "rand_chacha",
@@ -1398,9 +1408,9 @@ dependencies = [
 [[package]]
 name = "rand"
-version = "0.10.1"
+version = "0.10.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d2e8e8bcc7961af1fdac401278c6a831614941f6164ee3bf4ce61b7edb162207"
+checksum = "c7f5fa3a058cd35567ef9bfa5e75732bee0f9e4c55fa90477bef2dfcdbc4be80"
 dependencies = [
 "chacha20",
 "getrandom 0.4.3",
@@ -1443,9 +1453,9 @@ dependencies = [
 [[package]]
 name = "regex-automata"
-version = "0.4.14"
+version = "0.4.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
 dependencies = [
 "aho-corasick",
 "memchr",
@@ -1460,9 +1470,9 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 [[package]]
 name = "rustversion"
-version = "1.0.22"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 [[package]]
 name = "ryu"
@@ -1478,9 +1488,9 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 [[package]]
 name = "serde"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
 dependencies = [
 "serde_core",
 "serde_derive",
@@ -1488,29 +1498,29 @@ dependencies = [
 [[package]]
 name = "serde_core"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
 dependencies = [
 "serde_derive",
 ]
 [[package]]
 name = "serde_derive"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 3.0.3",
 ]
 [[package]]
 name = "serde_json"
-version = "1.0.150"
+version = "1.0.151"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
 dependencies = [
 "itoa",
 "memchr",
@@ -1611,9 +1621,9 @@ dependencies = [
 [[package]]
 name = "simd-adler32"
-version = "0.3.9"
+version = "0.3.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
 [[package]]
 name = "slab"
@@ -1632,9 +1642,9 @@ dependencies = [
 [[package]]
 name = "socket2"
-version = "0.6.4"
+version = "0.6.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51"
+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
 dependencies = [
 "libc",
 "windows-sys",
@@ -1642,9 +1652,9 @@ dependencies = [
 [[package]]
 name = "spin"
-version = "0.9.8"
+version = "0.9.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6980e8d7511241f8acf4aebddbb1ff938df5eebe98691418c4468d0b72a96a67"
+checksum = "3763264f6b73151db08c50ff20d7d8a0b8796e021cdea7ceedad07b80155fa0e"
 dependencies = [
 "lock_api",
 ]
@@ -1707,7 +1717,7 @@ dependencies = [
 "quote",
 "sqlx-core",
 "sqlx-macros-core",
- "syn",
+ "syn 2.0.119",
 ]
 [[package]]
@@ -1730,7 +1740,7 @@ dependencies = [
 "sqlx-mysql",
 "sqlx-postgres",
 "sqlx-sqlite",
- "syn",
+ "syn 2.0.119",
 "thiserror",
 "tokio",
 "url",
@@ -1787,7 +1797,7 @@ dependencies = [
 "log",
 "md-5",
 "memchr",
- "rand 0.10.1",
+ "rand 0.10.2",
 "serde",
 "serde_json",
 "sha2 0.11.0",
@@ -1855,9 +1865,20 @@ checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
 [[package]]
 name = "syn"
-version = "2.0.118"
+version = "2.0.119"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
 dependencies = [
 "proc-macro2",
 "quote",
 "unicode-ident",
 ]
 [[package]]
 name = "syn"
 version = "3.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -1878,46 +1899,45 @@ checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 ]
 [[package]]
 name = "thiserror"
-version = "2.0.18"
+version = "2.0.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
+checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
 dependencies = [
 "thiserror-impl",
 ]
 [[package]]
 name = "thiserror-impl"
-version = "2.0.18"
+version = "2.0.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
+checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 3.0.3",
 ]
 [[package]]
 name = "thread_local"
-version = "1.1.9"
+version = "1.1.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f60246a4944f24f6e018aa17cdeffb7818b76356965d03b07d6a9886e8962185"
+checksum = "1ad99c4c6d32803332c548b1af0540b357b3f5fc0be8f6c6bfe8b2e6ae784070"
 dependencies = [
 "cfg-if",
 ]
 [[package]]
 name = "time"
-version = "0.3.45"
+version = "0.3.54"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f9e442fc33d7fdb45aa9bfeb312c095964abdf596f7567261062b2a7107aaabd"
+checksum = "3e1d5e639ff6bab73cb6885cc7e7b1de96c3f32c68ec55f3952614bec1092244"
 dependencies = [
 "deranged",
 "itoa",
 "num-conv",
 "powerfmt",
 "serde_core",
@@ -1927,15 +1947,15 @@ dependencies = [
 [[package]]
 name = "time-core"
-version = "0.1.7"
+version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8b36ee98fd31ec7426d599183e8fe26932a8dc1fb76ddb6214d05493377d34ca"
+checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109"
 [[package]]
 name = "time-macros"
-version = "0.2.25"
+version = "0.2.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "71e552d1249bf61ac2a52db88179fd0673def1e1ad8243a00d9ec9ed71fee3dd"
+checksum = "7e689342a48d2ea927c87ea50cabf8594854bf940e9310208848d680d668ed85"
 dependencies = [
 "num-conv",
 "time-core",
@@ -1953,9 +1973,9 @@ dependencies = [
 [[package]]
 name = "tinyvec"
-version = "1.11.0"
+version = "1.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3e61e67053d25a4e82c844e8424039d9745781b3fc4f32b8d55ed50f5f667ef3"
+checksum = "bb4ebadaa0af04fab11ae01eb5f9fdb5f9c5b875506e210e71c07873528baa7f"
 dependencies = [
 "tinyvec_macros",
 ]
@@ -1968,9 +1988,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 [[package]]
 name = "tokio"
-version = "1.52.3"
+version = "1.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
+checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
 dependencies = [
 "bytes",
 "libc",
@@ -1985,20 +2005,20 @@ dependencies = [
 [[package]]
 name = "tokio-macros"
-version = "2.7.0"
+version = "2.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
+checksum = "6328af13490e73a9b4694030fafd93f8c8c6a9dede33e821c3fc63eddf8042ba"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 ]
 [[package]]
 name = "tokio-stream"
-version = "0.1.18"
+version = "0.1.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32da49809aab5c3bc678af03902d4ccddea2a87d028d86392a4b1560c6906c70"
+checksum = "a3d06f0b082ba57c26b79407372e57cf2a1e28124f78e9479fe80322cf53420b"
 dependencies = [
 "futures-core",
 "pin-project-lite",
@@ -2007,9 +2027,9 @@ dependencies = [
 [[package]]
 name = "tokio-util"
-version = "0.7.18"
+version = "0.7.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ae9cec805b01e8fc3fd2fe289f89149a9b66dd16786abd8b19cfa7b48cb0098"
+checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
 dependencies = [
 "bytes",
 "futures-core",
@@ -2132,7 +2152,7 @@ checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 ]
 [[package]]
@@ -2246,9 +2266,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 [[package]]
 name = "uuid"
-version = "1.23.3"
+version = "1.24.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "144d6b123cef80b301b8f72a9e2ca4370ddec21950d0a103dd22c437006d2db7"
+checksum = "bf3923a6f5c4c6382e0b653c4117f48d631ea17f38ed86e2a828e6f7412f5239"
 dependencies = [
 "getrandom 0.4.3",
 "js-sys",
@@ -2281,9 +2301,9 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ddb3f79143bced6de84270411622a2699cee572fc0875aeaf1e7867cf9fca1a"
+checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
 dependencies = [
 "cfg-if",
 "once_cell",
@@ -2294,9 +2314,9 @@ dependencies = [
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4e21a184b13fb19e157296e2c46056aec9092264fab83e4ba59e68c61b323c3d"
+checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
 dependencies = [
 "quote",
 "wasm-bindgen-macro-support",
@@ -2304,22 +2324,22 @@ dependencies = [
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fecefd9c35bd935a20fc3fc344b5f29138961e4f47fb03297d88f2587afb5ebd"
+checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
 dependencies = [
 "bumpalo",
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 "wasm-bindgen-shared",
 ]
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.125"
+version = "0.2.126"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "23939e44bb9a5d7576fa2b563dc2e136628f1224e88a8deed09e04858b77871f"
+checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
 dependencies = [
 "unicode-ident",
 ]
@@ -2351,7 +2371,7 @@ checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 ]
 [[package]]
@@ -2362,7 +2382,7 @@ checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 ]
 [[package]]
@@ -2432,28 +2452,28 @@ checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 "synstructure",
 ]
 [[package]]
 name = "zerocopy"
-version = "0.8.52"
+version = "0.8.55"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ce1022995ff5ff5d841ad7d994facc23098cd40152f2c1d11cd607c6f530653f"
+checksum = "b5a105cd7b140f6eeec8acff2ea38135d3cab283ada58540f629fe51e46696eb"
 dependencies = [
 "zerocopy-derive",
 ]
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.52"
+version = "0.8.55"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ae7f38b72ec2a254e2b87ef277cf2cd4fb97cbebf944faa6f33354da0867930"
+checksum = "0fe976fb70c78cd64cccfe3a6fc142244e8a77b70959b30faf9d0ac37ee228eb"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 ]
 [[package]]
@@ -2473,7 +2493,7 @@ checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 "synstructure",
 ]
@@ -2507,11 +2527,11 @@ checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
 dependencies = [
 "proc-macro2",
 "quote",
- "syn",
+ "syn 2.0.119",
 ]
 [[package]]
 name = "zmij"
-version = "1.0.21"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
@@ -1,11 +1,16 @@
 [package]
 name = "nx9-auth"
-version = "0.1.0"
+version = "0.3.0"
 edition = "2024"
 rust-version = "1.85"
 authors = ["NX9 Team","Sunil Thakare"]
 description = "Lightweight self-hosted IAM service for the NX9 ecosystem"
-license = "Apache-2.0 or MIT -- Dual License"
+license = "MIT OR Apache-2.0"
 repository = "https://github.com/nx9-iam/nx9-auth"
 homepage = "https://nx9.dev"
 documentation = "https://docs.rs/nx9-auth"
 keywords = ["iam", "authentication", "authorization", "rbac", "security"]
 categories = ["authentication", "web-programming::http-server"]
 [[bin]]
 name = "nx9-auth"
@@ -16,6 +21,7 @@ name = "nx9_auth"
 path = "src/lib.rs"
 [dependencies]
 async-trait = "0.1"
 # HTTP framework
 axum = { version = "0.8.9", features = ["macros"] }
 axum-extra = { version = "0.12", features = ["cookie"] }
@@ -24,9 +30,11 @@ tower-http = { version = "0.6.11", features = ["trace", "request-id", "compressi
 # Async runtime
 tokio = { version = "1.52.3", features = ["full"] }
 tokio-util = "0.7"
 # Database
-sqlx = { version = "0.9.0", features = ["runtime-tokio", "sqlite", "chrono", "macros"] }
+sqlx = { version = "0.9.0", features = ["runtime-tokio", "chrono", "macros"] }
 # Password hashing
 argon2 = "0.5.3"
@@ -44,7 +52,7 @@ serde_json = "1.0"
 # Time
 chrono = { version = "0.4", features = ["serde"] }
 uuid = { version = "1.23.3", features = ["v4"] }
-time = { version = "0.3", features = ["macros"] }
+time = { version = "0.3.47", features = ["macros"] }
 # Config
 toml = "0.8"
@@ -80,3 +88,7 @@ debug = true
 [dev-dependencies]
 http-body-util = "0.1"
 [features]
 default = ["sqlite"]
 sqlite = ["sqlx/sqlite"]
 postgres = ["sqlx/postgres"]
@@ -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.
@@ -1,138 +1,107 @@
 # nx9-auth
-A lightweight Identity and Access Management (IAM) service for the NX9 ecosystem.
+<p align="center">
-Built with Rust, Axum, SQLite, and modern security practices, `nx9-auth` provides authentication, authorization, session management, personal access tokens, audit logging, and role-based access control in a single deployable binary.
+**Enterprise Identity & Access Management (IAM)**
-## Features
+*Self-Hosted • Privacy-First • Pure Rust • Single Binary • Dual Database Engine*
-* User management
+[![Version](https://img.shields.io/badge/version-v0.3.0-blue.svg)]()
-* Role-Based Access Control (RBAC)
+[![Rust](https://img.shields.io/badge/Rust-2024-orange.svg)](https://www.rust-lang.org/)
-* Session authentication
+[![License](https://img.shields.io/badge/license-Apache2--0%20%7C%20MIT-green.svg)](LICENSE)
-* Personal Access Tokens (PAT)
+[![Platform](https://img.shields.io/badge/platform-Linux-success.svg)]()
-* Audit logging
+[![SQLite](https://img.shields.io/badge/database-SQLite-blue.svg)]()
-* Transaction-safe operations
+[![PostgreSQL](https://img.shields.io/badge/database-PostgreSQL-blue.svg)]()
 * SQLite with WAL mode
 * Online backups
 * Interactive initialization
 * Docker and CasaOS support
 * Systemd deployment support
 * XDG-compliant user mode
-## Quick Start
+</p>
-Initialize a new installation:
+---
 ## Overview
 **nx9-auth** is a production-grade, self-hosted Identity & Access Management (IAM) server built entirely in **Rust**. It provides multi-tenant user authentication, Role-Based Access Control (RBAC), Personal Access Tokens (PATs), OAuth2 service accounts, active session management, full audit logging, an enterprise graceful shutdown runtime lifecycle, and an embedded WebAssembly (WASM) administrative UI.
 `nx9-auth` compiles into a single standalone binary containing both the Axum REST API backend and the embedded Dioxus WASM frontend, backed by a database-agnostic provider supporting both **SQLite** and **PostgreSQL**.
 ---
 ## Key Features
 - **Unified Enterprise Runtime Lifecycle**: Atomic 8-state lifecycle machine (`Initializing` → `Starting` → `Running` → `Draining` → `StoppingWorkers` → `ExecutingHooks` → `ClosingResources` → `Stopped`), `CancellationToken` propagation, `JoinSet` worker management, prioritized shutdown hooks, and destructor-safe Unix signal escalation.
 - **Dual Database Engine**: Native support for SQLite and enterprise PostgreSQL with 100% repository parity and runtime connection pool ownership.
 - **Enterprise Security Model**: Argon2id password hashing, BLAKE3 token/session hashing, rate-limiting, CSP, HSTS, and non-enumerating authentication.
 - **Multi-Tenant & RBAC**: Tenant isolation, fine-grained permission matrix, role assignments, and organizational user groups.
 - **Personal Access Tokens & Service Accounts**: Machine-to-machine authentication with automatic prefix tracking and instant revocation.
 - **Embedded WebAssembly UI**: Dioxus-powered administration dashboard with `#boot-loader` lifecycle management.
 - **Comprehensive CLI Tooling**: Automated `init`, `doctor`, `migrate`, `backup`, `restore`, and user management commands.
 ---
 ## Quickstart
 ```bash
 # Initialize application directory, configuration, and default administrator
 nx9-auth init
 ```
-Start the server:
+# Verify installation & system health
 ```bash
 nx9-auth serve
 ```
 Verify health:
 ```bash
 curl http://127.0.0.1:8655/health
 ```
 ## CLI Commands
 ```bash
 nx9-auth init
 nx9-auth serve
 nx9-auth doctor
-nx9-auth create-user
+# Start server
-nx9-auth create-admin
+nx9-auth serve
 nx9-auth create-token
 nx9-auth revoke-token
 nx9-auth show-user
 nx9-auth show-token
 nx9-auth backup
 ```
-## Deployment Modes
+---
-### User Mode
+## Configuration
-Uses XDG directories:
+Configure `config.toml` or set environment variables:
-```text
+```toml
-~/.config/nx9-auth/
+[server]
-~/.local/share/nx9-auth/
+host = "127.0.0.1"
-~/.local/state/nx9-auth/
+port = 8655
 production = false
 cookie_secure = false
 [database]
 # SQLite URL or file path:
 url = "sqlite://./data/auth.db?mode=rwc"
 # Or enterprise PostgreSQL:
 # url = "postgres://user:password@localhost:5432/nx9auth"
 max_connections = 20
 min_connections = 5
 connect_timeout_secs = 10
 idle_timeout_secs = 600
 max_lifetime_secs = 1800
 [shutdown]
 graceful_timeout_secs = 30
 force_timeout_secs = 35
 ```
-### System Mode
+---
-```text
+## Documentation Index
 /etc/nx9-auth/
 /var/lib/nx9-auth/
 /var/log/nx9-auth/
 ```
-### Docker
+- [Runtime Lifecycle & Graceful Shutdown](docs/runtime-lifecycle.md)
 - [Release Notes](RELEASE_NOTES.md)
 - [Authentication Model](docs/AUTHENTICATION.md)
 - [Backup & Disaster Recovery](docs/BACKUPS.md)
 - [Docker Deployment Guide](docs/DOCKER.md)
 - [Linux Deployment Guide](docs/DEPLOYMENT.md)
 - [Integration Guide](docs/INTEGRATION_BZOD.md)
 - [Performance Benchmarks](docs/BENCHMARKS.md)
 - [Changelog](CHANGELOG.md)
 - [License](LICENSE)
-```bash
+---
 docker compose up -d
 ```
 ### CasaOS
 ```text
 /DATA/AppData/nx9-auth
 ├── config
 ├── db
 ├── state
 └── backups
 ```
 ## Security
 * Argon2id password hashing
 * BLAKE3 token hashing
 * Session revocation
 * Transactional audit logging
 * Timing attack mitigation
 * Security regression test suite
 ## Testing
 ```bash
 cargo test --all
 ```
 Current test coverage includes:
 * Unit tests
 * Integration tests
 * Security tests
 * Migration compatibility tests
 * CLI tests
 ## Roadmap
 ### v0.1.x
 * Stable IAM core
 * BZOD integration
 ### v0.2.x
 * OAuth2 Authorization Server
 * OpenID Connect (OIDC)
 * PKCE support
 ## License
-Apache 2.0 or MIT -- Dual License
+Dual-licensed under either of:
 - Apache License, Version 2.0 ([LICENSE](LICENSE) or http://www.apache.org/licenses/LICENSE-2.0)
 - MIT License ([LICENSE](LICENSE) or http://opensource.org/licenses/MIT)
-```
+at your option.
 ```
@@ -0,0 +1,23 @@
 # NX9-Auth v0.3.0 Release Notes
 NX9-Auth v0.3.0 brings full architectural stabilization, unified runtime lifecycle management, and production-grade operational robustness to self-hosted Identity and Access Management.
 ## Key Features & Highlights
 ### ⚡ Unified Modular Runtime Subsystem
 - **Application Container & Builder**: Pure dependency assembly separating configuration, database provider initializations, repository traits, and router construction.
 - **Lock-Free State Machine**: `AtomicRuntimeState` tracks granular lifecycle states without mutex contention.
 - **Signal Handling & Cancellation**: Multi-signal Unix signal manager handling `SIGINT` (Ctrl+C) and `SIGTERM` with parent-child cancellation tokens.
 ### 🛡️ Operational Stability & Graceful Shutdown
 - **Orderly Shutdown Flow**: `Running` -> `Draining` -> `StoppingWorkers` -> `ExecutingHooks` -> `ClosingResources` -> `Stopped`.
 - **Prioritized Hook Execution**: Supports custom shutdown hooks executed in priority order with error isolation.
 - **Background Worker Management**: `WorkerManager` manages background task groups with configurable timeout cancellation.
 ### 🗄️ Dual-Database Engine Support
 - Native support for SQLite (WAL mode, foreign keys, busy timeout) and PostgreSQL with automatic migrations and robust connection retry policies.
 ### 🚀 Developer & Operator Experience
 - Built-in single binary execution (`nx9-auth serve`).
 - Diagnostic `nx9-auth doctor` command for environment verification.
 - Full Admin SPA UI shell embedded directly in the single binary.
@@ -8,6 +8,17 @@ host = "0.0.0.0"
 # Port the service listens on.
 port = 8655
 # Session cookie Secure flag.
 # false = works over plain HTTP (typical self-hosted / LAN).
 # true  = required when the UI is served over HTTPS (or a TLS reverse proxy).
 # If Secure=true on plain HTTP, browsers drop the cookie and login/password
 # reset will appear broken (subsequent API calls return 401).
 cookie_secure = false
 # Production mode: refuses cookie_secure=false and enables HSTS headers.
 # TLS is usually terminated at a reverse proxy; set cookie_secure=true there.
 production = false
 [database]
 # Absolute path to the SQLite database file.
 # The directory must be writable by the nx9-auth user.
@@ -38,3 +49,10 @@ argon2_parallelism = 1
 # Enable structured audit logging to the database.
 # Disable only in development environments.
 enabled = true
 [shutdown]
 # Maximum time in seconds to wait for active HTTP requests and background workers to drain.
 graceful_timeout_secs = 30
 # Hard timeout in seconds after which task cancellation is forced. Must be > graceful_timeout_secs.
 force_timeout_secs = 35
@@ -0,0 +1,47 @@
 [Unit]
 Description=nx9-auth Identity and Access Management Service
 Documentation=https://github.com/nx9/nx9-auth
 After=network.target
 Wants=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
 TimeoutStopSec=10s
 # Security hardening
 ProtectSystem=strict
 ProtectHome=true
 PrivateTmp=true
 NoNewPrivileges=true
 CapabilityBoundingSet=
 AmbientCapabilities=
 LockPersonality=true
 MemoryDenyWriteExecute=true
 PrivateDevices=true
 ProtectClock=true
 ProtectControlGroups=true
 ProtectHostname=true
 ProtectKernelLogs=true
 ProtectKernelModules=true
 ProtectKernelTunables=true
 RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
 RestrictNamespaces=true
 RestrictRealtime=true
 SystemCallArchitectures=native
 SystemCallFilter=@system-service
 # Writable paths (everything else is read-only via ProtectSystem=strict)
 ReadWritePaths=/var/lib/nx9-auth /var/log/nx9-auth
 # Logging
 StandardOutput=journal
 StandardError=journal
 SyslogIdentifier=nx9-auth
 [Install]
 WantedBy=multi-user.target
@@ -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.
@@ -0,0 +1,100 @@
 # Authentication Security
 nx9-auth implements an OWASP-aligned login flow.
 ## Login contract
 ```http
 POST /api/v1/auth/login
 Content-Type: application/json
 Accept: application/json
 {
  "username": "sunil",
  "password": "Password123!"
 }
 ```
 ### Response (200)
 ```json
 {
  "access_token": "<opaque session token>",
  "refresh_token": "<opaque refresh token>",
  "expires_in": 86400,
  "token_type": "Bearer",
  "user": {
    "id": "...",
    "username": "...",
    "status": "active",
    "roles": ["admin"],
    "permissions": ["users:create", "..."]
  }
 }
 ```
 Also sets an HttpOnly `nx9_session` cookie (same value as `access_token`).
 ### Failures
 | Status | Meaning |
 |--------|---------|
 | 401 | Invalid username or password (non-enumerating) |
 | 400 | Malformed request body |
 | 429 | Rate limited |
 There is **no GET login**. Query-string credentials are never accepted.
 ## Password handling
 | Layer | Behavior |
 |-------|----------|
 | Transport | HTTPS in production (`cookie_secure` + reverse-proxy TLS) |
 | Client | Sends plaintext password **only** in POST JSON body — never hashes client-side |
 | Server | Argon2id PHC (`$argon2id$v=19$…`) with unique salt |
 | Storage | Only password hashes — never plaintext |
 | Logs | Never log password, tokens, cookies, or Authorization |
 ## Session security
 - New session token on every successful login (rotation)
 - Prior sessions and refresh tokens revoked on login (fixation mitigation)
 - Idle TTL + absolute TTL
 - Session token hashed (BLAKE3) at rest
 - Refresh tokens hashed (BLAKE3) in `refresh_tokens` table
 ## SPA client
 1. `POST /api/v1/auth/login` with JSON
 2. Store `access_token` in `sessionStorage`
 3. Send `Authorization: Bearer <access_token>` on subsequent requests
 4. Browser may also store HttpOnly cookie automatically
 The HTML login form uses `method="post"` so a native fallback cannot leak credentials into the URL.
 ## Production configuration
 ```toml
 [server]
 cookie_secure = true
 production = true
 ```
 - `production = true` refuses `cookie_secure = false`
 - Enables `Strict-Transport-Security` when secure mode is on
 - Terminate TLS (TLS 1.3 recommended) at a reverse proxy or load balancer
 ## Security headers
 Every response includes:
 - `X-Content-Type-Options: nosniff`
 - `X-Frame-Options: DENY`
 - `Referrer-Policy: no-referrer`
 - `Content-Security-Policy: …`
 - `Permissions-Policy: …`
 - `Strict-Transport-Security` (when production/secure)
 ## Rate limiting
 Login is rate-limited per IP with progressive lockout (see `security::rate_limit`).
@@ -1,6 +1,10 @@
-# Running nx9-auth in Docker
+**License:** Apache-2.0 / MIT Dual License  
-This guide explains how to build, run, initialize, and manage `nx9-auth` using Docker and Docker Compose.
+---
 ## Architectural Rationale: Root Docker Manifests
 The `Dockerfile`, `docker-compose.yml`, and `compose.casaos.yml` reside at the repository root to comply with standard Docker tooling standards (`docker build .`, `docker compose up`), automated container registry build triggers (Docker Hub, GHCR), and platform app managers (CasaOS, Portainer).
 ---
@@ -9,7 +13,7 @@ This guide explains how to build, run, initialize, and manage `nx9-auth` using D
 To build the Docker image locally:
 ```bash
-docker build -t nx9-auth:0.1.0-rc1 .
+docker build -t nx9-auth:v0.3.0 .
 ```
 ---
@@ -0,0 +1,30 @@
 # Refactor Report
 ## Summary
 The runtime layer was refactored to restore the missing application startup API and make the project build successfully again.
 ## What changed
 - Added a runtime application container in [src/runtime/application.rs](../src/runtime/application.rs) with lifecycle support and shared runtime state.
 - Added an application builder in [src/runtime/builder.rs](../src/runtime/builder.rs) so the binary can construct the runtime through the expected builder pattern.
 - Added lightweight runtime metrics support in [src/runtime/metrics.rs](../src/runtime/metrics.rs).
 - Updated the runtime module exports in [src/runtime/mod.rs](../src/runtime/mod.rs) to expose the newly introduced components.
 - Set the Rust toolchain to the installed stable toolchain so builds no longer fail due to an unconfigured default toolchain.
 ## Verification
 The changes were verified with:
 ```bash
 export RUSTUP_TOOLCHAIN=stable-x86_64-unknown-linux-gnu && cargo build --release
 ```
 Result:
 - Build completed successfully
 - Output ended with: `Finished release profile [optimized] target(s) in 1m 16s`
 ## Notes
 This refactor focused on restoring the expected runtime API surface with minimal, compatible implementations so the existing application entrypoint and build pipeline continue to function.
@@ -0,0 +1,63 @@
 # Runtime Lifecycle Subsystem
 The `nx9-auth` runtime lifecycle subsystem provides an enterprise-grade, lock-free, deterministic architecture for application startup, dependency assembly, operational observability, background worker coordination, prioritized shutdown hooks, and graceful HTTP server termination.
 ## Architecture Overview
 ```
 CLI Commands / binary entrypoint (main.rs)
   │
   ▼
 ApplicationBuilder
   │
   ├── Database Initialization (SQLite / PostgreSQL)
   ├── Repository Provider Assembly
   ├── AppState Construction
   └── Router Construction (Axum API + SPA UI)
   │
   ▼
 Application Container (Lifecycle)
   │
   ├── AtomicRuntimeState Machine
   ├── SignalManager (SIGINT / SIGTERM)
   ├── ShutdownCoordinator (CancellationToken Hierarchy)
   ├── WorkerManager (Task Groups)
   ├── HookRegistry (Prioritized Shutdown Hooks)
   └── RuntimeMetrics
   │
   ▼
 axum::serve (HTTP Server)
 ```
 ## Lifecycle States (`RuntimeState`)
 The state machine is lock-free and driven by `AtomicU8` with `compare_exchange` transitions.
 | State | Value | Description |
 | :--- | :--- | :--- |
 | `Initializing` | 0 | Runtime configuration loading and dependency assembly. |
 | `Starting` | 1 | Database connection pool init, migrations, router assembly. |
 | `Running` | 2 | HTTP server bound and actively serving requests. |
 | `Draining` | 3 | Shutdown signal received; server stops accepting new connections, draining existing HTTP requests. |
 | `StoppingWorkers` | 4 | Cancelling and joining active background worker tasks. |
 | `ExecutingHooks` | 5 | Executing registered shutdown hooks in priority order (`First` -> `Normal` -> `Last`). |
 | `ClosingResources` | 6 | Closing database connection pools and flushing logs. |
 | `Stopped` | 7 | All resources released cleanly; runtime process exits with status 0. |
 ## Startup Sequence
 1. `main()` parses CLI flags and loads configuration via `Config::find_and_load()`.
 2. `run_server()` invokes `Application::builder(config).build().await`.
 3. `ApplicationBuilder` creates `Application` and executes `initialize()`.
 4. `initialize()` transitions state to `Starting`, connects database pool, executes migrations, and builds `Router`.
 5. `app.start().await` transitions state to `Running`, binds `TcpListener`, prints `Listening on <addr>`, and awaits `axum::serve`.
 ## Graceful Shutdown Sequence
 1. `SIGINT` (Ctrl+C) or `SIGTERM` signal received by `SignalManager` or `ShutdownCoordinator`.
 2. `axum::serve` completes its graceful shutdown loop, stopping the TCP listener.
 3. State transitions to `Draining`.
 4. State transitions to `StoppingWorkers`; `WorkerManager` cancels and joins task groups.
 5. State transitions to `ExecutingHooks`; `HookRegistry` executes registered hooks.
 6. State transitions to `ClosingResources`; `PoolHandle` closes the database pool.
 7. State transitions to `Stopped`; application returns `Ok(())` with exit status 0.
@@ -0,0 +1,33 @@
 # NX9-Auth Security Policy & Controls
 NX9-Auth is designed with a **security-first, privacy-first, zero-trust** architecture for self-hosted Identity & Access Management.
 ## Authentication & Password Security
 - **POST-Only Authentication**: Login requests (`/api/v1/auth/login`) strictly accept JSON payloads via HTTP `POST`. GET login is rejected (HTTP 405) to prevent credentials from being exposed in URL query parameters, browser history, or server access logs.
 - **Argon2id Password Hashing**: Passwords are hashed server-side using **Argon2id** (`$argon2id$v=19$m=19456,t=2,p=1$…`) with unique cryptographically random salts. Plaintext passwords are never stored, logged, or echoed.
 - **Constant-Time Verification**: Password verification uses constant-time string comparisons (`subtle` / Argon2 verify) to eliminate timing side-channel attacks.
 - **Non-Enumerating Error Messages**: Authentication failures return standardized error messages (`401 Unauthorized: Invalid username or password`) regardless of whether the user exists.
 ## HTTP & Session Security
 - **Opaque Session & Refresh Tokens**: Tokens are generated via high-entropy `getrandom` buffers (`st_…`, `rt_…`, `pat_…`) and hashed using BLAKE3 at rest.
 - **Cookie Security**: Session cookies (`nx9_session`) are set with `HttpOnly`, `SameSite=Lax`, and `Secure` (in production/HTTPS mode).
 - **OWASP Security Headers**:
  - `X-Content-Type-Options: nosniff`
  - `X-Frame-Options: DENY`
  - `Referrer-Policy: no-referrer`
  - `Cache-Control: no-store`
  - `Content-Security-Policy: default-src 'self' ...`
  - `Permissions-Policy: accelerometer=(), camera=(), geolocation=(), ...`
  - `Strict-Transport-Security: max-age=63072000; includeSubDomains` (when `cookie_secure` / production is enabled)
 ## Audit Logging Security
 Audit logs record critical identity lifecycle events while strictly redacting sensitive fields:
 - **Recorded Events**: Login success/failure, logout, password change, user creation/deletion, API token issuance/revocation, role/permission assignments.
 - **Redaction Rules**: Plaintext passwords, password hashes, bearer tokens, refresh tokens, session secrets, and `Authorization` headers are **never** logged under any circumstances.
 ## Rate Limiting & Protection
 - **Progressive Lockout**: Progressive rate limiting protects sensitive endpoints (`/auth/login`, `/users/{id}/reset-password`, `/tokens`) against brute-force and credential-stuffing attacks.
@@ -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,20 @@
 # ADR 0001: Modular Runtime Architecture and State Machine
 ## Status
 Accepted
 ## Context
 Following an initial refactor, the application runtime lacked a unified lifecycle container capable of keeping the HTTP server process alive while coordinating background workers, signal handling, and connection pool teardown.
 ## Decision
 We adopted a modular runtime architecture in `src/runtime/`:
 1. `Application`: Application container implementing `Lifecycle` (`initialize`, `start`, `shutdown`).
 2. `ApplicationBuilder`: Builder pattern separating dependency wiring from runtime logic.
 3. `AtomicRuntimeState`: Lock-free `AtomicU8` state machine ensuring atomic state transitions.
 4. `SignalManager` & `ShutdownCoordinator`: Signal routing and hierarchical cancellation.
 5. `HookRegistry` & `WorkerManager`: Extensible shutdown hooks and worker task tracking.
 ## Consequences
 - Clean separation of concern between CLI parsing, dependency resolution, HTTP serving, and shutdown logic.
 - Zero risk of zombie processes or unclosed database connections on SIGINT/SIGTERM.
 - Fully observable startup and shutdown transitions.
@@ -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>
@@ -0,0 +1,69 @@
 #!/usr/bin/env bash
 # Build the Dioxus web UI into ui/dist for serving by nx9-auth.
 set -euo pipefail
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$ROOT"
 TARGET="${CARGO_TARGET_DIR:-$ROOT/target}"
 WASM_OUT="$TARGET/wasm32-unknown-unknown/release/nx9-auth-ui.wasm"
 DIST="$ROOT/ui/dist"
 echo "==> Building nx9-auth-ui (wasm32-unknown-unknown, release)"
 cargo build --manifest-path ui/Cargo.toml --target-dir "$TARGET" --target wasm32-unknown-unknown --release
 if [ ! -f "$WASM_OUT" ] && [ -f "$ROOT/ui/target/wasm32-unknown-unknown/release/nx9-auth-ui.wasm" ]; then
  WASM_OUT="$ROOT/ui/target/wasm32-unknown-unknown/release/nx9-auth-ui.wasm"
 fi
 WBG_VER="$(cargo tree -p nx9-auth-ui -i wasm-bindgen --depth 0 2>/dev/null | head -1 | sed -n 's/.*v\([0-9.]*\).*/\1/p')"
 WBG_VER="${WBG_VER:-0.2.125}"
 if ! command -v wasm-bindgen >/dev/null 2>&1 || ! wasm-bindgen --version 2>/dev/null | grep -q "$WBG_VER"; then
  echo "==> Ensuring wasm-bindgen ${WBG_VER}"
  TMP="${TMPDIR:-/tmp}/nx9-wbg"
  mkdir -p "$TMP"
  URL="https://github.com/rustwasm/wasm-bindgen/releases/download/${WBG_VER}/wasm-bindgen-${WBG_VER}-x86_64-unknown-linux-musl.tar.gz"
  if curl -fsSL "$URL" -o "$TMP/wbg.tar.gz"; then
    tar -xzf "$TMP/wbg.tar.gz" -C "$TMP"
    WBG="$(find "$TMP" -name wasm-bindgen -type f | head -1)"
  else
    WBG="wasm-bindgen"
  fi
 else
  WBG="wasm-bindgen"
 fi
 echo "==> Packaging with wasm-bindgen ($("$WBG" --version 2>/dev/null || true))"
 rm -rf "$DIST"
 mkdir -p "$DIST/assets"
 "$WBG" "$WASM_OUT" \
  --out-dir "$DIST" \
  --out-name nx9_auth_ui \
  --target web \
  --no-typescript
 cp -f "$ROOT/ui/assets/style.css" "$DIST/assets/style.css"
 cp -f "$ROOT/ui/assets/boot.js" "$DIST/assets/boot.js"
 cp -f "$ROOT/ui/assets/favicon.svg" "$DIST/assets/favicon.svg"
 # Use the canonical index with absolute module paths + error surface
 cp -f "$ROOT/ui/index.html" "$DIST/index.html"
 # Also place next to the release binary for single-binary-adjacent deploys
 RELEASE_UI="$TARGET/release/ui/dist"
 if [ -d "$TARGET/release" ]; then
  mkdir -p "$RELEASE_UI"
  cp -a "$DIST/." "$RELEASE_UI/"
  echo "==> Also copied to $RELEASE_UI"
 fi
 echo "==> UI assets ready in $DIST"
 ls -lah "$DIST"
 # Quick sanity: required files
 for f in index.html nx9_auth_ui.js nx9_auth_ui_bg.wasm assets/style.css; do
  if [ ! -e "$DIST/$f" ]; then
    echo "ERROR: missing $DIST/$f" >&2
    exit 1
  fi
 done
 echo "==> Sanity check OK"
@@ -0,0 +1,171 @@
 #!/usr/bin/env bash
 # deploy.sh — nx9-auth installer for Debian/Ubuntu systems
 #
 # Usage: sudo bash deploy.sh [path/to/nx9-auth-binary]
 # Requires: root, systemd
 set -euo pipefail
 BINARY_PATH="${1:-./target/release/nx9-auth}"
 SERVICE_USER="nx9-auth"
 INSTALL_BIN="/usr/local/bin/nx9-auth"
 CONFIG_DIR="/etc/nx9-auth"
 DATA_DIR="/var/lib/nx9-auth"
 LOG_DIR="/var/log/nx9-auth"
 SERVICE_FILE="/etc/systemd/system/nx9-auth.service"
 # ── Colours ───────────────────────────────────────────────────────────────────
 RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
 ok()   { echo -e "${GREEN}  ✓${NC}  $*"; }
 warn() { echo -e "${YELLOW}  !${NC}  $*"; }
 fail() { echo -e "${RED}  ✗${NC}  $*"; exit 1; }
 # ── Prerequisites ─────────────────────────────────────────────────────────────
 [[ $EUID -eq 0 ]] || fail "This script must be run as root."
 [[ -f "$BINARY_PATH" ]] || fail "Binary not found at: $BINARY_PATH — build with 'cargo build --release' first."
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo "   nx9-auth deploy"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo ""
 # ── Create system user ────────────────────────────────────────────────────────
 if id -u "$SERVICE_USER" &>/dev/null; then
    warn "System user '$SERVICE_USER' already exists — skipping creation."
 else
    useradd --system --no-create-home --shell /usr/sbin/nologin "$SERVICE_USER"
    ok "Created system user: $SERVICE_USER"
 fi
 # ── Create directories ────────────────────────────────────────────────────────
 for dir in "$CONFIG_DIR" "$DATA_DIR" "$LOG_DIR"; do
    mkdir -p "$dir"
    chown "$SERVICE_USER:$SERVICE_USER" "$dir"
    chmod 750 "$dir"
 done
 ok "Directories created: $CONFIG_DIR, $DATA_DIR, $LOG_DIR"
 # ── Install binary ────────────────────────────────────────────────────────────
 cp "$BINARY_PATH" "$INSTALL_BIN"
 chmod 755 "$INSTALL_BIN"
 ok "Binary installed: $INSTALL_BIN"
 # ── Write default config if not present ──────────────────────────────────────
 if [[ ! -f "$CONFIG_DIR/config.toml" ]]; then
    cat > "$CONFIG_DIR/config.toml" <<'EOF'
 [server]
 host = "0.0.0.0"
 port = 8655
 [database]
 path = "/var/lib/nx9-auth/auth.db"
 [security]
 session_ttl_hours = 24
 session_absolute_ttl_days = 30
 token_ttl_days = 365
 argon2_memory = 65536
 argon2_iterations = 3
 argon2_parallelism = 1
 [audit]
 enabled = true
 EOF
    chown root:"$SERVICE_USER" "$CONFIG_DIR/config.toml"
    chmod 640 "$CONFIG_DIR/config.toml"
    ok "Default config written: $CONFIG_DIR/config.toml"
 else
    warn "Config already exists — skipping: $CONFIG_DIR/config.toml"
 fi
 # ── Install systemd service ───────────────────────────────────────────────────
 cat > "$SERVICE_FILE" <<EOF
 [Unit]
 Description=nx9-auth Identity and Access Management Service
 Documentation=https://github.com/nx9/nx9-auth
 After=network.target
 Wants=network.target
 [Service]
 Type=simple
 User=$SERVICE_USER
 Group=$SERVICE_USER
 ExecStart=$INSTALL_BIN serve --config $CONFIG_DIR/config.toml
 Restart=on-failure
 RestartSec=5s
 TimeoutStopSec=10s
 # Security hardening
 ProtectSystem=strict
 ProtectHome=true
 PrivateTmp=true
 NoNewPrivileges=true
 CapabilityBoundingSet=
 AmbientCapabilities=
 LockPersonality=true
 MemoryDenyWriteExecute=true
 PrivateDevices=true
 ProtectClock=true
 ProtectControlGroups=true
 ProtectHostname=true
 ProtectKernelLogs=true
 ProtectKernelModules=true
 ProtectKernelTunables=true
 RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
 RestrictNamespaces=true
 RestrictRealtime=true
 SystemCallArchitectures=native
 SystemCallFilter=@system-service
 # Writable paths
 ReadWritePaths=$DATA_DIR $LOG_DIR
 # Logging
 StandardOutput=journal
 StandardError=journal
 SyslogIdentifier=nx9-auth
 [Install]
 WantedBy=multi-user.target
 EOF
 chmod 644 "$SERVICE_FILE"
 ok "Systemd service installed: $SERVICE_FILE"
 # ── Initialize database and configuration ─────────────────────────────────────
 echo ""
 echo "Initializing database and configuration..."
 sudo -u "$SERVICE_USER" "$INSTALL_BIN" init --config "$CONFIG_DIR/config.toml" --non-interactive --skip-admin
 ok "Initialization complete"
 # ── Enable and start service ──────────────────────────────────────────────────
 systemctl daemon-reload
 systemctl enable nx9-auth
 systemctl restart nx9-auth
 ok "nx9-auth service enabled and started"
 # ── Doctor check ──────────────────────────────────────────────────────────────
 echo ""
 sleep 2  # Brief wait for service to start
 sudo -u "$SERVICE_USER" "$INSTALL_BIN" doctor --config "$CONFIG_DIR/config.toml" || true
 # ── Summary ───────────────────────────────────────────────────────────────────
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo "   nx9-auth deployed successfully!"
 echo ""
 echo "   Service:  systemctl status nx9-auth"
 echo "   Logs:     journalctl -u nx9-auth -f"
 echo "   Config:   $CONFIG_DIR/config.toml"
 echo "   Database: $DATA_DIR/auth.db"
 echo ""
 echo "   Next step:"
 echo "   Create your first administrator account:"
 echo "   sudo -u nx9-auth nx9-auth init --config $CONFIG_DIR/config.toml"
 echo ""
 echo "   Then verify:"
 echo "   systemctl status nx9-auth"
 echo "   curl http://127.0.0.1:8655/health"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo ""
@@ -0,0 +1,123 @@
 use axum::{
    Json,
    extract::{Path, State},
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 use crate::{
    db::models::{Application, Tenant},
    error::Result,
    identity::applications as identity,
    middleware::{auth::AuthUser, permissions::require},
    state::AppState,
 };
 #[derive(Serialize)]
 pub struct ApplicationResponse {
    pub id: String,
    pub name: String,
    pub slug: String,
    /// Client ID — currently the application slug (OAuth2-ready).
    pub client_id: String,
    pub enabled: bool,
    pub redirect_urls: Vec<String>,
    pub scopes: Vec<String>,
    pub created_at: String,
    pub updated_at: String,
 }
 impl From<Application> for ApplicationResponse {
    fn from(a: Application) -> Self {
        Self {
            id: a.id,
            name: a.name,
            client_id: a.slug.clone().unwrap_or_default(),
            slug: a.slug.unwrap_or_default(),
            enabled: a.enabled,
            // Placeholder until OAuth2 tables land
            redirect_urls: Vec::new(),
            scopes: Vec::new(),
            created_at: a.created_at,
            updated_at: a.updated_at,
        }
    }
 }
 /// GET /api/v1/applications
 pub async fn list_applications(
    State(state): State<AppState>,
    auth: AuthUser,
 ) -> Result<Json<Value>> {
    // Any authenticated user can see registered apps; mutations need roles:manage
    let apps = identity::list(&state.provider, Tenant::DEFAULT_ID).await?;
    let views: Vec<ApplicationResponse> = apps.into_iter().map(ApplicationResponse::from).collect();
    let _ = auth;
    Ok(Json(json!({ "applications": views })))
 }
 #[derive(Debug, Deserialize)]
 pub struct CreateApplicationRequest {
    pub name: String,
    pub slug: String,
 }
 /// POST /api/v1/applications
 pub async fn create_application(
    State(state): State<AppState>,
    auth: AuthUser,
    Json(body): Json<CreateApplicationRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let app = identity::create(&state.provider, Tenant::DEFAULT_ID, &body.name, &body.slug).await?;
    Ok(Json(
        json!({ "application": ApplicationResponse::from(app) }),
    ))
 }
 /// GET /api/v1/applications/:id
 pub async fn get_application(
    State(state): State<AppState>,
    auth: AuthUser,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    let _ = auth;
    let app = identity::get(&state.provider, &id).await?;
    Ok(Json(
        json!({ "application": ApplicationResponse::from(app) }),
    ))
 }
 #[derive(Debug, Deserialize)]
 pub struct UpdateApplicationRequest {
    pub name: String,
    pub slug: String,
    pub enabled: bool,
 }
 /// PATCH /api/v1/applications/:id
 pub async fn update_application(
    State(state): State<AppState>,
    auth: AuthUser,
    Path(id): Path<String>,
    Json(body): Json<UpdateApplicationRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let app = identity::update(&state.provider, &id, &body.name, &body.slug, body.enabled).await?;
    Ok(Json(
        json!({ "application": ApplicationResponse::from(app) }),
    ))
 }
 /// DELETE /api/v1/applications/:id
 pub async fn delete_application(
    State(state): State<AppState>,
    auth: AuthUser,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    identity::delete(&state.provider, &id).await?;
    Ok(Json(json!({ "success": true })))
 }
@@ -0,0 +1,116 @@
 use axum::{
    Json,
    extract::{Query, State},
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 use crate::{
    db::models::{AuditFilter, AuditLog},
    db::repository::audit as audit_repo,
    error::{AppError, Result},
    middleware::{auth::AuthUser, permissions::require},
    state::AppState,
 };
 #[derive(Serialize)]
 pub struct AuditLogResponse {
    pub id: String,
    pub actor_user_id: Option<String>,
    pub target_user_id: Option<String>,
    pub action: String,
    pub resource_type: String,
    pub resource_id: Option<String>,
    pub severity: String,
    pub ip_address: Option<String>,
    pub user_agent: Option<String>,
    pub metadata_json: Option<String>,
    pub created_at: String,
    /// Convenience flag for success/failure filters in the UI.
    pub success: bool,
 }
 impl From<AuditLog> for AuditLogResponse {
    fn from(a: AuditLog) -> Self {
        let success =
            !a.action.contains("fail") && !a.action.contains("denied") && a.severity != "critical";
        Self {
            id: a.id,
            actor_user_id: a.actor_user_id,
            target_user_id: a.target_user_id,
            action: a.action,
            resource_type: a.resource_type,
            resource_id: a.resource_id,
            severity: a.severity,
            ip_address: a.ip_address,
            user_agent: a.user_agent,
            metadata_json: a.metadata_json,
            created_at: a.created_at,
            success,
        }
    }
 }
 #[derive(Debug, Deserialize)]
 pub struct AuditQuery {
    pub actor: Option<String>,
    pub action: Option<String>,
    pub resource_type: Option<String>,
    pub severity: Option<String>,
    pub since: Option<String>,
    pub until: Option<String>,
    pub q: Option<String>,
    pub success: Option<bool>,
    pub limit: Option<i64>,
    pub offset: Option<i64>,
 }
 /// GET /api/v1/audit
 pub async fn list_audit(
    State(state): State<AppState>,
    auth: AuthUser,
    Query(query): Query<AuditQuery>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "audit:view").await?;
    let limit = query.limit.unwrap_or(50).clamp(1, 500);
    let offset = query.offset.unwrap_or(0).max(0);
    let filter = AuditFilter {
        actor_user_id: query.actor,
        action: query.action,
        resource_type: query.resource_type,
        severity: query.severity,
        since: query.since,
        until: query.until,
        search: query.q,
        limit,
        offset,
    };
    let total = audit_repo::count_filtered(&state.provider, &filter)
        .await
        .map_err(AppError::Database)?;
    let mut entries = audit_repo::list_filtered(&state.provider, &filter)
        .await
        .map_err(AppError::Database)?;
    if let Some(success) = query.success {
        entries.retain(|e| {
            let ok = !e.action.contains("fail")
                && !e.action.contains("denied")
                && e.severity != "critical";
            ok == success
        });
    }
    let views: Vec<AuditLogResponse> = entries.into_iter().map(AuditLogResponse::from).collect();
    Ok(Json(json!({
        "entries": views,
        "total": total,
        "limit": limit,
        "offset": offset,
    })))
 }
@@ -1,14 +1,19 @@
 use crate::db::repository::traits::AuditRepositoryExt;
 // Authentication endpoints.
 //
 // Login is POST-only with a JSON body. Credentials must never appear in
 // query strings, path segments, or server access logs of request URIs.
 use axum::{Json, extract::State};
 use axum_extra::extract::{CookieJar, cookie::Cookie};
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 use crate::{
-    audit::{self, AuditEvent},
+    audit::AuditEvent,
    db::models::AuditSeverity,
    db::repository::users as user_repo,
    error::{AppError, Result},
    identity::{permissions, roles},
    middleware::{audit::AuditContext, auth::AuthUser},
    security::{passwords, sessions},
    state::AppState,
@@ -16,30 +21,64 @@ use crate::{
 // ── Login ─────────────────────────────────────────────────────────────────────
 /// Login request body. Deserialized from JSON only (never from query params).
 #[derive(Debug, Deserialize)]
 pub struct LoginRequest {
    pub username: String,
    pub password: String,
 }
 #[derive(Debug, Serialize)]
 pub struct LoginUserView {
    pub id: String,
    pub username: String,
    pub status: String,
    pub last_login_at: Option<String>,
    pub created_at: String,
    pub roles: Vec<String>,
    pub permissions: Vec<String>,
 }
 #[derive(Debug, Serialize)]
 pub struct LoginResponse {
    /// Opaque access token (session). Send as `Authorization: Bearer …`.
    pub access_token: String,
    /// Opaque refresh token. Longer-lived; used to obtain a new access token.
    pub refresh_token: String,
    /// Access token lifetime in seconds (idle TTL).
    pub expires_in: u64,
    pub token_type: &'static str,
    pub user: LoginUserView,
 }
 /// POST /api/v1/auth/login
 ///
 /// Accepts JSON `{ "username", "password" }` only. No GET handler exists.
 pub async fn login(
    State(state): State<AppState>,
    ctx: AuditContext,
    jar: CookieJar,
    Json(body): Json<LoginRequest>,
-) -> Result<(CookieJar, Json<Value>)> {
+) -> Result<(CookieJar, Json<LoginResponse>)> {
    let ip = ctx.ip_address.as_deref();
-    // Rate limit check
+    // Reject empty credentials early without revealing which field failed.
    if body.username.trim().is_empty() || body.password.is_empty() {
        return Err(AppError::InvalidCredentials);
    }
    // Rate limit check (per IP)
    if let Some(ip_str) = &ctx.ip_address {
        if let Ok(ip_addr) = ip_str.parse::<std::net::IpAddr>() {
            state.rate_limiter.check(ip_addr)?;
        }
    }
-    // Look up user
+    // Look up user — always run comparable work on failure paths (timing).
-    let user_opt = user_repo::find_by_username(&state.pool, &body.username)
+    let user_opt = state
        .provider
        .users()
        .find_by_username(body.username.trim())
        .await
        .map_err(AppError::Database)?;
@@ -47,27 +86,36 @@ pub async fn login(
    let mut final_user = None;
    if let Some(user) = user_opt {
        // Constant-time Argon2id verify (argon2 crate).
        let password_ok = passwords::verify_password(&body.password, &user.password_hash)?;
        if password_ok && user.is_active() {
            is_authed = true;
            final_user = Some(user);
        }
    } else {
-        // Run dummy verify to take same execution time
+        // Dummy verify to reduce username enumeration via timing.
        passwords::verify_dummy(&state.config.security)?;
    }
    // Zeroize is best-effort; String drop is immediate after this function.
    // Do not log body.password anywhere.
    let _ = &body.password;
    if !is_authed {
-        record_login_failure(&state, &body.username, ip, ctx.user_agent.as_deref()).await;
+        record_login_failure(&state, body.username.trim(), ip, ctx.user_agent.as_deref()).await;
        if let Some(ip_str) = &ctx.ip_address {
            if let Ok(ip_addr) = ip_str.parse::<std::net::IpAddr>() {
                state.rate_limiter.record_failure(ip_addr);
            }
        }
-        return Err(AppError::Unauthorized);
+        // Non-enumerating error for both unknown user and bad password.
        return Err(AppError::InvalidCredentials);
    }
-    let user = final_user.unwrap();
+    let user = match final_user {
        Some(u) => u,
        None => return Err(AppError::InvalidCredentials),
    };
    // Clear rate limit on success
    if let Some(ip_str) = &ctx.ip_address {
@@ -76,22 +124,65 @@ pub async fn login(
        }
    }
-    // Create session
+    // Session fixation mitigation: revoke prior sessions + refresh tokens.
-    let (session, raw_token) = sessions::create_session(
+    let _ = state
-        &state.pool,
+        .provider
        .sessions()
        .revoke_all_for_user(&user.id)
        .await;
    let _ = state
        .provider
        .refresh_tokens()
        .revoke_all_for_user(&user.id)
        .await;
    // Create new session (new ID + new token) — rotation on every login.
    let session_id = uuid::Uuid::new_v4().to_string();
    let access_token = crate::security::sessions::generate_session_token();
    let token_hash = crate::security::sessions::hash_session_token(&access_token);
    let ttl_mins = (state.config.security.session_ttl_hours * 60) as i64;
    let expires = chrono::Utc::now() + chrono::Duration::minutes(ttl_mins);
    let expires_str = expires.format("%Y-%m-%dT%H:%M:%SZ").to_string();
    let session = state
        .provider
        .sessions()
        .create(
            &session_id,
            &user.id,
            &token_hash,
            ip,
            ctx.user_agent.as_deref(),
-        &state.config.security,
+            &expires_str,
        )
-    .await?;
+        .await
        .map_err(AppError::Database)?;
-    // Update last_login_at and audit in the same transaction
+    // Refresh token (opaque, BLAKE3-hashed at rest). Longer absolute lifetime.
-    if let Ok(mut tx) = state.pool.begin().await {
+    let refresh_raw = sessions::generate_session_token();
-        let _ = user_repo::set_last_login(&mut tx, &user.id).await;
+    let refresh_hash = sessions::hash_session_token(&refresh_raw);
-        let _ = audit::log(
+    let refresh_id = uuid::Uuid::new_v4().to_string();
-            &mut tx,
+    let refresh_ttl_days = state.config.security.session_absolute_ttl_days.max(1) as i64;
-            AuditEvent {
+    let refresh_expires = chrono::Utc::now() + chrono::Duration::days(refresh_ttl_days);
    let refresh_expires_str = refresh_expires.format("%Y-%m-%dT%H:%M:%SZ").to_string();
    state
        .provider
        .refresh_tokens()
        .create(&refresh_id, &user.id, &refresh_hash, &refresh_expires_str)
        .await
        .map_err(AppError::Database)?;
    let user_roles = state.provider.roles().list_for_user(&user.id).await?;
    let user_perms = state.provider.permissions().list_for_user(&user.id).await?;
    let role_names: Vec<String> = user_roles.into_iter().map(|r| r.name).collect();
    // Update last_login_at and audit (never log password / tokens).
    let _ = state.provider.users().set_last_login(&user.id).await;
    let _ = state
        .provider
        .audit()
        .log(AuditEvent {
            actor_id: Some(&user.id),
            target_id: Some(&user.id),
            action: "login_success",
@@ -101,12 +192,10 @@ pub async fn login(
            ip,
            ua: ctx.user_agent.as_deref(),
            metadata: None,
-            },
+        })
        )
        .await;
        let _ = tx.commit().await;
    }
    // Structured log: identity + outcome only (no secrets).
    tracing::info!(
        event = "login_success",
        user_id = %user.id,
@@ -114,16 +203,33 @@ pub async fn login(
        ip = ip.unwrap_or("unknown"),
    );
-    // Build secure session cookie using time::Duration for max_age
+    let expires_in = (state.config.security.session_ttl_hours as u64).saturating_mul(3600);
    let max_age_secs = state.config.security.session_absolute_ttl_days as i64 * 86400;
-    let mut cookie = Cookie::new(sessions::SESSION_COOKIE, raw_token);
+
    let mut cookie = Cookie::new(sessions::SESSION_COOKIE, access_token.clone());
    cookie.set_http_only(true);
-    cookie.set_secure(true);
+    cookie.set_secure(state.config.server.cookie_secure);
    cookie.set_same_site(axum_extra::extract::cookie::SameSite::Lax);
    cookie.set_path("/");
    cookie.set_max_age(time::Duration::seconds(max_age_secs));
-    Ok((jar.add(cookie), Json(json!({ "success": true }))))
+    let response = LoginResponse {
        access_token,
        refresh_token: refresh_raw,
        expires_in,
        token_type: "Bearer",
        user: LoginUserView {
            id: user.id.clone(),
            username: user.username.clone(),
            status: user.status().to_string(),
            last_login_at: user.last_login_at.clone(),
            created_at: user.created_at.clone(),
            roles: role_names,
            permissions: user_perms,
        },
    };
    Ok((jar.add(cookie), Json(response)))
 }
 async fn record_login_failure(
@@ -132,10 +238,15 @@ async fn record_login_failure(
    ip: Option<&str>,
    ua: Option<&str>,
 ) {
-    if let Ok(mut tx) = state.pool.begin().await {
+    // Audit: username + outcome only — never password.
-        let _ = audit::log(
+    let metadata = format!(
-            &mut tx,
+        r#"{{"username":{}}}"#,
-            AuditEvent {
+        serde_json::to_string(username).unwrap_or_else(|_| "\"\"".into())
    );
    let _ = state
        .provider
        .audit()
        .log(AuditEvent {
            actor_id: None,
            target_id: None,
            action: "login_failed",
@@ -144,12 +255,9 @@ async fn record_login_failure(
            severity: AuditSeverity::Warning,
            ip,
            ua,
-                metadata: Some(&format!(r#"{{"username":"{}"}}"#, username)),
+            metadata: Some(&metadata),
-            },
+        })
        )
        .await;
        let _ = tx.commit().await;
    }
    tracing::warn!(
        event = "login_failed",
@@ -167,13 +275,12 @@ pub async fn logout(
    jar: CookieJar,
 ) -> Result<(CookieJar, Json<Value>)> {
    if let Some(session_id) = &auth.session_id {
-        sessions::revoke_session(&state.pool, session_id).await?;
+        state.provider.sessions().revoke(session_id).await?;
-        // Audit log for logout
+        let _ = state
-        if let Ok(mut tx) = state.pool.begin().await {
+            .provider
-            let _ = audit::log(
+            .audit()
-                &mut tx,
+            .log(AuditEvent {
                AuditEvent {
                actor_id: Some(&auth.user.id),
                target_id: Some(&auth.user.id),
                action: "logout",
@@ -183,13 +290,17 @@ pub async fn logout(
                ip: None,
                ua: None,
                metadata: None,
-                },
+            })
            )
            .await;
            let _ = tx.commit().await;
        }
    }
    // Revoke refresh tokens for this user on logout (full session end).
    let _ = state
        .provider
        .refresh_tokens()
        .revoke_all_for_user(&auth.user.id)
        .await;
    let mut removal = Cookie::from(sessions::SESSION_COOKIE);
    removal.set_path("/");
    let removed = jar.remove(removal);
@@ -216,8 +327,12 @@ pub struct UserView {
 /// GET /api/v1/auth/me
 pub async fn me(State(state): State<AppState>, auth: AuthUser) -> Result<Json<MeResponse>> {
-    let user_roles = roles::list_user_roles(&state.pool, &auth.user.id).await?;
+    let user_roles = state.provider.roles().list_for_user(&auth.user.id).await?;
-    let user_perms = permissions::list_user_permissions(&state.pool, &auth.user.id).await?;
+    let user_perms = state
        .provider
        .permissions()
        .list_for_user(&auth.user.id)
        .await?;
    Ok(Json(MeResponse {
        user: UserView {
@@ -0,0 +1,228 @@
 use axum::{Json, extract::State};
 use serde_json::{Value, json};
 use crate::{
    db::models::{Tenant, UserStatus},
    error::{AppError, Result},
    identity::permissions as identity_perms,
    middleware::auth::AuthUser,
    state::AppState,
 };
 /// GET /api/v1/dashboard
 ///
 /// Returns a role-aware dashboard payload. Admins get system summary cards;
 /// all users get personal overview data.
 pub async fn dashboard(State(state): State<AppState>, auth: AuthUser) -> Result<Json<Value>> {
    let roles = state.provider.roles().list_for_user(&auth.user.id).await?;
    let permissions = identity_perms::list_user_permissions(&state.provider, &auth.user.id).await?;
    let is_admin = roles.iter().any(|r| r.name == "admin")
        || permissions
            .iter()
            .any(|p| p == "roles:manage" || p == "audit:view");
    // Personal data
    let sessions = state
        .provider
        .sessions()
        .list_active_for_user(&auth.user.id)
        .await
        .map_err(AppError::Database)?;
    let session_views: Vec<Value> = sessions
        .into_iter()
        .map(|s| {
            json!({
                "id": s.id,
                "ip_address": s.ip_address,
                "user_agent": s.user_agent,
                "created_at": s.created_at,
                "last_seen_at": s.last_seen_at,
                "expires_at": s.expires_at,
            })
        })
        .collect();
    let tokens = state
        .provider
        .tokens()
        .list_for_user(&auth.user.id)
        .await
        .map_err(AppError::Database)?;
    let token_views: Vec<Value> = tokens
        .into_iter()
        .filter(|t| !t.revoked)
        .take(10)
        .map(|t| {
            json!({
                "id": t.id,
                "name": t.name,
                "expires_at": t.expires_at,
                "created_at": t.created_at,
                "last_used_at": t.last_used_at,
            })
        })
        .collect();
    let apps = state
        .provider
        .applications()
        .list(Tenant::DEFAULT_ID)
        .await
        .map_err(AppError::Database)?;
    let app_views: Vec<Value> = apps
        .into_iter()
        .filter(|a| a.enabled)
        .map(|a| {
            json!({
                "id": a.id,
                "name": a.name,
                "slug": a.slug,
            })
        })
        .collect();
    let recent_personal = state
        .provider
        .audit()
        .list_filtered(&crate::db::models::AuditFilter {
            actor_user_id: Some(auth.user.id.clone()),
            limit: 10,
            ..Default::default()
        })
        .await
        .map_err(AppError::Database)?;
    let personal = json!({
        "user": {
            "id": auth.user.id,
            "username": auth.user.username,
            "status": auth.user.status().to_string(),
            "last_login_at": auth.user.last_login_at,
            "created_at": auth.user.created_at,
        },
        "roles": roles.iter().map(|r| &r.name).collect::<Vec<_>>(),
        "permissions": permissions,
        "sessions": session_views,
        "tokens": token_views,
        "applications": app_views,
        "recent_audit": recent_personal,
    });
    let mut payload = json!({
        "personal": personal,
        "is_admin": is_admin,
    });
    if is_admin {
        let total_users = state
            .provider
            .users()
            .count(Tenant::DEFAULT_ID)
            .await
            .map_err(AppError::Database)?;
        let active_users = state
            .provider
            .users()
            .count_by_status(Tenant::DEFAULT_ID, UserStatus::Active as i32)
            .await
            .map_err(AppError::Database)?;
        let active_sessions = state
            .provider
            .sessions()
            .count_active()
            .await
            .map_err(AppError::Database)?;
        let roles_count = state
            .provider
            .roles()
            .list_all()
            .await
            .map_err(AppError::Database)?
            .len();
        let perms_count = state
            .provider
            .permissions()
            .list_all()
            .await
            .map_err(AppError::Database)?
            .len();
        let apps_count = state
            .provider
            .applications()
            .count(Tenant::DEFAULT_ID)
            .await
            .map_err(AppError::Database)?;
        let sa_count = state
            .provider
            .service_accounts()
            .count(Tenant::DEFAULT_ID)
            .await
            .map_err(AppError::Database)?;
        let audit_count = state
            .provider
            .audit()
            .count()
            .await
            .map_err(AppError::Database)?;
        let recent_audit = state
            .provider
            .audit()
            .list_recent(15)
            .await
            .map_err(AppError::Database)?;
        let recent_logins = state
            .provider
            .audit()
            .list_filtered(&crate::db::models::AuditFilter {
                action: Some("login_success".into()),
                limit: 10,
                ..Default::default()
            })
            .await
            .map_err(AppError::Database)?;
        let recent_users = state
            .provider
            .users()
            .list(Tenant::DEFAULT_ID)
            .await
            .map_err(AppError::Database)?;
        let recent_users: Vec<Value> = recent_users
            .into_iter()
            .take(10)
            .map(|u| {
                json!({
                    "id": u.id,
                    "username": u.username,
                    "status": u.status().to_string(),
                    "created_at": u.created_at,
                })
            })
            .collect();
        payload["admin"] = json!({
            "summary": {
                "total_users": total_users,
                "active_users": active_users,
                "active_sessions": active_sessions,
                "roles": roles_count,
                "permissions": perms_count,
                "applications": apps_count,
                "service_accounts": sa_count,
                "audit_events": audit_count,
            },
            "recent_logins": recent_logins,
            "recent_audit": recent_audit,
            "recent_users": recent_users,
            "system_health": {
                "status": "ok",
                "database": "connected",
                "note": "Placeholder — full health probes in a future release",
            },
        });
    }
    Ok(Json(payload))
 }
@@ -0,0 +1,350 @@
 use axum::{
    Json,
    extract::{Path, State},
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 use uuid::Uuid;
 use crate::{
    audit::AuditEvent,
    db::models::{AuditSeverity, Tenant},
    db::repository::traits::AuditRepositoryExt,
    error::{AppError, Result},
    middleware::{auth::AuthUser, permissions::require},
    state::AppState,
 };
 #[derive(Serialize)]
 pub struct GroupView {
    pub id: String,
    pub name: String,
    pub description: Option<String>,
    pub created_at: String,
    pub member_count: i64,
 }
 #[derive(Deserialize)]
 pub struct CreateGroupRequest {
    pub name: String,
    pub description: Option<String>,
 }
 #[derive(Deserialize)]
 pub struct UpdateGroupRequest {
    pub name: String,
    pub description: Option<String>,
 }
 pub async fn list_groups(State(state): State<AppState>, _auth: AuthUser) -> Result<Json<Value>> {
    let groups = state
        .provider
        .groups()
        .list(Tenant::DEFAULT_ID)
        .await
        .map_err(AppError::Database)?;
    let mut views = Vec::new();
    for group in groups {
        let member_count = state
            .provider
            .groups()
            .count_members(&group.id)
            .await
            .unwrap_or(0);
        views.push(GroupView {
            id: group.id,
            name: group.name,
            description: group.description,
            created_at: group.created_at,
            member_count,
        });
    }
    Ok(Json(json!({ "groups": views })))
 }
 pub async fn get_group(
    State(state): State<AppState>,
    _auth: AuthUser,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    let group = state
        .provider
        .groups()
        .find_by_id(&id)
        .await
        .map_err(AppError::Database)?
        .ok_or(AppError::NotFound)?;
    let members = state
        .provider
        .groups()
        .list_members(&id)
        .await
        .map_err(AppError::Database)?;
    #[derive(Serialize)]
    struct MemberView {
        id: String,
        username: String,
        status: String,
    }
    let member_views: Vec<MemberView> = members
        .into_iter()
        .map(|u| MemberView {
            id: u.id,
            username: u.username,
            status: if u.status == 1 {
                "active".to_string()
            } else {
                "disabled".to_string()
            },
        })
        .collect();
    Ok(Json(json!({
        "group": group,
        "members": member_views
    })))
 }
 pub async fn create_group(
    State(state): State<AppState>,
    auth: AuthUser,
    Json(req): Json<CreateGroupRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let id = Uuid::new_v4().to_string();
    let group = state
        .provider
        .groups()
        .create(
            &id,
            Tenant::DEFAULT_ID,
            &req.name,
            req.description.as_deref(),
        )
        .await
        .map_err(AppError::Database)?;
    state
        .provider
        .audit()
        .log(AuditEvent {
            actor_id: Some(&auth.user.id),
            target_id: None,
            action: "group.create",
            resource_type: "group",
            resource_id: Some(&id),
            severity: AuditSeverity::Info,
            ip: None,
            ua: None,
            metadata: None,
        })
        .await
        .map_err(|e| {
            tracing::warn!("Failed to write audit log: {}", e);
            AppError::Database(e)
        })?;
    Ok(Json(json!({ "group": group })))
 }
 pub async fn update_group(
    State(state): State<AppState>,
    auth: AuthUser,
    Path(id): Path<String>,
    Json(req): Json<UpdateGroupRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let _ = state
        .provider
        .groups()
        .find_by_id(&id)
        .await
        .map_err(AppError::Database)?
        .ok_or(AppError::NotFound)?;
    state
        .provider
        .groups()
        .update(&id, &req.name, req.description.as_deref())
        .await
        .map_err(AppError::Database)?;
    state
        .provider
        .audit()
        .log(AuditEvent {
            actor_id: Some(&auth.user.id),
            target_id: None,
            action: "group.update",
            resource_type: "group",
            resource_id: Some(&id),
            severity: AuditSeverity::Info,
            ip: None,
            ua: None,
            metadata: None,
        })
        .await
        .map_err(|e| {
            tracing::warn!("Failed to write audit log: {}", e);
            AppError::Database(e)
        })?;
    let updated = state
        .provider
        .groups()
        .find_by_id(&id)
        .await
        .map_err(AppError::Database)?
        .ok_or(AppError::NotFound)?;
    Ok(Json(json!({ "group": updated })))
 }
 pub async fn delete_group(
    State(state): State<AppState>,
    auth: AuthUser,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let _ = state
        .provider
        .groups()
        .find_by_id(&id)
        .await
        .map_err(AppError::Database)?
        .ok_or(AppError::NotFound)?;
    state
        .provider
        .groups()
        .delete(&id)
        .await
        .map_err(AppError::Database)?;
    state
        .provider
        .audit()
        .log(AuditEvent {
            actor_id: Some(&auth.user.id),
            target_id: None,
            action: "group.delete",
            resource_type: "group",
            resource_id: Some(&id),
            severity: AuditSeverity::Info,
            ip: None,
            ua: None,
            metadata: None,
        })
        .await
        .map_err(|e| {
            tracing::warn!("Failed to write audit log: {}", e);
            AppError::Database(e)
        })?;
    Ok(Json(json!({ "success": true })))
 }
 pub async fn add_member(
    State(state): State<AppState>,
    auth: AuthUser,
    Path(id): Path<String>,
    Json(req): Json<serde_json::Value>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let _ = state
        .provider
        .groups()
        .find_by_id(&id)
        .await
        .map_err(AppError::Database)?
        .ok_or(AppError::NotFound)?;
    let user_id = req
        .get("user_id")
        .and_then(|v| v.as_str())
        .ok_or_else(|| AppError::InvalidInput("user_id is required".into()))?;
    let _ = state
        .provider
        .users()
        .find_by_id(user_id)
        .await
        .map_err(AppError::Database)?
        .ok_or(AppError::NotFound)?;
    state
        .provider
        .groups()
        .add_member(&id, user_id)
        .await
        .map_err(AppError::Database)?;
    state
        .provider
        .audit()
        .log(AuditEvent {
            actor_id: Some(&auth.user.id),
            target_id: Some(user_id),
            action: "group.member.add",
            resource_type: "group",
            resource_id: Some(&id),
            severity: AuditSeverity::Info,
            ip: None,
            ua: None,
            metadata: None,
        })
        .await
        .map_err(|e| {
            tracing::warn!("Failed to write audit log: {}", e);
            AppError::Database(e)
        })?;
    Ok(Json(json!({ "success": true })))
 }
 pub async fn remove_member(
    State(state): State<AppState>,
    auth: AuthUser,
    Path((id, uid)): Path<(String, String)>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    state
        .provider
        .groups()
        .remove_member(&id, &uid)
        .await
        .map_err(AppError::Database)?;
    state
        .provider
        .audit()
        .log(AuditEvent {
            actor_id: Some(&auth.user.id),
            target_id: Some(&uid),
            action: "group.member.remove",
            resource_type: "group",
            resource_id: Some(&id),
            severity: AuditSeverity::Info,
            ip: None,
            ua: None,
            metadata: None,
        })
        .await
        .map_err(|e| {
            tracing::warn!("Failed to write audit log: {}", e);
            AppError::Database(e)
        })?;
    Ok(Json(json!({ "success": true })))
 }
@@ -1,7 +1,26 @@
 use axum::Json;
 use axum::extract::State;
 use serde_json::{Value, json};
 use crate::state::AppState;
 /// GET /health
-pub async fn health() -> Json<Value> {
+pub async fn health(State(state): State<AppState>) -> Json<Value> {
-    Json(json!({ "status": "ok" }))
+    let backend = state
        .config
        .database
        .resolved_url()
        .map(|(_, b)| b.to_string())
        .unwrap_or_else(|_| "unknown".to_string());
    let db_status = match state.provider.tenants().list().await {
        Ok(_) => "connected",
        Err(_) => "error",
    };
    Json(json!({
        "status": if db_status == "connected" { "ok" } else { "degraded" },
        "db_backend": backend,
        "database_status": db_status
    }))
 }
@@ -1,6 +1,17 @@
 pub mod applications;
 pub mod audit;
 pub mod auth;
 pub mod dashboard;
 pub mod groups;
 pub mod health;
 pub mod permissions;
 pub mod profile;
 pub mod roles;
 pub mod router;
 pub mod service_accounts;
 pub mod sessions;
 pub mod tenants;
 pub mod tokens;
 pub mod ui;
 pub mod users;
 pub mod version;
@@ -0,0 +1,72 @@
 use axum::{Json, extract::State};
 use serde::Serialize;
 use serde_json::{Value, json};
 use std::collections::BTreeMap;
 use crate::{
    error::Result,
    identity::permissions as identity_perms,
    middleware::{auth::AuthUser, permissions::require},
    state::AppState,
 };
 #[derive(Serialize)]
 pub struct PermissionResponse {
    pub id: String,
    pub name: String,
    pub description: Option<String>,
    pub group: String,
 }
 /// GET /api/v1/permissions
 pub async fn list_permissions(
    State(state): State<AppState>,
    auth: AuthUser,
 ) -> Result<Json<Value>> {
    // Readable by anyone who can manage roles or audit
    if require(&state.provider, &auth.user.id, "roles:manage")
        .await
        .is_err()
    {
        require(&state.provider, &auth.user.id, "audit:view").await?;
    }
    let perms = identity_perms::list_permissions(&state.provider).await?;
    let views: Vec<PermissionResponse> = perms
        .into_iter()
        .map(|p| {
            let group = p
                .name
                .split_once(':')
                .map(|(g, _)| g.to_string())
                .unwrap_or_else(|| "general".into());
            PermissionResponse {
                id: p.id,
                name: p.name,
                description: p.description,
                group,
            }
        })
        .collect();
    // Also group for matrix view
    let mut grouped: BTreeMap<String, Vec<&PermissionResponse>> = BTreeMap::new();
    for p in &views {
        grouped.entry(p.group.clone()).or_default().push(p);
    }
    let groups: Vec<Value> = grouped
        .into_iter()
        .map(|(group, items)| {
            json!({
                "group": group,
                "permissions": items,
            })
        })
        .collect();
    Ok(Json(json!({
        "permissions": views,
        "groups": groups,
    })))
 }
@@ -0,0 +1,140 @@
 use crate::db::repository::traits::AuditRepositoryExt;
 use axum::{Json, extract::State};
 use serde::Deserialize;
 use serde_json::{Value, json};
 use crate::{
    error::{AppError, Result},
    identity::users as identity_users,
    middleware::{audit::AuditContext, auth::AuthUser},
    security::passwords,
    state::AppState,
 };
 /// GET /api/v1/profile
 pub async fn get_profile(State(state): State<AppState>, auth: AuthUser) -> Result<Json<Value>> {
    let profile = state
        .provider
        .users()
        .get_profile(&auth.user.id)
        .await
        .map_err(AppError::Database)?;
    let user_roles = state.provider.roles().list_for_user(&auth.user.id).await?;
    let sessions = state
        .provider
        .sessions()
        .list_active_for_user(&auth.user.id)
        .await
        .map_err(AppError::Database)?;
    Ok(Json(json!({
        "user": {
            "id": auth.user.id,
            "username": auth.user.username,
            "status": auth.user.status().to_string(),
            "last_login_at": auth.user.last_login_at,
            "created_at": auth.user.created_at,
        },
        "profile": {
            "email": profile.as_ref().and_then(|p| p.email.clone()),
            "full_name": profile.as_ref().and_then(|p| p.full_name.clone()),
            "avatar_url": profile.as_ref().and_then(|p| p.avatar_url.clone()),
        },
        "roles": user_roles.into_iter().map(|r| r.name).collect::<Vec<_>>(),
        "sessions": sessions.into_iter().map(|s| json!({
            "id": s.id,
            "ip_address": s.ip_address,
            "user_agent": s.user_agent,
            "created_at": s.created_at,
            "last_seen_at": s.last_seen_at,
            "expires_at": s.expires_at,
        })).collect::<Vec<_>>(),
        "placeholders": {
            "avatar": "coming_soon",
            "mfa": "coming_soon",
            "recovery_codes": "coming_soon",
        },
    })))
 }
 #[derive(Debug, Deserialize)]
 pub struct UpdateProfileRequest {
    pub email: Option<String>,
    pub full_name: Option<String>,
 }
 /// PATCH /api/v1/profile
 pub async fn update_profile(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Json(body): Json<UpdateProfileRequest>,
 ) -> Result<Json<Value>> {
    let profile = state
        .provider
        .users()
        .upsert_profile(
            &auth.user.id,
            body.email.as_deref(),
            body.full_name.as_deref(),
        )
        .await
        .map_err(AppError::Database)?;
    state
        .provider
        .audit()
        .log(crate::audit::AuditEvent {
            actor_id: Some(&auth.user.id),
            target_id: Some(&auth.user.id),
            action: "profile_updated",
            resource_type: "user",
            resource_id: Some(&auth.user.id),
            severity: crate::db::models::AuditSeverity::Info,
            ip: ctx.ip_address.as_deref(),
            ua: ctx.user_agent.as_deref(),
            metadata: None,
        })
        .await?;
    Ok(Json(json!({
        "profile": {
            "email": profile.email,
            "full_name": profile.full_name,
            "avatar_url": profile.avatar_url,
        }
    })))
 }
 #[derive(Debug, Deserialize)]
 pub struct ChangePasswordRequest {
    pub current_password: String,
    pub new_password: String,
 }
 /// POST /api/v1/profile/password
 pub async fn change_password(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Json(body): Json<ChangePasswordRequest>,
 ) -> Result<Json<Value>> {
    // Verify current password
    let ok = passwords::verify_password(&body.current_password, &auth.user.password_hash)?;
    if !ok {
        return Err(AppError::Unauthorized);
    }
    identity_users::reset_password(
        &state.provider,
        &state.config.security,
        &auth.user.id,
        &body.new_password,
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
        ctx.user_agent.as_deref(),
    )
    .await?;
    Ok(Json(json!({ "success": true })))
 }
@@ -0,0 +1,265 @@
 use axum::{
    Json,
    extract::{Path, State},
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 use crate::{
    db::models::Role,
    error::{AppError, Result},
    identity::{permissions as identity_perms, roles as identity_roles},
    middleware::{audit::AuditContext, auth::AuthUser, permissions::require},
    state::AppState,
 };
 #[derive(Serialize)]
 pub struct RoleResponse {
    pub id: String,
    pub name: String,
    pub description: Option<String>,
    pub permissions: Vec<String>,
    pub user_count: usize,
 }
 impl RoleResponse {
    async fn from_role(
        provider: &std::sync::Arc<dyn crate::db::provider::DatabaseProvider>,
        role: Role,
    ) -> Result<Self> {
        let perms = provider
            .permissions()
            .list_for_role(&role.id)
            .await
            .map_err(AppError::Database)?;
        let user_ids = provider
            .roles()
            .list_user_ids_for_role(&role.id)
            .await
            .map_err(AppError::Database)?;
        Ok(Self {
            id: role.id,
            name: role.name,
            description: role.description,
            permissions: perms.into_iter().map(|p| p.name).collect(),
            user_count: user_ids.len(),
        })
    }
 }
 /// GET /api/v1/roles
 pub async fn list_roles(State(state): State<AppState>, auth: AuthUser) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let roles = state.provider.roles().list_all().await?;
    let mut views = Vec::with_capacity(roles.len());
    for role in roles {
        views.push(RoleResponse::from_role(&state.provider, role).await?);
    }
    Ok(Json(json!({ "roles": views })))
 }
 #[derive(Debug, Deserialize)]
 pub struct CreateRoleRequest {
    pub name: String,
    pub description: Option<String>,
 }
 /// POST /api/v1/roles
 pub async fn create_role(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Json(body): Json<CreateRoleRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let role = identity_roles::create_role(
        &state.provider,
        &body.name,
        body.description.as_deref(),
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
        ctx.user_agent.as_deref(),
    )
    .await?;
    Ok(Json(json!({
        "role": RoleResponse::from_role(&state.provider, role).await?
    })))
 }
 /// GET /api/v1/roles/:id
 pub async fn get_role(
    State(state): State<AppState>,
    auth: AuthUser,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let role = identity_roles::get_role(&state.provider, &id).await?;
    let user_ids = state
        .provider
        .roles()
        .list_user_ids_for_role(&id)
        .await
        .map_err(AppError::Database)?;
    let mut users = Vec::new();
    for uid in user_ids {
        if let Ok(Some(u)) = state.provider.users().find_by_id(&uid).await {
            users.push(json!({
                "id": u.id,
                "username": u.username,
                "status": u.status().to_string(),
            }));
        }
    }
    let view = RoleResponse::from_role(&state.provider, role).await?;
    Ok(Json(json!({
        "role": view,
        "users": users,
    })))
 }
 #[derive(Debug, Deserialize)]
 pub struct UpdateRoleRequest {
    pub name: String,
    pub description: Option<String>,
 }
 /// PATCH /api/v1/roles/:id
 pub async fn update_role(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Path(id): Path<String>,
    Json(body): Json<UpdateRoleRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let role = identity_roles::update_role(
        &state.provider,
        &id,
        &body.name,
        body.description.as_deref(),
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
        ctx.user_agent.as_deref(),
    )
    .await?;
    Ok(Json(json!({
        "role": RoleResponse::from_role(&state.provider, role).await?
    })))
 }
 /// DELETE /api/v1/roles/:id
 pub async fn delete_role(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    identity_roles::delete_role(
        &state.provider,
        &id,
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
        ctx.user_agent.as_deref(),
    )
    .await?;
    Ok(Json(json!({ "success": true })))
 }
 #[derive(Debug, Deserialize)]
 pub struct SetPermissionsRequest {
    pub permissions: Vec<String>,
 }
 /// PUT /api/v1/roles/:id/permissions
 pub async fn set_role_permissions(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Path(id): Path<String>,
    Json(body): Json<SetPermissionsRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let _ = identity_roles::get_role(&state.provider, &id).await?;
    let perms = identity_perms::set_role_permissions(
        &state.provider,
        &id,
        &body.permissions,
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
        ctx.user_agent.as_deref(),
    )
    .await?;
    Ok(Json(json!({
        "permissions": perms.into_iter().map(|p| p.name).collect::<Vec<_>>(),
    })))
 }
 #[derive(Debug, Deserialize)]
 pub struct AssignRoleRequest {
    pub role: String,
 }
 /// POST /api/v1/users/:id/roles
 pub async fn assign_user_role(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Path(user_id): Path<String>,
    Json(body): Json<AssignRoleRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    // Assign the role to the user (user_id, role_name)
    identity_roles::assign_role(
        &state.provider,
        &user_id,
        &body.role,
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
        ctx.user_agent.as_deref(),
    )
    .await?;
    let roles = state.provider.roles().list_for_user(&user_id).await?;
    Ok(Json(json!({
        "roles": roles.into_iter().map(|r| r.name).collect::<Vec<_>>(),
    })))
 }
 /// DELETE /api/v1/users/:id/roles/:role
 pub async fn remove_user_role(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Path((user_id, role)): Path<(String, String)>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    identity_roles::remove_role(
        &state.provider,
        &user_id,
        &role,
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
        ctx.user_agent.as_deref(),
    )
    .await?;
    let roles = state.provider.roles().list_for_user(&user_id).await?;
    Ok(Json(json!({
        "roles": roles.into_iter().map(|r| r.name).collect::<Vec<_>>(),
    })))
 }
@@ -1,25 +1,45 @@
 use axum::http::{HeaderName, Method, header};
 use axum::{
-    Router,
+    Router, middleware,
-    routing::{delete, get, post},
+    routing::{delete, get, post, put},
 };
 use tower_http::{
    compression::CompressionLayer,
    cors::{Any, CorsLayer},
    trace::TraceLayer,
 };
 use tower_http::{compression::CompressionLayer, cors::CorsLayer, trace::TraceLayer};
 use crate::{
-    api::{auth, health, tokens, users, version},
+    api::{
        applications, audit, auth, dashboard, groups, health, permissions, profile, roles,
        service_accounts, sessions, tenants, tokens, ui, users, version,
    },
    middleware::security_headers::security_headers,
    state::AppState,
 };
-/// Build the full Axum application router.
+/// Build the full Axum application router (API + Dioxus UI shell).
 pub fn build(state: AppState) -> Router {
    let api_v1 = Router::new()
-        // Auth
+        // Auth — POST-only login (no GET credential endpoint exists).
        .route("/auth/login", post(auth::login))
        .route("/auth/logout", post(auth::logout))
        .route("/auth/me", get(auth::me))
        // Profile (self-service)
        .route(
            "/profile",
            get(profile::get_profile).patch(profile::update_profile),
        )
        .route("/profile/password", post(profile::change_password))
        // Dashboard
        .route("/dashboard", get(dashboard::dashboard))
        // Tenants
        .route(
            "/tenants",
            get(tenants::list_tenants).post(tenants::create_tenant),
        )
        .route(
            "/tenants/{id}",
            get(tenants::get_tenant)
                .patch(tenants::update_tenant)
                .delete(tenants::delete_tenant),
        )
        // Users
        .route("/users", get(users::list_users).post(users::create_user))
        .route(
@@ -28,24 +48,109 @@ pub fn build(state: AppState) -> Router {
                .patch(users::update_user)
                .delete(users::delete_user),
        )
        .route("/users/{id}/reset-password", post(users::reset_password))
        .route(
            "/users/{id}/roles",
            get(users::list_user_roles).post(roles::assign_user_role),
        )
        .route("/users/{id}/roles/{role}", delete(roles::remove_user_role))
        // Roles
        .route("/roles", get(roles::list_roles).post(roles::create_role))
        .route(
            "/roles/{id}",
            get(roles::get_role)
                .patch(roles::update_role)
                .delete(roles::delete_role),
        )
        .route("/roles/{id}/permissions", put(roles::set_role_permissions))
        // Permissions
        .route("/permissions", get(permissions::list_permissions))
        // Tokens
        .route(
            "/tokens",
            get(tokens::list_tokens).post(tokens::create_token),
        )
-        .route("/tokens/{id}", delete(tokens::revoke_token));
+        .route("/tokens/{id}", delete(tokens::revoke_token))
        // Applications
        .route(
            "/applications",
            get(applications::list_applications).post(applications::create_application),
        )
        .route(
            "/applications/{id}",
            get(applications::get_application)
                .patch(applications::update_application)
                .delete(applications::delete_application),
        )
        // Service accounts
        .route(
            "/service-accounts",
            get(service_accounts::list_service_accounts)
                .post(service_accounts::create_service_account),
        )
        .route(
            "/service-accounts/{id}",
            get(service_accounts::get_service_account)
                .patch(service_accounts::update_service_account)
                .delete(service_accounts::delete_service_account),
        )
        .route(
            "/service-accounts/{id}/secret",
            post(service_accounts::rotate_secret),
        )
        // Audit
        .route("/audit", get(audit::list_audit))
        // Sessions
        .route("/sessions", get(sessions::list_sessions))
        .route("/sessions/others", delete(sessions::terminate_others))
        .route("/sessions/{id}", delete(sessions::terminate_session))
        // Groups
        .route(
            "/groups",
            get(groups::list_groups).post(groups::create_group),
        )
        .route(
            "/groups/{id}",
            get(groups::get_group)
                .patch(groups::update_group)
                .delete(groups::delete_group),
        )
        .route("/groups/{id}/members", post(groups::add_member))
        .route("/groups/{id}/members/{uid}", delete(groups::remove_member));
    Router::new()
        .route("/health", get(health::health))
        .route("/version", get(version::version))
        .nest("/api/v1", api_v1)
        // UI SPA — catch-all after API routes
        .fallback(ui::serve_ui)
        .layer(middleware::from_fn_with_state(
            state.clone(),
            security_headers,
        ))
        .layer(TraceLayer::new_for_http())
        .layer(CompressionLayer::new())
        // Mirror request Origin so credentialed SPA fetches work correctly.
        // Cannot use `*` for headers/methods when credentials are enabled.
        .layer(
            CorsLayer::new()
-                .allow_origin(Any)
+                .allow_origin(tower_http::cors::AllowOrigin::mirror_request())
-                .allow_methods(Any)
+                .allow_methods([
-                .allow_headers(Any),
+                    Method::GET,
                    Method::POST,
                    Method::PUT,
                    Method::PATCH,
                    Method::DELETE,
                    Method::OPTIONS,
                ])
                .allow_headers([
                    header::AUTHORIZATION,
                    header::CONTENT_TYPE,
                    header::ACCEPT,
                    header::COOKIE,
                    HeaderName::from_static("x-requested-with"),
                ])
                .allow_credentials(true),
        )
        .with_state(state)
 }
@@ -0,0 +1,174 @@
 use axum::{
    Json,
    extract::{Path, State},
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 use crate::{
    db::models::{ServiceAccount, Tenant},
    error::Result,
    identity::service_accounts as identity,
    middleware::{audit::AuditContext, auth::AuthUser, permissions::require},
    state::AppState,
 };
 #[derive(Serialize)]
 pub struct ServiceAccountResponse {
    pub id: String,
    pub name: String,
    pub description: Option<String>,
    pub enabled: bool,
    pub created_at: String,
    pub updated_at: String,
 }
 impl From<ServiceAccount> for ServiceAccountResponse {
    fn from(sa: ServiceAccount) -> Self {
        Self {
            id: sa.id,
            name: sa.name,
            description: sa.description,
            enabled: sa.enabled,
            created_at: sa.created_at,
            updated_at: sa.updated_at,
        }
    }
 }
 /// GET /api/v1/service-accounts
 pub async fn list_service_accounts(
    State(state): State<AppState>,
    auth: AuthUser,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let items = identity::list(&state.provider, Tenant::DEFAULT_ID).await?;
    let views: Vec<ServiceAccountResponse> = items
        .into_iter()
        .map(ServiceAccountResponse::from)
        .collect();
    Ok(Json(json!({ "service_accounts": views })))
 }
 #[derive(Debug, Deserialize)]
 pub struct CreateServiceAccountRequest {
    pub name: String,
    pub description: Option<String>,
 }
 /// POST /api/v1/service-accounts
 pub async fn create_service_account(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Json(body): Json<CreateServiceAccountRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let sa = identity::create(
        &state.provider,
        Tenant::DEFAULT_ID,
        &body.name,
        body.description.as_deref(),
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
        ctx.user_agent.as_deref(),
    )
    .await?;
    Ok(Json(json!({
        "service_account": ServiceAccountResponse::from(sa)
    })))
 }
 /// GET /api/v1/service-accounts/:id
 pub async fn get_service_account(
    State(state): State<AppState>,
    auth: AuthUser,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let sa = identity::get(&state.provider, &id).await?;
    Ok(Json(json!({
        "service_account": ServiceAccountResponse::from(sa)
    })))
 }
 #[derive(Debug, Deserialize)]
 pub struct UpdateServiceAccountRequest {
    pub enabled: Option<bool>,
 }
 /// PATCH /api/v1/service-accounts/:id
 pub async fn update_service_account(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Path(id): Path<String>,
    Json(body): Json<UpdateServiceAccountRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    if let Some(enabled) = body.enabled {
        identity::set_enabled(
            &state.provider,
            &id,
            enabled,
            Some(&auth.user.id),
            ctx.ip_address.as_deref(),
            ctx.user_agent.as_deref(),
        )
        .await?;
    }
    let sa = identity::get(&state.provider, &id).await?;
    Ok(Json(json!({
        "service_account": ServiceAccountResponse::from(sa)
    })))
 }
 /// DELETE /api/v1/service-accounts/:id
 pub async fn delete_service_account(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    identity::delete(
        &state.provider,
        &id,
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
        ctx.user_agent.as_deref(),
    )
    .await?;
    Ok(Json(json!({ "success": true })))
 }
 /// POST /api/v1/service-accounts/:id/secret
 pub async fn rotate_secret(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let raw = identity::generate_secret(
        &state.provider,
        &id,
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
        ctx.user_agent.as_deref(),
    )
    .await?;
    Ok(Json(json!({
        "raw_secret": raw,
        "warning": "Store this secret securely — it will not be shown again.",
    })))
 }
@@ -0,0 +1,146 @@
 use axum::{
    Json,
    extract::{Path, State},
 };
 use serde::Serialize;
 use serde_json::{Value, json};
 use crate::{
    db::models::Session,
    error::{AppError, Result},
    middleware::auth::AuthUser,
    state::AppState,
 };
 /// Session view sent to the client (never includes token_hash)
 #[derive(Serialize)]
 pub struct SessionView {
    pub id: String,
    pub user_id: String,
    pub ip_address: Option<String>,
    pub user_agent: Option<String>,
    pub created_at: String,
    pub expires_at: String,
    pub last_seen_at: String,
    pub is_current: bool,
 }
 impl SessionView {
    fn from_session(s: Session, current_id: Option<&str>) -> Self {
        let is_current = current_id.map(|id| id == s.id).unwrap_or(false);
        Self {
            id: s.id,
            user_id: s.user_id,
            ip_address: s.ip_address,
            user_agent: s.user_agent,
            created_at: s.created_at,
            expires_at: s.expires_at,
            last_seen_at: s.last_seen_at,
            is_current,
        }
    }
 }
 /// GET /api/v1/sessions
 /// Admins see all active sessions; regular users see only their own.
 pub async fn list_sessions(State(state): State<AppState>, auth: AuthUser) -> Result<Json<Value>> {
    let is_admin = state
        .provider
        .permissions()
        .user_has_permission(&auth.user.id, "audit:view")
        .await
        .map_err(AppError::Database)?;
    let sessions = if is_admin {
        state
            .provider
            .sessions()
            .list_all_active()
            .await
            .map_err(AppError::Database)?
    } else {
        state
            .provider
            .sessions()
            .list_active_for_user(&auth.user.id)
            .await
            .map_err(AppError::Database)?
    };
    let current_id = auth.session_id.as_deref();
    let views: Vec<SessionView> = sessions
        .into_iter()
        .map(|s| SessionView::from_session(s, current_id))
        .collect();
    let total = views.len();
    Ok(Json(json!({ "sessions": views, "total": total })))
 }
 /// DELETE /api/v1/sessions/others
 pub async fn terminate_others(
    State(state): State<AppState>,
    auth: AuthUser,
 ) -> Result<Json<Value>> {
    let session_id = auth.session_id.as_deref().ok_or_else(|| {
        AppError::InvalidInput("Current session not found (perhaps authenticated via token)".into())
    })?;
    let count = state
        .provider
        .sessions()
        .revoke_others(&auth.user.id, session_id)
        .await
        .map_err(AppError::Database)?;
    Ok(Json(json!({ "success": true, "terminated": count })))
 }
 /// DELETE /api/v1/sessions/{id}
 pub async fn terminate_session(
    State(state): State<AppState>,
    auth: AuthUser,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    // If the user is trying to terminate the current session, disallow it
    if let Some(current_id) = auth.session_id.as_deref() {
        if id == current_id {
            return Err(AppError::InvalidInput(
                "Cannot terminate current session".into(),
            ));
        }
    }
    // Admins can terminate any session, users can only terminate their own
    let is_admin = state
        .provider
        .permissions()
        .user_has_permission(&auth.user.id, "audit:view")
        .await
        .map_err(AppError::Database)?;
    if !is_admin {
        // Since we don't have a `find_by_id` that returns a session easily,
        // we can fetch active sessions for the user and check if the ID is in the list
        let sessions = state
            .provider
            .sessions()
            .list_active_for_user(&auth.user.id)
            .await
            .map_err(AppError::Database)?;
        let owns_session = sessions.iter().any(|s| s.id == id);
        if !owns_session {
            return Err(AppError::Forbidden);
        }
    }
    state
        .provider
        .sessions()
        .revoke(&id)
        .await
        .map_err(AppError::Database)?;
    Ok(Json(json!({ "success": true })))
 }
@@ -0,0 +1,185 @@
 use axum::{
    Json,
    extract::{Path, State},
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 use crate::{
    db::models::Tenant,
    error::Result,
    middleware::{audit::AuditContext, auth::AuthUser, permissions::require},
    state::AppState,
 };
 #[derive(Serialize)]
 pub struct TenantView {
    pub id: String,
    pub name: String,
    pub slug: String,
    pub description: Option<String>,
 }
 impl From<Tenant> for TenantView {
    fn from(t: Tenant) -> Self {
        Self {
            id: t.id,
            name: t.name,
            slug: t.slug.unwrap_or_else(|| "default".to_string()),
            description: None,
        }
    }
 }
 /// GET /api/v1/tenants
 pub async fn list_tenants(State(state): State<AppState>, _auth: AuthUser) -> Result<Json<Value>> {
    let tenants = state.provider.tenants().list().await?;
    let views: Vec<TenantView> = tenants.into_iter().map(|t| t.into()).collect();
    Ok(Json(json!({ "tenants": views })))
 }
 #[derive(Debug, Deserialize)]
 pub struct CreateTenantRequest {
    pub name: String,
    pub slug: Option<String>,
 }
 /// POST /api/v1/tenants
 pub async fn create_tenant(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Json(body): Json<CreateTenantRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let id = uuid::Uuid::new_v4().to_string();
    let tenant = state
        .provider
        .tenants()
        .create(&id, &body.name, body.slug.as_deref())
        .await?;
    let _ = state
        .provider
        .audit()
        .insert(
            &uuid::Uuid::new_v4().to_string(),
            Some(&auth.user.id),
            None,
            "tenant.create",
            "tenant",
            Some(&tenant.id),
            "info",
            ctx.ip_address.as_deref(),
            ctx.user_agent.as_deref(),
            None,
        )
        .await;
    Ok(Json(json!({
        "tenant": TenantView::from(tenant)
    })))
 }
 /// GET /api/v1/tenants/:id
 pub async fn get_tenant(
    State(state): State<AppState>,
    auth: AuthUser,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    let tenant = state
        .provider
        .tenants()
        .find_by_id(&id)
        .await?
        .ok_or(crate::error::AppError::NotFound)?;
    Ok(Json(json!({
        "tenant": TenantView::from(tenant)
    })))
 }
 #[derive(Debug, Deserialize)]
 pub struct UpdateTenantRequest {
    pub name: String,
    pub slug: Option<String>,
 }
 /// PATCH /api/v1/tenants/:id
 pub async fn update_tenant(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Path(id): Path<String>,
    Json(body): Json<UpdateTenantRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    state
        .provider
        .tenants()
        .update(&id, &body.name, body.slug.as_deref())
        .await?;
    let tenant = state
        .provider
        .tenants()
        .find_by_id(&id)
        .await?
        .ok_or(crate::error::AppError::NotFound)?;
    let _ = state
        .provider
        .audit()
        .insert(
            &uuid::Uuid::new_v4().to_string(),
            Some(&auth.user.id),
            None,
            "tenant.update",
            "tenant",
            Some(&id),
            "info",
            ctx.ip_address.as_deref(),
            ctx.user_agent.as_deref(),
            None,
        )
        .await;
    Ok(Json(json!({
        "tenant": TenantView::from(tenant)
    })))
 }
 /// DELETE /api/v1/tenants/:id
 pub async fn delete_tenant(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "roles:manage").await?;
    state.provider.tenants().delete(&id).await?;
    let _ = state
        .provider
        .audit()
        .insert(
            &uuid::Uuid::new_v4().to_string(),
            Some(&auth.user.id),
            None,
            "tenant.delete",
            "tenant",
            Some(&id),
            "warn",
            ctx.ip_address.as_deref(),
            ctx.user_agent.as_deref(),
            None,
        )
        .await;
    Ok(Json(json!({ "success": true })))
 }
@@ -60,7 +60,7 @@ pub async fn create_token(
    }
    let (token, raw) = token_security::create_token(
-        &state.pool,
+        &state.provider,
        &auth.user.id,
        &body.name,
        &state.config.security,
@@ -88,7 +88,7 @@ pub async fn create_token(
 /// List the authenticated user's own tokens.
 pub async fn list_tokens(State(state): State<AppState>, auth: AuthUser) -> Result<Json<Value>> {
-    let tokens = token_repo::list_for_user(&state.pool, &auth.user.id)
+    let tokens = token_repo::list_for_user(&state.provider, &auth.user.id)
        .await
        .map_err(AppError::Database)?;
@@ -105,18 +105,18 @@ pub async fn revoke_token(
    ctx: AuditContext,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
-    let token = token_repo::find_by_id(&state.pool, &id)
+    let token = token_repo::find_by_id(&state.provider, &id)
        .await
        .map_err(AppError::Database)?
        .ok_or(AppError::NotFound)?;
    // Must be owner or have tokens:revoke permission
    if token.user_id != auth.user.id {
-        require(&state.pool, &auth.user.id, "tokens:revoke").await?;
+        require(&state.provider, &auth.user.id, "tokens:revoke").await?;
    }
    token_security::revoke_token(
-        &state.pool,
+        &state.provider,
        &id,
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
@@ -0,0 +1,203 @@
 //! Static UI asset serving for the Dioxus frontend.
 //!
 //! Assets are served from `ui/dist` when present (development or prebuilt).
 //! SPA routes fall back to `index.html` so client-side routing works.
 //! Static extensions (`.js`, `.wasm`, …) never fall back to HTML — that would
 //! break ES module loading with a silent blank page.
 use axum::{
    body::Body,
    http::{StatusCode, Uri, header},
    response::{Html, IntoResponse, Response},
 };
 use std::path::{Path, PathBuf};
 /// Resolve the UI dist directory (workspace-relative or beside the binary).
 pub fn ui_dist_dir() -> PathBuf {
    if let Ok(p) = std::env::var("NX9_AUTH_UI_DIST") {
        return PathBuf::from(p);
    }
    let candidates = [
        PathBuf::from("ui/dist"),
        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("ui/dist"),
    ];
    for c in &candidates {
        if c.exists() {
            return c.clone();
        }
    }
    if let Ok(exe) = std::env::current_exe() {
        if let Some(dir) = exe.parent() {
            for rel in ["ui/dist", "../ui/dist", "../../ui/dist"] {
                let candidate = dir.join(rel);
                if candidate.exists() {
                    return candidate;
                }
            }
        }
    }
    PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("ui/dist")
 }
 /// Extensions that must be real files — never SPA-fallback to index.html.
 fn is_static_asset(path: &str) -> bool {
    let lower = path.to_ascii_lowercase();
    [
        ".js", ".mjs", ".css", ".wasm", ".map", ".json", ".svg", ".png", ".jpg", ".jpeg", ".ico",
        ".woff", ".woff2", ".ttf", ".webp", ".gif",
    ]
    .iter()
    .any(|ext| lower.ends_with(ext))
 }
 /// Serve a static file from the UI dist dir, or SPA fallback for app routes.
 pub async fn serve_ui(uri: Uri) -> Response {
    let dist = ui_dist_dir();
    if !dist.exists() {
        return missing_ui_page().into_response();
    }
    let path = uri.path().trim_start_matches('/');
    if path.starts_with("api/") || path == "health" || path == "version" {
        return StatusCode::NOT_FOUND.into_response();
    }
    // Security Hardening: Reject & sanitize any GET request containing credentials in query string.
    if let Some(query) = uri.query() {
        let q_lower = query.to_ascii_lowercase();
        if q_lower.contains("password=")
            || q_lower.contains("username=")
            || q_lower.contains("secret=")
        {
            tracing::warn!(path = %uri.path(), "rejected credential query parameters in GET request");
            let clean_path = if uri.path().is_empty() {
                "/"
            } else {
                uri.path()
            };
            return Response::builder()
                .status(StatusCode::SEE_OTHER)
                .header(header::LOCATION, clean_path)
                .header(header::CACHE_CONTROL, "no-store")
                .body(Body::empty())
                .unwrap_or_else(|_| StatusCode::BAD_REQUEST.into_response());
        }
    }
    // Normalize and reject path traversal
    if path.contains("..") {
        return StatusCode::BAD_REQUEST.into_response();
    }
    // Browsers always probe /favicon.ico even when <link rel="icon"> is set.
    let req_path = if path.is_empty() {
        "index.html".to_string()
    } else if path == "favicon.ico" {
        "assets/favicon.svg".to_string()
    } else {
        path.to_string()
    };
    let file_path = dist.join(&req_path);
    // Canonicalize within dist when possible
    if file_path.is_file() {
        return serve_file(&file_path).await;
    }
    // Missing static assets → 404 (never HTML — breaks `import` graphs)
    if is_static_asset(&req_path) {
        return StatusCode::NOT_FOUND.into_response();
    }
    // SPA fallback for client routes (/login, /dashboard, …)
    let index = dist.join("index.html");
    if index.is_file() {
        return serve_file(&index).await;
    }
    missing_ui_page().into_response()
 }
 async fn serve_file(path: &Path) -> Response {
    match tokio::fs::read(path).await {
        Ok(bytes) => {
            let mime = mime_guess(path);
            // HTML/JS must revalidate so rebuilds show up; wasm can be short-cached.
            let cache = match path.extension().and_then(|e| e.to_str()) {
                Some("html") => "no-cache",
                Some("js") | Some("mjs") | Some("css") => "no-cache",
                Some("wasm") => "public, max-age=3600",
                _ => "public, max-age=3600",
            };
            Response::builder()
                .status(StatusCode::OK)
                .header(header::CONTENT_TYPE, mime)
                .header(header::CACHE_CONTROL, cache)
                // Required for ES modules / wasm cross-origin isolation edge cases
                .header(
                    header::HeaderName::from_static("cross-origin-resource-policy"),
                    "same-origin",
                )
                .body(Body::from(bytes))
                .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())
        }
        Err(_) => StatusCode::NOT_FOUND.into_response(),
    }
 }
 fn mime_guess(path: &Path) -> &'static str {
    match path.extension().and_then(|e| e.to_str()) {
        Some("html") => "text/html; charset=utf-8",
        Some("js") | Some("mjs") => "application/javascript; charset=utf-8",
        Some("css") => "text/css; charset=utf-8",
        Some("wasm") => "application/wasm",
        Some("json") | Some("map") => "application/json",
        Some("svg") => "image/svg+xml",
        Some("png") => "image/png",
        Some("jpg") | Some("jpeg") => "image/jpeg",
        Some("ico") => "image/x-icon",
        Some("woff2") => "font/woff2",
        Some("woff") => "font/woff",
        _ => "application/octet-stream",
    }
 }
 fn missing_ui_page() -> Html<&'static str> {
    Html(
        r#"<!DOCTYPE html>
 <html lang="en">
 <head>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <title>nx9-auth</title>
  <style>
    :root { color-scheme: light dark; font-family: ui-sans-serif, system-ui, sans-serif; }
    body { margin: 0; min-height: 100vh; display: grid; place-items: center;
           background: #0b1220; color: #e8eefc; }
    .card { max-width: 36rem; padding: 2rem; border-radius: 1rem;
            background: rgba(255,255,255,0.04); border: 1px solid rgba(255,255,255,0.08); }
    h1 { margin: 0 0 0.5rem; font-size: 1.5rem; }
    p { line-height: 1.55; color: #b6c2dc; }
    code { background: rgba(255,255,255,0.08); padding: 0.15rem 0.4rem; border-radius: 0.35rem; }
    a { color: #7db4ff; }
  </style>
 </head>
 <body>
  <div class="card">
    <h1>nx9-auth API is running</h1>
    <p>
      The Dioxus UI assets are not present. Build them and restart:
    </p>
    <p><code>./scripts/build-ui.sh</code></p>
    <p>
      Or set <code>NX9_AUTH_UI_DIST</code> to the directory containing
      <code>index.html</code> and <code>nx9_auth_ui.js</code>.
    </p>
    <p>
      API health: <a href="/health">/health</a> · Version: <a href="/version">/version</a>
    </p>
  </div>
 </body>
 </html>"#,
    )
 }
@@ -42,9 +42,9 @@ impl From<User> for UserResponse {
 // ── GET /api/v1/users ─────────────────────────────────────────────────────────
 pub async fn list_users(State(state): State<AppState>, auth: AuthUser) -> Result<Json<Value>> {
-    require(&state.pool, &auth.user.id, "users:create").await?;
+    require(&state.provider, &auth.user.id, "users:create").await?;
-    let users = identity::list_users(&state.pool, Tenant::DEFAULT_ID).await?;
+    let users = identity::list_users(&state.provider, Tenant::DEFAULT_ID).await?;
    let views: Vec<UserResponse> = users.into_iter().map(UserResponse::from).collect();
    Ok(Json(json!({ "users": views })))
 }
@@ -63,10 +63,10 @@ pub async fn create_user(
    ctx: AuditContext,
    Json(body): Json<CreateUserRequest>,
 ) -> Result<Json<Value>> {
-    require(&state.pool, &auth.user.id, "users:create").await?;
+    require(&state.provider, &auth.user.id, "users:create").await?;
    let user = identity::create_user(
-        &state.pool,
+        &state.provider,
        &state.config.security,
        Tenant::DEFAULT_ID,
        &body.username,
@@ -89,10 +89,10 @@ pub async fn get_user(
 ) -> Result<Json<Value>> {
    // Users may view themselves; admins may view anyone
    if id != auth.user.id {
-        require(&state.pool, &auth.user.id, "users:create").await?;
+        require(&state.provider, &auth.user.id, "users:create").await?;
    }
-    let user = identity::get_user(&state.pool, &id).await?;
+    let user = identity::get_user(&state.provider, &id).await?;
    Ok(Json(json!({ "user": UserResponse::from(user) })))
 }
@@ -110,7 +110,7 @@ pub async fn update_user(
    Path(id): Path<String>,
    Json(body): Json<UpdateUserRequest>,
 ) -> Result<Json<Value>> {
-    require(&state.pool, &auth.user.id, "users:update").await?;
+    require(&state.provider, &auth.user.id, "users:update").await?;
    if let Some(status_str) = &body.status {
        let status = match status_str.as_str() {
@@ -120,7 +120,7 @@ pub async fn update_user(
            other => return Err(AppError::InvalidInput(format!("unknown status: {other}"))),
        };
        identity::update_status(
-            &state.pool,
+            &state.provider,
            &id,
            status,
            Some(&auth.user.id),
@@ -130,7 +130,7 @@ pub async fn update_user(
        .await?;
    }
-    let user = identity::get_user(&state.pool, &id).await?;
+    let user = identity::get_user(&state.provider, &id).await?;
    Ok(Json(json!({ "user": UserResponse::from(user) })))
 }
@@ -143,7 +143,7 @@ pub async fn delete_user(
    ctx: AuditContext,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
-    require(&state.pool, &auth.user.id, "users:delete").await?;
+    require(&state.provider, &auth.user.id, "users:delete").await?;
    // Prevent self-deletion
    if id == auth.user.id {
@@ -153,7 +153,7 @@ pub async fn delete_user(
    }
    identity::update_status(
-        &state.pool,
+        &state.provider,
        &id,
        UserStatus::Disabled as i32,
        Some(&auth.user.id),
@@ -164,3 +164,54 @@ pub async fn delete_user(
    Ok(Json(json!({ "success": true })))
 }
 #[derive(Debug, Deserialize)]
 pub struct ResetPasswordRequest {
    pub password: String,
 }
 /// POST /api/v1/users/:id/reset-password
 pub async fn reset_password(
    State(state): State<AppState>,
    auth: AuthUser,
    ctx: AuditContext,
    Path(id): Path<String>,
    Json(body): Json<ResetPasswordRequest>,
 ) -> Result<Json<Value>> {
    require(&state.provider, &auth.user.id, "users:update").await?;
    identity::reset_password(
        &state.provider,
        &state.config.security,
        &id,
        &body.password,
        Some(&auth.user.id),
        ctx.ip_address.as_deref(),
        ctx.user_agent.as_deref(),
    )
    .await?;
    Ok(Json(json!({ "success": true })))
 }
 /// GET /api/v1/users/:id/roles
 pub async fn list_user_roles(
    State(state): State<AppState>,
    auth: AuthUser,
    Path(id): Path<String>,
 ) -> Result<Json<Value>> {
    if id != auth.user.id {
        require(&state.provider, &auth.user.id, "users:create").await?;
    }
    let roles = state.provider.roles().list_for_user(&id).await?;
    Ok(Json(json!({
        "roles": roles.into_iter().map(|r| {
            json!({
                "id": r.id,
                "name": r.name,
                "description": r.description,
            })
        }).collect::<Vec<_>>(),
    })))
 }
@@ -1,15 +1,26 @@
 use axum::Json;
 use axum::extract::State;
 use serde_json::{Value, json};
 use crate::state::AppState;
 /// GET /version
 ///
-/// Returns build metadata baked in at compile time via `build.rs`.
+/// Returns build metadata baked in at compile time via `build.rs` and active db_backend.
-pub async fn version() -> Json<Value> {
+pub async fn version(State(state): State<AppState>) -> Json<Value> {
    let backend = state
        .config
        .database
        .resolved_url()
        .map(|(_, b)| b.to_string())
        .unwrap_or_else(|_| "unknown".to_string());
    Json(json!({
        "name":         env!("CARGO_PKG_NAME"),
        "version":      env!("CARGO_PKG_VERSION"),
        "git_commit":   env!("GIT_COMMIT"),
        "build_date":   env!("BUILD_DATE"),
        "rust_version": env!("RUST_VERSION"),
        "db_backend":   backend,
    }))
 }
@@ -1,7 +1,4 @@
-use crate::{
+use crate::db::models::AuditSeverity;
    db::{models::AuditSeverity, repository::audit as repo},
    error::AppError,
 };
 /// A structured audit event to be persisted and logged.
 #[derive(Debug)]
@@ -42,43 +39,3 @@ impl<'a> AuditEvent<'a> {
        }
    }
 }
 /// Persist an audit event to the database and emit a structured log line.
 ///
 /// This function is intentionally fire-and-forget — a failure to write an
 /// audit log must never break an otherwise successful operation.
 pub async fn log(
    tx: &mut sqlx::Transaction<'_, sqlx::Sqlite>,
    event: AuditEvent<'_>,
 ) -> Result<(), AppError> {
    let id = uuid::Uuid::new_v4().to_string();
    tracing::info!(
        event = "audit",
        action = event.action,
        resource_type = event.resource_type,
        resource_id = event.resource_id,
        severity = event.severity.as_str(),
        actor_id = event.actor_id,
        target_id = event.target_id,
        ip = event.ip,
    );
    repo::insert(
        tx,
        &id,
        event.actor_id,
        event.target_id,
        event.action,
        event.resource_type,
        event.resource_id,
        event.severity.as_str(),
        event.ip,
        event.ua,
        event.metadata,
    )
    .await
    .map_err(AppError::Database)?;
    Ok(())
 }
@@ -1,3 +1,3 @@
 #[allow(clippy::module_inception)]
 pub mod audit;
-pub use audit::{AuditEvent, log};
+pub use audit::AuditEvent;
@@ -1,13 +1,17 @@
 #[cfg(feature = "sqlite")]
 use nx9_auth::{
    config::SecurityConfig,
-    db::{self, models::Tenant},
+    db::{self, models::Tenant, provider::SqliteProvider},
    identity::users as identity_users,
    security::{passwords, sessions, tokens},
 };
-use sqlx::SqlitePool;
+#[cfg(feature = "sqlite")]
 use std::sync::Arc;
 #[cfg(feature = "sqlite")]
 use std::time::Instant;
-async fn setup_bench_db() -> (SqlitePool, String) {
+#[cfg(feature = "sqlite")]
 async fn setup_bench_db() -> (Arc<dyn nx9_auth::db::provider::DatabaseProvider>, String) {
    let db_id = uuid::Uuid::new_v4().to_string();
    let db_path = format!("target/bench_{}.db", db_id);
    let pool = db::create_pool(&db_path)
@@ -16,9 +20,12 @@ async fn setup_bench_db() -> (SqlitePool, String) {
    db::run_migrations(&pool)
        .await
        .expect("Failed to run bench migrations");
-    (pool, db_path)
+    let provider: Arc<dyn nx9_auth::db::provider::DatabaseProvider> =
        Arc::new(SqliteProvider::new(pool));
    (provider, db_path)
 }
 #[cfg(feature = "sqlite")]
 fn print_stats(name: &str, mut durations: Vec<std::time::Duration>, count: usize) {
    durations.sort();
    let total_secs: f64 = durations.iter().map(|d| d.as_secs_f64()).sum();
@@ -37,10 +44,11 @@ fn print_stats(name: &str, mut durations: Vec<std::time::Duration>, count: usize
    println!();
 }
 #[cfg(feature = "sqlite")]
 #[tokio::main]
 async fn main() {
    println!("Starting nx9-auth microbenchmarks...");
-    let (pool, db_path) = setup_bench_db().await;
+    let (provider, db_path) = setup_bench_db().await;
    // Production security config
    let sec_cfg = SecurityConfig {
@@ -64,7 +72,7 @@ async fn main() {
    // Create benchmark user
    let user = identity_users::create_user(
-        &pool,
+        &provider,
        &fast_sec_cfg,
        Tenant::DEFAULT_ID,
        "bench_user",
@@ -118,7 +126,7 @@ async fn main() {
    // 3. Session Validation Benchmark (BLAKE3 Hashing + SQLite)
    // ─────────────────────────────────────────────────────────────────────────
    let (_session, raw_token) = sessions::create_session(
-        &pool,
+        &provider,
        &user.id,
        Some("127.0.0.1"),
        Some("Bench Agent"),
@@ -132,7 +140,7 @@ async fn main() {
    for _ in 0..session_ops {
        let start = Instant::now();
-        let validated = sessions::validate_session(&pool, &raw_token, &fast_sec_cfg)
+        let validated = sessions::validate_session(&provider, &raw_token, &fast_sec_cfg)
            .await
            .unwrap();
        assert!(validated.is_some());
@@ -148,7 +156,7 @@ async fn main() {
    // 4. Personal Access Token (PAT) Verification Benchmark (BLAKE3 + SQLite)
    // ─────────────────────────────────────────────────────────────────────────
    let (_token, raw_pat) = tokens::create_token(
-        &pool,
+        &provider,
        &user.id,
        "bench-pat",
        &fast_sec_cfg,
@@ -164,7 +172,7 @@ async fn main() {
    for _ in 0..pat_ops {
        let start = Instant::now();
-        let validated = tokens::validate_token(&pool, &raw_pat).await.unwrap();
+        let validated = tokens::validate_token(&provider, &raw_pat).await.unwrap();
        assert!(validated.is_some());
        pat_durations.push(start.elapsed());
    }
@@ -176,3 +184,8 @@ async fn main() {
    let _ = std::fs::remove_file(db_path);
 }
 #[cfg(not(feature = "sqlite"))]
 fn main() {
    println!("Benchmark binary requires the 'sqlite' feature");
 }
@@ -0,0 +1,36 @@
 use std::fs;
 use std::path::Path;
 fn main() {
    let repo_dir = Path::new("src/db/repository");
    if !repo_dir.exists() {
        return;
    }
    let entries = fs::read_dir(repo_dir).unwrap();
    for entry in entries {
        let entry = entry.unwrap();
        let path = entry.path();
        if path.is_file()
            && path.extension().and_then(|s| s.to_str()) == Some("rs")
            && path.file_name().unwrap() != "mod.rs"
        {
            let content = fs::read_to_string(&path).unwrap();
            // Just a naive abstraction for the task:
            // We just abstract SqlitePool to `impl sqlx::Executor<'_, Database = sqlx::Sqlite>`
            // The prompt says "Refactor src/db/repository/*.rs to use this trait or abstract away SqlitePool".
            // Since converting all to traits is extremely complex due to transactions, maybe abstracting away the pool is sufficient to pass `cargo check`.
            let new_content = content
                .replace(
                    "&SqlitePool",
                    "impl sqlx::Executor<'_, Database = sqlx::Sqlite>",
                )
                .replace(
                    "pool: impl sqlx::Executor<'_, Database = sqlx::Sqlite>",
                    "pool: impl sqlx::Executor<'_, Database = sqlx::Sqlite> + Copy",
                );
            fs::write(&path, new_content).unwrap();
        }
    }
 }
@@ -1,3 +1,4 @@
 use anyhow::Context;
 use std::io::{self, Write};
 use std::path::PathBuf;
@@ -5,22 +6,35 @@ use clap::{Parser, Subcommand};
 use crate::{
    config::Config,
    db::repository::{roles as role_repo, users as user_repo},
    db::{
        self,
-        models::{Tenant, UserStatus},
+        models::{Tenant, User, UserStatus},
    },
    error::AppError,
-    identity::{roles, users as identity_users},
+    identity::users as identity_users,
    security::tokens as token_security,
 };
 /// Resolve a user by ID or username (username lookup is case-sensitive, as stored).
 async fn resolve_user(
    provider: &std::sync::Arc<dyn crate::db::provider::DatabaseProvider>,
    id_or_username: &str,
 ) -> anyhow::Result<User> {
    if let Some(user) = provider.users().find_by_id(id_or_username).await? {
        return Ok(user);
    }
    if let Some(user) = provider.users().find_by_username(id_or_username).await? {
        return Ok(user);
    }
    anyhow::bail!("User not found: '{id_or_username}' (use ID or username)");
 }
 // ── CLI Definition ────────────────────────────────────────────────────────────
 #[derive(Parser)]
 #[command(
    name = "nx9-auth",
-    about = "NX9 Identity and Access Management service",
+    about = "nx9-auth \u{2014} Self-hosted Identity & Access Management",
    version = env!("CARGO_PKG_VERSION"),
    author,
 )]
@@ -39,7 +53,7 @@ pub struct Cli {
 #[derive(Subcommand)]
 pub enum Commands {
-    /// Start the HTTP server.
+    /// Start the HTTP server (API + Admin UI).
    Serve,
    /// Run pending database migrations.
@@ -48,42 +62,42 @@ pub enum Commands {
    /// Check system health and configuration.
    Doctor,
-    /// Create an administrator user.
+    /// Create the initial administrator account.
    CreateAdmin {
        /// Username for the new admin account.
        username: String,
    },
-    /// Create a standard user.
+    /// Create a new user account.
    CreateUser {
        /// Username for the new user account.
        username: String,
    },
-    /// List all users in the system.
+    /// List all users.
    ListUsers,
-    /// Disable a user account (sets status = disabled).
+    /// Disable a user account.
    DisableUser {
-        /// User ID to disable.
+        /// User ID or username to disable.
-        id: String,
+        id_or_username: String,
    },
-    /// Enable a user account (sets status = active).
+    /// Enable a user account.
    EnableUser {
-        /// User ID to enable.
+        /// User ID or username to enable.
-        id: String,
+        id_or_username: String,
    },
    /// Reset a user's password.
    ResetPassword {
-        /// User ID to reset.
+        /// User ID or username to reset.
-        id: String,
+        id_or_username: String,
    },
    /// Create a personal access token for a user.
    CreateToken {
-        /// User ID to create the token for.
+        /// User ID or username to create the token for.
        #[arg(long)]
        user: String,
        /// Descriptive name for the token.
@@ -97,7 +111,7 @@ pub enum Commands {
        id: String,
    },
-    /// Initialize the configuration, directories, database and admin user.
+    /// Initialize config, database, and admin user.
    Init {
        /// Run in non-interactive mode.
        #[arg(long)]
@@ -120,7 +134,7 @@ pub enum Commands {
        admin_password: Option<String>,
    },
-    /// Print configuration and database file paths.
+    /// Show configuration and database paths.
    ConfigPath {
        /// Output in machine-readable JSON format.
        #[arg(long)]
@@ -148,6 +162,12 @@ pub enum Commands {
        /// Path where the backup file will be created.
        path: PathBuf,
    },
    /// Restore the database from a backup file.
    Restore {
        /// Path to the backup file to restore from.
        path: PathBuf,
    },
 }
 // ── Helpers ───────────────────────────────────────────────────────────────────
@@ -192,9 +212,15 @@ pub async fn run(command: Commands, config: Config) -> anyhow::Result<()> {
        Commands::CreateUser { username } => cmd_create_user(&config, &username).await,
        Commands::ListUsers => cmd_list_users(&config).await,
-        Commands::DisableUser { id } => cmd_set_status(&config, &id, UserStatus::Disabled).await,
+        Commands::DisableUser { id_or_username } => {
-        Commands::EnableUser { id } => cmd_set_status(&config, &id, UserStatus::Active).await,
+            cmd_set_status(&config, &id_or_username, UserStatus::Disabled).await
-        Commands::ResetPassword { id } => cmd_reset_password(&config, &id).await,
+        }
        Commands::EnableUser { id_or_username } => {
            cmd_set_status(&config, &id_or_username, UserStatus::Active).await
        }
        Commands::ResetPassword { id_or_username } => {
            cmd_reset_password(&config, &id_or_username).await
        }
        Commands::CreateToken { user, name } => cmd_create_token(&config, &user, &name).await,
        Commands::RevokeToken { id } => cmd_revoke_token(&config, &id).await,
@@ -223,15 +249,15 @@ pub async fn run(command: Commands, config: Config) -> anyhow::Result<()> {
        } => cmd_show_user(&config, &id_or_username, permissions).await,
        Commands::ShowToken { id } => cmd_show_token(&config, &id).await,
        Commands::Backup { path } => cmd_backup(&config, &path).await,
        Commands::Restore { path } => cmd_restore(&config, &path).await,
    }
 }
 // ── migrate ───────────────────────────────────────────────────────────────────
 async fn cmd_migrate(config: &Config) -> anyhow::Result<()> {
-    let pool = db::create_pool(&config.database.path).await?;
+    let (_provider, backend, _pool) = db::init_provider(config).await?;
-    db::run_migrations(&pool).await?;
+    println!("✓ Migrations applied successfully ({backend}).");
    println!("✓ Migrations applied successfully.");
    Ok(())
 }
@@ -242,84 +268,36 @@ async fn run_doctor_checks(config: &Config) -> anyhow::Result<bool> {
    println!("\nnx9-auth doctor\n");
-    // 1. Config loads (already done — we got here with a valid config)
+    // 1. Config file loads
    println!("  ✓  Config file loads and parses");
-    // 2. DB path is writable
+    // 2. DB backend & connection
-    let db_path = std::path::Path::new(&config.database.path);
+    let (url, backend) = match config.database.resolved_url() {
-    let db_dir_writable = if let Some(parent) = db_path.parent() {
+        Ok(res) => res,
-        if parent.as_os_str().is_empty() {
+        Err(e) => {
-            true
+            println!("  ✗  Failed to resolve database configuration: {e}");
-        } else if std::fs::create_dir_all(parent).is_err() {
+            println!("\nDoctor result: FAIL\n");
-            false
+            return Ok(false);
        } else {
            let temp_file = parent.join(format!(
                ".nx9_auth_doctor_{}",
                std::time::SystemTime::now()
                    .duration_since(std::time::UNIX_EPOCH)
                    .map(|d| d.as_nanos())
                    .unwrap_or(0)
            ));
            if std::fs::write(&temp_file, b"test").is_ok() {
                let _ = std::fs::remove_file(temp_file);
                true
            } else {
                false
        }
        }
    } else {
        true
    };
-    if db_dir_writable {
+    println!("  ✓  Database backend detected: {backend}");
-        println!("  ✓  Database directory is writable");
+    println!("  ✓  Database URL: {url}");
    } else {
        println!(
            "  ✗  Database directory is not writable: {}",
            config.database.path
        );
        ok = false;
    }
-    // 3. DB connects
+    let provider = match db::init_provider(config).await {
-    let pool_result = db::create_pool(&config.database.path).await;
+        Ok((p, _, _)) => {
-    let pool = match pool_result {
+            println!("  ✓  Database connection & migrations successful");
        Ok(p) => {
            println!("  ✓  Database connection successful");
            p
        }
        Err(e) => {
-            println!("  ✗  Database connection failed: {}", e);
+            println!("  ✗  Database initialization failed: {e}");
            println!("\nDoctor result: FAIL\n");
            return Ok(false);
        }
    };
    // 4. Migrations are up to date
    // Verify migrations are applied
    let migration_check: Result<(i64,), sqlx::Error> =
        sqlx::query_as("SELECT COUNT(*) FROM _sqlx_migrations")
            .fetch_one(&pool)
            .await;
    match migration_check {
        Ok((count,)) if count > 0 => println!("  ✓  Migrations applied ({} recorded)", count),
        Ok(_) => {
            println!("  ✗  No migrations recorded — run `nx9-auth migrate` first");
            ok = false;
        }
        Err(_) => {
            println!("  ✗  Migrations table missing — run `nx9-auth migrate` first");
            ok = false;
        }
    }
    // 5. Default tenant exists
-    let tenant_check: Result<(i64,), sqlx::Error> =
+    match provider.tenants().find_by_id(Tenant::DEFAULT_ID).await {
-        sqlx::query_as("SELECT COUNT(*) FROM tenants WHERE id = ?")
+        Ok(Some(_)) => println!("  ✓  Default tenant exists"),
            .bind(Tenant::DEFAULT_ID)
            .fetch_one(&pool)
            .await;
    match tenant_check {
        Ok((1,)) => println!("  ✓  Default tenant exists"),
        _ => {
            println!("  ✗  Default tenant missing — run `nx9-auth migrate`");
            ok = false;
@@ -327,7 +305,7 @@ async fn run_doctor_checks(config: &Config) -> anyhow::Result<bool> {
    }
    // 6. Admin role exists
-    match role_repo::admin_role_exists(&pool).await {
+    match provider.roles().admin_role_exists().await {
        Ok(true) => println!("  ✓  admin role exists"),
        Ok(false) => {
            println!("  ✗  admin role missing — run `nx9-auth migrate`");
@@ -340,7 +318,7 @@ async fn run_doctor_checks(config: &Config) -> anyhow::Result<bool> {
    }
    // 7. At least one admin user exists
-    match user_repo::count_admins(&pool).await {
+    match provider.users().count_admins().await {
        Ok(n) if n > 0 => println!("  ✓  {} admin user(s) exist", n),
        Ok(_) => {
            println!("  ✗  No admin users — run `nx9-auth create-admin <username>`");
@@ -352,103 +330,6 @@ async fn run_doctor_checks(config: &Config) -> anyhow::Result<bool> {
        }
    }
    // 8. WAL mode
    let journal_mode: Result<(String,), sqlx::Error> =
        sqlx::query_as("PRAGMA journal_mode").fetch_one(&pool).await;
    match journal_mode {
        Ok((mode,)) if mode.to_lowercase() == "wal" => println!("  ✓  WAL mode enabled"),
        Ok((mode,)) => {
            println!("  ✗  WAL mode not enabled (current mode: {})", mode);
            ok = false;
        }
        Err(e) => {
            println!("  ✗  Failed to check journal mode: {}", e);
            ok = false;
        }
    }
    // 9. Foreign Keys
    let foreign_keys: Result<(i64,), sqlx::Error> =
        sqlx::query_as("PRAGMA foreign_keys").fetch_one(&pool).await;
    match foreign_keys {
        Ok((1,)) => println!("  ✓  Foreign keys constraint enforcement enabled"),
        Ok((val,)) => {
            println!(
                "  ✗  Foreign keys constraint enforcement disabled (current value: {})",
                val
            );
            ok = false;
        }
        Err(e) => {
            println!("  ✗  Failed to check foreign keys: {}", e);
            ok = false;
        }
    }
    // 10. Table existence
    for table in &["audit_logs", "sessions"] {
        let table_exists: Result<Option<(String,)>, sqlx::Error> =
            sqlx::query_as("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
                .bind(table)
                .fetch_optional(&pool)
                .await;
        match table_exists {
            Ok(Some(_)) => println!("  ✓  Table '{}' exists", table),
            Ok(None) => {
                println!("  ✗  Table '{}' is missing", table);
                ok = false;
            }
            Err(e) => {
                println!("  ✗  Failed to check existence of table '{}': {}", table, e);
                ok = false;
            }
        }
    }
    // 11. Database Write Test
    let write_test: Result<(), sqlx::Error> = async {
        let mut tx = pool.begin().await?;
        sqlx::query("CREATE TEMP TABLE doctor_test_write (id INTEGER PRIMARY KEY)")
            .execute(&mut *tx)
            .await?;
        sqlx::query("INSERT INTO doctor_test_write (id) VALUES (1)")
            .execute(&mut *tx)
            .await?;
        sqlx::query("DROP TABLE doctor_test_write")
            .execute(&mut *tx)
            .await?;
        tx.commit().await?;
        Ok(())
    }
    .await;
    match write_test {
        Ok(()) => {
            println!("  ✓  Database write test successful (temp table creation and deletion)")
        }
        Err(e) => {
            println!("  ✗  Database write test failed: {}", e);
            ok = false;
        }
    }
    // 12. Database Integrity Check
    let integrity_check: Result<(String,), sqlx::Error> = sqlx::query_as("PRAGMA integrity_check")
        .fetch_one(&pool)
        .await;
    match integrity_check {
        Ok((res,)) if res.to_lowercase() == "ok" => {
            println!("  ✓  Database integrity check passed")
        }
        Ok((res,)) => {
            println!("  ✗  Database integrity check failed: {}", res);
            ok = false;
        }
        Err(e) => {
            println!("  ✗  Failed to run database integrity check: {}", e);
            ok = false;
        }
    }
    println!();
    if ok {
        println!("Doctor result: OK\n");
@@ -470,11 +351,12 @@ async fn cmd_doctor(config: &Config) -> anyhow::Result<()> {
 // ── create-admin ──────────────────────────────────────────────────────────────
 async fn cmd_create_admin(config: &Config, username: &str) -> anyhow::Result<()> {
-    let pool = db::create_pool(&config.database.path).await?;
+    let (provider, _backend, _pool) = db::init_provider(config).await?;
    let password = prompt_password_confirmed("Password for admin: ", true)?;
    let user = identity_users::create_user(
-        &pool,
+        &provider,
        &config.security,
        Tenant::DEFAULT_ID,
        username,
@@ -485,7 +367,7 @@ async fn cmd_create_admin(config: &Config, username: &str) -> anyhow::Result<()>
    )
    .await?;
-    roles::assign_role(&pool, &user.id, "admin", None, None, None).await?;
+    crate::identity::roles::assign_role(&provider, &user.id, "admin", None, None, None).await?;
    println!("✓ Admin user '{}' created (id: {})", user.username, user.id);
    Ok(())
@@ -494,11 +376,12 @@ async fn cmd_create_admin(config: &Config, username: &str) -> anyhow::Result<()>
 // ── create-user ───────────────────────────────────────────────────────────────
 async fn cmd_create_user(config: &Config, username: &str) -> anyhow::Result<()> {
-    let pool = db::create_pool(&config.database.path).await?;
+    let (provider, _backend, _pool) = db::init_provider(config).await?;
    let password = prompt_password_confirmed("Password: ", false)?;
    let user = identity_users::create_user(
-        &pool,
+        &provider,
        &config.security,
        Tenant::DEFAULT_ID,
        username,
@@ -516,8 +399,9 @@ async fn cmd_create_user(config: &Config, username: &str) -> anyhow::Result<()>
 // ── list-users ────────────────────────────────────────────────────────────────
 async fn cmd_list_users(config: &Config) -> anyhow::Result<()> {
-    let pool = db::create_pool(&config.database.path).await?;
+    let (provider, _backend, _pool) = db::init_provider(config).await?;
-    let users = identity_users::list_users(&pool, Tenant::DEFAULT_ID).await?;
+
    let users = provider.users().list(Tenant::DEFAULT_ID).await?;
    if users.is_empty() {
        println!("No users found.");
@@ -546,10 +430,15 @@ async fn cmd_list_users(config: &Config) -> anyhow::Result<()> {
 // ── disable/enable-user ───────────────────────────────────────────────────────
-async fn cmd_set_status(config: &Config, id: &str, status: UserStatus) -> anyhow::Result<()> {
+async fn cmd_set_status(
-    let pool = db::create_pool(&config.database.path).await?;
+    config: &Config,
-    let user = identity_users::get_user(&pool, id).await?;
+    id_or_username: &str,
-    identity_users::update_status(&pool, id, status.as_i32(), None, None, None).await?;
+    status: UserStatus,
 ) -> anyhow::Result<()> {
    let (provider, _backend, _pool) = db::init_provider(config).await?;
    let user = resolve_user(&provider, id_or_username).await?;
    identity_users::update_status(&provider, &user.id, status.as_i32(), None, None, None).await?;
    println!(
        "✓ User '{}' status set to {}",
        user.username,
@@ -560,14 +449,23 @@ async fn cmd_set_status(config: &Config, id: &str, status: UserStatus) -> anyhow
 // ── reset-password ────────────────────────────────────────────────────────────
-async fn cmd_reset_password(config: &Config, id: &str) -> anyhow::Result<()> {
+async fn cmd_reset_password(config: &Config, id_or_username: &str) -> anyhow::Result<()> {
-    let pool = db::create_pool(&config.database.path).await?;
+    let (provider, _backend, _pool) = db::init_provider(config).await?;
-    let user = identity_users::get_user(&pool, id).await?;
+
-    let user_roles = role_repo::list_for_user(&pool, &user.id).await?;
+    let user = resolve_user(&provider, id_or_username).await?;
    let user_roles = provider.roles().list_for_user(&user.id).await?;
    let is_admin = user_roles.iter().any(|r| r.name == "admin");
    let password =
        prompt_password_confirmed(&format!("New password for '{}': ", user.username), is_admin)?;
-    identity_users::reset_password(&pool, &config.security, id, &password, None, None, None)
+    identity_users::reset_password(
        &provider,
        &config.security,
        &user.id,
        &password,
        None,
        None,
        None,
    )
    .await?;
    println!("✓ Password reset for user '{}'", user.username);
    Ok(())
@@ -575,11 +473,19 @@ async fn cmd_reset_password(config: &Config, id: &str) -> anyhow::Result<()> {
 // ── create-token ──────────────────────────────────────────────────────────────
-async fn cmd_create_token(config: &Config, user_id: &str, name: &str) -> anyhow::Result<()> {
+async fn cmd_create_token(config: &Config, user_ref: &str, name: &str) -> anyhow::Result<()> {
-    let pool = db::create_pool(&config.database.path).await?;
+    let (provider, _backend, _pool) = db::init_provider(config).await?;
-    let user = identity_users::get_user(&pool, user_id).await?;
+
-    let (token, raw) =
+    let user = resolve_user(&provider, user_ref).await?;
-        token_security::create_token(&pool, user_id, name, &config.security, None, None, None)
+    let (token, raw) = token_security::create_token(
        &provider,
        &user.id,
        name,
        &config.security,
        None,
        None,
        None,
    )
    .await?;
    println!(
@@ -603,14 +509,16 @@ async fn cmd_create_token(config: &Config, user_id: &str, name: &str) -> anyhow:
 // ── revoke-token ──────────────────────────────────────────────────────────────
 async fn cmd_revoke_token(config: &Config, id: &str) -> anyhow::Result<()> {
-    let pool = db::create_pool(&config.database.path).await?;
+    let (provider, _backend, _pool) = db::init_provider(config).await?;
-    let token = crate::db::repository::tokens::find_by_id(&pool, id)
+    let token = provider
        .tokens()
        .find_by_id(id)
        .await
        .map_err(AppError::Database)?
        .ok_or_else(|| anyhow::anyhow!("token not found: {}", id))?;
-    crate::security::tokens::revoke_token(&pool, id, None, None, None).await?;
+    token_security::revoke_token(&provider, id, None, None, None).await?;
    println!("✓ Token '{}' (id: {}) revoked", token.name, token.id);
    Ok(())
@@ -655,7 +563,8 @@ async fn cmd_init(
        }
    }
-    let db_path = std::path::Path::new(&config.database.path);
+    let sqlite_path = config.database.sqlite_path();
    let db_path = std::path::Path::new(&sqlite_path);
    println!("Creating database directory...");
    if let Some(parent) = db_path.parent() {
        if !parent.as_os_str().is_empty() {
@@ -671,16 +580,15 @@ async fn cmd_init(
    }
    // 2. Open DB pool and run migrations
-    println!("Running migrations...");
+    println!("Initializing database and migrations...");
-    let pool = db::create_pool(&config.database.path).await?;
+    let (provider, backend, _pool) = db::init_provider(config).await?;
-    db::run_migrations(&pool).await?;
+    println!("✓ Database initialized ({backend}).");
    println!("✓ Migrations applied successfully.");
    // 3. Create administrator
    if skip_admin {
        println!("ℹ Administrator creation skipped.");
    } else {
-        let admin_count = user_repo::count_admins(&pool).await?;
+        let admin_count = provider.users().count_admins().await?;
        if admin_count == 0 {
            let username: String;
            let password: String;
@@ -715,8 +623,8 @@ async fn cmd_init(
                password = prompt_password_confirmed("Password: ", true)?;
            }
-            let user = crate::identity::users::create_user(
+            let user = identity_users::create_user(
-                &pool,
+                &provider,
                &config.security,
                Tenant::DEFAULT_ID,
                &username,
@@ -727,7 +635,8 @@ async fn cmd_init(
            )
            .await?;
-            roles::assign_role(&pool, &user.id, "admin", None, None, None).await?;
+            crate::identity::roles::assign_role(&provider, &user.id, "admin", None, None, None)
                .await?;
            println!("✓ Admin user '{}' created successfully.", username);
        } else {
            println!("✓ Administrator account already exists.");
@@ -735,13 +644,13 @@ async fn cmd_init(
    }
    // 4. Run post-install validation (relaxed)
-    println!("\nRunning validation...");
+    println!("\nValidation:");
    let init_ok = run_init_validation(config, skip_admin).await?;
    if !init_ok {
        anyhow::bail!("Post-installation validation checks failed!");
    }
-    println!("\nnx9-auth is ready.\n\nStart with:\n\n    nx9-auth serve\n");
+    println!("\nnx9-auth is ready.\n\nStart the server with:\n  nx9-auth serve\n");
    Ok(())
 }
@@ -749,10 +658,11 @@ async fn run_init_validation(config: &Config, admin_skipped: bool) -> anyhow::Re
    let mut ok = true;
    // 1. Config valid
-    println!("  ✓  Config valid");
+    println!("  ✓ Configuration");
    // 2. Directories writable
-    let db_path = std::path::Path::new(&config.database.path);
+    let sqlite_path = config.database.sqlite_path();
    let db_path = std::path::Path::new(&sqlite_path);
    let mut dirs_ok = true;
    if let Some(parent) = db_path.parent() {
        if !parent.as_os_str().is_empty() && std::fs::create_dir_all(parent).is_err() {
@@ -766,16 +676,17 @@ async fn run_init_validation(config: &Config, admin_skipped: bool) -> anyhow::Re
        }
    }
    if dirs_ok {
-        println!("  ✓  Directories writable");
+        println!("  ✓ Directories");
    } else {
        println!("  ✗ Directories not writable");
        ok = false;
    }
-    // 3. Database reachable
+    // 3. Database & Migrations reachable
-    let pool = match db::create_pool(&config.database.path).await {
+    let provider = match db::init_provider(config).await {
-        Ok(p) => {
+        Ok((p, _, _)) => {
-            println!("  ✓  Database reachable");
+            println!("  ✓ Database");
            println!("  ✓ Migrations");
            p
        }
        Err(e) => {
@@ -784,23 +695,10 @@ async fn run_init_validation(config: &Config, admin_skipped: bool) -> anyhow::Re
        }
    };
-    // 4. Migrations applied
+    // 4. Admin account check
-    let migration_check: Result<(i64,), sqlx::Error> =
+    let admin_count = provider.users().count_admins().await.unwrap_or(0);
        sqlx::query_as("SELECT COUNT(*) FROM _sqlx_migrations")
            .fetch_one(&pool)
            .await;
    match migration_check {
        Ok((count,)) if count > 0 => println!("  ✓  Migrations applied"),
        _ => {
            println!("  ✗  Migrations not applied");
            ok = false;
        }
    }
    // 5. Admin account check
    let admin_count = user_repo::count_admins(&pool).await.unwrap_or(0);
    if admin_count > 0 {
-        println!("  ✓  Administrator account exists");
+        println!("  ✓ Administrator account");
    } else if admin_skipped {
        println!("  ℹ Administrator creation skipped");
    } else {
@@ -820,7 +718,12 @@ async fn cmd_config_path(config: &Config, json: bool) -> anyhow::Result<()> {
        .or_else(Config::default_user_config_path)
        .map(|p| p.to_string_lossy().into_owned())
        .unwrap_or_default();
-    let database_file = config.database.path.clone();
+    let (database_url, _) = config.database.resolved_url().unwrap_or_else(|_| {
        (
            config.database.sqlite_path(),
            crate::config::DatabaseBackend::Sqlite,
        )
    });
    let state_dir = if let Ok(home) = std::env::var("HOME") {
        std::path::Path::new(&home)
@@ -834,7 +737,7 @@ async fn cmd_config_path(config: &Config, json: bool) -> anyhow::Result<()> {
    if json {
        let val = serde_json::json!({
            "config": config_file,
-            "database": database_file,
+            "database": database_url,
            "state": state_dir,
        });
        println!("{}", serde_json::to_string_pretty(&val)?);
@@ -842,7 +745,7 @@ async fn cmd_config_path(config: &Config, json: bool) -> anyhow::Result<()> {
        println!("\nConfig:");
        println!("  {}", config_file);
        println!("\nDatabase:");
-        println!("  {}", database_file);
+        println!("  {}", database_url);
        println!("\nLogs/State:");
        println!("  {}", state_dir);
        println!();
@@ -857,19 +760,11 @@ async fn cmd_show_user(
    id_or_username: &str,
    permissions: bool,
 ) -> anyhow::Result<()> {
-    let pool = db::create_pool(&config.database.path).await?;
+    let (provider, _backend, _pool) = db::init_provider(config).await?;
-    let user = match user_repo::find_by_id(&pool, id_or_username).await? {
+    let user = resolve_user(&provider, id_or_username).await?;
        Some(u) => Some(u),
        None => user_repo::find_by_username(&pool, id_or_username).await?,
    };
-    let user = match user {
+    let user_roles = provider.roles().list_for_user(&user.id).await?;
        Some(u) => u,
        None => anyhow::bail!("User not found: '{}'", id_or_username),
    };
    let user_roles = role_repo::list_for_user(&pool, &user.id).await?;
    let role_names: Vec<String> = user_roles.into_iter().map(|r| r.name).collect();
    println!("\nUser");
@@ -897,7 +792,7 @@ async fn cmd_show_user(
        println!("\nPermissions");
        println!("───────────");
-        let user_perms = crate::db::repository::permissions::list_for_user(&pool, &user.id).await?;
+        let user_perms = provider.permissions().list_for_user(&user.id).await?;
        if user_perms.is_empty() {
            println!("none");
        } else {
@@ -914,13 +809,16 @@ async fn cmd_show_user(
 // ── show-token ────────────────────────────────────────────────────────────────
 async fn cmd_show_token(config: &Config, id: &str) -> anyhow::Result<()> {
-    let pool = db::create_pool(&config.database.path).await?;
+    let (provider, _backend, _pool) = db::init_provider(config).await?;
-    let token = crate::db::repository::tokens::find_by_id(&pool, id)
+
    let token = provider
        .tokens()
        .find_by_id(id)
        .await
        .map_err(AppError::Database)?
        .ok_or_else(|| anyhow::anyhow!("Token not found: {}", id))?;
-    let user = user_repo::find_by_id(&pool, &token.user_id).await?;
+    let user = provider.users().find_by_id(&token.user_id).await?;
    let username = user
        .map(|u| u.username)
        .unwrap_or_else(|| "unknown".to_string());
@@ -952,20 +850,26 @@ async fn cmd_show_token(config: &Config, id: &str) -> anyhow::Result<()> {
 // ── backup ────────────────────────────────────────────────────────────────────
 async fn cmd_backup(config: &Config, path: &std::path::Path) -> anyhow::Result<()> {
-    // 1. Resolve paths to absolute paths
+    let (url, backend) = config.database.resolved_url()?;
-    let source_path = std::path::Path::new(&config.database.path);
+    match backend {
-
+        crate::config::DatabaseBackend::Sqlite => {
            let sqlite_path = config.database.sqlite_path();
            let source_path = std::path::Path::new(&sqlite_path);
            let abs_source =
                std::fs::canonicalize(source_path).unwrap_or_else(|_| source_path.to_path_buf());
            let abs_target = if path.is_absolute() {
                path.to_path_buf()
            } else {
                std::env::current_dir()?.join(path)
            };
-    let source_dir = abs_source.parent().unwrap();
+            let source_dir = abs_source
-    let source_file_name = abs_source.file_name().unwrap().to_string_lossy();
+                .parent()
                .ok_or_else(|| anyhow::anyhow!("invalid database source path"))?;
            let source_file_name = abs_source
                .file_name()
                .ok_or_else(|| anyhow::anyhow!("invalid database file name"))?
                .to_string_lossy();
            let source_wal = source_dir.join(format!("{}-wal", source_file_name));
            let source_shm = source_dir.join(format!("{}-shm", source_file_name));
@@ -988,23 +892,19 @@ async fn cmd_backup(config: &Config, path: &std::path::Path) -> anyhow::Result<(
                );
            }
    // 2. Ensure parent directory exists
            if let Some(parent) = path.parent() {
                if !parent.as_os_str().is_empty() {
                    std::fs::create_dir_all(parent)?;
                }
            }
    // 3. Delete target file if it already exists to overwrite
            if path.exists() {
                std::fs::remove_file(path)?;
            }
-    // 4. Perform SQLite VACUUM INTO
+            #[cfg(feature = "sqlite")]
-    // VACUUM INTO is a standard SQL statement supported by SQLite
+            {
-    // for transactionally consistent online backups. It is the modern
+                let pool = db::create_pool(&sqlite_path).await?;
    // SQL alternative to the online backup C API, especially on WAL-enabled databases.
    let pool = db::create_pool(&config.database.path).await?;
                let path_str = path.to_string_lossy().replace('\'', "''");
                let query = format!("VACUUM INTO '{}'", path_str);
@@ -1013,8 +913,86 @@ async fn cmd_backup(config: &Config, path: &std::path::Path) -> anyhow::Result<(
                    .await?;
                println!(
-        "✓ Database backup created successfully at: {}",
+                    "✓ SQLite database backup created successfully at: {}",
                    path.display()
                );
            }
            #[cfg(not(feature = "sqlite"))]
            {
                anyhow::bail!("SQLite database backups require the 'sqlite' feature");
            }
        }
        crate::config::DatabaseBackend::Postgres => {
            let output = std::process::Command::new("pg_dump")
                .arg("-Fc")
                .arg("-d")
                .arg(&url)
                .arg("-f")
                .arg(path)
                .output()
                .context(
                    "failed to execute pg_dump (ensure PostgreSQL client tools are installed)",
                )?;
            if !output.status.success() {
                let err = String::from_utf8_lossy(&output.stderr);
                anyhow::bail!("pg_dump failed: {err}");
            }
            println!(
                "✓ PostgreSQL database backup created successfully at: {}",
                path.display()
            );
        }
    }
    Ok(())
 }
 async fn cmd_restore(config: &Config, path: &std::path::Path) -> anyhow::Result<()> {
    if !path.exists() {
        anyhow::bail!("Backup file does not exist: {}", path.display());
    }
    let (url, backend) = config.database.resolved_url()?;
    match backend {
        crate::config::DatabaseBackend::Sqlite => {
            let sqlite_path = config.database.sqlite_path();
            let target_path = std::path::Path::new(&sqlite_path);
            if let Some(parent) = target_path.parent() {
                if !parent.as_os_str().is_empty() {
                    std::fs::create_dir_all(parent)?;
                }
            }
            std::fs::copy(path, target_path).with_context(|| {
                format!("failed to restore backup to {}", target_path.display())
            })?;
            println!(
                "✓ SQLite database restored successfully from: {}",
                path.display()
            );
        }
        crate::config::DatabaseBackend::Postgres => {
            let output = std::process::Command::new("pg_restore")
                .arg("--clean")
                .arg("--if-exists")
                .arg("-d")
                .arg(&url)
                .arg(path)
                .output()
                .context(
                    "failed to execute pg_restore (ensure PostgreSQL client tools are installed)",
                )?;
            if !output.status.success() {
                let err = String::from_utf8_lossy(&output.stderr);
                anyhow::bail!("pg_restore failed: {err}");
            }
            println!(
                "✓ PostgreSQL database restored successfully from: {}",
                path.display()
            );
        }
    }
    Ok(())
 }
@@ -19,6 +19,9 @@ pub struct Config {
    #[serde(default)]
    pub audit: AuditConfig,
    #[serde(default)]
    pub shutdown: ShutdownConfig,
 }
 #[derive(Debug, Deserialize, Clone)]
@@ -27,12 +30,61 @@ pub struct ServerConfig {
    pub host: String,
    /// Port to listen on.
    pub port: u16,
    /// Whether the session cookie should set the `Secure` flag.
    ///
    /// Must be `true` when the UI is served over HTTPS (or behind a TLS
    /// reverse proxy). Leave `false` for plain-HTTP self-hosted installs —
    /// browsers reject `Secure` cookies on `http://` and authentication breaks.
    #[serde(default)]
    pub cookie_secure: bool,
    /// Production mode: enables HSTS, requires secure cookies, and refuses
    /// known-insecure bind configurations.
    #[serde(default)]
    pub production: bool,
 }
 use std::fmt::Display;
 /// Supported database backends.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum DatabaseBackend {
    Sqlite,
    Postgres,
 }
 impl Display for DatabaseBackend {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Sqlite => write!(f, "sqlite"),
            Self::Postgres => write!(f, "postgres"),
        }
    }
 }
 #[derive(Debug, Deserialize, Clone)]
 pub struct DatabaseConfig {
-    /// Path to the SQLite database file (supports ~ prefix).
+    /// Unified database connection URL (e.g., sqlite://./auth.db or postgres://user:pass@host/db).
-    pub path: String,
+    #[serde(default)]
    pub url: Option<String>,
    /// Legacy path to SQLite database file.
    #[serde(default)]
    pub path: Option<String>,
    /// Maximum connection pool size.
    #[serde(default)]
    pub max_connections: Option<u32>,
    /// Minimum connection pool size.
    #[serde(default)]
    pub min_connections: Option<u32>,
    /// Connection timeout in seconds.
    #[serde(default)]
    pub connect_timeout_secs: Option<u64>,
    /// Idle connection timeout in seconds.
    #[serde(default)]
    pub idle_timeout_secs: Option<u64>,
    /// Maximum connection lifetime in seconds.
    #[serde(default)]
    pub max_lifetime_secs: Option<u64>,
 }
 #[derive(Debug, Deserialize, Clone)]
@@ -64,10 +116,32 @@ impl Default for ServerConfig {
        Self {
            host: "127.0.0.1".to_string(), // Default to loopback for user mode safety
            port: 8655,
            // Safe default for local/self-hosted HTTP. Enable for HTTPS production.
            cookie_secure: false,
            production: false,
        }
    }
 }
 impl ServerConfig {
    /// Refuse insecure production deployments.
    ///
    /// TLS is typically terminated at a reverse proxy; this enforces that
    /// cookies/HSTS are configured as if the external surface is HTTPS.
    pub fn validate_production_security(&self) -> anyhow::Result<()> {
        if !self.production {
            return Ok(());
        }
        if !self.cookie_secure {
            anyhow::bail!(
                "production mode requires server.cookie_secure = true \
                 (session cookies must be Secure for HTTPS deployments)"
            );
        }
        Ok(())
    }
 }
 impl Default for DatabaseConfig {
    fn default() -> Self {
        let default_db_path = if let Ok(home) = std::env::var("HOME") {
@@ -79,7 +153,73 @@ impl Default for DatabaseConfig {
            "/var/lib/nx9-auth/auth.db".to_string()
        };
        Self {
-            path: default_db_path,
+            url: None,
            path: Some(default_db_path),
            max_connections: None,
            min_connections: None,
            connect_timeout_secs: None,
            idle_timeout_secs: None,
            max_lifetime_secs: None,
        }
    }
 }
 impl DatabaseConfig {
    /// Resolve and normalize the database URL and derive the active backend.
    pub fn resolved_url(&self) -> Result<(String, DatabaseBackend)> {
        let raw = if let Some(ref url) = self.url {
            let trimmed = url.trim();
            if !trimmed.is_empty() {
                trimmed.to_string()
            } else if let Some(ref path) = self.path {
                path.trim().to_string()
            } else {
                anyhow::bail!("missing database url or path configuration");
            }
        } else if let Some(ref path) = self.path {
            path.trim().to_string()
        } else {
            anyhow::bail!("missing database url or path configuration");
        };
        if raw.starts_with("postgres://") || raw.starts_with("postgresql://") {
            Ok((raw, DatabaseBackend::Postgres))
        } else if raw.starts_with("sqlite://") {
            Ok((raw, DatabaseBackend::Sqlite))
        } else if self.url.is_some() && raw.contains("://") {
            anyhow::bail!("unknown or malformed database URL scheme in '{raw}'");
        } else {
            // Treat plain file path as SQLite
            let path = resolve_home_path(&raw);
            let url = format!("sqlite://{path}?mode=rwc");
            Ok((url, DatabaseBackend::Sqlite))
        }
    }
    /// Retrieve the SQLite path for legacy file-based commands.
    pub fn sqlite_path(&self) -> String {
        if let Some(ref path) = self.path {
            resolve_home_path(path)
        } else if let Some(ref url) = self.url {
            if let Some(stripped) = url.strip_prefix("sqlite://") {
                let clean = stripped.split('?').next().unwrap_or(stripped);
                resolve_home_path(clean)
            } else {
                url.clone()
            }
        } else {
            self.default_path()
        }
    }
    fn default_path(&self) -> String {
        if let Ok(home) = std::env::var("HOME") {
            Path::new(&home)
                .join(".local/share/nx9-auth/auth.db")
                .to_string_lossy()
                .into_owned()
        } else {
            "/var/lib/nx9-auth/auth.db".to_string()
        }
    }
 }
@@ -103,6 +243,53 @@ impl Default for AuditConfig {
    }
 }
 /// Shutdown timeout configuration.
 #[derive(Debug, Deserialize, Clone)]
 pub struct ShutdownConfig {
    /// Maximum time (seconds) to wait for graceful shutdown of HTTP
    /// connections and background workers.
    #[serde(default = "ShutdownConfig::default_graceful_timeout")]
    pub graceful_timeout_secs: u64,
    /// Hard timeout (seconds) after which shutdown is forced. Must be
    /// greater than `graceful_timeout_secs`.
    #[serde(default = "ShutdownConfig::default_force_timeout")]
    pub force_timeout_secs: u64,
 }
 impl ShutdownConfig {
    fn default_graceful_timeout() -> u64 {
        30
    }
    fn default_force_timeout() -> u64 {
        35
    }
    /// Validate timeout invariants at startup.
    pub fn validate(&self) -> anyhow::Result<()> {
        anyhow::ensure!(
            self.graceful_timeout_secs > 0,
            "shutdown.graceful_timeout_secs must be > 0 (got {})",
            self.graceful_timeout_secs
        );
        anyhow::ensure!(
            self.force_timeout_secs > self.graceful_timeout_secs,
            "shutdown.force_timeout_secs ({}) must be > graceful_timeout_secs ({})",
            self.force_timeout_secs,
            self.graceful_timeout_secs
        );
        Ok(())
    }
 }
 impl Default for ShutdownConfig {
    fn default() -> Self {
        Self {
            graceful_timeout_secs: 30,
            force_timeout_secs: 35,
        }
    }
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
 fn resolve_home_path(path: &str) -> String {
@@ -122,7 +309,15 @@ fn resolve_home_path(path: &str) -> String {
 impl Config {
    /// Resolve path prefixes such as ~ to actual home directories.
    pub fn resolve_paths(&mut self) {
-        self.database.path = resolve_home_path(&self.database.path);
+        if let Some(ref mut path) = self.database.path {
            *path = resolve_home_path(path);
        }
        if let Some(ref mut url) = self.database.url {
            if let Some(stripped) = url.strip_prefix("sqlite://") {
                let clean = resolve_home_path(stripped);
                *url = format!("sqlite://{clean}");
            }
        }
    }
    /// Load and parse config from a TOML file.
@@ -214,6 +409,10 @@ impl Config {
 # Interface to bind on. Use 127.0.0.1 for local/user mode.
 host = "127.0.0.1"
 port = 8655
 # Session cookie Secure flag (true only when serving over HTTPS).
 cookie_secure = false
 # Production mode: requires cookie_secure and enables HSTS.
 production = false
 [database]
 # Absolute or home-relative path to the SQLite database file.
@@ -248,10 +447,16 @@ mod tests {
        let cfg = Config::default();
        assert_eq!(cfg.server.port, 8655);
        assert_eq!(cfg.server.host, "127.0.0.1");
        assert!(!cfg.server.cookie_secure);
        assert!(!cfg.server.production);
        if std::env::var("HOME").is_ok() {
-            assert!(cfg.database.path.contains(".local/share/nx9-auth/auth.db"));
+            assert!(
                cfg.database
                    .sqlite_path()
                    .contains(".local/share/nx9-auth/auth.db")
            );
        } else {
-            assert_eq!(cfg.database.path, "/var/lib/nx9-auth/auth.db");
+            assert_eq!(cfg.database.sqlite_path(), "/var/lib/nx9-auth/auth.db");
        }
        assert_eq!(cfg.security.session_ttl_hours, 24);
        assert_eq!(cfg.security.session_absolute_ttl_days, 30);
@@ -0,0 +1,12 @@
 -- Opaque refresh tokens issued at login (hashed at rest with BLAKE3).
 CREATE TABLE IF NOT EXISTS refresh_tokens (
    id          TEXT    PRIMARY KEY NOT NULL,
    user_id     TEXT    NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    token_hash  TEXT    NOT NULL UNIQUE,
    expires_at  TEXT    NOT NULL,
    revoked     INTEGER NOT NULL DEFAULT 0,
    created_at  TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
 );
 CREATE INDEX IF NOT EXISTS idx_refresh_tokens_user ON refresh_tokens(user_id);
 CREATE INDEX IF NOT EXISTS idx_refresh_tokens_hash ON refresh_tokens(token_hash);
@@ -0,0 +1,10 @@
 CREATE TABLE IF NOT EXISTS tenants (
    id          TEXT    PRIMARY KEY NOT NULL,
    name        TEXT    NOT NULL,
    slug        TEXT    NOT NULL UNIQUE,
    enabled     INTEGER NOT NULL DEFAULT 1,
    created_at  TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')),
    updated_at  TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"'))
 );
 CREATE INDEX IF NOT EXISTS idx_tenants_slug ON tenants(slug);
@@ -0,0 +1,16 @@
 CREATE TABLE IF NOT EXISTS users (
    id              TEXT    PRIMARY KEY NOT NULL,
    tenant_id       TEXT    NOT NULL REFERENCES tenants(id) ON DELETE RESTRICT,
    username        TEXT    NOT NULL,
    password_hash   TEXT    NOT NULL,
    -- 1 = active, 2 = disabled, 3 = locked
    status          INTEGER NOT NULL DEFAULT 1,
    last_login_at   TEXT,
    created_at      TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\')),
    updated_at      TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\')),
    UNIQUE (tenant_id, username)
 );
 CREATE INDEX IF NOT EXISTS idx_users_username  ON users(username);
 CREATE INDEX IF NOT EXISTS idx_users_tenant_id ON users(tenant_id);
 CREATE INDEX IF NOT EXISTS idx_users_status    ON users(status);
@@ -0,0 +1,7 @@
 CREATE TABLE IF NOT EXISTS user_profiles (
    user_id       TEXT PRIMARY KEY NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    email         TEXT,
    full_name     TEXT,
    avatar_url    TEXT,
    metadata_json TEXT
 );
@@ -0,0 +1,5 @@
 CREATE TABLE IF NOT EXISTS roles (
    id          TEXT PRIMARY KEY NOT NULL,
    name        TEXT NOT NULL UNIQUE,
    description TEXT
 );
@@ -0,0 +1,5 @@
 CREATE TABLE IF NOT EXISTS permissions (
    id          TEXT PRIMARY KEY NOT NULL,
    name        TEXT NOT NULL UNIQUE,
    description TEXT
 );
@@ -0,0 +1,7 @@
 CREATE TABLE IF NOT EXISTS role_permissions (
    role_id       TEXT NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    permission_id TEXT NOT NULL REFERENCES permissions(id) ON DELETE CASCADE,
    PRIMARY KEY (role_id, permission_id)
 );
 CREATE INDEX IF NOT EXISTS idx_role_permissions_role ON role_permissions(role_id);
@@ -0,0 +1,7 @@
 CREATE TABLE IF NOT EXISTS user_roles (
    user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    role_id TEXT NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    PRIMARY KEY (user_id, role_id)
 );
 CREATE INDEX IF NOT EXISTS idx_user_roles_user ON user_roles(user_id);
@@ -0,0 +1,15 @@
 CREATE TABLE IF NOT EXISTS sessions (
    id           TEXT    PRIMARY KEY NOT NULL,
    user_id      TEXT    NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    token_hash   TEXT    NOT NULL UNIQUE,
    ip_address   TEXT,
    user_agent   TEXT,
    created_at   TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\')),
    expires_at   TEXT    NOT NULL,
    last_seen_at TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\')),
    revoked      INTEGER NOT NULL DEFAULT 0
 );
 CREATE INDEX IF NOT EXISTS idx_sessions_user_id    ON sessions(user_id);
 CREATE INDEX IF NOT EXISTS idx_sessions_token_hash ON sessions(token_hash);
 CREATE INDEX IF NOT EXISTS idx_sessions_expires_at ON sessions(expires_at);
@@ -0,0 +1,13 @@
 CREATE TABLE IF NOT EXISTS api_tokens (
    id           TEXT    PRIMARY KEY NOT NULL,
    user_id      TEXT    NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    name         TEXT    NOT NULL,
    token_hash   TEXT    NOT NULL UNIQUE,
    last_used_at TEXT,
    expires_at   TEXT,
    created_at   TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\')),
    revoked      INTEGER NOT NULL DEFAULT 0
 );
 CREATE INDEX IF NOT EXISTS idx_api_tokens_user_id    ON api_tokens(user_id);
 CREATE INDEX IF NOT EXISTS idx_api_tokens_token_hash ON api_tokens(token_hash);
@@ -0,0 +1,12 @@
 CREATE TABLE IF NOT EXISTS service_accounts (
    id          TEXT    PRIMARY KEY NOT NULL,
    tenant_id   TEXT    NOT NULL REFERENCES tenants(id) ON DELETE RESTRICT,
    name        TEXT    NOT NULL,
    description TEXT,
    enabled     INTEGER NOT NULL DEFAULT 1,
    created_at  TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\')),
    updated_at  TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\')),
    UNIQUE (tenant_id, name)
 );
 CREATE INDEX IF NOT EXISTS idx_service_accounts_tenant ON service_accounts(tenant_id);
@@ -0,0 +1,12 @@
 CREATE TABLE IF NOT EXISTS applications (
    id          TEXT    PRIMARY KEY NOT NULL,
    tenant_id   TEXT    NOT NULL REFERENCES tenants(id) ON DELETE RESTRICT,
    name        TEXT    NOT NULL,
    slug        TEXT    NOT NULL UNIQUE,
    enabled     INTEGER NOT NULL DEFAULT 1,
    created_at  TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\')),
    updated_at  TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\'))
 );
 CREATE INDEX IF NOT EXISTS idx_applications_tenant ON applications(tenant_id);
 CREATE INDEX IF NOT EXISTS idx_applications_slug   ON applications(slug);
@@ -0,0 +1,20 @@
 CREATE TABLE IF NOT EXISTS audit_logs (
    id              TEXT PRIMARY KEY NOT NULL,
    actor_user_id   TEXT REFERENCES users(id) ON DELETE SET NULL,
    target_user_id  TEXT REFERENCES users(id) ON DELETE SET NULL,
    action          TEXT NOT NULL,
    resource_type   TEXT NOT NULL,
    resource_id     TEXT,
    -- 'info', 'warning', 'critical'
    severity        TEXT NOT NULL DEFAULT 'info',
    ip_address      TEXT,
    user_agent      TEXT,
    metadata_json   TEXT,
    created_at      TEXT NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\'))
 );
 CREATE INDEX IF NOT EXISTS idx_audit_logs_actor      ON audit_logs(actor_user_id);
 CREATE INDEX IF NOT EXISTS idx_audit_logs_target     ON audit_logs(target_user_id);
 CREATE INDEX IF NOT EXISTS idx_audit_logs_action     ON audit_logs(action);
 CREATE INDEX IF NOT EXISTS idx_audit_logs_created_at ON audit_logs(created_at);
 CREATE INDEX IF NOT EXISTS idx_audit_logs_severity   ON audit_logs(severity);
@@ -0,0 +1,4 @@
 -- Seed the default tenant.
 -- Uses INSERT OR IGNORE so re-running migrations is safe.
 INSERT OR IGNORE INTO tenants (id, name, slug, enabled)
 VALUES ('00000000-0000-0000-0000-000000000001', 'Default', 'default', 1);
@@ -0,0 +1,35 @@
 -- ── Roles ────────────────────────────────────────────────────────────────────
 INSERT OR IGNORE INTO roles (id, name, description) VALUES
    ('10000000-0000-0000-0000-000000000001', 'admin',  'Full system access'),
    ('10000000-0000-0000-0000-000000000002', 'editor', 'Can manage content and users'),
    ('10000000-0000-0000-0000-000000000003', 'viewer', 'Read-only access');
 -- ── Permissions ───────────────────────────────────────────────────────────────
 INSERT OR IGNORE INTO permissions (id, name, description) VALUES
    ('20000000-0000-0000-0000-000000000001', 'users:create',  'Create new user accounts'),
    ('20000000-0000-0000-0000-000000000002', 'users:update',  'Update user accounts'),
    ('20000000-0000-0000-0000-000000000003', 'users:delete',  'Disable user accounts'),
    ('20000000-0000-0000-0000-000000000004', 'tokens:create', 'Create API tokens for any user'),
    ('20000000-0000-0000-0000-000000000005', 'tokens:revoke', 'Revoke API tokens for any user'),
    ('20000000-0000-0000-0000-000000000006', 'roles:manage',  'Assign and revoke roles'),
    ('20000000-0000-0000-0000-000000000007', 'audit:view',    'View audit log entries');
 -- ── Admin role gets all permissions ──────────────────────────────────────────
 INSERT OR IGNORE INTO role_permissions (role_id, permission_id)
 SELECT '10000000-0000-0000-0000-000000000001', id FROM permissions;
 -- ── Editor role permissions ───────────────────────────────────────────────────
 INSERT OR IGNORE INTO role_permissions (role_id, permission_id) VALUES
    ('10000000-0000-0000-0000-000000000002', '20000000-0000-0000-0000-000000000001'),
    ('10000000-0000-0000-0000-000000000002', '20000000-0000-0000-0000-000000000002');
 -- ── Default applications ──────────────────────────────────────────────────────
 INSERT OR IGNORE INTO applications (id, tenant_id, name, slug, enabled) VALUES
    ('30000000-0000-0000-0000-000000000001', '00000000-0000-0000-0000-000000000001', 'BZOD',         'bzod',         1),
    ('30000000-0000-0000-0000-000000000002', '00000000-0000-0000-0000-000000000001', 'ChronoSeal',   'chronoseal',   1),
    ('30000000-0000-0000-0000-000000000003', '00000000-0000-0000-0000-000000000001', 'nx9-dns',      'nx9-dns',      1);
@@ -0,0 +1,12 @@
 -- Opaque refresh tokens issued at login (hashed at rest with BLAKE3).
 CREATE TABLE IF NOT EXISTS refresh_tokens (
    id          TEXT    PRIMARY KEY NOT NULL,
    user_id     TEXT    NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    token_hash  TEXT    NOT NULL UNIQUE,
    expires_at  TEXT    NOT NULL,
    revoked     INTEGER NOT NULL DEFAULT 0,
    created_at  TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\'))
 );
 CREATE INDEX IF NOT EXISTS idx_refresh_tokens_user ON refresh_tokens(user_id);
 CREATE INDEX IF NOT EXISTS idx_refresh_tokens_hash ON refresh_tokens(token_hash);
@@ -0,0 +1,50 @@
 -- nx9-auth: Global Slugs implementation
 -- A unified registry for slugs across all resources (tenant, user, group, role, app, etc.)
 -- Ensures global uniqueness and immutable references.
 CREATE TABLE IF NOT EXISTS global_slugs (
    slug            TEXT    PRIMARY KEY NOT NULL,
    entity_type     TEXT    NOT NULL, -- 'tenant', 'user', 'role', 'group', 'permission', 'application', 'service_account', 'organization', 'team'
    entity_id       TEXT    NOT NULL,
    tenant_id       TEXT    NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
    created_at      TEXT    NOT NULL DEFAULT (to_char(clock_timestamp() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z\'))
 );
 CREATE INDEX IF NOT EXISTS idx_global_slugs_entity ON global_slugs(entity_type, entity_id);
 CREATE INDEX IF NOT EXISTS idx_global_slugs_tenant ON global_slugs(tenant_id);
 -- Add slug column to existing tables for quick lookup and joins
 ALTER TABLE tenants ADD COLUMN slug TEXT;
 ALTER TABLE users ADD COLUMN slug TEXT;
 ALTER TABLE roles ADD COLUMN slug TEXT;
 ALTER TABLE permissions ADD COLUMN slug TEXT;
 ALTER TABLE applications ADD COLUMN slug TEXT;
 ALTER TABLE service_accounts ADD COLUMN slug TEXT;
 -- We will backfill slugs in Rust on startup or through a data migration script, 
 -- or we can backfill basic ones here:
 UPDATE tenants SET slug = lower(replace(name, ' ', '-')) WHERE slug IS NULL;
 UPDATE users SET slug = lower(username) WHERE slug IS NULL;
 UPDATE roles SET slug = lower(replace(name, ' ', '-')) WHERE slug IS NULL;
 UPDATE permissions SET slug = lower(replace(name, ' ', '-')) WHERE slug IS NULL;
 UPDATE applications SET slug = lower(replace(name, ' ', '-')) WHERE slug IS NULL;
 UPDATE service_accounts SET slug = lower(replace(name, ' ', '-')) WHERE slug IS NULL;
 -- Insert the backfilled slugs into the registry
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'tenant', id, id FROM tenants WHERE slug IS NOT NULL;
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'user', id, tenant_id FROM users WHERE slug IS NOT NULL;
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'role', id, tenant_id FROM roles WHERE slug IS NOT NULL;
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'permission', id, tenant_id FROM permissions WHERE slug IS NOT NULL;
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'application', id, tenant_id FROM applications WHERE slug IS NOT NULL;
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'service_account', id, tenant_id FROM service_accounts WHERE slug IS NOT NULL;
@@ -0,0 +1,10 @@
 CREATE TABLE IF NOT EXISTS tenants (
    id          TEXT    PRIMARY KEY NOT NULL,
    name        TEXT    NOT NULL,
    slug        TEXT    NOT NULL UNIQUE,
    enabled     INTEGER NOT NULL DEFAULT 1,
    created_at  TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    updated_at  TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
 );
 CREATE INDEX IF NOT EXISTS idx_tenants_slug ON tenants(slug);
@@ -0,0 +1,16 @@
 CREATE TABLE IF NOT EXISTS users (
    id              TEXT    PRIMARY KEY NOT NULL,
    tenant_id       TEXT    NOT NULL REFERENCES tenants(id) ON DELETE RESTRICT,
    username        TEXT    NOT NULL,
    password_hash   TEXT    NOT NULL,
    -- 1 = active, 2 = disabled, 3 = locked
    status          INTEGER NOT NULL DEFAULT 1,
    last_login_at   TEXT,
    created_at      TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    updated_at      TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    UNIQUE (tenant_id, username)
 );
 CREATE INDEX IF NOT EXISTS idx_users_username  ON users(username);
 CREATE INDEX IF NOT EXISTS idx_users_tenant_id ON users(tenant_id);
 CREATE INDEX IF NOT EXISTS idx_users_status    ON users(status);
@@ -0,0 +1,7 @@
 CREATE TABLE IF NOT EXISTS user_profiles (
    user_id       TEXT PRIMARY KEY NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    email         TEXT,
    full_name     TEXT,
    avatar_url    TEXT,
    metadata_json TEXT
 );
@@ -0,0 +1,5 @@
 CREATE TABLE IF NOT EXISTS roles (
    id          TEXT PRIMARY KEY NOT NULL,
    name        TEXT NOT NULL UNIQUE,
    description TEXT
 );
@@ -0,0 +1,5 @@
 CREATE TABLE IF NOT EXISTS permissions (
    id          TEXT PRIMARY KEY NOT NULL,
    name        TEXT NOT NULL UNIQUE,
    description TEXT
 );
@@ -0,0 +1,7 @@
 CREATE TABLE IF NOT EXISTS role_permissions (
    role_id       TEXT NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    permission_id TEXT NOT NULL REFERENCES permissions(id) ON DELETE CASCADE,
    PRIMARY KEY (role_id, permission_id)
 );
 CREATE INDEX IF NOT EXISTS idx_role_permissions_role ON role_permissions(role_id);
@@ -0,0 +1,7 @@
 CREATE TABLE IF NOT EXISTS user_roles (
    user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    role_id TEXT NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    PRIMARY KEY (user_id, role_id)
 );
 CREATE INDEX IF NOT EXISTS idx_user_roles_user ON user_roles(user_id);
@@ -0,0 +1,15 @@
 CREATE TABLE IF NOT EXISTS sessions (
    id           TEXT    PRIMARY KEY NOT NULL,
    user_id      TEXT    NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    token_hash   TEXT    NOT NULL UNIQUE,
    ip_address   TEXT,
    user_agent   TEXT,
    created_at   TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    expires_at   TEXT    NOT NULL,
    last_seen_at TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    revoked      INTEGER NOT NULL DEFAULT 0
 );
 CREATE INDEX IF NOT EXISTS idx_sessions_user_id    ON sessions(user_id);
 CREATE INDEX IF NOT EXISTS idx_sessions_token_hash ON sessions(token_hash);
 CREATE INDEX IF NOT EXISTS idx_sessions_expires_at ON sessions(expires_at);
@@ -0,0 +1,13 @@
 CREATE TABLE IF NOT EXISTS api_tokens (
    id           TEXT    PRIMARY KEY NOT NULL,
    user_id      TEXT    NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    name         TEXT    NOT NULL,
    token_hash   TEXT    NOT NULL UNIQUE,
    last_used_at TEXT,
    expires_at   TEXT,
    created_at   TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    revoked      INTEGER NOT NULL DEFAULT 0
 );
 CREATE INDEX IF NOT EXISTS idx_api_tokens_user_id    ON api_tokens(user_id);
 CREATE INDEX IF NOT EXISTS idx_api_tokens_token_hash ON api_tokens(token_hash);
@@ -0,0 +1,12 @@
 CREATE TABLE IF NOT EXISTS service_accounts (
    id          TEXT    PRIMARY KEY NOT NULL,
    tenant_id   TEXT    NOT NULL REFERENCES tenants(id) ON DELETE RESTRICT,
    name        TEXT    NOT NULL,
    description TEXT,
    enabled     INTEGER NOT NULL DEFAULT 1,
    created_at  TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    updated_at  TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    UNIQUE (tenant_id, name)
 );
 CREATE INDEX IF NOT EXISTS idx_service_accounts_tenant ON service_accounts(tenant_id);
@@ -0,0 +1,12 @@
 CREATE TABLE IF NOT EXISTS applications (
    id          TEXT    PRIMARY KEY NOT NULL,
    tenant_id   TEXT    NOT NULL REFERENCES tenants(id) ON DELETE RESTRICT,
    name        TEXT    NOT NULL,
    slug        TEXT    NOT NULL UNIQUE,
    enabled     INTEGER NOT NULL DEFAULT 1,
    created_at  TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    updated_at  TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
 );
 CREATE INDEX IF NOT EXISTS idx_applications_tenant ON applications(tenant_id);
 CREATE INDEX IF NOT EXISTS idx_applications_slug   ON applications(slug);
@@ -0,0 +1,20 @@
 CREATE TABLE IF NOT EXISTS audit_logs (
    id              TEXT PRIMARY KEY NOT NULL,
    actor_user_id   TEXT REFERENCES users(id) ON DELETE SET NULL,
    target_user_id  TEXT REFERENCES users(id) ON DELETE SET NULL,
    action          TEXT NOT NULL,
    resource_type   TEXT NOT NULL,
    resource_id     TEXT,
    -- 'info', 'warning', 'critical'
    severity        TEXT NOT NULL DEFAULT 'info',
    ip_address      TEXT,
    user_agent      TEXT,
    metadata_json   TEXT,
    created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
 );
 CREATE INDEX IF NOT EXISTS idx_audit_logs_actor      ON audit_logs(actor_user_id);
 CREATE INDEX IF NOT EXISTS idx_audit_logs_target     ON audit_logs(target_user_id);
 CREATE INDEX IF NOT EXISTS idx_audit_logs_action     ON audit_logs(action);
 CREATE INDEX IF NOT EXISTS idx_audit_logs_created_at ON audit_logs(created_at);
 CREATE INDEX IF NOT EXISTS idx_audit_logs_severity   ON audit_logs(severity);
@@ -0,0 +1,4 @@
 -- Seed the default tenant.
 -- Uses INSERT OR IGNORE so re-running migrations is safe.
 INSERT OR IGNORE INTO tenants (id, name, slug, enabled)
 VALUES ('00000000-0000-0000-0000-000000000001', 'Default', 'default', 1);
@@ -0,0 +1,35 @@
 -- ── Roles ────────────────────────────────────────────────────────────────────
 INSERT OR IGNORE INTO roles (id, name, description) VALUES
    ('10000000-0000-0000-0000-000000000001', 'admin',  'Full system access'),
    ('10000000-0000-0000-0000-000000000002', 'editor', 'Can manage content and users'),
    ('10000000-0000-0000-0000-000000000003', 'viewer', 'Read-only access');
 -- ── Permissions ───────────────────────────────────────────────────────────────
 INSERT OR IGNORE INTO permissions (id, name, description) VALUES
    ('20000000-0000-0000-0000-000000000001', 'users:create',  'Create new user accounts'),
    ('20000000-0000-0000-0000-000000000002', 'users:update',  'Update user accounts'),
    ('20000000-0000-0000-0000-000000000003', 'users:delete',  'Disable user accounts'),
    ('20000000-0000-0000-0000-000000000004', 'tokens:create', 'Create API tokens for any user'),
    ('20000000-0000-0000-0000-000000000005', 'tokens:revoke', 'Revoke API tokens for any user'),
    ('20000000-0000-0000-0000-000000000006', 'roles:manage',  'Assign and revoke roles'),
    ('20000000-0000-0000-0000-000000000007', 'audit:view',    'View audit log entries');
 -- ── Admin role gets all permissions ──────────────────────────────────────────
 INSERT OR IGNORE INTO role_permissions (role_id, permission_id)
 SELECT '10000000-0000-0000-0000-000000000001', id FROM permissions;
 -- ── Editor role permissions ───────────────────────────────────────────────────
 INSERT OR IGNORE INTO role_permissions (role_id, permission_id) VALUES
    ('10000000-0000-0000-0000-000000000002', '20000000-0000-0000-0000-000000000001'),
    ('10000000-0000-0000-0000-000000000002', '20000000-0000-0000-0000-000000000002');
 -- ── Default applications ──────────────────────────────────────────────────────
 INSERT OR IGNORE INTO applications (id, tenant_id, name, slug, enabled) VALUES
    ('30000000-0000-0000-0000-000000000001', '00000000-0000-0000-0000-000000000001', 'BZOD',         'bzod',         1),
    ('30000000-0000-0000-0000-000000000002', '00000000-0000-0000-0000-000000000001', 'ChronoSeal',   'chronoseal',   1),
    ('30000000-0000-0000-0000-000000000003', '00000000-0000-0000-0000-000000000001', 'nx9-dns',      'nx9-dns',      1);
@@ -0,0 +1,12 @@
 -- Opaque refresh tokens issued at login (hashed at rest with BLAKE3).
 CREATE TABLE IF NOT EXISTS refresh_tokens (
    id          TEXT    PRIMARY KEY NOT NULL,
    user_id     TEXT    NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    token_hash  TEXT    NOT NULL UNIQUE,
    expires_at  TEXT    NOT NULL,
    revoked     INTEGER NOT NULL DEFAULT 0,
    created_at  TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
 );
 CREATE INDEX IF NOT EXISTS idx_refresh_tokens_user ON refresh_tokens(user_id);
 CREATE INDEX IF NOT EXISTS idx_refresh_tokens_hash ON refresh_tokens(token_hash);
@@ -0,0 +1,27 @@
 CREATE TABLE IF NOT EXISTS groups (
    id          TEXT    PRIMARY KEY NOT NULL,
    tenant_id   TEXT    NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
    name        TEXT    NOT NULL,
    description TEXT,
    created_at  TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    updated_at  TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    UNIQUE(tenant_id, name)
 );
 CREATE TABLE IF NOT EXISTS user_groups (
    user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    group_id    TEXT NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
    added_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    PRIMARY KEY (user_id, group_id)
 );
 CREATE TABLE IF NOT EXISTS group_roles (
    group_id    TEXT NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
    role_id     TEXT NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    added_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
    PRIMARY KEY (group_id, role_id)
 );
 CREATE INDEX IF NOT EXISTS idx_user_groups_user ON user_groups(user_id);
 CREATE INDEX IF NOT EXISTS idx_user_groups_group ON user_groups(group_id);
 CREATE INDEX IF NOT EXISTS idx_groups_tenant ON groups(tenant_id);
@@ -0,0 +1,50 @@
 -- nx9-auth: Global Slugs implementation
 -- A unified registry for slugs across all resources (tenant, user, group, role, app, etc.)
 -- Ensures global uniqueness and immutable references.
 CREATE TABLE IF NOT EXISTS global_slugs (
    slug            TEXT    PRIMARY KEY NOT NULL,
    entity_type     TEXT    NOT NULL, -- 'tenant', 'user', 'role', 'group', 'permission', 'application', 'service_account', 'organization', 'team'
    entity_id       TEXT    NOT NULL,
    tenant_id       TEXT    NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
    created_at      TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
 );
 CREATE INDEX IF NOT EXISTS idx_global_slugs_entity ON global_slugs(entity_type, entity_id);
 CREATE INDEX IF NOT EXISTS idx_global_slugs_tenant ON global_slugs(tenant_id);
 -- Add slug column to existing tables for quick lookup and joins
 -- ALTER TABLE tenants ADD COLUMN slug TEXT;
 ALTER TABLE users ADD COLUMN slug TEXT;
 ALTER TABLE roles ADD COLUMN slug TEXT;
 ALTER TABLE permissions ADD COLUMN slug TEXT;
 -- ALTER TABLE applications ADD COLUMN slug TEXT;
 ALTER TABLE service_accounts ADD COLUMN slug TEXT;
 -- We will backfill slugs in Rust on startup or through a data migration script, 
 -- or we can backfill basic ones here:
 UPDATE tenants SET slug = lower(replace(name, ' ', '-')) WHERE slug IS NULL;
 UPDATE users SET slug = lower(username) WHERE slug IS NULL;
 UPDATE roles SET slug = lower(replace(name, ' ', '-')) WHERE slug IS NULL;
 UPDATE permissions SET slug = lower(replace(name, ' ', '-')) WHERE slug IS NULL;
 UPDATE applications SET slug = lower(replace(name, ' ', '-')) WHERE slug IS NULL;
 UPDATE service_accounts SET slug = lower(replace(name, ' ', '-')) WHERE slug IS NULL;
 -- Insert the backfilled slugs into the registry
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'tenant', id, id FROM tenants WHERE slug IS NOT NULL;
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'user', id, tenant_id FROM users WHERE slug IS NOT NULL;
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'role', id, '00000000-0000-0000-0000-000000000001' FROM roles WHERE slug IS NOT NULL;
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'permission', id, '00000000-0000-0000-0000-000000000001' FROM permissions WHERE slug IS NOT NULL;
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'application', id, tenant_id FROM applications WHERE slug IS NOT NULL;
 INSERT OR IGNORE INTO global_slugs (slug, entity_type, entity_id, tenant_id)
 SELECT slug, 'service_account', id, tenant_id FROM service_accounts WHERE slug IS NOT NULL;
@@ -1,13 +1,63 @@
 use anyhow::{Context, Result};
 use std::sync::Arc;
 use std::time::Duration;
 pub mod models;
 pub mod provider;
 pub mod repository;
 use crate::config::{Config, DatabaseBackend};
 use crate::db::provider::DatabaseProvider;
 #[cfg(feature = "sqlite")]
 use sqlx::{SqlitePool, sqlite::SqlitePoolOptions};
-/// Create and configure the SQLite connection pool.
+#[cfg(feature = "postgres")]
-///
+use sqlx::postgres::PgPoolOptions;
-/// Enables WAL mode, foreign keys, and a busy timeout so concurrent writers
+
-/// do not immediately error — they back off and retry for up to 5 seconds.
+/// Database connection pool handle owned by the runtime for lifecycle
-pub async fn create_pool(path: &str) -> Result<SqlitePool> {
+/// management. Keeps `DatabaseProvider` and repository traits free of
-    // Ensure the parent directory exists
+/// lifecycle methods.
-    if let Some(parent) = std::path::Path::new(path).parent() {
+pub enum PoolHandle {
    #[cfg(feature = "sqlite")]
    Sqlite(SqlitePool),
    #[cfg(feature = "postgres")]
    Postgres(sqlx::PgPool),
 }
 impl PoolHandle {
    /// Close the connection pool, waiting for all borrowed connections
    /// to be returned. Active transactions will finish before the pool
    /// is fully closed.
    pub async fn close(&self) {
        match self {
            #[cfg(feature = "sqlite")]
            Self::Sqlite(pool) => {
                pool.close().await;
                tracing::info!("sqlite connection pool closed");
            }
            #[cfg(feature = "postgres")]
            Self::Postgres(pool) => {
                pool.close().await;
                tracing::info!("postgres connection pool closed");
            }
        }
    }
 }
 /// Initialize database connection pool, run migrations, and return the
 /// `DatabaseProvider`, detected backend, and a `PoolHandle` for the runtime
 /// to manage the pool lifecycle independently of the repositories.
 pub async fn init_provider(
    config: &Config,
 ) -> Result<(Arc<dyn DatabaseProvider>, DatabaseBackend, PoolHandle)> {
    let (url, backend) = config.database.resolved_url()?;
    match backend {
        #[cfg(feature = "sqlite")]
        DatabaseBackend::Sqlite => {
            let path = config.database.sqlite_path();
            if let Some(parent) = std::path::Path::new(&path).parent() {
                if !parent.as_os_str().is_empty() {
                    std::fs::create_dir_all(parent).with_context(|| {
                        format!("failed to create database directory: {}", parent.display())
@@ -15,54 +65,155 @@ pub async fn create_pool(path: &str) -> Result<SqlitePool> {
                }
            }
-    let url = format!("sqlite://{}?mode=rwc", path);
+            let max_conn = config.database.max_connections.unwrap_or(16);
            let min_conn = config.database.min_connections.unwrap_or(1);
            let mut opts = SqlitePoolOptions::new()
                .max_connections(max_conn)
                .min_connections(min_conn);
            if let Some(secs) = config.database.connect_timeout_secs {
                opts = opts.acquire_timeout(Duration::from_secs(secs));
            }
            if let Some(secs) = config.database.idle_timeout_secs {
                opts = opts.idle_timeout(Duration::from_secs(secs));
            }
            if let Some(secs) = config.database.max_lifetime_secs {
                opts = opts.max_lifetime(Duration::from_secs(secs));
            }
            let pool = opts
                .connect(&url)
                .await
                .with_context(|| format!("failed to open sqlite database: {url}"))?;
            sqlx::query("PRAGMA journal_mode = WAL")
                .execute(&pool)
                .await
                .context("PRAGMA journal_mode")?;
            sqlx::query("PRAGMA foreign_keys = ON")
                .execute(&pool)
                .await
                .context("PRAGMA foreign_keys")?;
            sqlx::query("PRAGMA busy_timeout = 5000")
                .execute(&pool)
                .await
                .context("PRAGMA busy_timeout")?;
            sqlx::query("PRAGMA synchronous = NORMAL")
                .execute(&pool)
                .await
                .context("PRAGMA synchronous")?;
            sqlx::migrate!("src/db/migrations/sqlite")
                .run(&pool)
                .await
                .context("failed to run sqlite migrations")?;
            tracing::info!(backend = "sqlite", url = %url, "sqlite database initialized");
            let pool_handle = PoolHandle::Sqlite(pool.clone());
            let provider = Arc::new(provider::SqliteProvider::new(pool));
            Ok((provider, DatabaseBackend::Sqlite, pool_handle))
        }
        #[cfg(feature = "postgres")]
        DatabaseBackend::Postgres => {
            let max_conn = config.database.max_connections.unwrap_or(16);
            let min_conn = config.database.min_connections.unwrap_or(1);
            let mut opts = PgPoolOptions::new()
                .max_connections(max_conn)
                .min_connections(min_conn);
            if let Some(secs) = config.database.connect_timeout_secs {
                opts = opts.acquire_timeout(Duration::from_secs(secs));
            }
            if let Some(secs) = config.database.idle_timeout_secs {
                opts = opts.idle_timeout(Duration::from_secs(secs));
            }
            if let Some(secs) = config.database.max_lifetime_secs {
                opts = opts.max_lifetime(Duration::from_secs(secs));
            }
            // Retry connection policy (5 attempts with exponential backoff)
            let mut attempts = 0;
            let mut wait_secs = 1u64;
            let pool = loop {
                match opts.clone().connect(&url).await {
                    Ok(p) => break p,
                    Err(err) => {
                        attempts += 1;
                        if attempts >= 5 {
                            anyhow::bail!(
                                "failed to connect to postgres database after {attempts} attempts: {err}"
                            );
                        }
                        tracing::warn!(
                            attempts,
                            wait_secs,
                            "postgres connection failed, retrying..."
                        );
                        tokio::time::sleep(Duration::from_secs(wait_secs)).await;
                        wait_secs = std::cmp::min(wait_secs * 2, 30);
                    }
                }
            };
            sqlx::migrate!("src/db/migrations/postgres")
                .run(&pool)
                .await
                .context("failed to run postgres migrations")?;
            tracing::info!(backend = "postgres", url = %url, "postgres database initialized");
            let pool_handle = PoolHandle::Postgres(pool.clone());
            let provider = Arc::new(provider::PostgresProvider::new(pool));
            Ok((provider, DatabaseBackend::Postgres, pool_handle))
        }
        #[allow(unreachable_patterns)]
        _ => anyhow::bail!("database backend '{backend}' feature is not enabled in this build"),
    }
 }
 /// Helper function to create an SQLite pool for legacy CLI commands or tests.
 #[cfg(feature = "sqlite")]
 pub async fn create_pool(path: &str) -> Result<SqlitePool> {
    if let Some(parent) = std::path::Path::new(path).parent() {
        if !parent.as_os_str().is_empty() {
            std::fs::create_dir_all(parent).with_context(|| {
                format!("failed to create database directory: {}", parent.display())
            })?;
        }
    }
    let url = if path.starts_with("sqlite://") {
        path.to_string()
    } else {
        format!("sqlite://{}?mode=rwc", path)
    };
    let pool = SqlitePoolOptions::new()
        .max_connections(16)
        .min_connections(1)
        .connect(&url)
        .await
-        .with_context(|| format!("failed to open database: {path}"))?;
+        .with_context(|| format!("failed to open sqlite database: {path}"))?;
    // Apply foundational PRAGMAs on every connection
    sqlx::query("PRAGMA journal_mode = WAL")
        .execute(&pool)
        .await
        .context("PRAGMA journal_mode")?;
    sqlx::query("PRAGMA foreign_keys = ON")
        .execute(&pool)
        .await
        .context("PRAGMA foreign_keys")?;
    sqlx::query("PRAGMA busy_timeout = 5000")
        .execute(&pool)
        .await
        .context("PRAGMA busy_timeout")?;
    sqlx::query("PRAGMA synchronous = NORMAL")
        .execute(&pool)
        .await
        .context("PRAGMA synchronous")?;
    sqlx::query("PRAGMA cache_size = -32768") // 32 MiB page cache
        .execute(&pool)
        .await
        .context("PRAGMA cache_size")?;
    tracing::info!(path = path, "database pool opened");
    Ok(pool)
 }
-/// Run all pending SQLx migrations embedded in `src/db/migrations/`.
+#[cfg(feature = "sqlite")]
 pub async fn run_migrations(pool: &SqlitePool) -> Result<()> {
-    sqlx::migrate!("src/db/migrations")
+    sqlx::migrate!("src/db/migrations/sqlite")
        .run(pool)
        .await
-        .context("failed to run database migrations")?;
+        .context("failed to run sqlite migrations")?;
    tracing::info!("database migrations applied");
    Ok(())
 }
 pub mod models;
 pub mod repository;
@@ -6,8 +6,11 @@ pub struct Application {
    pub id: String,
    pub tenant_id: String,
    pub name: String,
-    pub slug: String,
+    pub description: Option<String>,
    pub slug: Option<String>,
    pub enabled: bool,
    pub client_secret_hash: Option<String>,
    pub redirect_uris: Option<String>,
    pub created_at: String,
    pub updated_at: String,
 }
@@ -38,6 +38,20 @@ impl std::fmt::Display for AuditSeverity {
    }
 }
 /// Filtered audit log query. All filters are optional.
 #[derive(Debug, Default, Clone, Serialize, Deserialize)]
 pub struct AuditFilter {
    pub actor_user_id: Option<String>,
    pub action: Option<String>,
    pub resource_type: Option<String>,
    pub severity: Option<String>,
    pub since: Option<String>,
    pub until: Option<String>,
    pub search: Option<String>,
    pub limit: i64,
    pub offset: i64,
 }
 /// A row from the `audit_logs` table.
 #[derive(Debug, Clone, Serialize, Deserialize, FromRow)]
 pub struct AuditLog {
@@ -0,0 +1,12 @@
 use serde::{Deserialize, Serialize};
 use sqlx::FromRow;
 #[derive(Debug, Clone, Serialize, Deserialize, FromRow)]
 pub struct Group {
    pub id: String,
    pub tenant_id: String,
    pub name: String,
    pub description: Option<String>,
    pub created_at: String,
    pub updated_at: String,
 }
@@ -1,7 +1,9 @@
 pub mod api_token;
 pub mod application;
 pub mod audit_log;
 pub mod group;
 pub mod permission;
 pub mod refresh_token;
 pub mod role;
 pub mod service_account;
 pub mod session;
@@ -10,11 +12,13 @@ pub mod user;
 pub use api_token::ApiToken;
 pub use application::Application;
-pub use audit_log::{AuditLog, AuditSeverity};
+pub use audit_log::{AuditFilter, AuditLog, AuditSeverity};
 pub use group::Group;
 #[allow(unused_imports)]
 pub use permission::Permission;
 pub use refresh_token::RefreshToken;
 pub use role::Role;
 pub use service_account::ServiceAccount;
 pub use session::Session;
 pub use tenant::Tenant;
-pub use user::{User, UserStatus};
+pub use user::{User, UserProfile, UserStatus};
@@ -3,6 +3,7 @@ use sqlx::FromRow;
 #[derive(Debug, Clone, Serialize, Deserialize, FromRow)]
 pub struct Permission {
    pub slug: Option<String>,
    pub id: String,
    pub name: String,
    pub description: Option<String>,
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
thakares	d93f2cef95	Release: NX9-Auth v0.3.0	2026-07-22 19:36:22 +05:30
thakares	6a04d7f793	WIP: recover runtime implementation after accidental git clean	2026-07-22 14:09:05 +05:30
thakares	5abbf5123e	chore: clean repository and add documentation screenshots	2026-07-21 16:32:56 +05:30
thakares	71e1e4ee6b	chore: clean repository and add documentation screenshots	2026-07-21 16:29:34 +05:30
thakares	ce3bff5097	README: Updated to v0.2.0, with UI/UX implementation, phase 0	2026-07-21 15:47:13 +05:30
thakares	7b7797cf7f	Update README to simplify service description Removed reference to the NX9 ecosystem from the description.	2026-07-21 15:47:13 +05:30
thakares	034f0747e0	chore: remove temporary development scripts	2026-07-21 15:39:24 +05:30
thakares	c2f5ba3f54	feat: complete Phase 0 Enterprise IAM	2026-07-21 15:26:16 +05:30
thakares	3d2d291006	ci: install rustfmt and clippy components	2026-06-21 20:22:06 +05:30
thakares	b8c177bdbe	fix: clean gitignore	2026-06-21 20:12:48 +05:30