8feea123bb
* feat(docs): mirror every docs/ page in all 65 locales Extends the documentation mirrors from the 22-page core set (#13940) to every Markdown page under docs/: 152 sources x 65 locales = 9,880 mirrors (6,208 new), language bars rewritten for the full locale list, state adopted so the blocking drift gate now covers all 152 pages. run-translation.mjs: an oversized block made only of table rows or list items (PROVIDER_REFERENCE.md 244-row table, FREE_TIERS.md 71-item list) is cut at item boundaries and rejoined without a blank line — the single 16-40 KB request outlived the backend socket for verbose scripts. 48 older mirrors whose tables had lost rows were retranslated with --force. * docs(i18n): refresh mirrors for the sources the base changed since the branch cut Section-level retranslation of the 29 docs (and README.md) whose source or mirrors moved on release/v3.8.51 during the run, then state adoption; the drift gate is green again on the merged tree.
12 KiB
CLI Machine-ID Token (العربية)
🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW
نظرة عامة
تُجري أوامر OmniRoute CLI المصادقة مع واجهة API المحلية للإدارة باستخدام رمز
HMAC-SHA256(machine-id, salt) يُرسَل عبر ترويسة الطلب
x-omniroute-cli-token.
يسمح هذا للأوامر الفرعية في CLI (omniroute status وomniroute providers وغيرها)
باستدعاء نقاط نهاية الإدارة دون مطالبة المستخدم بتوفير JWT أو
كلمة مرور عند كل استدعاء.
آلية العمل
- تقرأ
getMachineTokenSync()مُعرّف الجهاز المادي عبرnode-machine-id(وتعود إلى سلسلة فارغة عند الفشل، مما يعطّل مصادقة CLI). - تحسب
HMAC-SHA256(machine_id, salt)وتُرجع ملخص hex كاملًا بطول 64 محرفًا — وهو رمز حتمي غير قابل للعكس ومرتبط بهذا الجهاز. - يرسل CLI الرمز باسم
x-omniroute-cli-tokenفقط عندما تكون الوجهة المحددة عنوان URL صريحًا لواجهة الاسترجاع (localhostأو127.0.0.0/8أو IPv6 لواجهة الاسترجاع). تستخدم الطلبات التي تحمل الرمزredirect: error، بحيث لا يمكن لعملية إعادة توجيه محلية تمريره إلى أصل آخر. تستخدم السياقات البعيدة رموز وصول محددة النطاق بدلًا من ذلك. إذا تعذر الاشتقاق، يحذف CLI الترويسة ويُبلغomniroute doctorعن الفشل بدلًا من اعتبار رمز فارغ صالحًا. - يعيد الخادم (
src/server/authz/policies/management.ts) حساب الرمز المتوقع باستخدام قيمة salt نفسها ويقارنه عبرtimingSafeEqualلمنع الاستخراج القائم على التوقيت.
خصائص الأمان
| الخاصية | التفاصيل |
|---|---|
| واجهة الاسترجاع فقط | لا يُقبل إلا عندما تشير علامة محلية النظير الموثوقة لدى الخادم (المشتقة من عنوان نظير TCP الحقيقي) إلى واجهة الاسترجاع. لا يُوثق مطلقًا بترويسة Host التي يتحكم بها العميل لتحديد المحلية. |
| مقارنة بزمن ثابت | تمنع crypto.timingSafeEqual هجمات التوقيت. |
| غير قابل للعكس | لا يمكن استخدام ناتج HMAC لاستعادة machine-id. |
لا تجاوز للحماية من نوع always |
تُقيَّم isAlwaysProtectedPath() قبل التحقق من رمز CLI. يتطلب كل من /api/shutdown و/api/settings/database دائمًا JWT. |
| غير قابل للتصدير | لا يُكتب الرمز مطلقًا على القرص ولا يُسجَّل. |
قيمة salt الافتراضية (عشوائية لكل تثبيت)
عندما لا تكون OMNIROUTE_CLI_SALT مضبوطة، تكون قيمة salt سلسلة hex عشوائية بطول 64 محرفًا
تُنشأ مرة واحدة وتُحفظ في <DATA_DIR>/cli-token-salt.json (بالوضع 0600) —
وليست القيمة الحرفية omniroute-cli-auth-v1 المضمّنة في المستودع. تقرأ كل من getActiveSalt() في
src/lib/machineToken.ts ونسختها المطابقة في bin/cli/utils/cliToken.mjs
الملف نفسه، بحيث يتوافق الخادم وكل استدعاء لـ CLI في هذا التثبيت على
القيمة نفسها؛ ولا تُستخدم القيمة الحرفية المضمّنة في المستودع إلا كحل أخير عندما لا يمكن
بعدُ إنشاء قيمة salt محفوظة أو مأخوذة من البيئة (مثلًا في تثبيت جديد يقتصر على CLI
قبل تشغيل الخادم لأول مرة). يعالج هذا نقطة ضعف القيمة الحرفية الثابتة
الافتراضية القديمة: يكون /etc/machine-id عادةً قابلًا للقراءة من جميع المستخدمين، ولذلك كان بإمكان
أي مستخدم محلي اشتقاق الرمز نفسه لكل تثبيت لم يضبط
OMNIROUTE_CLI_SALT.
تدوير الملح
عيّن OMNIROUTE_CLI_SALT لتدوير الرمز المشتق دون تغييرات في الشيفرة — فهو
يحظى دائمًا بالأولوية على الملح المحفوظ لكل تثبيت. بعد التدوير، ستستخدم جميع عمليات CLI
على هذا الجهاز الرمز الجديد تلقائيًا. يكون ذلك مفيدًا بعد تسرّب قائمة
العمليات الذي ربما كشف القيمة المشتقة السابقة.
# تدوير دائم (أضِفه إلى ملف تعريف الصدفة)
export OMNIROUTE_CLI_SALT="my-secret-salt-2026"
# تحقّق من استخدام الرمز الجديد
omniroute status
التنسيق القديم (SHA-256، 32 محرفًا) — لا يزال مقبولًا
قبل تنسيق HMAC أعلاه، كانت CLI تشتق رمزها على النحو التالي:
SHA-256(machineId + salt).hex[0..32] (بادئة من 32 محرفًا) في
bin/cli/utils/cliToken.mjs (getLegacyCliTokenSync في src/lib/machineToken.ts).
للتوافق مع الإصدارات السابقة، يقبل الخادم كلا التنسيقين: ينشئ المتحقق
expectedTokens = [getMachineTokenSync(), getLegacyCliTokenSync()] ويقارن
الترويسة الواردة بكل منهما باستخدام timingSafeEqual
(src/server/authz/policies/management.ts وsrc/lib/middleware/cliTokenAuth.ts).
لذلك يكون الرمز صالحًا إذا طابق إما مُلخّص HMAC المكوّن من 64 محرفًا أو بادئة
SHA-256 القديمة المكوّنة من 32 محرفًا.
إلغاء الاشتراك: عيّن OMNIROUTE_DISABLE_CLI_TOKEN=true (في البيئة أو .env) لتعطيل آلية رمز CLI
بالكامل؛ وعندئذٍ يتطلب كل وصول مفتاح API صريحًا. يُنصح بذلك على المضيفات متعددة المستخدمين،
لأن machine-id يُحدَّد لكل جهاز (وليس لكل مستخدم)، وقد يتمكن مستخدم آخر
على المضيف نفسه من حساب الرمز ذاته.
الملفات
| الملف | الغرض |
|---|---|
src/lib/machineToken.ts |
اشتقاق الرمز (getMachineTokenSync) |
bin/cli/utils/cliToken.mjs |
نسخة CLI المطابقة للاشتقاق نفسه |
<DATA_DIR>/cli-token-salt.json |
الملح العشوائي المحفوظ لكل تثبيت |
src/server/authz/headers.ts |
الثابت CLI_TOKEN_HEADER |
src/server/authz/policies/management.ts |
التحقق من جانب الخادم |
src/server/authz/routeGuard.ts |
فحص مضيف الاسترجاع (isLoopbackHost) |
انظر أيضًا
docs/security/ROUTE_GUARD_TIERS.md— مستويات حماية المساراتdocs/architecture/AUTHZ_GUIDE.md— مسار التفويض الكامل