Getting Started

This guide walks you through building AuthNexus from source, completing first-run PKI initialization, launching the core services, and verifying the setup with the admin frontend and SDK demo.

Prerequisites

Compiler & Toolchain

Requirement	Minimum Version
C++ Standard	C++23
MSVC (Windows)	Visual Studio 2022 17.8+
GCC (Linux)	13+
CMake	3.25+
Node.js	18+ (for admin frontend & website)

System Libraries

• OpenSSL 3.x -- TLS, certificate operations, and HMAC hashing.
• libpq + libpqxx -- required only when building with PostgreSQL support.
• Lua 5.4 -- embedded for cloud function execution.

On Windows, the project uses static MSVC runtime linking (/MT / /MTd). MSVC flags include /W4 /permissive- /utf-8.

Building from Source

Configure

# Clone and enter the repository
git clone https://github.com/AuroraEchos/AuthNexus.git
cd AuthNexus

# Configure (first time or after CMakeLists.txt changes)
cmake -B build -S .

Compile

# Release build (recommended parallel flag)
cmake --build build --config Release --parallel 16

# Debug build
cmake --build build --config Debug --parallel 16

# Build a single target
cmake --build build --config Release --target control_plane_app --parallel 16

Key build targets:

Target	Description
control_plane_app	Unified admin + control plane process
server_app	Business TCP node (mTLS)
unit_tests	GoogleTest test binary
benchmark_app	SDK-level load testing
sdk_demo	Minimal SDK integration example

All binaries are output to build/bin/<Config>/. The schema/ directory is automatically copied next to the binaries via a POST_BUILD step.

Running Tests

# Full test suite
ctest --test-dir build -C Release --output-on-failure

# Filter by test name (regex)
ctest --test-dir build -C Release --output-on-failure -R "PasswordHasher|CloudFunction"

# Run the binary directly (useful for debugging)
.\build\bin\Release\unit_tests.exe --gtest_filter=PasswordHasher.*

PostgreSQL Tests

PostgreSQL tests require connection environment variables. Without them, PG-specific tests are skipped automatically.

$env:AUTHNEXUS_TEST_PG_HOST = "localhost"
$env:AUTHNEXUS_TEST_PG_PORT = "5432"
$env:AUTHNEXUS_TEST_PG_USER = "postgres"
$env:AUTHNEXUS_TEST_PG_PASSWORD = "your_password"

ctest --test-dir build -C Release --output-on-failure -R "PgDBTest"

First Run -- Control Plane

The Control Plane must be started first. On its initial launch, it enters setup-only mode: the /cp/* southbound endpoints are not served until PKI initialization is complete.

.\build\bin\Release\control_plane_app.exe --auto

By default, the admin HTTP API listens on 127.0.0.1:9090 (loopback only). The CP southbound interface listens on 0.0.0.0:9091 (for remote node access).

On first startup the console prints a one-time setup token. Save this token -- it is required to complete the web-based setup wizard.

PKI Initialization (Setup Wizard)

Open the admin frontend (see below) and navigate to the setup wizard at /admin/v1/setup/status. The wizard guides you through:

1. Root admin creation -- establish the platform administrator account.
2. CA bootstrap -- initialize the four independent Certificate Authorities:
   • cp_server_ca -- Control Plane server certificate
   • cp_node_client_ca -- Node-to-CP client certificate
   • tcp_server_ca -- Business TCP server certificate
   • app_client_ca -- SDK / application client certificate

Until all four CAs are initialized, the Control Plane remains in setup-only mode and will not serve /cp/* endpoints.

First Run -- Server Node

After the Control Plane is ready and a node has been created via the admin UI (which generates a node_agent.json deployment package):

.\build\bin\Release\server_app.exe --auto --node-agent node_agent.json

The server binds to 0.0.0.0:8080 by default for client TCP connections (TLS 1.3 + mTLS). The --auto flag selects thread counts based on CPU core count.

The server will not open its business TLS port until the CP Agent has successfully connected and applied critical configurations (fail-closed startup).

Admin Frontend

cd src\admin_frontend
npm install
npm run dev    # http://localhost:3000

The Vite dev server proxies /admin/v1 and /cp requests to localhost:9090.

Demo Mode (No Backend Required)

npm run dev:demo    # MSW intercepts all API calls in-browser

Demo mode uses MSW (Mock Service Worker) to intercept requests at /admin/v1 within the browser. No backend process is needed. Mock handlers live in src/admin_frontend/src/mocks/handlers/.

Production Build

npm run build       # Outputs to dist/
npm run build:demo  # Outputs to dist-demo/ (for embedding in the website)

SDK Demo

After building, the sdk_demo binary provides a minimal integration example:

.\build\bin\Release\sdk_demo.exe

The SDK demo requires a running server_app with valid mTLS certificates. See SDK Integration for detailed integration steps.

Website (Marketing & Docs)

cd src\website
npm install
npm run dev              # http://localhost:5173
npm run build:with-demo  # Joint build including /demo/ sub-path

The dev server middleware routes /demo/* to the admin frontend demo build for a self-contained static site.

Directory Structure Overview

AuthNexus/
  build/bin/<Config>/     # Compiled binaries + schema/
  schema/                 # SQLite & PostgreSQL schema files
  src/
    control_plane/        # Control Plane process source
    server/               # Server node process source
    core/                 # Shared library (DB, protocol, TLS, etc.)
    sdk/                  # C++ client SDK
    admin_frontend/       # Vue 3 admin dashboard
    website/              # VitePress marketing site
  tests/                  # GoogleTest source (*_tests.cpp)
  docs/                   # Internal design documents

Next Steps

• System Architecture -- understand the three-process model
• TLS & PKI -- deep dive into the certificate infrastructure
• Deployment Guide -- production deployment checklist
• SDK Integration -- integrate AuthNexus into your application