{"id":13551121,"url":"https://github.com/devture/matrix-corporal","last_synced_at":"2025-04-04T23:08:49.605Z","repository":{"id":33883108,"uuid":"145540147","full_name":"devture/matrix-corporal","owner":"devture","description":"Matrix Corporal: reconciliator and gateway for a managed Matrix server","archived":false,"fork":false,"pushed_at":"2025-02-25T15:14:59.000Z","size":585,"stargazers_count":150,"open_issues_count":16,"forks_count":14,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-28T22:13:44.630Z","etag":null,"topics":["golang","golang-application","matrix-org"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devture.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"liberapay":"s.pantaleev"}},"created_at":"2018-08-21T09:24:04.000Z","updated_at":"2025-03-25T04:37:26.000Z","dependencies_parsed_at":"2023-01-15T03:08:49.287Z","dependency_job_id":"b4c1f807-83b3-40a1-949e-7a26007bbff3","html_url":"https://github.com/devture/matrix-corporal","commit_stats":{"total_commits":274,"total_committers":6,"mean_commits":"45.666666666666664","dds":"0.021897810218978075","last_synced_commit":"7038ca9c3f7fc0f17bf7a237b8f3212b1d0ad842"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devture%2Fmatrix-corporal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devture%2Fmatrix-corporal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devture%2Fmatrix-corporal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devture%2Fmatrix-corporal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devture","download_url":"https://codeload.github.com/devture/matrix-corporal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247261609,"owners_count":20910108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","golang-application","matrix-org"],"created_at":"2024-08-01T12:01:42.720Z","updated_at":"2025-04-04T23:08:49.585Z","avatar_url":"https://github.com/devture.png","language":"Go","funding_links":["https://liberapay.com/s.pantaleev","https://liberapay.com/s.pantaleev/donate"],"categories":["Go","golang"],"sub_categories":[],"readme":"[![Support room on Matrix](https://img.shields.io/matrix/matrix-corporal:devture.com.svg?label=%23matrix-corporal%3Adevture.com\u0026logo=matrix\u0026style=for-the-badge\u0026server_fqdn=matrix.devture.com)](https://matrix.to/#/#matrix-corporal:devture.com) [![donate](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/s.pantaleev/donate)\n\n# Matrix Corporal: reconciliator and gateway for a managed Matrix server\n\n`matrix-corporal` manages your [Matrix](http://matrix.org/) server according to a configuration policy.\n\nThe point is to have a single source of truth about users/rooms somewhere\n(say in an external system, like your intranet),\nand have something (`matrix-corporal`) continually reconfigure your Matrix server in accordance with it.\n\nIn a way, it can be thought of as \"Kubernetes for Matrix\", in that it takes such a JSON policy as an input,\nand performs **reconciliation** with the Matrix server -- creating, activating, disabling user accounts, making them (automatically) join/leave rooms, etc.\n\nBesides reconciliation, `matrix-policy` also does **firewalling** (acts as a gateway).\nYou can put `matrix-corporal` in front of your [Matrix Synapse](https://github.com/matrix-org/synapse) server,\nand have it capture all Matrix API requests and allow/deny them in accordance with the policy.\n\nWith **reconciliation** and **firewalling** both working together, `matrix-corporal` ensures\nthat your Matrix server's state always matches what the policy says, and that no user\nis allowed to perform actions which take the server out of that equilibrium.\n\nFor more information, read below or jump to the [FAQ](docs/faq.md).\n\n\n## Features\n\nYou give `matrix-corporal` a [policy](docs/policy.md) document by some means (some [policy provider](docs/policy-providers.md), and it takes care of the following things for you:\n\n- creating user accounts according to the [policy](docs/policy.md) or disabling user accounts and revoking access\n\n- authenticating users according to the policy (plain-text passwords, hashed passwords, REST auth)\n\n- changing user profile data (names and avatars), to keep them in sync with the policy\n\n- changing user room memberships, to keep them in sync with the policy\n\n- allowing or denying Matrix API requests, to prevent the server state deviating from the policy\n\n\n## Example\n\nIt's probably best explained with an example. Here's a [policy](docs/policy.md) that `matrix-corporal` can work with:\n\n```json\n{\n\t\"schemaVersion\": 1,\n\n\t\"flags\": {\n\t\t\"allowCustomUserDisplayNames\": false,\n\t\t\"allowCustomUserAvatars\": false\n\t},\n\n\t\"managedRoomIds\": [\n\t\t\"!roomA:example.com\",\n\t\t\"!roomB:example.com\",\n\t],\n\n\t\"hooks\": [\n\t\t{\n\t\t\t\"id\": \"custom-hook-to-prevent-banning\",\n\t\t\t\"eventType\": \"beforeAnyRequest\",\n\t\t\t\"routeMatchesRegex\": \"^/_matrix/client/r0/rooms/([^/]+)/ban\",\n\t\t\t\"methodMatchesRegex\": \"POST\",\n\t\t\t\"action\": \"reject\",\n\t\t\t\"responseStatusCode\": 403,\n\t\t\t\"rejectionErrorCode\": \"M_FORBIDDEN\",\n\t\t\t\"rejectionErrorMessage\": \"Banning is forbidden on this server. We're nice like that!\"\n\t\t},\n\n\t\t{\n\t\t\t\"id\": \"custom-hook-to-reject-room-creation-once-in-a-while\",\n\t\t\t\"eventType\": \"beforeAuthenticatedPolicyCheckedRequest\",\n\t\t\t\"routeMatchesRegex\": \"^/_matrix/client/r0/createRoom\",\n\t\t\t\"action\": \"consult.RESTServiceURL\",\n\t\t\t\"RESTServiceURL\": \"http://hook-rest-service:8080/reject/with-33-percent-chance\",\n\t\t\t\"RESTServiceRequestHeaders\": {\n\t\t\t\t\"Authorization\": \"Bearer SOME_TOKEN\"\n\t\t\t}\n\t\t}\n\t],\n\n\t\"users\": [\n\t\t{\n\t\t\t\"id\": \"@john:example.com\",\n\t\t\t\"active\": true,\n\t\t\t\"authType\": \"plain\",\n\t\t\t\"authCredential\": \"PaSSw0rD\",\n\t\t\t\"displayName\": \"John\",\n\t\t\t\"avatarUri\": \"https://example.com/john.jpg\",\n\t\t\t\"joinedRooms\": [\n\t\t\t\t{\"roomId\": \"!roomA:example.com\", \"powerLevel\": 0},\n\t\t\t\t{\"roomId\": \"!roomB:example.com\", \"powerLevel\": 50}\n\t\t\t]\n\t\t},\n\t\t{\n\t\t\t\"id\": \"@peter:example.com\",\n\t\t\t\"active\": true,\n\t\t\t\"authType\": \"sha1\",\n\t\t\t\"authCredential\": \"a94a8fe5ccb19ba61c4c0873d391e987982fbbd3\",\n\t\t\t\"displayName\": \"Just Peter\",\n\t\t\t\"avatarUri\": \"\",\n\t\t\t\"joinedRooms\": [\n\t\t\t\t{\"roomId\": \"!roomB:example.com\", \"powerLevel\": 0}\n\t\t\t]\n\t\t},\n\t\t{\n\t\t\t\"id\": \"@george:example.com\",\n\t\t\t\"active\": true,\n\t\t\t\"authType\": \"rest\",\n\t\t\t\"authCredential\": \"https://intranet.example.com/_matrix-internal/identity/v1/check_credentials\",\n\t\t\t\"displayName\": \"Georgey\",\n\t\t\t\"avatarUri\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==\",\n\t\t\t\"joinedRooms\": [\n\t\t\t\t{\"roomId\": \"!roomA:example.com\", \"powerLevel\": 25},\n\t\t\t\t{\"roomId\": \"!roomB:example.com\", \"powerLevel\": 50}\n\t\t\t]\n\t\t}\n\t]\n}\n```\n\nThe JSON [policy](docs/policy.md) above, describes the state that your server should have:\n\n- managed rooms - a list of rooms that you want `matrix-corporal` to manage for you. Any other rooms are untouched.\n\n- managed users (including their profile details and authentication data). Any other users are untouched.\n\n- membership information (which users need to be in which rooms). Any other memberships are untouched.\n\n\nAs a result, `matrix-corporal` will perform a sequence of actions, ensuring that:\n\n- all users are created and that their corresponding credentials are made to work\n\n- all user details are made to match the policy (names, avatars, etc.)\n\n- inactive users will be disabled and prevented from logging in\n\n- users are automatically joined to or kicked out of the specified rooms\n\nAny time you change the [policy](docs/policy.md) in the future, `matrix-corporal` acts upon the Matrix server,\nso that its state is made to match the policy.\n\n\n## Installation\n\nTo configure and install `matrix-corporal` on your own server, follow the [README in the docs/ directory](docs/README.md).\n\n\n## Development / Experimenting\n\nTo give `matrix-corporal` a try (without actually installing it anywhere) or to do development on it, refer to the [development introduction](docs/development.md).\n\n\n## Support\n\nMatrix room: [#matrix-corporal:devture.com](https://matrix.to/#/#matrix-corporal:devture.com)\n\nGithub issues: [devture/matrix-corporal/issues](https://github.com/devture/matrix-corporal/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevture%2Fmatrix-corporal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevture%2Fmatrix-corporal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevture%2Fmatrix-corporal/lists"}