feat: foreign advert detection — alert when out-of-region nodes appear in local mesh #730

Problem

When two regional MeshCore meshes get bridged (intentionally or accidentally), observers in one region start seeing adverts from nodes with GPS coordinates in a completely different region. Today, the ingestor silently drops these out-of-region adverts via NodePassesGeoFilter() (main.go L311). This means:

1. No visibility — operators don't know bridging is happening
2. Data loss — foreign adverts are discarded, not logged
3. No forensics — can't determine when bridging started, which nodes are entry points, or whether it's intentional

Operators need to know when this is happening and which nodes are the bridge entry points.

Current Behavior

• internal/geofilter/ provides PassesFilter() — polygon + buffer zone check
• Ingestor calls NodePassesGeoFilter() on every ADVERT with GPS
• If the node is outside the configured region → silent return, no log, no counter, no record
• Nodes without GPS (0,0) pass through (correct — can't classify them)

Proposed Feature

M1: Detect and log foreign adverts

Scope: Ingestor + API. No frontend changes.

At ingest time, when an ADVERT has GPS and fails the geofilter:

• Log it: log.Printf("MQTT [%s] foreign advert: node=%s lat=%.4f lon=%.4f", tag, pubkey, lat, lon)
• Increment a per-node counter in a new foreign_adverts table:

  CREATE TABLE foreign_adverts (
    pubkey TEXT NOT NULL,
    name TEXT,
    lat REAL,
    lon REAL,
    observer_id TEXT NOT NULL,
    first_seen DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_seen DATETIME DEFAULT CURRENT_TIMESTAMP,
    count INTEGER DEFAULT 1,
    UNIQUE(pubkey, observer_id)
  );

• Do NOT drop the advert — insert it into the normal pipeline too, but flag it. This preserves data for forensics. (The current silent drop is the wrong behavior for an analytics tool.)
• New API endpoint: GET /api/analytics/foreign-adverts — returns list of foreign nodes with counts, locations, observer IDs, first/last seen
• Query params: ?hours=24 (default 24h window), ?observer=<id> (filter by observer)

M2: Dashboard card + map overlay

Scope: Frontend analytics page + map.

Analytics page — new "Foreign Adverts" card:

• Count of foreign adverts in last 24h
• Table: node name, pubkey (truncated), GPS, observer(s) that heard it, count, first/last seen
• Timeline sparkline showing when foreign adverts started appearing (detect bridging onset)
• Link to map view filtered to foreign nodes

Map overlay:

• Foreign nodes shown with distinctive marker (red circle with warning icon or pulsing red dot)
• Different from normal out-of-region markers — these are nodes that are actively being heard by local observers
• Tooltip: "Foreign node — heard by [observer] at [time], GPS: [lat, lon]"

M3: Smart alerting + bridge detection

Scope: Analytics engine + optional webhook/notification.

Baseline tracking:

• Track normal out-of-region noise (GPS jitter on border nodes near the polygon edge)
• Configurable buffer zone already exists (BufferKm in geofilter config) — nodes within buffer are NOT foreign

Alert logic:

• Threshold: X foreign adverts from Y unique nodes in Z hours (all configurable)
• Distinguish between:
  • Single node roaming: one node briefly appears outside region → probably moved, low priority
  • Systematic bridge: multiple foreign nodes from a consistent distant region → active bridge, high priority
• Bridge entry point detection: cross-reference foreign node pubkeys against path bytes in relayed packets. If a foreign node appears in paths of packets relayed through local mesh → active bridge relay, not just leaked adverts

Notification:

• Optional webhook URL in config for bridge detection alerts
• Include: foreign node count, estimated bridge region (cluster foreign GPS coords), affected observers, onset time

Design Decisions to Resolve

Protocol Notes

Per MeshCore firmware behavior:

• from_node / originator pubkey is only available on ADVERT packets — this feature only applies to adverts, which is correct
• Adverts include GPS when the node has a fix (HasLocation flag in decoded payload)
• Repeaters flood adverts every 12-24h; companions advertise on app open — foreign advert frequency indicates bridge persistence
• Path bytes in forwarded adverts show the relay chain — path[last] is closest to the observer, which helps identify the local-side bridge node

Risk Considerations

• Fat tail scenario: A misconfigured bridge floods thousands of foreign adverts per hour. M1's foreign_adverts table must have reasonable eviction (e.g., keep last 7 days, configurable). Without eviction, SQLite bloats silently.
• Silent failure today: The current silent return is itself a silent risk — bridges happen with zero indication. This feature converts an invisible risk into an observable one.
• False positive management: Border nodes with GPS jitter will trigger if buffer zone is too small. M3's baseline tracking prevents alert fatigue.
• Backward compatibility: M1 changes ingestor behavior (no longer drops foreign adverts). Deployments that rely on the drop behavior need a config flag: "foreign_adverts": { "mode": "flag" | "drop" }, defaulting to "flag".

Milestones

• M1 — Low effort, high value. Can ship independently.
• M2 — Medium effort, depends on M1 API.
• M3 — Higher effort, depends on M1 data accumulation for baseline.