System Architecture

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Shashank-H/gaiter-gaurd/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Core Components

​

1. Gateway Core

• Service resolution — validates agent access to target service
• SSRF prevention — validates target URLs against registered service baseUrls
• Credential injection — decrypts and injects service credentials
• Request forwarding — proxies to target API with 30s timeout and 10MB size limits

// proxy.service.ts:380
export async function executeProxyRequest(
  agentId: number,
  userId: number,
  data: ProxyRequestData
): Promise<{ status: number; headers: string; body: string }>

​

2. Encrypted Vault

• Key derivation — uses scrypt to derive encryption key from ENCRYPTION_SECRET
• Authenticated encryption — AES-256-GCM with random IV per operation
• Storage format — iv:authTag:ciphertext (all hex-encoded)

​

3. Risk Assessor

• LLM-based intent analysis — OpenAI-compatible API call with 10s timeout
• HTTP method heuristics — baseline risk scores (DELETE: 0.7, PUT: 0.5, POST: 0.3, GET: 0.1)
• Blended scoring — finalScore = llmScore * 0.7 + heuristicScore * 0.3
• Fail-closed behavior — on LLM failure, escalates heuristic score by +0.3

​

4. Approval Queue

• 5-state model — PENDING → APPROVED/DENIED → EXECUTED/EXPIRED
• Race-safe transitions — uses conditional WHERE status = fromStatus updates
• TTL enforcement — cleanup job expires approved-but-unexecuted requests

​

5. Agent Authentication

• Agent-Key generation — cryptographically random 32-byte keys
• SHA-256 key hashing — only hash stored in database
• Service scoping — many-to-many relationship via agent_services table
• Revocation — soft delete via isActive flag

​

Data Flow

​

Sequence Diagram

​

Request Lifecycle

1. Resolve service — validates agent has access to target service
2. Validate target URL — SSRF prevention checks hostname and path
3. Risk assessment — LLM evaluates intent mismatch and method risk
4. Check idempotency — returns cached response if duplicate request
5. Inject credentials — decrypts vault secrets and adds auth headers
6. Forward request — proxies to target API with timeout and size limits
7. Log audit trail — writes to proxy_requests table (fire-and-forget)
8. Complete idempotency — caches response for future duplicate requests

​

Tech Stack

​

Directory Structure

backend/src/
├── config/       # Environment validation (env.ts, db.ts)
├── db/           # Drizzle schema and client
├── routes/       # Route handlers (auth, services, agents, proxy, approval)
├── services/     # Business logic
│   ├── encryption.service.ts    # AES-256-GCM vault
│   ├── risk.service.ts          # LLM risk assessor
│   ├── approval.service.ts      # State machine
│   ├── proxy.service.ts         # Gateway core
│   ├── agent.service.ts         # Agent CRUD
│   ├── auth.service.ts          # JWT auth
│   └── idempotency.service.ts   # Duplicate request handling
├── middleware/   # Auth and validation
└── utils/        # Response helpers, logging, API key utilities

​

SSRF Prevention

// proxy.service.ts:92
export function validateTargetUrl(targetUrl: string, serviceBaseUrl: string): void {
  // ... validation logic
  if (target.hostname !== base.hostname) {
    throw new ProxyError('Hostname mismatch', 403);
  }
  // ... private IP checks
}

​

Trust Boundaries

​

1. Agent ↔ Gateway

• Agent-Key authentication — SHA-256 hashed keys in agents table
• Service scoping — agents can only access explicitly granted services
• Intent logging — every request logs stated intent for audit trail

​

2. Gateway ↔ Target API

• Credential isolation — agents never see real credentials
• Request validation — SSRF checks prevent unauthorized target access
• Response sanitization — 10MB size limit prevents memory exhaustion

​

Related Concepts