vnfmarket/src/main/webapp/vnfmarket/node_modules/csurf/README.md

   1 # csurf
   2
   3 [![NPM Version][npm-image]][npm-url]
   4 [![NPM Downloads][downloads-image]][downloads-url]
   5 [![Build status][travis-image]][travis-url]
   6 [![Test coverage][coveralls-image]][coveralls-url]
   7 [![Gratipay][gratipay-image]][gratipay-url]
   8
   9 Node.js [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection middleware.
  10
  11 Requires either a session middleware or [cookie-parser](https://www.npmjs.com/package/cookie-parser) to be initialized first.
  12
  13   * If you are setting the ["cookie" option](#cookie) to a non-`false` value,
  14     then you must use [cookie-parser](https://www.npmjs.com/package/cookie-parser)
  15     before this module.
  16   * Otherwise, you must use a session middleware before this module. For example:
  17     - [express-session](https://www.npmjs.com/package/express-session)
  18     - [cookie-session](https://www.npmjs.com/package/cookie-session)
  19
  20 If you have questions on how this module is implemented, please read
  21 [Understanding CSRF](https://github.com/pillarjs/understanding-csrf).
  22
  23 ## Installation
  24
  25 ```sh
  26 $ npm install csurf
  27 ```
  28
  29 ## API
  30
  31 ```js
  32 var csurf = require('csurf')
  33 ```
  34
  35 ### csurf([options])
  36
  37 Create a middleware for CSRF token creation and validation. This middleware
  38 adds a `req.csrfToken()` function to make a token which should be added to
  39 requests which mutate state, within a hidden form field, query-string etc.
  40 This token is validated against the visitor's session or csrf cookie.
  41
  42 #### Options
  43
  44 The `csurf` function takes an optional `options` object that may contain
  45 any of the following keys:
  46
  47 ##### cookie
  48
  49 Determines if the token secret for the user should be stored in a cookie
  50 or in `req.session`. Defaults to `false`.
  51
  52 When set to `true` (or an object of options for the cookie), then the module
  53 changes behavior and no longer uses `req.session`. This means you _are no
  54 longer required to use a session middleware_. Instead, you do need to use the
  55 [cookie-parser](https://www.npmjs.com/package/cookie-parser) middleware in
  56 your app before this middleware.
  57
  58 When set to an object, cookie storage of the secret is enabled and the
  59 object contains options for this functionality (when set to `true`, the
  60 defaults for the options are used). The options may contain any of the
  61 following keys:
  62
  63   - `key` - the name of the cookie to use to store the token secret
  64     (defaults to `'_csrf'`).
  65   - `path` - the path of the cookie (defaults to `'/'`).
  66   - any other [res.cookie](http://expressjs.com/4x/api.html#res.cookie)
  67     option can be set.
  68
  69 ##### ignoreMethods
  70
  71 An array of the methods for which CSRF token checking will disabled.
  72 Defaults to `['GET', 'HEAD', 'OPTIONS']`.
  73
  74 ##### sessionKey
  75
  76 Determines what property ("key") on `req` the session object is located.
  77 Defaults to `'session'` (i.e. looks at `req.session`). The CSRF secret
  78 from this library is stored and read as `req[sessionKey].csrfSecret`.
  79
  80 If the ["cookie" option](#cookie) is not `false`, then this option does
  81 nothing.
  82
  83 ##### value
  84
  85 Provide a function that the middleware will invoke to read the token from
  86 the request for validation. The function is called as `value(req)` and is
  87 expected to return the token as a string.
  88
  89 The default value is a function that reads the token from the following
  90 locations, in order:
  91
  92   - `req.body._csrf` - typically generated by the `body-parser` module.
  93   - `req.query._csrf` - a built-in from Express.js to read from the URL
  94     query string.
  95   - `req.headers['csrf-token']` - the `CSRF-Token` HTTP request header.
  96   - `req.headers['xsrf-token']` - the `XSRF-Token` HTTP request header.
  97   - `req.headers['x-csrf-token']` - the `X-CSRF-Token` HTTP request header.
  98   - `req.headers['x-xsrf-token']` - the `X-XSRF-Token` HTTP request header.
  99
 100 ## Example
 101
 102 ### Simple express example
 103
 104 The following is an example of some server-side code that generates a form
 105 that requires a CSRF token to post back.
 106
 107 ```js
 108 var cookieParser = require('cookie-parser')
 109 var csrf = require('csurf')
 110 var bodyParser = require('body-parser')
 111 var express = require('express')
 112
 113 // setup route middlewares
 114 var csrfProtection = csrf({ cookie: true })
 115 var parseForm = bodyParser.urlencoded({ extended: false })
 116
 117 // create express app
 118 var app = express()
 119
 120 // parse cookies
 121 // we need this because "cookie" is true in csrfProtection
 122 app.use(cookieParser())
 123
 124 app.get('/form', csrfProtection, function(req, res) {
 125   // pass the csrfToken to the view
 126   res.render('send', { csrfToken: req.csrfToken() })
 127 })
 128
 129 app.post('/process', parseForm, csrfProtection, function(req, res) {
 130   res.send('data is being processed')
 131 })
 132 ```
 133
 134 Inside the view (depending on your template language; handlebars-style
 135 is demonstrated here), set the `csrfToken` value as the value of a hidden
 136 input field named `_csrf`:
 137
 138 ```html
 139 <form action="/process" method="POST">
 140   <input type="hidden" name="_csrf" value="{{csrfToken}}">
 141
 142   Favorite color: <input type="text" name="favoriteColor">
 143   <button type="submit">Submit</button>
 144 </form>
 145 ```
 146
 147 ### Custom error handling
 148
 149 When the CSRF token validation fails, an error is thrown that has
 150 `err.code === 'EBADCSRFTOKEN'`. This can be used to display custom
 151 error messages.
 152
 153 ```js
 154 var bodyParser = require('body-parser')
 155 var cookieParser = require('cookie-parser')
 156 var csrf = require('csurf')
 157 var express = require('express')
 158
 159 var app = express()
 160 app.use(bodyParser.urlencoded({ extended: false }))
 161 app.use(cookieParser())
 162 app.use(csrf({ cookie: true }))
 163
 164 // error handler
 165 app.use(function (err, req, res, next) {
 166   if (err.code !== 'EBADCSRFTOKEN') return next(err)
 167
 168   // handle CSRF token errors here
 169   res.status(403)
 170   res.send('form tampered with')
 171 })
 172 ```
 173
 174 ## License
 175
 176 [MIT](LICENSE)
 177
 178 [npm-image]: https://img.shields.io/npm/v/csurf.svg
 179 [npm-url]: https://npmjs.org/package/csurf
 180 [travis-image]: https://img.shields.io/travis/expressjs/csurf/master.svg
 181 [travis-url]: https://travis-ci.org/expressjs/csurf
 182 [coveralls-image]: https://img.shields.io/coveralls/expressjs/csurf/master.svg
 183 [coveralls-url]: https://coveralls.io/r/expressjs/csurf?branch=master
 184 [downloads-image]: https://img.shields.io/npm/dm/csurf.svg
 185 [downloads-url]: https://npmjs.org/package/csurf
 186 [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
 187 [gratipay-url]: https://gratipay.com/dougwilson/