aegis-plugin-sdk 0.1.1

# Aegis

## Open-Source Multi-Tenant API Gateway with Self-Service Dashboard

[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://www.rust-lang.org/)
[![React](https://img.shields.io/badge/react-19-blue.svg)](https://reactjs.org/)

### Overview

Aegis is an open-source, high-performance API gateway designed for multi-tenant SaaS applications. Built on OpenResty with a Rust admin backend and React dashboard, it enables SaaS companies to register applications, manage API keys, and protect their APIs with authentication, RBAC, and rate limiting.

### Why Aegis?

There are many excellent API gateways available. Here's an honest comparison to help you decide:

#### How Aegis Compares

| Feature | Aegis | Kong | AWS API Gateway | Traefik |
|---------|-------|------|-----------------|---------|
| **Self-hosted** | Yes | Yes | No (AWS only) | Yes |
| **Open source** | AGPL-3.0 | Apache 2.0 | N/A | Apache 2.0 |
| **Admin UI included** | Yes (free) | Enterprise only ($$$) | AWS Console | No built-in |
| **Multi-tenant RBAC** | Built-in | Plugin | Lambda Authorizer | ForwardAuth |
| **External auth callout** | Subrequest | Custom plugin | Lambda Authorizer | ForwardAuth |
| **Pricing** | Free | Free/Enterprise | Per-request | Free |
| **Cold start latency** | None (Lua) | None | Lambda cold starts | None |
| **Setup complexity** | Docker Compose | Kubernetes preferred | AWS ecosystem | Docker/K8s |

#### When to Choose Aegis

**Choose Aegis if you want:**
- Self-hosted solution with no vendor lock-in
- Built-in admin dashboard without enterprise pricing
- Simple Docker Compose deployment
- Multi-tenant SaaS with per-tenant isolation
- Low latency without cold starts

**Choose alternatives if you need:**
- Enterprise support contracts (Kong Enterprise)
- Deep AWS ecosystem integration (AWS API Gateway)
- Kubernetes-native service mesh (Traefik, Envoy)
- Production-proven at massive scale (Kong, AWS)

#### Feature Parity

To be clear: features like external authorization callouts, multi-tenancy, and RBAC are available in other gateways:
- **Kong**: [Custom Auth Plugins](https://docs.konghq.com/gateway/latest/plugin-development/)
- **AWS**: [Lambda Authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)
- **Traefik**: [ForwardAuth Middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/)

Aegis provides these capabilities in a simpler, self-contained package with a free admin UI.

### Architecture

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Admin Frontend │────▶│  Admin Service  │────▶│   PostgreSQL    │
│  (React/Vite)   │     │  (Rust/Axum)    │     │                 │
│  :5173          │     │  :3001          │     │  :5434          │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                                 ▼
┌─────────────────┐     ┌─────────────────┐
│  Gateway Core   │────▶│     Redis       │
│  (OpenResty)    │     │  :7979          │
│  :8000          │     └─────────────────┘
└─────────────────┘
```

### Features

#### Self-Service Dashboard
- Customer registration with email verification
- SaaS application management
- API key generation (production/staging/development)
- SSL certificate provisioning (Let's Encrypt ACME)
- Usage analytics and billing

#### Gateway Core
- Sub-2ms latency with OpenResty/Lua
- JWT validation with tenant context
- Hierarchical RBAC with Redis caching
- Subrequest fallback to backend for dynamic auth
- Rate limiting (fixed window, sliding window, token bucket, leaky bucket)
- Hot-reload configuration

#### Add-on Marketplace
- Heroku-style add-on provisioning
- Provider API for third-party integrations
- Revenue sharing (70/30 split)
- SSO for add-on dashboards
- Usage-based billing support

#### CLI Tool (aegis-cli)
- Customer management
- Cache operations (health, warm, invalidate)
- Platform metrics
- SSL certificate management
- Gateway health checks

#### Multi-Tenancy
- Complete tenant data isolation
- Per-tenant resource quotas
- Tenant-aware RBAC permissions
- Subrequest authorization for dynamic access control

## Quick Start

#### Prerequisites
- Docker & Docker Compose
- Rust (latest stable)
- Node.js 18+

#### Installation

```bash
# Clone the repository
git clone https://github.com/your-org/aegis.git
cd aegis

# Start infrastructure (PostgreSQL, Redis)
docker-compose -f docker-compose.dev.yml up -d

# Start backend
cd admin-service
DATABASE_URL="postgresql://aegis_user:aegis_password@localhost:5434/aegis" \
REDIS_URL="redis://localhost:7979" \
JWT_SECRET="your-secret-key" \
cargo run

# Start frontend (in another terminal)
cd admin-frontend
npm install
npm run dev
```

#### Try the Sample App

We include a sample multi-tenant backend to demonstrate Aegis features:

```bash
cd sample-backend
npm install
npm start
```

See [sample-backend/GETTING_STARTED.md](sample-backend/GETTING_STARTED.md) for the full walkthrough.

#### Access Points

| Service | URL |
|---------|-----|
| Dashboard | http://localhost:5173 |
| Admin API | http://localhost:3001 |
| Gateway | http://localhost:8000 |
| Sample Backend | http://localhost:4000 |

---

### Author

Created by **Ken C. Demanawa** ([@kanutocd](https://github.com/kanutocd))

See [AUTHORS](AUTHORS) for all contributors.

---

*Aegis: Open-source API gateway for multi-tenant SaaS applications*

*Built with purpose. Shared with love. Made to last.*