DOMPurify v3.4.13

jsdom

### استخدام الإصدار الإنتاجي المصغّر والمُختبَر (خريطة المصدر متاحة)```html
<script type="text/javascript" src="dist/purify.min.js"></script>

أو ربما هذا، إذا كنت تحب العمل مع Angular أو ما يشابهه:```js
import DOMPurify from 'dompurify';

const clean = DOMPurify.sanitize('<b>hello there</b>');

### هل هناك أي احتمال لإطلاق النار على القدم؟

حسنًا، لاحظ أنه إذا قمت _أولاً_ بتنقية HTML ثم قمت بتعديله _بعد ذلك_، فقد تُبطل بسهولة **تأثيرات التنقية**. إذا مرّرت الترميز المُنقّى إلى مكتبة أخرى _بعد_ التنقية، فتأكد من أن تلك المكتبة لا تعبث بالـ HTML من تلقاء نفسها. راجع [أهداف الأمان ونموذج التهديد](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model) للحصول على وصفات الاستخدام الآمن والوسوم/السمات التي تستحق إعادة النظر، و[فئات الهجمات وتاريخ التحايل](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History) لفهم سبب إبطال المعالجة اللاحقة وتغيير سياق الترميز للتنقية.

### حسنًا، هذا منطقي، لننتقل

بعد تنقية الترميز الخاص بك، يمكنك أيضًا إلقاء نظرة على الخاصية `DOMPurify.removed` لتعرف أي العناصر والسمات تم تجاهلها. يرجى **عدم استخدام** هذه الخاصية لاتخاذ أي قرارات حاسمة متعلقة بالأمان. إنها مجرد أداة مساعدة صغيرة للمهتمين.

### تشغيل DOMPurify على الخادم

يعمل DOMPurify تقنيًا أيضًا على جانب الخادم مع Node.js. ويسعى دعمنا إلى اتباع [دورة إصدارات Node.js](https://nodejs.org/en/about/previous-releases).

يتطلب تشغيل DOMPurify على الخادم وجود DOM، وهذا غالبًا ليس مفاجئًا. عادةً ما تكون [jsdom](https://github.com/jsdom/jsdom) هي الأداة المفضلة، ونحن **ننصح بشدة** باستخدام أحدث إصدار من _jsdom_.

لماذا؟ لأن الإصدارات الأقدم من _jsdom_ معروفة بوجود أخطاء فيها تؤدي إلى XSS _حتى لو_ قام DOMPurify بكل شيء بشكل صحيح بنسبة 100%. توجد **نواقل هجوم معروفة**، على سبيل المثال، في _jsdom v19.0.0_ وقد تم إصلاحها في _jsdom v20.0.0_ - وننصح حقًا بإبقاء _jsdom_ محدّثًا بسبب ذلك.

يرجى أيضًا الانتباه إلى وجود أدوات مثل [happy-dom](https://github.com/capricorn86/happy-dom)، لكنها **لا تُعتبر آمنة** في الوقت الحالي. لا يُنصح حاليًا بدمج DOMPurify مع _happy-dom_، ومن المرجح أن يؤدي ذلك إلى XSS. للاطلاع على خلفية حول كون الـ DOM من جانب الخادم الذي تختاره جزءًا من قاعدة الحوسبة الموثوقة لديك، راجع [فئات الهجمات وتاريخ التحايل](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History).

بخلاف ذلك، لا بأس في استخدام DOMPurify على الخادم. على الأرجح. يعتمد هذا حقًا على _jsdom_ أو أي DOM تستخدمه من جانب الخادم. إذا كان بإمكانك تقبّل ذلك، فهذه هي طريقة تشغيله:```bash
npm install dompurify
npm install jsdom

أو حتى هذا، إذا كنت تفضل العمل مع imports:```js
import { JSDOM } from 'jsdom';
import DOMPurify from 'dompurify';

const window = new JSDOM('').window;
const purify = DOMPurify(window);
const clean = purify.sanitize('<b>hello there</b>');

لم يتم توفير أي محتوى في المدخلات (INPUT) لهذه القطعة. لا يوجد نص للترجمة.```js
import DOMPurify from 'isomorphic-dompurify';

const clean = DOMPurify.sanitize('<s>hello</s>');

هذه مجرد عينة. للحصول على التصنيف الكامل لفئات الهجمات التي تأتي منها هذه العينات - mutation XSS وnamespace confusion وDOM clobbering وrawtext breakouts وغيرها - راجع [فئات الهجمات وسجل الالتفاف](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History).

## ما المدعوم؟

يدعم DOMPurify حاليًا HTML5 وSVG وMathML. يسمح DOMPurify افتراضيًا بسمات CSS وسمات البيانات المخصصة في HTML. يدعم DOMPurify أيضًا Shadow DOM - ويقوم بتعقيم قوالب DOM بشكل تكراري. يتيح لك DOMPurify أيضًا تعقيم HTML لاستخدامه مع واجهة jQuery `$()` و`elm.html()` API دون أي مشاكل معروفة. للحصول على المجموعة الدقيقة للعناصر والسمات المسموح بها افتراضيًا، راجع صفحة الويكي [Default TAGs & ATTRIBUTEs allow-list & blocklist](https://github.com/cure53/DOMPurify/wiki/Default-TAGs-ATTRIBUTEs-allow-list-&-blocklist).

## ماذا عن المتصفحات القديمة مثل Internet Explorer؟

لا يفعل DOMPurify أي شيء على الإطلاق. فهو ببساطة يعيد لك السلسلة النصية التي أدخلتها تمامًا. يكشف DOMPurify عن خاصية تسمى `isSupported`، والتي تخبرك ما إذا كان قادرًا على أداء مهمته، حتى تتمكن من وضع خطتك الاحتياطية الخاصة.

## ماذا عن DOMPurify وTrusted Types؟

في الإصدار 1.0.9، تمت إضافة دعم [Trusted Types API](https://github.com/w3c/webappsec-trusted-types) ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API)) إلى DOMPurify.
في الإصدار 2.0.0، تمت إضافة علامة تهيئة للتحكم في سلوك DOMPurify في هذا الشأن.

عند استخدام `DOMPurify.sanitize` في بيئة تتوفر فيها Trusted Types API ويتم تعيين `RETURN_TRUSTED_TYPE` إلى `true`، فإنه يحاول إرجاع قيمة `TrustedHTML` بدلاً من سلسلة نصية (لا يتغير سلوك خيارات التهيئة `RETURN_DOM` و`RETURN_DOM_FRAGMENT`).

لاحظ أنه لإنشاء سياسة في `trustedTypes` باستخدام DOMPurify، يلزم تعيين `RETURN_TRUSTED_TYPE: false`، لأن `createHTML` يتوقع سلسلة نصية عادية وليس `TrustedHTML`. المثال أدناه يوضح ذلك.```js
window.trustedTypes.createPolicy('default', {
  createHTML: (to_escape) =>
    DOMPurify.sanitize(to_escape, { RETURN_TRUSTED_TYPE: false }),
});

لا **تمرّر** سياسة الالتفاف الخاصة بك إلى DOMPurify كسياسة `TRUSTED_TYPES_POLICY` الخاصة به (على سبيل المثال عبر `DOMPurify.setConfig({ TRUSTED_TYPES_POLICY: myPolicy })`) عندما تستدعي `createHTML` في تلك السياسة `DOMPurify.sanitize` بالفعل. هذا دوران دائري بالتعريف - فالتعقيم سيستدعي السياسة، والسياسة تعقّم باستدعاء DOMPurify مجددًا - وسيرمي DOMPurify خطأ `TypeError` وصفيًا لمنع التكرار اللانهائي. يجب أن تستدعي سياستك الخاصة DOMPurify؛ ولا ينبغي تكوين DOMPurify ليستدعي سياستك.

إذا أردت تطبيق نمط سياسة `default` هذه على صفحة كاملة تلقائيًا - بحيث يتم تعقيم كل مصرف HTML، بما في ذلك التعليمات البرمجية القديمة، وأدوات الطرف الثالث، وآلاف عمليات إسناد `innerHTML` التي لا يمكنك العثور عليها أو إعادة كتابتها بسهولة - فألقِ نظرة على [DOMFortify](https://github.com/cure53/DOMFortify). فهو يثبّت بالضبط سياسة `default` من Trusted Types مدعومة بـ DOMPurify ويرفض مصرفات النصوص البرمجية (`eval`, `script.src`, ...) رفضًا قاطعًا. وهو مشروع منفصل عمدًا: يبقى DOMPurify معقّمًا مركّزًا، بينما يتولى DOMFortify طبقة الإنفاذ على مستوى المستند التي هي خارج نطاق DOMPurify عن قصد.

## هل يمكنني تكوين DOMPurify؟

نعم. قيم التكوين الافتراضية المضمنة جيدة جدًا بالفعل - لكن يمكنك بالطبع تجاوزها. اطّلع على مجلد [`/demos`](https://github.com/cure53/DOMPurify/tree/main/demos) لترى مجموعة من الأمثلة حول كيفية [تخصيص DOMPurify](https://github.com/cure53/DOMPurify/tree/main/demos#what-is-this).

قبل توسيع القائمة المسموح بها (`ADD_TAGS`, `ADD_ATTR`, `CUSTOM_ELEMENT_HANDLING`, …) أو تخفيف إعداد افتراضي، يجدر بك تصفّح [الوسوم والسمات التي يجب التفكير فيها مرتين](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model#dangerous-tags-and-attributes-think-twice-before-allow-listing) - فبعضها خطير بطرق غير واضحة.

### إعدادات عامة```js
// strip {{ ... }}, ${ ... } and <% ... %> to make output safe for template systems
// be careful please, this mode is not recommended for production usage.
// allowing template parsing in user-controlled HTML is not advised at all.
// only use this mode if there is really no alternative.
const clean = DOMPurify.sanitize(dirty, { SAFE_FOR_TEMPLATES: true });

// change how e.g. comments containing risky HTML characters are treated.
// be very careful, this setting should only be set to `false` if you really only handle
// HTML and nothing else, no SVG, MathML or the like.
// Otherwise, changing from `true` to `false` will lead to XSS in this or some other way.
const clean = DOMPurify.sanitize(dirty, { SAFE_FOR_XML: false });

### التحكم في السلوك المتعلق بالعناصر المخصصة```js
// DOMPurify allows to define rules for Custom Elements. When using the CUSTOM_ELEMENT_HANDLING
// literal, it is possible to define exactly what elements you wish to allow (by default, none are allowed).
//
// The same goes for their attributes. By default, the built-in or configured allow.list is used.
//
// You can use a RegExp literal to specify what is allowed or a predicate, examples for both can be seen below.
// When using a predicate function for attributeNameCheck, it can optionally receive the tagName as a second parameter
// for more granular control over which attributes are allowed for specific elements.
// The default values are very restrictive to prevent accidental XSS bypasses. Handle with great care!

const clean = DOMPurify.sanitize(
  '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: null, // no custom elements are allowed
      attributeNameCheck: null, // default / standard attribute allow-list is used
      allowCustomizedBuiltInElements: false, // no customized built-ins allowed
    },
  }
); // <div is=""></div>

const clean = DOMPurify.sanitize(
  '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: /^foo-/, // allow all tags starting with "foo-"
      attributeNameCheck: /baz/, // allow all attributes containing "baz"
      allowCustomizedBuiltInElements: true, // customized built-ins are allowed
    },
  }
); // <foo-bar baz="foobar"></foo-bar><div is="foo-baz"></div>

const clean = DOMPurify.sanitize(
  '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: (tagName) => tagName.match(/^foo-/), // allow all tags starting with "foo-"
      attributeNameCheck: (attr) => attr.match(/baz/), // allow all containing "baz"
      allowCustomizedBuiltInElements: true, // allow customized built-ins
    },
  }
); // <foo-bar baz="foobar"></foo-bar><div is="foo-baz"></div>

// Example with attributeNameCheck receiving tagName as a second parameter
const clean = DOMPurify.sanitize(
  '<element-one attribute-one="1" attribute-two="2"></element-one><element-two attribute-one="1" attribute-two="2"></element-two>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: (tagName) => tagName.match(/^element-(one|two)$/),
      attributeNameCheck: (attr, tagName) => {
        if (tagName === 'element-one') {
          return ['attribute-one'].includes(attr);
        } else if (tagName === 'element-two') {
          return ['attribute-two'].includes(attr);
        } else {
          return false;
        }
      },
      allowCustomizedBuiltInElements: false,
    },
  }
); // <element-one attribute-one="1"></element-one><element-two attribute-two="2"></element-two>

### التحكم في قيم السمات المسموح بها```js
// allow external protocol handlers in URL attributes (default is false, be careful, XSS risk)
// by default only http, https, ftp, ftps, tel, mailto, callto, sms, cid, xmpp and matrix are allowed.
const clean = DOMPurify.sanitize(dirty, { ALLOW_UNKNOWN_PROTOCOLS: true });

// allow specific protocol handlers in URL attributes via regex (default is false, be careful, XSS risk)
// by default only (protocol-)relative URLs, http, https, ftp, ftps, tel, mailto, callto, sms, cid, xmpp and matrix are allowed.
// Default RegExp: /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|sms|cid|xmpp):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i;
const clean = DOMPurify.sanitize(dirty, {
  ALLOWED_URI_REGEXP:
    /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|sms|cid|xmpp|matrix):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i,
});

### التأثير على كيفية التعقيم```js
// return entire document including <html> tags (default is false)
const clean = DOMPurify.sanitize(dirty, { WHOLE_DOCUMENT: true });

// disable DOM Clobbering protection on output (default is true, handle with care, minor XSS risks here)
const clean = DOMPurify.sanitize(dirty, { SANITIZE_DOM: false });

// enforce strict DOM Clobbering protection via namespace isolation (default is false)
// when enabled, isolates the namespace of named properties (i.e., `id` and `name` attributes)
// from JS variables by prefixing them with the string `user-content-`
const clean = DOMPurify.sanitize(dirty, { SANITIZE_NAMED_PROPS: true });

// keep an element's content when the element is removed (default is true)
const clean = DOMPurify.sanitize(dirty, { KEEP_CONTENT: false });

// glue elements like style, script or others to document.body and prevent unintuitive browser behavior in several edge-cases (default is false)
const clean = DOMPurify.sanitize(dirty, { FORCE_BODY: true });

// remove all <a> elements under <p> elements that are removed
const clean = DOMPurify.sanitize(dirty, {
  FORBID_CONTENTS: ['a'],
  FORBID_TAGS: ['p'],
});

// extend the default FORBID_CONTENTS list to also remove <a> elements under <p> elements
const clean = DOMPurify.sanitize(dirty, {
  ADD_FORBID_CONTENTS: ['a'],
  FORBID_TAGS: ['p'],
});

// change the parser type so sanitized data is treated as XML and not as HTML, which is the default
const clean = DOMPurify.sanitize(dirty, {
  PARSER_MEDIA_TYPE: 'application/xhtml+xml',
});

هناك حتى [مزيد من الأمثلة هنا](https://github.com/cure53/DOMPurify/tree/main/demos#what-is-this)، توضح كيف يمكنك تشغيل DOMPurify وتخصيصه وتهيئته ليلائم احتياجاتك.

## التكوين الدائم

بدلاً من تمرير نفس التكوين مرارًا وتكرارًا إلى `DOMPurify.sanitize`، يمكنك استخدام طريقة `DOMPurify.setConfig`. سيستمر تكوينك حتى استدعائك التالي لـ `DOMPurify.setConfig`، أو حتى تقوم باستدعاء `DOMPurify.clearConfig` لإعادة تعيينه. تذكر أن هناك تكوينًا نشطًا واحدًا فقط، مما يعني أنه بمجرد تعيينه، يتم تجاهل جميع معاملات التكوين الإضافية التي تمررها إلى `DOMPurify.sanitize`.

## الخطافات (Hooks)

يتيح لك DOMPurify توسيع وظائفه عن طريق إرفاق دالة أو أكثر باستخدام طريقة `DOMPurify.addHook` بأحد الخطافات التالية:

- `beforeSanitizeElements`
- `uponSanitizeElement` (بدون حرف 's' - يُستدعى لكل عنصر)
- `afterSanitizeElements`
- `beforeSanitizeAttributes`
- `uponSanitizeAttribute`
- `afterSanitizeAttributes`
- `beforeSanitizeShadowDOM`
- `uponSanitizeShadowNode`
- `afterSanitizeShadowDOM`

يقوم بتمرير عقدة DOM المعالجة حاليًا، وعند الحاجة، حرفية تحتوي على بيانات العقدة والسمات المؤكدة وإعدادات DOMPurify إلى دالة الاستدعاء. اطّلع على [عرض MentalJS hook](https://github.com/cure53/DOMPurify/blob/main/demos/hooks-mentaljs-demo.html) لترى كيف يمكن استخدام هذه الواجهة البرمجية بشكل أنيق.

_مثال_:```js
DOMPurify.addHook(
  'uponSanitizeAttribute',
  function (currentNode, hookEvent, config) {
    // Do something with the current node
    // You can also mutate hookEvent for current node (i.e. set hookEvent.forceKeepAttr = true)
    // For other than 'uponSanitizeAttribute' hook types hookEvent equals to null
  }
);

DOMPurify v3.4.13

DOMPurify

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

ماذا يفعل؟

كيف أستخدمه؟

استخدام النسخة غير المضغوطة (خريطة المصدر متاحة)```html

هل يوجد عرض توضيحي؟

ماذا لو وجدت ثغرة أمنية؟

بعض الأمثلة على التنقية من فضلك؟

التحكم في قوائم السماح وقوائم الحظر لدينا```js

التحكم في السلوك المتعلق بقيم URI```js

التأثير على نوع الإرجاع```js

التحكم في مكان التعقيم```js

ملاحظة حول استدعاء sanitize() من خطاف

الإعدادات المُزالة

التكامل المستمر

التطوير والمساهمة

التثبيت (npm i)

السكربتات

القائمة البريدية الأمنية

من ساهم؟

الفئات

ملاحظة حول استدعاء `sanitize()` من خطاف

التثبيت (`npm i`)