79 lines
2.6 KiB
Markdown
79 lines
2.6 KiB
Markdown
|
# 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]
|
||
|
|
|
||
|
|
Node.js [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection middleware.
|
||
|
|
|
||
|
|
Requires either a session middleware or [cookie-parser](https://github.com/expressjs/cookie-parser) to be initialized first.
|
||
|
|
- [session](https://github.com/expressjs/session)
|
||
|
|
- [cookie-session](https://github.com/expressjs/cookie-session)
|
||
|
|
|
||
|
|
### Install
|
||
|
|
|
||
|
|
```sh
|
||
|
|
$ npm install csurf
|
||
|
|
```
|
||
|
|
|
||
|
|
## API
|
||
|
|
|
||
|
|
```js
|
||
|
|
var csrf = require('csurf')
|
||
|
|
```
|
||
|
|
|
||
|
|
### csrf(options)
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
- `value` a function accepting the request, returning the token.
|
||
|
|
- The default function checks four possible token locations:
|
||
|
|
- `_csrf` parameter in `req.body` generated by the `body-parser` middleware.
|
||
|
|
- `_csrf` parameter in `req.query` generated by `query()`.
|
||
|
|
- `x-csrf-token` and `x-xsrf-token` header fields.
|
||
|
|
- `cookie` set to a truthy value to enable cookie-based instead of session-based csrf secret storage.
|
||
|
|
- If `cookie` is an object, these options can be configured, otherwise defaults are used:
|
||
|
|
- `key` the name of the cookie to use (defaults to `_csrf`) to store the csrf secret
|
||
|
|
- any other [res.cookie](http://expressjs.com/4x/api.html#res.cookie) options can be set
|
||
|
|
- `ignoreMethods` An array of the methods CSRF token checking will disabled.
|
||
|
|
(default: `['GET', 'HEAD', 'OPTIONS']`)
|
||
|
|
|
||
|
|
### req.csrfToken()
|
||
|
|
|
||
|
|
Lazy-loads the token associated with the request.
|
||
|
|
|
||
|
|
## Example
|
||
|
|
|
||
|
|
```js
|
||
|
|
var express = require('express')
|
||
|
|
var csrf = require('csurf')
|
||
|
|
|
||
|
|
var app = express()
|
||
|
|
app.use(csrf())
|
||
|
|
|
||
|
|
// 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('session has expired or form tampered with')
|
||
|
|
})
|
||
|
|
```
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
[MIT](LICENSE)
|
||
|
|
|
||
|
|
[npm-image]: https://img.shields.io/npm/v/csurf.svg?style=flat
|
||
|
|
[npm-url]: https://npmjs.org/package/csurf
|
||
|
|
[travis-image]: https://img.shields.io/travis/expressjs/csurf.svg?style=flat
|
||
|
|
[travis-url]: https://travis-ci.org/expressjs/csurf
|
||
|
|
[coveralls-image]: https://img.shields.io/coveralls/expressjs/csurf.svg?style=flat
|
||
|
|
[coveralls-url]: https://coveralls.io/r/expressjs/csurf?branch=master
|
||
|
|
[downloads-image]: https://img.shields.io/npm/dm/csurf.svg?style=flat
|
||
|
|
[downloads-url]: https://npmjs.org/package/csurf
|