API Gateway¶

O API Gateway é o ponto de entrada único do AIOS. Construído com Hono.js para performance máxima, com segurança enterprise integrada.

Base URL: http://localhost:3000 (desenvolvimento)

Middlewares (em ordem de execução)¶

graph LR
    REQ[Requisição] --> SH[Secure Headers]
    SH --> RL[Rate Limiter]
    RL --> IS[Input Sanitizer]
    IS --> AU[Audit Logger]
    AU --> AT[Auth JWT]
    AT --> RO[Rota]
    RO --> RES[Resposta]

1. Secure Headers¶

Aplica headers de segurança HTTP padrão: - X-Content-Type-Options: nosniff - X-Frame-Options: DENY - Referrer-Policy: strict-origin-when-cross-origin

2. Rate Limiter¶

Sliding window por IP + tenant_id, usando Redis:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87

Configurável via .env.docker:

RATE_LIMIT_REQUESTS=100    # máx requisições
RATE_LIMIT_WINDOW_MS=60000 # janela em ms (1 min)

3. Input Sanitizer (OWASP LLM01)¶

Detecta e bloqueia prompt injection antes de chegar ao LLM. Retorna 400 com error: "prompt_injection_detected".

4. Audit Logger¶

Cada requisição gera um log imutável com checksum SHA-256. Em produção, persiste em audit_logs no PostgreSQL.

5. Auth JWT (rotas `/v1/*`)¶

Authorization: Bearer <token>

O token deve conter:

{
  "tenant_id": "seu-tenant",
  "agent_id": "human",
  "scopes": ["squads:run", "squads:read"]
}

Endpoints¶

`GET /health`¶

Verificação de saúde do serviço.

Sem autenticação.

RequestResponse 200

curl http://localhost:3000/health

{
  "status": "ok",
  "service": "elroi-api-gateway",
  "version": "1.0.0",
  "timestamp": "2026-03-20T10:00:00.000Z"
}

`POST /v1/squads/{squad}/run`¶

Executa uma squad com o input fornecido.

Requer: Authorization: Bearer <token>

RequestBody SchemaResponse 200Erros

curl -X POST http://localhost:3000/v1/squads/copywriting/run \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Crie 5 headlines para um SaaS de produtividade",
    "model_tier": "tier2",
    "options": {}
  }'

Campo	Tipo	Obrigatório	Descrição
`input`	`string`	Sim	Tarefa para a squad (máx 32.000 chars)
`model_tier`	`"tier1"` \| `"tier2"` \| `"tier3"`	Não	Padrão: `tier2`
`options`	`object`	Não	Opções adicionais da squad

{
  "success": true,
  "data": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "squad": "copywriting",
    "model": "ollama/qwen2.5-coder:3b",
    "status": "queued",
    "message": "Execução enfileirada."
  }
}

Código	Error	Causa
400	`prompt_injection_detected`	Input contém padrão de injeção
400	`invalid_body`	JSON inválido
401	`unauthorized`	Token ausente ou inválido
422	`validation_error`	Schema do body inválido
429	`rate_limit_exceeded`	Limite de requisições atingido
500	`internal_error`	Erro interno

`GET /v1/squads`¶

Lista squads disponíveis para o tenant autenticado.

RequestResponse 200

curl http://localhost:3000/v1/squads \
  -H "Authorization: Bearer $JWT_TOKEN"

{
  "success": true,
  "data": {
    "tenant_id": "seu-tenant",
    "squads": [
      {
        "slug": "copywriting",
        "name": "Copywriting",
        "tier": "2-revenue",
        "version": "1.0.0"
      }
    ]
  }
}

Model Routing¶

O gateway roteia automaticamente para o LLM correto baseado em model_tier:

Tier	LLM	Quando usar
`tier1`	`claude-sonnet-4-6`	Tasks complexas, código crítico, decisões
`tier2`	`ollama/qwen2.5-coder:3b`	Padrão — automações, boilerplate
`tier3`	`openrouter/google/gemini-2.0-flash-exp`	Contexto longo (>32K), análise de docs

Configure os modelos via env:

MODEL_TIER1=claude-sonnet-4-6
MODEL_TIER2=ollama/qwen2.5-coder:3b
MODEL_TIER3=openrouter/google/gemini-2.0-flash-exp

Desenvolvimento local¶

cd infrastructure/api-gateway

# Instalar dependências
npm install

# Rodar em modo dev (hot reload)
npm run dev

# Build para produção
npm run build
npm start

Variáveis de ambiente para dev

Crie um .env.local na raiz do api-gateway/ para desenvolvimento:

PORT=3000
JWT_SECRET=dev-secret-nao-usar-em-producao
REDIS_URL=redis://localhost:6379