express-csp

express-csp
===========

[![npm Version][npm-badge]][npm]
[![Build Status][travis-badge]][travis]

Usage
-----

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

API
---

$3

``js
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.

`html

`

##### 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.

- base-uri
- child-src
- connect-src
- default-src
- font-src
- form-action
- frame-ancestors
- img-src
- media-src
- object-src
- plugin-types
- script-src
- style-src
- report-uri


#### 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.




$3

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

At the app level
`js
app.signScript('foo();');
`

Enables foo(); throughout the app
`html

`
At the response level
`js
app.route('/').get(function (req, res) {
res.signScript('bar();');
});
`
Enables bar(); for the route only.
`html

`

These will not work with the above examples.
`html



`

$3

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

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

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

$3


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.

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

$3

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

[LICENSE file]: https://github.com/yahoo/express-csp/blob/master/LICENSE
[travis]: https://travis-ci.org/yahoo/express-csp
[travis-badge]: http://img.shields.io/travis/yahoo/express-csp.svg?style=flat-square
[npm]: https://www.npmjs.org/package/express-csp
[npm-badge]: https://img.shields.io/npm/v/express-csp.svg?style=flat-square