async-matrix 3.0.1 → 4.0.0

data/lib/protocol/matrix/error.rb

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

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

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