express-recaptcha
    TypeScript icon, indicating that this package has built-in type declarations

    5.1.0 • Public • Published

    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:

    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 g-recaptcha-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).
    useRecaptchaDomain Boolean. Sets www.recaptcha.net as the host; useful in instances where www.google.com may be blocked (as detailed in the reCaptcha docs)

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

    Demo:

    Run the example folder for a live demo:

    $ node example\server.js
    

    Install

    npm i express-recaptcha

    DownloadsWeekly Downloads

    11,554

    Version

    5.1.0

    License

    MIT

    Unpacked Size

    38.3 kB

    Total Files

    25

    Last publish

    Collaborators

    • pdupavillon