Auth

A camada de autenticação do Vectora garante que apenas usuários e serviços autorizados acessem recursos, namespaces e operações sensíveis. Esta seção documenta os mecanismos de identidade, gestão de chaves de API e controle de acesso que protegem sua infraestrutura de contexto.

Autenticação e Autorização no Vectora

Tópicos desta seção

Fluxo de Autenticação Típico

    graph LR
    A[Usuário / Serviço] --> B{Tipo de Acesso}
    B -->|Humano| C[Login via SSO]
    B -->|Máquina| D[API Key com escopo]

    C --> E[JWT com claims: userId, roles, namespaces]
    D --> F[Validação de chave + rate limiting]

    E --> G[Middleware RBAC]
    F --> G

    G --> H{Permissão concedida?}
    H -->|Sim| I[Executa operação]
    H -->|Não| J[Retorna 403 Forbidden]
  

Conceitos Fundamentais

Boas Práticas de Segurança

Use API Keys com escopo mínimo: Conceda apenas read se a integração não precisa escrever Rotação periódica de chaves: Renove API Keys a cada 90 dias ou após incidentes Valide namespaces em cada chamada: Não confie apenas no token; revalide escopo no runtime Monitore logs de auditoria: Use audit_logs para detectar acessos anômalos Nunca exponha chaves no client: API Keys pertencem ao backend ou ao agent principal, nunca ao browser

Integração com Seu Sistema

Exemplo: Validação de JWT no seu backend

// Exemplo: middleware de validação de JWT
import { verifyJWT } from "@vectora/auth";

export async function authMiddleware(req: Request, next: Handler) {
  const token = req.headers.get("Authorization")?.replace("Bearer ", "");
  if (!token) return next({ status: 401, error: "Missing token" });

  try {
    const claims = await verifyJWT(token, { audience: "vectora-api" });
    req.context = {
      userId: claims.sub,
      roles: claims.roles,
      namespaces: claims.namespaces,
    };
    return next();
  } catch {
    return next({ status: 403, error: "Invalid token" });
  }
}

Exemplo: Uso de API Key em chamada MCP

{
  "mcpServers": {
    "vectora": {
      "command": "npx",
      "args": ["vectora-agent", "mcp-serve"],
      "env": {
        "VECTORA_API_KEY": "vca_live_...",
        "VECTORA_NAMESPACE": "my-project"
      }
    }
  }
}

Perguntas Frequentes

P: Preciso de SSO para usar o Vectora? R: Não. O plano Free usa autenticação local via vectora auth login. SSO é disponível nos planos Pro/Team para integração com provedores corporativos.

P: Posso usar minha própria infraestrutura de auth? R: Sim. O Vectora aceita qualquer JWT válido configurado via auth.jwt.publicKey. Consulte SSO para detalhes de integração customizada.

P: Como revogo uma API Key comprometida? R: Via dashboard (/settings/api-keys) ou CLI: vectora api-key revoke --id <key_id>. A revogação é imediata em todos os nós.

P: O Vectora armazena minhas credenciais? R: Não. Chaves de API são armazenadas como hash (bcrypt). Tokens JWT são validados, não persistidos. Credenciais de providers (Gemini, Voyage) são fornecidas via BYOK e nunca tocadas pela Kaffyn.

External Linking

Frase para guardar: “Autenticação verifica quem você é. Autorização define o que você pode fazer. Vectora aplica ambas em cada tool call — não apenas no login.”

Parte do ecossistema Vectora · Open Source (MIT) · Contribuidores