[devonh]

TODO:
This description is still LLM generated. I will personally reword it before marking this PR as ready for review.

Lets an admin API client email the invite link of a registration token. It's built for the restricted-guests Synapse module, whose invite_guests endpoint (element-hq/element-modules#304) checks the inviter and the room, mints one token per invitee, then has MAS email them all.

Replaces #6003.

Minting: POST /api/admin/v1/user-registration-tokens

It now takes a room_id, and checks what a token pins before minting it:

• a pinned email must parse;
• a username template (a username containing {, rendered with minijinja; see Templated username for registration tokens #6051) must render with a sample random, and the result must pass the registration policy. Otherwise it's a 400 carrying the render error. A template isn't checked for being taken;
• a pinned email or username must pass the registration policy (400, naming every violation), so no token is minted that its registration form would refuse;
• a pinned username that isn't a template must not be taken (409).

The module mints each invite as:

POST /api/admin/v1/user-registration-tokens
{
  "email": "bob@partner.example",
  "username": "guest-{{ random }}",
  "passwordless": true,
  "usage_limit": 1,
  "expires_at": "2026-10-23T12:00:00Z",
  "room_id": "!abc:example.com"
}

Sending: POST /api/admin/v1/user-registration-tokens/invite-emails

POST /api/admin/v1/user-registration-tokens/invite-emails
{
  "invites": [
    { "registration_token_id": "01J…" },
    { "registration_token_id": "01K…", "email": "carol@example.com" }
  ],
  "room_name": "Project X",
  "inviter": "@alice:example.com",
  "inviter_name": "Alice"
}
→ 202 {"scheduled": 2}

• Who can call it: admin API clients (urn:mas:admin), as for every admin endpoint.
• Recipient: a token that pins an email is sent to that email; email may be given, but must match it, ignoring case. A token without one needs email, so a multi-use token can be sent to several addresses.
• Validation, before anything is scheduled: every token exists (404) and is valid (400), every address parses, and room_name is only given if every token has a room. A token and address given more than once, ignoring case, are sent once. The batch commits as a whole.
• Untrusted text: the room name and the inviter's display name come from room state. They're stripped of control and bidi characters and truncated to 100 characters before they reach a job. The inviter's Matrix ID is kept whole or left out, never cut.
• At send time: the job looks the token up again, and sends nothing if it has been revoked, used up or has expired since.

The link is /register?token=…. For a token with a room, the email names the room and the inviter, and after signing up, or signing in with an existing account, the invitee is sent to the room in their client, where they ask to join. For a token without a room, the email invites them to the server.

Every guest invite is an invite registration: its form offers no upstream providers, and it skips the registration rate limit.

There is no configuration: the caller sets each token's expiry, and room_invites.client_room_url (#6025) is still where invitees are sent.

Notes for review

• Only MAS's users are checked for a taken username at mint. POST /register checks the homeserver when the guest signs up.
• Sends are spaced 100 ms apart within a request, so a batch doesn't burst against the SMTP server.
• The email is English only for now.
• The token API returns each token's invite_url, so the client that mints a token can read its link. Emailing it through MAS doesn't change who can see it.

[cloudflare-workers-and-pages]

Deploying matrix-authentication-service-docs with    Cloudflare Pages

Latest commit:	1a7956a
Status:	✅  Deploy successful!
Preview URL:	https://d90b457f.matrix-authentication-service-docs.pages.dev
Branch Preview URL:	https://devonh-invite-guests.matrix-authentication-service-docs.pages.dev

View logs

[github-actions]

A build for this PR at commit a2424d8 has been created through the Z-Build-Workflow label by sandhose.

Docker image is available at:

• ghcr.io/element-hq/matrix-authentication-service:pr-6026
• ghcr.io/element-hq/matrix-authentication-service:sha-a2424d8

Pre-built binaries are available through the workflow run artifacts.

[github-actions]

A build for this PR at commit 4b7d820 has been created through the Z-Build-Workflow label by sandhose.

Docker image is available at:

• ghcr.io/element-hq/matrix-authentication-service:pr-6026
• ghcr.io/element-hq/matrix-authentication-service:sha-4b7d820

Pre-built binaries are available through the workflow run artifacts.