feat(security): enforce packet authenticity policies

[RCGV1]

Summary

Adds a device-owned receive policy for Meshtastic's existing XEdDSA and PKI authentication results:

• Compatible verifies signatures when possible and accepts unsigned traffic.
• Balanced preserves the current signed-broadcast downgrade protection and legacy interoperability.
• Strict admits decryptable remote traffic to local processing only after a valid existing XEdDSA signature or successful existing PKI decryption.

Strict applies across packet types and destinations, including positions, NodeInfo, telemetry, text, routing/control, broadcasts, and unicasts. The policy is enforced before NodeDB/history storage, modules, connected clients, plaintext MQTT, ACK side effects, or rebroadcast of decryptable rejected traffic.

This PR does not add a signature version, change the existing signed tuple, change PKI/AES-CCM bytes, or make the receive policy affect outbound traffic. Licensed/ham plaintext signing is intentionally separate in design#122 / #10966.

Implementation

• consumes SecurityConfig.packet_signature_policy and reports DeviceMetadata.has_xeddsa
• validates first-contact signed NodeInfo against its embedded key and CRC32 node identity before committing the key
• preserves known-signer downgrade state through warm-store eviction
• distinguishes decryptable failures from opaque unknown-channel transit
• keeps opaque traffic relay-only, limited to rebroadcast modes that permit opaque forwarding and routed through normal duty-cycle/queue/transmit safety
• applies the same gate to RF, SimRadio/UDP, and MQTT ingress without trusting serialized auth flags
• carries an exact, one-shot, nonserialized authentication handoff so packets are verified once while original ciphertext remains byte-exact for encrypted MQTT forwarding
• enables XEdDSA on RAK3172 and CDEBYTE E77-MBL, while constrained STM32 targets that overflow remain excluded and report the capability as false

Validation

• packet signing/policy suite: 46/46 passed
• MQTT suite: 50/50 passed
• crypto suite: 11/11 passed
• warm store suite: 13/13 passed
• RAK3172 final build: 25,852 / 65,536 RAM (39.4%), 201,516 / 247,808 flash (81.3%)
• CDEBYTE E77-MBL policy build: 24,944 / 65,536 RAM (38.1%), 198,160 / 247,808 flash (80.0%)
• trunk check and git diff --check: clean
• dedicated security re-review: approved exact commit d6b12ea3f1fc83afcff63a7fb511d54c52cc871a

No RF/BLE/serial hardware verification has been performed. This PR must remain draft until real-device verification is recorded.

Depends on meshtastic/protobufs#983.

Closes #10963
Design: meshtastic/design#121

Summary by CodeRabbit

• New Features

  • Improved XEdDSA signature tracking, including warm-tier signer recognition and state rehydration.
  • Added a routing authentication gate to consistently accept/reject packets based on the configured signature policy (including opaque relay-only behavior).

• Bug Fixes

  • Tightened duplicate/rebroadcast and upgraded-packet handling so processing stops cleanly on auth/decode failures.
  • Updated handling of MQTT/UDP PKI metadata and clarified NodeInfo broadcast acceptance for previously signed-lites.

• Tests

  • Expanded signing-policy test coverage (strict/compatible) and upgraded routing/authentication-order assertions.

• Chores

  • Adjusted build variants to disable XEdDSA-exclusion where applicable.

[RCGV1]

@coderabbitai review

[github-actions]

⚡ Try this PR in the Web Flasher

Note

Building this pull request… the flash button, badges and supported-board
list will appear here automatically once CI finishes.

[RCGV1]

CI label check requires an enhancement (or equivalent allowed) label. This contributor account cannot add repository labels; a maintainer will need to apply it before the check can pass.

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR centralizes packet authenticity decisions, adds configurable XEdDSA receive-policy enforcement, preserves signer state across warm storage, supports opaque relay, gates routing side effects, updates MQTT/UDP ingress handling, and expands packet-signing and MQTT validation coverage.

Changes

Packet authenticity policy

Layer / File(s)	Summary
Policy contracts and signer persistence src/main.cpp, src/mesh/Router.h, src/mesh/WarmNodeStore.h, src/mesh/NodeDB.*, src/modules/AdminModule.cpp, variants/stm32/*	Adds routing-auth verdicts and decode states, reports XEdDSA capability, persists signer metadata through warm storage, normalizes unsupported policies, and enables XEdDSA for selected STM32 targets.
Centralized routing authentication src/mesh/Router.*, src/mesh/udp/UdpMulticastHandler.h, src/mqtt/MQTT.cpp, src/modules/NodeInfoModule.cpp	Adds cached authentication evaluation, policy handling, first-contact NodeInfo verification, opaque decode results, pre-routing gates, and consistent ingress processing.
Opaque relay and retry gating src/mesh/FloodingRouter.*, src/mesh/NextHopRouter.*	Prevents rebroadcast and ACK/retry actions after failed reprocessing and adds constrained opaque-packet relaying.
Policy matrix and pipeline validation test/test_packet_signing/test_main.cpp, test/test_mqtt/MQTT.cpp	Adds policy-mode, malformed-signature, downgrade, warm-store, MQTT-ingress, and routing-side-effect tests with an authentication pipeline harness.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RadioOrMQTT
  participant Router
  participant AuthCache
  participant RelayOrModule
  RadioOrMQTT->>Router: submit packet
  Router->>AuthCache: reuse or evaluate routing authentication
  AuthCache-->>Router: ACCEPT, REJECT, or OPAQUE_RELAY_ONLY
  Router->>RelayOrModule: relay opaque packet or update local routing state

Loading

Possibly related issues

• meshtastic/design issue 121 — Defines the packet-signature policy implemented by this PR.
• meshtastic/protobufs issue 982 — Covers the packet_signature_policy schema exercised by the firmware changes.
• meshtastic/web issue 1260 — Proposes exposing the firmware-supported packet-signature policy in the Web UI.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.93% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes implement the requested configurable receive policy, ingress gating, NodeInfo validation, warm-store handling, and XEdDSA capability reporting.
Out of Scope Changes check	✅ Passed	No clear out-of-scope code changes stand out; the touched routers, MQTT, tests, and variant configs all support the authenticity policy work.
Title check	✅ Passed	The title clearly summarizes the main change: enforcing packet authenticity policies.
Description check	✅ Passed	The description covers summary, implementation, validation, and draft/testing status, with only minor omission of explicit checkbox attestations.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[RCGV1]

CI dependency status: the current Native Simulator, WASM, and Docker failures all stop at DeviceMetadata.has_xeddsa being absent from the checked-out protobuf submodule. That field is supplied by the linked draft dependency meshtastic/protobufs#983. The later lcov: command not found line in the native job is only a cascading post-failure step. No independent firmware compile failure appears in these jobs; they should be rerun after the protobuf dependency lands.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mesh/Router.h`:
- Around line 178-181: Shorten the API comments near the receive authentication
policy and the related declarations around `Router` to one or two concise lines
each. Retain only the essential contract; remove detailed packet-routing and
policy behavior explanations from the header comments.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 634c2153-5eb0-42bd-97e8-8d8610d3f738

📥 Commits

Reviewing files that changed from the base of the PR and between 91043fa and d6b12ea.

📒 Files selected for processing (19)

• src/main.cpp
• src/mesh/FloodingRouter.cpp
• src/mesh/FloodingRouter.h
• src/mesh/NextHopRouter.cpp
• src/mesh/NextHopRouter.h
• src/mesh/NodeDB.cpp
• src/mesh/NodeDB.h
• src/mesh/Router.cpp
• src/mesh/Router.h
• src/mesh/WarmNodeStore.h
• src/mesh/udp/UdpMulticastHandler.h
• src/modules/AdminModule.cpp
• src/modules/NodeInfoModule.cpp
• src/mqtt/MQTT.cpp
• test/test_mqtt/MQTT.cpp
• test/test_packet_signing/test_main.cpp
• variants/stm32/CDEBYTE_E77-MBL/platformio.ini
• variants/stm32/rak3172/platformio.ini
• variants/stm32/stm32.ini

[RCGV1]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.