captcha-verifier
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.1 • Public • Published

    Captcha verifier

    Captcha verifying has never been so easy. Take a look on the live example: https://captcha-verifier.ivanadmaers.com/

    captcha-verifier logo

    Features

    • 📦 Zero dependencies
    • 🔌 Ease of use API
    • 🔫 ES6 syntax
    • 📝 MIT license
    • Verify reCaptcha 2, reCaptcha 3, hCaptcha easy peasy
      and much more...

    Installation

    # By npm:
    npm i captcha-verifier
    # By yarn:
    yarn add captcha-verifier

    Usage

    Configurate the config.

    Keep it on mind that if you need verify only reCaptcha 2 you don't necessary to set other keys for reCaptcha 3 or hCaptcha. Set keys only for captcha services that you will need to verify in your project

    const verifier = require('captcha-verifier');
    // import verifier from 'captcha-verifier';
    
    verifier.config({
      reCaptchaV2SecretKey: 'YOUR_RECAPTCHA_V2_SECRET_KEY', // string
      reCaptchaV3SecretKey: 'YOUR_RECAPTCHA_V3_SECRET_KEY', // string
      reCaptchaV3PassingScore: 0.4, // optional. Number. 0.4 by default
      hCaptchaSecretKey: 'YOUR_HCAPTCHA_SECRET_KEY', // string
    });

    API

    If you need to verify reCaptcha V2:

    const [success, response] = await verifier.reCaptchaV2('token (client captcha response)', 'client IP');

    If you need to verify reCaptcha V3:

    const [success, response] = await verifier.reCaptchaV3('token (client captcha response)', 'client IP');

    If you need to verify hCaptcha:

    const [success, response] = await verifier.hCaptcha(
        'token (client captcha response)',
        'client IP',
        'HCAPTCHA_PUBLIC_KEY', // optional (https://docs.hcaptcha.com/#verify-the-user-response-server-side)
      );

    Returns:

    [
      success: true|false, // boolean
      response: {}, // object
    ]

    If you just need to make sure that the captcha was successfully solved by a human, not a robot, do somethig like this:

    const [success, response] = await verifier.reCaptchaV2('token (client captcha response)', 'client IP');
    
    if (!success) {
      // actions for robots
    }
    
    // actions for humans

    If you need to get some specific parameters from the captcha service, you can find it in the second array item.

    const [success, response] = await verifier.reCaptchaV3('token (client captcha response)', 'client IP');
    
    if (!success || !response.hostname === 'localhost') {
      // do something for robots
    }
    
    // do something else for humans

    Notes

    reCaptchaV3PassingScore

    About the reCaptchaV3PassingScore paramete. It's an optional paramete that you may set if you verifies reCaptcha 3. After reCaptcha 3 verified your token (captcha response from client) you get a score param from 0 to 1. The higher the number, the more likely it is that the captcha was passed by a human, not a robot. So you can set a specific score that will give you success true result.

    Example:

    verifier.config({
      reCaptchaV3SecretKey: 'YOUR_CAPTCHA_SECRET_KEY', // string
      reCaptchaV3PassingScore: 0.5, // number
    });
    const [success, response] = await verifier.reCaptchaV3('token (client captcha response)', 'client ip');

    If reCaptcha returns score 0.9 the success parament will be true because the returned number from reCaptcha is more to setted passing score in the config.

    If reCaptcha returns score 0.2 the success parament will be false because the returned number from reCaptcha is less to setted passing score in the config.

    If reCaptcha returns score 0.5 the success parament will be true because the returned number from reCaptcha is equals to setted passing score in the config.

    response score < setted in config score = false
    response score = setted in config score = true
    response score > setted in config score = true

    Contributing

    # Clone the package
    
    # Run:
    npm ci i
    npm run dev
    
    cd /example
    
    npm ci i
    
    npm run dev

    Any ideas for improvement this package are always welcome!

    License

    MIT

    Copyright (c) 2021-present, Ivan Admaers

    Install

    npm i captcha-verifier

    DownloadsWeekly Downloads

    46

    Version

    1.1.1

    License

    MIT

    Unpacked Size

    165 kB

    Total Files

    41

    Last publish

    Collaborators

    • admaers