peerspeak/docs/contacts-plan.md

# Durable rooms + frictionless invites (W7, redesigned) — plan / scope contract

**Status:** SCOPED, not started. **Redesigned 2026-06-15** (brainstorm with the
user) away from the original "port pixelpass's friends/control-plane" approach.
This is the scope contract; update it as phases land. Source: wishlist **W7** in
`~/Documents/handoff-docs/Gemini/peerspeak/wishlist-handoff.md`.

> **This doc supersedes the original W7 design.** The first cut (an always-on
> control-plane endpoint + persistent reachable identity + n0 DNS discovery) is
> recorded at the bottom under "Heavyweight path (decided against)" with the
> reasons. The redesign below delivers the same *user-visible* goals — save/reuse
> rooms, share an invite in one click — **without** an always-on listener, a
> presence beacon, or any phone-home, per [[user-security-preferences]] /
> [[user-telemetry-preference]].

## Goals (user-visible)

1. **Reuse a room** without re-exchanging a fresh ticket every time.
2. **Share an invite in one click** through tools people already trust (Signal,
   Telegram, email, SMS) — peerspeak makes the invite trivially shareable and
   clickable; it does NOT try to be a messenger.
3. **Optionally** bookmark favorite rooms and see how busy one is before joining.

Explicitly **out of scope** (dropped from the old W7, with intent): in-app
"who's online right now" presence, a bespoke in-app invite inbox/drawer, and any
mechanism that requires peerspeak to be reachable while idle. Those are exactly
the parts that cost the security/privacy budget, and the user's position is that
Signal/OS notifications already do them better.

## The reframe that makes this cheap (the spine)

**Established facts (verified in-code this session):**
- A ticket is `PeerSpeakTicket { host_addr: EndpointAddr, topic_id: [u8;32] }`
  (`src/network/mod.rs:81`). It carries **one** bootstrap address (the creator's)
  plus the room's gossip topic id.
- The room's durable identity is the **`topic_id`** — every member is subscribed
  to it. The host address is just *one door* into that topic.
- `RoomState::join` already accepts **`extra_bootstrap: Vec<EndpointAddr>`** (added
  by the A8 fix) — multiple dial targets are already supported.
- Identity (`SecretKey`) is minted **once per process** (`src/core/mod.rs:421`),
  so a node id is stable for a running session but **regenerated on every fresh
  launch**. Retained peers (A8 `known_peers`) live **in memory only**.
- Consequence (the dead-end this redesign fixes): a ticket's lifespan equals **the
  creator's address staying live**, NOT room occupancy. Host goes offline → the
  ticket can't bootstrap anyone, even if the room is full, because it only ever
  carried the host's address.

**The spine — member-issued, multi-bootstrap tickets.** Today only the founder
mints a ticket. Instead, let **any current member** mint a fresh, fully valid
ticket on demand, stamped with **their own live address + the room's existing
`topic_id`** (both already in hand inside a live session). Every member is a door.

This alone makes **rooms outlive their creator**: a room is reachable as long as
*anyone* inside can hand out a ticket. Extended to carry *several* present members
as bootstrap candidates (the `Vec` is already there), the room loses its single
point of failure — a newcomer dials all listed members and connects to whoever's
up.

**Cost: almost nothing.** The ticket type and the multi-bootstrap join path
already exist; a live member already holds the `topic_id` and `endpoint.addr()`.
"Export this room as an invite" is a UI button + a `CoreCommand` that reads
existing session state and builds a ticket. No new networking, no new identity, no
discovery. It stays inside today's trust model (a ticket already grants a full
join; members can already forward the founder's ticket — this just hands out a
*fresher* pointer).

## Layers (each optional, stack as desired)

### Layer 0 — Member-issued / multi-bootstrap tickets — **the spine, Small**
As above. Delivers "rooms outlive their creator" and redundant bootstrap with no
identity/discovery changes.

### Layer 1 — One-click invite sharing (deep links + QR + file) — **Small–Medium**
Make a ticket trivially shareable through existing channels:
- **`peerspeak://join/<ticket>` URI scheme.** Register via a `.desktop` file with
  `MimeType=x-scheme-handler/peerspeak;` + `xdg-mime default` (Plasma + bare X11
  both honor it). Paste the link into Signal/email; the recipient clicks → peerspeak
  opens with a **"Join room? [preview] [Join] [Cancel]"** prompt. **Never
  auto-join** (the one real new surface; same defensive ticket validation we
  already do).
- **QR code** of the same URI (pure-Rust `qrcode`, no network — vet the crate) for
  in-person / screen-to-phone handoff.
- **`.peerspeak` invite file** + the same MimeType association (double-click →
  open + prompt). Sendable over any transport, incl. the user's `croc`.
- **"Invite via…"** buttons: `xdg-open "mailto:?body=peerspeak://join/<ticket>"`.

### Layer 2 — Persistent identity — **Small** (enables save-and-return)
Port pixelpass's `identity.rs` (~140 lines, near-verbatim) → a stable key file
(JSON, not TOML — see decisions); swap `core/mod.rs:421` `generate()` for
`load_or_create()`. **Only needed to make a *saved* member-address survive that
member's restart** (i.e. rejoin a favorite room tomorrow). Layer 0 works without
it. Side effect: the gossip-signing key (S2) becomes stable across launches →
minor cross-room linkability — note it.

### Layer 3 — Name-derived rooms — **Small–Medium** (memorable identity)
`hash(room_name [+ passphrase]) → topic_id`, so the room's *identity* is a
memorable shared word instead of a 32-byte blob, host-independent. Note the
entropy reality (established this session): a name can carry the **topic** (it
*derives* it) but **cannot contain the host key/address** — that's ~32 bytes of
irreducible random data. So a named room still needs Layer 0 for the *address*
half (who to bootstrap from). Name = identity; member-ticket = reachability.
Security: a guessable name = joinable by anyone → treat the name as a secret or
require a passphrase in the hash.

### Layer 4 — Favorite rooms (bookmarks) — **Small**
Persist a list of saved rooms = `{ friendly_name, topic_id, last-known member
addresses }`. On "rejoin," dial the saved member addresses as `extra_bootstrap`;
if any one is online, gossip pulls you back into the rest. Refresh the saved
addresses every time you're in the room. Reliable only in proportion to Layer 2
(stable member ids) + how many addresses you retain. Dials **only on explicit
rejoin** — no always-on endpoint, no beacon.

### Layer 5 — Silent occupancy peek — **Small** (optional, flagged)
"How busy is this room?" without fully joining. Mechanism (verified in-code): a
background joiner enters the gossip mesh but **never broadcasts its own
`Announce`**, so it doesn't appear in anyone's roster (roster is Announce-driven,
`gossip.rs:315`); existing members re-announce on `NeighborUp` (`gossip.rs:344`),
so the peeker collects the roster passively, reduces it to `peers.len()`, and
leaves.
- **Privacy contract (must hold):** receives identities transiently (unavoidable —
  the count *is* the roster), but **retains only the integer count**; never
  displays/logs/persists a name or address. One-liner in code: "receives
  identities transiently, retains only the count."
- **Honest caveats:** "invisible" is UI-level, not wire-level — members' gossip
  logs a `NeighborUp` (acceptable per user). Must linger briefly or it undercounts.
- **Consent note:** shipping this means anyone with a ticket can count a room
  without occupants' knowledge — a deliberate break from today's symmetric model
  (to see in, you announce yourself). Inside the app's trust boundary (a ticket
  already grants a full join), but name it as a conscious choice.

## Recommended build order

**Layer 0 first** (the spine; unblocks "rooms outlive their creator" immediately),
then **Layer 1** (the one-click-share headline). Layers 2–5 are independent
add-ons to pick up by appetite. The serverless persistent-room story = **0 + 2 + 3
+ 4**. The "polished invite" UX = always keep a fresh, multi-bootstrap "Invite to
this room" ticket ready to copy while in a session.

## Open decisions (user)

1. **Persistent identity (Layer 2):** adopt it? It's the gate for save-and-return
   rooms, and it makes the gossip-signing key stable across launches (minor
   linkability). (Layer 0/1 don't need it.)
2. **Multi-bootstrap ticket size:** how many present members to bundle as bootstrap
   (1 = today's size; more = more robust but a longer ticket). Also: tighten the
   ticket encoding (drop JSON/base64 fat, index the relay URL) — lossless, roughly
   halves the string; worth doing alongside.
3. **Storage format:** JSON (no new dep; matches `serde_json` everywhere) vs
   pixelpass's TOML. Default: JSON.
4. **Ship Layer 5 (silent peek)** at all, given the consent tradeoff? If yes,
   confirm the "retain only the count" contract.
5. **Named rooms (Layer 3):** require a passphrase in the hash, or treat the bare
   name as the secret?

## Effort summary

Spine + headline (Layers 0 + 1): **Small–Medium, ~1–2 sessions.** Full serverless
persistent-room story (+ 2, 3, 4): **+1–2 sessions.** Dramatically lighter than the
heavyweight path, and it adds **no always-on surface, no discovery beacon, no new
network-reachable listener.**

## Cross-references
- Ticket type / multi-bootstrap join seam: `src/network/mod.rs:81`, `RoomState::join`
  `extra_bootstrap` (A8).
- Identity mint point to make persistent: `src/core/mod.rs:421`.
- Roster = Announce-driven; re-announce on NeighborUp: `src/network/gossip.rs:315,344`.
- Notification precedent: `src/notify.rs` + W6 (`7e75ae3`).
- Reusable pixelpass code (Layer 2 identity port): `~/git/butter/pixelpass/src/common/identity.rs`.

---

## Heavyweight path (decided against 2026-06-15 — kept for reference)

The original W7 cut: a **persistent identity** + an **always-on control-plane
endpoint** (`peerspeak/ctrl/0`, online whenever the app runs, separate from any
session) + **n0 DNS discovery** to dial idle contacts by stable id, porting
pixelpass's `identity.rs`/`control.rs`/`friends.rs` (same `iroh = 1.0.0-rc.0`, so
the protocol ports near-verbatim). It would have added an in-app contacts list,
friend-request handshake, a notification drawer, and out-of-room invite delivery.

**Why dropped:** it requires three things the user specifically wants to avoid —
a persistent reachable identity (cross-room linkable), an always-on listening
endpoint (standing spam/DoS surface), and an n0 DNS **presence beacon**
(phone-home). The user's key observation: out-of-room **delivery + presence is
already solved, better, by Signal/Telegram/OS notifications** (which also work
when peerspeak is closed — the bespoke drawer can't). So peerspeak should make the
invite trivially shareable and **delegate identity/presence/delivery** to those
tools, which is what the redesign above does. The pixelpass `identity.rs` port
survives as the optional Layer 2 only.