Arxi بوابة القرار أصل أساسي
Docs
وثائق بوابة القرار

تقييم بوابة حتمي وقابل لإعادة التشغيل مع قرارات قابلة للتدقيق.

وثائق Asset Core

بوابة القرار للمصادقة والتفويض + هندسة الكشف

Audience: Engineers implementing or reviewing MCP authentication, الجمهور: المهندسون الذين يقومون بتنفيذ أو مراجعة سلوك مصادقة MCP، والتفويض، وكشف الأخطاء.

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

  1. نظرة عامة تنفيذية
  2. سياق الطلب والهوية
  3. أنماط المصادقة
  4. تفويض الأداة (قائمة السماح)
  5. تفويض المستأجر (قابل للتوصيل)
  6. قياس الاستخدام والحصص (قابل للتوصيل)
  7. أحداث تدقيق المصادقة
  8. وضع الإفصاح (JSON-RPC + HTTP)
  9. تحديد معدل الاستجابة والتحميل الزائد
  10. مرجع متقاطع ملف بملف

نظرة عامة تنفيذية

بوابة القرار MCP تفرض مصادقة وتفويض صارمين، مع إغلاق فاشل، لاستدعاءات الأدوات. المصادقة تعتمد على النقل (stdio، HTTP، SSE) ويتم تكوينها عبر server.auth. يتم فرض التفويض لكل استدعاء أداة عبر DefaultToolAuthz، مع قوائم أدوات اختيارية. يمكن أن تفرض طبقة تفويض مستأجر قابلة للتوصيل نطاق المستأجر/المساحة الاسمية قبل تنفيذ الأداة. تصدر قرارات المصادقة أحداث تدقيق منظمة، ويتم ربط فشل الطلبات بأكواد أخطاء JSON-RPC المستقرة وأكواد حالة HTTP من أجل الكشف الحتمي ووضع علامات على المقاييس. F:crates/decision-gate-mcp/src/auth.rs L293-L372 F:crates/decision-gate-mcp/src/tools.rs L1436-L1454 F:crates/decision-gate-mcp/src/tools.rs L2857-L2878 F:crates/decision-gate-mcp/src/server.rs L1984-L2017

سياق الطلب والهوية

سياق الطلب

تُعالج الطلبات الواردة في RequestContext الذي يسجل النقل، عنوان IP للند، رأس المصادقة، موضوع العميل، ومعرف الطلب الاختياري بالإضافة إلى بيانات التعريف المتعلقة بالترابط. بالنسبة لنقل HTTP/SSE، يتم بناء السياق من رأس Authorization ورأس x-decision-gate-client-subject لهوية وكيل mTLS. تصل معرفات الترابط المقدمة من العميل عبر x-correlation-id وتُعتبر مدخلات غير آمنة: يتم التحقق منها بدقة ورفضها إذا كانت غير صالحة. يقوم الخادم دائمًا بإصدار x-server-correlation-id الخاص به ويعيده في الردود، مما يوفر معرفًا ثابتًا وقابلًا للتدقيق حتى عندما تكون معرفات العملاء مفقودة أو مرفوضة. F:crates/decision-gate-mcp/src/auth.rs L82-L173 F:crates/decision-gate-mcp/src/server.rs L993-L1072 F:crates/decision-gate-mcp/src/server.rs L1648-L1734

الهوية الرئيسية

AuthContext يلتقط طريقة المصادقة بالإضافة إلى موضوع صريح أو بصمة توكن الحامل. إذا كانت الطلبات محلية فقط وليس لديها موضوع، يتم تعيين الموضوع إلى stdio أو loopback بناءً على النقل. بالنسبة لتوكنات الحامل، يتم حساب بصمة sha256 وتستخدم كعلامة هوية مستقرة. F:crates/decision-gate-mcp/src/auth.rs L181-L216 F:crates/decision-gate-mcp/src/auth.rs L503-L517

أنماط المصادقة

وضع المصادقة مُهيأ عبر server.auth.mode مع قوائم السماح الداعمة:

  • local_only: يُسمح باستخدام stdio؛ يُسمح بـ HTTP/SSE فقط لعناوين IP الخاصة بالحلقة.
  • bearer_token: يجب أن يتطابق رمز الحامل مع server.auth.bearer_tokens.
  • mtls: subject must be present in x-decision-gate-client-subject and match mtls: يجب أن يكون الموضوع موجودًا في x-decision-gate-client-subject ويتطابق مع server.auth.mtls_subjects عند تكوينه.

واجهة التكوين:

تفاصيل التنفيذ:

  • يرفض النظام المحلي فقط HTTP/SSE غير المتكرر.
  • Bearer tokens are parsed with size and scheme validation; invalid/missing يتم تحليل رموز الحامل مع التحقق من الحجم والمخطط؛ الفشل في المصادقة يحدث بسبب رؤوس غير صالحة أو مفقودة.
  • mTLS requires a subject; unauthorized subjects are rejected. يتطلب mTLS وجود موضوع؛ يتم رفض المواضيع غير المصرح بها. F:crates/decision-gate-mcp/src/auth.rs L479-L552

تفويض الأداة (قائمة السماح)

تُفرض مصادقة الأدوات حسب الطلب بواسطة DefaultToolAuthz. إذا تم تكوين server.auth.allowed_tools، يتم رفض أي أداة غير موجودة في قائمة السماح مع خطأ غير مصرح به. تُعتبر أسماء الأدوات غير الصالحة في قائمة السماح تكوينًا مغلقًا (قائمة سماح فارغة). F:crates/decision-gate-mcp/src/auth.rs L293-L372

نتائج تفويض الأداة يتم إصدارها بواسطة موجه الأداة:

تفويض المستأجر (قابل للتوصيل)

يتم تطبيق تفويض المستأجر/الفضاء بواسطة خطاف TenantAuthorizer القابل للتوصيل. يسمح التنفيذ الافتراضي بالوصول الكامل، ولكن يمكن للتطبيقات المؤسسية توفير مُفوض يربط الأفراد بنطاقات المستأجر والفضاء. يتم تشغيل تفويض المستأجر بعد فحوصات قائمة الأدوات المسموح بها وقبل تنفيذ الأداة. تصدر حالات رفض المستأجر أحداث تدقيق مخصصة (tenant_authz).

مراجع التنفيذ:

قياس الاستخدام والحصص (قابل للتوصيل)

يتم تطبيق قياس الاستخدام والتحقق من الحصص بواسطة خطاف UsageMeter القابل للتوصيل. التنفيذ الافتراضي هو عدم القيام بأي عملية، ولكن يمكن للتطبيقات المؤسسية توفير مقياس يفرض الحصص ويسجل الاستخدام بمستوى الفوترة. يتم تشغيل فحوصات الاستخدام قبل تنفيذ الأداة؛ حيث تصدر عمليات الرفض أحداث usage_audit.

مراجع التنفيذ:

أحداث تدقيق المصادقة

قرارات المصادقة تصدر أحداث تدقيق JSON منظمة تحتوي على تفاصيل النقل، الموضوع، الطريقة، وسبب الفشل. يقوم مصب التدقيق الافتراضي بتسجيل خطوط JSON إلى stderr؛ يمكن للاختبارات استخدام مصب لا يقوم بأي عملية. F:crates/decision-gate-mcp/src/auth.rs L379-L445

وضع الإفصاح (JSON-RPC + HTTP)

إفصاح الملاحظات (scenario_next)

scenario_next الردود هي ملخص فقط بشكل افتراضي. مستويات التغذية الراجعة الاختيارية (trace, evidence) محكومة بسياسة server.feedback.scenario_next، مع التحقق من الدور/الموضوع الذي يتم حله من server.auth.principals. لا تزال تغذية الأدلة الراجعة مصفاة من خلال سياسة الكشف عن الأدلة (قد يتم حجب القيم الخام ما لم يُسمح بذلك صراحة). F:crates/decision-gate-config/src/config.rs L452-L545 F:crates/decision-gate-mcp/src/tools.rs L2144-L2257

JSON-RPC خطأ Envelope

يستجيب خادم MCP باستخدام رموز خطأ JSON-RPC وبيانات وصفية منظمة (kind, retryable, request_id, retry_after_ms الاختياري). أنواع الأخطاء هي تسميات مستقرة تُستخدم لأغراض القياس وتصنيف التدقيق. F:crates/decision-gate-mcp/src/server.rs L1961-L2043

رسم الأخطاء (أخطاء الأدوات)

أخطاء الأدوات مرتبطة بحالة HTTP + رموز خطأ JSON-RPC:

ToolErrorHTTPJSON-RPC CodeMessage
غير مصادق عليه401-32001غير مصادق عليه
غير مخول403-32003غير مخول
معلمات غير صالحة400-32602الرسالة المقدمة
انتهاك القدرة400-32602code: message
أداة غير معروفة400-32601أداة غير معروفة
استجابة كبيرة جدًا200-32070الرسالة المقدمة
محدودية المعدل200-32071الرسالة المقدمة
غير موجود200-32004الرسالة المقدمة
تعارض200-32009الرسالة المقدمة
دليل200-32020الرسالة المقدمة
مستوى التحكم200-32030الرسالة المقدمة
تشغيل الحزمة200-32040الرسالة المقدمة
داخلي200-32050الرسالة المقدمة
تسلسل200-32060فشل التسلسل

تم تنفيذ هذه التعيينات في jsonrpc_error. F:crates/decision-gate-mcp/src/server.rs L1984-L2015

رأس تحدي المصادقة (RFC 6750)

تتضمن استجابات HTTP/SSE للطلبات غير المصرح بها رأس WWW-Authenticate مع مجال Bearer عندما تكون مصادقة رمز الحامل مفعلة. يتماشى هذا مع RFC 6750 ويحافظ على تحديات المصادقة بشكل صريح دون تسريب تفاصيل التحقق من الرمز. F:crates/decision-gate-mcp/src/auth.rs L46-L75 F:crates/decision-gate-mcp/src/server.rs L1706-L1718

رؤوس الارتباط

استجابات HTTP/SSE تتضمن دائمًا x-server-correlation-id الذي يصدره الخادم. إذا قدم العميل x-correlation-id صالح، يتم إعادته. يتم رفض معرفات ارتباط العميل غير الصالحة قبل تحليل الطلب ولا يتم إعادتها. تستخدم عملية رفض الارتباط غير الصالح HTTP 400 مع رمز خطأ JSON-RPC -32073 (invalid_correlation_id). F:crates/decision-gate-mcp/src/server.rs L993-L1072 F:crates/decision-gate-mcp/src/server.rs L1648-L1749

فشل تحليل الطلبات

تم رفض إصدارات JSON-RPC غير الصالحة، والطرق غير المعروفة، وأجسام الطلبات المشوهة باستخدام رموز خطأ JSON-RPC القياسية وHTTP 400. F:crates/decision-gate-mcp/src/server.rs L1505-L1583

تحديد معدل الاستجابة والتحميل الزائد

الخادم يفرض:

  • حدود الطلبات أثناء الطيران (رفض مع 503 و -32072).
  • تحديد معدل الطلبات (الرفض مع 429 و -32071، بما في ذلك تلميحات إعادة المحاولة بعد).
  • حدود حجم الحمولة (رفض مع 413 و -32070).

تُسجل هذه الأخطاء مع بيانات وصفية للخطأ بتنسيق JSON-RPC وهي مُعلمة بأنها قابلة لإعادة المحاولة عند الاقتضاء. F:crates/decision-gate-mcp/src/server.rs L1505-L1568 F:crates/decision-gate-mcp/src/server.rs L2051-L2053

مرجع متقاطع لكل ملف

المنطقةالملفالملاحظات
واجهة تكوين المصادقةcrates/decision-gate-config/src/config.rsأوضاع المصادقة، قوائم السماح بالرموز/الموضوعات، قائمة السماح بالأدوات.
محرك سياسة المصادقةcrates/decision-gate-mcp/src/auth.rsDefaultToolAuthz، أوضاع المصادقة، أحداث التدقيق، تحليل الرموز.
تكامل مصادقة الأدواتcrates/decision-gate-mcp/src/tools.rsتفويض لكل استدعاء + إصدار تدقيق.
واجهة تفويض المستأجرcrates/decision-gate-mcp/src/tenant_authz.rsنقطة تفويض المستأجر/الفضاء القابلة للتوصيل.
واجهة قياس الاستخدامcrates/decision-gate-mcp/src/usage.rsقياس الاستخدام القابل للتوصيل + تنفيذ الحصص.
الكشف عن JSON-RPCcrates/decision-gate-mcp/src/server.rsخريطة الأخطاء وأكواد الاستجابة.