Vai al contenuto
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🛡️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.

La stessa policy vale anche per il Componente React, che viene eseguito nella tua applicazione allo stesso modo.

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>:

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';

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:

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.

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.

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:

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.

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.

Ultimo aggiornamento