Implement to_device routing to appservices (complete sender.rs TODO)

[mangas]

Tracking issue for finishing the appservice transaction sender so it delivers to_device events to appservices.

Symptom

mautrix bridges (signal, whatsapp, telegram — v0.2604.0, bridgev2 framework) configured with mandatory end-to-bridge encryption fail to decrypt any messages they receive. The bridges request the megolm session keys via m.room_key_request to-device events, the homeserver accepts the request (HTTP 200), but the response from the user's device never reaches the bridge. After a 22-second timeout the bridge posts the standard ⚠️ Your message was not bridged: the bridge hasn't received the decryption keys notice into the portal room.

This affects every mautrix bridge run with encryption.require: true, on every modern Matrix client.

Root cause

In src/service/sending/sender.rs (current main, line 829-830):

.send_request(appservice, ruma::api::appservice::event::push_events::v1::Request {
    txn_id: txn_id.into(),
    events: pdu_jsons,
    ephemeral: edu_jsons,
    to_device: Vec::new(), // TODO
})

Tuwunel hardcodes the to_device slice of every appservice transaction to an empty vec. This means the homeserver never delivers to_device events (including megolm session-key shares) to AS-namespaced devices, even when the appservice has device_management: true in its registration (MSC4190) and the bridge has uploaded device keys for its bot user.

git blame puts the TODO in commit da92b97 (2026-03-23). It was left explicitly as a TODO during a recent refactor of the AS sender; there is no architectural blocker discussed anywhere in the tracker.

Upstream context

• Upstream repo: https://github.com/matrix-construct/tuwunel
• Upstream issue (mautrix) bridges fail to upload device keys via MSC4190, possibly due to incomplete MSC3202/MSC4190 support matrix-construct/tuwunel#327 — (mautrix) bridges fail to upload device keys via MSC4190. Closed after a UIAA-bypass fix for the device-key replacement endpoint. Resolves the AS-callable half of MSC4190 (the AS can upload keys / replace cross-signing keys). Does NOT touch the routing path.
• Upstream issue Appservices with receive_ephemeral should receive EDUs via namespaces matrix-construct/tuwunel#382 + PR Route ephemeral events to appservices with receive_ephemeral matrix-construct/tuwunel#406 — Route ephemeral events to appservices with receive_ephemeral. Merged 2026-04-27. Adds m.typing and m.receipt routing to AS via the ephemeral slot of the transaction. Sets the pattern for the same shape of fix on to_device. Previously reverted once (deadlock); the deadlock context is worth reading before redoing the same pattern.
• Upstream issue Appservice E2EE (MSC3202) not supported: missing device_id in /whoami response causing bot crash matrix-construct/tuwunel#401 — Appservice E2EE (MSC3202) not supported: missing device_id in /whoami response. Closed with a fix that lets bridges register their own devices via MSC4190. Brings AS-callable MSC3202/MSC4190 endpoints up to spec. Does NOT touch the to-device delivery path.
• Combined effect: Tuwunel ships the half where an AS can claim a device and upload keys (device_management = true); it does not yet ship the half where the homeserver routes inbound to_device events back to that device through AS transactions. That second half is what this issue tracks.

Symmetry

device_management is currently honored at five AS-callable endpoints (api/client/device.rs, api/client/register.rs, api/client/keys/upload_signing_keys.rs). The sender does not reference it — it just always sends to_device: []. The natural gate for the routing path is the same flag.

The existing ephemeral path at sender.rs:802 is the right shape to mirror:

if appservice.receive_ephemeral { /* gather edu_jsons */ }

The matching to_device block would be:

if appservice.registration.device_management {
    /* gather to_device events targeted at users in this AS's namespace,
       since this AS's to_device cursor */
}

Implementation sketch

1. Cursor per AS — analogous to max_edu_count at sender.rs:399, add a max_to_device_count (or similar) advanced as AS transactions are acknowledged. Stored in the same place as the existing AS cursors.
2. Gather — at the appservice transaction build site, for AS-es with registration.device_management set, scan the to-device queue for events whose recipient matches the AS's user namespace, since the cursor. Tuwunel already persists to-device events when AS users call PUT /_matrix/client/v3/sendToDevice/... (the inbound side works), so the storage exists; this is read-side only.
3. Populate the to_device: field on the appservice push_events::v1::Request.
4. Advance the cursor only after the transaction is acked by the AS, to avoid lost events on retries; same pattern as PDU/EDU.

Concurrency hazards to revisit before merging:

• PR Route ephemeral events to appservices with receive_ephemeral matrix-construct/tuwunel#406 (ephemeral routing) was reverted once for deadlocks before being re-landed. Read the revert + re-land thread first.
• Cursor advancement under retry must be idempotent; don't drop events if the AS 5xx's and we retry.
• Watch for batching: large device-key migrations (e.g. cross-signing reset on a multi-room user) can spike to-device volume per AS.

Spec references

• MSC3202 — encrypted appservices: MSC3202: Encrypted appservices matrix-org/matrix-spec-proposals#3202
• MSC4190 — appservice device management: MSC4190: Device management for application services matrix-org/matrix-spec-proposals#4190
• MSC2409 — appservice EDU/to-device delivery: MSC2409: Proposal to send typing, presence and receipts to appservices  matrix-org/matrix-spec-proposals#2409
• ruma already exposes to_device: Vec<Raw<AnyToDeviceEvent>> on appservice::event::push_events::v1::Request, so the wire format is done.

Plan

• Implement against main, mirror PR Route ephemeral events to appservices with receive_ephemeral matrix-construct/tuwunel#406's pattern, gate on registration.device_management.
• Test with a mautrix bridge (signal, whatsapp, or telegram on v0.2604.0+) configured for encryption.require: true.
• Submit upstream once verified working against the local fork.

[mangas]

Local testing strategy

Three layers, choose depth based on confidence needed.

1. Complement conformance suite

Tuwunel ships docker/Dockerfile.complement and docker/complement.sh for running the Matrix Complement test suite against a locally-built Tuwunel binary. Existing Complement tests cover the appservice transaction shape and EDU routing; rerunning them gates against regressions in the PDU/ephemeral/to_device payload assembly.

Adding a new Complement test that:

• registers an AS with device_management: true
• has a regular user send a to-device event to an AS-namespaced user
• asserts the AS receives a transaction with that event in the to_device slot

…gives upstream a tangible artifact for review and a regression gate going forward. Worth committing alongside the implementation in the same PR.

2. Minimal fake-AS harness via docker-compose (primary local test)

Spin up only:

• Tuwunel (patched build) in a container
• A tiny HTTP server that registers itself as an appservice with device_management: true. It accepts PUT /_matrix/app/v1/transactions/:txnId, dumps the request body to stdout, returns 200.

Then in the test:

• Register a regular user, say @alice:localhost
• Have alice PUT /_matrix/client/v3/sendToDevice/m.room_key/<txn> targeting a device on an AS-namespaced user like @bot:localhost
• Watch the fake-AS stdout for the next transaction. With the fix, the body should contain a to_device array with alice's event. Without the fix, to_device: [].

This is the most surgical evidence path — no client-side crypto, no real bridge, no MSC4190/MSC3202 device-key dance required. ~50 lines for the fake AS, useful as a reusable harness. Fits in test/fake-as/ alongside a docker-compose. Iteration loop is ~30 seconds per test run.

3. Real bridge integration (highest realism)

A full docker-compose with Tuwunel + Postgres + one mautrix bridge (mautrix-signal is simplest — no third-party API credentials needed). Two test Matrix accounts via a browser client, pair the bridge, send an encrypted message in the management room, watch the bridge's decrypt loop succeed or fail.

This is the closest end-to-end test, but slow to iterate and needs more moving parts. Use it as a final integration gate before sending the PR upstream, not for development iteration.

Recommendation

• (2) is the primary development loop — fast, direct, no client crypto required to demonstrate the wire-level routing change is correct.
• (1) provides the upstream-facing artifact (Complement regression test) and should land in the PR.
• (3) is the final smoke test before submitting upstream.