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

### Utilisation sûre

En raison des limitations du noyau web, afin d'intégrer LavaDome de manière sécurisée, quelques éléments doivent être pris en compte qui exigent un effort actif de la part du développeur intégrateur :

#### Ordre d'exécution

LavaDome, comme tout autre logiciel de sécurité JavaScript, est toujours vulnérable au code qui s'exécute avant lui.

Cela signifie qu'à l'exception du code auquel nous faisons entièrement confiance, LavaDome doit être le premier morceau de code à charger dans le programme de l'application web.

Bien que cela ne signifie pas que le développeur doive l'utiliser immédiatement (mais plutôt seulement lorsqu'il en a besoin), il doit cependant inclure le programme dès que possible.

Pour ce faire correctement (en toute sécurité), il doit être la première déclaration import/require de tout le programme :```javascript
import '@lavamoat/lavadome-react';
import 'other-stuff';

console.log('Program starts here');

et ne doit pas être :```html
<span> <lavadome>your key is 234789</lavadome> </span>

Voici quelques-unes des méthodes utilitaires de débogage exportées par `LavaDomeDebug` qui peuvent vous aider à tester les composants basés sur `LavaDome` :

#### `getTextByRoot()`

Étant donné une racine à laquelle `LavaDome` est attaché, `getTextByRoot()` extrait et reconstruit récursivement le secret interne. Pour ce faire, l'instance `LavaDome` doit avoir été initialisée à l'origine avec l'option NON SÛRE `@unsafeOpenModeShadow`, qui rend les ombres internes de `LavaDome` accessibles depuis l'extérieur.

Naturellement, c'est NON SÛR et laisse `LavaDome` entièrement vulnérable, mais cela n'a de sens que pour une utilisation à des fins de test/débogage uniquement - assurez-vous de ne jamais activer cette option en production !```javascript
new LavaDomeJavaScript(root, {
    unsafeOpenModeShadow: isThisTestingEnv, // boolean
}).text('123456');
LavaDomeDebug.getTextByRoot(root) === '123456'; // true

## Développement

Pour configurer une version de développement locale de **`LavaDome`**, clonez ce dépôt et exécutez l'une des commandes suivantes :```bash
npm install && npm install --global serve

## Solution

L'API Web [`ShadowDom`](https://web.dev/articles/`ShadowDom`-v1) nous permet d'isoler et d'encapsuler des nœuds DOM. Bien qu'elle [ne soit pas conçue comme une fonctionnalité de sécurité](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` fonctionne bien pour isoler des sous-arbres DOM du JavaScript et du CSS exécutés ailleurs dans la page.

L'approche de base de **`LavaDome`** consiste à exploiter `ShadowDom`, tout en traitant soigneusement ses [failles de sécurité potentielles](https://blog.ankursundara.com/shadow-dom/).

**[LavaDome](https://github.com/lavamoat/lavadome/)** est conçu pour être un **outil de sécurité dans la boîte à outils LavaMoat** permettant d'implémenter des composants frontend-only qui autorisent exclusivement les interactions avec l'utilisateur et le code de confiance, tout en bloquant les tentatives d'accès par du code JavaScript et CSS non fiable dans l'application.

> Merci à [@arxenix](https://github.com/arxenix) pour ses [recherches](https://blog.ankursundara.com/shadow-dom/) sur la sécurité de `ShadowDom`, qui ont servi de base aux améliorations majeures de sécurité implémentées dans **`LavaDome`**.

## Objectifs

Le projet **`LavaDome`** suit les principes fondamentaux suivants :

### Sécurisé

Notre priorité absolue est de fournir une sécurité infaillible. Nous avons enveloppé l'API `ShadowDom` avec des propriétés de sécurité avancées afin de la rendre sûre pour l'affichage d'informations sensibles.

Consultez [Sécurité](#Security) pour en savoir plus sur cet effort.

### DX (Expérience Développeur)

Nous nous efforçons d'offrir une expérience développeur fluide. À cette fin, nous allons :

1. Prendre en charge autant de frameworks populaires (React, Angular, etc.) que possible ;
2. Rendre l'API facile et simple à utiliser.

### Mode lecture seule

À ce stade, nous ne prévoyons pas de prendre en charge le mode écriture, ce qui signifie que **`LavaDome`** n'acceptera que du contenu en texte brut pour la protection, et rien de plus complexe que cela.

Cela s'explique par le fait que la prise en charge du mode écriture nécessiterait l'implémentation d'un DOM isolé intraitable, ce qui introduit plusieurs complications de sécurité que nous ne sommes pas encore prêts à affronter à ce stade, notamment :

1. Sécurité des écouteurs d'événements - empêcher le code externe d'intercepter les entrées destinées aux nœuds internes de LavaDome.
2. Sécurité de superposition - empêcher le code malveillant de poser un DOM de phishing sur **`LavaDome`** pour amener l'utilisateur à fournir des données sensibles à la mauvaise entité.

## Conception

La complexité de conception de ce projet n'est pas élevée. Cependant, satisfaire aux exigences combinées des principes de sécurité qu'il implémente est une tâche non triviale (voir [Sécurité](#Security)).

**`LavaDome`** se compose des paquets suivants :

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

Implémente la couche API de base qui sert d'intermédiaire entre le consommateur et le composant isolé protégé. L'API vise à permettre autant de manipulations externes du composant isolé que possible sans fournir à quiconque les nœuds DOM réels qui s'y trouvent - pas même au consommateur de LavaDome - afin de maintenir le niveau de sécurité le plus élevé possible.

De plus, il assume la responsabilité d'implémenter tout le durcissement de sécurité nécessaire pour rendre l'utilisation de la fonctionnalité `ShadowDom` réellement sécurisée, contrairement à sa nature native qui n'en fait pas une fonctionnalité de sécurité par défaut (voir [Sécurité](#Security)).

> Rappel : le paquet core ne doit pas être utilisé en production !

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

Exportent des fonctionnalités permettant aux développeurs de consommer **`LavaDome`** comme ils le préfèrent, que ce soit en JavaScript ou comme composant React (ou toute autre plateforme - [demandez !](https://github.com/lavamoat/lavadome/issues/new?title=**`LavaDome`**+misses+support+for+...))
> NOTE : Fournir le support **`LavaDome`** pour les frameworks intègre du code tiers que nous ne contrôlons pas, ce qui crée des « zones de sécurité aveugles ».

> Veuillez lire la section [Sécurité](#Security) pour apprendre comment rester aussi sûr que possible lors de l'utilisation de **`LavaDome`** avec des frameworks tiers.

## Sécurité

Si vous prévoyez d'utiliser **`LavaDome`** pour un projet, voici les aspects de sécurité à connaître :

### `ShadowDom` vs `iframe`

Encore une fois, c'est un projet encore expérimental, mais nous avons réfléchi à cette décision. Une alternative naturelle à l'utilisation du `ShadowDom` est d'exploiter des `iframe` cross-origin. Infiltrer une `iframe` cross-origin est impossible, et ce mécanisme est reconnu comme critique pour la sécurité par la spécification W3C. Cela signifie que si une brèche survenait, elle serait traitée comme une vulnérabilité de sécurité et corrigée en urgence par les fournisseurs de navigateurs.

L'inconvénient de cette approche, cependant, est que l'intégration d'une solution basée sur iframe est significativement plus difficile, en termes d'UI/UX/DX, surtout pour un outil visant une adoption massive.

**`LavaDome`** doit offrir une expérience développeur fluide et naturelle tout en facilitant l'intégration sécurisée de nœuds DOM encapsulés dans l'arbre DOM hôte, et `ShadowDom` est une API orientée DOM précisément conçue pour cela. Cela en fait un meilleur choix pour nos objectifs.

Bien que l'API `ShadowDom` ne soit pas officiellement recommandée comme outil de sécurité par ses créateurs, son implémentation est hautement sécurisée et ne laisse fuiter aucune information encapsulée depuis l'arbre du shadow DOM, sauf dans des scénarios très spécifiques.

Nous croyons qu'en traitant soigneusement ces scénarios précis, `ShadowDom` peut être augmenté en une API d'encapsulation DOM sécurisée (ça vaut le coup d'essayer).

### Menaces

Il est important d'aborder les menaces de sécurité actuelles qui existent avec une solution basée sur `ShadowDom` comme `LavaDome`.

#### 1. Injection

Les développeurs pourraient fournir à **`LavaDome`** du contenu HTML/JS/CSS qui, une fois chargé, peut accidentellement ou intentionnellement fuiter des nœuds DOM depuis l'intérieur du `ShadowDom`, par exemple en ajoutant dynamiquement du code JavaScript à l'exécution.

Lisez les [recherches](https://blog.ankursundara.com/shadow-dom/#contenteditable-or-css-injection) de [@arxenix](https://github.com/arxenix) pour en savoir plus sur cette technique.

Pour empêcher cette possibilité, **`LavaDome`** n'accepte aucun nœud DOM dans l'arbre du shadow DOM, et ne prend en charge que l'encapsulation de texte brut. Cela nous évite d'avoir à lutter contre les problèmes de sécurité inhérents à la confiance accordée au contenu HTML/JS/CSS fourni par l'utilisateur.

Nous serions ravis de revisiter cette décision à l'avenir alors que nous étudions un moyen stable et sécurisé de prendre en charge les entrées de nœuds DOM et de sous-arbres.

#### 2. Trouvabilité

L'API [find()](https://developer.mozilla.org/en-US/docs/Web/API/Window/find) permet aux développeurs de trouver et d'extraire des nœuds DOM en recherchant le texte qu'ils contiennent. C'est la seule API connue à ce jour pour fuiter avec succès des nœuds DOM depuis l'intérieur d'un `ShadowDom`.

<details>
<summary>
    Dans Firefox, après avoir trouvé le texte, on peut utiliser l'API <code>getSelection()</code> pour fuiter des nœuds DOM depuis l'intérieur du `ShadowDom`, compromettant ainsi toute l'idée : <i>(cliquer pour agrandir)</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);
});