Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pillarjs/csrf
Logic behind CSRF token creation and verification.
https://github.com/pillarjs/csrf
csrf javascript nodejs tokens
Last synced: 2 days ago
JSON representation
Logic behind CSRF token creation and verification.
- Host: GitHub
- URL: https://github.com/pillarjs/csrf
- Owner: pillarjs
- License: mit
- Created: 2014-06-08T21:46:35.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2024-06-02T17:16:24.000Z (6 months ago)
- Last Synced: 2024-11-04T01:33:02.303Z (11 days ago)
- Topics: csrf, javascript, nodejs, tokens
- Language: JavaScript
- Homepage:
- Size: 128 KB
- Stars: 299
- Watchers: 20
- Forks: 32
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- License: LICENSE
Awesome Lists containing this project
README
# CSRF
[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]
Logic behind CSRF token creation and verification.
Read [Understanding-CSRF](https://github.com/pillarjs/understanding-csrf)
for more information on CSRF. Use this module to create custom CSRF middleware.
Looking for a CSRF framework for your favorite framework that uses this
module?
* Express/connect: [csurf](https://www.npmjs.com/package/csurf) or
[alt-xsrf](https://www.npmjs.com/package/alt-xsrf)
* Koa: [koa-csrf](https://www.npmjs.com/package/koa-csrf) or
[koa-atomic-session](https://www.npmjs.com/package/koa-atomic-session)
### Install
```sh
$ npm install csrf
```
### TypeScript
This module includes a [TypeScript](https://www.typescriptlang.org/)
declaration file to enable auto complete in compatible editors and type
information for TypeScript projects.
## API
```js
var Tokens = require('csrf')
```
### new Tokens([options])
Create a new token generation/verification instance. The `options` argument is
optional and will just use all defaults if missing.
#### Options
Tokens accepts these properties in the options object.
##### saltLength
The length of the internal salt to use, in characters. Internally, the salt
is a base 62 string. Defaults to `8` characters.
##### secretLength
The length of the secret to generate, in bytes. Note that the secret is
passed around base-64 encoded and that this length refers to the underlying
bytes, not the length of the base-64 string. Defaults to `18` bytes.
#### tokens.create(secret)
Create a new CSRF token attached to the given `secret`. The `secret` is a
string, typically generated from the `tokens.secret()` or `tokens.secretSync()`
methods. This token is what you should add into HTML `` blocks and
expect the user's browser to provide back.
```js
var secret = tokens.secretSync()
var token = tokens.create(secret)
```
#### tokens.secret(callback)
Asynchronously create a new `secret`, which is a string. The secret is to
be kept on the server, typically stored in a server-side session for the
user. The secret should be at least per user.
```js
tokens.secret(function (err, secret) {
if (err) throw err
// do something with the secret
})
```
#### tokens.secret()
Asynchronously create a new `secret` and return a `Promise`. Please see
`tokens.secret(callback)` documentation for full details.
**Note**: To use promises in Node.js _prior to 0.12_, promises must be
"polyfilled" using `global.Promise = require('bluebird')`.
```js
tokens.secret().then(function (secret) {
// do something with the secret
})
```
#### tokens.secretSync()
A synchronous version of `tokens.secret(callback)`. Please see
`tokens.secret(callback)` documentation for full details.
```js
var secret = tokens.secretSync()
```
#### tokens.verify(secret, token)
Check whether a CSRF token is valid for the given `secret`, returning
a Boolean.
```js
if (!tokens.verify(secret, token)) {
throw new Error('invalid token!')
}
```
## License
[MIT](LICENSE)
[ci-image]: https://badgen.net/github/checks/pillarjs/csrf/master?label=ci
[ci-url]: https://github.com/pillarjs/csrf/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/pillarjs/csrf/master
[coveralls-url]: https://coveralls.io/r/pillarjs/csrf?branch=master
[node-image]: https://badgen.net/npm/node/csrf
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/csrf
[npm-url]: https://npmjs.org/package/csrf
[npm-version-image]: https://badgen.net/npm/v/csrf