..  GENERATED FILE, DO NOT EDIT DIRECTLY

    This file is automatically generated using https://codeberg.org/slidge/legacy-module-template/
    Its source is at:
    https://codeberg.org/slidge/legacy-module-template/src/branch/main/docs/source/admin/privileges.rst.jinja
    Open a pull request for this repository instead, to benefit the documentation of all slidge-based gateways.


.. _privileges:

==========
Privileges
==========

.. note::

  ":xep:`0356`: Privileged Entity" only works for XMPP users using the same server as matridge, e.g., ``eve@example.org`` on ``matrix.example.org``.

Setting up matridge as a privileged entity (:xep:`0356`) is optional, but nice to have.
It improves user experience with a few "cherry on top" features.
By configuring your XMPP server such that matridge is a privileged entity, matridge can:

- automatically add/remove "puppet contacts" from the XMPP roster of matridge users,
- reflect on the XMPP side messages sent by users via official Matrix apps,
- (if using :ref:`upload` for attachments from Matrix to XMPP) request upload slots on behalf of matridge users,
  respecting any quota, retention, permission, or other policy set at the upload component level,
- synchronize other actions done via official Matrix apps, such as marking messages as read, using emoji reactions,
  retracting messages, sending files…
- automatically add XMPP bookmarks (:xep:`0402`) for MUCs (:xep:`0045`).

Server-specific instructions
============================

Prosŏdy
-------

Install the `mod_privilege <https://modules.prosody.im/mod_privilege.html>`_
community module with:

.. code-block:: bash

    prosodyctl install --server=https://modules.prosody.im/rocks/ mod_privilege

In ``prosody.cfg.lua``, add ``mod_privilege`` to the ``modules_enabled`` list, and
declare matridge privileges in the appropriate virtualhost block:

.. code-block:: lua

    local _privileges = {
      roster = "both";       -- for adding/removing contacts from the users' rosters
      message = "outgoing";  -- for reflecting messages sent by the user themselve from official Matrix apps
      iq = {
        ["http://jabber.org/protocol/pubsub"] = "both";      -- for PEP Bookmarks
        ["http://jabber.org/protocol/pubsub#owner"] = "set"; -- for Message Display Synchronization
        ["urn:xmpp:http:upload:0"] = "get";                  -- for HTTP Upload on behalf of users
      }
    };

    VirtualHost "example.org"
      privileged_entities = {
        ["matrix.example.org"] = _privileges;
      }

Then either restart the prosody server, or reload the config.
You might need to use
`mod_reload_component <https://modules.prosody.im/mod_reload_components.html>`_,
and activate/deactivate hosts
for all changes to be taken into account
(restarting prosody is the easiest way to go).

ejabberd
--------

.. code-block:: yaml

    acl:
      slidge_acl:
        server:
          - "matrix.example.org"

    access_rules:
      slidge_rule:
        - allow: slidge_acl

    modules:
      mod_privilege:
        roster:
          both: slidge_rule
        message:
          outgoing: slidge_rule
        iq:
          "http://jabber.org/protocol/pubsub":
            both: slidge_rule
          "http://jabber.org/protocol/pubsub#owner":
            set: slidge_rule
          "urn:xmpp:http:upload:0":
            get: slidge_rule
      mod_roster:
        versioning: true

Next step
=========

Learn about about matridge's :ref:`configuration <config>` to tune its behaviour to your liking.
