docs(p2p): a proposal for signaling that needs no one to carry values

[masa-koz]

A proposal for replacing the manual exchange with automatic signaling: docs/p2p_signaling_plan.md. Document only — no code changes.

The problem

Opening a P2P connection means a human carries four values between the peers, in two round trips. The last one only exists after the client has started connecting, so the exchange happens while the client sits in a retry loop. That structure already produced a failure we spent a day chasing — the manual work did not fit inside the 120-second deadline (p2p_mode_migration_plan.md §7 #21).

Only one of the four is a decision: whether this endpoint may reach this camera. The rest is mechanical.

The shape of the proposal

Keep the decision with a person, move it to enrollment where it happens once, and take the per-connection exchange to nothing.

Three ways in, because they serve different situations:

	enrollment	grant to others	unattended camera	shared secret
A same-account auto-grant	none	no	yes	none
B pairing code / QR	carry a code once	yes	yes	short-lived code
C approval prompt	press approve	yes	no	none

Default is A + B. For the common case — your own camera from your own phone — enrollment disappears entirely.

At runtime: the client lists what it may reach (GET /v1/peer/listeners), connects without a capability, and the proxy tells the listener to bind. Nothing is carried.

The piece that does not exist yet

There is no channel from the proxy to a listener that is waiting. The relay leg is opened per connection, so today there is nowhere to deliver "someone wants in".

The proposal puts an NDJSON event stream on the control plane (GET /v1/peer-listeners/{id}/events) — existing auth, existing transport, separate from the relay data path — and reconciles pending connections on every reconnect rather than keeping an event log. A stream that drops is normal; the reconciliation is what makes it correct.

Alternatives considered and why they lost are in §5.4.

Phasing

Ordered so that the manual steps disappear at phase 3, on polling, without waiting for the proxy work phase 5 needs. The event stream is a latency and load improvement, not a prerequisite.

What needs checking before any of this is built

Written from what this repository shows. The proxy is not in it, so §6 onward is a proposal, recorded as risk #1 rather than presented as settled. Two questions decide the shape:

1. Does the proxy spec already have something equivalent to a grant? (avoid building it twice)
2. Does Identity give the control plane the endpoint's owner? Method A depends entirely on this — if not, B becomes the default.

§13 leaves three design decisions open on purpose: where a grant belongs, what becomes of capability, and how multi-camera setups are presented.

🤖 Generated with Claude Code