mkdev

HTTPS reale per sviluppo locale — con una TUI e condivisione LAN.

mkdev esegue HTTPS fidato su *.local. Un singolo binario Go: autorità di certificazione + proxy inverso + /etc/hosts + broadcast mDNS + una TUI completa.

Cosa lo rende diverso:

• Condivisione LAN Segna una route come condivisa, accedi a https://app.local dal tuo telefono o qualsiasi dispositivo sulla stessa Wi-Fi.
• TUI, non solo una CLI. Tabella delle route live, log delle richieste, ispezione dei certificati, health doctor. mkdev senza argomenti ti apre la TUI.
• Boundary dei privilegi rinforzato. Controlli del proprietario, scrivibilità e symlink sul binario helper sudo prima di qualsiasi chiamata elevata (internal/safeexec). Nessun shadowing basato su PATH, nessuna scorciatoia scrivibile da gruppo.
• Emissione di certificati per SNI. I certificati foglia vengono emessi su richiesta e limitati da un allow-list knownHost esplicito. Non wildcard, non pre-generati.

Cosa fa

mkdev install                    # CA + trust + servizio daemon + avvio automatico barra menu
mkdev add myapp localhost:3000   # route https://myapp.local → localhost:3000
curl https://myapp.local         # 200 dalla tua app locale

install è unico: genera la CA, la rende fidata nel sistema, installa e abilita il servizio utente del daemon (launchd / systemd), registra la barra menu per l'avvio al login e avvia immediatamente la barra quando una sessione GUI è presente. Il daemon possiede il proxy; la TUI (mkdev senza argomenti) e mkdev add | remove | list comunicano con esso tramite ~/.mkdev/daemon.sock.

Condivisione LAN

La funzionalità principale di mkdev. Condividi una route a qualsiasi dispositivo sulla stessa Wi-Fi con TLS reale — nessun avviso, nessun servizio tunnel.

1. Nella scheda Domini della TUI, seleziona una route e premi s per cambiare la colonna SHARE a LAN.
2. La route viene annunciata via mDNS come <name>.local → indirizzo IP LAN di questa macchina.
3. Sul telefono / secondo laptop, naviga su https://<name>.local. Una volta che il dispositivo ha fiducia nella CA di mkdev (una tantum), nessun avviso.

Avvertenze

• Solo le route .local vengono trasmesse su mDNS. Altre TLD fanno ancora da proxy ma non sono raggiungibili in LAN per nome.
• Le Wi-Fi aziendali / cloud spesso bloccano il multicast. Le reti domestiche e ufficio funzionano.
• L'attivazione con s è live — la pubblicità mDNS e l'ACL lato LAN vengono aggiornate alla prossima richiesta. Nessun riavvio.
• Le route non condivise rispondono con 403 alle richieste non loopback come difesa in profondità.
• Chiunque sulla LAN può colpire le tue route condivise. Non abilitare su Wi-Fi non fidato.

Installazione

Homebrew (macOS, Linux)

brew install venkatkrishna07/tap/mkdev

Aggiorna successivamente:

brew update
brew upgrade mkdev

Go

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

Aggiorna a una versione specifica:

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

Download diretto

Binari precompilati per macOS (Intel + Apple Silicon), Linux (amd64 + arm64) e Windows (amd64) sono pubblicati sulla pagina Releases. Ogni release include checksums.txt più una firma cosign keyless (checksums.txt.sig + .pem) — consulta SECURITY.md#verifying-releases per il comando di verifica.

Su macOS, se Gatekeeper blocca un binario scaricato direttamente:

xattr -d com.apple.quarantine ./mkdev

Dal sorgente

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

Richiede Go 1.25+.

Primo avvio

mkdev install   # CA, trust, servizio daemon, avvio automatico barra — un comando
mkdev           # avvia TUI

Dopo install, il daemon viene eseguito in background e appare la barra menu (macOS, Linux GNOME/KDE, Windows). La barra mostra lo stato del daemon, l'elenco delle route e gli switch per abilitare/condividere LAN per singola route; Quit esce dalla barra senza fermare il daemon.

Barra menu

La barra è l'interfaccia sempre attiva. Vive nella tray di sistema e comunica con il daemon tramite ~/.mkdev/daemon.sock. Si avvia al login (avvio automatico registrato da install); eseguibile anche in primo piano con mkdev bar.

Cosa mostra:

• Punto di stato — verde attivo, rosso fermo, giallo in attesa, grigio spento. Rispecchia la salute del daemon.
• Intestazione — mkdev v0.4.0 + PID del daemon + uptime + porta del proxy in ascolto.
• Route — ogni route nel repository, dall'alto verso il basso. Ogni voce mostra name.tld → target più badge di suffisso ( · disabilitato, · LAN).

Cosa fa (clicca su una route):

• Apri nel browser — apre https://name.tld con il gestore predefinito del sistema.
• Copia URL — copia l'URL del proxy negli appunti (pbcopy / wl-copy / xclip / clip.exe).
• Abilita / Disabilita — cambia il flag Enabled della route. Le route disabilitate rimangono nel repository ma smettono di essere proxate.
• Condividi su LAN — attiva/disattiva la pubblicità mDNS + ACL lato LAN.

Azioni a livello di barra:

• Ferma daemon — chiama prima DisableUnit così launchd / systemd KeepAlive non lo riavvia immediatamente, poi invia shutdown via socket.
• Esci — esce solo dal processo barra. Il daemon e il proxy continuano a funzionare.

Note:

• Due istanze della barra non possono funzionare contemporaneamente (lock su PID-file; la seconda esce immediatamente).
• La barra si riconnette automaticamente quando il daemon riparte. Il punto di stato si aggiorna senza aggiornamento manuale.
• Solo la barra (e mkdev daemon stop) fermano pulitamente il daemon supervisionato — uccidere direttamente il processo daemon lo farà riavviare da launchd / systemd.

Aggiornamento

Sostituisci il binario (brew upgrade / go install ...@latest / nuovo download). La prossima volta che esegui un qualsiasi sottocomando mkdev, il binario riconcilia le parti che vivono fuori di esso: riscrive il plist del daemon / unità systemd e la voce di avvio automatico della barra per puntare al nuovo binario, riafferma /etc/hosts per le route abilitate e riaffida la CA se è stata rimossa. Le richieste sudo vengono eseguite inline. Se hai solo il daemon in esecuzione e non tocchi mai la CLI, il daemon fa le parti sicure (senza sudo) all'avvio e accoda il resto fino al prossimo comando CLI.

Rieseguire mkdev install fa la stessa cosa in modo esplicito ed è sempre sicuro — ogni passo è idempotente.

Supporto piattaforme

Distribuzioni Linux rilevate: 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).

Firefox utilizza il proprio store NSS e non è ancora coperto — Chrome/Safari/Edge/curl/wget di sistema funzionano tutti.

Comandi

Flag e ambiente

Formati target

<target> accetta uno qualsiasi di:

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

Per upstream HTTPS (es. un GitLab privato su VPN aziendale), il certificato TLS dell'upstream deve essere verificabile dallo store di fiducia del sistema. Le CA private devono avere la loro root aggiunta al keychain di sistema.

hosts-helper non è destinato ad essere chiamato direttamente. add / remove richiamano lo stesso binario sotto sudo per eseguire la scrittura privilegiata di /etc/hosts.

Configurazione

Nota TLD. Le route .local necessitano di un responder mDNS (sempre attivo su macOS, disponibile su Linux quando nss-mdns è installato). .test / .dev / .localhost funzionano ovunque solo tramite /etc/hosts. Imposta tld nella configurazione per corrispondere.

La configurazione vive in ~/.mkdev/config.toml. Valori predefiniti:

tld           = ".local"   # aggiunto ai nomi nudi in `add`
proxy_port    = 443        # binding :443 richiede sudo per servire
theme         = "auto"     # riservato per la futura TUI
log_retention = "7d"       # riservato
log_max_size  = "100MB"    # riservato

Sostituisci la directory di configurazione con --home <percorso> o MKDEV_HOME=....

Come funziona

• Genera una CA root ECDSA P-256 in ~/.mkdev/ca/. La chiave privata è in modalità 0o400.
• Installa la CA nello store di fiducia nativo del sistema: Keychain macOS (security), directory CA-bundle Linux + update-ca-*, store ROOT Windows tramite crypt32.dll. L'integrazione dello store di fiducia è adattata da mkcert (BSD-3) — vedi LICENSE-MKCERT.
• Su add, il daemon scrive una route in un KV bbolt su ~/.mkdev/state.db e aggiunge una riga 127.0.0.1 <nome>.<tld> a /etc/hosts tramite un sottocomando helper invocato con sudo.

Sicurezza

Questo strumento installa una CA privata nel tuo store di fiducia di sistema. Chiunque abbia accesso in lettura a ~/.mkdev/ca/rootCA-key.pem può emettere certificati TLS che la tua macchina considererà fidati. La chiave viene creata 0o400 (solo proprietario in lettura).

• Il proxy fa bind su 0.0.0.0, ma un ACL basato sull'origine della connessione dà 403 alle richieste LAN per qualsiasi route non esplicitamente marcata condivisa. Il loopback passa sempre.
• Nessuna telemetria. Nessuna chiamata remota. Nessun controllo aggiornamenti.
• add / remove invocano sudo per modificare /etc/hosts. Vedi SECURITY.md per il modello di minaccia e un limite noto riguardo ai percorsi helper risolti da os.Executable().

Disinstallazione

mkdev uninstall   # ferma + disabilita daemon, rimuovi fiducia CA, pulisci /etc/hosts,
                  # rimuovi servizio daemon + avvio automatico barra, cancella ~/.mkdev/

Se qualcosa si blocca, apri Keychain Access.app, cerca mkdev e cancellalo a mano. Poi grep mkdev /etc/hosts e pulisci eventuali resti.

Daemon e API

Il daemon possiede il proxy e il repository delle route. Espone un'API HTTP locale su ~/.mkdev/daemon.sock (solo proprietario 0600). La TUI, i sottocomandi CLI e la barra menu sono tutti client del daemon — solo il daemon detiene il lock bbolt.

mkdev install installa il daemon come servizio utente (launchd LaunchAgent su macOS, systemd --user su Linux) e lo abilita. Viene eseguito in background e sopravvive al logout / login.

mkdev daemon status                # installato / abilitato / in esecuzione
mkdev daemon stop                  # ferma + disabilita (previene riavvio)
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

Prossimamente:

• Integrazione store di fiducia Firefox / NSS.
• Routing per path (/api → 8080, /ws → 9000 su un singolo dominio).

Risoluzione problemi

• Firefox mostra una barra rossa. Firefox usa il proprio store NSS; la fiducia di sistema non lo raggiunge. L'integrazione NSS è nella roadmap. Per ora, importa ~/.mkdev/ca/rootCA.pem manualmente sotto Impostazioni → Privacy e sicurezza → Certificati → Visualizza certificati → Autorità → Importa.
• Il daemon non riesce a fare binding su :443. Su macOS/Linux i servizi utente non root possono fare binding su :443 tramite capacità di launchd / systemd. Se la tua distribuzione lo restringe, imposta proxy_port = 8443 in ~/.mkdev/config.toml e usa https://name.local:8443.
• mkdev add continua a chiedere sudo. La cache per sessione di sudo scade (default 5 min). Usa la scheda Domini della TUI invece — eleva tramite osascript (prompt GUI macOS) o pkexec (Linux Polkit).
• /etc/hosts ha già una riga per quel nome. mkdev add è idempotente e aggiunge solo quando non esiste una riga gestita da mkdev. Rimuovi la riga precedente a mano o scegli un nome diverso.

Contribuire

Vedi CONTRIBUTING.md.

Ringraziamenti

L'integrazione dello store di fiducia di mkdev — Keychain/security su macOS, CA-bundle + update-ca-* su Linux, store ROOT crypt32.dll su Windows e i percorsi NSS adiacenti — è adattata da mkcert di Filippo Valsorda, BSD-3. Senza quel lavoro precedente, questo progetto sarebbe sostanzialmente più difficile. Vedi LICENSE-MKCERT per la licenza upstream.

La TUI è costruita con Charmbracelet's Bubble Tea / Bubbles / Lipgloss. mDNS tramite hashicorp/mdns. KV locale tramite bbolt.

Licenza

MIT LICENSE.