API Gateway

The API Gateway is the single entry point for all client traffic in AEGIS. It is a Go reverse proxy that handles authentication, rate limiting, CORS, and request routing to the appropriate backend microservice.

Overview

Every request from the frontend (or any external client) passes through the API Gateway on port 8000 before reaching a backend service. The gateway validates the JWT (from the Authorization header or the aegis_token cookie), enforces rate limits, attaches CORS headers, and rewrites URL paths before proxying requests to the correct upstream service.

The gateway strips CORS headers from backend responses to ensure it is the single source of truth for cross-origin policy.

Port & Language

Middleware Stack

Requests pass through the middleware chain in this order:

Client Request → CORS → Rate Limiter → Auth → Route Handler → Backend Service

1. CORS Middleware

Adds permissive CORS headers to every response and short-circuits OPTIONS preflight requests with a 200 OK.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

Backend CORS headers are stripped by the reverse proxy’s ModifyResponse hook to prevent conflicts.

2. Rate Limiter

Per-client token bucket rate limiter using golang.org/x/time/rate:

• Rate: 100 requests per minute (~1.67 req/sec)
• Burst: 10 requests
• Key: authenticated user_id from context, or remote IP address as fallback

When the limit is exceeded, the gateway returns 429 Too Many Requests.

3. Auth Middleware

Validates the JWT and injects user_id and roles into the request context. Authentication is JWT only — the gateway no longer accepts the X-API-Key header.

Where the JWT is read from (in order):

1. Authorization: Bearer <token> header — the standard case for API clients.
2. aegis_token cookie — fallback for browser SSE/EventSource clients that cannot set headers.

The token is validated locally using HMAC-SHA256 with the JWT_SECRET environment variable. A missing or invalid token returns 401 Unauthorized.

Unauthenticated routes (auth skipped):

• /health
• /api/v1/auth/token
• /api/v1/entity-types*
• /api/v1/relationship-rules*
• /api/v1/relationship-types*

Routing Rules

The gateway maps public API paths (prefixed with /api/v1/) to internal service paths. Each upstream service is configured via environment variables with sensible localhost defaults.

Route Table

Role-Based Access Control

Some routes enforce role checks before proxying:

• /api/v1/admin/* — Requires the admin role. Returns 403 Forbidden otherwise.
• /api/v1/detection-rules* — Requires power_user or admin role.

Roles are extracted from the authenticated JWT claims and placed into the request context by the auth middleware.

Architecture

cmd/gateway/main.go              # Entry point, middleware chain assembly
internal/
├── auth/
│   └── jwt.go                   # JWT parsing, validation, generation (HS256)
├── middleware/
│   ├── auth.go                  # Auth middleware (JWT only — header or cookie)
│   ├── cors.go                  # CORS header injection
│   └── ratelimit.go             # Per-client token bucket rate limiter
└── proxy/
    └── routes.go                # Route registration, reverse proxy setup

JWT Claims Structure

type Claims struct {
    UserID string   `json:"user_id"`
    Roles  []string `json:"roles"`
    jwt.RegisteredClaims
}

Tokens are signed with HS256 and expire after 24 hours. The issuer is set to aegis-gateway.

Dependencies

The gateway has no database dependencies. It proxies all persistence to backend services.

Service Dependencies

The gateway calls the auth-service (port 8009) for token generation. JWT validation is done locally using the shared JWT_SECRET. All other backend services are called only as reverse proxy targets.

Configuration

Running Locally

cd services/api-gateway
go run ./cmd/gateway/

The gateway will start on port 8000 and log the upstream service URLs it is configured to proxy to. Make sure the backend services you need are running before sending requests through the gateway.