express-csp

Usage

This is an Express extension which allows you to set the content-security-policy for your Express Application.

API

extend

var csp = require('express-csp');

var app = express();

csp.extend(app, {
    policy: {
        directives: {
            'default-src': ['self', 'https://*.foo.com'],
            'script-src': ['*.apis.bar.com']
        }
    },
    reportPolicy: {
        useScriptNonce: true,
        useStyleNonce: true,
        directives: {
            'default-src': ['self', 'https://*.foo.com'],
            'script-src': ['*.apis.bar.com'],
            'plugin-types': ['application/pdf']
        }
    }
});

The extend method takes two arguments. A reference to the express application, app, and a config object containing the following properties:

policy

An object containing necessary information to generate policy directives to be added to the content-security-policy header. The policy object can contain the following possible properties:

useScriptNonce

When set to true, a nonce will be generated for the 'script-src' directive of each response and made available as the res.locals.cspToken value. This value can then be used in your templates to allow for specified inline script blocks. If useStyleNonce is also true, the same token will be added to the 'style-src' directive and the same token will be available for inline style blocks.

useStyleNonce

When set to true, a nonce will be generated for the 'style-src' directive of each response and made available as the res.locals.cspToken value. This value can then be used in your templates to allow for specified inline script and style blocks. If useScriptNonce is also true, the same token will be added to the 'script-src' directive and the same token will be available for inline script blocks.

<script nonce="{{res.locals.cspToken}}">
foo();
</script>

directives

An object of key/value pairs representing CSP Policy Directives in which the keys refer to the directive name and the value is an array of rules to apply to that value.

reportPolicy

An object containing necessary information to generate policy directives to be added to the content-security-policy-report-only header. The reportPolicy object can contain the same properties specified for the policy object.

signScript

Generates and adds a valid hash to the script-src directive.

At the app level

app.signScript('foo();');

Enables foo(); throughout the app

<script>foo();</script>

At the response level

app.route('/').get(function (req, res) {
    res.signScript('bar();');
});

Enables bar(); for the route only.

<script>bar();</script>

These will not work with the above examples.

<script>
foo();
</script>

<script>
bar();
</script>

signStyle

Generates and adds a valid hash to the style-src directive.

app.signStyle('body{background-color:#eee}');

app.route('/').get(function (req, res) {
    res.signStyle('body{background-color:#eee}');
});

res.setPolicy

Allows policy to be set per request. The app level policy set in extend will be ignored when res.setPolicy is used. This method takes the same config object as the extend method.

app.get('/', function(req, res, next) {
    res.setPolicy({
        policy: {
            directives: {
                'script-src' : ['unsafe-inline', '*.foo.com']
            }
        },
        reportPolicy: {
            useNonce: true,
            directives: {
                'script-src' : ['*.foo.com']
            }
        }
    });
});

License

Code licensed under the BSD license. See LICENSE file file for terms.

adon-at-work/express-csp