### [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` export करता है और जो `LavaDome` आधारित घटकों के परीक्षण में आपकी सहायता कर सकती हैं:

#### `getTextByRoot()`

किसी `LavaDome` संलग्न root को देखते हुए, `getTextByRoot()` आंतरिक secret को recursively निकालकर पुनर्निर्मित करेगा। ऐसा करने में सक्षम होने के लिए, `LavaDome` instance को मूल रूप से असुरक्षित विकल्प `@unsafeOpenModeShadow` के साथ प्रारंभ किया जाना चाहिए, जो `LavaDome` के आंतरिक shadows को बाहर से accessible बनाता है।

स्वाभाविक रूप से, यह असुरक्षित है और `LavaDome` को पूरी तरह असुरक्षित छोड़ देता है, लेकिन केवल परीक्षण/डिबगिंग उद्देश्यों के लिए उपयोग करना उचित है - सुनिश्चित करें कि इस विकल्प को production में कभी सक्षम न करें!```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) Web API हमें 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` पृष्ठ पर कहीं और चल रहे JavaScript और CSS से DOM सबट्री को अलग करने के लिए अच्छी तरह काम करता है।

**`LavaDome`** का मूल दृष्टिकोण `ShadowDom` का लाभ उठाना है, साथ ही इसकी [संभावित सुरक्षा कमियों](https://blog.ankursundara.com/shadow-dom/) को ध्यानपूर्वक संबोधित करना है।

**[LavaDome](https://github.com/lavamoat/lavadome/)** को **LavaMoat टूलबॉक्स में एक सुरक्षा उपकरण** के रूप में डिज़ाइन किया गया है, जो केवल फ्रंटएंड-केवल घटकों को लागू करने के लिए है जो विशेष रूप से उपयोगकर्ता और विश्वसनीय कोड के साथ इंटरैक्शन की अनुमति देते हैं, साथ ही ऐप में अविश्वसनीय JavaScript और CSS कोड द्वारा एक्सेस प्रयासों को अवरुद्ध करते हैं।

> [@arxenix](https://github.com/arxenix) को उनके `ShadowDom` सुरक्षा पर [शोध](https://blog.ankursundara.com/shadow-dom/) के लिए शाउट-आउट, जिसने **`LavaDome`** में लागू प्रमुख सुरक्षा सुधारों का आधार प्रदान किया।

## लक्ष्य

**`LavaDome`** परियोजना निम्नलिखित मूल सिद्धांतों का पालन करती है:

### सुरक्षित

हमारी सर्वोच्च प्राथमिकता अभेद्य सुरक्षा प्रदान करना है। हमने `ShadowDom` API को उन्नत सुरक्षा गुणों से लपेटा है ताकि संवेदनशील जानकारी प्रस्तुत करते समय इसका उपयोग सुरक्षित रहे।

इस प्रयास के बारे में अधिक जानने के लिए [सुरक्षा](#Security) देखें।

### DX

हम एक सुव्यवस्थित डेवलपर अनुभव प्रदान करने का प्रयास करते हैं। इसके लिए, हम:

1. जितना संभव हो उतने लोकप्रिय फ्रेमवर्क (React, Angular, आदि) का समर्थन करेंगे;
2. API को आसान और सरल बनाएंगे।

### केवल पढ़ने-योग्य मोड

इस चरण में, हम राइट-मोड का समर्थन करने की योजना नहीं बनाते हैं, जिसका अर्थ है **`LavaDome`** केवल सुरक्षा के लिए सादा टेक्स्ट सामग्री स्वीकार करेगा, और इससे अधिक जटिल कुछ भी नहीं।

ऐसा इसलिए है क्योंकि राइट-मोड का समर्थन करने के लिए एक दुर्गम पृथक DOM लागू करने की आवश्यकता होगी, जो कई सुरक्षा जटिलताओं को पेश करता है जिनका सामना करने के लिए हम अभी तक तैयार नहीं हैं, जैसे:

1. इवेंट लिसनर सुरक्षा - बाहरी कोड को LavaDome आंतरिक नोड्स के लिए निर्धारित इनपुट को इंटरसेप्ट करने से रोकें।
2. ओवरले सुरक्षा - दुर्भावनापूर्ण कोड को **`LavaDome`** पर फ़िशिंग DOM रखने से रोकें, जिससे उपयोगकर्ता संवेदनशील इनपुट गलत इकाई को सौंप दे।

## डिज़ाइन

इस परियोजना की डिज़ाइन जटिलता अधिक नहीं है। हालाँकि, इसके द्वारा लागू सुरक्षा सिद्धांतों की संयुक्त आवश्यकताओं को पूरा करना एक आसान काम नहीं है ([सुरक्षा](#Security) देखें)।

**`LavaDome`** में निम्नलिखित पैकेज शामिल हैं:

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

उपभोक्ता और संरक्षित पृथक घटक के बीच संचार को मध्यस्थ करने वाली मूल API परत लागू करता है। API का लक्ष्य पृथक घटक के जितना संभव हो उतना बाहरी हेरफेर की अनुमति देना है, बिना उसके भीतर से किसी को भी वास्तविक 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`** को एक सहज और स्वाभाविक डेवलपर अनुभव प्रदान करना होगा, साथ ही होस्ट DOM ट्री के भीतर एनकैप्सुलेटेड शैडो DOM नोड्स के सुरक्षित एकीकरण को सुविधाजनक बनाना होगा, और `ShadowDom` एक DOM-उन्मुख API है जो ठीक इसी उद्देश्य के लिए बनाया गया है। इसने इसे हमारे लक्ष्यों के लिए अधिक उपयुक्त बना दिया।

हालाँकि `ShadowDom` API को इसके निर्माताओं द्वारा आधिकारिक रूप से एक सुरक्षा उपकरण के रूप में समर्थित नहीं किया गया है, इसका कार्यान्वयन अत्यधिक सुरक्षित है, और यह शैडो DOM ट्री के भीतर से कोई भी एनकैप्सुलेटेड जानकारी लीक नहीं करता है, सिवाय बहुत विशिष्ट परिदृश्यों के।

हम मानते हैं कि उन्हीं विशिष्ट परिदृश्यों को ध्यानपूर्वक संबोधित करके, `ShadowDom` को एक सुरक्षित DOM एनकैप्सुलेशन API में उन्नत किया जा सकता है (एक कोशिश के लायक)।

### खतरे

`LavaDome` जैसे `ShadowDom`-आधारित समाधान के साथ मौजूद वर्तमान सुरक्षा खतरों को संबोधित करना महत्वपूर्ण है।

#### 1. इंजेक्शन

डेवलपर्स **`LavaDome`** को HTML/JS/CSS सामग्री प्रदान कर सकते हैं जो लोड होने पर, गलती से या जानबूझकर `ShadowDom` के भीतर से DOM नोड्स को लीक कर सकती है, उदाहरण के लिए रनटाइम पर गतिशील रूप से JavaScript कोड जोड़कर।

इस तकनीक के बारे में अधिक जानने के लिए [@arxenix](https://github.com/arxenix) का [शोध](https://blog.ankursundara.com/shadow-dom/#contenteditable-or-css-injection) पढ़ें।

इस संभावना को रोकने के लिए, **`LavaDome`** शैडो DOM ट्री में DOM नोड्स को बिल्कुल भी स्वीकार नहीं करता है, और केवल सादा टेक्स्ट एनकैप्सुलेट करने का समर्थन करता है। यह हमें उपयोगकर्ता-आपूर्ति की गई HTML/JS/CSS सामग्री पर भरोसा करने में निहित सुरक्षा मुद्दों से निपटने से बचाता है।

हम भविष्य में इस निर्णय पर फिर से विचार करना पसंद करेंगे, क्योंकि हम DOM नोड और सबट्री इनपुट का समर्थन करने के लिए एक स्थिर और सुरक्षित साधन पर शोध कर रहे हैं।

#### 2. खोजनीयता

[find()](https://developer.mozilla.org/en-US/docs/Web/API/Window/find) API डेवलपर्स को उनमें मौजूद टेक्स्ट की खोज करके DOM नोड्स को खोजने और निकालने की अनुमति देता है। यह एकमात्र API है जो अब तक एक `ShadowDom` के भीतर से DOM नोड्स को सफलतापूर्वक लीक करने के लिए जाना जाता है।

<details>
<summary>
    Firefox में, टेक्स्ट खोजने के बाद, कोई व्यक्ति <code>getSelection()</code> API का उपयोग करके `ShadowDom` के भीतर से DOM नोड्स लीक कर सकता है, इस प्रकार पूरे विचार से समझौता कर सकता है: <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);
});