From a4ddba39892445fcba0e302f5e329e49f1ba762b Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Sun, 28 Jun 2026 19:52:24 +0300 Subject: [PATCH] mautrix-gmessages: expose bridge HTTP API (for mautrix-manager and similar) Add a generic mechanism for exposing bridges' HTTP API (the provisioning API, etc.) publicly on the Matrix domain, so tools like mautrix-manager (https://github.com/mautrix/manager) can drive bridge login. - Introduce global matrix_bridges_exposure_* vars (on by default), exposing each supported bridge under `/bridges/`. - mautrix-gmessages: make the provisioning shared secret configurable (auto-generated in group_vars) so the provisioning API is enabled, route the whole bridge HTTP port via Traefik, and populate appservice.public_address. Requests are authenticated by the bridge itself (per-user Matrix access token for the provisioning API, homeserver token for the appservice endpoints), not by the reverse proxy. This is the first bridge converted; the other mautrix bridges will follow. Co-Authored-By: Claude Opus 4.8 (1M context) --- group_vars/matrix_servers | 7 ++++ roles/custom/matrix-base/defaults/main.yml | 9 +++++ .../defaults/main.yml | 25 ++++++++++++++ .../templates/config.yaml.j2 | 4 +-- .../templates/labels.j2 | 33 +++++++++++++++++++ 5 files changed, 76 insertions(+), 2 deletions(-) diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index ef87a0a98..fbc620bbc 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -2195,6 +2195,8 @@ matrix_mautrix_gmessages_appservice_token: "{{ (matrix_homeserver_generic_secret matrix_mautrix_gmessages_homeserver_address: "{{ matrix_addons_homeserver_client_api_url }}" matrix_mautrix_gmessages_homeserver_token: "{{ (matrix_homeserver_generic_secret_key + ':gmessa.hs.token') | hash('sha512') | to_uuid }}" +matrix_mautrix_gmessages_provisioning_shared_secret: "{{ (matrix_homeserver_generic_secret_key + ':gmessa.prov') | hash('sha512') | to_uuid }}" + matrix_mautrix_gmessages_homeserver_async_media: "{{ matrix_homeserver_implementation in ['synapse'] }}" matrix_mautrix_gmessages_double_puppet_secrets_auto: |- @@ -2212,6 +2214,11 @@ matrix_mautrix_gmessages_metrics_proxying_enabled: "{{ matrix_mautrix_gmessages_ matrix_mautrix_gmessages_metrics_proxying_hostname: "{{ matrix_metrics_exposure_hostname }}" matrix_mautrix_gmessages_metrics_proxying_path_prefix: "{{ matrix_metrics_exposure_path_prefix }}/mautrix-gmessages" +matrix_mautrix_gmessages_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}" +matrix_mautrix_gmessages_exposure_enabled: "{{ matrix_bridges_exposure_enabled }}" +matrix_mautrix_gmessages_exposure_hostname: "{{ matrix_bridges_exposure_hostname }}" +matrix_mautrix_gmessages_exposure_path_prefix: "{{ matrix_bridges_exposure_path_prefix }}/gmessages" + # Postgres is the default, except if not using internal Postgres server matrix_mautrix_gmessages_database_engine: "{{ 'postgres' if postgres_enabled else 'sqlite' }}" matrix_mautrix_gmessages_database_hostname: "{{ postgres_connection_hostname if postgres_enabled else '' }}" diff --git a/roles/custom/matrix-base/defaults/main.yml b/roles/custom/matrix-base/defaults/main.yml index fd4eed773..f05017bc4 100644 --- a/roles/custom/matrix-base/defaults/main.yml +++ b/roles/custom/matrix-base/defaults/main.yml @@ -54,6 +54,15 @@ matrix_bridges_msc4190_enabled: "{{ matrix_authentication_service_enabled and ma # Global var for enabling bridge self-signing ( On supported bridges) matrix_bridges_self_sign_enabled: "{{ matrix_bridges_msc4190_enabled }}" +# Global vars for exposing bridges' HTTP API publicly on the Matrix domain. +# This is used by tools like mautrix-manager (https://github.com/mautrix/manager) to drive bridge login. +# Each supported bridge's HTTP endpoint is exposed under `/` (e.g. `/bridges/gmessages`). +# Requests are authenticated by the bridge itself (e.g. per-user Matrix access token for the provisioning API, +# or the homeserver token for the appservice endpoints), not by us. +matrix_bridges_exposure_enabled: true +matrix_bridges_exposure_hostname: "{{ matrix_server_fqn_matrix }}" +matrix_bridges_exposure_path_prefix: /bridges + # Global var to enable/disable relay mode across all bridges with relay mode support matrix_bridges_relay_enabled: false diff --git a/roles/custom/matrix-bridge-mautrix-gmessages/defaults/main.yml b/roles/custom/matrix-bridge-mautrix-gmessages/defaults/main.yml index 59cdbaca0..a6c695f94 100644 --- a/roles/custom/matrix-bridge-mautrix-gmessages/defaults/main.yml +++ b/roles/custom/matrix-bridge-mautrix-gmessages/defaults/main.yml @@ -38,6 +38,13 @@ matrix_mautrix_gmessages_homeserver_async_media: false matrix_mautrix_gmessages_homeserver_domain: "{{ matrix_domain }}" matrix_mautrix_gmessages_appservice_address: "http://matrix-mautrix-gmessages:8080" +# Scheme of the bridge's public address (see `matrix_mautrix_gmessages_bridge_public_address`). +matrix_mautrix_gmessages_scheme: https + +# The public base URL at which this bridge's HTTP API is reachable from outside (when exposed). +# Used for the provisioning API's external-server (OpenID) flow and for public media links. +matrix_mautrix_gmessages_bridge_public_address: "{{ (matrix_mautrix_gmessages_scheme + '://' + matrix_mautrix_gmessages_exposure_hostname + matrix_mautrix_gmessages_exposure_path_prefix) if matrix_mautrix_gmessages_exposure_enabled else '' }}" + matrix_mautrix_gmessages_msc4190_enabled: "{{ matrix_bridges_msc4190_enabled }}" matrix_mautrix_gmessages_self_sign_enabled: "{{ matrix_bridges_self_sign_enabled }}" @@ -75,6 +82,15 @@ matrix_mautrix_gmessages_container_labels_metrics_middleware_basic_auth_enabled: # See: https://doc.traefik.io/traefik/middlewares/http/basicauth/#users matrix_mautrix_gmessages_container_labels_metrics_middleware_basic_auth_users: '' +# Controls whether labels will be added that expose mautrix-gmessages' HTTP API +# (used by tools like mautrix-manager for bridge login) at `https://`. +matrix_mautrix_gmessages_container_labels_exposure_enabled: "{{ matrix_mautrix_gmessages_exposure_enabled }}" +matrix_mautrix_gmessages_container_labels_exposure_traefik_rule: "Host(`{{ matrix_mautrix_gmessages_exposure_hostname }}`) && PathPrefix(`{{ matrix_mautrix_gmessages_exposure_path_prefix }}`)" +matrix_mautrix_gmessages_container_labels_exposure_traefik_priority: 0 +matrix_mautrix_gmessages_container_labels_exposure_traefik_entrypoints: "{{ matrix_mautrix_gmessages_container_labels_traefik_entrypoints }}" +matrix_mautrix_gmessages_container_labels_exposure_traefik_tls: "{{ matrix_mautrix_gmessages_container_labels_exposure_traefik_entrypoints != 'web' }}" +matrix_mautrix_gmessages_container_labels_exposure_traefik_tls_certResolver: "{{ matrix_mautrix_gmessages_container_labels_traefik_tls_certResolver }}" # noqa var-naming + # matrix_mautrix_gmessages_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file. # See `../templates/labels.j2` for details. # @@ -119,6 +135,11 @@ matrix_mautrix_gmessages_metrics_proxying_enabled: false matrix_mautrix_gmessages_metrics_proxying_hostname: '' matrix_mautrix_gmessages_metrics_proxying_path_prefix: '' +# Controls whether mautrix-gmessages' HTTP API is exposed publicly (used by tools like mautrix-manager for bridge login). +matrix_mautrix_gmessages_exposure_enabled: false +matrix_mautrix_gmessages_exposure_hostname: '' +matrix_mautrix_gmessages_exposure_path_prefix: '' + # Database-related configuration fields. # # To use SQLite, stick to these defaults. @@ -168,6 +189,10 @@ matrix_mautrix_gmessages_appservice_username_template: "{% raw %}gmessages_{{.}} matrix_mautrix_gmessages_public_media_signing_key: '' +# Shared secret for authentication of provisioning API requests. +# If set to "disable", the provisioning API will be disabled. +matrix_mautrix_gmessages_provisioning_shared_secret: disable + matrix_mautrix_gmessages_bridge_personal_filtering_spaces: true matrix_mautrix_gmessages_bridge_permissions: | diff --git a/roles/custom/matrix-bridge-mautrix-gmessages/templates/config.yaml.j2 b/roles/custom/matrix-bridge-mautrix-gmessages/templates/config.yaml.j2 index ae87f818d..9e2aaad93 100644 --- a/roles/custom/matrix-bridge-mautrix-gmessages/templates/config.yaml.j2 +++ b/roles/custom/matrix-bridge-mautrix-gmessages/templates/config.yaml.j2 @@ -181,7 +181,7 @@ appservice: address: {{ matrix_mautrix_gmessages_appservice_address }} # A public address that external services can use to reach this appservice. # This value doesn't affect the registration file. - public_address: https://bridge.example.com + public_address: {{ matrix_mautrix_gmessages_bridge_public_address | to_json }} # The hostname and port where this appservice should listen. # For Docker, you generally have to change the hostname to 0.0.0.0. @@ -247,7 +247,7 @@ provisioning: prefix: /_matrix/provision # Shared secret for authentication. If set to "generate" or null, a random secret will be generated, # or if set to "disable", the provisioning API will be disabled. - shared_secret: disable + shared_secret: {{ matrix_mautrix_gmessages_provisioning_shared_secret | to_json }} # Whether to allow provisioning API requests to be authed using Matrix access tokens. # This follows the same rules as double puppeting to determine which server to contact to check the token, # which means that by default, it only works for users on the same server as the bridge. diff --git a/roles/custom/matrix-bridge-mautrix-gmessages/templates/labels.j2 b/roles/custom/matrix-bridge-mautrix-gmessages/templates/labels.j2 index 8dfe66067..282f7fb30 100644 --- a/roles/custom/matrix-bridge-mautrix-gmessages/templates/labels.j2 +++ b/roles/custom/matrix-bridge-mautrix-gmessages/templates/labels.j2 @@ -46,6 +46,39 @@ traefik.http.routers.matrix-mautrix-gmessages-metrics.tls.certResolver={{ matrix ############################################################ {% endif %} +{% if matrix_mautrix_gmessages_container_labels_exposure_enabled %} +############################################################ +# # +# Bridge API exposure # +# # +############################################################ + +traefik.http.services.matrix-mautrix-gmessages-exposure.loadbalancer.server.port=8080 + +traefik.http.middlewares.matrix-mautrix-gmessages-exposure-strip-prefix.stripprefix.prefixes={{ matrix_mautrix_gmessages_exposure_path_prefix }} +traefik.http.routers.matrix-mautrix-gmessages-exposure.middlewares=matrix-mautrix-gmessages-exposure-strip-prefix + +traefik.http.routers.matrix-mautrix-gmessages-exposure.rule={{ matrix_mautrix_gmessages_container_labels_exposure_traefik_rule }} + +{% if matrix_mautrix_gmessages_container_labels_exposure_traefik_priority | int > 0 %} +traefik.http.routers.matrix-mautrix-gmessages-exposure.priority={{ matrix_mautrix_gmessages_container_labels_exposure_traefik_priority }} +{% endif %} + +traefik.http.routers.matrix-mautrix-gmessages-exposure.service=matrix-mautrix-gmessages-exposure +traefik.http.routers.matrix-mautrix-gmessages-exposure.entrypoints={{ matrix_mautrix_gmessages_container_labels_exposure_traefik_entrypoints }} + +traefik.http.routers.matrix-mautrix-gmessages-exposure.tls={{ matrix_mautrix_gmessages_container_labels_exposure_traefik_tls | to_json }} +{% if matrix_mautrix_gmessages_container_labels_exposure_traefik_tls %} +traefik.http.routers.matrix-mautrix-gmessages-exposure.tls.certResolver={{ matrix_mautrix_gmessages_container_labels_exposure_traefik_tls_certResolver }} +{% endif %} + +############################################################ +# # +# /Bridge API exposure # +# # +############################################################ +{% endif %} + {% endif %}