core.bones.captcha
==================

.. py:module:: core.bones.captcha


Classes
-------

.. autoapisummary::

   core.bones.captcha.CaptchaBone


Module Contents
---------------

.. py:class:: CaptchaBone(*, public_key = None, score_threshold = 0.5, render_challenge = False, recaptcha_action = '', **kwargs)

   Bases: :py:obj:`viur.core.bones.base.BaseBone`


   The CaptchaBone validates reCAPTCHA Enterprise tokens to protect forms from bots.

   It uses the Google reCAPTCHA Enterprise API and supports both invisible (v3-style score-based)
   and visible (checkbox widget) challenges via the ``render_challenge`` parameter.

   The token is submitted by the client as the bone's field value and verified server-side
   against the configured site key. A configurable score threshold determines whether
   invisible challenges pass.

   .. seealso::

       `Google reCAPTCHA Enterprise setup
       <https://cloud.google.com/recaptcha/docs/set-up-non-google-cloud-environments-api-keys>`
       for creating a site key and enabling the API.

       Option :attr:`core.config.Security.captcha_default_public_key`
       for global security settings.

       Option :attr:`core.config.Security.captcha_enforce_always`
       to enforce validation even on development servers.

   Initializes a new CaptchaBone.

   :param public_key: The reCAPTCHA Enterprise site key shown to the client.
       Can be omitted if set globally via :attr:`core.config.Security.captcha_default_public_key`.
   :param score_threshold: Minimum score (0–1) required for invisible challenges to pass.
       Ignored when ``render_challenge`` is ``True``.
   :param render_challenge: If ``True``, renders a visible checkbox widget instead of
       running an invisible background check.
   :param recaptcha_action: The action name passed to reCAPTCHA for analytics and scoring.
       Should match the action used on the client side.


   .. py:attribute:: type
      :value: 'captcha'



   .. py:attribute:: public_key
      :value: None



   .. py:attribute:: render_challenge
      :value: False



   .. py:attribute:: recaptcha_action
      :value: ''



   .. py:attribute:: score_threshold
      :value: 0.5



   .. py:attribute:: required
      :value: True



   .. py:method:: serialize(skel, name, parentIndexed)

      Serializing the Captcha bone is not possible so it return False



   .. py:method:: unserialize(skel, name)

      Stores the public_key in the SkeletonInstance

      :param skel: The target :class:`SkeletonInstance`.
      :param name: The name of the CaptchaBone in the :class:`SkeletonInstance`.

      :returns: boolean, that is true, as the Captcha bone is always unserialized successfully.



   .. py:method:: fromClient(skel, name, data)

      Load the reCAPTCHA token from the provided data and validate it with the help of the API.

      reCAPTCHA provides the token via callback usually as "g-recaptcha-response",
      but to fit into the skeleton logic, we support both names.
      So the token can be provided as "g-recaptcha-response" or the name of the CaptchaBone in the Skeleton.
      While the latter one is the preferred name.



   .. py:method:: structure()

      Describes the bone and its settings as an JSON-serializable dict.
      This function has to be implemented for subsequent, specialized bone types.