feat(core): enable recaptcha in forms (#2896)

* added recaptcha v3

* update recaptcha package and make visible on forms

* linting

* make recaptcha optional for dynamic-form

* remove comments

* remove comments

* remove recaptcha provider since it wasn't used

* make recaptcha required if enabled and use getValue to retrieve token

* add types for react-google-recaptcha

* fix linting

* fix linting

* fix linting

* fix linting

* refactor(recaptcha): validate in form actions and separate parse from validate

- Add validateRecaptchaToken() to validate reCAPTCHA in form actions and
  return formErrors so Conform displays them (contact, review, register).
- Add getRecaptchaFromForm() to parse site key and token from FormData.
- Make validateRecaptchaToken() a pure function (siteKey, token, message)
  so validation is separate from form parsing and easier to test/reuse.
- Contact, review, and register actions: parse via getRecaptchaFromForm(),
  then validate via validateRecaptchaToken(), and pass token to mutations.

Made-with: Cursor

* fix linting

* remove client side logic and error handling

* rename validat function for recaptha token to assertRecaptchaTokenPresent

* remove unused recaptcha settings in graphql

* fix linting

* remove client side logic and validation for recaptcha

* remove unused properties from RecaptchaSettings interface

* remove unnecessary DynamicFormInner wrapper component

Made-with: Cursor

* remove unused failedLoginLockoutDurationSeconds and isEnabledOnCheckout from getReCaptchaSettings

Made-with: Cursor

* add changeset

* chore: add tests for recaptcha

---------

Co-authored-by: Jorge Moya <jorge.moya@bigcommerce.com>

Author: jamesqquick

.changeset/lazy-rivers-stare.md

@@ -0,0 +1,216 @@
+---
+"@bigcommerce/catalyst-core": minor
+---
+
+Add reCAPTCHA v2 support to storefront forms. The reCAPTCHA widget is rendered on the registration, contact, and product review forms when enabled in the BigCommerce admin. All validation and error handling is performed server-side in the corresponding form actions. The token is read from the native `g-recaptcha-response` field that the widget injects into the form, eliminating the need for manual token extraction on the client.
+
+## Migration steps
+
+### Step 1: Install dependencies
+
+Add `react-google-recaptcha` and its type definitions:
+
+```bash
+pnpm add react-google-recaptcha
+pnpm add -D @types/react-google-recaptcha
+```
+
+### Step 2: Add the reCAPTCHA server library
+
+Create `core/lib/recaptcha/constants.ts`:
+
+```ts
+export interface ReCaptchaSettings {
+  isEnabledOnStorefront: boolean;
+  siteKey: string;
+}
+
+export const RECAPTCHA_TOKEN_FORM_KEY = "g-recaptcha-response";
+```
+
+Create `core/lib/recaptcha.ts` with the server-side helpers for fetching reCAPTCHA settings, extracting the token from form data, and asserting the token is present. See the file in this release for the full implementation.
+
+### Step 3: Add reCAPTCHA translation strings
+
+Update `core/messages/en.json` to add the `recaptchaRequired` message in each form namespace:
+
+```diff
+  "Auth": {
+    "Register": {
++     "recaptchaRequired": "Please complete the reCAPTCHA verification.",
+```
+
+```diff
+  "Product": {
+    "Reviews": {
+      "Form": {
++       "recaptchaRequired": "Please complete the reCAPTCHA verification.",
+```
+
+```diff
+  "WebPages": {
+    "ContactUs": {
+      "Form": {
++       "recaptchaRequired": "Please complete the reCAPTCHA verification.",
+```
+
+```diff
+  "Form": {
++   "recaptchaRequired": "Please complete the reCAPTCHA verification.",
+```
+
+### Step 4: Update GraphQL mutations to accept reCAPTCHA token
+
+Update `core/app/[locale]/(default)/(auth)/register/_actions/register-customer.ts`:
+
+```diff
++ import { assertRecaptchaTokenPresent, getRecaptchaFromForm } from '~/lib/recaptcha';
+  ...
+  const RegisterCustomerMutation = graphql(`
+-   mutation RegisterCustomerMutation($input: RegisterCustomerInput!) {
++   mutation RegisterCustomerMutation(
++     $input: RegisterCustomerInput!
++     $reCaptchaV2: ReCaptchaV2Input
++   ) {
+      customer {
+-       registerCustomer(input: $input) {
++       registerCustomer(input: $input, reCaptchaV2: $reCaptchaV2) {
+```
+
+Update `core/app/[locale]/(default)/product/[slug]/_actions/submit-review.ts`:
+
+```diff
++ import { assertRecaptchaTokenPresent, getRecaptchaFromForm } from '~/lib/recaptcha';
+  ...
+  const AddProductReviewMutation = graphql(`
+-   mutation AddProductReviewMutation($input: AddProductReviewInput!) {
++   mutation AddProductReviewMutation(
++     $input: AddProductReviewInput!
++     $reCaptchaV2: ReCaptchaV2Input
++   ) {
+      catalog {
+-       addProductReview(input: $input) {
++       addProductReview(input: $input, reCaptchaV2: $reCaptchaV2) {
+```
+
+Update `core/app/[locale]/(default)/webpages/[id]/contact/_actions/submit-contact-form.ts`:
+
+```diff
++ import { assertRecaptchaTokenPresent, getRecaptchaFromForm } from '~/lib/recaptcha';
+  ...
+  const SubmitContactUsMutation = graphql(`
+-   mutation SubmitContactUsMutation($input: SubmitContactUsInput!) {
+-     submitContactUs(input: $input) {
++   mutation SubmitContactUsMutation($input: SubmitContactUsInput!, $reCaptchaV2: ReCaptchaV2Input) {
++     submitContactUs(input: $input, reCaptchaV2: $reCaptchaV2) {
+```
+
+### Step 5: Add server-side reCAPTCHA validation to form actions
+
+In each of the three server actions above, add the validation block after the `parseWithZod` check and pass the token to the GraphQL mutation. For example in `register-customer.ts`:
+
+```diff
++   const { siteKey, token } = await getRecaptchaFromForm(formData);
++   const recaptchaValidation = assertRecaptchaTokenPresent(siteKey, token, t('recaptchaRequired'));
++
++   if (!recaptchaValidation.success) {
++     return {
++       lastResult: submission.reply({ formErrors: recaptchaValidation.formErrors }),
++     };
++   }
+    ...
+    const response = await client.fetch({
+      document: RegisterCustomerMutation,
+      variables: {
+        input,
++       reCaptchaV2:
++         recaptchaValidation.token != null ? { token: recaptchaValidation.token } : undefined,
+      },
+```
+
+Apply the same pattern to `submit-review.ts` and `submit-contact-form.ts`.
+
+### Step 6: Pass `recaptchaSiteKey` to form components
+
+Fetch the site key in each page and pass it down through the component tree.
+
+Update `core/app/[locale]/(default)/(auth)/register/page.tsx`:
+
+```diff
++ import { getRecaptchaSiteKey } from '~/lib/recaptcha';
+  ...
++ const recaptchaSiteKey = await getRecaptchaSiteKey();
+  ...
+  <DynamicFormSection
++   recaptchaSiteKey={recaptchaSiteKey}
+```
+
+Update `core/app/[locale]/(default)/product/[slug]/page.tsx`:
+
+```diff
++ import { getRecaptchaSiteKey } from '~/lib/recaptcha';
+  ...
+- const { product: baseProduct, settings } = await getProduct(productId, customerAccessToken);
++ const [{ product: baseProduct, settings }, recaptchaSiteKey] = await Promise.all([
++   getProduct(productId, customerAccessToken),
++   getRecaptchaSiteKey(),
++ ]);
+  ...
+  <ProductDetail
++   recaptchaSiteKey={recaptchaSiteKey}
+  ...
+  <Reviews
++   recaptchaSiteKey={recaptchaSiteKey}
+```
+
+Update `core/app/[locale]/(default)/webpages/[id]/contact/page.tsx`:
+
+```diff
++ import { getRecaptchaSiteKey } from '~/lib/recaptcha';
+  ...
++ const recaptchaSiteKey = await getRecaptchaSiteKey();
+  ...
+  <DynamicForm
++   recaptchaSiteKey={recaptchaSiteKey}
+```
+
+### Step 7: Render the reCAPTCHA widget in form components
+
+Update `core/vibes/soul/form/dynamic-form/index.tsx`:
+
+```diff
++ import RecaptchaWidget from 'react-google-recaptcha';
+  ...
+  export interface DynamicFormProps<F extends Field> {
++   recaptchaSiteKey?: string;
+  }
+  ...
++         {recaptchaSiteKey ? <RecaptchaWidget sitekey={recaptchaSiteKey} /> : null}
+```
+
+Update `core/vibes/soul/sections/reviews/review-form.tsx`:
+
+```diff
++ import RecaptchaWidget from 'react-google-recaptcha';
+  ...
+  interface Props {
++   recaptchaSiteKey?: string;
+  }
+  ...
++           {recaptchaSiteKey ? (
++             <div>
++               <RecaptchaWidget sitekey={recaptchaSiteKey} />
++             </div>
++           ) : null}
+```
+
+### Step 8: Thread `recaptchaSiteKey` through intermediate components
+
+Add the `recaptchaSiteKey?: string` prop and pass it through in:
+
+- `core/vibes/soul/sections/dynamic-form-section/index.tsx`
+- `core/vibes/soul/sections/product-detail/index.tsx`
+- `core/vibes/soul/sections/reviews/index.tsx`
+- `core/app/[locale]/(default)/product/[slug]/_components/reviews.tsx`
+
+Each of these accepts the prop and forwards it to the form component that renders the widget.

core/app/[locale]/(default)/(auth)/register/_actions/register-customer.ts

@@ -14,13 +14,17 @@ import { graphql, VariablesOf } from '~/client/graphql';
 import { FieldNameToFieldId } from '~/data-transformers/form-field-transformer/utils';
 import { redirect } from '~/i18n/routing';
 import { getCartId } from '~/lib/cart';
+import { assertRecaptchaTokenPresent, getRecaptchaFromForm } from '~/lib/recaptcha';
 
 import { ADDRESS_FIELDS_NAME_PREFIX, CUSTOMER_FIELDS_NAME_PREFIX } from './prefixes';
 
 const RegisterCustomerMutation = graphql(`
-  mutation RegisterCustomerMutation($input: RegisterCustomerInput!) {
+  mutation RegisterCustomerMutation(
+    $input: RegisterCustomerInput!
+    $reCaptchaV2: ReCaptchaV2Input
+  ) {
     customer {
-      registerCustomer(input: $input) {
+      registerCustomer(input: $input, reCaptchaV2: $reCaptchaV2) {
         customer {
           firstName
           lastName
@@ -356,12 +360,23 @@ export async function registerCustomer<F extends Field>(
     };
   }
 
+  const { siteKey, token } = await getRecaptchaFromForm(formData);
+  const recaptchaValidation = assertRecaptchaTokenPresent(siteKey, token, t('recaptchaRequired'));
+
+  if (!recaptchaValidation.success) {
+    return {
+      lastResult: submission.reply({ formErrors: recaptchaValidation.formErrors }),
+    };
+  }
+
   try {
     const input = parseRegisterCustomerInput(submission.value, fields);
     const response = await client.fetch({
       document: RegisterCustomerMutation,
       variables: {
         input,
+        reCaptchaV2:
+          recaptchaValidation.token != null ? { token: recaptchaValidation.token } : undefined,
       },
       fetchOptions: { cache: 'no-store' },
     });

core/app/[locale]/(default)/(auth)/register/page.tsx

@@ -13,6 +13,7 @@ import {
   REGISTER_CUSTOMER_FORM_LAYOUT,
   transformFieldsToLayout,
 } from '~/data-transformers/form-field-transformer/utils';
+import { getRecaptchaSiteKey } from '~/lib/recaptcha';
 import { exists } from '~/lib/utils';
 
 import { ADDRESS_FIELDS_NAME_PREFIX, CUSTOMER_FIELDS_NAME_PREFIX } from './_actions/prefixes';
@@ -63,6 +64,8 @@ export default async function Register({ params }: Props) {
   const { addressFields, customerFields, countries, passwordComplexitySettings } =
     registerCustomerData;
 
+  const recaptchaSiteKey = await getRecaptchaSiteKey();
+
   const fields = transformFieldsToLayout(
     [
       ...addressFields.map((field) => {
@@ -154,6 +157,7 @@ export default async function Register({ params }: Props) {
       }}
       fields={fields}
       passwordComplexity={passwordComplexitySettings}
+      recaptchaSiteKey={recaptchaSiteKey}
       submitLabel={t('cta')}
       title={t('heading')}
     />

core/app/[locale]/(default)/product/[slug]/_actions/submit-review.ts

@@ -9,11 +9,15 @@ import { schema } from '@/vibes/soul/sections/reviews/schema';
 import { getSessionCustomerAccessToken } from '~/auth';
 import { client } from '~/client';
 import { graphql } from '~/client/graphql';
+import { assertRecaptchaTokenPresent, getRecaptchaFromForm } from '~/lib/recaptcha';
 
 const AddProductReviewMutation = graphql(`
-  mutation AddProductReviewMutation($input: AddProductReviewInput!) {
+  mutation AddProductReviewMutation(
+    $input: AddProductReviewInput!
+    $reCaptchaV2: ReCaptchaV2Input
+  ) {
     catalog {
-      addProductReview(input: $input) {
+      addProductReview(input: $input, reCaptchaV2: $reCaptchaV2) {
         __typename
         errors {
           __typename
@@ -38,6 +42,16 @@ export async function submitReview(
     return { ...prevState, lastResult: submission.reply() };
   }
 
+  const { siteKey, token } = await getRecaptchaFromForm(payload);
+  const recaptchaValidation = assertRecaptchaTokenPresent(siteKey, token, t('recaptchaRequired'));
+
+  if (!recaptchaValidation.success) {
+    return {
+      ...prevState,
+      lastResult: submission.reply({ formErrors: recaptchaValidation.formErrors }),
+    };
+  }
+
   const { productEntityId, ...input } = submission.value;
 
   try {
@@ -52,6 +66,8 @@ export async function submitReview(
           },
           productEntityId,
         },
+        reCaptchaV2:
+          recaptchaValidation.token != null ? { token: recaptchaValidation.token } : undefined,
       },
     });
 

core/app/[locale]/(default)/product/[slug]/_components/reviews.tsx

@@ -82,13 +82,15 @@ interface Props {
     pageInfo?: { hasNextPage: boolean; endCursor: string | null };
   }>;
   streamableProduct: Streamable<Awaited<ReturnType<typeof getStreamableProduct>>>;
+  recaptchaSiteKey?: string;
 }
 
 export const Reviews = async ({
   productId,
   searchParams,
   streamableProduct,
   streamableImages,
+  recaptchaSiteKey,
 }: Props) => {
   const t = await getTranslations('Product.Reviews');
 
@@ -189,6 +191,7 @@ export const Reviews = async ({
         paginationInfo={streamablePaginationInfo}
         previousLabel={t('previous')}
         productId={productId}
+        recaptchaSiteKey={recaptchaSiteKey}
         reviews={streamableReviews}
         reviewsLabel={t('title')}
         streamableImages={streamableImages}

core/app/[locale]/(default)/product/[slug]/page.tsx

@@ -12,6 +12,7 @@ import { pricesTransformer } from '~/data-transformers/prices-transformer';
 import { productCardTransformer } from '~/data-transformers/product-card-transformer';
 import { productOptionsTransformer } from '~/data-transformers/product-options-transformer';
 import { getPreferredCurrencyCode } from '~/lib/currency';
+import { getRecaptchaSiteKey } from '~/lib/recaptcha';
 import { getMetadataAlternates } from '~/lib/seo/canonical';
 
 import { addToCart } from './_actions/add-to-cart';
@@ -76,7 +77,10 @@ export default async function Product({ params, searchParams }: Props) {
 
   const productId = Number(slug);
 
-  const { product: baseProduct, settings } = await getProduct(productId, customerAccessToken);
+  const [{ product: baseProduct, settings }, recaptchaSiteKey] = await Promise.all([
+    getProduct(productId, customerAccessToken),
+    getRecaptchaSiteKey(),
+  ]);
 
   const reviewsEnabled = Boolean(settings?.reviews.enabled && !settings.display.showProductRating);
   const showRating = Boolean(settings?.reviews.enabled && settings.display.showProductRating);
@@ -581,6 +585,7 @@ export default async function Product({ params, searchParams }: Props) {
             backorderDisplayData: streamableBackorderDisplayData,
           }}
           quantityLabel={t('ProductDetails.quantity')}
+          recaptchaSiteKey={recaptchaSiteKey}
           reviewFormAction={submitReview}
           thumbnailLabel={t('ProductDetails.thumbnail')}
           user={streamableUser}
@@ -602,6 +607,7 @@ export default async function Product({ params, searchParams }: Props) {
         <div id="reviews">
           <Reviews
             productId={productId}
+            recaptchaSiteKey={recaptchaSiteKey}
             searchParams={searchParams}
             streamableImages={streamableImages}
             streamableProduct={streamableProduct}