Rename signer-proven -> key-proven for broadened provenance predicate

Address PR #11119 review: the copyPublicKey()/copyUser() out-parameter and
the cache-path replay gate now report entry->keyProven() (XEdDSA-signed OR
manually verified), so the "signerProven" name and "signer-proven" comments
were misleading. Rename the public out-param to keyProven, the local
cachedKeySignerProven to cachedKeyProven, and update coupled callers, log
strings, docs headings, and comments to say "key-proven".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: NomDeTom

docs/node_info_stores.md

@@ -154,7 +154,7 @@ independent of `hasFullUser`. Because the re-mark is only hourly, hook-driven ad
 an hour.
 
 **Retention:** no timed eviction. Slots die only by LRU displacement on insert, ranked by
-trust tiers - members and signer-proven keys are stickiest; the seeding pass additionally
+trust tiers - members and key-proven keys are stickiest; the seeding pass additionally
 refuses to churn one member out for another (`spareMembers`).
 
 **Key-commit funnel:** every path that writes a remote key into the hot store must route

docs/traffic_management_module.md

@@ -111,7 +111,7 @@ and the request is left to propagate normally:
 4. **Staleness gate (6 h)**: never vouch for a node not genuinely _heard_ within the serve
    window. Only a real observed frame stamps the recency bit - seeding and write-through are
    knowledge, not observation, so a silent node can never look alive to this path.
-5. **Signer-provenance gate** (`TMM_NODEINFO_REPLAY_SIGNED_GATE`, default on): vouch only for
+5. **Key-provenance gate** (`TMM_NODEINFO_REPLAY_SIGNED_GATE`, default on): vouch only for
    an identity whose key is proven - XEdDSA-verified (directly or inherited from NodeDB) **or**
    manually verified out-of-band. Both paths honour both channels: the cache path via
    `keyProven()`, the NodeDB fallback path via `HAS_XEDDSA_SIGNED | IS_KEY_MANUALLY_VERIFIED`. A

src/mesh/NodeDB.cpp

@@ -3773,7 +3773,7 @@ bool NodeDB::copyPublicKey(NodeNum n, meshtastic_NodeInfoLite_public_key_t &out)
 #if HAS_TRAFFIC_MANAGEMENT
     // Last resort: a key the TrafficManagement NodeInfo cache learned from an observed frame
     // for a node no longer in either NodeDB tier. This extends the pool of peers we can
-    // encrypt to. Keys here may be trust-on-first-use (see copyPublicKey's signerProven), the
+    // encrypt to. Keys here may be trust-on-first-use (see copyPublicKey's keyProven), the
     // same first-contact trust NodeDB itself applies via updateUser().
     if (trafficManagementModule && trafficManagementModule->copyPublicKey(n, out.bytes)) {
         out.size = 32;
@@ -3788,10 +3788,10 @@ bool NodeDB::copyPublicKeyForDecrypt(NodeNum n, meshtastic_NodeInfoLite_public_k
     if (copyPublicKeyAuthoritative(n, out))
         return true;
 #if HAS_TRAFFIC_MANAGEMENT
-    // A cold-tier cache key backs an authenticated decrypt only when signer-proven; unverified TOFU
+    // A cold-tier cache key backs an authenticated decrypt only when key-proven; unverified TOFU
     // cache keys must not. Outbound encryption still uses the opportunistic copyPublicKey().
-    bool signerProven = false;
-    if (trafficManagementModule && trafficManagementModule->copyPublicKey(n, out.bytes, &signerProven) && signerProven) {
+    bool keyProven = false;
+    if (trafficManagementModule && trafficManagementModule->copyPublicKey(n, out.bytes, &keyProven) && keyProven) {
         out.size = 32;
         return true;
     }

src/mesh/NodeDB.h

@@ -365,7 +365,7 @@ class NodeDB
     bool copyPublicKeyAuthoritative(NodeNum n, meshtastic_NodeInfoLite_public_key_t &out);
 
     /// Key for the inbound-decrypt path: authoritative (hot/warm), or a cold-tier cache key only when
-    /// it is signer-proven. Keeps unverified TOFU cache keys from backing pki_encrypted attribution.
+    /// it is key-proven. Keeps unverified TOFU cache keys from backing pki_encrypted attribution.
     bool copyPublicKeyForDecrypt(NodeNum n, meshtastic_NodeInfoLite_public_key_t &out);
 
     /// True if n is a known XEdDSA signer for exactly `key32` (hot signed bitfield or warm

src/mesh/Router.cpp

@@ -818,7 +818,7 @@ DecodeState perhapsDecode(meshtastic_MeshPacket *p)
         // Resolve the sender's key only for actual PKI-decrypt candidates, not every encrypted channel
         // packet: copyPublicKeyForDecrypt() can fall through to a linear scan of TrafficManagement's large
         // NodeInfo cache. It returns authoritative keys (hot/warm), or a cold-tier cache key only when it is
-        // signer-proven - an unverified TOFU cache key must not back authenticated (pki_encrypted, p->from)
+        // key-proven - an unverified TOFU cache key must not back authenticated (pki_encrypted, p->from)
         // DM attribution.
         meshtastic_NodeInfoLite_public_key_t remotePublic = {0, {0}};
         bool haveRemoteKey = nodeDB->copyPublicKeyForDecrypt(p->from, remotePublic);

src/modules/TrafficManagementModule.cpp

@@ -439,7 +439,7 @@ const TrafficManagementModule::NodeInfoPayloadEntry *TrafficManagementModule::fi
 
 /// Find or create a NodeInfo payload entry. Victim selection is trust-tiered so the cache
 /// doubles as a pubkey pool: NodeDB membership outranks key trust, then keyless < TOFU key <
-/// signer-proven key; within a tier the oldest observation loses (never-observed = oldest).
+/// key-proven key; within a tier the oldest observation loses (never-observed = oldest).
 TrafficManagementModule::NodeInfoPayloadEntry *
 TrafficManagementModule::findOrCreateNodeInfoEntry(NodeNum node, bool *usedEmptySlot, bool spareMembers)
 {
@@ -466,7 +466,7 @@ TrafficManagementModule::findOrCreateNodeInfoEntry(NodeNum node, bool *usedEmpty
         }
         if (empty)
             continue; // an empty slot beats any victim; stop scoring
-        // Eviction tier (lower loses first): 0 keyless, 1 TOFU key, 2 signer-proven key;
+        // Eviction tier (lower loses first): 0 keyless, 1 TOFU key, 2 key-proven key;
         // +3 for NodeDB members - never shed a NodeDB-tier identity over a stranger.
         const uint8_t tier = static_cast<uint8_t>(((entry.user.public_key.size != 32) ? 0 : (entry.keyProven() ? 2 : 1)) +
                                                   (entry.isMember ? 3 : 0));
@@ -724,7 +724,7 @@ void TrafficManagementModule::onNodeKeyCommitted(NodeNum node, const uint8_t key
     // hasObserved/obsTick untouched: a key commit is knowledge, not an observation.
 }
 
-bool TrafficManagementModule::copyPublicKey(NodeNum node, uint8_t out[32], bool *signerProven) const
+bool TrafficManagementModule::copyPublicKey(NodeNum node, uint8_t out[32], bool *keyProven) const
 {
     // Same enable gate as the write-through hooks and maintenance: a disabled module stops
     // updating and sweeping the cache, so its frozen contents must not keep feeding PKI key
@@ -740,12 +740,12 @@ bool TrafficManagementModule::copyPublicKey(NodeNum node, uint8_t out[32], bool
         return false;
 
     memcpy(out, entry->user.public_key.bytes, 32);
-    if (signerProven)
-        *signerProven = entry->keyProven();
+    if (keyProven)
+        *keyProven = entry->keyProven();
     return true;
 }
 
-bool TrafficManagementModule::copyUser(NodeNum node, meshtastic_User &out, bool *signerProven) const
+bool TrafficManagementModule::copyUser(NodeNum node, meshtastic_User &out, bool *keyProven) const
 {
     // Enable gate, as in copyPublicKey(): a disabled module must not feed name rehydration
     // from frozen cache contents once its maintenance/write-through have stopped.
@@ -762,8 +762,8 @@ bool TrafficManagementModule::copyUser(NodeNum node, meshtastic_User &out, bool
         return false;
 
     out = entry->user;
-    if (signerProven)
-        *signerProven = entry->keyProven();
+    if (keyProven)
+        *keyProven = entry->keyProven();
     return true;
 }
 
@@ -1432,7 +1432,7 @@ bool TrafficManagementModule::shouldRespondToNodeInfo(const meshtastic_MeshPacke
     uint8_t cachedObsTick = 0;
     // Signer-proven provenance of the cached key, consumed by the replay gate below
     // (maybe_unused: read only when TMM_NODEINFO_REPLAY_SIGNED_GATE is compiled in).
-    [[maybe_unused]] bool cachedKeySignerProven = false;
+    [[maybe_unused]] bool cachedKeyProven = false;
     // True once we commit to answering from the NodeDB fallback (no NodeInfo cache) path. The
     // response throttle no longer distinguishes the paths - the per-requester/per-target RAM
     // tables cover both - but the replay gate below still keys off it.
@@ -1449,7 +1449,7 @@ bool TrafficManagementModule::shouldRespondToNodeInfo(const meshtastic_MeshPacke
             cachedSourceChannel = entry->sourceChannel;
             cachedHasObserved = entry->hasObserved;
             cachedObsTick = entry->obsTick;
-            cachedKeySignerProven = entry->keyProven();
+            cachedKeyProven = entry->keyProven();
         }
     }
 
@@ -1500,10 +1500,10 @@ bool TrafficManagementModule::shouldRespondToNodeInfo(const meshtastic_MeshPacke
     }
 
 #if TMM_NODEINFO_REPLAY_SIGNED_GATE
-    // Replay provenance gate (cache path): only spoof a reply for a signer-proven cached key.
+    // Replay provenance gate (cache path): only spoof a reply for a key-proven cached key.
     // usedFallback entries were already gated above. See TMM_NODEINFO_REPLAY_REQUIRE_SIGNED.
-    if (!usedFallback && !cachedKeySignerProven) {
-        TM_LOG_DEBUG("NodeInfo cache entry for 0x%08x not signer-proven, not responding", p->to);
+    if (!usedFallback && !cachedKeyProven) {
+        TM_LOG_DEBUG("NodeInfo cache entry for 0x%08x not key-proven, not responding", p->to);
         return false;
     }
 #endif

src/modules/TrafficManagementModule.h

@@ -9,7 +9,7 @@
 #if HAS_TRAFFIC_MANAGEMENT
 
 // Replay provenance gate: when 1 (default), direct responses are spoofed only for nodes whose
-// cached key is signer-proven (XEdDSA-verified), not for trust-on-first-use identities.
+// cached key is key-proven (XEdDSA-signed or manually verified), not for trust-on-first-use identities.
 // Define as 0 to also serve fresh TOFU-only nodes; bypassed entirely when PKI is excluded.
 #ifndef TMM_NODEINFO_REPLAY_REQUIRE_SIGNED
 #define TMM_NODEINFO_REPLAY_REQUIRE_SIGNED 1
@@ -65,14 +65,14 @@ class TrafficManagementModule : public MeshModule, private concurrency::OSThread
     bool preloadNextHopsFromNodeDB();
 
     /// Last-resort key source for NodeDB::copyPublicKey() after the hot and warm tiers miss.
-    /// Copies the 32-byte key for `node` into out[32]; `signerProven` (optional) reports whether
-    /// the key was XEdDSA-verified vs trust-on-first-use. Thread-safe.
-    bool copyPublicKey(NodeNum node, uint8_t out[32], bool *signerProven = nullptr) const;
+    /// Copies the 32-byte key for `node` into out[32]; `keyProven` (optional) reports whether
+    /// the key is proven (XEdDSA-signed or manually verified) vs trust-on-first-use. Thread-safe.
+    bool copyPublicKey(NodeNum node, uint8_t out[32], bool *keyProven = nullptr) const;
 
     /// Copy the full cached User for `node` (used by NodeDB to rehydrate a re-admitted node's
     /// name - the warm tier keeps keys but not names). False on miss or key-only records.
-    /// `signerProven` (optional) reports the cached key's provenance. Thread-safe.
-    bool copyUser(NodeNum node, meshtastic_User &out, bool *signerProven = nullptr) const;
+    /// `keyProven` (optional) reports the cached key's provenance. Thread-safe.
+    bool copyUser(NodeNum node, meshtastic_User &out, bool *keyProven = nullptr) const;
 
     /// Write-through hook from NodeDB::updateUser(): upsert the committed identity immediately
     /// (the reconcile sweep remains the backstop). NodeDB's key is authoritative, but a keyless
@@ -125,7 +125,7 @@ class TrafficManagementModule : public MeshModule, private concurrency::OSThread
     /// (distinguishes "not tracked" from CLIENT == 0).
     int peekCachedRole(NodeNum node);
 
-    /// Test hook: force a cached NodeInfo entry's key to signer-proven so replay-gate tests
+    /// Test hook: force a cached NodeInfo entry's key to XEdDSA-signed so replay-gate tests
     /// can skip a full XEdDSA verification. No-op if absent.
     void markKeyXeddsaSignedForTest(NodeNum node);
 
@@ -285,7 +285,7 @@ class TrafficManagementModule : public MeshModule, private concurrency::OSThread
         // stickiest under LRU; the bit is the keep-alive (no TTL).
         uint8_t isMember : 1;
 
-        // Possession proven by either channel - the "signer-proven" predicate the replay gate,
+        // Possession proven by either channel - the "key-proven" predicate the replay gate,
         // eviction tiering, and NodeDB pubkey-pool callers consume.
         bool keyProven() const { return keyXeddsaSigned || keyManuallyVerified; }
     };