مرجع الوسيط

التسلسل الهرمي لأنواع الوسيط لخط أنابيب خادم ⁦Elide⁩.

يعترض الوسيط الطلبات والاستجابات بترتيب التصريح. كل وسيط مُدرج على مستوى الخادم يلتف حول كل طلب؛ الوسيط المُدرج على مستوى المسار يلتف فقط حول الطلبات المطابقة لذلك المسار.

يُطبق الوسيط كمكدس: الوسيط الأول في القائمة يعمل في الطبقة الخارجية (يرى الطلب الخام أولاً والاستجابة النهائية أخيراً).

أنواع الوسيط المحددة تُشكل اتحاداً مُمَيزاً عبر ⁦typealias Middleware⁩. استخدم الأصناف المفتوحة المحددة مباشرةً:

⁦Compress⁩ — ضغط الاستجابات أثناء الإرسال ⁦RateLimit⁩ — تحديد معدل الطلبات بنافذة منزلقة لكل مفتاح ⁦Cors⁩ — ترويسات مشاركة الموارد عبر المصادر ⁦Headers⁩ — إضافة أو تعيين أو إزالة ترويسات الطلب/الاستجابة العشوائية ⁦BasicAuth⁩ — مصادقة ⁦HTTP⁩ الأساسية مع بيانات اعتماد ⁦bcrypt⁩ ⁦RequestId⁩ — حقن معرف فريد في كل طلب ⁦AccessLog⁩ — تسجيل مُهيكل لكل طلب مع التحكم بالتنسيق ⁦Rewrite⁩ — إعادة كتابة مسارات الطلب قبل مطابقة المسارات ⁦BodyLimit⁩ — رفض أجسام الطلبات التي تتجاوز حد البايتات ⁦TailscaleAuth⁩ — مصادقة مدركة لهوية ⁦Tailscale⁩ ⁦ErrorPage⁩ — صفحات خطأ ⁦HTML⁩ مخصصة لكل كود حالة ⁦JwtAuth⁩ — التحقق من رموز ⁦JWT⁩/⁦OAuth⁩ بمفاتيح ثابتة ⁦SecurityHeaders⁩ — حقن ترويسات أمان الاستجابة القياسية (⁦HSTS⁩، ⁦CSP⁩، إلخ.) ⁦IpFilter⁩ — تصفية السماح/الرفض بعناوين ⁦IP⁩ حسب ⁦CIDR⁩ ⁦ConnectionLimit⁩ — تحديد الاتصالات المتزامنة لكل عنوان ⁦IP⁩

> هذه الصفحة مُولَّدة تلقائياً من مخطط ⁦PKL⁩. راجع الدليل لأمثلة الاستخدام.

الأنواع

HttpMethod

سلسلة طريقة ⁦HTTP⁩، مشتركة مع ⁦Route.pkl⁩.

typealias HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "TRACE"

AccessLogFormat

تنسيق مخرجات سجل الوصول.

⁦"combined"⁩ — تنسيق سجل ⁦Apache⁩ المُدمج (⁦IP⁩، المستخدم، الطريقة، المسار، الحالة، الحجم، المُحيل، وكيل المستخدم) ⁦"common"⁩ — تنسيق سجل ⁦Apache⁩ الشائع (بدون المُحيل أو وكيل المستخدم) ⁦"json"⁩ — كائن ⁦JSON⁩ واحد لكل سطر، قابل للتحليل آلياً ⁦"ecs"⁩ — مخطط ⁦Elastic⁩ المشترك، لاستيعاب ⁦Elasticsearch⁩/⁦Kibana⁩

typealias AccessLogFormat = "combined" | "common" | "json" | "ecs"

JwtAlgorithm

معرف خوارزمية توقيع ⁦JWT⁩.

⁦RSA⁩: ⁦"RS256"⁩، ⁦"RS384"⁩، ⁦"RS512"⁩. ⁦ECDSA⁩: ⁦"ES256"⁩، ⁦"ES384"⁩، ⁦"ES512"⁩. ⁦HMAC⁩ (متماثل): ⁦"HS256"⁩، ⁦"HS384"⁩، ⁦"HS512"⁩. ⁦EdDSA⁩: ⁦"EdDSA"⁩ (⁦Ed25519⁩).

typealias JwtAlgorithm = "RS256" | "RS384" | "RS512" | "ES256" | "ES384" | "ES512" | "HS256" | "HS384" | "HS512" | "EdDSA"

Middleware

اتحاد مُمَيز لجميع أنواع الوسيط.

استخدم أحد أصناف الوسيط المحددة المُدرجة أعلاه. يمكن دمج مثيلات وسيط متعددة في ⁦Listing⁩ على كتلة خادم أو مسار.

typealias Middleware = Compress | RateLimit | Cors | Headers | BasicAuth | RequestId | AccessLog | Rewrite | BodyLimit | TailscaleAuth | ErrorPage | JwtAuth | SecurityHeaders | IpFilter | ConnectionLimit

---

Compress

ضغط الاستجابات أثناء الإرسال.

يضغط أجسام الاستجابات باستخدام تفاوض المحتوى: يختار الخادم أفضل خوارزمية من ⁦algorithms⁩ يدعمها العميل (عبر ترويسة ⁦Accept-Encoding⁩ للطلب). الاستجابات الأصغر من ⁦minSize⁩ بايت تُرسل بدون ضغط لتجنب التكلفة على الحمولات الصغيرة.

مثال

new Compress {
  algorithms { "br"; "gzip" }
  minSize = 512
}

algorithms

خوارزميات الضغط المُقدمة للعملاء، بترتيب أفضلية الخادم.

أول خوارزمية يدعمها العميل أيضاً تفوز. الافتراضي هو ⁦zstd⁩ ثم ⁦Brotli⁩ ثم ⁦gzip⁩.

minSize

الحد الأدنى لحجم جسم الاستجابة (بالبايت) المطلوب لتفعيل الضغط.

الاستجابات ذات الجسم الأصغر من هذا الحد تُرسل بدون ضغط. الافتراضي: ⁦1024⁩ بايت.

contentTypes

أنماط ⁦Content-Type⁩ المؤهلة للضغط.

أنماط النمط الشامل مدعومة (مثل ⁦"text/"⁩). عند ⁦null⁩، تُستخدم القائمة الافتراضية المُدمجة: ⁦text/⁩، ⁦application/json⁩، ⁦application/xml⁩، ⁦application/javascript⁩، وما شابه.

---

RateLimit

تحديد معدل الطلبات بنافذة منزلقة لكل مفتاح.

يتتبع عدد الطلبات ضمن نافذة زمنية منزلقة، مفهرساً بهوية العميل (عنوان ⁦IP⁩ افتراضياً). عندما يتجاوز عميل الحد، يستجيب الخادم بـ⁦429 Too Many Requests⁩ وترويسة ⁦Retry-After⁩ تشير إلى وقت استعادة السعة.

مثال

new RateLimit {
  requests = 100
  window = 60.s
  key = "ip"
}

window

مدة النافذة المنزلقة التي تُحسب خلالها ⁦requests⁩.

الافتراضي: ثانية واحدة.

burst

بدل الاندفاع فوق ⁦requests⁩ قبل بدء التقييد.

عند تعيينه، يُسمح بهذا العدد من الطلبات الإضافية في اندفاع قبل تفعيل تحديد المعدل. عند ⁦null⁩ (الافتراضي)، لا يُسمح باندفاع إضافي فوق ⁦requests⁩.

key

دالة المفتاح التي تحدد كيفية تجميع الطلبات للتحديد.

القيم المدعومة: ⁦"ip"⁩ — عنوان ⁦IP⁩ للعميل (الافتراضي) ⁦"header:"⁩ — قيمة ترويسة طلب مُسماة ⁦"query:"⁩ — قيمة معامل استعلام ⁦"cookie:"⁩ — قيمة ملف تعريف ارتباط مُسمى

الطلبات التي تتشارك نفس قيمة المفتاح تتشارك دلو تحديد معدل واحد.

statusCode

كود حالة ⁦HTTP⁩ المُرجع عند تجاوز حد المعدل.

الافتراضي: ⁦429⁩ (⁦Too Many Requests⁩).

---

Cors

ترويسات مشاركة الموارد عبر المصادر (⁦CORS⁩).

يتحكم في المصادر والطرق والترويسات المسموح بها في الطلبات عبر المصادر واستجابات الاستعلام المسبق (⁦OPTIONS⁩). يُصدر الخادم ترويسات استجابة ⁦Access-Control-*⁩ بناءً على هذه الإعدادات.

مثال

new Cors {
  allowedOrigins { "https:<<>>
  allowedMethods { "GET"; "POST" }
  credentials = true
}

allowedOrigins

المصادر المسموح لها بإجراء طلبات عبر المصادر.

استخدم ⁦""⁩ للسماح بجميع المصادر. ملاحظة: ⁦""⁩ لا يمكن دمجها مع ⁦credentials = true⁩ (المتصفحات ترفض هذا الدمج). قائمة فارغة ترفض جميع الطلبات عبر المصادر.

allowedMethods

طرق ⁦HTTP⁩ المسموح بها للطلبات عبر المصادر.

عند ⁦null⁩، يعكس الخادم الطريقة من ترويسة ⁦Access-Control-Request-Method⁩ للاستعلام المسبق.

allowedHeaders

ترويسات الطلب المسموح للعملاء بإرسالها في الطلبات عبر المصادر.

عند ⁦null⁩، جميع الترويسات مسموح بها (تُعكس من ⁦Access-Control-Request-Headers⁩).

exposeHeaders

ترويسات الاستجابة المسموح للمتصفح بكشفها لـ⁦JS⁩ من جانب العميل.

الترويسات غير المُدرجة هنا تكون مخفية عن استجابات ⁦fetch()⁩. عند ⁦null⁩، لا تُكشف ترويسات إضافية فوق مجموعة ⁦CORS⁩ الآمنة.

maxAge

مدة تخزين المتصفح المؤقت لاستجابة الاستعلام المسبق.

قيم أعلى تُقلل عدد طلبات ⁦OPTIONS⁩ للاستعلام المسبق على حساب نشر أبطأ لتغييرات سياسة ⁦CORS⁩. الافتراضي: ⁦24⁩ ساعة.

credentials

ما إذا كانت الطلبات عبر المصادر قد تتضمن بيانات الاعتماد (ملفات تعريف الارتباط، شهادات عميل ⁦TLS⁩، ترويسات ⁦Authorization⁩).

عند ⁦true⁩، يجب أن يُدرج ⁦allowedOrigins⁩ مصادر صريحة (وليس ⁦"*"⁩).

---

Headers

إضافة أو تعيين أو إزالة ترويسات الطلب والاستجابة العشوائية.

تُطبق التعديلات بهذا الترتيب لكل اتجاه (طلب أو استجابة): 1. ⁦remove⁩ — حذف الترويسة إن وُجدت 2. ⁦set⁩ — الكتابة فوق الترويسة بقيمة واحدة 3. ⁦add⁩ — إلحاق قيمة إضافية (ترويسة متعددة القيم)

مثال

new Headers {
  responseSet { ["X-Served-By"] = "elide" }
  requestRemove { "X-Forwarded-For" }
}

requestSet

ترويسات تُعيَّن على الطلب قبل أن يراها المعالج.

إذا كانت الترويسة موجودة مسبقاً، تُكتب قيمتها فوقها.

requestAdd

ترويسات تُلحق بالطلب قبل أن يراها المعالج.

إذا كانت الترويسة موجودة مسبقاً، تُضاف القيمة الجديدة بجانبها.

responseSet

ترويسات تُعيَّن على الاستجابة بعد إنتاجها من المعالج.

إذا كانت الترويسة موجودة مسبقاً، تُكتب قيمتها فوقها.

responseAdd

ترويسات تُلحق بالاستجابة بعد إنتاجها من المعالج.

إذا كانت الترويسة موجودة مسبقاً، تُضاف القيمة الجديدة بجانبها.

---

BasicAuth

مصادقة ⁦HTTP⁩ الأساسية.

يتحقق من بيانات الاعتماد من ترويسة ⁦Authorization: Basic⁩ مقابل قائمة مستخدمين ثابتة بكلمات مرور مُجزأة بـ⁦bcrypt⁩. يُرجع ⁦401 Unauthorized⁩ مع تحدي ⁦WWW-Authenticate⁩ عندما تكون بيانات الاعتماد مفقودة أو غير صالحة.

مثال

new BasicAuth {
  realm = "Admin"
  users { ["admin"] = "$2b$10$..." }
  exclude { "/healthz" }
}

realm

سلسلة النطاق المعروضة في مطالبة بيانات الاعتماد للمتصفح.

الافتراضي: ⁦"Elide"⁩.

users

المستخدمون المسموح لهم كأزواج ⁦username⁩ إلى ⁦bcrypt-hash⁩.

إدخال واحد على الأقل مطلوب. أنشئ التجزئات باستخدام ⁦elide auth hash ⁩ أو أي أداة ⁦bcrypt⁩ قياسية. يُوصى بعامل تكلفة ⁦10⁩ أو أعلى.

exclude

بادئات المسارات المُستبعدة من المصادقة.

الطلبات التي يبدأ مسارها بأي بادئة مُدرجة تتجاوز المصادقة الأساسية بالكامل. مفيدة لنقاط نهاية فحص الصحة أو الجاهزية.

---

RequestId

حقن معرف طلب فريد في كل طلب.

header

اسم الترويسة المُستخدمة لحمل معرف الطلب.

الافتراضي: ⁦"X-Request-Id"⁩. تُنسخ نفس الترويسة إلى الاستجابة.

trustIncoming

عند ⁦true⁩، يُحتفظ بقيمة موجودة في ⁦header⁩ بدلاً من توليد واحدة جديدة.

فعّل هذا عندما يحقن موازن حمل أو بوابة ⁦API⁩ علوية معرفات الطلبات مسبقاً وتريد نشرها بدون تغيير.

---

AccessLog

تسجيل وصول مُهيكل لكل طلب.

يُصدر سجل واحد لكل طلب بعد إرسال الاستجابة. عند استخدامه على مستوى الخادم، يُسجل كل طلب. عند ربطه بمسار، تُسجل فقط الطلبات المطابقة. يمكن لهذا الوسيط التعايش مع ⁦LoggingSettings.accessLog⁩ للتجاوزات المحددة بالمسار أو التنسيق.

format

تنسيق مخرجات السجل.

الافتراضي: ⁦"json"⁩ (كائن ⁦JSON⁩ واحد لكل سطر). راجع ⁦AccessLogFormat⁩ لجميع الخيارات.

output

وجهة مخرجات السجل.

يقبل ⁦"stdout"⁩ أو ⁦"stderr"⁩ أو مسار ملف مطلق. عند استخدام مسار ملف، يُنشأ الملف إذا لم يكن موجوداً ويُلحق به خلاف ذلك.

includeHeaders

أسماء ترويسات الطلب التي تُضمن قيمها في كل سجل.

مفيدة لالتقاط معرفات الارتباط وتلميحات العميل أو الترويسات الخاصة بالتطبيق. راجع ⁦RequestId⁩ لحقن المعرفات تلقائياً.

minStatus

الحد الأدنى لكود حالة استجابة ⁦HTTP⁩ للتسجيل.

الاستجابات ذات الحالة أقل من هذه القيمة تُسقط بصمت. الافتراضي: ⁦0⁩ (تسجيل كل شيء). عيّنه إلى ⁦400⁩ لتسجيل الأخطاء فقط.

condition

تعبير تصفية تسجيل مشروط.

عند تعيينه، فقط الطلبات المطابقة للشرط تُنتج سجلاً. عند ⁦null⁩ (الافتراضي)، تُسجل جميع الطلبات (بشرط ⁦minStatus⁩). التنسيقات المدعومة: ⁦"status:4xx"⁩ — تسجيل استجابات ⁦4xx⁩ فقط ⁦"status:4xx-5xx"⁩ — تسجيل استجابات ⁦4xx⁩ و⁦5xx⁩ ⁦"status:500"⁩ — تسجيل الحالة ⁦500⁩ فقط ⁦"status:400-599"⁩ — تسجيل الحالة ⁦400⁩ إلى ⁦599⁩ ⁦"path:/api/*"⁩ — تسجيل الطلبات التي يبدأ مسارها بـ⁦/api/⁩ ⁦"path_regex:^/api/.*"⁩ — تسجيل الطلبات المطابقة لتعبير نظامي

---

Rewrite

إعادة كتابة مسار الطلب قبل مطابقة المسارات.

يُطبق استبدال تعبير نظامي على مسار ⁦URI⁩ للطلب (واختيارياً سلسلة الاستعلام). تُنفذ إعادة الكتابة قبل مطابقة المسارات، لذا ترى المسارات والمعالجات اللاحقة المسار المُعاد كتابته.

مثال

new Rewrite {
  from = "^/v1/(.*)"
  to = "/api/$1"
}

from

تعبير نظامي يُطابق مقابل مسار ⁦URI⁩ للطلب.

يمكن الإشارة إلى المجموعات الملتقطة في ⁦to⁩ باستخدام ⁦$1⁩، ⁦$2⁩، إلخ. يجب ألا يكون فارغاً.

to

نمط الاستبدال المُعوض عن الجزء المطابق من المسار.

يدعم مراجع المجموعات الملتقطة (⁦$1⁩، ⁦$2⁩، ...). يجب ألا يكون فارغاً.

replaceAll

عند ⁦true⁩، استبدال جميع تكرارات النمط في المسار.

عند ⁦false⁩ (الافتراضي)، يُستبدل أول تطابق فقط.

---

BodyLimit

رفض أجسام الطلبات التي تتجاوز حد حجم قابل للإعداد.

يُرجع ⁦413 Content Too Large⁩ عندما تتجاوز ترويسة ⁦Content-Length⁩ قيمة ⁦maxBytes⁩، أو عندما ينمو جسم مُجزأ/متدفق فوق الحد أثناء النقل. يُغلق الاتصال فوراً عند الرفض.

مثال

new BodyLimit { maxBytes = 10_000_000 }  // 10 MB

---

TailscaleAuth

مصادقة الطلبات المدركة لهوية ⁦Tailscale⁩.

تحل هوية ⁦Tailscale⁩ لكل طلب وارد عبر واجهة ⁦whois⁩ المحلية لـ⁦tailscaled⁩ وتُقيّم اختيارياً سياسات الوصول لكل مسار. يتطلب أن يكون ⁦--tailscale⁩ نشطاً أثناء التشغيل.

ترتيب التقييم: تُفحص قواعد الرفض قبل قواعد السماح. إذا طابق طلب قاعدة رفض، يُرفض بغض النظر عن قواعد السماح.

`Tailscale-User-Login`, `Tailscale-User-Name`,
`Tailscale-Node-Name`, `Tailscale-Node-Tags`

injectHeaders

حقن ترويسات هوية ⁦Tailscale⁩ في كل طلب مُصادق.

الافتراضي: ⁦true⁩.

allowAll

السماح لجميع أعضاء الشبكة الخاصة بدون فحوصات إضافية.

عند ⁦true⁩، يتجاوز ⁦allowUsers⁩ و⁦allowTags⁩ (جميع أعضاء الشبكة مسموح لهم). تُحقن ترويسات الهوية عند ⁦injectHeaders⁩ بقيمة ⁦true⁩. عند ⁦null⁩، تُطبق قوائم السماح/الرفض.

allowUsers

أسماء تسجيل دخول ⁦Tailscale⁩ (عناوين البريد الإلكتروني) المسموح لها بالوصول.

عند ⁦null⁩، لا تُطبق تصفية حسب المستخدم.

denyUsers

أسماء تسجيل دخول ⁦Tailscale⁩ المرفوض وصولها.

تُقيَّم قواعد الرفض قبل قواعد السماح.

allowTags

علامات ⁦ACL⁩ لـ⁦Tailscale⁩ المسموح لعُقدها بالوصول.

على سبيل المثال، ⁦"tag:web"⁩ أو ⁦"tag:prod"⁩. عند ⁦null⁩، لا تُطبق تصفية حسب العلامة.

denyTags

علامات ⁦ACL⁩ لـ⁦Tailscale⁩ المرفوض وصول عُقدها.

تُقيَّم قواعد الرفض قبل قواعد السماح.

---

ErrorPage

صفحة خطأ ⁦HTML⁩ مخصصة لكود حالة ⁦HTTP⁩ محدد.

تستبدل جسم استجابة الخطأ الافتراضي بقالب ⁦HTML⁩ يوفره المستخدم. تُستبدل متغيرات القالب لكل طلب: ⁦{{status}}⁩ — كود حالة ⁦HTTP⁩ الرقمي (مثل ⁦404⁩) ⁦{{message}}⁩ — عبارة سبب ⁦HTTP⁩ (مثل ⁦Not Found⁩) ⁦{{path}}⁩ — مسار ⁦URI⁩ للطلب

تُحمل القوالب عند بدء التشغيل وتُخزن في الذاكرة. أضف ⁦ErrorPage⁩ واحد لكل كود حالة تريد تخصيصه.

مثال

new ErrorPage {
  status = 404
  template = "./errors/404.html"
}

status

كود حالة ⁦HTTP⁩ الذي تُطبق عليه صفحة الخطأ هذه.

يجب أن يكون في النطاق ⁦400⁩-⁦599⁩ (خطأ عميل أو خادم).

template

مسار ملف أو قالب ⁦HTML⁩ مُضمن لصفحة الخطأ.

عندما تبدو القيمة كمسار ملف (تحتوي على ⁦/⁩ أو ⁦\⁩)، يُحمل الملف عند بدء التشغيل. خلاف ذلك، تُعامل كـ⁦HTML⁩ مُضمن. يدعم عناصر النائبة ⁦{{status}}⁩ و⁦{{message}}⁩ و⁦{{path}}⁩.

---

JwtKey

مفتاح عام ثابت يُستخدم للتحقق من توقيع ⁦JWT⁩.

kid

معرف المفتاح (⁦kid⁩) لاختيار المفتاح.

عند تعيينه، فقط الرموز التي تطابق ترويسة ⁦JOSE⁩ ⁦kid⁩ الخاصة بها هذه القيمة ستُتحقق بهذا المفتاح. عند ⁦null⁩، يُجرب المفتاح لجميع الرموز التي تطابق ⁦alg⁩.

pem

مفتاح عام بترميز ⁦PEM⁩ بتنسيق ⁦SPKI⁩ أو ⁦PKCS#8⁩.

لخوارزميات ⁦HMAC⁩ (⁦HS256⁩/⁦HS384⁩/⁦HS512⁩)، هذا هو السر المشترك المُرمز بـ⁦base64⁩.

---

JwtAuth

مصادقة رموز ⁦JWT⁩/⁦OAuth⁩.

يتحقق من رموز ⁦JSON Web Tokens⁩ (⁦JWT⁩) باستخدام مفاتيح عامة ثابتة مع التحقق من التوقيع بمكتبة ⁦ring⁩. يدعم ⁦RSA⁩ (⁦RS256⁩/⁦RS384⁩/⁦RS512⁩)، و⁦ECDSA⁩ (⁦ES256⁩/⁦ES384⁩/⁦ES512⁩)، و⁦HMAC⁩ (⁦HS256⁩/⁦HS384⁩/⁦HS512⁩)، و⁦EdDSA⁩.

يمكن استخراج الرموز من مصادر متعددة (تُفحص بالترتيب): ⁦"bearer"⁩ — ترويسة ⁦Authorization: Bearer ⁩ ⁦"cookie:"⁩ — قيمة ملف تعريف ارتباط مُسمى ⁦"query:"⁩ — قيمة معامل استعلام ⁦"header:"⁩ — قيمة ترويسة مخصصة

يُرجع ⁦401 Unauthorized⁩ عند عدم العثور على رمز صالح.

مثال

new JwtAuth {
  keys { new JwtKey { alg = "RS256"; pem = read("./public.pem") } }
  audiences { "https:<<>>
  exclude { "/healthz" }
}

keys

مفاتيح عامة ثابتة للتحقق من التوقيع.

يجب توفير مفتاح واحد على الأقل. راجع ⁦JwtKey⁩ لتنسيق المفتاح. عند وجود ترويسة ⁦kid⁩ في الرمز، تُجرب فقط المفاتيح ذات ⁦kid⁩ المطابق؛ وإلا تُجرب جميع المفاتيح ذات ⁦alg⁩ المطابق.

algorithms

الخوارزميات المقبولة للتحقق من الرموز.

تُرفض الرموز الموقعة بخوارزمية ليست في هذه القائمة حتى لو وُجد مفتاح مطابق. هذا يمنع هجمات إرباك الخوارزميات. الافتراضي: ⁦["RS256"]⁩.

issuers

مُصدرو الرموز المسموح بهم (مطالبة ⁦iss⁩).

عند عدم كونها فارغة، تُرفض الرموز التي لا تطابق مطالبة ⁦iss⁩ الخاصة بها أي إدخال. عند الفراغ (الافتراضي)، يُقبل أي مُصدر.

audiences

جمهور الرموز المسموح به (مطالبة ⁦aud⁩).

عند عدم كونها فارغة، تُرفض الرموز التي لا تتضمن مطالبة ⁦aud⁩ الخاصة بها قيمة واحدة مُدرجة على الأقل. عند الفراغ (الافتراضي)، يُقبل أي جمهور.

clockSkewSecs

تسامح انحراف الساعة (بالثواني) لفحوصات مطالبتي ⁦exp⁩ و⁦nbf⁩.

يعوض عن انحراف الساعة بين مُصدر الرمز وهذا الخادم. الافتراضي: ⁦30⁩ ثانية.

tokenSources

قائمة مرتبة بمواقع استخراج ⁦JWT⁩ منها.

أول مصدر يُنتج رمزاً يفوز. القيم المدعومة: ⁦"bearer"⁩ — ترويسة ⁦Authorization: Bearer ⁩ ⁦"cookie:"⁩ — ملف تعريف ارتباط مُسمى ⁦"query:"⁩ — معامل استعلام ⁦"header:"⁩ — ترويسة طلب مخصصة

عند الفراغ (الافتراضي)، يُستخدم ⁦"bearer"⁩ أثناء التشغيل.

exclude

بادئات المسارات المُستبعدة من مصادقة ⁦JWT⁩.

الطلبات التي يبدأ مسارها بأي بادئة مُدرجة تتجاوز التحقق من الرمز. مفيدة لفحوصات الصحة ونقاط النهاية العامة.

injectClaimsHeaders

عند ⁦true⁩، حقن مطالبات ⁦JWT⁩ المُتحقق منها كترويسات طلب.

كل مطالبة تصبح ترويسة بالاسم ⁦⁩ — على سبيل المثال، مطالبة ⁦sub⁩ تصبح ⁦X-Jwt-Claim-Sub⁩.

claimsHeaderPrefix

البادئة المُلحقة بأسماء المطالبات عند حقن ترويسات المطالبات.

الافتراضي: ⁦"X-Jwt-Claim-"⁩.

---

IpFilter

تصفية السماح/الرفض بعناوين ⁦IP⁩ حسب ⁦CIDR⁩.

يتحكم في الوصول بناءً على عنوان ⁦IP⁩ للعميل. عند تحديد كل من ⁦allow⁩ و⁦deny⁩، الرفض له الأولوية (عنوان ⁦IP⁩ مرفوض يُرفض حتى لو طابق إدخال سماح أيضاً). الطلبات المرفوضة تتلقى ⁦403 Forbidden⁩.

عند فراغ كلتا القائمتين، هذا الوسيط لا يفعل شيئاً.

مثال

new IpFilter {
  allow { "10.0.0.0/8"; "172.16.0.0/12" }
  deny  { "10.0.0.1/32" }
}

allow

نطاقات ⁦CIDR⁩ المسموح بها.

عند عدم كونها فارغة، فقط عناوين ⁦IP⁩ للعملاء المطابقة لإدخال واحد على الأقل مسموح بها. يدعم كلاً من تدوين ⁦IPv4⁩ و⁦IPv6⁩ (مثل ⁦"10.0.0.0/8"⁩، ⁦"::1/128"⁩).

deny

نطاقات ⁦CIDR⁩ المرفوضة.

الرفض له الأولوية على السماح. يدعم كلاً من تدوين ⁦IPv4⁩ و⁦IPv6⁩.

---

SecurityHeaders

ترويسات أمان الاستجابة القياسية (⁦HSTS⁩، ⁦X-Frame-Options⁩، ⁦CSP⁩، إلخ.).

يحقن ترويسات أمان في كل استجابة. كل حقل يُقابل ترويسة واحدة. عندما يكون الحقل ⁦null⁩، تُستخدم القيمة الافتراضية المُدمجة. عيّن الحقل إلى ⁦""⁩ (سلسلة فارغة) لإخفاء تلك الترويسة بالكامل.

مثال

new SecurityHeaders {
  hsts = "max-age=63072000; includeSubDomains; preload"
  contentSecurityPolicy = "default-src 'self'"
}

hsts

قيمة ترويسة ⁦Strict-Transport-Security⁩.

يتحكم في فرض ⁦HTTPS⁩ في المتصفحات. عند ⁦null⁩، تُستخدم القيمة الافتراضية المُدمجة. مثال: ⁦"max-age=31536000; includeSubDomains"⁩.

xContentTypeOptions

قيمة ترويسة ⁦X-Content-Type-Options⁩.

يمنع استنشاق نوع ⁦MIME⁩. القيمة الافتراضية المُدمجة: ⁦"nosniff"⁩.

xFrameOptions

قيمة ترويسة ⁦X-Frame-Options⁩.

يتحكم فيما إذا كان يمكن تضمين الصفحة في ⁦