### [React](https://github.com/lavamoat/lavadome/blob/main/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` полностью уязвимым, однако имеет смысл использовать только в целях тестирования/отладки — обязательно убедитесь, что этот параметр никогда не включён в production!```javascript
new LavaDomeJavaScript(root, {
    unsafeOpenModeShadow: isThisTestingEnv, // boolean
}).text('123456');
LavaDomeDebug.getTextByRoot(root) === '123456'; // true

## Разработка

Чтобы настроить локальную сборочную версию **`LavaDome`**, клонируйте этот репозиторий и выполните одну из следующих команд:```bash
npm install && npm install --global serve

## Решение

Веб-API [`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`** руководствуется следующими основными принципами:

### Безопасность

Наш главный приоритет — обеспечение абсолютной безопасности. Мы дополнили API `ShadowDom` расширенными свойствами безопасности, чтобы сделать его безопасным для использования при отображении конфиденциальной информации.

Посетите раздел [Безопасность](#Security), чтобы узнать больше об этой работе.

### DX

Мы стремимся обеспечить удобство работы разработчиков. Для этого мы планируем:

1. Поддерживать как можно больше популярных фреймворков (React, Angular и т. д.);
2. Сделать API лёгким и простым в использовании.

### Режим только чтения

На данном этапе мы не планируем поддерживать режим записи, то есть **`LavaDome`** будет принимать для защиты только содержимое в виде обычного текста (plaintext) и ничего более сложного.

Это связано с тем, что поддержка режима записи потребует реализации нетривиальной изолированной DOM, что влечёт за собой множество осложнений в области безопасности, к которым мы пока не готовы, например:

1. Безопасность обработчиков событий — предотвращение перехвата внешним кодом ввода, предназначенного для внутренних узлов LavaDome.
2. Безопасность оверлеев — предотвращение наложения вредоносным кодом фишинговой DOM-разметки поверх **`LavaDome`**, чтобы заставить пользователя передавать конфиденциальные данные не тому получателю.

## Проектирование

Сложность проектирования этого проекта невысока. Однако выполнение совокупных требований реализуемых в нём принципов безопасности — нетривиальная задача (см. [Безопасность](#Security)).

**`LavaDome`** состоит из следующих пакетов:

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

Реализует базовый уровень API, который обеспечивает взаимодействие между потребителем и защищённым изолированным компонентом. API стремится допускать как можно больше внешних манипуляций с изолированным компонентом, не предоставляя при этом реальных DOM-узлов изнутри него никому — даже потребителю LavaDome, — чтобы поддерживать максимально возможный уровень безопасности.

Кроме того, на него возлагается реализация всех необходимых мер по усилению безопасности, чтобы использование возможностей `ShadowDom` было по-настоящему безопасным, в отличие от его исходной природы, в которой он по умолчанию не является средством безопасности (см. [Безопасность](#Security)).

> Помните: пакет core не предназначен для использования в производстве!

### [JavaScript](https://github.com/lavamoat/lavadome/blob/main/packages/javascript) / [React](https://github.com/lavamoat/lavadome/blob/main/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`. Проникнуть в кросс-оригинный `iframe` невозможно, и спецификация W3C признаёт его критически важным механизмом безопасности. Это означает, что если взлом всё же происходит, он рассматривается как уязвимость безопасности и срочно устраняется производителями браузеров.

Однако недостаток этого подхода в том, что интеграция решения на основе iframe значительно сложнее с точки зрения UI/UX/DX, особенно для инструмента, ориентированного на массовое внедрение.

**`LavaDome`** должен обеспечивать плавный и естественный опыт разработчика и при этом способствовать безопасной интеграции инкапсулированных узлов теневого DOM в родительское дерево DOM, а `ShadowDom` — это DOM-ориентированный API, созданный именно для этой цели. Это сделало его более подходящим для наших целей.

Хотя создатели `ShadowDom` официально не одобряют его как средство безопасности, его реализация отличается высоким уровнем безопасности и не допускает утечки какой-либо инкапсулированной информации из дерева теневого DOM, за исключением весьма специфических сценариев.

Мы считаем, что, тщательно проработав именно эти сценарии, `ShadowDom` можно усовершенствовать до защищённого API инкапсуляции DOM (попробовать стоит).

### Угрозы

Важно рассмотреть текущие угрозы безопасности, характерные для решений на основе `ShadowDom`, таких как `LavaDome`.

#### 1. Инъекция

Разработчики могут передавать **`LavaDome`** HTML/JS/CSS-содержимое, которое при загрузке может случайно или намеренно привести к утечке DOM-узлов из `ShadowDom`, например за счёт динамического добавления JavaScript-кода во время выполнения.

Прочитайте [исследование](https://blog.ankursundara.com/shadow-dom/#contenteditable-or-css-injection) [@arxenix](https://github.com/arxenix), чтобы узнать больше об этом приёме.

Чтобы исключить такую возможность, **`LavaDome`** вообще не принимает DOM-узлы в дерево теневого DOM и поддерживает инкапсуляцию только обычного текста. Это избавляет нас от необходимости бороться с проблемами безопасности, присущими доверию к пользовательскому HTML/JS/CSS-содержимому.

В будущем мы хотели бы пересмотреть это решение, когда найдём стабильный и безопасный способ поддержки ввода DOM-узлов и поддеревьев.

#### 2. Обнаруживаемость

API [find()](https://developer.mozilla.org/en-US/docs/Web/API/Window/find) позволяет разработчикам находить и извлекать DOM-узлы, выполняя поиск по содержащемуся в них тексту. На данный момент это единственный известный API, которому успешно удаётся извлекать DOM-узлы из `ShadowDom`.

<details>
<summary>
    В Firefox, после того как текст найден, можно использовать API <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);
});