async-matrix 3.0.0-x86_64-linux → 3.0.1-x86_64-linux

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

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "openssl"
+
+module Async
+  module Matrix
+    module E2EE
+      # The key every stored crypto object in this namespace is encrypted with
+      # at rest.
+      #
+      # A "pickle" is vodozemac's serialised snapshot of an Account or a
+      # session -- the only way ratchet state survives a restart:
+      #
+      #   blob    = session.pickle(pickle_key.to_s)
+      #   session = E2EE::Session.from_pickle(blob, pickle_key.to_s)
+      #
+      # This key is what stops a copy of the database being a plaintext dump of
+      # the device's identity keys and every room key it holds.
+      #
+      # IT MUST NEVER CHANGE. Rotate or lose it and every pickle is
+      # undecryptable: the Account goes, every Megolm session goes, and all
+      # encrypted history becomes permanently unreadable unless server-side key
+      # backup happens to hold copies. There is no recovery path and no warning
+      # -- the symptom is simply that nothing decrypts any more.
+      #
+      # SO THE SECRET IS THE APPLICATION'S, not this library's. #derive exists
+      # because the shape requirement below catches everyone, not because a gem
+      # should own your key material.
+      class PickleKey
+        # vodozemac wants exactly 32 bytes AND rejects a binary string: hand it
+        # raw KDF output and it fails with "expected utf-8, got ASCII-8BIT".
+        LENGTH = 32
+
+        # 24 bytes of entropy base64s to exactly 32 ASCII characters, which
+        # satisfies both constraints at once -- 32 bytes, valid UTF-8, 192 bits.
+        # That arithmetic is the whole reason this class exists.
+        DERIVED_BYTES = 24
+
+        DEFAULT_INFO = "matrix device pickle"
+
+        class Error < StandardError; end
+
+        # Derive a key from an application secret.
+        #
+        # Deterministic: the same secret always yields the same key, which is
+        # what makes it survive a restart without being written down anywhere.
+        # Use a different `info` to derive unrelated keys from one secret.
+        def self.derive(secret, info: DEFAULT_INFO, salt: "")
+          if secret.nil? || secret.to_s.empty?
+            raise Error, "cannot derive a pickle key from an empty secret"
+          end
+
+          new(
+            [
+              OpenSSL::KDF.hkdf(
+                secret.to_s,
+                salt:   salt,
+                info:   info,
+                length: DERIVED_BYTES,
+                hash:   "SHA256",
+              ),
+            ].pack("m0"),
+          )
+        end
+
+        # Wrap a key you already have -- one derived elsewhere, or read from a
+        # secret store.
+        #
+        # @raises [Error] unless it is exactly 32 bytes and valid UTF-8, because
+        #   vodozemac refuses anything else and the failure it gives is obscure.
+        def initialize(value)
+          @value = value.to_s.dup.force_encoding(Encoding::UTF_8)
+
+          unless @value.bytesize == LENGTH
+            raise Error, "a pickle key must be exactly #{LENGTH} bytes, got #{@value.bytesize}"
+          end
+
+          unless @value.valid_encoding?
+            raise Error, "a pickle key must be valid UTF-8; vodozemac rejects binary strings"
+          end
+
+          @value.freeze
+        end
+
+        # The key as vodozemac wants it.
+        def to_s = @value
+
+        # Never the key itself: a pickle key in a log or an exception message is
+        # as bad as one in a repository.
+        def inspect = "#<#{self.class.name} [redacted]>"
+
+        def ==(other) = other.is_a?(self.class) && to_s == other.to_s
+      end
+    end
+  end
+end
+
+__END__
+  describe "Async::Matrix::E2EE::PickleKey" do
+    K = Async::Matrix::E2EE::PickleKey
+
+    # The arithmetic this class exists for: 24 bytes of entropy base64s to
+    # exactly the 32 ASCII characters vodozemac demands.
+    it "derives a key of exactly 32 bytes, valid UTF-8" do
+      key = K.derive("an application secret")
+
+      key.to_s.bytesize.should == 32
+      key.to_s.encoding.should == Encoding::UTF_8
+      key.to_s.valid_encoding?.should == true
+    end
+
+    # Deterministic, which is what lets it survive a restart without being
+    # written down.
+    it "derives the same key from the same secret" do
+      K.derive("secret").should == K.derive("secret")
+    end
+
+    it "derives different keys from different secrets" do
+      K.derive("one").should.not == K.derive("two")
+    end
+
+    # One secret, several unrelated keys.
+    it "separates keys by info string" do
+      K.derive("secret", info: "a").should.not == K.derive("secret", info: "b")
+    end
+
+    it "refuses an empty secret" do
+      lambda { K.derive("") }.should.raise(Async::Matrix::E2EE::PickleKey::Error)
+      lambda { K.derive(nil) }.should.raise(Async::Matrix::E2EE::PickleKey::Error)
+    end
+
+    # ── Wrapping an existing key ──────────────────────────────────────────────
+
+    it "accepts a 32-byte key" do
+      K.new("k" * 32).to_s.should == "k" * 32
+    end
+
+    # The error vodozemac gives for the wrong length is obscure, so this one is
+    # not.
+    it "refuses a key of the wrong length" do
+      lambda { K.new("short") }.should.raise(Async::Matrix::E2EE::PickleKey::Error)
+      lambda { K.new("k" * 33) }.should.raise(Async::Matrix::E2EE::PickleKey::Error)
+    end
+
+    # "expected utf-8, got ASCII-8BIT" is what raw KDF output gets you.
+    it "refuses bytes that are not valid UTF-8" do
+      lambda { K.new("\xFF\xFE".b + ("k" * 30)) }
+        .should.raise(Async::Matrix::E2EE::PickleKey::Error)
+    end
+
+    it "accepts binary-encoded bytes that happen to be valid UTF-8" do
+      K.new(("k" * 32).b).to_s.encoding.should == Encoding::UTF_8
+    end
+
+    # ── Not leaking ───────────────────────────────────────────────────────────
+
+    # A pickle key in a log is as bad as one in a repository.
+    it "never shows the key in inspect" do
+      key = K.derive("secret")
+
+      key.inspect.should.not.be.include? key.to_s
+      key.inspect.should.be.include? "redacted"
+    end
+
+    it "is frozen, so nothing can mutate it in place" do
+      K.derive("secret").to_s.frozen?.should == true
+    end
+
+    # It belongs beside the objects it encrypts, which is the point of the
+    # namespace: every one of these answers #pickle.
+    it "sits with the classes whose pickles it protects" do
+      [
+        Async::Matrix::E2EE::Account,
+        Async::Matrix::E2EE::Session,
+        Async::Matrix::E2EE::GroupSession,
+        Async::Matrix::E2EE::InboundGroupSession,
+      ].each { |klass| klass.instance_methods.should.be.include? :pickle }
+    end
+  end

data/lib/async/matrix/error.rb

@@ -3,17 +3,17 @@
 # Released under the Apache License, Version 2.0.
 # Copyright, 2026, by General Intelligence Systems.
 
+require_relative "../../protocol/matrix/error"
+
 module Async
   module Matrix
-    class Error < StandardError
-      attr_reader :errcode, :status
-
-      def initialize(errcode, message, status: nil)
-        @errcode = errcode
-        @status = status
-        super(message)
-      end
-    end
+    # One error base for the whole gem. See Protocol::Matrix::Error.
+    #
+    # A CONSTANT, NOT A SUBCLASS: the subclasses below it are declared as
+    # `class AuthError < Error`, which resolves this constant at load time, so
+    # they inherit the real class and `rescue Async::Matrix::Error` catches
+    # everything -- transport failures and format failures together.
+    Error = ::Protocol::Matrix::Error
   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.0"
-  end
+	module Matrix
+    VERSION = "3.0.1"
+	end
 end

data/lib/async/matrix.rb

@@ -10,6 +10,22 @@ module Async
   end
 end
 
+# The message FORMAT layer: events, content, schemas, encrypted messages. It
+# does no IO, so it lives beside the other protocol-* libraries rather than
+# under the gem that opens sockets. Required FIRST, because the aliases below
+# and the client both depend on it.
+require "protocol/matrix"
+
+module Async
+  module Matrix
+    # Where these constants used to live. Kept as aliases so code written
+    # against 3.0 keeps working; new code should name Protocol::Matrix directly.
+    Event = ::Protocol::Matrix::Event
+    Content = ::Protocol::Matrix::Content
+    Schema = ::Protocol::Matrix::Schema
+  end
+end
+
 Dir.glob("#{__dir__}/matrix/**/*.rb").sort.each do |path|
   require path
 end

data/lib/protocol/matrix/canonical_json.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "json"
+
+require_relative "error"
+
+module Protocol
+  module Matrix
+    # Canonical JSON: "the shortest UTF-8 JSON encoding with dictionary keys
+    # lexicographically sorted by Unicode codepoint."
+    #
+    # https://spec.matrix.org/latest/appendices/#canonical-json
+    #
+    # This is not a formatting preference. A signature is computed over these
+    # exact bytes, so any disagreement about whitespace, key order or number
+    # formatting produces a signature every other implementation rejects — and
+    # the failure appears at the far end, as somebody else's device refusing our
+    # keys, with nothing locally to see.
+    #
+    # The rules, each of which is enforced below:
+    #
+    #   * dictionary keys sorted by Unicode codepoint
+    #   * no insignificant whitespace (separators are "," and ":")
+    #   * code-points outside ASCII encoded as UTF-8, NOT as \u escapes
+    #   * integers only, in [-(2**53)+1, (2**53)-1], no exponents, no decimals
+    #   * "Float values are not permitted by this encoding"
+    #   * negative zero MUST NOT appear
+    module CanonicalJson
+      MAXIMUM_INTEGER = (2**53) - 1
+      MINIMUM_INTEGER = -(2**53) + 1
+
+      # The two keys a signature never covers: "The `unsigned` object and the
+      # `signatures` object are not covered by the signature."
+      EXCLUDED_FROM_SIGNATURE = %w[signatures unsigned].freeze
+
+      class Error < Protocol::Matrix::Error; end
+
+      # @returns [String] the canonical encoding of +value+.
+      def self.encode(value)
+        JSON.generate(canonicalize(value))
+      end
+
+      # Sort, stringify and check, recursively.
+      #
+      # Ruby's String#<=> compares bytes, and UTF-8 byte order is codepoint
+      # order, so a plain sort IS the codepoint sort the spec asks for. That
+      # equivalence is the whole reason this is three lines rather than a
+      # custom comparator.
+      #
+      # Keys are stringified BEFORE sorting, not read back out of the hash
+      # afterwards: `h[k] || h[k.to_sym]` would mishandle a stored `false`.
+      def self.canonicalize(value)
+        case value
+        when Hash
+          value.to_h { |key, nested| [key.to_s, canonicalize(nested)] }.sort.to_h
+        when Array
+          value.map { |nested| canonicalize(nested) }
+        when Float
+          raise Error, "float values are not permitted by canonical JSON: #{value.inspect}"
+        when Integer
+          check_integer(value)
+        when Symbol
+          value.to_s
+        else
+          value
+        end
+      end
+
+      def self.check_integer(value)
+        if value > MAXIMUM_INTEGER || value < MINIMUM_INTEGER
+          raise Error,
+            "integer out of canonical JSON range [#{MINIMUM_INTEGER}, #{MAXIMUM_INTEGER}]: #{value}"
+        end
+
+        value
+      end
+
+      # The object as it is signed: everything except the two keys a signature
+      # does not cover. Returns a copy; the original is untouched, because the
+      # caller still needs its signatures.
+      def self.signable(object)
+        object.reject { |key, _| EXCLUDED_FROM_SIGNATURE.include?(key.to_s) }
+      end
+
+      # The exact bytes a signature is computed over.
+      def self.signable_bytes(object)
+        encode(signable(object))
+      end
+    end
+  end
+end
+
+__END__
+  describe "Protocol::Matrix::CanonicalJson" do
+    def encode(value) = Protocol::Matrix::CanonicalJson.encode(value)
+
+    # The worked examples from https://spec.matrix.org/latest/appendices/#canonical-json
+    it "matches the spec's empty object example" do
+      encode({}).should == "{}"
+    end
+
+    it "matches the spec's key ordering example" do
+      encode({"one" => 1, "two" => "Two"}).should == '{"one":1,"two":"Two"}'
+      encode({"b" => "2", "a" => "1"}).should == '{"a":"1","b":"2"}'
+    end
+
+    it "matches the spec's nested example" do
+      encode({"auth" => {"success" => true, "mxid" => "@john.doe:example.com"}})
+        .should == '{"auth":{"mxid":"@john.doe:example.com","success":true}}'
+    end
+
+    # "Encode code-points outside of ASCII as UTF-8 rather than \u escapes."
+    it "emits non-ASCII as UTF-8 rather than escapes" do
+      encode({"a" => "日本語"}).should == '{"a":"日本語"}'
+    end
+
+    it "keeps an escape the JSON grammar requires" do
+      encode({"a" => "quote\"and\\slash"}).should == '{"a":"quote\"and\\\\slash"}'
+    end
+
+    # Keys sort by Unicode codepoint, which for UTF-8 is byte order.
+    it "sorts keys by codepoint, not by locale or length" do
+      encode({"Z" => 1, "a" => 2, "A" => 3, "z" => 4})
+        .should == '{"A":3,"Z":1,"a":2,"z":4}'
+      encode({"é" => 1, "z" => 2}).should == '{"z":2,"é":1}'
+    end
+
+    it "sorts nested objects too" do
+      encode({"b" => {"d" => 1, "c" => 2}, "a" => 3})
+        .should == '{"a":3,"b":{"c":2,"d":1}}'
+    end
+
+    # Arrays are ordered data: their order is the sender's, not ours to sort.
+    it "leaves array order alone" do
+      encode({"a" => [3, 1, 2]}).should == '{"a":[3,1,2]}'
+    end
+
+    it "has no insignificant whitespace anywhere" do
+      encoded = encode({"a" => {"b" => [1, 2]}, "c" => "d"})
+
+      encoded.should == '{"a":{"b":[1,2]},"c":"d"}'
+      encoded.include?(" ").should == false
+    end
+
+    it "stringifies symbol keys and values" do
+      encode({a: :b}).should == '{"a":"b"}'
+    end
+
+    it "encodes null, true and false" do
+      encode({"a" => nil, "b" => true, "c" => false}).should == '{"a":null,"b":true,"c":false}'
+    end
+
+    # "Float values are not permitted by this encoding."
+    it "refuses floats, including ones that look like integers" do
+      lambda { encode({"a" => 1.5}) }.should.raise(Protocol::Matrix::CanonicalJson::Error)
+      lambda { encode({"a" => 1.0}) }.should.raise(Protocol::Matrix::CanonicalJson::Error)
+      lambda { encode({"a" => [1.0]}) }.should.raise(Protocol::Matrix::CanonicalJson::Error)
+    end
+
+    # "Numbers in the JSON must be integers in the range [-(2**53)+1, (2**53)-1]"
+    it "accepts the integer range boundaries" do
+      encode({"a" => (2**53) - 1}).should == '{"a":9007199254740991}'
+      encode({"a" => -(2**53) + 1}).should == '{"a":-9007199254740991}'
+    end
+
+    it "refuses integers outside the range" do
+      lambda { encode({"a" => 2**53}) }.should.raise(Protocol::Matrix::CanonicalJson::Error)
+      lambda { encode({"a" => -(2**53)}) }.should.raise(Protocol::Matrix::CanonicalJson::Error)
+    end
+
+    # ── What a signature covers ───────────────────────────────────────────────
+
+    # "The `unsigned` object and the `signatures` object are not covered by the
+    # signature."
+    it "excludes signatures and unsigned from the signable form" do
+      object = {
+        "a" => 1,
+        "signatures" => {"@alice:example.com" => {"ed25519:DEV" => "sig"}},
+        "unsigned" => {"age" => 100},
+      }
+
+      Protocol::Matrix::CanonicalJson.signable(object).should == {"a" => 1}
+      Protocol::Matrix::CanonicalJson.signable_bytes(object).should == '{"a":1}'
+    end
+
+    it "leaves the original object untouched" do
+      object = {"a" => 1, "signatures" => {"x" => "y"}}
+      Protocol::Matrix::CanonicalJson.signable(object)
+
+      object.key?("signatures").should == true
+    end
+
+    it "excludes them whether the keys are strings or symbols" do
+      Protocol::Matrix::CanonicalJson.signable({:a => 1, :signatures => {}, :unsigned => {}})
+        .should == {:a => 1}
+    end
+  end

data/lib/{async → protocol}/matrix/content.rb

@@ -3,7 +3,7 @@
 # Released under the Apache License, Version 2.0.
 # Copyright, 2026, by General Intelligence Systems.
 
-module Async
+module Protocol
   module Matrix
     # Wraps the content object of a Matrix event, providing typed access to
     # schema-defined properties via method_missing.
@@ -54,9 +54,9 @@ module Async
 end
 
 __END__
-  describe "Async::Matrix::Content" do
+  describe "Protocol::Matrix::Content" do
     it "parses msgtype, body, and membership" do
-      content = Async::Matrix::Content.new({
+      content = Protocol::Matrix::Content.new({
         "msgtype" => "m.text",
         "body" => "hello",
         "membership" => "join"
@@ -67,19 +67,19 @@ __END__
     end
 
     it "handles missing fields gracefully" do
-      content = Async::Matrix::Content.new({})
+      content = Protocol::Matrix::Content.new({})
       content.msgtype.should.be.nil
       content.body.should.be.nil
       content.membership.should.be.nil
     end
 
     it "provides hash access via []" do
-      content = Async::Matrix::Content.new({"custom_field" => "value"})
+      content = Protocol::Matrix::Content.new({"custom_field" => "value"})
       content["custom_field"].should == "value"
     end
 
     it "provides dynamic access via method_missing" do
-      content = Async::Matrix::Content.new({
+      content = Protocol::Matrix::Content.new({
         "avatar_url" => "mxc://example.org/abc",
         "displayname" => "Alice"
       })
@@ -88,18 +88,18 @@ __END__
     end
 
     it "returns nil for unknown fields via method_missing" do
-      content = Async::Matrix::Content.new({})
+      content = Protocol::Matrix::Content.new({})
       content.nonexistent.should.be.nil
     end
 
     it "returns the raw hash via to_h" do
       data = {"msgtype" => "m.text", "body" => "hi"}
-      content = Async::Matrix::Content.new(data)
+      content = Protocol::Matrix::Content.new(data)
       content.to_h.should == data
     end
 
     it "responds to keys present in the data" do
-      content = Async::Matrix::Content.new({"avatar_url" => "mxc://x/y"})
+      content = Protocol::Matrix::Content.new({"avatar_url" => "mxc://x/y"})
       content.respond_to?(:avatar_url).should == true
       content.respond_to?(:nonexistent).should == false
     end