> For the complete documentation index, see [llms.txt](https://docs.aisuru.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisuru.com/frontend/content-security-policy.md).

# Content Security Policy

## Content Security Policy (CSP)

#### Panoramica

Se il sito in cui incorpori il tuo Agente usa una **Content Security Policy** (CSP), devi aggiungere alla policy gli host usati dal Componente Web. Senza queste voci il browser blocca le richieste del componente e l'Agente non si carica, oppure si carica solo in parte.

In questa pagina trovi:

* la policy pronta all'uso per **AIsuru SaaS** (`www.aisuru.com`) e per le **PaaS**;
* la policy con i segnaposto per le **altre installazioni**;
* il motivo di ogni voce e cosa succede se la ometti;
* la procedura consigliata per metterla in produzione.

#### Perché la CSP della tua pagina è quella che conta

Il Componente Web non è isolato dalla pagina che lo ospita: `<memori-client>` non usa né un iframe né lo shadow DOM, ma si monta direttamente nel documento della tua pagina.

Ogni richiesta del componente (chiamate API, WebSocket, font, audio, modelli dell'avatar) viene quindi valutata dal browser rispetto alla **CSP della tua pagina**. Per lo stesso motivo non possiamo impostare noi la policy al posto tuo: l'header è sotto il tuo controllo.

{% hint style="info" %}
La stessa policy vale anche per il Componente React, che viene eseguito nella tua applicazione allo stesso modo.
{% endhint %}

#### Policy per AIsuru SaaS e PaaS

Se il tuo Agente è su **AIsuru SaaS** (`www.aisuru.com`), puoi copiare questa policy così com'è. Inviala come **header di risposta** della pagina che contiene `<memori-client>`:

{% code overflow="wrap" %}

```
Content-Security-Policy:
  default-src 'none';
  script-src  'self' https://cdn.jsdelivr.net;
  style-src   'self' 'unsafe-inline' https://cdn.jsdelivr.net https://fonts.bunny.net;
  font-src    'self' data: https://cdn.jsdelivr.net https://fonts.bunny.net;
  img-src     'self' data: blob: https:;
  media-src   'self' blob: data: https://www.aisuru.com https://assets.memori.ai;
  connect-src 'self' https://www.aisuru.com
              https://backend-proxy.aisuru.com https://backend.memori.ai
              https://engine.memori.ai https://assets.memori.ai
              wss://nats.memori.ai
              https://pulse.aisuru.com
              https://status.claude.com https://status.openai.com https://status.mistral-data.com
              blob: data:;
  frame-src   'self' blob: data: https:;
  worker-src  'self' blob:;
  form-action 'self';
  base-uri    'self';
```

{% endcode %}

La policy copre tutte le funzionalità del componente. Se la tua pagina carica anche altre risorse, aggiungile alle stesse direttive.

**Se usi una PaaS**

Una PaaS usa gli stessi servizi di AIsuru SaaS: cambia solo il **dominio della tua piattaforma**, cioè quello che trovi negli attributi `tenantID` e `baseURL` del codice di incorporamento. Sostituisci `www.aisuru.com` con il tuo dominio nelle direttive `media-src` e `connect-src`. Ad esempio, con la PaaS su `ai.your-company.com`:

```
  media-src   'self' blob: data: https://ai.your-company.com https://assets.memori.ai;
  connect-src 'self' https://ai.your-company.com
              https://backend-proxy.aisuru.com https://backend.memori.ai
              ...
```

Tutte le altre righe restano invariate.

**Gli host della policy**

| Host                                                                | A cosa serve                                                                                   |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `www.aisuru.com` (o il dominio della tua PaaS)                      | Servizi del componente lato server: sintesi vocale, riconoscimento vocale, eventi di sessione  |
| `backend-proxy.aisuru.com`, `backend.memori.ai`                     | API della piattaforma: sessioni, Agenti, asset, autenticazione                                 |
| `engine.memori.ai`                                                  | Motore conversazionale                                                                         |
| `assets.memori.ai`                                                  | Asset archiviati: avatar, sfondi, media, documenti caricati                                    |
| `nats.memori.ai`                                                    | Canale WebSocket per gli eventi della sessione in tempo reale                                  |
| `cdn.jsdelivr.net`                                                  | Il codice e il foglio di stile del componente, più le librerie per formule e snippet di codice |
| `fonts.bunny.net`                                                   | Il font del componente                                                                         |
| `pulse.aisuru.com`                                                  | Un segnale anonimo di caricamento del componente                                               |
| `status.claude.com`, `status.openai.com`, `status.mistral-data.com` | Indicatore di stato del fornitore del modello                                                  |

Il Componente Web sostituisce automaticamente `backend.memori.ai` con `backend-proxy.aisuru.com`, per cui la richiesta parte verso il proxy anche se nel codice di incorporamento leggi `backend.memori.ai`. Il Componente React invece non fa questa sostituzione: per questo la policy li elenca entrambi.

{% hint style="info" %}
Vuoi una policy più compatta? Le wildcard `https://*.aisuru.com https://*.memori.ai wss://*.memori.ai` coprono in un colpo solo tutti gli host di `aisuru.com` e `memori.ai` nella direttiva `connect-src`.
{% endhint %}

Non devi consentire i fornitori di modelli o di voce (ad esempio OpenAI o Azure): il browser non li contatta mai direttamente. Sintesi e riconoscimento vocale passano dai servizi della piattaforma, che custodiscono le chiavi lato server.

#### Policy per le altre installazioni

Se il tuo Agente è su un'installazione dedicata o on-premise, gli host cambiano. Usa questa policy e sostituisci i segnaposto con i valori della tua installazione:

{% code overflow="wrap" %}

```
Content-Security-Policy:
  default-src 'none';
  script-src  'self' https://cdn.jsdelivr.net;
  style-src   'self' 'unsafe-inline' https://cdn.jsdelivr.net https://fonts.bunny.net;
  font-src    'self' data: https://cdn.jsdelivr.net https://fonts.bunny.net;
  img-src     'self' data: blob: https:;
  media-src   'self' blob: data: https://<tenant-host> https://<assets-host>;
  connect-src 'self' https://<tenant-host> https://<backend-host> https://<engine-host>
              https://<assets-host> wss://<nats-host>
              https://pulse.aisuru.com
              https://status.claude.com https://status.openai.com https://status.mistral-data.com
              blob: data:;
  frame-src   'self' blob: data: https:;
  worker-src  'self' blob:;
  form-action 'self';
  base-uri    'self';
```

{% endcode %}

| Segnaposto       | Che cos'è                                                                  | Dove trovarlo                                                              |
| ---------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `<tenant-host>`  | Dominio della piattaforma, che espone i servizi del componente lato server | Attributo `baseURL` del codice di incorporamento (in mancanza, `tenantID`) |
| `<backend-host>` | API della piattaforma                                                      | Attributo `apiURL`                                                         |
| `<engine-host>`  | Motore conversazionale                                                     | Attributo `engineURL`                                                      |
| `<assets-host>`  | Asset archiviati: avatar, sfondi, media, documenti                         | Indirizzo degli asset dell'Agente (ad esempio l'URL dell'avatar)           |
| `<nats-host>`    | Canale WebSocket per gli eventi della sessione                             | Fornito dal team che gestisce l'installazione                              |

Gli altri host (`cdn.jsdelivr.net`, `fonts.bunny.net`, `pulse.aisuru.com` e i tre `status.*`) sono gli stessi per tutte le installazioni.

{% hint style="warning" %}
Se il canale WebSocket della tua installazione risponde su una porta diversa dalla 443, devi indicarla esplicitamente, ad esempio `wss://nats.your-company.com:8080`. Una sorgente senza porta vale solo per la porta predefinita.
{% endhint %}

#### Direttiva per direttiva

| Direttiva     | Voce                                  | Perché serve                                                                                                                            |
| ------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `script-src`  | `https://cdn.jsdelivr.net`            | Il codice del componente; inoltre le librerie caricate quando l'Agente mostra uno snippet di codice o una formula                       |
| `style-src`   | `'unsafe-inline'`                     | Il componente applica colori del tema e dimensioni del layout tramite stili inline                                                      |
| `style-src`   | `cdn.jsdelivr.net`, `fonts.bunny.net` | Il foglio di stile del componente importa gli stili delle formule e il font                                                             |
| `font-src`    | gli stessi due host, più `data:`      | I file dei font                                                                                                                         |
| `img-src`     | `data:`, `blob:`                      | Immagini segnaposto, codici QR e anteprime delle immagini prima del caricamento                                                         |
| `img-src`     | `https:`                              | Le risposte e le anteprime dei link possono contenere immagini da qualsiasi sito: restringere questa voce rompe i contenuti dell'Agente |
| `media-src`   | `blob:`                               | La voce sintetizzata viene riprodotta localmente                                                                                        |
| `media-src`   | host del tenant e degli asset         | Audio e video allegati alle risposte                                                                                                    |
| `connect-src` | host del tenant                       | Sintesi vocale, riconoscimento vocale e configurazione degli eventi di sessione                                                         |
| `connect-src` | host di backend e motore              | Sessioni, informazioni sull'Agente, caricamento degli asset e la conversazione stessa                                                   |
| `connect-src` | `wss://` del canale eventi            | Ricezione in tempo reale degli eventi della sessione                                                                                    |
| `connect-src` | `pulse.aisuru.com`                    | Un evento anonimo per ogni caricamento del componente (non inviato su localhost)                                                        |
| `connect-src` | i tre host `status.*`                 | Indicatore di stato del fornitore del modello                                                                                           |
| `connect-src` | `blob:`, `data:`                      | Lettura di file prodotti localmente, ad esempio nel caricamento dei documenti e nell'esportazione in PDF                                |
| `frame-src`   | `blob:`, `data:`                      | Anteprima dei PDF                                                                                                                       |
| `frame-src`   | `https:`                              | Le anteprime dei link possono incorporare player video esterni, come YouTube o Vimeo                                                    |

Il componente non richiede `'unsafe-eval'` né `'wasm-unsafe-eval'`. Se una segnalazione di violazione ne riporta uno, la causa è un'altra parte della tua pagina.

#### Funzionalità opzionali

Se vuoi una policy più restrittiva, puoi rinunciare ad alcune voci. La tabella indica cosa aggiungere per le funzionalità non coperte dalla policy di base e cosa succede se ometti le voci.

| Funzionalità                    | Voci da aggiungere o rimuovere                                                                                                                                | Se le ometti                                                                                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Indicatore di stato del modello | `connect-src` verso i tre host `status.*` (già nella policy di base)                                                                                          | L'indicatore non compare e trovi solo un errore in console. Se lo vuoi, consenti tutti e tre gli host: quello usato cambia con il fornitore del modello dell'Agente        |
| Mappe e luoghi                  | `script-src` e `style-src https://unpkg.com`; `img-src https://unpkg.com https://*.tile.openstreetmap.org`; `connect-src https://nominatim.openstreetmap.org` | La mappa non viene mostrata e la ricerca dei luoghi non funziona                                                                                                           |
| Modelli 3D personalizzati       | `script-src https://unpkg.com`                                                                                                                                | I modelli GLB personalizzati non vengono mostrati                                                                                                                          |
| Avatar Ready Player Me          | `connect-src` e `img-src https://models.readyplayer.me`                                                                                                       | L'avatar ripiega su quello predefinito o non viene mostrato                                                                                                                |
| Input vocale                    | Nessuna voce CSP, ma l'header `Permissions-Policy: microphone=(self)` e una pagina servita in HTTPS                                                           | Il pulsante del microfono non funziona                                                                                                                                     |
| Artefatti interattivi           | `script-src 'unsafe-inline'`                                                                                                                                  | Gli artefatti ereditano la CSP della tua pagina: il contenuto compare, ma gli script al suo interno non vengono eseguiti. Nella maggior parte dei casi conviene accettarlo |
| Segnale di caricamento          | `connect-src https://pulse.aisuru.com` (già nella policy di base)                                                                                             | Non si rompe nulla                                                                                                                                                         |

#### Attenzione a

* **Wildcard e dominio principale**: `https://*.aisuru.com` copre `www.aisuru.com` ma non `aisuru.com`. Se usi il dominio senza sottodominio, elencali entrambi;
* **`data:` e `blob:`**: sono schemi, non host, e vanno ripetuti in ogni direttiva che li richiede. Una violazione che riporta un URL `data:` o `blob:` riguarda quasi sempre `img-src`, `media-src` o `frame-src`;
* **Header o tag `<meta>`**: se invii la policy tramite un tag `<meta>`, le direttive `frame-ancestors`, `report-uri` e `sandbox` vengono ignorate. Preferisci l'header;
* **`frame-ancestors`**: non riguarda il Componente Web, che non è un iframe. Serve solo se incorpori una pagina AIsuru in un iframe, e in quel caso è impostata dalla piattaforma, non dalla tua pagina.

#### Come mettere in produzione la policy

1. **Pubblica la policy in modalità di sola segnalazione**
   * Usa l'header `Content-Security-Policy-Report-Only` al posto di `Content-Security-Policy`;
   * Il browser segnala le violazioni senza bloccare nulla.
2. **Prova l'intera conversazione**
   * Invia un messaggio di testo;
   * Prova la voce in ingresso e in uscita;
   * Apri una risposta con immagini o video;
   * Carica un documento e apri un artefatto.
3. **Controlla le segnalazioni**
   * Ogni violazione indica un host o uno schema da aggiungere a una direttiva;
   * Confrontala con le tabelle di questa pagina.
4. **Applica la policy**
   * Passa a `Content-Security-Policy` solo quando non ricevi più segnalazioni.

{% hint style="warning" %}
Non affidarti solo a un controllo visivo: alcune funzionalità, come l'indicatore di stato del modello, smettono di funzionare senza mostrare alcun errore nella pagina. Le segnalazioni della CSP e la console del browser sono l'unico modo affidabile per trovarle.
{% endhint %}
