express-recaptcha


[![Build Status][ci-image]][ci-url]
[![npm version][npm-version-image]][npm-version-url]

[Google recaptcha][google-recaptcha] middleware for express.

[express-recaptcha v2][express-recaptcha-v2] (previous middleware version).

Table of contents

- Installation
- Requirements
- Usage
- How to initialise
- options available/properties
- Render - recaptcha.middleware.render
- Render and override options - recaptcha.middleware.renderWith
- Verify - recaptcha.middleware.verify
- List of possible error codes
- Examples

Installation

``shell
npm install express-recaptcha --save
`

Requirements

- [Expressjs][expressjs]
- A [body parser][body-parser] middleware to get captcha data from query: (If you're using an express version older than 4.16.0)
`javascript
app.use(bodyParser.json())
app.use(bodyParser.urlencoded({ extended: true }))
`

Usage

$3

`javascript
var Recaptcha = require('express-recaptcha').RecaptchaV3
//import Recaptcha from 'express-recaptcha'
var recaptcha = new Recaptcha('SITE_KEY', 'SECRET_KEY')
//or with options
var options = { hl: 'de' }
var recaptcha = new Recaptcha('SITE_KEY', 'SECRET_KEY', options)
`

#### options available/properties:

| option | description |
|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| onload | The callback function that gets called when all the dependencies have loaded. |
| hl | Forces the widget to render in a specific language (Auto-detects if unspecified). |
| callback | In that callback you will call your backend to verify the given token. To be verified, the token needs to be posted with the key g-recaptcha-response (see the example folder) |
| action | homepage by default should only be alphanumeric More info on google's web site |
| checkremoteip | Adding support of remoteip verification (based on x-forwarded-for header or remoteAddress.Value could be true OR false (default false). |
| useRecaptchaDomain | Boolean. Sets www.recaptcha.net as the host; useful in instances where www.google.com may be blocked (as detailed in the reCaptcha docs) |

For more information, please refer to:

- reCaptcha - display
- reCaptcha - verify

$3

The middleware's render method sets the recaptcha property of res object, with the generated html code. Therefore, you can easily append recaptcha into your templates by passing res.recaptcha to the view:

`javascript
app.get('/', recaptcha.middleware.render, function (req, res) {
res.render('login', { captcha: res.recaptcha })
})
`

$3

Same as the render middleware method except that you can override the options in parameter :

`javascript
app.get(
'/',
recaptcha.middleware.renderWith({ hl: 'fr' }),
function (req, res) {
res.render('login', { captcha: res.recaptcha })
}
)
`

$3

The middleware's verify method sets the recaptcha property of req object, with validation information:

`javascript
app.post('/', recaptcha.middleware.verify, function (req, res) {
if (!req.recaptcha.error) {
// success code
} else {
// error code
}
})
`

The response verification is performed on params, query, and body properties for the req object.

Here is an example of a req.recaptcha response:

#### Example of verification response:

`javascript
{
error: string, // error code (see table below), null if success
data: {
hostname: string, // the site's hostname where the reCAPTCHA was solved
score: number, // the score for this request (0.0 - 1.0)
action: string // the action name for this request (important to verify)
}
}
`

#### List of possible error codes:

| Error code | Description |
| :----------------------- | :---------------------------------------------- |
| missing-input-secret | The secret parameter is missing. |
| invalid-input-secret | The secret parameter is invalid or malformed. |
| missing-input-response | The response parameter is missing. |
| invalid-input-response | The response parameter is invalid or malformed. |
| invalid-json-response | Can't parse google's response. Server error. |

Examples

$3

`javascript
var express = require('express')
var bodyParser = require('body-parser')
var pub = __dirname + '/public'
var app = express()
var Recaptcha = require('express-recaptcha').RecaptchaV3

var recaptcha = new Recaptcha('SITE_KEY', 'SECRET_KEY', { callback: 'cb' })

//- required by express-recaptcha in order to get data from body or query.
app.use(bodyParser.json())
app.use(bodyParser.urlencoded())

app.use(express.static(pub))
app.set('views', __dirname + '/views')
app.set('view engine', 'jade')

app.get('/', recaptcha.middleware.render, function (req, res) {
res.render('login', { captcha: res.recaptcha })
})

// override default options for that route
app.get(
'/fr',
recaptcha.middleware.renderWith({ hl: 'fr' }),
function (req, res) {
res.render('login', { captcha: res.recaptcha })
}
)

app.post('/', recaptcha.middleware.verify, function (req, res) {
if (!req.recaptcha.error) {
// success code
} else {
// error code
}
})
`

$3

`javascript
var express = require('express')
var bodyParser = require('body-parser')
var pub = __dirname + '/public'
var app = express()
var Recaptcha = require('express-recaptcha').RecaptchaV3

var recaptcha = new Recaptcha('SITE_KEY', 'SECRET_KEY', { callback: 'cb' })

//- required by express-recaptcha in order to get data from body or query.
app.use(bodyParser.json())
app.use(bodyParser.urlencoded())

app.use(express.static(pub))
app.set('views', __dirname + '/views')
app.set('view engine', 'jade')

app.get('/', function (req, res) {
res.render('login', { captcha: recaptcha.render() })
})

// override default options for that route
app.get('/fr', function (req, res) {
res.render('login', { captcha: recaptcha.renderWith({ hl: 'fr' }) })
})

app.post('/', function (req, res) {
recaptcha.verify(req, function (error, data) {
if (!error) {
// success code
} else {
// error code
}
})
})
`

$3

Run the example folder for a live demo:

`
$ node example\server.js
``

[ci-image]: https://travis-ci.org/pdupavillon/express-recaptcha.svg?branch=master
[ci-url]: https://travis-ci.org/pdupavillon/express-recaptcha
[npm-version-image]: https://badge.fury.io/js/express-recaptcha.svg
[npm-version-url]: http://badge.fury.io/js/express-recaptcha
[expressjs]: https://github.com/expressjs/express
[body-parser]: https://github.com/expressjs/body-parser
[google-recaptcha]: https://www.google.com/recaptcha
[express-recaptcha-v2]: README.v2.md
[google-recaptcha-action]: https://developers.google.com/recaptcha/docs/v3#actions