This library has been developed to help you validate reCAPTCHA responses in Node.js.
It is compatible with Express.js but allows you to build your verification logic with ease.
npm install recaptcha --save
const recaptcha = require('recaptcha');
const expressMiddlerware = recaptcha({
siteSecret: 'string', // Required. The site secret created in the admin console.
captchaProperty: 'string' // Optional. The name of the property used to store the recaptcha response. More info later
});
app.post('/endpoint', recaptchaMiddleware, (req, res) => {
res.json({ message: 'SUCCESS' });
});
expressMiddleware
contains also 2 properties:
verifyCaptchaResponse
: a function you can use to validare directly your captcha response. It returns the raw json response from the reCAPTCHA APIs.RecaptchaError
: the class of the errors thrown by therecaptchaMiddleware
.
Using verifyCaptchaResponse
you can build your own validation logic as the following.
app.post('/endpoint', (req, res, next) => {
const response = await verifyCaptchaResponse(req.body.captcha['g-recaptcha-response']);
if (response.success){
res.json({ message: 'SUCCESS' });
return;
}
next(new Error('recaptcha challenge failed'));
});
options
is an object with 2 parameters:
siteSecret
: required, the site secret created in the admin console.captchaProperty
: optional, the name of the property used to store the recaptcha response
The middleware by default look for the recaptcha response under the g-recaptcha-response
property of the following objects in the given order:
req.headers
req.query
req.body
req
wherereq
is the express request passed to the middleware.
If your backend is not receiving the recaptcha response under that property you can override this behaviour by changing the name of the property or create your custom logic.
The function returns a function which is your express ready middleware.
The middleware has 2 properties:
verifyCaptchaResponse
RecaptchaError
gRecaptchaResponse
: the recaptcha response. Must be a string.
Returns a Promise that resolves to the json response returned by the reCAPTCHA APIs. The returned object from the promise has the following properties:
success
: boolean, indicates if the validation was successfulchallenge_ts
: timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)hostname
: the hostname of the site where the reCAPTCHA was solvederror-codes
: an array of strings representing the error codes. You can parse these strings usingRecaptchaError.fromCode
in order to get more info.
The error class used by the library. All the errors thrown by the middleware are instances of this class.
It provides the utility method fromCode(code, msg)
useful for getting more info from the error-codes
returned from the verifyCaptchaResponse
function. The msg
parameter overrides the default error, this was designed for an internal use.
Example:
const recaptcha = require('recaptcha');
const RecaptchaError = recaptcha({ siteSecret }).RecaptchaError;
async function run() {
const response = await verifyCaptchaResponse(gRecaptchaResponse);
if (!response.successful) {
const errCode = response[`error-codes`][0];
const err = RecaptchaError.fromCode(errCode);
console.log(err.code);
console.log(err.message); // Tells more about the errorCode
throw err;
}
//...
}