Runtime local

Desde a linha 0.5, toda Central roda localmente sem cadastro na Plataforma. O runtime local é seguro por construção: só aceita loopback, usa cookies HttpOnly com CSRF e nunca emite identidade operacional.

Início

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
npm install
npm run dev

O orquestrador:

1. inicia o backend em 127.0.0.1:4000 e o frontend em 127.0.0.1:5173;
2. gera dois códigos de uso único, aleatórios e independentes — um para o navegador e um para automação/seed;
3. abre o navegador já com o código de bootstrap.

O Vite encaminha /api ao backend para manter cookies e CSRF na mesma origem.

SERVICE_NAME=minha-central
PORT=4000
NODE_ENV=development
OON_RUNTIME_MODE=local
MONGO_URI=mongodb://localhost:27017/minha-central
APP_CODE=minha-central

Sessão

O primeiro acesso troca o código de uso único por:

• cookie de sessão HttpOnly, SameSite=Strict;
• cookie CSRF de double-submit;
• sessão local cujo banco armazena somente hashes e expiração.

O prazo padrão é de 30 dias. Reiniciar o processo rotaciona o segredo sem ampliar o prazo. Excluir o banco local inicia um novo período (limitação aceita). Secure é adicionado aos cookies quando OON_LOCAL_HTTPS=true.

Perfis

O banner superior permite selecionar apenas os papéis declarados em central.app.json. A permissão é recalculada no backend.

• O principal técnico é local:developer.
• O papel inicial é developer quando declarado; senão admin ou o primeiro papel.
• Convites e usuários reais não são criados.
• Apps com tenant usam o contexto virtual fixo local:tenant, sem criar tenant persistente nem aceitar tenant arbitrário do cliente.

Ativação

O estado local é ativa_local. O ActivationGuard não cria nem consulta instâncias da Plataforma. Isso não equivale a uma instância ativa publicada.

Integrações e capabilities

• Use dublês ou credenciais explicitamente fornecidas no .env local.
• O Core não busca segredos da Plataforma e não cria Deployment, binding ou entitlement.
• Capabilities de plataforma (PDF, e-mail) falham fechado localmente — por exemplo PDF_RENDERING_UNAVAILABLE.
• operationalRequestHeaders falha com LOCAL_OPERATION_NOT_SUPPORTED.
• Métricas de uso não são enviadas.

Seed e automação

Scripts de seed devem usar exclusivamente o código de Automação/seed impresso pelo npm run dev. Usar o código do navegador num script invalida a sessão do navegador.

Encerramento

Ctrl+C encerra os dois processos.

Falhas de startup

O Core falha no startup local quando encontra produção, Kubernetes, identidade operacional, bind não-loopback ou PUBLIC_APP_URL externa:

Veja também Fronteira de segurança local e Troubleshooting.