Logo for jsDocs.io

verify-hcaptcha

  • Version 2.1.0
  • Published
  • 13 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",
    secretKey: "YOUR-SECRET-KEY",
    siteKey: "YOUR-SITE-KEY",
});


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.ZodEffects<
    z.ZodObject<
        {
            success: z.ZodBoolean;
            challenge_ts: z.ZodOptional<z.ZodString>;
            hostname: z.ZodOptional<z.ZodString>;
            credit: z.ZodOptional<z.ZodBoolean>;
            'error-codes': z.ZodOptional<
                z.ZodArray<
                    z.ZodUnion<
                        [
                            z.ZodLiteral<'missing-input-secret'>,
                            z.ZodLiteral<'invalid-input-secret'>,
                            z.ZodLiteral<'missing-input-response'>,
                            z.ZodLiteral<'invalid-input-response'>,
                            z.ZodLiteral<'invalid-sitekey'>,
                            z.ZodLiteral<'missing-remoteip'>,
                            z.ZodLiteral<'invalid-remoteip'>,
                            z.ZodLiteral<'bad-request'>,
                            z.ZodLiteral<'invalid-or-already-seen-response'>,
                            z.ZodLiteral<'not-using-dummy-passcode'>,
                            z.ZodLiteral<'not-using-dummy-secret'>,
                            z.ZodLiteral<'sitekey-secret-mismatch'>
                        ]
                    >,
                    'many'
                >
            >;
            score: z.ZodOptional<z.ZodNumber>;
            'score-reason': z.ZodOptional<z.ZodArray<z.ZodString, 'many'>>;
        },
        'strip',
        z.ZodTypeAny,
        {
            success: boolean;
            challenge_ts?: string | undefined;
            hostname?: string | undefined;
            credit?: boolean | undefined;
            'error-codes'?:
                | (
                      | 'missing-input-secret'
                      | 'invalid-input-secret'
                      | 'missing-input-response'
                      | 'invalid-input-response'
                      | 'invalid-sitekey'
                      | 'missing-remoteip'
                      | 'invalid-remoteip'
                      | 'bad-request'
                      | 'invalid-or-already-seen-response'
                      | 'not-using-dummy-passcode'
                      | 'not-using-dummy-secret'
                      | 'sitekey-secret-mismatch'
                  )[]
                | undefined;
            score?: number | undefined;
            'score-reason'?: string[] | undefined;
        },
        {
            success: boolean;
            challenge_ts?: string | undefined;
            hostname?: string | undefined;
            credit?: boolean | undefined;
            'error-codes'?:
                | (
                      | 'missing-input-secret'
                      | 'invalid-input-secret'
                      | 'missing-input-response'
                      | 'invalid-input-response'
                      | 'invalid-sitekey'
                      | 'missing-remoteip'
                      | 'invalid-remoteip'
                      | 'bad-request'
                      | 'invalid-or-already-seen-response'
                      | 'not-using-dummy-passcode'
                      | 'not-using-dummy-secret'
                      | 'sitekey-secret-mismatch'
                  )[]
                | undefined;
            score?: number | undefined;
            'score-reason'?: string[] | undefined;
        }
    >,
    {
        success: boolean;
        challengeTimestamp: string | undefined;
        hostname: string | undefined;
        credit: boolean | undefined;
        errorCodes:
            | (
                  | 'missing-input-secret'
                  | 'invalid-input-secret'
                  | 'missing-input-response'
                  | 'invalid-input-response'
                  | 'invalid-sitekey'
                  | 'missing-remoteip'
                  | 'invalid-remoteip'
                  | 'bad-request'
                  | 'invalid-or-already-seen-response'
                  | 'not-using-dummy-passcode'
                  | 'not-using-dummy-secret'
                  | 'sitekey-secret-mismatch'
              )[]
            | undefined;
        score: number | undefined;
        scoreReasons: string[] | undefined;
    },
    {
        success: boolean;
        challenge_ts?: string | undefined;
        hostname?: string | undefined;
        credit?: boolean | undefined;
        'error-codes'?:
            | (
                  | 'missing-input-secret'
                  | 'invalid-input-secret'
                  | 'missing-input-response'
                  | 'invalid-input-response'
                  | 'invalid-sitekey'
                  | 'missing-remoteip'
                  | 'invalid-remoteip'
                  | 'bad-request'
                  | 'invalid-or-already-seen-response'
                  | 'not-using-dummy-passcode'
                  | 'not-using-dummy-secret'
                  | 'sitekey-secret-mismatch'
              )[]
            | 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 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>