<commit_before>Customize your Imbo installation with event listeners
=====================================================

Imbo ships with a collection of event listeners for you to use. Some of them are enabled in the default configuration file. Image transformations are also technically event listeners, but will not be covered in this chapter. Read the :doc:`../usage/image-transformations` chapter for more information regarding the image transformations.

.. contents::
    :local:
    :depth: 1

.. _access-token-event-listener:

Access token
++++++++++++

This event listener enforces the usage of access tokens on all read requests against user-specific resources. You can read more about how the actual access tokens work in the :ref:`access-tokens` part of the :doc:`../usage/api` chapter.

To enforce the access token check this event listener subscribes to the following events:

* ``user.get``
* ``user.head``
* ``images.get``
* ``images.head``
* ``image.get``
* ``image.head``
* ``metadata.get``
* ``metadata.head``

This event listener has a single parameter that can be used to whitelist and/or blacklist certain image transformations, used when the current request is against an image resource. The parameter is an array with a single key: ``transformations``. This is another array with two keys: ``whitelist`` and ``blacklist``. These two values are arrays where you specify which transformation(s) to whitelist or blacklist. The names of the transformations are the same as the ones used in the request. See :ref:`image-transformations` for a complete list of the supported transformations.

Use ``whitelist`` if you want the listener to skip the access token check for certain transformations, and ``blacklist`` if you want it to only check certain transformations:

.. code-block:: php

    [
        'transformations' => [
            'whitelist' => [
                'border',
            ],
        ],
    ]

means that the access token will **not** be enforced for the :ref:`border <border-transformation>` transformation.

.. code-block:: php

    [
        'transformations' => [
            'blacklist' => [
                'border',
            ],
        ],
    ]

means that the access token will be enforced **only** for the :ref:`border <border-transformation>` transformation.

If both ``whitelist`` and ``blacklist`` are specified all transformations will require an access token unless it's included in ``whitelist``.

This event listener is included in the default configuration file without specifying any transformation filters:

.. code-block:: php

    <?php
    return [
        // ...

        'eventListeners' => [
            'accessToken' => 'Imbo\EventListener\AccessToken',
        ],

        // ...
    ];

Disable this event listener with care. Installations with no access token check is open for `DoS <http://en.wikipedia.org/wiki/Denial-of-service_attack>`_ attacks.

.. _authenticate-event-listener:

Authenticate
++++++++++++

This event listener enforces the usage of signatures on all write requests against user-specific resources. You can read more about how the actual signature check works in the :ref:`signing-write-requests` section in the :doc:`../usage/api` chapter.

To enforce the signature check for all write requests supported by Imbo this event listener subscribes to the following events:

* ``images.post``
* ``image.delete``
* ``metadata.put``
* ``metadata.post``
* ``metadata.delete``

This event listener does not support any parameters and is enabled per default like this:

.. code-block:: php

    <?php
    return [
        // ...

        'eventListeners' => [
            'auth' => 'Imbo\EventListener\Authenticate',<commit_msg>Add documentation section on custom access token generators<commit_after>Customize your Imbo installation with event listeners
=====================================================

Imbo ships with a collection of event listeners for you to use. Some of them are enabled in the default configuration file. Image transformations are also technically event listeners, but will not be covered in this chapter. Read the :doc:`../usage/image-transformations` chapter for more information regarding the image transformations.

.. contents::
    :local:
    :depth: 1

.. _access-token-event-listener:

Access token
++++++++++++

This event listener enforces the usage of access tokens on all read requests against user-specific resources. You can read more about how the actual access tokens work in the :ref:`access-tokens` part of the :doc:`../usage/api` chapter.

To enforce the access token check this event listener subscribes to the following events:

* ``user.get``
* ``user.head``
* ``images.get``
* ``images.head``
* ``image.get``
* ``image.head``
* ``metadata.get``
* ``metadata.head``

This event listener has a single parameter that can be used to whitelist and/or blacklist certain image transformations, used when the current request is against an image resource. The parameter is an array with a single key: ``transformations``. This is another array with two keys: ``whitelist`` and ``blacklist``. These two values are arrays where you specify which transformation(s) to whitelist or blacklist. The names of the transformations are the same as the ones used in the request. See :ref:`image-transformations` for a complete list of the supported transformations.

Use ``whitelist`` if you want the listener to skip the access token check for certain transformations, and ``blacklist`` if you want it to only check certain transformations:

.. code-block:: php

    [
        'transformations' => [
            'whitelist' => [
                'border',
            ],
        ],
    ]

means that the access token will **not** be enforced for the :ref:`border <border-transformation>` transformation.

.. code-block:: php

    [
        'transformations' => [
            'blacklist' => [
                'border',
            ],
        ],
    ]

means that the access token will be enforced **only** for the :ref:`border <border-transformation>` transformation.

If both ``whitelist`` and ``blacklist`` are specified all transformations will require an access token unless it's included in ``whitelist``.

This event listener is included in the default configuration file without specifying any transformation filters:

.. code-block:: php

    <?php
    return [
        // ...

        'eventListeners' => [
            'accessToken' => 'Imbo\EventListener\AccessToken',
        ],

        // ...
    ];

Disable this event listener with care. Installations with no access token check is open for `DoS <http://en.wikipedia.org/wiki/Denial-of-service_attack>`_ attacks.

.. _custom-access-token-generators:

Custom Access Token Generators
------------------------------

You can customize how the access token is generated and which URL parameter that contain the access token. The default implementation uses a SHA256 HMAC generated from the private key and the URL of the request.

To switch to a different access token generator provide a new generator in the ``accessTokenGenerator`` parameter. This generator must implement the AccessTokenInterface interface, available under EventListener\AccessToken\AccessTokenInterface. An abstract class (``AccessTokenGenerator``) is included that you can subclass to quickly implement an alternative signature algorithm.

To use a different algorithm, provide it as a key in the parameter array when creating the AccessToken event listener:

.. code-block:: php

    [
        'accessTokenGenerator' => new AccessToken\SHA256(),
    ]

You can also provide a list of URL argument names for the access token, if it's not available through the regular ``accessToken`` argument.

.. code-block:: php

    [
        'accessTokenGenerator' => new AccessToken\SHA256(['argumentKeys' => ['foo', 'accessToken']]),
    ]

.. which would allow the token to be present under either ``foo`` or ``accessToken`` in the URL arguments.

Imbo uses a SHA256 HMAC as the default signature generation algorithm, available under ``EventListener\AccessToken\SHA256``.


.. _authenticate-event-listener:

Authenticate
++++++++++++

This event listener enforces the usage of signatures on all write requests against user-specific resources. You can read more about how the actual signature check works in the :ref:`signing-write-requests` section in the :doc:`../usage/api` chapter.

To enforce the signature check for all write requests supported by Imbo this event listener subscribes to the following events:

* ``images.post``
* ``image.delete``
* ``metadata.put``
* ``metadata.post``
* ``metadata.delete``

This event listener does not support any parameters and is enabled per default like this:

.. code-block:: php

    <?php
    return [
        // ...

        'eventListeners' => [
            'auth' => 'Imbo\EventListener\Authenticate',
{'fraction_non_alphanumeric': 0.11096121416526138, 'fraction_numerical': 0.0019111860595840359, 'mean_word_length': 3.557377049180328, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 28, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3852924', 'n_tokens_mistral': 2242, 'n_tokens_neox': 2136, 'n_words': 1002}