보안 모범 사례

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자의 소문자 16진수만 허용합니다. 원시 이메일, 전화번호 또는 디바이스 ID를 보내지 마세요. NU는 원시 PII를 수신하거나 저장하지 않습니다(재생 API).
• 재생 preferences에도 같은 규칙이 적용됩니다. 비PII 취향 신호만 보내세요. @ 또는 공백이 포함된 값은 422 validation_failed로 거부됩니다.

오리진 및 IP 제한

• allowed_origins로 재생 토큰이 귀사 도메인에만 발급되게 하고 allowed_ips로 API 요청을 귀사 서버 주소에 고정하세요(API 키).

사용할 최소 권한 스코프

• 각 키에는 해당 구성 요소에 필요한 권한만 부여하세요. 예를 들어 수집에는 settlement:dispute가 아니라 events:write가 필요합니다. 대용량과 민감한 워크로드를 분리하세요(인증).
• api_keys:write는 볼트에 보관된 운영 키에만 유지하세요. 재생 또는 이벤트 런타임 키에 키 관리 스코프를 부여하지 마세요.

재생 URL을 노출하지 마세요

• webview_url과 서명된 HLS/DASH 매니페스트는 수명이 짧고(기본 1,800초, 절대 최대 7,200초, Production 기본 상한 1,800초) 서명 토큰을 포함합니다. bearer 시크릿으로 취급하여 로그에 남기거나 expires_at 이후 캐시·공유하거나 webview_url을 공유 링크에 넣지 마세요. 필요할 때 재발급하고 webview_url은 시청자의 WebView 또는 iframe에서만 여세요.