Add an endpoint to invite guests to a room by email by devonh · Pull Request #304 · element-hq/element-modules

devonh · 2026-09-28T20:28:20Z

Part of https://github.com/element-hq/backend-internal/issues/292

Adds POST /_synapse/client/invite_guests, which invites a list of email addresses to join a room as guests. For each address, the module mints a single-use, passwordless invite code with MAS's POST /api/admin/v1/user-registration-tokens, pinned to that address, the room, and a guest username template. Once every code is minted, it has MAS email them all with POST /api/admin/v1/user-registration-tokens/invite-emails (element-hq/matrix-authentication-service#6026). An address MAS refuses fails the request before any email is sent.

The email names the room and the inviter. The invitee signs up through the link as a new guest, or signs in with an existing account, and lands on the room. There they ask to join, and a member approves them.

The endpoint currently sends no room invite event. The design for how that will work is still undecided and will come later.

The functionality added by this PR is off by default. email_invites.enabled turns it on.

email_invites:
  enabled: true
  max_emails: 20            # addresses per request
  per_inviter_per_hour: 50  # addresses per user per hour, per worker
  invite_lifetime: 604800   # seconds an invite link stays valid

Synapse's own email-invite controls don't apply yet: block_non_admin_invites, and the 3pid spam-checker and third-party-rules callbacks. A follow-up PR (#306) adds them.

Mounting the endpoint whenever `mas` was set gave every MAS deployment a way to send email on its behalf as soon as it upgraded. It's now opt-in. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZdGaj9bJcn5QeeUw8YXoF

The servlet read the sender's level from `m.room.power_levels` by hand, which misses room creators: in a version 12 room they outrank every level without being listed in it, so a creator was refused whenever the room's `invite` level was above zero. `get_user_power_level` handles creators and rooms without power levels as Synapse's own invite check does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZdGaj9bJcn5QeeUw8YXoF

Guests can't invite anyone by Matrix ID, so they can't invite by email either. An invited guest can only get into a room by asking to join, which needs the join rule `knock`: Element Web offers knocking only there, not on `knock_restricted`. And a room forbidden to guests never lets one in. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZdGaj9bJcn5QeeUw8YXoF

Every invite is an email sent from this server's domain, so the limit counts emails rather than requests, and charges a request's emails all or nothing. The module API has no rate limiter, so this uses Synapse's own `Ratelimiter` through `api._hs`, as the room list patch does. It's per worker and resets on restart. Addresses are deduplicated ignoring case first, so a repeated address is neither counted twice nor sent to MAS twice. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZdGaj9bJcn5QeeUw8YXoF

MAS names them in the invite email, so the invitee knows which room they're asked to join and who asked. Room members set both, so a value that isn't a non-empty string is left out, and MAS falls back to its generic wording. This also moves the request to `POST /api/admin/v1/invite-guests`, which is what MAS calls the endpoint that takes these fields. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZdGaj9bJcn5QeeUw8YXoF

Every MAS error reached the inviter as a 500. MAS's 400 is about the request the inviter made, such as a malformed address, so it passes through with MAS's message, and its 404 means MAS has guest invites turned off. Anything else, including a refused token request, a timeout or MAS being unreachable, is a 502: none of it is the inviter's to fix. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZdGaj9bJcn5QeeUw8YXoF

Covers the `email_invites` options, what the endpoint checks and answers, and a deployment checklist, including the advice to invite colleagues by Matrix ID rather than email. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CZdGaj9bJcn5QeeUw8YXoF

devonh · 2026-10-09T21:30:22Z

+        for email in unique_emails.values():
+            localpart = self._config.user_id_prefix + "".join(
+                secrets.choice(string.ascii_lowercase + string.digits)
+                for _ in range(32)
+            )
+            invites.append({"email": email, "username": localpart})


This duplicates a small little bit of the guest_registration_servlet to generate a random localpart.
It drops the retry on localpart collision. 32 random characters should be more than random enough to never feasibly collide.
It also drops the existence check. While it could be added here as another layer, the new guest email invites architecture means MAS will check for existence when creating the invite, then MAS will check again when the invited guest follows the invite link to actually create the user account.

…nvites Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LpxhUvvbRYpQSxhidPnnP7

devonh · 2026-10-09T21:40:46Z

+    max_emails: int = 20
+    per_inviter_per_hour: int = 50


These defaults seem okay 🤷
Basically just numbers to prevent users from generating email / endpoint spam.
Either way, they are configurable to meet a deployments actual usage.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LpxhUvvbRYpQSxhidPnnP7

devonh · 2026-10-09T22:21:40Z

+    async def test_mas_bad_request(self) -> None:
+        module, module_api, _ = self.create_module()
+        module_api.http_client.post_json_get_json.side_effect = HttpResponseException(
+            400, "Bad Request", b'{"errors":[{"title":"Invalid email address"}]}'
+        )
+
+        status, response = await self.render(module)
+
+        self.assertEqual((status, response), (400, {"msg": "Invalid email address"}))
+
+    async def test_mas_bad_request_unknown_body(self) -> None:
+        module, module_api, _ = self.create_module()
+        module_api.http_client.post_json_get_json.side_effect = HttpResponseException(
+            400, "Bad Request", b"<html>Bad Request</html>"
+        )
+
+        status, response = await self.render(module)
+
+        self.assertEqual((status, response), (400, {"msg": "MAS refused the invites"}))
+
+    async def test_mas_invites_disabled(self) -> None:
+        module, module_api, _ = self.create_module()
+        module_api.http_client.post_json_get_json.side_effect = HttpResponseException(
+            404, "Not Found", b'{"errors":[{"title":"Not found"}]}'
+        )
+
+        with self.assertLogs("synapse.contrib", "WARNING"):
+            status, response = await self.render(module)
+
+        self.assertEqual(status, 404)


I could easily be persuaded to drop these 3 tests.
They add a small amount of value in exercising all the code paths.
They are also super tiny, so easy enough to keep.

devonh · 2026-10-09T22:27:51Z

CI failing is due to a failure on main.
#308 fixes the issue.

Copilot

🟡 Changes recommended

Room validation, rate-limit enforcement, and upstream response validation have unresolved correctness and security issues.

4 open findings

Prevent requester exemptions bypassing invite rate limits · New
Validate room IDs before state lookup · New
Reject boolean and out-of-range scheduled counts · New
Fix broken deployment checklist link · New

What changed in this PR

Adds an opt-in endpoint for inviting room guests by email through MAS, including validation, authorization, rate limiting, configuration, documentation, and tests.

Changes:

Adds POST /_synapse/client/invite_guests.
Integrates MAS guest-invite scheduling and error handling.
Adds configuration, documentation, and test coverage.

File	Description
`README.md`	Documents configuration and endpoint behavior.
`config.py`	Defines email-invite configuration.
`guest_invite_servlet.py`	Implements validation, authorization, and scheduling.
`guest_module.py`	Parses configuration and registers the endpoint.
`mas_admin_client.py`	Calls MAS’s guest-invite API.
`test_guest_invite_servlet.py`	Tests endpoint behavior and failures.
`test_guest_module.py`	Tests configuration parsing.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

devonh · 2026-10-14T22:16:40Z

+        scheduled = response.get("scheduled")
+        if not isinstance(scheduled, int):
+            raise ValueError("MAS guest invite response missing `scheduled` field")


While this is technically more correct, it is adding a lot more complexity to validate a value we are receiving directly from MAS (not a user, config, or anything outside our control).
I'm inclined to leave it as is

Each invite now carries the username template `<user_id_prefix>{random}`, which MAS fills in when the guest signs up. The guest's localpart is then chosen once, when the account is created. Before, each invite pinned a localpart of its own. Only the first one registered was ever used, because MAS refuses a second account for an address that is in use. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RkxQWj8RAKd7iZ1JQtXdxm

MAS serves the invites at `POST /api/admin/v1/room-invites`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RkxQWj8RAKd7iZ1JQtXdxm

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RkxQWj8RAKd7iZ1JQtXdxm

The module mints a single-use, passwordless invite code per address with MAS's registration token admin API, then has MAS email them all with `POST /api/admin/v1/user-registration-tokens/invite-emails`. Every code is minted before any email is sent, so an address MAS refuses sends nothing. The module now sets the codes' expiry, from the new `email_invites.invite_lifetime` option. A 404 from MAS is a 502: MAS has no switch for these endpoints any more, so it means MAS is too old or isn't at `mas.admin_api_base_url`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R27QDzJTWSBxkrfbxBxcKF

MAS now takes a registration token's username as a minijinja template, with `random` as its variable. The old `{random}` placeholder is refused when minting a token by a MAS with element-hq/matrix-authentication-service#6026's template check. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0145EoXnCPYo2bnhuGTohX55

devonh and others added 8 commits October 4, 2026 16:14

Add an endpoint to invite guests to a room by email

447e570

devonh force-pushed the devonh/room-invite-guests branch from da4f448 to 2370ccc Compare October 5, 2026 21:17

devonh mentioned this pull request Oct 5, 2026

Apply Synapse's invite controls to guest invites #306

Draft

devonh added this pull request to stack #307 October 5, 2026 21:25

Cleanup README

ac66068

devonh commented Oct 9, 2026

View reviewed changes

Use Synapse's constants for event types and content fields in guest i…

d9be685

…nvites Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LpxhUvvbRYpQSxhidPnnP7

devonh commented Oct 9, 2026

View reviewed changes

Allow guest invites to knock_restricted rooms

adba40c

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LpxhUvvbRYpQSxhidPnnP7

devonh commented Oct 9, 2026

View reviewed changes

devonh marked this pull request as ready for review October 9, 2026 22:28

devonh requested a review from a team as a code owner October 9, 2026 22:28

devonh requested a review from erikjohnston October 9, 2026 22:28

erikjohnston requested a balanced review from Copilot October 13, 2026 08:26

Copilot started reviewing on behalf of erikjohnston October 13, 2026 08:28

View session

Copilot AI reviewed Oct 13, 2026

View reviewed changes

devonh and others added 3 commits October 13, 2026 19:01

Call MAS's room-invites endpoint

631a214

MAS serves the invites at `POST /api/admin/v1/room-invites`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RkxQWj8RAKd7iZ1JQtXdxm

Drop a link to the removed deployment checklist

c87ced9

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RkxQWj8RAKd7iZ1JQtXdxm

erikjohnston approved these changes Oct 14, 2026

View reviewed changes

devonh mentioned this pull request Oct 16, 2026

Invite email addresses to rooms element-hq/matrix-authentication-service#6026

Draft

Navigation Menu

Repository navigation

Add an endpoint to invite guests to a room by email - #304

Add an endpoint to invite guests to a room by email#304
devonh wants to merge 16 commits into
mainfrom
devonh/room-invite-guests

devonh commented Sep 28, 2026 •

edited

Loading

Uh oh!

devonh Oct 9, 2026

Uh oh!

devonh Oct 9, 2026

Uh oh!

devonh Oct 9, 2026

Uh oh!

devonh commented Oct 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

devonh Oct 14, 2026

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

devonh commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devonh Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

devonh Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

devonh Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

devonh commented Oct 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

devonh Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

devonh commented Sep 28, 2026 •

edited

Loading