peerspeak/docs/contacts-plan.md

Friends-first contacts + ephemeral rooms (W7, redesigned) — plan / scope contract

Status: SCOPED, not started. Model locked 2026-06-15 after an extended design session with the user. This is the scope contract; update it as phases land. Source: wishlist W7.

This doc supersedes two earlier drafts: (1) the heavyweight "port pixelpass's always-on control plane + reachable identity + n0 discovery" cut, and (2) the room-centric "durable named rooms" cut. Both are folded into the bottom section "Earlier directions (superseded)" with the reasons. The model below is the one to build.

The model in one paragraph

The friends list (stable node IDs) is the durable anchor; rooms are ephemeral cosmetic labels. You don't join a persistent room — you reach your friends and label the gathering ("HangOut"). Identity is persistent so a friend's node ID never changes. Presence is best-effort and private-by-default: your peerspeak, while open, listens for pings only from friends and answers from your saved address — no presence beacon. Reliability across network changes is opt-in per person (voluntary discovery), and there's a universal floor that always works regardless: a hand-shared member-issued ticket. Out-of-band coordination ("want to get on peerspeak?") stays on Signal/Telegram — peerspeak is not a messenger.

Locked design decisions (user, 2026-06-15)

1. Persistent identity = default foundation. Load/create a stable SecretKey at a key file instead of generate() each launch (core/mod.rs:421). Node ID stable across launches. iroh doesn't force rolling IDs; today's behaviour is an unrevisited default.
2. Settings "Regenerate identity" control (confirm + warn) for a deliberate unlink / fresh start. Breaks others' saved reachability to you until re-exchange.
3. Friends list keyed by node ID (+ a locally editable display name). Fully doable now that IDs are stable.
4. Rooms are ephemeral cosmetic labels, not addressable durable entities. A room is a gathering with a name tag shared between clients for display; the underlying gossip topic is per-session, not a saved/named identity. (Drops name-derived topics, favorite-room persistence, empty-room reachability — all the room-centric complexity.)
5. Recents list = local-only saved entries (cosmetic room name + the session's topic + the member addresses seen). Purely local UI state.
6. Presence via a friends-only idle listener. While the app is open, peerspeak answers pings only from node IDs on your friends list (authenticated via remote_id()); everyone else is silently dropped. No DNS presence beacon by default. This is the one new always-on-while-open primitive, deliberately accepted because it's whitelisted + beacon-free (it avoids the stranger-spam and phone-home costs that sank the heavyweight design).
7. Presence control axis: invisible ↔ normal ↔ discoverable.
   • invisible — don't answer pings at all.
   • normal (default) — answer friends-only, from saved address; no beacon.
   • discoverable — opt-in publish to n0 DNS so friends can find you after a network change. Default OFF. Toggle in Settings and a shortcut in the friends list. Ideally time-boxed ("available for 30 min").
8. Discovery is asymmetric — only the mover publishes. To find a friend who moved networks, that friend enables discovery (publishes); everyone else just looks them up (a DNS query, no publishing). So the privacy cost is localized to the one person who needs the reliability; stationary friends change nothing and keep no standing presence record.
9. Saved addresses auto-heal silently. Every successful connection to a friend carries their current PeerState.addr over gossip; peerspeak compares and re-saves it with no prompt. So for friends you actually talk to, saved addresses stay current on their own. (Opportunistic: only updates while connected — a move made while you're apart isn't seen until the next shared session, a ticket, or discovery.)
10. Universal floor: hand-shared member-issued tickets always work. Whatever auto-detection / discovery do, a friend can always mint a fresh ticket from their current address and drop it in Signal; you bootstrap off it from any network, any privacy setting, no beacon. Nobody is ever stuck — worst case is "paste one link."

Core primitives to build

P1 — Persistent identity (+ regenerate) — Small, foundational

Foundation DONE (d157d78, 2026-06-15): src/identity.rs (load_or_create / regenerate / save over a 0600 hex key file at ~/.config/peerspeak/identity.key, atomic write, malformed = hard error, path-injectable fs seam + 8 unit tests incl. create/persist/regenerate/perms). Core loop now loads the stable key instead of generate() (falls back to ephemeral only if the file can't be read/written). The key file is raw hex (a secret, not structured config — JSON/TOML only matters for the friends store). 238 lib tests green, clippy clean, release builds. Remaining in P1:

• Settings "Regenerate identity" control (confirm + warn) — regenerate() exists; UI + a CoreCommand that rebuilds the live endpoint with the new key still to wire.
• Visual warning when the key can't be read/written (user, 2026-06-15). Today the ephemeral fallback only logs — it must surface a persistent UI indicator, because running unsaved is a real degraded state (your id won't survive the next launch → friends stop recognising you). Plan: a dedicated UiEvent (IdentityNotPersisted(reason), distinct from the transient Error → status_message), an identity_degraded: Option<String> flag in app state, and a standing badge + a fuller explainer in the identity Settings section ("Identity couldn't be saved to ~/.config/peerspeak/identity.key — friends won't recognise you next launch; check disk/permissions"). Build alongside the regenerate UI slice (same identity Settings section + CoreCommand path).
• Spike: verify same-relay reachability by node ID without discovery on iroh = 1.0.0-rc.0 (a saved EndpointAddr should resolve while the peer stays on the same relay). Underpins the whole presence story; do during 2-machine testing.

P2 — Friends list — Small

Persist friends = { node_id, display_name, last_known_addr } (JSON store, atomic write — pattern from pixelpass friends.rs). Add-from-room (you met them in a gathering), local rename. No handshake required for the basic list (it's a local address book), though a lightweight mutual-add is optional polish.

P3 — Member-issued / multi-bootstrap tickets — Small (the ticket mechanism)

Let any current member mint a ticket from { their live addr, the session topic } (both already in hand). Pre-exists: the type PeerSpeakTicket and RoomState::join already takes extra_bootstrap: Vec<EndpointAddr> (A8). Optionally bundle several present members for redundancy. Also tighten ticket encoding (drop JSON/base64 fat, index the relay URL — lossless, ~halves the string).

P4 — Friends-only idle listener + presence — Medium (the new primitive)

A long-lived endpoint while the app is open (own ALPN, e.g. peerspeak/friends/0), outside the room-session lifecycle, that:

• answers a ping only if remote_id() ∈ friends list;
• replies with online + (if in a gathering) a fresh member-issued ticket + the cosmetic room name;
• is governed by the invisible/normal/discoverable state. On app open (and a slow rate-limited refresh), ping each friend; render their status in the friends list. If a friend reports a gathering, show a small room-name tag + Join entry; clicking bootstraps off their ticket.

P5 — Recents + UI — Medium

Local recents list (cosmetic room tags). Friends-list UI with status dots ("available" / "appears offline"), the discoverable shortcut toggle, and the join-friend's-room entries from P4. Invisible/discoverable controls in Settings.

P6 — Opt-in discovery — Small

Wire the discoverable state to n0 DNS publish (default off, time-boxed). Lookup path for finding a discoverable friend whose saved address went stale.

P7 — Security review + 2-machine field test — Small–Medium

Surface: the friends-only listener (confirm non-friends are truly dropped pre-any state change; rate-limit pings), tickets from friends (validate defensively, no auto-join), the discovery publish (only when toggled, ideally auto-expiring). cargo audit (JSON store → no new deps expected). Field test on dopedart.

The connect flow (the user's scenario, end to end)

1. Friend X, at a coffee shop, opens peerspeak and starts a gathering labeled "HangOut."
2. You open peerspeak → it pings your friends → X answers (you have X's address; X is on a reachable relay) and reports "in HangOut, here's a ticket."
3. Your friends list shows X · HangOut [Join]. Click → bootstrap off X's ticket → you're in. Gossip refreshes everyone's saved addresses.
4. If X had moved to an unreachable network: X either flips on discoverable, or drops a fresh ticket in Signal — the manual floor. Once you connect once, X's new address auto-saves for next time.

Build order & effort

P1 (identity + spike) first — everything depends on it. Then P2 (friends) → P3 (tickets) → P4 (listener/presence) is the spine that makes the friends list live. P5 (recents/UI) alongside P4. P6 (discovery) and P7 (security/field test) last. Rough total: ~3–4 focused sessions. No always-on stranger-facing surface, no default beacon.

Open decisions (small, remaining)

1. Mutual friend-add handshake (accept/decline) vs a purely local add-by-id? The local list works alone; a handshake is polish + prevents one-sided "friends." Lean: start local, add handshake later if wanted.
2. Ticket bundle size for multi-bootstrap (1 = today; more = robust, longer).
3. Discovery time-box default (e.g. 30 min) vs sticky-until-off.

Cross-references

• Ticket type / multi-bootstrap seam: src/network/mod.rs:81, RoomState::join extra_bootstrap (A8).
• Identity mint point: src/core/mod.rs:421.
• Presence carries addr (auto-heal source): PeerState.addr, re-announce on NeighborUp src/network/gossip.rs:315,344.
• Reusable pixelpass code: ~/git/butter/pixelpass/src/common/{identity,friends}.rs (port the store + identity; the always-on control plane is NOT ported).

---

Earlier directions (superseded — kept for reference)

Heavyweight control-plane cut (decided against 2026-06-15). An always-on control-plane endpoint reachable by strangers + a presence beacon (n0 DNS) + porting pixelpass's full friends/control stack. Dropped: it needs a persistent publicly reachable identity, a stranger-facing listener (spam/DoS surface), and a default phone-home beacon — all of which the friends-only listener + opt-in discovery avoid. The user's key point: out-of-room delivery/presence is already done better by Signal/OS notifications, so delegate it.

Room-centric cut (folded into the friends-first model 2026-06-15). Durable named rooms (sha256(name) → topic), favorite-room persistence, empty-room reachability. Dropped because it fought the serverless reality (an empty room has no one to bootstrap from) and the user reframed rooms as ephemeral cosmetic labels — the durable thing is the friends list, not the room. The member-issued ticket and the cosmetic name-tag survive from this cut; the persistence machinery does not.