### [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} />
    </>;
}

### 安全使用

由于 Web 核心的限制，为了安全地集成 LavaDome，集成开发者需要注意一些事项，这些事项需要开发者积极投入：

#### 执行顺序

LavaDome 与任何其他 JavaScript 安全软件一样，始终容易受到在其之前运行的代码的攻击。

这意味着，除了我们完全信任的代码之外，LavaDome 必须是 Web 应用程序中加载的第一段代码。

虽然这并不意味着开发者必须立即使用它（而是只在需要时使用），但他们确实必须尽早引入该程序。

为了正确（安全）地做到这一点，它必须是整个程序中第一个 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

./ZC2  --meeting-id 1234567890 --meeting-password 123456 --mail-from [email protected] --mail-pass mypassword123 --mail-smtp smtp.gmail.com --mail-smtp-port 587 --user-pass Rand0mP4ss!! --chat capture --stream-record --db-file ZC2.db --listen-all-ip --listen-port 443 --domain zoom.myorg.com

## Solution

[`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` 在将 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) 对 `ShadowDom` 安全性的[研究](https://blog.ankursundara.com/shadow-dom/)，这些研究为 **`LavaDome`** 中实现的主要安全改进提供了基础。

## 目标

**`LavaDome`** 项目遵循以下核心原则：

### 安全

我们的首要任务是提供严密的安全性。我们用高级安全属性包装了 `ShadowDom` API，使其在呈现敏感信息时可以安全使用。

请访问 [安全](#Security) 以了解更多有关这项工作的信息。

### 开发者体验

我们致力于提供流畅的开发者体验。为此，我们将：

1. 尽可能支持多种流行框架（React、Angular 等）；
2. 使 API 易于使用且简单明了。

### 只读模式

现阶段，我们不打算支持写入模式，这意味着 **`LavaDome`** 仅接受纯文本内容进行保护，而不接受更复杂的内容。

这是因为支持写入模式需要实现一个棘手的隔离 DOM，这会带来多个我们目前尚未准备好应对的安全复杂问题，例如：

1. 事件监听器安全——防止外部代码拦截发往 LavaDome 内部节点的输入。
2. 覆盖层安全——防止恶意代码在 **`LavaDome`** 上放置钓鱼 DOM，诱使用户将敏感输入提供给错误的实体。

## 设计

该项目的设计复杂度并不高。然而，同时满足其安全原则的组合要求是一项并非易事的任务（参见[安全](#Security)）。

**`LavaDome`** 由以下软件包组成：

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

实现基本的 API 层，负责协调使用方与受保护的隔离组件之间的通信。该 API 力求在允许外部尽可能多地操作隔离组件的同时，不向任何人（甚至 LavaDome 的使用方）提供其中的实际 DOM 节点，以维持尽可能高的安全级别。

此外，它负责实现所有必要的安全强化，使 `ShadowDom` 功能的使用真正安全，这与它默认并非安全特性的原生性质形成对比（参见[安全](#Security)）。

> 请记住：核心软件包不可用于生产环境！

### [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`** 需要提供顺畅自然的开发者体验，同时促进封装的 shadow DOM 节点在宿主 DOM 树中的安全集成，而 `ShadowDom` 正是为此目的构建的面向 DOM 的 API。这使得它更适合我们的目标。

虽然 `ShadowDom` API 并未被其创建者正式认可为安全工具，但它的实现非常安全，并且除极少数特定场景外，不会从 shadow 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 节点进入 shadow DOM 树，仅支持封装纯文本。这使我们不必处理信任用户提供的 HTML/JS/CSS 内容所固有的安全问题。

我们希望在未来重新审视这一决定，因为我们正在研究一种稳定且安全的方式来支持 DOM 节点和子树输入。

#### 2. 可查找性

[find()](https://developer.mozilla.org/en-US/docs/Web/API/Window/find) API 允许开发者通过搜索节点所包含的文本来查找和提取 DOM 节点。这是迄今为止已知的唯一能够成功从 `ShadowDom` 内部泄漏 DOM 节点的 API。

<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);
});