Server-side validation for v3 recaptcha response

fix biscolab#69
- server side validation of the recaptcha v3 verify response.
- validator now returns true/false
- validator checks action if specified
- validator checks challenge_ts within 2 minutes
- validator has configurable parameters for threshold of score and action
- js object with execute method able to be generated which can facilitate promise based calling

src/Facades/ReCaptcha.php

@@ -17,6 +17,8 @@
  * @package Biscolab\ReCaptcha\Facades
  *
  * @method static string htmlScriptTagJsApi(?array $config = [])
+ * @method static string htmlScriptTagJsObjectV3()
+ * @method static string htmlScriptTagJsObjectV3WithDependency()
  * @method static string htmlFormButton(?string $button_label = '', ?array $properties = [])
  * @method static string htmlFormSnippet()
  * @method static string getFormId()

src/ReCaptchaBuilder.php

@@ -293,6 +293,32 @@ public function htmlScriptTagJsApi(?array $configuration = []): string
         return $html;
     }
 
+    /**
+     * Writes a HTML script tag that exposes a ReCaptchaV3 object for resolving the reCAPTCHA token.
+     * Insert this before the closing </head> tag, following the htmlScriptTagJsApi call, as it does not load the reCAPTCHA script.
+     *
+     * The ReCaptchaV3 object in JavaScript has a method called execute that returns a promise resolving with a reCAPTCHA token.
+     *   - action: string, defaults to 'homepage'.
+     *     You may set this to a specific action, such as "contact_form_submit", based on the user's action.
+     *
+     * @return string The generated script HTML tag.
+     */
+    public function htmlScriptTagJsObjectV3(): string
+    {
+        return '<!-- htmlScriptTagJsObjectV3 is not implemented for other versions. -->';
+    }
+
+    /***
+     * The same as htmlScriptTagJsObjectV3 but it loads the reCAPTCHA script if the user is not skipped by IP.
+     * Can be used if you only want to include on specific pages but not send on page load.
+     *
+     * @return string
+     */
+    public function htmlScriptTagJsObjectV3WithDependency(): string
+    {
+        return '<!-- htmlScriptTagJsObjectV3WithDependency is not implemented for other versions. -->';
+    }
+
     /**
      * Call out to reCAPTCHA and process the response
      *
@@ -302,7 +328,7 @@ public function htmlScriptTagJsApi(?array $configuration = []): string
      */
     public function validate($response)
     {
-
+        // info("Recaptcha Validation called: ".$response);
         if ($this->skip_by_ip) {
             if ($this->returnArray()) {
                 // Add 'skip_by_ip' field to response
@@ -349,6 +375,7 @@ public function validate($response)
             return false;
         }
         $response = json_decode(trim($curl_response), true);
+        //info('Response from recaptcha'.json_encode($response));
 
         if ($this->returnArray()) {
             return $response;

src/ReCaptchaBuilderV3.php

@@ -63,6 +63,8 @@ public function getValidationUrlWithToken(): string
      * Write script HTML tag in you HTML code
      * Insert before </head> tag
      *
+     * I suspect that this is used to inform reCAPTCHA about the page load.
+     *
      * @param array|null $configuration
      *
      * @return string
@@ -118,4 +120,62 @@ public function htmlScriptTagJsApi(?array $configuration = []): string
 
         return $html;
     }
+
+    /**
+     * Writes a HTML script tag that exposes a ReCaptchaV3 object for resolving the reCAPTCHA token.
+     * Insert this before the closing </head> tag, following the htmlScriptTagJsApi call, as it does not load the reCAPTCHA script.
+     *
+     * The ReCaptchaV3 object in JavaScript has a method called execute that returns a promise resolving with a reCAPTCHA token.
+     *   - action: string, defaults to 'homepage'.
+     *     You may set this to a specific action, such as "contact_form_submit", based on the user's action.
+     *
+     * @return string The generated script HTML tag.
+     */
+    public function htmlScriptTagJsObjectV3(): string
+    {
+        $html = '';
+        if ($this->skip_by_ip) {
+            $html .= "<script>
+                  ReCaptchaV3 = {
+                      execute: async (action = 'homepage') => return 'skip_by_ip'
+                  };
+		     </script>";
+            return $html;
+        }
+
+        $html .= "<script>
+                  ReCaptchaV3 = {
+                      execute: async (action = 'homepage') => {
+                          return new Promise((resolve, reject) => {
+                              grecaptcha.ready(function() {
+                                  grecaptcha.execute('{$this->api_site_key}', {action: action})
+                                  .then(token => resolve(token))
+                                  .catch(err => reject(err));
+                              })
+                          });
+                      }
+                    };
+		     </script>";
+
+        return $html;
+    }
+
+    /***
+     * The same as htmlScriptTagJsObjectV3 but it loads the reCAPTCHA script if the user is not skipped by IP.
+     * Can be used if you only want to include on specific pages but not send on page load.
+     *
+     * @return string
+     */
+    public function htmlScriptTagJsObjectV3WithDependency(): string
+    {
+        $html = '';
+        if (!$this->skip_by_ip) {
+            $html = "<script src=\"".$this->api_js_url."?render={$this->api_site_key}\"></script>";
+            return $html;
+        }
+        $html .= $this->htmlScriptTagJsObjectV3();
+
+        return $html;
+    }
+
 }

src/ReCaptchaServiceProvider.php

@@ -14,6 +14,7 @@
 use Illuminate\Support\Facades\Route;
 use Illuminate\Support\Facades\Validator;
 use Illuminate\Support\ServiceProvider;
+use Illuminate\Support\Carbon;
 
 /**
  * Class ReCaptchaServiceProvider
@@ -52,10 +53,46 @@ public function addValidationRule()
         if (!config('recaptcha.empty_message')) {
             $message = trans(config('recaptcha.error_message_key'));
         }
-        Validator::extendImplicit(recaptchaRuleName(), function ($attribute, $value) {
 
-            return app('recaptcha')->validate($value);
-        }, $message);
+        switch (config('recaptcha.version')) {
+            case 'v3':
+                Validator::extendImplicit(recaptchaRuleName(), function ($attribute, $value, $parameters) {
+                    $threshold = floatval($parameters[0] ?? 0.5);
+                    $action = $parameters[1] ?? '';
+
+                    $response = app('recaptcha')->validate($value);
+                    // info("recaptcha response is: ".json_encode($response));
+                    if (isset($response['skip_by_ip']) && filled($response['skip_by_ip'])) {
+                        return true;
+                    }
+
+                    // Verify action if present.
+                    if (filled($action) && isset($response['action']) && $response['action'] !== $action) {
+                        // info("recaptcha action verification failed");
+                        return false;
+                    }
+
+                    // Verify that challenge_ts is within the last 2 minutes if present.
+                    if (isset($response['challenge_ts']) && filled($response['challenge_ts'])) {
+                        $challengeTimestamp = Carbon::parse($response['challenge_ts']);
+                        $currentTimestamp = Carbon::now();
+                        if ($challengeTimestamp->diffInMinutes($currentTimestamp) > 2) {
+                            // info("recaptcha challenge_ts verification failed");
+                            return false;
+                        }
+                    }
+
+                    return (isset($response['success']) && isset($response['score']) && $response['success']
+                        && $response['score'] >= $threshold);
+                }, $message);
+                break;
+            case 'v2':
+            case 'invisible':
+                Validator::extendImplicit(recaptchaRuleName(), function ($attribute, $value) {
+                    return app('recaptcha')->validate($value);
+                }, $message);
+                break;
+        }
     }
 
     /**

src/helpers.php

@@ -43,6 +43,41 @@ function htmlScriptTagJsApi(?array $config = []): string
     }
 }
 
+
+if (!function_exists('htmlScriptTagJsObjectV3')) {
+    /**
+     * Writes a HTML script tag that exposes a ReCaptchaV3 object for resolving the reCAPTCHA token.
+     * Insert this before the closing </head> tag, following the htmlScriptTagJsApi call, as it does not load the reCAPTCHA script.
+     *
+     * The ReCaptchaV3 object in JavaScript has a method called execute that returns a promise resolving with a reCAPTCHA token.
+     *   - action: string, defaults to 'homepage'.
+     *     You may set this to a specific action, such as "contact_form_submit", based on the user's action.
+     *
+     * Note: This is only valid for v3.
+     *
+     * @return string The generated script HTML tag.
+     */
+    function htmlScriptTagJsObjectV3(): string
+    {
+        return ReCaptcha::htmlScriptTagJsObjectV3();
+    }
+}
+
+
+if (!function_exists('htmlScriptTagJsObjectV3WithDependency')) {
+    /***
+     * The same as htmlScriptTagJsObjectV3 but it loads the reCAPTCHA script if the user is not skipped by IP.
+     * Can be used if you only want to include on specific pages but not send on page load.
+     *
+     * @return string
+     */
+    function htmlScriptTagJsObjectV3WithDependency(): string
+    {
+        return ReCaptcha::htmlScriptTagJsObjectV3WithDependency();
+    }
+}
+
+
 /**
  * call ReCaptcha::htmlFormButton()
  * Write HTML <button> tag in your HTML code