async-matrix 3.0.1 → 4.0.0

data/lib/async/matrix/representation.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "async/rest/representation"
+
+require_relative "redacted"
+require_relative "wrapper/json"
+
+module Async
+  module Matrix
+    # The base representation for all Matrix responses.
+    class Representation < Async::REST::Representation[Wrapper::JSON]
+      include Redacted
+
+      # What a pattern reads, which is the document the homeserver answered with.
+      #
+      # So a response is matched where it arrives, rather than having to be taken apart first. `[]` cannot do this, because `async-rest` already uses it to derive a sub-resource.
+      #
+      # @parameter keys [Array(Symbol) | nil] the names a pattern asked for.
+      # @returns [Hash] the value.
+      def deconstruct_keys(keys)
+        case self.value
+        in Hash => value
+          value
+        else
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/server_key.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "base64"
+require "openssl"
+
+require_relative "error"
+require_relative "e2ee/canonical_json"
+require_relative "signatures/verification_key"
+
+module Async
+  module Matrix
+    # The key a homeserver signs for its own server name with.
+    #
+    # A request is signed rather than carrying a token, and the same key signs events.
+    class ServerKey
+      # The only algorithm the specification defines for a server key.
+      ALGORITHM = "ed25519"
+
+      # How many bytes an ed25519 private key is, which is the seed rather than the expanded key.
+      SEED_SIZE = 32
+
+      class << self
+        # Read a key from the file a homeserver keeps it in.
+        #
+        # @parameter path [String] the file to read.
+        # @returns [ServerKey] the key.
+        # @raises [InvalidKeyError] if the file does not hold one.
+        def load(path)
+          self.parse(File.read(path))
+        end
+
+        # Read a key from the line a homeserver writes it as.
+        #
+        # @parameter text [String] the line, e.g. `ed25519 a_pxTp <seed>`.
+        # @returns [ServerKey] the key.
+        # @raises [InvalidKeyError] if the line does not hold one.
+        def parse(text)
+          algorithm, key_id, seed = text.strip.split(/\s+/, 3)
+
+          unless algorithm == ALGORITHM
+            raise InvalidKeyError, "Unsupported key algorithm #{algorithm.inspect}, expected #{ALGORITHM}!"
+          end
+
+          unless key_id and seed
+            raise InvalidKeyError, "A signing key is an algorithm, a key ID and a seed!"
+          end
+
+          self.new(key_id, Base64.decode64(seed))
+        end
+
+        # The unpadded base64 a signature and a key are written as.
+        #
+        # @parameter bytes [String] the bytes to encode.
+        # @returns [String] the encoded bytes.
+        def encode(bytes)
+          Base64.strict_encode64(bytes).delete("=")
+        end
+      end
+
+      # @parameter key_id [String] the key's name, e.g. `a_pxTp`.
+      # @parameter seed [String] the thirty two bytes the key is derived from.
+      # @raises [InvalidKeyError] if the seed is the wrong size.
+      def initialize(key_id, seed)
+        unless seed.bytesize == SEED_SIZE
+          raise InvalidKeyError, "An #{ALGORITHM} seed is #{SEED_SIZE} bytes, not #{seed.bytesize}!"
+        end
+
+        @key_id = key_id
+        @key = OpenSSL::PKey.new_raw_private_key(ALGORITHM, seed)
+      end
+
+      # @attribute [String] the key's name, which is not unique between servers.
+      attr :key_id
+
+      # @returns [String] the algorithm this key signs with.
+      def algorithm
+        ALGORITHM
+      end
+
+      # The name a signature is filed under, which is the algorithm and the key ID.
+      #
+      # @returns [String] the identifier, e.g. `ed25519:a_pxTp`.
+      def id
+        "#{ALGORITHM}:#{@key_id}"
+      end
+
+      # The public half, which is what another server verifies against.
+      #
+      # @returns [String] the key, as unpadded base64.
+      def public_key
+        self.class.encode(@key.raw_public_key)
+      end
+
+      # Sign an object, which is canonicalised first.
+      #
+      # @parameter object [Hash] the object to sign.
+      # @returns [String] the signature, as unpadded base64.
+      def sign(object)
+        self.class.encode(@key.sign(nil, E2EE::CanonicalJSON.for_signing(object)))
+      end
+
+      # @parameter object [Hash] the object the signature was made over.
+      # @parameter signature [String] the signature to check, as unpadded base64.
+      # @returns [Boolean] whether it was made by this key.
+      def verify(object, signature)
+        self.verification_key.verify(E2EE::CanonicalJSON.for_signing(object), Signatures::VerificationKey.decode(signature))
+      rescue ArgumentError
+        false
+      end
+
+      # The public half, as the thing which checks a signature with it.
+      #
+      # @returns [Signatures::VerificationKey] the key.
+      def verification_key
+        @verification_key ||= Signatures::VerificationKey.new(ALGORITHM, self.public_key)
+      end
+
+      def inspect
+        "\#<#{self.class} #{self.id}>"
+      end
+    end
+  end
+end

data/lib/async/matrix/signatures/keyring.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "verification_key"
+
+module Async
+  module Matrix
+    module Signatures
+      # Where a verification key is looked up, which the third step of the check needs.
+      #
+      # A caller holding keys from somewhere else answers `verification_key` itself instead.
+      class Keyring
+        class << self
+          # The keys a device published, which its owner's user ID signs with.
+          #
+          # @parameter device [E2EE::Device | Hash] the device, as the homeserver answered with it.
+          # @returns [Keyring] a keyring holding its keys.
+          def for_device(device)
+            value = self.value_of(device)
+            entity = value[:user_id] || value["user_id"]
+
+            self.new.tap do |keyring|
+              (value[:keys] || value["keys"] || {}).each do |key_id, key|
+                keyring.add(entity, key_id, key)
+              end
+            end
+          end
+
+          # The keys a homeserver publishes for itself, which it signs its own name with.
+          #
+          # @parameter server_keys [Hash] the answer from `/_matrix/key/v2/server`.
+          # @parameter expired [Boolean] whether to take the keys it has rotated away from too.
+          # @returns [Keyring] a keyring holding its keys.
+          def for_server(server_keys, expired: true)
+            value = self.value_of(server_keys)
+            entity = value[:server_name] || value["server_name"]
+            published = [value[:verify_keys] || value["verify_keys"] || {}]
+
+            if expired
+              published << (value[:old_verify_keys] || value["old_verify_keys"] || {})
+            end
+
+            self.new.tap do |keyring|
+              published.each do |keys|
+                keys.each do |key_id, key|
+                  keyring.add(entity, key_id, key[:key] || key["key"])
+                end
+              end
+            end
+          end
+
+          # @parameter key_id [String] the signing key identifier the key is filed under.
+          # @parameter key [String | VerificationKey] the key, as unpadded base64 or already read.
+          # @returns [VerificationKey | nil] the key, where we can check its algorithm.
+          def read(key_id, key)
+            key.is_a?(VerificationKey) ? key : VerificationKey.parse(key_id.to_s, key)
+          end
+
+          # A representation carries what the server answered with, and a plain hash is already it.
+          #
+          # @parameter object [Object] the answer, however it was given.
+          # @returns [Hash] the fields it holds.
+          def value_of(object)
+            object.respond_to?(:value) ? object.value : object
+          end
+        end
+
+        def initialize
+          @keys = {}
+        end
+
+        # @parameter entity [String] whose key it is, which is a server name or a user ID.
+        # @parameter key_id [String] the signing key identifier, e.g. `ed25519:1`.
+        # @parameter key [String | VerificationKey] the key, as unpadded base64 or already read.
+        # @returns [Keyring] the keyring, so that keys can be added one after another.
+        def add(entity, key_id, key)
+          verification_key = self.class.read(key_id, key)
+
+          if verification_key
+            (@keys[entity.to_s] ||= {})[key_id.to_s] = verification_key
+          end
+
+          self
+        end
+
+        # @parameter entity [String] whose keys to answer with.
+        # @returns [Hash] the keys it holds for that entity, by signing key identifier.
+        def [](entity)
+          @keys[entity.to_s] || {}
+        end
+
+        # @parameter entity [String] whose key it would be.
+        # @parameter key_id [String] the signing key identifier wanted.
+        # @returns [VerificationKey | nil] the key, where this keyring holds it.
+        def verification_key(entity, key_id)
+          self[entity][key_id.to_s]
+        end
+
+        # @returns [Array(String)] the entities this keyring holds a key for.
+        def entities
+          @keys.keys
+        end
+
+        def inspect
+          "\#<#{self.class} #{@keys.transform_values(&:keys)}>"
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/signatures/verification_key.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "base64"
+require "openssl"
+
+require_relative "../error"
+
+module Async
+  module Matrix
+    module Signatures
+      # The public half of a signing key, which is what checks a signature.
+      class VerificationKey
+        # The algorithms the specification defines, which is the one NACL implements.
+        ALGORITHMS = ["ed25519"].freeze
+
+        class << self
+          # @parameter key_id [String] the signing key identifier, e.g. `ed25519:1`.
+          # @parameter encoded [String] the key, as unpadded base64.
+          # @returns [VerificationKey | nil] the key, or nothing where we cannot check that algorithm.
+          # @raises [InvalidKeyError] if the algorithm is ours and the key is not readable.
+          def parse(key_id, encoded)
+            self.supported?(key_id) ? self.new(self.algorithm_of(key_id), encoded) : nil
+          end
+
+          # @parameter key_id [String] the signing key identifier to judge.
+          # @returns [Boolean] whether we understand the algorithm it names.
+          def supported?(key_id)
+            ALGORITHMS.include?(self.algorithm_of(key_id))
+          end
+
+          # The signing algorithm, which is the part of the identifier before the key identifier.
+          #
+          # @parameter key_id [String] the signing key identifier to read.
+          # @returns [String] the algorithm it names.
+          def algorithm_of(key_id)
+            key_id.to_s.split(":", 2).first.to_s
+          end
+
+          # The padding the specification leaves off, which `strict_decode64` wants back.
+          #
+          # @parameter encoded [String] the unpadded base64 to read.
+          # @returns [String] the bytes it holds.
+          # @raises [ArgumentError] if it is not base64.
+          def decode(encoded)
+            ::Base64.strict_decode64(encoded + ("=" * ((4 - (encoded.bytesize % 4)) % 4)))
+          end
+        end
+
+        # @parameter algorithm [String] the signing algorithm, e.g. `ed25519`.
+        # @parameter encoded [String] the key, as unpadded base64.
+        # @raises [InvalidKeyError] if the key is not readable.
+        def initialize(algorithm, encoded)
+          @algorithm = algorithm
+          @encoded = encoded
+          @key = OpenSSL::PKey.new_raw_public_key(algorithm, self.class.decode(encoded))
+        rescue ArgumentError, OpenSSL::PKey::PKeyError => error
+          raise InvalidKeyError, "#{encoded.inspect} is not an #{algorithm} key: #{error.message}"
+        end
+
+        # @attribute [String] the signing algorithm, e.g. `ed25519`.
+        attr :algorithm
+
+        # @attribute [String] the key, as unpadded base64.
+        attr :encoded
+
+        # @parameter bytes [String] the canonical form which was signed.
+        # @parameter signature [String] the signature bytes.
+        # @returns [Boolean] whether this key made it.
+        def verify(bytes, signature)
+          @key.verify(nil, signature, bytes)
+        rescue OpenSSL::PKey::PKeyError
+          false
+        end
+
+        def inspect
+          "\#<#{self.class} #{@algorithm}>"
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/signatures.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "error"
+require_relative "e2ee/canonical_json"
+require_relative "signatures/keyring"
+require_relative "signatures/verification_key"
+
+module Async
+  module Matrix
+    # Raised when an object does not carry the signature it was checked for.
+    #
+    # The reason is the step of the appendices' algorithm which failed.
+    class SignatureError < Error
+      # @parameter reason [Symbol] which step failed.
+      # @parameter message [String] what failed, in words.
+      # @parameter entity [String] whose signature was being checked.
+      # @parameter key_id [String | nil] the signing key identifier, where one was reached.
+      def initialize(reason, message, entity:, key_id: nil)
+        super(message)
+
+        @reason = reason
+        @entity = entity
+        @key_id = key_id
+      end
+
+      # @attribute [Symbol] which step failed, e.g. `:no_entity` or `:mismatch`.
+      attr :reason
+
+      # @attribute [String] whose signature was being checked.
+      attr :entity
+
+      # @attribute [String | nil] the signing key identifier, where one was reached.
+      attr :key_id
+    end
+
+    # The making and checking of signatures.
+    module Signatures
+      # The member a signature is filed under, which the signature never covers.
+      MEMBER = :signatures
+
+      class << self
+        # Sign an object, filing the signature beside any already there.
+        #
+        # The object is not changed: intermediate entities add their own signature to what they were given.
+        #
+        # @parameter object [Hash] the object to sign.
+        # @parameter key [ServerKey] the key to sign with.
+        # @parameter as [String] the entity the signature is made by.
+        # @returns [Hash] a copy of the object, carrying the signature.
+        def sign(object, key:, as:)
+          signatures = self.deep_copy(self.signatures(object))
+          entity = signatures[as.to_s] ||= {}
+          entity[key.id] = key.sign(object)
+
+          object.merge(self.member_of(object) => signatures)
+        end
+
+        # The algorithm the appendices give for checking a signature.
+        #
+        # Every signature we hold a key for must verify, and at least one must have been checked.
+        #
+        # @parameter object [Hash] the object the signature is over.
+        # @parameter entity [String] whose signature to check.
+        # @parameter keyring [Keyring] where to look a verification key up.
+        # @returns [Array(String)] the signing key identifiers which verified it.
+        # @raises [SignatureError] at whichever step fails.
+        def verify!(object, entity:, keyring:)
+          signatures = self.signatures_of(object, entity)
+          bytes = E2EE::CanonicalJSON.for_signing(object)
+
+          self.understood(signatures, entity).filter_map do |key_id, signature|
+            verification_key = keyring.verification_key(entity, key_id)
+
+            verification_key && self.check(bytes, signature, key_id, verification_key, entity)
+          end.tap do |checked|
+            if checked.empty?
+              raise SignatureError.new(:no_verification_key, "There is no verification key for #{entity.inspect}!", entity: entity)
+            end
+          end
+        end
+
+        # @parameter object [Hash] the object the signature is over.
+        # @parameter entity [String] whose signature to check.
+        # @parameter keyring [Keyring] where to look a verification key up.
+        # @returns [Boolean] whether the entity signed it.
+        def verify?(object, entity:, keyring:)
+          self.verify!(object, entity: entity, keyring: keyring)
+
+          true
+        rescue SignatureError
+          false
+        end
+
+        # @parameter object [Hash] the object to read.
+        # @returns [Hash] the signatures it carries, by entity and signing key identifier.
+        def signatures(object)
+          object[MEMBER] || object[MEMBER.to_s] || {}
+        end
+
+        # The first step: the entry for the entity, which must be there.
+        #
+        # @parameter object [Hash] the object to read.
+        # @parameter entity [String] whose signatures to find.
+        # @returns [Hash] their signatures, by signing key identifier.
+        # @raises [SignatureError] if they signed nothing.
+        def signatures_of(object, entity)
+          signatures = self.signatures(object)
+          mine = signatures[entity.to_s] || signatures[entity.to_s.to_sym]
+
+          unless mine and !mine.empty?
+            raise SignatureError.new(:no_entity, "There are no signatures from #{entity.inspect}!", entity: entity)
+          end
+
+          mine
+        end
+
+        # The second step: the identifiers whose algorithm we understand, of which there must be one.
+        #
+        # @parameter signatures [Hash] the entity's signatures, by signing key identifier.
+        # @parameter entity [String] whose signatures they are.
+        # @returns [Hash] those we could check, by signing key identifier.
+        # @raises [SignatureError] if we understand none of them.
+        def understood(signatures, entity)
+          signatures.to_h{|key_id, signature| [key_id.to_s, signature]}.select do |key_id, _|
+            VerificationKey.supported?(key_id)
+          end.tap do |known|
+            if known.empty?
+              raise SignatureError.new(:no_known_algorithm, "No signature from #{entity.inspect} uses an algorithm we know!", entity: entity)
+            end
+          end
+        end
+
+        # The fourth step and the last, which are the base64 and the signature itself.
+        #
+        # @parameter bytes [String] the canonical form the signature is over.
+        # @parameter signature [String] the signature, as unpadded base64.
+        # @parameter key_id [String] the signing key identifier it was made with.
+        # @parameter verification_key [VerificationKey] the key to check it against.
+        # @parameter entity [String] whose signature it is.
+        # @returns [String] the signing key identifier, where it verified.
+        # @raises [SignatureError] if the signature is not base64, or does not match.
+        def check(bytes, signature, key_id, verification_key, entity)
+          decoded = self.decode(signature, key_id, entity)
+
+          unless verification_key.verify(bytes, decoded)
+            raise SignatureError.new(:mismatch, "The signature from #{entity.inspect} under #{key_id.inspect} does not match!", entity: entity, key_id: key_id)
+          end
+
+          key_id
+        end
+
+        # The fourth step: the signature is base64, and nothing can be checked until it is read.
+        #
+        # @parameter signature [String] the signature, as unpadded base64.
+        # @parameter key_id [String] the signing key identifier it was made with.
+        # @parameter entity [String] whose signature it is.
+        # @returns [String] the signature bytes.
+        # @raises [SignatureError] if it is not base64.
+        def decode(signature, key_id, entity)
+          VerificationKey.decode(signature.to_s)
+        rescue ArgumentError
+          raise SignatureError.new(:malformed_signature, "The signature from #{entity.inspect} under #{key_id.inspect} is not base64!", entity: entity, key_id: key_id)
+        end
+
+        # @parameter object [Hash] the object to read.
+        # @returns [Symbol | String] the key its signatures are filed under, however it names them.
+        def member_of(object)
+          object.key?(MEMBER.to_s) ? MEMBER.to_s : MEMBER
+        end
+
+        # @parameter signatures [Hash] the signatures to copy.
+        # @returns [Hash] a copy, whose entities can be added to without changing the original.
+        def deep_copy(signatures)
+          signatures.to_h do |entity, keys|
+            [entity.to_s, keys.to_h{|key_id, signature| [key_id.to_s, signature]}]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/version.rb

@@ -4,7 +4,7 @@
 # Copyright, 2026, by General Intelligence Systems.
 
 module Async
-	module Matrix
-    VERSION = "3.0.1"
-	end
+  module Matrix
+    VERSION = "4.0.0"
+  end
 end

data/lib/async/matrix/version.rb.erb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Async
+  module Matrix
+    VERSION = "<%= version %>"
+  end
+end

data/lib/async/matrix/versioned.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Async
+  module Matrix
+    # Included into every class built for a version.
+    module Versioned
+      module ClassMethods
+        # @returns [Module] the generated API this class belongs to, or {Async::Matrix}.
+        def api
+          if self.const_defined?(:API)
+            self::API
+          else
+            self.namespace
+          end
+        end
+
+        # The API namespace this class belongs to: the module which holds it, which is one of the Matrix APIs, e.g. {Async::Matrix::ClientServer}.
+        #
+        # @returns [Module] the namespace.
+        def namespace
+          @namespace ||= begin
+            parts = self.unversioned.name.split("::")
+
+            Object.const_get(parts[0..-2].join("::"))
+          end
+        end
+
+        # The class this one was built from, which is this class when it is not versioned.
+        #
+        # @returns [Class] the unversioned class.
+        def unversioned
+          self.const_defined?(:API) ? self.superclass : self
+        end
+
+        # The specification version this class implements.
+        #
+        # Deliberately not `VERSION`: {Async::Matrix::VERSION} is the gem's own version, and an unversioned class resolves its api to {Async::Matrix}.
+        #
+        # @returns [String | nil] the version, or nil if this class is not versioned.
+        def version
+          api = self.api
+
+          if api.const_defined?(:SPEC_VERSION, false)
+            api::SPEC_VERSION
+          end
+        end
+      end
+
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      # @returns [Module] the generated API this instance's class belongs to.
+      def api
+        self.class.api
+      end
+
+      # @returns [String | nil] the specification version of this instance's class.
+      def version
+        self.class.version
+      end
+    end
+  end
+end