​

Known footguns

​

Trailing slash on frameOrigin

Mint compares exact strings. https://partner.com/ will fail if the allowlist entry is https://partner.com. CloudFront frame-ancestors also matches bare origins.

​

Cloudflare orange cloud

Proxy mode rewrites bytes and headers. Immutable pinning verification and CSP assertions will fail even when the page appears to work.

​

Mutable embed URLs

Never serve /chart/latest. Pin /chart/v<semver>/index.html and fail CI if the S3 prefix already exists. CloudFront has no directory-index rewrite, so /chart/v<semver>/ will not load the chart.

​

TOKEN_KEY_UNKNOWN after key rotation

Public keys are baked into pinned bundles. Key rotation requires shipping a new embed version and updating the partner pin.

​

Global allowlist

EMBED_ALLOWED_FRAME_ORIGINS is one list for all partners in MVP. Any allowed origin can frame using another partner’s token until per-partner scoping exists.

​

SDK copy vs npm

MVP docs use a copied snippet (~40 lines). An npm package is optional later; a script tag from our CDN is rejected because it places Headlight code in the partner origin.

​

postMessage targetOrigin

Always pass the embed CDN origin to postMessage. Using * defeats origin checks on the parent side.