- Python 92.8%
- HTML 3.8%
- CSS 3.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .github | ||
| email_account_validity | ||
| tests | ||
| .gitignore | ||
| LICENSE | ||
| README.md | ||
| setup.py | ||
| tox.ini | ||
Synapse email account validity
A Synapse plugin module to manage account validity using validation emails.
After a configured time, this module automatically expires user accounts. When a user is
expired, Synapse will respond to any request authenticated by the user's access token
with a 403 error containing the ORG_MATRIX_EXPIRED_ACCOUNT error code. Some time before
an account expires (defined by the module's configuration), an email is sent to the user
with instructions to renew the validity of their account.
This module requires:
- Synapse >= 1.39.0
- sqlite3 >= 3.24.0 (if using SQLite with Synapse (not recommended))
Installation
Thi plugin can be installed via PyPI:
pip install synapse-email-account-validity
Config
Add the following in your Synapse config:
modules:
- module: email_account_validity.EmailAccountValidity
config:
# The maximum amount of time an account can stay valid for without being renewed.
period: 6w
# How long before an account expires should Synapse send it a renewal email.
renew_at: 1w
# Whether to include a link to click in the emails sent to users. If false, only a
# renewal token is sent, in which case a shorter token is used, and the
# user will need to copy it into a compatible client that will send an
# authenticated request to the server.
# Defaults to true.
send_links: true
The syntax for durations is the same as in the rest of Synapse's configuration file.
Templates
The templates the module will use are:
notice_expiry.(html|txt): The content of the renewal email. It gets passed the following variables:app_name: The value configured forapp_namein the Synapse configuration file (under theemailsection).display_name: The display name of the user needing renewal.expiration_ts: A timestamp in milliseconds representing when the account will expire. Templates can use theformat_ts(with a date format as the function's parameter) to format this timestamp into a human-readable date.url: The URL the user is supposed to click on to renew their account. Ifsend_linksis set tofalsein the module's configuration, the value of this variable will beNone.renewal_token: The token to use in order to renew the user's account. Ifsend_linksis set tofalse, templates should prefer this variable tourl.
account_renewed.html: The HTML to display to a user when they successfully renew their account. It gets passed the following vaiables:expiration_ts: A timestamp in milliseconds representing when the account will expire. Templates can use theformat_ts(with a date format as the function's parameter) to format this timestamp into a human-readable date.
account_previously_renewed.html: The HTML to display to a user when they try to renew their account with a token that's valid but previously used. It gets passed the same variables asaccount_renewed.html.invalid_token.html: The HTML to display to a user when they try to renew their account with the wrong token. It doesn't get passed any variable.
You can find and change the default templates here.
Admins can install custom templates either by changing the default ones directly, or by
configuring Synapse with a custom template directory that contains the custom templates.
Note that the templates directory contains two files that aren't templates (mail.css
and mail-expiry.css), but are used by email templates to apply visual adjustments.
Admins that don't need to customise their templates can just use the module as is and ignore the previous paragraph.
Routes
This plugin exposes three HTTP routes to manage account validity:
POST /_synapse/client/email_account_validity/send_mail, which any registered user can hit with an access token to request a renewal email to be sent to their email addresses.GET /_synapse/client/email_account_validity/renew, which requires atokenquery parameter containing the latest token sent via email to the user, which renews the account associated with the token.POST /_synapse/client/email_account_validity/admin, which any server admin can use to manage the account validity of any registered user. It takes a JSON body with the following keys:user_id(string, required): The Matrix ID of the user to update.expiration_ts(integer, optional): The new expiration timestamp for this user, in milliseconds. If no token is provided, a value corresponding tonow + periodis used.enable_renewal_emails(boolean, optional): Whether to allow renewal emails to be sent to this user.
The two first routes need to be reachable by the end users for this feature to work as intended.
Development and Testing
This repository uses tox to run tests.
Tests
This repository uses unittest to run the tests located in the tests
directory. They can be ran with tox -e tests.
Making a release
git tag vX.Y
python3 setup.py sdist
twine upload dist/synapse-email-account-validity-X.Y.tar.gz
git push origin vX.Y