punchline

محادثة ند-لند مشفرة من طرف إلى طرف عبر UDP. لا حسابات، ولا خادم مركزي يقوم بتوجيه/تخزين الرسائل، ولا وسيط. فقط نظيران، اتصال مباشر، وتشفير بروتوكول Noise.

https://github.com/user-attachments/assets/939e96d3-45e3-4484-9a27-28c3a0457b05

جدول المحتويات

• ما الذي يفعله
• بداية سريعة
• كيف يعمل
• مرجع واجهة الأوامر
• الاستخدام
  • الإعدادات
  • إدارة النظائر
  • فحص الحالة
  • خيارات الخادم
  • تنسيق الألوان
  • إكمال أوامر shell
• التشفير
  • مصافحة IK
  • تحديد البادئ
  • تخزين المفاتيح
• بروتوكول الشبكة
  • بروتوكول اختراق NAT
  • بروتوكول النقل
  • بروتوكول الإشارة
  • بروتوكول STUN
• هيكل المشروع
• التثبيت
  • من crates.io
  • بناء من المصدر
• تشغيل الاختبارات
• المكدس التقني
• الترخيص

ما الذي يفعله

شخصان يقومان بتشغيل punchline connect <peer> على أجهزتهما. يقوم punchline باختراق NAT الخاص بهما، وإجراء مصافحة مشفرة، وإسقاطهما في محادثة خاصة - كل ذلك في بضع ميلي ثوانٍ. تقوم خوادم STUN والإشارة المضمنة باكتشاف الاتصال ثم تختفي من الطريق.

بداية سريعة

cargo build --release

قم بتشغيل الخوادم (على جهاز يمكن لكلا النظيرين الوصول إليه)، أو استخدم خوادمي العامة المستضافة على 64.225.107.28 (STUN: المنفذ 3478، الإشارة: المنفذ 8743):

punchline-stund                  # خادم STUN - يخبر النظائر بعنوان IP العام الخاص بهم
punchline-signald                # خادم الإشارة - يطابق النظائر الذين يريدون التحدث

على جهاز كل نظير:

# إنشاء هويتك (زوج مفاتيح X25519)
punchline keygen

# شارك مفتاحك العام مع نظيرك
punchline pubkey

# احفظ مفتاحهم
punchline peers add alice a1b2c3d4...64_hex_chars

# الاتصال (يقوم كلا النظيرين بتشغيل هذا، مستهدفين بعضهما البعض)
punchline connect alice --stun <server>:3478 --signal <server>:8743

يبدأ واجهة TUI مع عرض حي لتقدم الاتصال:

1. اكتشاف STUN - حل عنوانك الخارجي عبر punchline-stund

2. خادم الإشارة - الاتصال بـ punchline-signald

3. انتظار النظير - خادم الإشارة يطابق كلا النظيرين

4. اختراق NAT - إنشاء مسار UDP المباشر

5. مصافحة Noise - تبادل المفاتيح المشفر

   

بمجرد الاكتمال، تكون في المحادثة. اكتب ثم اضغط Enter. اضغط Esc للخروج.

كيف يعمل

يتكون النظام بأكمله من ثلاثة ملفات تنفيذية، كلها مضمنة في هذا المستودع:

بعد الإعداد الأولي، لا يتم الاتصال بخوادم STUN والإشارة مرة أخرى. كل شيء يتدفق مباشرة بين النظيرين.

مرجع واجهة الأوامر

punchline

الأعلام العامة:

punchline-stund

punchline-signald

الاستخدام

الإعدادات

بدلاً من تمرير --stun و --signal في كل مرة، أنشئ ~/.config/punchline/config.toml:

stun_server = "203.0.113.10:3478"
signal_server = "203.0.113.10:8743"

إدارة النظائر

punchline peers                              # سرد الكل
punchline peers add alice a1b2c3d4...        # إضافة
punchline peers remove alice                 # إزالة

يتم تخزين الأسماء المستعارة في ~/.punchline/known_peers.toml. يمكنك أيضًا الاتصال مباشرة باستخدام مفتاح سداسي عشري خام بطول 64 حرفًا.

فحص الحالة

punchline status

يظهر هويتك وإعداداتك وإمكانية الوصول إلى الخوادم (يرسل اختبار STUN حقيقي واتصال TCP) وعدد النظائر.

خيارات الخادم

كلا الخادمين يدعمان -v (تصحيح)، -vv (تتبع)، -q (صمت)، --address، و --port:

punchline-stund -v --port 3478
punchline-signald -v --port 8743

تنسيق الألوان

قم بتخصيص TUI عبر ~/.config/punchline/style.toml الأنماط المستخدمة في الفيديو:

[colors]
my_text = "#ebdbb2"
peer_text = "#bdae93"
input_text = "#ebdbb2"
border = "#ebdbb2"
sidebar_key = "#ebdbb2"
sidebar_value = "#bdae93"

[padding]
chat_horizontal = 2
chat_vertical = 1

جميع الألوان هي RGB سداسي عشري. إذا كان الملف غير موجود، يتم استخدام الألوان الافتراضية للمحطة الطرفية.

إكمال أوامر shell

punchline completions bash > ~/.local/share/bash-completion/completions/punchline
punchline completions zsh > ~/.zfunc/_punchline
punchline completions fish > ~/.config/fish/completions/punchline.fish

التشفير

اسم البروتوكول الكامل: Noise_IK_25519_ChaChaPoly_SHA256

مصافحة IK

يعني نمط IK أن البادئ يعرف المفتاح العام الثابت للمستجيب قبل بدء المصافحة. كلا النظيرين لديهما بالفعل مفاتيح بعضهما البعض (تم تبادلها خارج النطاق أو عبر سجل النظائر)، لذا لا حاجة إلى الثقة عند أول استخدام.

1. البادئ -> المستجيب: يرسل رسالة مشفرة تحتوي على مفتاحه العام الثابت، مشفرًا تحت المفتاح المعروف للمستجيب. يوفر إخفاء الهوية ضد المراقبين السلبيين.
2. المستجيب -> البادئ: يفك التشفير، يتحقق، ويرد. ينتقل كلا الجانبين إلى وضع النقل بمفاتيح جلسة مشتركة.

تحديد البادئ

يحدد Punchline البادئ بشكل حتمي بمقارنة أول 8 بايتات من المفتاح العام لكل نظير كعدد صحيح u64 كبير النهاية. النظير ذو القيمة الأصغر يصبح البادئ. يقوم كلا الجانبين بحساب هذا بشكل مستقل.

تخزين المفاتيح

الهوية هي مفتاح سري X25519 بطول 32 بايت في ~/.punchline/id_x25519 مع أذونات Unix 0600. المفتاح العام مشتق عند التحميل. يستخدم إنشاء المفاتيح x25519-dalek مع OsRng.

بروتوكول الشبكة

البايت الأول من كل حزمة UDP يحدد نوعها:

بروتوكول اختراق NAT

ينفذ كلا النظيرين نفس الخوارزمية في وقت واحد:

1. أرسل PROBE (0x00) كل 200ms إلى عنوان النظير الخارجي.
2. عند استلام PROBE، قم بالتبديل إلى إرسال ACK (0x01).
3. عند استلام ACK، أرسل ACK نهائيًا واحدًا وأعلن النجاح.
4. مهلة الأمان: 2 ثانية من إرسال ACKs دون رد تفترض أن النظير قد انتهى.

بروتوكول النقل

تحمل الرسائل (0x02) حمولات مشفرة بـ Noise بترميز UTF-8. الـ Keepalives (0x03) هي حمولات فارغة مشفرة تُرسل كل 10 ثوانٍ للحفاظ على مزامنة عداد nonce الخاص بالتشفير. 30 ثانية دون أي حزمة تؤدي إلى قطع الاتصال.

بروتوكول الإشارة

JSON فوق WebSocket:

// طلب الاقتران (عميل -> خادم)
{ "external_addr": "203.0.113.5:48291", "public_key": "a1b2...", "target_public_key": "d4e5..." }

// رد الاقتران (خادم -> عميل)
{ "target_external_addr": "198.51.100.7:51003", "target_public_key": "d4e5..." }

بروتوكول STUN

يتبع RFC 5389 (مبسط): طلب/رد الربط مع XOR-MAPPED-ADDRESS. IPv4 فقط.

هيكل المشروع

مساحة عمل Cargo مع أربع حاويات:

crates/
├── proto/      # مكتبة مشتركة: تشفير، أنواع STUN والإشارة، سمة النقل
├── client/     # عميل P2P: CLI، TUI، منطق الاتصال، إدارة النظائر
├── signald/    # خادم الإشارة: مطابقة WebSocket للنظائر
└── stund/      # خادم STUN: اكتشاف العنوان الخارجي

التثبيت

من crates.io

cargo install punchline           # عميل TUI
cargo install punchline-signald   # خادم الإشارة
cargo install punchline-stund     # خادم STUN

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

المتطلبات الأساسية: إصدار Rust 2024 (rustc 1.85+)

git clone https://github.com/michal-pielka/punchline.git
cd punchline
cargo build --release

توضع الملفات التنفيذية في target/release/:

• punchline
• punchline-signald
• punchline-stund

تشغيل الاختبارات

cargo test

تغطي الاختبارات العمليات التشفيرية، ترميز/فك STUN، تسلسل بروتوكول الإشارة، تحليل الإعدادات، إدارة النظائر، تنسيق الألوان، ومصافحة Noise IK.

المكدس التقني

الترخيص

MIT - انظر LICENSE.