Content Security Policy

Kaleidr 的 SDK 在客戶頁面中運行。這表示客戶頁面的 Content Security Policy 必須允許每個產品所載入的資源。本 頁面提供相應設定。

依產品

Tile 與 Viewer（iframe 產品）

Tile 與 Viewer 會在 map-embed.kaleidr.com 內、由 Kaleidr 自身 CSP 管理的環境中載入實際地圖。父頁面只需要允許 iframe 本身以及 SDK loader：

default-src 'self';
script-src  'self' https://cdn.kaleidr.com;
frame-src   https://map-embed.kaleidr.com;
connect-src 'self' https://api.kaleidr.com;

如果您只嵌入 Tile 或 Viewer，父頁面不需要允許 Mapbox / MapTiler / OSM / vendor image host — 這些資源都位於 Kaleidr iframe 內。

Chat 與 Editor（頁面內 attach）

Chat 與 Editor 會在父文件中掛載 MapLibre。父頁面的 CSP 必須允許 MapLibre 與 SDK 實際載入的每一個 host：

default-src 'self';
script-src  'self' 'wasm-unsafe-eval' https://cdn.kaleidr.com;
style-src   'self' 'unsafe-inline' https://cdn.kaleidr.com;
connect-src 'self'
            https://api.kaleidr.com
            https://api.mapbox.com https://events.mapbox.com
            https://api.maptiler.com
            https://*.tiles.mapbox.com;
img-src     'self' data: blob:
            https://api.mapbox.com https://*.tiles.mapbox.com
            https://api.maptiler.com
            https://*.tile.openstreetmap.org;
worker-src  'self' blob:;
font-src    'self' data:;

'wasm-unsafe-eval' 是必要的 — MapLibre 會在運行時編譯 WebAssembly， 缺少它就會失敗。如果您的 CSP 禁止 'wasm-unsafe-eval'，目前就無法 在頁面內掛載 Chat 或 Editor。

最先出現的問題

症狀	可能缺少的 directive
SDK loader 傳回 404 或被阻擋	script-src https://cdn.kaleidr.com
MapLibre 初始化失敗（Chat/Editor）	script-src 中缺少 'wasm-unsafe-eval'
Tile 顯示空白 / 灰色	vendor host 對應的 connect-src 和/或 img-src
Iframe 始終無法呈現（Tile / Viewer）	frame-src https://map-embed.kaleidr.com
Console 中 session exchange 傳回 4xx	不是 CSP — 請查看 Auth & scopes 中的 origin allowlist

Nonce 與 hash

上面的 style-src 包含 'unsafe-inline'，因為 MapLibre 會產生 inline <style> block。如果您的 CSP 目前禁止 'unsafe-inline'，請使用 nonce，並在該 nonce 下重新輸出樣式 — SDK 目前不會 為每次載入產生 nonce；如有需要，請在 kaleidr-sdk 提交 issue。

Report-only rollout

安全採用此政策的方法是：

1. 將上述設定設為 Content-Security-Policy-Report-Only，並使用您自己的 report-uri 運行一週。
2. 將違規報告中出現的 host 加入正確的 directive。
3. 當報告不再出現問題時，將 header 升級為 Content-Security-Policy。