보안 모범 사례

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)이어야 합니다. 원시 이메일, 전화번호, 디바이스 ID를 절대 전송하지 마세요. NU는 어떠한 원시 PII도 수신하거나 저장하지 않습니다(재생 API).
• 재생 preferences에도 동일하게 적용됩니다: 비PII 취향 신호(언어, 장르, 자막/오디오 기본값, 자동 재생)만 전송하세요. @나 공백을 포함하는 값은 422 validation_failed로 거부됩니다.

오리진 및 IP 제한

• allowed_origins를 설정하여 재생 토큰이 본인의 도메인에 대해서만 발급되도록 하고, allowed_ips를 설정하여 요청을 본인의 서버 주소로 고정하세요(API 키).

최소 권한 스코프

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

재생 URL을 노출하지 마세요

• webview_url과 서명된 HLS/DASH 매니페스트는 수명이 짧으며(기본 1800초, 최대 7200초) 둘 다 서명된 토큰을 내장합니다. 이를 베어러 시크릿으로 취급하세요: 절대 로그에 남기거나, expires_at 이후로 캐싱·공유하거나, webview_url을 공유 가능한 링크에 넣지 마세요. 필요에 따라 재발급하고, webview_url은 시청자 본인의 WebView/iframe 내에서만 여세요.