async-matrix 3.0.1 → 4.0.0

data/lib/async/matrix/double_puppet_client.rb

@@ -1,82 +0,0 @@
-# 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 subclass that authenticates with a user's double puppet token
-    # instead of the appservice's as_token.
-    #
-    # This allows the bridge to send events as the real Matrix user rather
-    # than as the appservice bot or a ghost user.
-    #
-    #   puppet = DoublePuppetClient.new(config, double_puppet_token: "syt_...")
-    #   puppet.send_text("!room:example.com", "sent as the real user")
-    #   puppet.whoami  # => {"user_id" => "@alice:example.com"}
-    #
-    class DoublePuppetClient < Client
-      def initialize(config, double_puppet_token:, **kwargs)
-        super(config, **kwargs)
-        @headers[0] = ["authorization", "Bearer #{double_puppet_token}"]
-      end
-    end
-  end
-end
-
-__END__
-  describe "Async::Matrix::DoublePuppetClient" do
-    def make_config
-      Async::Matrix::Config.new({
-        "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
-        "appservice" => { "as_token" => "as_token_value", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
-      })
-    end
-
-    it "uses the double_puppet_token for authorization" do
-      puppet = Async::Matrix::DoublePuppetClient.new(make_config, double_puppet_token: "syt_puppet_token")
-      auth_header = puppet.instance_variable_get(:@headers).find { |k, _| k == "authorization" }
-      auth_header[1].should == "Bearer syt_puppet_token"
-    end
-
-    it "does not use the as_token from config" do
-      puppet = Async::Matrix::DoublePuppetClient.new(make_config, double_puppet_token: "syt_puppet_token")
-      auth_header = puppet.instance_variable_get(:@headers).find { |k, _| k == "authorization" }
-      auth_header[1].should.not.include "as_token_value"
-    end
-
-    it "inherits retry defaults from Client" do
-      puppet = Async::Matrix::DoublePuppetClient.new(make_config, double_puppet_token: "syt_puppet_token")
-      puppet.config.appservice.as_token.should == "as_token_value"
-    end
-
-    it "accepts custom retry configuration" do
-      puppet = Async::Matrix::DoublePuppetClient.new(
-        make_config,
-        double_puppet_token: "syt_puppet_token",
-        max_retries: 5,
-        retry_base_delay: 1.0,
-        max_retry_delay: 60
-      )
-      auth_header = puppet.instance_variable_get(:@headers).find { |k, _| k == "authorization" }
-      auth_header[1].should == "Bearer syt_puppet_token"
-    end
-
-    it "responds to all Client methods" do
-      puppet = Async::Matrix::DoublePuppetClient.new(make_config, double_puppet_token: "syt_puppet_token")
-      puppet.should.respond_to :send_text
-      puppet.should.respond_to :send_html
-      puppet.should.respond_to :send_notice
-      puppet.should.respond_to :join_room
-      puppet.should.respond_to :leave_room
-      puppet.should.respond_to :whoami
-      puppet.should.respond_to :api
-    end
-
-    it "is a subclass of Client" do
-      puppet = Async::Matrix::DoublePuppetClient.new(make_config, double_puppet_token: "syt_puppet_token")
-      puppet.should.be.kind_of Async::Matrix::Client
-    end
-  end

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

@@ -1,182 +0,0 @@
-# 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/endpoint.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the Apache License, Version 2.0.
-# Copyright, 2026, by General Intelligence Systems.
-
-require "json"
-require "async/http"
-
-module Async
-  module Matrix
-    # Extends Async::HTTP::Endpoint with Matrix well-known discovery.
-    # spec.matrix.org/v1.9/client-server-api/#well-known-uri
-    #
-    # A server at example.com may serve clients from a completely
-    # different origin — e.g. https://matrix.example.com:8448.
-    # #discover resolves that indirection as a proper async I/O
-    # operation before constructing the Endpoint, so every downstream
-    # caller gets a correctly-pointed connection pool for free.
-    class Endpoint < Async::HTTP::Endpoint
-      WELL_KNOWN = "/.well-known/matrix/client"
-
-      # Resolves homeserver base URL, falls back to https://domain.
-      # Must be called inside an Async block — uses the running scheduler.
-      def self.discover(domain, **options)
-        internet = Async::HTTP::Internet.new
-        data     = JSON.parse(internet.get("https://#{domain}#{WELL_KNOWN}").read)
-        base_url = data.dig("m.homeserver", "base_url") || "https://#{domain}"
-        parse(base_url, **options)
-      rescue StandardError
-        # Well-known is optional per spec — fall back gracefully
-        parse("https://#{domain}", **options)
-      ensure
-        internet&.close
-      end
-    end
-  end
-end
-
-__END__
-  it "defines the WELL_KNOWN constant" do
-    Async::Matrix::Endpoint::WELL_KNOWN.should == "/.well-known/matrix/client"
-  end
-
-  it "responds to .discover" do
-    Async::Matrix::Endpoint.should.respond_to :discover
-  end
-
-  it "inherits from Async::HTTP::Endpoint" do
-    Async::Matrix::Endpoint.ancestors.should.include Async::HTTP::Endpoint
-  end
-
-  it "falls back to https://domain when well-known fails" do
-    Async do
-      endpoint = Async::Matrix::Endpoint.discover("nonexistent.invalid")
-      endpoint.to_s.should =~ /nonexistent\.invalid/
-    end.wait
-  end

data/lib/async/matrix/error_response.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the Apache License, Version 2.0.
-# Copyright, 2026, by General Intelligence Systems.
-
-module Async
-  module Matrix
-    # 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
-    end
-  end
-end
-
-__END__
-  describe "Async::Matrix::ErrorResponse" do
-    it "parses errcode and error" do
-      resp = Async::Matrix::ErrorResponse.new({
-        "errcode" => "M_FORBIDDEN",
-        "error" => "Access denied"
-      })
-      resp.errcode.should == "M_FORBIDDEN"
-      resp.error.should == "Access denied"
-    end
-
-    it "handles missing fields" do
-      resp = Async::Matrix::ErrorResponse.new({})
-      resp.errcode.should.be.nil
-      resp.error.should.be.nil
-    end
-  end

data/lib/async/matrix/homeserver_error.rb

@@ -1,20 +0,0 @@
-# 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

@@ -1,20 +0,0 @@
-# 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

@@ -1,181 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the Apache License, Version 2.0.
-# Copyright, 2026, by General Intelligence Systems.
-
-require "async/http/internet"
-require "json"
-require "console"
-
-module Async
-  module Matrix
-    # Async HTTP client for binary Matrix media operations.
-    #
-    # Handles raw byte uploads and downloads against the Matrix content
-    # repository. Unlike the JSON-only Client, this never wraps request
-    # bodies in JSON.generate and can return raw binary response bodies.
-    #
-    # Not intended to be used directly — the Chain dispatches here
-    # automatically when the request path matches a BINARY_ROUTES entry.
-    #
-    #   media_client = Async::Matrix::MediaClient.new(config)
-    #   media_client.upload("POST", path, bytes, "image/png")
-    #   bytes = media_client.download(path)
-    #
-    class MediaClient
-      # Upload JSON responses are small; error bodies are even smaller.
-      UPLOAD_RESPONSE_SIZE_LIMIT = 1 * 1024 * 1024   # 1 MiB
-      ERROR_RESPONSE_SIZE_LIMIT  = 512 * 1024          # 512 KiB
-
-      def initialize(config)
-        @config = config
-        @base   = config.homeserver.address
-        @auth_headers = [
-          ["authorization", "Bearer #{config.appservice.as_token}"],
-          ["user-agent",    "AsyncMatrix/#{Async::Matrix::VERSION}"]
-        ]
-      end
-
-      # Upload raw bytes to the content repository.
-      #
-      # @param method [String] HTTP method ("POST" or "PUT")
-      # @param path [String] URL path (already URL-encoded)
-      # @param body [String] raw bytes to upload
-      # @param content_type [String] MIME type of the body
-      # @return [Hash] parsed JSON response (e.g. {"content_uri" => "mxc://..."})
-      def upload(method, path, body, content_type = "application/octet-stream")
-        url = "#{@base}#{path}"
-        headers = @auth_headers + [["content-type", content_type]]
-
-        Console.debug(self) { "UPLOAD #{method} #{path} (#{content_type}, #{body.bytesize} bytes)" }
-
-        response = internet.call(
-          method,
-          url,
-          headers,
-          body,
-        )
-        status   = response.status
-
-        unless (200..299).cover?(status)
-          payload = read_limited(response, ERROR_RESPONSE_SIZE_LIMIT)
-          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,
-          )
-        end
-
-        payload = read_limited(response, UPLOAD_RESPONSE_SIZE_LIMIT)
-        payload && !payload.empty? ? JSON.parse(payload) : {}
-      end
-
-      # Download from the content repository.
-      #
-      # Returns the raw HTTP response object so the caller has access to
-      # both the body and response metadata:
-      #
-      #   response = media_client.download(path)
-      #   response.read                          # raw bytes (String, Encoding::BINARY)
-      #   response.headers["content-type"]       # "image/png"
-      #   response.headers["content-disposition"] # "inline; filename=\"photo.jpg\""
-      #   response.body.each { |chunk| ... }     # streaming
-      #
-      # @param path [String] URL path (already URL-encoded, may include query string)
-      # @return [Protocol::HTTP::Response] the HTTP response
-      def download(path)
-        url = "#{@base}#{path}"
-
-        Console.debug(self) { "DOWNLOAD #{path}" }
-
-        response = internet.call(
-          "GET",
-          url,
-          @auth_headers,
-          nil,
-        )
-        status   = response.status
-
-        unless (200..299).cover?(status)
-          payload = response.read
-          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,
-          )
-        end
-
-        response
-      end
-
-      def close
-        @internet&.close
-        @internet = nil
-      end
-
-      private
-
-        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
-          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
-    end
-  end
-end
-
-__END__
-  describe "Async::Matrix::MediaClient" do
-    def make_config
-      Async::Matrix::Config.new({
-        "homeserver" => { "address" => "http://localhost:8008", "domain" => "localhost" },
-        "appservice" => { "as_token" => "test_token", "hs_token" => "hs_secret", "bot" => { "username" => "bot" } }
-      })
-    end
-
-    it "responds to upload and download" do
-      client = Async::Matrix::MediaClient.new(make_config)
-      client.should.respond_to :upload
-      client.should.respond_to :download
-    end
-
-    it "can be closed without error" do
-      client = Async::Matrix::MediaClient.new(make_config)
-      lambda { client.close }.should.not.raise
-    end
-  end

data/lib/async/matrix/not_found_error.rb

@@ -1,20 +0,0 @@
-# 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