diff --git a/docs/cli_commands.md b/docs/cli_commands.md index dc2088e17..74e996c7d 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -631,20 +631,25 @@ and the next attempt follows the normal 30-minute retry. The command requires also retains the normal quorum, timestamp-validity, and drift checks. `clock.sync.mesh` collects signature-verified advert timestamps and MAC-valid, -decrypted Public-channel plain-text timestamps, but only after the packet passes -every forwarding filter. Sources are deduplicated by advert public key or -case-insensitive Public-channel display name. Every fresh sample must also have -a different full received path; all direct, zero-hop receptions count as the -same empty path. This prevents repeated packets or multiple names arriving over -one route from increasing the vote count. +decrypted Public-channel plain-text timestamps. In normal path mode, collection +occurs only after the packet passes every forwarding filter. Sources are +deduplicated by advert public key or case-insensitive Public-channel display +name. Every fresh sample must also have a different full received path; all +direct, zero-hop receptions count as the same empty path. This prevents repeated +packets or multiple names arriving over one route from increasing the vote +count. For a node at the edge of the network where every packet arrives through one relay path, `set clock.sync.mesh.edge on` changes the evidence requirement from distinct receive paths to distinct sources. Signature-verified adverts are deduplicated by public key, and Public-channel timestamps are deduplicated by case-insensitive display name. Repeated packets from one source still count -once. Changing edge mode clears the in-memory sample table so evidence collected -under the other policy is not reused. The setting is persistent and defaults on. +once. Edge mode observes this verified evidence on the receive path, independently +of the forwarding decision, so `repeat off` and forwarding filters do not prevent +clock collection. Other packet types are observed normally but cannot be clock +evidence because they do not provide a suitable authenticated Unix timestamp. +Changing edge mode clears the in-memory sample table so evidence collected under +the other policy is not reused. The setting is persistent and defaults on. At least the configured number of distinct fresh evidence sources (nine by default) and a strict majority of all fresh samples must fall within ten minutes diff --git a/docs/halo_keymind_settings.md b/docs/halo_keymind_settings.md index 78833ed81..f9a950892 100644 --- a/docs/halo_keymind_settings.md +++ b/docs/halo_keymind_settings.md @@ -87,7 +87,7 @@ set flood.retry.ignore none | `flood.filter` | Persistent repeater-only forwarding rules for flood routes `0x00`/`0x01`, selected by payload type and optional received hop count/range (omitted means `all`). New tables seed slot 1 with `ota all suspend=tempradio`; only rows marked `suspend=tempradio` are skipped during temporary-radio operation. Login-capable `anon_req`/`path`/`response` types become filterable at hop `7`; flood `txt_msg` becomes filterable at hop `5`. Standard direct traceroute, other direct routing, and local receive/logging are unchanged. | `get flood.filter[.n]`, `set flood.filter[.n] [N|N+|N-M|all] [suspend=tempradio]`, `del flood.filter.|all` | `set flood.filter.1 0x0C all suspend=tempradio` | | `flood.moderation` | Decrypts keyed `GRP_TXT` channels and applies drop, per-username messages/minute, and maximum-hop controls, optionally matched against the first 1-3 path hashes. Supports `public`, `#channel`, and 128/256-bit channel keys. Sender names and truncated path hashes are moderation hints, not authenticated identities. | `get flood.moderation[.n]`, `set flood.moderation[.n] [path=...]`, `del flood.moderation.|all` | `set flood.moderation public "Noisy User" rate=5/min hops=4` | | `clock.sync.mesh` | Defaults on for nRF52 repeaters and off for other builds; a saved setting overrides that default. After 30 minutes of uptime, it estimates UTC from a configurable consensus of fresh signed-advert or valid Public-channel sources, then repeats lazily seven days after each successful estimate. Failed attempts retry every 30 minutes; `clock.sync.mesh now` queues an immediate LoRa-only attempt without bypassing quorum or source suppression. Only timestamps from firmware build time through build time plus ten years are recorded. Successful CLI, GPS, or WiFi/NTP clock updates suppress LoRa time collection until reboot; after reboot LoRa is the fallback if NTP cannot sync. Status reports the reason a clock was not set; its `.table` and `.1` through `.16` forms inspect collected samples. | `get clock.sync.mesh`, `set clock.sync.mesh `, `clock.sync.mesh now`, `get clock.sync.status[.table|.1-.16]` | `set clock.sync.mesh on` | -| `clock.sync.mesh.edge` | Defaults on so edge repeaters can collect clock evidence when all packets arrive through one relay path. Signed adverts are deduplicated by public key and Public-channel timestamps by case-insensitive display name; all may share one receive path. Public display names are unauthenticated and can be spoofed. Changing this setting clears current clock samples. | `get clock.sync.mesh.edge`, `set clock.sync.mesh.edge ` | `set clock.sync.mesh.edge on` | +| `clock.sync.mesh.edge` | Defaults on so edge repeaters can collect clock evidence when all packets arrive through one relay path. Verified evidence is observed before the forwarding decision, so `repeat off` and forwarding filters do not prevent collection. Signed adverts are deduplicated by public key and Public-channel timestamps by case-insensitive display name; all may share one receive path. Public display names are unauthenticated and can be spoofed. Changing this setting clears current clock samples. | `get clock.sync.mesh.edge`, `set clock.sync.mesh.edge ` | `set clock.sync.mesh.edge on` | | `clock.sync.internet` | Adds a read-only internet/NTP estimate at the same initial and seven-day checks on WiFi MQTT repeater-observer builds. Other builds retain the setting but report internet unavailable. | `get clock.sync.internet`, `set clock.sync.internet ` | `set clock.sync.internet on` | | `clock.sync.drift` | Absolute correction threshold in seconds. The clock is moved forward or backward only when the estimate differs by more than this value. | `get clock.sync.drift`, `set clock.sync.drift <30-86400>` | `set clock.sync.drift 3600` | | `clock.sync.samples` | Minimum fresh evidence count before mesh time can be used: distinct receive paths in normal mode or distinct advert keys/Public-channel display names in edge mode. A strict majority of all fresh samples is also required. Range `3-16`; default `9`. | `get clock.sync.samples`, `set clock.sync.samples <3-16>` | `set clock.sync.samples 9` | diff --git a/examples/simple_repeater/MyMesh.cpp b/examples/simple_repeater/MyMesh.cpp index a9f781b7d..77d6e5ef8 100644 --- a/examples/simple_repeater/MyMesh.cpp +++ b/examples/simple_repeater/MyMesh.cpp @@ -884,10 +884,11 @@ bool MyMesh::allowPacketForward(const mesh::Packet *packet) { // for a message this repeater will actually retransmit. #if !defined(PORTABLE_MQTT_OBSERVER) if (packet->isRouteFlood() && shouldBlockFloodGroupTextForward(packet)) return false; - // Clock evidence is collected only after every forwarding filter accepts the - // packet. Blocked regions, moderated users, hop/type rules, and looped packets - // therefore cannot influence the estimate. - recordAcceptedFloodClockSample(packet); + // Normal path mode accepts clock evidence only from packets this node would + // forward. Edge mode observes verified evidence on the receive path instead, + // so repeat off and other forwarding filters do not hide a single upstream + // path from a node at the edge of the network. + if (!clock_sync_mesh_edge_enabled) recordAcceptedFloodClockSample(packet); #endif return true; } @@ -2229,6 +2230,16 @@ void MyMesh::onAdvertRecv(mesh::Packet *packet, const mesh::Identity &id, uint32 const uint8_t *app_data, size_t app_data_len) { mesh::Mesh::onAdvertRecv(packet, id, timestamp, app_data, app_data_len); // chain to super impl + // Mesh calls this hook only after verifying the advert's Ed25519 signature. + // Edge mode observes it here rather than in allowPacketForward(), because + // forwarding can be disabled on a receive-only edge node. + if (clock_sync_mesh_edge_enabled && isClockSyncCollectionActive()) { + uint8_t source_id[4]; + mesh::Utils::sha256(source_id, sizeof(source_id), id.pub_key, PUB_KEY_SIZE); + recordClockSyncSample(mesh::CLOCK_SYNC_SAMPLE_SOURCE_SIGNED_ADVERT, + source_id, timestamp, packet); + } + // if this a zero hop advert (and not via 'Share'), add it to neighbours if (packet->getPathHashCount() == 0 && !isShare(packet)) { AdvertDataParser parser(app_data, app_data_len); @@ -2238,6 +2249,16 @@ void MyMesh::onAdvertRecv(mesh::Packet *packet, const mesh::Identity &id, uint32 } } +void MyMesh::onGroupPacketRecv(mesh::Packet* packet) { + // The base Mesh calls this for every unseen, structurally valid group packet + // before the forwarding decision. Public-channel decryption below also + // verifies its MAC, so unrelated or forged channel packets are ignored. + if (clock_sync_mesh_edge_enabled && packet != NULL + && packet->getPayloadType() == PAYLOAD_TYPE_GRP_TXT) { + recordPublicChannelClockSample(packet); + } +} + void MyMesh::onPeerDataRecv(mesh::Packet *packet, uint8_t type, int sender_idx, const uint8_t *secret, uint8_t *data, size_t len) { int i = matching_peer_indexes[sender_idx]; diff --git a/examples/simple_repeater/MyMesh.h b/examples/simple_repeater/MyMesh.h index b587d6d47..9a5d6d324 100644 --- a/examples/simple_repeater/MyMesh.h +++ b/examples/simple_repeater/MyMesh.h @@ -567,7 +567,8 @@ protected: void onAnonDataRecv(mesh::Packet* packet, const uint8_t* secret, const mesh::Identity& sender, uint8_t* data, size_t len) override; int searchPeersByHash(const uint8_t* hash) override; void getPeerSharedSecret(uint8_t* dest_secret, int peer_idx) override; - void onAdvertRecv(mesh::Packet* packet, const mesh::Identity& id, uint32_t timestamp, const uint8_t* app_data, size_t app_data_len); + void onAdvertRecv(mesh::Packet* packet, const mesh::Identity& id, uint32_t timestamp, const uint8_t* app_data, size_t app_data_len) override; + void onGroupPacketRecv(mesh::Packet* packet) override; void onPeerDataRecv(mesh::Packet* packet, uint8_t type, int sender_idx, const uint8_t* secret, uint8_t* data, size_t len) override; bool onPeerPathRecv(mesh::Packet* packet, int sender_idx, const uint8_t* secret, uint8_t* path, uint8_t path_len, uint8_t extra_type, uint8_t* extra, uint8_t extra_len) override; void onControlDataRecv(mesh::Packet* packet) override; diff --git a/src/Mesh.cpp b/src/Mesh.cpp index 486a51199..59a1777fa 100644 --- a/src/Mesh.cpp +++ b/src/Mesh.cpp @@ -772,6 +772,7 @@ DispatcherAction Mesh::onRecvPacket(Packet* pkt) { uint8_t* macAndData = &pkt->payload[i]; // MAC + encrypted data if (!_tables->wasSeen(pkt)) { _tables->markSeen(pkt); + onGroupPacketRecv(pkt); // scan channels DB, for all matching hashes of 'channel_hash' (max 4 matches supported ATM) GroupChannel channels[4]; int num = searchChannelsByHash(&channel_hash, channels, 4); diff --git a/src/Mesh.h b/src/Mesh.h index 78d6dbf7d..dc6919a16 100644 --- a/src/Mesh.h +++ b/src/Mesh.h @@ -459,6 +459,13 @@ protected: */ virtual int searchChannelsByHash(const uint8_t* hash, GroupChannel channels[], int max_matches); + /** + * \brief A structurally valid encrypted group packet has been observed. + * Called once for each unseen packet before local channel matching and + * independently of whether the packet will be forwarded. + */ + virtual void onGroupPacketRecv(Packet* packet) { } + /** * \brief An encrypted group data packet has been received. * NOTE: the same payload can be received multiple times, via different routes diff --git a/test/test_trace_retry/test_trace_retry.cpp b/test/test_trace_retry/test_trace_retry.cpp index 945cbb0fd..b67e3f847 100644 --- a/test/test_trace_retry/test_trace_retry.cpp +++ b/test/test_trace_retry/test_trace_retry.cpp @@ -55,6 +55,7 @@ class TraceTestMesh : public mesh::Mesh { public: bool forwardFloods = false; bool floodRetriesAllowed = true; + bool groupPacketObserved = false; TraceTestMesh(mesh::Radio& radio, mesh::MillisecondClock& ms, mesh::RNG& rng, mesh::RTCClock& rtc, mesh::PacketManager& mgr, mesh::MeshTables& tables) @@ -96,6 +97,10 @@ public: bool allowFloodRetry(const mesh::Packet*) const override { return floodRetriesAllowed; } + + void onGroupPacketRecv(mesh::Packet*) override { + groupPacketObserved = true; + } }; TEST(RTCClock, UniqueSequenceCanFollowAnIntentionalBackwardCorrection) { @@ -154,6 +159,25 @@ TEST(ClockSyncPathPolicy, EdgeModeAllowsOnePath) { EXPECT_FALSE(mesh::clockSyncRequiresUniquePath(true)); } +TEST(MeshReceiveHooks, GroupPacketIsObservedWhenForwardingIsDisabled) { + TraceTestClock clock; + TraceTestRTC rtc; + TraceTestRNG rng; + TraceTestRadio radio; + TraceTestTables tables; + StaticPoolPacketManager manager(12); + TraceTestMesh node(radio, clock, rng, rtc, manager, tables); + + mesh::Packet packet; + packet.header = ROUTE_TYPE_FLOOD | (PAYLOAD_TYPE_GRP_TXT << PH_TYPE_SHIFT); + packet.payload_len = 1 + CIPHER_MAC_SIZE + CIPHER_BLOCK_SIZE; + memset(packet.payload, 0, packet.payload_len); + + ASSERT_FALSE(node.forwardFloods); + node.receivePacket(&packet); + EXPECT_TRUE(node.groupPacketObserved); +} + static mesh::Packet* makeTrace(TraceTestMesh& node, uint32_t tag, uint32_t auth, const uint8_t* route, uint8_t route_len) { mesh::Packet* packet = node.createTrace(tag, auth, 0);