Room Invite Flows#

A room invite in Matrix follows the path: inviter sends m.room.member invite event → invitee sees the invite in their room list → invitee accepts (joins) or declines. Element Web adds several layers on top of this protocol-level flow:

1. Identity confirmation — warns before inviting users whose cryptographic identity is unknown 1
2. Error normalization — translates invite-specific join failures (e.g. "unreachable room") into user-friendly messages 2
3. Encrypted history sharing (MSC4268) — optionally sends a bundle of historical room keys to the invited user so they can decrypt past messages 3 4 5

The implementation spans two repositories: element-web (UI, dialogs, RoomViewStore) and matrix-js-sdk (client API, crypto backend, rust-crypto).

Invite UI: Unknown Identity Confirmation#

Before sending any invite, InviteDialog.tsx checks whether each target's cryptographic identity is known. The check runs in onGoButtonPressed(): for each target it calls crypto.getUserVerificationStatus(userId).known 6. Users that return false (or that are not Matrix user IDs) are collected into unknownIdentityUsers.

If any unknown-identity users are present, the dialog transitions to UnknownIdentityUsersWarningDialog instead of proceeding to send invites. The warning dialog has two modes 7:

• Invite mode — "Invite" (continue anyway) or "Remove" (remove the unknown users from the target list)
• DM mode — "Continue" or "Cancel"

If the unknown-identity list is empty, startDmOrSendInvites() is called directly 8. This feature was introduced in 1.

Join Error Handling and Unreachable Rooms#

When a user accepts an invite and the join attempt fails, RoomViewStore.showJoinRoomError() normalizes the error and shows a modal. The key error cases are:

The 404 "unreachable room" path is the most invite-specific case. getInvitingUserId() identifies the inviter by checking the room's current invite membership event, then the server suffix of the inviting user ID determines which of the two messages is shown 9.

Type safety 2: JoinRoomErrorPayload.err was widened from MatrixError to generic Error, and roomId was made string | null. Non-Error values thrown during join are now wrapped in UserFriendlyError before dispatch. The null guard roomId && this.getInvitingUserId(roomId) prevents crashes when roomId is unavailable 10. joinRoomError() calls showJoinRoomError() only when !canAskToJoin 11, so "knock" flows are not affected.

Encrypted History Sharing (MSC4268)#

MSC4268 defines how a room member can share historical encryption keys with a newly invited user via an m.room_key_bundle to-device message. Three interlinked matrix-js-sdk PRs implement this in the rust-crypto backend.

History Visibility Gate#

Key bundles are only sent when the room's current history visibility is shared or world_readable 4. If visibility is invited or joined, shareRoomHistoryWithUser() skips the bundle and logs a debug message. This prevents accidentally exposing encrypted history to users who should not see pre-invite messages. The check uses room.getHistoryVisibility() in the invite flow in src/client.ts 4.

Late Bundle Arrival#

There is a race condition where the invitee may join the room before the m.room_key_bundle to-device message arrives from the inviter's server. The fix in 3:

• joinRoom({ acceptSharedHistory: true }) calls maybeAcceptKeyBundle() on the crypto backend, which returns Promise<boolean>
• true → bundle is already present and imported immediately
• false → bundle not yet arrived; markRoomAsPendingKeyBundle(roomId, inviterId) is called so the backend will auto-import the bundle when it arrives via to-device delivery

The markRoomAsPendingKeyBundle() method is a new addition to the CryptoBackend interface 3. Handling across session reloads was deferred to a separate PR (partially fixes element-web #30740).

Key Backup Before Bundle Construction#

When building the key bundle to send to an invitee, the local client may be missing keys for older messages (e.g., if the client recently logged in). To avoid incomplete bundles, shareRoomHistoryWithUser() in src/rust-crypto/rust-crypto.ts 5 now:

1. Checks olmMachine.hasDownloadedAllRoomKeys() for the room
2. If not downloaded, calls backupManager.downloadLatestRoomKeyBackup(roomId) — a new method in src/rust-crypto/backup.ts that hits /room_keys/keys/{roomId} and imports the result
3. Marks the room as fully downloaded to avoid redundant backup fetches on repeat invites

This ensures the bundle contains a complete key set for all shared-history messages (closes matrix-rust-sdk #5111).

Key Source Files and Entry Points#

Related PRs: element-web #32621 (join error handling), #33171 (unknown identity dialog), matrix-js-sdk #5216 (history visibility gate), #5080 (late bundle arrival), #5171 (backup before bundle)