diff --git a/docs/README.md b/docs/README.md index e679ea73..2ba0c625 100644 --- a/docs/README.md +++ b/docs/README.md @@ -54,6 +54,7 @@ step-by-step guides, and some predate the current implementation. - [Dual Ecash](dual-ecash-design.md) - [Hardware Signer](hardware-signer-design.md) - [Manifest Hooks](manifest-hooks-design.md) +- [Peering & Federation Trust](peering-trust-model.md) — naming/semantics of trust levels vs discovery (#134) - [kdump + rasdaemon Troubleshooting](kdump-rasdaemon-design.md) — post-mortem and hardware-error capture on nodes (#144) - [Meshroller Integration](meshroller-integration-design.md) - [Nostr Git Source Hosting](nostr-git-source-hosting.md) diff --git a/docs/peering-trust-model.md b/docs/peering-trust-model.md new file mode 100644 index 00000000..473e1d3a --- /dev/null +++ b/docs/peering-trust-model.md @@ -0,0 +1,47 @@ +# Peering & Federation Trust — naming and semantics + +Status: TERMINOLOGY SET — records what the code does today (#134). +Deferred: the "don't advertise my peers" opt-out (see §Open questions). + +The code is the authority; this doc gives names to the four concepts that +issue #134 showed get conflated in conversation. Where a name changed in +user-facing discussion, the term below is the one to use everywhere +(UI copy, docs, issues, reviews). + +## The four concepts + +| Term (use this) | What it is | Where it lives | +|---|---|---| +| **Trusted peer** | A node THIS operator invited and verified: bilateral DID challenge over an out-of-band invite code (`federation::sync`, ADR-007). The only level that grants full access. | `TrustLevel::Trusted`, set via `TrustSource::Invite` or `Manual` | +| **Discovered peer** | A peer we learned about from a Trusted peer's advertised list — the transitive merge. Never better than **Observer**: `TRUST IS NOT TRANSITIVE` (sync.rs guard). | `TrustLevel::Observer`, `TrustSource::TransitiveMerge` | +| **Routing hint** | What a Discovered peer actually contributes: an address that lets us route directly over FIPS without a second invite hop. Reachability, not trust. | Observer-level sync + FIPS endpoint records | +| **Peer advertisement** | The act of a Trusted peer sharing its own peer list during sync. This is the *mechanism* #134 observed — a feature, not a leak. | sync.rs merge path | + +## The two rules that make it sound + +1. **Trust requires an operator decision, always traceable.** Every trust + level carries a `TrustSource`. Only a minted invite (or an explicit + operator change) can produce `Trusted`; uninvited joins and transitive + merges are hard-capped at `Observer` — a peer can never expand our + trusted set on its own authority. +2. **Discovery is transitive; trust is not.** Seeing more nodes through a + Trusted peer is expected and useful (routing). Granting those nodes + anything is an operator action, never automatic. + +## Why a Trusted peer advertising its list is by design + +Without advertisement, every new node needs a direct invite from every node +that wants to reach it — the invite graph becomes the routing bottleneck +AdDR-007 set out to remove. With it, one invite makes a node *reachable* to +the trusted set (routing hints), while *authorization* still requires each +operator's own invite. Reachability ≠ access. + +## Open questions (deferred, tracked in #134) + +- **"Don't advertise my peers"** — an operator privacy toggle suppressing + peer advertisement during sync. Small code change, real design questions: + it hides peers who may WANT discovery, and it degrades the routing benefit + for every node trusting you. Needs a product decision, not just code. +- **Tier vocabulary in the UI** — whether to surface "Observer" as such or + a friendlier term ("Connected"/"Visible") — part of the TODO.md peering + trust-model item.