mkdev

HTTPS real para desarrollo local — con TUI y uso compartido en LAN.

mkdev ejecuta HTTPS de confianza en *.local. Un único binario Go: autoridad de certificados + proxy inverso + /etc/hosts + difusión mDNS + un TUI completo.

Qué lo hace diferente:

• Uso compartido en LAN Marca una ruta como compartida y accede a https://app.local desde tu teléfono o cualquier dispositivo en la misma Wi-Fi.
• TUI, no solo una CLI. Tabla de rutas en vivo, registros de solicitudes, inspección de certificados, doctor de salud. mkdev sin argumentos te lleva directo.
• Límite de privilegios reforzado. Comprobaciones de propietario, escritura y enlaces simbólicos en el binario auxiliar de sudo antes de cualquier llamada elevada (internal/safeexec). Sin suplantación basada en PATH, sin atajos escribibles por el grupo.
• Emisión de certificados por SNI. Los certificados hoja se emiten bajo demanda y están restringidos por una lista de permitidos knownHost explícita. Ni comodín ni pregenerados.

Qué hace

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 es de una sola pasada: genera la CA, la confía en el almacén del sistema, instala y habilita el servicio de usuario del daemon (launchd / systemd), registra la barra de menú para que se inicie al iniciar sesión y la lanza inmediatamente cuando hay una sesión gráfica presente. El daemon es el propietario del proxy; el TUI (mkdev sin argumentos) y mkdev add | remove | list se comunican con él a través de ~/.mkdev/daemon.sock.

Uso compartido en LAN

La función estrella de mkdev. Comparte una ruta con cualquier dispositivo en la misma Wi-Fi con TLS real — sin advertencias, sin servicio de túnel.

1. En la pestaña Domains del TUI, selecciona una ruta y pulsa s para cambiar la columna SHARE a LAN.
2. La ruta se anuncia vía mDNS como <name>.local → la IP LAN de esta máquina.
3. En el teléfono / segundo portátil, navega a https://<name>.local. Una vez que el dispositivo confía en la CA de mkdev (una sola vez), no hay advertencias.

Advertencias

• Solo las rutas .local se difunden por mDNS. Otros TLD siguen haciendo de proxy pero no son alcanzables en LAN por nombre.
• Las Wi-Fi corporativas / en la nube suelen bloquear el multicast. Las Wi-Fi domésticas y de oficina funcionan.
• Alternar s es en vivo — el anuncio mDNS y la ACL del lado LAN se actualizan en la siguiente solicitud. Sin reinicio.
• Las rutas no compartidas devuelven 403 a las solicitudes no loopback como defensa en profundidad.
• Cualquiera en la LAN puede acceder a tus rutas compartidas. No lo actives en Wi-Fi no confiable.

Instalación

Homebrew (macOS, Linux)

brew install venkatkrishna07/tap/mkdev

Actualiza más tarde:

brew update
brew upgrade mkdev

Go

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

Actualiza a una versión específica:

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

Descarga directa

Los binarios precompilados para macOS (Intel + Apple Silicon), Linux (amd64 + arm64) y Windows (amd64) se publican en la página de Releases. Cada versión incluye checksums.txt más una firma cosign sin clave (checksums.txt.sig + .pem) — consulta SECURITY.md#verifying-releases para el comando de verificación.

En macOS, si Gatekeeper bloquea un binario descargado directamente:

xattr -d com.apple.quarantine ./mkdev

Desde el código fuente

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

Requiere Go 1.25+.

Primera ejecución

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

Después de install, el daemon se ejecuta en segundo plano y aparece la barra de menú (macOS, Linux GNOME/KDE, Windows). La barra muestra el estado del daemon, la lista de rutas y los interruptores por ruta de habilitar / compartir en LAN; Quit cierra la barra sin detener el daemon.

Barra de menú

La barra es la interfaz siempre activa. Vive en la bandeja del sistema y se comunica con el daemon a través de ~/.mkdev/daemon.sock. Se inicia al iniciar sesión (autoinicio registrado por install); también se puede ejecutar en primer plano con mkdev bar.

Qué muestra:

• Punto de estado — verde activo, rojo caído, amarillo sondeando, gris apagado. Refleja la salud del daemon.
• Cabecera — mkdev v0.4.0 + PID del daemon + tiempo de actividad + puerto de escucha del proxy.
• Rutas — todas las rutas del almacén, de arriba a abajo. Cada entrada muestra name.tld → target más insignias de sufijo ( · disabled, · LAN).

Qué hace (clic en una ruta):

• Abrir en el navegador — abre https://name.tld con el manejador predeterminado del sistema.
• Copiar URL — copia la URL del proxy al portapapeles (pbcopy / wl-copy / xclip / clip.exe).
• Habilitar / Deshabilitar — cambia el indicador Enabled de la ruta. Las rutas deshabilitadas permanecen en el almacén pero dejan de pasar por el proxy.
• Compartir en LAN — alterna el anuncio mDNS + la ACL del lado LAN.

Acciones a nivel de barra:

• Detener daemon — llama primero a DisableUnit para que launchd / systemd KeepAlive no lo reinicie inmediatamente, y luego envía el apagado a través del socket.
• Salir — cierra solo el proceso de la barra. El daemon y el proxy siguen ejecutándose.

Notas:

• No pueden ejecutarse dos instancias de la barra a la vez (bloqueo por archivo PID; la segunda sale inmediatamente).
• La barra se reconecta automáticamente cuando el daemon se reinicia. El punto de estado se actualiza sin necesidad de actualización manual.
• Solo la barra (y mkdev daemon stop) detienen limpiamente el daemon supervisado — matar el proceso del daemon directamente hará que launchd / systemd lo reinicie.

Actualización

Reemplaza el binario (brew upgrade / go install ...@latest / nueva descarga). La próxima vez que ejecutes cualquier subcomando mkdev, el binario reconcilia las partes que viven fuera de él: reescribe el plist del daemon / la unidad de systemd y la entrada de autoinicio de la barra para que apunten al nuevo binario, vuelve a aplicar las entradas de /etc/hosts para las rutas habilitadas y vuelve a confiar en la CA si se eliminó. Los avisos de sudo se ejecutan en línea. Si solo tienes el daemon ejecutándose y nunca tocas la CLI, el daemon hace las partes seguras (sin sudo) en su propio inicio y pone en cola el resto hasta el siguiente comando de la CLI.

Volver a ejecutar mkdev install hace lo mismo explícitamente y siempre es seguro — cada paso es idempotente.

Plataformas compatibles

Distribuciones 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).

Firefox usa su propio almacén NSS y aún no está cubierto — Chrome/Safari/Edge/curl/wget del sistema funcionan todos.

Comandos

Banderas y entorno

Formatos de destino

<target> acepta cualquiera de estos:

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 orígenes HTTPS (p. ej., un GitLab privado en una VPN corporativa), el certificado TLS del origen debe verificarse contra el almacén de confianza del sistema. Las CA privadas necesitan que su raíz se añada al llavero del sistema operativo.

hosts-helper no está pensado para llamarse directamente. add / remove vuelven a invocar el mismo binario bajo sudo para realizar la escritura privilegiada en /etc/hosts.

Configuración

Nota sobre TLD. Las rutas .local necesitan un respondedor mDNS (siempre activo en macOS, disponible en Linux cuando nss-mdns está instalado). .test / .dev / .localhost funcionan en todas partes solo con /etc/hosts. Establece tld en la configuración para que coincida.

La configuración vive en ~/.mkdev/config.toml. Valores predeterminados:

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

Sobrescribe el directorio de configuración con --home <path> o MKDEV_HOME=....

Cómo funciona

• Genera una CA raíz ECDSA P-256 en ~/.mkdev/ca/. La clave privada tiene modo 0o400.
• Instala la CA en el almacén de confianza nativo del sistema operativo: Llavero de macOS (security), directorio de paquete de CA de Linux + update-ca-*, almacén ROOT de Windows vía crypt32.dll. La integración con el almacén de confianza está adaptada de mkcert (BSD-3) — consulta LICENSE-MKCERT.
• En add, el daemon escribe una ruta en un KV bbolt en ~/.mkdev/state.db y agrega una línea 127.0.0.1 <name>.<tld> a /etc/hosts mediante un subcomando auxiliar invocado con sudo.

Seguridad

Esta herramienta instala una CA privada en el almacén de confianza de tu sistema. Cualquiera con acceso de lectura a ~/.mkdev/ca/rootCA-key.pem puede emitir certificados TLS en los que tu máquina confiará. La clave se crea 0o400 (solo lectura para el propietario).

• El proxy se vincula a 0.0.0.0, pero una ACL de origen de conexión devuelve 403 a las solicitudes LAN hacia cualquier ruta no marcada explícitamente como compartida. Loopback siempre pasa.
• Sin telemetría. Sin llamadas remotas. Sin comprobaciones de actualización.
• add / remove invocan sudo para mutar /etc/hosts. Consulta SECURITY.md para el modelo de amenazas y un límite conocido en torno a las rutas auxiliares resueltas con os.Executable().

Desinstalación

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

Si algo se queda atascado, abre Keychain Access.app, busca mkdev y elimínalo a mano. Luego grep mkdev /etc/hosts y limpia cualquier resto.

Daemon y API

El daemon es el propietario del proxy y del almacén de rutas. Expone una API HTTP local en ~/.mkdev/daemon.sock (solo propietario 0600). El TUI, los subcomandos de la CLI y la barra de menú son todos clientes del daemon — solo el daemon tiene el bloqueo de bbolt.

mkdev install instala el daemon como un servicio de usuario (LaunchAgent de launchd en macOS, --user de systemd en Linux) y lo habilita. Se ejecuta en segundo plano y sobrevive al cierre / inicio de sesión.

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

Hoja de ruta

Próximamente:

• Integración del almacén de confianza de Firefox / NSS.
• Enrutamiento por ruta (/api → 8080, /ws → 9000 en un solo dominio).

Solución de problemas

• Firefox muestra una barra roja. Firefox usa su propio almacén NSS; la confianza del sistema no llega hasta él. La integración NSS está en la hoja de ruta. Por ahora, importa ~/.mkdev/ca/rootCA.pem manualmente en Configuración → Privacidad y seguridad → Certificados → Ver certificados → Autoridades → Importar.
• El daemon no puede vincularse a :443. macOS/Linux permiten que los servicios de usuario no root se vinculen a :443 mediante las capacidades de launchd / systemd. Si tu distribución restringe esto, establece proxy_port = 8443 en ~/.mkdev/config.toml y usa https://name.local:8443.
• mkdev add sigue pidiendo sudo. La caché por sesión de sudo caduca (5 min por defecto). Usa en su lugar la pestaña Domains del TUI — eleva privilegios vía osascript (aviso GUI de macOS) o pkexec (Polkit de Linux).
• /etc/hosts ya tiene una entrada para ese nombre. mkdev add es idempotente y solo agrega cuando no existe ninguna entrada gestionada por mkdev. Elimina la entrada anterior a mano o elige un nombre diferente.

Contribuciones

Consulta CONTRIBUTING.md.

Agradecimientos

La integración del almacén de confianza de mkdev — Keychain/security en macOS, paquete de CA + update-ca-* en Linux, almacén ROOT de crypt32.dll en Windows y las rutas adyacentes a NSS — está adaptada de mkcert de Filippo Valsorda, BSD-3. Sin ese trabajo previo, este proyecto sería sustancialmente más difícil. Consulta LICENSE-MKCERT para la licencia original.

El TUI está construido con Bubble Tea / Bubbles / Lipgloss de Charmbracelet. mDNS vía hashicorp/mdns. KV local vía bbolt.

Licencia

MIT LICENSE.