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

### Utilizzo Sicuro

A causa delle limitazioni del web core, per integrare LavaDome in modo sicuro, ci sono alcune cose da tenere a mente che richiedono un impegno attivo da parte dello sviluppatore che integra il programma:

#### Ordine di esecuzione

LavaDome, come qualsiasi altro software di sicurezza JavaScript, è sempre vulnerabile al codice che viene eseguito prima di esso.

Ciò significa che, tranne che per il codice di cui ci fidiamo assolutamente, LavaDome deve essere il primo pezzo di codice a essere caricato nel programma dell'applicazione web.

Anche se questo non significa che lo sviluppatore debba usarlo immediatamente (ma solo quando ne ha bisogno), deve comunque includere il programma il prima possibile.

Per farlo correttamente (in sicurezza), deve essere la prima dichiarazione import/require nell'intero programma:```javascript
import '@lavamoat/lavadome-react';
import 'other-stuff';

console.log('Program starts here');

e non deve essere:```html
<span> <lavadome>your key is 234789</lavadome> </span>

Ecco alcuni dei metodi di utilità di debug esportati da `LavaDomeDebug` che possono aiutarti a testare i componenti basati su `LavaDome`:

#### `getTextByRoot()`

Data una root a cui è collegato `LavaDome`, `getTextByRoot()` estrae e ricostruisce ricorsivamente il segreto interno. Per consentire ciò, l'istanza di `LavaDome` deve essere inizializzata originariamente con l'opzione UNSAFE `@unsafeOpenModeShadow`, che rende accessibili dall'esterno le shadow interne di `LavaDome`.

Naturalmente, questa è una scelta UNSAFE e rende `LavaDome` completamente vulnerabile, ma ha senso solo per scopi di test/debugging: assicurati di non abilitare mai questa opzione in produzione!```javascript
new LavaDomeJavaScript(root, {
    unsafeOpenModeShadow: isThisTestingEnv, // boolean
}).text('123456');
LavaDomeDebug.getTextByRoot(root) === '123456'; // true

## Sviluppo

Per configurare una build di sviluppo locale di **`LavaDome`**, clona questo repository ed esegui uno dei seguenti comandi:```bash
npm install && npm install --global serve

myapp --ssl --cert /path/to/cert.pem --key /path/to/key.pem

## Soluzione

L'API Web [`ShadowDom`](https://web.dev/articles/`ShadowDom`-v1) ci consente di isolare e incapsulare i nodi DOM. Sebbene [non sia progettata come funzionalità di sicurezza](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` funziona bene per isolare sottoalberi DOM da JavaScript e CSS in esecuzione altrove nella pagina.

L'approccio di base di **`LavaDome`** è sfruttare `ShadowDom`, affrontando con attenzione le sue [potenziali lacune di sicurezza](https://blog.ankursundara.com/shadow-dom/).

**[LavaDome](https://github.com/lavamoat/lavadome/)** è pensato per essere uno **strumento di sicurezza nella cassetta degli attrezzi LavaMoat** per implementare componenti solo-frontend che consentano esclusivamente interazioni con l'utente e con codice fidato, bloccando al contempo i tentativi di accesso da parte di codice JavaScript e CSS non fidato nell'app.

> Un ringraziamento a [@arxenix](https://github.com/arxenix) per la loro [ricerca](https://blog.ankursundara.com/shadow-dom/) sulla sicurezza di `ShadowDom`, che ha fornito le basi per importanti miglioramenti di sicurezza implementati in **`LavaDome`**.

## Obiettivi

Il progetto **`LavaDome`** segue i seguenti principi fondamentali:

### Sicuro

La nostra priorità assoluta è garantire una sicurezza a prova di falle. Abbiamo avvolto l'API `ShadowDom` con proprietà di sicurezza avanzate per renderne sicuro l'uso quando si presentano informazioni sensibili.

Visita [Sicurezza](#Security) per saperne di più su questo lavoro.

### DX

Ci impegniamo a fornire un'esperienza di sviluppo fluida. A tal fine:

1. Supportiamo quanti più framework popolari possibile (React, Angular, ecc.);
2. Rendiamo l'API facile e semplice da usare.

### Solo modalità di lettura

In questa fase, non prevediamo di supportare la modalità di scrittura, il che significa che **`LavaDome`** accetterà solo contenuti in testo semplice da proteggere, e niente di più complesso.

Questo perché supportare la modalità di scrittura richiederebbe l'implementazione di un DOM isolato intrattabile, che introduce molteplici complicazioni di sicurezza che non siamo ancora pronti ad affrontare, come:

1. Sicurezza degli event listener - impedire al codice esterno di intercettare input destinati ai nodi interni di LavaDome.
2. Sicurezza delle sovrapposizioni - impedire a codice dannoso di sovrapporre un DOM di phishing su **`LavaDome`** per indurre l'utente a fornire input sensibili all'entità sbagliata.

## Design

La complessità progettuale di questo progetto non è elevata. Tuttavia, soddisfare i requisiti combinati dei principi di sicurezza che implementa è un compito non banale (vedi [Sicurezza](#Security)).

**`LavaDome`** è composto dai seguenti pacchetti:

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

Implementa il livello API di base che gestisce la comunicazione tra il consumatore e il componente isolato protetto. L'API mira a consentire quante più manipolazioni esterne possibile del componente isolato senza fornire a nessuno i nodi DOM effettivi al suo interno - nemmeno al consumatore di LavaDome - per mantenere il massimo livello di sicurezza possibile.

Inoltre, si assume la responsabilità di implementare tutto l'indurimento di sicurezza necessario per rendere l'uso della funzionalità `ShadowDom` davvero sicuro, in contrasto con la sua natura nativa di non essere una funzionalità di sicurezza per impostazione predefinita (vedi [Sicurezza](#Security)).

> Ricorda: il pacchetto core non è da usare per scopi di produzione!

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

Esportano funzionalità affinché gli sviluppatori possano utilizzare **`LavaDome`** come preferiscono, sia tramite JavaScript che come componente React (o qualsiasi altra piattaforma - [chiedete pure!](https://github.com/lavamoat/lavadome/issues/new?title=**`LavaDome`**+misses+support+for+...))
> NOTA: fornire supporto **`LavaDome`** per framework integra codice di terze parti che non controlliamo, il che crea "punti ciechi di sicurezza".

> Si prega di leggere la sezione [Sicurezza](#Security) per sapere come rimanere il più al sicuro possibile quando si usa **`LavaDome`** con framework di terze parti.

## Sicurezza

Se hai intenzione di usare **`LavaDome`** per un progetto, ecco gli aspetti di sicurezza da tenere presenti:

### `ShadowDom` vs `iframe`

Ancora una volta, questo è ancora un progetto sperimentale, ma abbiamo riflettuto su questa decisione. Un'alternativa naturale all'uso del `ShadowDom` è sfruttare `iframe` cross-origin. Infiltrare un `iframe` cross-origin è impossibile, ed è riconosciuto come meccanismo critico per la sicurezza dalle specifiche W3C. Ciò significa che se una violazione dovesse comunque verificarsi, verrebbe trattata come una vulnerabilità di sicurezza e corretta dai produttori di browser con urgenza.

Lo svantaggio di questo approccio, tuttavia, è che integrare una soluzione basata su iframe è significativamente più difficile, in termini di UI/UX/DX, soprattutto come strumento pensato per un'adozione di massa.

**`LavaDome`** deve fornire un'esperienza di sviluppo fluida e naturale, facilitando al contempo l'integrazione sicura di nodi DOM ombra incapsulati all'interno dell'albero DOM host, e `ShadowDom` è un'API orientata al DOM costruita proprio per questo scopo. Questo l'ha resa più adatta ai nostri obiettivi.

Sebbene l'API `ShadowDom` non sia ufficialmente sostenuta come strumento di sicurezza dai suoi creatori, la sua implementazione è altamente sicura e non fa trapelare alcuna informazione incapsulata dall'interno dell'albero DOM ombra, tranne che in scenari molto specifici.

Crediamo che affrontando con attenzione proprio quegli scenari, `ShadowDom` possa essere potenziata in un'API di incapsulamento DOM sicura (vale la pena provarci).

### Minacce

È importante affrontare le attuali minacce alla sicurezza che esistono con una soluzione basata su `ShadowDom` come `LavaDome`.

#### 1. Iniezione

Gli sviluppatori potrebbero fornire a **`LavaDome`** contenuti HTML/JS/CSS che, una volta caricati, possono accidentalmente o intenzionalmente far trapelare nodi DOM dall'interno del `ShadowDom`, ad esempio aggiungendo dinamicamente codice JavaScript a runtime.

Leggi la [ricerca](https://blog.ankursundara.com/shadow-dom/#contenteditable-or-css-injection) di [@arxenix](https://github.com/arxenix) per saperne di più su questa tecnica.

Per prevenire questa possibilità, **`LavaDome`** non accetta affatto nodi DOM nell'albero del DOM ombra e supporta solo l'incapsulamento di testo semplice. Questo ci evita di dover affrontare i problemi di sicurezza insiti nel fidarsi di contenuti HTML/JS/CSS forniti dall'utente.

Ci piacerebbe riconsiderare questa decisione in futuro, mentre studiamo un mezzo stabile e sicuro per supportare l'input di nodi DOM e sottoalberi.

#### 2. Reperibilità

L'API [find()](https://developer.mozilla.org/en-US/docs/Web/API/Window/find) consente agli sviluppatori di trovare ed estrarre nodi DOM cercando il testo che contengono. Questa è l'unica API finora nota in grado di far trapelare con successo nodi DOM dall'interno di un `ShadowDom`.

<details>
<summary>
    In Firefox, dopo aver trovato il testo, si può usare l'API <code>getSelection()</code> per far trapelare nodi DOM dall'interno del `ShadowDom`, compromettendo così l'intera idea: <i>(clicca per espandere)</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);
});