/** * PG 결제창 CSP 허용 도메인 표. * * ## 왜 필요한가 * * `open_type: 'iframe'` 으로 결제창을 띄우면 SDK 가 만든 iframe 이 `about:blank`/`srcdoc` * 상태로 시작하므로 **가맹점 페이지의 CSP 를 상속**한다. 그래서 결제창 안에서 PG 로 넘어가는 * 프레임까지 가맹점 CSP 로 검사되고, `frame-src` 에 부트페이 도메인만 넣어두면 PG 단계에서 막힌다. * * ``` * Framing 'https://web.nicepay.co.kr/' violates the following Content Security Policy * directive: "frame-src 'self' https://*.bootpay.co.kr https://*.lightpay.kr ..." * ``` * * ## 신뢰 수준 * * 아래 `verifiedHosts` 는 2026-08-25 DNS 해석으로 **호스트 실재만** 확인한 값이다. * PG 는 도메인을 바꾸므로 이 표가 항상 최신이라는 보장은 없다. * **콘솔 에러에 찍힌 도메인을 그대로 추가하는 것이 언제나 우선하는 폴백**이며, * 이 표는 "무엇을 미리 넣어두면 대부분 안 막히는가" 를 답하는 용도다. */ export type CspDirective = 'frame-src' | 'form-action' | 'connect-src' | 'script-src' | 'img-src'; export interface PgCspEntry { /** 부트페이 `pg` 파라미터 코드 */ code: string; /** 한글 PG사명 */ label: string; /** frame-src 에 넣을 host-source (와일드카드 권장값) */ frameSrc: string[]; /** DNS 로 실재를 확인한 호스트 — 와일드카드 근거 */ verifiedHosts: string[]; /** * 이 PG 를 고르면 **내부적으로 함께 열리는** 다른 PG 코드. * 라이트페이가 대표 사례 — 결제창은 라이트페이지만 실제 결제 모듈은 * 세틀뱅크 또는 나이스페이로 넘어간다. */ routesThrough?: string[]; /** 결제창 서브도메인을 특정하지 못해 와일드카드로만 안내하는 항목 */ unverified?: boolean; note?: string; } /** 부트페이 연동이면 PG 무관하게 항상 필요한 도메인 */ export declare const BOOTPAY_COMMON: string[]; /** 주소검색(다음 우편번호) · 상담 위젯 등 결제 흐름에 흔히 끼는 부가 도메인 */ export declare const COMMON_EXTRAS: string[]; /** 본인인증(method: 'auth') 을 쓸 때 추가로 필요한 도메인 */ export declare const CERT_DOMAINS: string[]; export declare const PG_CSP_TABLE: PgCspEntry[]; /** * 카드사 ACS(Access Control Server) 도메인 — 3-D Secure/안심클릭 인증 화면. * * PG 도메인과 **다른 레이어**다. PG 결제창 안에서 카드 인증 단계로 넘어갈 때 * 카드사 자체 서버가 프레임되므로, PG 도메인만 열어두면 "카드 고르고 인증 단계에서 멈춘다"가 된다. * * 근거: DNS 해석 + HTTPS 실응답 + **TLS 인증서 주체**(EV 인증서에 발급 법인명이 박혀 있어 * 오귀속을 걸러낼 수 있다) 3중 확인 (2026-08-25). * 공개된 정리본이 없어(GA 리퍼럴 제외 목록이 3건으로 가장 근접) 이 표가 사실상 유일한 출처다. */ export interface CardAcsEntry { /** 카드사명 */ issuer: string; /** CSP host-source */ frameSrc: string[]; /** 실응답을 확인한 호스트 */ verifiedHosts: string[]; /** 확인 근거 (인증서 주체 등) */ evidence: string; note?: string; } export declare const CARD_ACS_TABLE: CardAcsEntry[]; /** * DNS 는 해석되지만 HTTPS 응답이 없어 **실제 ACS 인지 확인하지 못한** 호스트. * 추측으로 허용목록에 넣으면 표 전체의 신뢰도가 깎이므로 기본 목록에서 제외한다. * 해당 카드로 막히는 사례가 나오면 콘솔 도메인으로 확정해 위 표로 승격할 것. */ export declare const CARD_ACS_UNCONFIRMED: string[]; /** 카드사 ACS frame-src 값 전체 (평탄화) */ export declare function cardAcsHosts(): string[]; export declare function resolvePgCode(input: string): string | null; export interface AllowlistOptions { /** 본인인증(method: 'auth') 사용 여부 */ includeCert?: boolean; /** 주소검색·상담위젯 등 부가 도메인 포함 여부 (기본 true) */ includeExtras?: boolean; /** * 카드사 ACS(3-D Secure 인증) 도메인 포함 여부 (**기본 true**). * * 본인인증과 달리 이건 선택 상품이 아니라 **평범한 카드결제의 일부**다. * 빼면 "결제창은 뜨는데 카드 인증에서 멈춘다"가 되고, PG 도메인만 보고 있으면 * 원인을 못 찾는다. 끄는 것은 카드결제를 아예 안 받는 경우뿐이다. */ includeCardAcs?: boolean; } export interface AllowlistResult { /** 실제로 반영된 PG 엔트리 (routesThrough 로 자동 추가된 것 포함) */ entries: PgCspEntry[]; /** routesThrough 로 자동 추가된 코드 → 그 원인이 된 코드 */ implied: Array<{ code: string; because: string; }>; /** 표에 없어 해석하지 못한 입력 */ unknown: string[]; /** 함께 넣은 카드사 ACS 항목 (비어 있으면 미포함) */ cardAcs: CardAcsEntry[]; directives: Record; } /** * PG 코드 목록으로 CSP 지시어별 허용 목록을 만든다. * `codes` 가 비어 있으면 표 전체를 넣는다 (PG 를 아직 못 정한 가맹점용 최대 허용본). */ export declare function buildAllowlist(codes: string[], opts?: AllowlistOptions): AllowlistResult; export type SnippetTarget = 'vercel' | 'nextjs' | 'nuxt' | 'nginx' | 'express' | 'meta' | 'raw'; /** * 복붙 스니펫에 **실제로 넣는** 지시어. * * 결제창을 막는 것은 `frame-src` 뿐이다. 나머지(`script-src`·`img-src`·`connect-src`·`form-action`)를 * 같이 넣으면, **CSP 가 원래 없던 사이트에서는 없던 제약이 새로 생긴다** — 특히 `script-src` 를 * 넣는 순간 애널리틱스·챗봇·광고 태그 등 그 사이트의 다른 스크립트가 전부 차단된다. * 결제를 고치려다 사이트를 부수는 셈이다. * * (실측: 초보 시뮬레이션에서 어시스턴트가 5개 지시어를 그대로 vercel.json 에 써 넣었다.) * * 그래서 스니펫은 frame-src 만 내고, 나머지는 "이미 선언 중이라면 병합할 값" 으로 따로 보여준다. */ export declare const SNIPPET_DIRECTIVES: CspDirective[]; /** 이미 선언 중일 때만 병합해야 하는 지시어 — 새로 만들면 없던 제약이 생긴다 */ export declare const MERGE_ONLY_DIRECTIVES: CspDirective[]; /** 지시어 맵에서 일부만 골라낸다 */ export declare function pickDirectives(directives: Record, keys: CspDirective[]): Record; /** 지시어 맵을 한 줄짜리 CSP 헤더 값으로 직렬화 */ export declare function renderHeaderValue(directives: Partial>): string; export declare function renderSnippet(target: SnippetTarget, directives: Partial>): string; /** 표에 있는 모든 PG 코드 (도구 describe 문구 생성용) */ export declare function allPgCodes(): string[]; //# sourceMappingURL=pg-domains.d.ts.map