[jmpuch]

Problem

microReticulum has no support for interface access codes (IFAC). The IFAC code in Transport::transmit() / Transport::inbound() is a commented-out Python TODO, so:

• a microReticulum node cannot join a network whose interfaces use network_name / passphrase (Python RNS ifac_netname / ifac_netkey, as commonly set on shared LoRa channels) — its packets carry no access code and are dropped by the other nodes;
• packets that do carry an IFAC are unpacked as if they were plain packets. On a LoRa channel shared with IFAC-protected nodes this shows up as a stream of "Invalid signature" announces and bogus hop counts.

Solution

Follow Python RNS exactly:

• Interface::setup_ifac(netname, netkey) derives ifac_key = HKDF(64, SHA256(SHA256(netname) || SHA256(netkey)), IFAC_SALT) and the IFAC signing identity from it. ifac_size defaults to 8 (the RNode/LoRa value) and can be changed with ifac_size(n). Passing empty/null for both leaves IFAC off, so existing users see no change.
• Transport::ifac_mask(): the IFAC is the last ifac_size bytes of the identity's signature of the packet; header and payload are masked with HKDF(ifac) salted with ifac_key. Called from transmit().
• Transport::ifac_unmask(): unmask and verify. inbound() drops packets without a valid IFAC on an IFAC-enabled interface, and — as Python RNS does — drops IFAC-flagged packets on an interface without IFAC instead of misparsing them.

The masking lives in two small static helpers so it can be unit-tested without a radio. The implementation is ported from the IFAC support in the microReticulum copy bundled with jrl290/RTNode-HeltecV4 (Apache-2.0), which has been running it on LoRa nodes; credit to its author. The README roadmap gets an "Implement interface access codes (IFAC)" entry.

Compatibility: no API is removed; interfaces without setup_ifac() behave as before, except that IFAC-flagged packets are now dropped rather than misread.

Testing

• Unit tests — test/test_ifac (native): the derived key, the masked packet and the unmasked packet are checked byte for byte against vectors produced by Python RNS 1.5.4 itself (its interface key derivation and RNS.Transport.transmit()); tampered, other-network, unflagged and truncated packets are rejected.
• Native (Linux, GCC 15.2, native-local): test_ifac, test_crypto, test_transport, test_rns_loopback, test_bytes, test_general pass. (Needs Include stdint.h in Utilities/Memory.h #90 on GCC 15, independent of this change.)
• nRF52 hardware — Heltec T114 running microReticulum_Firmware with this library, LoRa interface configured with an IFAC network name + passphrase, on a real LoRa link with a node running RTNode-HeltecV4 (same IFAC): announces propagate both ways, and a Link + request to the T114's NomadNet page from Python RNS instances two and three hops away succeeds. Before the change the T114 could not talk to IFAC-protected nodes at all.
• ESP32 — pio run -e ttgo-lora32-v21 builds; not tested on ESP32 hardware.

A follow-up PR to microReticulum_Firmware exposes the network name and passphrase as Provisioning fields.

🤖 Generated with Claude Code

[jmpuch]

Firmware side (Provisioning fields + a small USB tool to set the network name / passphrase): attermann/microReticulum_Firmware#117.

[attermann]

Thank you for this, @jmpuch. IFAC was a critical missing piece for parity with the Reticulum reference implementation. Without it, microReticulum nodes couldn't join IFAC-protected networks at all. Checking the derivation and masking byte for byte against vectors from Python RNS itself, and testing on real LoRa hardware against Python nodes, is exactly the care this kind of change needs. I really appreciate the work, including the credit to RTNode-HeltecV4 for the port.

I'm happy to take this as it is. A few suggestions for future PRs, none of which hold this one up:

• Keep unrelated changes, like the #undef min / #undef max in Log.h, in their own PR. The contribution policy asks for one concern per PR (section 5.2).
• Add a CHANGELOG entry when behavior changes for existing users. Here that would be IFAC-flagged packets now being dropped on interfaces without IFAC (sections 5.6 and 5.7).
• Add a short docs or README note on how to use a new API. For this PR that would be Interface::setup_ifac() and the ifac_size default of 8, which non-LoRa interfaces may need to change (section 5.7).

Thanks again, and for the matching firmware work in attermann/microReticulum_Firmware#117.