Logo for jsDocs.io

verify-hcaptcha

  • Version 3.0.0
  • Published
  • 12.7 kB
  • 1 dependency
  • MIT license

Install

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

Overview

A fully typed library to verify hCaptcha.com 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';


const result = await verifyHcaptchaToken({
    token: "USER-SUBMITTED-RESPONSE-TOKEN", // Required
    secretKey: "YOUR-SECRET-KEY",           // Required
    siteKey: "YOUR-SITE-KEY",               // Optional
    remoteIp: "USER-IP-ADDRESS",            // Optional
});


if (result.success) {
    console.log("User is human");
} else {
    console.log("User is robot");
}

Index

Variables

Functions

Type Aliases

Variables

variable hCaptchaResponseSchema

const hCaptchaResponseSchema: z.ZodMiniPipe<
    z.ZodMiniObject<
        {
            success: z.ZodMiniBoolean<boolean>;
            challenge_ts: z.ZodMiniOptional<z.ZodMiniString<string>>;
            hostname: z.ZodMiniOptional<z.ZodMiniString<string>>;
            credit: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
            'error-codes': z.ZodMiniOptional<
                z.ZodMiniArray<
                    z.ZodMiniType<
                        ErrorCodes | (string & {}),
                        unknown,
                        z.core.$ZodTypeInternals<ErrorCodes | (string & {}), unknown>
                    >
                >
            >;
            score: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
            'score-reason': z.ZodMiniOptional<
                z.ZodMiniArray<z.ZodMiniString<string>>
            >;
        },
        z.core.$strip
    >,
    z.ZodMiniTransform<
        {
            success: boolean;
            challengeTimestamp: string | undefined;
            hostname: string | undefined;
            credit: boolean | undefined;
            errorCodes: (ErrorCodes | (string & {}))[] | undefined;
            score: number | undefined;
            scoreReasons: string[] | undefined;
        },
        {
            success: boolean;
            challenge_ts?: string | undefined;
            hostname?: string | undefined;
            credit?: boolean | undefined;
            'error-codes'?: (ErrorCodes | (string & {}))[] | undefined;
            score?: number | undefined;
            'score-reason'?: string[] | undefined;
        }
    >
>;

    Functions

    function verifyHcaptchaToken

    verifyHcaptchaToken: ({
        token,
        secretKey,
        siteKey,
        remoteIp,
    }: {
        token: string;
        secretKey: string;
        siteKey?: string;
        remoteIp?: string;
    }) => Promise<HcaptchaResponse>;

    • verifyHcaptchaToken verifies with the hCaptcha.com API that the response token obtained from a user who solved a captcha challenge is valid.

      Parameter token

      required: the token obtained from the user who solved the 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 who solved the challenge

      Returns

      a HcaptchaResponse with the verification result

    Type Aliases

    type ErrorCodes

    type ErrorCodes =
        /** 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'
        /** User response token is expired. */
        | 'expired-input-response'
        /** User response token was already verified once. */
        | 'already-seen-response'
        /** Request is invalid. */
        | 'bad-request'
        /** Remote user IP is missing. */
        | 'missing-remoteip'
        /** Remote user IP is invalid. */
        | 'invalid-remoteip'
        /** Must use the test site key when using a test verification token. */
        | 'not-using-dummy-passcode'
        /** The site key is not associated to the secret key. */
        | 'sitekey-secret-mismatch'
        /** Site key is invalid (Not listed on hcaptcha docs). */
        | 'invalid-sitekey'
        /** Must use the test secret key when using a test verification token (Not listed on hcaptcha docs). */
        | 'not-using-dummy-secret';

      type HcaptchaResponse

      type HcaptchaResponse = z.infer<typeof hCaptchaResponseSchema>;

      Package Files (1)

      Dependencies (1)

      Dev Dependencies (8)

      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>