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

### Uso Seguro

Devido às limitações do núcleo web, para integrar o LavaDome com segurança, há algumas coisas a serem consideradas que exigem algum esforço ativo por parte do desenvolvedor que realiza a integração:

#### Ordem de Execução

O LavaDome, como qualquer outro software de segurança JavaScript, está sempre vulnerável a código que é executado antes dele.

Isso significa que, exceto para código em que confiamos absolutamente, o LavaDome deve ser o primeiro pedaço de código a carregar no programa da aplicação web.

Embora isso não signifique que o desenvolvedor deva usá-lo imediatamente (mas sim apenas quando necessário), ele deve, no entanto, incluir o programa o mais cedo possível.

Para fazer isso corretamente (com segurança), ele deve ser a primeira declaração de import/require em todo o programa:```javascript
import '@lavamoat/lavadome-react';
import 'other-stuff';

console.log('Program starts here');

e não deve ser:```html
<span> <lavadome>your key is 234789</lavadome> </span>

Aqui estão alguns dos métodos utilitários de depuração que `LavaDomeDebug` exporta e que podem ajudar você a testar componentes baseados em `LavaDome`:

#### `getTextByRoot()`

Dado um root (`raiz`) anexado a um `LavaDome`, `getTextByRoot()` extrairá e reconstruirá recursivamente o segredo interno. Para que isso seja possível, a instância de `LavaDome` deve ser iniciada originalmente com a opção INSEGURA `@unsafeOpenModeShadow`, que torna as sombras internas de `LavaDome` acessíveis a partir de fora.

Naturalmente, isso é INSEGURO e deixa `LavaDome` totalmente vulnerável, mas faz sentido usar apenas para fins de teste/depuração - certifique-se de nunca habilitar essa opção em produção!```javascript
new LavaDomeJavaScript(root, {
    unsafeOpenModeShadow: isThisTestingEnv, // boolean
}).text('123456');
LavaDomeDebug.getTextByRoot(root) === '123456'; // true

## Desenvolvimento

Para configurar uma compilação de desenvolvimento local do **`LavaDome`**, clone este repositório e execute um dos seguintes comandos:```bash
npm install && npm install --global serve

## Solução

A [`ShadowDom`](https://web.dev/articles/`ShadowDom`-v1) Web API nos permite isolar e encapsular nós do DOM. Embora ela [não tenha sido projetada como um recurso de segurança](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.), o `ShadowDom` funciona bem para isolar subárvores do DOM de JavaScript e CSS que estejam sendo executados em outras partes da página.

A abordagem básica do **`LavaDome`** é aproveitar o `ShadowDom`, ao mesmo tempo em que aborda cuidadosamente suas [possíveis lacunas de segurança](https://blog.ankursundara.com/shadow-dom/).

O **[LavaDome](https://github.com/lavamoat/lavadome/)** tem a intenção de ser uma **ferramenta de segurança na caixa de ferramentas do LavaMoat** para implementar componentes exclusivamente de frontend que permitam somente interações com o usuário e código confiável, bloqueando tentativas de acesso por código JavaScript e CSS não confiável no aplicativo.

> Um agradecimento especial ao [@arxenix](https://github.com/arxenix) pela [pesquisa](https://blog.ankursundara.com/shadow-dom/) sobre segurança do `ShadowDom`, que serviu de base para as principais melhorias de segurança implementadas no **`LavaDome`**.

## Objetivos

O projeto **`LavaDome`** segue os seguintes princípios fundamentais:

### Segurança

Nossa prioridade máxima é fornecer segurança hermética. Envolvemos a API `ShadowDom` com propriedades de segurança avançadas para torná-la segura ao apresentar informações sensíveis.

Visite [Segurança](#Security) para saber mais sobre esse esforço.

### DX

Nós nos esforçamos para proporcionar uma experiência de desenvolvimento simplificada. Para isso, vamos:

1. Suportar o maior número possível de frameworks populares (React, Angular, etc.);
2. Tornar a API fácil e simples de usar.

### Somente leitura

Nesta fase, não planejamos suportar o modo de escrita, ou seja, o **`LavaDome`** aceitará apenas conteúdo em texto simples para proteção, e nada mais complexo do que isso.

Isso porque suportar o modo de escrita exigirá a implementação de um DOM isolado intratável, o que introduz múltiplas complicações de segurança que ainda não estamos prontos para enfrentar neste momento, tais como:

1. Segurança dos listeners de eventos — impedir que códigos externos interceptem entradas destinadas aos nós internos do LavaDome.
2. Segurança de sobreposição — impedir que códigos maliciosos coloquem um DOM de phishing sobre o **`LavaDome`** para fazer o usuário fornecer informações sensíveis à entidade errada.

## Design

A complexidade de design deste projeto não é alta. No entanto, satisfazer os requisitos combinados dos princípios de segurança que ele implementa é uma tarefa não trivial (veja [Segurança](#Security)).

O **`LavaDome`** consiste nos seguintes pacotes:

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

Implementa a camada básica da API que medeia a comunicação entre o consumidor e o componente isolado protegido. A API busca permitir o máximo de manipulação externa do componente isolado possível, sem fornecer a ninguém os nós reais do DOM internos a ele — nem mesmo ao consumidor do LavaDome — para manter o mais alto nível de segurança possível.

Além disso, assume a responsabilidade de implementar todo o endurecimento de segurança necessário para tornar o uso do recurso `ShadowDom` verdadeiramente seguro, em contraste com sua natureza nativa de não ser um recurso de segurança por padrão (veja [Segurança](#Security)).

> Lembre-se: o pacote core não deve ser usado em produção!

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

Exportam funcionalidades para que desenvolvedores consumam o **`LavaDome`** da forma que preferirem, seja por JavaScript ou como um componente React (ou qualquer outra plataforma — [pergunte à vontade!](https://github.com/lavamoat/lavadome/issues/new?title=**`LavaDome`**+misses+support+for+...))
> NOTA: Fornecer suporte do **`LavaDome`** para frameworks integra código de terceiros que não controlamos, o que gera "pontos cegos de segurança".

> Por favor, leia a seção [Segurança](#Security) para saber como permanecer o mais seguro possível ao usar o **`LavaDome`** com frameworks de terceiros.

## Segurança

Se você planeja usar o **`LavaDome`** em um projeto, estes são os aspectos de segurança dos quais deve estar ciente:

### `ShadowDom` vs `iframe`

Novamente, este ainda é um projeto experimental, mas pensamos bastante nessa decisão. Uma alternativa natural ao uso do `ShadowDom` é aproveitar `iframe`s de origem cruzada. Infiltrar um `iframe` de origem cruzada é impossível, e ele é reconhecido como um mecanismo crítico de segurança pela especificação da W3C. Isso significa que, se uma violação acontecer de alguma forma, ela é tratada como uma vulnerabilidade de segurança e corrigida com urgência pelos fornecedores de navegadores.

A desvantagem dessa abordagem, no entanto, é que integrar uma solução baseada em iframe é significativamente mais difícil, em termos de UI/UX/DX, especialmente para uma ferramenta que busca adoção em massa.

O **`LavaDome`** precisa oferecer uma experiência de desenvolvedor fluida e natural, ao mesmo tempo em que facilita a integração segura de nós de shadow DOM encapsulados dentro da árvore DOM hospedeira, e o `ShadowDom` é uma API orientada ao DOM criada exatamente para esse propósito. Isso o tornou mais adequado aos nossos objetivos.

Embora a API `ShadowDom` não seja oficialmente endossada como uma ferramenta de segurança por seus criadores, sua implementação é altamente segura e não vaza nenhuma informação encapsulada de dentro da árvore de shadow DOM, exceto em cenários muito específicos.

Acreditamos que, ao abordar cuidadosamente exatamente esses cenários, o `ShadowDom` pode ser aprimorado para se tornar uma API segura de encapsulamento de DOM (vale a pena tentar).

### Ameaças

É importante abordar as ameaças de segurança atuais que existem em soluções baseadas em `ShadowDom`, como o `LavaDome`.

#### 1. Injeção

Os desenvolvedores podem fornecer ao **`LavaDome`** conteúdo HTML/JS/CSS que, quando carregado, pode vazar acidental ou intencionalmente nós do DOM de dentro do `ShadowDom`, por exemplo, adicionando código JavaScript dinamicamente em tempo de execução.

Leia a [pesquisa](https://blog.ankursundara.com/shadow-dom/#contenteditable-or-css-injection) do [@arxenix](https://github.com/arxenix) para saber mais sobre essa técnica.

Para evitar essa possibilidade, o **`LavaDome`** não aceita absolutamente nenhum nó do DOM na árvore de shadow DOM e suporta apenas encapsular texto simples. Isso nos permite evitar ter de lidar com os problemas de segurança inerentes à confiança em conteúdo HTML/JS/CSS fornecido pelo usuário.

Adoraríamos rever essa decisão no futuro, enquanto pesquisamos uma forma estável e segura de suportar entrada de nós do DOM e subárvores.

#### 2. Encontrabilidade

A API [find()](https://developer.mozilla.org/en-US/docs/Web/API/Window/find) permite que desenvolvedores encontrem e extraiam nós do DOM pesquisando pelo texto que eles contêm. Esta é a única API conhecida até agora que vaza com sucesso nós do DOM de dentro de um `ShadowDom`.

<details>
<summary>
    No Firefox, após encontrar o texto, pode-se usar a API <code>getSelection()</code> para vazar nós do DOM de dentro do `ShadowDom`, comprometendo assim toda a ideia: <i>(clique para expandir)</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);
});