Bot Defense: reCAPTCHA Guard & Quarantine Manager

Public-facing forms (Quote Intake, Contact Inquiries, Scheduled Calls, Claims, and Careers) are primary targets for automated credential stuffers, spam bots, and malicious script scanners.

veridex-hitech-web-application implements a multi-layered bot mitigation protocol pairing Google reCAPTCHA v3 invisible risk scoring with v2 interactive checkbox fallback, honeypot fields, and a dedicated Quarantine Isolation Subsystem.

---

1. Multi-Tier Threat Analysis Workflow

---

2. Shared verifyRecaptchaGuard Helper (src/lib/recaptcha-guard.ts)

To avoid duplicating threat analysis across Server Actions and API route handlers, all form submissions funnel through the central verifyRecaptchaGuard helper:

export async function verifyRecaptchaGuard(
  data: Record<string, any>,
  token: string | null | undefined,
  formType: string,
  ipAddress: string = "unknown",
  userAgent: string = "unknown"
): Promise<RecaptchaGuardResult> {
  let clientIp = ipAddress;
  let clientUa = userAgent;

  // Auto-resolve IP and User Agent from request headers
  if (clientIp === "unknown" || clientUa === "unknown") {
    try {
      const headersList = await headers();
      clientIp =
        headersList.get("x-forwarded-for")?.split(",")[0]?.trim() ||
        headersList.get("x-real-ip") ||
        "unknown";
      clientUa = headersList.get("user-agent") || "unknown";
    } catch {
      // Running outside request context (e.g. test scripts)
    }
  }

  // 1. Missing Token (Ad-blockers, Brave Shields, or network script blocks)
  if (!token) {
    console.warn(`[reCAPTCHA Guard] Missing token for "${formType}" from ${clientIp}. Quarantining and proceeding.`);
    await QuarantineManager.quarantine({
      originalData: data,
      score: 0.5,
      reason: "FAILED_VERIFICATION",
      formType,
      ipAddress: clientIp,
      userAgent: clientUa,
    });
    return { success: true, score: 0.5, quarantined: true };
  }

  // 2. Google reCAPTCHA Verification
  const verification = await verifyRecaptchaWithScoreAndMessage(token, formType);

  // 3. Score-Based Categorization
  if (!verification.success || verification.score < 0.3) {
    await QuarantineManager.quarantine({
      originalData: data,
      score: verification.score ?? 0.0,
      reason: "LOW_SCORE",
      formType,
      ipAddress: clientIp,
      userAgent: clientUa,
    });
    return {
      success: false,
      error: "Verification failed. If you are human, please try again or call our office.",
      score: verification.score,
      quarantined: true,
    };
  }

  return { success: true, score: verification.score };
}

---

3. The Fail-Open Quarantine Guarantee

A common vulnerability of aggressive bot protections is false-positive rejection: if an actual commercial fleet manager uses privacy extensions (such as Brave Shields, uBlock Origin, or Privacy Badger) that block Google scripts, a strict bot filter would completely block their multi-thousand-dollar quote inquiry.

The platform guarantees Fail-Open Lead Recovery:

• When a token is missing due to client script blocking, the system never crashes or throws a 400 error.
• The full form payload is immediately diverted into QuarantinedLead marked with reason: 'FAILED_VERIFICATION'.
• The user interface receives a standard confirmation screen so the policyholder is not alienated.
• The record immediately appears in the Admin Control Center for human review.

---

4. Quarantine Classification Taxonomy

Every document in QuarantinedLead is categorized by a specific diagnostic reason:

Reason Code	Trigger Condition	System Action
LOW_SCORE	Google reCAPTCHA v3 returns a score below 0.3.	Diverted to quarantine; client receives human fallback error message.
FAILED_VERIFICATION	Missing token (ad-blocker), Google server outage, or token replay.	Diverted to quarantine; client receives standard confirmation (fail-open).
SUSPICIOUS_PATTERN	Hidden honeypot form fields were filled in, or rapid form completion (< 1.5s).	Diverted to quarantine; blocked from operational CRM pipelines.
MALICIOUS_CONTENT	Input fields contain SQL injection strings, XSS payloads, or known spam URLs.	Isolated immediately for compliance and threat analysis.

---

5. Administrative Review & Resolution Workflow

1. Quarantine Inspection (/admin): Authorized administrators can filter quarantined records by form type, risk score, and date range.
2. Threat Assessment: Staff view the submitter's IP address, User Agent, calculated risk score, and full JSON payload.
3. Approval to CRM: If staff determines that an inquiry is a legitimate prospective client, clicking "Approve & Forward" automatically transfers the record into Lead and dispatches it to the HTI CRM.
4. Dismissal: If verified as spam, the administrator marks the record as processed with optional review notes.