From 4939a769ff53746ecf2ecabe6f843fc80e405c6e Mon Sep 17 00:00:00 2001 From: Strycher Date: Wed, 1 Jul 2026 00:52:23 -0400 Subject: [PATCH] docs(#164): block/ignore design-of-record contract (app-local + fw offload) Two-layer, app-authoritative design: Layer 1 app-local block (DMs+adverts by key, channel name-key resolution, per-channel mute); Layer 2 capability-gated Offband firmware offload [TO LOCK with PearlMeadow, meshcore-firmware]. Feature #164 / Epic A #165 / Epic B #166. Co-Authored-By: Claude Opus 4.8 --- docs/architecture/block-contract-as-built.md | 175 +++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 docs/architecture/block-contract-as-built.md diff --git a/docs/architecture/block-contract-as-built.md b/docs/architecture/block-contract-as-built.md new file mode 100644 index 0000000..ee41132 --- /dev/null +++ b/docs/architecture/block-contract-as-built.md @@ -0,0 +1,175 @@ +# Block / Ignore — App ↔ Firmware Contract + +**Status:** Proposed contract (design-of-record from the 2026-07 brainstorm). **Not yet built** — the +`-as-built` filename is the intended home for this doc; it will be reconciled to actual behavior as +Epic A / Epic B land. Sections marked **[TO LOCK]** require agreement with the firmware side +(`OffbandMesh/meshcore-firmware`, agent PearlMeadow — which **already has a block feature**) before +Layer 2 is coded. + +**Owners:** app = meshcore-client (Offband); firmware = meshcore-firmware (Offband). +**Tracking:** Feature #164 → Epic A (app-local) #165 / Epic B (firmware offload) #166. +**Related:** device-config-parity Feature #7; firmware companion-API config command. + +--- + +## 1. Problem + +A single misbehaving node floods the mesh with **adverts, pings, DMs, and Public-channel posts**. +Users want to *ignore* that node so they stop seeing its traffic. Repeater/firmware-wide rate limiting +(`flood.max`, `flood.advert.interval`, region scoping) is a blunt, network-operator-level tool and is +explicitly **out of scope** here. This contract covers a **per-user, per-node block**. + +## 2. Reality constraints (verified against the code + upstream) + +1. **DMs and adverts carry the sender's public key** → blockable by identity, reliably. +2. **Channel/Public messages carry NO public key.** `ChannelMessage.senderKey` is always `null` + (`lib/models/channel_message.dart`); the "sender" is a plaintext `"name: msg"` prefix. Public is a + shared-PSK channel (`Channel.publicChannelPsk`). So channel senders can only be matched by + **claimed name**, or by **resolving that name to a known contact's key**. +3. **There is no block primitive in stock MeshCore** — not in the companion protocol command set + (tops out at `cmdSetPathHashMode = 61`, no block), not on the radio, not in the official app + (its "Block Sender" is app-local UI filtering, same as MeshMonitor's "Ignored Nodes"). + → **Cross-app portability of a block is not achievable today by anyone.** A firmware-stored block + is only meaningful as an **Offband-fork extension**; the stock app will not honor it. +4. **`cmdRemoveContact` (15) is not a block** — the firmware re-adds the contact on its next advert. +5. **Contact names track the pubkey.** On each advert, `_handleContactAdvert` + (`lib/connector/meshcore_connector.dart`) replaces the stored contact with fresh advert data, + including the current name (only the user path-override is preserved). This is what lets + name→key resolution self-heal across renames (§5). + +## 3. Core principle — two layers, app-authoritative, graceful degradation + +``` +Layer 1 App-local block ── always on, any firmware. SOURCE OF TRUTH. +Layer 2 Firmware offload ── Offband radios only, capability-gated. Best-effort mirror. +``` + +- **Layer 1** works identically on stock MeshCore and Offband firmware — full parity with the + official app's behavior. +- **Layer 2** is an optional accelerator: on an Offband radio that advertises block capability, the + app pushes the block down so the **radio drops that node's traffic before it reaches the app** + (saves airtime surfacing / battery; persists across app reinstalls). +- The app never depends on Layer 2. If the firmware can't do it, Layer 1 still fully hides the node. + +## 4. Layer 1 — app-local block (data model) + +New `BlockStore extends ChangeNotifier`, persisted via `PrefsManager`, **scoped by the connected +device key** (first 10 hex chars — same pattern as `contact_settings_store`). Provider-wired alongside +the existing services. + +Two sets: + +| Set | Key type | Covers | +|---|---|---| +| `blockedKeys` | public-key hex | DMs, adverts, and channel posts that resolve to a known contact | +| `blockedNames` | lowercased display-name string | channel posts from senders with no matching contact (fallback) | + +API: `isBlocked(keyHex)`, `isNameBlocked(name)`, `block(keyHex)`, `unblock(keyHex)`, +`blockName(name)`, `unblockName(name)`, plus read accessors for the management UI. + +### Where blocks take effect (app side) + +| Surface | Rule | +|---|---| +| Incoming DM | drop from thread + suppress notification when `senderKey ∈ blockedKeys` | +| Advert | in `_handleContactAdvert`: suppress new-advert notification; exclude key from Contacts + Discovery lists | +| Contacts / Discovery lists | filter out `blockedKeys` | +| Channel message | hide when it resolves to a blocked key (§5) OR `senderName.toLowerCase() ∈ blockedNames`, OR the channel is muted (§6) | + +Blocking never deletes stored history; it hides. Unblock restores visibility. + +## 5. Channel handling — name ↔ key resolution (the important part) + +Channel packets are anonymous by protocol. To make channel blocking as strong as possible: + +**At display:** a channel message is hidden if +`resolveContactByName(senderName)?.publicKeyHex ∈ blockedKeys` **OR** +`senderName.toLowerCase() ∈ blockedNames`. + +**Long-press "Block sender" in a channel:** +- **Name resolves to a contact** → add that contact's **public key** to `blockedKeys` (this unifies the + block: the node vanishes from the channel *and* DMs *and* adverts in one action). Also record the + name in `blockedNames` as belt-and-suspenders. +- **No matching contact** → add the **name** only to `blockedNames`, surfaced with a clear + "name-only — can be evaded by renaming" note. + +**Why this resists rename evasion:** when the node renames, its next advert updates its contact's name +under the same pubkey (§2.5), so name→key resolution re-links automatically. Because this class of +abuser floods adverts, the link stays fresh in practice. + +**Honest limitation:** if the node renames **and** the app never receives a linking advert (it goes +silent on adverts but keeps posting to Public), that specific post is genuinely unattributable — no +identity exists in the packet. Residual recourse is name-pattern matching or muting the channel (§6). +This is a protocol limit, not an app defect. + +## 6. Per-channel mute (in scope, Layer 1) + +Independent of per-sender blocking: a user can **mute an entire channel** (e.g. a noisy Public) so it +stops generating notifications/unread badges and is de-emphasized, regardless of who is posting. This +is the blunt-but-reliable answer to the unattributable-poster limitation in §5. + +- Stored in the `BlockStore` (or the existing channel-settings store) as a set of muted channel + indices / PSK identities, scoped by device key. +- Muting suppresses notifications + unread counts for that channel; messages remain readable when the + channel is opened (mute ≠ leave). +- Toggle from the channel header/overflow and from the channel list (long-press). + +## 7. Layer 2 — firmware offload contract **[TO LOCK with PearlMeadow]** + +Mirrors the existing `0xC1`/`offband_caps` capability pattern (`supportsOffbandGps` in the connector). +The firmware side **already has a block feature** — this section aligns the app to *its* real wire +format rather than inventing one. + +- **Capability bit:** a `block` bit in the `offband_caps` bitfield in the device-info reply. + App exposes `bool get supportsOffbandBlock => firmwareSupportsOffbandBlock(_offbandCaps);`. + Stock firmware omits the byte → Layer 2 silently disabled. **[TO LOCK]** exact bit value. +- **Transport / representation [TO LOCK]:** how the radio stores + exchanges the block list + (paginated `START → ITEM×N → END` list under a `block.*` namespace, vs a dedicated add/remove + command with a sub-type byte). Adopt PearlMeadow's existing scheme. +- **Firmware behavior [TO LOCK]:** what the radio does with a blocked key (suppress delivery of that + node's DMs/adverts to the companion; MAY drop relay on repeater builds). Record PearlMeadow's + actual semantics here. +- **Capability-gated + additive** — stock MeshCore clients/firmware unaffected. + +## 8. Sync model + +- **App is authoritative.** `blockedKeys` in the app is the source of truth. +- On `block()/unblock()`: write local first; if `supportsOffbandBlock`, push the change to firmware. +- On connect to a capable radio: **reconcile** by pushing the current local block set down + (mirrors `_reconcileGpsPolling`, tolerant of frame-arrival order). +- The app does **not** read firmware→app blocks; one-way push keeps a single source of truth. + **[TO CONFIRM with PearlMeadow]** whether their existing feature expects a read-back / two-way merge. + +## 9. Error visibility (per DifferentWire error-visibility rules) + +- Firmware push failure surfaces a **persistent** snackbar (not a 4s flash); the local block still + applies. Never swallow the error. +- All block/unblock/mute actions log with context (key/channel, surface, firmware-push result). + +## 10. UX surfaces + +- **Entry points:** contact context menu, chat overflow menu, Discovery item, channel message + long-press (name-based, labeled), channel header/list (mute). +- **Management:** Settings → **Blocked** — list of entries (name if known + short pubkey), unblock + action, muted-channels list, and an indicator of whether firmware-offload is active on the current + radio. + +## 11. Scope + +**In scope (this contract):** app-local block of DMs + adverts by key; channel block via name↔key +resolution + name fallback; **per-channel mute**; capability-gated firmware offload. + +**Deferred / out of scope (tracked separately, not silently dropped):** +- Content filtering (bullying/profanity/kids-mode) — explicitly future (original request item #3). +- Repeater / network-wide rate limiting — operator-level. + +## 12. Decomposition + +| Epic | Scope | Depends on | +|---|---|---| +| **A — app-local block** (#165) | `BlockStore`, filter points, name↔key channel resolution, per-channel mute, entry points, management UI | none — ships standalone | +| **B — firmware offload** (#166) | `offband_caps` block bit, config-command block list, sync/reconcile, capability UI | firmware wire contract §7 **[TO LOCK]** with PearlMeadow | + +**Open items to lock before Epic B codes:** §7 representation (list vs command), firmware suppression +semantics, capability-bit value, and §8 read-back expectation. Coordinate with PearlMeadow +(`OffbandMesh/meshcore-firmware`); record decisions back into §7–§8 of this file.