Module key_ops 

Device keys, to-device, cross-signing, and backup decisions. Signature checks that the protocol requires stay here. Transport does not.

Structs

BackupVersionCreateRequest

BackupVersionUpdateRequest

DeleteDevicesRequest

DeviceListDelta

The device_lists object of a sync window: mxids, sorted and de-duplicated.

DeviceSigningUploadRequest

KeysChangesQuery

KeysClaimRequest

KeysQueryRequest

What keys_upload’s blocking half hands back: the caller’s one-time-key counts, and the peers to wake when its device keys changed.

KeysUploadOutcome

KeysUploadRequest

PutDeviceRequest

SendToDeviceRequest

VersionQuery

Enums

DeviceKeysUploadAction

SendToDeviceOutcome

Constants

BACKUP_ALGORITHM

The one key-backup algorithm this server accepts (plan P9 brief, MSC3270 naming) — m.megolm_backup.v1.curve25519-aes-sha2 (the PkEncryption backup) is refused outright, never even reaching storage.

SEND_TO_DEVICE_MAX_CONTENT_BYTES

Per-target content-size cap (plan P9 brief: “≤ 64 KiB per content”).

SEND_TO_DEVICE_MAX_TARGETS

Per-request cap on PUT /sendToDevice’s flattened target-device count (plan P9 brief: “≤ 1 000 target devices”).

Functions

apply_device_signing_upload

DB-only core for POST /keys/device_signing/upload (plan P9 brief): validates each provided key object’s shape/ownership, verifies self_signing/user_signing against the master key (freshly uploaded in this SAME call, or the caller’s existing one), and stores whatever was provided. No UIA (single factor, matches every other route in this tree). Replacing an existing master key is allowed (user reset). Returns whether anything was actually written — the caller only wakes peers when it did.

apply_keys_upload

DB-only core for POST /keys/upload: ownership check on device_keys, then insert / no-op / authenticated identity reset (see decide_device_keys_upload), OTK-id validation, and storage. On DeviceKeysUploadAction::Reset old one-time and fallback keys for this device are wiped before the new identity is stored. Returns whether device_keys actually changed (the caller wakes peers when it did).

apply_send_to_device

DB-only core for PUT /sendToDevice/{eventType}/{txnId}: txn-deduped per (sender_user_id, sender_device_id, txn_id) — a repeat is a no-op — then expand_send_to_device_targets and one atomic dedup-checked enqueue (crate::keys::enqueue_to_device_deduped).

apply_signatures_upload

DB-only core for POST /keys/signatures/upload: per submitted (target_user, target_key_id) pair, checks signature_target_is_authorized and stores the whole submitted value opaquely on success (crate::keys::add_signatures), or files a per-entry M_INVALID_PARAM failure. Returns the failures map (empty on full success).

backup_sessions_to_response

Shape a batch of stored crate::keys::KeyBackupSession rows into the GET response’s three tiers.

backup_version_to_response

build_keys_changes_response

DB-only core for GET /keys/changes (plan §3.7 / P9 brief): the same device_lists delta /sync reports for (from, to] (device_list_delta) — device-list changes and newly shared encrypted rooms among users the caller can see (changed), and users who no longer share any room with the caller (left).

build_keys_claim_response

DB-only core for POST /keys/claim (plan P9 brief): per requested (mxid, device, algorithm), claims one OTK (or a reusable fallback) — restricted to the SAME share-a-room set as /keys/query — silently omitting any device that yields nothing (no such device, no keys left) or any user this caller may not see.

build_keys_claim_visible

build_keys_claim_response with an explicit visible-user set (federation).

build_keys_query_response

DB-only core for POST /keys/query (plan P9 brief): batch device_keys for every requested user this caller may see (self, or a shared-room peer — peers_sharing_a_room_with), plus master_keys/ self_signing_keys for the same allowed set, and user_signing_keys ONLY for the caller (spec: a user-signing key is never shared with anyone else). A requested user this caller may NOT see, or an mxid naming no known account, gets an empty device_keys entry ({}) rather than being omitted — the caller learns nothing about whether the account even exists.

build_keys_query_visible

build_keys_query_response with an explicit visible-user set; caller is None for a federation request (no user-signing key is returned).

canonical_json_without_signatures

Matrix canonical JSON (RFC 8259 subset: sorted keys, no insignificant whitespace) of value with signatures/unsigned stripped — the exact bytes a client signs when producing a cross-signing signature. serde_json::Value::Object is backed by a BTreeMap everywhere in this workspace (no preserve_order feature enabled anywhere in the dependency graph — Cargo.toml), so keys are already sorted at every nesting level, and its compact to_string emits no insignificant whitespace and leaves non-ASCII UTF-8 unescaped — together already exactly canonical JSON’s shape, with no extra re-serialization step needed beyond stripping the two keys.

check_device_keys_ownership

device_keys.user_id/device_id must name the authenticated caller (plan §2 manager decision 5 / P9 brief) — else M_INVALID_PARAM.

count_claim_targets

Total number of (mxid, device) pairs a /keys/claim request asks for — the cost charged against [crate::typing::ClaimRateLimiter] (plan P9 brief: “≤ 100 device claims / minute per caller”).

decide_device_keys_upload

Decide what a device_keys upload does for an already-authenticated device bearer. Compares only the keys object (curve25519/ed25519 identity), not algorithms/signatures.

device_list_delta

The device_lists delta of (from_exclusive, to_inclusive] as seen by caller_user_id — see DeviceListDelta. /sync (incremental) and GET /keys/changes both build their answer from this one function so the two can never disagree.

device_to_json

expand_send_to_device_targets

Resolve messages into a flat per-device list, expanding "*" to every current device of that recipient (an explicit device entry for the same recipient always overrides the wildcard’s content for that one device, never both delivered) and dropping — silently, per this module’s own documented policy (“no enumeration via to-device”) — any recipient who does not share a joined room with the sender and is not the sender themself. Enforces the per-content-size cap up front; the per-request device-count cap is enforced once, after expansion (a caller mistake, refused outright — unlike the stranger case, a cap violation is unambiguous and refusing it leaks nothing a working client didn’t already know about its own request).

master_key_names_local_id

Whether user_id’s master cross-signing key names local_id as one of its own ed25519:<local_id> entries — the user-signing case’s authorization check (plan P9 brief: “target must be … another user’s master key”).

master_verifying_key

Extract the single ed25519:<key_id> entry from a cross-signing key object’s keys map (Matrix’s cross-signing keys always carry exactly one) — (key_id, decoded 32-byte verifying key).

normalize_put_backup_body

Normalize the three PUT room_keys/keys[...] body shapes into a flat (room_id, session_id, session_data_json) list — session_data_json is the WHOLE submitted KeyBackupData object (opaque to this server, see crate::keys::key_backup_sessions.session_data’s own doc), not just its inner session_data field.

parse_required_version

peers_sharing_a_room_with

Every user id the caller may see key material for through this module’s share-a-room gate: user_id itself, plus every user who is JOINED or INVITED in a room the caller is JOINED to (plan P9 brief: /keys/query/ /keys/claim/PUT /sendToDevice “restrict to users who share a room with the caller, or the caller”; the invited half is P16 S-e — see this module’s own doc). The caller must be joined: a room where the caller is only invited, has left, or is banned contributes nothing. A target outside this set is dropped/emptied by the caller, never distinguished from “no such account”.

require_current_backup_version

?version= must name the caller’s CURRENT (non-deleted) backup version — plan P9 brief: “wrong/stale version → 403 M_WRONG_ROOM_KEYS_VERSION with current_version”. Applies uniformly to GET/PUT/DELETE room_keys/keys[...].

shared_room_transitions

Users who entered (entered) or stopped sharing (departed, before the still-shares-another-room exclusion the caller applies) an ENCRYPTED room with caller_user_id in (from_exclusive, to_inclusive]. Encrypted rooms only: the client tracks device lists for those alone, and a public unencrypted channel would otherwise list every one of its members whenever the caller joins it.

signature_target_is_authorized

Whether caller_mxid may file a signature against (target_user_id, target_key_id) (plan P9 brief: “the signer must be the caller; target must be the caller’s own device/keys or (for user-signing) another user’s master key”). This endpoint never verifies the signature bytes themselves — only this authorization shape — matching crate::keys::cross_signing_signatures’s own “opaque, never verified” contract (the one deliberate exception in this module is /keys/device_signing/upload’s master-key check, scoped to that endpoint alone — see this module’s own doc).

sorted_mxids

The mxids of user_ids, sorted and de-duplicated (a user with no mxid row cannot be named to a client and is dropped).

split_algorithm_key_id

algorithm:key_id — every one-time/fallback key’s own wire id (plan P9 brief: “OTK ids algorithm:key_id format validated”).

validate_backup_algorithm

Refuse anything but this server’s one symmetric key-backup algorithm (plan P9 brief, MSC3270 naming) — m.megolm_backup.v1.curve25519-aes-sha2 (the PkEncryption backup) is refused outright.

validate_cross_signing_key_object

user_id/usage shape validation shared by all three cross-signing key kinds (plan P9 brief).

verify_signed_by_master

Verify that target_key_object (a self_signing_key/user_signing_key upload) carries a valid ed25519 signature by master_key_object’s own key, filed under signatures[caller_mxid]["ed25519:<master_key_id>"] — Matrix’s own cross-signing trust chain (plan P9 brief: “verify with ed25519 over canonical JSON”).