async-matrix 3.0.0-x86_64-linux → 3.0.1-x86_64-linux

data/lib/async/matrix/device_store.rb

@@ -0,0 +1,1621 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "digest"
+
+require_relative "../../protocol/matrix/encrypted_message"
+require_relative "../../protocol/matrix/keys"
+
+module Async
+  module Matrix
+    # One device's key material, and the ability to read anything it holds a key
+    # for.
+    #
+    # A CLIENT CLASS, NOT A PROTOCOL ONE. Protocol::Matrix owns formats and the
+    # rules for reading them, and holds no state and no key material. This holds
+    # both: a live Olm account, the ratchets, and every room key the device has
+    # accumulated. It is also where the native crypto primitives are injected,
+    # which the format layer must never name.
+    #
+    # This is what you hand to a sync client. It owns the Olm account, the 1:1
+    # sessions with other devices, and every Megolm room key the device has been
+    # given — so it can decrypt a message from ANY room, because a room key is
+    # just an entry in here.
+    #
+    #   store = DeviceStore.new(
+    #     user_id: "@bot:example.org", device_id: "ABCDEFGHIJ",
+    #     account: account, e2ee: Async::Matrix::E2EE,
+    #   )
+    #
+    #   store.decrypt(message)   # => message if it could be read, nil if not
+    #
+    # IT ACCUMULATES AS IT READS. Decrypting an Olm to-device message routinely
+    # yields an `m.room_key`, and the store absorbs it on the spot. That is what
+    # makes a sync loop work with no orchestration above it: feed the batch
+    # through in order and the keys arriving early in it unlock the messages
+    # later in it.
+    #
+    # NO PERSISTENCE, BY CONSTRUCTION. The primitives are handed in, already
+    # unpickled, and every ratchet step is reported through #changes for the
+    # caller to write wherever it likes. This class never sees a database, and
+    # it holds no opinion about where its keys came from — which is also why it
+    # can be driven in a test with three fake objects and no cryptography.
+    #
+    # THE PRIMITIVES ARE INJECTED. `account` is duck-typed, and `e2ee` is
+    # whatever module provides InboundGroupSession. The protocol layer therefore
+    # names no native extension and keeps its dependency list empty; the caller
+    # decides which implementation backs it.
+    class DeviceStore
+      class Error < Protocol::Matrix::Error; end
+
+      # The same message, delivered twice, with a different event id.
+      class ReplayError < Error; end
+
+      # A key issued for one room used against a message in another. Refused
+      # rather than decrypted: a sender who can place a message in a room they
+      # hold no key for could otherwise have it attributed to a room they do.
+      class RoomMismatchError < Error; end
+
+      # The store was asked to absorb a room key it cannot build, because no
+      # primitive factory was supplied.
+      class MissingPrimitivesError < Error; end
+
+      # Rotation is a security property, not housekeeping: everyone holding the
+      # current key can read everything encrypted with it, so a session must not
+      # live forever. These are the spec defaults for m.room.encryption when the
+      # room does not override them.
+      DEFAULT_ROTATION_MESSAGES = 100
+      DEFAULT_ROTATION_MS = 7 * 24 * 60 * 60 * 1000
+
+      ROOM_KEY = "m.room_key"
+      FORWARDED_ROOM_KEY = "m.forwarded_room_key"
+      MEGOLM = Protocol::Matrix::EncryptedMessage::MEGOLM
+
+      # @parameter account [Object] an unpickled Olm account, answering
+      #   #curve25519_key, #ed25519_key, #sign and #create_inbound_session.
+      # @parameter e2ee [Module] supplies InboundGroupSession, used to build a
+      #   session from a received room key. Optional: a store that only ever
+      #   reads keys handed to it directly does not need one.
+      # @parameter olm_sessions [Hash] sender_key => [session, ...], most
+      #   recently used first.
+      # @parameter group_sessions [Hash] session_id => {session:, room_id:}.
+      def initialize(user_id:, device_id:, account:, e2ee: nil, olm_sessions: {}, group_sessions: {})
+        @user_id = user_id
+        @device_id = device_id
+        @account = account
+        @e2ee = e2ee
+        @olm_sessions = olm_sessions
+        @group_sessions = group_sessions
+
+        @outbound_sessions = {}
+        @message_indexes = {}
+        @olm_hashes = {}
+
+        @changed_olm_sessions = []
+        @changed_group_sessions = []
+        @changed_outbound_rooms = []
+        @account_changed = false
+      end
+
+      attr_reader :user_id, :device_id, :account
+
+      # Our own curve25519 identity key: what other devices encrypt Olm messages
+      # to, and the key an Olm ciphertext map is addressed under.
+      def identity_key = @account.curve25519_key
+
+      # Our own ed25519 key: what our signatures are verified against.
+      def fingerprint = @account.ed25519_key
+
+      # ── Publishing ──────────────────────────────────────────────────────────
+      #
+      # Until these are uploaded the device is unreachable: no peer can claim a
+      # one-time key, so none can open an Olm session, so none can send us a
+      # room key -- and every message in an encrypted room stays ciphertext
+      # forever. Publication is not an optimisation; it is the precondition for
+      # receiving anything at all.
+
+      # This device's signed identity document, for POST /keys/upload.
+      def device_keys
+        Protocol::Matrix::Keys.device_keys(
+          user_id:    @user_id,
+          device_id:  @device_id,
+          curve25519: identity_key,
+          ed25519:    fingerprint,
+          signer:     @account,
+        )
+      end
+
+      # Generate +count+ one-time keys and return them signed, ready to upload.
+      #
+      # NOT MARKED PUBLISHED HERE. The account only forgets a key once
+      # #mark_keys_published! is called, and calling that before the upload
+      # succeeds would discard keys the server never received -- which looks,
+      # later, exactly like a peer claiming a key we have no record of.
+      def generate_one_time_keys(count = default_one_time_key_count)
+        @account.generate_one_time_keys(count)
+        @account_changed = true
+
+        Protocol::Matrix::Keys.one_time_keys(
+          @account.one_time_keys,
+          user_id:   @user_id,
+          device_id: @device_id,
+          signer:    @account,
+        )
+      end
+
+      # The fallback key, which answers claims once the one-time keys run out.
+      # It is NOT consumed when used, which is what stops a peer who has
+      # exhausted our keys being unable to reach us at all.
+      def generate_fallback_key
+        @account.generate_fallback_key
+        @account_changed = true
+
+        Protocol::Matrix::Keys.fallback_keys(
+          @account.fallback_key,
+          user_id:   @user_id,
+          device_id: @device_id,
+          signer:    @account,
+        )
+      end
+
+      # Call this ONLY after the upload succeeded.
+      def mark_keys_published!
+        @account.mark_keys_as_published
+        @account_changed = true
+        self
+      end
+
+      # The spec suggests keeping around half of the maximum available, since a
+      # device that runs out cannot be reached.
+      def default_one_time_key_count
+        @account.max_number_of_one_time_keys / 2
+      end
+
+      # Should we top up? Compared against what the SERVER last reported it
+      # still holds, not against what we generated: keys are consumed by other
+      # devices claiming them, which we never observe directly.
+      def needs_one_time_keys?(server_count)
+        server_count < default_one_time_key_count
+      end
+
+      # ── Reading ─────────────────────────────────────────────────────────────
+
+      # Read +message+ with whatever key this store holds for it.
+      #
+      # @returns [EncryptedMessage | Nil] the message, decrypted, or nil when we
+      #   hold no key for it.
+      #
+      # NIL IS NOT AN ERROR. A message whose room key has not arrived is the
+      # single most common state in an encrypted room, and it is recoverable:
+      # the key may turn up later in this batch, in a later one, or from backup.
+      # Raising here would make the normal case exceptional and force every sync
+      # loop to rescue it.
+      def decrypt(message)
+        case message.algorithm
+        when MEGOLM
+          decrypt_megolm(message)
+        when Protocol::Matrix::EncryptedMessage::OLM
+          decrypt_olm(message)
+        else
+          raise Protocol::Matrix::EncryptedMessage::UnsupportedAlgorithmError,
+            "unsupported algorithm: #{message.algorithm.inspect}"
+        end
+      end
+
+      # ── Writing ─────────────────────────────────────────────────────────────
+
+      # Encrypt a room event, rotating the session first if policy says so.
+      #
+      # @returns [Array] [content, session_id, targets_already_holding_the_key]
+      #   The caller needs the last two: before this content can be read by
+      #   anyone, the session key has to reach every device in the room that
+      #   does not already have it, and only the caller can talk to the
+      #   homeserver to do that.
+      def encrypt(room_id:, type:, content:, rotation: {})
+        entry = outbound_session(room_id, rotation: rotation)
+        payload = Protocol::Matrix::EncryptedMessage.room_payload(
+          type: type, content: content, room_id: room_id,
+        )
+
+        ciphertext = entry[:session].encrypt(JSON.generate(payload))
+        entry[:message_count] += 1
+        @changed_outbound_rooms << room_id
+
+        [
+          Protocol::Matrix::EncryptedMessage.megolm_content(
+            ciphertext: ciphertext,
+            session_id: entry[:session].session_id,
+            sender_key: identity_key,
+            device_id:  @device_id,
+          ),
+          entry[:session].session_id,
+          entry[:shared_with],
+        ]
+      end
+
+      # The live outbound session for a room, started or rotated as needed.
+      def outbound_session(room_id, rotation: {})
+        entry = @outbound_sessions[room_id]
+
+        if entry.nil? || expired?(entry, rotation)
+          rotate!(room_id)
+        else
+          entry
+        end
+      end
+
+      # Start a fresh session for a room, discarding the old one.
+      #
+      # CALL THIS WHEN ANYONE LEAVES. Whoever left still holds the current key,
+      # so every message encrypted with it afterwards would be readable by them;
+      # rotation is the only thing that stops that, and no timer will do it in
+      # time.
+      def rotate!(room_id)
+        if @e2ee.nil?
+          raise MissingPrimitivesError, "no e2ee factory was supplied, so no session can be started"
+        end
+
+        session = @e2ee::GroupSession.new
+        @changed_outbound_rooms << room_id
+
+        @outbound_sessions[room_id] = {
+          session:       session,
+          started_at:    now_ms,
+          message_count: 0,
+          shared_with:   {},
+        }
+      end
+
+      # The m.room_key payload handing a room's current session to someone else.
+      #
+      # ALSO STORED FOR OURSELVES. An outbound Megolm session cannot decrypt, so
+      # without keeping the matching inbound session we could not read our own
+      # messages back.
+      def room_key_payload(room_id)
+        entry = @outbound_sessions[room_id]
+
+        if entry.nil?
+          nil
+        else
+          session_key = entry[:session].session_key
+
+          add_group_session(@e2ee::InboundGroupSession.new(session_key), room_id: room_id)
+
+          Protocol::Matrix::EncryptedMessage.room_key_payload(
+            room_id:     room_id,
+            session_id:  entry[:session].session_id,
+            session_key: session_key,
+          )
+        end
+      end
+
+      # Has this device already been given the room's current key? Re-sharing to
+      # everyone on every message would be correct but wasteful.
+      def shared_with?(room_id, matrix_user_id, device_id)
+        entry = @outbound_sessions[room_id]
+
+        if entry.nil?
+          false
+        else
+          Array(entry[:shared_with][matrix_user_id]).include?(device_id)
+        end
+      end
+
+      # Record that a set of devices now holds the room's current key.
+      # +targets+ is { "@user:server" => ["DEVICEID", ...] }.
+      def record_shared!(room_id, targets)
+        @outbound_sessions[room_id].tap do |entry|
+          unless entry.nil?
+            targets.each do |matrix_user_id, device_ids|
+              held = entry[:shared_with][matrix_user_id] || []
+              entry[:shared_with][matrix_user_id] = held | Array(device_ids)
+            end
+
+            @changed_outbound_rooms << room_id
+          end
+        end
+      end
+
+      # Wrap a payload in Olm for one device.
+      #
+      # @parameter one_time_key [String] a claimed key, needed only when we have
+      #   no session with this device yet. Without either, the device is
+      #   unreachable and this answers nil rather than guessing.
+      def encrypt_to_device(payload, recipient:, recipient_identity_key:, recipient_key:, one_time_key: nil)
+        session = olm_sessions_with(recipient_identity_key).first ||
+          open_outbound_session(recipient_identity_key, one_time_key)
+
+        if session.nil?
+          nil
+        else
+          body = Protocol::Matrix::EncryptedMessage.olm_payload(
+            type:          payload["type"],
+            content:       payload["content"],
+            sender:        @user_id,
+            sender_key:    fingerprint,
+            recipient:     recipient,
+            recipient_key: recipient_key,
+          )
+
+          type, ciphertext = session.encrypt(JSON.generate(body))
+          @changed_olm_sessions << session.session_id
+
+          Protocol::Matrix::EncryptedMessage.olm_content(
+            sender_key: identity_key,
+            ciphertext: {
+              recipient_identity_key => Protocol::Matrix::EncryptedMessage.olm_ciphertext(
+                type: type, body: ciphertext,
+              ),
+            },
+          )
+        end
+      end
+
+      # ── Room keys ───────────────────────────────────────────────────────────
+
+      # Take a room key out of a decrypted to-device payload.
+      #
+      # Idempotent: the same key is commonly sent more than once -- a re-share,
+      # or a second device forwarding it -- and the session already held is the
+      # one further back in the ratchet, so replacing it would LOSE history.
+      #
+      # @returns [String | Nil] the session id absorbed, or nil if it was
+      #   already held or the payload was not a room key.
+      def absorb(payload)
+        type = payload["type"]
+
+        if type == ROOM_KEY || type == FORWARDED_ROOM_KEY
+          store_room_key(payload["content"] || {}, forwarded: type == FORWARDED_ROOM_KEY)
+        end
+      end
+
+      # Import a session recovered from server-side key backup.
+      #
+      # A DIFFERENT KEY FORMAT from a live m.room_key, which is the whole reason
+      # this is its own method: a backup blob carries an unsigned, version-1
+      # ExportedSessionKey, and InboundGroupSession.new rejects it outright --
+      # only .import accepts one. A session built this way carries no signature,
+      # so it cannot be attributed to the device that originally created it;
+      # `signing_key` is what the blob claims, kept for whatever wants to decide
+      # how much to trust it.
+      #
+      # @returns [String | Nil] the session id, or nil if already held.
+      def import_session(room_id:, session_id:, session_key:, sender_key: nil, signing_key: nil)
+        if @e2ee.nil?
+          raise MissingPrimitivesError, "no e2ee factory was supplied, so no session can be imported"
+        end
+
+        if @group_sessions.key?(session_id)
+          nil
+        else
+          put_group_session(
+            session_id,
+            @e2ee::InboundGroupSession.import(session_key),
+            room_id,
+            sender_key:  sender_key,
+            signing_key: signing_key,
+          )
+        end
+      end
+
+      # Add a room key we already hold a session object for.
+      def add_group_session(session, room_id:)
+        put_group_session(session.session_id, session, room_id)
+      end
+
+      def knows_session?(session_id) = @group_sessions.key?(session_id)
+
+      # Every room key held, as session_id => room_id.
+      def room_keys
+        @group_sessions.transform_values { |entry| entry[:room_id] }
+      end
+
+      def olm_sessions_with(sender_key) = Array(@olm_sessions[sender_key])
+
+      # ── What the caller must persist ────────────────────────────────────────
+
+      # Every piece of state this store advanced since the last #flush_changes!.
+      #
+      # THE CALLER MUST WRITE THESE. Olm and Megolm both ratchet, so a session
+      # that decrypted a message and was not saved will fail on the next one --
+      # permanently, because the peer has moved on and we have not. The account
+      # matters for the same reason: a prekey message consumes a one-time key.
+      def changes
+        {
+          account:        @account_changed ? @account : nil,
+          olm_sessions:   @changed_olm_sessions.uniq,
+          group_sessions: @changed_group_sessions.uniq,
+          outbound_rooms: @changed_outbound_rooms.uniq,
+        }
+      end
+
+      # Everything that changed, PICKLED AND READY TO WRITE.
+      #
+      # #changes names what moved; this hands over the bytes. The distinction
+      # matters because #changes alone was not enough to act on: it reports
+      # session ids, and an id cannot be pickled -- only the object can, and
+      # only the store holds those.
+      #
+      # Returns plain data. Where it goes, in what table, under what column, on
+      # what schedule, is the application's business entirely.
+      #
+      # @parameter pickle_key [PickleKey] see that class for why losing it loses
+      #   everything that was ever encrypted to this device.
+      def export(pickle_key)
+        key = pickle_key.to_s
+
+        {
+          account:           @account_changed ? @account.pickle(key) : nil,
+          olm_sessions:      export_olm_sessions(key),
+          group_sessions:    export_group_sessions(key),
+          outbound_sessions: export_outbound_sessions(key),
+        }
+      end
+
+
+      def changed?
+        @account_changed || @changed_olm_sessions.any? ||
+          @changed_group_sessions.any? || @changed_outbound_rooms.any?
+      end
+
+      def flush_changes!
+        @changed_olm_sessions = []
+        @changed_group_sessions = []
+        @changed_outbound_rooms = []
+        @account_changed = false
+        self
+      end
+
+      private
+
+        # Looked up by id rather than kept as a list of objects, so a session
+        # that ratcheted several times in one batch is pickled once, at its
+        # final position.
+        def export_olm_sessions(key)
+          @changed_olm_sessions.uniq.filter_map do |session_id|
+            found = find_olm_session(session_id)
+
+            if found
+              {session_id: session_id, sender_key: found.first, pickle: found.last.pickle(key)}
+            end
+          end
+        end
+
+        # No index from session id to peer, because the store is keyed the way
+        # the protocol is: Olm sessions are found BY PEER when decrypting. The
+        # scan costs nothing at the size this ever reaches -- a handful of
+        # sessions changed in one batch.
+        def find_olm_session(session_id)
+          pair = nil
+
+          @olm_sessions.each do |sender_key, sessions|
+            session = sessions.find { |candidate| candidate.session_id == session_id }
+
+            if session
+              pair = [sender_key, session]
+              break
+            end
+          end
+
+          pair
+        end
+
+        def export_group_sessions(key)
+          @changed_group_sessions.uniq.filter_map do |session_id|
+            entry = @group_sessions[session_id]
+
+            if entry
+              {
+                session_id:  session_id,
+                room_id:     entry[:room_id],
+                sender_key:  entry[:sender_key],
+                signing_key: entry[:signing_key],
+                pickle:      entry[:session].pickle(key),
+              }
+            end
+          end
+        end
+
+        def export_outbound_sessions(key)
+          @changed_outbound_rooms.uniq.filter_map do |room_id|
+            entry = @outbound_sessions[room_id]
+
+            if entry
+              {
+                room_id:       room_id,
+                session_id:    entry[:session].session_id,
+                message_count: entry[:message_count],
+                started_at:    entry[:started_at],
+                shared_with:   entry[:shared_with],
+                pickle:        entry[:session].pickle(key),
+              }
+            end
+          end
+        end
+
+
+        # The session id is the key, and it comes from ONE place per path: the
+        # payload when absorbing a received key, the session object when the
+        # caller supplies one directly. The two agree in practice; keying off
+        # whichever was to hand would hide it when they did not.
+        # The spec: a client "should remember the megolm `message_index` ... of
+        # each event they decrypt for each session" and treat a repeat as
+        # invalid -- UNLESS the event_id and origin_server_ts also match, which
+        # is the legitimate case of decrypting the same event twice.
+        #
+        # Without this, anyone who can place an event in the room can replay an
+        # old message under a fresh event id and have it accepted as new.
+        def check_message_index(message)
+          index = message.message_index
+
+          if index.nil?
+            nil
+          else
+            seen = @message_indexes[message.session_id] ||= {}
+            previous = seen[index]
+            current = [message.event_id, message.origin_server_ts]
+
+            if previous.nil?
+              seen[index] = current
+            elsif previous != current
+              raise ReplayError,
+                "session #{message.session_id} index #{index} already decrypted as " \
+                "#{previous.first.inspect}; this event claims #{message.event_id.inspect}"
+            end
+          end
+        end
+
+        # The same guard for Olm: a to-device ciphertext delivered twice is a
+        # replay, and an Olm session will happily decrypt a prekey message again.
+        def check_olm_replay(sender_key, info)
+          digest = Digest::SHA256.hexdigest("#{sender_key}|#{info['type']}|#{info['body']}")
+
+          if @olm_hashes.key?(digest)
+            raise ReplayError, "olm message from #{sender_key} was already decrypted"
+          end
+
+          @olm_hashes[digest] = now_ms
+        end
+
+        def expired?(entry, rotation)
+          messages = rotation[:rotation_period_msgs] || rotation["rotation_period_msgs"] ||
+            DEFAULT_ROTATION_MESSAGES
+          period = rotation[:rotation_period_ms] || rotation["rotation_period_ms"] ||
+            DEFAULT_ROTATION_MS
+
+          entry[:message_count] >= messages || (now_ms - entry[:started_at]) >= period
+        end
+
+        def open_outbound_session(identity_key, one_time_key)
+          if one_time_key.nil?
+            nil
+          else
+            if one_time_key.is_a?(Hash)
+              key = (one_time_key["key"] || one_time_key[:key])
+            else
+              key = one_time_key
+            end
+            session = @account.create_outbound_session(identity_key, key)
+            @account_changed = true
+            (@olm_sessions[identity_key] ||= []).unshift(session)
+            session
+          end
+        end
+
+        def now_ms = (Time.now.to_f * 1000).to_i
+
+        def put_group_session(session_id, session, room_id, sender_key: nil, signing_key: nil)
+          if @group_sessions.key?(session_id)
+            nil
+          else
+            @group_sessions[session_id] = {
+              session:     session,
+              room_id:     room_id,
+              sender_key:  sender_key,
+              signing_key: signing_key,
+            }
+            @changed_group_sessions << session_id
+            session_id
+          end
+        end
+
+        def decrypt_megolm(message)
+          entry = @group_sessions[message.session_id]
+
+          if entry.nil?
+            nil
+          else
+            # A key is issued FOR A ROOM. Using one against a message in another
+            # room would let a sender have a message attributed to a room they
+            # hold no key for.
+            if message.room_id && entry[:room_id] && message.room_id != entry[:room_id]
+              raise RoomMismatchError,
+                "session #{message.session_id} belongs to #{entry[:room_id]}, " \
+                "message claims #{message.room_id}"
+            end
+
+            message.decrypt!(entry[:session])
+            @changed_group_sessions << message.session_id
+            check_message_index(message)
+
+            # The payload carries its own room_id, and a sender whose payload
+            # disagrees with the envelope is attempting the same substitution
+            # from the inside.
+            if message.payload_room_id && message.room_id &&
+                message.payload_room_id != message.room_id
+              raise RoomMismatchError,
+                "payload claims #{message.payload_room_id}, envelope says #{message.room_id}"
+            end
+
+            message
+          end
+        end
+
+        def decrypt_olm(message)
+          info = message.ciphertext_for(identity_key)
+
+          if info.nil?
+            nil
+          else
+            check_olm_replay(message.sender_key, info)
+            payload = with_known_session(message) || with_new_session(message, info)
+
+            if payload
+              absorb(payload)
+              message
+            end
+          end
+        end
+
+        # Every session we already have with this peer, newest first. Several can
+        # exist when both sides opened one at the same time, and only one holds
+        # the ratchet state that reads this message.
+        def with_known_session(message)
+          decrypted = nil
+
+          olm_sessions_with(message.sender_key).each do |session|
+            decrypted = try_session(message, session)
+
+            if decrypted
+              @changed_olm_sessions << session.session_id
+              break
+            end
+          end
+
+          decrypted
+        end
+
+        def try_session(message, session)
+          message.decrypt!(session, identity_key: identity_key)
+        rescue Protocol::Matrix::EncryptedMessage::DecryptionError
+          nil
+        end
+
+        # A prekey message carries enough to open a NEW inbound session, and
+        # doing so CONSUMES one of our one-time keys -- which is why the account
+        # is marked changed even when the decryption then fails.
+        def with_new_session(message, info)
+          if info["type"] == Protocol::Matrix::EncryptedMessage::PREKEY
+            session = open_inbound_session(message, info)
+            @account_changed = true
+
+            (@olm_sessions[message.sender_key] ||= []).unshift(session)
+            @changed_olm_sessions << session.session_id
+
+            # Deliberately OUTSIDE the rescue below: a payload that decrypts to
+            # nonsense is a malformed message, not a failure to establish a
+            # session, and conflating them sends a reader looking in the wrong
+            # place.
+            try_session(message, session)
+          end
+        end
+
+        # Consumes one of our one-time keys, whether or not what follows works --
+        # which is why the account is marked changed even on a later failure.
+        def open_inbound_session(message, info)
+          session, _plaintext = @account.create_inbound_session(message.sender_key, info["body"])
+          session
+        rescue StandardError => e
+          raise Error, "could not open an inbound session from #{message.sender_key}: #{e.message}"
+        end
+
+        def store_room_key(content, forwarded:)
+          if content["algorithm"] != MEGOLM
+            nil
+          else
+            session_id = content["session_id"]
+
+            if session_id.nil? || @group_sessions.key?(session_id)
+              # Checked BEFORE building: constructing the session would be
+              # wasted work, and for a forwarded key it would also be the wrong
+              # answer -- the one already held is further back in the ratchet.
+              nil
+            else
+              put_group_session(
+                session_id,
+                build_group_session(content, forwarded: forwarded),
+                content["room_id"],
+                sender_key:  content["sender_key"],
+                signing_key: (content["sender_claimed_keys"] || {})["ed25519"],
+              )
+            end
+          end
+        end
+
+        # A direct room key is a signed, version-2 SessionKey; a FORWARDED one is
+        # an unsigned, version-1 ExportedSessionKey, which .new rejects outright.
+        # Different constructors, and the distinction is not cosmetic: a session
+        # built from a forwarded key carries no signature and so cannot be
+        # attributed to the device that originally created it.
+        def build_group_session(content, forwarded:)
+          if @e2ee.nil?
+            raise MissingPrimitivesError,
+              "no e2ee factory was supplied, so a received room key cannot be built"
+          end
+
+          if forwarded
+            @e2ee::InboundGroupSession.import(content["session_key"])
+          else
+            @e2ee::InboundGroupSession.new(content["session_key"])
+          end
+        end
+    end
+  end
+end
+
+__END__
+  describe "Async::Matrix::DeviceStore" do
+    # Fake primitives. The store names no native extension -- the account and
+    # the factory are injected -- so the whole class is driveable with three
+    # plain objects and no cryptography.
+    def fake_account(identity: "ourcurve", fingerprint: "oured")
+      account = Object.new
+      opened = []
+      account.define_singleton_method(:curve25519_key) { identity }
+      account.define_singleton_method(:pickle) { |_key| "account-pickle" }
+      account.define_singleton_method(:ed25519_key) { fingerprint }
+      account.define_singleton_method(:opened) { opened }
+      published = 0
+      account.define_singleton_method(:sign) { |_message| "SIGNED" }
+      account.define_singleton_method(:published) { published }
+      account.define_singleton_method(:max_number_of_one_time_keys) { 100 }
+      account.define_singleton_method(:generate_one_time_keys) { |_count| nil }
+      account.define_singleton_method(:one_time_keys) { {"k1" => "otk1", "k2" => "otk2"} }
+      account.define_singleton_method(:generate_fallback_key) { nil }
+      account.define_singleton_method(:fallback_key) { {"fb1" => "fbkey"} }
+      account.define_singleton_method(:mark_keys_as_published) { published += 1 }
+      account.define_singleton_method(:create_outbound_session) do |identity_key, one_time_key|
+        session = Object.new
+        session.define_singleton_method(:session_id) { "outbound-olm" }
+        session.define_singleton_method(:pickle) { |_key| "session-pickle" }
+        session.define_singleton_method(:encrypt) { |plaintext| [0, "prekey:#{plaintext.length}"] }
+        session
+      end
+      account.define_singleton_method(:create_inbound_session) do |sender_key, body|
+        opened << [sender_key, body]
+        payload = JSON.generate({
+          "type" => "m.dummy", "content" => {},
+          "sender" => "@bob:example.org", "recipient" => "@bot:example.org",
+          "recipient_keys" => {"ed25519" => "oured"}, "keys" => {"ed25519" => "theired"},
+        })
+        session = Object.new
+        session.define_singleton_method(:session_id) { "new-olm-session" }
+        session.define_singleton_method(:pickle) { |_key| "session-pickle" }
+        session.define_singleton_method(:decrypt) { |_type, _body| payload }
+        [session, payload]
+      end
+      account
+    end
+
+    def fake_olm_session(id, plaintext)
+      session = Object.new
+      session.define_singleton_method(:session_id) { id }
+      session.define_singleton_method(:pickle) { |_key| "session-pickle" }
+      session.define_singleton_method(:decrypt) do |_type, _body|
+        plaintext || raise(RuntimeError, "BAD_MESSAGE_MAC")
+      end
+      session
+    end
+
+    def olm_encrypting_session
+      session = Object.new
+      session.define_singleton_method(:session_id) { "existing-olm" }
+      session.define_singleton_method(:pickle) { |_key| "session-pickle" }
+      session.define_singleton_method(:encrypt) { |plaintext| [1, "msg:#{plaintext.length}"] }
+      session
+    end
+
+    # Reports a new message index each time, as a real session does.
+    def counting_group_session
+      index = -1
+      session = Object.new
+      session.define_singleton_method(:session_id) { "s" }
+      session.define_singleton_method(:pickle) { |_key| "inboundgroupsession-pickle" }
+      session.define_singleton_method(:decrypt) do |_ciphertext|
+        index += 1
+        [JSON.generate({"type" => "m.room.message", "content" => {}, "room_id" => "!room:example.org"}), index]
+      end
+      session
+    end
+
+    def fake_group_session(id, plaintext, index = 0)
+      session = Object.new
+      session.define_singleton_method(:session_id) { id }
+      session.define_singleton_method(:pickle) { |_key| "inboundgroupsession-pickle" }
+      session.define_singleton_method(:decrypt) { |_ciphertext| [plaintext, index] }
+      session
+    end
+
+    # Stands in for Async::Matrix::E2EE: all the store asks of it is
+    # InboundGroupSession.new / .import.
+    def fake_e2ee
+      built = []
+      # A payload the reader accepts: anything without type and content is
+      # refused, and rightly.
+      valid_payload = JSON.generate({
+        "type" => "m.room.message",
+        "content" => {"msgtype" => "m.text", "body" => "from backup"},
+        "room_id" => "!room:example.org",
+      })
+      factory = Module.new
+      klass = Class.new do
+        define_singleton_method(:built) { built }
+        define_singleton_method(:new) do |session_key|
+          built << [:new, session_key]
+          session = Object.new
+          session.define_singleton_method(:session_id) { "session-from-#{session_key}" }
+          session.define_singleton_method(:pickle) { |_key| "inboundgroupsession-pickle" }
+          session.define_singleton_method(:decrypt) { |_c| [valid_payload, 0] }
+          session
+        end
+        define_singleton_method(:import) do |exported|
+          built << [:import, exported]
+          session = Object.new
+          session.define_singleton_method(:session_id) { "session-from-#{exported}" }
+          session.define_singleton_method(:pickle) { |_key| "inboundgroupsession-pickle" }
+          session.define_singleton_method(:decrypt) { |_c| [valid_payload, 0] }
+          session
+        end
+      end
+      factory.const_set(:InboundGroupSession, klass)
+
+      group = Class.new do
+        define_singleton_method(:new) do
+          counter = 0
+          session = Object.new
+          session.define_singleton_method(:session_id) { "outbound1" }
+          session.define_singleton_method(:session_key) { "AgAAAAoutbound" }
+          session.define_singleton_method(:pickle) { |_key| "groupsession-pickle" }
+          session.define_singleton_method(:encrypt) do |plaintext|
+            counter += 1
+            "cipher#{counter}:#{plaintext.length}"
+          end
+          session
+        end
+      end
+      factory.const_set(:GroupSession, group)
+      factory
+    end
+
+    def build_store(**options)
+      Async::Matrix::DeviceStore.new(
+        **{
+          user_id: "@bot:example.org",
+          device_id: "ABCDEFGHIJ",
+          account: fake_account,
+        }.merge(options),
+      )
+    end
+
+    def megolm_message(session_id: "session1", room_id: "!room:example.org")
+      Protocol::Matrix::EncryptedMessage.new({
+        "type" => "m.room.encrypted",
+        "event_id" => "$evt1",
+        "room_id" => room_id,
+        "sender" => "@alice:example.org",
+        "content" => {
+          "algorithm" => "m.megolm.v1.aes-sha2",
+          "ciphertext" => "AwgAEnAC",
+          "session_id" => session_id,
+        },
+      })
+    end
+
+    def olm_message(type: 0, sender_key: "theircurve", recipient: "ourcurve")
+      Protocol::Matrix::EncryptedMessage.new({
+        "type" => "m.room.encrypted",
+        "sender" => "@bob:example.org",
+        "content" => {
+          "algorithm" => "m.olm.v1.curve25519-aes-sha2",
+          "sender_key" => sender_key,
+          "ciphertext" => {recipient => {"type" => type, "body" => "olmbody"}},
+        },
+      })
+    end
+
+    def room_key_payload(session_id: "shared1", room_id: "!room:example.org", type: "m.room_key")
+      JSON.generate({
+        "type" => type,
+        "content" => {
+          "algorithm" => "m.megolm.v1.aes-sha2",
+          "room_id" => room_id,
+          "session_id" => session_id,
+          "session_key" => "AgAAAAsession",
+        },
+        "sender" => "@bob:example.org",
+        "recipient" => "@bot:example.org",
+        "recipient_keys" => {"ed25519" => "oured"},
+        "keys" => {"ed25519" => "theired"},
+      })
+    end
+
+    def megolm_payload(room_id = "!room:example.org")
+      JSON.generate({
+        "type" => "m.room.message",
+        "content" => {"msgtype" => "m.text", "body" => "hello"},
+        "room_id" => room_id,
+      })
+    end
+
+    # ── Identity ──────────────────────────────────────────────────────────────
+
+    it "exposes the device's own keys" do
+      store = build_store
+
+      store.identity_key.should == "ourcurve"
+      store.fingerprint.should == "oured"
+      store.user_id.should == "@bot:example.org"
+      store.device_id.should == "ABCDEFGHIJ"
+    end
+
+    # ── Reading megolm ────────────────────────────────────────────────────────
+
+    it "decrypts a room message with the key it holds" do
+      store = build_store(
+        group_sessions: {
+          "session1" => {session: fake_group_session("session1", megolm_payload), room_id: "!room:example.org"},
+        },
+      )
+      message = store.decrypt(megolm_message)
+
+      message.decrypted?.should == true
+      message.type.should == "m.room.message"
+      message.content.should == {"msgtype" => "m.text", "body" => "hello"}
+    end
+
+    # A key for any room: the store holds them all, so nothing about the room
+    # has to be arranged in advance.
+    it "decrypts messages from several rooms" do
+      store = build_store(
+        group_sessions: {
+          "s-a" => {session: fake_group_session("s-a", megolm_payload("!a:example.org")), room_id: "!a:example.org"},
+          "s-b" => {session: fake_group_session("s-b", megolm_payload("!b:example.org")), room_id: "!b:example.org"},
+        },
+      )
+
+      store.decrypt(megolm_message(session_id: "s-a", room_id: "!a:example.org")).decrypted?.should == true
+      store.decrypt(megolm_message(session_id: "s-b", room_id: "!b:example.org")).decrypted?.should == true
+      store.room_keys.length.should == 2
+    end
+
+    # NOT AN ERROR. The key may arrive later in this batch, in a later one, or
+    # from backup; raising would make the commonest state exceptional.
+    it "answers nil for a message it holds no key for" do
+      store = build_store
+
+      store.decrypt(megolm_message).should.be.nil
+    end
+
+    # A key is issued FOR A ROOM. Honouring it elsewhere would let a sender have
+    # a message attributed to a room they hold no key for.
+    it "refuses a session issued for a different room" do
+      store = build_store(
+        group_sessions: {
+          "session1" => {session: fake_group_session("session1", megolm_payload), room_id: "!elsewhere:example.org"},
+        },
+      )
+
+      lambda {
+        store.decrypt(megolm_message(room_id: "!room:example.org"))
+      }.should.raise(Async::Matrix::DeviceStore::RoomMismatchError)
+    end
+
+    # The same substitution attempted from inside the ciphertext.
+    it "refuses a payload whose room disagrees with the envelope" do
+      store = build_store(
+        group_sessions: {
+          "session1" => {
+            session: fake_group_session("session1", megolm_payload("!other:example.org")),
+            room_id: "!room:example.org",
+          },
+        },
+      )
+
+      lambda {
+        store.decrypt(megolm_message(room_id: "!room:example.org"))
+      }.should.raise(Async::Matrix::DeviceStore::RoomMismatchError)
+    end
+
+    # ── Reading olm, and absorbing what it carries ────────────────────────────
+
+    it "decrypts a to-device message with a session it already has" do
+      store = build_store(
+        e2ee: fake_e2ee,
+        olm_sessions: {"theircurve" => [fake_olm_session("olm1", room_key_payload)]},
+      )
+      message = store.decrypt(olm_message(type: 1))
+
+      message.decrypted?.should == true
+      message.type.should == "m.room_key"
+    end
+
+    # THE POINT OF THE CLASS: reading a to-device message leaves the store able
+    # to read the room.
+    it "absorbs a room key as it reads it" do
+      store = build_store(
+        e2ee: fake_e2ee,
+        olm_sessions: {"theircurve" => [fake_olm_session("olm1", room_key_payload(session_id: "shared1"))]},
+      )
+
+      store.knows_session?("shared1").should == false
+      store.decrypt(olm_message(type: 1))
+      store.knows_session?("shared1").should == true
+      store.room_keys["shared1"].should == "!room:example.org"
+    end
+
+    it "tries every session it has with a peer, newest first" do
+      store = build_store(
+        e2ee: fake_e2ee,
+        olm_sessions: {
+          "theircurve" => [
+            fake_olm_session("stale", nil),
+            fake_olm_session("good", room_key_payload),
+          ],
+        },
+      )
+
+      store.decrypt(olm_message(type: 1)).decrypted?.should == true
+      store.changes[:olm_sessions].should == ["good"]
+    end
+
+    # A prekey message is the only kind that can open a new session, and doing
+    # so consumes one of our one-time keys.
+    it "opens a new inbound session from a prekey message" do
+      account = fake_account
+      store = build_store(account: account, e2ee: fake_e2ee)
+
+      store.decrypt(olm_message(type: 0))
+
+      account.opened.should == [["theircurve", "olmbody"]]
+      store.olm_sessions_with("theircurve").length.should == 1
+      store.changes[:account].should == account
+    end
+
+    it "does not open a session for an ordinary olm message" do
+      account = fake_account
+      store = build_store(account: account)
+
+      store.decrypt(olm_message(type: 1)).should.be.nil
+      account.opened.should == []
+    end
+
+    it "ignores a to-device message addressed to another device" do
+      store = build_store
+
+      store.decrypt(olm_message(recipient: "someone-elses-key")).should.be.nil
+    end
+
+    # ── Absorbing room keys directly ──────────────────────────────────────────
+
+    it "builds a direct room key with .new and a forwarded one with .import" do
+      factory = fake_e2ee
+      store = build_store(e2ee: factory)
+
+      store.absorb(JSON.parse(room_key_payload(session_id: "a")))
+      store.absorb(JSON.parse(room_key_payload(session_id: "b", type: "m.forwarded_room_key")))
+
+      factory::InboundGroupSession.built.map(&:first).should == [:new, :import]
+    end
+
+    # The session already held is the one further back in the ratchet, so
+    # replacing it would lose history.
+    it "keeps the key it already holds rather than replacing it" do
+      factory = fake_e2ee
+      store = build_store(e2ee: factory)
+
+      store.absorb(JSON.parse(room_key_payload)).should == "shared1"
+      store.absorb(JSON.parse(room_key_payload)).should.be.nil
+      factory::InboundGroupSession.built.length.should == 1
+    end
+
+    it "ignores a payload that is not a room key" do
+      store = build_store(e2ee: fake_e2ee)
+
+      store.absorb({"type" => "m.room.message", "content" => {}}).should.be.nil
+    end
+
+    it "ignores a room key for an algorithm it does not implement" do
+      store = build_store(e2ee: fake_e2ee)
+      payload = JSON.parse(room_key_payload)
+      payload["content"]["algorithm"] = "m.megolm.v2.made-up"
+
+      store.absorb(payload).should.be.nil
+    end
+
+    it "reports plainly when no factory was supplied" do
+      store = build_store
+
+      lambda {
+        store.absorb(JSON.parse(room_key_payload))
+      }.should.raise(Async::Matrix::DeviceStore::MissingPrimitivesError)
+    end
+
+    # ── What the caller must persist ──────────────────────────────────────────
+
+    # Both algorithms ratchet, so a session that read a message and was not
+    # saved fails on the next one -- permanently.
+    it "reports the sessions that ratcheted" do
+      store = build_store(
+        group_sessions: {
+          "session1" => {session: fake_group_session("session1", megolm_payload), room_id: "!room:example.org"},
+        },
+      )
+
+      store.changed?.should == false
+      store.decrypt(megolm_message)
+      store.changed?.should == true
+      store.changes[:group_sessions].should == ["session1"]
+    end
+
+    it "clears what it reported once the caller has written it" do
+      store = build_store(
+        group_sessions: {
+          "session1" => {session: fake_group_session("session1", megolm_payload), room_id: "!room:example.org"},
+        },
+      )
+      store.decrypt(megolm_message)
+      store.flush_changes!
+
+      store.changed?.should == false
+      store.changes[:group_sessions].should == []
+    end
+
+    it "reports a new room key as something to persist" do
+      store = build_store(e2ee: fake_e2ee)
+      store.absorb(JSON.parse(room_key_payload))
+
+      store.changes[:group_sessions].should == ["shared1"]
+    end
+
+    it "does not report the account until a one-time key is consumed" do
+      store = build_store(
+        olm_sessions: {"theircurve" => [fake_olm_session("olm1", room_key_payload)]},
+        e2ee: fake_e2ee,
+      )
+      store.decrypt(olm_message(type: 1))
+
+      store.changes[:account].should.be.nil
+    end
+
+    # ── Unknown algorithms ────────────────────────────────────────────────────
+
+    it "refuses an algorithm it does not implement" do
+      store = build_store
+      message = Protocol::Matrix::EncryptedMessage.new({
+        "type" => "m.room.encrypted",
+        "content" => {"algorithm" => "m.made.up", "ciphertext" => "x"},
+      })
+
+      lambda {
+        store.decrypt(message)
+      }.should.raise(Protocol::Matrix::EncryptedMessage::UnsupportedAlgorithmError)
+    end
+    # ── Publishing ────────────────────────────────────────────────────────────
+
+    it "builds its own signed device keys" do
+      store = build_store
+      keys = store.device_keys
+
+      keys["user_id"].should == "@bot:example.org"
+      keys["device_id"].should == "ABCDEFGHIJ"
+      keys["keys"].should == {
+        "curve25519:ABCDEFGHIJ" => "ourcurve",
+        "ed25519:ABCDEFGHIJ" => "oured",
+      }
+      keys["signatures"]["@bot:example.org"]["ed25519:ABCDEFGHIJ"].should == "SIGNED"
+    end
+
+    it "generates and signs one-time keys" do
+      store = build_store
+      keys = store.generate_one_time_keys(2)
+
+      keys.keys.sort.should == ["signed_curve25519:k1", "signed_curve25519:k2"]
+      keys["signed_curve25519:k1"]["key"].should == "otk1"
+      keys["signed_curve25519:k1"]["signatures"].should ==
+        {"@bot:example.org" => {"ed25519:ABCDEFGHIJ" => "SIGNED"}}
+    end
+
+    it "generates a fallback key, marked as one" do
+      store = build_store
+
+      store.generate_fallback_key["signed_curve25519:fb1"]["fallback"].should == true
+    end
+
+    # Generating consumes account state, so the caller has to save it.
+    it "reports the account as changed after generating keys" do
+      store = build_store
+      store.generate_one_time_keys(1)
+
+      store.changes[:account].should.not.be.nil
+    end
+
+    # The account forgets a key once marked published, so marking before the
+    # upload succeeds discards keys the server never got.
+    it "does not mark keys published until told to" do
+      account = fake_account
+      store = build_store(account: account)
+      store.generate_one_time_keys(1)
+
+      account.published.should == 0
+
+      store.mark_keys_published!
+      account.published.should == 1
+    end
+
+    it "asks for half the maximum, as the spec suggests" do
+      build_store.default_one_time_key_count.should == 50
+    end
+
+    # Compared against what the SERVER says it holds: keys are consumed by peers
+    # claiming them, which we never see.
+    it "tops up based on the server's count" do
+      store = build_store
+
+      store.needs_one_time_keys?(0).should == true
+      store.needs_one_time_keys?(49).should == true
+      store.needs_one_time_keys?(50).should == false
+    end
+    # ── Writing: megolm ───────────────────────────────────────────────────────
+
+    it "encrypts a room event and says which session it used" do
+      store = build_store(e2ee: fake_e2ee)
+      content, session_id, shared = store.encrypt(
+        room_id: "!room:example.org", type: "m.room.message", content: {"body" => "hi"},
+      )
+
+      content["algorithm"].should == "m.megolm.v1.aes-sha2"
+      content["session_id"].should == "outbound1"
+      content["sender_key"].should == "ourcurve"
+      content["device_id"].should == "ABCDEFGHIJ"
+      session_id.should == "outbound1"
+      shared.should == {}
+    end
+
+    it "reuses the room's session across messages" do
+      store = build_store(e2ee: fake_e2ee)
+      first = store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {})
+      second = store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {})
+
+      first[1].should == second[1]
+      first[0]["ciphertext"].should.not == second[0]["ciphertext"]
+    end
+
+    # Spec defaults for m.room.encryption.
+    it "rotates after the message limit" do
+      store = build_store(e2ee: fake_e2ee)
+      100.times { store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {}) }
+      entry = store.outbound_session("!r:example.org")
+
+      entry[:message_count].should == 0
+    end
+
+    it "honours the room's own rotation policy" do
+      store = build_store(e2ee: fake_e2ee)
+      rotation = {"rotation_period_msgs" => 2}
+      3.times { store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {}, rotation: rotation) }
+
+      store.outbound_session("!r:example.org", rotation: rotation)[:message_count].should == 1
+    end
+
+    # Whoever left still holds the current key, so every later message would be
+    # readable by them. No timer does this in time.
+    it "starts a new session when told to rotate" do
+      store = build_store(e2ee: fake_e2ee)
+      store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {})
+      store.record_shared!("!r:example.org", {"@ada:example.org" => ["DEV1"]})
+
+      store.rotate!("!r:example.org")
+
+      store.shared_with?("!r:example.org", "@ada:example.org", "DEV1").should == false
+      store.outbound_session("!r:example.org")[:message_count].should == 0
+    end
+
+    it "tracks who already holds the room's key" do
+      store = build_store(e2ee: fake_e2ee)
+      store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {})
+
+      store.shared_with?("!r:example.org", "@ada:example.org", "DEV1").should == false
+      store.record_shared!("!r:example.org", {"@ada:example.org" => ["DEV1", "DEV2"]})
+      store.shared_with?("!r:example.org", "@ada:example.org", "DEV1").should == true
+      store.record_shared!("!r:example.org", {"@ada:example.org" => ["DEV3"]})
+      store.shared_with?("!r:example.org", "@ada:example.org", "DEV1").should == true
+      store.shared_with?("!r:example.org", "@ada:example.org", "DEV3").should == true
+    end
+
+    # An outbound session cannot decrypt, so without keeping the inbound twin we
+    # could not read our own messages back.
+    it "keeps its own room key when handing it out" do
+      store = build_store(e2ee: fake_e2ee)
+      store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {})
+      payload = store.room_key_payload("!r:example.org")
+
+      payload["type"].should == "m.room_key"
+      payload["content"]["session_id"].should == "outbound1"
+      payload["content"]["room_id"].should == "!r:example.org"
+      store.room_keys.values.should == ["!r:example.org"]
+    end
+
+    it "has no room key payload for a room it never sent to" do
+      build_store(e2ee: fake_e2ee).room_key_payload("!never:example.org").should.be.nil
+    end
+
+    it "refuses to start a session with no factory" do
+      lambda {
+        build_store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {})
+      }.should.raise(Async::Matrix::DeviceStore::MissingPrimitivesError)
+    end
+
+    # ── Writing: olm ──────────────────────────────────────────────────────────
+
+    it "wraps a payload for a device it already has a session with" do
+      store = build_store(olm_sessions: {"theircurve" => [olm_encrypting_session]})
+      content = store.encrypt_to_device(
+        {"type" => "m.room_key", "content" => {"a" => 1}},
+        recipient: "@bob:example.org",
+        recipient_identity_key: "theircurve",
+        recipient_key: "theired",
+      )
+
+      content["algorithm"].should == "m.olm.v1.curve25519-aes-sha2"
+      content["sender_key"].should == "ourcurve"
+      content["ciphertext"]["theircurve"]["type"].should == 1
+    end
+
+    it "opens a session from a claimed key when it has none" do
+      store = build_store
+      content = store.encrypt_to_device(
+        {"type" => "m.room_key", "content" => {}},
+        recipient: "@bob:example.org",
+        recipient_identity_key: "theircurve",
+        recipient_key: "theired",
+        one_time_key: {"key" => "theirotk"},
+      )
+
+      content["ciphertext"]["theircurve"]["type"].should == 0
+      store.olm_sessions_with("theircurve").length.should == 1
+    end
+
+    # Unreachable rather than guessable: with no session and no claimed key
+    # there is nothing to encrypt to.
+    it "answers nil for a device it cannot reach" do
+      build_store.encrypt_to_device(
+        {"type" => "m.room_key", "content" => {}},
+        recipient: "@bob:example.org",
+        recipient_identity_key: "theircurve",
+        recipient_key: "theired",
+      ).should.be.nil
+    end
+
+    # ── Replay protection ─────────────────────────────────────────────────────
+
+    # The spec: remember the message_index per session and treat a repeat as
+    # invalid, unless event_id and origin_server_ts also match.
+    it "accepts the same event decrypted twice" do
+      store = build_store(
+        group_sessions: {
+          "session1" => {session: fake_group_session("session1", megolm_payload, 5), room_id: "!room:example.org"},
+        },
+      )
+
+      store.decrypt(megolm_message).should.not.be.nil
+      store.decrypt(megolm_message).should.not.be.nil
+    end
+
+    # A message replayed under a fresh event id would otherwise be accepted as
+    # new.
+    it "refuses a reused message index under a different event id" do
+      store = build_store(
+        group_sessions: {
+          "session1" => {session: fake_group_session("session1", megolm_payload, 5), room_id: "!room:example.org"},
+        },
+      )
+      store.decrypt(megolm_message)
+
+      replayed = Protocol::Matrix::EncryptedMessage.new({
+        "type" => "m.room.encrypted",
+        "event_id" => "$different",
+        "room_id" => "!room:example.org",
+        "sender" => "@alice:example.org",
+        "content" => {
+          "algorithm" => "m.megolm.v1.aes-sha2",
+          "ciphertext" => "AwgAEnAC",
+          "session_id" => "session1",
+        },
+      })
+
+      lambda { store.decrypt(replayed) }.should.raise(Async::Matrix::DeviceStore::ReplayError)
+    end
+
+    it "allows different indexes in the same session" do
+      store = build_store(
+        group_sessions: {
+          "s" => {session: counting_group_session, room_id: "!room:example.org"},
+        },
+      )
+
+      store.decrypt(megolm_message(session_id: "s")).should.not.be.nil
+      store.decrypt(
+        Protocol::Matrix::EncryptedMessage.new({
+          "type" => "m.room.encrypted", "event_id" => "$two", "room_id" => "!room:example.org",
+          "sender" => "@alice:example.org",
+          "content" => {"algorithm" => "m.megolm.v1.aes-sha2", "ciphertext" => "c", "session_id" => "s"},
+        }),
+      ).should.not.be.nil
+    end
+
+    # An Olm session will decrypt a prekey message again quite happily.
+    it "refuses the same olm ciphertext twice" do
+      store = build_store(
+        e2ee: fake_e2ee,
+        olm_sessions: {"theircurve" => [fake_olm_session("olm1", room_key_payload)]},
+      )
+
+      store.decrypt(olm_message(type: 1)).should.not.be.nil
+      lambda { store.decrypt(olm_message(type: 1)) }.should.raise(Async::Matrix::DeviceStore::ReplayError)
+    end
+
+    it "reports an outbound room as needing persistence" do
+      store = build_store(e2ee: fake_e2ee)
+      store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {})
+
+      store.changes[:outbound_rooms].should == ["!r:example.org"]
+      store.flush_changes!
+      store.changes[:outbound_rooms].should == []
+    end
+    # ── Importing from backup ─────────────────────────────────────────────────
+
+    # The format is the point: a backup blob carries an unsigned, version-1
+    # ExportedSessionKey, which .new rejects -- only .import takes one.
+    it "imports a session recovered from backup" do
+      factory = fake_e2ee
+      store = build_store(e2ee: factory)
+
+      store.import_session(
+        room_id: "!old:example.org",
+        session_id: "backed-up-1",
+        session_key: "AgAAAADxexported",
+        sender_key: "theircurve",
+        signing_key: "theired",
+      ).should == "backed-up-1"
+
+      store.knows_session?("backed-up-1").should == true
+      store.room_keys["backed-up-1"].should == "!old:example.org"
+      factory::InboundGroupSession.built.should == [[:import, "AgAAAADxexported"]]
+    end
+
+    # The live key we already hold is further back in the ratchet, so a backup
+    # copy must not replace it.
+    it "keeps a session it already holds" do
+      store = build_store(e2ee: fake_e2ee)
+      store.import_session(room_id: "!r:example.org", session_id: "s1", session_key: "k")
+
+      store.import_session(room_id: "!r:example.org", session_id: "s1", session_key: "k").should.be.nil
+    end
+
+    it "reports an imported session as something to persist" do
+      store = build_store(e2ee: fake_e2ee)
+      store.import_session(room_id: "!r:example.org", session_id: "s1", session_key: "k")
+
+      store.changes[:group_sessions].should == ["s1"]
+    end
+
+    it "says plainly when it has no factory to import with" do
+      lambda {
+        build_store.import_session(room_id: "!r:example.org", session_id: "s1", session_key: "k")
+      }.should.raise(Async::Matrix::DeviceStore::MissingPrimitivesError)
+    end
+
+    # Decrypting works the same whether the key arrived live or from backup.
+    it "decrypts with an imported session" do
+      factory = fake_e2ee
+      store = build_store(e2ee: factory)
+      store.import_session(
+        room_id: "!room:example.org", session_id: "session1", session_key: "exported",
+      )
+
+      store.decrypt(megolm_message).should.not.be.nil
+    end
+    # ── Exporting what to persist ─────────────────────────────────────────────
+
+    def pickle_key = Async::Matrix::E2EE::PickleKey.derive("a test secret")
+
+    # #changes names what moved; #export hands over the bytes. The difference is
+    # the point: an id cannot be pickled, and only the store holds the objects.
+    it "exports the pickled account once a one-time key is consumed" do
+      store = build_store(e2ee: fake_e2ee)
+      store.decrypt(olm_message(type: 0))
+
+      store.export(pickle_key)[:account].should == "account-pickle"
+    end
+
+    it "exports nothing for an untouched store" do
+      store = build_store(e2ee: fake_e2ee)
+      exported = store.export(pickle_key)
+
+      exported[:account].should.be.nil
+      exported[:olm_sessions].should == []
+      exported[:group_sessions].should == []
+      exported[:outbound_sessions].should == []
+    end
+
+    # An Olm session is found BY PEER when decrypting, so there is no index from
+    # session id back to peer -- export has to look it up, and it must find it.
+    it "exports a ratcheted olm session with the peer it belongs to" do
+      store = build_store(
+        e2ee: fake_e2ee,
+        olm_sessions: {"theircurve" => [fake_olm_session("olm1", room_key_payload)]},
+      )
+      store.decrypt(olm_message(type: 1))
+      rows = store.export(pickle_key)[:olm_sessions]
+
+      rows.length.should == 1
+      rows.first[:session_id].should == "olm1"
+      rows.first[:sender_key].should == "theircurve"
+      rows.first[:pickle].should == "session-pickle"
+    end
+
+    it "exports a received room key with what it claimed about its sender" do
+      store = build_store(e2ee: fake_e2ee)
+      store.absorb(JSON.parse(room_key_payload))
+      row = store.export(pickle_key)[:group_sessions].first
+
+      row[:session_id].should == "shared1"
+      row[:room_id].should == "!room:example.org"
+      row[:pickle].should == "inboundgroupsession-pickle"
+    end
+
+    it "exports an outbound session with its rotation bookkeeping" do
+      store = build_store(e2ee: fake_e2ee)
+      store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {})
+      store.record_shared!("!r:example.org", {"@ada:example.org" => ["DEV1"]})
+      row = store.export(pickle_key)[:outbound_sessions].first
+
+      row[:room_id].should == "!r:example.org"
+      row[:session_id].should == "outbound1"
+      row[:message_count].should == 1
+      row[:shared_with].should == {"@ada:example.org" => ["DEV1"]}
+      row[:pickle].should == "groupsession-pickle"
+      row[:started_at].should.not.be.nil
+    end
+
+    # A session that ratchets several times in one batch is pickled once, at its
+    # final position -- not once per message.
+    it "exports a repeatedly ratcheted session once" do
+      store = build_store(e2ee: fake_e2ee)
+      3.times { store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {}) }
+      rows = store.export(pickle_key)[:outbound_sessions]
+
+      rows.length.should == 1
+      rows.first[:message_count].should == 3
+    end
+
+    it "exports nothing again once the caller has flushed" do
+      store = build_store(e2ee: fake_e2ee)
+      store.encrypt(room_id: "!r:example.org", type: "m.room.message", content: {})
+      store.flush_changes!
+
+      store.export(pickle_key)[:outbound_sessions].should == []
+    end
+  end