Экспериментальная политика безопасности контента (CSP)

Тип: boolean | object
По умолчанию: false

Добавлено в: astro@5.9.0

Включает поддержку Политики безопасности контента (CSP), чтобы помочь минимизировать определенные типы угроз безопасности, контролируя, какие ресурсы документу разрешено загружать. Это обеспечивает дополнительную защиту от атак межсайтового скриптинга (XSS).

Включение этой функции добавляет дополнительную безопасность к обработке Astro обработанных и объединенных скриптов и стилей по умолчанию и позволяет вам дополнительно настраивать эти и другие типы контента.

Эта экспериментальная функция CSP имеет некоторые ограничения. Встроенные (inline) скрипты не поддерживаются «из коробки», но вы можете предоставить свои собственные хеши для внешних и встроенных скриптов. Переходы (view transitions) Astro с использованием <ClientRouter /> не поддерживаются, но вы можете рассмотреть возможность перехода на нативный браузерный API View Transition вместо этого, если вы не используете улучшения Astro для нативных API View Transitions и Navigation.

Чтобы включить эту функцию, добавьте экспериментальный флаг в вашу конфигурацию Astro:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: true
  }
});

При включении Astro добавит элемент <meta> внутри элемента <head> каждой страницы.

Этот элемент будет иметь атрибут http-equiv="content-security-policy", а атрибут content будет предоставлять значения для директив script-src и style-src на основе скриптов и стилей, используемых на странице.

<head>
  <meta
    http-equiv="content-security-policy"
    content="
      script-src 'self' 'sha256-somehash';
      style-src 'self' 'sha256-somehash';
    "
  >
</head>

Конфигурация

Вы можете дополнительно настроить элемент <meta>, включив эту функцию с объектом конфигурации, который включает дополнительные опции.

`algorithm`

Тип: 'SHA-256' | 'SHA-512' | 'SHA-384'
По умолчанию: 'SHA-256'

Добавлено в: astro@5.9.0

Хеш-функция для использования при генерации хешей стилей и скриптов, создаваемых Astro.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      algorithm: 'SHA-512'
    }
  }
});

`directives`

Тип: CspDirective[]
По умолчанию: []

Добавлено в: astro@5.9.0

Список директив CSP, определяющий допустимые источники для конкретных типов контента.

Хотя Astro должен контролировать директивы script-src и style-src, можно контролировать другие директивы CSP с помощью поля csp.directives. Эти директивы добавляются ко всем страницам. Принимает список типобезопасных директив:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      directives: [
        "default-src 'self'",
        "img-src 'self' https://images.cdn.example.com"
      ]
    }
  }
});

После сборки элемент <meta> добавит ваши директивы в значение content наряду с директивами Astro по умолчанию:

<meta
  http-equiv="content-security-policy"
  content="
    default-src 'self';
    img-src 'self' 'https://images.cdn.example.com';
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
  "
>

`styleDirective` и `scriptDirective`

Тип: object
По умолчанию: {}

Добавлено в: astro@5.9.0

Объекты конфигурации, позволяющие переопределить источники по умолчанию для директив style-src и script-src с помощью свойства resources или предоставить дополнительные хеши для рендеринга.

Эти свойства добавляются ко всем страницам и полностью переопределяют ресурсы Astro по умолчанию, а не добавляются к ним. Поэтому вы должны явно указать любые значения по умолчанию, которые вы хотите включить.

`resources`

Тип: string[]
По умолчанию: []

Добавлено в: astro@5.9.0

Список допустимых источников для директив script-src и style-src, включая значения для подклассов.

Директивы script-src и style-src обрабатываются Astro по умолчанию и используют ресурс 'self'. Это означает, что скрипты и стили могут быть загружены только с текущего хоста (обычно текущего веб-сайта).

Чтобы переопределить источник по умолчанию, вы можете предоставить список ресурсов вместо этого. Он не будет включать 'self' по умолчанию, и его необходимо включить в этот список, если вы хотите его сохранить. Эти ресурсы добавляются ко всем страницам.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      styleDirective: {
        resources: [
          "'self'",
          "https://styles.cdn.example.com"
        ]
      },
      scriptDirective: {
        resources: [
          "https://cdn.example.com"
        ]
      }
    }
  }
});

После сборки элемент <meta> вместо этого применит ваши источники к директивам style-src и script-src:

<head>
  <meta
    http-equiv="content-security-policy"
    content="
      script-src https://cdn.example.com 'sha256-somehash';
      style-src 'self' https://styles.cdn.example.com 'sha256-somehash';
    "
  >
</head>

Добавление значений для подклассов

Вы также можете использовать это поле для добавления допустимых значений, принадлежащих script-src-attr, script-src-elem, style-src-attr и style-src-elem, таких как unsafe-hashes и unsafe-inline.

Например, если у вас есть внешняя библиотека, которая добавляет скрипты или встроенные стили к некоторым HTML-элементам страницы, вы можете добавить unsafe-inline, чтобы сообщить браузеру, что их безопасно рендерить.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      styleDirective: {
        resources: [
          "'unsafe-inline'"
        ]
      },
      scriptDirective: {
        resources: [
          "'unsafe-inline'"
        ]
      }
    }
  }
});

После сборки директивы style-src и script-src будут содержать ресурс 'unsafe-line':

<head>
  <meta
    http-equiv="content-security-policy"
    content="
      script-src 'unsafe-line';
      style-src 'unsafe-line';
    "
  >
</head>

Несколько ресурсов

Когда ресурсы вставляются несколько раз или из нескольких источников (например, определены в вашей конфигурации csp и добавлены с использованием API выполнения CSP), Astro удалит любые дубликаты и объединит новые.

В следующем примере директивы img-src https://global.cdn.example.org и default-src https://global.cdn.example.org установлены в конфигурации csp и будут применены ко всем страницам.

export default defineConfig({
  experimental: {
    csp: {
      directives: [
        "img-src https://global.cdn.example.org",
        "default-src https://global.cdn.example.org"
      ]
    }
  }
})

Кроме того, на отдельной странице ресурсы img-src https://vendor.cdn.example.org/ и default-src https://global.cdn.example.org/ https://vendor.cdn.example.org/ добавляются с использованием Astro.csp.insertDirective.

---
Astro.csp.insertDirective("img-src https://vendor.cdn.example.org")
Astro.csp.insertDirective("default-src https://global.cdn.example.org https://vendor.cdn.example.org")
---

Во время сборки ресурсы директив img-src и default-src для страницы index.html объединяются и дедуплицируются для создания соответствующих заголовков.

<head>
  <meta
    http-equiv="content-security-policy"
    content="
        img-src https://global.cdn.example.org https://vendor.cdn.example.org;
        default-src https://global.cdn.example.org https://vendor.cdn.example.org;
    "
  >
</head>

`hashes`

Тип: CspHash[]
По умолчанию: []

Добавлено в: astro@5.9.0

Список дополнительных хешей для рендеринга.

Если у вас есть внешние скрипты или стили, которые не генерируются Astro, или встроенные скрипты, эта опция конфигурации позволяет предоставить дополнительные хеши для рендеринга.

Вы должны предоставить хеши, которые начинаются с sha384-, sha512- или sha256-. Другие значения вызовут ошибку валидации. Эти хеши добавляются ко всем страницам.

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"
        ]
      }
    }
  }
});

После сборки элемент <meta> будет включать ваши дополнительные хеши в директивах script-src и style-src:

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha384-scriptHash' 'sha512-scriptHash' 'sha256-scriptHash' 'sha256-generatedByAstro';
    style-src 'self' 'sha384-styleHash' 'sha512-styleHash' 'sha256-styleHash' 'sha256-generatedByAstro';
  "
>

`strictDynamic`

Тип: boolean
По умолчанию: false

Добавлено в: astro@5.9.0

Включает ключевое слово strict-dynamic для поддержки динамической инъекции скриптов.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      scriptDirective: {
        strictDynamic: true
      }
    }
  }
});

API выполнения

Вы можете настраивать элемент <meta> для каждой страницы с помощью API выполнения, доступных из глобального объекта Astro внутри компонентов .astro или типа APIContext в эндпоинтах и мидлваре.

`csp.insertDirective`

Тип: (directive: CspDirective) => void

Добавлено в: astro@5.9.0

Добавляет одну директиву на текущую страницу. Вы можете вызывать этот метод несколько раз для добавления дополнительных директив.

---
Astro.csp.insertDirective("default-src 'self'");
Astro.csp.insertDirective("img-src 'self' https://images.cdn.example.com");
---

После сборки элемент <meta> для этой отдельной страницы будет включать ваши дополнительные директивы наряду с существующими директивами script-src и style-src:

<meta
  http-equiv="content-security-policy"
  content="
    default-src 'self';
    img-src 'self' https://images.cdn.example.com;
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
  "
>

`csp.insertStyleResource`

Тип: (resource: string) => void

Добавлено в: astro@5.9.0

Вставляет новый ресурс для использования в директиве style-src.

---
Astro.csp.insertStyleResource("https://styles.cdn.example.com");
---

После сборки элемент <meta> для этой отдельной страницы добавит ваш источник в директиву style-src по умолчанию:

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha256-somehash';
    style-src https://styles.cdn.example.com 'sha256-somehash';
  "
>

`csp.insertStyleHash`

Тип: (hash: CspHash) => void

Добавлено в: astro@5.9.0

Добавляет новый хеш в директиву style-src.

---
Astro.csp.insertStyleHash("sha512-styleHash");
---

После сборки элемент <meta> для этой отдельной страницы добавит ваш хеш в директиву style-src по умолчанию:

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash' 'sha512-styleHash';
  "
>

`csp.insertScriptResource`

Тип: (resource: string) => void

Добавлено в: astro@5.9.0

Вставляет новый допустимый источник для использования в директиве script-src.

---
Astro.csp.insertScriptResource("https://scripts.cdn.example.com");
---

После сборки элемент <meta> для этой отдельной страницы добавит ваш источник в директиву script-src по умолчанию:

<meta
  http-equiv="content-security-policy"
  content="
    script-src https://scripts.cdn.example.com 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
  "
>

`csp.insertScriptHash`

Тип: (hash: CspHash) => void

Добавлено в: astro@5.9.0

Добавляет новый хеш в директиву script-src.

---
Astro.csp.insertScriptHash("sha512-scriptHash");
---

После сборки элемент <meta> для этой отдельной страницы добавит ваш хеш в директиву script-src по умолчанию:

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha256-somehash' 'sha512-styleHash';
    style-src 'self' 'sha256-somehash';
  "
>

Экспериментальная политика безопасности контента (CSP)

Конфигурация

algorithm

directives

styleDirective и scriptDirective

resources

Добавление значений для подклассов

Несколько ресурсов

hashes

strictDynamic

API выполнения

csp.insertDirective

csp.insertStyleResource

csp.insertStyleHash

csp.insertScriptResource

csp.insertScriptHash

`algorithm`

`directives`

`styleDirective` и `scriptDirective`

`resources`

`hashes`

`strictDynamic`

`csp.insertDirective`

`csp.insertStyleResource`

`csp.insertStyleHash`

`csp.insertScriptResource`

`csp.insertScriptHash`