diff options
Diffstat (limited to 'node_modules/csurf/README.md')
| -rw-r--r-- | node_modules/csurf/README.md | 238 |
1 files changed, 0 insertions, 238 deletions
diff --git a/node_modules/csurf/README.md b/node_modules/csurf/README.md deleted file mode 100644 index dc88802..0000000 --- a/node_modules/csurf/README.md +++ /dev/null @@ -1,238 +0,0 @@ -# csurf - -[![NPM Version][npm-image]][npm-url] -[![NPM Downloads][downloads-image]][downloads-url] -[![Build status][travis-image]][travis-url] -[![Test coverage][coveralls-image]][coveralls-url] -[![Gratipay][gratipay-image]][gratipay-url] - -Node.js [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection middleware. - -Requires either a session middleware or [cookie-parser](https://www.npmjs.com/package/cookie-parser) to be initialized first. - - * If you are setting the ["cookie" option](#cookie) to a non-`false` value, - then you must use [cookie-parser](https://www.npmjs.com/package/cookie-parser) - before this module. - * Otherwise, you must use a session middleware before this module. For example: - - [express-session](https://www.npmjs.com/package/express-session) - - [cookie-session](https://www.npmjs.com/package/cookie-session) - -If you have questions on how this module is implemented, please read -[Understanding CSRF](https://github.com/pillarjs/understanding-csrf). - -## Installation - -```sh -$ npm install csurf -``` - -## API - -```js -var csurf = require('csurf') -``` - -### csurf([options]) - -Create a middleware for CSRF token creation and validation. This middleware -adds a `req.csrfToken()` function to make a token which should be added to -requests which mutate state, within a hidden form field, query-string etc. -This token is validated against the visitor's session or csrf cookie. - -#### Options - -The `csurf` function takes an optional `options` object that may contain -any of the following keys: - -##### cookie - -Determines if the token secret for the user should be stored in a cookie -or in `req.session`. Defaults to `false`. - -When set to `true` (or an object of options for the cookie), then the module -changes behavior and no longer uses `req.session`. This means you _are no -longer required to use a session middleware_. Instead, you do need to use the -[cookie-parser](https://www.npmjs.com/package/cookie-parser) middleware in -your app before this middleware. - -When set to an object, cookie storage of the secret is enabled and the -object contains options for this functionality (when set to `true`, the -defaults for the options are used). The options may contain any of the -following keys: - - - `key` - the name of the cookie to use to store the token secret - (defaults to `'_csrf'`). - - `path` - the path of the cookie (defaults to `'/'`). - - any other [res.cookie](http://expressjs.com/4x/api.html#res.cookie) - option can be set. - -##### ignoreMethods - -An array of the methods for which CSRF token checking will disabled. -Defaults to `['GET', 'HEAD', 'OPTIONS']`. - -##### sessionKey - -Determines what property ("key") on `req` the session object is located. -Defaults to `'session'` (i.e. looks at `req.session`). The CSRF secret -from this library is stored and read as `req[sessionKey].csrfSecret`. - -If the ["cookie" option](#cookie) is not `false`, then this option does -nothing. - -##### value - -Provide a function that the middleware will invoke to read the token from -the request for validation. The function is called as `value(req)` and is -expected to return the token as a string. - -The default value is a function that reads the token from the following -locations, in order: - - - `req.body._csrf` - typically generated by the `body-parser` module. - - `req.query._csrf` - a built-in from Express.js to read from the URL - query string. - - `req.headers['csrf-token']` - the `CSRF-Token` HTTP request header. - - `req.headers['xsrf-token']` - the `XSRF-Token` HTTP request header. - - `req.headers['x-csrf-token']` - the `X-CSRF-Token` HTTP request header. - - `req.headers['x-xsrf-token']` - the `X-XSRF-Token` HTTP request header. - -## Example - -### Simple express example - -The following is an example of some server-side code that generates a form -that requires a CSRF token to post back. - -```js -var cookieParser = require('cookie-parser') -var csrf = require('csurf') -var bodyParser = require('body-parser') -var express = require('express') - -// setup route middlewares -var csrfProtection = csrf({ cookie: true }) -var parseForm = bodyParser.urlencoded({ extended: false }) - -// create express app -var app = express() - -// parse cookies -// we need this because "cookie" is true in csrfProtection -app.use(cookieParser()) - -app.get('/form', csrfProtection, function(req, res) { - // pass the csrfToken to the view - res.render('send', { csrfToken: req.csrfToken() }) -}) - -app.post('/process', parseForm, csrfProtection, function(req, res) { - res.send('data is being processed') -}) -``` - -Inside the view (depending on your template language; handlebars-style -is demonstrated here), set the `csrfToken` value as the value of a hidden -input field named `_csrf`: - -```html -<form action="/process" method="POST"> - <input type="hidden" name="_csrf" value="{{csrfToken}}"> - - Favorite color: <input type="text" name="favoriteColor"> - <button type="submit">Submit</button> -</form> -``` - -### Ignoring Routes - -**Note** CSRF checks should only be disabled for requests that you expect to -come from outside of your website. Do not disable CSRF checks for requests -that you expect to only come from your website. An existing session, even if -it belongs to an authenticated user, is not enough to protect against CSRF -attacks. - -The following is an example of how to order your routes so that certain endpoints -do not check for a valid CSRF token. - -```js -var cookieParser = require('cookie-parser') -var csrf = require('csurf') -var bodyParser = require('body-parser') -var express = require('express') - -// create express app -var app = express() - -// create api router -var api = createApiRouter() - -// mount api before csrf is appended to the app stack -app.use('/api', api) - -// now add csrf and other middlewares, after the "/api" was mounted -app.use(bodyParser.urlencoded({ extended: false })) -app.use(cookieParser()) -app.use(csrf({ cookie: true })) - -app.get('/form', function(req, res) { - // pass the csrfToken to the view - res.render('send', { csrfToken: req.csrfToken() }) -}) - -app.post('/process', function(req, res) { - res.send('csrf was required to get here') -}) - -function createApiRouter() { - var router = new express.Router() - - router.post('/getProfile', function(req, res) { - res.send('no csrf to get here') - }) - - return router -} -``` - -### Custom error handling - -When the CSRF token validation fails, an error is thrown that has -`err.code === 'EBADCSRFTOKEN'`. This can be used to display custom -error messages. - -```js -var bodyParser = require('body-parser') -var cookieParser = require('cookie-parser') -var csrf = require('csurf') -var express = require('express') - -var app = express() -app.use(bodyParser.urlencoded({ extended: false })) -app.use(cookieParser()) -app.use(csrf({ cookie: true })) - -// error handler -app.use(function (err, req, res, next) { - if (err.code !== 'EBADCSRFTOKEN') return next(err) - - // handle CSRF token errors here - res.status(403) - res.send('form tampered with') -}) -``` - -## License - -[MIT](LICENSE) - -[npm-image]: https://img.shields.io/npm/v/csurf.svg -[npm-url]: https://npmjs.org/package/csurf -[travis-image]: https://img.shields.io/travis/expressjs/csurf/master.svg -[travis-url]: https://travis-ci.org/expressjs/csurf -[coveralls-image]: https://img.shields.io/coveralls/expressjs/csurf/master.svg -[coveralls-url]: https://coveralls.io/r/expressjs/csurf?branch=master -[downloads-image]: https://img.shields.io/npm/dm/csurf.svg -[downloads-url]: https://npmjs.org/package/csurf -[gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg -[gratipay-url]: https://gratipay.com/dougwilson/ |