Add webpack compilation object to processfn (#81)

Allowing the ability to manipulate the webpack build to add an asset file to the build via the `compilation` object. 
See readme for an example on how to generate a file that can be included by NGINX.

Author: samsaggace

README.md

@@ -17,15 +17,15 @@ All inline JS and CSS will be hashed and inserted into the policy.
 
 Install the plugin with npm:
 
-```
+```bash
 npm i --save-dev csp-html-webpack-plugin
 ```
 
 ## Basic Usage
 
 Include the following in your webpack config:
 
-```
+```js
 const HtmlWebpackPlugin = require('html-webpack-plugin');
 const CspHtmlWebpackPlugin = require('csp-html-webpack-plugin');
 
@@ -90,6 +90,7 @@ This `CspHtmlWebpackPlugin` accepts 2 params with the following structure:
       - `builtPolicy`: a `string` containing the completed policy;
       - `htmlPluginData`: the `HtmlWebpackPlugin` `object`;
       - `$`: the `cheerio` object of the html file currently being processed
+      - `compilation`: Internal webpack object to manipulate the build
 
 ### `HtmlWebpackPlugin`
 
@@ -105,6 +106,7 @@ The plugin also adds a new config option onto each `HtmlWebpackPlugin` instance:
       - `builtPolicy`: a `string` containing the completed policy;
       - `htmlPluginData`: the `HtmlWebpackPlugin` `object`;
       - `$`: the `cheerio` object of the html file currently being processed
+      - `compilation`: Internal webpack object to manipulate the build
 
 ### Order of Precedence:
 
@@ -125,7 +127,7 @@ In the case where a config object is defined in multiple places, it will be merg
 
 #### Default Policy:
 
-```
+```js
 {
   'base-uri': "'self'",
   'object-src': "'none'",
@@ -136,7 +138,7 @@ In the case where a config object is defined in multiple places, it will be merg
 
 #### Default Additional Options:
 
-```
+```js
 {
   enabled: true
   hashingMethod: 'sha256',
@@ -154,7 +156,7 @@ In the case where a config object is defined in multiple places, it will be merg
 
 #### Full Default Configuration:
 
-```
+```js
 new HtmlWebpackPlugin({
   cspPlugin: {
     enabled: true,
@@ -195,7 +197,49 @@ new CspHtmlWebpackPlugin({
   processFn: defaultProcessFn  // defined in the plugin itself
 })
 ```
+## Advanced Usage
+### Generating a file containing the CSP directives
 
+Some specific directives require the CSP to be sent to the client via a response header (e.g. `report-uri` and `report-to`)
+You can set your own `processFn` callback to make this happen.
+
+#### nginx
+
+In your webpack config:
+
+```js
+const RawSource = require('webpack-sources').RawSource;
+
+function generateNginxHeaderFile(
+  builtPolicy,
+  _htmlPluginData,
+  _obj,
+  compilation
+) {
+  const header =
+    'add_header Content-Security-Policy "' +
+    builtPolicy +
+    '; report-uri /csp-report/ ";';
+  compilation.emitAsset('nginx-csp-header.conf', new RawSource(header));
+}
+
+module.exports = {
+  {...},
+  plugins: [
+    new CspHtmlWebpackPlugin(
+      {...}, {
+      processFn: generateNginxHeaderFile
+    })
+  ]
+};
+```
+In your nginx config:
+```nginx
+location / {
+  ...
+  include /path/to/webpack/output/nginx-csp-header.conf
+}
+```
 ## Contribution
 
 Contributions are most welcome! Please see the included contributing file for more information.

package.json

@@ -48,6 +48,7 @@
     "jest": "^26.6.3",
     "memory-fs": "^0.5.0",
     "prettier": "^2.2.1",
-    "webpack": "^5.10.1"
+    "webpack": "^5.10.1",
+    "webpack-sources": "^2.2.0"
   }
 }

plugin.jest.js

@@ -1,6 +1,7 @@
 const path = require('path');
 const crypto = require('crypto');
 const HtmlWebpackPlugin = require('html-webpack-plugin');
+const { RawSource } = require('webpack-sources');
 const {
   WEBPACK_OUTPUT_DIR,
   createWebpackConfig,
@@ -885,6 +886,7 @@ describe('CspHtmlWebpackPlugin', () => {
         expect(processFn).toHaveBeenCalledWith(
           builtPolicy,
           expect.anything(),
+          expect.anything(),
           expect.anything()
         );
 
@@ -932,12 +934,57 @@ describe('CspHtmlWebpackPlugin', () => {
         expect(processFn).toHaveBeenCalledWith(
           index1BuiltPolicy,
           expect.anything(),
+          expect.anything(),
           expect.anything()
         );
 
         done();
       });
     });
+
+    it('Allows to generate a file containing the policy', (done) => {
+      function generateCSPFile(
+        builtPolicy,
+        _htmlPluginData,
+        _obj,
+        compilation
+      ) {
+        compilation.emitAsset('csp.conf', new RawSource(builtPolicy));
+      }
+      const index1BuiltPolicy = `base-uri 'self'; object-src 'none'; script-src 'unsafe-inline' 'self' 'unsafe-eval' 'sha256-ixjZMYNfWQWawUHioWOx2jBsTmfxucX7IlwsMt2jWvc=' 'nonce-mockedbase64string-1' 'nonce-mockedbase64string-2'; style-src 'unsafe-inline' 'self' 'unsafe-eval' 'sha256-MqG77yUiqBo4MMVZAl09WSafnQY4Uu3cSdZPKxaf9sQ=' 'nonce-mockedbase64string-3'`;
+
+      const config = createWebpackConfig([
+        new HtmlWebpackPlugin({
+          filename: path.join(WEBPACK_OUTPUT_DIR, 'index-1.html'),
+          template: path.join(
+            __dirname,
+            'test-utils',
+            'fixtures',
+            'with-script-and-style.html'
+          ),
+        }),
+        new CspHtmlWebpackPlugin(
+          {},
+          {
+            processFn: generateCSPFile,
+          }
+        ),
+      ]);
+
+      webpackCompile(config, (csps, selectors, fileSystem) => {
+        const cspFileContent = fileSystem
+          .readFileSync(path.join(WEBPACK_OUTPUT_DIR, 'csp.conf'), 'utf8')
+          .toString();
+
+        // it won't exist in the html file since we overwrote processFn
+        expect(csps['index-1.html']).toBeUndefined();
+
+        // A file has been generated
+        expect(cspFileContent).toEqual(index1BuiltPolicy);
+
+        done();
+      });
+    });
   });
 
   describe('HTML parsing', () => {

plugin.js

@@ -311,7 +311,7 @@ class CspHtmlWebpackPlugin {
    * @param htmlPluginData
    * @param compileCb
    */
-  processCsp(htmlPluginData, compileCb) {
+  processCsp(compilation, htmlPluginData, compileCb) {
     const $ = cheerio.load(htmlPluginData.html, {
       decodeEntities: false,
       _useHtmlParser2: true,
@@ -343,7 +343,7 @@ class CspHtmlWebpackPlugin {
       ),
     });
 
-    this.processFn(builtPolicy, htmlPluginData, $);
+    this.processFn(builtPolicy, htmlPluginData, $, compilation);
 
     return compileCb(null, htmlPluginData);
   }
@@ -360,7 +360,7 @@ class CspHtmlWebpackPlugin {
       );
       HtmlWebpackPlugin.getHooks(compilation).beforeEmit.tapAsync(
         'CspHtmlWebpackPlugin',
-        this.processCsp.bind(this)
+        this.processCsp.bind(this, compilation)
       );
     });
   }