BitBang CLI

BitBang CLI هي أداة متعددة الاستخدامات للوصول عن بُعد في ملف ثنائي ثابت واحد: افتح غلافًا تفاعليًا، وتصفّح الملفات وانقلها، وصول إلى تطبيقات الويب على شبكة الجهاز البعيد من أي متصفح — دون إعادة توجيه منافذ، ودون إعدادات، ودون حساب.

على الجهاز الذي تريد الوصول إليه:

curl -sSfL bitba.ng/install | sh
bitbang serve

يطبع الأمر serve رابطًا. افتحه في أي متصفح وستحصل على طرفية، ومتصفح ملفات، وبروكسي إلى شبكة ذلك الجهاز — أو اتصل من طرفية أخرى باستخدام bitbang connect <url> عبر نفس الملف الثنائي. الاتصال مشفّر من طرف إلى طرف ومن نظير إلى نظير (peer-to-peer)؛ يتولى خادم bitba.ng التعارف بين الطرفين ثم ينسحب.

bitbang هو ملف ثنائي واحد ثابت بلغة Go. وهو جزء من مشروع BitBang؛ وتغطي هذه الورقة التقنية التصميم بعمق.

الاقتران برمز من 6 أرقام

عندما لا يمكنك لصق رابط أو مسح رمز QR ضوئيًا، مثلما يحدث عندما تكون على الهاتف أو على مرمى الصوت، يطبع bitbang serve أيضًا رمز اقتران قصيرًا. يفتح الطرف الآخر bitba.ng/<code> (أو يشغّل bitbang connect <code>)، فتظهر على شاشته أرقام ثانية مكونة من 6 أرقام، ويقرأ ذلك الرقم بصوت مسموع لك. تكتبه أنت للموافقة. لا يمكن لجهاز في المنتصف (machine-in-the-middle) جعل الرقمين متطابقين، ويحفظ الاقتران بيانات اعتماد اتصال الجهاز للمرة القادمة، مثل bitbang connect nas1. إذا كنت تعرف Magic Wormhole، فالشكل مشابه — رمز منطوق يقدّم جهازين بشكل آمن.

لماذا؟

• لا شيء لإعادة توجيهه أو إعداده. يعمل من خلف NAT أو CGNAT أو شبكة مقيدة — دون تغيير في الراوتر، وبدون VPN، وبدون برنامج خفي للأنفاق (tunnel daemon).
• لا شيء لتثبيته على جهة الاتصال. المتصفح كافٍ. وتتوفر واجهة CLI عندما تريد النصوص البرمجية والأنابيب ونسخ الملفات.
• خصوصية بالتصميم. حركة المرور عبر WebRTC/DTLS من نظير إلى نظير. لا يطّلع خادم الإشارات (signaling) عليها أبدًا؛ وإذا تعذّر المسار المباشر، ينقل مرحّل TURN النص المشفّر فقط.
• بدون حساب، وبدون أي بيانات تتبع (telemetry).

لماذا لا نكتفي بـ SSH؟

bitbang مصمم على هيئة ssh: فـ serve و connect و cp تقابل sshd و ssh و scp، مع استخدام WebRTC كوسيلة نقل بدلًا من TCP. بالنسبة لجهاز تستطيع الوصول إليه عبر SSH بشكل مريح، لا يضيف لك هذا الفرق الكثير. لكن معظم ميزات bitbang جاءت من إزعاجات يبدو أنني أواجهها أكثر مما ينبغي:

الوصول. يتطلب الوصول عن بُعد عبر SSH مسارًا واردًا، وفي معظم الشبكات لا يكون فتحه بيدك — CGNAT (شبكات الجوال، Starlink، والعديد من مزودي الخدمة)، وشبكات الشركات والجامعات والبلديات. لذا عمليًا تضطر لإضافة نظام ثانٍ: Tailscale أو VPN أو ngrok — تثبيت إضافي، وحساب إضافي، وبرنامج خفي إضافي يبقى قيد التشغيل. bitbang serve لا يحتاج منفذًا مفتوحًا ويعمل من أي مكان.

الإعداد. يجب تفعيل SSH وضبط إعداده قبل أن يسمح لك بالدخول. وهو معطّل افتراضيًا على Raspberry Pi OS، وغالبًا يعمل بالمفاتيح فقط، ما يعني أن عليك وضع مفتاحك العام على الجهاز أولًا. وكيف تفعل ذلك؟ عادة ما يكون البريد الإلكتروني أو بطاقة USB من أقل الخيارات إيلامًا. يقيم bitbang الاتصال بدلًا من ذلك عبر تبادل رمز من 6 أرقام — وهو شيء يمكنك فعله بأمان عبر الهاتف أو مناداةً به عبر الغرفة. كما أنه يعمل كمستخدم عادي — بدون root، وبدون برنامج خفي، وبدون ملف إعدادات.

البروكسي. إذا أردت تطبيق ويب على شبكة ذلك الجهاز، يمنحك SSH نفقًا منفصلًا لكل تطبيق، محدد الاسم مسبقًا. أما بروكسي bitbang فهو عام: حدد رابط تطبيق الويب وقت الاتصال.

عميل المتصفح. يتطلب SSH عميل SSH ومفتاحًا أو كلمة مرور على جهة الاتصال. أما bitbang فيحتاج متصفحًا فقط — أي هاتفًا، أو حاسوبًا محمولًا مستعارًا، أو شخصًا لم يفتح طرفية في حياته. سلّمهم الرابط فيحصلون على الوصول الذي منحتهم إياه.

استخدام bitbang

لكل اتصال طرفان: المستمع (bitbang serve، يعمل على الجهاز الذي يتم الوصول إليه) والموصل (متصفح، أو واجهة bitbang CLI على الجهاز الذي يقوم بالوصول). رابط مستمع واحد يخدم كلا النوعين من الموصلات.

المستمع: bitbang serve

bitbang serve                    # everything: shell + files + proxy on one URL
bitbang serve shell              # shell only
bitbang serve files ~/share      # files only (add -upload to allow uploads)
bitbang serve proxy              # proxy; pick the target in the browser
bitbang serve proxy localhost:8080   # ...or pin a single target

يطبع كلٌّ منها رمز QR ورابطًا ورمز اقتران.

الاتصال من المتصفح

افتح الرابط. بحسب ما يُقدَّم عبره، تحصل على:

• الغلاف -- طرفية كاملة في الصفحة (ألوان، تغيير حجم، نسخ/لصق).
• الملفات -- تصفح ومعاينة وتنزيل ورفع.
• البروكسي -- اكتب عنوان شبكة محلية (nas.local، 192.168.1.10:8080، localhost:3000/admin) واستخدم التطبيق وكأنك محلي. تعمل تسجيلات الدخول وملفات تعريف الارتباط (cookies) والرفع والبث جميعها.

الاتصال من CLI

bitbang connect <url>                                   # interactive shell
bitbang connect <url> -- tail -f /var/log/syslog        # one-shot command
bitbang cp <url>:/var/log/app.log ./app.log             # copy files, scp-style
bitbang cp - <url>:/tmp/firmware.bin < firmware.bin     # stdin/stdout work too

يُحفظ كل اتصال ناجح أو اقتران في ~/.bitbang/devices.json، ومنذ ذلك الحين يصبح الاسم المختصر كافيًا: bitbang connect nas1.

التثبيت

يكتشف السطر الواحد بنية جهازك (amd64، arm64، armv7)، وينزّل الملف الثنائي من أحدث إصدار على GitHub، ويتحقق من SHA-256 الخاص به مقابل checksums.txt الخاص بالإصدار، ويثبّته في ~/.local/bin/bitbang.

ثبّت إصدارًا محددًا، أو غيّر مسار التثبيت، أو راجع السكربت أولًا:

curl -sSfL bitba.ng/install | sh -s -- --version v0.5.0
curl -sSfL bitba.ng/install | sh -s -- --prefix /usr/local/bin

curl -sSfL bitba.ng/install -o install.sh && less install.sh && sh install.sh

إصدارات macOS وWindows قادمة — تم إنشاء issue لكل منهما (macOS، windows)؛ فقط تفاعل أو اكتب لإظهار اهتمامك. التثبيت اليدوي: نزّل الملف الثنائي من صفحة Releases وضعه في PATH. البناء من المصدر: انظر أدناه.

كيف يعمل رابط التثبيت

bitba.ng/install هو إعادة توجيه (redirect) وليس سكربتًا مستضافًا. السلسلة:

1. يصل curl إلى https://bitba.ng/install، الذي يرد برمز 302 محوّلًا إلى install.sh في هذا المستودع (على فرع main).
2. يعمل السكربت في غلافك، ويكتشف نظام التشغيل والبنية، وينزّل الملف الثنائي من https://github.com/richlegrand/bitbang-cli/releases/latest/download/bitbang-linux-<arch>.
3. يجلب checksums.txt من نفس الإصدار ويتحقق من SHA-256 الخاص بالملف الثنائي.
4. يثبّت في ~/.local/bin (قابل للتغيير).

يعيش سكربت التثبيت في هذا المستودع بجوار الكود الذي يثبّته — لذا يمكنك مراجعته جنبًا إلى جنب مع الملف الثنائي، ولا يملك مضيف bitba.ng الرسمي سوى الرابط المختصر. يمكن لمن يستضيفون الخدمة ذاتيًا توجيه /install على مضيفهم نحو أي سكربت يوزّعونه: يتحكم متغير البيئة INSTALL_URL في خادم الإشارات بهدف إعادة التوجيه (فارغ ← 404).

الأمان

• هوية ذاتية التوثيق. عند أول تشغيل، يولّد bitbang زوج مفاتيح RSA داخل ~/.bitbang/<program>/؛ يُشتق معرّف الجهاز (UID) من المفتاح العام، لذا فإن انتحال جهاز يعني إيجاد صورة عكسية ثانية (second preimage) لمعرّفه.
• السر لا يلامس الخادم أبدًا. رمز الوصول موجود في جزء الرابط (fragment) (#…)، وهو ما لا ترسله المتصفحات أبدًا — يتوسط bitba.ng الاتصال دون أن يرى أبدًا بيانات الاعتماد التي تأذن به.
• تشفير من طرف إلى طرف. تسير كل حركة المرور عبر DTLS الخاص بـ WebRTC. لا يرى خادم الإشارات سوى المفتاح العام والمعرّف المشتق وبيانات الاتصال الوصفية — ولا يرى بياناتك أبدًا. ومرحّل TURN، إذا لزم الأمر، لا يرى سوى النص المشفّر (ciphertext).
• اقتران موثّق. الرقم الذي يُقرأ بصوت مسموع في اقتران الرموز هو سلسلة مصادقة قصيرة (SAS)، تُحسب بشكل مستقل على الطرفين من بصمات DTLS المتفاوض عليها وإثنين من القيم العشوائية المُلزَم بها (nonces) — لا يمكن لجهاز في المنتصف، الذي تختلف بصماته حتمًا، جعل الرقمين متطابقين.
• رقم PIN اختياري (--pin) للإعدادات الدائمة أو بلا شاشة (headless)، ووضع الاستعمال لمرة واحدة (-ephemeral) لهوية جديدة في كل تشغيل.

تُغطى بالتفصيل كيفية مصادقة الطرفين لبعضهما دون الثقة بخادم الإشارات هنا: الإشارات بلا ثقة: المصادقة دون سلطة مركزية.

المقارنة مع البدائل

مرجع الأوامر

تقبل الخيارات (flags) أيًا من الصيغتين (-pin أو --pin). الخيارات المنطقية (Boolean) تكون معطلة افتراضيًا ما لم يُذكر خلاف ذلك.

bitbang serve [flags]                  All capabilities: shell + files + proxy on one URL
bitbang serve shell [flags]            Shell only
bitbang serve files [PATH] [flags]     Files only (PATH defaults to cwd)
bitbang serve proxy [TARGET] [flags]   HTTP/WebSocket reverse proxy (TARGET pins one host:port)
bitbang connect <target> [-- cmd …]    Client shell (interactive or one-shot)
bitbang cp <src> <dst>                 Copy files (one side is <URL>:/path, or '-')
bitbang version                        Print version (also --version)
bitbang help                           Usage (also --help, -h)

bitbang serve -- تشغيل مستمع

خيارات مشتركة (جميع صيغ serve الأربع):

خيارات الغلاف (serve و serve shell):

خيارات الملفات:

(متقدم: -video-fd N يمرر واصف ملف (FD) من نوع socketpair موروثًا إلى أداة فيديو خارجية؛ للاستخدام الداخلي/المدمج.)

bitbang connect <target> [-- command …] -- غلاف العميل

يمكن أن يكون <target> أيًا مما يلي:

• اسم محفوظ -- مثل nas1؛ يُحلّ من جدول المضيفات المعروفة (انظر أدناه)
• رمز اقتران من 6 أرقام -- مثل 482731؛ يشغّل عملية الاقتران ثم يتصل
• رابط URL -- https://bitba.ng/<id>#<code>، أو bitba.ng/<id>#<code>، أو <id>#<code> مجردًا

بدون -- command، يفتح غلافًا تفاعليًا (PTY عندما يكون stdin طرفية). ومع -- command args…، يشغّل ذلك الأمر الواحد دون تفاعل ويخرج بحالته (حالات الخروج بالإشارة تُبلَّغ كرقم 128).

bitbang cp <src> <dst> -- نسخ الملفات

واحد فقط من <src> / <dst> يكون بعيدًا، ويُكتب بصيغة <URL>:/path (الرابط بأي صيغة يقبلها connect). تعني - الإدخال/الإخراج القياسي (stdin/stdout)، لذا فإن cp <URL>:/f - يدفق إلى stdout وcp - <URL>:/f يرفع من stdin. وجود / أو . في نهاية الجهة المحلية يُبقي اسم الملف الأساسي البعيد (بأسلوب scp).

أسماء الأجهزة وجدول المضيفات المعروفة

يُتذكَّر كل اتصال أو اقتران ناجح في ~/.bitbang/devices.json (بصلاحيات 0600)، لذا يمكنك إعادة الاتصال باسم مختصر بدلًا من رابط أو رمز:

bitbang connect 482731 -name nas1     # pair once, save it as "nas1"
bitbang connect nas1                  # thereafter, just the name

• -name NAME يختار الاسم؛ وينطبق على مضيف جديد فقط. وبدونه، يُعيَّن اسم تلقائي (device1، device2، …) ويُطبع (Saved as "device1".).
• قواعد التسمية: يجب أن يبدأ الاسم بحرف وأن يحتوي على أحرف وأرقام و- أو _ فقط. يضمن ذلك عدمَ الخطأ بينه وبين رمز من 6 أرقام أو رابط. البحث والتفرد غير حساسين لحالة الأحرف.
• لا إعادة تسمية عبر connect: bitbang connect nas1 -name nas2 مرفوض — -name مخصص للحفظ لأول مرة فقط.
• متى يُحفظ: يُسجَّل الاقتران بمجرد التحقق من SAS (حتى لا يضيع عند إعادة اتصال متعثرة)؛ ويُسجَّل اتصال الرابط بمجرد الاتصال.
• يخزّن كل إدخال {name, uid, access_code, server, paired_at}. إعادة الاتصال بمضيف معروف (بالاسم أو الرابط) تُحدّثه في مكانه وتُبقي الاسم.

البناء من المصدر

يتطلب Go 1.25+. كود Go نقي، مرتبط ارتباطًا ثابتًا (CGO_ENABLED=0) — تجميع متقاطع (cross-compilation) بسيط، دون أي تبعيات وقت تشغيل.

go build ./cmd/bitbang/

# cross-compile:
GOOS=linux   GOARCH=arm64        go build -o bitbang-arm64 ./cmd/bitbang/
GOOS=linux   GOARCH=arm GOARM=7  go build -o bitbang-armv7 ./cmd/bitbang/
GOOS=windows GOARCH=amd64        go build -o bitbang.exe   ./cmd/bitbang/
GOOS=darwin  GOARCH=arm64        go build -o bitbang-macos ./cmd/bitbang/

الرسوم البيانية

خارطة الطريق

متاح اليوم: الغلاف، والملفات، والبروكسي، يمكن الوصول إليها من المتصفح أو من CLI، بالإضافة إلى نسخ الملفات بأسلوب scp والاقتران اللحظي (ad-hoc pairing) مع جدول أجهزة محفوظ. مصمَّم وفي الطريق:

• جسر المنفذ التسلسلي (Serial bridging) -- تشغيل /dev/ttyUSB0 عن بُعد من منفذ افتراضي محلي (مثل تشغيل Arduino IDE عبر الإنترنت). تم فتح issue هنا.
• إعادة توجيه منفذ TCP -- -L 5432:db.internal:5432 للوصول إلى خدمات الشبكة المحلية فقط. تم فتح issue هنا.
• سطح المكتب البعيد -- الشاشة عبر مسار فيديو WebRTC، ولوحة المفاتيح/الفأرة عبر قناة البيانات.

الترخيص

MIT — انظر LICENSE.

المساهمة

نرحب بـ issues وطلبات السحب (PRs).