@jackdbd/eleventy-plugin-content-security-policy

Eleventy plugin that writes Content-Security-Policy and Content-Security-Policy-Report-Only headers to a _headers file when Eleventy builds your site.

• Installation
• About
• Usage
• Configuration
• Troubleshooting
• Dependencies
• License

Installation

npm install @jackdbd/eleventy-plugin-content-security-policy

Note: this library was tested on Node.js >=18. It might work on other Node.js versions though.

About

Hosting providers like Cloudflare Pages and Netlify allow to define custom response headers in a plain text file called _headers. This file must be placed in the publish directory of your site (e.g. usually _site for a Eleventy site).

This plugin allows you to define a Content-Security-Policy (CSP) or a Content-Security-Policy-Report-Only header in your Eleventy configuration file, and then it automatically writes those headers into your _headers file when you build your site.

Usage

In your Eleventy config file:

import { contentSecurityPolicyPlugin } from '@jackdbd/eleventy-plugin-content-security-policy'

export default function (eleventyConfig) {
  // some other eleventy configuration...

  // use the default CSP directives (not recommended)...
  eleventyConfig.addPlugin(contentSecurityPolicyPlugin)

  // ...or define your CSP directives
  eleventyConfig.addPlugin(contentSecurityPolicyPlugin, {
    allowDeprecatedDirectives: true,
    
    directives: {
      'base-uri': ['self'],

      // allow only self-hosted fonts (i.e. fonts hosted on this origin)
      'font-src': ['self'],

      // allow scripts hosted on this origin, on plausible.io (analytics),
      // cloudflareinsights.com (analytics), unpkg.com (preact)
      'script-src-elem': [
        'self',
        'https://plausible.io/js/plausible.js',
        'https://static.cloudflareinsights.com/beacon.min.js',
        'https://unpkg.com/htm/preact/standalone.module.js'
      ],

      // allow CSS hosted on this origin, and inline styles that match a sha256
      // hash automatically computed at build time by this 11ty plugin.
      // See also here for the pros and cons of 'unsafe-inline'
      // https://stackoverflow.com/questions/30653698/csp-style-src-unsafe-inline-is-it-worth-it
      'style-src-elem': ['self', 'sha256'],
    },

    // Only .html files should be served with the Content-Security-Policy header. Avoid header bloat by making sure that other files are not served with Content-Security-Policy header.
    globPatternsDetach: ['/*.png'],

    includePatterns: ['/**/**.html']
  })

  // some other eleventy configuration...
}

Configuration

Refer also to the library @jackdbd/content-security-policy for the configuration.

| Option | Default | Explanation | | --- | --- | --- | | allowDeprecatedDirectives | false | whether deprecated directives should be allowed or not. | | directives | {} | Directives for the Content-Security-Policy (or Content-Security-Policy-Report-Only) header. | | excludePatterns | [] | Files that match these patterns will not be searched. | | globPatterns | ['/', '/*/'] | Files that match these patterns will be searched. | | globPatternsDetach | [] | Files that match these patterns will not be served with the Content-Security-Policy (or Content-Security-Policy-Report-Only) header. | | includePatterns | ['/**/**.html'] | Files that match these patterns will be served with the Content-Security-Policy (or Content-Security-Policy-Report-Only) header. | | jsonRecap | false | whether to write a JSON containing the configuration of this plugin. This can useful for troubleshooting the CSP and/or to consume the CSP with some other tool (e.g. send a Telegram message containing the current CSP directives). | | reportOnly | false | whether the policy should be applied to the Content-Security-Policy header, or to the Content-Security-Policy-Report-Only header. |

Troubleshooting

This plugin uses the debug library for logging. You can control what's logged using the DEBUG environment variable.

For example, if you set your environment variables in a .envrc file, you can do:

# print all logging statements
export DEBUG=11ty-plugin:*

Dependencies

| Package | Version | |---|---| | @jackdbd/content-security-policy | 3.0.0-canary.1 | | @jackdbd/hosting-utils | 1.0.0-canary.1 | | zod | ^3.23.0 | | zod-validation-error | ^3.1.0 |

⚠️ Peer Dependencies

This package defines 2 peer dependencies.

| Peer | Version range | |---|---| | @11ty/eleventy | >=2.0.0 or 3.0.0-alpha.6 | | debug | >=4.0.0 |

License

© 2022 - 2024 Giacomo Debidda // MIT License