search

matrix-org / go-neb

Extensible matrix bot written in Go
Apache License 2.0
283 stars 92 forks source link

readme

⚠️ Discontinued

Go-NEB has been discontinued and won't recieve any updates or support. matrix-hookshot is the spiritual successor to Go-NEB and supports migrating RSS and GitHub integrations. Other options are also available from matrix.org.

Go-NEB

Build Status

Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the original Matrix bot written in Python.

Table of Contents

Quick Start

Clone and run (Requires Go 1.16+):

go build github.com/matrix-org/go-neb
BIND_ADDRESS=:4050 DATABASE_TYPE=sqlite3 DATABASE_URL=go-neb.db?_busy_timeout=5000 BASE_URL=http://localhost:4050 ./go-neb

Get a Matrix user ID and access token. You can do this, for example, with the following curl command by replacing the user ID, password and Synapse URL with your own.

curl -X POST --header 'Content-Type: application/json' -d '{
    "identifier": { "type": "m.id.user", "user": "nebUsername" },
    "password": "nebPassword",
    "type": "m.login.password"
}' 'http://localhost:8008/_matrix/client/r0/login'

This is preferable to, for example, logging in via Riot and copying the access token and device ID from there, as then Riot will have uploaded its own device keys which Go-NEB won't have access to causing it to be unable to create encryption sessions.

The response of this command will be a JSON object with an access token and device ID.

Then, give the values to Go-NEB:

curl -X POST localhost:4050/admin/configureClient --data-binary '{
    "UserID": "@goneb:localhost",
    "HomeserverURL": "http://localhost:8008",
    "AccessToken": "<access_token>",
    "DeviceID": "<DEVICEID>",
    "Sync": true,
    "AutoJoinRooms": true,
    "DisplayName": "My Bot"
}'

Tell it what service to run:

curl -X POST localhost:4050/admin/configureService --data-binary '{
    "Type": "echo",
    "Id": "myserviceid",
    "UserID": "@goneb:localhost",
    "Config": {}
}'

Invite the bot user into a Matrix room and type !echo hello world. It will reply with hello world.

Features

Github

JIRA

Giphy

Guggy

RSS Bot

Travis CI

Alertmanager

Installing

Go-NEB is built using Go 1.16+. Once you have installed Go, run the following commands:

# Clone the go-neb repository
git clone https://github.com/matrix-org/go-neb
cd go-neb

# Build go-neb
go build github.com/matrix-org/go-neb

Running

Go-NEB uses environment variables to configure its SQLite database and bind address. To run Go-NEB, run the following command:

BIND_ADDRESS=:4050 DATABASE_TYPE=sqlite3 DATABASE_URL=go-neb.db?_busy_timeout=5000 BASE_URL=https://public.facing.endpoint ./go-neb

Configuration file

If you run Go-NEB with a CONFIG_FILE environment variable, it will load that file and use it for services, clients, etc. There is a sample configuration file which explains all the options. In most cases, these are direct mappings to the corresponding HTTP API.

API

The API is documented in sections using godoc. The sections consists of:

To form the complete API, you need to combine the HTTP API with the JSON request body, and the "Configuration" information (which is always under a JSON key called Config). In addition, most APIs have a Type which determines which piece of code to load. To find out what the right type is for the thing you're creating, check the constants defined in godoc.

Configuring Clients

Go-NEB needs to connect as a matrix user to receive messages. Go-NEB can listen for messages as multiple matrix users. The users are configured using an HTTP API and the config is stored in the database.

Configuring Services

Services contain all the useful functionality in Go-NEB. They require a client to operate. Services are configured using an HTTP API and the config is stored in the database. Services use one of the matrix users configured on Go-NEB to send/receive matrix messages.

Every service has an "ID", "type" and "user ID". Services may specify additional "config" keys: see the specific service you're interested in for the additional keys, if any.

List of Services:

Configuring Realms

Realms are how Go-NEB authenticates users on third-party websites.

List of Realms:

Authentication via HTTP:

Authentication via the config file:

SAS verification

Go-NEB supports SAS verification using the decimal method. Another user can start a verification transaction with Go-NEB using their client, and it will be accepted. In order to confirm the devices, the 3 SAS integers must then be sent to Go-NEB, to the endpoint '/verifySAS' so that it can mark the device as trusted.

For example, if your user ID is @user:localhost and your device ID is ABCD, you start a SAS verification with Go-NEB and get the SAS "1111 2222 3333". You can perform the following curl request to let Go-NEB know the SAS integers so that it can match them with its own:

curl -X POST --header 'Content-Type: application/json' -d '{
    "UserID": "@neb:localhost",
    "OtherUserID": "@user:localhost",
    "OtherDeviceID": "ABCD",
    "SAS": [1111,2222,3333]
}' 'http://localhost:4050/verifySAS'

If the SAS match and you also confirm that via the other device's client, the verification should finish successfully.

Contributing

Before submitting pull requests, please read the Matrix.org contribution guidelines regarding sign-off of your work.

Developing

This project depends on libolm for the end-to-end encryption. Therefore, you need to install libolm3 and libolm-dev on Ubuntu / libolm-devel on CentOS to be able to build and run it.

There's a bunch more tools this project uses when developing in order to do things like linting. Some of them are bundled with go (fmt and vet) but some are not. You should install the ones which are not:

go install honnef.co/go/tools/cmd/staticcheck@latest
go install github.com/fzipp/gocyclo/cmd/gocyclo@latest

You can then install the pre-commit hook:

./hooks/install.sh

Architecture


   HOMESERVER
       |
+=============================================================+
|      |                 Go-NEB                               |
| +---------+                                                 |
| | Clients |                                                 |
| +---------+                                                 |
|      |                                                      |
| +---------+       +------------+      +--------------+      |
| | Service |-------| Auth Realm |------| Auth Session |-+    |
| +---------+       +------------+      +--------------+ |    |
|     ^                   ^              +---------------+    |
|     |                   |                                   |
+=============================================================+
      |                   |                   
    WEBHOOK            REDIRECT
    REQUEST            REQUEST

Clients      = A thing which can talk to homeservers and listen for events. /configureClient makes these.
Service      = An individual bot, configured by a user. /configureService makes these.
Auth Realm   = A place where a user can authenticate with. /configureAuthRealm makes these.
Auth Session = An individual authentication session /requestAuthSession makes these.

Viewing the API docs

The full docs can be found on Github Pages. Alternatively, you can locally host the API docs:

# Start a documentation server listening on :6060
GOPATH=$GOPATH:$(pwd) godoc -v -http=localhost:6060 &

# Open up the documentation for go-neb in a browser.
sensible-browser http://localhost:6060/pkg/github.com/matrix-org/go-neb

Docker image

To get started quickly, use the image from docker.io:

docker run -v /path/to/data:/data -e "BASE_URL=http://your.public.url:4050" matrixdotorg/go-neb

If you'd prefer to build the file yourself, clone this repository and build the Dockerfile.

The image sets the following environment variables:

BIND_ADDRESS=:4050
DATABASE_TYPE=sqlite3
DATABASE_URL=/data/go-neb.db?_busy_timeout=5000

The image exposes port 4050 and a volume at /data. The BASE_URL environment variable needs to be set, a volume should be mounted at /data and port 4050 should be appropriately mapped as desired.