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-keyde 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 InfraHub usa pra validar JWT em cada query. Nunca deve sair do InfraHub nem do servidor do app que precisar emitir tokens externos.
• RLS (Row-Level Security): políticas SQL que filtram linhas por usuário. InfraHub 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: InfraHub 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: InfraHub 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 InfraHub (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.

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 InfraHub. 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

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 InfraHub)
• 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 diferentese 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 InfraHub 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 InfraHub 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 — InfraHub já manda esse header)
• Rate limit no seu lado se relevante (InfraHub tem por IP global, mas você pode ter cota por feature)
• Não logue JWT em error tracker (Sentry, Datadog) — adicione filter