Sign plaintext packets in licensed mode

[RCGV1]

Closes #10966

Design: meshtastic/design#122
Related receive-policy work: #10967
Related schema: meshtastic/protobufs#983

Summary

• generate or restore the existing identity keypair for licensed operation and publish its public key in NodeInfo;
• sign fitting licensed broadcasts and directed packets with the existing XEdDSA implementation and existing from | id | portnum | payload tuple;
• keep licensed traffic plaintext by preserving the PKI send prohibition, blocking licensed PKI receive, and persistently removing channel PSKs/admin channels;
• warn before key-derived NodeNum migration, including deferred notification for legacy licensed nodes migrated during boot;
• sanitize licensed channel state during owner changes, cold boot/reload, and backup restore.

This does not add an authentication version, signature format, certificate system, or new wire-auth scheme. Normal-mode broadcast signing and PKI direct messages are unchanged. A signed callsign-bearing NodeInfo self-binds that label to a key; it does not validate licence ownership, provide confidentiality, or by itself prevent replay.

Validation

• test_admin_radio: 72/72 passed
• test_packet_signing: 39/39 passed
• rak3172: successful build
  • RAM: 25,012 / 65,536 (38.2%)
  • flash: 183,464 / 247,808 (74.0%)
• Trunk: no new issues
• git diff --check: clean
• Independent security review completed for commit 155c4f76289e760bd789d36f3254105f6b8e1702

Draft / hardware status

No RF hardware verification has been performed. Before this leaves draft:

• capture licensed broadcast and directed packets over RF and confirm the Data payload remains readable plaintext;
• verify signatures across representative devices and cross-version peers;
• verify reboot, licensed-mode transition, and backup-restore sanitation on hardware;
• verify Strict first-contact acceptance together with feat(security): enforce packet authenticity policies #10967 after its schema dependency is available.

Operators remain responsible for their licence conditions, jurisdiction, permitted modes, and station-identification requirements.

Summary by CodeRabbit

• New Features

  • Added notifications when licensed identity signing must migrate due to identity key changes.
  • Licensed nodes now automatically sign eligible packets, while tightening licensed encryption/decryption behavior.

• Bug Fixes

  • Improved licensed-channel sanitization during admin, restore, and boot flows to persist correctly and avoid unsupported encryption settings.
  • Preserved the default private key more safely and adjusted identity migration/regen behavior during configuration changes.

• Reliability

  • Licensed-channel updates are now persisted only when needed and remain idempotent (no repeated re-saves).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 63269516-5cc3-40a3-91c5-96636e77a952

📥 Commits

Reviewing files that changed from the base of the PR and between 8009692 and 155c4f7.

📒 Files selected for processing (3)

• src/modules/AdminModule.cpp
• test/test_admin_radio/test_main.cpp
• test/test_packet_signing/test_main.cpp

🚧 Files skipped from review as they are similar to previous changes (2)

• src/modules/AdminModule.cpp
• test/test_packet_signing/test_main.cpp

---

📝 Walkthrough

Walkthrough

Licensed operation now generates and publishes identity keys, signs eligible plaintext traffic, prevents PKI decryption, sanitizes channels, and persists migration changes across boot, configuration, and restore flows.

Changes

Licensed operation

Layer / File(s)	Summary
Licensed packet signing and identity publication src/mesh/Router.cpp, src/modules/NodeInfoModule.cpp	Licensed packets are signed when their encoded data fits, PKI decryption is disabled for licensed nodes, and NodeInfo retains the public identity key.
Licensed identity migration lifecycle src/mesh/NodeDB.*, src/modules/AdminModule.*, src/main.cpp, test/support/MockMeshService.h	Identity generation, migration detection, deferred notifications, region and ham-mode handling, and conditional persistence are added for licensed operation.
Licensed channel sanitization and persistence src/mesh/Channels.cpp, src/mesh/NodeDB.cpp, src/modules/AdminModule.cpp	Admin and encrypted channels are sanitized during owner changes, boot migration, and preference restoration, with affected channel segments persisted.
Licensed behavior test coverage test/test_admin_radio/*, test/test_packet_signing/*, test/support/AdminModuleTestShim.h	Tests cover signing, PKI exclusion, identity handling, NodeInfo publication, channel sanitation, persistence, and test lifecycle support.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant AdminModule
  participant NodeDB
  participant Router
  participant NodeInfoModule
  participant MeshService

  AdminModule->>NodeDB: generate licensed identity key
  NodeDB->>NodeDB: mark migration pending
  NodeDB->>MeshService: notify pending identity migration
  Router->>Router: sign eligible plaintext licensed packet
  Router->>Router: skip PKI decryption for licensed traffic
  NodeInfoModule->>NodeInfoModule: publish identity public key

Loading

Possibly related issues

• meshtastic/design 122 — Defines the licensed identity-key publication, plaintext signing, and PKI exclusion behavior implemented here.
• meshtastic/design 123 — Covers the overlapping licensed identity and signed plaintext authorization flow.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 31.91% 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
Title check	✅ Passed	The title is concise and accurately reflects the main change: signing plaintext packets in licensed mode.
Description check	✅ Passed	The description is mostly complete, with summary, validation, and hardware-status sections; the template attestation checklist is omitted.
Linked Issues check	✅ Passed	The changes satisfy #10966 by signing licensed plaintext packets, preserving identity keys/public keys, keeping PKI off, and adding migration/sanitation coverage.
Out of Scope Changes check	✅ Passed	No clearly unrelated code changes stand out; the edits stay focused on licensed identity, signing, sanitation, and supporting tests.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

⚡ Try this PR in the Web Flasher

Warning

This is an automated, unreviewed CI test build. Back up your device configuration
before flashing, and only flash devices you are able to recover.

Supported boards built by this PR (27)

	Device	Board	Platform
	Crowpanel Adv 3.5 TFT	elecrow-adv-35-tft	esp32-s3
	Heltec HT62	heltec-ht62-esp32c3-sx1262	esp32-c3
	Heltec Mesh Node 096	heltec-mesh-node-t096	nrf52840
	Heltec Mesh Node T1	heltec-mesh-node-t1	nrf52840
	Heltec Mesh Node T114	heltec-mesh-node-t114	nrf52840
	Heltec V3	heltec-v3	esp32-s3
	Heltec V4	heltec-v4	esp32-s3
	Meshnology W10	meshnology_w10	esp32-s3
	Raspberry Pi Pico	pico	rp2040
	Raspberry Pi Pico W	picow	rp2040
	RAK WisMesh Tag	rak_wismeshtag	nrf52840
	RAK WisBlock 11200	rak11200	esp32
	RAK WisBlock 11310	rak11310	rp2040
	RAK3312	rak3312	esp32-s3
	RAK WisBlock 4631	rak4631	nrf52840
	Seeed SenseCAP Mesh-Tracker-X1	seeed_mesh_tracker_X1	nrf52840
	Seeed Wio Tracker L1	seeed_wio_tracker_L1	nrf52840
	Seeed Xiao NRF52840 Kit	seeed_xiao_nrf52840_kit	nrf52840
	Seeed Xiao ESP32-S3	seeed-xiao-s3	esp32-s3
	Station G2	station-g2	esp32-s3
	Station G3	station-g3	esp32-s3
	LILYGO T-Deck	t-deck-tft	esp32-s3
	LILYGO T-Echo	t-echo	nrf52840
	LILYGO T-Echo Plus	t-echo-plus	nrf52840
	LILYGO T-Impulse Plus	t-impulse-plus	nrf52840
	LilyGo T3-C6	tlora-c6	esp32-c6
	Seeed SenseCAP T1000-E	tracker-t1000-e	nrf52840

Build artifacts expire on 2026-08-09. Updated for 155c4f7.

[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.

[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]

Actionable comments posted: 3

🤖 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/modules/AdminModule.cpp`:
- Around line 978-987: Update the licensed first-region setup branch in
AdminModule.cpp after nodeDB->generateCryptoKeyPair() to persist all newly
generated identity state by saving SEGMENT_CONFIG | SEGMENT_MODULECONFIG |
SEGMENT_DEVICESTATE | SEGMENT_NODEDATABASE, ensuring the node number and owner
identity survive reboot.

In `@test/test_admin_radio/test_main.cpp`:
- Around line 968-976: In the test setup around testAdmin, preserve the existing
global owner and config.lora.region values before assigning test-specific
values, then restore both after the test completes, preferably with a small RAII
guard to cover failures and early exits. Use the NodeDB replacement block and
the licensed test setup as the integration point, ensuring restoration occurs
before teardown.

In `@test/test_packet_signing/test_main.cpp`:
- Around line 597-600: Shorten the Group C banner comment to one or two lines,
retaining only a concise section heading and the rationale that it covers
NodeInfoModule downgrade drops for broadcast ingress paths while unicast
NodeInfo is exempt.

🪄 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: 7d239e62-5359-4d18-a5d7-5a318749999c

📥 Commits

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

📒 Files selected for processing (12)

• src/main.cpp
• src/mesh/Channels.cpp
• src/mesh/NodeDB.cpp
• src/mesh/NodeDB.h
• src/mesh/Router.cpp
• src/modules/AdminModule.cpp
• src/modules/AdminModule.h
• src/modules/NodeInfoModule.cpp
• test/support/AdminModuleTestShim.h
• test/support/MockMeshService.h
• test/test_admin_radio/test_main.cpp
• test/test_packet_signing/test_main.cpp

[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.