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

### Sichere Verwendung

Aufgrund der Einschränkungen des Webkerns gibt es bei der sicheren Integration von LavaDome einige Punkte zu beachten, die aktive Arbeit des integrierenden Entwicklers erfordern:

#### Ausführungsreihenfolge

LavaDome ist wie jede andere JavaScript-Sicherheitssoftware immer anfällig für Code, der vor ihm ausgeführt wird.

Das bedeutet, dass LavaDome – abgesehen von Code, dem wir absolut vertrauen – das erste Codestück sein muss, das im Webanwendungsprogramm geladen wird.

Das bedeutet zwar nicht, dass der Entwickler es sofort nutzen muss (sondern nur dann, wenn er es benötigt), er muss das Programm jedoch so früh wie möglich einbinden.

Um dies korrekt (sicher) zu tun, muss es die erste import/require-Deklaration im gesamten Programm sein:```javascript
import '@lavamoat/lavadome-react';
import 'other-stuff';

console.log('Program starts here');

und darf nicht sein:```html
<span> <lavadome>your key is 234789</lavadome> </span>

Hier sind einige der Debugging-Utility-Methoden, die `LavaDomeDebug` exportiert und die dir beim Testen von Komponenten auf Basis von `LavaDome` helfen können:

#### `getTextByRoot()`

Wenn eine `LavaDome`-Root angehängt ist, extrahiert `getTextByRoot()` rekursiv das innere Geheimnis und rekonstruiert es. Damit das möglich ist, muss die `LavaDome`-Instanz ursprünglich mit der UNSAFE-Option `@unsafeOpenModeShadow` initialisiert worden sein, welche die inneren Schatten von `LavaDome` von außen zugänglich macht.

Natürlich ist das UNSAFE und macht `LavaDome` vollständig verwundbar, ist aber sinnvoll, wenn es nur für Test-/Debugging-Zwecke verwendet wird – stelle sicher, dass diese Option niemals in der Produktion aktiviert wird!```javascript
new LavaDomeJavaScript(root, {
    unsafeOpenModeShadow: isThisTestingEnv, // boolean
}).text('123456');
LavaDomeDebug.getTextByRoot(root) === '123456'; // true

## Entwicklung

Um einen lokalen Entwicklungs-Build von **`LavaDome`** einzurichten, klonen Sie dieses Repo und führen Sie einen der folgenden Befehle aus:```bash
npm install && npm install --global serve

## Lösung

Die [`ShadowDom`](https://web.dev/articles/`ShadowDom`-v1) Web-API ermöglicht es uns, DOM-Knoten zu isolieren und zu kapseln. Obwohl sie [nicht als Sicherheitsfunktion konzipiert ist](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.), funktioniert `ShadowDom` gut, um DOM-Teilbäume von JavaScript und CSS zu isolieren, die an anderer Stelle in der Seite ausgeführt werden.

Der grundlegende Ansatz von **`LavaDome`** besteht darin, `ShadowDom` zu nutzen und dabei sorgfältig seine [potenziellen Sicherheitslücken](https://blog.ankursundara.com/shadow-dom/) zu adressieren.

**[LavaDome](https://github.com/lavamoat/lavadome/)** soll ein **Sicherheitswerkzeug im LavaMoat-Werkzeugkasten** sein, um reine Frontend-Komponenten zu implementieren, die ausschließlich Interaktionen mit dem Benutzer und vertrauenswürdigem Code ermöglichen, während Zugriffsversuche durch nicht vertrauenswürdigen JavaScript- und CSS-Code in der App blockiert werden.

> Ein großes Dankeschön an [@arxenix](https://github.com/arxenix) für die [Forschung](https://blog.ankursundara.com/shadow-dom/) zur `ShadowDom`-Sicherheit, die die Grundlage für bedeutende Sicherheitsverbesserungen bildete, die in **`LavaDome`** implementiert wurden.

## Ziele

Das **`LavaDome`**-Projekt folgt den folgenden Kernprinzipien:

### Sicher

Unsere oberste Priorität ist die Gewährleistung einer lückenlosen Sicherheit. Wir haben die `ShadowDom`-API mit erweiterten Sicherheitseigenschaften ausgestattet, um sie bei der Darstellung sensibler Informationen sicher zu machen.

Besuchen Sie [Security](#Security), um mehr über diese Bemühungen zu erfahren.

### DX

Wir bemühen uns, eine optimierte Entwicklererfahrung zu bieten. Zu diesem Zweck werden wir:

1. So viele gängige Frameworks (React, Angular, etc.) wie möglich unterstützen;
2. Die API leicht und einfach zu bedienen machen.

### Nur Lese-Modus

In dieser Phase planen wir nicht, den Schreibmodus zu unterstützen, das bedeutet, **`LavaDome`** wird nur Klartextinhalte zum Schutz akzeptieren und nichts Komplexeres als das.

Das liegt daran, dass die Unterstützung des Schreibmodus die Implementierung eines unbeherrschbaren isolierten DOMs erfordern würde, was mehrere Sicherheitskomplikationen mit sich bringt, die wir zu diesem Zeitpunkt noch nicht in Angriff nehmen können, wie zum Beispiel:

1. Sicherheit von Ereignis-Listenern - verhindern, dass externer Code Eingaben abfängt, die für LavaDome-interne Knoten bestimmt sind.
2. Overlay-Sicherheit - verhindern, dass bösartiger Code ein Phishing-DOM über **`LavaDome`** legt, um den Benutzer dazu zu bringen, sensible Eingaben an die falsche Entität zu übermitteln.

## Design

Die Designkomplexität dieses Projekts ist nicht hoch. Allerdings ist es eine nicht triviale Aufgabe, die kombinierten Anforderungen der umgesetzten Sicherheitsprinzipien zu erfüllen (siehe [Security](#Security)).

**`LavaDome`** besteht aus den folgenden Paketen:

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

Implementiert die grundlegende API-Schicht, die die Kommunikation zwischen dem Konsumenten und der geschützten isolierten Komponente vermittelt. Die API strebt danach, so viel externe Manipulation der isolierten Komponente wie möglich zu ermöglichen, ohne tatsächliche DOM-Knoten aus ihr an irgendjemanden weiterzugeben – nicht einmal an den Konsumenten von LavaDome – um das höchstmögliche Sicherheitsniveau aufrechtzuerhalten.

Darüber hinaus übernimmt es die Verantwortung, alle notwendigen Sicherheitshärtungen zu implementieren, um die Nutzung des `ShadowDom`-Features wirklich sicher zu machen, im Gegensatz zu seiner nativen Beschaffenheit, standardmäßig keine Sicherheitsfunktion zu sein (siehe [Security](#Security)).

> Denken Sie daran: Das Core-Paket ist nicht für Produktionszwecke gedacht!

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

Exportiert Funktionalitäten, mit denen Entwickler **`LavaDome`** so nutzen können, wie sie es bevorzugen, sei es über JavaScript oder als React-Komponente (oder jede andere Plattform – [frag einfach!](https://github.com/lavamoat/lavadome/issues/new?title=**`LavaDome`**+misses+support+for+...))
> HINWEIS: Die Bereitstellung von **`LavaDome`**-Unterstützung für Frameworks integriert Code von Drittanbietern, den wir nicht kontrollieren, was zu „blinden Flecken" in der Sicherheit führt.

> Bitte lesen Sie den Abschnitt [Security](#Security), um zu erfahren, wie Sie bei der Verwendung von **`LavaDome`** mit Drittanbieter-Frameworks so sicher wie möglich bleiben.

## Security

Wenn Sie planen, **`LavaDome`** für ein Projekt zu verwenden, finden Sie hier die Sicherheitsaspekte, die Sie beachten sollten:

### `ShadowDom` vs `iframe`

Wieder einmal ist dies noch ein experimentelles Projekt, aber wir haben uns bei dieser Entscheidung durchaus Gedanken gemacht. Eine natürliche Alternative zur Verwendung des `ShadowDom` ist die Nutzung von Cross-Origin-`iframe`s. Das Eindringen in einen Cross-Origin-`iframe` ist unmöglich, und er wird von der W3C-Spezifikation als sicherheitskritischer Mechanismus anerkannt. Das bedeutet, dass eine Sicherheitsverletzung, falls sie dennoch auftritt, als Sicherheitslücke behandelt und von den Browser-Anbietern umgehend behoben wird.

Der Nachteil dieses Ansatzes ist jedoch, dass die Integration einer iframe-basierten Lösung erheblich schwieriger ist – in Bezug auf UI/UX/DX – insbesondere für ein Tool, das auf Massenadoption abzielt.

**`LavaDome`** muss eine reibungslose und natürliche Entwicklererfahrung bieten und gleichzeitig die sichere Integration gekapselter Shadow-DOM-Knoten in den Host-DOM-Baum ermöglichen, und `ShadowDom` ist eine genau für diesen Zweck entwickelte DOM-orientierte API. Das machte es besser geeignet für unsere Ziele.

Obwohl die `ShadowDom`-API von ihren Entwicklern nicht offiziell als Sicherheitswerkzeug empfohlen wird, ist ihre Implementierung sehr sicher, und sie gibt keine gekapselten Informationen aus dem Shadow-DOM-Baum preis, außer unter ganz bestimmten Szenarien.

Wir glauben, dass `ShadowDom` durch die sorgfältige Behandlung genau dieser Szenarien zu einer gesicherten DOM-Kapselungs-API erweitert werden kann (einen Versuch wert).

### Bedrohungen

Es ist wichtig, die aktuellen Sicherheitsbedrohungen zu adressieren, die bei `ShadowDom`-basierten Lösungen wie `LavaDome` bestehen.

#### 1. Injektion

Entwickler könnten **`LavaDome`** HTML-/JS-/CSS-Inhalte bereitstellen, die beim Laden versehentlich oder absichtlich DOM-Knoten aus dem `ShadowDom` preisgeben – zum Beispiel durch dynamisches Hinzufügen von JavaScript-Code zur Laufzeit.

Lesen Sie die [Forschung](https://blog.ankursundara.com/shadow-dom/#contenteditable-or-css-injection) von [@arxenix](https://github.com/arxenix), um mehr über diese Technik zu erfahren.

Um diese Möglichkeit zu verhindern, akzeptiert **`LavaDome`** überhaupt keine DOM-Knoten im Shadow-DOM-Baum und unterstützt nur das Kapseln von Klartext. Das ermöglicht es uns, uns nicht mit den Sicherheitsproblemen auseinandersetzen zu müssen, die mit dem Vertrauen in benutzerbereitgestellte HTML-/JS-/CSS-Inhalte verbunden sind.

Wir würden diese Entscheidung in Zukunft gerne überdenken, während wir nach einem stabilen und sicheren Mittel suchen, um DOM-Knoten- und Teilbaum-Eingaben zu unterstützen.

#### 2. Auffindbarkeit

Die [find()](https://developer.mozilla.org/en-US/docs/Web/API/Window/find)-API ermöglicht es Entwicklern, DOM-Knoten zu finden und zu extrahieren, indem sie nach dem enthaltenen Text suchen. Dies ist die einzige API, von der bisher bekannt ist, dass sie erfolgreich DOM-Knoten aus einem `ShadowDom` preisgibt.

<details>
<summary>
    In Firefox kann man nach dem Finden des Textes mit der <code>getSelection()</code>-API DOM-Knoten aus dem `ShadowDom` preisgeben, wodurch die gesamte Idee gefährdet wird: <i>(klicken zum Erweitern)</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);
});