archipelago
9df580bf2b
Gives stable names to what issue #134 showed gets conflated: Trusted peer (invite-verified, operator decision), Discovered peer (learned from a Trusted peer's advertisement, hard-capped at Observer — TRUST IS NOT TRANSITIVE), Routing hint (what a Discovered peer actually contributes: reachability, not trust), and Peer advertisement (the mechanism itself, a feature not a leak). Records the two rules that make the model sound (trust requires a traceable operator decision; discovery is transitive, trust is not), why advertisement exists (one invite makes a node reachable to the trusted set without granting anything), and the deferred open questions: the 'don't advertise my peers' privacy toggle and UI tier vocabulary.
2.9 KiB
2.9 KiB
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
- Trust requires an operator decision, always traceable. Every trust
level carries a
TrustSource. Only a minted invite (or an explicit operator change) can produceTrusted; uninvited joins and transitive merges are hard-capped atObserver— a peer can never expand our trusted set on its own authority. - 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.