er

express-recaptcha

Implementation of google recaptcha v2 & V3 solutions for express.js

Showing:

Popularity

Downloads/wk

14.1K

GitHub Stars

109

Maintenance

Last Commit

7mos ago

Contributors

7

Package

Dependencies

0

Size (min+gzip)

1.6KB

License

MIT

Type Definitions

Built-In

Tree-Shakeable

No?

Readme

express-recaptcha

NPM

Build Status npm version

Google recaptcha middleware for express.

express-recaptcha v2 (previous middleware version).

Table of contents

Installation

npm install express-recaptcha --save

Requirements

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

Usage

How to initialise:

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:

optiondescription
onloadThe callback function that gets called when all the dependencies have loaded.
hlForces the widget to render in a specific language (Auto-detects if unspecified).
callbackIn 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)
actionhomepage by default should only be alphanumeric More info on google's web site
checkremoteipAdding support of remoteip verification (based on x-forwarded-for header or remoteAddress.Value could be true OR false (default false).

For more information, please refer to:

Render - recaptcha.middleware.render

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:

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

Render - recaptcha.middleware.renderWith

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

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

Verify - recaptcha.middleware.verify

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

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:

{
  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 codeDescription
missing-input-secretThe secret parameter is missing.
invalid-input-secretThe secret parameter is invalid or malformed.
missing-input-responseThe response parameter is missing.
invalid-input-responseThe response parameter is invalid or malformed.
invalid-json-responseCan't parse google's response. Server error.

Examples

express-recaptcha - with verification middleware:

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
  }
});

express-recaptcha - without verification middleware: (using recaptcha.verify callback instead)

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 (!req.recaptcha.error) {
      // success code
    } else {
      // error code
    }
  });
});

Demo:

Run the example folder for a live demo:

$ node example\server.js

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
jnsys1 Rating0 Reviews
5 days ago

Tutorials

No tutorials found
Add a tutorial