From 4a2e85032d9464505f96a92c73a2a1248b94fa40 Mon Sep 17 00:00:00 2001
From: Junseong Park <39112954+jsparkdev@users.noreply.github.com>
Date: Fri, 6 Jun 2025 16:58:05 +0900
Subject: [PATCH] i18n(ko-KR): create `csp.mdx`
---
.../ko/reference/experimental-flags/csp.mdx | 411 ++++++++++++++++++
1 file changed, 411 insertions(+)
create mode 100644 src/content/docs/ko/reference/experimental-flags/csp.mdx
diff --git a/src/content/docs/ko/reference/experimental-flags/csp.mdx b/src/content/docs/ko/reference/experimental-flags/csp.mdx
new file mode 100644
index 0000000000000..6b981bc66f469
--- /dev/null
+++ b/src/content/docs/ko/reference/experimental-flags/csp.mdx
@@ -0,0 +1,411 @@
+---
+title: 실험적 콘텐츠 보안 정책
+sidebar:
+ label: 콘텐츠 보안 정책
+i18nReady: true
+tableOfContents:
+ minHeadingLevel: 2
+ maxHeadingLevel: 6
+---
+
+import Since from '~/components/Since.astro'
+
+
+
+ **타입:** `boolean | object`
+ **기본값:** `false`
+
+
+
+[콘텐츠 보안 정책 (CSP)](https://developer.mozilla.org/ko/docs/Web/HTTP/Guides/CSP) 지원을 활성화하여 문서가 로드할 수 있는 리소스를 제어함으로써 특정 유형의 보안 위협을 최소화합니다. 이는 [교차 사이트 스크립팅 (XSS)](https://developer.mozilla.org/ko/docs/Glossary/Cross-site_scripting) 공격에 대한 추가적인 보호를 제공합니다.
+
+이 기능을 활성화하면 기본적으로 **Astro에 의해 처리되고 번들링된 스크립트 및 스타일에** 추가 보안이 적용되며, 이러한 콘텐츠 유형과 추가적인 콘텐츠 유형을 더욱 세밀하게 구성할 수 있습니다.
+
+이 실험적인 CSP 기능에는 몇 가지 제한 사항이 있습니다. 인라인 스크립트는 기본적으로 지원되지 않지만, 외부 및 인라인 스크립트에 [자체 해시를 제공](#hashes)할 수 있습니다. 또한 ``를 사용하는 [Astro의 뷰 전환](/ko/guides/view-transitions/)은 아직 완전히 지원되지 않습니다. 다른 페이지로 이동할 때 일부 스타일이 적용되지 않거나 일부 스크립트가 실행되지 않을 수 있습니다.
+
+:::note
+Vite 개발 서버의 특성상, `dev` 모드에서 작업하는 동안에는 이 기능이 지원되지 않습니다. 대신 `build` 및 `preview`를 사용하면 Astro 프로젝트에서 이 기능을 테스트할 수 있습니다.
+:::
+
+이 기능을 사용하려면 Astro 구성에서 실험적 플래그를 추가하세요.
+
+```js title="astro.config.mjs" ins={4-6}
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+ experimental: {
+ csp: true
+ }
+});
+```
+
+이 기능을 활성화하면 Astro는 각 페이지의 `` 요소에 `` 요소를 추가합니다.
+
+이 요소에는 `http-equiv="content-security-policy"` 속성이 있으며, `content` 속성은 페이지에 사용된 스크립트 및 스타일을 기반으로 `script-src` 및 `style-src` [지시어](#directives)에 대한 값을 제공합니다.
+
+```html
+
+
+
+```
+
+## 구성
+
+추가 옵션이 포함된 구성 객체로 이 기능을 활성화하여 `` 요소를 추가로 사용자 정의할 수 있습니다.
+
+### `algorithm`
+
+
+
+**타입:** `'SHA-256' | 'SHA-512' | 'SHA-384'`
+**기본값:** `'SHA-256'`
+
+
+
+Astro에서 내보낸 스타일 및 스크립트의 해시를 생성할 때 사용할 [해시 함수](https://developer.mozilla.org/ko/docs/Glossary/Hash_function)입니다.
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+ experimental: {
+ csp: {
+ algorithm: 'SHA-512'
+ }
+ }
+});
+```
+
+### `directives`
+
+
+
+**타입:** `CspDirective[]`
+**기본값:** `[]`
+
+
+
+특정 콘텐츠 유형에 대해 유효한 소스를 정의하는 [CSP 지시어](https://content-security-policy.com/#directive) 목록입니다.
+
+Astro는 `script-src` 및 `style-src` 지시어를 제어해야 하지만, `csp.directives` 필드를 사용하면 다른 CSP 지시어를 제어할 수도 있습니다. 이 지시어들은 모든 페이지에 추가됩니다. 타입 안전 지시어 목록을 전달받습니다.
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+ experimental: {
+ csp: {
+ directives: [
+ "default-src 'self'",
+ "image-src 'self' 'https://images.cdn.example.com'"
+ ]
+ }
+ }
+});
+```
+
+빌드 후, `` 요소는 `content` 값에 Astro의 기본 지시어와 새로운 지시어를 추가합니다.
+
+```html
+
+```
+
+### `styleDirective` and `scriptDirective`
+
+
+
+**타입:** `object`
+**기본값:** `{}`
+
+
+
+`style-src` 및 `script-src` 지시어의 기본 소스를 [`resources`](#resources) 속성으로 재정의하거나 렌더링할 추가 [해시](#hashes)를 제공하는 구성 객체입니다.
+
+이러한 속성은 모든 페이지에 추가되는 것이 아니라 **Astro의 기본 리소스를 완전히 재정의합니다.** 따라서 포함할 기본값을 명시적으로 지정해야 합니다.
+
+#### `resources`
+
+
+
+**타입:** `string[]`
+**기본값:** `[]`
+
+
+
+`script-src` 및 `style-src` 지시어에 유효한 소스 목록입니다.
+
+기본적으로 `script-src` 및 `style-src` 지시어는 Astro에서 처리하며 `'self'` 리소스를 사용합니다. 즉, 스크립트와 스타일은 현재 호스트 (일반적으로 현재 웹사이트)에서만 다운로드할 수 있습니다.
+
+기본 소스를 재정의하기 위해 리소스 목록을 제공할 수 있습니다. 이 목록에는 기본적으로 `'self'`가 포함되지 않으므로, 이를 유지하려면 이 목록에 포함시켜야 합니다. 이 리소스들은 모든 페이지에 추가됩니다.
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+ experimental: {
+ csp: {
+ styleDirective: {
+ resources: [
+ "self",
+ "https://styles.cdn.example.com"
+ ]
+ },
+ scriptDirective: {
+ resources: [
+ "https://cdn.example.com"
+ ]
+ }
+ }
+ }
+});
+```
+
+빌드 후, `` 요소는 `style-src` 및 `script-src` 지시어에 소스를 적용합니다.
+
+```html
+
+
+
+```
+
+#### `hashes`
+
+
+
+**타입:** `CspHash[]`
+**기본값:** `[]`
+
+
+
+렌더링할 추가 해시 목록입니다.
+
+Astro에서 생성되지 않은 외부 스크립트, 스타일, 인라인 스크립트를 사용하는 경우, 이 구성 옵션을 사용하여 렌더링할 추가 해시를 제공할 수 있습니다.
+
+`sha384-`, `sha512-`, `sha256-`로 시작하는 해시를 제공해야 합니다. 다른 값을 제공하면 유효성 검사 오류가 발생합니다. 이 해시들은 모든 페이지에 추가됩니다.
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+ experimental: {
+ csp: {
+ styleDirective: {
+ hashes: [
+ "sha384-styleHash",
+ "sha512-styleHash",
+ "sha256-styleHash"
+ ]
+ },
+ scriptDirective: {
+ hashes: [
+ "sha384-scriptHash",
+ "sha512-scriptHash",
+ "sha256-scriptHash"
+ ]
+ }
+ }
+ }
+});
+```
+
+빌드 후, `` 요소는 `script-src` 및 `style-src` 지시어에 추가 해시를 포함시킵니다.
+
+```html
+
+```
+
+#### `strictDynamic`
+
+
+
+**타입:** `boolean`
+**기본값:** `false`
+
+
+
+스크립트의 동적 삽입을 지원하기 위해 [`strict-dynamic` 키워드](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP#the_strict-dynamic_keyword)를 활성화합니다.
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+ experimental: {
+ csp: {
+ scriptDirective: {
+ strictDynamic: true
+ }
+ }
+ }
+});
+```
+## 런타임 API
+
+`.astro` 컴포넌트의 런타임 API (`Astro` global을 통해 사용 가능) 또는 엔드포인트 및 미들웨어의 `APIContext` 타입을 통해 페이지별 `` 요소를 사용자 정의할 수 있습니다.
+
+### `addDirective`
+
+
+ **타입:** `(directive: CspDirective) => void`
+
+
+
+현재 페이지에 하나의 지시어를 추가합니다. 이 메서드를 여러 번 호출하여 여러 지시어를 추가할 수도 있습니다.
+
+```astro
+---
+Astro.addDirective("default-src 'self'");
+Astro.addDirective("img-src 'self' 'https://images.cdn.example.com'");
+---
+```
+
+빌드 후, 이 페이지의 `` 요소는 포함된 `style-src` 및 `script-src` 지시어에 새로운 지시어를 추가합니다.
+
+```html
+
+```
+
+### `insertStyleResource`
+
+
+ **타입:** `(resource: string) => void`
+
+
+
+`style-src` 지시어에 사용할 새 리소스를 삽입합니다.
+
+```astro
+---
+Astro.insertStyleResource("'https://styles.cdn.example.com'");
+---
+```
+
+빌드 후, 이 페이지의 `` 요소는 기본 `style-src` 지시어에 소스를 추가합니다.
+
+```html
+
+```
+
+
+### `addStyleHash`
+
+
+ **타입:** `(hash: CspHash) => void`
+
+
+
+`style-src` 지시어에 새 해시를 추가합니다.
+
+```astro
+---
+Astro.addStyleHash("sha512-styleHash");
+---
+```
+
+빌드 후, 이 페이지의 `` 요소는 기본 `style-src` 지시어에 해시를 추가합니다.
+
+```html
+
+```
+
+
+### `insertScriptResource`
+
+
+ **타입:** `(resource: string) => void`
+
+
+
+`script-src` 지시어에 사용할 새 유효한 소스를 삽입합니다.
+
+
+```astro
+---
+Astro.insertScriptResource("'https://scripts.cdn.example.com'");
+---
+```
+
+빌드 후, 이 페이지의 `` 요소는 기본 `script-src` 지시어에 소스를 추가합니다.
+
+```html
+
+```
+
+### `addScriptHash`
+
+
+ **타입:** `(hash: CspHash) => void`
+
+
+
+`script-src` 지시어에 새 해시를 추가합니다.
+
+
+```astro
+---
+Astro.addScriptHash("sha512-scriptHash");
+---
+```
+
+빌드 후, 이 페이지의 `` 요소는 기본 `script-src` 지시어에 해시를 추가합니다.
+
+```html
+
+```