async-matrix 3.0.0 → 4.0.0

data/lib/async/matrix/credentials.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "async/semaphore"
+
+require_relative "error"
+
+module Async
+  module Matrix
+    # The access token a client authenticates with, and the means to replace it.
+    #
+    # It lives below the resource because `#with` copies headers into every resource derived from one.
+    class Credentials
+      # How long before expiry a token is replaced. A sync long poll outlives a token with seconds left on it, so the margin is longer than the longest poll the token will be used for.
+      MARGIN = 60.0
+
+      # When an access token with the given lifetime expires.
+      #
+      # @parameter expires_in_ms [Integer | nil] the lifetime, in milliseconds.
+      # @returns [Time | nil] when it expires, or nil if the homeserver did not say.
+      def self.expires_at(expires_in_ms)
+        if expires_in_ms
+          Time.now + (expires_in_ms / 1000.0)
+        end
+      end
+
+      # @parameter refresh [ClientServer::Refresh] the unauthenticated endpoint which issues tokens.
+      # @parameter access_token [String] the token to authenticate with.
+      # @parameter refresh_token [String | nil] the token which buys a new access token.
+      # @parameter expires_in_ms [Integer | nil] how long the access token lasts.
+      def initialize(refresh, access_token:, refresh_token: nil, expires_in_ms: nil)
+        @refresh = refresh
+
+        @access_token = access_token
+        @refresh_token = refresh_token
+        @expires_at = self.class.expires_at(expires_in_ms)
+
+        # Bumped on every replacement, so that a rejected request can tell "my token is stale" from "somebody has already replaced it":
+        @generation = 0
+
+        # A replacement rotates the refresh token, so two at once would store one pair and discard the other:
+        @semaphore = Async::Semaphore.new(1)
+
+        # The refusal which ended this session, once one has. Remembered so that a burst of requests carrying a dead token asks the homeserver once rather than once each:
+        @rejection = nil
+      end
+
+      # @attribute [String] the access token requests are authenticated with.
+      attr :access_token
+
+      # @attribute [String | nil] the token which buys the next access token.
+      attr :refresh_token
+
+      # @attribute [Time | nil] when the access token expires, if the homeserver said.
+      attr :expires_at
+
+      # @attribute [Integer] how many times the access token has been replaced.
+      attr :generation
+
+      # Whether a refusal is one the homeserver may recover from, leaving the session alone.
+      #
+      # @parameter error [RequestError] the refusal.
+      # @returns [Boolean] whether the session may still be good.
+      def self.transient?(error)
+        # A server error is the homeserver having a bad moment, and a rate limit is it asking us to wait. Anything else is a verdict on the refresh token itself.
+        error.status >= 500 or error.status == 429
+      end
+
+      # Whether there is both a refresh token and somewhere to spend it.
+      #
+      # @returns [Boolean] whether there is anything to replace the access token with.
+      def renewable?
+        !@refresh.nil? and !@refresh_token.nil?
+      end
+
+      # Whether the access token has expired, or is close enough that it should be replaced now.
+      #
+      # @parameter now [Time] the time to measure against.
+      # @returns [Boolean] whether it needs replacing.
+      def expiring?(now = Time.now)
+        if @expires_at
+          now >= (@expires_at - MARGIN)
+        else
+          false
+        end
+      end
+
+      # The authorization header to send, replacing the access token first if it is about to expire.
+      #
+      # @returns [Tuple(String, Integer)] the header value, and the generation it came from.
+      def authorization
+        if self.renewable? and self.expiring?
+          self.renew!
+        end
+
+        ["Bearer #{@access_token}", @generation]
+      end
+
+      # Replace the access token, unless it has already been replaced since the given generation.
+      #
+      # @parameter generation [Integer] the generation the caller's token came from.
+      # @returns [Integer] the current generation.
+      # @raises [AuthenticationError] if the homeserver would not issue a new token.
+      def renew!(generation = @generation)
+        @semaphore.acquire do
+          if @generation > generation
+            @generation
+          elsif @rejection
+            raise @rejection
+          else
+            self.replace!
+          end
+        end
+      end
+
+      # Adopt tokens obtained some other way.
+      #
+      # Every resource derived from the client shares these credentials, so the resource graph does not have to be rebuilt after logging in again.
+      #
+      # @parameter access_token [String] the token to authenticate with from now on.
+      # @parameter refresh_token [String | nil] the token which buys the next access token.
+      # @parameter expires_in_ms [Integer | nil] how long the access token lasts.
+      # @returns [Integer] the new generation.
+      def replace(access_token:, refresh_token: nil, expires_in_ms: nil)
+        @semaphore.acquire do
+          @access_token = access_token
+          @refresh_token = refresh_token || @refresh_token
+          @expires_at = self.class.expires_at(expires_in_ms)
+
+          # The session is no longer known to be dead:
+          @rejection = nil
+
+          @generation += 1
+        end
+      end
+
+      # Withdraw both tokens, which is how a session ends where the homeserver does not hold it.
+      #
+      # The access token is withdrawn last, so that a failure leaves nothing usable behind.
+      #
+      # @returns [Integer] the generation the session ended on.
+      def revoke!
+        @semaphore.acquire do
+          if @refresh_token
+            @refresh.revoke(@refresh_token, token_type_hint: "refresh_token")
+          end
+
+          @refresh.revoke(@access_token, token_type_hint: "access_token")
+
+          @refresh_token = nil
+          @generation += 1
+        end
+      end
+
+      # Close whatever issues the tokens, which may hold a connection of its own.
+      #
+      # @returns [Nil] nothing.
+      def close
+        @refresh&.close
+      end
+
+      def inspect
+        "\#<#{self.class} generation=#{@generation} renewable=#{self.renewable?}>"
+      end
+
+      # Exchange the refresh token for a new access token, and adopt whatever comes back.
+      #
+      # @returns [Integer] the new generation.
+      # @raises [AuthenticationError] if the homeserver would not issue a new token.
+      private def replace!
+        begin
+          refreshed = @refresh.refresh(@refresh_token)
+        rescue RequestError => error
+          if self.class.transient?(error)
+            # The session may still be good, so the caller is told what went wrong rather than to log in again:
+            raise
+          else
+            # Reported with the refusal's own status and code, so that a caller which already handles a rejected token handles this too. Logging out invalidates the refresh token along with the access token, which is exactly this path.
+            @rejection = AuthenticationError.new(error.status, error.errcode, "The access token could not be replaced.")
+
+            raise @rejection
+          end
+        end
+
+        @access_token = refreshed.access_token
+
+        # The homeserver may omit a new refresh token, in which case the existing one stands:
+        @refresh_token = refreshed.refresh_token || @refresh_token
+
+        @expires_at = self.class.expires_at(refreshed.expires_in_ms)
+        @generation += 1
+
+        @generation
+      end
+    end
+  end
+end

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

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "json"
+
+require "vodozemac"
+
+module Async
+  module Matrix
+    module E2EE
+      # The key a server side backup is encrypted to.
+      #
+      # Anybody holding the public half can add to a backup, and only the private half reads it back.
+      class Backup
+        # The only backup algorithm the specification defines.
+        ALGORITHM = "m.megolm_backup.v1.curve25519-aes-sha2"
+
+        # @returns [Backup] a new key pair, whose private half the user must keep.
+        def self.generate
+          self.new(Vodozemac::PkDecryption.new)
+        end
+
+        # The backup a private key opens, which is what secret storage hands back.
+        #
+        # @parameter private_key [String] the private half, base64 encoded.
+        # @parameter version [String | nil] which backup on the server it is.
+        # @returns [Backup] the backup.
+        def self.from_private_key(private_key, version: nil)
+          self.new(Vodozemac::PkDecryption.from_base64(self.unpadded(private_key)), version: version)
+        end
+
+        # A backup which can be added to but not read, which is all that writing needs.
+        #
+        # @parameter public_key [String] the public half, base64 encoded.
+        # @parameter version [String | nil] which backup on the server it is.
+        # @returns [Backup] the backup.
+        def self.from_public_key(public_key, version: nil)
+          self.new(nil, public_key: self.unpadded(public_key), version: version)
+        end
+
+        # @parameter decryption [Vodozemac::PkDecryption | nil] the private half, when there is one.
+        # @parameter public_key [String | nil] the public half, for a backup which has no private one.
+        # @parameter version [String | nil] which backup on the server it is.
+        def initialize(decryption, public_key: nil, version: nil)
+          @decryption = decryption
+          @public_key = public_key || decryption.public_key
+          @version = version
+        end
+
+        # @attribute [String | nil] which backup on the server this is.
+        attr :version
+
+        # The same backup, known to be a particular one on the server.
+        #
+        # @parameter version [String] the version the server gave it.
+        # @returns [Backup] the backup.
+        def at(version)
+          self.class.new(@decryption, public_key: @public_key, version: version)
+        end
+
+        # @returns [String] the public half, which goes into the backup's `auth_data`.
+        def public_key
+          @public_key
+        end
+
+        # @returns [String | nil] the private half, which belongs in secret storage.
+        def private_key
+          if self.private?
+            @decryption.secret_key
+          else
+            nil
+          end
+        end
+
+        # @returns [Boolean] whether this backup can be read as well as written to.
+        def private?
+          !@decryption.nil?
+        end
+
+        # What describes this backup to every other device, and what they check before writing to it.
+        #
+        # @returns [Hash] the authentication data, which a caller signs.
+        def auth_data
+          {public_key: self.public_key}
+        end
+
+        # One session, as the backup holds it.
+        #
+        # The fields outside `session_data` are what the server breaks a tie with, so they are sent in the clear deliberately.
+        #
+        # @parameter session [Hash] the session, as {Machine#export_for_backup} answers it.
+        # @returns [Hash] what to send for it.
+        def encrypt(session)
+          {
+            first_message_index: session[:first_message_index] || 0,
+            forwarded_count: session[:forwarded_count] || 0,
+            is_verified: session[:is_verified] || false,
+            session_data: self.sealed(::JSON.dump(self.backed_up(session))),
+          }
+        end
+
+        # Read one session back, if this is the key it was written to.
+        #
+        # @parameter session_data [Hash] the ciphertext, the code and the ephemeral key.
+        # @returns [Hash | nil] the session, or nil when it does not read.
+        def decrypt(session_data)
+          unless self.private?
+            raise ArgumentError, "This backup holds no private key, so nothing can be read from it!"
+          end
+
+          plaintext = self.opened(session_data)
+
+          if plaintext
+            ::JSON.parse(plaintext, symbolize_names: true)
+          else
+            nil
+          end
+        end
+
+        def inspect
+          "\#<#{self.class} #{self.public_key}#{self.private? ? " private" : ""}>"
+        end
+
+        # The specification carries base64 unpadded, and the binding refuses padding rather than ignoring it.
+        #
+        # @parameter string [String] what a server sent.
+        # @returns [String] the same, with any padding taken off.
+        def self.unpadded(string)
+          string.to_s.delete("=")
+        end
+
+        private
+
+        # What goes inside the ciphertext, which is the session and what is claimed about its sender.
+        #
+        # @parameter session [Hash] the session.
+        # @returns [Hash] the fields the specification names.
+        def backed_up(session)
+          {
+            algorithm: session[:algorithm] || Machine::MEGOLM,
+            forwarding_curve25519_key_chain: session[:forwarding_curve25519_key_chain] || [],
+            sender_key: session[:sender_key],
+            sender_claimed_keys: session[:sender_claimed_keys] || {},
+            session_key: session[:session_key],
+            shared_history: session[:shared_history] || false,
+          }
+        end
+
+        # Encrypt to this backup, with a key pair which the binding uses once and throws away.
+        #
+        # @parameter plaintext [String] the JSON to seal.
+        # @returns [Hash] the ciphertext, the code, and the public half of the ephemeral key.
+        def sealed(plaintext)
+          ciphertext, mac, ephemeral = Vodozemac::PkEncryption.from_base64(@public_key).encrypt(plaintext)
+
+          {ciphertext: ciphertext, mac: mac, ephemeral: ephemeral}
+        end
+
+        # The code over the ciphertext authenticates nothing, which is libolm's bug and the specification's warning.
+        #
+        # So a message which fails it was written to another key, rather than tampered with. See MSC4048 for the version which fixes it.
+        #
+        # @parameter session_data [Hash] the three parts the server holds.
+        # @returns [String | nil] the plaintext, or nil when this is not the key it was written to.
+        def opened(session_data)
+          @decryption.decrypt(
+            self.class.unpadded(session_data[:ciphertext]),
+            self.class.unpadded(session_data[:mac]),
+            self.class.unpadded(session_data[:ephemeral]),
+          )
+        rescue RuntimeError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "json"
+
+module Async
+  module Matrix
+    module E2EE
+      # The form an object is signed and hashed in.
+      module CanonicalJSON
+        # The keys which are never signed, because they are added after signing.
+        UNSIGNED = [:signatures, :unsigned, "signatures", "unsigned"].freeze
+
+        # The integers the specification allows, which are those an IEEE double represents exactly.
+        INTEGERS = (-(2**53) + 1)..((2**53) - 1)
+
+        class << self
+          # Keys are sorted, there is no insignificant whitespace, and a float cannot be represented.
+          #
+          # @parameter object [Object] the object to render.
+          # @returns [String] its canonical form.
+          def dump(object)
+            ::JSON.generate(self.canonical(object))
+          end
+
+          # The object as it is signed, without the fields which carry the signature itself.
+          #
+          # @parameter object [Hash] the object to sign.
+          # @returns [String] its canonical form.
+          def for_signing(object)
+            self.dump(object.reject{|key, _| UNSIGNED.include?(key)})
+          end
+
+          # @parameter object [Object] the object to convert.
+          # @returns [Object] the same value, as something the grammar allows.
+          # @raises [ArgumentError] if the grammar has no way to write it.
+          def canonical(object)
+            case object
+            when Hash
+              self.members(object)
+            when Array
+              object.map{|value| self.canonical(value)}
+            when Integer
+              self.integer(object)
+            when Float
+              self.integer(self.whole(object))
+            when Symbol
+              object.to_s
+            when String, true, false, nil
+              object
+            else
+              raise ArgumentError, "Canonical JSON cannot represent #{object.class}!"
+            end
+          end
+
+          # The members of an object, sorted by name, which is what gives one object one encoding.
+          #
+          # @parameter object [Hash] the object whose members to sort.
+          # @returns [Hash] the members, in order.
+          # @raises [ArgumentError] if two keys are the same name.
+          def members(object)
+            object.sort_by{|key, _| self.name(key)}.each_with_object({}) do |(key, value), sorted|
+              name = self.name(key)
+
+              if sorted.key?(name)
+                raise ArgumentError, "Canonical JSON has one member named #{name.inspect}, not two!"
+              end
+
+              sorted[name] = self.canonical(value)
+            end
+          end
+
+          # @parameter key [Object] the key to name.
+          # @returns [String] the name it is written as.
+          # @raises [ArgumentError] if it is not a name.
+          def name(key)
+            case key
+            when String
+              key
+            when Symbol
+              key.to_s
+            else
+              raise ArgumentError, "A Canonical JSON name is a string, not #{key.class}!"
+            end
+          end
+
+          # @parameter value [Integer] the number to write.
+          # @returns [Integer] the same number.
+          # @raises [ArgumentError] if it is outside the range the specification allows.
+          def integer(value)
+            unless INTEGERS.cover?(value)
+              raise ArgumentError, "Canonical JSON cannot represent #{value}, which is outside #{INTEGERS}!"
+            end
+
+            value
+          end
+
+          # The integer a float carries, because JSON writes one with an exponent and a parser reads a float.
+          #
+          # @parameter value [Float] the number to read.
+          # @returns [Integer] the integer it is.
+          # @raises [ArgumentError] if it is not one.
+          def whole(value)
+            unless value.finite? and value.to_i == value
+              raise ArgumentError, "Canonical JSON cannot represent the float #{value}!"
+            end
+
+            value.to_i
+          end
+        end
+      end
+    end
+  end
+end