Documentação

• Projeto: unidade de isolamento. Cada projeto tem banco Postgres dedicado, bucket MinIO próprio, JWT secret próprio.
• API key (if_xxx...): identifica o projeto. Vai no header x-infraforge-key de toda request server-side. Pode ficar no app cliente (não é segredo de produção isolado — mas não exponha pra atacantes desnecessariamente).
• JWT secret: assina os tokens dos end-users. Backend do InfraForge usa pra validar JWT em cada query. Nunca deve sair do InfraForge nem do servidor do app que precisar emitir tokens externos.
• RLS (Row-Level Security): políticas SQL que filtram linhas por usuário. InfraForge injeta request.jwt.sub / role / email em cada query do SDK, e suas policies referenciam auth.uid() / auth.role().

No painel, vai em Projetos → Novo projeto. Escolhe modo:

• managed_local: InfraForge spawna container Postgres+MinIO na própria VPS. Sem setup, mais rápido.
• external (BYODB): você fornece a connection URL do seu Postgres. Veja BYO Database antes.
• managed_remote: InfraForge spawna container numa VPS sua (cadastrada em Minhas VPSs) via SSH.

Após o provisionamento (~10-30s), você recebe API key(formato if_xxx...). Copia essa key.

// Cadastro — default vai pra "pending approval" (admin libera no painel)
const { user, pending } = await client.auth.signUp({
  email: 'alice@example.com',
  password: 'senha-forte',
})

// Login (após aprovação)
const { token, error } = await client.auth.signIn({
  email: 'alice@example.com',
  password: 'senha-forte',
})

// Logout — limpa sessão local
client.auth.signOut()

// Verificar usuário atual (faz request server-side)
const { user } = await client.auth.getUser()

// Sessão local (sem rede)
const session = client.auth.getSession()
if (session) console.log(session.user.email)

Modos de aprovação (configura no painel do projeto, aba Auth): manual_approval (default — admin aprova), email_verification (link no email confirma), auto_approve (libera direto, use com cuidado).

Configura credenciais do provider no painel do projeto (aba Auth → Providers). SDK lida com o redirect + callback.

// Inicia o fluxo (browser redireciona pro provider)
client.auth.signInWithSocial({
  provider: 'google',           // ou 'github'
  redirectTo: '/dashboard',     // path relativo OU mesma origin (rejeita externos)
})

// Na sua página /callback, rode handleOAuthCallback
const result = client.auth.handleOAuthCallback()
if (result?.user) {
  // Logado! result.token tem o JWT
} else if (result?.error) {
  console.error('OAuth falhou:', result.error)
}

Segurança: o SDK gera um state random salvo em sessionStorage antes do redirect, e valida no callback. Previne session fixation via link malicioso #token=....

MFA com TOTP (Google Authenticator, Authy, 1Password) está disponível pra contas do painel InfraForge (admin/tenant), não pros end-users do projeto. Ative em Conta → Segurança.

MFA pra end-users do projeto não está implementado ainda — está no roadmap. Se você precisa, abra uma issue.

Útil quando o JWT chega de outro fluxo (callback OAuth externo, sistema legado, server-side handoff).

// Lança erro se JWT mal-formado, expirado, ou sem 'sub'.
// Não cria sessão "vazia" — UI nunca fica em estado pseudo-logada.
try {
  client.auth.setToken(jwt)
} catch (err) {
  console.error('JWT inválido:', err.message)
}

Por default, sessão (JWT) é persistida em localStorage. Pra apps mais sensíveis, escolha modo:

createClient({
  url, projectSlug, apiKey,
  session: 'localStorage',     // (default) persiste entre tabs e refresh
  // session: 'sessionStorage',// só vive enquanto a aba estiver aberta
  // session: 'memory',        // nada gravado; refresh = re-login
})

memory é imune a XSS de leitura, mas pior UX. Use pra apps com dados muito sensíveis.

Assine um JWT HS256 com o JWT Secret do projeto e injete via auth.setToken(). A partir daí, db.query() manda API key + Bearer juntos:

import { SignJWT } from 'jose'
import { createClient } from '@infraforge/sdk'

// O JWT Secret do projeto — guarde como segredo de servidor (env var),
// NUNCA no client. Não é o NEXTAUTH_SECRET da plataforma.
const secret = new TextEncoder().encode(process.env.INFRAFORGE_JWT_SECRET!)

const serviceToken = await new SignJWT({
  sub: '00000000-0000-0000-0000-000000000000', // UUID válido (auth.uid() faz ::uuid)
  email: 'service@suaapp.local',               // precisa ser NÃO-vazio
  role: 'service_role',                         // role reconhecida pelo InfraForge
})
  .setProtectedHeader({ alg: 'HS256' })
  .setIssuedAt()
  .setExpirationTime('30d') // longo, mas finito — rotacione quando necessário
  .sign(secret)

const client = createClient({
  url: process.env.INFRAFORGE_URL!,
  projectSlug: 'meu-app',
  apiKey: process.env.INFRAFORGE_API_KEY!,
})

client.auth.setToken(serviceToken)

// Agora roda server-side, sem usuário interativo:
const { data, error } = await client.db.query('SELECT * FROM invoices')

No painel: Projeto → aba Visão geral → Credenciais → “JWT Secret”. É o mesmo segredo que o InfraForge usa pra assinar os tokens de login dos seus end-users.

⚠ É um segredo de servidor: quem tem ele pode forjar qualquer identidade no seu projeto. Mantenha em env var, nunca commite, nunca exponha no bundle do client. Não confunda com o NEXTAUTH_SECRET da plataforma — esse não vale aqui.

• sub, email e role precisam ser não-vazios — o backend rejeita a query se algum vier vazio. (role assume authenticated por default; email não tem default seguro.)
• sub é convertido pra uuid por auth.uid() — use um UUID válido (ex: o all-zeros) ou queries que chamam auth.uid() quebram no cast.

Com um service token, db.query() roda DDL normalmente (a query proxy aceita SQL arbitrário e executa com privilégio de owner do banco). Dá pra rodar migrations no boot de um container:

client.auth.setToken(serviceToken)

await client.db.query(`
  CREATE TABLE IF NOT EXISTS jobs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    status TEXT NOT NULL DEFAULT 'pending',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
  );
`)

Pra múltiplos statements num único query(), não use parâmetros (params vazio): com $1 o Postgres entra no extended protocol e aceita só 1 statement por chamada. Pra fluxo versionado/idempotente, prefira o CLI infraforge migrations (ver seção Migrations).

A query proxy nunca faz bypass de RLS — nem com service token. O toggle de bypass do painel (TTL 60min) é só pra recuperação emergencial, não serve pra worker always-on. O que o token consegue depende das suas políticas:

• A conexão ao banco do projeto é como owner, e o Postgres só aplica RLS em tabelas marcadas com FORCE ROW LEVEL SECURITY. Sem FORCE, o service token (e qualquer end-user) ignora as políticas e enxerga tudo — confira isso se seu isolamento entre usuários depende de RLS.
• Com FORCE ROW LEVEL SECURITY, crie uma política que libere o service explicitamente:

ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
ALTER TABLE invoices FORCE ROW LEVEL SECURITY;

-- End-users só veem as próprias linhas
CREATE POLICY invoices_owner ON invoices
  USING (user_id = auth.uid());

-- O service token (role='service_role') acessa tudo
CREATE POLICY invoices_service ON invoices
  USING (auth.role() = 'service_role');

O backend popula 3 functions no schema auth que suas policies usam:

auth.uid()    -- UUID do user logado (request.jwt.sub)
auth.role()   -- role do JWT (default 'authenticated')
auth.email()  -- email do user

Exemplo de policies básicas:

-- Tabela com author_id
CREATE TABLE posts (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  author_id uuid REFERENCES auth.users(id) NOT NULL DEFAULT auth.uid(),
  title text,
  body text,
  created_at timestamptz DEFAULT now()
);
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

-- Cada user vê só os próprios posts
CREATE POLICY "select own" ON posts
  FOR SELECT USING (author_id = auth.uid());

-- Pode inserir posts seus
CREATE POLICY "insert own" ON posts
  FOR INSERT WITH CHECK (author_id = auth.uid());

-- Pode editar/deletar só próprios
CREATE POLICY "update own" ON posts
  FOR UPDATE USING (author_id = auth.uid());
CREATE POLICY "delete own" ON posts
  FOR DELETE USING (author_id = auth.uid());

Aplica via aba Migrations ou SQL Editor do projeto. Use a aba RLS pra editar policies via UI.

Cada call de client.db.query() já roda em transação implícita (BEGIN + sets de JWT context + COMMIT). Pra múltiplas operações atômicas, mande tudo num DO $$ BEGIN ... END $$ OU separe em statements numa única string com ;.

Se você precisa ver/consertar dados como admin (ex: perdeu acesso a conta de user, precisa migrar dados manualmente), use o toggle Bypass RLS em Configurações do projeto. Vale por 1h.

Importante: o bypass aplica APENAS no painel (SQL Editor, Tables) e na CLI (admin). O SDK do app continua respeitando RLS — end-users não veem dados além das policies.

• Pool: até 20 conexões simultâneas por projeto
• Query timeout: 5 minutos (longo, mas pra evitar pendurar conexão)
• Tamanho da query SQL: max 50.000 caracteres

Pra arquivos grandes (vídeo, dump), evite proxar bytes pelo InfraForge. Pega URL presigned, browser faz PUT direto no MinIO.

// 1. Pede URL presigned (TTL default 1h, max 24h)
const { url, method } = await client.storage.getUploadUrl('videos/clip.mp4', {
  expiresIn: 3600,
})

// 2. Browser faz PUT direto
await fetch(url, {
  method,
  body: file,
  headers: { 'Content-Type': 'video/mp4' },
})

// Download URL similar:
const { url: dlUrl } = await client.storage.getDownloadUrl('videos/clip.mp4')
window.location.href = dlUrl

Por default, bucket é privado — só presigned URLs (com expiração) permitem acesso. Pra expor diretório como público (ex: avatares com URLs estáveis), use a aba Arquivos → Policy do projeto ou direto via SDK:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::meu-projeto/public/*"
    }
  ]
}

URLs públicas ficam em https://<slug>.<STORAGE_PUBLIC_DOMAIN>/<bucket>/<path>

• Tamanho de arquivo via SDK helper: ~25 MB recomendado (proxa pelo Next). Acima disso, use presigned URL.
• Presigned URL TTL: 60s a 24h
• Quota total de storage: por plano (ver Limites & Quotas)

No painel do projeto, aba Realtime, encontra a tabela e clica Ativar. Cria o trigger AFTER INSERT/UPDATE/DELETE chamando realtime.notify_change().

Browser EventSource não permite custom headers, então credenciais não vão direto na URL (era um bug de segurança CWE-598). Em vez disso:

1. SDK faz POST /api/realtime/[slug]/session com headers normais → recebe sse_token efêmero (1h)
2. Abre EventSource com ?sse_token=...
3. Token tem purpose:'sse' — se vazar em log de proxy, só dá pra subscribe a esse endpoint, nada mais.

SDKs server-side (Python, Go, Java) mandam headers direto, sem precisar do handshake.

• 16 canais por conexão SSE
• 20 conexões SSE simultâneas por projeto (cada uma consome 1 client do pool PG)
• ~8KB de payload por evento (pg_notify limite). Rows maiores chegam com truncated:true — cliente busca via client.db.query()
• sse_token expira em 1h. Reconexão automática reaproveita o mesmo token; após 1h, faz nova handshake

Mesmo padrão do client.realtime.subscribe(), via SSE, autenticado só pela API key do projeto (mensageria é uma capacidade de projeto, não por usuário final).

const msg = client.messaging()

const sub = msg.on('message', (envelope) => {
  console.log(envelope.platform, envelope.text, envelope.senderId)
  // envelope.contentType: 'text' | 'image' | 'document' | 'video' | 'audio' | 'button' | 'location' | 'other'
})

// depois...
sub.unsubscribe()

Configure um Webhook URL nas configurações de Mensageria do projeto (painel). Toda mensagem de entrada vira um POST assinado por HMAC-SHA256, sem precisar do SDK:

• Header x-infraforge-signature: sha256=<hmac> do corpo cru, calculado com o segredo do webhook configurado (ou o JWT secret do projeto, se nenhum segredo específico for definido)
• Corpo: { platform, channelKind, conversationId, senderId, contentType, text, attachments, timestamp }
• Retry automático com backoff se seu endpoint responder erro ou timeout (10s)

Cada projeto pode ligar um assistente que responde automaticamente mensagens de texto recebidas, usando um alias do módulo de IA já configurado, com prompt de sistema e histórico de conversa próprios do projeto — configurado inteiramente pelo painel(aba do projeto → Mensageria → Assistente), sem chamada nenhuma de SDK. Um toggle opcional "simular comportamento humano" adiciona atraso de leitura/digitação e quebra a resposta em mensagens curtas, reduzindo (não eliminando) o risco de banimento em canais que emulam o WhatsApp Web (não oficial, Evolution, WAHA).

O cliente messaging() (envio + on('message')) existe hoje só no SDK TypeScript. As outras linguagens (Python, Go, PHP, Ruby, Java, C#) ainda não têm esse wrapper — pra usar mensageria a partir delas, chame a API REST direto (POST /api/messaging/send, exemplo cURL acima) e/ou configure o webhook, que funciona com qualquer linguagem sem precisar de SDK nenhum.

npm install -g @infraforge/cli

# Salva URL + API key globalmente em ~/.infraforge/config.json (chmod 600)
infraforge login

# Linka o diretório atual a um projeto (.infraforge/config.json no cwd)
infraforge link meu-projeto

Override por env: INFRAFORGE_URL, INFRAFORGE_API_KEY, INFRAFORGE_PROJECT. Override por flag: --url, --api-key, --project.

infraforge gen types -o src/database.ts

Lê o schema do projeto (tabelas, colunas com tipos PG, PKs, FKs, enums) e gera interface TypeScript no estilo Supabase:

import type { Database, Tables, TablesInsert } from './database'

type Post = Tables<'public', 'posts'>
type NewPost = TablesInsert<'public', 'posts'>

const newPost: NewPost = {
  title: 'Hello',
  // colunas com default são opcionais
}

Mapeia 30+ tipos PG (incluindo arrays _int4 e enums custom como union types).

# Inline
infraforge sql "SELECT count(*) FROM posts"

# Arquivo
infraforge sql -f schema.sql

# Stdin
echo "TRUNCATE old_data" | infraforge sql

# JSON output
infraforge sql "SELECT * FROM posts" --json

Modo admin: bypass RLS automático. Usa apenas a API key (sem JWT). Quem tem a API key tem acesso total ao projeto via CLI.

# Cria infraforge/migrations/<timestamp>_<nome>.sql
infraforge migrations new add_posts_table

# Aplica migrations pendentes em ordem alfabética
infraforge migrations up

Estado é mantido na tabela _infraforge_migrations do banco do projeto (id, applied_at). Re-rodar pula aplicadas.

⚠ Painel vs CLI: o painel usa um sistema separado (tabela migrations no meta-DB). Hoje os dois não se sincronizam. Migrations aplicadas via CLI não aparecem no painel e vice-versa. Item §6.4 do roadmap propõe unificar.

Cola SQL no textarea, dá nome, click Aplicar:

• Grava em migrations (tabela no meta-DB do InfraForge)
• Histórico fica visível no painel
• Sem versionamento de arquivo, sem idempotência (re-rodar mesmo SQL falha 2× em CREATE TABLE)
• Sem “down” — só forward. Pra desfazer, escreve outra migration manual
• Bom pra: hotfix rápido, mudança one-off, exploração

# Cria infraforge/migrations/<timestamp>_<nome>.sql
infraforge migrations new add_orders_table

# Aplica pendentes em ordem alfabética (idempotente)
infraforge migrations up

• Lê .sql de infraforge/migrations/ (cwd)
• Estado em _infraforge_migrations no banco do projeto
• Idempotente — re-rodar pula migrations já aplicadas
• Versionável em git → revisão de PR
• Bom pra: produção, time, fluxo CI/CD

Painel e CLI usam tabelas de controle diferentes e não se sincronizam. Se você aplicar migration via CLI, o painel mostra “0 migrations”. Vice-versa idem.

Item §6.4 do roadmap propõe unificar (ambos gravando em _infraforge_migrations no banco do projeto). Por enquanto, escolha um caminho e fique nele.

• Use CREATE TABLE IF NOT EXISTS e ALTER TABLE ... ADD COLUMN IF NOT EXISTS pra garantir idempotência manual mesmo no painel
• Prefira CLI pra qualquer projeto que vá pra produção
• Evite queries enormes numa migration só — divide em arquivos
• Backup antes de migration que toca dados (não só DDL)
• Teste em projeto staging antes (BYO DB com banco separado pra dev)

O InfraForge tem 2 tipos de credencial. Saber a diferença evita acidentes.

• API key (if_xxx...): identifica o projeto. Acompanha toda request server-side via header x-infraforge-key. Vai no app cliente também (browser SDK precisa). Não é segredo absoluto — mas trate como secreta-ish (não cole em commit público de exemplo).
• JWT do end-user: assinado com jwtSecret do projeto, identifica QUAL user fez a request. Fica no header Authorization: Bearer <jwt>. Backend valida em cada call e injeta como contexto pra RLS.
• JWT secret: assina os JWTs. Nunca expor em código cliente. Só fica no InfraForge e no backend do app que precisar emitir tokens externos.

Sempre habilite RLS em qualquer tabela com dados por usuário:

ALTER TABLE minha_tabela ENABLE ROW LEVEL SECURITY;

-- Sem POLICY, ninguém vê nada (negação por default).
-- Adicione policies USING / WITH CHECK explícitas:
CREATE POLICY "select_own" ON minha_tabela
  FOR SELECT USING (owner_id = auth.uid());

⚠ Tabela sem RLS = tudo público pra qualquer user autenticado. Tem aba RLS no painel pra auditar quais tabelas estão protegidas.

Toggle Bypass RLS em Configurações dura 1h e libera SQL Editor + Tables + CLI a ignorar policies. SDK do app continua respeitando RLS — end-users não veem dados além das policies, mesmo com bypass ligado.

O fluxo OAuth do SDK gera um state random salvo em sessionStorage antes de redirecionar pro provider. Backend roundtripa o state via state assinado HMAC (TTL 10min). No callback, SDK compara — se mismatch, rejeita. Bloqueia ataque de atacante forjar link #token=ATTACKER_JWT pra fixar sessão na vítima.

JWT da sessão é persistido em localStorage por default. Pra apps com dados muito sensíveis, escolha:

createClient({
  url, projectSlug, apiKey,
  session: 'localStorage',     // (default) persiste entre tabs
  // session: 'sessionStorage',// só durante a aba aberta
  // session: 'memory',        // nada gravado, refresh = re-login
})

• localStorage: melhor UX, vulnerável a XSS de leitura no app cliente
• sessionStorage: blast radius menor (limpa quando fecha aba)
• memory: imune a XSS de leitura, mas usuário precisa logar de novo a cada refresh

SSE auth usa sse_token curto-vivo (1h, purpose:'sse') em vez de credencial de longa duração na URL. Se vazar em log, expira rápido e só dá pra subscribe a esse endpoint do projeto, nada mais.

• Sanitizar input — XSS é bug do APP, não do framework
• CSP restrita (Content-Security-Policy)
• HTTPS obrigatório (HSTS — InfraForge já manda esse header)
• Rate limit no seu lado se relevante (InfraForge tem por IP global, mas você pode ter cota por feature)
• Não logue JWT em error tracker (Sentry, Datadog) — adicione filter