meshtastic 0.0.187 → 0.0.188

data/spec/lib/meshtastic/admin/backup_spec.rb

@@ -18,7 +18,7 @@ class BackupRadioPeer
       device: Meshtastic::Config.new(device: { serial_enabled: false }),
       network: Meshtastic::Config.new(network: { wifi_enabled: true, wifi_psk: 'password' }),
       mqtt: Meshtastic::ModuleConfig.new(mqtt: { enabled: false, password: 'broker-secret' }),
-      channel: Meshtastic::Channel.new(index: 0, role: :PRIMARY, settings: { psk: "\x00\xff".b, name: 'Test' }),
+      channel: Meshtastic::Channel.new(index: 0, role: :PRIMARY, settings: { psk: "\x00\xff".b * 8, name: 'Test' }),
       ui: Meshtastic::DeviceUIConfig.new(calibration_data: "\x00\xff".b)
     }
     @handle = { serial_conn: self, my_node_num: 0xaabbccdd, from_radio_queue: Queue.new }
@@ -75,6 +75,150 @@ describe 'Meshtastic::Admin::Backup' do
   let(:peer) { BackupRadioPeer.new }
   let(:options) { { transport_obj: peer.handle, config_types: [:DEVICE_CONFIG], module_config_types: [:MQTT_CONFIG], channel_indexes: [0], include_ui: true, timeout: 0.3 } }
 
+  it 'rejects semantic errors in every backup format before any requests' do
+    invalid_messages = [Meshtastic::User.new(long_name: 'é' * 13),
+                        Meshtastic::Channel.new(index: 0, settings: { psk: 'bad' }),
+                        Meshtastic::Config.new(lora: { region: 999 })]
+    invalid_messages.zip([['owner', nil], ['channel', 0], %w[config LORA_CONFIG]]).each do |message, (section, slot)|
+      document = { 'format' => backup_api::FORMAT, 'version' => 1, 'warning' => '', 'records' => [
+        { 'section' => section, 'slot' => slot, 'value' => JSON.parse(message.class.encode_json(message, preserve_proto_fieldnames: true)) }
+      ] }
+      expect { backup_api.import(transport_obj: peer.handle, backup: document, dry_run: true) }.to raise_error(ArgumentError)
+    end
+    profile = Meshtastic::DeviceProfile.new(long_name: 'é' * 13)
+    expect { backup_api.import(transport_obj: peer.handle, backup: profile.to_proto) }.to raise_error(ArgumentError)
+    expect(peer.sent).to be_empty
+  end
+
+  it 'requires explicit identity-key restoration without conflating omitted owner metadata' do
+    profile = Meshtastic::DeviceProfile.new(config: { security: { private_key: 'k' * 32, public_key: 'p' * 32 } })
+    bytes = profile.to_proto
+    expect { backup_api.import(transport_obj: peer.handle, backup: bytes) }.to raise_error(ArgumentError, /identity_keys/)
+    expect(peer.sent).to be_empty
+    result = backup_api.import(transport_obj: peer.handle, backup: bytes, identity_keys: :restore, timeout: 0.3)
+    expect(result).to include(acknowledged: 1, persistence_verified: false, reconnect_required: true)
+    expect(result[:warnings].join).to match(/node number.*reconnect/i)
+    expect(peer.sent.last.set_config.security.private_key).to eq('k' * 32)
+    expect(bytes).to eq(profile.to_proto)
+    peer.sent.clear
+    clean = Meshtastic::DeviceProfile.new(config: { security: { serial_enabled: true } })
+    expect { backup_api.import(transport_obj: peer.handle, backup: clean.to_proto, dry_run: true) }.not_to raise_error
+    expect(peer.sent).to be_empty
+  end
+
+  it 'checks policy consistently for JSON security keys and channel sharing before edit requests' do
+    messages = [[Meshtastic::Config.new(security: { public_key: 'p' * 32 }), 'config', 'SECURITY_CONFIG', { identity_keys: :restore }],
+                [Meshtastic::Channel.new(settings: { uplink_enabled: true }), 'channel', 0, { allow_privacy_changes: true }]]
+    messages.each do |message, section, slot, consent|
+      document = { 'format' => backup_api::FORMAT, 'version' => 1, 'warning' => '', 'records' => [
+        { 'section' => section, 'slot' => slot, 'value' => JSON.parse(message.class.encode_json(message, preserve_proto_fieldnames: true)) }
+      ] }
+      expect { backup_api.import(transport_obj: peer.handle, backup: document, edit_transaction: true) }.to raise_error(ArgumentError)
+      report = backup_api.import({ transport_obj: peer.handle, backup: document, dry_run: true }.merge(consent))
+      expect(report[:planned]).to eq(1)
+      expect(peer.sent).to be_empty
+    end
+  end
+
+  it 'documents explicit restore consent and reconnect limitations in runtime help' do
+    expect { backup_api.help }.to output(/identity_keys:.*:reject.*:restore.*allow_privacy_changes:.*reconnect/m).to_stdout
+  end
+
+  it 'requires privacy opt-in for location and broker sharing without silently redacting values' do
+    profiles = [Meshtastic::DeviceProfile.new(fixed_position: { latitude_i: 1 }),
+                Meshtastic::DeviceProfile.new(config: { position: {} }),
+                Meshtastic::DeviceProfile.new(module_config: { mqtt: { enabled: true } }),
+                Meshtastic::DeviceProfile.new(channel_url: Meshtastic::Admin::Channel.export_url(channels: [
+                                                                                                   Meshtastic::Channel.new(role: :PRIMARY, settings: { module_settings: { position_precision: 32 } })
+                                                                                                 ]))]
+    profiles.each do |profile|
+      bytes = profile.to_proto
+      expect { backup_api.import(transport_obj: peer.handle, backup: bytes) }.to raise_error(ArgumentError, /allow_privacy_changes/)
+      expect(peer.sent).to be_empty
+      report = backup_api.import(transport_obj: peer.handle, backup: bytes, dry_run: true, allow_privacy_changes: true)
+      expect(report[:warnings].join).to match(/privacy.*location.*MQTT/i)
+      expect(report[:planned]).to be_positive
+      expect(bytes).to eq(profile.to_proto)
+    end
+  end
+end
+
+describe 'Meshtastic::Admin::Backup telemetry privacy' do
+  let(:backup_api) { Meshtastic::Admin::Backup }
+  let(:peer) { BackupRadioPeer.new }
+
+  %i[json device_profile].each do |format|
+    context "with #{format} input" do
+      let(:telemetry) { {} }
+      let(:message) { Meshtastic::ModuleConfig.new(telemetry: telemetry) }
+      let(:backup) do
+        if format == :device_profile
+          Meshtastic::DeviceProfile.new(long_name: 'Portable', module_config: { telemetry: telemetry }).to_proto
+        else
+          JSON.generate({ 'format' => backup_api::FORMAT, 'version' => 1, 'warning' => '', 'records' => [
+                          { 'section' => 'owner', 'slot' => nil, 'value' => { 'long_name' => 'Portable' } },
+                          { 'section' => 'module_config', 'slot' => 'TELEMETRY_CONFIG',
+                            'value' => JSON.parse(message.class.encode_json(message, preserve_proto_fieldnames: true)) }
+                        ] })
+        end
+      end
+      let(:options) { { transport_obj: peer.handle, backup: backup, format: format, timeout: 0.3 } }
+
+      %i[device_telemetry_enabled environment_measurement_enabled air_quality_enabled power_measurement_enabled health_measurement_enabled].each do |flag|
+        it "rejects #{flag} before any requests, including dry runs and edit transactions" do
+          telemetry[flag] = true
+          [{}, { dry_run: true }, { edit_transaction: true }, { allow_privacy_changes: false }].each do |policy|
+            expect { backup_api.import(options.merge(policy)) }.to raise_error(ArgumentError, /allow_privacy_changes/)
+            expect(peer.sent).to be_empty
+          end
+        end
+
+        it "restores #{flag} unchanged only with explicit consent and warns without values" do
+          telemetry.merge!(flag => true, device_update_interval: 123_457)
+          original = backup.dup
+          report = backup_api.import(options.merge(allow_privacy_changes: true, dry_run: true))
+          expect(peer.sent).to be_empty
+          expect(report[:warnings].join).to match(/telemetry.*device.*environment.*air quality.*power.*health/i)
+          expect(report.inspect).not_to include('123457', 'Portable')
+          result = backup_api.import(options.merge(allow_privacy_changes: true, verify: true))
+          expect(result).to include(status: :readback_matched, acknowledged: 2, readback_matched: 2)
+          expect(peer.sent.find { |sent| sent.payload_variant == :set_module_config }.set_module_config).to eq(message)
+          expect(backup).to eq(original)
+        end
+      end
+
+      it 'permits disabled broadcasts with nonzero intervals and local display preferences' do
+        telemetry.merge!(device_telemetry_enabled: false, environment_measurement_enabled: false,
+                         air_quality_enabled: false, power_measurement_enabled: false, health_measurement_enabled: false,
+                         device_update_interval: 60, environment_update_interval: 60, air_quality_interval: 60,
+                         power_update_interval: 60, health_update_interval: 60, environment_screen_enabled: true,
+                         power_screen_enabled: true, health_screen_enabled: true, air_quality_screen_enabled: true,
+                         environment_display_fahrenheit: true)
+        result = backup_api.import(options.merge(verify: true))
+        expect(result).to include(status: :readback_matched, acknowledged: 2)
+        expect(result[:warnings].join).not_to include('Privacy:')
+        expect(peer.state[:TELEMETRY_CONFIG]).to eq(message)
+      end
+
+      it 'permits an empty telemetry section without privacy consent' do
+        result = backup_api.import(options.merge(dry_run: true))
+        expect(result).to include(status: :dry_run, planned: 2)
+        expect(result[:warnings].join).not_to include('Privacy:')
+        expect(peer.sent).to be_empty
+      end
+    end
+  end
+
+  it 'documents telemetry consent in runtime help' do
+    expect { backup_api.help }.to output(/allow_privacy_changes:.*telemetry.*device.*environment.*air quality.*power.*health/).to_stdout
+  end
+end
+
+describe 'Meshtastic::Admin::Backup export' do
+  let(:backup_api) { Meshtastic::Admin::Backup }
+  let(:peer) { BackupRadioPeer.new }
+  let(:options) { { transport_obj: peer.handle, config_types: [:DEVICE_CONFIG], module_config_types: [:MQTT_CONFIG], channel_indexes: [0], include_ui: true, timeout: 0.3 } }
+
   it 'exports binary DeviceProfile bytes with fresh values and presence-aware semantic round trips' do
     peer.state[:owner].is_unmessagable = false
     peer.state[:channel].settings.psk = "\x01".b
@@ -153,7 +297,7 @@ describe 'Meshtastic::Admin::Backup' do
     expect(profile.canned_messages).to eq('')
     expect(peer.sent.map(&:payload_variant)).to eq(%i[get_ringtone_request get_canned_message_module_messages_request])
     peer.sent.clear
-    expect(backup_api.import(transport_obj: peer.handle, backup: result[:backup], dry_run: true)[:planned]).to eq(3)
+    expect(backup_api.import(transport_obj: peer.handle, backup: result[:backup], dry_run: true, allow_privacy_changes: true)[:planned]).to eq(3)
     expect(peer.sent).to be_empty
     [nil, 'bad', { unknown: 1 }].each do |position|
       expect { backup_api.export(opts.merge(fixed_position: position)) }.to raise_error(ArgumentError)
@@ -183,7 +327,7 @@ describe 'Meshtastic::Admin::Backup' do
       expect(profile.module_config[field.name]).to eq(peer.state[backup_api::MODULE_TYPES[index]][field.name])
     end
     peer.sent.clear
-    expect(backup_api.import(transport_obj: peer.handle, backup: result[:backup], dry_run: true)[:planned]).to eq(25)
+    expect(backup_api.import(transport_obj: peer.handle, backup: result[:backup], dry_run: true, allow_privacy_changes: true)[:planned]).to eq(25)
     expect(peer.sent).to be_empty
     peer.state[:device] = Meshtastic::Config.new(network: {})
     expect { backup_api.export(options.merge(format: :device_profile, include_ui: false, channel_indexes: [])) }.to raise_error(ArgumentError, /slot/)
@@ -219,14 +363,14 @@ describe 'Meshtastic::Admin::Backup import and JSON export' do
     Meshtastic::Config.descriptor.to_a.take(8).each { |field| config[field.name] = field.subtype.msgclass.new }
     modules = Meshtastic::LocalModuleConfig.new(version: 24)
     Meshtastic::ModuleConfig.descriptor.each { |field| modules[field.name] = field.subtype.msgclass.new }
-    config.security = Meshtastic::Config::SecurityConfig.new(private_key: "\x00\xff".b, admin_key: ['synthetic-key'], serial_enabled: false)
+    config.security = Meshtastic::Config::SecurityConfig.new(private_key: "\x00\xff".b * 16, admin_key: ['k' * 32], serial_enabled: false)
     config.lora = Meshtastic::Config::LoRaConfig.new(region: :US, tx_power: -1, frequency_offset: 1.25, ignore_incoming: [1, 0xffffffff])
     modules.mqtt = Meshtastic::ModuleConfig::MQTTConfig.new(enabled: false, password: 'synthetic-password')
     channels = Meshtastic::ChannelSet.new(settings: [{ name: 'test', psk: "\x01".b }], lora_config: config.lora)
     profile = Meshtastic::DeviceProfile.new(long_name: 'Profile', short_name: '', is_licensed: false, is_unmessagable: false,
                                             config: config, module_config: modules, channel_url: "https://meshtastic.org/e/##{Base64.urlsafe_encode64(channels.to_proto, padding: false)}",
                                             fixed_position: { latitude_i: 0, longitude_i: 0, altitude: 0 }, ringtone: '', canned_messages: '')
-    result = backup_api.import(transport_obj: peer.handle, backup: profile.to_proto, format: :device_profile, verify: true, timeout: 0.3)
+    result = backup_api.import(transport_obj: peer.handle, backup: profile.to_proto, format: :device_profile, verify: true, identity_keys: :restore, allow_privacy_changes: true, timeout: 0.3)
     expect(result).to include(status: :readback_incomplete, planned: 30, acknowledged: 30, readback_matched: 29)
     expect(result[:records].find { |record| record[:section] == 'fixed_position' }).to include(readback: :unsupported)
     expect(peer.state[:owner]).to eq(Meshtastic::User.new(long_name: 'Profile', short_name: '', is_licensed: false, is_unmessagable: false))
@@ -344,7 +488,7 @@ describe 'Meshtastic::Admin::Backup missing write ACK recovery' do
   let(:backup_api) { Meshtastic::Admin::Backup }
   let(:peer) { BackupRadioPeer.new }
   let(:profile) { Meshtastic::DeviceProfile.new(module_config: { mqtt: { enabled: true, password: 'synthetic-secret' } }, config: { lora: { region: :US } }) }
-  let(:options) { { transport_obj: peer.handle, backup: profile.to_proto, edit_transaction: true, timeout: 0.15 } }
+  let(:options) { { transport_obj: peer.handle, backup: profile.to_proto, edit_transaction: true, allow_privacy_changes: true, timeout: 0.15 } }
 
   before { peer.drop_ack_on = :set_module_config }
 
@@ -517,13 +661,13 @@ describe 'Meshtastic::Admin::Backup DeviceProfile validation' do
   it 'keeps ordinary profile writes in source plan order before disruptive sections' do
     modules = Meshtastic::ModuleConfig.descriptor.to_h { |field| [field.name.to_sym, {}] }
     profile = Meshtastic::DeviceProfile.new(long_name: 'order', ringtone: '', canned_messages: '', config: { device: {}, position: {}, power: {}, display: {}, lora: {}, security: {} }, module_config: modules)
-    plan = backup_api.import(transport_obj: peer.handle, backup: profile.to_proto, dry_run: true)[:plan]
+    plan = backup_api.import(transport_obj: peer.handle, backup: profile.to_proto, dry_run: true, allow_privacy_changes: true)[:plan]
     expect(plan.map { |entry| entry[:slot] || entry[:section] }).to eq(%w[owner ringtone canned_messages DEVICE_CONFIG POSITION_CONFIG POWER_CONFIG DISPLAY_CONFIG] + backup_api::MODULE_TYPES.map(&:to_s) + %w[LORA_CONFIG SECURITY_CONFIG])
     expect(peer.sent).to be_empty
   end
 
   it 'auto-detects binary content and cfg paths while retaining explicit and automatic JSON input' do
-    profile = Meshtastic::DeviceProfile.new(long_name: 'x' * 123, is_unmessagable: false)
+    profile = Meshtastic::DeviceProfile.new(long_name: 'x' * 24, is_unmessagable: false)
     Dir.mktmpdir do |directory|
       ['profile.cfg', 'profile.bin'].each do |name|
         path = File.join(directory, name)
@@ -683,7 +827,7 @@ describe 'Meshtastic::Admin::Backup validation and readback' do
     end
     document = backup_api.export(options.merge(config_types: backup_api::CONFIG_TYPES, module_config_types: backup_api::MODULE_TYPES, include_owner: false, include_ui: false, channel_indexes: []))[:backup]
     peer.sent.clear
-    result = backup_api.import(transport_obj: peer.handle, backup: document, timeout: 0.3)
+    result = backup_api.import(transport_obj: peer.handle, backup: document, allow_privacy_changes: true, timeout: 0.3)
     expect(result[:acknowledged]).to eq(configs.length + modules.length)
     restored = peer.sent.map { |message| message.public_send(message.payload_variant) }
     expect(restored).to match_array(configs + modules)

data/spec/lib/meshtastic/admin/config_spec.rb

@@ -9,7 +9,7 @@ RSpec.describe Meshtastic::Admin::Config do
   end
 end
 
-describe Meshtastic::Admin::Config do
+module AdminConfigSpecHelpers
   def fake_serial_obj
     written = +''.b
     serial_conn = Object.new
@@ -28,6 +28,10 @@ describe Meshtastic::Admin::Config do
     body = frame.byteslice(4, (frame.getbyte(2) << 8) + frame.getbyte(3))
     Meshtastic::AdminMessage.decode(Meshtastic::ToRadio.decode(body).packet.decoded.payload)
   end
+end
+
+describe Meshtastic::Admin::Config do
+  include AdminConfigSpecHelpers
 
   it 'rejects legacy connection keys rather than silently filtering them' do
     %i[serial_obj bluetooth_obj tcp_obj mqtt_obj].each do |key|
@@ -123,6 +127,71 @@ describe Meshtastic::Admin::Config do
       expect(message.get_config_request).to eq(config_type)
     end
   end
+end
+
+describe Meshtastic::Admin::Config, 'read-modify-readback helpers' do
+  include AdminConfigSpecHelpers
+
+  it 'updates signature policy with fresh correlated readback while preserving other security fields' do
+    current = Meshtastic::Config.new(security: { serial_enabled: true, public_key: 'k' * 32 })
+    handle = fake_serial_obj.merge(from_radio_queue: Queue.new, messages: [])
+    handle[:serial_conn].define_singleton_method(:write) do |bytes|
+      packet = Meshtastic::ToRadio.decode(bytes.byteslice(4..)).packet
+      message = Meshtastic::AdminMessage.decode(packet.decoded.payload)
+      handle[:messages] << message
+      if message.payload_variant == :get_config_request
+        payload = Meshtastic::AdminMessage.new(get_config_response: current).to_proto
+        data = Meshtastic::Data.new(portnum: :ADMIN_APP, request_id: packet.id, payload: payload)
+      else
+        current = Meshtastic::Config.decode(message.set_config.to_proto)
+        data = Meshtastic::Data.new(portnum: :ROUTING_APP, request_id: packet.id)
+      end
+      handle[:from_radio_queue] << Meshtastic::FromRadio.new(packet: Meshtastic::MeshPacket.new(from: packet.to, decoded: data))
+      bytes.bytesize
+    end
+    result = described_class.set_packet_signature_policy(transport_obj: handle, policy: :PACKET_SIGNATURE_POLICY_STRICT)
+    expect(current.security).to have_attributes(serial_enabled: true, public_key: 'k' * 32, packet_signature_policy: :PACKET_SIGNATURE_POLICY_STRICT)
+    expect(handle[:messages].map(&:payload_variant)).to eq(%i[get_config_request set_config get_config_request])
+    expect(result).to include(matched: true, reboot_requested: false)
+    expect(result[:acknowledgment][:delivery]).to eq(:acknowledged)
+    expect(result[:readback][:delivery]).to eq(:readback)
+  end
+
+  it 'sets local receive-only without resetting LoRa fields or issuing a reboot and reports mismatched readback' do
+    [true, false].each do |apply|
+      current = Meshtastic::Config.new(lora: { region: :US, hop_limit: 3, tx_enabled: true })
+      handle = fake_serial_obj.merge(from_radio_queue: Queue.new, messages: [])
+      handle[:serial_conn].define_singleton_method(:write) do |bytes|
+        packet = Meshtastic::ToRadio.decode(bytes.byteslice(4..)).packet
+        message = Meshtastic::AdminMessage.decode(packet.decoded.payload)
+        handle[:messages] << message
+        if message.payload_variant == :get_config_request
+          data = Meshtastic::Data.new(portnum: :ADMIN_APP, request_id: packet.id,
+                                      payload: Meshtastic::AdminMessage.new(get_config_response: current).to_proto)
+        else
+          current = message.set_config if apply
+          data = Meshtastic::Data.new(portnum: :ROUTING_APP, request_id: packet.id)
+        end
+        handle[:from_radio_queue] << Meshtastic::FromRadio.new(packet: Meshtastic::MeshPacket.new(from: packet.to, decoded: data))
+        bytes.bytesize
+      end
+      result = described_class.set_receive_only(transport_obj: handle, enabled: true)
+      expect(result).to include(matched: apply, reboot_requested: false)
+      expect(handle[:messages][1].set_config.lora).to have_attributes(region: :US, hop_limit: 3, tx_enabled: false)
+      expect(handle[:messages].map(&:payload_variant)).to eq(%i[get_config_request set_config get_config_request])
+    end
+  end
+
+  it 'rejects invalid policy and receive-only settings before any transmission' do
+    handle = fake_serial_obj
+    [99, nil, true, 'PACKET_SIGNATURE_POLICY_STRICT', :UNKNOWN].each do |policy|
+      expect { described_class.set_packet_signature_policy(transport_obj: handle, policy: policy) }.to raise_error(ArgumentError)
+    end
+    expect { described_class.set_receive_only(transport_obj: handle, enabled: 'true') }.to raise_error(ArgumentError)
+    expect { described_class.set_receive_only(transport_obj: handle, enabled: true, to: '!aabbccdd') }.to raise_error(ArgumentError, /local/)
+    expect { described_class.set_receive_only(transport_obj: MQTTClient.new, enabled: true) }.to raise_error(ArgumentError, /local/)
+    expect(handle[:written]).to be_empty
+  end
 
   it 'prints usage without raising' do
     expect { described_class.help }.to output(/USAGE/).to_stdout

data/spec/lib/meshtastic/admin/firmware_migration_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Meshtastic::Admin::Firmware, 'v2.8.1 migration (no hardware)' do
+  let(:version) { '2.8.1.8e6a88d' }
+  let(:public_key) { 'k'.b * 32 }
+
+  # Hardware writes are mocked; ToRadio, AdminMessage and FromRadio codecs and
+  # Admin source/request correlation are production code, not mocked requests.
+  def radio(kind, version:, key:, decoys: false, fresh: true)
+    queue = Queue.new
+    requests = []
+    writer = Object.new
+    writer.define_singleton_method(:write) do |bytes|
+      packet = Meshtastic::ToRadio.decode(kind == :bluetooth ? bytes : bytes.byteslice(4..)).packet
+      request = Meshtastic::AdminMessage.decode(packet.decoded.payload)
+      requests << [packet.to, request.payload_variant]
+      response = if request.get_owner_request
+                   Meshtastic::AdminMessage.new(get_owner_response: Meshtastic::User.new(public_key: key))
+                 else
+                   Meshtastic::AdminMessage.new(get_device_metadata_response: Meshtastic::DeviceMetadata.new(firmware_version: version))
+                 end
+      sources = decoys ? [[999, packet.id], [456, packet.id - 1]] : []
+      sources << [456, packet.id] if fresh
+      sources.each do |from, id|
+        frame = Meshtastic::FromRadio.new(packet: Meshtastic::MeshPacket.new(from: from, decoded: Meshtastic::Data.new(portnum: :ADMIN_APP, request_id: id, payload: response.to_proto)))
+        queue << Meshtastic::FromRadio.decode(frame.to_proto)
+      end
+      bytes.bytesize
+    end
+    writer.define_singleton_method(:flush) { true }
+    handle = { my_node_num: 456, from_radio_queue: queue, tx_mutex: Mutex.new, metadata: { firmware_version: '2.8.1.8e6a88d' } }
+    handle[kind == :bluetooth ? :bluetooth_conn : :serial_conn] = writer
+    handle[:tcp_socket] = writer if kind == :tcp
+    transport = { serial: Meshtastic::Serial, bluetooth: Meshtastic::Bluetooth, tcp: Meshtastic::TCP }.fetch(kind)
+    allow(transport).to receive(:wait_for_config).and_return(handle)
+    allow(transport).to receive(:disconnect)
+    [handle, requests]
+  end
+
+  it 'rejects a reconnect callback returning a different transport before Admin traffic' do
+    handle, requests = radio(:serial, version: version, key: public_key)
+    allow(Meshtastic::Bluetooth).to receive(:wait_for_config).and_return(handle)
+    expect(Meshtastic::Serial).to receive(:disconnect).with(serial_obj: handle)
+    expect(Meshtastic::Bluetooth).not_to receive(:disconnect)
+    expect do
+      described_class.verify_reboot(transport: :bluetooth, reconnect: ->(_) { handle }, expected_version: version, reboot_delay: 0, timeout: 0.1)
+    end.to raise_error(ArgumentError, /transport/)
+    expect(requests).to be_empty
+  end
+
+  it 'validates migration identity and explicit endpoint settings before invoking any loader' do
+    base = { transport: :serial, connection: { block_dev: '/dev/ttyACM0' }, expected_version: version }
+    invalid = [{ expected_public_key: 'short' }, { expected_public_key: 'a' * 64 }, { expected_public_key: "\x00" * 32 },
+               { previous_node: 123 }, { expected_node: 0xffffffff }, { previous_node: '!0000007b', expected_public_key: public_key },
+               { to: '!000001c8' }, { connection: {} }, { transport: :mqtt }]
+    expect(described_class::BLE).not_to receive(:install)
+    invalid.each do |options|
+      expect { described_class.install(protocol: :unified_ble, bytes: 'abc', verify: base.merge(options)) }.to raise_error(ArgumentError)
+    end
+  end
+
+  it 'documents the public continuity options in actual runtime help' do
+    expect { described_class.help }.to output(/expected_public_key:.*previous_node:/m).to_stdout
+  end
+
+  %i[serial bluetooth tcp].each do |kind|
+    %w[2.8.1.wrongsuffix 2.8.1 2.8.0.8e6a88d 2.7.23.b246bcd].each do |wrong|
+      it "rejects #{wrong} despite exact cached metadata over #{kind}" do
+        handle, = radio(kind, version: wrong, key: public_key)
+        expect do
+          described_class.verify_reboot(transport: kind, reconnect: ->(_) { handle }, expected_version: version,
+                                        expected_public_key: public_key, previous_node: 123, reboot_delay: 0, timeout: 1)
+        end.to raise_error(IOError, /version mismatch/)
+      end
+    end
+
+    it "does not accept an arbitrary new node with another key over #{kind}" do
+      handle, requests = radio(kind, version: version, key: 'x' * 32)
+      expect do
+        described_class.verify_reboot(transport: kind, reconnect: ->(_) { handle }, expected_version: version,
+                                      expected_public_key: public_key, previous_node: 123, reboot_delay: 0, timeout: 1)
+      end.to raise_error(IOError, 'Post-reboot public-key identity mismatch')
+      expect(requests).to eq([[456, :get_owner_request]])
+    end
+
+    it "does not relax an explicitly strict numeric expectation over #{kind}" do
+      handle, requests = radio(kind, version: version, key: public_key)
+      expect do
+        described_class.verify_reboot(transport: kind, reconnect: ->(_) { handle }, expected_version: version,
+                                      expected_node: 123, expected_public_key: public_key, reboot_delay: 0, timeout: 1)
+      end.to raise_error(IOError, /node identity mismatch/)
+      expect(requests).to be_empty
+    end
+
+    [false, true].each do |owner|
+      it "rejects stale or wrong-source #{owner ? 'owner' : 'metadata'} and retains unrelated traffic over #{kind}" do
+        handle, = radio(kind, version: version, key: public_key, decoys: true, fresh: false)
+        identity = owner ? { expected_public_key: public_key } : {}
+        expect do
+          described_class.verify_reboot({ transport: kind, reconnect: ->(_) { handle }, expected_version: version,
+                                          reboot_delay: 0, timeout: 0.05 }.merge(identity))
+        end.to raise_error(Timeout::Error)
+        expect(handle[:from_radio_queue].size).to eq(2)
+      end
+    end
+
+    it "allows an explicit key-continuous node migration over #{kind} without exposing keys" do
+      handle, requests = radio(kind, version: version, key: public_key, decoys: true)
+      result = described_class.verify_reboot(transport: kind, reconnect: ->(_) { handle }, expected_version: version,
+                                             expected_public_key: public_key, previous_node: 123, reboot_delay: 0, timeout: 1)
+      expect(result).to include(status: :boot_verified, node_num: 456, previous_node_num: 123,
+                                node_id: '!000001c8', previous_node_id: '!0000007b', node_changed: true,
+                                identity: :public_key_continuity)
+      expect(requests).to eq([[456, :get_owner_request], [456, :get_device_metadata_request]])
+      expect(result.inspect).not_to include(public_key)
+      expect(handle[:from_radio_queue].size).to eq(4)
+    end
+  end
+end

data/spec/lib/meshtastic/admin/firmware_spec.rb

@@ -134,7 +134,7 @@ RSpec.describe Meshtastic::Admin::Firmware do
     handle = { serial_conn: Object.new, my_node_num: 123 }
     expect(Meshtastic::Serial).to receive(:wait_for_config).with(serial_obj: handle, timeout: 1).and_return(handle)
     expect(Meshtastic::Serial).to receive(:disconnect).with(serial_obj: handle)
-    expect(Meshtastic::Admin).to receive(:request).with(transport_obj: handle, get_device_metadata_request: true, timeout: 1)
+    expect(Meshtastic::Admin).to receive(:request).with(transport_obj: handle, to: 123, get_device_metadata_request: true, timeout: 1)
                                                   .and_return(value: Meshtastic::DeviceMetadata.new(firmware_version: 'expected'))
     result = described_class.verify_reboot(transport: :serial, reconnect: ->(_options) { handle },
                                            expected_version: 'expected', reboot_delay: 0, timeout: 1)

data/spec/lib/meshtastic/admin/firmware_target_selection_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Meshtastic::Admin::Firmware, 'installer target selection (no hardware)' do
+  it 'rejects unimplemented chips before opening a serial programmer' do
+    expect(UART).not_to receive(:open)
+    %i[esp32c6 rp2350 stm32 nrf52840].each do |chip|
+      expect do
+        described_class.install(protocol: :esp_rom, chip: chip, bytes: 'image', port: '/dev/ttyACM0', offset: 0x10000, flash_size: 4_194_304)
+      end.to raise_error(ArgumentError, /chip must/)
+    end
+  end
+
+  it 'never guesses a Secure Nordic or unsupported board loader from an artifact' do
+    expect(Socket).not_to receive(:tcp)
+    expect(UART).not_to receive(:open)
+    %i[nordic_secure_dfu rp2350 stm32 mqtt].each do |protocol|
+      expect { described_class.install(protocol: protocol, bytes: 'image') }.to raise_error(NotImplementedError)
+    end
+  end
+
+  it 'does not pretend that full erase is implemented' do
+    expect(UART).not_to receive(:open)
+    expect(Socket).not_to receive(:tcp)
+    %i[esp_rom unified_wifi unified_ble nordic_dfu uf2 swd].each do |protocol|
+      expect { described_class.install(protocol: protocol, bytes: 'image', full_erase: true) }.to raise_error(ArgumentError, /[Uu]nsupported|[Uu]nknown/)
+    end
+  end
+
+  it 'rejects unsupported RP2350 UF2 families before opening a destination' do
+    expect(File).not_to receive(:open)
+    expect do
+      described_class.install(protocol: :uf2, bytes: 'image', family_id: 0xe48bff59, mount: '/selected/volume', board_id: 'RP2350')
+    end.to raise_error(ArgumentError, /Unsupported UF2 family/)
+  end
+
+  it 'requires the exact supported SWD chip before invoking any programmer' do
+    expect(described_class::Hex).not_to receive(:program)
+    expect do
+      described_class::Hex.validate(bytes: ':00000001FF', expected_chip: :stm32)
+    end.to raise_error(ArgumentError, /nrf52840/)
+  end
+end

data/spec/lib/meshtastic/admin/validation_spec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Admin semantic validation' do
+  it 'rejects owner names beyond the pinned firmware UTF-8 byte limit without truncating' do
+    name = 'é' * 13
+    user = Meshtastic::User.new(long_name: name)
+    expect { Meshtastic::Admin.encode(set_owner: user) }.to raise_error(ArgumentError, /24/)
+    expect(user.long_name).to eq(name)
+    expect(Meshtastic::Admin.encode(set_owner: Meshtastic::User.new(long_name: 'é' * 12)).set_owner.long_name.bytesize).to eq(24)
+  end
+
+  it 'rejects names firmware cannot represent, while preserving omitted names' do
+    [{ long_name: "bad\0name" }, { long_name: " \t" }, { short_name: 'ééé' }].each do |fields|
+      expect { Meshtastic::Admin.encode(set_owner: Meshtastic::User.new(fields)) }.to raise_error(ArgumentError)
+    end
+    expect { Meshtastic::Admin.encode(set_owner: Meshtastic::User.new) }.not_to raise_error
+  end
+
+  it 'validates ham nanopb fields and the composed owner name before encoding' do
+    [{ call_sign: '' }, { call_sign: '        ' }, { call_sign: 'ABCDEFGH' },
+     { call_sign: 'N0CALL', long_name: 'é' * 8 }, { call_sign: 'N0CALL', short_name: 'ABCDE' }].each do |fields|
+      expect { Meshtastic::Admin.encode(set_ham_mode: Meshtastic::HamParameters.new(fields)) }.to raise_error(ArgumentError)
+    end
+    expect { Meshtastic::Admin.encode(set_ham_mode: Meshtastic::HamParameters.new(call_sign: 'N0CALL', long_name: 'é' * 7)) }.not_to raise_error
+  end
+
+  it 'rejects unknown enum integers recursively and accepts known numeric enum values' do
+    [Meshtastic::AdminMessage.new(get_config_request: 999),
+     Meshtastic::AdminMessage.new(set_config: { lora: { region: 999 } }),
+     Meshtastic::AdminMessage.new(set_module_config: { serial: { mode: 999 } })].each do |message|
+      expect { Meshtastic::Admin.encode(message: message) }.to raise_error(ArgumentError, /enum/)
+    end
+    expect { Meshtastic::Admin.encode(get_config_request: 0) }.not_to raise_error
+  end
+
+  it 'requires a selected writable config section but allows an explicitly selected default section' do
+    [Meshtastic::AdminMessage.new(set_config: Meshtastic::Config.new),
+     Meshtastic::AdminMessage.new(set_module_config: Meshtastic::ModuleConfig.new),
+     Meshtastic::AdminMessage.new(set_config: { sessionkey: {} }),
+     Meshtastic::AdminMessage.new(set_config: { device_ui: {} })].each do |message|
+      expect { Meshtastic::Admin.encode(message: message) }.to raise_error(ArgumentError, /section|sessionkey|device_ui/)
+    end
+    expect { Meshtastic::Admin.encode(set_config: Meshtastic::Config.new(device: {})) }.not_to raise_error
+  end
+
+  it 'applies channel PSK, name, index and role validation to raw Admin writes' do
+    [{ index: 8 }, { index: -1 }, { role: 99 }, { settings: { psk: 'bad' } },
+     { settings: { name: 'é' * 6 } }, { settings: { name: "x\0y" } }].each do |fields|
+      expect { Meshtastic::Admin.encode(set_channel: Meshtastic::Channel.new(fields)) }.to raise_error(ArgumentError)
+    end
+    [0, 1, 16, 32].each do |length|
+      channel = Meshtastic::Channel.new(index: 7, role: :PRIMARY, settings: { name: 'é' * 5, psk: 'x' * length })
+      expect(Meshtastic::Admin.encode(set_channel: channel).set_channel).to eq(channel)
+    end
+  end
+
+  it 'preflights every URL section and rejects invalid offline settings before any write' do
+    expect(Meshtastic::Admin).not_to receive(:send)
+    expect { Meshtastic::Admin::Channel.build_settings(name: "x\0y") }.to raise_error(ArgumentError)
+    set = Meshtastic::ChannelSet.new(settings: [{ psk: 'x' }], lora_config: { region: 999 })
+    url = "https://meshtastic.org/e/##{Base64.urlsafe_encode64(set.to_proto, padding: false)}"
+    expect { Meshtastic::Admin::Channel.apply_url(url: url, transport_obj: { serial_conn: Object.new }) }.to raise_error(ArgumentError)
+  end
+
+  it 'rejects malformed security key sizes rather than silently triggering firmware identity preservation' do
+    [{ private_key: 'bad' }, { public_key: 'bad' }, { admin_key: ['bad'] }].each do |fields|
+      expect { Meshtastic::Admin.encode(set_config: Meshtastic::Config.new(security: fields)) }.to raise_error(ArgumentError, /key/)
+    end
+    expect { Meshtastic::Admin.encode(set_config: Meshtastic::Config.new(security: { private_key: 'k' * 32 })) }.not_to raise_error
+  end
+
+  it 'rejects invalid mutations before delivery or remote session acquisition across public setters' do
+    handle = { serial_conn: Object.new, my_node_num: 0xaabbccdd, from_radio_queue: Queue.new }
+    transport = { transport_obj: handle, to: '!aabbccee' }
+    expect(Meshtastic).not_to receive(:deliver_data)
+    [[:set_owner, { long_name: 'x' * 25 }], [:set_ham_mode, { call_sign: '' }],
+     [:set_channel, { channel_settings: Meshtastic::Channel.new(index: 8) }],
+     [:set_config, { config: Meshtastic::Config.new }],
+     [:set_module_config, { module_config: Meshtastic::ModuleConfig.new }]].each do |method, payload|
+      expect { Meshtastic::Admin.public_send(method, transport.merge(payload)) }.to raise_error(ArgumentError)
+    end
+    expect { Meshtastic::Admin::Config.set_lora(transport.merge(lora: { region: 999 })) }.to raise_error(ArgumentError)
+    expect { Meshtastic::ModuleConfig.set(transport.merge(module_config: Meshtastic::ModuleConfig.new)) }.to raise_error(ArgumentError)
+    expect { Meshtastic::Admin::Channel.set(transport.merge(settings: { psk: 'bad' })) }.to raise_error(ArgumentError)
+    expect(handle).not_to have_key(:admin_sessions)
+  end
+end