peerspeak/docs/contacts-plan.md

# Contacts list + room-invite notifications (W7) — plan / scope contract

**Status:** SCOPED, not started (assessment 2026-06-14 by the senior). This is the
scope contract; update it as phases land. Source: wishlist item **W7** in
`~/Documents/handoff-docs/Gemini/peerspeak/wishlist-handoff.md`.

## Goal

Save known peers and make joining their rooms frictionless:
- A **contacts list** — save known peers (by stable id + name) so you don't
  re-exchange tickets every time.
- A **notification drawer** where incoming **room invites** appear out-of-room.
- Each invite carries the room **ticket in a button**; clicking it **auto-fills
  the join-room text box** (one-click join — never copy/paste a ticket).

## The decisive architectural finding (read this first)

The wishlist says "port pixelpass's friends-list/notification system." The
*protocol* code ports nearly verbatim — **both projects are on the exact same
`iroh = "1.0.0-rc.0"`** — but the *integration* is genuinely new architecture for
PeerSpeak, because the two apps have opposite networking lifecycles:

- **pixelpass** runs a **persistent identity** + an **always-on control-plane
  endpoint** (bound at GUI start, online the whole time the app is open),
  separate from any video session. The friends system rides that.
- **PeerSpeak** has **no endpoint at all when not in a call**: `core/mod.rs:500`
  (the `Join` handler) builds the endpoint and tears it down on `Leave`, and
  `core/mod.rs:421` mints a **fresh random `SecretKey::generate()` every launch**,
  so a peer's `EndpointId` changes each run and nothing is listening while idle.

W7 fundamentally needs to reach a contact who is **not in a room** — which
PeerSpeak currently cannot do at all. **That gap, not the friends list, is the
real work.** Porting the proven protocol/store is ~60% of the effort (low risk);
the new 40% is the always-on control plane (Phase 1) and the all-new drawer/
contacts UI (Phase 3).

## Reusable prior art (pixelpass — `~/git/butter/pixelpass/`)

Field-verified + merged (`04bc0a8` + audit `6d0bf99`/`cfc4800`). Same stack, same
iroh version → API-compatible.

| pixelpass file | lines | reuse for PeerSpeak |
| --- | --- | --- |
| `src/common/identity.rs` | ~140 | **near-verbatim** — persistent ed25519 key, `load_or_create()`, atomic 0600 write. |
| `src/common/control.rs` | ~260 | **protocol reusable as-is** — one-message-per-connection JSON over a bi-stream, **authenticated sender via `conn.remote_id()`** (not spoofable), one-byte ACK = delivery+parse signal, `serve()` accept loop → `mpsc::Receiver<Inbound>`. `ControlMsg` variants `Hello`/`FriendRequest`/`FriendAccept`/`FriendDecline`/`ShareCode`. |
| `src/common/friends.rs` | ~330 | **near-verbatim** — `FriendStore`, mutual-consent `FriendState` (`PendingOutgoing`/`PendingIncoming`/`Accepted`), atomic write, keyed by stable `EndpointId`. |
| `src/common/alpn.rs` | — | `CONTROL_ALPN = b"pixelpass/ctrl/0"` pattern → mint `b"peerspeak/ctrl/0"`. |
| `src/gui/presence.rs` | ~299 | **reference, not copy** — service orchestration + online/presence indicators; PeerSpeak's iced UI differs, so adapt. |

## Locked design decisions

*(none yet — see "Open decisions" below; the user must answer the four before build)*

## Adaptations from pixelpass's model

- pixelpass's `ControlMsg::ShareCode { name, ticket }` (push a video share-code to a
  friend) maps directly onto PeerSpeak's need: a **room invite** carrying a
  `PeerSpeakTicket` (`src/network/mod.rs:81`). Likely rename to `RoomInvite`.
- Store contacts/identity as **JSON** (PeerSpeak already uses `serde_json`
  everywhere; pixelpass uses `toml`) to avoid adding the `toml` dependency — see
  Open decision #3.

## Phases

### Phase 0 — Persistent identity · Small (~1 session)
Port `identity.rs` → `~/.config/peerspeak/identity.key` (0600). Swap
`core/mod.rs:421` `SecretKey::generate()` for `load_or_create()`. Unit-testable
(hex round-trip tests come with it).
- **Side effect:** the gossip-signing key (security S2) becomes stable across
  launches → minor cross-room linkability. Note it (Open decision #2).

### Phase 1 — Always-on control plane · Large (the crux, ~1–2 sessions)
Stand up a **second, long-lived endpoint** on `peerspeak/ctrl/0`, online whenever
the app runs, owned by the core loop **outside** the `Join`/`Leave` session
lifecycle (today *all* networking lives inside `ActiveSession`).
- Port `control.rs` (protocol as-is). Wire its inbound `mpsc::Receiver<Inbound>`
  into the core→UI event flow (new `UiEvent` variants + `CoreCommand`s for
  send-request / accept / decline / invite).
- **Discovery:** the control endpoint likely needs **`presets::N0` (n0 DNS
  discovery)** to be reachable by bare id while idle, even if the call posture
  stays `RelayNoDiscovery`. This is Open decision #1.
- This is net-new long-lived networking; the bulk of W7's risk lives here.

### Phase 2 — Contacts store + friend handshake · Medium (~1 session)
Port `friends.rs` (as JSON). Wire `FriendRequest`/`Accept`/`Decline` through the
control plane and core. Persist `~/.config/peerspeak/contacts.json`. Pure store =
unit-testable. Implement the `RoomInvite` send/receive path (carry a
`PeerSpeakTicket`).

### Phase 3 — UI: contacts list + notification drawer + one-click join · Medium (~1 session)
All-new iced UI (PeerSpeak has **no drawer/notification panel today** — the only
"drawer" is the chat layout):
- **Contacts view** — add by id, see online/pending status, accept/decline.
- **Notification drawer** — top-right popup, **reuse the layout-switcher popup
  pattern** (`SelectRoomLayout` flow) in the always-visible top-right cluster;
  incoming invites listed with a one-click-join button.
- **One-click join** — the button routes the carried ticket into the join-room
  text-input state (validate, then pre-fill; do **not** auto-join).
- Online/presence indicators driven by `ControlMsg::Hello` refreshes.
- Cross-ref **W4 avatars**: show a contact's avatar (ties into `PeerState.avatar`).

### Phase 4 — Security review + 2-machine field test · Small–Medium
New untrusted surface:
- **Unsolicited control messages from arbitrary ids** = friend-request spam / DoS
  vector → need a cap / rate-limit (Open decision #4).
- **Invite-carried tickets** are untrusted even from a contact → validate
  defensively before pre-fill; never auto-join.
- Sender identity is **authenticated** (`remote_id()`) — inherited from
  pixelpass's design, good.
- `cargo audit` (no new deps expected if we store as JSON, not TOML).
- 2-machine field test on dopedart: add-contact both ways, request/accept,
  send a room invite out-of-room, one-click join.

## Open decisions (the user must answer before build)

1. **Discovery vs privacy (the big one).** Reaching an idle contact by stable id
   needs **n0 DNS discovery**, which conflicts with the privacy-minded
   `RelayNoDiscovery` default ([[user-security-preferences]] / telemetry stance).
   Proposed: run **only the control plane** on n0 discovery; keep the user's
   chosen posture for the call itself. Accept?
2. **Stable identity → stable gossip-signing key** across rooms (minor
   linkability). Acceptable?
3. **Dependency:** store contacts/identity as **JSON** (no new dep) rather than
   pixelpass's TOML. Confirm (default: JSON).
4. **Spam control:** cap / rate-limit unsolicited friend requests from the start?

## Effort summary

**Medium–High, ~4 focused sessions.** ~60% proven low-risk port (same iroh
version); ~40% new design — the always-on control endpoint (Phase 1) and the
all-new drawer/contacts UI (Phase 3).

## Cross-references
- Wishlist W7 (the request, with pixelpass-port pointer): `wishlist-handoff.md`.
- Notification system precedent (chimes): `src/notify.rs` + W6 (per-sound toggles,
  `7e75ae3`).
- Top-right popup pattern to reuse: the layout switcher (`SelectRoomLayout`).
- Ticket type to carry in invites: `PeerSpeakTicket` (`src/network/mod.rs:81`).