@sprdv/hapi-captcha v0.2.1

hapi-captcha

Hapi plugin to setup reCAPTCHA v3.

reCAPTCHA v3 returns a score for each request without user friction. The score is based on interactions with your site and enables you to take an appropriate action for your site. Register reCAPTCHA v3 keys here.

Installation

hapi-captcha can be installed using npm or yarn.

npm install @sprdv/hapi-captcha

Usage

This plugin can be registered like any other:

'use strict';

const Hapi = require('@hapi/hapi');

const init = async () => {

    const server = Hapi.server();

    await server.register({ 
        plugin: require('@sprdv/hapi-captcha'), 
        options: {
            secret: process.env.CAPTCHA_SECRET,
            score: 0.7,
            mock: false
        } 
    });

    await server.start();
    console.log('Server running on %s', server.info.uri);
};

init();

Options

The following options are available:

• secret: a shared key between your site and reCAPTCHA (required).
• score: the minimum score required when verifying a request (between 0.0 and 1.0, defaults to 0.5).
• mock: mock captcha's methods (defaults to false). All verification requests will be successful.

Documentation

Verifying responses

To verify a user's response to a reCAPTCHA challenge, use the verify method:

server.route({
    method: 'POST',
    path: '/users/register',
    options: {
        validate: {
            payload: Joi.object({
                token: Joi.string().required()
            })
        },
        async handler(req, h) {
            
            const { token } = req.payload;

            // ...

            await req.captcha.verify(token, 'register');

            // ...

        }              
    }
});

In this case, the validation is done automatically. It will make sure that:

1. The request is successful
2. The action name matches with the one defined in your client implementation
3. The score is higher or equal than the one defined when registering the plugin

If any criteria isn't met, a Boom.badRequest (400) error will be thrown.

You can also specify the minimum score for each request individually:

await req.captcha.verify(token, 'register', 0.8);

The following options are available:

• token: the user response token provided by the reCAPTCHA client-side integration on your site (required).
• action: the action name for this request (required).
• score: the minimum score required (between 0.0 and 1.0).

This library is capable of validating a request automatically, but you can also do the validation yourself:

const payload = await req.captcha.payload(token);

if (!payload.success) {
    throw Boom.badRequest('Invalid captcha');
}

// Verify the action name, score, ...

The response is a JSON Object:

{
  "success": "true|false",
  "score": "number",
  "action": "string",
  "challenge_ts": "timestamp",
  "hostname": "string",
  "error-codes": "[...]"
}