meshtastic 0.0.187 → 0.0.188

data/spec/lib/meshtastic/admin_spec.rb

@@ -86,6 +86,21 @@ describe Meshtastic::Admin do
     expect(published.length).to eq(1)
   end
 
+  it 'passes named MQTT AEAD selection through the Admin boundary without promoting broker claims' do
+    client = MQTTClient.new(client_id: 'aabbccdd')
+    published = []
+    client.define_singleton_method(:publish) { |_topic, bytes| published << Meshtastic::ServiceEnvelope.decode(bytes) }
+    result = described_class.request(transport_obj: client, to: '!aabbccee', get_owner_request: true, wait: false,
+                                     channel_id: 'Admin', psks: { Admin: { psk: 'AQ==', use_aead: true } })
+    expect(result).not_to have_key(:delivery)
+    envelope = published.fetch(0)
+    expect(envelope.channel_id).to eq('Admin')
+    decoded = Meshtastic::MeshInterface.new.decrypt_packet(message: envelope.packet.to_h, channel: envelope.channel_id,
+                                                           psks: { Admin: { psk: 'AQ==', use_aead: true } })
+    expect(Meshtastic::AdminMessage.decode(decoded[:decoded][:payload]).get_owner_request).to be(true)
+    expect(decoded[:security_provenance][:verification]).not_to eq(:verified)
+  end
+
   it 'sends a reboot AdminMessage on ADMIN_APP' do
     serial_obj = fake_serial_obj
     described_class.reboot(transport_obj: serial_obj, seconds: 7)
@@ -165,6 +180,65 @@ module AdminSynchronousSpecHelpers
   end
 end
 
+describe Meshtastic::Admin, 'delivery provenance' do
+  include AdminSynchronousSpecHelpers
+
+  it 'keeps standalone or broker-origin response claims untrusted even with caller-supplied provenance' do
+    packet = Meshtastic::MeshPacket.new(from: 42, ack_proof_status: :ACK_PROOF_VALID, xeddsa_signed: true,
+                                        decoded: Meshtastic::Data.new(portnum: :ADMIN_APP, request_id: 9,
+                                                                      payload: Meshtastic::AdminMessage.new(get_owner_response: Meshtastic::User.new).to_proto))
+    result = described_class.response(packet: Meshtastic::FromRadio.new(packet: packet), from: 42, request_id: 9,
+                                      security_provenance: { source: :radio, verification: :device_reported })
+    expect(result[:delivery]).to eq(:readback)
+    expect(result[:security_provenance]).to include(source: :unknown, verification: :untrusted,
+                                                    reported: { ack_proof_status: :ACK_PROOF_VALID, xeddsa_signed: true })
+  end
+
+  it 'requires actual request ID and target rather than a local or unrelated valid proof' do
+    ignored = []
+    handle = responding_serial do |connection, packet|
+      [[packet.to, packet.id + 1], [connection[:my_node_num], packet.id], [123, packet.id]].each do |from, request_id|
+        incoming = Meshtastic::FromRadio.new(packet: Meshtastic::MeshPacket.new(from: from, ack_proof_status: :ACK_PROOF_VALID,
+                                                                                decoded: Meshtastic::Data.new(portnum: :ROUTING_APP, request_id: request_id)))
+        ignored << incoming
+        connection[:from_radio_queue] << incoming
+      end
+      connection[:from_radio_queue] << Meshtastic::FromRadio.new(packet: Meshtastic::MeshPacket.new(from: packet.to,
+                                                                                                    decoded: Meshtastic::Data.new(portnum: :ROUTING_APP, request_id: packet.id)))
+    end
+    result = described_class.request(transport_obj: handle, to: '!aabbccdd', auto_session: false, reboot_seconds: 5)
+    expect(result[:delivery]).to eq(:acknowledged)
+    expect(ignored.map { handle[:from_radio_queue].pop(true) }).to eq(ignored)
+  end
+
+  it 'identifies readback from the connected radio without treating a signature as delivery proof' do
+    handle = responding_serial do |connection, packet|
+      reply = admin_reply(packet)
+      reply.packet.xeddsa_signed = true
+      reply.packet.ack_proof_status = :ACK_PROOF_VALID
+      connection[:from_radio_queue] << reply
+    end
+    result = described_class.request(transport_obj: handle, get_device_metadata_request: true)
+    expect(result[:delivery]).to eq(:readback)
+    expect(result[:security_provenance]).to include(source: :radio, verification: :device_reported)
+  end
+
+  it 'distinguishes device-reported valid proof from signed or ordinary target ACKs' do
+    (%i[ACK_PROOF_VALID ACK_PROOF_ABSENT ACK_PROOF_INVALID ACK_PROOF_NO_KEY] + [99]).each do |proof|
+      handle = responding_serial do |connection, packet|
+        connection[:from_radio_queue] << Meshtastic::FromRadio.new(packet: Meshtastic::MeshPacket.new(
+          from: packet.to, ack_proof_status: proof, xeddsa_signed: true,
+          decoded: Meshtastic::Data.new(portnum: :ROUTING_APP, request_id: packet.id, payload: Meshtastic::Routing.new.to_proto)
+        ))
+      end
+      result = described_class.request(transport_obj: handle, to: '!aabbccdd', auto_session: false, reboot_seconds: 5)
+      expect(result[:delivery]).to eq(proof == :ACK_PROOF_VALID ? :device_verified : :acknowledged)
+      expect(result[:security_provenance]).to include(source: :radio, verification: :device_reported,
+                                                      reported: { ack_proof_status: proof, xeddsa_signed: true })
+    end
+  end
+end
+
 describe Meshtastic::Admin, 'automatic sessions' do
   include AdminSynchronousSpecHelpers
 
@@ -398,6 +472,9 @@ describe Meshtastic::Admin, 'generated schema coverage' do
               when :enum then 0
               else 1
               end
+      value = Meshtastic::Config.new(device: {}) if %w[set_config get_config_response].include?(field.name)
+      value = Meshtastic::ModuleConfig.new(mqtt: {}) if %w[set_module_config get_module_config_response].include?(field.name)
+      value = Meshtastic::HamParameters.new(call_sign: 'N0CALL') if field.name == 'set_ham_mode'
       message = described_class.encode(field.name.to_sym => value)
       decoded = described_class.decode(payload: message.to_proto)
       expect(decoded.payload_variant).to eq(field.name.to_sym)

data/spec/lib/meshtastic/bluetooth_spec.rb

@@ -3,7 +3,7 @@
 require 'spec_helper'
 require_relative '../../support/payload_fixtures'
 
-describe Meshtastic::Bluetooth do
+describe Meshtastic::Bluetooth do # rubocop:disable Metrics/BlockLength
   include PayloadFixtures
 
   it 'decodes every application fixture received from GATT including malformed and default messages' do
@@ -17,6 +17,31 @@ describe Meshtastic::Bluetooth do
     end
   end
 
+  it 'preserves device security provenance and decrypts AEAD through GATT' do
+    handle = connect
+    packet = Meshtastic::MeshPacket.new(from: 123, to: 0xffffffff, id: 42,
+                                        channel: 'Custom'.bytes.reduce(0, :^) ^ 0xae,
+                                        encrypted: ['f0285b86af98b3f88815b9938ecf0ddf1693c987'].pack('H*'),
+                                        xeddsa_signed: true, ack_proof_status: :ACK_PROOF_VALID)
+    connection.incoming << Meshtastic::FromRadio.new(packet: packet).to_proto
+    received = Timeout.timeout(2) do
+      described_class.subscribe(bluetooth_obj: handle, psks: { Custom: { psk: Base64.strict_encode64('k' * 16), use_aead: true } }) { |message| break message }
+    end
+    expect(received.dig(:packet, :decoded, :payload)).to eq('test')
+    expect(received.dig(:packet, :security_provenance)).to include(source: :radio, verification: :device_reported,
+                                                                   reported: { xeddsa_signed: true, ack_proof_status: :ACK_PROOF_VALID }, channel_authentication: :aead)
+  end
+
+  it 'forwards PKI text through the real GATT ToRadio codec' do
+    handle = connect
+    described_class.send_text(bluetooth_obj: handle, text: 'private', to: '!00000002', pki_encrypted: true, public_key: 'k' * 32)
+    packet = Meshtastic::ToRadio.decode(connection.writes.last).packet
+    expect(packet.pki_encrypted).to be true
+    expect(packet.public_key).to eq('k' * 32)
+    expect(packet.decoded.payload).to eq('private')
+    expect(packet.encrypted).to be_empty
+  end
+
   let(:connection) do
     Class.new do
       attr_reader :writes, :incoming

data/spec/lib/meshtastic/mesh_interface_spec.rb

@@ -2,6 +2,38 @@
 
 require 'spec_helper'
 require_relative '../../support/payload_fixtures'
+require_relative '../../support/channel_crypto_reference'
+
+describe Meshtastic::MeshInterface, 'pinned firmware CCM interoperability' do
+  it 'validates the independent reference against firmware RFC3610 vector 1' do
+    hex = ->(value) { [value].pack('H*') }
+    bytes = ChannelCryptoReference.encrypt(
+      key: hex.call('C0C1C2C3C4C5C6C7C8C9CACBCCCDCECF'), nonce: hex.call('00000003020100A0A1A2A3A4A5'),
+      aad: hex.call('0001020304050607'), plain: hex.call('08090A0B0C0D0E0F101112131415161718191A1B1C1D1E'), tag_len: 8
+    )
+    expect(bytes.unpack1('H*')).to eq('588c979a61c663d2f066d0c2c0f989806d5f6b61dac38417e8d12cfdf926e0')
+  end
+
+  it 'matches the firmware smoke inputs using an independent reference and decodes the fixed result' do
+    plain = ['08011204746573744800'].pack('H*')
+    key = Base64.strict_decode64('1PG7OiApB1nwvP+rz05pAQ==')
+    encrypted = ChannelCryptoReference.encrypt(key: key, nonce: [0xaabbccdd, 0, 0x12345678, 0].pack('V4')[0, 13],
+                                               aad: [0x12345678, 0xaaaa].pack('V2'), plain: plain)
+    expect(encrypted.unpack1('H*')).to eq('62bb832909c076bb019632d85aac0b9db32ae40cbe95')
+    packet = { id: 0xaabbccdd, from: 0x12345678, to: 0xaaaa, encrypted: encrypted }
+    result = described_class.new.decrypt_packet(message: packet, channel: 'LongFast',
+                                                psks: { LongFast: { psk: 'AQ==', use_aead: true } })
+    expect(result[:decoded]).to eq(Meshtastic::Data.decode(plain).to_h)
+  end
+
+  it 'independently reproduces both broker broadcast golden vectors' do
+    { 16 => 'f0285b86af98b3f88815b9938ecf0ddf1693c987', 32 => '8640f69cc0583046e446be6d72147811991099bb' }.each do |size, expected|
+      bytes = ChannelCryptoReference.encrypt(key: 'k' * size, nonce: [42, 0, 123, 0].pack('V4')[0, 13],
+                                             aad: [123, 0xffffffff].pack('V2'), plain: ['0801120474657374'].pack('H*'))
+      expect(bytes.unpack1('H*')).to eq(expected)
+    end
+  end
+end
 
 describe Meshtastic::MeshInterface do
   include PayloadFixtures
@@ -150,6 +182,15 @@ describe Meshtastic::MeshInterface do
     expect(result[:encrypted]).to eq(encrypted)
   end
 
+  it 'rejects duplicate named PSKs rather than silently choosing a string or symbol entry' do
+    packet = { from: 123, to: 0xffffffff, id: 42, channel: 'Custom'.bytes.reduce(0, :^) ^ 0xae,
+               encrypted: ['f0285b86af98b3f88815b9938ecf0ddf1693c987'].pack('H*') }
+    keys = { 'Custom' => { psk: Base64.strict_encode64('k' * 16), use_aead: true }, Custom: 'AQ==' }
+    result = described_class.new.decrypt_packet(message: packet, psks: keys, channel: 'Custom', source: :mqtt)
+    expect(result[:decoded]).to be_nil
+    expect(result[:decryption_error]).not_to be_nil
+  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)
@@ -182,6 +223,19 @@ describe Meshtastic::MeshInterface do
     end.to raise_error(ArgumentError, /PKI.*radio/)
   end
 
+  it 'documents explicit PKI and per-channel crypto options in instance help' do
+    expect { described_class.new.help }.to output(/pki_encrypted:.*public_key:.*channel_id:.*use_aead/m).to_stdout
+  end
+
+  it 'forwards explicit PKI text options to the device without encrypting on the host' do
+    wire = described_class.new.send_text(from: 1, to: 2, text: 'private', psks: nil,
+                                         pki_encrypted: true, public_key: 'k' * 32)
+    packet = Meshtastic::ToRadio.decode(wire).packet
+    expect(packet.pki_encrypted).to be true
+    expect(packet.public_key).to eq('k' * 32)
+    expect(packet.decoded.payload).to eq('private')
+  end
+
   it 'rejects malformed recipient public keys' do
     expect do
       described_class.new.send_data(

data/spec/lib/meshtastic/module_config_spec.rb

@@ -39,7 +39,7 @@ describe Meshtastic::ModuleConfig do
     %i[get set].each do |operation|
       it "encodes a real Admin packet for #{operation} with #{key}" do
         connection = fake_serial_obj
-        options = { key => connection, module_config: Meshtastic::ModuleConfig.new }
+        options = { key => connection, module_config: Meshtastic::ModuleConfig.new(mqtt: {}) }
         options[:bluetooth_obj] = nil
         described_class.public_send(operation, options.freeze)
         frame = connection[:written]

data/spec/lib/meshtastic/mqtt_spec.rb

@@ -12,6 +12,7 @@ describe Meshtastic::MQTT do # rubocop:disable Metrics/BlockLength
       payload_cases.each do |port, bytes, _expected|
         packet = payload_radio(port, bytes).packet
         if encrypted
+          packet.channel = ('LongFast'.bytes + Base64.strict_decode64('1PG7OiApB1nwvP+rz05pAQ==').bytes).reduce(0, :^)
           cipher = OpenSSL::Cipher.new('AES-128-CTR')
           cipher.encrypt
           cipher.key = Base64.strict_decode64('1PG7OiApB1nwvP+rz05pAQ==')
@@ -96,6 +97,103 @@ describe Meshtastic::MQTT do # rubocop:disable Metrics/BlockLength
   end
 
   describe '.send_text' do
+    it 'fails closed on direct text and explicit PKI without publishing' do
+      client = fake_mqtt_obj
+      [{ to: '!00000002' }, { pki_encrypted: true, public_key: 'k' * 32 }].each do |options|
+        expect { described_class.send_text({ mqtt_obj: client, text: 'private' }.merge(options)) }.to raise_error(ArgumentError, /PKI|direct/i)
+      end
+      expect(client.published).to be_empty
+    end
+
+    it 'selects the explicit channel key and firmware hash, never the first key' do
+      client = fake_mqtt_obj
+      keys = { Wrong: Base64.strict_encode64('w' * 16), Custom: Base64.strict_encode64('k' * 32) }
+      described_class.send_text(mqtt_obj: client, channel_id: 'Custom', psks: keys, text: 'selected')
+      item = client.published.last
+      envelope = Meshtastic::ServiceEnvelope.decode(item[:payload])
+      expect(envelope.channel_id).to eq('Custom')
+      expect(envelope.packet.channel).to eq(('Custom'.bytes + ('k' * 32).bytes).reduce(0, :^))
+      expect(item[:topic]).to include('/Custom/')
+      client.incoming << mqtt_packet(topic: item[:topic], payload: item[:payload])
+      client.incoming << nil
+      described_class.subscribe(mqtt_obj: client, psks: keys) do |message|
+        expect(message.dig(:packet, :decoded, :payload)).to eq('selected')
+      end
+      expect { described_class.send_text(mqtt_obj: client, psks: keys) }.to raise_error(ArgumentError, /channel_id|ambiguous/)
+    end
+
+    it 'encrypts and decrypts firmware CCM vectors for both AES key sizes over the broker codec' do
+      # Firmware 8e6a88d CryptoEngine: L=2, M=12, nonce=id64le/from32le/00, AAD=from32le/to32le.
+      # Independently generated using CBC-MAC/CTR, checked against upstream RFC3610 vector 1.
+      { 16 => 'f0285b86af98b3f88815b9938ecf0ddf1693c987', 32 => '8640f69cc0583046e446be6d72147811991099bb' }.each do |size, vector|
+        client = fake_mqtt_obj
+        keys = { Custom: { psk: Base64.strict_encode64('k' * size), use_aead: true } }
+        described_class.send_text(mqtt_obj: client, from: 123, last_packet_id: 41, channel_id: 'Custom', psks: keys, text: 'test')
+        item = client.published.last
+        packet = Meshtastic::ServiceEnvelope.decode(item[:payload]).packet
+        expect(packet.encrypted.unpack1('H*')).to eq(vector)
+        expect(packet.channel).to eq(('Custom'.bytes + ('k' * size).bytes).reduce(0, :^) ^ 0xae)
+        client.incoming << mqtt_packet(topic: item[:topic], payload: item[:payload])
+        client.incoming << nil
+        described_class.subscribe(mqtt_obj: client, psks: keys) do |message|
+          expect(message.dig(:packet, :decoded, :payload)).to eq('test')
+          expect(message.dig(:packet, :security_provenance, :channel_authentication)).to eq(:aead)
+          expect(message.dig(:packet, :security_provenance, :verification)).to eq(:untrusted)
+        end
+      end
+    end
+
+    it 'rejects conflicting channel selections and unsupported crypto requests before publishing' do
+      client = fake_mqtt_obj
+      cases = [
+        { psks: { Custom: 'AQ==', 'Custom' => 'Ag==' }, channel_id: 'Custom' },
+        { psks: { Custom: 'AQ==' }, channel_id: 'Unknown' },
+        { psks: { Custom: 'AQ==' }, channel_id: 'Custom', topic: '2/e/Other/#' },
+        { psks: nil }, { psks: {} }, { public_key: 'k' * 32 }
+      ]
+      cases.each do |options|
+        expect { described_class.send_text({ mqtt_obj: client }.merge(options)) }.to raise_error(ArgumentError)
+      end
+      expect(client.published).to be_empty
+    end
+
+    it 'rejects misplaced mode options instead of silently publishing legacy CTR' do
+      client = fake_mqtt_obj
+      expect { described_class.send_text(mqtt_obj: client, use_aead: true, text: 'private') }.to raise_error(ArgumentError, /use_aead.*psks/)
+      expect { described_class.send_data(mqtt_obj: client, use_aead: true, data: Meshtastic::Data.new(portnum: :TEXT_MESSAGE_APP)) }.to raise_error(ArgumentError, /use_aead.*psks/)
+      expect(client.published).to be_empty
+      client.incoming << nil
+      expect { described_class.subscribe(mqtt_obj: client, use_aead: true) }.to raise_error(ArgumentError, /use_aead.*psks/)
+    end
+
+    it 'requires an explicit boolean mode in structured key records' do
+      client = fake_mqtt_obj
+      [{ psk: 'AQ==' }, { psk: 'AQ==', use_aed: true }, { psk: 'AQ==', use_aead: 'true' }].each do |record|
+        expect { described_class.send_text(mqtt_obj: client, psks: { Private: record }) }.to raise_error(ArgumentError)
+      end
+      expect(client.published).to be_empty
+    end
+
+    it 'accepts frozen key configuration without modifying caller options' do
+      keys = { LongFast: 'AQ==' }.freeze
+      client = fake_mqtt_obj
+      options = { mqtt_obj: client, psks: keys, text: 'immutable' }.freeze
+      described_class.send_text(options)
+      client.incoming << nil
+      described_class.subscribe(mqtt_obj: client, psks: keys)
+      expect(keys).to eq(LongFast: 'AQ==')
+      expect(options.keys).to eq(%i[mqtt_obj psks text])
+    end
+
+    it 'expands firmware short PSK aliases on any named channel' do
+      client = fake_mqtt_obj
+      described_class.send_text(mqtt_obj: client, channel_id: 'Custom', psks: { Custom: { psk: 'Ag==', use_aead: true } }, text: 'alias')
+      packet = Meshtastic::ServiceEnvelope.decode(client.published.last[:payload]).packet
+      key = Base64.strict_decode64('1PG7OiApB1nwvP+rz05pAQ==')
+      key.setbyte(15, 2)
+      expect(packet.channel).to eq(('Custom'.bytes + key.bytes).reduce(0, :^) ^ 0xae)
+    end
+
     it 'publishes an encrypted ServiceEnvelope without UART framing' do
       mqtt_obj = fake_mqtt_obj
       described_class.send_text(
@@ -130,6 +228,69 @@ describe Meshtastic::MQTT do # rubocop:disable Metrics/BlockLength
   end
 
   describe 'mqtt reception' do
+    it 'rejects authenticated packet tampering, truncated tags and mode downgrades without plaintext' do
+      vector = ['f0285b86af98b3f88815b9938ecf0ddf1693c987'].pack('H*')
+      base = { from: 123, to: 0xffffffff, id: 42, channel: 'Custom'.bytes.reduce(0, :^) ^ 0xae, encrypted: vector }
+      variants = vector.bytes.each_index.map do |index|
+        altered = vector.dup
+        altered.setbyte(index, altered.getbyte(index) ^ 1)
+        base.merge(encrypted: altered)
+      end
+      variants += %i[from to id channel].map { |field| base.merge(field => base[field] ^ 1) }
+      variants += [base.merge(encrypted: vector[0, 12])]
+      [true, false].each do |aead|
+        client = fake_mqtt_obj
+        packets = aead ? variants : [base]
+        packets.each do |fields|
+          envelope = Meshtastic::ServiceEnvelope.new(packet: Meshtastic::MeshPacket.new(fields), channel_id: 'Custom')
+          client.incoming << mqtt_packet(topic: 'msh/US/2/e/Custom/!0000007b', payload: envelope.to_proto)
+        end
+        client.incoming << nil
+        received = []
+        described_class.subscribe(mqtt_obj: client, psks: { Custom: { psk: Base64.strict_encode64('k' * 16), use_aead: aead } }) do |message|
+          received << message[:packet]
+        end
+        expect(received.size).to eq(packets.size)
+        received.each do |packet|
+          expect(packet[:decoded]).to be_nil
+          expect(packet[:encrypted]).to be_a(String)
+          expect(packet[:decryption_error]).not_to be_nil
+        end
+      end
+    end
+
+    it 'does not expose broker security claims even when later enrichment fails' do
+      client = fake_mqtt_obj
+      forged = { channel_id: 'LongFast', packet: { xeddsa_signed: true, ack_proof_status: 'ACK_PROOF_VALID',
+                                                   public_key: 5, decoded: { portnum: 1, payload: 'hello' },
+                                                   security_provenance: { source: 'radio', verification: 'verified' } } }
+      client.incoming << mqtt_packet(topic: 'msh/US/2/e/LongFast/!00000001', payload: JSON.generate(forged))
+      client.incoming << nil
+      received = []
+      begin
+        described_class.subscribe(mqtt_obj: client, json: true) { |message| received << message[:packet] }
+      rescue TypeError
+        # The enrichment failure must not yield a broker claim as a radio result.
+      end
+      expect(received.size).to eq(1)
+      expect(received.first[:xeddsa_signed]).to be_nil
+      expect(received.first[:ack_proof_status]).to be_nil
+      expect(received.first[:security_provenance]).to include(source: :mqtt, verification: :untrusted)
+    end
+
+    it 'labels broker verification claims as untrusted and preserves their reported values' do
+      client = fake_mqtt_obj
+      packet = Meshtastic::MeshPacket.new(decoded: Meshtastic::Data.new(portnum: :TEXT_MESSAGE_APP, payload: 'hello'), xeddsa_signed: true)
+      envelope = Meshtastic::ServiceEnvelope.new(packet: packet, channel_id: 'LongFast')
+      client.incoming << mqtt_packet(topic: 'msh/US/2/e/LongFast/!00000001', payload: envelope.to_proto)
+      client.incoming << nil
+      described_class.subscribe(mqtt_obj: client) do |message|
+        expect(message[:packet][:xeddsa_signed]).to be_nil
+        expect(message[:packet][:security_provenance]).to include(source: :mqtt, verification: :untrusted,
+                                                                  reported: include(xeddsa_signed: true))
+      end
+    end
+
     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
@@ -214,6 +375,10 @@ describe Meshtastic::MQTT do # rubocop:disable Metrics/BlockLength
   end
 
   describe '.help' do
+    it 'documents channel selection and explicit per-key mode in runtime help' do
+      expect { described_class.help }.to output(/channel_id:.*use_aead/m).to_stdout
+    end
+
     it 'prints usage without raising' do
       expect { described_class.help }.to output(/USAGE/).to_stdout
     end

data/spec/lib/meshtastic/serial_spec.rb

@@ -25,6 +25,22 @@ describe Meshtastic::Serial do # rubocop:disable Metrics/BlockLength
     end
   end
 
+  it 'preserves device security provenance and decrypts AEAD through UART framing' do
+    with_serial_link do |handle, device|
+      packet = Meshtastic::MeshPacket.new(from: 123, to: 0xffffffff, id: 42,
+                                          channel: 'Custom'.bytes.reduce(0, :^) ^ 0xae,
+                                          encrypted: ['f0285b86af98b3f88815b9938ecf0ddf1693c987'].pack('H*'),
+                                          xeddsa_signed: true, ack_proof_status: :ACK_PROOF_VALID)
+      device.write(radio_frame(Meshtastic::FromRadio.new(packet: packet)))
+      received = Timeout.timeout(2) do
+        described_class.subscribe(serial_obj: handle, psks: { Custom: { psk: Base64.strict_encode64('k' * 16), use_aead: true } }) { |message| break message }
+      end
+      expect(received.dig(:packet, :decoded, :payload)).to eq('test')
+      expect(received.dig(:packet, :security_provenance)).to include(source: :radio, verification: :device_reported,
+                                                                     reported: { xeddsa_signed: true, ack_proof_status: :ACK_PROOF_VALID }, channel_authentication: :aead)
+    end
+  end
+
   def with_serial_link(opts = {})
     PTY.open do |device, host|
       serial_obj = described_class.connect({ block_dev: host.path, want_config: false }.merge(opts))
@@ -257,6 +273,16 @@ describe Meshtastic::Serial do # rubocop:disable Metrics/BlockLength
   end
 
   describe '.send_text' do
+    it 'forwards PKI text requests through real ToRadio framing' do
+      serial_obj = fake_serial_obj
+      described_class.send_text(serial_obj: serial_obj, text: 'private', to: '!00000002', pki_encrypted: true, public_key: 'k' * 32)
+      packet = Meshtastic::ToRadio.decode(serial_obj[:written].byteslice(4..)).packet
+      expect(packet.pki_encrypted).to be true
+      expect(packet.public_key).to eq('k' * 32)
+      expect(packet.decoded.payload).to eq('private')
+      expect(packet.encrypted).to be_empty
+    end
+
     it 'rejects text exceeding the byte limit without closing the connection' do
       serial_obj = fake_serial_obj
       expect do

data/spec/lib/meshtastic/tcp_spec.rb

@@ -19,6 +19,22 @@ describe Meshtastic::TCP do
     end
   end
 
+  it 'preserves device security provenance and decrypts AEAD through TCP framing' do
+    with_tcp_link do |handle, remote|
+      packet = Meshtastic::MeshPacket.new(from: 123, to: 0xffffffff, id: 42,
+                                          channel: 'Custom'.bytes.reduce(0, :^) ^ 0xae,
+                                          encrypted: ['f0285b86af98b3f88815b9938ecf0ddf1693c987'].pack('H*'),
+                                          xeddsa_signed: true, ack_proof_status: :ACK_PROOF_VALID)
+      remote.write(radio_frame(Meshtastic::FromRadio.new(packet: packet)))
+      received = Timeout.timeout(2) do
+        described_class.subscribe(tcp_obj: handle, psks: { Custom: { psk: Base64.strict_encode64('k' * 16), use_aead: true } }) { |message| break message }
+      end
+      expect(received.dig(:packet, :decoded, :payload)).to eq('test')
+      expect(received.dig(:packet, :security_provenance)).to include(source: :radio, verification: :device_reported,
+                                                                     reported: { xeddsa_signed: true, ack_proof_status: :ACK_PROOF_VALID }, channel_authentication: :aead)
+    end
+  end
+
   def with_tcp_link(opts = {})
     local, remote = UNIXSocket.pair
     tcp_obj = described_class.connect({ socket: local, host: '127.0.0.1', port: 4403, want_config: false }.merge(opts))
@@ -46,6 +62,19 @@ describe Meshtastic::TCP do
     end
   end
 
+  it 'forwards PKI text through the real TCP ToRadio codec' do
+    with_tcp_link do |handle, remote|
+      described_class.send_text(tcp_obj: handle, text: 'private', to: '!00000002', pki_encrypted: true, public_key: 'k' * 32)
+      remote.read(32)
+      header = remote.read(4)
+      packet = Meshtastic::ToRadio.decode(remote.read(header.unpack('CCn').last)).packet
+      expect(packet.pki_encrypted).to be true
+      expect(packet.public_key).to eq('k' * 32)
+      expect(packet.decoded.payload).to eq('private')
+      expect(packet.encrypted).to be_empty
+    end
+  end
+
   it 'receives a framed FromRadio over TCP' do
     with_tcp_link do |tcp_obj, remote|
       remote.read(32)

data/spec/lib/meshtastic/waypoint_spec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Meshtastic::Waypoint do
+  it 'transmits a validated box using production radio framing and preserves security options' do
+    frames = []
+    conn = Object.new
+    conn.define_singleton_method(:write) do |bytes|
+      frames << bytes
+      bytes.bytesize
+    end
+    conn.define_singleton_method(:flush) { true }
+    handle = { serial_conn: conn, my_node_num: 42 }
+    waypoint = described_class.build(fields: { bounding_box: { longitude_west_i: -10, longitude_east_i: 10 }, notify_on_exit: true })
+    described_class.transmit(serial_obj: handle, waypoint: waypoint, to: '!aabbccdd', pki_encrypted: true, public_key: 'k' * 32, want_ack: true)
+    packet = Meshtastic::ToRadio.decode(frames.last.byteslice(4..)).packet
+    expect(packet.decoded.portnum).to eq(:WAYPOINT_APP)
+    expect(described_class.decode(packet.decoded.payload)).to eq(waypoint)
+    expect(packet).to have_attributes(pki_encrypted: true, public_key: 'k' * 32, want_ack: true)
+    expect { described_class.transmit(serial_obj: handle, waypoint: described_class.new(geofence_radius: 1)) }.to raise_error(ArgumentError)
+    expect(frames.length).to eq(1)
+    expect { described_class.help }.to output(/#{described_class}\.transmit/).to_stdout
+  end
+
+  it 'validates bounds, geometry, notification types and firmware UTF-8 byte capacity' do
+    invalid = [
+      { latitude_i: 900_000_001, longitude_i: 0 }, { latitude_i: 0, longitude_i: -1_800_000_001 },
+      { latitude_i: 0 }, { geofence_radius: 1 }, { geofence_radius: -1 }, { geofence_radius: 1.5 },
+      { notify_on_enter: 1 }, { notify_on_exit: 'true' }, { notify_favorites_only: nil },
+      { bounding_box: { longitude_west_i: 10, longitude_east_i: 9 } },
+      { bounding_box: { latitude_south_i: 1, latitude_north_i: 0 } },
+      { bounding_box: { latitude_north_i: 900_000_001 } }, { bounding_box: { latitude_north_i: nil } },
+      { name: "bad\0name" }, { name: "\xff".b },
+      { name: 'é' * 15 }, { description: 'x' * 100 }, { shape: :circle }
+    ]
+    invalid.each do |fields|
+      expect { described_class.build(fields: fields) }.to raise_error(ArgumentError), fields.inspect
+    end
+    fields = { latitude_i: 0, longitude_i: 0, geofence_radius: 10,
+               bounding_box: { longitude_west_i: -1_800_000_000, latitude_south_i: -900_000_000,
+                               longitude_east_i: 1_800_000_000, latitude_north_i: 900_000_000 },
+               name: 'x' * 29, description: 'x' * 99 }
+    expect(described_class.build(fields: fields).bounding_box.latitude_north_i).to eq(900_000_000)
+    expect(described_class.build(fields: { bounding_box: {} }).bounding_box).to eq(Meshtastic::BoundingBox.new)
+  end
+
+  it 'preserves the generated protobuf class and builds a circle with notification flags' do
+    waypoint = described_class.build(fields: { id: 7, latitude_i: 450_000_000, longitude_i: -730_000_000,
+                                               geofence_radius: 100, notify_on_enter: true, notify_on_exit: true, notify_favorites_only: true })
+    expect(waypoint).to be_a(described_class)
+    expect(described_class.decode(waypoint.to_proto).to_h).to include(geofence_radius: 100, notify_favorites_only: true)
+    expect(described_class.build.to_proto).to eq(''.b)
+  end
+end

data/spec/support/channel_crypto_reference.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+# Independent test-only CBC-MAC/CTR reference, not OpenSSL's CCM implementation.
+# Layout from firmware 8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c
+# src/mesh/aes-ccm.cpp (L=2). The specs validate this against its RFC3610 vector.
+module ChannelCryptoReference
+  def self.encrypt(key:, nonce:, aad:, plain:, tag_len: 12)
+    ecb = OpenSSL::Cipher.new("aes-#{key.bytesize * 8}-ecb")
+    ecb.encrypt
+    ecb.padding = 0
+    ecb.key = key
+    encrypt = ->(block) { ecb.update(block) }
+    xor = ->(left, right) { left.bytes.zip(right.bytes).map { |x, y| x ^ y }.pack('C*') }
+    b0 = [0x40 | (((tag_len - 2) / 2) << 3) | 1].pack('C') + nonce + [plain.bytesize].pack('n')
+    mac = encrypt.call(b0)
+    [[aad.bytesize].pack('n') + aad, plain].each do |bytes|
+      bytes = bytes.ljust((bytes.bytesize + 15) / 16 * 16, "\0")
+      bytes.bytes.each_slice(16) { |block| mac = encrypt.call(xor.call(mac, block.pack('C*'))) }
+    end
+    ctr = ->(index) { encrypt.call("\1#{nonce}#{[index].pack('n')}") }
+    tag = xor.call(mac, ctr.call(0))[0, tag_len]
+    crypt = plain.bytes.each_slice(16).with_index.map do |block, index|
+      xor.call(block.pack('C*'), ctr.call(index + 1)[0, block.size])
+    end.join
+    crypt + tag
+  end
+end

data/spec/support/firmware_release_artifact_audit.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'meshtastic'
+require 'digest'
+require 'json'
+
+# Opt-in, parser-only audit. No installer, device, subprocess or network calls.
+# Extract the named official release members into ARGV[0] before running.
+root = ARGV.fetch(0)
+firmware = Meshtastic::Admin::Firmware
+cases = [
+  ['firmware-heltec-ht62-esp32c3-sx1262-2.8.1.8e6a88d.bin', '4bae94b7f5132bff199a8890094a3642c6096bf366dcdf1eb4ba84cdb2b9e290', :bin, nil],
+  ['firmware-heltec-ht62-esp32c3-sx1262-2.8.1.8e6a88d.factory.bin', 'da6b9789f869b6b48da7a6532e4b769be4cbb6633a61a9c90eb1d92732784d3c', :bin, 'trailing data'],
+  ['firmware-rak4631-2.8.1.8e6a88d.uf2', 'ba35ee9247125dba2551261446b130d861dd00478caaf9ba6377aecbf0b2aa1e', :nrf_uf2, 'outside application flash'],
+  ['firmware-rak4631-2.8.1.8e6a88d.hex', '718482dc2a56d8f89b8cf416c775cbb78fb3eee694f6642ab8a6545ba2e8f07b', :hex, nil],
+  ['firmware-rak4631-2.8.1.8e6a88d-ota.zip', '2315a758cdfcd635fc5a11341619d67787fddbdf9f0e5778364950c36f4fdeaa', :zip, 'Only application-only legacy Adafruit DFU packages'],
+  ['firmware-rak11310-2.8.1.8e6a88d.uf2', '941cc6d0b44ac5498a44c708705a0209509de7183fdc8862fe19a223d9b3d066', :rp_uf2, nil]
+]
+results = cases.map do |name, digest, kind, expected_error|
+  bytes = File.binread(File.join(root, name))
+  raise "Release artifact hash mismatch: #{name}" unless Digest::SHA256.hexdigest(bytes) == digest
+
+  error = nil
+  begin
+    case kind
+    when :bin then firmware::SerialBootloader.send(:validate_image, bytes: bytes, chip_id: 5)
+    when :nrf_uf2 then firmware::UF2.send(:validate_image, bytes: bytes, family_id: 0xada52840)
+    when :rp_uf2 then firmware::UF2.send(:validate_image, bytes: bytes, family_id: 0xe48bff56, flash_size: 2_097_152)
+    when :hex then firmware::Hex.validate(bytes: bytes, expected_chip: :nrf52840)
+    when :zip then firmware::NordicDFU.send(:package, package_bytes: bytes)
+    end
+  rescue ArgumentError => e
+    error = e.message
+  end
+  raise "Unexpected parser result for #{name}: #{error || 'accepted'}" unless expected_error ? error&.include?(expected_error) : error.nil?
+
+  { artifact: name, bytes: bytes.bytesize, sha256: digest, parser: error ? :rejected : :accepted, reason: error, hardware: false }
+end
+puts JSON.pretty_generate(results)