aegis-server

REST API server for the Aegis Database Platform.

Overview

aegis-server provides the HTTP API layer built on Axum, featuring authentication, authorization, and endpoints for all database operations. It serves both the programmatic API and the web dashboard backend.

Features

• REST API - Full CRUD operations for all data paradigms
• TLS/HTTPS - Native TLS support with certificate-based encryption
• Authentication - Username/password (Argon2id), MFA, LDAP, OAuth2/OIDC
• Authorization - Role-based access control (RBAC)
• Rate Limiting - Token bucket rate limiting for API protection
• Secrets Management - HashiCorp Vault integration
• Audit Logging - Comprehensive activity tracking
• Admin API - Cluster management and monitoring
• Bulk Import - CSV/JSON bulk data import via import.rs
• VACUUM - Storage reclamation and index rebuild endpoint
• PHI Classification - Column-level data classification endpoints
• Query Safety Limits - Configurable max result rows and query timeouts
• Log Rotation - Automatic log file rotation and retention

Architecture

┌─────────────────────────────────────────────┐
│                HTTP Server                  │
│                  (Axum)                     │
├─────────────────────────────────────────────┤
│              Middleware Layer               │
│  ┌─────────┬──────────┬─────────────────┐  │
│  │  Auth   │  Logging │  Rate Limiting  │  │
│  └─────────┴──────────┴─────────────────┘  │
├─────────────────────────────────────────────┤
│               Route Handlers                │
│  ┌───────┬───────┬────────┬────────────┐   │
│  │ Query │  KV   │  Docs  │   Admin    │   │
│  └───────┴───────┴────────┴────────────┘   │
├─────────────────────────────────────────────┤
│            Application State                │
│         (Storage, Config, Auth)             │
└─────────────────────────────────────────────┘

Modules

API Endpoints

Core

Authentication

Key-Value Store

Documents

Bulk Import

VACUUM & Maintenance

PHI Classification

Admin

Usage

Running the Server

# Using the CLI
aegis server start

# Or directly with cargo
cargo run -p aegis-server -- --port 9090

# With custom host
cargo run -p aegis-server -- --host 0.0.0.0 --port 9090

Command-Line Options

aegis-server [OPTIONS]

Options:
  -H, --host <HOST>        Host to bind to [default: 127.0.0.1]
  -p, --port <PORT>        Port to listen on [default: 9090]
  -d, --data-dir <DIR>     Data directory for persistence
      --node-id <ID>       Unique node ID
      --node-name <NAME>   Node display name
      --peers <PEERS>      Comma-separated peer addresses
      --cluster <NAME>     Cluster name [default: aegis-cluster]
      --tls                Enable TLS/HTTPS
      --tls-cert <PATH>    TLS certificate file (PEM)
      --tls-key <PATH>     TLS private key file (PEM)
  -h, --help               Print help

TLS/HTTPS Mode

# With command-line arguments
cargo run -p aegis-server -- --tls --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

# With environment variables
export AEGIS_TLS_CERT=/path/to/cert.pem
export AEGIS_TLS_KEY=/path/to/key.pem
cargo run -p aegis-server -- --tls

Configuration

[server]
host = "127.0.0.1"
port = 9090
max_connections = 1000
request_timeout = "30s"

[auth]
method = "local"           # local, ldap, oauth2
session_timeout = "30m"
mfa_required = false

[tls]
enabled = true
cert_file = "/etc/aegis/tls.crt"
key_file = "/etc/aegis/tls.key"

[rate_limit]
requests_per_minute = 1000
login_requests_per_minute = 30

Environment Variables

HashiCorp Vault Integration

For enterprise secrets management, the server integrates with HashiCorp Vault:

# Configure Vault
export VAULT_ADDR=https://vault.example.com:8200
export VAULT_TOKEN=hvs.your-token

# Secrets are read from: secret/data/aegis/*
# Falls back to environment variables if Vault unavailable

Authentication

Configuring Credentials

Set credentials via environment variables before starting the server:

export AEGIS_ADMIN_USERNAME=your_admin_username
export AEGIS_ADMIN_PASSWORD=your_secure_password

Local Authentication

curl -X POST http://localhost:9090/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "$AEGIS_ADMIN_USERNAME", "password": "$AEGIS_ADMIN_PASSWORD"}'

Using the Token

curl http://localhost:9090/api/v1/admin/cluster \
  -H "Authorization: Bearer <token>"

Security Features

Password Hashing

Passwords are hashed using Argon2id with:

• Memory cost: 19 MiB
• Time cost: 2 iterations
• Parallelism: 1
• Unique random salt per password

Rate Limiting

Token bucket algorithm protects against brute force:

• Login endpoints: 30 requests/minute/IP
• General API: 1000 requests/minute/IP

Session Tokens

Secure random tokens generated using rand::thread_rng() with cryptographically secure random number generation.

Tests

cargo test -p aegis-server

Test count: 634 tests (workspace total)

License

Business Source License 1.1 (BSL) - See LICENSE for details.