# koa-csrf

> CSRF tokens for Koa

Latest version **5.0.1** (published 2022-07-02) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install koa-csrf
pnpm add koa-csrf
yarn add koa-csrf
bun add koa-csrf
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 5.0.1 |
| Published | 2022-07-02 |
| First published | 2013-11-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/koa-csrf) |
| Module format | CommonJS |
| Node | >= 14 |
| Dependencies | 3 |
| Unpacked size | 7.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 265 |
| Author | Jonathan Ong |
| Maintainers | coderhaoxin, dead-horse, niftylettuce, aaron, juliangruber, eivifj, dead_horse, stephenmathieson, tjholowaychuk, jongleberry, fengmk2, popomore, titanism |
| Keywords | cross, csrf, forgery, koa, koa2, koa@2, koa@next, koanext, middleware, next, request, security, site |

## Links

- npm: https://www.npmjs.com/package/koa-csrf
- Repository: https://github.com/koajs/csrf
- npm.io page: https://npm.io/package/koa-csrf

## Dependencies (3)

- [csrf](https://npm.io/package/csrf.md) ^3.1.0
- [multimatch](https://npm.io/package/multimatch.md) 5
- [is-string-and-not-blank](https://npm.io/package/is-string-and-not-blank.md) ^0.0.2

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 5.0.1 (latest) — 2022-07-02
- 5.0.0 — 2022-07-02
- 4.0.1 — 2022-07-02
- 4.0.0 — 2022-07-01
- 3.0.8 — 2019-09-09
- 3.0.7 — 2019-01-13
- 3.0.6 — 2017-05-08
- 3.0.5 — 2017-03-16
- 3.0.4 — 2016-10-02
- 3.0.3 — 2016-09-18
- 3.0.2 — 2016-09-12
- 2.5.0 — 2016-06-06
- 2.4.0 — 2015-10-31
- 2.3.0 — 2015-05-17
- 2.2.0 — 2015-05-17
- … 11 more at https://npm.io/package/koa-csrf/versions

## README

# koa-csrf

[![build status](https://github.com/koajs/csrf/actions/workflows/ci.yml/badge.svg)](https://github.com/koajs/csrf/actions/workflows/ci.yml)
[![build status](https://img.shields.io/travis/koajs/csrf.svg)](https://travis-ci.com/koajs/csrf)
[![code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
[![made with lass](https://img.shields.io/badge/made_with-lass-95CC28.svg)](https://lass.js.org)
[![license](https://img.shields.io/github/license/koajs/csrf.svg)](LICENSE)

> CSRF tokens for Koa

> **NOTE:** As of v5.0.0+ `ctx.csrf`, `ctx_csrf`, and `ctx.response.csrf` are removed – instead use `ctx.state._csrf`.  Furthermore we have dropped `invalidTokenMessage` and `invalidTokenStatusCode` in favor of an `errorHandler` function option.


## Table of Contents

* [Install](#install)
* [Usage](#usage)
* [Options](#options)
* [Contributors](#contributors)
* [License](#license)


## Install

[npm][]:

```sh
npm install koa-csrf
```


## Usage

1. Add middleware in Koa app (see [options](#options) below):

   ```js
   const Koa = require('koa');
   const bodyParser = require('koa-bodyparser');
   const session = require('koa-generic-session');
   const convert = require('koa-convert');
   const CSRF = require('koa-csrf');

   const app = new Koa();

   // set the session keys
   app.keys = [ 'a', 'b' ];

   // add session support
   app.use(convert(session()));

   // add body parsing
   app.use(bodyParser());

   // add the CSRF middleware
   app.use(new CSRF());

   // your middleware here (e.g. parse a form submit)
   app.use((ctx, next) => {
     if (![ 'GET', 'POST' ].includes(ctx.method))
       return next();
     if (ctx.method === 'GET') {
       ctx.body = ctx.state._csrf;
       return;
     }
     ctx.body = 'OK';
   });

   app.listen();
   ```

2. Add the CSRF token in your template forms:

   > Jade Template:

   ```jade
   form(action='/register', method='POST')
     input(type='hidden', name='_csrf', value=_csrf)
     input(type='email', name='email', placeholder='Email')
     input(type='password', name='password', placeholder='Password')
     button(type='submit') Register
   ```

   > EJS Template:

   ```ejs
   <form action="/register" method="POST">
     <input type="hidden" name="_csrf" value="<%= _csrf %>" />
     <input type="email" name="email" placeholder="Email" />
     <input type="password" name="password" placeholder="Password" />
     <button type="submit">Register</button>
   </form>
   ```


## Options

* `errorHandler` (Function) - defaults to a function that returns `ctx.throw(403, 'Invalid CSRF token')`
* `excludedMethods` (Array) - defaults to `[ 'GET', 'HEAD', 'OPTIONS' ]`
* `disableQuery` (Boolean) - defaults to `false`
* `ignoredPathGlobs` (Array) - defaults to an empty Array, but you can pass an Array of glob paths to ignore


## Contributors

| Name            | Website                           |
| --------------- | --------------------------------- |
| **Nick Baugh**  | <https://github.com/niftylettuce> |
| **Imed Jaberi** | <https://www.3imed-jaberi.com/>   |


## License

[MIT](LICENSE) © [Jonathan Ong](http://jongleberry.com)


##

[npm]: https://www.npmjs.com/

---
_Source: https://npm.io/package/koa-csrf · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._