meshtastic 0.0.184 → 0.0.185

data/spec/lib/meshtastic/forwarder_spec.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'Meshtastic::Forwarder' do
+  it 'decodes a libcotshrink wire event rather than treating it as zlib XML' do
+    require 'meshtastic/forwarder'
+    # Hand-authored protobuf wire: uid="test", omitted type means PLI.
+    result = Meshtastic::Forwarder.decode(payload: "\x0a\x04test".b)
+    expect(result[:format]).to eq(:libcotshrink_protobuf)
+    expect(result[:event]).to include(uid: 'test', type: 'a-f-G-U-C', lat: 0.0, lon: 0.0)
+  end
+
+  it 'unwraps GZIP and decodes packed fields and nested detail' do
+    require 'meshtastic/forwarder'
+    require 'zlib'
+    packed = (123 << 39) | (60 << 16) | 3000
+    message = Meshtastic::ForwarderProtobuf::CotEvent.new(
+      uid: 'example', lat: 123_456_789, lon: -987_654_321,
+      customBytes: packed, customBytesExt: 2 << 61,
+      detail: { contact: { callsign: 'EXAMPLE' } }
+    )
+    result = Meshtastic::Forwarder.decode(payload: Zlib.gzip(message.to_proto), start_of_year: Time.utc(2025))
+    expect(result).to include(compression: :gzip)
+    expect(result[:protobuf][:detail][:contact][:callsign]).to eq('EXAMPLE')
+    expect(result[:event]).to include(lat: 12.3456789, lon: -98.7654321, hae: 100.0,
+                                      time: '2025-01-01T00:02:03Z', stale: '2025-01-01T00:03:03Z', how: 'm-g')
+    expect(result[:extensions]).to include(battery: 0, readiness: false, role: 'Team Member')
+  end
+
+  it 'bounds compressed and decompressed input and rejects damaged gzip' do
+    require 'meshtastic/forwarder'
+    require 'zlib'
+    expect { Meshtastic::Forwarder.decode(payload: Zlib.gzip('a' * 100_000), max_bytes: 100) }.to raise_error(ArgumentError, /limit/)
+    expect { Meshtastic::Forwarder.decode(payload: 'a' * 101, max_bytes: 100) }.to raise_error(ArgumentError, /limit/)
+    expect { Meshtastic::Forwarder.decode(payload: Zlib.gzip('abc')[0...-4]) }.to raise_error(ArgumentError, /GZIP/)
+  end
+
+  it 'recognizes EXI but explicitly reports the missing decoder' do
+    require 'meshtastic/forwarder'
+    ["\x80\x00".b, "$EXI\x80\x00".b].each do |payload|
+      expect { Meshtastic::Forwarder.decode(payload: payload) }.to raise_error(Meshtastic::Forwarder::UnsupportedFormat, /EXI/)
+    end
+  end
+
+  it 'does not invent a year and honors compact null sentinels' do
+    require 'meshtastic/forwarder'
+    message = Meshtastic::ForwarderProtobuf::CotEvent.new(uid: 'example', customBytesExt: 32 << 55)
+    result = Meshtastic::Forwarder.decode(payload: message.to_proto)
+    expect(result[:event]).to include(time_offset_seconds: 0, stale_after_seconds: 0)
+    expect(result[:event]).not_to have_key(:time)
+    expect(result[:extensions][:geopointsrc]).to be_nil
+  end
+
+  it 'decodes real Forwarder nibble headers and separates incomplete chunks' do
+    require 'meshtastic/forwarder'
+    result = Meshtastic::Forwarder.decode_packet(payload: "\x01\x0a\x04test".b)
+    expect(result[:event][:uid]).to eq('test')
+    expect(Meshtastic::Forwarder.decode_packet(payload: "\x02\x0a\x04".b)).to include(
+      format: :forwarder_fragment, index: 0, count: 2, body: "\x0a\x04".b
+    )
+    result = Meshtastic::Forwarder.decode_chunks(chunks: ["\x12test".b, "\x02\x0a\x04".b])
+    expect(result[:event][:uid]).to eq('test')
+    expect { Meshtastic::Forwarder.decode_chunks(chunks: ["\x02\x0a\x04".b]) }.to raise_error(ArgumentError, /missing/)
+    expect { Meshtastic::Forwarder.decode_packet(payload: "\x22bad".b) }.to raise_error(ArgumentError, /header/)
+    expect { Meshtastic::Forwarder.decode_chunks(chunks: ["\x02a".b, "\x02b".b]) }.to raise_error(ArgumentError, /duplicate/)
+  end
+
+  it 'returns discovery broadcasts separately from CoT' do
+    require 'meshtastic/forwarder'
+    result = Meshtastic::Forwarder.decode_packet(payload: "\x01ATAKBCAST,!aabbccdd,example,EXAMPLE,1".b)
+    expect(result).to include(format: :forwarder_discovery, mesh_id: '!aabbccdd', uid: 'example', callsign: 'EXAMPLE', initial: true)
+  end
+
+  it 'decodes independent protoc wire with the complete upstream detail graph' do
+    require 'meshtastic/forwarder'
+    # Produced by protoc --encode against pinned upstream .proto files, not this Ruby encoder.
+    wire = ['0a0e736368656d612d6669787475726518aab4de7520e1a2f3ad07282a300739b872c102006702004100000000000000404a1e0a090a074558414d504c452a0042008201008a01009201009a0100b20100'].pack('H*')
+    result = Meshtastic::Forwarder.decode(payload: wire)
+    expect(result[:event]).to include(uid: 'schema-fixture', lat: 12.3456789, lon: -98.7654321, ce: 42, le: 7)
+    expect(result[:protobuf][:detail].keys).to contain_exactly(:contact, :remarks, :chat, :route, :sensor, :video, :geoFence, :medevac)
+  end
+
+  it 'enforces packet limits even for discovery and incomplete fragments' do
+    require 'meshtastic/forwarder'
+    expect { Meshtastic::Forwarder.decode_packet(payload: "\x02abc".b, max_bytes: 2) }.to raise_error(ArgumentError, /limit/)
+    expect { Meshtastic::Forwarder.decode_packet(payload: "\x01ATAKBCAST,a,b,c,1".b, max_bytes: 2) }.to raise_error(ArgumentError, /limit/)
+    expect { Meshtastic::Forwarder.decode_chunks(chunks: ["\x02abc".b, "\x12def".b], max_bytes: 5) }.to raise_error(ArgumentError, /limit/)
+  end
+
+  it 'rejects invalid mapped values and malformed protobuf' do
+    require 'meshtastic/forwarder'
+    message = Meshtastic::ForwarderProtobuf::CotEvent.new(uid: 'example', customBytesExt: 7 << 61)
+    expect { Meshtastic::Forwarder.decode(payload: message.to_proto) }.to raise_error(ArgumentError, /mapping/)
+    expect { Meshtastic::Forwarder.decode(payload: "\x0a\x08x".b) }.to raise_error(ArgumentError, /protobuf/)
+  end
+end

data/spec/lib/meshtastic/mesh_interface_spec.rb

@@ -1,8 +1,177 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../../support/payload_fixtures'
 
 describe Meshtastic::MeshInterface do
+  include PayloadFixtures
+
+  it 'inventories every bundled port exactly once and exercises each through transport fixtures' do
+    ports = described_class::PROTOBUF_PAYLOADS.keys + described_class::TEXT_PAYLOADS + described_class::BINARY_PAYLOADS + described_class::RAW_PAYLOADS + [:PRIVATE_APP]
+    expect(ports.sort).to eq(Meshtastic::PortNum.constants.sort)
+    expect(payload_cases.map(&:first).grep(Symbol).uniq.sort).to eq(ports.sort)
+    doc = File.read(File.expand_path('../../../documentation/mesh-interface.md', __dir__))
+    rows = doc.scan(/^\| (\d+) \| ([A-Z0-9_]+) \|/).to_h.transform_values(&:to_sym)
+    expect(rows).to eq(ports.to_h { |port| [Meshtastic::PortNum.resolve(port).to_s, port] })
+  end
+
+  it 'decodes default proto3 application messages even when Data omits payload bytes' do
+    data = Meshtastic::Data.new(portnum: :ROUTING_APP).to_h
+    expect(described_class.new.decode_payload(payload: data[:payload], msg_type: data[:portnum])).to eq({})
+    expect(described_class.new.decode_payload(payload: ''.b, msg_type: 5)).to eq({})
+  end
+
+  {
+    REMOTE_HARDWARE_APP: :HardwareMessage, POSITION_APP: :Position, NODEINFO_APP: :User,
+    ROUTING_APP: :Routing, ADMIN_APP: :AdminMessage, WAYPOINT_APP: :Waypoint,
+    KEY_VERIFICATION_APP: :KeyVerification, REMOTE_SHELL_APP: :RemoteShell,
+    PAXCOUNTER_APP: :Paxcount, STORE_FORWARD_PLUSPLUS_APP: :StoreForwardPlusPlus,
+    NODE_STATUS_APP: :StatusMessage, MESH_BEACON_APP: :MeshBeacon,
+    STORE_FORWARD_APP: :StoreAndForward, TELEMETRY_APP: :Telemetry,
+    SIMULATOR_APP: :Compressed, TRACEROUTE_APP: :RouteDiscovery,
+    NEIGHBORINFO_APP: :NeighborInfo, ATAK_PLUGIN: :TAKPacket, MAP_REPORT_APP: :MapReport,
+    POWERSTRESS_APP: :PowerStressMessage, LORAWAN_BRIDGE: :LoRaWANBridge, ATAK_PLUGIN_V2: :TAKPacketV2
+  }.each do |port, schema|
+    it "decodes empty #{port} using #{schema}, with symbolic and numeric portnums" do
+      [port, Meshtastic::PortNum.resolve(port)].each do |portnum|
+        [nil, ''.b].each do |bytes|
+          expect(described_class.new.decode_payload(payload: bytes, msg_type: portnum)).to eq(Meshtastic.const_get(schema).new.to_h)
+        end
+      end
+    end
+  end
+end
+
+describe Meshtastic::MeshInterface, 'simulator and text decoding' do
+  it 'dispatches nested simulator data through its contained application port' do
+    position = Meshtastic::Position.new(latitude_i: 10_000_000).to_proto
+    inner = Meshtastic::Compressed.new(portnum: :POSITION_APP, data: position).to_proto
+    outer = Meshtastic::Compressed.new(portnum: :SIMULATOR_APP, data: inner).to_proto
+    result = described_class.new.decode_payload(payload: outer, msg_type: 69)
+    expect(result.dig(:data, :data)).to include(latitude_i: 10_000_000, latitude: 1.0)
+  end
+
+  it 'bounds simulator decoding to eight wrappers and preserves the remaining wire bytes' do
+    remaining = Meshtastic::Compressed.new(portnum: :TEXT_MESSAGE_APP, data: 'still encoded').to_proto
+    wire = remaining
+    8.times { wire = Meshtastic::Compressed.new(portnum: :SIMULATOR_APP, data: wire).to_proto }
+    result = described_class.new.decode_payload(payload: wire, msg_type: :SIMULATOR_APP)
+    8.times { result = result.fetch(:data) }
+    expect(result).to eq(remaining)
+  end
+
+  it 'uses unknown port zero when a simulator wrapper omits its portnum' do
+    wire = Meshtastic::Compressed.new(data: "\xff\x00".b).to_proto
+    expect(described_class.new.decode_payload(payload: wire, msg_type: :SIMULATOR_APP)).to eq(data: "\xff\x00".b)
+    expect(described_class.new.decode_payload(payload: nil, msg_type: :SIMULATOR_APP)).to eq({})
+  end
+
+  it 'decodes omitted simulator data using the known inner proto3 schema' do
+    wire = Meshtastic::Compressed.new(portnum: :ROUTING_APP).to_proto
+    expect(described_class.new.decode_payload(payload: wire, msg_type: :SIMULATOR_APP)).to eq(portnum: :ROUTING_APP, data: {})
+  end
+
+  it 'preserves malformed simulator wrappers and malformed inner data' do
+    mesh = described_class.new
+    raw = "\xff".b
+    expect(mesh.decode_payload(payload: raw, msg_type: :SIMULATOR_APP)).to eq(raw)
+    %i[POSITION_APP SIMULATOR_APP].each do |port|
+      wire = Meshtastic::Compressed.new(portnum: port, data: raw).to_proto
+      expect(mesh.decode_payload(payload: wire, msg_type: :SIMULATOR_APP)).to eq(portnum: port, data: raw)
+    end
+  end
+
+  it 'still dispatches a non-simulator leaf after eight wrappers' do
+    wire = Meshtastic::Compressed.new(portnum: :ROUTING_APP).to_proto
+    7.times { wire = Meshtastic::Compressed.new(portnum: :SIMULATOR_APP, data: wire).to_proto }
+    result = described_class.new.decode_payload(payload: wire, msg_type: :SIMULATOR_APP)
+    8.times { result = result.fetch(:data) }
+    expect(result).to eq({})
+  end
+
+  it 'scrubs text for display without mutating the original wire bytes' do
+    raw = "hello\xff\x00".b.freeze
+    result = described_class.new.decode_payload(payload: raw, msg_type: :TEXT_MESSAGE_APP)
+    expect(result).to eq("hello\uFFFD\x00")
+    expect(result.encoding).to eq(Encoding::UTF_8)
+    expect(raw.bytes).to eq([104, 101, 108, 108, 111, 255, 0])
+    expect(raw.encoding).to eq(Encoding::ASCII_8BIT)
+  end
+end
+
+describe Meshtastic::MeshInterface do
+  it 'treats sensor, alert, reply and range test payloads as text' do
+    %i[DETECTION_SENSOR_APP ALERT_APP REPLY_APP RANGE_TEST_APP].each do |port|
+      expect(described_class.new.decode_payload(payload: "\x08\x01", msg_type: port)).to eq("\x08\x01")
+      expect(described_class.new.decode_payload(payload: nil, msg_type: port)).to eq('')
+    end
+  end
+
+  it 'preserves opaque binary data rather than guessing a protobuf schema' do
+    %i[UNKNOWN_APP SERIAL_APP PRIVATE_APP].each do |port|
+      expect(described_class.new.decode_payload(payload: "\x08\x01".b, msg_type: port)).to eq("\x08\x01".b)
+    end
+  end
+
+  it 'preserves malformed protobuf bytes rather than terminating reception' do
+    expect(described_class.new.decode_payload(payload: "\xff".b, msg_type: :POSITION_APP)).to eq("\xff".b)
+  end
+
+  it 'preserves V2 wire bytes if the optional native library is unavailable' do
+    require 'meshtastic/payload_compression'
+    raw = "\x00compressed".b
+    allow(Meshtastic::PayloadCompression).to receive(:decode_v2).and_raise(Meshtastic::PayloadCompression::Unavailable, 'missing libzstd')
+    expect(described_class.new.decode_payload(payload: raw, msg_type: 78)).to eq(raw)
+  end
+
+  it 'uses the same codec dispatcher inside simulator wrappers' do
+    raw = ['8767c714bdeb7c74'].pack('H*')
+    wire = Meshtastic::Compressed.new(portnum: :TEXT_MESSAGE_COMPRESSED_APP, data: raw).to_proto
+    expect(described_class.new.decode_payload(payload: wire, msg_type: 69)).to eq(portnum: :TEXT_MESSAGE_COMPRESSED_APP, data: 'Hello world')
+  end
+
+  it 'selects radio ciphertext by channel hash and refuses ambiguous keys' do
+    key = 'k' * 32
+    name = 'Custom'
+    hash = (name.bytes + key.bytes).reduce(0, :^)
+    cipher = OpenSSL::Cipher.new('AES-256-CTR')
+    cipher.encrypt
+    cipher.key = key
+    cipher.iv = [42, 0, 123, 0].pack('V4')
+    data = Meshtastic::Data.new(portnum: :NODE_STATUS_APP, payload: Meshtastic::StatusMessage.new(status: 'ok').to_proto)
+    encrypted = cipher.update(data.to_proto) + cipher.final
+    packet = { id: 42, from: 123, channel: hash, encrypted: encrypted }
+    keys = { name => Base64.strict_encode64(key) }
+    result = described_class.new.decrypt_packet(message: packet.dup, psks: keys)
+    expect(result[:decoded]).to eq(data.to_h)
+    collision = keys.merge(name.reverse => Base64.strict_encode64(key))
+    result = described_class.new.decrypt_packet(message: packet.dup, psks: collision)
+    expect(result[:decoded]).to be_nil
+    expect(result[:encrypted]).to eq(encrypted)
+  end
+
+  it 'preserves already decoded PKI packets and ciphertext on invalid channel keys' do
+    decoded = { decoded: { portnum: :ROUTING_APP }, pki_encrypted: true }
+    expect(OpenSSL::Cipher).not_to receive(:new)
+    expect(described_class.new.decrypt_packet(message: decoded, psks: {}, channel: 'test')).to eq(decoded)
+    ['not base64!', Base64.strict_encode64('short')].each do |key|
+      packet = { encrypted: 'ciphertext' }
+      result = described_class.new.decrypt_packet(message: packet, psks: { test: key }, channel: 'test')
+      expect(result[:encrypted]).to eq('ciphertext')
+      expect(result[:decoded]).to be_nil
+      expect(result[:decryption_error]).to match(/Unable to decode/)
+    end
+  end
+
+  it 'preserves unsupported payloads without leaking them to diagnostic output' do
+    [:PRIVATE_APP, 400, :UNRECOGNIZED_APP].each do |port|
+      expect do
+        result = described_class.new.decode_payload(payload: 'secret payload', msg_type: port)
+        expect(result).to eq('secret payload')
+      end.not_to output.to_stdout
+    end
+  end
+
   it 'rejects PKI on MQTT instead of falling back to channel encryption' do
     expect do
       described_class.new.send_data(

data/spec/lib/meshtastic/mqtt_spec.rb

@@ -1,8 +1,34 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../../support/payload_fixtures'
 
 describe Meshtastic::MQTT do # rubocop:disable Metrics/BlockLength
+  include PayloadFixtures
+
+  it 'decodes every fixture from already decoded and AES encrypted ServiceEnvelopes without losing subsequent packets' do
+    [false, true].each do |encrypted|
+      client = fake_mqtt_obj
+      payload_cases.each do |port, bytes, _expected|
+        packet = payload_radio(port, bytes).packet
+        if encrypted
+          cipher = OpenSSL::Cipher.new('AES-128-CTR')
+          cipher.encrypt
+          cipher.key = Base64.strict_decode64('1PG7OiApB1nwvP+rz05pAQ==')
+          cipher.iv = [42, 0, 123, 0].pack('V4')
+          data = packet.decoded.to_proto
+          packet.encrypted = (data.empty? ? ''.b : cipher.update(data)) + cipher.final
+        end
+        envelope = Meshtastic::ServiceEnvelope.new(packet: packet, channel_id: 'LongFast')
+        client.incoming << mqtt_packet(topic: 'msh/US/2/e/LongFast/!0000007b', payload: envelope.to_proto)
+      end
+      client.incoming << nil
+      received = []
+      described_class.subscribe(mqtt_obj: client) { |message| received << message.dig(:packet, :decoded, :payload) }
+      expect(received).to eq(payload_cases.map(&:last))
+    end
+  end
+
   def fake_mqtt_obj(client_id: '00000b0b')
     published = []
     subscribed = []
@@ -104,6 +130,36 @@ describe Meshtastic::MQTT do # rubocop:disable Metrics/BlockLength
   end
 
   describe 'mqtt reception' do
+    it 'does not apply a channel PSK to PKI ciphertext or fall back for an unknown channel' do
+      [true, false].each do |pki|
+        client = fake_mqtt_obj
+        packet = Meshtastic::MeshPacket.new(id: 42, from: 123, encrypted: 'ciphertext', pki_encrypted: pki)
+        envelope = Meshtastic::ServiceEnvelope.new(packet: packet, channel_id: 'Other')
+        client.incoming << mqtt_packet(topic: 'msh/US/2/e/Other/!0000007b', payload: envelope.to_proto)
+        client.incoming << nil
+        received = []
+        expect(OpenSSL::Cipher).not_to receive(:new)
+        described_class.subscribe(mqtt_obj: client) { |message| received << message }
+        expect(received.first.dig(:packet, :encrypted)).to eq('ciphertext')
+        expect(received.first.dig(:packet, :decoded)).to be_nil
+        expect(received.first.dig(:packet, :decryption_error)).to match(/PKI|No PSK/)
+      end
+    end
+
+    it 'does not substitute radio hash selection when MQTT channel identity is missing' do
+      client = fake_mqtt_obj
+      key = Base64.strict_decode64('1PG7OiApB1nwvP+rz05pAQ==')
+      hash = ('LongFast'.bytes + key.bytes).reduce(0, :^)
+      envelope = Meshtastic::ServiceEnvelope.new(packet: Meshtastic::MeshPacket.new(channel: hash, encrypted: 'ciphertext'))
+      client.incoming << mqtt_packet(topic: '', payload: envelope.to_proto)
+      client.incoming << nil
+      expect(OpenSSL::Cipher).not_to receive(:new)
+      described_class.subscribe(mqtt_obj: client) do |message|
+        expect(message.dig(:packet, :encrypted)).to eq('ciphertext')
+        expect(message.dig(:packet, :decryption_error)).to match(/No PSK/)
+      end
+    end
+
     it 'decrypts a published text message as UTF-8, never as a nested protobuf' do
       text = "\n\x02hi"
       _mqtt_obj, received = publish_and_subscribe(text: text, from: '!00000b0b', psks: { LongFast: 'AQ==' })

data/spec/lib/meshtastic/payload_compression_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'meshtastic/payload_compression'
+require_relative '../../support/tak_codec_fixtures'
+
+describe 'Meshtastic::PayloadCompression' do
+  it 'rejects oversized decoded frames without allocating their advertised size' do
+    # libzstd ZSTD_compress level 3, input: 4097 a bytes; magic stripped.
+    bomb = ['0060010f4d00001061610100fcf70116'].pack('H*')
+    expect { Meshtastic::PayloadCompression.decode_v2(payload: bomb) }.to raise_error(ArgumentError, /4096/)
+    expect { Meshtastic::PayloadCompression.decode_v2(payload: "\xff".b + ('a' * 4097)) }.to raise_error(ArgumentError, /4097/)
+  end
+
+  it 'ignores reserved flag bits and rejects trailing or truncated frames' do
+    _, hex, proto = TAK_CODEC_FIXTURES.first
+    wire = [hex].pack('H*')
+    wire.setbyte(0, wire.getbyte(0) | 0xc0)
+    expect(Meshtastic::PayloadCompression.decode_v2(payload: wire)).to eq([proto].pack('H*'))
+    ["#{wire}x", wire.byteslice(0...-1), "\x02".b, ''.b].each do |bad|
+      expect { Meshtastic::PayloadCompression.decode_v2(payload: bad) }.to raise_error(ArgumentError)
+    end
+  end
+
+  it 'does not require a native library for raw proto3 empty messages' do
+    expect(Meshtastic::PayloadCompression).not_to receive(:native)
+    expect(Meshtastic::PayloadCompression.decode_v2(payload: "\xff".b)).to eq(''.b)
+  end
+
+  it 'reports native availability failures explicitly' do
+    require 'fiddle'
+    allow(Fiddle).to receive(:dlopen).and_raise(Fiddle::DLError, 'not installed')
+    expect { Meshtastic::PayloadCompression.decode_v2(payload: [TAK_CODEC_FIXTURES.first[1]].pack('H*')) }
+      .to raise_error(Meshtastic::PayloadCompression::Unavailable, /libzstd/)
+  end
+
+  it 'decodes every official SDK golden frame to the exact protobuf bytes' do
+    TAK_CODEC_FIXTURES.each do |name, wire, protobuf|
+      expect(Meshtastic::PayloadCompression.decode_v2(payload: [wire].pack('H*')))
+        .to eq([protobuf].pack('H*')), name
+    end
+  end
+end

data/spec/lib/meshtastic/payload_formats_spec.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'meshtastic/payload_formats'
+
+RSpec.describe 'Meshtastic::PayloadFormats' do
+  def decode(port, hex)
+    Meshtastic::PayloadFormats.decode(portnum: port, payload: [hex.delete(' ')].pack('H*'))
+  end
+
+  it 'parses an RFC 791 IPv4 header and preserves the upper-layer bytes' do
+    # RFC 791 figure 5, instantiated with documentation-only addresses/data.
+    result = decode(33, '45000015006f00007b012b77 0a000001 0a000002 00')
+    expect(result).to include(format: :ip, version: 4, header_length: 20, total_length: 21,
+                              source: '10.0.0.1', destination: '10.0.0.2', protocol: 1, ttl: 123,
+                              identification: 111, header_checksum_valid: true)
+    expect(result[:body].bytesize).to eq(1)
+    expect(decode(33, '45000029')[:status]).to eq(:malformed)
+  end
+
+  it 'parses an RFC 8200 IPv6 base header without inventing extension decoding' do
+    result = decode(33, '6000000000033b40 20010db8000000000000000000000001 20010db8000000000000000000000002 010203')
+    expect(result).to include(version: 6, source: '2001:db8::1', destination: '2001:db8::2', next_header: 59, hop_limit: 64)
+    expect(result[:body].unpack1('H*')).to eq('010203')
+  end
+
+  it 'leaves ZPS opaque unless its experimental ESP32 dialect is explicitly selected' do
+    # ZPSPlugin::outBufAdd + encodeBSS: uint64 timestamp, reserved word, packed scan.
+    bytes = ['0100000000000000 0000000000000000 ffeeddccbbaa063c'.delete(' ')].pack('H*')
+    expect(Meshtastic::PayloadFormats.decode(portnum: 68, payload: bytes)[:status]).to eq(:unsupported)
+    result = Meshtastic::PayloadFormats.decode(portnum: 68, payload: bytes, zps_profile: :esp32_legacy)
+    expect(result).to include(format: :zps, timestamp: 1, profile: :esp32_legacy)
+    expect(result[:records]).to eq([{ kind: :wifi, address: 'aa:bb:cc:dd:ee:ff', channel: 6, rssi: -60 }])
+  end
+
+  it 'optionally decodes real native Codec2 encoder output to signed PCM through Ruby Fiddle' do
+    require 'fiddle'
+    begin
+      library = Fiddle.dlopen('libcodec2.so')
+    rescue Fiddle::DLError
+      skip 'optional libcodec2 is not installed'
+    end
+    create = Fiddle::Function.new(library['codec2_create'], [Fiddle::TYPE_INT], Fiddle::TYPE_VOIDP)
+    destroy = Fiddle::Function.new(library['codec2_destroy'], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_VOID)
+    encode = Fiddle::Function.new(library['codec2_encode'], [Fiddle::TYPE_VOIDP] * 3, Fiddle::TYPE_VOID)
+    context = create.call(0)
+    frame = "\0".b * 8
+    encode.call(context, frame, Array.new(160, 0).pack('s*'))
+    destroy.call(context)
+    result = Meshtastic::PayloadFormats.decode(portnum: 9, payload: [0xc0, 0xde, 0xc2, 0].pack('C*') + frame, pcm: true)
+    expect(result).to include(pcm_decoded: true, pcm_encoding: :s16le, sample_rate: 8000)
+    expect(result[:pcm].bytesize).to eq(320)
+    expect(result[:frames]).to eq([frame])
+  end
+
+  it 'splits firmware Codec2 frames without mistaking compressed bytes for PCM' do
+    result = decode(9, 'c0dec200 0011223344556677 8899aabbccddeeff')
+    expect(result).to include(format: :codec2, mode: 0, bitrate: 3200, samples_per_frame: 160, pcm_decoded: false)
+    expect(result[:frames].map { |frame| frame.unpack1('H*') }).to eq(%w[0011223344556677 8899aabbccddeeff])
+    expect(decode(9, 'c0dec20011')[:status]).to eq(:malformed)
+    expect(decode(9, 'c0dec2ff')[:status]).to eq(:unsupported)
+  end
+
+  it 'decodes ota-common upstream header and start-info test vectors' do
+    expect(decode(79, '0307d204c8000004')).to include(format: :ota_common, type: :block, session: 7, index: 1234, offset: 200, total: 1024)
+    result = decode(79, '0107000000000000 0004320050c30000c0004000')
+    expect(result[:start]).to eq(block_size: 1024, block_count: 50, payload_length: 50_000, manifest_length: 192, signature_length: 64)
+    expect(result[:signature_verified]).to be false
+  end
+
+  it 'decodes published signed temperature and acceleration examples' do
+    expect(decode(:CAYENNE_APP, '0167ffd7')[:records].first[:value]).to eq(-4.1)
+    expect(decode(77, '067104d2fb2e0000')[:records].first[:value]).to eq(x: 1.234, y: -1.234, z: 0.0)
+  end
+
+  it 'decodes every original Cayenne scalar type and signed GPS coordinates' do
+    vectors = { 0 => ['01', 1], 1 => ['00', 0], 2 => ['ff9c', -1], 3 => ['007b', 1.23],
+                101 => ['ffff', 65_535], 102 => ['01', 1], 104 => ['64', 50], 115 => ['279d', 1014.1] }
+    vectors.each do |type, (value, expected)|
+      expect(decode(77, format('01%<type>02x%<value>s', type: type, value: value))[:records].first[:value]).to eq(expected)
+    end
+    gps = decode(77, '0188 000001 ffffff 000064')[:records].first[:value]
+    expect(gps).to eq(latitude: 0.0001, longitude: -0.0001, altitude: 1.0)
+    expect(decode(77, '0186 0064 ff9c 0000')[:records].first[:value]).to eq(x: 1, y: -1, z: 0)
+  end
+
+  it 'never skips unknown LPP fields or loses malformed wire bytes' do
+    result = decode(77, '0167006402feabcd')
+    expect(result).to include(status: :unsupported, undecoded_offset: 4)
+    expect(result[:records].size).to eq(1)
+    expect(result[:remainder].unpack1('H*')).to eq('02feabcd')
+    %w[01 0167 016700].each do |hex|
+      expect(decode(77, hex)).to include(status: :malformed, raw: [hex].pack('H*'))
+    end
+    expect(decode(77, '')).to include(status: :decoded, records: [])
+  end
+
+  it 'checks IP lengths and keeps options and fragments uninterpreted' do
+    result = decode(33, '46000018106f2001800600000a0000010a00000201010000')
+    expect(result).to include(header_length: 24, fragment_offset: 8, flags: 1, body: ''.b)
+    expect(result[:options].unpack1('H*')).to eq('01010000')
+    expect(result[:header_checksum_valid]).to be false
+    %w[45000014106f0000800600000a0000010a00000200 44000014106f0000800600000a0000010a000002].each do |hex|
+      expect(decode(33, hex)[:status]).to eq(:malformed)
+    end
+    expect(decode(33, '')[:status]).to eq(:malformed)
+    expect(decode(33, 'f0')[:status]).to eq(:unsupported)
+    expect(decode(33, '60')[:status]).to eq(:malformed)
+  end
+
+  it 'validates all firmware Codec2 mode frame boundaries' do
+    [8, 6, 8, 7, 7, 6, 4, 4, 4].each_with_index do |width, mode|
+      result = decode(9, format('c0dec2%02x', mode) + ('00' * width))
+      expect(result).to include(status: :decoded, bytes_per_frame: width)
+      expect(result[:frames].length).to eq(1)
+    end
+    %w[00 c0dec2 00000000].each { |hex| expect(decode(9, hex)[:status]).to eq(:malformed) }
+  end
+
+  it 'decodes OTA load prefixes and controls while bounding fragments' do
+    result = decode(79, '0901000000000000 0400000001000000 aabb')
+    expect(result[:load]).to eq(total_length: 4, offset: 1, chunk: [0xaa, 0xbb].pack('C*'))
+    [5, 6, 7, 8, 10].each do |type|
+      expect(decode(79, format('%02x01ffff00000000', type))[:status]).to eq(:decoded)
+    end
+    expect(decode(79, '0401000000000000')[:status]).to eq(:decoded) # Single-leaf empty proof.
+    expect(decode(79, '0201ffff00000400aabb')[:body].unpack1('H*')).to eq('aabb')
+    %w[00 0101000000000000 0301000001000100ff 09010000000000000100000001000000ff].each do |hex|
+      expect(decode(79, hex)[:status]).to eq(:malformed)
+    end
+    expect(decode(79, '0b01000000000000')[:status]).to eq(:unsupported)
+    expect(decode(79, 'ff01000000000000')[:status]).to eq(:unsupported)
+    expect(decode(79, '00' * 234)[:status]).to eq(:malformed)
+  end
+
+  it 'decodes the source-defined ZPS position flag and BLE records only in the explicit profile' do
+    payload = [0x830000000001, 0xfffffffffffffffe, 0x3cffaabbccddeeff].pack('Q<*')
+    result = Meshtastic::PayloadFormats.decode(portnum: 68, payload: payload, zps_profile: :esp32_legacy)
+    expect(result[:position]).to eq(latitude_i: -1, longitude_i: -2, pdop: 3)
+    expect(result[:records].first).to include(kind: :ble, address: 'aa:bb:cc:dd:ee:ff', rssi: -60)
+    result = Meshtastic::PayloadFormats.decode(portnum: 68, payload: 'a', zps_profile: :esp32_legacy)
+    expect(result[:status]).to eq(:malformed)
+  end
+
+  it 'preserves unknown ports and rejects non-byte inputs' do
+    expect(decode(256, 'deadbeef')).to include(format: :opaque, status: :unsupported, raw: ['deadbeef'].pack('H*'))
+    expect { Meshtastic::PayloadFormats.decode(portnum: 77, payload: nil) }.to raise_error(ArgumentError)
+  end
+
+  it 'documents its public integration options at runtime' do
+    expect { Meshtastic::PayloadFormats.help }.to output(/portnum:.*\n.*payload:.*\n.*pcm:.*\n.*zps_profile:/).to_stdout
+    expect(Meshtastic::PayloadFormats.authors).not_to be_empty
+  end
+
+  it 'decodes the published myDevices two-temperature wire example' do
+    result = decode(77, '03 67 01 10 05 67 00 FF')
+    expect(result[:format]).to eq(:cayenne_lpp)
+    expect(result[:records].map { |r| r.values_at(:channel, :value) }).to eq([[3, 27.2], [5, 25.5]])
+  end
+end

data/spec/lib/meshtastic/reticulum_spec.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+
+RSpec.describe 'Meshtastic::Reticulum' do
+  let(:fixtures) { JSON.parse(File.read(File.expand_path('../../support/reticulum_fixtures.json', __dir__))) }
+  let(:chunks) { fixtures.fetch('chunks_hex').map { |hex| [hex].pack('H*') } }
+
+  it 'loads the tunnel codec from the gem entrypoint' do
+    expect(Meshtastic.const_defined?(:Reticulum)).to be(true)
+  end
+
+  it 'packages the upstream JSON fixture even without a Git file listing' do
+    root = File.expand_path('../../..', __dir__)
+    context = Object.new
+    allow(context).to receive(:`).with('git ls-files -z').and_return('')
+    path = File.join(root, 'meshtastic.gemspec')
+    specification = context.instance_eval(File.read(path), path)
+    expect(specification.files).to include('spec/support/reticulum_fixtures.json')
+  end
+
+  it 'recognizes upstream REQ control without feeding its bytes to an RNS decoder' do
+    require 'meshtastic/reticulum'
+    raw = [fixtures.fetch('request_hex')].pack('H*')
+    expect(Meshtastic::Reticulum.decode_packet(payload: raw)).to include(
+      format: :reticulum_request, message_index: 255, position: 2, index: 2, raw: raw, complete: false
+    )
+  end
+
+  it 'rejects malformed frames and bounds every wire input before copying' do
+    require 'meshtastic/reticulum'
+    [nil, 12, '', "\x01", "\x01\x00x", "\x01\xff", 'REQ', "REQ\x01", "REQ\x01\x00", "REQ\x01\x01x", "\x01\xff#{'x' * 201}"].each do |raw|
+      expect { Meshtastic::Reticulum.decode_packet(payload: raw) }.to raise_error(ArgumentError)
+    end
+  end
+
+  it 'retains an opaque complete single fragment and handles signed byte extremes' do
+    require 'meshtastic/reticulum'
+    raw = [fixtures.fetch('single_hex')].pack('H*')
+    expect(Meshtastic::Reticulum.decode_packet(payload: raw)).to include(complete: true, count: 1, message_index: 0, raw: raw)
+    expect(Meshtastic::Reticulum.decode_packet(payload: "\xff\x80x".b)).to include(position: -128, count: 128)
+    expect(Meshtastic::Reticulum.decode_packet(payload: "\x00\x7fx".b)).to include(position: 127, count: nil)
+  end
+
+  it 'reassembles a complete explicitly grouped upstream message final-first without inner decoding' do
+    require 'meshtastic/reticulum'
+    result = Meshtastic::Reticulum.decode_chunks(chunks: chunks.reverse)
+    expect(result).to include(format: :reticulum_packet, complete: true, message_index: 255,
+                              count: 3, body: [fixtures.fetch('payload_hex')].pack('H*'), raw_chunks: chunks)
+    expect(result[:fragments].map { |frame| frame[:position] }).to eq([1, 2, -3])
+  end
+
+  it 'rejects incomplete, duplicate, conflicting, mixed-index and control-containing groups' do
+    require 'meshtastic/reticulum'
+    cases = [nil, [], chunks * 43, chunks.first(2), [chunks.last], chunks + [chunks.first],
+             [chunks.first, "\xff\x01different".b, chunks.last],
+             [chunks.first, "\xff\xfex".b, chunks.last],
+             [chunks.first, "\x00\x02x".b, chunks.last],
+             [chunks.first, "\xff\x04x".b, chunks.last],
+             ["REQ\xff\x02".b]]
+    cases.each do |group|
+      expect { Meshtastic::Reticulum.decode_chunks(chunks: group) }.to raise_error(ArgumentError)
+    end
+  end
+
+  it 'bounds aggregate output and rejects invalid caller limits' do
+    require 'meshtastic/reticulum'
+    [0, -1, 565, '564', 1.5].each do |limit|
+      expect { Meshtastic::Reticulum.decode_chunks(chunks: chunks, max_bytes: limit) }.to raise_error(ArgumentError)
+    end
+    expect { Meshtastic::Reticulum.decode_chunks(chunks: chunks, max_bytes: 563) }.to raise_error(ArgumentError, /limit/)
+    big = ["\x01\x01#{'x' * 200}", "\x01\x02#{'x' * 200}", "\x01\xfd#{'x' * 165}"]
+    expect { Meshtastic::Reticulum.decode_chunks(chunks: big) }.to raise_error(ArgumentError, /limit/)
+  end
+
+  it 'exposes usable runtime help and attribution' do
+    require 'meshtastic/reticulum'
+    expect { Meshtastic::Reticulum.help }.to output(/decode_packet.*payload:.*decode_chunks.*chunks:.*max_bytes:.*authors/m).to_stdout
+    expect(Meshtastic::Reticulum.authors).to include('landandair')
+  end
+
+  it 'decodes the two byte unsigned/signed upstream header and retains original bytes' do
+    require 'meshtastic/reticulum'
+    result = Meshtastic::Reticulum.decode_packet(payload: chunks.last)
+    expect(result).to include(format: :reticulum_fragment, message_index: 255, position: -3,
+                              index: 3, count: 3, final: true, complete: false,
+                              raw: chunks.last, body: chunks.last.byteslice(2..))
+    expect(result[:raw].encoding).to eq(Encoding::BINARY)
+  end
+end