### [React](https://github.com/lavamoat/lavadome/blob/HEAD/packages/react)```javascript
import { LavaDome as LavaDomeReact, toLavaDomeToken } from '@lavamoat/lavadome-react';

function Secret({ text }) {
    const {token, copy} = toLavaDomeCapabilities(text);
    return <>
        <a onClick={copy}> copy to clipboard </a>
        <LavaDomeReact token={token} />
    </>;
}

### الاستخدام الآمن

نظرًا لقيود النواة الأساسية للويب، لدمج LavaDome بشكل آمن، هناك عدد من الأمور التي يجب الانتباه إليها وتتطلب جهدًا فعّالًا من المطور الذي يقوم بالدمج:

#### ترتيب التنفيذ

LavaDome، مثل أي برنامج أمان آخر بلغة JavaScript، يكون دائمًا عرضة للكود الذي يعمل قبله.

هذا يعني أنه باستثناء الكود الذي نثق به تمامًا، يجب أن يكون LavaDome أول قطعة كود يتم تحميلها في برنامج تطبيق الويب.

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

للقيام بذلك بشكل صحيح (آمن)، يجب أن يكون أول تعريف import/require في البرنامج بأكمله:```javascript
import '@lavamoat/lavadome-react';
import 'other-stuff';

console.log('Program starts here');

ويجب ألا يكون:```html
<span> <lavadome>your key is 234789</lavadome> </span>

فيما يلي بعض طرق الأدوات المساعدة للتصحيح التي يصدّرها `LavaDomeDebug` لمساعدتك في اختبار المكونات القائمة على `LavaDome`:

#### `getTextByRoot()`

عند إعطاء جذر مرتبط بـ `LavaDome`، سيقوم `getTextByRoot()` باستخراج السر الداخلي وإعادة بنائه بشكل تكراري. وللسماح بذلك، يجب أن يكون مثيل `LavaDome` قد تم تهيئته في الأصل مع الخيار غير الآمن `@unsafeOpenModeShadow`، مما يجعل الظلال الداخلية لـ `LavaDome` قابلة للوصول من الخارج.

بطبيعة الحال، هذا غير آمن ويجعل `LavaDome` عرضة للخطر تمامًا، لكنه منطقي للاستخدام لأغراض الاختبار/التصحيح فقط - تأكد من عدم تفعيل هذا الخيار أبدًا في الإنتاج!```javascript
new LavaDomeJavaScript(root, {
    unsafeOpenModeShadow: isThisTestingEnv, // boolean
}).text('123456');
LavaDomeDebug.getTextByRoot(root) === '123456'; // true

## التطوير

لإعداد بيئة تطوير محلية لـ **`LavaDome`**، استنسخ هذا المستودع وشغّل أحد الأوامر التالية:```bash
npm install && npm install --global serve

## الحل

تمكننا واجهة برمجة تطبيقات الويب [`ShadowDom`](https://web.dev/articles/`ShadowDom`-v1) من عزل وتغليف عُقد DOM. ورغم أنه [لم يُصمم كميزة أمنية](https://web.dev/articles/`ShadowDom`-v1#:~:text=Note%3A%20Closed%20shadow%20roots%20are%20not%20very%20useful.%20Some%20developers%20will%20see%20closed%20mode%20as%20an%20artificial%20security%20feature.%20But%20let%27s%20be%20clear%2C%20it%27s%20not%20a%20security%20feature.for%20Closed%20mode%20simply%20prevents%20outside%20JS%20from%20drilling%20into%20an%20element%27s%20internal%20DOM.)، فإن `ShadowDom` يعمل بشكل جيد لعزل الأشجار الفرعية لـ DOM عن JavaScript وCSS التي تعمل في مكان آخر من الصفحة.

يعتمد الأسلوب الأساسي لـ **`LavaDome`** على الاستفادة من `ShadowDom`، مع معالجة [فجواته الأمنية المحتملة](https://blog.ankursundara.com/shadow-dom/) بعناية.

يُقصد بـ **[LavaDome](https://github.com/lavamoat/lavadome/)** أن يكون **أداة أمنية في صندوق أدوات LavaMoat** لبناء مكونات تعمل في الواجهة الأمامية فقط، تسمح حصريًا بالتفاعل مع المستخدم والكود الموثوق، مع حظر محاولات الوصول من كود JavaScript وCSS غير الموثوق في التطبيق.

> تحية إلى [@arxenix](https://github.com/arxenix) على [بحثهم](https://blog.ankursundara.com/shadow-dom/) حول أمان `ShadowDom`، الذي وفّر الأساس لتحسينات أمنية كبيرة تم تنفيذها في **`LavaDome`**.

## الأهداف

يتبع مشروع **`LavaDome`** المبادئ الأساسية التالية:

### الأمان

أولويتنا القصوى هي توفير أمان محكم. لقد أحطنا واجهة برمجة تطبيقات `ShadowDom` بخصائص أمنية متقدمة لجعلها آمنة للاستخدام عند عرض معلومات حساسة.

تفضّل بزيارة [الأمان](#Security) لمعرفة المزيد عن هذا الجهد.

### DX

نسعى إلى توفير تجربة مطوّر سلسة. ولتحقيق ذلك، سنعمل على:

1. دعم أكبر عدد ممكن من الأطر الشائعة (React وAngular وغيرها)؛
2. جعل واجهة برمجة التطبيقات سهلة وبسيطة الاستخدام.

### وضع القراءة فقط

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

يعود السبب إلى أن دعم وضع الكتابة سيتطلب تنفيذ DOM معزول مستعصٍ، وهو ما يقدّم عدة تعقيدات أمنية لسنا مستعدين لمواجهتها في هذه المرحلة، مثل:

1. أمن Event listeners - منع الكود الخارجي من اعتراض الإدخال الموجّه إلى العقد الداخلية لـ LavaDome.
2. أمن Overlay - منع الكود الخبيث من وضع طبقة DOM تصيّد فوق **`LavaDome`** لحمل المستخدم على تقديم إدخال حساس إلى جهة خاطئة.

## التصميم

التعقيد التصميمي لهذا المشروع ليس عاليًا. غير أن تلبية المتطلبات مجتمعة للمبادئ الأمنية التي ينفّذها يُعدّ مهمة غير تافهة (انظر [الأمان](#Security)).

يتكوّن **`LavaDome`** من الحزم التالية:

### [Core](https://github.com/lavamoat/lavadome/blob/HEAD/packages/core)

تنفّذ طبقة واجهة برمجة التطبيقات الأساسية التي تتوسط التواصل بين المستهلك والمكوّن المعزول المحمي. تهدف واجهة برمجة التطبيقات إلى السماح بأكبر قدر ممكن من التلاعب الخارجي بالمكوّن المعزول دون إتاحة عُقد DOM الفعلية من داخله لأي شخص - ولا حتى لمستهلك LavaDome - للحفاظ على أعلى مستوى أمني ممكن.

بالإضافة إلى ذلك، تتحمل مسؤولية تنفيذ جميع عمليات التحصين الأمني اللازمة لجعل استخدام ميزة `ShadowDom` آمنًا حقًا، على عكس طبيعته الأصلية كونه ليس ميزة أمنية افتراضيًا (انظر [الأمان](#Security)).

> تذكّر: لا يجوز استخدام الحزمة الأساسية في بيئات الإنتاج!

### [JavaScript](https://github.com/lavamoat/lavadome/blob/HEAD/packages/javascript) / [React](https://github.com/lavamoat/lavadome/blob/HEAD/packages/react) / إلخ

تُصدِّر وظائف للمطوّرين لاستهلاك **`LavaDome`** بالطريقة التي يفضّلونها، سواء عبر JavaScript أو كمكوّن React (أو أي منصة أخرى - [اسأل!](https://github.com/lavamoat/lavadome/issues/new?title=**`LavaDome`**+misses+support+for+...))
> ملاحظة: تقديم دعم **`LavaDome`** لأطر العمل يتضمن دمج كود من جهات خارجية لا نتحكم فيها، مما يسبب "بقعًا أمنية عمياء".

> يُرجى قراءة قسم [الأمان](#Security) لمعرفة كيفية البقاء في أقصى درجات الأمان عند استخدام **`LavaDome`** مع أطر عمل من جهات خارجية.

## الأمان

إذا كنت تخطط لاستخدام **`LavaDome`** في مشروع، فإليك الجوانب الأمنية التي يجب أن تكون على دراية بها:

### `ShadowDom` مقابل `iframe`

مرة أخرى، ما زال هذا مشروعًا تجريبيًا، لكننا فكرنا كثيرًا في هذا القرار. البديل الطبيعي لاستخدام `ShadowDom` هو الاستفادة من `iframe`s عبر الأصول المختلفة. اختراق `iframe` عبر الأصول المختلفة أمر مستحيل، وهو معترف به كآلية بالغة الأهمية أمنيًا في مواصفات W3C. وهذا يعني أنه إذا حدث اختراق بطريقة ما، فإنه يُعامل كثغرة أمنية ويُصلح بشكل عاجل من قبل موردي المتصفحات.

لكن الجانب السلبي لهذا النهج هو أن دمج حل قائم على iframe أصعب بكثير، من حيث UI/UX/DX، خاصةً كأداة تهدف إلى التبني الواسع.

يحتاج **`LavaDome`** إلى توفير تجربة مطوّر سلسة وطبيعية مع تسهيل التكامل الآمن لعُقد shadow DOM المعزولة داخل شجرة DOM المضيفة، و`ShadowDom` هي واجهة برمجة تطبيقات موجّهة نحو DOM صُممت بدقة لهذا الغرض. وهذا ما جعلها أكثر ملاءمة لأهدافنا.

في حين أن واجهة برمجة تطبيقات `ShadowDom` ليست معتمدة رسميًا كأداة أمنية من قبل منشئيها، فإن تنفيذها آمن للغاية، ولا تسرّب أي معلومات معزولة من داخل شجرة shadow DOM إلا في سيناريوهات محددة جدًا.

نعتقد أنه من خلال معالجة تلك السيناريوهات تحديدًا بعناية، يمكن تعزيز `ShadowDom` ليصبح واجهة برمجة تطبيقات آمنة لتغليف DOM (الأمر يستحق المحاولة).

### التهديدات

من المهم معالجة التهديدات الأمنية الحالية المرتبطة بحل قائم على `ShadowDom` مثل `LavaDome`.

#### 1. الحقن

قد يزوّد المطوّرون **`LavaDome`** بمحتوى HTML/JS/CSS يمكنه، عند تحميله، تسريب عُقد DOM من داخل `ShadowDom` عن طريق الخطأ أو عن قصد، على سبيل المثال عبر إضافة كود JavaScript ديناميكيًا في وقت التشغيل.

اقرأ [@arxenix](https://github.com/arxenix) [بحثه](https://blog.ankursundara.com/shadow-dom/#contenteditable-or-css-injection) لمعرفة المزيد عن هذه التقنية.

لمنع هذا الاحتمال، لا يقبل **`LavaDome`** عُقد DOM إطلاقًا داخل شجرة shadow DOM، ولا يدعم سوى تغليف نص عادي. هذا يتيح لنا تجنب التعامل مع المشكلات الأمنية الكامنة في الوثوق بمحتوى HTML/JS/CSS المقدَّم من المستخدم.

نود إعادة النظر في هذا القرار مستقبلًا بينما نبحث عن وسيلة مستقرة وآمنة لدعم إدخال عُقد DOM والأشجار الفرعية.

#### 2. القابلية للاكتشاف

تتيح واجهة برمجة تطبيقات [find()](https://developer.mozilla.org/en-US/docs/Web/API/Window/find) للمطوّرين العثور على عُقد DOM واستخراجها عن طريق البحث عن النص الذي تحتويه. هذه هي واجهة برمجة التطبيقات الوحيدة المعروفة حتى الآن التي نجحت في تسريب عُقد DOM من داخل `ShadowDom`.

<details>
<summary>
    في Firefox، بعد العثور على النص، يمكن للمرء استخدام واجهة برمجة تطبيقات <code>getSelection()</code> لتسريب عُقد DOM من داخل `ShadowDom`، مما يخرق الفكرة بأكملها: <i>(انقر للتوسيع)</i>
</summary>```js
// defender
const secret = 'AN UNPREDICTABLE SECRET';
const opts = { mode:'closed' };
const root = document.body.firstElementChild.firstElementChild;
const p = document.createElement('p');
const shadow = root.attachShadow(opts);
shadow.append(p);
p.innerText = 'Secret is: ' + secret;

// attacker
setTimeout(() => {
    find('Secret is:'); // assuming the Shadow includes predictable text
    console.log('stolen secret: ', getSelection().anchorNode.textContent);
});