diff --git a/README.md b/README.md index 1b556aa..a0dc571 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,6 @@ * [Restricting available homeserver](#restricting-available-homeserver) * [Protecting appservice managed users](#protecting-appservice-managed-users) * [Adding custom menu items](#adding-custom-menu-items) - * [Providing support URL](#providing-support-url) * [Usage](#usage) * [Supported Synapse](#supported-synapse) * [Prerequisites](#prerequisites) @@ -157,120 +156,20 @@ That way `username` and `homeserver` fields will be pre-filled with `admin` and You can restrict the homeserver(s), so that the user can no longer define it himself. -Edit `config.json` to restrict either to a single homeserver: - -```json -{ - "restrictBaseUrl": "https://matrix.example.com" -} -``` - -similar for `/.well-known/matrix/client`: - -```json -{ - "cc.etke.synapse-admin": { - "restrictBaseUrl": "https://matrix.example.com" - } -} -``` - -or to a list of homeservers: - -```json -{ - "restrictBaseUrl": ["https://your-first-matrix-server.example.com", "https://your-second-matrix-server.example.com"] -} -``` - -similar for `/.well-known/matrix/client`: - -```json -{ - "cc.etke.synapse-admin": { - "restrictBaseUrl": ["https://your-first-matrix-server.example.com", "https://your-second-matrix-server.example.com"] - } -} -``` +[Documentation](./docs/restrict-hs.md) ### Protecting appservice managed users To avoid accidental adjustments of appservice-managed users (e.g., puppets created by a bridge) and breaking the bridge, you can specify the list of MXIDs (regexp) that should be prohibited from any changes, except display name and avatar. -Example for [mautrix-telegram](https://github.com/mautrix/telegram) - -```json -{ - "asManagedUsers": ["^@telegram_[a-zA-Z0-9]+:example\\.com$"] -} -``` - -similar for `/.well-known/matrix/client`: - -```json -{ - "cc.etke.synapse-admin": { - "asManagedUsers": ["^@telegram_[a-zA-Z0-9]+:example\\.com$"] - } -} -``` +[Documentation](./docs/system-users.md) ### Adding custom menu items -You can add custom menu items to the main menu by providing a `menu` array in the `config.json`. +You can add custom menu items to the main menu by providing a `menu` array in the config. -```json -{ - "menu": [ - { - "label": "Contact support", - "icon": "SupportAgent", - "url": "https://github.com/etkecc/synapse-admin/issues" - } - ] -} -``` - -similar for `/.well-known/matrix/client`: - -```json -{ - "cc.etke.synapse-admin": { - "menu": [ - { - "label": "Contact support", - "icon": "SupportAgent", - "url": "https://github.com/etkecc/synapse-admin/issues" - } - ] - } -} -``` - -Where `icon` is one of the [preloaded icons](./src/components/icons.ts) - -### Providing support URL - -**Deprecated**: use `menu` config option described above. Automatically migrated to the `menu` if the `supportURL` is present. - -~~Synapse Admin provides a support link in the main menu - `Contact support`. By default, the link points to the GitHub issues page of the project. You can change this link by providing a `supportURL` in the `config.json`.~~ - -```json -{ - "supportURL": "https://example.com/support" -} -``` - -similar for `/.well-known/matrix/client`: - -```json -{ - "cc.etke.synapse-admin": { - "supportURL": "https://example.com/support" - } -} -``` +[Documentation](./docs/custom-menu.md) ## Usage diff --git a/docs/custom-menu.md b/docs/custom-menu.md new file mode 100644 index 0000000..93a4576 --- /dev/null +++ b/docs/custom-menu.md @@ -0,0 +1,45 @@ +# Custom Menu Items + +You can add custom menu items to the main menu (sidebar) by providing a `menu` array in the config. +This is useful for adding links to external sites or other pages in your documentation, like a support page or internal wiki. + +## Configuration + +The examples below contain the configuration settings to add a link to the [Synapse Admin issues](https://github.com/etke.cc/synapse-admin/issues). + +Each `menu` item can contain the following fields: + +* `label` (required): The text to display in the menu. +* `icon` (optional): The icon to display next to the label, one of the [../src/components/icons.ts] icons, otherwise a +default icon will be used. +* `url` (required): The URL to navigate to when the menu item is clicked. + +### config.json + +```json +{ + "menu": [ + { + "label": "Contact support", + "icon": "SupportAgent", + "url": "https://github.com/etkecc/synapse-admin/issues" + } + ] +} +``` + +### `/.well-known/matrix/client` + +```json +{ + "cc.etke.synapse-admin": { + "menu": [ + { + "label": "Contact support", + "icon": "SupportAgent", + "url": "https://github.com/etkecc/synapse-admin/issues" + } + ] + } +} +``` diff --git a/docs/restrict-hs.md b/docs/restrict-hs.md new file mode 100644 index 0000000..fb22d32 --- /dev/null +++ b/docs/restrict-hs.md @@ -0,0 +1,42 @@ +# Restricting available homeserver + +If you want to have your Synapse Admin instance work only with specific homeserver(-s), +you can do that by setting `restrictBaseUrl` in the configuration. + +## Configuration + +You can do that for a single homeserver or multiple homeservers at once, as `restrictBaseUrl` accepts both a string and +an array of strings. + +The examples below contain the configuration settings to restrict the Synapse Admin instance to work only with +`example.com` (with Synapse runing at `matrix.example.com`) and +`example.net` (with Synapse running at `synapse.example.net`) homeservers. +Note that the homeserver URL should be the _actual_ homeserver URL, and not the delegated one. + +So, if you have a homeserver `example.com` where users have MXIDs like `@user:example.com`, +but actual Synapse is installed on `matrix.example.com` subdomain, you should use `https://matrix.example.com` in the +configuration. + +### config.json + +```json +{ + "restrictBaseUrl": [ + "https://matrix.example.com", + "https://synapse.example.net" + ] +} +``` + +### `/.well-known/matrix/client` + +```json +{ + "cc.etke.synapse-admin": { + "restrictBaseUrl": [ + "https://matrix.example.com", + "https://synapse.example.net" + ] + } +} +``` diff --git a/docs/system-users.md b/docs/system-users.md new file mode 100644 index 0000000..fec91c9 --- /dev/null +++ b/docs/system-users.md @@ -0,0 +1,42 @@ +# System / Appservice-managed Users + +Inadvertently altering system user accounts managed by appservices (such as bridges) / system (such as bots) is a common issue. +Editing, deleting, locking, or changing the passwords of these appservice-managed accounts can cause serious problems. +To prevent this, we've added a new feature that blocks these types of modifications to such accounts, +while still allowing other risk-free changes (changing display names and avatars). +By defining a list of MXID regex patterns in the new `asManagedUsers` configuration setting, +you can protect these accounts from accidental changes. + +## Configuration + +The examples below contain the configuration settings to mark +[Telegram bridge (mautrix-telegram)](https://github.com/mautrix/telegram), +[Slack bridge (mautrix-slack)](https://github.com/mautrix/slack), +and [Baibot](https://github.com/etkecc/baibot) users of `example.com` homeserver as appservice-managed users, +just to illustrate the options to protect both specific MXIDs (as in the Baibot example) and all puppets of a bridge (as in the Telegram and Slack examples). + +### config.json + +```json +"asManagedUsers": [ + "^@baibot:example\\.com$", + "^@slackbot:example\\.com$", + "^@slack_[a-zA-Z0-9\\-]+:example\\.com$", + "^@telegrambot:example\\.com$", + "^@telegram_[a-zA-Z0-9]+:example\\.com$" +] +``` + +### `/.well-known/matrix/client` + +```json +"cc.etke.synapse-admin": { + "asManagedUsers": [ + "^@baibot:example\\.com$", + "^@slackbot:example\\.com$", + "^@slack_[a-zA-Z0-9\\-]+:example\\.com$", + "^@telegrambot:example\\.com$", + "^@telegram_[a-zA-Z0-9]+:example\\.com$" + ] +} +```