@satyajeetsahoo/captcha

A unified CAPTCHA service supporting HCaptcha and ReCaptcha.

Why use this package?

Client-side CAPTCHAs are useless without server-side validation. This package provides a single interface to validate CAPTCHA tokens securely on your backend. It normalizes the responses so you can swap between ReCaptcha v2/v3 and HCaptcha without rewriting your authentication routes.

Features

• ReCaptcha v3 Score Support: Easily set minScore thresholds to silently block bots.
• Standardized Validation: Always returns a boolean success status regardless of the provider's underlying JSON format.

Installation

npm install @satyajeetsahoo/captcha

Configuration & Strategies

HCaptcha Strategy

import { CaptchaFactory } from '@satyajeetsahoo/captcha';

export const captcha = CaptchaFactory.createCaptchaStrategy('hcaptcha', { 
  secretKey: process.env.HCAPTCHA_SECRET 
});

ReCaptcha Strategy (v2/v3)

import { CaptchaFactory } from '@satyajeetsahoo/captcha';

export const captcha = CaptchaFactory.createCaptchaStrategy('recaptcha', { 
  secretKey: process.env.RECAPTCHA_SECRET,
  minScore: 0.5 // Optional threshold. Any score below 0.5 will fail validation.
});

Usage Examples

Securing a Login Route

Always validate the token before processing sensitive actions.

app.post('/login', async (req, res) => {
  const isValid = await captcha.verify(req.body.captchaToken, req.ip);
  
  if (!isValid) {
    return res.status(400).json({ message: 'CAPTCHA verification failed. Bot detected.' });
  }

  // Proceed with normal login...
});