meshtastic 0.0.186 → 0.0.188

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e07fc03dd4ac92690b8209db83c3878cedaeeccae799f64d5a66ebcd77c661f
-  data.tar.gz: b084165dc768b1446b4977a1ab8be30657773b2549c6ef42f699ecb336516890
+  metadata.gz: 4acf199373bf9ae044384b1b735b8ce1706716882129fd59feedeeec6f203ece
+  data.tar.gz: 7586ab8345b4125963358eeea95df60279221ca8546ab7864ec6d2624db46727
 SHA512:
-  metadata.gz: 981f4b515e1820458ddfa5655aeb9d568e72fa92e05b7458b9069dc2b3baeb6bd7ab6c7a61c91e6d74fdd6f34e77c3aa4ae25f8b47c4f202667a8d0aaa147bc3
-  data.tar.gz: 54c9de46786ccf0052ede5e441cc526a3294eabb098a8c717d477edd46cf28a47d4e4cfa67349a97f067780ff7a056e3d80a6be598495754d967a69729b49135
+  metadata.gz: ec0d592b650fe5695c3c364ec571232710c5558375c362f03d41ec2ba57e133b461d2806a144fdc3dd15bb21f9e8028199e279debfe587199a2ca0e8d10c22b6
+  data.tar.gz: '097ee4ded46e2d30fc56cf5d4e04324d2b2d38432e4b62d7c6af7105c4f37c602f302c1d50141583600065e65f5986f6c4b81376138a18187433ab08ef3a4e25'

data/Gemfile

@@ -6,7 +6,7 @@ source 'https://rubygems.org'
 
 gemspec
 
-gem 'bundler', '>=4.0.21'
+gem 'bundler', '>=4.0.22'
 gem 'bundler-audit', '>=0.9.3'
 gem 'executable-hooks', '1.7.1'
 gem 'fiddle', '1.1.8'
@@ -18,7 +18,7 @@ gem 'mqtt', '0.7.0'
 gem 'rake', '13.4.2'
 gem 'rdoc', '7.0.4'
 gem 'rspec', '3.13.2'
-gem 'rubocop', '1.91.0'
+gem 'rubocop', '1.92.0'
 gem 'rubocop-rake', '0.7.1'
 gem 'rubocop-rspec', '3.10.2'
 gem 'ruby-dbus', '0.25.0'

data/documentation/README.md

@@ -40,6 +40,7 @@ Do not open Serial and Bluetooth to the same radio at once. Always `disconnect`
   - [Nordic legacy BLE DFU packages](admin-firmware-nordic.md)
 - [Meshtastic::ModuleConfig](module-config.md)
 - [Meshtastic::Position](position.md)
+- [Meshtastic::Waypoint](waypoint.md) — circle/box geofences and notification fields
 - [Meshtastic::Telemetry](telemetry.md)
 - [Meshtastic::Traceroute](traceroute.md)
 - [Meshtastic::RemoteHardware](remote-hardware.md)
@@ -67,4 +68,4 @@ Do not open Serial and Bluetooth to the same radio at once. Always `disconnect`
 - [Meshtastic::Util](util.md)
 - [Generated protobuf types](protobufs.md)
 
-Protobuf message classes that this gem reopens (`Channel`, `Config`, `Position`, `Telemetry`, `ModuleConfig`, `Paxcount`) must not define class methods named `send` or `encode` (those belong to protobuf). Use `get`/`set`, `transmit`, `build`, or `request` instead.
+Protobuf message classes that this gem reopens (`Channel`, `Config`, `Position`, `Waypoint`, `Telemetry`, `ModuleConfig`, `Paxcount`) must not define class methods named `send` or `encode` (those belong to protobuf). Use `get`/`set`, `transmit`, `build`, or `request` instead.

data/documentation/admin-backup.md

@@ -47,7 +47,7 @@ JSON selection defaults (binary-specific differences are listed below):
 - `include_owner: true`: only `long_name`, `short_name`, `is_licensed`.
   Never clone User ID, MAC, hardware model, public key, role or messaging
   capability metadata. Role belongs to device configuration; security keys
-  belong to explicitly selected security configuration.
+  belong to security configuration (included in the default selection).
 - `config_types:` defaults to `DEVICE_CONFIG`, `POSITION_CONFIG`, `POWER_CONFIG`,
   `NETWORK_CONFIG`, `DISPLAY_CONFIG`, `LORA_CONFIG`, `BLUETOOTH_CONFIG`,
   `SECURITY_CONFIG`. Use a narrower list for firmware that lacks sections.
@@ -75,18 +75,94 @@ resolved or pinned. A disk write/sync failure raises and can leave a partial
 0600 file; it is never reported as a successful backup. File mode protection is
 not encryption and does not protect against privileged host access.
 
+## Restore safety policy (firmware v2.8.1.8e6a88d)
+
+Validation is pinned to firmware commit
+[`8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c`](https://github.com/meshtastic/firmware/blob/8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c/src/modules/AdminModule.cpp)
+and protobuf commit `8f97d66a63ce10cfb12f94203e361691647f5ad3`.
+The same semantic validator runs for Admin setters, JSON backups and binary
+profiles before session acquisition or writes. It rejects rather than truncates:
+
+- Owner long names over **24 UTF-8 bytes**, short names over four bytes, embedded
+  NULs and nonempty ASCII-whitespace-only names. Empty owner names mean unchanged
+  on this firmware, not clearing. The User license flag has no presence: an
+  omitted flag in an owner write is false, not a read/merge patch.
+- Ham callsigns must be nonblank and at most seven bytes; the optional suffix is
+  at most fourteen bytes and short name at most four. The composed `CALL//suffix`
+  is checked against 24 bytes. Blank nonempty optional names are rejected rather
+  than silently ignored.
+- Unknown enum values, including numeric values accepted by protobuf; channel
+  indexes outside 0–7, unknown roles, names of twelve or more bytes/NUL, and PSKs
+  other than 0, 1, 16 or 32 raw bytes. PRIMARY is allowed at any valid slot for
+  direct/JSON writes; binary URL ordering still requires primary slot zero.
+- Config/ModuleConfig without exactly one selected section. A selected empty
+  section such as `device: {}` remains valid and means protobuf defaults.
+  Sessionkey is request-only and UI requires the dedicated store operation.
+- Security keys other than zero or 32 bytes, or more than three admin keys.
+  Size validation does **not** authenticate a keypair or prove public/private
+  correspondence; firmware derives/normalizes identity state.
+
+**Compatibility change:** `identity_keys: :reject` is the import default. Any
+nonempty `security.private_key` **or** `security.public_key` causes rejection of
+an entire restore before radio I/O. Use `identity_keys: :restore` only when
+intentionally cloning/restoring that identity. It sends the exact input; there
+is no silent stripping, rewriting or `:preserve` mode. To leave security entirely
+untouched, remove the complete security record offline or omit it from export.
+Excluding the owner record/owner ID does **not** exclude security identity keys;
+SECURITY_CONFIG is part of the default export selection. Admin authorization
+keys are secret-bearing configuration too, but are not the node identity keypair.
+
+**Privacy opt-in:** `allow_privacy_changes: false` is the import default. Set it
+to `true` explicitly for any PositionConfig (even an empty/default section), fixed
+position, positive channel position precision, channel uplink, enabled MQTT,
+MQTT map reporting, or enabled telemetry broadcasts. In both JSON and binary
+profiles, any true TelemetryConfig flag below requires consent:
+
+- `device_telemetry_enabled`
+- `environment_measurement_enabled`
+- `air_quality_enabled`
+- `power_measurement_enabled`
+- `health_measurement_enabled`
+
+These flags match the pinned protobuf revision above and current generated
+descriptors. An empty/default telemetry section, false broadcast flags, nonzero
+intervals alone, and on-device screen/Fahrenheit preferences do not require
+telemetry consent. Disabling device mesh telemetry does not disable metrics sent
+to a connected client. This is a conservative restore guard, not a complete
+privacy assessment of every firmware module. It does not fetch existing state to infer
+whether a setting is already enabled. No values are silently disabled or
+redacted. The report warns that these settings may disclose location/traffic or
+device, environment, air quality, power and health metrics, without printing values,
+and firmware may clamp public-channel position precision. Both consent options
+are required for relevant **dry runs too**; neither changes the backup bytes.
+Direct Admin setters are explicit low-level writes and do not use these backup
+consent flags.
+
+Absent security private keys preserve an existing firmware keypair; they do not
+request an identity reset. Owner/license, LoRa region and security changes can
+migrate identity and change the node number; network/Bluetooth changes can break
+the connection. Reports expose `reconnect_required` conservatively for these
+sections and warn the caller to reconnect and rediscover the target. The importer
+does **not** reconnect, infer a new target, replay writes, or claim persisted
+state. Optional readback still uses the original connection/target and can fail
+after an identity change. `persistence_verified` always remains false. Verify
+all selected sections on a newly established connection before claiming durable
+restoration. Hardware/reconnect verification is outside this implementation.
+
 ## Validate, plan and import
 
 ```ruby
 plan = Meshtastic::Admin::Backup.import(
   transport_obj: connection,
   path: '/private/directory/node-backup.json',
+  allow_privacy_changes: true, # reviewed location/sharing restoration
   dry_run: true
 )
 
 result = Meshtastic::Admin::Backup.import(
   transport_obj: connection,
   backup: snapshot[:backup], # use exactly one of backup: or path:
+  allow_privacy_changes: true, # explicitly restore reviewed location/sharing
   edit_transaction: true,   # ONLY when target firmware supports it
   verify: true,
   timeout: 10
@@ -160,7 +236,8 @@ snapshot = Meshtastic::Admin::Backup.export(
 snapshot.slice(:status, :format, :count)
 # snapshot[:backup] is a raw ASCII-8BIT String, not JSON/base64 or a protobuf object.
 # Pass it directly to Backup.import(transport_obj: connection,
-#                                 backup: snapshot[:backup], dry_run: true).
+#                                 backup: snapshot[:backup], dry_run: true,
+#                                 allow_privacy_changes: true).
 ```
 
 Binary returns `{ status: :exported, format: :device_profile, count: Integer,
@@ -216,6 +293,7 @@ plan = Meshtastic::Admin::Backup.import(
   transport_obj: connection,
   path: '/private/directory/nodeConfig.cfg',
   format: :device_profile,
+  allow_privacy_changes: true, # if restoring reviewed position/sharing sections
   dry_run: true
 )
 # Only section/slot identities and counts are returned; no profile contents.
@@ -226,6 +304,7 @@ plan = Meshtastic::Admin::Backup.import(
   transport_obj: connection,
   backup: binary_profile_string,
   format: :device_profile,
+  allow_privacy_changes: true, # if restoring reviewed position/sharing sections
   dry_run: true
 )
 ```
@@ -291,7 +370,7 @@ no-replay, secret-handling and persistence limitations apply.
 ACK, sends each section once with a correlated ACK wait (or matching timeout
 readback as described below), then sends
 `commit_edit_settings` and waits again. Current upstream
-[AdminModule.cpp](https://github.com/meshtastic/firmware/blob/master/src/modules/AdminModule.cpp)
+[AdminModule.cpp](https://github.com/meshtastic/firmware/blob/8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c/src/modules/AdminModule.cpp)
 implements a begin flag and commit save of configuration/module/device/channel/
 node database segments. Commit also disables Bluetooth. **This is not an atomic
 rollback facility**: firmware may apply values before commit, UI has its own

data/documentation/admin-config.md

@@ -29,7 +29,7 @@ ModuleConfig is a different protobuf: use `Admin.get_module_config` / `Admin.set
 
 Read/write helpers pass through Admin options, including `transport_obj: connection`, `to`, `from`, numeric transport `channel`, `want_ack`, `want_response`, `hop_limit`, and `session_passkey`. Use a supported connected transport. Session authentication and remote-node routing follow [Admin](admin.md).
 
-A return value means transport submission, **not confirmed persistence**. These methods inherit Admin's automatic remote session-key acquisition, but do not wait for write acknowledgments or read settings back. Obtain the prior configuration, edit it, write, and request it again to confirm; configuration writes replace a whole section rather than patching only non-default fields. Omitting a field in a Hash can reset that setting to its protobuf default. Firmware version and hardware determine which fields are applied, and writes may reboot/disconnect the node.
+For the section getters/setters above, a return value means transport submission, **not confirmed persistence**. These methods inherit Admin's automatic remote session-key acquisition, but do not wait for write acknowledgments or read settings back. Obtain the prior configuration, edit it, write, and request it again to confirm; configuration writes replace a whole section rather than patching only non-default fields. Omitting a field in a Hash can reset that setting to its protobuf default. Firmware version and hardware determine which fields are applied, and writes may reboot/disconnect the node.
 
 ## Example
 
@@ -50,6 +50,33 @@ Meshtastic::Admin::Config.set_device_ui(
 
 Ruby protobuf's `display` reader collides with `Object#display`; inspect `config['display']`, not `config.display`. Do not log configuration objects: network/security settings and session passkeys can contain secrets.
 
+## Signature policy and receive-only read/modify/readback
+
+Two helpers perform **fresh get → single set → fresh get**, rather than replacing a whole section with defaults:
+
+```ruby
+result = Meshtastic::Admin::Config.set_packet_signature_policy(
+  transport_obj: connection,
+  policy: :PACKET_SIGNATURE_POLICY_BALANCED,
+  timeout: 10
+)
+
+result = Meshtastic::Admin::Config.set_receive_only(
+  transport_obj: connection,
+  enabled: true, # writes LoRaConfig.tx_enabled = false; false re-enables TX
+  timeout: 10
+)
+```
+
+- `policy:` accepts the known `Config::SecurityConfig::PacketSignaturePolicy` symbols (`PACKET_SIGNATURE_POLICY_COMPATIBLE`, `PACKET_SIGNATURE_POLICY_BALANCED`, `PACKET_SIGNATURE_POLICY_STRICT`) or their known integer values. Unknown enums fail before any request. Compatible accepts unsigned traffic, balanced rejects unsigned signable broadcasts from previously signing nodes, strict requires authenticated traffic; strict can exclude older nodes.
+- Both require a radio receive queue; MQTT is unsupported. Receive-only is deliberately restricted to the **connected local node**: disabling a remote node's radio TX would prevent reliable remote readback and recovery. This is LoRa TX disablement, not a new firmware role or a host-side packet filter.
+- Current section fields are copied and only the requested field is changed. Security readback may contain private keys locally; do not log the returned data. Pinned firmware redacts remote private-key readback and preserves the existing identity keypair on a key-omitting security write.
+- The return value contains `acknowledgment:` (the setter's Admin result), `readback:` (the final correlated Admin result), `matched:` (whether the requested field matches), and `reboot_requested: false`. A firmware build without signature support may normalize the policy to compatible; `matched: false` exposes that instead of claiming success. Inspect the returned section for other firmware-normalized changes.
+- Helpers always wait and generate a fresh ID for each request, irrespective of supplied `wait`/`request_id`. `timeout` applies to each request. Pause other queue consumers throughout the sequence; do not run concurrent configuration editors.
+- No explicit reboot, implicit commit, retry, or mutation replay is issued. **Firmware itself can reboot or disable BLE on a section write**, so a timeout/disconnect is not evidence of rollback. Reconnect and issue `Admin.request(get_config_request: :SECURITY_CONFIG)` or `:LORA_CONFIG` before deciding what to do next. `matched` is current readback, not post-reboot persistence or host cryptographic verification. An already-open firmware edit transaction remains the caller's responsibility.
+
+These helpers are pinned to **v2.8.1.8e6a88d**: [config.proto](https://github.com/meshtastic/protobufs/blob/8f97d66a63ce10cfb12f94203e361691647f5ad3/meshtastic/config.proto) and [AdminModule.cpp](https://github.com/meshtastic/firmware/blob/8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c/src/modules/AdminModule.cpp). Offline framing/readback tests establish host behavior, not live firmware application.
+
 ## Protocol evidence
 
 - [Official Config schema](https://github.com/meshtastic/protobufs/blob/master/meshtastic/config.proto): all ten variants and request-only SessionkeyConfig.

data/documentation/admin-firmware-migration.md

@@ -0,0 +1,171 @@
+# Firmware v2.8.1 migration and installer matrix
+
+## Exact release boundary
+
+This delivery targets **`v2.8.1.8e6a88d`**, firmware commit
+`8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c`. The expected PhoneAPI version is
+**`2.8.1.8e6a88d`** (no leading `v`). The firmware's actual protobuf submodule
+pin is **`8f97d66a63ce10cfb12f94203e361691647f5ad3`**, not whichever protobuf
+revision happens to be current on `develop`.
+
+Sources: [exact release and migration warnings](https://github.com/meshtastic/firmware/releases/tag/v2.8.1.8e6a88d),
+[firmware protobuf gitlink](https://github.com/meshtastic/firmware/tree/8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c/protobufs),
+[pinned protobuf definitions](https://github.com/meshtastic/protobufs/tree/8f97d66a63ce10cfb12f94203e361691647f5ad3).
+
+**2.8.0 was revoked** for a packet-signing defect; its signatures are not
+compatible with 2.8.1. Do not substitute 2.8.0, a bare `2.8.1`, a different
+build suffix, or cached metadata for this release. `verify_reboot` is a generic
+exact-string verifier, not a firmware downloader/revocation service: the caller
+must pin `expected_version: '2.8.1.8e6a88d'` rather than pass an untrusted value
+reported by the device itself.
+
+## Implemented installer versus board support
+
+A board/chip label is not sufficient authorization or compatibility evidence.
+Select the actual board variant, image type, installed loader and physical
+endpoint. There is no automatic board selection, fallback or universal flasher.
+All rows below are **hardware-unverified**. Parser acceptance does not prove that
+a firmware image is safe for a specific radio, partition layout or bootloader.
+
+| Chip / representative board | Artifact | Implemented loader / data transport | Exact-release scope and restrictions |
+| --- | --- | --- | --- |
+| ESP32 (e.g. T-Beam), ESP32-S3 (e.g. Heltec V3) | Matching application BIN | `:esp_rom`, USB/UART ROM | Explicit `chip`, `port`, application `offset >= 0x10000`, flash capacity; identify chip/security before erase; flash MD5 verification. No factory/merged images, stub, secure/encrypted targets or full erase. These two release artifacts were not sampled in this audit. |
+| ESP32 / ESP32-S3 with compatible unified loader already installed | Matching application-update BIN | `:unified_wifi` TCP 3232 or `:unified_ble` custom GATT | Separate preparation via `request_ota`, NVS hash pin and final loader `OK`. Not PhoneAPI TCP 4403/BLE. No automatic loader installation or image/board compatibility inference. |
+| ESP32-C3 / Heltec HT62 SX1262 | Application BIN | `:esp_rom`, USB/UART ROM | Exact-release application parser accepted; factory BIN deliberately rejected. Do not infer unified-loader C3 support from a release's `bleota-c3.bin`. |
+| nRF52840 / RAK4631 | Intel HEX | `:swd`, trusted local OpenOCD executable and interface/target Tcl files | Exact-release parser accepted; explicit nRF52840 FICR/geometry checks before programming, `verify_image` and reset. No automatic recovery mass erase. |
+| nRF52840 / RAK4631 | UF2 | `:uf2`, explicitly selected Linux mounted bootloader volume | Backend exists for application range `0x27000...0xf4000` and exact Board-ID/family; **this exact-release UF2 is rejected**, since it starts at `0x26000`. Do not trim blocks or relax bounds blindly. |
+| nRF52840 / legacy Adafruit SDK11 DFU | Application-only legacy ZIP + DAT inside ZIP | `:nordic_dfu`, separate BLE DFU GATT | Backend exists, but **this release's RAK4631 OTA ZIP is rejected**: its manifest includes `dfu_version: 0.5`, while the current parser permits only the application member. This is a parser compatibility gap, not evidence the package uses Secure DFU. No conversion is attempted. |
+| RP2040 / RAK11310 | UF2 | `:uf2`, explicitly selected Linux mounted bootloader volume | Exact-release parser accepted with family `0xe48bff56` and explicit 2 MiB capacity. Require selected volume's Board-ID and correct actual capacity. Copy/fsync is submission, not flash verification. |
+| ESP32-C6 | Release BIN | **Unsupported** | Not in native ROM chip set; no claimed unified-loader support. |
+| RP2350 (including Ethernet OTA boards) | Release UF2 / Ethernet OTA | **Unsupported** | RP2040 support does not imply RP2350 families or its OTA protocol. |
+| STM32 / STM32WL | Release artifacts | **Unsupported** | nRF52840 OpenOCD support does not imply a generic STM32 installer. |
+| Nordic Secure DFU, serial Nordic DFU | Secure/signed ZIP or other package | **Unsupported** | Not the implemented legacy Adafruit BLE protocol. |
+| Any radio via MQTT or PhoneAPI XModem | Any image | **Unsupported image transport** | MQTT Admin preparation is distinct from upload; no synchronous MQTT reboot verifier. PhoneAPI XModem is filesystem transfer. |
+
+Format/protocol and verifier option mismatches fail before an installer is
+invoked. Backend-specific target/image validation occurs before opening a
+programmer, GATT loader or destination where implemented. ROM/SWD hardware chip
+checks necessarily occur after connecting but before erase. Unified OTA cannot
+prove board/image compatibility: the operator must select it explicitly.
+
+No backend offers a `full_erase:` option. The release recommends full erase and
+flash **if** upgrading causes bootloops/crashes, after exporting configuration.
+That recovery requires a separately authorized, board-specific tool/workflow;
+this gem must not report a normal application-region write as a full erase.
+
+## Backup and migration consent
+
+1. Before a destructive operation, obtain explicit authorization for the board,
+   endpoint, selected release/artifact, preparation/reboot, and recovery method.
+   Capture the old node number and a **fresh local owner public key** over the
+   trusted connection; retain the raw key only in memory/private backup. Do not
+   print keys, profiles or complete Admin packets. Close competing subscribers.
+2. Export and privately store a [host backup](admin-backup.md), JSON or binary
+   DeviceProfile `.cfg`. A backup can contain private identity keys, channel PSKs,
+   credentials, coordinates and PINs. Restrict access; do not attach it to logs.
+   Excluding owner metadata does **not** exclude `security` identity keys.
+3. Review a restore offline/dry-run before sending. `identity_keys: :reject` is
+   the default; explicitly choose `identity_keys: :restore` only for an intended
+   identity restoration. Privacy-sensitive position, telemetry and MQTT-sharing
+   restores require separate `allow_privacy_changes: true`, including dry runs.
+   Consent is not implicit in possessing a backup. No keys/settings are silently
+   stripped to make a restore pass. A key replacement/full erase without key
+   restoration will not satisfy continuity with the original identity.
+4. Review the release changes: key-derived node IDs replace MAC-derived IDs;
+   owner long names are limited to 24 UTF-8 bytes plus NUL; position/telemetry
+   broadcasts are opt-in; precise position is restricted on known-key channels;
+   first-time US region selection on the device screen now defaults to
+   **LongTurbo**, not LongFast. Choose compatible region/preset deliberately.
+   Do not blindly enable old sharing settings or replay a 2.7 backup wholesale.
+5. After the authorized installation and any restore, reconnect and read back the
+   requested state. ACKs, loader checksums and UF2 copy success are distinct from
+   application boot health and persisted configuration. Keep interrupted writes
+   ambiguous; never automatically replay a mutation or raw firmware bytes.
+
+## Key-continuous post-reboot verification
+
+`expected_node:` remains a **strict post-reboot numeric ID** check. Do not put the
+old 2.7 ID there when a 2.8 key-derived ID transition is expected. Instead provide
+a trusted pre-upgrade `expected_public_key:` (exactly 32 nonzero raw bytes) and
+`previous_node:` (old numeric unicast ID for mapping/reporting):
+
+```ruby
+result = Meshtastic::Admin::Firmware.verify_reboot(
+  transport: :serial,
+  connection: { block_dev: '/dev/ttyACM0', baud: 115_200 },
+  expected_version: '2.8.1.8e6a88d',
+  expected_public_key: trusted_pre_upgrade_public_key, # do not log this value
+  previous_node: old_node_number,
+  timeout: 90
+)
+# Use only selected report fields; never print the backup or request options.
+puts "#{result[:previous_node_id]} -> #{result[:node_id]}"
+```
+
+The same options work with explicitly selected application TCP or Bluetooth
+connections, or as the `verify:` Hash on `install`. `previous_node` requires key
+continuity; it is not a destination override. The verifier:
+
+- reconnects with the selected transport and waits for configuration completion;
+- fixes the connected local node as the target, then requests fresh **owner and
+  metadata** with independent request-ID/source correlation;
+- compares the public key and exact firmware string, rejecting another key,
+  stale/wrong-source replies and a local ID change during verification;
+- never scans or retries arbitrary mesh nodes to find an apparent match;
+- reports `identity: :public_key_continuity`, `previous_node_num`, `node_num`,
+  fixed-width `previous_node_id` / `node_id`, and `node_changed`; it returns no
+  owner/key material and does not log keys or echo them in identity errors.
+
+If both `expected_node` and `expected_public_key` are given, **both must match**.
+An advanced `reconnect:` callback must return a newly connected handle of the
+selected transport with configuration requested; freshness of that callback's
+connection is the caller's responsibility. Cached handle metadata never suffices.
+This is device-reported continuity on a trusted local connection, **not** a
+cryptographic challenge, signed boot attestation or RF-delivery test. Reports do
+not rewrite application destination maps: review and explicitly update them.
+
+## Executed exact-release parser audit (no hardware)
+
+Official archive members were retrieved from the exact release using Ruby
+`open-uri`, extracted in memory with Ruby `rubyzip`, then passed to the production
+Ruby parsers only. No Python, flasher, serial port, BLE radio, programmer or mount
+was opened. Samples were not modified to obtain a pass.
+
+| Official member | Bytes | Production parser result |
+| --- | ---: | --- |
+| `firmware-heltec-ht62-esp32c3-sx1262-2.8.1.8e6a88d.bin` | 2119088 | Accepted: ESP image/chip/checksum/SHA |
+| `firmware-heltec-ht62-esp32c3-sx1262-2.8.1.8e6a88d.factory.bin` | 2184624 | Rejected: merged/trailing data |
+| `firmware-rak4631-2.8.1.8e6a88d.hex` | 1966833 | Accepted: nRF52840 HEX |
+| `firmware-rak4631-2.8.1.8e6a88d.uf2` | 1398784 | Rejected: 16 blocks below supported application start |
+| `firmware-rak4631-2.8.1.8e6a88d-ota.zip` | 700163 | Rejected: manifest shape (`dfu_version`) |
+| `firmware-rak11310-2.8.1.8e6a88d.uf2` | 1611776 | Accepted: RP2040 UF2 |
+
+Reproduce without hardware: retrieve `firmware-esp32c3-2.8.1.8e6a88d.zip`,
+`firmware-nrf52840-2.8.1.8e6a88d.zip` and `firmware-rp2040-2.8.1.8e6a88d.zip`
+from the linked release; extract only the six named members to a private local
+directory, then run:
+
+```sh
+bundle exec ruby -Ilib spec/support/firmware_release_artifact_audit.rb /path/to/extracted-members
+```
+
+This opt-in audit pins each member's SHA-256, asserts the documented acceptance
+**or rejection**, and prints a JSON report. It is separate from the default spec
+suite and does not download artifacts itself. Rejections are real compatibility
+gaps, not verified installers. Hashes identify retrieved bytes, not publisher
+signatures. Firmware archives/binaries are not bundled in this repository.
+
+`firmware_migration_spec.rb` uses production ToRadio/AdminMessage/FromRadio codecs
+and synchronous Admin correlation over mocked Serial/BLE/TCP hardware writes.
+It covers changed mapping, exact suffix/revoked version rejection, stale cached
+metadata, unrelated source/request preservation, key mismatch, strict numeric
+expectation, reconnect transport mismatch and preflash option validation.
+Existing firmware specs additionally exercise a real loopback PhoneAPI TCP
+configuration/metadata exchange. `firmware_target_selection_spec.rb` guards
+unsupported chips/protocols, full-erase claims and preflash format selection.
+
+**Delivery step 6 remains blocked** pending the user's endpoint selection and
+explicit live-operation authorization. No hardware has been contacted, staged,
+prepared, erased, flashed or verified by this step.
+
+[Installer API and transport details](admin-firmware.md)

data/documentation/admin-firmware.md

@@ -2,6 +2,8 @@
 
 **PhoneAPI XModem is not a firmware flashing protocol.** The old implementation incorrectly sent padded XModem data after an OTA admin request and could report completion without any device acknowledgement. That path is now rejected, including MQTT's former silent request-only `install`.
 
+For the exact **v2.8.1.8e6a88d** release, see the [migration checklist and installer matrix](admin-firmware-migration.md): firmware/protobuf pins, public-key identity continuity, backup/privacy consent, actual release-parser results and unsupported board families. Parser/loader success is not hardware verification.
+
 ## Supported operations
 
 | Operation | What the Ruby implementation actually does |
@@ -120,8 +122,9 @@ result = Meshtastic::Admin::Firmware.install(
   verify: {
     transport: :bluetooth,
     connection: { address: 'AA:BB:CC:DD:EE:FF', adapter: 'hci0' }, # application address
-    expected_version: '2.7.1.example', # exact version from your chosen release
-    expected_node: 0xaabbccdd,
+    expected_version: '2.8.1.8e6a88d', # exact intended release, including suffix
+    expected_public_key: trusted_pre_upgrade_public_key, # raw 32 bytes, never log
+    previous_node: 0xaabbccdd, # report mapping; not a strict post-reboot ID check
     timeout: 90
   }
 )
@@ -138,7 +141,8 @@ For tests or an alternative Ruby GATT implementation, unified BLE accepts `backe
 
 - Required: `transport: :tcp | :bluetooth | :serial`, `expected_version:` (exact nonempty String).
 - Production default: `connection:` Hash for a **new** application connection, explicitly specifying `host`, `address`, or `block_dev`, respectively. TCP uses PhoneAPI port **4403**, not updater port 3232; set `connection[:port]` only for a custom PhoneAPI port. Do not supply an existing socket/handle.
-- Optional: `expected_node:` numeric node ID, `timeout:` whole-operation deadline (60 seconds), `reboot_delay:` initial wait (3 seconds).
+- Optional: `expected_node:` strict post-reboot numeric node ID, `timeout:` whole-operation deadline (60 seconds), `reboot_delay:` initial wait (3 seconds).
+- Migration identity: `expected_public_key:` trusted pre-upgrade raw 32-byte public key adds a fresh source/request-correlated local owner readback. `previous_node:` requires this key expectation and reports old/new fixed-width node IDs and `node_changed`; it does not retarget another node. Both an explicit `expected_node` and key expectation must match if supplied together. No keys are returned/logged; key comparison is device-reported continuity, not cryptographic attestation. See the [2.8.1 migration guide](admin-firmware-migration.md).
 - Optional advanced `reconnect:` callable receives `{transport:, connection:, timeout:}` and must return a newly connected handle of the selected transport, with configuration requested. The verifier still waits for configuration and issues a fresh Admin metadata request; a callback cannot substitute a cached metadata Hash. The returned handle is closed afterward.
 - Pre-metadata connection/configuration I/O failures retry every 0.25 seconds within the total deadline. Metadata errors/version mismatches do not cause a reflash or get converted to success.
 - A fresh source/request-ID-matched `get_device_metadata_response` is required. Cached `handle[:metadata]`, configuration metadata, loader VERSION, a routing ACK or successful port open cannot satisfy verification.

data/documentation/admin.md

@@ -87,6 +87,22 @@ After reboot, reconnect, complete the transport handshake, and make this request
 - `request(wait: false, ...)` retains the old `{ request_id:, result: }` submission-only API, including MQTT. Use your existing receive loop with `response` in that mode. Automatic remote session acquisition can still wait unless an explicit key or `auto_session: false` is supplied.
 - IDs are generated or supplied with `request_id:` (2 through `0xffffffff`), overriding `last_packet_id`. Use fresh IDs; deliberately reusing one cannot distinguish a stale reply. ID 1 is excluded because transport predecessor zero requests a random ID.
 
+### Delivery evidence and trust boundary (v2.8.1.8e6a88d)
+
+Synchronous `request` adds `delivery` and `security_provenance`:
+
+| `delivery` | Meaning |
+| --- | --- |
+| `:acknowledged` | Target-correlated successful routing ACK without valid device-reported ACK proof. Includes absent, invalid, unknown, and no-key proof statuses. |
+| `:device_verified` | Connected radio reports `ACK_PROOF_VALID` on the successful routing ACK matching the actual request ID **and addressed target**. This is a **device report**, not host cryptographic verification. |
+| `:readback` | Expected Admin response matched request ID and target. This is not an ACK proof or a persistence check. |
+
+`security_provenance` contains `source: :radio`, `verification: :device_reported`, and `reported: { ack_proof_status:, xeddsa_signed: }`. Raw enum values are retained, including unknown integers. A signature report **does not** substitute for ACK proof; invalid/no-key/absent proof must not be displayed as verified delivery. A local ACK cannot establish remote delivery. Even valid proof does not establish configuration persistence, application execution, or post-reboot health.
+
+Trust is assigned only inside the synchronous receive path using the already-classified radio handle's queue. `response` on caller-provided bytes (even a `FromRadio` object) instead reports `source: :unknown, verification: :untrusted`; caller-supplied provenance flags cannot promote it. MQTT publication or broker-supplied signature/proof fields cannot produce `:device_verified`. `wait: false` remains submission-only and has no verified-delivery result. Do not inject external/broker traffic into a radio handle's private receive queue.
+
+Pinned evidence: [ReliableRouter.cpp](https://github.com/meshtastic/firmware/blob/8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c/src/mesh/ReliableRouter.cpp) and [mesh.proto](https://github.com/meshtastic/protobufs/blob/8f97d66a63ce10cfb12f94203e361691647f5ad3/meshtastic/mesh.proto), firmware tag **v2.8.1.8e6a88d**. ACK proof is advisory on that release; legacy/no-proof ACKs remain distinguishable rather than being silently upgraded or retried.
+
 ### Automatic sessions
 
 Remote state-changing `send` calls (including convenience setters, reboot, and firmware commands) automatically request `get_config_request: :SESSIONKEY_CONFIG` before transmitting when no passkey was supplied. Acquisition must return a correlated `get_config_response` containing exactly eight passkey bytes; otherwise the write is not sent. Reads and local PhoneAPI operations do not need acquisition. An explicit eight-byte `session_passkey:` or a passkey already in `message:` bypasses acquisition; `auto_session: false` explicitly disables it. For MQTT provide the key obtained through your own authorized receive workflow.

data/documentation/mesh-interface.md

@@ -14,13 +14,13 @@ Packet builder used by Serial, Bluetooth, TCP, and MQTT. Instantiated internally
 - `send_data` / `send_text`
 - `send_to_radio` / `send_to_mqtt` — serialize only
 - `decode_payload` — shared protobuf/text/binary decoding; [complete port inventory](#receive-payload-coverage)
-- `decrypt_packet` — selected channel AES-CTR only; ciphertext preserved on failure
+- `decrypt_packet` — exact channel AES-CTR or AES-CCM (AEAD); ciphertext preserved on failure
 - `help` / `authors`
 
 On Serial/Bluetooth/TCP, transports pass `psks: nil` so the radio owns channel crypto. MQTT must pass `psks`.
 
-`send_data` and `send_packet` preserve `pki_encrypted: true` and `public_key:`
-(32 raw bytes) for remote administrative requests. The connected radio performs
+`send_text`, `send_data` and `send_packet` preserve `pki_encrypted: true` and `public_key:`
+(32 raw bytes) for radio-owned direct messaging and remote administrative requests. The connected radio performs
 the public-key encryption; the Ruby client does not encrypt these packets itself.
 Explicit PKI requests reject MQTT and host-side PSK encryption instead of silently
 falling back to channel encryption. Supplying a recipient key does not grant admin
@@ -46,7 +46,7 @@ text_bytes = mesh.send_text(
 envelope = mesh.send_text(
   from: '!c0ffee00',
   to: '!ffffffff',
-  channel: 93,
+  channel_id: 'LongFast', # exact name; firmware hash is computed
   text: 'Hello MQTT',
   via: :mqtt,
   psks: { LongFast: 'AQ==' }
@@ -184,21 +184,49 @@ This is schema dispatch, not decompression of arbitrary bytes.
 
 ### Encryption boundary
 
-`decrypt_packet(message:, psks:, channel:)` preserves already-decoded packets,
-even if PKI metadata is present. MQTT selects the exact `ServiceEnvelope.channel_id`
+`decrypt_packet(message:, psks:, channel:, source:)` preserves already-decoded payloads,
+even if PKI metadata is present, but always attaches host-created security provenance.
+MQTT passes `source: :mqtt` and selects the exact `ServiceEnvelope.channel_id`
 (string or symbol PSK key), using the topic channel only when the envelope omits it.
-It never falls back from an unknown channel to LongFast. Radio ciphertext carries
-an eight-bit XOR hash of channel name and key, not a local channel slot; only a
-unique matching configured name/key is selected. Hash collisions are refused.
-Supply the actual firmware channel name and full Base64 16- or 32-byte key.
-Subscription wrappers also accept the existing `LongFast: 'AQ=='` shorthand.
-
-PKI ciphertext is never fed to an AES channel cipher. Missing/ambiguous/invalid keys
-and malformed decrypted `Data` preserve ciphertext with `:decryption_error`.
-Successful channel decoding retains the existing `encrypted: :decrypted` marker.
-AES-CTR is unauthenticated: valid protobuf parsing is not proof the key was correct
-or the sender authentic. Device-owned private-key decryption remains the radio's
-responsibility. No private-key discovery or downgrade fallback is performed.
+Unknown names never fall back. Radio ciphertext uses the unique eight-bit XOR hash
+of name and expanded key, additionally XOR `0xAE` for an AEAD channel. Hash collisions
+and duplicate string/symbol key names are refused.
+
+Supply `psks: { Name: base64_key }` for legacy CTR or
+`psks: { Name: { psk: base64_key, use_aead: true } }` for CCM. Modes are configured
+per key, not detected by trial. Firmware aliases 1–255 expand on any channel name;
+otherwise require full 16/32-byte keys. Unlike firmware, arbitrary short keys are
+not padded and inherited secondary keys must be resolved by the caller.
+
+MQTT sends accept `channel_id:` (mandatory with multiple keys); they compute the
+firmware hash instead of using the old arbitrary numeric `channel:`. MQTT refuses
+plaintext fallback, explicit recipient PKI options, and nonbroadcast text, including
+text supplied as `Data`. Other channel-addressed application Data is not PKI.
+Serial/Bluetooth/TCP retain device channel-slot semantics and pass `psks: nil`.
+
+PKI ciphertext is never fed to an AES channel cipher. Missing/ambiguous/invalid keys,
+mode/hash mismatches, failed CCM tags and malformed decrypted Data preserve ciphertext
+with `:decryption_error`. Success retains `encrypted: :decrypted`. No fallback cipher
+or key is tried. AES-CTR parsing is not authentication.
+
+`:security_provenance` records `source: :radio, verification: :device_reported` for
+the three radio subscriptions (the direct helper defaults to `source: :radio`).
+The original `xeddsa_signed` and `ack_proof_status` are retained and copied under
+`:reported`. These are the connected device's reports, not host cryptographic checks.
+For MQTT, `source: :mqtt, verification: :untrusted`; those fields are removed from
+the top-level packet and preserved only under `:reported`. Broker-created provenance
+is overwritten. Successful host decryption adds `channel_authentication: :aead` or
+`:none`; channel-key possession does not prove sender identity, ACK validity or freshness.
+Raw FromRadio/protobuf APIs do not add this host-only metadata.
+
+Channel crypto is pinned to **v2.8.1.8e6a88d**, firmware
+`8e6a88d06f44cad26f1e8d7cd402939ccacb9b4c`, protobuf
+`8f97d66a63ce10cfb12f94203e361691647f5ad3`. CCM uses a 13-byte nonce
+`packet_id64le || from32le || 00`, AAD `from32le || to32le`, and appends a 12-byte tag.
+CTR uses the same prefix in a 16-byte nonce. See [MQTT](mqtt.md#pinned-firmware-interoperability)
+for source links, key selection, OpenSSL requirements, nonce-reuse limits and examples.
+No host XEdDSA signing/verification, PKI encryption/decryption or ACK-proof verification
+is implemented by these channel helpers.
 
 ### Verification