payload-recaptcha-v3 v2.0.1

Payload reCAPTCHA v3 Plugin

A plugin for Payload to protect collection's operations using Google reCAPTCHA v3.

Installation

Please install the plugin version according to the Payload version. The major version of the plugin must match the major version of the Payload.

yarn add payload-recaptcha-v3
# OR
npm i payload-recaptcha-v3

Configuration

In the plugins array of your Payload config, call the plugin with options:

import { buildConfig } from 'payload/config';
import reCAPTCHAv3 from 'payload-recaptcha-v3';

const config = buildConfig({
	// ... rest of your config
	plugins: [
		reCAPTCHAv3({
			secret: process.env.GOOGLE_RECAPTCHA_SECRET,
		}),
	],
});

export default config;

Plugin Options

• secret: string

  Required. Your Google reCAPTCHA v3 secret key.

• errorHandler: reCAPTCHAErrorHandler

  Optional. The function that throws the exception. By default, it throws Forbidden when the response from Google is not a success.

Usage

To protect a collection's operation, you have to add in the Collection Config the property recaptcha into the custom. The recaptcha property has to be an array of strings containing the operation name according to Available Collection operations.

import { CollectionConfig } from 'payload/types';

export const Orders: CollectionConfig = {
	slug: 'orders',
	fields: [],
	// ... rest of your config
	custom: {
		recaptcha: [
			{
				name: 'create',
				action: 'submit',
			},
			{
				name: 'update',
				action: 'modify',
			},
		],
	},
};

export default Orders;

Then, when you make an HTTP Request to the Payload API, include the header X-reCAPTCHA-V3 with the token received from Google:

   <script>
      function onClick(e) {
        e.preventDefault();
        grecaptcha.ready(function() {
          grecaptcha.execute('reCAPTCHA_site_key', {action: 'submit'}).then(function(token) {
            fetch('/api/orders', {
              method: 'POST',
              headers: {
                'X-reCAPTCHA-V3': token
              },
              body: JSON.stringify({...})
            })
          });
        });
      }
  </script>

Tests

Tests are using Jest, to run the tests use:

npm test

Types

reCAPTCHAErrorHandler

A function that has the purpose of throwing an exception depending on the response received from Google.

type reCAPTCHAErrorHandler = (response?: reCAPTCHAResponse) => void;

reCAPTCHAResponse

The response received from Google when verifying the token.

Properties

reCAPTCHAErrorCode