mkdev

HTTPS real para desenvolvimento local — com uma TUI e compartilhamento na LAN.

mkdev executa HTTPS confiável em *.local. Um único binário Go: autoridade certificadora + proxy reverso + /etc/hosts + broadcast mDNS + uma TUI completa.

O que o torna diferente:

• Compartilhamento na LAN Marque uma rota como compartilhada e acesse https://app.local do seu celular ou de qualquer dispositivo na mesma rede Wi-Fi.
• TUI, não apenas CLI. Tabela de rotas ao vivo, logs de requisições, inspeção de certificados, verificador de saúde. mkdev sem argumentos já abre a interface.
• Limite de privilégio endurecido. Verificações de proprietário, permissão de escrita e symlinks no binário auxiliar do sudo antes de qualquer chamada elevada (internal/safeexec). Sem sombreamento baseado em PATH, sem atalhos graváveis pelo grupo.
• Emissão de certificados por SNI. Certificados folha são emitidos sob demanda e controlados por uma lista de permissões explícita knownHost. Nem curinga, nem pré-gerados.

O que ele faz

mkdev install                    # CA + trust + daemon service + menu bar autostart
mkdev add myapp localhost:3000   # routes https://myapp.local → localhost:3000
curl https://myapp.local         # 200 from your local app

install é único: gera a CA, confia nela no repositório do sistema, instala e habilita o serviço de usuário do daemon (launchd / systemd), registra a barra de menu para iniciar no login e abre a barra imediatamente quando há uma sessão gráfica ativa. O daemon é dono do proxy; a TUI (mkdev sem argumentos) e mkdev add | remove | list comunicam-se com ele via ~/.mkdev/daemon.sock.

Compartilhamento na LAN

A principal função do mkdev. Compartilhe uma rota com qualquer dispositivo na mesma rede Wi-Fi com TLS real — sem avisos, sem serviço de túnel.

1. Na aba Domains da TUI, selecione uma rota e pressione s para alternar a coluna SHARE para LAN.
2. A rota é anunciada via mDNS como <name>.local → o IP LAN desta máquina.
3. No celular / segundo notebook, acesse https://<name>.local. Depois que o dispositivo confiar na CA do mkdev (uma única vez), sem avisos.

Ressalvas

• Apenas rotas .local são transmitidas via mDNS. Outros TLDs continuam sendo proxy, mas não são alcançáveis na LAN pelo nome.
• Wi-Fi corporativo / de nuvem geralmente bloqueia multicast. Wi-Fi doméstico e de escritório funcionam.
• Alternar s é imediato — o anúncio mDNS e a ACL do lado da LAN são atualizados na próxima requisição. Sem reinício.
• Rotas não compartilhadas respondem 403 para requisições não loopback como defesa em profundidade.
• Qualquer pessoa na LAN pode acessar suas rotas compartilhadas. Não habilite em Wi-Fi não confiável.

Instalação

Homebrew (macOS, Linux)

brew install venkatkrishna07/tap/mkdev

Atualize depois:

brew update
brew upgrade mkdev

Go

go install github.com/venkatkrishna07/mkdev/cmd/mkdev@latest

Atualize para uma versão específica:

go install github.com/venkatkrishna07/mkdev/cmd/[email protected]

Download direto

Binários pré-compilados para macOS (Intel + Apple Silicon), Linux (amd64 + arm64) e Windows (amd64) são publicados na página de Releases. Cada release inclui checksums.txt além de uma assinatura cosign sem chave (checksums.txt.sig + .pem) — veja SECURITY.md#verifying-releases para o comando de verificação.

No macOS, se o Gatekeeper bloquear um binário baixado diretamente:

xattr -d com.apple.quarantine ./mkdev

A partir do código-fonte

git clone https://github.com/venkatkrishna07/mkdev.git
cd mkdev
task build
cp bin/mkdev ~/bin/        # or /usr/local/bin

Requer Go 1.25+.

Primeira execução

mkdev install   # CA, trust, daemon service, bar autostart — one command
mkdev           # launch TUI

Após install, o daemon roda em segundo plano e a barra de menu aparece (macOS, Linux GNOME/KDE, Windows). A barra mostra o status do daemon, a lista de rotas e alternâncias por rota de ativar / compartilhar na LAN; Quit sai da barra sem parar o daemon.

Barra de menu

A barra é a interface sempre ativa. Ela vive na bandeja do sistema e conversa com o daemon via ~/.mkdev/daemon.sock. Inicia no login (autostart registrado pelo install); também pode ser executada em primeiro plano com mkdev bar.

O que ela mostra:

• Ponto de status — verde ativo, vermelho inativo, amarelo verificando, cinza desligado. Reflete a saúde do daemon.
• Cabeçalho — mkdev v0.4.0 + PID do daemon + tempo de atividade + porta de escuta do proxy.
• Rotas — todas as rotas do armazenamento, de cima para baixo. Cada entrada mostra name.tld → target além de selos de sufixo ( · disabled, · LAN).

O que ela faz (clique em uma rota):

• Abrir no navegador — abre https://name.tld com o aplicativo padrão do sistema.
• Copiar URL — copia a URL do proxy para a área de transferência (pbcopy / wl-copy / xclip / clip.exe).
• Ativar / Desativar — alterna a flag Enabled da rota. Rotas desativadas permanecem no armazenamento, mas deixam de ser proxy.
• Compartilhar na LAN — alterna o anúncio mDNS + ACL do lado da LAN.

Ações da barra:

• Parar daemon — chama DisableUnit primeiro para que o KeepAlive do launchd / systemd não o reinicie imediatamente e então envia o desligamento pelo socket.
• Sair — encerra apenas o processo da barra. O daemon e o proxy continuam rodando.

Notas:

• Duas instâncias da barra não podem rodar ao mesmo tempo (trava via arquivo de PID; a segunda sai imediatamente).
• A barra se reconecta automaticamente quando o daemon reinicia. O ponto de status é atualizado sem atualização manual.
• Apenas a barra (e mkdev daemon stop) param o daemon supervisionado de forma limpa — matar o processo do daemon diretamente fará com que ele seja reiniciado pelo launchd / systemd.

Atualização

Substitua o binário (brew upgrade / go install ...@latest / novo download). Na próxima vez que você executar qualquer subcomando mkdev, o binário reconcilia as partes externas a ele: reescreve o plist do daemon / unit do systemd e a entrada de autostart da barra para apontar para o novo binário, reafirma /etc/hosts para rotas habilitadas e volta a confiar na CA se ela tiver sido removida. Os prompts de sudo são executados inline. Se você tiver apenas o daemon rodando e nunca tocar na CLI, o daemon faz as partes seguras (sem sudo) na própria inicialização e enfileira o restante até o próximo comando da CLI.

Executar mkdev install novamente faz o mesmo de forma explícita e é sempre seguro — cada etapa é idempotente.

Suporte a plataformas

Distros Linux detectadas: Debian/Ubuntu (/usr/local/share/ca-certificates), RHEL/Fedora (/etc/pki/ca-trust/source/anchors), Arch (/etc/ca-certificates/trust-source/anchors), openSUSE (/usr/share/pki/trust/anchors).

O Firefox usa seu próprio armazenamento NSS e ainda não é suportado — Chrome/Safari/Edge/curl/wget do sistema funcionam.

Comandos

Flags e ambiente

Formatos de destino

<target> aceita qualquer um dos seguintes:

host:port                  e.g. localhost:3000
http://host[:port]/path    e.g. http://localhost:3000/api
https://host[:port]/path   e.g. https://gitlab.example.com

Para upstreams HTTPS (por exemplo, um GitLab privado em uma VPN corporativa), o certificado TLS do upstream precisa ser verificado pelo repositório de confiança do sistema. CAs privadas precisam ter a raiz adicionada ao chaveiro do SO.

hosts-helper não deve ser chamado diretamente. add / remove reexecutam o mesmo binário com sudo para realizar a escrita privilegiada em /etc/hosts.

Configuração

Nota sobre TLD. Rotas .local precisam de um respondedor mDNS (sempre ativo no macOS, disponível no Linux quando nss-mdns está instalado). .test / .dev / .localhost funcionam em qualquer lugar apenas via /etc/hosts. Defina tld na configuração para corresponder.

A configuração fica em ~/.mkdev/config.toml. Padrões:

tld           = ".local"   # appended to bare names in `add`
proxy_port    = 443        # binding :443 requires sudo on serve
theme         = "auto"     # reserved for future TUI
log_retention = "7d"       # reserved
log_max_size  = "100MB"    # reserved

Substitua o diretório de configuração com --home <path> ou MKDEV_HOME=....

Como funciona

• Gera uma CA raiz ECDSA P-256 em ~/.mkdev/ca/. A chave privada tem modo 0o400.
• Instala a CA no repositório de confiança nativo do SO: Keychain do macOS (security), diretório de CA-bundle do Linux + update-ca-*, armazenamento ROOT do Windows via crypt32.dll. A integração com o repositório de confiança é adaptada do mkcert (BSD-3) — veja LICENSE-MKCERT.
• No add, o daemon grava uma rota em um KV bbolt em ~/.mkdev/state.db e acrescenta uma linha 127.0.0.1 <name>.<tld> ao /etc/hosts via um subcomando auxiliar invocado com sudo.

Segurança

Esta ferramenta instala uma CA privada no repositório de confiança do seu sistema. Qualquer pessoa com acesso de leitura a ~/.mkdev/ca/rootCA-key.pem pode emitir certificados TLS que sua máquina vai confiar. A chave é criada com modo 0o400 (somente leitura do dono).

• O proxy faz bind em 0.0.0.0, mas uma ACL de origem da conexão responde 403 para requisições da LAN a qualquer rota não marcada explicitamente como compartilhada. Loopback sempre passa.
• Sem telemetria. Sem chamadas remotas. Sem verificação de atualizações.
• add / remove invocam sudo para alterar /etc/hosts. Veja SECURITY.md para o modelo de ameaças e um limite conhecido em relação aos caminhos do auxiliar resolvidos com os.Executable().

Desinstalação

mkdev uninstall   # stops + disables daemon, untrusts CA, clears /etc/hosts,
                  # removes daemon service + bar autostart, wipes ~/.mkdev/

Se algo travar, abra o Keychain Access.app, procure por mkdev e exclua manualmente. Depois, grep mkdev /etc/hosts e limpe qualquer resíduo.

Daemon e API

O daemon é dono do proxy e do armazenamento de rotas. Ele expõe uma API HTTP local em ~/.mkdev/daemon.sock (somente dono, 0600). A TUI, os subcomandos de CLI e a barra de menu são todos clientes do daemon — apenas o daemon segura o lock do bbolt.

mkdev install instala o daemon como um serviço de usuário (launchd LaunchAgent no macOS, systemd --user no Linux) e o habilita. Ele roda em segundo plano e sobrevive a logout / login.

mkdev daemon status                # installed / enabled / running
mkdev daemon stop                  # stop + disable (prevents respawn)
curl --unix-socket ~/.mkdev/daemon.sock http://x/v1/status
curl --unix-socket ~/.mkdev/daemon.sock http://x/v1/routes
curl --unix-socket ~/.mkdev/daemon.sock -X POST http://x/v1/routes \
     -H 'Content-Type: application/json' \
     -d '{"name":"foo","target":"localhost:3000"}'
curl --unix-socket ~/.mkdev/daemon.sock -X DELETE http://x/v1/routes/foo

Roadmap

A seguir:

• Integração com o repositório de confiança do Firefox / NSS.
• Roteamento por caminho (/api → 8080, /ws → 9000 em um único domínio).

Solução de problemas

• O Firefox mostra uma barra vermelha. O Firefox usa seu próprio armazenamento NSS; a confiança do sistema não chega até ele. A integração com NSS está no roadmap. Por enquanto, importe ~/.mkdev/ca/rootCA.pem manualmente em Configurações → Privacidade e Segurança → Certificados → Ver Certificados → Autoridades → Importar.
• O daemon não consegue fazer bind na porta :443. macOS/Linux permitem que serviços de usuário não-root façam bind na :443 via capacidades do launchd / systemd. Se sua distro restringir isso, defina proxy_port = 8443 em ~/.mkdev/config.toml e use https://name.local:8443.
• mkdev add fica pedindo sudo. O cache por sessão do sudo expira (padrão de 5 min). Use a aba Domains da TUI — ela eleva privilégios via osascript (prompt gráfico no macOS) ou pkexec (Polkit no Linux).
• /etc/hosts já tem uma entrada para esse nome. mkdev add é idempotente e só acrescenta quando não existe uma entrada gerenciada pelo mkdev. Remova a entrada anterior manualmente ou escolha outro nome.

Contribuição

Veja CONTRIBUTING.md.

Agradecimentos

A integração do mkdev com repositórios de confiança — Keychain/security no macOS, CA-bundle + update-ca-* no Linux, armazenamento ROOT via crypt32.dll no Windows e caminhos adjacentes ao NSS — é adaptada do mkcert de Filippo Valsorda, BSD-3. Sem esse trabalho anterior, este projeto seria consideravelmente mais difícil. Veja LICENSE-MKCERT para a licença upstream.

A TUI é construída com Bubble Tea / Bubbles / Lipgloss do Charmbracelet. mDNS via hashicorp/mdns. KV local via bbolt.

Licença

MIT LICENSE.