### [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>

다음은 `LavaDome` 기반 구성 요소를 테스트하는 데 도움이 되는 `LavaDomeDebug`가 내보내는 몇 가지 디버깅 유틸 메서드입니다:

#### `getTextByRoot()`

`LavaDome`이 연결된 루트(root)가 주어지면 `getTextByRoot()`는 내부 비밀(secret)을 재귀적으로 추출하여 재구성합니다. 이를 허용하려면 `LavaDome` 인스턴스가 원래 UNSAFE 옵션 `@unsafeOpenModeShadow`로 초기화되어 있어야 합니다. 이 옵션은 `LavaDome`의 내부 섀도우를 외부에서 접근 가능하게 만듭니다.

당연히 이는 UNSAFE하며 `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) 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/)**는 사용자 및 신뢰할 수 있는 코드와의 상호작용만 허용하면서 앱의 신뢰할 수 없는 JavaScript 및 CSS 코드의 접근 시도를 차단하는 프런트엔드 전용 구성 요소를 구현하기 위한 **LavaMoat 도구 모음의 보안 도구**입니다.

> [@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/main/packages/core)

소비자와 보호된 격리 구성 요소 간의 통신을 중재하는 기본 API 레이어를 구현합니다. API는 가능한 한 높은 보안 수준을 유지하기 위해 격리 구성 요소 내부의 실제 DOM 노드를 누구에게도 제공하지 않으면서(심지어 LavaDome의 소비자에게도) 외부 조작을 최대한 허용하는 것을 목표로 합니다.

또한, 기본적으로 보안 기능이 아닌 `ShadowDom`의 본래 특성과 대조적으로, `ShadowDom` 기능 사용이 진정으로 안전하도록 필요한 모든 보안 강화를 구현할 책임을 집니다 ([보안](#Security) 참조).

> 기억하세요: 코어 패키지는 프로덕션 용도로 사용해서는 안 됩니다!

### [JavaScript](https://github.com/lavamoat/lavadome/blob/main/packages/javascript) / [React](https://github.com/lavamoat/lavadome/blob/main/packages/react) / etc

개발자가 JavaScript 또는 React 컴포넌트(또는 기타 다른 플랫폼 - [언제든 문의하세요!](https://github.com/lavamoat/lavadome/issues/new?title=**`LavaDome`**+misses+support+for+...))를 통해 선호하는 방식으로 **`LavaDome`**을 사용할 수 있도록 기능을 내보냅니다.

> 참고: **`LavaDome`**의 프레임워크 지원을 제공하려면 우리가 통제할 수 없는 타사 코드가 통합되며, 이로 인해 "보안 사각지대"가 발생합니다.

> 타사 프레임워크와 함께 **`LavaDome`**을 사용할 때 최대한 안전하게 유지하는 방법을 알아보려면 [보안](#Security) 섹션을 읽어주세요.

## 보안

프로젝트에 **`LavaDome`**을 사용할 계획이라면, 알아두어야 할 보안 측면은 다음과 같습니다:

### `ShadowDom` vs `iframe`

다시 말하지만, 이 프로젝트는 아직 실험적이지만, 우리는 이 결정에 대해 많은 고민을 했습니다. `ShadowDom`을 사용하는 것의 자연스러운 대안은 교차 출처 `iframe`들을 활용하는 것입니다. 교차 출처 `iframe`을 침투하는 것은 불가능하며, W3C 사양에 의해 보안에 중요한 메커니즘으로 인정받고 있습니다. 즉, 만약 침해가 어떻게든 발생한다면 보안 취약점으로 취급되어 브라우저 공급업체가 긴급하게 수정합니다.

그러나 이 접근 방식의 단점은 iframe 기반 솔루션을 통합하는 것이 UI/UX/DX 측면에서 훨씬 더 어렵다는 점입니다, 특히 대규모 채택을 목표로 하는 도구로서는 더욱 그렇습니다.

**`LavaDome`**은 호스트 DOM 트리 내에서 캡슐화된 섀도 DOM 노드의 안전한 통합을 촉진하면서 원활하고 자연스러운 개발자 경험을 제공해야 하며, `ShadowDom`은 정확히 그 목적을 위해 만들어진 DOM 지향 API입니다. 이로 인해 `ShadowDom`이 우리의 목표에 더 적합했습니다.

`ShadowDom` API는 제작자에 의해 공식적으로 보안 도구로 승인되지는 않았지만, 그 구현은 매우 안전하며 매우 특정한 시나리오를 제외하고는 섀도 DOM 트리 내부에서 캡슐화된 정보를 유출하지 않습니다.

우리는 바로 그러한 시나리오를 신중하게 해결함으로써 `ShadowDom`이 안전한 DOM 캡슐화 API로 강화될 수 있다고 믿습니다 (시도해 볼 가치가 있습니다).

### 위협

`LavaDome`과 같은 `ShadowDom` 기반 솔루션에 존재하는 현재의 보안 위협을 해결하는 것이 중요합니다.

#### 1. 주입

개발자는 **`LavaDome`**에 HTML/JS/CSS 콘텐츠를 제공할 수 있으며, 로드될 때 예를 들어 런타임에 JavaScript 코드를 동적으로 추가하여 실수로 또는 의도적으로 `ShadowDom` 내부의 DOM 노드를 유출할 수 있습니다.

이 기술에 대해 자세히 알아보려면 [@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 노드를 찾고 추출할 수 있습니다. 이것은 지금까지 `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);
});