WebLocal

Todos os serviços locais num só painel.

O WebLocal (@alemdocodigo/web-local) deteta serviços HTTP/HTTPS em portas locais, mostra-os num painel e permite abrir cada página no navegador. A terminação só fica disponível para processos reconhecidos como servidores de desenvolvimento.

Versão 0.1.2, distribuída sob licença MIT.

Requisitos

• Node.js 20 ou superior.
• Windows: PowerShell com Get-NetTCPConnection e CIM.
• macOS: lsof e ps.
• Linux: ss e acesso permitido aos dados necessários em /proc.

Executar

Sem instalação permanente:

npx @alemdocodigo/web-local

Ou com instalação global:

npm install --global @alemdocodigo/web-local
web-local

Ajuda e versão:

web-local --help
web-local --version

Durante o desenvolvimento deste repositório:

npm start

O painel abre em http://127.0.0.1:7331. Para usar outra porta:

$env:PORT = "7444"
npm start

Em shells POSIX:

PORT=7444 npm start

Utilização

O painel atualiza automaticamente a lista de serviços. Cada linha mostra a URL, porta, PID, processo, estado e duas ações:

• Os cabeçalhos Página, Porta, Processo e PID ordenam a lista nos dois sentidos.

• Abrir abre o serviço no navegador.

• Terminar pede confirmação e só é ativado quando o processo pertence ao utilizador atual, tem uma identidade temporal confirmada e corresponde à allowlist explícita de ferramentas de desenvolvimento.

Guarde o trabalho antes de terminar um processo. O WebLocal envia apenas process.kill(pid, 'SIGTERM') ao PID revalidado, sem terminar a árvore, sem elevação e sem fallback para SIGKILL. No Windows, segundo a semântica do Node.js, este sinal termina o processo de forma abrupta e incondicional.

API local

Estes são endpoints internos do painel, não uma API pública:

• GET /api/services devolve os serviços HTTP/HTTPS locais detetados, avisos e a hora da pesquisa. Exige o token da sessão no cabeçalho X-WebLocal-CSRF.
• POST /api/services/:id/terminate revalida a identidade do processo e pede a sua terminação. Exige o mesmo token, uma origem local válida e corpo JSON vazio ({}).

Segurança

• O servidor aceita ligações apenas em 127.0.0.1 e valida Host e Origin.
• A API exige um token CSRF por instância; não existe CORS.
• O painel aplica Content Security Policy e outros cabeçalhos defensivos.
• Linhas de comando completas são usadas apenas no processo local para classificação e nunca são devolvidas ao navegador.
• Antes de terminar, o WebLocal volta a enumerar o PID e confirma a identidade, o instante de início, o proprietário e a assinatura reconhecida.
• Processos Docker, WSL, de sistema, do próprio WebLocal, do processo pai ou não reconhecidos permanecem protegidos.

Limitações conhecidas

• A descoberta considera apenas serviços HTTP/HTTPS acessíveis por loopback.
• Não descobre serviços apenas dentro de Docker, WSL, VMs ou máquinas remotas.
• Não termina árvores de processos, não eleva privilégios e não usa SIGKILL.
• A descoberta e terminação foram validadas ao vivo no Windows. macOS e Linux estão cobertos por testes com fixtures, mas ainda não foram validados ao vivo.

Testes e pacote

npm test
npm pack --dry-run

Publicação

Ao publicar uma GitHub Release, o workflow publish.yml testa e publica a versão definida em package.json no npm através de Trusted Publishing (OIDC). O workflow não usa tokens npm persistentes.

Licença

MIT © 2026 Além do Código LDA.