Add appservice-double-puppet service for better bridge double-puppeting

Bridges will be switched to this new method in future patches.

docs/configuring-playbook-appservice-double-puppet.md

@@ -0,0 +1,15 @@
+# Setting up Appservice Double Puppet (optional)
+
+Appservice Double Puppet is a homeserver appservice through which bridges (and potentially other services) can impersonate any user on the homeserver.
+
+This is useful for performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) via the [appservice method](https://docs.mau.fi/bridges/general/double-puppeting.html#appservice-method-new). The Appservice Double Puppet service is an implementation of this approach.
+
+Previously, bridges supported performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but this old and hacky solution has been superseded by this Appservice Double Puppet method.
+
+To enable the Appservice Double Puppet service, adjust your `vars.yml` configuration like this and [re-run the playbook](./installing.md) (`just install-all`):
+
+```yml
+matrix_appservice_double_puppet_enabled: true
+```
+
+When enabled, double puppeting will automatically be enabled for all bridges that support double puppeting via the appservice method.

docs/configuring-playbook.md

@@ -89,6 +89,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 ### Authentication and user-related
 
+- [Setting up Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) (optional)
+
 - [Setting up an ma1sd Identity Server](configuring-playbook-ma1sd.md) (optional)
 
 - [Setting up Synapse Admin](configuring-playbook-synapse-admin.md) (optional)

group_vars/matrix_servers

@@ -84,6 +84,8 @@ matrix_homeserver_container_extra_arguments_auto: |
     +
     (['--mount type=bind,src=' + matrix_appservice_draupnir_for_all_config_path + '/draupnir-for-all-registration.yaml,dst=/matrix-appservice-draupnir-for-all-registration.yaml,ro'] if matrix_appservice_draupnir_for_all_enabled else [])
     +
+    (['--mount type=bind,src=' + matrix_appservice_double_puppet_config_path + '/registration.yaml,dst=/matrix-appservice-double-puppet-registration.yaml,ro'] if matrix_appservice_double_puppet_enabled else [])
+    +
     (['--mount type=bind,src=' + matrix_appservice_irc_config_path + '/registration.yaml,dst=/matrix-appservice-irc-registration.yaml,ro'] if matrix_appservice_irc_enabled else [])
     +
     (['--mount type=bind,src=' + matrix_appservice_kakaotalk_config_path + '/registration.yaml,dst=/matrix-appservice-kakaotalk-registration.yaml,ro'] if matrix_appservice_kakaotalk_enabled else [])
@@ -155,6 +157,8 @@ matrix_homeserver_app_service_config_files_auto: |
     +
     (['/matrix-appservice-draupnir-for-all-registration.yaml'] if matrix_appservice_draupnir_for_all_enabled else [])
     +
+    (['/matrix-appservice-double-puppet-registration.yaml'] if matrix_appservice_double_puppet_enabled else [])
+    +
     (['/matrix-appservice-irc-registration.yaml'] if matrix_appservice_irc_enabled else [])
     +
     (['/matrix-appservice-kakaotalk-registration.yaml'] if matrix_appservice_kakaotalk_enabled else [])
@@ -2891,6 +2895,24 @@ matrix_appservice_draupnir_for_all_database_password: "{{ '%s' | format(matrix_h
 ######################################################################
 
 
+######################################################################
+#
+# matrix-appservice-double-puppet
+#
+######################################################################
+
+matrix_appservice_double_puppet_enabled: false
+
+matrix_appservice_double_puppet_registration_as_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'as.doub.pup', rounds=655555) | to_uuid }}"
+matrix_appservice_double_puppet_registration_hs_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'hs.doub.pup', rounds=655555) | to_uuid }}"
+
+######################################################################
+#
+# /matrix-appservice-double-puppet
+#
+######################################################################
+
+
 ######################################################################
 #
 # matrix-pantalaimon

roles/custom/matrix-appservice-double-puppet/defaults/main.yml

@@ -0,0 +1,38 @@
+matrix_appservice_double_puppet_enabled: true
+
+matrix_appservice_double_puppet_base_path: "{{ matrix_base_data_path }}/appservice-double-puppet"
+matrix_appservice_double_puppet_config_path: "{{ matrix_appservice_double_puppet_base_path }}/config"
+
+matrix_appservice_double_puppet_registration_id: double-puppet
+matrix_appservice_double_puppet_registration_url: ~
+matrix_appservice_double_puppet_registration_as_token: ''
+matrix_appservice_double_puppet_registration_hs_token: ''
+matrix_appservice_double_puppet_registration_sender_localpart: appservice-double-puppet
+
+matrix_appservice_double_puppet_registration_namespace_user_regex: "{{ '@.*:' + (matrix_domain | regex_escape) }}"
+
+# Default matrix-appservice-double-puppet registration configuration template which covers the generic use case.
+# You can customize it by controlling the various variables inside it.
+#
+# For a more advanced customization, you can extend the default (see `matrix_appservice_double_puppet_registration_configuration_extension_yaml`)
+# or completely replace this variable with your own template.
+matrix_appservice_double_puppet_registration_configuration_yaml: "{{ lookup('template', 'templates/registration.yaml.j2') }}"
+
+matrix_appservice_double_puppet_registration_configuration_extension_yaml: |
+  # Your custom YAML configuration for matrix-appservice-double-puppet goes here.
+  # This configuration extends the default starting configuration (`matrix_appservice_double_puppet_registration_configuration_yaml`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_appservice_double_puppet_registration_configuration_yaml`.
+  #
+  # Example configuration extension follows:
+  #
+  # rate_limited: true
+
+matrix_appservice_double_puppet_registration_configuration_extension: "{{ matrix_appservice_double_puppet_registration_configuration_extension_yaml | from_yaml if matrix_appservice_double_puppet_registration_configuration_extension_yaml | from_yaml is mapping else {} }}"
+
+# Holds the final matrix-appservice-double-puppet configuration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_appservice_double_puppet_registration_configuration_yaml`.
+matrix_appservice_double_puppet_registration_configuration: "{{ matrix_appservice_double_puppet_registration_configuration_yaml | from_yaml | combine(matrix_appservice_double_puppet_registration_configuration_extension, recursive=True) }}"

roles/custom/matrix-appservice-double-puppet/tasks/install.yml

@@ -0,0 +1,23 @@
+---
+
+- name: Ensure matrix-appservice-double-puppet paths exist
+  ansible.builtin.file:
+    path: "{{ item.path }}"
+    state: directory
+    mode: 0750
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - path: "{{ matrix_appservice_double_puppet_base_path }}"
+      when: true
+    - path: "{{ matrix_appservice_double_puppet_config_path }}"
+      when: true
+  when: item.when | bool
+
+- name: Ensure matrix-appservice-double-puppet registration configuration installed
+  ansible.builtin.copy:
+    content: "{{ matrix_appservice_double_puppet_registration_configuration | to_nice_yaml(indent=2, width=999999) }}"
+    dest: "{{ matrix_appservice_double_puppet_config_path }}/registration.yaml"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"

roles/custom/matrix-appservice-double-puppet/tasks/main.yml

@@ -0,0 +1,20 @@
+---
+
+- tags:
+    - setup-all
+    - setup-appservice-double-puppet
+    - install-all
+    - install-appservice-double-puppet
+  block:
+    - when: matrix_appservice_double_puppet_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
+
+    - when: matrix_appservice_double_puppet_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/install.yml"
+
+- tags:
+    - setup-all
+    - setup-appservice-double-puppet
+  block:
+    - when: not matrix_appservice_double_puppet_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/uninstall.yml"

roles/custom/matrix-appservice-double-puppet/tasks/uninstall.yml

@@ -0,0 +1,6 @@
+---
+
+- name: Ensure matrix-appservice-double-puppet paths don't exist
+  ansible.builtin.file:
+    path: "{{ matrix_appservice_double_puppet_base_path }}"
+    state: absent

roles/custom/matrix-appservice-double-puppet/tasks/validate_config.yml

@@ -0,0 +1,10 @@
+---
+- name: Fail if required matrix-appservice-double-puppet settings not defined
+  ansible.builtin.fail:
+    msg: >
+      You need to define a required configuration setting (`{{ item.name }}`).
+  when: "item.when | bool and vars[item.name] == ''"
+  with_items:
+    - {'name': 'matrix_appservice_double_puppet_registration_as_token', when: true}
+    - {'name': 'matrix_appservice_double_puppet_registration_as_token', when: true}
+    - {'name': 'matrix_appservice_double_puppet_registration_sender_localpart', when: true}

roles/custom/matrix-appservice-double-puppet/templates/registration.yaml.j2

@@ -0,0 +1,21 @@
+# The ID doesn't really matter, put whatever you want.
+id: {{ matrix_appservice_double_puppet_registration_id | to_json }}
+# The URL is intentionally left empty (null), as the homeserver shouldn't
+# push events anywhere for this extra appservice. If you use a
+# non-spec-compliant server, you may need to put some fake URL here.
+url: {{ matrix_appservice_double_puppet_registration_url | to_json }}
+# Generate random strings for these three fields. Only the as_token really
+# matters, hs_token is never used because there's no url, and the default
+# user (sender_localpart) is never used either.
+as_token: {{ matrix_appservice_double_puppet_registration_as_token | to_json }}
+hs_token: {{ matrix_appservice_double_puppet_registration_hs_token | to_json }}
+sender_localpart: {{ matrix_appservice_double_puppet_registration_sender_localpart | to_json}}
+# Bridges don't like ratelimiting. This should only apply when using the
+# as_token, normal user tokens will still be ratelimited.
+rate_limited: false
+namespaces:
+  users:
+  # Replace your\.domain with your server name (escape dots for regex)
+  - regex: {{ matrix_appservice_double_puppet_registration_namespace_user_regex | to_json }}
+    # This must be false so the appservice doesn't take over all users completely.
+    exclusive: false

setup.yml

@@ -51,6 +51,7 @@
     - galaxy/keydb
     - custom/matrix-corporal
     - custom/matrix-appservice-draupnir-for-all
+    - custom/matrix-appservice-double-puppet
     - custom/matrix-alertmanager-receiver
     - custom/matrix-bridge-appservice-discord
     - custom/matrix-bridge-appservice-slack