meshtastic 0.0.187 → 0.0.188

data/lib/meshtastic/admin.rb

@@ -3,6 +3,7 @@
 require 'timeout'
 require 'monitor'
 require 'meshtastic/admin_pb'
+require 'meshtastic/admin/validation'
 require 'meshtastic/mqtt'
 
 module Meshtastic
@@ -19,7 +20,7 @@ module Meshtastic
     end
 
     SKIP = %i[
-      message transport_obj to from channel want_ack hop_limit
+      message transport_obj to from channel channel_id want_ack hop_limit
       want_response port_num data via psks seconds owner long_name short_name index config_type
       module_config_type path node_num lat lon altitude time channel_settings channel_pb
       config module_config messages ringtone scale location event event_code kb_char touch_x
@@ -70,7 +71,7 @@ module Meshtastic
 
         message.session_passkey = passkey
       end
-      message
+      Validation.validate(message: message)
     end
 
     public_class_method def self.send(opts = {})
@@ -86,11 +87,7 @@ module Meshtastic
         message.session_passkey = acquire_session(opts.merge(connection: connection, target: destination))
       end
       want_response = opts.fetch(:want_response) { message.payload_variant.to_s.match?(/\Aget_.*_request\z/) }
-      data = Meshtastic::Data.new(
-        portnum: :ADMIN_APP,
-        payload: message.to_proto,
-        want_response: want_response
-      )
+      data = Meshtastic::Data.new(portnum: :ADMIN_APP, payload: message.to_proto, want_response: want_response)
       delivery = opts.except(:transport_obj).merge(data: data, port_num: Meshtastic::PortNum::ADMIN_APP, to: destination)
       delivery[:"#{type}_obj"] = opts[:transport_obj]
       delivery[:from] = 0 if connection && !opts.key?(:from)
@@ -176,10 +173,17 @@ module Meshtastic
            [opts[:target], opts[:connection][:my_node_num]].include?(packet.from)
           reason = Meshtastic::Routing.decode(packet.decoded.payload).error_reason
           raise RoutingError.new(reason, opts[:request_id], packet.from) if reason != :NONE && [opts[:target], opts[:connection][:my_node_num]].include?(packet.from)
-          return { variant: :routing, value: reason, request_id: opts[:request_id], from: packet.from } if reason == :NONE && packet.from == opts[:target] && opts[:variant] == :routing
+          if reason == :NONE && packet.from == opts[:target] && opts[:variant] == :routing
+            return { variant: :routing, value: reason, request_id: opts[:request_id], from: packet.from,
+                     delivery: packet.ack_proof_status == :ACK_PROOF_VALID ? :device_verified : :acknowledged,
+                     security_provenance: { source: :radio, verification: :device_reported, reported: { ack_proof_status: packet.ack_proof_status, xeddsa_signed: packet.xeddsa_signed } } }
+          end
         end
         reply = response(packet: incoming, request_id: opts[:request_id], from: opts[:target])
-        return reply if reply && reply[:variant] == opts[:variant]
+        if reply && reply[:variant] == opts[:variant]
+          reply[:security_provenance].merge!(source: :radio, verification: :device_reported)
+          return reply
+        end
 
         deferred << incoming
       end
@@ -227,8 +231,9 @@ module Meshtastic
       return nil unless variant.to_s.end_with?('_response')
 
       {
-        message: message, variant: variant, value: message.public_send(variant),
-        session_passkey: message.session_passkey, request_id: packet.decoded.request_id, from: packet.from
+        message: message, variant: variant, value: message.public_send(variant), delivery: :readback,
+        session_passkey: message.session_passkey, request_id: packet.decoded.request_id, from: packet.from,
+        security_provenance: { source: :unknown, verification: :untrusted, reported: { ack_proof_status: packet.ack_proof_status, xeddsa_signed: packet.xeddsa_signed } }
       }
     end
 
@@ -338,12 +343,8 @@ module Meshtastic
     end
 
     public_class_method def self.send_input_event(opts = {})
-      event = opts[:event] || Meshtastic::AdminMessage::InputEvent.new(
-        event_code: opts[:event_code].to_i,
-        kb_char: opts[:kb_char].to_i,
-        touch_x: opts[:touch_x].to_i,
-        touch_y: opts[:touch_y].to_i
-      )
+      event = opts[:event] || Meshtastic::AdminMessage::InputEvent.new(event_code: opts[:event_code].to_i, kb_char: opts[:kb_char].to_i,
+                                                                       touch_x: opts[:touch_x].to_i, touch_y: opts[:touch_y].to_i)
       send(opts.merge(send_input_event: event))
     end
 
@@ -471,7 +472,8 @@ module Meshtastic
           channel: 'optional - routing channel index (default zero)',
           want_ack: 'optional - request routing acknowledgment, distinct from an admin reply',
           hop_limit: 'optional - maximum radio hop count',
-          psks: 'optional - MQTT channel key map; not public-key admin authorization',
+          channel_id: 'optional - exact MQTT channel name selecting one PSK and explicit AEAD mode',
+          psks: 'optional - MQTT name to Base64 legacy PSK or {psk: Base64, use_aead: boolean} map; not public-key admin authorization',
           pki_encrypted: 'optional - enable device-owned PKI on serial BLE or TCP; unsupported over MQTT',
           public_key: 'optional - recipient public-key bytes for radio PKI',
           last_packet_id: 'optional - previous packet number used by transport packet generation',
@@ -488,6 +490,10 @@ module Meshtastic
           timeout: 'optional - positive finite total response budget in seconds including session acquisition (default ten)'
         )
 
+        # Results distinguish :acknowledged, :device_verified and :readback.
+        # :device_verified requires a target/request-correlated ACK_PROOF_VALID from the radio queue.
+        # security_provenance retains raw proof/signature reports; verification is device_reported, never host-verified.
+
         # Decode protobuf bytes or an incoming admin packet.
         #{self}.decode(
           payload: 'optional - serialized AdminMessage bytes when packet is omitted',
@@ -526,8 +532,8 @@ module Meshtastic
         # Set the node owner User protobuf.
         #{self}.set_owner(
           owner: 'optional - Meshtastic::User protobuf to send as set_owner',
-          long_name: 'optional - owner long name when owner is omitted',
-          short_name: 'optional - owner short name when owner is omitted'
+          long_name: 'optional - owner long name, at most 24 UTF-8 bytes; empty means unchanged on firmware v2.8.1.8e6a88d',
+          short_name: 'optional - owner short name, at most four UTF-8 bytes; empty means unchanged'
         )
 
         # Request the node owner User protobuf.
@@ -643,11 +649,11 @@ module Meshtastic
         # Enable ham-radio identity parameters.
         #{self}.set_ham_mode(
           ham: 'optional - HamParameters protobuf to send',
-          call_sign: 'optional - amateur callsign when ham is omitted',
+          call_sign: 'optional - required within ham parameters, nonblank callsign at most seven UTF-8 bytes',
           tx_power: 'optional - transmit power when ham is omitted',
           frequency: 'optional - frequency in MHz when ham is omitted',
           short_name: 'optional - short name when ham is omitted',
-          long_name: 'optional - long name when ham is omitted'
+          long_name: 'optional - ham suffix at most fourteen UTF-8 bytes; composed CALL//suffix must fit 24 bytes; rejected, never truncated'
         )
 
         # Remove a node from the local nodedb by number.

data/lib/meshtastic/mesh_interface.rb

@@ -113,14 +113,14 @@ module Meshtastic
     def get_cipher_keys(opts = {})
       psks = opts[:psks]
 
-      psks.each_key do |key|
-        psk = psks[key]
-        padded_psk = psk.ljust(psk.length + ((4 - (psk.length % 4)) % 4), '=')
-        replaced_psk = padded_psk.gsub('-', '+').gsub('_', '/')
-        psks[key] = replaced_psk
-      end
+      psks.to_h do |name, value|
+        entry = value.is_a?(Hash) ? value.dup : { psk: value }
+        psk = entry[:psk]
+        raise ArgumentError, 'PSK must be a Base64 string' unless psk.is_a?(String)
 
-      psks
+        entry[:psk] = psk.tr('-_', '+/').ljust(psk.length + ((4 - (psk.length % 4)) % 4), '=')
+        [name, value.is_a?(Hash) ? entry : entry[:psk]]
+      end
     rescue StandardError => e
       raise e
     end
@@ -212,6 +212,8 @@ module Meshtastic
     #   psks: 'optional - hash of :channel => psk key value pairs (default: { LongFast: "AQ==" })'
     # )
     def send_packet(opts = {})
+      raise ArgumentError, 'use_aead belongs inside each psks channel record' if opts.key?(:use_aead)
+
       mesh_packet = opts[:mesh_packet]
       from = opts[:from] ||= '!00000b0b'
       # from_hex = from.delete('!').bytes.map { |b| b.to_s(16).rjust(2, '0') }.join if from.is_a?(String)
@@ -245,6 +247,9 @@ module Meshtastic
       # my_info = Meshtastic::FromRadio.my_info
       # wait_connected if to != my_info.my_node_num && my_info.is_a(Meshtastic::Deviceonly::MyInfo)
 
+      raise ArgumentError, 'MQTT does not support recipient public_key PKI encryption' if via == :mqtt && opts[:public_key] && !opts[:pki_encrypted]
+      raise ArgumentError, 'MQTT direct text requires unsupported PKI encryption; use a radio transport' if via == :mqtt && to != 0xffffffff && mesh_packet.decoded&.portnum == :TEXT_MESSAGE_APP
+
       mesh_packet.from = from
       mesh_packet.to = to
       mesh_packet.channel = channel
@@ -258,26 +263,24 @@ module Meshtastic
         raise ArgumentError, 'recipient public_key must contain 32 bytes' unless mesh_packet.public_key.bytesize == 32
       end
 
-      # When psks is nil/empty, leave the packet decoded so the radio (serial/TCP)
-      # device can apply the channel PSK itself. MQTT callers must pass psks so the
-      # ServiceEnvelope payload is pre-encrypted for the mesh.
+      # Select by exact name, never Hash insertion order when there are multiple keys.
+      selected_name = opts[:channel_id]&.to_s
       if psks && !psks.empty?
-        nonce_packet_id = [mesh_packet.id].pack('V').ljust(8, "\x00")
-        nonce_from_node = [from].pack('V').ljust(8, "\x00")
-        nonce = "#{nonce_packet_id}#{nonce_from_node}"
-
-        psk = psks[psks.keys.first]
-        dec_psk = Base64.strict_decode64(psk)
-        cipher = OpenSSL::Cipher.new('AES-128-CTR')
-        cipher = OpenSSL::Cipher.new('AES-256-CTR') if dec_psk.length == 32
-        cipher.encrypt
-        cipher.key = dec_psk
-        cipher.iv = nonce
-
-        decrypted_payload = mesh_packet.decoded.to_proto
-        encrypted_payload = cipher.update(decrypted_payload) + cipher.final
-
-        mesh_packet.encrypted = encrypted_payload
+        raise ArgumentError, 'Ambiguous duplicate channel names in psks' unless psks.keys.map(&:to_s).uniq.size == psks.size
+
+        selected_name ||= psks.keys.first.to_s if psks.size == 1
+        raise ArgumentError, 'channel_id required for ambiguous PSKs' unless selected_name
+        raise ArgumentError, 'MQTT topic conflicts with selected channel_id' if via == :mqtt && opts[:topic] && opts[:topic].split('/')[-2] != selected_name
+
+        psk = psks[selected_name] || psks[selected_name.to_sym]
+        raise ArgumentError, 'No PSK for selected channel_id' unless psk
+
+        config = channel_crypto(name: selected_name, value: psk)
+        mesh_packet.channel = config[:hash] if via == :mqtt
+        mesh_packet.encrypted = crypt_channel(config: config, message: mesh_packet.to_h,
+                                              bytes: mesh_packet.decoded.to_proto, encrypt: true)
+      elsif via == :mqtt
+        raise ArgumentError, 'MQTT requires an explicit channel PSK; plaintext fallback is disabled'
       end
       # puts mesh_packet.to_h
 
@@ -290,8 +293,7 @@ module Meshtastic
       when :mqtt
         service_envelope = Meshtastic::ServiceEnvelope.new
         service_envelope.packet = mesh_packet
-        # TODO: Add support for multiple PSKs by accepting channel_id
-        service_envelope.channel_id = psks.keys.first
+        service_envelope.channel_id = selected_name
         service_envelope.gateway_id = "!#{from.to_s(16).downcase}"
         send_to_mqtt(service_envelope: service_envelope)
       else
@@ -315,6 +317,8 @@ module Meshtastic
     #   psks: 'optional - hash of :channel => psk key value pairs (default: { LongFast: "AQ==" })'
     # )
     def send_data(opts = {})
+      raise ArgumentError, 'use_aead belongs inside each psks channel record' if opts.key?(:use_aead)
+
       # Send a text message to a node
       from = opts[:from] ||= '!00000b0b'
       # from_hex = from.delete('!').bytes.map { |b| b.to_s(16).rjust(2, '0') }.join if from.is_a?(String)
@@ -366,6 +370,8 @@ module Meshtastic
         hop_limit: hop_limit,
         pki_encrypted: opts.fetch(:pki_encrypted, false),
         public_key: opts[:public_key],
+        channel_id: opts[:channel_id],
+        topic: opts[:topic],
         psks: psks
       )
     rescue StandardError => e
@@ -387,6 +393,8 @@ module Meshtastic
     #   psks: 'optional - hash of :channel => psk key value pairs (default: { LongFast: "AQ==" })'
     # )
     def send_text(opts = {})
+      raise ArgumentError, 'use_aead belongs inside each psks channel record' if opts.key?(:use_aead)
+
       # Send a text message to a node
       from = opts[:from] ||= '!00000b0b'
       # from_hex = from.delete('!').bytes.map { |b| b.to_s(16).rjust(2, '0') }.join if from.is_a?(String)
@@ -443,6 +451,10 @@ module Meshtastic
         hop_limit: hop_limit,
         port_num: port_num,
         on_response: on_response,
+        pki_encrypted: opts.fetch(:pki_encrypted, false),
+        public_key: opts[:public_key],
+        channel_id: opts[:channel_id],
+        topic: opts[:topic],
         psks: psks
       )
     rescue StandardError => e
@@ -544,10 +556,71 @@ module Meshtastic
 
     private :decode_application_payload
 
+    # Firmware v2.8.1.8e6a88d: Channels::generateHash and CryptoEngine CCM.
+    def channel_crypto(opts = {})
+      value = opts[:value]
+      entry = value.is_a?(Hash) ? value : { psk: value, use_aead: false }
+      raise ArgumentError, 'Channel records require psk and explicit use_aead only' unless entry.keys.sort == %i[psk use_aead]
+
+      aead = entry[:use_aead]
+      raise ArgumentError, 'use_aead must be true or false' unless [true, false].include?(aead)
+
+      encoded = entry[:psk]
+      raise ArgumentError, 'PSK must be a Base64 string' unless encoded.is_a?(String)
+
+      encoded = encoded.tr('-_', '+/').ljust(encoded.length + ((4 - (encoded.length % 4)) % 4), '=')
+      key = Base64.strict_decode64(encoded)
+      if key.bytesize == 1 && key.getbyte(0).positive?
+        index = key.getbyte(0)
+        key = Base64.strict_decode64('1PG7OiApB1nwvP+rz05pAQ==')
+        key.setbyte(15, (key.getbyte(15) + index - 1) & 0xff)
+      end
+      raise ArgumentError, 'PSK must contain 16 or 32 bytes (or a nonzero one-byte firmware alias)' unless [16, 32].include?(key.bytesize)
+
+      { key: key, aead: aead, hash: (opts[:name].to_s.bytes + key.bytes).reduce(0, :^) ^ (aead ? 0xae : 0) }
+    end
+
+    def crypt_channel(opts = {})
+      config = opts[:config]
+      message = opts[:message]
+      encrypt = opts[:encrypt]
+      bytes = opts[:bytes]
+      aead = config[:aead]
+      key = config[:key]
+      cipher = OpenSSL::Cipher.new("AES-#{key.bytesize * 8}-#{aead ? 'CCM' : 'CTR'}")
+      encrypt ? cipher.encrypt : cipher.decrypt
+      if aead
+        raise ArgumentError, 'Truncated AEAD ciphertext' if !encrypt && bytes.bytesize <= 12
+
+        cipher.iv_len = 13
+        cipher.auth_tag_len = 12
+        unless encrypt
+          cipher.auth_tag = bytes.byteslice(-12, 12)
+          bytes = bytes.byteslice(0, bytes.bytesize - 12)
+        end
+      end
+      cipher.key = key
+      nonce = [message.fetch(:id, 0), 0, message.fetch(:from, 0), 0].pack('V4')
+      cipher.iv = aead ? nonce.byteslice(0, 13) : nonce
+      if aead
+        cipher.ccm_data_len = bytes.bytesize
+        cipher.auth_data = [message.fetch(:from, 0), message.fetch(:to, 0)].pack('V2')
+      end
+      result = (bytes.empty? ? ''.b : cipher.update(bytes)) + cipher.final
+      result += cipher.auth_tag(12) if aead && encrypt
+      result
+    end
+
+    private :channel_crypto, :crypt_channel
+
     # Decode only the selected channel key; never reinterpret PKI as PSK crypto.
     # AES-CTR parsing is not authentication or proof of origin.
     def decrypt_packet(opts = {})
       message = opts[:message]
+      source = opts.fetch(:source, :radio)
+      reported = message.slice(:xeddsa_signed, :ack_proof_status)
+      message[:security_provenance] = { source: source, verification: source == :radio ? :device_reported : :untrusted, reported: reported }
+      reported.each_key { |key| message.delete(key) } unless source == :radio
       return message if message[:decoded] || !message.key?(:encrypted)
 
       if message[:pki_encrypted]
@@ -557,32 +630,29 @@ module Meshtastic
 
       channel = opts[:channel]
       psks = opts[:psks] || {}
+      raise ArgumentError, 'Ambiguous duplicate channel names in psks' unless psks.keys.map(&:to_s).uniq.size == psks.size
+
       psk = psks[channel] || psks[channel.to_s] || psks[channel.to_s.to_sym] unless channel.nil?
       if channel.nil?
         # Encrypted radio packets carry an eight-bit name/key XOR hash, not a slot.
         candidates = psks.select do |name, value|
-          bytes = Base64.strict_decode64(value)
-          [16, 32].include?(bytes.bytesize) && (name.to_s.bytes + bytes.bytes).reduce(0, :^) == message.fetch(:channel, 0)
+          channel_crypto(name: name, value: value)[:hash] == message.fetch(:channel, 0)
         rescue ArgumentError
           false
         end
-        psk = candidates.values.first if candidates.size == 1
+        channel, psk = candidates.first if candidates.size == 1
       end
       unless psk
         message[:decryption_error] = 'No PSK for the selected channel'
         return message
       end
 
-      key = Base64.strict_decode64(psk)
-      raise ArgumentError, 'PSK must contain 16 or 32 bytes' unless [16, 32].include?(key.bytesize)
+      config = channel_crypto(name: channel, value: psk)
+      raise ArgumentError, 'Channel hash does not match selected key and mode' if opts[:source] == :mqtt && config[:hash] != message.fetch(:channel, 0)
 
-      cipher = OpenSSL::Cipher.new(key.bytesize == 32 ? 'AES-256-CTR' : 'AES-128-CTR')
-      cipher.decrypt
-      cipher.key = key
-      cipher.iv = [message.fetch(:id, 0), 0, message.fetch(:from, 0), 0].pack('V4')
-      ciphertext = message[:encrypted]
-      plaintext = (ciphertext.empty? ? ''.b : cipher.update(ciphertext)) + cipher.final
+      plaintext = crypt_channel(config: config, message: message, bytes: message[:encrypted], encrypt: false)
       message[:decoded] = Meshtastic::Data.decode(plaintext).to_h
+      message[:security_provenance][:channel_authentication] = config[:aead] ? :aead : :none
       message[:encrypted] = :decrypted
       message
     rescue ArgumentError, OpenSSL::Cipher::CipherError, Google::Protobuf::ParseError
@@ -623,7 +693,10 @@ module Meshtastic
           channel: 'optional - Channel (Default: 0)',
           want_ack: 'optional - Want Acknowledgement (Default: false)',
           hop_limit: 'optional - Hop Limit (Default: 3)',
-          psks: 'optional - hash of :channel => psk key value pairs (default: { LongFast: \"AQ==\" })'
+          pki_encrypted: 'optional - radio-owned PKI; requires psks: nil and a 32-byte recipient public_key',
+          public_key: 'optional - raw recipient key forwarded to the radio without host encryption',
+          channel_id: 'optional - exact channel name; required when multiple PSKs are supplied',
+          psks: 'optional - names to Base64 keys or { psk: Base64, use_aead: true/false }; nil delegates to radio'
         )
 
         #{self}.send_data(
@@ -636,7 +709,10 @@ module Meshtastic
           want_ack: 'optional - Want Acknowledgement (Default: false)',
           hop_limit: 'optional - Hop Limit (Default: 3)',
           port_num: 'optional - (Default: Meshtastic::PortNum::PRIVATE_APP)',
-          psks: 'optional - hash of :channel => psk key value pairs (default: { LongFast: \"AQ==\" })'
+          pki_encrypted: 'optional - radio-owned PKI; requires psks: nil and a 32-byte recipient public_key',
+          public_key: 'optional - raw recipient key forwarded to the radio without host encryption',
+          channel_id: 'optional - exact channel name; required when multiple PSKs are supplied',
+          psks: 'optional - names to Base64 keys or { psk: Base64, use_aead: true/false }; nil delegates to radio'
         )
 
         #{self}.send_text(
@@ -650,7 +726,10 @@ module Meshtastic
           want_response: 'optional - Want Response (Default: false)',
           hop_limit: 'optional - Hop Limit (Default: 3)',
           on_response: 'optional - Callback on Response',
-          psks: 'optional - hash of :channel => psk key value pairs (default: { LongFast: \"AQ==\" })'
+          pki_encrypted: 'optional - radio-owned PKI; requires psks: nil and a 32-byte recipient public_key',
+          public_key: 'optional - raw recipient key forwarded to the radio without host encryption',
+          channel_id: 'optional - exact channel name; required when multiple PSKs are supplied',
+          psks: 'optional - names to Base64 keys or { psk: Base64, use_aead: true/false }; nil delegates to radio'
         )
 
         # Binary codecs: Unishox2, ATAK V1/V2, Forwarder, Reticulum and PayloadFormats.
@@ -664,7 +743,8 @@ module Meshtastic
 
         #{self}.decrypt_packet(
           message: 'required - decoded MeshPacket hash, updated in place',
-          psks: 'required - channel names mapped to full Base64 AES keys',
+          psks: 'required - names to Base64 keys or { psk: Base64, use_aead: true/false }',
+          source: 'optional - :radio (device reports) or :mqtt (untrusted broker claims)',
           channel: 'optional - exact MQTT channel name; omitted selects unique radio channel hash'
         )
 

data/lib/meshtastic/module_config.rb

@@ -41,6 +41,8 @@ module Meshtastic
         # Legacy serial_obj:, bluetooth_obj:, tcp_obj:, mqtt_obj: remain accepted.
         # Supply one non-nil connection only; mixed connection options are rejected.
         # Remote setters inherit Admin automatic sessions, not persistence readback.
+        # Firmware v2.8.1.8e6a88d: exactly one selected module section is required.
+        # Empty outer messages and unknown enum values fail before any radio I/O.
 
         # Run the authors class method for this module.
         #{self}.authors

data/lib/meshtastic/mqtt.rb

@@ -72,16 +72,17 @@ module Meshtastic
 
     public_class_method def self.subscribe(opts = {})
       mqtt_obj = opts[:mqtt_obj]
+      raise ArgumentError, 'use_aead belongs inside each psks channel record' if opts.key?(:use_aead)
+
       root_topic = opts[:root_topic] ||= 'msh'
       region = opts[:region] ||= 'US'
       topic = opts[:topic] ||= '2/e/LongFast/#'
-      # TODO: Support Array of PSKs and attempt each until decrypted
+      # Exact channel-name selection; never probe alternative keys or modes.
 
       public_psk = '1PG7OiApB1nwvP+rz05pAQ=='
       psks = opts[:psks] ||= { LongFast: public_psk }
       raise 'ERROR: psks parameter must be a hash of :channel_id => psk key value pairs' unless psks.is_a?(Hash)
 
-      psks[:LongFast] = public_psk if psks[:LongFast] == 'AQ=='
       mui = Meshtastic::MeshInterface.new
       psks = mui.get_cipher_keys(psks: psks)
 
@@ -121,6 +122,10 @@ module Meshtastic
           next unless decoded_payload_hash[:packet].is_a?(Hash)
 
           message = decoded_payload_hash[:packet] if decoded_payload_hash.keys.include?(:packet)
+          mui.decrypt_packet(
+            message: message, psks: psks, source: :mqtt,
+            channel: decoded_payload_hash[:channel_id].to_s.empty? ? raw_topic.split('/')[-2].to_s : decoded_payload_hash[:channel_id]
+          )
           message[:topic] = raw_topic
           message[:node_id_from] = "!#{message[:from].to_i.to_s(16)}"
           message[:node_id_to] = "!#{message[:to].to_i.to_s(16)}"
@@ -137,11 +142,6 @@ module Meshtastic
             message[:public_key] = Base64.strict_encode64(raw_public_key)
           end
 
-          mui.decrypt_packet(
-            message: message, psks: psks,
-            channel: decoded_payload_hash[:channel_id].to_s.empty? ? raw_topic.split('/')[-2].to_s : decoded_payload_hash[:channel_id]
-          )
-
           if message[:decoded]
             # payload = Meshtastic::Data.decode(message[:decoded][:payload]).to_h
             payload = message[:decoded][:payload]
@@ -228,12 +228,13 @@ module Meshtastic
     #   psks: 'optional - hash of :channel_id => psk key value pairs (default: { LongFast: "AQ==" })'
     # )
     public_class_method def self.send_text(opts = {})
+      opts = opts.dup
       mqtt_obj = opts[:mqtt_obj]
       opts[:from] ||= mqtt_obj.client_id
       opts[:to] ||= '!ffffffff'
       opts[:root_topic] ||= 'msh'
       opts[:region] ||= 'US'
-      opts[:topic] ||= '2/e/LongFast/#'
+      opts[:topic] ||= "2/e/#{opts[:channel_id] || (opts[:psks]&.size == 1 ? opts[:psks].keys.first : 'LongFast')}/#"
       opts[:topic] = opts[:topic].to_s.gsub('/#', '')
       opts[:channel] ||= 6
       absolute_topic = "#{opts[:root_topic]}/#{opts[:region]}/#{opts[:topic]}/#{opts[:from]}"
@@ -260,7 +261,7 @@ module Meshtastic
       opts[:to] ||= '!ffffffff'
       opts[:root_topic] ||= 'msh'
       opts[:region] ||= 'US'
-      opts[:topic] ||= '2/e/LongFast/#'
+      opts[:topic] ||= "2/e/#{opts[:channel_id] || (opts[:psks]&.size == 1 ? opts[:psks].keys.first : 'LongFast')}/#"
       opts[:topic] = opts[:topic].to_s.gsub('/#', '')
       opts[:channel] ||= 6
       absolute_topic = "#{opts[:root_topic]}/#{opts[:region]}/#{opts[:topic]}/#{opts[:from]}"
@@ -314,7 +315,7 @@ module Meshtastic
           root_topic: 'optional - value for root_topic passed into subscribe',
           region: 'optional - value for region passed into subscribe',
           topic: 'optional - value for topic passed into subscribe',
-          psks: 'optional - value for psks passed into subscribe',
+          psks: 'optional - channel names to Base64 keys or { psk: Base64, use_aead: true/false }; configured mode only',
           qos: 'optional - value for qos passed into subscribe',
           json: 'optional - value for json passed into subscribe',
           exclude: 'optional - value for exclude passed into subscribe',
@@ -331,7 +332,11 @@ module Meshtastic
           root_topic: 'optional - value for root_topic passed into send_text',
           region: 'optional - value for region passed into send_text',
           topic: 'optional - value for topic passed into send_text',
-          channel: 'optional - value for channel passed into send_text',
+          channel_id: 'optional - exact PSK channel name; required for multiple keys',
+          psks: 'optional - channel names to Base64 keys or { psk: Base64, use_aead: true/false }',
+          pki_encrypted: 'optional - unsupported on MQTT; raises rather than downgrades',
+          public_key: 'optional - unsupported recipient PKI key; raises on MQTT',
+          channel: 'optional - legacy value ignored; firmware hash is computed from selected name, key and mode',
           via: 'optional - value for via passed into send_text',
           text: 'optional - value for text passed into send_text'
         )
@@ -345,7 +350,11 @@ module Meshtastic
           root_topic: 'optional - value for root_topic passed into send_data',
           region: 'optional - value for region passed into send_data',
           topic: 'optional - value for topic passed into send_data',
-          channel: 'optional - value for channel passed into send_data',
+          channel_id: 'optional - exact PSK channel name; required for multiple keys',
+          psks: 'optional - channel names to Base64 keys or { psk: Base64, use_aead: true/false }',
+          pki_encrypted: 'optional - unsupported on MQTT; raises rather than downgrades',
+          public_key: 'optional - unsupported recipient PKI key; raises on MQTT',
+          channel: 'optional - legacy value ignored; firmware hash is computed from selected name, key and mode',
           via: 'optional - value for via passed into send_data'
         )
 

data/lib/meshtastic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Meshtastic
-  VERSION = '0.0.187'
+  VERSION = '0.0.188'
 end

data/lib/meshtastic/waypoint.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'meshtastic/mesh_pb'
+
+module Meshtastic
+  class Waypoint
+    public_class_method def self.build(opts = {})
+      fields = opts.fetch(:fields, {})
+      raise ArgumentError, 'fields must be a Waypoint field Hash' unless fields.is_a?(Hash)
+      raise ArgumentError, 'nil fields are not valid waypoint values' if fields.values.any?(&:nil?)
+
+      box = fields[:bounding_box] || fields['bounding_box']
+      raise ArgumentError, 'bounding_box coordinates cannot be nil' if box.is_a?(Hash) && box.values.any?(&:nil?)
+
+      waypoint = new(fields)
+      raise ArgumentError, 'latitude_i and longitude_i must be supplied together' if !waypoint.has_latitude_i? != !waypoint.has_longitude_i?
+      raise ArgumentError, 'a circular geofence requires latitude_i and longitude_i' if waypoint.geofence_radius.positive? && !waypoint.has_latitude_i?
+
+      validate_coordinates(fields: { latitude_i: waypoint.latitude_i, longitude_i: waypoint.longitude_i })
+      if waypoint.bounding_box
+        box = waypoint.bounding_box
+        validate_coordinates(fields: { latitude_south_i: box.latitude_south_i, latitude_north_i: box.latitude_north_i,
+                                       longitude_west_i: box.longitude_west_i, longitude_east_i: box.longitude_east_i })
+        raise ArgumentError, 'bounding_box requires south <= north and west <= east; split antimeridian regions' unless box.latitude_south_i <= box.latitude_north_i && box.longitude_west_i <= box.longitude_east_i
+      end
+      { name: 29, description: 99 }.each do |field, maximum|
+        text = waypoint.public_send(field)
+        raise ArgumentError, "#{field} must be valid NUL-free UTF-8 and at most #{maximum} bytes" unless text.valid_encoding? && !text.include?("\0") && text.bytesize <= maximum
+      end
+      waypoint
+    rescue TypeError, RangeError, EncodingError => e
+      raise ArgumentError, e.message
+    end
+
+    private_class_method def self.validate_coordinates(opts = {})
+      opts.fetch(:fields).each do |field, value|
+        maximum = field.to_s.start_with?('latitude') ? 900_000_000 : 1_800_000_000
+        raise ArgumentError, "#{field} is outside geographic bounds" unless value.is_a?(Integer) && value.between?(-maximum, maximum)
+      end
+    end
+
+    public_class_method def self.transmit(opts = {})
+      waypoint = opts[:waypoint]
+      raise ArgumentError, 'waypoint must be a Waypoint protobuf' if waypoint && !waypoint.is_a?(self)
+      raise ArgumentError, 'supply waypoint or fields, not both' if waypoint && opts.key?(:fields)
+
+      waypoint = build(fields: waypoint ? waypoint.to_h : opts.fetch(:fields, {}))
+      data = Meshtastic::Data.new(portnum: :WAYPOINT_APP, payload: waypoint.to_proto)
+      Meshtastic.deliver_data(opts.except(:waypoint, :fields).merge(data: data, port_num: Meshtastic::PortNum::WAYPOINT_APP))
+    end
+
+    public_class_method def self.authors
+      "AUTHOR(S):\n        0day Inc. <support@0dayinc.com>\n      "
+    end
+
+    public_class_method def self.help
+      puts "USAGE:
+        # Build a waypoint or geofence protobuf.
+        #{self}.build(fields: 'optional - exact Waypoint field hash; coordinates are integer degrees times 10000000; default empty message')
+        # fields: latitude_i and longitude_i must be paired, within +/-90 and +/-180 degrees scaled by 10000000.
+        # geofence_radius is uint32 meters, positive requires center; zero means no circle.
+        # bounding_box uses longitude_west_i, latitude_south_i, longitude_east_i, latitude_north_i.
+        # Require west <= east and south <= north; circle and box can coexist.
+        # notify_on_enter, notify_on_exit and notify_favorites_only are booleans resolved on receivers.
+        # name and description allow 29 and 99 UTF-8 bytes respectively, without embedded NUL.
+        # id, expire, locked_to and icon retain the exact protobuf integer semantics.
+        # Send a validated waypoint over WAYPOINT_APP.
+        #{self}.transmit(
+          waypoint: 'optional - Waypoint protobuf to validate and transmit instead of fields',
+          fields: 'optional - exact Waypoint fields as accepted by build; default empty message',
+          serial_obj: 'optional - connected serial handle; choose exactly one transport',
+          bluetooth_obj: 'optional - connected Bluetooth handle',
+          tcp_obj: 'optional - connected TCP handle',
+          mqtt_obj: 'optional - connected MQTT client; accepts channel_id and psks',
+          to: 'optional - destination !eighthex node ID; defaults to broadcast',
+          want_ack: 'optional - request routing acknowledgment, not proof of delivery',
+          pki_encrypted: 'optional - radio-owned PKI encryption; MQTT PKI unsupported',
+          public_key: 'optional - recipient public-key bytes for radio PKI'
+        )
+        # Print the module author information.
+        #{self}.authors
+      "
+    end
+  end
+end

data/lib/meshtastic.rb

@@ -115,3 +115,4 @@ require 'meshtastic/paxcount'
 require 'meshtastic/position'
 require 'meshtastic/reticulum'
 require 'meshtastic/telemetry'
+require 'meshtastic/waypoint'