Security Model

Overview

GaiterGuard’s security model is built on three pillars:

Encrypted vault — secrets encrypted at rest with AES-256-GCM
Agent-key scoping — agents can only access explicitly granted services
Trust boundaries — gateway enforces isolation between agents and credentials

Agents never receive production credentials. The gateway injects secrets at request time and immediately forwards to the target API. Credentials are never included in responses.

Encrypted Vault

Encryption Algorithm

GaiterGuard uses AES-256-GCM (Galois/Counter Mode) for authenticated encryption:

Key size: 256 bits (32 bytes)
IV size: 128 bits (16 bytes, randomly generated per operation)
Authentication: GCM mode provides built-in authentication tag
Key derivation: scrypt with configurable salt

Implementation

The encryption service is implemented in backend/src/services/encryption.service.ts:

import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';

const ALGORITHM = 'aes-256-gcm';
const KEY_LENGTH = 32; // 256 bits
const IV_LENGTH = 16;  // 128 bits

// Derive key from ENCRYPTION_SECRET at startup
ENCRYPTION_KEY = scryptSync(
  env.ENCRYPTION_SECRET,
  env.ENCRYPTION_SALT,
  KEY_LENGTH
);

Storage Format

Encrypted credentials are stored in the credentials table with format:

iv:authTag:ciphertext

All components are hex-encoded. Example:

// encryption.service.ts:39
export function encrypt(plaintext: string): string {
  const iv = randomBytes(IV_LENGTH);
  const cipher = createCipheriv(ALGORITHM, ENCRYPTION_KEY, iv);
  
  let encrypted = cipher.update(plaintext, 'utf8', 'hex');
  encrypted += cipher.final('hex');
  
  const authTag = cipher.getAuthTag();
  
  return `${iv.toString('hex')}:${authTag.toString('hex')}:${encrypted}`;
}

Why GCM mode? AES-GCM provides authenticated encryption, which detects tampering. If someone modifies the ciphertext, the authentication tag verification will fail during decryption.

Decryption Process

Decryption verifies the authentication tag to detect corruption or tampering:

// encryption.service.ts:65
export function decrypt(ciphertext: string): string {
  const [ivHex, authTagHex, encrypted] = ciphertext.split(':');
  
  const iv = Buffer.from(ivHex, 'hex');
  const authTag = Buffer.from(authTagHex, 'hex');
  
  const decipher = createDecipheriv(ALGORITHM, ENCRYPTION_KEY, iv);
  decipher.setAuthTag(authTag);
  
  let decrypted = decipher.update(encrypted, 'hex', 'utf8');
  decrypted += decipher.final('utf8'); // Throws if auth tag invalid
  
  return decrypted;
}

Key Management

The encryption key is derived at server startup in server.ts:191:

import { initEncryption } from '@/services/encryption.service';

// Initialize encryption before starting server
initEncryption();

Critical: The ENCRYPTION_SECRET environment variable must be at least 32 characters. If you lose this secret, all encrypted credentials are unrecoverable.

Environment Variables

Required configuration in .env:

ENCRYPTION_SECRET=your-secret-here-minimum-32-chars
ENCRYPTION_SALT=gaiter-guard-salt-v1  # Optional, defaults to this value

Validation is enforced at startup in backend/src/config/env.ts:28:

ENCRYPTION_SECRET: (() => {
  const secret = getEnvVar('ENCRYPTION_SECRET');
  if (secret.length < 32) {
    throw new Error('ENCRYPTION_SECRET must be at least 32 characters long');
  }
  return secret;
})(),

Agent-Key Authentication

Key Generation

Agent keys are 32-byte cryptographically random values generated via Node.js crypto:

// utils/apikey.ts
import { randomBytes } from 'node:crypto';

export function generateApiKey(): string {
  return 'gg_' + randomBytes(32).toString('hex'); // 64 hex chars + prefix
}

Example key: gg_a1b2c3d4e5f6... (67 characters total)

Key Storage

Only the SHA-256 hash of the key is stored in the database:

// utils/apikey.ts
import { createHash } from 'node:crypto';

export function hashApiKey(apiKey: string): string {
  return createHash('sha256').update(apiKey).digest('hex');
}

The agents table schema (backend/src/db/schema.ts:73):

export const agents = pgTable('agents', {
  id: integer().primaryKey().generatedAlwaysAsIdentity(),
  userId: integer().references(() => users.id).notNull(),
  name: varchar({ length: 255 }).notNull(),
  keyHash: varchar({ length: 64 }).notNull().unique(), // SHA-256 hex
  keyPrefix: varchar({ length: 16 }).notNull(),        // First 12 chars for display
  isActive: boolean().default(true).notNull(),
  lastUsedAt: timestamp(),
  createdAt: timestamp().defaultNow().notNull(),
  updatedAt: timestamp().defaultNow().notNull(),
});

The full API key is returned only once when the agent is created. If lost, a new agent must be created.

Authentication Flow

Agent authentication is handled by middleware (backend/src/middleware/auth.ts):

Extract Agent-Key header from request
Hash the provided key with SHA-256
Look up agent by keyHash in database
Verify agent is active (isActive = true)
Update lastUsedAt timestamp

// middleware/auth.ts (simplified)
export async function requireAgentAuth(req: Request) {
  const agentKey = req.headers.get('Agent-Key');
  if (!agentKey) throw new AuthError('Missing Agent-Key header', 401);
  
  const keyHash = hashApiKey(agentKey);
  const agent = await db.select().from(agents).where(eq(agents.keyHash, keyHash));
  
  if (!agent || !agent.isActive) {
    throw new AuthError('Invalid or revoked Agent-Key', 401);
  }
  
  return { agentId: agent.id, userId: agent.userId };
}

Service Scoping

Agent-Service Association

Agents are granted access to specific services via the agent_services join table:

// db/schema.ts:90
export const agentServices = pgTable('agent_services', {
  id: integer().primaryKey().generatedAlwaysAsIdentity(),
  agentId: integer().references(() => agents.id, { onDelete: 'cascade' }),
  serviceId: integer().references(() => services.id, { onDelete: 'cascade' }),
  createdAt: timestamp().defaultNow().notNull(),
});

This creates a many-to-many relationship: one agent can access multiple services, and one service can be accessed by multiple agents.

Access Enforcement

When an agent makes a proxy request, the gateway validates access in proxy.service.ts:169:

export async function resolveService(targetUrl: string, agentId: number) {
  const result = await db
    .select({ service: services })
    .from(services)
    .innerJoin(agentServices, eq(agentServices.serviceId, services.id))
    .where(eq(agentServices.agentId, agentId))
    .execute();
  
  const matchingService = result.find((row) => 
    targetUrl.startsWith(row.service.baseUrl)
  );
  
  if (!matchingService) {
    throw new NotFoundError('Agent does not have access to this service');
  }
  
  return matchingService.service;
}

If an agent attempts to access a service it’s not scoped to, the request is rejected with 403 Forbidden before any credentials are touched.

Updating Agent Scope

Service associations can be updated via the dashboard API:

PUT /agents/:id/services
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "serviceIds": [1, 3, 5]
}

This replaces all existing associations with the new list (implemented in agent.service.ts:297).

Credential Injection

Credentials are decrypted and injected only at request time, never returned to the agent.

Supported Authentication Types

The gateway supports four auth types (proxy.service.ts:212):

Bearer Token
API Key
Basic Auth
OAuth2

case 'bearer':
  headers['Authorization'] = `Bearer ${decryptedCreds.token}`;
  break;

Requires credential key: token

case 'api_key':
  const apiKeyValue = decryptedCreds.api_key || decryptedCreds[keyName];
  headers['X-API-Key'] = apiKeyValue;
  break;

Requires credential key: api_key or custom header name

case 'basic':
  const basicAuth = Buffer.from(
    `${decryptedCreds.username}:${decryptedCreds.password}`
  ).toString('base64');
  headers['Authorization'] = `Basic ${basicAuth}`;
  break;

Requires credential keys: username, password

case 'oauth2':
  headers['Authorization'] = `Bearer ${decryptedCreds.access_token}`;
  break;

Requires credential key: access_token

Credential Storage

Credentials are stored via the dashboard API:

POST /services/:id/credentials
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "credentials": {
    "api_key": "sk-...",
    "username": "admin",
    "password": "secret"
  }
}

Each key-value pair is encrypted separately and stored in the credentials table.

Auth Header Stripping

Before storing blocked requests in the approval queue, auth headers are stripped (proxy.service.ts:408):

const safeHeaders = { ...data.headers };
delete safeHeaders['Authorization'];
delete safeHeaders['authorization'];
delete safeHeaders['Agent-Key'];
delete safeHeaders['agent-key'];

This prevents credentials from being persisted in the database. When an approved request is executed, credentials are re-injected fresh from the vault.

Trust Boundaries

1. Agent ↔ Gateway Boundary

Enforced by:

Agent-Key authentication (SHA-256 hashed)
Service scoping (agent_services table)
SSRF validation (hostname and path checks)

Guarantees:

Agents can only access services explicitly granted
Agents cannot forge requests to unauthorized services
Agents cannot access other agents’ approval actions

2. Gateway ↔ Vault Boundary

Enforced by:

AES-256-GCM encryption at rest
Key derivation from ENCRYPTION_SECRET
Runtime-only decryption (never stored decrypted)

Guarantees:

Credentials are encrypted in database
Decryption key never leaves server memory
Tampering detected via authentication tag

3. Gateway ↔ Target API Boundary

Enforced by:

30-second request timeout
10MB response size limit
Manual redirect handling (disabled)
Private IP blocking

Guarantees:

No SSRF attacks to internal networks
No unbounded memory consumption
No credential leakage via redirects

Attack Scenarios

Scenario 1: Agent Key Compromise

Attack: Attacker steals an agent key Mitigation:

Agent can only access services it’s scoped to
All requests are logged with agentId for audit trail
High-risk requests require human approval (can’t be bypassed)
Revoke agent via dashboard (isActive = false)

Scenario 2: Database Breach

Attack: Attacker gains read access to PostgreSQL database Mitigation:

Credentials are AES-256-GCM encrypted
Agent keys are SHA-256 hashed (not reversible)
Encryption key (ENCRYPTION_SECRET) not stored in database
Without encryption key, credentials are unreadable

Scenario 3: SSRF Attempt

Attack: Agent tries to access internal network via targetUrl Mitigation:

Target hostname must match service baseUrl hostname
Private IP ranges blocked (127.x, 10.x, 192.168.x, etc.)
Localhost access blocked
Target path must start with service baseUrl path

Scenario 4: Intent Mismatch

Attack: Agent states benign intent but sends malicious payload Mitigation:

LLM risk assessor compares intent to actual request
Intent integrity check flags mismatches
Mismatched requests blocked with 428 status
Human reviews full context before approval

See Risk Assessment for the full scoring model.

Security Best Practices

Rotate Encryption Keys

To rotate the ENCRYPTION_SECRET:

Deploy new instance with new secret
Re-upload all service credentials via dashboard
Old instance’s encrypted data becomes unreadable

Warning: There is no automated key rotation. Plan for downtime.

Audit Agent Activity

All proxy requests are logged in the proxy_requests table:

SELECT 
  method, 
  target_url, 
  intent, 
  status_code, 
  requested_at 
FROM proxy_requests 
WHERE agent_id = 123 
ORDER BY requested_at DESC;

Revoke Compromised Agents

If an agent key is compromised:

PUT /agents/:id
Authorization: Bearer <jwt>

{
  "isActive": false
}

All subsequent requests with that key will be rejected.

Monitor Approval Queue

High volumes of risk-blocked requests may indicate:

Agent malfunction or misconfiguration
Threshold too low (RISK_THRESHOLD < 0.5)
LLM hallucination or overly sensitive rules

Review the approval_queue table for patterns.

Architecture

See how encryption integrates with the gateway

Risk Assessment

Understand intent integrity checking

Get Started

Core Concepts

Guides

Overview

Encrypted Vault

Encryption Algorithm

Implementation

Storage Format

Decryption Process

Key Management

Environment Variables

Agent-Key Authentication

Key Generation

Key Storage

Authentication Flow

Service Scoping

Agent-Service Association

Access Enforcement

Updating Agent Scope

Credential Injection

Supported Authentication Types

Credential Storage

Auth Header Stripping

Trust Boundaries

1. Agent ↔ Gateway Boundary

2. Gateway ↔ Vault Boundary

3. Gateway ↔ Target API Boundary

Attack Scenarios

Scenario 1: Agent Key Compromise

Scenario 2: Database Breach

Scenario 3: SSRF Attempt

Scenario 4: Intent Mismatch

Security Best Practices

Architecture

Risk Assessment

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​Overview

​Encrypted Vault

​Encryption Algorithm

​Implementation

​Storage Format

​Decryption Process

​Key Management

​Environment Variables

​Agent-Key Authentication

​Key Generation

​Key Storage

​Authentication Flow

​Service Scoping

​Agent-Service Association

​Access Enforcement

​Updating Agent Scope

​Credential Injection

​Supported Authentication Types

​Credential Storage

​Auth Header Stripping

​Trust Boundaries

​1. Agent ↔ Gateway Boundary

​2. Gateway ↔ Vault Boundary

​3. Gateway ↔ Target API Boundary

​Attack Scenarios

​Scenario 1: Agent Key Compromise

​Scenario 2: Database Breach

​Scenario 3: SSRF Attempt

​Scenario 4: Intent Mismatch

​Security Best Practices

​Related Concepts

Architecture

Risk Assessment

Build docs developers (and LLMs) love

Overview

Encrypted Vault

Encryption Algorithm

Implementation

Storage Format

Decryption Process

Key Management

Environment Variables

Agent-Key Authentication

Key Generation

Key Storage

Authentication Flow

Service Scoping

Agent-Service Association

Access Enforcement

Updating Agent Scope

Credential Injection

Supported Authentication Types

Credential Storage

Auth Header Stripping

Trust Boundaries

1. Agent ↔ Gateway Boundary

2. Gateway ↔ Vault Boundary

3. Gateway ↔ Target API Boundary

Attack Scenarios

Scenario 1: Agent Key Compromise

Scenario 2: Database Breach

Scenario 3: SSRF Attempt

Scenario 4: Intent Mismatch

Security Best Practices

Related Concepts