meshtastic 0.0.187 → 0.0.188

data/documentation/mqtt.md

@@ -1,101 +1,93 @@
 # Meshtastic::MQTT
 
-Broker client. The host encrypts and decrypts with channel PSKs. Default public broker is `mqtt.meshtastic.org` (port 1883, user `meshdev`).
+Broker client using protobuf `ServiceEnvelope`. The host performs channel PSK encryption/decryption; MQTT does **not** provide public-key direct messaging. A broker publish is submission, not RF delivery or a verified ACK.
 
-`channel:` on MQTT is the integer hash seen in envelopes, not the radio channel index (that is Serial/Bluetooth/TCP).
-
-## Methods
-
-- `connect` — returns an `MQTT::Client`
-- `subscribe` — blocking loop; yields a hash per envelope, or pretty-prints without a block. Disconnects on exit.
-- `send_text` — publishes a `ServiceEnvelope` (raises if text exceeds `Meshtastic::Constants::DATA_PAYLOAD_LEN`)
-- `disconnect`
-- `help` / `authors`
-
-### `connect`
+## Connect and subscribe
 
 ```ruby
+require 'meshtastic'
+
 mqtt_obj = Meshtastic::MQTT.connect(
-  host: 'mqtt.meshtastic.org',
-  port: 1883,
-  tls: false,
-  username: 'meshdev',
-  password: 'large4cats',
-  client_id: nil,          # default: random 4-byte hex
-  keep_alive: 15,
-  ack_timeout: 30
+  host: 'mqtt.meshtastic.org', port: 1883, tls: false,
+  username: 'meshdev', password: 'large4cats',
+  client_id: 'aabbccdd', keep_alive: 15, ack_timeout: 30
 )
-```
 
-### `subscribe`
+# Use your own Base64 16- or 32-byte channel key, not this public alias.
+keys = {
+  LongFast: 'AQ==',                         # backward-compatible AES-CTR
+  Private: { psk: 'AQ==', use_aead: true }  # firmware AES-CCM, public example key
+}
 
-```ruby
 Meshtastic::MQTT.subscribe(
-  mqtt_obj: mqtt_obj,
-  root_topic: 'msh',
-  region: 'US',
-  topic: '2/e/LongFast/#',
-  psks: { LongFast: 'AQ==' },
-  qos: 0,
-  exclude: nil,            # comma-delimited substrings to hide
-  include: nil,            # all listed substrings must appear
-  gps_metadata: false,
-  include_raw: false
-) do |message|
-  puts message.inspect
+  mqtt_obj: mqtt_obj, root_topic: 'msh', region: 'US',
+  topic: '2/e/Private/#', psks: keys, qos: 0,
+  include: nil, exclude: nil, gps_metadata: false, include_raw: false
+) do |envelope|
+  puts envelope[:packet].inspect
 end
 ```
 
-`include: '_APP, LongFast'` keeps only messages whose flattened inspect contains both strings.
+`subscribe` is blocking and disconnects on exit. `include`/`exclude` are comma-delimited substrings. `json: true` accepts JSON envelopes but does not make their security claims trustworthy. Binary protobuf is the normal interoperable path.
 
-### `send_text`
+The exact `ServiceEnvelope.channel_id` selects the key. If absent, the penultimate MQTT topic segment is used. Unknown names never fall back to LongFast or the first key. Encrypted packets must have the firmware hash matching the configured name, expanded key and mode. Already-decoded envelopes bypass host decryption and are not authenticated by it.
 
-```ruby
-require 'meshtastic'
+## Send text or application Data
 
-mqtt_obj = Meshtastic::MQTT.connect
-client_id = "!#{mqtt_obj.client_id}"
+```ruby
 Meshtastic::MQTT.send_text(
-  mqtt_obj: mqtt_obj,
-  from: client_id,
-  to: '!ffffffff',
-  root_topic: 'msh',
-  region: 'US',
-  topic: '2/e/LongFast/#',
-  channel: 93,
-  text: 'Hello, World!',
-  psks: { LongFast: 'AQ==' }
+  mqtt_obj: mqtt_obj, from: '!aabbccdd', to: '!ffffffff',
+  channel_id: 'Private', psks: keys,
+  text: 'Hello', want_ack: false, hop_limit: 3
+)
+
+Meshtastic::MQTT.send_data(
+  mqtt_obj: mqtt_obj, from: '!aabbccdd',
+  channel_id: 'Private', psks: keys,
+  data: Meshtastic::Data.new(portnum: :TEXT_MESSAGE_APP, payload: 'Hello')
 )
 ```
 
-Default `channel` is `6`. The value that actually works is the integer in a received envelope for that mesh channel. Subscribe with `include: '!YOUR_CLIENT_ID'` while sending a test message from the official app:
+- `channel_id:` selects the exact channel name. It may be omitted only for a single configured key; omitted `psks` retains the public LongFast CTR default. Multiple keys without a selector, duplicate string/symbol names, unknown selectors, and conflicting publication topics raise `ArgumentError` before publish.
+- `psks:` maps names to Base64 strings (legacy CTR), or `{ psk: base64_string, use_aead: true/false }`. `use_aead` belongs **inside each key record**, not at the top level. Structured records require exactly `psk` and a boolean `use_aead`; omitted/misspelled modes and top-level `use_aead` are rejected rather than silently selecting CTR. No mode probing or AEAD-to-CTR retry occurs.
+- Keys must decode to 16 or 32 bytes, or a nonzero one-byte firmware PSK alias. Aliases 1–255 expand using the firmware default key and last-byte adjustment on **any** channel name. Empty/zero aliases, malformed keys and other lengths are rejected; unlike firmware, arbitrary short keys are not silently zero-padded. Resolve secondary-channel inherited keys before supplying them here. Public aliases do not provide confidentiality.
+- The packet channel hash is computed, not guessed: XOR all UTF-8 channel-name bytes and expanded key bytes, then XOR `0xAE` for AEAD. Legacy numeric `channel:` remains accepted but does not override this computed MQTT hash. On radio transports, `channel:` is still a device slot.
+- The default publish path is `msh/US/2/e/<selected channel>/<from>`. Supply `root_topic`, `region`, or `topic: '2/e/Private/#'` to customize. A topic must identify the selected channel.
+- `send_text` and text `send_data` reject nonbroadcast destinations, even without `pki_encrypted`. Explicit `pki_encrypted: true` or recipient `public_key:` also raise. Use Serial/Bluetooth/TCP with device-owned PKI for direct messages. Non-text channel-addressed application Data remains supported, but is not PKI.
+- `psks: nil` and `{}` cannot publish plaintext. `send_text` enforces the payload byte limit. Large encoded Data plus AEAD overhead still must fit the receiving firmware's RF limits; publish success does not prove airtime acceptance.
+- Do not reuse a packet ID with the same sender/key. Normal sends generate IDs; `last_packet_id:` exists for controlled sequencing/testing, not replay protection. The host does not maintain a durable nonce/replay database.
+
+`disconnect(mqtt_obj:)`, `help`, and `authors` are also available.
+
+## Security provenance
+
+Every enriched packet has host-created `:security_provenance`:
 
 ```ruby
-mqtt_obj = Meshtastic::MQTT.connect
-Meshtastic::MQTT.subscribe(
-  mqtt_obj: mqtt_obj,
-  root_topic: 'msh',
-  region: 'US',
-  topic: '2/e/LongFast/#',
-  psks: { LongFast: 'AQ==' },
-  include: '!c0ffee00'
-) do |message|
-  puts message.inspect
-end
+{
+  source: :mqtt,
+  verification: :untrusted,
+  reported: { xeddsa_signed: true, ack_proof_status: :ACK_PROOF_VALID },
+  channel_authentication: :aead # only after a successful local CCM check
+}
 ```
 
-Example envelope (placeholders):
+Broker `xeddsa_signed` and `ack_proof_status` are removed from the top-level packet hash and retained only under `reported`. They are untrusted broker assertions, including on already-decoded packets, encrypted packets and failed-enrichment paths. A broker-supplied `security_provenance` is overwritten. `include_raw` is wire evidence, not a trusted verification result.
 
-```
-{packet: {from: 3237997296, to: 4294967295, channel: 93, id: 1, rx_time: 1735689600, rx_snr: 0.0, hop_limit: 3, want_ack: false, priority: :HIGH, rx_rssi: 0, delayed: :NO_DELAY, via_mqtt: false, hop_start: 3, public_key: "", pki_encrypted: false, next_hop: 0, relay_node: 0, tx_after: 0, decoded: {portnum: :TEXT_MESSAGE_APP, payload: "WHAT IS MY channel VALUE?", want_response: false, dest: 0, source: 0, request_id: 0, reply_id: 0, emoji: 0, bitfield: 0}, encrypted: :decrypted, topic: "msh/US/2/e/LongFast/!c0ffee00", node_id_from: "!c0ffee00", node_id_to: "!ffffffff", rx_time_utc: "2025-01-01 00:00:00 UTC"}, channel_id: "LongFast", gateway_id: "!c0ffee00"}
-```
+Successful CCM proves possession of the shared channel key, **not** sender identity, XEdDSA signature validity, ACK proof validity, freshness or radio delivery. CTR decoding sets `channel_authentication: :none`; protobuf parsing is not authentication. Failures preserve ciphertext and add `decryption_error` without publishing partial plaintext. PKI ciphertext is never attempted with PSK crypto.
+
+## Pinned firmware interoperability
+
+Implemented against release **v2.8.1.8e6a88d**:
+
+- Firmware [`8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c`](https://github.com/meshtastic/firmware/tree/8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c): `src/mesh/Channels.cpp`, `CryptoEngine.cpp/.h`, `aes-ccm.cpp`, and `test/test_crypto/test_main.cpp`.
+- Protobuf [`8f97d66a63ce10cfb12f94203e361691647f5ad3`](https://github.com/meshtastic/protobufs/tree/8f97d66a63ce10cfb12f94203e361691647f5ad3): existing `ChannelSettings.use_aead`, `MeshPacket.xeddsa_signed` and `ack_proof_status` schemas.
 
-Use `channel: 93` from that dump when publishing.
+CTR uses AES-128/256 with the 16-byte nonce `packet_id64le || from32le || zero32`. Channel AEAD uses AES-128/256-CCM, **13-byte nonce** `packet_id64le || from32le || 00`, **12-byte tag**, and AAD `from32le || to32le`. Wire bytes are `ciphertext || tag`; there is no PKI extra nonce. Relayed hop fields are not AAD. Packet IDs in MeshPacket are 32-bit and occupy the low four bytes of the 64-bit nonce field.
 
-`AQ==` is expanded to the well-known LongFast PSK. Pass a Base64 channel key for private channels.
+Ruby OpenSSL must provide AES-CCM, `iv_len=`, `auth_tag_len=`, `ccm_data_len=`, and authenticated decrypt. Unsupported crypto fails, never downgrades. No new gem/native extension dependency was added. Tests use fixed independently calculated CCM vectors, upstream RFC3610 validation, real ServiceEnvelope/FromRadio codecs, fake broker/GATT, PTY UART and UNIXSocket TCP; no hardware or live broker was used.
 
 ## Related
 
-- [Meshtastic::MeshInterface](mesh-interface.md) (`via: :mqtt`)
-- [Meshtastic::Portnums](portnums.md)
-- Protobuf: `ServiceEnvelope`, `MapReport` in [protobufs.md](protobufs.md)
+- [MeshInterface](mesh-interface.md)
+- [Protobuf catalog](protobufs.md)

data/documentation/waypoint.md

@@ -0,0 +1,54 @@
+# Meshtastic::Waypoint
+
+`Waypoint` remains the generated protobuf **class**. `build(fields:)` and `transmit` add validated waypoint/geofence helpers without replacing its constructor, descriptor, encoder, or decoder. All methods accept one options Hash; `help` and `authors` expose usage and attribution.
+
+## Circle and box examples
+
+```ruby
+circle = Meshtastic::Waypoint.build(fields: {
+  id: 7, name: 'Meeting point',
+  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
+})
+
+box = Meshtastic::Waypoint.build(fields: {
+  id: 8, name: 'Search area',
+  bounding_box: {
+    longitude_west_i: -731_000_000, latitude_south_i: 449_000_000,
+    longitude_east_i: -729_000_000, latitude_north_i: 451_000_000
+  },
+  notify_on_enter: true
+})
+
+Meshtastic::Waypoint.transmit(serial_obj: connection, waypoint: circle, want_ack: true)
+# Alternative: pass fields: directly, not both waypoint and fields.
+```
+
+Coordinates are **integer decimal degrees × 10,000,000**, not radians, floating-point degrees, or map pixels. Latitude must be within ±900,000,000 and longitude within ±1,800,000,000. Supply waypoint latitude and longitude together, including explicit zero for equator/prime-meridian locations. A positive radius requires that center. `geofence_radius` is uint32 meters; zero means no circular fence.
+
+`bounding_box` uses exactly `longitude_west_i`, `latitude_south_i`, `longitude_east_i`, `latitude_north_i` (west/south/east/north), with south ≤ north and west ≤ east. Antimeridian-spanning boxes must be split; they are not silently reordered. An explicitly empty box is valid proto3 and denotes all-zero bounds. Circle and box may coexist, as allowed by the pinned schema.
+
+Notification flags are booleans: `notify_on_enter`, `notify_on_exit`, `notify_favorites_only`. Favorite status is resolved **locally on each receiving device**. These are firmware/client notification instructions, not a host tracking service or a guarantee that every device will alert.
+
+## Other fields and validation
+
+Only exact generated `Waypoint` fields are accepted under `fields:`. In addition to the geometry/notification fields, these are `id`, `expire` (Unix seconds), `locked_to` (editing node number, zero for unrestricted), `name`, `description`, and `icon` (Unicode designator integer). There is no invented `shape`, `radius`, `receive_only`, or `geofence` wire field. The helper rejects unknown fields, invalid types, out-of-range numbers, nil values, geographic bounds violations, incomplete centers, and reversed boxes before transmission.
+
+Pinned nanopb storage allows **29 UTF-8 bytes for name and 99 for description**, leaving the terminating byte inside the schema's 30/100-byte storage buffers. Overlength text, embedded NUL, and invalid UTF-8 are rejected, never truncated. `build` without fields and a decoded empty proto3 message are valid default waypoints; absence of payload bytes does not mean a malformed known protobuf payload.
+
+## Transmission and limits
+
+`transmit(waypoint:)` revalidates even an object made directly with `Waypoint.new`, then submits `Data(portnum: :WAYPOINT_APP)` through `Meshtastic.deliver_data`. Use the existing non-Admin transport keywords: `serial_obj`, `bluetooth_obj`, `tcp_obj`, or `mqtt_obj`. Shared transport options such as destination, channel, hop limit, packet ID, `want_ack`, `pki_encrypted`, and `public_key` pass through unchanged. For MQTT use `channel_id` and `psks` per the [MQTT](mqtt.md) documentation; MQTT PKI remains unsupported. Do not supply multiple transport handles.
+
+Submission is not an RF receipt or notification confirmation. Signing reports, ACK proofs, and broker claims are different evidence; see [Admin delivery results](admin.md#delivery-evidence-and-trust-boundary-v2818e6a88d). Geofence handling and UI notifications depend on the receiver's firmware/build. No live radio verification was performed.
+
+## Pinned contract
+
+Firmware **v2.8.1.8e6a88d**, commit `8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c`, pins protobuf commit `8f97d66a63ce10cfb12f94203e361691647f5ad3`:
+
+- [Waypoint and BoundingBox schema](https://github.com/meshtastic/protobufs/blob/8f97d66a63ce10cfb12f94203e361691647f5ad3/meshtastic/mesh.proto)
+- [Firmware string capacities](https://github.com/meshtastic/protobufs/blob/8f97d66a63ce10cfb12f94203e361691647f5ad3/meshtastic/mesh.options)
+
+Related: [Position](position.md), [Admin::Config](admin-config.md).

data/lib/meshtastic/admin/backup.rb

@@ -13,7 +13,7 @@ module Meshtastic
     # Host-side snapshots, not firmware filesystem backup commands.
     module Backup
       FORMAT = 'meshtastic-admin-backup'
-      WARNING = 'Contains secrets returned by firmware. Firmware may redact secrets; absent/default values are not proof of completeness. Owner identity and hardware metadata are excluded. ACKs do not prove persistence.'
+      WARNING = 'Contains secrets returned by firmware. Firmware may redact secrets; absent/default values are not proof of completeness. Owner id, MAC and hardware metadata are excluded, NOT security private/public identity keys. ACKs do not prove persistence.'
       CONFIG_TYPES = %i[DEVICE_CONFIG POSITION_CONFIG POWER_CONFIG NETWORK_CONFIG DISPLAY_CONFIG LORA_CONFIG BLUETOOTH_CONFIG SECURITY_CONFIG].freeze
       MODULE_TYPES = %i[MQTT_CONFIG SERIAL_CONFIG EXTNOTIF_CONFIG STOREFORWARD_CONFIG RANGETEST_CONFIG TELEMETRY_CONFIG CANNEDMSG_CONFIG AUDIO_CONFIG REMOTEHARDWARE_CONFIG NEIGHBORINFO_CONFIG AMBIENTLIGHTING_CONFIG DETECTIONSENSOR_CONFIG PAXCOUNTER_CONFIG STATUSMESSAGE_CONFIG TRAFFICMANAGEMENT_CONFIG TAK_CONFIG MESHBEACON_CONFIG].freeze
       OWNER_FIELDS = %w[long_name short_name is_licensed].freeze
@@ -127,6 +127,20 @@ module Meshtastic
           end
         end
         entries = import_plan(document: document, format: opts.fetch(:format, :auto), path: opts[:path])
+        identity = entries.any? do |entry|
+          security = entry[:message].security if entry[:section] == 'config'
+          security && (!security.private_key.empty? || !security.public_key.empty?)
+        end
+        raise ArgumentError, 'backup contains security identity keys; explicitly select identity_keys: :restore or remove the entire security record offline' if identity && opts.fetch(:identity_keys, :reject) != :restore
+
+        reconnect = identity || entries.any? { |entry| entry[:section] == 'owner' || (entry[:section] == 'config' && %w[LORA_CONFIG SECURITY_CONFIG NETWORK_CONFIG BLUETOOTH_CONFIG].include?(entry[:slot])) }
+        privacy = entries.any? { |entry| privacy_sensitive?(entry) }
+        raise ArgumentError, 'backup changes location, sharing or telemetry settings; explicitly select allow_privacy_changes: true' if privacy && !opts.fetch(:allow_privacy_changes, false)
+
+        warnings = [WARNING]
+        warnings << 'Privacy: restored location, channel precision, MQTT sharing or enabled telemetry may disclose location, traffic or device, environment, air quality, power and health metrics. Firmware may clamp public-channel precision; values are never silently stripped by this client.' if privacy
+        warnings << 'Identity or connection settings may change the node number or connection. Reconnect, rediscover the target, and compare fresh configuration before claiming persistence; this API does not reconnect or retarget automatically.' if reconnect
+        warnings << 'Security public keys may be derived from private keys by firmware; absent private keys preserve an existing identity, not a request to reset it.' if entries.any? { |entry| entry[:section] == 'config' && entry[:slot] == 'SECURITY_CONFIG' }
         plan = entries.each_with_index.sort_by do |entry, index|
           priority = if entry[:section] == 'config'
                        { 'LORA_CONFIG' => 20, 'BLUETOOTH_CONFIG' => 21, 'NETWORK_CONFIG' => 22, 'SECURITY_CONFIG' => 23 }.fetch(entry[:slot], 0)
@@ -136,7 +150,7 @@ module Meshtastic
           [priority, index]
         end.map(&:first)
         report = { status: :dry_run, planned: plan.length, attempted: 0, acknowledged: 0, readback_confirmed: 0, persistence_verified: false,
-                   transaction: :not_requested, records: [], plan: plan.map { |entry| entry.slice(:section, :slot) }, warnings: [WARNING] }
+                   transaction: :not_requested, records: [], plan: plan.map { |entry| entry.slice(:section, :slot) }, warnings: warnings, reconnect_required: reconnect }
         return report if opts.fetch(:dry_run, false)
 
         failure = nil
@@ -174,6 +188,23 @@ module Meshtastic
         report
       end
 
+      private_class_method def self.privacy_sensitive?(opts = {})
+        message = opts[:message]
+        case opts[:section]
+        when 'fixed_position' then true
+        when 'config' then opts[:slot] == 'POSITION_CONFIG'
+        when 'channel'
+          settings = message.settings
+          settings && (settings.uplink_enabled || settings.module_settings&.position_precision.to_i.positive?)
+        when 'module_config'
+          return message.mqtt.enabled || message.mqtt.map_reporting_enabled if message.mqtt
+
+          telemetry = message.telemetry
+          telemetry && %w[device_telemetry_enabled environment_measurement_enabled air_quality_enabled power_measurement_enabled health_measurement_enabled].any? { |field| telemetry[field] }
+        else false
+        end
+      end
+
       # A timed-out mutation is never resent; only a fresh getter can resolve it.
       private_class_method def self.apply_entry(opts = {})
         entry = opts[:entry]
@@ -345,6 +376,7 @@ module Meshtastic
         end
         raise ArgumentError, 'DeviceProfile contains no restorable fields' if entries.empty?
 
+        entries.each { |entry| Validation.validate(message: entry[:message]) if entry[:message].respond_to?(:to_proto) }
         entries
       rescue Google::Protobuf::ParseError, TypeError, RangeError, URI::InvalidURIError
         raise ArgumentError, 'invalid DeviceProfile protobuf or channel URL', cause: nil
@@ -422,6 +454,7 @@ module Meshtastic
                   end
           validate_proto_json(value: record['value'], descriptor: klass.descriptor)
           message = klass.decode_json(JSON.generate(record['value']), ignore_unknown_fields: false)
+          Validation.validate(message: message)
           if %w[config module_config].include?(section)
             types = section == 'config' ? CONFIG_TYPES : MODULE_TYPES
             fields = klass.descriptor.map(&:name)
@@ -461,14 +494,16 @@ module Meshtastic
       private_class_method def self.validate_options(opts = {})
         options = opts[:options]
         allowed = %i[transport_obj to timeout channel hop_limit path]
-        allowed += opts[:operation] == :export ? %i[format config_types module_config_types channel_indexes include_owner include_ui] : %i[backup format dry_run edit_transaction verify]
+        allowed += opts[:operation] == :export ? %i[format config_types module_config_types channel_indexes include_owner include_ui] : %i[backup format dry_run edit_transaction verify identity_keys allow_privacy_changes]
+        raise ArgumentError, 'identity_keys must be :reject (default) or :restore' if options.key?(:identity_keys) && !%i[reject restore].include?(options[:identity_keys])
+
         allowed += %i[fixed_position include_ringtone include_canned_messages] if opts[:operation] == :export && options[:format] == :device_profile
         raise ArgumentError, 'unknown backup options' unless (options.keys - allowed).empty?
 
         formats = opts[:operation] == :export ? %i[json device_profile] : %i[auto json device_profile]
         raise ArgumentError, "format must be one of #{formats.join(', ')}" if options.key?(:format) && !formats.include?(options[:format])
 
-        %i[include_owner include_ui include_ringtone include_canned_messages dry_run edit_transaction verify].each do |key|
+        %i[include_owner include_ui include_ringtone include_canned_messages dry_run edit_transaction verify allow_privacy_changes].each do |key|
           raise ArgumentError, 'backup flags must be boolean' if options.key?(key) && ![true, false].include?(options[key])
         end
         timeout = options.fetch(:timeout, 10)
@@ -542,7 +577,9 @@ module Meshtastic
             path: 'optional - existing JSON or binary DeviceProfile .cfg file; mutually exclusive with backup',
             backup: 'optional - versioned JSON Hash, JSON String or binary DeviceProfile String; mutually exclusive with path',
             format: 'optional - :auto (default), :json or :device_profile; cfg paths select binary, other content is validated',
-            dry_run: 'optional - validate and plan without any radio requests; default false',
+            identity_keys: 'optional - :reject (default) rejects any nonempty security private/public identity key; :restore sends unchanged; never strips keys, including in dry runs',
+            allow_privacy_changes: 'optional - boolean default false; explicitly consent to position/fixed-position, positive channel precision/uplink, enabled MQTT/map reporting or telemetry (device, environment, air quality, power, health) restoration',
+            dry_run: 'optional - validate and plan without any radio requests; default false; consent flags still required',
             edit_transaction: 'optional - begin/commit on firmware known to support edits; default false',
             verify: 'optional - additional fresh comparison after completed writes/commit; timeout recovery reads occur regardless; not durability proof; default false',
             timeout: 'optional - positive finite seconds per request; default 10',
@@ -551,6 +588,8 @@ module Meshtastic
             hop_limit: 'optional - mesh transport hop limit; default Admin behavior'
           )
           # Contains secrets; firmware may redact values. Never logs document contents.
+          # Firmware v2.8.1.8e6a88d semantics; owner metadata exclusion does not exclude security identity keys.
+          # Reports reconnect_required when identity/connection settings may change. No automatic reconnect or target discovery; persistence_verified remains false.
           # Display the module authors.
           #{self}.authors
         "

data/lib/meshtastic/admin/channel.rb

@@ -25,10 +25,7 @@ module Meshtastic
           value = field.subtype.msgclass.new(value) if value.is_a?(Hash) && field.subtype
           settings[field.name] = value
         end
-        raise ArgumentError, 'PSK must contain 0, 1, 16, or 32 raw bytes' unless [0, 1, 16, 32].include?(settings.psk.bytesize)
-        raise ArgumentError, 'channel name must be fewer than 12 bytes' unless settings.name.bytesize < 12
-
-        settings
+        Validation.validate(message: settings)
       end
 
       public_class_method def self.build(opts = {})
@@ -38,10 +35,8 @@ module Meshtastic
 
         channel.index = index
         channel.role = opts[:role] if opts[:role]
-        raise ArgumentError, 'role must be PRIMARY, SECONDARY, or DISABLED' unless %i[PRIMARY SECONDARY DISABLED].include?(channel.role)
-
         channel.settings = build_settings(opts.merge(settings: opts.fetch(:settings, channel.settings)))
-        channel
+        Validation.validate(message: channel)
       end
 
       public_class_method def self.get(opts = {})
@@ -82,7 +77,7 @@ module Meshtastic
         channel_set = Meshtastic::ChannelSet.decode(Base64.urlsafe_decode64(uri.fragment))
         raise ArgumentError, 'invalid channel URL' unless (1..8).cover?(channel_set.settings.length)
 
-        channel_set
+        Validation.validate(message: channel_set)
       rescue URI::InvalidURIError, Google::Protobuf::ParseError, ArgumentError, TypeError
         raise ArgumentError, 'invalid channel URL'
       end

data/lib/meshtastic/admin/config.rb

@@ -100,6 +100,49 @@ module Meshtastic
         set(opts.merge(config: Meshtastic::Config.new(device_ui: opts.fetch(:device_ui))))
       end
 
+      public_class_method def self.set_packet_signature_policy(opts = {})
+        policy = opts.fetch(:policy)
+        enum = Meshtastic::Config::SecurityConfig::PacketSignaturePolicy
+        valid = policy.is_a?(Symbol) ? enum.resolve(policy) : (policy.is_a?(Integer) && enum.lookup(policy))
+        raise ArgumentError, 'policy must be a known PacketSignaturePolicy symbol or integer' unless valid
+
+        section = Meshtastic::Config::SecurityConfig.new(packet_signature_policy: policy)
+        Admin::Validation.validate(message: Meshtastic::AdminMessage.new(set_config: Meshtastic::Config.new(security: section)))
+        update_field(opts.except(:policy).merge(section: :security, config_type: :SECURITY_CONFIG, field: :packet_signature_policy,
+                                                value: section.packet_signature_policy))
+      end
+
+      public_class_method def self.set_receive_only(opts = {})
+        enabled = opts.fetch(:enabled)
+        raise ArgumentError, 'enabled must be true or false' unless [true, false].include?(enabled)
+        raise ArgumentError, 'receive-only requires a local radio connection' if Admin.transport_type(opts) == :mqtt
+
+        connection = opts.fetch(:transport_obj)
+        target = opts.fetch(:to, connection[:my_node_num])
+        target = target.delete_prefix('!').to_i(16) if target.is_a?(String) && target.match?(/\A![0-9a-fA-F]{8}\z/)
+        raise ArgumentError, 'receive-only requires the local node for reliable readback and recovery' unless target && target == connection[:my_node_num]
+
+        update_field(opts.except(:enabled).merge(section: :lora, config_type: :LORA_CONFIG, field: :tx_enabled, value: !enabled))
+      end
+
+      private_class_method def self.update_field(opts = {})
+        section = opts.fetch(:section)
+        field = opts.fetch(:field)
+        value = opts.fetch(:value)
+        options = opts.except(:section, :field, :value, :config_type, :wait, :request_id).merge(wait: true)
+        query = options.merge(get_config_request: opts.fetch(:config_type))
+        before = Admin.request(query).fetch(:value)
+        raise IOError, "expected #{section} configuration readback" unless before.is_a?(Meshtastic::Config) && before.payload_variant == section
+
+        intended = Meshtastic::Config.decode(before.to_proto)
+        intended.public_send(section).public_send("#{field}=", value)
+        acknowledgment = Admin.request(options.merge(set_config: intended))
+        readback = Admin.request(query)
+        actual = readback.fetch(:value)
+        matched = actual.is_a?(Meshtastic::Config) && actual.payload_variant == section && actual.public_send(section).public_send(field) == value
+        { acknowledgment: acknowledgment, readback: readback, matched: matched, reboot_requested: false }
+      end
+
       public_class_method def self.authors
         "AUTHOR(S):\n        0day Inc. <support@0dayinc.com>\n      "
       end
@@ -115,7 +158,7 @@ module Meshtastic
           # Write a Config protobuf to the node.
           #{self}.set(
             transport_obj: 'required - connected Serial, Bluetooth, TCP handle or MQTT client',
-            config: 'required - Meshtastic::Config protobuf to write'
+            config: 'required - Config protobuf with exactly one selected section; empty outer messages and unknown enum values are rejected; device_ui uses dedicated store operation'
           )
 
           # Request DEVICE_CONFIG from the node.
@@ -204,6 +247,25 @@ module Meshtastic
           # Write device UI configuration to node.
           #{self}.set_device_ui(device_ui: 'required - DeviceUIConfig protobuf or field hash')
 
+          # Change signature policy preserving other security fields with fresh readback.
+          #{self}.set_packet_signature_policy(
+            transport_obj: 'required - connected radio handle with receive queue; MQTT unsupported',
+            policy: 'required - PACKET_SIGNATURE_POLICY_COMPATIBLE, BALANCED or STRICT enum symbol with full prefix, or known integer',
+            to: 'optional - target node, defaults to connected radio; accepts shared Admin request options',
+            timeout: 'optional - per-request positive deadline seconds; default ten'
+          )
+
+          # Set local LoRa transmit enablement with fresh readback.
+          #{self}.set_receive_only(
+            transport_obj: 'required - local connected radio with receive queue; remote targets and MQTT rejected',
+            enabled: 'required - true disables LoRa transmission, false enables it; preserves other LoRa fields',
+            to: 'optional - must equal the connected local node number',
+            timeout: 'optional - per-request positive deadline seconds; default ten'
+          )
+          # Helpers return acknowledgment, readback, matched and reboot_requested false.
+          # They do not request reboot; firmware may itself reboot/disconnect after settings changes.
+          # Timeout propagates without replay; reconnect and read back before retrying mutations.
+
           # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "

data/lib/meshtastic/admin/firmware.rb

@@ -125,8 +125,11 @@ module Meshtastic
       public_class_method def self.verify_reboot(opts = {})
         validate_verification(opts.merge({}))
         handle = nil
-        transport = { tcp: Meshtastic::TCP, bluetooth: Meshtastic::Bluetooth, serial: Meshtastic::Serial }.fetch(opts.fetch(:transport))
-        key = { tcp: :tcp_obj, bluetooth: :bluetooth_obj, serial: :serial_obj }.fetch(opts.fetch(:transport))
+        handle_type = nil
+        transports = { tcp: Meshtastic::TCP, bluetooth: Meshtastic::Bluetooth, serial: Meshtastic::Serial }
+        keys = { tcp: :tcp_obj, bluetooth: :bluetooth_obj, serial: :serial_obj }
+        transport = transports.fetch(opts.fetch(:transport))
+        key = keys.fetch(opts.fetch(:transport))
         Timeout.timeout(opts.fetch(:timeout, 60)) do
           sleep opts.fetch(:reboot_delay, 3)
           begin
@@ -135,6 +138,9 @@ module Meshtastic
                      else
                        transport.connect(opts.fetch(:connection).merge(want_config: true))
                      end
+            handle_type = Admin.transport_type(transport_obj: handle)
+            raise ArgumentError, 'Reconnect transport does not match selected transport' unless handle_type == opts.fetch(:transport)
+
             transport.wait_for_config(key => handle, timeout: opts.fetch(:timeout, 60))
           rescue IOError, SystemCallError
             transport.disconnect(key => handle) if handle
@@ -142,25 +148,50 @@ module Meshtastic
             sleep 0.25
             retry
           end
-          reply = Admin.request(transport_obj: handle, get_device_metadata_request: true, timeout: opts.fetch(:timeout, 60))
+          node = handle[:my_node_num]
+          identity = verify_identity(opts.merge(handle: handle, node: node))
+          reply = Admin.request(transport_obj: handle, to: node, get_device_metadata_request: true, timeout: opts.fetch(:timeout, 60))
           metadata = reply.fetch(:value).to_h
-          raise IOError, "Firmware version mismatch: #{metadata[:firmware_version].inspect}" unless metadata[:firmware_version] == opts.fetch(:expected_version)
-          raise IOError, 'Post-reboot node identity mismatch' if opts[:expected_node] && handle[:my_node_num] != opts[:expected_node]
+          raise IOError, 'Firmware version mismatch' unless metadata[:firmware_version] == opts.fetch(:expected_version)
+          raise IOError, 'Post-reboot node changed during verification' unless handle[:my_node_num] == node
 
-          { status: :boot_verified, firmware_version: metadata[:firmware_version], node_num: handle[:my_node_num], metadata: metadata }
+          { status: :boot_verified, firmware_version: metadata[:firmware_version], node_num: node, node_id: format('!%08x', node), metadata: metadata }.merge(identity)
         end
       ensure
-        transport.disconnect(key => handle) if handle
+        transports.fetch(handle_type).disconnect(keys.fetch(handle_type) => handle) if handle && transports.key?(handle_type)
+      end
+
+      private_class_method def self.verify_identity(opts = {})
+        node = opts[:node]
+        raise IOError, 'Missing valid local node identity' unless node.is_a?(Integer) && (1...0xffffffff).cover?(node)
+        raise IOError, 'Post-reboot node identity mismatch' if opts[:expected_node] && node != opts[:expected_node]
+        return {} unless opts[:expected_public_key]
+
+        reply = Admin.request(transport_obj: opts[:handle], to: node, get_owner_request: true, timeout: opts.fetch(:timeout, 60))
+        raise IOError, 'Post-reboot public-key identity mismatch' unless reply.fetch(:value).public_key == opts[:expected_public_key]
+
+        result = { identity: :public_key_continuity }
+        return result unless opts[:previous_node]
+
+        result.merge(previous_node_num: opts[:previous_node], previous_node_id: format('!%08x', opts[:previous_node]), node_changed: node != opts[:previous_node])
       end
 
       private_class_method def self.validate_verification(opts = {})
         raise ArgumentError, 'verify must be a Hash of verify_reboot options' unless opts.is_a?(Hash)
 
-        allowed = %i[transport connection expected_version expected_node reconnect timeout reboot_delay]
+        allowed = %i[transport connection expected_version expected_node expected_public_key previous_node reconnect timeout reboot_delay]
         raise ArgumentError, 'Unknown reboot verification option' unless (opts.keys - allowed).empty?
         raise ArgumentError, 'transport must be :tcp, :bluetooth or :serial' unless %i[tcp bluetooth serial].include?(opts[:transport])
         raise ArgumentError, 'expected_version must be a nonempty firmware version String' unless opts[:expected_version].is_a?(String) && !opts[:expected_version].empty?
-        raise ArgumentError, 'expected_node must be a numeric node ID' if opts.key?(:expected_node) && !(opts[:expected_node].is_a?(Integer) && (1..0xffffffff).cover?(opts[:expected_node]))
+
+        %i[expected_node previous_node].each do |name|
+          raise ArgumentError, "#{name} must be a unicast numeric node ID" if opts.key?(name) && !(opts[name].is_a?(Integer) && (1...0xffffffff).cover?(opts[name]))
+        end
+        if opts.key?(:expected_public_key)
+          key = opts[:expected_public_key]
+          raise ArgumentError, 'expected_public_key must be 32 nonzero raw bytes' unless key.is_a?(String) && key.bytesize == 32 && key.bytes.any?(&:positive?)
+        end
+        raise ArgumentError, 'previous_node requires expected_public_key continuity' if opts.key?(:previous_node) && !opts[:expected_public_key]
 
         timeout = opts.fetch(:timeout, 60)
         delay = opts.fetch(:reboot_delay, 3)
@@ -300,7 +331,9 @@ module Meshtastic
             transport: 'required - :tcp, :bluetooth or :serial for the restarted application',
             connection: 'optional - connect options Hash with explicit host/address/block_dev; required without reconnect',
             expected_version: 'required - exact firmware version reported by the intended application',
-            expected_node: 'optional - numeric node identity to verify after restart',
+            expected_node: 'optional - strict numeric post-restart node identity; never relaxed by key continuity',
+            expected_public_key: 'optional - trusted pre-upgrade public identity, 32 raw bytes; compared with fresh local owner reply',
+            previous_node: 'optional - pre-upgrade numeric node for changed mapping output; requires expected_public_key',
             reconnect: 'optional - callable accepting options Hash and returning a newly connected transport handle',
             timeout: 'optional - entire reboot/reconnect/config/metadata deadline seconds, default 60',
             reboot_delay: 'optional - initial wait for loader restart, default 3 seconds'

data/lib/meshtastic/admin/validation.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Meshtastic
+  module Admin
+    # Firmware v2.8.1.8e6a88d: reject lossy writes rather than emulate clamping.
+    module Validation
+      public_class_method def self.validate(opts = {})
+        message = opts.fetch(:message)
+        message.class.descriptor.each do |field|
+          value = message[field.name]
+          values = field.label == :repeated ? value : [value]
+          values.each do |item|
+            if field.type == :enum
+              known = item.is_a?(Symbol) ? field.subtype.lookup_name(item) : field.subtype.lookup_value(item)
+              raise ArgumentError, "unknown enum for #{field.name}" if known.nil?
+            elsif field.type == :message && item
+              validate(message: item)
+            end
+          end
+        end
+        if message.is_a?(Meshtastic::Config::SecurityConfig)
+          keys = [message.private_key, message.public_key] + message.admin_key.to_a
+          raise ArgumentError, 'security keys must contain zero or 32 bytes; at most three admin keys' unless keys.all? { |key| [0, 32].include?(key.bytesize) } && message.admin_key.length <= 3
+        end
+        if message.is_a?(Meshtastic::Channel)
+          raise ArgumentError, 'channel index must be from 0 through 7' unless message.index.between?(0, 7)
+        elsif message.is_a?(Meshtastic::ChannelSettings)
+          raise ArgumentError, 'PSK must contain 0, 1, 16, or 32 raw bytes' unless [0, 1, 16, 32].include?(message.psk.bytesize)
+          raise ArgumentError, 'channel name must be fewer than 12 UTF-8 bytes without NUL' unless message.name.valid_encoding? && message.name.bytesize < 12 && !message.name.include?("\0")
+        end
+        if message.is_a?(Meshtastic::Config) || message.is_a?(Meshtastic::ModuleConfig)
+          raise ArgumentError, 'exactly one config section is required' unless message.payload_variant
+          raise ArgumentError, 'sessionkey is request-only; device_ui requires store_ui_config' if %i[sessionkey device_ui].include?(message.payload_variant)
+        end
+        owner(message: message) if message.is_a?(Meshtastic::User)
+        ham(message: message.set_ham_mode) if message.is_a?(Meshtastic::AdminMessage) && (message.payload_variant == :set_ham_mode)
+        message
+      end
+
+      private_class_method def self.owner(opts = {})
+        message = opts[:message]
+        name(value: message.long_name, label: 'owner long_name', limit: 24)
+        name(value: message.short_name, label: 'owner short_name', limit: 4)
+      end
+
+      private_class_method def self.ham(opts = {})
+        message = opts[:message]
+        name(value: message.call_sign, label: 'ham call_sign', limit: 7)
+        raise ArgumentError, 'ham call_sign is required' if message.call_sign.empty?
+
+        name(value: message.long_name, label: 'ham long_name', limit: 14)
+        name(value: message.short_name, label: 'ham short_name', limit: 4)
+        composed = message.long_name.empty? ? message.call_sign : "#{message.call_sign}//#{message.long_name}"
+        name(value: composed, label: 'ham composed owner long_name', limit: 24)
+      end
+
+      private_class_method def self.name(opts = {})
+        value = opts[:value]
+        valid = value.encoding == Encoding::UTF_8 && value.valid_encoding? && !value.include?("\0") && value.bytesize <= opts[:limit]
+        valid &&= value.empty? || !value.match?(/\A[ \t\r\n\v\f]*\z/)
+        raise ArgumentError, "#{opts[:label]} must be nonblank UTF-8 without NUL, at most #{opts[:limit]} bytes (empty means omitted)" unless valid
+      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:
+          # Validate semantics without changing data or contacting hardware.
+          #{self}.validate(message: 'required - protobuf message to validate against firmware v2.8.1.8e6a88d')
+          # Display the module authors.
+          #{self}.authors
+        "
+      end
+    end
+  end
+end