async-matrix 3.0.0-aarch64-linux → 3.0.1-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bef87f1b22f1fd59477479583775a4a235bd7985ae1c8567d3fe303572ab73f
-  data.tar.gz: ce844a66c8973aedc7b417afd1f811c77dc436ae1539cbc05dee932f09cdc35b
+  metadata.gz: 2b5019a1e531cc2e4130955f983b0ab97858020be746cb05ed7c2fd0fdfa18d4
+  data.tar.gz: b9a60430770fc16598f4e7d8b9b02548f74b34804b3b077b61e534c1202df0f0
 SHA512:
-  metadata.gz: 277f2e43ef49200ec76053fc316a994bf9881f5879e03d2bf00e0d0ae6c902608f74651f9e4b564336b05b229cff7619fe2814ec05be9227536cc508aea7070e
-  data.tar.gz: d1c41dcb08c2fe00456dfe5f0162389fb27b419ef242b16efd9a3a451b474be1f94b17ff6d6fcf10b08caad469d3c08d0d808caebe7c876ebb12a6d8053c750d
+  metadata.gz: 1a59e748998b8f5a4629204ebec300ad78867953356517addcd22595762abff097d047c4265066bb8967a5604d2b3902f2da5a6a1164ee90b2218500fb6a4397
+  data.tar.gz: 309cc2fcd6ea442563e744d385fd0f1f4ce487bfc91c54e0e254ac643e2874eae46f85f1f3dcf540fdeb8257c4ec381ed7fccd3cfacf773a9acab59f532f5982

data/lib/async/matrix/app_service_client.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "client"
+
+module Async
+  module Matrix
+    # A Client that acts AS one of the appservice's users, on one of that user's
+    # devices.
+    #
+    #   client = AppServiceClient.new(config, user_id: "@ada:example.org", device_id: "ABCDEFGHIJ")
+    #   client.upload_keys(device_keys: ...)   # uploaded for Ada's device, not the bot's
+    #
+    # This is double puppeting, and it is the officially intended mechanism
+    # rather than a trick. Identity assertion -- `?user_id=` -- has been in the
+    # application service spec for years; [MSC4326] added `?device_id=` beside
+    # it and is MERGED, so the plain parameter names below are stable spec, not
+    # the unstable `org.matrix.msc3202.device_id` an older implementation would
+    # have sent.
+    #
+    # WHY NOT A TOKEN. Bridges used to get a per-user access token by calling
+    # /login with `m.login.application_service` ([MSC2778]), and that route is
+    # gone on a homeserver fronted by OAuth2 -- it answers
+    # M_APPSERVICE_LOGIN_UNSUPPORTED. [MSC4190], which is also merged, replaced
+    # it: an appservice creates devices directly (`PUT /devices/{deviceId}`) and
+    # then acts as them with these two parameters. No token is ever issued, so
+    # none can expire or need refreshing.
+    #
+    # IT STILL WORKS BEHIND MAS. Synapse checks an as_token against its own
+    # appservice registry before it introspects anything at the authentication
+    # service, so masquerading is unaffected by next-generation auth.
+    #
+    # THE USER MUST BE IN THE REGISTRATION'S NAMESPACE. The homeserver refuses
+    # otherwise -- which is why a double-puppet registration claims a wide user
+    # namespace non-exclusively rather than naming individuals.
+    #
+    # [MSC4326]: https://github.com/matrix-org/matrix-spec-proposals/pull/4326
+    # [MSC4190]: https://github.com/matrix-org/matrix-spec-proposals/pull/4190
+    # [MSC2778]: https://github.com/matrix-org/matrix-spec-proposals/pull/2778
+    class AppServiceClient < Client
+      # @parameter user_id [String] the user to act as. Must match the
+      #   registration's user namespace.
+      # @parameter device_id [String] the device to act as.
+      #
+      #   WITHOUT IT THE REQUEST HAS NO DEVICE, and an appservice request with
+      #   no device cannot upload one-time keys, claim keys or send to-device
+      #   messages -- every call encryption is made of. It is optional only
+      #   because the device has to be CREATED before it can be acted as, and
+      #   that one call is made without it.
+      def initialize(config, user_id:, device_id: nil, **options)
+        super(config, **options)
+
+        @user_id = user_id
+        @device_id = device_id
+      end
+
+      attr_reader :user_id, :device_id
+
+      # NAMED ON EVERY REQUEST, not only the ones that obviously need it. An
+      # appservice request that omits them is not an error: it silently acts as
+      # the registration's sender_localpart, with no device, which is far worse
+      # than a failure because it succeeds.
+      def default_query
+        {user_id: @user_id}.tap do |query|
+          if @device_id
+            query[:device_id] = @device_id
+          end
+        end
+      end
+
+      # A sibling client for another user or device, sharing this one's config
+      # and retry policy.
+      #
+      # One appservice commonly acts for many users, and the alternative --
+      # mutating user_id on a single client -- races itself the moment two
+      # fibers use it, which is exactly what an async bridge does.
+      def as(user_id:, device_id: nil)
+        self.class.new(@config, user_id: user_id, device_id: device_id)
+      end
+
+      # The same user, now on a device: what you call once the device exists.
+      def with_device(device_id)
+        as(user_id: @user_id, device_id: device_id)
+      end
+    end
+  end
+end
+
+__END__
+  describe "Async::Matrix::AppServiceClient" do
+    def config
+      Async::Matrix::Config.new({
+        "homeserver" => {"address" => "http://synapse:8008", "domain" => "example.org"},
+        "appservice" => {"as_token" => "as", "hs_token" => "hs", "bot" => {"username" => "bot"}},
+      })
+    end
+
+    def recording_client(user_id: "@ada:example.org", device_id: "ABCDEFGHIJ")
+      Async::Matrix::Api.reset!
+
+      client = Async::Matrix::AppServiceClient.new(config, user_id: user_id, device_id: device_id)
+      calls = []
+      client.define_singleton_method(:calls) { calls }
+      client.define_singleton_method(:internet) do
+        internet = Object.new
+        internet.define_singleton_method(:call) do |method, url, _headers, _body|
+          calls << [method, url]
+
+          # Shaped like what Client#read_limited consumes: a body that yields
+          # chunks and reports its own length.
+          body = Object.new
+          body.define_singleton_method(:length) { 2 }
+          body.define_singleton_method(:each) { |&block| block.call("{}") }
+          body.define_singleton_method(:close) { nil }
+
+          response = Object.new
+          response.define_singleton_method(:status) { 200 }
+          response.define_singleton_method(:body) { body }
+          response.define_singleton_method(:close) { nil }
+          response
+        end
+        internet
+      end
+      client
+    end
+
+    def last_url(client) = client.calls.last[1]
+
+    it "asserts the user and device on every request" do
+      client = recording_client
+      client.whoami
+
+      last_url(client).should ==
+        "http://synapse:8008/_matrix/client/v3/account/whoami" \
+        "?user_id=%40ada%3Aexample.org&device_id=ABCDEFGHIJ"
+    end
+
+    # Not only on the calls that obviously need it: an appservice request that
+    # omits them silently acts as the sender_localpart, with no device.
+    it "asserts them through the api chain too" do
+      client = recording_client
+      client.joined_members(room_id: "!ops:example.org")
+
+      last_url(client).should.be.include? "user_id=%40ada%3Aexample.org"
+      last_url(client).should.be.include? "device_id=ABCDEFGHIJ"
+    end
+
+    # The chain appends its own query first, so this is the case that catches a
+    # naive "?" concatenation.
+    it "appends to a path that already carries a query" do
+      client = recording_client
+      client.messages(room_id: "!ops:example.org", limit: 10)
+
+      last_url(client).should.be.include? "?dir=b&limit=10&"
+      last_url(client).should.be.include? "user_id=%40ada%3Aexample.org"
+      last_url(client).count("?").should == 1
+    end
+
+    # The device has to be created before it can be acted as, and that one call
+    # is made without a device.
+    it "omits the device when it has none" do
+      client = recording_client(device_id: nil)
+      client.whoami
+
+      last_url(client).should.be.include? "user_id=%40ada%3Aexample.org"
+      last_url(client).should.not.be.include? "device_id"
+    end
+
+    # Overwriting it would mean acting as somebody other than the caller asked
+    # for, which is worse than a failure.
+    it "lets a caller's own parameter win" do
+      client = recording_client
+      client.get("/_matrix/client/v3/account/whoami?user_id=%40bob%3Aexample.org")
+
+      last_url(client).should.be.include? "user_id=%40bob%3Aexample.org"
+      last_url(client).scan("user_id=").length.should == 1
+    end
+
+    it "encodes the punctuation in a user id" do
+      client = recording_client(user_id: "@ada:example.org")
+      client.whoami
+
+      last_url(client).should.be.include? "%40ada%3Aexample.org"
+    end
+
+    # One appservice acts for many users; mutating a shared client would race
+    # itself the moment two fibers used it.
+    it "makes a sibling client for another user" do
+      client = recording_client
+      other = client.as(user_id: "@bob:example.org", device_id: "OTHERDEV")
+
+      other.user_id.should == "@bob:example.org"
+      other.device_id.should == "OTHERDEV"
+      client.user_id.should == "@ada:example.org"
+      other.config.should.be == client.config
+    end
+
+    it "makes a client for the same user on a device" do
+      client = recording_client(device_id: nil)
+      with_device = client.with_device("NEWDEVICE")
+
+      with_device.user_id.should == "@ada:example.org"
+      with_device.device_id.should == "NEWDEVICE"
+    end
+
+    # An ordinary client asserts nothing: a user's own token already says who
+    # the request is for.
+    it "is the only client that asserts anything" do
+      Async::Matrix::Client.new(config).default_query.should == {}
+    end
+  end

data/lib/async/matrix/client/encryption.rb

@@ -0,0 +1,413 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "securerandom"
+
+module Async
+  module Matrix
+    class Client
+      # The endpoints that make a device exist, be reachable, and be able to
+      # share keys. Mixed into Client.
+      #
+      # ORDER MATTERS, and it is the one thing a reader needs from this file:
+      #
+      #   register_user      the account exists (appservices only)
+      #   create_device      the device exists, without /login (MSC4190)
+      #   upload_keys        other devices can now find and reach us
+      #   query_keys         we learn who else is in the room, and their keys
+      #   claim_keys         we take a key to open a session with one of them
+      #   send_to_device     we hand them a room key through that session
+      #
+      # Until `upload_keys` has run the device is invisible: nobody can claim a
+      # one-time key, so nobody can open an Olm session, so nobody can send us a
+      # room key, and every message in an encrypted room stays ciphertext. It is
+      # a precondition, not an optimisation.
+      #
+      # Every method routes through #api, so the path is validated against the
+      # vendored OpenAPI tree before a request is made -- a typo is an
+      # InvalidEndpointError here rather than a 404 from the homeserver.
+      module Encryption
+        # ── Publishing our own keys ───────────────────────────────────────────
+
+        # POST /keys/upload. Any combination of the three may be sent; a nil is
+        # omitted rather than sent as null.
+        #
+        # @parameter device_keys [Hash] from Protocol::Matrix::Keys.device_keys
+        # @parameter one_time_keys [Hash] from Keys.one_time_keys
+        # @parameter fallback_keys [Hash] from Keys.fallback_keys
+        # @returns [Hash] with `one_time_key_counts`, which is what tells us how
+        #   many the server now holds.
+        def upload_keys(device_keys: nil, one_time_keys: nil, fallback_keys: nil)
+          body = {}
+
+          if device_keys
+            body[:device_keys] = device_keys
+          end
+
+          unless one_time_keys.nil? || one_time_keys.empty?
+            body[:one_time_keys] = one_time_keys
+          end
+
+          unless fallback_keys.nil? || fallback_keys.empty?
+            body[:fallback_keys] = fallback_keys
+          end
+
+          api.keys.upload.post(body)
+        end
+
+        # POST /keys/device_signing/upload -- the cross-signing keys.
+        #
+        # MSC4190 removed the user-interactive auth requirement here for
+        # appservices, which is what makes this reachable without a password.
+        # It matters because MSC4153 lets senders refuse to share room keys with
+        # a device that is not cross-signed.
+        def upload_cross_signing_keys(master_key: nil, self_signing_key: nil, user_signing_key: nil)
+          body = {}
+
+          if master_key
+            body[:master_key] = master_key
+          end
+
+          if self_signing_key
+            body[:self_signing_key] = self_signing_key
+          end
+
+          if user_signing_key
+            body[:user_signing_key] = user_signing_key
+          end
+
+          api.keys.device_signing.upload.post(body)
+        end
+
+        # POST /keys/signatures/upload -- our signatures over other keys.
+        def upload_signatures(signatures)
+          api.keys.signatures.upload.post(signatures)
+        end
+
+        # ── Learning about other devices ──────────────────────────────────────
+
+        # POST /keys/query. +user_ids+ is who to ask about; an empty device list
+        # per user means "all of their devices".
+        #
+        # @parameter token [String] the `device_lists` sync token, so the server
+        #   can tell us whether our view is already current.
+        def query_keys(user_ids:, token: nil)
+          body = {device_keys: user_ids.to_h { |user_id| [user_id, []] }}
+
+          if token
+            body[:token] = token
+          end
+
+          api.keys.query.post(body)
+        end
+
+        # POST /keys/claim -- take one one-time key per device, to open a
+        # session.
+        #
+        # ONLY FOR DEVICES WE HAVE NO SESSION WITH. Each claim consumes a key
+        # from a finite pool, so claiming for a device we can already reach
+        # burns one for nothing.
+        #
+        # @parameter devices [Hash] { "@user:server" => ["DEVICEID", ...] }
+        def claim_keys(devices:, algorithm: Protocol::Matrix::Keys::SIGNED_CURVE25519, timeout: nil)
+          body = {
+            one_time_keys: devices.transform_values { |ids|
+              ids.to_h { |device_id| [device_id, algorithm] }
+            },
+          }
+
+          if timeout
+            body[:timeout] = timeout
+          end
+
+          api.keys.claim.post(body)
+        end
+
+        # ── Talking to devices directly ───────────────────────────────────────
+
+        # PUT /sendToDevice/{eventType}/{txnId}
+        #
+        # @parameter messages [Hash] { "@user:server" => { "DEVICEID" => content } }
+        #
+        # This is how a room key travels. The transaction id makes it
+        # idempotent, so a retry after a timeout cannot deliver twice.
+        def send_to_device(event_type:, messages:, txn_id: nil)
+          api.sendToDevice(event_type, txn_id || SecureRandom.uuid).put({messages: messages})
+        end
+
+        # ── Device lifecycle ──────────────────────────────────────────────────
+
+        # PUT /devices/{deviceId} -- MSC4190.
+        #
+        # THE REASON THIS EXISTS: appservices used to create devices by calling
+        # /login with `m.login.application_service`, and that route is gone on a
+        # homeserver fronted by OAuth2 (MAS). This endpoint creates the device
+        # with no login at all, answering 201 for a new one and 200 for one that
+        # already existed.
+        #
+        # The device id is OURS to choose and must never change afterwards: it
+        # is the identity every room key we hold is bound to.
+        def create_device(device_id:, display_name: nil)
+          body = {}
+
+          if display_name
+            body[:display_name] = display_name
+          end
+
+          api.devices(device_id).put(body)
+        end
+
+        # DELETE /devices/{deviceId}. MSC4190 removed the UIA requirement for
+        # appservices, which is what makes this callable unattended.
+        def delete_device(device_id:)
+          api.devices(device_id).delete
+        end
+
+        def devices = api.devices.get
+
+        def device(device_id:) = api.devices(device_id).get
+
+        # POST /register for an appservice-owned user.
+        #
+        # `inhibit_login` IS MANDATORY, not tidiness: honouring a login would
+        # mean issuing an access token, and under OAuth2 the homeserver no
+        # longer owns that -- so without it the call fails with
+        # M_APPSERVICE_LOGIN_UNSUPPORTED.
+        def register_user(username:)
+          api.register.post(
+            {
+              type:          "m.login.application_service",
+              username:      username,
+              inhibit_login: true,
+            },
+          )
+        end
+
+        # ── Key backup ────────────────────────────────────────────────────────
+
+        # GET /room_keys/version[/{version}] -- the backup's algorithm and
+        # auth_data, which carries the public key it was encrypted to.
+        def key_backup_version(version: nil)
+          if version
+            api.room_keys.version(version).get
+          else
+            api.room_keys.version.get
+          end
+        end
+
+        # GET /room_keys/keys -- every backed-up session, as
+        # rooms -> sessions -> session_data blobs for
+        # Protocol::Matrix::KeyBackup to decrypt.
+        def room_keys(version:)
+          # Plain keys, not the "?"-prefixed form: that convention exists to
+          # separate query params from a BODY on POST/PUT, and a GET has no
+          # body -- every kwarg is already a query parameter.
+          api.room_keys.keys.get(version: version)
+        end
+      end
+    end
+  end
+end
+
+__END__
+  describe "Async::Matrix::Client::Encryption" do
+    # A real Client with its transport stubbed, so these specs exercise the
+    # actual path construction AND the OpenAPI path-tree validation -- a wrong
+    # path fails here rather than as a 404 from a homeserver.
+    def recording_client(response = {})
+      # The REAL path tree. Api memoises it process-wide, and the Api specs
+      # inject a small fixture tree without restoring it (Api.reset! exists for
+      # that and goes uncalled), so without this these specs pass or fail
+      # according to the order scampi happens to load files in.
+      Async::Matrix::Api.reset!
+
+      config = Async::Matrix::Config.new({
+        "homeserver" => {"address" => "http://synapse:8008", "domain" => "example.org"},
+        "appservice" => {"as_token" => "as", "hs_token" => "hs", "bot" => {"username" => "bot"}},
+      })
+      client = Async::Matrix::Client.new(config)
+      calls = []
+      client.define_singleton_method(:calls) { calls }
+      client.define_singleton_method(:request) do |method, path, body = nil, **_options|
+        calls << [method, path, body]
+        response
+      end
+      client
+    end
+
+    def last(client) = client.calls.last
+
+    # ── Publishing ────────────────────────────────────────────────────────────
+
+    it "uploads device keys" do
+      client = recording_client
+      client.upload_keys(device_keys: {"user_id" => "@bot:example.org"})
+
+      last(client)[0].should == "POST"
+      last(client)[1].should == "/_matrix/client/v3/keys/upload"
+      last(client)[2].should == {device_keys: {"user_id" => "@bot:example.org"}}
+    end
+
+    it "uploads all three kinds of key together" do
+      client = recording_client
+      client.upload_keys(
+        device_keys: {"a" => 1},
+        one_time_keys: {"signed_curve25519:k" => {"key" => "k"}},
+        fallback_keys: {"signed_curve25519:f" => {"key" => "f", "fallback" => true}},
+      )
+
+      last(client)[2].keys.sort.should == [:device_keys, :fallback_keys, :one_time_keys]
+    end
+
+    # A nil is omitted rather than sent as null -- "May be absent if no new
+    # one-time keys are required".
+    it "omits what it was not given" do
+      client = recording_client
+      client.upload_keys(one_time_keys: {})
+
+      last(client)[2].should == {}
+    end
+
+    it "uploads cross-signing keys" do
+      client = recording_client
+      client.upload_cross_signing_keys(master_key: {"keys" => {}})
+
+      last(client)[1].should == "/_matrix/client/v3/keys/device_signing/upload"
+      last(client)[2].should == {master_key: {"keys" => {}}}
+    end
+
+    it "uploads signatures" do
+      client = recording_client
+      client.upload_signatures({"@bot:example.org" => {"ed25519:DEV" => {}}})
+
+      last(client)[1].should == "/_matrix/client/v3/keys/signatures/upload"
+    end
+
+    # ── Querying ──────────────────────────────────────────────────────────────
+
+    # An empty device list per user means "all of their devices".
+    it "queries keys for a set of users" do
+      client = recording_client
+      client.query_keys(user_ids: ["@ada:example.org", "@bob:example.org"])
+
+      last(client)[1].should == "/_matrix/client/v3/keys/query"
+      last(client)[2].should == {
+        device_keys: {"@ada:example.org" => [], "@bob:example.org" => []},
+      }
+    end
+
+    it "passes the device_lists token when it has one" do
+      client = recording_client
+      client.query_keys(user_ids: ["@ada:example.org"], token: "s72")
+
+      last(client)[2][:token].should == "s72"
+    end
+
+    it "claims one key per device, naming the algorithm" do
+      client = recording_client
+      client.claim_keys(devices: {"@ada:example.org" => ["DEV1", "DEV2"]})
+
+      last(client)[1].should == "/_matrix/client/v3/keys/claim"
+      last(client)[2].should == {
+        one_time_keys: {
+          "@ada:example.org" => {
+            "DEV1" => "signed_curve25519",
+            "DEV2" => "signed_curve25519",
+          },
+        },
+      }
+    end
+
+    # ── To-device ─────────────────────────────────────────────────────────────
+
+    it "sends to-device messages with a transaction id" do
+      client = recording_client
+      client.send_to_device(
+        event_type: "m.room.encrypted",
+        messages: {"@ada:example.org" => {"DEV1" => {"algorithm" => "m.olm.v1.curve25519-aes-sha2"}}},
+      )
+
+      last(client)[0].should == "PUT"
+      last(client)[1].should.be.start_with? "/_matrix/client/v3/sendToDevice/m.room.encrypted/"
+      last(client)[2].should == {
+        messages: {"@ada:example.org" => {"DEV1" => {"algorithm" => "m.olm.v1.curve25519-aes-sha2"}}},
+      }
+    end
+
+    # Idempotence: a retry after a timeout must not deliver twice.
+    it "lets the caller supply the transaction id" do
+      client = recording_client
+      client.send_to_device(event_type: "m.room.encrypted", messages: {}, txn_id: "txn1")
+
+      last(client)[1].should == "/_matrix/client/v3/sendToDevice/m.room.encrypted/txn1"
+    end
+
+    it "generates a different transaction id each time" do
+      client = recording_client
+      client.send_to_device(event_type: "m.room.encrypted", messages: {})
+      client.send_to_device(event_type: "m.room.encrypted", messages: {})
+
+      client.calls[0][1].should.not == client.calls[1][1]
+    end
+
+    # ── Devices ───────────────────────────────────────────────────────────────
+
+    # MSC4190: creates the device with no /login, which is the only way under
+    # OAuth2.
+    it "creates a device" do
+      client = recording_client
+      client.create_device(device_id: "ABCDEFGHIJ", display_name: "controller")
+
+      last(client)[0].should == "PUT"
+      last(client)[1].should == "/_matrix/client/v3/devices/ABCDEFGHIJ"
+      last(client)[2].should == {display_name: "controller"}
+    end
+
+    it "deletes a device" do
+      client = recording_client
+      client.delete_device(device_id: "ABCDEFGHIJ")
+
+      last(client)[0].should == "DELETE"
+      last(client)[1].should == "/_matrix/client/v3/devices/ABCDEFGHIJ"
+    end
+
+    # inhibit_login is mandatory under OAuth2: honouring a login would mean
+    # issuing an access token the homeserver no longer owns.
+    it "registers an appservice user without logging it in" do
+      client = recording_client
+      client.register_user(username: "controller")
+
+      last(client)[1].should == "/_matrix/client/v3/register"
+      last(client)[2].should == {
+        type: "m.login.application_service",
+        username: "controller",
+        inhibit_login: true,
+      }
+    end
+
+    # ── Key backup ────────────────────────────────────────────────────────────
+
+    it "reads the current backup version" do
+      client = recording_client
+      client.key_backup_version
+
+      last(client)[0].should == "GET"
+      last(client)[1].should == "/_matrix/client/v3/room_keys/version"
+    end
+
+    it "reads a specific backup version" do
+      client = recording_client
+      client.key_backup_version(version: "3")
+
+      last(client)[1].should == "/_matrix/client/v3/room_keys/version/3"
+    end
+
+    it "fetches the backed-up keys for a version" do
+      client = recording_client
+      client.room_keys(version: "3")
+
+      last(client)[1].should == "/_matrix/client/v3/room_keys/keys?version=3"
+    end
+  end