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:

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:

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

pip install -e .[dev]

To run the unit tests, you can either use:

tox -e py

or

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):

   version=X.Y.Z

2. Update setup.cfg so that the version is correct.

3. Stage the changed files and commit.

   git add -u
   git commit -m v$version -n

4. Push your changes.

   git push

5. When ready, create a signed tag for the release:

   git tag -s v$version

   Base the tag message on the changelog.

6. Push the tag.

   git push origin tag v$version

7. Create a source distribution and upload it to PyPI:

   python -m build
   twine upload dist/threepid_checker-$version*