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 {}
HcaptchaResponse
represents the response to the verification challenge performed by calling verifyHcaptchaToken.See Also
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[];
Optional: list of error codes
See Also
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 {}
RawHcaptchaResponse
represents the raw response to the verification challenge obtained by directly calling the hCaptcha API endpoint with rawVerifyHcaptchaToken.See Also
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';
HcaptchaError
collects the errors explaining why a verification challenge failed.See Also
Package Files (1)
Dependencies (0)
No dependencies.
Dev Dependencies (17)
Peer Dependencies (0)
No peer dependencies.
Badge
To add a badge like this oneto 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>
- Updated .
Package analyzed in 1122 ms. - Missing or incorrect documentation? Open an issue for this package.