express-hcaptcha

Google hcaptcha middleware for express.

express-hcaptcha v2 (previous middleware version).

Table of contents

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

Installation

npm install express-hcaptcha --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 HCaptcha = require('express-hcaptcha').RecaptchaV3;
//import HCaptcha from 'express-hcaptcha'
var hcaptcha = new HCaptcha('SITE_KEY', 'SECRET_KEY');
//or with options
var options = {'hl':'de'};
var hcaptcha = new HCaptcha('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 h-captcha-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).

For more information, please refer to:

• reCaptcha - display
• reCaptcha - verify

Render - hcaptcha.middleware.render

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

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

Render - hcaptcha.middleware.renderWith

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

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

Verify - hcaptcha.middleware.verify

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

app.post('/', hcaptcha.middleware.verify, function(req, res){
  if (!req.hcaptcha.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.hcaptcha 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 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

express-hcaptcha - with verification middleware:

var express = require('express');
var bodyParser = require('body-parser');
var pub = __dirname + '/public';
var app = express();
var HCaptcha = require('express-hcaptcha').RecaptchaV3;

var hcaptcha = new HCaptcha('SITE_KEY', 'SECRET_KEY',{callback:'cb'});

//- required by express-hcaptcha 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('/', hcaptcha.middleware.render, function(req, res){
  res.render('login', { captcha:res.hcaptcha });
});

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

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

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

var express = require('express');
var bodyParser = require('body-parser');
var pub = __dirname + '/public';
var app = express();
var HCaptcha = require('express-hcaptcha').RecaptchaV3;

var hcaptcha = new HCaptcha('SITE_KEY', 'SECRET_KEY', {callback:'cb'});

//- required by express-hcaptcha 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:hcaptcha.render() });
});

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

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

Demo:

Run the example folder for a live demo:

$ node example\server.js