مرجع Control Center Connect
يشغّل Control Center Connect تسجيلات الدخول لدى المزوّدين للخوادم التي لم تسجّل
تطبيقاتها الخاصة. يستخدم الخادم إما Connect المستضاف من Control Center، وإما Connect
تشغّله مؤسسته (تشغيل خادم Connect)،
وإما لا شيء. يعيش الاختيار في الإعدادات ← الخادم ← تسجيل الدخول الموحّد ← Control Center Connect، أو في cc_server connect، أو في CC_CONNECT_URL. تتبعه مساحة العمل ما لم يختر مسؤول خيارًا آخر لتلك المساحة في الإعدادات ← مساحة العمل ← التكاملات (الاختيار لكل مساحة عمل).
المسارات
قسم بعنوان “المسارات”كل مزوّد مسار. تحت استخدام تطبيقاتي الخاصة (أو قبل أن يختار أحد)، يعمل المسار على التطبيق الخاص بالخادم حين يكون مضبوطًا بالكامل، وإلا فهو غير متاح. مع Control Center أو Connect مخصص، يشغّل Connect كل مسار يخدمه: تبقى التطبيقات الخاصة بالخادم محفوظة دون استخدام، لا للتسجيلات ولا لأتمتة الخادم ولا للحالة التي يبلغ عنها الخادم. ومساحة العمل التي اختارت خيارها الخاص تشغّل كل مسار بحسب ذلك الاختيار بدلًا من ذلك.
| المسار | ما يحتاجه التطبيق الخاص | عبر Connect |
|---|---|---|
github |
معرّف التطبيق، والمفتاح الخاص، ومعرّف العميل، وسر العميل | يسجّل الناس دخولهم إلى GitHub App المشترك |
google |
معرّف العميل وسر العميل | يربط الناس Google Calendar |
linear |
معرّف العميل | يسجّل الناس دخولهم إلى Linear |
linear_app |
معرّف العميل | يربط مسؤول مساحة العمل فاعل التطبيق في Linear |
slack |
اتصال تطبيق Slack الخاص بمساحة العمل | يربط مسؤول مساحة العمل Slack بتطبيق Slack المشترك |
klipy |
KLIPY_APP_KEY |
بحث GIF، بوساطة Connect |
التطبيق الخاص المضبوط جزئيًا يجعل مساره خطأ، ولا يرجع أبدًا إلى Connect في صمت. ومساحة العمل التي تستخدم استخدام تطبيقاتي الخاصة لا تمر أبدًا عبر تطبيقات الخادم ولا عبر أي Connect، لأي مزوّد. ولا يؤدي تغيير اختيار Connect لدى الخادم إلى تسجيل خروج أحد من مساحة عمل اختارت خيارها الخاص.
ما يراه Connect وما لا يراه أبدًا
قسم بعنوان “ما يراه Connect وما لا يراه أبدًا”| ما يراه Connect | ما لا يراه Connect أبدًا |
|---|---|
| معرّف تثبيت الخادم وتوقيعات الطلبات | الشفرة المصدرية، ومحتويات المستودعات، والفروق، ونص طلبات السحب |
| حساب المزوّد الذي سجّل الدخول، أثناء تسجيل الدخول | التذاكر، والنسخ النصية، وأي شيء في قاعدة بيانات مساحة عمل |
| مساحة العمل التي تخصها بيانات الاعتماد، بمعرّف معتم داخل الختم | أسرار تطبيق الخادم الخاص: لا تغادر الخادم أبدًا |
| المستودع الذي يُسكّ له رمز GitHub لمستودع واحد | رموز التجديد في حالة السكون: لا توجد إلا داخل أختام يحتفظ بها الخادم |
| فريق Slack المربوط بالخادم | أسرار Linear: يتبادل الخادم رمز Linear بنفسه |
| عبارات بحث GIF، حين يتوسط لـ Klipy | كلمات المرور، ومفاتيح الاقتران، ومفاتيح مزوّدي النماذج |
| مراجع أحداث Slack (الفريق، والقناة، ومعرّف الرسالة) ونص أوامر الشرطة المائلة | نص رسائل Slack: يُسقطه Connect لحظة وصوله، ويقرأ الخادم الرسالة من Slack بنفسه |
يحتفظ Connect بتسجيلات الدخول المرحلية والقيم nonce والذاكرات المؤقتة لمدة 10 دقائق على الأكثر، وبعدّادات الاستخدام بالساعة لمدة ساعتين على الأكثر. يبقى رمز GitHub لمستودع واحد يُسكّ لشخص مسجَّلًا، مختومًا على تسجيل الدخول الذي طلبه، حتى تنتهي صلاحيته (8 ساعات على الأكثر)، ليستطيع Connect أن يعطيه من جديد ويُبطله عند قطع الاتصال. وسجلاته الدائمة الوحيدة هي روابط Slack (بأي خادم يرتبط كل فريق Slack) ومعرّفات التثبيت المتقاعدة. تحمل الأخطاء رمزًا، لا استجابة المزوّد أبدًا. والسجلات لا تدوّن معرّفات التثبيت إلا بصفة تجزئات مفتاحية، ولا تدوّن رمز GitHub إلا بصفة hashed_token الذي يعرضه سجل تدقيق مؤسسة GitHub له، ليستطيع مالك المؤسسة أن يطابق بينهما.
الأوضاع
قسم بعنوان “الأوضاع”| الوضع | الإعداد | السلوك |
|---|---|---|
| غير مضبوط | خادم جديد | لا يستخدم أي مسار Connect. يطلب الإعداد الأولي من مالك الخادم أن يختار |
hosted |
استخدام تطبيقات Control Center | https://connect.usectrl.dev، بإعدادات موقّعة دون اتصال. لا تُستخدم التطبيقات الخاصة بالخادم |
custom |
استخدام خادم Connect مخصص | Connect عند عنوان HTTPS (وhttp على loopback فقط)، موثوق عند أول استخدام. لا تُستخدم التطبيقات الخاصة بالخادم |
off |
استخدام تطبيقاتي الخاصة | لا يستخدم أي مسار Connect. لا يُدخِل الناس إلا التطبيقات الخاصة |
CC_CONNECT_URL في بيئة الخادم أو في .env يقفل الاختيار: hosted، أو off، أو
عنوان URL لـ Connect. عندها تعرض الإعدادات القفل ولا تستطيع تغييره.
هذا البناء لا يضمّن أي مفتاح إعدادات مستضافة، فيبلّغ الوضع المستضاف عن
hosted_unprovisioned ولا يخدم أي مسار. التطبيقات الخاصة وConnect المخصص يعملان.
يعمل Connect المستضاف في حاوية واحدة. ومفتاح الختم ومفتاح GitHub App الخاص بالتطبيق المشترك متغيّرات بيئة هناك، لا مفاتيح في خزنة لا تفعل إلا التوقيع أو فك التشفير، كما توصي GitHub لمفتاح تطبيق خاص. وهذه ثغرة معروفة في الإعداد الحالي.
يقرأ الخادم إعدادات Connect مرة كل 10 دقائق على الأكثر، وينتظر كل استدعاء 5 ثوانٍ على الأكثر. وحين يتعذر بلوغ Connect، تبقى آخر إعدادات سليمة قيد الاستخدام، وتسمها الإعدادات بأنها قديمة.
الاختيار لكل مساحة عمل
قسم بعنوان “الاختيار لكل مساحة عمل”الإعدادات ← مساحة العمل ← التكاملات ← Control Center Connect يتجاوز اختيار الخادم لمساحة عمل واحدة. يرى كل الأعضاء الاختيار وأين يعمل كل تسجيل دخول؛ ولا يغيّره إلا مسؤول مساحة العمل.
| الاختيار | السلوك |
|---|---|
| مثل هذا الخادم | الافتراضي. تعمل مساحة العمل على ما اختاره مالك الخادم، والخيار يسميه |
| استخدام تطبيقات Control Center | Connect المستضاف من Control Center، أيًّا كان ما يستخدمه الخادم |
| استخدام تطبيقاتي الخاصة | تطبيقات مساحة العمل وحدها: تطبيق GitHub الخاص بها، وعميل Google، وتطبيق Linear، ومفتاح Klipy، وتطبيق Slack. المزوّد الذي لا تطبيق له هنا يكون معطّلًا، والتطبيق الناقص جزئيًا خطأ إعداد |
| استخدام خادم Connect مخصص | Connect على عنوان HTTPS تسمّيه مساحة العمل. العناوين على شبكة خاصة أو محلية مرفوضة |
- أي اختيار غير مثل هذا الخادم يحفظ تسجيلات الدخول إلى GitHub وLinear لكل شخص في خانة خاصة بمساحة العمل، فلا تختلط بتلك التي على مستوى الخادم
- التبديل يسأل أولًا: يسجّل الجميع الدخول إلى GitHub وLinear وتقويم Google من جديد عبر التطبيقات الجديدة
- اتصال تطبيق Slack الخاص بمساحة العمل يعمل تحت كل اختيار؛ وإضافة Control Center إلى Slack يتبع الاختيار
- يمنع
CC_CONNECT_URLمساحات العمل أيضًا من امتلاك Connect خاص بها: يمكنها أن تتبع الخادم أو أن تستخدم تطبيقاتها الخاصة - يُوثَق بـ Connect المخصص لمساحة العمل عند أول استخدام لتلك المساحة وحدها: الوثوق بالتطبيقات الجديدة هناك لا يغيّر ما يثق به الخادم أو مساحة عمل أخرى
هوية التثبيت
قسم بعنوان “هوية التثبيت”| العنصر | ما هو |
|---|---|
| مفتاح التثبيت | بذرة من 32 بايت في ملف أسرار الخادم (connect_install_key)، منفصلة عن مفاتيح اقتران الأجهزة |
| مفتاح لكل Connect | مفتاح Ed25519 مشتق من البذرة ومن عنوان Connect. يُوقَّع به كل طلب إلى Connect (RFC 9421) |
| معرّف التثبيت | 26 محرفًا مشتقة من ذلك المفتاح العام. يظهر في الإعدادات وفي cc_server connect status |
للخادم نفسه معرّف تثبيت مختلف لكل عنوان Connect. ولا يتغيّر المعرّف إلا حين يُدوَّر المفتاح.
بيانات الاعتماد المختومة
قسم بعنوان “بيانات الاعتماد المختومة”يعيد تسجيل الدخول عبر Connect ختم بيانات اعتماد: كتلة مشفّرة لا يستطيع فتحها إلا Connect الذي صنعها. وهي مربوطة بالمزوّد، وعنوان Connect، ومعرّف التثبيت، ومساحة العمل، وحساب المزوّد، والتطبيق، وجيل السر.
- يخزّن الخادم الختم ومعرّف التثبيت الذي خُتم له. وتبقى رموز الوصول في الذاكرة
- للتجديد، يعيد الخادم الختم ويتلقى رمز وصول جديدًا وختمًا جديدًا
- الختم الذي لم يعد معرّف تثبيته أو عنوان Connect الخاص به مطابقًا يُحذف حين يُقرأ في المرة التالية، ويسجّل ذلك الشخص الدخول من جديد. يحدث هذا بعد تدوير المفتاح، أو التحويل إلى Connect آخر، أو استعادة دليل بيانات على خادم مختلف
- الختم الذي لا يستطيع Connect فتحه يُرفض بـ
access_denied
تثبيتات GitHub
قسم بعنوان “تثبيتات GitHub”يستطيع أي خادم استخدام تثبيت لـ GitHub App المشترك. لا يحتفظ Connect بسجل لمن يحق له استخدامه.
- تثبيت تطبيق GitHub في الإعدادات ← مساحة العمل ← التكاملات يفتح صفحة تثبيت التطبيق على GitHub. يبني الخادم الرابط من اسم التطبيق في إعدادات Connect
- يحتاج رمز مستودع واحد إلى تثبيت التطبيق على الحساب الذي يملك المستودع، وإلى صلاحية الشخص المسجّل الدخول على ذلك المستودع. وهو رمز ذلك الشخص نفسه، محصور بدوره، ولا يتجاوزه أبدًا
- تحدّ المؤسسة من Control Center على GitHub: بإزالة التثبيت، أو بتضييق مستودعاته، أو بإزالة الشخص
- بالنسبة للاستدعاءات التي لا يقدر عليها إلا الشخص، مثل سرد تثبيتاته، يسلّم Connect الخادم رمز مستخدم App الخاص بالشخص نفسه، لا رمز مستودع واحد. والتسجيل على خادم يعني الوثوق بذلك الخادم بهذا الرمز
- المؤسسة التي تفرض قائمة سماح لعناوين IP في GitHub لا تستطيع استخدام Connect المستضاف، فعناوينه ليست ثابتة. تسجّل تطبيق GitHub خاصًا بها بدلًا من ذلك، على خوادمها أو على Connect تشغّله
- قطع الاتصال يُبطل تسجيل الدخول ذاك وحده: يستهلك Connect رمز التجديد مرة واحدة ويحذف ما يعيده، ويحذف رمز المستخدم الخاص به ورموز المستودع الواحد التي سكّها له. ويتوقف عن العمل كل نسخة من ختمه محفوظة في أي مكان. تبقى تسجيلات دخول الشخص على الخوادم ومساحات العمل الأخرى تعمل. ولإزالة Control Center من حساب GitHub بالكامل، أبطله في GitHub من الإعدادات ← التطبيقات ← تطبيقات GitHub المصرّح بها ← إبطال
البوت المشترك
قسم بعنوان “البوت المشترك”ترى الرموز التي تُسكّ بصفة بوت التطبيق (as: app) البوت نفسه على GitHub لكل خادم يستخدم Connect نفسه: فلا تستطيع GitHub التمييز بين تلك الخوادم.
- يُسمح لكل خادم بأن يجعل البوت يقرأ ويعلّق:
readوreviewوcomment(التعليقات والوسوم والمكلّفون والتفاعلات على المسائل وطلبات السحب) - مراجعة طلب سحب بصفة البوت (
bot، الذي يكتب في طلبات السحب) مسموحة فقط للخوادم التي يدرجها مشغّل Connect فيCONNECT_GITHUB_REVIEW_BOT_INSTALLS. يُجاب كل خادم آخر بـneeds_requester، وينشر المراجعة برمز الشخص المسؤول نفسه، الذي تقصره GitHub عليه: فتظهر المراجعة باسمه. ويشمل ذلك نشر مراجعة الذكاء الاصطناعي، وتعليقات المراجعة، وطلبات المراجعين - الدفع وإنشاء فرع وفتح طلب سحب (
write) لا يُسكّ أبدًا بصفة البوت المشترك. تستخدم دائمًا تسجيل دخول الطالب نفسه - الموافقة على طلب سحب لا تُؤتمت أبدًا، على أي رمز
- الخادم أو مساحة العمل اللذان لهما تطبيق GitHub خاص بهما يحتفظان بالبوت لكل ما سبق، والمراجعات داخلة فيه
ما ينبغي أن يعرفه مالكو المؤسسات والأعضاء
قسم بعنوان “ما ينبغي أن يعرفه مالكو المؤسسات والأعضاء”- الخادم الذي يسجّل شخص الدخول عليه يحمل رمز مستخدم App الخاص بذلك الشخص: حتى 8 ساعات لكل رمز، ويُجدَّد حتى يقطع الاتصال. ويستطيع أن يتصرف باسمه على كل مستودع يصل إليه ويكون عليه تطبيق GitHub المشترك مثبّتًا. يستطيع Connect قطع خادم بصفة نهائية (تثبيت متقاعد أو مرفوض)، لكن الرمز الذي سُلّم أصلًا يبقى صالحًا حتى تنتهي صلاحيته
- تثبيت تطبيق GitHub المشترك على مؤسسة يمنح الموافقة لكل خادم Control Center يسجّل فيه أي عضو، لا لخادم واحد
- البوت مشترك كما سبق: لا تستطيع مؤسسة أن تعرف على GitHub أي خادم تصرّف بصفة البوت
- المؤسسة التي تريد حدودها الخاصة تسجّل تطبيق GitHub خاصًا بها وتشغّل Connect خاصًا بها (تشغيل خادم Connect)، أو تضبط التطبيق على خوادمها الخاصة
الثقة في الإعدادات
قسم بعنوان “الثقة في الإعدادات”| Connect | كيف يثق الخادم بإعداداته |
|---|---|
| المستضاف | يتحقق من توقيع Ed25519 مقابل مفاتيح مضمّنة في البناء. ويرفض حقبة أدنى من أعلى حقبة رآها (rollback) |
| المخصص | يثبّت معرّف تطبيق GitHub ومعرّف عميله، ومعرّفَي عميل Google وLinear، ومعرّفَي تطبيق Slack وعميله عند أول استخدام. أي تغيير يوقف تسجيلات الدخول عبر Connect (pins_changed) إلى أن يضغط مالك الخادم الوثوق بالتطبيقات الجديدة |
العمليات
قسم بعنوان “العمليات”إعدادات Connect على الخادم لمالك الخادم وحده.
| العملية | ما تفعله |
|---|---|
connect.status |
الوضع، والعنوان، والقفل، ومعرّف التثبيت، والسلامة، وحقبة الإعدادات، ومصدر كل مسار |
connect.configure |
يضبط hosted أو custom (مع url) أو off |
connect.test |
يجلب الإعدادات من جديد ويبلّغ عن السلامة |
connect.confirmPins |
يقبل المعرّفات المتغيّرة لـ Connect مخصص |
connect.rotateKey |
يصكّ مفتاح تثبيت جديدًا ومعرّف تثبيت جديد (force يستبدله حتى حين يتعذر على Connect إيقاف القديم)؛ انظر تدوير مفتاح التثبيت |
لاختيار مساحة عمل خاص بها عمليات خاصة، كل منها يسمّي مساحة العمل:
| العملية | من | ما تفعله |
|---|---|---|
workspaceConnect.status |
أي عضو | الاختيار، وما يحلّ إليه، والسلامة، ومصدر كل مزوّد. معرّف التثبيت والمعرّفات المعلّقة للمسؤولين وحدهم |
workspaceConnect.set |
مسؤول مساحة العمل | يضبط inherit أو hosted أو custom (مع url) أو own |
workspaceConnect.test |
مسؤول مساحة العمل | يجلب إعدادات Connect الخاص بمساحة العمل من جديد ويبلّغ عن السلامة |
workspaceConnect.confirmPins |
مسؤول مساحة العمل | يقبل المعرّفات المتغيّرة لـ Connect المخصص الخاص بمساحة العمل |
تستخدم تسجيلات الدخول نفسها oauth.lanes وoauth.begin وoauth.status
وoauth.complete وoauth.connections وoauth.disconnect. والشخص هو دائمًا المستدعي
المسجّل الدخول.
تسجيل الدخول عبر Connect
قسم بعنوان “تسجيل الدخول عبر Connect”- يطلب الخادم من Connect بدء المسار ويتلقى عنوان التفويض لدى المزوّد، ويفحصه قبل عرضه. يعرض GitHub دائمًا منتقي الحساب
- يوافق الشخص في المتصفح. يعيده المزوّد إلى Connect
- يعرض Connect ما يستطيع الخادم الذي بدأ تسجيل الدخول أن يفعله باسم الشخص، ولمدة كم. لا يستطيع Connect أن يعرف من يشغّل ذلك الخادم، لذا تطلب الصفحة من الشخص أن يتابع فقط إن كان هو من بدأ تسجيل الدخول، وأن يغلقها إن أرسل إليه أحد الرابط. وحين يكون المتصفح على شبكة غير الشبكة التي بدأ منها تسجيل الدخول، تقول الصفحة ذلك: وهذا طبيعي لخادم مستضاف أو لجهاز آخر، وهو أيضًا ما يبدو عليه التصيّد. إلغاء ينهي تسجيل الدخول: لا يُستخدم رمز المزوّد أبدًا. ويجيب كل صفحة مرة واحدة: إجابة لم تأتِ من الصفحة التي عرضها Connect للتو تُرفض
- بعد متابعة، يعرض Connect رمزًا من 8 محارف ورابط
control-center://oauth-done. من يحصل على الرمز يحصل على الوصول الذي وافق عليه للتو، لذا لا يذهب الرمز إلا إلى المكان الذي بدأ منه تسجيل الدخول - يكتب الشخص الرمز في التطبيق، أو يتبع الرابط. يطالب الخادم بتسجيل الدخول بالرمز وبإثباته الخاص على الطلب
تنتهي صلاحية تسجيل الدخول بعد 10 دقائق. وخمسة رموز خاطئة تنهيه. والرابط الذي لم يبدأه
هذا التطبيق يُرفض بـ لم يبدأ تسجيل الدخول من هنا. يحدّ Connect عدد تسجيلات الدخول التي يستطيع عنوان شبكة واحد بدءها، وعدد مرات إصدار رموز GitHub لكل شخص وخادم، ولكل شخص عبر الخوادم، ولكل عنوان، وللتطبيق كله. ولتسجيلات الدخول الجديدة ميزانية خاصة بها، فلا تعطّل أبدًا التجديدات التي يحتاجها الآخرون. وتُرفض الاستدعاءات التي تتجاوز حدًا بـ rate_limited، ويحاول الخادم لاحقًا دون أن يسجّل أحدًا خروجه. ويُلغى تسجيل الدخول الذي يتجاوز حد الشخص عند GitHub ويُرفض.
تدوير مفتاح التثبيت
قسم بعنوان “تدوير مفتاح التثبيت”لا يستطيع تدوير المفتاح إلا مالك الخادم، بزر تدوير المفتاح في بطاقة Control Center Connect ضمن الإعدادات ← الخادم ← تسجيل الدخول الموحّد. لا يوجد أمر لذلك. ويفعل التدوير الآتي:
- يُخرج الجميع من كل مسار يعمل عبر Connect. لكل خادم Connect استُخدم معه المفتاح القديم، يُبطل الخادم تسجيلات الدخول إلى GitHub وSlack التي يحملها من هناك (تسجيل الدخول إلى Google لا شيء يُبطله وينتهي وحده)
- يُلغي معرّف التثبيت القديم عند كل خادم Connect من هذه الخوادم، موقَّعًا بالمفتاح القديم ومُثبتًا بختم بيانات اعتماد واحد يحتفظ به الخادم من ذلك Connect. ومن ذلك الوقت يرفض Connect كل طلب يُرسَل بالمفتاح القديم، فيصير الختم أو نسخة المفتاح القديم المأخوذة من هذا الخادم بلا فائدة، وتُحرَّر مساحات عمل Slack المربوطة بالمعرّف القديم لتستطيع الاتصال من جديد. وتبقى الرموز التي سُلّمت أصلًا صالحة حتى تنتهي صلاحيتها (ساعة لرمز البوت، و8 ساعات لرمز الشخص). ولا يُتخطّى إلا خادم Connect لم يحتفظ هذا الخادم بختم منه، فلا شيء عنده ليلغيه
- ثم يعطي الخادم مفتاح تثبيت جديدًا ومعرّف تثبيت جديدًا
- إن تعذّر بلوغ خادم Connect، أو رفض إلغاء المعرّف القديم، يتوقف الخادم قبل تبديل المفاتيح ويعرض تعذّر على Connect إيقاف المفتاح القديم. ويبدّل التدوير على أي حال المفاتيح بصرف النظر؛ عندها يبقى معرّف التثبيت القديم صالحًا للاستخدام لدى ذلك Connect حتى تنتهي صلاحية رموزه، أي 8 ساعات على الأكثر لرموز GitHub
- تبقى تسجيلات الدخول عبر تطبيقات الخادم الخاصة دون مساس
- يحتاج إلى إضافة معرّف التثبيت الجديد إلى قائمة السماح في Connect المخصص
رموز الحالة
قسم بعنوان “رموز الحالة”| الرمز | المعنى |
|---|---|
hosted_unprovisioned |
ليس لهذا البناء مفتاح إعدادات مستضافة |
signature |
فشلت الإعدادات المستضافة في فحص التوقيع |
rollback |
قدّم Connect إعدادات أقدم مما رآه الخادم أصلًا |
unreachable |
لا يستطيع الخادم بلوغ Connect |
install_blocked |
لا يسمح Connect بمعرّف التثبيت هذا، أو أن معرّفه قد أُلغي |
pins_changed |
أعلن Connect مخصص معرّفات تطبيقات مختلفة |
protocol |
أجاب Connect بصيغة لا يفهمها هذا الخادم |