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。