Aegis

Self-hosted identity server. OIDC, email auth, sessions.
Rust · SQLite · Authorization Code + PKCE · RS256

Docs · Quick Start · Examples

---

Aegis is a modular identity monolith for developers who want a self-hosted auth environment without external dependencies like SMTP, Redis, Kubernetes, or SaaS providers. It provides a full hosted login, a local mailbox, a management console, and an OAuth Playground to inspect every protocol step.

Quick start

Requirements: Rust 1.85+ and Node.js 22+.

cd console
npm install
npm run build
cd ..

cargo run -- init --name pulse --defaults
cargo run -- dev

You now have a local identity server running on port 4000. Access the Console, Mailbox, and Playground. Create an account, verify the email in the Mailbox, sign in, and run the OAuth flow in the Playground.

Configuration

Authentication state is defined in aegis.yaml:

version: "1"
project:
  name: pulse

server:
  issuer: http://localhost:4000
  bind: 127.0.0.1
  port: 4000

applications:
  - id: web
    name: Pulse
    type: web
    redirect_uris:
      - http://localhost:4000/playground/callback

CLI Commands

Command	Description
aegis validate	Validate the aegis.yaml configuration.
aegis diff	Show changes between the current config and the database.
aegis apply	Apply configuration changes to the database.
aegis doctor	Check system requirements and data integrity.
aegis migrate	Run database schema migrations.
aegis dev	Start the development server (with Mailbox/Playground).
aegis serve	Start the production server.

What's in v0.1

• Hosted login, registration, email verification, and session management.
• Argon2id password hashing and opaque server-side sessions.
• OIDC discovery, JWKS, Authorization Code flow with S256 PKCE.
• Atomic refresh-token rotation and replay detection.
• Strict redirect matching, rate limiting, and CSRF protection.
• Built-in SQLite storage and a local mailbox.
• Visual OAuth trace and security simulator via the Playground.
• Opaque public IDs (usr_, ses_, app_, evt_, req_).
• Single Rust binary with embedded web assets and migrations.

OIDC integration

Aegis integrates with standard OpenID Connect clients.

issuer:       http://localhost:4000
client_id:    app_web
redirect_uri: http://localhost:4000/playground/callback
flow:         authorization_code
PKCE:         S256 (required)
scopes:       openid profile email offline_access

Docker

Run the self-contained development environment via Docker Compose:

docker compose -f deploy/docker/docker-compose.yml up --build

Architecture

                       HTTP
                        │
                 Axum router / API
                        │
       ┌────────────────┼────────────────┐
       │                │                │
    Identity          OAuth           Console
       │          codes / tokens    mailbox / trace
       └────────────────┼────────────────┘
                        │
                 Sessions + Audit
                        │
                      SQLite

See the Architecture, API reference, and Threat model.

Security

Aegis v0.1 is intended for local development and evaluation. It has not received an independent security audit. Do not expose aegis dev to untrusted traffic. See SECURITY.md for details.

Development

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cd console && npm run build

See CONTRIBUTING.md.

License

Licensed under the Apache License 2.0.