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

data/lib/protocol/matrix/error.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Protocol
+  module Matrix
+    # THE base error for this gem, in both namespaces: Async::Matrix::Error is a
+    # constant pointing here, so `rescue Async::Matrix::Error` catches a format
+    # failure and a transport failure alike, and every subclass declared as
+    # `class AuthError < Error` inside Async::Matrix resolves to this class.
+    #
+    # It lives under Protocol:: because an error about bytes should not require
+    # there to have been a connection -- but the two namespaces ship in one gem,
+    # so there is no dependency direction to defend and no reason for consumers
+    # to need two rescues.
+    class Error < StandardError
+      # The Matrix errcode this maps to, when it maps to one. M_BAD_JSON and
+      # friends are spec vocabulary, so a format error is entitled to carry one;
+      # most carry none.
+      attr_reader :errcode
+
+      # The HTTP status, for the failures that came from one.
+      attr_reader :status
+
+      # TWO CALLING CONVENTIONS, deliberately, because this class serves both
+      # layers:
+      #
+      #   Error.new("M_UNKNOWN_TOKEN", "token expired", status: 401)
+      #   raise MalformedError, "megolm ciphertext must be a string"
+      #
+      # The first is how the transport has always raised, and changing it would
+      # break every caller. The second is what `raise Klass, "message"` does,
+      # which is how a format error reads naturally. A lone argument is the
+      # message; two are errcode then message.
+      def initialize(errcode = nil, message = nil, status: nil)
+        @status = status
+
+        if message.nil?
+          @errcode = nil
+          super(errcode)
+        else
+          @errcode = errcode
+          super(message)
+        end
+      end
+    end
+  end
+end

data/lib/protocol/matrix/event.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+module Protocol
+  module Matrix
+    # Represents a Matrix event, however it arrived — a /sync response, an
+    # application service transaction, or a hash you built yourself.
+    #
+    # Provides typed accessors for all envelope fields plus schema-driven
+    # validation using the official Matrix spec YAML schemas.
+    #
+    #   event = Event.new(raw_hash)
+    #   event.type           # => "m.room.message"
+    #   event.sender         # => "@alice:example.org"
+    #   event.content.body   # => "hello"
+    #   event.valid?         # => true
+    #   event.valid!         # => true (or raises Schema::ValidationError)
+    #
+    class Event
+      attr_reader :type,
+        :sender,
+        :room_id,
+        :state_key,
+        :content,
+        :event_id,
+        :origin_server_ts,
+        :unsigned,
+        :raw
+
+      def initialize(data)
+        @raw       = data
+        @type      = data["type"]
+        @sender    = data["sender"]
+        @room_id   = data["room_id"]
+        @state_key = data["state_key"]
+        @event_id  = data["event_id"]
+        @origin_server_ts = data["origin_server_ts"]
+        @unsigned  = data["unsigned"]
+        @content   = Content.new(data["content"] || {})
+      end
+
+      # The JSONSchemer::Schema for this event's type, or nil if unknown.
+      def schema = Schema[@type]
+
+      # Validate this event against its schema.
+      # Returns true if valid or if no schema exists (lenient).
+      def valid? = Schema.valid?(@raw)
+
+      # Validate this event against its schema.
+      # Raises Schema::ValidationError with detailed errors on failure.
+      # Returns true if valid or if no schema exists.
+      def valid!
+        errors = Schema.validate(@raw)
+
+        unless errors.empty?
+          raise Schema::ValidationError.new(
+            errors,
+            event_type: @type,
+            event_id:   @event_id,
+          )
+        end
+
+        true
+      end
+
+      # Content property names defined by the schema for this event type.
+      # @return [Array<String>]
+      def content_properties = Schema.content_properties(@type)
+
+      # Is this a state event? (has a state_key)
+      def state_event? = !@state_key.nil?
+
+      # ── The shape MessageBatch yields ───────────────────────────────────────
+      #
+      # A batch mixes plaintext and encrypted events, and a consumer should not
+      # have to ask which class it is holding before reading #type or #content.
+      # So both answer the same three questions, and for a plaintext event the
+      # answers are the trivial ones: it was never encrypted, so there is
+      # nothing left to decrypt.
+
+      def encrypted? = false
+      def decrypted? = true
+    end
+  end
+end
+
+__END__
+  describe "Protocol::Matrix::Event" do
+    it "parses all event fields" do
+      event = Protocol::Matrix::Event.new({
+        "type" => "m.room.message",
+        "sender" => "@alice:example.com",
+        "room_id" => "!abc:example.com",
+        "state_key" => "",
+        "event_id" => "$evt1",
+        "origin_server_ts" => 1234567890,
+        "unsigned" => {"age" => 1000},
+        "content" => {"msgtype" => "m.text", "body" => "hi"}
+      })
+      event.type.should == "m.room.message"
+      event.sender.should == "@alice:example.com"
+      event.room_id.should == "!abc:example.com"
+      event.state_key.should == ""
+      event.event_id.should == "$evt1"
+      event.origin_server_ts.should == 1234567890
+      event.unsigned.should == {"age" => 1000}
+      event.content.should.be.kind_of Protocol::Matrix::Content
+      event.content.body.should == "hi"
+    end
+
+    it "defaults content to empty Content when missing" do
+      event = Protocol::Matrix::Event.new({"type" => "m.room.message"})
+      event.content.should.be.kind_of Protocol::Matrix::Content
+      event.content.body.should.be.nil
+    end
+
+    it "exposes the raw hash" do
+      data = {"type" => "m.room.message", "content" => {"body" => "hi", "msgtype" => "m.text"}}
+      event = Protocol::Matrix::Event.new(data)
+      event.raw.should.equal data
+    end
+
+    it "detects state events" do
+      state = Protocol::Matrix::Event.new({"type" => "m.room.member", "state_key" => "@a:b"})
+      state.state_event?.should == true
+
+      msg = Protocol::Matrix::Event.new({"type" => "m.room.message"})
+      msg.state_event?.should == false
+    end
+
+    it "returns the schema for known event types" do
+      event = Protocol::Matrix::Event.new({"type" => "m.room.message", "content" => {}})
+      event.schema.should.not.be.nil
+      event.schema.should.be.kind_of JSONSchemer::Schema
+    end
+
+    it "returns nil schema for unknown event types" do
+      event = Protocol::Matrix::Event.new({"type" => "m.custom.event", "content" => {}})
+      event.schema.should.be.nil
+    end
+
+    it "validates a correct event" do
+      event = Protocol::Matrix::Event.new({
+        "type" => "m.room.message",
+        "content" => {"msgtype" => "m.text", "body" => "hello"},
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      })
+      event.valid?.should == true
+      event.valid!.should == true
+    end
+
+    it "rejects an invalid event" do
+      event = Protocol::Matrix::Event.new({
+        "type" => "m.room.message",
+        "content" => {"msgtype" => "m.text"},
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      })
+      event.valid?.should == false
+    end
+
+    it "raises ValidationError from valid!" do
+      event = Protocol::Matrix::Event.new({
+        "type" => "m.room.member",
+        "content" => {"membership" => "invalid_state"},
+        "state_key" => "@alice:example.org",
+        "event_id" => "$abc123",
+        "sender" => "@alice:example.org",
+        "origin_server_ts" => 1234567890,
+        "room_id" => "!room:example.org"
+      })
+      begin
+        event.valid!
+        raise "should have raised"
+      rescue Protocol::Matrix::Schema::ValidationError => e
+        e.message.should.include "m.room.member"
+        e.message.should.include "$abc123"
+        e.errors.should.not.be.empty
+      end
+    end
+
+    it "is lenient with unknown event types" do
+      event = Protocol::Matrix::Event.new({
+        "type" => "com.custom.event",
+        "content" => {"anything" => "goes"},
+        "event_id" => "$x",
+        "sender" => "@a:b"
+      })
+      event.valid?.should == true
+      event.valid!.should == true
+    end
+
+    it "returns content properties for known types" do
+      event = Protocol::Matrix::Event.new({
+        "type" => "m.room.member",
+        "content" => {"membership" => "join"}
+      })
+      props = event.content_properties
+      props.should.include "membership"
+    end
+  end

data/lib/protocol/matrix/key_backup.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "json"
+require "openssl"
+
+require_relative "error"
+require_relative "secret_storage"
+
+module Protocol
+  module Matrix
+    # Server-side key backup: `m.megolm_backup.v1.curve25519-aes-sha2`.
+    #
+    # THIS IS THE ONLY WAY TO READ HISTORY THAT PREDATES A DEVICE. A device is
+    # only ever sent `m.room_key` for messages encrypted while it existed and
+    # was known to the sender; everything older stays ciphertext forever. Key
+    # backup is the account-wide escrow that fixes it: every client uploads its
+    # room keys encrypted to a public key whose private half lives in 4S behind
+    # the user's recovery key.
+    #
+    #   recovery key ─▶ 4S storage key ─▶ m.megolm_backup.v1 (the backup PRIVATE key)
+    #                                                │
+    #   GET /room_keys/keys ─▶ per-session blobs ────┘ decrypt (X25519 + AES-CBC)
+    #                                                │
+    #                                                ▼
+    #                            an exported session key, importable as inbound
+    #
+    # Implemented on OpenSSL rather than through vodozemac, whose equivalent
+    # sits behind an `insecure-pk-encryption` feature flag. That label is about
+    # the SCHEME -- it does not authenticate the ciphertext's sender -- which is
+    # a property of the Matrix format we must interoperate with either way.
+    module KeyBackup
+      ALGORITHM = "m.megolm_backup.v1.curve25519-aes-sha2"
+
+      # "a salt of 32 bytes of 0, and with the empty string as the info"
+      ZERO_SALT = SecretStorage::ZERO_SALT
+
+      # "The first 8 bytes of the resulting MAC"
+      MAC_LENGTH = 8
+
+      # 80 bytes: "The first 32 bytes are used as the AES key, the next 32 bytes
+      # are used as the MAC key, and the last 16 bytes are used as the AES
+      # initialization vector."
+      DERIVED_LENGTH = 80
+
+      class Error < Protocol::Matrix::Error; end
+      class MacError < Error; end
+
+      # Decrypt one backed-up session blob to its BackedUpSessionData.
+      #
+      # @parameter private_key [String] the raw 32-byte backup private key, out
+      #   of 4S.
+      # @parameter session_data [Hash] the blob's `ephemeral`, `ciphertext`, `mac`.
+      # @returns [Hash | Nil] the session data, or nil when the blob cannot be
+      #   read at all (missing or empty fields).
+      # @raises [MacError] when the MAC does not verify.
+      #
+      # NIL RATHER THAN RAISING for an unreadable blob: a mature backup
+      # routinely contains keys written by clients with slightly different
+      # habits, and one bad entry must not abandon the thousands after it.
+      def self.decrypt_session(private_key, session_data)
+        if session_data.nil?
+          nil
+        else
+          ephemeral = SecretStorage.decode64(session_data["ephemeral"].to_s)
+          ciphertext = SecretStorage.decode64(session_data["ciphertext"].to_s)
+
+          if ephemeral.empty? || ciphertext.empty?
+            nil
+          else
+            decrypt_blob(
+              private_key,
+              ephemeral,
+              ciphertext,
+              session_data["mac"],
+            )
+          end
+        end
+      end
+
+      def self.decrypt_blob(private_key, ephemeral, ciphertext, mac)
+        aes_key, mac_key, iv = subkeys(private_key, ephemeral)
+
+        unless SecretStorage.mac_equal?(expected_mac(mac_key), mac)
+          raise MacError, "backed-up session failed its MAC -- wrong backup key?"
+        end
+
+        cipher = OpenSSL::Cipher.new("aes-256-cbc")
+        cipher.decrypt
+        cipher.key = aes_key
+        cipher.iv = iv
+
+        parse(cipher.update(ciphertext) + cipher.final)
+      rescue OpenSSL::OpenSSLError
+        nil
+      end
+
+      # THE MAC IS OVER AN EMPTY STRING, and that is not a mistake here.
+      #
+      # The spec's step 5 says to "pass an empty string through HMAC-SHA-256
+      # using the MAC key", with a warning attached: "Step 5 was intended to
+      # pass the raw encrypted data, but due to a bug in libolm, all
+      # implementations have since passed an empty string instead."
+      #
+      # So MACing the ciphertext -- the obvious reading, and what our previous
+      # implementation did -- rejects every blob any real client ever wrote. The
+      # consequence worth knowing is that this MAC proves only that we derived
+      # the same MAC key, i.e. that the ECDH matched: it is a key check, not an
+      # integrity check on the data. MSC4048 is the proposed fix.
+      def self.expected_mac(mac_key)
+        OpenSSL::HMAC.digest("SHA256", mac_key, "")[0, MAC_LENGTH]
+      end
+
+      # X25519 ECDH against the blob's ephemeral key, expanded to the three
+      # subkeys the scheme uses.
+      def self.subkeys(private_key, ephemeral)
+        shared = ecdh(private_key, ephemeral)
+        okm = OpenSSL::KDF.hkdf(
+          shared,
+          salt:   ZERO_SALT,
+          info:   "",
+          length: DERIVED_LENGTH,
+          hash:   "SHA256",
+        )
+
+        [okm[0, 32], okm[32, 32], okm[64, 16]]
+      end
+
+      def self.ecdh(private_key, peer_public_key)
+        OpenSSL::PKey.new_raw_private_key("X25519", private_key)
+          .derive(OpenSSL::PKey.new_raw_public_key("X25519", peer_public_key))
+      end
+
+      # The public half of a backup private key, unpadded base64 -- what the
+      # backup version's auth_data publishes.
+      def self.public_key_for(private_key)
+        SecretStorage.encode64_unpadded(
+          OpenSSL::PKey.new_raw_private_key("X25519", private_key).raw_public_key,
+        )
+      end
+
+      # Is this private key the one this backup version was encrypted to?
+      #
+      # Worth checking before walking thousands of blobs: the alternative is
+      # every single one failing its MAC, which looks like a corrupt backup
+      # rather than the wrong key.
+      def self.key_matches?(private_key, auth_data)
+        public_key = (auth_data || {})["public_key"]
+
+        if public_key.nil?
+          false
+        else
+          public_key.delete("=") == public_key_for(private_key)
+        end
+      end
+
+      def self.parse(plaintext)
+        JSON.parse(plaintext)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end
+
+__END__
+  describe "Protocol::Matrix::KeyBackup" do
+    B = Protocol::Matrix::KeyBackup
+
+    def backup_keypair
+      key = OpenSSL::PKey.generate_key("X25519")
+      [key.raw_private_key, key.raw_public_key]
+    end
+
+    def session_payload
+      {
+        "algorithm" => "m.megolm.v1.aes-sha2",
+        "forwarding_curve25519_key_chain" => [],
+        "sender_key" => "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
+        "sender_claimed_keys" => {"ed25519" => "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y"},
+        "session_key" => "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf",
+      }
+    end
+
+    # Back a session up by following the spec's own five steps, so these specs
+    # are a real round trip. Step 5 is the one that matters: the MAC is over an
+    # EMPTY STRING, which is what every real implementation does.
+    def back_up(public_key, payload, mac_over: :empty)
+      ephemeral = OpenSSL::PKey.generate_key("X25519")
+      shared = ephemeral.derive(OpenSSL::PKey.new_raw_public_key("X25519", public_key))
+      okm = OpenSSL::KDF.hkdf(shared, salt: B::ZERO_SALT, info: "", length: 80, hash: "SHA256")
+      aes_key, mac_key, iv = okm[0, 32], okm[32, 32], okm[64, 16]
+
+      cipher = OpenSSL::Cipher.new("aes-256-cbc")
+      cipher.encrypt
+      cipher.key = aes_key
+      cipher.iv = iv
+      ciphertext = cipher.update(JSON.generate(payload)) + cipher.final
+
+      mac_input = mac_over == :empty ? "" : ciphertext
+
+      {
+        "ephemeral" => Protocol::Matrix::SecretStorage.encode64(ephemeral.raw_public_key),
+        "ciphertext" => Protocol::Matrix::SecretStorage.encode64(ciphertext),
+        "mac" => Protocol::Matrix::SecretStorage.encode64(
+          OpenSSL::HMAC.digest("SHA256", mac_key, mac_input)[0, B::MAC_LENGTH],
+        ),
+      }
+    end
+
+    # ── Decrypting a blob ─────────────────────────────────────────────────────
+
+    it "decrypts a backed-up session" do
+      private_key, public_key = backup_keypair
+
+      B.decrypt_session(private_key, back_up(public_key, session_payload))
+        .should == session_payload
+    end
+
+    # The field that carries the sending device's ed25519 key, which is how a
+    # restored session can still be attributed to a device.
+    it "recovers sender_claimed_keys with the session" do
+      private_key, public_key = backup_keypair
+
+      B.decrypt_session(private_key, back_up(public_key, session_payload))["sender_claimed_keys"]
+        .should == {"ed25519" => "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y"}
+    end
+
+    # THE REGRESSION THAT MATTERED. The spec says step 5 MACs an empty string,
+    # with a warning that it "was intended to pass the raw encrypted data, but
+    # due to a bug in libolm, all implementations have since passed an empty
+    # string instead". MACing the ciphertext rejects every blob a real client
+    # ever wrote.
+    it "accepts the empty-string MAC every real client writes" do
+      private_key, public_key = backup_keypair
+
+      B.decrypt_session(private_key, back_up(public_key, session_payload, mac_over: :empty))
+        .should.not.be.nil
+    end
+
+    it "rejects a blob MACed over the ciphertext, which nothing produces" do
+      private_key, public_key = backup_keypair
+
+      lambda {
+        B.decrypt_session(private_key, back_up(public_key, session_payload, mac_over: :ciphertext))
+      }.should.raise(Protocol::Matrix::KeyBackup::MacError)
+    end
+
+    it "refuses a blob backed up to a different key" do
+      _private_key, public_key = backup_keypair
+      other_private, = backup_keypair
+
+      lambda {
+        B.decrypt_session(other_private, back_up(public_key, session_payload))
+      }.should.raise(Protocol::Matrix::KeyBackup::MacError)
+    end
+
+    # One unreadable entry must not abandon the thousands after it.
+    it "answers nil for a blob it cannot read at all" do
+      private_key, = backup_keypair
+
+      B.decrypt_session(private_key, nil).should.be.nil
+      B.decrypt_session(private_key, {}).should.be.nil
+      B.decrypt_session(private_key, {"ephemeral" => "", "ciphertext" => ""}).should.be.nil
+    end
+
+    it "answers nil when the plaintext is not JSON" do
+      private_key, public_key = backup_keypair
+      blob = back_up(public_key, session_payload)
+      # Same key, same MAC, but ciphertext that decrypts to rubbish.
+      ephemeral = Protocol::Matrix::SecretStorage.decode64(blob["ephemeral"])
+      aes_key, _mac_key, iv = B.subkeys(private_key, ephemeral)
+      cipher = OpenSSL::Cipher.new("aes-256-cbc")
+      cipher.encrypt
+      cipher.key = aes_key
+      cipher.iv = iv
+      blob["ciphertext"] = Protocol::Matrix::SecretStorage.encode64(cipher.update("not json") + cipher.final)
+
+      B.decrypt_session(private_key, blob).should.be.nil
+    end
+
+    # ── Subkeys ───────────────────────────────────────────────────────────────
+
+    # "The first 32 bytes are used as the AES key, the next 32 bytes are used as
+    # the MAC key, and the last 16 bytes are used as the AES initialization
+    # vector."
+    it "derives 80 bytes as an aes key, a mac key and an iv" do
+      private_key, = backup_keypair
+      _other_private, other_public = backup_keypair
+      aes_key, mac_key, iv = B.subkeys(private_key, other_public)
+
+      aes_key.bytesize.should == 32
+      mac_key.bytesize.should == 32
+      iv.bytesize.should == 16
+    end
+
+    # Both sides of an ECDH reach the same secret, which is what makes the
+    # scheme work at all.
+    it "agrees with the sender's ECDH" do
+      private_key, public_key = backup_keypair
+      ephemeral_private, ephemeral_public = backup_keypair
+
+      B.ecdh(private_key, ephemeral_public).should == B.ecdh(ephemeral_private, public_key)
+    end
+
+    # ── The backup version's public key ───────────────────────────────────────
+
+    it "derives the public half a backup version publishes" do
+      private_key, public_key = backup_keypair
+
+      B.public_key_for(private_key).should == Protocol::Matrix::SecretStorage.encode64(public_key).delete("=")
+    end
+
+    it "emits the public key unpadded" do
+      private_key, = backup_keypair
+
+      B.public_key_for(private_key).include?("=").should == false
+    end
+
+    # Worth checking before walking thousands of blobs: the alternative is every
+    # one failing its MAC, which looks like a corrupt backup rather than the
+    # wrong key.
+    it "recognises the key a backup version was made for" do
+      private_key, = backup_keypair
+      other_private, = backup_keypair
+      auth_data = {"public_key" => B.public_key_for(private_key)}
+
+      B.key_matches?(private_key, auth_data).should == true
+      B.key_matches?(other_private, auth_data).should == false
+    end
+
+    it "tolerates padding in the published public key" do
+      private_key, public_key = backup_keypair
+
+      B.key_matches?(private_key, {"public_key" => Protocol::Matrix::SecretStorage.encode64(public_key)})
+        .should == true
+    end
+
+    it "answers false for auth data with no public key" do
+      private_key, = backup_keypair
+
+      B.key_matches?(private_key, {}).should == false
+      B.key_matches?(private_key, nil).should == false
+    end
+  end