async-matrix 2.1.0-x86_64-linux → 3.0.1-x86_64-linux

data/lib/async/matrix/double_puppet_client.rb

@@ -29,7 +29,7 @@ end
 __END__
   describe "Async::Matrix::DoublePuppetClient" do
     def make_config
-      Async::Matrix::ApplicationService::Config.new({
+      Async::Matrix::Config.new({
         "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
         "appservice" => { "as_token" => "as_token_value", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
       })

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

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "openssl"
+
+module Async
+  module Matrix
+    module E2EE
+      # The key every stored crypto object in this namespace is encrypted with
+      # at rest.
+      #
+      # A "pickle" is vodozemac's serialised snapshot of an Account or a
+      # session -- the only way ratchet state survives a restart:
+      #
+      #   blob    = session.pickle(pickle_key.to_s)
+      #   session = E2EE::Session.from_pickle(blob, pickle_key.to_s)
+      #
+      # This key is what stops a copy of the database being a plaintext dump of
+      # the device's identity keys and every room key it holds.
+      #
+      # IT MUST NEVER CHANGE. Rotate or lose it and every pickle is
+      # undecryptable: the Account goes, every Megolm session goes, and all
+      # encrypted history becomes permanently unreadable unless server-side key
+      # backup happens to hold copies. There is no recovery path and no warning
+      # -- the symptom is simply that nothing decrypts any more.
+      #
+      # SO THE SECRET IS THE APPLICATION'S, not this library's. #derive exists
+      # because the shape requirement below catches everyone, not because a gem
+      # should own your key material.
+      class PickleKey
+        # vodozemac wants exactly 32 bytes AND rejects a binary string: hand it
+        # raw KDF output and it fails with "expected utf-8, got ASCII-8BIT".
+        LENGTH = 32
+
+        # 24 bytes of entropy base64s to exactly 32 ASCII characters, which
+        # satisfies both constraints at once -- 32 bytes, valid UTF-8, 192 bits.
+        # That arithmetic is the whole reason this class exists.
+        DERIVED_BYTES = 24
+
+        DEFAULT_INFO = "matrix device pickle"
+
+        class Error < StandardError; end
+
+        # Derive a key from an application secret.
+        #
+        # Deterministic: the same secret always yields the same key, which is
+        # what makes it survive a restart without being written down anywhere.
+        # Use a different `info` to derive unrelated keys from one secret.
+        def self.derive(secret, info: DEFAULT_INFO, salt: "")
+          if secret.nil? || secret.to_s.empty?
+            raise Error, "cannot derive a pickle key from an empty secret"
+          end
+
+          new(
+            [
+              OpenSSL::KDF.hkdf(
+                secret.to_s,
+                salt:   salt,
+                info:   info,
+                length: DERIVED_BYTES,
+                hash:   "SHA256",
+              ),
+            ].pack("m0"),
+          )
+        end
+
+        # Wrap a key you already have -- one derived elsewhere, or read from a
+        # secret store.
+        #
+        # @raises [Error] unless it is exactly 32 bytes and valid UTF-8, because
+        #   vodozemac refuses anything else and the failure it gives is obscure.
+        def initialize(value)
+          @value = value.to_s.dup.force_encoding(Encoding::UTF_8)
+
+          unless @value.bytesize == LENGTH
+            raise Error, "a pickle key must be exactly #{LENGTH} bytes, got #{@value.bytesize}"
+          end
+
+          unless @value.valid_encoding?
+            raise Error, "a pickle key must be valid UTF-8; vodozemac rejects binary strings"
+          end
+
+          @value.freeze
+        end
+
+        # The key as vodozemac wants it.
+        def to_s = @value
+
+        # Never the key itself: a pickle key in a log or an exception message is
+        # as bad as one in a repository.
+        def inspect = "#<#{self.class.name} [redacted]>"
+
+        def ==(other) = other.is_a?(self.class) && to_s == other.to_s
+      end
+    end
+  end
+end
+
+__END__
+  describe "Async::Matrix::E2EE::PickleKey" do
+    K = Async::Matrix::E2EE::PickleKey
+
+    # The arithmetic this class exists for: 24 bytes of entropy base64s to
+    # exactly the 32 ASCII characters vodozemac demands.
+    it "derives a key of exactly 32 bytes, valid UTF-8" do
+      key = K.derive("an application secret")
+
+      key.to_s.bytesize.should == 32
+      key.to_s.encoding.should == Encoding::UTF_8
+      key.to_s.valid_encoding?.should == true
+    end
+
+    # Deterministic, which is what lets it survive a restart without being
+    # written down.
+    it "derives the same key from the same secret" do
+      K.derive("secret").should == K.derive("secret")
+    end
+
+    it "derives different keys from different secrets" do
+      K.derive("one").should.not == K.derive("two")
+    end
+
+    # One secret, several unrelated keys.
+    it "separates keys by info string" do
+      K.derive("secret", info: "a").should.not == K.derive("secret", info: "b")
+    end
+
+    it "refuses an empty secret" do
+      lambda { K.derive("") }.should.raise(Async::Matrix::E2EE::PickleKey::Error)
+      lambda { K.derive(nil) }.should.raise(Async::Matrix::E2EE::PickleKey::Error)
+    end
+
+    # ── Wrapping an existing key ──────────────────────────────────────────────
+
+    it "accepts a 32-byte key" do
+      K.new("k" * 32).to_s.should == "k" * 32
+    end
+
+    # The error vodozemac gives for the wrong length is obscure, so this one is
+    # not.
+    it "refuses a key of the wrong length" do
+      lambda { K.new("short") }.should.raise(Async::Matrix::E2EE::PickleKey::Error)
+      lambda { K.new("k" * 33) }.should.raise(Async::Matrix::E2EE::PickleKey::Error)
+    end
+
+    # "expected utf-8, got ASCII-8BIT" is what raw KDF output gets you.
+    it "refuses bytes that are not valid UTF-8" do
+      lambda { K.new("\xFF\xFE".b + ("k" * 30)) }
+        .should.raise(Async::Matrix::E2EE::PickleKey::Error)
+    end
+
+    it "accepts binary-encoded bytes that happen to be valid UTF-8" do
+      K.new(("k" * 32).b).to_s.encoding.should == Encoding::UTF_8
+    end
+
+    # ── Not leaking ───────────────────────────────────────────────────────────
+
+    # A pickle key in a log is as bad as one in a repository.
+    it "never shows the key in inspect" do
+      key = K.derive("secret")
+
+      key.inspect.should.not.be.include? key.to_s
+      key.inspect.should.be.include? "redacted"
+    end
+
+    it "is frozen, so nothing can mutate it in place" do
+      K.derive("secret").to_s.frozen?.should == true
+    end
+
+    # It belongs beside the objects it encrypts, which is the point of the
+    # namespace: every one of these answers #pickle.
+    it "sits with the classes whose pickles it protects" do
+      [
+        Async::Matrix::E2EE::Account,
+        Async::Matrix::E2EE::Session,
+        Async::Matrix::E2EE::GroupSession,
+        Async::Matrix::E2EE::InboundGroupSession,
+      ].each { |klass| klass.instance_methods.should.be.include? :pickle }
+    end
+  end

data/lib/async/matrix/error.rb

@@ -3,24 +3,17 @@
 # Released under the Apache License, Version 2.0.
 # Copyright, 2026, by General Intelligence Systems.
 
+require_relative "../../protocol/matrix/error"
+
 module Async
   module Matrix
-    class Error < StandardError
-      attr_reader :errcode, :status
-
-      def initialize(errcode, message, status: nil)
-        @errcode = errcode
-        @status = status
-        super(message)
-      end
-    end
-
-    class NotFoundError < Error; end
-    class BadJsonError < Error; end
-    class AuthError < Error; end
-    class HomeserverError < Error; end
-    class InvalidEndpointError < Error; end
-    class ResponseTooLargeError < Error; end
+    # One error base for the whole gem. See Protocol::Matrix::Error.
+    #
+    # A CONSTANT, NOT A SUBCLASS: the subclasses below it are declared as
+    # `class AuthError < Error`, which resolves this constant at load time, so
+    # they inherit the real class and `rescue Async::Matrix::Error` catches
+    # everything -- transport failures and format failures together.
+    Error = ::Protocol::Matrix::Error
   end
 end
 
@@ -45,23 +38,3 @@ __END__
       Async::Matrix::Error.new("M_UNKNOWN", "bad").should.be.kind_of StandardError
     end
   end
-
-  it "NotFoundError inherits from Error" do
-    Async::Matrix::NotFoundError.new("M_NOT_FOUND", "gone").should.be.kind_of Async::Matrix::Error
-  end
-
-  it "BadJsonError inherits from Error" do
-    Async::Matrix::BadJsonError.new("M_BAD_JSON", "invalid").should.be.kind_of Async::Matrix::Error
-  end
-
-  it "AuthError inherits from Error" do
-    Async::Matrix::AuthError.new("M_FORBIDDEN", "denied").should.be.kind_of Async::Matrix::Error
-  end
-
-  it "HomeserverError inherits from Error" do
-    Async::Matrix::HomeserverError.new("M_UNKNOWN", "upstream").should.be.kind_of Async::Matrix::Error
-  end
-
-  it "ResponseTooLargeError inherits from Error" do
-    Async::Matrix::ResponseTooLargeError.new("M_TOO_LARGE", "too big").should.be.kind_of Async::Matrix::Error
-  end

data/lib/async/matrix/{application_service/error_response.rb → error_response.rb}

@@ -5,23 +5,23 @@
 
 module Async
   module Matrix
-    module ApplicationService
-      class ErrorResponse
-        attr_reader :errcode, :error
+    # A Matrix standard error response body: `{"errcode": ..., "error": ...}`.
+    # Both {Client} and {MediaClient} parse failed responses into one of these.
+    class ErrorResponse
+      attr_reader :errcode, :error
 
-        def initialize(data)
-          @errcode = data["errcode"]
-          @error   = data["error"]
-        end
+      def initialize(data)
+        @errcode = data["errcode"]
+        @error   = data["error"]
       end
     end
   end
 end
 
 __END__
-  describe "Async::Matrix::ApplicationService::ErrorResponse" do
+  describe "Async::Matrix::ErrorResponse" do
     it "parses errcode and error" do
-      resp = Async::Matrix::ApplicationService::ErrorResponse.new({
+      resp = Async::Matrix::ErrorResponse.new({
         "errcode" => "M_FORBIDDEN",
         "error" => "Access denied"
       })
@@ -30,7 +30,7 @@ __END__
     end
 
     it "handles missing fields" do
-      resp = Async::Matrix::ApplicationService::ErrorResponse.new({})
+      resp = Async::Matrix::ErrorResponse.new({})
       resp.errcode.should.be.nil
       resp.error.should.be.nil
     end

data/lib/async/matrix/homeserver_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+# Async::Matrix::Error is this class's superclass, so it has to exist before
+# this file finishes loading — the glob in async/matrix.rb sorts
+# alphabetically and would otherwise get here first.
+require_relative "error"
+
+module Async
+  module Matrix
+    class HomeserverError < Error; end
+  end
+end
+
+__END__
+  it "HomeserverError inherits from Error" do
+    Async::Matrix::HomeserverError.new("M_UNKNOWN", "upstream").should.be.kind_of Async::Matrix::Error
+  end

data/lib/async/matrix/invalid_endpoint_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+# Async::Matrix::Error is this class's superclass, so it has to exist before
+# this file finishes loading — the glob in async/matrix.rb sorts
+# alphabetically and would otherwise get here first.
+require_relative "error"
+
+module Async
+  module Matrix
+    class InvalidEndpointError < Error; end
+  end
+end
+
+__END__
+  it "InvalidEndpointError inherits from Error" do
+    Async::Matrix::InvalidEndpointError.new("M_UNRECOGNIZED", "no such route").should.be.kind_of Async::Matrix::Error
+  end

data/lib/async/matrix/media_client.rb

@@ -49,19 +49,24 @@ module Async
 
         Console.debug(self) { "UPLOAD #{method} #{path} (#{content_type}, #{body.bytesize} bytes)" }
 
-        response = internet.call(method, url, headers, body)
+        response = internet.call(
+          method,
+          url,
+          headers,
+          body,
+        )
         status   = response.status
 
         unless (200..299).cover?(status)
           payload = read_limited(response, ERROR_RESPONSE_SIZE_LIMIT)
-          parsed = ApplicationService::ErrorResponse.new(
-            begin; JSON.parse(payload); rescue; {} end
+          parsed = ErrorResponse.new(
+            begin; JSON.parse(payload); rescue; {} end,
           )
           Console.error(self) { "Matrix media upload #{status}: #{parsed.errcode} — #{parsed.error}" }
           raise HomeserverError.new(
             parsed.errcode || "UNKNOWN",
             parsed.error || payload.to_s[0..200],
-            status: status
+            status: status,
           )
         end
 
@@ -87,19 +92,24 @@ module Async
 
         Console.debug(self) { "DOWNLOAD #{path}" }
 
-        response = internet.call("GET", url, @auth_headers, nil)
+        response = internet.call(
+          "GET",
+          url,
+          @auth_headers,
+          nil,
+        )
         status   = response.status
 
         unless (200..299).cover?(status)
           payload = response.read
-          parsed = ApplicationService::ErrorResponse.new(
-            begin; JSON.parse(payload); rescue; {} end
+          parsed = ErrorResponse.new(
+            begin; JSON.parse(payload); rescue; {} end,
           )
           Console.error(self) { "Matrix media download #{status}: #{parsed.errcode} — #{parsed.error}" }
           raise HomeserverError.new(
             parsed.errcode || "UNKNOWN",
             parsed.error || payload.to_s[0..200],
-            status: status
+            status: status,
           )
         end
 
@@ -113,37 +123,38 @@ module Async
 
       private
 
-      def internet
-        @internet ||= Async::HTTP::Internet.new
-      end
+        def internet
+          @internet ||= Async::HTTP::Internet.new
+        end
 
       # Read response body with a size limit. Raises ResponseTooLargeError
       # if the body exceeds the limit.
-      def read_limited(response, limit)
-        body = response.body
-        return nil unless body
-
-        if body.respond_to?(:length) && body.length && body.length > limit
-          body.close
-          raise ResponseTooLargeError.new(
-            "M_TOO_LARGE",
-            "Response Content-Length #{body.length} bytes exceeds limit of #{limit} bytes"
-          )
-        end
-
-        buffer = String.new(encoding: Encoding::BINARY)
-        body.each do |chunk|
-          buffer << chunk
-          if buffer.bytesize > limit
-            body.close
-            raise ResponseTooLargeError.new(
-              "M_TOO_LARGE",
-              "Response body exceeds limit of #{limit} bytes"
-            )
+        def read_limited(response, limit)
+          body = response.body
+          if body
+            if body.respond_to?(:length) && body.length && body.length > limit
+              body.close
+              raise ResponseTooLargeError.new(
+                "M_TOO_LARGE",
+                "Response Content-Length #{body.length} bytes exceeds limit of #{limit} bytes",
+              )
+            end
+            buffer = String.new(encoding: Encoding::BINARY)
+            body.each do |chunk|
+              buffer << chunk
+              if buffer.bytesize > limit
+                body.close
+                raise ResponseTooLargeError.new(
+                  "M_TOO_LARGE",
+                  "Response body exceeds limit of #{limit} bytes",
+                )
+              end
+            end
+            buffer.empty? ? nil : buffer
+          else
+            nil
           end
         end
-        buffer.empty? ? nil : buffer
-      end
     end
   end
 end
@@ -151,7 +162,7 @@ end
 __END__
   describe "Async::Matrix::MediaClient" do
     def make_config
-      Async::Matrix::ApplicationService::Config.new({
+      Async::Matrix::Config.new({
         "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
         "appservice" => { "as_token" => "test_token", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
       })

data/lib/async/matrix/not_found_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+# Async::Matrix::Error is this class's superclass, so it has to exist before
+# this file finishes loading — the glob in async/matrix.rb sorts
+# alphabetically and would otherwise get here first.
+require_relative "error"
+
+module Async
+  module Matrix
+    class NotFoundError < Error; end
+  end
+end
+
+__END__
+  it "NotFoundError inherits from Error" do
+    Async::Matrix::NotFoundError.new("M_NOT_FOUND", "gone").should.be.kind_of Async::Matrix::Error
+  end

data/lib/async/matrix/notifier.rb

@@ -37,17 +37,21 @@ module Async
 
         loop do
           result = yield
-          return result if result
+          if result
+            break result
+          end
 
           remaining = deadline - Time.now
-          return result if remaining <= 0
+          if remaining <= 0
+            break result
+          end
 
           begin
             Async::Task.current.with_timeout(remaining) do
               @condition.wait
             end
           rescue Async::TimeoutError
-            return yield
+            break yield
           end
         end
       end

data/lib/async/matrix/response_too_large_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+# Async::Matrix::Error is this class's superclass, so it has to exist before
+# this file finishes loading — the glob in async/matrix.rb sorts
+# alphabetically and would otherwise get here first.
+require_relative "error"
+
+module Async
+  module Matrix
+    class ResponseTooLargeError < Error; end
+  end
+end
+
+__END__
+  it "ResponseTooLargeError inherits from Error" do
+    Async::Matrix::ResponseTooLargeError.new("M_TOO_LARGE", "too big").should.be.kind_of Async::Matrix::Error
+  end

data/lib/async/matrix/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Matrix
-    VERSION = "2.1.0"
+    VERSION = "3.0.1"
 	end
 end

data/lib/async/matrix.rb

@@ -3,7 +3,6 @@
 # Released under the Apache License, Version 2.0.
 # Copyright, 2026, by General Intelligence Systems.
 
-require "bundler/setup"
 require "async/http"
 
 module Async
@@ -11,12 +10,22 @@ module Async
   end
 end
 
+# The message FORMAT layer: events, content, schemas, encrypted messages. It
+# does no IO, so it lives beside the other protocol-* libraries rather than
+# under the gem that opens sockets. Required FIRST, because the aliases below
+# and the client both depend on it.
+require "protocol/matrix"
+
+module Async
+  module Matrix
+    # Where these constants used to live. Kept as aliases so code written
+    # against 3.0 keeps working; new code should name Protocol::Matrix directly.
+    Event = ::Protocol::Matrix::Event
+    Content = ::Protocol::Matrix::Content
+    Schema = ::Protocol::Matrix::Schema
+  end
+end
+
 Dir.glob("#{__dir__}/matrix/**/*.rb").sort.each do |path|
-  next if path.include?("/migrations/")
-  # The Discord bridge is opt-in — it pulls in Sequel and opens a placeholder
-  # database at load time. Require "async/matrix/bridge/discord/db" explicitly
-  # when you need it, so plain Matrix use stays free of that dependency.
-  next if path.include?("/bridge/")
   require path
 end
-