https://github.com/matrix-org/synapse-3pid-checker
A module that checks whether a 3PID (email address, phone number) can be allowed to register by querying a remote backend.
https://github.com/matrix-org/synapse-3pid-checker
python synapse
Last synced: 6 months ago
JSON representation
A module that checks whether a 3PID (email address, phone number) can be allowed to register by querying a remote backend.
- Host: GitHub
- URL: https://github.com/matrix-org/synapse-3pid-checker
- Owner: matrix-org
- License: apache-2.0
- Created: 2022-01-31T18:03:22.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2022-10-31T19:07:39.000Z (almost 3 years ago)
- Last Synced: 2025-03-24T13:36:25.880Z (6 months ago)
- Topics: python, synapse
- Language: Python
- Homepage:
- Size: 42 KB
- Stars: 4
- Watchers: 6
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# 3PID checker for Synapse
A module that checks whether a 3PID (email address, phone number) can be allowed to be
registered on the local homeserver by querying a remote backend.
## Installation
From the virtual environment that you use for Synapse, install this module with:
```shell
pip install threepid-checker
```
(If you run into issues, you may need to upgrade `pip` first, e.g. by running
`pip install --upgrade pip`)
Then alter your homeserver configuration, adding to your `modules` configuration:
```yaml
modules:
- module: threepid_checker.ThreepidChecker
config:
# The URL to send requests to when checking if a 3PID can be associated to an account.
# See below for more information.
# Required.
url: https://foo/bar
# If true, the module will only send requests to the URL as part of registering a
# new user. This means no request will be sent to the URL when associating a 3PID with
# an already existing account.
# Optional, defaults to false.
only_check_at_registration: false
```
The configured URL will be hit by a `GET` HTTP request. Note that this is _not_ subject to Synapse's IP blacklist, with 2 parameters to qualify the 3PID:
* `medium`: The 3PID's medium (`email` for an email address, `msisdn` for a phone number)
* `address`: The 3PID's address
The server at that URL is expected to respond with a JSON object that contains the following keys:
* `hs` (string): Required. The name of the homeserver the 3PID is allowed to be associated
on. This is the `server_name` variable in Synapse's configuration file.
The 3PID will be denied if this is absent from the response's body.
* `requires_invite` (bool): Optional. Whether an invite is required for this 3PID to be associated
with an account on this homeserver. What qualifies as an invite is left to the
server serving the configured URL to define. Defaults to `false`.
* `invited` (bool): Optional. Whether there is a pending invite for the 3PID. Defaults to `false`.
The module will deny the 3PID's association based on the response if:
* `hs` does not match the homeserver's configured server name, or is missing, or
* `requires_invite` is `true` and `invited` is `false` or missing
The 3PID will be allowed to be associated with a local user otherwise.
## Development
In a virtual environment with pip ≥ 21.1, run
```shell
pip install -e .[dev]
```
To run the unit tests, you can either use:
```shell
tox -e py
```
or
```shell
trial tests
```
To run the linters and `mypy` type checker, use `./scripts-dev/lint.sh`.
## Releasing
The exact steps for releasing will vary; but this is an approach taken by the
Synapse developers (assuming a Unix-like shell):
1. Set a shell variable to the version you are releasing (this just makes
subsequent steps easier):
```shell
version=X.Y.Z
```
2. Update `setup.cfg` so that the `version` is correct.
3. Stage the changed files and commit.
```shell
git add -u
git commit -m v$version -n
```
4. Push your changes.
```shell
git push
```
5. When ready, create a signed tag for the release:
```shell
git tag -s v$version
```
Base the tag message on the changelog.
6. Push the tag.
```shell
git push origin tag v$version
```
7. Create a source distribution and upload it to PyPI:
```shell
python -m build
twine upload dist/threepid_checker-$version*
```