Matrix Corporal: reconciliator and gateway for a managed Matrix server

matrix-corporal manages your Matrix server according to a configuration policy.

The point is to have a single source of truth about users/rooms somewhere (say in an external system, like your intranet), and have something (matrix-corporal) continually reconfigure your Matrix server in accordance with it.

In a way, it can be thought of as "Kubernetes for Matrix", in that it takes such a JSON policy as an input, and performs reconciliation with the Matrix server -- creating, activating, disabling user accounts, making them (automatically) join/leave rooms, etc.

Besides reconciliation, matrix-policy also does firewalling (acts as a gateway). You can put matrix-corporal in front of your Matrix Synapse server, and have it capture all Matrix API requests and allow/deny them in accordance with the policy.

With reconciliation and firewalling both working together, matrix-corporal ensures that your Matrix server's state always matches what the policy says, and that no user is allowed to perform actions which take the server out of that equilibrium.

For more information, read below or jump to the FAQ.

Features

You give matrix-corporal a policy document by some means (some policy provider, and it takes care of the following things for you:

• creating user accounts according to the policy or disabling user accounts and revoking access

• authenticating users according to the policy (plain-text passwords, hashed passwords, REST auth)

• changing user profile data (names and avatars), to keep them in sync with the policy

• changing user room memberships, to keep them in sync with the policy

• allowing or denying Matrix API requests, to prevent the server state deviating from the policy

Example

It's probably best explained with an example. Here's a policy that matrix-corporal can work with:

{
	"schemaVersion": 1,

	"flags": {
		"allowCustomUserDisplayNames": false,
		"allowCustomUserAvatars": false
	},

	"managedRoomIds": [
		"!roomA:example.com",
		"!roomB:example.com",
	],

	"hooks": [
		{
			"id": "custom-hook-to-prevent-banning",
			"eventType": "beforeAnyRequest",
			"routeMatchesRegex": "^/_matrix/client/r0/rooms/([^/]+)/ban",
			"methodMatchesRegex": "POST",
			"action": "reject",
			"responseStatusCode": 403,
			"rejectionErrorCode": "M_FORBIDDEN",
			"rejectionErrorMessage": "Banning is forbidden on this server. We're nice like that!"
		},

		{
			"id": "custom-hook-to-reject-room-creation-once-in-a-while",
			"eventType": "beforeAuthenticatedPolicyCheckedRequest",
			"routeMatchesRegex": "^/_matrix/client/r0/createRoom",
			"action": "consult.RESTServiceURL",
			"RESTServiceURL": "http://hook-rest-service:8080/reject/with-33-percent-chance",
			"RESTServiceRequestHeaders": {
				"Authorization": "Bearer SOME_TOKEN"
			}
		}
	],

	"users": [
		{
			"id": "@john:example.com",
			"active": true,
			"authType": "plain",
			"authCredential": "PaSSw0rD",
			"displayName": "John",
			"avatarUri": "https://example.com/john.jpg",
			"joinedRooms": [
				{"roomId": "!roomA:example.com", "powerLevel": 0},
				{"roomId": "!roomB:example.com", "powerLevel": 50}
			]
		},
		{
			"id": "@peter:example.com",
			"active": true,
			"authType": "sha1",
			"authCredential": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
			"displayName": "Just Peter",
			"avatarUri": "",
			"joinedRooms": [
				{"roomId": "!roomB:example.com", "powerLevel": 0}
			]
		},
		{
			"id": "@george:example.com",
			"active": true,
			"authType": "rest",
			"authCredential": "https://intranet.example.com/_matrix-internal/identity/v1/check_credentials",
			"displayName": "Georgey",
			"avatarUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
			"joinedRooms": [
				{"roomId": "!roomA:example.com", "powerLevel": 25},
				{"roomId": "!roomB:example.com", "powerLevel": 50}
			]
		}
	]
}

The JSON policy above, describes the state that your server should have:

• managed rooms - a list of rooms that you want matrix-corporal to manage for you. Any other rooms are untouched.

• managed users (including their profile details and authentication data). Any other users are untouched.

• membership information (which users need to be in which rooms). Any other memberships are untouched.

As a result, matrix-corporal will perform a sequence of actions, ensuring that:

• all users are created and that their corresponding credentials are made to work

• all user details are made to match the policy (names, avatars, etc.)

• inactive users will be disabled and prevented from logging in

• users are automatically joined to or kicked out of the specified rooms

Any time you change the policy in the future, matrix-corporal acts upon the Matrix server, so that its state is made to match the policy.

Installation

To configure and install matrix-corporal on your own server, follow the README in the docs/ directory.

Development / Experimenting

To give matrix-corporal a try (without actually installing it anywhere) or to do development on it, refer to the development introduction.

Support

Matrix room: #matrix-corporal:devture.com

Github issues: devture/matrix-corporal/issues