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.
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.
|