1# Multi-viewer relay design and issue #81 decision23## Decision45Production viewer-to-viewer media routing is **deferred**. The Phase 2 wire shape is adopted now: every control-v2 media generation has a host-certified ephemeral Ed25519 key, every media object is signed over canonical coordinates and a SHA-256 payload digest, and every subscriber receives a short-lived host-signed capability bound to its exact Iroh endpoint. Direct-host v2 media uses this contract immediately, so later relay delivery does not require replacing the media trust model.67Deferral is deliberate rather than an undocumented follow-up. A production relay scheduler, alternate-publisher discovery, automatic failover, and relay UI are not enabled by this phase. Input, focus, authorization mutation, and host administration always terminate at Sigil.89## Spike result1011`scripts/relay-spike-proof.sh` models two Portal roles over a bounded virtual five-minute media horizon. Portal A receives each host-authored object and re-serves it through a four-object-capacity relay queue. Portal B verifies the host certificate, final MoQ group/object coordinates, object signature, and payload digest before accepting the existing media envelope. The spike does not sleep, so CPU percentages are normalized against the represented 300 seconds rather than wall-clock runtime.1213Release-mode result on the development macOS arm64 machine on 2026-07-23:1415| Measurement | Result |16|---|---:|17| Video target | 1280x800 at 60 fps |18| Audio target | Opus, 48 kHz stereo, 50 objects/s |19| Virtual duration | 300 s |20| Signed video objects | 18,000 |21| Signed audio objects | 15,000 |22| Relay queue high-water mark | 1 of 4 |23| Host upload through Portal A | 1,187,934,000 bytes |24| Direct host upload to two viewers | 2,375,868,000 bytes |25| Modeled host-upload saving | 50% |26| Ed25519 signing CPU / virtual realtime | 0.72% of one core |27| Ed25519 verification CPU / virtual realtime | 1.14% of one core |28| Local verification p95 | 160 us |29| Added network latency | Not measured by the virtual spike |3031The automated spike proves canonical re-serving, bounded memory, upload accounting, and cryptographic behavior. It is not evidence for Iroh direct-path or relay-fallback network latency. The manual Phase 2 gate must record two physical Portal paths before production mesh routing can be reconsidered.3233## Resource threshold and authentication mode3435Ed25519 is the only accepted v2 catalog authentication mode. It remains the default while exact-target release-mode evidence stays at or below all of these thresholds:3637- Host signing uses at most 5% of one core over the represented 1280x800/60 plus Opus workload.38- Portal verification uses at most 5% of one core over the same workload.39- Local authentication adds at most 1 ms p95 per object before codec validation.40- Signing overhead does not cause a source, MoQ, frontend, audio, or input queue to exceed its existing bound.4142A shared-MAC contingency may be evaluated only if an exact Bazzite host or supported Portal target crosses one of those thresholds. It must use a separately negotiated and diagnosed catalog mode. It must never be a silent downgrade, and its security consequence must be explicit: any viewer holding the shared key could forge relayed media. No shared-MAC mode is implemented or accepted now.4344## Connectivity model4546Sigil and every Portal retain normal Iroh endpoints. Iroh owns endpoint identity, encryption, direct-path discovery, NAT traversal, and relay fallback. A media relay is another authenticated Iroh delivery hop; it does not become Sigil and does not receive input or administration authority.4748Steps 1 and 2 ship today and carry every direct multi-viewer attachment. Steps493 through 5 are the relay extension and are not built.50511. Sigil admits Portal B over control v2 and issues a short-lived subscription capability for B's exact Iroh endpoint, media generation, authorization revision, tracks, expiry, nonce, and one relay hop. The accepted hello also states the authorization revision the capability was minted against, because a viewer cannot know its own enrollment revision; a hello whose capability disagrees with that advertisement is rejected before use.522. Sigil's catalog certifies the generation key and media authentication format.533. Sigil or a selected Portal A advertises an alternate publisher for a bounded group range. A production descriptor must identify the publisher endpoint, generation, track, group range, expiry, and host signature; raw peer identities must not enter the shared roster UI.544. Portal B connects to Portal A through Iroh and presents the capability. Portal A verifies the host signature and compares the authenticated downstream `remote_id()` with the capability subscriber.555. Portal B independently verifies the generation certificate and every object. Trust remains rooted in the enrolled Sigil host, not Portal A or the delivery path.5657Alternate-publisher descriptors are intentionally not emitted in Phase 2 because no production relay accepts them. The v2 catalog has an explicit version and authentication block, so a later strict extension can add a bounded alternate-publisher list without changing object bytes or treating an unknown mode as valid.5859## Trust boundaries6061- The persistent Sigil Iroh key signs only the domain-separated generation certificate and subscription capability.62- A fresh ephemeral generation key signs canonical media-object headers. The header binds host-certified generation, track, MoQ group, object index, media flags, payload length, and SHA-256 digest.63- The existing H.264 or Opus envelope remains the signed payload and is validated only after object authentication succeeds.64- Subscription capabilities authorize tracks, not focus or input. They are endpoint-bound, revision-bound, expiring, nonce-bearing, and permit exactly one relay hop.65- Capability tokens, host secrets, generation secrets, peer keys, and object payloads are excluded from diagnostics and logs.6667## Failure, failover, and abuse6869| Failure or abuse | Required behavior |70|---|---|71| Relay changes payload, coordinates, flags, or signature | Portal rejects the object before codec parsing and increments a local verification-failure counter. |72| Relay withholds a group or stalls an object | Existing bounded MoQ deadlines enter recovery; withheld bytes are never counted as trusted media. |73| Relay disappears | Portal discards relay-owned state and reconnects directly to Sigil using the same host-rooted object trust contract. |74| Wrong or expired subscriber capability | Relay or host rejects attachment before publishing media. |75| Wrong host or generation certificate | Portal rejects the catalog and terminates v2 media setup without falling back to unauthenticated v2 objects. |76| Replay from another track/group/object | Canonical coordinate comparison rejects it even when the payload and signature were once valid. |77| Slow or malicious relay | Its bounded queue may drop or disconnect that path; it cannot increase Sigil's producer history or another viewer's queue. |78| Alternate publisher lies about availability | Timeout leads to direct-host recovery; advertisements never make absent media trusted. |7980Direct fallback is a transport fallback, not an authentication fallback. An unknown catalog mode, absent v2 certificate, malformed capability, or failed object signature is terminal for that path.8182## Adoption triggers8384Re-open production mesh routing only when all of these are available:8586- Exact-target measurements show direct Sigil upload is sustained above 70% of available uplink with at least three viewers, or product UAT establishes a lower measured saturation threshold.87- Two physical Portals prove direct Iroh and relay-fallback paths, one-hop capability presentation, relay loss, and direct-host recovery with added end-to-end p95 below one 60 Hz frame period.88- The relay queue remains bounded under a slow downstream and cannot retain a playable history.89- Abuse tests cover tampering, withholding, wrong host/subscriber/generation/revision, expiry, replay, and relay churn.90- Portal UX can truthfully disclose `direct_host` versus `viewer_relay` without exposing endpoint keys or topology details.9192Until those triggers pass, the adopted authentication format keeps fan-out relay-ready while all production viewers subscribe directly to Sigil.9394## Reproduction9596```bash97./scripts/relay-spike-proof.sh \98 --video 1280x800@60 \99 --audio opus-48k-stereo \100 --duration-seconds 300101```102103The command must report Ed25519 mode, 50% modeled two-viewer host-upload savings, bounded relay queue depth, tamper/wrong-subscriber/expiry rejection, zero trusted withheld media, and successful direct-host verification after simulated relay loss.