async-matrix 4.0.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 294aac9f09e13800fd19f8bd62cc9290ac574ef9c44577b76c97a01c45f06384
-  data.tar.gz: 329a49b5d8cff3fd05493b49aed557863d13607c9cef11eb2dbbdf60aaf02bed
+  metadata.gz: dd82bb8b903732843ac2a6ddf292ff3d74a6c3e7680a61c0924ee51dd6c9ccea
+  data.tar.gz: 9b4c4a64624938601f9bd027fc015abbd556ffb6944e4ad69163e03a5f0012d9
 SHA512:
-  metadata.gz: 76ceb50e1bce05d67997cac434915dc3e5b1b70c083e4c8d8d7aed9520a71fc9b93f27e65715dd2178f99374911d7e9349b7b0c4ba35796faaf9f96b397788ac
-  data.tar.gz: 134172207429e74a48eb81531ea5c31d90b3a96e21551ab909209c073f4491dcba2f21a6beb09310434a65403f1c122b5941091d788dc0b9cb6110e4f9c66064
+  metadata.gz: 2ab96f1825dc29eff57ba0f15bcd15c22a1cb135175f8187e006521aaef2e34aee9212b6c822d075ea3e95de2af40306a017c014518d71ca27ddbdfc4fff7463
+  data.tar.gz: 21d0efab729f157698a1c614459c61d6323269dbd49be17982434498e1f7773790a5ee91714fd4ab26a62d2c69aae445ca24bb1ccaae658010836d1192a418d5

data/CHANGELOG.md

@@ -6,6 +6,30 @@ project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [4.0.1] - 2026-10-13
+
+### Added
+
+- **`E2EE::Machine#dump` and `E2EE::Machine.load`**, which carry the device a machine encrypts as
+  alongside its key material. `load` takes the `user_id` and `device_id` restoring the state and
+  raises `MismatchedAccountError` where they are not the ones which wrote it, so a device cannot
+  take on another's state. The implementation which wrote it is named by `crypto:`, since only the
+  caller knows which it encrypts with.
+
+- **`Async::Matrix::MismatchedAccountError`**, carrying `#expected` and `#got` as the user and
+  device each side names. This mirrors `CryptoStoreError::MismatchedAccount` in matrix-rust-sdk,
+  where building an `OlmMachine` over a store belonging to another device is an error rather than a
+  resumption.
+
+  A device's state is its own, and so is the sync cursor which acknowledges what it has read. A
+  client which resumes one device from another's state acknowledges to-device messages this device
+  never received, and a room key lost that way is lost for good — the messages it would have read
+  stay unreadable. Refusing to restore is what makes that unrepresentable.
+
+- **Cases for to-device delivery**, in `test/async/matrix/api/client_server/to_device.rb`: a
+  message is delivered to the device it was addressed to and not to the account's other device, and
+  it is delivered once, against the cursor of the device it was sent to.
+
 ## [4.0.0] - 2026-10-12
 
 ### Added
@@ -441,7 +465,8 @@ server-side API.
   Socketry ecosystem, with schema-driven event validation, an OpenAPI-backed
   client, media support, and mautrix-compatible configuration.
 
-[Unreleased]: https://github.com/general-intelligence-systems/async-matrix/compare/v4.0.0...HEAD
+[Unreleased]: https://github.com/general-intelligence-systems/async-matrix/compare/v4.0.1...HEAD
+[4.0.1]: https://github.com/general-intelligence-systems/async-matrix/releases/tag/v4.0.1
 [4.0.0]: https://github.com/general-intelligence-systems/async-matrix/releases/tag/v4.0.0
 [3.0.1]: https://github.com/general-intelligence-systems/async-matrix/releases/tag/v3.0.1
 [3.0.0]: https://github.com/general-intelligence-systems/async-matrix/releases/tag/v3.0.0

data/README.md

@@ -429,8 +429,9 @@ npm install
 npm run dev     # http://localhost:3000
 ```
 
-Its pages are MDX in `docs/content/docs`, written there rather than generated from this file and
-`guides/`, so a change to either has to be made in both places. See `docs/README.md`.
+Its pages are MDX in `docs/content/docs`, written there rather than generated from this file, so a
+change to either has to be made in both places. They are also where `context/` comes from, which
+`bin/update-context` generates: the agent context this gem ships. See `docs/README.md`.
 
 ## Testing
 

data/context/design.md

@@ -0,0 +1,26 @@
+<!-- Generated by bin/update-context from docs/content/docs. Do not edit: edit the pages there and re-run it. -->
+
+# Design
+
+The library follows the `async-rest` model: a `Async::Matrix::Client` is a *resource*, and every
+response is a *representation*.
+
+  - **Paths are absolute.** The client-server API is versioned per-endpoint (`/_matrix/client/v3`
+    for most endpoints, `/_matrix/client/v1` for some), so the client is rooted at the homeserver
+    and each method supplies an absolute path, which replaces rather than extends the resource path.
+
+  - **Errors are raised by the wrapper.** Matrix reports failures with a non-2xx status and an
+    `{errcode, error}` body. `async-rest`'s generated class methods do not check the status, so
+    `Async::Matrix::Wrapper` inspects it and raises `Async::Matrix::RequestError`.
+
+  - **Rate limiting is retried.** Matrix reports `M_LIMIT_EXCEEDED` with `retry_after_ms` in the
+    *body*, where `async-rest` only understands the `retry-after` header. The wrapper handles both,
+    and surfaces the error rather than waiting when the delay exceeds
+    `Wrapper::MAXIMUM_RETRY_DELAY`.
+
+  - **A room is a resource with no representation.** There is no `GET /rooms/{roomId}`, so
+    `Async::Matrix::Room` is a navigator onto a room's state, members and timeline, carrying the
+    room ID alongside its resource.
+
+  - **Representations are lazy.** `client.get_joined_rooms` issues no request until something reads its
+    value, and a room enumerated from a collection carries its ID without a further request.

data/context/getting-started.md

@@ -0,0 +1,122 @@
+<!-- Generated by bin/update-context from docs/content/docs. Do not edit: edit the pages there and re-run it. -->
+
+# Getting Started
+
+This guide explains how to use the `async-matrix` gem to talk to a Matrix homeserver.
+
+## Installation
+
+Add the gem to your project:
+
+```shell
+$ bundle add async-matrix
+```
+
+## Core Concepts
+
+- A `Async::Matrix::Client` is an `Async::REST::Resource` rooted at a homeserver. An
+  unauthenticated client can read `/versions` and log in; `Async::Matrix::Client#authenticated`
+  derives a client which carries an access token.
+- A `Async::Matrix::Room` is a navigator onto one room. It is not a representation, because the
+  client-server API has no `GET /rooms/{roomId}`: a room is only ever observed through its state,
+  members or timeline.
+- Everything a request returns is a `Async::Matrix::Representation`: `Async::Matrix::State`,
+  `Async::Matrix::Messages`, `Async::Matrix::Sync` and so on.
+
+## Logging In
+
+```ruby
+require "async/matrix"
+
+Async::Matrix::Client.open("http://localhost:7300") do |unauthenticated|
+  client = unauthenticated.logged_in("alice", "password")
+
+  puts client.get_token_owner.user_id
+  # @alice:localhost
+end
+```
+
+If you already hold an access token, skip the login:
+
+```ruby
+client = unauthenticated.authenticated(ENV["MATRIX_ACCESS_TOKEN"])
+```
+
+## Rooms
+
+```ruby
+room = client.create_room(name: "Planning", topic: "Sprint planning")
+
+room.send_message("Hello, World!")
+
+puts room.state.name
+# Planning
+puts room.joined_members.user_ids
+# ["@alice:localhost"]
+```
+
+Nothing is fetched until it is read, so listing rooms is cheap, and each room enumerated from the
+list already knows its own ID:
+
+```ruby
+client.get_joined_rooms.each do |room|
+  puts room.id
+end
+```
+
+A timeline is paged with opaque tokens. `Async::Matrix::Messages#following` continues from
+where the previous page ended, and returns `nil` at the end:
+
+```ruby
+page = room.get_room_events(dir: "b", limit: 20)
+
+while page
+  page.each do |event|
+    puts event.dig(:content, :body)
+  end
+
+  page = page.following
+end
+```
+
+## Sync
+
+`/sync` is a long poll: the server holds the request open until something happens, or until the
+timeout expires. Each batch carries the token the next one should continue from, so a sync loop is a
+chain of `Async::Matrix::Sync#following` calls.
+
+```ruby
+# The initial sync reports all current state. Use `timeout: 0` for it, and treat it as a cursor:
+sync = client.sync(timeout: 0)
+
+while true
+  sync = sync.following(timeout: 30_000)
+
+  sync.each_message do |room_id, sender, body, event|
+    puts "#{room_id} #{sender}: #{body}"
+  end
+end
+```
+
+Note that the room IDs in a parsed payload are symbols, because the JSON parser symbolizes names.
+`Async::Matrix::Sync#each_event` and `Async::Matrix::Sync#each_message` convert them back
+to strings for you; `Async::Matrix::Sync#joined` does not.
+
+## Errors and Rate Limiting
+
+A failed request raises `Async::Matrix::RequestError`, which carries the HTTP status and the
+Matrix `errcode`:
+
+```ruby
+begin
+  client.join("#nonexistent:localhost")
+rescue Async::Matrix::RequestError => error
+  puts error.status  # 404
+  puts error.errcode # M_NOT_FOUND
+end
+```
+
+A rate limited request is retried automatically, for as long as the server asks for a delay within
+`Async::Matrix::Wrapper::MAXIMUM_RETRY_DELAY`. A longer delay is raised as an error instead, so that
+a task is never silently blocked for minutes: Synapse answers a login burst with a penalty of around
+five minutes, and you almost certainly want to know rather than wait.

data/context/index.yaml

@@ -0,0 +1,25 @@
+# Generated by bin/update-context from docs/content/docs. Do not edit: edit the pages there and re-run it.
+---
+description: An asynchronous Ruby library for the Matrix protocol.
+metadata:
+  source_code_uri: https://github.com/general-intelligence-systems/async-matrix
+  documentation_uri: https://general-intelligence-systems.github.io/async-matrix/
+files:
+- path: overview.md
+  title: Overview
+  description: A Ruby client for the Matrix client-server API, built on async-rest.
+- path: getting-started.md
+  title: Getting Started
+  description: Install the gem, log in, work with rooms, and run a sync loop.
+- path: design.md
+  title: Design
+  description: Resources, representations, errors and laziness — why the client looks
+    the way it does.
+- path: server-server.md
+  title: Server-server API
+  description: Federation — signed requests, membership templates, and the keys a
+    server publishes.
+- path: testing.md
+  title: Testing
+  description: Running the suite against a real homeserver, on either backend, and
+    linting.

data/context/overview.md

@@ -0,0 +1,46 @@
+<!-- Generated by bin/update-context from docs/content/docs. Do not edit: edit the pages there and re-run it. -->
+
+# Overview
+
+`async-matrix` is a client for the [Matrix](https://matrix.org) client-server API, built on
+[async-rest](https://github.com/socketry/async-rest).
+
+The scope is rooms and sync: logging in, enumerating and creating rooms, reading room state and
+members, sending events, paging through a timeline, and running a sync loop.
+
+## Usage
+
+```ruby
+require "async/matrix"
+
+Async::Matrix::Client.open("http://localhost:7300") do |unauthenticated|
+  client = unauthenticated.logged_in("alice", "password")
+
+  room = client.create_room(name: "Hello", topic: "Built with async-rest")
+  room.send_message("Hello, World!")
+
+  client.get_joined_rooms.each do |room|
+    puts "#{room.id}: #{room.state.name}"
+  end
+
+  # Sync is a long poll: each batch continues from the one before it.
+  sync = client.sync(timeout: 0)
+
+  while true
+    sync = sync.following(timeout: 30_000)
+
+    sync.each_message do |room_id, sender, body, event|
+      puts "#{room_id} #{sender}: #{body}"
+    end
+  end
+end
+```
+
+See `examples/echo.rb` for a bot which joins rooms it is invited to and replies to every message.
+
+## Where to go next
+
+- [Getting Started](getting-started.md) — Install the gem, log in, send a message, and run a sync loop.
+- [Design](design.md) — Why the client looks the way it does: resources, representations, and errors.
+- [Testing](testing.md) — Run the suite against a real homeserver, on either backend.
+- [Matrix Specification](https://spec.matrix.org) — The specification the client implements.

data/context/server-server.md

@@ -0,0 +1,79 @@
+<!-- Generated by bin/update-context from docs/content/docs. Do not edit: edit the pages there and re-run it. -->
+
+# Server-server API
+
+`Async::Matrix::ServerServer::Server` is the federation client: a resource rooted at another
+homeserver, with a navigator per concept the specification names and a representation per answer.
+
+```ruby
+require "async/matrix"
+
+key = Async::Matrix::ServerKey.load("/etc/synapse/signing.key")
+
+Async::Matrix::ServerServer::Server.open("https://matrix.example.com") do |unsigned|
+  server = unsigned.signed_as("example.com", key, "matrix.example.com")
+
+  puts unsigned.server_version.get_version.name
+  puts server.query.query_profile("@alice:matrix.example.com").displayname
+
+  # A join is a template to sign and send back:
+  template = server.joins_v1.make_join(room_id, "@bob:example.com", versions: ["11"])
+end
+```
+
+## Signing
+
+There is no access token. A server proves who it is by signing the request, so
+`Async::Matrix::Middleware::Signed` sits below the resource and signs the method, the path, the
+origin, the destination and the body as a document. The signature is over the canonical form rather
+than over the bytes, so it cannot depend on how the sender wrote them.
+
+`Async::Matrix::ServerKey` reads the one line a homeserver keeps its ed25519 key in, and is what
+the other side fetches from `/_matrix/key/v2/server` to check a signature against.
+
+Some endpoints are not signed at all. The version, the keys, the discovery document and the OpenID
+exchange are read before there is anything to sign with, so they are asked for through the unsigned
+resource.
+
+## Answers which are not JSON
+
+`/media/download` answers `multipart/mixed`: a document describing the file, and then the file, or
+a `Location` pointing at it. `Async::Matrix::Wrapper::Multipart` reads both, so
+`Async::Matrix::ServerServer::FederatedContent` has bytes and a description rather than a body to
+parse.
+
+The first versions of `send_join` and `send_invite` answered `[200, {...}]` — a status beside the
+body — which the second versions replaced with the body alone. Those representations read either
+shape.
+
+## Events
+
+Since room version 3 an event ID is the hash of its redacted form rather than a field it carries,
+so a representation reads events by type rather than looking one up by ID.
+
+A join, a leave and a knock are all built by the server which has the room: it answers a
+`MembershipTemplate` for the asking server to hash, sign and send back, because only it knows the
+state the event should point at.
+
+## Withdrawals
+
+v1.18 dropped the first versions of `send_join` and `send_leave`, so those layers register the
+withdrawal and the methods say what replaced them:
+
+```ruby
+Async::Matrix::ServerServer::Server["v1.19"].open(url) do |server|
+  server.joins_v1.send_join_v1(room_id, event_id, event)
+  # => Async::Matrix::RemovedOperationError: #send_join_v1 was removed in v1.18: call #send_join_v2 instead!
+end
+```
+
+## Testing it
+
+The suite signs as the homeserver it is testing, using the key checked into `synapse/`: a
+homeserver verifies a signature made by its own server name against the key it already holds rather
+than fetching one, so every authenticated endpoint is reachable from a single server. There is no
+other way to do it — a server name invented by the suite would have no keys for anybody to fetch.
+
+```shell
+bin/test --keep-alive --api server-server
+```

data/context/testing.md

@@ -0,0 +1,49 @@
+<!-- Generated by bin/update-context from docs/content/docs. Do not edit: edit the pages there and re-run it. -->
+
+# Testing
+
+The tests run against a real homeserver, and against more than one of them. There is a rig per
+backend, each a directory with a flake which publishes one image per Matrix specification version
+and a compose file with a service per version, so that a run is just the version wanted:
+
+```shell
+bin/test                      # the latest version, on Synapse
+bin/test --all                # every version
+bin/test v1.11 v1.12          # just these
+bin/test --backend tuwunel    # on tuwunel instead
+bin/test --keep-alive         # and leave the homeserver running afterwards
+```
+
+`synapse/` is the first rig, and pins each specification version to the Synapse which first
+advertised it, which is the oldest server that version can be tested against. `tuwunel/` is the
+second, and pins every version to the same tuwunel release: one tuwunel build advertises the whole
+range, and its advertised list records the order it did the work in rather than when support
+arrived, so the first release to advertise v1.5 predates most of its development.
+
+A second backend is the point rather than a bonus. A suite which only ever talks to Synapse tests
+what Synapse does, not what the specification says, so where a version passes on one server and
+fails on the other, either one of them is wrong or the specification is read two ways.
+
+Each test gets a fresh user and a fresh room, so tests cannot interfere with each other and the
+suite can be run repeatedly. The one thing the rigs cannot do alike is make that user: Synapse
+carries a module which registers it on first login, where tuwunel has no way to accept any
+password, so its rig opens registration and the suite registers the account before logging in.
+`bin/test` tells the suite which it is talking to.
+
+Set `MATRIX_HOMESERVER` to test against a server of your own — but note that one with default rate
+limits will fail the suite, because Synapse allows a burst of 10 room creations and then one per
+~62 seconds, and a burst of 5 logins and then one per ~5 minutes.
+
+The images come from the Build Test Images workflows, which is also what a new version needs run
+after it is added: a job pulls `ghcr.io/<owner>/<backend>:spec-<version>`, so without it there is
+nothing to start.
+
+### Linting
+
+```shell
+bin/rubocop
+```
+
+The cops in `cops/` read files with Prism through `ast-crispr-ruby-prism`, which requires Ruby 4,
+so they are in a `lint` bundler group of their own. The suite itself runs on Ruby 3.3 and up, and
+the Test workflows install without that group.

data/lib/async/matrix/abstract/api/push_gateway/push_notifier.rb

@@ -33,8 +33,12 @@ module Async
           module V1_14
           end
 
-          # No changes in v1.13.
+          # v1.13 added a format to a device's data.
           module V1_13
+            # @returns [Boolean] whether the field is accepted.
+            def device_data_accepts_format?
+              true
+            end
           end
 
           # No changes in v1.12.
@@ -81,8 +85,12 @@ module Async
           module V1_2
           end
 
-          # No changes in v1.1.
+          # v1.1 has the notification, with no format.
           module V1_1
+            # @returns [Boolean] whether the field is accepted.
+            def device_data_accepts_format?
+              false
+            end
           end
         end
       end

data/lib/async/matrix/e2ee/backup.rb

@@ -160,8 +160,6 @@ module Async
 
         # The code over the ciphertext authenticates nothing, which is libolm's bug and the specification's warning.
         #
-        # So a message which fails it was written to another key, rather than tampered with. See MSC4048 for the version which fixes it.
-        #
         # @parameter session_data [Hash] the three parts the server holds.
         # @returns [String | nil] the plaintext, or nil when this is not the key it was written to.
         def opened(session_data)
@@ -171,6 +169,7 @@ module Async
             self.class.unpadded(session_data[:ephemeral]),
           )
         rescue RuntimeError
+          # A message which fails the code was written to another key, rather than tampered with. See MSC4048 for the version which fixes it.
           nil
         end
       end

data/lib/async/matrix/e2ee/cross_signing.rb

@@ -11,9 +11,9 @@ module Async
   module Matrix
     module E2EE
       # The three keys which make a user's identity, so that verifying a person once covers every device they have.
-      #
-      # The master key is the identity, the self signing key signs their own devices, and the user signing key signs other people's master keys.
       class CrossSigning
+        # The master key is the identity, the self signing key signs their own devices, and the user signing key signs other people's master keys.
+        #
         # What each key is for, which the server and every other client reads it by.
         USAGE = {master: "master", self_signing: "self_signing", user_signing: "user_signing"}.freeze
 

data/lib/async/matrix/e2ee/devices.rb

@@ -194,8 +194,6 @@ module Async
 
         # Whether this device carries a signature by its owner's self signing key.
         #
-        # The signature is checked where there is something to check it with, because its presence alone says only that somebody wrote one.
-        #
         # @parameter user_id [String] the user.
         # @parameter value [Hash] the device keys the homeserver answered with.
         # @returns [Boolean] whether it is cross signed.
@@ -203,6 +201,7 @@ module Async
           signing = @identities.dig(user_id, :self_signing)
           signature = value.dig(:signatures, user_id.to_sym, :"ed25519:#{signing}")
 
+          # The signature is checked where there is something to check it with, because its presence alone says only that somebody wrote one.
           case {signing: signing, signature: signature, crypto: @crypto}
           in {signing: String, signature: String => claimed, crypto: Crypto => crypto}
             crypto.verify(value.reject{|name, _| name == :signatures}, key: signing, signature: claimed)

data/lib/async/matrix/e2ee/machine.rb

@@ -6,6 +6,7 @@
 require "console"
 require "json"
 
+require_relative "../error"
 require_relative "../events"
 require_relative "backup"
 require_relative "canonical_json"
@@ -37,6 +38,13 @@ module Async
         # The history visibilities which let a session be passed on to a later member.
         SHAREABLE = ["shared", "world_readable"].freeze
 
+        # Which part of the identity each of the three cross signing secrets carries.
+        CROSS_SIGNING = {
+          "m.cross_signing.master" => :master,
+          "m.cross_signing.self_signing" => :self_signing,
+          "m.cross_signing.user_signing" => :user_signing,
+        }.freeze
+
         # @parameter user_id [String] the user this device belongs to.
         # @parameter device_id [String] this device.
         # @parameter crypto [Crypto] the implementation to encrypt with.
@@ -64,6 +72,45 @@ module Async
           @released = []
         end
 
+        # The state this device holds, which is written for this device and no other.
+        #
+        # @parameter pickle_key [String] a 32 byte key.
+        # @returns [String] the state.
+        def dump(pickle_key)
+          ::JSON.dump(
+            user_id: @user_id,
+            device_id: @device_id,
+            crypto: @crypto.dump(pickle_key),
+          )
+        end
+
+        # Restore a device from what it wrote, which must be the device asking.
+        #
+        # @parameter dumped [String] what {#dump} wrote.
+        # @parameter pickle_key [String] the 32 byte key it was written with.
+        # @parameter user_id [String] the user restoring it.
+        # @parameter device_id [String] the device restoring it.
+        # @parameter crypto [Class] the implementation which wrote it, since only the caller knows which it encrypts with.
+        # @parameter options [Hash] what else to build it with, as the constructor takes.
+        # @returns [Machine] that device.
+        # @raises [MismatchedAccountError] if the state belongs to another user or device.
+        def self.load(dumped, pickle_key, user_id:, device_id:, crypto:, **options)
+          value = ::JSON.parse(dumped, symbolize_names: true)
+          written = [value[:user_id], value[:device_id]]
+
+          # A device which took on another's state would acknowledge what it never read, so this is refused rather than resumed.
+          unless written == [user_id, device_id]
+            raise MismatchedAccountError.new(written, [user_id, device_id])
+          end
+
+          self.new(
+            user_id: user_id,
+            device_id: device_id,
+            crypto: crypto.load(value[:crypto], pickle_key),
+            **options,
+          )
+        end
+
         # @attribute [String] the user this device encrypts as.
         attr :user_id
 
@@ -138,19 +185,19 @@ module Async
         # @parameter secret [String] the private key, base64 encoded.
         # @returns [CrossSigning | nil] our identity, or nil where the name is not one of the three.
         def accept_cross_signing_secret(name, secret)
-          case name.to_s
-          in "m.cross_signing.master" then @identity[:master] = CrossSigning::Key.from_base64(secret)
-          in "m.cross_signing.self_signing" then @identity[:self_signing] = CrossSigning::Key.from_base64(secret)
-          in "m.cross_signing.user_signing" then @identity[:user_signing] = CrossSigning::Key.from_base64(secret)
-          else
+          part = CROSS_SIGNING[name.to_s]
+
+          if part.nil?
             Console.warn(self, "That is not a cross signing key.", name: name)
 
-            return nil
-          end
+            nil
+          else
+            @identity[part] = CrossSigning::Key.from_base64(secret)
 
-          Console.info(self, "Took on a cross signing key.", name: name)
+            Console.info(self, "Took on a cross signing key.", name: name)
 
-          @identity
+            @identity
+          end
         end
 
         # Sign this device with our own self signing key, which is what makes it cross signed.
@@ -236,8 +283,6 @@ module Async
 
         # One session, as a backup wants it.
         #
-        # A restored session carries no signature, so what it claims about its sender is only as good as whoever put it there: that is why `is_verified` is what the sender's device was, not what the backup says.
-        #
         # @parameter session [Hash] the session, as {#sessions} answers it.
         # @returns [Hash] the fields a backup is written from.
         def export_for_backup(session)
@@ -256,6 +301,7 @@ module Async
             shared_history: session[:shared_history] || false,
             first_message_index: index,
             forwarded_count: (session[:forwarding_curve25519_key_chain] || []).size,
+            # A restored session carries no signature, so what it claims about its sender is only as good as whoever put it there: this is what the sender's device was, not what the backup says.
             is_verified: @devices.verified?(session[:sender], session[:device_id].to_s),
           }
         end
@@ -360,20 +406,18 @@ module Async
 
         # Whether a session for this room may be given to somebody who joins later.
         #
-        # True only while the history is visible to them, which is what the flag on a shared key reports.
-        #
         # @parameter room_id [String] the room.
         # @returns [Boolean] whether the history is shared.
         def shared_history?(room_id)
+          # True only while the history is visible to them, which is what the flag on a shared key reports.
           SHAREABLE.include?(@rooms.dig(room_id, :visibility))
         end
 
         # The rooms whose session has been used for too long, or for too many messages.
         #
-        # Neither is an event, so neither can be noticed by reading one: they are measured here instead.
-        #
         # @returns [Hash] why each room is due, by room ID.
         def rooms_due_for_rotation
+          # Neither is an event, so neither can be noticed by reading one: they are measured here instead.
           @rooms.each_with_object({}) do |(room_id, room), due|
             session = @crypto.session_for(room_id)
 
@@ -677,17 +721,34 @@ module Async
           case session
           in nil
             nil
-          in {message_index: Integer => index} if index >= room.fetch(:messages, DEFAULT_MESSAGES)
-            "it has carried #{index} messages"
+          in {message_index: Integer => index}
+            if index >= room.fetch(:messages, DEFAULT_MESSAGES)
+              "it has carried #{index} messages"
+            else
+              self.expired(room_id, room)
+            end
           else
-            started = @store.started(room_id)
+            self.expired(room_id, room)
+          end
+        end
+
+        # Why the room's session is too old to go on using, if it is.
+        #
+        # @parameter room_id [String] the room.
+        # @parameter room [Hash] what its state said.
+        # @returns [String | nil] the reason, or nil while it may still be used.
+        def expired(room_id, room)
+          started = @store.started(room_id)
 
-            case started
-            in Time => at if (Time.now - at) * 1000 >= room.fetch(:period, DEFAULT_PERIOD)
+          case started
+          in Time => at
+            if (Time.now - at) * 1000 >= room.fetch(:period, DEFAULT_PERIOD)
               "it has been in use since #{at}"
             else
               nil
             end
+          else
+            nil
           end
         end