إخفاء الأسرار

يمنع إرسال القيم الحساسة (مفاتيح API، والرموز المميزة، وكلمات المرور) إلى موفري LLM. عند التفعيل، يتم استبدال الأسرار بعناصر نائبة حتمية قبل مغادرتها للعملية، واستعادتها في وسائط استدعاء الأدوات التي يُعيدها النموذج.

التفعيل

مُفعَّل افتراضيًا. يمكن التبديل عبر واجهة المستخدم /settings أو مباشرةً في config.yml:

secrets:
  enabled: false

كيفية عمله

1. عند بدء الجلسة، يتم جمع الأسرار من مصدرين:

   • متغيرات البيئة المطابقة لأنماط الأسرار الشائعة (*_KEY، و*_SECRET، و*_TOKEN، و*_PASSWORD، وغيرها) ذات القيم التي تبلغ 8 أحرف أو أكثر
   • ملفات secrets.yml (انظر أدناه)

2. يتم في الرسائل الصادرة إلى LLM استبدال جميع قيم الأسرار بعناصر نائبة مثل <<$env:S0>>، و<<$env:S1>>، وغيرها.

3. يتم التنقل العميق في وسائط استدعاء الأدوات التي يُعيدها النموذج، واستعادة العناصر النائبة إلى قيمها الأصلية قبل التنفيذ.

يتحكم وضعان في ما يحدث لكل سر:

الوضع	السلوك	قابل للعكس
obfuscate (افتراضي)	يُستبدل بعنصر نائب مفهرس <<$env:SN>>	نعم (تُستعاد قيمته الأصلية في وسائط الأداة)
replace	يُستبدل بسلسلة نصية حتمية بالطول ذاته	لا (أحادي الاتجاه)

secrets.yml

حدِّد إدخالات الأسرار المخصصة في YAML. يتم فحص موقعين:

المستوى	المسار	الغرض
عام	~/.xcsh/agent/secrets.yml	الأسرار عبر جميع المشاريع
مشروع	<cwd>/.xcsh/secrets.yml	الأسرار الخاصة بالمشروع

تتجاوز إدخالات المشروع الإدخالات العامة ذات content المتطابق.

المخطط

كل إدخال في المصفوفة يحتوي على هذه الحقول:

الحقل	النوع	مطلوب	الوصف
type	"plain" أو "regex"	نعم	استراتيجية المطابقة
content	سلسلة نصية	نعم	قيمة السر (plain) أو نمط regex (regex)
mode	"obfuscate" أو "replace"	لا	الافتراضي: "obfuscate"
replacement	سلسلة نصية	لا	استبدال مخصص (وضع replace فقط)
flags	سلسلة نصية	لا	أعلام regex (نوع regex فقط)

أمثلة

الأسرار النصية العادية

# إخفاء مفتاح API محدد (الوضع الافتراضي)
- type: plain
  content: sk-proj-abc123def456

# استبدال كلمة مرور قاعدة البيانات بسلسلة ثابتة
- type: plain
  content: hunter2
  mode: replace
  replacement: "********"

أسرار Regex

# إخفاء أي مفتاح بأسلوب AWS
- type: regex
  content: "AKIA[0-9A-Z]{16}"

# مطابقة غير حساسة لحالة الأحرف مع أعلام صريحة
- type: regex
  content: "api[_-]?key\\s*=\\s*\\w+"
  flags: "i"

# صيغة regex الحرفية (النمط والأعلام في سلسلة واحدة)
- type: regex
  content: "/bearer\\s+[a-zA-Z0-9._~+\\/=-]+/i"

تُجري إدخالات Regex المسح دائمًا على نطاق عام (يتم تطبيق العلم g تلقائيًا). تُدعم صيغة regex الحرفية /pattern/flags كبديل لحقلي content وflags المنفصلين. يتم التعامل مع الشرطات المائلة المُهرَّبة داخل النمط (\\/) بصورة صحيحة.

وضع الاستبدال مع Regex

# استبدال أحادي الاتجاه لسلاسل الاتصال (غير قابل للعكس)
- type: regex
  content: "postgres://[^\\s]+"
  mode: replace
  replacement: "postgres://***"

التفاعل مع اكتشاف متغيرات البيئة

يتم جمع متغيرات البيئة دائمًا أولًا. تُلحَق الإدخالات المُعرَّفة في الملفات بعدها، لذا يمكن للإدخالات الملفية تغطية الأسرار التي لا توجد في متغيرات البيئة (ملفات التكوين، والقيم المُضمَّنة، وغيرها). إذا ظهرت القيمة ذاتها في كليهما، فإن وضع إدخال الملف يأخذ الأولوية.

الملفات الرئيسية

• src/secrets/index.ts — التحميل والدمج وجمع متغيرات البيئة
• src/secrets/obfuscator.ts — فئة SecretObfuscator، وتوليد العناصر النائبة، وإخفاء الرسائل
• src/secrets/regex.ts — تحليل regex الحرفية وتجميعها
• src/config/settings-schema.ts — تعريف إعداد secrets.enabled