mkdev

HTTPS حقيقي للتطوير المحلي — مع واجهة TUI ومشاركة الشبكة المحلية (LAN).

mkdev يدير HTTPS موثوقًا على *.local. ملف ثنائي واحد بلغة Go: سلطة التصديق + وكيل عكسي + /etc/hosts + بث mDNS + واجهة TUI كاملة.

ما يجعله مختلفًا:

• مشاركة الشبكة المحلية (LAN) ضع علامة على مسار كمشارَك، ثم تصفح https://app.local من هاتفك أو أي جهاز على نفس شبكة Wi-Fi.
• TUI، وليس CLI فقط. جدول مسارات حي، سجلات الطلبات، فحص الشهادات، طبيب الصحة. mkdev بدون معاملات يفتحها لك.
• حدود صلاحيات محصّنة. فحوصات المالك، قابلية الكتابة، والروابط الرمزية على ملف المساعد sudo قبل أي استدعاء برفع صلاحيات (internal/safeexec). لا تظليل يعتمد على PATH، ولا اختصارات قابلة للكتابة للمجموعة.
• إصدار شهادات لكل SNI. يتم إصدار الشهادات الفرعية حسب الطلب وتكون مقيدة بقائمة السماح الصريحة knownHost. ليست شهادة wildcard، ولا معدّة مسبقًا.

ما يفعله

mkdev install                    # CA + الثقة + خدمة الخفيّة + بدء شريط القوائم تلقائيًا
mkdev add myapp localhost:3000   # يوجه https://myapp.local ← localhost:3000
curl https://myapp.local         # 200 من تطبيقك المحلي

install هي عملية لمرة واحدة: ينشئ CA، ويثق به في مخزن النظام، ويُثبت ويفعّل خدمة الخفيّة للمستخدم (launchd / systemd)، ويسجّل شريط القوائم ليبدأ عند تسجيل الدخول، ويُشغّل الشريط فورًا عند وجود جلسة GUI. الخفيّة تمتلك الوكيل؛ وواجهة TUI (mkdev بدون معاملات) وأوامر mkdev add | remove | list تتواصل معها عبر ~/.mkdev/daemon.sock.

مشاركة الشبكة المحلية (LAN)

الميزة الرئيسية لـ mkdev. شارك مسارًا مع أي جهاز على نفس Wi-Fi مع TLS حقيقي — بدون تحذيرات، بدون خدمة نفق.

1. في علامة "المجالات" (Domains) في TUI، اختر مسارًا واضغط s لتحويل عمود SHARE إلى LAN.
2. يتم الإعلان عن المسار عبر mDNS باسم <name>.local ← عنوان IP للجهاز على الشبكة المحلية.
3. على الهاتف / اللابتوب الثاني، تصفّح https://<name>.local. بمجرد أن يثق الجهاز في CA الخاص بـ mkdev (مرة واحدة)، لن تظهر تحذيرات.

ملاحظات

• فقط مسارات .local تُبث عبر mDNS. الامتدادات الأخرى لا تزال تُوكَل ولكن لا يمكن الوصول إليها عبر LAN بالاسم.
• شبكات Wi-Fi الخاصة بالشركات / السحابية غالبًا ما تحجب البث المتعدد (multicast). شبكات المنزل والمكتب تعمل.
• التبديل s هو حي — إعلان mDNS وقائمة التحكم في الوصول على LAN تُحدّث عند الطلب التالي. لا حاجة لإعادة التشغيل.
• المسارات غير المشارَكة تُعيد 403 للطلبات غير القادمة من الحلقة المحلية كإجراء أمني عميق.
• أي شخص على LAN يمكنه الوصول إلى مساراتك المشارَكة. لا تفعّلها على Wi-Fi غير موثوق.

التثبيت

Homebrew (macOS, Linux)

brew install venkatkrishna07/tap/mkdev

الترقية لاحقًا:

brew update
brew upgrade mkdev

Go

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

الترقية إلى إصدار معين:

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

تحميل مباشر

الملفات الثنائية المبنية مسبقًا لأنظمة macOS (Intel + Apple Silicon)، Linux (amd64 + arm64)، وWindows (amd64) منشورة على صفحة الإصدارات. كل إصدار يتضمن checksums.txt بالإضافة إلى توقيع cosign بدون مفتاح (checksums.txt.sig + .pem) — انظر SECURITY.md#verifying-releases لأمر التحقق.

على macOS، إذا منع Gatekeeper ملفًا ثنائيًا تم تحميله مباشرة:

xattr -d com.apple.quarantine ./mkdev

من المصدر

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

يتطلب Go 1.25+.

التشغيل الأول

mkdev install   # CA، الثقة، خدمة الخفيّة، بدء الشريط تلقائيًا — أمر واحد
mkdev           # تشغيل TUI

بعد install، تعمل الخفيّة في الخلفية ويظهر شريط القوائم (macOS، Linux GNOME/KDE، Windows). يُظهر الشريط حالة الخفيّة، قائمة المسارات، ومفاتيح التمكين / مشاركة LAN لكل مسار؛ Quit يُخرج من الشريط دون إيقاف الخفيّة.

شريط القوائم

الشريط هو واجهة المستخدم الدائمة. يوجد في علبة النظام ويتواصل مع الخفيّة عبر ~/.mkdev/daemon.sock. يبدأ عند تسجيل الدخول (تم تسجيل التشغيل التلقائي بواسطة install)؛ يمكن أيضًا تشغيله في الواجهة الأمامية باستخدام mkdev bar.

ما يُظهره:

• نقطة الحالة — أخضر: شغال، أحمر: معطل، أصفر: قيد الفحص، رمادي: متوقف. تعكس صحة الخفيّة.
• الرأس — mkdev v0.4.0 + معرف عملية الخفيّة + وقت التشغيل + منفذ الوكيل المستمع.
• المسارات — كل مسار في المخزن، من الأعلى إلى الأسفل. كل إدخال يُظهر name.tld → target بالإضافة إلى شارات لاحقة ( · disabled، · LAN).

ما يفعله (انقر على مسار):

• فتح في المتصفح — يفتح https://name.tld باستخدام المعالج الافتراضي للنظام.
• نسخ الرابط — ينسخ رابط الوكيل إلى الحافظة (pbcopy / wl-copy / xclip / clip.exe).
• تمكين / تعطيل — يقلب علامة Enabled للمسار. المسارات المعطلة تبقى في المخزن ولكن تتوقف عن التوكيل.
• مشاركة على LAN — يبدّل إعلان mDNS وقائمة التحكم في الوصول على LAN.

إجراءات على مستوى الشريط:

• إيقاف الخفيّة — يستدعي DisableUnit أولاً حتى لا يعيد launchd / systemd KeepAlive تشغيلها فورًا، ثم يرسل أمر إيقاف عبر المقبس.
• خروج — يُنهي عملية الشريط فقط. الخفيّة والوكيل يظلان قيد التشغيل.

ملاحظات:

• لا يمكن تشغيل نسختين من الشريط في نفس الوقت (قفل ملف PID؛ الثانية تخرج فورًا).
• الشريط يعيد الاتصال تلقائيًا عند إعادة تشغيل الخفيّة. يتم تحديث نقطة الحالة دون تحديث يدوي.
• فقط الشريط (و mkdev daemon stop) يُوقف الخفيّة التي تحت الإشراف بشكل نظيف — قتل عملية الخفيّة مباشرة سيعيد تشغيلها بواسطة launchd / systemd.

الترقية

استبدل الملف الثنائي (brew upgrade / go install ...@latest / تحميل جديد). في المرة التالية التي تشغّل فيها أي أمر فرعي mkdev، يقوم الملف الثنائي بمطابقة الأجزاء التي تقع خارجه: يعيد كتابة plist / systemd unit للخفيّة وإدخال بدء الشريط التلقائي للإشارة إلى الملف الثنائي الجديد، ويعيد تأكيد /etc/hosts للمسارات المفعّلة، ويعيد الثقة في CA إذا تم إسقاطها. تظهر مطالبات sudo داخلية. إذا كان لديك فقط الخفيّة قيد التشغيل ولم تستخدم CLI، فإن الخفيّة تقوم بالأجزاء الآمنة (بدون sudo) بنفسها عند بدء التشغيل وتنتظر الباقي حتى أمر CLI التالي.

إعادة تشغيل mkdev install تفعل نفس الشيء بشكل صريح وهي آمنة دائمًا — كل خطوة هي idempotent.

دعم المنصات

توزيعات Linux المدعومة: 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 يستخدم مخزن NSS الخاص به ولم يتم تغطيته بعد — المتصفحات Chrome وSafari وEdge وcurl وwget في النظام تعمل جميعًا.

الأوامر

العلامات والبيئة

صيغ الهدف

<target> يقبل أيًا من:

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

بالنسبة للمصادر upstream HTTPS (مثل GitLab خاص على VPN شركة)، يجب التحقق من شهادة TLS الخاصة بالمصدر upstream مقابل مخزن الثقة للنظام. تحتاج CAs الخاصة إلى إضافة جذرها إلى سلسلة مفاتيح النظام.

hosts-helper ليس مخصصًا للاستدعاء المباشر. add / remove يعيدان استدعاء نفس الملف الثنائي تحت sudo لإجراء الكتابة المميزة إلى /etc/hosts.

الإعدادات

ملاحظة حول TLD. مسارات .local تحتاج إلى مستجيب mDNS (دائم التشغيل على macOS، متاح على Linux عند تثبيت nss-mdns). مسارات .test / .dev / .localhost تعمل في كل مكان عبر /etc/hosts وحده. اضبط tld في الإعدادات ليتوافق.

الإعدادات موجودة في ~/.mkdev/config.toml. الإعدادات الافتراضية:

tld           = ".local"   # يُلحق بالأسماء المجردة في `add`
proxy_port    = 443        # ربط :443 يتطلب sudo عند الخدمة
theme         = "auto"     # محجوز لواجهة TUI المستقبلية
log_retention = "7d"       # محجوز
log_max_size  = "100MB"    # محجوز

تجاوز دليل الإعدادات بـ --home <path> أو MKDEV_HOME=....

كيفية عمله

• يُنشئ جذر CA بمنحنى ECDSA P-256 في ~/.mkdev/ca/. المفتاح الخاص هو وضع 0o400.
• يُثبت CA في مخزن الثقة الأصلي للنظام: Keychain في macOS (security)، دليل حزمة CA في Linux + update-ca-*، مخزن ROOT في Windows عبر crypt32.dll. تكامل مخزن الثقة مقتبس من mkcert (BSD-3) — انظر LICENSE-MKCERT.
• عند add، تكتب الخفيّة مسارًا في مخزن KV bbolt في ~/.mkdev/state.db وتُلحق سطرًا 127.0.0.1 <name>.<tld> في /etc/hosts عبر أمر مساعد يُستدعى بـ sudo.
• تستمع الخفيّة لـ TLS على 0.0.0.0:<proxy_port>، حسب الطلب باستخدام جذر CA، وتُوكّل عكسيًا إلى المصدر upstream المُعد.

الأمان

هذه الأداة تُثبت CA خاص في مخزن الثقة لنظامك. أي شخص لديه حق الوصول للقراءة إلى ~/.mkdev/ca/rootCA-key.pem يمكنه إصدار شهادات TLS سيثق بها جهازك. يتم إنشاء المفتاح بـ 0o400 (القراءة فقط للمالك).

• الوكيل يربط 0.0.0.0، ولكن قائمة التحكم في الوصول بناءً على مصدر الاتصال ترد بـ 403 على طلبات LAN لأي مسار غير مميز صراحة بـ مشاركة. الحلقة المحلية دائمًا مسموح بها.
• لا تتبع. لا استدعاءات عن بعد. لا فحوصات تحديث.
• add / remove تستدعي sudo لتعديل /etc/hosts. انظر SECURITY.md لنموذج التهديد وحدود معروفة حول مسارات المساعد التي تم حلها بواسطة os.Executable().

إلغاء التثبيت

mkdev uninstall   # يوقف ويعطّل الخفيّة، يزيل الثقة من CA، يمسح /etc/hosts،
                  # يحذف خدمة الخفيّة وبدء الشريط التلقائي، ويمسح ~/.mkdev/

إذا علق شيء، افتح Keychain Access.app، وابحث عن mkdev، واحذف يدويًا. ثم grep mkdev /etc/hosts ونظف أي بقايا.

الخفيّة و API

الخفيّة تمتلك الوكيل ومخزن المسارات. تعرض API HTTP محلي على ~/.mkdev/daemon.sock (للمالك فقط 0600). واجهة TUI، وأوامر CLI الفرعية، وشريط القوائم كلها عملاء للخفيّة — فقط الخفيّة تحمل قفل bbolt.

mkdev install تُثبت الخفيّة كخدمة مستخدم (launchd LaunchAgent على macOS، systemd --user على Linux) وتفعلها. تعمل في الخلفية وتتحمل الخروج / تسجيل الدخول.

mkdev daemon status                # مثبّتة / مفعّلة / قيد التشغيل
mkdev daemon stop                  # إيقاف + تعطيل (يمنع إعادة التشغيل)
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

خريطة الطريق

التالي:

• تكامل مخزن الثقة Firefox / NSS.
• التوجيه لكل مسار (/api → 8080، /ws → 9000 على مجال واحد).

استكشاف الأخطاء وإصلاحها

• يعرض Firefox شريطًا أحمر. يستخدم Firefox مخزن NSS الخاص به؛ ثقة النظام لا تصل إليه. تكامل NSS موجود في خريطة الطريق. في الوقت الحالي، استورد ~/.mkdev/ca/rootCA.pem يدويًا من خلال الإعدادات → الخصوصية والأمان → الشهادات → عرض الشهادات → السلطات → استيراد.
• تفشل الخفيّة في ربط :443. macOS/Linux تسمح لخدمات المستخدم غير الجذر بربط :443 عبر إمكانيات launchd / systemd. إذا كانت توزيعة Linux تقيد ذلك، اضبط proxy_port = 8443 في ~/.mkdev/config.toml واستخدم https://name.local:8443.
• mkdev add يستمر في طلب sudo. ذاكرة التخزين المؤقت لجلسة sudo تنتهي صلاحيتها (افتراضي 5 دقائق). استخدم علامة TUI Domains بدلاً من ذلك — ترفع الصلاحيات عبر osascript (موجه macOS GUI) أو pkexec (Polkit Linux).
• /etc/hosts يحتوي بالفعل على إدخال لذلك الاسم. mkdev add هو idempotent ويضيف فقط عندما لا يوجد إدخال مُدار بواسطة mkdev. أزل الإدخال السابق يدويًا أو اختر اسمًا مختلفًا.

المساهمة

انظر CONTRIBUTING.md.

الشكر

تكامل مخزن الثقة في mkdev — Keychain/security على macOS، حزمة CA + update-ca-* على Linux، مخزن ROOT crypt32.dll على Windows، والمسارات المجاورة لـ NSS — مقتبس من mkcert بواسطة Filippo Valsorda، BSD-3. بدون هذا العمل السابق، لكان هذا المشروع أصعب بكثير. انظر LICENSE-MKCERT للترخيص الأصلي.

واجهة TUI مبنية باستخدام Charmbracelet's Bubble Tea / Bubbles / Lipgloss. mDNS عبر hashicorp/mdns. مخزن KV محلي عبر bbolt.

الترخيص

MIT LICENSE.