Fio Raiz

Gateway de WhatsApp auto-hospedado com API HTTP, MCP e painel — escrito do zero, sem dependências de produção, em Node 24 + TypeScript e SQLite embutido.

• API HTTP com chave em x-api-key: sessões, mensagens, contatos, etiquetas, grupos, webhooks, busca, estatísticas, configurações e chaves.

• MCP em POST /mcp (JSON-RPC 2.0) com 10 ferramentas próprias.

• Painel de leitura em GET /painel, sem build e sem framework.

• Zero dependências obrigatórias: o núcleo roda com node:http e node:sqlite; o Baileys é optionalDependency (só o motor real usa) e npm ci --omit=optional continua sem runtime. O banco é node:sqlite, o servidor é node:http.

Começar

git clone https://github.com/Voltolini-SPACE/fio-raiz && cd fio-raiz
npm ci            # dev (typescript) + Baileys opcional; use --omit=optional para o motor simulado
npm test          # 68 testes, node --test
npm start         # http://127.0.0.1:2790

A chave nasce em data/.api-key com modo 0600. Use:

CHAVE=$(cat data/.api-key)
curl -s http://127.0.0.1:2790/api/health
curl -s -H "x-api-key: $CHAVE" -X POST -H 'content-type: application/json' \
  -d '{"nome":"Atendimento"}' http://127.0.0.1:2790/api/sessions

Related MCP server: WhatsApp Business API MCP Server

Rodar sem interrupções

Unit systemd pronta em deploy/: fio-raiz.service (gateway, Restart=always, sessão retomada no boot). Instruções em deploy/README.md.

Acesso remoto (Mac, iPad, Maestri)

Pelo Tailscale: http://100.x.y.z:2793 de qualquer rede, com portão FIO_RAIZ_ACESSO=tailnet (só loopback e 100.64.0.0/10; LAN/internet → 403). O painel /painel pede a chave; o MCP é POST /mcp com x-api-key. SSH para o Mac: ssh mac.

O que já funciona

Sessões com ciclo de vida (criar, iniciar, parar, parear, status, QR), envio de texto e mídia, listagem paginada, contatos, etiquetas, grupos, webhooks com entrega e histórico de falha, busca, estatísticas, configurações, chaves de API, MCP e painel. Há um motor real de WhatsApp opcional (Baileys, carregado por import() dinâmico) que emite QR de verdade e recebe mensagens; o padrão continua sendo o motor simulado, sem rede. O ensaio real está em EVIDENCIA.md.

Motor real (opcional)

npm ci            # o Baileys já vem como dependência opcional
FIO_RAIZ_MOTOR=baileys npm start

Criar sessão com "motor":"baileys", chamar /start e ler /qr devolve o QR emitido pelo WhatsApp. O adaptador reconecta com espera exponencial e desiste em 401/403/405 (aparelho deslogado). Sessão fica em data/sessoes/<id>/auth; depois de reiniciar o processo, as sessões voltam como parada e precisam de /start (a credencial é reaproveitada, QR não é pedido de novo).

Risco declarado: conexão não oficial viola os termos do WhatsApp e pode levar o número a bloqueio. Use um número dedicado. Verificado em 04/11: QR emitido, aparelho conectado, mensagem real enviada e 46 mensagens recebidas de terceiros. Reconexão após queda de rede, download do binário de mídia e recibo de leitura continuam NÃO VERIFICADOS.

Pré-requisitos externos

O que não vem do código e precisa existir antes de parear. O plano da réplica (vive no repositório da Fábrica, planos/v3/voltolini-fio-raiz.json, chave dependencias_externas) declara o mesmo mapa; o gate da Fábrica reprova plano ou entrega sem ele.

Limites declarados

• O transporte real não é dependência do produto: sem baileys instalado, o motor simulado segue sendo o padrão e o adaptador responde motor_indisponivel com a instrução de instalação. A conexão com um celular de verdade não foi verificada — só a emissão do QR pelo servidor do WhatsApp.

• Plugins, ingress, integrações, exportação/importação, métricas Prometheus e auditoria não estão implementados — cada rota aparece em PARIDADE.md como excluído, com data.

• Não há paridade 100% com nenhum outro produto, e não é o objetivo.

Documentos

Licença MIT — LICENSE · NOTICE.

Qualidade

npm test (68 testes) e npm run check (tsc --noEmit) rodam no CI a cada push; o badge acima mostra o estado. Sem baileys instalado a suíte passa e o /start responde 503 motor_indisponivel com o comando de instalação.