mkdev

Vrai HTTPS pour le développement local — avec une TUI et le partage LAN.

mkdev fait tourner du HTTPS de confiance sur *.local. Un seul binaire Go : autorité de certification + proxy inverse + /etc/hosts + diffusion mDNS + une TUI complète.

Ce qui le distingue :

• Partage LAN Marquez une route comme partagée, puis accédez à https://app.local depuis votre téléphone ou tout appareil sur le même Wi-Fi.
• Une TUI, pas seulement une CLI. Table de routes en direct, journaux de requêtes, inspection des certificats, diagnostic de santé. mkdev sans argument vous y plonge directement.
• Frontière de privilèges renforcée. Vérifications du propriétaire, des droits d'écriture et des liens symboliques sur le binaire d'aide sudo avant tout appel élevé (internal/safeexec). Pas d'ombrage basé sur PATH, pas de raccourcis accessibles en écriture au groupe.
• Émission de certificats par SNI. Les certificats feuilles sont délivrés à la demande et contrôlés par une liste d'autorisation explicite knownHost. Pas de wildcard, pas de pré-génération.

Ce qu'il fait

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 est une opération unique : il génère l'AC, la fait approuver dans le magasin de certificats du système, installe et active le service utilisateur du démon (launchd / systemd), enregistre le lancement de la barre de menu à la connexion, et lance la barre immédiatement lorsqu'une session graphique est présente. Le démon possède le proxy ; la TUI (mkdev sans argument) et mkdev add | remove | list communiquent avec lui via ~/.mkdev/daemon.sock.

Partage LAN

La fonctionnalité phare de mkdev. Partagez une route vers tout appareil sur le même Wi-Fi avec un vrai TLS — sans avertissements, sans service de tunnel.

1. Dans l'onglet Domaines de la TUI, sélectionnez une route et appuyez sur s pour faire passer la colonne SHARE à LAN.
2. La route est annoncée via mDNS sous la forme <name>.local → l'IP LAN de cette machine.
3. Sur le téléphone / second ordinateur portable, accédez à https://<name>.local. Une fois que l'appareil approuve l'AC de mkdev (une seule fois), plus aucun avertissement.

Mises en garde

• Seules les routes .local sont diffusées sur mDNS. Les autres TLD continuent de passer par le proxy mais ne sont pas accessibles par nom sur le LAN.
• Les Wi-Fi d'entreprise / cloud bloquent souvent le multicast. Les Wi-Fi domestiques et de bureau fonctionnent.
• L'activation de s est immédiate — la diffusion mDNS et l'ACL côté LAN sont mises à jour à la prochaine requête. Pas de redémarrage.
• Les routes non partagées renvoient une 403 aux requêtes non-bouclage local par défense en profondeur.
• Toute personne sur le LAN peut accéder à vos routes partagées. Ne l'activez pas sur un Wi-Fi non fiable.

Installation

Homebrew (macOS, Linux)

brew install venkatkrishna07/tap/mkdev

Mise à niveau ultérieure :

brew update
brew upgrade mkdev

Go

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

Mise à niveau vers une version spécifique :

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

Téléchargement direct

Des binaires pré-compilés pour macOS (Intel + Apple Silicon), Linux (amd64 + arm64) et Windows (amd64) sont publiés sur la page des versions. Chaque version inclut checksums.txt ainsi qu'une signature cosign sans clé (checksums.txt.sig + .pem) — consultez SECURITY.md#verifying-releases pour la commande de vérification.

Sous macOS, si Gatekeeper bloque un binaire téléchargé directement :

xattr -d com.apple.quarantine ./mkdev

Depuis les sources

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

Nécessite Go 1.25+.

Première exécution

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

Après install, le démon s'exécute en arrière-plan et la barre de menu apparaît (macOS, Linux GNOME/KDE, Windows). La barre affiche l'état du démon, la liste des routes et des bascules d'activation / de partage LAN par route ; Quit ferme la barre sans arrêter le démon.

Barre de menu

La barre est l'interface toujours active. Elle se trouve dans la zone de notification et communique avec le démon via ~/.mkdev/daemon.sock. Elle se lance à la connexion (démarrage automatique enregistré par install) ; elle peut également être exécutée au premier plan avec mkdev bar.

Ce qu'elle affiche :

• Point d'état — vert actif, rouge arrêté, jaune en cours de sondage, gris éteint. Reflète la santé du démon.
• En-tête — mkdev v0.4.0 + PID du démon + durée de fonctionnement + port d'écoute du proxy.
• Routes — chaque route du registre, de haut en bas. Chaque entrée affiche name.tld → target ainsi que des badges de suffixe ( · disabled, · LAN).

Ce qu'elle fait (clic sur une route) :

• Ouvrir dans le navigateur — ouvre https://name.tld avec le gestionnaire par défaut du système.
• Copier l'URL — copie l'URL du proxy dans le presse-papiers (pbcopy / wl-copy / xclip / clip.exe).
• Activer / Désactiver — inverse le drapeau Enabled de la route. Les routes désactivées restent dans le registre mais ne sont plus proxifiées.
• Partager sur le LAN — active/désactive la diffusion mDNS + l'ACL côté LAN.

Actions au niveau de la barre :

• Arrêter le démon — appelle d'abord DisableUnit pour que KeepAlive de launchd / systemd ne le relance pas immédiatement, puis envoie un arrêt via la socket.
• Quitter — quitte uniquement le processus de la barre. Le démon et le proxy continuent de tourner.

Remarques :

• Deux instances de la barre ne peuvent pas fonctionner simultanément (verrou par fichier PID ; la seconde se ferme immédiatement).
• La barre se reconnecte automatiquement lorsque le démon redémarre. Le point d'état se met à jour sans actualisation manuelle.
• Seules la barre (et mkdev daemon stop) arrêtent proprement le démon supervisé — tuer directement le processus du démon le fera relancer par launchd / systemd.

Mise à niveau

Remplacez le binaire (brew upgrade / go install ...@latest / nouveau téléchargement). À la prochaine exécution d'une sous-commande mkdev, le binaire réconcilie les éléments qui vivent en dehors de lui : il réécrit la plist du démon / l'unité systemd et l'entrée de démarrage automatique de la barre pour pointer vers le nouveau binaire, ré-applique les entrées /etc/hosts pour les routes activées, et ré-approuve l'AC si elle a été retirée. Les invites sudo s'affichent immédiatement. Si seul le démon est en cours d'exécution et que vous ne touchez jamais à la CLI, le démon effectue les opérations sûres (sans sudo) à son propre démarrage et met le reste en file d'attente jusqu'à la prochaine commande CLI.

Ré-exécuter mkdev install fait explicitement la même chose et est toujours sans danger — chaque étape est idempotente.

Plateformes prises en charge

Distributions Linux détectées : 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 utilise son propre magasin NSS et n'est pas encore couvert — les Chrome/Safari/Edge/curl/wget du système fonctionnent tous.

Commandes

Options et environnement

Formats de cible

<target> accepte l'un des formats suivants :

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

Pour les upstreams HTTPS (par ex. un GitLab privé sur un VPN d'entreprise), le certificat TLS de l'upstream doit être vérifié par le magasin de certificats de confiance du système. Les AC privées nécessitent l'ajout de leur racine au trousseau du système d'exploitation.

hosts-helper n'est pas destiné à être appelé directement. add / remove ré-invoquent le même binaire sous sudo pour effectuer l'écriture privilégiée dans /etc/hosts.

Configuration

Remarque sur le TLD. Les routes .local nécessitent un répondeur mDNS (toujours actif sur macOS, disponible sur Linux lorsque nss-mdns est installé). .test / .dev / .localhost fonctionnent partout avec /etc/hosts seul. Définissez tld dans la configuration en conséquence.

La configuration se trouve dans ~/.mkdev/config.toml. Valeurs par défaut :

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

Remplacez le répertoire de configuration avec --home <path> ou MKDEV_HOME=....

Comment ça marche

• Génère une AC racine ECDSA P-256 dans ~/.mkdev/ca/. La clé privée est en mode 0o400.
• Installe l'AC dans le magasin de certificats natif du système : trousseau macOS (security), répertoire CA-bundle Linux + update-ca-*, magasin ROOT Windows via crypt32.dll. L'intégration du magasin de certificats est adaptée de mkcert (BSD-3) — voir LICENSE-MKCERT.
• Lors d'un add, le démon écrit une route dans un KV bbolt à ~/.mkdev/state.db et ajoute une ligne 127.0.0.1 <name>.<tld> à /etc/hosts via une sous-commande auxiliaire invoquée par sudo.

Sécurité

Cet outil installe une AC privée dans le magasin de certificats de confiance de votre système. Toute personne ayant un accès en lecture à ~/.mkdev/ca/rootCA-key.pem peut émettre des certificats TLS que votre machine approuvera. La clé est créée en 0o400 (lecture propriétaire uniquement).

• Le proxy se lie sur 0.0.0.0, mais une ACL sur la source de connexion renvoie une 403 aux requêtes LAN vers toute route non explicitement marquée partagée. Le bouclage local passe toujours.
• Pas de télémétrie. Pas d'appels distants. Pas de vérifications de mises à jour.
• add / remove invoquent sudo pour modifier /etc/hosts. Consultez SECURITY.md pour le modèle de menace et une limite connue concernant les chemins des binaires d'aide résolus via os.Executable().

Désinstallation

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

Si quelque chose reste bloqué, ouvrez Keychain Access.app, recherchez mkdev et supprimez-le à la main. Ensuite, lancez grep mkdev /etc/hosts et nettoyez les éventuels résidus.

Démon et API

Le démon possède le proxy et le registre des routes. Il expose une API HTTP locale sur ~/.mkdev/daemon.sock (propriétaire uniquement, 0600). La TUI, les sous-commandes CLI et la barre de menu sont tous des clients du démon — seul le démon détient le verrou bbolt.

mkdev install installe le démon en tant que service utilisateur (launchd LaunchAgent sur macOS, systemd --user sur Linux) et l'active. Il s'exécute en arrière-plan et survit aux déconnexions / connexions.

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

Feuille de route

À venir :

• Intégration du magasin de certificats Firefox / NSS.
• Routage par chemin (/api → 8080, /ws → 9000 sur un seul domaine).

Dépannage

• Firefox affiche une barre rouge. Firefox utilise son propre magasin NSS ; la confiance du système ne l'atteint pas. L'intégration NSS est sur la feuille de route. Pour l'instant, importez ~/.mkdev/ca/rootCA.pem manuellement dans Paramètres → Vie privée et sécurité → Certificats → Afficher les certificats → Autorités → Importer.
• Le démon n'arrive pas à se lier sur le port 443. macOS/Linux permettent aux services utilisateur non-root de se lier sur le port 443 via les capacités de launchd / systemd. Si votre distribution le restreint, définissez proxy_port = 8443 dans ~/.mkdev/config.toml et utilisez https://name.local:8443.
• mkdev add ne cesse de demander sudo. Le cache par session de sudo expire (5 min par défaut). Utilisez plutôt l'onglet Domaines de la TUI — il élève les privilèges via osascript (invite graphique macOS) ou pkexec (Polkit Linux).
• /etc/hosts contient déjà une entrée pour ce nom. mkdev add est idempotent et n'ajoute une entrée que lorsqu'aucune entrée gérée par mkdev n'existe. Supprimez l'entrée précédente à la main ou choisissez un autre nom.

Contribution

Consultez CONTRIBUTING.md.

Remerciements

L'intégration du magasin de certificats de mkdev — trousseau/security sur macOS, CA-bundle + update-ca-* sur Linux, magasin ROOT via crypt32.dll sur Windows, et les chemins adjacents à NSS — est adaptée de mkcert par Filippo Valsorda, BSD-3. Sans ce travail préalable, ce projet serait nettement plus difficile. Voir LICENSE-MKCERT pour la licence d'origine.

La TUI est construite avec Bubble Tea / Bubbles / Lipgloss de Charmbracelet. mDNS via hashicorp/mdns. KV local via bbolt.

Licence

MIT LICENSE.