hwp-csp-plugin

Content Security Policy plugin for html-webpack-plugin

Usage no npm install needed!

<script type="module">
  import hwpCspPlugin from 'https://cdn.skypack.dev/hwp-csp-plugin';
</script>

README

hwp-csp-plugin

Build & Test CI

Plugin to add Content-Security-Policy to HTML files generated by html-webpack-plugin

It was heavily inspired by csp-html-webpack-plugin, but it operates a bit differently.

Installation

npm i -D hwp-csp-plugin

Usage

import { HwpCspPlugin } from 'hwp-csp-plugin';

// Webpack configuration object
export default {

    plugins: [
        new HtmlWebpackPlugin({ /* ... */ }),
        new HwpCspPlugin(/* options */),
    ],
};

To configure the plugin, pass an object with the following keys to its constructor (all keys are optional):

  • enabled (boolean, defaults to true): whether to enable the plugin;
  • policy (Record<string, string | string[]>): Content Security Policy; keys are <directives>, values are <values>. Values can be a string ("'self' https:") or arrays (["'self'", 'https:'])
  • hashFunc (one of sha256, sha384 (default), sha512): hash function to generate hashes of inline scripts / styles;
  • hashEnabled: can be either boolean or an object with the following properties:
    • script (boolean, defaults to true): whether to generate hashes of inline scripts;
    • style (boolean, defaults to true): whether to generate hashes of inline styles;
  • addIntegrity (boolean, defaults to false): whether to add integrity attribute to inline scripts and styles (controlled by hashEnabled option).

Differences to csp-html-webpack-plugin

  1. HwpCspPlugin intentionally does not support nonces. Nonces, by definition, must be used only once and be unique for every request.
  2. HwpCspPlugin does not support html-webpack-plugin < 4.x
  3. HwpCspPlugin does not enforce a default content security policy.
  4. HwpCspPlugin uses a subjectively simpler approach to configuration and lets you shoot yourself in the foot.
  5. HwpCspPlugin is written in TypeScript (not that it is a killer feature, but it hopefully simplifies maintenance)

Things to Do

  • Currently the plugin removes existing <meta http-equiv="Content-Security-Policy"/> metatags. However, it could be possible to have multiple CSPs. This needs to be investigated, and if so, then this behavior should be configurable;
  • Add callbacks allowing the user to modify the CSP before it is written to the file;
  • Consider unsafe-hashes and script-src-attr / style-src-attr.