Security

• Zero-Trust Model — Every request authenticated, authorized, and audited; no implicit trust between components
• Defense in Depth — Multiple validation layers: authentication → authorization → scope validation → credential selection
• Rate Limiting — Per-IP, per-user, and per-agent rate limiting with configurable windows
• Header Sanitization — Security-sensitive response headers stripped from downstream API responses
• Constant-Time Comparison — Admin API key validation resists timing attacks

Operations

• Structured Audit Logging — Comprehensive audit trail with SIEM forwarding support (JSON, structured pino logs)
• Health & Readiness — /health and /ready endpoints for orchestration probes
• Prometheus Metrics — Request duration, auth success/failure, token refreshes, rate limit hits, scope violations
• Circuit Breaker — Proxy-to-upstream circuit breaker with configurable failure thresholds

Architecture

┌─────────────┐      ┌──────────────────────┐      ┌─────────────────┐
│   AI Agent  │─────▶│   Agent Auth Proxy   │─────▶│  Downstream API │
│  (Client)   │      │   (Identity Layer)   │      │  (Google, etc)  │
└─────────────┘      └──────────────────────┘      └─────────────────┘
                            │
                            ▼
                    ┌──────────────┐
                    │  PostgreSQL  │
                    └──────────────┘

Request Pipeline:

1. Authenticate agent (JWT validation)
2. Extract user context and requested scopes
3. Validate granted scopes (scope enforcement)
4. Retrieve and decrypt user credentials
5. Attach credentials to downstream request
6. Forward and stream response back to agent

See ARCHITECTURE.md for detailed component design, security model, scaling strategy, and monitoring setup.

Tech Stack

Prerequisites

• Node.js >= 22.0.0
• pnpm >= 10.0.0
• PostgreSQL 15+ (or Docker for local development)
• Docker & Docker Compose (optional, for containerized setup)

Quick Start

Option 1: Docker Compose

# Clone the repository
git clone https://github.com/reaatech/agent-auth-proxy.git
cd agent-auth-proxy

# Configure environment
cp .env.example .env
# Edit .env with your secrets (see Configuration section)

# Start services
docker compose up -d

# Run database migrations
docker compose --profile setup run --rm migrate

# Verify
curl http://localhost:3000/health

Option 2: Local Development

# Install dependencies
pnpm install

# Configure environment
cp .env.example .env
# Edit .env — set DATABASE_URL and generate MASTER_KEY

# Start PostgreSQL (Docker convenience)
docker compose up -d db

# Run migrations
pnpm db:migrate

# Start development server with hot reload
pnpm dev

Configuration

Required Environment Variables

OAuth Providers

Optional

Generating Secrets

# Generate MASTER_KEY (base64-encoded 32-byte key)
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Generate ADMIN_API_KEY (base64url-encoded 32-byte key)
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# Generate AGENT_JWT_SECRET
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

API Overview

Agent Authentication

POST /auth/agent
Authorization: Bearer <agent_api_key>

Response: { "token": "<jwt>", "agent": { "id": "<uuid>", "name": "<string>" } }

Agents exchange their long-lived API key (prefix aap_) for a short-lived JWT (default 1 hour). The JWT is then used as a Bearer token for all proxied requests. Agent API keys are returned by POST /api/v1/agents at registration time — they are shown only once.

Proxy Requests

Proxied requests forward method, path, headers, and body to the target downstream API with the user's credentials attached.

METHOD /proxy/:provider/<path...>
Authorization: Bearer <agent_jwt>
X-User-ID: <user_id>
?_scope=<comma,separated,scopes>      # Optional: enforce scopes

# Example: Read Google Calendar
curl -X GET "http://localhost:3000/proxy/google/calendar/v3/calendars/primary?_scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.readonly" \
  -H "Authorization: Bearer <agent_jwt>" \
  -H "X-User-ID: <user_id>"

The proxy forwards status codes, headers, and body directly from the downstream API. No response envelope — compatible with standard HTTP clients and SDKs.

Supported providers: google, github

Management API

All management endpoints are mounted under /api/v1 and require the admin API key passed via the X-Admin-API-Key header.

Users:

Agents:

Grants:

Tokens:

OAuth:

Client SDK

A typed TypeScript SDK is published as @reaatech/agent-auth-proxy-client. It wraps these endpoints with AgentClient (auth + proxy) and AdminClient (management). See packages/client/README.md.

Development

# Install dependencies
pnpm install

# Start development server (hot reload)
pnpm dev

# Build for production
pnpm build

# Run all tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run tests in watch mode
pnpm test:watch

# Run security-focused tests
pnpm test:security

# Type-check the project
pnpm typecheck

# Lint and format
pnpm lint
pnpm format

# Database operations
pnpm db:generate          # Generate migration files from schema
pnpm db:migrate           # Run pending migrations
pnpm db:seed              # Seed database with test data
pnpm db:studio            # Open Drizzle Studio (GUI)

# Security audit
pnpm audit

Code Quality

CI enforces:

• Biome lint + format (pnpm lint, pnpm format:check)
• TypeScript strict mode (pnpm typecheck)
• Test coverage thresholds (85% lines, 85% functions, 78% branches)
• pnpm audit at moderate level and above

Deployment

Docker

# Build the image
pnpm docker:build

# Run with Docker Compose
pnpm docker:up

# Tear down
pnpm docker:down

The Dockerfile uses multi-stage builds: a builder stage compiles TypeScript, and a slim runtime stage runs the application as a non-root nodejs user.

Kubernetes

Kubernetes manifests are provided in k8s/:

kubectl apply -f k8s/

Production Considerations

• Front the service with a reverse proxy (nginx, AWS ALB) for TLS termination
• Store secrets in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Kubernetes Secrets)
• Set NODE_ENV=production
• Enable audit log SIEM forwarding for centralized monitoring
• Rotate MASTER_KEY, AGENT_JWT_SECRET, and ADMIN_API_KEY regularly

Project Structure

This is a pnpm + Turborepo monorepo with three publishable packages.