verify-hcaptcha

  • Version 1.0.0
  • Published
  • 252 kB
  • No dependencies
  • MIT license

Install

npm i verify-hcaptcha
yarn add verify-hcaptcha
pnpm add verify-hcaptcha

Overview

A no dependencies, fully typed library to verify hCaptcha tokens submitted by users when solving CAPTCHA challenges.

Remarks

Note: this is an unofficial library; we are not affiliated with hCaptcha.com

Example 1

Verify a token submitted by a user:

import { verifyHcaptchaToken } from 'verify-hcaptcha';
(async () => {
const result = await verifyHcaptchaToken({
token: "USER-SUBMITTED-RESPONSE-TOKEN",
secretKey: "YOUR-SECRET-KEY",
siteKey: "YOUR-SITE-KEY",
});
if (result.success) {
console.log("User is human");
} else {
console.log("User is robot");
}
})();

Example 2

Verify a token submitted by a user and get the raw response from hCaptcha:

import { rawVerifyHcaptchaToken } from 'verify-hcaptcha';
(async () => {
const result = await rawVerifyHcaptchaToken({
token: "USER-SUBMITTED-RESPONSE-TOKEN",
secretKey: "YOUR-SECRET-KEY",
siteKey: "YOUR-SITE-KEY",
});
if (result.success) {
console.log("User is human");
} else {
console.log("User is robot");
}
})();

Index

Functions

function rawVerifyHcaptchaToken

rawVerifyHcaptchaToken: ({
token,
secretKey,
siteKey,
remoteIp,
}: {
token: string;
secretKey: string;
siteKey?: string;
remoteIp?: string;
}) => Promise<RawHcaptchaResponse>;
  • rawVerifyHcaptchaToken verifies with the hCaptcha API that the response token obtained from a captcha challenge is valid and returns the raw hCaptcha response.

    Parameter token

    required: the token obtained from a user with a captcha challenge

    Parameter secretKey

    required: the secret key for your account

    Parameter siteKey

    optional but recommended: the site key for the website hosting the captcha challenge

    Parameter remoteIp

    optional: the IP address of the user submitting the challenge

    Returns

    a RawHcaptchaResponse with the verification result

function verifyHcaptchaToken

verifyHcaptchaToken: ({
token,
secretKey,
siteKey,
remoteIp,
}: {
token: string;
secretKey: string;
siteKey?: string;
remoteIp?: string;
}) => Promise<HcaptchaResponse>;
  • verifyHcaptchaToken verifies with the hCaptcha API that the response token obtained from a captcha challenge is valid.

    Parameter token

    required: the token obtained from a user with a captcha challenge

    Parameter secretKey

    required: the secret key for your account

    Parameter siteKey

    optional but recommended: the site key for the website hosting the captcha challenge

    Parameter remoteIp

    optional: the IP address of the user submitting the challenge

    Returns

    a HcaptchaResponse with the verification result

Interfaces

interface HcaptchaResponse

interface HcaptchaResponse {}

property challengeTimestamp

readonly challengeTimestamp?: string;
  • Optional: UTC timestamp of the challenge in ISO 8601 format (for example, 2021-10-02T18:12:10.149Z)

property credit

readonly credit?: boolean;
  • Optional: true if the response will be credited

property errorCodes

readonly errorCodes?: HcaptchaError[];

property hostname

readonly hostname?: string;
  • Optional: hostname of the website where the challenge was solved

property score

readonly score?: number;
  • Enterprise-only feature: score for malicious activity

property scoreReasons

readonly scoreReasons?: string[];
  • Enterprise-only feature: list of reasons for the malicious activity score

property success

readonly success: boolean;
  • True if the token is valid and meets the specified security criteria (for example, if the site key is associated to the secret key)

interface RawHcaptchaResponse

interface RawHcaptchaResponse {}

property "error-codes"

readonly 'error-codes'?: string[];

    property challenge_ts

    readonly challenge_ts?: string;

      property credit

      readonly credit?: boolean;

        property hostname

        readonly hostname?: string;

          property score

          readonly score?: number;

            property score_reason

            readonly score_reason?: string[];

              property success

              readonly success: boolean;

                Type Aliases

                type HcaptchaError

                type HcaptchaError =
                /** Secret key is missing */
                | 'missing-input-secret'
                /** Secret key is invalid */
                | 'invalid-input-secret'
                /** User response token is missing */
                | 'missing-input-response'
                /** User response token is invalid */
                | 'invalid-input-response'
                /** Site key is invalid */
                | 'invalid-sitekey'
                /** Remote user IP is invalid */
                | 'invalid-remoteip'
                /** Request is invalid */
                | 'bad-request'
                /** User response token is invalid or has already been checked */
                | 'invalid-or-already-seen-response'
                /** Must use the test site key when using a test verification token */
                | 'not-using-dummy-passcode'
                /** Must use the test secret key when using a test verification token */
                | 'not-using-dummy-secret'
                /** The site key is not associated to the secret key */
                | 'sitekey-secret-mismatch';

                Package Files (1)

                Dependencies (0)

                No dependencies.

                Dev Dependencies (17)

                Peer Dependencies (0)

                No peer dependencies.

                Badge

                To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/verify-hcaptcha.

                • Markdown
                  [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/verify-hcaptcha)
                • HTML
                  <a href="https://www.jsdocs.io/package/verify-hcaptcha"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>