II.6.h. Captcha engines

Place your custom captcha engine files into the captchas directory. One file may export one or several captcha engines. Like so:

module.exports = engine;

or:

module.exports = [
    engine1,
    engine2,
    //...
];

Both files will be automatically loaded by ololord.js.

Note: You may also add Captcha settings with the Captcha.defineSetting(name, defaultValue) method.

Captcha API

Captcha(id, title)

Constructor.

• id The string captcha engine identifier.
• title Human-readable title. Either a string, or a result of Tools.translate.noop (translation object).

Example:

var googleRecaptcha = new Captcha("google-recaptcha-v1", Tools.translate.noop("Google reCAPTCHA v1"));

Captcha.apiRoutes()

Must return a list of objects representing Express routes. Each object must have the following fields:

• method HTTP method (GET, POST, etc.). Normally GET.
• path Route path relative to /api path.
• handler Handler function (the req and res arguments will be passed to it).

Captcha.actionRoutes()

Must return a list of objects representing Express routes. Each object must have the following fields:

• method HTTP method (GET, POST, etc.). Normally POST.
• path Route path relative to /action path.
• handler Handler function (the req and res arguments will be passed to it).

Captcha.checkCaptcha(req, fields)

Must return a resolving Promise if the captcha is correct, and a rejecting Promise with an error message (non-empty string) as a value otherwise.

• req Express request object.
• fields Post form fields (Object).

This method MUST be defined.

Example:

googleRecaptcha.checkCaptcha = function(req, fields) {
    var challenge = fields.recaptcha_challenge_field;
    var response = fields.recaptcha_response_field;
    if (!challenge)
        return Promise.reject(Tools.translate("Captcha challenge is empty"));
    if (!response)
        return Promise.reject(Tools.translate("Captcha is empty"));
    var query = `privatekey=${this.privateKey}&remoteip=${req.ip}&challenge=${encodeURIComponent(challenge)}`
        + `&response=${encodeURIComponent(response)}`;
    var url = "https://www.google.com/recaptcha/api/verify?" + query;
    return HTTP.request({
        url: url,
        timeout: (15 * Tools.Second)
    }).then(function(response) {
        if (response.status != 200)
            return Promise.reject(Tools.translate("Failed to check captcha"));
        return response.body.read("utf8");
    }).then(function(data) {
        var result = data.toString();
        if (result.replace("true", "") == result)
            return Promise.reject(Tools.translate("Invalid captcha"));
        return Promise.resolve();
    });
};

Captcha.widgetHtml()

Must return the rendered captcha widget HTML. THe HTML is inserted into the page as a raw text.

This method or Captcha.widgetTemplate MUST be defined.

Captcha.widgetTemplate()

Returns the captcha widget template name. The template is rendered by ololord.js automatically and then inserted into the page.

This method or Captcha.widgetHtml MUST be defined.

Example:

googleRecaptcha.widgetTemplate = function() {
    return "googleRecaptchaWidget";
};

Captcha.script()

If this method returns a non-null value, that value is treated as a raw script tag data to insert into the page.

Captcha.scriptSource()

If this method returns a non-null value, that value is treated as the src attribute value of a script tag to be inserted into the page.

Example:

googleRecaptcha.scriptSource = function() {
    return "https://www.google.com/recaptcha/api.js";
};

Note: Take a look at the captchas/captcha.js file and other files in the captchas directory for better understanding of how to create custom captcha engines.