meshtastic 0.0.179 → 0.0.181

data/lib/meshtastic/admin/config.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require 'meshtastic/config_pb'
+
+module Meshtastic
+  module Admin
+    module Config
+      public_class_method def self.get(opts = {})
+        Admin.get_config(opts.merge(config_type: opts[:config_type] || :DEVICE_CONFIG))
+      end
+
+      public_class_method def self.set(opts = {})
+        config = opts[:config]
+        raise ArgumentError, 'config must contain one Config section' unless config.is_a?(Meshtastic::Config) && config.payload_variant
+        raise ArgumentError, 'sessionkey is a request-only placeholder; use get_sessionkey' if config.payload_variant == :sessionkey
+
+        section_keys = Meshtastic::Config.descriptor.map { |field| field.name.to_sym }
+        return Admin.store_ui_config(opts.except(*section_keys, :config).merge(ui_config: config.device_ui)) if config.payload_variant == :device_ui
+
+        Admin.set_config(opts.except(*section_keys).merge(config: config))
+      end
+
+      public_class_method def self.get_device(opts = {})
+        get(opts.merge(config_type: :DEVICE_CONFIG))
+      end
+
+      public_class_method def self.get_position(opts = {})
+        get(opts.merge(config_type: :POSITION_CONFIG))
+      end
+
+      public_class_method def self.get_power(opts = {})
+        get(opts.merge(config_type: :POWER_CONFIG))
+      end
+
+      public_class_method def self.get_network(opts = {})
+        get(opts.merge(config_type: :NETWORK_CONFIG))
+      end
+
+      public_class_method def self.get_display(opts = {})
+        get(opts.merge(config_type: :DISPLAY_CONFIG))
+      end
+
+      public_class_method def self.get_lora(opts = {})
+        get(opts.merge(config_type: :LORA_CONFIG))
+      end
+
+      public_class_method def self.get_bluetooth(opts = {})
+        get(opts.merge(config_type: :BLUETOOTH_CONFIG))
+      end
+
+      public_class_method def self.get_security(opts = {})
+        get(opts.merge(config_type: :SECURITY_CONFIG))
+      end
+
+      public_class_method def self.get_sessionkey(opts = {})
+        get(opts.merge(config_type: :SESSIONKEY_CONFIG))
+      end
+
+      public_class_method def self.get_device_ui(opts = {})
+        Admin.get_ui_config(opts.merge({}))
+      end
+
+      public_class_method def self.set_device(opts = {})
+        set(opts.merge(config: Meshtastic::Config.new(device: opts.fetch(:device))))
+      end
+
+      public_class_method def self.set_lora(opts = {})
+        set(opts.merge(config: Meshtastic::Config.new(lora: opts.fetch(:lora))))
+      end
+
+      public_class_method def self.set_position(opts = {})
+        set(opts.merge(config: Meshtastic::Config.new(position: opts.fetch(:position))))
+      end
+
+      public_class_method def self.set_power(opts = {})
+        set(opts.merge(config: Meshtastic::Config.new(power: opts.fetch(:power))))
+      end
+
+      public_class_method def self.set_network(opts = {})
+        set(opts.merge(config: Meshtastic::Config.new(network: opts.fetch(:network))))
+      end
+
+      public_class_method def self.set_display(opts = {})
+        set(opts.merge(config: Meshtastic::Config.new(display: opts.fetch(:display))))
+      end
+
+      public_class_method def self.set_bluetooth(opts = {})
+        set(opts.merge(config: Meshtastic::Config.new(bluetooth: opts.fetch(:bluetooth))))
+      end
+
+      public_class_method def self.set_security(opts = {})
+        set(opts.merge(config: Meshtastic::Config.new(security: opts.fetch(:security))))
+      end
+
+      public_class_method def self.set_sessionkey(opts = {})
+        set(opts.merge(config: Meshtastic::Config.new(sessionkey: opts.fetch(:sessionkey))))
+      end
+
+      public_class_method def self.set_device_ui(opts = {})
+        set(opts.merge(config: Meshtastic::Config.new(device_ui: opts.fetch(:device_ui))))
+      end
+
+      public_class_method def self.authors
+        "AUTHOR(S):\n        0day Inc. <support@0dayinc.com>\n      "
+      end
+
+      public_class_method def self.help
+        puts "USAGE:
+          # Request a radio Config section by ConfigType.
+          #{self}.get(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect',
+            config_type: 'optional - :DEVICE_CONFIG or another ConfigType (default: :DEVICE_CONFIG)'
+          )
+
+          # Write a Config protobuf to the node.
+          #{self}.set(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect',
+            config: 'required - Meshtastic::Config protobuf to write'
+          )
+
+          # Request DEVICE_CONFIG from the node.
+          #{self}.get_device(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+          )
+
+          # Request POSITION_CONFIG from the node.
+          #{self}.get_position(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+          )
+
+          # Request POWER_CONFIG from the node.
+          #{self}.get_power(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+          )
+
+          # Request NETWORK_CONFIG from the node.
+          #{self}.get_network(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+          )
+
+          # Request DISPLAY_CONFIG from the node.
+          #{self}.get_display(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+          )
+
+          # Request LORA_CONFIG from the node.
+          #{self}.get_lora(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+          )
+
+          # Request BLUETOOTH_CONFIG from the node.
+          #{self}.get_bluetooth(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+          )
+
+          # Request SECURITY_CONFIG from the node.
+          #{self}.get_security(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+          )
+
+          # Request SESSIONKEY_CONFIG from the node.
+          #{self}.get_sessionkey(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+          )
+
+          # Request DeviceUIConfig using dedicated firmware operation.
+          #{self}.get_device_ui(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+          )
+
+          # Write DeviceConfig wrapped in a Config protobuf.
+          #{self}.set_device(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect',
+            device: 'required - DeviceConfig protobuf or complete section field Hash'
+          )
+
+          # Write LoRaConfig wrapped in a Config protobuf.
+          #{self}.set_lora(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect',
+            lora: 'required - LoRaConfig protobuf or complete section field Hash'
+          )
+
+          # Write position configuration to node.
+          #{self}.set_position(position: 'required - PositionConfig protobuf or field hash')
+
+          # Write power configuration to node.
+          #{self}.set_power(power: 'required - PowerConfig protobuf or field hash')
+
+          # Write network configuration to node.
+          #{self}.set_network(network: 'required - NetworkConfig protobuf or field hash')
+
+          # Write display configuration to node.
+          #{self}.set_display(display: 'required - DisplayConfig protobuf or field hash')
+
+          # Write Bluetooth configuration to node.
+          #{self}.set_bluetooth(bluetooth: 'required - BluetoothConfig protobuf or field hash')
+
+          # Write security configuration to node.
+          #{self}.set_security(security: 'required - SecurityConfig protobuf or field hash')
+
+          # Reject writes to request-only session key placeholder.
+          #{self}.set_sessionkey(sessionkey: 'required - placeholder only; always raises ArgumentError')
+
+          # Write device UI configuration to node.
+          #{self}.set_device_ui(device_ui: 'required - DeviceUIConfig protobuf or field hash')
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+      end
+    end
+  end
+end

data/lib/meshtastic/admin/firmware/ble.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Meshtastic
+  module Admin
+    module Firmware
+      # ESP32 unified loader only; not the legacy firmware-ota protocol.
+      module BLE
+        SERVICE_UUID = '4fafc201-1fb5-459e-8fcc-c5c9c331914b'
+        OTA_UUID = '62ec0272-3ec5-11eb-b378-0242ac130005'
+        TX_UUID = '62ec0272-3ec5-11eb-b378-0242ac130003'
+
+        public_class_method def self.install(opts = {})
+          unknown = opts.keys - %i[protocol bytes firmware backend address adapter timeout]
+          raise ArgumentError, "Unsupported BLE options: #{unknown.join(', ')}" unless unknown.empty?
+          raise ArgumentError, 'protocol must be :unified_ble' unless opts.fetch(:protocol, :unified_ble) == :unified_ble
+
+          timeout = opts.fetch(:timeout, 120)
+          raise ArgumentError, 'timeout must be positive finite seconds' unless timeout.is_a?(Numeric) && timeout.real? && timeout.finite? && timeout.positive?
+
+          bytes = Firmware.__send__(:firmware_bytes, opts)
+          backend = opts[:backend] || BlueZ.new(address: opts[:address], adapter: opts.fetch(:adapter, 'hci0'), timeout: timeout, service_uuid: SERVICE_UUID).connect
+          Timeout.timeout(timeout) do
+            backend.subscribe(uuid: TX_UUID)
+            stream = Stream.new(backend)
+            stream.command("VERSION\n")
+            version = stream.line
+            raise IOError, "Invalid loader VERSION: #{version}" unless version.match?(/\AOK \d+ \S+ \d+ \S+\z/)
+
+            digest = Digest::SHA256.hexdigest(bytes)
+            stream.command("OTA #{bytes.bytesize} #{digest}\n")
+            reply = stream.line
+            reply = stream.line if reply == 'ERASING'
+            raise IOError, "OTA handshake rejected: #{reply}" unless reply == 'OK'
+
+            offset = 0
+            while offset < bytes.bytesize
+              chunk = bytes.byteslice(offset, 20)
+              backend.write(uuid: OTA_UUID, bytes: chunk, response: true)
+              offset += chunk.bytesize
+              reply = stream.line
+              expected = offset == bytes.bytesize ? 'OK' : 'ACK'
+              raise IOError, "OTA transfer expected #{expected}, received: #{reply}" unless reply == expected
+            end
+            { status: :verified, bytes: bytes.bytesize, sha256: digest, loader_version: version.delete_prefix('OK ') }
+          end
+        ensure
+          backend&.close
+        end
+
+        # Shared backend for unified OTA and Nordic DFU. All bus I/O stays on
+        # the caller thread: synchronous replies also dispatch queued signals.
+        # No discovery, pairing, address inference, or cross-device UUID lookup.
+        class BlueZ < Meshtastic::Bluetooth::BlueZ
+          def initialize(address:, service_uuid:, adapter: 'hci0', timeout: 15)
+            super(address: address, adapter: adapter, timeout: timeout)
+            raise ArgumentError, 'Invalid GATT service UUID' unless service_uuid.is_a?(String) && /\A[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/i.match?(service_uuid)
+
+            @service_uuid = service_uuid
+            @notifications = []
+          end
+
+          def connect_locked
+            @bus = DBus::ASystemBus.allocate
+            bounded { @bus.__send__(:initialize) }
+            objects = managed_objects
+            check_adapter(objects)
+            @device_path = objects.find do |_path, interfaces|
+              device = interfaces['org.bluez.Device1']
+              device && device['Address']&.casecmp?(@address) && device['Adapter'] == "/org/bluez/#{@adapter}"
+            end&.first
+            raise IOError, 'Selected bootloader address not known to BlueZ; discover it explicitly first' unless @device_path
+
+            @disconnect_needed = true
+            call(@device_path, 'org.bluez.Device1', 'Connect')
+            deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
+            until properties(@device_path, 'org.bluez.Device1')['ServicesResolved']
+              raise IOError, 'Bootloader ServicesResolved timed out' if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+              sleep 0.05
+            end
+            self
+          rescue StandardError
+            close_locked
+            raise
+          end
+
+          def characteristic(uuid)
+            objects = managed_objects
+            services = objects.filter_map do |path, interfaces|
+              props = interfaces['org.bluez.GattService1']
+              path if props && props['Device'] == @device_path && props['UUID']&.casecmp?(@service_uuid)
+            end
+            matches = objects.filter_map do |path, interfaces|
+              props = interfaces['org.bluez.GattCharacteristic1']
+              path if props && services.include?(props['Service']) && props['UUID']&.casecmp?(uuid)
+            end
+            raise IOError, "Expected exactly one GATT characteristic #{uuid} on selected device" unless matches.size == 1
+
+            matches.first
+          end
+
+          def connected!
+            raise IOError, 'Bootloader disconnected' unless @bus && properties(@device_path, 'org.bluez.Device1')['Connected']
+          end
+
+          def write(uuid:, bytes:, response: true)
+            @mutex.synchronize do
+              connected!
+              path = characteristic(uuid)
+              call(path, 'org.bluez.GattCharacteristic1', 'WriteValue', ['ay', bytes.bytes], ['a{sv}', { 'type' => ['s', response ? 'request' : 'command'] }])
+              bytes.bytesize
+            end
+          end
+
+          def subscribe(uuid:)
+            @mutex.synchronize do
+              connected!
+              path = characteristic(uuid)
+              rule = "type='signal',sender='org.bluez',interface='org.freedesktop.DBus.Properties',member='PropertiesChanged',path='#{path}'"
+              bounded do
+                @bus.add_match(rule) do |message|
+                  interface, changed = message.params
+                  next unless message.path == path && interface == 'org.bluez.GattCharacteristic1' && changed.key?('Value')
+
+                  @notifications << { uuid: uuid, bytes: changed.fetch('Value').pack('C*') }
+                end
+              end
+              call(path, 'org.bluez.GattCharacteristic1', 'StartNotify')
+            end
+          end
+
+          def notification(timeout:)
+            @mutex.synchronize do
+              Timeout.timeout(timeout) do
+                loop do
+                  return @notifications.shift unless @notifications.empty?
+
+                  raise IOError, 'Bootloader bus closed' unless @bus
+
+                  message = @bus.message_queue.pop
+                  @bus.process(message)
+                end
+              end
+            end
+          rescue Timeout::Error
+            release_bus
+            raise IOError, 'Bootloader notification timed out; transfer not retried'
+          end
+        end
+
+        class Stream
+          def initialize(backend)
+            @backend = backend
+            @buffer = +''.b
+          end
+
+          def command(bytes)
+            offset = 0
+            while offset < bytes.bytesize
+              @backend.write(uuid: OTA_UUID, bytes: bytes.byteslice(offset, 20), response: true)
+              offset += 20
+            end
+          end
+
+          def line
+            loop do
+              if (index = @buffer.index("\n"))
+                raise IOError, 'Oversized OTA response' if index > 511
+
+                return @buffer.slice!(0, index + 1).chomp
+              end
+              raise IOError, 'Oversized OTA response' if @buffer.bytesize > 512
+
+              event = @backend.notification(timeout: 120)
+              raise IOError, 'OTA disconnected before confirmation' unless event
+              raise IOError, 'Unexpected OTA notification UUID' unless event[:uuid].to_s.casecmp?(TX_UUID)
+
+              raise IOError, 'Invalid OTA notification bytes' unless event[:bytes].is_a?(String) && !event[:bytes].empty?
+
+              @buffer << event.fetch(:bytes)
+            end
+          end
+        end
+
+        public_class_method def self.authors
+          Firmware.authors
+        end
+
+        public_class_method def self.help
+          puts "USAGE:
+            # Upload using the unified ESP32 BLE protocol.
+            #{self}.install(
+              backend: 'optional - connected GATT backend; default selected-device BlueZ',
+              address: 'optional - required bootloader BLE MAC address when backend is omitted',
+              adapter: 'optional - selected BlueZ adapter, default hci0',
+              bytes: 'optional - application image bytes, exclusive with firmware',
+              firmware: 'optional - application image path, exclusive with bytes',
+              timeout: 'optional - whole transfer deadline seconds, default 120'
+            )
+            # Print the authors of this module.
+            #{self}.authors
+          "
+        end
+      end
+    end
+  end
+end

data/lib/meshtastic/admin/firmware/nordic_dfu.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'zlib'
+require 'digest'
+require 'timeout'
+
+module Meshtastic
+  module Admin
+    module Firmware
+      # Adafruit SDK11 legacy BLE DFU, not Nordic Secure DFU.
+      module NordicDFU
+        CONTROL_UUID = '00001531-1212-efde-1523-785feabcd123'
+        PACKET_UUID = '00001532-1212-efde-1523-785feabcd123'
+        MAX_PACKAGE = 8 * 1024 * 1024
+
+        public_class_method def self.install(opts = {})
+          unknown = opts.keys - %i[package package_bytes gatt address adapter timeout protocol]
+          raise ArgumentError, "Unsupported Nordic DFU options: #{unknown.join(', ')}" unless unknown.empty?
+          raise ArgumentError, 'protocol must be :nordic_dfu' unless opts.fetch(:protocol, :nordic_dfu) == :nordic_dfu
+          raise ArgumentError, 'Supply exactly one of package or package_bytes' unless opts.key?(:package) ^ opts.key?(:package_bytes)
+
+          image, init = package(opts.merge({}))
+          timeout = opts.fetch(:timeout, 30)
+          raise ArgumentError, 'timeout must be finite and positive' unless timeout.is_a?(Numeric) && timeout.positive? && timeout.finite?
+
+          gatt = opts[:gatt]
+          unless gatt
+            require_relative 'ble'
+            gatt = BLE::BlueZ.new(address: opts.fetch(:address), adapter: opts.fetch(:adapter, 'hci0'),
+                                  timeout: timeout, service_uuid: '00001530-1212-efde-1523-785feabcd123').connect
+          end
+          session = { gatt: gatt, timeout: timeout }
+          gatt.subscribe(uuid: CONTROL_UUID)
+          control(session.merge(bytes: [1, 4].pack('C*')))
+          packet(session.merge(bytes: [0, 0, image.bytesize].pack('V3')))
+          response(session.merge(opcode: 1))
+          control(session.merge(bytes: [2, 0].pack('C*')))
+          init.bytes.each_slice(20) { |chunk| packet(session.merge(bytes: chunk.pack('C*'))) }
+          control(session.merge(bytes: [2, 1].pack('C*')))
+          response(session.merge(opcode: 2))
+          # PRN=1 bounds outstanding data and catches loss before any next chunk.
+          control(session.merge(bytes: [8, 1].pack('Cv')))
+          control(session.merge(bytes: [3].pack('C')))
+          offset = 0
+          image.bytes.each_slice(20) do |chunk|
+            packet(session.merge(bytes: chunk.pack('C*')))
+            offset += chunk.length
+            if offset == image.bytesize
+              response(session.merge(opcode: 3))
+            else
+              receipt = notification(session)
+              raise IOError, 'DFU packet receipt offset mismatch' unless receipt == [17, offset].pack('CV')
+            end
+          end
+          control(session.merge(bytes: [4].pack('C')))
+          response(session.merge(opcode: 4))
+          control(session.merge(bytes: [5].pack('C')))
+          { status: :verified, protocol: :nordic_dfu, bytes: image.bytesize,
+            sha256: Digest::SHA256.hexdigest(image), reboot_verified: false }
+        ensure
+          gatt&.close
+        end
+
+        private_class_method def self.control(opts = {})
+          opts.fetch(:gatt).write(uuid: CONTROL_UUID, bytes: opts.fetch(:bytes), response: true)
+        end
+
+        private_class_method def self.packet(opts = {})
+          opts.fetch(:gatt).write(uuid: PACKET_UUID, bytes: opts.fetch(:bytes), response: false)
+        end
+
+        private_class_method def self.notification(opts = {})
+          event = opts.fetch(:gatt).notification(timeout: opts.fetch(:timeout))
+          raise Timeout::Error, 'DFU notification timeout; session cannot safely resume' unless event
+          raise IOError, 'Invalid DFU notification envelope' unless event.is_a?(Hash) && event[:uuid].to_s.downcase == CONTROL_UUID && event[:bytes].is_a?(String)
+
+          event[:bytes].b
+        end
+
+        private_class_method def self.response(opts = {})
+          bytes = notification(opts.merge({}))
+          expected = [16, opts.fetch(:opcode), 1].pack('C*')
+          raise IOError, "DFU response rejected or out of order: #{bytes.unpack1('H*')}" unless bytes == expected
+        end
+
+        private_class_method def self.package(opts = {})
+          raw = opts[:package_bytes] || File.binread(opts.fetch(:package), MAX_PACKAGE + 1)
+          raise ArgumentError, 'DFU ZIP must be a bounded binary String' unless raw.is_a?(String) && raw.bytesize <= MAX_PACKAGE
+
+          entries = archive(bytes: raw.b)
+          root = JSON.parse(entries.fetch('manifest.json'))
+          raise ArgumentError, 'Invalid manifest JSON object' unless root.is_a?(Hash)
+
+          manifest = root.fetch('manifest')
+          raise ArgumentError, 'Only application-only legacy Adafruit DFU packages are supported' unless manifest.is_a?(Hash) && manifest.compact.keys == ['application']
+
+          app = manifest.fetch('application')
+          raise ArgumentError, 'Invalid application manifest entry' unless app.is_a?(Hash)
+
+          image = entries.fetch(app.fetch('bin_file'))
+          init = entries.fetch(app.fetch('dat_file'))
+          raise ArgumentError, 'DFU image must be nonempty and word aligned' if image.empty? || image.bytesize % 4 != 0
+          raise ArgumentError, 'Invalid legacy Adafruit init packet' if init.bytesize < 12 || init.unpack1('v') != 0x52
+
+          count = init.byteslice(8, 2).unpack1('v')
+          raise ArgumentError, 'Unsupported init variant: expected legacy CRC16, not Secure DFU or signed extension' unless count.positive? && init.bytesize == 12 + (2 * count)
+          raise ArgumentError, 'DFU image CRC16 mismatch' unless crc16(bytes: image) == init.byteslice(-2, 2).unpack1('v')
+
+          [image, init]
+        rescue KeyError, JSON::ParserError, TypeError => e
+          raise ArgumentError, "Invalid DFU package: #{e.message}"
+        end
+
+        private_class_method def self.crc16(opts = {})
+          crc = 0xffff
+          opts.fetch(:bytes).each_byte do |byte|
+            crc = ((crc >> 8) | (crc << 8)) & 0xffff
+            crc ^= byte
+            crc ^= (crc & 0xff) >> 4
+            crc ^= (crc << 12) & 0xffff
+            crc ^= ((crc & 0xff) << 5) & 0xffff
+          end
+          crc
+        end
+
+        # Read ZIP entries in memory, never extract paths or invoke a CLI.
+        private_class_method def self.archive(opts = {})
+          raw = opts.fetch(:bytes)
+          eocd = raw.rindex("PK\x05\x06".b)
+          raise ArgumentError, 'Invalid ZIP end record' unless eocd && raw.bytesize >= eocd + 22
+
+          disk, cd_disk, disk_count, count, cd_size, cd_offset, comment = raw.byteslice(eocd + 4, 18).unpack('vvvvVVv')
+          unless disk.zero? && cd_disk.zero? && count == disk_count && count.between?(1, 32) &&
+                 cd_offset + cd_size == eocd && eocd + 22 + comment == raw.bytesize
+            raise ArgumentError, 'Unsupported ZIP layout (split, ZIP64, or invalid directory)'
+          end
+
+          entries = {}
+          cursor = cd_offset
+          count.times do
+            header = raw.byteslice(cursor, 46)
+            raise ArgumentError, 'Invalid ZIP directory entry' unless header&.bytesize == 46 && header.unpack1('V') == 0x02014b50
+
+            fields = header.unpack('VvvvvvvVVVvvvvvVV')
+            flags, method, crc, packed, size = fields.values_at(3, 4, 7, 8, 9)
+            name_size, extra_size, comment_size, entry_disk, offset = fields.values_at(10, 11, 12, 13, 16)
+            name = raw.byteslice(cursor + 46, name_size)
+            unless flags.nobits?(~0x800) && [0, 8].include?(method) && entry_disk.zero? && size <= MAX_PACKAGE && packed <= MAX_PACKAGE &&
+                   name && name.match?(%r{\A[\w./-]+\z}) && !name.split('/').include?('..') && !name.start_with?('/') && !entries.key?(name)
+              raise ArgumentError, 'Unsupported or unsafe ZIP entry'
+            end
+
+            local = raw.byteslice(offset, 30)
+            raise ArgumentError, 'Invalid ZIP local header' unless local&.bytesize == 30 && local.unpack1('V') == 0x04034b50
+
+            lfields = local.unpack('VvvvvvVVVvv')
+            lname_size, lextra_size = lfields.values_at(9, 10)
+            start = offset + 30 + lname_size + lextra_size
+            unless lfields.values_at(2, 3, 6, 7, 8) == [flags, method, crc, packed, size] &&
+                   raw.byteslice(offset + 30, lname_size) == name && start + packed <= cd_offset
+              raise ArgumentError, 'Inconsistent ZIP local entry'
+            end
+
+            bytes = raw.byteslice(start, packed)
+            bytes = inflate(bytes: bytes, size: size) if method == 8
+            raise ArgumentError, 'ZIP entry size or CRC32 mismatch' unless bytes && bytes.bytesize == size && Zlib.crc32(bytes) == crc
+
+            entries[name] = bytes
+            cursor += 46 + name_size + extra_size + comment_size
+          end
+          raise ArgumentError, 'Invalid ZIP directory length' unless cursor == eocd
+
+          entries
+        end
+
+        private_class_method def self.inflate(opts = {})
+          inflater = Zlib::Inflate.new(-Zlib::MAX_WBITS)
+          output = ''.b
+          inflater.inflate(opts.fetch(:bytes)) do |chunk|
+            raise ArgumentError, 'ZIP decompression exceeds declared size' if output.bytesize + chunk.bytesize > opts.fetch(:size)
+
+            output << chunk
+          end
+          raise ArgumentError, 'Invalid ZIP deflate stream' unless inflater.finished? && inflater.total_in == opts.fetch(:bytes).bytesize
+
+          output
+        rescue Zlib::Error => e
+          raise ArgumentError, "Invalid ZIP deflate stream: #{e.message}"
+        ensure
+          inflater&.close
+        end
+
+        public_class_method def self.authors
+          ['Meshtastic Ruby contributors']
+        end
+
+        public_class_method def self.help
+          puts <<~HELP
+            Install application via Adafruit legacy BLE DFU.
+            #{self}.install(
+              protocol: 'optional - protocol selector, must be nordic_dfu',
+              package: 'optional - DFU ZIP filename; required unless package_bytes is supplied',
+              package_bytes: 'optional - raw DFU ZIP bytes instead of filename',
+              gatt: 'optional - connected adapter implementing write/subscribe/notification/close',
+              address: 'optional - bootloader BLE address; required without gatt',
+              adapter: 'optional - BlueZ adapter name, default hci0',
+              timeout: 'optional - positive notification timeout seconds, default 30'
+            )
+
+            List module contributing authors.
+            #{self}.authors
+          HELP
+        end
+      end
+    end
+  end
+end