From fa301881ea70a942c3637258c255a62bc39e254c Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 4 Nov 2019 20:45:37 +0000 Subject: [PATCH 01/22] Initial WIP of proposal --- proposals/xxxx-bridge-info-state-event.md | 91 +++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 proposals/xxxx-bridge-info-state-event.md diff --git a/proposals/xxxx-bridge-info-state-event.md b/proposals/xxxx-bridge-info-state-event.md new file mode 100644 index 00000000000..14e4145ec66 --- /dev/null +++ b/proposals/xxxx-bridge-info-state-event.md @@ -0,0 +1,91 @@ +### MSC XXXX: Bridge information state event + +Many rooms across the matrix network are currently bridged into other networks, using our bridging API. +However the specification does not contain a method to determine which networks are bridged into a given +room. Many users have taken to peeking at the list of aliases for a giveaway alias like `#freenode_` or +looking for bridge bots or users with a `@_discord_` prefix. + +This is an unacceptable situation. Users must know beforehand the names of IRC networks or protocols in order +to determine if a given ID is part of a bridge. The bridge cannot give away any infomation about itself +via Matrix. And blah blah blah. It alos allows bridges to be re-usable between different servers should we +want to go for the decentralised route one day. + +This proposal stands to fix, or partially fix the following issues: + - a bunch of riot projects that depend upon this + - a bunch of spec items too + +This proposal is heavily based upon my previous attempt [#1410](https://github.com/matrix-org/matrix-doc/issues/1410) +albeit with a notably reduced set of features. The aim of this proposal is to offer information about the +bridged network and nothing more. + +## Proposal + +This proposal uses + +It should be noted that this MSC is intended to provide the baseline needed to display information about +a bridge. Future MSCs should be written to expand this event as the need arises. + +### `org.matrix.bridge` + +*The name of the event type should eventually be `m.bridge` but has been prefixed until the spec is ready.* + +```js +{ + "state_key": "org.matrix.appservice-irc://network_id/channel_id", + "type": "org.matrix.bridge" + "content": { + "creator": "@alice:matrix.org", // Optional + "status": "active" // Optional, will default to active. One of "active", "disabled". + "network": { + "id": "freenode", + "displayname": "Freenode", // Optional + "avatar": "mxc://foo/bar" // Optinal + }, + "channel": { + "id": "#friends", + "displayname": "Friends" // Optional + }, + // Custom vendor-specific keys + "org.matrix.appservice-irc.room_mode": "+sn", + }, + "sender": "@appservice-irc:matrix.org" +} +``` + +The `state_key` must be comprised of the bridge's prefix, followed by the `network.id`, followed by the `channel.id`. + +The `sender` should be the MXID of the bridge bot. + +The `creator` field is the name of the *user* which provisioned the bridge. In the case of alias based bridges, where the +creator is not known -- it may be omitted. + +The `status` field informs the client if the bridge is still active, or has been disabled. The meaning may be different +depending on the context of the network. + +The `network` field should be information about the specific network the bridge is connected to. This may be "Freenode" for IRC, +or "Discord" if the network is global. (What does this mean?). + +The event may contain information specific to the bridge in question, such as the mode for the room in IRC. These keys +should be prefixed by the bridge's name. Clients may be capable of displaying this extra information and are free to do so. + +## Potential issues + +This proposal knowingly discards some information present in #1410. These were removed to allow the MSC to pass quicker +through the process, as well as some of the information having limited value to clients. + +The proposal intentionally sidesteps the 'bridge type' problem: Codifing what a portal, plumbed and gatewayed bridge look +like in Matrix. For the time being, the event will not contain information about the type of bridge in a room but merely +information about what is is connected to. + +## Alternatives + +Some thoughts have been thought on using the third party bridge routes in the AS api to get bridge info, +by calling a specalised endpoint. There are many issues with this, such as the routes not working presently +over federation, as well as requring the bridge to be online. Using a state event ensures the data is scoped +per room, and can be synchronised and updated over federation. + +## Security considerations + +Anybody with the correct PLs to post state events will be able to manipulate a room by sending a bridge +event into a room , even if the bridge is not present or does not exist. It goes without saying that if +you let people modify your room state, you need to trust them not to mess around. \ No newline at end of file From e5daeb9708a74d0fa2b2537c4871ee41ff40f034 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Tue, 5 Nov 2019 15:30:34 +0000 Subject: [PATCH 02/22] 2346 --- ...ge-info-state-event.md => 2346-bridge-info-state-event.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{xxxx-bridge-info-state-event.md => 2346-bridge-info-state-event.md} (98%) diff --git a/proposals/xxxx-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md similarity index 98% rename from proposals/xxxx-bridge-info-state-event.md rename to proposals/2346-bridge-info-state-event.md index 14e4145ec66..9716b4d1c03 100644 --- a/proposals/xxxx-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -1,4 +1,4 @@ -### MSC XXXX: Bridge information state event +### MSC 2346: Bridge information state event Many rooms across the matrix network are currently bridged into other networks, using our bridging API. However the specification does not contain a method to determine which networks are bridged into a given @@ -88,4 +88,4 @@ per room, and can be synchronised and updated over federation. Anybody with the correct PLs to post state events will be able to manipulate a room by sending a bridge event into a room , even if the bridge is not present or does not exist. It goes without saying that if -you let people modify your room state, you need to trust them not to mess around. \ No newline at end of file +you let people modify your room state, you need to trust them not to mess around. From e13cbec451400d74fe9d5902f015144addda5d83 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Mon, 2 Dec 2019 15:10:47 +0000 Subject: [PATCH 03/22] Various updates to take this out of WIP --- proposals/2346-bridge-info-state-event.md | 95 +++++++++++++++-------- 1 file changed, 62 insertions(+), 33 deletions(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 9716b4d1c03..81fe87b5260 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -1,49 +1,53 @@ -### MSC 2346: Bridge information state event +# MSC 2346: Bridge information state event -Many rooms across the matrix network are currently bridged into other networks, using our bridging API. -However the specification does not contain a method to determine which networks are bridged into a given -room. Many users have taken to peeking at the list of aliases for a giveaway alias like `#freenode_` or -looking for bridge bots or users with a `@_discord_` prefix. +Many rooms across the Matrix network are currently bridged into third party networks, using bridges. +However the spec does not contain a cross-federated method to determine which networks are +bridged into a given room. -This is an unacceptable situation. Users must know beforehand the names of IRC networks or protocols in order -to determine if a given ID is part of a bridge. The bridge cannot give away any infomation about itself -via Matrix. And blah blah blah. It alos allows bridges to be re-usable between different servers should we -want to go for the decentralised route one day. +There exists a way to do this in a local setting, by using the [/thirdparty/location](https://matrix.org/docs/spec/application_service/r0.1.2#get-matrix-app-v1-thirdparty-protocol-protocol) API but this creates a splitbrain view across the +federation and is an unnacceptable situation. -This proposal stands to fix, or partially fix the following issues: - - a bunch of riot projects that depend upon this - - a bunch of spec items too - -This proposal is heavily based upon my previous attempt [#1410](https://github.com/matrix-org/matrix-doc/issues/1410) -albeit with a notably reduced set of features. The aim of this proposal is to offer information about the -bridged network and nothing more. +Many users have taken to peeking at the list of aliases for a giveaway alias like `#freenode_` or +looking for bridge bots or users with a `@_discord_` prefix. This is an unacceptable situation, +as it assumes prior knowledge of these networks and an understanding of how bridges operate. ## Proposal -This proposal uses +This proposal attempts to address this problem by providing a single state event for each bridge in a room +to announce what network/channel combination have been bridged into a room. It should be noted that this MSC is intended to provide the baseline needed to display information about -a bridge. Future MSCs should be written to expand this event as the need arises. +a bridge, and nothing more. + +This proposal is heavily based upon my previous attempt [#1410](https://github.com/matrix-org/matrix-doc/issues/1410) +albeit with a notably reduced set of features. The aim of this proposal is to offer information about the +bridged network and nothing more. -### `org.matrix.bridge` +### `m.bridge` *The name of the event type should eventually be `m.bridge` but has been prefixed until the spec is ready.* ```js { - "state_key": "org.matrix.appservice-irc://network_id/channel_id", - "type": "org.matrix.bridge" + "state_key": "org.matrix.appservice-irc://{protocol.id}/{network.id}/{channel.id}", + "type": "m.bridge", "content": { "creator": "@alice:matrix.org", // Optional "status": "active" // Optional, will default to active. One of "active", "disabled". - "network": { + "protocol": { + "id": "irc", + "displayname": "IRC" + }, + "network": { // Optional "id": "freenode", "displayname": "Freenode", // Optional - "avatar": "mxc://foo/bar" // Optinal + "avatar": "mxc://foo/bar", // Optional + "external_url": "irc://chat.freenode.net" // Optional }, "channel": { "id": "#friends", - "displayname": "Friends" // Optional + "displayname": "Friends", // Optional + "external_url": "irc://chat.freenode.net/#friends" // Optional }, // Custom vendor-specific keys "org.matrix.appservice-irc.room_mode": "+sn", @@ -59,19 +63,32 @@ The `sender` should be the MXID of the bridge bot. The `creator` field is the name of the *user* which provisioned the bridge. In the case of alias based bridges, where the creator is not known -- it may be omitted. -The `status` field informs the client if the bridge is still active, or has been disabled. The meaning may be different -depending on the context of the network. +The `status` field informs the client if the bridge is still active, or has been disabled. + +The `protocol` field describes the protocol that is being bridged. For example, it may be "IRC", "Slack", or "Discord". This +field does not describe the low level protocol the bridge is using to access the network, but a common user recongnisable +name. -The `network` field should be information about the specific network the bridge is connected to. This may be "Freenode" for IRC, -or "Discord" if the network is global. (What does this mean?). +The `network` field should be information about the specific network the bridge is connected to. +It's important to make the distinction here that this does *NOT* describe the protocol name, but the specific network +the user is on. For protocols that do not have the concept of a network, this field may be omitted. + +The `channel` field should be information about the specific channel the room is connected to. + +The `external_url` key is a optional link to a connected channel or network that works in much the same way as +`external_url` works for bridged messages in the AS spec. + +In terms of hierachy, the protocol can contain many networks, which can contain many channels. The event may contain information specific to the bridge in question, such as the mode for the room in IRC. These keys should be prefixed by the bridge's name. Clients may be capable of displaying this extra information and are free to do so. -## Potential issues +## /_matrix/app/v1/thirdparty/location + +This proposal does NOT seek to deprecate the `location` API even though this spec effectively supercedes it in most respects. +A future MSC may choose to remove it, however. -This proposal knowingly discards some information present in #1410. These were removed to allow the MSC to pass quicker -through the process, as well as some of the information having limited value to clients. +## Potential issues The proposal intentionally sidesteps the 'bridge type' problem: Codifing what a portal, plumbed and gatewayed bridge look like in Matrix. For the time being, the event will not contain information about the type of bridge in a room but merely @@ -84,8 +101,20 @@ by calling a specalised endpoint. There are many issues with this, such as the r over federation, as well as requring the bridge to be online. Using a state event ensures the data is scoped per room, and can be synchronised and updated over federation. +## Future MSCs + +(This section is for the beneift of readers to understand why this MSC doesn't contain X feature) + +This proposal forms the basis for bridges to become more interactive with clients as first class citizens rather +than relying upon users having prior knowledge about which users are bridged users, or where a room is bridged to. + +Future MSCs could expand the /publicRooms response format to show what network a room is bridged to before the +user attempts to join it. Another potential MSC could allow users to see which bridges they are connected to +via an accounts settings page, rather than relying on PMs to the bridge bot. + ## Security considerations Anybody with the correct PLs to post state events will be able to manipulate a room by sending a bridge -event into a room , even if the bridge is not present or does not exist. It goes without saying that if -you let people modify your room state, you need to trust them not to mess around. +event into a room, even if the bridge is not present or does not exist. It goes without saying that if +you let people modify your room state, you need to trust them not to mess around. A future MSC may allow +users to "trust" some mxids as bridges, rather than relying on just PLs to convey trustworthiness. From e887a089285c465f156d6bfa8e58d9cf380295b9 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 2 Dec 2019 21:20:12 +0000 Subject: [PATCH 04/22] Backticks around location header Co-Authored-By: Hubert Chathi --- proposals/2346-bridge-info-state-event.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 81fe87b5260..c2ad364b37a 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -83,7 +83,7 @@ In terms of hierachy, the protocol can contain many networks, which can contain The event may contain information specific to the bridge in question, such as the mode for the room in IRC. These keys should be prefixed by the bridge's name. Clients may be capable of displaying this extra information and are free to do so. -## /_matrix/app/v1/thirdparty/location +## `/_matrix/app/v1/thirdparty/location` This proposal does NOT seek to deprecate the `location` API even though this spec effectively supercedes it in most respects. A future MSC may choose to remove it, however. From dfba42d4a193d1809fa0e939b687fc45bd965f11 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Tue, 3 Dec 2019 10:45:25 +0000 Subject: [PATCH 05/22] Clarify fields --- proposals/2346-bridge-info-state-event.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index c2ad364b37a..ee66df9a946 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -57,6 +57,9 @@ bridged network and nothing more. ``` The `state_key` must be comprised of the bridge's prefix, followed by the `network.id`, followed by the `channel.id`. +Any `/`s must be escaped into `%2F`. The bridge prefix can be anything, but should uniquely identify the bridge software +that consumes the event. E.g. The matrix.org IRC bridge `matrix-org/matrix-appservice-irc` becomes `org.matrix.appservice-irc`. +This is to help distinguish two bridges on different softwares which may conflict. The `sender` should be the MXID of the bridge bot. @@ -75,6 +78,8 @@ the user is on. For protocols that do not have the concept of a network, this fi The `channel` field should be information about the specific channel the room is connected to. +The `id` field is case-insensitive and should be lowercase. + The `external_url` key is a optional link to a connected channel or network that works in much the same way as `external_url` works for bridged messages in the AS spec. From 38e635a318707f391ac733b734e7c38145dc9a7b Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Tue, 3 Dec 2019 10:45:33 +0000 Subject: [PATCH 06/22] Add some example event bodys --- proposals/2346-bridge-info-state-event.md | 99 ++++++++++++++++++++++- 1 file changed, 98 insertions(+), 1 deletion(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index ee66df9a946..acc504ad6e3 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -33,7 +33,7 @@ bridged network and nothing more. "type": "m.bridge", "content": { "creator": "@alice:matrix.org", // Optional - "status": "active" // Optional, will default to active. One of "active", "disabled". + "status": "active", // Optional, will default to active. One of "active", "disabled". "protocol": { "id": "irc", "displayname": "IRC" @@ -88,6 +88,103 @@ In terms of hierachy, the protocol can contain many networks, which can contain The event may contain information specific to the bridge in question, such as the mode for the room in IRC. These keys should be prefixed by the bridge's name. Clients may be capable of displaying this extra information and are free to do so. +### Example Content + +#### XMPP + +An example of a non-messaging bridge, such as the GitHub bridge: + +```js +{ + "state_key": "org.matrix.matrix-bifrost://xmpp/general/muc.xmpp.org", + "type": "m.bridge", + "content": { + "creator": "@alice:matrix.org", + "status": "active", + "protocol": { + "id": "xmpp", + "displayname": "XMPP" + }, + "network": { + "id": "muc.xmpp.org", + "displayname": "XSF", + "external_url": "xmpp:muc.xmpp.org" + }, + "channel": { + "id": "xsf@muc.xmpp.org", + "displayname": "XSF Discussion", + "external_url": "xmpp:xsf@muc.xmpp.org" + } + }, + "sender": "@xmpp:matrix.org" +} +``` + +#### GitHub + +An example of a non-messaging bridge, such as the GitHub bridge: + +```js +{ + "state_key": "uk.half-shot.matrix-github://github/matrix-org%2Fmatrix-doc/2346", + "type": "m.bridge", + "content": { + "creator": "@alice:matrix.org", + "status": "active", + "protocol": { + "id": "github", + "displayname": "GitHub" + }, + "network": { + "id": "matrix-org/matrix-doc", + "external_url": "https://github.com/matrix-org/matrix-doc" + }, + "channel": { + "id": "2346", + "displayname": "MSC2346: Bridge information state event", + "external_url": "https://github.com/matrix-org/matrix-doc/pull/2346" + }, + "uk.half-shot.matrix-github.merged": false, + "uk.half-shot.matrix-github.opened_by": "Half-Shot", + }, + "sender": "@github:matrix.org" +} +``` + +#### Mastodon feed + +An example of a feed oriented bridge. + +```js +{ + "state_key": "org.matrix-org.matrix-mastodon://mastodon/mastodon.matrix.org/@matrix", + "type": "m.bridge", + "content": { + "creator": "@alice:matrix.org", + "status": "active", + "protocol": { + "id": "mastodon", + "displayname": "Mastodon" + }, + "network": { + "id": "mastodon.matrix.org", + "external_url": "https://mastodon.matrix.org" + }, + "channel": { + "id": "@matrix", + "displayname": "Matrix.org", + "external_url": "https://mastodon.matrix.org/@matrix" + } + }, + "org.matrix-org.matrix-mastodon.bio": "An open standard for decentralised persistent communication. Toots by @matthew, @Amandine & co.", + "org.matrix-org.matrix-mastodon.joined": "May 2017", + "sender": "@mastodon:matrix.org" +} +``` + +Note the `@` in this case helps distinguish the type of channel. Here the protocol used is "Mastodon" rather than "ActivityPub". +While the underlying protocol might indeed be ActivityPub, the choice of name should be recognisable to users. + ## `/_matrix/app/v1/thirdparty/location` This proposal does NOT seek to deprecate the `location` API even though this spec effectively supercedes it in most respects. From 0103c3030a2b6e3fb5e0abcbb87fcdbcf7980380 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Tue, 3 Dec 2019 10:55:41 +0000 Subject: [PATCH 07/22] Small fixes --- proposals/2346-bridge-info-state-event.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index acc504ad6e3..449a94c1043 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -14,10 +14,10 @@ as it assumes prior knowledge of these networks and an understanding of how brid ## Proposal This proposal attempts to address this problem by providing a single state event for each bridge in a room -to announce what network/channel combination have been bridged into a room. +to announce which channels have been bridged into a room. It should be noted that this MSC is intended to provide the baseline needed to display information about -a bridge, and nothing more. +a bridge, and nothing more. See the "Future MSCs" section for more information. This proposal is heavily based upon my previous attempt [#1410](https://github.com/matrix-org/matrix-doc/issues/1410) albeit with a notably reduced set of features. The aim of this proposal is to offer information about the @@ -25,8 +25,6 @@ bridged network and nothing more. ### `m.bridge` -*The name of the event type should eventually be `m.bridge` but has been prefixed until the spec is ready.* - ```js { "state_key": "org.matrix.appservice-irc://{protocol.id}/{network.id}/{channel.id}", From ffc98ce63df9a087bebe29ccb93a8e1935e10a4f Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Tue, 3 Dec 2019 10:56:47 +0000 Subject: [PATCH 08/22] C&P fail --- proposals/2346-bridge-info-state-event.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 449a94c1043..b545bd1f8e6 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -90,7 +90,7 @@ should be prefixed by the bridge's name. Clients may be capable of displaying th #### XMPP -An example of a non-messaging bridge, such as the GitHub bridge: +An example of a straight forward messaging bridge, such as the XMPP (bifrost) bridge: ```js { From ef21d6bac1957126ad8b19e41930c7d2f7276e7e Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Tue, 3 Dec 2019 11:56:14 +0000 Subject: [PATCH 09/22] Fix content in mastodon example. --- proposals/2346-bridge-info-state-event.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index b545bd1f8e6..7cd91569b8c 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -172,10 +172,10 @@ An example of a feed oriented bridge. "id": "@matrix", "displayname": "Matrix.org", "external_url": "https://mastodon.matrix.org/@matrix" - } + }, + "org.matrix-org.matrix-mastodon.bio": "An open standard for decentralised persistent communication. Toots by @matthew, @Amandine & co.", + "org.matrix-org.matrix-mastodon.joined": "May 2017", }, - "org.matrix-org.matrix-mastodon.bio": "An open standard for decentralised persistent communication. Toots by @matthew, @Amandine & co.", - "org.matrix-org.matrix-mastodon.joined": "May 2017", "sender": "@mastodon:matrix.org" } ``` From 542dfa7ad3df56cf0015e923782b1489804e6f5d Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 4 Dec 2019 10:54:24 +0000 Subject: [PATCH 10/22] @uhoreg nit picks Co-Authored-By: Hubert Chathi --- proposals/2346-bridge-info-state-event.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 7cd91569b8c..921da8af5d4 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -54,7 +54,7 @@ bridged network and nothing more. } ``` -The `state_key` must be comprised of the bridge's prefix, followed by the `network.id`, followed by the `channel.id`. +The `state_key` must be comprised of the bridge's prefix, followed by the `protocol.id`, followed by the `network.id`, followed by the `channel.id`. Any `/`s must be escaped into `%2F`. The bridge prefix can be anything, but should uniquely identify the bridge software that consumes the event. E.g. The matrix.org IRC bridge `matrix-org/matrix-appservice-irc` becomes `org.matrix.appservice-irc`. This is to help distinguish two bridges on different softwares which may conflict. @@ -94,7 +94,7 @@ An example of a straight forward messaging bridge, such as the XMPP (bifrost) br ```js { - "state_key": "org.matrix.matrix-bifrost://xmpp/general/muc.xmpp.org", + "state_key": "org.matrix.matrix-bifrost://xmpp/muc.xmpp.org/xsf@muc.xmpp.org", "type": "m.bridge", "content": { "creator": "@alice:matrix.org", From 4f05bb3f80f29aa53fc5a8a92411755d7e03ab49 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sun, 8 Dec 2019 15:38:24 +0000 Subject: [PATCH 11/22] Remove `status` key --- proposals/2346-bridge-info-state-event.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 921da8af5d4..0d8458b68fe 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -31,7 +31,6 @@ bridged network and nothing more. "type": "m.bridge", "content": { "creator": "@alice:matrix.org", // Optional - "status": "active", // Optional, will default to active. One of "active", "disabled". "protocol": { "id": "irc", "displayname": "IRC" @@ -64,8 +63,6 @@ The `sender` should be the MXID of the bridge bot. The `creator` field is the name of the *user* which provisioned the bridge. In the case of alias based bridges, where the creator is not known -- it may be omitted. -The `status` field informs the client if the bridge is still active, or has been disabled. - The `protocol` field describes the protocol that is being bridged. For example, it may be "IRC", "Slack", or "Discord". This field does not describe the low level protocol the bridge is using to access the network, but a common user recongnisable name. From 8deecda5a28456c41efdee94589d078747fc5854 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sun, 8 Dec 2019 15:39:03 +0000 Subject: [PATCH 12/22] Update 2346-bridge-info-state-event.md --- proposals/2346-bridge-info-state-event.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 0d8458b68fe..3d16f205995 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -95,7 +95,6 @@ An example of a straight forward messaging bridge, such as the XMPP (bifrost) br "type": "m.bridge", "content": { "creator": "@alice:matrix.org", - "status": "active", "protocol": { "id": "xmpp", "displayname": "XMPP" @@ -125,7 +124,6 @@ An example of a non-messaging bridge, such as the GitHub bridge: "type": "m.bridge", "content": { "creator": "@alice:matrix.org", - "status": "active", "protocol": { "id": "github", "displayname": "GitHub" @@ -156,7 +154,6 @@ An example of a feed oriented bridge. "type": "m.bridge", "content": { "creator": "@alice:matrix.org", - "status": "active", "protocol": { "id": "mastodon", "displayname": "Mastodon" From 899f4b161a1c6f9ab4b2628cef451af49c1515b9 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sun, 8 Dec 2019 15:47:44 +0000 Subject: [PATCH 13/22] Update key info for dispn/avatar --- proposals/2346-bridge-info-state-event.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 3d16f205995..925c0bad7a2 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -33,7 +33,9 @@ bridged network and nothing more. "creator": "@alice:matrix.org", // Optional "protocol": { "id": "irc", - "displayname": "IRC" + "displayname": "IRC", // Optional + "avatar": "mxc://foo/bar", // Optional + "external_url": "https://example.com" // Optional }, "network": { // Optional "id": "freenode", @@ -44,6 +46,7 @@ bridged network and nothing more. "channel": { "id": "#friends", "displayname": "Friends", // Optional + "avatar": "mxc://foo/bar", // Optional "external_url": "irc://chat.freenode.net/#friends" // Optional }, // Custom vendor-specific keys @@ -71,11 +74,13 @@ The `network` field should be information about the specific network the bridge It's important to make the distinction here that this does *NOT* describe the protocol name, but the specific network the user is on. For protocols that do not have the concept of a network, this field may be omitted. -The `channel` field should be information about the specific channel the room is connected to. +The `channel` field should be information about the specific channel the room is connected to. The `id` field is case-insensitive and should be lowercase. -The `external_url` key is a optional link to a connected channel or network that works in much the same way as +The `network`, `channel` and `protocol` fields can contain `displayname` and `avatar` keys. The `displayname` is meant to be a human readable identifier for the item in question, whereas the ID should be a unique identifer relevant to the protocol. The `id` should be used in place of a `displayname`, if not given. The `avatar` key is a MXC URI which refers to an image file, similar to a user or room avatar. + +The `external_url` key is a optional link to a connected channel, network or protocol that works in much the same way as `external_url` works for bridged messages in the AS spec. In terms of hierachy, the protocol can contain many networks, which can contain many channels. From d21d25b6f673de97de66d6b08e2fd76948956f3d Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 9 Dec 2019 19:22:13 +0000 Subject: [PATCH 14/22] Update MSC to include escaping information --- proposals/2346-bridge-info-state-event.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 925c0bad7a2..b81349cc2d1 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -76,7 +76,7 @@ the user is on. For protocols that do not have the concept of a network, this fi The `channel` field should be information about the specific channel the room is connected to. -The `id` field is case-insensitive and should be lowercase. +The `id` field is case-insensitive and should be lowercase. Uppercase characters should be escaped (e.g. using QP encoding or similar). The purpose of the id field is not to be human readable but just for comparing within the same bridge type, hence no encoding standard will be enforced in this proposal. The `network`, `channel` and `protocol` fields can contain `displayname` and `avatar` keys. The `displayname` is meant to be a human readable identifier for the item in question, whereas the ID should be a unique identifer relevant to the protocol. The `id` should be used in place of a `displayname`, if not given. The `avatar` key is a MXC URI which refers to an image file, similar to a user or room avatar. From e133838e93de53485f97864f2a87d0a45ffc84b2 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 9 Jan 2020 01:00:23 +0000 Subject: [PATCH 15/22] Add Implementation notes --- proposals/2346-bridge-info-state-event.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index b81349cc2d1..92fc4062b8e 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -217,3 +217,8 @@ Anybody with the correct PLs to post state events will be able to manipulate a r event into a room, even if the bridge is not present or does not exist. It goes without saying that if you let people modify your room state, you need to trust them not to mess around. A future MSC may allow users to "trust" some mxids as bridges, rather than relying on just PLs to convey trustworthiness. + + +## Implementation notes + +This proposal is partially implemented by [Riot](https://github.com/vector-im/riot-web) and the [IRC Bridge](https://github.com/matrix-org/matrix-appservice-irc) using the `uk.half-shot.*` namespace until this becomes stable. Therefore `m.bridge` becomes `uk.half-shot.bridge`. From 6e72d102522ce010f723ca9cd071832885b3debc Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 5 Feb 2020 11:49:00 +0000 Subject: [PATCH 16/22] Apply suggestions from code review Co-Authored-By: Travis Ralston Co-Authored-By: V02460 --- proposals/2346-bridge-info-state-event.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 92fc4062b8e..75d31163874 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -34,7 +34,7 @@ bridged network and nothing more. "protocol": { "id": "irc", "displayname": "IRC", // Optional - "avatar": "mxc://foo/bar", // Optional + "avatar_url": "mxc://foo/bar", // Optional "external_url": "https://example.com" // Optional }, "network": { // Optional @@ -86,7 +86,7 @@ The `external_url` key is a optional link to a connected channel, network or pro In terms of hierachy, the protocol can contain many networks, which can contain many channels. The event may contain information specific to the bridge in question, such as the mode for the room in IRC. These keys -should be prefixed by the bridge's name. Clients may be capable of displaying this extra information and are free to do so. +should be prefixed by the bridge's prefix. Clients may be capable of displaying this extra information and are free to do so. ### Example Content From 91047405faecd9a4640a1f3b789cc20a3649656c Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 5 Feb 2020 12:30:39 +0000 Subject: [PATCH 17/22] Update proposals/2346-bridge-info-state-event.md Co-Authored-By: Travis Ralston --- proposals/2346-bridge-info-state-event.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 75d31163874..e9c6470e958 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -33,7 +33,7 @@ bridged network and nothing more. "creator": "@alice:matrix.org", // Optional "protocol": { "id": "irc", - "displayname": "IRC", // Optional + "display_name": "IRC", // Optional "avatar_url": "mxc://foo/bar", // Optional "external_url": "https://example.com" // Optional }, From a0b98d71cbaa7fc08f0445f91f9805d340058def Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Fri, 7 Feb 2020 17:47:52 +0000 Subject: [PATCH 18/22] Some feedback changes --- proposals/2346-bridge-info-state-event.md | 51 ++++++++++++++++------- 1 file changed, 35 insertions(+), 16 deletions(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 92fc4062b8e..49f1ddb9fcc 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -4,8 +4,9 @@ Many rooms across the Matrix network are currently bridged into third party netw However the spec does not contain a cross-federated method to determine which networks are bridged into a given room. -There exists a way to do this in a local setting, by using the [/thirdparty/location](https://matrix.org/docs/spec/application_service/r0.1.2#get-matrix-app-v1-thirdparty-protocol-protocol) API but this creates a splitbrain view across the -federation and is an unnacceptable situation. +There exists a way to do this in a local setting, by using the +[/thirdparty/location](https://matrix.org/docs/spec/application_service/r0.1.2#get-matrix-app-v1-thirdparty-protocol-protocol) +API but this creates a splitbrain view across the federation and is an unnacceptable situation. Many users have taken to peeking at the list of aliases for a giveaway alias like `#freenode_` or looking for bridge bots or users with a `@_discord_` prefix. This is an unacceptable situation, @@ -30,6 +31,7 @@ bridged network and nothing more. "state_key": "org.matrix.appservice-irc://{protocol.id}/{network.id}/{channel.id}", "type": "m.bridge", "content": { + "bridgebot": "@appservice-irc:matrix.org", "creator": "@alice:matrix.org", // Optional "protocol": { "id": "irc", @@ -48,23 +50,23 @@ bridged network and nothing more. "displayname": "Friends", // Optional "avatar": "mxc://foo/bar", // Optional "external_url": "irc://chat.freenode.net/#friends" // Optional - }, - // Custom vendor-specific keys - "org.matrix.appservice-irc.room_mode": "+sn", + } }, "sender": "@appservice-irc:matrix.org" } ``` -The `state_key` must be comprised of the bridge's prefix, followed by the `protocol.id`, followed by the `network.id`, followed by the `channel.id`. -Any `/`s must be escaped into `%2F`. The bridge prefix can be anything, but should uniquely identify the bridge software -that consumes the event. E.g. The matrix.org IRC bridge `matrix-org/matrix-appservice-irc` becomes `org.matrix.appservice-irc`. -This is to help distinguish two bridges on different softwares which may conflict. +The `state_key` must be comprised of the bridge's prefix, followed by the `protocol.id`, followed by the `network.id`, +followed by the `channel.id`. Any `/`s must be escaped into `%2F`. The bridge prefix can be anything, but should uniquely +identify the bridge software. E.g. The matrix.org IRC bridge `matrix-org/matrix-appservice-irc` +becomes `org.matrix.appservice-irc`. This is to help distinguish two bridges on different softwares which may conflict. -The `sender` should be the MXID of the bridge bot. +The `bridgebot` should be the MXID of the bridge bot. It is important to note that `sender` should not be presumed to be +the bridge bot. This is because room upgrades, other bridges or admins could also set the state in the room on behalf of +the bridge bot. The `creator` field is the name of the *user* which provisioned the bridge. In the case of alias based bridges, where the -creator is not known -- it may be omitted. +creator is not known -- it should be omitted. The `protocol` field describes the protocol that is being bridged. For example, it may be "IRC", "Slack", or "Discord". This field does not describe the low level protocol the bridge is using to access the network, but a common user recongnisable @@ -76,17 +78,24 @@ the user is on. For protocols that do not have the concept of a network, this fi The `channel` field should be information about the specific channel the room is connected to. -The `id` field is case-insensitive and should be lowercase. Uppercase characters should be escaped (e.g. using QP encoding or similar). The purpose of the id field is not to be human readable but just for comparing within the same bridge type, hence no encoding standard will be enforced in this proposal. +The `id` field is case-insensitive and should be lowercase. Uppercase characters should be escaped (e.g. using QP encoding +or similar).The purpose of the id field is not to be human readable but just for comparing within the same bridge type, +hence no encoding standard will be enforced in this proposal. -The `network`, `channel` and `protocol` fields can contain `displayname` and `avatar` keys. The `displayname` is meant to be a human readable identifier for the item in question, whereas the ID should be a unique identifer relevant to the protocol. The `id` should be used in place of a `displayname`, if not given. The `avatar` key is a MXC URI which refers to an image file, similar to a user or room avatar. +The `network`, `channel` and `protocol` fields can contain `displayname` and `avatar` keys. The `displayname` is meant to +be a human readable identifier for the item in question, whereas the ID should be a unique identifer relevant to the protocol. +The `id` should be used in place of a `displayname`, if not given. The `avatar` key is a MXC URI which refers to an image +file, similar to a user or room avatar. The `external_url` key is a optional link to a connected channel, network or protocol that works in much the same way as `external_url` works for bridged messages in the AS spec. In terms of hierachy, the protocol can contain many networks, which can contain many channels. -The event may contain information specific to the bridge in question, such as the mode for the room in IRC. These keys -should be prefixed by the bridge's name. Clients may be capable of displaying this extra information and are free to do so. +### Removing a bridge + +When removing a bridge, you simply need to send a new state event with the same `state_key` with a `content` of `{}`. This +is because matrix does not yet have a mechanism to remove a state event in it's entireity. ### Example Content @@ -189,10 +198,18 @@ A future MSC may choose to remove it, however. ## Potential issues +### We do not specify a "bridge type". + The proposal intentionally sidesteps the 'bridge type' problem: Codifing what a portal, plumbed and gatewayed bridge look like in Matrix. For the time being, the event will not contain information about the type of bridge in a room but merely information about what is is connected to. +### Anyone* can send this event into the room. + +This kinda goes for *any* event in Matrix, there is no way to determine a bridge across federation. The difference here +is that we at least require the user for the ability to send state events into the room. If you are allowed to send +arbitrary state events into the room, it's assumed you are somewhat trusted. + ## Alternatives Some thoughts have been thought on using the third party bridge routes in the AS api to get bridge info, @@ -221,4 +238,6 @@ users to "trust" some mxids as bridges, rather than relying on just PLs to conve ## Implementation notes -This proposal is partially implemented by [Riot](https://github.com/vector-im/riot-web) and the [IRC Bridge](https://github.com/matrix-org/matrix-appservice-irc) using the `uk.half-shot.*` namespace until this becomes stable. Therefore `m.bridge` becomes `uk.half-shot.bridge`. +This proposal is partially implemented by [Riot](https://github.com/vector-im/riot-web) and the +[IRC Bridge](https://github.com/matrix-org/matrix-appservice-irc) using the `uk.half-shot.*` namespace +until this becomes stable. Therefore `m.bridge` becomes `uk.half-shot.bridge`. From 5251039caf917091d46cc64d11eb67c4c9474698 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Fri, 7 Feb 2020 17:50:46 +0000 Subject: [PATCH 19/22] Add bridgebot --- proposals/2346-bridge-info-state-event.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 5523d9786b8..6371fea529b 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -109,6 +109,7 @@ An example of a straight forward messaging bridge, such as the XMPP (bifrost) br "type": "m.bridge", "content": { "creator": "@alice:matrix.org", + "bridgebot": "@xmpp:matrix.org", "protocol": { "id": "xmpp", "displayname": "XMPP" @@ -138,6 +139,7 @@ An example of a non-messaging bridge, such as the GitHub bridge: "type": "m.bridge", "content": { "creator": "@alice:matrix.org", + "bridgebot": "@github:matrix.org", "protocol": { "id": "github", "displayname": "GitHub" @@ -168,6 +170,7 @@ An example of a feed oriented bridge. "type": "m.bridge", "content": { "creator": "@alice:matrix.org", + "bridgebot": "@mastodon:matrix.org", "protocol": { "id": "mastodon", "displayname": "Mastodon" From 74bc2d97415dd6d06fa4dd4ad087dbba18b61a00 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Fri, 7 Feb 2020 17:54:07 +0000 Subject: [PATCH 20/22] Remove thirdparty/location statement --- proposals/2346-bridge-info-state-event.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index 6371fea529b..bd5812f410b 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -194,11 +194,6 @@ An example of a feed oriented bridge. Note the `@` in this case helps distinguish the type of channel. Here the protocol used is "Mastodon" rather than "ActivityPub". While the underlying protocol might indeed be ActivityPub, the choice of name should be recognisable to users. -## `/_matrix/app/v1/thirdparty/location` - -This proposal does NOT seek to deprecate the `location` API even though this spec effectively supercedes it in most respects. -A future MSC may choose to remove it, however. - ## Potential issues ### We do not specify a "bridge type". From 380b54d6a97f4cb83e5b3f45d381a6597b5b6453 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Fri, 22 May 2020 14:50:26 +0100 Subject: [PATCH 21/22] "avatar_url" is now the standard for avatars --- proposals/2346-bridge-info-state-event.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index bd5812f410b..cafac6bf6c4 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -42,13 +42,13 @@ bridged network and nothing more. "network": { // Optional "id": "freenode", "displayname": "Freenode", // Optional - "avatar": "mxc://foo/bar", // Optional + "avatar_url": "mxc://foo/bar", // Optional "external_url": "irc://chat.freenode.net" // Optional }, "channel": { "id": "#friends", "displayname": "Friends", // Optional - "avatar": "mxc://foo/bar", // Optional + "avatar_url": "mxc://foo/bar", // Optional "external_url": "irc://chat.freenode.net/#friends" // Optional } }, From 62afef8aae98e39536bcda450db24fac4056ec88 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Fri, 3 Jul 2020 11:15:01 +0100 Subject: [PATCH 22/22] Update proposals/2346-bridge-info-state-event.md Co-authored-by: Tulir Asokan --- proposals/2346-bridge-info-state-event.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2346-bridge-info-state-event.md b/proposals/2346-bridge-info-state-event.md index cafac6bf6c4..f017e8138c7 100644 --- a/proposals/2346-bridge-info-state-event.md +++ b/proposals/2346-bridge-info-state-event.md @@ -35,7 +35,7 @@ bridged network and nothing more. "creator": "@alice:matrix.org", // Optional "protocol": { "id": "irc", - "display_name": "IRC", // Optional + "displayname": "IRC", // Optional "avatar_url": "mxc://foo/bar", // Optional "external_url": "https://example.com" // Optional },