48 lines
2.9 KiB
Markdown
48 lines
2.9 KiB
Markdown
|
# 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.
|