async-matrix-bridge 2.0.0 → 3.0.0

data/lib/async/matrix/bridge/registration.rb

@@ -3,242 +3,161 @@
 # Released under the Apache License, Version 2.0.
 # Copyright, 2026, by General Intelligence Systems.
 
-require "async/matrix"
-require "json_schemer"
-require "pathname"
 require "yaml"
 
+require_relative "puppet"
+
 module Async
   module Matrix
     module Bridge
+      # What the homeserver was told about this service, which is also the whole of its authority.
+      #
+      # A service cannot register itself: one which could would claim `.*` and read everything, so an
+      # administrator puts this file beside the homeserver's own configuration by hand.
+      #
+      # The namespaces are regexes the homeserver holds too, which is why a user outside them is
+      # refused here rather than asked about: the answer is already known.
       class Registration
-        SCHEMA_DIR = Pathname.new(__dir__).join("registration", "schema").freeze
-
-        Homeserver = Struct.new(:address, :domain)
-
-        Appservice = Struct.new(:as_token, :hs_token, :sender_localpart)
-
-        NAMESPACES = %w[users rooms aliases].freeze
-
-        attr_reader :raw, :homeserver, :appservice
-
-        def self.schema
-          @schema ||= JSONSchemer.schema(SCHEMA_DIR.join("registration.json"))
-        end
+        KINDS = ["users", "aliases", "rooms"].freeze
 
-        def self.load(path, homeserver:, domain:)
-          Pathname.new(path).then do |pathname|
-            unless pathname.exist?
-              raise Async::Matrix::NotFoundError.new(
-                "M_NOT_FOUND",
-                "Registration file not found: #{pathname}",
-              )
-            end
-
-            new(YAML.safe_load_file(pathname), homeserver: homeserver, domain: domain)
-          end
+        # @parameter path [String] the registration file.
+        # @parameter homeserver [String] where the homeserver is.
+        # @returns [Registration] the registration it describes.
+        def self.load(path, homeserver:)
+          self.new(::YAML.safe_load_file(path), homeserver: homeserver)
         end
 
-        def self.validate!(data)
-          schema.validate(data).to_a.then do |errors|
-            unless errors.empty?
-              messages = errors.map { |error| error["error"] }.join("; ")
-              raise Async::Matrix::BadJsonError.new(
-                "M_BAD_JSON",
-                "Registration validation failed: #{messages}",
-              )
+        # @parameter value [Hash] the registration, as the file spells it.
+        # @parameter homeserver [String] where the homeserver is.
+        def initialize(value, homeserver:)
+          ["id", "as_token", "hs_token", "sender_localpart"].each do |field|
+            unless value[field]
+              raise ArgumentError, "A registration must declare #{field}!"
             end
           end
-        end
 
-        def initialize(data, homeserver:, domain:)
-          self.class.validate!(data)
-
-          @raw = data
-          @homeserver = Homeserver.new(homeserver, domain)
-          @appservice = Appservice.new(
-            data["as_token"],
-            data["hs_token"],
-            data["sender_localpart"],
-          )
+          @value = value
+          @homeserver = homeserver
+          @domain = ::URI.parse(homeserver).host
         end
 
-        def id = @raw["id"]
+        # @attribute [Hash] the registration, as the file spells it.
+        attr :value
 
-        def url = @raw["url"]
+        # @attribute [String] where the homeserver is.
+        attr :homeserver
 
-        def as_token = @appservice.as_token
+        # @attribute [String] the server name the users of this service belong to.
+        attr :domain
 
-        def hs_token = @appservice.hs_token
+        # @returns [String] what the homeserver knows this service as.
+        def id = @value["id"]
 
-        def sender_localpart = @appservice.sender_localpart
+        # @returns [String] the token this service authenticates to the homeserver with.
+        def as_token = @value["as_token"]
 
-        def protocols = @raw["protocols"] || []
+        # @returns [String] the token the homeserver authenticates to this service with.
+        def hs_token = @value["hs_token"]
 
-        def rate_limited? = @raw.fetch("rate_limited", false)
+        # @returns [String] the user an unnamed request acts as.
+        def sender = "@#{@value["sender_localpart"]}:#{@domain}"
 
-        def receive_ephemeral? = @raw.fetch("receive_ephemeral", false)
+        # @returns [Boolean] whether the homeserver pushes read receipts and typing as well as events.
+        def ephemeral? = @value.fetch("receive_ephemeral", false)
 
+        # @parameter kind [String] `users`, `aliases` or `rooms`.
+        # @returns [Array(Hash)] the namespaces of that kind.
         def namespaces(kind)
-          unless NAMESPACES.include?(kind.to_s)
-            raise ArgumentError, "unknown namespace #{kind.inspect}; expected one of #{NAMESPACES.join(", ")}"
+          unless KINDS.include?(kind)
+            raise ArgumentError, "A registration has no #{kind} namespace!"
           end
 
-          @raw.fetch("namespaces", {}).fetch(kind.to_s, [])
+          @value.dig("namespaces", kind) || []
         end
 
+        # Whether this service is interested in something, which is the same answer the homeserver has.
+        #
+        # @parameter kind [String] `users`, `aliases` or `rooms`.
+        # @parameter value [String] the ID or alias to ask about.
+        # @returns [Boolean] whether a namespace covers it.
         def covers?(kind, value)
-          namespaces(kind).any? { |entry| Regexp.new(entry["regex"]).match?(value) }
+          self.namespaces(kind).any?{|namespace| self.class.claims?(namespace, value)}
         end
 
-        def bot_mxid = "@#{sender_localpart}:#{@homeserver.domain}"
-
+        # Whether nothing else may create this, which is what an exclusive namespace means.
+        #
+        # @parameter kind [String] `users`, `aliases` or `rooms`.
+        # @parameter value [String] the ID or alias to ask about.
+        # @returns [Boolean] whether this service owns it alone.
         def exclusive?(kind, value)
-          namespaces(kind).any? do |entry|
-            entry["exclusive"] && Regexp.new(entry["regex"]).match?(value)
+          self.namespaces(kind).any? do |namespace|
+            namespace["exclusive"] and self.class.claims?(namespace, value)
           end
         end
-      end
-    end
-  end
-end
-
-__END__
-  require "tempfile"
-
-  describe "Async::Matrix::Bridge::Registration" do
-    Registration = Async::Matrix::Bridge::Registration
-
-    def valid_data
-      {
-        "id" => "agent",
-        "url" => "http://appservice:9000",
-        "as_token" => "as_secret",
-        "hs_token" => "hs_secret",
-        "sender_localpart" => "agent",
-        "namespaces" => {
-          "users" => [{"regex" => "@_agent_.*:localhost", "exclusive" => true}],
-          "aliases" => [],
-          "rooms" => [],
-        },
-      }
-    end
-
-    def rejected?(data)
-      Registration.new(data, homeserver: "http://hs", domain: "d")
-      false
-    rescue Async::Matrix::BadJsonError
-      true
-    end
-
-    def build(overrides = {})
-      Registration.new(valid_data.merge(overrides), homeserver: "http://synapse:8008", domain: "localhost")
-    end
-
-    it "reads the spec fields off the registration" do
-      registration = build
-      registration.id.should == "agent"
-      registration.url.should == "http://appservice:9000"
-      registration.sender_localpart.should == "agent"
-    end
-
-    it "presents the config surface a Client and an Endpoint need" do
-      registration = build
-      registration.homeserver.address.should == "http://synapse:8008"
-      registration.appservice.as_token.should == "as_secret"
-      registration.appservice.hs_token.should == "hs_secret"
-      registration.bot_mxid.should == "@agent:localhost"
-    end
-
-    it "derives bot_mxid from sender_localpart and the supplied domain" do
-      Registration.new(valid_data, homeserver: "http://hs", domain: "example.org")
-        .bot_mxid.should == "@agent:example.org"
-    end
-
-    it "requires the spec's required fields" do
-      ["id", "as_token", "hs_token", "sender_localpart", "namespaces"].map do |field|
-        rejected?(valid_data.reject { |k, _| k == field })
-      end.should == [true, true, true, true, true]
-    end
-
-    it "requires url to be present but allows an explicit null" do
-      build("url" => nil).url.should == nil
-
-      rejected?(valid_data.reject { |k, _| k == "url" }).should == true
-    end
-
-    it "rejects a namespace entry missing regex or exclusive" do
-      [{"exclusive" => true}, {"regex" => "@a:b"}].map do |entry|
-        rejected?(valid_data.merge("namespaces" => {"users" => [entry]}))
-      end.should == [true, true]
-    end
-
-    it "rejects a non-string id" do
-      rejected?(valid_data.merge("id" => 42)).should == true
-    end
-
-    it "reports whether a value falls in a namespace" do
-      registration = build
-      registration.covers?(:users, "@_agent_alice:localhost").should == true
-      registration.covers?(:users, "@someone:localhost").should == false
-    end
-
-    it "reports exclusivity separately from coverage" do
-      registration = build("namespaces" => {"users" => [{"regex" => "@a.*:localhost", "exclusive" => false}]})
-      registration.covers?(:users, "@alice:localhost").should == true
-      registration.exclusive?(:users, "@alice:localhost").should == false
-    end
 
-    it "returns an empty list for an absent namespace kind" do
-      build("namespaces" => {"users" => []}).namespaces(:rooms).should == []
-    end
-
-    it "raises for an unknown namespace kind" do
-      error =
-        begin
-          build.namespaces(:widgets)
-          nil
-        rescue ArgumentError => e
-          e
+        # Whether one namespace names this, which is the whole of it rather than part.
+        #
+        # Anchored because a namespace names a user rather than appears inside one: unanchored,
+        # `@_bridge_.*` would claim `@notours_bridge_x:localhost` too, and a bridge asks this about
+        # senders to decide what is its own.
+        #
+        # @parameter namespace [Hash] one entry of one kind.
+        # @parameter value [String] the ID or alias to ask about.
+        # @returns [Boolean] whether the regex matches all of it.
+        def self.claims?(namespace, value)
+          ::Regexp.new("\\A(?:#{namespace["regex"]})\\z").match?(value)
         end
 
-      error.class.should == ArgumentError
-    end
-
-    it "defaults the spec's optional booleans to false" do
-      registration = build
-      registration.receive_ephemeral?.should == false
-      registration.rate_limited?.should == false
-      registration.protocols.should == []
-    end
-
-    it "reads receive_ephemeral when set" do
-      build("receive_ephemeral" => true).receive_ephemeral?.should == true
-    end
+        # A client which acts as this service, or as one of the users it may act as.
+        #
+        # Identity assertion rather than a login: the token says which service, so the user is a
+        # parameter on every request. `Async::REST::Resource#with` merges it into the reference, which
+        # is why this is a derived resource rather than a middleware.
+        #
+        # `ts` is timestamp massaging, which only a service may ask for: it says when an event really
+        # happened, so a backlog carried over from another network is not stamped as now.
+        #
+        # @parameter client [Async::Matrix::ClientServer::Client] an unauthenticated client.
+        # @parameter user_id [String | nil] the user to act as, or nil for this service's own.
+        # @parameter device_id [String | nil] the device to act as, which is honoured from v1.17.
+        # @parameter ts [Integer | nil] when what is sent through it happened, in milliseconds.
+        # @returns [Async::Matrix::ClientServer::Client] a client which acts as them.
+        def as(client, user_id = nil, device_id: nil, ts: nil)
+          service = client.authenticated(self.as_token)
+          parameters = {user_id: user_id, device_id: device_id, ts: ts}.compact
+
+          case user_id
+          in nil
+            service.with(parameters: parameters)
+          in String if self.covers?("users", user_id)
+            service.with(parameters: parameters)
+          in String
+            raise ArgumentError, "#{user_id} is outside this service's namespaces!"
+          end
+        end
 
-    it "loads from a YAML file" do
-      file = Tempfile.new(["registration", ".yaml"])
-      begin
-        file.write(YAML.dump(valid_data))
-        file.close
-
-        registration = Registration.load(file.path, homeserver: "http://synapse:8008", domain: "localhost")
-        registration.id.should == "agent"
-        registration.bot_mxid.should == "@agent:localhost"
-      ensure
-        file.unlink
-      end
-    end
+        # The user this service is, as something which can be given a device.
+        #
+        # An unnamed request acts as this user, but acting as a *device* of theirs needs one to exist:
+        # a service holds keys per device, and the sender has none until it makes one.
+        #
+        # @parameter client [Async::Matrix::ClientServer::Client] an unauthenticated client.
+        # @returns [Puppet] the user this service is.
+        def bot(client)
+          Puppet.new(self, client, @value["sender_localpart"])
+        end
 
-    it "raises NotFoundError for a missing file" do
-      error =
-        begin
-          Registration.load("/nonexistent/registration.yaml", homeserver: "http://hs", domain: "d")
-          nil
-        rescue Async::Matrix::NotFoundError => e
-          e
+        # One of this service's users, which has to be made before it can be acted as.
+        #
+        # @parameter client [Async::Matrix::ClientServer::Client] an unauthenticated client.
+        # @parameter localpart [String] the part of the ID which names them, without the sigil.
+        # @returns [Puppet] the user, and what makes it exist.
+        def puppet(client, localpart)
+          Puppet.new(self, client, localpart)
         end
 
-      error.class.should == Async::Matrix::NotFoundError
+        def inspect = "\#<#{self.class} #{self.id}>"
+      end
     end
   end
+end

data/lib/async/matrix/bridge/service.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "json"
+require "openssl"
+
+require "protocol/http/middleware"
+require "protocol/http/response"
+require "protocol/url/reference"
+
+require "console"
+
+require_relative "transaction"
+require_relative "transaction_store"
+
+module Async
+  module Matrix
+    module Bridge
+      # The paths a homeserver calls, which this service answers.
+      #
+      # A middleware rather than a Rack application: it is the same primitive which sits below a
+      # resource on the way out, pointed the other way, so it composes with everything else in the
+      # stack and reads a streamed body without an adapter in between.
+      class Service < ::Protocol::HTTP::Middleware
+        # Where every path this service answers begins.
+        PREFIX = "/_matrix/app/v1"
+
+        JSON_HEADERS = {"content-type" => "application/json"}.freeze
+
+        # @parameter registration [Registration] what the homeserver was told about this service.
+        # @parameter version [String] the specification version to type the events as.
+        # @parameter store [TransactionStore] what remembers the transactions already handled.
+        # @yields {|transaction| ...}
+        #   @parameter transaction [Transaction] the events the homeserver pushed.
+        def initialize(registration, version: Async::Matrix::LATEST, store: TransactionStore.new, &block)
+          super(::Protocol::HTTP::Middleware::NotFound)
+
+          @registration = registration
+          @version = version
+          @store = store
+          @block = block
+
+          @queries = {}
+        end
+
+        # @attribute [Registration] what the homeserver was told about this service.
+        attr :registration
+
+        # Answer whether a user is one of this service's own.
+        #
+        # The homeserver asks before it invents them, and nothing means no.
+        #
+        # @yields {|user_id| ...} whether the user exists, or should be made to.
+        def query_user(&block)
+          @queries[:user] = block
+        end
+
+        # Answer whether a room alias is one of this service's own, creating the room if it is.
+        #
+        # @yields {|alias_id| ...} whether the room exists, or should be made to.
+        def query_room(&block)
+          @queries[:room] = block
+        end
+
+        # Answer what this service bridges to, which a client asks a homeserver and it asks here.
+        #
+        # @yields {|kind, rest| ...} the protocols, locations or users it was asked for.
+        def query_thirdparty(&block)
+          @queries[:thirdparty] = block
+        end
+
+        # @parameter request [Protocol::HTTP::Request] what the homeserver asked.
+        # @returns [Protocol::HTTP::Response] what this service answers.
+        def call(request)
+          reference = ::Protocol::URL::Reference.parse(request.path)
+          segments = reference.path.to_s.delete_prefix("#{PREFIX}/").split("/")
+          parameters = self.parameters_of(reference)
+
+          case [request.method, segments]
+          # Nothing of ours, so nothing to say about it: a health check is not an unauthorised request.
+          in [_, [*]] if !reference.path.to_s.start_with?("#{PREFIX}/")
+            self.failure(404, "M_UNRECOGNIZED", "This service does not answer #{request.path}.")
+
+          # Every path of ours, the ping included: a wrong token is what the ping exists to find.
+          in [_, [*]] if !self.authentic?(request, parameters)
+            self.failure(403, "M_FORBIDDEN", "The token does not match the registration.")
+
+          in ["POST", ["ping"]]
+            self.rendered(200, {})
+
+          in ["PUT", ["transactions", txn_id]]
+            self.transaction(request, ::Protocol::URL::Encoding.unescape(txn_id))
+
+          in ["GET", ["users", user_id]]
+            self.answered(:user, ::Protocol::URL::Encoding.unescape(user_id), parameters)
+
+          in ["GET", ["rooms", alias_id]]
+            self.answered(:room, ::Protocol::URL::Encoding.unescape(alias_id), parameters)
+
+          in ["GET", ["thirdparty", *rest]]
+            self.answered(:thirdparty, rest, parameters)
+
+          # Which tells a homeserver that a feature is missing, rather than that this service is broken.
+          else
+            self.failure(404, "M_UNRECOGNIZED", "This service does not answer #{request.path}.")
+          end
+        end
+
+        def inspect = "\#<#{self.class} #{@registration.id}>"
+
+        private
+
+          # Hand the transaction over, and say whether to send it again.
+          #
+          # It is not recorded until it has been handled, so a handler which raises leaves the
+          # homeserver to retry rather than losing what it carried.
+          #
+          # @parameter request [Protocol::HTTP::Request] the request it arrived in.
+          # @parameter txn_id [String] the transaction, which the homeserver numbers.
+          # @returns [Protocol::HTTP::Response] the answer.
+          def transaction(request, txn_id)
+            case @store.seen?(txn_id)
+            in true
+              Console.debug(self) {"Transaction #{txn_id} was handled already."}
+
+              self.rendered(200, {})
+            in false
+              transaction = Transaction.for(request, txn_id, version: @version)
+
+              @block&.call(transaction)
+              @store.mark_seen(txn_id)
+
+              self.rendered(200, {})
+            end
+          rescue ::JSON::ParserError => error
+            # Sending it again would carry the same bytes, so this says so rather than asking for them.
+            Console.error(self, "A transaction was not JSON.", txn_id: txn_id, error: error)
+
+            self.failure(400, "M_BAD_JSON", error.message)
+          rescue => error
+            # Not recorded, so the homeserver sends it again: whatever failed may not fail twice.
+            Console.error(self, "A transaction was not handled.", txn_id: txn_id, error: error)
+
+            self.failure(500, "M_UNKNOWN", error.message)
+          end
+
+          # Ask whoever registered an answer for this kind of question.
+          #
+          # The answer is a block rather than a lambda, so one which does not want the query string
+          # may simply not take it.
+          #
+          # @parameter kind [Symbol] `:user`, `:room` or `:thirdparty`.
+          # @parameter subject [Object] what was asked about.
+          # @parameter parameters [Hash] the query string, which the third party lookups read.
+          # @returns [Protocol::HTTP::Response] the answer.
+          def answered(kind, subject, parameters)
+            query = @queries[kind]
+
+            case query&.call(subject, parameters)
+            # Nothing answered, so this service does not claim it.
+            in nil | false
+              self.failure(404, "M_NOT_FOUND", "This service does not know #{subject}.")
+
+            # A document to send back, which the third party lookups answer with.
+            in Hash | Array => document
+              self.rendered(200, document)
+
+            # Anything else is a yes, and a yes carries no document.
+            else
+              self.rendered(200, {})
+            end
+          end
+
+          # Whether the request carries the token the registration declares.
+          #
+          # From v1.4 it is a bearer token. Before that it was a query parameter, which a homeserver
+          # may still send, and which must agree when both are there.
+          #
+          # @parameter request [Protocol::HTTP::Request] the request to check.
+          # @parameter parameters [Hash] its query string, decoded.
+          # @returns [Boolean] whether it matches.
+          def authentic?(request, parameters)
+            offered = [self.bearer(request), parameters["access_token"]].compact
+
+            case offered
+            in []
+              false
+            in [*] if offered.all?{|token| self.matches?(token)}
+              true
+            else
+              false
+            end
+          end
+
+          # @parameter request [Protocol::HTTP::Request] the request to read.
+          # @returns [String | nil] the bearer token it carries.
+          def bearer(request)
+            case request.headers["authorization"]
+            in String => authorization if authorization.start_with?("Bearer ")
+              authorization.delete_prefix("Bearer ")
+            else
+              nil
+            end
+          end
+
+          # Compared in constant time, because the comparison is what an attacker measures.
+          #
+          # @parameter token [String] the token offered.
+          # @returns [Boolean] whether it is the one the registration declares.
+          def matches?(token)
+            ::OpenSSL.fixed_length_secure_compare(token, @registration.hs_token)
+          rescue ArgumentError
+            false
+          end
+
+          # The query string, which a reference carries as it arrived rather than decoded.
+          #
+          # @parameter reference [Protocol::URL::Reference] the path this request asked for.
+          # @returns [Hash] its parameters, which may be none.
+          def parameters_of(reference)
+            case reference.query
+            in String => query
+              ::Protocol::URL::Encoding.decode_www_form(query)
+            else
+              {}
+            end
+          end
+
+          # @parameter status [Integer] the status to answer with.
+          # @parameter payload [Hash | Array] the document to answer with.
+          # @returns [Protocol::HTTP::Response] the response.
+          def rendered(status, payload)
+            ::Protocol::HTTP::Response[status, JSON_HEADERS, [::JSON.generate(payload)]]
+          end
+
+          # The shape the client-server API uses, so a caller reads it the same way either side.
+          #
+          # @parameter status [Integer] the status to answer with.
+          # @parameter errcode [String] the Matrix error code.
+          # @parameter error [String] what went wrong, for a person to read.
+          # @returns [Protocol::HTTP::Response] the response.
+          def failure(status, errcode, error)
+            self.rendered(status, {errcode: errcode, error: error})
+          end
+      end
+    end
+  end
+end