安全最佳实践

安全集成 NU Signal Partners API 的指南。

保护密钥

• API 密钥值和观众 ID 盐仅显示或可知一次。请存入密钥管理器；绝不要放入源码管理、客户端包、日志或错误报告。
• 密钥泄露后应立即吊销或轮换（API 密钥）。

仅在服务器端使用密钥

• 请从后端调用 API。绝不要将 nsp_test_ 或 nsp_live_ 密钥嵌入浏览器、移动应用或其他分发客户端。
• 所有由客户端发起的流程（如播放令牌请求）都应经服务器代理，以确保密钥和观众盐保持私密。

定期轮换密钥

• 请定期并在怀疑泄露时采用 overlap-and-revoke：创建、部署、验证，再吊销旧密钥。吊销密钥不会取消已签发的令牌或会话；它们按自身 TTL 过期，因此 TTL 应保持较短。

观众 ID 哈希——禁止 PII

• viewer_id_hash 必须是由您计算的 SHA-256(stable_viewer_id + salt)。Production 仅接受恰好 64 个小写十六进制字符。绝不要发送原始邮箱、电话或设备 ID。NU 不接收也不存储原始 PII（播放 API）。
• 播放 preferences 同样适用此规则：仅发送非 PII 偏好信号。包含 @ 或空格的值会以 422 validation_failed 拒绝。

限制来源和 IP

• 设置 allowed_origins，使播放令牌仅为您的域名签发；设置 allowed_ips，将 API 请求限定到您的服务器地址（API 密钥）。

使用最小权限作用域

• 每个密钥只授予其组件所需权限；例如摄取需要 events:write，而非 settlement:dispute。分离高容量和敏感工作负载（身份验证）。
• api_keys:write 仅应保留在保险库中的运维密钥上。不要向播放或事件运行时密钥授予密钥管理作用域。

不要暴露播放 URL

• webview_url 和签名 HLS/DASH 清单有效期很短（默认 1,800 秒，绝对上限 7,200；Production 默认上限 1,800），并嵌入签名令牌。应视为 Bearer 密钥：不要记录日志，不要在 expires_at 后缓存或分享，也不要将 webview_url 放入可分享链接。按需重新签发，并仅在观众 WebView 或 iframe 中打开 webview_url。