Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Sorunome/mx-puppet-bridge

Puppeting library for matrix
https://github.com/Sorunome/mx-puppet-bridge

Last synced: 26 days ago
JSON representation

Puppeting library for matrix

Awesome Lists containing this project

README 

        
**THIS PROJECT HAS BEEN MIGRATED OVER TO GITLAB: [mx-puppet-bridge](https://gitlab.com/mx-puppet/mx-puppet-bridge)**



[Support Chat](https://matrix.to/#/#mx-puppet-bridge:sorunome.de) [![donate](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/Sorunome/donate)



# mx-puppet-bridge

This is a library for easily building puppeting bridges for matrix.



A puppeting bridge is a bridge which logs into a remote account of a service for you (puppeting) and

thus allows you to use it via matrix. Matrix will basically act as a client for that remote

implementation. Double-puppeting is available, but 100% optional.



In addition to puppeting mode, this library also supports a relay mode: The account of the remote

protocol is used as relay bot between the remote protocol and matrix.



## Example implementation

 - [Echo](https://github.com/Sorunome/mx-puppet-echo), this just echos back messages sent to it



## Current protocol implementations

 - [Slack](https://github.com/Sorunome/mx-puppet-slack)

 - [Tox](https://github.com/Sorunome/mx-puppet-tox)

 - [Discord](https://github.com/matrix-discord/mx-puppet-discord)

 - [Instagram](https://github.com/Sorunome/mx-puppet-instagram)

 - [Twitter](https://github.com/Sorunome/mx-puppet-twitter)

 - [voip.ms](https://github.com/zoenb/mx-puppet-voipms)

 - [Skype](https://github.com/Sorunome/mx-puppet-skype)

 - [Steam](https://github.com/icewind1991/mx-puppet-steam)

 - [VK](https://github.com/innereq/mx-puppet-vk)

 - [GroupMe](https://gitlab.com/robintown/mx-puppet-groupme)



## Docs

 - [bridge.md](https://github.com/Sorunome/mx-puppet-bridge/blob/master/bridge.md)

 - `npm run docs`



## Features

Please note that not all protocol implementations support all features. This is just a feature list

of the features available in this library.

 - Plain messages

 - Formatted messages

 - Message edits

 - Message redactions

 - Message reactions

 - Send files/images/videos/audio/etc.

 - Remote user mapping

 - Remote room mapping

 - Remote group mapping

 - Multi-account (many matrix users can start many remote links)

 - Automatic double puppeting

 - Relay mode



### Group Mapping

For group mapping to work the homeserver in use has to support groups and group creation. For

synapse, you need to set `enable_group_creation: true` in your `homeserver.yaml`. After that, in the

protocols `config.yaml` set `bridge.enableGroupSync` to `true`.



### Relay mode

Relay mode is a mode where the remote puppet acts as a relay bot, rather than a puppeting bot. In

relay mode the display name of the author of the message on the matrix side is prepended to the

message.



To activate relay mode for a puppet type `settype  relay`. If you want the rooms of said

relay to be publicly usable, type `setispublic  1`.



Be sure to whitelist the users you want to relay, a possible config for to relay everyone could look

as follows:

```yaml

relay:

  whitelist:

    - ".*"

```



### Plumbed rooms

In order for plumbed rooms to work the protocol implementation must support global namespace and at

least one puppet of relay type has to have been added. In your config you can specify who is able to

create plumbed rooms. If everyone should be able to, your config could look as follows:

```yaml

selfService:

  whitelist:

    - ".*"

```

After that, invite the bridge bot into the matrix room you want to bridge. Then type

`! bridge `, for example for discord `!discord bridge 123456`. A

protocol implementation may add additional parsing to the remote room ID to allow multiple formats.



### Automatic double-puppeting

It can be a hassle to have to tell the bridge what your access token is to enable double-puppeting.

To circumvent that automatic double-puppeting is available. Configure your homeserver with

[matrix-synapse-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) and set

the secret for that homeserver in the `bridge.loginSharedSecretMap` mapping.



### Adding of metadata for images, videos and audio

Sent images, video and audio can have metadata added to them, for that make sure that `ffprobe`

is installed in your `$PATH`. It usually comes bundled with `ffmpeg`.



## Bridging new protocols

To bridge a new protocol only a small amount of features has to be implemented. For examples see

the corresponding section. For a full list of available endpoints, see [bridge.md](https://github.com/Sorunome/mx-puppet-bridge/blob/master/bridge.md).

### Features

Not all features need to be implemented by protocol implementations. Here are some features and which hooks are required to get them working:



| Feature | Hooks |

|---------|-------|

| normal functionality | `botHeaderMsg`, `getDataFromStr`, `getDesc` |

| make `listusers` working | `listUsers` |

| make `listrooms` working | `listRooms` |

| inject data on user creation | `createUser` |

| inject data on room creation | `createRoom` |

| enable group syncing | `createGroup` |

| initiate 1:1 rooms from the matrix side | `getDmRoomId`, `createRoom` |

| initiate rooms from the matrix side | `createRoom` |

| autopopulate rooms with users | `getUserIdsInRoom` |