async-matrix 1.1.1 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1798ded13f8a49d533a6e38598e73cd7144255f5f4d1fb83f92cbf06e9d56f35
-  data.tar.gz: c8ce38d7134972f477c56bfb4afc1438cecfde8144c12be879d8c5fba47d51fa
+  metadata.gz: 2a0c3eee197effa06e2abe173a328734d5c0e2db5c033c26a24030813d7ad69b
+  data.tar.gz: 597a3fdae49b1fdf17584bdb181067c27f3fc6e2877e56ec4607f60bff242c06
 SHA512:
-  metadata.gz: d542389cafdfc0877d773bbae151687c041ca5d2a71742c5b133bd1596e9f1e3e024123c285162f73491c2cf0f48939a925c37788d341c900554b3526d696f42
-  data.tar.gz: 547149b7af5dd824d6f47d6640b53eb35801919037dc5c6fec4a23ab3b1a30229c925e8ca86ecee3f04260f75ddb06aa7b0f08fd83ce9efa25a8bb7dde7c72b1
+  metadata.gz: d596428929e71d223463ac9bd28f78941cd9ced8e6dde5ccb9450f9c5fd7e0e527ae2953c5592a6d3ffa93b7a5557f74935a58fddee6de687d466d7540c7b426
+  data.tar.gz: 87faa2828aba3103c88feb145a0b53bb1bbfb2f05adaa795e05f7020c6cc15aa1bc81b51a260e5485b986eb2d4196b18d82e954309cdbbae2b56a99a73c1bd12

data/ext/async_matrix_e2ee/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "async_matrix_e2ee"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+name = "async_matrix_e2ee"
+crate-type = ["cdylib"]
+
+[dependencies]
+# magnus 0.8 is required for Ruby 4.0 C-API compatibility (0.7 fails to compile
+# against Ruby 4.0: rb_fiber_raise pointer mutability + RTypedData.typed_flag).
+magnus = "0.8"
+
+# vodozemac 0.10.0 (2026-04-13), default features (libolm-compat).
+#
+# - 0.10 is the release that fixes the all-zero / non-contributory DH issue from
+#   Soatok's review (the proposed patch was deprecated `since = "0.10.0"`), so we
+#   pin >= 0.10 rather than 0.9.
+# - There is no `strict-signatures` feature in 0.10 (it existed pre-0.10; the
+#   related signature-verification hardening was resolved upstream).
+# - There is no `fuzzing` Cargo feature: vodozemac's MAC/signature bypass is
+#   gated behind `#[cfg(fuzzing)]`, only set by `cargo fuzz`
+#   (RUSTFLAGS=--cfg fuzzing). A normal `cargo build`/`rake compile` never
+#   enables it. Never build production artifacts with `cargo fuzz`.
+[dependencies.vodozemac]
+version = "0.10"

data/ext/async_matrix_e2ee/extconf.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+# Builds the Rust crate in this directory and produces async_matrix_e2ee.so.
+# The crate's #[magnus::init] defines the classes under Async::Matrix::E2EE.
+create_rust_makefile("async_matrix_e2ee")

data/ext/async_matrix_e2ee/src/lib.rs

@@ -0,0 +1,328 @@
+//! Ruby bindings for vodozemac (Matrix Olm/Megolm), via magnus.
+//!
+//! This is the Ruby analogue of matrix-nio/vodozemac-python (which uses PyO3).
+//! It exposes vodozemac's Account / Session (Olm) and GroupSession /
+//! InboundGroupSession (Megolm) under the `Async::Matrix::E2EE` module.
+//!
+//! The API is deliberately base64-string / integer centric rather than passing
+//! wrapped key objects around: Matrix moves keys and ciphertext as base64
+//! strings inside JSON, so a string API drops straight into the protocol layer
+//! and keeps the magnus surface small.
+
+use std::cell::RefCell;
+use std::collections::HashMap;
+
+use magnus::{function, method, prelude::*, Error, Ruby};
+
+use vodozemac::{base64_decode, base64_encode, Curve25519PublicKey, Ed25519PublicKey, Ed25519Signature};
+use vodozemac::olm::{
+    Account as OlmAccount, AccountPickle, OlmMessage, PreKeyMessage, Session as OlmSession,
+    SessionConfig as OlmSessionConfig, SessionPickle,
+};
+use vodozemac::megolm::{
+    GroupSession as MegolmGroupSession, GroupSessionPickle, InboundGroupSession as MegolmInbound,
+    InboundGroupSessionPickle, MegolmMessage, SessionConfig as MegolmSessionConfig, SessionKey,
+};
+
+// --- helpers ---------------------------------------------------------------
+
+fn rt_err<E: std::fmt::Display>(e: E) -> Error {
+    // Safe: every caller runs inside a Ruby method invocation (GVL held).
+    let ruby = Ruby::get().expect("rt_err called outside the Ruby VM");
+    Error::new(ruby.exception_runtime_error(), e.to_string())
+}
+
+fn key32(label: &str, bytes: &[u8]) -> Result<[u8; 32], Error> {
+    bytes
+        .try_into()
+        .map_err(|_| rt_err(format!("{label} must be 32 bytes, got {}", bytes.len())))
+}
+
+// --- Account ---------------------------------------------------------------
+
+#[magnus::wrap(class = "Async::Matrix::E2EE::Account", free_immediately, size)]
+struct Account(RefCell<OlmAccount>);
+
+impl Account {
+    fn new() -> Self {
+        Account(RefCell::new(OlmAccount::new()))
+    }
+
+    fn from_pickle(pickle: String, pickle_key: String) -> Result<Self, Error> {
+        let key = key32("pickle_key", pickle_key.as_bytes())?;
+        let p = AccountPickle::from_encrypted(&pickle, &key).map_err(rt_err)?;
+        Ok(Account(RefCell::new(OlmAccount::from_pickle(p))))
+    }
+
+    fn pickle(&self, pickle_key: String) -> Result<String, Error> {
+        let key = key32("pickle_key", pickle_key.as_bytes())?;
+        Ok(self.0.borrow().pickle().encrypt(&key))
+    }
+
+    fn ed25519_key(&self) -> String {
+        self.0.borrow().ed25519_key().to_base64()
+    }
+
+    fn curve25519_key(&self) -> String {
+        self.0.borrow().curve25519_key().to_base64()
+    }
+
+    fn sign(&self, message: String) -> String {
+        self.0.borrow().sign(message.as_bytes()).to_base64()
+    }
+
+    fn one_time_keys(&self) -> HashMap<String, String> {
+        self.0
+            .borrow()
+            .one_time_keys()
+            .into_iter()
+            .map(|(k, v)| (k.to_base64(), v.to_base64()))
+            .collect()
+    }
+
+    fn max_number_of_one_time_keys(&self) -> usize {
+        self.0.borrow().max_number_of_one_time_keys()
+    }
+
+    fn generate_one_time_keys(&self, count: usize) {
+        self.0.borrow_mut().generate_one_time_keys(count);
+    }
+
+    fn fallback_key(&self) -> HashMap<String, String> {
+        self.0
+            .borrow()
+            .fallback_key()
+            .into_iter()
+            .map(|(k, v)| (k.to_base64(), v.to_base64()))
+            .collect()
+    }
+
+    fn generate_fallback_key(&self) {
+        self.0.borrow_mut().generate_fallback_key();
+    }
+
+    fn mark_keys_as_published(&self) {
+        self.0.borrow_mut().mark_keys_as_published();
+    }
+
+    /// Returns a Session for sending to a peer identified by their identity and
+    /// one-time keys (both base64).
+    fn create_outbound_session(
+        &self,
+        identity_key: String,
+        one_time_key: String,
+    ) -> Result<Session, Error> {
+        let ik = Curve25519PublicKey::from_base64(&identity_key).map_err(rt_err)?;
+        let otk = Curve25519PublicKey::from_base64(&one_time_key).map_err(rt_err)?;
+        let session = self
+            .0
+            .borrow()
+            .create_outbound_session(OlmSessionConfig::version_1(), ik, otk)
+            .map_err(rt_err)?;
+        Ok(Session(RefCell::new(session)))
+    }
+
+    /// Establishes an inbound Session from a received pre-key message (base64
+    /// body, as carried in an m.room.encrypted olm `body`). Returns
+    /// `[session, plaintext]`.
+    fn create_inbound_session(
+        &self,
+        identity_key: String,
+        prekey_message_body: String,
+    ) -> Result<(Session, String), Error> {
+        let ik = Curve25519PublicKey::from_base64(&identity_key).map_err(rt_err)?;
+        let prekey = PreKeyMessage::from_base64(&prekey_message_body).map_err(rt_err)?;
+        let result = self
+            .0
+            .borrow_mut()
+            .create_inbound_session(OlmSessionConfig::version_1(), ik, &prekey)
+            .map_err(rt_err)?;
+        let plaintext = String::from_utf8(result.plaintext).map_err(rt_err)?;
+        Ok((Session(RefCell::new(result.session)), plaintext))
+    }
+}
+
+// --- Session (Olm 1:1) -----------------------------------------------------
+
+#[magnus::wrap(class = "Async::Matrix::E2EE::Session", free_immediately, size)]
+struct Session(RefCell<OlmSession>);
+
+impl Session {
+    fn session_id(&self) -> String {
+        self.0.borrow().session_id()
+    }
+
+    fn pickle(&self, pickle_key: String) -> Result<String, Error> {
+        let key = key32("pickle_key", pickle_key.as_bytes())?;
+        Ok(self.0.borrow().pickle().encrypt(&key))
+    }
+
+    fn from_pickle(pickle: String, pickle_key: String) -> Result<Self, Error> {
+        let key = key32("pickle_key", pickle_key.as_bytes())?;
+        let p = SessionPickle::from_encrypted(&pickle, &key).map_err(rt_err)?;
+        Ok(Session(RefCell::new(OlmSession::from_pickle(p))))
+    }
+
+    /// Encrypts plaintext; returns `[message_type, body_base64]` matching the
+    /// Matrix olm ciphertext shape.
+    fn encrypt(&self, plaintext: String) -> Result<(usize, String), Error> {
+        let message = self.0.borrow_mut().encrypt(plaintext.as_bytes()).map_err(rt_err)?;
+        let (mtype, ciphertext) = message.to_parts();
+        Ok((mtype, base64_encode(ciphertext)))
+    }
+
+    /// Decrypts an olm message given its type (0 = pre-key, 1 = normal) and
+    /// base64 body.
+    fn decrypt(&self, message_type: usize, body: String) -> Result<String, Error> {
+        let ciphertext = base64_decode(&body).map_err(rt_err)?;
+        let message = OlmMessage::from_parts(message_type, &ciphertext).map_err(rt_err)?;
+        let plaintext = self.0.borrow_mut().decrypt(&message).map_err(rt_err)?;
+        String::from_utf8(plaintext).map_err(rt_err)
+    }
+}
+
+// --- GroupSession (Megolm outbound) ---------------------------------------
+
+#[magnus::wrap(class = "Async::Matrix::E2EE::GroupSession", free_immediately, size)]
+struct GroupSession(RefCell<MegolmGroupSession>);
+
+impl GroupSession {
+    fn new() -> Self {
+        GroupSession(RefCell::new(MegolmGroupSession::new(MegolmSessionConfig::version_1())))
+    }
+
+    fn session_id(&self) -> String {
+        self.0.borrow().session_id()
+    }
+
+    fn message_index(&self) -> u32 {
+        self.0.borrow().message_index()
+    }
+
+    /// The session key (base64) to share with recipients via m.room_key.
+    fn session_key(&self) -> String {
+        self.0.borrow().session_key().to_base64()
+    }
+
+    /// Encrypts plaintext, returning the megolm message as base64.
+    fn encrypt(&self, plaintext: String) -> String {
+        self.0.borrow_mut().encrypt(plaintext.as_bytes()).to_base64()
+    }
+
+    fn pickle(&self, pickle_key: String) -> Result<String, Error> {
+        let key = key32("pickle_key", pickle_key.as_bytes())?;
+        Ok(self.0.borrow().pickle().encrypt(&key))
+    }
+
+    fn from_pickle(pickle: String, pickle_key: String) -> Result<Self, Error> {
+        let key = key32("pickle_key", pickle_key.as_bytes())?;
+        let p = GroupSessionPickle::from_encrypted(&pickle, &key).map_err(rt_err)?;
+        Ok(GroupSession(RefCell::new(MegolmGroupSession::from_pickle(p))))
+    }
+}
+
+// --- InboundGroupSession (Megolm inbound) ---------------------------------
+
+#[magnus::wrap(class = "Async::Matrix::E2EE::InboundGroupSession", free_immediately, size)]
+struct InboundGroupSession(RefCell<MegolmInbound>);
+
+impl InboundGroupSession {
+    /// Build from a base64 session key received in an m.room_key event.
+    fn new(session_key: String) -> Result<Self, Error> {
+        let key = SessionKey::from_base64(&session_key).map_err(rt_err)?;
+        Ok(InboundGroupSession(RefCell::new(MegolmInbound::new(
+            &key,
+            MegolmSessionConfig::version_1(),
+        ))))
+    }
+
+    fn session_id(&self) -> String {
+        self.0.borrow().session_id()
+    }
+
+    fn first_known_index(&self) -> u32 {
+        self.0.borrow().first_known_index()
+    }
+
+    /// Decrypts a base64 megolm message; returns `[plaintext, message_index]`.
+    fn decrypt(&self, message: String) -> Result<(String, u32), Error> {
+        let msg = MegolmMessage::from_base64(&message).map_err(rt_err)?;
+        let decrypted = self.0.borrow_mut().decrypt(&msg).map_err(rt_err)?;
+        let plaintext = String::from_utf8(decrypted.plaintext).map_err(rt_err)?;
+        Ok((plaintext, decrypted.message_index))
+    }
+
+    fn pickle(&self, pickle_key: String) -> Result<String, Error> {
+        let key = key32("pickle_key", pickle_key.as_bytes())?;
+        Ok(self.0.borrow().pickle().encrypt(&key))
+    }
+
+    fn from_pickle(pickle: String, pickle_key: String) -> Result<Self, Error> {
+        let key = key32("pickle_key", pickle_key.as_bytes())?;
+        let p = InboundGroupSessionPickle::from_encrypted(&pickle, &key).map_err(rt_err)?;
+        Ok(InboundGroupSession(RefCell::new(MegolmInbound::from_pickle(p))))
+    }
+}
+
+// --- module-level functions ------------------------------------------------
+
+/// Verify an ed25519 signature. `key` and `signature` are base64; returns bool.
+fn verify_signature(key: String, message: String, signature: String) -> Result<bool, Error> {
+    let public_key = Ed25519PublicKey::from_base64(&key).map_err(rt_err)?;
+    let sig = Ed25519Signature::from_base64(&signature).map_err(rt_err)?;
+    Ok(public_key.verify(message.as_bytes(), &sig).is_ok())
+}
+
+// --- init ------------------------------------------------------------------
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let namespace = ruby.define_module("Async")?.define_module("Matrix")?.define_module("E2EE")?;
+
+    let account = namespace.define_class("Account", ruby.class_object())?;
+    account.define_singleton_method("new", function!(Account::new, 0))?;
+    account.define_singleton_method("from_pickle", function!(Account::from_pickle, 2))?;
+    account.define_method("pickle", method!(Account::pickle, 1))?;
+    account.define_method("ed25519_key", method!(Account::ed25519_key, 0))?;
+    account.define_method("curve25519_key", method!(Account::curve25519_key, 0))?;
+    account.define_method("sign", method!(Account::sign, 1))?;
+    account.define_method("one_time_keys", method!(Account::one_time_keys, 0))?;
+    account.define_method(
+        "max_number_of_one_time_keys",
+        method!(Account::max_number_of_one_time_keys, 0),
+    )?;
+    account.define_method("generate_one_time_keys", method!(Account::generate_one_time_keys, 1))?;
+    account.define_method("fallback_key", method!(Account::fallback_key, 0))?;
+    account.define_method("generate_fallback_key", method!(Account::generate_fallback_key, 0))?;
+    account.define_method("mark_keys_as_published", method!(Account::mark_keys_as_published, 0))?;
+    account.define_method("create_outbound_session", method!(Account::create_outbound_session, 2))?;
+    account.define_method("create_inbound_session", method!(Account::create_inbound_session, 2))?;
+
+    let session = namespace.define_class("Session", ruby.class_object())?;
+    session.define_singleton_method("from_pickle", function!(Session::from_pickle, 2))?;
+    session.define_method("session_id", method!(Session::session_id, 0))?;
+    session.define_method("pickle", method!(Session::pickle, 1))?;
+    session.define_method("encrypt", method!(Session::encrypt, 1))?;
+    session.define_method("decrypt", method!(Session::decrypt, 2))?;
+
+    let group = namespace.define_class("GroupSession", ruby.class_object())?;
+    group.define_singleton_method("new", function!(GroupSession::new, 0))?;
+    group.define_singleton_method("from_pickle", function!(GroupSession::from_pickle, 2))?;
+    group.define_method("session_id", method!(GroupSession::session_id, 0))?;
+    group.define_method("message_index", method!(GroupSession::message_index, 0))?;
+    group.define_method("session_key", method!(GroupSession::session_key, 0))?;
+    group.define_method("encrypt", method!(GroupSession::encrypt, 1))?;
+    group.define_method("pickle", method!(GroupSession::pickle, 1))?;
+
+    let inbound = namespace.define_class("InboundGroupSession", ruby.class_object())?;
+    inbound.define_singleton_method("new", function!(InboundGroupSession::new, 1))?;
+    inbound.define_singleton_method("from_pickle", function!(InboundGroupSession::from_pickle, 2))?;
+    inbound.define_method("session_id", method!(InboundGroupSession::session_id, 0))?;
+    inbound.define_method("first_known_index", method!(InboundGroupSession::first_known_index, 0))?;
+    inbound.define_method("decrypt", method!(InboundGroupSession::decrypt, 1))?;
+    inbound.define_method("pickle", method!(InboundGroupSession::pickle, 1))?;
+
+    namespace.define_module_function("verify_signature", function!(verify_signature, 3))?;
+
+    Ok(())
+}

data/lib/async/matrix/e2ee.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+# Loads the native vodozemac binding (ext/async_matrix_e2ee) and namespaces the
+# Olm/Megolm primitives under Async::Matrix::E2EE.
+#
+# The native classes (Account, Session, GroupSession, InboundGroupSession) and
+# the module function verify_signature are defined by the Rust #[magnus::init].
+# This file only locates and requires the compiled object.
+#
+#   account = Async::Matrix::E2EE::Account.new
+#   account.curve25519_key            # => base64 string
+#   group = Async::Matrix::E2EE::GroupSession.new
+#   msg   = group.encrypt("hello")    # => base64 megolm message
+#   inbound = Async::Matrix::E2EE::InboundGroupSession.new(group.session_key)
+#   inbound.decrypt(msg)              # => ["hello", 0]
+
+module Async
+  module Matrix
+    module E2EE
+    end
+  end
+end
+
+# rake-compiler installs the shared object alongside this file.
+require_relative "async_matrix_e2ee"
+
+test do
+  describe "Async::Matrix::E2EE" do
+    it "exposes account identity keys as base64" do
+      account = Async::Matrix::E2EE::Account.new
+      account.curve25519_key.should.be.kind_of String
+      account.ed25519_key.should.be.kind_of String
+      account.curve25519_key.length.should.be > 0
+    end
+
+    it "round-trips a megolm group message" do
+      group   = Async::Matrix::E2EE::GroupSession.new
+      inbound = Async::Matrix::E2EE::InboundGroupSession.new(group.session_key)
+
+      message = group.encrypt("hello world")
+      plaintext, index = inbound.decrypt(message)
+
+      plaintext.should == "hello world"
+      index.should == 0
+      inbound.session_id.should == group.session_id
+    end
+
+    it "round-trips an olm 1:1 message" do
+      alice = Async::Matrix::E2EE::Account.new
+      bob   = Async::Matrix::E2EE::Account.new
+      bob.generate_one_time_keys(1)
+      bob_otk = bob.one_time_keys.values.first
+
+      outbound = alice.create_outbound_session(bob.curve25519_key, bob_otk)
+      type, body = outbound.encrypt("yo g")
+      type.should == 0 # pre-key message
+
+      session, plaintext = bob.create_inbound_session(alice.curve25519_key, body)
+      plaintext.should == "yo g"
+
+      reply_type, reply_body = session.encrypt("hello back")
+      outbound.decrypt(reply_type, reply_body).should == "hello back"
+    end
+
+    it "verifies a valid ed25519 signature and rejects a bad one" do
+      account   = Async::Matrix::E2EE::Account.new
+      signature = account.sign("payload")
+
+      Async::Matrix::E2EE.verify_signature(account.ed25519_key, "payload", signature).should == true
+      Async::Matrix::E2EE.verify_signature(account.ed25519_key, "tampered", signature).should == false
+    end
+
+    it "survives a pickle round-trip" do
+      key   = "0" * 32
+      group = Async::Matrix::E2EE::GroupSession.new
+      pickled = group.pickle(key)
+
+      restored = Async::Matrix::E2EE::GroupSession.from_pickle(pickled, key)
+      restored.session_id.should == group.session_id
+    end
+  end
+end

data/lib/async/matrix/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Matrix
-    VERSION = "1.1.1"
+    VERSION = "1.2.1"
 	end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-matrix
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.1
 platform: ruby
 authors:
 - Nathan Kidd
@@ -107,6 +107,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: falcon
   requirement: !ruby/object:Gem::Requirement
@@ -149,12 +163,27 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
 description: Async-native Matrix protocol primitives built on the Socketry async ecosystem.
   Provides well-known discovery, event notification, and application service models.
 email:
 - nathankidd@hey.com
 executables: []
-extensions: []
+extensions:
+- ext/async_matrix_e2ee/extconf.rb
 extra_rdoc_files: []
 files:
 - LICENSE
@@ -455,6 +484,9 @@ files:
 - data/matrix-spec/event-schemas/schema/m.sticker.yaml
 - data/matrix-spec/event-schemas/schema/m.tag.yaml
 - data/matrix-spec/event-schemas/schema/m.typing.yaml
+- ext/async_matrix_e2ee/Cargo.toml
+- ext/async_matrix_e2ee/extconf.rb
+- ext/async_matrix_e2ee/src/lib.rs
 - lib/async/discord.rb
 - lib/async/discord/api.rb
 - lib/async/discord/api/path_tree.rb
@@ -511,6 +543,7 @@ files:
 - lib/async/matrix/client.rb
 - lib/async/matrix/connection.rb
 - lib/async/matrix/double_puppet_client.rb
+- lib/async/matrix/e2ee.rb
 - lib/async/matrix/endpoint.rb
 - lib/async/matrix/error.rb
 - lib/async/matrix/media_client.rb