protocol-zmtp 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dafca992ff161d0cdb81664bfc85fd7f9194517222dcb5d11426a35c6a5f1c38
-  data.tar.gz: 9176b6c3090ef6ccaab8c37bb95d00f781a91c38a57606f08215ccaaf835726c
+  metadata.gz: a8774efa1927a863efbec0173b00b4642fe99f809ee0df07e3ab6a164829909e
+  data.tar.gz: a77071e52f4461323f7d839738ad56d0ed83af312ae1071b4f88ffb365ee2514
 SHA512:
-  metadata.gz: 0aeecc4dd2454e4953ca64a5211aae337cc05846a348434f90cecd258495aefcac9489dc264df65dcbe9e7d0c266436ecdca355c80a8e4423a4b6c052d904f91
-  data.tar.gz: f725b19d48b976315b64e2c1f44663f0454db080a737de074f84a77122e623e8673afb7d662627972d680b6b9af7c209aab90c4c95a1a2654706b5daefe89dd9
+  metadata.gz: c0cc5712a1c5aabd5f360ea5fe052bb45e963f645551f0bea2a46f62d3d43d4f9f8a0a0cd3a2de63e563641d2463586b0574016db6ab394a66b78a0c7bd93924
+  data.tar.gz: 87ae97e2a6bc9448b16a9053d959e7b7707639bb15ad168bc020f83eae0d95309b82be6a0772a38d6e56307038de013d7544e836094c5d52b4dfb114175b5a28

data/lib/protocol/zmtp/codec/command.rb

@@ -30,6 +30,7 @@ module Protocol
           @data = data.b
         end
 
+
         # Encodes as a command frame body.
         #
         # @return [String] binary body (name-length + name + data)
@@ -38,6 +39,7 @@ module Protocol
           name_bytes.bytesize.chr.b + name_bytes + @data
         end
 
+
         # Encodes as a complete command Frame.
         #
         # @return [Frame]
@@ -45,6 +47,7 @@ module Protocol
           Frame.new(to_body, command: true)
         end
 
+
         # Decodes a command from a frame body.
         #
         # @param body [String] binary frame body
@@ -63,49 +66,78 @@ module Protocol
           new(name, data)
         end
 
-        # Builds a READY command with Socket-Type and Identity properties.
-        def self.ready(socket_type:, identity: "")
-          props = encode_properties(
-            "Socket-Type" => socket_type,
-            "Identity"    => identity,
-          )
-          new("READY", props)
+
+        # Builds a READY command with Socket-Type, Identity, and optional X-QoS properties.
+        #
+        # @param qos [Integer] QoS level (0 = omitted)
+        # @param qos_hash [String] supported hash algorithms in preference order (e.g. "xXsS")
+        # @return [Command]
+        def self.ready(socket_type:, identity: "", qos: 0, qos_hash: "")
+          props = { "Socket-Type" => socket_type, "Identity" => identity }
+          if qos > 0
+            props["X-QoS"]      = qos.to_s
+            props["X-QoS-Hash"] = qos_hash unless qos_hash.empty?
+          end
+          new("READY", encode_properties(props))
         end
 
+
         # Builds a SUBSCRIBE command.
+        #
+        # @param prefix [String] subscription prefix to match
+        # @return [Command]
         def self.subscribe(prefix)
           new("SUBSCRIBE", prefix.b)
         end
 
+
         # Builds a CANCEL command (unsubscribe).
+        #
+        # @param prefix [String] subscription prefix to cancel
+        # @return [Command]
         def self.cancel(prefix)
           new("CANCEL", prefix.b)
         end
 
+
         # Builds a JOIN command (RADIO/DISH group subscription).
+        #
+        # @param group [String] group name to join
+        # @return [Command]
         def self.join(group)
           new("JOIN", group.b)
         end
 
+
         # Builds a LEAVE command (RADIO/DISH group unsubscription).
+        #
+        # @param group [String] group name to leave
+        # @return [Command]
         def self.leave(group)
           new("LEAVE", group.b)
         end
 
+
         # Builds a PING command.
         #
         # @param ttl [Numeric] time-to-live in seconds (sent as deciseconds)
         # @param context [String] optional context bytes (up to 16 bytes)
+        # @return [Command]
         def self.ping(ttl: 0, context: "".b)
           ttl_ds = (ttl * 10).to_i
           new("PING", [ttl_ds].pack("n") + context.b)
         end
 
+
         # Builds a PONG command.
+        #
+        # @param context [String] context bytes echoed from the PING
+        # @return [Command]
         def self.pong(context: "".b)
           new("PONG", context.b)
         end
 
+
         # Extracts TTL (in seconds) and context from a PING command's data.
         #
         # @return [Array(Numeric, String)] [ttl_seconds, context_bytes]
@@ -115,12 +147,19 @@ module Protocol
           [ttl_ds / 10.0, context]
         end
 
+
         # Parses READY command data as a property list.
+        #
+        # @return [Hash{String => String}] property name-value pairs
         def properties
           self.class.decode_properties(@data)
         end
 
+
         # Encodes a hash of properties into ZMTP property list format.
+        #
+        # @param props [Hash{String => String}] property name-value pairs
+        # @return [String] binary-encoded property list
         def self.encode_properties(props)
           parts = props.map do |name, value|
             name_bytes  = name.b
@@ -130,7 +169,12 @@ module Protocol
           parts.join
         end
 
+
         # Decodes a ZMTP property list from binary data.
+        #
+        # @param data [String] binary-encoded property list
+        # @return [Hash{String => String}] property name-value pairs
+        # @raise [Error] on malformed property data
         def self.decode_properties(data)
           result = {}
           offset = 0

data/lib/protocol/zmtp/codec/frame.rb

@@ -15,9 +15,11 @@ module Protocol
         FLAGS_LONG    = 0x02
         FLAGS_COMMAND = 0x04
 
+
         # Short frame: 1-byte size, max body 255 bytes.
         SHORT_MAX = 255
 
+
         # @return [String] frame body (binary)
         attr_reader :body
 
@@ -30,6 +32,7 @@ module Protocol
           @command = command
         end
 
+
         # @return [Boolean] true if more frames follow in this message
         def more?    = @more
 
@@ -52,6 +55,7 @@ module Protocol
           end
         end
 
+
         # Encodes a multi-part message into a single wire-format string.
         # The result can be written to multiple connections without
         # re-encoding each time (useful for fan-out patterns like PUB).
@@ -67,6 +71,7 @@ module Protocol
           buf.freeze
         end
 
+
         # Reads one frame from an IO-like object.
         #
         # @param io [#read_exactly] must support read_exactly(n)

data/lib/protocol/zmtp/codec/greeting.rb

@@ -26,6 +26,7 @@ module Protocol
         MECHANISM_LENGTH = 20
         AS_SERVER_OFFSET = 32
 
+
         # Encodes a ZMTP 3.1 greeting.
         #
         # @param mechanism [String] security mechanism name (e.g. "NULL")
@@ -39,6 +40,7 @@ module Protocol
           buf << ("\x00" * 31)
         end
 
+
         # Decodes a ZMTP greeting.
         #
         # @param data [String] 64-byte binary greeting

data/lib/protocol/zmtp/connection.rb

@@ -18,6 +18,12 @@ module Protocol
       # @return [String] peer's identity (from READY handshake)
       attr_reader :peer_identity
 
+      # @return [Integer] peer's QoS level (from READY handshake, 0 if absent)
+      attr_reader :peer_qos
+
+      # @return [String] peer's supported hash algorithms in preference order
+      attr_reader :peer_qos_hash
+
       # @return [Object] transport IO (#read_exactly, #write, #flush, #close)
       attr_reader :io
 
@@ -31,7 +37,7 @@ module Protocol
       # @param mechanism [Mechanism::Null, Mechanism::Curve] security mechanism
       # @param max_message_size [Integer, nil] max frame size in bytes, nil = unlimited
       def initialize(io, socket_type:, identity: "", as_server: false,
-                     mechanism: nil, max_message_size: nil)
+                     mechanism: nil, max_message_size: nil, qos: 0, qos_hash: "")
         @io               = io
         @socket_type      = socket_type
         @identity         = identity
@@ -39,11 +45,16 @@ module Protocol
         @mechanism        = mechanism || Mechanism::Null.new
         @peer_socket_type = nil
         @peer_identity    = nil
+        @peer_qos         = nil
+        @peer_qos_hash    = nil
+        @qos              = qos
+        @qos_hash         = qos_hash
         @mutex            = Mutex.new
         @max_message_size = max_message_size
         @last_received_at = nil
       end
 
+
       # Performs the full ZMTP handshake via the configured mechanism.
       #
       # @return [void]
@@ -54,10 +65,14 @@ module Protocol
           as_server:   @as_server,
           socket_type: @socket_type,
           identity:    @identity,
+          qos:         @qos,
+          qos_hash:    @qos_hash,
         )
 
         @peer_socket_type = result[:peer_socket_type]
         @peer_identity    = result[:peer_identity]
+        @peer_qos         = result[:peer_qos] || 0
+        @peer_qos_hash    = result[:peer_qos_hash] || ""
 
         unless @peer_socket_type
           raise Error, "peer READY missing Socket-Type"
@@ -69,6 +84,7 @@ module Protocol
         end
       end
 
+
       # Sends a multi-frame message (write + flush).
       #
       # @param parts [Array<String>] message frames
@@ -80,6 +96,7 @@ module Protocol
         end
       end
 
+
       # Writes a multi-frame message to the buffer without flushing.
       # Call {#flush} after batching writes.
       #
@@ -91,6 +108,7 @@ module Protocol
         end
       end
 
+
       # Writes pre-encoded wire bytes to the buffer without flushing.
       # Used for fan-out: encode once, write to many connections.
       #
@@ -102,22 +120,26 @@ module Protocol
         end
       end
 
+
       # Returns true if the ZMTP mechanism encrypts at the frame level
-      # (e.g. CURVE). TLS encryption is below ZMTP and does not affect
-      # wire-format bytes.
+      # (e.g. CURVE, BLAKE3ZMQ).
       #
       # @return [Boolean]
-      def curve?
+      def encrypted?
         @mechanism.encrypted?
       end
 
+
       # Flushes the write buffer to the underlying IO.
+      #
+      # @return [void]
       def flush
         @mutex.synchronize do
           @io.flush
         end
       end
 
+
       # Receives a multi-frame message.
       # PING/PONG commands are handled automatically by #read_frame.
       #
@@ -137,6 +159,7 @@ module Protocol
         frames.freeze
       end
 
+
       # Sends a command.
       #
       # @param command [Codec::Command]
@@ -152,9 +175,11 @@ module Protocol
         end
       end
 
+
       # Reads one frame from the wire. Handles PING/PONG automatically.
-      # When using an encrypted mechanism, MESSAGE commands are decrypted
-      # back to ZMTP frames transparently.
+      # When using an encrypted mechanism, all frames are decrypted
+      # transparently (supports both CURVE MESSAGE wrapping and inline
+      # encryption like BLAKE3ZMQ).
       #
       # @return [Codec::Frame]
       # @raise [EOFError] if connection is closed
@@ -168,9 +193,7 @@ module Protocol
           end
           touch_heartbeat
 
-          if @mechanism.encrypted? && frame.body.bytesize > 8 && frame.body.byteslice(0, 8) == "\x07MESSAGE".b
-            frame = @mechanism.decrypt(frame)
-          end
+          frame = @mechanism.decrypt(frame) if @mechanism.encrypted?
 
           if frame.command?
             cmd = Codec::Command.from_body(frame.body)
@@ -187,11 +210,15 @@ module Protocol
         end
       end
 
+
       # Records that a frame was received (for heartbeat expiry tracking).
+      #
+      # @return [void]
       def touch_heartbeat
         @last_received_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end
 
+
       # Returns true if no frame has been received within +timeout+ seconds.
       #
       # @param timeout [Numeric] seconds
@@ -201,7 +228,10 @@ module Protocol
         (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @last_received_at) > timeout
       end
 
+
       # Closes the connection.
+      #
+      # @return [void]
       def close
         @io.close
       rescue IOError

data/lib/protocol/zmtp/error.rb

@@ -3,6 +3,7 @@
 module Protocol
   module ZMTP
     # Raised on ZMTP protocol violations.
-    class Error < RuntimeError; end
+    class Error < RuntimeError
+    end
   end
 end

data/lib/protocol/zmtp/mechanism/curve.rb

@@ -23,6 +23,7 @@ module Protocol
       class Curve
         MECHANISM_NAME = "CURVE"
 
+
         # Nonce prefixes.
         NONCE_PREFIX_HELLO     = "CurveZMQHELLO---"
         NONCE_PREFIX_WELCOME   = "WELCOME-"
@@ -33,46 +34,66 @@ module Protocol
         NONCE_PREFIX_VOUCH     = "VOUCH---"
         NONCE_PREFIX_COOKIE    = "COOKIE--"
 
+
         BOX_OVERHEAD = 16
         MAX_NONCE    = (2**64) - 1
 
+
         # Creates a CURVE server mechanism.
         #
         # @param public_key [String] 32 bytes
         # @param secret_key [String] 32 bytes
         # @param crypto [Module] NaCl-compatible backend (RbNaCl or Nuckle)
-        # @param authenticator [#include?, #call, nil] client key authenticator
+        # @param authenticator [#call, nil] called with a {PeerInfo}
+        #   during authentication; must return truthy to allow the connection.
+        #   When nil, any client with a valid vouch is accepted.
         # @return [Curve]
-        def self.server(public_key, secret_key, crypto:, authenticator: nil)
+        def self.server(public_key:, secret_key:, crypto:, authenticator: nil)
           new(public_key:, secret_key:, crypto:, as_server: true, authenticator:)
         end
 
+
         # Creates a CURVE client mechanism.
         #
-        # @param public_key [String] 32 bytes
-        # @param secret_key [String] 32 bytes
-        # @param server_key [String] 32 bytes
+        # @param server_key [String] 32 bytes (server permanent public key)
         # @param crypto [Module] NaCl-compatible backend (RbNaCl or Nuckle)
+        # @param public_key [String, nil] 32 bytes (or nil for auto-generated ephemeral identity)
+        # @param secret_key [String, nil] 32 bytes (or nil for auto-generated ephemeral identity)
         # @return [Curve]
-        def self.client(public_key, secret_key, server_key:, crypto:)
+        def self.client(server_key:, crypto:, public_key: nil, secret_key: nil)
           new(public_key:, secret_key:, server_key:, crypto:, as_server: false)
         end
 
-        def initialize(server_key: nil, public_key:, secret_key:, crypto:, as_server: false, authenticator: nil)
-          validate_key!(public_key, "public_key")
-          validate_key!(secret_key, "secret_key")
 
-          @crypto           = crypto
-          @permanent_public = crypto::PublicKey.new(public_key.b)
-          @permanent_secret = crypto::PrivateKey.new(secret_key.b)
-          @as_server        = as_server
-          @authenticator    = authenticator
+        # @param public_key [String, nil] 32-byte permanent public key
+        # @param secret_key [String, nil] 32-byte permanent secret key
+        # @param server_key [String, nil] 32-byte server permanent public key (client only)
+        # @param crypto [Module] NaCl-compatible crypto backend
+        # @param as_server [Boolean] whether this side acts as the CURVE server
+        # @param authenticator [#call, nil] optional server-side authenticator
+        def initialize(public_key: nil, secret_key: nil, server_key: nil, crypto:, as_server: false, authenticator: nil)
+          @crypto        = crypto
+          @as_server     = as_server
+          @authenticator = authenticator
 
           if as_server
+            validate_key!(public_key, "public_key")
+            validate_key!(secret_key, "secret_key")
+            @permanent_public = crypto::PublicKey.new(public_key.b)
+            @permanent_secret = crypto::PrivateKey.new(secret_key.b)
             @cookie_key = crypto::Random.random_bytes(32)
           else
             validate_key!(server_key, "server_key")
             @server_public = crypto::PublicKey.new(server_key.b)
+            if public_key && secret_key
+              validate_key!(public_key, "public_key")
+              validate_key!(secret_key, "secret_key")
+              @permanent_public = crypto::PublicKey.new(public_key.b)
+              @permanent_secret = crypto::PrivateKey.new(secret_key.b)
+            else
+              @permanent_secret = crypto::PrivateKey.generate
+              @permanent_public = @permanent_secret.public_key
+            end
           end
 
           @session_box = nil
@@ -80,6 +101,11 @@ module Protocol
           @recv_nonce  = -1
         end
 
+
+        # Resets session state when duplicating (e.g. for a new connection).
+        #
+        # @param source [Curve] the original instance being duplicated
+        # @return [void]
         def initialize_dup(source)
           super
           @session_box    = nil
@@ -89,16 +115,44 @@ module Protocol
           @recv_nonce_buf = nil
         end
 
+
+        # @return [Boolean] true -- CURVE always encrypts frames
         def encrypted? = true
 
-        def handshake!(io, as_server:, socket_type:, identity:)
+        # Returns a periodic maintenance task for rotating the cookie key (server only).
+        #
+        # @return [Hash, nil] a hash with +:interval+ (seconds) and +:task+ (Proc), or nil for clients
+        def maintenance
+          return unless @as_server
+          { interval: 60, task: -> { @cookie_key = @crypto::Random.random_bytes(32) } }.freeze
+        end
+
+
+        # Performs the full CurveZMQ handshake (HELLO/WELCOME/INITIATE/READY).
+        #
+        # @param io [#read_exactly, #write, #flush] transport IO
+        # @param as_server [Boolean] ignored -- uses the value from #initialize
+        # @param socket_type [String] our socket type name
+        # @param identity [String] our identity
+        # @param qos [Integer] QoS level
+        # @param qos_hash [String] supported hash algorithms
+        # @return [Hash] { peer_socket_type:, peer_identity:, peer_qos:, peer_qos_hash: }
+        # @raise [Error] on handshake failure
+        def handshake!(io, as_server:, socket_type:, identity:, qos: 0, qos_hash: "")
           if @as_server
-            server_handshake!(io, socket_type:, identity:)
+            server_handshake!(io, socket_type:, identity:, qos:, qos_hash:)
           else
-            client_handshake!(io, socket_type:, identity:)
+            client_handshake!(io, socket_type:, identity:, qos:, qos_hash:)
           end
         end
 
+
+        # Encrypts a frame body into a CURVE MESSAGE command on the wire.
+        #
+        # @param body [String] plaintext frame body
+        # @param more [Boolean] whether more frames follow in this message
+        # @param command [Boolean] whether this is a command frame
+        # @return [String] binary wire bytes ready for writing
         def encrypt(body, more: false, command: false)
           flags = 0
           flags |= 0x01 if more
@@ -122,9 +176,16 @@ module Protocol
           wire << "\x07MESSAGE" << short_nonce << ciphertext
         end
 
+
         MESSAGE_PREFIX      = "\x07MESSAGE".b.freeze
         MESSAGE_PREFIX_SIZE = MESSAGE_PREFIX.bytesize
 
+
+        # Decrypts a CURVE MESSAGE command frame back into a plaintext frame.
+        #
+        # @param frame [Codec::Frame] an encrypted MESSAGE command frame
+        # @return [Codec::Frame] the decrypted frame with restored flags
+        # @raise [Error] on decryption failure or nonce violation
         def decrypt(frame)
           body = frame.body
           unless body.start_with?(MESSAGE_PREFIX)
@@ -161,7 +222,7 @@ module Protocol
         # Client-side handshake
         # ----------------------------------------------------------------
 
-        def client_handshake!(io, socket_type:, identity:)
+        def client_handshake!(io, socket_type:, identity:, qos: 0, qos_hash: "")
           cn_secret = @crypto::PrivateKey.generate
           cn_public = cn_secret.public_key
 
@@ -172,6 +233,7 @@ module Protocol
             raise Error, "expected CURVE mechanism, got #{peer_greeting[:mechanism]}"
           end
 
+
           # --- HELLO ---
           short_nonce = [1].pack("Q>")
           nonce       = NONCE_PREFIX_HELLO + short_nonce
@@ -218,10 +280,12 @@ module Protocol
           vouch_plaintext = cn_public.to_s + @server_public.to_s
           vouch           = @crypto::Box.new(sn_public, @permanent_secret).encrypt(vouch_nonce, vouch_plaintext)
 
-          metadata = Codec::Command.encode_properties(
-            "Socket-Type" => socket_type,
-            "Identity"    => identity,
-          )
+          props = { "Socket-Type" => socket_type, "Identity" => identity }
+          if qos > 0
+            props["X-QoS"]      = qos.to_s
+            props["X-QoS-Hash"] = qos_hash unless qos_hash.empty?
+          end
+          metadata = Codec::Command.encode_properties(props)
 
           initiate_box_plaintext = "".b
           initiate_box_plaintext << @permanent_public.to_s
@@ -264,20 +328,23 @@ module Protocol
           props            = Codec::Command.decode_properties(r_plaintext)
           peer_socket_type = props["Socket-Type"]
           peer_identity    = props["Identity"] || ""
+          peer_qos         = (props["X-QoS"] || "0").to_i
+          peer_qos_hash    = props["X-QoS-Hash"] || ""
 
           @session_box = session
           @send_nonce  = 1
           @recv_nonce  = 0
           init_nonce_buffers!
 
-          { peer_socket_type: peer_socket_type, peer_identity: peer_identity }
+          { peer_socket_type: peer_socket_type, peer_identity: peer_identity, peer_qos: peer_qos, peer_qos_hash: peer_qos_hash }
         end
 
+
         # ----------------------------------------------------------------
         # Server-side handshake
         # ----------------------------------------------------------------
 
-        def server_handshake!(io, socket_type:, identity:)
+        def server_handshake!(io, socket_type:, identity:, qos: 0, qos_hash: "")
           io.write(Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: true))
           io.flush
           peer_greeting = Codec::Greeting.decode(io.read_exactly(Codec::Greeting::SIZE))
@@ -285,6 +352,7 @@ module Protocol
             raise Error, "expected CURVE mechanism, got #{peer_greeting[:mechanism]}"
           end
 
+
           # --- Read HELLO ---
           hello_frame = Codec::Frame.read_from(io)
           raise Error, "expected command frame" unless hello_frame.command?
@@ -308,6 +376,7 @@ module Protocol
             raise Error, "HELLO signature content invalid"
           end
 
+
           # --- WELCOME ---
           sn_secret = @crypto::PrivateKey.generate
           sn_public = sn_secret.public_key
@@ -391,20 +460,21 @@ module Protocol
           end
 
           if @authenticator
-            client_key = client_permanent.to_s
-            allowed    = if @authenticator.respond_to?(:include?)
-                           @authenticator.include?(client_key)
-                         else
-                           @authenticator.call(client_key)
-                         end
-            raise Error, "client key not authorized" unless allowed
+            peer = PeerInfo.new(public_key: client_permanent)
+            unless @authenticator.call(peer)
+              send_error(io, "client key not authorized")
+              raise Error, "client key not authorized"
+            end
           end
 
+
           # --- READY ---
-          ready_metadata = Codec::Command.encode_properties(
-            "Socket-Type" => socket_type,
-            "Identity"    => identity,
-          )
+          ready_props = { "Socket-Type" => socket_type, "Identity" => identity }
+          if qos > 0
+            ready_props["X-QoS"]      = qos.to_s
+            ready_props["X-QoS-Hash"] = qos_hash unless qos_hash.empty?
+          end
+          ready_metadata = Codec::Command.encode_properties(ready_props)
 
           r_short_nonce = [1].pack("Q>")
           r_nonce       = NONCE_PREFIX_READY + r_short_nonce
@@ -428,9 +498,12 @@ module Protocol
           {
             peer_socket_type: props["Socket-Type"],
             peer_identity:    props["Identity"] || "",
+            peer_qos:         (props["X-QoS"] || "0").to_i,
+            peer_qos_hash:    props["X-QoS-Hash"] || "",
           }
         end
 
+
         # ----------------------------------------------------------------
         # Nonce helpers
         # ----------------------------------------------------------------
@@ -442,21 +515,41 @@ module Protocol
           @recv_nonce_buf = String.new(recv_pfx + ("\x00" * 8), encoding: Encoding::BINARY)
         end
 
+
         def make_send_nonce
           @send_nonce += 1
           raise Error, "nonce counter exhausted" if @send_nonce > MAX_NONCE
           n = @send_nonce
-          @send_nonce_buf.setbyte(23, n & 0xFF); n >>= 8
-          @send_nonce_buf.setbyte(22, n & 0xFF); n >>= 8
-          @send_nonce_buf.setbyte(21, n & 0xFF); n >>= 8
-          @send_nonce_buf.setbyte(20, n & 0xFF); n >>= 8
-          @send_nonce_buf.setbyte(19, n & 0xFF); n >>= 8
-          @send_nonce_buf.setbyte(18, n & 0xFF); n >>= 8
-          @send_nonce_buf.setbyte(17, n & 0xFF); n >>= 8
+          @send_nonce_buf.setbyte(23, n & 0xFF)
+          n >>= 8
+          @send_nonce_buf.setbyte(22, n & 0xFF)
+          n >>= 8
+          @send_nonce_buf.setbyte(21, n & 0xFF)
+          n >>= 8
+          @send_nonce_buf.setbyte(20, n & 0xFF)
+          n >>= 8
+          @send_nonce_buf.setbyte(19, n & 0xFF)
+          n >>= 8
+          @send_nonce_buf.setbyte(18, n & 0xFF)
+          n >>= 8
+          @send_nonce_buf.setbyte(17, n & 0xFF)
+          n >>= 8
           @send_nonce_buf.setbyte(16, n & 0xFF)
           @send_nonce_buf
         end
 
+
+        def send_error(io, reason)
+          error_body = "".b
+          error_body << "\x05ERROR"
+          error_body << reason.bytesize.chr << reason.b
+          io.write(Codec::Frame.new(error_body, command: true).to_wire)
+          io.flush
+        rescue IOError
+          # connection may already be broken
+        end
+
+
         def validate_key!(key, name)
           raise ArgumentError, "#{name} is required" if key.nil?
           raise ArgumentError, "#{name} must be 32 bytes (got #{key.b.bytesize})" unless key.b.bytesize == 32

data/lib/protocol/zmtp/mechanism/null.rb

@@ -2,6 +2,7 @@
 
 module Protocol
   module ZMTP
+    # Security mechanisms for the ZMTP handshake (NULL, PLAIN, CURVE).
     module Mechanism
       # NULL security mechanism — no encryption, no authentication.
       #
@@ -10,6 +11,7 @@ module Protocol
       class Null
         MECHANISM_NAME = "NULL"
 
+
         # Performs the full NULL handshake over +io+.
         #
         # 1. Exchange 64-byte greetings
@@ -22,7 +24,7 @@ module Protocol
         # @param identity [String]
         # @return [Hash] { peer_socket_type:, peer_identity: }
         # @raise [Error]
-        def handshake!(io, as_server:, socket_type:, identity:)
+        def handshake!(io, as_server:, socket_type:, identity:, qos: 0, qos_hash: "")
           io.write(Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: as_server))
           io.flush
 
@@ -33,7 +35,7 @@ module Protocol
             raise Error, "unsupported mechanism: #{peer_greeting[:mechanism]}"
           end
 
-          ready_cmd = Codec::Command.ready(socket_type: socket_type, identity: identity)
+          ready_cmd = Codec::Command.ready(socket_type: socket_type, identity: identity, qos: qos, qos_hash: qos_hash)
           io.write(ready_cmd.to_frame.to_wire)
           io.flush
 
@@ -50,14 +52,17 @@ module Protocol
           props            = peer_cmd.properties
           peer_socket_type = props["Socket-Type"]
           peer_identity    = props["Identity"] || ""
+          peer_qos         = (props["X-QoS"] || "0").to_i
+          peer_qos_hash    = props["X-QoS-Hash"] || ""
 
           unless peer_socket_type
             raise Error, "peer READY missing Socket-Type"
           end
 
-          { peer_socket_type: peer_socket_type, peer_identity: peer_identity }
+          { peer_socket_type: peer_socket_type, peer_identity: peer_identity, peer_qos: peer_qos, peer_qos_hash: peer_qos_hash }
         end
 
+
         # @return [Boolean] false — NULL does not encrypt frames
         def encrypted? = false
       end

data/lib/protocol/zmtp/mechanism/plain.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Protocol
+  module ZMTP
+    module Mechanism
+      # PLAIN security mechanism — username/password authentication, no encryption.
+      #
+      # Implements the ZMTP PLAIN handshake (RFC 24):
+      #
+      #   client → server:  HELLO    (username + password)
+      #   server → client:  WELCOME  (empty, credentials accepted)
+      #   client → server:  INITIATE (socket metadata)
+      #   server → client:  READY    (socket metadata)
+      #
+      class Plain
+        MECHANISM_NAME = "PLAIN"
+
+
+        # @param username [String] client username (max 255 bytes)
+        # @param password [String] client password (max 255 bytes)
+        # @param authenticator [#call, nil] server-side credential verifier;
+        #   called as +authenticator.call(username, password)+ and must return
+        #   truthy to accept the connection.  When +nil+, all credentials pass.
+        def initialize(username: "", password: "", authenticator: nil)
+          @username      = username
+          @password      = password
+          @authenticator = authenticator
+        end
+
+
+        # Performs the full PLAIN handshake over +io+.
+        #
+        # @param io [#read_exactly, #write, #flush] transport IO
+        # @param as_server [Boolean]
+        # @param socket_type [String]
+        # @param identity [String]
+        # @return [Hash] { peer_socket_type:, peer_identity: }
+        # @raise [Error]
+        def handshake!(io, as_server:, socket_type:, identity:, qos: 0, qos_hash: "")
+          io.write(Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: as_server))
+          io.flush
+
+          greeting_data = io.read_exactly(Codec::Greeting::SIZE)
+          peer_greeting = Codec::Greeting.decode(greeting_data)
+
+          unless peer_greeting[:mechanism] == MECHANISM_NAME
+            raise Error, "unsupported mechanism: #{peer_greeting[:mechanism]}"
+          end
+
+          if as_server
+            server_handshake!(io, socket_type: socket_type, identity: identity, qos: qos, qos_hash: qos_hash)
+          else
+            client_handshake!(io, socket_type: socket_type, identity: identity, qos: qos, qos_hash: qos_hash)
+          end
+        end
+
+
+        # @return [Boolean] false — PLAIN does not encrypt frames
+        def encrypted?
+          false
+        end
+
+
+        private
+
+
+        def client_handshake!(io, socket_type:, identity:, qos: 0, qos_hash: "")
+          send_command(io, hello_command)
+
+          cmd = read_command(io)
+          raise Error, "expected WELCOME, got #{cmd.name}" unless cmd.name == "WELCOME"
+
+          props = { "Socket-Type" => socket_type, "Identity" => identity }
+          if qos > 0
+            props["X-QoS"]      = qos.to_s
+            props["X-QoS-Hash"] = qos_hash unless qos_hash.empty?
+          end
+          initiate = Codec::Command.new("INITIATE", Codec::Command.encode_properties(props))
+          send_command(io, initiate)
+
+          cmd = read_command(io)
+          raise Error, "expected READY, got #{cmd.name}" unless cmd.name == "READY"
+
+          extract_peer_info(cmd)
+        end
+
+
+        def server_handshake!(io, socket_type:, identity:, qos: 0, qos_hash: "")
+          cmd = read_command(io)
+          raise Error, "expected HELLO, got #{cmd.name}" unless cmd.name == "HELLO"
+
+          username, password = decode_credentials(cmd.data)
+
+          if @authenticator && !@authenticator.call(username, password)
+            raise Error, "authentication failed"
+          end
+
+          send_command(io, Codec::Command.new("WELCOME"))
+
+          cmd = read_command(io)
+          raise Error, "expected INITIATE, got #{cmd.name}" unless cmd.name == "INITIATE"
+
+          peer_info = extract_peer_info(cmd)
+
+          send_command(io, Codec::Command.ready(socket_type: socket_type, identity: identity, qos: qos, qos_hash: qos_hash))
+
+          peer_info
+        end
+
+
+        def hello_command
+          u = @username.b
+          p = @password.b
+
+          raise Error, "username too long (max 255 bytes)" if u.bytesize > 255
+          raise Error, "password too long (max 255 bytes)" if p.bytesize > 255
+
+          data = u.bytesize.chr.b + u + p.bytesize.chr.b + p
+          Codec::Command.new("HELLO", data)
+        end
+
+
+        def decode_credentials(data)
+          data = data.b
+          raise Error, "HELLO body too short" if data.bytesize < 1
+
+          u_len    = data.getbyte(0)
+          p_offset = 1 + u_len
+
+          raise Error, "HELLO username truncated" if data.bytesize < p_offset + 1
+
+          username = data.byteslice(1, u_len)
+          p_len    = data.getbyte(p_offset)
+
+          raise Error, "HELLO password truncated" if data.bytesize < p_offset + 1 + p_len
+
+          password = data.byteslice(p_offset + 1, p_len)
+
+          [username, password]
+        end
+
+
+        def extract_peer_info(cmd)
+          props            = cmd.properties
+          peer_socket_type = props["Socket-Type"]
+
+          raise Error, "peer command missing Socket-Type" unless peer_socket_type
+
+          { peer_socket_type: peer_socket_type, peer_identity: props["Identity"] || "", peer_qos: (props["X-QoS"] || "0").to_i, peer_qos_hash: props["X-QoS-Hash"] || "" }
+        end
+
+
+        def send_command(io, cmd)
+          io.write(cmd.to_frame.to_wire)
+          io.flush
+        end
+
+
+        def read_command(io)
+          frame = Codec::Frame.read_from(io)
+          raise Error, "expected command frame, got data frame" unless frame.command?
+
+          Codec::Command.from_body(frame.body)
+        end
+      end
+    end
+  end
+end

data/lib/protocol/zmtp/peer_info.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Protocol
+  module ZMTP
+    # Context passed to an authenticator during authentication.
+    # +public_key+ is a +crypto::PublicKey+ instance.
+    PeerInfo = Data.define(:public_key)
+  end
+end

data/lib/protocol/zmtp/version.rb

@@ -2,6 +2,6 @@
 
 module Protocol
   module ZMTP
-    VERSION = "0.1.2"
+    VERSION = "0.3.0"
   end
 end

data/lib/protocol/zmtp/z85.rb

@@ -15,6 +15,12 @@ module Protocol
 
       BASE = 85
 
+
+      # Encodes binary data to a Z85-encoded ASCII string.
+      #
+      # @param data [String] binary data (length must be a multiple of 4)
+      # @return [String] Z85-encoded string (5/4 the size of the input)
+      # @raise [ArgumentError] if data length is not a multiple of 4
       def self.encode(data)
         data = data.b
         raise ArgumentError, "data length must be a multiple of 4 (got #{data.bytesize})" unless (data.bytesize % 4).zero?
@@ -32,6 +38,12 @@ module Protocol
         out
       end
 
+
+      # Decodes a Z85-encoded string back to binary data.
+      #
+      # @param string [String] Z85-encoded string (length must be a multiple of 5)
+      # @return [String] decoded binary data (4/5 the size of the input)
+      # @raise [ArgumentError] if string length is not a multiple of 5 or contains invalid characters
       def self.decode(string)
         raise ArgumentError, "string length must be a multiple of 5 (got #{string.bytesize})" unless (string.bytesize % 5).zero?
 

data/lib/protocol/zmtp.rb

@@ -5,10 +5,14 @@ require_relative "zmtp/error"
 require_relative "zmtp/valid_peers"
 require_relative "zmtp/codec"
 require_relative "zmtp/connection"
+require_relative "zmtp/peer_info"
 require_relative "zmtp/mechanism/null"
+require_relative "zmtp/mechanism/plain"
 require_relative "zmtp/z85"
 
+# Top-level namespace for wire protocol implementations.
 module Protocol
+  # ZMTP 3.1 (ZeroMQ Message Transport Protocol) implementation.
   module ZMTP
     # Autoload CURVE mechanism — requires a crypto backend (rbnacl or nuckle).
     autoload :Curve, File.expand_path("zmtp/mechanism/curve", __dir__)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-zmtp
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -29,6 +29,8 @@ files:
 - lib/protocol/zmtp/error.rb
 - lib/protocol/zmtp/mechanism/curve.rb
 - lib/protocol/zmtp/mechanism/null.rb
+- lib/protocol/zmtp/mechanism/plain.rb
+- lib/protocol/zmtp/peer_info.rb
 - lib/protocol/zmtp/valid_peers.rb
 - lib/protocol/zmtp/version.rb
 - lib/protocol/zmtp/z85.rb