diff --git a/README.md b/README.md index 6ae2a9e..510e830 100644 --- a/README.md +++ b/README.md @@ -29,8 +29,8 @@ The following is supported from this package: Therefore, you can easily build a bot, chat relay, or administrate your Matrix server from within [Node-RED](https://nodered.org/). -### Examples -We have examples! [Check them out](examples) +### Usage +We have examples! [Check them out](https://github.com/Skylar-Tech/node-red-contrib-matrix-chat/tree/master/examples#readme) ### Installing @@ -39,9 +39,19 @@ You can either install from within Node-RED by searching for `node-red-contrib-m npm install node-red-contrib-matrix-chat ``` -### Usage +### End-to-End Encryption Notes +Currently this module has no way of getting encryption keys from other devices on the same account. Therefore it is recommended you use the bot exclusively with Node-RED after it's creation. Failure to do so will lead to your bot being unable to receive messages from e2ee rooms it joined from another client. Shared secret registration makes this super easy since it returns a token and device ID. + +This module stores a folder in your Node-RED directory called `matrix-local-storage` and is it vital that you periodically back this up if you are using e2ee. This is where the client stores all the keys necessary to decrypt messages and if lost you will lose access to e2e rooms. If you move your client to another NR install make sure to migrate this folder as well (and do not let both the old and new client run at same time). + +Want to contribute? Any help on getting the last pieces of e2ee figured out would be greatly appreciated :) + +### Generate user +You will need a user to use this module. Luckily this module comes with a node that allows you to register users to a homeserver using the secret registration endpoint. This is perfect because it returns an `access_token` as well as a `device_id` which is exactly what we need. + +[Click here](https://github.com/Skylar-Tech/node-red-contrib-matrix-chat/tree/master/examples#readme) to see how to generate a user using secret registration + -Using this package is very straightforward. Examples coming soon! ### Other Packages @@ -49,4 +59,5 @@ Using this package is very straightforward. Examples coming soon! ### Contributing All contributions are welcome! If you do add a feature please do a pull request so that everyone benefits :) -Sharing is caring. \ No newline at end of file + +Sharing is caring! \ No newline at end of file diff --git a/examples/README.md b/examples/README.md index dd41b05..8c1dae2 100644 --- a/examples/README.md +++ b/examples/README.md @@ -7,14 +7,38 @@ Build something cool with these nodes? Feel free to submit a pull request to sha ## Index +- [Create User with Shared Secret Registration](#create-user-with-shared-secret-registration) +- [Create/Edit Synapse User](#createedit-synapse-user) - [Respond to "ping" with "pong"](#respond-to-ping-with-pong) - [Respond to "html" with an HTML message](#respond-to-html-with-an-html-message) -- [Create user using Synapse v1 API](#create-user-using-synapse-v1-api) - [Respond to "image" with an uploaded image](#respond-to-image-with-an-uploaded-image) - [Respond to "file" with an uploaded file](#respond-to-file-with-an-uploaded-file) - [Respond to "react" with a reaction](#respond-to-react-with-a-reaction) - [Respond to "users" with full list of server users](#respond-to-users-with-full-list-of-server-users) + +### Create user with Shared Secret Registration + +[View JSON](shared-secret-registration.json) + +Use this flow to create users on servers with closed registration. You also use this endpoint to create your first admin user as it is the same as running the local python script on the server. This requires your registration secret from your homeserver.yaml Synapse server configuration file. + +Edit the object on the inject node to the user/pass combo you want to create and hit the inject button (to the left of the inject node). + +**Note:** This only works on Synapse servers. + +![img.png](shared-secret-registration.png) + + +### Create/Edit Synapse User + +[View JSON](add-user-with-admin-user.json) + +Allows an administrator to create or modify a user account with a specified `msg.userId`. + +![img.png](add-user-with-admin-user.png) + + ### Respond to "ping" with "pong" [View JSON](respond-to-html-with-html.json) @@ -35,20 +59,6 @@ Use this flow to respond to anyone that says "html" with an example HTML message -### Create user using Synapse v1 API - -[View JSON](create-user-synapse-v1-api.json) - -Use this flow to create users on servers with closed registration. You also use this endpoint to create your first admin user as it is the same as running the local python script on the server. This requires your registration secret from your homeserver.yaml Synapse server configuration file. - -Edit the object on the inject node to the user/pass combo you want to create and hit the inject button (to the left of the inject node). - -**Note:** This only works on Synapse servers. - -![img.png](create-user-synapse-v1-api.png) - - - ### Respond to "image" with an uploaded image [View JSON](respond-image-with-image.json) diff --git a/examples/add-user-with-admin-user.json b/examples/add-user-with-admin-user.json new file mode 100644 index 0000000..0004ea5 --- /dev/null +++ b/examples/add-user-with-admin-user.json @@ -0,0 +1,92 @@ +[ + { + "id": "56b6ae18958287f3", + "type": "inject", + "z": "f025a8b9fbd1b054", + "name": "", + "props": [ + { + "p": "payload" + }, + { + "p": "userId", + "v": "@example:matrix.org", + "vt": "str" + } + ], + "repeat": "", + "crontab": "", + "once": false, + "onceDelay": 0.1, + "topic": "", + "payload": "{\"password\":\"example-password\",\"displayname\":\"Example User\",\"admin\":false,\"deactivated\":false}", + "payloadType": "json", + "x": 370, + "y": 1500, + "wires": [ + [ + "bc882759b3b11884" + ] + ] + }, + { + "id": "bc882759b3b11884", + "type": "matrix-synapse-create-edit-user", + "z": "f025a8b9fbd1b054", + "name": "", + "x": 570, + "y": 1500, + "wires": [ + [ + "624f5aa29b67602f" + ], + [ + "9f71a73d53f06853" + ] + ] + }, + { + "id": "7ac657a41b57e680", + "type": "comment", + "z": "f025a8b9fbd1b054", + "name": "Create or edit Synapse User", + "info": "", + "x": 440, + "y": 1460, + "wires": [] + }, + { + "id": "624f5aa29b67602f", + "type": "debug", + "z": "f025a8b9fbd1b054", + "name": "", + "active": true, + "tosidebar": true, + "console": false, + "tostatus": false, + "complete": "true", + "targetType": "full", + "statusVal": "", + "statusType": "auto", + "x": 750, + "y": 1480, + "wires": [] + }, + { + "id": "9f71a73d53f06853", + "type": "debug", + "z": "f025a8b9fbd1b054", + "name": "", + "active": true, + "tosidebar": true, + "console": false, + "tostatus": false, + "complete": "true", + "targetType": "full", + "statusVal": "", + "statusType": "auto", + "x": 750, + "y": 1520, + "wires": [] + } +] \ No newline at end of file diff --git a/examples/add-user-with-admin-user.png b/examples/add-user-with-admin-user.png new file mode 100644 index 0000000..d42bb2f Binary files /dev/null and b/examples/add-user-with-admin-user.png differ diff --git a/examples/create-user-synapse-v1-api.json b/examples/create-user-synapse-v1-api.json deleted file mode 100644 index 71a673f..0000000 --- a/examples/create-user-synapse-v1-api.json +++ /dev/null @@ -1,49 +0,0 @@ -[ - { - "id": "dc757ef02529f228", - "type": "inject", - "z": "f025a8b9fbd1b054", - "name": "", - "props": [ - { - "p": "payload" - } - ], - "repeat": "", - "crontab": "", - "once": false, - "onceDelay": 0.1, - "topic": "", - "payload": "{\"username\":\"example\",\"password\":\"replaceme\"}", - "payloadType": "json", - "x": 130, - "y": 600, - "wires": [ - [ - "62f9049cf48342da" - ] - ] - }, - { - "id": "62f9049cf48342da", - "type": "matrix-synapse-register", - "z": "f025a8b9fbd1b054", - "name": "", - "x": 330, - "y": 600, - "wires": [ - [], - [] - ] - }, - { - "id": "3f9d486ca3c75bf2", - "type": "comment", - "z": "f025a8b9fbd1b054", - "name": "Register user using API v1", - "info": "", - "x": 170, - "y": 560, - "wires": [] - } -] \ No newline at end of file diff --git a/examples/create-user-synapse-v1-api.png b/examples/create-user-synapse-v1-api.png deleted file mode 100644 index 53980fd..0000000 Binary files a/examples/create-user-synapse-v1-api.png and /dev/null differ diff --git a/examples/respond-file-with-file.json b/examples/respond-file-with-file.json index c1555ef..cc20f02 100644 --- a/examples/respond-file-with-file.json +++ b/examples/respond-file-with-file.json @@ -4,7 +4,6 @@ "type": "matrix-receive", "z": "f025a8b9fbd1b054", "name": "", - "server": "4de4e868e02a9051", "roomId": "", "ignoreText": false, "ignoreReactions": false, @@ -138,7 +137,6 @@ "type": "matrix-send-file", "z": "f025a8b9fbd1b054", "name": "", - "server": "4de4e868e02a9051", "roomId": "", "contentType": "application/pdf", "x": 1160, @@ -151,11 +149,5 @@ "f6826747cd96b814" ] ] - }, - { - "id": "4de4e868e02a9051", - "type": "matrix-server-config", - "name": "Your Server", - "autoAcceptRoomInvites": true } ] \ No newline at end of file diff --git a/examples/respond-image-with-image.json b/examples/respond-image-with-image.json index bcc8de6..b768836 100644 --- a/examples/respond-image-with-image.json +++ b/examples/respond-image-with-image.json @@ -4,7 +4,6 @@ "type": "matrix-receive", "z": "f025a8b9fbd1b054", "name": "", - "server": "4de4e868e02a9051", "roomId": "", "ignoreText": false, "ignoreReactions": false, @@ -77,7 +76,6 @@ "type": "matrix-send-image", "z": "f025a8b9fbd1b054", "name": "", - "server": "4de4e868e02a9051", "roomId": "", "contentType": "image/png", "x": 1030, @@ -86,11 +84,5 @@ [], [] ] - }, - { - "id": "4de4e868e02a9051", - "type": "matrix-server-config", - "name": "Your Server", - "autoAcceptRoomInvites": true } ] \ No newline at end of file diff --git a/examples/respond-ping-pong.json b/examples/respond-ping-pong.json index 4609253..bfa0c08 100644 --- a/examples/respond-ping-pong.json +++ b/examples/respond-ping-pong.json @@ -4,7 +4,6 @@ "type": "matrix-receive", "z": "f025a8b9fbd1b054", "name": "", - "server": "4de4e868e02a9051", "roomId": "", "ignoreText": false, "ignoreReactions": false, @@ -85,7 +84,6 @@ "type": "matrix-send-message", "z": "f025a8b9fbd1b054", "name": "", - "server": "4de4e868e02a9051", "roomId": "", "messageType": "m.text", "messageFormat": "", @@ -133,11 +131,5 @@ "x": 1250, "y": 140, "wires": [] - }, - { - "id": "4de4e868e02a9051", - "type": "matrix-server-config", - "name": "Your Server", - "autoAcceptRoomInvites": true } ] \ No newline at end of file diff --git a/examples/respond-react-with-reaction.json b/examples/respond-react-with-reaction.json index fb92d81..43b1d8d 100644 --- a/examples/respond-react-with-reaction.json +++ b/examples/respond-react-with-reaction.json @@ -4,7 +4,6 @@ "type": "matrix-receive", "z": "f025a8b9fbd1b054", "name": "", - "server": "4de4e868e02a9051", "roomId": "", "ignoreText": false, "ignoreReactions": false, @@ -119,7 +118,6 @@ "type": "matrix-react", "z": "f025a8b9fbd1b054", "name": "", - "server": "4de4e868e02a9051", "roomId": "", "x": 1030, "y": 120, @@ -131,11 +129,5 @@ "07b598284bcadc58" ] ] - }, - { - "id": "4de4e868e02a9051", - "type": "matrix-server-config", - "name": "Your Server", - "autoAcceptRoomInvites": true } ] \ No newline at end of file diff --git a/examples/respond-to-html-with-html.json b/examples/respond-to-html-with-html.json index 5a041fd..9798a38 100644 --- a/examples/respond-to-html-with-html.json +++ b/examples/respond-to-html-with-html.json @@ -4,7 +4,6 @@ "type": "matrix-receive", "z": "f025a8b9fbd1b054", "name": "", - "server": "4de4e868e02a9051", "roomId": "", "ignoreText": false, "ignoreReactions": false, @@ -48,7 +47,6 @@ "type": "matrix-send-message", "z": "f025a8b9fbd1b054", "name": "Send HTML Message", - "server": "4de4e868e02a9051", "roomId": "", "messageType": "m.text", "messageFormat": "html", @@ -133,11 +131,5 @@ "x": 530, "y": 80, "wires": [] - }, - { - "id": "4de4e868e02a9051", - "type": "matrix-server-config", - "name": "Your Server", - "autoAcceptRoomInvites": true } ] \ No newline at end of file diff --git a/examples/respond-users-list.json b/examples/respond-users-list.json index ab54fb2..39970b6 100644 --- a/examples/respond-users-list.json +++ b/examples/respond-users-list.json @@ -4,7 +4,6 @@ "type": "matrix-receive", "z": "f025a8b9fbd1b054", "name": "", - "server": "4de4e868e02a9051", "roomId": "", "ignoreText": false, "ignoreReactions": false, @@ -48,7 +47,6 @@ "type": "matrix-synapse-users", "z": "f025a8b9fbd1b054", "name": "", - "server": "4de4e868e02a9051", "x": 890, "y": 120, "wires": [ @@ -63,7 +61,6 @@ "type": "matrix-send-message", "z": "f025a8b9fbd1b054", "name": "Send HTML Notice", - "server": "4de4e868e02a9051", "roomId": "", "messageType": "m.notice", "messageFormat": "html", @@ -102,11 +99,5 @@ "x": 550, "y": 80, "wires": [] - }, - { - "id": "4de4e868e02a9051", - "type": "matrix-server-config", - "name": "Your Server", - "autoAcceptRoomInvites": true } ] \ No newline at end of file diff --git a/examples/shared-secret-registration.json b/examples/shared-secret-registration.json new file mode 100644 index 0000000..38f3e6e --- /dev/null +++ b/examples/shared-secret-registration.json @@ -0,0 +1,87 @@ +[ + { + "id": "8a694cb7ebec1684", + "type": "inject", + "z": "f025a8b9fbd1b054", + "name": "", + "props": [ + { + "p": "payload" + } + ], + "repeat": "", + "crontab": "", + "once": false, + "onceDelay": 0.1, + "topic": "", + "payload": "{\"username\":\"example\",\"displayname\":\"Example User\",\"password\":\"super-secret-password\",\"admin\":true}", + "payloadType": "json", + "x": 470, + "y": 1780, + "wires": [ + [ + "f19521453aeaa6ba" + ] + ] + }, + { + "id": "f19521453aeaa6ba", + "type": "matrix-synapse-register", + "z": "f025a8b9fbd1b054", + "name": "", + "x": 670, + "y": 1780, + "wires": [ + [ + "cd2ea4e791098aa0" + ], + [ + "a365bedfad2280fe" + ] + ] + }, + { + "id": "66fbaa12bfadd0b4", + "type": "comment", + "z": "f025a8b9fbd1b054", + "name": "Register user using secret registration", + "info": "", + "x": 630, + "y": 1740, + "wires": [] + }, + { + "id": "cd2ea4e791098aa0", + "type": "debug", + "z": "f025a8b9fbd1b054", + "name": "", + "active": true, + "tosidebar": true, + "console": false, + "tostatus": false, + "complete": "true", + "targetType": "full", + "statusVal": "", + "statusType": "auto", + "x": 870, + "y": 1760, + "wires": [] + }, + { + "id": "a365bedfad2280fe", + "type": "debug", + "z": "f025a8b9fbd1b054", + "name": "", + "active": true, + "tosidebar": true, + "console": false, + "tostatus": false, + "complete": "true", + "targetType": "full", + "statusVal": "", + "statusType": "auto", + "x": 870, + "y": 1800, + "wires": [] + } +] \ No newline at end of file diff --git a/examples/shared-secret-registration.png b/examples/shared-secret-registration.png new file mode 100644 index 0000000..9fc13dd Binary files /dev/null and b/examples/shared-secret-registration.png differ diff --git a/src/matrix-server-config.html b/src/matrix-server-config.html index 902435c..fc77518 100644 --- a/src/matrix-server-config.html +++ b/src/matrix-server-config.html @@ -74,13 +74,6 @@ \ No newline at end of file