Math & Slider Captcha — @itzsa/captcha

import { useRef, useState } from "react";
import { MathCaptcha, type MathCaptchaHandle } from "@itzsa/captcha";

/** Client: generate + verify in the browser */
export function ClientMathGate() {
  const ref = useRef<MathCaptchaHandle>(null);
  const [ok, setOk] = useState(false);

  return (
    <>
      <MathCaptcha
        ref={ref}
        difficulty="medium"
        layout="inline"
        // no serverChallenge → local generateMathChallenge + verifyMathAnswer
        onVerified={setOk}
      />
      <button type="button" disabled={!ok} onClick={() => {
        if (!ref.current?.validate()) return;
        // soft gate only
      }}>
        Continue
      </button>
    </>
  );
}

import { useCallback, useEffect, useRef, useState } from "react";
import {
  MathCaptcha,
  type MathCaptchaHandle,
  type MathCaptchaServerChallenge,
} from "@itzsa/captcha";

/** Server: trusted source of truth — answer never sent to the client */
export function ServerMathGate() {
  const ref = useRef<MathCaptchaHandle>(null);
  const meta = useRef<{ renderStamp: string; honeypotField: string } | null>(null);
  const [challenge, setChallenge] = useState<MathCaptchaServerChallenge | null>(null);
  const [ok, setOk] = useState(false);

  const load = useCallback(async () => {
    const res = await fetch("/api/captcha/challenge", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ difficulty: "bodmas", action: "login" }),
    });
    const data = await res.json();
    meta.current = { renderStamp: data.renderStamp, honeypotField: data.honeypotField };
    setChallenge({ prompt: data.prompt, token: data.token });
    setOk(false);
  }, []);

  useEffect(() => { void load(); }, [load]);

  return (
    <MathCaptcha
      ref={ref}
      layout="inline"
      serverChallenge={challenge}
      onRequestChallenge={load}
      verify={async ({ value, challengeId }) => {
        const m = meta.current;
        if (!m) return false;
        const res = await fetch("/api/captcha/verify", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            token: challengeId,
            answer: value,
            renderStamp: m.renderStamp,
            honeypotField: m.honeypotField,
            honeypotValue: "",
            action: "login",
          }),
        });
        return res.ok && (await res.json()).ok === true;
      }}
      onVerified={setOk}
    />
  );
}

import { useRef, useState } from "react";
import { Captcha, type CaptchaHandle } from "@itzsa/captcha";

export function LoginGate() {
  const captchaRef = useRef<CaptchaHandle>(null);
  const [verified, setVerified] = useState(false);

  return (
    <>
      <Captcha
        ref={captchaRef}
        length={6}
        charsetMode="both"
        onVerified={setVerified}
      />
      <button
        type="button"
        disabled={!verified}
        onClick={() => {
          if (!captchaRef.current?.validate()) return;
          // submit…
        }}
      >
        Continue
      </button>
    </>
  );
}

/**
 * Example Express wiring for @itzsa/captcha server-side challenges.
 * Uses the same headless helpers: generateMathChallenge + verifyMathAnswer.
 *
 * npm i express express-rate-limit rate-limit-redis redis ioredis cookie-parser
 * # optional: hcaptcha (or use Turnstile fetch below — no SDK)
 */
import express from "express";
import cookieParser from "cookie-parser";
import rateLimit from "express-rate-limit";
import { RedisStore } from "rate-limit-redis";
import { createClient } from "redis";
import {
  generateMathChallenge,
  verifyMathAnswer,
  createChallengeId,
} from "@itzsa/captcha";

const app = express();
app.use(express.json());
app.use(cookieParser());

const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

const challenges = new Map(); // replace with redis.set(token, JSON, { EX: 300 })

const verifyLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 30,
  standardHeaders: true,
  legacyHeaders: false,
  store: new RedisStore({
    sendCommand: (...args) => redis.sendCommand(args),
  }),
});

app.post("/api/captcha/challenge", async (req, res) => {
  const token = createChallengeId();
  const c = generateMathChallenge({ difficulty: req.body?.difficulty ?? "medium" });
  // STORE answer server-side only — never send c.answer
  await redis.set(
    `captcha:chal:${token}`,
    JSON.stringify({ answer: String(c.answer), kind: "math" }),
    { EX: 300 },
  );
  res.json({
    token,
    prompt: c.prompt,
    honeypotField: `hp_${token.slice(0, 8)}`,
    renderStamp: Date.now(), // prefer HMAC-signed stamp in production
  });
});

app.post("/api/captcha/verify", verifyLimiter, async (req, res) => {
  const { token, answer, honeypotField, honeypotValue } = req.body ?? {};
  if (honeypotValue) return res.status(400).json({ ok: false });

  const raw = await redis.get(`captcha:chal:${token}`);
  await redis.del(`captcha:chal:${token}`); // single-use
  if (!raw) return res.status(400).json({ ok: false, error: "expired" });

  const { answer: expected } = JSON.parse(raw);
  const ok = verifyMathAnswer({ value: answer, answer: Number(expected) });
  if (!ok) return res.status(400).json({ ok: false, error: "incorrect" });

  // Issue short-lived human cookie / JWT here (HMAC or jose)
  res.cookie("itzsa_human", "…signed…", { httpOnly: true, sameSite: "lax" });
  res.json({ ok: true });
});

/** Sensitive action — require human cookie + optional Turnstile */
app.post("/api/checkout", async (req, res) => {
  // verifyTurnstile(req.body.turnstileToken)
  // verifyHumanPass(req.cookies.itzsa_human, "checkout")
  // idempotency key + velocity checks
  res.json({ ok: true });
});

app.listen(3001);